Hubungkan model eksternal ke Codex

Panduan ini membahas dua jalur integrasi untuk model pihak ketiga yang dihosting:

Ada satu batasan penting yang perlu dipahami terlebih dahulu:

Panduan ini berlaku untuk klien Codex yang berjalan secara lokal, termasuk Codex CLI, ekstensi Codex IDE, dan klien desktop yang membaca config.toml yang sama. Chat cloud Codex saat ini tidak dapat beralih ke model kustom melalui konfigurasi ini.

Sebelum memulai

Instal atau perbarui Codex CLI

npm install -g @openai/codex@latest
codex --version

Setelah instalasi pertama, jalankan Codex setidaknya sekali:

codex

Tindakan ini menginisialisasi direktori konfigurasi pengguna.

Lokasi file konfigurasi Codex

macOS dan Linux:

~/.codex/config.toml

Windows:

%USERPROFILE%\.codex\config.toml

Cadangkan file sebelum membuat perubahan.

macOS / Linux:

mkdir -p ~/.codex/backup
cp ~/.codex/config.toml \
  ~/.codex/backup/config.toml.$(date +%Y%m%d-%H%M%S) \
  2>/dev/null || true

PowerShell:

$codexDir = Join-Path $HOME ".codex"
$backupDir = Join-Path $codexDir "backup"
New-Item -ItemType Directory -Force -Path $backupDir | Out-Null

$configFile = Join-Path $codexDir "config.toml"
if (Test-Path $configFile) {
  $timestamp = Get-Date -Format "yyyyMMdd-HHmmss"
  Copy-Item $configFile (Join-Path $backupDir "config.toml.$timestamp")
}

Penyedia, MCP, dan gateway model berbeda

Konsep-konsep ini menyelesaikan masalah yang berbeda:

• model_provider menentukan ke mana Codex mengirim permintaan model;
• MCP menambahkan alat dan konteks seperti GitHub, browser, atau basis data;
• gateway model menangani konversi protokol, autentikasi, perutean, pencatatan, atau pembatasan laju antara Codex dan model upstream.

Untuk mengubah model yang mendasarinya, konfigurasikan penyedia, bukan MCP.

Lindungi API key

Jangan commit API key asli ke repositori Git atau menampilkan key lengkap dalam tangkapan layar, log, atau tiket dukungan.

Untuk penyedia yang dikonfigurasi secara manual, utamakan variabel lingkungan:

[model_providers.example]
env_key = "EXAMPLE_API_KEY"

CC Switch menyimpan konfigurasi penyedia secara lokal dan mengubah konfigurasi Codex lokal saat Anda beralih penyedia. CC Switch adalah alat sumber terbuka pihak ketiga, bukan produk OpenAI. Instal hanya dari situs web resmi atau repositori GitHub CC Switch, serta lindungi basis data, konfigurasi, dan cadangan lokalnya.

1. Hubungkan model pihak ketiga dengan CC Switch

CC Switch merupakan opsi yang lebih mudah untuk sebagian besar model pihak ketiga. Alat ini mengelola penyedia, API key, daftar model, dan perutean lokal, serta dapat menerjemahkan protokol upstream yang tidak kompatibel.

1.1 Masalah yang diselesaikan CC Switch

Klien Codex modern mengirim permintaan Responses API, sedangkan banyak layanan pihak ketiga menyediakan salah satu dari hal berikut:

• OpenAI Chat Completions;
• Anthropic Messages;
• ID model yang secara default tidak tercantum di Codex;
• parameter penalaran atau format peristiwa streaming khusus vendor.

CC Switch dapat menerjemahkan jalur permintaan sebagai berikut:

Codex
  │  Responses API
  ▼
CC Switch local route
  │  Converts the protocol and model name when required
  ▼
Third-party model API
  │
  ▼
CC Switch converts JSON, SSE, reasoning data, and tool calls back to Responses
  │
  ▼
Codex

