跳转至

配置 — 智能体模型

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、OpenRouter provider 路由、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 也是如此。

{
  agents: { defaults: { modelSelectionScope: "session" } },
}
值 效果
"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