English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisहिन्दीالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiРусскийفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

CLI commands

入門設定

openclaw onboard

用於本機或遠端閘道設定的完整引導式初始設定。當你想讓 OpenClaw 在同一個流程中逐步完成模型驗證、工作區、閘道、頻道、Skills 與健康狀態檢查時，請使用此指令。

相關指南

命令列介面初始設定中心

互動式命令列介面流程逐步說明。
初始設定概覽

OpenClaw 初始設定如何互相銜接。
命令列介面設定參考

輸出、內部機制與各步驟行為。
命令列介面自動化

非互動式旗標與指令碼化設定。
macOS 應用程式初始設定

macOS 選單列應用程式的初始設定流程。

範例

bash
openclaw onboardopenclaw onboard --modernopenclaw onboard --flow quickstartopenclaw onboard --flow manualopenclaw onboard --flow importopenclaw onboard --import-from hermes --import-source ~/.hermesopenclaw onboard --skip-bootstrapopenclaw onboard --mode remote --remote-url wss://gateway-host:18789

--flow import 會使用外掛擁有的遷移提供者，例如 Hermes。它只會針對全新的 OpenClaw 設定執行；如果已有設定、憑證、工作階段或工作區記憶/身分檔案，請先重設或選擇全新的設定再匯入。

--modern 會啟動 Crestodian 對話式初始設定預覽。不使用 --modern 時，openclaw onboard 會保留傳統初始設定流程。

在全新安裝中，如果作用中的設定檔不存在，或沒有任何已編寫的 設定（空白或只有中繼資料），單獨執行 openclaw 也會啟動傳統 初始設定流程。設定檔一旦有已編寫的設定，單獨執行 openclaw 就會改為開啟 Crestodian。

明文 ws:// 可用於 local loopback、私人 IP 字面值、.local 與 Tailnet *.ts.net 閘道 URL。對於其他受信任的私人 DNS 名稱，請在 初始設定程序環境中設定 OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1。

地區設定

互動式初始設定會使用命令列介面精靈地區設定來顯示固定設定文案。解析 順序如下：

  1. OPENCLAW_LOCALE
  2. LC_ALL
  3. LC_MESSAGES
  4. LANG
  5. 英文備援

支援的精靈地區設定為 en、zh-CN 與 zh-TW。地區設定值可使用 底線或 POSIX 後綴形式，例如 zh_CN.UTF-8。產品名稱、指令 名稱、設定鍵、URL、提供者 ID、模型 ID，以及外掛/頻道標籤 會保持原樣。

範例：

bash
OPENCLAW_LOCALE=zh-CN openclaw onboard

非互動式自訂提供者：

bash
openclaw onboard --non-interactive \  --auth-choice custom-api-key \  --custom-base-url "https://llm.example.com/v1" \  --custom-model-id "foo-large" \  --custom-api-key "$CUSTOM_API_KEY" \  --secret-input-mode plaintext \  --custom-compatibility openai \  --custom-image-input

--custom-api-key 在非互動式模式中是選用的。如果省略，初始設定會檢查 CUSTOM_API_KEY。 OpenClaw 會自動將常見的視覺模型 ID 標記為具備圖片能力。對未知的自訂視覺 ID 傳入 --custom-image-input，或使用 --custom-text-input 強制設為純文字中繼資料。 若 OpenAI 相容端點支援 /v1/responses 但不支援 /v1/chat/completions，請使用 --custom-compatibility openai-responses。

LM Studio 在非互動式模式中也支援提供者專用的金鑰旗標：

bash
openclaw onboard --non-interactive \  --auth-choice lmstudio \  --custom-base-url "http://localhost:1234/v1" \  --custom-model-id "qwen/qwen3.5-9b" \  --lmstudio-api-key "$LM_API_TOKEN" \  --accept-risk

非互動式 Ollama：

bash
openclaw onboard --non-interactive \  --auth-choice ollama \  --custom-base-url "http://ollama-host:11434" \  --custom-model-id "qwen3.5:27b" \  --accept-risk