Penyedia yang secara native mendukung Responses tidak memerlukan konversi protokol Chat. Penyedia Chat Completions atau Anthropic Messages memerlukan perutean lokal.

1.2 Instal CC Switch

Gunakan hanya saluran distribusi resmi:

• Situs web resmi CC Switch
• Repositori GitHub CC Switch
• Rilis CC Switch

Di macOS, Homebrew direkomendasikan:

brew install --cask cc-switch

Untuk memperbarui:

brew upgrade --cask cc-switch

Di Windows, unduh penginstal .msi atau arsip portabel dari Releases.

Di Linux, unduh paket .deb, .rpm, atau AppImage dari Releases. Label mungkin sedikit berubah antarversi, jadi gunakan rilis stabil terbaru dan jadikan opsi yang ditampilkan dalam aplikasi sebagai acuan utama.

1.3 Prasyarat

Siapkan hal-hal berikut:

1. Codex telah diinstal dan dijalankan setidaknya sekali;
2. CC Switch telah diinstal dan dapat dimulai dengan benar;
3. Anda memiliki API key untuk layanan model tujuan;
4. Anda telah mengonfirmasi Base URL, ID model, dan protokol upstream dalam dokumentasi penyedia;
5. jika memerlukan fitur akun Codex resmi, selesaikan satu kali login resmi terlebih dahulu.

Periksa status login Codex saat ini:

codex login status

Masuk bila diperlukan:

codex login

Login dengan kode perangkat juga tersedia:

codex login --device-auth

1.4 Opsional: pertahankan login resmi saat menggunakan penyedia pihak ketiga

Hal ini terutama berguna jika Anda ingin mempertahankan fitur desktop, plugin resmi, atau fitur kendali jarak jauh sementara permintaan model dikirim ke penyedia pihak ketiga. Pengguna yang hanya menggunakan CLI dan tidak bergantung pada fitur akun resmi dapat melewatinya.

Urutan yang disarankan:

1. pilih OpenAI Official di panel Codex CC Switch;
2. jalankan Codex dan masuk dengan akun resmi;
3. buka Settings → General → Codex App Enhancements di CC Switch;
4. aktifkan Keep official login when switching third-party providers;
5. tambahkan atau beralihlah ke penyedia pihak ketiga.

Dengan opsi ini diaktifkan, CC Switch berupaya mempertahankan:

• ~/.codex/auth.json untuk status login resmi;
• ~/.codex/config.toml untuk penyedia pihak ketiga yang aktif, model, endpoint, dan konfigurasi autentikasi.

auth.json berisi data login sensitif. Jangan membagikannya atau melakukan commit ke kontrol versi.

1.5 Tambahkan penyedia pihak ketiga

Buka CC Switch, beralihlah ke panel tingkat atas Codex, lalu klik tombol tambah di sudut kanan atas.

Utamakan preset bawaan

Jika tersedia preset, gunakan preset tersebut dan masukkan hanya API key serta nilai khusus akun yang diperlukan. Preset biasanya mengonfigurasi:

• Base URL;
• model default;
• protokol upstream;
• apakah perutean lokal diperlukan;
• pemetaan model;
• parameter penalaran yang dipilih.

Daftar preset berubah seiring perkembangan CC Switch. Dokumentasi jangka panjang sebaiknya tidak menetapkan ID model vendor saat ini secara permanen; gunakan daftar dalam aplikasi dan dokumentasi resmi penyedia.

Buat penyedia kustom

Jika tidak tersedia preset, pilih konfigurasi kustom dan berikan:

Pengaturan terpenting adalah Upstream Format:

Jangan memilih Responses hanya karena penyedia mengiklankan “kompatibilitas OpenAI”. Banyak API yang kompatibel dengan OpenAI hanya mengimplementasikan Chat Completions.

1.6 Masukkan Base URL dengan benar

Secara default, CC Switch menambahkan jalur API yang sesuai ke Base URL. Dalam kebanyakan kasus, masukkan root API dari dokumentasi penyedia, alih-alih mengulangi sendiri /chat/completions atau /responses.

Misalnya, jika penyedia mendokumentasikan:

POST https://api.example.com/v1/chat/completions

Anda mungkin perlu memasukkan:

https://api.example.com

atau, bergantung pada preset dan dokumentasi penyedia:

https://api.example.com/v1

Apakah /v1 perlu disertakan dalam Base URL bergantung pada penyedia dan preset CC Switch. Gunakan pemeriksaan konektivitas bawaan atau log perutean untuk mengonfirmasi URL permintaan akhir.

Gunakan Full URL Mode hanya jika penyedia memerlukan jalur endpoint lengkap yang tidak standar.

1.7 Konfigurasikan Needs Local Routing dan pemetaan model

Aktifkan Needs Local Routing jika penyedia menggunakan Chat Completions, Anthropic Messages, atau nama model yang secara default tidak dikenali Codex.

Preset yang berorientasi Chat biasanya mengaktifkannya secara otomatis. Verifikasi opsi tersebut untuk penyedia kustom.

Setelah diaktifkan, tabel pemetaan model akan tersedia. Bidang yang umum meliputi:

Hal-hal penting:

• gunakan ID model yang tepat dari dokumentasi penyedia;
• jangan menebak ukuran jendela konteks;
• mulai ulang Codex setelah mengubah daftar model;
• CC Switch menghasilkan katalog model Codex dari pemetaan ini;
• jika relay mengubah domain atau nama model, deteksi otomatis kemampuan penalaran mungkin keliru dan perlu ditinjau dalam pengaturan lanjutan.

1.8 Aktifkan perutean lokal dan pengambilalihan Codex

Di CC Switch, buka:

Settings → Routing → Local Routing

Kemudian:

1. aktifkan sakelar utama perutean lokal;
2. aktifkan Codex di bawah Routing Enabled;
3. konfirmasikan pengaturan Needs Local Routing penyedia;
4. biarkan CC Switch tetap berjalan selama penyedia digunakan.

Rute lokal default biasanya:

http://127.0.0.1:15721

Setelah pengambilalihan, konfigurasi Codex aktif mengarah ke rute lokal CC Switch. CC Switch kemudian meneruskan permintaan ke penyedia upstream yang saat ini dipilih.

Untuk upstream Chat Completions, alurnya biasanya:

Codex POST /responses
  → CC Switch converts it to POST /chat/completions
  → the provider returns JSON or SSE
  → CC Switch rebuilds Responses JSON or SSE
  → Codex continues the tool-call loop

1.9 Beralih penyedia dan mulai ulang Codex

Kembali ke daftar penyedia Codex di CC Switch, pilih penyedia yang telah dikonfigurasi, lalu aktifkan.

Mulai ulang Codex sepenuhnya setelah beralih karena:

• Codex membaca config.toml saat dimulai;
• menu /model biasanya memuat katalog saat dimulai;
• ekstensi IDE atau klien desktop mungkin menyimpan cache penyedia sebelumnya;
• sesi yang ada mungkin mempertahankan metadata model lama.

Pengguna CLI cukup memulai proses baru:

codex

1.10 Verifikasi integrasi

Di dalam Codex, jalankan:

/status

Tinjau model aktif, penyedia, izin, dan informasi konteks.

Buka pemilih model:

/model

Periksa lapisan konfigurasi:

/debug-config

Periksa juga:

• penyedia Codex yang aktif di CC Switch;
• log atau statistik perutean lokal CC Switch;
• riwayat permintaan dan perubahan saldo di dasbor penyedia;
• apakah ~/.codex/config.toml saat ini mengarah ke rute lokal.

Jangan memvalidasi penyiapan hanya dengan sapaan sederhana. Jalankan setidaknya satu pengujian kemampuan agen:

