配置 — 智能体

​

智能体默认值

​

agents.defaults.workspace

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
}

​

agents.defaults.repoRoot

{
  agents: { defaults: { repoRoot: "~/Projects/openclaw" } },
}

​

agents.defaults.skills

{
  agents: {
    defaults: { skills: ["github", "weather"] },
    list: [
      { id: "writer" }, // inherits github, weather
      { id: "docs", skills: ["docs-search"] }, // replaces defaults
      { id: "locked-down", skills: [] }, // no skills
    ],
  },
}

• 省略 agents.defaults.skills 表示默认不限制 Skills。
• 省略 agents.list[].skills 表示继承默认值。
• 设置 agents.list[].skills: [] 表示无 Skills。
• 非空的 agents.list[].skills 列表是该智能体的最终集合；它不会与默认值合并。

​

agents.defaults.skipBootstrap

{
  agents: { defaults: { skipBootstrap: true } },
}

​

agents.defaults.skipOptionalBootstrapFiles

{
  agents: {
    defaults: {
      skipOptionalBootstrapFiles: ["SOUL.md", "USER.md"],
    },
  },
}

​

agents.defaults.contextInjection

• "continuation-skip"：安全的延续轮次（在一次完成的助手响应之后）会跳过工作区 bootstrap 的重新注入，从而减小提示词大小。Heartbeat 运行和压缩后的重试仍会重建上下文。
• "never"：在每个轮次都禁用工作区 bootstrap 和上下文文件注入。仅对完全自行管理提示词生命周期的智能体使用此选项（自定义上下文引擎、构建自身上下文的原生运行时，或无需 bootstrap 的专用工作流）。Heartbeat 和压缩恢复轮次也会跳过注入。

{
  agents: { defaults: { contextInjection: "continuation-skip" } },
}

​

agents.defaults.bootstrapMaxChars

{
  agents: { defaults: { bootstrapMaxChars: 20000 } },
}

​

agents.defaults.bootstrapTotalMaxChars

{
  agents: { defaults: { bootstrapTotalMaxChars: 60000 } },
}

​

按智能体覆盖 bootstrap 配置文件

{
  agents: {
    defaults: {
      contextInjection: "continuation-skip",
      bootstrapMaxChars: 20000,
      bootstrapTotalMaxChars: 60000,
    },
    list: [
      {
        id: "strict-worker",
        contextInjection: "always",
        bootstrapMaxChars: 50000,
        bootstrapTotalMaxChars: 300000,
      },
    ],
  },
}

​

agents.defaults.bootstrapPromptTruncationWarning

• "off"：绝不向系统提示词注入截断通知文本。
• "once"：每个唯一截断签名只注入一次简洁通知。
• "always"：存在截断时，每次运行都注入简洁通知（推荐）。

{
  agents: { defaults: { bootstrapPromptTruncationWarning: "always" } }, // off | once | always
}

​

上下文预算所有权映射

• agents.list[].skillsLimits.maxSkillsPromptChars
• agents.list[].contextInjection
• agents.list[].bootstrapMaxChars
• agents.list[].bootstrapTotalMaxChars
• agents.list[].contextLimits.*

​

agents.defaults.startupContext

{
  agents: {
    defaults: {
      startupContext: {
        enabled: true,
        applyOn: ["new", "reset"],
        dailyMemoryDays: 2,
        maxFileBytes: 16384,
        maxFileChars: 1200,
        maxTotalChars: 2800,
      },
    },
  },
}

​

agents.defaults.contextLimits

{
  agents: {
    defaults: {
      contextLimits: {
        memoryGetMaxChars: 12000,
        memoryGetDefaultLines: 120,
        postCompactionMaxChars: 1800,
      },
    },
  },
}

• memoryGetMaxChars：添加截断元数据和延续通知前，默认 memory_get 摘录上限。
• memoryGetDefaultLines：省略 lines 时默认的 memory_get 行窗口。
• toolResultMaxChars：高级实时工具结果上限，用于持久化结果和溢出恢复。保持未设置时使用模型上下文自动上限：低于 100K tokens 时为 16000 字符，100K+ tokens 时为 32000 字符，200K+ tokens 时为 64000 字符。长上下文模型可接受最高 1000000 的显式值，但有效上限仍限制为模型上下文窗口的大约 30%。openclaw doctor --deep 会打印有效上限，且 Doctor 仅在显式覆盖已过时或没有效果时发出警告。
• postCompactionMaxChars：压缩后刷新注入期间使用的 AGENTS.md 摘录上限。

​

agents.list[].contextLimits

{
  agents: {
    defaults: {
      contextLimits: { memoryGetMaxChars: 12000 },
    },
    list: [
      {
        id: "tiny-local",
        contextLimits: {
          memoryGetMaxChars: 6000,
          toolResultMaxChars: 8000, // advanced ceiling for this agent
        },
      },
    ],
  },
}

​

skills.limits.maxSkillsPromptChars

{
  skills: { limits: { maxSkillsPromptChars: 18000 } },
}

​

agents.list[].skillsLimits.maxSkillsPromptChars

{
  agents: {
    list: [{ id: "tiny-local", skillsLimits: { maxSkillsPromptChars: 6000 } }],
  },
}

​

agents.defaults.imageMaxDimensionPx

{
  agents: { defaults: { imageMaxDimensionPx: 1200 } },
}

​

agents.defaults.imageQuality

• auto：适配模型限制和图像数量。
• efficient：偏好较小图像，以降低 token 和字节用量。
• balanced：使用标准的中间档阶梯。
• high：为截图、图表和文档图像保留更多细节。

{
  agents: { defaults: { imageQuality: "auto" } },
}

​

agents.defaults.userTimezone

{
  agents: { defaults: { userTimezone: "America/Chicago" } },
}

​

agents.defaults.timeFormat

{
  agents: { defaults: { timeFormat: "auto" } }, // auto | 12 | 24
}

