一文彻底搞懂 OpenClaw 的架构设计与运行原理（万字图文）

大家好，我是汤师爷，南京大学硕士，前华为、阿里 AI架构师。

全网10万粉AI博主，2本畅销书作家（第3本写作中）。

目前专注AI智能体，致力于帮助100W人用智能体创富~

GitHub史上增长最快的开源项目，18万个star，背后的核心开发者只有一个人。

这种增长速度不只是火了，简直是史无前例。

今天汤师爷就来给大家扒一扒 OpenClaw 的架构设计。

这篇文章会用最简单的大白话，把 OpenClaw 这个让 GitHub 都震惊的项目，从里到外拆开给你看。

不管你是技术小白还是开发老手，读完保证能彻底搞清楚它到底是怎么运作的。

OpenClaw 到底是什么

OpenClaw 是一个个人 AI 助手平台，跑在你自己的设备上，你的笔记本电脑、一台云服务器、机柜里的 Mac Mini，或者一个云容器。

它把 AI 模型和各种工具，连接到你日常用的聊天 App，例如，WhatsApp、Telegram、飞书、钉钉等等。

OpenClaw 把 AI 助手当作基础设施来构建，而不只是优化提示词。

打个比方，普通聊天机器人就像一个只会接电话的客服，你问什么它答什么。

而 OpenClaw 更像是给 AI 搭了一整套办公系统，有会话管理、有记忆系统、有工具权限控制、有消息路由。

AI 模型扮演大脑的角色，OpenClaw 负责帮你落地。

AI 模型的 API 调用还是走 Anthropic、OpenAI 那些服务商，但对话记录、工具执行、会话状态、所有调度逻辑，全部留在你自己的设备上。

下面这些功能，你可以完全自主控制：

• 助手跑在哪里
• 消息怎么路由
• 它能用哪些工具
• 会话之间怎么隔离

OpenClaw 整体系统架构

OpenClaw 的整体架构长什么样，几大组件怎么配合？

OpenClaw 不是一个套了层壳的 AI 聊天机器人，它是一个AI Agent 的操作系统。

它采用调度中心架构，就像一个机场调度中心，所有航班（消息）都经过一个中央塔台（Gateway 网关），由它分配到正确的跑道（Agent）。

核心就两大模块：

1. 网关（Gateway）：一个 WebSocket 服务器，连接各种聊天平台和控制界面，把收到的消息派发给 Agent 运行时处理。
2. 智能体（Agent） ：真正干活的核心引擎，组装上下文、调用 AI 模型、执行工具操作（比如浏览网页、操作文件、定时任务等）、保存状态。

关键设计思想： 把消息通信、接口层和AI 怎么思考和执行（Agent）彻底分开。

这样你就有了一个统一的 AI 助手，不管你从 WhatsApp、飞书 还是钉钉发消息，它都能接入。

而且会话状态和工具权限都在你的设备上集中管理。

通过插件实现可扩展性

那么OpenClaw 怎么让别人在不改核心代码的情况下，扩展新功能？

OpenClaw 的设计哲学是开放扩展，不改核心。

你可以通过插件（Plugin）在四个方向上扩展：

• 渠道插件（Channel Plugin）：添加新的聊天平台，比如 飞书、钉钉等
• 记忆插件（Memory Plugin）：换一种存储后端，比如用向量数据库代替默认的 SQLite
• 工具插件（Tool Plugin）：添加自定义能力，比如除了内置的命令行、浏览器、文件操作之外的新工具
• 模型提供商插件（Provider Plugin）：接入自定义的 AI 模型或自己部署的模型

插件代码放在 extensions/ 目录下，系统会自动扫描、发现和加载。

OpenClaw 的核心组件

1. 渠道适配器（Channel Adapter）

OpenClaw 怎么对接各种聊天平台，把不同平台的消息翻译成统一格式？

每个聊天平台都有一个专门的适配器。

有些是内置的（比如 Telegram、Discord），有些可以通过插件添加。