1. minta Codex mencantumkan file dalam proyek saat ini;
2. minta Codex membaca dan merangkum satu file;
3. minta Codex mengubah sebuah file kecil;
4. minta Codex menjalankan pengujian;
5. biarkan satu kegagalan sederhana tetap ada dan verifikasi bahwa Codex dapat menggunakan hasil pengujian untuk melanjutkan perbaikan proyek.

Keberhasilan menghasilkan teks tidak membuktikan bahwa pemanggilan alat dan alur kerja agen multigilir kompatibel.

1.11 Beralih kembali ke penyedia resmi OpenAI

Pilih OpenAI Official di CC Switch dan mulai ulang Codex.

Periksa status login:

codex login status

Jika perlu, masuk kembali:

codex login

Jika memerlukan status login resmi sekaligus permintaan model pihak ketiga, pastikan Keep official login when switching third-party providers tetap diaktifkan.

1.12 Batasan dan pertimbangan operasional

CC Switch menyederhanakan konfigurasi, tetapi tidak menghilangkan batasan upstream:

• CC Switch harus tetap berjalan untuk konversi Chat atau Messages;
• konversi protokol tidak dapat mereproduksi setiap fitur khusus vendor;
• beberapa model dapat melakukan chat, tetapi tidak dapat menjalankan pemanggilan alat secara andal;
• Web Search, input gambar, WebSockets, atau penyimpanan respons mungkin tidak tersedia;
• batas laju, penagihan, dan kebijakan retensi data penyedia upstream tetap berlaku;
• relay API dapat mengubah permintaan dan respons lagi;
• konfigurasi harus diuji ulang setelah peningkatan CC Switch, Codex, atau penyedia.

CC Switch paling sesuai untuk pengembangan desktop lokal. Untuk server, CI, atau otomatisasi headless yang berjalan lama, utamakan penyedia Responses native atau gateway yang dihosting sendiri.

2. Hubungkan API yang dihosting dengan penyedia model kustom

Konfigurasikan penyedia secara langsung hanya jika layanan secara native mendukung Responses API yang diperlukan Codex.

Jika layanan hanya menyediakan /chat/completions atau Anthropic Messages, gunakan alur kerja CC Switch di bagian 1. Jangan mencoba mengatasi ketidakcocokan tersebut dengan wire_api = "chat".

2.1 Kemampuan API yang diperlukan

Penyedia yang sesuai untuk integrasi Codex langsung setidaknya harus mendukung:

• POST /responses;
• objek JSON Responses;
• peristiwa streaming SSE Responses;
• pemanggilan fungsi atau alat;
• parameter alat JSON Schema;
• kelanjutan setelah hasil alat dikembalikan;
• permintaan multigilir atau padanan previous_response_id;
• jendela konteks yang memadai dan permintaan jangka panjang yang stabil;
• autentikasi, batas laju, dan respons kesalahan yang terdokumentasi.

Pembuatan teks biasa saja tidak cukup untuk agen Codex yang andal.

2.2 Konfigurasi generik

Edit konfigurasi tingkat pengguna:

~/.codex/config.toml

Tambahkan:

model_provider = "third_party"
model = "provider-model-id"

# Set this only when the model explicitly supports it.
model_reasoning_effort = "high"

# Optional: use the real value published by the provider when no catalog exists.
# model_context_window = 131072

[model_providers.third_party]
name = "My Responses-compatible Provider"
base_url = "https://provider.example.com/v1"
env_key = "THIRD_PARTY_API_KEY"
wire_api = "responses"
request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 300000

Jangan gunakan ID penyedia yang dicadangkan berikut:

openai
ollama
lmstudio

Gunakan ID kustom seperti third_party atau company_gateway sebagai gantinya.

2.3 Bidang konfigurasi

Apakah base_url menyertakan /v1 bergantung pada dokumentasi penyedia. Endpoint akhir yang umum adalah:

https://provider.example.com/v1/responses

2.4 Tetapkan API key

Sesi bash / zsh saat ini:

