CLI Onboarding 參考

這個頁面是 openclaw onboard 的完整參考。 簡短的指南請參考 Onboarding 精靈（CLI）。

精靈做了什麼

本地模式（預設）引導你完成：

  • 模型與驗證設定（OpenAI Code subscription OAuth、Anthropic API key 或 setup token，加上 MiniMax、GLM、Ollama、Moonshot 和 AI Gateway 選項）
  • 工作區位置和 bootstrap 檔案
  • Gateway 設定（埠號、綁定、驗證、tailscale）
  • 頻道和提供者（Telegram、WhatsApp、Discord、Google Chat、Mattermost 外掛、Signal）
  • Daemon 安裝（LaunchAgent 或 systemd user unit）
  • 健康檢查
  • Skills 設定

遠端模式設定這台機器連線到其他地方的 gateway。 它不會在遠端主機上安裝或修改任何東西。

本地流程詳情

步驟一：偵測現有設定

- 如果 `~/.openclaw/openclaw.json` 存在，可選擇保留、修改或重置。
- 重新執行精靈不會清除任何東西，除非你明確選擇重置（或傳入 `--reset`）。
- CLI `--reset` 預設為 `config+creds+sessions`；使用 `--reset-scope full` 來一併移除工作區。
- 如果設定無效或含有舊版 key，精靈會停下來要求你先執行 `openclaw doctor` 再繼續。
- 重置使用 `trash`，提供以下範圍：
  - 僅設定
  - 設定 + 憑證 + sessions
  - 完整重置（同時移除工作區）

步驟二：模型與驗證

