Skip to content
OpenClaw Docs

入門參考

入門參考

Section titled “入門參考”

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

流程詳細資訊（本機模式）

Section titled “流程詳細資訊（本機模式）”

  1. 偵測現有設定

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

  2. Model/Auth

    • Anthropic API 金鑰：如果存在則使用 ANTHROPIC_API_KEY，否則提示輸入金鑰，然後將其儲存以供 daemon 使用。
    • Anthropic Claude CLI：在 macOS 上，入職檢查鑰匙圈項目「Claude Code-credentials」（選擇「始終允許」以免 launchd 啟動時被阻塞）；在 Linux/Windows 上，如果存在則重複使用 ~/.claude/.credentials.json，並將模型選擇切換至 claude-cli/...。
    • Anthropic token (貼上 setup-token)：在任何機器上執行 claude setup-token，然後貼上 token（您可以對其命名；空白 = 預設）。
    • OpenAI Code (Codex) 訂閱：如果 ~/.codex/auth.json 存在，入職可以重複使用它。
    • OpenAI Code (Codex) 訂閱：瀏覽器流程；貼上 code#state。
      • 當模型未設定或 openai/* 時，將 agents.defaults.model 設定為 openai-codex/gpt-5.2。
    • OpenAI API 金鑰：如果存在則使用 OPENAI_API_KEY，否則提示輸入金鑰，然後將其儲存在 auth profiles 中。
    • xAI (Grok) API 金鑰：提示輸入 XAI_API_KEY 並將 xAI 設定為模型提供者。
    • OpenCode：提示輸入 OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY，可在 https://opencode.ai/auth 取得），並讓您選擇 Zen 或 Go 目錄。
    • Ollama：提示輸入 Ollama 基礎 URL，提供 Cloud + Local 或 Local 模式，探索可用的模型，並在需要時自動拉取所選的本機模型。
    • 更多詳情：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。
    • 更多詳情：MiniMax
    • Synthetic (相容 Anthropic)：提示輸入 SYNTHETIC_API_KEY。
    • 更多詳情：Synthetic
    • Moonshot (Kimi K2)：設定會自動寫入。
    • Kimi Coding：設定會自動寫入。
    • 更多詳情：Moonshot AI (Kimi + Kimi Coding)
    • 跳過：尚未設定驗證。
    • 從偵測到的選項中選擇預設模型（或手動輸入提供者/模型）。為了獲得最佳品質並降低 prompt-injection 風險，請選擇您的提供者堆疊中最強大的最新一代模型。
    • 入職會執行模型檢查，如果設定的模型未知或缺少驗證，則會發出警告。
    • API 金鑰儲存模式預設為純文字 auth-profile 值。使用 --secret-input-mode ref 來儲存 env-backed refs（例如 keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }）。
    • OAuth 憑證位於 ~/.openclaw/credentials/oauth.json；auth profiles 位於 `~/.openclaw/agents/

    /agent/auth-profiles.json`（API 金鑰 + OAuth）。 - 更多詳情：/concepts/oauth

  3. Workspace

    • 預設 ~/.openclaw/workspace (可配置)。
    • 播種代理程式啟動儀式所需的工作區檔案。
    • 完整的工作區佈局 + 備份指南：代理程式工作區

  4. Gateway

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

    。 - 需要在入門程序環境中設定非空白的環境變數。 - 無法與 —gateway-token` 結合使用。 - 僅在您完全信任每個本機程序時才停用認證。 - 非回環綁定仍需認證。

  5. Channels

    • WhatsApp：可選的 QR 登入。
    • Telegram：Bot 權杖。
    • Discord：Bot 權杖。
    • Google Chat：服務帳戶 JSON + Webhook 受眾。
    • Mattermost (外掛程式)：Bot 權杖 + 基礎 URL。
    • Signal：可選的 signal-cli 安裝 + 帳戶配置。
    • BlueBubbles：iMessage 的推薦選項；伺服器 URL + 密碼 + Webhook。
    • iMessage：舊版 imsg CLI 路徑 + 資料庫存取權。
    • 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.2 \
  --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 設定 (signal-cli)

Section titled “Signal 設定 (signal-cli)”

入職程序可以從 GitHub 版本安裝 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 設定參考)
  • channels.telegram.botToken, channels.discord.token, channels.matrix.*, 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 或本地路徑）。

相關文件

Section titled “相關文件”