diff --git a/docs/zh-CN/concepts/system-prompt.md b/docs/zh-CN/concepts/system-prompt.md index 3562198af..467cafc78 100644 --- a/docs/zh-CN/concepts/system-prompt.md +++ b/docs/zh-CN/concepts/system-prompt.md @@ -1,74 +1,65 @@ --- read_when: - - 编辑系统提示词文本、工具列表或时间 / 心跳部分时 + - 编辑系统提示词文本、工具列表或时间/心跳部分时 - 更改工作区引导或 Skills 注入行为时 summary: OpenClaw 系统提示词包含哪些内容以及如何组装 title: 系统提示词 x-i18n: - generated_at: "2026-04-05T17:47:02Z" + generated_at: "2026-04-07T23:53:48Z" model: gpt-5.4 provider: openai - source_hash: f14ba7f16dda81ac973d72be05931fa246bdfa0e1068df1a84d040ebd551c236 + source_hash: e55fc886bc8ec47584d07c9e60dfacd964dc69c7db976ea373877dc4fe09a79a source_path: concepts/system-prompt.md workflow: 15 --- # 系统提示词 -OpenClaw 会为每次智能体运行构建自定义系统提示词。该提示词由 **OpenClaw 自有**，不使用 pi-coding-agent 的默认提示词。 +OpenClaw 会为每次智能体运行构建一个自定义系统提示词。该提示词由 **OpenClaw 自有**，不使用 pi-coding-agent 的默认提示词。 提示词由 OpenClaw 组装，并注入到每次智能体运行中。 -提供商插件可以贡献具备缓存感知能力的提示词引导，而无需替换完整的 OpenClaw 自有提示词。提供商运行时可以： +提供商插件可以贡献具备缓存感知能力的提示词指导，而无需替换完整的 OpenClaw 自有提示词。提供商运行时可以： -- 替换一小组具名核心部分（`interaction_style`、`tool_call_style`、`execution_bias`） -- 在提示词缓存边界之上注入**稳定前缀** -- 在提示词缓存边界之下注入**动态后缀** +- 替换一小组已命名的核心部分（`interaction_style`、`tool_call_style`、`execution_bias`） +- 在提示词缓存边界之上注入一个**稳定前缀** +- 在提示词缓存边界之下注入一个**动态后缀** -将提供商自有贡献用于针对特定模型家族的调优。保留旧版 -`before_prompt_build` 提示词变更机制，用于兼容性或真正的全局提示词更改，而不是常规的提供商行为。 +将提供商自有的贡献用于特定模型家族的调优。保留传统的 +`before_prompt_build` 提示词变更机制，以用于兼容性需求或真正的全局提示词变更，而不是常规的提供商行为。 ## 结构 -该提示词有意保持紧凑，并使用固定部分： +该提示词刻意保持紧凑，并使用固定部分： -- **工具**：结构化工具事实来源提醒，加上运行时工具使用引导。 -- **安全**：简短的护栏提醒，用于避免追求权力的行为或绕过监督。 -- **Skills**（可用时）：告诉模型如何按需加载 skill 说明。 -- **OpenClaw 自更新**：如何使用 - `config.schema.lookup` 安全检查配置，使用 `config.patch` 修补配置，使用 `config.apply` 替换完整配置，以及仅在用户明确请求时运行 `update.run`。仅所有者可用的 `gateway` 工具也会拒绝重写 - `tools.exec.ask` / `tools.exec.security`，包括会规范化为这些受保护 exec 路径的旧版 `tools.bash.*` - 别名。 -- **工作区**：工作目录（`agents.defaults.workspace`）。 -- **文档**：OpenClaw 文档的本地路径（仓库或 npm 包）以及何时读取它们。 -- **工作区文件（已注入）**：表示引导文件已包含在下方。 -- **沙箱**（启用时）：表示沙箱隔离运行时、沙箱路径以及是否可使用提升权限的 exec。 -- **当前日期和时间**：用户本地时间、时区和时间格式。 -- **回复标签**：受支持提供商的可选回复标签语法。 -- **心跳**：心跳提示词和确认行为。 -- **运行时**：主机、操作系统、node、仓库根目录（检测到时）、思考级别（一行）。 -- **推理**：当前可见性级别 + /reasoning 切换提示。 +- **Tooling**：结构化工具的权威来源提醒，以及运行时工具使用指导。 +- **Safety**：简短的护栏提醒，避免寻求权力的行为或绕过监督。 +- **Skills**（可用时）：告诉模型如何按需加载 skill 指令。 +- **OpenClaw Self-Update**：如何使用 `config.schema.lookup` 安全检查配置，使用 `config.patch` 修补配置，使用 `config.apply` 替换完整配置，以及仅在用户明确请求时运行 `update.run`。仅所有者可用的 `gateway` 工具也会拒绝重写 `tools.exec.ask` / `tools.exec.security`，包括会被规范化为这些受保护 exec 路径的旧版 `tools.bash.*` 别名。 +- **Workspace**：工作目录（`agents.defaults.workspace`）。 +- **Documentation**：OpenClaw 文档的本地路径（仓库或 npm 包）以及何时应阅读它们。 +- **Workspace Files (injected)**：表示引导文件已包含在下方。 +- **Sandbox**（启用时）：表示处于沙箱隔离运行时、沙箱路径，以及是否提供提权 exec。 +- **Current Date & Time**：用户本地时间、时区和时间格式。 +- **Reply Tags**：受支持提供商的可选回复标签语法。 +- **Heartbeats**：心跳提示词与确认行为，以及何时为默认智能体启用心跳。 +- **Runtime**：主机、操作系统、node、模型、仓库根目录（检测到时）、思考级别（一行）。 +- **Reasoning**：当前可见性级别 + `/reasoning` 切换提示。 -“工具”部分还包含针对长时间运行工作的运行时引导： +Tooling 部分还包含针对长时间运行任务的运行时指导： -- 对未来的后续操作使用 cron（`check back later`、提醒、周期性工作） - ，而不是使用 `exec` 睡眠循环、`yieldMs` 延迟技巧或重复的 `process` - 轮询 -- 仅将 `exec` / `process` 用于立即启动并持续在后台运行的命令 -- 当启用了自动完成唤醒时，只启动命令一次，并在其输出内容或失败时依赖基于推送的唤醒路径 +- 对于将来的后续跟进（`check back later`、提醒、周期性工作），使用 cron，而不是 `exec` 睡眠循环、`yieldMs` 延迟技巧或重复的 `process` 轮询 +- 仅将 `exec` / `process` 用于那些现在启动并将在后台继续运行的命令 +- 启用自动完成唤醒时，只启动命令一次，并在其输出结果或失败时依赖基于推送的唤醒路径 - 当你需要检查正在运行的命令时，使用 `process` 查看日志、状态、输入或进行干预 -- 如果任务更大，优先使用 `sessions_spawn`；子智能体完成是基于推送的，并会自动通知回请求方 -- 不要为了等待完成而循环轮询 `subagents list` / `sessions_list` +- 如果任务更大，优先使用 `sessions_spawn`；子智能体完成采用基于推送的方式，并会自动向请求方通告 +- 不要仅为了等待完成而循环轮询 `subagents list` / `sessions_list` -当启用实验性的 `update_plan` 工具时，“工具”部分还会告诉模型： -仅将其用于非平凡的多步骤工作，始终保持恰好一个 -`in_progress` 步骤，并避免在每次更新后重复整个计划。 +启用实验性 `update_plan` 工具时，Tooling 还会告诉模型：仅将其用于非平凡的多步骤工作，始终只保留一个 `in_progress` 步骤，并避免在每次更新后重复整个计划。 -系统提示词中的安全护栏属于建议性内容。它们会引导模型行为，但不强制执行策略。硬性约束应使用工具策略、exec 审批、沙箱隔离和渠道允许列表；操作员可按设计禁用这些约束。 +系统提示词中的 Safety 护栏属于建议性质。它们会引导模型行为，但不强制执行策略。需要使用工具策略、exec 审批、沙箱隔离和渠道允许列表来实现硬性约束；操作员可以按设计禁用这些机制。 -在具有原生审批卡片 / 按钮的渠道上，运行时提示词现在会告诉 -智能体优先依赖该原生审批 UI。只有当工具结果表明聊天审批不可用，或手动审批是唯一途径时，它才应包含手动 -`/approve` 命令。 +在具有原生审批卡片/按钮的渠道上，运行时提示词现在会告诉智能体优先依赖该原生审批 UI。只有当工具结果表明聊天审批不可用，或手动审批是唯一途径时，它才应包含手动 `/approve` 命令。 ## 提示词模式 @@ -76,18 +67,15 @@ OpenClaw 可以为子智能体渲染更小的系统提示词。运行时会为 `promptMode`（不是面向用户的配置）： - `full`（默认）：包含上述所有部分。 -- `minimal`：用于子智能体；省略 **Skills**、**Memory Recall**、**OpenClaw - Self-Update**、**Model Aliases**、**User Identity**、**Reply Tags**、 - **Messaging**、**Silent Replies** 和 **Heartbeats**。工具、**安全**、 - 工作区、沙箱、当前日期和时间（已知时）、运行时和注入的上下文仍然可用。 +- `minimal`：用于子智能体；省略 **Skills**、**Memory Recall**、**OpenClaw Self-Update**、**Model Aliases**、**User Identity**、**Reply Tags**、**Messaging**、**Silent Replies** 和 **Heartbeats**。Tooling、**Safety**、Workspace、Sandbox、Current Date & Time（已知时）、Runtime 以及注入的上下文仍然可用。 - `none`：仅返回基础身份行。 -当 `promptMode=minimal` 时，额外注入的提示词会标记为 **子智能体 -上下文**，而不是 **群聊上下文**。 +当 `promptMode=minimal` 时，额外注入的提示词会标记为 **Subagent +Context**，而不是 **Group Chat Context**。 ## 工作区引导注入 -引导文件会被裁剪并附加在 **项目上下文** 下，以便模型在无需显式读取的情况下看到身份和配置文件上下文： +引导文件会被裁剪并附加在 **Project Context** 下，以便模型在无需显式读取的情况下看到身份和配置上下文： - `AGENTS.md` - `SOUL.md` @@ -96,33 +84,32 @@ OpenClaw 可以为子智能体渲染更小的系统提示词。运行时会为 - `USER.md` - `HEARTBEAT.md` - `BOOTSTRAP.md`（仅在全新工作区中） -- 存在时使用 `MEMORY.md`，否则回退为小写的 `memory.md` +- 存在时使用 `MEMORY.md`，否则使用小写回退文件 `memory.md` -所有这些文件都会在每一轮**注入到上下文窗口中**，这意味着它们会消耗 token。请保持其简洁——尤其是 `MEMORY.md`，它会随着时间增长，并可能导致上下文用量意外升高以及更频繁的压缩。 +除非某个文件适用特定门控条件，否则所有这些文件都会在每一轮**注入到上下文窗口中**。当默认智能体禁用心跳，或 +`agents.defaults.heartbeat.includeSystemPromptSection` 为 false 时，正常运行中会省略 `HEARTBEAT.md`。请保持注入文件简洁——尤其是 `MEMORY.md`，它会随着时间增长，并可能导致上下文使用量意外升高以及更频繁的压缩。 -> **注意：** `memory/*.md` 每日文件**不会**被自动注入。它们会按需通过 `memory_search` 和 `memory_get` 工具访问，因此除非模型显式读取它们，否则不会计入上下文窗口。 +> **注意：** `memory/*.md` 每日文件**不会**自动注入。它们按需通过 `memory_search` 和 `memory_get` 工具访问，因此除非模型显式读取，否则不会占用上下文窗口。 -大文件会被截断，并附带标记。每个文件的最大大小由 -`agents.defaults.bootstrapMaxChars` 控制（默认值：20000）。跨文件注入的引导内容总量上限由 `agents.defaults.bootstrapTotalMaxChars` -控制（默认值：150000）。缺失的文件会注入简短的缺失文件标记。发生截断时，OpenClaw 可以在项目上下文中注入警告块；可通过 -`agents.defaults.bootstrapPromptTruncationWarning` 控制（`off`、`once`、`always`； -默认值：`once`）。 +大文件会带标记被截断。每个文件的最大大小由 +`agents.defaults.bootstrapMaxChars` 控制（默认：20000）。跨文件注入的引导内容总量上限由 `agents.defaults.bootstrapTotalMaxChars` +控制（默认：150000）。缺失文件会注入一个简短的缺失文件标记。发生截断时，OpenClaw 可以在 Project Context 中注入一个警告块；可通过 +`agents.defaults.bootstrapPromptTruncationWarning` 控制（`off`、`once`、`always`；默认：`once`）。 -子智能体会话仅注入 `AGENTS.md` 和 `TOOLS.md`（其他引导文件会被过滤掉，以保持子智能体上下文较小）。 +子智能体会话只注入 `AGENTS.md` 和 `TOOLS.md`（其他引导文件会被过滤掉，以保持子智能体上下文较小）。 -内部 hooks 可以通过 `agent:bootstrap` 拦截此步骤，以变更或替换 -注入的引导文件（例如将 `SOUL.md` 替换为其他 persona）。 +内部 hooks 可以通过 `agent:bootstrap` 拦截此步骤，以变更或替换注入的引导文件（例如将 `SOUL.md` 替换为另一种 persona）。 -如果你希望让智能体听起来不那么通用，请从 +如果你想让智能体听起来不那么泛化，可以从 [SOUL.md Personality Guide](/zh-CN/concepts/soul) 开始。 -要检查每个注入文件贡献了多少内容（原始与注入、截断以及工具 schema 开销），请使用 `/context list` 或 `/context detail`。参见 [Context](/zh-CN/concepts/context)。 +若要检查每个注入文件贡献了多少内容（原始内容与注入内容、截断情况，以及工具 schema 开销），请使用 `/context list` 或 `/context detail`。参见 [Context](/zh-CN/concepts/context)。 ## 时间处理 -当用户时区已知时，系统提示词会包含专门的**当前日期和时间**部分。为了保持提示词缓存稳定，它现在只包含**时区**（不包含动态时钟或时间格式）。 +当已知用户时区时，系统提示词会包含一个专门的 **Current Date & Time** 部分。为了保持提示词缓存稳定，它现在只包含**时区**（不包含动态时钟或时间格式）。 -当智能体需要当前时间时，请使用 `session_status`；状态卡片包含时间戳行。相同工具还可以选择设置每个会话的模型覆盖（`model=default` 会清除它）。 +当智能体需要当前时间时，请使用 `session_status`；状态卡片包含时间戳行。该工具还可以选择设置按会话生效的模型覆盖（`model=default` 会清除它）。 配置方式： @@ -134,9 +121,9 @@ OpenClaw 可以为子智能体渲染更小的系统提示词。运行时会为 ## Skills 当存在符合条件的 Skills 时，OpenClaw 会注入一个紧凑的**可用 Skills 列表** -（`formatSkillsForPrompt`），其中包含每个 skill 的**文件路径**。提示词会指示模型使用 `read` 加载列出位置（工作区、托管或内置）的 SKILL.md。若无符合条件的 Skills，则省略 Skills 部分。 +（`formatSkillsForPrompt`），其中包含每个 skill 的**文件路径**。提示词会指示模型使用 `read` 在所列位置（工作区、托管或内置）加载 SKILL.md。若没有符合条件的 Skills，则省略 Skills 部分。 -符合条件与否会考虑 skill 元数据门控、运行时环境 / 配置检查，以及在配置了 `agents.defaults.skills` 或 +符合条件的判断包括 skill 元数据门控、运行时环境/配置检查，以及在配置了 `agents.defaults.skills` 或 `agents.list[].skills` 时生效的智能体 skill 允许列表。 ``` @@ -149,10 +136,9 @@ OpenClaw 可以为子智能体渲染更小的系统提示词。运行时会为 ``` -这样可以保持基础提示词较小，同时仍支持有针对性的 skill 使用。 +这样可以在保持基础提示词精简的同时，仍支持有针对性的 skill 使用。 ## 文档 -可用时，系统提示词会包含一个**文档**部分，指向本地 OpenClaw 文档目录（仓库工作区中的 `docs/` 或内置 npm -包文档），并说明公共镜像、源仓库、社区 Discord 以及用于发现 Skills 的 ClawHub（[https://clawhub.ai](https://clawhub.ai)）。提示词会指示模型在处理 OpenClaw 行为、命令、配置或架构时优先查阅本地文档，并在可能时自行运行 -`openclaw status`（仅在缺少访问权限时才询问用户）。 +可用时，系统提示词会包含一个 **Documentation** 部分，指向本地 OpenClaw 文档目录（仓库工作区中的 `docs/` 或内置 npm 包文档），并且还会说明公共镜像、源代码仓库、社区 Discord，以及用于发现 Skills 的 ClawHub（[https://clawhub.ai](https://clawhub.ai)）。提示词会指示模型在处理 OpenClaw 行为、命令、配置或架构时优先查阅本地文档，并在可能时自行运行 +`openclaw status`（只有在无法访问时才询问用户）。 diff --git a/docs/zh-CN/gateway/heartbeat.md b/docs/zh-CN/gateway/heartbeat.md index 0bc469551..509c6fcfe 100644 --- a/docs/zh-CN/gateway/heartbeat.md +++ b/docs/zh-CN/gateway/heartbeat.md @@ -1,39 +1,38 @@ --- read_when: - - 调整 heartbeat 频率或消息内容 - - 在定时任务中决定使用 heartbeat 还是 cron -summary: Heartbeat 轮询消息和通知规则 -title: Heartbeat + - 调整心跳频率或消息传递方式 + - 决定在计划任务中使用心跳还是 cron +summary: 心跳轮询消息和通知规则 +title: 心跳 x-i18n: - generated_at: "2026-04-05T08:24:14Z" + generated_at: "2026-04-07T23:54:15Z" model: gpt-5.4 provider: openai - source_hash: f417b0d4453bed9022144d364521a59dec919d44cca8f00f0def005cd38b146f + source_hash: a8021d747637060eacb91ec5f75904368a08790c19f4fca32acda8c8c0a25e41 source_path: gateway/heartbeat.md workflow: 15 --- -# Heartbeat（Gateway 网关） +# 心跳 (Gateway 网关) -> **Heartbeat 还是 Cron？** 何时使用它们，请参阅[自动化与任务](/automation)。 +> **心跳 vs Cron？** 参见 [Automation & Tasks](/zh-CN/automation)，了解何时使用它们各自更合适。 -Heartbeat 会在主会话中运行**周期性的智能体轮次**，让模型可以 -发现任何需要你注意的内容，同时避免刷屏。 +心跳会在主会话中运行**周期性的智能体轮次**，让模型能够提示任何需要关注的事项，同时不会对你造成刷屏。 -Heartbeat 是一次计划中的主会话轮次——它**不会**创建[后台任务](/automation/tasks)记录。 +心跳是一个计划执行的主会话轮次——它**不会**创建[后台任务](/zh-CN/automation/tasks)记录。 任务记录用于脱离式工作（ACP 运行、子智能体、隔离的 cron 作业）。 -故障排除：[定时任务](/automation/cron-jobs#troubleshooting) +故障排除：[Scheduled Tasks](/zh-CN/automation/cron-jobs#troubleshooting) -## 快速开始（新手） +## 快速开始（初学者） -1. 保持 heartbeats 启用（默认是 `30m`，对于 Anthropic OAuth/token 认证，包括 Claude CLI 复用，则为 `1h`），或者设置你自己的频率。 -2. 在智能体工作区中创建一个小型 `HEARTBEAT.md` 检查清单或 `tasks:` 块（可选，但推荐）。 -3. 决定 heartbeat 消息应发送到哪里（默认是 `target: "none"`；设置 `target: "last"` 可将其路由到上一次联系人）。 -4. 可选：启用 heartbeat 推理内容投递以提高透明度。 -5. 可选：如果 heartbeat 运行只需要 `HEARTBEAT.md`，则使用轻量 bootstrap 上下文。 -6. 可选：启用隔离会话，避免每次 heartbeat 都发送完整对话历史。 -7. 可选：将 heartbeat 限制在活跃时段（本地时间）。 +1. 保持心跳启用状态（默认是 `30m`，对于 Anthropic OAuth/token 认证，包括 Claude CLI 复用，则为 `1h`），或者设置你自己的频率。 +2. 在智能体工作区中创建一个简短的 `HEARTBEAT.md` 清单或 `tasks:` 块（可选但推荐）。 +3. 决定心跳消息应发送到哪里（默认是 `target: "none"`；设置 `target: "last"` 可路由到最近联系对象）。 +4. 可选：启用心跳推理传递以提高透明度。 +5. 可选：如果心跳运行只需要 `HEARTBEAT.md`，可使用轻量级引导上下文。 +6. 可选：启用隔离会话，以避免每次心跳都发送完整的对话历史。 +7. 可选：将心跳限制在活跃时段内（本地时间）。 示例配置： @@ -43,12 +42,12 @@ Heartbeat 是一次计划中的主会话轮次——它**不会**创建[后台 defaults: { heartbeat: { every: "30m", - target: "last", // 显式投递到上一次联系人（默认是 "none"） - directPolicy: "allow", // 默认：允许 direct/私信目标；设为 "block" 可抑制 - lightContext: true, // 可选：仅从 bootstrap 文件注入 HEARTBEAT.md + target: "last", // 显式发送到最近联系对象（默认是 "none"） + directPolicy: "allow", // 默认：允许直接/私信目标；设为 "block" 可抑制发送 + lightContext: true, // 可选：只从引导文件中注入 HEARTBEAT.md isolatedSession: true, // 可选：每次运行都使用全新会话（无对话历史） // activeHours: { start: "08:00", end: "24:00" }, - // includeReasoning: true, // 可选：额外发送单独的 `Reasoning:` 消息 + // includeReasoning: true, // 可选：同时发送单独的 `Reasoning:` 消息 }, }, }, @@ -57,41 +56,33 @@ Heartbeat 是一次计划中的主会话轮次——它**不会**创建[后台 ## 默认值 -- 间隔：`30m`（如果检测到的认证模式是 Anthropic OAuth/token 认证，包括 Claude CLI 复用，则为 `1h`）。设置 `agents.defaults.heartbeat.every` 或按智能体设置 `agents.list[].heartbeat.every`；使用 `0m` 可禁用。 -- 提示正文（可通过 `agents.defaults.heartbeat.prompt` 配置）： +- 间隔：`30m`（或者在检测到的认证模式为 Anthropic OAuth/token 认证时为 `1h`，包括 Claude CLI 复用）。设置 `agents.defaults.heartbeat.every` 或针对每个智能体设置 `agents.list[].heartbeat.every`；使用 `0m` 可禁用。 +- 提示词正文（可通过 `agents.defaults.heartbeat.prompt` 配置）： `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.` -- heartbeat 提示会**原样**作为用户消息发送。系统 - 提示中会包含一个“Heartbeat”部分，并且该运行会在内部被标记。 -- 活跃时段（`heartbeat.activeHours`）会根据已配置时区进行检查。 - 若超出该时间窗口，heartbeat 会跳过，直到窗口内的下一次 tick。 +- 心跳提示词会**原样**作为用户消息发送。只有当默认智能体启用了心跳，并且该运行在内部被标记后，系统提示词才会包含一个“Heartbeat”部分。 +- 当使用 `0m` 禁用心跳时，普通运行也会从引导上下文中省略 `HEARTBEAT.md`，这样模型就不会看到仅供心跳使用的说明。 +- 活跃时段（`heartbeat.activeHours`）会在配置的时区中进行检查。 + 在该时间窗口之外，心跳会被跳过，直到窗口内的下一个 tick。 -## heartbeat 提示的用途 +## 心跳提示词的用途 -默认提示刻意保持宽泛： +默认提示词刻意保持宽泛： -- **后台任务**：“Consider outstanding tasks” 会推动智能体检查 - 后续事项（收件箱、日历、提醒、排队工作），并提示任何紧急内容。 -- **人工签到**：“Checkup sometimes on your human during day time” 会推动其 - 偶尔发送轻量级的“你有什么需要吗？”消息，但通过使用你配置的本地时区来避免夜间刷屏 - （见 [/concepts/timezone](/concepts/timezone)）。 +- **后台任务**：“Consider outstanding tasks” 会推动智能体审查待跟进事项（收件箱、日历、提醒、排队工作），并提示任何紧急内容。 +- **人工检查**：“Checkup sometimes on your human during day time” 会推动偶尔发送轻量级的“你有什么需要吗？”消息，但会根据你配置的本地时区避免夜间刷屏（参见 [/concepts/timezone](/zh-CN/concepts/timezone)）。 -Heartbeat 可以对已完成的[后台任务](/automation/tasks)作出反应，但 heartbeat 运行本身不会创建任务记录。 +心跳可以对已完成的[后台任务](/zh-CN/automation/tasks)作出反应，但心跳运行本身不会创建任务记录。 -如果你希望 heartbeat 执行非常具体的操作（例如“检查 Gmail PubSub -统计信息”或“验证 gateway 健康状态”），请设置 `agents.defaults.heartbeat.prompt`（或 -`agents.list[].heartbeat.prompt`）为自定义正文（会原样发送）。 +如果你希望心跳执行非常具体的事情（例如“检查 Gmail PubSub 统计信息”或“验证 Gateway 网关健康状态”），请将 `agents.defaults.heartbeat.prompt`（或 `agents.list[].heartbeat.prompt`）设置为自定义正文（原样发送）。 ## 响应约定 -- 如果没有任何内容需要注意，请回复 **`HEARTBEAT_OK`**。 -- 在 heartbeat 运行期间，当 `HEARTBEAT_OK` 出现在回复的**开头或结尾**时， - OpenClaw 会将其视为确认。若剩余内容长度**≤ `ackMaxChars`**（默认：300）， - 则会剥离该标记并丢弃回复。 -- 如果 `HEARTBEAT_OK` 出现在回复**中间**，则不会被特殊处理。 -- 对于告警，**不要**包含 `HEARTBEAT_OK`；只返回告警文本。 +- 如果没有任何事项需要关注，请回复 **`HEARTBEAT_OK`**。 +- 在心跳运行期间，如果 `HEARTBEAT_OK` 出现在回复的**开头或结尾**，OpenClaw 会将其视为确认。该标记会被移除；如果剩余内容**≤ `ackMaxChars`**（默认：300），则整条回复会被丢弃。 +- 如果 `HEARTBEAT_OK` 出现在回复的**中间**，则不会被特殊处理。 +- 对于提醒消息，**不要**包含 `HEARTBEAT_OK`；只返回提醒文本。 -在 heartbeat 之外，如果某条消息的开头/结尾出现了多余的 `HEARTBEAT_OK`，也会被剥离 -并记录日志；如果整条消息只有 `HEARTBEAT_OK`，则会被丢弃。 +在心跳之外，如果消息开头或结尾意外出现 `HEARTBEAT_OK`，它会被移除并记录日志；如果消息只有 `HEARTBEAT_OK`，则该消息会被丢弃。 ## 配置 @@ -100,14 +91,14 @@ Heartbeat 可以对已完成的[后台任务](/automation/tasks)作出反应， agents: { defaults: { heartbeat: { - every: "30m", // 默认：30m（0m 表示禁用） + every: "30m", // 默认：30m（0m 禁用） model: "anthropic/claude-opus-4-6", - includeReasoning: false, // 默认：false（可用时投递单独的 Reasoning: 消息） - lightContext: false, // 默认：false；true 时仅保留工作区 bootstrap 文件中的 HEARTBEAT.md - isolatedSession: false, // 默认：false；true 时每次 heartbeat 都在全新会话中运行（无对话历史） + includeReasoning: false, // 默认：false（可用时发送单独的 Reasoning: 消息） + lightContext: false, // 默认：false；true 时仅保留工作区引导文件中的 HEARTBEAT.md + isolatedSession: false, // 默认：false；true 时每次心跳都在全新会话中运行（无对话历史） target: "last", // 默认：none | 可选值：last | none | （核心或插件，例如 "bluebubbles"） - to: "+15551234567", // 可选的渠道特定覆盖 - accountId: "ops-bot", // 可选的多账户渠道 id + to: "+15551234567", // 可选的特定渠道覆盖 + accountId: "ops-bot", // 可选的多账号渠道 id prompt: "Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.", ackMaxChars: 300, // HEARTBEAT_OK 之后允许的最大字符数 }, @@ -116,21 +107,21 @@ Heartbeat 可以对已完成的[后台任务](/automation/tasks)作出反应， } ``` -### 作用域和优先级 +### 作用范围和优先级 -- `agents.defaults.heartbeat` 设置全局 heartbeat 行为。 -- `agents.list[].heartbeat` 会在其上合并；如果任意智能体拥有 `heartbeat` 块，**则只有这些智能体**会运行 heartbeat。 -- `channels.defaults.heartbeat` 为所有渠道设置可见性默认值。 -- `channels..heartbeat` 会覆盖渠道默认值。 -- `channels..accounts..heartbeat`（多账户渠道）会覆盖按渠道设置。 +- `agents.defaults.heartbeat` 设置全局心跳行为。 +- `agents.list[].heartbeat` 会在其之上合并；如果任何智能体有 `heartbeat` 块，则**只有这些智能体**会运行心跳。 +- `channels.defaults.heartbeat` 设置所有渠道的可见性默认值。 +- `channels..heartbeat` 覆盖渠道默认值。 +- `channels..accounts..heartbeat`（多账号渠道）按渠道内账号进行覆盖。 -### 按智能体配置 heartbeat +### 每个智能体的心跳 -如果任意 `agents.list[]` 条目包含 `heartbeat` 块，**则只有这些智能体** -会运行 heartbeat。按智能体配置块会在 `agents.defaults.heartbeat` +如果任意 `agents.list[]` 条目包含 `heartbeat` 块，则**只有这些智能体** +会运行心跳。每个智能体的块会在 `agents.defaults.heartbeat` 之上合并（因此你可以先设置共享默认值，再按智能体覆盖）。 -示例：两个智能体，只有第二个智能体运行 heartbeat。 +示例：两个智能体，只有第二个智能体运行心跳。 ```json5 { @@ -138,7 +129,7 @@ Heartbeat 可以对已完成的[后台任务](/automation/tasks)作出反应， defaults: { heartbeat: { every: "30m", - target: "last", // 显式投递到上一次联系人（默认是 "none"） + target: "last", // 显式发送到最近联系对象（默认是 "none"） }, }, list: [ @@ -159,7 +150,7 @@ Heartbeat 可以对已完成的[后台任务](/automation/tasks)作出反应， ### 活跃时段示例 -将 heartbeat 限制在特定时区的工作时段内： +将心跳限制在某个特定时区的工作时段内： ```json5 { @@ -167,11 +158,11 @@ Heartbeat 可以对已完成的[后台任务](/automation/tasks)作出反应， defaults: { heartbeat: { every: "30m", - target: "last", // 显式投递到上一次联系人（默认是 "none"） + target: "last", // 显式发送到最近联系对象（默认是 "none"） activeHours: { start: "09:00", end: "22:00", - timezone: "America/New_York", // 可选；如果设置了 userTimezone 则使用它，否则使用主机时区 + timezone: "America/New_York", // 可选；如果已设置则使用你的 userTimezone，否则使用主机时区 }, }, }, @@ -179,21 +170,21 @@ Heartbeat 可以对已完成的[后台任务](/automation/tasks)作出反应， } ``` -在该时间窗口之外（美东时间上午 9 点前或晚上 10 点后），heartbeat 会被跳过。窗口内的下一次计划 tick 将正常运行。 +在这个时间窗口之外（美东时间上午 9 点前或晚上 10 点后），心跳会被跳过。窗口内的下一次计划 tick 会正常运行。 -### 24/7 设置 +### 24/7 配置 -如果你希望 heartbeat 全天运行，可以使用以下模式之一： +如果你希望心跳全天运行，可以使用以下模式之一： -- 完全省略 `activeHours`（不限制时间窗口；这是默认行为）。 +- 完全省略 `activeHours`（无时间窗口限制；这是默认行为）。 - 设置全天窗口：`activeHours: { start: "00:00", end: "24:00" }`。 -不要将 `start` 和 `end` 设为相同时间（例如 `08:00` 到 `08:00`）。 -这会被视为零宽度窗口，因此 heartbeat 会始终被跳过。 +不要将 `start` 和 `end` 设置为相同时间（例如 `08:00` 到 `08:00`）。 +这会被视为零宽度窗口，因此心跳会始终被跳过。 -### 多账户示例 +### 多账号示例 -在 Telegram 这类多账户渠道中，使用 `accountId` 指向特定账户： +使用 `accountId` 将消息发送到 Telegram 等多账号渠道中的特定账号： ```json5 { @@ -222,65 +213,64 @@ Heartbeat 可以对已完成的[后台任务](/automation/tasks)作出反应， ### 字段说明 -- `every`：heartbeat 间隔（时长字符串；默认单位 = 分钟）。 -- `model`：heartbeat 运行使用的可选模型覆盖（`provider/model`）。 -- `includeReasoning`：启用后，当可用时也会投递单独的 `Reasoning:` 消息（形式与 `/reasoning on` 相同）。 -- `lightContext`：为 true 时，heartbeat 运行使用轻量 bootstrap 上下文，并且只保留工作区 bootstrap 文件中的 `HEARTBEAT.md`。 -- `isolatedSession`：为 true 时，每次 heartbeat 都会在一个没有先前对话历史的全新会话中运行。使用与 cron `sessionTarget: "isolated"` 相同的隔离模式。可大幅降低每次 heartbeat 的 token 成本。与 `lightContext: true` 组合可获得最大节省。投递路由仍使用主会话上下文。 -- `session`：heartbeat 运行使用的可选会话键。 +- `every`：心跳间隔（时长字符串；默认单位 = 分钟）。 +- `model`：心跳运行时可选的模型覆盖（`provider/model`）。 +- `includeReasoning`：启用后，在可用时也会发送单独的 `Reasoning:` 消息（形式与 `/reasoning on` 相同）。 +- `lightContext`：为 true 时，心跳运行会使用轻量级引导上下文，并且只保留工作区引导文件中的 `HEARTBEAT.md`。 +- `isolatedSession`：为 true 时，每次心跳都会在无先前对话历史的全新会话中运行。使用与 cron `sessionTarget: "isolated"` 相同的隔离模式。可显著降低每次心跳的 token 成本。与 `lightContext: true` 结合使用可获得最大节省。消息传递路由仍使用主会话上下文。 +- `session`：心跳运行的可选会话键。 - `main`（默认）：智能体主会话。 - - 显式会话键（可从 `openclaw sessions --json` 或 [sessions CLI](/cli/sessions) 复制）。 - - 会话键格式：参见[会话](/concepts/session)和[群组](/channels/groups)。 + - 显式会话键（从 `openclaw sessions --json` 或 [sessions CLI](/cli/sessions) 复制）。 + - 会话键格式：参见 [Sessions](/zh-CN/concepts/session) 和 [Groups](/zh-CN/channels/groups)。 - `target`： - - `last`：投递到最后一次使用的外部渠道。 - - 显式渠道：任意已配置渠道或插件 id，例如 `discord`、`matrix`、`telegram` 或 `whatsapp`。 - - `none`（默认）：运行 heartbeat，但**不进行**外部投递。 -- `directPolicy`：控制 direct/私信投递行为： - - `allow`（默认）：允许 direct/私信 heartbeat 投递。 - - `block`：抑制 direct/私信投递（`reason=dm-blocked`）。 -- `to`：可选收件人覆盖（渠道特定 id，例如 WhatsApp 的 E.164 或 Telegram chat id）。对于 Telegram topic/thread，请使用 `:topic:`。 -- `accountId`：多账户渠道的可选账户 id。当 `target: "last"` 时，如果解析出的最后渠道支持账户，则应用该账户 id；否则会被忽略。如果该账户 id 与解析出的渠道中任何已配置账户都不匹配，则会跳过投递。 -- `prompt`：覆盖默认提示正文（不合并）。 -- `ackMaxChars`：`HEARTBEAT_OK` 之后允许的最大字符数。 -- `suppressToolErrorWarnings`：为 true 时，在 heartbeat 运行期间抑制工具错误警告负载。 -- `activeHours`：将 heartbeat 运行限制在某个时间窗口内。对象包含 `start`（HH:MM，含边界；使用 `00:00` 表示一天开始）、`end`（HH:MM，不含边界；允许 `24:00` 表示一天结束）以及可选的 `timezone`。 - - 省略或设为 `"user"`：如果设置了 `agents.defaults.userTimezone` 则使用它，否则回退到主机系统时区。 + - `last`：发送到最近使用的外部渠道。 + - 显式渠道：任意已配置的渠道或插件 id，例如 `discord`、`matrix`、`telegram` 或 `whatsapp`。 + - `none`（默认）：运行心跳，但**不向外部发送**。 +- `directPolicy`：控制直接/私信传递行为： + - `allow`（默认）：允许直接/私信心跳传递。 + - `block`：抑制直接/私信传递（`reason=dm-blocked`）。 +- `to`：可选的接收者覆盖（渠道特定 id，例如 WhatsApp 的 E.164 或 Telegram chat id）。对于 Telegram topic/thread，使用 `:topic:`。 +- `accountId`：多账号渠道的可选账号 id。当 `target: "last"` 时，如果解析出的最近渠道支持账号，则该账号 id 会应用于该渠道；否则会被忽略。如果该账号 id 与解析出的渠道中已配置账号不匹配，则会跳过传递。 +- `prompt`：覆盖默认提示词正文（不做合并）。 +- `ackMaxChars`：`HEARTBEAT_OK` 之后允许的最大字符数，超过则会发送。 +- `suppressToolErrorWarnings`：为 true 时，在心跳运行期间抑制工具错误警告载荷。 +- `activeHours`：将心跳运行限制在某个时间窗口内。对象包含 `start`（HH:MM，含边界；一天开始请使用 `00:00`）、`end`（HH:MM，不含边界；一天结束可使用 `24:00`）以及可选的 `timezone`。 + - 省略或设为 `"user"`：如果已设置，则使用你的 `agents.defaults.userTimezone`，否则回退到主机系统时区。 - `"local"`：始终使用主机系统时区。 - - 任意 IANA 标识符（例如 `America/New_York`）：直接使用；若无效，则回退到上述 `"user"` 行为。 - - 对于有效窗口，`start` 和 `end` 不能相等；相等会被视为零宽度（始终在窗口外）。 - - 超出活跃窗口时，heartbeat 会被跳过，直到窗口内的下一次 tick。 + - 任意 IANA 标识符（例如 `America/New_York`）：直接使用；如果无效，则回退到上面的 `"user"` 行为。 + - 对于活跃窗口，`start` 和 `end` 不得相等；相等会被视为零宽度（始终在窗口外）。 + - 在活跃窗口之外，心跳会被跳过，直到窗口内的下一个 tick。 -## 投递行为 +## 传递行为 -- heartbeat 默认在智能体主会话中运行（`agent::`）， - 或在 `session.scope = "global"` 时使用 `global`。设置 `session` 可覆盖为某个 +- 默认情况下，心跳在智能体的主会话中运行（`agent::`）， + 或者当 `session.scope = "global"` 时使用 `global`。设置 `session` 可覆盖为某个 特定渠道会话（Discord/WhatsApp 等）。 -- `session` 只影响运行上下文；投递由 `target` 和 `to` 控制。 -- 若要投递到特定渠道/收件人，请设置 `target` + `to`。当 - `target: "last"` 时，会使用该会话的最后一个外部渠道进行投递。 -- heartbeat 默认允许向 direct/私信目标投递。设置 `directPolicy: "block"` 可在仍运行 heartbeat 轮次的同时抑制 direct 目标发送。 -- 如果主队列繁忙，heartbeat 会被跳过并在稍后重试。 -- 如果 `target` 未解析到外部目标，该运行仍会发生，但不会 - 发送任何出站消息。 -- 如果 `showOk`、`showAlerts` 和 `useIndicator` 全部被禁用，则运行会在开始前以 `reason=alerts-disabled` 被跳过。 -- 如果只是禁用了告警投递，OpenClaw 仍可以运行 heartbeat、更新时间到期任务时间戳、恢复会话空闲时间戳，并抑制向外发送的告警负载。 -- 仅 heartbeat 的回复**不会**保持会话活跃；最后的 `updatedAt` +- `session` 只影响运行上下文；消息传递由 `target` 和 `to` 控制。 +- 若要发送到特定渠道/接收者，请设置 `target` + `to`。当 + `target: "last"` 时，传递会使用该会话最近的外部渠道。 +- 默认情况下，心跳传递允许直接/私信目标。设置 `directPolicy: "block"` 可在仍然运行心跳轮次的同时抑制向直接目标发送。 +- 如果主队列繁忙，心跳会被跳过，并在稍后重试。 +- 如果 `target` 解析后没有外部目的地，运行仍会发生，但不会 + 发送外发消息。 +- 如果 `showOk`、`showAlerts` 和 `useIndicator` 全部被禁用，则该运行会在前期被跳过，并标记为 `reason=alerts-disabled`。 +- 如果仅禁用了提醒传递，OpenClaw 仍可运行心跳、更新时间已到任务的时间戳、恢复会话空闲时间戳，并抑制向外发送的提醒载荷。 +- 仅心跳的回复**不会**保持会话活跃；最后的 `updatedAt` 会被恢复，因此空闲过期行为保持正常。 -- 脱离式[后台任务](/automation/tasks)可以排入一个系统事件并唤醒 heartbeat， - 以便主会话能尽快注意到某些内容。该唤醒不会让 heartbeat 运行变成后台任务。 +- 脱离式[后台任务](/zh-CN/automation/tasks)可以加入一个系统事件队列并唤醒心跳，以便主会话更快注意到某些事情。这种唤醒不会使心跳运行成为后台任务。 ## 可见性控制 -默认情况下，`HEARTBEAT_OK` 确认会被抑制，而告警内容会被 -投递。你可以按渠道或按账户进行调整： +默认情况下，`HEARTBEAT_OK` 确认会被抑制，而提醒内容会 +正常发送。你可以按渠道或按账号进行调整： ```yaml channels: defaults: heartbeat: showOk: false # 隐藏 HEARTBEAT_OK（默认） - showAlerts: true # 显示告警消息（默认） - useIndicator: true # 发出 indicator 事件（默认） + showAlerts: true # 显示提醒消息（默认） + useIndicator: true # 发出指示器事件（默认） telegram: heartbeat: showOk: true # 在 Telegram 上显示 OK 确认 @@ -288,20 +278,20 @@ channels: accounts: work: heartbeat: - showAlerts: false # 为此账户抑制告警投递 + showAlerts: false # 为该账号抑制提醒发送 ``` -优先级：按账户 → 按渠道 → 渠道默认值 → 内置默认值。 +优先级：每账号 → 每渠道 → 渠道默认值 → 内置默认值。 ### 每个标志的作用 - `showOk`：当模型返回仅包含 OK 的回复时，发送 `HEARTBEAT_OK` 确认。 -- `showAlerts`：当模型返回非 OK 回复时，发送告警内容。 -- `useIndicator`：为 UI 状态表面发出 indicator 事件。 +- `showAlerts`：当模型返回非 OK 回复时，发送提醒内容。 +- `useIndicator`：为 UI 状态界面发出指示器事件。 -如果**三者全部**为 false，OpenClaw 会完全跳过 heartbeat 运行（不会发起模型调用）。 +如果**三者都**为 false，OpenClaw 会完全跳过心跳运行（不调用模型）。 -### 按渠道与按账户示例 +### 每渠道与每账号示例 ```yaml channels: @@ -312,11 +302,11 @@ channels: useIndicator: true slack: heartbeat: - showOk: true # 所有 Slack 账户 + showOk: true # 所有 Slack 账号 accounts: ops: heartbeat: - showAlerts: false # 仅为 ops 账户抑制告警 + showAlerts: false # 仅为 ops 账号抑制提醒 telegram: heartbeat: showOk: true @@ -326,23 +316,28 @@ channels: | 目标 | 配置 | | ---------------------------------------- | ---------------------------------------------------------------------------------------- | -| 默认行为（静默 OK，显示告警） | _(无需配置)_ | -| 完全静默（无消息，无 indicator） | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }` | -| 仅 indicator（无消息） | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }` | -| 仅在某一个渠道显示 OK | `channels.telegram.heartbeat: { showOk: true }` | +| 默认行为（静默 OK，提醒开启） | _(无需配置)_ | +| 完全静默（无消息，无指示器） | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }` | +| 仅指示器（无消息） | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }` | +| 仅在一个渠道中显示 OK | `channels.telegram.heartbeat: { showOk: true }` | -## `HEARTBEAT.md`（可选） +## HEARTBEAT.md（可选） -如果工作区中存在 `HEARTBEAT.md` 文件，默认提示会告诉 -智能体读取它。你可以把它看作你的“heartbeat 检查清单”：小巧、稳定，并且 -适合每 30 分钟都纳入一次。 +如果工作区中存在 `HEARTBEAT.md` 文件，默认提示词会告诉 +智能体读取它。你可以将其视为你的“心跳检查清单”：内容要小而稳定， +并且适合每 30 分钟都包含一次。 -如果 `HEARTBEAT.md` 存在，但实际上是空的（只有空行和 Markdown -标题，例如 `# Heading`），OpenClaw 会跳过 heartbeat 运行以节省 API 调用。 -该跳过会记录为 `reason=empty-heartbeat-file`。 -如果文件缺失，heartbeat 仍会运行，并由模型决定该做什么。 +在普通运行中，只有当默认智能体启用了心跳指引时， +`HEARTBEAT.md` 才会被注入。如果使用 `0m` 禁用心跳频率，或 +设置 `includeSystemPromptSection: false`，它就会从普通引导 +上下文中省略。 -请尽量保持它很小（简短检查清单或提醒），避免提示膨胀。 +如果 `HEARTBEAT.md` 存在但实际上为空（只有空行和 markdown +标题，例如 `# Heading`），OpenClaw 会跳过心跳运行以节省 API 调用。 +这种跳过会报告为 `reason=empty-heartbeat-file`。 +如果文件不存在，心跳仍会运行，并由模型决定该做什么。 + +请保持它很小（简短清单或提醒），以避免提示词膨胀。 示例 `HEARTBEAT.md`： @@ -356,8 +351,8 @@ channels: ### `tasks:` 块 -`HEARTBEAT.md` 还支持一个小型结构化 `tasks:` 块，用于在 heartbeat 内部执行基于间隔的 -检查。 +`HEARTBEAT.md` 还支持一个小型结构化 `tasks:` 块， +用于在心跳内部执行基于间隔的检查。 示例： @@ -377,73 +372,73 @@ tasks: - If nothing needs attention after all due tasks, reply HEARTBEAT_OK. ``` -行为如下： +行为： -- OpenClaw 会解析 `tasks:` 块，并根据每个任务自己的 `interval` 来检查它。 -- 每个 tick 中只会包含**已到期**的任务到 heartbeat 提示中。 -- 如果没有任何任务到期，heartbeat 会被完全跳过（`reason=no-tasks-due`），避免浪费一次模型调用。 -- `HEARTBEAT.md` 中非任务内容会被保留，并在到期任务列表之后追加为额外上下文。 -- 任务上次运行时间戳会存储在会话状态中（`heartbeatTaskState`），因此在正常重启后也能保留间隔信息。 -- 只有在 heartbeat 运行完成其正常回复路径后，任务时间戳才会前进。被跳过的 `empty-heartbeat-file` / `no-tasks-due` 运行不会将任务标记为已完成。 +- OpenClaw 会解析 `tasks:` 块，并根据各任务自己的 `interval` 检查每个任务。 +- 只有**到期**任务会被包含在该次 tick 的心跳提示词中。 +- 如果没有任务到期，心跳会被完全跳过（`reason=no-tasks-due`），以避免浪费一次模型调用。 +- `HEARTBEAT.md` 中的非任务内容会被保留，并作为附加上下文追加在到期任务列表之后。 +- 任务上次运行时间戳存储在会话状态中（`heartbeatTaskState`），因此这些间隔在正常重启后仍会保留。 +- 只有在心跳运行完成其正常回复路径后，任务时间戳才会推进。被跳过的 `empty-heartbeat-file` / `no-tasks-due` 运行不会将任务标记为已完成。 -当你希望一个 heartbeat 文件包含多个周期性检查，而又不想在每个 tick 上都为它们全部付费时，任务模式非常有用。 +当你希望一个心跳文件容纳多个周期性检查，同时又不想每次 tick 都为全部检查付费时，任务模式就很有用。 -### 智能体可以更新 `HEARTBEAT.md` 吗？ +### 智能体可以更新 HEARTBEAT.md 吗？ 可以——如果你要求它这么做。 -`HEARTBEAT.md` 只是智能体工作区中的一个普通文件，因此你可以在普通聊天中告诉 -智能体，例如： +`HEARTBEAT.md` 只是智能体工作区中的一个普通文件，因此你可以在 +普通聊天中对智能体说： -- “Update `HEARTBEAT.md` to add a daily calendar check.” -- “Rewrite `HEARTBEAT.md` so it’s shorter and focused on inbox follow-ups.” +- “更新 `HEARTBEAT.md`，加入每日历检查。” +- “重写 `HEARTBEAT.md`，让它更短，并专注于收件箱跟进事项。” 如果你希望它主动这样做，也可以在 -heartbeat 提示中加入一条显式说明，例如：“If the checklist becomes stale, update HEARTBEAT.md -with a better one.” +心跳提示词中加入一行明确说明，例如：“如果清单已经过时，请更新 HEARTBEAT.md +并替换为更好的版本。” -安全提示：不要把密钥（API key、电话号码、私有 token）放进 -`HEARTBEAT.md`——它会成为提示上下文的一部分。 +安全说明：不要把密钥（API keys、电话号码、私有 token）放进 +`HEARTBEAT.md`——它会成为提示词上下文的一部分。 ## 手动唤醒（按需） -你可以通过以下命令排入一个系统事件并立即触发 heartbeat： +你可以通过以下命令将系统事件加入队列并立即触发心跳： ```bash openclaw system event --text "Check for urgent follow-ups" --mode now ``` -如果多个智能体配置了 `heartbeat`，一次手动唤醒会立即运行这些 -智能体中的每一个 heartbeat。 +如果多个智能体配置了 `heartbeat`，手动唤醒会立即运行其中每个 +智能体的心跳。 -使用 `--mode next-heartbeat` 则会等待下一次计划 tick。 +使用 `--mode next-heartbeat` 可等待下一次计划 tick。 -## 推理内容投递（可选） +## 推理传递（可选） -默认情况下，heartbeat 只会投递最终的“answer”负载。 +默认情况下，心跳只传递最终的“answer”载荷。 如果你希望提高透明度，请启用： - `agents.defaults.heartbeat.includeReasoning: true` -启用后，heartbeat 还会投递一条单独消息，前缀为 +启用后，心跳还会传递一条单独的消息，前缀为 `Reasoning:`（形式与 `/reasoning on` 相同）。当智能体 -管理多个会话/Codex，并且你想知道它为什么决定提醒 -你时，这会很有用——但它也可能泄露比你希望看到的更多内部细节。在群聊中通常应保持关闭。 +正在管理多个会话/codexes，而你希望看到它为何决定提醒 +你时，这会很有帮助——但它也可能泄露比你想要的更多内部细节。建议在群聊中保持关闭。 ## 成本意识 -Heartbeat 会运行完整的智能体轮次。间隔越短，消耗的 token 越多。要降低成本： +心跳会运行完整的智能体轮次。更短的间隔会消耗更多 token。要降低成本： -- 使用 `isolatedSession: true` 以避免发送完整对话历史（每次运行可从约 100K token 降到约 2-5K）。 -- 使用 `lightContext: true` 将 bootstrap 文件限制为仅 `HEARTBEAT.md`。 +- 使用 `isolatedSession: true` 以避免发送完整对话历史（每次运行约从 ~100K tokens 降至 ~2-5K）。 +- 使用 `lightContext: true` 将引导文件限制为只有 `HEARTBEAT.md`。 - 设置更便宜的 `model`（例如 `ollama/llama3.2:1b`）。 -- 保持 `HEARTBEAT.md` 简短。 -- 如果你只想更新内部状态，请使用 `target: "none"`。 +- 保持 `HEARTBEAT.md` 小巧。 +- 如果你只想要内部状态更新，请使用 `target: "none"`。 -## 相关 +## 相关内容 -- [自动化与任务](/automation) — 各种自动化机制的总览 -- [后台任务](/automation/tasks) — 如何跟踪脱离式工作 -- [时区](/concepts/timezone) — 时区如何影响 heartbeat 调度 -- [故障排除](/automation/cron-jobs#troubleshooting) — 调试自动化问题 +- [Automation & Tasks](/zh-CN/automation) — 所有自动化机制概览 +- [Background Tasks](/zh-CN/automation/tasks) — 脱离式工作如何被跟踪 +- [Timezone](/zh-CN/concepts/timezone) — 时区如何影响心跳调度 +- [Troubleshooting](/zh-CN/automation/cron-jobs#troubleshooting) — 自动化问题调试