Kết nối các mô hình bên ngoài với Codex

Hướng dẫn này trình bày hai phương thức tích hợp mô hình bên thứ ba được lưu trữ:

Trước tiên, bạn cần hiểu một hạn chế quan trọng:

Hướng dẫn này áp dụng cho các ứng dụng Codex chạy cục bộ, bao gồm Codex CLI, tiện ích Codex dành cho IDE và các ứng dụng máy tính để bàn đọc cùng một config.toml. Hiện tại, các cuộc trò chuyện trên Codex cloud không thể chuyển sang mô hình tùy chỉnh bằng cấu hình này.

Trước khi bắt đầu

Cài đặt hoặc cập nhật Codex CLI

npm install -g @openai/codex@latest
codex --version

Sau lần cài đặt đầu tiên, hãy chạy Codex ít nhất một lần:

codex

Thao tác này khởi tạo thư mục cấu hình người dùng.

Vị trí tệp cấu hình Codex

macOS và Linux:

~/.codex/config.toml

Windows:

%USERPROFILE%\.codex\config.toml

Hãy sao lưu tệp trước khi thay đổi.

macOS / Linux:

mkdir -p ~/.codex/backup
cp ~/.codex/config.toml \
  ~/.codex/backup/config.toml.$(date +%Y%m%d-%H%M%S) \
  2>/dev/null || true

PowerShell:

$codexDir = Join-Path $HOME ".codex"
$backupDir = Join-Path $codexDir "backup"
New-Item -ItemType Directory -Force -Path $backupDir | Out-Null

$configFile = Join-Path $codexDir "config.toml"
if (Test-Path $configFile) {
  $timestamp = Get-Date -Format "yyyyMMdd-HHmmss"
  Copy-Item $configFile (Join-Path $backupDir "config.toml.$timestamp")
}

Nhà cung cấp, MCP và cổng mô hình là những khái niệm khác nhau

Các khái niệm này giải quyết những vấn đề khác nhau:

• model_provider xác định nơi Codex gửi yêu cầu mô hình;
• MCP bổ sung công cụ và ngữ cảnh như GitHub, trình duyệt hoặc cơ sở dữ liệu;
• cổng mô hình xử lý việc chuyển đổi giao thức, xác thực, định tuyến, ghi nhật ký hoặc giới hạn tốc độ giữa Codex và mô hình thượng nguồn.

Để thay đổi mô hình nền tảng, hãy cấu hình nhà cung cấp thay vì MCP.

Bảo vệ API key

Không cam kết API key thật vào kho lưu trữ Git hoặc để lộ toàn bộ khóa trong ảnh chụp màn hình, nhật ký hay phiếu hỗ trợ.

Với nhà cung cấp được cấu hình thủ công, nên ưu tiên dùng biến môi trường:

[model_providers.example]
env_key = "EXAMPLE_API_KEY"

CC Switch lưu cấu hình nhà cung cấp trên máy cục bộ và sửa đổi cấu hình Codex cục bộ khi bạn chuyển đổi nhà cung cấp. Đây là công cụ mã nguồn mở của bên thứ ba, không phải sản phẩm của OpenAI. Chỉ cài đặt công cụ này từ trang web chính thức hoặc kho lưu trữ GitHub của CC Switch, đồng thời bảo vệ cơ sở dữ liệu, cấu hình và bản sao lưu cục bộ của công cụ.

1. Kết nối mô hình bên thứ ba bằng CC Switch

CC Switch là lựa chọn dễ dàng hơn cho hầu hết mô hình bên thứ ba. Công cụ này quản lý nhà cung cấp, API key, danh sách mô hình và định tuyến cục bộ, đồng thời có thể chuyển đổi các giao thức thượng nguồn không tương thích.

1.1 Những vấn đề CC Switch giải quyết

Các ứng dụng Codex hiện đại gửi yêu cầu Responses API, trong khi nhiều dịch vụ bên thứ ba cung cấp một trong các loại sau:

• OpenAI Chat Completions;
• Anthropic Messages;
• ID mô hình không được Codex liệt kê theo mặc định;
• tham số suy luận hoặc định dạng sự kiện truyền trực tuyến riêng của nhà cung cấp.

CC Switch có thể chuyển đổi đường dẫn yêu cầu như sau:

Codex
  │  Responses API
  ▼
CC Switch local route
  │  Converts the protocol and model name when required
  ▼
Third-party model API
  │
  ▼
CC Switch converts JSON, SSE, reasoning data, and tool calls back to Responses
  │
  ▼
Codex

