夜雨聆风从架构设计到实现细节，5100 字拆解一个开源 AI 网关的核心技术
文章结构：
1. 整体架构 - Gateway 作为唯一真相源 • 配置热加载机制 • 无状态设计 2. 消息路由 - Binding 规则的确定性 • 9 层优先级决策树 • 配置示例 3. 多智能体隔离 - 每个 Agent 是独立的大脑 • Workspace / AgentDir / Session 三层隔离 • 同一 WhatsApp 号码服务多用户 4. 技能系统 - 插件化扩展机制 • 三级加载优先级 • 技能门控（Gating） • Token 影响 5. 记忆系统 - 双层设计 • 内置记忆（MEMORY.md + daily logs） • 扩展记忆（memory skill） • 记忆安全 6. 工具调用与沙箱 - 安全第一 • 3 种沙箱模式 • 3 种 scope • 工具策略 7. 会话管理 - DM 折叠与群聊隔离 • 4 种 dmScope • Thread Binding 8. Channel 实现 - 协议适配层 • DM Policy • 群聊提及规则 9. 配置管理 - JSON5 + $include • 模块化配置 • 环境变量替换 10. 设计哲学总结 • 确定性、隔离、可观测性、扩展性、开发者友好
我为什么要写这篇文章
我最近在研究如何让 AI Agent 真正融入日常工作流。试了一圈方案后发现：大多数要么是 SaaS（数据不在自己手上），要么是单点工具（换个渠道就得重来）。
直到我深入研究了 OpenClaw 的源码和架构。
这是一个自托管的多渠道 AI Agent 网关——听起来很抽象，但它的设计确实解决了一些很实际的问题。我想从技术角度拆解一下，它到底是怎么工作的。
一、整体架构：Gateway 作为唯一真相源
OpenClaw 的核心是一个 Gateway 进程，它做了三件事：
1. 消息路由：收消息，决定发给哪个 Agent 2. 会话管理：维护对话历史，处理上下文 3. 工具调用：让 AI 能执行代码、读写文件
关键设计决策：Gateway 是无状态的——所有状态都存储在文件系统（~/.openclaw/）。这意味着你可以随时重启 Gateway，会话不会丢失。
配置热加载
Gateway 监听 ~/.openclaw/openclaw.json 的变化，支持三种重载模式：
hybrid | |
hot | |
restart | |
off |
哪些变更需要重启？
• Gateway 服务器配置（端口、绑定、TLS） • 基础设施（discovery、canvasHost、plugins） • 其他所有配置都支持热加载
这个设计让我印象深刻——你改了渠道配置、Agent 设置、甚至工具策略，都不需要重启。
二、消息路由：Binding 规则的确定性
OpenClaw 的路由系统设计得非常清晰：Binding 规则是确定性的，最具体的匹配胜出。
路由优先级
Binding 配置示例
{ agents: { list: [ { id: "main", workspace: "~/.openclaw/workspace" }, { id: "work", workspace: "~/.openclaw/workspace-work" }, { id: "family", workspace: "~/.openclaw/workspace-family" }, ], }, bindings: [ // 最高优先级：精确 peer 匹配 { agentId: "work", match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551234567" } } }, // 群组匹配 { agentId: "family", match: { channel: "whatsapp", peer: { kind: "group", id: "1203630...@g.us" } } }, // 渠道级别匹配（最低优先级） { agentId: "main", match: { channel: "telegram" } }, ],}关键细节：
• 如果 Binding 省略 accountId，只匹配默认账户• 使用 accountId: "*"作为渠道级别的 fallback• 同一层级的多个匹配，按配置顺序选第一个
这个设计保证了路由行为是可预测的——不会出现"我不知道这条消息会去哪"的情况。
三、多智能体隔离：每个 Agent 是独立的大脑
OpenClaw 的多智能体设计解决了一个很实际的问题：如何在同一个 Gateway 下运行多个完全独立的 AI。
Agent 的隔离边界
每个 Agent 有自己的：
1. Workspace（工作空间） • 文件系统隔离 • 独立的 AGENTS.md/SOUL.md/USER.md• 独立的 skills/目录2. AgentDir（状态目录） • 认证配置： ~/.openclaw/agents/<agentId>/agent/auth-profiles.json• 模型注册表 • Per-Agent 配置 3. Session Store（会话存储） • 对话历史： ~/.openclaw/agents/<agentId>/sessions• 完全隔离，不共享上下文
一个 WhatsApp 号码，多个用户
这是个很巧妙的设计：你可以用同一个 WhatsApp 号码，把不同 DM 路由到不同 Agent：
{ agents: { list: [ { id: "alex", workspace: "~/.openclaw/workspace-alex" }, { id: "mia", workspace: "~/.openclaw/workspace-mia" }, ], }, bindings: [ { agentId: "alex", match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551230001" } } }, { agentId: "mia", match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551230002" } } }, ],}重要细节：DM 访问控制是全局的（per WhatsApp account），不是 per agent。私聊会折叠到 Agent 的 main session，所以真正的隔离需要一人一 Agent。
四、技能系统：插件化的扩展机制
技能（Skills）是 OpenClaw 的扩展机制，让 AI 能做更多事情。设计上参考了 AgentSkills 规范。
技能加载优先级
技能从三个地方加载，优先级从高到低：
1. Workspace Skills： <workspace>/skills/（Per-Agent）2. Managed Skills： ~/.openclaw/skills/（共享）3. Bundled Skills：随 OpenClaw 安装（内置）
技能格式
每个技能是一个目录，核心是 SKILL.md：
---name: feishu-docdescription: 获取飞书文档内容并转换为 Markdownmetadata: { "openclaw": { "requires": { "env": ["FEISHU_APP_ID", "FEISHU_APP_SECRET"] }, "primaryEnv": "FEISHU_APP_ID", } }---# 飞书文档技能## 使用方法提供飞书文档 URL，AI 会自动获取并转换为 Markdown。技能门控（Gating）
OpenClaw 在加载时过滤技能，基于 metadata.openclaw：
{ "requires": { "bins": ["uv"], // 必须存在于 PATH "env": ["GEMINI_API_KEY"], // 必须存在于环境或配置 "config": ["browser.enabled"] // 必须在 openclaw.json 中为真 }}Token 影响：
当有技能可用时，OpenClaw 会注入一个紧凑的 XML 列表到系统提示词。公式：
total_chars = 195 + Σ (97 + len(name) + len(description) + len(location))大约每个技能 24 tokens（按 OpenAI tokenizer 估算）。
ClawHub：技能市场
ClawHub 是官方技能市场：
# 安装技能clawhub install feishu-doc# 更新所有技能clawhub update --all五、记忆系统：双层设计
OpenClaw 的记忆系统是双层的：内置记忆 + 扩展记忆。
内置记忆（自动）
每个 Agent 自动拥有：
workspace/├── MEMORY.md # 长期记忆（重要决策、偏好）├── memory/│ ├── 2026-03-20.md # 今日日志│ ├── 2026-03-19.md # 昨日日志│ └── ...├── SOUL.md # AI 人格└── USER.md # 用户信息工作流程：
1. 会话启动时，AI 自动读取 MEMORY.md+ 最近两天日志2. 对话中记录到 memory/YYYY-MM-DD.md3. 定期提炼重要信息到 MEMORY.md
扩展记忆（可选）
安装 memory 技能后，支持无限分类存储：
clawhub install memory结构：
~/memory/├── config.md # 配置├── INDEX.md # 总索引├── projects/ # 项目历史│ ├── INDEX.md│ └── openclaw.md├── people/ # 人际网络│ └── john-doe.md└── knowledge/ # 领域知识 └── typescript.md语义搜索：
通过 memory_search 工具实现语义检索，快速定位相关记忆。
记忆安全
• 私聊记忆：仅在 main session 加载，不泄露给群聊 • 群聊记忆：独立会话，不污染私聊上下文 • Agent 隔离：每个 Agent 的记忆完全独立
六、工具调用与沙箱安全
OpenClaw 让 AI 能调用工具，但安全是第一优先级。
工具分类
read | ||
write | ||
edit | ||
exec | ||
image | ||
cron | ||
sessions_spawn |
沙箱模式
OpenClaw 支持 Docker 容器隔离，三种模式：
off | |
non-main | |
all |
Scope（容器数量）：
session | |
agent | |
shared |
Workspace Access
控制沙箱能看到的文件：
none | |
ro | /agent |
rw | /workspace |
配置示例
{ agents: { defaults: { sandbox: { mode: "non-main", scope: "session", workspaceAccess: "none", docker: { image: "openclaw-sandbox:bookworm-slim", network: "none", // 默认无网络 setupCommand: "apt-get update && apt-get install -y git curl", } } } }}工具策略（Tool Policy）
即使沙箱启用，工具策略仍然适用：
{ agents: { list: [ { id: "family", tools: { allow: ["read", "sessions_list"], deny: ["exec", "write", "edit", "cron"] } } ] }}Elevated 模式：tools.elevated 是显式的逃逸舱，允许在主机执行 exec。但需要发送者授权，且有严格的审批流程。
七、会话管理：DM 折叠与群聊隔离
OpenClaw 的会话设计有个核心概念：DM 折叠到 main session。
Session Scope
{ session: { dmScope: "per-channel-peer", // 推荐：多用户场景 // 可选：main | per-peer | per-channel-peer | per-account-channel-peer }}main | |
per-peer | |
per-channel-peer | |
per-account-channel-peer |
群聊隔离
群聊会话是独立的，不会污染私聊上下文：
Thread Binding（线程继承）
对于支持线程的平台（如 Discord），可以继承父会话：
{ session: { threadBindings: { enabled: true, idleHours: 24, // 空闲 24h 后解绑 maxAgeHours: 0, // 0 = 无上限 } }}八、Channel 实现：协议适配层
OpenClaw 支持多种渠道，每个渠道是一个协议适配层。
支持的渠道
DM Policy
所有渠道共享相同的 DM 策略模式：
{ channels: { telegram: { enabled: true, botToken: "123:abc", dmPolicy: "pairing", // pairing | allowlist | open | disabled allowFrom: ["tg:123"], // 仅 allowlist/open 需要 } }}pairing | |
allowlist | allowFrom 中的发送者 |
open | allowFrom: ["*"]） |
disabled |
群聊提及规则
群聊默认需要 @ 提及才响应：
{ agents: { list: [ { id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"], } } ] }, channels: { whatsapp: { groups: { "*": { requireMention: true } } } }}九、配置管理：JSON5 + $include
OpenClaw 使用 JSON5（支持注释和尾随逗号），并支持模块化配置。
$include 拆分配置
// ~/.openclaw/openclaw.json{ gateway: { port: 18789 }, agents: { $include: "./agents.json5" }, channels: { $include: ["./channels/whatsapp.json5", "./channels/telegram.json5"] }}规则：
• 单文件：替换包含对象 • 数组文件：按顺序深度合并（后者胜出） • 兄弟键：在 include 之后合并（覆盖包含值） • 嵌套 include：最多支持 10 层
环境变量替换
任何字符串值都可以引用环境变量：
{ models: { providers: { openai: { apiKey: "${OPENAI_API_KEY}" } } }}规则：
• 只匹配大写名称： [A-Z_][A-Z0-9_]*• 缺失变量在加载时报错 • 用 $${VAR}转义为字面值
十、总结：设计哲学
深入研究 OpenClaw 后，我总结出几个设计哲学：
1. 确定性优于魔法
• 路由规则是确定性的 • 配置是显式的 • 行为是可预测的
2. 隔离是第一优先级
• Agent 之间完全隔离 • 会话之间独立存储 • 沙箱提供额外保护
3. 可观测性
• 所有状态都在文件系统 • 配置热加载+自动重启 • 详细的日志和诊断
4. 扩展性
• 技能系统支持无限扩展 • ClawHub 提供社区生态 • 插件机制支持更多渠道
5. 开发者友好
• JSON5 配置（支持注释） • CLI 工具完整 • 文档详尽
技术栈一览
• 语言：TypeScript • 运行时：Node.js 22+ • 沙箱：Docker • 文档：Mermaid 图表 • 配置：JSON5
相关链接
• 🌐 官网：https://openclaw.ai • 📖 文档：https://docs.openclaw.ai • 💻 GitHub：https://github.com/openclaw/openclaw • 💬 社区：https://discord.com/invite/clawd • 🛒 技能市场：https://clawhub.com
写在最后
OpenClaw 不是完美的——它需要一定的技术背景，Docker 沙箱配置也有学习曲线。但作为一个自托管的多渠道 AI Agent 网关，它的设计是深思熟虑的。
如果你需要一个真正属于自己的 AI 助手，不想把数据交给第三方，OpenClaw 值得一试。
