安裝引導精靈參考

這是 openclaw onboard CLI 精靈的完整參考。 概略的概覽參見 安裝引導精靈。

流程詳情（本地模式）

步驟 1：既有設定偵測

  • 若 ~/.openclaw/openclaw.json 存在，選擇保留 / 修改 / 重置。
  • 重新執行精靈不會清除任何東西，除非你明確選擇重置（或傳入 --reset）。
  • CLI --reset 預設為 config+creds+sessions；使用 --reset-scope full 也移除工作區。
  • 若設定無效或包含舊有鍵，精靈會停止並要求你先執行 openclaw doctor。
  • 重置使用 trash（從不 rm）並提供範圍：
    • 僅設定
    • 設定 + 憑證 + session
    • 完全重置（也移除工作區）

步驟 2：模型/驗證

  • Anthropic API 金鑰：若存在則使用 ANTHROPIC_API_KEY，否則提示輸入金鑰，然後為 daemon 儲存。
  • Anthropic OAuth（Claude Code CLI）：macOS 上精靈檢查 Keychain 項目「Claude Code-credentials」（選擇「Always Allow」以免 launchd 啟動時阻塞）；Linux/Windows 上若存在則重用 ~/.claude/.credentials.json。
  • Anthropic token（貼上 setup-token）：在任何機器上執行 claude setup-token，然後貼上 token（可命名；留空 = 預設）。
  • OpenAI Code（Codex）訂閱（Codex CLI）：若 ~/.codex/auth.json 存在，精靈可重用。
  • OpenAI Code（Codex）訂閱（OAuth）：瀏覽器流程；貼上 code#state。
    • 模型未設定或為 openai/* 時，設定 agents.defaults.model 為 openai-codex/gpt-5.2。
  • OpenAI API 金鑰：若存在則使用 OPENAI_API_KEY，否則提示輸入金鑰，儲存至 auth profiles。
  • xAI（Grok）API 金鑰：提示 XAI_API_KEY 並設定 xAI 作為模型供應商。
  • OpenCode：提示 OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY，在 https://opencode.ai/auth 取得），讓你選擇 Zen 或 Go 目錄。
  • Ollama：提示 Ollama base URL，提供雲端 + 本地或僅本地模式，探索可用模型，需要時自動拉取選定的本地模型。
  • 更多細節：Ollama
  • API 金鑰：為你儲存金鑰。
  • Vercel AI Gateway（多模型代理）：提示 AI_GATEWAY_API_KEY。
  • 更多細節：Vercel AI Gateway
  • Cloudflare AI Gateway：提示 Account ID、Gateway ID 和 CLOUDFLARE_AI_GATEWAY_API_KEY。
  • 更多細節：Cloudflare AI Gateway
  • MiniMax M2.5：設定自動寫入。
  • 更多細節：MiniMax
  • Synthetic（Anthropic 相容）：提示 SYNTHETIC_API_KEY。
  • 更多細節：Synthetic
  • Moonshot（Kimi K2）：設定自動寫入。
  • Kimi Coding：設定自動寫入。
  • 更多細節：Moonshot AI（Kimi + Kimi Coding）
  • 跳過：尚未設定驗證。
  • 從偵測到的選項中選擇預設模型（或手動輸入 provider/model）。為最佳品質和較低的 prompt 注入風險，選擇你供應商堆疊中可用的最強最新世代模型。
  • 精靈執行模型檢查，若設定的模型未知或缺少驗證則警告。
  • API 金鑰儲存模式預設為純文字 auth-profile 值。使用 --secret-input-mode ref 改為儲存環境變數支援的 ref（例如 keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }）。
  • OAuth 憑證位於 ~/.openclaw/credentials/oauth.json；auth profiles 位於 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json（API 金鑰 + OAuth）。
  • 更多細節：/concepts/oauth

注意： Headless/伺服器提示：在有瀏覽器的機器上完成 OAuth，然後將 ~/.openclaw/credentials/oauth.json（或 $OPENCLAW_STATE_DIR/credentials/oauth.json）複製到 gateway 主機。

步驟 3：工作區

  • 預設 ~/.openclaw/workspace（可設定）。
  • 填入代理啟動儀式所需的工作區檔案。
  • 完整工作區佈局 + 備份指南：代理工作區

步驟 4：Gateway

  • 埠號、綁定、驗證模式、tailscale 曝光。
  • 驗證建議：即使迴路也保持 Token，讓本地 WS 用戶端必須驗證。
  • Token 模式下互動式安裝引導提供：
    • 產生/儲存純文字 token（預設）
    • 使用 SecretRef（選擇加入）
  • 密碼模式下互動式安裝引導也支援純文字或 SecretRef 儲存。
  • 非互動式 token SecretRef 路徑：--gateway-token-ref-env <ENV_VAR>。
  • 僅在你完全信任每個本地行程時才停用驗證。
  • 非迴路綁定仍需要驗證。

步驟 5：頻道

  • WhatsApp：選用 QR 登入。
  • Telegram：bot token。
  • Discord：bot token。
  • Google Chat：service account JSON + webhook audience。
  • Mattermost（外掛）：bot token + base URL。
  • Signal：選用 signal-cli 安裝 + 帳號設定。
  • BlueBubbles：iMessage 推薦；伺服器 URL + 密碼 + webhook。
  • iMessage：舊版 imsg CLI 路徑 + DB 存取。
  • DM 安全：預設為配對。首次 DM 傳送驗證碼；透過 openclaw pairing approve <channel> <code> 核准或使用白名單。

步驟 6：網頁搜尋

  • 選擇供應商：Perplexity、Brave、Gemini、Grok 或 Kimi（或跳過）。
  • 貼上 API 金鑰（QuickStart 自動偵測環境變數或既有設定中的金鑰）。
  • 以 --skip-search 跳過。
  • 稍後設定：openclaw configure --section web。

步驟 7：Daemon 安裝

  • macOS：LaunchAgent
  • Linux（和透過 WSL2 的 Windows）：systemd user unit
  • 執行時選擇： Node（推薦；WhatsApp/Telegram 需要）。Bun 不推薦。

步驟 8：健康檢查

  • 啟動 Gateway（若需要）並執行 openclaw health。
  • 提示：openclaw status --deep 在狀態輸出中加入 gateway 健康探測（需要可達的 gateway）。

步驟 9：技能（建議）

  • 讀取可用技能並檢查需求。
  • 讓你選擇節點管理器：npm / pnpm（bun 不推薦）。
  • 安裝選用依賴（macOS 上部分使用 Homebrew）。

步驟 10：完成

  • 摘要 + 後續步驟，包含 iOS/Android/macOS 應用的額外功能。

注意： 若未偵測到 GUI，精靈印出 SSH 埠轉發指示供控制 UI 使用，而非開啟瀏覽器。 若控制 UI 資產遺失，精靈嘗試建構；回退為 pnpm ui:build（自動安裝 UI 依賴）。

非互動模式

使用 --non-interactive 以自動化或腳本化安裝引導：

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback \
  --install-daemon \
  --daemon-runtime node \
  --skip-skills

加入 --json 取得機器可讀的摘要。

注意： --json 不代表非互動模式。腳本使用 --non-interactive（和 --workspace）。

供應商專屬的指令範例位於 CLI 自動化。 本參考頁面供旗標語義和步驟排序使用。

新增代理（非互動）

openclaw agents add work \
  --workspace ~/.openclaw/workspace-work \
  --model openai/gpt-5.2 \
  --bind whatsapp:biz \
  --non-interactive \
  --json

Gateway 精靈 RPC

Gateway 透過 RPC 公開精靈流程（wizard.start、wizard.next、wizard.cancel、wizard.status）。用戶端（macOS 應用、控制 UI）可呈現步驟而不需重新實作安裝引導邏輯。

精靈寫入的內容

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

  • agents.defaults.workspace
  • agents.defaults.model / models.providers（若選擇 Minimax）
  • tools.profile（本地安裝引導在未設定時預設為 "coding"；既有的明確值保留）
  • gateway.*（mode、bind、auth、tailscale）
  • session.dmScope
  • channels.telegram.botToken、channels.discord.token、channels.signal.*、channels.imessage.*
  • 頻道白名單（Slack/Discord/Matrix/Microsoft Teams）在你於提示中選擇加入時（名稱可能解析為 ID）。
  • skills.install.nodeManager
  • wizard.lastRunAt
  • wizard.lastRunVersion
  • wizard.lastRunCommit
  • wizard.lastRunCommand
  • wizard.lastRunMode

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

WhatsApp 憑證放在 ~/.openclaw/credentials/whatsapp/<accountId>/。 Session 儲存在 ~/.openclaw/agents/<agentId>/sessions/。

部分頻道以外掛形式提供。安裝引導期間選擇時，精靈會提示安裝它（npm 或本地路徑）才能設定。

相關文件

arrow_back
上一頁
USER
下一頁
Token Use
arrow_forward