一、从技术本质定义 OpenClaw

OpenClaw（曾用名 Moltbot/Clawdbot）是一款极具参考价值的个人 AI 助手，支持本地部署并通过大模型 API 调用，可实现手机端轻松操作。但它的技术本质究竟是什么？

OpenClaw 的核心，是一个基于 TypeScript 开发的命令行界面（CLI）应用。

划重点：它既非 Python 开发的项目，也不是 Next.js 应用，更不是传统的网页应用。

作为一个独立运行的进程，OpenClaw 主要实现以下4 大核心功能：

  1. 网关服务：在本地设备运行，处理所有渠道（如 Telegram、WhatsApp、Slack 等）的连接请求。
  2. 模型调用：对接各类大模型 API（Anthropic、OpenAI、本地大模型等）。
  3. 工具执行：在本地执行各类工具命令。
  4. 用户操作：实现用户在电脑上的各类操作需求。

二、核心架构全解析（从发消息到收回复）

为了更通俗地解释其架构设计，以下以“用户发送消息到收到回复”的全流程为例，拆解具体执行步骤。

OpenClaw.jpeg

当你在即时通讯工具中向 OpenClaw 发送指令后，系统会依次执行以下6 个环节：

1. 渠道适配器：消息的“预处理中转站”

渠道适配器负责接收消息并进行预处理，核心任务是标准化消息格式与提取附件。

  • 关键设计：针对不同的即时通讯工具（Telegram、WhatsApp 等）和输入流，配有专属适配器，避免格式混乱。

2. 网关服务：系统的“核心枢纽”

网关服务是整个系统的任务与会话协调中心，核心作用包括：

  1. 接收预处理后的消息，将其精准分发至对应的会话。
  2. 支持处理多个重叠的请求，避免冲突。

这里有一个非常值得借鉴的设计——基于通道的命令队列：

  • 每个会话都有专属的执行通道，保证单个会话的操作有序执行。
  • 低风险、可并行的任务（如定时任务），则可在并行通道中运行，兼顾效率。

这个设计彻底规避了传统异步/等待（async/await）代码的混乱嵌套问题。过度并行化会严重降低系统可靠性，还会引发大量难以调试的 Bug。

核心设计原则：默认序列化执行，显式声明并行执行。

但凡做过智能体开发的工程师，想必都有过类似的踩坑经历。这一思路，也与 Cognition 公司在《别再构建多智能体系统》博文中的核心观点不谋而合。

  • 反例：如果为每个智能体简单配置异步执行，最终只会得到一堆交错混乱的执行结果——日志杂乱无章、无法追溯；若多个智能体共享状态，还需时刻警惕竞态条件的问题。
  • OpenClaw 的优化：将“通道”设计为队列的上层抽象，把“序列化执行”作为默认架构（而非后期补充的优化）。

这一设计直接改变了开发思维：从思考“我需要为哪些内容加锁？”，转变为思考“哪些操作并行执行是安全的？”，极大降低了开发复杂度。

3. 智能体运行器：AI 能力的“承载者”

这是真正承载 AI 能力的核心模块，全程自动化处理，核心工作有4 件事：

  1. 自动匹配适配的大模型。
  2. 匹配对应的 API 密钥（若当前密钥失效，自动将该配置标记为冷却状态，尝试下一个）。
  3. 主模型调用失败时，自动降级至备用模型，保证可用性。
  4. 动态拼接系统提示词。
重点细节：智能体运行器会结合可用工具、技能、记忆数据，动态拼接系统提示词，再加入会话历史记录（存储在 .jsonl 文件中），生成完整的大模型输入内容。

除此之外，它还会调用“上下文窗口守卫模块”，校验是否有足够的上下文空间。若上下文即将占满，系统会要么对会话内容进行压缩（总结上下文），要么优雅地终止请求，避免崩溃。

4. 大模型 API 调用：结果的“生成环节”

这一环节主要负责实际的大模型调用，核心亮点有两个：

  1. 以流式方式返回结果，提升用户体验。
  2. 对不同大模型提供商的 API 做了抽象封装，实现调用层统一，后续切换模型无需大幅修改代码。
