Plugins (Extensions)

快速开始（第一次用 plugin？）

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

大多数时候，你会在想要一个核心 OpenClaw 还没内置的功能时使用 plugin（或者你想把可选功能从主安装中分离出来）。

快速上手：

查看已加载的 plugin：

openclaw plugins list

安装官方 plugin（示例：Voice Call）：

openclaw plugins install @openclaw/voice-call

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

查看 Voice Call 了解具体的 plugin 示例。

可用的 plugin（官方）

Microsoft Teams 从 2026.1.15 开始只能通过 plugin 使用；如果你用 Teams，安装 @openclaw/msteams。
Memory (Core) — 内置的内存搜索 plugin（默认通过 plugins.slots.memory 启用）
Memory (LanceDB) — 内置的长期记忆 plugin（自动回忆/捕获；设置 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 plugin 是通过 jiti 在运行时加载的 TypeScript 模块。配置验证不会执行 plugin 代码；它使用 plugin manifest 和 JSON Schema。查看 Plugin manifest。

Plugin 可以注册：

Gateway RPC 方法
Gateway HTTP 处理器
Agent 工具
CLI 命令
后台服务
可选的配置验证
Skill（通过在 plugin manifest 中列出 skills 目录）
自动回复命令（无需调用 AI agent 即可执行）

Plugin 与 Gateway 在同一进程中运行，所以要把它们当作可信代码对待。工具编写指南：Plugin agent tools。

Runtime 辅助工具

Plugin 可以通过 api.runtime 访问选定的核心辅助工具。用于电话 TTS：

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

注意：

使用核心 messages.tts 配置（OpenAI 或 ElevenLabs）。
返回 PCM 音频缓冲区 + 采样率。Plugin 必须为提供商重新采样/编码。
电话不支持 Edge TTS。

发现和优先级

OpenClaw 按顺序扫描：

配置路径

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

Workspace extensions

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

全局 extensions

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

内置 extensions（随 OpenClaw 一起发布，默认禁用）

