从 OpenClaw 和 Hermes 看成熟 Agent 框架怎么设计-夜雨聆风

从 OpenClaw 和 Hermes 看成熟 Agent 框架怎么设计

成熟 Agent 框架的价值，不在于“支持多少能力”，而在于它把模型调用、工具执行、会话状态、插件权限和安全边界放到了什么位置。

读 OpenClaw 和 Hermes 时，最值得追问的不是“它有没有工具调用、记忆、插件、MCP”，而是这些能力进入真实产品之后，框架如何回答下面这些问题：

谁来决定工具能不能被调用？
工具执行在哪个权限边界里发生？
会话如何恢复？
上下文如何压缩？
记忆什么时候写入？
插件能获得多大权限？
多渠道消息怎么映射成稳定 session？
出了问题能不能解释？

本文分析的两个仓库是：

框架	仓库	本地 HEAD
OpenClaw	`openclaw/openclaw`	`1b076608`
Hermes Agent	`NousResearch/hermes-agent`	`a8c8629`

它们都不是简单 demo。OpenClaw 本地浅克隆约 2 万个文件，测试文件 6500+；Hermes 约 5600 个文件，测试文件接近 2000。这样的规模说明：它们已经在处理真实 Agent 产品的复杂度。

1. 先给结论

OpenClaw 和 Hermes 都是个人 AI assistant 方向，但气质不同。

OpenClaw 更像一个 local-first 的多渠道 AI Gateway。它的重点是：

Gateway
+ channel integrations
+ plugin capability model
+ agent runtime
+ tool policy
+ companion apps / nodes

Hermes 更像一个 Python Agent runtime 加上工具、记忆、技能和消息网关。它的重点是：

AIAgent
+ tool registry / toolsets
+ memory manager
+ skills
+ session lifecycle
+ terminal backends
+ messaging gateway

如果把二者放到前面六个阶段的学习体系里：

学习阶段	OpenClaw 对应点	Hermes 对应点
Phase1 Agent loop	内置 embedded agent runner	`AIAgent` 和 conversation loop
Phase2 RAG / Memory	context engine / memory plugins	memory manager / session search
Phase3 Frameworks	runtime harness / provider abstraction	provider transports / toolsets
Phase4 MCP / Tools	plugin SDK / MCP tools / tool policy	MCP tools / registry / tool search
Phase5 Production	Gateway daemon / health / tests	Gateway / Docker / session recovery
Phase6 Capstone	多渠道知识助手平台参考	可运行的长期助手内核参考

一句话：

OpenClaw值得学“平台边界”。
Hermes值得学“Agent内核”。

2. OpenClaw：重点不是 Agent，而是 Gateway 平台

OpenClaw README 把自己描述成 personal AI assistant，但从源码结构看，它更大的价值在 Gateway 和插件平台。

它的目录非常平台化：

src/gateway/
src/agents/
src/channels/
src/plugin-sdk/
src/plugins/
src/security/
src/sessions/
src/tools/
extensions/
packages/
ui/
apps/

这不是一个“写个 agent loop 调工具”的项目，而是一个把 Agent 放进真实消息渠道、设备节点、插件生态和本地运行环境里的平台。

2.1 OpenClaw 的核心链路

可以把 OpenClaw 的主链路理解成：

外部消息/ CLI /App
->Gateway
-> session routing
-> agent runtime selection
-> prompt / context / skill / plugin surface
-> model provider
-> tool policy
-> tool execution
-> reply payload
-> channel delivery

关键源码入口包括：

关注点	文件
agent runtime 架构说明	`docs/agent-runtime-architecture.md`
embedded agent run 入口	`src/agents/embedded-agent-runner/run.ts`
工具面装配	`src/agents/agent-tools.ts`
Gateway 启动	`src/gateway/boot.ts`
插件架构	`docs/plugins/architecture.md`

其中 src/agents/embedded-agent-runner/run.ts 是主运行入口之一，里面能看到模型选择、runtime plugin 加载、context engine、compaction、failover、attempt 执行等逻辑。这个文件很大，但它说明 OpenClaw 的 Agent runtime 已经不是单轮 loop，而是一个带故障恢复、上下文维护、插件运行时和多模型策略的执行器。

2.2 OpenClaw 最值得学的是 capability ownership

OpenClaw 的插件文档里有一个非常重要的设计：插件不是随便挂工具，而是注册 capability。

比如：

text inference
embeddings
speech
realtime transcription
image generation
video generation
web fetch
web search
channel / messaging
gateway discovery

这个设计背后的思想是：

plugin = ownership boundary
capability = core contract

