夜雨聆风📖 「Agent 学习实操系列：OpenClaw x Hermes 」
- 引言 -
你可能已经装好了 OpenClaw，飞书机器人也跑起来了，发条消息过去秒回。但你想过没有，这条消息经历了什么？
从你在飞书打字，到 Agent 把结果送回来，中间经过了网关、会话、模型、工具调用好几个环节。搞懂这条链路，后面加 Skill、配 Cron、调模型，你都知道该改哪里。
这篇把 OpenClaw 的架构拆开给你看。不是源码级分析，是"作为使用者你需要理解的全部"。
🔻
● 六个关键词，建立心智模型
OpenClaw 的架构可以浓缩成六个关键词。先记住它们，后面逐个展开。
Gateway（网关）
OpenClaw 的心脏，一个常驻后台的 Node.js 进程。所有消息进出都经过它。
它的职责很单纯：收消息、找 Agent、把结果送回去。不思考，不判断，只做调度。
管理方式：
openclaw gateway start # 启动
openclaw gateway stop # 停止
openclaw gateway restart # 重启
openclaw gateway status # 看状态
默认跑在本地 18789 端口，配置在 openclaw.json 的 gateway 字段。
Session（会话）
每个对话窗口对应一个 Session。你跟 Agent 私聊是一个 Session，群里 @ 它是另一个 Session，Cron 任务跑起来又是独立的 Session。
三种 Session 类型：
- main：主会话，你直接跟 Agent 聊天时用
- isolated：隔离会话，Cron 定时任务专用，跑完就销毁
- subagent：子 Agent 会话，主 Agent 派出去干活的
Session 决定了两件事：上下文隔离（不同 Session 之间互不干扰）和工具权限（isolated session 能用什么工具有限制）。
Agent（智能体）
配置在 openclaw.json 里，每个 Agent 有自己的模型、工具权限、身份文件。
最简单的配置只有一个 Agent：
{
"agents": {
"list": [{
"id": "main",
"model": "zai/glm-5.1",
"tools": { "profile": "full" }
}]
}
}
Channel（渠道）
飞书、Telegram、Discord、微信——都是 Channel。Agent 不关心消息从哪来，Gateway 负责统一格式。
Skill（技能）
Agent 的工具箱。一个 Skill 就是一个 SKILL.md 文件加上可选的脚本。Agent 收到消息后扫描所有可用 Skill，根据 description 字段判断要不要调用。
Cron（定时任务）
配置在 cron/jobs.json 里，支持热加载——改完文件不用重启 Gateway。
📌 小结：Gateway 是引擎，Session 是车厢，Agent 是司机，Channel 是乘客上车的地方，Skill 是司机的技能包，Cron 是闹钟。记住这个比喻就够了。
🔻
● 目录结构：哪个文件管什么
你不需要记住所有目录。重点关注三个：
1. openclaw.json — 改模型、改渠道、改权限
2. workspace/ — 改 Agent 性格、加记忆、装 Skill
3. cron/jobs.json — 定时任务全在这里
workspace 目录是 Agent 的"大脑"：
workspace/
├── AGENTS.md # 行为准则（启动流程/红线/规则）
├── SOUL.md # 性格内核（风格/偏好/态度）
├── USER.md # 用户画像（你是谁/怎么沟通）
├── IDENTITY.md # 身份卡（名字/emoji/定位）
├── MEMORY.md # 长期记忆
├── memory/ # 短期记忆（每天一个日志）
├── skills/ # 用户安装的 Skill
├── scripts/ # 自定义脚本
└── temp/ # 临时文件
📌 小结：openclaw.json 管"硬件"（模型、渠道、权限），workspace/ 管"灵魂"（身份、记忆、技能）。一个管身子，一个管脑子。
🔻
● 四个身份文件：让 Agent 变成"你的"Agent
这是 OpenClaw 最独特的设计。四个纯文本文件定义 Agent 的人格。
AGENTS.md — 宪法（必须遵守的规则）
启动时必须读哪些文件、红线（不能做的事）、群聊行为规范、自我改进协议。
SOUL.md — 性格（愿意怎么做）
核心价值观和沟通风格。我自己的 SOUL.md 里写了一句"用能力赢得信任"，直接影响了 Agent 每次回复的语气。
USER.md — 用户画像（对用户的理解）
你是谁、什么职业、什么沟通偏好。知道你是工程师，Agent 就直接用术语，不每次解释。
IDENTITY.md — 名片（对外展示）
名字、emoji、定位、核心能力。最轻量的文件。
实操验证：改 SOUL.md，加一句"回复时最后加个 🧊"，保存后发消息，下一秒就能看到变化。
📌 小结：AGENTS.md 是宪法，SOUL.md 是性格，USER.md 是对你的理解，IDENTITY.md 是名片。四个文件协作，让 Agent 从"通用机器人"变成"你的专属助手"。
🔻
● 一条消息的完整旅程
全篇最核心的部分。跟着一条消息走一遍，把前面所有概念串起来。
场景：你在飞书发了"今天深圳天气怎么样？"
第1站：飞书服务器 — 通过 WebSocket 长连接把消息推送到你服务器的 18789 端口。
第2站：Gateway — 解析消息来源，找到对应 Session，路由到 main Agent。
第3站：Agent 醒来 — 读取 SOUL.md、USER.md、近期记忆、MEMORY.md，然后扫描 Skill 列表。
第4站：调用工具 — 匹配到 weather skill，读取 SKILL.md，调用天气 API。
第5站：生成回复 — 按 SOUL.md 的风格和 USER.md 的偏好，把数据整合成自然语言。
第6站：返回飞书 — 回复经 Gateway → WebSocket → 飞书，你在聊天窗口看到结果。
整个过程，通常 2-5 秒。
📌 小结：理解这条链路，你就理解了 OpenClaw 的全部。后面遇到任何问题，都能定位到是哪个环节出了状况。
🔻
● openclaw.json 核心字段速查
最常用的字段整理出来，方便查阅：
{
"agents": {
"defaults": {
"model": {
"primary": "zai/glm-5.1",
"fallbacks": ["minimax/MiniMax-M2.7"]
}
},
"list": [{ "id": "main", "model": "zai/glm-5.1" }]
},
"gateway": { "port": 18789 },
"session": { "dmScope": "per-channel-peer" },
"channels": { "feishu": { "enabled": true } }
}
常用操作：换模型改 agents.defaults.model.primary，加渠道在 channels 下加配置块，改完 openclaw gateway restart 生效。
📌 小结：一个文件管完所有硬件配置。改完 restart 就生效。
🔻
● 写在最后
这篇覆盖了 OpenClaw 架构的五个维度：核心概念、目录结构、身份文件、消息生命周期、配置文件。
搞懂这些不需要写代码。OpenClaw 的设计哲学就是"配置即一切"——改文本文件就能改行为，改 JSON 就能改架构。
下一篇 L03，我们拆 Hermes Agent 的架构，重点对比两个框架的异同，以及双 Agent 共存的运维模式。
⚡
以上，如果觉得有用，请点个赞，谢谢。。
🏗️ 系统架构 | 💡 行业观察