跳轉到主要內容

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

這是 openclaw onboard 的完整參考。 如需高階概觀，請參閱入門設定（CLI）。

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

1

現有設定偵測

  • 如果 ~/.openclaw/openclaw.json 存在，請選擇保留目前值、檢閱並更新或設定前重設。
  • 重新執行入門設定不會清除任何內容，除非你明確選擇重設 （或傳入 --reset）。
  • CLI --reset 預設為 config+creds+sessions；使用 --reset-scope full 也會移除工作區。
  • 如果設定無效或包含舊版金鑰，精靈會停止並要求 你先執行 openclaw doctor 再繼續。
  • 重設使用 trash（絕不使用 rm），並提供以下範圍：
    • 僅設定
    • 設定 + 憑證 + 工作階段
    • 完整重設（也會移除工作區）
2

模型/驗證

  • Anthropic API 金鑰：如果存在則使用 ANTHROPIC_API_KEY，否則提示輸入金鑰，然後儲存供 daemon 使用。
  • Anthropic API 金鑰：入門設定/設定中的偏好 Anthropic 助理選項。
  • Anthropic setup-token：仍可在入門設定/設定中使用，不過 OpenClaw 現在會在可用時優先重用 Claude CLI。
  • OpenAI Code (Codex) 訂閱（OAuth）：瀏覽器流程；貼上 code#state。
    • 當模型未設定或已是 OpenAI 系列時，透過 Codex runtime 將 agents.defaults.model 設為 openai/gpt-5.5。
  • OpenAI Code (Codex) 訂閱（裝置配對）：使用短效裝置碼的瀏覽器配對流程。
    • 當模型未設定或已是 OpenAI 系列時，透過 Codex runtime 將 agents.defaults.model 設為 openai/gpt-5.5。
  • OpenAI API 金鑰：如果存在則使用 OPENAI_API_KEY，否則提示輸入金鑰，然後將其儲存在驗證設定檔中。
    • 當模型未設定、為 openai/* 或 openai-codex/* 時，將 agents.defaults.model 設為 openai/gpt-5.5。
  • xAI (Grok) API 金鑰：提示輸入 XAI_API_KEY，並將 xAI 設定為模型提供者。
  • OpenCode：提示輸入 OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY，可在 https://opencode.ai/auth 取得），並讓你選擇 Zen 或 Go 目錄。
  • Ollama：先提供雲端 + 本機、僅雲端或僅本機。Cloud only 會提示輸入 OLLAMA_API_KEY 並使用 https://ollama.com；由主機支援的模式會提示輸入 Ollama 基底 URL、探索可用模型，並在需要時自動拉取所選本機模型；Cloud + Local 也會檢查該 Ollama 主機是否已登入以使用雲端存取。
  • 更多詳細資料：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：設定會自動寫入；託管預設值為 MiniMax-M2.7。 API 金鑰設定使用 minimax/...，OAuth 設定使用 minimax-portal/...。
  • 更多詳細資料：MiniMax
  • StepFun：會為中國或全球端點上的 StepFun 標準版或 Step Plan 自動寫入設定。
  • 標準版目前包含 step-3.5-flash，Step Plan 也包含 step-3.5-flash-2603。
  • 更多詳細資料：StepFun
  • 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" }）。
  • 驗證設定檔位於 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json（API 金鑰 + OAuth）。~/.openclaw/credentials/oauth.json 是舊版僅匯入來源。
  • 更多詳細資料：/concepts/oauth
無介面/伺服器提示：在有瀏覽器的機器上完成 OAuth，然後複製 該 agent 的 auth-profiles.json（例如 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json，或對應的 $OPENCLAW_STATE_DIR/... 路徑）到 Gateway 主機。credentials/oauth.json 只是舊版匯入來源。
3

工作區

  • 預設 ~/.openclaw/workspace（可設定）。
  • 植入 agent bootstrap ritual 所需的工作區檔案。
  • 完整工作區配置 + 備份指南：Agent 工作區
4

Gateway

  • 連接埠、繫結、驗證模式、Tailscale 暴露。
  • 驗證建議：即使是 loopback 也保留 Token，讓本機 WS 用戶端必須驗證。
  • 在 token 模式中，互動式設定提供：
    • 產生/儲存純文字 token（預設）
    • 使用 SecretRef（選擇加入）
    • 快速入門會重用跨 env、file 和 exec 提供者的現有 gateway.auth.token SecretRefs，用於入門設定探測/儀表板 bootstrap。
    • 如果該 SecretRef 已設定但無法解析，入門設定會及早失敗並顯示清楚的修正訊息，而不是默默降低 runtime 驗證等級。
  • 在密碼模式中，互動式設定也支援純文字或 SecretRef 儲存。
  • 非互動式 token SecretRef 路徑：--gateway-token-ref-env <ENV_VAR>。
    • 需要入門設定程序環境中有非空的環境變數。
    • 不能與 --gateway-token 搭配使用。
  • 只有在你完全信任每個本機程序時，才停用驗證。
  • 非 loopback 繫結仍需要驗證。
5

頻道

  • WhatsApp：選用 QR 登入。
  • Telegram：bot token。
  • Discord：bot token。
  • Google Chat：服務帳戶 JSON + webhook audience。
  • Mattermost (plugin)：bot token + 基底 URL。
  • Signal：選用 signal-cli 安裝 + 帳戶設定。
  • iMessage：imsg CLI 路徑 + Messages DB 存取權；當 Gateway 在非 Mac 上執行時，請使用 SSH 包裝器。
  • DM 安全性：預設為配對。第一則 DM 會傳送一組代碼；透過 openclaw pairing approve <channel> <code> 核准，或使用允許清單。
6

網頁搜尋

  • 選擇支援的提供者，例如 Brave、DuckDuckGo、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Ollama Web Search、Perplexity、SearXNG 或 Tavily（或略過）。
  • API 支援的提供者可使用環境變數或現有設定進行快速設定；免金鑰提供者則使用其提供者特定的先決條件。
  • 使用 --skip-search 略過。
  • 稍後設定：openclaw configure --section web。
7

Daemon 安裝

  • macOS：LaunchAgent
    • 需要已登入的使用者工作階段；若為無介面環境，請使用自訂 LaunchDaemon（未隨附）。
  • Linux（以及透過 WSL2 的 Windows）：systemd 使用者單元
    • 入門設定會嘗試透過 loginctl enable-linger <user> 啟用 lingering，讓 Gateway 在登出後保持執行。
    • 可能提示 sudo（寫入 /var/lib/systemd/linger）；它會先嘗試不使用 sudo。
  • **Runtime 選擇：**Node（建議；WhatsApp/Telegram 必要）。不建議使用 Bun。
  • 如果 token 驗證需要 token，且 gateway.auth.token 由 SecretRef 管理，daemon 安裝會驗證它，但不會將解析後的純文字 token 值保存到 supervisor 服務環境中繼資料。
  • 如果 token 驗證需要 token，且設定的 token SecretRef 未解析，daemon 安裝會被封鎖並提供可操作的指引。
  • 如果同時設定了 gateway.auth.token 和 gateway.auth.password，且 gateway.auth.mode 未設定，daemon 安裝會被封鎖，直到明確設定模式為止。
8

健康檢查

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

Skills（建議）

  • 讀取可用 Skills 並檢查需求。
  • 讓你選擇 Node 管理器：npm / pnpm（不建議 bun）。
  • 安裝選用相依套件（有些會在 macOS 上使用 Homebrew）。
10

完成

  • 摘要 + 後續步驟，包括 How do you want to hatch your agent? 提示，可選 Terminal、Browser 或稍後。
如果未偵測到 GUI，入門設定會列印 Control UI 的 SSH 連接埠轉送指示，而不是開啟瀏覽器。 如果缺少 Control 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 token 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）。
提供者特定的命令範例位於 CLI 自動化。 使用此參考頁了解旗標語意和步驟順序。

​
新增 agent（非互動式）

openclaw agents add work \
  --workspace ~/.openclaw/workspace-work \
  --model openai/gpt-5.5 \
  --bind whatsapp:biz \
  --non-interactive \
  --json

​
Gateway 精靈 RPC

Gateway 透過 RPC（wizard.start、wizard.next、wizard.cancel、wizard.status）公開入門設定流程。 用戶端（macOS app、Control UI）可以呈現步驟，而不需要重新實作入門設定邏輯。

​
Signal 設定（signal-cli）

入門設定可以從 GitHub releases 安裝 signal-cli：
  • 下載適當的 release 資產。
  • 將其儲存在 ~/.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.matrix.*、channels.signal.*、channels.imessage.*
  • 在提示期間選擇加入時的頻道允許清單（Slack/Discord/Matrix/Microsoft Teams）（名稱會在可行時解析為 ID）。
  • skills.install.nodeManager
    • setup --node-manager 接受 npm、pnpm 或 bun。
    • 手動設定仍可透過直接設定 skills.install.nodeManager 來使用 yarn。
  • 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/ 下。 有些頻道會以 Plugin 形式提供。當你在設定期間選取其中一個時，導覽設定會提示你先安裝它（npm 或本機路徑），之後才能設定。

​
相關文件