整体架构
OpenClaw 的架构围绕一个核心理念：所有通讯平台的消息最终汇聚到同一个 AI Agent 运行时。Gateway 是中枢，负责连接、路由和管理。
架构全景
核心系统分层
OpenClaw 分为五个主要层次：
1. Gateway 控制平面
Gateway 是整个系统的神经中枢。它运行一个 WebSocket 服务，所有客户端（CLI、原生应用、Web UI）和通道（Telegram、Discord 等）都通过它通信。
关键职责：
| 职责 | 实现文件 | 说明 |
|---|---|---|
| WebSocket 服务 | src/gateway/server.impl.ts | 基于 ws 库的 WS 服务器 |
| 认证授权 | src/gateway/auth.ts | Token/Password/Tailscale 认证 |
| 方法派发 | src/gateway/server-methods.ts | 请求路由到对应 handler |
| 会话管理 | src/gateway/session-utils.ts | 会话状态、持久化、补丁 |
| 配置热加载 | src/gateway/config-reload.ts | chokidar 监听 + 增量重载 |
2. 通道抽象层
每个通讯平台都是一个"通道"（Channel），通过 Channel Plugin 接口统一抽象，再通过 Channel Dock 提供轻量元数据。
3. Agent 运行时
Agent 运行时负责与 AI 模型交互，处理工具调用，管理流式输出。核心入口是 subscribeEmbeddedPiSession()。
执行流程：
4. 插件系统
插件系统通过 Registry 管理工具、通道、Hooks 和 HTTP 路由的注册。支持热加载和生命周期管理。
插件注册类型：
| 类型 | 说明 |
|---|---|
PluginToolRegistration | 注册 Agent 工具（factory 模式） |
PluginChannelRegistration | 注册通道插件 + dock 元数据 |
PluginHookRegistration | 注册生命周期钩子 |
PluginHttpRegistration | 注册 HTTP 路由 |
PluginServiceRegistration | 注册后台服务 |
5. CLI 命令行
CLI 使用 Commander.js 构建，通过依赖注入模式 (createDefaultDeps()) 将通道发送函数注入到命令中。
请求-响应协议
Gateway 定义了标准的请求-响应-事件帧格式：
授权检查层次：
- 角色检查 — operator vs node
- 作用域检查 — admin, read, write, approvals, pairing
- 方法级权限 — 每个方法声明所需 scope
数据流：发送消息
完整的消息发送流程跨越多个层：
配置热加载策略
Gateway 通过 chokidar 监听配置文件变化，并按规则决定处理方式：
| 重载类型 | 说明 | 示例 |
|---|---|---|
restart | 需要完全重启 Gateway | 插件配置、Gateway 核心配置 |
hot | 运行时热加载 | Hooks、Cron、浏览器、通道配置 |
none | 忽略变更 | 身份配置、向导、日志、模型 |
变更有 300ms 去抖延迟，以合并快速连续的文件变化。
小结
- Gateway 是中枢：WebSocket 控制平面 + 方法派发 + 认证授权
- Channels 通过 Plugin + Dock 双层抽象统一不同平台
- Agent 运行时处理 AI 交互、工具调用、流式输出
- Plugins 提供可插拔的工具、通道、Hooks、HTTP 路由
- CLI 使用 Commander.js + 依赖注入，是用户的主要交互入口
下一章：项目结构