AGENTS.md cho Codex: Hướng Dẫn Cấu Hình Đầy Đủ (2026)

- Cơ chế AGENTS.md của Codex đổi khá nhanh; các chi tiết dưới đây đã đối chiếu tài liệu chính thức tại thời điểm viết (08/2026) - kiểm tra docs live trước khi phụ thuộc.

AGENTS.md làm gì trong Codex (và chuyện CLAUDE.md)

AGENTS.md là file hướng dẫn bền vững mà Codex tự nạp vào ngữ cảnh mỗi khi mở một phiên làm việc - chứa quy ước dự án, lệnh test/build, và các rule không được phá, để bạn khỏi phải lặp lại chúng trong từng prompt. Theo tài liệu chính thức learn.chatgpt.com/codex/agent-configuration/agents-md, Codex tìm và nạp các file AGENTS.md theo một cơ chế cố định - nhưng tài liệu này không hề nhắc tới CLAUDE.md ở đâu cả. Nói thẳng: hiện tại Codex không đọc CLAUDE.md - dù CLAUDE.md và AGENTS.md phục vụ cùng một ý tưởng.

Một dòng để khỏi nhầm: AGENTS.md (file cấu hình của Codex) khác AgentKit (bộ kit chạy trong Codex/Claude Code, agentkit.best) và khác OpenAI AgentKit (Agent Builder/ChatKit của OpenAI).

Nếu bạn cũng chạy Claude Code và tò mò liệu file dài có thực sự giúp ích, xem AGENTS.md vs CLAUDE.md - và liệu file dài có giúp gì không - bài đó đi sâu vào nghiên cứu; bài này tập trung vào cơ chế cấu hình của riêng Codex.

Codex tìm AGENTS.md ở đâu - đúng thứ tự tìm kiếm

Codex không đọc một file AGENTS.md duy nhất - nó đi qua nhiều cấp, theo đúng thứ tự sau (theo tài liệu chính thức):

1. Cấp global: Codex kiểm tra ~/.codex/AGENTS.override.md trước; nếu file này tồn tại, nó dùng file này thay cho ~/.codex/AGENTS.md. Nếu không có override, nó đọc ~/.codex/AGENTS.md.
2. Cấp thư mục (đi từ git-root xuống thư mục hiện tại): Codex xác định root của git repo, rồi đi xuống từng cấp thư mục cho tới cwd (thư mục bạn đang đứng chạy Codex). Ở mỗi cấp, nó lặp lại đúng quy tắc override: có AGENTS.override.md ở cấp đó thì dùng nó, không có thì dùng AGENTS.md.

Ví dụ: bạn đang ở ~/projects/shop/apps/web, git-root là ~/projects/shop. Codex sẽ tìm lần lượt: global (~/.codex/) → ~/projects/shop/AGENTS.md (git-root) → ~/projects/shop/apps/AGENTS.md (nếu có) → ~/projects/shop/apps/web/AGENTS.md (cwd). File nào không tồn tại thì bị bỏ qua, không gây lỗi.

Tác dụng thực tế của file .override.md: bạn giữ AGENTS.md dùng chung (commit vào git, cả team share) trong khi vẫn thêm chỉnh sửa cá nhân - máy riêng, sở thích riêng - vào file .override.md ở đúng cấp đó mà không đụng vào file team dùng chung.

Cần nhớ: đây không phải kiểu "file gần nhất thắng, các file khác bị bỏ qua" - toàn bộ file tìm thấy đều được gộp lại (xem phần tiếp theo), không phải chỉ chọn một file duy nhất.

Cách các file gộp lại - nối theo thứ tự root-xuống-thấp, file gần cwd thắng

Sau khi tìm xong, Codex không chọn một file - nó nối tất cả file tìm thấy lại thành một khối ngữ cảnh, theo đúng thứ tự tìm kiếm ở trên: global trước, rồi git-root, rồi các cấp thư mục con, cách nhau bằng dòng trống. Vì file càng gần cwd càng được nối vào sau cùng, nó nằm ở cuối ngữ cảnh - và khi có mâu thuẫn giữa hai chỉ dẫn, chỉ dẫn xuất hiện sau (tức gần cwd hơn) thường được agent ưu tiên làm theo.

Ví dụ 3 file, ai thắng khi mâu thuẫn:

1. ~/.codex/AGENTS.md (global): "Luôn chạy full test suite trước khi commit."
2. ~/projects/shop/AGENTS.md (git-root): "Dùng pnpm, không dùng npm."
3. ~/projects/shop/apps/web/AGENTS.md (cwd): "Chỉ chạy test unit (pnpm test:unit) khi sửa trong thư mục này - full suite quá chậm để lặp nhanh."