<openclaw>/extensions/*

内置 plugin 必须通过 plugins.entries.<id>.enabled 或 openclaw plugins enable <id> 显式启用。已安装的 plugin 默认启用，但可以用同样的方式禁用。

每个 plugin 必须在其根目录包含一个 openclaw.plugin.json 文件。如果路径指向一个文件，plugin 根目录就是该文件的目录，并且必须包含 manifest。

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

Package packs

Plugin 目录可以包含一个带有 openclaw.extensions 的 package.json：

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

每个条目都会成为一个 plugin。如果 pack 列出多个 extension，plugin id 会变成 name/<fileBase>。

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

Channel catalog 元数据

Channel plugin 可以通过 openclaw.channel 发布引导元数据，通过 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 还可以合并外部 channel catalog（例如，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": {...} } } ] }。

Plugin ID

默认 plugin id：

Package packs：package.json 的 name
独立文件：文件基本名（~/.../voice-call.ts → voice-call）

如果 plugin 导出 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：额外的 plugin 文件/目录
entries.<id>：每个 plugin 的开关 + 配置

配置更改需要重启 gateway。

验证规则（严格）：

entries、allow、deny 或 slots 中的未知 plugin id 是错误。
未知的 channels.<id> 键是错误，除非 plugin manifest 声明了该 channel id。
Plugin 配置使用嵌入在 openclaw.plugin.json 中的 JSON Schema（configSchema）进行验证。
如果 plugin 被禁用，其配置会被保留并发出警告。

Plugin slots（独占类别）

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

{
  plugins: {
    slots: {
      memory: "memory-core", // 或 "none" 禁用 memory plugin
    },
  },
}

如果多个 plugin 声明 kind: "memory"，只有选定的那个会加载。其他的会被禁用并显示诊断信息。

Control UI（schema + 标签）

Control UI 使用 config.schema（JSON Schema + uiHints）来渲染更好的表单。

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

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

如果你想让 plugin 配置字段显示良好的标签/占位符（并将密钥标记为敏感），在 plugin manifest 中的 JSON Schema 旁边提供 uiHints。

示例：

{
  "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 update <id>
openclaw plugins update --all
openclaw plugins enable <id>
openclaw plugins disable <id>
openclaw plugins doctor

plugins update 只对在 plugins.installs 下跟踪的 npm 安装有效。

Plugin 也可以注册自己的顶级命令（示例：openclaw voicecall）。

Plugin API（概述）

Plugin 导出以下之一：

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

Plugin hooks

Plugin 可以附带 hook 并在运行时注册它们。这让 plugin 可以捆绑事件驱动的自动化，而无需单独安装 hook pack。

示例

import { registerPluginHooksFromDir } from "openclaw/plugin-sdk";

export default function register(api) {
  registerPluginHooksFromDir(api, "./hooks");
}

注意：

Hook 目录遵循正常的 hook 结构（HOOK.md + handler.ts）。
Hook 资格规则仍然适用（OS/bins/env/config 要求）。
Plugin 管理的 hook 在 openclaw hooks list 中显示为 plugin:<id>。
你不能通过 openclaw hooks 启用/禁用 plugin 管理的 hook；改为启用/禁用 plugin。

Provider plugin（模型认证）

Plugin 可以注册模型 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 接收一个 ProviderAuthContext，包含 prompter、runtime、openUrl 和 oauth.createVpsAwareHandlers 辅助工具。
当你需要添加默认模型或 provider 配置时，返回 configPatch。
返回 defaultModel，这样 --set-default 可以更新 agent 默认值。

注册消息 channel

Plugin 可以注册 channel plugin，其行为类似于内置 channel（WhatsApp、Telegram 等）。Channel 配置位于 channels.<id> 下，由你的 channel plugin 代码验证。

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 列出当两者都配置时要跳过自动启用的 channel id。
meta.detailLabel 和 meta.systemImage 让 UI 显示更丰富的 channel 标签/图标。

编写新的消息 channel（分步指南）

当你想要一个新的聊天界面（“消息 channel”）而不是模型 provider 时使用。模型 provider 文档位于 /providers/*。

选择一个 id + 配置形状

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

定义 channel 元数据

meta.label、meta.selectionLabel、meta.docsPath、meta.blurb 控制 CLI/UI 列表。
meta.docsPath 应指向类似 /channels/<id> 的文档页面。
meta.preferOver 让 plugin 替换另一个 channel（自动启用时优先选择它）。
meta.detailLabel 和 meta.systemImage 被 UI 用于详细文本/图标。

实现必需的适配器

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

根据需要添加可选适配器

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

在你的 plugin 中注册 channel

api.registerChannel({ plugin })

最小配置示例：

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

最小 channel plugin（仅出站）：

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` 传递到你的 channel
      return { ok: true };
    },
  },
};

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

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

Agent 工具

查看专门的指南：Plugin agent tools。

注册 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"] },
  );
}

注册自动回复命令

Plugin 可以注册自定义斜杠命令，这些命令无需调用 AI agent 即可执行。这对于切换命令、状态检查或不需要 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：发送命令的 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}` };
  },
});

注意：

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

注册后台服务

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，但避免与核心命令冲突

Skill

Plugin 可以在仓库中附带 skill（skills/<name>/SKILL.md）。使用 plugins.entries.<id>.enabled（或其他配置门控）启用它，并确保它存在于你的 workspace/托管 skill 位置。

分发（npm）

推荐的打包方式：

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

发布约定：

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

示例 plugin：Voice Call

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

源代码：extensions/voice-call
Skill：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 了解设置和使用。

安全注意事项

Plugin 与 Gateway 在同一进程中运行。把它们当作可信代码对待：

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

测试 plugin

Plugin 可以（也应该）附带测试：

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