Nhà cung cấp hỗ trợ Responses nguyên bản không cần chuyển đổi giao thức Chat. Nhà cung cấp Chat Completions hoặc Anthropic Messages cần định tuyến cục bộ.

1.2 Cài đặt CC Switch

Chỉ sử dụng các kênh phân phối chính thức:

• Trang web chính thức của CC Switch
• Kho lưu trữ GitHub của CC Switch
• Các bản phát hành CC Switch

Trên macOS, bạn nên dùng Homebrew:

brew install --cask cc-switch

Để cập nhật:

brew upgrade --cask cc-switch

Trên Windows, hãy tải trình cài đặt .msi hoặc gói lưu trữ di động từ Releases.

Trên Linux, hãy tải gói .deb, .rpm hoặc AppImage từ Releases. Nhãn có thể thay đổi đôi chút giữa các phiên bản, vì vậy hãy dùng bản phát hành ổn định mới nhất và xem các tùy chọn hiển thị trong ứng dụng là nguồn thông tin chính xác.

1.3 Điều kiện tiên quyết

Hãy chuẩn bị những nội dung sau:

1. Codex đã được cài đặt và khởi chạy ít nhất một lần;
2. CC Switch đã được cài đặt và khởi động đúng cách;
3. bạn có API key cho dịch vụ mô hình đích;
4. bạn đã xác nhận Base URL, ID mô hình và giao thức thượng nguồn trong tài liệu của nhà cung cấp;
5. nếu cần các tính năng tài khoản Codex chính thức, trước tiên hãy hoàn tất một lần đăng nhập chính thức.

Kiểm tra trạng thái đăng nhập Codex hiện tại:

codex login status

Đăng nhập khi cần:

codex login

Bạn cũng có thể đăng nhập bằng mã thiết bị:

codex login --device-auth

1.4 Không bắt buộc: duy trì đăng nhập chính thức khi dùng nhà cung cấp bên thứ ba

Tùy chọn này chủ yếu hữu ích khi bạn muốn giữ các tính năng máy tính để bàn, plugin chính thức hoặc tính năng điều khiển từ xa trong khi gửi yêu cầu mô hình đến nhà cung cấp bên thứ ba. Người dùng chỉ dùng CLI và không phụ thuộc vào các tính năng tài khoản chính thức có thể bỏ qua.

Thứ tự được đề xuất:

1. chọn OpenAI Official trong bảng Codex của CC Switch;
2. khởi chạy Codex và đăng nhập bằng tài khoản chính thức;
3. mở Settings → General → Codex App Enhancements trong CC Switch;
4. bật Keep official login when switching third-party providers;
5. thêm hoặc chuyển sang nhà cung cấp bên thứ ba.

Khi bật tùy chọn này, CC Switch sẽ cố gắng duy trì:

• ~/.codex/auth.json cho trạng thái đăng nhập chính thức;
• ~/.codex/config.toml cho nhà cung cấp bên thứ ba đang hoạt động, mô hình, điểm cuối và cấu hình xác thực.

auth.json chứa dữ liệu đăng nhập nhạy cảm. Không chia sẻ hoặc cam kết tệp này vào hệ thống quản lý phiên bản.

1.5 Thêm nhà cung cấp bên thứ ba

Mở CC Switch, chuyển sang bảng Codex cấp cao nhất rồi nhấp vào nút thêm ở góc trên bên phải.

Ưu tiên cấu hình đặt sẵn tích hợp

Khi có cấu hình đặt sẵn, hãy sử dụng cấu hình đó và chỉ nhập API key cùng mọi giá trị bắt buộc dành riêng cho tài khoản. Một cấu hình đặt sẵn thường thiết lập:

• Base URL;
• mô hình mặc định;
• giao thức thượng nguồn;
• có cần định tuyến cục bộ hay không;
• ánh xạ mô hình;
• các tham số suy luận được chọn.

Danh sách cấu hình đặt sẵn thay đổi theo quá trình phát triển của CC Switch. Tài liệu có thời hạn sử dụng dài không nên mã hóa cứng ID mô hình hiện tại của nhà cung cấp; hãy dùng danh sách trong ứng dụng và tài liệu chính thức của nhà cung cấp.

Tạo nhà cung cấp tùy chỉnh

Khi không có cấu hình đặt sẵn, hãy chọn cấu hình tùy chỉnh và cung cấp:

Thiết lập quan trọng nhất là Upstream Format:

Không chọn Responses chỉ vì nhà cung cấp quảng cáo khả năng “tương thích với OpenAI”. Nhiều API tương thích với OpenAI chỉ triển khai Chat Completions.

