Cài Đặt Codex CLI Trên Windows, macOS, Linux Năm 2026

Cài đặt Codex CLI mất khoảng 5 phút trên macOS, Windows 11 native, Linux, hoặc WSL2. Tool open-source của OpenAI tải về free từ npm (npm install -g @openai/codex) hoặc Homebrew (brew install --cask codex) hoặc binary trực tiếp từ GitHub Releases. Yêu cầu duy nhất là Node.js 18+ và tài khoản ChatGPT Plus, Pro, Business để authenticate.

Bài này hướng dẫn chi tiết từng OS với lệnh thực tế đã test, cộng với 5 lỗi thường gặp mình từng gặp khi setup trên 3 máy khác nhau (MacBook M2, Windows 11 desktop, Ubuntu VPS). Reader chưa biết Codex CLI là gì có thể đọc trước bài Codex CLI là gì, sau đó quay lại đây làm bước cài đặt.

Cài Đặt Codex CLI Cần Pre-Install Gì? Yêu Cầu Hệ Thống Ra Sao?

Pre-install checklist gồm 3 thứ chính. Một là Node.js 18 trở lên, kiểm tra bằng lệnh node --version trong terminal. Recommend Node 20 LTS hoặc 22 cho stability tốt nhất. Nếu chưa có Node, cài qua nvm (Node Version Manager) là cách an toàn nhất vì tránh quyền root và dễ switch version khi cần.

Hai là tài khoản ChatGPT: Free / Plus / Pro / Business / Enterprise đều dùng được, nhưng Free tier có rate limit chặt (khoảng 50 message mỗi 3 giờ) nên không phù hợp daily workflow. Plus $20/tháng là sweet spot cho solo dev, Pro $200 cho heavy user. Subscription thanh toán qua Visa / Mastercard quốc tế từ ngân hàng VN đều work.

Ba là disk space và RAM: Codex CLI viết 96% bằng Rust nên footprint nhỏ, khoảng 80MB RAM session bình thường, 100MB disk cho install. Yêu cầu OS tối thiểu: macOS 12+ (Apple Silicon hoặc Intel), Windows 11 (Windows 10 phiên bản 1809+ vẫn chạy nhưng kém ổn định), Linux kernel 5.10+ với glibc hiện đại.

Cài Codex CLI Trên macOS (Apple Silicon Và Intel) Ra Sao?

Trên macOS, cách nhanh nhất là dùng Homebrew. Lệnh duy nhất:

# macOS , Homebrew (recommended)
brew install --cask codex

# Verify install
codex --version
# Output: codex 0.131.0

# Chạy session đầu tiên
cd ~/your-project
codex

Homebrew tự handle Apple Silicon (ARM) và Intel binary, không cần chọn architecture. Nếu chưa cài Homebrew, lệnh setup tại brew.sh chạy 1 dòng trong Terminal.

Cách thay thế qua npm nếu không muốn Homebrew:

# macOS , npm
# Cài Node qua nvm trước nếu chưa có
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
source ~/.zshrc
nvm install 22

# Sau đó cài Codex CLI
npm install -g @openai/codex
codex --version

Test trên MacBook M2 Pro ongboit: cài Homebrew xong, lệnh brew install --cask codex mất 1 phút 30 giây download và setup. Tổng pre-install + install + first auth khoảng 4 phút 30 giây.

Cài Codex CLI Trên Windows 11 Native + WSL2 Như Thế Nào?

Windows 11 hỗ trợ 2 path: WSL2 (recommended cho production / dev nghiêm túc) hoặc native PowerShell (experimental, dễ thử nhưng có sandbox edge case). Theo Codex CLI Windows setup guide, OpenAI vẫn label Windows native là experimental, khuyến nghị WSL2 cho workflow chính. Native nhanh setup nhưng có edge case sandbox elevated + missing optional binary dep (xem Lỗi 6, 7 phía dưới). Beginner chưa cần serious production có thể start native, dev workflow nặng nên skip thẳng xuống WSL2.

Native PowerShell:

# Windows 11 , PowerShell native
# 1. Cài Node.js qua winget
winget install OpenJS.NodeJS.LTS

