Skip to main content

​
CLI 入門參考

本頁是 openclaw onboard 的完整參考。 如需簡短指南，請參閱入門精靈（CLI）。

​
精靈的功能

本地模式（預設）會引導您完成：
  • 模型和認證設定（OpenAI Code 訂閱 OAuth、Anthropic API key 或 setup token，以及 MiniMax、GLM、Ollama、Moonshot 和 AI Gateway 選項）
  • 工作區位置和引導檔案
  • Gateway 設定（連接埠、綁定、認證、tailscale）
  • 頻道和提供者（Telegram、WhatsApp、Discord、Google Chat、Mattermost 外掛、Signal）
  • Daemon 安裝（LaunchAgent 或 systemd 使用者單元）
  • 健康檢查
  • 技能設定
遠端模式設定此機器連接到其他地方的 gateway。 它不會在遠端主機上安裝或修改任何東西。

​
本地流程詳情

1

偵測現有設定

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

模型和認證

3

工作區

  • 預設 ~/.openclaw/workspace（可設定）。
  • 植入首次執行引導儀式所需的工作區檔案。
  • 工作區佈局：Agent workspace。
4

Gateway

  • 提示輸入連接埠、綁定、認證模式和 tailscale 曝露。
  • 建議：即使對環回也保持 token 認證啟用，這樣本地 WS 客戶端必須認證。
  • 在 token 模式中，互動式入門提供：
    • 產生/儲存明文 token（預設）
    • 使用 SecretRef（選用啟用）
  • 在密碼模式中，互動式入門也支援明文或 SecretRef 儲存。
  • 非互動式 token SecretRef 路徑：--gateway-token-ref-env <ENV_VAR>。
    • 在入門程序環境中需要非空的環境變數。
    • 不能與 --gateway-token 組合使用。
  • 只有在完全信任每個本地程序時才停用認證。
  • 非環回綁定仍然需要認證。
5

頻道

  • WhatsApp：選用 QR 登入
  • Telegram：機器人 token
  • Discord：機器人 token
  • Google Chat：服務帳號 JSON + webhook audience
  • Mattermost 外掛：機器人 token + 基本 URL
  • Signal：選用 signal-cli 安裝 + 帳號設定
  • BlueBubbles：建議用於 iMessage；伺服器 URL + 密碼 + webhook
  • iMessage：舊版 imsg CLI 路徑 + 資料庫存取
  • DM 安全性：預設為配對。第一個 DM 發送驗證碼；透過 openclaw pairing approve <channel> <code> 核准或使用允許清單。
6

Daemon 安裝

  • macOS：LaunchAgent
    • 需要已登入的使用者會話；對於無頭設定，請使用自訂 LaunchDaemon（未隨附）。
  • Linux 和 Windows（透過 WSL2）：systemd 使用者單元
    • 精靈嘗試執行 loginctl enable-linger <user> 使 gateway 在登出後仍然執行。
    • 可能提示 sudo（寫入 /var/lib/systemd/linger）；先嘗試不使用 sudo。
  • 執行階段選擇：Node（建議；WhatsApp 和 Telegram 需要）。不建議使用 Bun。
7

健康檢查

  • 啟動 gateway（如需要）並執行 openclaw health。
  • openclaw status --deep 將 gateway 健康探測加入狀態輸出。
8

技能

  • 讀取可用技能並檢查需求。
  • 讓您選擇節點管理器：npm 或 pnpm（不建議使用 bun）。
  • 安裝選用相依套件（某些在 macOS 上使用 Homebrew）。
9

完成

  • 摘要和後續步驟，包括 iOS、Android 和 macOS 應用程式選項。
如果未偵測到 GUI，精靈會印出 SSH 連接埠轉發指示以使用控制 UI，而非開啟瀏覽器。 如果控制 UI 資產遺失，精靈嘗試建置它們；後備方案是 pnpm ui:build（自動安裝 UI 相依套件）。

​
遠端模式詳情

遠端模式設定此機器連接到其他地方的 gateway。
遠端模式不會在遠端主機上安裝或修改任何東西。
您設定的內容：
  • 遠端 gateway URL（ws://...）
  • 如果遠端 gateway 需要認證，則提供 token（建議）
  • 如果 gateway 僅限環回，請使用 SSH 隧道或 tailnet。
  • 探索提示：
    • macOS：Bonjour（dns-sd）
    • Linux：Avahi（avahi-browse）

