OpenClaw 工作原理与架构解析

智能摘要

OpenClaw的核心是一个基于TypeScript的命令行应用，通过网关服务器协调多通道通信与任务调度，采用默认串行的任务通道队列避免竞态问题。其智能体运行器动态生成提示词并调用大模型API，结合工具执行实现本地电脑操作，支持Shell命令、文件读写与浏览器控制。记忆系统由jsonl会话日志和Markdown记忆文件构成，通过向量与关键词混合检索实现信息召回，具备简洁但持久的无衰减存储机制。

— 此摘要由AI生成仅供参考。

OpenClaw 工作原理

Hesam@Hesamation 原文来自 Hesam (@Hesamation) 发布于 X 的文章，链接见文末。

我研究了 OpenClaw 的架构，以及它处理智能体执行、工具调用、浏览器操作等功能的实现逻辑，其中诸多设计思路对 AI 工程师极具借鉴价值。深入了解 Clawd 的底层运行机制，能让我们更清晰地认识这套系统的功能边界，更重要的是，明确它的优势与短板。我最初的研究初衷，只是出于个人好奇，想探究 Clawd 的记忆机制设计及其运行可靠性。

在本文中，我将为大家浅述 Clawd 的核心运行原理。

Clawd 的技术本质

大家都知道，OpenClaw 是一款个人智能助手，可本地部署或通过大模型 API 调用，甚至在手机上就能轻松操作，但它的技术本质究竟是什么？ OpenClaw 的核心是一个基于 TypeScript 开发的命令行应用（CLI），既非 Python 开发、也非基于 Next.js 的网页应用。作为一个独立运行进程，它的核心功能包括：

在本地设备运行并启动网关服务器，处理全渠道连接（电报、WhatsApp、斯拉克等）；
调用大语言模型 API（Anthropic、OpenAI、本地模型等）；
本地执行各类工具指令；
实现用户对电脑的各类操作需求。

技术框架

为了更通俗地解释其架构，我们以“向 Clawd 发送消息到获取反馈”的完整流程为例说明。

v2-7d2d042ede9e467214d5e34e7781ef57_1440w

（流程链路：用户消息 → 通道适配器 → 网关服务器 → 会话路由器 → 智能体运行器 → 模型解析器 → 系统提示词构建器 → 历史加载器 → 会话 → 任务通道队列 → 上下文窗口防护机制 → 大语言模型 API → 智能体循环 → 反馈通路 → 通道适配器 → 最终文本）

在即时通讯工具中向 Clawd 发送指令后，会依次触发以下环节：

1.通道适配器

通道适配器接收用户消息并进行预处理，包括消息标准化、提取附件等。不同的即时通讯工具和输入流，都配有专属的适配器。

2.网关服务器

作为任务与会话的协调中枢，网关服务器接收用户消息并将其分发至对应会话，是 Clawd 的核心模块，可处理多个并行的请求。为实现操作序列化，Clawd 采用了基于任务通道的命令队列：每个会话对应专属的任务通道，低风险、可并行的任务（如定时任务）则可在多个通道中并行执行。这与编写混乱的异步/等待（async/await）嵌套代码形成了鲜明对比——过度并行化会降低系统可靠性，还会引发大量难以调试的问题。

Clawd 的设计原则为：默认串行执行，显式声明并行。

从事智能体开发的开发者想必对此深有体会，这也是 Cognition 公司在博文中传递的核心观点。为单个智能体搭建简单的异步架构，最终只会产生杂乱无章的交错代码，日志无法阅读；若多个智能体共享状态，开发过程中还需时刻警惕竞态条件问题。

而任务通道是对队列的一层抽象，将序列化作为默认架构设计，而非后续的补充优化。开发者只需编写业务代码，队列会自动处理竞态条件问题，开发思路也将从“需要为哪些内容加锁”转变为“哪些操作可以安全地并行执行”。

3.智能体运行器

这是真正承载 AI 能力的模块。该模块会确定待调用的模型、匹配对应的 API 密钥（若密钥失效，会将该配置标记为冷却状态并尝试下一个），若主模型调用失败，会自动切换至备用模型。智能体运行器会结合可用工具、技能、记忆内容动态生成系统提示词，再加入会话历史（存储于.jsonl 文件），随后将完整提示词传入上下文窗口防护机制，校验是否有足够的上下文空间。若上下文空间即将耗尽，系统会选择压缩会话内容（对上下文进行总结）或优雅降级终止执行。

4.大语言模型 API 调用

大模型调用环节会以流式方式返回结果，同时对不同服务商的 API 做了一层抽象封装；若所调用的模型支持深度思考功能，该模块还会触发模型的扩展思考逻辑。

5.智能体循环

若大模型返回工具调用指令，Clawd 会在本地执行该指令，并将执行结果补充至对话中。这一过程会反复执行，直至大模型返回最终文本结果，或达到最大循环次数（默认约 20 次）。正是在这一环节，Clawd 实现了其核心能力——电脑操作功能。

