OpenClawd 架构深度解析：简单而精妙
开发者扒开这个 AI 助手的内部，发现它厉害不在技术复杂，而在每个关键节点都选了「够用且简单」的方案，再串成一条清晰的链。
- 技术本质那节先破除神秘感——没有黑科技，全是常规选择。
- 整体架构流程走一遍，看清各模块怎么衔接。
- 记忆系统的设计是重点，它决定了助手能不能跨会话干活。
- 计算机使用能力和安全机制成对出现：能动手就必须有边界。
- 浏览器语义快照那节最有借鉴价值，讲怎么把网页压成模型能读的形式。
这篇文章来自开发者 ℏεsam，他深入研究了 OpenClawd（原名 Clawdbot）的内部架构，揭示了这个 AI 助手的工作原理。
Clawdbot 的厉害之处不在于用了多复杂的技术，而在于每个关键节点都选择了「够用且简单」的方案，然后把它们串成一条清晰的流水线。
一、技术本质
Clawdbot 本质上是一个 TypeScript CLI 应用，不是 Python、Next.js 或 Web 应用。它是一个运行在本地机器上的进程，负责：
- 暴露一个网关服务器处理所有渠道连接（Telegram、WhatsApp、Slack 等）
- 调用 LLM API（Anthropic、OpenAI、本地模型等）
- 在本地执行工具
- 在用户电脑上执行各种操作
二、整体架构流程
当用户发送消息到收到回复，经历以下六个阶段：
1. 渠道适配器（Channel Adapter） 接收用户消息并进行处理（标准化、提取附件）。不同的消息平台有各自专属的适配器。
2. 网关服务器（Gateway Server） 这是 Clawdbot 的核心，负责任务/会话协调，将消息传递给正确的会话。它采用基于通道（Lane）的命令队列来序列化操作：
- 每个会话有自己的专属通道
- 低风险的可并行任务可在并行通道运行（如定时任务）
- 设计理念：默认串行，显式并行
这种设计避免了 async/await 代码混乱、日志难读、共享状态的竞态条件等问题。开发者的思维模式从"我需要锁什么？"转变为"什么可以安全并行？"
3. Agent Runner AI 的核心执行层，负责：
- 决定使用哪个模型
- 选择 API Key（失败则标记冷却并尝试下一个）
- 主模型失败时回退到备用模型
- 动态组装系统提示词（包含可用工具、技能、记忆）
- 添加会话历史（来自 .jsonl 文件）
- 上下文窗口守卫：检查上下文空间是否足够，空间不足时压缩会话（总结上下文）或优雅失败
4. LLM API 调用 流式传输响应，抽象了不同提供商的差异，支持扩展思考（extended thinking）功能。
5. Agentic Loop（智能体循环） 如果 LLM 返回工具调用，Clawdbot 在本地执行并将结果添加到对话中，循环直到 LLM 返回最终文本或达到最大轮次（默认约20轮）。这里也是 Computer Use 发生的地方。
6. 响应路径 响应通过渠道返回给用户，会话以 JSONL 格式持久化存储（每行一个 JSON 对象，包含用户消息、工具调用、结果、响应等）。
三、记忆系统
Clawdbot 通过两个系统处理记忆：
存储方式：
- 会话记录：JSONL 格式文件
- 记忆文件：Markdown 格式，存储在 MEMORY.md 或 memory/ 文件夹
搜索机制： 采用向量搜索 + 关键词匹配的混合方式。搜索"authentication bug"既能找到提及"auth issues"的文档（语义匹配），也能找到精确短语（关键词匹配）。
- 向量搜索：SQLite
- 关键词搜索：FTS5（SQLite 扩展）
- 嵌入提供商可配置
写入机制： 没有特殊的记忆写入 API，Agent 直接使用标准的文件写入工具写入 memory/*.md。新对话开始时，钩子会抓取上一次对话并写入 Markdown 摘要。
特点：
- 设计简单，无记忆合并、无月度/周度压缩
- 记忆永久保存，旧记忆与新记忆权重基本相等
- 没有遗忘曲线
四、计算机使用能力
这是 Clawdbot 的核心竞争力之一。它通过 exec 工具在以下环境运行 shell 命令：
- 沙盒（默认）：命令在 Docker 容器中运行
- 宿主机：直接在用户机器上运行
- 远程设备
其他工具：
- 文件系统工具：读、写、编辑
- 浏览器工具：基于 Playwright，使用语义快照
- 进程管理：后台长期命令、终止进程等
五、安全机制
类似 Claude Code 的设计，采用命令白名单机制（允许一次、始终允许、拒绝）：
{
"agents": {
"main": {
"allowlist": [
{ "pattern": "/usr/bin/npm", "lastUsedAt": 1706644800 },
{ "pattern": "/opt/homebrew/bin/git", "lastUsedAt": 1706644900 }
]
}
}
}
预批准的安全命令：jq、grep、cut、sort、uniq、head、tail、tr、wc
默认阻止的危险 shell 构造：
- 命令替换：npm install $(cat /etc/passwd)
- 重定向：cat file > /etc/hosts
- 链式操作：rm -rf / || echo "failed"
- 子 shell：(sudo rm -rf /)
设计理念：在用户允许的范围内给予最大自主权。
六、浏览器语义快照
浏览器工具不主要依赖截图，而是使用语义快照，即页面可访问性树（ARIA）的文本表示：
- button "Sign In" [ref=1]
- textbox "Email" [ref=2]
- textbox "Password" [ref=3]
- link "Forgot password?" [ref=4]
- heading "Welcome back"
- list
- listitem "Dashboard"
- listitem "Settings"
四大优势：
- 浏览网页本质上不是视觉任务
- 截图约 5MB，语义快照不到 50KB
- 大幅降低 token 成本
- 更适合 AI 理解和操作
核心启示
这篇文章揭示了几个重要的 AI Agent 工程原则：
- 串行优先：避免过度并行化带来的调试噩梦
- 简单可解释：记忆系统宁可简单也不要复杂
- 分层抽象：通道适配器、网关服务器、Agent Runner 各司其职
- 安全与自主的平衡：白名单机制 + 危险命令阻止
- 语义优于视觉：浏览器操作用语义快照而非截图
全文翻译
全网都在聊的 Clawdbot，我拆开看了看里面的「内脏」
最近 Clawdbot 火了。
这个能接管你电脑、帮你干活的 AI 助手，让很多人第一次感受到：原来 AI 不只是聊天，它真的能「动手」。
但很少有人问：它到底是怎么做到的？
我花了点时间研究了 Clawdbot 的架构。说实话，看完之后我的感受是——这东西的设计，比大多数人想象的要精妙得多。
今天就带你拆开看看。
先破除一个误解
很多人以为 Clawdbot 是个网页应用，或者是某种复杂的云端服务。
不是。
它的本体就是一个跑在你电脑上的命令行程序。用 TypeScript 写的，干净利落。
它做的事情很简单：接收你的消息，调用大模型，执行工具，返回结果。
但「简单」不代表「简陋」。恰恰相反，真正的高手都知道：把复杂的事情做简单，才是最难的。
一条消息的奇幻漂流
当你在 Telegram 上给 Clawdbot 发一条消息，背后发生了什么？
我画了张图，但用文字描述可能更直观：
第一站：渠道适配器
不管你从哪发消息——Telegram、WhatsApp、Slack——都会先经过一个「翻译官」。它把各种格式的消息统一成 Clawdbot 能理解的样子。
第二站：网关服务器（这是精华）
这里是整个系统的「调度中心」。
你可能会想：调度有什么难的？不就是收到消息、处理、返回吗？
问题在于：如果同时来了 10 条消息怎么办？
大多数开发者的本能反应是：并行处理啊，快！
但 Clawdbot 的设计者选择了一条反直觉的路：默认串行，显式并行。
为什么？
因为他们踩过坑。做过 AI Agent 的人都知道，过度并行化简直是噩梦——日志乱成一锅粥，状态互相打架，bug 藏得比忍者还深。
所以 Clawdbot 用了一个叫「Lane（通道）」的设计：每个会话有自己的专属通道，消息排着队一个个处理。只有那些明确标记为「安全」的任务，才会被扔到并行通道里。
这个设计哲学可以浓缩成一句话：
不要问「我需要锁什么」，要问「什么可以安全地并行」。
简单，但深刻。
第三站：Agent Runner
到这里，AI 才真正登场。
这个模块干几件事：选模型、选 API 密钥、组装提示词、检查上下文窗口够不够用。
有意思的是上下文窗口守卫这个设计。
我们都知道大模型有「记忆容量」限制。Clawdbot 会实时监控这个容量，快满了就自动「压缩」——把之前的对话总结成精华版，腾出空间。
这就像一个会整理书桌的助手：桌子快堆满了，就把旧资料归档，只留最重要的。
第四站：Agent 循环
这是魔法发生的地方。
大模型返回结果后，如果它说「我需要用个工具」，Clawdbot 就执行这个工具，把结果喂回去。如此循环，直到任务完成或者达到上限（默认 20 轮）。
这个循环，就是 AI Agent 能「自主干活」的核心。
记忆系统：简单到让人意外
一个没有记忆的 AI 助手，和金鱼没什么区别。
那 Clawdbot 是怎么记住事情的？
答案可能会让你失望——就是写文件。
两种文件：
- .jsonl 文件记录对话历史
- memory/*.md 文件存储长期记忆
搜索的时候，用向量搜索（理解语义）加关键词搜索（精确匹配）。比如你搜「登录 bug」，它既能找到写着「认证问题」的笔记，也能找到精确提到「登录 bug」的内容。
没有复杂的记忆融合算法，没有什么「周记忆」「月记忆」的分层压缩，就是朴素的文件读写。
这让我想起一句老话：能用简单方案解决的问题，就别搞复杂。
当然，这也有代价——旧记忆和新记忆权重一样，没有「遗忘曲线」。时间久了，记忆库可能会变得臃肿。
但至少，它是可解释的。出了问题，你打开文件就能看到一切。
真正的护城河：让 AI 操作你的电脑
这才是 Clawdbot 最硬核的部分。
它能执行 shell 命令、读写文件、操作浏览器、管理进程。
听起来很危险？确实。
所以它设计了几道防线：
第一道：沙箱
默认情况下，命令在 Docker 容器里跑。就像给 AI 一个「隔离舱」，它折腾得再狠，也不会伤到你的真实系统。
第二道：白名单
你可以设置哪些命令允许自动执行，哪些需要手动确认。安全命令（比如 grep、cat）预先放行，危险操作必须你点头。
第三道：语法检测
它会在执行前扫描命令，发现危险结构直接拦截：
npm install $(cat /etc/passwd) # 🚫 命令注入？不行
rm -rf / || echo "failed" # 🚫 链式命令？不行
这套设计的哲学是：给用户最大的自由，同时设好安全边界。
浏览器操作：不看图，看「骨架」
这个设计让我眼前一亮。
你可能以为 AI 操作浏览器，是通过截图来「看」页面的。
Clawdbot 不是。
它用的是语义快照——把网页的结构用文字描述出来：
- 按钮「登录」
- 输入框「邮箱」
- 输入框「密码」
- 链接「忘记密码？」
为什么这么做？
因为便宜，而且够用。
一张截图 5MB，语义快照不到 50KB。Token 成本差了两个数量级。
而且你仔细想想：浏览网页这件事，本质上不是「看图」，而是「理解结构」。AI 不需要知道按钮是蓝色还是绿色，它只需要知道「这里有个登录按钮」。
这就是工程上的取舍智慧：用最小的成本，获取足够的信息。
写在最后
看完 Clawdbot 的架构，我最大的感受是：
好的系统设计，往往不是堆砌复杂技术，而是在每个关键点上做出正确的取舍。
- 默认串行 vs 激进并行
- 文件记忆 vs 复杂数据库
- 语义快照 vs 截图识别
每一个选择背后，都是对「简单」和「够用」的坚持。
这也是为什么我说，AI 工程师应该研究一下 Clawdbot。不是为了抄它的代码，而是学它做决策的方式。
毕竟，架构设计的本质，就是一连串的取舍。