OpenClaw(Clawdbot) 架构解析：

姚姚林先

OpenClaw(Clawdbot) 架构解析：个人AI智能体的核心引擎（everyone talks about Clawdbot, but here's how it works）


1. 摘要
OpenClaw 是一个个人AI智能体，其核心是一个在本地计算机上运行的 Typescript 命令行界面（CLI）应用程序，而非传统的Web应用。它的架构旨在实现高可靠性和强大的本地计算机集成能力。

其设计的关键亮点在于采用了基于通道的命令队列，默认执行串行操作，从而有效避免了并发处理中常见的“异步/await意大利面代码”和竞态条件问题。
这种“默认串行，显式并行”的理念显著提升了系统的稳定性和可调试性。

OpenClaw的内存系统设计出奇地简洁而高效，它结合了用于存储会话记录的.jsonl文件和用于长期记忆的Markdown文件。代理通过标准的“写入文件”工具直接与Markdown记忆文件交互。其检索机制采用向量搜索（用于语义匹配）和关键字搜索（用于精确匹配）的混合模式，确保了信息检索的全面性。

该智能体最核心的“护城河”在于其深度计算机集成能力，通过工具集赋予了代理执行shell命令、操作文件系统、管理后台进程以及控制浏览器的能力。
在浏览器交互方面，OpenClaw创新性地使用“语义快照”（基于页面的可访问性树生成的文本表示）代替传统的屏幕截图，极大地减小了数据体积（从MB级降至KB级）并显著降低了LLM的Token成本。

为确保安全，OpenClaw实施了一套以用户授权为核心的安全机制，包括一个命令许可名单和对危险shell构造的默认阻止，旨在实现用户允许范围内的最大自主性。

2. 核心架构与技术栈

OpenClaw的本质是一个Typescript CLI应用程序。它并非一个Python或Next.js驱动的Web应用。作为一个本地进程，其核心职能包括：

- 本地运行：在用户的计算机上作为独立进程运行。
- 暴露网关服务器：处理来自Telegram、WhatsApp、Slack等不同渠道的连接。
- 调用LLM API：与Anthropic、OpenAI或本地模型等多种大型语言模型进行交互。
- 本地执行工具：在用户的计算机上直接运行工具和命令。
- 实现用户指令：在用户计算机上执行任意授权的任务。

3. 任务执行流程

当用户通过消息应用向OpenClaw发送提示时，系统会经过以下一系列精确协调的步骤来处理请求并生成响应：

1）通道适配器 (Channel Adapter)
  - 接收来自不同输入流（如即时通讯软件）的消息。
  - 对消息进行标准化处理并提取附件。
2）网关服务器 (Gateway Server)
  - 作为系统的任务和会话协调中心，是OpenClaw的心脏。
  - 负责接收消息并将其传递给正确的会话，能够处理多个重叠请求。
  - 关键设计：为序列化操作，系统采用基于“通道”（lane-based）的命令队列。每个会话拥有一个专用通道，确保任务按顺序执行。低风险且可并行的任务（如cron job）可以在并行通道中运行。
  - 设计哲学：这种“默认串行，显式并行”的架构避免了过度并行化导致的“异步/await意大利面代码”和调试噩梦，将开发者的心智模型从“我需要锁定什么？”转变为“什么可以安全地并行化？”。
3）智能体运行器 (Agent Runner)
  - 系统的AI核心，负责决定使用哪个模型和API密钥。
  - 具备故障切换能力：当首选模型或密钥失败时，会将该配置标记为冷却状态并尝试下一个可用选项。
  - 动态组装系统提示（System Prompt），整合可用的工具、技能和内存信息，并附加当前会话的历史记录（从.jsonl文件中读取）。
  - 内置“上下文窗口守卫”，监控上下文空间。当接近上限时，它会通过总结（压缩）会话来释放空间，或在无法处理时优雅地失败。
4）LLM API调用 (LLM API Call)
  - 一个封装了不同LLM提供商的抽象层。
  - 支持流式响应，并在模型支持的情况下请求延长思考时间。
5）Agentic循环 (Agentic Loop)
  - 当LLM返回工具调用请求时，Clawdbot会在本地执行该工具。
  - 将工具执行结果添加回对话历史中，并再次调用LLM。
  - 此循环会重复进行，直到LLM返回最终的文本响应或达到最大交互轮次（默认为约20轮）。
  - 所有与计算机的交互都在这个循环中发生。
