插件

插件为 OpenClaw 扩展了新能力：频道、模型 Provider、工具、技能（skills）、语音、图像生成等。部分插件是核心插件（随 OpenClaw 内置），其他是外部插件（由社区发布到 npm）。

快速开始

第一步：查看已加载的插件

openclaw plugins list

第二步：安装插件

# 从 npm 安装
openclaw plugins install @openclaw/voice-call

# 从本地目录或压缩包安装
openclaw plugins install ./my-plugin
openclaw plugins install ./my-plugin.tgz

第三步：重启 Gateway

openclaw gateway restart

然后在配置文件的 plugins.entries.<id>.config 下进行配置。

如果你更喜欢在聊天中控制，启用 commands.plugins: true 并使用：

/plugin install clawhub:@openclaw/voice-call
/plugin show voice-call
/plugin enable voice-call

安装路径使用的解析器与 CLI 相同：本地路径/压缩包、显式 clawhub:<pkg>，或裸包名（先查 ClawHub，再回退到 npm）。

插件类型

OpenClaw 识别两种插件格式：

格式	工作方式	示例
Native（原生）	openclaw.plugin.json + 运行时模块；在进程内执行	官方插件、社区 npm 包
Bundle（包）	Codex/Claude/Cursor 兼容布局；映射到 OpenClaw 功能	.codex-plugin/、.claude-plugin/、.cursor-plugin/

两种类型都会显示在 openclaw plugins list 中。Bundle 详情参见 Plugin Bundles。

如果你想编写原生插件，从 Building Plugins 和 Plugin SDK Overview 开始。

官方插件

可安装（npm）

插件	包名	文档
Matrix	@openclaw/matrix	Matrix
Microsoft Teams	@openclaw/msteams	Microsoft Teams
Nostr	@openclaw/nostr	Nostr
Voice Call	@openclaw/voice-call	Voice Call
Zalo	@openclaw/zalo	Zalo
Zalo Personal	@openclaw/zalouser	Zalo Personal

核心插件（随 OpenClaw 内置）

模型 Provider（默认启用）

anthropic、byteplus、cloudflare-ai-gateway、github-copilot、google、 huggingface、kilocode、kimi-coding、minimax、mistral、modelstudio、 moonshot、nvidia、openai、opencode、opencode-go、openrouter、 qianfan、synthetic、together、venice、 vercel-ai-gateway、volcengine、xiaomi、zai

记忆插件

• memory-core — 内置记忆搜索（通过 plugins.slots.memory 默认启用）
• memory-lancedb — 按需安装的长期记忆，支持自动回忆/捕获（设置 plugins.slots.memory = "memory-lancedb"）

语音 Provider（默认启用）

elevenlabs、microsoft

其他

• browser — 内置浏览器插件，提供浏览器工具、openclaw browser CLI、browser.request Gateway 方法、浏览器运行时和默认浏览器控制服务（默认启用；替换前请先禁用）
• copilot-proxy — VS Code Copilot Proxy 桥接（默认禁用）

第三方插件请参见 Community Plugins。

配置

{
  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	额外的插件文件/目录
slots	独占插槽选择器（如 memory、contextEngine）
entries.<id>	单插件开关 + 配置

配置变更需要重启 Gateway。如果 Gateway 在启用配置监视 + 进程内重启的情况下运行（默认 openclaw gateway 路径），通常会在配置写入后自动重启。

插件状态：disabled、missing、invalid 的区别

• Disabled（禁用）：插件存在，但启用规则将其关闭。配置保留。
• Missing（缺失）：配置引用了一个发现过程中未找到的插件 ID。
• Invalid（无效）：插件存在，但配置不符合声明的 schema。

发现与优先级

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 内置。许多默认启用（模型 Provider、语音）。其他需要显式启用。

启用规则

• plugins.enabled: false 禁用所有插件
• plugins.deny 始终优先于 allow
• plugins.entries.<id>.enabled: false 禁用该插件
• 工作区来源的插件默认禁用（必须显式启用）
• 内置插件遵循内置默认启用集，除非被覆盖
• 独占插槽可强制启用该插槽对应的插件

插件插槽（独占分类）

某些分类是独占的（同一时间只能有一个处于活动状态）：

{
  plugins: {
    slots: {
      memory: "memory-core", // 或 "none" 禁用
      contextEngine: "legacy", // 或插件 ID
    },
  },
}

插槽	控制内容	默认值
memory	活动记忆插件	memory-core
contextEngine	活动上下文引擎	legacy（内置）

CLI 参考

openclaw plugins list                    # 紧凑清单
openclaw plugins inspect <id>            # 详细信息
openclaw plugins inspect <id> --json     # 机器可读
openclaw plugins status                  # 运行状态摘要
openclaw plugins doctor                  # 诊断

openclaw plugins install <package>        # 安装（先 ClawHub，再 npm）
openclaw plugins install clawhub:<pkg>   # 仅从 ClawHub 安装
openclaw plugins install <path>          # 从本地路径安装
openclaw plugins install -l <path>       # 链接（不复制，用于开发）
openclaw plugins update <id>             # 更新单个插件
openclaw plugins update --all            # 更新所有插件

openclaw plugins enable <id>
openclaw plugins disable <id>

完整 CLI 参考参见 openclaw plugins CLI reference。

插件 API 概览

插件导出一个函数或带 register(api) 的对象：

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  register(api) {
    api.registerProvider({
      /* ... */
    });
    api.registerTool({
      /* ... */
    });
    api.registerChannel({
      /* ... */
    });
  },
});

常用注册方法：

方法	注册内容
registerProvider	模型 Provider（LLM）
registerChannel	聊天频道
registerTool	Agent 工具
registerHook / on(...)	生命周期钩子
registerSpeechProvider	文本转语音 / STT
registerMediaUnderstandingProvider	图像/音频分析
registerImageGenerationProvider	图像生成
registerWebSearchProvider	网络搜索
registerHttpRoute	HTTP 端点
registerCommand / registerCli	CLI 命令
registerContextEngine	上下文引擎
registerService	后台服务

类型化生命周期钩子的守护行为：

• before_tool_call：{ block: true } 是终止性的；优先级更低的处理器会被跳过。
• before_tool_call：{ block: false } 是空操作，不会清除之前的 block。
• message_sending：{ cancel: true } 是终止性的；优先级更低的处理器会被跳过。
• message_sending：{ cancel: false } 是空操作，不会清除之前的 cancel。

完整类型化钩子行为参见 SDK Overview。

相关链接

• Building Plugins — 创建你自己的插件
• Plugin Bundles — Codex/Claude/Cursor Bundle 兼容性
• Plugin Manifest — manifest schema
• Registering Tools — 在插件中添加 Agent 工具
• Plugin Internals — 能力模型和加载流水线
• Community Plugins — 第三方插件列表

养龙虾小贴士：给你的龙虾装上语音通话插件（@openclaw/voice-call），它就能直接接打电话了。插件生态正是让 OpenClaw 从聊天机器人进化为真正 AI 助理的关键。