跳轉到主要內容

​
入門引導精靈參考

這是 openclaw onboard CLI 精靈的完整參考。 如需高層概覽，請參閱 入門引導精靈。

​
流程細節（本機模式）

1

Existing config detection

  • 若 ~/.openclaw/openclaw.json 存在，請選擇 保留 / 修改 / 重設。
  • 重新執行精靈 不會 清除任何內容，除非你明確選擇 重設 （或傳入 --reset）。
  • 如果設定無效或包含舊版鍵值，精靈會停止並要求你在繼續之前執行 openclaw doctor。
  • 重設會使用 trash（絕不使用 rm），並提供範圍選項：
    • 僅設定
    • 設定 + 憑證 + 工作階段
    • 完整重設（也會移除工作區）
2

Model/Auth

  • Anthropic API 金鑰（建議）：若存在則使用 ANTHROPIC_API_KEY，否則提示輸入金鑰，接著儲存以供 daemon 使用。
  • Anthropic OAuth（Claude Code CLI）：在 macOS 上，精靈會檢查 Keychain 項目「Claude Code-credentials」（請選擇「Always Allow」以避免 launchd 啟動時被阻擋）；在 Linux/Windows 上，若存在則重用 ~/.claude/.credentials.json。
  • Anthropic token（貼上 setup-token）：在任何機器上執行 claude setup-token，然後貼上 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，否則提示輸入金鑰，然後將其儲存至 ~/.openclaw/.env 以便 launchd 讀取。
  • xAI（Grok）API 金鑰：提示輸入 XAI_API_KEY，並將 xAI 設定為模型提供者。
  • OpenCode Zen（多模型代理）：提示輸入 OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY，於 https://opencode.ai/auth 取得）。
  • API 金鑰：為你儲存金鑰。
  • Vercel AI Gateway（多模型代理）：提示輸入 AI_GATEWAY_API_KEY。
  • 更多細節：Vercel AI Gateway
  • Cloudflare AI Gateway：提示輸入 Account ID、Gateway ID 與 CLOUDFLARE_AI_GATEWAY_API_KEY。
  • 更多細節：Cloudflare AI Gateway
  • MiniMax M2.1：設定會自動寫入。
  • 更多細節：MiniMax
  • Synthetic（相容 Anthropic）：提示輸入 SYNTHETIC_API_KEY。
  • 更多細節：Synthetic
  • Moonshot（Kimi K2）：設定會自動寫入。
  • Kimi Coding：設定會自動寫入。
  • 更多細節：Moonshot AI（Kimi + Kimi Coding）
  • Skip：尚未設定任何驗證。
  • 從偵測到的選項中選擇預設模型（或手動輸入 provider/model）。
  • 精靈會執行模型檢查，若設定的模型未知或缺少驗證，會顯示警告。
  • 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）複製到 Gateway 主機。
3

Workspace

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

Gateway

  • 連接埠、bind、驗證模式、Tailscale 對外暴露。
  • 驗證建議：即使是 loopback，也請保留 Token，讓本機 WS 用戶端必須驗證。
  • 只有在你完全信任所有本機程序時才停用驗證。
  • 非 loopback 的 bind 仍然需要驗證。
5

Channels

  • WhatsApp：可選 QR 登入。
  • Telegram：bot token。
  • Discord：bot token。
  • Google Chat：service account JSON + webhook audience。
  • Mattermost（外掛）：bot token + base URL。
  • Signal：可選安裝 signal-cli + 帳號設定。
  • BlueBubbles：iMessage 建議方案；server URL + password + webhook。
  • iMessage：舊版 imsg CLI 路徑 + DB 存取。
  • DM 安全性：預設為配對。第一則 DM 會傳送代碼；透過 openclaw pairing approve <channel> <code> 核准，或使用允許清單。
6

Daemon install

  • macOS：LaunchAgent
    • 需要已登入的使用者工作階段；若為無頭環境，請使用自訂 LaunchDaemon（未隨附）。
  • Linux（以及透過 WSL2 的 Windows）：systemd 使用者單元
    • 精靈會嘗試透過 loginctl enable-linger <user> 啟用 lingering，讓 Gateway 在登出後仍持續運行。
    • 可能會提示 sudo（寫入 /var/lib/systemd/linger）；會先嘗試不使用 sudo。
  • 執行環境選擇： Node（建議；WhatsApp/Telegram 必須）。不建議 使用 Bun。
7

Health check

  • 啟動 Gateway（如有需要）並執行 openclaw health。
  • 提示：openclaw status --deep 會在狀態輸出中加入 gateway 健康探測（需要可連線的 gateway）。
8

Skills (recommended)

  • 讀取可用的 Skills 並檢查需求。
  • 讓你選擇 node 管理工具：npm / pnpm（不建議使用 bun）。
  • 安裝選用相依套件（部分在 macOS 上使用 Homebrew）。
9

Finish

  • 摘要與後續步驟，包括 iOS/Android/macOS 應用程式以啟用額外功能。
若未偵測到 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 以取得機器可讀的摘要。
--json 不代表非互動模式。請在指令碼中使用 --non-interactive（以及 --workspace）。
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice gemini-api-key \
  --gemini-api-key "$GEMINI_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

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

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

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

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

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

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

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

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、Control UI）可在不重新實作入門邏輯的情況下呈現步驟。

​
Signal 設定（signal-cli）

精靈可從 GitHub 發行版安裝 signal-cli：
  • 下載對應的發行版資產。
  • 儲存在 ~/.openclaw/tools/signal-cli/<version>/ 之下。
  • 將 channels.signal.cliPath 寫入你的設定。
注意事項：
  • JVM 版本需要 Java 21。
  • 若有可用版本，會使用 Native build。
  • Windows 使用 WSL2；signal-cli 的安裝會在 WSL 內依 Linux 流程進行。

​
What the wizard writes

~/.openclaw/openclaw.json 中的常見欄位：
  • agents.defaults.workspace
  • agents.defaults.model / models.providers（若選擇 Minimax）
  • gateway.*（模式、bind、驗證、tailscale）
  • 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>/。 Sessions are stored under ~/.openclaw/agents/<agentId>/sessions/. 部分頻道以外掛形式提供。當你在入門流程中選擇其中一個時，精靈會先提示安裝它（npm 或本機路徑），然後才能進行設定。