OpenClaw Onboarding Wizard 參考指南

設定開發環境通常很瑣碎。你可能需要手動處理各種 API key 和配置檔，這過程既無聊又容易出錯。

與其浪費時間在這些重複的步驟上，不如把力氣花在編寫核心邏輯。這就是為什麼我們開發了引導工具，幫你自動化處理這些繁瑣的配置流程。

需要準備的東西

在開始之前，請確保你已經準備好：

安裝好 OpenClaw CLI

快速開始

如果你想快速開始，只需在你的終端機執行以下指令：

openclaw onboard

這個 CLI 工具會引導你完成所有必要的設定步驟，確保你的環境配置正確。

疑難排解

目前源文件未列出具體的錯誤處理方案。如果你在執行過程中遇到問題，建議參考下方的 AI Setup Assistant 獲取即時協助。

如果你有任何關於配置的疑問，可以直接詢問我們的 AI Setup Assistant。

下一步

Onboarding Wizard 概覽

每次安裝新的開發工具，最怕的就是設定檔打架，或是漏掉某個環境變數導致程式跑不起來。你可能遇過那種手動改了半天 .env 結果還是報錯的窘境，最後只能把資料夾砍掉重練。OpenClaw 的初始化精靈（Wizard）就是為了幫你搞定這些瑣事，這篇會帶你走一遍本地模式的完整流程，讓你清楚知道每一步到底在改什麼。

需要準備的東西

在開始之前，請確保你已經準備好以下內容（根據源文件需求）：

Node.js: 推薦的執行環境（注意：不推薦使用 Bun）
API Key: 至少一個支援的供應商（Anthropic, OpenAI, xAI 等）
權限: 如果你在 Linux 上且需要背景執行，可能需要 sudo 權限來開啟 lingering
現有配置: 如果你之前裝過，精靈會自動偵測 ~/.openclaw/openclaw.json

快速開始

這個初始化精靈旨在讓你 5 分鐘內完成配置。你可以按照以下步驟進行：

1. 偵測現有配置

如果偵測到 ~/.openclaw/openclaw.json，你可以選擇 Keep / Modify / Reset。除非你明確選擇 Reset 或在執行時加上 --reset 參數，否則精靈不會刪除任何內容。

使用 --reset 預設會清除 config+creds+sessions。
使用 --reset-scope full 會連同 workspace 一併刪除。
所有的刪除操作都會使用 trash 而非 rm，確保安全。
如果設定檔無效或包含舊版 Key，精靈會要求你先執行 openclaw doctor。

2. 模型與認證 (Model/Auth)

這是最關鍵的一步，精靈支援多種方式獲取你的 API Key：

Anthropic: 優先讀取 ANTHROPIC_API_KEY 環境變數，或手動貼上 API Key。
Anthropic OAuth (Claude Code CLI):
- macOS：檢查 Keychain 中的 “Claude Code-credentials”（記得選「永遠允許」避免 launchd 啟動被擋）。
- Linux/Windows：複用 ~/.claude/.credentials.json。
OpenAI Code (Codex): 支援複用 ~/.codex/auth.json 或透過瀏覽器 OAuth 流程（貼上 code#state）。
其他供應商: 支援 xAI (Grok), Moonshot (Kimi), MiniMax, Synthetic 等。
Gateway 代理: 支援 Vercel AI Gateway 或 Cloudflare AI Gateway（需提供 Account ID 與 Gateway ID）。

小撇步：API Key 預設以明文儲存在 auth-profile 中。如果你想改用環境變數參照，請使用 --secret-input-mode ref。

3. 工作區 (Workspace)

預設路徑為 ~/.openclaw/workspace。精靈會在這裡產生 Agent 啟動所需的初始檔案。

4. Gateway 設定

你需要設定 Port、繫結位址（bind）以及認證模式。

認證建議：即使是本地 loopback 連線，也建議保持 Token 模式。
Token 設定：支援產生明文 Token 或使用 SecretRef。
非互動模式：可以使用 --gateway-token-ref-env <ENV_VAR> 來指定環境變數。

5. 通訊頻道 (Channels)

你可以選擇要開啟的溝通管道：

WhatsApp: 透過 QR code 登入。
Telegram / Discord: 貼上你的 bot token。
BlueBubbles: 如果你要在 iMessage 上使用，這是推薦方案。
DM 安全性：預設使用配對模式。第一個 DM 會發送代碼，你必須執行 openclaw pairing approve <channel> <code> 來核准。

6. 網頁搜尋

選擇搜尋供應商（Perplexity, Brave, Gemini, Grok 或 Kimi）。如果你想跳過，可以使用 --skip-search。

