OpenClaw 的工作原理:通过真实架构理解 AI 代理
简而言之：OpenClaw 是一款开源的个人 AI 代理，在 2026 年初迅速突破了 10 万颗 GitHub star。通过研究它的构建方式，包括其网关、代理循环、技能、MCP 和记忆系统，我们可以了解当今所有严肃的 AI 代理的核心概念。
你可能在 X、Reddit 或 Hacker News 上看到过它。OpenClaw（前身是 Clawdbot，然后是 Moltbot）是目前最受关注的开源人工智能项目之一，原因显而易见。
它运行在您的本地计算机上，可以连接到 WhatsApp、Telegram 和 Slack 等即时通讯应用，并能代表您执行各种实际操作：读写文件、运行 shell 命令、发送电子邮件、浏览网页、管理您的日历。用户反馈称，他们甚至让它全权负责处理谈判、保险纠纷和日程安排等事宜。
人们称它为“长着手的克劳德”。这个说法很有趣。但从工程学的角度来看，这究竟是怎么回事呢？
本文旨在探讨这个问题。我不想再写一篇安装指南，而是想把 OpenClaw 当作教学工具。它的架构简洁明了，开源地实现了当今所有严肃的 AI 智能体赖以运行的模式：智能体循环、工具使用、上下文注入和持久化记忆。一旦你理解了 OpenClaw 的工作原理，你也就理解了智能体的一般工作原理。
在深入了解架构之前，有必要先明确 OpenClaw 是什么以及它不是什么。
OpenClaw 不是聊天机器人，而是一个运行在您的计算机或虚拟专用服务器上的本地网关进程。该网关连接到您已使用的消息平台，并将所有传入消息路由到一个基于 LLM 的代理。该代理可以回复文本消息，但更重要的是，它还可以在现实世界中采取行动。
你可以自带API密钥，用于你想要使用的任何模型：Claude、GPT、Gemini，或者通过Ollama运行的完全本地化的模型。OpenClaw与模型无关。
乍一看，它像是一个智能消息助手。但实际上，它是一个用于人工智能代理的本地编排平台。接下来，我们将深入探讨二者之间的区别。
OpenClaw 中的所有数据都通过一个名为Gateway的单一进程进行处理。官方文档将其描述为会话、路由和通道连接的“唯一数据源”。你可以把它想象成整个系统的神经系统。
网关通常作为长时间运行的后台进程运行（通常systemd在 Linux 上 ，LaunchAgent在 macOS 上）。客户端通过 WebSocket 连接到配置的绑定主机，默认为ws://127.0.0.1:18789。
网关负责路由、连接、身份验证和会话管理。代理运行时负责推理和执行。这种职责分离是刻意为之且至关重要的。
这是第一个值得深入理解的架构概念：真正的 AI 代理部署始终在模型之前有一个编排层。您不会将原始的 LLM API 调用直接暴露给用户输入。您需要在两者之间放置一个受控进程，负责处理路由、编排和状态管理。OpenClaw 将这种模式具体化且易于理解。
当你向 OpenClaw 发送 WhatsApp 消息时，首先发生的是通道适配器对其进行规范化。
OpenClaw 支持十几个通讯平台。这些平台集成使用适配器库（例如，常见的 WhatsApp 使用 Baileys，Telegram 使用 grammY），Slack、Discord、Signal、iMessage 和 WebChat 也都有类似的适配器。每个平台都使用不同的协议，并以不同的格式发送消息。WhatsApp 的语音消息和 Slack 的文本消息看起来完全不同。
通道适配器会将所有这些信息转换为一个单一且一致的消息对象，其中包含发件人、正文、附件和元数据。如果您发送语音消息，它会在到达模型之前被转录成文本。
这是所有生产级AI流程中都会出现的模式：在模型接收到输入数据之前，先对其进行规范化处理。传递给LLM的上下文至关重要。混乱或不一致的输入会导致混乱的输出。
网关收到规范化消息后，需要决定由哪个代理处理该消息以及该消息属于哪个会话。
OpenClaw 支持多代理路由。您可以为不同的渠道、联系人或群组配置不同的代理。例如，一个代理可以以轻松的语气处理个人私信，并拥有访问您日历的权限；另一个代理则可以以更正式的风格管理团队支持渠道，并拥有访问产品文档的权限。所有这些都通过一个网关进程运行。
每个代理都维护着自己的会话：会话是对正在进行的对话的一种有状态的表示。会话具有 ID，会跟踪历史记录，并且会序列化执行过程。最后一点值得注意。
OpenClaw每次只处理会话中的一条消息，而不是并行处理。这是由命令队列 (Command Queue)实现的，文档中对此有明确的解释：按会话通道进行序列化可以防止工具冲突并保持会话历史记录的一致性。如果来自同一会话的两条消息同时运行，它们可能会破坏状态或产生相互冲突的工具输出。
这是一个重要的工程教训。当代理共享状态时，并发是危险的。按会话串行执行是刻意的设计选择，而不是限制。
这是OpenClaw的核心，也是所有AI智能体的核心概念。官方文档是这样描述的：
代理循环是代理的完整运行过程：接收 > 上下文组装 > 模型推理 > 工具执行 > 流式回复 > 持久化。
在模型接收到您的消息之前，代理运行时会组装一个上下文包。根据文档，系统提示由以下四个部分组成：
OpenClaw 的基本提示：代理始终遵循的核心指令
技能提示：一份简洁的可用技能列表（名称、描述、路径），用于告知模型有哪些技能可用。
Bootstrap 上下文文件：提供环境级上下文的工作区文件
模型没有眼睛。它只能处理你输入到其上下文窗口中的信息。上下文构建并非可以忽略的预处理步骤。可以说，它是任何智能体系统中最重要的工程决策。模型所知道的一切、所相信的一切以及所能做的一切，都经过这一阶段。
组装好的上下文会以标准 API 调用的形式发送给您配置的提供商（Anthropic、OpenAI、Google、Ollama 等）。OpenClaw 会处理一些重要的细节：强制执行模型特定的上下文限制，并维护一个压缩储备（一个为模型响应预留的令牌缓冲区），以确保模型永远不会因为空间不足而无法响应。
接下来事情变得有趣起来。当LLM做出响应时，它会执行以下两种操作之一：
工具调用是指模型以结构化格式输出类似这样的信息：“我想用这些特定参数运行这个特定工具。” 可以把它想象成模型在说“我需要读取这个文件”、“我需要搜索网络”或“我需要发送这封邮件”。
OpenClaw 的代理运行时会拦截该请求，执行相应的工具，捕获结果，并将其作为新消息反馈到对话中。模型看到结果后会决定下一步操作，例如调用另一个工具或最终回复。
这个循环被称为ReAct循环（Reason + Act的缩写）。它是智能体人工智能的定义模式，也是智能体与聊天机器人的区别所在。
while True :
response = llm.call(context) if response.is_text():
send_reply(response.text) break if response.is_tool_call():
result = execute_tool(response.tool_name, response.tool_params)
context.add_message( “tool_result” , result)
# 循环继续
OpenClaw 也采用了同样的循环模式，实时地将部分响应流式传输回用户。您可以观察工具的调用过程、结果的返回情况，并在模型做出响应之前观察其推理过程。
技能是 OpenClaw 中最优雅的功能之一，它们也是对真正的提示工程技术的清晰演示。
技能是一个包含文件的文件夹。该 Markdown 文件包含自然语言指令、示例，有时还包含工具配置，SKILL.md用于告诉代理如何处理特定领域，例如管理 GitHub 代码库、审查拉取请求或与特定 API 交互。
—
名称：github-pr-reviewer描述：审核 GitHub 拉取请求并发布反馈
— # GitHub PR 审核员
当被要求审核拉取请求时：
1.使用 web _fetch 工具从 GitHub URL 获取 PR 差异
2. 分析差异的正确性、安全问题和代码风格
3. 审核结构如下：摘要、发现的问题、建议
4. 如果被要求发布审核，请使用 GitHub API 工具提交
始终保持建设性。将阻塞性问题与建议分开标记。
现在，这里是容易出错的部分。OpenClaw 并不会将每个SKILL.md技能的完整文本注入到系统提示符中。相反，上下文组装步骤会注入一个精简的可用技能列表，基本上只包含技能名称、描述和文件路径。模型读取此列表，并在判断某个特定技能与当前任务相关时，按需读取该技能。
这是一个重要的架构区别。该模型并非被动地接收指令，而是主动决定需要参考哪些技能，并根据需要加载它们。上下文窗口是有限的，这种设计使得无论安装了多少技能，基础提示框都能保持简洁。
技能可以从 OpenClaw 的社区注册中心ClawHub安装，也可以自行编写。值得注意的是：思科的研究人员警告称，社区技能可能导致数据静默泄露和提示注入式攻击。Snyk 安全审计扫描了数千个社区技能，发现其中相当一部分存在严重问题，包括提示注入、恶意软件和凭证窃取。安装技能前务必进行审查，尤其是那些与电子邮件或浏览器自动化等敏感工具交互的技能。
如果你读过我之前关于MCP的文章，你就会明白这里发生了什么。
部分 OpenClaw 部署方案将 MCP 服务器集成为标准化工具层，从而将代理连接到外部服务，例如 Google 日历、Notion、Home Assistant 或自定义 API。该项目正在积极开发原生 MCP 支持，目前已有社区适配器支持此功能。
基本思路很简单。MCP 服务器不会对每个外部集成进行硬编码，而是公开一组具有预定义模式的工具。代理程序会发现哪些工具可用，使用标准请求格式调用它们，并接收结构化的结果。
代理程序从不直接接触底层服务。它调用一个标准接口，其余部分由 MCP 服务器处理。这赋予了工具良好的可移植性：为一个 MCP 兼容代理程序构建的工具可以复用于其他使用相同协议的系统。
问问任何一位人工智能工程师，智能体系统中最大的难题是什么，记忆力肯定会名列前茅。大语言模型（LLM）本质上是无状态的。每一次新的对话都从一张白纸开始。那么，如何构建一个智能体，使其能够记住你的偏好、正在进行的项目以及你的沟通风格，并能跨越数天甚至数周的时间呢？
OpenClaw 的答案刻意保持简洁，我认为这是整个项目中最好的设计决策之一。
内存信息存储在代理工作区内的纯 Markdown 文件中，默认为~/.openclaw/workspace。OpenClaw 的配置和状态（凭据、会话、日志、已安装的技能）位于~/.openclaw/。
~/.openclaw/workspace/
+– AGENTS.md <– 代理配置和说明
+– SOUL.md <– 个性、偏好、语气
+– MEMORY.md <– 长期事实和摘要
+– HEARTBEAT.md <– 主动任务清单
+– memory/
+– 2026-02-15.md <– 每日临时日志
+– 2026-02-16.md <– 每日临时日志
每日日志（memory/YYYY-MM-DD.md）是持久化的、仅追加的文件，用于记录每天发生的事情。重要的是，这些日志不会在每次交互时自动注入到上下文中。代理仅在日志与当前任务相关时才通过内存工具按需检索它们。这可以保持日常对话的简洁性，避免不必要的上下文膨胀。
MEMORY.md存储代理了解到的关于您的长期事实：例如“用户喜欢简洁的回复”、“用户的技术栈是 Next.js 和 Supabase”或“从不在星期五安排会议”。
SOUL.md 文件定义了代理的个性、名称和沟通风格。这使得它感觉像是你的助手，而不是一个普通的机器人。
当加载所有历史记录导致上下文窗口超出限制时，OpenClaw 会执行压缩过程。它将较早的对话转折汇总成压缩条目，在保留语义内容的同时减少词元数量。这为基于 LLM 的系统中的长上下文问题提供了一种切实可行的解决方案。
对于内存检索，OpenClaw 支持基于嵌入的搜索，并可选择使用sqlite-vecSQLite 扩展来加速搜索。某些部署方案会根据配置将此功能与基于关键字的搜索相结合，从而同时实现概念匹配和精确的词元匹配。
无需外部数据库，无需 Redis，无需 Pinecone，只需 SQLite 和 Markdown 文件。这提醒我们，在工程领域，真正解决问题的最简单方案通常才是正确的方案。
OpenClaw 最有趣的地方之一在于它不会只是被动地等待你发送消息。它会运行心跳机制：一个默认每 30 分钟触发一次的定时触发器。
每次心跳时，代理都会读取HEARTBEAT.md一个待办事项清单，该清单列出了它应该主动检查的任务。它会判断是否有任何事项需要立即处理。如果有，它会采取行动，并可能向您发送消息。如果没有需要处理的事情，它会回复HEARTBEAT_OK，但网关会屏蔽此回复，并且不会将其发送给您。
这种模式使得 OpenClaw 能够主动而非被动地执行任务。其架构理念是cron 触发的智能体循环：智能体并非仅仅响应人类输入，而是定期被唤醒并评估其任务列表。你可以利用它给自己发送每日简报、监控网站变更，或者在你注意到之前就发现日历冲突。
以下是一条消息在 OpenClaw 中流转的完整过程：
大多数现代代理框架虽然API和抽象层各不相同，但其核心模式基本相同。以OpenClaw为例，这些模式就清晰可见：
-
-
推理之前，上下文组装步骤会将历史记录、内存和指令打包在一起
-
ReAct循环中，模型进行推理、调用工具并整合结果
-
-
一种技能或提示系统，可按需加载，为代理提供特定领域的专业知识。
-
-
OpenClaw并非唯一使用这些模式的Claw。它的价值在于将这些模式具象化、文件化和可读化。您可以打开文件SOUL.md，查看代理正在执行的具体指令。您可以阅读任何文件SKILL.md，并准确理解某项功能是如何添加的。您可以检查MEMORY.md和审核代理所了解的关于您的所有信息。
这种透明性既是其最大的工程优势，也是其最大的安全隐患。一个能够访问您的文件、浏览器、电子邮件和即时通讯应用的代理程序功能强大。理论上，恶意技能或通过代理程序访问的网页发起的提示注入攻击都可能危及所有这些安全。因此，在将网关暴露给网络之前，务必运行安全审计工具，并在安装任何第三方技能之前对其进行审查。
# 全局安装（需要 Node.js 22+）
npm install -g openclaw@latest
# 运行引导式引导安装向导
openclaw onboard –install-daemon
# 在公开任何内容之前运行安全审计
openclaw security audit –deep
引导向导会引导您完成网关设置、通道配置和技能安装。命令可能会随版本更新而变化，因此如果发现任何异常，请查看docs.openclaw.ai上的官方 CLI 文档。
OpenClaw 在 2026 年初成为 GitHub 上增长最快的代码库之一。开发者社区不仅仅是在认可一个实用的工具，他们更是在认可一种架构模式。本地网关 + 代理循环 + 技能 + 持久记忆模型将在未来很长一段时间内成为个人 AI 代理的蓝图。
如果你一直想了解人工智能代理的底层工作原理，OpenClaw 是你能找到的最佳实际案例之一。它的代码采用 MIT 许可证，架构清晰易读，并且它所实现的概念与主流人工智能公司生产环境中使用的代理系统所采用的概念相同。
去阅读源代码。打开一个文件SKILL.md。编辑你的文件SOUL.md。搞砸一些东西。这才是真正学习的方法。
夜雨聆风
