WorkBuddy 的 MCP 显示红灯怎么办？官方给了三个排查方向
MCP 配完保存，界面上那个状态指示灯是红的。
官方对这两种状态的说明很简洁：
| 状态 | 含义 |
|---|---|
| 🟢 绿色 | 连接成功，可正常使用 |
| 🔴 红色 | 配置异常，需检查配置内容、命令环境或地址 |
三个方向，官方还额外强调了其中一个的优先级。这篇把它们拆成可执行的顺序。
本文依据 WorkBuddy 官方文档《MCP》（
Function-Description/MCP-Guide），核对日 2026-08-16。我们没有安装客户端，本文不含实测数据；官方未列错误码表，本文不编造。
一、第一步：查 JSON 格式（官方点名优先）
官方在安全提示里明确写了优先级：
检查 JSON 格式——配置失败时优先确认括号、引号是否完整。
为什么排第一：这是手改配置最高频的错误，而且格式错了整个配置都不会生效，后面查什么都白搭。
对照官方给的标准结构自查：
{
"mcpServers": {
"wecom": {
"command": "uvx",
"args": ["wecom-bot-mcp-server"],
"env": {
"WECOM_WEBHOOK_URL": "your-webhook-url"
}
}
}
}
常见错误清单：
| 错误 | 表现 |
|---|---|
| 最外层大括号少一个 | 整段解析失败 |
| 替换地址时把引号删掉了 | 最常见——"WECOM_WEBHOOK_URL": 你的地址 缺了双引号 |
| 多个 server 之间少了逗号 | 第二个开始不生效 |
| 最后一项后面多了个逗号 | JSON 不允许尾逗号 |
| 从网页复制时带进了全角引号 | 看着像引号，其实不是 |
最后一条最阴：中文输入法下打出的弯引号跟 JSON 要的直双引号是不同的字符，肉眼几乎看不出区别。从聊天软件、文档里复制配置片段时特别容易中招。
自查办法：把整段配置贴进任意一个 JSON 校验工具看一眼，或者对照官方那段结构逐个括号数一遍。
二、第二步：查命令环境
官方给的第二个方向是「命令环境」。
看配置里这一行：
"command": "uvx",
这是要在你的机器上执行的命令。如果这个命令在你的电脑上不存在，MCP Server 起不来。
不同的 MCP Server 依赖的命令不一样——官方这个示例用的是 uvx，别的可能用别的。
怎么确认：打开终端（Windows 用 PowerShell 或 cmd，Mac 用终端），输入那个命令看看有没有反应。提示「不是内部或外部命令」「command not found」，就说明环境里没有。
需要如实说明：官方文档没有列出各命令的安装方式与前置依赖，我们不编。遇到这种情况，以该 MCP Server 自己的官方说明为准。
一个降低踩坑概率的做法：官方在最佳实践里建议从成熟示例起步——先接入 WeCom Bot 等路径清晰的 MCP Server。第一个就挑冷门的，环境问题会成倍增加。
三、第三步：查地址
第三个方向是「地址」。以官方那个企微机器人的例子来说，就是 WECOM_WEBHOOK_URL 的值。
官方给的地址格式：
https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
逐项核对：
| 检查项 | 常见问题 |
|---|---|
| 协议头 | 是不是 https://，有没有被截成 http:// |
| 首尾空白 | 复制粘贴带进来的空格或换行，肉眼看不出来 |
| 是否完整 | 地址很长，复制时可能只选中了一部分 |
| key 参数 | ?key= 后面那串有没有缺字符 |
| 有没有换行 | 长地址在某些编辑器里会自动折行 |
首尾空白是最难发现的一个。 处理办法：把地址先粘到纯文本编辑器（记事本 / TextEdit）里看清楚，确认干净了再填进 JSON。别在两个界面之间直接来回复制。
官方在多个平台的接入指南里反复提醒过同一件事——避免带入多余空格或遗漏字符。这条对 MCP 同样适用。
四、还要确认一件事：你配到哪一级了
有一种「红灯」其实是配错了地方。官方支持两个配置级别：
| 级别 | 适用场景 | 配置文件路径 |
|---|---|---|
| 用户级 | 配置一次，所有项目复用 | ~/.workbuddy/mcp.json |
| 项目级 | 仅当前项目生效，互不影响 | <项目目录>/.workbuddy/mcp.json |
如果你把某个能力配成了项目级，那换个项目就读不到——这时候看到的「没生效」不是配置错了，是你在另一个项目里。
官方给的选择标准：频繁跨项目使用的能力（如企微机器人通知）→ 用户级；仅特定项目需要的专属服务 → 项目级。
五、排查顺序总结
1. JSON 格式 ← 官方点名优先。括号、引号（注意全角引号）、逗号
2. 命令环境 ← 终端里敲一下那个 command 看在不在
3. 地址 ← 协议头、首尾空白、是否完整（先过纯文本编辑器）
4. 配置级别 ← 用户级还是项目级，你现在在哪个项目
前三条是官方给的方向，第四条是配置机制带来的。
六、这几种情况不是 MCP 的问题
别在 MCP 配置里查一个别的问题：
- 读不了图片 / PDF / Excel / Word——官方给的原因是当前模型不支持对应文件类型，或未安装相关插件与 Skill；做法是切换模型、分步骤描述需求、在插件或技能市场安装文档处理类插件与 Skill。
- 任务卡住没响应——官方做法是点右下角「停止任务」→ 切换到其他模型 → 重新执行历史任务。
- 回复乱码、胡乱输出——官方归因为模型异常、任务过重或网络不稳定；先切模型测试、把复杂任务拆更小。
- 权限确认框拦住了操作——那是权限模式的事，不是 MCP。
七、能不能换条路
如果某个 MCP 反复配不通，先想想有没有现成的连接器能替代。
官方的连接器目前支持 QQ 邮箱、腾讯乐享、腾讯文档、TAPD、微云五个，点一下授权就能用，不用碰任何配置文件。
官方在连接器文档里也说明了两者的关系：连接器基于标准化协议（如 MCP）实现；自定义连接器的配置方式与 MCP 配置类似。
能用连接器解决的，就别花时间调 JSON。
八、还是不行怎么办
收集这些走官方反馈路径：
【MCP Server 名称】____
【配置级别】用户级 / 项目级
【配置内容】（把 mcp.json 贴上，务必把 WebHook URL 等凭证打码）
【状态】红灯
【已排查】JSON 格式 ✓ ；命令 ____ 在终端可执行 ✓/✗ ；地址已过纯文本检查 ✓
【系统】Windows ____ / macOS ____
贴配置前一定把凭证打码。 官方专门提醒过：妥善保管 WebHook URL——它是机器人调用凭证，切勿泄露。
反馈入口：客户端右上角「帮助」下拉框，或右下角头像 → 设置 - 帮助与反馈 - 意见反馈；官方支持邮箱 workbuddy@tencent.com。注意官方提示日志可能包含对话记录、设备信息等数据。
小结
- 官方状态灯：🟢 绿色可用、🔴 红色异常，需检查配置内容、命令环境或地址三个方向。
- 第一查 JSON 格式（官方点名优先）：括号、引号、逗号；特别注意替换地址时丢引号和全角引号。
- 第二查命令环境：配置里的
command（如uvx）在你机器上存不存在，终端里敲一下就知道。 - 第三查地址：协议头、首尾空白、是否完整——先过一道纯文本编辑器。
- 第四确认配置级别：用户级
~/.workbuddy/mcp.json全项目通用，项目级只在当前项目生效。 - 官方建议从成熟示例起步，第一个 MCP 别挑冷门的。
- 读不了文件、任务卡住、回复乱码都不是 MCP 的问题，别在这儿查。
- 反复配不通就看看连接器里有没有现成的（QQ 邮箱、腾讯乐享、腾讯文档、TAPD、微云）。
功能与文档表述以官方为准，核对日 2026-08-16。