設定 — 工具與自訂供應商

供應商項目（type: "provider" 或省略）：

• provider：API 供應商 ID（openai、anthropic、google/gemini、groq 等）
• model：模型 ID 覆寫
• profile / preferredProfile：auth-profiles.json 設定檔選擇

命令列介面項目（type: "cli"）：

• command：要執行的可執行檔
• args：範本化引數（支援 {{MediaPath}}、{{Prompt}}、{{MaxChars}} 等；openclaw doctor --fix 會將已棄用的 {input} 預留位置遷移至 {{MediaPath}}）

共用欄位：

• capabilities：包含 image、audio 及 video 中一項或多項的清單。
• prompt、maxChars、maxBytes、timeoutSeconds、language：個別項目的覆寫。
• 當代理程式呼叫明確的 image 工具時，相符影像模型的 timeoutSeconds 項目也會套用。對於影像理解，此逾時套用至請求本身，不會因先前的準備工作而縮短。
• 失敗時會改用下一個項目。

供應商驗證依照標準順序進行：auth-profiles.json → 環境變數 → models.providers.*.apiKey。

• self：僅限目前工作階段鍵。
• tree：目前工作階段 + 由目前工作階段產生的工作階段（子代理程式）。對於讀取操作，這也包括目前工作階段透過環境群組感知監看的同一代理程式群組工作階段。
• agent：屬於目前代理程式 ID 的任何工作階段（如果你在同一代理程式 ID 下依傳送者執行工作階段，可能會包含其他使用者）。
• all：任何工作階段。跨代理程式指定目標仍需要 tools.agentToAgent。
• 沙箱限制：當目前工作階段位於沙箱中且 agents.defaults.sandbox.sessionToolsVisibility="spawned"（預設值）時，即使 tools.sessions.visibility="all"，可見性仍會強制設為 tree。
• 當不是 all 時，sessions_list 會包含精簡的 visibility 欄位，說明實際模式，並警告目前範圍以外的部分工作階段可能會被省略。

• 附件需要 enabled: true。
• 子代理程式附件會具體化至子工作區的 .openclaw/attachments/<uuid>/，並附有 .manifest.json。
• ACP 附件僅限影像，並會在通過相同的檔案數量、單檔位元組數及總位元組數限制後，以行內方式轉送至 ACP 執行階段。
• 附件內容會自動從逐字稿持久化資料中遮蔽。
• Base64 輸入會接受嚴格的字母表／填補檢查，以及解碼前大小防護。
• 子代理程式附件的檔案權限，目錄為 0700，檔案為 0600。
• 子代理程式清理遵循 cleanup 原則：delete 一律移除附件；只有在 retainOnSessionKeep: true 時，keep 才會保留附件。

• 若有自訂驗證需求，請使用 authHeader: true + headers。
• 使用 OPENCLAW_AGENT_DIR 覆寫代理程式設定根目錄。
• 相符供應商 ID 的合併優先順序：
  • 代理程式中非空的 models.json baseUrl 值優先。
  • 僅當該供應商在目前的設定／驗證設定檔情境中不受 SecretRef 管理時，代理程式中非空的 apiKey 值才優先。
  • 受 SecretRef 管理的供應商 apiKey 值會從來源標記重新整理（環境變數參照使用 ENV_VAR_NAME，檔案／執行參照使用 secretref-managed），而不會保存解析後的祕密。
  • 受 SecretRef 管理的供應商標頭值會從來源標記重新整理（環境變數參照使用 secretref-env:ENV_VAR_NAME，檔案／執行參照使用 secretref-managed）。
  • 代理程式的 apiKey/baseUrl 為空或缺少時，會退回使用設定中的 models.providers。
  • 相符模型的 contextWindow/maxTokens：若明確設定值存在且有效（正的有限數值），則該值優先；否則使用隱含／產生的目錄值。
  • 相符模型的 contextTokens 遵循相同的「明確值優先，否則使用隱含值」規則；可用它限制有效情境，而不變更原生模型中繼資料。
  • 供應商外掛目錄會以產生的外掛自有目錄分片形式，儲存在代理程式的外掛狀態下。
  • 若要讓設定完整重寫 models.json，並略過合併外掛自有的目錄分片，請使用 models.mode: "replace"。
  • 標記保存以來源為準：標記是從作用中的來源設定快照（解析前）寫入，而不是從解析後的執行階段祕密值寫入。

