登機精靈參考

這是 openclaw onboard CLI 精靈的完整參考。如需高層級概覽，請參閱登機精靈。

流程詳細資料（本地模式）

現有設定偵測

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

模型／驗證

Anthropic API 金鑰：使用 ANTHROPIC_API_KEY（如果存在）或提示輸入金鑰，然後為精靈用途儲存。
Anthropic OAuth（Claude Code CLI）：在 macOS 上，精靈檢查鑰匙圈項目「Claude Code-credentials」（選擇「始終允許」以便 launchd 啟動不會阻止）；在 Linux／Windows 上，如果存在則重新使用 ~/.claude/.credentials.json。
Anthropic 令牌（貼上設定令牌）：在任何機器上執行 claude setup-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（如果存在）或提示輸入金鑰，然後儲存在驗證設定檔中。
xAI（Grok）API 金鑰：提示輸入 XAI_API_KEY 並將 xAI 設定為模型提供者。
OpenCode：提示輸入 OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY，在 https://opencode.ai/auth 取得）並讓您挑選 Zen 或 Go 目錄。
Ollama：提示輸入 Ollama 基礎 URL、提供 雲端 + 本地或本地模式、發現可用模型，以及在需要時自動拉取所選本地模型。
更多詳細資訊：Ollama
API 金鑰：為您儲存金鑰。
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 M2.5：設定自動寫入。
更多詳細資訊：MiniMax
Synthetic（Anthropic 相容）：提示輸入 SYNTHETIC_API_KEY。
更多詳細資訊：Synthetic
Moonshot（Kimi K2）：設定自動寫入。
Kimi Coding：設定自動寫入。
更多詳細資訊：Moonshot AI（Kimi + Kimi Coding）
略過：尚未設定驗證。
從偵測的選項中挑選預設模型（或手動輸入提供者／模型）。為獲得最佳品質和較低的提示注入風險，請選擇提供者堆疊中可用的最強最新產生模型。
精靈執行模型檢查並警告已設定的模型是否不明或遺留驗證。
API 金鑰儲存模式預設為純文字驗證設定檔值。使用 --secret-input-mode ref 改為儲存環境支援的重新（例如 keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }）。
OAuth 認證存儲在 ~/.openclaw/credentials/oauth.json；驗證設定檔存儲在 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json（API 金鑰 + OAuth）。
更多詳細資訊：/concepts/oauth

無頭／伺服器提示：在具有瀏覽器的機器上完成 OAuth，然後複製 ~/.openclaw/credentials/oauth.json（或 $OPENCLAW_STATE_DIR/credentials/oauth.json）到閘道主機。

工作區

預設 ~/.openclaw/workspace（可設定）。
針對代理啟動儀式播種必要的工作區檔案。
完整工作區配置 + 備份指南：代理工作區

閘道

連接埠、繫結、驗證模式、tailscale 暴露。
驗證建議：即使針對迴圈保持令牌，以便本地 WS 用戶端必須驗證。
在令牌模式中，互動式登機提供：
- 產生／儲存純文字令牌（預設）
- 使用 SecretRef（選擇加入）
- Quickstart 針對登機探測／儀表板啟動在 env、file 和 exec 提供者間重新使用現有 gateway.auth.token SecretRef。
- 如果該 SecretRef 已設定但無法解析，登機早期失敗，並清除修復訊息，而不是無聲降級執行時間驗證。
在密碼模式中，互動式登機也支援純文字或 SecretRef 儲存。
非互動令牌 SecretRef 路徑：--gateway-token-ref-env <ENV_VAR>。
- 需要登機程序環境中的非空環境變數。
- 無法與 --gateway-token 結合。
僅在您完全信任每個本地程序時停用驗證。
非迴圈繫結仍需要驗證。

頻道

WhatsApp：選擇性 QR 登入。
Telegram：機器人令牌。
Discord：機器人令牌。
Google Chat：服務帳戶 JSON + webhook 對象。
Mattermost（外掛）：機器人令牌 + 基礎 URL。
Signal：選擇性 signal-cli 安裝 + 帳戶設定。
BlueBubbles：建議用於 iMessage；伺服器 URL + 密碼 + webhook。
iMessage：舊版 imsg CLI 路徑 + 資料庫存取。
DM 安全性：預設為配對。第一次 DM 傳送代碼；透過 openclaw pairing approve <channel> <code> 批准或使用允許清單。

Web 搜尋

挑選提供者：Perplexity、Brave、Gemini、Grok 或 Kimi（或略過）。
貼上您的 API 金鑰（QuickStart 自動偵測來自環境變數或現有設定的金鑰）。
使用 --skip-search 略過。
稍後設定：openclaw configure --section web。

精靈安裝

