MCP 故障排查

快速检查

1. Weave 是否正在运行。
2. command 是否为 Weave 生成的绝对路径。
3. ZX_RUNTIME_DATA_ROOT、ZX_MCP_CLIENT_FINGERPRINT 与 ZX_MCP_BRIDGE_SECRET 是否完整。
4. 配置外层是否匹配目标 Agent：Codex 使用 TOML，Claude 常用 mcpServers，VS Code 使用 servers。
5. 保存配置后是否完全重启 Agent。
6. 当前客户端是否仍有目标知识库的授权。

常见错误

现象	处理方法
找不到 weave Server	检查配置位置和格式，然后完全重启 Agent。
RUNTIME_NOT_RUNNING	打开 Weave，确认配置来自当前安装和数据目录。
MCP client is not paired	指纹或 secret 错误、缺失或已撤销；重新配对。
能连接但没有知识库	当前客户端没有有效的知识库读取授权。
能检索但不能写入	只读连接正常；在 Weave 中单独授予对应能力。
写操作未执行	检查待确认计划；令牌可能过期或 payload 已变化。
stdio 或 JSON 错误	不要使用会向 stdout 写日志的 shell wrapper。
从 DMG 运行后路径失效	把 Weave 移到“应用程序”后重新生成配置。

收集诊断信息

报告问题时请提供 Weave 版本、操作系统、Agent 及版本、Agent 显示的 MCP 状态，以及错误发生在连接、搜索还是写入确认阶段。

不要发送真实 ZX_MCP_BRIDGE_SECRET。

macOS 日志位置：

~/Library/Logs/cloud.longde.zhixi.desktop/Weave.log