• models.mode：供應商目錄行為（merge 或 replace）。
• models.providers：以供應商 ID 為鍵的自訂供應商對應表。
  • 安全編輯：使用 openclaw config set models.providers.<id> '<json>' --strict-json --merge 或 openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge 進行增量更新。除非傳入 --replace，否則 config set 會拒絕破壞性取代。

• models.providers.*.api：請求轉接器（openai-completions、openai-responses、openai-chatgpt-responses、anthropic-messages、google-generative-ai、google-vertex、github-copilot、bedrock-converse-stream、ollama、azure-openai-responses）。對於 MLX、vLLM、SGLang 及多數與 OpenAI 相容的本機伺服器等自行託管的 /v1/chat/completions 後端，請使用 openai-completions。具有 baseUrl 但沒有 api 的自訂供應商，預設使用 openai-completions；僅當後端支援 /v1/responses 時，才設定 openai-responses。
• models.providers.*.apiKey：供應商認證資訊（建議使用 SecretRef／環境變數替換）。
• models.providers.*.auth：驗證策略（api-key、token、oauth、aws-sdk）。
• models.providers.*.contextWindow：當模型項目未設定 contextWindow 時，此供應商旗下模型的預設原生情境視窗。
• models.providers.*.contextTokens：當模型項目未設定 contextTokens 時，此供應商旗下模型的預設有效執行階段情境上限。
• models.providers.*.maxTokens：當模型項目未設定 maxTokens 時，此供應商旗下模型的預設輸出權杖上限。
• models.providers.*.timeoutSeconds：選用的各供應商模型 HTTP 請求逾時秒數，涵蓋連線、標頭、本文與整體請求中止處理。
• models.providers.*.injectNumCtxForOpenAICompat：對於 Ollama + openai-completions，將 options.num_ctx 注入請求（預設值：true）。
• models.providers.*.authHeader：需要時，強制透過 Authorization 標頭傳輸認證資訊。
• models.providers.*.baseUrl：上游 API 基底 URL。
• models.providers.*.headers：用於 Proxy／租戶路由的額外靜態標頭。

models.providers.*.request：模型供應商 HTTP 請求的傳輸覆寫。

• request.headers：額外標頭（與供應商預設值合併）。值可接受 SecretRef。
• request.auth：驗證策略覆寫。模式："provider-default"（使用供應商的內建驗證）、"authorization-bearer"（搭配 token）、"header"（搭配 headerName、value，以及選用的 prefix）。
• request.proxy：HTTP Proxy 覆寫。模式："env-proxy"（使用 HTTP_PROXY/HTTPS_PROXY 環境變數）、"explicit-proxy"（搭配 url）。兩種模式都可接受選用的 tls 子物件。
• request.tls：直接連線的 TLS 覆寫。欄位：ca、cert、key、passphrase（皆可接受 SecretRef）、serverName、insecureSkipVerify。
• request.allowPrivateNetwork：當為 true 時，允許模型供應商 HTTP 請求透過供應商 HTTP 擷取防護存取私有、CGNAT 或類似範圍。自訂／本機供應商的基底 URL 已信任確切設定的來源，但中繼資料／連結本機來源除外；若未明確選用，這些來源仍會遭到封鎖。將此項設為 false，可停用確切來源信任。WebSocket 會使用相同的 request 處理標頭／TLS，但不使用該擷取 SSRF 防護。預設值為 false。

