Hubungkan ke gateway

Konfigurasikan gateway model dan lakukan autentikasi dengan OAuth bawaan gateway, API key, atau alat bantu kredensial.

Hubungkan Codex ke gateway model organisasi Anda menggunakan pengaturan penyedia dan metode autentikasi yang diberikan oleh tim gateway Anda. Gateway merutekan permintaan model ke backend Anda, seperti Amazon Bedrock.

Periksa konfigurasi yang sudah ada

Instal klien Codex dengan versi yang telah diuji administrator Anda. Jika organisasi Anda mengelola pengaturannya, buka klien tersebut dan selesaikan langkah-langkah masuk dalam petunjuk serah terima yang Anda terima. Anda dapat melewati contoh konfigurasi penyedia di bawah ini.

  • Untuk CLI, periksa profil yang dipilih dan jalankan codex doctor. Setelah dijalankan, gunakan /status untuk memastikan model dan penyedia yang aktif.
  • Untuk aplikasi macOS, periksa ~/.codex/config.toml atau konfigurasi terkelola yang didistribusikan organisasi Anda.
  • Untuk aplikasi Windows, periksa %USERPROFILE%\.codex\config.toml atau konfigurasi sistem yang didistribusikan organisasi Anda.

Jika penyedia gateway dan model yang diharapkan sudah aktif, selesaikan langkah-langkah masuk yang diberikan administrator Anda, lalu lanjutkan ke Memverifikasi koneksi. Hindari menambahkan konfigurasi penyedia kedua ke komputer yang dikelola. Jika pengaturannya berbeda dari petunjuk serah terima administrator, tanyakan lapisan konfigurasi mana yang seharusnya menyediakan pengaturan tersebut sebelum mengedit file lokal.

Dapatkan detail koneksi gateway Anda

Untuk penyiapan manual, pastikan apakah Anda memerlukan proses masuk ke ruang kerja ChatGPT, autentikasi gateway, atau keduanya.

Untuk mengonfigurasi Codex sendiri, dapatkan nilai berikut dari tim gateway Anda:

  • URL dasar gateway HTTPS, termasuk jalur API-nya, seperti https://gateway.example.com/v1.
  • Nama model dan ID penyedia yang akan digunakan.
  • Metode autentikasi: OAuth gateway bawaan, API key dengan cakupan terbatas beserta variabel lingkungannya, atau pembantu kredensial yang terinstal.
  • Untuk OAuth, URL otorisasi, URL token, ID klien publik, dan cakupan yang diperlukan. Untuk gateway yang menggunakan cookie atau header kustom, sertakan namanya.
  • URL katalog model yang diperlukan, atau file katalog beserta jalur lokal absolutnya.

Konfigurasikan penyedia

Buka config.toml di ~/.codex/config.toml pada macOS atau Linux, atau %USERPROFILE%\.codex\config.toml pada Windows.

Gabungkan contoh ini ke dalam konfigurasi yang sudah ada, lalu ganti URL dan model dengan nilai yang diberikan administrator Anda. Jangan menambahkan definisi kedua untuk kunci atau tabel yang sudah ada. Contoh ini menggunakan gpt-6-sol; gunakan tanpa katalog kustom hanya jika administrator Anda memastikan bahwa versi Codex Anda mengenali model tersebut dan metadata bawaannya sesuai dengan gateway.

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"
requires_openai_auth = false

Lalu tambahkan pengaturan autentikasi yang diberikan oleh tim gateway Anda.

enterprise-gateway merupakan contoh ID penyedia. Gunakan ID yang sama dalam model_provider serta tabel penyedia dan autentikasinya. Contoh ini menonaktifkan pencarian web untuk pengujian koneksi awal; administrator Anda harus memverifikasi dukungan fitur sebelum mengaktifkannya.

Konfigurasikan katalog model Anda