1.6 Nhập Base URL chính xác

Theo mặc định, CC Switch nối thêm đường dẫn API phù hợp vào Base URL. Trong hầu hết trường hợp, hãy nhập gốc API từ tài liệu của nhà cung cấp thay vì tự lặp lại /chat/completions hoặc /responses.

Ví dụ, nếu nhà cung cấp ghi trong tài liệu:

POST https://api.example.com/v1/chat/completions

bạn có thể cần nhập:

https://api.example.com

hoặc, tùy vào cấu hình đặt sẵn và tài liệu của nhà cung cấp:

https://api.example.com/v1

Việc Base URL có bao gồm /v1 hay không phụ thuộc vào nhà cung cấp và cấu hình đặt sẵn của CC Switch. Hãy dùng chức năng kiểm tra kết nối tích hợp hoặc nhật ký định tuyến để xác nhận URL yêu cầu cuối cùng.

Chỉ dùng Full URL Mode khi nhà cung cấp yêu cầu một đường dẫn điểm cuối đầy đủ không theo tiêu chuẩn.

1.7 Cấu hình Needs Local Routing và ánh xạ mô hình

Bật Needs Local Routing khi nhà cung cấp dùng Chat Completions, Anthropic Messages hoặc tên mô hình mà Codex không nhận dạng theo mặc định.

Các cấu hình đặt sẵn hướng đến Chat thường tự động bật tùy chọn này. Hãy kiểm tra tùy chọn đó đối với nhà cung cấp tùy chỉnh.

Sau khi bật, bảng ánh xạ mô hình sẽ xuất hiện. Các trường thường gặp gồm:

Các điểm quan trọng:

• dùng ID mô hình chính xác trong tài liệu của nhà cung cấp;
• không đoán độ dài cửa sổ ngữ cảnh;
• khởi động lại Codex sau khi thay đổi danh sách mô hình;
• CC Switch tạo danh mục mô hình Codex từ các ánh xạ này;
• nếu dịch vụ chuyển tiếp thay đổi miền hoặc tên mô hình, khả năng tự động phát hiện năng lực suy luận có thể không chính xác và cần được xem xét trong phần cài đặt nâng cao.

1.8 Bật định tuyến cục bộ và quyền tiếp quản Codex

Trong CC Switch, mở:

Settings → Routing → Local Routing

Sau đó:

1. bật công tắc định tuyến cục bộ chính;
2. bật Codex trong Routing Enabled;
3. xác nhận thiết lập Needs Local Routing của nhà cung cấp;
4. duy trì CC Switch hoạt động trong khi sử dụng nhà cung cấp.

Tuyến cục bộ mặc định thường là:

http://127.0.0.1:15721

Sau khi tiếp quản, cấu hình Codex đang hoạt động sẽ trỏ đến tuyến cục bộ của CC Switch. Sau đó, CC Switch chuyển tiếp yêu cầu đến nhà cung cấp thượng nguồn hiện được chọn.

Đối với hệ thống thượng nguồn Chat Completions, luồng thường là:

Codex POST /responses
  → CC Switch converts it to POST /chat/completions
  → the provider returns JSON or SSE
  → CC Switch rebuilds Responses JSON or SSE
  → Codex continues the tool-call loop

1.9 Chuyển đổi nhà cung cấp và khởi động lại Codex

Quay lại danh sách nhà cung cấp Codex trong CC Switch, chọn nhà cung cấp bạn đã cấu hình rồi bật nhà cung cấp đó.

Khởi động lại hoàn toàn Codex sau khi chuyển đổi vì:

• Codex đọc config.toml khi khởi động;
• menu /model thường tải danh mục khi khởi động;
• tiện ích IDE hoặc ứng dụng máy tính để bàn có thể lưu vào bộ nhớ đệm nhà cung cấp trước đó;
• các phiên hiện có có thể giữ lại siêu dữ liệu của mô hình cũ.

Người dùng CLI chỉ cần bắt đầu một tiến trình mới:

codex

1.10 Xác minh tích hợp

Trong Codex, chạy:

/status

Xem lại mô hình, nhà cung cấp, quyền và thông tin ngữ cảnh đang hoạt động.

Mở bộ chọn mô hình:

/model

Kiểm tra các lớp cấu hình:

/debug-config

Đồng thời kiểm tra:

• nhà cung cấp Codex đang hoạt động trong CC Switch;
• nhật ký hoặc số liệu thống kê định tuyến cục bộ của CC Switch;
• lịch sử yêu cầu và thay đổi số dư trong trang tổng quan của nhà cung cấp;
• liệu ~/.codex/config.toml hiện có trỏ đến tuyến cục bộ hay không.