• models.providers.*.models：明確的供應商模型目錄項目。
• models.providers.*.models.*.input：模型輸入模態。純文字模型使用 ["text"]，原生圖片／視覺模型使用 ["text", "image"]。僅當所選模型標示為支援圖片時，圖片附件才會注入代理程式回合。
• models.providers.*.models.*.contextWindow：原生模型情境視窗中繼資料。這會覆寫該模型的供應商層級 contextWindow。
• models.providers.*.models.*.contextTokens：選用的執行階段情境上限。這會覆寫供應商層級的 contextTokens；若要使用比模型原生 contextWindow 更小的有效情境預算，請使用此項；當兩個值不同時，openclaw models list 會同時顯示兩者。

自訂供應商能力宣告

對於內建和目錄已知的模型路由，供應商目錄擁有 compat。請勿將這些旗標複製到設定中：只要已設定的 api 與 baseUrl 仍指向該路由，OpenClaw 就會使用目錄資料列。openclaw doctor --fix 會移除相符的舊版覆寫，並回報不一致的值以供審查。

對於真正的自訂供應商、自訂模型，或路由至不同端點的目錄模型，仍支援 compat 區塊。僅設定已針對該端點驗證的能力：

• plugins.entries.amazon-bedrock.config.discovery：Bedrock 自動探索設定根節點。
• plugins.entries.amazon-bedrock.config.discovery.enabled：開啟／關閉隱式探索。
• plugins.entries.amazon-bedrock.config.discovery.region：用於探索的 AWS 區域。
• plugins.entries.amazon-bedrock.config.discovery.providerFilter：用於定向探索的選用提供者 ID 篩選器。
• plugins.entries.amazon-bedrock.config.discovery.refreshInterval：探索重新整理的輪詢間隔。
• plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow：已探索模型的備援上下文視窗。
• plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens：已探索模型的備援最大輸出權杖數。

官方外部 cerebras 提供者外掛可透過 openclaw onboard --auth-choice cerebras-api-key 進行設定。只有在覆寫預設值時才使用明確的提供者設定。

{  env: { CEREBRAS_API_KEY: "sk-..." },  agents: {    defaults: {      model: {        primary: "cerebras/zai-glm-4.7",        fallbacks: ["cerebras/gpt-oss-120b"],      },      models: {        "cerebras/zai-glm-4.7": { alias: "GLM 4.7 (Cerebras)" },        "cerebras/gpt-oss-120b": { alias: "GPT OSS 120B (Cerebras)" },      },    },  },  models: {    mode: "merge",    providers: {      cerebras: {        baseUrl: "https://api.cerebras.ai/v1",        apiKey: "${CEREBRAS_API_KEY}",        api: "openai-completions",        models: [          { id: "zai-glm-4.7", name: "GLM 4.7 (Cerebras)" },          { id: "gpt-oss-120b", name: "GPT OSS 120B (Cerebras)" },        ],      },    },  },}

Cerebras 請使用 cerebras/zai-glm-4.7；直接使用 Z.AI 則請使用 zai/glm-4.7。

{  env: { KIMI_API_KEY: "sk-..." },  agents: {    defaults: {      model: { primary: "kimi/kimi-for-coding" },      models: { "kimi/kimi-for-coding": { alias: "Kimi Code" } },    },  },}

內建且與 Anthropic 相容的提供者。捷徑：openclaw onboard --auth-choice kimi-code-api-key。

請參閱本機模型。簡而言之：在高效能硬體上透過 LM Studio Responses API 執行大型本機模型；保留已合併的託管模型作為備援。

{  agents: {    defaults: {      model: { primary: "minimax/MiniMax-M3" },      models: {        "minimax/MiniMax-M3": { alias: "Minimax" },      },    },  },  models: {    mode: "merge",    providers: {      minimax: {        baseUrl: "https://api.minimax.io/anthropic",        apiKey: "${MINIMAX_API_KEY}",        api: "anthropic-messages",        models: [          {            id: "MiniMax-M3",            name: "MiniMax M3",            reasoning: true,            input: ["text", "image"],            cost: { input: 0.6, output: 2.4, cacheRead: 0.12, cacheWrite: 0 },            contextWindow: 1000000,            maxTokens: 131072,          },        ],      },    },  },}