- 完整選項矩陣在 [驗證與模型選項](#驗證與模型選項)。

步驟三：工作區

- 預設 `~/.openclaw/workspace`（可設定）。
- 產生首次執行 bootstrap 儀式所需的工作區檔案。
- 工作區配置：[Agent 工作區](/docs/concepts/agent-workspace)。

步驟四：Gateway

- 提示埠號、綁定、驗證模式和 tailscale 暴露。
- 建議：即使是 loopback 也保持 token 驗證啟用，讓本地 WS 客戶端必須驗證。
- Token 模式下，互動 onboarding 提供：
  - **產生/儲存明文 token**（預設）
  - **使用 SecretRef**（選擇加入）
- Password 模式下，互動 onboarding 也支援明文或 SecretRef 儲存。
- 非互動 token SecretRef 路徑：`--gateway-token-ref-env <ENV_VAR>`。
  - 需要 onboarding 行程環境中有非空的環境變數。
  - 不能與 `--gateway-token` 併用。
- 只在你完全信任每個本地行程時才停用驗證。
- 非 loopback 綁定仍然需要驗證。

步驟五：頻道

- [WhatsApp](/docs/channels/whatsapp)：選用 QR 登入
- [Telegram](/docs/channels/telegram)：bot token
- [Discord](/docs/channels/discord)：bot token
- [Google Chat](/docs/channels/googlechat)：service account JSON + webhook audience
- [Mattermost](/docs/channels/mattermost) 外掛：bot token + base URL
- [Signal](/docs/channels/signal)：選用 `signal-cli` 安裝 + 帳號設定
- [BlueBubbles](/docs/channels/bluebubbles)：建議用於 iMessage；server URL + password + webhook
- [iMessage](/docs/channels/imessage)：舊版 `imsg` CLI 路徑 + DB 存取
- DM 安全：預設為配對。第一個 DM 會發送一組代碼；透過
  `openclaw pairing approve <channel> <code>` 核准或使用白名單。

步驟六：Daemon 安裝

- macOS：LaunchAgent
  - 需要已登入的使用者 session；無頭模式請使用自訂 LaunchDaemon（未隨附）。
- Linux 和 Windows（WSL2）：systemd user unit
  - 精靈會嘗試 `loginctl enable-linger <user>`，讓 gateway 在登出後持續執行。
  - 可能需要 sudo（寫入 `/var/lib/systemd/linger`）；會先嘗試不用 sudo。
- 執行環境選擇：Node（建議；WhatsApp 和 Telegram 必須使用）。不建議使用 Bun。

步驟七：健康檢查

- 啟動 gateway（如果需要）並執行 `openclaw health`。
- `openclaw status --deep` 在狀態輸出中加入 gateway 健康探測。

步驟八：Skills

- 讀取可用 skills 並檢查需求。
- 讓你選擇 node 管理器：npm 或 pnpm（不建議 bun）。
- 安裝選用相依套件（有些在 macOS 上使用 Homebrew）。

步驟九：完成

- 摘要和後續步驟，包含 iOS、Android 和 macOS app 選項。

注意： 如果未偵測到 GUI，精靈會輸出 SSH 埠號轉發指令給 Control UI，而非開啟瀏覽器。 如果 Control UI 資源遺失，精靈會嘗試建置；備案是 pnpm ui:build（自動安裝 UI 相依套件）。

遠端模式詳情

遠端模式設定這台機器連線到其他地方的 gateway。

Info: 遠端模式不會在遠端主機上安裝或修改任何東西。

設定的項目：

  • 遠端 gateway URL（ws://...）
  • Token（如果遠端 gateway 驗證有要求，建議設定）

注意：

  • 如果 gateway 是 loopback 限定，使用 SSH tunneling 或 tailnet。
  • 發現提示：
    • macOS：Bonjour（dns-sd）
    • Linux：Avahi（avahi-browse）

驗證與模型選項

Anthropic API key 
使用 `ANTHROPIC_API_KEY`（如果存在）或提示輸入 key，然後儲存給 daemon 使用。
Anthropic OAuth（Claude Code CLI） 
- macOS：檢查 Keychain 項目 "Claude Code-credentials"
- Linux 和 Windows：如果存在則重用 `~/.claude/.credentials.json`

macOS 上請選擇「一律允許」，這樣 launchd 啟動時不會被阻擋。
Anthropic token（setup-token 貼上） 
在任何機器上執行 `claude setup-token`，然後貼上 token。
可以命名；留空使用預設。
OpenAI Code subscription（Codex CLI 重用） 
如果 `~/.codex/auth.json` 存在，精靈可以重用它。
OpenAI Code subscription（OAuth） 
瀏覽器流程；貼上 `code#state`。

當模型未設定或為 `openai/*` 時，設定 `agents.defaults.model` 為 `openai-codex/gpt-5.4`。
OpenAI API key 
使用 `OPENAI_API_KEY`（如果存在）或提示輸入 key，然後將憑證儲存到 auth profiles。

當模型未設定、為 `openai/*` 或 `openai-codex/*` 時，設定 `agents.defaults.model` 為 `openai/gpt-5.1-codex`。
xAI（Grok）API key 
提示輸入 `XAI_API_KEY` 並設定 xAI 為模型提供者。
OpenCode 
提示輸入 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）並讓你選擇 Zen 或 Go 目錄。
設定網址：[opencode.ai/auth](https://opencode.ai/auth)。
API key（通用） 
為你儲存 key。
Vercel AI Gateway 
提示輸入 `AI_GATEWAY_API_KEY`。
更多細節：[Vercel AI Gateway](/docs/providers/vercel-ai-gateway)。
Cloudflare AI Gateway 
提示輸入 account ID、gateway ID 和 `CLOUDFLARE_AI_GATEWAY_API_KEY`。
更多細節：[Cloudflare AI Gateway](/docs/providers/cloudflare-ai-gateway)。
MiniMax M2.5 
設定會自動寫入。
更多細節：[MiniMax](/docs/providers/minimax)。
Synthetic（Anthropic 相容） 
提示輸入 `SYNTHETIC_API_KEY`。
更多細節：[Synthetic](/docs/providers/synthetic)。
Ollama（雲端和本地開源模型） 
提示輸入 base URL（預設 `http://127.0.0.1:11434`），然後提供雲端 + 本地或純本地模式。
自動發現可用模型並建議預設值。
更多細節：[Ollama](/docs/providers/ollama)。
Moonshot 和 Kimi Coding 
Moonshot（Kimi K2）和 Kimi Coding 設定會自動寫入。
更多細節：[Moonshot AI（Kimi + Kimi Coding）](/docs/providers/moonshot)。
自訂提供者 
支援 OpenAI 相容和 Anthropic 相容端點。

互動 onboarding 支援與其他提供者 API key 流程相同的儲存選擇：
- **現在貼上 API key**（明文）
- **使用 secret reference**（env ref 或已設定的提供者 ref，附帶預檢驗證）

非互動旗標：
- `--auth-choice custom-api-key`
- `--custom-base-url`
- `--custom-model-id`
- `--custom-api-key`（選用；備案為 `CUSTOM_API_KEY`）
- `--custom-provider-id`（選用）
- `--custom-compatibility <openai|anthropic>`（選用；預設 `openai`）
跳過 
驗證維持未設定。

模型行為：

  • 從偵測到的選項中選擇預設模型，或手動輸入提供者和模型。
  • 精靈會執行模型檢查，如果設定的模型未知或缺少驗證會發出警告。

憑證和設定檔路徑：

  • OAuth 憑證：~/.openclaw/credentials/oauth.json
  • Auth profiles（API keys + OAuth）：~/.openclaw/agents/<agentId>/agent/auth-profiles.json

憑證儲存模式：

  • 預設 onboarding 行為以明文值在 auth profiles 中持久化 API keys。
  • --secret-input-mode ref 啟用參考模式取代明文 key 儲存。 互動 onboarding 中，你可以選擇：
    • 環境變數 ref（例如 keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }）
    • 已設定的提供者 ref（file 或 exec），含提供者別名和 id
  • 互動參考模式在儲存前會執行快速預檢驗證。
    • Env ref：驗證變數名稱和目前 onboarding 環境中的非空值。
    • 提供者 ref：驗證提供者設定並解析請求的 id。
    • 預檢失敗時，onboarding 會顯示錯誤並讓你重試。
  • 非互動模式下，--secret-input-mode ref 僅支援 env 後端。
    • 在 onboarding 行程環境中設定提供者環境變數。
    • 行內 key 旗標（例如 --openai-api-key）需要該環境變數已設定；否則 onboarding 立即失敗。
    • 自訂提供者的非互動 ref 模式將 models.providers.<id>.apiKey 儲存為 { source: "env", provider: "default", id: "CUSTOM_API_KEY" }。
    • 該自訂提供者情境下，--custom-api-key 需要 CUSTOM_API_KEY 已設定；否則 onboarding 立即失敗。
  • Gateway 驗證憑證在互動 onboarding 中支援明文和 SecretRef 選擇：
    • Token 模式：產生/儲存明文 token（預設）或 使用 SecretRef。
    • Password 模式：明文或 SecretRef。
  • 非互動 token SecretRef 路徑：--gateway-token-ref-env <ENV_VAR>。
  • 現有的明文設定會繼續正常運作。

注意： 無頭和伺服器小技巧：在有瀏覽器的機器上完成 OAuth，然後把 ~/.openclaw/credentials/oauth.json（或 $OPENCLAW_STATE_DIR/credentials/oauth.json） 複製到 gateway 主機。

輸出與內部機制

~/.openclaw/openclaw.json 中的常見欄位：

  • agents.defaults.workspace
  • agents.defaults.model / models.providers（選擇 Minimax 時）
  • tools.profile（本地 onboarding 在未設定時預設為 "coding"；現有的明確值會保留）
  • gateway.*（mode、bind、auth、tailscale）
  • session.dmScope（本地 onboarding 在未設定時預設為 per-channel-peer；現有的明確值會保留）
  • 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>/。 Sessions 儲存在 ~/.openclaw/agents/<agentId>/sessions/。

注意： 部分頻道以外掛形式提供。在 onboarding 中選擇時，精靈會提示安裝外掛 （npm 或本地路徑），然後再進行頻道設定。

Gateway 精靈 RPC：

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

客戶端（macOS app 和 Control UI）可以渲染步驟而不需要重新實作 onboarding 邏輯。

Signal 設定行為：

  • 下載對應的 release 資產
  • 儲存在 ~/.openclaw/tools/signal-cli/<version>/
  • 在設定中寫入 channels.signal.cliPath
  • JVM 版本需要 Java 21
  • 有原生版本時優先使用
  • Windows 使用 WSL2 並在 WSL 內遵循 Linux signal-cli 流程

相關文件

arrow_back
上一頁
Openclaw
下一頁
Wizard CLI Automation
arrow_forward