配置 — 智能体模型
agents.defaults.model 与 agents.defaults.modelSelectionScope:智能体使用哪个模型、回退到哪个模型,以及模型更改的作用范围。
agents.defaults.model¶
{
agents: {
defaults: {
models: {
"anthropic/claude-opus-4-6": { alias: "opus" },
"minimax/MiniMax-M2.7": { alias: "minimax" },
},
model: {
primary: "anthropic/claude-opus-4-6",
fallbacks: ["minimax/MiniMax-M2.7"],
},
utilityModel: "openai/gpt-5.4-mini",
imageModel: {
primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],
},
mediaModels: {
image: {
primary: "openai/gpt-image-2",
fallbacks: ["google/gemini-3.1-flash-image"],
},
video: {
primary: "qwen/wan2.6-t2v",
fallbacks: ["qwen/wan2.6-i2v"],
},
},
pdfModel: {
primary: "anthropic/claude-opus-4-6",
fallbacks: ["openai/gpt-5.4-mini"],
},
params: { cacheRetention: "long" }, // global default provider params
pdfMaxMb: 10,
pdfMaxPages: 20,
thinkingDefault: "low",
fastModeDefault: false,
verboseDefault: "off",
toolProgressDetail: "explain",
reasoningDefault: "off",
elevatedDefault: "on",
mediaMaxMb: 5,
maxConcurrent: 4,
},
},
}
如果不设置 agents.defaults.timeoutSeconds,普通智能体运行将使用默认的 48 小时限制。仅当您需要不同的整体运行时限时才设置它;请参阅 智能体运行时。
model:接受字符串("provider/model")或对象({ primary, fallbacks })。- 字符串形式仅设置主要模型。
- 对象形式设置主要模型及按顺序排列的回退模型。
utilityModel:可选的provider/model引用或别名,用于短小的内部任务。它目前为生成的控制 UI 会话标题、Telegram DM 主题标题、Discord 自动线程标题、滚动式 活动回顾 以及 进度草稿叙述 提供支持。未设置时,如果主要提供商存在声明的小模型默认值,OpenClaw 会使用该默认值(OpenAI →gpt-5.6-luna,Anthropic →claude-haiku-4-5);否则标题任务使用智能体的主要模型,叙述功能保持关闭。如果不同的实用模型无法准备或完成生成的标题,OpenClaw 会使用主要模型再重试一次该标题。对于仪表板标题,自动的实用模型派生和常规回退会使用有效的会话提供商和认证配置文件;显式的实用模型则保留其配置的提供商/认证。设置utilityModel: ""可跳过备用实用模型路径;仪表板标题生成仍会直接使用常规会话模型。agents.entries.*.utilityModel会覆盖默认值,而操作特定的模型覆盖优先于两者。实用任务会发起独立的模型调用,并将特定于任务的内容发送给所选的模型提供商。仪表板标题生成最多发送第一条非命令消息的前 1,000 个字符;叙述会发送入站请求以及简洁的经脱敏处理的工具摘要。活动回顾会发送之前的回顾以及新转录消息的有限摘录。回顾保持在实用模型路径上,在实用模型不可用时保留缓存文本,并在禁用实用模型路由时停止生成。请选择符合您成本和数据处理要求的提供商。 在全新设置期间,显式的非空utilityModel可以在配置常规主要模型之前为 OpenClaw 设置助手提供支持。选择实用角色会使常规智能体聊天保持未配置。自动按提供商派生的实用模型不会用于引导设置。一旦配置了主要模型,系统助手就会使用它,而短小的实用任务保留其实用模型路径。旧配置保留先前隐式的主要模型,即使它与实用模型或别名匹配也是如此。Doctor 和普通配置写入会先将该路径保留为显式主要模型,再记录实用模型分离迁移。设置使用提供商准备前的配置,因此新添加的实用提供商不会成为保留的主要模型。迁移后,对已配置提供商的隐式回退会跳过显式的实用模型;显式的主要或回退选择仍然具有权威性。动态目录 ID 和有歧义的认证配置文件后缀会在您选择显式主要模型之前保持其旧版路由;迁移不会固化这些值。如果实用模型设置遇到未转换的旧版主要模型,它会要求您运行openclaw doctor --fix,或在认证实用提供商之前选择显式主要模型。在修复期间,现有模型路由仍然可用。imageModel:接受字符串("provider/model")或对象({ primary, fallbacks })。- 当活动模型无法接受图像时,由
view_image工具路径用作其视觉模型配置。原生视觉模型则直接接收加载的图像字节。 - 当所选/默认模型无法接受图像输入时,也用作回退路由。
- 优先使用显式的
provider/model引用。为兼容性也接受裸 ID;如果某个裸 ID 唯一匹配models.providers.*.models中配置的具备图像能力的条目,OpenClaw 会将其限定到该提供商。有歧义的配置匹配要求使用显式的提供商前缀。 mediaModels.image:接受字符串("provider/model")或对象({ primary, fallbacks })。- 用于共享图像生成能力以及任何未来生成图像的工具/插件表面。
- 典型值:
google/gemini-3.1-flash-image用于原生 Gemini 图像生成,fal/fal-ai/flux/dev用于 fal,openai/gpt-image-2用于 OpenAI Images,或openai/gpt-image-1.5用于透明背景的 OpenAI PNG/WebP 输出。 - 如果直接选择提供商/模型,也要配置匹配的提供商认证(例如,
google/*使用GEMINI_API_KEY或GOOGLE_API_KEY;openai/gpt-image-2/openai/gpt-image-1.5使用OPENAI_API_KEY或 OpenAI Codex OAuth;fal/*使用FAL_KEY)。 - 如果省略,
image_generate仍然可以推断出已认证的提供商默认值。它会先尝试当前默认提供商,然后按提供商 ID 顺序尝试其余已注册的图像生成提供商。 mediaModels.music:接受字符串("provider/model")或对象({ primary, fallbacks })。- 用于共享音乐生成能力以及内置的
music_generate工具。 - 典型值:
google/lyria-3-clip-preview、google/lyria-3-pro-preview或minimax/music-2.6。 - 如果省略,
music_generate仍然可以推断出已认证的提供商默认值。它会先尝试当前默认提供商,然后按提供商 ID 顺序尝试其余已注册的音乐生成提供商。 - 如果直接选择提供商/模型,也要配置匹配的提供商认证/API 密钥。
mediaModels.video:接受字符串("provider/model")或对象({ primary, fallbacks })。- 用于共享视频生成能力以及内置的
video_generate工具。 - 典型值:
qwen/wan2.6-t2v、qwen/wan2.6-i2v、qwen/wan2.6-r2v、qwen/wan2.6-r2v-flash或qwen/wan2.7-r2v。 - 如果省略,
video_generate仍然可以推断出已认证的提供商默认值。它会先尝试当前默认提供商,然后按提供商 ID 顺序尝试其余已注册的视频生成提供商。 - 如果直接选择提供商/模型,也要配置匹配的提供商认证/API 密钥。
- 官方 Qwen 视频生成插件支持最多 1 个输出视频、1 个输入图像、4 个输入视频、10 秒时长,以及提供商级别的
size、aspectRatio、resolution、audio和watermark选项。 pdfModel:接受字符串("provider/model")或对象({ primary, fallbacks })。- 由
pdf工具用于模型路由。 - 如果省略,PDF 工具会先回退到
imageModel,然后再回退到解析后的会话/默认模型。 pdfMaxMb:当调用时未传入maxBytesMb时,pdf工具的默认 PDF 大小限制。pdfMaxPages:pdf工具中提取回退模式默认考虑的最大页数。fastModeDefault:智能体的默认快速模式。值:"auto"、true、false。当未设置按消息或会话级别的快速模式覆盖时,每个智能体的agents.entries.*.fastModeDefault会覆盖此默认值。verboseDefault:智能体的默认详细级别。值:"off"、"on"、"full"。默认值:"off"。toolProgressDetail:/verbose工具摘要和进度草稿工具行的详细模式。值:"explain"(默认,简洁的人类可读标签)或"raw"(在可用时追加原始命令/详情)。每个智能体的agents.entries.*.toolProgressDetail会覆盖此默认值。reasoningDefault:智能体的默认推理可见性。值:"off"、"on"、"stream"。每个智能体的agents.entries.*.reasoningDefault会覆盖此默认值。当未设置按消息或会话级别的推理覆盖时,配置的推理默认值仅适用于所有者、授权发送方或运营者/管理员网关上下文。elevatedDefault:智能体的默认提升输出级别。值:"off"、"on"、"ask"、"full"。默认值:"on"。model.primary:格式为provider/model(例如openai/gpt-6-astra用于 Codex OAuth 访问)。如果省略提供商,OpenClaw 会先尝试别名,然后尝试对该确切模型 ID 的唯一定义的提供商匹配,最后才回退到配置的默认提供商(已弃用的兼容性行为,因此请优先使用显式的provider/model)。如果该提供商不再暴露配置的默认模型,OpenClaw 会回退到第一个配置的提供商/模型,而不是显示过时的已删除提供商的默认值。- 要为某个模型限制活动输入,请设置
models.providers.<provider>.models[].contextTokens;在同一条目上使用contextWindow来设置其原生窗口。请参阅 OpenAI 上下文窗口默认值。 models:配置的别名和按模型的设置。每个条目可包含alias(快捷方式)和params(提供商特定的,例如temperature、maxTokens、cacheRetention、context1m、anthropicServerCompaction、anthropicCompactThreshold、responsesServerCompaction、responsesCompactThreshold、OpenRouterprovider路由、chat_template_kwargs、extra_body/extraBody)。添加条目不会限制模型覆盖。- 使用
provider/*条目(如"openai/*": {}或"vllm/*": {})可以显示所选提供商的所有发现模型,而无需手动列出每个模型 ID。 - 当该提供商的每个动态发现的模型都应使用相同运行时,请将
agentRuntime添加到provider/*条目中。确切的provider/model运行时策略仍优先于通配符。 - 向确切的
provider/model条目添加codeMode: true或codeMode: false可覆盖 OpenClaw Code Mode 激活。省略它以继承全局tools.codeMode默认值,包括"auto";智能体特定的激活设置优先。这既不改变运行时选择,也不改变 Codex 原生 Code Mode。Control UI 模型编辑器在运行时设置旁提供 Default、On 和 Off。有关优先级和示例,请参阅 按模型的 Code Mode。 - 安全的元数据编辑:使用
openclaw config set agents.defaults.models '<json>' --strict-json --merge添加条目。config set会拒绝会删除现有条目的替换,除非您传递--replace。 -
modelPolicy.allow:显式覆盖允许列表。接受别名、确切的provider/model引用以及尾部前缀通配符,例如openai/*或clawrouter/anthropic/*。省略它或使用[]表示允许任何模型。agents.entries.*.modelPolicy.allow会替换该智能体的默认策略;显式的空列表使该智能体选择允许任何模型。 -
提供商级别的配置/接入流程会将所选提供商的模型合并到此映射中,并保留已配置的无关提供商。
- 对于使用 API 密钥认证的直接 Anthropic 模型,设置
params.anthropicServerCompaction: true以启用服务端压缩。使用params.anthropicCompactThreshold覆盖输入 token 触发阈值;默认值为max(50000, floor(contextWindow * 0.7)),配置值低于50000时会被限制为50000。OAuth/订阅和非直接端点被排除在外。参见 Anthropic 服务端压缩。 - 对于支持 store 的直接 OpenAI Responses 模型,服务端压缩会自动启用,相同的有效阈值会延迟本地预检压缩。使用
params.responsesServerCompaction: false停止注入context_management,或使用params.responsesCompactThreshold覆盖默认值(已解析上下文窗口的 70%,不可用时为 80,000)。ChatGPT OAuth、自定义代理以及compat.supportsStore: false的路由不会启用此路径。参见 OpenAI 服务端压缩。 params:应用于所有模型的全局默认提供商参数。在agents.defaults.params中设置(例如{ cacheRetention: "long" })。params合并优先级(配置):agents.defaults.params(全局基础),然后是agents.defaults.models["provider/model"].params(所有 Agent 按模型共享),接着是agents.entries.*.models["provider/model"].params(特定 Agent 的按模型配置),最后是agents.entries.*.params(Agent 全局)。后面的层按 key 覆盖。详情参见 提示缓存。- 模型的
params.thinking设置该模型的思考默认值;Agent 特定的模型条目会覆盖共享条目。消息级和会话级的选择优先,其次是 Agent 的thinkingDefault,两者都优先于任一模型设置。参见 思考解析顺序。 models.providers.openrouter.params.provider:OpenRouter 全局默认提供商路由策略。OpenClaw 会将此值转发到 OpenRouter 请求的provider对象;按模型的agents.defaults.models["openrouter/<model>"].params.provider和 Agent 参数会按 key 覆盖该值。参见 OpenRouter 提供商路由。params.extra_body/params.extraBody:高级透传 JSON,合并到适用于 OpenAI 兼容代理的api: "openai-completions"请求体中。如果与生成的请求键冲突,则 extra body 优先;非原生 completions 路由之后仍会剥离 OpenAI 独有的store。params.chat_template_kwargs:vLLM/OpenAI 兼容的聊天模板参数,合并到顶层api: "openai-completions"请求体中。对于关闭了思考的vllm/nemotron-3-*模型,内置的 vLLM 插件会自动发送enable_thinking: false和force_nonempty_content: true;显式的chat_template_kwargs会覆盖生成的默认值,而extra_body.chat_template_kwargs仍具有最终优先级。已配置的 vLLM Qwen 和 Nemotron 思考模型暴露二元的/think选项(off、on),而不是多级努力程度阶梯。compat.thinkingFormat:OpenAI 兼容的思考负载样式。对 Together 风格的reasoning.enabled使用"together",对 Qwen 风格的顶层enable_thinking使用"qwen",或对chat_template_kwargs.enable_thinking使用"qwen-chat-template"(适用于支持请求级聊天模板参数的 Qwen 系列后端,如 vLLM)。OpenClaw 将关闭的思考映射为false,开启的思考映射为true,而已配置的 vLLM Qwen 模型会为这些格式暴露二元的/think选项。compat.supportedReasoningEfforts:按模型的 OpenAI 兼容推理努力程度列表。对于真正接受"xhigh"的自定义端点,请将其包含在列表中;随后对于该已配置的提供商/模型,OpenClaw 会在命令菜单、Gateway 会话行、会话 PATCH 校验、Agent CLI 校验和llm-task校验中暴露/think xhigh。当后端需要某个标准级别的提供商特定值时,使用compat.reasoningEffortMap。params.preserveThinking:仅 Z.AI 支持的保留思考选择启用项。启用且思考开启时,OpenClaw 会发送thinking.clear_thinking: false并重放之前的reasoning_content;参见 Z.AI 思考与保留思考。localService:可选的提供商级进程管理器,用于本地/自托管模型服务器。当所选模型属于该提供商时,OpenClaw 会检查healthUrl(或baseUrl + "/models"),如果端点不可用,则使用args参数启动command,最多等待readyTimeoutMs,然后发送模型请求。command必须是绝对路径。idleStopMs: 0会让进程保持存活,直到 OpenClaw 退出;正值会在经过该空闲毫秒数后停止由 OpenClaw 启动的进程。参见 本地模型服务。- 运行时策略应放在提供商或模型上,而不是
agents.defaults。提供商级规则使用models.providers.<provider>.agentRuntime,模型级规则使用agents.defaults.models["provider/model"].agentRuntime/agents.entries.*.models["provider/model"].agentRuntime。仅凭提供商/模型前缀本身永远不会选择 harness。当运行时未设置或为auto时,OpenAI 可能仅对完全匹配的官方 HTTPS Platform Responses 或 ChatGPT Responses 路由(且没有自定义请求覆盖)隐式选择 Codex。参见 OpenAI 隐式 Agent 运行时。 - 修改这些字段的配置写入器(例如
/models set、/models set-image以及回退添加/移除命令)会保存规范对象形式,并在可能的情况下保留现有的回退列表。 maxConcurrent:跨会话的最大并行 Agent 运行数(每个会话仍串行执行)。默认情况下,OpenClaw 使用max(8, available CPU parallelism * 4),基于os.availableParallelism(),并以os.cpus().length作为回退。这样可以在 8 个可用 CPU 上并发运行 32 个,在 48 个上并发运行 192 个。显式值会覆盖 CPU 推导出的默认值,包括升级之后。
agents.defaults.modelSelectionScope¶
未显式指定作用域时,聊天命令和 Gateway 会话模型更新的作用域。
默认值为 "session":在一个聊天中更改模型不会更改其他
聊天或已配置的默认值,即使调用者是 owner/admin 也是如此。
| 值 | 效果 |
|---|---|
"session" |
仅更改当前会话的模型选择。 |
"agent" |
同时更新当前 agent 在 agents.entries.<agent>.model 处的显式主模型,必要时创建该主模型。绝不更改共享的全局回退。 |
"global" |
同时更新共享的 agents.defaults.model 回退。不要替换其他 agent 的显式主模型或其他会话的固定选择。 |
| 未设置 | 仅更改当前会话,与 "session" 相同。 |
Agent/全局写入需要显式的作用域标志或配置选择。显式 /model 标志
-s/--session、-a/--agent 和 -g/--global 优先于该设置。
如果没有 owner/admin 权限,未带标志的命令仍仅限会话,显式
-a 或 -g 请求会被拒绝。Telegram 回调选择器和嵌入式本地 TUI 即使配置了此设置也
仍仅限会话。此设置没有按 agent 或
按通道的覆盖。
Agent 和全局更新可能影响新的和现有的未固定会话以及 cron
作业,这些作业在下次运行时继承更改后的默认值。它们不会重写
其他会话的显式模型选择。/model default -s 仅清除
当前会话的选择,使其继承当前配置的默认值。
选择当前生效的已配置默认值会清除会话模型固定,但
agent/global 作用域仍会请求写入配置目标。
有关持久性、
权限和选择器行为,请参阅 聊天中的模型选择。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw