OpenClaw 的 agent 配置集中在 agents.*、multiAgent.*、session.*、messages.* 和 talk.* 等键下。你可以通过 agents.list[] 为每个智能体独立设置模型、工作区、技能、沙箱和运行时策略，或者用 agents.defaults 提供全局默认值，减少重复。合理的 compaction 和 contextPruning 能控制 token 消耗，而 multi-agent routing 让不同渠道来源的消息自动路由到对应智能体。遇到配置问题先用 openclaw doctor --fix 清理字段并验证 sink。

OpenClaw Agent 配置：默认值、多智能体路由、会话与消息

代理（agent）作用域的配置键位于 agents.*、multiAgent.*、session.*、messages.* 以及 talk.* 下。关于渠道、工具、网关运行时和其他顶级键，参见配置参考。

智能体默认值

`agents.defaults.workspace`

默认值：环境变量 OPENCLAW_WORKSPACE_DIR 的值（若设置），否则为 ~/.openclaw/workspace。

json5

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

明确设置的 agents.defaults.workspace 优先级高于 OPENCLAW_WORKSPACE_DIR。如果你不想把挂载路径写进配置文件，可以使用环境变量让默认智能体指向已挂载的工作区。

`agents.defaults.repoRoot`

可选的仓库根目录，会显示在系统提示（system prompt）的 Runtime 行中。如果未设置，OpenClaw 会从工作区往上自动检测。

json5

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

`agents.defaults.skills`

可选默认技能允许列表，供未设置 agents.list[].skills 的智能体继承。

json5

{
  agents: {
    defaults: { skills: ["github", "weather"] },
    list: [
      { id: "writer" },                     // 继承 github, weather
      { id: "docs", skills: ["docs-search"] }, // 替换默认值
      { id: "locked-down", skills: [] },      // 无技能
    ],
  },
}

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

`agents.defaults.skipBootstrap`

禁止自动创建工作区引导文件（AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、HEARTBEAT.md、BOOTSTRAP.md）。

json5

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

`agents.defaults.skipOptionalBootstrapFiles`

跳过选中的可选工作区文件，但仍会写入必需的引导文件。有效值：SOOL.md、USER.md、HEARTBEAT.md、IDENTITY.md。

json5

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

`agents.defaults.contextInjection`

控制工作区引导文件在何时注入系统提示中。默认值："always"。

"continuation-skip"：安全延续轮次（助手完成回复后）跳过工作区引导文件的重新注入，减少提示大小。心跳运行和压缩后重试仍会重建上下文。
"never"：完全禁止注入工作区引导和上下文文件。只用于那些完全自主管理提示生命周期的智能体（自定义上下文引擎、原生运行时自己构建上下文，或无引导的工作流）。心跳和压缩恢复轮次也会跳过注入。

json5

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

每个智能体可覆盖：agents.list[].contextInjection。省略的值继承 agents.defaults.contextInjection。

`agents.defaults.bootstrapMaxChars`

每个工作区引导文件被截断前的最大字符数。默认值：12000。

json5

{
  agents: { defaults: { bootstrapMaxChars: 12000 } },
}

每个智能体可覆盖：agents.list[].bootstrapMaxChars。省略的值继承 agents.defaults.bootstrapMaxChars。

`agents.defaults.bootstrapTotalMaxChars`

所有工作区引导文件总共注入的最大字符数。默认值：60000。

json5

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

每个智能体可覆盖：agents.list[].bootstrapTotalMaxChars。省略的值继承 agents.defaults.bootstrapTotalMaxChars。

每个智能体的引导配置覆盖

当一个智能体需要与共享默认值不同的提示注入行为时，使用每个智能体的引导配置覆盖。省略的字段继承自 agents.defaults。

json5

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

`agents.defaults.bootstrapPromptTruncationWarning`

控制当引导上下文被截断时智能体可见的系统提示通知。默认值："always"。

"off"：从不向系统提示注入截断通知文本。
"once"：同一截断签名只注入一次简短通知。
"always"：每次存在截断时都注入简短通知（推荐）。

详细的原始/注入计数和调优字段保留在诊断信息中（如 context/status 报告和日志）；日常的 WebChat 用户/运行时上下文只收到简洁的恢复通知。

json5

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

上下文预算所有权映射

OpenClaw 有多个高容量的提示/上下文预算，它们按子系统分开，而不是共用一个通用旋钮。

