Skip to content
OpenClaw Docs

CLI 安裝參考

本頁是 openclaw onboard 的完整參考。 若需簡短指南，請參閱 Onboarding (CLI)。

精靈的功能

Section titled “精靈的功能”

本機模式（預設）會引導您完成：

  • 模型與驗證設定（OpenAI Code 訂閱 OAuth、Anthropic Claude CLI 或 API 金鑰，以及 MiniMax、GLM、Ollama、Moonshot、StepFun 和 AI Gateway 選項）
  • 工作區位置與啟動檔案
  • Gateway 設定（連接埠、綁定、驗證、Tailscale）
  • 頻道和提供者（Telegram、WhatsApp、Discord、Google Chat、Mattermost、Signal、iMessage 及其他內建的頻道外掛程式）
  • Daemon 安裝（LaunchAgent、systemd 使用者單元，或原生的 Windows 排程任務，並備有啟動資料夾後援）
  • 健康檢查
  • 技能設定

遠端模式會將此機器設定為連線到其他地方的 Gateway。 它不會在遠端主機上安裝或修改任何內容。

本機流程詳情

Section titled “本機流程詳情”

  1. Existing config detection

    • 如果 ~/.openclaw/openclaw.json 存在，請選擇 Keep（保留）、Modify（修改）或 Reset（重設）。
    • 重新執行精靈不會清除任何內容，除非您明確選擇 Reset（或傳遞 --reset）。
    • CLI --reset 預設為 config+creds+sessions；請使用 --reset-scope full 一併移除工作區。
    • 如果組態無效或包含舊版金鑰，精靈會停止並要求您在繼續之前執行 openclaw doctor。
    • 重設使用 trash 並提供範圍選項：
      • 僅組態
      • 組態 + 憑證 + 會話
      • 完整重設（也會移除工作區）

  2. Model and auth

  3. Workspace

    • 預設 ~/.openclaw/workspace（可設定）。
    • 植入首次執行啟動程序所需的工作區檔案。
    • 工作區佈局：Agent workspace。

  4. Gateway

    • 提示輸入連接埠、綁定、驗證模式和 Tailscale 暴露設定。
    • 建議：即使對於 loopback，也請保持 token 驗證已啟用，以便本地 WS 用戶端必須進行驗證。
    • 在 token 模式下，互動式設定提供：
      • 產生/儲存明文 token（預設）
      • 使用 SecretRef（選用）
    • 在密碼模式下，互動式設定也支援明文或 SecretRef 儲存。
    • 非互動式 token SecretRef 路徑：`—gateway-token-ref-env

    。 - 需要 onboarding 程序環境中的非空環境變數。 - 不能與 —gateway-token` 結合使用。 - 僅在您完全信任每個本機程序時才停用驗證。 - 非 loopback 綁定仍需要驗證。

  5. 頻道

    • WhatsApp：選用性的 QR 登入
    • Telegram：bot token
    • Discord：bot token
    • Google Chat：服務帳號 JSON + webhook audience
    • Mattermost：bot token + 基礎 URL
    • Signal：選用性 signal-cli 安裝 + 帳號設定
    • iMessage：imsg CLI 路徑 + 訊息資料庫存取；當 Gateway 在 Mac 以外執行時，請使用 SSH 包裝器
    • DM 安全性：預設為配對。第一則 DM 會傳送代碼；透過 `openclaw pairing approve

    ` 核准或使用允許清單。

遠端模式詳細資訊

Section titled “遠端模式詳細資訊”

遠端模式會將此機器設定為連線到其他地方的閘道。

