Dùng `codex doctor`, `codex mcp` và `config.toml` để tự chẩn đoán Codex CLI

TL;DR: Khi Codex CLI có vấn đề, đừng đoán. Hãy chạy theo thứ tự: codex --version, codex mcp list, codex mcp get <name>, codex doctor --ascii --summary, rồi mới mở ~/.codex/config.toml. Chỉ cần 5 phút đọc đúng tín hiệu, bạn sẽ biết đây là lỗi MCP, lỗi app path, lỗi auth hay lỗi repo.

Lỗi node_repl trong hai bài trước chỉ là một ví dụ tốt để xây playbook. Điểm có giá trị lâu dài không phải mỗi câu lệnh sửa, mà là cách bạn tự phân loại lỗi Codex trong terminal.

Bộ lệnh baseline tôi dùng khi Codex CLI trục trặc

Nếu phải tạo thói quen chẩn đoán, tôi chọn bộ này:

codex --version
codex mcp list
codex mcp get node_repl
codex doctor --ascii --summary
rg -n 'mcp_servers|node_repl|command' ~/.codex/config.toml

Ý nghĩa của từng lệnh:

• codex --version: biết ngay mình đang debug phiên bản nào.
• codex mcp list: xem Codex đang cố khởi động những server nào.
• codex mcp get <name>: xem đúng command, args và env của server bị nghi ngờ.
• codex doctor --ascii --summary: lấy chẩn đoán tổng quát thay vì mò từng thành phần.
• rg vào config: xác nhận file cấu hình đang lưu gì thật sự.

Chỉ riêng chuỗi này đã giúp bạn tránh kiểu chữa bệnh bằng linh cảm.

Đọc triệu chứng theo scope, không theo cảm xúc

Một bảng nhỏ sẽ tiết kiệm rất nhiều thời gian:

Triệu chứng	Scope khả dĩ nhất	Lệnh kế tiếp
MCP startup incomplete (failed: NAME)	MCP server cục bộ	codex mcp get NAME
No such file or directory (os error 2)	path tới binary/file không còn tồn tại	codex doctor --summary rồi kiểm tra command trong config
command -v node vẫn OK nhưng node_repl fail	không phải Node hệ thống	codex mcp get node_repl
mở repo thấy build/test fail sau khi Codex đã vào được	repo/project issue	chạy test repo thay vì sửa Codex config
lỗi login/auth	tài khoản hoặc token	kiểm tra lệnh auth/login tương ứng và output doctor

Điểm mấu chốt: mỗi symptom nên kéo theo một lệnh kế tiếp cụ thể. Nếu không, bạn sẽ loop giữa nhiều giả thuyết mà không loại được giả thuyết nào.

codex doctor mạnh ở đâu?

codex doctor đáng dùng vì nó gom nhiều kiểm tra runtime vào một chỗ: config, auth, runtime health, command resolution. Với lỗi node_repl, doctor không tự sửa giúp bạn, nhưng nó giúp xác nhận rất nhanh rằng:

• server nào đang fail;
• lý do thuộc nhóm command/path hay nhóm khác;
• đây là lỗi local runtime chứ không phải source code của repo.

Khi cần output gọn để nhìn nhanh:

codex doctor --ascii --summary

Khi cần chia sẻ cho người khác hỗ trợ:

codex doctor --json

Nhưng hãy nhớ: output JSON vẫn có thể chứa metadata đáng chú ý. Đọc trước khi paste công khai.

codex mcp cho bạn sự thật về từng server

Rất nhiều người chạy codex doctor rồi dừng lại ở nhãn lỗi. Nhưng để sửa, bạn cần biết server cụ thể đang được định nghĩa ra sao.

Ví dụ với node_repl:

codex mcp get node_repl

Từ đó bạn có thể thấy:

• tên command;
• args nếu có;
• env đang gắn;
• timeout hoặc trạng thái enable/disable.

Nếu command là một đường dẫn tuyệt đối tới app bundle đã biến mất, root cause gần như lộ nguyên hình. Nếu command là một executable còn tồn tại nhưng vẫn fail, khi đó bạn mới chuyển sang nghi permission, dependency runtime hoặc env.

config.toml chỉ nên là bước xác nhận, không phải bước đoán mò

