配置 — 智能体模型

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",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      maxConcurrent: 4,
    },
  },
}

• model：接受字符串（"provider/model"）或对象（{ primary, fallbacks }）。
• 字符串形式仅设置主模型。
• 对象形式设置主模型以及按顺序排列的回退模型。
• utilityModel：可选，用于简短内部任务的 provider/model 引用或别名。它目前为生成的 Control UI 会话标题、Telegram 私信主题标题、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（例如，用于 Codex OAuth 访问的 openai/gpt-6-astra）。如果省略提供商，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。
• 当某个提供商的所有动态发现模型都应使用相同运行时，请向 provider/* 条目添加 agentRuntime。精确的 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。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（共享的逐模型），然后 agents.entries.*.models["provider/model"].params（特定于 agent 的逐模型），再然后 agents.entries.*.params（agent 全局）。后面的层级按键覆盖。详见 提示缓存。
• 模型的 params.thinking 设置该模型的思考默认值；特定于 agent 的模型条目会覆盖共享条目。逐消息和会话的选择，以及随后的 agent 的 thinkingDefault，优先于任一模型设置。参见 思考解析顺序。
• models.providers.openrouter.params.provider：OpenRouter 全局的默认提供方路由策略。OpenClaw 会将其转发到 OpenRouter 请求的 provider 对象；逐模型的 agents.defaults.models["openrouter/<model>"].params.provider 和 agent 参数按键覆盖。参见 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），而不是多级 effort 阶梯。
• compat.thinkingFormat：OpenAI 兼容的思考负载样式。对 Together 风格的 reasoning.enabled 使用 "together"，对 Qwen 风格的顶层 enable_thinking 使用 "qwen"，或对支持请求级聊天模板 kwargs 的 Qwen 系列后端（如 vLLM）使用 "qwen-chat-template" 来设置 chat_template_kwargs.enable_thinking。OpenClaw 将禁用思考映射为 false，启用思考映射为 true，并且配置的 vLLM Qwen 模型针对这些格式暴露二进制 /think 选项。
• compat.supportedReasoningEfforts：逐模型的 OpenAI 兼容推理 effort 列表。为真正接受 "xhigh" 的自定义端点包含它；OpenClaw 随后会在命令菜单、Gateway 会话行、会话补丁验证、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 以及 fallback 添加/删除命令）会保存规范对象形式，并在可能时保留现有 fallback 列表。
• 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"：在一个聊天中更改模型不会更改其他 聊天或已配置的默认值，即使调用者是所有者/管理员也是如此。

{
  agents: { defaults: { modelSelectionScope: "session" } },
}

对 agent/全局的写入需要显式的作用域标志或配置选择。显式 /model 标志 -s/--session、-a/--agent 和 -g/--global 优先于该设置。 如果没有所有者/管理员权限，未带作用域标志的命令仍仅限会话，并且显式 -a 或 -g 请求会被拒绝。即使配置了此设置，Telegram 回调选择器和嵌入式本地 TUI 仍 仅限会话。此设置没有按 agent 或 按通道的覆盖。

agent 和全局更新可能影响新的和现有的未固定会话，以及在其下次运行时继承已更改默认值的 cron 任务。它们不会重写 其他会话的显式模型选择。/model default -s 仅清除 当前会话的选择，使其继承当前配置的默认值。 选择生效的已配置默认值会清除会话模型固定值，但 agent/全局作用域仍会请求写入已配置的目标。 请参阅 聊天中的模型选择 了解持久性、 权限和选择器行为。