# Hướng dẫn cấu hình Codex CLI

> Thông qua ~/.codex/config.toml để tùy chỉnh nhà cung cấp mô hình, kết nối Codex CLI với cổng LLMoxy và dùng các mô hình như Grok 4.7 để lập trình trong terminal.

> **📌 Về Codex CLI**
> Codex CLI là tác nhân lập trình terminal chính thức của OpenAI, được viết bằng Rust, có thể đọc, sửa và chạy mã cục bộ ([mã nguồn mở](https://github.com/openai/codex)). Mặc định nó kết nối với OpenAI, nhưng hỗ trợ `model_provider` tùy chỉnh, vì vậy có thể kết nối liền mạch với cổng LLMoxy và dùng các mô hình như Grok 4.7.

## Các bước cài đặt

### 1. Cài đặt Node.js

Truy cập [trang chủ Node.js](https://nodejs.org/), khuyến nghị tải bản LTS ở bên trái; đây là bản hỗ trợ dài hạn, ổn định hơn.

### 2. Cài đặt Codex CLI

Mở dòng lệnh và cài đặt toàn cục bằng npm:

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

Người dùng macOS cũng có thể dùng Homebrew:

```bash
brew install codex
```

Xác minh cài đặt:

```bash
codex --version
```

Codex CLI hỗ trợ macOS, Linux và Windows. Trên Windows, nên chạy trực tiếp trong PowerShell, hoặc dùng WSL2 để có môi trường Linux nguyên bản.

## Các bước cấu hình

Tệp cấu hình của Codex CLI nằm ở `~/.codex/config.toml` (trên Windows là `%USERPROFILE%\.codex\config.toml`). Để kết nối LLMoxy, chỉ cần hai bước: **đăng ký một nhà cung cấp tùy chỉnh** + **cung cấp API Key**.

### 1. Lấy khóa API

Vào [bảng điều khiển LLMoxy](https://llmoxy.com/) → Quản lý API Key → sao chép khóa bí mật.

> Lưu ý: hãy dùng token thuộc nhóm **auto**.

### 2. Ghi vào config.toml

Thêm nội dung sau vào `~/.codex/config.toml` (nếu tệp chưa tồn tại thì tạo mới):

```toml
# Mặc định dùng nhà cung cấp và mô hình LLMoxy
model = "grok-4.7"
model_provider = "llmoxy"

[model_providers.llmoxy]
name = "LLMoxy"
base_url = "https://llmoxy.com/v1"
wire_api = "responses"
env_key = "LLMOXY_API_KEY"
```

**Giải thích các cấu hình:**

- `model` — tên mô hình mặc định, điền mô hình được LLMoxy hỗ trợ (ví dụ `grok-4.7`)
- `model_provider` — trỏ tới ID nhà cung cấp được định nghĩa bên dưới
- `base_url` — địa chỉ cổng LLMoxy, **có** `/v1`
- `wire_api` — điền `responses` để dùng `/v1/responses`. Codex chỉ hỗ trợ giá trị này, điền `chat` sẽ báo lỗi
- `env_key` — tên biến môi trường lưu API Key, sẽ được thiết lập ở bước tiếp theo

> **MẸO**
> Khác với Claude Code, `base_url` của Codex CLI **bắt buộc** phải có `/v1`.

### 3. Thiết lập biến môi trường API Key

Biến môi trường do `env_key` chỉ định cần được thiết lập trong hệ thống với khóa thật.

**Windows (PowerShell, có hiệu lực vĩnh viễn):**

```powershell
[Environment]::SetEnvironmentVariable("LLMOXY_API_KEY","API Key LLMoxy của bạn","User")
```

Sau khi thiết lập, hãy **đóng PowerShell và mở lại một cửa sổ mới** để tải biến môi trường.

**macOS / Linux:**

```bash
{
echo ''
echo '# LLMoxy'
echo 'export LLMOXY_API_KEY="API Key LLMoxy của bạn"'
} >> ~/.zshrc   # Người dùng Bash đổi thành ~/.bashrc
source ~/.zshrc
```

Xác minh:

```bash
echo "$LLMOXY_API_KEY"
```

Bạn **phải** thay `API Key LLMoxy của bạn` bằng khóa thật sao chép từ [bảng điều khiển LLMoxy](https://llmoxy.com/).

### 4. Khởi chạy

Vào thư mục dự án của bạn và khởi động phiên tương tác:

```bash
codex
```

Nếu có thể trò chuyện và thực thi tác vụ bình thường, nghĩa là bạn đã kết nối thành công với LLMoxy.

## Các thao tác thường dùng

### Chuyển mô hình và mức độ suy luận

Trong phiên, nhập `/model` để đổi mô hình hoặc điều chỉnh mức độ suy luận (reasoning effort). Bạn cũng có thể chỉ định lúc khởi động bằng `-m`:

```bash
codex -m grok-4.7
```

### Chế độ phê duyệt

Codex sẽ yêu cầu xác nhận trước khi sửa tệp hoặc chạy lệnh. Có thể đổi trong phiên bằng `/approvals`, hoặc chỉ định khi khởi động:

```bash
codex --ask-for-approval      # Xác nhận từng bước (mặc định, an toàn nhất)
codex --full-auto             # Tự động thực thi, chỉ chạy trong sandbox bị giới hạn mạng, trong thư mục làm việc
```

> **💡 Gợi ý**
> Lần đầu chạy trong một thư mục dự án nào đó, Codex sẽ hỏi bạn có tin cậy thư mục đó hay không.

### Chạy theo kịch bản (không tương tác)

Dùng lệnh con `exec` để giao tác vụ một lần cho Codex, phù hợp cho script hoặc CI:

```bash
codex exec "Viết thêm unit test cho ParseConfig trong main.go"
```

### Đầu vào hình ảnh

Bạn có thể đính kèm ảnh chụp màn hình hoặc bản thiết kế để Codex hiểu yêu cầu cùng với hình ảnh:

```bash
codex -i screenshot.png "Dựa trên bản thiết kế này, triển khai trang đăng nhập"
```

### Tìm kiếm trên web

Bật Web Search để lấy thông tin mới nhất:

```bash
codex --search
```

### Kết nối công cụ MCP

Trong `config.toml`, đăng ký dịch vụ MCP qua `[mcp_servers.*]` để cung cấp cho Codex các công cụ và ngữ cảnh bên thứ ba. Cấu hình này có thể dùng chung với cấu hình nhà cung cấp LLMoxy:

```toml
[mcp_servers.chrome-devtools]
command = "npx"
args = ["chrome-devtools-mcp@latest"]
```

## Câu hỏi thường gặp

### `npm install -g` báo lỗi quyền truy cập

Đừng dùng `sudo npm install -g`. Khuyến nghị dùng nvm để quản lý Node.js, hoặc đổi thư mục toàn cục của npm:

```bash
npm config set prefix ~/.npm-global
```

Sau đó thêm `~/.npm-global/bin` vào PATH. Người dùng macOS cũng có thể cài Node.js bằng Homebrew (không cần sudo).

### Sau khi khởi chạy vẫn yêu cầu đăng nhập tài khoản OpenAI

Xác nhận `model_provider = "llmoxy"` trong `config.toml` đã có hiệu lực và biến môi trường `LLMOXY_API_KEY` đã được thiết lập. Khi đã cấu hình nhà cung cấp tùy chỉnh, Codex sẽ xác thực bằng API Key, không cần đăng nhập ChatGPT.

### Báo lỗi 404 / mô hình không tồn tại

- Kiểm tra `base_url` có kèm `/v1`: `https://llmoxy.com/v1`
- Kiểm tra `model` có phải là tên mô hình mà LLMoxy hỗ trợ hay không
- Kiểm tra `wire_api = "responses"`: Codex không còn hỗ trợ `chat`, và `wire_api = "chat"` trong hướng dẫn cũ sẽ báo lỗi

### Biến môi trường chưa có hiệu lực

- Windows: `SetEnvironmentVariable(...,"User")` cần **mở lại terminal**
- macOS / Linux: chạy `source ~/.zshrc` (hoặc `~/.bashrc`), hoặc mở lại terminal, rồi dùng `echo "$LLMOXY_API_KEY"` để xác minh

### Gọi API thất bại / vấn đề số dư

- Kiểm tra API Key không có khoảng trắng thừa
- Vào [bảng điều khiển LLMoxy](https://llmoxy.com/) để kiểm tra số dư tài khoản và nhóm token (khuyến nghị dùng nhóm **auto**)

### Kết nối máy chủ từ xa bị timeout (Linux)

- Kiểm tra mạng: `curl -I https://llmoxy.com`
- Nếu cần proxy, cấu hình biến môi trường `HTTPS_PROXY`

Đây là bản markdown của https://vi.llmoxy.com/docs/code-tutorials/codex-cli.