Ba dòng trên không loại trừ nhau hoàn toàn, nhưng dòng (3) mâu thuẫn thực tế với dòng (1). Vì (3) được nối vào sau cùng, Codex có xu hướng theo (3) khi làm việc trong apps/web. Đây chính là lý do "file gần bạn hơn" nên chứa chỉ dẫn cụ thể, còn file global/root nên chỉ giữ quy ước rộng, ổn định.

Giới hạn 32 KiB - project_doc_max_bytes

Tổng dung lượng của tất cả file AGENTS.md gộp lại (không phải từng file riêng) bị giới hạn bởi project_doc_max_bytes, mặc định 32 KiB. Theo tài liệu config nâng cao, Codex bỏ qua file rỗng và dừng thêm nội dung ngay khi tổng dung lượng chạm mức giới hạn - phần vượt ngưỡng không được nạp vào ngữ cảnh, không hề có lỗi hay cảnh báo trên TUI.

Muốn nâng giới hạn, thêm dòng này vào ~/.codex/config.toml:

project_doc_max_bytes = 65536

(con số ví dụ 65536 byte = 64 KiB; chỉnh theo nhu cầu thật, đừng chỉnh chỉ vì "để cho chắc" - file càng dài, agent càng dễ làm quá tay theo từng chỉ dẫn, xem phần ví dụ gọn ở dưới.)

Gotcha thật: cắt âm thầm khi vượt 32 KiB (một bug report có thật)

Đây là phần nhiều bài hướng dẫn khác không nhắc tới. GitHub Issue #7138 (mở 22/11/2025, đóng ở trạng thái "not planned") ghi lại đúng trường hợp: một người dùng có file AGENTS.md gộp lại khoảng 40 KB, bị Codex âm thầm cắt còn 32 KB - không một dòng cảnh báo nào trên TUI hay ở lệnh /stats. Issue còn đối chiếu với Claude Code, vốn có cảnh báo khi file ngữ cảnh vượt ngưỡng.

Lưu ý: tính tới thời điểm viết bài, issue này đã bị đóng ở trạng thái "not planned" - tức đội Codex không có kế hoạch thêm cảnh báo; kiểm tra lại trạng thái issue trước khi trích dẫn, tracker có thể đổi.

Cách né thực tế: đừng nhồi mọi quy ước vào một AGENTS.md gốc khổng lồ. Tách theo cấp thư mục - global giữ quy ước chung, mỗi thư mục con giữ đúng phần liên quan tới nó - vừa tránh chạm ngưỡng 32 KiB, vừa đúng tinh thần "file gọn, hành động được" mà nghiên cứu AGENTS.md/CLAUDE.md đã chỉ ra: file dài không giúp gì thêm, chỉ tốn chi phí.

project_doc_fallback_filenames và CODEX_HOME

Hai tham số nhỏ nhưng hữu ích nếu bạn tùy biến sâu:

• project_doc_fallback_filenames: mảng tên file thay thế mà Codex chấp nhận ở một cấp thư mục khi không có AGENTS.md ở đó - ví dụ team bạn đã có sẵn TEAM_GUIDE.md và chưa muốn đổi tên. Khai báo trong ~/.codex/config.toml: project_doc_fallback_filenames = ["TEAM_GUIDE.md"].
• CODEX_HOME: biến môi trường trỏ tới thư mục cấu hình của Codex, mặc định ~/.codex. Đây là nơi chứa config.toml, auth.json, và history.jsonl - đổi biến này nếu bạn muốn tách cấu hình Codex theo profile/máy.

Một AGENTS.md thật, ngắn gọn, dùng được ngay

Đây là AGENTS.md gốc mình đang dùng cho một repo Node/TypeScript - cố tình ngắn, vì file dài không giúp Codex làm tốt hơn (xem lại phần gotcha ở trên và bài nghiên cứu về file ngữ cảnh):

# Build & test
- Cài đặt: `pnpm install`
- Test unit: `pnpm test` - test e2e: `pnpm test:e2e` (Playwright, chạy chậm, chỉ chạy khi cần)
- Build: `pnpm build`
- Trước khi commit: `pnpm lint && pnpm typecheck`

# Không được phá
- Không đổi API public trong `src/sdk/` nếu chưa bump major version.
- Không commit file `.env*`.
- Không sửa `infra/` (Terraform) ngoài một PR đã review riêng.

# Path quan trọng
- API routes: `src/api/`
- Type dùng chung: `src/types/`
- Migration DB: `db/migrations/` (không sửa migration đã apply, luôn thêm file mới)

