Xử lý sự cố
Xử lý sự cố Aki MCP Server
Các lỗi hay gặp và cách sửa, mỗi lỗi theo thứ tự triệu chứng, nguyên nhân, cách sửa. Lỗi kết nối thường nằm ở địa chỉ công khai hoặc bước đăng nhập, không phải lỗi trong code của bạn.
Gặp từ chưa biết? Những từ bạn sẽ gặp
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Đừng test bằng
curl https://your-hosttrần từ chính máy chạy server: nó đi đường tắt mesh nội bộ. - 2Test đường công khai thật bằng
dig @8.8.8.8 your-host A +shortrồicurl --resolve your-host:443:<IP> https://your-host/.well-known/oauth-authorization-server. - 3Nếu timeout dù báo “on”, sao chép Re-sync command trong phần hướng dẫn Tailscale của panel và chạy nó trong terminal (cần
sudo) để ép đẩy lại cấu hình. Từ bản 4.1, lệnh kết thúc bằng đúng cổng server của bạn đang nghe, không phải lúc nào cũng là 9999.
“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.
- 1Chờ 15 phút, hoặc mở mục “Security & connection limits” của panel và bấm Release cạnh người gọi bị chặn.
- 2Kiểm tra lại passphrase bạn đã nhập. Copy nó từ panel (bấm nút con mắt để hiện).
- 3Nếu bạn vẫn chạm ngưỡng dù dùng đúng, hãy nâng các con số ở mục “Security & connection limits” của panel.
AI trên web không đăng nhập xong được
AkiMCP chỉ trả lần đăng nhập về địa chỉ nó biết. Lần bị từ chối trả về invalid_redirect_uri kèm một dòng chỉ chỗ để thêm địa chỉ, lý do không thêm được, hoặc cho biết AI không gửi địa chỉ nào.
- 1Mở mục “Connectors” của panel → Web · needs ingress → Other AI (sign-in). Nếu địa chỉ của AI hiện dưới Refused since AkiMCP started, bấm Add, rồi kết nối lại và nhập passphrase.
- 2Địa chỉ hiện lý do thay vì nút (http, localhost, địa chỉ IP) thì không thêm được: AI phải đăng nhập qua một địa chỉ https công khai.
- 3Không có gì trong danh sách bị từ chối? AI chưa hề tới được AkiMCP: kiểm tra địa chỉ công khai còn chạy (xem trang Bắt đầu) và connector dùng đúng MCP URL lấy từ panel.
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 “Allowed shell commands” của panel 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épgittrầ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), EVICTED (đã rơi khỏi 200 receipt server giữ), STALE (file rule đã đổi từ đó) hoặc UNCHECKED (không đọc được rule).
- 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. - 2Sau khi khởi động lại akimcp hoặc sửa file rule, các receipt cũ chuyển thành
UNKNOWNhoặcSTALE. Receipt bị bỏ không trong lúc 200 receipt mới hơn được cấp hoặc được dùng sẽ thànhEVICTED; receipt mà chat còn dùng thì vẫn còn hiệu lực. Trường hợp nào cũng vậy: hãy lấy receipt mới. - 3Tool thao tác trên một project có
CLAUDE.md,AGENTS.mdhoặcGEMINI.mdcó 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. - 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.
- 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. - 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. - 3Cập nhật từ 2.2 lên 3.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 từ 3.0.x lên 3.1.0: khởi động lại, rồi kết nối lại một lần để client thấy tham số session file mới. Cập nhật lên 4.1.0: kết nối lại một lần, và Claude hỏi “Always allow” lại cho mọi tool nhận receipt cùng sáu tool khác. Cập nhật lên 4.2.0: kết nối lại một lần để client thấy mô tả mới của sqlite_query.
chrome_interact không gõ, hoặc chrome_stop trả lời stopped: false
Từ bản 4.2, cả hai tool báo đúng chuyện đã xảy ra thay vì luôn trả lời thành công.
- 1
Element <div> is not a text field: typing needs an input or textarea: selector đang trỏ vào nút, ô chọn hay một phần tử thường. Hãy trỏtypevào chínhinputhoặctextarea. - 2
stopped: falsekèmits Chrome is already gone: Chrome đó đã đóng từ trước, nên không có tín hiệu nào được gửi và phiên của nó đã được xóa. Không cần làm gì thêm. - 3
stopped: falsekèmcould not check whether its Chrome is still running: AkiMCP không xác nhận được tiến trình đó là Chrome của nó, nên để yên. Tự đóng cửa sổ, hoặc truyềnpidcủa nó chochrome_stopnếu bạn chắc chắ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: …).
- 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_profilescũng liệt kê các id dùng chung. - 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ạyaki__devtools_targetstrên cổng đó, khớp tab theo title hoặc url, rồi truyền rõ cổng đó cùng targetId. - 3Thư mục cũ
~/.aki/mcpsv/chrome-cloneskhông còn được đọc và có thể xóa, tham sốrefreshcũng đã bị bỏ.
chrome_launch trả lời aiobox_running
Từ bản 4.1, khi ứng dụng AIObox đang chạy, chrome_launch không mở cũng không gắn vào gì, để AI không thể thao tác từ một profile đăng nhập tài khoản khác. Câu trả lời nêu một bước tiếp theo.
- 1Nhờ AI làm đúng như câu trả lời:
aki__aiobox_write op=open_url url=<link> profileId=<id>mở link từ cửa sổ AIObox thay vào đó. - 2Không có cờ ép chạy. Muốn tự khởi chạy profile, hãy tắt AIObox trước; khi không có AIObox, hoặc
aki__aioboxbị tắt trong panel,chrome_launchchạy như trước. - 3AIObox đã tắt mà vẫn nhận câu trả lời này? AkiMCP chỉ coi nó đang chạy khi tiến trình ghi trong
~/.aki/aiobox/cdp/windows.jsoncòn sống. Trong trường hợp hiếm khi một chương trình khác dùng lại process ID đó, hãy mở AIObox và mở link từ cửa sổ của nó.
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
the 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
the 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
the CDP endpoint host:port did not answer within 50s: kiểm tra ứng dụng còn chạy bằngaki__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
Failed 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 tracwdbạn truyền và chương trình đã cài, nằm trongPATHcủa server. - 2
Failed 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
Failed to launch Postman: ENOENThoặcEACCES: cài Postman, hoặc sửa quyền file chạy của nó, rồi bấm Launch Postman lại. - 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.
- 1Mở mục “Tool providers” của panel. 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. - 2Cài ứng dụng, rồi bấm Detect again. Không cần khởi động lại.
- 3Với
agyvà Kiro CLI, hãy bật provider ngay trong mục đó. - 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.
ClickUp báo “Connection request invalid”
ClickUp giữ client ID mà nó đăng ký lần đầu. Khi AkiMCP đã quên đăng ký đó (Remove only, Revoke & roll, hoặc lần đăng nhập không được duyệt trong một giờ), các bản trước 3.3.1 từ chối ID cũ và không còn đường nào khác.
- 1Cập nhật AkiMCP lên 3.3.1 trở lên bằng lệnh cài, rồi khởi động lại.
- 2Kết nối lại từ ClickUp và nhập passphrase. AkiMCP nhận lại ID cũ và ghi nó ở mục “Security & connection limits” của panel là
MCP client.
Sau khi đổi tên, app không thấy tool hoặc vẫn thấy tool cũ
Server ID hay Tool prefix mới đổi tên mọi tool, và mỗi app giữ danh sách nó đã tải.
- 1Khởi động lại AkiMCP sau khi bấm Save name.
- 2Kết nối lại ở từng app. Ở Claude Code, Codex, Cursor và AGY, bấm Apply. Với connector web, gõ Display name mới làm tên của nó.
- 3Trong Claude, cho phép lại từng tool (Always allow), rồi mở chat mới.
Nghi ngờ bí mật đã bị lộ
Mở control panel và roll thứ bí mật đã bị lộ.
- Passphrase:
Roll passphrase, rồiRoll & 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. - Sau khi roll token: Cursor, Claude Code và Codex nhận token mới qua nút Apply ở tab của chúng trong panel; JSON của Postman (hay của Any MCP app) và header của Buda thì dán lại. App AI trên web đăng nhập bằng passphrase tự làm mới, trừ ClickUp phải kết nối lại một lần. App Claude và AGY không dùng 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.