# 故障排查

Canonical source: https://maguyva.ai/zh-hans/docs/troubleshooting

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

修复 Maguyva 常见的配置故障：API 密钥问题、@maguyva/mcp 桥接问题、仓库查找问题和连接错误。

### API 密钥问题

- 确认你的密钥以 mgv_ 前缀开头。
- 检查你是否已经把配置示例中的 mgv_xxxx 占位符替换成了从 app.maguyva.ai 获取的真实密钥。
- 如果你的配置是从 MAGUYVA_API_KEY 读取密钥的，请确认该变量在你的客户端实际启动的环境中已经设置好。添加到 ~/.zshrc 或 ~/.bashrc 中的 shell 导出，只有在重新加载 shell 之后才会生效，而且 GUI 应用可能完全不会继承它们。如果拿不准，就把密钥直接写进配置里：原生远程配置写在 Authorization 请求头中（Bearer 后接你的密钥），@maguyva/mcp 桥接配置则写在 env 块中。
- 确认密钥没有过期或被吊销。

### @maguyva/mcp 桥接问题

- 确认 npx 在你的 PATH 中可用 -- 桥接程序需要一个可正常工作的 Node.js 安装。在终端里运行 npx -y @maguyva/mcp --help，确认它能够启动。
- 检查你的客户端 MCP 配置语法 -- 在某些客户端中，格式错误的 JSON 文件会静默失败。
- 很多客户端根本不需要桥接程序。Claude Code 使用 Maguyva 插件（/plugin install maguyva@maguyva），Cursor、VS Code、Devin Desktop 和 Zed 则原生地通过 Bearer 请求头连接远程服务器（Zed 通过 context_servers）。桥接程序适用于无法从配置中发送该请求头的客户端，例如 Claude Desktop：它的 claude_desktop_config.json 只能启动本地服务器。Claude Desktop 的自定义连接器可以发送 authorization 请求头，但请求头功能目前仍在测试阶段，仅对少数组织开放。

### 找不到仓库

- 确认该仓库已经在 app.maguyva.ai 中连接并完成索引。
- 检查格式：“owner/repo” 指向默认分支，“owner/repo:branch” 指向指定分支（例如 “owner/repository:develop”）。
- 确认你的账户有权限访问该仓库。
- 使用 repository_context(action="info", repository="...") 检查仓库名称的解析结果；仅当 MCP 客户端提供请求默认值，或密钥恰好只能访问一个仓库时，才省略仓库参数。

### MCP 连接问题

- 从你的机器测试到 https://maguyva.tools/mcp 的连通性 -- 公司代理和防火墙通常是罪魁祸首。
- 检查你的 API 令牌是否有效、是否已过期。
- 对照你所用客户端的安装指南，重新检查客户端配置 -- 配置文件的位置和格式因客户端而异。

### 验证修复结果

每次改动之后，都问一下你的智能体“我连接了哪些仓库？”-- 这样能端到端地验证连接是否正常。然后再问一个关于你仓库的真实问题；你应该会看到来自已连接仓库的、带有文件路径和行号的答案。