一个 OpenAI 插件可以同时拥有 text inference、speech、image generation；一个 channel 插件可以拥有自己的消息接入和发送动作。Core 不应该到处 import 某个供应商的实现，而应该消费能力契约。

这对自己的项目很有启发。

我们在 Phase4 写 MCP Server 时，更多是在想：

我要暴露哪些 tools？

但 OpenClaw 提醒我们，成熟一点的系统要继续问：

这个能力属于谁？
它的生命周期谁负责？
它的配置 schema 谁定义？
它的健康检查谁暴露？
多个实现冲突时谁优先？

这就是从“工具集合”走向“平台能力”的差别。

2.3 OpenClaw 的工具面不是静态列表

OpenClaw 的工具装配在 src/agents/agent-tools.ts。文件开头就说明它负责构建 effective tool surface：

core tools
shell tools
channel tools
OpenClaw tools
plugin tools
ToolSearch tools

然后再叠加：

sandbox
profile
provider
sender
group
sub-agent policy

这说明工具不是“注册了就能用”。真正运行时会根据当前会话、渠道、用户、sandbox、agent profile、插件状态动态计算工具面。

这是 Agent 工程里非常关键的一点：

工具列表不是能力清单，而是权限结果。

如果以后把自己的学习项目扩展成可给别人用的 Agent 服务，也应该避免“所有工具全局可见”。更合理的是：

tool registry
-> session scope
-> user role
-> data permission
-> sandbox mode
->final tool surface

2.4 OpenClaw 的风险：native plugin 是进程内信任边界

OpenClaw 文档说得很直接：native plugin 运行在 Gateway 进程内，不是 sandboxed。插件 bug 可能 crash Gateway，恶意插件等价于进程内任意代码执行。

这是一个成熟项目的诚实边界。

它不是“缺陷”，而是一个架构取舍：进程内插件带来更低延迟、更强集成、更好的开发体验，但安全边界就必须依赖插件来源、allowlist、安装路径和使用者信任。

所以学习 OpenClaw 时不能只学插件怎么写，还要学它如何描述信任模型：

trusted installed plugin
untrusted inbound message
trusted operator
sandboxed non-main session
host-first main session

这些概念比 API 更重要。

3. Hermes：重点是 Python Agent 内核和自我改进

Hermes 的 README 重点强调 self-improving、skills、memory、tool-calling、messaging gateway。源码也基本符合这个定位。

它的关键文件非常集中：

关注点	文件
Agent 主类	`run_agent.py`
工具定义和过滤	`model_tools.py`
工具集合	`toolsets.py`
工具注册表	`tools/registry.py`
工具执行	`agent/tool_executor.py`
记忆管理	`agent/memory_manager.py`
会话状态	`hermes_state.py`
Gateway 会话文档	`docs/session-lifecycle.md`

Hermes 的代码风格和 OpenClaw 不一样。OpenClaw 更像大型 TypeScript 平台，边界更类型化；Hermes 更像不断演进出来的 Python 产品内核，很多东西务实、直接、可改。

3.1 Hermes 的 Agent 主类很重

run_agent.py 里的 AIAgent 是核心类。它负责接收大量初始化参数：

provider / model / api key
toolsets
session id
callbacks
reasoning config
platform / user / chat / thread
memory
checkpoint
credential pool

它再通过 forwarder 把初始化、conversation loop、tool execution 拆到其他模块。

这说明项目已经意识到主文件过重，所以开始把逻辑外移，比如：

agent.agent_init
agent.conversation_loop
agent.tool_executor
agent.memory_manager
agent.codex_runtime

但从阅读体验看，Hermes 仍然有明显“大内核”特征。对学习者来说，这恰恰是一个现实案例：

Agent项目最容易长成一个巨大的 run_agent.py。

如果自己写系统，要尽早把这些边界拆开：

AgentConfig
ToolRuntime
MemoryRuntime
SessionStore
ModelTransport
GatewayAdapter

不要等到几千行之后再拆。

3.2 Hermes 的工具系统很适合学习

Hermes 的 tools/registry.py 明确说明：每个工具文件通过 registry.register() 自注册 schema、handler、toolset membership 和 availability check。

然后 model_tools.py 负责：

discover builtin tools
按 enabled / disabled toolsets 过滤
生成模型可见的 tool definitions
对 plugin / MCP 工具做 toolsearch / tooldescribe / tool_call 延迟暴露
执行 pretoolcall / posttoolcall hook
分发 function call

这套设计非常适合学习“工具系统怎么从 demo 变成产品”。

demo 里的工具通常是：

tools =[search, read_file, write_file]