Không xác thực thiết lập chỉ bằng một lời chào đơn giản. Hãy chạy ít nhất một phép thử năng lực tác nhân:

1. yêu cầu Codex liệt kê các tệp trong dự án hiện tại;
2. yêu cầu công cụ đọc và tóm tắt một tệp;
3. yêu cầu công cụ sửa đổi một tệp nhỏ;
4. yêu cầu công cụ chạy các bài kiểm thử;
5. để lại một lỗi đơn giản và xác minh rằng công cụ có thể dùng kết quả kiểm thử để tiếp tục sửa dự án.

Việc tạo văn bản thành công không chứng minh rằng chức năng gọi công cụ và quy trình tác nhân nhiều lượt tương thích.

1.11 Chuyển lại nhà cung cấp OpenAI chính thức

Chọn OpenAI Official trong CC Switch rồi khởi động lại Codex.

Kiểm tra trạng thái đăng nhập:

codex login status

Nếu cần, hãy đăng nhập lại:

codex login

Khi cần cả trạng thái đăng nhập chính thức và yêu cầu mô hình bên thứ ba, hãy xác nhận Keep official login when switching third-party providers vẫn được bật.

1.12 Hạn chế và lưu ý khi vận hành

CC Switch đơn giản hóa cấu hình nhưng không loại bỏ các hạn chế của hệ thống thượng nguồn:

• CC Switch phải duy trì hoạt động để chuyển đổi Chat hoặc Messages;
• việc chuyển đổi giao thức không thể tái tạo mọi tính năng riêng của nhà cung cấp;
• một số mô hình có thể trò chuyện nhưng không thực hiện được các lệnh gọi công cụ một cách đáng tin cậy;
• Web Search, đầu vào hình ảnh, WebSockets hoặc lưu trữ phản hồi có thể không khả dụng;
• giới hạn tốc độ, chính sách thanh toán và lưu giữ dữ liệu của nhà cung cấp thượng nguồn vẫn được áp dụng;
• dịch vụ chuyển tiếp API có thể tiếp tục sửa đổi yêu cầu và phản hồi;
• cần kiểm thử lại cấu hình sau khi nâng cấp CC Switch, Codex hoặc nhà cung cấp.

CC Switch phù hợp nhất với hoạt động phát triển cục bộ trên máy tính để bàn. Đối với máy chủ, CI hoặc tự động hóa không giao diện chạy dài hạn, hãy ưu tiên nhà cung cấp Responses nguyên bản hoặc cổng tự lưu trữ.

2. Kết nối API được lưu trữ bằng nhà cung cấp mô hình tùy chỉnh

Chỉ cấu hình trực tiếp nhà cung cấp khi dịch vụ hỗ trợ nguyên bản Responses API mà Codex yêu cầu.

Nếu dịch vụ chỉ cung cấp /chat/completions hoặc Anthropic Messages, hãy dùng quy trình CC Switch trong phần 1. Đừng cố giải quyết sự không tương thích bằng wire_api = "chat".

2.1 Các năng lực API bắt buộc

Một nhà cung cấp phù hợp để tích hợp trực tiếp với Codex cần hỗ trợ ít nhất:

• POST /responses;
• đối tượng JSON của Responses;
• sự kiện truyền trực tuyến SSE của Responses;
• gọi hàm hoặc công cụ;
• tham số công cụ theo JSON Schema;
• tiếp tục sau khi kết quả công cụ được trả về;
• yêu cầu nhiều lượt hoặc tính năng tương đương với previous_response_id;
• cửa sổ ngữ cảnh đủ lớn và yêu cầu chạy dài ổn định;
• tài liệu về xác thực, giới hạn tốc độ và phản hồi lỗi.

Chỉ tạo văn bản thông thường là chưa đủ để có một tác nhân Codex đáng tin cậy.

2.2 Cấu hình chung

Chỉnh sửa cấu hình cấp người dùng:

~/.codex/config.toml

Thêm:

model_provider = "third_party"
model = "provider-model-id"

# Set this only when the model explicitly supports it.
model_reasoning_effort = "high"

# Optional: use the real value published by the provider when no catalog exists.
# model_context_window = 131072

[model_providers.third_party]
name = "My Responses-compatible Provider"
base_url = "https://provider.example.com/v1"
env_key = "THIRD_PARTY_API_KEY"
wire_api = "responses"
request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 300000

Không dùng các ID nhà cung cấp dành riêng sau:

openai
ollama
lmstudio

Thay vào đó, hãy dùng ID tùy chỉnh như third_party hoặc company_gateway.

