# 疑難排解

Canonical source: https://maguyva.ai/zh-hant/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 export，只有在重新載入 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 用戶端為此次請求提供預設值，或金鑰僅能存取單一儲存庫時，才可省略 repository 參數。

### MCP 連線問題

- 從你的機器測試對 https://maguyva.tools/mcp 的連線——公司代理伺服器與防火牆通常是常見的元兇。
- 確認你的 API 權杖有效且尚未過期。
- 對照你用戶端的安裝指南，重新檢查設定內容——不同用戶端的設定檔位置與格式各不相同。

### 驗證修復結果

做完任何變更之後，問你的代理「我目前連接了哪些儲存庫？」——這樣就能端到端驗證連線是否正常。接著再問一個關於你儲存庫的真實問題；你應該會看到附有檔案路徑與行號、來自你已連接儲存庫的答案。