12.1 插件开发体系：自定义扩展的工程机制

扩展能力的工程化关键不是“能不能加功能”，而是“扩展是否可控、可审计、可回滚”。OpenClaw 以插件体系作为扩展主入口：插件可以引入新的工具、集成能力或运行时组件，并通过显式启用与白名单机制收敛风险。本节基于官方插件文档说明插件的核心结构、配置方式与安全边界，并给出一组可用于验收的命令。

12.1.1 插件是什么：长驻进程内的 TypeScript 模块

与仅提供文本提示思路的技能（Skills）截然不同，插件本质是运行在 Gateway 进程内的 TypeScript 扩展模块。它们通过 jiti 在运行时被动态编译加载，能直接挂载自定义的 Agent tools、注册全新的聊天频道、实现后台轮询服务，甚至接管系统的 RPC/HTTP handler。

官方文档对插件的定位、能力范围与加载方式给出了完整说明。其中最核心的安全与工程设计在于引入了 openclaw.plugin.json (Manifest) 文件。要求每个插件必须提供这份包含配置 JSON Schema 和 uiHints 的清单声明，这么做的精妙之处是：系统在渲染 Control UI 表单或是进行首次配置拦截校验时，根本无需（也不会）执行第三方插件底层潜在的高风险 JS 代码。

工程上建议把插件当作严肃的代码级系统依赖对待：

1. 插件版本进入版本控制与发布流程。

2. 插件的 openclaw.plugin.json 严格约束参数，不合规清单在 Gateway 启动期直接拒载。

3. 插件的工具与副作用被工具策略与白名单彻底约束绑定。

12.1.2 配置与启用：entries、enabled、config 与 load.paths

插件的启用通过 plugins.entries 声明。插件 ID 使用与 npm 包名一致的短名（如 voice-call）或带作用域的包名（如 @yourorg/my-plugin）。每个条目包含唯一标识、启用开关与插件自定义配置。官方文档还提供了 allow、deny、load.paths 等字段的完整写法：https://docs.openclaw.ai/tools/plugin。

下面示例展示了完整骨架：白名单准入 + 本地路径加载 + 启用插件并传入配置。

{
  plugins: {
    enabled: true,
    allow: ['my-plugin'],           // 白名单：仅允许列出的插件加载
    deny: ['untrusted-plugin'],     // 黑名单：deny 优先于 allow
    load: {
      paths: ['~/Projects/my-plugin'], // 本地开发中的插件目录
    },
    entries: {
      'my-plugin': {
        enabled: true,
        config: {
          // 插件自定义配置
        },
      },
    },
  },
}

为了降低供应链风险，建议配合白名单机制只允许经过审计的插件生效。

12.1.3 安全边界：插件白名单与工具策略协同

插件引入的是能力，能力的使用边界仍应由确定性的策略系统兜底。官方插件文档提供了 plugins.allow 与 plugins.deny 的白名单机制；官方工具文档提供了工具的允许、拒绝与分层策略机制，并强调拒绝规则优先：

• 插件白名单：https://docs.openclaw.ai/tools/plugin

• 工具治理：https://docs.openclaw.ai/tools

实践中建议采用“双层收敛”：

1. 先用 plugins.allow 收敛可加载插件集合。

2. 再用工具策略把插件提供的工具按风险分组，并在默认档案中拒绝高风险组。

这样可以把“扩展可用性”与“扩展可执行性”拆开管理，避免某个插件被安装后立即具备不受控副作用。

具体例子：Jira 插件的灰度上线流程

假设团队开发了一个 Jira 集成插件 jira-sync（npm 包名 @yourteam/jira-sync），能让智能体查询和创建工单。安全的上线路径如下：

1. 阶段一：白名单准入 ——只在 plugins.allow 中添加该插件，但在 tools.deny 中拒绝其写入工具，先只允许查询功能：

{
  plugins: {
    allow: ['jira-sync'],
    entries: { 'jira-sync': { enabled: true } },
  },
  tools: {
    deny: ['jira.create*', 'jira.update*', 'jira.delete*'],
  },
}

1. 阶段二：小范围放开写入 ——在内部 Telegram 群中，通过 toolsBySender 只允许管理员触发创建工单：

{
  channels: {
    telegram: {
      groups: {
        '*': {
          toolsBySender: {
            'admin_id_001': { alsoAllow: ['jira.create*'] },
          },
        },
      },
    },
  },
}

1. 阶段三：全量放开 ——在内部验证 2 周无异常后，移除 tools.deny 中的 Jira 写入限制，但保留审计日志与幂等键。

12.1.4 验收与排障：用插件诊断与状态深查做成完整流程

插件相关问题不应靠“对话试出来”。官方 CLI 提供了插件列表与诊断命令，可用于上线前验收与线上排障：https://docs.openclaw.ai/cli/plugins。

建议把以下命令固定为插件变更后的最小验收集：

openclaw plugins list
openclaw plugins info my-plugin
openclaw plugins doctor
openclaw status --deep

当插件加载失败时，优先看 plugins doctor 与 status --deep 输出；当插件加载成功但行为异常时，再结合结构化日志按 traceId 回放单次链路。

openclaw logs --follow --json