您的設定：

  • 遠端 gateway URL (ws://...)
  • 權杖（如果遠端閘道需要驗證）（建議）

驗證與模型選項

Section titled “驗證與模型選項”
Anthropic API 金鑰

如果存在則使用 ANTHROPIC_API_KEY，否則提示輸入金鑰，然後將其儲存供 daemon 使用。

OpenAI Code 訂閱 (OAuth)

瀏覽器流程；貼上 code#state。

當模型未設定或已經是 OpenAI 系列時，透過 Codex 執行時將 agents.defaults.model 設定為 openai/gpt-5.5。

OpenAI Code 訂閱 (裝置配對)

具有短期裝置代碼的瀏覽器配對流程。

當模型未設定或已經是 OpenAI 系列時，透過 Codex 執行時將 agents.defaults.model 設定為 openai/gpt-5.5。

OpenAI API 金鑰

如果存在則使用 OPENAI_API_KEY，否則提示輸入金鑰，然後將憑證儲存在 auth profiles 中。

當模型未設定、openai/* 或 openai-codex/* 時，將 agents.defaults.model 設定為 openai/gpt-5.5。

xAI (Grok) OAuth

符合資格的 SuperGrok 或 X Premium 帳戶的瀏覽器登入。這是 大多數使用者推薦的 xAI 路徑。OpenClaw 將結果 auth profile 儲存給 Grok 模型、x_search 和 code_execution。

xAI (Grok) 裝置代碼

適合遠端的瀏覽器登入，使用短代碼代替 localhost 回呼。從 SSH、Docker 或 VPS 主機使用此功能。

xAI (Grok) API 金鑰

提示輸入 XAI_API_KEY 並將 xAI 設定為模型提供者。當您想要 使用 xAI Console API 金鑰而不是訂閱 OAuth 時使用此選項。

OpenCode

提示輸入 OPENCODE_API_KEY (或 OPENCODE_ZEN_API_KEY) 並讓您選擇 Zen 或 Go 目錄。 設定 URL: opencode.ai/auth。

API key (generic)

幫您儲存金鑰。

Vercel AI Gateway

提示輸入 AI_GATEWAY_API_KEY。 更多詳情: Vercel AI Gateway。

Cloudflare AI Gateway

提示輸入帳戶 ID、Gateway ID 和 CLOUDFLARE_AI_GATEWAY_API_KEY。 更多詳情: Cloudflare AI Gateway。

MiniMax

配置會自動寫入。託管預設值為 MiniMax-M2.7；API 金鑰設定使用 minimax/...，OAuth 設定使用 minimax-portal/...。 更多詳情: MiniMax。

StepFun

針對中國或全球端點上的 StepFun 標準版或 Step Plan 自動寫入配置。 標準版目前包含 step-3.5-flash，而 Step Plan 也包含 step-3.5-flash-2603。 更多詳情: StepFun。

Synthetic (Anthropic-compatible)

提示輸入 SYNTHETIC_API_KEY。 更多詳情: Synthetic。

Ollama (Cloud and local open models)

首先提示輸入 Cloud + Local、Cloud only 或 Local only。 Cloud only 使用 OLLAMA_API_KEY 搭配 https://ollama.com。 主機支援模式會提示輸入基礎 URL (預設 http://127.0.0.1:11434)，探索可用的模型，並建議預設值。 Cloud + Local 也會檢查該 Ollama 主機是否已登入以使用雲端存取。 更多詳細資訊：Ollama。

Moonshot and Kimi Coding

Moonshot (Kimi K2) 和 Kimi Coding 設定會自動寫入。 更多詳細資訊：Moonshot AI (Kimi + Kimi Coding)。

Custom provider

可與 OpenAI 相容和 Anthropic 相容的端點搭配使用。

互動式上架支援與其他提供者 API 金鑰流程相同的 API 金鑰儲存選項：

  • 立即貼上 API 金鑰 (純文字)
  • 使用秘密參照 (env ref 或已設定的提供者參照，並包含預檢驗證)

非互動式標誌：

  • --auth-choice custom-api-key
  • --custom-base-url
  • --custom-model-id
  • --custom-api-key (選用；若未提供則回退至 CUSTOM_API_KEY)
  • --custom-provider-id (選用)
  • `—custom-compatibility

(選用；預設為openai) - —custom-image-input/—custom-text-input` (選用；覆寫推斷的模型輸入能力)

Skip

保持未設定驗證狀態。

模型行為：

  • 從偵測到的選項中挑選預設模型，或手動輸入提供者和模型。
  • 自訂提供者上架會推斷常見模型 ID 的圖片支援，並僅在模型名稱未知時進行詢問。
  • 當上線是從提供商身份驗證選擇開始時，模型選擇器會自動優先選擇該提供商。對於 Volcengine 和 BytePlus，相同的優先順序也會符合其編碼計畫變體（volcengine-plan/*、byteplus-plan/*）。
  • 如果該優先提供商的過濾結果為空，選擇器會改為回退到完整目錄，而不顯示無模型。
  • 精靈會執行模型檢查，如果設定的模型未知或缺少身份驗證，則會發出警告。

憑證與設定檔路徑：

  • 身份驗證設定檔（API 金鑰 + OAuth）：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • 舊版 OAuth 匯入：~/.openclaw/credentials/oauth.json

憑證儲存模式：

  • 預設的上線行為會將 API 金鑰以純文字值的形式保存在身份驗證設定檔中。
  • --secret-input-mode ref 會啟用參考模式，而非純文字金鑰儲存。在互動式設定中，您可以選擇：
    • 環境變數參考（例如 keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }）
    • 設定的提供商參考（file 或 exec），搭配提供商別名 + ID
  • 互動式參考模式會在儲存前執行快速預檢驗證。
    • 環境變數參考：會驗證變數名稱 + 目前上線環境中的非空值。
    • 提供商參考：會驗證提供商設定並解析要求的 ID。
    • 如果預檢失敗，上線程序會顯示錯誤並讓您重試。
  • 在非互動模式下，--secret-input-mode ref 僅支援環境變數後端。
    • 在上線程序環境中設定提供商環境變數。
    • 內嵌金鑰旗標（例如 --openai-api-key）要求必須設定該環境變數；否則上線程序會快速失敗。
    • 對於自訂提供商，非互動式 ref 模式會將 models.providers.<id>.apiKey 儲存為 { source: "env", provider: "default", id: "CUSTOM_API_KEY" }。
    • 在該自訂提供商的情況下，--custom-api-key 要求必須設定 CUSTOM_API_KEY；否則上線程序會快速失敗。
  • 閘道身份驗證憑證在互動式設定中支援純文字和 SecretRef 選項：
    • 權杖模式：產生/儲存純文字權杖（預設）或 使用 SecretRef。
    • 密碼模式：純文字或 SecretRef。
  • 非互動式權杖 SecretRef 路徑：--gateway-token-ref-env <ENV_VAR>。
  • 現有的明文設定繼續保持不變並正常運作。

輸出與內部機制

Section titled “輸出與內部機制”

~/.openclaw/openclaw.json 中的典型欄位：

  • agents.defaults.workspace
  • 當傳遞 --skip-bootstrap 時的 agents.defaults.skipBootstrap
  • agents.defaults.model / models.providers（若選擇 Minimax）
  • tools.profile（本地啟用若未設定則預設為 "coding"；現有的明確值將被保留）
  • gateway.*（模式、綁定、驗證、tailscale）
  • session.dmScope（本地啟用若未設定則將此預設為 per-channel-peer；現有的明確值將被保留）
  • channels.telegram.botToken、channels.discord.token、channels.matrix.*、channels.signal.*、channels.imessage.*
  • 當您在提示期間選擇加入時的頻道允許清單（Slack、Discord、Matrix、Microsoft Teams）（名稱會盡可能解析為 ID）
  • skills.install.nodeManager
    • setup --node-manager 標誌接受 npm、pnpm 或 bun。
    • 手動設定之後仍可以設定 skills.install.nodeManager: "yarn"。
  • wizard.lastRunAt
  • wizard.lastRunVersion
  • wizard.lastRunCommit
  • wizard.lastRunCommand
  • wizard.lastRunMode

openclaw agents add 會寫入 agents.list[] 和可選的 bindings。

WhatsApp 憑證位於 ~/.openclaw/credentials/whatsapp/<accountId>/ 之下。 會話儲存在 ~/.openclaw/agents/<agentId>/sessions/ 之下。

Gateway 精靈 RPC：

  • wizard.start
  • wizard.next
  • wizard.cancel
  • wizard.status

客戶端（macOS 應用程式和控制 UI）可以呈現步驟，而無需重新實現入邏輯。

信號設置行為：

  • 下載適當的版本資產
  • 將其儲存在 ~/.openclaw/tools/signal-cli/<version>/ 下
  • 在設定中寫入 channels.signal.cliPath
  • JVM 構建需要 Java 21
  • 如果可用，則使用原生構建
  • Windows 使用 WSL2，並在 WSL 內遵循 Linux signal-cli 流程

相關文件

Section titled “相關文件”