--- read_when: - 调整智能体默认设置（模型、思考、工作区、Heartbeat、媒体、Skills） - 配置多智能体路由和绑定 - 调整会话、消息投递和 Talk 模式行为 summary: 智能体默认设置、多 Agent 路由、会话、消息和 Talk 配置 title: 配置 — 智能体 x-i18n: generated_at: "2026-05-12T23:30:34Z" model: gpt-5.5 provider: openai source_hash: 08ddc1b36f4b9408ebaa5f071693b1c1333cedc9b00f75df93f12e73081e1033 source_path: gateway/config-agents.md workflow: 16 --- 智能体范围的配置键位于 `agents.*`、`multiAgent.*`、`session.*`、 `messages.*` 和 `talk.*` 下。对于渠道、工具、Gateway 网关运行时和其他 顶层键，请参阅 [配置参考](/zh-CN/gateway/configuration-reference)。 ## 智能体默认值 ### `agents.defaults.workspace` 默认值：`~/.openclaw/workspace`。 ```json5 { agents: { defaults: { workspace: "~/.openclaw/workspace" } }, } ``` ### `agents.defaults.repoRoot` 可选的仓库根目录，会显示在系统提示词的 Runtime 行中。如果未设置，OpenClaw 会从工作区开始向上遍历并自动检测。 ```json5 { agents: { defaults: { repoRoot: "~/Projects/openclaw" } }, } ``` ### `agents.defaults.skills` 可选的默认技能允许列表，用于未设置 `agents.list[].skills` 的智能体。 ```json5 { 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`，表示默认不限制技能。 - 省略 `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` 跳过创建选定的可选工作区文件，同时仍会写入必需的引导文件。有效值：`SOUL.md`、`USER.md`、`HEARTBEAT.md` 和 `IDENTITY.md`。 ```json5 { agents: { defaults: { skipOptionalBootstrapFiles: ["SOUL.md", "USER.md"], }, }, } ``` ### `agents.defaults.contextInjection` 控制何时将工作区引导文件注入系统提示词。默认值：`"always"`。 - `"continuation-skip"`：安全的延续轮次（已完成的助手响应之后）会跳过重新注入工作区引导，从而减少提示词大小。Heartbeat 运行和压缩后的重试仍会重建上下文。 - `"never"`：在每个轮次都禁用工作区引导和上下文文件注入。仅对完全拥有自身提示词生命周期的智能体使用此选项（自定义上下文引擎、会构建自身上下文的原生运行时，或专门的无引导工作流）。Heartbeat 和压缩恢复轮次也会跳过注入。 ```json5 { agents: { defaults: { contextInjection: "continuation-skip" } }, } ``` ### `agents.defaults.bootstrapMaxChars` 截断前每个工作区引导文件的最大字符数。默认值：`12000`。 ```json5 { agents: { defaults: { bootstrapMaxChars: 12000 } }, } ``` ### `agents.defaults.bootstrapTotalMaxChars` 跨所有工作区引导文件注入的最大总字符数。默认值：`60000`。 ```json5 { agents: { defaults: { bootstrapTotalMaxChars: 60000 } }, } ``` ### `agents.defaults.bootstrapPromptTruncationWarning` 控制引导上下文被截断时，智能体可见的系统提示词通知。 默认值：`"once"`。 - `"off"`：从不向系统提示词注入截断通知文本。 - `"once"`：对每个唯一截断签名注入一次简洁通知（推荐）。 - `"always"`：当存在截断时，在每次运行都注入简洁通知。 详细的原始/注入计数和配置调优字段会保留在诊断信息中， 例如上下文/状态报告和日志；常规 WebChat 用户/运行时上下文只会 获得简洁的恢复通知。 ```json5 { agents: { defaults: { bootstrapPromptTruncationWarning: "once" } }, // 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[].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` 在调用提供商之前，转录/工具图片块中图片最长边的最大像素尺寸。 默认值：`1200`。 较低的值通常会减少大量截图运行中的视觉 token 用量和请求负载大小。 较高的值会保留更多视觉细节。 ```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" }, // 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: 3, }, }, } ``` - `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - 字符串形式只设置主模型。 - 对象形式会设置主模型和有序故障转移模型。 - `imageModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - 由 `image` 工具路径用作它的视觉模型配置。 - 当选定/默认模型不能接受图像输入时，也会用作回退路由。 - 优先使用显式 `provider/model` 引用。为兼容性也接受裸 ID；如果裸 ID 唯一匹配 `models.providers.*.models` 中已配置的具备图像能力的条目，OpenClaw 会将它限定到该提供商。已配置匹配项存在歧义时，需要显式提供商前缀。 - `imageGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。 - 由共享图像生成能力以及任何未来生成图像的工具/插件表面使用。 - 典型值：用于原生 Gemini 图像生成的 `google/gemini-3.1-flash-image-preview`，用于 fal 的 `fal/fal-ai/flux/dev`，用于 OpenAI Images 的 `openai/gpt-image-2`，或用于透明背景 OpenAI PNG/WebP 输出的 `openai/gpt-image-1.5`。 - 如果你直接选择提供商/模型，也要配置匹配的提供商认证（例如 `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 API-key 或 Codex OAuth 访问的 `openai/gpt-5.5`）。如果你省略提供商，OpenClaw 会先尝试别名，然后尝试该精确模型 ID 的唯一已配置提供商匹配，最后才回退到已配置的默认提供商（已弃用的兼容行为，因此优先使用显式 `provider/model`）。如果该提供商不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是显示过期的已移除提供商默认值。 - `models`：为 `/model` 配置的模型目录和允许列表。每个条目都可以包含 `alias`（快捷方式）和 `params`（提供商特定，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`、`responsesServerCompaction`、`responsesCompactThreshold`、`chat_template_kwargs`、`extra_body`/`extraBody`）。 - 使用 `"openai-codex/*": {}` 或 `"vllm/*": {}` 这类 `provider/*` 条目，可展示所选提供商的所有已发现模型，而无需手动列出每个模型 ID。 - 安全编辑：使用 `openclaw config set agents.defaults.models '' --strict-json --merge` 添加条目。除非传递 `--replace`，否则 `config set` 会拒绝会移除现有允许列表条目的替换。 - 按提供商配置/新手引导流程会将所选提供商模型合并到此映射中，并保留已配置的无关提供商。 - 对于直接 OpenAI Responses 模型，会自动启用服务器端压缩。使用 `params.responsesServerCompaction: false` 停止注入 `context_management`，或使用 `params.responsesCompactThreshold` 覆盖阈值。参阅 [OpenAI 服务器端压缩](/zh-CN/providers/openai#server-side-compaction-responses-api)。 - `params`：应用于所有模型的全局默认提供商参数。在 `agents.defaults.params` 设置（例如 `{ cacheRetention: "long" }`）。 - `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后 `agents.list[].params`（匹配的智能体 ID）按键覆盖。详见 [提示词缓存](/zh-CN/reference/prompt-caching)。 - `params.extra_body`/`params.extraBody`：高级透传 JSON，会合并到 OpenAI 兼容代理的 `api: "openai-completions"` 请求体中。如果它与生成的请求键冲突，额外 body 优先；非原生 completions 路由随后仍会剥离 OpenAI 专用的 `store`。 - `params.chat_template_kwargs`：vLLM/OpenAI 兼容的聊天模板参数，会合并到顶层 `api: "openai-completions"` 请求体中。对于关闭 thinking 的 `vllm/nemotron-3-*`，内置 vLLM 插件会自动发送 `enable_thinking: false` 和 `force_nonempty_content: true`；显式 `chat_template_kwargs` 会覆盖生成的默认值，而 `extra_body.chat_template_kwargs` 仍拥有最终优先级。对于 vLLM Qwen thinking 控制，请在该模型条目上将 `params.qwenThinkingFormat` 设置为 `"chat-template"` 或 `"top-level"`。 - `compat.thinkingFormat`：OpenAI 兼容的 thinking 载荷样式。对于 Qwen 风格的顶层 `enable_thinking` 使用 `"qwen"`；对于支持请求级聊天模板 kwargs 的 Qwen 系列后端（如 vLLM），使用 `"qwen-chat-template"` 表示 `chat_template_kwargs.enable_thinking`。OpenClaw 会将禁用 thinking 映射为 `false`，将启用 thinking 映射为 `true`。 - `compat.supportedReasoningEfforts`：按模型配置的 OpenAI 兼容 reasoning effort 列表。对于真正接受它的自定义端点，请包含 `"xhigh"`；随后 OpenClaw 会在命令菜单、Gateway 网关会话行、会话补丁验证、智能体 CLI 验证和该已配置提供商/模型的 `llm-task` 验证中公开 `/think xhigh`。当后端需要规范级别对应的提供商特定值时，使用 `compat.reasoningEffortMap`。 - `params.preserveThinking`：仅限 Z.AI 的保留 thinking 选择加入项。启用且 thinking 开启时，OpenClaw 会发送 `thinking.clear_thinking: false` 并重放先前的 `reasoning_content`；参阅 [Z.AI thinking 和保留 thinking](/zh-CN/providers/zai#thinking-and-preserved-thinking)。 - `localService`：可选的提供商级别进程管理器，用于本地/自托管模型服务器。当选定模型属于该提供商时，OpenClaw 会探测 `healthUrl`（或 `baseUrl + "/models"`），如果端点离线，则使用 `args` 启动 `command`，最多等待 `readyTimeoutMs`，然后发送模型请求。`command` 必须是绝对路径。`idleStopMs: 0` 会保持进程存活直到 OpenClaw 退出；正值会在该毫秒数的空闲时间后停止由 OpenClaw 生成的进程。参阅 [本地模型服务](/zh-CN/gateway/local-model-services)。 - 运行时策略属于提供商或模型，不属于 `agents.defaults`。使用 `models.providers..agentRuntime` 设置提供商范围规则，或使用 `agents.defaults.models["provider/model"].agentRuntime` / `agents.list[].models["provider/model"].agentRuntime` 设置模型特定规则。官方 OpenAI provider 上的 OpenAI 智能体模型默认选择 Codex。 - 变更这些字段的配置写入器（例如 `/models set`、`/models set-image` 和回退添加/移除命令）会保存规范对象形式，并在可能时保留现有回退列表。 - `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话仍会串行化）。默认值：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" }, }, }, }, }, } ``` - `id`：`"auto"`、`"pi"`、已注册的插件 harness ID，或受支持的 CLI 后端别名。内置 Codex 插件会注册 `codex`；内置 Anthropic 插件提供 `claude-cli` CLI 后端。 - `id: "auto"` 允许已注册的插件 harness 认领受支持的轮次，并在没有 harness 匹配时使用 PI。显式插件运行时（如 `id: "codex"`）要求该 harness 存在，并在不可用或失败时封闭失败。 - 整个智能体级别的运行时键属于旧版。`agents.defaults.agentRuntime`、`agents.list[].agentRuntime`、会话运行时固定值和 `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` 模型引用为兼容性仍可工作，但新配置应保持提供商/模型选择的规范性，并将执行后端放入提供商/模型运行时策略中。 - 这只控制文本智能体轮次执行。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用它们的提供商/模型设置。 **内置别名简写**（仅在模型位于 `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` | 你配置的别名始终优先于默认值。 除非你设置 `--thinking off` 或自行定义 `agents.defaults.models["zai/"].params.thinking`，否则 Z.AI GLM-4.x 模型会自动启用思考模式。 Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `agents.defaults.models["zai/"].params.tool_stream` 设置为 `false` 可将其禁用。 Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `adaptive` 思考。 ### `agents.defaults.cliBackends` 用于纯文本回退运行（无工具调用）的可选 CLI 后端。在 API 提供商失败时，可用作备份。 ```json5 { agents: { defaults: { cliBackends: { "codex-cli": { command: "/opt/homebrew/bin/codex", }, "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 转录尾部恢复安全失效的会话。凭证配置文件或凭证纪元变更仍然绝不会原始重播种。 ### `agents.defaults.systemPromptOverride` 用固定字符串替换整个由 OpenClaw 组装的系统提示。可在默认级别（`agents.defaults.systemPromptOverride`）或按智能体（`agents.list[].systemPromptOverride`）设置。按智能体设置的值优先；空值或仅含空白字符的值会被忽略。适用于受控的提示实验。 ```json5 { agents: { defaults: { systemPromptOverride: "You are a helpful assistant.", }, }, } ``` ### `agents.defaults.promptOverlays` 按模型族应用的、与提供商无关的提示叠加。GPT-5 系列模型 ID 会在各提供商之间接收共享行为契约；`personality` 仅控制友好的交互风格层。 ```json5 { agents: { defaults: { promptOverlays: { gpt5: { personality: "friendly", // friendly | on | off }, }, }, }, } ``` - `"friendly"`（默认）和 `"on"` 启用友好的交互风格层。 - `"off"` 仅禁用友好层；带标签的 GPT-5 行为契约仍会启用。 - 未设置此共享设置时，仍会读取旧版 `plugins.entries.openai.config.personality`。 ### `agents.defaults.heartbeat` 周期性 Heartbeat 运行。 ```json5 { 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 密钥认证）或 `1h`（OAuth 认证）。设置为 `0m` 可禁用。 - `includeSystemPromptSection`：为 false 时，会从系统提示中省略 Heartbeat 部分，并跳过将 `HEARTBEAT.md` 注入启动上下文。默认值：`true`。 - `suppressToolErrorWarnings`：为 true 时，会在 Heartbeat 运行期间抑制工具错误警告负载。 - `timeoutSeconds`：Heartbeat 智能体轮次在中止前允许的最长秒数。留空则使用 `agents.defaults.timeoutSeconds`。 - `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` ```json5 { agents: { defaults: { compaction: { mode: "safeguard", // default | safeguard provider: "my-provider", // id of a registered compaction provider plugin (optional) timeoutSeconds: 900, reserveTokensFloor: 24000, keepRecentTokens: 50000, 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 Pi tool-loop pressure check postCompactionSections: ["Session Startup", "Red Lines"], // [] disables 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, // send brief notices when compaction starts and completes (default: false) memoryFlush: { enabled: true, model: "ollama/qwen3:8b", // optional memory-flush-only model override softThresholdTokens: 6000, 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`（用于长历史的分块摘要）。参见[压缩](/zh-CN/concepts/compaction)。 - `provider`：已注册压缩提供商插件的 ID。设置后会调用该提供商的 `summarize()`，而不是内置 LLM 摘要。失败时会回退到内置方式。设置提供商会强制 `mode: "safeguard"`。参见[压缩](/zh-CN/concepts/compaction)。 - `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` 覆盖。当主会话应保留一个模型、但压缩摘要应在另一个模型上运行时使用此项；未设置时，压缩使用会话的主模型。 - `maxActiveTranscriptBytes`：可选字节阈值（`number` 或类似 `"20mb"` 的字符串），当活动 JSONL 增长超过该阈值时，会在运行前触发常规本地压缩。需要 `truncateAfterCompaction`，以便成功压缩后可轮转到更小的后继转录。未设置或为 `0` 时禁用。 - `notifyUser`：为 `true` 时，会在压缩开始和完成时向用户发送简短通知（例如，“正在压缩上下文...”和“压缩完成”）。默认禁用以保持压缩静默。 - `memoryFlush`：自动压缩前用于存储持久记忆的静默智能体轮次。当此类维护轮次应停留在本地模型上时，将 `model` 设置为精确的提供商/模型，例如 `ollama/qwen3:8b`；此覆盖不会继承活动会话回退链。工作区为只读时跳过。 ### `agents.defaults.runRetries` 嵌入式 Pi 运行器的外层运行循环重试迭代边界，用于防止故障恢复期间出现无限执行循环。请注意，此设置目前仅适用于嵌入式智能体运行时，不适用于 ACP 或 CLI 运行时。 ```json5 { 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` 在发送给 LLM 之前，从内存上下文中剪除**旧工具结果**。**不会**修改磁盘上的会话历史。 ```json5 { agents: { defaults: { contextPruning: { mode: "cache-ttl", // off | cache-ttl ttl: "1h", // duration (ms/s/m/h), default unit: minutes 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"] }, }, }, }, } ``` - `mode: "cache-ttl"` 启用裁剪过程。 - `ttl` 控制裁剪多久后可以再次运行（从上一次缓存触达后开始算）。 - 裁剪会先软裁剪过大的工具结果，然后在需要时硬清除更旧的工具结果。 **软裁剪** 会保留开头 + 结尾，并在中间插入 `...`。 **硬清除** 会用占位符替换整个工具结果。 注意事项： - 图片块永远不会被裁剪/清除。 - 比例基于字符数（近似值），不是精确的 token 计数。 - 如果助手消息少于 `keepLastAssistants`，会跳过裁剪。 行为详情见 [会话裁剪](/zh-CN/concepts/session-pruning)。 ### 分块流式传输 ```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 (use minMs/maxMs) }, }, } ``` - 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才能启用分块回复。 - 渠道覆盖：`channels..blockStreamingCoalesce`（以及按账号的变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。 - `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500ms。按智能体覆盖：`agents.list[].humanDelay`。 行为和分块详情见 [流式传输](/zh-CN/concepts/streaming)。 ### 输入状态指示 ```json5 { agents: { defaults: { typingMode: "instant", // never | instant | thinking | message typingIntervalSeconds: 6, }, }, } ``` - 默认值：私聊/提及时为 `instant`，未提及的群聊为 `message`。 - 按会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。 见 [输入状态指示](/zh-CN/concepts/typing-indicators)。 ### `agents.defaults.sandbox` 嵌入式智能体的可选沙箱隔离。完整指南见 [沙箱隔离](/zh-CN/gateway/sandboxing)。 ```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 / 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"], }, }, }, } ``` **后端：** - `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 在运行时具现化为临时文件的内联内容或 SecretRefs - `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略开关 **SSH 凭证优先级：** - `identityData` 优先于 `identityFile` - `certificateData` 优先于 `certificateFile` - `knownHostsData` 优先于 `knownHostsFile` - 基于 SecretRef 的 `*Data` 值会在沙箱会话启动前，从活动 secrets 运行时快照中解析 **SSH 后端行为：** - 创建或重新创建后，只初始化一次远程工作区 - 随后保持远程 SSH 工作区为权威副本 - 通过 SSH 路由 `exec`、文件工具和媒体路径 - 不会自动把远程更改同步回主机 - 不支持沙箱浏览器容器 **工作区访问：** - `none`：`~/.openclaw/sandboxes` 下按作用域的沙箱工作区 - `ro`：沙箱工作区位于 `/workspace`，智能体工作区以只读方式挂载到 `/agent` - `rw`：智能体工作区以读写方式挂载到 `/workspace` **作用域：** - `session`：每个会话一个容器 + 工作区 - `agent`：每个智能体一个容器 + 工作区（默认） - `shared`：共享容器和工作区（无跨会话隔离） **OpenShell 插件配置：** ```json5 { plugins: { entries: { openshell: { enabled: true, config: { mode: "mirror", // mirror | remote 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, }, }, }, }, } ``` **OpenShell 模式：** - `mirror`：执行前从本地初始化远程，执行后同步回来；本地工作区保持为权威副本 - `remote`：创建沙箱时只初始化一次远程，随后保持远程工作区为权威副本 在 `remote` 模式下，在主机本地、OpenClaw 之外进行的编辑不会在初始化步骤之后自动同步到沙箱中。 传输方式是通过 SSH 进入 OpenShell 沙箱，但插件负责沙箱生命周期和可选的镜像同步。 **`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出站访问、可写的 root 文件系统、root 用户。 **容器默认使用 `network: "none"`**；如果智能体需要出站访问，请设置为 `"bridge"`（或自定义 bridge 网络）。 `"host"` 会被阻止。`"container:"` 默认会被阻止，除非你显式设置 `sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急例外）。 **入站附件** 会暂存到活动工作区中的 `media/inbound/*`。 **`docker.binds`** 会挂载额外的主机目录；全局和按智能体的绑定会合并。 **沙箱隔离浏览器**（`sandbox.browser.enabled`）：容器中的 Chromium + CDP。noVNC URL 会注入系统提示词。不需要在 `openclaw.json` 中启用 `browser.enabled`。 noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会生成短期有效的令牌 URL（而不是在共享 URL 中暴露密码）。 - `allowHostControl: false`（默认）会阻止沙箱隔离会话定位到主机浏览器。 - `network` 默认为 `openclaw-sandbox-browser`（专用 bridge 网络）。只有在你明确需要全局 bridge 连通性时，才设置为 `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=` - `--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=` 更改；设置 `0` 可使用 Chromium 的 默认进程限制。 - 当 `noSandbox` 启用时，此外还会加上 `--no-sandbox`。 - 默认值是容器镜像基线；要更改容器默认值，请使用带自定义入口点的自定义浏览器镜像。 浏览器沙箱隔离和 `sandbox.docker.binds` 仅适用于 Docker。 构建镜像（从源码检出）： ```bash scripts/sandbox-setup.sh # main sandbox image scripts/sandbox-browser-setup.sh # optional browser image ``` 对于没有源码检出的 npm 安装，内联 `docker build` 命令见 [沙箱隔离 § 镜像和设置](/zh-CN/gateway/sandboxing#images-and-setup)。 ### `agents.list`（按智能体覆盖） 使用 `agents.list[].tts` 为智能体指定自己的 TTS 提供商、声音、模型、风格或自动 TTS 模式。智能体块会深度合并到全局 `messages.tts` 之上，因此共享凭证可以保留在一个位置，而各个智能体只覆盖它们需要的声音或提供商字段。当前智能体的覆盖配置会应用于自动语音回复、`/tts audio`、`/tts status` 和 `tts` 智能体工具。请参阅 [文本转语音](/zh-CN/tools/tts#per-agent-voice-overrides)，了解提供商示例和优先级。 ```json5 { 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 } 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: { voiceId: "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", 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` 中选定的模型条目之上。用它为智能体设置特定覆盖，例如 `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`：可选的每智能体默认快速模式（`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` 会派生默认值：从 `emoji` 派生 `ackReaction`，从 `name`/`emoji` 派生 `mentionPatterns`。 - `subagents.allowAgents`：显式 `sessions_spawn.agentId` 目标的智能体 ID 允许列表（`["*"]` = 任意；默认：仅相同智能体）。当应允许自目标 `agentId` 调用时，请包含请求者 ID。 - 沙箱继承保护：如果请求者会话处于沙箱隔离中，`sessions_spawn` 会拒绝将以非沙箱方式运行的目标。 - `subagents.requireAgentId`：为 true 时，阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置文件；默认：false）。 --- ## 多智能体路由 在一个 Gateway 网关中运行多个隔离的智能体。请参阅 [Multi-Agent](/zh-CN/concepts/multi-agent)。 ```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 }` **确定性的匹配顺序：** 1. `match.peer` 2. `match.guildId` 3. `match.teamId` 4. `match.accountId`（精确匹配，无 peer/guild/team） 5. `match.accountId: "*"`（整个渠道） 6. 默认智能体 在每一层级中，第一个匹配的 `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", ], }, }, ], }, } ``` 有关优先级详情，请参阅 [多 Agent 沙盒和工具](/zh-CN/tools/multi-agent-sandbox-tools)。 --- ## 会话 ```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 or false maxDiskBytes: "500mb", // optional hard budget highWaterBytes: "400mb", // optional cleanup target }, 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", }, }, } ``` - **`scope`**：群聊上下文的基础会话分组策略。 - `per-sender`（默认）：每个发送者在渠道上下文中获得一个隔离会话。 - `global`：渠道上下文中的所有参与者共享单个会话（仅在有意共享上下文时使用）。 - **`dmScope`**：私信的分组方式。 - `main`：所有私信共享主会话。 - `per-peer`：跨渠道按发送者 ID 隔离。 - `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。 - `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离（推荐用于多账号）。 - **`identityLinks`**：将规范 ID 映射到带提供商前缀的对等方，用于跨渠道会话共享。`/dock_discord` 等 Dock 命令使用同一映射，把活动会话的回复路由切换到另一个已链接的渠道对等方；参见[渠道停靠](/zh-CN/concepts/channel-docking)。 - **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。两者都配置时，先到期者生效。每日重置的新鲜度使用会话行的 `sessionStartedAt`；空闲重置的新鲜度使用 `lastInteractionAt`。heartbeat、cron 唤醒、exec 通知和 Gateway 网关记账等后台/系统事件写入可以更新 `updatedAt`，但不会让每日/空闲会话保持新鲜。 - **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 可作为 `direct` 的别名接受。 - **`mainKey`**：旧版字段。运行时始终使用 `"main"` 作为主直接聊天存储桶。 - **`agentToAgent.maxPingPongTurns`**：智能体到智能体交换期间，智能体之间最大往返回复轮次（整数，范围：`0`-`20`，默认：`5`）。`0` 会禁用往返链式回复。 - **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个拒绝规则生效。 - **`maintenance`**：会话存储清理 + 保留控制。 - `mode`：`warn` 仅发出警告；`enforce` 执行清理。 - `pruneAfter`：陈旧条目的年龄截止点（默认 `30d`）。 - `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。运行时会为生产规模上限使用小型高水位缓冲区批量写入清理；`openclaw sessions cleanup --enforce` 会立即应用上限。 - `rotateBytes`：已弃用并被忽略；`openclaw doctor --fix` 会从旧配置中移除它。 - `resetArchiveRetention`：`*.reset.` transcript 归档的保留期。默认使用 `pruneAfter`；设为 `false` 可禁用。 - `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下记录警告；在 `enforce` 模式下会优先移除最旧的工件/会话。 - `highWaterBytes`：预算清理后的可选目标值。默认是 `maxDiskBytes` 的 `80%`。 - **`threadBindings`**：线程绑定会话功能的全局默认值。 - `enabled`：主默认开关（提供商可以覆盖；Discord 使用 `channels.discord.threadBindings.enabled`） - `idleHours`：默认无活动自动取消聚焦时间，单位为小时（`0` 禁用；提供商可以覆盖） - `maxAgeHours`：默认硬性最大年龄，单位为小时（`0` 禁用；提供商可以覆盖） - `spawnSessions`：从 `sessions_spawn` 和 ACP 线程 spawn 创建线程绑定工作会话的默认门控。启用线程绑定时默认为 `true`；提供商/账号可以覆盖。 - `defaultSpawnContext`：线程绑定 spawn 的默认原生子智能体上下文（`"fork"` 或 `"isolated"`）。默认值为 `"fork"`。 --- ## 消息 ```json5 { messages: { responsePrefix: "🦞", // or "auto" ackReaction: "👀", ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all removeAckAfterReply: false, queue: { mode: "steer", // steer | queue (legacy one-at-a-time) | followup | collect | steer-backlog | steer+backlog | interrupt debounceMs: 500, cap: 20, drop: "summarize", // old | new | summarize byChannel: { whatsapp: "steer", telegram: "steer", }, }, inbound: { debounceMs: 2000, // 0 disables byChannel: { whatsapp: 5000, slack: 1500, }, }, }, } ``` ### 响应前缀 按渠道/账号覆盖：`channels..responsePrefix`、`channels..accounts..responsePrefix`。 解析（最具体者优先）：账号 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 派生为 `[{identity.name}]`。 **模板变量：** | 变量 | 描述 | 示例 | | ----------------- | ---------------- | --------------------------- | | `{model}` | 简短模型名称 | `claude-opus-4-6` | | `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` | | `{provider}` | 提供商名称 | `anthropic` | | `{thinkingLevel}` | 当前思考级别 | `high`, `low`, `off` | | `{identity.name}` | 智能体身份名称 |（与 `"auto"` 相同） | 变量不区分大小写。`{think}` 是 `{thinkingLevel}` 的别名。 ### 确认反应 - 默认使用活动智能体的 `identity.emoji`，否则使用 `"👀"`。设置为 `""` 可禁用。 - 按渠道覆盖：`channels..ackReaction`、`channels..accounts..ackReaction`。 - 解析顺序：账号 → 渠道 → `messages.ackReaction` → 身份回退值。 - 范围：`group-mentions`（默认）、`group-all`、`direct`、`all`。 - `removeAckAfterReply`：在 Slack、Discord、Telegram、WhatsApp 和 iMessage 等支持反应的渠道上，回复后移除确认反应。 - `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态反应。 在 Slack 和 Discord 上，未设置时，如果确认反应处于活动状态，则保持启用状态反应。 在 Telegram 上，需要显式设为 `true` 才能启用生命周期状态反应。 ### 入站防抖 将同一发送者快速发送的纯文本消息批处理为单个智能体轮次。媒体/附件会立即刷新。控制命令会绕过防抖。 ### 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`。 - 内置语音提供商由插件拥有。如果设置了 `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 模式（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 提供商时，`talk.provider` 必须匹配 `talk.providers` 中的一个键。 - 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容。运行 `openclaw doctor --fix` 可将持久化配置重写到 `talk.providers.`。 - 语音 ID 会回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。 - `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 智能体运行所使用的思考级别。留空可保留正常会话/模型行为。 - `consultFastMode` 为 Control UI Talk 实时咨询设置一次性快速模式覆盖，而不更改会话的正常快速模式设置。 - `speechLocale` 设置 iOS/macOS Talk 语音识别使用的 BCP 47 区域设置 ID。留空则使用设备默认值。 - `silenceTimeoutMs` 控制 Talk 模式在用户静默后等待多久再发送转录。未设置时保留平台默认暂停窗口（`macOS 和 Android 上为 700 ms，iOS 上为 900 ms`）。 - `realtime.instructions` 会向 OpenClaw 的内置实时提示追加面向提供商的系统指令，因此可以配置语音风格而不丢失默认的 `openclaw_agent_consult` 指导。 --- ## 相关 - [配置参考](/zh-CN/gateway/configuration-reference) — 所有其他配置键 - [配置](/zh-CN/gateway/configuration) — 常见任务和快速设置 - [配置示例](/zh-CN/gateway/configuration-examples)