Konfirmasikan dengan tim gateway Anda bagaimana Codex mendapatkan kapabilitas dan instruksi untuk model yang Anda pilih:

  • Nama bawaan: Jika gateway menerima nama model persis seperti yang disertakan dalam versi Codex Anda dan mengarahkannya ke model yang sesuai, tetapkan model ke nama tersebut. Codex sudah memiliki metadatanya.
  • Endpoint katalog: Jika gateway menyajikan metadata yang kompatibel dengan Codex, gunakan URL katalog lengkapnya. Ini dapat berupa endpoint /v1/models yang mengimplementasikan respons katalog Codex. Respons yang hanya mencantumkan ID model tidak memadai untuk alias kustom.
  • File katalog: Jika gateway Anda menggunakan alias kustom dan administrator Anda mendistribusikan file, gunakan contoh models.json lokal. Gunakan file lokal jika OAuth gateway bawaan merupakan satu-satunya kredensial Anda dan Anda memerlukan metadata kustom.

Untuk autentikasi dengan API key atau alat bantu, jika administrator Anda menyediakan URL katalog, tambahkan URL tersebut ke tabel [model_providers.enterprise-gateway] yang sudah ada:

model_catalog_url = "https://gateway.example.com/codex/models.json"

Hapus setiap pengaturan model_catalog_json yang berlaku; pengaturan tersebut lebih diprioritaskan daripada URL. Administrator dapat menemukan persyaratan endpoint dalam penyiapan katalog jarak jauh.

Jika administrator Anda memberikan file katalog model lokal, simpan file tersebut dan tambahkan model_catalog_json sebelum tabel TOML pertama dengan menggunakan jalur absolut file. Alias kustom memerlukan metadata katalog yang cocok. Contoh:

model_catalog_json = "/etc/codex/gateway-models.json"

Gunakan nama model dan katalog yang disediakan secara bersamaan oleh administrator Anda. Jangan menambahkan jalur katalog kecuali file tersebut ada di lokasi itu.

Pilih metode autentikasi

Gunakan OAuth bawaan gateway untuk masuk melalui browser, API key untuk kredensial dengan cakupan terbatas, atau alat bantu kredensial jika organisasi Anda menyediakan perintah.

{/* prettier-ignore */}

Gunakan OAuth bawaan gateway

OAuth gateway bekerja secara independen dari proses masuk ChatGPT. Gunakan metode ini jika gateway Anda menerima token akses yang diterbitkan oleh penyedia identitas organisasi Anda, seperti Microsoft Entra ID. Codex menangani proses masuk melalui browser, penyimpanan kredensial terenkripsi, dan penyegaran token ketika server otorisasi menerbitkan token penyegaran.

Untuk autentikasi khusus gateway, Codex CLI 0.166.0 dan versi lebih baru mengirimkan token akses dalam Authorization: Bearer <gateway access token> secara default. Hapus semua entri Authorization dari http_headers atau env_http_headers penyedia ini.

Tim gateway Anda harus mendaftarkan klien OAuth publik yang mendukung alur kode otorisasi dengan PKCE. Tambahkan tabel ini ke konfigurasi penyedia di config.toml, lalu ganti URL dan ID klien dengan nilai yang sesuai:

[model_providers.enterprise-gateway.gateway_oauth]
authorization_url = "https://login.example.com/oauth/authorize"
token_url = "https://login.example.com/oauth/token"
client_id = "YOUR_PUBLIC_CLIENT_ID"
# redirect_port = 43127

Tambahkan scopes dan, jika diperlukan, resource ke tabel ini menggunakan nilai yang disyaratkan penyedia identitas dan gateway Anda. Minta cakupan yang diperlukan untuk token penyegaran jika penyedia Anda mensyaratkannya. Secara default, Codex menggunakan port loopback yang tersedia. Jika penyedia identitas Anda memerlukan URI pengalihan tetap, tetapkan redirect_port dan daftarkan http://127.0.0.1:43127/callback untuk contoh ini.

