Session 01
Agent 架构总览
这节建立总地图：Claude Code、OpenClaw、Hermes Agent 不只是三个产品，而是三种 agent 设计取向。先把 agent app、agent runtime、agent harness、tool system、workspace、memory、orchestration 分清。
1. 训练目标
本页要练会：能用同一套组件语言描述 Claude Code、OpenClaw、Hermes：谁拥有 run loop，谁负责上下文，工具怎么执行，状态在哪里，权限边界在哪里。
主要依据：Claude Code overview / OpenClaw agent runtimes / Hermes docs。
2. 三项目对照
| 维度 | Claude Code | OpenClaw | Hermes Agent |
|---|---|---|---|
| 核心定位 | Agentic coding tool / Agent SDK，围绕代码库、命令、git 和开发工作流。 | 自托管 Gateway + embedded runtime，围绕个人 assistant、多 channel 和本地 workspace。 | 开源 terminal/desktop agent，强调多 provider、工具、sandbox、记忆和自动化。 |
| 学习入口 | 看工具、CLAUDE.md、MCP、hooks、subagents、权限。 | 看 Gateway、agentDir、workspace、context、skills、multi-agent routing。 | 看 provider、tools、terminal backend、memory providers、plugins、delegation。 |
| 架构风险 | 代码库权限、命令执行、上下文漂移、自动改错。 | 自托管权限、channel routing、workspace 隔离、skills 注入。 | 长期记忆污染、工具面过宽、后台任务和 sandbox 边界。 |
3. 组件机制
| 机制 | 解释 |
|---|---|
| Agent app | 用户看到的产品形态，如 coding CLI、聊天网关、桌面 agent。它可以包装一个或多个 runtime。 |
| Agent runtime | 拥有一次完整 agent loop 的执行单元：组装上下文、调用模型、处理工具、保存状态、返回结果。 |
| Agent harness | 把多个 runtime、工具、权限、状态、协作和生命周期统一管理的平台层。HiClaw 更接近这个层。 |
| Control surface | 用户或平台控制 agent 的地方：permission mode、hooks、policy、workspace、channels、provider config。 |
4. 失败模式
| 失败模式 | 为什么危险 |
|---|---|
| 把 product 当 architecture | 只说 Claude Code 很好用、OpenClaw 能自托管、Hermes 工具多，但说不出 run loop 和状态边界。 |
| 把 runtime 和 provider 混为一谈 | 换模型不等于换 agent runtime；provider 提供模型，runtime 决定上下文、工具和状态。 |
| 忽略权限控制面 | agent 能运行命令、改文件、读记忆时，权限和审计必须进入架构图。 |
5. 架构练习
- 画一张三层图：产品层、runtime 层、工具/状态层。把 Claude Code、OpenClaw、Hermes 填进去。
- 回答：为什么 HiClaw 和 OpenClaw/Hermes/Claude Code 不在同一抽象层？
- 给一个“企业内部代码助手”场景，判断更接近 Claude Code 型、OpenClaw 型还是 Hermes 型。
6. 知识展开
上面的卡片是索引，点击后跳到对应的详细解释。阅读时不要只记名词，要同时记住组件边界、为什么需要它、三个项目怎么体现，以及你能用什么问题自检。
Agent runtime
拥有 run loop 的执行单元，负责把输入、上下文、模型调用、工具调用和停止条件连成闭环。
Control plane
管理配置、权限、生命周期、路由和多 agent 关系的控制层，不等于模型推理本身。
Workspace
agent 读写任务文件、临时产物、上下文材料和执行结果的工作目录或工作域。
Tool surface
模型可调用能力的集合，包括文件、shell、浏览器、搜索、MCP、插件和自定义技能。
Observability
对 agent 行为进行 trace、回放、指标归因和审计的能力。
Detailed Concepts
| 概念 | 是什么 | 为什么重要 | 项目对照 | 自检问题 |
|---|---|---|---|---|
| Agent runtime | 拥有 run loop 的执行单元，负责把输入、上下文、模型调用、工具调用和停止条件连成闭环。 | 没有 runtime 视角时，容易把 agent 理解成一次 prompt；真正的系统问题都发生在循环、状态和工具回写之间。 | Claude Code 展示 coding agent 的产品化 runtime；OpenClaw 文档明确 agent loop；Hermes 以 terminal/desktop agent 暴露工具驱动 runtime。 | 能否画出一次任务从用户输入到工具结果回写的闭环？ |
| Control plane | 管理配置、权限、生命周期、路由和多 agent 关系的控制层，不等于模型推理本身。 | 多 agent 系统一旦有创建、隔离、回收、审计需求，就需要控制面，否则会变成脚本拼接。 | HiClaw 是 harness/control-plane 参照；OpenClaw 的 Gateway/Channel 有控制面意味；Hermes 更偏本地 agent app。 | 能否说清哪些逻辑应该在控制面，而不是交给模型自由决定？ |
| Workspace | agent 读写任务文件、临时产物、上下文材料和执行结果的工作目录或工作域。 | workspace 决定上下文可见性和副作用边界，是安全、恢复和协作的基础。 | Claude Code 面向代码仓库；OpenClaw 强调 per-agent workspace/agentDir；Hermes 通过文件和 terminal backend 接触本地环境。 | 能否说明 workspace 与 memory 的边界？ |
| Tool surface | 模型可调用能力的集合，包括文件、shell、浏览器、搜索、MCP、插件和自定义技能。 | 工具越强，副作用越大；工具设计要同时考虑能力、权限、参数校验和审计。 | Claude Code 有 tools/MCP/hooks/skills；OpenClaw 有 skill/plugin runtime；Hermes 有广泛内置工具和插件体系。 | 能否为高风险工具设计审批或沙箱策略？ |
| Observability | 对 agent 行为进行 trace、回放、指标归因和审计的能力。 | 没有观测就无法定位“模型错了、上下文错了、工具错了、权限错了、还是编排错了”。 | Claude Agent SDK 可接 OpenTelemetry；OpenClaw 需要从 Gateway/session 观察；Hermes 可从 tool log、terminal log、memory provider 观察。 | 能否定义一次 agent 失败排障需要保留的最小 trace？ |