Skip to content
OpenClaw Docs

Onboarding 參考

這是 openclaw onboard 的完整參考。 若要了解高階概覽，請參閱 Onboarding (CLI)。

流程詳情 (本機模式)

Section titled “流程詳情 (本機模式)”

  1. Existing config detection

    • 如果 ~/.openclaw/openclaw.json 存在，請選擇 Keep current values（保留當前值）、Review and update（審閱並更新）或 Reset before setup（在設定前重設）。
    • 重新執行入門嚮導不會清除任何內容，除非您明確選擇 Reset（重設） （或傳遞 --reset）。
    • CLI --reset 預設為 config+creds+sessions；請使用 --reset-scope full 同時移除工作區。
    • 如果設定無效或包含舊版金鑰，嚮導會停止並要求您 在繼續之前執行 openclaw doctor。
    • 重設會使用 trash（絕不使用 rm）並提供範圍選項：
      • 僅設定
      • 設定 + 憑證 + 會話
      • 完整重設（同時移除工作區）

  2. Model/Auth

    • Anthropic API key: 如果存在則使用 ANTHROPIC_API_KEY，否則提示輸入金鑰，然後將其保存供守護程序使用。
    • Anthropic API key: 在 onboarding/configure 中首選的 Anthropic 助手選項。
    • Anthropic setup-token: 仍然可在 onboarding/configure 中使用，儘管 OpenClaw 現在在可用時更傾向於重複使用 Claude CLI。
    • OpenAI Code (Codex) subscription (OAuth): 瀏覽器流程；貼上 code#state。
      • 當模型未設定或已是 OpenAI 系列時，透過 Codex 執行時將 agents.defaults.model 設定為 openai/gpt-5.5。
    • OpenAI Code (Codex) subscription (device pairing): 使用短期裝置代碼的瀏覽器配對流程。
      • 當模型未設定或已是 OpenAI 系列時，透過 Codex 執行時將 agents.defaults.model 設定為 openai/gpt-5.5。
    • OpenAI API key: 如果存在則使用 OPENAI_API_KEY，否則提示輸入金鑰，然後將其儲存在 auth profiles 中。
      • 當模型未設定、openai/* 或 openai-codex/* 時，將 agents.defaults.model 設定為 openai/gpt-5.5。
    • xAI (Grok) API key: 提示輸入 XAI_API_KEY 並將 xAI 設定為模型提供者。
    • OpenCode: 提示輸入 OPENCODE_API_KEY (或 OPENCODE_ZEN_API_KEY，請在 https://opencode.ai/auth 取得)，並讓您選擇 Zen 或 Go 目錄。
    • Ollama: 首先提供 Cloud + Local、Cloud only 或 Local only。Cloud only 提示輸入 OLLAMA_API_KEY 並使用 https://ollama.com；主機託管模式會提示輸入 Ollama 基礎 URL，探索可用模型，並在需要時自動拉取選定的本地模型；Cloud + Local 也會檢查該 Ollama 主機是否已登入雲端存取權。
    • 更多詳情: Ollama
    • API key: 為您儲存金鑰。
    • Vercel AI Gateway (multi-model proxy): 提示輸入 AI_GATEWAY_API_KEY。
    • 更多詳情: Vercel AI Gateway
    • Cloudflare AI Gateway: 提示輸入 Account 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-compatible): 提示輸入 SYNTHETIC_API_KEY。
    • 更多詳情: Synthetic
    • Moonshot (Kimi K2): 配置會自動寫入。
    • Kimi Coding: 配置會自動寫入。
    • 更多詳情: Moonshot AI (Kimi + Kimi Coding)
    • Skip: 尚未配置身份驗證。
    • 從偵測到的選項中挑選一個預設模型 (或手動輸入提供者/模型)。為了獲得最佳品質並降低提示注入風險，請選擇您提供者堆疊中可用的最強最新一代模型。
    • Onboarding 會執行模型檢查，如果設定的模型未知或缺少身份驗證，則會發出警告。
    • API 金鑰儲存模式預設為純文字 auth-profile 值。使用 --secret-input-mode ref 來改為儲存環境變數支援的參照 (例如 keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" })。
    • Auth profiles 儲存在 `~/.openclaw/agents/

    /agent/auth-profiles.json 中 (API 金鑰 + OAuth)。~/.openclaw/credentials/oauth.json` 僅供舊版匯入使用。 - 更多詳情: /concepts/oauth

  3. Workspace

    • 預設為 ~/.openclaw/workspace（可設定）。
    • 產生代理程式啟動儀式所需的工作區檔案。
    • 完整的工作區佈局與備份指南：Agent workspace

  4. Gateway

    • 連接埠、綁定、驗證模式、Tailscale 暴露。
    • 驗證建議：即使是回環也請保留 Token，以便本機 WS 用戶端必須通過驗證。
    • 在 Token 模式下，互動式設定提供：
      • 產生/儲存明文 Token（預設）
      • 使用 SecretRef（選用）
      • 快速入門會跨 env、file 和 exec 提供者重用現有的 gateway.auth.token SecretRefs，以進行入站探查/儀表板啟動。
      • 如果該 SecretRef 已設定但無法解析，入站程式會提前失敗並顯示明確的修復訊息，而不是讓執行時期驗證無聲降級。
    • 在密碼模式下，互動式設定也支援明文或 SecretRef 儲存。
    • 非互動式 Token SecretRef 路徑：`—gateway-token-ref-env

    。 - 需要在入站程式程序環境中有一個非空的環境變數。 - 不能與 —gateway-token` 結合使用。 - 僅在您完全信任每個本機程序時才停用驗證。 - 非回環綁定仍需驗證。

  5. Channels

    • WhatsApp：選用 QR 登入。
    • Telegram：Bot Token。
    • Discord：Bot Token。
    • Google Chat：服務帳戶 JSON + Webhook 受眾。
    • Mattermost (外掛程式)：Bot Token + 基礎 URL。
    • Signal：選用 signal-cli 安裝 + 帳戶設定。
    • iMessage：imsg CLI 路徑 + Messages DB 存取；當 Gateway 在非 Mac 上執行時，請使用 SSH 包裝程式。
    • DM 安全性：預設為配對。第一個 DM 會傳送程式碼；透過 `openclaw pairing approve

    ` 核准或使用允許清單。

非互動模式

Section titled “非互動模式”

使用 --non-interactive 來自動化或撰寫 onboarding 腳本：

Terminal window
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：

Terminal window
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 互斥。

特定提供者的指令範例位於 CLI Automation。 請使用此參考頁面了解旗標語義與步驟順序。

新增代理程式（非互動式）

Section titled “新增代理程式（非互動式）”
Terminal window
openclaw agents add work \
  --workspace ~/.openclaw/workspace-work \
  --model openai/gpt-5.5 \
  --bind whatsapp:biz \
  --non-interactive \
  --json

Gateway 精靈 RPC

Section titled “Gateway 精靈 RPC”

Gateway 透過 RPC (wizard.start, wizard.next, wizard.cancel, wizard.status) 公開入職流程。 客戶端 (macOS app, Control UI) 可以在不重新實作入職邏輯的情況下呈現步驟。

Signal 設定

Section titled “Signal 設定”

入職流程可以從 GitHub releases 安裝 signal-cli：

  • 下載適當的發行資源。
  • 將其儲存在 ~/.openclaw/tools/signal-cli/<version>/ 下。
  • 將 channels.signal.cliPath 寫入您的設定。

備註：

  • JVM 版本需要 Java 21。
  • 可用時會使用原生版本。
  • Windows 使用 WSL2；signal-cli 安裝會在 WSL 內遵循 Linux 流程。

精靈寫入的內容

Section titled “精靈寫入的內容”

~/.openclaw/openclaw.json 中的常見欄位：

  • agents.defaults.workspace
  • agents.defaults.model / models.providers（若選擇 Minimax）
  • tools.profile（若未設定，本機入職預設為 "coding"；保留現有的明確值）
  • gateway.*（mode、bind、auth、tailscale）
  • session.dmScope (行為細節：CLI Setup Reference)
  • 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>/ 下方。 Session 儲存在 ~/.openclaw/agents/<agentId>/sessions/ 下方。

部分通道是以外掛程式形式提供。當您在設定期間選擇其中一個時，入門程序會提示您在進行設定之前先安裝它（npm 或本機路徑）。

相關文件

Section titled “相關文件”