# 2. Restart PowerShell, verify
node --version

# 3. Cài Codex CLI
npm install -g @openai/codex

# 4. Run lần đầu (cần admin để setup sandbox elevated)
codex

Sau khi chạy codex lần đầu, tool yêu cầu admin permission để setup Windows sandbox elevated mode. Nếu không có admin quyền hoặc setup fail, Codex tự fallback về unelevated mode (sandbox yếu hơn nhưng vẫn chạy được). Setting này lưu trong ~/.codex/config.toml dưới section [windows].

WSL2 fallback nếu native sandbox không work hoặc bạn quen Linux:

# Windows 11 , WSL2 (alternative)
# Mở PowerShell admin
wsl --install

# Sau khi reboot, mở WSL Ubuntu
wsl

# Trong WSL shell, cài Node qua nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
source ~/.bashrc
nvm install 22

# Cài Codex CLI
npm install -g @openai/codex
codex

Tip quan trọng cho WSL2: đặt project code trong ~/code/ (Linux home directory), KHÔNG trong /mnt/c/ (Windows filesystem mount). Performance khác biệt rõ, đặc biệt với project có nhiều file (như Next.js node_modules), tốc độ I/O trong /mnt/c/ có thể chậm hơn 5-10 lần so với ~/.

Cài Codex CLI Trên Linux Ubuntu / Debian / Fedora Ra Sao?

Trên Linux có 2 cách phổ biến: dùng npm (cross-distro) hoặc tải binary trực tiếp từ GitHub Releases.

Ubuntu / Debian (qua npm):

# Ubuntu 22.04 / Debian 12
# Cài Node.js 22 LTS qua NodeSource
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# Verify Node
node --version  # nên là v22.x.x

# Cài Codex CLI
npm install -g @openai/codex
codex --version

Fedora / RHEL / CentOS Stream:

# Fedora 39+
sudo dnf install -y nodejs npm
npm install -g @openai/codex
codex --version

Binary download (mọi distro Linux): nếu hệ điều hành không có npm hoặc bạn muốn tránh runtime Node, tải binary từ GitHub Releases. Chọn file phù hợp với CPU architecture:

# Linux x86_64
curl -L https://github.com/openai/codex/releases/latest/download/codex-x86_64-unknown-linux-musl.tar.gz -o codex.tar.gz
tar -xzf codex.tar.gz
sudo mv codex-x86_64-unknown-linux-musl /usr/local/bin/codex
codex --version

# Linux ARM64 (Raspberry Pi 4/5, AWS Graviton, Ampere VPS)
curl -L https://github.com/openai/codex/releases/latest/download/codex-aarch64-unknown-linux-musl.tar.gz -o codex.tar.gz
tar -xzf codex.tar.gz
sudo mv codex-aarch64-unknown-linux-musl /usr/local/bin/codex

ongboit VPS chạy Ubuntu 22.04 ARM Ampere, dùng binary download cho consistency với production stack. Time tổng cài + auth khoảng 3 phút.

OpenAI API Key Setup + Sign-in ChatGPT Flow Ra Sao?

Sau khi codex --version trả về phiên bản (ví dụ codex 0.131.0), chạy codex lần đầu trong thư mục project. Tool sẽ mở browser tự động yêu cầu đăng nhập OpenAI account.

Authentication có 2 đường:

• Sign in with ChatGPT (recommended): dùng subscription Plus / Pro / Business của bạn, không cần tạo API key riêng. Quota dùng chung với ChatGPT Web. Chọn option này nếu đã có Plus.
• API key: tạo key tại platform.openai.com/api-keys, pay-as-you-go theo token. Phù hợp dev test workflow nặng hoặc team có policy không share ChatGPT account.

Thanh toán từ Việt Nam: ChatGPT Plus chấp nhận Visa / Mastercard quốc tế phát hành tại VN. Test thành công với thẻ TPBank, Sacombank, Techcombank, Vietcombank, MB Bank. Paypal cũng accept. OpenAI hiện không block IP Việt Nam, không cần VPN. Nếu thẻ bị reject, thử trên trình duyệt Incognito để loại trừ cache cookie.