​
認證和模型選項

使用 ANTHROPIC_API_KEY（如果存在）或提示輸入金鑰，然後儲存供 daemon 使用。
  • macOS：檢查 Keychain 項目「Claude Code-credentials」
  • Linux 和 Windows：若存在則重用 ~/.claude/.credentials.json
在 macOS 上，選擇「Always Allow」以防止 launchd 啟動時被封鎖。
在任何機器上執行 claude setup-token，然後貼上 token。 可命名；空白則使用預設。
如果 ~/.codex/auth.json 存在，精靈可重用它。
瀏覽器流程；貼上 code#state。當模型未設定或為 openai/* 時，將 agents.defaults.model 設為 openai-codex/gpt-5.4。
使用 OPENAI_API_KEY（如果存在）或提示輸入金鑰，然後將憑證儲存在認證設定檔中。當模型未設定、為 openai/* 或 openai-codex/* 時，將 agents.defaults.model 設為 openai/gpt-5.1-codex。
提示輸入 XAI_API_KEY 並將 xAI 設定為模型提供者。
提示輸入 OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY）。 設定 URL：opencode.ai/auth。
為您儲存金鑰。
提示輸入 AI_GATEWAY_API_KEY。 更多詳情：Vercel AI Gateway。
提示輸入帳號 ID、gateway ID 和 CLOUDFLARE_AI_GATEWAY_API_KEY。 更多詳情：Cloudflare AI Gateway。
設定自動寫入。 更多詳情：MiniMax。
提示輸入 SYNTHETIC_API_KEY。 更多詳情：Synthetic。
Moonshot（Kimi K2）和 Kimi Coding 設定自動寫入。 更多詳情：Moonshot AI（Kimi + Kimi Coding）。
適用於 OpenAI 相容和 Anthropic 相容端點。互動式入門支援與其他提供者 API key 流程相同的 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
  • 認證設定檔（API keys + OAuth）：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
憑證儲存模式：
  • 預設入門行為將 API key 以明文值持久化在認證設定檔中。
  • --secret-input-mode ref 啟用參考模式而非明文 key 儲存。 在互動式入門中，您可以選擇：
    • 環境變數 ref（例如 keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }）
    • 已設定的提供者 ref（file 或 exec）含提供者別名 + id
  • 互動式參考模式在儲存前執行快速預檢驗證。
    • Env refs：驗證變數名稱 + 目前入門環境中的非空值。
    • 提供者 refs：驗證提供者設定並解析請求的 id。
    • 如果預檢失敗，入門顯示錯誤並讓您重試。
  • 在非互動式模式中，--secret-input-mode ref 僅支援 env 支援的模式。
    • 在入門程序環境中設定提供者環境變數。
    • 內聯 key 標誌（例如 --openai-api-key）需要設定該環境變數；否則入門快速失敗。
    • 對於自訂提供者，非互動式 ref 模式將 models.providers.<id>.apiKey 儲存為 { source: "env", provider: "default", id: "CUSTOM_API_KEY" }。
    • 在該自訂提供者情況下，--custom-api-key 需要設定 CUSTOM_API_KEY；否則入門快速失敗。
  • Gateway 認證憑證在互動式入門中支援明文和 SecretRef 選項：
    • Token 模式：產生/儲存明文 token（預設）或使用 SecretRef。
    • 密碼模式：明文或 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（本地入門預設為 "coding"（未設定時）；現有明確值予以保留）
  • gateway.*（模式、綁定、認證、tailscale）
  • session.dmScope（本地入門預設為 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>/ 下。 會話存放在 ~/.openclaw/agents/<agentId>/sessions/ 下。
某些頻道以外掛形式提供。在入門過程中選擇時，精靈 在頻道設定之前提示安裝外掛（npm 或本地路徑）。
Gateway 精靈 RPC：
  • wizard.start
  • wizard.next
  • wizard.cancel
  • wizard.status
客戶端（macOS 應用程式和控制 UI）可以渲染步驟而無需重新實作入門邏輯。 Signal 設定行為：
  • 下載適當的發布資產
  • 儲存在 ~/.openclaw/tools/signal-cli/<version>/ 下
  • 在設定中寫入 channels.signal.cliPath
  • JVM 版本需要 Java 21
  • 可用時使用原生版本
  • Windows 使用 WSL2 並在 WSL 內遵循 Linux signal-cli 流程

​
相關文件