Codex CLI là công cụ rất mạnh để hỗ trợ lập trình bằng AI. Tuy nhiên, khi dùng mặc định qua tài khoản OpenAI/ChatGPT, người dùng có thể gặp giới hạn quota hoặc credit.
OpenRouter giúp giải quyết bài toán này bằng cách đóng vai trò như một “cổng trung gian” cho nhiều model AI. Thay vì Codex CLI gọi trực tiếp model mặc định của OpenAI, ta có thể cấu hình để Codex CLI gọi qua OpenRouter.
Mô hình hoạt động sẽ là:
Codex CLI → OpenRouter → Model AI được chọnƯu điểm:
OpenRouter có tài liệu riêng hướng dẫn tích hợp với Codex CLI, trong đó họ khuyến nghị cấu hình một provider riêng tên openrouter thay vì ghi đè provider mặc định của OpenAI.
Trước khi làm, cần hiểu rõ điểm này:
Codex CLI chạy trong PowerShell / Terminal → có thể cấu hình dùng OpenRouter
Codex Desktop / app chính thức → thường vẫn dùng quota OpenAI/ChatGPT mặc địnhVì vậy, nếu mục tiêu là dùng OpenRouter để tiết kiệm chi phí hoặc tránh giới hạn quota Codex native, hãy chạy bằng lệnh:
codextrong PowerShell hoặc terminal.
Nếu mở Codex Desktop bằng giao diện app, nhiều khả năng vẫn dùng quota OpenAI/ChatGPT mặc định.
Trước khi cấu hình, cần có:
API key OpenRouter thường có dạng:
sk-or-xxxxxxxxxxxxxxxxKhông chia sẻ API key này lên chat, email công khai, GitHub hoặc tài liệu nội bộ không được kiểm soát.
Đăng nhập OpenRouter, vào phần API Keys và tạo key mới.
Nên đặt tên key theo người dùng hoặc thiết bị, ví dụ:
codex-huong-windows
codex-dev-ngoc
codex-dev-quyLàm vậy sẽ dễ quản lý nếu sau này cần khóa key, kiểm tra usage hoặc giới hạn chi phí cho từng nhân viên.
OpenRouter có trang quản lý key và usage, đồng thời cung cấp endpoint để kiểm tra thông tin key, credit limit và usage.
Mở PowerShell và chạy:
[Environment]::SetEnvironmentVariable("OPENROUTER_API_KEY", "sk-or-xxxxxxxxxxxxxxxx", "User")
$env:OPENROUTER_API_KEY = "sk-or-xxxxxxxxxxxxxxxx"Thay sk-or-xxxxxxxxxxxxxxxx bằng key thật.
Kiểm tra lại:
echo $env:OPENROUTER_API_KEYNếu hiện ra key dạng sk-or-... là được.
Nếu không hiện gì, đóng PowerShell rồi mở lại, sau đó chạy lại:
echo $env:OPENROUTER_API_KEYCodex CLI dùng file cấu hình tại:
C:\Users\<Tên user>\.codex\config.tomlTrên máy Windows thường mở bằng lệnh:
notepad $env:USERPROFILE\.codex\config.tomlNếu thư mục .codex chưa tồn tại, chạy:
mkdir $env:USERPROFILE\.codex
notepad $env:USERPROFILE\.codex\config.tomlCodex có tài liệu cấu hình config.toml, trong đó hỗ trợ khai báo model_provider, model_providers, base_url, env_key và wire_api cho provider tùy chỉnh.
Trước khi sửa, nên backup file cũ.
Chạy trong PowerShell:
copy $env:USERPROFILE\.codex\config.toml $env:USERPROFILE\.codex\config.backup.tomlNếu sau này cấu hình lỗi, chỉ cần khôi phục lại file backup.
Mở file:
notepad $env:USERPROFILE\.codex\config.tomlỞ phần đầu file, đặt cấu hình như sau:
model = "openai/gpt-5.1-codex-mini"
model_provider = "openrouter"
model_reasoning_effort = "low"
model_context_window = 20000
model_max_output_tokens = 12000
[model_providers.openrouter]
name = "OpenRouter"
base_url = "https://openrouter.ai/api/v1"
env_key = "OPENROUTER_API_KEY"
wire_api = "responses"Trong đó:
model = model muốn dùng qua OpenRouter
model_provider = provider mà Codex sẽ gọi
base_url = endpoint API của OpenRouter
env_key = tên biến môi trường chứa API key
wire_api = "responses" để Codex dùng Responses APIOpenRouter lưu ý rằng với Codex CLI, nên dùng wire_api = "responses" và tạo provider riêng tên openrouter.
Nếu Codex hiện cảnh báo:
Skill descriptions were shortened to fit the 2% skills context budget.thì không phải lỗi nghiêm trọng. Nó chỉ có nghĩa là Codex đang bật quá nhiều skills/plugins, nên phần mô tả skill bị rút gọn.
Nếu chỉ dùng Codex để code, có thể tắt bớt plugin như Gmail, Google Drive, Notion, Canva, PDF, Spreadsheets.
Thêm hoặc sửa các đoạn sau trong config.toml:
[plugins."gmail@openai-curated"]
enabled = false
[plugins."google-drive@openai-curated"]
enabled = false
[plugins."notion@openai-curated"]
enabled = false
[plugins."google-calendar@openai-curated"]
enabled = false
[plugins."canva@openai-curated"]
enabled = false
[plugins."documents@openai-primary-runtime"]
enabled = false
[plugins."spreadsheets@openai-primary-runtime"]
enabled = false
[plugins."presentations@openai-primary-runtime"]
enabled = false
[plugins."pdf@openai-primary-runtime"]
enabled = false
[plugins."template-creator@openai-primary-runtime"]
enabled = false
[plugins."browser@openai-bundled"]
enabled = trueCó thể giữ browser nếu thường cần Codex đọc web hoặc kiểm tra giao diện.
Đóng PowerShell đang mở, sau đó mở lại PowerShell mới.
Đi tới thư mục project:
cd D:\xampp\htdocs\aiwebChạy Codex:
codexNhập prompt test:
Chỉ trả lời "OK OpenRouter", không đọc file, không sửa gì.Nếu Codex trả lời được, tiếp tục vào OpenRouter Activity để kiểm tra có request mới không.
Nếu Activity có request, nghĩa là cấu hình đã thành công:
Codex CLI → OpenRouter → Model AICó thể kiểm tra key bằng PowerShell:
curl https://openrouter.ai/api/v1/key -H "Authorization: Bearer $env:OPENROUTER_API_KEY"Nếu trả về thông tin key, usage hoặc limit, nghĩa là API key đang hoạt động.
Nếu lỗi authentication, kiểm tra lại biến môi trường:
echo $env:OPENROUTER_API_KEYCó 3 hướng chọn model.
model = "openai/gpt-5.1-codex-mini"Phù hợp với:
model = "openai/gpt-5.3-codex"Phù hợp với:
Tên model trên OpenRouter có thể thay đổi theo thời gian, nên nên kiểm tra lại trong trang Models của OpenRouter trước khi áp dụng cho team.
OpenRouter có router model miễn phí:
model = "openrouter/free"Router này chọn trong nhóm model miễn phí có sẵn và có thể xem model nào đã chạy trong phần Activity.
Tuy nhiên, không nên kỳ vọng model free xử lý tốt các task coding phức tạp. Nên dùng để test kết nối, test prompt nhẹ hoặc các việc phụ.
Với nhân viên dùng Codex CLI hằng ngày, có thể dùng cấu hình sau:
model = "openai/gpt-5.1-codex-mini"
model_provider = "openrouter"
model_reasoning_effort = "low"
model_context_window = 20000
model_max_output_tokens = 12000
[model_providers.openrouter]
name = "OpenRouter"
base_url = "https://openrouter.ai/api/v1"
env_key = "OPENROUTER_API_KEY"
wire_api = "responses"
[plugins."gmail@openai-curated"]
enabled = false
[plugins."google-drive@openai-curated"]
enabled = false
[plugins."notion@openai-curated"]
enabled = false
[plugins."google-calendar@openai-curated"]
enabled = false
[plugins."canva@openai-curated"]
enabled = false
[plugins."documents@openai-primary-runtime"]
enabled = false
[plugins."spreadsheets@openai-primary-runtime"]
enabled = false
[plugins."presentations@openai-primary-runtime"]
enabled = false
[plugins."pdf@openai-primary-runtime"]
enabled = false
[plugins."template-creator@openai-primary-runtime"]
enabled = false
[plugins."browser@openai-bundled"]
enabled = trueNếu muốn đưa cho nhân viên tự cài, có thể tạo file:
setup-codex-openrouter.ps1Dán nội dung sau:
# setup-codex-openrouter.ps1
# Cau hinh Codex CLI dung OpenRouter tren Windows
Write-Host "=== Setup Codex CLI + OpenRouter ===" -ForegroundColor Cyan
# 1. Nhap API key
$apiKey = Read-Host "Nhap OpenRouter API key, dang sk-or-..."
if ([string]::IsNullOrWhiteSpace($apiKey)) {
Write-Host "Chua nhap API key. Thoat." -ForegroundColor Red
exit 1
}
if (-not $apiKey.StartsWith("sk-or-")) {
Write-Host "Canh bao: API key khong bat dau bang sk-or-. Van tiep tuc..." -ForegroundColor Yellow
}
# 2. Luu API key vao User Environment
[Environment]::SetEnvironmentVariable("OPENROUTER_API_KEY", $apiKey, "User")
$env:OPENROUTER_API_KEY = $apiKey
Write-Host "Da luu OPENROUTER_API_KEY vao User Environment." -ForegroundColor Green
# 3. Tao thu muc .codex
$codexDir = Join-Path $env:USERPROFILE ".codex"
$configPath = Join-Path $codexDir "config.toml"
if (!(Test-Path $codexDir)) {
New-Item -ItemType Directory -Path $codexDir | Out-Null
Write-Host "Da tao thu muc: $codexDir" -ForegroundColor Green
}
# 4. Backup config cu neu co
if (Test-Path $configPath) {
$backupPath = "$configPath.backup-$(Get-Date -Format 'yyyyMMdd-HHmmss')"
Copy-Item $configPath $backupPath
Write-Host "Da backup config cu: $backupPath" -ForegroundColor Yellow
}
# 5. Ghi config moi
$config = @'
model = "openai/gpt-5.1-codex-mini"
model_provider = "openrouter"
model_reasoning_effort = "low"
model_context_window = 20000
model_max_output_tokens = 12000
[model_providers.openrouter]
name = "OpenRouter"
base_url = "https://openrouter.ai/api/v1"
env_key = "OPENROUTER_API_KEY"
wire_api = "responses"
[plugins."gmail@openai-curated"]
enabled = false
[plugins."google-drive@openai-curated"]
enabled = false
[plugins."notion@openai-curated"]
enabled = false
[plugins."google-calendar@openai-curated"]
enabled = false
[plugins."canva@openai-curated"]
enabled = false
[plugins."documents@openai-primary-runtime"]
enabled = false
[plugins."spreadsheets@openai-primary-runtime"]
enabled = false
[plugins."presentations@openai-primary-runtime"]
enabled = false
[plugins."pdf@openai-primary-runtime"]
enabled = false
[plugins."template-creator@openai-primary-runtime"]
enabled = false
[plugins."browser@openai-bundled"]
enabled = true
'@
Set-Content -Path $configPath -Value $config -Encoding UTF8
Write-Host "Da ghi config Codex OpenRouter:" -ForegroundColor Green
Write-Host $configPath
# 6. Kiem tra lenh codex
$codexCmd = Get-Command codex -ErrorAction SilentlyContinue
if ($null -eq $codexCmd) {
Write-Host ""
Write-Host "CANH BAO: Chua tim thay lenh 'codex' trong PATH." -ForegroundColor Yellow
Write-Host "Hay cai Codex CLI truoc, hoac mo lai terminal neu vua cai."
} else {
Write-Host ""
Write-Host "Tim thay Codex CLI tai:" -ForegroundColor Green
Write-Host $codexCmd.Source
}
# 7. Huong dan test
Write-Host ""
Write-Host "=== Hoan tat ===" -ForegroundColor Cyan
Write-Host "Hay dong PowerShell/Cursor/VS Code roi mo lai."
Write-Host ""
Write-Host "Test bang lenh:"
Write-Host " echo $env:OPENROUTER_API_KEY"
Write-Host " codex"
Write-Host ""
Write-Host "Prompt test trong Codex:"
Write-Host ' Chi tra loi "OK OpenRouter", khong doc file, khong sua gi.'
Write-Host ""
Write-Host "Model dang cau hinh: openai/gpt-5.1-codex-mini"Cách chạy script:
powershell -ExecutionPolicy Bypass -File .\setup-codex-openrouter.ps1Sau khi chạy xong:
1. Đóng PowerShell / VS Code / Cursor.
2. Mở lại terminal mới.
3. Chạy lệnh codex.
4. Nhập prompt test.
5. Kiểm tra OpenRouter Activity.echo $env:OPENROUTER_API_KEY không hiện gìNguyên nhân: biến môi trường chưa được set trong phiên PowerShell hiện tại.
Cách sửa:
[Environment]::SetEnvironmentVariable("OPENROUTER_API_KEY", "sk-or-xxxxxxxx", "User")
$env:OPENROUTER_API_KEY = "sk-or-xxxxxxxx"
echo $env:OPENROUTER_API_KEYSau đó đóng PowerShell và mở lại.
Nếu thấy lỗi kiểu:
You've hit your usage limit. Upgrade to Pro...nghĩa là phiên Codex đó vẫn đang dùng quota OpenAI/ChatGPT native, chưa đi qua OpenRouter.
Cách xử lý:
1. Đóng Codex Desktop nếu đang mở.
2. Mở PowerShell mới.
3. Chạy codex bằng terminal.
4. Kiểm tra OpenRouter Activity có request mới không.Nhớ rằng Codex Desktop/app có thể vẫn dùng quota mặc định. OpenRouter chủ yếu áp dụng chắc chắn khi chạy qua Codex CLI.
Model metadata not foundVí dụ:
Model metadata for ~openai/gpt-latest not found.Lỗi này thường xảy ra khi dùng alias model. Nên dùng model slug cụ thể hơn, ví dụ:
model = "openai/gpt-5.1-codex-mini"hoặc chọn một slug chính xác từ trang Models của OpenRouter.
402 Payment RequiredVí dụ:
unexpected status 402 Payment RequiredTheo OpenRouter, lỗi 402 payment_required nghĩa là tài khoản hoặc API key không đủ credit. Cách xử lý là nạp thêm credit hoặc giảm request/token.
Nếu vừa nạp credit mà vẫn lỗi, kiểm tra:
1. API key có bị đặt credit limit thấp không?
2. Account có balance âm không?
3. Codex có đang xin max_tokens quá lớn không?Có thể giảm cấu hình:
model_reasoning_effort = "minimal"
model_context_window = 16000
model_max_output_tokens = 8000OpenRouter cũng lưu ý rằng nếu tài khoản có credit balance âm, có thể gặp lỗi 402 kể cả khi gọi model free.
Thông báo:
Skill descriptions were shortened to fit the 2% skills context budget.Đây không phải lỗi nghiêm trọng. Nó chỉ báo rằng Codex đang bật nhiều skills/plugins quá.
Cách xử lý:
Tắt bớt plugin không cần cho coding.
Giữ browser nếu cần.
Restart Codex.Nếu triển khai cho nhân viên, có thể áp dụng quy trình sau:
1. Admin tạo OpenRouter account.
2. Tạo API key riêng cho từng nhân viên hoặc từng máy.
3. Đặt giới hạn credit cho từng key nếu cần.
4. Gửi script setup-codex-openrouter.ps1 cho nhân viên.
5. Nhân viên chạy script và nhập API key.
6. Test bằng prompt "OK OpenRouter".
7. Admin kiểm tra Activity trên OpenRouter.
8. Khi cần task khó, đổi model mạnh hơn.Gợi ý phân tầng model:
| Nhu cầu | Model gợi ý |
|---|---|
| Test kết nối | openrouter/free |
| Việc code thường ngày | openai/gpt-5.1-codex-mini |
| Debug/refactor khó | openai/gpt-5.3-codex |
| Tiết kiệm chi phí | model mini hoặc free |
| Việc quan trọng | model mạnh, context cao hơn |
Sau khi cài xong, kiểm tra nhanh:
[ ] Đã có OpenRouter API key.
[ ] Đã set biến OPENROUTER_API_KEY.
[ ] echo $env:OPENROUTER_API_KEY có hiện key.
[ ] File C:\Users\<User>\.codex\config.toml có model_provider = "openrouter".
[ ] Có block [model_providers.openrouter].
[ ] wire_api = "responses".
[ ] Chạy codex từ PowerShell.
[ ] Prompt test trả lời được.
[ ] OpenRouter Activity có request mới.
[ ] Không còn báo usage limit của ChatGPT/Codex native.Cấu hình Codex CLI dùng OpenRouter là một cách thực tế để team developer dùng AI coding linh hoạt hơn.
Thay vì bị phụ thuộc hoàn toàn vào quota mặc định của Codex/OpenAI, ta có thể:
- Chọn model phù hợp từng loại việc.
- Dùng model rẻ cho task nhẹ.
- Dùng model mạnh cho task khó.
- Theo dõi chi phí qua OpenRouter.
- Triển khai nhanh cho nhiều nhân viên bằng script.Điểm quan trọng nhất cần nhớ:
Codex CLI chạy trong terminal có thể dùng OpenRouter.
Codex Desktop/app thường vẫn dùng quota OpenAI mặc định.Với team nhỏ hoặc startup đang dùng AI để tăng tốc phát triển phần mềm, đây là một cấu hình đáng làm. Nó giống như gắn thêm một bảng điều khiển model cho Codex: việc nhẹ dùng số tiết kiệm, việc khó mới bật chế độ mạnh.
