Codex CLI với khóa API — cấu hình, mô hình và chi phí phiên

Codex CLI là agent lập trình mã nguồn mở trên terminal của OpenAI, và có thể chạy bằng đăng nhập ChatGPT hoặc khóa API. Phương thức dùng khóa là phần đáng tìm hiểu: tính phí theo token, không có phí hàng tháng và là phương thức duy nhất cho phép trỏ CLI đến provider khác — hoặc một họ model khác. Hướng dẫn này trình bày cấu hình hoạt động, yêu cầu khiến phần lớn gateway thất bại, chi phí của một phiên làm việc và cách thanh toán bằng Pix từ Brazil.

Yêu cầu duy nhất quan trọng

Codex CLI sử dụng Responses API của OpenAI, và chỉ API đó: khối model_providers chỉ chấp nhận wire_api = "responses". Một gateway chỉ cung cấp /v1/chat/completions đơn giản là không thể được cấu hình — đó là lý do phần lớn endpoint “tương thích với OpenAI” thất bại ở đây. Kunavo cung cấp POST /v1/responses cùng với chat endpoint, nên khối bên dưới hoạt động mà không cần điều chỉnh.

Cấu hình

# ~/.codex/config.toml
model          = "gpt-5-6-sol"
model_provider = "kunavo"

[model_providers.kunavo]
name     = "kunavo"
base_url = "https://api.kunavo.com/v1"
env_key  = "KUNAVO_API_KEY"
wire_api = "responses"

env_key là tên của biến môi trường, không phải khóa: Codex không bao giờ ghi khóa vào tệp cấu hình.

# O Codex lê a chave da variável indicada em env_key.
export KUNAVO_API_KEY="sk-kn-..."     # crie em kunavo.com/app/keys

# Deixe persistente (escolha o arquivo que o seu shell realmente carrega):
echo 'export KUNAVO_API_KEY="sk-kn-..."' >> ~/.zshrc

codex "explique a estrutura deste repositório"

Tạo khóa trong bảng điều khiển sau khi đăng ký và nạp $10 — khóa chỉ xuất hiện một lần.

Thanh toán từ Brazil — Pix, không cần thẻ quốc tế

Đối với nhà phát triển Brazil, trở ngại hiếm khi là tệp TOML mà là phương thức thanh toán. Thanh toán trực tiếp cho OpenAI API yêu cầu thẻ tín dụng quốc tế đã bật mua hàng ở nước ngoài. Tại Kunavo, checkout được xử lý bởi Stripe và Pix xuất hiện dưới dạng phương thức thanh toán cho người thanh toán từ Brazil — số tiền bằng real và đối soát ngay lập tức. Thẻ quốc tế (Visa, Mastercard, American Express), Apple Pay và Google Pay vẫn khả dụng cho những người muốn dùng.

Phí theo token được tính bằng USD: với Pix, Stripe hiển thị quy đổi sang real tại thời điểm thanh toán; với thẻ, quy đổi tuân theo tỷ giá của đơn vị phát hành (hãy kiểm tra IOF và phí giao dịch quốc tế trong ứng dụng ngân hàng) — hướng dẫn từng bước nạp tiền bằng Pix có trong hướng dẫn thanh toán API bằng Pix. Ví là trả trước — nạp tối thiểu $10, không đăng ký thuê bao và không tự động gia hạn, với số dư không bao giờ hết hạn.

Nên dùng model nào

gpt-5-6-sol là GPT được tinh chỉnh cho mã và là lựa chọn tự nhiên mặc định của CLI này, với $2,00 / $12,00 cho mỗi 1M token so với $5,00 / $30,00 theo giá niêm yết của OpenAI — hiện OpenAI tính giá khuyến mãi $4,00 / $20,00, áp dụng ít nhất đến 21 tháng 11, 2026 theo trang giá. Toàn bộ mức giá có trên trang giá.

Chạy model Claude trên Codex CLI

Điều này thường khiến mọi người bất ngờ: Codex CLI bị ràng buộc bởi giao thức, không phải model. Nó sử dụng định dạng Responses, và bất kỳ model trò chuyện nào phía sau endpoint đó đều có thể phản hồi. Trỏ đến claude-opus-5 và CLI sẽ chạy xuyên suốt từ đầu đến cuối — bao gồm cả các lệnh gọi công cụ, vì vậy agent vẫn tiếp tục đọc tệp, đề xuất chỉnh sửa và chạy lệnh.

# Mesmo bloco de provider, outro modelo — sem chave nova, sem config nova.
model          = "claude-opus-5"
model_provider = "kunavo"

[model_providers.kunavo]
name     = "kunavo"
base_url = "https://api.kunavo.com/v1"
env_key  = "KUNAVO_API_KEY"
wire_api = "responses"

Gateway chuyển đổi yêu cầu Responses sang API Anthropic Messages gốc và chuyển phản hồi trở lại định dạng Responses. Một lưu ý thẳng thắn: Codex gửi các mục reasoning không trong suốt mà chỉ model Responses gốc mới có thể tiếp nhận, và chúng bị loại bỏ trên đường đến upstream không phải GPT. Model mất bản nháp riêng của lượt trước; bản chép lại hiển thị mà nó dựa vào vẫn nguyên vẹn. Trên thực tế, điều này làm giảm một chút tính liên tục trong các chuỗi suy luận dài, nhưng không ảnh hưởng đến các vòng lặp chỉnh sửa-chạy-sửa thông thường.

Nếu bạn muốn dùng Claude cụ thể, Claude Code được xây dựng cho mục đích đó và truyền cache_control mà không cần dịch. Nhưng nếu bạn thích sandbox của Codex CLI và muốn chạy Claude phía sau nó, sự kết hợp này vẫn khả thi.

Một phiên làm việc tốn bao nhiêu

Các CLI agent gửi lại system prompt, lịch sử tác vụ và ngữ cảnh tệp ở mỗi bước, vì vậy token tích lũy nhanh hơn số bước gợi ý. Một bước điển hình có khoảng 25.000 token đầu vào và 1.200 token đầu ra:

Nói cách khác: một lần nạp $10 bằng Pix chi trả cho khoảng 8 tác vụ agent 20 bước. Và các yêu cầu thất bại không bị tính phí — lỗi 5xx giữa một phiên làm việc không biến thành một dòng trên hóa đơn.

Khi có điều gì đó không hoạt động

Trước khi đổ lỗi cho Codex, hãy xác minh rằng khóa và endpoint có phản hồi:

# Confirme a chave e o endpoint antes de culpar o Codex.
curl https://api.kunavo.com/v1/responses \
  -H "Authorization: Bearer $KUNAVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-6-sol",
    "input": "Responda OK e nada mais."
  }'

• 404 — provider không triển khai /v1/responses, hoặc base_url đã bao gồm /responses. Codex tự thêm đường dẫn: base kết thúc bằng /v1.
• 401 — biến được chỉ định trong env_key đang trống trong shell đã mở Codex. Kiểm tra bằng echo $KUNAVO_API_KEY ngay trong terminal đó.
• 402 — số dư không đủ: nạp thêm trong billing (Pix được ghi nhận ngay).
• model_not_found — slug của model không tồn tại trong danh mục; kiểm tra tại /models.

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