万字解析 OpenClaw 源码架构-消息渠道集成简介

渠道插件系统由"插件 SDK（编译期、稳定、可发布）"和"插件运行时（执行面、被注入）"两层组成，所有插件通过 SDK 暴露的类型与工具函数进行开发，并通过运行时访问核心行为，避免直接依赖 src/** 的内部实现。

• 插件 SDK：导出类型、配置工具、分组策略、消息处理辅助等，作为稳定接口层。
• 插件运行时：提供通道文本、回复、路由、配对、媒体、提及、群组策略、防抖、命令授权等运行期能力。
• 内置插件：以 extensions/* 下的具体渠道插件为代表，如 Discord、Telegram 等，遵循统一的 ChannelPlugin 合同并通过 openclaw.plugin.json 声明元数据。

graph TB subgraph "插件SDK" SDK_Index["SDK入口
src/plugin-sdk/index.ts"] SDK_Types["SDK类型与工具
src/channels/plugins/types.*"] SDK_RuntimeTypes["运行时类型
src/plugins/runtime/types.ts"] end subgraph "内置插件" Ext_Discord["Discord插件
extensions/discord/index.ts"] Ext_Telegram["Telegram插件
extensions/telegram/index.ts"] Ext_PluginJSON["插件清单
extensions/*/openclaw.plugin.json"] end SDK_Index --> Ext_Discord SDK_Index --> Ext_Telegram Ext_Discord --> Ext_PluginJSON Ext_Telegram --> Ext_PluginJSON SDK_Types --> SDK_Index SDK_RuntimeTypes --> SDK_Index

核心组件

• 插件 SDK 入口与导出：集中导出类型、适配器、配置模式、工具函数与运行时访问点，确保外部插件只依赖 SDK。
• ChannelPlugin 合同：定义渠道插件的 id、meta、capabilities、配置、适配器集合（认证、网关、消息、线程、目录、解析器、心跳等）以及可选的代理工具。
• 运行时接口 PluginRuntime：提供子代理运行、会话查询、删除，以及通道级能力（文本分块、路由、配对、媒体、提及、群组策略、防抖、命令授权等）。
• 插件 API OpenClawPluginApi：插件注册入口，支持注册工具、钩子、HTTP 路由、通道、网关方法、CLI、服务、提供商、命令与上下文引擎。
• 卸载流程：从配置中移除插件条目、安装记录、白名单、加载路径与内存槽位，保证干净卸载。

架构总览

插件系统采用"SDK + 运行时"的双层架构，确保：

