Extension 加载

Extension 是 OpenClaw 的可插拔模块，包括通道扩展（如 Microsoft Teams、Matrix）和功能扩展（如 LanceDB、OpenTelemetry）。本章介绍它们如何在运行时被发现、加载和注册。

加载流程

Source: src/plugins/loader.ts

步骤详解

1. 扫描 — 遍历 extensions/ 目录下所有子目录
2. 解析 manifest — 读取每个扩展的 package.json 或专用 manifest 文件
3. Schema 验证 — 确保 manifest 包含必需字段（id, name, version, entry）
4. 动态导入 — 使用 import() 加载插件的入口模块
5. 初始化 — 调用插件导出的 init 函数，传入 OpenClawPluginApi
6. 注册 — 插件通过 API 注册工具、通道、Hooks 等

Manifest 解析

每个 extension 必须有一个 manifest，声明插件的元数据和入口：

// Plugin manifest (simplified)
interface PluginManifest {
  id: string;              // Unique identifier
  name: string;            // Display name
  version: string;         // Semver version
  entry: string;           // Entry module path
  kind: "extension";       // Plugin kind
  dependencies?: string[]; // Required dependencies
}

动态导入

Source: src/plugins/loader.ts

插件使用 jiti 别名解析器进行动态导入，支持 TypeScript 源文件直接加载：

// Dynamic import with jiti resolver (simplified)
// Supports loading:
// - Compiled JS from dist/
// - TypeScript source directly
// - ESM and CJS modules

TIP

jiti 是一个运行时 TypeScript/ESM 转换工具，让 OpenClaw 可以直接加载 TypeScript 插件源码，无需预编译。

Extension 目录结构

典型的 extension 结构：

extensions/msteams/
├── package.json           # Manifest + dependencies
├── src/
│   ├── index.ts          # Entry point (exports init function)
│   ├── plugin.ts         # ChannelPlugin implementation
│   ├── send.ts           # Message sending
│   ├── receive.ts        # Message receiving
│   └── auth.ts           # Authentication
└── tsconfig.json

插件注册到 Registry

Source: src/plugins/registry.ts

加载完成后，插件被记录为 PluginRecord：

interface PluginRecord {
  id: string;
  name: string;
  version: string;
  kind: "extension" | "skill" | "core";
  origin: string;          // Source path
  manifest: PluginManifest;
}

Registry 按类型管理所有注册：

错误处理

加载过程中的错误处理策略：

错误类型	处理方式
Manifest 缺失	跳过，记录警告
Schema 验证失败	跳过，记录详细错误
模块导入失败	跳过，记录错误和堆栈
Init 函数抛出	标记为失败，不注册

单个插件的加载失败不会影响其他插件或 Gateway 启动。

小结

• Extension 通过 manifest + 动态导入 模式加载
• 使用 jiti 支持直接加载 TypeScript 源码
• 加载流程：扫描 → 解析 → 验证 → 导入 → 初始化 → 注册
• 错误隔离 — 单个插件失败不影响其他插件和系统启动
• 所有注册通过 PluginRecord 记录在 Registry 中

下一章：Hooks 机制