> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.tramlabs.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.tramlabs.io/_mcp/server.

# Codex CLI

> Dùng Codex CLI với Trạm AI

## Codex CLI là gì?

[Codex CLI](https://github.com/openai/codex) là coding agent mã nguồn mở của OpenAI, chạy trực tiếp ngay trong terminal của người dùng. Codex CLI hỗ trợ nhiều model provider, trong đó có Trạm AI — nghĩa là người dùng vừa giữ được quy trình agentic coding quen thuộc của Codex, vừa tận dụng được API hợp nhất, provider failover và các công cụ kiểm soát ở cấp tổ chức của Trạm AI.

## Bắt đầu nhanh

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

Làm theo [hướng dẫn cài đặt Codex CLI](https://github.com/openai/codex) để cài CLI lên máy.

### Bước 2: Lấy API key của Trạm AI

1. Đăng ký hoặc đăng nhập tại [Trạm AI](https://tramlabs.io)
2. Mở [trang API Keys](https://console.tramlabs.io/keys)
3. Tạo một API key mới
4. Sao chép key (key bắt đầu bằng `tram_sk-...`)

### Bước 3: Cấu hình Codex cho Trạm AI

Codex dùng file `config.toml`, thường nằm ở `~/.codex/config.toml`. Tạo mới file này hoặc mở file sẵn có rồi thêm cấu hình sau:

**`lines`**

```toml lines
model_provider = "tram"
model_reasoning_effort = "high"
model="gpt-5.5"

[model_providers.tram]
name = "Tram AI"

base_url="https://api.tramlabs.io/v1"
env_key="TRAM_AI_API_KEY"
```

### Bước 4: Thiết lập API key

Export API key của Trạm AI trong shell profile:

**`lines`**

```bash lines
# Add to ~/.zshrc, ~/.bashrc, or ~/.config/fish/config.fish
export TRAM_AI_API_KEY="tram_sk-..."
```

> **Note**
>
> Codex đọc API key từ biến môi trường khai báo ở `env_key` (mặc định là `TRAM_AI_API_KEY`). Hãy đảm bảo biến này đã được thiết lập trước khi khởi động Codex.

### Bước 5: Khởi động Codex

Mở thư mục dự án và chạy:

**`lines`**

```bash lines
cd /path/to/your/project
codex
```

Hoàn tất — từ giờ mọi request sẽ được route qua Trạm AI.

## Tham chiếu cấu hình

### Các thiết lập cốt lõi

| Thiết lập                  | Mô tả                                          | Ví dụ                                    |
| -------------------------- | ---------------------------------------------- | ---------------------------------------- |
| `model_provider`           | Provider dùng cho các request model            | `"tram"`                                 |
| `model`                    | Model ID của Trạm AI                           | `"gpt-5.5"`                              |
| `model_reasoning_effort`   | Mức reasoning effort cho các model Codex       | `"low"`, `"medium"`, `"high"`, `"xhigh"` |
| `show_raw_agent_reasoning` | Có hiển thị reasoning token trong UI hay không | `true` hoặc `false`                      |
| `personality`              | Preset tính cách của agent                     | `"pragmatic"`, `"helpful"`, v.v.         |

### Khối Provider của Trạm AI

**`lines`**

```toml lines
[model_providers.tram]
name = "Tram AI"
base_url = "https://api.tramlabs.io/v1"
env_key = "TRAM_AI_API_KEY"
```

* `base_url`: Endpoint API của Trạm AI. Dùng `https://api.tramlabs.io/v1` cho production.
* `env_key`: Tên biến môi trường chứa API key.

### Mức tin cậy (Trust Level) theo dự án

Codex cho phép đặt mức tin cậy riêng cho từng dự án. Thêm đường dẫn dự án vào để kiểm soát những gì agent được phép truy cập vào:

**`lines`**

```toml lines
[projects."/path/to/trusted/project"]
trust_level = "trusted"

[projects."/path/to/untrusted/project"]
trust_level = "untrusted"
```

* `trusted`: Agent có toàn quyền (chạy lệnh, sửa file, v.v.).
* `untrusted`: Agent bị giới hạn quyền truy cập cho an toàn.

## Vì sao nên dùng Trạm AI với Codex CLI?

### Provider Failover

Trạm AI điều phối request qua nhiều provider. Khi một provider gặp sự cố hoặc bị rate-limit, Trạm AI sẽ tự động chuyển sang provider khác, giúp phiên làm việc không bị gián đoạn.

### Theo dõi mức sử dụng

Xem mức sử dụng Codex theo thời gian thực ngay trên [Trạm AI Activity Dashboard](https://console.tramlabs.io/settings/logs) — chi phí, lượng token, và các kiểu request đều rõ ràng.

### Linh hoạt đổi model

Chỉ cần trỏ `model` tới bất kỳ slug nào của Trạm AI (ví dụ `gpt-5.5`, `claude-sonnet-4.6`) hoặc một phiên bản cố định là người dùng có thể đổi model — không cần cài lại Codex, chỉ cần cập nhật `config.toml`.

## Khắc phục sự cố

* **Lỗi xác thực:** Kiểm tra `TRAM_AI_API_KEY` đã được thiết lập và còn hợp lệ chưa, tại [tramlabs.io/keys](https://console.tramlabs.io/keys).
* **Không tìm thấy model:** Đối chiếu lại model ID tại [tramlabs.io/models](https://tramlabs.io/models), và nhớ dùng đúng định dạng (ví dụ `gpt-5.5`).
* **Quyền riêng tư:** Trạm AI không log các prompt chứa mã nguồn của người dùng, trừ khi người dùng chủ động bật prompt logging. Xem [Chính sách quyền riêng tư](https://tramlabs.io/privacy) để biết thêm.

## Resources

* [Codex CLI trên GitHub](https://github.com/openai/codex)
* [Các model Codex trên Trạm AI](https://tramlabs.io/models?q=codex)
* [Trạm AI Activity Dashboard](https://console.tramlabs.io/settings/logs)
* [Tài liệu API của Trạm AI](https://tram-ai.docs.buildwithfern.com/api)