7. Daemon 安裝與健康檢查

macOS: 使用 LaunchAgent（需要使用者登入）。
Linux: 使用 systemd user unit，精靈會嘗試執行 loginctl enable-linger 確保登出後 Gateway 依然運作。
健康檢查: 安裝完成後會自動執行 openclaw health。你可以用 openclaw status --deep 查看詳細的 Gateway 探針狀態。

8. Skills 與完成

精靈會讀取可用 Skill 並檢查環境需求，你可以選擇 npm 或 pnpm 作為 Node 模組管理工具。最後，你會看到一份總結，並附上 iOS/Android/macOS App 的下載連結。

疑難排解

配置衝突: 如果遇到舊版 key 導致精靈停止，請執行 openclaw doctor 修復。
OAuth 失敗: 如果你在沒有瀏覽器的伺服器（Headless）上操作，請在有瀏覽器的電腦完成 OAuth 後，將 ~/.openclaw/credentials/oauth.json 複製到伺服器。
Daemon 啟動被擋: 在 macOS 上，如果出現 Keychain 存取提示，請務必選擇「永遠允許」。
UI 檔案缺失: 如果找不到 Control UI 資源，精靈會嘗試執行 pnpm ui:build 自動構建。

如果你在設定過程中遇到任何奇怪的問題，或是想了解更進階的配置，可以隨時詢問我們的 AI Setup Assistant。

下一步

每次在新的伺服器或環境部署工具時，最煩人的就是得盯著螢幕回答一堆 CLI 的互動問題。如果你正試圖將 OpenClaw 整合到 CI/CD 流程，或是想寫個腳本一鍵搞定環境建置，手動輸入顯然不是個好選擇。

我們開發了 Non-interactive mode，讓你直接透過 CLI flags 傳遞所有配置，讓自動化流程跑起來更順手。

需要準備的東西

在開始之前，請確保你已經準備好以下項目（根據源文件需求）：

已安裝 OpenClaw CLI
對應 AI 模型的 API Key（如 Anthropic, Gemini 等）
Node.js（如果你需要安裝 daemon）

快速開始

要在腳本中自動完成 onboarding，只需加上 --non-interactive 參數。這是一個使用 Anthropic API 的典型範例：

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

在自動化模式下，你可以選擇直接傳入 token，或是引用環境變數。請注意，--gateway-token 與 --gateway-token-ref-env 是互斥的，你只能擇一使用：

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

各大模型供應商配置範例

根據你的需求，可以參考以下不同 Provider 的自動化指令：

Gemini:

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

Z.AI:

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

Vercel AI Gateway:

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

Cloudflare AI Gateway:

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

Moonshot:

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

Synthetic:

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

OpenCode Zen:

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

自動化新增 Agent

除了初始配置，你也可以在非互動模式下直接新增 Agent。這對於需要快速擴展多個工作空間的情況非常有用：

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

疑難排解

問題：我加了 --json 參數，但 CLI 還是跳出互動問題。 解決方案： 請記住 --json 並不等同於非互動模式。如果你是在腳本中使用，必須同時加上 --non-interactive（建議也加上 --workspace）來確保流程不會被中斷。

問題：同時設定了 --gateway-token 和 --gateway-token-ref-env 導致報錯。 解決方案： 這兩個參數是互斥的。請決定是要直接在指令中傳入 token，還是透過環境變數名稱來引用。

如果你在配置過程中遇到其他問題，可以詢問我們的 AI Setup Assistant。

下一步

每次開發新工具，最讓人頭痛的就是處理環境依賴和初始化設定。如果你正在為 Gateway 開發 UI（例如 macOS App 或控制台介面），你肯定不想在每個客戶端都重新寫一遍下載、解壓縮和配置環境變數的邏輯。這類重複性的工作不僅容易出錯，還會讓維護成本翻倍。

我推薦直接使用 Gateway 內建的 wizard RPC 介面。這套機制把複雜的安裝邏輯封裝在後端，你只需要呼叫幾個 API 就能引導用戶完成設定，這絕對是開發用戶端介面的最佳實踐。

需要準備的東西

在開始使用 wizard 處理 Signal 設定前，請確保你的環境滿足以下條件：

Java 21: 如果你打算使用 JVM 版本，這是硬性要求。
WSL2: Windows 用戶必須在 WSL2 環境下執行，安裝流程會比照 Linux 模式。

快速開始

Gateway 透過 RPC 暴露了完整的 wizard 流程，讓你可以直接控制安裝步驟。

1. 使用 RPC 控制流程