export THIRD_PARTY_API_KEY="your API key"

fish:

set -gx THIRD_PARTY_API_KEY "your API key"

Sesi PowerShell saat ini:

$env:THIRD_PARTY_API_KEY = "your API key"

Simpan secara permanen untuk pengguna Windows saat ini:

[Environment]::SetEnvironmentVariable(
  "THIRD_PARTY_API_KEY",
  "your API key",
  [EnvironmentVariableTarget]::User
)

Mulai ulang terminal, IDE, atau klien desktop setelah menetapkan variabel lingkungan permanen.

2.5 Uji endpoint Responses terlebih dahulu

Sebelum menjalankan Codex, panggil penyedia secara langsung:

export PROVIDER_BASE_URL="https://provider.example.com/v1"

curl "$PROVIDER_BASE_URL/responses" \
  -H "Authorization: Bearer $THIRD_PARTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "provider-model-id",
    "input": "Reply with exactly: PROVIDER_OK",
    "stream": false
  }'

Verifikasi bahwa:

• endpoint tidak mengembalikan 404;
• respons memiliki struktur bergaya Responses, bukan hanya array choices Chat Completions;
• ID model diterima;
• autentikasi sudah benar;
• kesalahan berisi informasi diagnostik yang berguna.

Kemudian uji secara terpisah:

• stream: true;
• pemanggilan alat;
• kelanjutan hasil alat;
• beberapa giliran;
• konteks panjang;
• konkurensi dan batas laju.

2.6 Validasi konfigurasi Codex

Mulai dalam mode ketat:

codex --strict-config

--strict-config memperlakukan kunci konfigurasi yang tidak dikenal sebagai kesalahan, sehingga membantu mengidentifikasi bidang yang disalin dari panduan lama.

Di dalam Codex, jalankan:

/status

Untuk memeriksa sumber konfigurasi, jalankan:

/debug-config

Timpa penyedia dan model untuk satu kali proses tanpa mengubah konfigurasi default:

codex \
  -c 'model_provider="third_party"' \
  -m 'provider-model-id'

2.7 Katalog model dan Unknown model

Katalog model Codex dapat mendeskripsikan:

• ukuran jendela konteks;
• tingkat penalaran yang didukung;
• modalitas input;
• kemampuan pemanggilan alat;
• perilaku pemotongan;
• versi minimum klien.

Jika penyedia menyediakan katalog model yang kompatibel dengan Codex, simpan secara lokal dan konfigurasikan:

model_catalog_json = "~/.codex/provider-models.json"

Jika tidak ada katalog, tetapkan jendela konteks hanya setelah mengonfirmasi nilai sebenarnya:

model_context_window = 131072

Jangan menyalin metadata dari model yang tidak terkait hanya untuk menghilangkan peringatan. Metadata kemampuan atau konteks yang salah dapat menyebabkan pemotongan prematur, kesalahan batas upstream, atau kerusakan pemanggilan alat.

2.8 Daftar periksa kompatibilitas lengkap

Sebelum penggunaan produksi, uji:

• teks /responses tanpa streaming;
• streaming SSE Responses;
• satu pemanggilan alat;
• beberapa pemanggilan alat secara berurutan atau paralel;
• parameter JSON Schema;
• kelanjutan hasil alat;
• konteks panjang dan pemadatan otomatis;
• parameter penalaran;
• gambar atau modalitas input lainnya;
• batas laju dan perilaku percobaan ulang;
• apakah proxy menahan SSE dalam buffer;
• apakah penyedia menghapus atau menulis ulang bidang alat;
• kebijakan retensi data, pencatatan, dan privasi.

2.9 Lokasi konfigurasi penyedia

Tempatkan model_provider, model_providers, dan autentikasi penyedia dalam file tingkat pengguna:

~/.codex/config.toml

Jangan menempatkannya dalam file tingkat repositori:

<project>/.codex/config.toml

