插件（扩展）

快速开始（插件新手？）

插件只是一个小型代码模块，用额外功能扩展 OpenClaw（命令、工具和 Gateway RPC）。

大多数时候，你会在想要核心 OpenClaw 中尚未内置的功能时使用插件（或者你想把可选功能从主安装中排除）。

快速路径：

1. 查看已加载的内容：

openclaw plugins list

2. 安装官方插件（示例：语音通话）：

openclaw plugins install @openclaw/voice-call

Npm 规范仅限注册表（包名 + 可选版本/标签）。Git/URL/文件规范被拒绝。

3. 重启 Gateway，然后在 plugins.entries.<id>.config 下配置。

具体示例插件见 Voice Call。 寻找第三方列表？见社区插件。

可用插件（官方）

• Microsoft Teams 从 2026.1.15 起仅限插件；如果你使用 Teams，安装 @openclaw/msteams。
• Memory (Core) — 捆绑的记忆搜索插件（通过 plugins.slots.memory 默认启用）
• Memory (LanceDB) — 捆绑的长期记忆插件（自动回忆/捕获；设置 plugins.slots.memory = "memory-lancedb"）
• Voice Call — @openclaw/voice-call
• Zalo Personal — @openclaw/zalouser
• Matrix — @openclaw/matrix
• Nostr — @openclaw/nostr
• Zalo — @openclaw/zalo
• Microsoft Teams — @openclaw/msteams
• Google Antigravity OAuth（provider auth）— 捆绑为 google-antigravity-auth（默认禁用）
• Gemini CLI OAuth（provider auth）— 捆绑为 google-gemini-cli-auth（默认禁用）
• Qwen OAuth（provider auth）— 捆绑为 qwen-portal-auth（默认禁用）
• Copilot Proxy（provider auth）— 本地 VS Code Copilot Proxy 桥接；与内置 github-copilot 设备登录不同（捆绑，默认禁用）

OpenClaw 插件是通过 jiti 在运行时加载的 TypeScript 模块。配置验证不执行插件代码；它使用插件清单和 JSON Schema。 见插件清单。

插件可以注册：

• Gateway RPC 方法
• Gateway HTTP 处理程序
• 代理工具
• CLI 命令
• 后台服务
• 可选配置验证
• 技能（通过在插件清单中列出 skills 目录）
• 自动回复命令（不调用 AI 代理执行）

插件与 Gateway 进程内运行，因此将它们视为可信代码。工具创作指南：插件代理工具。

运行时助手

插件可以通过 api.runtime 访问选定的核心助手。对于电话 TTS：