2.3 Các trường cấu hình

Việc base_url có bao gồm /v1 hay không phụ thuộc vào tài liệu của nhà cung cấp. Một điểm cuối hoàn chỉnh thường gặp là:

https://provider.example.com/v1/responses

2.4 Thiết lập API key

Phiên bash / zsh hiện tại:

export THIRD_PARTY_API_KEY="your API key"

fish:

set -gx THIRD_PARTY_API_KEY "your API key"

Phiên PowerShell hiện tại:

$env:THIRD_PARTY_API_KEY = "your API key"

Lưu cố định cho người dùng Windows hiện tại:

[Environment]::SetEnvironmentVariable(
  "THIRD_PARTY_API_KEY",
  "your API key",
  [EnvironmentVariableTarget]::User
)

Khởi động lại terminal, IDE hoặc ứng dụng máy tính để bàn sau khi thiết lập biến môi trường cố định.

2.5 Kiểm thử điểm cuối Responses trước

Trước khi khởi chạy Codex, hãy gọi trực tiếp nhà cung cấp:

export PROVIDER_BASE_URL="https://provider.example.com/v1"

curl "$PROVIDER_BASE_URL/responses" \
  -H "Authorization: Bearer $THIRD_PARTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "provider-model-id",
    "input": "Reply with exactly: PROVIDER_OK",
    "stream": false
  }'

Xác minh rằng:

• điểm cuối không trả về 404;
• phản hồi có cấu trúc kiểu Responses thay vì chỉ có mảng choices của Chat Completions;
• ID mô hình được chấp nhận;
• thông tin xác thực là chính xác;
• lỗi chứa thông tin chẩn đoán hữu ích.

Sau đó, kiểm thử riêng:

• stream: true;
• lệnh gọi công cụ;
• tiếp tục sau kết quả công cụ;
• nhiều lượt;
• ngữ cảnh dài;
• tính đồng thời và giới hạn tốc độ.

2.6 Xác thực cấu hình Codex

Khởi động ở chế độ nghiêm ngặt:

codex --strict-config

--strict-config xem các khóa cấu hình không xác định là lỗi, giúp nhận diện những trường được sao chép từ hướng dẫn lỗi thời.

Trong Codex, chạy:

/status

Để kiểm tra nguồn cấu hình, chạy:

/debug-config

Ghi đè nhà cung cấp và mô hình cho một lần chạy mà không thay đổi cấu hình mặc định:

codex \
  -c 'model_provider="third_party"' \
  -m 'provider-model-id'

2.7 Danh mục mô hình và Unknown model

Danh mục mô hình Codex có thể mô tả:

• kích thước cửa sổ ngữ cảnh;
• các mức suy luận được hỗ trợ;
• phương thức đầu vào;
• năng lực gọi công cụ;
• hành vi cắt bớt;
• phiên bản ứng dụng tối thiểu.

Khi nhà cung cấp cung cấp danh mục mô hình tương thích với Codex, hãy lưu danh mục đó trên máy cục bộ và cấu hình:

model_catalog_json = "~/.codex/provider-models.json"

Khi không có danh mục, chỉ thiết lập cửa sổ ngữ cảnh sau khi xác nhận giá trị thực:

model_context_window = 131072

Không sao chép siêu dữ liệu từ một mô hình không liên quan chỉ để loại bỏ cảnh báo. Siêu dữ liệu không chính xác về năng lực hoặc ngữ cảnh có thể gây cắt bớt quá sớm, lỗi giới hạn thượng nguồn hoặc lệnh gọi công cụ bị hỏng.

2.8 Danh sách kiểm tra khả năng tương thích đầy đủ

Trước khi sử dụng trong môi trường sản xuất, hãy kiểm thử:

• văn bản /responses không truyền trực tuyến;
• truyền trực tuyến SSE của Responses;
• một lệnh gọi công cụ;
• nhiều lệnh gọi công cụ tuần tự hoặc song song;
• tham số JSON Schema;
• tiếp tục sau kết quả công cụ;
• ngữ cảnh dài và tự động thu gọn;
• tham số suy luận;
• hình ảnh hoặc các phương thức đầu vào khác;
• giới hạn tốc độ và hành vi thử lại;
• liệu proxy có lưu đệm SSE hay không;
• liệu nhà cung cấp có loại bỏ hoặc viết lại các trường công cụ hay không;
• chính sách lưu giữ dữ liệu, ghi nhật ký và quyền riêng tư.

2.9 Vị trí đặt cấu hình nhà cung cấp