macOS：LaunchAgent
- 需要已登入的使用者工作階段；用於無頭，使用自訂 LaunchDaemon（未發佈）。
Linux（和透過 WSL2 的 Windows）：systemd 使用者單位
- 精靈嘗試透過 loginctl enable-linger <user> 啟用逗留，以便 Gateway 在登出後保持執行。
- 可能提示 sudo（寫入 /var/lib/systemd/linger）；它先嘗試無 sudo。
執行時間選擇：Node（建議；WhatsApp／Telegram 必需）。Bun 不建議。
如果令牌驗證需要令牌且 gateway.auth.token 為 SecretRef 管理，精靈安裝驗證它但不將已解析的純文字令牌值保持到監督服務環境中繼資料。
如果令牌驗證需要令牌且已設定的令牌 SecretRef 未解析，精靈安裝被阻止並具有可操作指導。
如果同時設定 gateway.auth.token 和 gateway.auth.password 且 gateway.auth.mode 未設定，精靈安裝被阻止直到明確設定模式。

健康檢查

啟動 Gateway（如果需要）並執行 openclaw health。
提示：openclaw status --deep 將閘道健康探測新增到狀態輸出（需要可到達的閘道）。

技能（建議）

讀取可用的技能並檢查需求。
讓您選擇節點管理員：npm / pnpm（不建議 bun）。
安裝選擇性依賴項（某些在 macOS 上使用 Homebrew）。

完成

摘要 + 後續步驟，包括 iOS／Android／macOS app 以取得額外功能。

如果未偵測到 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 以取得機器可讀摘要。非互動模式中的 Gateway 令牌 SecretRef：

export OPENCLAW_GATEWAY_TOKEN="your-token"
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice skip \
  --gateway-auth token \
  --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN

--gateway-token 和 --gateway-token-ref-env 互斥。

--json 不隱含非互動模式。使用 --non-interactive（和 --workspace）以用於指令碼。

Gemini 範例

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice gemini-api-key \
  --gemini-api-key "$GEMINI_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Z.AI 範例

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice zai-api-key \
  --zai-api-key "$ZAI_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Vercel AI Gateway 範例

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice ai-gateway-api-key \
  --ai-gateway-api-key "$AI_GATEWAY_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Cloudflare AI Gateway 範例

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice cloudflare-ai-gateway-api-key \
  --cloudflare-ai-gateway-account-id "your-account-id" \
  --cloudflare-ai-gateway-gateway-id "your-gateway-id" \
  --cloudflare-ai-gateway-api-key "$CLOUDFLARE_AI_GATEWAY_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Moonshot 範例

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice moonshot-api-key \
  --moonshot-api-key "$MOONSHOT_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Synthetic 範例

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice synthetic-api-key \
  --synthetic-api-key "$SYNTHETIC_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

OpenCode 範例

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice opencode-zen \
  --opencode-zen-api-key "$OPENCODE_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

切換到 --auth-choice opencode-go --opencode-go-api-key "$OPENCODE_API_KEY" 以取得 Go 目錄。

Ollama 範例

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice ollama \
  --custom-model-id "qwen3.5:27b" \
  --accept-risk \
  --gateway-port 18789 \
  --gateway-bind loopback

新增 --custom-base-url "http://ollama-host:11434" 以將目標指向遠端 Ollama 實例。

新增代理（非互動）

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 app、控制 UI）可以轉譯步驟而不需重新實現登機邏輯。

Signal 設定（signal-cli）

精靈可以從 GitHub 發佈安裝 signal-cli：

下載適當的發佈資產。
儲存在 ~/.openclaw/tools/signal-cli/<version>/ 下。
寫入 channels.signal.cliPath 到您的設定。

備註：

JVM 構建需要 Java 21。
可用時使用原生構建。
Windows 使用 WSL2；signal-cli 安裝遵循 WSL 內的 Linux 流程。

精靈寫入的內容

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

agents.defaults.workspace
agents.defaults.model / models.providers（如果選擇 Minimax）
tools.profile（本地登機預設為 "coding"（未設定時）；現有明確值已保留）
gateway.*（模式、繫結、驗證、tailscale）
session.dmScope（行為詳細資料：CLI 登機參考）
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 或本地路徑），然後才能設定。

CLI 指令

RPC 與 API

範本

技術參考

概念內部機制

專案

發布政策

Onboarding Reference（登機精靈參考）

登機精靈參考

流程詳細資料（本地模式）

非互動模式

新增代理（非互動）

Gateway 精靈 RPC

Signal 設定（signal-cli）

精靈寫入的內容

相關文件

CLI 指令

RPC 與 API

範本

技術參考

概念內部機制

專案

發布政策

​登機精靈參考

​流程詳細資料（本地模式）

​非互動模式

​新增代理（非互動）

​Gateway 精靈 RPC

​Signal 設定（signal-cli）

​精靈寫入的內容

​相關文件

登機精靈參考

流程詳細資料（本地模式）

非互動模式

新增代理（非互動）

Gateway 精靈 RPC

Signal 設定（signal-cli）

精靈寫入的內容

相關文件