openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-07 23:54:16 +00:00
parent 7222307211
commit f4eb5203c5
2 changed files with 230 additions and 249 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

126
docs/zh-CN/concepts/system-prompt.md
View File

@ -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 可以为子智能体渲染更小的系统提示词。运行时会为
</available_skills>
```
这样可以保持基础提示词较小，同时仍支持有针对性的 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`（只有在无法访问时才询问用户）。

353
docs/zh-CN/gateway/heartbeat.md
View File

@ -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 | <channel id>（核心或插件，例如 "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.<channel>.heartbeat` 会覆盖渠道默认值。
- `channels.<channel>.accounts.<id>.heartbeat`（多账户渠道）会覆盖按渠道设置。
- `agents.defaults.heartbeat` 设置全局心跳行为。
- `agents.list[].heartbeat` 会在其之上合并；如果任何智能体有 `heartbeat` 块，则**只有这些智能体**会运行心跳。
- `channels.defaults.heartbeat` 设置所有渠道的可见性默认值。
- `channels.<channel>.heartbeat` 覆盖渠道默认值。
- `channels.<channel>.accounts.<id>.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，请使用 `<chatId>:topic:<messageThreadId>`。
- `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，使用 `<chatId>:topic:<messageThreadId>`。
- `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:<id>:<mainKey>`），
或在 `session.scope = "global"` 时使用 `global`。设置 `session` 可覆盖为某个
- 默认情况下，心跳在智能体的主会话中运行（`agent:<id>:<mainKey>`），
或者当 `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) — 自动化问题调试