CLIProxyAPI

macOS

Windows

Cho Codex App dùng chung account pool của CCS

Mặc định Codex App chỉ OAuth với một OpenAI account. Cách đó ổn cho một tài khoản, nhưng sẽ vướng khi bạn có nhiều subscription accounts và muốn app dùng chung pool đang quản lý trong CCS.

Giải pháp thực tế: giữ Codex App làm giao diện, trỏ provider config về CLIProxyAPI local, rồi để CCS xử lý rotation account, quota check, pause/resume, và failover phía sau.

Sau khi setup: Codex App vẫn là UI; CCS lo routing phía sau.

Phần setup chỉ đổi provider routing và launch environment. Không thay trải nghiệm app. Tới setup chính.

config.toml

model_provider cliproxy

model_context_window 272000

wire_api responses

127.0.0.1:8317/api/provider/codex

Codex App

desktop UI

App người dùng thấy vẫn giữ nguyên.

CLIProxyAPI

127.0.0.1:8317

Route local nói đúng chuẩn Codex Responses.

CCS pool

quota + routing

Rotation, pause/resume, quota checks.

Cài đặt

Cài Codex App từ docs chính thức của OpenAI

Dùng trang cài đặt chính thức cho các luồng app macOS và Windows hiện tại. Sau khi cài xong, quay lại đây để cấu hình CLIProxyAPI routing.

Mở official install docs

Chưa biết CCS?

CCS đứng phía sau route của Codex App

CCS là routing layer cho Codex account pool: quản lý CLIProxyAPI, quota checks, pause/resume và dashboard controls. Phần setup Codex App đầy đủ nằm ngay bên dưới; guide CCS chỉ là background thêm khi bạn cần hiểu workflow CCS rộng hơn.

CCS Giữ account pool, routing policy, quota visibility, và dashboard controls.

CLIProxyAPI Expose Codex Responses endpoint local ở port 8317.

Mở guide CCS

Setup Codex App với CCS/CLIProxyAPI

Cho desktop app route qua shared pool

Vai trò nên rõ ràng: Codex App vẫn là desktop interface, CLIProxyAPI là endpoint local, còn CCS quản lý routing, account rotation và quota visibility.

Với macOS desktop, làm tuần tự các bước bên dưới. Sau bước verify cuối, quit hẳn Codex App rồi mở lại.

127.0.0.1:8317/api/provider/codex

Cài đặt và add codex accounts

Skip nếu đã có CCS và Codex accounts. Nếu chưa, add account trong ccs config, rồi check quota.

optional · ccs + accounts

# Bỏ qua nếu đã cài CCS và đã có Codex accounts trong pool.
$npm install -g @kaitranntt/ccs

# Mở dashboard CCS, rồi thêm account ở CLIProxy -> Codex -> Accounts.
$ccs config

# Kiểm tra CLIProxyAPI thấy được trạng thái Codex account.
$ccs cliproxy quota --provider codex

Lưu token hiện có vào macOS Keychain

CLIPROXY_API_KEY là token vào CLIProxyAPI. Với CCS thường là ccs-internal-managed; self-hosted proxy dùng key riêng.

shell · keychain

$security add-generic-password \
   -a "$USER" \
   -s CLIPROXY_API_KEY \
   -w "$CLIPROXY_API_KEY" \
   -U

Tạo auth helper

Ghi file helper này. Codex chạy nó để đọc token Keychain qua stdout.

shell · create file

$mkdir -p "$HOME/.codex/bin"
$touch "$HOME/.codex/bin/cliproxy-token"

file · $HOME/.codex/bin/cliproxy-token

#!/bin/zsh
set -euo pipefail

service="CLIPROXY_API_KEY"
account="${USER:-$(id -un)}"

token="$(security find-generic-password -a "$account" -s "$service" -w 2>/dev/null || true)"

if [[ -z "$token" ]]; then
  token="$(security find-generic-password -s "$service" -w 2>/dev/null || true)"
fi

if [[ -z "$token" ]]; then
  print -u2 "Missing Keychain item: service=$service account=$account"
  exit 1
fi

printf '%s\n' "$token"

