Triển khai gateway
Phân phối và xác minh kết nối gateway Codex cho tổ chức của bạn
Với vai trò quản trị viên gateway, hãy cấu hình các tuyến mô hình và cấp quyền cho một người dùng thử nghiệm. Kiểm tra kết nối trên từng ứng dụng khách mà bạn hỗ trợ trước khi phân phối thiết lập cho nhà phát triển. Sử dụng OAuth gateway tích hợp sẵn, API key hoặc trình hỗ trợ thông tin xác thực để xác thực gateway. Để kết hợp xác thực gateway với đăng nhập không gian làm việc ChatGPT, xem Đăng nhập bằng ChatGPT qua gateway.
Điều kiện tiên quyết
Trước khi triển khai Codex cho các nhà phát triển, hãy xác nhận rằng bạn có:
- Gateway phục vụ HTTPS tại đúng URL cơ sở mà bạn sẽ phân phối.
- Thông tin xác thực của nhà cung cấp thượng nguồn được lưu giữ trên gateway.
- Các bí danh mô hình đã được phê duyệt để Codex sử dụng, được ánh xạ tới các mô hình thượng nguồn dự kiến.
- Phương thức xác thực đã kiểm thử: OAuth gốc của gateway, API key của gateway có giới hạn phạm vi, hoặc trình trợ giúp thông tin xác thực.
- Với OAuth, ứng dụng khách công khai đã đăng ký, người dùng thử nghiệm đã được phê duyệt và gateway hỗ trợ xác thực token truy cập OAuth.
- Với API key hoặc trình trợ giúp, cơ chế phân phối thông tin bí mật hoặc trình trợ giúp đã được kiểm thử.
- Cách phân phối cấu hình, mọi trình trợ giúp cần thiết và các tệp danh mục.
Yêu cầu đối với gateway
Trước khi kết nối Codex, hãy xác minh rằng sản phẩm gateway duy trì các hành vi bắt buộc sau:
- Chấp nhận các yêu cầu Responses API của Codex tại
POST /v1/responses. - Truyền các sự kiện SSE theo luồng mà không lưu đệm và kết thúc bằng
response.completed. - Duy trì khả năng tiếp nối ở các lượt tiếp theo bằng dữ liệu đầu vào được gửi lại.
- Duy trì
previous_response_idchỉ khi bật WebSocket hoặc cơ chế truyền tăng dần. - Giữ nguyên các lệnh gọi hàm và các mục
function_call_outputtương ứng. - Định tuyến từng bí danh mô hình mà Codex sử dụng tới mô hình thượng nguồn dự kiến.
- Xác thực riêng từng người dùng và trả về lỗi hữu ích mà không che giấu nguyên nhân.
Một điểm cuối kiểm tra tình trạng, /v1/models, phản hồi Chat Completions hoặc một câu trả lời văn bản thuần túy không đủ để xác nhận gateway đáp ứng yêu cầu. Xem Yêu cầu về khả năng tương thích của gateway để biết đặc tả chi tiết.
Triển khai gateway
Để chuyển từ gateway đã triển khai sang trải nghiệm nhà phát triển đã được xác minh, hãy hoàn thành năm bước kiểm tra sau theo thứ tự:
- Chọn tên mô hình và xác minh tuyến định tuyến.
- Chọn phương thức xác thực.
- Kiểm thử Codex qua gateway.
- Phân phối cấu hình.
- Xác minh từ máy của nhà phát triển.
Chọn tên mô hình và tuyến định tuyến
Đặt model của Codex thành tên mô hình trên gateway. Cấu hình gateway để định tuyến tên đó tới mô hình thượng nguồn đã được phê duyệt.
| Tên mô hình trên gateway | Cấu hình Codex |
|---|---|
| Một tên mô hình tích hợp sẵn có trong phiên bản Codex của bạn | Đặt model trong config.toml thành chính xác tên này. |
Một bí danh tùy chỉnh, chẳng hạn như company-coding-model |
Cung cấp danh mục từ xa hoặc cục bộ chứa bí danh và siêu dữ liệu của mô hình tương ứng. |
Sử dụng danh mục mô hình cho tên tùy chỉnh
Đối với danh mục cục bộ, hãy bắt đầu với ví dụ models.json.
Hãy cung cấp danh mục mô hình khi gateway sử dụng tên mô hình mà Codex không nhận dạng. Danh mục cung cấp các chỉ dẫn, tùy chọn suy luận, giới hạn ngữ cảnh và khả năng công cụ mà Codex sử dụng cho tên đó. Nếu không có mục nhập tương ứng, yêu cầu vẫn có thể đến đúng mô hình thượng nguồn dự kiến trong khi Codex sử dụng chế độ cài đặt chung.
Lưu trữ danh mục từ xa bằng model_providers.<id>.model_catalog_url để cập nhật siêu dữ liệu mô hình tập trung, hoặc phân phối tệp cục bộ bằng model_catalog_json. Sử dụng danh mục cục bộ khi OAuth gốc của gateway là phương thức xác thực duy nhất; chỉ OAuth không đủ để bật tính năng tự động tìm danh mục từ xa. Xem tài liệu tham chiếu cấu hình để biết cả hai thiết lập.
Lấy điểm cuối hoặc tệp danh mục tương thích với phiên bản Codex của bạn từ nhà cung cấp đám mây hoặc gateway. Đảm bảo danh mục bao gồm từng bí danh đã được phê duyệt và siêu dữ liệu mô hình tương ứng. Để triển khai danh mục, xem Triển khai danh mục mô hình cho gateway và đám mây.
Cung cấp danh mục từ xa
Sử dụng điểm cuối danh mục HTTPS do nhà cung cấp của bạn cung cấp.
Phân phối URL đầy đủ của điểm cuối trong bảng config.toml của nhà cung cấp đã chọn:
model = "company-coding-model"
model_provider = "enterprise-gateway"
web_search = "disabled"
[model_providers.enterprise-gateway]
name = "Organization Gateway"
base_url = "https://gateway.example.com/v1"
model_catalog_url = "https://gateway.example.com/codex/models"
wire_api = "responses"
env_key = "CODEX_GATEWAY_API_KEY"Cung cấp CODEX_GATEWAY_API_KEY cho tiến trình Codex. Đặt riêng base_url
để định tuyến hoạt động suy luận qua gateway. Nếu bạn bỏ qua thiết lập này, Codex sẽ sử dụng
điểm cuối OpenAI mặc định cho chế độ xác thực hiện tại.
Tính năng tự động tìm danh mục yêu cầu xác thực bằng API key, bằng lệnh hoặc qua backend của Codex. Chỉ OAuth gốc của gateway hoặc header tùy chỉnh sẽ không kích hoạt tính năng này.
Phối hợp với nhà cung cấp để cập nhật danh mục khi các mô hình được phê duyệt thay đổi. Khởi động lại ứng dụng khách sau khi thay đổi cấu hình.
Xóa mọi chế độ cài đặt model_catalog_json đang có hiệu lực, bao gồm cả chế độ được thực thi thông qua
requirements.toml. Chế độ này được ưu tiên hơn URL từ xa và ngăn quá trình tìm nạp.
Phân phối danh mục cục bộ
Sử dụng model_catalog_json để tải tệp do nhà cung cấp cung cấp khi khởi động. Danh mục tùy chỉnh
cục bộ thay thế danh mục đi kèm.
Đặt bí danh gateway, slug trong danh mục và model của Codex thành company-coding-model. Thêm các thiết lập này trước bảng TOML đầu tiên trong cấu hình Codex mà bạn phân phối, sử dụng đường dẫn tuyệt đối thực tế của tệp:
model = "company-coding-model"
model_catalog_json = "/absolute/path/to/gateway-models.json"Khởi động lại CLI hoặc ứng dụng máy tính sau khi thay đổi danh mục vì Codex tải danh mục khi khởi động.
Xác minh tuyến định tuyến mô hình
Với mỗi mô hình, hãy xác minh tuyến định tuyến bằng yêu cầu Responses thực tế và bản ghi
của gateway. Phản hồi /v1/models có thể giúp tìm tên nhưng không chứng minh rằng
mô hình hỗ trợ hành vi yêu cầu và công cụ cần thiết.
Định tuyến mô hình và cấp quyền công cụ là hai phần riêng biệt của quá trình triển khai. Hãy cấu hình các kết nối MCP, việc phân phối plugin và chính sách của chúng một cách riêng biệt.
Chọn phương thức xác thực
OAuth gốc của gateway
- Đăng ký ứng dụng khách OAuth công khai hỗ trợ mã ủy quyền với PKCE và phê duyệt những người dùng hoặc nhóm được phép đăng nhập.
- Cấu hình gateway để xác thực token truy cập đã cấp trong cookie hoặc header tùy chỉnh đã chọn. Áp dụng các mô hình được phê duyệt, giới hạn tốc độ và ngân sách cho danh tính của từng người dùng.
- Làm theo OAuth gốc của gateway để thu thập URL ủy quyền và URL token, ID ứng dụng khách công khai, phạm vi, tài nguyên tùy chọn, thiết lập truyền token và cổng chuyển hướng cố định nếu có. Đăng ký URI chuyển hướng loopback tương ứng với nhà cung cấp danh tính của bạn.
- Kiểm thử đăng nhập qua trình duyệt, làm mới token và thu hồi quyền truy cập bằng một người dùng thử nghiệm trên CLI hoặc ứng dụng máy tính mà bạn dự định triển khai. Xác nhận rằng trình duyệt có thể truy cập địa chỉ callback, kể cả với người dùng CLI từ xa.
Mỗi người dùng đăng nhập riêng. Bạn phân phối cấu hình OAuth, không phải thông tin bí mật của ứng dụng khách, API key của gateway hay tệp thực thi của trình trợ giúp. Giữ thông tin xác thực của nhà cung cấp thượng nguồn trên gateway.
API key hoặc trình trợ giúp thông tin xác thực
- Cấp một bộ thông tin xác thực gateway với phạm vi giới hạn cho mỗi nhà phát triển để bạn có thể xác định người sử dụng và thu hồi quyền truy cập riêng lẻ.
- Thiết lập các mô hình được phê duyệt, giới hạn tốc độ, ngân sách, thời hạn và chu kỳ gia hạn cho từng bộ thông tin xác thực.
- Phân phối thông tin xác thực qua trình quản lý bí mật hoặc trình trợ giúp thông tin xác thực đã cài đặt. Không lưu thông tin xác thực của nhà cung cấp thượng nguồn và quản trị viên gateway trên máy của nhà phát triển.
- Nếu sử dụng trình trợ giúp, hãy tuân theo đặc tả xác thực dựa trên lệnh và kiểm thử việc truy xuất cũng như làm mới token trước khi phân phối.
- Hướng dẫn nhà phát triển cách gia hạn thông tin xác thực và người cần liên hệ để được hỗ trợ.
Kiểm thử Codex qua gateway
Trước khi phân phối bất cứ thành phần nào, làm theo Cấu hình nhà cung cấp để cấu hình một người dùng thử nghiệm riêng biệt với khối cấu hình nhà cung cấp và phương thức xác thực mà bạn dự định phân phối.
Nếu gateway cung cấp danh mục mô hình, hãy xác nhận rằng gateway trả về một mảng models tương thích với Codex. Đối với suy luận OpenAI sử dụng thông tin xác thực của người dùng, hãy xác nhận rằng gateway chuyển tiếp các tiêu đề ChatGPT bắt buộc đến backend Codex.
Ghi lại phiên bản ứng dụng khách, hệ điều hành, ID nhà cung cấp, bí danh mô hình và phương thức xác thực cho đợt thử nghiệm. Chạy các bước kiểm tra bên dưới trên từng giao diện CLI hoặc ứng dụng máy tính mà bạn dự định hỗ trợ. Nếu bạn cung cấp cả xác thực chỉ qua gateway và xác thực gateway kết hợp với đăng nhập ChatGPT, hãy kiểm tra riêng từng tổ hợp.
| Kiểm tra | Hành động | Bằng chứng đạt yêu cầu |
|---|---|---|
| Cấu hình có hiệu lực | Kiểm tra các lớp cấu hình và xác nhận nhà cung cấp, mô hình và các yêu cầu dự kiến. | Đợt thử nghiệm sử dụng các thiết lập đã phân phối. Các giá trị mặc định của người dùng hoặc hồ sơ không chọn tuyến khác. |
| Kết nối | Làm theo Xác minh kết nối. | Nhà cung cấp và bí danh dự kiến đang hoạt động, prompt thử nghiệm thành công và nhật ký cổng xác định được người dùng thử nghiệm. |
| Truyền luồng | Yêu cầu một câu trả lời ngắn gồm nhiều đoạn. | Văn bản được gửi dần và phương thức truyền tải đang hoạt động phát ra response.completed. Kiểm tra HTTP riêng để xác minh cổng chuyển tiếp các sự kiện SSE mà không lưu đệm. |
| Vòng lặp công cụ cục bộ | Trong một thư mục tạm chỉ có quyền đọc, yêu cầu Codex liệt kê các tệp ở cấp cao nhất và tóm tắt chúng. | Codex thực hiện lệnh gọi công cụ cục bộ, trả về kết quả và tạo câu trả lời cuối cùng mà không chỉnh sửa. |
| Trao đổi tiếp | Đặt một câu hỏi tiếp theo trong cùng luồng hội thoại. | Câu trả lời sử dụng lượt trao đổi trước; cổng chấp nhận đầu vào được gửi lại. Nếu bật WebSocket hoặc phương thức truyền tải tăng dần, phương thức đó cũng giữ nguyên previous_response_id. |
| Lỗi và quy thuộc | Lặp lại với bí danh thử nghiệm cố ý đặt không hợp lệ hoặc thông tin xác thực thử nghiệm đã hết hạn. | Máy khách nhận được lỗi định tuyến hoặc xác thực hữu ích, và các yêu cầu hợp lệ vẫn được quy cho người dùng thử nghiệm. |
Nếu bật phê duyệt tự động, hãy dùng thư mục thử nghiệm tạm để kích hoạt một thao tác công cụ cần được xem xét theo chính sách dự kiến. Xác nhận rằng cổng xử lý yêu cầu xem xét và máy khách áp dụng quyết định phê duyệt. Lệnh gọi công cụ chỉ đọc không cần phê duyệt sẽ không kiểm tra luồng xử lý này. Ghi lại mọi quy trình chưa được hỗ trợ trước khi mở rộng đợt thử nghiệm.
Nếu đợt triển khai thay đổi nhà cung cấp cho người dùng hiện tại, hãy kiểm tra một cuộc hội thoại mới và một cuộc hội thoại được tạo trước thay đổi trên từng máy khách được hỗ trợ. Ghi lại liệu người dùng có thể xem, tiếp tục hoặc phân nhánh cuộc hội thoại hiện có hay không, đồng thời cung cấp quy trình khôi phục cho mọi quy trình bị chặn. Đừng cho rằng việc thay đổi nhà cung cấp mặc định sẽ di chuyển lịch sử hội thoại.
Sau khi các bước kiểm tra này thành công, hãy chuẩn bị bàn giao cho nhà phát triển.
Phân phối cấu hình
Để mọi máy đều có cùng đường kết nối, hãy phân phối URL cơ sở của gateway, ID nhà cung cấp, bí danh mô hình đã được phê duyệt và thiết lập xác thực.
Những thành phần cần phân phối
Với OAuth gốc của gateway, hãy phân phối bảng nhà cung cấp và bảng
[model_providers.<id>.gateway_oauth] từ hướng dẫn
kết nối, kèm theo các
giá trị đăng ký đã thu thập ở trên. Giữ requires_openai_auth = false và bỏ
env_key, experimental_bearer_token cùng bảng auth dùng lệnh khi
OAuth là phương thức xác thực gateway duy nhất.
Với trình trợ giúp thông tin xác thực, hãy phân phối khối config.toml sau qua
lớp cấu hình bạn đã chọn. Sử dụng mô hình mà phiên bản Codex của bạn nhận diện được, hoặc
cung cấp danh mục tương ứng như mô tả ở trên. Cài đặt trình lấy token tại
đường dẫn lệnh đã cấu hình:
model = "gpt-6-sol"
model_provider = "enterprise-gateway"
web_search = "disabled"
[model_providers.enterprise-gateway]
name = "Organization Gateway"
base_url = "https://gateway.example.com/v1"
wire_api = "responses"
[model_providers.enterprise-gateway.auth]
command = "/usr/local/bin/fetch-codex-gateway-token"
args = ["print-token"]
timeout_ms = 30000
refresh_interval_ms = 300000Với khóa thử nghiệm tĩnh có thời hạn ngắn, hãy xóa khối xác thực, đặt env_key = "CODEX_GATEWAY_API_KEY" bên trong [model_providers.enterprise-gateway] và thiết lập biến đó bên ngoài TOML. Không kết hợp env_key với xác thực dựa trên lệnh.
Phân phối giá trị mặc định và yêu cầu bắt buộc
Nếu người dùng không đăng nhập vào Codex bằng ChatGPT, bạn có thể phân phối thiết lập nhóm từ máy chủ riêng. Codex lấy các thiết lập đó độc lập với cách bạn định tuyến yêu cầu mô hình.
Sử dụng Thứ tự ưu tiên cấu hình để chọn nơi phân phối giá trị mặc định. Với các thiết lập bắt buộc và payload MDM trên macOS, hãy xem Cấu hình được quản lý.
Để đặt giá trị mặc định cho toàn máy trên macOS hoặc Linux, hãy dùng /etc/codex/config.toml. Trên
Windows, đặt config.toml trong %ProgramData%\OpenAI\Codex\. Người dùng và
hồ sơ có thể ghi đè các giá trị mặc định này. Các tài liệu tham khảo được liên kết mô tả những
yêu cầu được hỗ trợ và vị trí tệp tương ứng.
Phân phối riêng mọi tệp thực thi hỗ trợ và tệp danh mục cục bộ được tham chiếu.
Để thực thi một URL danh mục từ xa, hãy đặt định nghĩa đầy đủ của nhà cung cấp trong
requirements.toml dưới [model_providers.<id>]. Định nghĩa nhà cung cấp được thực thi
sẽ thay thế bảng nhà cung cấp tương ứng trong cấu hình thông thường;
hãy bao gồm base_url, các chế độ cài đặt xác thực và những trường bắt buộc khác.
Sử dụng yêu cầu model_provider khi bạn cũng cần thực thi việc lựa chọn nhà cung cấp.
model_catalog_json trỏ tới một tệp JSON cục bộ. Nếu bạn bắt buộc áp dụng thiết lập này qua
requirements.toml, yêu cầu đó cố định đường dẫn; nó không phân phối
tệp. Đặt danh mục tại đường dẫn tuyệt đối đó trước khi Codex khởi động.
Ghi đường dẫn Windows tuyệt đối đã được phân giải vào TOML. Codex không mở rộng
%ProgramData% bên trong model_catalog_json hoặc các giá trị command dùng để xác thực nhà cung cấp. Ví
dụ, chỉ sử dụng các đường dẫn này nếu quá trình triển khai của bạn đã đặt tệp tại đó:
model_catalog_json = 'C:\ProgramData\OpenAI\Codex\models.json'
[model_providers.enterprise-gateway.auth]
command = 'C:\ProgramData\OpenAI\Codex\fetch-gateway-token.cmd'
args = ["print-token"]CLI bên trong WSL đọc đường dẫn Linux và CODEX_HOME của Linux; CLI không tự động
kế thừa cấu hình Windows gốc.
Phân phối các tiêu đề định tuyến
Nếu cổng định tuyến yêu cầu theo cấu hình hoặc công cụ, hãy thêm các tiêu đề mà cổng yêu cầu vào nhà cung cấp trong requirements.toml do bạn quản lý. Ví dụ sau cung cấp ID cấu hình định tuyến và xác định Codex là máy khách:
[model_providers.enterprise-gateway.http_headers]
x-portkey-config = "<gateway-routing-config-id>"
x-portkey-metadata = '{"tool_id":"codex"}'Dùng env_http_headers cho các giá trị tiêu đề do môi trường máy khách cung cấp. Gửi yêu cầu thử nghiệm và xác nhận tuyến được chọn trong nhật ký cổng. Xem Nhà cung cấp mô hình tùy chỉnh để biết các tùy chọn tiêu đề.
Cung cấp các giá trị cấu hình cho nhà phát triển
Cung cấp cho nhà phát triển một cách thiết lập phù hợp với đợt thử nghiệm bạn đã kiểm tra. Bao gồm các thông tin sau ngay cả khi bạn phân phối cấu hình tập trung:
| Hạng mục bàn giao | Thông tin cần cung cấp |
|---|---|
| Máy khách được phê duyệt | Máy khách, phiên bản, hệ điều hành và hướng dẫn cài đặt hoặc cập nhật đã dùng trong đợt thử nghiệm. |
| Phân phối cấu hình | Các thiết lập đã được quản lý hay cần thiết lập cục bộ; xác định mọi trình trợ giúp hoặc tệp danh mục được cài đặt riêng. |
| Kết nối dự kiến | ID nhà cung cấp, bí danh mô hình và URL cổng, bao gồm đường dẫn API. Giải thích những giá trị người dùng có thể thay đổi. |
| Các bước đăng nhập | Người dùng phải đăng nhập vào không gian làm việc ChatGPT, xác thực với cổng hay thực hiện cả hai. Nêu rõ không gian làm việc bắt buộc và phương thức xác thực với cổng. |
| Thông tin xác thực và danh mục | Các giá trị đăng ký OAuth, biến môi trường chứa thông tin xác thực hoặc cấu hình trình trợ giúp đã cài đặt, cùng mọi URL danh mục hoặc đường dẫn cục bộ đã phân giải. Cung cấp thông tin bí mật qua cơ chế phân phối thông tin bí mật đã được phê duyệt. |
| Xác minh và hỗ trợ | Bài kiểm tra kết nối, kết quả dự kiến, người phụ trách cổng và thông tin cần đưa vào khi báo cáo lỗi. |
Đối với máy được quản lý, hãy hướng dẫn nhà phát triển xem Kiểm tra cấu hình hiện có. Đối với thiết lập thủ công, hãy hướng dẫn họ xem Cấu hình nhà cung cấp.
Kèm theo hướng dẫn đã được kiểm tra cho các cuộc hội thoại hiện có nếu đợt triển khai này thay đổi nhà cung cấp. Giữ cấu hình hoạt động trước đó sẵn có cho người phụ trách triển khai để sử dụng nếu đợt thử nghiệm phát hiện vấn đề.
Thiết lập thủ công không phải là kênh thực thi bắt buộc. .codex/config.toml cục bộ của dự án không thể ghi đè các khóa định tuyến nhạy cảm về nhà cung cấp hoặc xác thực.
Xác minh từ máy của nhà phát triển
Để xác nhận các thiết lập đã phân phối tới máy của nhà phát triển:
- Xác nhận rằng máy khách được phê duyệt và mọi trình trợ giúp hoặc tệp danh mục bắt buộc đã được cài đặt. Khởi động lại Codex và hoàn tất các bước đăng nhập trong tài liệu bàn giao.
- Xác nhận nhà cung cấp và mô hình dự kiến. Trong CLI, dùng
/status. Dùng/debug-configđể kiểm tra các lớp cấu hình khi thiết lập có hiệu lực khác với tài liệu bàn giao. - Chạy bài kiểm tra ngắn trong Kết nối với cổng.
- Đặt một câu hỏi tiếp theo để xác nhận khả năng tiếp tục, rồi kiểm tra nhật ký cổng để tìm yêu cầu của nhà phát triển đó.
Mở rộng quyền truy cập sau khi đợt thử nghiệm đạt yêu cầu trên các máy khách và tổ hợp xác thực mà bạn hỗ trợ. Lưu cấu hình đã kiểm tra và kết quả cùng hướng dẫn triển khai để bạn có thể lặp lại các bước kiểm tra sau khi cập nhật máy khách, cổng hoặc chính sách.
Khắc phục lỗi triển khai
Dựa vào vấn đề để tìm lớp cấu hình, thông tin xác thực hoặc gateway cần xử lý:
| Vấn đề | Cách khắc phục |
|---|---|
| Không thấy nhà cung cấp dự kiến sau khi khởi động lại. | Kiểm tra lớp cấu hình đang có hiệu lực. Cấu hình người dùng hoặc hồ sơ có thể ghi đè giá trị mặc định của hệ thống. |
| Xác thực thất bại với mọi người dùng. | Kiểm tra xác thực gateway và thông tin xác thực của nhà cung cấp thượng nguồn; xác định dịch vụ nào đã từ chối yêu cầu. |
| Xác thực thất bại với một người dùng. | Kiểm tra quyền truy cập tại nhà cung cấp danh tính, thông tin xác thực gateway hoặc trình lấy token của người dùng đó. |
| Luồng bị ngưng trệ. | Kiểm tra việc lưu đệm của gateway và chuyển tiếp response.completed kết thúc luồng. |
| Thiếu mô hình hoặc mô hình dùng các khả năng chung. | Với bí danh tùy chỉnh, xác nhận bí danh gateway, model của Codex và slug trong danh mục khớp nhau. Kiểm tra đường dẫn danh mục và khả năng tương thích với phiên bản Codex đã cài đặt, sau đó khởi động lại Codex. |
| Đường dẫn Windows không hoạt động. | Sử dụng đường dẫn tuyệt đối đã được phân giải. Trong TOML, dùng chuỗi đặt trong dấu nháy đơn cho đường dẫn Windows có dấu gạch chéo ngược đơn. |
Tái sử dụng triển khai gateway hiện có
Nếu tổ chức của bạn đã sử dụng Claude Code qua gateway, bạn có thể
sử dụng lại sản phẩm gateway, đường mạng, hệ thống ghi nhật ký và quyền truy cập Bedrock. Thêm
tuyến Responses dành cho Codex, thông tin xác thực, bí danh mô hình và config.toml đồng thời
giữ nguyên thiết lập hiện có đang hoạt động. Các thiết lập máy khách Claude và
đặc tả /v1/messages không cấu hình Codex.
| Triển khai Claude hiện có | Chuyển đổi sang Codex |
|---|---|
| Sản phẩm gateway, DNS, TLS, mạng riêng, ghi nhật ký, che dữ liệu nhạy cảm và giám sát | Giữ nguyên các dịch vụ này. Thêm tuyến dành cho Codex đáp ứng Yêu cầu về khả năng tương thích của gateway. |
| Tài khoản Bedrock, thông tin xác thực nhà cung cấp, ranh giới IAM, hồ sơ suy luận và luân chuyển thông tin xác thực | Chỉ giữ lại khi chúng cấp quyền truy cập các mô hình thượng nguồn phía sau bí danh Codex mới. Thông tin xác thực nhà cung cấp vẫn được lưu trên gateway. |
Tuyến /v1/messages của Claude, định dạng Bedrock InvokeModel, các header Anthropic và cơ chế thử lại hoặc lỗi riêng của Claude |
Không dùng lại những thành phần này làm bằng chứng về khả năng tương thích. Codex cần POST /v1/responses, truyền Responses theo luồng, tiếp nối hội thoại, gọi công cụ và lỗi hữu ích. |
ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY hoặc apiKeyHelper |
Codex không hỗ trợ apiKeyHelper. Cấu hình OAuth gốc của gateway, khóa có giới hạn phạm vi bằng env_key hoặc trình lấy token bằng lệnh của Codex. |
Tên mô hình Claude, ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_*_MODEL, modelOverrides và ánh xạ hồ sơ Bedrock |
Yêu cầu nhóm phụ trách gateway chọn tên mô hình và cấu hình mọi bí danh tùy chỉnh. Sử dụng tên mô hình và mọi JSON danh mục mô hình mà họ cung cấp. |
settings.json của Claude, managed-settings.json, các khối JSON env, plist hoặc payload registry |
Giữ nguyên kênh MDM hoặc quản lý cấu hình, nhưng thay vào đó phân phối config.toml của Codex và các giá trị requirements.toml được hỗ trợ. |
Để chuyển đổi an toàn, hãy hoàn thành các bước sau theo thứ tự:
- Kiểm kê luồng Claude hiện tại: URL cổng, nguồn thông tin xác thực, các tiêu đề bắt buộc, bí danh mô hình, ánh xạ hồ sơ Bedrock và kênh phân phối được quản lý.
- Thêm một tuyến Responses song song phục vụ Codex và các bí danh mô hình Codex.
- Chọn OAuth gốc của cổng, API key hoặc trình trợ giúp thông tin xác thực và cấp quyền cho một người dùng thử nghiệm. Với thông tin xác thực tĩnh, cung cấp qua
env_key; với trình trợ giúp, triển khai và kiểm tra hợp đồng của bộ phân giải dựa trên lệnh trong Codex. - Cấu hình nhà cung cấp cho nhà phát triển đó bằng phương thức xác thực bạn đã chọn ở bước 3. Với đợt triển khai được quản lý, chuyển đổi tải trọng sang các đường dẫn và thứ tự ưu tiên của Codex được mô tả trong Triển khai cổng.
- Chạy bài kiểm tra kết nối ngắn trên CLI hoặc giao diện ứng dụng máy tính mà nhà phát triển thực sự sử dụng, sau đó chạy đầy đủ các bước kiểm tra truyền luồng, tiếp tục hội thoại, gọi công cụ, lỗi, ghi nhật ký và định tuyến bí danh trong Kiểm tra Codex qua cổng.
- Sau khi đợt thử nghiệm đạt yêu cầu, phân phối cấu hình cho các nhà phát triển còn lại.
Tài liệu tham chiếu danh mục mô hình
Bắt đầu với tệp models.json cục bộ
Trước tiên, cấu hình và chọn nhà cung cấp cổng của bạn trên máy chạy Codex.
Lưu danh mục này dưới dạng models.json trên máy chạy Codex. Thay
gateway-model bằng ID mô hình chính xác mà cổng chấp nhận. Tên hiển thị
là nhãn người dùng thấy trong bộ chọn mô hình.
{
"models": [
{
"slug": "gateway-model",
"display_name": "Gateway model",
"base_instructions": "Help the user with their coding tasks.",
"supported_reasoning_levels": [],
"shell_type": "shell_command",
"visibility": "list",
"supported_in_api": true,
"priority": 0,
"support_verbosity": false,
"truncation_policy": { "mode": "tokens", "limit": 10000 },
"experimental_supported_tools": []
}
]
}Để xem ví dụ lớn hơn, hãy xem danh mục mô hình của Codex.
Đặt model_catalog_json trong config.toml thành đường dẫn tuyệt đối của tệp.
Khởi động lại Codex, chọn Gateway model và gửi yêu cầu. Kiểm tra xem
cổng đã nhận được ID mô hình bạn đặt trong slug hay chưa.
Với bí danh của mô hình tích hợp sẵn, hãy sao chép toàn bộ mục danh mục của mô hình đó cho phiên bản Codex
của bạn và thay đổi slug cùng display_name. Nếu bí danh không có đích di chuyển, hãy đặt upgrade thành null. Việc này giữ nguyên
cửa sổ ngữ cảnh, các tùy chọn suy luận và thiết lập công cụ của mô hình.
Cung cấp danh mục cho máy khách
Trang này dành cho các nhà phát triển triển khai định dạng Codex Models, định dạng xác định danh mục mô hình và hỗ trợ hoạt động của bộ chọn mô hình. Nếu bạn xây dựng một nhà cung cấp dịch vụ suy luận, chẳng hạn như cổng hoặc dịch vụ đám mây, hãy dùng đặc tả này để cho phép ứng dụng Codex trên máy tính và CLI khám phá các mô hình của bạn và sử dụng hướng dẫn cùng thiết lập khả năng của chúng.
Nếu bạn quản trị doanh nghiệp và muốn kiểm soát danh mục mô hình, hãy xem
hướng dẫn cấu hình model_catalog_url.
Để hỗ trợ định dạng này, hãy triển khai một điểm cuối danh mục có xác thực. Lấy các giá trị mặc định hiện tại từ nhà cung cấp thượng nguồn cho phiên bản Codex gửi yêu cầu, áp dụng các giá trị ghi đè của bạn rồi trả về danh mục kết quả.
client_version Triển khai điểm cuối danh mục
Điểm cuối danh mục mặc định là /models bên dưới base_url của nhà cung cấp.
Ví dụ, với base_url = "https://gateway.example.com/v1", Codex gửi yêu cầu:
GET /v1/models?client_version=0.162.1
Authorization: Bearer <PROVIDER_ACCESS_TOKEN>Cơ chế khám phá mặc định hỗ trợ xác thực thông qua lệnh và xác thực qua backend Codex,
chẳng hạn như ChatGPT. Với nhà cung cấp tùy chỉnh dùng xác thực bằng API key
mà không xác thực thông qua lệnh, hãy đặt model_providers.<id>.model_catalog_url
một cách tường minh để bật khám phá từ xa. Chỉ riêng API key không kích hoạt khám phá
ở đường dẫn mặc định.
Dùng model_catalog_url để chọn URL danh mục đầy đủ, chẳng hạn như
https://gateway.example.com/codex/models. URL này cũng có thể trỏ đến điểm cuối
/v1/models mặc định. Codex dùng trực tiếp URL này mà không nối thêm /models.
Để khám phá bằng API key, hãy giữ features.api_key_model_discovery ở trạng thái bật; cài đặt này được bật
theo mặc định. Chỉ riêng các header tùy chỉnh không bật tính năng khám phá.
Codex gửi thông tin xác thực và các header đã cấu hình của nhà cung cấp được chọn, đồng thời
thêm client_version và mọi query_params của nhà cung cấp. Lưu trữ danh mục trên một
dịch vụ được phép nhận các thông tin xác thực đó.
Xác thực bên gọi, lấy các giá trị mặc định thượng nguồn tương ứng, áp dụng các giá trị
ghi đè của bạn rồi trả về trực tiếp JSON ModelsResponse đầy đủ. Gán cho mỗi
mục một slug duy nhất, không rỗng. Với model_catalog_url được đặt tường minh, Codex từ chối
chuyển hướng và phản hồi lớn hơn 1 MiB. Tiếp tục thực thi quyền truy cập mô hình đối với
các yêu cầu suy luận.
Xóa mọi cài đặt model_catalog_json đang có hiệu lực khỏi các máy khách sử dụng điểm cuối:
tệp cục bộ được ưu tiên và ngăn việc lấy dữ liệu từ xa.
Khớp với lược đồ của máy khách
Đọc tham số truy vấn client_version trong yêu cầu danh mục. Codex gửi phiên bản
CLI dưới dạng major.minor.patch, sau khi loại bỏ mọi hậu tố tiền phát hành. Với máy khách
trên máy tính, đây là phiên bản CLI đi kèm.
Dùng thẻ rust-v<version> tương ứng trong kho lưu trữ Codex công khai, hoặc
commit mã nguồn chính xác cho bản dựng tùy chỉnh. Các liên kết này dùng rust-v0.162.1; hãy chọn
bản sửa đổi khớp với máy khách của bạn:
- Đọc các kiểu phản hồi
ModelsResponsevàModelInfođể xem lược đồ. - Xem
models.jsonđi kèm để có ví dụ đầy đủ. Đây là dữ liệu danh mục, không phải tài liệu JSON Schema.
Tệp đi kèm là ảnh chụp dữ liệu tại thời điểm phát hành. Lấy các giá trị mặc định hiện tại trước khi tạo danh mục của bạn.
Lấy các giá trị mặc định thượng nguồn hiện tại
Các nhà cung cấp đám mây phục vụ mô hình OpenAI lấy giá trị mặc định từ OpenAI. Gateway đọc danh mục của nhà cung cấp đám mây hoặc thượng nguồn để giữ lại cài đặt của mô hình đã triển khai và tính khả dụng theo tài khoản và khu vực. Truyền phiên bản Codex gửi yêu cầu ở từng bước và xác thực riêng với từng điểm cuối.
Để lấy giá trị mặc định trực tiếp từ OpenAI, hãy gọi điểm cuối mô hình Codex với
cùng client_version. Ví dụ, với API key của OpenAI:
curl --fail --silent --show-error \
'https://chatgpt.com/backend-api/codex/models?client_version=0.162.1' \
-H "Authorization: Bearer $OPENAI_API_KEY"Đối với tích hợp ChatGPT, hãy dùng token truy cập ChatGPT của bên gọi và
header ChatGPT-Account-ID khi phù hợp. Dùng thông tin xác thực được cấp quyền cho
điểm cuối thượng nguồn; API key riêng của gateway không xác thực được với OpenAI.
Phân tích toàn bộ phản hồi, bao gồm mảng models ở cấp cao nhất. Điểm cuối này
trả về siêu dữ liệu Codex như chỉ dẫn, giá trị mặc định cho suy luận, cài đặt công cụ,
giới hạn ngữ cảnh và các cấp dịch vụ. Điểm cuối /v1/models công khai không
cung cấp danh mục này.
Làm mới các giá trị mặc định này ngay cả khi phiên bản Codex chưa thay đổi. Giới hạn các yêu cầu trong phạm vi danh tính thượng nguồn dự định dùng và tuân thủ các chỉ thị bộ nhớ đệm của phản hồi: danh mục có thể phụ thuộc vào quyền truy cập của bên gọi. Giữ riêng các giá trị ghi đè để bạn có thể áp dụng lại chúng cho các giá trị mặc định mới.
Áp dụng các giá trị ghi đè của nhà cung cấp
Thay đổi giá trị các trường nhưng vẫn giữ nguyên cấu trúc phản hồi của phiên bản:
- Lọc để chỉ giữ các mô hình mà bên gọi có thể dùng. Ánh xạ từng
slugtới một tuyến suy luận được hỗ trợ và điều chỉnhdisplay_name,descriptionhoặcpriority. Với bí danh không có quá trình di chuyển mô hình, đặtupgradethànhnull. - Đặt các tùy chọn suy luận, giới hạn ngữ cảnh, phương thức đầu vào và cấp dịch vụ thành
các giá trị mà mô hình và tuyến của bạn hỗ trợ. Giữ giá trị mặc định trong các
lựa chọn được hỗ trợ. Với tuyến không có cấp dịch vụ, xóa
service_tiersvàadditional_speed_tiers, đồng thời đặtdefault_service_tierthànhnull. - Giữ nguyên chỉ dẫn và cài đặt công cụ từ thượng nguồn trừ khi bạn đã kiểm thử một phương án thay thế. Siêu dữ liệu không bổ sung khả năng cho mô hình hay cấp quyền truy cập suy luận.
Đối với bí danh mô hình trên gateway, hãy xem cách cung cấp siêu dữ liệu mô hình. Kiểm thử danh mục kết quả với từng phiên bản Codex được hỗ trợ.
Sử dụng các kiểu Rust công khai
Dùng các crate từ cùng thẻ Git hoặc commit công khai với lược đồ của máy khách:
- Dùng
codex-protocolchocodex_protocol::openai_models::{ModelsResponse, ModelInfo}. Phân tích bằngserde_json::from_slice::<ModelsResponse>(), chỉnh sửacatalog.modelsvà tuần tự hóa toàn bộ đối tượng bao bằngserde_json::to_vec(). Đối tượng bao xử lý các trường tương thích cho chỉ dẫn mô hình. - Dùng
codex-models-manager::bundled_models_response()để tải danh mục tĩnh đi kèm bản sửa đổi đó dưới dạngModelsResponse. Hàm này không lấy các giá trị mặc định thượng nguồn hiện tại.