--custom-base-url 預設為 http://127.0.0.1:11434。--custom-model-id 是選用的；如果省略，初始設定會使用 Ollama 建議的預設值。像 kimi-k2.5:cloud 這類雲端模型 ID 也可在此使用。

將提供者金鑰儲存為參照，而不是明文：

bash
openclaw onboard --non-interactive \  --auth-choice openai-api-key \  --secret-input-mode ref \  --accept-risk

使用 --secret-input-mode ref 時，初始設定會寫入環境支援的參照，而不是明文金鑰值。 對於以 auth-profile 為基礎的提供者，這會寫入 keyRef 項目；對於自訂提供者，這會將 models.providers.<id>.apiKey 寫為環境參照（例如 { source: "env", provider: "default", id: "CUSTOM_API_KEY" }）。

非互動式 ref 模式合約：

  • 在初始設定程序環境中設定提供者環境變數（例如 OPENAI_API_KEY）。
  • 不要傳入行內金鑰旗標（例如 --openai-api-key），除非該環境變數也已設定。
  • 如果傳入行內金鑰旗標但缺少必要的環境變數，初始設定會快速失敗並提供指引。

非互動式模式中的閘道權杖選項：

  • --gateway-auth token --gateway-token <token> 會儲存明文權杖。
  • --gateway-auth token --gateway-token-ref-env <name> 會將 gateway.auth.token 儲存為環境 SecretRef。
  • --gateway-token 與 --gateway-token-ref-env 互斥。
  • --gateway-token-ref-env 需要初始設定程序環境中有非空的環境變數。
  • 使用 --install-daemon 時，若權杖驗證需要權杖，SecretRef 管理的閘道權杖會被驗證，但不會在監督程式服務環境中繼資料中以解析後的明文形式持久化。
  • 使用 --install-daemon 時，若權杖模式需要權杖且設定的權杖 SecretRef 無法解析，初始設定會以關閉狀態失敗並提供修復指引。
  • 使用 --install-daemon 時，若同時設定了 gateway.auth.token 與 gateway.auth.password，且未設定 gateway.auth.mode，初始設定會阻止安裝，直到明確設定模式。
  • 本機初始設定會將 gateway.mode="local" 寫入設定。如果之後的設定檔缺少 gateway.mode，請將其視為設定損壞或未完成的手動編輯，而不是有效的本機模式捷徑。
  • 當所選設定路徑需要時，本機初始設定會安裝所選的可下載外掛。
  • 遠端初始設定只會寫入遠端閘道的連線資訊，不會安裝本機外掛套件。
  • --allow-unconfigured 是獨立的閘道執行階段逃生口。它不代表初始設定可以省略 gateway.mode。

範例：

bash
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 \  --accept-risk

非互動式本機閘道健康狀態：

  • 除非你傳入 --skip-health，否則初始設定會等待可連線的本機閘道，然後才成功結束。
  • --install-daemon 會先啟動受管理的閘道安裝路徑。不使用它時，你必須已經有本機閘道在執行，例如 openclaw gateway run。
  • 如果你在自動化中只需要寫入設定/工作區/bootstrap，請使用 --skip-health。
  • 如果你自行管理工作區檔案，請傳入 --skip-bootstrap 以設定 agents.defaults.skipBootstrap: true，並略過建立 AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、HEARTBEAT.md 與 BOOTSTRAP.md。
  • 在原生 Windows 上，--install-daemon 會先嘗試排程工作，若工作建立遭拒，則退回到每位使用者的 Startup 資料夾登入項目。

參照模式下的互動式初始設定行為：

  • 在提示時選擇 使用祕密參照。
  • 然後選擇以下任一項：
    • 環境變數
    • 已設定的祕密提供者（file 或 exec）
  • 初始設定會在儲存參照前執行快速預檢驗證。
    • 如果驗證失敗，初始設定會顯示錯誤並讓你重試。

非互動式 Z.AI 端點選擇

