OpenClaw学习总结_I_核心架构系列_AgentLoop详解
I. 核心架构 - 2. Agent Loop
📍 课程位置
阶段：I. 核心架构
课序：第 2 课
前置知识：I-1. Gateway 架构
后续课程：I-3. Context 管理
🎯 本课核心问题
如果你问我：“OpenClaw 的 Agent 是怎么工作的？一条消息进来后，它是怎么处理的？”
我会这样回答：Agent 有一个完整的工作循环，叫Agent Loop，像工厂的流水线，一条消息进来后，会经过 6 个阶段的处理。
📚 你需要理解的六个阶段
阶段 1：Message（消息接收）
发生了什么：
- Gateway 收到一条消息
- 转发给 Agent
- Agent 开始处理
类比：
- 工厂门口收到了一个订单
- 订单被放到传送带上
关键点：
- 消息来源：可以是 WhatsApp、Telegram、Discord 等
- 消息格式：被 Gateway 标准化后发送
- 消息内容：文本、图片、文件等都行
阶段 2：Context Assembly（上下文组装）
发生了什么：
- Agent 把"需要知道的信息"组装起来
- 包括：系统提示词、对话历史、可用工具
类比：
- 工厂里，工人开始准备
- 查看订单要求（系统提示词）
- 翻看之前的加工记录（对话历史）
- 看看手边有哪些工具（可用工具）
关键点：
- 这个阶段决定 Agent “知道什么”
- 上下文太长会有成本问题
- 可以通过 Compaction 优化（后面会讲）
阶段 3：Model Inference（模型推理）
发生了什么：
- 把组装好的上下文发给 AI 模型
- 模型思考并决定：回复什么？用什么工具？
类比：
- 工人根据订单要求、历史记录、工具清单
- 思考：“我应该怎么做？”
- 决定：“我需要查一下库存，然后用原材料加工”
关键点：
- 这个阶段调用外部 AI 服务（如 Claude）
- 模型可以调用工具（Tool Calling）
- 可以设置多个模型作为备份（Model Failover）
阶段 4：Tool Execution（工具执行）
发生了什么：
- 如果模型决定需要调用工具，就执行
- 工具可以是：发消息、读文件、执行命令、浏览器操作等
类比：
- 工人去仓库查库存
- 或者操作机器加工产品
- 或者叫其他工人帮忙
关键点：
- 工具执行后，结果返回给模型
- 模型根据结果继续推理
- 可以多次执行工具（循环）
阶段 5：Streaming（流式输出）
发生了什么：
- 把回复内容实时显示给用户
- 不是等全部生成完再显示，而是一个字一个字地显示
类比：
- 工厂流水线上的产品
- 完成后不是一次性交付
- 而是在生产过程中就展示给客户看
关键点：
- 用户体验更好（更快看到回复）
- 可以显示"正在输入"状态
- 有两种模式：Block（等全部）和 Preview（实时）
阶段 6：Persistence（持久化）
发生了什么：
- 把对话内容保存到磁盘
- 这样下次对话时，Agent 知道"之前聊过什么"
类比：
- 工厂把这次的加工记录存档
- 下次有类似订单，可以参考之前的做法
关键点：
- 保存位置：
~/.openclaw/agents/<agentId>/sessions/ - 格式：JSONL（每行一个 JSON）
- Session 会被定期压缩（Compaction）来节省空间
🔄 完整的 Agent Loop 流程图
Message（消息进来） ↓ Context Assembly（组装上下文） ↓ Model Inference（AI 思考） ↓ ├─ 需要工具？ → Tool Execution（执行工具） │ ↓ │ 回到 Model Inference（继续思考） │ ↓ └─ 不需要工具？ ↓ Streaming（流式输出给用户） ↓ Persistence（保存到磁盘） ↓ 结束，等待下一条消息💡 这个设计的关键点
1. 可扩展性
- 每个阶段都可以干预和定制
- 就像工厂流水线的每个环节都可以调整
- 通过Hooks可以在关键点插入自定义逻辑
2. 上下文成本
- 上下文不是免费的
- token 需要花钱
- 所以需要** Compaction** 来压缩（后面会讲）
3. 工具调用
- Agent 不是只"说话"，还能"做事"
- 可以执行命令、读写文件、控制浏览器
- 通过 Tool Calling 实现
4. 会话管理
- 每次对话都会被保存
- 下次继续时可以"记得"
- 但如果太长，会压缩（Compaction）
🔧 实战：看看 Agent Loop 在做什么
查看当前会话
# 查看 Agent 的会话列表openclaw sessions list# 查看某个会话的详情openclaw sessions show<sessionId># 查看对话历史cat~/.openclaw/agents/main/sessions/*.jsonl查看日志
# 实时查看 Agent 处理的日志openclaw logs--follow|grep"agent"# 会显示每个阶段的详细信息调试工具调用
# 如果你想看 Agent 调用了什么工具# 查看日志中的 tool_call 相关内容openclaw logs|grep-itool⚠️ 常见陷阱
| 陷阱 | 表现 | 原因 | 解决 |
|---|---|---|---|
| 上下文太长 | “Token limit exceeded” | 对话历史太长 | 使用 Compaction |
| 工具执行失败 | “Tool execution failed” | 工具参数错误或权限问题 | 检查工具配置 |
| 模型超时 | “Request timeout” | 模型响应太慢 | 设置更长的超时时间 |
| 死循环 | Agent 不停调用同一个工具 | 工具逻辑问题 | 检查工具设计 |
📝 学习心得
我学这一课时的体会
我之前以为 Agent 就是"收到消息 → 回复消息"的简单过程。
学完后才发现，中间有这么多复杂的阶段！尤其是：
Tool Execution 循环- 模型可以多次调用工具，这让我想到"如果工具设计不好，可能会陷入死循环"
Context 成本- 之前没意识到，每次对话都在"累积成本"，Compaction 是必须的
Hooks 的强大- 原来可以在每个阶段插入自定义逻辑，这为自动化提供了无限可能
与其他课程的关联
- 前置课程：Gateway 架构 - 消息从 Gateway 来到 Agent
- 后续课程：Context 管理 - 详细讲阶段 2
- 配合课程：Session 管理 - 阶段 6 的持久化
- 配合课程：Compaction - 优化阶段 2 和 6
✅ 你现在应该理解的
- 说出 Agent Loop 的 6 个阶段
- 解释每个阶段在做什么
- 画出完整的流程图
- 知道 Context 成本是什么
- 理解工具调用和循环
📚 快速参考表
| 阶段 | 名称 | 做什么 |
|---|---|---|
| 1 | Message | 接收消息 |
| 2 | Context Assembly | 组装上下文（系统提示词+历史+工具） |
| 3 | Model Inference | AI 模型思考 |
| 4 | Tool Execution | 执行工具（如需要） |
| 5 | Streaming | 流式输出回复 |
| 6 | Persistence | 保存对话到磁盘 |
🔗 相关资源
官方文档：
- Agent Loop：https://docs.openclaw.ai/concepts/agent-loop
- Hooks：https://docs.openclaw.ai/automation/hooks
- Session：https://docs.openclaw.ai/concepts/session
相关课程：
- 上一课：I-1. Gateway 架构
- 下一课：I-3. Context 管理
📊 本课总结
最关键的 3 点：
6 阶段流水线
- Message → Context → Model → Tool → Stream → Persist
- 每个阶段都可以定制和干预
工具调用的循环
- 模型可以多次调用工具
- 需要注意不要陷入死循环
为后续课程打基础
- Context 管理（阶段 2）
- Session 管理（阶段 6）
- Compaction（优化 2 和 6）
现在你应该理解了 Agent 是怎么"思考"的。下一课会讲它"思考时需要什么"（Context 管理）。