补充：若所调用的大模型支持，该模块还能触发“深度思考”功能，提升回复的准确性。

5. 智能体循环：工具调用的“核心循环”

这是 OpenClaw 实现复杂操作的关键环节，逻辑很简单：

若大模型返回的是工具调用指令，OpenClaw 会在本地执行该指令，并将执行结果添加至会话中。这一过程不断循环，直到大模型返回最终文本回复，或达到最大循环次数（默认约 20 次）。

划重点：OpenClaw 的核心亮点——电脑操作能力，就是在这个环节实现的。

6. 回复通路：结果的“反馈与留存”

这一环节的逻辑十分标准，核心是"反馈 + 留存"：

  1. 反馈：回复内容通过原输入渠道（如微信、Telegram）反馈给用户，保证体验连贯。
  2. 留存：会话数据被持久化存储在 .jsonl 文件中。文件中每一行都是一个 JSON 对象，包含用户消息、工具调用记录、执行结果、AI 回复等全量信息。

而这，也是 OpenClaw 实现记忆功能的核心方式——基于会话的记忆。

以上就是 OpenClaw 的基础架构流程，接下来我们聚焦 3 个最关键的核心组件，拆解其中的设计亮点。

三、OpenClaw 的记忆管理机制（不做“金鱼式”AI）

没有完善的记忆系统，一款 AI 助手的能力就会像金鱼一样转瞬即忘。OpenClaw 通过两套系统，实现了高效的记忆管理，设计简洁却实用。

两套记忆存储系统

  1. 会话记忆：前文提到的 JSONL 格式会话记录文件，存储每一次会话的全量信息。
  2. 长期记忆：存储在 MEMORY.md 文件或 memory/ 文件夹中的 Markdown 格式记忆文件，用于长期留存关键信息。

混合检索方案（向量 + 关键词）

OpenClaw 采用向量检索 + 关键词匹配的混合方案，兼顾语义匹配的灵活性和关键词匹配的精准性，这是非常实用的设计。

举个例子：搜索“认证漏洞（authentication bug）”时，既能检索到提及“认证问题（auth issues）”的文档（语义匹配，捕捉同义表达），也能精准匹配到包含该精确短语的内容（关键词匹配，锁定核心）。

技术实现细节（可直接借鉴）

  1. 向量检索：基于 SQLite 实现，无需额外部署复杂的向量数据库，降低部署成本。
  2. 关键词检索：依托 SQLite 的扩展插件 FTS5 实现，轻量化且高效。
  3. 嵌入向量：生成提供商支持自定义配置，适配不同的大模型需求。

简洁却高效的记忆同步与生成