​

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"],
      },
      imageGenerationModel: {
        primary: "openai/gpt-image-2",
        fallbacks: ["google/gemini-3.1-flash-image-preview"],
      },
      videoGenerationModel: {
        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
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "off",
      toolProgressDetail: "explain",
      reasoningDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      contextTokens: 200000,
      maxConcurrent: 4,
    },
  },
}

• model：接受字符串（"provider/model"）或对象（{ primary, fallbacks }）。
  • 字符串形式只设置主模型。
  • 对象形式设置主模型以及有序故障转移模型。
• utilityModel：可选的 provider/model 引用或别名，用于短小的内部任务。它目前用于生成 Control UI 会话标题、Telegram 私信话题标题和 Discord 自动线程标题。未设置时，这些任务会回退到智能体的主模型；agents.list[].utilityModel 会覆盖默认值，而特定操作的模型覆盖会优先于二者。实用任务会发起单独的模型调用，并将任务特定内容发送给选定的模型提供商。仪表板标题生成最多发送第一条非命令消息的前 1,000 个字符。请选择符合你的成本和数据处理要求的提供商。
• imageModel：接受字符串（"provider/model"）或对象（{ primary, fallbacks }）。
  • 被 image 工具路径用作其视觉模型配置。
  • 当选定/默认模型不能接受图像输入时，也会用作回退路由。
  • 优先使用显式 provider/model 引用。出于兼容性也接受裸 ID；如果裸 ID 唯一匹配 models.providers.*.models 中已配置且支持图像的条目，OpenClaw 会将其限定到该提供商。存在歧义的已配置匹配需要显式提供商前缀。
• imageGenerationModel：接受字符串（"provider/model"）或对象（{ primary, fallbacks }）。
  • 被共享图像生成能力以及任何未来生成图像的工具/插件表面使用。
  • 典型值：google/gemini-3.1-flash-image-preview 用于原生 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 顺序尝试其余已注册的图像生成提供商。
• musicGenerationModel：接受字符串（"provider/model"）或对象（{ primary, fallbacks }）。
  • 被共享音乐生成能力和内置 music_generate 工具使用。
  • 典型值：google/lyria-3-clip-preview、google/lyria-3-pro-preview 或 minimax/music-2.6。
  • 如果省略，music_generate 仍可推断带凭证的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的音乐生成提供商。
  • 如果你直接选择提供商/模型，也要配置匹配的提供商凭证/API key。
• videoGenerationModel：接受字符串（"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 key。
  • 官方 Qwen 视频生成插件最多支持 1 个输出视频、1 张输入图像、4 个输入视频、10 秒时长，以及提供商级别的 size、aspectRatio、resolution、audio 和 watermark 选项。
• pdfModel：接受字符串（"provider/model"）或对象（{ primary, fallbacks }）。
  • 被 pdf 工具用于模型路由。
  • 如果省略，PDF 工具会回退到 imageModel，然后回退到已解析的会话/默认模型。
