Claude Code Router 如何从零创建并安装第一个 Wrapper 插件

Claude Code Router 如何从零创建并安装第一个 Wrapper 插件【免费下载链接】claude-code-routerOne local control plane for every AI agent: route across models, fuse new capabilities, orchestrate tools, and stay fully in control.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-router如果你想在 Claude Code Router下称 CCR上跑一段自己的代码——比如暴露一个状态接口、启动一个本地后端、或者把代理模式捕获到的某个域名转发到自己的服务——就需要写一个 Wrapper plugin。本文按 CCR 官方文档给出一条完整路径创建一个最小扩展目录plugin.jsonindex.cjs通过桌面 UI 安装重启网关后用curl验证路由是否生效。适用于 CCR Desktop桌面应用配置通过Extensions页面管理验证命令依赖本机的 Node 和 curl。Wrapper plugin 能做什么CCR 的扩展分两层多数自定义扩展应从 Wrapper plugin 开始类型配置位置运行位置适合做什么Wrapper pluginpluginsCCR Desktop 的 Electron wrapper 进程注册本地 HTTP 路由、启动本地后端、拦截代理流量、添加内置浏览器入口、连接供应商账号用量Core gateway pluginproviderPlugins或plugins[].coreGateway.providerPluginscore gateway runtime扩展上游供应商、认证方式或 core gateway 内部能力Wrapper plugin 的模块通过setup(ctx)拿到ctx常用能力包括ctx.pluginId、ctx.pluginConfig配置里plugins[].config的内容、ctx.logger带[plugin:id]前缀的日志、ctx.paths.pluginDataDir扩展专属数据目录、ctx.registerGatewayRoute在 CCR 网关上注册本地 HTTP 路由、ctx.registerHttpBackend启动本地 HTTP 后端返回{ url, host, port }、ctx.registerProxyRoute把代理模式捕获的 host/path 转发到后端等完整字段见 扩展机制文档。加载上有两条硬约束module必须解析到明确的本地 JavaScript 文件路径可以是绝对路径、~/开头路径或相对 CCR 配置目录的./...路径任何通过module加载 JavaScript 的扩展都必须显式声明trusted-code权限。该权限不是操作系统级沙箱它用于限制 CCR 插件 API 并把“执行本地代码”的信任边界显式化。创建扩展目录和 plugin.json创建一个目录例如~/ccr-extensions/hello-extension结构如下hello-extension/ plugin.json index.cjsplugin.json用于让 CCR 的本地扩展选择器识别扩展 ID、名称和入口文件{ id: hello-extension, name: Hello Extension, module: index.cjs, surfaces: [apps, gateway], permissions: [trusted-code, apps, gateway-routes, http-backends, proxy-routes], apps: [ { id: hello-status, name: Hello Status, url: http://127.0.0.1:3456/plugins/hello } ] }其中apps里的入口会让这个扩展出现在 CCR 内置浏览器应用列表中url指向上面网关路由的默认地址CCR 桌面应用网关默认监听http://127.0.0.1:3456。编写 index.cjs 模块下面这个index.cjs注册一个状态路由、一个 echo 后端以及一个代理转发规则use strict; module.exports { async setup(ctx) { ctx.registerGatewayRoute({ auth: none, id: hello-status, method: GET, path: /plugins/hello, handler(_request, response, helpers) { helpers.sendJson(response, 200, { ok: true, plugin: ctx.pluginId, message: ctx.pluginConfig?.message || hello from CCR }); } }); const backend await ctx.registerHttpBackend({ id: hello-echo, async handler(request, response, helpers) { const body request.method POST ? (await helpers.readBody(request)).toString(utf8) : ; helpers.sendJson(response, 200, { method: request.method, path: request.url, body }); } }); ctx.registerProxyRoute({ host: api.example.local, id: hello-example-api, paths: [/v1], preserveHost: true, upstream: backend.url }); ctx.logger.info(hello backend listening at ${backend.url}); } };这个扩展会暴露三样东西GET /plugins/hello直接挂在 CCR 网关上用来验证扩展是否加载。示例里显式设了auth: none因为它是状态页如果你自己的路由要留在默认鉴权下见后文验证部分。一个本地 echo 后端由 CCR 自动分配端口backend.url会写进日志。一个代理规则当代理模式捕获到api.example.local/v1...时转发到 echo 后端。api.example.local是文档给出的示例域名真实流量要命中它需要请求方确实访问这个 host代理规则匹配时host支持精确匹配、.example.com后缀和*.example.com通配paths为空则匹配该 host 的所有路径多个路径命中时取最长 path prefix。模块也可以直接导出函数或者返回注册对象支持apps、gatewayRoutes、proxyRoutes、stop、onStop等字段不必照抄上面的结构。通过 Extensions 页面安装CCR 的运行配置存储在 SQLite 中桌面应用默认位于~/.claude-code-router/config.sqliteWindows 为%APPDATA%\claude-code-router\config.sqlite官方推荐通过 UI 添加扩展旧版 JSON 配置文件仅用于参考。步骤打开Extensions页面。点击添加扩展选择本地扩展目录。选择刚创建的hello-extension目录。保存配置。打开Server页面重启网关。保存扩展配置后必须重启网关才会生效。保存后配置数据库中的条目结构大致如下module是解析后的入口文件路径config对应代码里的ctx.pluginConfig{ plugins: [ { id: hello-extension, enabled: true, module: /Users/you/ccr-extensions/hello-extension/index.cjs, surfaces: { apps: true, gateway: true, provider: false }, permissions: [trusted-code, apps, gateway-routes, http-backends, proxy-routes], config: { message: hello from my config } } ] }上面的 JSON 是文档给出的条目结构示例其中module的绝对路径要换成你机器上扩展目录的真实路径。如果选择器没有识别到你的入口文件本地目录选择器按顺序查找plugin.json、ccr-plugin.json、.ccr-plugin/plugin.json、.codex-plugin/plugin.json、package.json里的main、ccr.module或ccrPlugin.module都没有时依次尝试目录里的index.cjs、index.mjs、index.js、plugin.cjs、plugin.mjs、plugin.js。验证扩展是否加载1. 先做语法检查CommonJS 扩展可以先跑一遍语法检查避免启动后才发现代码报错node --check ~/ccr-extensions/hello-extension/index.cjs如果扩展依赖 npm 包先在扩展目录安装依赖并确保入口文件能被 Node 解析。2. 验证 Gateway route重启网关后请求状态路由curl http://127.0.0.1:3456/plugins/hello按上面示例的 handler响应是包含ok: true、插件 ID 和message字段的 JSON配置了config: { message: hello from my config }时message返回该值否则回落到hello from CCR。如果路由使用默认的auth: gateway并且 CCR 配置了 API Key在API 密钥页面创建的客户端 Key请求必须带凭据把CCR_API_KEY替换为你的 Keycurl -H Authorization: Bearer CCR_API_KEY http://127.0.0.1:3456/plugins/hello或者curl -H x-api-key: CCR_API_KEY http://127.0.0.1:3456/plugins/hello3. 验证 HTTP 后端和代理规则registerHttpBackend返回的backend.url会写入日志示例里的ctx.logger.info会打印出来。先直接请求这个地址确认后端工作正常再开启代理模式验证目标 host/path 是否被registerProxyRoute命中。如果你是从源码运行 CCR 来调试可以在 CCR 仓库根目录执行npm install和npm run dev这会安装依赖并以开发模式启动桌面应用。扩展里的ctx.logger.info/warn/error会出现在启动 CCR 的终端中前缀类似[plugin:hello-extension]。常见问题对照现象排查方向扩展没有加载检查plugins[].enabled、plugins[].module路径和终端里的[plugin:id]报错GET /plugins/hello返回 404确认网关已重启路由path或pathPrefix是否以/开头返回 401路由默认需要 gateway API Key调试路由可显式设置auth: none修改代码不生效Wrapper plugin 会在网关重启时重新加载只有进程卡住时才需要重启 CCR端口被占用registerHttpBackend不传port会自动分配端口固定端口冲突时改回自动分配代理规则不命中检查代理模式是否开启、证书是否安装、host 是否匹配真实请求的 hostname限制与安全边界扩展代码运行在 CCR Desktop 的 Electron wrapper 进程里且trusted-code只是 API 层面的信任声明写扩展时按文档给出的安全建议约束自己只有状态页、健康检查或本机调试路由才使用auth: none其余路由保留默认的auth: gateway不要在日志里打印 API Key、OAuth token、Cookie 或完整请求头扩展写入文件时优先使用ctx.paths.pluginDataDir对readJson得到的外部输入做类型校验代理转发到外部 upstream 时明确处理 header 白名单避免把本地鉴权信息转发到不可信服务。扩展停止时 CCR 会反向执行stop、onStop钩子并关闭该扩展注册的 HTTP 后端和 SQLite store所以长连接等资源可以在stop里释放。配置数据库位置、服务地址与端口的更多细节见 配置数据库位置 和 服务配置完整的ctx字段、代理规则匹配语义和加载机制说明以 扩展机制 为准。【免费下载链接】claude-code-routerOne local control plane for every AI agent: route across models, fuse new capabilities, orchestrate tools, and stay fully in control.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-router创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考