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_id hanya ketika WebSocket atau transport inkremental diaktifkan.
  • Mempertahankan pemanggilan fungsi dan item function_call_output yang 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:

  1. Pilih nama model dan verifikasi rute.
  2. Pilih autentikasi.
  3. Uji Codex melalui gateway.
  4. Distribusikan konfigurasi.
  5. 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

  1. Daftarkan klien OAuth publik yang mendukung kode otorisasi dengan PKCE, dan setujui pengguna atau grup yang dapat masuk.
  2. 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.
  3. 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.
  4. 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

  1. Terbitkan satu kredensial gateway dengan cakupan terbatas untuk setiap pengembang agar Anda dapat mengatribusikan penggunaan dan mencabut akses secara individual.
  2. Tetapkan model yang disetujui, batas laju, anggaran, masa berlaku, dan periode perpanjangan untuk setiap kredensial.
  3. Kirimkan kredensial melalui pengelola rahasia atau helper kredensial yang terpasang. Jangan simpan kredensial penyedia upstream dan administrator gateway di komputer pengembang.
  4. Jika Anda menggunakan helper, ikuti kontrak autentikasi berbasis perintah dan uji pengambilan serta penyegaran token sebelum distribusi.
  5. 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 = 300000

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

  1. 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.
  2. Pastikan penyedia dan model sesuai dengan yang diharapkan. Di CLI, gunakan /status. Gunakan /debug-config untuk memeriksa lapisan konfigurasi jika pengaturan efektif berbeda dari informasi serah terima.
  3. Jalankan pengujian singkat di Hubungkan ke gateway.
  4. 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:

  1. Inventarisasi alur Claude saat ini: URL gateway, sumber kredensial, header yang diperlukan, alias model, pemetaan profil Bedrock, dan saluran distribusi terkelola.
  2. Tambahkan rute Responses paralel yang melayani Codex beserta alias model Codex.
  3. 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.
  4. 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.
  5. 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.
  6. 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.

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:

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 slug ke rute inferensi yang didukung, lalu sesuaikan display_name, description, atau priority. Untuk alias tanpa migrasi model, tetapkan upgrade ke null.
  • 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_tiers dan additional_speed_tiers, lalu tetapkan default_service_tier ke null.
  • 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-protocol untuk codex_protocol::openai_models::{ModelsResponse, ModelInfo}. Urai dengan serde_json::from_slice::<ModelsResponse>(), edit catalog.models, lalu serialisasikan seluruh pembungkus dengan serde_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 sebagai ModelsResponse. Fungsi ini tidak mengambil nilai default upstream terkini.

Dokumentasi terkait