文档
插件（扩展）

插件（扩展）

适用范围

在以下情况使用本页面：

  • 添加或修改插件/扩展
  • 记录插件安装或加载规则

快速入门（插件新手？）

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

大多数情况下，当你需要一个尚未内置到核心 Moltbot 的功能时（或者你想将可选功能保留在主安装之外），你会使用插件。

快速路径：

  1. 查看已加载的插件：
moltbot plugins list
  1. 安装官方插件（示例：语音通话）：
moltbot plugins install @moltbot/voice-call
  1. 重启 Gateway，然后在 plugins.entries.<id>.config 下进行配置。

具体插件示例请参阅 语音通话。

可用插件（官方）

  • Microsoft Teams 从 2026.1.15 起仅作为插件提供；如果你使用 Teams，请安装 @moltbot/msteams。
  • Memory (Core) — 捆绑的内存搜索插件（通过 plugins.slots.memory 默认启用）
  • Memory (LanceDB) — 捆绑的长期内存插件（自动召回/捕获；设置 plugins.slots.memory = "memory-lancedb"）
  • 语音通话 — @moltbot/voice-call
  • Zalo 个人版 — @moltbot/zalouser
  • Matrix — @moltbot/matrix
  • Nostr — @moltbot/nostr
  • Zalo — @moltbot/zalo
  • Microsoft Teams — @moltbot/msteams
  • Google Antigravity OAuth（提供商认证）— 捆绑为 google-antigravity-auth（默认禁用）
  • Gemini CLI OAuth（提供商认证）— 捆绑为 google-gemini-cli-auth（默认禁用）
  • Qwen OAuth（提供商认证）— 捆绑为 qwen-portal-auth（默认禁用）
  • Copilot Proxy（提供商认证）— 本地 VS Code Copilot Proxy 代理；与内置的 github-copilot 设备登录不同（捆绑，默认禁用）

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

插件可以注册：

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

插件在 Gateway 中进程内运行，因此请将它们视为可信代码。 工具编写指南：插件 agent 工具。

运行时辅助函数

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

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

注意事项：

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

发现与优先级

Moltbot 按顺序扫描：

  1. 配置路径
  • plugins.load.paths（文件或目录）
  1. 工作区扩展
  • <workspace>/.moltbot/extensions/*.ts
  • <workspace>/.moltbot/extensions/*/index.ts
  1. 全局扩展
  • ~/.moltbot/extensions/*.ts
  • ~/.moltbot/extensions/*/index.ts
  1. 捆绑扩展（随 Moltbot 附带，默认禁用）
  • <moltbot>/extensions/*

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

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

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

包集合

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

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

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

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

渠道目录元数据

渠道插件可以通过 moltbot.channel 宣传入门元数据，通过 moltbot.install 宣传安装提示。这使核心目录不包含数据。

示例：

{
  "name": "@moltbot/nextcloud-talk",
  "moltbot": {
    "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": "@moltbot/nextcloud-talk",
      "localPath": "extensions/nextcloud-talk",
      "defaultChoice": "npm"
    }
  }
}

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

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

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

插件 ID

默认插件 ID：

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

如果插件导出 id，Moltbot 将使用它，但当它与配置的 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：拒绝列表（可选；拒绝优先）
  • load.paths：额外的插件文件/目录
  • entries.<id>：每个插件的开关 + 配置

配置更改需要重启 gateway。

验证规则（严格）：

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

插件槽（独占类别）

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

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

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

控制界面（schema + 标签）

控制界面使用 config.schema（JSON Schema + uiHints）来呈现更好的表单。

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

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

如果你希望插件配置字段显示良好的标签/占位符（并将机密标记为敏感），请在插件清单中与 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 

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

plugins update 仅适用于在 plugins.installs 下跟踪的 npm 安装。

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

插件 API（概述）

插件导出以下任一形式：

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

插件钩子

插件可以附带钩子并在运行时注册它们。这允许插件捆绑事件驱动的自动化，而无需单独安装钩子包。

示例 

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

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

注意事项：

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

提供商插件（模型认证）

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

通过 api.registerProvider(...) 注册提供商。每个提供商公开一种或多种认证方法（OAuth、API 密钥、设备代码等）。这些方法支持：

  • moltbot 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 辅助函数。
  • 当你需要添加默认模型或提供商配置时，返回 configPatch。
  • 返回 defaultModel 以便 --set-default 可以更新 agent 默认值。

注册消息渠道

插件可以注册渠道插件，其行为类似于内置渠道（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 显示更丰富的渠道标签/图标。

编写新的消息渠道（分步说明）

当你想要一个新的聊天界面（“消息渠道”）而不是模型提供商时使用此方法。模型提供商文档位于 /providers/* 下。

  1. 选择 ID + 配置形状
  • 所有渠道配置位于 channels.<id> 下。
  • 对于多账户设置，首选 channels.<id>.accounts.<accountId>。
  1. 定义渠道元数据
  • meta.label、meta.selectionLabel、meta.docsPath、meta.blurb 控制 CLI/UI 列表。
  • meta.docsPath 应指向文档页面，如 /channels/<id>。
  • meta.preferOver 允许插件替换另一个渠道（自动启用优先选择它）。
  • meta.detailLabel 和 meta.systemImage 由 UI 用于详细文本/图标。
  1. 实现所需的适配器
  • config.listAccountIds + config.resolveAccount
  • capabilities（聊天类型、媒体、线程等）
  • outbound.deliveryMode + outbound.sendText（用于基本发送）
  1. 根据需要添加可选适配器
  • setup（向导）、security（DM 策略）、status（健康/诊断）
  • gateway（启动/停止/登录）、mentions、threading、streaming
  • actions（消息操作）、commands（本机命令行为）
  1. 在你的插件中注册渠道
  • 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 });
}

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

Agent 工具

请参阅专用指南：插件 agent 工具。

注册 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 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：发送命令的渠道
  • isAuthorizedSender：发送者是否为授权用户
  • args：命令后传递的参数（如果 acceptsArgs: true）
  • commandBody：完整的命令文本
  • config：当前的 Moltbot 配置

命令选项：

  • 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 agent 之前处理
  • 命令是全局注册的，在所有渠道中都可以工作
  • 命令名称不区分大小写（/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）

推荐的打包方式：

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

发布约定：

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

示例插件：语音通话

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

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

有关设置和用法，请参阅 语音通话 和 extensions/voice-call/README.md。

安全注意事项

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

  • 仅安装你信任的插件。
  • 首选 plugins.allow 允许列表。
  • 更改后重启 Gateway。

测试插件

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

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