命令列介面設定參考資料

本頁涵蓋逐步的新手引導行為、輸出與內部機制。 如需操作指南，請參閱新手引導（命令列介面）。如需完整的命令列介面旗標 參考資料（每個 --flag、非互動式範例、供應商專屬 命令），請參閱 openclaw onboard。

精靈的功能

本機模式（預設）會引導你完成：

• 模型與驗證設定（Anthropic、OpenAI Code 訂閱 OAuth、xAI、OpenCode、自訂端點，以及更多由供應商管理的驗證流程）
• 工作區位置與啟動檔案
• 閘道設定（連接埠、繫結、驗證、Tailscale）
• 頻道與供應商（Discord、Feishu、Google Chat、iMessage、Mattermost、Microsoft Teams、QQ Bot、Signal、Slack、Telegram、WhatsApp，以及其他隨附或外掛頻道）
• 網頁搜尋供應商（選用）
• 常駐程式安裝（LaunchAgent、systemd 使用者單元，或原生 Windows 排程工作；失敗時改用「啟動」資料夾）
• 健康狀態檢查
• Skills 設定

遠端模式會設定此機器，使其連線至其他位置的閘道。它不會 在遠端主機上安裝或修改任何內容。

本機流程詳細資訊

遠端模式詳細資訊

遠端模式會設定此機器連線到其他位置的閘道。它不會在遠端主機上安裝或修改任何項目。

你需要設定：

• 遠端閘道 URL（ws://... 或 wss://...）
• 權杖、密碼或不使用驗證，須與遠端閘道的設定相符

驗證與模型選項

如果供應商設定步驟在互動式新手設定中失敗（例如選擇重複使用命令列介面，但本機尚未登入），精靈會顯示錯誤並返回供應商選擇器，而不是結束。明確指定 --auth-choice 的執行仍會快速失敗，以便用於自動化。

模型行為：

• 從偵測到的選項中挑選預設模型，或手動輸入供應商與模型。
• 當初始設定從供應商驗證選項開始時，模型選擇器會自動優先顯示 該供應商。對於 Volcengine 和 BytePlus，相同的偏好設定 也會比對其程式設計方案變體（volcengine-plan/*、 byteplus-plan/*）。
• 如果套用該偏好供應商篩選條件後沒有任何結果，選擇器會改用 完整目錄，而不會顯示沒有任何模型。
• 精靈會執行模型檢查，若已設定的模型未知或缺少驗證，便會發出警告。

認證資訊與設定檔路徑：

• 驗證設定檔（API 金鑰 + OAuth）：~/.openclaw/agents/<agentId>/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.<id>.apiKey 儲存為 { source: "env", provider: "default", id: "CUSTOM_API_KEY" }。
  • 在此自訂提供者情況下，--custom-api-key 要求必須設定 CUSTOM_API_KEY；否則初始設定會立即失敗。
• 閘道驗證認證資訊在互動式設定中支援純文字和 SecretRef 選項：
  • 權杖模式：產生／儲存純文字權杖（預設）或 使用 SecretRef。
  • 密碼模式：純文字或 SecretRef。
• 非互動式權杖 SecretRef 路徑：--gateway-token-ref-env <ENV_VAR>。
• 現有的純文字設定可繼續運作，無須變更。

輸出與內部資訊

~/.openclaw/openclaw.json 中的常見欄位：

• agents.defaults.workspace
• 傳入 --skip-bootstrap 時的 agents.defaults.skipBootstrap
• agents.defaults.model / models.providers（如果選擇 Minimax）
• tools.profile（未設定時，本機初始設定預設為 "coding"；既有的明確值會予以保留）
• gateway.*（模式、繫結、驗證、Tailscale）
• session.dmScope（未設定時，本機初始設定會將此項預設為 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/<accountId>/。 作用中的工作階段與逐字記錄儲存在 ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite。 ~/.openclaw/agents/<agentId>/sessions/ 目錄用於舊版遷移 輸入以及封存／支援成品。

非互動式設定

--non-interactive 需要搭配 --accept-risk（確認代理程式功能 強大，且完整系統存取權限具有風險）：

openclaw onboard --non-interactive --accept-risk \  --auth-choice apiKey \  --anthropic-api-key "$ANTHROPIC_API_KEY"

完整旗標參考與供應商特定範例：openclaw onboard、命令列介面自動化。

閘道精靈 RPC

• wizard.start
• wizard.next
• wizard.cancel
• wizard.status

用戶端（macOS 應用程式與控制介面）無須重新實作初始設定邏輯，即可呈現各個步驟。

Signal 設定行為

• 從官方 signal-cli GitHub 發行版本下載適當的發行資產（原生建置，僅限 Linux x86-64）
• 在其他平台（macOS、非 x64 Linux）上，則改透過 Homebrew 安裝
• 將發行資產安裝內容儲存在 ~/.openclaw/tools/signal-cli/<version>/
• 將 channels.signal.cliPath 寫入設定
• 目前尚不支援原生 Windows；請在 WSL2 內執行初始設定，以取得 Linux 安裝路徑

相關文件

• 初始設定中心：初始設定（命令列介面）
• 自動化與指令碼：命令列介面自動化
• 指令參考：openclaw onboard