不同平台的 API 和协议千差万别，但每个适配器都做同样的四件事：

1. 身份验证（Authentication）
2. 收消息并解析（Inbound Message Parsing）
3. 访问控制（Access Control）
4. 发消息并格式化（Outbound Message Formatting）

身份验证

不同平台的验证方式不一样：

• WhatsApp：用 QR 码配对（通过 Baileys 库），凭据存在本地
• Telegram / Discord：用 Bot Token（机器人令牌），通过环境变量配置
• iMessage：需要 macOS 原生集成，必须在真正的 Mac 上跑

收消息并解析

各平台的数据格式差异非常大，适配器的工作就是把它们统一。

不管消息从 WhatsApp 还是 飞书来，提取出文字、图片、音频、视频、文档、表情反应和回复上下文后，OpenClaw 的其他部分就不用操心平台差异了。

访问控制

这是渠道层面的安全关卡：

• 白名单（Allowlist）：指定哪些手机号/用户名可以跟你的 Bot 对话
• 私聊策略（DM Policy）：默认是配对模式，陌生人发消息得先审批才能通过；也可以设成"开放"（不推荐）或"禁止"
• 群聊策略：可以要求 Bot 只在被 @提到时才回复，还能设群级别的白名单

发消息并格式化

每个平台的 Markdown 格式、消息长度限制、媒体上传方式都不一样。

适配器负责处理这些，长消息自动切分、Markdown 格式转换、媒体文件上传、甚至"正在输入"的提示。

2. 控制界面（Control Interface）

除了聊天 App，你还有哪些方式可以操控 OpenClaw？

OpenClaw 提供了四种交互方式：

网页界面（Web UI）

用浏览器打开 http://127.0.0.1:18789 就行，能聊天、管配置、查会话、监控状态。

不需要额外装 Web 服务器，网关自己就搞定了。

命令行工具（CLI）

喜欢敲命令的人可以用命令行控制一切：

• openclaw gateway 启动网关
• openclaw agent 直接调用 Agent
• openclaw channels login 配对 WhatsApp/Signal
• openclaw message send 编程发消息
• openclaw doctor 跑健康检查
• openclaw onboard 引导式初始设置

macOS 菜单栏应用

用 Swift 写的原生 Mac 应用，可以放在在菜单栏里。

可以一键启动/停止/重启网关，内置聊天界面，还支持语音唤醒。

手机端（Mobile）

iOS 和 Android 的 App 通过 WebSocket 连接到网关，

不光能聊天，还能把手机的摄像头、录屏、定位等能力暴露给 Agent 使用，让你的手机变成 AI 的外挂硬件。

3. 网关控制平台（Gateway Control Plane）

网关是整个系统的大脑中枢，所有消息和指令都经过它。

网关就像一个快递分拣中心，所有包裹（消息）进来后，由它检查收件人信息、分配到正确的分拣线（Agent），最后把回复发出去。

技术细节：

• 基于 Node.js 22+，使用 WebSocket 协议
• 默认只绑定到 127.0.0.1（本机地址），不对外暴露
• 所有 WebSocket 消息都有严格的格式校验，发送格式不对会被立刻拒绝
• 采用事件驱动而非轮询，客户端订阅事件，不用反复处理有没有新消息
• 所有可能产生副作用的操作都需要幂等键（Idempotency Key），防止重复执行

核心设计原则：

• 一台机器只跑一个网关（因为 WhatsApp 协议限制只能单设备）
• 协议全部有类型定义和校验
• 本地连接可以自动信任，远程连接需要验证

4. Agent

Agent 是真正跑 AI 对话和工具执行的地方，相当于 AI 的工作台。

Agent 运行时每一轮对话做四件事：

步骤 1：确定会话（Session Resolution）

消息进来后，先搞清楚这条消息属于哪个会话：

• 你自己发的私聊 ： main 会话（权限最高）
• 别人通过某个平台发的私聊 ：dm:平台:ID 会话
• 群聊消息 ： group:平台:ID 会话