Tôi vẫn mở ~/.codex/config.toml, nhưng không mở đầu tiên. Lý do đơn giản: file config rất dễ làm người đọc suy diễn quá sớm.

Hãy dùng search hẹp:

rg -n 'node_repl|mcp_servers|command' ~/.codex/config.toml

Bạn đang tìm:

• block server tên gì;
• command trỏ đi đâu;
• có phải path tuyệt đối cũ hay không;
• có biến môi trường nào cho thấy server phụ thuộc app bundle không.

Với lỗi của series này, chính bước này xác nhận config còn giữ path dưới /Applications/Codex.app/.../node_repl, trong khi app không còn trên máy.

Phân biệt warning phụ với lỗi chính

Trong lúc chạy các lệnh help hoặc doctor, bạn có thể gặp warning kiểu liên quan tới tạo PATH aliases. Đừng vội gộp nó vào lỗi node_repl.

Quy tắc thực dụng:

• warning nhắc tới alias, shell hoặc permission tạo shortcut: xem như một chủ đề khác;
• warning nhắc trực tiếp node_repl, MCP startup, os error 2: xem như cùng chuỗi lỗi chính.

Việc tách symptom theo nhóm giúp bạn không sửa một chuyện rồi tưởng đã sửa chuyện kia.

Playbook 5 phút cho mọi lỗi Codex CLI

Khi Codex có dấu hiệu bất thường, tôi khuyên chạy theo nhịp sau:

1. codex --version
2. codex mcp list
3. codex mcp get <server-bị-nhắc-tên>
4. codex doctor --ascii --summary
5. rg -n 'tên-server|mcp_servers|command' ~/.codex/config.toml

Sau năm bước này, bạn nên trả lời được bốn câu hỏi:

• lỗi nằm ở Codex local hay trong repo?
• lỗi là do path, auth hay runtime?
• có thể bỏ server đó đi không?
• hay phải khôi phục app/runtime mà server phụ thuộc?

Nếu chưa trả lời được, lúc ấy mới đáng đào sâu hơn.

Cách giảm khả năng lặp lại lỗi

Một vài thói quen rất rẻ nhưng hữu ích:

• dùng codex mcp add/remove thay vì chỉnh tay config mỗi khi có thể;
• sau khi gỡ hoặc thay máy, chạy lại codex doctor;
• nếu gỡ Codex App, nhớ kiểm tra các MCP đang trỏ vào app bundle;
• ghi chú MCP nào là tự thêm, MCP nào do app hoặc tích hợp khác sinh ra;
• không kết luận lỗi repo chỉ vì cảnh báo xuất hiện khi đang đứng trong repo.

Đây là tư duy “local runtime first”. Nó giúp bạn không kéo project vào một cuộc chữa lỗi vốn không thuộc về project.

Đọc thêm để biến playbook thành workflow hằng ngày

Playbook này hữu ích nhất khi nó được nối với workflow AI coding rộng hơn, thay vì chỉ dùng lúc có lỗi:

• Codex CLI báo node_repl failed to start: đây là lỗi gì?
• Cách sửa MCP startup incomplete (failed: node_repl) trong Codex CLI
• Kiểm tra tình trạng PR sau merge: merged ≠ live
• Workflow 30 phút mỗi ngày: sửa bug và tạo PR với OpenCode
• Dùng OpenCode an toàn: không để AI phá repo hoặc lộ token
• Chuyên mục Công nghệ

Nếu bạn thích desktop flow hơn terminal thuần, hãy xem Codex App như một điểm kiểm tra nữa: đôi khi path MCP lỗi đơn giản là vì runtime trong app bundle đã biến mất, không phải vì repo hay shell của bạn vừa đổi.

Kết luận

codex doctor, codex mcp và ~/.codex/config.toml tạo thành một bộ ba đủ tốt để tự chẩn đoán phần lớn lỗi startup của Codex CLI. Mục tiêu không phải là thuộc lòng mọi loại lỗi, mà là luôn có trình tự kiểm tra ngắn, lặp lại được, và cho bằng chứng.

Nếu bạn mới gặp lỗi node_repl, hãy quay lại bài giải thích lỗi node_repl failed to start rồi làm theo bài hướng dẫn sửa từng bước bằng CLI. Sau series này, bạn nên có đủ khung để tự xử lý những lỗi Codex cùng họ thay vì đoán mò.