Xử lý sự cố Aki MCP Server

Claude không kết nối dù Funnel báo “on”

Cấu hình serve có thể lưu cục bộ nhưng không đồng bộ lên Tailscale, nên client thật bị chặn ở TLS trong khi máy của bạn thấy mọi thứ vẫn ổn.

1. 1Đừng test bằng curl https://your-host trần từ chính máy chạy server: nó đi đường tắt mesh nội bộ.
2. 2Test đường công khai thật bằng dig @8.8.8.8 your-host A +short rồi curl --resolve your-host:443:<IP> https://your-host/.well-known/oauth-authorization-server.
3. 3Nếu timeout dù báo “on”, chạy lại tailscale funnel --bg 9999 để ép đẩy lại cấu hình.

“Wrong token” hoặc panel 403 khi chạy lần hai

Trước đây chạy lần hai sẽ tranh cổng với instance đang chạy. Nay server tái sử dụng panel đang chạy khi trùng version, hoặc dừng bản cũ trước.

• Đảm bảo bạn đang dùng bản hiện tại. Nếu tab panel cũ còn mở, tải lại từ instance vừa khởi chạy.

Cổng đang bận (EADDRINUSE)

• Gatekeeper dùng cổng cố định 9999; xung đột thật sự nay sẽ nêu nguyên nhân. Giải phóng cổng hoặc dừng tiến trình kia.
• Panel tự động chuyển sang cổng trống kế tiếp nếu 9998 bị chiếm.

Client bị 429 sau khi nhập sai thông tin

5 thông tin xác thực bị từ chối trong 60 giây sẽ chặn người gọi 15 phút. Bearer token hợp lệ không bao giờ bị chặn, nên kết nối đang chạy không bị ảnh hưởng.

1. 1Chờ 15 phút, hoặc mở mục 7 của panel và bấm Release cạnh người gọi bị chặn.
2. 2Kiểm tra lại passphrase hoặc client secret bạn đã nhập. Copy từ panel (bấm nút con mắt để hiện).
3. 3Nếu bạn vẫn chạm ngưỡng dù dùng đúng, hãy nâng các con số ở mục 7 (Connection limits).

Một lệnh bị từ chối

• Thông báo nêu lý do và các subcommand được phép. Thêm lệnh ở mục 6 của panel (Shell allowlist) nếu bạn tin nó.
• Các dạng ghi của git (branch -D, tag -d, remote set-url, --output=) bị từ chối có chủ đích. Tự chạy chúng, hoặc cho phép git trần và chấp nhận rằng khi đó mọi thứ đều được phép.

Nghi ngờ bí mật đã bị lộ

Mở control panel và roll thứ bí mật đã bị lộ.

• Passphrase: Roll passphrase, rồi Roll & sign out all clients.
• Access token: Roll & sign out all clients, rồi kết nối lại từng AI bằng passphrase.
• Cấu hình local (Cursor, Claude Code, Codex, Postman) cần dán lại token mới sau mỗi lần roll token.

Gemini kết nối nhưng không dùng tool

• Đây là giới hạn đã biết: OAuth thành công nhưng phát hiện tool chưa ổn. Dùng Claude, Grok hoặc ChatGPT cho công việc thật lúc này.