第4课：创建插件#

为什么需要这个#

插件是 OpenClaw 的"扩展"，可以添加新功能：工具、通信渠道、命令。如果基本功能不够用，可以安装现成的插件或创建自己的。就像手机上的应用 — 基本功能已经有了，但应用商店才让手机真正好用。

插件能做什么#

插件可以添加：

• 工具 给助手使用（例如语音通话）
• 通信渠道（新的聊天软件）
• CLI 命令（新的文本命令）
• 后台服务（持续运行）
• 技能（skills — 给助手的指令）
• 自动回复 斜杠命令（无需调用 AI）

安装现成的插件#

查看已安装的插件#

openclaw plugins list

从 npm 安装#

openclaw plugins install @openclaw/voice-call

启用/禁用#

openclaw plugins enable voice-call
openclaw plugins disable voice-call

修改后需要重启 Gateway：

openclaw gateway restart

官方插件#

插件清单文件#

每个插件必须在根目录有一个 openclaw.plugin.json 文件。这是插件的"身份证"，描述了它是什么。

最简清单：

{
  "id": "my-plugin",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {}
  }
}

扩展版本：

{
  "id": "my-plugin",
  "name": "我的插件",
  "description": "添加有用的功能",
  "version": "1.0.0",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "apiKey": { "type": "string" }
    }
  },
  "uiHints": {
    "apiKey": { "label": "API 密钥", "sensitive": true }
  }
}

必填字段：

• id — 插件的唯一名称
• configSchema — 设置的 JSON Schema（即使没有设置也需要）

可选字段：

• name — 显示名称
• description — 简短描述
• kind — 插件类型（例如 "memory"）
• channels — 注册的频道
• skills — 技能文件夹

简单插件的结构#

my-plugin/
├── openclaw.plugin.json    ← 清单文件（必需）
├── index.ts                ← 插件代码
└── package.json            ← 依赖项（如需要）

代码示例（index.ts）#

最简单的插件 — 添加一个命令：

export default function(api) {
  // 注册斜杠命令
  api.registerCommand({
    name: "ping",
    description: "检查插件是否工作",
    handler: () => ({
      text: "Pong! 插件正常工作 🎉"
    })
  });
}

带助手工具的插件#

export default function(api) {
  // 注册 RPC 方法（远程调用）
  api.registerGatewayMethod("myplugin.weather", ({ respond }) => {
    respond(true, { temperature: 22, city: "Moscow" });
  });
}

带后台服务的插件#

export default function(api) {
  api.registerService({
    id: "my-monitor",
    start: () => api.logger.info("监控已启动"),
    stop: () => api.logger.info("监控已停止")
  });
}

如何将插件添加到 OpenClaw#

方式1：本地插件#

将文件放在扩展文件夹中：

~/.openclaw/extensions/my-plugin/
├── openclaw.plugin.json
└── index.ts

OpenClaw 会自动找到它。

方式2：通过配置#

{
  plugins: {
    enabled: true,
    load: {
      paths: ["~/Projects/my-plugin"]
    },
    entries: {
      "my-plugin": {
        enabled: true,
        config: {
          apiKey: "你的密钥"
        }
      }
    }
  }
}

方式3：从文件安装#

openclaw plugins install ./path/to/my-plugin
openclaw plugins install ./plugin.zip

插件搜索顺序#

OpenClaw 按以下顺序搜索插件（先找到的优先）：

1. plugins.load.paths 中的路径
2. <workspace>/.openclaw/extensions/
3. ~/.openclaw/extensions/
4. 内置扩展（默认关闭）

插件安全#

⚠️ 插件在 Gateway 内部运行 — 它们有完全的访问权限。只安装你信任的插件。

使用列表来限制：

{
  plugins: {
    allow: ["voice-call", "my-plugin"],  // 只允许这些
    deny: ["untrusted-plugin"]            // 禁止这些
  }
}

诊断#

openclaw plugins list      # 查看已安装的
openclaw plugins info my-plugin  # 插件详情
openclaw plugins doctor    # 检查错误

课程总结#

• 插件 是扩展 OpenClaw 功能的模块
• 每个插件必须有清单文件 openclaw.plugin.json
• 插件可以添加命令、工具、频道和后台服务
• 通过 openclaw plugins install 安装，或放在扩展文件夹中
• 插件在 Gateway 内部运行 — 只信任经过验证的插件
• 使用 openclaw plugins doctor 检查问题