Mengonfigurasi Codex melalui penyedia terpadu CC Switch
Tentang dokumen ini
Dokumen ini menjelaskan cara menggunakan fitur penyedia terpadu (Universal Provider) CC Switch untuk menghubungkan alat baris perintah OpenAI Codex ke API gateway yang ditentukan, lalu membuat konfigurasi tersebut berlaku.
Versi yang berlaku: CC Switch v3.16.x ke atas.
Sumber informasi: panduan pengguna dan kode sumber repositori resmi CC Switch. Perangkat lunak ini berkembang cepat; jika antarmuka produk tidak sama dengan uraian dalam dokumen ini, tampilan aktual di dalam aplikasi yang berlaku.
Penjelasan istilah
| Istilah | Keterangan |
|---|---|
| Codex | Asisten pemrograman AI baris perintah dari OpenAI. Setelah diinstal, jalankan perintah codex di terminal untuk memulainya. |
| CC Switch | Alat manajemen konfigurasi desktop lintas platform untuk mengelola endpoint layanan dan kredensial alat seperti Codex, Claude Code, dan Gemini CLI. CC Switch sendiri tidak menyediakan kemampuan AI; ia hanya membuat dan mengganti berkas konfigurasi. |
| Penyedia (Provider) | Pihak yang menyediakan kemampuan inferensi model. Bisa berupa layanan resmi vendor model, maupun API gateway yang dibangun sendiri atau dibeli. |
| API Key | String kunci untuk autentikasi, biasanya diawali dengan sk-. |
| Penyedia terpadu (Universal Provider) | Sebuah fitur CC Switch. Satu konfigurasi dapat disinkronkan sekaligus ke tiga alat: Claude Code, Codex, dan Gemini CLI. Cocok untuk gateway yang mendukung beberapa protokol API sekaligus (misalnya NewAPI). |
| Penyedia khusus aplikasi | Konfigurasi penyedia yang hanya berlaku untuk satu alat, sebagai lawan dari penyedia terpadu. |
Sebelum memulai
Persyaratan sistem
| Sistem operasi | Versi minimum | Arsitektur |
|---|---|---|
| Windows | Windows 10 | x64 |
| macOS | macOS 12 (Monterey) | Intel (x64) / Apple Silicon (arm64) |
| Linux | Ubuntu 22.04 / Debian 11 / Fedora 34 dan versi yang setara | x64 / ARM64 |
Selain itu, Anda juga memerlukan Node.js 18 atau versi yang lebih tinggi. Langkah instalasi ada di "Tugas 1".
Informasi yang perlu diperoleh terlebih dahulu
Sebelum mulai mengonfigurasi, dapatkan empat informasi berikut dari penyedia layanan API. Jika ada satu yang kurang, konfigurasi tidak dapat diselesaikan.
| Item | Keterangan | Contoh |
|---|---|---|
| Alamat API (Base URL) | Alamat layanan gateway | https://seedrouter.net |
| API Key | Kunci autentikasi | sk-xxxxxxxxxxxx |
| Nama model | Pengenal model yang digunakan di sisi Codex | gpt-5.6-sol |
| Status dukungan protokol | Apakah gateway mendukung protokol OpenAI Responses | Didukung / Tidak didukung |
Poin penting: Item keempat menentukan apakah dokumen ini berlaku. Dalam konfigurasi yang dihasilkan penyedia terpadu untuk Codex, protokol komunikasi ditetapkan sebagai wire_api = "responses" dan tidak dapat diubah. Jika gateway tidak mendukung protokol Responses dan hanya mendukung protokol Chat Completions, Anda tidak dapat menggunakan penyedia terpadu. Gunakan solusi F di bagian "Pemecahan masalah".
Membuka terminal
Di banyak bagian, dokumen ini mengharuskan Anda menjalankan perintah di terminal. Cara membuka terminal adalah sebagai berikut:
- Windows: Tekan
Win + R, ketikpowershell, lalu tekan Enter. - macOS: Tekan
Command + Spasi, ketikterminal, lalu tekan Enter. - Linux: Gunakan aplikasi terminal bawaan distribusi.
Tugas 1: Menginstal Node.js
Tentang tugas ini
Codex didistribusikan melalui npm, pengelola paket Node.js. Meskipun Anda memakai instalasi satu klik CC Switch, lingkungan runtime Node.js tetap harus tersedia terlebih dahulu.
Prosedur
Kunjungi situs resmi Node.js.
Unduh paket instalasi yang bertanda LTS (dukungan jangka panjang). Jangan unduh versi Current.
Jalankan penginstal, selesaikan instalasi dengan opsi default, tanpa mengubah item konfigurasi apa pun.
Pengguna macOS yang sudah memasang Homebrew juga dapat menjalankan
brew install nodedi terminal.Tutup semua jendela terminal yang sedang terbuka, lalu buka kembali satu jendela terminal baru.
Jalankan perintah berikut secara berurutan untuk memverifikasi instalasi:
node --version npm --version
Hasil
Kedua perintah menampilkan nomor versi (misalnya v22.14.0 dan 10.9.2), dan versi Node.js tidak lebih rendah dari v18. Itu menandakan instalasi berhasil.
Catatan: Jika muncul pesan "tidak dikenali sebagai perintah internal atau eksternal" atau "command not found", biasanya karena jendela terminal belum dibuka kembali. Perintah yang baru diinstal hanya berlaku pada sesi terminal yang baru dibuka.
Tugas 2: Menginstal CC Switch
Tentang tugas ini
CC Switch adalah perangkat lunak sumber terbuka gratis, dan hanya didistribusikan melalui dua saluran berikut:
- Situs resmi: ccswitch.io
- Halaman rilis GitHub: farion1231/cc-switch Releases
Peringatan: Situs atau klien "CC Switch" mana pun yang meminta pembayaran, pengisian saldo, atau kredensial login akun bukan saluran resmi. Jangan unduh dan jangan gunakan.
Prosedur
Windows
Buka halaman rilis GitHub, lalu temukan
CC-Switch-v3.16.x-Windows.msidi area Assets pada entri versi terbaru.Unduh dan klik dua kali untuk menjalankan penginstal, lalu selesaikan instalasi sesuai petunjuk.
Jika setelah klik dua kali tidak ada reaksi sama sekali, file dikunci oleh kebijakan keamanan sistem. Klik kanan file tersebut, pilih Properti, pada bagian bawah tab Umum di area Keamanan centang Buka blokir, klik OK, lalu jalankan kembali.
Jika Anda tidak ingin menginstalnya ke sistem, Anda juga dapat mengunduh versi tanpa instalasi
CC-Switch-v3.16.x-Windows-Portable.zip, mengekstraknya, lalu langsung menjalankanCC-Switch.exe.
macOS
Gunakan salah satu cara berikut:
Cara pertama (disarankan jika Homebrew sudah terpasang): jalankan di terminal
brew install --cask cc-switchCara kedua: Unduh
CC-Switch-v3.16.x-macOS.dmg, klik dua kali untuk membukanya, lalu seret ikon CC Switch ke folder "Aplikasi".Catatan: Versi macOS telah melewati code signing dan notarization Apple, sehingga dapat langsung diinstal dan dibuka. Peringatan "cannot verify the developer" tidak akan muncul, dan tidak perlu tindakan tambahan untuk melepas karantina.
Linux
Pilih sesuai distribusi:
Debian / Ubuntu: Setelah mengunduh paket
.deb, jalankansudo dpkg -i CC-Switch-v3.16.x-Linux-*.deb sudo apt-get install -fArch Linux:
paru -S cc-switch-binDistribusi lain: Unduh
.AppImage, jalankanchmod +xuntuk menambahkan izin eksekusi, lalu jalankan langsung.
Hasil
Setelah CC Switch dijalankan, jendela utama tampil normal, dan ikon CC Switch muncul di area system tray (di Windows berada di pojok kanan bawah, di macOS berada di sisi kanan menu bar). Ini menandakan instalasi berhasil.
Saat pertama kali dijalankan, jika muncul permintaan untuk mengimpor konfigurasi alat CLI yang sudah ada, sebaiknya Anda memilih impor. Tindakan ini menyimpan konfigurasi yang sudah ada sebagai satu provider default, dan tidak menyebabkan konfigurasi hilang.
Tugas 3: Menginstal Codex
Tentang tugas ini
Anda dapat menginstal melalui antarmuka grafis CC Switch, atau melalui baris perintah. Pengguna pertama kali disarankan memakai Cara A.
Prosedur
Cara A: Menginstal melalui CC Switch (disarankan)
Jalankan CC Switch.
Masuk ke Settings > About.
Di area Local Environment Check, lihat status pada baris Codex.
Jika status yang ditampilkan adalah belum terdeteksi, klik tombol Install di sisi kanan baris tersebut.
Instalasi berjalan senyap di latar belakang, progres ditampilkan pada tombol, dan nomor versi diperbarui secara otomatis setelah selesai.
Catatan: Peningkatan versi berikutnya juga dilakukan di antarmuka ini. Saat versi baru terdeteksi, Anda dapat meningkatkan satu per satu, atau mengklik Upgrade All untuk memproses sekaligus.
Cara B: Menginstal melalui baris perintah
Buka terminal.
Jalankan perintah berikut:
npm install -g @openai/codexJika unduhan terlalu lambat, Anda dapat beralih ke mirror:
npm install -g @openai/codex --registry=https://registry.npmmirror.comJika Anda ingin memakai mirror dalam jangka panjang, jalankan perintah berikut satu kali terlebih dahulu untuk pengaturan global:
npm config set registry https://registry.npmmirror.com
Hasil
Setelah menutup dan membuka kembali terminal, jalankan perintah berikut:
codex --versionJika nomor versi tercetak, instalasi berhasil.
Catatan: Pada tahap ini konfigurasi provider belum selesai. Menjalankan codex secara langsung akan menghasilkan error karena tidak ada kredensial yang valid. Ini adalah perilaku yang diharapkan. Konfigurasi diselesaikan di Tugas 4.
Tugas 4: Membuat Unified Provider
Tentang tugas ini
Tugas ini membuat satu konfigurasi Unified Provider di CC Switch, lalu menyinkronkannya ke daftar provider Codex.
Prosedur
Jalankan CC Switch.
Pada pengalih aplikasi di bagian atas, beralih ke Codex.
Beralih ke panel Claude atau Gemini juga dapat membuka entri Unified Provider. Ketiganya memakai konfigurasi yang sama.
Klik tombol + di pojok kanan atas untuk membuka panel penambahan provider.
Di bagian atas panel, pilih tab Unified Provider.
Batasan: Panel OpenCode, OpenClaw, Hermes, dan Claude Desktop tidak mendukung Unified Provider, sehingga tab ini tidak ditampilkan pada panel tersebut. Jika Anda tidak melihat tab ini, beralihlah terlebih dahulu ke panel Claude, Codex, atau Gemini.
Klik Add Unified Provider.
Isi field formulir sesuai tabel berikut:
Field Petunjuk pengisian Select Preset Type Jika gateway-nya NewAPI, pilih NewAPI. Untuk kasus lain atau jika tidak yakin, pilih Custom Gateway. Field keduanya sepenuhnya sama; hanya nilai default yang berbeda. Name Nama identifikasi yang Anda tentukan sendiri, misalnya NewAPI Gateway. Nama ini akan ditampilkan pada kartu provider Codex.API Address Isi Base URL yang sudah diperoleh sebelumnya. Aturan pengisian lihat "Aturan pemrosesan alamat API" di bawah. API Key Isi kunci yang sudah diperoleh sebelumnya. Anda dapat mengklik ikon mata di sisi kanan untuk beralih ke tampilan teks polos. Official Website Opsional. Setelah diisi, Anda dapat langsung berpindah dari kartu provider. Notes Opsional. Disarankan mencatat informasi seperti sumber kunci dan masa berlaku. Enabled Apps Mencakup tiga sakelar: Claude Code, OpenAI Codex, dan Gemini. OpenAI Codex wajib diaktifkan. Jika gateway ini juga dipakai oleh dua alat lainnya, keduanya dapat diaktifkan bersama. Model Configuration > Codex > Model Isi nama model yang sudah diperoleh sebelumnya, misalnya gpt-5.6-sol.Model Configuration > Codex > Reasoning Effort Intensitas penalaran, dengan nilai low,medium, atauhigh. Jika tidak ada persyaratan khusus, isihigh.Catatan: Formulir penyedia terpadu tidak menyediakan tombol "Fetch Models". Nama model harus diisi secara manual dan case-sensitive.
Klik Add.
Hasil
Antarmuka menampilkan "Unified provider added and synced". Pada tahap ini, CC Switch telah membuat satu kartu penyedia dengan nama yang sama di daftar penyedia Codex; jika aplikasi lain juga dicentang, kartu juga dibuat di daftar yang sesuai.
Poin penting: Sinkronisasi tidak sama dengan pengaktifan. Saat ini konfigurasi belum ditulis ke file konfigurasi runtime Codex, sehingga Anda harus melanjutkan ke tugas 5.
Aturan pemrosesan alamat API
Saat membuat konfigurasi untuk Codex, CC Switch memproses alamat API yang diisi sebagai berikut:
| Bentuk alamat yang diisi | Hasil pemrosesan |
|---|---|
Hanya domain, tanpa path, misalnya https://seedrouter.net |
Dilengkapi otomatis menjadi https://seedrouter.net/v1 |
Sudah berakhiran /v1, misalnya https://seedrouter.net/v1 |
Digunakan apa adanya |
Berisi path lain, misalnya https://api.example.com/openai |
Digunakan apa adanya, tanpa dilengkapi /v1 |
Kriterianya: alamat hasil pemrosesan, setelah ditambah /responses, harus merupakan path endpoint yang benar-benar dapat digunakan oleh gateway. Sebelum mengisi, sebaiknya Anda mengonfirmasi alamat endpoint yang lengkap kepada penyedia layanan, lalu menentukan isi yang harus diisi dengan menelusuri balik tabel di atas. Alamat yang tidak tepat akan membuat permintaan mengembalikan 404.
Tugas 5: Mengaktifkan penyedia dan menerapkan konfigurasi
Tentang tugas ini
Setelah kartu penyedia dibuat, Anda harus mengaktifkannya secara manual agar konfigurasi ditulis ke file konfigurasi Codex. Codex tidak mendukung hot reload konfigurasi, jadi setelah diaktifkan terminal harus dimulai ulang.
Proses
Tutup panel tambah penyedia.
Pada pengalih aplikasi di bagian atas, beralih ke Codex.
Di daftar penyedia, temukan kartu dengan nama yang sama yang dibuat pada tugas 4.
Klik tombol Enable pada kartu.
Kartu tampil dengan bingkai biru dan label "Currently Enabled", yang berarti konfigurasi telah ditulis.
Tutup sepenuhnya jendela terminal saat ini, lalu buka jendela terminal yang baru.
Poin penting: Yang dimaksud adalah menutup seluruh jendela terminal, bukan keluar dari proses codex lalu menjalankan kembali perintah
codex. Cara pemberlakuan pada masing-masing alat berbeda sebagai berikut:Alat Cara berlaku setelah beralih penyedia Claude Code Berlaku seketika, mendukung hot reload Gemini CLI Berlaku seketika, konfigurasi dibaca ulang pada setiap permintaan Codex Terminal harus ditutup lalu dibuka kembali OpenCode / OpenClaw Terminal harus ditutup lalu dibuka kembali Di terminal yang baru, jalankan:
codexSetelah terbuka, masukkan satu kalimat uji, misalnya "Halo, mohon perkenalkan diri secara singkat".
Hasil
Model mengembalikan jawaban secara normal, yang berarti konfigurasi selesai dan Codex telah terhubung ke gateway yang ditentukan.
Referensi: File konfigurasi yang dihasilkan
CC Switch mengikuti prinsip intervensi minimal. Setelah penyedia diaktifkan, konfigurasi ditulis langsung ke file konfigurasi Codex sendiri; meskipun CC Switch di-uninstall, Codex tetap dapat bekerja secara normal.
File yang terkait adalah sebagai berikut. ~ pada path berarti direktori pengguna saat ini, di Windows berupa C:\Users\<nama pengguna>\, di macOS dan Linux berupa /Users/<nama pengguna>/ atau /home/<nama pengguna>/.
~/.codex/auth.json — menyimpan kredensial:
{
"OPENAI_API_KEY": "<API Key>"
}~/.codex/config.toml — menyimpan konfigurasi model dan endpoint:
model_provider = "cliproxyapi"
model = "gpt-5.6-sol"
model_reasoning_effort = "max"
sandbox_mode = "workspace-write"
model_context_window = 372000
model_auto_compact_token_limit = 334800
model_auto_compact_token_limit_scope = "total"
service_tier = "priority"
[model_providers.cliproxyapi]
name = "SeedRouter"
base_url = "https://seedrouter.net/v1"
wire_api = "responses"
requires_openai_auth = true
experimental_bearer_token = "sk-xxxxxxxxxx"Data CC Switch sendiri disimpan di direktori ~/.cc-switch/, dengan file database cc-switch.db. Cadangan otomatis berada di subdirektori backups/, dan 10 salinan terbaru disimpan.
Operasi pemeliharaan
Mengubah konfigurasi
Saat mengubah API Key, nama model, atau alamat layanan:
Klik tombol +, lalu beralih ke tab Unified Provider.
Klik ikon edit pada kartu target.
Ubah bidang yang sesuai.
Dalam mode edit, bagian bawah formulir menyediakan area Config JSON Preview untuk mengonfirmasi konten aktual yang akan ditulis ke setiap aplikasi sebelum sinkronisasi.
Klik Save and Sync.
Konfirmasikan operasi di dialog konfirmasi. Operasi ini akan menimpa konfigurasi penyedia terkait di Claude, Codex, dan Gemini.
Tutup terminal, lalu buka kembali.
Penjelasan operasi kartu penyedia
| Operasi | Keterangan |
|---|---|
| Sync | Dorong ulang konfigurasi saat ini secara manual ke setiap aplikasi terkait, untuk perbaikan saat konfigurasi tidak konsisten. |
| Copy | Buat satu salinan berdasarkan konfigurasi saat ini, untuk memudahkan konfigurasi kunci cadangan. |
| Edit | Ubah isi konfigurasi. |
| Delete | Hapus Unified Provider, sekaligus hapus kartu penyedia terkait yang dihasilkannya di Claude, Codex, dan Gemini. |
Peralihan cepat
Klik kanan ikon CC Switch di baki sistem, lalu klik langsung nama penyedia target di submenu Codex untuk beralih, tanpa membuka antarmuka utama. Setelah beralih, Anda juga perlu memulai ulang terminal.
Diagnosis gangguan
A. Mengembalikan 401 atau 403, autentikasi gagal
| Kemungkinan penyebab | Solusi |
|---|---|
| API Key berisi spasi atau karakter baris baru yang berlebih saat disalin | Salin dan tempel ulang, perhatikan rentang pilihan |
| API Key sudah kedaluwarsa atau kuota habis | Konfirmasikan status kunci kepada penyedia layanan |
| API Key tidak cocok dengan alamat API | Periksa apakah keduanya berasal dari layanan yang sama |
B. Mengembalikan 404 atau muncul pemberitahuan bahwa endpoint tidak ada
Pada sebagian besar kasus, alamat API tidak benar setelah diproses. Silakan periksa ulang dengan merujuk “Tugas 4 > Aturan pemrosesan alamat API”, dan konfirmasikan alamat endpoint yang lengkap kepada penyedia layanan.
C. Tidak ada perubahan sama sekali setelah konfigurasi diubah
Terminal belum dimulai ulang. Silakan tutup jendela terminal sepenuhnya, lalu buka kembali. Ini adalah masalah yang paling umum saat menggunakan Codex.
D. Bagian atas antarmuka menampilkan peringatan konflik variabel lingkungan
Di sistem terdapat variabel lingkungan seperti OPENAI_API_KEY. Variabel lingkungan memiliki prioritas lebih tinggi daripada file konfigurasi dan akan menimpa konfigurasi yang ditulis CC Switch, sehingga permintaan terkirim ke endpoint yang salah atau menggunakan kunci yang salah.
Langkah penanganan:
- Klik Expand pada banner peringatan untuk melihat nama, nilai, dan sumber variabel yang berkonflik.
- Centang variabel yang perlu dihapus, atau klik Select All.
- Klik Delete Selected dan konfirmasikan.
CC Switch mencadangkan secara otomatis ke ~/.cc-switch/env-backups/ sebelum penghapusan. Jika perlu memulihkan, Anda dapat mengembalikan secara manual dari file JSON di direktori tersebut.
E. Terminal menunjukkan perintah codex tidak ada
| Kemungkinan penyebab | Solusi |
|---|---|
| Terminal tidak dibuka kembali setelah instalasi | Tutup semua jendela terminal, lalu buka kembali |
| Node.js tidak terpasang dengan benar | Kembali ke Tugas 1, lalu verifikasi apakah npm --version menghasilkan output secara normal |
| Direktori global npm belum ditambahkan ke PATH | Instal ulang melalui Settings > About > Local Environment Check di CC Switch |
F. Gateway hanya mendukung protokol Chat Completions
Protokol komunikasi Unified Provider tetap Responses, sehingga tidak berlaku untuk skenario ini. Anda harus beralih ke penyedia khusus aplikasi.
- Di CC Switch, beralih ke panel Codex, lalu klik tombol +.
- Tetap di tab Codex Provider di sebelah kiri, jangan beralih ke Unified Provider.
- Pada menu tarik-turun preset, pilih penyedia layanan yang sesuai. DeepSeek, Zhipu GLM, Kimi, MiniMax, StepFun, Bailian, ModelScope, SiliconFlow, Doubao Seed, Xiaomi MiMo, Novita AI, dan lainnya semuanya termasuk preset kategori Chat Completions.
- Setelah preset jenis ini dipilih, CC Switch secara otomatis mengaktifkan sakelar “Local Route Mapping Required” dan mengonfigurasi tabel pemetaan model. Konversi protokol diselesaikan oleh proxy lokal, tanpa pengaturan manual.
- Isi API Key, klik Add, lalu aktifkan penyedia tersebut dan mulai ulang terminal.
G. Perlu memulihkan ke login akun resmi
- Di panel Codex, tambahkan penyedia dengan preset “OpenAI Official”.
- Aktifkan penyedia tersebut dan mulai ulang terminal.
- Selesaikan autentikasi sesuai alur login Codex sendiri.
Setelah selesai, Anda dapat beralih secara bebas antara login resmi dan penyedia pihak ketiga.
Referensi pemilihan: Unified Provider dan App-specific Provider
| Skenario penggunaan | Rekomendasi |
|---|---|
| Satu gateway yang melayani Claude Code, Codex, dan Gemini CLI sekaligus, serta mendukung protokol Responses | Unified Provider |
| Hanya menggunakan satu alat, yaitu Codex | Keduanya bisa; jalur konfigurasi App-specific Provider lebih singkat |
| Gateway hanya mendukung protokol Chat Completions | App-specific Provider, beserta preset bawaan |
| Masing-masing alat terhubung ke pihak layanan yang berbeda | App-specific Provider, dikonfigurasi terpisah |
| Perlu mengonfigurasi OpenCode, OpenClaw, atau Hermes | App-specific Provider, ketiga alat ini tidak mendukung Unified Provider |
Catatan keamanan
- API Key sama sensitifnya dengan kredensial akun. Jangan meneruskan API Key melalui aplikasi pesan instan, membagikannya lewat tangkapan layar, atau mengirimkannya ke repositori kode.
- Dapatkan paket instalasi CC Switch hanya dari situs resmi CC Switch atau repositori GitHub resmi.
- Saat perangkat berganti atau Anda menduga kunci telah bocor, segera ganti kunci tersebut.
- Fitur ekspor konfigurasi CC Switch menuliskan seluruh informasi penyedia dalam bentuk plaintext ke file cadangan
.sql. Simpan file hasil ekspor dengan baik, dan jangan letakkan di direktori bersama.
Referensi cepat
1. Instal Node.js nodejs.org, pilih versi LTS
2. Instal CC Switch ccswitch.io atau GitHub Releases
3. Instal Codex CC Switch > Settings > About > Local Environment Check > Install
4. Buat Unified Provider Beralih ke panel Codex > + > Unified Provider > Add Unified Provider
Isi nama, alamat API, dan API Key
Nyalakan sakelar OpenAI Codex, lalu isi nama model
5. Aktifkan penyedia panel Codex > kartu yang dituju > Enable
6. Mulai ulang terminal Tutup jendela terminal sepenuhnya, lalu buka kembali
7. Verifikasi Jalankan perintah codex dan kirim pesan uji
Saat Anda mengirim umpan balik masalah, sertakan sekaligus tangkapan layar lengkap pesan kesalahan serta alamat API yang Anda isi pada tugas 4 (bagian kunci harus disamarkan), untuk mempersingkat siklus penelusuran.