青橙记录追剧
110.94M · 2026-02-27
大家好，我是汤师爷，n京大学硕士，前华为、阿里 AI架构师。
全网10万粉AI博主，2本畅销书作家（第3本写作中）。
目前专注AI智能体，致力于帮助100W人用智能体创富~
GitHub史上增长最快的开源项目，18万个star，背后的核心开发者只有一个人。
这种增长速度不只是火了，简直是史无前例。
今天汤师爷就来给大家扒一扒 OpenClaw 的架构设计。
这篇文章会用最简单的大白话，把 OpenClaw 这个让 GitHub 都震惊的项目，从里到外拆开给你看。
不管你是技术小白还是开发老手，读完保证能彻底搞清楚它到底是怎么运作的。
OpenClaw 是一个个人 AI 助手平台，跑在你自己的设备上，你的笔记本电脑、一台云服务器、机柜里的 Mac Mini，或者一个云容器。
它把 AI 模型和各种工具，连接到你日常用的聊天 App，例如，WhatsApp、T@elegrimm、飞书、钉钉等等。
OpenClaw 把 AI 助手当作基础设施来构建，而不只是优化提示词。
打个比方，普通聊天机器人就像一个只会接电话的客服，你问什么它答什么。
而 OpenClaw 更像是给 AI 搭了一整套办公系统，有会话管理、有记忆系统、有工具权限控制、有消息路由。
AI 模型扮演大脑的角色，OpenClaw 负责帮你落地。
AI 模型的 API 调用还是走 Anthropic、OpenAI 那些服务商，但对话记录、工具执行、会话状态、所有调度逻辑，全部留在你自己的设备上。
下面这些功能，你可以完全自主控制：
OpenClaw 的整体架构长什么样，几大组件怎么配合？
OpenClaw 不是一个套了层壳的 AI 聊天机器人，它是一个AI Agent 的操作系统。
它采用调度中心架构，就像一个机场调度中心，所有航班（消息）都经过一个中央塔台（Gateway 网关），由它分配到正确的跑道（Agent）。
核心就两大模块：
关键设计思想： 把消息通信、接口层和AI 怎么思考和执行（Agent）彻底分开。
这样你就有了一个统一的 AI 助手，不管你从 WhatsApp、飞书 还是钉钉发消息，它都能接入。
而且会话状态和工具权限都在你的设备上集中管理。
那么OpenClaw 怎么让别人在不改核心代码的情况下，扩展新功能？
OpenClaw 的设计哲学是开放扩展，不改核心。
你可以通过插件（Plugin）在四个方向上扩展：
插件代码放在 extensions/ 目录下，系统会自动扫描、发现和加载。
OpenClaw 怎么对接各种聊天平台，把不同平台的消息翻译成统一格式？
每个聊天平台都有一个专门的适配器。
有些是内置的（比如 T@elegrimm、Discord），有些可以通过插件添加。
不同平台的 API 和协议千差万别，但每个适配器都做同样的四件事：
不同平台的验证方式不一样：
各平台的数据格式差异非常大，适配器的工作就是把它们统一。
不管消息从 WhatsApp 还是 飞书来，提取出文字、图片、音频、视频、文档、表情反应和回复上下文后，OpenClaw 的其他部分就不用操心平台差异了。
这是渠道层面的安全关卡：
每个平台的 Markdown 格式、消息长度限制、媒体上传方式都不一样。
适配器负责处理这些，长消息自动切分、Markdown 格式转换、媒体文件上传、甚至"正在输入"的提示。
除了聊天 App，你还有哪些方式可以操控 OpenClaw？
OpenClaw 提供了四种交互方式：
用浏览器打开 就行，能聊天、管配置、查会话、坚控状态。
不需要额外装 Web 服务器，网关自己就搞定了。
喜欢敲命令的人可以用命令行控制一切：
openclaw gateway 启动网关openclaw agent 直接调用 Agentopenclaw channels login 配对 WhatsApp/Signalopenclaw message send 编程发消息openclaw doctor 跑健康检查openclaw onboard 引导式初始设置用 Swift 写的原生 Mac 应用，可以放在在菜单栏里。
可以一键启动/停止/重启网关，内置聊天界面，还支持语音唤醒。
iOS 和 Android 的 App 通过 WebSocket 连接到网关，
不光能聊天，还能把手机的摄像头、录屏、定位等能力暴露给 Agent 使用，让你的手机变成 AI 的外挂硬件。
网关是整个系统的大脑中枢，所有消息和指令都经过它。
网关就像一个快递分拣中心，所有包裹（消息）进来后，由它检查收件人信息、分配到正确的分拣线（Agent），最后把回复发出去。
技术细节：
127.0.0.1（本机地址），不对外暴露核心设计原则：
Agent 是真正跑 AI 对话和工具执行的地方，相当于 AI 的工作台。
Agent 运行时每一轮对话做四件事：
步骤 1：确定会话（Session Resolution）
消息进来后，先搞清楚这条消息属于哪个会话：
main 会话（权限最高）dm:平台:ID 会话group:平台:ID 会话注意： 会话不只是个标签，它还是安全边界。不同类型的会话有不同的权限和沙箱规则。
步骤 2：组装上下文（Context Assembly）
确定会话后，运行时会组装 AI 需要的上下文信息：
步骤 3：调用模型并执行工具（Execution Loop）
AI 模型开始回复时，Agent 会实时坚控：
步骤 4：保存状态
对话结束后，把所有消息、工具调用结果都存回磁盘。
OpenClaw 如何把多个配置文件拼成一份完整的AI 执行计划？
OpenClaw 的系统提示词不是一个写死的文件，而是由多个来源组合拼装而成：
工作空间配置文件：
AGENTS.md：核心指令，定义 Agent 能做什么、不能做什么（基线规则）SOUL.md：人格和语气指导，Agent 说话的风格（可选）TOOLS.md：用户写的工具使用备注（可选）动态上下文（每轮对话实时组装）：
工具定义（自动生成）：
这种可组合的设计意味着：你只需要编辑工作空间里的文件，就能改变 Agent 的行为、风格和能力，完全不用改源代码。
一个重要细节：
OpenClaw 不会把所有技能一股脑塞进提示词。
它会智能筛选，只注入当前这轮对话需要的技能，避免提示词太长导致 AI 表现下降。
Canvas 是一个由 AI 驱动的可视化工作区，你可以把它理解成一块"画板"，AI 可以在上面画出各种可交互的界面，比如按钮、列表、表单等等。
而 A2UI（Agent-to-UI）就是 AI 用来"画"这些界面的工具。AI 不需要写复杂的代码，只要生成一些带特殊标记的 HTML，就能让界面元素活起来，用户点击后 AI 还能收到反馈并做出响应。
Canvas 是一个独立运行的可视化工作区服务（默认端口 18793），跟主网关是分开的。好处是Canvas 崩了不影响网关正常运行。
交互流程：
A2UI 全称是 Agent-to-UI，是一套声明式框架。
Agent 只需要生成带特殊属性的 HTML，就能创建按钮、列表等交互元素，不需要写 JavaScript。用户点击按钮后，事件会传回 Agent，Agent 处理完再更新界面。
Canvas 支持 macOS 原生应用、iOS、Android 和 Web 浏览器。
你可以用语音跟 OpenClaw 对话，就像跟 Siri 说话一样。
在 macOS、iOS、Android 上，你可以说"Hey OpenClaw"唤醒助手，或者用快捷键按住说话。
音频会发到 ElevenLabs 做语音识别，Agent 处理后再用语音合成把回复念出来。
对话模式（Talk Mode）支持连续对话，你甚至可以在 Agent 说话时打断它。
你可以让不同的聊天渠道/群组使用完全不同的 AI 助手实例，各自独立。
比如你想让：
通过配置就能搞定，每个 Agent 实例有自己的工作空间、模型和行为设定。
这带来了很多玩法：
Agent 之间怎么互相沟通和协作？
OpenClaw 提供了一组会话工具，让不同的 Agent 可以互相传话、协作：
sessions_list：查看有哪些活跃会话sessions_send：给另一个会话发消息sessions_history：查看另一个会话的对话记录sessions_spawn：创建新会话来委派任务怎么让 Agent 定时干活或被外部事件触发？
两者都是通过配置文件设置，不需要写代码。
从你在 WhatsApp 发一条消息，到收到 AI 回复，中间经历了哪些步骤？
以 WhatsApp 为例，完整流程分 6 个阶段：
网关收到 WhatsApp 服务器的 WebSocket 事件。
WhatsApp 适配器解析这个事件，提取出消息文字、媒体附件和发送者信息。
消息先过安全检查：
没通过？消息到此为止。
通过后，系统确定用哪个会话处理：
main 会话（最高权限）dm 会话group 会话Agent 运行时加载对应的会话记录，读取配置文件拼出系统提示词，并从记忆系统中搜索语义相关的历史对话。
组装好的上下文打包发给你配置的 AI 模型（Claude、GPT 等），以流式方式获取回复。
AI 回复过程中如果需要调用工具（比如执行命令、打开浏览器），运行时会拦截并执行，结果实时反馈给模型继续生成。
回复内容经过 WhatsApp 适配器格式化（Markdown 转换、长消息切分），通过网关发回你的手机。
最后，整轮对话的所有内容存到磁盘。
各阶段大致耗时：
OpenClaw 把数据存在哪、怎么存的？
简单来说，OpenClaw 会把你的对话记录、配置信息、记忆数据等等，都存在你自己的设备上。
存储方式设计得很科学，既保证数据安全，又方便检索和使用。
下面我们来详细看看。
主配置文件在 ~/.openclaw/openclaw.json，用 JSON5 格式（可以写注释、允许末尾逗号，手动编辑更舒服）。
配置是分层的：环境变量 > 配置文件 > 内置默认值。
敏感信息（比如 Token）可以放环境变量，静态配置放文件。
每个对话以会话文件的形式存在 ~/.openclaw/sessions/ 下，采用追加式事件日志格式，支持分支。
为了不超出 AI 模型的上下文长度限制，OpenClaw 会自动压缩（Compaction），把较早的对话内容做摘要。
压缩前，系统会先把重要信息提取到记忆文件里，防止关键细节丢失。
会话 ID 的命名也有讲究，直接编码了"谁的会话"和"信任级别"：
agent:<agentId>:main：你自己的主会话，权限最高agent:<agentId>:<channel>:dm:<id>：别人的私聊，默认沙箱隔离agent:<agentId>:<channel>:group:<id>：群聊，默认沙箱隔离OpenClaw 怎么记住你以前聊过的东西，并在需要时自动找出来？
OpenClaw 会维护一个可搜索的对话记忆库。
当你问问题时，系统自动搜索过去的对话，找到语义相似的内容注入当前上下文。
这样 Agent 能引用你几周前聊过的东西，不用你重复。
记忆数据存在 SQLite 数据库里（~/.openclaw/memory/ 目录），带有向量嵌入（Vector Embedding，简单说就是把文字转成数字，方便计算相似度）。
搜索方式是混合搜索：
除了自动索引的对话记录，你还可以手动维护结构化的记忆文件：
MEMORY.md：长期记忆，存放稳定的重要信息（只在私聊中加载，群聊中不会暴露）memory/YYYY-MM-DD.md：每日笔记，记录当天的活动和上下文系统会按优先级自动选择嵌入模型：
文件坚控器会自动检测记忆文件的变化并重新索引。
换了嵌入模型会自动全量重新索引。
还有实验性功能可以把整个对话历史都索引起来。
敏感的认证数据存在 ~/.openclaw/credentials/，文件权限限制为 0600（只有文件主人能读写），自动排除在版本控制之外，防止泄露。
OpenClaw 怎么层层设防，保护你的系统安全？
OpenClaw 采用多层防御策略，多层安全措施叠加，每层保护不同方面。
默认情况下，网关只绑定到 127.0.0.1（本机回环地址），外面谁也连不进来。
如果需要远程访问，推荐两种方式：
两层保护：
配对通过后，设备会获得一个令牌，之后连接无需重复审批。
怎么限制 AI 执行工具时的权限，防止失控？
OpenClaw 用 Docker 沙箱来隔离工具执行。
打个比方，就像给 AI 一个独立的小房间，它只能在里面干活，不能破坏你的整个房子。
权限是分层的，越往后越严格：
工具配置 → 模型提供商配置 → 全局策略 → 提供商策略 → Agent 策略 → 群组策略 → 沙箱策略。
群组和沙箱策略可以收紧权限，但不能放宽。
怎么防止恶意用户通过精心构造的消息来"劫持"AI 助手的行为？
两个核心手段：
此外还要做到：
OpenClaw 有几种部署方式，适合不同场景。
不管哪种方式，核心架构是一样的，区别在于网关跑在哪、客户端怎么连。
一切都跑在你的开发机上。
用 pnpm dev 启动网关（支持代码热更新），只绑定本机地址，不需要认证，调试日志全开。
网关作为后台服务自动启动运行。
菜单栏应用提供启停控制、内嵌聊天界面和语音唤醒。
支持 iMessage（因为 iMessage 必须在 Mac 上跑）。
可通过 SSH 或 Tailscale 远程访问。
把 OpenClaw 跑在云服务器上，可以 7×24 小时在线。
网关作为 systemd 服务运行，绑定本机地址。你的本地设备通过以下方式连接：
把本地端口映射到远程服务器的网关端口，所有流量走加密隧道。
把服务器和你的设备加入同一个 Tailscale 私有网络，通过 HTTPS 加密访问，不用管 SSH 密钥和隧道。
在阿里云、腾讯云这些云平台上，你可以把 OpenClaw 跑在 Docker 容器里。
Docker 容器就像一个打包好的软件盒子，里面装着 OpenClaw 运行需要的一切，可以在任何支持 Docker 的服务器上直接启动。
注意： 因为是公网可达的，必须开启强认证。
OpenClaw 提供了一种强大的个人 AI 基础设施的思路。
它的架构在简洁和强大之间取得了平衡：
围绕网关控制的中心化架构设计，实现了跨聊天平台的统一访问。
不管你从 WhatsApp、Discord 还是 飞书、钉钉 发消息，体验是一致的。
强安全边界保护系统不受恶意输入影响，同时不牺牲功能性。
Agent 体系（带工具执行和持久会话）提供了真正智能的助手体验，而不仅仅是给大语言模型（LLM）套了个聊天壳子。
无论你是在笔记本上跑来自己用，还是部署到云服务器 7×24 在线。
你始终掌控着控制权，它跑在哪里、怎么暴露、数据怎么存储和访问。
OpenClaw 提供了一个按你自己要求运行的 AI 助手。
不依赖大厂的云服务，不用担心数据被收集，不受平台规则限制。
你的数据存在哪、AI 能做什么、谁能访问，全部由你说了算。
这才是真正属于你自己的 AI 助手。
