Cách Cài Đặt Codex CLI Trên Windows, macOS, Linux (2026)
Cài xong Codex CLI trong khoảng 5 phút: một lệnh cho macOS/Linux, một lệnh PowerShell cho Windows - không bắt buộc Node.js nếu bạn dùng script cài hoặc Homebrew. Bài này có lệnh thật cho cả 3 hệ điều hành (đã chạy thử trực tiếp trên Windows), bảng cấu hình config.toml, bảng lỗi thường gặp kèm cách sửa, và FAQ - kể cả câu "cài ở Việt Nam có cần VPN không".
- Lệnh cài và đường dẫn tài liệu đã đối chiếu với tài liệu chính thức tại thời điểm viết (08/2026); domain tài liệu Codex từng đổi một lần (developers.openai.com → learn.chatgpt.com), nên kiểm tra lại docs live trước khi chạy nếu bài viết đã cũ.
Cần gì trước khi cài đặt Codex CLI?
Trước khi cài đặt Codex CLI, chuẩn bị đúng mấy thứ sau:
- Tài khoản ChatGPT có gói hỗ trợ Codex. Theo trang giá tại thời điểm viết, quyền dùng CLI rõ nhất từ gói Plus trở lên (Plus, Pro, Business, Enterprise) hoặc trả theo API key; gói Free/Go có thể chưa mở CLI - xem chi tiết ở giá Codex trước khi cài, đừng đoán.
- Hệ điều hành: Windows, macOS hoặc Linux - Codex CLI hỗ trợ native cả ba, không bắt buộc WSL2 trên Windows.
- Kết nối mạng tới chatgpt.com để tải installer và đăng nhập.
- Node.js chỉ cần nếu bạn chọn nhánh cài qua npm - hai cách còn lại (script cài, Homebrew) không đụng tới Node.
Chuẩn bị đủ bốn thứ trên, cả quá trình cài thực tế chỉ mất một lệnh và vài phút chờ tải - phần lâu hơn thường là chọn đúng tài khoản ChatGPT để đăng nhập, nhất là nếu bạn có cả tài khoản cá nhân lẫn tài khoản do công ty cấp (workspace/Business); hai loại có thể có quyền dùng CLI khác nhau.
Cài Codex CLI trên macOS và Linux
Cách nhanh nhất là script cài chính thức, dán thẳng vào terminal - nó tải về một binary native, không cần runtime nào khác:
curl -fsSL https://chatgpt.com/codex/install.sh | shHai lựa chọn thay thế nếu bạn thích quản lý qua package manager:
brew install --cask codexnpm install -g @openai/codexBẫy hay gặp nhất: tên gói npm là @openai/codex, không phải codex trơn - gõ npm install -g codex sẽ cài nhầm gói (hoặc báo lỗi 404), hai trang hướng dẫn EN mình đọc đều nhắc đúng lỗi này. Nếu chọn nhánh npm, dùng Node.js bản LTS hiện hành; các nguồn thứ cấp mình đối chiếu chưa thống nhất mốc tối thiểu chính xác, nên nếu npm báo lỗi phiên bản, cập nhật Node lên LTS mới nhất trước, hoặc né hẳn bằng script cài/Homebrew ở trên. Xem thêm README chính thức trên GitHub nếu cần đối chiếu.
Chọn cách nào? Nếu chỉ cài một lần và không quan tâm cập nhật thủ công, dùng script cài - nhanh nhất. Nếu máy bạn đã dùng Homebrew để quản lý mọi CLI khác, giữ nguyên thói quen đó cho gọn (brew upgrade sau này cũng update Codex luôn). Nhánh npm chỉ hợp nếu bạn vốn đã có Node.js cài sẵn cho việc khác - đừng cài riêng Node chỉ để chạy nhánh này.
Cài Codex CLI trên Windows
Trên Windows, mở PowerShell rồi chạy đúng lệnh sau - mình đã chạy lệnh này thật trên máy Windows của mình khi viết bài:
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"- Mở PowerShell (không cần quyền Administrator ở hầu hết máy).
- Dán nguyên lệnh trên rồi Enter.
- Cờ
-ExecutionPolicy ByPasschỉ áp dụng cho đúng phiên chạy lệnh này - không đổi policy toàn máy - nó chỉ cho phép chạy script cài (chưa ký số) trong lần gọi này. - Đóng terminal cũ, mở terminal mới để PATH vừa được thêm có hiệu lực.
- Gõ
codex --versionđể xác nhận.
Codex CLI chạy native trên Windows, không bắt buộc WSL2. Nếu team bạn đã chuẩn hoá pipeline trên WSL2 (ví dụ dùng chung script với CI Linux), bạn vẫn cài được Codex bên trong WSL2 - dùng đúng lệnh curl ở mục macOS/Linux phía trên, không có lệnh Windows riêng cho WSL2.
Nếu máy Windows của bạn do công ty quản lý (managed device, có group policy), -ExecutionPolicy ByPass đôi khi vẫn bị chặn ở tầng chính sách tổ chức chứ không phải tầng người dùng - lúc đó cần IT nới quyền, không có cách né nào ở phía người dùng. Windows Defender SmartScreen cũng có thể hỏi xác nhận lần đầu chạy installer tải về - đây là cảnh báo bình thường cho file mới, không phải dấu hiệu file hỏng.
Kiểm tra đã cài đúng chưa
Chạy codex --version. Có số phiên bản in ra là cài xong. Nếu terminal báo không nhận lệnh codex, gần như luôn là do PATH chưa nạp thư mục cài - đóng hẳn terminal (kể cả cửa sổ IDE tích hợp) và mở lại một cửa sổ mới trước khi nghi ngờ gì khác. Nếu bạn từng thử cả hai cách cài (ví dụ npm rồi lại script cài), và codex --version ra số phiên bản lạ hoặc không như mong đợi, khả năng cao có hai bản cùng nằm trên PATH - kiểm tra bằng where codex (Windows) hoặc which codex (macOS/Linux) để biết bản nào đang được gọi, rồi gỡ bản dư.
Đăng nhập Codex
Gõ codex trong terminal để mở CLI, rồi chọn mục đăng nhập bằng tài khoản ChatGPT khi được hỏi (chữ chính xác trên màn hình có thể đổi giữa các bản - làm theo hướng dẫn trên chính màn hình CLI lúc bạn chạy). Quy trình thường mở một tab trình duyệt để bạn xác nhận đăng nhập, rồi quay lại terminal là CLI đã nhận phiên - không cần dán token thủ công. Gói ChatGPT bạn dùng quyết định model và giới hạn dùng CLI ra sao; xem chi tiết ở so sánh giá các gói Codex thay vì đoán số ở đây.
Chạy lệnh Codex đầu tiên
Vào một thư mục project thật (không phải thư mục trống - Codex cần code thật để đọc và làm việc), rồi chạy:
codexThử một yêu cầu cụ thể, ví dụ: "Đọc README, liệt kê 3 cách chạy test trong repo này." Hoặc thử việc nhỏ hơn để làm quen trước: "Liệt kê 5 file lớn nhất trong repo theo số dòng." Nếu Codex cần chạy lệnh hoặc sửa file, nó sẽ dừng lại xin duyệt trước (tuỳ approval_policy đang đặt) và hiện rõ lệnh/diff sắp chạy để bạn đồng ý hoặc từ chối - đây là bước phê duyệt bình thường, không phải lỗi; xem mục cấu hình bên dưới để hiểu vì sao nó dừng và cách nới/siết mức đó.
Cấu hình cơ bản trong ~/.codex/config.toml
File cấu hình người dùng nằm ở ~/.codex/config.toml; dự án có thể override qua .codex/config.toml ở gốc repo. Thứ tự ưu tiên (cao xuống thấp, theo tài liệu cấu hình chính thức): cờ dòng lệnh (CLI flags) > .codex/config.toml của project > profile (--profile) > ~/.codex/config.toml của user. Ví dụ thực tế: nếu ~/.codex/config.toml cá nhân đặt approval_policy = "on-request" làm mặc định chung, nhưng một repo cụ thể đặt approval_policy = "untrusted" trong .codex/config.toml để siết hơn, file của project sẽ thắng mỗi khi bạn làm việc trong repo đó - còn cờ --approval-policy gõ tay lúc chạy thắng cả hai, nhưng chỉ áp dụng cho đúng lần chạy ấy.
| Key | Công dụng | Ví dụ |
|---|---|---|
model | Model mặc định cho CLI | model = "gpt-5.6" |
sandbox_mode | Mức truy cập file/network của agent | sandbox_mode = "workspace-write" |
approval_policy | Khi nào Codex dừng lại xin duyệt lệnh | approval_policy = "on-request" |
Ba key này là bộ ba đáng chỉnh đầu tiên: model quyết định chất lượng/tốc độ/chi phí, sandbox_mode quyết định Codex được đụng tới gì (tuỳ chọn còn có read-only an toàn nhất và danger-full-access nên tránh dùng mặc định), approval_policy quyết định bạn phải duyệt tay bao nhiêu lần. Gộp cả ba vào một file ~/.codex/config.toml trông như sau:
model = "gpt-5.6"
sandbox_mode = "workspace-write"
approval_policy = "on-request"Đây mới là lớp cấu hình cơ bản. Lớp tiếp theo - dạy Codex quy ước riêng của dự án (lệnh test/build, rule không được phá) - nằm ở AGENTS.md cho Codex.
Các lỗi cài đặt hay gặp và cách sửa
Phần lớn sự cố cài đặt quy về một trong bốn nguyên nhân: gõ nhầm tên gói, PATH cũ chưa refresh, chính sách chặn script mặc định của Windows, hoặc một thư mục Codex khó xác định quyền ghi. Dưới đây là từng lỗi kèm cách sửa cụ thể, thay vì kiểu "cài lại rồi hy vọng":
| Lỗi | Nguyên nhân | Cách sửa |
|---|---|---|
| npm báo 404 hoặc cài nhầm gói | Gõ npm install -g codex thay vì tên gói đúng | Dùng đúng npm install -g @openai/codex |
codex không được nhận diện / command not found | Thư mục cài chưa nằm trong PATH của phiên terminal hiện tại | Đóng hẳn và mở lại terminal mới; kiểm tra lại bằng codex --version |
| PowerShell chặn script, báo lỗi execution policy | Windows mặc định chặn script cài chưa ký số | Dùng đúng cờ -ExecutionPolicy ByPass như lệnh cài chính thức ở trên - chỉ áp dụng cho phiên đó |
| Cảnh báo sandbox/quyền ghi trên thư mục Windows | Project nằm ở thư mục Codex khó xác định quyền ghi (ví dụ thư mục đồng bộ OneDrive) | Chuyển project sang thư mục cục bộ thường, ví dụ dưới C:\Users\<ban>\projects |
Lưu ý: hai lệnh cài "curl ... | sh" khác nhau
Nếu sau này bạn thấy hướng dẫn chạy curl -fsSL https://agentkit.best/install.sh | sh, đó là một công cụ khác - AgentKit (CLI ak), một bộ kit trả phí cài thêm vào Codex hoặc Claude Code, không phải một phần của Codex. Hai lệnh trông gần giống hệt nhau (cùng dạng curl -fsSL <domain>/install.sh | sh), nên nếu bạn lưu lệnh trong ghi chú hay lịch sử terminal để dùng lại, hãy ghi rõ domain kèm theo - đừng copy nhầm hai script cho nhau.
Câu hỏi thường gặp
Cài Codex CLI có miễn phí không?
Bản thân CLI mã nguồn mở và cài miễn phí. Nhưng để đăng nhập và dùng, bạn cần tài khoản ChatGPT có gói hỗ trợ Codex (rõ nhất từ Plus trở lên theo trang giá tại thời điểm viết) hoặc trả theo API key.
Có cần API key không?
Không bắt buộc nếu bạn đăng nhập bằng tài khoản ChatGPT có gói hỗ trợ Codex. API key chỉ cần khi bạn muốn trả theo token (hữu ích cho automation/CI) thay vì dùng gói ChatGPT.
Có thể cài mà không cần Node.js không?
Có. Script cài chính thức (curl ... | sh trên macOS/Linux, PowerShell trên Windows) và Homebrew đều không cần Node.js. Chỉ nhánh npm install -g @openai/codex mới cần Node.
Windows có cần WSL không?
Không bắt buộc. Codex CLI chạy native trên Windows. WSL2 chỉ cần nếu bạn muốn dùng chung pipeline/script Linux đã có sẵn.
Cập nhật Codex CLI thế nào?
Chạy lại đúng lệnh cài ban đầu (script cài, brew upgrade, hoặc npm install -g @openai/codex tuỳ nhánh bạn dùng) sẽ ghi đè bản cũ bằng bản mới nhất.
Cài Codex CLI ở Việt Nam có cần VPN không?
Không, riêng bước cài đặt và đăng nhập không cần VPN - installer và trang đăng nhập chatgpt.com/codex đều truy cập trực tiếp được. Nếu bạn từng nghe nói phải dùng VPN, đó thường là nhầm lẫn với việc truy cập ChatGPT nói chung ở một số thời điểm/mạng cụ thể, không phải yêu cầu bắt buộc của riêng bước cài Codex CLI.
Cài xong Codex rồi - có nên thêm AgentKit không?
Codex CLI tự thân là miễn phí (đi kèm gói ChatGPT bạn đã có). AgentKit là một lớp riêng, trả phí, cài thêm vào Codex để có sẵn skills/subagents/workflow thay vì tự dựng từ đầu: ak kit init engineer --target codex --global, xác nhận màn hình preview, mở phiên Codex mới rồi gõ $ak:cook ... để bắt đầu. Không có gì trong đó đổi lệnh codex gốc bạn vừa cài - nó chỉ cho lệnh đó thêm việc có cấu trúc sẵn để chạy theo. Đây là bộ gate mình đang dùng thật trên cả Claude Code lẫn Codex, không phải quảng cáo suông - chi tiết cơ chế nằm ở AgentKit trong Codex.
Muốn có sẵn bộ workflow thay vì tự ghép từ đầu? AgentKit Engineer Kit cài trực tiếp vào Codex (và Claude Code) qua ak kit init, không đổi cách bạn dùng CLI gốc.