把你的AI放在自己的服务器上而不是别人的网页里——OpenClaw 架构与实践第一章为什么不是打开一个网页就够了“一切从实践中来一切到实践中去。”——认识论实践场景你在网上看到了一个叫 OpenClaw 的东西——“一个开源的 AI Agent 框架”。你想试试。按照正常人的思路你去找它的网站……没找到。你再找 App Store 下载……也没有。最后你在 GitHub 上找到它看到一行安装命令。装完之后你在终端里敲了一个命令一个服务启动了监听在 18789 端口上。然后你打开浏览器连到http://localhost:18789——出现了一个聊天界面。你终于能跟它说话了。但你脑子里冒出一个问题为什么不能直接给我一个网页地址为什么要我装在自己机器上引出矛盾今天你用的大多数 AI 产品——ChatGPT、Claude、Gemini——都是 SaaS打开网页、注册账号、开始聊天。它们替你管好了服务器、升级版本、备份数据。你拿来就用什么都不用操心。但 OpenClaw 走的是另一条路——你自己是管理员。这堵墙在实践中的体现很明显你要自己装 Node.js自己配置自己启动服务升级要看 Release Notes手动拉新版本出了问题只能自己排查但它不会限制你一个月能聊多少条因为模型是你自己配的你的对话不上传给别人因为全在你的机器上这就是核心矛盾SaaS 产品替你管理一切但你也失去了对一切的控制权。开源自托管让你拥有完全的控制权但管理成本落到了你头上。理论/经验自托管智能体网关OpenClaw 的架构选择是围绕自托管这个前提长出来的你的机器上跑着一个 Gateway 服务端口 18789 ↓ 你是管理员——配置、数据、能力都在你手里 ↓ 你配一个或多个 Agent每个有独立的工作区、人格、模型 ↓ Agent 通过渠道对外服务Web 页面 / Telegram 机器人 / Discord 等为什么自托管因为 OpenClaw 的设计者认定了三件事你的数据不该在别人的服务器上— 对话历史、配置、记忆全在你的磁盘里你的 Agent 不该被别人限速限流— 你自己付模型 API 费用没有每月固定条数这种限制你的 Agent 必须可定制— SaaS 产品给你一个固定界面OpenClaw 让你改到源代码级别付出的代价就是你要当管理员。对比维度SaaS AI 产品OpenClaw自托管谁管服务器提供商你谁管升级提供商你数据在哪里提供商服务器你的机器扩展能力产品给你什么用什么你自己加技能、加渠道费用按月订阅自己付模型 API 费用知识门槛零懂命令行和配置回到实践所以当你第一次看到openclaw gateway这个命令、看到 18789 这个端口时你不是在装一个工具——你是在在自己的机器上架设一台 AI 服务器。门槛比打开网页高但换来的东西也比打开网页多。你在哪里读到 OpenClaw 不重要。重要的是你读完了知道它不是被托管在别处的产品是可以被你自己运营和管理的基础设施。第二章一条消息是怎么变成一段回复的“感觉到了的东西我们不能立刻理解它只有理解了的东西才更深刻地感觉它。”——《实践论》实践场景你连上了 18789 端口在聊天框里打了一行字按了回车。过了一会儿屏幕上一段回复出现了。看起来就像 ChatGPT 一样——输入、等待、输出。但 OpenClaw 不是直接访问 OpenAI 或 DeepSeek 的 API 然后把结果还给你。它多做了很多事——尽管看上去一样简单。引出矛盾你感觉到它回复了你——就像感觉到手机响了接起来有声音。但真遇到问题了客服问你Gateway 的日志看了吗Session 是哪个技能加载了吗——你才意识到你完全不知道这个过程怎么拆。你知道出去的是什么——你输入的文字。你知道回来的是什么——Agent 的回复。但你不知道中间发生了什么。一张黑布隔在输入和输出之间。你摸得到两边但看不见里面。这就是核心矛盾Agent 和人之间隔着一层看似简单的 UI但复杂的传动机构被完全隐藏了。一旦需要诊断问题你就变成了拆盲盒。理论/经验消息在 OpenClaw 中的完整路径一条消息从你发出到看到回复穿越了五层你 → 渠道WebChat / Telegram / CLI / … ↓ Gateway端口 18789 —— 统一入口 ↓ 1. 验证身份你是谁 ↓ 2. 判断来源从哪个渠道来的 ↓ 3. 路由这条消息该走哪个 Agent ↓ Session 管理 ↓ 4. 恢复或创建会话之前聊过没 ↓ Agent 循环核心 ↓ 5. 组装上下文人格文件 记忆 技能 工具列表 历史对话 ↓ 6. 调用大模型 ↓ ┌── 如果是文字回复 ──→ 直接输出 ──┐ │ │ └── 如果是工具调用 ──→ 执行工具 → 结果喂回模型 → 继续循环 ──┘ ↓ Session 持久化写回对话历史 ↓ Gateway 推送到渠道 ↓ 你 ← 看到回复这五层各自解决一个独立的问题层解决的问题渠道把各种消息源的差异归一成统一格式——你在 WebChat 打进去的字跟从 Telegram 发来的消息到了 Gateway 这里就是同一种东西Gateway统一验证和路由——不管从哪来、不管有几个 Agent都走这一个入口Session会话隔离和复用——群聊和 DM 互不干扰同一个人连续聊天自动接上上下文Agent Loop想和干的分离——大模型负责想工具负责干Loop 负责协调技能 工具能力可插拔——想加新能力就写一个 markdown 文件不用改代码回到实践下次你再对着 OpenClaw 发一条消息你可以自己在脑子里走一遍这条路径“这条消息进 18789 了 → Gateway 验了我的身份 → 找到我的 session → Agent 加载了我的配置和技能 → 调了一次大模型 → 没有工具调用 → 直接输出 → 写回 session → 我收到了。”这条路径走一次只要一两秒。但理解它之后你再也不会觉得输入→输出是一个简单操作了——你看到的是一套精密的分层传动机构在一两秒内跑完了全线。第三章一个 AI 怎么拥有人格“内因是变化的根据外因是变化的条件。”——《矛盾论》实践场景你打开 OpenClaw 开始跟它聊天。它自称一个名字有特定的语气对有些问题果断、对有些问题谦让。它似乎知道自己是谁、在跟谁说话、应该怎么回应。但你很清楚大模型本身没有人格——你给它什么系统提示它就是什么样子。换一组提示词它就变成另一个人。那么OpenClaw 的这种稳定人格是怎么保持的引出矛盾每次 Agent Loop 启动你都给了大模型一个上下文——里面带着服务端的配置、用户的信息、对话的历史。但这个上下文是怎么长成的谁决定了大模型的人设如果说大模型是一个演员那么系统提示词就是剧本。但问题在于演员每场演出只拿到当场的剧本不拿到全部剧本。换一个 session剧本就从头来。你怎么保证每次拿到的剧本都是同一个人这就是矛盾大模型是白纸一张但 Agent 需要一个稳定、可预期的人格。这个人格不能靠程序员写死在代码里因为用户需要自己能改。理论/经验工作区文件驱动人格系统OpenClaw 的解法是工作区文件 角色路由。工作区里有一组 markdown 文件定义了 Agent 的人workspace/ ├── AGENTS.md ← 运行规则知道怎么做事 ├── SOUL.md ← 人格设定知道怎么做人 ├── MEMORY.md ← 长期记忆记得发生过什么 ├── USER.md ← 用户资料知道自己跟谁说话 ├── TOOLS.md ← 工具偏好知道用什么顺手 └── IDENTITY.md ← 自我介绍知道自己叫什么每次新的会话启动时这些文件被全量读入系统提示。所以 Agent 每次重启都知道自己是谁、在跟谁说话、应该怎么回应。人格文件最值得关注的特性它们是文本文件不是数据库— 你打开编辑器就能改不用 SQL、不用 API。改完保存下次对话就生效。它们是用户可控的— 开发者设计框架但人格的定义权在你手里它们可以组合出多角色— 同一份 SOUL.md 里可以写角色路由表根据不同的关键词匹配不同人格SOUL.md 里的角色路由示例触发关键词角色说明分析、怎么看、矛盾分析专家辩证分析给你结构性答案技能、SKILL、触发词技能开发者按规范格式写技能文档其他默认助手灵活应对回到实践OpenClaw 聊起来像一个人不是大模型恰好生成了符合你期望的语气——而是因为每次对话开始前一组精心编写的 markdown 文件被放进了它的认知基础里。改一行 SOUL.md人格就变了。不是你写代码重新编译它是你拿着文本编辑器改了段话。这就是内因是变化的根据——Agent 的人格不是代码决定的是你在那一堆 markdown 文件里写下的定义决定的。第四章一个不会动手的大模型怎么成了干活的好手“不同质的矛盾只有用不同质的方法才能解决。”——《矛盾论》实践场景你对 OpenClaw 说“帮我把这个目录里的文件统计一下按类型分类输出一份报告。”OpenClaw 说“好的”过了几秒一份完整的文件统计报告出现在屏幕上分类清晰、数据准确。但你仔细想一下OpenClaw 背后是一个大模型——大模型会写文字、会推理但它不会读文件。它没有眼睛、没有手、不能操作文件系统。它怎么统计的引出矛盾大模型的能力边界是生成文本。它不知道当前目录有什么文件因为它没有看的能力。它不能执行 Shell 命令因为 LLM API 让你传 message 和工具定义不让你传 Shell 指令。但用户需要的 Agent恰恰是要能执行的——读文件、跑脚本、查数据库、调 API。如果 Agent 不能做这些事它就是一个高级聊天机器人不是智能体。这就是核心矛盾大模型只会想生成文字但用户需要的是干执行操作。理论/经验Agent Loop 工具调用机制OpenClaw 用一个叫做Agent Loop的循环机制来解决这个矛盾。工作方式很简单用户统计文件 ↓ Agent 循环开始 第 1 轮调 LLM LLM 推理 → 我需要列出文件应该用 terminal 工具跑 ls LLM 输出工具调用 ↓ 拦截工具调用 → 执行 hermes_terminal(ls -R) → 拿到文件列表 ↓ 第 2 轮把文件列表喂回 LLM LLM 推理 → 有 32 个 .md 文件, 15 个 .py 文件…… LLM 输出分类结果 ↓ 输出给用户三步走步骤谁做的做了什么想大模型LLM分析用户需求决定该调什么工具、传什么参数干Agent Loop拦截 LLM 发出的工具调用请求调用真实函数执行再看大模型拿到工具执行结果继续推理下一步或输出最终回复每一步之间Agent Loop 就是那个转接器——它把 LLM 的想法翻译成动作再把动作的结果翻译回 LLM 能理解的格式。OpenClaw 可以接入的工具有几类工具来源举例怎么接的内置工具read/exec/write/edit框架自带的开箱即用MCP 桥工具任何第三方 Agent 暴露的能力通过 MCP 标准协议接入自定义工具你写的 API 调用脚本通过工具定义注册进去回到实践你让 OpenClaw 统计文件、写文章、分析架构——每一个看起来像跟 AI 聊天的操作背后都是 Agent Loop 在想→干→再想→再干地转圈。大模型一动嘴Agent Loop 就跑断腿。但你作为用户只看到它回答了你。这就是 Agent 跟聊天机器人的区别聊天机器人只知道怎么回答你。Agent 知道怎么帮你把事情办了——因为它有手。第五章一个 Gateway 怎么伺候好多个人和多个地方“具体问题具体分析。”——《实践论》实践场景你的 OpenClaw 跑起来了正在 WebChat 上跟你聊天。但你出门在外只有手机——你想通过 Telegram 继续聊。另外你还有一个朋友想用 Discord 跟你的 Agent 说话——但你觉得应该给他安排一个不一样的 Agent性格偏正式一些不像跟你聊天这么随意。一个 Gateway多个人多个地方每个人还要不同的 Agent——这怎么实现的引出矛盾三个不同的问题压在一起多个渠道— Telegram 有自己的 Bot APIDiscord 有自己的 GatewayWeb 有自己的 WebSocket——每套协议都不同多个 Agent— 一个给你当哥们一个给同事当助手你不能让同一个 Agent 用同一套语气对所有人多条消息— 如果同时来三条消息全交给同一个 Agent 会串全串行处理会慢不把这些理清楚你的 OpenClaw 就只能在单机单用户单渠道下运行——谈不上基础设施。这就是核心矛盾统一运行服务和差异化服务能力之间的矛盾。理论/经验多 Agent 路由 渠道绑定系统OpenClaw 把谁在说话和谁在回答用一套 binding 系统解耦了。Binding 决定路由每条消息该走哪个 Agent消息来源Telegram / Discord / WebChat / CLI ↓ Binding 规则一条接一条匹配 1. 先查 peer是否是特定用户发的 2. 再查 guild是否是特定群组的 3. 再查 channel是否来自整个渠道 4. 最后查 default没匹配上就用默认 Agent ↓ 路由到匹配的 Agent匹配规则是最具体优先——你对指定用户发来的消息单独安排了某个 Agent那就它没有任何特殊规则就走默认 Agent。每个 Agent 完全隔离Agent A跟你聊天——随意、哥们 ├── 自己的工作区SOUL.md: 你是个哥们 ├── 自己的人格文件 ├── 自己的 session 历史 └── 自己的技能列表 Agent B跟同事对接——正式、专业 ├── 自己的工作区SOUL.md: 你是个专业助理 ├── 自己的人格文件 ├── 自己的 session 历史 └── 自己的技能列表两个 Agent 共享一个 Gateway 进程、共享一个 18789 端口——但在逻辑上完全独立。Agent A 不知道 Agent B 跟谁聊了什么反之亦然。多渠道通过适配器接入每个渠道配一个适配器文件把平台协议翻译成统一格式平台接入方式OpenClaw 适配器做了什么WebChat浏览器直接连 WS渲染聊天界面历史记录TelegramBot API token轮询更新发送消息DiscordGateway 连接 Bot token监听事件发送消息CLI终端 WS 连接无界面交互更多各平台协议归一化成统一消息格式回到实践所以当你在 WebChat 上跟 OpenClaw 聊天你的朋友通过 Telegram 跟另一个 Agent 聊天——看起来是四个独立聊天窗口实际上都是同一个 Gateway同一个 18789 端口在背后统一路由。谁在哪个渠道、发给哪个 Agent、用什么人格说话——这一切在 Binding 规则表里定义好之后服务器就不需要你手操了。消息进来自动匹配正确的人用正确的语气回答正确的来源。这就是具体问题具体分析在架构上的体现——每个场景不同渠道不同、用户不同、用途不同解决方案也不同不同的 Agent、不同的人格、不同的适配器但所有的具体都归一在同一个 Gateway 之下。小结“一切从实践中来一切到实践中去。”OpenClaw 每一层的架构设计都是从一个很具体的实践困境出发的实践困境架构解法不想把数据和对话交到别人服务器上自托管 Gateway想知道消息在服务端经历了什么五层链路渠道→Gateway→Session→Agent Loop→技能/工具需要 Agent 拥有稳定可预期的人格工作区文件驱动人格系统大模型只会想不会干Agent Loop 工具调用机制一个服务要对多个平台、多人、多角色提供服务多 Agent 路由 渠道绑定系统它不是从一本系统设计教科书里抄出来的。每一层都是被一个问题逼出来的——你先遇到了用户发了一条消息我怎么知道该给哪个 Agent这道题然后才有了 Binding 系统。你先遇到了每次对话都要重新介绍自己这个烦人的事然后才有了 session 持久化。OpenClaw 的架构是长出来的不是想出来的。好的架构的特点就在这你不觉得它复杂但它确实复杂。只是把复杂藏到了你不需要看见的地方。