Đặt model_provider, model_providers và thông tin xác thực nhà cung cấp trong tệp cấp người dùng:

~/.codex/config.toml

Không đặt chúng trong tệp cấp kho lưu trữ:

<project>/.codex/config.toml

Codex bỏ qua các trường cục bộ của dự án có thể chuyển hướng yêu cầu mô hình hoặc thay đổi thông tin xác thực nhà cung cấp. Điều này ngăn một kho lưu trữ không đáng tin cậy được sao chép về âm thầm chuyển tiếp yêu cầu đến máy chủ khác.

3. Quản lý nhiều nhà cung cấp bên thứ ba bằng hồ sơ

Người dùng CC Switch thường có thể chuyển đổi nhà cung cấp trong ứng dụng và không cần hồ sơ Codex.

Hồ sơ hữu ích khi bạn cấu hình thủ công nhiều nhà cung cấp Responses nguyên bản. Hãy giữ định nghĩa nhà cung cấp trong cấu hình cơ sở và dùng các tệp hồ sơ riêng để chọn nhà cung cấp và mô hình.

~/.codex/config.toml cơ sở:

[model_providers.provider_a]
name = "Provider A"
base_url = "https://api.provider-a.example/v1"
env_key = "PROVIDER_A_API_KEY"
wire_api = "responses"

[model_providers.provider_b]
name = "Provider B"
base_url = "https://api.provider-b.example/v1"
env_key = "PROVIDER_B_API_KEY"
wire_api = "responses"

Tạo:

~/.codex/fast.config.toml

model_provider = "provider_a"
model = "provider-a-fast-model"
model_reasoning_effort = "medium"

Tạo một hồ sơ khác:

~/.codex/quality.config.toml

model_provider = "provider_b"
model = "provider-b-quality-model"
model_reasoning_effort = "high"

Chọn hồ sơ khi khởi chạy Codex:

codex --profile fast
codex --profile quality

Chế độ không tương tác:

codex exec --profile quality "Review the current changes"

Các tệp hồ sơ nằm tại:

$CODEX_HOME/<profile-name>.config.toml

CODEX_HOME mặc định là ~/.codex.

Các phiên bản Codex gần đây sử dụng tệp hồ sơ riêng và không còn đọc bảng [profiles.<name>] cũ. Hãy di chuyển từng hồ sơ cũ sang tệp <name>.config.toml riêng.

4. Header tùy chỉnh và xác thực nâng cao

4.1 Bearer token tiêu chuẩn

Hầu hết dịch vụ bên thứ ba hoạt động với:

[model_providers.third_party]
env_key = "THIRD_PARTY_API_KEY"

Codex đọc khóa từ môi trường và áp dụng cơ chế xác thực bearer của nhà cung cấp.

4.2 Header API key tùy chỉnh

Một số dịch vụ yêu cầu:

x-api-key: <key>

Dùng env_http_headers:

model_provider = "custom_header_provider"
model = "provider-model-id"

[model_providers.custom_header_provider]
name = "Custom Header Provider"
base_url = "https://provider.example.com/v1"
wire_api = "responses"
env_http_headers = { "x-api-key" = "VENDOR_API_KEY" }

Giá trị VENDOR_API_KEY là tên biến môi trường, không phải chính bí mật đó.

export VENDOR_API_KEY="your API key"

4.3 Header tĩnh và tham số truy vấn

Thêm header tĩnh không nhạy cảm:

http_headers = { "X-Client-Name" = "codex", "X-Environment" = "development" }

Thêm tham số truy vấn:

query_params = { "api-version" = "2026-08-01" }

Không đặt bí mật thật trong http_headers.

4.4 Xác thực dựa trên lệnh

Môi trường doanh nghiệp có thể lấy token ngắn hạn từ chuỗi khóa, trình trợ giúp thông tin xác thực đám mây hoặc lệnh nội bộ:

[model_providers.corporate]
name = "Corporate Gateway"
base_url = "https://gateway.example.com/v1"
wire_api = "responses"

[model_providers.corporate.auth]
command = "/usr/local/bin/fetch-codex-token"
args = ["--audience", "codex"]
timeout_ms = 5000
refresh_interval_ms = 300000

Lệnh chỉ được in token ra đầu ra tiêu chuẩn.

Không kết hợp các phương thức xác thực sau:

• [model_providers.<id>.auth];
• env_key;
• experimental_bearer_token;
• requires_openai_auth.

4.5 Tái sử dụng thông tin xác thực OpenAI qua proxy

Chỉ thiết lập nội dung sau khi proxy vẫn truy cập các mô hình OpenAI và Codex cần dùng cơ chế xác thực chính thức của OpenAI:

requires_openai_auth = true

Đây không phải thiết lập phù hợp cho API key thông thường của mô hình bên thứ ba. Khi được bật, Codex bỏ qua env_key của nhà cung cấp.

5. Khắc phục sự cố

5.1 CC Switch thay đổi nhà cung cấp nhưng Codex vẫn dùng mô hình cũ

Kiểm tra từng mục:

1. nhà cung cấp Codex dự định sử dụng đã được bật trong CC Switch;
2. công tắc chính của định tuyến cục bộ đang bật;
3. Codex được bật trong Routing Enabled;
4. nhà cung cấp Chat hoặc Messages đã bật Needs Local Routing;
5. CC Switch vẫn đang chạy;
6. Codex, IDE hoặc ứng dụng máy tính để bàn đã được khởi động lại hoàn toàn;
7. /debug-config hiển thị nguồn cấu hình dự kiến.

Khởi động lại Codex sau khi thay đổi ánh xạ mô hình để menu /model có thể tải lại danh mục.

5.2 404, 400 hoặc thiếu điểm cuối /responses

Các nguyên nhân thường gặp gồm:

• xem nhà cung cấp Chat Completions là nhà cung cấp Responses nguyên bản;
• thêm hoặc xóa /v1 không chính xác;
• nối thêm /chat/completions hai lần;
• không bật Full URL Mode cho điểm cuối không theo tiêu chuẩn;
• định tuyến cục bộ chưa tiếp quản Codex;
• triển khai Responses không đầy đủ trong cổng bên thứ ba.

Người dùng CC Switch nên kiểm tra Upstream Format và nhật ký định tuyến. Người dùng nhà cung cấp trực tiếp nên gọi <base_url>/responses với curl.

5.3 401 Unauthorized hoặc 403 Forbidden

Kiểm tra:

• API key có hợp lệ hay không;
• khóa có thuộc đúng khu vực, dự án hoặc gói dịch vụ hay không;
• tài khoản có đủ số dư và quyền hay không;
• dịch vụ yêu cầu bearer token hay x-api-key;
• tên biến môi trường có khớp chính xác với env_key hay không;
• CC Switch đã lưu đúng khóa hay chưa;
• proxy có xóa header xác thực hay không.

Không in toàn bộ khóa vào nhật ký dùng chung.

bash / zsh:

printenv THIRD_PARTY_API_KEY

PowerShell:

$env:THIRD_PARTY_API_KEY

5.4 Mô hình không xuất hiện trong /model

Kiểm tra:

• Model Mapping của CC Switch có chứa ID mô hình thượng nguồn chính xác hay không;
• nhà cung cấp đã được lưu và bật hay chưa;
• Codex đã được khởi động lại hay chưa;
• nhà cung cấp thủ công có model_catalog_json hợp lệ hay không;
• JSON của danh mục có hợp lệ hay không;
• nhà cung cấp có đổi tên hoặc ngừng cung cấp mô hình hay không.

5.5 Văn bản hoạt động nhưng Codex không thể đọc tệp, chỉnh sửa mã hoặc chạy lệnh

Các nguyên nhân có thể gồm:

• mô hình yếu về khả năng gọi công cụ;
• hệ thống thượng nguồn không triển khai chức năng gọi hàm;
• dịch vụ chuyển tiếp loại bỏ ID lệnh gọi công cụ;
• các mảnh lệnh gọi công cụ truyền trực tuyến không được ghép lại chính xác;
• JSON Schema bị viết lại;
• kết quả công cụ không được trả về trong lượt tiếp theo;
• ngữ cảnh của mô hình quá ngắn;
• danh mục mô hình quảng bá sai năng lực.

Hãy kiểm thử một vòng lặp “đọc → chỉnh sửa → chạy kiểm thử → kiểm tra lỗi → sửa” thực tế thay vì một lời nhắc trò chuyện đơn giản.

5.6 Truyền trực tuyến thường xuyên bị ngắt kết nối

Trước tiên, người dùng CC Switch nên kiểm tra nhật ký định tuyến cục bộ và phản hồi thượng nguồn. Các nguyên nhân thường gặp gồm:

• hệ thống thượng nguồn xếp hàng hoặc mất nhiều thời gian suy luận;
• cổng không phát SSE kịp thời;
• CDN, proxy ngược hoặc mạng doanh nghiệp lưu đệm;
• sự kiện thượng nguồn không theo tiêu chuẩn;
• vấn đề tương thích trong một phiên bản CC Switch hoặc nhà cung cấp cụ thể.