注意： 会话不只是个标签，它还是安全边界。不同类型的会话有不同的权限和沙箱规则。

步骤 2：组装上下文（Context Assembly）

确定会话后，运行时会组装 AI 需要的上下文信息：

• 从磁盘加载该会话的历史记录
• 读取工作空间里的配置文件，拼出系统提示词（System Prompt）
• 通过语义搜索从记忆库里拉取相关的历史对话

步骤 3：调用模型并执行工具（Execution Loop）

AI 模型开始回复时，Agent 会实时监控：

• 如果模型说"我要执行一个命令行命令"，Agent 拦截并执行（可能在 Docker 沙箱里）
• 如果模型说"我要打开浏览器抓个网页"，Agent 启动浏览器去抓
• 工具执行结果实时喂回给AI模型，模型接着往下做

步骤 4：保存状态

对话结束后，把所有消息、工具调用结果都存回磁盘。

系统提示词架构（System Prompt Architecture）

OpenClaw 如何把多个配置文件拼成一份完整的AI 执行计划？

OpenClaw 的系统提示词不是一个写死的文件，而是由多个来源组合拼装而成：

工作空间配置文件：

• AGENTS.md：核心指令，定义 Agent 能做什么、不能做什么（基线规则）
• SOUL.md：人格和语气指导，Agent 说话的风格（可选）
• TOOLS.md：用户写的工具使用备注（可选）

动态上下文（每轮对话实时组装）：

• 会话历史：最近的对话记录
• 技能文件（Skills）：特定任务的操作指南
• 记忆搜索结果：语义相关的历史对话

工具定义（自动生成）：

• 内置工具：命令行、浏览器、文件操作等
• 插件工具：通过扩展系统注册的自定义工具

这种可组合的设计意味着：你只需要编辑工作空间里的文件，就能改变 Agent 的行为、风格和能力，完全不用改源代码。

一个重要细节：

OpenClaw 不会把所有技能一股脑塞进提示词。

它会智能筛选，只注入当前这轮对话需要的技能，避免提示词太长导致 AI 表现下降。

OpenClaw 的交互与协调

1. Canvas 画布和 A2UI

Canvas 是一个由 AI 驱动的可视化工作区，你可以把它理解成一块"画板"，AI 可以在上面画出各种可交互的界面，比如按钮、列表、表单等等。

而 A2UI（Agent-to-UI）就是 AI 用来"画"这些界面的工具。AI 不需要写复杂的代码，只要生成一些带特殊标记的 HTML，就能让界面元素活起来，用户点击后 AI 还能收到反馈并做出响应。

Canvas 是一个独立运行的可视化工作区服务（默认端口 18793），跟主网关是分开的。好处是Canvas 崩了不影响网关正常运行。

交互流程：

1. Agent 调用 Canvas 更新方法，发送一段 HTML
2. Canvas 服务器解析 HTML 里的 A2UI 属性
3. 通过 WebSocket 推送到浏览器
4. 浏览器渲染成可交互的界面

A2UI 全称是 Agent-to-UI，是一套声明式框架。

Agent 只需要生成带特殊属性的 HTML，就能创建按钮、列表等交互元素，不需要写 JavaScript。用户点击按钮后，事件会传回 Agent，Agent 处理完再更新界面。

Canvas 支持 macOS 原生应用、iOS、Android 和 Web 浏览器。

2. 语音唤醒和对话模式（Voice Wake & Talk Mode）

你可以用语音跟 OpenClaw 对话，就像跟 Siri 说话一样。

在 macOS、iOS、Android 上，你可以说"Hey OpenClaw"唤醒助手，或者用快捷键按住说话。

音频会发到 ElevenLabs 做语音识别，Agent 处理后再用语音合成把回复念出来。

对话模式（Talk Mode）支持连续对话，你甚至可以在 Agent 说话时打断它。

3. 多 Agent 路由（Multi-Agent Routing）

你可以让不同的聊天渠道/群组使用完全不同的 AI 助手实例，各自独立。

比如你想让：

