Clawdbot值得借鉴的Agent架构设计经验

Clawdbot（也称为Moltbot，最近又改名为OpenClaw）在Agent执行、工具使用、浏览器等方面的架构值得关注。深入了解Clawdbot的底层原理，有助于更好地理解其系统及能力，尤其是它擅长的地方，以及能力边界。

本文从技术层面介绍Clawdbot的工作原理，探讨它如何处理记忆和执行任务。

1Clawdbot的技术背景

Clawdbot是一种智能个人助理，既可以在本地运行，也可以通过模型API进行访问，使用方式类似手机上的应用程序。其核心技术是基于TypeScript的CLI应用程序，而不是Python、Next.js或者Web应用程序。它的工作方式包括：

• 在本地设备上运行，并提供网关服务器来处理所有的频道连接（如Telegram、WhatsApp、Slack等）。
• 调用LLM API（如Anthropic、OpenAI、本地等）。
• 在本地执行工具，并且可以在计算机上执行各种操作。

2架构

以下是Clawdbot处理信息的基本流程：

1. 频道适配器（Channel Adapter）
 频道适配器接收消息并处理（标准化、提取附件等）。每种消息平台都有自己的适配器。

2. 网关服务器（Gateway Server）
 网关服务器是任务/会话的协调者，它将消息传递到正确的会话。它是Clawdbot的核心，能够处理多个重叠的请求。为了序列化操作，Clawdbot使用基于车道（Lane）的命令队列。每个会话有自己的专用车道，低风险可并行执行的任务可以在不同的车道上并行执行（如定时任务）。

这种设计避免了常见的async/await混乱，过度并行化会破坏系统的可靠性，带来调试的噩梦。默认采用串行执行，只有明确要求时才会进行并行处理。

3. Agent执行器（Agent Runner）
 Agent执行器负责选择使用哪个模型，挑选API密钥（如果没有密钥，它会标记配置并尝试下一个密钥）。如果主模型失败，它会回退到其他模型。Agent执行器动态组装系统提示，结合可用的工具、技能、记忆，并加入会话历史（从.jsonl文件中读取）。

接下来，Agent执行器将提示传递给上下文窗口守卫，确保上下文空间足够。如果上下文接近满负荷，它会压缩会话内容（总结上下文），或者在无法继续时优雅地退出。

4. LLM API调用（LLM API Call）
 这个过程会流式传输响应，并在不同的提供商之间进行抽象。如果模型支持，Agent还可以请求扩展思考。

5. Agent循环（Agentic Loop）
 如果LLM返回了工具调用响应，Clawdbot会在本地执行该工具，并将结果添加到会话中。这一过程会持续进行，直到LLM返回最终文本或者达到最大回合数（默认为20回合）。

6. 响应路径（Response Path）
 这一部分比较标准，响应通过频道返回给用户。会话还会通过基本的JSONL格式进行持久化，每行一个JSON对象，包含用户消息、工具调用、结果、响应等。这是Clawdbot如何记住信息（基于会话的记忆）。

3Clawdbot的记忆系统

没有适当的记忆系统，AI助手的效果就像金鱼一样。Clawdbot通过以下两种系统处理记忆：

• 会话转录（Session Transcripts）以JSONL格式保存。
• 记忆文件（Memory Files）存储在MEMORY[.]md或memory/文件夹下。

在搜索时，它使用向量搜索和关键词匹配的混合方式，结合了两者的优点。因此，搜索“认证错误”不仅能找到包含“auth issues”的文档（语义匹配），还能够找到包含准确短语的文档（关键词匹配）。

向量搜索使用SQLite，而关键词搜索则使用FTS5（SQLite扩展）。嵌入提供者是可配置的。它还支持智能同步，当文件变动时触发。

这些记忆文件是通过Agent自己使用标准的“写入”工具生成的，而没有特别的记忆写入API。Agent直接写入memory/*.md文件。

每当新的对话开始时，Clawdbot会读取之前的对话，并将总结写入Markdown格式。这种简洁的记忆系统类似于工作流记忆。没有复杂的记忆合并或定期压缩。

这种简化有其优点，但也有一定的局限性。从可解释性角度看，简化设计比复杂的代码更加易于理解，也减少了潜在的错误。

4Clawdbot如何利用计算机

Clawdbot的一大优势是能够在计算机上执行各种操作。其工作原理如下：

Clawdbot通过exec工具运行shell命令：

• 默认情况下，命令会在Docker容器中运行。
• 它也可以直接在主机上运行命令。
• 还支持在远程设备上运行命令。

除了执行命令外，Clawdbot还提供了文件系统工具（读取、写入、编辑）、浏览器工具（基于Playwright，支持语义快照），以及进程管理工具（管理后台长期命令、终止进程等）。

5安全性（或缺乏安全性）

Clawdbot提供了允许列表（Allowlist）机制，允许用户批准某些命令（可以选择一次性批准、始终批准或拒绝提示）。
 对于安全命令（如jq、grep、cut等）是预先批准的，而危险的shell命令则默认被阻止。

例如，以下命令会被拒绝执行：

• npm install $(cat /etc/passwd)
• cat file > /etc/hosts
• rm -rf / || echo "failed"
• (sudo rm -rf /)

这种安全性设计与Claude Code类似，允许用户根据需求授予适当的权限，同时尽量保持系统的自主性。

6浏览器：语义快照

Clawdbot的浏览器工具不依赖于传统的截图，而是使用语义快照，这是一种基于文本的表示页面可访问性树（ARIA）的方式。

因此，Agent能够读取到页面的语义结构：

• 按钮“Sign In” [ref=1]
• 文本框“Email” [ref=2]
• 文本框“Password” [ref=3]
• 链接“Forgot password?” [ref=4]
• 标题“Welcome back”
• 列表
• 列表项“Dashboard”
• 列表项“Settings”

这种方式带来了几个显著优势。

首先，浏览网站不仅仅是视觉上的任务；

其次，传统截图可能大于5MB，而语义快照的大小不到50KB；

最后，显著降低了token的使用成本。