两个关键设计，保证记忆的及时性和简洁性：

  1. 智能同步：文件监视器检测到记忆文件变化时，自动触发同步更新，无需手动操作。
  2. 自动生成：记忆文件由智能体通过标准的文件写入工具生成，无需专属的记忆写入 API——智能体只需直接向 memory/*.md 路径写入内容即可。
补充：新会话启动时，系统会自动抓取上一次会话内容，生成 Markdown 格式的总结，存入长期记忆，实现记忆的连贯。

OpenClaw 的记忆系统设计异常简洁，与我们在 CamelAIOrg 中实现的工作流记忆高度相似：无需记忆合并，也没有月度/周度的记忆压缩操作。

这种简洁性见仁见智，但我始终推崇——可解释的简洁设计，远优于混乱复杂的嵌套式设计。

另外一个特点：OpenClaw 的记忆会永久保存，且新旧记忆的权重基本一致，不存在所谓的“遗忘曲线”。

四、核心竞争力：电脑操作能力（OpenClaw 的“护城河”）

OpenClaw 最核心的优势，就是能直接操作你的电脑——这也是它的核心护城河之一。其实现逻辑很直观，但设计很严谨。

核心逻辑：OpenClaw 为智能体赋予较高的电脑操作权限（风险由用户自行承担），通过“执行工具（exec tool）”，在 3 种环境中运行 Shell 命令：

  1. 沙箱环境（默认）：命令在 Docker 容器中运行，隔离本地环境，降低风险。
  2. 本地主机：直接在用户的电脑上运行，适合需要调用本地资源的操作。
  3. 远程设备：在联网的远程终端运行，实现远程控制。

除了 Shell 命令执行，OpenClaw 还内置了3 类核心工具，覆盖大部分电脑操作需求：

  1. 文件系统工具：支持读、写、编辑各类文件，轻松处理本地文档。
  2. 浏览器工具：基于 Playwright 开发，核心特性是“语义快照”（后文详细说）。
  3. 进程管理工具：支持后台长期运行命令、终止进程等，管控电脑运行状态。

五、安全机制设计（或说“是否真的安全？”）

开放电脑操作权限，安全必然是核心关注点。OpenClaw 的安全设计，参考了 Claude Code 的思路，核心是"白名单管控 + 危险命令拦截"。

1. 命令白名单机制

OpenClaw 设计了命令白名单，用户可对命令进行 3 类授权操作（操作时会弹出提示）：单次允许、永久允许、拒绝。

白名单配置文件示例：

// ~/.clawdbot/exec-approvals.json
{
  "agents": {
    "main": {
      "allowlist": [
        { "pattern": "/usr/bin/npm", "lastUsedAt": 1706644800 },
        { "pattern": "/opt/homebrew/bin/git", "lastUsedAt": 1706644900 }
      ]
    }
  }
}

2. 预授权安全命令

一些基础的安全命令（如 jq、grep、cut、sort、uniq、head、tail、tr、wc），已被系统预授权，可直接运行，无需用户额外批准，提升使用效率。

3. 危险命令默认拦截

系统会默认拦截所有危险的 Shell 语法结构，从源头规避风险。示例如下（这些命令会在执行前被直接拒绝）：

# 以下命令在执行前会被直接拒绝：
# these get rejected before execution:
npm install $(cat /etc/passwd)     # command substitution
cat file > /etc/hosts              # redirection
rm -rf / || echo "failed"          # chained with ||
(sudo rm -rf /)                    # subshell

总结：OpenClaw 的安全设计核心原则是——在用户授权的范围内，赋予智能体最大的自主操作能力，兼顾安全性和灵活性。

六、浏览器工具亮点：语义快照技术

OpenClaw 的浏览器工具，没有采用传统的截图方式，而是用了一种更高效的设计——语义快照。

核心定义：基于页面的可访问性树（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"

这一设计带来了4 大显著优势，尤其适合 AI 处理：

  1. 轻量化：一张普通网页截图约 5MB，而语义快照不足 50KB，大幅节省存储和传输成本。
  2. 低令牌消耗：文本形式的快照，令牌消耗仅为图片的几分之一，降低大模型调用成本。
  3. 易解析：AI 可直接识别文本描述的元素（按钮、文本框等），无需进行图像识别，提升操作效率。
  4. 通用性强：不受页面样式、分辨率影响，适配所有网页。

最后总结

OpenClaw 的架构设计，整体给人的感觉是"简洁、实用、可落地"——没有复杂的冗余设计，每一个模块都有明确的目标，尤其适合 AI 工程师借鉴学习。

核心可借鉴的 3 个点：

  1. 序列化优先的队列设计，规避并行带来的可靠性问题。
  2. 简洁高效的混合记忆系统，兼顾轻量化和实用性。
  3. 安全可控的电脑操作权限管控，平衡灵活性和安全性。

对于 AI 工程师来说，研究这类成熟的开源项目（OpenClaw 可本地部署），远比单纯看理论文档更有收获——看懂它的底层实现，能帮我们更快地规避踩坑，提升自己的系统设计能力。

原文链接：

https://blog.jsdiff.com/archives/openclawjia-gou-jie-xi

说明：本文基于作者当时研究的 OpenClaw 版本架构进行解析，具体功能细节可能随项目迭代有所调整，请以官方最新文档为准。