設定 MINIMAX_API_KEY。捷徑：openclaw onboard --auth-choice minimax-global-api 或 openclaw onboard --auth-choice minimax-cn-api。模型目錄預設為 M3，也包含 M2.7 變體。在與 Anthropic 相容的串流路徑上，除非你自行明確設定 thinking，否則 OpenClaw 預設會停用 MiniMax M2.x 的思考功能；MiniMax-M3（及 M3.x）預設仍使用提供者省略／自適應的思考路徑。/fast on 或 params.fastMode: true 會將 MiniMax-M2.7 改寫為 MiniMax-M2.7-highspeed。

{  env: { MOONSHOT_API_KEY: "sk-..." },  agents: {    defaults: {      model: { primary: "moonshot/kimi-k2.6" },      models: { "moonshot/kimi-k2.6": { alias: "Kimi K2.6" } },    },  },  models: {    mode: "merge",    providers: {      moonshot: {        baseUrl: "https://api.moonshot.ai/v1",        apiKey: "${MOONSHOT_API_KEY}",        api: "openai-completions",        models: [          {            id: "kimi-k2.6",            name: "Kimi K2.6",            reasoning: false,            input: ["text", "image"],            cost: { input: 0.95, output: 4, cacheRead: 0.16, cacheWrite: 0 },            contextWindow: 262144,            maxTokens: 262144,          },        ],      },    },  },}

中國端點請使用：baseUrl: "https://api.moonshot.cn/v1" 或 openclaw onboard --auth-choice moonshot-api-key-cn。

原生 Moonshot 端點會在共用的 openai-completions 傳輸層上宣告串流用量相容性，而 OpenClaw 會依據端點功能決定是否啟用，不會只依據內建提供者 ID。

{  agents: {    defaults: {      model: { primary: "opencode/claude-opus-4-6" },      models: { "opencode/claude-opus-4-6": { alias: "Opus" } },    },  },}

設定 OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY）。Zen 目錄請使用 opencode/... 參照，Go 目錄則使用 opencode-go/... 參照。捷徑：openclaw onboard --auth-choice opencode-zen 或 openclaw onboard --auth-choice opencode-go。

{  env: { SYNTHETIC_API_KEY: "sk-..." },  agents: {    defaults: {      model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M3" },      models: { "synthetic/hf:MiniMaxAI/MiniMax-M3": { alias: "MiniMax M3" } },    },  },  models: {    mode: "merge",    providers: {      synthetic: {        baseUrl: "https://api.synthetic.new/anthropic",        apiKey: "${SYNTHETIC_API_KEY}",        api: "anthropic-messages",        models: [          {            id: "hf:MiniMaxAI/MiniMax-M3",            name: "MiniMax M3",            reasoning: true,            input: ["text", "image"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 262144,            maxTokens: 65536,          },        ],      },    },  },}

基底 URL 應省略 /v1（Anthropic 用戶端會附加該部分）。捷徑：openclaw onboard --auth-choice synthetic-api-key。

{  agents: {    defaults: {      model: { primary: "zai/glm-4.7" },      models: { "zai/glm-4.7": {} },    },  },}

設定 ZAI_API_KEY。模型參照使用標準的 zai/* 提供者 ID。捷徑：openclaw onboard --auth-choice zai-api-key。

• 一般端點：https://api.z.ai/api/paas/v4
• 程式設計端點：https://api.z.ai/api/coding/paas/v4
• 預設的 zai-api-key 驗證選項會探測你的金鑰，並自動偵測其所屬端點（若偵測結果不明確，則會改為提示你選擇，預設為 Global）。另有專用的 CN 與 Coding-Plan 驗證選項，可供明確選取。
• 若使用一般端點，請定義自訂提供者並覆寫基底 URL。