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

> Cài đặt OpenAI Codex App trên macOS và Windows, rồi kết nối với Grok 4.7 của LLMoxy qua config.toml.

> **Phạm vi áp dụng**
> Bài viết này chỉ nói về việc kết nối Codex App với LLMoxy; mô hình ví dụ luôn dùng `grok-4.7`. Nếu cần bản terminal, hãy xem “Hướng dẫn cấu hình CodeX CLI”.

![Xem trước giao diện Codex App](https://vi.llmoxy.com/docs-assets/migrated/tutorial-codex-app/app-screenshot-light.webp)

## Chuẩn bị

Trước khi bắt đầu, hãy chuẩn bị ba thứ:

1. Một tài khoản [LLMoxy](https://llmoxy.com/) hợp lệ
2. Một API Key LLMoxy thuộc nhóm **auto**
3. Tên mô hình dùng thống nhất trong bài: `grok-4.7`

Codex App dùng chung lớp cấu hình Codex với Codex CLI và plugin IDE. Cấu hình cấp người dùng thường đặt tại `~/.codex/config.toml`; ở chế độ Windows native thì đường dẫn tương ứng là `%USERPROFILE%\.codex\config.toml`.

## Cấu hình LLMoxy dùng chung

Phần cấu hình dưới đây sẽ dùng cho macOS, Windows Native, và Windows + WSL. Hãy ghi nó vào `config.toml` trong môi trường tương ứng:

```toml
model_provider = "llmoxy"
model = "grok-4.7"
model_reasoning_effort = "high"
model_verbosity = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

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

Ý nghĩa của cấu hình:

- `model_provider = "llmoxy"`: mặc định dùng Provider LLMoxy được định nghĩa bên dưới
- `model = "grok-4.7"`: mặc định gọi Grok 4.7 trên LLMoxy
- `base_url = "https://llmoxy.com/v1"`: endpoint tương thích OpenAI của Codex phải kèm `/v1`
- `wire_api = "responses"`: dùng `/v1/responses`. Codex chỉ hỗ trợ giá trị này, điền `chat` sẽ báo lỗi
- `env_key = "LLMOXY_API_KEY"`: API Key được đọc từ biến môi trường, không ghi vào file cấu hình
- `approval_policy` và `sandbox_mode`: giữ xác nhận và sandbox trong workspace, phù hợp cho người dùng phổ thông khi bắt đầu

## Cài đặt và cấu hình trên macOS

### 1. Cài đặt Codex App

Mở địa chỉ tải xuống chính thức cho macOS:

- [https://persistent.oaistatic.com/codex-app-prod/Codex.dmg](https://persistent.oaistatic.com/codex-app-prod/Codex.dmg)

Sau khi tải xong, nhấp đúp vào `.dmg`, rồi làm theo hướng dẫn của hệ thống để kéo Codex vào `Applications`.

### 2. Ghi file cấu hình

Mở terminal và tạo thư mục cấu hình Codex:

```bash
mkdir -p ~/.codex
open -a TextEdit ~/.codex/config.toml
```

Dán phần “Cấu hình LLMoxy dùng chung” ở trên vào rồi lưu lại.

### 3. Thiết lập API Key

Shell mặc định trên macOS thường là Zsh; hãy ghi vào `~/.zshrc`:

```bash
{
echo ''
echo '# LLMoxy'
echo 'export LLMOXY_API_KEY="API Key LLMoxy của bạn"'
} >> ~/.zshrc
source ~/.zshrc
```

Kiểm tra:

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

Bạn phải thay `API Key LLMoxy của bạn` bằng token thật đã sao chép từ console.

### 4. Mở dự án để xác minh

Khởi động Codex App, chọn một thư mục mã nguồn, rồi gửi một tác vụ nhẹ:

```text
Hãy giải thích cấu trúc dự án hiện tại và chỉ ra file entry nằm ở đâu.
```

Nếu Codex đọc được dự án và phản hồi bình thường, nghĩa là phía macOS đã kết nối với LLMoxy.

## Cài đặt và cấu hình trên Windows Native

![Giao diện Codex App trên Windows](https://vi.llmoxy.com/docs-assets/migrated/tutorial-codex-app/codex-windows-light.webp)

Windows mặc định dùng **Windows Native Agent**; lệnh chạy trong môi trường PowerShell, và file cấu hình nằm trong thư mục người dùng Windows.

### 1. Cài đặt Codex App

Chọn một trong hai cách:

- Trang Microsoft Store: [Codex App](https://apps.microsoft.com/detail/9plm9xgg6vks?hl=en-US&gl=US)
- Cài bằng PowerShell:

```powershell
winget install Codex -s msstore
```

### 2. Ghi file cấu hình

Dùng PowerShell để tạo và mở file cấu hình:

```powershell
New-Item -ItemType Directory -Force "$HOME\.codex"
notepad "$HOME\.codex\config.toml"
```

Dán “Cấu hình LLMoxy dùng chung” vào rồi lưu lại.

Đường dẫn thực tế thường sẽ giống:

```text
C:\Users\tên-người-dùng-của-bạn\.codex\config.toml
```

### 3. Thiết lập API Key

Nên ghi vào biến môi trường cấp người dùng của Windows:

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

Đóng Codex App và PowerShell, rồi mở lại để kiểm tra:

```powershell
echo $env:LLMOXY_API_KEY
```

### 4. Mở dự án để xác minh

Khởi động Codex App, thêm thư mục dự án rồi gửi:

```text
Chạy git status và giải thích trạng thái hiện tại của workspace.
```

Nếu PowerShell chặn việc chạy script, hãy thực thi trong PowerShell:

```powershell
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
```

Nếu tính năng Git không dùng được, hãy cài Git gốc trước:

```powershell
winget install Git.Git
```

## Cấu hình Windows + WSL

Nếu dự án của bạn chủ yếu phát triển bằng bộ công cụ Linux, bạn có thể chuyển Codex Agent sang WSL.

![Chuyển sang WSL Agent](https://vi.llmoxy.com/docs-assets/migrated/tutorial-codex-app/wsl-select-light.webp)

### 1. Chuyển Agent

Trong Codex App, mở `Settings`, chuyển Agent từ Windows Native sang WSL rồi khởi động lại App. Thiết lập này chỉ có hiệu lực sau khi restart.

### 2. Ghi cấu hình trong WSL

Sau khi vào terminal WSL, hãy tạo cấu hình:

```bash
mkdir -p ~/.codex
nano ~/.codex/config.toml
```

Ghi “Cấu hình LLMoxy dùng chung” vào `~/.codex/config.toml` bên trong WSL.

### 3. Thiết lập API Key trong WSL

Người dùng Bash:

```bash
{
echo ''
echo '# LLMoxy'
echo 'export LLMOXY_API_KEY="API Key LLMoxy của bạn"'
} >> ~/.bashrc
source ~/.bashrc
```

Người dùng Zsh:

```bash
{
echo ''
echo '# LLMoxy'
echo 'export LLMOXY_API_KEY="API Key LLMoxy của bạn"'
} >> ~/.zshrc
source ~/.zshrc
```

Kiểm tra:

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

Windows Native và WSL là hai môi trường khác nhau. Khi Agent chạy trong WSL, bạn phải sửa `~/.codex/config.toml` trong WSL và cũng phải đặt `LLMOXY_API_KEY` ngay trong WSL.

## Các thiết lập App thường dùng

### Mở trình soạn thảo mặc định

Bạn có thể chọn trình soạn thảo mặc định trong phần cài đặt `Open In`, chẳng hạn VS Code hoặc Visual Studio.

![Thiết lập trình soạn thảo mở mặc định](https://vi.llmoxy.com/docs-assets/migrated/tutorial-codex-app/open-in-windows-light.webp)

### Terminal tích hợp

Trên Windows, terminal tích hợp có thể chọn PowerShell, Command Prompt, Git Bash hoặc WSL. Thiết lập này khác với môi trường chạy Agent: bạn có thể để Agent chạy trên WSL nhưng terminal tích hợp vẫn dùng PowerShell.

![Thiết lập terminal tích hợp](https://vi.llmoxy.com/docs-assets/migrated/tutorial-codex-app/integrated-shell-light.webp)

Sau khi đổi terminal, thường chỉ áp dụng cho phiên mới; nếu cần, hãy khởi động lại Codex App.

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

### Vẫn bị yêu cầu đăng nhập OpenAI sau khi khởi động

Xác nhận `config.toml` của môi trường hiện tại đã có:

```toml
model_provider = "llmoxy"
```

và đảm bảo `LLMOXY_API_KEY` có thể đọc được trong cùng môi trường đó. Khi dùng LLMoxy Provider, Codex sẽ dùng API Key từ biến môi trường để gọi LLMoxy, không cần viết secret vào file cấu hình.

### 404 hoặc không có mô hình

Kiểm tra ba điểm:

1. `base_url` phải là `https://llmoxy.com/v1`
2. `model` phải là `grok-4.7`
3. API Key nên dùng token thuộc nhóm **auto**

### Cấu hình Windows và WSL không đồng bộ

Hãy xem Agent đang chạy ở môi trường nào:

- Windows Native: sửa `%USERPROFILE%\.codex\config.toml`, và đặt biến môi trường người dùng của Windows
- WSL: sửa `~/.codex/config.toml` trong WSL, và đặt biến môi trường Shell trong WSL

### Muốn đặt lại về quyền hạn thận trọng hơn

Giữ nguyên cấu hình sau:

```toml
approval_policy = "on-request"
sandbox_mode = "workspace-write"
```

Như vậy Codex sẽ hỏi trước khi cần vượt qua sandbox hoặc thực hiện thao tác nhạy cảm.

## Liên kết tham khảo

- [OpenAI Codex App](https://developers.openai.com/codex/app/)
- [OpenAI Codex App for Windows](https://developers.openai.com/codex/app/windows/)
- [Cơ bản về cấu hình OpenAI Codex](https://developers.openai.com/codex/config-basic)
- [Tài liệu xác thực OpenAI Codex](https://developers.openai.com/codex/auth)

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