配置 — 智能体心跳、压缩和流式传输

agents.defaults.* 键控制 agent 何时自主运行、其对话记录如何被压缩和修剪，以及部分输出如何到达聊天。

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 密钥认证）或 1h（OAuth 认证）。设为 0m 可禁用定期执行节奏。定向事件驱动的唤醒（包括后台 exec 完成后的后续处理）仍可运行一个 agent 回合。
• agentId：当不存在 agents.entries.*.heartbeat 配置块时，作为隐式心跳运行的显式所有者。不带 agentId 的共享心跳配置块将保留现有的全 agent 参与行为。
• 执行节奏会写入一条系统拥有的 cron 监控记录。运行 openclaw doctor --fix 可创建缺失或过期的记录。如果 cron 被禁用，计划的心跳将不会运行，gateway 会记录一条启动警告。
• heartbeat 对象是严格的。其支持的字段为 agentId、every、activeHours、model、session、target、directPolicy、to、accountId、prompt、timeoutSeconds、lightContext 和 isolatedSession。
• timeoutSeconds：心跳 agent 回合在被中止前允许的最长时间（秒）。不设置时，若 agents.defaults.timeoutSeconds 已配置则使用该值，否则使用上限为 600 秒的心跳节奏。
• directPolicy：direct/DM 投递策略。allow（默认）允许直接目标投递。block 禁止直接目标投递，并发出 reason=dm-blocked。
• target：owner（默认）仅发送到来自 commands.ownerAllowFrom 或渠道 allowFrom 的私信身份。last 显式跟随最近的对话（包括群组）。none 将结果保留在内部。
• to：仅用于显式渠道目标。owner 和未设置的目标会忽略它。
• lightContext：为 true 时，心跳运行使用轻量级引导上下文，并跳过工作区引导文件。无论哪种方式，心跳运行器都会注入 Monitor scratch 上下文。
• isolatedSession：为 true 时，每次心跳都在全新会话中运行，不携带之前的对话历史。与 cron sessionTarget: "isolated" 的隔离模式相同。可将每次心跳的 token 成本从约 100K 降低到约 2-5K tokens。
• 忙碌时自动推迟：计划的心跳会等待 main/cron 活动、同一 agent 的活动运行以及目标会话工作。即时唤醒和手动唤醒仅绕过宽泛的同一 agent 活动运行预检查。
• 心跳运行使用常规的 agent 系统提示词。确认消息抑制使用固定的 300 字符剩余预算，推理负载保持内部，工具错误警告保持启用。
• 按 agent 单独配置：设置 agents.entries.*.heartbeat。当任何 agent 定义了 heartbeat 时，只有这些 agent 会运行心跳。
• 心跳会运行完整的 agent 回合——间隔越短，消耗的 token 越多。

agents.defaults.systemAgent¶

选择其模型和凭据作为隐式 OpenClaw 系统工作所有者的 agent：system-agent 和 Custodian 咨询，以及隐式路径省略 agentId 时的回退所有者。这包括 models.list、models.authStatus、skills.status 和 doctor.memory.status，认证、模型目录和 doctor 解析背后的默认 agent 目录与工作区，出站渠道引导和队列投递恢复，未限定范围的 main-session 路由，Talk relay 所有权，以及首次运行引导：

{
  agents: {
    defaults: {
      systemAgent: { agentId: "ops" },
    },
  },
}

显式请求的 agentId 始终优先，其次是 systemAgent.agentId，再是所有权不显式时的旧版默认所有者，最后是唯一配置的 agent。仅靠保留的迁移来源记录，永远不会指定显式集群的运行时默认值。由请求 agent 委托的咨询会保留该请求者作为其所有者。

当 agents.ownership: "explicit" 时，此设置还为支持默认 agent 选择的操作提供已记录的默认值，包括 agent 列表徽章、未绑定渠道路由、未限定范围的 Gateway 读取、openclaw sessions、openclaw hooks 状态以及 TUI 启动。Doctor 会将迁移后的默认值记录在此处，以便这些操作在重启后保持相同的所有者。显式绑定、请求和会话存储所有者优先。使用 --agent <id> 选择其他 agent，或使用 openclaw sessions --all-agents 检查整个集群。要求显式选择的操作（如 openclaw models）仍保留该要求。

无所有者的多 agent 集群没有默认徽章。使用 openclaw config set agents.defaults.systemAgent.agentId <id> 设置一个已配置的 id。即使没有保存默认指定，唯一配置的 agent 仍可拥有未指定 agent 的 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：内置压缩中每个模型请求的安全窗口。多阶段压缩会在下一个串行模型请求开始时刷新窗口，因此完整压缩可以超过该值，而无响应的请求仍会被中止。由插件管理的压缩针对完整操作获得一个窗口。默认值：180。
• keepRecentTokens：代理切分点预算，用于逐字保留最近的转录尾部。默认值：20000。
• recentTurnsPreserve：在 safeguard 摘要之外逐字保留的最近用户/助手轮数。默认值：3。
• identifierPolicy：strict（默认）或 off。strict 会在压缩摘要期间前置内置的不透明标识符保留指导。
• qualityGuard：针对内置 safeguard 摘要的有界验证。在 safeguard 模式下默认启用。最终预算分配后，必需标题必须保留在保留的生成正文中，而待处理请求和精确标识符必须保留在待存储的精确工件中。如果没有任何尝试通过，OpenClaw 会保留原始历史并返回压缩失败，而不是存储已知无效的上下文。设置 enabled: false 可跳过审计。已配置的压缩提供商输出保持其现有的由提供商管理的验证行为。
• midTurnPrecheck：可选的工具循环压力检查。当 enabled: true 时，OpenClaw 会在工具结果追加后、下一次模型调用前检查上下文压力。如果上下文不再能容纳，它会在提交提示前中止当前尝试，并复用现有预检恢复路径来截断工具结果或压缩后重试。兼容 default 和 safeguard 两种压缩模式。默认：禁用。
• postIndexSync：压缩后的会话内存重建索引模式。默认值："async"。使用 "await" 可获得最高新鲜度，使用 "async" 可降低压缩延迟，或仅在会话内存同步由其他地方处理时使用 "off"。
• postCompactionSections：可选的 AGENTS.md H2/H3 章节名称，用于在压缩后重新注入。保持未设置或使用 [] 可禁用。
• 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]",
        },
      },
    },
  },
}

有关行为详情，请参阅 会话修剪。

块流式传输¶

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

请参阅 输入指示器。