跳轉到主要內容
本頁涵蓋逐步 onboarding 行為、輸出與內部機制。 如需逐步導覽，請參閱 Onboarding（命令列介面）。如需完整的命令列介面旗標 參考（每個 --flag、非互動式範例、供應商特定 命令），請參閱 openclaw onboard。

​
精靈會做什麼

本機模式（預設）會引導你完成：
  • 模型與驗證設定（Anthropic、OpenAI Code 訂閱 OAuth、xAI、OpenCode、自訂端點，以及更多由供應商擁有的驗證流程）
  • 工作區位置與 bootstrap 檔案
  • 閘道設定（連接埠、綁定、驗證、Tailscale）
  • 頻道與供應商（Discord、Feishu、Google Chat、iMessage、Mattermost、Microsoft Teams、QQ Bot、Signal、Slack、Telegram、WhatsApp，以及其他內建或外掛頻道）
  • 網頁搜尋供應商（選用）
  • 常駐程式安裝（LaunchAgent、systemd 使用者單元，或原生 Windows 排程工作，並以啟動資料夾作為備援）
  • 健康檢查
  • Skills 設定
遠端模式會設定這台機器連線到其他位置的閘道。它不會 在遠端主機上安裝或修改任何內容。

​
本機流程細節

1

Existing config detection

  • 如果 ~/.openclaw/openclaw.json 存在，請選擇 保留目前值、檢閱並更新，或 設定前重設。
  • 重新執行精靈不會清除任何內容，除非你明確選擇重設（或傳入 --reset）。
  • 命令列介面 --reset 預設為 config+creds+sessions；使用 --reset-scope full 也會移除工作區。
  • 如果設定無效或包含舊版鍵，精靈會停止並要求你先執行 openclaw doctor 再繼續。
  • 重設會將狀態移到垃圾桶（絕不直接刪除），並提供範圍：
    • 僅設定
    • 設定 + 認證 + 工作階段
    • 完整重設（也會移除工作區）
2

Model and auth

3

Workspace

  • 預設 ~/.openclaw/workspace（可設定）。
  • 植入首次執行 bootstrap 所需的工作區檔案。
  • 工作區配置：代理工作區。
4

Gateway

  • 提示輸入連接埠、綁定、驗證模式與 Tailscale 暴露設定。
  • 建議：即使是 loopback 也保持權杖驗證啟用，讓本機 WS 用戶端必須驗證。
  • 在權杖模式中，互動式設定提供：
    • 產生/儲存純文字權杖（預設）
    • 使用 SecretRef（選用）
  • 在密碼模式中，互動式設定也支援純文字或 SecretRef 儲存。
  • 非互動式權杖 SecretRef 路徑：--gateway-token-ref-env <ENV_VAR>。
    • onboarding 程序環境中必須有非空的環境變數。
    • 不能與 --gateway-token 合併使用。
  • 只有在你完全信任每個本機程序時才停用驗證。
  • 非 loopback 綁定仍需要驗證。
5

Channels

  • WhatsApp：選用 QR 登入
  • Telegram：Bot 權杖
  • Discord：Bot 權杖
  • Google Chat：服務帳戶 JSON + 網路鉤子 audience
  • Mattermost：Bot 權杖 + 基底 URL
  • Signal：選用 signal-cli 安裝 + 帳戶設定
  • iMessage：imsg 命令列介面路徑 + Messages DB 存取；當閘道在非 Mac 上執行時，請使用 SSH wrapper
  • DM 安全性：預設為配對。第一則 DM 會傳送代碼；透過 openclaw pairing approve <channel> <code> 核准，或使用允許清單。
6

Web search

  • 選擇供應商（Brave、DuckDuckGo、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Ollama Web Search、Perplexity、SearXNG、Tavily）或略過。
  • 使用 --skip-search 略過此步驟；稍後可用 openclaw configure --section web 重新設定。
7

Daemon install

  • macOS：LaunchAgent
    • 需要已登入的使用者工作階段；若為 headless，請使用自訂 LaunchDaemon（未隨附）。
  • Linux 與透過 WSL2 的 Windows：systemd 使用者單元
    • 精靈會嘗試 loginctl enable-linger <user>，讓閘道在登出後保持執行。
    • 可能提示 sudo（寫入 /var/lib/systemd/linger）；它會先嘗試不使用 sudo。
  • 原生 Windows：優先使用排程工作
    • 如果建立工作遭拒，OpenClaw 會退回每位使用者的啟動資料夾登入項目，並立即啟動閘道。
    • 排程工作仍是偏好的方式，因為它們提供更好的 supervisor 狀態。
  • 執行階段選擇：互動式只提供節點。Bun 在 WhatsApp/Telegram 重新連線時可能造成記憶體毀損，且不是這些頻道支援的常駐程式執行階段；只有在該組合之外才傳入 --daemon-runtime bun。
8

Health check

  • 啟動閘道（如有需要）並執行 openclaw health。
  • openclaw status --deep 會將即時閘道健康探測加入狀態輸出，包含支援時的頻道探測。
9

Skills

  • 讀取可用的 Skills 並檢查需求。
  • 讓你選擇節點管理器：npm、pnpm 或 bun。
  • 當所需 安裝器可用時，為受信任的內建 Skills 安裝選用依賴。
  • 略過不可用的 Homebrew、uv 與 Go 安裝器，然後將受影響的 Skills 分組並提供手動設定指引。安裝缺少的先決條件後，執行 openclaw doctor。
10

Finish

  • 摘要與後續步驟，包含 iOS、Android 與 macOS app 選項。
如果未偵測到 GUI，精靈會列印 Control UI 的 SSH 連接埠轉送指示，而不是開啟瀏覽器。 如果缺少 Control UI 資產，精靈會嘗試建置它們；備援是 pnpm ui:build（會自動安裝 UI 依賴）。

​
遠端模式細節

遠端模式會設定這台機器連線到其他位置的閘道。它不會 在遠端主機上安裝或修改任何內容。 你會設定：
  • 遠端閘道 URL（ws://... 或 wss://...）
  • 權杖、密碼或無驗證，與遠端閘道的設定相符
1

Discovery (optional)

如果 dns-sd（macOS）或 avahi-browse（Linux）可用，onboarding 會在退回手動輸入 URL 前，提供搜尋 Bonjour/mDNS 閘道 beacon 的選項。 設定後也會嘗試廣域 DNS-SD 探索。文件：閘道探索、Bonjour。
2

Connection method

選取 beacon 時，請選擇直接 WebSocket 或 SSH tunnel：
  • 直接：透過 wss:// 連線，並提示信任探索到的 TLS 指紋（首次使用信任釘選；只有在你接受時才會釘選）。
  • SSH tunnel：列印要先執行的 ssh -N -L 18789:127.0.0.1:18789 <user>@<host> 命令，然後連線到本機 tunnel 端點。
3

Auth

選擇權杖（建議）、密碼或無驗證，然後選擇性地將其儲存 為 SecretRef，而不是純文字。
如果閘道僅限 loopback 且無法探索，請手動使用 SSH tunneling 或 tailnet。 純文字 ws:// 可用於 loopback、私有 IP 字面值、.local 與 Tailnet *.ts.net URL；其他私有 DNS 名稱需要 OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1。

​
驗證與模型選項

