OpenClaw 源码架构深度解析:从消息到行动的完整旅程

OpenClaw 是一个开源的多通道 AI Gateway，能将 WhatsApp、Telegram、Discord、飞书等即时通讯工具统一接入 LLM Agent。本文从架构设计到源码路径，带你拆解这个项目的核心骨架。

一、全局架构鸟瞰

OpenClaw 的核心理念很简单：一个 Gateway 进程，统治所有消息通道。

这张图揭示了 OpenClaw 最核心的分层：

1. 消息通道层：各平台 SDK 负责收发原始消息

2. Gateway 核心层：路由、队列、会话管理

3. Agent 运行时层：模型调用、工具执行、技能加载

4. 外部依赖层：LLM API、插件、设备节点

二、消息的一生：从用户发送到 Agent 回复

让我们跟踪一条消息的完整生命周期。当你在 WhatsApp 上给 Agent 发一句”帮我查一下今天的天气”，背后发生了什么？

2.1 路由：消息如何找到正确的 Agent

OpenClaw 支持多 Agent 模式——一个 Gateway 可以同时运行多个独立的 AI 人格，每个有自己的工作空间、Session 存储和认证配置。

路由规则通过 bindings 配置，采用最精确匹配优先：

{
 bindings: [
   // 精确匹配：特定用户 → 特定 Agent
   { agentId: “work”, match: { channel: “whatsapp”, peer: { kind: “direct”, id: “+8613800138000” } } },
   // 通道匹配：所有 Telegram 消息 → 另一个 Agent
   { agentId: “deep”, match: { channel: “telegram” } },
   // 兜底：其他全部 → 默认 Agent
 ],
}

匹配优先级从高到低：peer > parentPeer > guildId+roles > guildId > accountId > channel > 默认 Agent。

2.2 命令队列：防止消息踩踏

当多条消息快速涌入同一个 Session，OpenClaw 用 Lane-FIFO 队列 保证有序处理：

关键设计：

• Session 内串行：同一 Session 的消息严格排队，避免 Session 文件竞争

• Session 间并行：不同 Session 可以并行执行，受全局并发上限控制

• 队列模式可选：collect（合并多条为一轮）、steer（注入当前运行）、followup（排队下轮）

{
 messages: {
   queue: {
     mode: “collect”,    // 合并模式：积攒消息后一次处理
     debounceMs: 1000,   // 等 1 秒没新消息才开始
     cap: 20,            // 最多积攒 20 条
     drop: “summarize”,  // 溢出时自动摘要
   },
 },
}

2.3 Session 管理：对话的记忆

每个对话（DM / 群聊 / Cron 任务）都有自己的 Session Key：

>

类型	Key 格式	示例
DM (主模式)	agent:<agentId>:main	agent:main:main
DM (按人隔离)	agent:<agentId>:<channel>:dm:<peerId>	agent:main:telegram:dm:123456
群聊	agent:<agentId>:<channel>:group:<id>	agent:main:whatsapp:group:120363...@g.us
Cron 任务	cron:<jobId>	cron:ab983e54-...

Session 的持久化很直白：

• 索引文件：~/.openclaw/agents/<agentId>/sessions/sessions.json

• 对话记录：~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl（每行一个 turn）

Session 重置策略支持每日重置（凌晨 4 点）和空闲重置（N 分钟无活动），两者谁先到期谁生效。

三、Agent Loop：大脑的工作循环

Agent Loop 是 OpenClaw 最核心的运行时——它把消息变成行动。

3.1 System Prompt：模型看到的世界

每次 Agent 运行，OpenClaw 都会动态组装 System Prompt，包含以下部分：

>

部分	内容	大小控制
Tooling	可用工具列表 + 描述	工具 Schema 是大头
Safety	安全护栏（不自我复制、不绕过监管）	固定几百字
Skills	技能列表（名字+描述+路径）	按需 read 加载详情
Workspace Files	AGENTS.md / SOUL.md / USER.md 等	每个文件最多 20K 字符
Runtime	主机/OS/模型/时区	一行

设计亮点：技能只注入元信息（名称+描述+文件路径），实际内容由模型自己决定是否 read 加载。这避免了所有技能全量注入导致的上下文爆炸。

