Clawdbot 项目虽广为人知，但其内部运作机制却鲜有人探究。这次技术解剖将揭示其作为 TypeScript 命令行应用的极简架构，从串行的网关设计到独特的记忆管理，展示如何用基础工具构建强大可靠的 AI 系统。
智能速览
Clawdbot 本质是一个本地的 TypeScript 命令行应用。
采用独特的“涌道”架构，默认串行处理以提升可调试性。
记忆系统结合 JSONL 与 Markdown 文件，实现简单而高效的检索。
通过命令白名单机制保障本地执行系统命令的安全性。
浏览器工具使用语义快照替代截图，大幅降低 Token 成本。
精华内容
要理解 Clawdbot 的强大，不能只看其功能表象，必须深入其架构设计的内核。它的每一个环节都体现了“用朴素方式解决核心问题”的工程哲学。
基础架构与哲学
Clawdbot 的底层是一个运行在本地的 TypeScript 命令行应用，而非网页服务或 Python 程序。其整体架构被清晰地划分为六个环节：渠道适配器、网关服务器、智能体运行器、大模型API调用、智能体循环和响应路径。
其中，网关服务器的设计尤为关键。它采用了一种名为“涌道”的串行架构，而非主流的并行处理。这一设计背后蕴含着重要的工程考量：默认串行，显式并行。这样做可以避免异步调用带来的复杂交织，极大提升了代码的可调试性和可维护性，将开发者的心智模型从复杂的并发控制中解放出来。
智能体运行核心
智能体的运行由“智能体运行器”模块负责，它会选择合适的模型，组装系统提示词，并加载工具与记忆。当对话上下文接近上限时，系统会自动进行压缩或优雅地失败，确保稳定运行。
在调用大模型API时，系统支持流式响应和扩展思考。如果模型返回工具调用请求，系统便进入“智能体循环”环节，在本地执行相应工具，将结果再次喂给模型，如此循环往复，直至任务完成或达到最大轮次限制。
双重记忆系统
Clawdbot 的记忆系统采用两层结构：短期记忆存储在 JSONL 文件中，记录完整的对话历史；长期记忆则保存在普通的 Markdown 文件里。这种设计避免了复杂的数据库依赖。
在检索记忆时，系统会同时使用向量检索和关键词匹配两种方式，既能找到语义相似的内容，也能精确命中特定关键词。这些 Markdown 记忆文件通过简单的文件操作生成，没有记忆合并或周期性压缩，新旧记忆权重相等，追求极致的简洁与透明。
安全与效率设计
在安全性方面，Clawdbot 通过一个命令白名单机制来控制本地 Shell 命令的执行。用户可以选择“允许一次”、“始终允许”或“拒绝”，危险操作会被默认拦截，提供了灵活的安全保障。
效率优化上，其基于 Playwright 的浏览器工具设计十分巧妙。它不依赖像素级的网页截图，因为一张截图可能占用 5MB 空间。取而代之的是一种仅 50KB 大小的语义快照，即页面可访问性树的文本表示。这一设计将浏览网页的 Token 成本降低了约 100 倍，因为它聚焦于页面的语义而非视觉呈现。
Clawdbot 的设计启示我们，卓越的 AI 工程并非堆砌前沿技术，而是回归问题本质，用最简洁的方案实现最高效的运作。这套架构或许能引发关于如何构建更可靠、更透明 AI 系统的深入思考。
