配置 — 智能体心跳、压缩与流式
agents.defaults.* 键用于控制代理何时自主运行、其转录如何压缩和修剪,以及部分输出如何到达聊天。
agents.defaults.heartbeat¶
周期性心跳运行。
{
agents: {
defaults: {
heartbeat: {
agentId: "ops", // ambient owner when no per-agent heartbeat is configured
every: "30m", // 0m disables recurring cadence
activeHours: { start: "08:00", end: "24:00" },
model: "openai/gpt-5.4-mini",
session: "main",
target: "owner", // default | options: last | none | whatsapp | telegram | discord | ...
directPolicy: "allow", // allow (default) | block
to: "+15555550123",
accountId: "ops-bot",
prompt: "Follow the heartbeat monitor scratch context...",
timeoutSeconds: 45,
lightContext: false, // default: false; true skips workspace bootstrap files for heartbeat runs
isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history)
},
},
},
}
every:持续时间字符串(ms/s/m/h)。默认:30m(API-key 认证)或1h(OAuth 认证)。设置为0m可禁用周期性运行。目标事件驱动的唤醒(包括后台 exec 完成后的后续处理)仍可以运行一个代理轮次。agentId:当不存在agents.entries.*.heartbeat块时,用于指定常驻心跳运行的显式所有者。没有agentId的共享心跳块会保留现有的所有代理注册行为。- 运行周期会被写入系统拥有的 cron 监控行。运行
openclaw doctor --fix以生成缺失或过期的行。如果 cron 已禁用,计划心跳不会运行,并且网关会记录一条启动警告。 - 心跳对象是严格的。其支持的字段为
agentId、every、activeHours、model、session、target、directPolicy、to、accountId、prompt、timeoutSeconds、lightContext和isolatedSession。 timeoutSeconds:允许心跳代理轮次在被中止前运行的最大秒数。留空时,如果已设置agents.defaults.timeoutSeconds则使用它,否则使用心跳周期,上限为 600 秒。directPolicy:直接/私信投递策略。allow(默认)允许向直接目标投递。block会抑制向直接目标投递,并输出reason=dm-blocked。target:owner(默认)仅发送到来自commands.ownerAllowFrom或频道allowFrom的私信身份。last显式跟随最新会话,包括群组。none将结果保留在内部。to:仅与显式频道目标一起使用。owner和未设置的目标会忽略它。lightContext:为 true 时,心跳运行使用轻量级引导上下文,并跳过工作区引导文件。无论如何,监控草稿都会由心跳运行器注入。isolatedSession:为 true 时,每次心跳都在一个没有先前会话历史的新会话中运行。与 cronsessionTarget: "isolated"的隔离模式相同。可将每次心跳的 token 成本从约 100K 降低到约 2-5K tokens。- 忙碌延迟是自动的:计划心跳会等待 main/cron 活动、同一代理的活跃运行以及目标会话工作。立即和手动唤醒仅绕过宽泛的同一代理活跃运行预检查。
- 心跳运行使用普通代理系统提示。确认抑制使用固定的 300 字符剩余预算,推理负载保持内部,工具错误警告保持启用。
- 按代理:设置
agents.entries.*.heartbeat。当任何代理定义了heartbeat时,只有这些代理会运行心跳。 - 心跳运行完整的代理轮次——更短的间隔会消耗更多 token。
agents.defaults.systemAgent¶
选择负责常驻 OpenClaw 系统工作的代理;该代理的模型和凭据将拥有以下工作:system-agent 和 Custodian 咨询,以及当常驻路径省略 agentId 时的回退所有者。这包括 models.list、models.authStatus、skills.status 和 doctor.memory.status,认证、模型目录和 doctor 解析背后的默认代理目录和工作区,出站频道引导和队列投递恢复,无范围主会话路由,Talk 中继所有权,以及首次运行引导:
显式请求的 agentId 始终优先,其次是 systemAgent.agentId,当所有权不明确时是遗留默认所有者,最后是唯一的已配置代理。仅保留的迁移来源信息永远不会指定显式代理群的运行时默认值。带有请求代理的委托咨询会保留该请求者作为其所有者。
在 agents.ownership: "explicit" 下,此设置还为支持默认代理选择的操作提供已记录的默认值,包括代理列表徽章、未绑定频道路由、无范围 Gateway 读取、openclaw sessions、openclaw hooks 状态以及 TUI 启动。Doctor 会在此记录迁移后的默认值,以便这些操作在重启后保持相同的所有者。显式绑定、请求和会话存储所有者优先。使用 --agent <id> 选择其他代理,或使用 openclaw sessions --all-agents 检查整个代理群。需要显式选择的操作(例如 openclaw models)会保留该要求。
无所有者的多代理群没有默认徽章。使用 openclaw config set agents.defaults.systemAgent.agentId <id> 设置一个已配置的 id。唯一已配置的代理即使没有保存的默认指定,仍可拥有未限定的 Gateway 会话请求。没有所有者的常驻工作会以可操作的错误失败,队列投递恢复除外;它会记录失败的投递并继续排空队列中的其余部分。更改运行时默认值不会迁移现有工作区或遗留数据。仅用于升级的所有权位于 agents.defaults.authInheritance.agentId(用于继承凭据)和 agents.defaults.sessionStore.agentId(用于已退役的 main 会话行或固定 session.store 中的无范围行)。
agents.defaults.compaction¶
{
agents: {
defaults: {
compaction: {
enabled: false, // disable embedded proactive auto-compaction (default: true)
mode: "safeguard", // default | safeguard
provider: "my-provider", // id of a registered compaction provider plugin (optional)
thinkingLevel: "low", // optional override; omit for the provider default
timeoutSeconds: 180,
keepRecentTokens: 50000,
recentTurnsPreserve: 3,
identifierPolicy: "strict", // strict | off
qualityGuard: { enabled: true, maxRetries: 1 },
midTurnPrecheck: { enabled: false }, // optional tool-loop pressure check
postIndexSync: "async", // off | async | await
postCompactionSections: ["Session Startup", "Red Lines"],
model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override
maxActiveTranscriptBytes: "20mb", // opt in to preflight local compaction
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",
},
},
},
},
}
enabled:当为false时,禁用嵌入式代理运行时中由阈值触发的自动压缩。OpenClaw 的预检和溢出恢复压缩路径以及手动/compact仍然可用。默认值:true。mode:default或safeguard(摘要质量审计和最近轮次保留)。参见 压缩。provider:已注册的压缩提供商插件的 ID。设置后,将调用该提供商的summarize(),而不是内置 LLM 摘要。失败时回退到内置实现。设置提供商会强制mode: "safeguard"。参见 压缩。thinkingLevel:仅用于嵌入式 OpenClaw 压缩摘要的思考级别(off、minimal、low、medium、high、xhigh、adaptive、max、ultra或inherit)。省略时,提供商可以提供压缩偏好;否则默认为low。原生本地 Ollama 优先使用off,以便摘要不会将请求预算花在思考上。设置inherit以复用会话当前的思考级别,或选择显式级别来覆盖提供商默认值。所选级别会被限制在压缩模型/运行时的范围内。原生 Codex app-server 压缩会忽略此设置,因为原生 compact 请求没有按操作覆盖思考级别的功能;配置后 OpenClaw 会记录警告。timeoutSeconds:内置压缩模型请求可以无进展的最长时间。每次请求开始以及每个流式输出 Token(文本、推理或工具调用增量;不包括 keepalive)都会刷新窗口,因此持续流式输出的慢请求可以完成,而静默请求会在一个窗口后中止。即使持续流式输出,完整压缩也会在 10 个窗口(默认 30 分钟)后停止。当插件上下文引擎调用delegateCompactionToRuntime时,此规则同样适用;插件自身的压缩工作在整个操作中获得一个窗口。默认值:180。keepRecentTokens:代理切分点预算,用于逐字保留最近的转录尾部。默认值:20000。recentTurnsPreserve:在 safeguard 摘要之外逐字保留的最近用户/助手轮次数。默认值:3。identifierPolicy:strict(默认)或off。strict会在压缩摘要期间前置内置的不透明标识符保留指导。qualityGuard:针对内置 safeguard 摘要的有界验证。在 safeguard 模式下默认启用。最终预算分配后,必需标题必须保留在保留的生成正文中,而待处理请求和精确标识符必须保留在要存储的精确工件中。如果没有任何尝试通过,OpenClaw 会保留原始历史,并返回压缩失败,而不是存储已知无效的上下文。自动压缩中的摘要超时是例外:OpenClaw 会在没有摘要的情况下提交压缩,较早的未摘要事实会离开模型上下文(参见 压缩)。设置enabled: false可跳过审计。已配置的压缩提供商输出保留其现有的提供商拥有的验证行为。midTurnPrecheck:可选的工具循环压力检查。当enabled: true时,OpenClaw 会在工具结果追加之后、下一次模型调用之前检查预计的提供商 Prompt。如果上一次调用报告了上下文使用情况,并且其前缀、系统 Prompt、工具和模型均未变化,则检查会复用其测量的 Prompt 和 completion 占用,包括不透明推理。匹配的助手片段只计算一次;新的工具结果和其他追加内容采用保守估计。保留的 completion 使用情况可在上下文变化后继续覆盖不透明推理。缺少使用情况或上下文变化时使用保守的 Prompt 估计。如果上下文不再适合,它会在提交 Prompt 之前中止当前尝试,并复用现有的预检恢复路径来截断工具结果或压缩并重试。兼容default和safeguard两种压缩模式。默认值:禁用。postIndexSync:压缩后的会话内存重新索引模式。默认值:"async"。使用"await"可获得最强的新鲜度,使用"async"可降低压缩延迟,仅当会话内存同步在其他地方处理时使用"off"。异步模式会在压缩返回前开始索引,但不会等待其完成;冷内存初始化仍可能增加延迟。postCompactionSections:压缩后要重新注入的可选 AGENTS.md H2/H3 章节名称。safeguard 摘要会从有效代理工作区读取这些章节,如果文件无法读取或配置的章节缺失,则记录警告。保持未设置或使用[]可禁用。model:仅用于压缩摘要的可选provider/model-id或来自agents.defaults.models的裸别名。裸别名在分发前解析;发生冲突时,配置的显式模型 ID 保留优先权。当主会话应保留一个模型,但压缩摘要应在另一个模型上运行时,使用此设置;未设置时,压缩使用会话的主模型。maxActiveTranscriptBytes:字节阈值(number或类似"20mb"的字符串),当模型看到的转录窗口(自最近一次压缩或重置以来的所有内容,加上其保留尾部)达到阈值时,启用运行前的常规本地压缩。对于 Codex app-server 会话,同一阈值会限制原生 rollout 转录,超大的原生线程会重新开始。未设置或为0时禁用。当上下文引擎返回显式的压缩后继身份时,OpenClaw 会采用它;内置 SQLite 压缩器保留当前身份。notifyUser:当为true时,向用户发送简短的上下文维护通知:压缩开始和完成时(例如,“正在压缩上下文...” 和 “压缩完成”),以及压缩前内存刷新耗尽、回复以降级状态继续时(例如,“内存维护暂时失败;正在继续您的回复。”)。默认禁用,以保持这些通知静默。memoryFlush:自动压缩前用于存储持久内存的静默代理轮次。宿主会结合活动上下文窗口解析这些设置,并填充所选内存提供商从计划中省略的计时字段。当此维护轮次应保留在本地模型上时,将model设置为精确的提供商/模型,例如ollama/qwen3:8b;该覆盖不会继承活动会话的回退链。当模型可见的转录窗口达到阈值时,forceFlushTranscriptBytes会强制刷新,即使 Token 计数器已过时;压缩后,该窗口包括保留尾部和后续轮次,而不是被丢弃的历史。文件端提供商需要可写工作区访问权限;工具端提供商不需要。
自定义压缩指令由代码控制。实现一个压缩提供程序插件,并使用 summarize() 进行自定义摘要构建;当需要将压缩后的上下文注入到后续模型提示中时,使用 before_prompt_build。Doctor 会移除已弃用的指令字段,并指向这些扩展点。
agents.defaults.contextPruning¶
在发送到 LLM 之前,从内存上下文修剪 旧工具结果。不会 修改 磁盘上的会话历史。默认禁用;设置 mode: "cache-ttl" 以启用。
{
agents: {
defaults: {
contextPruning: {
mode: "cache-ttl", // off (default) | cache-ttl
ttl: "1h", // duration string; bare numbers are minutes (default 5m)
tools: { allow: [], deny: [] }, // tool names eligible for / excluded from pruning
hardClear: {
enabled: true, // false skips the hard-clear step
placeholder: "[Old tool result content cleared]",
},
},
},
},
}
cache-ttl 模式行为
mode: "cache-ttl"启用修剪过程。ttl设置缓存条目在被视为新鲜之前可保持新鲜的时间,之后才能开始新的修剪轮次。它是一个时长字符串,其中纯数字表示分钟;内置默认值为 5 分钟,捆绑的 Anthropic 插件会预置1h。tools.allow和tools.deny限定哪些工具名称可被修剪。hardClear.enabled: false跳过硬清除步骤,hardClear.placeholder替换默认的[Old tool result content cleared]文本。- 修剪会先软修剪过大的工具结果,然后在必要时硬清除较旧的工具结果。
软修剪 保留开头 + 结尾,并在中间插入 ...。
硬清除 将整个工具结果替换为占位符。
备注:
- 图像块永远不会被修剪/清除。
- 比例基于字符(近似值),不是精确的 Token 计数。
- 最近的助手消息会被保留。
有关行为详情,请参阅 会话修剪。
块流式传输¶
{
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 渠道需要显式设置
*.streaming.block.enabled: true才能启用块回复。QQ Bot 是例外:它没有streaming.block键,并且会流式传输块回复,除非channels.qqbot.streaming.mode为"off"。 - 渠道覆盖:
channels.<channel>.streaming.block.coalesce(以及按账户的变体)。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.entries.*.humanDelay。
有关行为和分块详情,请参阅 流式传输。
正在输入指示器¶
{
agents: {
defaults: {
typingMode: "instant", // never | instant | thinking | message
typingIntervalSeconds: 6,
},
},
}
- 默认值:直接聊天/提及使用
instant,未提及的群聊使用message。 typingIntervalSeconds默认值:6。- 按代理覆盖:
agents.entries.*.typingMode。
请参阅 正在输入指示器。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw