万字解析 OpenClaw 源码架构-插件开发示例

毛骗导演
4 阅读19分钟

OpenClaw 的插件体系由“插件清单 + 运行时注册 + 严格配置校验”构成。官方文档对插件发现顺序、加载路径、安全策略与缓存机制有明确规范；通道插件通过 api.registerChannel 注册消息适配器；工具插件通过 api.registerTool 注册可被代理调用的工具；集成插件则结合 HTTP 路由、生命周期钩子与服务管理实现深度集成。

graph TB
subgraph "插件目录"
VC["extensions/voice-call"]
DC["extensions/discord"]
TG["extensions/telegram"]
LB["extensions/lobster"]
LLM["extensions/llm-task"]
MC["extensions/memory-core"]
ML["extensions/memory-lancedb"]
end
subgraph "插件清单"
VC_JSON["openclaw.plugin.json"]
DC_JSON["openclaw.plugin.json"]
TG_JSON["openclaw.plugin.json"]
end
VC --> VC_JSON
DC --> DC_JSON
TG --> TG_JSON
subgraph "运行时"
API["OpenClawPluginApi"]
REG["registerChannel/registerTool/registerGatewayMethod"]
end
VC --> API
DC --> API
TG --> API
LB --> API
LLM --> API
MC --> API
ML --> API
API --> REG

核心组件

  • 插件清单与 JSON Schema：所有插件必须提供 openclaw.plugin.json，并内置 configSchema 用于严格配置校验，避免执行插件代码即可完成验证。
  • 插件注册接口：通过 OpenClawPluginApi 提供的 registerChannel、registerTool、registerGatewayMethod、registerCli、registerService、registerHook 等能力，将功能注入到网关与代理运行时。
  • 通道插件：负责消息出站/入站适配，统一对外暴露为“频道”，支持多账号、能力声明、安全策略与状态诊断。
  • 工具插件：封装系统命令或外部 API，以类型化的参数与返回值形式供代理调用，支持沙箱与可选注册。
  • 集成插件：结合 HTTP 路由、生命周期钩子与服务管理，实现第三方服务的深度集成与自动化。

架构总览

下图展示了插件在 OpenClaw 网关中的位置与交互方式：客户端通过 WebSocket 连接网关，网关根据插件注册的方法与工具进行消息路由与执行；通道插件负责具体消息渠道的收发；工具插件提供可被代理调用的能力；集成插件通过 HTTP 路由与钩子扩展系统行为。

sequenceDiagram
participant Client as "客户端(WS)"
participant Gateway as "网关"
participant Plugin as "插件(通道/工具/集成)"
participant Ext as "外部服务"
Client->>Gateway : "连接/请求"
Gateway->>Plugin : "调用已注册方法/工具"
Plugin->>Ext : "HTTP/SDK/系统命令"
Ext-->>Plugin : "响应/事件"
Plugin-->>Gateway : "结果/事件"
Gateway-->>Client : "响应/事件推送"

详细组件分析

消息适配器插件示例：Telegram 与 Discord

这两个插件属于“通道插件”，通过 api.registerChannel 将外部消息平台接入 OpenClaw 的统一消息面。它们的共同特征是：

  • 在 openclaw.plugin.json 中声明 channels 字段，标识该插件注册了哪些频道。
  • 在 index.ts 中导入通道实现与运行时设置函数，完成注册与钩子绑定。
  • 通道插件通常包含配置解析、账户解析、能力声明、出站发送等适配器。
classDiagram
class TelegramPlugin {
+id : string
+name : string
+description : string
+configSchema : object
+register(api)
}
class DiscordPlugin {
+id : string
+name : string
+description : string
+configSchema : object
+register(api)
}
class ChannelPlugin {
+id : string
+meta : object
+capabilities : object
+config : object
+outbound : object
+registerChannel()
}
TelegramPlugin --> ChannelPlugin : "注册"
DiscordPlugin --> ChannelPlugin : "注册"

工具插件示例：Lobster 与 LLM Task

工具插件通过 api.registerTool 将可被代理调用的工具注册到运行时，支持沙箱环境下的可选注册与类型化参数校验。示例包括：

  • Lobster：提供可恢复审批的类型化工作流工具，支持沙箱条件下的选择性注册。
  • LLM Task：提供结构化任务的 JSON-only 工具，支持默认模型、鉴权配置与超时控制。
flowchart TD
Start(["工具调用入口"]) --> CheckSandbox["检查沙箱环境"]
CheckSandbox --> |允许| CreateTool["创建工具实例"]
CheckSandbox --> |不允许| Deny["返回空(禁用)"]
CreateTool --> Register["api.registerTool(...)"]
Register --> End(["可用"])
Deny --> End

集成插件示例：Voice Call（消息适配器+工具+服务）

Voice Call 插件是“通道插件 + 工具插件 + 服务”的综合示例，展示了如何：

  • 通过 openclaw.plugin.json 定义复杂的配置 Schema（含提供商、TTS/STT、隧道、流式通话等）。
  • 在 index.ts 中注册多个网关方法（如 voicecall.initiate、voicecall.continue、voicecall.speak、voicecall.end、voicecall.status、voicecall.start），并通过工具接口提供统一的工具调用入口。
  • 通过 api.registerService 管理生命周期（启动/停止），并在失败时记录日志。
  • 通过 ensureRuntime 延迟初始化与错误重试控制，避免资源泄漏。
sequenceDiagram
participant Client as "客户端"
participant Gateway as "网关"
participant VC as "Voice Call 插件"
participant RT as "运行时/管理器"
participant Provider as "提供商(Twilio/Telnyx)"
Client->>Gateway : "voicecall.initiate"
Gateway->>VC : "调用注册方法"
VC->>RT : "ensureRuntime()"
RT-->>VC : "返回运行时"
VC->>Provider : "发起呼叫"
Provider-->>VC : "返回结果"
VC-->>Gateway : "响应{callId}"
Gateway-->>Client : "确认"

集成插件示例：Memory Core 与 Memory (LanceDB)

这两个插件属于“内存/记忆”类插件，分别代表两类集成模式：

  • Memory Core：基于文件系统的轻量级搜索与 CLI 工具，通过 api.registerTool 注册 memory_search 与 memory_get，并提供 CLI 子命令。
  • Memory (LanceDB)：基于向量数据库的长期记忆，包含自动召回与自动捕获的生命周期钩子、CLI 命令、HTTP 路由与服务管理，同时具备提示注入防护与去重策略。
flowchart TD
A["before_agent_start"] --> B["embed(prompt)"]
B --> C["db.search(vector, limit)"]
C --> D{"命中?"}
D --> |是| E["prependContext 注入"]
D --> |否| F["跳过"]
subgraph "agent_end"
G["提取用户消息文本"] --> H["shouldCapture 过滤"]
H --> I{"可捕获?"}
I --> |是| J["embed -> store"]
I --> |否| K["跳过"]
end

依赖关系分析

  • 插件发现与加载：官方文档规定了从“配置路径 → 工作区扩展 → 全局扩展 → 内置扩展”的优先级顺序，且对路径安全性与缓存策略有明确要求。
  • 清单与 Schema：每个插件必须提供 openclaw.plugin.json 与 configSchema，缺失或无效将导致验证失败。
  • 运行时接口：插件通过 OpenClawPluginApi 的子路径导入（如 plugin-sdk/telegram、plugin-sdk/discord 等）获得特定平台的适配器与工具。
graph LR
P["插件清单(openclaw.plugin.json)"] --> V["配置校验(JSON Schema)"]
V --> R["运行时注册(register*)"]
R --> G["网关/代理"]

性能考量

  • 缓存与延迟初始化：Voice Call 插件通过 ensureRuntime 与运行时 Promise 缓存避免重复初始化；Memory (LanceDB) 插件采用惰性初始化与向量维度预计算降低冷启动成本。
  • 资源释放：Voice Call 插件在服务停止时重置运行时引用，防止端口孤儿与内存泄漏。
  • I/O 与网络：通道插件与集成插件应限制并发、设置超时与重试策略，避免阻塞网关主循环。
  • 日志与可观测性：通过 api.logger 输出关键事件与错误，便于定位性能瓶颈。

工具插件

OpenClaw 的插件体系由“插件 SDK + 多个具体插件”构成。插件以模块形式组织在 extensions 目录下，每个插件通常包含：

  • 插件入口文件（index.ts）：定义插件注册逻辑、工具、命令、服务与生命周期钩子
  • 配置文件（openclaw.plugin.json）：声明插件 ID、类型、UI 提示与配置模式
  • 可选的内部模块（如通知、配置解析等）
graph TB
subgraph "插件SDK"
SDK["src/plugin-sdk/index.ts<br/>导出插件API与类型"]
TYPES["src/plugins/types.ts<br/>插件类型与钩子定义"]
end
subgraph "内存工具插件"
MEM_CORE["extensions/memory-core/index.ts"]
MEM_LANCE["extensions/memory-lancedb/index.ts"]
CFG["extensions/memory-lancedb/config.ts"]
MEM_JSON["extensions/memory-lancedb/openclaw.plugin.json"]
end
subgraph "系统工具插件"
DEV_PAIR["extensions/device-pair/index.ts"]
DEV_NOTIFY["extensions/device-pair/notify.ts"]
PHONE_CTRL["extensions/phone-control/index.ts"]
VOICE_CALL["extensions/voice-call/index.ts"]
DEV_JSON["extensions/device-pair/openclaw.plugin.json"]
PHONE_JSON["extensions/phone-control/openclaw.plugin.json"]
VOICE_JSON["extensions/voice-call/openclaw.plugin.json"]
end
SDK --> MEM_CORE
SDK --> MEM_LANCE
SDK --> DEV_PAIR
SDK --> PHONE_CTRL
SDK --> VOICE_CALL
CFG --> MEM_LANCE
MEM_JSON --> MEM_LANCE
DEV_JSON --> DEV_PAIR
PHONE_JSON --> PHONE_CTRL
VOICE_JSON --> VOICE_CALL

核心组件

本节概述 OpenClaw 插件系统的关键能力与约定，为后续各插件实现提供统一参考。

  • 插件 API（OpenClawPluginApi）

    • 注册工具：registerTool
    • 注册命令：registerCommand
    • 注册网关方法：registerGatewayMethod
    • 注册 CLI：registerCli
    • 注册服务：registerService
    • 生命周期钩子：on（支持 before_agent_start、agent_end、before_tool_call、after_tool_call 等）
    • 路径解析：resolvePath
    • 日志：logger
    • 运行时访问：runtime（用于访问工具工厂、配置、状态目录等）

  • 插件类型与钩子

    • OpenClawPluginConfigSchema：支持 parse/safeParse/validate/uiHints/jsonSchema
    • PluginHookName：定义可用的生命周期钩子名称集合
    • PluginHookHandlerMap：按钩子名映射处理器签名

  • 插件命令上下文（PluginCommandContext）

    • 包含发送者标识、通道、授权状态、账户 ID、线程 ID 等
    • 返回值为 ReplyPayload，统一消息格式

  • 插件服务（OpenClawPluginService）

    • 支持 start/stop 生命周期，常用于定时任务或后台守护

架构总览

OpenClaw 插件通过统一的 API 将“工具、命令、网关方法、CLI、服务与生命周期钩子”整合到运行时环境。下图展示了典型调用链路：

sequenceDiagram
participant User as "用户/渠道"
participant Cmd as "插件命令"
participant API as "OpenClawPluginApi"
participant Tools as "工具注册器"
participant Runtime as "运行时"
participant DB as "数据库/LanceDB"
User->>Cmd : 触发命令
Cmd->>API : 解析参数/鉴权
API->>Runtime : 访问工具工厂/配置
API->>Tools : registerTool(...)
Tools->>Runtime : 创建工具实例
Tools->>DB : 读写/查询
DB-->>Tools : 结果
Tools-->>API : 工具执行结果
API-->>Cmd : ReplyPayload
Cmd-->>User : 回复

详细组件分析

内存工具插件（LanceDB）

该插件提供长短期记忆的向量检索与自动捕获/召回能力，核心特性：

  • 向量嵌入：使用 OpenAI Embeddings 生成文本向量
  • 存储：基于 LanceDB 的向量表，支持相似度搜索与去重
  • 自动捕获：在会话结束时自动提取并存储重要信息
  • 自动召回：在对话前注入相关记忆上下文
  • CLI 命令：ltm list/search/stats
  • 工具：memory_recall/memory_store/memory_forget
classDiagram
class MemoryDB {
-db
-table
-initPromise
+store(entry)
+search(vector, limit, minScore)
+delete(id)
+count()
}
class Embeddings {
-client
+embed(text)
}
class MemoryPlugin {
+register(api)
+shouldCapture(text, options)
+detectCategory(text)
+formatRelevantMemoriesContext(memories)
}
MemoryPlugin --> MemoryDB : "使用"
MemoryPlugin --> Embeddings : "使用"

sequenceDiagram
participant Agent as "代理"
participant API as "OpenClawPluginApi"
participant Embed as "Embeddings"
participant DB as "MemoryDB"
participant Tools as "工具"
Agent->>API : before_agent_start
API->>Embed : embed(prompt)
Embed-->>API : 向量
API->>DB : search(vector, limit, minScore)
DB-->>API : 搜索结果
API-->>Agent : prependContext(记忆上下文)
Agent->>API : agent_end
API->>Tools : 提取用户消息
API->>Embed : embed(候选文本)
API->>DB : search(vector, 1, 0.95)
DB-->>API : 是否重复
API->>DB : store(新记忆)
DB-->>API : 成功

  • 参数验证与配置

    • 使用 memoryConfigSchema 对插件配置进行解析与校验
    • 支持环境变量占位符替换（如 ${OPENAI_API_KEY}）
    • 默认数据库路径与模型维度映射

  • 工具注册与执行

    • registerTool 注册 memory_recall/memory_store/memory_forget
    • 执行时进行参数校验、向量化、去重检查与结果序列化

  • CLI 与服务

    • registerCli 注册 ltm 子命令
    • registerService 启停日志输出

设备配对工具插件

该插件用于生成配对码、批准设备请求，并支持 Telegram 通知订阅与一次性提醒。

  • 关键流程
    • 生成配对码：编码网关 URL、认证方式与令牌
    • 批准请求：approveDevicePairing 并返回批准结果
    • 通知：Telegram 订阅与轮询推送新请求
    • URL 解析：优先 publicUrl，其次 Tailscale Serve/Funnel，再回退到本地绑定
sequenceDiagram
participant User as "用户"
participant Cmd as "命令处理器"
participant Pair as "设备配对"
participant Notify as "通知服务"
participant Gate as "网关URL解析"
User->>Cmd : /pair
Cmd->>Gate : 解析网关URL
Gate-->>Cmd : URL/错误
Cmd->>Pair : 生成配对码
Pair-->>Cmd : 配对码/说明
Cmd-->>User : 发送配对码/二维码
Notify->>Pair : 轮询待批准列表
Notify-->>User : 推送新请求提醒

  • 参数与鉴权解析

    • 支持 token/password 两种模式，优先从环境变量与配置中解析
    • URL 正规化与端口选择策略

  • 命令与通知

    • /pair status/pending/approve/qr/notify
    • 一次性订阅与持久订阅模式

电话控制工具插件

该插件用于临时允许高风险节点命令（相机、屏幕录制、写操作），并支持自动过期与状态持久化。

  • 核心能力
    • 状态文件：armed.json，记录允许/拒绝命令集与过期时间
    • 允许/拒绝列表更新：动态修改配置并写回
    • 定时服务：定期检查过期并自动解除武装
    • 命令：/phone status/arm/disarm/help
flowchart TD
Start(["进入 /phone 命令"]) --> Parse["解析动作与参数"]
Parse --> Action{"动作类型"}
Action --> |status| ReadState["读取状态文件"]
ReadState --> ReplyStatus["回复当前状态"]
Action --> |arm| UpdateAllow["计算允许/拒绝命令集"]
UpdateAllow --> WriteState["写入状态文件"]
WriteState --> WriteCfg["写回配置"]
WriteCfg --> ReplyArm["回复已临时允许的命令"]
Action --> |disarm| Disarm["恢复允许/拒绝列表"]
Disarm --> ClearState["清空状态文件"]
ClearState --> ReplyDisarm["回复已解除武装"]
Action --> |help| ReplyHelp["回复帮助信息"]

  • 状态持久化与版本兼容

    • 支持 v1/v2 状态文件格式，自动迁移字段
    • 文件原子写入，异常时保留原状

  • 自动过期

    • 定时服务每 15 秒检查一次，过期后自动解除武装

语音通话工具插件

该插件提供电话呼入呼出能力，支持 Telnyx/Twilio/Plivo 等提供商，并可选实时流式 TTS/STT。

  • 网关方法

    • voicecall.initiate/continue/speak/end/status/start
    • 统一响应格式：success/error + 附加数据

  • 工具与 CLI

    • registerTool 提供 voice_call 工具
    • registerCli 提供 voicecall 子命令

  • 配置与校验

    • 支持多种提供商配置与敏感字段 UI 提示
    • 提供解析与校验函数，确保必要字段存在
sequenceDiagram
participant User as "用户"
participant Tool as "voice_call 工具"
participant API as "OpenClawPluginApi"
participant RT as "VoiceCallRuntime"
participant Provider as "提供商(如 Twilio)"
User->>Tool : 调用 action
Tool->>API : ensureRuntime()
API->>RT : 创建/获取运行时
Tool->>RT : manager.initiateCall/continue/speak/end
RT->>Provider : 发起/继续/播放/结束通话
Provider-->>RT : 结果
RT-->>Tool : 结果
Tool-->>User : JSON 响应

内存核心工具插件

该插件通过运行时工具工厂创建内存搜索与获取工具，并注册 CLI。

  • 工具工厂

    • createMemorySearchTool / createMemoryGetTool
    • 若工厂不可用则返回空

  • CLI

    • registerMemoryCli 注册 memory 子命令

依赖关系分析

  • 插件 SDK 与类型

    • 所有插件均依赖 OpenClawPluginApi 与插件类型定义
    • 生命周期钩子与工具签名在 types.ts 中集中定义

  • 插件间耦合

    • 内存插件依赖 LanceDB 与 OpenAI
    • 设备配对插件依赖网关绑定与 Tailscale
    • 电话控制插件依赖配置文件系统与定时服务
    • 语音通话插件依赖提供商 SDK 与实时流式能力
graph LR
SDK["插件SDK(types.ts)"] --> MEM["内存插件(LanceDB)"]
SDK --> DEV["设备配对"]
SDK --> PHONE["电话控制"]
SDK --> CALL["语音通话"]
MEM --> LANCEDB["@lancedb/lancedb"]
MEM --> OPENAI["OpenAI Embeddings"]
DEV --> BIND["网关绑定/Tailscale"]
PHONE --> CFG["配置文件系统"]
CALL --> PROVIDER["提供商SDK/实时流"]

性能考虑

  • 向量搜索与相似度转换

    • LanceDB 默认使用 L2 距离，插件将其映射到 0-1 相似度范围，避免额外开销
    • 限制返回数量与最小分数阈值，减少序列化与传输成本

  • 异步初始化与懒加载

    • MemoryDB 与 Embeddings 采用延迟初始化，首次使用时才加载模块与连接数据库
    • 语音通话插件运行时采用 Promise 缓存，失败后重置以便下次重试

  • 状态持久化与原子写入

    • phone-control 使用原子写入与目录创建，避免部分写入导致的状态损坏
    • 内存插件对向量数组进行剥离，防止无法克隆的数据结构造成序列化问题

  • 定时任务与资源释放

    • 设备配对通知服务与电话控制定时器在 stop 时清理，避免资源泄漏

认证插件

认证插件位于 extensions 目录下，每个插件由“入口文件 + 认证流程实现 + 插件清单 + 可选测试”组成；同时，命令层负责调用插件、写入凭据与配置补丁。

graph TB
subgraph "插件层"
GG["google-gemini-cli-auth<br/>入口与OAuth实现"]
MM["minimax-portal-auth<br/>入口与OAuth实现"]
QW["qwen-portal-auth<br/>入口与OAuth实现"]
end
subgraph "SDK与命令层"
SDK_MM["plugin-sdk/minimax-portal-auth.ts"]
SDK_QW["plugin-sdk/qwen-portal-auth.ts"]
CMD_AUTH["commands/models/auth.ts"]
APPLY["commands/auth-choice.apply.plugin-provider.ts"]
end
subgraph "文档与配置"
DOC_OAUTH["docs/concepts/oauth.md"]
DOC_AUTH["docs/gateway/authentication.md"]
DOC_MM["docs/providers/minimax.md"]
DOC_QW["docs/providers/qwen.md"]
end
GG --> CMD_AUTH
MM --> CMD_AUTH
QW --> CMD_AUTH
CMD_AUTH --> APPLY
SDK_MM --> MM
SDK_QW --> QW
CMD_AUTH --> DOC_OAUTH
CMD_AUTH --> DOC_AUTH
DOC_MM --> MM
DOC_QW --> QW

核心组件

  • 插件入口：注册 Provider、声明认证方法（kind）、运行时上下文（openUrl、prompter、note、progress）。
  • OAuth 实现：封装 PKCE、授权端点、令牌交换、用户信息与项目发现、轮询等待与错误处理。
  • 配置补丁：动态注入默认模型、基础 URL、API 类型、成本与上下文窗口等。
  • 命令集成：通过 CLI 触发插件认证，写入 auth-profiles.json 并合并 models.json。

架构总览

认证插件遵循“插件定义 → 命令触发 → SDK 调用 → OAuth 执行 → 凭据落盘”的闭环。

sequenceDiagram
participant U as "用户"
participant CLI as "命令行(models/auth)"
participant API as "插件API(ProviderAuthContext)"
participant SDK as "插件SDK(minimax/qwen)"
participant AUTH as "OAuth实现(google-gemini-cli/minimax/qwen)"
participant STORE as "凭据存储(auth-profiles.json)"
U->>CLI : 运行认证命令
CLI->>API : 解析Provider与Method
API->>SDK : 调用认证方法(run)
SDK->>AUTH : 执行OAuth流程(PKCE/轮询/回调)
AUTH-->>SDK : 返回访问令牌/刷新令牌/过期时间/项目ID
SDK-->>API : 构建ProviderAuthResult(含configPatch)
API->>STORE : 写入凭据与配置补丁
STORE-->>CLI : 完成并提示

详细组件分析

Google Gemini CLI 认证插件

  • 功能要点
    • 支持 PKCE + 本地回调（localhost:8085），自动或手动模式切换。
    • 从环境变量或已安装的 Gemini CLI 提取 OAuth 客户端凭据。
    • 令牌交换后获取邮箱与项目 ID，必要时通过多端点探测与引导完成项目发现。
    • 将结果包装为 ProviderAuthResult，包含默认模型、访问/刷新令牌、过期时间与额外字段。
  • 关键流程（远程/WSL2 同步场景）
    • 自动打开浏览器并在本地监听回调；若端口占用则回退到手动粘贴回调 URL。
    • 多端点探测 loadCodeAssist，兼容 VPC-SC 场景，必要时引导设置 GOOGLE_CLOUD_PROJECT。
  • 错误处理
    • 状态不匹配、超时、端口占用、缺少刷新令牌、项目发现失败等均抛出明确错误并提示。
sequenceDiagram
participant P as "插件入口(index.ts)"
participant C as "ProviderAuthContext"
participant O as "OAuth(loginGeminiCliOAuth)"
participant G as "Google OAuth端点"
participant U as "用户浏览器"
P->>C : 注册Provider与OAuth方法
C->>O : 调用run()
O->>U : 打开授权URL(PKCE)
alt 本地回调可用
U-->>O : 回调至localhost : 8085
else 端口不可用/远程
O->>C : 提示手动粘贴回调URL
C-->>O : 用户粘贴回调
end
O->>G : 交换授权码为令牌
G-->>O : 返回access/refresh/expires
O->>G : 获取用户邮箱与项目ID
O-->>P : 返回ProviderAuthResult

MiniMax 门户认证插件

  • 功能要点
    • 设备码登录（device_code），支持 CN 与 Global 区域端点。
    • 轮询令牌状态，动态调整轮询间隔，超时/错误时给出明确提示。
    • 返回 access/refresh/expires 与可选资源 URL，构建 ProviderAuthResult 并合并 models.json。
  • 关键流程
    • 申请设备码与用户码，打开验证页，轮询换取令牌，成功后返回并写入配置补丁。
sequenceDiagram
participant P as "插件入口(index.ts)"
participant C as "ProviderAuthContext"
participant O as "OAuth(loginMiniMaxPortalOAuth)"
participant M as "MiniMax OAuth端点"
participant U as "用户浏览器"
P->>C : 注册Provider与OAuth方法
C->>O : 调用run()
O->>M : 申请设备码(PKCE)
M-->>O : 返回user_code/verification_uri/过期时间
O->>U : 打开验证页并提示输入user_code
loop 轮询
O->>M : 以device_code换取令牌
alt pending/slow_down
O->>O : 延长轮询间隔
else success
M-->>O : 返回access/refresh/expires/resourceUrl
O-->>P : 返回ProviderAuthResult
else error
O-->>P : 抛出错误
end
end

Qwen 门户认证插件

  • 功能要点
    • 设备码登录（device_code），支持 PKCE。
    • 轮询等待授权，支持 slow_down 情况下的指数退避。
    • 返回 access/refresh/expires 与可选资源 URL，合并默认模型与别名。
  • 关键流程
    • 申请设备码，打开验证页，轮询换取令牌，成功后写入配置补丁。
sequenceDiagram
participant P as "插件入口(index.ts)"
participant C as "ProviderAuthContext"
participant O as "OAuth(loginQwenPortalOAuth)"
participant Q as "Qwen OAuth端点"
participant U as "用户浏览器"
P->>C : 注册Provider与OAuth方法
C->>O : 调用run()
O->>Q : 申请设备码(PKCE)
Q-->>O : 返回device_code/user_code/verification_uri/过期时间
O->>U : 打开验证页并提示输入user_code
loop 轮询
O->>Q : 以device_code换取令牌
alt authorization_pending
O->>O : 维持轮询
else slow_down
O->>O : 增大轮询间隔
else success
Q-->>O : 返回access/refresh/expires/resourceUrl
O-->>P : 返回ProviderAuthResult
else error
O-->>P : 抛出错误
end
end

插件 SDK 与命令集成

  • SDK 暴露
    • minimax-portal-auth：导出空配置模式、构建 OAuth 结果、PKCE 工具与表单编码工具。
    • qwen-portal-auth：导出空配置模式、构建 OAuth 结果、PKCE 工具与表单编码工具。
  • 命令层
    • 解析 Provider 与 Method，创建 VPS/远程适配的 OAuth 处理器，执行 run 并写入凭据。
    • 应用插件 Provider 的认证选择，启用插件、解析 Provider、选择方法并执行。

依赖关系分析

  • 插件对 SDK 的依赖：仅使用 SDK 暴露的最小接口（空配置、PKCE、表单编码、结果构建）。
  • 插件对命令层的依赖：通过 ProviderAuthContext 注入 openUrl、note、progress、prompt 等能力。
  • 文档与配置：凭据存储位置、多账户路由、刷新与过期策略、API Key 旋转行为等。
graph LR
IDX_GG["google-gemini-cli-auth/index.ts"] --> OAUTH_GG["google-gemini-cli-auth/oauth.ts"]
IDX_MM["minimax-portal-auth/index.ts"] --> OAUTH_MM["minimax-portal-auth/oauth.ts"]
IDX_QW["qwen-portal-auth/index.ts"] --> OAUTH_QW["qwen-portal-auth/oauth.ts"]
SDK_MM["plugin-sdk/minimax-portal-auth.ts"] --> IDX_MM
SDK_QW["plugin-sdk/qwen-portal-auth.ts"] --> IDX_QW
CMD["commands/models/auth.ts"] --> IDX_GG
CMD --> IDX_MM
CMD --> IDX_QW
DOC_OAUTH["docs/concepts/oauth.md"] --> CMD
DOC_AUTH["docs/gateway/authentication.md"] --> CMD

性能与可靠性

  • 轮询策略
    • MiniMax 与 Qwen 的轮询采用指数退避与最大上限控制，避免频繁请求。
  • 端点容错
    • Gemini CLI 的项目发现尝试多个端点，兼容不同环境与异常情况。
  • 超时与重试
    • 明确的超时阈值与错误提示，便于用户快速定位问题。
  • 存储与并发
    • 凭据写入采用原子更新与文件锁，避免并发冲突。

消息渠道插件

OpenClaw 将每个消息渠道封装为独立的扩展目录，遵循统一的组织规范：

  • 扩展根目录：extensions/{channel}
  • 插件清单：openclaw.plugin.json（定义插件标识、支持的通道类型、配置模式）
  • 入口文件：index.ts（负责注册插件、注入运行时、导出通道插件）
graph TB
subgraph "扩展目录"
D["extensions/discord"]
T["extensions/telegram"]
S["extensions/slack"]
W["extensions/whatsapp"]
end
D --> D_idx["index.ts"]
D --> D_cfg["openclaw.plugin.json"]
T --> T_idx["index.ts"]
T --> T_cfg["openclaw.plugin.json"]
S --> S_idx["index.ts"]
S --> S_cfg["openclaw.plugin.json"]
W --> W_idx["index.ts"]
W --> W_cfg["openclaw.plugin.json"]

核心组件

  • 插件清单（openclaw.plugin.json）：声明插件 id、支持的通道数组、配置模式（JSON Schema）。用于向系统注册该插件可处理的消息通道类型。
  • 插件入口（index.ts）：定义插件对象，包含 id、name、description、configSchema，以及 register 回调。register 中完成运行时注入与通道插件注册。
  • 通道插件（由各扩展的 src/channel.js 导出）：实现具体的消息收发逻辑，供插件入口通过 api.registerChannel 注册使用。
  • 运行时注入（runtime）：通过各扩展的 runtime 文件设置运行时环境，确保通道插件在正确的上下文中执行。

架构总览

下图展示了从插件入口到通道插件与运行时的整体交互关系：

graph LR
A["OpenClaw 核心"] --> B["插件入口 index.ts"]
B --> C["注册通道插件<br/>api.registerChannel"]
B --> D["注入运行时<br/>set*Runtime(api.runtime)"]
C --> E["通道插件<br/>src/channel.js"]
D --> E

详细组件分析

Discord 插件

  • 插件清单：声明 id 为 discord，支持通道类型为 ["discord"]，配置模式为空对象。
  • 插件入口：注册插件后，设置 Discord 运行时，注册 Discord 通道插件，并注册子代理钩子。
  • 通道插件：由扩展目录下的 src/channel.js 提供，作为 ChannelPlugin 注入到核心。
  • 运行时注入：setDiscordRuntime(api.runtime) 将运行时注入到通道插件中。
sequenceDiagram
participant Core as "OpenClaw 核心"
participant Plugin as "Discord 插件入口"
participant Runtime as "Discord 运行时"
participant Channel as "Discord 通道插件"
Core->>Plugin : 调用 register(api)
Plugin->>Runtime : setDiscordRuntime(api.runtime)
Plugin->>Core : api.registerChannel({ plugin : Channel })
Plugin->>Core : registerDiscordSubagentHooks(api)
Core-->>Channel : 在运行时上下文中执行

Telegram 插件

  • 插件清单：声明 id 为 telegram，支持通道类型为 ["telegram"]，配置模式为空对象。
  • 插件入口：注册插件后，设置 Telegram 运行时，注册 Telegram 通道插件。
  • 通道插件：由扩展目录下的 src/channel.js 提供，作为 ChannelPlugin 注入到核心。
sequenceDiagram
participant Core as "OpenClaw 核心"
participant Plugin as "Telegram 插件入口"
participant Runtime as "Telegram 运行时"
participant Channel as "Telegram 通道插件"
Core->>Plugin : 调用 register(api)
Plugin->>Runtime : setTelegramRuntime(api.runtime)
Plugin->>Core : api.registerChannel({ plugin : Channel })
Core-->>Channel : 在运行时上下文中执行

Slack 插件

  • 插件清单：声明 id 为 slack，支持通道类型为 ["slack"]，配置模式为空对象。
  • 插件入口：注册插件后，设置 Slack 运行时，注册 Slack 通道插件。
  • 通道插件：由扩展目录下的 src/channel.js 提供，作为 ChannelPlugin 注入到核心。
sequenceDiagram
participant Core as "OpenClaw 核心"
participant Plugin as "Slack 插件入口"
participant Runtime as "Slack 运行时"
participant Channel as "Slack 通道插件"
Core->>Plugin : 调用 register(api)
Plugin->>Runtime : setSlackRuntime(api.runtime)
Plugin->>Core : api.registerChannel({ plugin : Channel })
Core-->>Channel : 在运行时上下文中执行

WhatsApp 插件

  • 插件清单：声明 id 为 whatsapp，支持通道类型为 ["whatsapp"]，配置模式为空对象。
  • 插件入口：注册插件后，设置 WhatsApp 运行时，注册 WhatsApp 通道插件。
  • 通道插件：由扩展目录下的 src/channel.js 提供，作为 ChannelPlugin 注入到核心。
sequenceDiagram
participant Core as "OpenClaw 核心"
participant Plugin as "WhatsApp 插件入口"
participant Runtime as "WhatsApp 运行时"
participant Channel as "WhatsApp 通道插件"
Core->>Plugin : 调用 register(api)
Plugin->>Runtime : setWhatsAppRuntime(api.runtime)
Plugin->>Core : api.registerChannel({ plugin : Channel })
Core-->>Channel : 在运行时上下文中执行

依赖关系分析

  • 插件入口依赖 SDK 类型与空配置模式生成器，确保插件对象满足核心要求。
  • 插件入口通过 api.registerChannel 注册通道插件，形成“入口 → 通道插件”的直接依赖。
  • 插件入口通过 set*Runtime 注入运行时，形成“入口 → 运行时”的依赖链。
  • 插件清单 openclaw.plugin.json 决定插件的通道能力与配置约束，是系统识别与加载的关键。
graph TB
IDX["index.ts"] --> REG["api.registerChannel"]
IDX --> RUNTIME["set*Runtime"]
REG --> CH["通道插件"]
RUNTIME --> CH
CFG["openclaw.plugin.json"] --> IDX
CFG --> REG

性能考虑

  • 运行时注入：通过 set*Runtime 将运行时注入通道插件，避免重复初始化，提升启动与执行效率。
  • 空配置模式：使用 emptyPluginConfigSchema 可减少不必要的配置校验开销，适合无需复杂参数的轻量插件。
  • 通道注册：仅在 register 中进行一次 api.registerChannel，避免重复注册导致的资源浪费。
  • 错误隔离：在通道插件内部对网络请求与第三方 API 调用进行超时与重试控制，降低失败对整体系统的冲击。

专用插件

OpenClaw 插件体系采用“扩展包”组织方式，每个插件位于独立目录下，包含：

  • 扩展包根目录：如 voice-call、bluebubbles、acpx、diagnostics-otel、talk-voice 等
  • 插件清单：openclaw.plugin.json，定义插件标识、UI 提示、配置模式与能力声明
  • 入口与实现：index.ts（部分插件）或具体模块（如 voice-call 的多提供商适配）
  • 技能目录：如 acpx/skills，用于承载与插件绑定的技能资源
  • 文档与使用说明：各插件目录下的 README.md 或 SKILL.md
graph TB
subgraph "插件扩展包"
VC["语音通话插件<br/>extensions/voice-call"]
BB["BlueBubbles 插件<br/>extensions/bluebubbles"]
ACX["ACPX 插件<br/>extensions/acpx"]
DIO["诊断监控插件<br/>extensions/diagnostics-otel"]
TV["Talk 语音管理插件<br/>extensions/talk-voice"]
end
subgraph "配置与清单"
OPL1["voice-call/openclaw.plugin.json"]
OPL2["bluebubbles/openclaw.plugin.json"]
OPL3["acpx/openclaw.plugin.json"]
OPL4["diagnostics-otel/openclaw.plugin.json"]
OPL5["talk-voice/openclaw.plugin.json"]
end
VC --- OPL1
BB --- OPL2
ACX --- OPL3
DIO --- OPL4
TV --- OPL5

核心组件

  • 语音通话插件：支持 Twilio、Telnyx、Plivo 多提供商，具备外呼/通知模式、媒体流、实时 STT/TTS、签名验证与去重保护、超时与清理策略等。
  • BlueBubbles 插件：作为外部通道插件，负责健康检查、消息发送、反应/打字指示、附件下载、Webhook 路由与运行时桥接。
  • ACPX 插件：提供 ACP 运行时后端，支持命令路径、版本策略、权限模式、非交互权限策略、队列所有权 TTL、MCP 服务器注入等。
  • 诊断监控插件：基于 OTel 的诊断能力，提供可观测性与指标采集。
  • Talk 语音管理插件：提供 Talk 设备语音选择与管理能力。
  • 文本生成插件（技能）：通过技能目录与工具链实现文本生成任务，与插件生态协同工作。

架构总览

OpenClaw 插件通过统一的插件清单与运行时桥接，将第三方服务与本地能力整合到统一的消息与工具调用管道中。语音通话与 BlueBubbles 插件分别对接外部通道与提供商，ACPX 插件提供会话与权限控制，诊断插件提供可观测性，Talk 语音插件提供设备侧语音管理。

graph TB
GW["网关/运行时"]
VC["语音通话插件"]
BB["BlueBubbles 插件"]
ACX["ACPX 插件"]
DIO["诊断监控插件"]
TV["Talk 语音管理插件"]
GW --> VC
GW --> BB
GW --> ACX
GW --> DIO
GW --> TV
VC --> |"Webhook/媒体流"| VC_EXT["提供商: Twilio/Telnyx/Plivo/Mock"]
BB --> |"REST/Webhook"| BB_EXT["BlueBubbles 服务"]
ACX --> |"会话/权限/队列"| GW
DIO --> |"OTel 指标"| GW
TV --> |"设备语音"| GW

详细组件分析

语音通话插件（Voice Call）

  • 功能要点
    • 多提供商适配：Twilio、Telnyx、Plivo、Mock（本地开发）
    • 外呼模式：通知式（notify）与对话式（conversation）
    • 媒体流与实时 STT/TTS：支持 WebSocket 流、OpenAI Realtime API、提供商原生语音
    • 安全与稳定性：Webhook 签名验证、去重保护、静音/转写超时、挂断延迟、呼叫清理器
    • 配置覆盖：支持深合并覆盖核心 TTS 配置
  • 关键配置项（节选）
    • provider、fromNumber、toNumber、inboundPolicy、allowFrom、inboundGreeting
    • serve/port/path、tailscale、tunnel、webhookSecurity
    • outbound/defaultMode、notifyHangupDelaySec、maxDurationSeconds、staleCallReaperSeconds
    • streaming/enabled、sttProvider、openaiApiKey、sttModel、streamPath、预连接与并发限制
    • tts/provider、openai/elevenlabs 参数、edge（通话场景禁用）
    • store、responseModel、responseSystemPrompt、responseTimeoutMs
  • 使用与工具
    • CLI：openclaw voicecall call/continue/speak/end/status/tail/expose
    • 工具：voice_call.initiate_call/continue_call/speak_to_user/end_call/get_status
    • RPC：voicecall.initiate/continue/speak/end/status
sequenceDiagram
participant U as "用户"
participant CLI as "CLI/工具"
participant VC as "语音通话插件"
participant Prov as "提供商(如 Twilio)"
participant RT as "实时流/STT/TTS"
U->>CLI : 发起外呼/继续/播报
CLI->>VC : voice_call.initiate_call/continue_call/speak_to_user
VC->>Prov : 创建/控制通话(外呼/媒体流)
Prov-->>VC : Webhook(状态/事件)
VC->>RT : 启动/维护媒体流(可选)
RT-->>VC : 实时转写/合成音频
VC-->>CLI : 返回状态/结果
CLI-->>U : 展示/播报

BlueBubbles 集成插件（External Channel）

  • 功能要点
    • 外部通道插件：负责 BlueBubbles 服务的健康检查、消息发送、反应/打字指示、附件下载
    • Webhook 处理：注册插件 HTTP 路由，规范化发送方/聊天 ID，跳过自发消息，路由至核心回复管线
    • 运行时桥接：通过 api.runtime 与 openclaw/plugin-sdk 辅助函数集成
  • 内部助手（推荐使用）
    • probeBlueBubbles、sendMessageBlueBubbles、resolveChatGuidForTarget
    • sendBlueBubblesReaction、sendBlueBubblesTyping/markBlueBubblesChatRead
    • downloadBlueBubblesAttachment、buildBlueBubblesApiUrl/blueBubblesFetchWithTimeout
  • 配置（核心）
    • channels.bluebubbles.serverUrl、password、webhookPath
    • 行为限制：channels.bluebubbles.actions.reactions（默认开启）
flowchart TD
Start(["收到 BlueBubbles Webhook"]) --> Normalize["规范化发送方/聊天标识"]
Normalize --> SelfCheck{"是否来自自身?"}
SelfCheck --> |是| Drop["丢弃该消息"]
SelfCheck --> |否| Attachments{"是否有附件/贴图?"}
Attachments --> |是| Placeholder["文本为空时使用<mime:...>占位符"]
Attachments --> |否| Route["路由到核心回复管线"]
Placeholder --> Route
Route --> Done(["完成"])
Drop --> Done

ACPX 协议插件（ACPX Runtime）

  • 功能要点
    • ACP 运行时后端，支持命令路径、版本策略、工作目录、权限模式（approve-all/read-only/deny-all）
    • 非交互权限策略（deny/fail），严格 Windows cmd 包装器开关
    • 提示超时与队列拥有者 TTL，MCP 服务器注入（command/args/env）
  • 关键配置项（节选）
    • command、expectedVersion、cwd、permissionMode、nonInteractivePermissions
    • strictWindowsCmdWrapper、timeoutSeconds、queueOwnerTtlSeconds
    • mcpServers（命名 MCP 服务器定义）
classDiagram
class ACPXPlugin {
+命令路径
+期望版本
+工作目录
+权限模式
+非交互权限策略
+严格Windows包装器
+提示超时
+队列拥有者TTL
+MCP服务器列表
}
class MCP_Server {
+命令
+参数数组
+环境变量
}
ACPXPlugin --> MCP_Server : "注入"

诊断监控插件（Diagnostics OTel）

  • 功能要点
    • 基于 OpenTelemetry 的诊断能力，提供可观测性与指标采集
    • 插件清单最小化，便于在不同环境中启用/停用
  • 配置
    • 当前无额外配置项，保持开箱即用

Talk 语音管理插件（Talk Voice）

  • 功能要点
    • 管理 Talk 设备的语音选择与设置
    • 插件清单简洁，提供列出/设置能力
  • 配置
    • 当前无额外配置项

文本生成插件（以技能形式体现）

  • 功能要点
    • 通过技能目录与工具链实现文本生成任务
    • 与插件生态协同，提供可复用的生成能力
  • 说明
    • 本节为概念性说明，不直接分析具体源码文件

依赖关系分析

  • 语音通话插件对提供商的依赖：Twilio/Telnyx/Plivo/Mock；对实时流服务（如 OpenAI Realtime）的依赖
  • BlueBubbles 插件对 BlueBubbles 服务的 REST/Webhook 依赖
  • ACPX 插件对本地命令与 MCP 服务器的依赖
  • 诊断插件对 OTel 生态的依赖
  • Talk 语音插件对设备侧语音能力的依赖
graph LR
VC["语音通话插件"] --> TW["Twilio"]
VC --> TL["Telnyx"]
VC --> PV["Plivo"]
VC --> MK["Mock"]
VC --> OR["OpenAI Realtime"]
BB["BlueBubbles 插件"] --> BB_API["BlueBubbles 服务"]
ACX["ACPX 插件"] --> CMD["本地命令/脚本"]
ACX --> MCP["MCP 服务器"]
DIO["诊断监控插件"] --> OT["OTel 生态"]
TV["Talk 语音管理插件"] --> DEV["设备语音"]

性能考量

  • 语音通话
    • 媒体流并发与预连接上限需结合硬件与网络带宽设定，避免拥塞与抖动
    • 实时 STT/TTS 的超时与静音阈值应平衡响应速度与准确性
    • 呼叫清理器时间窗应高于最大通话时长，防止误杀正常通话
  • BlueBubbles
    • Webhook 路由与附件下载应异步化，避免阻塞主消息管线
    • 健康检查与重试策略需考虑服务可用性与速率限制
  • ACPX
    • 队列拥有者 TTL 应尽量短，减少轮询与延迟
    • 权限模式与非交互策略影响执行效率与安全性
  • 诊断与监控
    • 指标采样频率与上报间隔需权衡精度与资源占用
  • Talk 语音
    • 设备语音切换应避免阻塞主线程，必要时采用后台线程
avatar
文章
阅读
粉丝