設定 — 工具與自訂提供者

提供者項目（type: "provider" 或省略）：

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

CLI 項目（type: "cli"）：

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

通用欄位：

• capabilities：選用清單（image、audio、video）。預設值：openai/anthropic/minimax → 圖片，google → 圖片+音訊+影片，groq → 音訊。
• prompt、maxChars、maxBytes、timeoutSeconds、language：個別項目覆寫。
• 當 agent 呼叫明確的 image 工具時，tools.media.image.timeoutSeconds 與相符圖片模型的 timeoutSeconds 項目也會套用。
• 失敗時會回退到下一個項目。

提供者驗證遵循標準順序：auth-profiles.json → 環境變數 → models.providers.*.apiKey。

非同步完成欄位：

• asyncCompletion.directSend：已棄用的相容性旗標。已完成的非同步媒體任務會維持由請求者工作階段中介，因此 agent 會收到結果、決定如何告知使用者，並在來源交付需要時使用訊息工具。

• self：僅限目前工作階段金鑰。
• tree：目前工作階段 + 由目前工作階段產生的工作階段（subagent）。
• agent：屬於目前 agent ID 的任何工作階段（如果你在同一個 agent ID 下依傳送者執行工作階段，可能包含其他使用者）。
• all：任何工作階段。跨 agent 目標仍需要 tools.agentToAgent。
• 沙箱限制：當目前工作階段在沙箱中，且 agents.defaults.sandbox.sessionToolsVisibility="spawned" 時，即使 tools.sessions.visibility="all"，可見性也會被強制為 tree。

• 附件僅支援 runtime: "subagent"。ACP 執行階段會拒絕它們。
• 檔案會具體化到子工作區的 .openclaw/attachments/<uuid>/，並包含 .manifest.json。
• 附件內容會自動從對話稿持久化中遮蔽。
• Base64 輸入會使用嚴格的字母表/填補檢查和解碼前大小防護進行驗證。
• 檔案權限為目錄 0700、檔案 0600。
• 清理會遵循 cleanup 政策：delete 一律移除附件；keep 只會在 retainOnSessionKeep: true 時保留附件。

• 對於自訂驗證需求，使用 authHeader: true + headers。
• 使用 OPENCLAW_AGENT_DIR（或舊版環境變數別名 PI_CODING_AGENT_DIR）覆寫代理程式設定根目錄。
• 相符提供者 ID 的合併優先順序：
  • 非空的代理程式 models.json baseUrl 值勝出。
  • 非空的代理程式 apiKey 值只會在該提供者於目前設定/驗證設定檔情境中不是由 SecretRef 管理時勝出。
  • 由 SecretRef 管理的提供者 apiKey 值會從來源標記（環境變數參照為 ENV_VAR_NAME，檔案/exec 參照為 secretref-managed）重新整理，而不是持久化已解析的秘密。
  • 由 SecretRef 管理的提供者標頭值會從來源標記（環境變數參照為 secretref-env:ENV_VAR_NAME，檔案/exec 參照為 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、anthropic-messages、google-generative-ai 等）。對於自託管的 /v1/chat/completions 後端，例如 MLX、vLLM、SGLang，以及大多數 OpenAI 相容的本機伺服器，使用 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：用於代理/租戶路由的額外靜態標頭。

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 時，如果 DNS 解析為私有、CGNAT 或類似範圍，透過提供者 HTTP 擷取防護允許 HTTPS 到 baseUrl（操作員選擇加入，用於受信任的自託管 OpenAI 相容端點）。除非明確設為 false，否則會自動允許 localhost、127.0.0.1 和 [::1] 等迴路模型提供者串流 URL；LAN、tailnet 和私有 DNS 主機仍需要選擇加入。WebSocket 對標頭/TLS 使用相同的 request，但不使用該擷取 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 會在兩個值不同時顯示兩者。
• models.providers.*.models.*.compat.supportsDeveloperRole：選用的相容性提示。對於 api: "openai-completions" 搭配非空的非原生 baseUrl（主機不是 api.openai.com），OpenClaw 會在執行階段強制將其設為 false。空白/省略的 baseUrl 會保留預設 OpenAI 行為。
• models.providers.*.models.*.compat.requiresStringContent：用於僅支援字串的 OpenAI 相容聊天端點的選用相容性提示。當為 true 時，OpenClaw 會在傳送請求前，將純文字 messages[].content 陣列扁平化為一般字串。
• models.providers.*.models.*.compat.strictMessageKeys：用於嚴格 OpenAI 相容聊天端點的選用相容性提示。當為 true 時，OpenClaw 會在傳送請求前，將傳出的 Chat Completions 訊息物件剝離為 role 和 content。
• models.providers.*.models.*.compat.thinkingFormat：選用的 thinking 酬載提示。對頂層 enable_thinking 使用 "qwen"，或對支援請求層級 chat-template kwargs 的 Qwen 系列 OpenAI 相容伺服器（例如 vLLM）上的 chat_template_kwargs.enable_thinking 使用 "qwen-chat-template"。

• 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 提供者 Plugin 可透過 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-M2.7" },      models: {        "minimax/MiniMax-M2.7": { alias: "Minimax" },      },    },  },  models: {    mode: "merge",    providers: {      minimax: {        baseUrl: "https://api.minimax.io/anthropic",        apiKey: "${MINIMAX_API_KEY}",        api: "anthropic-messages",        models: [          {            id: "MiniMax-M2.7",            name: "MiniMax M2.7",            reasoning: true,            input: ["text"],            cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0.375 },            contextWindow: 204800,            maxTokens: 131072,          },        ],      },    },  },}

設定 MINIMAX_API_KEY。快捷方式：openclaw onboard --auth-choice minimax-global-api 或 openclaw onboard --auth-choice minimax-cn-api。模型目錄預設只有 M2.7。在 Anthropic 相容的串流路徑上，除非你自行明確設定 thinking，否則 OpenClaw 預設會停用 MiniMax 的思考功能。/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-M2.5" },      models: { "synthetic/hf:MiniMaxAI/MiniMax-M2.5": { alias: "MiniMax M2.5" } },    },  },  models: {    mode: "merge",    providers: {      synthetic: {        baseUrl: "https://api.synthetic.new/anthropic",        apiKey: "${SYNTHETIC_API_KEY}",        api: "anthropic-messages",        models: [          {            id: "hf:MiniMaxAI/MiniMax-M2.5",            name: "MiniMax M2.5",            reasoning: true,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 192000,            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。z.ai/* 和 z-ai/* 是可接受的別名。快捷方式：openclaw onboard --auth-choice zai-api-key。

• 一般端點：https://api.z.ai/api/paas/v4
• 程式碼端點（預設）：https://api.z.ai/api/coding/paas/v4
• 若使用一般端點，請定義自訂提供者並覆寫基礎 URL。