1. 为什么你的 Claude Code 插件总是只在当前目录生效如果你最近在折腾 Claude Code 的 plugin大概率踩过这个坑明明装好了插件换个项目目录就找不到了或者团队里别人拉代码后完全用不了你配的东西。这不是插件坏了而是 scope 没选对。Claude Code 的 plugin以及底层的 MCP server配置有三个作用域层级local、project、user。它们决定了配置写进哪个文件、对谁生效、能不能跟着 git 走。搞不清这三者的区别就会出现我这儿好好的同事那儿报错的经典场面。这篇内容聚焦三件事把 local/project/user 三种 scope 的存储位置和生效范围讲透给出可直接复制的 settings.json 与命令行配置骨架把插件通道统一接到 TaoToken 的 Key/API 上避免每个项目重复填一堆密钥。适合正在用 Claude Code 做日常开发、想让插件配置在个人机器和团队仓库之间正确分流的同学。先说结论方便你带着预期往下看local 只认当前目录project 跟着仓库走、能共享给团队user 是你这台机器的全局配置。优先级上同名插件冲突时 project local user。记住这一条后面所有配置都是它的展开。2. TaoToken 前置把统一 Key 和 API 通道准备好在配 scope 之前先把插件要连的那个后端准备好。Claude Code 的插件和 MCP 服务通常需要两类东西一个是模型/API 的访问凭证一个是 API 的 base 地址。如果每个项目都单独填一遍scope 配得再对也会被密钥管理拖累。TaoToken 在这里的作用就是提供统一的 Key 和 API 通道。你只需要在它那边拿到一个 Key然后在各个 scope 的配置里引用同一个环境变量或同一个值就能让 local、project、user 三种配置共用一套凭证。操作路径很直接打开 https://taotoken.net/api 对应的控制台入口进入 API Keys 页面创建一个 Key。创建时建议按用途命名比如claude-code-dev方便以后区分是哪个场景在用。拿到形如sk-开头的字符串后先别急着写进项目里的.mcp.json——那会被 git 提交出去。正确做法是写进系统环境变量配置里只引用变量名。模型对话相关的调试入口在 https://taotoken.net/api 的模型对话页你可以先用它验证 Key 是否可用再去配 Claude Code 的插件。接入文档在 https://taotoken.net/api 的 doc 区域里面有 base 地址和请求格式的说明配 MCP 的 env 时会用到。这里有个我踩过的坑很多人把 Key 直接硬编码进.mcp.json然后提交结果 Key 泄露还得重新生成。project scope 的配置文件是要进 git 的里面只能放变量引用不能放真实密钥。真实值放在 user scope 或系统环境变量里。3. 三种 scope 的配置骨架与优先级覆盖3.1 local scope默认模式只认当前目录local 是默认 scope不写--scope参数时就是它。配置存储在~/.claude.json里但注意——它是按项目路径分桶存的挂在projects字段下对应你当前目录的那一项里。也就是说文件是全局的但内容只对那个路径生效。命令行添加一个 local 插件claude mcp add-json --scope local my-plugin {command:npx,args:[-y,some-mcp-server],env:{TAOTOKEN_API_KEY:${TAOTOKEN_API_KEY}}}对应的~/.claude.json结构大致是这样{ projects: { /Users/you/work/project-a: { mcpServers: { my-plugin: { command: npx, args: [-y, some-mcp-server], env: { TAOTOKEN_API_KEY: ${TAOTOKEN_API_KEY} } } } } } }关键点mcpServers嵌在projects.具体路径下面换个目录就找不到这个插件了。适合放那些只在这个项目里用、不想污染全局的实验性插件。3.2 project scope跟着仓库走团队共享project scope 把配置写进项目根目录的.mcp.json。这个文件可以提交到 git团队成员拉下来就能用同一套插件配置。这是团队协作场景最该用的模式。claude mcp add-json --scope project team-plugin {command:npx,args:[-y,team-mcp-server],env:{TAOTOKEN_API_KEY:${TAOTOKEN_API_KEY}}}生成的.mcp.json{ mcpServers: { team-plugin: { command: npx, args: [-y, team-mcp-server], env: { TAOTOKEN_API_KEY: ${TAOTOKEN_API_KEY} } } } }注意env里用的是${TAOTOKEN_API_KEY}这种变量引用不是真实 Key。每个团队成员在自己机器上把TAOTOKEN_API_KEY设成自己的值即可。这样仓库里没有密钥但大家连的是同一套 TaoToken 通道。3.3 user scope全局生效所有项目通用user scope 写进~/.claude.json的顶层mcpServers对所有项目生效。适合放你个人高频使用的插件比如搜索、文档查询这类到哪都要用的工具。claude mcp add-json --scope user global-search {command:npx,args:[-y,search-mcp],env:{TAOTOKEN_API_KEY:${TAOTOKEN_API_KEY}}}对应结构{ mcpServers: { global-search: { command: npx, args: [-y, search-mcp], env: { TAOTOKEN_API_KEY: ${TAOTOKEN_API_KEY} } } }, projects: { ...: {} } }顶层mcpServers就是 user scope 的地盘和projects平级。3.4 优先级project local user当同一个插件名在多个 scope 里都出现时Claude Code 按 project local user 的顺序取用。也就是说项目里.mcp.json的定义会盖过你全局的定义。这个设计很合理团队约定优先于个人偏好个人偏好优先于全局默认。你可以用一张表记住scope命令参数存储位置生效范围能否 git 共享local--scope local或不写~/.claude.json的projects.路径仅当前目录否project--scope project项目根.mcp.json仅该项目是user--scope user~/.claude.json顶层所有项目否提示优先级只在同名插件冲突时起作用。不同名的插件会同时存在互不覆盖。4. 验证配置是否生效配完别急着用先验证。三步走。第一步列出当前生效的插件claude mcp list输出里每个插件后面会带 scope 标记比如global-search (user)或team-plugin (project)。看到标记就说明 scope 写对了。第二步检查配置文件内容。user 和 local 看~/.claude.jsonproject 看项目根的.mcp.json。确认mcpServers出现在正确的层级顶层是 userprojects.路径下是 local项目根文件是 project。第三步换目录实测。user scope 的插件cd到任意其他项目再跑claude mcp list应该还在local scope 的插件换个目录就应该消失project scope 的插件在项目内可见、项目外不可见。验证 Key 通道是否通可以在 Claude Code 里直接发一条请求让它调用插件工具。如果返回正常结果说明 TaoToken 的 Key 和 base 地址都配对了。想单独验证模型通道用模型对话入口发一条测试消息即可。5. 本篇常见错误排查报错一mcpServers放错层级。最常见。把 user scope 的配置写进了projects下面结果只有某个目录能用。检查~/.claude.jsonuser 的mcpServers必须在顶层和projects平级。报错二project scope 提交了真实 Key。.mcp.json进了 git里面是明文sk-xxx。立刻把 Key 换成${TAOTOKEN_API_KEY}引用然后去控制台轮换那个泄露的 Key。报错三环境变量没生效。配置里写了${TAOTOKEN_API_KEY}但系统里没设这个变量插件启动就报认证失败。在终端echo $TAOTOKEN_API_KEY确认有值Windows PowerShell 用$env:TAOTOKEN_API_KEY。设完记得重启终端和 Claude Code。报错四同名插件冲突没意识到。user 和 project 都配了search你以为用的是全局那个实际被 project 覆盖了。用claude mcp list看标记或者干脆给不同 scope 的插件起不同名字。报错五改了配置没重启。Claude Code 启动时读配置运行中改文件不一定热加载。改完~/.claude.json或.mcp.json后退出重进一次。报错六路径大小写或斜杠问题。local scope 按项目路径分桶macOS 上路径大小写不敏感但存储时可能不一致导致同一个项目被当成两个。尽量用绝对路径别用~简写去配。6. 按场景选对 scope把 Key 统一收口回到最开始的问题插件只在当前目录生效是因为你用了默认的 local scope。想让它在所有项目通用加--scope user想让团队共享用--scope project并把配置提交到.mcp.json。三种 scope 的配置骨架你已经有了Key 统一走 TaoToken 的环境变量引用仓库里不留明文。日常编码和 Agent 场景如果调用频繁可以了解下 Coding Plan 这类长期方案把额度规划好临时验证模型通道就用模型对话页接入细节和 base 地址以接入文档为准。最后留一个实用习惯新建项目时先想清楚这个插件是只我用还是团队用再决定 scope。配错了不用慌claude mcp remove 名字 --scope 范围删掉重来就行配置文件里手动清理对应层级也可以。