• pdfMaxBytesMb：未在调用时传入 maxBytesMb 时，pdf 工具的默认 PDF 大小限制。
• pdfMaxPages：pdf 工具中提取回退模式考虑的默认最大页数。
• verboseDefault：智能体的默认详细级别。取值："off"、"on"、"full"。默认："off"。
• toolProgressDetail：/verbose 工具摘要和进度草稿工具行的详细模式。取值："explain"（默认，紧凑的人类可读标签）或 "raw"（可用时附加原始命令/详情）。按智能体配置的 agents.list[].toolProgressDetail 会覆盖此默认值。
• reasoningDefault：智能体的默认推理可见性。取值："off"、"on"、"stream"。按智能体配置的 agents.list[].reasoningDefault 会覆盖此默认值。已配置的推理默认值只会在没有设置逐消息或会话推理覆盖时，应用于所有者、已授权发送者或操作员管理员 Gateway 网关上下文。
• elevatedDefault：智能体的默认提升输出级别。取值："off"、"on"、"ask"、"full"。默认："on"。
• model.primary：格式为 provider/model（例如 openai/gpt-5.5 用于 OpenAI API key 或 Codex OAuth 访问）。如果省略提供商，OpenClaw 会先尝试别名，然后为该精确模型 ID 查找唯一的已配置提供商匹配，最后才回退到已配置的默认提供商（已弃用的兼容行为，因此优先使用显式 provider/model）。如果该提供商不再公开已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是暴露陈旧的已移除提供商默认值。
• models：为 /model 配置的模型目录和允许列表。每个条目可以包含 alias（快捷方式）和 params（提供商特定，例如 temperature、maxTokens、cacheRetention、context1m、responsesServerCompaction、responsesCompactThreshold、OpenRouter provider 路由、chat_template_kwargs、extra_body/extraBody）。
  • 使用 provider/* 条目，例如 "openai/*": {} 或 "vllm/*": {}，可显示所选提供商的所有已发现模型，而不必手动列出每个模型 ID。
  • 当该提供商的每个动态发现模型都应使用相同运行时时，请向 provider/* 条目添加 agentRuntime。精确的 provider/model 运行时策略仍优先于通配符。
  • 安全编辑：使用 openclaw config set agents.defaults.models '<json>' --strict-json --merge 添加条目。除非传入 --replace，否则 config set 会拒绝会移除现有允许列表条目的替换。
  • 提供商作用域的配置/新手引导流程会将所选提供商模型合并到此映射中，并保留已配置的无关提供商。
  • 对于直接 OpenAI Responses 模型，服务端压缩会自动启用。使用 params.responsesServerCompaction: false 停止注入 context_management，或使用 params.responsesCompactThreshold 覆盖阈值。参见 OpenAI 服务端压缩。
• params：应用于所有模型的全局默认提供商参数。设置在 agents.defaults.params（例如 { cacheRetention: "long" }）。
• params 合并优先级（配置）：agents.defaults.params（全局基础）会被 agents.defaults.models["provider/model"].params（逐模型）覆盖，然后 agents.list[].params（匹配的智能体 ID）按键覆盖。详情参见 Prompt 缓存。
• models.providers.openrouter.params.provider：OpenRouter 范围的默认提供商路由策略。OpenClaw 会将其转发到 OpenRouter 请求的 provider 对象；逐模型的 agents.defaults.models["openrouter/<model>"].params.provider 和智能体参数会按键覆盖。参见 OpenRouter 提供商路由。
• params.extra_body/params.extraBody：高级透传 JSON，会合并到 OpenAI 兼容代理的 api: "openai-completions" 请求体中。如果它与生成的请求键冲突，额外请求体会胜出；非原生 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）上，对 chat_template_kwargs.enable_thinking 使用 "qwen-chat-template"。OpenClaw 会将禁用思考映射为 false，将启用思考映射为 true，并且已配置的 vLLM Qwen 模型会为这些格式公开二元 /think 选择。
• compat.supportedReasoningEfforts：逐模型的 OpenAI 兼容推理 effort 列表。对于真正接受该值的自定义端点，包含 "xhigh"；随后 OpenClaw 会在命令菜单、Gateway 网关会话行、会话补丁验证、智能体 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.list[].models["provider/model"].agentRuntime 配置模型特定规则。官方 OpenAI provider 上的 OpenAI 智能体模型默认选择 Codex。
• 修改这些字段的配置写入器（例如 /models set、/models set-image 以及回退添加/移除命令）会保存规范对象形式，并尽可能保留现有回退列表。
• maxConcurrent：跨会话的最大并行智能体运行数（每个会话仍会串行执行）。默认：4。

​

运行时策略

{
  models: {
    providers: {
      openai: {
        agentRuntime: { id: "codex" },
      },
    },
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      models: {
        "anthropic/claude-opus-4-8": {
          agentRuntime: { id: "claude-cli" },
        },
        "vllm/*": {
          agentRuntime: { id: "openclaw" },
        },
      },
    },
  },
}

• id："auto"、"openclaw"、已注册的插件 harness id，或受支持的 CLI 后端别名。内置 Codex 插件会注册 codex；内置 Anthropic 插件提供 claude-cli CLI 后端。
• id: "auto" 允许已注册的插件 harness 声明其支持的轮次，并在没有 harness 匹配时使用 OpenClaw。显式插件运行时（例如 id: "codex"）要求该 harness 存在；如果它不可用或失败，则会故障关闭。
• id: "pi" 仅作为 openclaw 的已弃用别名被接受，用于保留 v2026.5.22 及更早版本已发布配置。新配置应使用 openclaw。
• 运行时优先级首先是精确模型策略（agents.list[].models["provider/model"]、agents.defaults.models["provider/model"] 或 models.providers.<provider>.models[]），然后是 agents.list[] / agents.defaults.models["provider/*"]，最后是 models.providers.<provider>.agentRuntime 处的提供商级策略。
• 整个智能体级运行时键是遗留配置。agents.defaults.agentRuntime、agents.list[].agentRuntime、会话运行时固定项和 OPENCLAW_AGENT_RUNTIME 会被运行时选择忽略。运行 openclaw doctor --fix 以移除过时值。
• OpenAI agent 模型默认使用 Codex harness；当你想显式指定时，提供商/模型的 agentRuntime.id: "codex" 仍然有效。
• 对于 Claude CLI 部署，建议使用 model: "anthropic/claude-opus-4-8" 加模型作用域的 agentRuntime.id: "claude-cli"。旧版 claude-cli/<model> 引用仍可兼容使用，但新配置应保持提供商/模型选择规范，并将执行后端放在提供商/模型运行时策略中。
• 这只控制文本智能体轮次执行。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用其提供商/模型设置。

​

agents.defaults.cliBackends

{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude",
        },
        "my-cli": {
          command: "my-cli",
          args: ["--json"],
          output: "json",
          modelArg: "--model",
          sessionArg: "--session",
          sessionMode: "existing",
          systemPromptArg: "--system",
          // Or use systemPromptFileArg when the CLI accepts a prompt file flag.
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
        },
      },
    },
  },
}

• CLI 后端以文本优先；工具始终禁用。
• 设置 sessionArg 时支持会话。
• 当 imageArg 接受文件路径时支持图像透传。
• reseedFromRawTranscriptWhenUncompacted: true 允许后端在首次压缩摘要存在之前，从有界的原始 OpenClaw transcript 尾部恢复安全的已失效会话。认证配置文件或凭据 epoch 变更仍绝不会使用原始内容重新播种。

​

agents.defaults.promptOverlays

{
  agents: {
    defaults: {
      promptOverlays: {
        gpt5: {
          personality: "friendly", // friendly | on | off
        },
      },
    },
  },
}

• "friendly"（默认）和 "on" 启用友好的交互风格层。
• "off" 仅禁用友好层；带标记的 GPT-5 行为契约仍保持启用。
• 当此共享设置未设置时，仍会读取旧版 plugins.entries.openai.config.personality。

​

agents.defaults.heartbeat

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 0m disables
        model: "openai/gpt-5.4-mini",
        includeReasoning: false,
        includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt
        lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files
        isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history)
        skipWhenBusy: false, // default: false; true also waits for this agent's subagent/nested lanes
        session: "main",
        to: "+15555550123",
        directPolicy: "allow", // allow (default) | block
        target: "none", // default: none | options: last | whatsapp | telegram | discord | ...
        prompt: "Read HEARTBEAT.md if it exists...",
        ackMaxChars: 300,
        suppressToolErrorWarnings: false,
        timeoutSeconds: 45,
      },
    },
  },
}

• every：时长字符串（ms/s/m/h）。默认值：30m（API key 认证）或 1h（OAuth 认证）。设为 0m 可禁用。
• includeSystemPromptSection：为 false 时，从系统提示词中省略 Heartbeat 部分，并跳过将 HEARTBEAT.md 注入启动上下文。默认值：true。
• suppressToolErrorWarnings：为 true 时，在 Heartbeat 运行期间抑制工具错误警告载荷。
• timeoutSeconds：Heartbeat 智能体轮次被中止前允许的最长秒数。留空时，如果设置了 agents.defaults.timeoutSeconds 则使用它，否则使用 Heartbeat 周期并上限为 600 秒。
• directPolicy：直接/私信投递策略。allow（默认）允许直接目标投递。block 会抑制直接目标投递并发出 reason=dm-blocked。
• lightContext：为 true 时，Heartbeat 运行使用轻量级启动上下文，并且只保留工作区启动文件中的 HEARTBEAT.md。
• isolatedSession：为 true 时，每次 Heartbeat 都在没有先前对话历史的新会话中运行。与 cron sessionTarget: "isolated" 相同的隔离模式。将每次 Heartbeat 的 token 成本从约 100K 降到约 2-5K token。
• skipWhenBusy：为 true 时，当该智能体有额外繁忙通道时，Heartbeat 运行会推迟：其自己的按会话键分组的子智能体或嵌套命令工作。Cron 通道始终推迟 Heartbeat，即使没有此标志。
• 按智能体：设置 agents.list[].heartbeat。当任一智能体定义了 heartbeat 时，只有这些智能体运行 Heartbeat。
• Heartbeat 会运行完整智能体轮次，间隔越短消耗的 token 越多。

​

agents.defaults.compaction

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
        provider: "my-provider", // id of a registered compaction provider plugin (optional)
        timeoutSeconds: 180,
        reserveTokensFloor: 24000,
        keepRecentTokens: 50000,
        recentTurnsPreserve: 3,
        maxHistoryShare: 0.7,
        identifierPolicy: "strict", // strict | off | custom
        identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom
        qualityGuard: { enabled: true, maxRetries: 1 },
        midTurnPrecheck: { enabled: false }, // optional tool-loop pressure check
        postIndexSync: "async", // off | async | await
        postCompactionSections: ["Session Startup", "Red Lines"], // opt in to AGENTS.md section reinjection
        model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override
        truncateAfterCompaction: true, // rotate to a smaller successor JSONL after compaction
        maxActiveTranscriptBytes: "20mb", // optional preflight local compaction trigger
        notifyUser: true, // notices when compaction starts/completes and on memory-flush degradation (default: false)
        memoryFlush: {
          enabled: true,
          model: "ollama/qwen3:8b", // optional memory-flush-only model override
          softThresholdTokens: 6000,
          forceFlushTranscriptBytes: "2mb",
          systemPrompt: "Session nearing compaction. Store durable memories now.",
          prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.",
        },
      },
    },
  },
}

• mode：default 或 safeguard（用于长历史的分块摘要）。参见 压缩。
• provider：已注册压缩提供商插件的 id。设置后会调用提供商的 summarize()，而不是内置 LLM 摘要生成。失败时回退到内置摘要。设置提供商会强制 mode: "safeguard"。参见 压缩。
• timeoutSeconds：单次压缩操作允许的最长秒数，超过后 OpenClaw 会中止。默认值：180。
• reserveTokens：压缩后为模型输出和后续工具结果保留的 token 余量。当模型上下文窗口已知时，OpenClaw 会限制有效保留量，避免其消耗提示预算。
• reserveTokensFloor：嵌入式运行时强制执行的最小保留量。设置为 0 可禁用下限。该下限仍受当前上下文窗口上限约束。
• keepRecentTokens：智能体切点预算，用于逐字保留最近的转录尾部。手动 /compact 在显式设置时会遵守此值；否则手动压缩是硬检查点。
• recentTurnsPreserve：在 safeguard 摘要外逐字保留的最近用户/助手轮次数。默认值：3。
• maxHistoryShare：压缩后保留历史允许占总上下文预算的最大比例（范围 0.1-0.9）。
• identifierPolicy：strict（默认）、off 或 custom。strict 会在压缩摘要期间前置内置的不透明标识符保留指引。
• identifierInstructions：当 identifierPolicy=custom 时使用的可选自定义标识符保留文本。
• qualityGuard：针对 safeguard 摘要的格式异常输出重试检查。在 safeguard 模式下默认启用；设置 enabled: false 可跳过审计。
• midTurnPrecheck：可选的工具循环压力检查。当 enabled: true 时，OpenClaw 会在追加工具结果后、下一次模型调用前检查上下文压力。如果上下文已无法容纳，它会在提交提示前中止当前尝试，并复用现有预检查恢复路径来截断工具结果，或执行压缩后重试。适用于 default 和 safeguard 两种压缩模式。默认：禁用。
• postIndexSync：压缩后的会话记忆重新索引模式。默认值："async"。使用 "await" 可获得最强新鲜度，使用 "async" 可降低压缩延迟，只有在会话记忆同步由其他位置处理时才使用 "off"。
• postCompactionSections：压缩后可选重新注入的 AGENTS.md H2/H3 章节名称。未设置或设置为 [] 时禁用重新注入。显式设置 ["Session Startup", "Red Lines"] 会启用这一对章节，并保留旧版 Every Session/Safety 回退。仅当额外上下文值得承担重复项目指引的风险时才启用，因为这些指引可能已被压缩摘要捕获。
• model：仅用于压缩摘要的可选 provider/model-id，或来自 agents.defaults.models 的裸别名。裸别名会在分发前解析；配置的字面模型 ID 在冲突时保留优先级。当主会话应保留一个模型、但压缩摘要应在另一个模型上运行时使用此项；未设置时，压缩使用会话的主模型。
• truncateAfterCompaction：压缩后轮换当前会话 JSONL，使后续轮次只加载摘要和未摘要尾部，同时保留之前的完整转录归档。防止长时间运行会话中的当前转录无限增长。默认值：false。
• maxActiveTranscriptBytes：可选字节阈值（number 或类似 "20mb" 的字符串），当当前 JSONL 增长超过阈值时，会在运行前触发普通本地压缩。需要 truncateAfterCompaction，这样成功压缩后才能轮换为更小的后继转录。未设置或为 0 时禁用。
• notifyUser：为 true 时，向用户发送简短的上下文维护通知：压缩开始和完成时（例如，“正在压缩上下文…”和“压缩完成”），以及压缩前记忆刷新已耗尽、因此回复以降级状态继续时（例如，“记忆维护暂时失败；正在继续你的回复。”）。默认禁用，以保持这些通知静默。
• memoryFlush：自动压缩前用于存储持久记忆的静默智能体轮次。当此维护轮次应保留在本地模型上时，将 model 设置为精确提供商/模型，例如 ollama/qwen3:8b；该覆盖不会继承当前会话回退链。forceFlushTranscriptBytes 会在转录文件大小达到阈值时强制刷新，即使 token 计数器已过期。工作区为只读时跳过。

​

agents.defaults.runRetries

{
  agents: {
    defaults: {
      runRetries: {
        base: 24,
        perProfile: 8,
        min: 32,
        max: 160,
      },
    },
    list: [
      {
        id: "main",
        runRetries: { max: 50 }, // optional per-agent overrides
      },
    ],
  },
}

• base：外层运行循环的基础运行重试迭代次数。默认值：24。
• perProfile：每个回退配置候选额外授予的运行重试迭代次数。默认值：8。
• min：运行重试迭代次数的绝对最小限制。默认值：32。
• max：运行重试迭代次数的绝对最大限制，用于防止失控执行。默认值：160。

​

agents.defaults.contextPruning

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl", // off (default) | cache-ttl
        ttl: "1h", // duration (ms/s/m/h), default unit: minutes; default: 5m
        keepLastAssistants: 3,
        softTrimRatio: 0.3,
        hardClearRatio: 0.5,
        minPrunableToolChars: 50000,
        softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 },
        hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" },
        tools: { deny: ["browser", "canvas"] },
      },
    },
  },
}

​

分块流式传输

{
  agents: {
    defaults: {
      blockStreamingDefault: "off", // on | off
      blockStreamingBreak: "text_end", // text_end | message_end
      blockStreamingChunk: { minChars: 800, maxChars: 1200, breakPreference: "paragraph" },
      blockStreamingCoalesce: { idleMs: 1000 },
      humanDelay: { mode: "natural" }, // off (default) | natural | custom (use minMs/maxMs)
    },
  },
}

• 非 Telegram 渠道需要显式设置 *.blockStreaming: true 才能启用分块回复。
• 渠道覆盖项：channels.<channel>.blockStreamingCoalesce（以及按账号配置的变体）。Discord、Google Chat、Mattermost、MS Teams、Signal 和 Slack 默认 minChars: 1500 / idleMs: 1000。
• blockStreamingChunk.breakPreference：首选分块边界（"paragraph" | "newline" | "sentence"）。
• humanDelay：分块回复之间的随机暂停。默认值：off。natural = 800-2500ms。custom 使用 minMs/maxMs（任何未设置的边界都会回退到自然范围）。按智能体覆盖：agents.list[].humanDelay。

​

输入状态指示器

{
  agents: {
    defaults: {
      typingMode: "instant", // never | instant | thinking | message
      typingIntervalSeconds: 6,
    },
  },
}

• 默认值：直接聊天/提及时为 instant，未提及的群聊为 message。
• typingIntervalSeconds 默认值：6。
• 按会话覆盖：session.typingMode、session.typingIntervalSeconds。

​

agents.defaults.sandbox

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off (default) | non-main | all
        backend: "docker", // docker (default) | ssh | openshell
        scope: "agent", // session | agent (default) | shared
        workspaceAccess: "none", // none (default) | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          containerPrefix: "openclaw-sbx-",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          gpus: "all",
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256,
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "openclaw-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"],
          binds: ["/home/user/source:/source:rw"],
        },
        ssh: {
          target: "user@gateway-host:22",
          command: "ssh",
          workspaceRoot: "/tmp/openclaw-sandboxes",
          strictHostKeyChecking: true,
          updateHostKeys: true,
          identityFile: "~/.ssh/id_ed25519",
          certificateFile: "~/.ssh/id_ed25519-cert.pub",
          knownHostsFile: "~/.ssh/known_hosts",
          // SecretRefs / inline contents also supported:
          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
        },
        browser: {
          enabled: false,
          image: "openclaw-sandbox-browser:bookworm-slim",
          network: "openclaw-sandbox-browser",
          cdpPort: 9222,
          cdpSourceRange: "172.21.0.1/32",
          vncPort: 5900,
          noVncPort: 6080,
          headless: false,
          enableNoVnc: true,
          allowHostControl: false,
          autoStart: true,
          autoStartTimeoutMs: 12000,
        },
        prune: {
          idleHours: 24,
          maxAgeDays: 7,
        },
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: [
          "exec",
          "process",
          "read",
          "write",
          "edit",
          "apply_patch",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status",
        ],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
      },
    },
  },
}

{
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          mode: "mirror", // mirror (default) | remote
          command: "openshell",
          from: "openclaw",
          remoteWorkspaceDir: "/sandbox",
          remoteAgentWorkspaceDir: "/agent",
          gateway: "lab", // optional
          gatewayEndpoint: "https://lab.example", // optional
          policy: "strict", // optional OpenShell policy id
          providers: ["openai"], // optional
          autoProviders: true,
          timeoutSeconds: 120,
        },
      },
    },
  },
}

scripts/sandbox-setup.sh           # main sandbox image
scripts/sandbox-browser-setup.sh   # optional browser image

​

agents.list（按智能体覆盖）

{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        name: "Main Agent",
        workspace: "~/.openclaw/workspace",
        agentDir: "~/.openclaw/agents/main/agent",
        model: "anthropic/claude-opus-4-6", // or { primary, fallbacks }
        utilityModel: "openai/gpt-5.4-mini",
        thinkingDefault: "high", // per-agent thinking level override
        reasoningDefault: "on", // per-agent reasoning visibility override
        fastModeDefault: false, // per-agent fast mode override
        params: { cacheRetention: "none" }, // overrides matching defaults.models params by key
        tts: {
          providers: {
            elevenlabs: { speakerVoiceId: "EXAVITQu4vr4xnSDxMaL" },
          },
        },
        skills: ["docs-search"], // replaces agents.defaults.skills when set
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
          emoji: "🦥",
          avatar: "avatars/samantha.png",
        },
        groupChat: { mentionPatterns: ["@openclaw"] },
        sandbox: { mode: "off" },
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent", // persistent | oneshot
            cwd: "/workspace/openclaw",
          },
        },
        subagents: { allowAgents: ["*"] },
        tools: {
          profile: "coding",
          allow: ["browser"],
          deny: ["canvas"],
          elevated: { enabled: true },
        },
      },
    ],
  },
}

• id：稳定的智能体 id（必填）。
• default：设置多个时，第一个生效（会记录警告）。如果没有设置，则列表中的第一项为默认值。
• model：字符串形式会设置严格的单智能体主模型，且没有模型回退；对象形式 { primary } 也同样严格，除非你添加 fallbacks。使用 { primary, fallbacks: [...] } 可让该智能体启用回退，或使用 { primary, fallbacks: [] } 明确指定严格行为。仅覆盖 primary 的 Cron 任务仍会继承默认回退，除非你设置 fallbacks: []。
• utilityModel：可选的单智能体覆盖项，用于生成会话和线程标题等短内部任务。回退到 agents.defaults.utilityModel，然后回退到此智能体的主模型。
• params：单智能体流参数，会覆盖合并到 agents.defaults.models 中选定的模型条目上。可用于 cacheRetention、temperature 或 maxTokens 等智能体专属覆盖，而不需要复制整个模型目录。
• tts：可选的单智能体文本转语音覆盖项。该块会深度合并到 messages.tts 上，因此请将共享的提供商凭证和回退策略保留在 messages.tts 中，并在此处仅设置 persona 专属值，例如提供商、声音、模型、风格或自动模式。
• skills：可选的单智能体 Skills 允许列表。如果省略，智能体会在已设置时继承 agents.defaults.skills；显式列表会替换默认值而不是合并，且 [] 表示无 Skills。
• thinkingDefault：可选的单智能体默认思考级别（off | minimal | low | medium | high | xhigh | adaptive | max）。当未设置单消息或会话覆盖时，会覆盖此智能体的 agents.defaults.thinkingDefault。所选的提供商/模型配置决定哪些值有效；对于 Google Gemini，adaptive 会保留由提供商拥有的动态思考（Gemini 3/3.1 上省略 thinkingLevel，Gemini 2.5 上使用 thinkingBudget: -1）。
• reasoningDefault：可选的单智能体默认推理可见性（on | off | stream）。当未设置单消息或会话推理覆盖时，会覆盖此智能体的 agents.defaults.reasoningDefault。
• fastModeDefault：可选的单智能体快速模式默认值（"auto" | true | false）。在未设置单消息或会话快速模式覆盖时应用。
• models：可选的单智能体模型目录/运行时覆盖，以完整的 provider/model id 为键。使用 models["provider/model"].agentRuntime 设置单智能体运行时例外。
• runtime：可选的单智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，使用 type: "acp" 以及 runtime.acp 默认值（agent、backend、mode、cwd）。
• identity.avatar：工作区相对路径、http(s) URL 或 data: URI。
• 本地工作区相对的 identity.avatar 图像文件限制为 2 MB。http(s) URL 和 data: URI 不会按本地文件大小限制检查。
• identity 会派生默认值：ackReaction 来自 emoji，mentionPatterns 来自 name/emoji。
• subagents.allowAgents：已配置智能体 id 的允许列表，用于显式 sessions_spawn.agentId 目标（["*"] = 任意已配置目标；默认：仅同一智能体）。当应允许以自身为目标的 agentId 调用时，请包含请求者 id。其智能体配置已删除的过期条目会被 sessions_spawn 拒绝，并从 agents_list 中省略；运行 openclaw doctor --fix 清理它们，或在该目标应在继承默认值的同时保持可生成时，添加一个最小的 agents.list[] 条目。
• 沙箱继承保护：如果请求者会话处于沙箱隔离中，sessions_spawn 会拒绝将以非沙箱方式运行的目标。
• subagents.requireAgentId：为 true 时，阻止省略 agentId 的 sessions_spawn 调用（强制显式选择配置文件；默认：false）。
• subagents.maxConcurrent：子智能体执行中的最大并发子智能体运行数。默认值：8。
• subagents.maxChildrenPerAgent：单个智能体会话可生成的最大活动子项数。默认值：5。
• subagents.maxSpawnDepth：子智能体生成的最大嵌套深度（1-5）。默认值：1（无嵌套）。
• subagents.archiveAfterMinutes：已完成子智能体状态归档前的时长。默认值：60。

​

多智能体路由

{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}

​

绑定匹配字段

• type（可选）：route 表示普通路由（缺失 type 时默认为 route），acp 表示持久 ACP 对话绑定。
• match.channel（必填）
• match.accountId（可选；* = 任意账号；省略 = 默认账号）
• match.peer（可选；{ kind: direct|group|channel, id }）
• match.guildId / match.teamId（可选；渠道特定）
• acp（可选；仅用于 type: "acp"）：{ mode, label, cwd, backend }

1. match.peer
2. match.guildId
3. match.teamId
4. match.accountId（精确匹配，无 peer/guild/team）
5. match.accountId: "*"（整个渠道）
6. 默认智能体

​

单智能体访问配置文件

{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: { mode: "off" },
      },
    ],
  },
}

{
  agents: {
    list: [
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: { mode: "all", scope: "agent", workspaceAccess: "ro" },
        tools: {
          allow: [
            "read",
            "sessions_list",
            "sessions_history",
            "sessions_send",
            "sessions_spawn",
            "session_status",
          ],
          deny: ["write", "edit", "apply_patch", "exec", "process", "browser"],
        },
      },
    ],
  },
}

{
  agents: {
    list: [
      {
        id: "public",
        workspace: "~/.openclaw/workspace-public",
        sandbox: { mode: "all", scope: "agent", workspaceAccess: "none" },
        tools: {
          allow: [
            "sessions_list",
            "sessions_history",
            "sessions_send",
            "sessions_spawn",
            "session_status",
            "whatsapp",
            "telegram",
            "slack",
            "discord",
            "gateway",
          ],
          deny: [
            "read",
            "write",
            "edit",
            "apply_patch",
            "exec",
            "process",
            "browser",
            "canvas",
            "nodes",
            "cron",
            "gateway",
            "image",
          ],
        },
      },
    ],
  },
}

​

会话

{
  session: {
    scope: "per-sender",
    dmScope: "main", // main | per-peer | per-channel-peer | per-account-channel-peer
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"],
    },
    reset: {
      mode: "daily", // daily | idle
      atHour: 4,
      idleMinutes: 60,
    },
    resetByType: {
      thread: { mode: "daily", atHour: 4 },
      direct: { mode: "idle", idleMinutes: 240 },
      group: { mode: "idle", idleMinutes: 120 },
    },
    resetByChannel: {
      discord: { mode: "idle", idleMinutes: 30 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    maintenance: {
      mode: "enforce", // enforce (default) | warn
      pruneAfter: "30d",
      maxEntries: 500,
      resetArchiveRetention: "30d", // duration or false
      maxDiskBytes: "500mb", // optional hard budget
      highWaterBytes: "400mb", // optional cleanup target
    },
    writeLock: {
      acquireTimeoutMs: 60000,
      staleMs: 1800000,
      maxHoldMs: 300000,
    },
    threadBindings: {
      enabled: true,
      idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables)
      maxAgeHours: 0, // default hard max age in hours (`0` disables)
    },
    mainKey: "main", // legacy (runtime always uses "main")
    agentToAgent: { maxPingPongTurns: 5 },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}

​

消息

{
  messages: {
    responsePrefix: "🦞", // or "auto"
    ackReaction: "👀",
    ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all | off | none
    removeAckAfterReply: false,
    queue: {
      mode: "steer", // steer (default) | followup | collect | interrupt
      debounceMs: 500,
      cap: 20,
      drop: "summarize", // old | new | summarize (default)
      byChannel: {
        whatsapp: "followup",
        telegram: "followup",
      },
    },
    inbound: {
      debounceMs: 2000, // 0 disables
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
      },
    },
  },
}

​

响应前缀

​

确认表情回应

• 默认使用活动 Agent 的 identity.emoji，否则使用 "👀"。设置为 "" 可禁用。
• 按渠道覆盖：channels.<channel>.ackReaction、channels.<channel>.accounts.<id>.ackReaction。
• 解析顺序：账号 → 渠道 → messages.ackReaction → 身份回退值。
• 范围：group-mentions（默认）、group-all、direct、all，或 off/none（完全禁用确认表情回应）。
• removeAckAfterReply：在 Slack、Discord、Signal、Telegram、WhatsApp 和 iMessage 等支持表情回应的渠道上，回复后移除确认表情回应。
• messages.statusReactions.enabled：在 Slack、Discord、Signal、Telegram 和 WhatsApp 上启用生命周期状态表情回应。 在 Discord 上，未设置时，如果确认表情回应处于活动状态，则保持启用状态表情回应。 在 Slack、Signal、Telegram 和 WhatsApp 上，显式设置为 true 以启用生命周期状态表情回应。 Slack 默认使用其原生助手线程状态和轮换加载消息显示进度，同时保持配置的确认表情回应静态不变。
• messages.statusReactions.emojis：覆盖生命周期 emoji 键： queued、thinking、compacting、tool、coding、web、deploy、build、 concierge、done、error、stallSoft 和 stallHard。 Telegram 只允许固定的表情回应集合，因此不受支持的已配置 emoji 会回退 到该聊天中最接近的受支持状态变体。

​

队列

• mode：当会话运行处于活动状态时，到达的入站消息使用的队列策略。默认值："steer"。
  • steer：将新提示注入活动运行。
  • followup：在活动运行完成后运行新提示。
  • collect：批处理兼容消息，稍后一起运行。
  • interrupt：在启动最新提示前中止活动运行。
• debounceMs：分发已排队/已 steer 消息前的延迟。默认值：500。
• cap：应用丢弃策略前的最大排队消息数。默认值：20。
• drop：超过上限时的策略。"summarize"（默认）会丢弃最旧条目但保留压缩摘要；"old" 丢弃最旧条目且不保留摘要；"new" 拒绝最新项目。
• byChannel：按渠道的 mode 覆盖，以提供商 id 为键。
• debounceMsByChannel：按渠道的 debounceMs 覆盖，以提供商 id 为键。

​

入站防抖

​

其他消息键

• messages.messagePrefix：在入站用户消息到达 Agent Runtimes 前预置的前缀文本。谨慎用于渠道上下文标记。
• messages.visibleReplies：控制 direct、group 和 channel 对话中的可见来源回复（"message_tool" 要求使用 message(action=send) 产生可见输出；"automatic" 像以前一样发布普通回复）。
• messages.usageTemplate / messages.responseUsage：自定义 /usage 页脚模板和默认每条回复用量模式（off | tokens | full，另有旧版 on 作为 tokens 的别名）。
• messages.groupChat.mentionPatterns / historyLimit：群组消息提及触发器和历史窗口大小。
• messages.suppressToolErrors：为 true 时，抑制向用户显示的 ⚠️ 工具错误警告（智能体仍会在上下文中看到错误并可重试）。默认值：false。

​

TTS（文本转语音）

{
  messages: {
    tts: {
      auto: "off", // off (default) | always | inbound | tagged
      mode: "final", // final | all
      provider: "elevenlabs",
      summaryModel: "openai/gpt-5.4-mini",
      modelOverrides: { enabled: true },
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
      providers: {
        elevenlabs: {
          apiKey: "elevenlabs_api_key",
          baseUrl: "https://api.elevenlabs.io",
          speakerVoiceId: "voice_id",
          modelId: "eleven_multilingual_v2",
          seed: 42,
          applyTextNormalization: "auto",
          languageCode: "en",
          voiceSettings: {
            stability: 0.5,
            similarityBoost: 0.75,
            style: 0.0,
            useSpeakerBoost: true,
            speed: 1.0,
          },
        },
        microsoft: {
          speakerVoice: "en-US-MichelleNeural",
          lang: "en-US",
          outputFormat: "audio-24khz-48kbitrate-mono-mp3",
        },
        openai: {
          apiKey: "openai_api_key",
          baseUrl: "https://api.openai.com/v1",
          model: "gpt-4o-mini-tts",
          speakerVoice: "coral",
        },
      },
    },
  },
}

• auto 控制默认的自动 TTS 模式：off、always、inbound 或 tagged。/tts on|off 可以覆盖本地偏好，/tts status 会显示生效状态。
• summaryModel 会覆盖用于自动摘要的 agents.defaults.model.primary。
• modelOverrides 默认启用（enabled !== false）；modelOverrides.allowProvider 需要选择启用。
• API 密钥会回退到 ELEVENLABS_API_KEY/XI_API_KEY 和 OPENAI_API_KEY。
• 内置语音提供商由插件拥有。如果设置了 plugins.allow，请包含你想使用的每个 TTS 提供商插件，例如用于 Edge TTS 的 microsoft。旧版 edge 提供商 id 会作为 microsoft 的别名被接受。
• providers.openai.baseUrl 会覆盖 OpenAI TTS 端点。解析顺序是配置，然后是 OPENAI_TTS_BASE_URL，然后是 https://api.openai.com/v1。
• 当 providers.openai.baseUrl 指向非 OpenAI 端点时，OpenClaw 会将其视为兼容 OpenAI 的 TTS 服务器，并放宽模型/语音校验。

​

Talk

{
  talk: {
    provider: "elevenlabs",
    providers: {
      elevenlabs: {
        speakerVoiceId: "elevenlabs_voice_id",
        voiceAliases: {
          Clawd: "EXAVITQu4vr4xnSDxMaL",
          Roger: "CwhRBWXzGAHq8TQ4Fs17",
        },
        modelId: "eleven_multilingual_v2",
        outputFormat: "mp3_44100_128",
        apiKey: "elevenlabs_api_key",
      },
      mlx: {
        modelId: "mlx-community/Soprano-80M-bf16",
      },
      system: {},
    },
    consultThinkingLevel: "low",
    consultFastMode: true,
    speechLocale: "ru-RU",
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
    realtime: {
      provider: "openai",
      providers: {
        openai: {
          model: "gpt-realtime-2",
          speakerVoice: "cedar",
        },
      },
      instructions: "Speak warmly and keep answers brief.",
      mode: "realtime", // realtime | stt-tts | transcription
      transport: "webrtc", // webrtc | provider-websocket | gateway-relay | managed-room
      vadThreshold: 0.5,
      silenceDurationMs: 500,
      prefixPaddingMs: 300,
      reasoningEffort: "medium",
      brain: "agent-consult", // agent-consult | direct-tools | none
    },
  },
}

• 配置多个 Talk 提供商时，talk.provider 必须匹配 talk.providers 中的一个键。
• 旧版扁平 Talk 键（talk.voiceId、talk.voiceAliases、talk.modelId、talk.outputFormat、talk.apiKey）仅用于兼容。运行 openclaw doctor --fix 可将持久化配置重写为 talk.providers.<provider>。
• 语音 ID 会回退到 ELEVENLABS_VOICE_ID 或 SAG_VOICE_ID（macOS Talk 客户端行为）。
• providers.*.apiKey 接受明文字符串或 SecretRef 对象。
• 仅在未配置 Talk API 密钥时，才会应用 ELEVENLABS_API_KEY 回退。
• providers.*.voiceAliases 让 Talk 指令可以使用友好名称。
• providers.mlx.modelId 选择 macOS 本地 MLX 辅助程序使用的 Hugging Face 仓库。如果省略，macOS 会使用 mlx-community/Soprano-80M-bf16。
• macOS MLX 播放会在存在时通过内置的 openclaw-mlx-tts 辅助程序运行，或通过 PATH 上的可执行文件运行；OPENCLAW_MLX_TTS_BIN 会覆盖开发用辅助程序路径。
• consultThinkingLevel 控制 Control UI Talk 实时 openclaw_agent_consult 调用背后的完整 OpenClaw agent 运行的思考级别。保持未设置可保留正常会话/模型行为。
• consultFastMode 为 Control UI Talk 实时 consult 设置一次性快速模式覆盖，而不会更改会话的正常快速模式设置。
• speechLocale 设置 iOS/macOS Talk 语音识别使用的 BCP 47 区域设置 id。保持未设置会使用设备默认值。
• silenceTimeoutMs 控制 Talk 模式在用户静默后等待多久才发送转录。未设置会保留平台默认暂停窗口（macOS 和 Android 上为 700 ms，iOS 上为 900 ms）。
• realtime.instructions 会向 OpenClaw 内置实时提示追加面向提供商的系统指令，因此可配置语音风格而不丢失默认 openclaw_agent_consult 指引。
• realtime.vadThreshold 设置提供商的语音活动阈值，范围从 0（最敏感）到 1（最不敏感）。未设置会保留提供商默认值。
• realtime.silenceDurationMs 设置提供商提交实时用户轮次前的正整数静默窗口。未设置会保留提供商默认值。
• realtime.prefixPaddingMs 设置在检测到语音开始前保留的非负整数音频量。未设置会保留提供商默认值。
• realtime.reasoningEffort 设置实时会话的提供商特定推理级别。未设置会保留提供商默认值。
• realtime.consultRouting："provider-direct"（默认）会在实时提供商生成没有 openclaw_agent_consult 的最终用户转录时，保留直接提供商回复。"force-agent-consult" 会改为通过 OpenClaw 路由最终请求。

​

相关

• 配置参考 — 所有其他配置键
• 配置 — 常见任务和快速设置
• 配置示例