模型提供商

模型提供商（LLM/model providers）的参考资料（不是 WhatsApp/Telegram 这样的聊天渠道）。如需了解模型选择规则，请参阅 Models。

快速规则

模型引用和 CLI 辅助命令

模型引用使用 provider/model（示例：opencode/claude-opus-4-6）。
设置后，agents.defaults.models 会作为允许列表。
CLI 辅助命令：openclaw onboard、openclaw models list、openclaw models set <provider/model>。
models.providers.*.contextWindow / contextTokens / maxTokens 设置提供商级默认值；models.providers.*.models[].contextWindow / contextTokens / maxTokens 会按模型覆盖这些默认值。
回退规则、冷却探测和会话级覆盖持久化：模型故障转移。

添加提供商凭证不会更改你的主模型

当你添加或重新认证提供商时，openclaw configure 会保留现有的 agents.defaults.model.primary。提供商插件仍然可能在其凭证配置补丁中返回推荐的默认模型，但如果主模型已经存在，configure 会将其视为“让此模型可用”，而不是“替换当前主模型”。若要有意切换默认模型，请使用 openclaw models set <provider/model> 或 openclaw models auth login --provider <id> --set-default。

OpenAI provider/运行时拆分

OpenAI 系列路由按前缀区分：

openai/<model> 加上 agents.defaults.agentRuntime.id: "codex" 使用原生 Codex 应用服务器 harness。这是常见的 ChatGPT/Codex 订阅设置。
openai-codex/<model> 在 PI 中使用 Codex OAuth。
没有 Codex 运行时覆盖的 openai/<model> 在 PI 中使用直接的 OpenAI API key 提供商。

请参阅 OpenAI 和 Codex harness。如果提供商/运行时拆分让人困惑，请先阅读 Agent Runtimes。插件自动启用遵循同一边界：openai-codex/<model> 属于 OpenAI 插件，而 Codex 插件由 agentRuntime.id: "codex" 或旧版 codex/<model> 引用启用。设置 agentRuntime.id: "codex" 时，可以通过原生 Codex 应用服务器 harness 使用 GPT-5.5；在 PI 中通过 openai-codex/gpt-5.5 使用 Codex OAuth；当你的账户公开该能力时，在 PI 中通过 openai/gpt-5.5 使用直接 API key 流量。

CLI 运行时

