# Khắc phục sự cố

Canonical source: https://maguyva.ai/vi/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).

Khắc phục các lỗi cài đặt Maguyva thường gặp: sự cố khóa API, lỗi cầu nối @maguyva/mcp, tra cứu repository, và lỗi kết nối.

### Sự cố khóa API

- Kiểm tra key của bạn có bắt đầu bằng tiền tố mgv_ không.
- Kiểm tra bạn đã thay placeholder mgv_xxxx trong các ví dụ cấu hình bằng key thật của bạn từ app.maguyva.ai chưa.
- Nếu cấu hình của bạn đọc key từ MAGUYVA_API_KEY, hãy xác nhận biến đó đã được thiết lập trong môi trường mà client của bạn thực sự khởi chạy từ đó. Các export shell thêm vào ~/.zshrc hoặc ~/.bashrc chỉ có hiệu lực sau khi reload shell, và các ứng dụng GUI có thể không kế thừa chúng chút nào. Nếu không chắc, hãy ghi key trực tiếp vào cấu hình: trong header Authorization của cấu hình kết nối từ xa trực tiếp (Bearer rồi đến key của bạn), hoặc trong khối env của cấu hình dùng cầu nối @maguyva/mcp.
- Đảm bảo key chưa hết hạn hoặc bị thu hồi.

### Sự cố cầu nối @maguyva/mcp

- Kiểm tra npx có sẵn trong PATH của bạn không -- cầu nối cần một bản cài đặt Node.js hoạt động được. Chạy npx -y @maguyva/mcp --help trong terminal để xác nhận nó có thể khởi động.
- Kiểm tra cú pháp cấu hình MCP của client -- một file JSON sai định dạng sẽ thất bại âm thầm ở một số client.
- Nhiều client không cần cầu nối chút nào. Claude Code dùng plugin Maguyva (/plugin install maguyva@maguyva), còn Cursor, VS Code, Devin Desktop, và Zed kết nối tới server từ xa trực tiếp bằng header Bearer (Zed thông qua context_servers). Cầu nối dành cho các client không thể gửi header đó từ cấu hình của mình, chẳng hạn Claude Desktop, vốn có claude_desktop_config.json chỉ khởi chạy server cục bộ. Connector tùy chỉnh của Claude Desktop có thể gửi request header authorization, nhưng request header đang ở giai đoạn beta cho một số tổ chức giới hạn.

### Không tìm thấy repository

- Xác nhận repository đã được kết nối và lập chỉ mục trong app.maguyva.ai.
- Kiểm tra định dạng: "owner/repo" nhắm vào nhánh mặc định, "owner/repo:branch" nhắm vào một nhánh cụ thể (ví dụ "owner/repository:develop").
- Đảm bảo tài khoản của bạn có quyền truy cập repository.
- Dùng repository_context(action="info", repository="...") để kiểm tra cách repository được phân giải; chỉ bỏ tham số repository khi MCP client của bạn cung cấp mặc định theo từng yêu cầu hoặc khi khóa có thể truy cập đúng một repository.

### Sự cố kết nối MCP

- Kiểm tra kết nối tới https://maguyva.tools/mcp từ máy của bạn -- proxy công ty và firewall thường là thủ phạm.
- Kiểm tra API token của bạn còn hợp lệ và chưa hết hạn.
- Kiểm tra lại cấu hình client so với Hướng dẫn cài đặt dành cho client của bạn -- vị trí và định dạng file cấu hình khác nhau tùy client.

### Xác minh bản sửa lỗi

Sau bất kỳ thay đổi nào, hãy hỏi agent của bạn "Tôi đang kết nối những repository nào?" -- điều đó xác minh kết nối từ đầu đến cuối. Sau đó hãy đặt một câu hỏi thật về repo của bạn; bạn sẽ thấy các câu trả lời kèm đường dẫn file và số dòng từ repository đã kết nối.