> ## Documentation Index > Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt > Use this file to discover all available pages before exploring further. # 命令列介面設定參考 本頁涵蓋逐步 onboarding 行為、輸出與內部機制。 如需逐步導覽，請參閱 [Onboarding（命令列介面）](/zh-TW/start/wizard)。如需完整的命令列介面旗標 參考（每個 `--flag`、非互動式範例、供應商特定 命令），請參閱 [`openclaw onboard`](/zh-TW/cli/onboard)。 ## 精靈會做什麼 本機模式（預設）會引導你完成： * 模型與驗證設定（Anthropic、OpenAI Code 訂閱 OAuth、xAI、OpenCode、自訂端點，以及更多由供應商擁有的驗證流程） * 工作區位置與 bootstrap 檔案 * 閘道設定（連接埠、綁定、驗證、Tailscale） * 頻道與供應商（Discord、Feishu、Google Chat、iMessage、Mattermost、Microsoft Teams、QQ Bot、Signal、Slack、Telegram、WhatsApp，以及其他內建或外掛頻道） * 網頁搜尋供應商（選用） * 常駐程式安裝（LaunchAgent、systemd 使用者單元，或原生 Windows 排程工作，並以啟動資料夾作為備援） * 健康檢查 * Skills 設定 遠端模式會設定這台機器連線到其他位置的閘道。它不會 在遠端主機上安裝或修改任何內容。 ## 本機流程細節 * 如果 `~/.openclaw/openclaw.json` 存在，請選擇 **保留目前值**、**檢閱並更新**，或 **設定前重設**。 * 重新執行精靈不會清除任何內容，除非你明確選擇重設（或傳入 `--reset`）。 * 命令列介面 `--reset` 預設為 `config+creds+sessions`；使用 `--reset-scope full` 也會移除工作區。 * 如果設定無效或包含舊版鍵，精靈會停止並要求你先執行 `openclaw doctor` 再繼續。 * 重設會將狀態移到垃圾桶（絕不直接刪除），並提供範圍： * 僅設定 * 設定 + 認證 + 工作階段 * 完整重設（也會移除工作區） * 完整選項矩陣位於 [驗證與模型選項](#auth-and-model-options)。 * 預設 `~/.openclaw/workspace`（可設定）。 * 植入首次執行 bootstrap 所需的工作區檔案。 * 工作區配置：[代理工作區](/zh-TW/concepts/agent-workspace)。 * 提示輸入連接埠、綁定、驗證模式與 Tailscale 暴露設定。 * 建議：即使是 loopback 也保持權杖驗證啟用，讓本機 WS 用戶端必須驗證。 * 在權杖模式中，互動式設定提供： * **產生/儲存純文字權杖**（預設） * **使用 SecretRef**（選用） * 在密碼模式中，互動式設定也支援純文字或 SecretRef 儲存。 * 非互動式權杖 SecretRef 路徑：`--gateway-token-ref-env `。 * onboarding 程序環境中必須有非空的環境變數。 * 不能與 `--gateway-token` 合併使用。 * 只有在你完全信任每個本機程序時才停用驗證。 * 非 loopback 綁定仍需要驗證。 * [WhatsApp](/zh-TW/channels/whatsapp)：選用 QR 登入 * [Telegram](/zh-TW/channels/telegram)：Bot 權杖 * [Discord](/zh-TW/channels/discord)：Bot 權杖 * [Google Chat](/zh-TW/channels/googlechat)：服務帳戶 JSON + 網路鉤子 audience * [Mattermost](/zh-TW/channels/mattermost)：Bot 權杖 + 基底 URL * [Signal](/zh-TW/channels/signal)：選用 `signal-cli` 安裝 + 帳戶設定 * [iMessage](/zh-TW/channels/imessage)：`imsg` 命令列介面路徑 + Messages DB 存取；當閘道在非 Mac 上執行時，請使用 SSH wrapper * DM 安全性：預設為配對。第一則 DM 會傳送代碼；透過 `openclaw pairing approve ` 核准，或使用允許清單。 * 選擇供應商（Brave、DuckDuckGo、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Ollama Web Search、Perplexity、SearXNG、Tavily）或略過。 * 使用 `--skip-search` 略過此步驟；稍後可用 `openclaw configure --section web` 重新設定。 * macOS：LaunchAgent * 需要已登入的使用者工作階段；若為 headless，請使用自訂 LaunchDaemon（未隨附）。 * Linux 與透過 WSL2 的 Windows：systemd 使用者單元 * 精靈會嘗試 `loginctl enable-linger `，讓閘道在登出後保持執行。 * 可能提示 sudo（寫入 `/var/lib/systemd/linger`）；它會先嘗試不使用 sudo。 * 原生 Windows：優先使用排程工作 * 如果建立工作遭拒，OpenClaw 會退回每位使用者的啟動資料夾登入項目，並立即啟動閘道。 * 排程工作仍是偏好的方式，因為它們提供更好的 supervisor 狀態。 * 執行階段選擇：互動式只提供節點。Bun 在 WhatsApp/Telegram 重新連線時可能造成記憶體毀損，且不是這些頻道支援的常駐程式執行階段；只有在該組合之外才傳入 `--daemon-runtime bun`。 * 啟動閘道（如有需要）並執行 `openclaw health`。 * `openclaw status --deep` 會將即時閘道健康探測加入狀態輸出，包含支援時的頻道探測。 * 讀取可用的 Skills 並檢查需求。 * 讓你選擇節點管理器：npm、pnpm 或 bun。 * 當所需 安裝器可用時，為受信任的內建 Skills 安裝選用依賴。 * 略過不可用的 Homebrew、uv 與 Go 安裝器，然後將受影響的 Skills 分組並提供手動設定指引。安裝缺少的先決條件後，執行 `openclaw doctor`。 * 摘要與後續步驟，包含 iOS、Android 與 macOS app 選項。 如果未偵測到 GUI，精靈會列印 Control UI 的 SSH 連接埠轉送指示，而不是開啟瀏覽器。 如果缺少 Control UI 資產，精靈會嘗試建置它們；備援是 `pnpm ui:build`（會自動安裝 UI 依賴）。 ## 遠端模式細節 遠端模式會設定這台機器連線到其他位置的閘道。它不會 在遠端主機上安裝或修改任何內容。 你會設定： * 遠端閘道 URL（`ws://...` 或 `wss://...`） * 權杖、密碼或無驗證，與遠端閘道的設定相符 如果 `dns-sd`（macOS）或 `avahi-browse`（Linux）可用，onboarding 會在退回手動輸入 URL 前，提供搜尋 Bonjour/mDNS 閘道 beacon 的選項。 設定後也會嘗試廣域 DNS-SD 探索。文件：[閘道探索](/zh-TW/gateway/discovery)、[Bonjour](/zh-TW/gateway/bonjour)。 選取 beacon 時，請選擇直接 WebSocket 或 SSH tunnel： * **直接**：透過 `wss://` 連線，並提示信任探索到的 TLS 指紋（首次使用信任釘選；只有在你接受時才會釘選）。 * **SSH tunnel**：列印要先執行的 `ssh -N -L 18789:127.0.0.1:18789 @` 命令，然後連線到本機 tunnel 端點。 選擇權杖（建議）、密碼或無驗證，然後選擇性地將其儲存 為 SecretRef，而不是純文字。 如果閘道僅限 loopback 且無法探索，請手動使用 SSH tunneling 或 tailnet。 純文字 `ws://` 可用於 loopback、私有 IP 字面值、`.local` 與 Tailnet `*.ts.net` URL；其他私有 DNS 名稱需要 `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`。 ## 驗證與模型選項 如果存在則使用 `ANTHROPIC_API_KEY`，否則提示輸入金鑰，然後儲存以供常駐程式使用。 互動式 onboarding/configure 中偏好的本機路徑；可用時會重用現有 Claude 命令列介面登入。 瀏覽器流程；貼上 `code#state`。 當模型未設定或已是 OpenAI 系列時，透過 Codex 執行階段將 `agents.defaults.model` 設為 `openai/gpt-5.5`。 使用短效裝置代碼的瀏覽器配對流程。 當模型未設定或已是 OpenAI 系列時，透過 Codex 執行階段將 `agents.defaults.model` 設為 `openai/gpt-5.5`。 如果存在則使用 `OPENAI_API_KEY`，否則提示輸入金鑰，然後將認證儲存在驗證設定檔中。 當模型未設定、為 `openai/*`，或為舊版 Codex 模型參照時，將 `agents.defaults.model` 設為 `openai/gpt-5.5`。 適用於符合資格的 SuperGrok 或 X Premium 帳戶的瀏覽器登入。這是多數使用者 建議的 xAI 路徑。OpenClaw 會儲存產生的驗證 設定檔，用於 Grok 模型、Grok `web_search`、`x_search` 與 `code_execution`。 使用短代碼而非 localhost callback 的遠端友善瀏覽器登入。請在 SSH、Docker 或 VPS 主機上使用此方式。 提示輸入 `XAI_API_KEY`，並將 xAI 設定為模型供應商。當你想使用 xAI Console API key 而非訂閱 OAuth 時，請使用此方式。 提示輸入 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`），並讓你選擇 Zen 或 Go 目錄（一個 API key 涵蓋兩者）。 設定 URL：[opencode.ai/auth](https://opencode.ai/auth)。 為你儲存金鑰。 提示輸入 `AI_GATEWAY_API_KEY`。 更多細節：[Vercel AI Gateway](/zh-TW/providers/vercel-ai-gateway)。 提示輸入帳戶 ID、閘道 ID 與 `CLOUDFLARE_AI_GATEWAY_API_KEY`。 更多細節：[Cloudflare AI Gateway](/zh-TW/providers/cloudflare-ai-gateway)。 設定會自動寫入。託管預設值為 `MiniMax-M3`；API key 設定使用 `minimax/...`，OAuth 設定使用 `minimax-portal/...`。 更多細節：[MiniMax](/zh-TW/providers/minimax)。 設定會為中國或全球端點上的 StepFun standard 或 Step Plan 自動寫入。 Standard 目前包含 `step-3.5-flash`，Step Plan 也包含 `step-3.5-flash-2603`。 更多細節：[StepFun](/zh-TW/providers/stepfun)。 提示輸入 `SYNTHETIC_API_KEY`。 更多細節：[Synthetic](/zh-TW/providers/synthetic)。 先提示選擇 `Cloud + Local`、`Cloud only` 或 `Local only`。 `Cloud only` 使用 `OLLAMA_API_KEY` 搭配 `https://ollama.com`。 主機支援的模式會提示輸入基底 URL（預設 `http://127.0.0.1:11434`）、探索可用模型，並建議預設值。 `Cloud + Local` 也會檢查該 Ollama 主機是否已登入以取得雲端存取。 更多細節：[Ollama](/zh-TW/providers/ollama)。 Moonshot（Kimi K2）與 Kimi Coding 設定會自動寫入。 更多細節：[Moonshot AI（Kimi + Kimi Coding）](/zh-TW/providers/moonshot)。 可搭配 OpenAI-compatible、OpenAI Responses-compatible 與 Anthropic-compatible 端點運作。 互動式 onboarding 支援與其他供應商 API key 流程相同的 API key 儲存選項： * **立即貼上 API key**（純文字） * **使用 secret reference**（環境 ref 或已設定的供應商 ref，並進行 preflight 驗證） Onboarding 會為常見 vision 模型 ID（GPT-4o/4.1/5.x、Claude 3/4、Gemini、Qwen-VL、LLaVA、Pixtral 及類似模型）推斷影像支援，且只有在模型名稱未知時才詢問。 非互動式旗標： * `--auth-choice custom-api-key` * `--custom-base-url` * `--custom-model-id` * `--custom-api-key`（選用；會退回使用 `CUSTOM_API_KEY`） * `--custom-provider-id`（選用） * `--custom-compatibility `（選用；預設為 `openai`） * `--custom-image-input` / `--custom-text-input`（選用；覆寫推斷出的模型輸入能力） 保持驗證未設定。 模型行為： * 從偵測到的選項中挑選預設模型，或手動輸入提供者和模型。 * 當上手流程從提供者驗證選擇開始時，模型選擇器會自動偏好 該提供者。對於 Volcengine 和 BytePlus，同一個偏好 也會匹配它們的 coding-plan 變體（`volcengine-plan/*`、 `byteplus-plan/*`）。 * 如果該偏好提供者篩選結果為空，選擇器會改為退回使用 完整目錄，而不是不顯示任何模型。 * 精靈會執行模型檢查，並在設定的模型未知或缺少驗證時發出警告。 憑證與設定檔路徑： * 驗證設定檔（API 金鑰 + OAuth）：`~/.openclaw/agents//agent/auth-profiles.json` * 舊版 OAuth 匯入：`~/.openclaw/credentials/oauth.json` 憑證儲存模式： * 預設上手流程行為會將 API 金鑰以純文字值保存到驗證設定檔中。 * `--secret-input-mode ref` 會啟用參照模式，而不是純文字金鑰儲存。 在互動式設定中，你可以選擇以下任一項： * 環境變數參照（例如 `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`） * 已設定的提供者參照（`file` 或 `exec`），包含提供者別名 + id * 互動式參照模式會在儲存前執行快速預檢驗證。 * 環境參照：驗證目前上手流程環境中的變數名稱 + 非空值。 * 提供者參照：驗證提供者設定並解析要求的 id。 * 如果預檢失敗，上手流程會顯示錯誤並讓你重試。 * 在非互動式模式中，`--secret-input-mode ref` 僅由環境支援。 * 在上手流程處理程序環境中設定提供者環境變數。 * 內嵌金鑰旗標（例如 `--openai-api-key`）要求該環境變數已設定；否則上手流程會快速失敗。 * 對於自訂提供者，非互動式 `ref` 模式會將 `models.providers..apiKey` 儲存為 `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`。 * 在該自訂提供者情況下，`--custom-api-key` 要求 `CUSTOM_API_KEY` 已設定；否則上手流程會快速失敗。 * 閘道驗證憑證在互動式設定中支援純文字和 SecretRef 選擇： * 權杖模式：**產生/儲存純文字權杖**（預設）或 **使用 SecretRef**。 * 密碼模式：純文字或 SecretRef。 * 非互動式權杖 SecretRef 路徑：`--gateway-token-ref-env `。 * 現有純文字設定會照常繼續運作。 無頭與伺服器提示：在有瀏覽器的機器上完成 OAuth，然後將 該代理的 `auth-profiles.json`（例如 `~/.openclaw/agents//agent/auth-profiles.json`，或相符的 `$OPENCLAW_STATE_DIR/...` 路徑）複製到閘道主機。`credentials/oauth.json` 只是舊版匯入來源。 ## 輸出與內部項目 `~/.openclaw/openclaw.json` 中的典型欄位： * `agents.defaults.workspace` * 傳入 `--skip-bootstrap` 時的 `agents.defaults.skipBootstrap` * `agents.defaults.model` / `models.providers`（如果選擇 Minimax） * `tools.profile`（local 上手流程在未設定時預設為 `"coding"`；現有明確值會保留） * `gateway.*`（模式、繫結、驗證、tailscale） * `session.dmScope`（local 上手流程在未設定時會將此預設為 `per-channel-peer`；現有明確值會保留） * `channels.telegram.botToken`、`channels.discord.token`、`channels.matrix.*`、`channels.signal.*`、`channels.imessage.*` * 當你在提示中選擇加入時的頻道允許清單（Discord、iMessage、Signal、Slack、Telegram、WhatsApp）；Discord 和 Slack 也會將輸入的名稱解析為 ID * `skills.install.nodeManager` * `setup --node-manager` 旗標接受 `npm`、`pnpm` 或 `bun`。 * 手動設定稍後仍可設定 `skills.install.nodeManager: "yarn"`。 * `wizard.lastRunAt` * `wizard.lastRunVersion` * `wizard.lastRunCommit` * `wizard.lastRunCommand` * `wizard.lastRunMode` * `wizard.securityAcknowledgedAt` `openclaw agents add` 會寫入 `agents.list[]` 和選用的 `bindings`。 WhatsApp 憑證會放在 `~/.openclaw/credentials/whatsapp//` 底下。 工作階段會儲存在 `~/.openclaw/agents//sessions/` 底下。 部分頻道是以外掛形式提供。當在設定期間選取時，精靈會 在頻道設定前提示安裝外掛（npm 或本機路徑）。 ## 非互動式設定 `--non-interactive` 需要 `--accept-risk`（確認代理很強大， 且完整系統存取具有風險）： ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw onboard --non-interactive --accept-risk \ --auth-choice apiKey \ --anthropic-api-key "$ANTHROPIC_API_KEY" ``` 完整旗標參考與提供者特定範例：[`openclaw onboard`](/zh-TW/cli/onboard)、[命令列介面自動化](/zh-TW/start/wizard-cli-automation)。 ## 閘道精靈 RPC * `wizard.start` * `wizard.next` * `wizard.cancel` * `wizard.status` 用戶端（macOS app 和控制 UI）可以呈現步驟，而不需要重新實作上手流程邏輯。 ## Signal 設定行為 * 從官方 `signal-cli` GitHub releases 下載適當的發行資產（原生建置，僅限 Linux x86-64） * 在其他平台（macOS、非 x64 Linux）上，改用 Homebrew 安裝 * 將發行資產安裝儲存在 `~/.openclaw/tools/signal-cli//` 底下 * 在設定中寫入 `channels.signal.cliPath` * 尚未支援原生 Windows；請在 WSL2 內執行上手流程，以取得 Linux 安裝路徑 ## 相關文件 * 上手流程中心：[上手流程（命令列介面）](/zh-TW/start/wizard) * 自動化與指令碼：[命令列介面自動化](/zh-TW/start/wizard-cli-automation) * 命令參考：[`openclaw onboard`](/zh-TW/cli/onboard)