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/statusuntuk memastikan model dan penyedia yang aktif. - Untuk aplikasi macOS, periksa
~/.codex/config.tomlatau konfigurasi terkelola yang didistribusikan organisasi Anda. - Untuk aplikasi Windows, periksa
%USERPROFILE%\.codex\config.tomlatau 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 = falseLalu 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
modelke 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/modelsyang 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 = 43127Tambahkan 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@remoteDalam 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.
Gunakan API key
Gunakan pengaturan ini jika gateway mengharapkan API key dalam header Authorization.
Tambahkan pengaturan berikut ke dalam tabel yang sudah ada,
[model_providers.enterprise-gateway]:
env_key = "CODEX_GATEWAY_API_KEY"Sediakan kredensial gateway Anda sebagai CODEX_GATEWAY_API_KEY di
lingkungan proses yang menjalankan Codex, menggunakan mekanisme distribusi rahasia
organisasi Anda. Jangan menyimpan kredensial dalam TOML atau repositori. Variabel
yang ditetapkan di terminal mungkin tidak tersedia bagi aplikasi yang dijalankan dari desktop.
Gunakan header autentikasi kustom
Jika gateway Anda memerlukan header seperti X-API-Key alih-alih token bearer,
ganti env_key dalam tabel penyedia dengan:
env_http_headers = { "X-API-Key" = "CODEX_GATEWAY_API_KEY" }Gunakan nama header persis seperti yang diberikan administrator Anda. Codex membaca nilainya dari
variabel lingkungan yang disebutkan; jangan simpan kredensial dalam file konfigurasi.
Lihat referensi konfigurasi untuk
model_providers.<id>.env_http_headers.
Saat menggunakan proses masuk ChatGPT, gunakan header khusus untuk kunci gateway agar Codex dapat mengirim kredensial OpenAI pengguna dalam Authorization.
Jika header kustom merupakan satu-satunya mekanisme autentikasi Anda, gunakan
model_catalog_json; penemuan katalog jarak jauh tidak akan berjalan.
Gunakan alat bantu kredensial organisasi
Jika administrator Anda menyediakan autentikasi berbasis perintah, gunakan program bantu yang telah mereka instal
beserta konfigurasinya sebagai pengganti env_key. Jangan konfigurasikan kedua mekanisme sekaligus.
Program bantu tersebut harus tersedia di komputer Anda; Codex tidak menginstalnya. Misalnya,
tambahkan tabel ini tanpa env_key, menggunakan jalur resolver dan
argumen yang disediakan administrator Anda:
[model_providers.enterprise-gateway.auth]
command = "/usr/local/bin/fetch-codex-gateway-token"
args = ["print-token"]
timeout_ms = 30000
refresh_interval_ms = 300000Referensi autentikasi penyedia kustom mendefinisikan perintah, argumen, batas waktu, interval penyegaran, dan kontrak keluaran token. Tanyakan kepada administrator Anda cara memperbarui sesi masuk jika alat bantu tidak dapat lagi mengambil token.
Saat menggunakan proses masuk ChatGPT, jalankan program bantu sebelum menjalankan Codex dan teruskan keluarannya melalui header gateway khusus alih-alih mengonfigurasi tabel auth. Saat kunci kedaluwarsa, dapatkan kunci baru dan jalankan ulang Codex.
Gunakan jalur absolut yang telah diresolusikan untuk file eksekusi alat bantu dan file katalog.
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:
- Tetapkan
requires_openai_auth = truedan pastikanbase_urltetap mengarah ke gateway Anda. Hapus semua pengaturanenv_key,experimental_bearer_token, danauthpenyedia agar Codex menggunakan kredensial OpenAI Anda untuk autentikasi utama. - Kirim kredensial gateway secara terpisah. Untuk OAuth bawaan gateway, konfigurasikan
gateway_oauth.deliveryagar menggunakan cookie atau header khusus yang diterima gateway Anda. Untuk API key atau program pembantu kredensial, gunakan header autentikasi khusus. GunakanAuthorizationhanya 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
/modelsdan/responsesmelalui proksi kehttps://chatgpt.com/backend-api/codexserta meneruskanAuthorizationdan setiap headerChatGPT-Account-IDtanpa 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-IDapa pun dalam permintaan ke layanan hulu.
Diagram berikut menunjukkan rute yang disarankan untuk inferensi OpenAI.
Cara kerja kunci gateway dengan proses masuk ChatGPT


Cara kerja OAuth gateway dengan proses masuk ChatGPT


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 = 300000Dalam 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-okHasil 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.