Jika gateway Anda memerlukan cookie atau header khusus, tetapkan kolom opsional delivery dalam tabel OAuth. Pilih metode yang divalidasi oleh gateway Anda:

delivery = { kind = "cookie", name = "auth-openid" }
delivery = { kind = "header", name = "X-Gateway-Token", scheme = "Bearer" }

Jika deployment Anda juga memerlukan proses masuk ChatGPT, gunakan cookie atau header gateway terpisah yang ditampilkan di atas. Lihat Aktifkan proses masuk ChatGPT.

Gateway yang hanya menerima API key statis harus menambahkan dukungan untuk token OAuth dan metode pengirimannya sebelum Anda dapat menggunakan alur ini. Gateway tetap mengelola kredensial upstream-nya sendiri, seperti kredensial AWS untuk Bedrock.

Jika OAuth merupakan satu-satunya kredensial Anda, pertahankan requires_openai_auth = false dan hapus pengaturan env_key, experimental_bearer_token, atau auth sebelumnya yang digunakan untuk kredensial gateway. Gunakan katalog model lokal jika Anda memerlukan metadata model khusus; OAuth saja tidak mengaktifkan penemuan katalog jarak jauh.

Mulai ulang aplikasi desktop dan ikuti petunjuk masuk gateway untuk membuka browser. Di CLI, jalankan codex dan ikuti proses masuk melalui browser saat Codex pertama kali mengakses gateway. Selesaikan proses masuk dan MFA organisasi Anda, lalu kembali ke klien. Jika pemberian otorisasi kedaluwarsa atau Codex tidak dapat memperbaruinya, masuk kembali saat diminta.

OAuth bawaan gateway memerlukan browser dan callback loopback yang dapat diakses. Metode ini tidak memiliki opsi cadangan berupa kode perangkat. Jika CLI berjalan melalui SSH, tetapkan redirect_port = 43127 dalam tabel OAuth dan daftarkan URI pengalihan yang sesuai seperti dijelaskan di atas. Dari komputer yang menjalankan browser Anda, teruskan port tersebut sebelum menjalankan Codex:

ssh -L 43127:127.0.0.1:43127 user@remote

Dalam sesi SSH tersebut, jalankan codex dan buka URL masuk gateway di browser lokal Anda. CLI di dalam kontainer juga memerlukan callback yang dapat diakses dari browser. Jika Anda tidak dapat membuat callback dapat diakses, gunakan API key atau alat bantu kredensial sebagai gantinya.

Aktifkan proses masuk ChatGPT (disarankan)

Jika organisasi Anda menggunakan ruang kerja ChatGPT, masuk ke ruang kerja tersebut memberi pengguna akses ke fitur yang tersedia bagi mereka, seperti plugin pihak pertama. Kontrol ruang kerja Anda tetap berlaku, dan gateway Anda tetap menangani permintaan model. Bandingkan ketersediaan fitur.

Untuk penyiapan manual, perbarui tabel [model_providers.enterprise-gateway] yang ada sebelum masuk:

  1. Tetapkan requires_openai_auth = true dan pastikan base_url tetap mengarah ke gateway Anda. Hapus semua pengaturan env_key, experimental_bearer_token, dan auth penyedia agar Codex menggunakan kredensial OpenAI Anda untuk autentikasi utama.
  2. Kirim kredensial gateway secara terpisah. Untuk OAuth bawaan gateway, konfigurasikan gateway_oauth.delivery agar menggunakan cookie atau header khusus yang diterima gateway Anda. Untuk API key atau program pembantu kredensial, gunakan header autentikasi khusus. Gunakan Authorization hanya untuk kredensial OpenAI.

Masuk ke ruang kerja ChatGPT yang ditentukan administrator Anda. Selesaikan proses masuk gateway jika diminta, lalu verifikasi koneksi Anda.

Administrator dapat mendistribusikan pengaturan penyedia terkelola dan memverifikasi penerusan kredensial.

Tangani kredensial di gateway