const result = await api.runtime.tts.textToSpeechTelephony({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

注意：

• 使用核心 messages.tts 配置（OpenAI 或 ElevenLabs）。
• 返回 PCM 音频缓冲区和采样率。插件必须为 provider 进行重采样/编码。
• Edge TTS 不支持电话。

发现和优先级

OpenClaw 按顺序扫描：

1. 配置路径

• plugins.load.paths（文件或目录）

2. 工作区扩展

• <workspace>/.openclaw/extensions/*.ts
• <workspace>/.openclaw/extensions/*/index.ts

3. 全局扩展

• ~/.openclaw/extensions/*.ts
• ~/.openclaw/extensions/*/index.ts

4. 捆绑扩展（随 OpenClaw 一起发布，默认禁用）

• <openclaw>/extensions/*

捆绑插件必须通过 plugins.entries.<id>.enabled 或 openclaw plugins enable <id> 显式启用。安装的插件默认启用，但可以用相同方式禁用。

硬化说明：

• 如果 plugins.allow 为空且可发现非捆绑插件，OpenClaw 记录启动警告，包含插件 id 和来源。
• 候选路径在发现准入前经过安全检查。OpenClaw 在以下情况下阻止候选：
  • 扩展入口解析到插件根目录之外（包括符号链接/路径遍历逃逸），
  • 插件根目录/源路径是全局可写的，
  • 对于非捆绑插件，路径所有权可疑（POSIX 所有者既不是当前 uid 也不是 root）。
• 没有 install/load-path 来源的加载非捆绑插件发出警告，以便你可以固定信任（plugins.allow）或安装跟踪（plugins.installs）。

每个插件必须在其根目录包含 openclaw.plugin.json 文件。如果路径指向文件，插件根目录是文件所在目录，必须包含清单。

如果多个插件解析到相同 id，上述顺序中的第一个匹配获胜，较低优先级的副本被忽略。

包包

插件目录可以包含带 openclaw.extensions 的 package.json：

{
  "name": "my-pack",
  "openclaw": {
    "extensions": ["./src/safety.ts", "./src/tools.ts"]
  }
}

每个条目变成一个插件。如果包列出多个扩展，插件 id 变为 name/<fileBase>。

如果你的插件导入 npm 依赖，在该目录中安装它们以便 node_modules 可用（npm install / pnpm install）。

安全护栏：每个 openclaw.extensions 条目在符号链接解析后必须保持在插件目录内。逃逸包目录的条目被拒绝。

安全说明：openclaw plugins install 使用 npm install --ignore-scripts（无生命周期脚本）安装插件依赖。保持插件依赖树”纯 JS/TS”，避免需要 postinstall 构建的包。

频道目录元数据

频道插件可以通过 openclaw.channel 广告 onboarding 元数据，通过 openclaw.install 提供安装提示。这使核心目录数据保持无状态。

示例：

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk (self-hosted)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "extensions/nextcloud-talk",
      "defaultChoice": "npm"
    }
  }
}

OpenClaw 还可以合并外部频道目录（例如，一个 MPM 注册表导出）。将 JSON 文件放在以下位置之一：

• ~/.openclaw/mpm/plugins.json
• ~/.openclaw/mpm/catalog.json
• ~/.openclaw/plugins/catalog.json

或将 OPENCLAW_PLUGIN_CATALOG_PATHS（或 OPENCLAW_MPM_CATALOG_PATHS）指向一个或多个 JSON 文件（逗号/分号/PATH 分隔）。每个文件应包含 { "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }。

插件 ID

默认插件 ID：

• 包包：package.json name
• 独立文件：文件基本名称（~/.../voice-call.ts → voice-call）

如果插件导出 id，OpenClaw 使用它，但在与配置的 id 不匹配时发出警告。

配置

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    deny: ["untrusted-plugin"],
    load: { paths: ["~/Projects/oss/voice-call-extension"] },
    entries: {
      "voice-call": { enabled: true, config: { provider: "twilio" } },
    },
  },
}

字段：

• enabled：主开关（默认：true）
• allow：白名单（可选）
• deny：拒绝列表（可选；deny 获胜）
• load.paths：额外插件文件/目录
• entries.<id>：每个插件开关 + 配置

配置更改需要重启 Gateway。

验证规则（严格）：

• entries、allow、deny 或 slots 中未知的插件 id 是错误。
• 未知的 channels.<id> 键是错误，除非插件清单声明频道 id。
• 插件配置使用嵌入在 openclaw.plugin.json（configSchema）中的 JSON Schema 验证。
• 如果插件被禁用，其配置被保留并发出警告。

插件槽（独占类别）

某些插件类别是独占的（一次只能激活一个）。使用 plugins.slots 选择哪个插件拥有该槽：

{
  plugins: {
    slots: {
      memory: "memory-core", // 或 "none" 禁用内存插件
    },
  },
}

如果多个插件声明 kind: "memory"，只有选中的加载。其他被禁用并显示诊断。

Control UI（schema + 标签）

Control UI 使用 config.schema（JSON Schema + uiHints）呈现更好的表单。

OpenClaw 在运行时根据发现的插件增强 uiHints：

• 为 plugins.entries.<id> / .enabled / .config 添加每个插件的标签
• 在以下位置合并可选插件提供的配置字段提示： plugins.entries.<id>.config.<field>

如果你希望你的插件配置字段显示良好的标签/占位符（并将 secrets 标记为敏感），在插件清单中提供 uiHints 以及你的 JSON Schema。

示例：

{
  "id": "my-plugin",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "apiKey": { "type": "string" },
      "region": { "type": "string" }
    }
  },
  "uiHints": {
    "apiKey": { "label": "API Key", "sensitive": true },
    "region": { "label": "Region", "placeholder": "us-east-1" }
  }
}

CLI

openclaw plugins list
openclaw plugins info <id>
openclaw plugins install <path>                 # 将本地文件/目录复制到 ~/.openclaw/extensions/<id>
openclaw plugins install ./extensions/voice-call # 相对路径也可以
openclaw plugins install ./plugin.tgz           # 从本地 tarball 安装
openclaw plugins install ./plugin.zip           # 从本地 zip 安装
openclaw plugins install -l ./extensions/voice-call # 链接（不复制）用于开发
openclaw plugins install @openclaw/voice-call # 从 npm 安装
openclaw plugins install @openclaw/voice-call --pin # 存储精确解析的 name@version
openclaw plugins update <id>
openclaw plugins update --all
openclaw plugins enable <id>
openclaw plugins disable <id>
openclaw plugins doctor

plugins update 仅对在 plugins.installs 下跟踪的 npm 安装有效。如果存储的完整性元数据在更新之间发生变化，OpenClaw 发出警告并请求确认（使用全局 --yes 跳过提示）。

插件还可以注册自己的顶级命令（示例：openclaw voicecall）。

插件 API（概述）

插件导出：

• 函数：(api) => { ... }
• 对象：{ id, name, configSchema, register(api) { ... } }

插件钩子

插件可以在运行时注册钩子。这让插件可以捆绑事件驱动的自动化，而无需单独的钩子包安装。

示例

export default function register(api) {
  api.registerHook(
    "command:new",
    async () => {
      // 钩子逻辑在这里。
    },
    {
      name: "my-plugin.command-new",
      description: "Runs when /new is invoked",
    },
  );
}

注意：

• 通过 api.registerHook(...) 显式注册钩子。
• 钩子资格规则仍然适用（OS/bins/env/config 要求）。
• 插件管理的钩子显示在 openclaw hooks list 中，带有 plugin:<id>。
• 你不能通过 openclaw hooks 启用/禁用插件管理的钩子；改为启用/禁用插件。

Provider 插件（模型认证）

插件可以注册模型 provider 认证流程，以便用户可以在 OpenClaw 内运行 OAuth 或 API 密钥设置（无需外部脚本）。

通过 api.registerProvider(...) 注册 provider。每个 provider 暴露一种或多种认证方法（OAuth、API 密钥、设备代码等）。这些方法为以下功能提供动力：

• openclaw models auth login --provider <id> [--method <id>]

示例：

api.registerProvider({
  id: "acme",
  label: "AcmeAI",
  auth: [
    {
      id: "oauth",
      label: "OAuth",
      kind: "oauth",
      run: async (ctx) => {
        // 运行 OAuth 流程并返回认证配置文件。
        return {
          profiles: [
            {
              profileId: "acme:default",
              credential: {
                type: "oauth",
                provider: "acme",
                access: "...",
                refresh: "...",
                expires: Date.now() + 3600 * 1000,
              },
            },
          ],
          defaultModel: "acme/opus-1",
        };
      },
    },
  ],
});

注意：

• run 接收带 prompter、runtime、openUrl 和 oauth.createVpsAwareHandlers 助手的 ProviderAuthContext。
• 当你需要添加默认模型或 provider 配置时返回 configPatch。
• 返回 defaultModel 以便 --set-default 可以更新代理默认值。

注册消息频道

插件可以注册行为类似于内置频道（WhatsApp、Telegram 等）的频道插件。频道配置位于 channels.<id> 下，由你的频道插件代码验证。

const myChannel = {
  id: "acmechat",
  meta: {
    id: "acmechat",
    label: "AcmeChat",
    selectionLabel: "AcmeChat (API)",
    docsPath: "/channels/acmechat",
    blurb: "demo channel plugin.",
    aliases: ["acme"],
  },
  capabilities: { chatTypes: ["direct"] },
  config: {
    listAccountIds: (cfg) => Object.keys(cfg.channels?.acmechat?.accounts ?? {}),
    resolveAccount: (cfg, accountId) =>
      cfg.channels?.acmechat?.accounts?.[accountId ?? "default"] ?? {
        accountId,
      },
  },
  outbound: {
    deliveryMode: "direct",
    sendText: async () => ({ ok: true }),
  },
};

export default function (api) {
  api.registerChannel({ plugin: myChannel });
}

注意：

• 将配置放在 channels.<id> 下（不是 plugins.entries）。
• meta.label 用于 CLI/UI 列表中的标签。
• meta.aliases 添加用于规范化和 CLI 输入的替代 id。
• meta.preferOver 列出当两者都配置时要跳过的自动启用的频道 id。
• meta.detailLabel 和 meta.systemImage 让 UI 显示更丰富的频道标签/图标。

频道 onboarding 钩子

频道插件可以在 plugin.onboarding 上定义可选的 onboarding 钩子：

• configure(ctx) 是基线设置流程。
• configureInteractive(ctx) 可以完全拥有针对已配置和未配置状态的交互式设置。
• configureWhenConfigured(ctx) 只能覆盖已配置频道的行为。

向导中的钩子优先级：

1. configureInteractive（如果存在）
2. configureWhenConfigured（仅当频道状态已配置时）
3. 回退到 configure

上下文详情：

• configureInteractive 和 configureWhenConfigured 接收：
  • configured（true 或 false）
  • label（提示使用的面向用户的频道名称）
  • 加上共享的 config/runtime/prompter/options 字段
• 返回 "skip" 保持选择和账户跟踪不变。
• 返回 { cfg, accountId? } 应用配置更新并记录账户选择。

编写新消息频道（逐步）

当你想要新的聊天界面（“消息频道”）而不是 model provider 时使用这个。Model provider 文档位于 /providers/*。

1. 选择 id + 配置形状

• 所有频道配置位于 channels.<id> 下。
• 对于多账户设置，优先使用 channels.<id>.accounts.<accountId>。

2. 定义频道元数据

• meta.label、meta.selectionLabel、meta.docsPath、meta.blurb 控制 CLI/UI 列表。
• meta.docsPath 应指向文档页面，如 /channels/<id>。
• meta.preferOver 让插件替换另一个频道（自动启用优先它）。
• meta.detailLabel 和 meta.systemImage 由 UI 用于详情文本/图标。

3. 实现所需适配器

• config.listAccountIds + config.resolveAccount
• capabilities（聊天类型、媒体、线程等）
• outbound.deliveryMode + outbound.sendText（用于基本发送）

4. 根据需要添加可选适配器

• setup（向导）、security（DM 策略）、status（健康/诊断）
• gateway（启动/停止/登录）、mentions、threading、streaming
• actions（消息操作）、commands（本机命令行为）

5. 在插件中注册频道

• api.registerChannel({ plugin })

最小配置示例：

{
  channels: {
    acmechat: {
      accounts: {
        default: { token: "ACME_TOKEN", enabled: true },
      },
    },
  },
}

最小频道插件（仅出站）：

const plugin = {
  id: "acmechat",
  meta: {
    id: "acmechat",
    label: "AcmeChat",
    selectionLabel: "AcmeChat (API)",
    docsPath: "/channels/acmechat",
    blurb: "AcmeChat messaging channel.",
    aliases: ["acme"],
  },
  capabilities: { chatTypes: ["direct"] },
  config: {
    listAccountIds: (cfg) => Object.keys(cfg.channels?.acmechat?.accounts ?? {}),
    resolveAccount: (cfg, accountId) =>
      cfg.channels?.acmechat?.accounts?.[accountId ?? "default"] ?? {
        accountId,
      },
  },
  outbound: {
    deliveryMode: "direct",
    sendText: async ({ text }) => {
      // 在这里传递 `text` 到你的频道
      return { ok: true };
    },
  },
};

export default function (api) {
  api.registerChannel({ plugin });
}

加载插件（扩展目录或 plugins.load.paths），重启 gateway，然后在配置中配置 channels.<id>。

代理工具

见专用指南：插件代理工具。

注册 Gateway RPC 方法

export default function (api) {
  api.registerGatewayMethod("myplugin.status", ({ respond }) => {
    respond(true, { ok: true });
  });
}

注册 CLI 命令

export default function (api) {
  api.registerCli(
    ({ program }) => {
      program.command("mycmd").action(() => {
        console.log("Hello");
      });
    },
    { commands: ["mycmd"] },
  );
}

注册自动回复命令

插件可以注册自定义斜杠命令，不调用 AI 代理执行。这对切换命令、状态检查或不需要 LLM 处理的快速操作很有用。

export default function (api) {
  api.registerCommand({
    name: "mystatus",
    description: "Show plugin status",
    handler: (ctx) => ({
      text: `Plugin is running! Channel: ${ctx.channel}`,
    }),
  });
}

命令处理程序上下文：

• senderId：发送者的 ID（如果可用）
• channel：发送命令的频道
• isAuthorizedSender：发送者是否是授权用户
• args：命令后传递的参数（如果 acceptsArgs: true）
• commandBody：完整命令文本
• config：当前 OpenClaw 配置

命令选项：

• name：命令名称（不带前导 /）
• description：命令列表中显示的帮助文本
• acceptsArgs：命令是否接受参数（默认：false）。如果为 false 且提供了参数，命令不会匹配，消息会传递到其他处理程序
• requireAuth：是否需要授权发送者（默认：true）
• handler：返回 { text: string } 的函数（可以是异步的）

带授权和参数的示例：

api.registerCommand({
  name: "setmode",
  description: "Set plugin mode",
  acceptsArgs: true,
  requireAuth: true,
  handler: async (ctx) => {
    const mode = ctx.args?.trim() || "default";
    await saveMode(mode);
    return { text: `Mode set to: ${mode}` };
  },
});

注意：

• 插件命令在内置命令和 AI 代理之前处理
• 命令全局注册并跨所有频道工作
• 命令名称不区分大小写（/MyStatus 匹配 /mystatus）
• 命令名称必须以字母开头，仅包含字母、数字、连字符和下划线
• 保留的命令名称（如 help、status、reset 等）不能被插件覆盖
• 跨插件重复命令注册将失败并显示诊断错误

注册后台服务

export default function (api) {
  api.registerService({
    id: "my-service",
    start: () => api.logger.info("ready"),
    stop: () => api.logger.info("bye"),
  });
}

命名约定

• Gateway 方法：pluginId.action（示例：voicecall.status）
• 工具：snake_case（示例：voice_call）
• CLI 命令：kebab 或 camel，但避免与核心命令冲突

技能

插件可以在仓库中附带技能（skills/<name>/SKILL.md）。 通过 plugins.entries.<id>.enabled（或其他配置门控）启用它，并确保它存在于你的工作区/管理的技能位置。

分发（npm）

推荐打包：

• 主包：openclaw（此仓库）
• 插件：单独的 npm 包在 @openclaw/* 下（示例：@openclaw/voice-call）

发布合约：

• 插件 package.json 必须包含 openclaw.extensions 以及一个或多个入口文件。
• 入口文件可以是 .js 或 .ts（jiti 在运行时加载 TS）。
• openclaw plugins install <npm-spec> 使用 npm pack，解压到 ~/.openclaw/extensions/<id>/，并在配置中启用它。
• 配置键稳定性：作用域包在 plugins.entries.* 中规范化为非作用域 id。

示例插件：语音通话

此仓库包含一个语音通话插件（Twilio 或日志回退）：

• 源码：extensions/voice-call
• 技能：skills/voice-call
• CLI：openclaw voicecall start|status
• 工具：voice_call
• RPC：voicecall.start、voicecall.status
• 配置（twilio）：provider: "twilio" + twilio.accountSid/authToken/from（可选 statusCallbackUrl、twimlUrl）
• 配置（dev）：provider: "log"（无网络）

设置和使用见 Voice Call 和 extensions/voice-call/README.md。

安全说明

插件与 Gateway 进程内运行。将它们视为可信代码：

• 只安装你信任的插件。
• 优先使用 plugins.allow 白名单。
• 更改后重启 Gateway。

测试插件

插件可以（应该）附带测试：

• 仓库内插件可以将 Vitest 测试保留在 src/** 下（示例：src/plugins/voice-call.plugin.test.ts）。
• 单独发布的插件应运行自己的 CI（lint/build/test）并验证 openclaw.extensions 指向构建的入口点（dist/index.js）。