OpenClaw 扩展构建指南

构建扩展

本指南将带你从零开始创建一个 OpenClaw 扩展。通过扩展，你可以为 OpenClaw 新增通道、模型提供商、工具或其他能力。

前置要求

• 已克隆 OpenClaw 代码仓库，并完成依赖安装（执行 pnpm install）
• 具备 TypeScript（ESM 模块）相关开发经验

扩展目录结构

所有扩展都存放在 extensions/<扩展名称>/ 目录下，遵循以下目录结构：

extensions/my-channel/
├── package.json          # npm 元信息 + OpenClaw 配置
├── index.ts              # 入口文件（defineChannelPluginEntry）
├── setup-entry.ts        # 安装向导（可选）
├── api.ts                # 公共契约导出文件（可选）
├── runtime-api.ts        # 内部运行时导出文件（可选）
└── src/
    ├── channel.ts        # 通道适配器实现
    ├── runtime.ts        # 运行时关联逻辑
    └── *.test.ts         # 同目录单元测试

步骤 1：创建包文件

创建 extensions/my-channel/package.json 文件，内容如下：

{
  "name": "@openclaw/my-channel",
  "version": "2026.1.1",
  "description": "OpenClaw My Channel 插件",
  "type": "module",
  "dependencies": {},
  "openclaw": {
    "extensions": ["./index.ts"],
    "setupEntry": "./setup-entry.ts",
    "channel": {
      "id": "my-channel",
      "label": "My Channel",
      "selectionLabel": "My Channel (插件)",
      "docsPath": "/channels/my-channel",
      "docsLabel": "my-channel",
      "blurb": "该通道的简短描述。",
      "order": 80
    },
    "install": {
      "npmSpec": "@openclaw/my-channel",
      "localPath": "extensions/my-channel"
    }
  }
}

其中的 openclaw 字段用于向插件系统声明你的扩展所提供的能力。如果是提供商类型的插件，请将这里的 channel 替换为 providers。

步骤 2：定义入口文件

创建 extensions/my-channel/index.ts 入口文件：

import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";


export default defineChannelPluginEntry({
  id: "my-channel",
  name: "My Channel",
  description: "将 OpenClaw 与 My Channel 连接",
  plugin: {
    // 通道适配器实现
  },
});

如果是提供商类型的插件，请改用 definePluginEntry。

步骤 3：从细分子路径导入

插件 SDK 提供了 70 多个细分的子路径。请始终从特定的子路径导入内容，而非从整体根路径导入：

// 正确：使用细分子路径
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";
import { resolveOutboundSendDep } from "openclaw/plugin-sdk/channel-runtime";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import { resolveChannelGroupRequireMention } from "openclaw/plugin-sdk/channel-policy";


// 错误：整体根路径导入（代码检查会拒绝该写法）
import { ... } from "openclaw/plugin-sdk";

常用子路径说明：

步骤 4：使用本地导出文件处理内部导入

在你的扩展内部，请创建导出文件来实现内部代码共享，而非通过插件 SDK 进行导入：

// api.ts — 该扩展的公共契约
export { MyChannelConfig } from "./src/config.js";
export { MyChannelRuntime } from "./src/runtime.js";


// runtime-api.ts — 仅内部使用的导出（不对外提供给生产环境消费者）
export { internalHelper } from "./src/helpers.js";

自导入防护规则：永远不要在生产文件中通过 openclaw/plugin-sdk/my-channel 导入你自己的扩展。请改为通过 ./api.ts 或 ./runtime-api.ts 来处理内部导入。SDK 子路径仅用于对外的外部契约。

步骤 5：添加插件清单

在你的扩展根目录创建 openclaw.plugin.json 清单文件：

{
  "id": "my-channel",
  "kind": "channel",
  "channels": ["my-channel"],
  "name": "My Channel 插件",
  "description": "将 OpenClaw 与 My Channel 连接"
}

你可以查看插件清单文档获取完整的 schema 定义。

步骤 6：通过契约测试进行验证

OpenClaw 会对所有已注册的插件执行契约测试。添加完你的扩展后，执行以下命令进行测试：

pnpm test:contracts:channels   # 通道插件测试
pnpm test:contracts:plugins    # 提供商插件测试

契约测试会验证你的插件是否符合预期的接口规范，包括安装向导、会话绑定、消息处理、群组策略等内容。

如果是单元测试，你可以从公共测试接口导入测试辅助工具：

import { createTestRuntime } from "openclaw/plugin-sdk/testing";

代码检查规则

有三个脚本会强制校验 SDK 的边界规范：

1. 禁止整体根路径导入 — 不允许从 openclaw/plugin-sdk 根路径直接导入
2. 禁止直接 src 导入 — 扩展不能直接导入 ../../src/ 路径的内容
3. 禁止自导入 — 扩展不能导入自己的 plugin-sdk/<name> 子路径

在提交代码前，请执行 pnpm check 来验证所有边界规范是否都符合要求。

提交检查清单

在提交你的扩展之前，请确认以下事项都已完成：

• [ ] package.json 中配置了正确的 OpenClaw 元信息
• [ ] 入口文件使用了 defineChannelPluginEntry 或 definePluginEntry
• [ ] 所有导入都使用了细分的 plugin-sdk/<子路径> 路径
• [ ] 内部导入使用了本地导出文件，而非 SDK 自导入
• [ ] 已添加有效的 openclaw.plugin.json 清单文件
• [ ] 契约测试已通过（执行 pnpm test:contracts）
• [ ] 单元测试已以 *.test.ts 的形式放在同目录下
• [ ] pnpm check 已通过（包含代码检查与格式校验）
• [ ] 已在 docs/channels/ 或 docs/plugins/ 下创建了对应的文档页面