Hermes 里的工具是：

tool file
-> registry
-> toolset
-> session filter
-> schema sanitizer
-> deferred tool search
-> hook
-> handler execution
-> result budget
-> transcript persistence

这就是生产化差距。

3.3 Hermes 的 toolset 是一个好抽象

toolsets.py 里有 _HERMES_CORE_TOOLS，也有 coding、memory、skills、delegate、platform bundle 等组合。

这个抽象比单纯 allowlist 更适合实际使用。因为用户或会话通常不是一个个选择工具，而是选择工作模式：

coding mode
research mode
messaging mode
memory mode
minimal mode

对应到自己的项目，可以提炼成：

tool profile =一组工具+一组策略+一组默认限制

比如企业知识库 Agent 可以有：

profile	工具
`qa-readonly`	retrieve、rerank、read_citation
`analyst`	retrieve、aggregate、chart、export
`admin`	ingest、reindex、eval、delete_index
`debug`	trace、sessionhistory、rawchunks

这比“所有工具都给模型看”安全很多。

3.4 Hermes 的记忆系统有两个重点

Hermes 的 MemoryManager 文档写得很清楚：它是 run_agent.py 里的单一集成点，用来替代散落在各处的 memory backend 代码。

它做几件事：

build system prompt
pre-turn prefetch
post-turn sync
queue background prefetch
expose memory provider tools
sanitize memory context

其中有一个设计很值得注意：同一时间只允许一个 external plugin provider。这是为了避免 tool schema 膨胀和多个 memory backend 冲突。

这和很多学习项目正好相反。学习项目容易不断加 memory：

短期记忆
长期记忆
向量记忆
用户画像
会话搜索
外部记忆服务

但真正运行时，如果都塞进 prompt 和 tool surface，系统会变得不可控。Hermes 的做法提醒我们：

记忆不是越多越好，记忆入口必须收敛。

3.5 Hermes 的会话生命周期值得单独学

Hermes 有一篇 docs/session-lifecycle.md，专门解释 session key、session entry、reset policy、restart recovery、message queue、agent cache。

这部分比很多 Agent loop 更接近真实产品。

因为消息平台里的会话不是简单的 conversation_id。它要考虑：

platform
chat id
user id
thread id
group / channel / dm
per-user isolation
idle reset
daily reset
restart recovery
pending message queue
cached agent eviction

一个严肃的长期 Agent，如果没有这层设计，很快会遇到问题：

群聊里不同用户上下文串了
线程回复错位了
重启后任务丢了
长会话占满内存
旧会话一直不释放
用户/reset 后后台任务还在写旧 transcript

Hermes 在这块给了非常具体的工程样本。

4. 两个框架放在一起看：差异真正在哪里

4.1 抽象重心不同

维度	OpenClaw	Hermes
主抽象	Gateway / Plugin / Channel / Agent runtime	AIAgent / Toolset / Memory / Session
技术栈	TypeScript / Node / pnpm workspace	Python / uv / optional Node apps
扩展方式	native plugin capability model	Python tool registry + plugins + MCP
工具策略	强 policy pipeline，按 session / sandbox / sender 计算	toolset 过滤 + registry availability + hooks
记忆	context engine / memory plugin 方向	memory manager / provider / session search
多渠道	核心卖点之一	gateway 支持，但更像 Agent 外围能力
安全模型	host-first main session，non-main 可 sandbox	terminal backend / approval / allowlist / sandbox
学习价值	平台化、插件边界、多渠道、安全模型	agent loop、工具执行、记忆、会话恢复

4.2 工具设计的差异

OpenClaw 的工具设计更像：

capability / plugin / policy / runtime scope

Hermes 的工具设计更像：

registry / toolset / schema / handler

前者适合大型平台长期演进，后者适合 Python Agent 快速扩工具。

如果你现在要给学习工程加一套工具系统，不应该照搬 OpenClaw 那么重的 capability model，也不应该只用简单 list。

更合适的中间形态是：

ToolRegistry
ToolProfile
ToolPolicy
ToolRuntime

先做到：

工具自注册
工具属于某个 profile
每个 profile 有默认 allow / deny
每次会话动态计算可用工具
工具执行前后有 hook
工具结果有长度预算和结构化错误

这就足够支撑 Phase6 之后的继续演进。

4.3 安全默认值都要谨慎

两个框架都不是“默认适合企业公网暴露”的系统。

OpenClaw README 明确说，main session 默认 host-first，工具运行在 host 上。它的安全模型更像：

个人可信operator
本地优先
远程渠道需要 pairing / allowlist / sandbox