shell · chmod 700

$chmod 700 "$HOME/.codex/bin/cliproxy-token"

Trỏ Codex App về CLIProxyAPI

Set provider là cliproxy và dùng helper làm auth command. model_context_window chỉ dành cho metadata của custom proxy; bỏ khi fallback về OpenAI/OAuth native.

toml · config.toml

model = "gpt-5.5"
# Tùy chọn cho custom provider/proxy khi Codex không tự suy ra metadata model.
# Bỏ dòng này khi fallback về OpenAI/OAuth native; Codex sẽ tự detect.
model_context_window = 272000
model_provider = "cliproxy"

[model_providers.cliproxy]
name = "CLIProxy"
base_url = "http://127.0.0.1:8317/api/provider/codex"
wire_api = "responses"

[model_providers.cliproxy.auth]
# Tạo ở bước 3
# Nếu bản Codex của bạn không mở rộng $HOME ở đây, thay bằng kết quả của: echo "$HOME"
command = "$HOME/.codex/bin/cliproxy-token"
timeout_ms = 5000
refresh_interval_ms = 300000

Verify rồi mở lại Codex App

Check helper, Keychain, port 8317 và doctor. Chỉ mở lại app khi doctor báo 0 warn | 0 fail.

shell · verify

# Kiểm tra helper đọc được token không rỗng từ Keychain.
$test -n "$("$HOME/.codex/bin/cliproxy-token")" && echo "Keychain helper OK"

# Kiểm tra mục Keychain tồn tại. Lệnh này in thông tin mô tả, không in token.
$security find-generic-password -a "$USER" -s CLIPROXY_API_KEY

# Kiểm tra CLIProxyAPI local đang mở port 8317.
$lsof -nP -iTCP:8317 -sTCP:LISTEN

# Kiểm tra cấu hình, xác thực và kết nối của Codex. Quan trọng nhất là "0 warn | 0 fail".
$codex doctor --summary --no-color --ascii

Provider switch

Giữ fallback OAuth khi CLIProxyAPI chậm

Không cần xóa setup CLIProxyAPI. Giữ nguyên provider block cliproxy, rồi xóa/comment dòng model_provider active hoặc set explicit thành openai. Khi bỏ trống, Codex mặc định dùng provider built-in openai. openai dùng đường Codex/OpenAI OAuth bình thường và không cần model_context_window; cliproxy route qua CCS/CLIProxyAPI và có thể cần dòng này khi không suy ra được metadata.

Dùng lại OAuth bình thường

Dùng khi CLIProxyAPI bị latency rõ rệt hoặc local proxy không healthy. model_provider = "openai" là explicit nhưng không bắt buộc; bỏ trống model_provider cũng fallback về OpenAI. Codex App cần đã sign in bằng ChatGPT/OpenAI OAuth.

toml · OAuth fallback

# Fallback nhanh khi CLIProxyAPI bị chậm
# Codex mặc định dùng OpenAI khi model_provider bị bỏ trống.
# Comment/xóa selector CLIProxy, hoặc set explicit fallback:
model_provider = "openai"

# Không set model_context_window ở đây.
# OpenAI/OAuth native để Codex tự detect metadata model.

# Để nguyên block [model_providers.cliproxy].
# Chỉ đổi hoặc xóa dòng model_provider active ở trên.

Bật lại CLIProxyAPI

Dùng lại khi cần CCS account rotation, quota checks, pause/resume, hoặc failover.

toml · CLIProxyAPI route

# Bật lại khi quota/độ trễ của CLIProxyAPI đã ổn
model_provider = "cliproxy"

# Dùng lại khối [model_providers.cliproxy] và auth helper đã có.

Verify sau mỗi lần switch

Sau khi đổi hoặc xóa model_provider, chạy doctor một lần. Pass signal: 0 warn | 0 fail. Sau đó quit hẳn và mở lại Codex App để desktop process load lại ~/.codex/config.toml.

shell · verify switch

$codex doctor --summary --no-color --ascii
# Đạt khi dòng tổng kết kết thúc bằng "0 warn | 0 fail".
# Sau đó thoát hẳn Codex App rồi mở lại.