你可以透過以下四個 RPC 方法來驅動初始化精靈，無需在你的 App 裡重新實作邏輯：

wizard.start: 啟動設定流程。
wizard.next: 進入下一個步驟。
wizard.cancel: 取消目前的設定。
wizard.status: 獲取當前進度狀態。

這樣一來，不論是 macOS App 還是 Web UI，都能呈現一致的安裝體驗。

2. 自動化 Signal 設定 (signal-cli)

當你透過 wizard 進行 Signal 設定時，它會自動執行以下操作：

從 GitHub releases 下載適合你系統架構的 signal-cli 資源。
將檔案儲存在 ~/.openclaw/tools/signal-cli/<version>/ 路徑下。
自動將路徑寫入你的設定檔中的 channels.signal.cliPath 欄位。

Gateway 會優先嘗試使用 Native 版本以獲得更好的效能；如果沒有對應的 Native 版本，則會回退到 JVM 版本。

疑難排解

在設定過程中，你可能會遇到以下狀況：

Java 版本不相容: 如果你發現 signal-cli 無法啟動且你使用的是 JVM 版本，請檢查系統是否安裝了 Java 21。
Windows 路徑問題: 記得 Windows 環境必須透過 WSL2 執行，所有的 signal-cli 安裝流程都會在 WSL 內部完成，不要嘗試在原生 Windows 命令行執行。

如果你在設定過程中遇到其他問題，可以直接詢問 AI Setup Assistant 獲取即時幫助。

下一步

每次執行設定嚮導（Wizard）時，你是不是也會擔心它到底在你的系統裡改了什麼？是把檔案亂塞在奇怪的資料夾，還是偷偷改了你不知道的參數？

搞清楚設定檔的內容對開發者來說非常重要，這能讓你更輕鬆地進行手動微調或排查問題。這篇文章會幫你拆解 OpenClaw Wizard 在執行過程中，具體寫入了哪些欄位與路徑。

需要準備的東西

已安裝 OpenClaw
對 ~/.openclaw/ 目錄的讀取權限

快速開始

當你執行 Wizard 時，主要的設定都會集中在 ~/.openclaw/openclaw.json 這個檔案中。以下是它會寫入的核心欄位：

核心設定與 Agent 預設值

agents.defaults.workspace：定義 Agent 的工作空間。
agents.defaults.model / models.providers：如果你選擇了 Minimax，Wizard 會在這裡設定對應的 Provider。
tools.profile：如果你沒有特別設定，系統預設會使用 "coding"。如果你已經有明確的設定值，Wizard 會保留它。
skills.install.nodeManager：指定用於安裝 Skill 的 Node.js 套件管理器。

Gateway 與連線設定

gateway.*：這裡包含了 mode、bind、auth 和 tailscale 等 Gateway 相關配置。
session.dmScope：定義私訊作用域的行為細節，具體邏輯可以參考 CLI Onboarding Reference。

Channel 通訊管道設定

Wizard 會幫你填入各個通訊平台的憑證，例如：

channels.telegram.botToken
channels.discord.token
channels.signal.*
channels.imessage.*
Allowlists：如果你在提示中選擇加入，Wizard 會設定 Slack、Discord、Matrix 或 Microsoft Teams 的允許清單（名稱會盡可能解析為 ID）。

Wizard 執行紀錄

為了追蹤進度，Wizard 會留下一些後設資料（Metadata）：

wizard.lastRunAt
wizard.lastRunVersion
wizard.lastRunCommit
wizard.lastRunCommand
wizard.lastRunMode

檔案路徑與目錄結構

除了 JSON 檔案，有些資料會存放在特定的目錄下：

Agent 列表：使用 openclaw agents add 時，會寫入 agents.list[] 以及選填的 bindings。
WhatsApp 憑證：存放在 ~/.openclaw/credentials/whatsapp/<accountId>/。
Session 紀錄：存放在 ~/.openclaw/agents/<agentId>/sessions/。

疑難排解

找不到某些 Channel 的設定選項？

有些 Channel 是以 plugin 形式提供的。當你在 Onboarding 過程中選擇這些 Channel 時，Wizard 會提示你先安裝它（透過 npm 或指定本地路徑），安裝完成後才能進行後續設定。

如果你需要更即時的協助，可以詢問 AI Setup Assistant。

下一步

Onboarding Wizard 總覽
macOS App 入門指南
Gateway 設定參考
Providers 詳細設定：WhatsApp, Telegram, Discord, Google Chat, Signal, BlueBubbles (iMessage), iMessage (Legacy)
Skills 擴充：Skills 介紹, Skills 設定

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。