Triển khai Codex qua gateway

Triển khai Codex qua gateway LLM của tổ chức. Cấu hình tuyến định tuyến mô hình, cấp thông tin xác thực cho nhà phát triển và phân phối cấu hình Codex đã được xác minh.

Đ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.
• Thông tin xác thực gateway dành cho thử nghiệm với phạm vi giới hạn.
• Cơ chế phân phối bí mật hoặc trình trợ giúp thông tin xác thực đã được kiểm thử.
• Cách phân phối cấu hình, tệp thực thi của trình trợ giúp và mọi 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_id chỉ 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_output tươ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ự:

1. Chọn tên mô hình và xác minh tuyến định tuyến.
2. Cấp thông tin xác thực cho nhà phát triển.
3. Kiểm thử Codex qua gateway.
4. Phân phối cấu hình.
5. 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.

Sử dụng danh mục mô hình cho tên tùy chỉnh

Sử dụng model_catalog_json khi gateway dùng tên mô hình mà Codex không nhận diện được. 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 khớp, yêu cầu vẫn có thể tới mô hình thượng nguồn dự kiến trong khi Codex dùng các thiết lập chung.

Ví dụ, để dùng company-coding-model làm bí danh cho gpt-6-luna:

1. Tạo bí danh company-coding-model trên gateway và định tuyến bí danh đó tới mô hình thượng nguồn gpt-6-luna đã được phê duyệt.
2. Tải danh mục mô hình Codex cho phiên bản Codex của bạn và lưu một bản sao dưới tên gateway-models.json. Dùng tệp này làm điểm khởi đầu.
3. Chỉnh sửa mục gpt-6-luna trong bản sao: đặt slug thành company-coding-model và kiểm tra xem siêu dữ liệu còn lại có khớp với mô hình thượng nguồn và khả năng của gateway hay không. Với bí danh không có chuyển đổi mô hình, hãy đặt upgrade thành null.
4. Giữ các mục trong mảng models cấp cao nhất và phân phối tệp tới từng máy khách. Danh mục tùy chỉnh thay thế danh mục đi kèm, vì vậy hãy đưa vào mọi mô hình mà người dùng cần chọn.

Đối với Bedrock qua LiteLLM, hãy áp dụng các chỉnh sửa danh mục bắt buộc.

Đặ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.

Cấp thông tin xác thực cho nhà phát triển

1. 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ẻ.
2. 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.
3. 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.
4. 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.
5. 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 kỳ thành phần nào, hãy làm theo Kết nối với gateway để cấu hình một người dùng thử nghiệm biệt lập với khối cấu hình nhà cung cấp và cơ chế thông tin xác thực mà bạn dự định phân phối.

Thực hiện các bước kiểm tra bên dưới trên cùng giao diện CLI hoặc ứng dụng máy tính mà các nhà phát triển sẽ sử dụng:

Sau khi các bước kiểm tra này thành công, hãy hướng dẫn nhà phát triển xem Kết nối với gateway để cấu hình và xác minh máy của họ.

Phân phối cấu hình

Để mọi máy 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à cơ chế thông tin xác thực.

Những thành phần cần phân phối

Để đặt giá trị mặc định cho nhà cung cấp, hãy phân phối khối config.toml này qua lớp cấu hình bạn đã chọn. Dùng mô hình được phiên bản Codex của bạn nhận diện hoặc cung cấp danh mục tương ứng như mô tả ở trên. Cài đặt trình phân giải 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 = 300000

Vớ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

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 của trình trợ giúp và tệp danh mục được tham chiếu.

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.

Cung cấp các giá trị cấu hình cho nhà phát triển

Nếu không có cơ chế phân phối được quản lý, hãy cung cấp cho mỗi nhà phát triển URL gateway, ID nhà cung cấp, bí danh mô hình, biến thông tin xác thực hoặc trình phân giải và mọi đường dẫn danh mục. Hướng dẫn họ xem Kết nối với gateway để cấu hình và xác minh máy của mình.

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:

1. Khởi động lại Codex và xác nhận nhà cung cấp cùng mô hình dự kiến.
2. Chạy bài kiểm tra ngắn trong Kết nối với gateway.
3. Đặt một câu hỏi tiếp theo để xác nhận khả năng tiếp nối, sau đó kiểm tra nhật ký gateway để tìm yêu cầu của nhà phát triển đó.

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ý:

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.

Để chuyển đổi an toàn, hãy hoàn thành các bước sau theo thứ tự:

1. Kiểm kê đường kết nối Claude hiện tại: URL gateway, nguồn thông tin xác thực, các header 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ý.
2. Thêm song song một tuyến Responses dành cho Codex và các bí danh mô hình Codex.
3. Cấp một bộ thông tin xác thực Codex với phạm vi giới hạn. Nếu Codex sẽ dùng thông tin xác thực tĩnh, hãy cung cấp thông tin xác thực mới đó qua env_key; nếu Claude dùng trình trợ giúp thông tin xác thực, hãy triển khai và kiểm thử đặc tả trình phân giải dựa trên lệnh của Codex.
4. Cấu hình cho nhà phát triển đó bằng khối cấu hình nhà cung cấp. Với triển khai được quản lý, chuyển đổi payload theo các đường dẫn và thứ tự ưu tiên của Codex được mô tả trong Triển khai Codex qua gateway.
5. Chạy bài kiểm tra kết nối ngắn trên giao diện CLI hoặc ứng dụng máy tính thực tế của nhà phát triển, sau đó chạy đầy đủ các bước kiểm tra truyền theo luồng, tiếp nối hội thoại, gọi công cụ, lỗi, ghi nhật ký và định tuyến bí danh trong Kiểm thử Codex qua gateway.
6. Sau khi thử nghiệm ban đầu đạt yêu cầu, hãy phân phối cấu hình cho các nhà phát triển còn lại.

Tài liệu liên quan

• Kết nối với gateway
• MCP
• Plugin
• Cấu hình được quản lý