Đối với nhà cung cấp trực tiếp, bạn có thể tăng:

request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 600000

Thời gian chờ dài hơn có thể giảm bớt vấn đề về mạng hoặc suy luận chậm, nhưng không thể sửa một triển khai giao thức không chính xác.

5.7 wire_api = "chat" ngăn Codex khởi động

Giá trị này xuất hiện trong các hướng dẫn cũ. Cấu hình Codex hiện tại chỉ hỗ trợ:

wire_api = "responses"

Hãy dùng CC Switch khi hệ thống thượng nguồn chỉ cung cấp Chat Completions.

Kiểm tra các trường lỗi thời khác bằng:

codex --strict-config

5.8 Chỉnh sửa cấu hình dự án không làm thay đổi nhà cung cấp

Cài đặt nhà cung cấp nằm trong:

~/.codex/config.toml

.codex/config.toml cấp dự án không thể ghi đè các trường chuyển hướng yêu cầu hoặc thay đổi thông tin xác thực nhà cung cấp, bao gồm model_provider và model_providers.

5.9 Terminal hoạt động nhưng tiện ích IDE không tìm thấy API key

Ứng dụng có giao diện đồ họa thường không kế thừa các biến được xuất tạm thời trong một terminal hiện có.

Các lựa chọn gồm:

• khởi chạy IDE từ terminal nơi biến đã được thiết lập;
• lưu cố định biến trong môi trường người dùng của hệ điều hành;
• thoát hoàn toàn rồi mở lại IDE;
• dùng CC Switch để quản lý cấu hình nhà cung cấp cục bộ.

5.10 Đăng nhập chính thức hoặc các tính năng chính thức ngừng hoạt động sau khi chuyển đổi

Kiểm tra:

• OpenAI Official đã được chọn lại hay chưa;
• Keep official login when switching third-party providers có được bật hay không;
• quy trình cũ có ghi đè ~/.codex/auth.json hay không;
• codex login status có thực thi thành công hay không.

Khi cần, hãy đăng nhập lại:

codex login

Không chia sẻ hoặc chỉnh sửa thủ công tệp auth.json chứa access token.

5.11 Web Search, hình ảnh hoặc các năng lực nâng cao khác không hoạt động

Nhà cung cấp hỗ trợ văn bản và lệnh gọi công cụ không nhất thiết triển khai mọi năng lực của Codex.

Nhà cung cấp tùy chỉnh không quảng bá Web Search độc lập theo mặc định. Chỉ thiết lập nội dung sau khi nhà cung cấp, mô hình và điểm cuối thực sự hỗ trợ tính năng đó:

supports_standalone_web_search = true

Bật không chính xác chỉ khiến Codex gửi các yêu cầu mà hệ thống thượng nguồn không thể xử lý. Hãy xác thực riêng đầu vào hình ảnh, WebSockets, lưu trữ phản hồi và các tính năng nâng cao khác.

6. Chọn phương thức tích hợp

Xác thực mọi tích hợp ở ba cấp độ:

1. Khả năng kết nối: hệ thống trả về văn bản một cách đáng tin cậy;
2. Sử dụng công cụ: hệ thống có thể đọc tệp, chạy lệnh và tiếp tục từ kết quả công cụ;
3. Hoàn thành tác vụ: hệ thống có thể hoàn thành vòng lặp chỉnh sửa, kiểm thử và sửa chữa.

Đồng thời xem xét:

• giá của bên thứ ba;
• giới hạn tốc độ;
• mã nguồn và lời nhắc có được ghi nhật ký hay không;
• khu vực lưu trữ dữ liệu;
• yêu cầu tuân thủ của nhóm hoặc doanh nghiệp;
• việc nâng cấp mô hình có yêu cầu kiểm thử hồi quy hay không.

Khi bạn dùng API key của bên thứ ba, mức sử dụng sẽ do nhà cung cấp hoặc dịch vụ chuyển tiếp đó tính phí. Mức sử dụng này không tự động tiêu thụ hoặc dùng chung hạn mức đi kèm ChatGPT Plus, Pro hay gói đăng ký Codex.

Tài liệu tham khảo

• Kiến thức cơ bản về cấu hình Codex
• Cấu hình Codex nâng cao
• Tài liệu tham chiếu cấu hình Codex
• Xác thực Codex
• Lệnh dành cho nhà phát triển Codex
• Các mô hình Codex
• CC Switch trên GitHub
• Hướng dẫn sử dụng CC Switch
• CC Switch: Thêm nhà cung cấp
• CC Switch: Duy trì đăng nhập Codex chính thức