Plugin 基础：把 Skill、MCP 和前端能力打包，TaoToken 配置骨架怎么搭

1. 为什么要把 Skill、MCP 和前端能力打包成 Plugin如果你最近在折腾本地 AI 工具大概率遇到过这种局面Skill 写了好几个MCP server 也接了两三个前端还挂着一个自定义面板结果换台机器或者分享给同事时对方要手动复制目录、改路径、填 Key、重启、再逐个验证。装一次半小时出错还得从头排查。Plugin 解决的就是这个交付问题。它把「Agent 怎么做事」的 Skill、「外部系统怎么接」的 MCP、「界面怎么调」的前端能力统一收进一个可安装、可配置、可升级的运行时扩展里。你交付的不再是一堆散落文件而是一个带 manifest、带配置 schema、带运行时入口的能力包。这篇面向需要在本地 AI 工具中快速跑通插件化能力的开发者给出可复制的settings.json/config.toml骨架配合 CC Switch、Cline 的配置示例最后用三个验证动作确认Skill 加载成功、MCP 通道连通、前端能力可调用。TaoToken 在这里的角色是统一提供模型接入层让插件里的模型调用不用各自维护一套 Key 和地址。先明确三者的分工不然后面配置容易混概念职责类比Skill教 Agent 怎么做事流程、规范、话术员工手册MCP把外部系统接成工具和上下文电话线 通讯录Plugin把上面两者加前端能力打包交付整台装好的工作站一句话Skill 教会 AgentMCP 连接外部系统Plugin 把能力打包成可安装、可配置、可升级的运行时扩展。2. TaoToken 前置先把模型接入层固定下来Plugin 里最容易被忽略的坑是每个 Skill 或 MCP 工具各自去读环境变量、各自拼 base_url。一旦要换模型或者换接入点就得满仓库改。我的做法是先把模型接入层固定成一份配置插件内部只引用统一的 provider 名称。TaoToken 提供的就是这一层。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意 API 路径不带 UTM 参数配置里填干净地址就行。你需要先拿到一个 API Key。进入控制台创建https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 然后在 API Keys 页面生成https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。生成后立刻复制页面刷新就不再完整显示。注意Key 只放在本地配置文件或系统环境变量里不要写进 Plugin 的 manifest更不要提交到仓库。manifest 是冷启动就能被读取的元数据写进去等于公开。如果你还没确认模型名和调用格式可以先用模型对话页面验证一次https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。确认能正常返回之后再往 Plugin 里接能省掉一半排障时间。3. 可复制配置settings.json 与 config.toml 骨架下面这份骨架按「Plugin 目录 统一 provider Skill 挂载 MCP 通道 前端入口」组织。你可以直接改路径和名称使用。3.1 Plugin 目录结构my-plugin/ package.json openclaw.plugin.json src/ index.ts skills/ ticket-triage-guide/ SKILL.md mcp/ servers.json web/ panel.htmlpackage.json负责 npm 包信息和扩展声明openclaw.plugin.json是冷启动可检查的 manifestsrc/index.ts是真正注册工具、provider、hook、route 的运行时入口skills/放随插件分发的操作指南mcp/放外部通道声明web/放前端面板。3.2 settings.json 骨架CC Switch / Cline 通用思路{ provider: { name: taotoken, baseUrl: https://taotoken.net/api, apiKeyEnv: TAOTOKEN_API_KEY, defaultModel: claude-sonnet-4-5 }, plugins: { my-plugin: { enabled: true, config: { apiBaseUrl: https://internal.example.com, apiKeyEnv: TICKET_API_KEY }, skills: [ticket-triage-guide], mcpServers: [ticket-mcp], webEntry: web/panel.html } }, mcpServers: { ticket-mcp: { command: node, args: [./mcp/ticket-server.js], env: { TICKET_API_KEY: ${TICKET_API_KEY} } } } }关键点apiKeyEnv指向环境变量名而不是明文skills数组声明随插件加载的指南mcpServers声明通道webEntry指向前端入口。这样一份配置同时覆盖了 Skill、MCP 和前端三块。3.3 config.toml 骨架有些工具链偏好 TOML等价写法如下[provider] name taotoken base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY default_model claude-sonnet-4-5 [plugins.my-plugin] enabled true skills [ticket-triage-guide] mcp_servers [ticket-mcp] web_entry web/panel.html [plugins.my-plugin.config] api_base_url https://internal.example.com api_key_env TICKET_API_KEY [mcp_servers.ticket-mcp] command node args [./mcp/ticket-server.js] [mcp_servers.ticket-mcp.env] TICKET_API_KEY ${TICKET_API_KEY}3.4 manifest 与运行时入口openclaw.plugin.json里声明身份、配置校验和能力归属{ id: my-plugin, name: Internal Ticket Plugin, version: 0.1.0, configSchema: { type: object, properties: { apiBaseUrl: { type: string }, apiKeyEnv: { type: string } }, required: [apiBaseUrl, apiKeyEnv] }, contracts: { tools: [ticket.search, ticket.create], skills: [ticket-triage-guide], mcpServers: [ticket-mcp] } }运行时入口按能力类型注册import { definePluginEntry } from openclaw/plugin-sdk; export default definePluginEntry({ tools: [ { name: ticket.search, description: 按关键词搜索内部工单, parameters: { type: object, properties: { keyword: { type: string } }, required: [keyword] }, handler: async ({ keyword }, ctx) { const base ctx.config.apiBaseUrl; const key process.env[ctx.config.apiKeyEnv]; const res await fetch(${base}/tickets?q${encodeURIComponent(keyword)}, { headers: { Authorization: Bearer ${key} } }); return await res.json(); } } ], routes: [ { method: GET, path: /panel, handler: () ({ file: web/panel.html }) } ] });如果你只是想加几个固定工具用defineToolPlugin更短一旦同时有工具、路由、hook、provider、随附 Skill就用通用的definePluginEntry它更像一个小应用。4. 验证请求三个动作确认跑通配置写完不算完必须验证。我习惯按「冷检查 → 运行时 → 实际调用」三步走。4.1 冷检查manifest 与配置是否被识别openclaw plugins list openclaw plugins inspect my-plugin --jsonplugins list做的是冷检查只读 manifest、config 和 registry不执行插件代码。如果这里就报 configSchema 校验失败说明配置字段类型或必填项不对先修配置再往下走。4.2 运行时验证工具、hook、route 是否真的注册openclaw plugins inspect my-plugin --runtime --json这一步会真正加载运行时入口。输出里应该能看到ticket.search、ticket.create出现在 tools 列表/panel出现在 routes 列表。如果冷检查通过但运行时为空通常是入口文件路径写错或者 build 产物没生成。4.3 实际调用Skill 加载、MCP 连通、前端可调用Skill 加载确认在对话里触发一次指南里的流程看 Agent 是否按SKILL.md的步骤走。比如问「帮我按规范分派一个工单」如果它先问优先级再问归属说明 Skill 生效了。MCP 通道连通确认直接调一次工具。curl -s http://localhost:3000/api/tools/ticket.search \ -H Content-Type: application/json \ -d {keyword:登录异常}返回结构化结果说明 MCP 通道通了。如果超时先单独跑node ./mcp/ticket-server.js看 server 本身能不能起。前端能力确认浏览器打开http://localhost:3000/panel面板能渲染并且能触发一次工具调用就说明前端入口和运行时是打通的。模型调用这一层如果插件内部要直接请求模型统一走 TaoTokencurl -s https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: $TAOTOKEN_API_KEY \ -d { model: claude-sonnet-4-5, max_tokens: 256, messages: [{role:user,content:用一句话说明 Plugin 和 Skill 的区别}] }能正常返回内容说明接入层没问题插件里的模型调用可以放心复用同一份配置。5. 本篇常见错排查错误一装了 Plugin 但工具不可见。装了不等于可见。还受enabled、config 校验、optional tools、tool allowlist 影响。先看plugins list里 enabled 是不是 true再看 configSchema 有没有校验失败。错误二manifest 随便写。manifest 是冷启动验证和能力发现的关键contracts.tools里没声明的工具运行时注册了也可能不被识别。声明和实现要对齐。错误三把 Plugin 当成 Skill 的压缩包。Plugin 可以包含 Skill但它的核心价值是注册运行时能力。只写 Skill 不写运行时入口那它就是个目录不是插件。错误四所有扩展都写成 Plugin。简单操作流程写 Skill标准外部工具接 MCP只有需要安装、运行时和配置管理时才写 Plugin。过度封装会让维护成本翻倍。错误五Key 写进 manifest 或提交到仓库。用apiKeyEnv指向环境变量本地用.env或系统变量注入仓库里只留变量名。错误六MCP server 起了但通道不通。先确认 server 单独能跑再确认mcpServers里的 command 和 args 路径是相对插件根目录还是工作目录路径基准搞错是最常见的原因。6. 长期编码与 Agent 场景的接入建议如果你只是偶尔验证模型输出用模型对话页面就够了https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。但 Plugin 这类场景通常是长期跑在本地编码或 Agent 工作流里的调用频次高、会话长建议直接上 Coding Plan把配额和模型选择固定下来https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入文档在这里配置字段和错误码对照着看https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果你用的是 Claude Code 这类工具链Anthropic 兼容入口的说明在https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。回到 Plugin 本身落地时我建议先做一件事为一个内部系统画出目录结构判断它是 tool-only plugin 还是 mixed plugin写出contracts.tools清单再决定哪些说明随插件放进skills/。这一步想清楚后面的配置骨架基本就是填空题。