agents.defaults.bootstrapMaxChars / agents.defaults.bootstrapTotalMaxChars：普通工作区引导注入。
agents.defaults.startupContext.*：一次性重置/启动模型运行的前奏，包括最近的每日 memory/*.md 文件。仅聊天的 /new 和 /reset 命令会确认重置，不会调用模型。
skills.limits.*：注入系统提示的紧凑技能列表。
agents.defaults.contextLimits.*：受限的运行时摘录和注入的运行时自有块。
memory.qmd.limits.*：索引记忆搜索片段和注入大小。

仅当某个智能体需要不同预算时，使用对应的每个智能体覆盖：

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

`agents.defaults.startupContext`

控制重置/启动模型运行时注入的首轮启动前奏。仅聊天的 /new 和 /reset 命令确认重置而不调用模型，因此它们不会加载这段前奏。

json5

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

`agents.defaults.contextLimits`

受限运行时上下面的共享默认值。

json5

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

memoryGetMaxChars：默认的 memory_get 摘录在添加截断元数据和继续通知前的上限。
memoryGetDefaultLines：当省略 lines 时默认的 memory_get 行窗口。
toolResultMaxChars：持久化结果和溢出恢复中实时工具结果的上限。
postCompactionMaxChars：压缩后刷新注入时 AGENTS.md 摘录的上限。

`agents.list[].contextLimits`

每个智能体覆盖共享 contextLimits 旋钮。省略的字段继承自 agents.defaults.contextLimits。

json5

{
  agents: {
    defaults: {
      contextLimits: {
        memoryGetMaxChars: 12000,
        toolResultMaxChars: 16000,
      },
    },
    list: [
      {
        id: "tiny-local",
        contextLimits: {
          memoryGetMaxChars: 6000,
          toolResultMaxChars: 8000,
        },
      },
    ],
  },
}

`skills.limits.maxSkillsPromptChars`

注入系统提示的紧凑技能列表的全局上限。这不影响按需读取 SKILL.md 文件。

json5

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

`agents.list[].skillsLimits.maxSkillsPromptChars`

每个智能体覆盖技能提示预算。

json5

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

`agents.defaults.imageMaxDimensionPx`

在调用 provider 之前，转录/工具图像块中图片最长边的最大像素值。默认值：1200。

较低的数值通常会减少屏幕截图密集型运行的视觉 token 使用和请求payload大小。较高的数值保留更多视觉细节。

json5

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

`agents.defaults.userTimezone`

系统提示上下文中的时区（不是消息时间戳）。回退到主机时区。

json5

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

`agents.defaults.timeFormat`

系统提示中的时间格式。默认值：auto（操作系统偏好）。

json5

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

`agents.defaults.model`

json5

{
  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"],
      },
      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" }, // 全局默认 provider 参数
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "off",
      toolProgressDetail: "explain",
      reasoningDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      contextTokens: 200000,
      maxConcurrent: 3,
    },
  },
}

model：接受字符串（"provider/model"）或对象（{ primary, fallbacks }）。
- 字符串形式只设置主要模型。
- 对象形式设置主要模型和有序的故障转移模型。
imageModel：接受字符串（"provider/model"）或对象（{ primary, fallbacks }）。
- 被 image 工具路径用作其视觉模型配置。
- 也用作当选定/默认模型无法接受图像输入时的回退路由。
- 优先使用显式的 provider/model 引用。裸 ID 为兼容性而接受；如果裸 ID 唯一匹配 models.providers.*.models 中配置的图像兼容条目，OpenClaw 会将其限定到该 provider。模糊的配置匹配需要显式 provider 前缀。
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 输出）。
- 如果直接选择 provider/model，需要配置对应的 provider 认证（例如 GEMINI_API_KEY 或 GOOGLE_API_KEY 用于 google/*，OPENAI_API_KEY 或 OpenAI Codex OAuth 用于 openai/gpt-image-2 / openai/gpt-image-1.5，FAL_KEY 用于 fal/*）。
- 如果省略，image_generate 仍能推断一个基于认证的 provider 默认值。它会先尝试当前默认 provider，然后按 provider-id 顺序尝试剩余已注册的图像生成 provider。
musicGenerationModel：接受字符串（"provider/model"）或对象（{ primary, fallbacks }）。
- 被共享的音乐生成能力和内置的 music_generate 工具使用。
- 典型值：google/lyria-3-clip-preview、google/lyria-3-pro-preview 或 minimax/music-2.6。
- 如果省略，music_generate 仍能推断一个基于认证的 provider 默认值。它会先尝试当前默认 provider，然后按 provider-id 顺序尝试剩余已注册的音乐生成 provider。
- 如果直接选择 provider/model，需要配置对应的 provider 认证/API 密钥。
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 仍能推断一个基于认证的 provider 默认值。它会先尝试当前默认 provider，然后按 provider-id 顺序尝试剩余已注册的视频生成 provider。
- 如果直接选择 provider/model，需要配置对应的 provider 认证/API 密钥。
- 捆绑的 Qwen 视频生成 provider 支持最多 1 个输出视频、1 个输入图像、4 个输入视频、10 秒时长，以及 provider 级别的 size、aspectRatio、resolution、audio 和 watermark 选项。
pdfModel：接受字符串（"provider/model"）或对象（{ primary, fallbacks }）。
- 由 pdf 工具用于模型路由。
- 如果省略，pdf 工具会回退到 imageModel，然后到已解析的 session/默认模型。
pdfMaxBytesMb：pdf 工具在调用时未传递 maxBytesMb 情况下的默认 PDF 大小限制。
pdfMaxPages：pdf 工具在提取回退模式下考虑的默认最大页数。
verboseDefault：智能体的默认详细级别。值："off"、"on"、"full"。默认值："off"。
toolProgressDetail：/verbose 工具摘要和进度草稿工具行的详细模式。值："explain"（默认，紧凑的人类标签）或 "raw"（如果可用，附加原始命令/详细信息）。每个智能体 agents.list[].toolProgressDetail 覆盖此默认值。
reasoningDefault：智能体的默认推理可见性。值："off"、"on"、"stream"。每个智能体 agents.list[].reasoningDefault 覆盖此默认值。配置的推理默认值仅在未设置每条消息或 session 推理覆盖时应用于所有者、授权发送者或 operator-admin 网关上下文。
elevatedDefault：智能体的默认提升输出级别。值："off"、"on"、"ask"、"full"。默认值："on"。
model.primary：格式 provider/model（例如 openai/gpt-5.5 用于 OpenAI API 密钥或 Codex OAuth 访问）。如果省略 provider，OpenClaw 先尝试别名，然后尝试与配置的 provider 完全匹配该模型 ID，最后才回退到配置的默认 provider（已弃用的兼容性行为，所以优先使用显式 provider/model）。如果该 provider 不再暴露配置的默认模型，OpenClaw 会回退到第一个配置的 provider/model，而不是显示一个过时的已移除 provider 的默认值。
models：配置的模型目录和 /model 的允许列表。每个条目可以包含 alias（快捷方式）和 params（provider 特定的，例如 temperature、maxTokens、cacheRetention、context1m、responsesServerCompaction、responsesCompactThreshold、OpenRouter provider 路由、chat_template_kwargs、extra_body/extraBody）。
- 使用 provider/* 条目，例如 "openai-codex/*": {} 或 "vllm/*": {}，无需手动列出每个模型 ID 即可显示所选 provider 的所有自动发现模型。
- 如果每个自动发现的模型都应使用相同的运行时，请在 provider/* 条目中添加 agentRuntime。精确的 provider/model 运行时策略仍然胜于通配符。
- 安全编辑：使用 openclaw config set agents.defaults.models '<json>' --strict-json --merge 添加条目。config set 拒绝会移除现有允许列表条目的替换，除非传递 --replace。
- Provider 作用域的配置/引导流程会将选中的 provider 模型合并到此映射中，并保留已配置的其他 provider。
- 对于直接使用 OpenAI Responses 模型的，服务器端压缩会自动启用。使用 params.responsesServerCompaction: false 停止注入 context_management，或使用 params.responsesCompactThreshold 覆盖阈值。参见 OpenAI 服务器端压缩。
params：应用于所有模型的全局默认 provider 参数。在 agents.defaults.params 中设置（例如 { cacheRetention: "long" }）。
params 合并优先级（配置）：agents.defaults.params（全局基础）被 agents.defaults.models["provider/model"].params（每个模型）覆盖，然后 agents.list[].params（匹配的智能体 ID）按键覆盖。参见提示缓存获取详细信息。
models.providers.openrouter.params.provider：OpenRouter 全局默认 provider 路由策略。OpenClaw 会将其转发到 OpenRouter 请求的 provider 对象；每个模型的 agents.defaults.models["openrouter/<model>"].params.provider 和智能体参数按键覆盖。参见 OpenRouter provider 路由。
params.extra_body/params.extraBody：高级透传 JSON，合并到 api: "openai-completions" 请求体中，用于 OpenAI 兼容代理。如果与生成的请求键冲突，extra body 优先；非原生补全路径仍会在之后剥离 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 思考控制，在该模型条目上设置 params.qwenThinkingFormat 为 "chat-template" 或 "top-level"。
compat.thinkingFormat：OpenAI 兼容的思考载荷样式。使用 "together" 表示 Together 风格的 reasoning.enabled，"qwen" 表示 Qwen 风格的顶层 enable_thinking，或 "qwen-chat-template" 用于 Qwen 系列后端（如 vLLM）上通过请求级 chat_template_kwargs 的思考控制。OpenClaw 将禁用思考映射为 false，启用思考映射为 true。
compat.supportedReasoningEfforts：每个模型的 OpenAI 兼容思考 effort 列表。如果自定义端点确实支持 "xhigh"，则包含它；OpenClaw 会在该配置的 provider/model 的命令菜单、Gateway session 行、session 补丁验证、智能体 CLI 验证和 llm-task 验证中暴露 /think xhigh。当后端希望为规范级别提供 provider 特定值时，使用 compat.reasoningEffortMap。
params.preserveThinking：Z.AI 独有选择加入的保留思考。启用且思考打开时，OpenClaw 发送 thinking.clear_thinking: false 并重放先前的 reasoning_content；参见 Z.AI 思考和保留思考。
localService：可选的 provider 级进程管理器，用于本地/自托管模型服务器。当选定的模型属于该 provider 时，OpenClaw 探测 healthUrl（或 baseUrl + "/models"），如果端点不可用则启动 command 和 args，等待 readyTimeoutMs，然后发送模型请求。command 必须是绝对路径。idleStopMs: 0 使进程保持活动直到 OpenClaw 退出；正数值会在空闲那么多毫秒后停止 OpenClaw 启动的进程。参见本地模型服务。
运行时策略应放在 providers 或 models 上，而不是 agents.defaults。使用 models.providers.<provider>.agentRuntime 指定 provider 范围的规则，或使用 agents.defaults.models["provider/model"].agentRuntime / agents.list[].models["provider/model"].agentRuntime 指定模型特定的规则。官方 OpenAI provider 上的 OpenAI 智能体模型默认选择 Codex。
配置写入器（例如 /models set、/models set-image 以及回退添加/删除命令）会保存规范的对象形式，并在可能时保留现有的回退列表。
maxConcurrent：跨 session 的最大并行智能体运行数（每个 session 仍然是序列化的）。默认值：4。

运行时策略

json5

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

id："auto"、"pi"、注册的插件 harness id，或支持的 CLI 后端别名。捆绑的 Codex 插件注册 codex；捆绑的 Anthropic 插件提供 claude-cli CLI 后端。
id: "auto" 让注册的插件 harness 声明支持的轮次，没有 harness 匹配时使用 PI。显式插件运行时（如 id: "codex"）需要该 harness，如果不可用或失败则错误关闭。
运行时优先级如下：精确模型策略（agents.list[].models["provider/model"]、agents.defaults.models["provider/model"] 或 models.providers.<provider>.models[]）> agents.list[] / agents.defaults.models["provider/*"] > provider 范围策略（models.providers.<provider>.agentRuntime）。
整体智能体运行时键已弃用。agents.defaults.agentRuntime、agents.list[].agentRuntime、session 运行时引脚和 OPENCLAW_AGENT_RUNTIME 在运行时选择中被忽略。运行 openclaw doctor --fix 移除过时值。
OpenAI 智能体模型默认使用 Codex harness；如果你想显式指定，agentRuntime.id: "codex" 仍然有效。
对于 Claude CLI 部署，首选 model: "anthropic/claude-opus-4-7" 加上模型作用域的 agentRuntime.id: "claude-cli"。旧的 claude-cli/claude-opus-4-7 模型引用仍然兼容，但新配置应保持 provider/model 选择规范，并将执行后端放在 provider/model 运行时策略中。
这只控制文本智能体轮次的执行。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用它们自己的 provider/model 设置。

内置别名快捷方式（仅当模型在 agents.defaults.models 中时适用）：

别名	模型
`opus`	`anthropic/claude-opus-4-6`
`sonnet`	`anthropic/claude-sonnet-4-6`
`gpt`	`openai/gpt-5.5`
`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-preview`

你配置的别名始终优先于默认值。

Z.AI GLM-4.x 模型会默认启用思考模式，除非你设置 --thinking off 或自行定义 agents.defaults.models["zai/<model>"].params.thinking。 Z.AI 模型默认启用 tool_stream 进行工具调用流式输出。设置 agents.defaults.models["zai/<model>"].params.tool_stream 为 false 以禁用它。当未设置显式思考级别时，Anthropic Claude 4.6 模型默认为 adaptive 思考。

`agents.defaults.cliBackends`

文本专用回退运行（无工具调用）的可选 CLI 后端。当 API provider 失败时，可作为备份。

json5

{
  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",
          // 或者当 CLI 接受提示文件标志时使用 systemPromptFileArg。
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
        },
      },
    },
  },
}

CLI 后端是文本优先的；工具始终禁用。
当设置 sessionArg 时，支持 session。
当 imageArg 接受文件路径时，支持图像传递。
reseedFromRawTranscriptWhenUncompacted: true 让后端在首次压缩摘要存在之前，从有限长度的原始 OpenClaw 转录尾部恢复安全的无效 session。认证配置文件或凭证周期变更仍不会进行原始重新播种。

`agents.defaults.systemPromptOverride`

用固定字符串替换整个 OpenClaw 构建的系统提示。可在默认级别（agents.defaults.systemPromptOverride）或每个智能体（agents.list[].systemPromptOverride）设置。每个智能体的值优先；空值或仅空白值被忽略。适用于受控提示实验。

json5

{
  agents: {
    defaults: {
      systemPromptOverride: "You are a helpful assistant.",
    },
  },
}

`agents.defaults.promptOverlays`

Provider 无关的提示覆盖，按模型系列应用于 OpenClaw 构建的提示表面。GPT-5 系列模型 ID 在 PI/provider 路由之间接收共享的行为契约；personality 仅控制友好交互样式层。原生 Codex 应用服务器路由保留 Codex 拥有的基础/模型/人格指令，而不是此 OpenClaw GPT-5 覆盖。

json5

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

"friendly"（默认）和 "on" 启用友好交互样式层。
"off" 仅禁用友好层；标记的 GPT-5 行为契约保留启用。
旧的 plugins.entries.openai.config.personality 在此共享设置未设置时仍会被读取。

`agents.defaults.heartbeat`

周期性心跳运行。

json5

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 0m 禁用
        model: "openai/gpt-5.4-mini",
        includeReasoning: false,
        includeSystemPromptSection: true, // 默认: true; false 会从系统提示中省略 Heartbeat 部分
        lightContext: false, // 默认: false; true 仅保留工作区引导文件中的 HEARTBEAT.md
        isolatedSession: false, // 默认: false; true 在全新 session 中运行每次心跳（无对话历史）
        skipWhenBusy: false, // 默认: false; true 还会等待此智能体的子智能体/嵌套通道
        session: "main",
        to: "+15555550123",
        directPolicy: "allow", // allow (默认) | block
        target: "none", // 默认: none | 选项: last | whatsapp | telegram | discord | ...
        prompt: "Read HEARTBEAT.md if it exists...",
        ackMaxChars: 300,
        suppressToolErrorWarnings: false,
        timeoutSeconds: 45,
      },
    },
  },
}

every：持续时间字符串（ms/s/m/h）。默认值：30m（API 密钥认证）或 1h（OAuth 认证）。设为 0m 禁用。
includeSystemPromptSection：为 false 时，从系统提示中省略 Heartbeat 部分，并跳过将 HEARTBEAT.md 注入引导上下文。默认值：true。
suppressToolErrorWarnings：为 true 时，抑制心跳运行期间的工具错误警告载荷。
timeoutSeconds：心跳智能体轮次在终止前允许的最大秒数。未设置则使用 agents.defaults.timeoutSeconds。
directPolicy：直接/DM 传递策略。allow（默认）允许直接目标传递。block 抑制直接目标传递并发出 reason=dm-blocked。
lightContext：为 true 时，心跳运行使用轻量引导上下文，仅保留工作区引导文件中的 HEARTBEAT.md。
isolatedSession：为 true 时，每次心跳在新的 session 中运行，没有之前的对话历史。与 cron sessionTarget: "isolated" 相同的隔离模式。可将每次心跳的 token 成本从约 100K 降至约 2-5K token。
skipWhenBusy：为 true 时，心跳运行会推迟该智能体的额外繁忙通道：其 own session 键的子智能体或嵌套命令工作。cron 通道总是会推迟心跳，即使没有此标志。
每个智能体：设置 agents.list[].heartbeat。当任何智能体定义了 heartbeat，只有那些智能体 运行心跳。
心跳运行完整的智能体轮次——较短的间隔会消耗更多 token。

`agents.defaults.compaction`

json5

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
        provider: "my-provider", // 已注册的压缩 provider 插件 ID（可选）
        timeoutSeconds: 900,
        reserveTokensFloor: 24000,
        keepRecentTokens: 50000,
        identifierPolicy: "strict", // strict | off | custom
        identifierInstructions: "保留部署 ID、工单 ID 和 host:port 对。", // identifierPolicy=custom 时使用
        qualityGuard: { enabled: true, maxRetries: 1 },
        midTurnPrecheck: { enabled: false }, // 可选的 Pi 工具循环压力检查
        postCompactionSections: ["Session Startup", "Red Lines"], // [] 禁用重新注入
        model: "openrouter/anthropic/claude-sonnet-4-6", // 可选的仅压缩模型覆盖
        truncateAfterCompaction: true, // 压缩后轮换到更小的后续 JSONL
        maxActiveTranscriptBytes: "20mb", // 可选的预检本地压缩触发器
        notifyUser: true, // 压缩开始和完成时发送简短通知（默认: false）
        memoryFlush: {
          enabled: true,
          model: "ollama/qwen3:8b", // 可选的仅内存刷新模型覆盖
          softThresholdTokens: 6000,
          systemPrompt: "Session 即将压缩。现在存储持久记忆。",
          prompt: "写下任何持久的笔记到 memory/YYYY-MM-DD.md；如果没有什么要存储的，回复精确的静默 token NO_REPLY。",
        },
      },
    },
  },
}

mode：default 或 safeguard（用于长历史的分块摘要）。参见压缩。
provider：已注册的压缩 provider 插件 ID。设置后，调用该 provider 的 summarize() 代替内置 LLM 摘要。失败时回退到内置。设置 provider 会强制 mode: "safeguard"。参见压缩。
timeoutSeconds：单个压缩操作在 OpenClaw 中止前允许的最大秒数。默认值：900。
keepRecentTokens：Pi 切割点预算，用于保留最新转录尾部原文。手动 /compact 在显式设置时会遵守此值；否则手动压缩是硬检查点。
identifierPolicy：strict（默认）、off 或 custom。strict 在压缩摘要期间注入内置的不透明标识符保留指导。
identifierInstructions：当 identifierPolicy=custom 时使用的可选自定义标识符保留文本。
qualityGuard：对 safeguard 摘要进行输出格式错误重试检查。safeguard 模式下默认启用；设置 enabled: false 跳过审计。
midTurnPrecheck：可选的 Pi 工具循环压力检查。enabled: true 时，OpenClaw 在工具结果追加后、下一次模型调用前检查上下文压力。如果上下文不再合适，则在提交提示前中止当前尝试，并使用现有的预检恢复路径截断工具结果或压缩并重试。与 default 和 safeguard 压缩模式都兼容。默认：禁用。
postCompactionSections：可选的 AGENTS.md H2/H3 节名称，压缩后重新注入。默认值：["Session Startup", "Red Lines"]；设置 [] 禁用重新注入。当未设置或显式设置为该默认对时，旧的 Every Session/Safety 标题也被接受为兼容回退。
model：可选的 provider/model-id 覆盖，仅用于压缩摘要。当主 session 应保持一个模型但压缩摘要使用另一个模型时使用；未设置时，压缩使用 session 的主要模型。
maxActiveTranscriptBytes：可选的字节阈值（数字或类似 "20mb" 的字符串），当活动 JSONL 增长超过阈值时，在运行前触发正常本地压缩。需要 truncateAfterCompaction 使成功压缩能轮换到更小的后续转录。未设置或为 0 时禁用。
notifyUser：为 true 时，在压缩开始和完成时向用户发送简短通知（例如 "Compacting context..." 和 "Compaction complete"）。默认禁用，保持压缩静默。
memoryFlush：自动压缩前的静默智能体轮次，用于存储持久记忆。将 model 设置为精确的 provider/model，如 ollama/qwen3:8b，当此维护轮次应保留在本地模型上时；该覆盖不会继承活动 session 的回退链。工作区只读时跳过。

`agents.defaults.runRetries`

嵌入的 Pi 运行器外层运行循环的重试迭代边界，以防止故障恢复期间的无限执行循环。请注意，此设置目前仅适用于嵌入的智能体运行时，不适用于 ACP 或 CLI 运行时。

json5

{
  agents: {
    defaults: {
      runRetries: {
        base: 24,
        perProfile: 8,
        min: 32,
        max: 160,
      },
    },
    list: [
      {
        id: "main",
        runRetries: { max: 50 }, // 可选的每个智能体覆盖
      },
    ],
  },
}

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

`agents.defaults.contextPruning`

在发送给 LLM 之前，从内存上下文中修剪旧的工具结果。不修改磁盘上的 session 历史。

json5

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl", // off | cache-ttl
        ttl: "1h", // 持续时间 (ms/s/m/h), 默认单位: 分钟
        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"] },
      },
    },
  },
}

cache-ttl 模式行为

mode: "cache-ttl" 启用修剪轮次。
ttl 控制修剪可再次运行的间隔（自上次缓存触及后）。
修剪首先对过大的工具结果进行软裁剪（soft-trim），然后在需要时对较旧的结果进行硬清除（hard-clear）。

软裁剪：保留开头和结尾，中间插入 ...。

硬清除：用占位符替换整个工具结果。

注意：

图像块永远不会被修剪/清除。
比例是基于字符的（近似），不是精确的 token 计数。
如果小于 keepLastAssistants 条助手消息，则跳过修剪。

参见Session 修剪获取行为细节。

块流式

json5

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

非 Telegram 渠道需要显式的 *.blockStreaming: true 以启用块回复。
渠道覆盖：channels.<channel>.blockStreamingCoalesce（以及每个账号的变体）。Signal/Slack/Discord/Google Chat 默认 minChars: 1500。
humanDelay：块回复之间的随机暂停。natural = 800–2500ms。每个智能体覆盖：agents.list[].humanDelay。

参见流式获取行为和分块细节。

正在输入指示器

json5

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

默认值：直接聊天/提及为 instant，未被提及的群聊为 message。
每个 session 覆盖：session.typingMode、session.typingIntervalSeconds。

参见正在输入指示器。

`agents.defaults.sandbox`

嵌入智能体的可选沙箱。参见沙箱获取完整指南。

json5

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        backend: "docker", // docker | ssh | openshell
        scope: "agent", // session | agent | shared
        workspaceAccess: "none", // none | 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,
          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 / 内联内容：
          // 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"],
      },
    },
  },
}

沙箱详情

后端：

docker：本地 Docker 运行时（默认）
ssh：通用 SSH 后端远程运行时
openshell：OpenShell 运行时

当选择 backend: "openshell" 时，运行时特定设置移至 plugins.entries.openshell.config。

SSH 后端配置：

target：user@host[:port] 格式的 SSH 目标
command：SSH 客户端命令（默认：ssh）
workspaceRoot：用于每个作用域工作区的远程绝对根目录
identityFile / certificateFile / knownHostsFile：传递给 OpenSSH 的现有本地文件
identityData / certificateData / knownHostsData：OpenClaw 在运行时具体化为临时文件的内联内容或 SecretRef
strictHostKeyChecking / updateHostKeys：OpenSSH 主机密钥策略旋钮

SSH 认证优先级：

identityData 优先于 identityFile
certificateData 优先于 certificateFile
knownHostsData 优先于 knownHostsFile
SecretRef 支持的 *Data 值在沙箱 session 开始前从活动 secrets 运行时快照解析

SSH 后端行为：

创建或重新创建后播种远程工作区一次
然后保持远程 SSH 工作区规范
通过 SSH 路由 exec、文件工具和媒体路径
不会自动将远程更改同步回主机
不支持沙箱浏览器容器

工作区访问：

none：~/.openclaw/sandboxes 下的各作用域沙箱工作区
ro：沙箱工作区位于 /workspace，智能体工作区以只读方式挂载在 /agent
rw：智能体工作区以读写方式挂载在 /workspace

作用域：

session：每个 session 的容器 + 工作区
agent：每个智能体的容器 + 工作区（默认）
shared：共享容器和工作区（无跨 session 隔离）

OpenShell 插件配置：

json5

{
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          mode: "mirror", // mirror | remote
          from: "openclaw",
          remoteWorkspaceDir: "/sandbox",
          remoteAgentWorkspaceDir: "/agent",
          gateway: "lab", // 可选
          gatewayEndpoint: "https://lab.example", // 可选
          policy: "strict", // 可选的 OpenShell 策略 ID
          providers: ["openai"], // 可选
          autoProviders: true,
          timeoutSeconds: 120,
        },
      },
    },
  },
}

OpenShell 模式：

mirror：执行前从本地播种到远程，执行后同步回来；本地工作区保持规范
remote：创建沙箱时播种远程一次，然后保持远程工作区规范

在 remote 模式下，在 OpenClaw 外部进行的主机本地编辑不会在播种步骤后自动同步到沙箱。传输层是通过 SSH 进入 OpenShell 沙箱，但插件拥有沙箱生命周期和可选的镜像同步。

setupCommand 在容器创建后运行一次（通过 sh -lc）。需要网络出口、可写根目录、root 用户。

容器默认 network: "none" —— 如果智能体需要出站访问，设置为 "bridge"（或自定义桥接网络）。"host" 被阻止。"container:<id>" 默认被阻止，除非你显式设置 sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true（应急方案）。活动 OpenClaw 沙箱中的 Codex 应用服务器轮次使用相同的出口设置来获取其原生代码模式的网络访问。

入站附件 被暂存到活动工作区的 media/inbound/*。

docker.binds 挂载额外的主机目录；全局和每个智能体的绑定会合并。

沙箱浏览器（sandbox.browser.enabled）：Chromium + CDP 在容器中。noVNC URL 注入系统提示。不需要在 openclaw.json 中设置 browser.enabled。 noVNC 观察者访问默认使用 VNC 认证，OpenClaw 发出一个短效 token URL（而不是在共享 URL 中暴露密码）。

allowHostControl: false（默认）阻止沙箱 session 针对主机浏览器。
network 默认为 openclaw-sandbox-browser（专用桥接网络）。仅当你显式想要全局桥接连接时才设为 bridge。
cdpSourceRange 可选限制容器边缘的 CDP 入站到 CIDR 范围（例如 172.21.0.1/32）。
sandbox.browser.binds 仅在沙箱浏览器容器中挂载额外主机目录。当设置时（包括 []），它替换浏览器容器的 docker.binds。
启动默认值在 scripts/sandbox-browser-entrypoint.sh 中定义，并为容器主机调优：
- --remote-debugging-address=127.0.0.1
- --remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>
- --user-data-dir=${HOME}/.chrome
- --no-first-run
- --no-default-browser-check
- --disable-3d-apis
- --disable-gpu
- --disable-software-rasterizer
- --disable-dev-shm-usage
- --disable-background-networking
- --disable-features=TranslateUI
- --disable-breakpad
- --disable-crash-reporter
- --renderer-process-limit=2
- --no-zygote
- --metrics-recording-only
- --disable-extensions（默认启用）
- --disable-3d-apis、--disable-software-rasterizer 和 --disable-gpu 默认启用，如果需要 WebGL/3D 用法，可以通过 OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 禁用。
- OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 如果你的工作流依赖扩展，重新启用它们。
- --renderer-process-limit=2 可以通过 OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N> 更改；设为 0 使用 Chromium 的默认进程限制。
- 加上启用 noSandbox 时的 --no-sandbox。
- 默认值是容器镜像基线；使用自定义浏览器镜像和自定义入口点来更改容器默认值。

浏览器沙箱和 sandbox.docker.binds 仅适用于 Docker。

构建镜像（从源码 checkout）：

bash

scripts/sandbox-setup.sh           # 主沙箱镜像
scripts/sandbox-browser-setup.sh   # 可选浏览器镜像

对于没有源码 checkout 的 npm 安装，请参见沙箱 § 镜像和设置获取内联 docker build 命令。

`agents.list`（每个智能体覆盖）

使用 agents.list[].tts 为智能体指定自己的 TTS provider、声音、模型、风格或自动 TTS 模式。智能体块会深度合并全局 messages.tts，因此共享凭据可以放在一个地方，而个别智能体只覆盖它们需要的语音或 provider 字段。活动智能体的覆盖适用于自动语音回复、/tts audio、/tts status 和 tts 智能体工具。参见文本转语音获取 provider 示例和优先级。

json5

{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        name: "Main Agent",
        workspace: "~/.openclaw/workspace",
        agentDir: "~/.openclaw/agents/main/agent",
        model: "anthropic/claude-opus-4-6", // 或 { primary, fallbacks }
        thinkingDefault: "high", // 每个智能体思考级别覆盖
        reasoningDefault: "on", // 每个智能体推理可见性覆盖
        fastModeDefault: false, // 每个智能体快速模式覆盖
        params: { cacheRetention: "none" }, // 按键覆盖匹配的 defaults.models params
        tts: {
          providers: {
            elevenlabs: { voiceId: "EXAVITQu4vr4xnSDxMaL" },
          },
        },
        skills: ["docs-search"], // 设置时替换 agents.defaults.skills
        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",
            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: []。
params：每个智能体流参数，会合并到 agents.defaults.models 中选择的模型条目。用于 agent 特定的覆盖，如 cacheRetention、temperature 或 maxTokens，无需复制整个模型目录。
tts：可选的每个智能体文本转语音覆盖。该块会深度合并到 messages.tts，因此将共享 provider 凭据和回退策略放在 messages.tts 中，此处只设置角色特定的值，如 provider、voice、model、style 或 auto 模式。
skills：可选的每个智能体技能允许列表。如果省略，该智能体继承 agents.defaults.skills（如果设置）；显式列表替换默认值而不是合并，[] 表示无技能。
thinkingDefault：可选的每个智能体默认思考级别（off | minimal | low | medium | high | xhigh | adaptive | max）。当没有每条消息或 session 覆盖时，覆盖此智能体的 agents.defaults.thinkingDefault。选定的 provider/model 配置文件控制哪些值有效；对于 Google Gemini，adaptive 保持 provider 拥有的动态思考（Gemini 3/3.1 上省略 thinkingLevel，Gemini 2.5 上使用 thinkingBudget: -1）。
reasoningDefault：可选的每个智能体默认推理可见性（on | off | stream）。当没有每条消息或 session 推理覆盖时，覆盖此智能体的 agents.defaults.reasoningDefault。
fastModeDefault：可选的每个智能体快速模式默认值（true | false）。当没有每条消息或 session 快速模式覆盖时应用。
models：可选的每个智能体模型目录/运行时覆盖，按完整的 provider/model ID 键控。使用 models["provider/model"].agentRuntime 进行每个智能体的运行时例外。
runtime：可选的每个智能体运行时描述符。使用 type: "acp" 和 runtime.acp 默认值（agent、backend、mode、cwd）当该智能体应默认使用 ACP harness session。
identity.avatar：工作区相对路径、http(s) URL 或 data: URI。
identity 从 emoji 派生 ackReaction 默认值，从 name/emoji 派生 mentionPatterns 默认值。
subagents.allowAgents：已配置智能体 ID 的允许列表，用于显式的 sessions_spawn.agentId 目标（["*"] = 任何已配置目标；默认：仅相同智能体）。当应允许自目标的 agentId 调用时，包括请求者 ID。其智能体配置已删除的过期条目会被 sessions_spawn 拒绝，并从 agents_list 中省略；运行 openclaw doctor --fix 清理它们，或添加最小的 agents.list[] 条目（如果该目标应在继承默认值的同时保持可生成）。
沙箱继承保护：如果请求者 session 是沙箱化的，sessions_spawn 拒绝会无沙箱运行的目标。
subagents.requireAgentId：为 true 时，阻止省略 agentId 的 sessions_spawn 调用（强制显式配置文件选择；默认：false）。

多智能体路由

在一个 Gateway 内运行多个隔离的智能体。参见多智能体。

json5

{
  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 }

确定性匹配顺序：

match.peer
match.guildId
match.teamId
match.accountId（精确，无 peer/guild/team）
match.accountId: "*"（渠道范围）
默认智能体

在每个层级内，第一个匹配的 bindings 条目胜出。

对于 type: "acp" 条目，OpenClaw 按精确对话标识（match.channel + 账号 + match.peer.id）解析，并且不使用上述路由绑定层级顺序。

每个智能体的访问配置文件

完全访问（无沙箱）

json5

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

只读工具 + 工作区

json5

{
  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"],
        },
      },
    ],
  },
}

无文件系统访问（仅聊天）

json5

{
  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

json5

{
  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 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    maintenance: {
      mode: "warn", // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      resetArchiveRetention: "30d", // duration 或 false
      maxDiskBytes: "500mb", // 可选硬预算
      highWaterBytes: "400mb", // 可选清理目标
    },
    threadBindings: {
      enabled: true,
      idleHours: 24, // 默认不活动自动失焦（小时）；`0` 禁用
      maxAgeHours: 0, // 默认硬最大年龄（小时）；`0` 禁用
    },
    mainKey: "main", // 遗留字段（运行时总是使用 "main"）
    agentToAgent: { maxPingPongTurns: 5 },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}

Session 字段详情

scope：群聊上下文中 session 的基础分组策略。
- per-sender（默认）：每个发送者在频道上下文中获得隔离的 session。
- global：频道上下文中的所有参与者共享一个 session（仅在意图共享上下文时使用）。
dmScope：如何分组私聊。
- main：所有私聊共享主 session。
- per-peer：按发送者 ID 跨渠道隔离。
- per-channel-peer：按渠道 + 发送者隔离（推荐用于多用户收件箱）。
- per-account-channel-peer：按账号 + 渠道 + 发送者隔离（推荐用于多账号）。
identityLinks：将规范 ID 映射到 provider 前缀的 peer，用于跨渠道 session 共享。Dock 命令（如 /dock_discord）使用同一映射将活动 session 的回复路由切换到另一个链接的渠道 peer；参见渠道对接。
reset：主重置策略。daily 在 atHour 本地时间重置；idle 在经过 idleMinutes 后重置。当同时配置时，无论哪个先到期胜出。每日重置新鲜度使用 session 行的 sessionStartedAt；空闲重置新鲜度使用 lastInteractionAt。后台/系统事件写入（如心跳、cron 唤醒、exec 通知和网关记账）可以更新 updatedAt，但不会保持每日/空闲 session 的新鲜度。
resetByType：按类型覆盖（direct、group、thread）。旧版 dm 被接受为 direct 的别名。
mainKey：遗留字段。运行时对于主私聊桶始终使用 "main"。
agentToAgent.maxPingPongTurns：智能体间交换期间的最大回复回退轮次（整数，范围：0-20，默认：5）。0 禁用 ping-pong 链。
sendPolicy：按 channel、chatType（direct|group|channel，旧版 dm 别名）、keyPrefix 或 rawKeyPrefix 匹配。第一个 deny 胜出。
maintenance：session 存储清理 + 保留控制。
- mode：warn 仅发出警告；enforce 应用清理。
- pruneAfter：过期条目的年龄截止（默认 30d）。
- maxEntries：sessions.json 中的最大条目数（默认 500）。运行时为生产规模的容量限制写入带有小高水位缓冲区的批量清理；openclaw sessions cleanup --enforce 立即应用上限。
- rotateBytes：已弃用且忽略；openclaw doctor --fix 会将其从旧配置中移除。
- resetArchiveRetention：*.reset.<timestamp> 转录存档的保留期。默认值为 pruneAfter；设为 false 禁用。
- maxDiskBytes：可选的 session 目录磁盘预算。在 warn 模式下记录警告；在 enforce 模式下首先移除最旧的 artifacts/sessions。
- highWaterBytes：预算清理后的可选目标。默认值为 maxDiskBytes 的 80%。
threadBindings：线程绑定 session 特性的全局默认值。
- enabled：主默认开关（provider 可覆盖；Discord 使用 channels.discord.threadBindings.enabled）
- idleHours：默认不活动自动失焦（小时）；0 禁用（provider 可覆盖）
- maxAgeHours：默认硬最大年龄（小时）；0 禁用（provider 可覆盖）
- spawnSessions：从 sessions_spawn 和 ACP 线程生成创建线程绑定工作 session 的默认门控。当线程绑定启用时默认为 true；provider/账号可覆盖。
- defaultSpawnContext：线程绑定生成的默认原生子智能体上下文（"fork" 或 "isolated"）。默认为 "fork"。

消息

json5

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

回复前缀

每个渠道/账号覆盖：channels.<channel>.responsePrefix、channels.<channel>.accounts.<id>.responsePrefix。

解析（最具体胜出）：账号 → 渠道 → 全局。"" 禁用并停止级联。"auto" 推导 [{identity.name}]。

模板变量：

变量	描述	示例
`{model}`	简短模型名	`claude-opus-4-6`
`{modelFull}`	完整模型标识符	`anthropic/claude-opus-4-6`
`{provider}`	Provider 名称	`anthropic`
`{thinkingLevel}`	当前思考级别	`high`、`low`、`off`
`{identity.name}`	智能体身份名称	（与 `"auto"` 相同）

变量不区分大小写。{think} 是 {thinkingLevel} 的别名。

Ack 反应

默认使用活动智能体的 identity.emoji，否则为 "👀"。设为 "" 禁用。
每个渠道覆盖：channels.<channel>.ackReaction、channels.<channel>.accounts.<id>.ackReaction。
解析顺序：账号 → 渠道 → messages.ackReaction → 身份回退。
范围：group-mentions（默认）、group-all、direct、all。
removeAckAfterReply：在支持反应的渠道（如 Slack、Discord、Telegram、WhatsApp、iMessage）上回复后移除 ack。
messages.statusReactions.enabled：在 Slack、Discord、Telegram 和 WhatsApp 上启用生命周期状态反应。在 Slack 和 Discord 上，未设置时会在 ack 反应激活时保持状态反应启用。在 Telegram 和 WhatsApp 上，显式设置为 true 以启用生命周期状态反应。
messages.statusReactions.emojis：覆盖生命周期表情键： queued、thinking、compacting、tool、coding、web、deploy、build、 concierge、done、error、stallSoft 和 stallHard。 Telegram 只允许固定的反应集合，所以不支持的配置表情会回退到该聊天最近的支持状态变体。

入站防抖（debounce）

将来自同一发送者的快速纯文本消息批处理为单个智能体轮次。媒体/附件立即刷新。控制命令绕过防抖。

TTS（文本转语音）

json5

{
  messages: {
    tts: {
      auto: "always", // off | always | inbound | tagged
      mode: "final", // final | all
      provider: "elevenlabs",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: { enabled: true },
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
      providers: {
        elevenlabs: {
          apiKey: "elevenlabs_api_key",
          baseUrl: "https://api.elevenlabs.io",
          voiceId: "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: {
          voice: "en-US-AvaMultilingualNeural",
          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",
          voice: "alloy",
        },
      },
    },
  },
}

auto 控制默认自动 TTS 模式：off、always、inbound 或 tagged。/tts on|off 可覆盖本地偏好，/tts status 显示有效状态。
summaryModel 覆盖 agents.defaults.model.primary 用于自动摘要。
modelOverrides 默认启用；modelOverrides.allowProvider 默认值为 false（选择加入）。
API 密钥回退到 ELEVENLABS_API_KEY/XI_API_KEY 和 OPENAI_API_KEY。
捆绑的语音 provider 是插件拥有的。如果设置了 plugins.allow，请包括要使用的每个 TTS provider 插件，例如 microsoft 用于 Edge TTS。旧版 edge provider 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 模式的默认值（macOS/iOS/Android）。

json5

{
  talk: {
    provider: "elevenlabs",
    providers: {
      elevenlabs: {
        voiceId: "elevenlabs_voice_id",
        voiceAliases: {
          Clawd: "EXAVITQu4vr4xnSDxMaL",
          Roger: "CwhRBWXzGAHq8TQ4Fs17",
        },
        modelId: "eleven_v3",
        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",
          voice: "cedar",
        },
      },
      instructions: "Speak warmly and keep answers brief.",
      mode: "realtime",
      transport: "webrtc",
      brain: "agent-consult",
    },
  },
}

talk.provider 当配置了多个 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。
providers.*.apiKey 接受纯文本字符串或 SecretRef 对象。
ELEVENLABS_API_KEY 回退仅在未配置 Talk API 键时应用。
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 智能体运行的思考级别。保持未设置以保留正常的 session/模型行为。
consultFastMode 为 Control UI Talk 实时咨询设置一次性快速模式覆盖，而不更改 session 的正常快速模式设置。
speechLocale 设置 iOS/macOS Talk 语音识别使用的 BCP 47 区域设置 ID。保持未设置以使用设备默认值。
silenceTimeoutMs 控制 Talk 模式在用户静音后等待多长时间才发送转录。保持未设置以保持平台默认暂停窗口（macOS 和 Android 上为 700 ms，iOS 上为 900 ms）。
realtime.instructions 将 provider 面向的系统指令追加到 OpenClaw 的内置实时提示中，以便无需丢失默认的 openclaw_agent_consult 指导即可配置语音风格。

常见问题

多智能体路由中的 bindings 匹配顺序是怎样的？

匹配顺序按确定性层级执行：先精确 peer（match.peer），然后 guildId、teamId、accountId（精确）、accountId: "*"（渠道级），最后默认智能体。在每个层级内，第一个匹配的 bindings 条目胜出。对于 type: "acp" 条目，按精确对话标识匹配，不使用路由层级。

智能体之间的 `sessions_spawn` 怎么限制可以调用的目标智能体？

通过 subagents.allowAgents 设置允许列表。["*"] 允许任何已配置的目标；省略则只允许同智能体。如果请求者 session 已沙箱化，sessions_spawn 会拒绝无沙箱运行的目标。过期的条目会被自动拒绝，用 openclaw doctor --fix 清理。

`agents.defaults.skills` 和 `agents.list[].skills` 怎么合并？

它们不合并。如果 agents.list[].skills 被省略，则继承 agents.defaults.skills（如果设置）。如果显式设置，无论是空列表 [] 还是非空列表，该智能体的技能就是那个最终集合，不会与默认值合并。

OpenClaw Agent 配置：默认值、多智能体路由、会话与消息 ​

智能体默认值 ​

agents.defaults.workspace ​

agents.defaults.repoRoot ​

agents.defaults.skills ​

agents.defaults.skipBootstrap ​

agents.defaults.skipOptionalBootstrapFiles ​

agents.defaults.contextInjection ​

agents.defaults.bootstrapMaxChars ​

agents.defaults.bootstrapTotalMaxChars ​

每个智能体的引导配置覆盖 ​

agents.defaults.bootstrapPromptTruncationWarning ​

上下文预算所有权映射 ​

agents.defaults.startupContext ​

agents.defaults.contextLimits ​

agents.list[].contextLimits ​

skills.limits.maxSkillsPromptChars ​

agents.list[].skillsLimits.maxSkillsPromptChars ​

agents.defaults.imageMaxDimensionPx ​

agents.defaults.userTimezone ​

agents.defaults.timeFormat ​

agents.defaults.model ​

运行时策略 ​

agents.defaults.cliBackends ​

agents.defaults.systemPromptOverride ​

agents.defaults.promptOverlays ​

agents.defaults.heartbeat ​

agents.defaults.compaction ​

agents.defaults.runRetries ​

agents.defaults.contextPruning ​

块流式 ​

正在输入指示器 ​

agents.defaults.sandbox ​

agents.list（每个智能体覆盖） ​

多智能体路由 ​

绑定匹配字段 ​

每个智能体的访问配置文件 ​

Session ​

消息 ​

回复前缀 ​

Ack 反应 ​

入站防抖（debounce） ​

TTS（文本转语音） ​

Talk ​

相关 ​

常见问题 ​

多智能体路由中的 bindings 匹配顺序是怎样的？ ​

智能体之间的 sessions_spawn 怎么限制可以调用的目标智能体？ ​

agents.defaults.skills 和 agents.list[].skills 怎么合并？ ​

OpenClaw Agent 配置：默认值、多智能体路由、会话与消息

智能体默认值

`agents.defaults.workspace`

`agents.defaults.repoRoot`

`agents.defaults.skills`

`agents.defaults.skipBootstrap`

`agents.defaults.skipOptionalBootstrapFiles`

`agents.defaults.contextInjection`

`agents.defaults.bootstrapMaxChars`

`agents.defaults.bootstrapTotalMaxChars`

每个智能体的引导配置覆盖

`agents.defaults.bootstrapPromptTruncationWarning`

上下文预算所有权映射

`agents.defaults.startupContext`

`agents.defaults.contextLimits`

`agents.list[].contextLimits`

`skills.limits.maxSkillsPromptChars`

`agents.list[].skillsLimits.maxSkillsPromptChars`

`agents.defaults.imageMaxDimensionPx`

`agents.defaults.userTimezone`

`agents.defaults.timeFormat`

`agents.defaults.model`

运行时策略

`agents.defaults.cliBackends`

`agents.defaults.systemPromptOverride`

`agents.defaults.promptOverlays`

`agents.defaults.heartbeat`

`agents.defaults.compaction`

`agents.defaults.runRetries`

`agents.defaults.contextPruning`

块流式

正在输入指示器

`agents.defaults.sandbox`

`agents.list`（每个智能体覆盖）

多智能体路由

绑定匹配字段

每个智能体的访问配置文件

Session

消息

回复前缀

Ack 反应

入站防抖（debounce）

TTS（文本转语音）

Talk

相关

常见问题

多智能体路由中的 bindings 匹配顺序是怎样的？

智能体之间的 `sessions_spawn` 怎么限制可以调用的目标智能体？

`agents.defaults.skills` 和 `agents.list[].skills` 怎么合并？