15 dòng. Không có "giới thiệu tổng quan dự án", không văn xuôi giải thích lý do. Mỗi dòng là một lệnh chạy được hoặc một rule cấm cụ thể - đúng phần agent thực sự làm theo, theo dữ liệu nghiên cứu ở bài AGENTS.md vs CLAUDE.md.

AGENTS.md đặt luật chơi - AgentKit thêm bộ kỹ năng

AGENTS.md là cấu hình miễn phí, Codex tự đọc, không cần cài thêm gì. Nó trả lời câu "phải làm gì / không được làm gì". Nhưng nó không mang theo skill/workflow đóng gói sẵn - đó là phần AgentKit (agentkit.best, CLI ak) thêm vào, chạy trên nền Codex chứ không thay thế AGENTS.md.

Cài kit cho Codex: ak kit init engineer --target codex --global (thêm --global để dùng ở mọi repo), rồi trong một phiên Codex mới gõ $ak:cook ... để chạy (lưu ý cú pháp $ak: ở Codex, khác /ak: ở Claude Code - Codex delivery hiện là native-only: skills, rules, agent dispatch, hooks một phần; kit command chưa hoạt động, không có status line).

Nói thẳng ranh giới free/trả phí: AGENTS.md không tốn tiền. AgentKit là add-on trả phí (Engineer Kit khoảng $99, cửa hàng hay có giảm -20% còn khoảng $79.20 tại thời điểm viết - kiểm tra giá live). Nếu bạn mới làm quen Codex, xem Codex là gì trước; muốn hiểu SKILL.md (khác AGENTS.md, là năng lực nạp theo nhu cầu chứ không phải context luôn nạp), xem Codex Skills là gì; muốn xem cách dùng AgentKit trong Codex, xem AgentKit trong Codex.

Câu hỏi thường gặp (FAQ)

Codex có đọc CLAUDE.md không?

Không. Theo tài liệu chính thức, Codex chỉ tìm và nạp file AGENTS.md (cùng AGENTS.override.md) - không có cơ chế nào đọc CLAUDE.md. Nếu bạn chạy cả Claude Code lẫn Codex trên cùng repo, cần giữ cả hai file (hoặc symlink một file sang tên kia).

Giới hạn dung lượng AGENTS.md trong Codex là bao nhiêu?

Mặc định 32 KiB cho tổng tất cả file AGENTS.md gộp lại (không phải từng file riêng), qua tham số project_doc_max_bytes. Vượt ngưỡng bị cắt âm thầm, không có lỗi hay cảnh báo. Có thể nâng giới hạn trong ~/.codex/config.toml.

Nếu có AGENTS.md ở cả global, repo-root và thư mục con, file nào thắng?

Không có file nào "thắng" theo nghĩa loại trừ - Codex gộp tất cả lại theo thứ tự global → git-root → xuống tới thư mục hiện tại. Vì file gần thư mục hiện tại được nối vào sau cùng, chỉ dẫn của nó thường được ưu tiên khi có mâu thuẫn.

AGENTS.override.md dùng để làm gì?

Khi có mặt ở một cấp (global hoặc một thư mục), AGENTS.override.md được Codex dùng thay cho AGENTS.md ở đúng cấp đó. Hữu ích để giữ AGENTS.md dùng chung cho cả team trong git, còn thêm chỉnh sửa riêng vào file override mà không đụng bản chung.

Codex có cảnh báo khi AGENTS.md quá dài không?

Không, ít nhất tính tới thời điểm viết. GitHub Issue #7138 ghi lại trường hợp file 40 KB bị cắt còn 32 KB mà không có cảnh báo trên TUI, và đã bị đóng ở trạng thái not planned. Ngược lại, Claude Code có cảnh báo khi file ngữ cảnh vượt ngưỡng - đây là khác biệt đáng nhớ.

Codex lưu cấu hình ở đâu?

Trong thư mục CODEX_HOME, mặc định ~/.codex - chứa config.toml, auth.json và history.jsonl. Có thể đổi biến môi trường CODEX_HOME để dùng thư mục khác.

Kết luận

Cơ chế AGENTS.md của Codex gói gọn trong ba điều cần nhớ: thứ tự tìm cố định (global → git-root → cwd), gộp root-xuống-thấp với file gần bạn hơn được ưu tiên, và trần 32 KiB âm thầm cắt phần dư - không CLAUDE.md nào được đọc ở đây cả. Viết file gọn, tách theo thư mục thay vì nhồi một file khổng lồ, và bạn né được cả gotcha lẫn chi phí thừa. Muốn hiểu sâu hơn vì sao file dài không giúp gì, xem AGENTS.md vs CLAUDE.md - và liệu file dài có giúp gì không.