Onboarding 精靈（CLI）

Onboarding 精靈是在 macOS、Linux 或 Windows（透過 WSL2，強烈建議）上設定 OpenClaw 的推薦方式。 它會在一個引導式流程中設定本地 Gateway 或遠端 Gateway 連線，以及頻道、skills 和工作區預設值。

openclaw onboard

Info: 最快的第一次對話：打開 Control UI（不需要設定頻道）。執行 openclaw dashboard 然後在瀏覽器中聊天。文件：Dashboard。

之後要重新設定：

openclaw configure
openclaw agents add <name>

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

提示： Onboarding 精靈包含一個 web search 步驟，你可以選擇一個提供者 （Perplexity、Brave、Gemini、Grok 或 Kimi）並貼上你的 API key，讓 agent 能使用 web_search。也可以之後再用 openclaw configure --section web 設定。文件：Web 工具。

QuickStart vs 進階

精靈會先讓你選 QuickStart（預設值）或 進階（完全控制）。

QuickStart（預設值）

- 本地 gateway（loopback）
- 預設工作區（或現有工作區）
- Gateway 埠號 **18789**
- Gateway 驗證 **Token**（自動產生，即使是 loopback）
- 新的本地安裝預設工具策略：`tools.profile: "coding"`（現有的明確設定會保留）
- DM 隔離預設：本地 onboarding 在未設定時會寫入 `session.dmScope: "per-channel-peer"`。詳情：[CLI Onboarding 參考](/docs/start/wizard-cli-reference#outputs-and-internals)
- Tailscale 暴露 **關閉**
- Telegram + WhatsApp DM 預設為**白名單**（會提示輸入你的手機號碼）

進階（完全控制）

- 公開所有步驟（模式、工作區、gateway、頻道、daemon、skills）。

精靈設定的內容

**本地模式（預設）**引導你完成以下步驟：

  1. 模型/驗證 — 選擇任何支援的提供者/驗證流程（API key、OAuth 或 setup-token），包括 Custom Provider （OpenAI 相容、Anthropic 相容或 Unknown 自動偵測）。選擇預設模型。 安全提醒：如果這個 agent 會執行工具或處理 webhook/hooks 內容，優先使用最新一代的最強模型，並維持嚴格的工具策略。較弱或較舊的層級更容易被 prompt injection 攻擊。 非互動模式下，--secret-input-mode ref 在 auth profiles 中儲存以環境變數為後端的參考，而非明文 API key。 非互動 ref 模式下，提供者環境變數必須已設定；傳入行內 key 旗標但沒有對應環境變數會立即失敗。 互動模式中，選擇 secret reference 模式後可以指向環境變數或已設定的提供者參考（file 或 exec），並在儲存前進行快速預檢驗證。
  2. 工作區 — Agent 檔案的位置（預設 ~/.openclaw/workspace）。產生 bootstrap 檔案。
  3. Gateway — 埠號、綁定地址、驗證模式、Tailscale 暴露。 互動 token 模式下，可選擇預設的明文 token 儲存或改用 SecretRef。 非互動 token SecretRef 路徑：--gateway-token-ref-env <ENV_VAR>。
  4. 頻道 — WhatsApp、Telegram、Discord、Google Chat、Mattermost、Signal、BlueBubbles 或 iMessage。
  5. Daemon — 安裝 LaunchAgent（macOS）或 systemd user unit（Linux/WSL2）。 如果 token 驗證需要 token 且 gateway.auth.token 由 SecretRef 管理，daemon 安裝會驗證它但不會將解析後的 token 持久化到監督服務環境元資料中。 如果 token 驗證需要 token 且設定的 token SecretRef 未解析，daemon 安裝會被阻擋並提供可操作的指引。 如果同時設定了 gateway.auth.token 和 gateway.auth.password 但 gateway.auth.mode 未設定，daemon 安裝會被阻擋直到明確設定 mode。
  6. 健康檢查 — 啟動 Gateway 並驗證它正在執行。
  7. Skills — 安裝推薦的 skills 和選用相依套件。

注意： 重新執行精靈不會清除任何東西，除非你明確選擇 Reset（或傳入 --reset）。 CLI --reset 預設重置設定、憑證和 sessions；使用 --reset-scope full 來包含工作區。 如果設定無效或含有舊版 key，精靈會要求你先執行 openclaw doctor。

遠端模式只設定本地客戶端連線到其他地方的 Gateway。 它不會在遠端主機上安裝或變更任何東西。

新增另一個 agent

使用 openclaw agents add <name> 來建立有獨立工作區、sessions 和 auth profiles 的 agent。不帶 --workspace 執行時會啟動精靈。

設定的項目：

  • agents.list[].name
  • agents.list[].workspace
  • agents.list[].agentDir

注意事項：

  • 預設工作區路徑為 ~/.openclaw/workspace-<agentId>。
  • 加入 bindings 來路由傳入訊息（精靈可以幫你做）。
  • 非互動旗標：--model、--agent-dir、--bind、--non-interactive。

完整參考

詳細的步驟拆解和設定輸出請參考 CLI Onboarding 參考。 非互動範例請參考 CLI 自動化。 更深入的技術參考（包含 RPC 細節）請參考 精靈參考。

相關文件

arrow_back
上一頁
Onboarding Overview
下一頁
Onboarding
arrow_forward