OpenClaw架构解析：一个本地AI Agent系统是怎么工作的
用OpenClaw这个项目，你不需要记住每个配置项。你需要知道的是三件事：系统怎么转起来的，哪里会出问题，以及你能在哪里插手。
先说结论
OpenClaw本质上是一个在你电脑上运行的AI Agent操作系统。它做的事情不复杂：把消息平台（飞书、Telegram、Discord）发来的消息，交给大模型，大模型决定调用哪些工具，工具执行完把结果返回，最后把答案发回消息平台。
复杂的是：它把这个流程做成了持久运行的后台服务，还加上了记忆、技能、定时任务、多Agent路由。这个循环能24小时不停自动运转。
六个子系统
1. Gateway（网关）
Gateway是整个系统的神经中枢。它是一个单进程的Node.js应用，以macOS LaunchAgent形式常驻后台。
关键信息：
监听WebSocket：ws://127.0.0.1:18789
所有消息平台的连接都挂在Gateway上
网页控制台也由Gateway直接提供：http://127.0.0.1:18789/
配置文件在~/.openclaw/openclaw.json
日志在~/.openclaw/logs/gateway.log
为什么做成单进程？这是刻意的选择。单进程意味着状态集中、调试简单、没有服务之间通信的麻烦。代价是：Gateway崩了，整个系统就崩了。
2. Router（路由器）
Router负责决定这条消息该交给哪个Agent处理。
路由规则的优先级从高到低是这样：
精确匹配（特定用户ID）
父子匹配（线程继承）
服务器ID加角色（Discord）
服务器ID
团队ID（Slack）
账号ID
频道通配
默认Agent
同一个优先级里，配置顺序靠前的获胜。
3. Agent Loop（核心循环）
这是OpenClaw实际思考的地方。每次收到消息后的执行流程：
加载人格：读SOUL.md文件
加载长期记忆：读MEMORY.md文件
加载当天日志：读memory文件夹里当天日期的md文件
技能注入：只选跟当前任务相关的技能，不是全量塞进去
调用大模型：把上下文、消息、技能一起发给模型
执行工具：模型说要调哪个工具，Gateway就去执行
循环：工具结果返回给模型，继续直到得到最终回答
更新记忆：把当天对话写进memory文件
关键细节：技能是按需注入的。一个配了50个技能的Agent，不会每次对话都把50个技能描述塞进prompt。这是为了省token。
4. Brain（大模型层）
Brain跟模型无关，可以随便换。可以换成任何支持Anthropic API格式的模型。
Brain的职责：
理解用户想干什么
决定调哪些工具
安排多步执行的顺序
生成最终回答
5. Memory（记忆系统）
记忆分三层：
人格层：SOUL.md文件，定义Agent的性格、语气、工作方式。每次会话都加载。
长期记忆：MEMORY.md文件，存稳定的长期事实，比如用户偏好、重要信息。私聊会话时加载。
日志层：memory文件夹里按日期存的md文件，是当天的原始活动记录。当天会话时加载。
底层存储用SQLite加向量嵌入，支持混合搜索（语义相似加关键词匹配）。
还有自动压缩功能。当对话太长快超限时，系统会自动总结旧对话，把重要信息提出来存到MEMORY.md，然后压缩历史。这样防止对话太长撑爆。
6. Scheduler（调度器）
两种主动执行模式：
心跳模式：默认每30分钟唤醒一次Agent。Agent读HEARTBEAT.md文件，看看要检查什么。如果没什么要做的，就回复HEARTBEAT_OK，不产生噪音。
定时任务模式：精确到分钟的时间调度。任务存在~/.openclaw/cron/文件夹里，重启电脑也不会丢。
设计上的几个想法
文件优先，不用数据库
SOUL.md、MEMORY.md、HEARTBEAT.md都是普通的Markdown文件。好处是：可以直接打开看，可以用git管理版本，可以直接用编辑器改，Obsidian也能打开浏览。
这是故意对抗复杂性的选择：没有数据库，没有微服务，不会被某个厂商绑死。
本地运行，数据自己管
所有执行都在本机，调用大模型API时直接从你的机器发出，不经过OpenClaw任何服务器中转。你的对话记录、文件、执行历史，全在~/.openclaw/文件夹下，你完全掌控。
单一Gateway，简单优先
单进程设计就是一句话：能简单就不搞复杂。Anthropic官方也说过类似的话：能用简单循环搞定的，别过度引入编排框架。OpenClaw照着这个理念做的。
消息完整流转路径
消息从平台进来，到Gateway，Router决定给哪个Agent，Agent循环处理，调工具，拿结果，最后原路返回。
需要记住的三件事
Gateway是核心：所有东西都跑在这个单进程里。它挂了，系统就停了。用openclaw gateway status随时检查。
文件就是配置：SOUL.md定义人格，HEARTBEAT.md定义心跳任务，MEMORY.md定义长期记忆。改文件就是改Agent行为。
技能是按需注入的：不用担心技能太多拖慢系统，运行时只注入相关的。但SOUL.md和MEMORY.md是每次都加载的，所以这两文件要保持精简。
本文内容仅供个人学习、研究或参考使用，不构成任何形式的决策建议、专业指导或法律依据。未经授权，禁止任何单位或个人以商业售卖、虚假宣传、侵权传播等非学习研究目的使用本文内容。如需分享或转载，请保留原文来源信息，不得篡改、删减内容或侵犯相关权益。感谢您的理解与支持！