Troubleshooting

macOS báo thiếu CLIPROXY_API_KEY

Đây là case được fix bằng bước 3-5 ở trên. Nếu Codex App vẫn báo Missing environment variable: CLIPROXY_API_KEY, thường là active provider vẫn đọc env_key trong ~/.codex/config.toml thay vì [model_providers.cliproxy.auth].

Vì sao setup không dùng env_key

CLI có thể chạy vì zsh/bash có CLIPROXY_API_KEY. Dock, Finder, Spotlight, và Login Items không luôn inherit shell env đó.

Vì vậy setup chính dùng [model_providers.cliproxy.auth] thay cho env_key trên macOS desktop.

toml · env_key mode to avoid on macOS desktop app

model_provider = "cliproxy"

[model_providers.cliproxy]
name = "CLIProxy"
base_url = "http://127.0.0.1:8317/api/provider/codex"
env_key = "CLIPROXY_API_KEY"
wire_api = "responses"

Plugin behavior

UI Plugins của app và plugin runtime của CLI bị gate khác nhau

CLIProxyAPI không tự động làm hỏng plugin runtime. Điểm cần chú ý là UI Plugins của Codex App: bundle app disable tab/sidebar Plugins khi authMethod !== "chatgpt" và hiện tooltip kiểu Please sign in with ChatGPT to use plugins.

Codex App UI

Nếu route qua CLIProxyAPI làm app rơi vào API-key auth mode, UI browse/manage Plugins sẽ bị disabled. Muốn UI này sáng lại thì Codex App phải auth bằng ChatGPT.

Codex CLI / agent runtime

Plugin local vẫn dùng được khi config có [plugins."..."] enabled = true và marketplace/cache tồn tại. Phần này tách biệt với UI browse/manage Plugins trong Codex App.

CLIPROXY_API_KEY

Fallback: chế độ env_key

Skip section này nếu đã setup macOS Keychain helper ở trên. Chỉ dùng khi bạn cố tình giữ env_key = "CLIPROXY_API_KEY" hoặc đang test Windows path chưa verify.

Quay lại setup khuyến nghị

Windows expected path

Chưa verify

Chỉ dùng nếu provider của Codex App trên Windows vẫn dùng env_key = "CLIPROXY_API_KEY". Luồng này chưa được test end-to-end trên Windows Codex App; cần verify bằng PowerShell session mới và mở lại Codex App trước khi dùng chính thức.

Mở PowerShell session mới.
Confirm user env value tồn tại.
Restart Codex App.
Chạy `codex doctor` trước khi dùng chính thức.

Chỉ cho Codex launch từ terminal

Chỉ dùng khi Codex được start từ zsh, bash, fish, hoặc script terminal và provider vẫn dùng `env_key`.

shell · env

# zsh/bash
$export CLIPROXY_API_KEY="ccs-internal-managed"

# fish
$set -gx CLIPROXY_API_KEY ccs-internal-managed

Fallback cho app macOS desktop

Chỉ là fallback. Chỉ dùng thay auth helper Keychain nếu bạn cố tình giữ `env_key`; sau reboot có thể phải chạy lại.

shell · launchctl

$launchctl setenv CLIPROXY_API_KEY ccs-internal-managed
$launchctl getenv CLIPROXY_API_KEY

Windows

Chưa verify

Guidance PowerShell cho chế độ env_key. Xem đây là expected behavior cho tới khi được test trên Windows Codex App.

powershell · unverified env_key

# PowerShell: phiên hiện tại
$$env:CLIPROXY_API_KEY = "ccs-internal-managed"

# Lưu cho các phiên Windows mới
$setx CLIPROXY_API_KEY "ccs-internal-managed"

# Kiểm tra trong PowerShell mới sau khi mở lại Codex App
$[Environment]::GetEnvironmentVariable("CLIPROXY_API_KEY", "User")
$codex doctor --summary --no-color --ascii

Muốn Remote Control dùng chung route này?

Page này chỉ cover request routing của Codex App. Remote Control có luồng Codex riêng vì còn cần app server, remote identity checks, và session handoff behavior.

Remote Control cho Codex