Codex CLI với nhà cung cấp tùy chỉnh: config.toml, mô hình GPT và Claude, tiện ích mở rộng IDE và cách khắc phục lỗi

Codex đọc một tệp, ~/.codex/config.toml, được dùng chung bởi CLI, codex exec và tiện ích mở rộng IDE. Một nhà cung cấp tùy chỉnh trong tệp đó trỏ Codex đến cổng API này, nơi cùng một cấu hình có thể chạy cả mô hình GPT và Claude. Các phiên bản Codex hiện tại chỉ giao tiếp qua Responses API (wire_api = "responses"), nên các hướng dẫn cũ sử dụng wire_api = "chat" không còn hoạt động.

Cài đặt Codex

# macOS / Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# or with a package manager
npm install -g @openai/codex
brew install --cask codex

codex --version

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Tiện ích mở rộng Codex cho VS Code, Cursor và Windsurf được cài đặt từ kho tiện ích mở rộng của trình soạn thảo và sử dụng cùng ~/.codex/config.toml với CLI, vì vậy mọi nội dung bên dưới đều áp dụng cho cả hai.

Dùng khóa thuộc đúng nhóm

Khóa cổng API thuộc về một nhóm, và nhóm đó quyết định các mô hình mà khóa có thể gọi. Với mô hình GPT, hãy tạo khóa trong nhóm **Codex** trên bảng điều khiển. Với mô hình Claude, mọi khóa Claude tính phí theo mức sử dụng đều dùng được. Khóa thuộc nhóm Không giới hạn cần có gói đang hoạt động; nếu không, mọi yêu cầu đều thất bại với No active subscription found for this group.

export AIPRIME_CODEX_KEY=key_from_the_codex_group    # GPT models
export AIPRIME_CLAUDE_KEY=key_from_a_claude_group    # Claude models

setx AIPRIME_CODEX_KEY "key_from_the_codex_group"
setx AIPRIME_CLAUDE_KEY "key_from_a_claude_group"
# open a new terminal afterwards

config.toml cho các mô hình GPT

model_provider = "aiprime"
model = "gpt-6-astra"
model_reasoning_effort = "high"

[model_providers.aiprime]
name = "AI Prime Tech"
base_url = "https://aiprimetech.io/v1"
env_key = "AIPRIME_CODEX_KEY"
wire_api = "responses"
supports_websockets = false

Chạy Codex với các mô hình Claude

Cổng API chấp nhận các yêu cầu Responses API cho mô hình Claude và chuyển đổi chúng, vì vậy Codex cũng có thể điều khiển Claude. Thêm nhà cung cấp thứ hai sử dụng khóa Claude của bạn, rồi thêm một hồ sơ cấu hình để chuyển sang nhà cung cấp đó.

[model_providers.aiprime_claude]
name = "AI Prime Tech (Claude)"
base_url = "https://aiprimetech.io/v1"
env_key = "AIPRIME_CLAUDE_KEY"
wire_api = "responses"
supports_websockets = false

model_provider = "aiprime_claude"
model = "claude-sonnet-5"
model_reasoning_effort = "high"

codex --profile claude
codex exec --profile claude "review the last commit for bugs"

Kể từ Codex 0.134.0, mỗi hồ sơ cấu hình có tệp riêng, ~/.codex/<name>.config.toml, với các khóa ở cấp cao nhất; [profiles.<name>] các bảng bên trong config.toml không còn được đọc. Hồ sơ cấu hình và nhà cung cấp chỉ có thể được đặt trong cấu hình người dùng của bạn: tệp của dự án .codex/config.toml bỏ qua model_provider và model_providers.

Mô hình và mức độ suy luận

model_reasoning_effort chấp nhận low, medium, high, xhigh hoặc max, tùy theo mô hình. Đừng đặt none: các mô hình này từ chối giá trị đó với 'none' is not supported. review_model đặt một mô hình khác cho /review nếu bạn muốn. Bảng điều khiển hiển thị mọi mô hình mà nhóm của khóa có thể gọi.

Tiện ích mở rộng IDE và codex exec

Tiện ích mở rộng IDE đọc cùng config.toml, nhưng env_key được xác định từ môi trường riêng của trình soạn thảo. Trình soạn thảo khởi động từ Dock hoặc menu Start không nhận được các biến được xuất trong .bashrc, và khi đó Codex thất bại với Invalid API key trong khi CLI vẫn hoạt động. Đặt biến cho toàn hệ thống (trên Windows, setx thực hiện việc này), hoặc khởi động trình soạn thảo từ terminal, ví dụ code ..

codex exec chạy một tác vụ mà không có giao diện tương tác, phù hợp với tập lệnh và CI. Lệnh này sử dụng cùng cấu hình và hồ sơ cấu hình:

codex exec "write unit tests for utils.py"
codex exec --profile claude "summarise the changes on this branch"
codex login status        # which authentication method is active

Thử lại và thời gian chờ

Mỗi nhà cung cấp có cài đặt thử lại và truyền dữ liệu dạng luồng riêng. Giá trị mặc định là 4 lần thử lại yêu cầu, 5 lần kết nối lại luồng và thời gian chờ khi không có hoạt động là 5 phút cho mỗi luồng. Các lượt suy luận dài có thể không phát dữ liệu trong một khoảng thời gian, vì vậy tăng thời gian chờ này sẽ hữu ích khi dùng mức độ suy luận cao.

[model_providers.aiprime]
# ...settings from above...
request_max_retries = 6
stream_max_retries = 8
stream_idle_timeout_ms = 600000

Khắc phục sự cố: các lỗi người dùng Codex gặp phải

Các lỗi bên dưới là những lỗi mà ứng dụng khách Codex thực sự tạo ra trên cổng API này, được sắp xếp từ phổ biến nhất.

Bạn đang so sánh Codex với Claude Code trước khi quyết định chọn một công cụ? Xem Claude Code so với Codex.

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

AI Prime Tech là một cổng API độc lập. AI Prime Tech không liên kết với, không được Anthropic chứng thực và không phải là đại lý bán lại của Anthropic. Claude và các tên mô hình liên quan là nhãn hiệu của chủ sở hữu tương ứng.