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 bạn đã nhập (với Gemini, cả client secret). Copy passphrase 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.

Tool bị từ chối: thiếu hoặc hết hạn rule receipt

Mọi tool có thể thực hiện thao tác đều cần rule receipt hiện hành do aki__akidevrule_context trả về. Mã từ chối cho biết trường hợp nào: RULE_RECEIPT_MISSING (không gửi), INVALID (không phải sha256: cộng 64 ký tự hex), UNKNOWN (chưa từng cấp từ lúc server khởi động), STALE (file rule đã đổi từ đó) hoặc UNCHECKED (không đọc được rule).

1. 1Thông báo từ chối có sẵn cách sửa: call aki__akidevrule_context (without knownReceipt if the rules are no longer in your context), then call this tool again with receipt=<the sha256:… it returns>. Hãy nhờ AI làm đúng như vậy.
2. 2Sau khi khởi động lại akimcp hoặc sửa file rule, các receipt cũ chuyển thành UNKNOWN hoặc STALE: hãy lấy receipt mới.
3. 3Tool thao tác trên một project có CLAUDE.md, AGENTS.md hoặc GEMINI.md có thể trả về rule của project cùng receipt mới thay vì chạy ngay. Đó không phải lỗi: gọi lại với receipt mới.
4. 4Nếu tool hoàn toàn không có tham số receipt, chat đang giữ schema cũ: kết nối lại akimcp hoặc mở chat mới.

Một lệnh gọi lỗi -32602 (tham số không hợp lệ)

Chat giữ nguyên schema tool đã tải. Sau khi cập nhật, nó có thể gửi tham số mà schema mới không còn nhận, và giao thức trả về -32602. Lỗi nay cho biết đó là trường hợp nào.

1. 1Nếu thông báo có dạng <tool> takes no <argument>; its arguments are …, tên tham số không thuộc phiên bản này: dùng một tên trong danh sách nó in ra.
2. 2Nếu thông báo kết thúc bằng tool schema is stale; reconnect AkiMCP or start a new chat, mọi tham số đều hợp lệ với server đang chạy nhưng không khớp schema mà chat đã lưu. Kết nối lại akimcp trong client, hoặc mở chat mới, rồi thử lại.
3. 3Cập nhật từ 2.2 lên 3.0.x: hãy kết nối lại akimcp trong từng client một lần, vì định nghĩa tool đã đổi ở 3.0.0 và Claude sẽ hỏi “Always allow” lại cho các tool đó. Cập nhật 3.0.0 lên 3.0.1 chỉ cần khởi động lại: định nghĩa tool giữ nguyên.

chrome_launch lỗi no_profile

Profile trình duyệt nằm trong ~/.aki/cdp/profiles/<browser>-<profile>/ và chỉ ứng dụng AIObox (tùy chọn) mới tạo chúng. chrome_launch chỉ mở hoặc gắn vào profile có sẵn, không bao giờ tạo hay sao chép. Lỗi có dạng Profile "chrome-profile-14" not found in … AkiMCP opens existing shared profiles and does not create them. (no_profile; next: …).

1. 1Dùng một id mà lỗi liệt kê sau open one of, hoặc truyền tên thư mục như Profile 14. chrome_profiles cũng liệt kê các id dùng chung.
2. 2Chưa có profile dùng chung? Hãy gắn vào Chrome đang chạy: tìm cổng của một Chrome chạy với remote-debugging port bằng aki__port_status, chạy aki__devtools_targets trên cổng đó, khớp tab theo title hoặc url, rồi truyền rõ cổng đó cùng targetId.
3. 3Thư mục cũ ~/.aki/mcpsv/chrome-clones không còn được đọc và có thể xóa, tham số refresh cũng đã bị bỏ.

Lệnh gọi trình duyệt kết thúc với “code timeout” sau 50 giây

Client bỏ cuộc với một lệnh gọi tool sau khoảng một phút và khi đó không hiện gì, nên mọi lệnh gọi CDP (devtools_eval, devtools_screenshot, devtools_targets, yêu cầu về tab, postman_eval) đều kết thúc trong 50 giây, tính cả bước tìm target và kết nối. Tab bị treo hoặc bị ẩn, script không bao giờ trả về, hay endpoint không phản hồi đều chạm giới hạn này.

1. 1the page did not answer within 50s (the tab is frozen, or the script is still running): script có thể đã chạy. Kiểm tra bằng một biểu thức chỉ-đọc ngắn trước khi chạy lại. Vẫn không có phản hồi nghĩa là tab đang treo, hãy tự tải lại hoặc đóng tab đó.
2. 2the page gave no screenshot within 50s (the tab is frozen or hidden): thử lại một lần. Vẫn không có ảnh nghĩa là tab đang treo hoặc bị ẩn: hiện tab lên hoặc tải lại.
3. 3the CDP endpoint host:port did not answer within 50s: kiểm tra ứng dụng còn chạy bằng aki__port_status, rồi thử lại một lần. Từ 3.0.1, thông báo này cũng áp dụng khi lệnh hết giờ lúc còn đang liệt kê tab hoặc kết nối: chưa có gì chạy, nên không cần kiểm tra tác dụng phụ. Bản 3.0.0 có thể báo “script có thể đã chạy” trong trường hợp đó.

Task nền hoặc Postman không khởi động

aki__task_start và nút Launch Postman trong panel báo lỗi kèm mã lỗi hệ thống của lần khởi động thất bại, còn server vẫn chạy. Trước 3.0.1, task khởi động thất bại làm sập cả server, còn Postman khởi chạy thất bại làm thoát tiến trình trợ giúp Postman, nên hãy cập nhật nếu bạn gặp tình huống ấy.

1. 1Failed to spawn background task process: ENOENT: thư mục làm việc hoặc chương trình không tồn tại. Kiểm tra cwd bạn truyền và chương trình đã cài, nằm trong PATH của server.
2. 2Failed to spawn background task process: EACCES: chương trình có nhưng không chạy được. Sửa quyền của file hoặc trỏ tới đúng file thực thi.
3. 3Failed to launch Postman: ENOENT hoặc EACCES: cài Postman, hoặc sửa quyền file chạy của nó, rồi bấm Launch Postman lại.
4. 4Lệnh bị từ chối trước khi thử khởi động là trường hợp khác: xem mục “Một lệnh bị từ chối” trên trang này.

Thiếu một tool, hoặc lệnh gọi báo tool bị disabled

Tool của ứng dụng chưa cài thì không được phục vụ, và provider tùy chọn có thể bị tắt. agy và Kiro CLI mặc định tắt, vì mỗi cái giao cả một tác vụ cho một agent trả phí khác. Rule context, file, search và shell luôn bật.

1. 1Mở mục 8 của panel (Tool providers). Provider thiếu ứng dụng sẽ hiện lý do: agy is not on PATH, kiro-cli is not on PATH, Postman app not found, no Chromium browser installed (Chrome, Brave, Edge), hoặc không có thư mục ~/.aki/aiobox/ cho các tool AIObox tùy chọn.
2. 2Cài ứng dụng, rồi bấm Detect again. Không cần khởi động lại.
3. 3Với agy và Kiro CLI, hãy bật provider ngay trong mục đó.
4. 4Công tắc có hiệu lực ngay trên server, nhưng client chỉ thấy khi lấy danh sách tool lần sau: mở chat mới hoặc kết nối lại connector. Trước đó, gọi một tool đang ẩn sẽ lỗi với thông báo tool bị disabled.

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.