Hermes 的 Docker compose 默认 network_mode:host，它自己的网络隔离文档也明确说这会让 agent process 有 unrestricted outbound access，并建议通过 internal network + egress proxy 做隔离。

这给自己的生产化学习一个很清楚的启发：

Agent安全不能只靠 prompt。

至少要有：

caller allowlist
tool allowlist
command approval
sandbox backend
network egress policy
secret redaction
session isolation
audit log

而且这些东西要在框架层实现，不应该靠每个业务 prompt 自觉。

5. 从源码提炼出的四个工程问题

把 OpenClaw 和 Hermes 放在一起看，成熟 Agent 框架至少有四个不能被 prompt 或单个 demo 文件掩盖的工程问题。

5.1 Runtime：一次 Agent turn 怎么跑完

核心设计点包括：

prompt 构建
context 注入
model transport
tool call loop
tool result 回填
retry / failover
compaction
final response

参考：

OpenClaw embedded-agent-runner
Hermes AIAgent / conversation_loop

5.2 Tool Platform：工具怎么注册、过滤和执行

核心设计点包括：

tool registry
schema sanitizer
toolsets / profiles
tool search
pre / post hook
result budget
tool policy
approval

参考：

OpenClaw agent-tools.ts
Hermes model_tools.py / tools/registry.py

5.3 Session & Memory：长期助手怎么不断片

核心设计点包括：

session key
transcript store
reset policy
restart recovery
agent cache
memory prefetch / sync
memory context fencing

参考：

Hermes docs/session-lifecycle.md
Hermes agent/memory_manager.py
OpenClaw sessions / context engine

5.4 Security：Agent 怎么不越界

核心设计点包括：

trusted operator model
untrusted inbound message
sandbox mode
plugin trust
command approval
egress isolation
secret handling
audit

参考：

OpenClaw SECURITY.md
OpenClaw plugin execution model
Hermes SECURITY.md
Hermes network egress isolation 文档

6. 可以反哺到本学习工程的最小设计

不要试图复制 OpenClaw 或 Hermes。它们是成熟产品，复杂度很大。

对当前 ai-agent-learn 项目，最值得吸收的是五个小设计。

6.1 ToolProfile，而不是全局工具列表

现在可以设计：

classToolProfile:
    name: str
    tools: list[str]
    default_policy:ToolPolicy

比如：

readonly-rag
coding
admin-eval
ingestion

6.2 ToolResult budget

任何工具结果都不应该无限塞回上下文。

需要有：

最大字符数
大结果落盘
返回摘要和引用 id
trace 记录完整路径

这点 Hermes 做得很细。

6.3 Session key 规则

Phase6 如果接 Web UI、API、多用户，就不能只用一个 session_id。

应该设计：

tenant:user:channel:thread

并明确哪些场景共享上下文，哪些场景隔离上下文。

6.4 Memory 写入边界

记忆不能在任何 turn 后随便写。

至少要区分：

transcript
summary
user preference
task fact
retrieved evidence
system-generated note

记忆写入应该有 schema 和来源，不要让 memory 变成另一个 prompt 垃圾堆。

6.5 Security checklist 变成代码测试

不要只写安全原则。

要把这些变成测试：

未授权用户不能调用 admin tool
readonly profile 不能写文件
大工具结果不会塞爆上下文
secret 不出现在日志
sandbox mode 下不能访问 workspace 外路径

OpenClaw 和 Hermes 都有大量安全/边界测试，这个方向值得学习。

7. 最后总结

OpenClaw 和 Hermes 都给了一个很重要的提醒：

Agent框架不是 LLM 调用封装。
Agent框架是在管理不确定性、权限、状态和长期运行成本。

OpenClaw 让我们看到，一个 Agent 如果要进入真实消息渠道和插件生态，就必须处理 Gateway、channel、plugin ownership、tool policy、sandbox 和 trusted operator model。

Hermes 让我们看到，一个 Agent 如果要长期陪伴用户，就必须处理 tool registry、toolsets、session lifecycle、memory provider、skills、自我改进和重启恢复。

它们都不是轻量学习项目。

但它们非常适合在六阶段学习完成之后阅读。因为这时你已经知道 Agent 的基本构件，再看这些大框架，就不会只看到功能，而会看到工程边界：

哪里需要显式状态？
哪里需要权限策略？
哪里需要插件所有权？
哪里需要 sandbox？
哪里需要会话恢复？
哪里不能相信模型自觉？

这也是当前学习工程接下来最需要补齐的部分：让 Agent 不只会回答问题，还能在明确的权限、状态、记忆和运行边界里长期工作。