如果存在則使用 ANTHROPIC_API_KEY，否則提示輸入金鑰，然後儲存以供常駐程式使用。
互動式 onboarding/configure 中偏好的本機路徑；可用時會重用現有 Claude 命令列介面登入。
瀏覽器流程；貼上 code#state。當模型未設定或已是 OpenAI 系列時，透過 Codex 執行階段將 agents.defaults.model 設為 openai/gpt-5.5。
使用短效裝置代碼的瀏覽器配對流程。當模型未設定或已是 OpenAI 系列時，透過 Codex 執行階段將 agents.defaults.model 設為 openai/gpt-5.5。
如果存在則使用 OPENAI_API_KEY，否則提示輸入金鑰，然後將認證儲存在驗證設定檔中。當模型未設定、為 openai/*，或為舊版 Codex 模型參照時，將 agents.defaults.model 設為 openai/gpt-5.5。
適用於符合資格的 SuperGrok 或 X Premium 帳戶的瀏覽器登入。這是多數使用者 建議的 xAI 路徑。OpenClaw 會儲存產生的驗證 設定檔，用於 Grok 模型、Grok web_search、x_search 與 code_execution。
使用短代碼而非 localhost callback 的遠端友善瀏覽器登入。請在 SSH、Docker 或 VPS 主機上使用此方式。
提示輸入 XAI_API_KEY，並將 xAI 設定為模型供應商。當你想使用 xAI Console API key 而非訂閱 OAuth 時，請使用此方式。
提示輸入 OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY），並讓你選擇 Zen 或 Go 目錄（一個 API key 涵蓋兩者）。 設定 URL：opencode.ai/auth。
為你儲存金鑰。
提示輸入 AI_GATEWAY_API_KEY。 更多細節：Vercel AI Gateway。
提示輸入帳戶 ID、閘道 ID 與 CLOUDFLARE_AI_GATEWAY_API_KEY。 更多細節：Cloudflare AI Gateway。
設定會自動寫入。託管預設值為 MiniMax-M3；API key 設定使用 minimax/...，OAuth 設定使用 minimax-portal/...。 更多細節：MiniMax。
設定會為中國或全球端點上的 StepFun standard 或 Step Plan 自動寫入。 Standard 目前包含 step-3.5-flash，Step Plan 也包含 step-3.5-flash-2603。 更多細節：StepFun。
提示輸入 SYNTHETIC_API_KEY。 更多細節：Synthetic。
先提示選擇 Cloud + Local、Cloud only 或 Local only。 Cloud only 使用 OLLAMA_API_KEY 搭配 https://ollama.com。 主機支援的模式會提示輸入基底 URL（預設 http://127.0.0.1:11434）、探索可用模型，並建議預設值。 Cloud + Local 也會檢查該 Ollama 主機是否已登入以取得雲端存取。 更多細節：Ollama。
Moonshot（Kimi K2）與 Kimi Coding 設定會自動寫入。 更多細節：Moonshot AI（Kimi + Kimi Coding）。
可搭配 OpenAI-compatible、OpenAI Responses-compatible 與 Anthropic-compatible 端點運作。互動式 onboarding 支援與其他供應商 API key 流程相同的 API key 儲存選項：
  • 立即貼上 API key（純文字）
  • 使用 secret reference（環境 ref 或已設定的供應商 ref，並進行 preflight 驗證）
Onboarding 會為常見 vision 模型 ID（GPT-4o/4.1/5.x、Claude 3/4、Gemini、Qwen-VL、LLaVA、Pixtral 及類似模型）推斷影像支援，且只有在模型名稱未知時才詢問。非互動式旗標：
  • --auth-choice custom-api-key
  • --custom-base-url
  • --custom-model-id
  • --custom-api-key（選用；會退回使用 CUSTOM_API_KEY）
  • --custom-provider-id（選用）
  • --custom-compatibility <openai|openai-responses|anthropic>（選用；預設為 openai）
  • --custom-image-input / --custom-text-input（選用；覆寫推斷出的模型輸入能力）
保持驗證未設定。
模型行為：
  • 從偵測到的選項中挑選預設模型，或手動輸入提供者和模型。
  • 當上手流程從提供者驗證選擇開始時，模型選擇器會自動偏好 該提供者。對於 Volcengine 和 BytePlus，同一個偏好 也會匹配它們的 coding-plan 變體（volcengine-plan/*、 byteplus-plan/*）。
  • 如果該偏好提供者篩選結果為空，選擇器會改為退回使用 完整目錄，而不是不顯示任何模型。
  • 精靈會執行模型檢查，並在設定的模型未知或缺少驗證時發出警告。
憑證與設定檔路徑：
  • 驗證設定檔（API 金鑰 + OAuth）：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • 舊版 OAuth 匯入：~/.openclaw/credentials/oauth.json
憑證儲存模式：
  • 預設上手流程行為會將 API 金鑰以純文字值保存到驗證設定檔中。
  • --secret-input-mode ref 會啟用參照模式，而不是純文字金鑰儲存。 在互動式設定中，你可以選擇以下任一項：
    • 環境變數參照（例如 keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }）
    • 已設定的提供者參照（file 或 exec），包含提供者別名 + id
  • 互動式參照模式會在儲存前執行快速預檢驗證。
    • 環境參照：驗證目前上手流程環境中的變數名稱 + 非空值。
    • 提供者參照：驗證提供者設定並解析要求的 id。
    • 如果預檢失敗，上手流程會顯示錯誤並讓你重試。
  • 在非互動式模式中，--secret-input-mode ref 僅由環境支援。
    • 在上手流程處理程序環境中設定提供者環境變數。
    • 內嵌金鑰旗標（例如 --openai-api-key）要求該環境變數已設定；否則上手流程會快速失敗。
    • 對於自訂提供者，非互動式 ref 模式會將 models.providers.<id>.apiKey 儲存為 { source: "env", provider: "default", id: "CUSTOM_API_KEY" }。
    • 在該自訂提供者情況下，--custom-api-key 要求 CUSTOM_API_KEY 已設定；否則上手流程會快速失敗。
  • 閘道驗證憑證在互動式設定中支援純文字和 SecretRef 選擇：
    • 權杖模式：產生/儲存純文字權杖（預設）或 使用 SecretRef。
    • 密碼模式：純文字或 SecretRef。
  • 非互動式權杖 SecretRef 路徑：--gateway-token-ref-env <ENV_VAR>。
  • 現有純文字設定會照常繼續運作。
無頭與伺服器提示：在有瀏覽器的機器上完成 OAuth，然後將 該代理的 auth-profiles.json（例如 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json，或相符的 $OPENCLAW_STATE_DIR/... 路徑）複製到閘道主機。credentials/oauth.json 只是舊版匯入來源。

​
輸出與內部項目

~/.openclaw/openclaw.json 中的典型欄位：
  • agents.defaults.workspace
  • 傳入 --skip-bootstrap 時的 agents.defaults.skipBootstrap
  • agents.defaults.model / models.providers（如果選擇 Minimax）
  • tools.profile（local 上手流程在未設定時預設為 "coding"；現有明確值會保留）
  • gateway.*（模式、繫結、驗證、tailscale）
  • session.dmScope（local 上手流程在未設定時會將此預設為 per-channel-peer；現有明確值會保留）
  • channels.telegram.botToken、channels.discord.token、channels.matrix.*、channels.signal.*、channels.imessage.*
  • 當你在提示中選擇加入時的頻道允許清單（Discord、iMessage、Signal、Slack、Telegram、WhatsApp）；Discord 和 Slack 也會將輸入的名稱解析為 ID
  • skills.install.nodeManager
    • setup --node-manager 旗標接受 npm、pnpm 或 bun。
    • 手動設定稍後仍可設定 skills.install.nodeManager: "yarn"。
  • wizard.lastRunAt
  • wizard.lastRunVersion
  • wizard.lastRunCommit
  • wizard.lastRunCommand
  • wizard.lastRunMode
  • wizard.securityAcknowledgedAt
openclaw agents add 會寫入 agents.list[] 和選用的 bindings。 WhatsApp 憑證會放在 ~/.openclaw/credentials/whatsapp/<accountId>/ 底下。 工作階段會儲存在 ~/.openclaw/agents/<agentId>/sessions/ 底下。
部分頻道是以外掛形式提供。當在設定期間選取時，精靈會 在頻道設定前提示安裝外掛（npm 或本機路徑）。

​
非互動式設定

--non-interactive 需要 --accept-risk（確認代理很強大， 且完整系統存取具有風險）： 
openclaw onboard --non-interactive --accept-risk \
  --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY"
完整旗標參考與提供者特定範例：openclaw onboard、命令列介面自動化。

​
閘道精靈 RPC

  • wizard.start
  • wizard.next
  • wizard.cancel
  • wizard.status
用戶端（macOS app 和控制 UI）可以呈現步驟，而不需要重新實作上手流程邏輯。

​
Signal 設定行為

  • 從官方 signal-cli GitHub releases 下載適當的發行資產（原生建置，僅限 Linux x86-64）
  • 在其他平台（macOS、非 x64 Linux）上，改用 Homebrew 安裝
  • 將發行資產安裝儲存在 ~/.openclaw/tools/signal-cli/<version>/ 底下
  • 在設定中寫入 channels.signal.cliPath
  • 尚未支援原生 Windows；請在 WSL2 內執行上手流程，以取得 Linux 安裝路徑

​
相關文件