• Discord 服务器的 Bot 用 Claude Sonnet，性格像个友好的版主
• Telegram 的客服私聊用 GPT-4，语气更正式，工具权限不同

通过配置就能搞定，每个 Agent 实例有自己的工作空间、模型和行为设定。

这带来了很多玩法：

• 不同社区用不同人设
• 不同场景开放不同工具
• 给不信任的用户设隔离沙箱
• 在一个渠道测试新功能，不影响其他已有的 Agent

4. Agent 之间的通信：会话工具

Agent 之间怎么互相沟通和协作？

OpenClaw 提供了一组会话工具，让不同的 Agent 可以互相传话、协作：

• sessions_list：查看有哪些活跃会话
• sessions_send：给另一个会话发消息
• sessions_history：查看另一个会话的对话记录
• sessions_spawn：创建新会话来委派任务

5. 定时任务（Cron Jobs）和外部触发器（Webhooks）

怎么让 Agent 定时干活或被外部事件触发？

• 定时任务：比如每天早上 9 点自动生成日报
• Webhooks：外部服务（比如飞书多维表格）可以触发 Agent 执行操作

两者都是通过配置文件设置，不需要写代码。

深入解析：一条消息的完整生命周期

从你在 WhatsApp 发一条消息，到收到 AI 回复，中间经历了哪些步骤？

以 WhatsApp 为例，完整流程分 6 个阶段：

阶段 1：消息接收（Ingestion）

网关收到 WhatsApp 服务器的 WebSocket 事件。

WhatsApp 适配器解析这个事件，提取出消息文字、媒体附件和发送者信息。

阶段 2：访问控制与路由（Access Control & Routing）

消息先过安全检查：

• 这个发送者在白名单里吗？
• 如果是第一次私聊，配对审批通过了吗？

没通过？消息到此为止。

通过后，系统确定用哪个会话处理：

• 你自己发的 → main 会话（最高权限）
• 别人的私聊 → dm 会话
• 群聊 → group 会话

阶段 3：上下文组装（Context Assembly）

Agent 运行时加载对应的会话记录，读取配置文件拼出系统提示词，并从记忆系统中搜索语义相关的历史对话。

阶段 4：调用 AI 模型（Model Invocation）

组装好的上下文打包发给你配置的 AI 模型（Claude、GPT 等），以流式方式获取回复。

阶段 5：工具执行（Tool Execution）

AI 回复过程中如果需要调用工具（比如执行命令、打开浏览器），运行时会拦截并执行，结果实时反馈给模型继续生成。

阶段 6：回复发送（Response Delivery）

回复内容经过 WhatsApp 适配器格式化（Markdown 转换、长消息切分），通过网关发回你的手机。

最后，整轮对话的所有内容存到磁盘。

各阶段大致耗时：

• 访问控制：< 10 毫秒
• 加载会话：< 50 毫秒
• 组装提示词：< 100 毫秒
• AI 模型首个 token：200-500 毫秒
• 工具执行：命令行 < 100 毫秒，浏览器操作 1-3 秒

数据存储和状态管理

OpenClaw 把数据存在哪、怎么存的？

简单来说，OpenClaw 会把你的对话记录、配置信息、记忆数据等等，都存在你自己的设备上。

存储方式设计得很科学，既保证数据安全，又方便检索和使用。

下面我们来详细看看。

配置文件（Configuration）

主配置文件在 ~/.openclaw/openclaw.json，用 JSON5 格式（可以写注释、允许末尾逗号，手动编辑更舒服）。

配置是分层的：环境变量 > 配置文件 > 内置默认值。

敏感信息（比如 Token）可以放环境变量，静态配置放文件。

会话状态与压缩（Session State and Compaction）

每个对话以会话文件的形式存在 ~/.openclaw/sessions/ 下，采用追加式事件日志格式，支持分支。

为了不超出 AI 模型的上下文长度限制，OpenClaw 会自动压缩（Compaction），把较早的对话内容做摘要。

