OpenClaw 插件系统实战：用 Manifest 扩展你的 AI Agent 边界

1. 当内置工具不够用OpenClaw 插件系统要解决的真实问题OpenClaw 的插件系统是一套围绕 Manifest 声明文件构建的扩展机制它让 AI Agent 在不改动核心代码的前提下获得新工具、新中间件和新事件处理能力。如果你正在用 OpenClaw 跑自动化流程迟早会遇到一个尴尬时刻Agent 能读写文件、能搜索网页、能操作浏览器但老板突然说让它每天查一下上海天气自动推到群里。你打开工具列表一看没有天气工具。这时候有三条路。改核心代码加一个 weather 工具维护噩梦升级就丢写一个 Skill 用 Python 脚本调天气 API但 Skill 太重你只是想要一个工具写插件注册一个 weather 工具独立、轻量、可复用。插件系统的价值就在这里——它是 OpenClaw 扩展性的核心用 Manifest 声明能力用生命周期钩子管理状态用工具注册中心让 Agent 发现并调用。这篇面向需要为 AI Agent 增加自定义能力的开发者给出可复制的插件目录结构、Manifest 字段骨架、本地加载验证步骤并说明如何通过 TaoToken 统一 Key/API 通道接入模型调用最终跑通一个最小插件示例。适合已经跑通 OpenClaw 基础对话、想往 Agent 里塞自己业务逻辑的人。2. TaoToken 前置统一 Key 与 API 通道在写插件之前先把模型调用通道理顺。插件里如果直接硬编码各家模型的 Key换模型就要改代码测试和生产环境还要各维护一套。我试过用 TaoToken 做统一入口插件只认一个 API 地址和一个 Key模型切换在配置层完成。TaoToken 的 API 地址是https://taotoken.net/api兼容 OpenAI 风格的请求格式。你需要在控制台创建一个 API Key然后把它写进环境变量插件通过环境变量读取不落盘到代码里。具体操作路径打开控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite创建 API Key在 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite复制你的 Key接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite里面有完整的请求示例把 Key 写进环境变量export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api插件里读取这两个变量构造请求时用TAOTOKEN_BASE_URL作为 baseTAOTOKEN_API_KEY作为 Bearer Token。这样你的插件不关心背后是哪个模型只关心我要调一次对话补全。注意不要把 Key 写进plugin.json或任何会提交到版本库的文件。Manifest 里的config字段只声明需要一个 secret 类型的 api_key实际值从环境变量注入。3. 可复制配置插件目录结构与 Manifest 骨架3.1 最小插件目录一个能跑起来的 OpenClaw 插件最少需要三个文件weather-plugin/ ├── plugin.json # Manifest插件身份与能力声明 ├── main.py # 插件入口工具实现与生命周期钩子 └── requirements.txt # Python 依赖plugin.json是插件的身份证OpenClaw 的 Plugin Manager 靠它识别插件、校验依赖、注册工具。字段骨架如下{ name: weather-plugin, version: 1.0.0, description: 查询城市天气支持实时与未来预报, author: your-name, license: MIT, capabilities: [ { type: tool, id: get_weather, description: 查询指定城市的天气信息, parameters: { type: object, properties: { city: { type: string, description: 城市名称如 上海、Beijing }, days: { type: number, description: 预报天数 1-7默认 1, default: 1 } }, required: [city] } } ], dependencies: { requests: ^2.28.0 }, runtime: { type: python, version: 3.9, entry: main.py }, permissions: [ network:api.openweathermap.org ], config: { api_key: { type: string, description: 天气服务 API Key, required: true, secret: true }, units: { type: string, enum: [metric, imperial, standard], default: metric } } }Manifest 关键字段的作用对照字段必填说明name是插件唯一标识符version是语义化版本号capabilities是插件提供的能力列表工具/中间件/事件处理dependencies否运行时依赖的第三方包runtime是运行环境Python/Node.js/Shellpermissions是插件需要的权限声明config否插件可配置项secret 类型从环境变量注入3.2 工具注册机制工具注册是插件系统最核心的机制。Agent 启动时Plugin Manager 扫描插件目录读取每个plugin.json校验 Manifest 合法性检查依赖和权限然后把capabilities里声明的工具注册到 Tool Registry。Agent 查询可用工具时Registry 返回过滤后的列表Agent 就能看到你的get_weather。注册流程的关键点工具 ID 必须全局唯一重复注册会抛冲突参数 schema 会被校验格式不对直接拒绝权限声明不全会导致工具被过滤掉Agent 看不到。所以 Manifest 里的capabilities和permissions不是装饰是运行时真正生效的约束。3.3 插件入口实现main.py里要实现工具逻辑和生命周期钩子。最小实现如下import os import time import requests PLUGIN_META { capabilities: [tool:get_weather], hooks_implemented: [on_load, on_unload] } class PluginConfig: def __init__(self): self.api_key os.environ.get(WEATHER_API_KEY, ) self.units os.environ.get(WEATHER_UNITS, metric) self.cache_ttl 600 self._cache {} def get_cache(self, city): cached self._cache.get(city) if cached and (time.time() - cached[ts]) self.cache_ttl: return cached[data] return None def set_cache(self, city, data): self._cache[city] {data: data, ts: time.time()} config PluginConfig() tool None def on_load(): global tool if not config.api_key: print(weather-plugin: API Key 未配置将返回模拟数据) tool WeatherTool(config) print(fweather-plugin loaded, units{config.units}) return {status: loaded, capabilities: PLUGIN_META[capabilities]} def on_unload(): global tool config._cache.clear() tool None print(weather-plugin unloaded) return {status: unloaded} class WeatherTool: BASE_URL https://api.openweathermap.org/data/2.5/weather def __init__(self, cfg): self.config cfg def get_weather(self, city, days1): cached self.config.get_cache(city) if cached: return {source: cache, **cached} params { q: city, appid: self.config.api_key, units: self.config.units, lang: zh_cn } try: resp requests.get(self.BASE_URL, paramsparams, timeout10) resp.raise_for_status() data resp.json() info { city: data.get(name, city), temperature: data[main][temp], humidity: data[main][humidity], weather: data[weather][0][description], timestamp: int(time.time()) } self.config.set_cache(city, info) return {source: api, **info} except requests.exceptions.Timeout: return {source: fallback, city: city, error: 请求超时} except requests.exceptions.HTTPError as e: if e.response.status_code 404: return {source: fallback, city: city, error: f未找到城市 {city}} raise def handle_get_weather(params): city params.get(city, 北京) days params.get(days, 1) if not tool: return {error: 插件未初始化} return tool.get_weather(city, days) EXPORTS { get_weather: handle_get_weather }这里有几个约定要记住工具处理函数命名必须是handle_{tool_id}Plugin Manager 靠这个命名规则找到入口EXPORTS字典是工具调用的映射表Agent 调用get_weather时实际执行的是handle_get_weatheron_load和on_unload是生命周期钩子分别在插件加载和卸载时触发。3.4 安装与启用把插件目录复制到 OpenClaw 的插件目录然后在openclaw.yaml里启用cp -r weather-plugin/ /etc/openclaw/plugins/plugins: enabled: true directory: /etc/openclaw/plugins installed: weather-plugin: enabled: true config: api_key: ${WEATHER_API_KEY} units: metric management: fail_strategy: continue hot_reload: truefail_strategy: continue表示插件加载失败不阻塞 Gateway 启动hot_reload: true在开发模式下开启热加载改代码不用重启。4. 验证请求本地加载与成功结果4.1 本地测试脚本不启动 Gateway 也能验证插件逻辑。写一个测试脚本直接调用on_load和handle_get_weatherfrom main import on_load, handle_get_weather result on_load() print(f插件状态: {result[status]}) print(f提供能力: {result[capabilities]}) test_cases [ {city: 上海, days: 1}, {city: Beijing, days: 3}, {city: 不存在的城市XYZ, days: 1}, ] for params in test_cases: print(f\n查询: {params}) res handle_get_weather(params) if error in res: print(f 错误: {res[error]}) else: print(f {res[city]}: {res[weather]}, {res[temperature]}°C, 湿度 {res[humidity]}%) print(f 数据来源: {res.get(source)})预期输出weather-plugin loaded, unitsmetric 插件状态: loaded 提供能力: [tool:get_weather] 查询: {city: 上海, days: 1} 上海: 晴, 28.0°C, 湿度 65% 数据来源: api 查询: {city: Beijing, days: 3} Beijing: 多云, 22.0°C, 湿度 45% 数据来源: api 查询: {city: 不存在的城市XYZ, days: 1} 错误: 未找到城市 不存在的城市XYZ4.2 通过 TaoToken 接入模型调用插件本身不直接调模型但你的 Agent 在调用工具前后需要模型决策。把模型调用统一走 TaoToken插件里如果需要做根据天气生成推送文案这类二次处理可以这样请求import os import requests def call_model(prompt): base os.environ.get(TAOTOKEN_BASE_URL, https://taotoken.net/api) key os.environ.get(TAOTOKEN_API_KEY, ) resp requests.post( f{base}/v1/chat/completions, headers{ Authorization: fBearer {key}, Content-Type: application/json }, json{ model: gpt-4o-mini, messages: [{role: user, content: prompt}] }, timeout30 ) resp.raise_for_status() return resp.json()[choices][0][message][content]这样插件只认TAOTOKEN_BASE_URL和TAOTOKEN_API_KEY换模型改配置即可。想先验证模型通道是否通可以直接在模型对话页面https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite发一条消息测试。4.3 Gateway 内验证启动 Gateway 后用 CLI 检查插件状态openclaw plugins list openclaw plugins inspect weather-plugin openclaw plugins validate weather-plugininspect会输出插件声明的能力和注册的工具 IDvalidate会校验 Manifest 格式和依赖完整性。如果get_weather出现在工具列表里说明注册成功。5. 本篇常见错排查5.1 插件未加载症状是openclaw plugins list里看不到你的插件。先检查plugin.json是否在插件根目录文件名必须是plugin.json或manifest.json。再检查 JSON 格式多一个逗号都会导致解析失败。用openclaw plugins validate weather-plugin能直接定位格式错误。5.2 工具未被发现插件加载了但 Agent 看不到get_weather。最常见原因是capabilities里声明的id和EXPORTS里的键不一致。Manifest 里写get_weatherEXPORTS里也必须是get_weather处理函数是handle_get_weather。三者对不上工具就注册不上。5.3 运行时 404Agent 调用工具时报 404通常是工具 ID 和处理函数命名不匹配。检查handle_{tool_id}的命名规则tool_id是get_weather函数就必须叫handle_get_weather不能叫get_weather_handler。5.4 权限拒绝工具被过滤掉Agent 看不到。检查permissions声明是否覆盖了插件实际访问的资源。访问外部 API 要声明network:api.openweathermap.org读文件要声明filesystem:read:/path。权限声明不全Plugin Manager 会在注册阶段就把工具过滤掉。5.5 依赖缺失插件加载时报ModuleNotFoundError。检查requirements.txt是否列全了依赖然后在插件目录执行pip install -r requirements.txt。注意 OpenClaw 的 Python 环境可能和系统 Python 不是同一个用openclaw plugins check-deps weather-plugin确认。5.6 开启调试日志排查问题时打开详细日志logging: plugins: debug tools: debugplugins: debug输出插件加载、校验、注册的每一步tools: debug输出工具调用的参数和结果。日志里能看到工具是否注册成功、参数是否通过 schema 校验、调用是否命中处理函数。6. 继续扩展从最小插件到生产可用最小插件跑通后往生产走还有几个方向。中间件插件可以在工具调用前后插入逻辑比如记录每次调用的耗时和结果大小不改变工具核心逻辑只在外层做拦截。事件驱动插件监听 Gateway 的内部事件比如message.received、tool.called在特定事件发生时触发自定义处理。多能力插件在一个 Manifest 里同时声明工具、中间件和事件处理适合企业微信这类需要多种能力配合的场景。热加载是开发利器。hot_reload: true开启后修改插件代码文件监听器检测到变化自动卸载旧版本、校验新版本、激活新版本失败则回退到旧版本。开发时不用反复重启 Gateway。如果你要长期跑编码类 Agent 或自动化流程Coding Plan 页面https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite有更完整的接入方案。Claude Code 相关的 Anthropic 兼容接入在https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode-anthropicutm_campaignrewrite。插件系统的边界在于 Manifest 声明什么Agent 就能用什么。把业务逻辑封装成插件核心代码保持干净升级不丢功能这是 OpenClaw 扩展性的真正价值。