模型提供商
本页面涵盖 LLM/模型提供商(不包括 WhatsApp/Telegram 等聊天频道)。 有关模型选择规则,请参阅 /concepts/models。快速规则
- 模型引用使用
provider/model(例如:opencode/claude-opus-4-6)。 - 如果您设置
agents.defaults.models,它将成为允许列表。 - CLI 辅助工具:
openclaw onboard、openclaw models list、openclaw models set <provider/model>。 - 提供商插件可以通过
registerProvider({ catalog })注入模型目录; OpenClaw 在写入models.json之前将该输出合并到models.providers中。 - 提供商清单可以声明
providerAuthEnvVars,因此基于通用环境的身份验证探针不需要加载插件运行时。剩余的核心环境变量映射现在仅用于非插件/核心提供商以及少数通用优先级的情况,例如 Anthropic API 密钥优先的新手引导。 - 提供商插件还可以通过
resolveDynamicModel、prepareDynamicModel、normalizeResolvedModel、capabilities、prepareExtraParams、wrapStreamFn、formatApiKey、refreshOAuth、buildAuthDoctorHint、isCacheTtlEligible、buildMissingAuthMessage、suppressBuiltInModel、augmentModelCatalog、isBinaryThinking、supportsXHighThinking、resolveDefaultThinkingLevel、isModernModelRef、prepareRuntimeAuth、resolveUsageAuth和fetchUsageSnapshot拥有提供商运行时行为。 - 注意:提供商运行时
capabilities是共享的运行器元数据(提供商 系列、转录/工具特性、传输/缓存提示)。它与公共能力模型 不同,后者描述插件注册的内容(文本推理、语音等)。
插件拥有的提供商行为
提供商插件现在可以拥有大多数特定于提供商的逻辑,而 OpenClaw 保留 通用推理循环。 典型分工:auth[].run/auth[].runNonInteractive:提供商拥有openclaw onboard、openclaw models auth和 无头设置的新手引导/登录流程wizard.setup/wizard.modelPicker:提供商拥有身份验证选择标签、 传统别名、新手引导允许列表提示以及新手引导/模型选择器中的设置条目catalog:提供商出现在models.providers中resolveDynamicModel:提供商接受本地静态目录中尚不存在的模型 IDprepareDynamicModel:提供商在重试动态解析之前需要元数据刷新normalizeResolvedModel:提供商需要传输或基础 URL 重写capabilities:提供商发布转录/工具/提供商系列特性prepareExtraParams:提供商设置或规范化每个模型的请求参数wrapStreamFn:提供商应用请求头/正文/模型兼容性包装器formatApiKey:提供商将存储的身份验证配置格式化为传输 所需的运行时apiKey字符串refreshOAuth:当共享pi-ai刷新器 不够用时,提供商拥有 OAuth 刷新buildAuthDoctorHint:当 OAuth 刷新 失败时,提供商附加修复指南isCacheTtlEligible:提供商决定哪些上游模型 ID 支持 prompt-cache TTLbuildMissingAuthMessage:提供商使用特定于提供商的恢复提示替换通用身份验证存储错误suppressBuiltInModel:提供商隐藏过时的上游行,并且可以为直接解析失败返回供应商拥有的错误augmentModelCatalog:提供商在发现和配置合并后附加合成/最终目录行isBinaryThinking:提供商拥有二元开/关思考用户体验 (UX)supportsXHighThinking:提供商将所选模型选择加入xhighresolveDefaultThinkingLevel:提供商拥有模型系列的默认/think策略isModernModelRef:提供商拥有实时/冒烟首选模型匹配prepareRuntimeAuth:提供商将配置的凭据转换为短期运行时令牌resolveUsageAuth:提供商解析/usage的使用/配额凭据以及相关的状态/报告表面fetchUsageSnapshot:提供商拥有使用端点获取/解析,而核心仍然拥有摘要外壳和格式化
anthropic:Claude 4.6 前向兼容回退、身份验证修复提示、使用端点获取和缓存 TTL/提供商系列元数据openrouter:透传模型 ID、请求包装器、提供商功能提示和缓存 TTL 策略github-copilot:新手引导/设备登录、前向兼容模型回退、Claude 思考记录提示、运行时令牌交换和使用端点获取openai:GPT-5.4 前向兼容回退、直接 OpenAI 传输规范化、感知 Codex 的缺失身份验证提示、Spark 抑制、合成 OpenAI/Codex 目录行、思考/实时模型策略和提供商系列元数据google和google-gemini-cli:Gemini 3.1 前向兼容回退和现代模型匹配;Gemini CLI OAuth 还拥有使用表面的身份验证配置文件令牌格式化、使用令牌解析和配额端点获取moonshot:共享传输、插件拥有的思考负载规范化kilocode:共享传输、插件拥有的请求头、推理负载 标准化、Gemini 转录提示以及缓存 TTL 策略zai:GLM-5 向后兼容回退、tool_stream默认值、缓存 TTL 策略、二进制思考/实时模型策略,以及使用情况认证 + 配额获取mistral、opencode和opencode-go:插件拥有的功能元数据byteplus、cloudflare-ai-gateway、huggingface、kimi-coding、modelstudio、nvidia、qianfan、synthetic、together、venice、vercel-ai-gateway和volcengine:仅限插件拥有的目录qwen-portal:插件拥有的目录、OAuth 登录和 OAuth 刷新minimax和xiaomi:插件拥有的目录以及使用情况认证/快照逻辑
openai 插件现在拥有以下两个提供商 ID:openai 和
openai-codex。
这涵盖了仍然符合 OpenClaw 常规传输方式的提供商。需要完全自定义请求执行器的提供商属于一个独立、更深层的扩展
表面。
API 密钥轮换
- 支持所选提供商的通用提供商轮换。
- 通过以下方式配置多个密钥:
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)。 - 非速率限制的失败会立即报错;不会尝试轮换密钥。
- 当所有候选密钥均失败时,将返回最后一次尝试的最终错误。
内置提供商(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.4、openai/gpt-5.4-pro - 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 优先处理 - 可以通过
agents.defaults.models["<provider>/<model>"].params.fastMode为每个模型启用 OpenAI 快速模式 openai/gpt-5.3-codex-spark在 OpenClaw 中被有意屏蔽,因为实时 OpenAI API 会拒绝它;Spark 被视为仅限 Codex 使用
Anthropic
- 提供商:
anthropic - 身份验证:
ANTHROPIC_API_KEY或claude setup-token - 可选轮换:
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 token(粘贴 setup-token)或openclaw models auth paste-token --provider anthropic - 直接 API 密钥模型支持共享
/fast切换开关和params.fastMode;OpenClaw 将其映射到 Anthropicservice_tier(auto对比standard_only) - 政策说明:支持 setup-token 属于技术兼容性;Anthropic 过去曾阻止在 Claude Code 之外使用某些订阅。请验证当前的 Anthropic 条款,并根据您的风险承受能力做出决定。
- 建议:与订阅 setup-token 认证相比,Anthropic API 密钥认证是更安全、更推荐的方式。
OpenAI Code (Codex)
- 提供商:
openai-codex - 认证:OAuth (ChatGPT)
- 示例模型:
openai-codex/gpt-5.4 - 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按模型覆盖("sse"、"websocket"或"auto") - 与直接
openai/*共享相同的/fast切换开关和params.fastMode配置 - 当 Codex OAuth 目录公开
openai-codex/gpt-5.3-codex-spark时,该模型仍然可用;取决于权限 - 政策说明:明确支持将 OpenAI Codex OAuth 用于像 OpenClaw 这样的外部工具/工作流。
OpenCode
- 认证:
OPENCODE_API_KEY(或OPENCODE_ZEN_API_KEY) - Zen 运行时提供商:
opencode - Go 运行时提供商:
opencode-go - 示例模型:
opencode/claude-opus-4-6、opencode-go/kimi-k2.5 - CLI:
openclaw onboard --auth-choice opencode-zen或openclaw onboard --auth-choice opencode-go
Google Gemini (API 密钥)
- 提供商:
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 - CLI:
openclaw onboard --auth-choice gemini-api-key
Google Vertex 和 Gemini CLI
- 提供商:
google-vertex,google-gemini-cli - 身份验证:Vertex 使用 gcloud ADC;Gemini CLI 使用其 OAuth 流程
- 注意:CLI 中的 Gemini OAuth OpenClaw 是非官方集成。有用户报告在使用第三方客户端后 Google 账户受到限制。如果您选择继续,请查阅 Google 条款并使用非关键账户。
- Gemini CLI OAuth 作为内置
google插件的一部分提供。- 启用:
openclaw plugins enable google - 登录:
openclaw models auth login --provider google-gemini-cli --set-default - 注意:您不要将客户端 ID 或密钥粘贴到
openclaw.json中。CLI 登录流程会将令牌存储在 Gateway 主机上的身份验证配置文件中。
- 启用:
Z.AI (GLM)
- 提供商:
zai - 身份验证:
ZAI_API_KEY - 示例模型:
zai/glm-5 - CLI:
openclaw onboard --auth-choice zai-api-key- 别名:
z.ai/*和z-ai/*会规范化为zai/*
- 别名:
Vercel AI Gateway(网关)
- 提供商:
vercel-ai-gateway - 身份验证:
AI_GATEWAY_API_KEY - 示例模型:
vercel-ai-gateway/anthropic/claude-opus-4.6 - CLI:
openclaw onboard --auth-choice ai-gateway-api-key
Kilo Gateway(网关)
- 提供商:
kilocode - 身份验证:
KILOCODE_API_KEY - 示例模型:
kilocode/anthropic/claude-opus-4.6 - CLI:
openclaw onboard --kilocode-api-key <key> - 基础 URL:
https://api.kilo.ai/api/gateway/ - 扩展的内置目录包括 GLM-5 Free、MiniMax M2.5 Free、GPT-5.2、Gemini 3 Pro Preview、Gemini 3 Flash Preview、Grok Code Fast 1 和 Kimi K2.5。
其他内置提供商插件
- OpenRouter:
openrouter(OPENROUTER_API_KEY) - 示例模型:
openrouter/anthropic/claude-sonnet-4-6 - Kilo Gateway(网关):
kilocode(KILOCODE_API_KEY) - 示例模型:
kilocode/anthropic/claude-opus-4.6 - MiniMax:
minimax(MINIMAX_API_KEY) - Moonshot:
moonshot(MOONSHOT_API_KEY) - Kimi Coding:
kimi-coding(KIMI_API_KEY或KIMICODE_API_KEY) - Qianfan:
qianfan(QIANFAN_API_KEY) - Model Studio:
modelstudio(MODELSTUDIO_API_KEY) - NVIDIA:
nvidia(NVIDIA_API_KEY) - Together:
together(TOGETHER_API_KEY) - Venice:
venice(VENICE_API_KEY) - Xiaomi:
xiaomi(XIAOMI_API_KEY) - Vercel AI Gateway(网关):
vercel-ai-gateway(AI_GATEWAY_API_KEY) - Hugging Face Inference:
huggingface(HUGGINGFACE_HUB_TOKEN或HF_TOKEN) - Cloudflare AI Gateway(网关):
cloudflare-ai-gateway(CLOUDFLARE_AI_GATEWAY_API_KEY) - Volcengine:
volcengine(VOLCANO_ENGINE_API_KEY) - BytePlus:
byteplus(BYTEPLUS_API_KEY) - xAI:
xai(XAI_API_KEY) - Mistral:
mistral(MISTRAL_API_KEY) - 示例模型:
mistral/mistral-large-latest - CLI:
openclaw onboard --auth-choice mistral-api-key - Groq:
groq(GROQ_API_KEY) - Cerebras:
cerebras(CEREBRAS_API_KEY)- Cerebras 上的 GLM 模型使用 id
zai-glm-4.7和zai-glm-4.6。 - OpenAI 兼容的基础 URL:
https://api.cerebras.ai/v1。
- Cerebras 上的 GLM 模型使用 id
- GitHub Copilot:
github-copilot(COPILOT_GITHUB_TOKEN/GH_TOKEN/GITHUB_TOKEN) - Hugging Face Inference 示例模型:
huggingface/deepseek-ai/DeepSeek-R1; CLI:openclaw onboard --auth-choice huggingface-api-key。参见 Hugging Face (Inference)。
通过 models.providers 提供商(自定义/基础 URL)
使用 models.providers(或 models.json)添加自定义提供商或
OpenAI/Anthropic 兼容的代理。
下面的许多捆绑提供商插件已经发布了默认目录。
仅在您想要覆盖默认基础 URL、标头或模型列表时,才使用显式的 models.providers.<id> 条目。
Moonshot AI (Kimi)
Moonshot 使用 OpenAI 兼容的端点,因此将其配置为自定义提供商:- 提供商:
moonshot - 认证:
MOONSHOT_API_KEY - 示例模型:
moonshot/kimi-k2.5
moonshot/kimi-k2.5moonshot/kimi-k2-0905-previewmoonshot/kimi-k2-turbo-previewmoonshot/kimi-k2-thinkingmoonshot/kimi-k2-thinking-turbo
Kimi Coding
Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点:- 提供商:
kimi-coding - 认证:
KIMI_API_KEY - 示例模型:
kimi-coding/k2p5
Qwen OAuth (免费层)
Qwen 通过设备码流提供 OAuth 访问 Qwen Coder + Vision。 捆绑的提供商插件默认已启用,因此只需登录:qwen-portal/coder-modelqwen-portal/vision-model
Volcano Engine (Doubao)
Volcano Engine (火山引擎) 提供对 Doubao 和中国其他模型的访问。- 提供商:
volcengine(编程:volcengine-plan) - 认证:
VOLCANO_ENGINE_API_KEY - 示例模型:
volcengine/doubao-seed-1-8-251228 - CLI:
openclaw onboard --auth-choice volcengine-api-key
volcengine/doubao-seed-1-8-251228(Doubao Seed 1.8)volcengine/doubao-seed-code-preview-251028volcengine/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):
volcengine-plan/ark-code-latestvolcengine-plan/doubao-seed-codevolcengine-plan/kimi-k2.5volcengine-plan/kimi-k2-thinkingvolcengine-plan/glm-4.7
BytePlus (International)
BytePlus ARK 为国际用户提供与火山引擎相同的模型。- 提供商:
byteplus(编码:byteplus-plan) - 认证:
BYTEPLUS_API_KEY - 示例模型:
byteplus/seed-1-8-251228 - CLI:
openclaw onboard --auth-choice byteplus-api-key
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):
byteplus-plan/ark-code-latestbyteplus-plan/doubao-seed-codebyteplus-plan/kimi-k2.5byteplus-plan/kimi-k2-thinkingbyteplus-plan/glm-4.7
Synthetic
Synthetic 在synthetic 提供商后面提供 Anthropic-compatible 模型:
- 提供商:
synthetic - 认证:
SYNTHETIC_API_KEY - 示例模型:
synthetic/hf:MiniMaxAI/MiniMax-M2.5 - CLI:
openclaw onboard --auth-choice synthetic-api-key
MiniMax
MiniMax 通过models.providers 进行配置,因为它使用自定义端点:
- MiniMax (Anthropic‑compatible):
--auth-choice minimax-api - 认证:
MINIMAX_API_KEY
Ollama
Ollama 作为捆绑的提供商插件提供,并使用 Ollama 的原生 API:- 提供商:
ollama - 认证:无(本地服务器)
- 示例模型:
ollama/llama3.3 - 安装:https://ollama.com/download
OLLAMA_API_KEY 选择加入时,Ollama 会在 http://127.0.0.1:11434 本地被检测到,并且捆绑的提供商插件会将 Ollama 直接添加到 openclaw onboard 和模型选择器中。有关新手引导、云/本地模式和自定义配置,请参阅 /providers/ollama。
vLLM
vLLM 作为捆绑的提供商插件提供,用于本地/自托管的 OpenAI-compatible 服务器:- 提供商:
vllm - 认证:可选(取决于您的服务器)
- 默认基础 URL:
http://127.0.0.1:8000/v1
/v1/models 返回的 ID 之一):
SGLang
SGLang 作为捆绑的提供商插件提供,用于快速自托管 OpenAI 兼容服务器:- 提供商:
sglang - 身份验证:可选(取决于您的服务器)
- 默认基础 URL:
http://127.0.0.1:30000/v1
/v1/models 返回的 ID 之一):
本地代理(LM Studio、vLLM、LiteLLM 等)
示例(OpenAI 兼容):- 对于自定义提供商,
reasoning、input、cost、contextWindow和maxTokens是可选的。 如果省略,OpenClaw 默认为:reasoning: falseinput: ["text"]cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }contextWindow: 200000maxTokens: 8192
- 建议:设置与您的代理/模型限制匹配的显式值。
- 对于非原生端点上的
api: "openai-completions"(任何主机不是api.openai.com的非空baseUrl),OpenClaw 强制compat.supportsDeveloperRole: false以避免提供商因不支持的developer角色而出现 400 错误。 - 如果
baseUrl为空/省略,OpenClaw 将保留默认的 OpenAI 行为(其解析为api.openai.com)。 - 为了安全起见,显式的
compat.supportsDeveloperRole: true在非原生openai-completions端点上仍会被覆盖。
CLI 示例
本页面源自 openclaw/openclaw,由 BeaversLab 翻译,遵循 MIT 协议 发布。