6.反馈通路

这一环节的逻辑较为常规：执行结果会通过原消息通道反馈给用户，同时会话数据会以基础的 jsonl 格式持久化存储，文件中每行都是一个 json 对象，记录了用户消息、工具调用指令、执行结果、模型反馈等内容，这也是 Clawd 的记忆实现方式——基于会话的记忆机制。

以上就是 Clawd 的基础架构，接下来我们聊聊其中几个关键的核心模块。

Clawd 的记忆机制

没有完善的记忆系统，AI 助手的能力便会大打折扣。Clawd 通过两套系统实现记忆功能：

1、前文提到的、以 jsonl 格式存储的会话记录； 2、存储为 Markdown 格式的记忆文件，文件位于 MEMORY.md 或 memory/文件夹中。

在检索环节，Clawd 采用了向量检索与关键词匹配相结合的混合检索方式，兼具两种方式的优势。例如检索“认证漏洞（authentication bug）”时，系统既能找到提及“认证问题（auth issues）”的文档（语义匹配），也能精准定位包含该精确短语的内容（关键词匹配）。

其中，向量检索基于 SQLite 实现，关键词检索则借助 SQLite 的扩展模块 FTS5 完成，嵌入向量生成服务商支持自定义配置该系统还搭载了智能同步功能，当文件监视器检测到文件变化时，会自动触发同步。这些 Markdown 记忆文件由智能体通过常规的“写入”文件工具生成，无专属的记忆写入 API，智能体只需向 memory/*.md 路径写入内容即可。

当新的对话开始时，系统会提取上一轮的对话内容，并将其总结为 Markdown 格式的文件。

Clawd 的记忆系统设计出乎意料地简洁，与我们在[项目名称]中实现的工作流记忆机制高度相似：无需合并记忆文件，也无需按每月/每周的周期压缩记忆内容。这种简洁性是优势还是缺陷，因人而异，但我始终推崇可解释的简洁设计，而非混乱复杂的架构。

Clawd 的记忆会永久保存，且新老记忆的权重基本一致，不存在记忆衰减曲线。

Clawd 的核心能力：电脑操作实现

这是 Clawd 的核心壁垒之一：可接管本地电脑并实现各类操作。其实现逻辑与大家的直观认知基本一致。

Clawd 会向智能体开放较高权限的电脑操作能力，相关风险由用户自行承担。它通过执行工具（exec tool）在设备上运行 Shell 命令，支持三种运行环境：

沙箱环境（默认）：命令在 Docker 容器中运行；
本地宿主机；
远程设备。

除此之外，Clawd 还配备了各类工具：

文件系统工具（支持读取、写入、编辑）；基于 Playwright 实现的浏览器工具，可生成语义快照；进程管理工具，用于执行后台长期运行的命令、终止进程等。

安全机制（或近乎缺失？）

与 Claude Code 类似，Clawd 为用户设置了命令白名单，用户可对各类命令进行权限审批，支持三种操作：单次允许、始终允许、拒绝，并会向用户弹出审批提示。

代码块示例：命令审批配置文件

{
"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 语法结构会被拦截。代码块示例：被拦截的危险命令

以下命令在执行前会被拒绝：

cat file > /etc/hosts # 重定向
rm -rf / || echo "failed" # 逻辑或链接
(sudo rm -rf /)           # 子 shell`

Clawd 的安全机制与 Claude Code 的设计思路高度相似，核心是在用户允许的范围内，给予智能体最大的自主操作权限。

浏览器工具：语义快照而非截图

Clawd 的浏览器工具并非主要依赖截图，而是采用语义快照——一种基于页面无障碍树（ARIA）的文本化表示形式。

所以Agent将看到：

- 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，且仅占图像代币成本的一小部分。

好了，既然我们已经介绍了主要组成部分，以下是一些有趣的细节：

动态系统提示词

与大多数框架不同，Clawd 的系统提示词并非固定不变，而是结合技能、记忆检索结果、用户身份、时区等信息动态构建。其基础系统提示词如下：

## 工具集
可用工具（按策略筛选）：工具名称区分大小写，需严格按列出的名称调用。
- read：读取文件内容 
- exec：运行 Shell 命令 
- browser：控制网页浏览器
[...仅显示该智能体可访问的工具]

## 工具调用风格
默认规则：常规、低风险的工具调用无需说明（直接调用即可）；
仅在以下场景需补充说明：多步骤操作、复杂问题、敏感操作。

## Moltbot 命令行快速参考
[网关命令参考内容]

## 工作目录
你的工作目录为：/path/to/workspace
将该目录视为唯一的全局工作空间...

##运行时信息
运行环境：智能体=主智能体 | 主机=MacBook | 操作系统=Darwin（arm64架构） | 模型=claude-sonnet-420250514 | 通道=电报 | 思考模式=关闭
推理过程：关闭（仅在开启/流式模式下显示）