Gateway menerima dua kredensial pada setiap permintaan model. Misalnya, saat Codex mengirim token OAuth gateway dalam cookie:

POST /backend-api/codex/responses
Authorization: Bearer <ChatGPT token>
ChatGPT-Account-ID: <workspace ID, when available>
Cookie: auth-openid=<gateway token>

Validasi kredensial gateway dan hapus cookie atau header khususnya. Samarkan kredensial dan data permintaan sensitif dalam log. Pilih kredensial yang akan digunakan untuk permintaan ke layanan hulu:

  • Teruskan kredensial pengguna untuk inferensi langsung oleh OpenAI (disarankan). Ini memungkinkan OpenAI mengaitkan penggunaan dengan pengguna tersebut dan menerapkan pengaturan inferensinya. Untuk rute ini, gateway harus meneruskan /models dan /responses melalui proksi ke https://chatgpt.com/backend-api/codex serta meneruskan Authorization dan setiap header ChatGPT-Account-ID tanpa perubahan.
  • Biarkan gateway melakukan autentikasi ke penyedia inferensi. Gunakan kredensial yang dikonfigurasikan di gateway untuk penyedia tersebut. Jangan sertakan token OpenAI pengguna dan header ChatGPT-Account-ID apa pun dalam permintaan ke layanan hulu.

Diagram berikut menunjukkan rute yang disarankan untuk inferensi OpenAI.

Cara kerja kunci gateway dengan proses masuk ChatGPT
Gunakan kembali perintah kredensial melalui program bantu peluncuran. Kunci gateway yang sama berpindah dari Authorization ke X-Gateway-Key, sementara proses masuk ChatGPT menyediakan Authorization.
Gateway memvalidasi dan menghapus X-Gateway-Key, lalu meneruskan Authorization ChatGPT dan ID akun apa pun tanpa perubahan ke backend Codex.
Cara kerja OAuth gateway dengan proses masuk ChatGPT
Ganti autentikasi gateway berbasis API key dengan OAuth bawaan gateway yang digunakan bersama proses masuk ChatGPT.
Gateway memproses cookie OAuth miliknya dan meneruskan kredensial ChatGPT ke backend Codex.

Tambahkan header perutean (opsional)

Gunakan pengaturan perutean yang diberikan administrator Anda. Operator gateway dapat mendistribusikan pengaturan ini dan memeriksa rute yang dipilih dalam log gateway.

Hanya permintaan ke penyedia model yang menggunakan rute gateway ini. Sesi suara menggunakan rute terpisah. Proses masuk ruang kerja, MCP server, dan plugin juga dapat menggunakan jalur jaringan lain.

Jalankan klien

Saat menggunakan proses masuk ChatGPT, jalankan klien dan masuk ke ruang kerja yang menyediakan konfigurasi terkelola. Jika Anda menggunakan OAuth bawaan gateway, selesaikan juga proses masuk gateway organisasi Anda saat diminta. Kemudian verifikasi koneksi.

Untuk penyedia yang dikonfigurasikan secara lokal, ikuti petunjuk untuk klien Anda.

Konfigurasikan CLI

Secara default, CLI membaca ~/.codex/config.toml pada macOS atau Linux. Setelah menyimpan pengaturan penyedia, jalankan codex. Di dalam WSL, gunakan konfigurasi dan jalur Linux kecuali CODEX_HOME menunjuk ke lokasi lain.

Konfigurasikan aplikasi macOS

Aplikasi macOS membaca ~/.codex/config.toml yang sama. Setelah menyimpan pengaturan penyedia, mulai ulang aplikasi. Jika Anda menggunakan variabel lingkungan untuk kredensial, pastikan variabel tersebut tersedia bagi proses aplikasi.

Konfigurasikan aplikasi Windows

Tempatkan pengaturan penyedia di %USERPROFILE%\.codex\config.toml, lalu mulai ulang aplikasi. Untuk autentikasi berbasis perintah, gunakan resolver yang diinstal oleh administrator Anda. Misalnya, ganti tabel autentikasi Unix dengan:

