模型 FAQ
模型与认证配置文件问答。有关安装设置、会话、网关、频道和故障排查,请参阅主要 FAQ。
模型:默认值、选择、别名与切换¶
什么是“默认模型”?
通过以下设置:
模型使用 provider/model 引用(示例:openai/gpt-5.5、anthropic/claude-sonnet-4-6)。请始终显式设置 provider/model。如果省略 provider,OpenClaw 会先尝试别名匹配,然后尝试在已配置的 provider 中唯一匹配该模型 id,最后回退到已配置的默认 provider(已弃用的兼容路径)。如果该 provider 不再拥有已配置的默认模型,OpenClaw 会回退到第一个已配置的 provider/model,而不是过期的默认值。
你推荐使用什么模型?
请使用你的 provider 组合中最强的最新一代模型,尤其是对于启用工具或处理不可信输入的代理——较弱或过度量化的模型更容易受到 Prompt 注入和危险行为的影响(参见安全)。根据代理角色,将更便宜的模型路由到日常/低风险聊天。
按代理路由模型,并使用子代理并行处理长任务(每个子代理消耗自己的 token)。参见模型、子代理、MiniMax和本地模型。
如何在不清空配置的情况下切换模型?
只更改模型相关字段——避免整体替换配置。
- 在聊天中使用
/model <model> -s(仅当前会话) - 所有者/管理员:
/model <model> -a(当前会话和代理默认值) - 所有者/管理员:
/model <model> -g(当前会话和全局默认值) openclaw models set ...(仅更新模型配置)openclaw configure --section model(交互式)- 直接编辑
~/.openclaw/openclaw.json中的agents.defaults.model
不带标志的 /model <model> 仅更改当前会话,对所有者/管理员也是如此,除非你明确选择了更广泛的模型选择作用域。
对于 RPC 编辑,先用 config.schema.lookup 进行检查(规范化路径、浅层 schema 文档、子项摘要),然后在需要部分对象时优先使用 config.patch 而非 config.apply。如果你确实覆盖了配置,请从备份恢复或运行 openclaw doctor 进行修复。
我能否使用自托管模型(llama.cpp、vLLM、Ollama)?
可以——Ollama 是最简单的路径。快速设置:
- 从
https://ollama.com/download安装 Ollama - 拉取一个本地模型,例如
ollama pull gemma4 - 如果还需要云端模型,请运行
ollama signin - 运行
openclaw onboard,选择Ollama,然后选择Local或Cloud + Local
Cloud + Local 为你提供云端模型以及本地 Ollama 模型;kimi-k2.5:cloud 等云端模型无需在本地拉取。如需手动切换:先运行 openclaw models list,然后运行 openclaw models set ollama/<model>。
llmman 是另一种选择:当你希望从 OCI 注册表或 Hugging Face 拉取模型、使用未经修改的上游 llama-server、vllm 或 mlx-lm 引擎,或使用混合路由(将小请求保留在 qwen3.8 等本地模型上,将大请求溢出到托管模型)时。
较小或重度量化的模型更容易受到 Prompt 注入。任何具有工具访问权限的 bot 都应使用大模型;如果你仍然使用小模型,请启用沙箱和严格的工具白名单。
如何即时切换模型(无需重启)?
单独发送一条 /model <name> -s 消息即可仅切换当前会话。如果不带作用域标志,则应用可选的模型选择作用域;保持未设置会将更改保留在当前会话中,对所有者/管理员也是如此。完整命令列表请参阅斜杠命令,包括模型浏览(/model、/models、/model list)、用 /model default -s 仅清除会话级模型覆盖,以及用 /model status 查看端点/API 模式详情。
使用 @profile 为每个会话强制指定特定的认证配置文件:
不带 @profile 的模型选择会保留现有的兼容 profile 固定项。选择其他显式 @profile 后缀即可替换它。使用 /model status 查看当前活动的认证配置文件。/model default 会保留兼容的 auth 固定项,并清除与已配置默认 provider 不匹配的固定项。
如果两个 provider 暴露相同的模型 id,/model 会使用哪一个?
/model provider/model 会选择该确切的 provider 路由。例如,qianfan/deepseek-v4-flash 和 deepseek/deepseek-v4-flash 即使模型 id 相同,也是不同的引用——OpenClaw 不会在裸 id 匹配时静默切换 provider。
用户选择的 /model 引用在回退方面是严格的:如果该 provider/model 不可用,回复会明显失败,而不会回退到 agents.defaults.model.fallbacks。已配置的回退链仍然适用于已配置的默认值、cron 任务主模型以及自动选择的回退状态。当非会话覆盖的运行被允许使用回退时,OpenClaw 会先尝试请求的 provider/model,然后是已配置的回退项,最后是已配置的主模型——因此重复的裸模型 id 永远不会直接跳回默认 provider。
我可以将 GPT 5.5 用于日常任务,将 Codex 5.5 用于编码吗?
是的——模型选择与运行时选择是相互独立的:
- 原生 Codex 编码智能体: 将
agents.defaults.model.primary设置为openai/gpt-5.5。使用openclaw models auth login --provider openai登录以获取 ChatGPT/Codex 订阅身份验证。 - 智能体循环之外直接调用 OpenAI API 的任务: 为图像、嵌入、语音、实时以及其他非智能体 OpenAI API 接口配置
OPENAI_API_KEY。 - OpenAI 智能体 API 密钥认证: 使用有序的
openaiAPI 密钥配置执行/model openai/gpt-5.5。 - 子智能体: 将编码任务路由到一个专注于 Codex 的智能体,该智能体拥有自己的
openai/gpt-5.5模型。
如何为 GPT 5.5 配置快速模式?
- 按会话: 在使用
openai/gpt-5.5时发送/fast on。 - 按模型设置默认值: 将
agents.defaults.models["openai/gpt-5.5"].params.fastMode设置为true。 - 自动截止:
/fast auto或params.fastMode: "auto"会让新的模型调用以快速模式运行,直到截止时间;随后的重试、回退、工具结果或后续调用则不再使用快速模式。截止时间默认为 60 秒;可通过模型上的params.fastAutoOnSeconds进行覆盖。
{
agents: {
defaults: {
models: {
"openai/gpt-5.5": {
params: {
fastMode: "auto",
fastAutoOnSeconds: 30,
},
},
},
},
},
}
在原生 OpenAI Responses 请求中,快速模式映射为 service_tier = "priority";现有的 service_tier 值会被保留,快速模式不会重写 reasoning 或 text.verbosity。会话级 /fast 覆盖优先于配置默认值。
为什么我会看到“Model ... is not allowed”然后没有回复?
如果 agents.defaults.modelPolicy.allow 非空,它将成为 /model、会话覆盖和 --model 的允许列表。选择该列表之外的模型时,会返回以下内容而不是正常回复:
修复方法:将精确模型或提供商通配符(如 "provider/*")添加到指定的 modelPolicy.allow 列表中,移除/清空该列表,或从 /model list 中选择模型。如果该命令还包含 --runtime codex,请先更新允许列表,然后重试相同的 /model provider/model --runtime codex 命令。
为什么我会看到“Unknown model: minimax/MiniMax-M3”?
如果你使用的是较旧的 OpenClaw 版本,请先升级(或从源码 main 分支运行)并重启网关——MiniMax-M3 可能尚未出现在你已安装版本的目录中。否则说明 MiniMax 提供方未配置(未找到提供方条目或身份验证配置),因此该模型无法解析。有关完整修复清单、提供方/模型 ID 表和配置块示例,请参阅 MiniMax 提供方页面上的“故障排除”部分。
我可以将 MiniMax 作为默认模型,并将 OpenAI 用于复杂任务吗?
可以。将 MiniMax 设为默认模型,并逐个会话切换模型——回退机制用于处理错误,而不是“困难任务”,因此请使用 /model 或单独的智能体。
选项 A:按会话切换
{
env: { vars: { MINIMAX_API_KEY: "sk-...", OPENAI_API_KEY: "sk-..." } },
agents: {
defaults: {
model: { primary: "minimax/MiniMax-M3" },
models: {
"minimax/MiniMax-M3": { alias: "minimax" },
"openai/gpt-5.5": { alias: "gpt" },
},
},
},
}
然后执行 /model gpt -s。
选项 B:使用独立智能体 — 智能体 A 默认使用 MiniMax,智能体 B 默认使用 OpenAI;按智能体路由,或使用 /agent 进行切换。
opus / sonnet / gpt 是内置快捷方式吗?
是的——内置简写,仅在目标模型存在于 agents.defaults.models 中时生效:
| 别名 | 解析为 |
|---|---|
opus |
anthropic/claude-opus-5-5 |
sonnet |
anthropic/claude-sonnet-5-5 |
gpt |
openai/gpt-5.4 |
gpt-mini |
openai/gpt-5.4-mini |
gpt-nano |
openai/gpt-5.4-nano |
gemini |
google/gemini-3.1-pro-preview |
gemini-flash |
google/gemini-3-flash-preview |
gemini-flash-lite |
google/gemini-3.1-flash-lite |
你自己的同名别名会覆盖内置别名。
如何定义/覆盖模型快捷方式(别名)?
别名位于 agents.defaults.models.<modelId>.alias:
{
agents: {
defaults: {
model: { primary: "anthropic/claude-opus-4-6" },
models: {
"anthropic/claude-opus-4-6": { alias: "opus" },
"anthropic/claude-sonnet-4-6": { alias: "sonnet" },
},
},
},
}
然后 /model sonnet -s 仅针对当前会话选择该模型 ID。所有者/管理员可以使用 -a 同时更新智能体默认设置,或使用 -g 更新共享的全局默认设置。未加标志的选择遵循 模型选择范围。
如何添加来自 OpenRouter 或 Z.AI 等其他提供方的模型?
OpenRouter(按 token 付费;模型众多):
Z.AI (GLM models):
{
agents: {
defaults: {
model: { primary: "zai/glm-5.1" },
models: { "zai/glm-5.1": {} },
},
},
env: { vars: { ZAI_API_KEY: "..." } },
}
引用的提供方/模型缺少提供方密钥会引发运行时认证错误(例如 No API key found for provider "zai")。
添加新代理后未找到提供方的 API 密钥
新代理无需复制即可读取共享的认证配置文件。其自身的配置文件位于 ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite,并覆盖共享的直读基础配置。参见 认证凭据语义。
修复方法:当代理需要自己的凭据时,在 Gateway 主机上运行 openclaw models auth login --provider <providerId> --agent <agentId>。你也可以在使用 openclaw agents add <id> 创建代理时配置认证。对于 OAuth,当代理需要自己的账户时,请单独登录。完整的 agentDir 复用和凭据共享规则请参阅 多代理路由 —— 切勿跨代理复用 agentDir。
模型故障转移与"所有模型均失败"¶
故障转移是如何工作的?
两个阶段:
- 同一提供方内的认证配置文件轮换。
- 模型回退到
agents.defaults.model.fallbacks中的下一个模型。
冷却时间适用于失败的配置文件(指数退避),因此当提供方受到速率限制或暂时故障时,OpenClaw 仍能持续响应。
速率限制桶涵盖的不只是纯 429:Too many concurrent requests、ThrottlingException、concurrency limit reached、workers_ai ... quota limit exceeded、resource exhausted 以及周期性用量窗口限制(weekly/monthly limit reached)都属于值得触发故障转移的速率限制。
计费响应并不总是 402,某些 402 也会停留在瞬时/速率限制桶中,而不是计费通道。401/403 上明确的计费文本仍然可以路由到计费;提供方特定的文本匹配器(例如 OpenRouter 的 Key limit exceeded)仍限定在其自己的提供方范围内。看起来像可重试的用量窗口或组织/工作区消费限额的 402(daily limit reached, resets tomorrow、organization spending limit exceeded)会被视为 rate_limit,而不是长期的计费禁用。
上下文溢出错误完全不会进入回退路径 —— 像 request_too_large、input exceeds the maximum number of tokens、input token count exceeds the maximum number of input tokens、input is too long for the model 或 ollama error: context length exceeded 这类特征会进入压缩/重试流程,而不是推进模型回退。
通用服务器错误文本比"任何包含 unknown/error 的内容"范围更窄。提供方范围内的瞬时形态中,确实算作故障转移信号的有:Anthropic 仅返回 An unknown error occurred、OpenRouter 仅返回 Provider returned error、停止原因错误如 Unhandled stop reason: error、带有瞬时服务器文本的 JSON api_error 载荷(internal server error、unknown error, 520、upstream error、backend error),以及在提供方上下文匹配时的提供方繁忙错误,如 ModelNotReadyException。像 LLM request failed with an unknown error. 这样的通用内部回退文本保持保守,不会单独触发回退。
'No credentials found for profile anthropic:default' 是什么意思?
认证配置文件 ID anthropic:default 在预期的认证存储中没有凭据。
修复清单:
- 确认配置文件所在位置:共享和代理本地的 SQLite 认证存储。如果旧安装仍然有
auth-profiles.json,请运行openclaw doctor --fix;它是迁移来源,而非运行时存储。 - 确认 Gateway 加载了你的环境变量。仅在你的 shell 中设置的
ANTHROPIC_API_KEY不会传递到通过 systemd/launchd 运行的 Gateway —— 请将其放入~/.openclaw/.env或启用env.shellEnv。 - 确认你在配置正确的代理 —— 使用
--agent <agentId>配合openclaw models auth login来选择其本地存储。 - 运行
openclaw models status --agent <agentId>查看该代理的模型路由和认证状态。仅存储的配置文件并不能证明就绪;参见 正确读取状态。
对于"No credentials found for profile anthropic"(无邮箱后缀):
该运行被固定在一个 Gateway 无法找到的 Anthropic 配置文件上。
- 使用 Claude CLI:在 gateway 主机上运行
openclaw models auth login --provider anthropic --method cli --set-default。 - 更推荐使用 API 密钥:将
ANTHROPIC_API_KEY放入 gateway 主机上的~/.openclaw/.env,然后清除任何强制使用缺失配置文件的固定顺序:
- 远程模式:认证配置文件位于 gateway 机器上,而不是你的笔记本电脑上 —— 请确认你是在那里运行命令。
为什么它也尝试了 Google Gemini 并失败?
如果你的模型配置将 Google Gemini 作为回退(或者你切换到了 Gemini 简写),OpenClaw 会在回退期间尝试它。未配置 Google 凭据会报 No API key found for provider "google"。修复方法:添加 Google 认证,或从 agents.defaults.model.fallbacks/别名中移除 Google 模型。
LLM 请求被拒绝:需要思考签名(Google Antigravity)
原因:会话历史中包含没有签名的思考块(通常来自中止/不完整的流);Google Antigravity 要求思考块带有签名。OpenClaw 会为 Google Antigravity Claude 移除无签名的思考块;如果问题仍然出现,请开始一个新会话,或为该代理设置 /thinking off。
身份验证配置文件:它们是什么以及如何管理它们¶
相关:/concepts/oauth(OAuth 流程、令牌存储、多账户模式)
什么是身份验证配置文件?
与某个提供商关联的命名凭据记录(API 密钥、令牌或 OAuth),存储在 SQLite 中。位于
~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite 的代理本地配置文件会覆盖
~/.openclaw/state/openclaw.sqlite 中的共享读透基础存储。
旧版安装会在 openclaw doctor --fix 将其迁移之前,继续将共享存储保留在主代理的数据库中。
在不泄露机密的情况下检查已保存的配置文件:openclaw models auth
list(可选 --provider <id> 或 --json)。参见
模型 CLI。
典型的配置文件 ID 是什么?
带提供商前缀:anthropic:default(在没有电子邮件身份时常见)、用于 OAuth 身份的
anthropic:<email>,或你选择的自定义 ID(例如 anthropic:work)。
我能否控制优先尝试哪个身份验证配置文件?
可以。auth.order.<provider> 配置会为每个提供商设置轮换顺序
(仅元数据 — 不存储机密)。
OpenClaw 可能会在短暂的 冷却(速率限制、
超时、身份验证失败)或较长的 禁用 状态
(计费/额度不足)中跳过某个配置文件。使用 openclaw models status
--json 进行检查,并查看 auth.unusableProfiles。速率限制冷却可以
按模型限定范围 — 某个配置文件针对一个模型处于冷却状态时,仍可为
同一提供商的同级模型提供服务;计费/禁用窗口会阻止
整个配置文件。
设置按代理的顺序覆盖(存储在该代理的
openclaw-agent.sqlite 数据库中):
# Defaults to the configured default agent (omit --agent)
openclaw models auth order get --provider anthropic
# Lock rotation to a single profile
openclaw models auth order set --provider anthropic anthropic:default
# Or set an explicit order (fallback within provider)
openclaw models auth order set --provider anthropic anthropic:work anthropic:default
# Clear override (fall back to config auth.order / round-robin)
openclaw models auth order clear --provider anthropic
# Target a specific agent
openclaw models auth order set --provider anthropic --agent main anthropic:default
验证实际会尝试的内容:openclaw models status --probe。被
显式顺序省略的已存储配置文件会报告
excluded_by_auth_order,而不是被静默尝试。
OAuth 与 API 密钥 - 有什么区别?
- OAuth / CLI 登录 通常在提供商支持时使用订阅访问。
对于 Anthropic,OpenClaw 的 Claude CLI 后端
使用 Claude Code
claude -p,Anthropic 目前将其视为 Agent SDK/程序化使用,并从订阅使用限制中扣除 — 参见 Anthropic 了解当前的计费暂停 状态和来源链接。 - API 密钥 使用按令牌计费。
向导支持 Anthropic Claude CLI、OpenAI Codex OAuth 和 API 密钥。
相关¶
- 常见问题解答 — 主要常见问题解答
- 常见问题解答 — 快速入门和首次运行设置
- 模型选择
- 模型故障转移
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw