CodePilot 插件系统完整指南：3 步启用第一个扩展，看懂三层配置怎么覆盖

CodePilot 插件系统完整指南：3 步启用第一个扩展，看懂三层配置怎么覆盖

【免费下载链接】CodePilotA multi-model AI agent desktop client — connect any AI provider, extend with MCP & skills, control from your phone. Built with Electron + Next.js.项目地址: https://gitcode.com/gh_mirrors/co0dep/CodePilot

CodePilot 是一个能接入多家 AI 服务商的桌面客户端。它的插件系统让你给助手装上技能（Skills）、MCP 服务器和 CLI 工具，让同一个窗口里的助手会画图、会查库、会跑脚本。这篇文章带你先装起来，再弄明白它为什么这样工作。

3 步装好第一个插件：先会用，再懂为什么

1. 打开 CodePilot，点左侧导航的「扩展」入口，进入扩展页。页面顶部是 Skills、MCP、CLI 三个标签页。
2. 在 Skills 标签点「技能商店」按钮，打开商店列表，找到想要的插件点 Install。
3. 点插件卡片右上角的开关启用它，状态立刻生效；想停用时再点一次即可。

做完这三步，插件带来的技能就会出现在聊天输入框的命令列表里。

它是怎么工作的：三个环节看懂插件加载

它去哪两个目录找插件

扫描只认两个固定位置：

• 市场插件：~/.claude/plugins/marketplaces/{市场名}/plugins/*/
• 外部插件：~/.claude/plugins/external_plugins/*/

每个插件文件夹里必须有.claude-plugin/plugin.json清单文件，缺了就不认。扫描逻辑在 src/lib/plugin-discovery.ts 里，结果带 60 秒缓存，避免每次打开页面都重读磁盘。

三层配置怎么互相覆盖

启用状态写在设置文件的enabledPlugins字段里，键的格式是插件名@市场名。共有三层，后面的覆盖前面的：

1. 用户级~/.claude/settings.json，对全部项目生效
2. 项目级{项目目录}/.claude/settings.json，只对当前项目生效
3. 本地级{项目目录}/.claude/settings.local.json，优先级最高，通常被 git 忽略

点开关时默认写用户级。如果检测到项目级或本地级会把这个值盖掉，写入会自动升级写到本地级，保证你点一下就真的生效。

黑名单优先于一切

~/.claude/plugins/blocklist.json可以硬性封禁某个插件。进了这份名单，开关点了也没用。

场景化操作：按你的实际需求走

想给助手接一个新的外部能力

切到 MCP 标签，点「添加 MCP」，填服务器名称、URL 和认证信息，保存后自动连接；嫌表单麻烦就用「JSON 配置」整段粘贴。更细的规则可以看 docs/guardrails/MCP.md。

启用前想看清楚一个插件带什么

点插件卡片打开详情弹窗，里面列着描述、作者，以及它自带的命令、技能、子代理三类内容。确认没问题再开开关。

只想在某个项目里开，不想全局生效

在项目目录的.claude/settings.json里给enabledPlugins加一条记录，改动只影响这个项目。带密钥的配置建议放本地级settings.local.json，因为它不进 git。

自定义扩展（选读）：一个最小插件长什么样

📦 插件本质就是一个带清单的文件夹。最小结构如下：

my-plugin/ ├── .claude-plugin/ │ └── plugin.json ├── commands/ # 斜杠命令 ├── skills/ # 技能 └── agents/ # 子代理

plugin.json最小可写三行：

{ "name": "my-plugin", "description": "我的第一个插件", "author": { "name": "你的名字" } }

把这个文件夹复制进~/.claude/plugins/external_plugins/，等 60 秒或重启应用，它就会出现在扩展列表里。开关打开后，技能、命令会出现在对应标签页。

避坑：不显示、不生效，按这三处查

现象一：插件文件夹拷好了，列表里没有原因：扫描结果有 60 秒缓存，或.claude-plugin/plugin.json缺失、JSON 格式错误。 解决：重启应用或等一分钟再看；没有清单文件的文件夹不会被识别。

现象二：开关是绿的，能力却用不了原因：项目级或本地级设置里有同名键把你的值盖掉了，或者插件在黑名单里。 解决：依次打开三层设置文件核对enabledPlugins里同一个键的值；再检查~/.claude/plugins/blocklist.json。

现象三：换个项目，插件状态"自己变了"原因：项目级和本地级只在各自的项目目录内生效，换项目自然换了一套值。 解决：要全局一致就只维护用户级~/.claude/settings.json，别在项目文件里重复写。

到这里，安装、启用、覆盖规则、自定义插件这条线你已经走完了。想再往下挖，直接读 src/lib/plugin-discovery.ts，扫描、缓存、三层合并都在这一个文件里。更多背景可以看项目根目录的 README_CN.md。从零开始的话：

git clone https://gitcode.com/gh_mirrors/co0dep/CodePilot cd CodePilot && npm install

【免费下载链接】CodePilotA multi-model AI agent desktop client — connect any AI provider, extend with MCP & skills, control from your phone. Built with Electron + Next.js.项目地址: https://gitcode.com/gh_mirrors/co0dep/CodePilot