本文从内部视角介绍 Clawdbot（又称 Moltbot）的架构，包括代理执行、工具调用、浏览器交互等机制，并提炼对 AI 工程师有价值的经验。
理解 Clawd 的实现原理有助于更好地把握系统能力边界，尤其是它擅长什么、不擅长什么。本文源于对 Clawd 记忆机制与可靠性的好奇，将从表层梳理 Clawd 的工作方式。
Clawd 的技术本质
Clawd 常被描述为可本地运行或通过模型 API 使用的个人助手，在手机等设备上即可访问。那它本质上是什么？
Clawdbot 的核心是一个 TypeScript 编写的 CLI 应用。
它不是 Python、Next.js 或 Web 应用，而是一个进程，负责：
- 在本地运行并暴露 Gateway Server，统一处理各渠道连接（Telegram、WhatsApp、Slack 等）
- 调用 LLM API（Anthropic、OpenAI、本地模型等）
- 在本地执行工具
- 按你的需求在电脑上完成各类操作
整体架构
下面用「从你发出一条消息到收到回复」的完整链路，说明架构是如何运转的。
当你在某个 Messenger 里向 Clawd 发消息时，会发生什么？
1. Channel Adapter（渠道适配器）
Channel Adapter 接收你的消息并做预处理（归一化、提取附件等）。不同 Messenger 和输入流有各自的适配器。
2. Gateway Server（网关服务器）
Gateway Server 是任务/会话协调中心，接收消息并分发给对应会话，是 Clawd 的核心。它需要处理大量并发请求。
为串行化操作，Clawd 使用基于 Lane 的命令队列：每个会话有独立 Lane，低风险、可并行的任务可在并行 Lane 中执行（如 cron 任务）。
这与「到处 async/await」的做法形成对比：过度并行会损害可靠性并带来大量调试问题。
原则：默认串行，仅在明确安全时并行。
若你做过 Agent 开发，对此会有体会；Cognition 的《Don't Build Multi-Agents》也强调了这一点。每个 Agent 简单 async 一把梭，很容易得到交错混乱的日志；若共享状态，竞态会成为开发中的常态。Lane 是对队列的抽象，串行是默认架构，而不是事后补救。开发者只需写业务逻辑，队列负责避免竞态；心智从「要锁什么？」变成「什么可以安全并行？」。
3. Agent Runner（代理运行器）
这里才真正接入 AI。Agent Runner 会：
- 决定使用哪个模型、选用哪个 API Key（若都不可用则标记该 profile 进入 cooldown 并尝试下一个）
- 主模型失败时回退到其他模型
- 动态组装系统提示：包含可用工具、技能、记忆，再附上会话历史（来自
.jsonl文件） - 将组装好的内容交给 Context Window Guard，检查上下文是否足够；若接近满则压缩会话（如总结）或优雅失败
4. LLM API 调用
真正的 LLM 调用在这里完成：流式返回结果，并对不同提供商做统一抽象；若模型支持，还可请求扩展思考（extended thinking）。
5. Agentic Loop（代理循环）
若 LLM 返回的是工具调用，Clawd 在本地执行该工具并把结果追加到对话中，然后继续请求 LLM。如此循环，直到 LLM 返回最终文本或达到最大轮数（默认约 20）。
这里也是 Computer Use 等能力的实现位置（后文会展开）。
6. Response Path（响应路径）
响应经渠道返回给你；会话通过 JSONL 持久化，每行一个 JSON 对象（用户消息、工具调用、结果、回复等）。这就是 Clawd 的会话级记忆。
以上是基础架构。下面深入几个关键组件。
Clawd 如何记忆
没有合适的记忆系统，AI 助手和「金鱼记忆」差不多。Clawd 通过两套机制实现记忆：
- 会话记录：如上所述，用 JSONL 保存会话。
- 记忆文件：以 Markdown 形式存放在
MEMORY.md或memory/目录下。
检索采用 向量搜索 + 关键词匹配 的混合方式，兼顾语义与精确匹配。例如搜 "authentication bug" 既能命中写「auth 相关问题」的文档（语义），也能命中包含该精确短语的文档（关键词）。
- 向量搜索基于 SQLite；关键词搜索用 FTS5（SQLite 扩展）。
- 嵌入模型/提供商可配置。
- Smart Syncing：文件变更时由 file watcher 触发同步。
这些 Markdown 记忆由 Agent 通过普通的「写文件」工具生成，没有专门的 memory-write API，Agent 只是往 memory/*.md 写。新会话开始时，一个 hook 会抓取上一轮对话并写出摘要到 Markdown。
Clawd 的记忆设计相当简单，与 CamelAIOrg 中的 workflow memories 思路接近：不做记忆合并，不做按月/按周的压缩。这种简单可以是优势也可以是局限，但作者倾向于「可解释的简单」而非复杂纠缠。记忆长期保留，旧记忆权重与新区分不大，可以说没有遗忘曲线。
Clawd 的「爪子」：如何使用你的电脑
Clawd 的一大护城河是：你给它一台电脑，它就真的能用。具体方式大致如下。
Clawd 在用户自担风险的前提下，给 Agent 较高的电脑权限。它通过 exec 工具在以下环境执行 shell 命令：
- Sandbox（默认）：在 Docker 容器中执行
- 宿主机：直接在主机上执行
- 远程设备：在指定远程机器上执行
此外还有：
- 文件系统工具：读、写、编辑文件
- 浏览器工具：基于 Playwright，配合语义快照（见下节）
- 进程管理：长时间后台命令、结束进程等（process 相关工具）
安全机制（或说「有意为之的有限安全」）
类似 Claude Code，存在命令审批列表：用户可对命令选择「本次允许」「始终允许」或「拒绝」并会收到提示。
配置示例（~/.clawdbot/exec-approvals.json）：
{
"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" # 链式 ||
(sudo rm -rf /) # 子 shell
整体思路与 Claude Code 的本地安全模型类似：在用户允许的范围内尽量给 Agent 自主权。
浏览器：语义快照（Semantic Snapshots）
浏览器工具主要不依赖截图，而是使用 语义快照：基于页面无障碍树（ARIA）的文本表示。
Agent 看到的可能是这样的结构：
- 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"
这带来几个明显好处：浏览网页在很多场景下并非「纯视觉任务」；相比一张 5 MB 的截图，语义快照往往不到 50 KB，且只占图像的一小部分 token 成本。
小结
- Clawdbot 是 TypeScript CLI，通过 Gateway、Lane 队列、Agent Runner 和 Agentic Loop 串联起渠道、模型与工具。
- 记忆依赖 JSONL 会话 + Markdown 记忆文件，检索用向量 + 关键词，设计简单、可解释。
- 电脑使用依赖 exec / 文件 / 浏览器 / 进程 等工具，配合审批列表与危险构造拦截，在安全与自主之间做权衡。
- 浏览器能力建立在 语义快照 上，节省 token 并更利于推理。
若你关心「一个可本地跑、多渠道、能真正用电脑的 Agent 是怎么搭出来的」，Clawd 的架构是一个很好的参考样本。