6） 响应路径 (Response Path)
  - 将最终响应通过原始通道返回给用户。
  - 通过将用户消息、工具调用、执行结果、模型响应等信息以JSON对象的形式逐行写入.jsonl文件，来持久化会话状态，实现基于会话的记忆。

4. 内存系统：简单与实用的结合

OpenClaw通过一个简洁且可解释的双重系统来处理记忆，避免了复杂的记忆合并或压缩机制。

1）双重系统
  - 会话记录 (Session Transcripts)：以.jsonl文件的形式存储，每一行是一个JSON对象，记录了单次交互的完整信息。这构成了其基于会话的短期记忆。
  - 长期记忆文件 (Long-term Memory Files)：以Markdown文件的形式存储在MEMORY[.]md或memory/文件夹中。代理通过一个标准的“写入文件”工具直接创建和修改这些文件，而非依赖特殊的记忆写入API。当新对话开始时，一个钩子（hook）会触发，抓取并总结上一次对话，并将其写入Markdown记忆文件。
2） 混合搜索机制
  - 为了从记忆中检索信息，系统采用了向量搜索和关键字搜索的混合方法，以兼顾语义相似性和精确匹配。
  - 向量搜索：使用SQLite实现，用于捕捉语义相关的内容（例如，搜索“authentication bug”可以找到提及“auth issues”的文档）。
  - 关键字搜索：使用SQLite的FTS5扩展实现，用于查找精确的短语匹配。
3） 系统特点
  - 智能同步：当文件监视器检测到记忆文件发生变化时，会自动触发同步。
  - 可解释的简单性：设计理念倾向于简单明了，而非复杂的“意大利面式”架构。
  - 无遗忘曲线：记忆被永久保存，且旧记忆与新记忆具有同等权重。

5. 计算机集成：OpenClaw的“护城河”

OpenClaw的核心优势之一是其深度集成于本地计算机环境的能力，它通过一套强大的工具集赋予代理直接操作计算机的权限。

1） Shell命令执行
  - 通过一个exec工具，代理可以在用户的机器上运行shell命令。
  - 支持多种执行环境：
    > 沙盒 (sandbox)：默认选项，命令在Docker容器内运行以增强安全性。
    > 主机 (host machine)：直接在用户的操作系统上运行。
    > 远程设备 (remote devices)：在连接的远程机器上执行。
2) 核心工具集
  - 文件系统工具：支持读取、写入和编辑本地文件。
  - 浏览器工具：基于Playwright，并采用语义快照技术进行网页交互。
  - 进程管理工具：用于处理需要长时间运行的后台命令，以及终止进程等。

6. 安全机制：用户授权下的自主性

为了在赋予代理强大能力的同时确保安全可控，OpenClaw采用了一套类似Claude Code的安全模型，其核心理念是在用户允许的范围内给予代理最大的自主权。

1) 命令审批系统
  - 通过一个位于~/.clawdbot/exec-approvals.json的许可名单文件来管理命令授权。
  - 当智能体尝试执行一个新命令时，会向用户发出提示，选项包括“允许一次”、“始终允许”或“拒绝”。
  - 用户的选择会被记录在许可名单中。
2） 默认安全设置
  - 一组被认为是安全的命令（如 jq, grep, cut, sort 等）已被预先批准。
  - 危险的shell构造在执行前会被默认阻止。

7. 浏览器交互：语义快照的创新应用

OpenClaw的浏览器工具不依赖传统的屏幕截图，而是采用一种名为“语义快照”的创新技术，这是一种基于页面可访问性树（ARIA）的文本表示。

1) 工作原理
  - 代理看到的不是页面的视觉图像，而是一个结构化的文本描述
2) 核心优势
  - 大幅减小数据体积：一张屏幕截图的大小约为5MB，而一个语义快照通常小于50KB。
  - 显著降低Token成本：文本表示的处理成本远低于图像，为LLM节省了大量的Token消耗。
  - 机器友好：为代理提供了结构化、易于解析的页面信息，使其能够更准确地理解和操作网页元素。

原文：x.com/hesamation/status/2017038553058857413

#HOW I AI#  #程序员#