3.2 工具执行：Agent 的手和脚

OpenClaw 内置 20+ 核心工具，覆盖文件操作、命令执行、浏览器控制、消息发送等：

四、插件系统：扩展的边界

OpenClaw 的插件系统是它区别于”简单 wrapper”的关键设计之一。

4.1 插件结构

每个插件需要一个 openclaw.plugin.json 清单文件：

{
 “id”: “my-channel”,
 “name”: “My Custom Channel”,
 “channels”: [“mychannel”],
 “configSchema”: {
   “type”: “object”,
   “properties”: {
     “apiKey”: { “type”: “string” },
     “webhook”: { “type”: “string” }
   },
   “additionalProperties”: false
 }
}

插件可以做三件事：

1. 注册新通道（Channel）：接入新的即时通讯平台

2. 注册 Agent 工具（Tool）：给 Agent 新的能力

3. 注册生命周期钩子（Hook）：在消息处理的各个阶段注入逻辑

4.2 Agent Tool 插件

让 Agent 获得新能力，最常见的插件类型：

// my-plugin/index.ts
import { Type } from “@sinclair/typebox”;

export default function (api) {
 api.registerTool({
   name: “query_database”,
   description: “查询内部数据库”,
   parameters: Type.Object({
     sql: Type.String({ description: “SQL 查询语句” }),
     database: Type.String({ description: “数据库名” }),
   }),
   async execute(_id, params) {
     const result = await runQuery(params.database, params.sql);
     return {
       content: [{ type: “text”, text: JSON.stringify(result) }],
     };
   },
 });
}

工具分为 required（默认启用）和 optional（需要在 tools.allow 中显式开启）两种：

{
 agents: {
   list: [{
     id: “main”,
     tools: {
       allow: [
         “query_database”,   // 按工具名启用
         “my-plugin”,        // 按插件 ID 启用所有工具
         “group:plugins”,    // 启用所有插件工具
       ],
     },
   }],
 },
}

4.3 生命周期钩子

插件可以在 Agent 运行的各个阶段注入逻辑：

实际场景举例：

• before_prompt_build：注入额外的系统提示（比如当前用户的权限级别）

• before_tool_call：拦截危险操作（比如阻止删除系统文件）

• agent_end：运行结束后发送统计数据

• message_received：入站消息过滤或转换

五、Gateway 设计：单进程的力量

5.1 WebSocket 协议

Gateway 的通信协议基于 WebSocket，纯 JSON 文本帧：

协议要点：

• 第一帧必须是 connect，否则直接断开

• 支持幂等键（idempotencyKey），安全重试

• 节点（Node）连接需要声明 role: "node" + 设备能力

5.2 配置热加载

修改 ~/.openclaw/openclaw.json 后，大部分配置无需重启即可生效：

>

分类	需要重启?
通道配置 channels.*	❌ 热加载
Agent/模型配置	❌ 热加载
自动化 hooks/cron	❌ 热加载
Session/消息配置	❌ 热加载
工具/技能/浏览器	❌ 热加载
Gateway 端口/绑定/TLS	✅ 需要重启
插件加载	✅ 需要重启

在默认的 hybrid 模式下，需要重启的配置变更会自动触发重启。

5.3 设备配对与信任

六、实战：写一个飞书消息通道插件

让我们以飞书插件为例，看看一个完整的 Channel 插件是怎么工作的。飞书作为 Extension 插件接入 OpenClaw，核心流程：

插件需要做的事情：

1. 接收飞书事件（消息、@提及、群聊变更）

2. 转换为 OpenClaw 内部消息格式（统一信封）

3. 注册通道特有工具（飞书文档读写、Wiki 操作等）

4. 处理媒体（图片下载/上传、文件收发）

配置示例：

{
 channels: {
   feishu: {
     enabled: true,
     appId: “cli_xxxxx”,
     appSecret: “xxxxx”,
     dmPolicy: “allowlist”,
     allowFrom: [“ou_xxxxx”],
   },
 },
}

这展示了 OpenClaw 插件系统的威力：任何即时通讯平台都可以通过同样的模式接入，而 Agent 逻辑完全不需要修改。

