> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 入門引導精靈參考

# 入門引導精靈參考

這是 `openclaw onboard` CLI 精靈的完整參考。
如需高層概覽，請參閱 [入門引導精靈](/start/wizard)。

## 流程細節（本機模式）

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

  <Step title="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](https://opencode.ai/auth) 取得）。
    * **API 金鑰**：為你儲存金鑰。
    * **Vercel AI Gateway（多模型代理）**：提示輸入 `AI_GATEWAY_API_KEY`。
    * 更多細節：[Vercel AI Gateway](/providers/vercel-ai-gateway)
    * **Cloudflare AI Gateway**：提示輸入 Account ID、Gateway ID 與 `CLOUDFLARE_AI_GATEWAY_API_KEY`。
    * 更多細節：[Cloudflare AI Gateway](/providers/cloudflare-ai-gateway)
    * **MiniMax M2.1**：設定會自動寫入。
    * 更多細節：[MiniMax](/providers/minimax)
    * **Synthetic（相容 Anthropic）**：提示輸入 `SYNTHETIC_API_KEY`。
    * 更多細節：[Synthetic](/providers/synthetic)
    * **Moonshot（Kimi K2）**：設定會自動寫入。
    * **Kimi Coding**：設定會自動寫入。
    * 更多細節：[Moonshot AI（Kimi + Kimi Coding）](/providers/moonshot)
    * **Skip**：尚未設定任何驗證。
    * 從偵測到的選項中選擇預設模型（或手動輸入 provider/model）。
    * 精靈會執行模型檢查，若設定的模型未知或缺少驗證，會顯示警告。
    * OAuth 憑證位於 `~/.openclaw/credentials/oauth.json`；驗證設定檔位於 `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`（API 金鑰 + OAuth）。
    * 更多說明：[/concepts/oauth](/concepts/oauth)

    <Note>
      無頭／伺服器提示：請在有瀏覽器的機器上完成 OAuth，然後將
      `~/.openclaw/credentials/oauth.json`（或 `$OPENCLAW_STATE_DIR/credentials/oauth.json`）複製到
      Gateway 主機。
    </Note>
  </Step>

  <Step title="Workspace">
    * 預設為 `~/.openclaw/workspace`（可設定）。
    * 產生代理程式啟動流程所需的工作區檔案。
    * 完整工作區配置與備份指南：[代理程式工作區](/concepts/agent-workspace)
  </Step>

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

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

  <Step title="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。
  </Step>

  <Step title="Health check">
    * 啟動 Gateway（如有需要）並執行 `openclaw health`。
    * 提示：`openclaw status --deep` 會在狀態輸出中加入 gateway 健康探測（需要可連線的 gateway）。
  </Step>

  <Step title="Skills (recommended)">
    * 讀取可用的 Skills 並檢查需求。
    * 讓你選擇 node 管理工具：**npm / pnpm**（不建議使用 bun）。
    * 安裝選用相依套件（部分在 macOS 上使用 Homebrew）。
  </Step>

  <Step title="Finish">
    * 摘要與後續步驟，包括 iOS/Android/macOS 應用程式以啟用額外功能。
  </Step>
</Steps>

<Note>
  若未偵測到 GUI，精靈會顯示 Control UI 的 SSH 連接埠轉送指示，而非開啟瀏覽器。
  若缺少 Control UI 資產，精靈會嘗試建置；備援指令為 `pnpm ui:build`（會自動安裝 UI 相依套件）。
</Note>

## 非互動模式

使用 `--non-interactive` 來自動化或以指令碼進行入門：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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` 以取得機器可讀的摘要。

<Note>
  `--json` **不**代表非互動模式。請在指令碼中使用 `--non-interactive`（以及 `--workspace`）。
</Note>

<AccordionGroup>
  <Accordion title="Gemini example">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw onboard --non-interactive \
      --mode local \
      --auth-choice gemini-api-key \
      --gemini-api-key "$GEMINI_API_KEY" \
      --gateway-port 18789 \
      --gateway-bind loopback
    ```
  </Accordion>

  <Accordion title="Z.AI example">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw onboard --non-interactive \
      --mode local \
      --auth-choice zai-api-key \
      --zai-api-key "$ZAI_API_KEY" \
      --gateway-port 18789 \
      --gateway-bind loopback
    ```
  </Accordion>

  <Accordion title="Vercel AI Gateway example">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    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
    ```
  </Accordion>

  <Accordion title="Cloudflare AI Gateway example">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    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
    ```
  </Accordion>

  <Accordion title="Moonshot example">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw onboard --non-interactive \
      --mode local \
      --auth-choice moonshot-api-key \
      --moonshot-api-key "$MOONSHOT_API_KEY" \
      --gateway-port 18789 \
      --gateway-bind loopback
    ```
  </Accordion>

  <Accordion title="Synthetic example">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw onboard --non-interactive \
      --mode local \
      --auth-choice synthetic-api-key \
      --synthetic-api-key "$SYNTHETIC_API_KEY" \
      --gateway-port 18789 \
      --gateway-bind loopback
    ```
  </Accordion>

  <Accordion title="OpenCode Zen example">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw onboard --non-interactive \
      --mode local \
      --auth-choice opencode-zen \
      --opencode-zen-api-key "$OPENCODE_API_KEY" \
      --gateway-port 18789 \
      --gateway-bind loopback
    ```
  </Accordion>
</AccordionGroup>

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 或本機路徑），然後才能進行設定。

## Related docs

* 精靈概覽：[入門引導精靈](/start/wizard)
* macOS 應用程式入門：[入門](/start/onboarding)
* 設定參考：[Gateway 設定](/gateway/configuration)
* 提供者：[WhatsApp](/channels/whatsapp)、[Telegram](/channels/telegram)、[Discord](/channels/discord)、[Google Chat](/channels/googlechat)、[Signal](/channels/signal)、[BlueBubbles](/channels/bluebubbles)（iMessage）、[iMessage](/channels/imessage)（舊版）
* Skills：[Skills](/tools/skills)、[Skills 設定](/tools/skills-config)