• 可移植性：插件仅依赖 SDK 类型与工具，不直接导入 src/**。
• 可演进性：运行时版本与 SDK 版本独立管理，插件声明所需运行时范围。
• 可测试性：通过 adapter-level 单测与 golden 测试验证行为一致性。

sequenceDiagram participant Dev as "开发者" participant SDK as "插件SDK" participant Runtime as "插件运行时" participant Core as "核心系统" Dev->>SDK : 使用类型与工具开发插件 SDK->>Runtime : 通过api.runtime访问运行能力 Runtime->>Core : 访问核心行为路由、配对、媒体等 Core-->>Runtime : 返回结果或状态 Runtime-->>SDK : 提供统一运行时接口 SDK-->>Dev : 导出插件合约与工具

详细组件分析

插件 SDK 与运行时接口

• SDK 入口导出大量类型与工具，包括通道适配器、配置模式、分组策略、允许列表解析、命令授权、入站信封构建、回复派发、媒体处理、SSRF 策略、Webhook 内存守卫、日志与诊断事件等。
• 运行时接口提供：
  • 子代理运行与等待、会话消息读取、会话删除
  • 通道级能力：文本分块与长度解析、路由解析、配对、媒体抓取与保存、提及正则构建与匹配、群组策略解析、防抖器、命令授权

classDiagram class OpenClawPluginApi { +registerTool(tool, opts) +registerHook(events, handler, opts) +registerHttpRoute(params) +registerChannel(registration) +registerGatewayMethod(method, handler) +registerCli(registrar, opts) +registerService(service) +registerProvider(provider) +registerCommand(command) +registerContextEngine(id, factory) +resolvePath(input) +on(hookName, handler, opts) } class PluginRuntime { +subagent.run(params) +subagent.waitForRun(params) +subagent.getSessionMessages(params) +subagent.deleteSession(params) +channel.text.* +channel.reply.* +channel.routing.resolveAgentRoute(...) +channel.pairing.* +channel.media.* +channel.mentions.* +channel.groups.* +channel.debounce.* +channel.commands.* } OpenClawPluginApi --> PluginRuntime : "通过api.runtime访问"

ChannelPlugin 合同与扩展点

• ChannelPlugin 定义了插件的标识、元数据、能力、默认参数、重载前缀、引导向导、配置适配器、配置模式、设置、配对、安全、群组、提及、出站、状态、网关方法、网关、认证、提升权限、命令、流式、线程、消息、代理提示、目录、解析器、消息动作、心跳以及代理工具集合。
• 扩展点覆盖从"账户配置、目录、群组策略、消息路由、配对、安全策略、消息发送、状态探测、网关方法、消息动作、心跳"到"代理工具"的全链路能力。

classDiagram class ChannelPlugin { +id : ChannelId +meta : ChannelMeta +capabilities : ChannelCapabilities +defaults.queue.debounceMs +reload.configPrefixes +onboarding +config +configSchema +setup +pairing +security +groups +mentions +outbound +status +gatewayMethods[] +gateway +auth +elevated +commands +streaming +threading +messaging +agentPrompt +directory +resolver +actions +heartbeat +agentTools }

内置插件示例：Telegram 与 Discord

• Telegram 插件：通过入口文件注册运行时并注册通道插件，配置模式为空（无额外字段），体现最小化配置原则。
• Discord 插件：通过 openclaw.plugin.json 声明 id 与支持的渠道数组，配置模式为空对象，表明当前版本无特定配置项。

sequenceDiagram participant Entry as "插件入口
extensions/telegram/index.ts" participant SDK as "SDK" participant Runtime as "运行时" participant Registry as "通道注册表" Entry->>Runtime : setTelegramRuntime(api.runtime) Entry->>SDK : api.registerChannel({ plugin }) SDK->>Registry : 注册Telegram ChannelPlugin Note over Registry : 完成通道能力接入

插件安装、更新与卸载流程

• 安装：将插件源码置于工作区或全局路径，配置安装记录与加载路径；插件通过 openclaw.plugin.json 声明 id 与渠道支持。
• 更新：通过重新安装或替换插件包，保持配置兼容；运行时版本与 SDK 版本需满足兼容范围。
• 卸载：从配置中移除插件条目、安装记录、白名单、加载路径与内存槽位，确保无残留引用。

flowchart TD Start(["开始卸载"]) --> ReadCfg["读取配置中的插件段"] ReadCfg --> RemoveEntry["从entries移除插件"] ReadCfg --> RemoveInstall["从installs移除插件"] ReadCfg --> RemoveAllow["从allow移除插件"] ReadCfg --> CleanLoadPaths["从load.paths清理关联路径"] ReadCfg --> CleanupSlots["清理内存槽位"] RemoveEntry --> WriteCfg["写回配置"] RemoveInstall --> WriteCfg RemoveAllow --> WriteCfg CleanLoadPaths --> WriteCfg CleanupSlots --> WriteCfg WriteCfg --> End(["完成"])

自定义插件开发指南

• 契约与适配器：实现 ChannelPlugin 合同，按需提供 config、messaging、threading、directory、resolver、heartbeat、agentTools 等适配器。
• 配置模式：使用 SDK 提供的配置模式工具与 Schema 构建 UI 提示与校验逻辑。
• 运行时访问：通过 api.runtime 访问通道能力与核心行为，避免直接导入 src/**。
• 钩子与命令：注册插件钩子与命令，实现提示词注入、消息拦截、工具调用控制与简单命令处理。
• 文档与测试：遵循 SDK 版本与运行时版本兼容策略，提供 adapter-level 单测与 golden 测试。

API 接口规范与最佳实践

• 插件 API：统一的注册入口，支持工具、钩子、HTTP 路由、通道、网关方法、CLI、服务、提供商、命令与上下文引擎注册。
• 运行时接口：最小但完整的通道能力集合，确保跨渠道一致性。
• 最佳实践：
  • 严格遵循 SDK 类型与工具，避免直接依赖核心实现。
  • 使用运行时而非直接调用核心逻辑。
  • 为复杂场景提供适配器与配置模式，简化用户配置。
  • 通过钩子与命令实现非 LLM 的快速交互与状态切换。

安全机制、权限控制与性能监控

• 允许列表与分组策略：提供 allowlist 解析、分组访问决策、提及要求解析与工具策略，结合 DM 策略与命令授权，形成多层安全控制。
• SSRF 与请求限制：提供 SSRF 策略、HTTPS 允许列表、请求体大小限制与异常计数器，防止滥用与资源耗尽。
• 性能监控：通过诊断事件系统与运行时日志，记录消息队列、处理、工具调用、会话生命周期等关键指标，便于性能分析与问题定位。

依赖关系分析

• 插件 SDK 与运行时：SDK 仅暴露类型与工具，运行时提供执行面能力，二者通过 OpenClawPluginApi 关联。
• 内置插件与 SDK：内置插件通过 SDK 入口导出的类型与工具进行开发与注册，遵循统一合同。
• 卸载流程：依赖配置结构与路径清理，确保插件完全移除。

graph LR SDK_Index["SDK入口
src/plugin-sdk/index.ts"] --> Types_Plugin["ChannelPlugin类型
src/channels/plugins/types.plugin.ts"] SDK_Index --> Types_Runtime["运行时类型
src/plugins/runtime/types.ts"] Types_Plugin --> Ext_Discord["Discord插件
extensions/discord/index.ts"] Types_Plugin --> Ext_Telegram["Telegram插件
extensions/telegram/index.ts"] Uninstall["卸载流程
src/plugins/uninstall.ts"] --> Cfg["配置结构"]

性能考量

• 防抖与批处理：运行时提供入站消息防抖器，降低重复处理开销。
• 文本分块与媒体处理：提供文本分块与媒体加载优化，减少单次传输压力。
• 请求限制与异常追踪：通过请求体限制与异常计数器，避免过载与异常放大。
• 诊断事件：记录关键阶段的耗时与用量，辅助性能优化与容量规划。

渠道架构设计

OpenClaw 的渠道体系由"核心渠道类型定义""插件注册表与加载器""渠道停靠（Dock）元数据""健康监控与路由"等模块构成。下图展示关键模块之间的关系：

graph TB subgraph "渠道类型与适配器" Types["types.ts
类型导出"] TypesCore["types.core.ts
核心类型"] TypesAdapters["types.adapters.ts
适配器接口"] end subgraph "插件系统" Registry["plugins/registry.ts
插件注册表"] Loader["channels/plugins/registry-loader.ts
通道注册表加载器"] LoadPlugin["channels/plugins/load.ts
加载插件"] LoadOutbound["channels/plugins/outbound/load.ts
加载出站适配器"] end subgraph "渠道停靠与元数据" Dock["channels/dock.ts
渠道停靠(Dock)"] Reg["channels/registry.ts
渠道注册表/别名"] end subgraph "运行时与监控" Health["gateway/channel-health-monitor.ts
健康监控"] Router["infra/outbound/bound-delivery-router.ts
绑定投递路由器"] DeliveryCmd["commands/agent/delivery.ts
交付命令"] end Types --> TypesCore Types --> TypesAdapters Registry --> Loader Loader --> LoadPlugin Loader --> LoadOutbound Dock --> Reg Dock --> Loader Health --> Registry Router --> Registry DeliveryCmd --> Loader

核心组件

• 渠道类型与适配器接口

  • 类型导出与核心类型：统一导出渠道适配器、账户快照、能力集、消息动作等类型定义，便于跨模块复用。
  • 适配器接口：定义配置、状态、网关、认证、心跳、目录解析、线程处理、消息动作等适配器契约，确保不同渠道实现的一致性与可替换性。

• 插件注册表与加载器

  • 插件注册表：集中记录已加载的插件、工具、钩子、HTTP 路由、命令、服务等，并维护渠道注册项列表。
  • 注册表加载器：基于活跃插件注册表，按渠道 ID 缓存并解析对应插件或适配器实例，避免重复导入与副作用。

• 渠道停靠（Dock）

  • 停靠元数据：为内置渠道提供能力集、默认文本分片限制、提及规则、线程上下文构建、允许来源解析与格式化等轻量行为描述。
  • 动态停靠：从插件构建停靠信息，支持外部渠道扩展。

• 健康监控与路由

  • 健康监控：周期性检查渠道运行时快照，评估健康度并执行重启策略，带冷却与限速保护。
  • 绑定投递路由器：根据会话绑定与请求者信息解析目标渠道账户，支持单活绑定与回退模式。

架构总览

下图展示渠道适配器在系统中的位置与交互关系：

graph TB Client["客户端/命令行"] --> DeliveryCmd["交付命令
commands/agent/delivery.ts"] DeliveryCmd --> Loader["插件加载器
channels/plugins/load.ts"] Loader --> Registry["插件注册表
plugins/registry.ts"] Registry --> Dock["渠道停靠
channels/dock.ts"] Dock --> Router["绑定投递路由器
infra/outbound/bound-delivery-router.ts"] Dock --> Health["健康监控
gateway/channel-health-monitor.ts"] Dock --> Types["类型与适配器
channels/plugins/types.*.ts"]

详细组件分析

注册表系统与插件加载

• 设计要点

  • 活跃注册表缓存：加载器在首次访问时读取当前活跃注册表，若注册表变更则清空缓存，保证一致性。
  • 值解析器抽象：通过通用工厂函数将插件注册项映射为具体适配器或插件对象，支持出站适配器专用加载路径以降低导入成本。
  • 错误与诊断：注册表对缺失 ID、重复注册、HTTP 路由冲突等情况进行诊断并记录。

• 关键流程（加载插件）

sequenceDiagram participant Cmd as "交付命令" participant Loader as "插件加载器" participant Registry as "插件注册表" participant Dock as "渠道停靠" Cmd->>Loader : 请求加载渠道插件 Loader->>Registry : 查询通道注册项 alt 找到注册项 Loader->>Loader : 解析插件/适配器 Loader-->>Cmd : 返回适配器实例 Loader->>Dock : 构建停靠元数据 else 未找到 Loader-->>Cmd : 返回未命中 end

配置管理与停靠元数据

• 设计要点

  • 内置渠道停靠：为 Telegram、WhatsApp、Discord、IRC、Google Chat、Slack、Signal、iMessage、LINE 等内置渠道提供统一的能力集、默认文本分片限制、提及规则与线程上下文构建。
  • 外部渠道停靠：从插件动态构建停靠信息，保持与内置渠道一致的行为边界。
  • 允许来源与默认目标：针对不同渠道提供允许来源解析与格式化、默认目标解析逻辑，确保安全与可用性。

• 关键流程（解析允许来源）

flowchart TD Start(["开始"]) --> Resolve["解析渠道配置
resolveAllowFrom"] Resolve --> Format["格式化允许来源
formatAllowFrom"] Format --> Apply["应用到线程/投递上下文"] Apply --> End(["结束"])

消息路由与状态同步

• 设计要点

  • 绑定投递路由器：根据目标会话键与活动绑定列表解析最终投递目标；当存在多个绑定或缺少请求者时采用回退模式，确保在多账户场景下的正确路由。
  • 状态同步：渠道状态快照包含启用/配置/连接/最近事件时间戳、错误信息、令牌状态等字段，用于健康监控与诊断。

• 关键流程（绑定路由解析）

flowchart TD S(["输入: 目标会话键, 请求者"]) --> CheckKey{"会话键为空?"} CheckKey -- 是 --> Fallback["返回回退模式
原因: 缺少目标会话"] CheckKey -- 否 --> List["列出该会话的活动绑定"] List --> HasAny{"是否存在活动绑定?"} HasAny -- 否 --> Fallback2["返回回退模式
原因: 无活动绑定"] HasAny -- 是 --> HasReq{"是否有请求者?"} HasReq -- 否 --> Single{"绑定数量=1?"} Single -- 是 --> Bound["返回绑定模式
原因: 单一活动绑定"] Single -- 否 --> Fallback3["返回回退模式
原因: 无请求者且不唯一"] HasReq -- 是 --> Multi{"绑定数量>1?"} Multi -- 是 --> Fallback4["返回回退模式
原因: 不明确(多绑定)"] Multi -- 否 --> Bound

生命周期管理与健康监控

• 设计要点

  • 周期性检查：健康监控器在启动宽限期后开始定期检查渠道运行时快照，评估连接状态与事件新鲜度。
  • 重启策略：对不健康的渠道执行停止/启动组合操作，带冷却周期与每小时最大重启次数限制，防止风暴重启。
  • 可配置参数：检查间隔、启动宽限期、事件过期阈值、连接宽限期等均可配置。

• 关键流程（健康检查与重启）

sequenceDiagram participant Monitor as "健康监控器" participant Manager as "渠道管理器" participant Snapshot as "运行时快照" Monitor->>Monitor : 计算冷却与限速 Monitor->>Manager : 获取运行时快照 Manager-->>Monitor : 返回快照 Monitor->>Monitor : 评估每个渠道健康度 alt 不健康 Monitor->>Monitor : 记录重启记录 Monitor->>Manager : 停止渠道 Monitor->>Manager : 启动渠道 else 健康 Monitor->>Monitor : 无需操作 end

数据传输协议、序列化与事件传播

• 协议与序列化

  • 出站适配器支持直接/网关/混合三种投递模式，并提供文本分片器与轮询选项上限，确保消息在不同渠道间的可靠传输。
  • 消息动作适配器定义了可发现的动作清单、按钮/卡片支持与工具发送提取逻辑，便于跨渠道统一事件传播。

• 事件传播

  • 网关上下文提供日志、状态读写与可选的渠道运行时辅助能力，使外部插件能够参与 AI 回复派发、路由、文本处理、会话管理、媒体处理、命令授权与群组策略等高级功能。

错误恢复策略与性能优化

• 错误恢复

  • 健康监控器在检测到异常后执行重启，同时应用冷却与限速，避免频繁重启导致雪崩。
  • 出站适配器提供分片与轮询上限，减少单次传输失败的影响面。

• 性能优化

  • 加载器缓存：按渠道 ID 缓存解析结果，避免重复解析与昂贵的插件导入。
  • 轻量化出站加载：出站路径仅加载必要能力，降低导入成本。
  • 文本分片：针对不同渠道设置合理的文本分片限制，平衡吞吐与兼容性。

依赖关系分析

• 组件耦合

  • 渠道类型与适配器接口是所有渠道实现的基础契约，耦合度低、内聚性强。
  • 插件注册表与加载器承担"发现---解析---缓存"的职责，与具体渠道实现解耦。
  • 渠道停靠聚合了渠道行为的轻量元数据，既可来自内置定义，也可来自插件构建，形成统一入口。

• 外部依赖与集成点

  • 健康监控依赖渠道管理器提供的运行时快照与控制接口。
  • 投递路由器依赖会话绑定服务与渠道账户状态。
  • 交付命令依赖插件注册表以解析渠道插件。

graph LR Types["类型与适配器"] --> Dock["渠道停靠"] Dock --> Loader["注册表加载器"] Loader --> Registry["插件注册表"] Dock --> Router["绑定投递路由器"] Dock --> Health["健康监控"] Router --> Registry Health --> Registry DeliveryCmd["交付命令"] --> Loader

性能考虑

• 导入与初始化
  • 使用注册表加载器缓存解析结果，避免重复扫描与昂贵的插件导入。
  • 出站加载器仅加载必要能力，缩短冷启动路径。
• 文本分片与传输
  • 针对不同渠道设置合理的文本分片限制，兼顾吞吐与平台兼容性。
  • 轮询选项上限限制长轮询带来的资源占用。
• 健康监控节流
  • 通过冷却周期与每小时重启上限，避免风暴重启对系统造成压力。

渠道配置管理

渠道配置管理涉及以下关键模块：

• 配置读写与验证：负责配置的加载、校验、写回与变更检测
• 动态重载与热重载：监听配置文件变化，评估变更影响并执行重启或热更新
• 渠道插件配置模式：统一构建渠道配置的 JSON Schema，并支持多账户与默认账户
• 备份与恢复：生成可验证的归档，记录清单并支持恢复
• UI 表单渲染：基于通道 Schema 动态渲染表单，支持额外字段展示
• 安全审计：对渠道安全策略进行审计与告警

graph TB subgraph "配置层" CFG["配置读写与验证
src/config/*"] VALID["配置验证器
validation.ts"] MIG["配置迁移
legacy-migrate.ts"] ENV["环境变量保留
env-preserve.ts"] end subgraph "网关与重载" RELOAD["配置重载器
config-reload.ts"] PLAN["重载计划
config-reload-plan.ts"] HANDLER["重启处理器
server-reload-handlers.ts"] end subgraph "渠道插件" SCHEMA["通道配置Schema构建
config-schema.ts"] HELPERS["通道配置辅助
config-helpers.ts"] ONBOARD["引导配置辅助
onboarding/helpers.ts"] end subgraph "命令与工具" BACKUP["备份命令
commands/backup.ts"] VERIFY["备份验证
commands/backup-verify.ts"] ADD["添加渠道账户
commands/channels/add.ts"] DOCTOR["安全审计
commands/doctor-security.ts"] end subgraph "界面" UI["通道配置表单
ui/views/channels.config.ts"] end CFG --> VALID CFG --> MIG CFG --> ENV CFG --> RELOAD RELOAD --> PLAN RELOAD --> HANDLER SCHEMA --> UI HELPERS --> ADD ONBOARD --> ADD BACKUP --> VERIFY DOCTOR --> UI

核心组件

• 配置读写与验证
  • 提供配置加载、快照读取、写回、运行时快照刷新等能力
  • 统一的配置对象验证流程，支持插件配置校验与警告收集
• 动态重载与热重载
  • 基于文件监控的变更检测，计算差异路径，构建重载计划
  • 支持 off/restart/hot/hybrid 模式，自动选择重启或热更新
• 渠道配置 Schema 与多账户
  • 使用 Zod 构建 JSON Schema，兼容旧版插件
  • 支持 accounts.catchall 与 defaultAccount，实现多账户与默认账户
• 环境变量保留
  • 在写回时识别并保留 ${VAR} 引用，避免丢失原始占位符
• 备份与恢复
  • 生成带清单的压缩归档，支持输出路径解析、硬链接/拷贝发布、可选验证
  • 验证清单格式与字段完整性，确保可恢复性
• UI 表单渲染
  • 基于通道 Schema 动态渲染表单，支持额外字段展示（如 groupPolicy、streamMode、dmPolicy）

架构总览

下图展示了从配置文件到运行时生效的关键流转：文件监控触发重载计划，评估是否需要重启或热更新；同时，配置验证与迁移保证数据一致性；环境变量保留确保写回后仍能保留占位符；备份与验证保障可恢复性。

sequenceDiagram participant FS as "文件系统" participant Watch as "配置重载器
config-reload.ts" participant Plan as "重载计划
config-reload-plan.ts" participant Handler as "重启处理器
server-reload-handlers.ts" participant Valid as "配置验证
validation.ts" participant Env as "环境变量保留
env-preserve.ts" FS-->>Watch : "文件变更事件" Watch->>Watch : "读取配置快照" Watch->>Valid : "验证配置" Valid-->>Watch : "返回验证结果" Watch->>Plan : "构建重载计划" Plan-->>Watch : "返回计划(重启/热更新)" alt "需要重启" Watch->>Handler : "请求重启" Handler-->>Watch : "重启完成" else "热更新" Watch-->>Watch : "执行热更新" end Watch->>Env : "写回前保留环境变量引用" Env-->>Watch : "返回保留后的配置" Watch-->>FS : "写回配置文件"

详细组件分析

配置文件结构与参数定义

• 结构要点
  • 顶层包含 gateway、channels、plugins、agents、tools 等命名空间
  • channels 下按渠道 ID 维度组织，支持 accounts.catchall 与 defaultAccount
  • 插件配置通过 plugins.entries..config 进行声明
• 参数定义
  • 使用 Zod Schema 生成 JSON Schema，用于 UI 表单渲染与前端校验
  • 兼容旧版 Zod v3 的插件，若缺少 toJSONSchema 则退化为允许任意属性的对象
• 验证机制
  • 原始验证与应用默认值验证两条路径
  • 对插件配置进行独立 Schema 校验，收集错误与警告
  • 特定约束检查（如头像路径、Tailscale 绑定规则等）

flowchart TD Start(["开始"]) --> Load["加载配置"] Load --> ValidateRaw["原始验证
validateConfigObjectRaw"] ValidateRaw --> Valid{"验证通过？"} Valid --> |否| ReportIssues["报告问题"] Valid --> |是| ApplyDefaults["应用默认值"] ApplyDefaults --> PluginValidate["插件配置验证"] PluginValidate --> Issues{"有错误？"} Issues --> |是| ReportIssues Issues --> |否| Done(["完成"])

动态配置更新与热重载

• 变更检测
  • 计算前后配置的差异路径，数组采用深度比较以避免误报
  • 支持缺失配置的有限次重试，降低瞬时文件系统抖动的影响
• 重载决策
  • 基于预设规则集匹配变更路径，决定 restart/hot/none
  • 支持插件贡献的热更新/无操作前缀，实现通道级热更新
• 执行策略
  • hybrid/off/restart/hot 模式由 gateway.reload.mode 控制
  • 热更新失败时记录日志并保持重载器运行等待下次变更
• 文件监控
  • 使用 chokidar 监听配置文件目录，等待写入完成后再触发重载

flowchart TD S(["收到变更事件"]) --> Snapshot["读取配置快照"] Snapshot --> Missing{"文件存在？"} Missing --> |否| Retry["有限重试/跳过"] Missing --> |是| Valid{"快照有效？"} Valid --> |否| Skip["跳过并记录问题"] Valid --> |是| Diff["计算差异路径"] Diff --> Plan["构建重载计划"] Plan --> Mode{"模式？"} Mode --> |off| Stop["停止重载"] Mode --> |restart| QueueRestart["排队重启"] Mode --> |hot| Hot["执行热更新"] Mode --> |hybrid且需重启| QueueRestart Mode --> |hybrid且可热更新| Hot Hot --> End(["结束"]) QueueRestart --> End Skip --> End Retry --> End

配置迁移

• 迁移流程
  • 应用遗留配置迁移规则，得到新配置与变更说明
  • 对迁移后的配置再次进行验证，若仍有问题则提示人工修复
• 适用场景
  • 升级过程中自动修复不兼容字段
  • 保持配置可用性的同时尽量减少人工干预

sequenceDiagram participant Raw as "原始配置" participant Mig as "迁移器
legacy-migrate.ts" participant Val as "验证器
validation.ts" Raw->>Mig : "迁移" Mig->>Val : "验证迁移后配置" Val-->>Mig : "返回验证结果" Mig-->>Raw : "返回迁移后的配置/变更说明"

多账户支持与默认账户

• 多账户模型
  • 通过 accounts.catchall 接受任意键值，结合 defaultAccount 指定默认账户
  • 支持按账户维度启用/禁用与配置状态判断
• 账户上下文
  • 解析默认账户 ID、账户详情、启用状态与配置状态
• 账户操作
  • 添加/删除账户、启用状态切换、配置补丁更新
  • 渠道令牌轮换后清理相关状态（如 Telegram 更新偏移）

classDiagram class ChannelPlugin { +listAccountIds(cfg) +resolveAccount(cfg, accountId) +config.isEnabled(account, cfg) +config.isConfigured(account, cfg) } class ChannelAccountContext { +accountIds : string[] +defaultAccountId : string +account : unknown +enabled : boolean +configured : boolean } ChannelPlugin --> ChannelAccountContext : "解析默认账户上下文"

配置模板与环境变量替换

• 环境变量替换
  • 支持 ${VAR} 语法，字符串中可包含多个变量与混合内容
  • 严格名称规范（大写字母、数字、下划线，可以下划线开头）
• 写回时的引用保留
  • 当写回值与当前环境变量展开一致时，恢复原始 ${VAR} 引用
  • 避免无意中将占位符替换为实际值，导致后续启动时无法正确展开

flowchart TD A["读取配置(含${VAR})"] --> B["解析环境变量"] B --> C["写回配置"] C --> D{"写回值与解析值一致？"} D --> |是| E["恢复${VAR}引用"] D --> |否| F["保留写回值"] E --> G["写回文件"] F --> G

UI 表单渲染与额外字段展示

• Schema 解析
  • 基于通道 Schema 动态生成表单节点，支持对象与数组类型
  • 通过路径定位到具体通道的配置节点
• 额外字段
  • 展示 groupPolicy、streamMode、dmPolicy 等非表单字段的当前值
  • 便于用户快速了解通道的附加行为设置

sequenceDiagram participant UI as "UI 表单
channels.config.ts" participant Schema as "通道 Schema" participant Value as "通道配置值" UI->>Schema : "解析通道 Schema" UI->>Value : "获取通道配置值" UI->>UI : "渲染表单节点" UI->>UI : "展示额外字段"

安全考虑与审计

• 默认账户令牌策略
  • 默认账户允许使用环境变量令牌，命名账户不允许直接注入环境令牌
• 安全审计
  • 对启用且已配置的通道收集安全策略与警告
  • 支持 DM 策略可视化与建议修复

flowchart TD Start(["安全审计"]) --> List["枚举通道插件"] List --> Check{"启用且已配置？"} Check --> |否| Next["下一个"] Check --> |是| Policy["解析DM策略/收集警告"] Policy --> Warn["输出警告/建议"] Warn --> Next Next --> End(["结束"])

版本管理、备份恢复与批量部署

• 备份
  • 自动解析输出路径，支持目录与文件两种形式
  • 生成清单并打包为压缩归档，支持硬链接/拷贝发布
  • 可选验证步骤，确保归档完整性
• 恢复
  • 验证清单格式与字段，确保 schemaVersion、archiveRoot、createdAt 等字段有效
  • 校验资产列表与跳过项，防止越界与重复
• 批量部署
  • 通过 CLI 命令批量添加渠道账户，自动处理默认账户与启用状态
  • 支持令牌轮换后的状态清理（如 Telegram）

sequenceDiagram participant CLI as "CLI 备份命令" participant Plan as "备份计划" participant Tar as "归档打包" participant Ver as "备份验证" CLI->>Plan : "解析包含资产/路径" CLI->>Tar : "生成清单并打包" Tar-->>CLI : "输出归档路径" CLI->>Ver : "可选验证" Ver-->>CLI : "验证结果"

依赖关系分析

• 组件耦合
  • 配置重载器依赖重载计划与重启处理器，形成清晰的职责分离
  • 渠道插件通过 Schema 构建与 UI 表单解耦，便于扩展
  • 备份命令与验证命令相互独立，便于测试与维护
• 外部依赖
  • chokidar 用于文件监控
  • tar 用于归档打包
  • Zod 用于配置 Schema 生成与校验

graph TB CR["config-reload.ts"] --> CRP["config-reload-plan.ts"] CR --> SRH["server-reload-handlers.ts"] CS["config-schema.ts"] --> UI["channels.config.ts"] VAL["validation.ts"] --> CFG["config.ts"] ENV["env-preserve.ts"] --> CFG BK["backup.ts"] --> VER["backup-verify.ts"] CHADD["commands/channels/add.ts"] --> CFG

性能考量

• 文件监控稳定性
  • 使用 awaitWriteFinish 避免写入中途触发重载
  • 在测试环境下启用轮询模式，提升可靠性
• 重载节流
  • 通过去抖与并发标记避免频繁重载
  • 缺失配置的有限重试策略降低无效工作负载
• 归档性能
  • 优先使用硬链接发布，不支持时回退到拷贝
  • 压缩与便携选项平衡体积与跨平台兼容性

消息渠道集成

项目采用模块化设计，核心由以下部分组成：

• 网关（Gateway）：WebSocket控制平面，承载会话、存在性、配置、定时任务、钩子与事件分发
• 渠道适配器（Channel Adapters）：针对各消息平台的接入层，负责认证、连接、消息收发与格式转换
• 客户端与节点（Clients & Nodes）：桌面应用、CLI、Web界面与移动节点通过WS连接到网关
• 插件与技能（Plugins & Skills）：扩展能力与自动化工作流

graph TB subgraph "网关控制平面" GW["Gateway
WebSocket 控制面"] CFG["配置中心"] SESS["会话存储"] EVT["事件总线"] end subgraph "渠道适配器" WA["WhatsApp Baileys"] TG["Telegram grammY"] DC["Discord Bot API"] SG["Signal signal-cli"] IM["iMessage imsg"] GC["Google Chat HTTP"] Others["其他渠道..."] end subgraph "客户端与节点" CLI["CLI 工具"] WEB["WebChat UI"] MAC["macOS 应用"] IOS["iOS 节点"] AND["Android 节点"] end CLI --> GW WEB --> GW MAC --> GW IOS --> GW AND --> GW GW --> WA GW --> TG GW --> DC GW --> SG GW --> IM GW --> GC GW --> Others CFG --> GW SESS --> GW EVT --> GW

核心组件

• 网关（Gateway）
  • 维护各提供商连接，暴露类型化WebSocket API（请求/响应/服务端推送事件）
  • 验证入站帧，发出事件如agent、chat、presence、health、heartbeat、cron
• 渠道适配器（Channel Adapters）
  • 各平台专用适配器，负责认证、连接生命周期、消息路由与格式转换
  • 支持多账户、多账号实例、群组/频道/私聊隔离
• 会话与路由（Sessions & Routing）
  • 基于会话键（session key）的确定性路由，确保回复回到原渠道
  • 支持主会话共享、按对端/按渠道/按账号隔离
• 安全与配对（Security & Pairing）
  • 默认对未知发送者启用配对模式；允许通过批准码加入白名单
  • 设备级配对与本地信任模型，支持远程隧道与令牌认证

架构总览

系统采用单网关控制平面，所有消息表面（WhatsApp、Telegram、Discord、Signal、iMessage、WebChat等）均由网关统一持有连接与会话状态。客户端（桌面应用、CLI、Web UI、自动化）通过WebSocket连接到网关，节点（macOS/iOS/Android/headless）同样通过WebSocket连接并声明角色与权限。

sequenceDiagram participant Client as "客户端/节点" participant Gateway as "网关" participant Adapter as "渠道适配器" participant Provider as "消息平台" Client->>Gateway : 连接握手(connect) Gateway-->>Client : 连接成功(状态快照) Gateway-->>Client : 推送事件(presence/tick) Client->>Gateway : 请求(agent/send/...) Gateway->>Adapter : 分发到对应渠道 Adapter->>Provider : 发送/接收消息 Provider-->>Adapter : 平台事件 Adapter-->>Gateway : 标准化消息 Gateway-->>Client : 返回结果/事件流

详细组件分析

渠道适配器架构

• 共同特征
  • 认证与凭据管理：各渠道通过配置或环境变量提供凭据；部分渠道支持密钥管理（SecretRef）
  • 连接与重连：网关负责维持长连接与重连逻辑，避免重复会话
  • 消息路由：入站消息标准化为统一信封，出站消息根据会话键回送到原渠道
  • 会话隔离：私聊共享主会话，群组/频道/论坛主题保持独立会话
• 多账户支持：各渠道支持多账号实例，可通过默认账号与账号级覆盖实现差异化策略
• 配置写入：多数渠道允许通过命令或事件触发配置写入（需显式开启）

连接管理与生命周期

• 连接建立：首次帧必须为connect；握手后请求/响应与事件推送
• 认证：可选令牌认证（OPENCLAW_GATEWAY_TOKEN），节点需包含角色与权限声明
• 重连与健康：网关维护心跳与健康检查，异常时自动重连
• 远程访问：支持Tailscale Serve/Funnel或SSH隧道，配合令牌/密码认证

消息路由与状态同步

• 确定性路由：回复总是回到消息来源渠道，模型不选择渠道
• 会话键规则：私聊使用主会话键；群组/频道/论坛主题使用带标识的键
• 状态同步：事件不重放，客户端断线后需刷新以重建状态

渠道特定实现概览

WhatsApp（Web）

• 运行模型：网关拥有链接会话，忽略@status与@broadcast
• 访问控制：默认DM策略为配对；群组支持允许列表与提及门控
• 消息处理：媒体占位符、位置/联系人提取、未处理历史注入
• 多账户：支持多账号实例与凭据路径
• 故障排除：未链接、断开重连、无活动监听器、群消息被忽略等问题排查

Telegram（Bot API）

• 运行模型：grammY Runner长轮询；Webhook可选；支持论坛主题
• 访问控制：DM策略与群组策略分离；提及门控默认开启
• 功能特性：实时预览流、HTML解析回退、内联按钮、贴纸动作、反应通知、投票
• 限制与重试：文本分块、媒体上限、超时与网络不稳定处理
• 故障排除：隐私模式、命令不可用、轮询/网络问题

Discord（Bot API）

• 运行模型：官方网关；支持论坛/媒体频道；交互组件（buttons/selects/modals）
• 访问控制：DM策略；公会策略（允许列表/开放/禁用）；基于角色的代理路由
• 功能特性：实时预览流、历史上下文、线程绑定会话、持久ACP绑定、反应通知、确认反应
• 故障排除：意图权限、命令可见性、线程绑定与ACP会话

Signal（signal-cli）

• 运行模型：通过HTTP JSON-RPC + SSE与signal-cli通信；设备模型（专用号码）
• 访问控制：DM配对；群组策略；UUID/号码识别
• 功能特性：打字指示、已读回执转发、反应动作、媒体限制、分块策略
• 故障排除：守护进程可达性、DM被忽略、群消息被阻、配置校验

iMessage（legacy imsg）

• 运行模型：通过stdio JSON-RPC与imsg通信；推荐新部署使用BlueBubbles
• 访问控制：DM策略；群组策略；提及门控（正则）
• 功能特性：附件与媒体、分块策略、远端附件抓取（SSH/SCP）
• 故障排除：权限提示、DM被忽略、群消息被忽略、远端附件失败

自定义渠道开发指南

• 适配器接口：遵循网关协议，实现connect/req/res/event帧交换
• 认证与凭据：支持环境变量、SecretRef与多账户配置
• 连接与重连：实现稳定的心跳与重连策略
• 消息格式：输入标准化为统一信封，输出按渠道格式转换
• 会话与路由：使用会话键规则，确保回复回到原渠道
• 安全与配对：实现配对流程与白名单策略
• 扩展机制：通过插件与技能扩展能力，遵循工具策略与沙箱配置

依赖关系分析

• 渠道适配器依赖网关协议与配置中心，确保一致的认证、路由与会话行为
• 客户端与节点通过WebSocket与网关交互，节点需声明角色与权限
• 事件总线驱动各组件协作，确保状态一致性与可观测性

graph LR GW["网关"] --> CFG["配置中心"] GW --> ADAPTERS["渠道适配器集合"] ADAPTERS --> PROVIDERS["消息平台API"] CLIENTS["客户端/节点"] --> GW GW --> EVT["事件总线"] EVT --> CLIENTS

性能考虑

• 连接复用：网关统一持有各渠道连接，避免重复会话与资源浪费
• 会话隔离：按渠道/账号/对端隔离，减少并发冲突与状态竞争
• 流式输出：Telegram/Discord支持实时预览流，提升用户体验
• 媒体优化：图片压缩与大小限制，降低传输与渲染成本
• 重试与降级：对外部API错误进行可恢复重试与降级策略

Web 聊天集成

WebChat 在本仓库中的定位是"网关 WebSocket 的聊天 UI"，不包含本地静态服务器或嵌入式浏览器，而是通过原生应用（macOS/iOS）或控制面板的聊天标签页直接连接到网关 WebSocket，复用相同的会话与路由规则，确保回复始终回到 WebChat。

graph TB subgraph "客户端" UI["WebChat 原生视图
或 控制面板聊天标签"] end subgraph "网关" WS["WebSocket 服务端"] CHAT["聊天通道(chat.*)"] AUTH["认证与授权"] end UI --> WS WS --> CHAT WS --> AUTH

核心组件

• 网关 WebSocket 接口
  • chat.history：历史消息获取（受稳定性限制，可能截断长文本、省略重元数据）
  • chat.send：发送消息
  • chat.inject：向对话注入助手备注（无代理执行）
  • chat.abort：中止运行（保留部分输出可见）
  • 事件：chat、agent、presence、tick、health
• 会话与路由
  • WebChat 使用与其它渠道一致的会话与路由规则；回复总是回到 WebChat
  • 默认主会话（main 或 global），支持切换
• 认证与远程模式
  • 本地模式直连本地网关 WebSocket
  • 远程模式通过 SSH/Tailscale 隧道转发网关 WebSocket 控制端口
• 媒体与自动回复
  • 自动回复心跳、媒体加载与优化、Web 入站/出站消息处理

架构总览

WebChat 的整体交互流程如下：客户端通过 WebSocket 连接到网关，使用 chat.* 方法进行历史拉取、消息发送与注入，同时订阅聊天事件以实现状态同步与实时更新。

sequenceDiagram participant Client as "客户端(WebChat)" participant WS as "网关 WebSocket" participant Chat as "聊天通道" participant Auth as "认证模块" Client->>WS : 建立连接(携带 Origin/Token) WS->>Auth : 校验认证(令牌/密码/反向代理) Auth-->>WS : 认证结果 WS-->>Client : hello-ok Client->>WS : chat.history(会话ID) WS->>Chat : 查询历史 Chat-->>WS : 历史消息(可能截断/省略) WS-->>Client : 历史消息 Client->>WS : chat.send(消息, 媒体, 投票) WS->>Chat : 发送消息 Chat-->>WS : 确认 WS-->>Client : ack WS-->>Client : 事件(chat/agent/presence/tick/health) Client->>Client : 更新界面/状态

组件详解

WebSocket 连接与认证

• 客户端连接时需设置 Origin 头，用于跨域与来源校验
• 支持多种认证模式：令牌、密码、可信代理反向代理认证
• 连接成功后收到 hello-ok，随后进入消息收发与事件订阅阶段

历史消息与状态同步

• chat.history 从网关获取，受稳定性约束：长文本字段可能被截断、重元数据可能省略、超大条目替换为占位提示
• chat.inject 可直接注入助手备注并广播至 UI（不触发代理执行）
• 中止运行时，若存在缓冲输出，网关会持久化到历史并标记中止元数据；网关不可达时 UI 为只读

消息发送与媒体处理

• 支持文本、媒体（图片等）、投票等消息类型
• 媒体优化与加载由专用模块负责，确保传输效率与兼容性
• 出站消息通过 sendMessageWhatsApp 调用，入站消息解析与占位符提取由 inbound 模块处理

会话与路由

• WebChat 使用与其它渠道一致的会话与路由规则，回复总是回到 WebChat
• 默认主会话（main 或 global），支持在 UI 中切换
• 首次引导使用专用会话，避免与常规会话混淆

登录与会话生命周期

• loginWeb 负责创建与等待 WhatsApp Web 连接，处理常见错误码（如 515 重启、登出）
• 会话登录后保存凭据，后续发送无需重复扫码
• 会话关闭前等待 Baileys 事件刷新，确保最终事件落盘

控制面板与工具面板

• 控制面板的 Agents 工具面板通过 tools.catalog 获取运行时目录，标注 core 与 plugin:，并区分可选工具
• 若 catalog 不可用，回退内置静态列表
• 配置编辑影响展示与覆盖，但实际访问仍遵循策略优先级（allow/deny）

主题与响应式设计

• UI 渲染层提供导航折叠、品牌区、状态指示等基础布局
• 通过类名组合实现不同状态下的样式切换（如聊天焦点、导航折叠、引导态）

平台集成（macOS）

• macOS 应用将 WebChat 视图为原生 SwiftUI 视图内嵌
• 本地模式直连本地网关；远程模式通过 SSH 隧道转发控制端口
• 日志子系统与分类便于调试

依赖关系分析

WebChat 的核心依赖围绕"网关 WebSocket + 会话/路由 + 认证 + 媒体处理"展开，模块间职责清晰、耦合度低，便于测试与扩展。

graph LR Login["loginWeb
登录与会话管理"] --> Session["createWaSocket/waitForWaConnection
会话建立/等待"] Session --> Outbound["sendMessageWhatsApp
出站消息"] Session --> Inbound["monitorWebInbox/extract*
入站消息解析"] Session --> Media["loadWebMedia/optimizeImageToJpeg
媒体处理"] Login --> Auth["认证配置(gateway.auth.*)"] UI["WebChat UI"] --> WS["chat.history/chat.send/chat.inject
事件(chat/agent/presence/tick/health)"] WS --> Auth WS --> Session

性能与可扩展性

• 历史消息截断与元数据省略：chat.history 返回受限，避免内存与带宽压力
• 媒体优化：图片 JPEG 优化与大小限制，降低传输成本
• 事件驱动：chat/agent/presence/tick/health 事件按需推送，减少轮询开销
• 远程隧道：SSH/Tailscale 隧道仅转发控制端口，降低网络复杂度
• 可扩展点：工具目录 catalog 动态获取，支持插件生态扩展

安全与合规

• 认证模式：支持令牌、密码、可信代理反向代理认证，满足不同部署场景
• 远程模式：仅转发 WebSocket 控制端口，最小暴露面
• Origin 校验：客户端连接时携带 Origin，防止跨域滥用
• 会话隔离：默认主会话与首开引导会话分离，降低误操作风险
• 平台侧：macOS 应用日志子系统与分类，便于审计与问题定位

故障排查

• 连接失败
  • 检查网关认证配置（令牌/密码/可信代理）
  • 确认 Origin 设置正确
  • 查看 hello-ok 是否返回
• 历史为空或被截断
  • 确认 chat.history 请求参数与会话 ID
  • 接受截断与省略策略，必要时调整消息长度
• 媒体发送异常
  • 确认媒体尺寸与格式符合优化策略
  • 检查 loadWebMedia 与 optimizeImageToJpeg 流程
• 登录问题
  • 错误码 515：会话重启后重试
  • 登出：清理缓存后重新扫码登录
• 远程模式不可达
  • 检查 SSH/Tailscale 隧道是否建立
  • 确认网关端口与绑定地址

结论

WebChat 通过网关 WebSocket 提供统一的聊天体验，具备稳定的会话与路由、灵活的认证与远程模式、完善的事件驱动与媒体处理能力。其模块化设计便于扩展与维护，适合在多平台（macOS/iOS 原生视图、控制面板标签页）中复用同一套 UI 与协议。

附录：使用与定制指南

快速开始

• 启动网关
• 打开 WebChat UI（macOS/iOS 应用或控制面板聊天标签）
• 确保网关认证已配置（即使本地回环也需认证）

配置参考（WebChat）

• 无专用 webchat.* 配置块；WebChat 使用网关端点与认证设置
• 关键项：gateway.port、gateway.bind、gateway.auth.、gateway.remote.

自定义开发建议

• UI 层
  • 利用事件驱动更新界面，避免轮询
  • 导航折叠与品牌区可复用现有类名体系
• 协议层
  • 严格遵循 chat.history/chat.send/chat.inject 语义
  • 对 chat.inject 的使用保持谨慎，避免与代理执行混淆
• 认证层
  • 根据部署环境选择合适认证模式
  • Origin 校验与令牌/密码配置需一致
• 媒体层
  • 使用优化后的 JPEG 与大小限制，提升传输效率
• 平台集成
  • macOS 应用可参考 SwiftUI 内嵌视图与日志子系统

源码阅读地址

• ui/src/ui/app-render.ts
• docs/platforms/mac/webchat.md
• src/channel-web.ts