七、多 Agent 架构：一个 Gateway，多个人格

每个 Agent 拥有完全隔离的：

• 工作空间（不同的 SOUL.md = 不同的人格）

• Session 存储（对话历史不交叉）

• 认证配置（可以用不同的 LLM API Key）

• 工具策略（可以限制某些 Agent 的能力）

八、关键设计决策总结

>

设计选择	理由
单进程 Gateway	简化部署，避免分布式协调开销
WebSocket 协议	双向实时通信，支持流式推送
Lane-FIFO 队列	Session 内串行保证一致性，跨 Session 并行保证吞吐
技能延迟加载	避免上下文爆炸，按需读取
JSON5 配置	支持注释和尾逗号，对人类友好
插件清单校验	启动前发现配置错误，而不是运行时崩溃
配置热加载	改配置不断服务，hybrid 模式自动处理重启
JSONL 转录	增量写入，不会因为大 JSON 损坏全部历史

九、源码导航地图

如果你想深入阅读 OpenClaw 的源码，以下是关键路径：

openclaw/
├── docs/                        # 官方文档
│   ├── concepts/
│   │   ├── architecture.md      # 架构概览 ← 从这里开始
│   │   ├── agent-loop.md        # Agent 循环详解
│   │   ├── session.md           # Session 管理
│   │   ├── queue.md             # 命令队列
│   │   ├── system-prompt.md     # System Prompt 组装
│   │   └── context.md           # 上下文管理
│   ├── plugins/
│   │   ├── agent-tools.md       # 插件工具开发
│   │   └── manifest.md          # 插件清单规范
│   └── gateway/
│       ├── configuration.md     # 配置指南
│       └── protocol.md          # WebSocket 协议
├── dist/                        # 编译后的代码
│   ├── entry.js                 # 入口
│   ├── daemon-runtime-*.js      # Gateway 守护进程
│   ├── plugin-registry-*.js     # 插件注册表
│   └── session-*.js             # Session 管理
├── extensions/                  # 官方扩展（飞书等）
└── skills/                      # 内置技能

十、总结与预告

OpenClaw 的架构可以用一句话概括：一个 Gateway 进程 + 多通道适配器 + 可扩展的 Agent 运行时。

它的设计哲学很务实：

• 不做分布式：单进程足够大部分场景，省去了一切协调开销

• 通道即插件：新增通讯平台不需要改核心代码

• Agent 即配置：多人格、多工作空间、多策略，全部通过配置文件搞定

• 按需加载：技能不预加载、工具可选启用、上下文严格控制

对于想要搭建个人 AI 助手、或者需要在企业内部统一管理多个 AI Agent 的开发者来说，OpenClaw 的架构设计提供了一个非常好的参考。它证明了一件事：好的架构不是复杂的架构，而是恰到好处的架构。

🔮 下期预告：Pi-Agent 推理引擎与 ACP 协议

本文覆盖了 OpenClaw 的整体架构——Gateway、通道适配器、Session 管理、插件系统、命令队列。但有一个核心模块我们还没有深入：Pi-Agent（π-Agent）推理引擎。

Pi-Agent 是 OpenClaw 真正的「大脑」，它负责：

• 🧠 Agent Loop 推理循环：从接收用户消息到生成回复的完整思考链路

• 🔧 工具调用编排：如何决定调用哪些工具、如何处理工具返回结果、如何实现多轮工具调用

• 🌊 流式响应：Token 级别的实时流式输出机制

• 🤝 ACP（Agent Communication Protocol）集成：如何与外部 Agent 运行时（Codex、Claude Code 等）对接，实现跨 Agent 协作

这些内容将在下一篇文章中完整展开。如果你对 AI Agent 的推理实现细节感兴趣，敬请关注本系列的第二篇：《OpenClaw 源码深度解析（下）：Pi-Agent 推理引擎与 ACP 协议》。

本文基于 OpenClaw v2026.3.2 源码分析，项目地址：github.com/openclaw/openclaw
本文为 OpenClaw 架构解析系列第一篇，下篇将聚焦 Pi-Agent 推理引擎。