Terapkan gateway
Distribusikan dan verifikasi koneksi gateway Codex untuk organisasi Anda
Sebagai administrator gateway, konfigurasikan rute model dan berikan otorisasi kepada pengguna uji coba. Uji koneksi pada setiap klien yang Anda dukung sebelum mendistribusikan pengaturan kepada pengembang. Gunakan OAuth bawaan gateway, API key, atau program pembantu kredensial untuk autentikasi gateway. Untuk menggabungkan autentikasi gateway dengan proses masuk ruang kerja ChatGPT, lihat Masuk dengan ChatGPT melalui gateway.
Prasyarat
Sebelum menerapkan Codex untuk pengembang, pastikan Anda memiliki:
- Gateway yang melayani HTTPS pada URL dasar persis seperti yang akan Anda distribusikan.
- Kredensial penyedia upstream yang disimpan oleh gateway.
- Alias model yang disetujui untuk digunakan oleh Codex dan dipetakan ke model upstream yang dituju.
- Metode autentikasi yang telah diuji: OAuth bawaan gateway, API key gateway dengan cakupan terbatas, atau helper kredensial.
- Untuk OAuth, klien publik yang terdaftar, pengguna uji yang disetujui, dan dukungan gateway untuk memvalidasi token akses OAuth.
- Untuk API key atau helper, mekanisme distribusi rahasia atau helper yang telah diuji.
- Cara untuk mendistribusikan konfigurasi, helper yang diperlukan, dan file katalog.
Persyaratan gateway
Sebelum menghubungkan Codex, verifikasi bahwa produk gateway mempertahankan perilaku wajib berikut:
- Menerima permintaan Responses API dari Codex di
POST /v1/responses. - Mengalirkan peristiwa SSE tanpa buffering dan mengakhirinya dengan
response.completed. - Mempertahankan kelanjutan percakapan dengan input yang dikirim ulang.
- Mempertahankan
previous_response_idhanya ketika WebSocket atau transport inkremental diaktifkan. - Mempertahankan pemanggilan fungsi dan item
function_call_outputyang sesuai. - Merutekan setiap alias model yang digunakan oleh Codex ke model upstream yang dituju.
- Mengautentikasi pengguna secara terpisah dan mengembalikan kesalahan yang informatif tanpa menyembunyikan penyebabnya.
Endpoint pemeriksaan kesehatan, /v1/models, respons Chat Completions, atau satu balasan teks biasa tidak membuktikan kelayakan gateway. Lihat Persyaratan kompatibilitas gateway untuk kontrak terperinci.
Luncurkan gateway
Untuk beralih dari gateway yang telah diterapkan ke pengalaman pengembang yang telah diverifikasi, selesaikan lima tahap pemeriksaan berikut secara berurutan:
- Pilih nama model dan verifikasi rute.
- Pilih autentikasi.
- Uji Codex melalui gateway.
- Distribusikan konfigurasi.
- Verifikasi dari komputer pengembang.
Pilih nama dan rute model
Atur model Codex ke nama model gateway. Konfigurasikan gateway untuk merutekan nama tersebut ke model upstream yang disetujui.
| Nama model gateway | Konfigurasi Codex |
|---|---|
| Nama model bawaan yang disertakan dalam versi Codex Anda | Atur model dalam config.toml ke nama persis ini. |
Alias kustom, seperti company-coding-model |
Sediakan katalog jarak jauh atau lokal yang berisi alias dan metadata model terkait. |
Gunakan katalog model untuk nama kustom
Untuk katalog lokal, mulailah dengan contoh models.json.
Sediakan katalog model jika gateway Anda menggunakan nama model yang tidak dikenali Codex. Katalog tersebut menyediakan instruksi, opsi penalaran, batas konteks, dan kemampuan alat yang digunakan Codex untuk nama tersebut. Tanpa entri yang cocok, permintaan dapat mencapai model upstream yang dituju sementara Codex menggunakan pengaturan generik.
Host katalog jarak jauh dengan model_providers.<id>.model_catalog_url untuk memperbarui metadata model secara terpusat, atau distribusikan file lokal dengan model_catalog_json. Gunakan katalog lokal jika OAuth bawaan gateway merupakan satu-satunya kredensial; OAuth saja tidak mengaktifkan penemuan katalog jarak jauh. Lihat referensi konfigurasi untuk kedua pengaturan tersebut.
Dapatkan endpoint atau file katalog yang kompatibel dengan versi Codex Anda dari penyedia cloud atau gateway Anda. Pastikan katalog tersebut menyertakan setiap alias yang disetujui beserta metadata modelnya. Untuk implementasi katalog, lihat Mengimplementasikan katalog model untuk gateway dan cloud.
Sajikan katalog jarak jauh
Gunakan endpoint katalog HTTPS yang disediakan oleh penyedia Anda.
Distribusikan URL endpoint lengkap dalam tabel config.toml milik penyedia yang dipilih:
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"Pastikan CODEX_GATEWAY_API_KEY tersedia bagi proses Codex. Atur base_url
secara terpisah untuk merutekan inferensi melalui gateway. Jika Anda menghilangkannya, Codex menggunakan
endpoint OpenAI default untuk mode autentikasi saat ini.
Penemuan memerlukan autentikasi berbasis API key, perintah, atau backend Codex. OAuth bawaan gateway atau header kustom saja tidak memicunya.
Koordinasikan pembaruan katalog dengan penyedia Anda saat model yang disetujui berubah. Mulai ulang klien setelah mengubah konfigurasinya.
Hapus setiap pengaturan model_catalog_json yang berlaku, termasuk yang diberlakukan melalui
requirements.toml. Pengaturan tersebut lebih diprioritaskan daripada URL jarak jauh dan mencegah pengambilan.
Distribusikan katalog lokal
Gunakan model_catalog_json untuk memuat berkas yang disediakan penyedia saat aplikasi dimulai. Katalog kustom
lokal menggantikan katalog bawaan.
Atur alias gateway, slug katalog, dan model Codex ke company-coding-model. Tambahkan pengaturan ini sebelum tabel TOML pertama dalam konfigurasi Codex yang Anda distribusikan, dengan menggunakan jalur absolut file yang sebenarnya:
model = "company-coding-model"
model_catalog_json = "/absolute/path/to/gateway-models.json"Mulai ulang CLI atau aplikasi desktop setelah mengubah katalog karena Codex memuatnya saat dimulai.
Verifikasi rute model
Untuk setiap model, verifikasi rutenya dengan permintaan Responses nyata dan catatan
gateway. Respons /v1/models dapat membantu menemukan nama, tetapi tidak membuktikan bahwa
model mendukung perilaku permintaan dan alat yang diperlukan.
Perutean model dan otorisasi alat merupakan bagian terpisah dari peluncuran. Konfigurasikan koneksi MCP, distribusi plugin, dan kebijakannya secara terpisah.
Pilih autentikasi
OAuth bawaan gateway
- Daftarkan klien OAuth publik yang mendukung kode otorisasi dengan PKCE, dan setujui pengguna atau grup yang dapat masuk.
- Konfigurasikan gateway untuk memvalidasi token akses yang diterbitkan dalam cookie atau header kustom yang dipilih. Terapkan model yang disetujui, batas laju, dan anggaran untuk identitas setiap pengguna.
- Ikuti OAuth bawaan gateway untuk mengumpulkan URL otorisasi dan token, ID klien publik, cakupan, sumber daya opsional, pengaturan pengiriman token, dan port pengalihan tetap jika ada. Daftarkan URI pengalihan loopback yang sesuai pada penyedia identitas Anda.
- Uji proses masuk melalui browser, pembaruan token, dan pencabutan akses dengan pengguna uji di CLI atau aplikasi desktop yang akan Anda terapkan. Pastikan browser dapat menjangkau callback, termasuk untuk pengguna CLI jarak jauh.
Pengguna masuk secara individual. Anda mendistribusikan konfigurasi OAuth, bukan rahasia klien, API key gateway, atau file eksekusi helper. Simpan kredensial penyedia upstream di gateway.
API key atau helper kredensial
- Terbitkan satu kredensial gateway dengan cakupan terbatas untuk setiap pengembang agar Anda dapat mengatribusikan penggunaan dan mencabut akses secara individual.
- Tetapkan model yang disetujui, batas laju, anggaran, masa berlaku, dan periode perpanjangan untuk setiap kredensial.
- Kirimkan kredensial melalui pengelola rahasia atau helper kredensial yang terpasang. Jangan simpan kredensial penyedia upstream dan administrator gateway di komputer pengembang.
- Jika Anda menggunakan helper, ikuti kontrak autentikasi berbasis perintah dan uji pengambilan serta penyegaran token sebelum distribusi.
- Beri tahu pengembang cara memperpanjang kredensial dan pihak yang dapat dihubungi untuk mendapatkan bantuan.
Uji Codex melalui gateway
Sebelum mendistribusikan apa pun, ikuti Konfigurasikan penyedia untuk mengonfigurasi satu pengguna uji terisolasi dengan blok penyedia dan metode autentikasi yang akan Anda distribusikan.
Jika gateway menyajikan katalog model, pastikan gateway mengembalikan array models yang kompatibel dengan Codex. Untuk inferensi OpenAI yang menggunakan kredensial pengguna, pastikan gateway meneruskan header ChatGPT yang diperlukan ke backend Codex.
Catat versi klien, sistem operasi, ID penyedia, alias model, dan metode autentikasi untuk uji coba Anda. Jalankan pemeriksaan di bawah ini dari setiap antarmuka CLI atau desktop yang ingin Anda dukung. Jika Anda menyediakan autentikasi khusus gateway serta autentikasi gateway bersama proses masuk ChatGPT, uji setiap kombinasi secara terpisah.
| Pemeriksaan | Tindakan | Bukti keberhasilan |
|---|---|---|
| Konfigurasi efektif | Periksa lapisan konfigurasi dan pastikan penyedia, model, serta persyaratan sesuai dengan yang dimaksud. | Uji coba menggunakan pengaturan yang didistribusikan. Pengaturan default pengguna atau profil tidak memilih rute lain. |
| Koneksi | Ikuti Verifikasi koneksi. | Penyedia dan alias yang diharapkan aktif, prompt pengujian berhasil, dan log gateway mengidentifikasi pengguna pengujian. |
| Streaming | Minta jawaban singkat yang terdiri dari beberapa paragraf. | Teks diterima secara bertahap dan transport aktif mengirimkan response.completed. Uji HTTP secara terpisah untuk memastikan gateway meneruskan peristiwa SSE tanpa buffering. |
| Siklus alat lokal | Dalam folder sementara dengan izin hanya baca, minta Codex mencantumkan file di tingkat teratas dan merangkumnya. | Codex melakukan panggilan alat lokal, mengembalikan hasilnya, dan menghasilkan jawaban akhir tanpa mengedit file. |
| Tindak lanjut | Ajukan pertanyaan lanjutan dalam utas yang sama. | Jawaban menggunakan giliran sebelumnya; gateway menerima input yang dikirim ulang. Jika WebSocket atau transport inkremental diaktifkan, transport tersebut juga mempertahankan previous_response_id. |
| Kesalahan dan atribusi | Ulangi dengan alias pengujian yang sengaja dibuat tidak valid atau kredensial pengujian yang sudah kedaluwarsa. | Klien menerima pesan kesalahan perutean atau autentikasi yang berguna, dan permintaan yang valid tetap diatribusikan kepada pengguna pengujian. |
Jika persetujuan otomatis diaktifkan, gunakan folder pengujian sementara untuk memicu tindakan alat yang memerlukan peninjauan berdasarkan kebijakan yang Anda inginkan. Pastikan gateway menangani permintaan peninjauan dan klien menerapkan keputusan persetujuan. Panggilan alat hanya baca yang tidak memerlukan persetujuan tidak menguji alur ini. Catat setiap alur kerja yang tidak didukung sebelum memperluas uji coba.
Jika peluncuran ini mengubah penyedia bagi pengguna yang sudah ada, uji percakapan baru dan percakapan yang dibuat sebelum perubahan pada setiap klien yang didukung. Catat apakah pengguna dapat melihat, melanjutkan, atau membuat cabang dari percakapan yang sudah ada, dan berikan prosedur pemulihan untuk setiap alur kerja yang terblokir. Jangan berasumsi bahwa mengubah penyedia default akan memigrasikan riwayat percakapan.
Setelah semua pemeriksaan ini berhasil, siapkan serah terima kepada pengembang.
Distribusikan konfigurasi
Agar setiap komputer memiliki jalur koneksi yang sama, distribusikan URL dasar gateway, ID penyedia, alias model yang disetujui, dan pengaturan autentikasi.
Komponen yang perlu didistribusikan
Untuk OAuth bawaan gateway, distribusikan tabel penyedia dan
[model_providers.<id>.gateway_oauth] dari panduan
koneksi, beserta
nilai pendaftaran yang dikumpulkan di atas. Pertahankan requires_openai_auth = false dan hilangkan
env_key, experimental_bearer_token, serta tabel auth berbasis perintah jika
OAuth merupakan satu-satunya kredensial gateway.
Untuk helper kredensial, distribusikan blok config.toml berikut melalui
lapisan konfigurasi yang Anda pilih. Gunakan model yang dikenali oleh versi Codex Anda, atau
sediakan katalog yang sesuai seperti dijelaskan di atas. Instal resolver token Anda di
jalur perintah yang dikonfigurasi:
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 = 300000Untuk kunci pengujian statis berumur pendek, hapus blok autentikasi, letakkan env_key = "CODEX_GATEWAY_API_KEY" di dalam [model_providers.enterprise-gateway], dan tetapkan variabel tersebut di luar TOML. Jangan gabungkan env_key dengan autentikasi berbasis perintah.
Distribusikan nilai default dan persyaratan
Jika pengguna Anda tidak masuk ke Codex dengan ChatGPT, Anda dapat mendistribusikan pengaturan tim dari server Anda sendiri. Codex mengambil pengaturan tersebut secara independen dari cara Anda merutekan permintaan model.
Gunakan Urutan prioritas konfigurasi untuk memilih tempat mendistribusikan nilai default. Untuk pengaturan yang diberlakukan dan payload MDM macOS, lihat Konfigurasi terkelola.
Untuk nilai default yang berlaku di seluruh host pada macOS atau Linux, gunakan /etc/codex/config.toml. Pada
Windows, letakkan config.toml di %ProgramData%\OpenAI\Codex\. Pengguna dan
profil dapat mengganti nilai default ini. Referensi tertaut menjelaskan persyaratan
yang didukung dan lokasi filenya.
Distribusikan setiap file katalog lokal dan executable pembantu yang dirujuk secara terpisah.
Untuk memberlakukan URL katalog jarak jauh, tempatkan definisi penyedia lengkap dalam
requirements.toml di bawah [model_providers.<id>]. Definisi penyedia yang diberlakukan
menggantikan tabel penyedia yang cocok dari konfigurasi biasa;
sertakan base_url, pengaturan autentikasi, dan bidang wajib lainnya.
Gunakan persyaratan model_provider jika Anda juga perlu memberlakukan pemilihan
penyedia.
model_catalog_json menunjuk ke file JSON lokal. Jika Anda memberlakukannya melalui
requirements.toml, persyaratan tersebut menetapkan jalurnya; persyaratan itu tidak mendistribusikan
file. Letakkan katalog pada jalur absolut tersebut sebelum Codex dimulai.
Tulis jalur Windows absolut yang telah diresolusikan dalam TOML. Codex tidak mengekspansi
%ProgramData% di dalam model_catalog_json atau nilai command autentikasi penyedia. Sebagai
contoh, gunakan jalur berikut hanya jika penerapan Anda menempatkan file di sana:
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 di dalam WSL membaca jalur Linux dan CODEX_HOME Linux; CLI tersebut tidak secara otomatis
mewarisi konfigurasi Windows native.
Distribusikan header perutean
Jika gateway Anda merutekan permintaan berdasarkan konfigurasi atau alat, tambahkan header yang diharapkannya ke penyedia dalam requirements.toml yang Anda kelola. Contoh berikut menyediakan ID konfigurasi perutean dan mengidentifikasi Codex sebagai klien:
[model_providers.enterprise-gateway.http_headers]
x-portkey-config = "<gateway-routing-config-id>"
x-portkey-metadata = '{"tool_id":"codex"}'Gunakan env_http_headers untuk nilai header yang disediakan oleh lingkungan klien. Kirim permintaan pengujian dan pastikan rute yang dipilih melalui log gateway. Lihat Penyedia model kustom untuk opsi header.
Berikan nilai konfigurasi kepada pengembang
Berikan satu alur penyiapan kepada pengembang yang sesuai dengan uji coba yang telah Anda lakukan. Sertakan informasi berikut meskipun Anda mendistribusikan konfigurasi secara terpusat:
| Item serah terima | Informasi yang perlu disediakan |
|---|---|
| Klien yang disetujui | Klien, versi, sistem operasi, dan petunjuk penginstalan atau pembaruan yang digunakan dalam uji coba. |
| Distribusi konfigurasi | Apakah pengaturan sudah dikelola atau memerlukan penyiapan lokal; identifikasi helper atau file katalog yang diinstal secara terpisah. |
| Koneksi yang diharapkan | ID penyedia, alias model, dan URL gateway, termasuk jalur API-nya. Jelaskan nilai mana yang boleh diubah pengguna. |
| Langkah masuk | Apakah pengguna harus masuk ke ruang kerja ChatGPT, melakukan autentikasi ke gateway, atau keduanya. Sebutkan ruang kerja yang diperlukan dan metode autentikasi gateway. |
| Kredensial dan katalog | Nilai pendaftaran OAuth, variabel lingkungan kredensial, atau konfigurasi helper yang diinstal, beserta URL katalog atau jalur lokal yang telah diresolusi. Distribusikan rahasia melalui mekanisme distribusi rahasia yang Anda setujui. |
| Verifikasi dan dukungan | Pengujian koneksi, hasil yang diharapkan, penanggung jawab gateway, dan informasi yang perlu disertakan saat melaporkan kegagalan. |
Untuk mesin yang dikelola, arahkan pengembang ke Periksa konfigurasi yang sudah ada. Untuk penyiapan manual, arahkan mereka ke Konfigurasikan penyedia.
Sertakan petunjuk yang telah Anda uji untuk percakapan yang sudah ada jika peluncuran ini mengubah penyedia. Pastikan konfigurasi sebelumnya yang berfungsi tetap tersedia bagi penanggung jawab peluncuran untuk berjaga-jaga jika uji coba mengungkap masalah.
Penyiapan manual bukan saluran pemberlakuan kebijakan. .codex/config.toml lokal proyek tidak dapat mengganti kunci perutean penyedia atau autentikasi yang sensitif.
Verifikasi dari komputer pengembang
Untuk memastikan pengaturan yang didistribusikan telah diterima oleh komputer pengembang:
- Pastikan klien yang disetujui dan semua helper atau file katalog yang diperlukan telah diinstal. Mulai ulang Codex dan selesaikan langkah masuk yang tercantum dalam serah terima Anda.
- Pastikan penyedia dan model sesuai dengan yang diharapkan. Di CLI, gunakan
/status. Gunakan/debug-configuntuk memeriksa lapisan konfigurasi jika pengaturan efektif berbeda dari informasi serah terima. - Jalankan pengujian singkat di Hubungkan ke gateway.
- Ajukan satu pertanyaan lanjutan untuk memastikan percakapan dapat dilanjutkan, lalu periksa log gateway untuk permintaan pengembang tersebut.
Perluas akses setelah uji coba berhasil pada klien dan kombinasi autentikasi yang Anda dukung. Simpan konfigurasi yang telah diuji dan hasilnya bersama petunjuk peluncuran agar Anda dapat mengulangi pemeriksaan setelah pembaruan klien, gateway, atau kebijakan.
Atasi kegagalan peluncuran
Gunakan masalah yang terjadi untuk menemukan lapisan konfigurasi, kredensial, atau gateway yang memerlukan perhatian:
| Masalah | Penanganan |
|---|---|
| Penyedia yang diharapkan tidak muncul setelah mulai ulang. | Periksa lapisan konfigurasi yang berlaku. Konfigurasi pengguna atau profil dapat mengganti nilai default sistem. |
| Autentikasi gagal untuk semua pengguna. | Periksa autentikasi gateway dan kredensial penyedia upstream; identifikasi layanan yang menolak permintaan. |
| Autentikasi gagal untuk satu pengguna. | Periksa akses pengguna tersebut ke penyedia identitas, kredensial gateway, atau resolver token. |
| Streaming terhenti. | Periksa buffering gateway dan penerusan response.completed penutup. |
| Model tidak muncul atau menggunakan kemampuan generik. | Untuk alias kustom, pastikan alias gateway, model Codex, dan slug katalog cocok. Periksa jalur katalog dan kompatibilitasnya dengan versi Codex yang terpasang, lalu mulai ulang Codex. |
| Jalur Windows gagal. | Gunakan jalur absolut yang telah diresolusikan. Dalam TOML, gunakan string dengan tanda kutip tunggal untuk jalur Windows dengan garis miring terbalik tunggal. |
Gunakan kembali penerapan gateway yang ada
Jika organisasi Anda sudah menggunakan Claude Code melalui gateway, Anda mungkin dapat
menggunakan kembali produk gateway, jalur jaringan, pencatatan log, dan akses Bedrock. Tambahkan
rute Responses yang melayani Codex, kredensial, alias model, dan config.toml sambil
mempertahankan penyiapan yang sudah berfungsi. Pengaturan klien Claude dan
kontrak /v1/messages tidak mengonfigurasi Codex.
| Penerapan Claude yang ada | Migrasi Codex |
|---|---|
| Produk gateway, DNS, TLS, jaringan privat, pencatatan log, penyamaran data, dan pemantauan | Pertahankan layanan ini. Tambahkan rute yang melayani Codex dan memenuhi Persyaratan kompatibilitas gateway. |
| Akun Bedrock, kredensial penyedia, batas IAM, profil inferensi, dan rotasi kredensial | Pertahankan hanya jika semuanya mengizinkan model upstream di balik alias Codex baru. Kredensial penyedia tetap berada di gateway. |
Rute Claude /v1/messages, format Bedrock InvokeModel, header Anthropic, serta percobaan ulang atau kesalahan khusus Claude |
Jangan gunakan kembali hal-hal ini sebagai bukti kompatibilitas. Codex memerlukan POST /v1/responses, streaming Responses, kelanjutan percakapan, pemanggilan alat, dan kesalahan yang informatif. |
ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, atau apiKeyHelper |
Codex tidak mendukung apiKeyHelper. Konfigurasikan OAuth bawaan gateway, kunci dengan cakupan terbatas melalui env_key, atau resolver token Codex berbasis perintah. |
Nama model Claude, ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_*_MODEL, modelOverrides, dan pemetaan profil Bedrock |
Minta tim gateway Anda memilih nama model dan mengonfigurasi alias kustom yang diperlukan. Gunakan nama model dan JSON katalog model apa pun yang mereka sediakan. |
settings.json Claude, managed-settings.json, blok JSON env, plist, atau payload registri |
Pertahankan saluran MDM atau pengelolaan konfigurasi yang sama, tetapi distribusikan config.toml Codex dan nilai requirements.toml yang didukung sebagai gantinya. |
Untuk bermigrasi dengan aman, selesaikan langkah-langkah berikut secara berurutan:
- Inventarisasi alur Claude saat ini: URL gateway, sumber kredensial, header yang diperlukan, alias model, pemetaan profil Bedrock, dan saluran distribusi terkelola.
- Tambahkan rute Responses paralel yang melayani Codex beserta alias model Codex.
- Pilih OAuth bawaan gateway, API key, atau helper kredensial dan beri otorisasi kepada satu pengguna pengujian. Untuk kredensial statis, sediakan melalui
env_key; untuk helper, implementasikan dan uji kontrak resolver Codex berbasis perintah. - Konfigurasikan penyedia untuk pengembang tersebut menggunakan metode autentikasi yang Anda pilih pada langkah 3. Untuk peluncuran terkelola, sesuaikan payload dengan jalur dan urutan prioritas Codex yang dijelaskan dalam Luncurkan gateway.
- Jalankan pemeriksaan koneksi singkat pada antarmuka CLI atau desktop yang benar-benar digunakan pengembang, lalu jalankan seluruh pemeriksaan streaming, kelanjutan percakapan, panggilan alat, kesalahan, pencatatan log, dan perutean alias dalam Uji Codex melalui gateway.
- Setelah uji coba berhasil, distribusikan konfigurasi kepada pengembang lainnya.
Referensi katalog model
Mulai dengan file models.json lokal
Pertama, konfigurasikan dan pilih penyedia gateway Anda pada mesin tempat Anda menjalankan Codex.
Simpan katalog ini sebagai models.json pada mesin yang menjalankan Codex. Ganti
gateway-model dengan ID model persis yang diterima gateway Anda. Nama tampilan
adalah label yang dilihat pengguna di pemilih model.
{
"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": []
}
]
}Untuk contoh yang lebih lengkap, lihat katalog model Codex.
Tetapkan model_catalog_json dalam config.toml ke jalur absolut file tersebut.
Mulai ulang Codex, pilih Gateway model, lalu kirim permintaan. Pastikan
gateway menerima ID model yang Anda tetapkan dalam slug.
Untuk alias model bawaan, salin entri katalog lengkapnya untuk versi Codex
Anda dan ubah slug serta display_name. Jika alias tidak memiliki target migrasi, tetapkan upgrade ke null. Ini mempertahankan
jendela konteks, opsi penalaran, dan pengaturan alat model tersebut.
Sajikan katalog kepada klien
Halaman ini ditujukan bagi pengembang yang mengimplementasikan format Codex Models, yang mendefinisikan katalog model dan mendukung pemilih model. Jika Anda membangun penyedia inferensi, seperti gateway atau layanan cloud, gunakan spesifikasi ini agar aplikasi desktop Codex dan CLI dapat menemukan model Anda serta menggunakan instruksi dan pengaturan kemampuannya.
Jika Anda mengelola perusahaan dan ingin mengontrol katalog model, lihat
panduan konfigurasi model_catalog_url.
Untuk mendukung format ini, implementasikan endpoint katalog yang diautentikasi. Ambil nilai default terkini dari penyedia upstream Anda untuk versi Codex yang meminta, terapkan penggantian nilai Anda, lalu kembalikan katalog yang dihasilkan.
client_version Implementasikan endpoint katalog
Endpoint katalog default adalah /models di bawah base_url penyedia.
Misalnya, dengan base_url = "https://gateway.example.com/v1", Codex mengirim permintaan:
GET /v1/models?client_version=0.162.1
Authorization: Bearer <PROVIDER_ACCESS_TOKEN>Penemuan default mendukung autentikasi berbasis perintah dan autentikasi backend Codex,
seperti ChatGPT. Untuk penyedia kustom yang menggunakan autentikasi API key
tanpa autentikasi berbasis perintah, tetapkan model_providers.<id>.model_catalog_url
secara eksplisit untuk mengaktifkan penemuan jarak jauh. API key saja tidak memicu penemuan
pada jalur default.
Gunakan model_catalog_url untuk memilih URL katalog lengkap, seperti
https://gateway.example.com/codex/models. URL ini juga dapat mengarah ke endpoint default
/v1/models. Codex menggunakan URL ini secara langsung tanpa menambahkan /models.
Untuk penemuan melalui API key, biarkan features.api_key_model_discovery tetap aktif; fitur ini aktif
secara default. Header kustom saja tidak mengaktifkan penemuan.
Codex mengirim autentikasi penyedia yang dipilih beserta header yang dikonfigurasi, lalu
menambahkan client_version dan setiap query_params penyedia. Host katalog pada
layanan yang berwenang menerima kredensial tersebut.
Autentikasi pemanggil, ambil nilai default upstream yang sesuai, terapkan penggantian nilai
Anda, lalu kembalikan JSON ModelsResponse lengkap secara langsung. Beri setiap
entri slug yang unik dan tidak kosong. Untuk model_catalog_url yang ditetapkan secara eksplisit, Codex menolak
pengalihan dan respons yang lebih besar dari 1 MiB. Tetap terapkan kontrol akses model pada
permintaan inferensi.
Hapus setiap pengaturan model_catalog_json yang berlaku dari klien yang menggunakan endpoint:
file lokal diprioritaskan dan mencegah pengambilan jarak jauh.
Sesuaikan dengan skema klien
Baca parameter kueri client_version pada permintaan katalog. Codex mengirim
versi CLI-nya dalam format major.minor.patch, dengan semua akhiran prarilis dihapus. Untuk klien desktop,
versi ini adalah versi CLI yang disertakan.
Gunakan tag rust-v<version> yang sesuai di repositori publik Codex, atau
commit sumber yang tepat untuk build kustom. Tautan ini menggunakan rust-v0.162.1; pilih
revisi yang sesuai dengan klien Anda:
- Baca tipe respons
ModelsResponsedanModelInfountuk mengetahui skemanya. - Periksa
models.jsonyang disertakan untuk melihat contoh lengkap. Ini adalah data katalog, bukan dokumen JSON Schema.
File yang disertakan merupakan snapshot rilis. Ambil nilai default terkini sebelum membuat katalog Anda.
Ambil nilai default upstream terkini
Penyedia cloud yang menyediakan model OpenAI mengambil nilai default dari OpenAI. Gateway membaca katalog penyedia cloud atau upstream mereka agar tetap mempertahankan pengaturan model yang diterapkan serta ketersediaan akun dan wilayah. Teruskan versi Codex yang meminta pada setiap langkah, dan lakukan autentikasi secara terpisah ke setiap endpoint.
Untuk mengambil nilai default langsung dari OpenAI, panggil endpoint model Codex dengan
client_version yang sama. Misalnya, dengan API key OpenAI:
curl --fail --silent --show-error \
'https://chatgpt.com/backend-api/codex/models?client_version=0.162.1' \
-H "Authorization: Bearer $OPENAI_API_KEY"Untuk integrasi ChatGPT, gunakan token akses ChatGPT milik pemanggil dan
header ChatGPT-Account-ID jika berlaku. Gunakan kredensial yang diizinkan untuk
endpoint upstream; API key gateway Anda sendiri tidak dapat digunakan untuk autentikasi ke OpenAI.
Urai seluruh respons, termasuk array models di tingkat teratas. Endpoint ini
mengembalikan metadata Codex seperti instruksi, nilai default penalaran, pengaturan alat,
batas konteks, dan tingkat layanan. Endpoint publik /v1/models tidak
menyediakan katalog ini.
Perbarui nilai default ini meskipun versi Codex belum berubah. Batasi permintaan pada identitas upstream yang dituju dan patuhi kontrol cache respons: katalog dapat bergantung pada akses pemanggil. Simpan penggantian nilai Anda secara terpisah agar Anda dapat menerapkannya kembali pada nilai default terbaru.
Terapkan penggantian nilai penyedia
Ubah nilai field dengan tetap mempertahankan struktur respons versi tersebut:
- Filter model agar hanya mencakup model yang dapat digunakan pemanggil. Petakan setiap
slugke rute inferensi yang didukung, lalu sesuaikandisplay_name,description, ataupriority. Untuk alias tanpa migrasi model, tetapkanupgradekenull. - Tetapkan opsi penalaran, batas konteks, modalitas input, dan tingkat layanan ke
nilai yang didukung model dan rute Anda. Pastikan nilai default termasuk dalam
pilihan yang didukung. Untuk rute tanpa tingkat layanan, kosongkan
service_tiersdanadditional_speed_tiers, lalu tetapkandefault_service_tierkenull. - Pertahankan instruksi upstream dan pengaturan alat kecuali Anda telah menguji penggantinya. Metadata tidak menambahkan kemampuan model atau memberikan akses inferensi.
Untuk alias model gateway, lihat cara menyediakan metadata model. Uji katalog yang dihasilkan dengan setiap versi Codex yang didukung.
Gunakan tipe Rust publik
Gunakan crate dari tag atau commit Git publik yang sama dengan skema klien:
- Gunakan
codex-protocoluntukcodex_protocol::openai_models::{ModelsResponse, ModelInfo}. Urai denganserde_json::from_slice::<ModelsResponse>(), editcatalog.models, lalu serialisasikan seluruh pembungkus denganserde_json::to_vec(). Pembungkus ini menangani field kompatibilitas untuk instruksi model. - Gunakan
codex-models-manager::bundled_models_response()untuk memuat katalog statis yang disertakan pada revisi tersebut sebagaiModelsResponse. Fungsi ini tidak mengambil nilai default upstream terkini.