Sau auth thành công, config tự lưu vào ~/.codex/config.toml với token authentication. Detail customize file config (model, sandbox, profiles) xem ở bài Codex CLI config.toml deep dive. Muốn integrate với GitHub, Notion, hay tool khác qua MCP sau khi setup xong? Đọc 7 MCP server đáng cài cho Codex CLI. Đã cài xong và muốn so sánh với Claude Code? Bài Claude Code vs Codex CLI có verdict thực tế trên 47 PR.

Test First Command Trong 30 Giây Như Thế Nào?

Sau khi authenticate, test workflow đầu tiên trong thư mục project:

# Test 1: Version check
codex --version
# Output: codex 0.131.0

# Test 2: Help menu
codex --help
# Output: usage info + available flags

# Test 3: First session
cd ~/projects/your-project
codex
# > Hello, tôi là Codex. Project này dùng stack gì?

# Test 4: One-shot exec mode (không vào interactive)
codex exec "list 3 file lớn nhất trong project hiện tại"

Nếu output trả về có context project (Codex đọc AGENTS.md nếu có, hoặc tự scan thư mục), setup đã hoàn tất. Bước tiếp theo: tạo file AGENTS.md ở project root để Codex hiểu context. Pattern setup AGENTS.md xem ở bài Claude Code và Codex CLI cùng project.

5 Lỗi Thường Gặp Khi Cài Codex CLI Là Gì?

Sau khi cài trên 3 máy khác nhau, đây là 5 lỗi mình từng gặp và workaround:

Lỗi 1: codex: command not found sau khi npm install -g. Nguyên nhân là npm global path chưa nằm trong PATH environment. Fix: chạy npm config get prefix để biết path npm global, thêm vào PATH. Trên macOS / Linux: echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc rồi source ~/.zshrc. Trên Windows PowerShell: setup PATH qua System Properties → Environment Variables.

Lỗi 2: EACCES permission denied khi npm install -g. Linux / macOS thường gặp khi npm cố ghi vào /usr/local/lib/node_modules. KHÔNG sudo (risk security). Fix đúng: dùng nvm để Node ở user directory ~/.nvm/, npm tự ghi vào đó không cần sudo.

Lỗi 3: Windows sandbox elevated setup failed. Lỗi này xảy ra khi user không có admin quyền hoặc Windows version cũ hơn 1809. Fix: chạy PowerShell admin, hoặc accept fallback unelevated mode (yếu hơn về isolation nhưng vẫn dùng được). Nếu muốn full sandbox, cài WSL2 thay vì native.

Lỗi 4: Proxy / firewall block kết nối tới api.openai.com. Một số mạng công ty, trường học, hoặc ISP Việt Nam đôi khi cache DNS sai cho openai.com. Test bằng curl -v https://api.openai.com. Nếu fail, cấu hình proxy trong ~/.codex/config.toml hoặc switch sang DNS public (1.1.1.1 hoặc 8.8.8.8). Đôi khi reset modem là đủ.

Lỗi 5: Node version conflict. Nếu máy đã có Node 14 hoặc 16 cài từ trước (Apache / nginx old setup), npm global có thể cài Codex CLI vào path Node cũ, dẫn tới syntax error. Fix: dùng nvm use 22 trước khi npm install -g, hoặc clean uninstall Node cũ rồi cài lại Node 22 LTS.

Lỗi 6: PowerShell báo “running scripts is disabled on this system”. Windows mặc định cấm chạy script chưa ký, làm codex command không khởi động được dù npm install thành công. Fix: mở PowerShell admin và chạy Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser rồi confirm Y. Hoặc đơn giản hơn, dùng Git Bash hoặc WSL2 thay vì native PowerShell, Codex CLI chạy ổn định hơn trên Unix-style shell theo issue #14016.