CLI 运行时使用相同拆分：选择规范模型引用，例如 anthropic/claude-*、google/gemini-* 或 openai/gpt-*，然后在需要本地 CLI 后端时，将 agents.defaults.agentRuntime.id 设置为 claude-cli、google-gemini-cli 或 codex-cli。旧版 claude-cli/*、google-gemini-cli/* 和 codex-cli/* 引用会迁移回规范提供商引用，并单独记录运行时。

插件拥有的提供商行为

大多数提供商特定逻辑位于提供商插件（registerProvider(...)）中，而 OpenClaw 保留通用推理循环。插件负责新手引导、模型目录、凭证环境变量映射、传输/配置规范化、工具 schema 清理、故障转移分类、OAuth 刷新、用量报告、思考/推理配置等。提供商 SDK 钩子和内置插件示例的完整列表位于 Provider plugins。需要完全自定义请求执行器的提供商属于另一个更深层的扩展表面。

提供商拥有的 runner 行为位于显式提供商钩子上，例如重放策略、工具 schema 规范化、流包装以及传输/请求辅助函数。旧版 ProviderPlugin.capabilities 静态包仅用于兼容性，共享 runner 逻辑不再读取它。

API key 轮换

密钥来源和优先级

通过以下方式配置多个密钥：

OPENCLAW_LIVE_<PROVIDER>_KEY（单个实时覆盖，最高优先级）
<PROVIDER>_API_KEYS（逗号或分号列表）
<PROVIDER>_API_KEY（主密钥）
<PROVIDER>_API_KEY_*（编号列表，例如 <PROVIDER>_API_KEY_1）

对于 Google 提供商，GOOGLE_API_KEY 也会作为回退包含在内。密钥选择顺序会保留优先级并对值去重。

轮换何时生效

仅在速率限制响应时，才会使用下一个密钥重试请求（例如 429、rate_limit、quota、resource exhausted、Too many concurrent requests、ThrottlingException、concurrency limit reached、workers_ai ... quota limit exceeded，或周期性用量限制消息）。
非速率限制故障会立即失败；不会尝试密钥轮换。
当所有候选密钥都失败时，会返回最后一次尝试的最终错误。

内置提供商（pi-ai 目录）

OpenClaw 随附 pi‑ai 目录。这些提供商不需要 models.providers 配置；只需设置凭证并选择模型。

OpenAI

提供商：openai
凭证：OPENAI_API_KEY
可选轮换：OPENAI_API_KEYS、OPENAI_API_KEY_1、OPENAI_API_KEY_2，以及 OPENCLAW_LIVE_OPENAI_KEY（单个覆盖）
示例模型：openai/gpt-5.5、openai/gpt-5.4-mini
如果特定安装或 API key 的行为不同，请使用 openclaw models list --provider openai 验证账户/模型可用性。
CLI：openclaw onboard --auth-choice openai-api-key
默认传输为 auto（WebSocket 优先，SSE 回退）
通过 agents.defaults.models["openai/<model>"].params.transport 按模型覆盖（"sse"、"websocket" 或 "auto"）
OpenAI Responses WebSocket 预热默认通过 params.openaiWsWarmup 启用（true/false）
可通过 agents.defaults.models["openai/<model>"].params.serviceTier 启用 OpenAI 优先级处理
/fast 和 params.fastMode 会将直接 openai/* Responses 请求映射为 api.openai.com 上的 service_tier=priority
当你需要显式层级而不是共享 /fast 开关时，请使用 params.serviceTier
隐藏的 OpenClaw 归因标头（originator、version、User-Agent）仅应用于发往 api.openai.com 的原生 OpenAI 流量，不适用于通用 OpenAI 兼容代理
原生 OpenAI 路由还会保留 Responses store、提示缓存提示和 OpenAI 推理兼容负载整形；代理路由不会
openai/gpt-5.3-codex-spark 在 OpenClaw 中被有意抑制，因为实时 OpenAI API 请求会拒绝它，且当前 Codex 目录未公开它

{
  agents: { defaults: { model: { primary: "openai/gpt-5.5" } } },
}

Anthropic

提供商：anthropic
凭证：ANTHROPIC_API_KEY
可选轮换：ANTHROPIC_API_KEYS、ANTHROPIC_API_KEY_1、ANTHROPIC_API_KEY_2，以及 OPENCLAW_LIVE_ANTHROPIC_KEY（单个覆盖）
示例模型：anthropic/claude-opus-4-6
CLI：openclaw onboard --auth-choice apiKey
直接公共 Anthropic 请求支持共享 /fast 开关和 params.fastMode，包括发送到 api.anthropic.com 的 API key 和 OAuth 认证流量；OpenClaw 会将其映射到 Anthropic service_tier（auto 与 standard_only）
首选 Claude CLI 配置会保持模型引用规范，并单独选择 CLI 后端：anthropic/claude-opus-4-7 搭配 agents.defaults.agentRuntime.id: "claude-cli"。旧版 claude-cli/claude-opus-4-7 引用仍可用于兼容性。

Anthropic 工作人员告知我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此除非 Anthropic 发布新策略，否则 OpenClaw 会将 Claude CLI 复用和 claude -p 用法视为此集成的受认可方式。Anthropic setup-token 仍可作为受支持的 OpenClaw 令牌路径使用，但 OpenClaw 现在优先复用 Claude CLI，并在可用时使用 claude -p。

{
  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
}

OpenAI Codex OAuth

提供商：openai-codex
凭证：OAuth（ChatGPT）
PI 模型引用：openai-codex/gpt-5.5
原生 Codex 应用服务器 harness 引用：openai/gpt-5.5 搭配 agents.defaults.agentRuntime.id: "codex"
原生 Codex 应用服务器 harness 文档：Codex harness
旧版模型引用：codex/gpt-*
插件边界：openai-codex/* 加载 OpenAI 插件；原生 Codex 应用服务器插件仅由 Codex harness 运行时或旧版 codex/* 引用选择。
CLI：openclaw onboard --auth-choice openai-codex 或 openclaw models auth login --provider openai-codex
默认传输为 auto（WebSocket 优先，SSE 回退）
通过 agents.defaults.models["openai-codex/<model>"].params.transport 按 PI 模型覆盖（"sse"、"websocket" 或 "auto"）
params.serviceTier 也会在原生 Codex Responses 请求（chatgpt.com/backend-api）上转发
隐藏的 OpenClaw 归因标头（originator、version、User-Agent）仅附加到发往 chatgpt.com/backend-api 的原生 Codex 流量，不适用于通用 OpenAI 兼容代理
与直接 openai/* 共享相同的 /fast 开关和 params.fastMode 配置；OpenClaw 会将其映射为 service_tier=priority
openai-codex/gpt-5.5 使用 Codex 目录原生 contextWindow = 400000 和默认运行时 contextTokens = 272000；可使用 models.providers.openai-codex.models[].contextTokens 覆盖运行时上限
策略说明：OpenAI Codex OAuth 明确支持 OpenClaw 这类外部工具/工作流。
对于常见的订阅加原生 Codex 运行时路线，请使用 openai-codex 凭证登录，但配置 openai/gpt-5.5 加 agents.defaults.agentRuntime.id: "codex"。
仅当你想通过 PI 使用 Codex OAuth/订阅路线时，才使用 openai-codex/gpt-5.5；当你的 API key 设置和本地目录公开公共 API 路线时，请使用不带 Codex 运行时覆盖的 openai/gpt-5.5。

{
  plugins: { entries: { codex: { enabled: true } } },
  agents: {
    defaults: {
      model: { primary: "openai/gpt-5.5" },
      agentRuntime: { id: "codex" },
    },
  },
}

{
  models: {
    providers: {
      "openai-codex": {
        models: [{ id: "gpt-5.5", contextTokens: 160000 }],
      },
    },
  },
}

其他订阅式托管选项

GLM 模型

Z.AI Coding Plan 或通用 API 端点。

MiniMax

MiniMax Coding Plan OAuth 或 API key 访问。

Qwen Cloud

Qwen Cloud 提供商表面，加上 Alibaba DashScope 和 Coding Plan 端点映射。

OpenCode

凭证：OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY）
Zen 运行时提供商：opencode
Go 运行时提供商：opencode-go
示例模型：opencode/claude-opus-4-6、opencode-go/kimi-k2.6
CLI：openclaw onboard --auth-choice opencode-zen 或 openclaw onboard --auth-choice opencode-go

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

Google Gemini（API key）

提供商：google
凭证：GEMINI_API_KEY
可选轮换：GEMINI_API_KEYS、GEMINI_API_KEY_1、GEMINI_API_KEY_2、GOOGLE_API_KEY 回退，以及 OPENCLAW_LIVE_GEMINI_KEY（单个覆盖项）
示例模型：google/gemini-3.1-pro-preview、google/gemini-3-flash-preview
兼容性：使用 google/gemini-3.1-flash-preview 的旧版 OpenClaw 配置会规范化为 google/gemini-3-flash-preview
别名：接受 google/gemini-3.1-pro，并将其规范化为 Google 的实时 Gemini API id，即 google/gemini-3.1-pro-preview
CLI：openclaw onboard --auth-choice gemini-api-key
思考：/think adaptive 使用 Google 动态思考。Gemini 3/3.1 会省略固定的 thinkingLevel；Gemini 2.5 会发送 thinkingBudget: -1。
直接 Gemini 运行也接受 agents.defaults.models["google/<model>"].params.cachedContent（或旧版 cached_content），用于转发提供商原生的 cachedContents/... 句柄；Gemini 缓存命中会显示为 OpenClaw cacheRead

Google Vertex 和 Gemini CLI

提供商：google-vertex、google-gemini-cli
凭证：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程

OpenClaw 中的 Gemini CLI OAuth 是非官方集成。一些用户报告称，使用第三方客户端后遇到了 Google 账号限制。如果你选择继续，请查看 Google 条款并使用非关键账号。

Gemini CLI OAuth 作为内置 google 插件的一部分提供。

Install Gemini CLI

brew
npm

brew install gemini-cli

npm install -g @google/gemini-cli

Enable plugin

openclaw plugins enable google

openclaw models auth login --provider google-gemini-cli --set-default

默认模型：google-gemini-cli/gemini-3-flash-preview。你不需要把客户端 id 或密钥粘贴到 openclaw.json 中。CLI 登录流程会将令牌存储在 Gateway 网关主机上的凭证配置文件中。

Set project (if needed)

如果登录后请求失败，请在 Gateway 网关主机上设置 GOOGLE_CLOUD_PROJECT 或 GOOGLE_CLOUD_PROJECT_ID。

Gemini CLI JSON 回复会从 response 解析；用量会回退到 stats，其中 stats.cached 会规范化为 OpenClaw cacheRead。

Z.AI（GLM）

提供商：zai
凭证：ZAI_API_KEY
示例模型：zai/glm-5.1
CLI：openclaw onboard --auth-choice zai-api-key
- 别名：z.ai/* 和 z-ai/* 会规范化为 zai/*
- zai-api-key 会自动检测匹配的 Z.AI 端点；zai-coding-global、zai-coding-cn、zai-global 和 zai-cn 会强制使用特定入口面

Vercel AI Gateway 网关

提供商：vercel-ai-gateway
凭证：AI_GATEWAY_API_KEY
示例模型：vercel-ai-gateway/anthropic/claude-opus-4.6、vercel-ai-gateway/moonshotai/kimi-k2.6
CLI：openclaw onboard --auth-choice ai-gateway-api-key

Kilo Gateway 网关

提供商：kilocode
凭证：KILOCODE_API_KEY
示例模型：kilocode/kilo/auto
CLI：openclaw onboard --auth-choice kilocode-api-key
基础 URL：https://api.kilo.ai/api/gateway/
静态回退目录随附 kilocode/kilo/auto；实时 https://api.kilo.ai/api/gateway/models 设备发现可以进一步扩展运行时目录。
kilocode/kilo/auto 背后的精确上游路由由 Kilo Gateway 网关负责，不在 OpenClaw 中硬编码。

设置详情请参阅 /providers/kilocode。

其他内置提供商插件

提供商	Id	凭证环境变量	示例模型
BytePlus	`byteplus` / `byteplus-plan`	`BYTEPLUS_API_KEY`	`byteplus-plan/ark-code-latest`
Cerebras	`cerebras`	`CEREBRAS_API_KEY`	`cerebras/zai-glm-4.7`
Cloudflare AI Gateway	`cloudflare-ai-gateway`	`CLOUDFLARE_AI_GATEWAY_API_KEY`	—
DeepInfra	`deepinfra`	`DEEPINFRA_API_KEY`	`deepinfra/deepseek-ai/DeepSeek-V3.2`
DeepSeek	`deepseek`	`DEEPSEEK_API_KEY`	`deepseek/deepseek-v4-flash`
GitHub Copilot	`github-copilot`	`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`	—
Groq	`groq`	`GROQ_API_KEY`	—
Hugging Face Inference	`huggingface`	`HUGGINGFACE_HUB_TOKEN` 或 `HF_TOKEN`	`huggingface/deepseek-ai/DeepSeek-R1`
Kilo Gateway	`kilocode`	`KILOCODE_API_KEY`	`kilocode/kilo/auto`
Kimi Coding	`kimi`	`KIMI_API_KEY` 或 `KIMICODE_API_KEY`	`kimi/kimi-code`
MiniMax	`minimax` / `minimax-portal`	`MINIMAX_API_KEY` / `MINIMAX_OAUTH_TOKEN`	`minimax/MiniMax-M2.7`
Mistral	`mistral`	`MISTRAL_API_KEY`	`mistral/mistral-large-latest`
Moonshot	`moonshot`	`MOONSHOT_API_KEY`	`moonshot/kimi-k2.6`
NVIDIA	`nvidia`	`NVIDIA_API_KEY`	`nvidia/nvidia/nemotron-3-super-120b-a12b`
OpenRouter	`openrouter`	`OPENROUTER_API_KEY`	`openrouter/auto`
Qianfan	`qianfan`	`QIANFAN_API_KEY`	`qianfan/deepseek-v3.2`
Qwen Cloud	`qwen`	`QWEN_API_KEY` / `MODELSTUDIO_API_KEY` / `DASHSCOPE_API_KEY`	`qwen/qwen3.5-plus`
StepFun	`stepfun` / `stepfun-plan`	`STEPFUN_API_KEY`	`stepfun/step-3.5-flash`
Together	`together`	`TOGETHER_API_KEY`	`together/moonshotai/Kimi-K2.5`
Venice	`venice`	`VENICE_API_KEY`	—
Vercel AI Gateway	`vercel-ai-gateway`	`AI_GATEWAY_API_KEY`	`vercel-ai-gateway/anthropic/claude-opus-4.6`
Volcano Engine（Doubao）	`volcengine` / `volcengine-plan`	`VOLCANO_ENGINE_API_KEY`	`volcengine-plan/ark-code-latest`
xAI	`xai`	`XAI_API_KEY`	`xai/grok-4.3`
Xiaomi	`xiaomi`	`XIAOMI_API_KEY`	`xiaomi/mimo-v2-flash`

值得了解的特性

OpenRouter

仅在已验证的 openrouter.ai 路由上应用其应用归因标头和 Anthropic cache_control 标记。DeepSeek、Moonshot 和 ZAI refs 可用于 OpenRouter 管理的提示缓存 TTL，但不会接收 Anthropic 缓存标记。作为代理式 OpenAI 兼容路径，它会跳过仅适用于原生 OpenAI 的成形处理（serviceTier、Responses store、提示缓存提示、OpenAI reasoning 兼容）。Gemini 后端的 refs 仅保留代理 Gemini 思考签名清理。

Kilo Gateway

Gemini 后端的 refs 遵循相同的代理 Gemini 清理路径；kilocode/kilo/auto 和其他不支持代理推理的 refs 会跳过代理推理注入。

MiniMax

API key 新手引导会写入显式的纯文本 M2.7 聊天模型定义；图像理解仍由插件拥有的 MiniMax-VL-01 媒体提供商处理。

NVIDIA

模型 ID 使用 nvidia/<vendor>/<model> 命名空间（例如 nvidia/nvidia/nemotron-... 以及 nvidia/moonshotai/kimi-k2.5）；选择器会保留字面上的 <provider>/<model-id> 组合，而发送到 API 的规范键仍保持单前缀。

xAI

使用 xAI Responses 路径。grok-4.3 是内置的默认聊天模型。/fast 或 params.fastMode: true 会将 grok-3、grok-3-mini、grok-4 和 grok-4-0709 重写为其 *-fast 变体。tool_stream 默认开启；可通过 agents.defaults.models["xai/<model>"].params.tool_stream=false 禁用。

Cerebras

作为内置的 cerebras 提供商插件随附。GLM 使用 zai-glm-4.7；OpenAI 兼容基础 URL 为 https://api.cerebras.ai/v1。

通过 `models.providers` 配置的提供商（自定义/基础 URL）

使用 models.providers（或 models.json）添加自定义提供商或 OpenAI/Anthropic 兼容代理。下方许多内置提供商插件已经发布默认目录。只有在你想覆盖默认基础 URL、标头或模型列表时，才使用显式的 models.providers.<id> 条目。 Gateway 网关模型能力检查也会读取显式的 models.providers.<id>.models[] 元数据。如果自定义或代理模型接受图像，请在该模型上设置 input: ["text", "image"]，这样 WebChat 和节点来源附件路径会将图像作为原生模型输入传递，而不是作为纯文本媒体 refs。

Moonshot AI (Kimi)

Moonshot 作为内置提供商插件随附。默认使用内置提供商，只有在需要覆盖基础 URL 或模型元数据时，才添加显式的 models.providers.moonshot 条目：

提供商：moonshot
凭证：MOONSHOT_API_KEY
示例模型：moonshot/kimi-k2.6
CLI：openclaw onboard --auth-choice moonshot-api-key 或 openclaw onboard --auth-choice moonshot-api-key-cn

Kimi K2 模型 ID：

moonshot/kimi-k2.6
moonshot/kimi-k2.5
moonshot/kimi-k2-thinking
moonshot/kimi-k2-thinking-turbo
moonshot/kimi-k2-turbo

{
  agents: {
    defaults: { model: { primary: "moonshot/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" }],
      },
    },
  },
}

Kimi 编程

Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点：

提供商：kimi
凭证：KIMI_API_KEY
示例模型：kimi/kimi-code

{
  env: { KIMI_API_KEY: "sk-..." },
  agents: {
    defaults: { model: { primary: "kimi/kimi-code" } },
  },
}

旧版 kimi/k2p5 仍作为兼容模型 ID 被接受。

Volcano Engine（Doubao）

Volcano Engine（火山引擎）提供在中国访问 Doubao 和其他模型的能力。

提供商：volcengine（编码：volcengine-plan）
认证：VOLCANO_ENGINE_API_KEY
示例模型：volcengine-plan/ark-code-latest
CLI：openclaw onboard --auth-choice volcengine-api-key

{
  agents: {
    defaults: { model: { primary: "volcengine-plan/ark-code-latest" } },
  },
}

新手引导默认使用编码表面，但通用的 volcengine/* 目录会同时注册。在新手引导/配置模型选择器中，Volcengine 认证选项会优先显示 volcengine/* 和 volcengine-plan/* 两类行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示空的提供商限定选择器。

标准模型
编码模型（volcengine-plan）

volcengine/doubao-seed-1-8-251228（Doubao Seed 1.8）
volcengine/doubao-seed-code-preview-251028
volcengine/kimi-k2-5-260127（Kimi K2.5）
volcengine/glm-4-7-251222（GLM 4.7）
volcengine/deepseek-v3-2-251201（DeepSeek V3.2 128K）

volcengine-plan/ark-code-latest
volcengine-plan/doubao-seed-code
volcengine-plan/kimi-k2.5
volcengine-plan/kimi-k2-thinking
volcengine-plan/glm-4.7

BytePlus（国际版）

BytePlus ARK 为国际用户提供访问与 Volcano Engine 相同模型的能力。

提供商：byteplus（编码：byteplus-plan）
认证：BYTEPLUS_API_KEY
示例模型：byteplus-plan/ark-code-latest
CLI：openclaw onboard --auth-choice byteplus-api-key

{
  agents: {
    defaults: { model: { primary: "byteplus-plan/ark-code-latest" } },
  },
}

新手引导默认使用编码表面，但通用的 byteplus/* 目录会同时注册。在新手引导/配置模型选择器中，BytePlus 认证选项会优先显示 byteplus/* 和 byteplus-plan/* 两类行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示空的提供商限定选择器。

标准模型
编码模型（byteplus-plan）

byteplus/seed-1-8-251228（Seed 1.8）
byteplus/kimi-k2-5-260127（Kimi K2.5）
byteplus/glm-4-7-251222（GLM 4.7）

byteplus-plan/ark-code-latest
byteplus-plan/doubao-seed-code
byteplus-plan/kimi-k2.5
byteplus-plan/kimi-k2-thinking
byteplus-plan/glm-4.7

Synthetic

Synthetic 通过 synthetic 提供商提供 Anthropic 兼容模型：

提供商：synthetic
认证：SYNTHETIC_API_KEY
示例模型：synthetic/hf:MiniMaxAI/MiniMax-M2.5
CLI：openclaw onboard --auth-choice synthetic-api-key

{
  agents: {
    defaults: { model: { primary: "synthetic/hf:MiniMaxAI/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" }],
      },
    },
  },
}

MiniMax

MiniMax 通过 models.providers 配置，因为它使用自定义端点：

MiniMax OAuth（全球）：--auth-choice minimax-global-oauth
MiniMax OAuth（中国）：--auth-choice minimax-cn-oauth
MiniMax API 密钥（全球）：--auth-choice minimax-global-api
MiniMax API 密钥（中国）：--auth-choice minimax-cn-api
认证：minimax 使用 MINIMAX_API_KEY；minimax-portal 使用 MINIMAX_OAUTH_TOKEN 或 MINIMAX_API_KEY

请参阅 /providers/minimax 了解设置详情、模型选项和配置片段。

在 MiniMax 的 Anthropic 兼容流式传输路径上，除非你显式设置 thinking，否则 OpenClaw 默认会禁用它，并且 /fast on 会将 MiniMax-M2.7 重写为 MiniMax-M2.7-highspeed。

由插件拥有的能力划分：

文本/聊天默认值保留在 minimax/MiniMax-M2.7
图像生成使用 minimax/image-01 或 minimax-portal/image-01
图像理解在两个 MiniMax 认证路径上都由插件拥有，使用 MiniMax-VL-01
Web 搜索保留在提供商 ID minimax 上

LM Studio

LM Studio 作为内置提供商插件随附，使用原生 API：

提供商：lmstudio
认证：LM_API_TOKEN
默认推理基础 URL：http://localhost:1234/v1

然后设置一个模型（替换为 http://localhost:1234/api/v1/models 返回的某个 ID）：

{
  agents: {
    defaults: { model: { primary: "lmstudio/openai/gpt-oss-20b" } },
  },
}

OpenClaw 使用 LM Studio 的原生 /api/v1/models 和 /api/v1/models/load 进行发现 + 自动加载，并默认使用 /v1/chat/completions 进行推理。如果你希望由 LM Studio JIT 加载、TTL 和自动驱逐来接管模型生命周期，请设置 models.providers.lmstudio.params.preload: false。请参阅 /providers/lmstudio 了解设置和故障排除。

Ollama

Ollama 作为内置提供商插件随附，并使用 Ollama 的原生 API：

提供商：ollama
认证：不需要（本地服务器）
示例模型：ollama/llama3.3
安装：https://ollama.com/download

# Install Ollama, then pull a model:
ollama pull llama3.3

{
  agents: {
    defaults: { model: { primary: "ollama/llama3.3" } },
  },
}

当你使用 OLLAMA_API_KEY 选择启用时，OpenClaw 会在本地的 http://127.0.0.1:11434 检测 Ollama，并且内置提供商插件会将 Ollama 直接加入 openclaw onboard 和模型选择器。请参阅 /providers/ollama 了解新手引导、云端/本地模式和自定义配置。

vLLM

vLLM 作为内置提供商插件随附，用于本地/自托管的 OpenAI 兼容服务器：

提供商：vllm
认证：可选（取决于你的服务器）
默认基础 URL：http://127.0.0.1:8000/v1

若要选择启用本地自动发现（如果你的服务器不强制认证，任意值都可以）：

export VLLM_API_KEY="vllm-local"

然后设置一个模型（替换为 /v1/models 返回的某个 ID）：

{
  agents: {
    defaults: { model: { primary: "vllm/your-model-id" } },
  },
}

请参阅 /providers/vllm 了解详情。

SGLang

SGLang 作为内置提供商插件随附，用于快速的自托管 OpenAI 兼容服务器：

提供商：sglang
认证：可选（取决于你的服务器）
默认基础 URL：http://127.0.0.1:30000/v1

若要选择启用本地自动发现（如果你的服务器不强制认证，任意值都可以）：

export SGLANG_API_KEY="sglang-local"

然后设置一个模型（替换为 /v1/models 返回的某个 ID）：

{
  agents: {
    defaults: { model: { primary: "sglang/your-model-id" } },
  },
}

请参阅 /providers/sglang 了解详情。

本地代理（LM Studio、vLLM、LiteLLM 等）

示例（OpenAI 兼容）：

{
  agents: {
    defaults: {
      model: { primary: "lmstudio/my-local-model" },
      models: { "lmstudio/my-local-model": { alias: "Local" } },
    },
  },
  models: {
    providers: {
      lmstudio: {
        baseUrl: "http://localhost:1234/v1",
        apiKey: "${LM_API_TOKEN}",
        api: "openai-completions",
        timeoutSeconds: 300,
        models: [
          {
            id: "my-local-model",
            name: "Local Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 200000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

默认可选字段

对于自定义提供商，reasoning、input、cost、contextWindow 和 maxTokens 都是可选的。省略时，OpenClaw 默认使用：

reasoning: false
input: ["text"]
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }
contextWindow: 200000
maxTokens: 8192

建议：设置与你的代理/模型限制匹配的显式值。

代理路由整形规则

对于非原生端点（任何非空且主机不是 api.openai.com 的 baseUrl）上的 api: "openai-completions"，OpenClaw 会强制设置 compat.supportsDeveloperRole: false，以避免因不支持 developer 角色而触发提供商 400 错误。
代理式 OpenAI 兼容路由也会跳过仅适用于原生 OpenAI 的请求整形：没有 service_tier、没有 Responses store、没有 Completions store、没有提示缓存提示、没有 OpenAI reasoning 兼容载荷整形，也没有隐藏的 OpenClaw 归因标头。
对于需要供应商特定字段的 OpenAI 兼容 Completions 代理，请设置 agents.defaults.models["provider/model"].params.extra_body（或 extraBody），以将额外 JSON 合并到出站请求体中。
对于 vLLM 聊天模板控制项，请设置 agents.defaults.models["provider/model"].params.chat_template_kwargs。当会话 thinking 级别关闭时，内置 vLLM 插件会自动为 vllm/nemotron-3-* 发送 enable_thinking: false 和 force_nonempty_content: true。
对于较慢的本地模型或远程 LAN/tailnet 主机，请设置 models.providers.<id>.timeoutSeconds。这会延长提供商模型 HTTP 请求处理时间，包括连接、标头、正文流式传输以及总的受保护 fetch 中止，而不会增加整个智能体运行时超时时间。
模型提供商 HTTP 调用仅允许为已配置提供商 baseUrl 主机名使用 198.18.0.0/15 和 fc00::/7 中的 Surge、Clash 和 sing-box fake-IP DNS 响应。其他私有、回环、链路本地和元数据目标仍然需要显式选择启用 models.providers.<id>.request.allowPrivateNetwork: true。
如果 baseUrl 为空或省略，OpenClaw 会保留默认 OpenAI 行为（解析到 api.openai.com）。
为了安全，在非原生 openai-completions 端点上，即使显式设置 compat.supportsDeveloperRole: true，仍会被覆盖。
对于非直连端点上的 api: "anthropic-messages"（除规范的 anthropic 之外的任何提供商，或主机不是公共 api.anthropic.com 端点的自定义 models.providers.anthropic.baseUrl），OpenClaw 会抑制隐式 Anthropic beta 标头，例如 claude-code-20250219、interleaved-thinking-2025-05-14 和 OAuth 标记，因此自定义 Anthropic 兼容代理不会拒绝不支持的 beta 标志。如果你的代理需要特定 beta 功能，请显式设置 models.providers.<id>.headers["anthropic-beta"]。

CLI 示例

openclaw onboard --auth-choice opencode-zen
openclaw models set opencode/claude-opus-4-6
openclaw models list

另请参阅：配置获取完整配置示例。

概览

模型概念

配置

提供商

快速规则

插件拥有的提供商行为

API key 轮换

内置提供商（pi-ai 目录）

OpenAI

Anthropic

OpenAI Codex OAuth

其他订阅式托管选项

GLM 模型

MiniMax

Qwen Cloud

OpenCode

Google Gemini（API key）

Google Vertex 和 Gemini CLI

Z.AI（GLM）

Vercel AI Gateway 网关

Kilo Gateway 网关

其他内置提供商插件

值得了解的特性

通过 `models.providers` 配置的提供商（自定义/基础 URL）

Moonshot AI (Kimi)

Kimi 编程

Volcano Engine（Doubao）

BytePlus（国际版）

Synthetic

MiniMax

LM Studio

Ollama

vLLM

SGLang

本地代理（LM Studio、vLLM、LiteLLM 等）

CLI 示例

相关内容

概览

模型概念

配置

提供商

Documentation Index

​快速规则

​插件拥有的提供商行为

​API key 轮换

​内置提供商（pi-ai 目录）

​OpenAI

​Anthropic

​OpenAI Codex OAuth

​其他订阅式托管选项

GLM 模型

MiniMax

Qwen Cloud

​OpenCode

​Google Gemini（API key）

​Google Vertex 和 Gemini CLI

​Z.AI（GLM）

​Vercel AI Gateway 网关

​Kilo Gateway 网关

​其他内置提供商插件

​值得了解的特性

​通过 models.providers 配置的提供商（自定义/基础 URL）

​Moonshot AI (Kimi)

​Kimi 编程

​Volcano Engine（Doubao）

​BytePlus（国际版）

​Synthetic

​MiniMax

​LM Studio

​Ollama

​vLLM

​SGLang

​本地代理（LM Studio、vLLM、LiteLLM 等）

​CLI 示例

​相关内容

快速规则

插件拥有的提供商行为

API key 轮换

内置提供商（pi-ai 目录）

OpenAI

Anthropic

OpenAI Codex OAuth

其他订阅式托管选项

OpenCode

Google Gemini（API key）

Google Vertex 和 Gemini CLI

Z.AI（GLM）

Vercel AI Gateway 网关

Kilo Gateway 网关

其他内置提供商插件

值得了解的特性

通过 `models.providers` 配置的提供商（自定义/基础 URL）

Moonshot AI (Kimi)

Kimi 编程

Volcano Engine（Doubao）

BytePlus（国际版）

Synthetic

MiniMax

LM Studio

Ollama

vLLM

SGLang

本地代理（LM Studio、vLLM、LiteLLM 等）

CLI 示例

相关内容