`openclaw onboard`

互動式引導精靈（本機或遠端 Gateway 設定）。

範例

openclaw onboard
openclaw onboard --flow quickstart
openclaw onboard --flow manual
openclaw onboard --mode remote --remote-url wss://gateway-host:18789

若要連線到私有網路的明文 ws:// 目標（僅限受信任的網路），請在引導程序的環境中設定 OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1。

非互動式自訂提供者：

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-api-key 為選填。省略時，引導程式會檢查 CUSTOM_API_KEY 環境變數。

非互動式 Ollama：

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 建議的預設值。雲端模型 ID 如 kimi-k2.5:cloud 也適用。

將提供者金鑰儲存為參照而非明文：

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

使用 --secret-input-mode ref 時，引導程式會寫入環境變數參照而非明文金鑰值。對於驗證設定檔支援的提供者，會寫入 keyRef 項目；對於自訂提供者，會將 models.providers.<id>.apiKey 寫為環境變數參照（例如 { source: "env", provider: "default", id: "CUSTOM_API_KEY" }）。

非互動式 ref 模式規範：

在引導程序環境中設定提供者的環境變數（例如 OPENAI_API_KEY）。
除非該環境變數也已設定，否則不要傳入行內金鑰旗標（例如 --openai-api-key）。
若傳入了行內金鑰旗標但缺少必要的環境變數，引導程式會立即失敗並提供修正指引。

非互動模式的 Gateway 權杖選項：

--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 管理的 Gateway 權杖會被驗證，但不會以解析後的明文持久化到 supervisor 服務環境中繼資料中。
搭配 --install-daemon 時，若權杖模式需要權杖且已設定的權杖 SecretRef 未解析，引導程式會直接失敗並提供修正指引。
搭配 --install-daemon 時，若同時設定了 gateway.auth.token 與 gateway.auth.password 但未設定 gateway.auth.mode，引導程式會阻擋安裝，直到明確設定 mode。

範例：

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

非互動式本機 Gateway 健康檢查：

除非使用 --skip-health，否則引導程式會等待本機 Gateway 可連線後才成功結束。
--install-daemon 會先啟動託管的 Gateway 安裝流程。未使用時，你必須已有正在執行的本機 Gateway，例如透過 openclaw gateway run。
若在自動化中只需要寫入設定/工作區/初始化檔案，請使用 --skip-health。
在原生 Windows 上，--install-daemon 會先嘗試排程工作，若建立失敗則退回使用者層級的啟動資料夾登入項目。

互動式引導中的參照模式行為：

系統提示時選擇使用機密參照。
然後選擇：
- 環境變數
- 已設定的機密提供者（file 或 exec）
引導程式會在儲存參照前執行快速預檢驗證。
- 驗證失敗時，會顯示錯誤並讓你重試。

非互動式 Z.AI 端點選擇：

注意：--auth-choice zai-api-key 現在會為你的金鑰自動偵測最佳的 Z.AI 端點（偏好使用 zai/glm-5 的通用 API）。若你特別需要 GLM Coding Plan 端點，請選擇 zai-coding-global 或 zai-coding-cn。

# 無提示的端點選擇
openclaw onboard --non-interactive \
  --auth-choice zai-coding-global \
  --zai-api-key "$ZAI_API_KEY"

# 其他 Z.AI 端點選項：
# --auth-choice zai-coding-cn
# --auth-choice zai-global
# --auth-choice zai-cn

非互動式 Mistral 範例：

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

流程說明：

quickstart：最少提示，自動產生 Gateway 權杖。
manual：完整的連接埠/綁定/驗證提示（advanced 的別名）。
本機引導 DM 範圍行為：CLI Onboarding Reference。
最快開始對話：openclaw dashboard（Control UI，無需設定頻道）。
自訂提供者：連接任何 OpenAI 或 Anthropic 相容端點，包含未列出的託管提供者。選擇 Unknown 可自動偵測。

常用後續指令

openclaw configure
openclaw agents add <name>

注意： --json 並不等同於非互動模式。自動化腳本請使用 --non-interactive。

openclaw onboard

相關指南

範例

常用後續指令

`openclaw onboard`