配置不生效时，先别打开编辑器

配置不生效时，先别打开编辑器

一个很具体的场景：~/.workbuddy/mcp.json 里那段配置，字段名、类型、参数逐字对过三遍，跟文档一模一样。打开会话，让它调工具，它说没有可用工具。

你回去再看配置文件，还是对的。因为问题不在文件里。

先分清「没写对」和「没生效」

这两类在界面上长得几乎一样：列表空着，或者会话里用不到工具。但它们的修法完全不通用，而且坑点库把它们分在了两个不同的组：

| 组 | 条数 | 断在哪 | 修法 |

|---|---|---|---|

| A 配置写法 | 6 | 键名、type、顶层键写错 | 改文件里的字段 |

| E 生效条件 | 4 | 配置对，但宿主没加载它 | 去开关、点信任、做批准 |

区分的动作只有一个：看宿主里有没有这个 server 的条目。连条目都没有，是 E 组；条目在但工具是空的，往 server 侧查（tools/list 返回什么），那属于另一条线。

这篇只讲 E 组那 4 条，因为它们最反直觉——你越是在文件上较真，越查不出来。坑点库 17 条记录里实测 3 条、官方文档 11 条、第三方记录 3 条，而 E 组这 4 条里只有 1 条走到实测，剩下 3 条都还在文档与第三方记录档。

四条记录，逐条

一 · Trae 的项目级 MCP 默认是关的

配置写在 .trae/mcp.json，文件存在、格式正确，MCP 列表依然是空的。原因很直接：Trae 的项目级 MCP 默认关闭，不打开这个开关，配置文件完全不参与加载。

开关位置在「设置 → MCP → 启用项目级 MCP」，勾上并确认才生效。这条记录的证据档是 reported —— 来自第三方教程记录，没有官方文档交叉验证，也没有真机复现，所以只能当线索用。

同一条记录还带了两个旁注，都属于「配置对但行为不对」：command 里不能含空格，参数必须单独放进 args；超时配置的位置也和别家不同，stdio 的写在 env 里（START_MCP_TIMEOUT_MS / RUN_MCP_TIMEOUT_MS），HTTP 的写在 headers 里。

二 · WorkBuddy 的新条目要手动 Trust

~/.workbuddy/mcp.json 改完，条目不会自动生效。要去「专家·技能·连接器」里找到那一条，手动授权 / 启用，然后重启会话。

这条是 documented 档：腾讯云 WorkBuddy 文档加接入实例两处都能对上。

值得注意的是，这同一家还挂着另一个坑，属于 A 组：远程条目的 type 要写 streamablehttp，中间没有连字符。写成 streamable-http 会连不上。也就是说，同一次接入你可能同时踩 A 组和 E 组——先被字段卡住，改对之后又被信任卡住，两步看起来像同一个故障。

三 · Claude Code 的项目级 server 要批准

用 .mcp.json 加项目级 server，add 会成功，命令不报错，但会话里就是不可用——它在等一次人工批准。

这条记录有两处独立来源都写了同一件事（designrevision.com 2026-07 的客户端对比、Tessera compatibility.md 2026-10-06），证据档 documented。

绕行办法是换 scope：自动化场景改用 user scope，或者 claude mcp add 之后显式确认一次，别指望它自己生效。

四 · Gemini CLI 要先 trust 工作区

这条是四条里唯一给你明确报错的：Error: Cannot modify settings in an untrusted workspace。在未受信任的目录里执行 mcp add，写项目级配置会直接失败。

它是四条里唯一一个 measured 档——真机装测时撞到的，不是从文档推的。17 条坑点里实测只有 3 条，这是其中 1 条，所以这条可以放心按字面理解：看到这句报错，就跟配置写得好不好没关系。

绕行有两条：手动执行 gemini trust，或者自动化场景设 GEMINI_CLI_TRUST_WORKSPACE=true。后一条在 CI 里比较实用，代价是你主动放弃了那道保护。

一张对照表

| 宿主 | 开关在哪 | 看到什么算生效 | 证据档 |

|---|---|---|---|

| Trae | 设置 → MCP → 启用项目级 MCP | 列表里出现该条目 | reported |

| WorkBuddy | 连接器管理页 → Trust / 启用 → 重启会话 | 新会话里能列出工具 | documented |

| Claude Code | 首次使用时批准，或改用 user scope | 会话里工具可调，不再等批准 | documented |

| Gemini CLI | gemini trust 或设 GEMINI_CLI_TRUST_WORKSPACE=true | 不再报 untrusted workspace | measured |

为什么偏偏是这四家

把 hosts.json 的 approval 字段横着读一遍：17 个宿主里写「无需」的有 8 个（Claude Desktop、Cursor、Windsurf、Zed、Cline、Roo Code、OpenCode、Continue），剩下 9 个都要求先做一次人工动作——手动开启、手动授权、批准、trust，或者显式指定 scope。

这 9 个里，真正属于「配置写对也不算数」的强制门就是上面那 4 个。另外 5 个（CodeBuddy、Qoder、Lingma、VS Code Copilot、Codex CLI）的约束落在 scope 或添加方式上，行为更容易预期。

一个规律：图形界面越重、越强调工作区安全边界的宿主，这道门越硬。 反过来，纯 CLI 且默认信任本地目录的（OpenCode、Continue、Cline），基本不设这道门。

判据只有一条

不要用「配置文件对不对」判断，用「宿主列表里有没有这个条目」判断。

• 没条目 → 这篇的 4 条，去翻开关。
• 有条目、工具空 → 先排除 server 侧 0 工具（合成样本 fixture-zero-tools 在 17 个宿主上实测全判不可用，说明这是 server 的问题，不是宿主的问题），再查宿主能力上限与资源原语，见 平台能力对照。
• 有条目、工具在、但行为不对 → 回到 A 组的字段问题，装不上的原因 里有逐条的触发条件（共 17 条）。

想先确认自己手上的 server 长什么形状，可以先看一个具体样本：server-time 详情——2 个工具、0 个资源、启动近 8 秒，是这类本地 stdio server 的典型形态。它在这 4 家上都不会触发 E 组，因为 E 组跟 server 无关，只跟宿主有关。

最后一句

E 组只占 17 条坑点里的 4 条，但它们贡献了最多「我明明配对了」的困惑。原因不复杂：前 13 条你改文件总能试出来，这 4 条改文件永远试不出来。

配置写完不生效时，先别打开编辑器。打开宿主的列表看一眼，比改十遍字段快。如果连「该看哪个位置」都不确定，数据是怎么来的 里那套最小请求可以先替你确认 server 本身是活的。