[model_providers.enterprise-gateway.auth]
command = 'C:\Program Files\OpenAI\Codex\fetch-codex-gateway-token.exe'
args = ["print-token"]
timeout_ms = 30000
refresh_interval_ms = 300000

Dalam TOML Windows, string literal dengan tanda kutip tunggal mempertahankan garis miring terbalik. Ganti juga jalur katalog Unix, misalnya dengan 'C:\ProgramData\OpenAI\Codex\models.json', menggunakan jalur sebenarnya yang diberikan administrator Anda.

Konfigurasikan MCP server dan plugin secara terpisah. Kredensial gateway model tidak memberikan otorisasi akses ke alat atau sistem Anda yang terhubung.

Verifikasi koneksi

Gunakan ID penyedia dan alias model dalam informasi yang diberikan administrator Anda. Penyedia mengidentifikasi koneksi yang dikonfigurasi; alias model mengidentifikasi model yang dirutekan melalui koneksi tersebut. Proses masuk ChatGPT dan autentikasi gateway mengontrol akses dan keduanya mungkin diperlukan.

Mulai ulang klien setelah mengubah konfigurasi. Di CLI, jalankan codex dan gunakan /status untuk memeriksa model dan penyedia yang aktif. Di aplikasi desktop, periksa model yang dipilih dan konfigurasinya.

Kirim prompt ini dalam tugas baru:

Reply with exactly: gateway-ok

Hasil yang diharapkan adalah gateway-ok. Respons saja tidak membuktikan rute mana yang menanganinya: minta administrator Anda memastikan bahwa gateway mencatat pengguna, alias model, dan rute upstream yang dimaksud. Jangan mengidentifikasi model dengan menanyakan namanya.

Atasi masalah koneksi

Gejala Yang perlu diperiksa
Penyedia yang diharapkan tidak aktif. Periksa profil yang dipilih dan urutan prioritas konfigurasi. Pastikan kunci tingkat teratas tidak berada di dalam tabel penyedia.
Proses masuk OAuth atau pengiriman token gagal. Periksa pendaftaran klien publik, URI pengalihan, cakupan, serta cookie atau header yang dikonfigurasi. Pastikan gateway menerima token akses yang diterbitkan.
Autentikasi API key atau helper gagal. Pastikan variabel kredensial tersedia bagi proses klien, atau helper yang terinstal dapat mengambil token yang masih berlaku. Minta administrator membedakan autentikasi gateway dari autentikasi upstream.
Model tidak ditemukan. Pastikan nama model yang diberikan sudah benar dan minta administrator memeriksa rutenya.
Model menggunakan kemampuan yang tidak diharapkan. Minta administrator memeriksa apakah metadata katalog sesuai dengan model yang diwakili alias tersebut.
Streaming terhenti atau percakapan lanjutan gagal. Minta pemilik gateway memeriksa buffering proxy, peristiwa penutup response.completed, dan Kompatibilitas gateway.
Jalur katalog atau alat bantu tidak berfungsi. Pastikan file tersebut ada di jalur absolut yang dikonfigurasi dalam lingkungan yang menjalankan Codex.

Saat meminta bantuan, sertakan versi klien, sistem operasi, penyedia dan alias model yang diharapkan, metode autentikasi, serta langkah yang gagal. Sertakan pesan kesalahan dan waktu permintaan agar pemilik gateway dapat menemukan permintaan tersebut. Hapus token, cookie, header otorisasi, dan prompt sensitif. Jangan kirim file kredensial atau dump konfigurasi yang berisi rahasia.

Gunakan deployment gateway yang sudah ada

Minta pengaturan penyedia Codex dan alias model yang disetujui kepada tim gateway Anda. Jika tim masih perlu mengaktifkan rute Codex, bagikan daftar periksa migrasi administrator.

Dokumentasi terkait