拒绝硬编码 fork！用插件系统安全扩展 AI Agent 的实战指南
大家好，我是提米哥。在搭建或运营 AI Agent 平台时，很多团队都会踩同一个坑：为了快速响应客户，把各种定制功能直接写进核心代码里。刚开始觉得效率极高，但一旦客户多了、需求分化，每次系统升级都会变成“代码冲突地狱”，平台风险直线上升。
今天我们就用大白话拆解 OpenClaw 的插件架构。核心思想就一个：别把个性化需求塞进核心，用插件边界把核心保护起来。 内容尽量通俗，刚入门的开发者甚至非技术背景的运营同学也能看懂背后的逻辑。
为什么“不 fork 核心”是开发者的生命线？
想象一下你在经营一家智能客服餐厅。如果每个客户点特殊菜，你都往主菜单里硬改，厨房迟早瘫痪。AI Agent 平台也一样。核心系统只该负责“消息路由、会话管理、基础调度”这些基本功。而像“对接小众聊天软件”、“接入特定 AI 模型”、“执行内部业务接口”这些定制需求，必须交给插件去做。
插件就是一个带着说明书、入口明确、能独立测试、随时能卸载的小包裹。这样核心升级时，插件不受影响，平台才能长久稳定赚钱。
第一步：先划清界限，再写代码
动笔前，先问自己：这个插件到底该管什么？
– 渠道插件（Channel）：负责账号解析、安全策略、配对流程和消息收发。核心只负责把消息递给正确的人。
– 模型提供商插件（Provider）：负责模型授权、目录解析和运行逻辑。核心不碰密钥。
– 工具/钩子插件（Tool/Hook）：负责具体的小动作，比如查订单、发通知。绝对不要越权去改核心会话存储。
记住原则：职责越窄，系统越稳。别为了一个统计指标去动核心数据库，也别自己造轮子重复实现发送逻辑。
第二步：每个插件都少不了的“身份证”
在 OpenClaw 里，所有原生插件根目录必须放一个 openclaw.plugin.json 文件。这就是插件的身份证。系统加载任何代码前，第一件事就是读它。如果文件缺失或格式错误，直接拦截，根本不会让你跑起来。
这个文件只写静态事实：插件 ID、配置校验规则、认证元数据、UI 提示等。运行逻辑请写在代码里，依赖管理请写在 package.json 里。
特别注意 configSchema 字段。哪怕你的插件不需要任何配置，也得写一个空的严格 JSON Schema 对象。这样系统在读写配置时就能提前拦截错误，而不是等网关加载一半才发现坏了。
// 插件身份证（清单文件）示例
{
// 插件全局唯一标识，不可重复
"id": "my-custom-integration",
// 配置校验规则（必填，即使无配置也要保留严格对象）
"configSchema": {
"type": "object",
"additionalProperties": false
},
// 声明该插件拥有的能力边界快照
"tools": ["query_inventory", "send_alert"]
}
第三步：SDK 导入要“专一”，别搞大杂烩
官方 SDK 有一条铁律：导入路径必须精确到子目录。
– 用 openclaw/plugin-sdk/plugin-entry 定义普通插件入口。
– 用 openclaw/plugin-sdk/core 定义渠道或设置入口。
– 运行时、测试、授权等模块，只 import 你真正用到的部分。
这么做有两个好处：启动速度飞快，还能避开循环依赖的玄学 bug。切记，不要在插件内部通过 SDK 路径导入自己写的模块，直接用相对路径（如 ./api.ts）就好。
// 精确导入 SDK 子路径示例
// 作用：避免加载无关模块，防止启动卡顿和依赖冲突
import { definePluginEntry } from 'openclaw/plugin-sdk/plugin-entry';
import { runtime } from 'openclaw/plugin-sdk/runtime';
export default definePluginEntry(async (api) => {
// 仅在此处注册业务逻辑，保持入口纯净
api.registerTool({ name: 'safe_action', handler: () => {} });
});
第四步：小功能用“工具插件”，大改动用“渠道插件”
大多数业务自动化根本不需要重做渠道。如果只是让 Agent 多一个“查库存”或“调内部 API”的能力，注册一个工具插件（Tool）就够了。
工具就是 LLM 能调用的带类型函数。如果是执行敏感操作（如改数据、调外部支付），一定要加上 { optional: true }，让管理员在后台手动勾选启用，防止 AI 误触发。
// 定义一个可选的业务工具
// 作用：安全地执行外部操作，默认关闭，需管理员显式授权
export const sensitiveTool = {
name: 'process_refund',
description: '为用户发起退款流程',
// 标记为可选，防止 Agent 自动调用
optional: true,
parameters: {
orderId: { type: 'string' },
amount: { type: 'number' }
}
}
如果是对接全新的聊天平台（如 Slack、飞书、企业微信），那就需要渠道插件。渠道插件分两层：
1. 设置层（Setup）：只负责引导用户输入密钥、配置参数。必须保持极度轻量，不要加载重型运行时库。
2. 运行层（Runtime）：消息收发和线程管理。
使用 defineChannelPluginEntry 或 defineSetupPluginEntry 时，系统会自动根据 api.registrationMode 判断当前该加载哪一层。这样能避免在“用户还没填完配置”时，因为加载了不该加载的代码而报错。
// 渠道插件入口示例
// 作用：根据注册模式自动分离设置逻辑和运行逻辑，保障启动流畅
import { defineChannelPluginEntry } from 'openclaw/plugin-sdk/core';
export default defineChannelPluginEntry({
id: 'enterprise-wechat-channel',
// 仅包含设置界面所需的轻量组件，不加载后台服务
setup: () => import('./setup-entry.ts'),
// 仅在全量启动时加载运行时逻辑
runtime: () => import('./runtime-entry.ts')
});
第五步：别碰底层黑盒，用好官方运行时助手
插件运行时需要读文件、管会话、调语音或跑子 Agent，请直接使用 api.runtime 提供的官方助手接口。
绝对不要直接去 import OpenClaw 核心库的私有文件。你的插件可能是别人在 npm 上下载的，如果路径写死了，换台服务器就报“找不到文件”。用官方注入的 api.runtime，能保证插件走到哪都能跑。同时，如果插件想自定义模型参数，必须通过配置明确获得管理员授权，不能偷偷摸摸覆盖。
第六步：测试要测“翻车现场”，发布要走正规包管理
别只测“正常流程”。插件能不能在“断网”、“缺密钥”、“被禁用”、“配置填错”的时候优雅报错？用官方提供的测试助手模拟这些场景，配合 Vitest 写单元测试。
测试通过后，把插件打包发布到 ClawHub 或 npm。用户只需要一行命令 openclaw plugins install <包名> 就能安装。注意：npm 安装默认会忽略 preinstall 脚本，所以尽量保持依赖是纯 JS/TS 代码，别依赖复杂的本地编译步骤。
# 开发者发布与安装命令示例
# 作用：通过包管理器分发插件，用户无需 fork 源码即可集成
npm publish --access public
# 用户端安装命令（支持指定来源 clawhub: 或 npm:）
openclaw plugins install my-cool-plugin
开发者实战清单（Checklist）
- 明确插件边界：只选最小的能力（工具/钩子/渠道/模型/服务）。
- 配置
package.json的openclaw元数据。 - 创建
openclaw.plugin.json，写好稳定 ID 和严格configSchema。 - SDK 导入精确到子路径，内部模块用相对路径。
- 非渠道插件用
definePluginEntry，渠道插件用defineChannelPluginEntry。 - 设置逻辑保持轻量，严格判断
api.registrationMode。 - 使用
api.runtime官方助手，禁止依赖核心私有文件。 - 敏感工具标记为
optional: true，要求管理员显式启用。 - 测试覆盖：设置流程、缺密钥、已禁用、配置错误等边界场景。
- 发布到 ClawHub 或 npm，让用户通过插件安装，而不是去 fork 你的源码。
平台开发有时确实需要改核心，但绝不能把它当成应对客户定制功能的默认方案。把通用能力留在平台里，把个性化需求交给插件。遵循这套架构，你的 Agent 业务才能像搭积木一样，随时升级，永不崩溃。