Codex mengabaikan bidang lokal proyek yang dapat mengalihkan permintaan model atau mengubah autentikasi penyedia. Hal ini mencegah repositori kloning yang tidak tepercaya meneruskan permintaan secara diam-diam ke server lain.

3. Kelola beberapa penyedia pihak ketiga dengan profil

Pengguna CC Switch biasanya dapat beralih penyedia dalam aplikasi dan tidak memerlukan profil Codex.

Profil berguna jika Anda mengonfigurasi beberapa penyedia Responses native secara manual. Simpan definisi penyedia dalam konfigurasi dasar dan gunakan file profil terpisah untuk memilih penyedia dan model.

~/.codex/config.toml dasar:

[model_providers.provider_a]
name = "Provider A"
base_url = "https://api.provider-a.example/v1"
env_key = "PROVIDER_A_API_KEY"
wire_api = "responses"

[model_providers.provider_b]
name = "Provider B"
base_url = "https://api.provider-b.example/v1"
env_key = "PROVIDER_B_API_KEY"
wire_api = "responses"

Buat:

~/.codex/fast.config.toml

model_provider = "provider_a"
model = "provider-a-fast-model"
model_reasoning_effort = "medium"

Buat profil lain:

~/.codex/quality.config.toml

model_provider = "provider_b"
model = "provider-b-quality-model"
model_reasoning_effort = "high"

Pilih profil saat menjalankan Codex:

codex --profile fast
codex --profile quality

Mode noninteraktif:

codex exec --profile quality "Review the current changes"

File profil berada di:

$CODEX_HOME/<profile-name>.config.toml

CODEX_HOME default adalah ~/.codex.

Versi Codex terbaru menggunakan file profil terpisah dan tidak lagi membaca tabel [profiles.<name>] lama. Migrasikan setiap profil lama ke file <name>.config.toml tersendiri.

4. Header kustom dan autentikasi lanjutan

4.1 Token bearer standar

Sebagian besar layanan pihak ketiga berfungsi dengan:

[model_providers.third_party]
env_key = "THIRD_PARTY_API_KEY"

Codex membaca key dari lingkungan dan menerapkan autentikasi bearer penyedia.

4.2 Header API key kustom

Beberapa layanan memerlukan:

x-api-key: <key>

Gunakan env_http_headers:

model_provider = "custom_header_provider"
model = "provider-model-id"

[model_providers.custom_header_provider]
name = "Custom Header Provider"
base_url = "https://provider.example.com/v1"
wire_api = "responses"
env_http_headers = { "x-api-key" = "VENDOR_API_KEY" }

Nilai VENDOR_API_KEY adalah nama variabel lingkungan, bukan rahasia itu sendiri.

export VENDOR_API_KEY="your API key"

4.3 Header statis dan parameter kueri

Tambahkan header statis yang tidak sensitif:

http_headers = { "X-Client-Name" = "codex", "X-Environment" = "development" }

Tambahkan parameter kueri:

query_params = { "api-version" = "2026-08-01" }

Jangan menempatkan rahasia asli di http_headers.

4.4 Autentikasi berbasis perintah

Lingkungan perusahaan dapat memperoleh token berumur pendek dari keychain, pembantu kredensial cloud, atau perintah internal:

[model_providers.corporate]
name = "Corporate Gateway"
base_url = "https://gateway.example.com/v1"
wire_api = "responses"

[model_providers.corporate.auth]
command = "/usr/local/bin/fetch-codex-token"
args = ["--audience", "codex"]
timeout_ms = 5000
refresh_interval_ms = 300000

Perintah tersebut hanya boleh mencetak token ke output standar.

Jangan menggabungkan metode autentikasi berikut:

• [model_providers.<id>.auth];
• env_key;
• experimental_bearer_token;
• requires_openai_auth.

4.5 Gunakan kembali autentikasi OpenAI melalui proxy

Tetapkan hal berikut hanya jika proxy masih mengakses model OpenAI dan Codex harus menggunakan autentikasi resmi OpenAI:

requires_openai_auth = true

Ini bukan pengaturan yang tepat untuk API key model pihak ketiga biasa. Jika diaktifkan, Codex mengabaikan env_key penyedia.

5. Pemecahan masalah

5.1 CC Switch mengganti penyedia, tetapi Codex masih menggunakan model lama

Periksa setiap hal berikut:

1. penyedia Codex yang diinginkan telah diaktifkan di CC Switch;
2. sakelar utama perutean lokal aktif;
3. Codex diaktifkan di bawah Routing Enabled;
4. penyedia Chat atau Messages telah mengaktifkan Needs Local Routing;
5. CC Switch masih berjalan;
6. Codex, IDE, atau klien desktop telah dimulai ulang sepenuhnya;
7. /debug-config menampilkan sumber konfigurasi yang diharapkan.

Mulai ulang Codex setelah mengubah pemetaan model agar menu /model dapat memuat ulang katalognya.

5.2 404, 400, atau endpoint /responses tidak ditemukan

Penyebab umum meliputi:

• memperlakukan penyedia Chat Completions sebagai penyedia Responses native;
• menambahkan atau menghapus /v1 secara keliru;
• menambahkan /chat/completions dua kali;
• tidak mengaktifkan Full URL Mode untuk endpoint yang tidak standar;
• perutean lokal tidak mengambil alih Codex;
• implementasi Responses yang tidak lengkap di gateway pihak ketiga.

Pengguna CC Switch harus memeriksa Upstream Format dan log perutean. Pengguna penyedia langsung harus memanggil <base_url>/responses dengan curl.

5.3 401 Unauthorized atau 403 Forbidden

Periksa:

• apakah API key valid;
• apakah key tersebut terkait dengan wilayah, proyek, atau paket yang benar;
• apakah akun memiliki saldo dan izin yang memadai;
• apakah layanan mengharapkan token bearer atau x-api-key;
• apakah nama variabel lingkungan sama persis dengan env_key;
• apakah CC Switch menyimpan key yang benar;
• apakah proxy menghapus header autentikasi.

Jangan mencetak key lengkap ke log bersama.

bash / zsh:

printenv THIRD_PARTY_API_KEY

PowerShell:

$env:THIRD_PARTY_API_KEY

5.4 Model tidak tercantum di /model

Periksa:

• apakah Model Mapping CC Switch berisi ID model upstream yang tepat;
• apakah penyedia telah disimpan dan diaktifkan;
• apakah Codex telah dimulai ulang;
• apakah penyedia manual memiliki model_catalog_json yang valid;
• apakah JSON katalog valid;
• apakah penyedia mengganti nama atau menghentikan model.

5.5 Teks berfungsi, tetapi Codex tidak dapat membaca file, mengedit kode, atau menjalankan perintah

Kemungkinan penyebab:

• kemampuan model dalam pemanggilan alat lemah;
• upstream tidak mengimplementasikan pemanggilan fungsi;
• relay menghapus ID pemanggilan alat;
• fragmen pemanggilan alat streaming tidak dirangkai kembali dengan benar;
• JSON Schema ditulis ulang;
• hasil alat tidak dikembalikan pada giliran berikutnya;
• konteks model terlalu pendek;
• katalog model mengiklankan kemampuan secara keliru.

Uji alur nyata “baca → edit → jalankan pengujian → periksa kegagalan → perbaiki”, bukan prompt chat sederhana.

5.6 Streaming sering terputus

Pengguna CC Switch harus memeriksa log perutean lokal dan respons upstream terlebih dahulu. Penyebab umum meliputi:

• antrean upstream atau waktu penalaran yang panjang;
• gateway yang tidak segera memancarkan SSE;
• buffering oleh CDN, reverse proxy, atau jaringan perusahaan;
• peristiwa upstream yang tidak standar;
• masalah kompatibilitas pada versi CC Switch atau penyedia tertentu.