压缩前，系统会先把重要信息提取到记忆文件里，防止关键细节丢失。

会话 ID 的命名也有讲究，直接编码了"谁的会话"和"信任级别"：

• agent:<agentId>:main：你自己的主会话，权限最高
• agent:<agentId>:<channel>:dm:<id>：别人的私聊，默认沙箱隔离
• agent:<agentId>:<channel>:group:<id>：群聊，默认沙箱隔离

记忆搜索（Memory Search）

OpenClaw 怎么记住你以前聊过的东西，并在需要时自动找出来？

OpenClaw 会维护一个可搜索的对话记忆库。

当你问问题时，系统自动搜索过去的对话，找到语义相似的内容注入当前上下文。

这样 Agent 能引用你几周前聊过的东西，不用你重复。

存储和索引

记忆数据存在 SQLite 数据库里（~/.openclaw/memory/ 目录），带有向量嵌入（Vector Embedding，简单说就是把文字转成数字，方便计算相似度）。

搜索方式是混合搜索：

• 向量相似度（语义匹配）：理解意思接近的内容
• BM25 关键词匹配：精确匹配特定词汇

工作空间中的记忆文件

除了自动索引的对话记录，你还可以手动维护结构化的记忆文件：

• MEMORY.md：长期记忆，存放稳定的重要信息（只在私聊中加载，群聊中不会暴露）
• memory/YYYY-MM-DD.md：每日笔记，记录当天的活动和上下文

向量嵌入模型选择

系统会按优先级自动选择嵌入模型：

1. 如果配了本地模型 ，用本地的
2. 有 OpenAI API Key ，用 OpenAI
3. 有 Gemini API Key ，用 Gemini
4. 都没有，记忆搜索功能禁用

索引管理

文件监控器会自动检测记忆文件的变化并重新索引。

换了嵌入模型会自动全量重新索引。

还有实验性功能可以把整个对话历史都索引起来。

凭据管理（Credentials）

敏感的认证数据存在 ~/.openclaw/credentials/，文件权限限制为 0600（只有文件主人能读写），自动排除在版本控制之外，防止泄露。

OpenClaw的安全架构

OpenClaw 怎么层层设防，保护你的系统安全？

OpenClaw 采用多层防御策略，多层安全措施叠加，每层保护不同方面。

1. 网络安全（Network Security）

默认情况下，网关只绑定到 127.0.0.1（本机回环地址），外面谁也连不进来。

如果需要远程访问，推荐两种方式：

• SSH （推荐）：通过加密隧道转发
• Tailscale：一种组网工具，可以把你的设备组成私有网络

2. 身份验证与设备配对（Authentication & Device Pairing）

两层保护：

• Token / 密码认证：非本地连接都需要提供认证信息
• 设备配对：每个连接的设备都有唯一的设备 ID 和密钥。新设备首次连接时，本地设备可以自动通过，远程设备需要签名验证并手动审批

配对通过后，设备会获得一个令牌，之后连接无需重复审批。

3. 渠道访问控制（Channel Access Control）

• DM 配对：陌生人首次发私聊时，系统不处理消息，而是给一个配对码。你手动审批后才放行
• 白名单：明确指定允许的手机号/用户名
• 群聊策略：可以要求 @提到 Bot 才回复，还能设群级别白名单

4. 工具沙箱（Tool Sandboxing）

怎么限制 AI 执行工具时的权限，防止失控？

OpenClaw 用 Docker 沙箱来隔离工具执行。

打个比方，就像给 AI 一个独立的小房间，它只能在里面干活，不能破坏你的整个房子。

基于会话的安全边界

• 主会话（Main）：你自己操作，完全信任，直接在主机上执行
• 私聊会话（DM）：默认沙箱隔离，即使是已审批的联系人
• 群聊会话（Group）：默认沙箱隔离，因为多人参与风险更高

影响安全级别的关键设置