bash
# Promptless endpoint selectionopenclaw onboard --non-interactive \  --auth-choice zai-coding-global \  --zai-api-key "$ZAI_API_KEY" # Other Z.AI endpoint choices:# --auth-choice zai-coding-cn# --auth-choice zai-global# --auth-choice zai-cn

非互動式 Mistral 範例：

bash
openclaw onboard --non-interactive \  --auth-choice mistral-api-key \  --mistral-api-key "$MISTRAL_API_KEY"

其他非互動式旗標

以權杖為基礎的模型驗證（非互動式；搭配 --auth-choice token 使用）：

  • --token-provider <id> — 權杖提供者 ID。識別由哪個提供者簽發權杖。
  • --token <token> — 用於模型驗證的權杖值。
  • --token-profile-id <id> — 驗證設定檔 ID。通用權杖儲存預設為 <provider>:manual；由提供者擁有的設定流程可能會使用自己的預設值，例如 anthropic:default。
  • --token-expires-in <duration> — 選用的權杖到期時間長度（例如 365d、12h）。

Cloudflare AI Gateway（非互動式）：

  • --cloudflare-ai-gateway-account-id <id> — 用於透過 Cloudflare AI Gateway 路由的 Cloudflare 帳戶 ID。
  • --cloudflare-ai-gateway-gateway-id <id> — Cloudflare AI Gateway ID。

常駐程式安裝控制：

  • --no-install-daemon — 明確略過閘道服務安裝。
  • --skip-daemon — --no-install-daemon 的別名。

UI 與 hook 設定控制：

  • --skip-ui — 在初始設定期間略過 Control UI / 終端介面提示。
  • --skip-hooks — 在初始設定期間略過網路鉤子 / hook 設定提示。

輸出抑制：

  • --suppress-gateway-token-output — 抑制含權杖的 Gateway/UI 輸出（權杖提示、嵌入權杖的自動登入 URL，以及自動啟動 Control UI）。適合共享終端機與 CI 環境。

流程備註

流程類型
  • quickstart：最少提示，自動產生閘道權杖。
  • manual：完整提示連接埠、繫結與驗證（advanced 的別名）。
  • import：執行偵測到的遷移提供者，預覽計畫，然後在確認後套用。
提供者預先篩選

當驗證選項暗示偏好的提供者時，初始設定會將預設模型與允許清單選擇器預先篩選到該提供者。對於 Volcengine 與 BytePlus，這也會符合 coding-plan 變體（volcengine-plan/*、byteplus-plan/*）。

如果偏好提供者篩選尚未產生任何已載入模型，初始設定會退回未篩選的目錄，而不是讓選擇器保持空白。

網頁搜尋後續提示

某些網頁搜尋提供者會觸發提供者專用的後續提示：

  • Grok 可使用相同的 xAI OAuth 設定檔或 API 金鑰，以及 x_search 模型選擇，提供選用的 x_search 設定。
  • Kimi 可詢問 Moonshot API 區域（api.moonshot.ai 或 api.moonshot.cn）以及預設 Kimi 網頁搜尋模型。
其他行為
  • 本機初始設定 DM 範圍行為：命令列介面設定參考。
  • 最快的首次聊天：openclaw dashboard（Control UI，無需頻道設定）。
  • 自訂提供者：連接任何 OpenAI 或 Anthropic 相容端點，包括未列出的託管提供者。使用 Unknown 進行自動偵測。
  • 如果偵測到 Hermes 狀態，初始設定會提供遷移流程。使用 遷移 取得 dry-run 計畫、覆寫模式、報告與精確對應。

常見後續指令

bash
openclaw channels addopenclaw configureopenclaw agents add <name>

將 openclaw setup 作為相同的引導式初始設定進入點。當你只需要基準設定/工作區時使用 openclaw setup --baseline，之後使用 openclaw configure 進行目標式變更，並使用 openclaw channels add 進行僅頻道設定。

Was this useful?
On this page

On this page