Untuk penyedia langsung, Anda dapat meningkatkan:

request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 600000

Batas waktu yang lebih panjang dapat mengurangi masalah jaringan atau inferensi lambat, tetapi tidak dapat memperbaiki implementasi protokol yang keliru.

5.7 wire_api = "chat" mencegah Codex dimulai

Nilai ini muncul dalam panduan lama. Konfigurasi Codex saat ini hanya mendukung:

wire_api = "responses"

Gunakan CC Switch jika upstream hanya menyediakan Chat Completions.

Periksa bidang usang lainnya dengan:

codex --strict-config

5.8 Mengedit konfigurasi proyek tidak mengubah penyedia

Pengaturan penyedia berada di:

~/.codex/config.toml

.codex/config.toml tingkat proyek tidak dapat menimpa bidang yang mengalihkan permintaan atau mengubah autentikasi penyedia, termasuk model_provider dan model_providers.

5.9 Terminal berfungsi, tetapi ekstensi IDE tidak dapat menemukan API key

Aplikasi GUI sering kali tidak mewarisi variabel yang diekspor sementara dalam terminal yang sudah berjalan.

Pilihannya meliputi:

• jalankan IDE dari terminal tempat variabel ditetapkan;
• simpan variabel secara permanen dalam lingkungan pengguna sistem operasi;
• tutup IDE sepenuhnya lalu buka kembali;
• gunakan CC Switch untuk mengelola konfigurasi penyedia lokal.

5.10 Login resmi atau fitur resmi berhenti berfungsi setelah beralih

Periksa:

• apakah OpenAI Official telah dipilih kembali;
• apakah Keep official login when switching third-party providers diaktifkan;
• apakah alur kerja lama menimpa ~/.codex/auth.json;
• apakah codex login status berhasil.

Jika perlu, masuk kembali:

codex login

Jangan membagikan atau mengedit secara manual file auth.json yang berisi token akses.

5.11 Web Search, gambar, atau kemampuan lanjutan lainnya tidak berfungsi

Penyedia yang mendukung teks dan pemanggilan alat belum tentu mengimplementasikan setiap kemampuan Codex.

Secara default, penyedia kustom tidak mengiklankan Web Search mandiri. Tetapkan hal berikut hanya jika penyedia, model, dan endpoint benar-benar mendukungnya:

supports_standalone_web_search = true

Mengaktifkannya secara keliru hanya menyebabkan Codex mengirim permintaan yang tidak dapat diproses upstream. Validasi input gambar, WebSockets, penyimpanan respons, dan fitur lanjutan lainnya secara terpisah.

6. Pilih jalur integrasi

Validasi setiap integrasi pada tiga tingkat:

1. Konektivitas: integrasi menghasilkan teks secara andal;
2. Penggunaan alat: integrasi dapat membaca file, menjalankan perintah, dan melanjutkan dari hasil alat;
3. Penyelesaian tugas: integrasi dapat menyelesaikan alur edit, pengujian, dan perbaikan.

Tinjau juga:

• harga pihak ketiga;
• batas laju;
• apakah kode sumber dan prompt dicatat;
• wilayah penyimpanan data;
• persyaratan kepatuhan tim atau perusahaan;
• apakah peningkatan model memerlukan pengujian regresi.

Jika menggunakan API key pihak ketiga, penggunaan ditagihkan oleh penyedia atau relay tersebut. Penggunaan itu tidak secara otomatis memakai atau berbagi kuota yang disertakan dalam ChatGPT Plus, Pro, atau langganan Codex.

Referensi

• Dasar-Dasar Konfigurasi Codex
• Konfigurasi Lanjutan Codex
• Referensi Konfigurasi Codex
• Autentikasi Codex
• Perintah Pengembang Codex
• Model Codex
• GitHub CC Switch
• Panduan Pengguna CC Switch
• CC Switch: Tambahkan Penyedia
• CC Switch: Pertahankan Login Resmi Codex