• 沙箱粒度：可以按会话隔离（最安全）、按 Agent 隔离、或共享（效率最高但隔离最弱）
• 主机暴露程度：容器能看到主机上的多少文件
• 网络访问：容器是否能联网
• 逃逸通道：绕过沙箱的高权限工具要严格控制

工具权限的优先级

权限是分层的，越往后越严格：

工具配置 → 模型提供商配置 → 全局策略 → 提供商策略 → Agent 策略 → 群组策略 → 沙箱策略。

群组和沙箱策略可以收紧权限，但不能放宽。

5. 提示词注入防御（Prompt Injection Defense）

怎么防止恶意用户通过精心构造的消息来"劫持"AI 助手的行为？

两个核心手段：

1. 上下文隔离：用户消息、系统指令、工具结果各自带有来源标记，互相分开，不容易被混淆
2. 选用最强模型：官方推荐能调用工具的 Agent 用最强的模型（如 Claude Opus 4.6），因为越强的模型越不容易被忽悠。如果用小模型省成本，就要配合更严格的沙箱和权限限制

此外还要做到：

• 保持私聊的配对/白名单机制
• 群聊优先用 @提及触发而不是"全天候在线"
• 把链接、附件、粘贴的指令默认当作"可能有恶意"来处理
• 敏感工具跑沙箱，密钥放在 Agent 够不到的地方

部署架构

OpenClaw 有几种部署方式，适合不同场景。

不管哪种方式，核心架构是一样的，区别在于网关跑在哪、客户端怎么连。

本地开发环境（macOS/Linux）

一切都跑在你的开发机上。

用 pnpm dev 启动网关（支持代码热更新），只绑定本机地址，不需要认证，调试日志全开。

生产 macOS 环境（菜单栏应用）

网关作为后台服务自动启动运行。

菜单栏应用提供启停控制、内嵌聊天界面和语音唤醒。

支持 iMessage（因为 iMessage 必须在 Mac 上跑）。

可通过 SSH 或 Tailscale 远程访问。

Linux/云服务器（远程网关）

把 OpenClaw 跑在云服务器上，可以 7×24 小时在线。

网关作为 systemd 服务运行，绑定本机地址。你的本地设备通过以下方式连接：

方案 A：SSH （推荐）

把本地端口映射到远程服务器的网关端口，所有流量走加密隧道。

方案 B：Tailscale Serve

把服务器和你的设备加入同一个 Tailscale 私有网络，通过 HTTPS 加密访问，不用管 SSH 密钥和隧道。

云平台容器部署

在阿里云、腾讯云这些云平台上，你可以把 OpenClaw 跑在 Docker 容器里。

Docker 容器就像一个打包好的软件盒子，里面装着 OpenClaw 运行需要的一切，可以在任何支持 Docker 的服务器上直接启动。

注意： 因为是公网可达的，必须开启强认证。

总结

OpenClaw 提供了一种强大的个人 AI 基础设施的思路。

它的架构在简洁和强大之间取得了平衡：

• 简洁：单进程的网关模型
• 强大：多 Agent 路由、工具沙箱、可扩展插件

围绕网关控制的中心化架构设计，实现了跨聊天平台的统一访问。

不管你从 WhatsApp、Discord 还是 飞书、钉钉 发消息，体验是一致的。

强安全边界保护系统不受恶意输入影响，同时不牺牲功能性。

Agent 体系（带工具执行和持久会话）提供了真正智能的助手体验，而不仅仅是给大语言模型（LLM）套了个聊天壳子。

无论你是在笔记本上跑来自己用，还是部署到云服务器 7×24 在线。

你始终掌控着控制权，它跑在哪里、怎么暴露、数据怎么存储和访问。

OpenClaw 提供了一个按你自己要求运行的 AI 助手。

不依赖大厂的云服务，不用担心数据被收集，不受平台规则限制。

你的数据存在哪、AI 能做什么、谁能访问，全部由你说了算。

这才是真正属于你自己的 AI 助手。

对了，我整理了一份《Agent 学习手册(含 OpenClaw)》10 万字干货，持续更新。限时开放领取👉：tangshiye.cn