Khóa API Codex CLI — thiết lập nhà cung cấp tùy chỉnh hoạt động

Khóa API Codex là bất kỳ khóa nào mà Codex CLI có thể dùng để tính phí theo token thay cho gói ChatGPT: khóa OpenAI API từ platform.openai.com hoặc khóa của provider như sk-kn- của Kunavo, được Codex đọc từ biến môi trường do env_key chỉ định trong khối model_providers. Provider phải cung cấp Responses API — đây là yêu cầu duy nhất bên dưới.

Codex CLI là tác nhân lập trình mã nguồn mở trên terminal của OpenAI và chạy bằng đăng nhập ChatGPT hoặc khóa API. Tuyến khóa API là phần đáng tìm hiểu: tính phí theo token, không có phí hàng tháng và là tuyến duy nhất cho phép trỏ CLI tới provider khác — hoặc hoàn toàn sang một họ mô hình khác. Hướng dẫn này trình bày cấu hình thực tế, yêu cầu duy nhất khiến phần lớn gateway gặp lỗi và chi phí thực tế của một phiên.

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

Codex CLI nghiêm ngặt hơn hầu hết công cụ khi dùng endpoint tùy chỉnh. Khối model_providers có khóa wire_api, và chỉ chấp nhận chính xác một giá trị: responses. Điều đó có nghĩa provider tùy chỉnh phải cung cấp Responses API của OpenAI tại POST /v1/responses — không phải /v1/chat/completions phổ biến hơn nhiều. Hầu hết gateway tương thích OpenAI chỉ cung cấp tuyến sau, đó là lý do rất nhiều gateway không thể điều khiển Codex CLI, bất kể bạn cung cấp base_url nào.

Kunavo cung cấp cả hai giao diện, vì vậy cấu hình bên dưới hoạt động như đã viết.

Cấu hình

Codex đọc ~/.codex/config.toml. Hai khóa cấp cao nhất chọn mô hình và provider; khối provider mô tả cách kết nối tới provider đó:

# ~/.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"

Lưu ý điều không có trong tệp: chính khóa API. env_key chỉ định một biến môi trường và Codex đọc khóa từ đó khi khởi chạy — vì vậy tệp cấu hình an toàn để commit hoặc chia sẻ.

# Codex reads the key from the variable named by env_key.
export KUNAVO_API_KEY="sk-kn-..."     # create at kunavo.com/app/keys

# Persist it (pick the file your shell actually loads):
echo 'export KUNAVO_API_KEY="sk-kn-..."' >> ~/.zshrc

codex "explain the structure of this repository"

Tạo khóa tại bảng điều khiển sau khi đăng ký và nạp $10. Khóa chỉ hiển thị một lần, hãy lưu ngay. Nếu codex đã chạy trong một shell khác, hãy khởi động lại — biến được đọc khi khởi chạy, không phải ở mỗi yêu cầu.

Xác minh trước khi gỡ lỗi

Nếu có vấn đề, hãy xác định đó là khóa, endpoint hay CLI. Một yêu cầu là đủ:

# Confirm the key and the endpoint before blaming 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": "Say OK and nothing else."
  }'

Phản hồi JSON có nghĩa khóa và endpoint hợp lệ, vấn đề còn lại nằm ở config.toml. 401 có nghĩa khóa sai hoặc biến đang trống trong shell này. 404 trên model có nghĩa slug không khớp với danh mục.

Nên đặt mô hình nào

Giá trị model chỉ là một slug trên cùng endpoint, vì vậy đổi mô hình chỉ là sửa một từ — không cần khóa mới, không cần khối provider mới.

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

Chạy các mô hình Claude trong Codex CLI

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

# Same provider block, different model — no new key, no new config.
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 thành Anthropic Messages API và chuyển phản hồi trở lại dạng Responses. Một lưu ý quan trọng: Codex gửi các mục reasoning không trong suốt mà chỉ mô hình gốc Responses mới có thể sử dụng; các mục này bị loại bỏ khi chuyển tới upstream không phải GPT. Mô hình mất scratchpad riêng từ lượt trước; bản ghi hiển thị mà nó sử dụng 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 và không ảnh hưởng gì trong các vòng lặp chỉnh sửa-chạy-sửa thông thường.

Việc đó có phải ý tưởng hay hay không là câu hỏi khác với việc nó có hoạt động hay không. Nếu bạn muốn Claude cụ thể, Claude Code được xây dựng cho nó và truyền cache_control qua mà không dịch. Nhưng nếu bạn thích sandbox của Codex CLI và muốn chạy Claude phía sau, tổ hợp đó vẫn khả dụng.

Một phiên tốn bao nhiêu

Các CLI có khả năng hoạt động tự chủ gửi lại lời nhắc hệ thống, lịch sử tác vụ và ngữ cảnh tệp mới ở mỗi bước, nên token tích lũy nhanh hơn mức mà 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:

Vì giá output khác nhau giữa các họ mô hình nhiều hơn đáng kể so với giá input, công việc thiên về output sẽ thay đổi thứ hạng — hãy đưa số liệu của bạn vào trình tính chi phí thay vì tin vào một ví dụ duy nhất. Các yêu cầu thất bại không bị tính phí.

Khi tuyến khóa API có lợi hơn gói đăng ký

Gói ChatGPT bao gồm việc sử dụng Codex với mức phí hàng tháng cố định; khóa API chỉ tính cho những gì bạn chạy. Tuyến khóa có lợi khi bạn lập trình theo đợt thay vì hằng ngày, khi muốn giới hạn chi tiêu theo khóa và khả năng xem mức sử dụng thay vì hạn mức không minh bạch, hoặc khi muốn một mô hình mà gói đăng ký không cung cấp. Nó kém lợi hơn khi bạn là người dùng hằng ngày với cường độ cao — ở mức đó, phí cố định khó bị đánh bại. Hai tuyến không loại trừ nhau: profile Codex cho phép giữ cả hai và chuyển đổi theo từng tác vụ.

Khắc phục sự cố

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