Agent 循环
Agent 循环（Agent Loop）是 OpenClaw 处理每条消息的核心机制。它实现了 ReAct（Reasoning + Acting）模式——AI 不只是回答问题，而是通过推理 → 行动 → 观察的循环，自主完成复杂任务。
核心区别
OpenClaw 和传统 AI 的本质区别：
| 维度 | 传统 AI（ChatGPT） | OpenClaw |
|---|---|---|
| 交互模式 | 一问一答 | 任务驱动 |
| 工具使用 | 模拟或建议 | 真实调用执行 |
| 错误处理 | 需要用户手动修复 | 自动重试和调整 |
| 记忆 | 单次对话 | 持久化长期记忆 |
| 运行方式 | 在线服务 | 本地运行 / 自托管 |
核心区别：ChatGPT 是顾问，OpenClaw 是执行者。
ReAct 循环流程
收到消息
↓
构建上下文（历史 + 系统提示词 + 工作区文件 + 记忆）
↓
调用 AI 模型（推理 Reasoning）
↓
模型输出
├── 文本回复 → 发送给用户，循环结束
└── 工具调用（行动 Acting）
↓
执行工具
↓
将结果附加到上下文（观察 Observation）
↓
再次调用模型 → 继续推理...工具调用可以多轮进行，直到模型认为已有足够信息生成最终回复。整个过程中 Agent 会进行自我检查：结果是否正确？格式是否符合要求？如果某一步失败，会自动重试或调整策略。
典型执行流程
以「生成周报并发送给团队」为例：
- 任务分解：读取本周 Git 提交 → 获取任务完成情况 → 生成周报 → 发送邮件
- 逐步执行：读取 Git log 发现 23 次提交 → 调用 Jira API 获取 5 个已完成任务
- 生成结果：使用 Markdown 格式生成周报 → 验证收件人地址
- 自检发送：检查周报是否完整 → 发送邮件 → 返回状态
四大核心工具
OpenClaw 的设计哲学是 Unix 风格的极简主义——只有 4 个核心基础工具：
| 工具 | 说明 |
|---|---|
| Read | 读取文件内容 |
| Write / Edit | 写入或编辑文件 |
| Bash | 执行 shell 命令 |
| Browser | 浏览器自动化操作 |
通过这 4 个工具的组合，加上 Skills 扩展，OpenClaw 可以完成几乎任何任务。
多 Agent 协作
OpenClaw 支持多 Agent 架构，主 Agent 可以派出 Sub-agent 并行执行子任务：
| 场景 | 适合拆分 | 适合单一 Agent |
|---|---|---|
| 代码库搜索 | ✅ 低耦合 | |
| 信息收集 | ✅ 各自独立 | |
| 核心编码 | ✅ 需完整上下文 | |
| 架构设计 | ✅ 高耦合 |
Token 成本
Anthropic 的实践数据：普通聊天消耗 1x Token，单 Agent 约 4x，多 Agent 系统达 15x。拆分前权衡成本和收益。
系统提示词
系统提示词通过工作区文件定义 Agent 的行为、身份和约束。详见 系统提示词 章节。
记忆机制
OpenClaw 支持多层记忆系统。详见 记忆系统 章节。
自主任务模式（目标驱动）
指令驱动 vs 目标驱动
OpenClaw 的 Agent 支持两种工作模式：
| 维度 | 指令驱动 | 目标驱动 |
|---|---|---|
| 谁拆解任务 | 你 | Agent |
| 谁更新进度 | 你手动 | Agent 自动 |
| 调度机制 | 你手动触发 | Heartbeat 定时推醒 |
| 状态文件 | temp/xxx-plan.md | AUTONOMOUS.md + memory/tasks-log.md |
| 适用场景 | 步骤已知的任务 | 目标明确但步骤不明的任务 |
| 风险等级 | 低（你全程控制） | 需要安全边界 |
指令驱动就是中级用法：你手动创建 temp/xxx-plan.md，列好步骤，Agent 按顺序走，你手动打勾更新进度。
目标驱动是进阶用法：你只说一句「调研 OpenClaw 社区最近一个月的热门讨论」，Agent 自己决定要搜哪些平台、怎么筛选、怎么分析、产出什么格式的报告。
工作原理
目标驱动不是一个「功能」，是一种「模式」。Agent loop 本身是单次执行的——接收输入、推理、执行工具、回复。
循环是你在应用层搭出来的：用 Heartbeat 提供驱动力，用 AGENTS.md 规则提供行为逻辑，用文件系统维护状态。类似 AutoGPT、BabyAGI 做的事，但不需要引入任何外部框架——OpenClaw 自带的基础设施就够了。
三个文件搭出自主任务系统
需要配置三个东西：AUTONOMOUS.md 管目标状态、AGENTS.md 管行为规则、HEARTBEAT.md 管定时触发。
第一步：创建 AUTONOMOUS.md
重要
AUTONOMOUS.md 不是官方 workspace 文件。OpenClaw 系统不会自动识别它——你得通过 AGENTS.md 规则和 HEARTBEAT.md checklist 告诉 Agent 去读。没有这步引导，这个文件就是个摆设。
# 自主任务系统
## 当前目标
### 目标1: OpenClaw 社区趋势调研
- 描述: 调研 OpenClaw 社区最近一个月的热门讨论，产出趋势报告
- 优先级: 高
- 截止时间: 今天
- 成功标准:
- 找到至少 10 个热门讨论话题
- 分析每个话题的关键点
- 产出 markdown 格式的趋势报告
## 待办任务（Agent 自动生成）
（Agent 会在这里填充子任务）
## 已完成任务
（记录在 memory/tasks-log.md）第二步：在 AGENTS.md 添加自主任务规则
## 自主任务模式（目标驱动）
当 AUTONOMOUS.md 中有未完成目标时，进入自主任务模式：
### 工作流程
1. 读取目标：读取 AUTONOMOUS.md 中的当前目标，理解描述和成功标准
2. 拆解任务：将目标拆解为 3-5 个可执行子任务，写入 AUTONOMOUS.md 的待办部分
3. 执行任务：按优先级逐个执行，每完成一个追加到 memory/tasks-log.md
4. 评估完成度：检查是否满足成功标准，未完成则生成新子任务
5. 失败处理：子任务失败时分析原因、调整策略，最多重试 3 次
### 安全限制
- 最多执行 20 个子任务（防止无限循环）
- 连续 3 次失败，暂停并报告用户
- 每个 sub-agent 设置 runTimeoutSeconds
### 日志格式
所有执行记录追加到 memory/tasks-log.md:
YYYY-MM-DD HH:MM - [任务名] - 状态: 成功/失败 - 结果摘要第三步：配置 HEARTBEAT.md
# Heartbeat Checklist
- [ ] 读取 AUTONOMOUS.md，检查是否有未完成的目标
- [ ] 如果有待执行的子任务，选择下一个执行
- [ ] 如果今天的任务尚未生成，根据目标生成今日任务
- [ ] 检查 memory/tasks-log.md，确认是否有失败任务需要重试
- [ ] 清理超过 7 天的临时文件Workspace 文件全表
在折腾自主任务之前，先搞清楚 OpenClaw 的 workspace 文件有哪些：
官方 workspace 文件（系统自动识别和处理）：
| 文件 | 作用 |
|---|---|
AGENTS.md | 定义 Agent 操作指令和工作流程 |
SOUL.md | 定义 Agent 人格和行为准则 |
USER.md | 定义用户偏好和上下文 |
IDENTITY.md | 定义 Agent 身份信息 |
TOOLS.md | 定义可用工具和使用方式 |
HEARTBEAT.md | 心跳检查列表，daemon 定时读取 |
BOOT.md | 启动时执行的初始化指令 |
BOOTSTRAP.md | 工作区引导配置 |
MEMORY.md | 长期记忆存储 |
memory/YYYY-MM-DD.md | 按日期分的记忆文件 |
skills/ | Skill 目录 |
canvas/ | 画布文件 |
社区自定义文件（系统不认识，需要你通过 AGENTS.md 规则告诉 Agent 去读）：
| 文件 | 作用 | 来源 |
|---|---|---|
AUTONOMOUS.md | 存储自主任务目标和待办 | 社区最佳实践 |
memory/tasks-log.md | 任务执行日志（只追加不修改） | 社区最佳实践 |
关键区别：HEARTBEAT.md 是官方的，Gateway 心跳时自动读取。AUTONOMOUS.md 不是官方的，你不在 AGENTS.md 里写规则让 Agent 去读，它就当这个文件不存在。
常见坑
坑 1：Heartbeat 的 token 成本
每次心跳消耗大约 17-21 万 tokens（长 session 中）。即使 Agent 没有实际任务要做，心跳本身就有成本。
解决：用 Dual-model 策略——心跳用便宜模型（Haiku），主会话用贵模型（Opus 或 Sonnet）。同时合理设置心跳频率，不需要每 5 分钟一次。
坑 2：目标太模糊导致拆解跑偏
「让 OpenClaw 更好用」这种目标，Agent 不知道从哪下手。目标必须有明确的成功标准。「找到至少 10 个热门讨论」比「调研社区讨论」好得多。
坑 3：Agent 分析瘫痪——一直在规划不执行
Agent 花十分钟拆解、分析、列举潜在风险，还没动手干活。
解决：在 AGENTS.md 里加规则——「拆解任务不超过 5 分钟，先执行再调整」。敏捷模式比完美计划更适合 Agent。
坑 4：sub-agent 工具集受限
spawn 出来的 sub-agent 和 main session 的能力是不对等的：
- 不能嵌套 spawn — sub-agent 默认不能再创建孙子 Agent
- 没有 session tools — sub-agent 默认拿不到 sessions_send 等通信工具
- context 不含基础文件 — sub-agent 的上下文不包含 SOUL.md、IDENTITY.md 这些基础 workspace 文件
解决：在 sessions_spawn 时通过 prompt 参数手动传入关键规则。设计架构时不要假设 sub-agent 拥有和 main session 一样的能力。