# Hướng dẫn cài đặt Codex cho người mới bắt đầu

> Hướng dẫn cài đặt Codex để chạy coding agent ngay trong terminal: cài đặt, đăng nhập bằng tài khoản OpenAI và chạy tác vụ đầu tiên.

Nguồn: https://camnangai.com/cong-cu/huong-dan-cai-dat-codex  
Xuất bản: 2026-07-31

Xong bài hướng dẫn cài đặt Codex này, bạn có một coding agent chạy thẳng trong terminal: nó đọc mã
  nguồn trong dự án, sửa file và chạy lệnh ngay trên máy bạn.


Bạn cần một terminal và một tài khoản OpenAI, tức là gói ChatGPT hoặc một API key. Trình cài đặt độc lập và bản Homebrew tải về binary dựng sẵn, không cần Node.js. Cài qua npm thì cần Node.js 16 trở lên. Nếu bạn chưa rõ agent này làm được gì, đọc [Codex là gì](https://camnangai.com/cong-cu/codex-la-gi) trước.

![Phiên làm việc Codex CLI trong terminal: nhận yêu cầu giải thích codebase rồi lập kế hoạch từng bước](https://camnangai.com/articles/huong-dan-cai-dat-codex/01-infographic.webp)

## Bước 1 — Cài đặt Codex

Chọn đúng một nhánh, bỏ qua phần còn lại.

![Ba cách cài đặt Codex — trình cài đặt độc lập, npm và Homebrew — cùng dẫn tới một binary duy nhất](https://camnangai.com/articles/huong-dan-cai-dat-codex/02-vn.webp)

### Cài đặt bằng trình cài đặt độc lập (macOS và Linux)

```bash
curl -fsSL https://chatgpt.com/codex/install.sh | sh
```

Lệnh này tải binary Codex và cài thẳng vào máy. Đây là cách nhanh nhất trên macOS và Linux, và cũng là cách ít rắc rối nhất, vì nó không đụng gì tới phiên bản Node.js trên máy bạn.

### Cài đặt qua npm (đa nền tảng)

```bash
npm install -g @openai/codex
```

Dùng cho Windows, macOS hoặc Arm Linux. Trên Arm Linux hoặc những máy cài Node.js thẳng vào hệ thống (không qua NVM), bạn có thể phải thêm `sudo` để có quyền ghi vào thư mục binary chung.

### Cài đặt qua Homebrew (macOS)

```bash
brew install --cask codex
```

## Bước 2 — Xác nhận Codex đã cài đúng

```bash
codex --version
```

Terminal in ra số phiên bản, ví dụ `@openai/codex, 0.146.0`. Số này xác nhận binary đã nằm trong PATH và gọi được từ mọi thư mục.

## Bước 3 — Đăng nhập vào Codex

Chọn một trong hai cách xác thực dưới đây, tuỳ loại tài khoản bạn có.

### Đăng nhập bằng tài khoản ChatGPT

```bash
codex login
```

Lệnh mở trình duyệt để bạn đăng nhập. Dùng cách này nếu bạn đang có gói ChatGPT Plus, Team hoặc Enterprise.

### Đăng nhập bằng API Key

```bash
export OPENAI_API_KEY=your-api-key-here
```

Cách trên chỉ có hiệu lực trong phiên terminal hiện tại. Để lưu lại lâu dài, đẩy khoá thẳng vào lệnh login:

```bash
printenv OPENAI_API_KEY | codex login --with-api-key
```

Codex lưu thông tin đăng nhập tại `~/.codex/auth.json`. Đừng chia sẻ tệp này, vì nó mở thẳng vào tài khoản của bạn.

## Bước 4 — Chọn chế độ quyền cho phiên làm việc

Vào thư mục dự án rồi chạy `codex`. Trong phiên làm việc, gõ lệnh nội bộ để xem và đổi quyền:

```bash
/permissions
```

- `workspace-write`: Codex đọc và sửa file trong thư mục dự án.
- `read-only`: Codex chỉ đọc để phân tích, không sửa gì.


  Trong thư mục không có `.git`, Codex mặc định chạy ở chế độ chỉ đọc — nó sẽ không sửa được file
  nào cho tới khi bạn đổi quyền.


Codex dùng sandbox ở cấp hệ điều hành (`bwrap` trên Linux, Seatbelt trên macOS) để cô lập môi trường chạy.

![So sánh hai chế độ quyền workspace-write và read-only, kèm mặc định read-only cho thư mục không có .git](https://camnangai.com/articles/huong-dan-cai-dat-codex/03-vn.webp)

## Bước 5 — Chạy tác vụ đầu tiên trong dự án của bạn

Gõ yêu cầu thẳng vào shell của Codex:

- `Giải thích cấu trúc dự án này`
- `Tìm lỗi logic trong file main.js`

**Lưu ý:** trước khi giao việc, chạy `git status` để chắc chắn cây làm việc đang sạch. Tôi luôn làm bước này, vì khi sửa đổi của agent trộn lẫn vào những thay đổi dở dang của bạn thì gỡ ra rất mệt. Khi Codex đề xuất thay đổi, đọc kỹ diff rồi mới chấp nhận.

## Những lệnh bạn sẽ dùng hằng ngày

| Lệnh           | Chức năng                                       |
| :------------- | :---------------------------------------------- |
| `/init`        | Tạo file AGENTS.md để đặt luật riêng cho dự án. |
| `/model`       | Đổi model và mức suy luận (reasoning effort).   |
| `codex review` | Xem lại thay đổi chưa commit và tìm lỗi.        |
| `codex resume` | Mở lại phiên gần nhất trong thư mục hiện tại.   |

## Xử lý sự cố thường gặp

| Lỗi                                               | Nguyên nhân                                                  | Cách sửa                                                                         |
| :------------------------------------------------ | :----------------------------------------------------------- | :------------------------------------------------------------------------------- |
| `bwrap: No such file or directory`                | Thiếu bubblewrap trên Linux nên sandbox không khởi tạo được. | Chạy `sudo apt install bubblewrap`.                                              |
| `npm warn EBADENGINE Unsupported engine`          | Node.js thấp hơn mức tối thiểu `>=16` của gói.               | Chạy `nvm install 20 && nvm alias default 20`, rồi cài lại Codex.                |
| Trình duyệt không nhận callback khi `codex login` | Máy không có giao diện, hoặc chưa forward cổng 1455 qua SSH. | Dùng `codex login --device-auth`, hoặc `ssh -L 1455:localhost:1455 user@remote`. |

## Việc nên làm tiếp theo

Chạy `/init` để tạo file `AGENTS.md` trong repo. Đây là nơi bạn viết luật riêng cho dự án (quy ước code, lệnh chạy test, những thứ Codex phải tránh), và Codex đọc lại nó ở mọi phiên sau. Xem thêm [cách viết AGENTS.md hiệu quả](https://camnangai.com/ung-dung-ai/lap-trinh-vien/agents-md-best-practices).

## Tài liệu tham khảo

- [Codex CLI | ChatGPT Learn](https://learn.chatgpt.com/docs/codex/cli)
- [Authentication | ChatGPT Learn](https://learn.chatgpt.com/docs/auth)
- [Agent approvals & security | ChatGPT Learn](https://learn.chatgpt.com/docs/agent-approvals-security)
- [Developer commands | ChatGPT Learn](https://learn.chatgpt.com/docs/developer-commands?surface=cli)
- [openai/codex — GitHub](https://github.com/openai/codex)
- [Codex CLI Install Guide — Arm Learning Paths](https://learn.arm.com/install-guides/codex-cli/)
- [codex: command not found? 7 Fixes for npm install -g @openai/codex — ofox.ai](https://ofox.ai/blog/codex-command-not-found-fix-npm-install-2026/)
- [How to Run Codex CLI on Windows: Native Install or WSL — CodeAgentSwarm](https://www.codeagentswarm.com/en/guides/codex-cli-on-windows)