Phiên bản áp dụng: CC Switch 3.16.0 trở lên. Bài viết được biên soạn dựa trên tài liệu và mã nguồn của kho lưu trữ, sử dụng DeepSeek làm ví dụ cho giao diện tương thích OpenAI Chat Completions. Ảnh chụp màn hình từ giao diện frontend hiện tại, được tạo bằng dữ liệu mẫu đã được ẩn danh để tránh rò rỉ API Key thật hoặc số dư tài khoản.
Tại sao cần Định tuyến Cục bộ (Local Routing)
Phiên bản mới của Codex CLI hướng tới OpenAI Responses API, trong khi nhiều nhà cung cấp như DeepSeek, Kimi, MiniMax và SiliconFlow thực tế lại sử dụng định dạng OpenAI Chat Completions, đó là /chat/completions. Cấu trúc request body, sự kiện stream và dữ liệu trả về của hai giao thức này khác nhau. Việc nhập trực tiếp giao diện Chat vào cấu hình Codex thường dẫn đến danh sách model không chính xác, lỗi 404/400 hoặc phản hồi stream mà Codex không thể phân tích đúng.
Cách tiếp cận của CC Switch là yêu cầu Codex luôn kết nối tới một route cục bộ, vẫn gửi request qua Responses API; route nội bộ sẽ xác định xem nhà cung cấp hiện tại có đang ở định dạng Chat hay không, viết lại request thành Chat Completions để gửi lên thượng nguồn, và cuối cùng chuyển đổi phản hồi Chat về định dạng Responses để trả về Codex.
Chuỗi này chủ yếu được chia thành bốn bước:
- Khi Codex được tiếp quản, cấu hình cục bộ được ghi là
http://127.0.0.1:15721/v1, và buộcwire_api = "responses". meta.apiFormat = "openai_chat"của Provider báo cho route biết: thượng nguồn thực sự là Chat Completions.- Route viết lại
/responseshoặc/v1/responsesthành/chat/completionsvà chuyển đổi request body của Responses thành request body của Chat. - Sau khi thượng nguồn trả về, route chuyển đổi Chat JSON hoặc SSE thành Responses JSON/SSE mà Codex có thể hiểu được.
Chuẩn bị
Bạn cần chuẩn bị ba thứ trước:
- CC Switch đã được cài đặt và sẵn sàng khởi động.
- Codex CLI đã được cài đặt và chạy ít nhất một lần để cấu trúc thư mục
~/.codex/config.tomltồn tại. - Một API Key cho DeepSeek hoặc nhà cung cấp Chat Completions tương tự.
Tài liệu chính thức của DeepSeek hiện nêu rõ base URL tương thích OpenAI là https://api.deepseek.com (các nhà cung cấp khác thường dùng base URL có hậu tố /v1), và đường dẫn Chat API là /chat/completions; preset DeepSeek của CC Switch đã được cấu hình sẵn thông tin này, vì vậy hãy ưu tiên sử dụng preset thay vì tự ghép đường dẫn giao diện.
Bước 1: Thêm Codex Provider
Mở CC Switch, chuyển sang tab Codex ở trên cùng, và nhấp vào dấu cộng ở góc trên bên phải để thêm provider.
Chọn DeepSeek từ các preset có sẵn; bạn chỉ cần làm hai việc:
- Nhập DeepSeek API Key.
- Lưu provider.
Preset đã bao gồm địa chỉ request, model mặc định, menu model và tham số suy luận/lý luận của DeepSeek, đồng thời sẽ tự động bật "Yêu cầu Ánh xạ Định tuyến Cục bộ (Requires Local Routing Mapping)". Bạn có thể điều chỉnh model mặc định hoặc tên hiển thị model nếu cần; việc chuyển đổi giao thức được xử lý bởi tầng định tuyến.
Bước 2: Bật Định tuyến Cục bộ và Tiếp quản Codex
Đi đến trang Định tuyến (Routing) trong Cài đặt (Settings), mở rộng Định tuyến Cục bộ (Local Routing), và thực hiện hai lần bật:
- Bật Công tắc Định tuyến Chính (Main Routing Switch) để khởi động dịch vụ cục bộ. Địa chỉ mặc định là
127.0.0.1:15721. - Bật Codex trong phần Bật Định tuyến (Routing Enablement). Nếu bạn chỉ muốn Codex đi qua route, bạn có thể tắt Claude và Gemini.
Sau khi tiếp quản, CC Switch sẽ trỏ cấu hình đang hoạt động của Codex đến route cục bộ và quản lý xác thực bằng các placeholder. DeepSeek Key thật vẫn được lưu trong cấu hình Provider của CC Switch và được route cục bộ chèn vào trong quá trình chuyển tiếp, vì vậy bạn không cần phải lộ Key trong cấu hình đang hoạt động của Codex.
Bước 3: Chuyển đổi Provider và Khởi động lại Codex
Quay lại danh sách provider Codex và nhấp vào Bật (Enable) cho provider DeepSeek. Nếu bạn thấy thẻ "Yêu cầu Route (Requires Route)", điều đó có nghĩa là provider này phải được sử dụng khi route đang chạy; nếu route chưa được khởi động, CC Switch sẽ hiện một lời nhắc "Dịch vụ định tuyến là cần thiết để sử dụng bình thường (Routing service is required for normal use)."
Sau khi chuyển đổi, bạn nên khởi động lại phiên terminal Codex hiện tại vì:
- Tiến trình Codex có thể đã đọc
config.tomlcũ. - Sau khi
modelcatalogjsonđược tạo, menu/modelthường yêu cầu một tiến trình mới để làm mới.
Khi đã ở trong Codex, bạn có thể sử dụng /model để kiểm tra xem model hiện tại có phải từ preset DeepSeek không, ví dụ DeepSeek V4 Flash. Hiện tại, ứng dụng Codex không hỗ trợ lựa chọn đa model tùy chỉnh và sẽ mặc định sử dụng model đầu tiên trong cấu hình.
Cách Xử lý với các Nhà cung cấp Chat Khác
Các nhà cung cấp định dạng Chat phổ biến như DeepSeek, Kimi, MiniMax và SiliconFlow đều đã có preset trong CC Switch; hãy ưu tiên sử dụng chúng. Chỉ đối với các nhà cung cấp không có trong preset, bạn mới cần chọn cấu hình tùy chỉnh; trong trường hợp đó, hãy điền API Key, base URL và model theo tài liệu của họ, và đặt Định dạng API (API Format) thành OpenAI Chat Completions (yêu cầu định tuyến).
Nếu thượng nguồn trực tiếp hỗ trợ OpenAI Responses API, bạn không cần bật "Yêu cầu Ánh xạ Định tuyến Cục bộ"; trong trường hợp này, CC Switch có thể kết nối trực tiếp qua Responses mà không cần chuyển đổi Chat.
Câu hỏi thường gặp (FAQ)
Codex báo lỗi 404 hoặc không tìm thấy /responses
Thông thường, điều này là do chưa bật tính năng tiếp quản Codex, hoặc bạn đã tự viết trực tiếp base URL Chat thượng nguồn vào Codex. Hãy kiểm tra xem ~/.codex/config.toml có trỏ tới http://127.0.0.1:15721/v1 hay không.
DeepSeek thượng nguồn báo lỗi 404
Nếu sử dụng preset DeepSeek tích hợp, trước tiên hãy xác nhận provider hiện tại thực sự đến từ preset và định tuyến Codex đã được bật. Chỉ khi sử dụng provider tùy chỉnh, bạn mới cần kiểm tra lại base URL: nó phải là địa chỉ gốc của dịch vụ, không phải là đường dẫn giao diện đầy đủ với /chat/completions.
/model không hiển thị các model DeepSeek
Khởi động lại Codex sau khi lưu provider. CC Switch tạo cc-switch-model-catalog.json và ghi đường dẫn vào modelcatalogjson, nhưng một tiến trình Codex đang chạy có thể không tải nóng thư mục model.
Hiện tại, ứng dụng Codex không hỗ trợ lựa chọn đa model và mặc định sử dụng model đầu tiên.
Route đang bật nhưng request vẫn đi đến sai provider
Xác nhận ba trạng thái nhất quán: provider hiện tại trong tab Codex là DeepSeek; dịch vụ định tuyến cục bộ đang chạy; và công tắc Codex trong phần Bật Định tuyến (Routing Enablement) đang bật.
Tôi có thể sử dụng tài khoản Codex chính thức của OpenAI thông qua định tuyến cục bộ không?
Không khuyến khích. CC Switch ngăn chặn việc chuyển đổi sang các provider chính thức trong chế độ tiếp quản định tuyến cục bộ vì sử dụng proxy để truy cập API chính thức có thể gây rủi ro cho tài khoản. Định tuyến chủ yếu dành cho các tình huống của bên thứ ba, tổng hợp hoặc chuyển đổi giao thức.
