插件

​

插件

插件为 OpenClaw 扩展了新功能：渠道、模型提供商、工具、技能、语音、图像生成等。有些插件是核心插件（随 OpenClaw 附带），其他是外部插件（由社区发布在 npm 上）。

​

快速开始

1. See what is loaded

   openclaw plugins list
   
2. 安装插件

   # From npm
   openclaw plugins install @openclaw/voice-call
   
   # From a local directory or archive
   openclaw plugins install ./my-plugin
   openclaw plugins install ./my-plugin.tgz
   
3. 重启 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 识别两种插件格式：

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

两者都显示在 openclaw plugins list 下。有关包的详细信息，请参阅插件包。

如果您正在编写原生插件，请从构建插件 和插件 SDK 概述开始。

​

官方插件

​

可安装 (npm)

插件	包	文档
Matrix	@openclaw/matrix	Matrix
Microsoft Teams	@openclaw/msteams	Microsoft Teams
Nostr	@openclaw/nostr	Nostr
语音通话	@openclaw/voice-call	语音通话
Zalo	@openclaw/zalo	Zalo
Zalo Personal	@openclaw/zalouser	Zalo Personal

​

核心（随 OpenClaw 附带）

Model providers (enabled by default)

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

Memory plugins

• memory-core — 捆绑的内存搜索（默认通过 plugins.slots.memory） - memory-lancedb — 按需安装的长期内存，具有自动回忆/捕获功能（设置 plugins.slots.memory = "memory-lancedb"）

Speech providers (enabled by default)

elevenlabs, microsoft

Other

• copilot-proxy — VS Code Copilot 代理桥（默认禁用）

寻找第三方插件？请参阅社区插件。

​

配置

{
  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 路径）的情况下运行，则该重启通常在配置写入完成后自动执行。

Plugin states: disabled vs missing vs invalid

• Disabled（已禁用）：插件存在，但启用规则将其关闭。配置被保留。 - Missing（缺失）：配置引用了设备发现未找到的插件 ID。 - Invalid（无效）：插件 存在，但其配置与声明的架构不匹配。

​

设备发现和优先级

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 一起提供。许多默认启用（模型提供商，语音）。 其他则需要显式启用。

​

启用规则

• plugins.enabled: false 禁用所有插件
• plugins.deny 总是覆盖允许设置
• plugins.entries.\<id\>.enabled: false 禁用该插件
• 工作区来源的插件默认禁用（必须显式启用）
• 捆绑插件遵循内置的默认开启集，除非被覆盖
• 独占插槽可以强制启用该插槽选定的插件

​

插件插槽（独占类别）

某些类别是独占的（一次只能激活一个）：

{
  plugins: {
    slots: {
      memory: "memory-core", // or "none" to disable
      contextEngine: "legacy", // or a plugin id
    },
  },
}

插槽	控制内容	默认值
memory	活动内存插件	memory-core
contextEngine	活动上下文引擎	legacy (内置)

​

CLI 参考

openclaw plugins list                    # compact inventory
openclaw plugins inspect <id>            # deep detail
openclaw plugins inspect <id> --json     # machine-readable
openclaw plugins status                  # operational summary
openclaw plugins doctor                  # diagnostics

openclaw plugins install <package>        # install (ClawHub first, then npm)
openclaw plugins install clawhub:<pkg>   # install from ClawHub only
openclaw plugins install <path>          # install from local path
openclaw plugins install -l <path>       # link (no copy) for dev
openclaw plugins update <id>             # update one plugin
openclaw plugins update --all            # update all

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

有关详细信息，请参阅 openclaw plugins CLI 参考。

​

插件 API 概览

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

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

常用注册方法：

方法	注册内容
registerProvider	模型提供商 (LLM)
registerChannel	聊天渠道
registerTool	代理工具
registerHook / on(...)	生命周期钩子
registerSpeechProvider	文本转语音 / STT
registerMediaUnderstandingProvider	图像/音频分析
registerImageGenerationProvider	图像生成
registerWebSearchProvider	网络搜索
registerHttpRoute	HTTP 端点
registerCommand / registerCli	CLI commands
registerContextEngine	Context engine
registerService	Background service

Hook guard behavior for typed lifecycle hooks:

• before_tool_call: { block: true } is terminal; lower-priority handlers are skipped.
• before_tool_call: { block: false } is a no-op and does not clear an earlier block.
• message_sending: { cancel: true } is terminal; lower-priority handlers are skipped.
• message_sending: { cancel: false } is a no-op and does not clear an earlier cancel.

For full typed hook behavior, see SDK Overview.

​

Related

• Building Plugins — create your own plugin
• Plugin Bundles — Codex/Claude/Cursor bundle compatibility
• Plugin Manifest — manifest schema
• Registering Tools — add agent tools in a plugin
• Plugin Internals — capability 模型 and load pipeline
• Community Plugins — third-party listings

---

本页面源自 openclaw/openclaw，由 BeaversLab 翻译，遵循 MIT 协议 发布。