Lỗi 7: Missing optional dep @openai/codex-win32-x64 (Windows only). Trên một số máy Windows, lệnh npm install -g @openai/codex@latest báo “Missing optional dependency @openai/codex-win32-x64” và codex fail to start. Workaround chính thức theo issue #12931: tải native binary codex-x86_64-pc-windows-msvc.exe từ GitHub Releases và đặt vào PATH manual. Hoặc switch sang WSL2 để tránh entirely.

Lỗi 8: nvm default version drift giữa các terminal session. Nếu bạn dùng nvm và default version vẫn là Node 18 hoặc 20 thì npm install -g có thể cài Codex CLI dưới Node 22 nhưng terminal mới mở lại dùng Node 20, dẫn tới MODULE_NOT_FOUND. Fix: chạy nvm alias default 22 để lock Node 22 làm default permanent cho mọi session.

Update + Uninstall Codex CLI Đúng Cách Ra Sao?

Update theo cách bạn đã cài:

# Update qua Homebrew (macOS)
brew upgrade --cask codex

# Update qua npm (mọi OS)
npm update -g @openai/codex

# Verify version mới
codex --version

Update tần suất khoảng 1-2 tuần ship 1 version mới per Codex changelog. Recommend update mỗi tháng để có security fix và feature mới.

Uninstall clean khi không dùng nữa:

# Uninstall binary
brew uninstall --cask codex
# HOẶC
npm uninstall -g @openai/codex

# Clean config + history (optional, mất hết setting cá nhân)
rm -rf ~/.codex/

Lưu ý: rm -rf ~/.codex/ xóa toàn bộ config, profile, history, MCP server setup. Backup trước bằng cp -r ~/.codex/ ~/.codex.bak/ nếu có thể quay lại dùng sau.

Câu Hỏi Thường Gặp

Cài Codex CLI có cần Node.js không? Version nào?

Cần nếu cài qua npm (cách phổ biến nhất). Node.js 18 trở lên, recommend Node 20 LTS hoặc 22 LTS cho stability. Nếu cài qua Homebrew (brew install --cask codex) hoặc binary trực tiếp từ GitHub Releases thì không cần Node, vì Codex CLI viết bằng Rust nên binary self-contained, không phụ thuộc Node runtime.

Windows 10 cài được không hay phải lên Windows 11?

Windows 10 phiên bản 1809 trở lên vẫn cài được nhưng OpenAI khuyến nghị Windows 11 vì sandbox elevated mode cần tính năng AppContainer modern. Trên Windows 10 cũ, Codex CLI fallback về unelevated mode (sandbox yếu hơn về isolation). Nếu vẫn dùng Windows 10, alternative tốt là cài WSL2 Ubuntu và chạy Codex CLI trong đó, được sandbox Linux đầy đủ.

M1/M2 Mac có bug gì khi cài Codex CLI không?

Apple Silicon hoạt động native không bug, binary đã build sẵn cho ARM64 (file codex-aarch64-apple-darwin.tar.gz trên GitHub Releases). Test trên MacBook M2 Pro ongboit và M1 MacBook Air thấy performance tốt hơn Intel Mac khoảng 30% cho session dài. Lưu ý duy nhất: tránh cài qua Rosetta 2 emulation (chạy arch -arm64 brew install --cask codex nếu Homebrew của bạn đang ở Intel mode).

Cài Codex CLI cho team có share license được không?

Không share license trực tiếp được. Codex CLI bind vào ChatGPT account của mỗi user. Solution cho team: mỗi dev có ChatGPT Plus / Pro riêng (cost $20-200/tháng/seat), hoặc team account ChatGPT Business / Enterprise có admin dashboard quản lý seat tập trung. Pricing chi tiết tại pricing Claude Code Pro vs Max để so sánh với option Anthropic.

Cài Codex CLI offline (không internet) được không?

Cài binary từ GitHub Releases được mà không cần internet sau khi tải file .tar.gz, copy qua USB hoặc network local. Tuy nhiên KHÔNG chạy được offline vì authentication và inference đều cần kết nối tới api.openai.com. Codex CLI không có local model mode (khác với Claude Code workflow dual-tool nếu kết hợp với Ollama local). Air-gapped environment không phù hợp với Codex CLI ở thời điểm 2026.