Cara Menggunakan Codex dengan Model Open Source Apa Pun (Mode OSS)

Codex hadir dengan model OpenAI secara default, namun tidak mengunci Anda untuk menggunakannya. CLI memiliki mode OSS bawaan untuk runtime lokal seperti Ollama dan LM Studio, ditambah sistem penyedia kustom yang mengarahkan agen ke endpoint yang kompatibel yang Anda tentukan dalam file TOML. Itu berarti Anda dapat menjalankan gpt-oss di laptop Anda, menggerakkan Codex dengan API DeepSeek atau Qwen yang dihosting, atau beralih antara penyedia per proyek.

Panduan ini menjelaskan seluruh pengaturan: apa yang dilakukan mode OSS, kunci konfigurasi yang tepat, resep per model, dan kompromi yang Anda terima saat menukar model OpenAI. Semua yang ada di sini berasal dari dokumentasi konfigurasi lanjutan Codex resmi. Jika dokumennya ambigu, saya akan menyatakannya daripada menebak.

Satu catatan sebelum kita mulai. Setelah model Anda berjalan di dalam Codex, model itu hanyalah separuh dari alur kerja. Separuh lainnya adalah memverifikasi API yang dibangun dan dipanggil oleh agen Anda. Di sinilah Apidog berperan, dan kita akan membahas pasangannya menjelang akhir.

TL;DR

Mode OSS Codex adalah fitur CLI. Jalankan codex --oss dan Codex akan berbicara dengan server Ollama atau LM Studio lokal alih-alih OpenAI. Atur oss_provider = "ollama" di ~/.codex/config.toml untuk menjadikannya default, dan teruskan -m <model> untuk memilih model lokal mana yang akan berjalan. Untuk model sumber terbuka yang dihosting (DeepSeek, Qwen, GLM melalui API mereka), definisikan blok [model_providers.<id>] dengan base_url dan env_key, lalu pilih dengan model_provider. Perangkapnya: referensi konfigurasi saat ini mencantumkan responses sebagai satu-satunya nilai wire_api yang didukung, jadi endpoint Anda perlu berbicara protokol Responses API.

Apa itu mode OSS

Mode OSS adalah jalan pintas Codex untuk berjalan melawan server model sumber terbuka lokal. Dokumen-dokumen tersebut menjelaskan dua penyedia lokal yang didukung:

• Ollama, runtime model lokal yang populer
• LM Studio, aplikasi desktop dengan server lokal bawaan

Anda mengaktifkannya dengan flag --oss. Dari referensi perintah pengembang Codex:

--oss: Gunakan penyedia model sumber terbuka lokal. Codex menggunakan --local-provider, oss_provider yang Anda konfigurasi, atau meminta Anda untuk memilih antara LM Studio dan Ollama.

Ada flag pendamping, --local-provider, yang menerima lmstudio atau ollama dan menimpa default Anda untuk satu kali eksekusi. Jika Anda tidak mengatur flag maupun default konfigurasi, CLI interaktif akan meminta Anda untuk memilih. codex exec yang non-interaktif tidak akan meminta; ia akan keluar dengan kesalahan. Jadi untuk skrip dan CI, selalu atur penyedia secara eksplisit.

Catatan kejujuran mengenai permukaan: dokumentasi mencakup mode OSS dan penyedia kustom di bawah sistem config.toml CLI. Ekstensi IDE dan cloud Codex tidak disebutkan mendukung penyedia lokal di mana pun dalam dokumen konfigurasi. [VERIFIKASI: apakah ekstensi IDE Codex membaca model_providers dari config.toml dengan cara yang sama seperti CLI; dokumen tidak menyatakannya dengan cara apa pun.] Perlakukan ini sebagai alur kerja CLI sampai OpenAI mendokumentasikan sebaliknya.

Mengapa menjalankan model sumber terbuka di dalam Codex

Pertanyaan yang wajar, karena Codex adalah agen milik OpenAI. Beberapa alasan nyata:

• Kontrol biaya. Inferensi lokal melalui Ollama tidak membebankan biaya per token. Jika Anda menghabiskan batas penggunaan pada sesi agen yang panjang, model lokal menangani pekerjaan dasar sementara Anda menyimpan panggilan yang dihosting untuk masalah yang sulit.
• Privasi dan pekerjaan terisolasi. Beberapa basis kode tidak boleh meninggalkan mesin. Model Kimi, GLM, atau gpt-oss lokal menyimpan setiap token di perangkat keras Anda. Panduan kami tentang menjalankan Kimi K3 secara lokal mencakup apa yang dibutuhkan dalam praktiknya.
• Preferensi model. Model open-weight telah menutup sebagian besar celah dalam pengodean. API yang dihosting DeepSeek dan Qwen memotong harga OpenAI sambil mencetak skor dalam jangkauan pada tolok ukur pengodean, dan Anda mungkin hanya menyukai cara model tertentu menulis kode.
• Satu kerangka agen, banyak model. UX terminal Codex, sandboxing, dan alur persetujuan sangat baik. Konfigurasi penyedia memungkinkan Anda mempertahankan kerangka tersebut dan mengganti 'otaknya'.

Di mana konfigurasi berada

Codex menyimpan status di bawah CODEX_HOME, yang secara default adalah ~/.codex. Konfigurasi tingkat pengguna Anda adalah ~/.codex/config.toml, dan sebuah repo dapat membawa penggantian tingkat proyek di .codex/config.toml. Semua yang di bawah ini masuk ke salah satu dari kedua file tersebut.

Mulai cepat: Codex dengan Ollama

Jalur tercepat untuk mendapatkan model sumber terbuka di Codex adalah Ollama.

1. Instal Ollama dari ollama.com dan jalankan. Ia menyajikan API yang kompatibel dengan OpenAI di port 11434.
2. Tarik model. Rilis open-weight milik OpenAI adalah pilihan pertama yang alami; halaman pustaka gpt-oss memiliki varian 20b dan 120b. Kami telah membahas penyiapan mandiri dalam cara menjalankan gpt-oss menggunakan Ollama.

ollama pull gpt-oss:20b

3. Jalankan Codex dalam mode OSS dan beri nama model:

codex --oss -m gpt-oss:20b

Flag -m/--model menimpa model yang dikonfigurasi, dan dikombinasikan dengan --oss itu memilih model lokal mana yang akan berjalan. Untuk penggunaan non-interaktif:

codex exec --oss --local-provider ollama -m gpt-oss:20b "add input validation to the signup route"

4. Jadikan itu default sehingga Anda dapat menghilangkan flag. Di ~/.codex/config.toml:

# Default local provider used with `--oss`
oss_provider = "ollama" # or "lmstudio"

Itulah seluruh fitur untuk model lokal. Tidak ada kunci API, tidak ada blok penyedia kustom. LM Studio berfungsi dengan cara yang sama: muat model di aplikasi, mulai server lokalnya, dan jalankan codex --oss --local-provider lmstudio. Lihat lmstudio.ai untuk penyiapan server.

Penyedia kustom: arahkan Codex ke endpoint yang kompatibel

Mode OSS mencakup Ollama dan LM Studio. Untuk yang lainnya, seperti API DeepSeek atau Qwen yang dihosting, proxy, server vLLM di LAN Anda, Codex memiliki penyedia model kustom. Dokumen mendefinisikan penyedia sebagai “cara Codex terhubung ke model (URL dasar, wire API, autentikasi, dan header HTTP opsional).”

Pola dari dokumen resmi:

model = "gpt-5.6-terra"
model_provider = "proxy"

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"

[model_providers.local_ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"

[model_providers.mistral]
name = "Mistral"
base_url = "https://api.mistral.ai/v1"
env_key = "MISTRAL_API_KEY"

Kunci-kunci yang penting:

Penyetelan jaringan per penyedia juga tersedia: request_max_retries (default 4), stream_max_retries (default 5), dan stream_idle_timeout_ms (default 300000). Perangkat keras lokal yang lambat akan diuntungkan dari batas waktu idle yang lebih lama, karena model 120b di laptop dapat diam sesaat di antara token.

Dua aturan yang disebutkan langsung oleh dokumen. Pertama, ID openai, ollama, dan lmstudio adalah cadangan; Anda tidak dapat menimpa penyedia bawaan. Untuk mengubah URL dasar penyedia OpenAI bawaan, atur openai_base_url alih-alih membuat [model_providers.openai]. Kedua, dan ini yang membentuk segalanya: referensi konfigurasi menyatakan bahwa untuk wire_api, “responses adalah satu-satunya nilai yang didukung, dan itu adalah default jika dihilangkan.”

Itu adalah batasan yang nyata. Versi Codex sebelumnya menerima wire_api = "chat" untuk endpoint Chat Completions, dan halaman ikhtisar model masih mengatakan Anda dapat mengarahkan Codex ke penyedia yang mendukung “baik Chat Completions atau Responses APIs.” Referensi dan ikhtisar tidak setuju. [VERIFIKASI: apakah wire_api = "chat" masih berfungsi di rilis CLI saat ini; referensi konfigurasi mengatakan hanya respons, halaman model menyiratkan obrolan masih berfungsi. Uji terhadap endpoint hanya-obrolan sebelum menerbitkan.] Jika hanya respons yang berlaku, penyedia Anda memerlukan endpoint Responses API, yang kini diekspos oleh sebagian besar server yang kompatibel dengan OpenAI tetapi beberapa API yang dihosting masih belum.

Resep model demi model

Setiap resep di bawah ini adalah blok konfigurasi ditambah perintah untuk dijalankan. Atur variabel lingkungan kunci API sebelum meluncurkan.

DeepSeek (API yang dihosting)

DeepSeek menambahkan dukungan Responses API bersamaan dengan beta V4 Flash-nya, yang persis seperti yang diinginkan protokol wire Codex. Kami membahas peluncuran itu di DeepSeek V4 Flash, Responses API, dan Codex.

model = "deepseek-chat"
model_provider = "deepseek"

[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
env_key = "DEEPSEEK_API_KEY"

export DEEPSEEK_API_KEY="sk-..."
codex

Periksa dokumen API DeepSeek untuk ID model saat ini. [VERIFIKASI: jalur base_url DeepSeek yang tepat untuk akses protokol Respons; jalur chat /v1 mungkin berbeda dari jalur Respons.]

Qwen (dihosting melalui Model Studio)

Model Studio (DashScope) Alibaba mengekspos mode yang kompatibel dengan OpenAI untuk keluarga Qwen 3.8. Endpoint mode kompatibel secara historis berbentuk Chat Completions. [VERIFIKASI: apakah mode kompatibel DashScope sekarang menyajikan protokol Respons; jika tidak, resep ini bergantung pada pertanyaan wire_api = "chat" di atas.]

model = "qwen3.8-max"
model_provider = "qwen"

[model_providers.qwen]
name = "Qwen via Model Studio"
base_url = "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
env_key = "DASHSCOPE_API_KEY"

Panduan API Qwen 3.8 kami mencakup kunci, ID model, dan harga untuk rute yang dihosting.

Kimi, GLM, dan open weights lainnya (lokal via Ollama)

Apa pun yang dapat Anda tarik ke Ollama berfungsi melalui mode OSS biasa, tanpa blok penyedia yang diperlukan:

ollama pull <model>
codex --oss -m <model>

Itu mencakup GLM dan Qwen open weights, ditambah Kimi K3 jika perangkat keras Anda sanggup (bobot K3 adalah 594 GB pada MXFP4, jadi kebanyakan orang harus membaca menjalankan Kimi K3 secara lokal sebelum mencoba). Untuk mesin berukuran menengah, gpt-oss:20b atau build Qwen coder terkuantisasi adalah pilihan praktis.

vLLM yang di-host sendiri atau server LAN

Server vLLM atau server yang kompatibel dengan OpenAI serupa di mesin lain adalah penyedia kustom, bukan mode OSS:

model_provider = "lan_vllm"

[model_providers.lan_vllm]
name = "vLLM on the workstation"
base_url = "http://192.168.1.50:8000/v1"
env_key = "VLLM_API_KEY"

Profil: beralih "otak" per tugas

Anda tidak perlu memilih satu pengaturan. Profil Codex adalah file TOML terpisah di ~/.codex/<nama-profil>.config.toml, yang berlapis di atas konfigurasi dasar Anda saat Anda meneruskan --profile. Profil model lokal terlihat seperti ini:

# ~/.codex/oss-local.config.toml
oss_provider = "ollama"
model = "gpt-oss:20b"

codex --profile oss-local
codex exec --profile oss-local "write unit tests for utils/dates.ts"

Pertahankan konfigurasi default Anda pada model OpenAI untuk refactor yang sulit dan gunakan --profile oss-local untuk perbaikan lint, perancah pengujian, dan pemeriksaan dokumen. Penggantian satu kali juga berfungsi tanpa profil: codex -c model='"deepseek-chat"' -c model_provider='"deepseek"'.

Kompromi dibandingkan model OpenAI

Jujurlah pada diri sendiri tentang apa yang Anda tukarkan:

• Kapabilitas. gpt-oss:20b bukanlah gpt-5.6-terra. Model lokal lebih sering gagal pada pengeditan multi-file yang panjang, dan perulangan agen memperkuat kelemahan model karena setiap langkah dibangun di atas langkah sebelumnya.
• Kecepatan. API yang dihosting mengalir dengan cepat. Model lokal yang besar pada perangkat keras konsumen bisa sangat lambat hingga mengubah cara Anda bekerja.
• Kualitas perkakas. Prompt dan panggilan perkakas Codex disetel untuk model OpenAI. Model sumber terbuka bervariasi dalam seberapa andal mereka mengeluarkan panggilan perkakas, dan protokol wire hanya-respons mempersempit endpoint mana yang memenuhi syarat sama sekali.
• Permukaan dukungan. Mode OSS adalah jalur CLI yang terdokumentasi, tetapi penyedia pihak ketiga adalah tanggung jawab Anda: ID model, batas laju, dan keanehan protokol ada di antara Anda dan vendor.

Pembagian pragmatis: model lokal atau yang dihosting murah untuk pekerjaan bervolume tinggi berisiko rendah, model frontier untuk tugas-tugas di mana eksekusi yang gagal menghabiskan waktu Anda seharian.

Verifikasi API yang disentuh agen Anda

Model apa pun yang berjalan di dalam Codex, hasilnya biasanya adalah kode yang memanggil atau mendefinisikan API, dan model sumber terbuka lebih sering berhalusinasi endpoint dan skema daripada model frontier. Tangkap itu di lapisan API daripada di produksi.

Apidog mencakup sisi alur kerja tersebut. Arahkan server Apidog MCP ke proyek Anda dan agen Codex Anda dapat membaca spesifikasi API yang sebenarnya saat menulis kode, alih-alih mengarang nama bidang. Kemudian gunakan Apidog CLI di dalam Codex untuk membiarkan agen menjalankan skenario pengujian Anda dari terminal setelah setiap perubahan: ia mengedit, ia menguji, Anda meninjau diff yang lolos. Lingkaran itu lebih penting, bukan kurang penting, ketika model yang lebih kecil menulis kode. Unduh Apidog untuk menghubungkannya; CLI dan server MCP bekerja dengan model apa pun yang telah Anda konfigurasi.

Pemecahan Masalah

• codex exec langsung eror dalam mode OSS. Anda tidak mengatur penyedia. Eksekusi non-interaktif tidak pernah meminta, jadi teruskan --local-provider ollama atau atur oss_provider di konfigurasi.
• Koneksi ditolak pada port 11434. Ollama tidak berjalan, atau terikat ke alamat yang berbeda. Mulai aplikasi atau ollama serve, dan konfirmasikan dengan curl http://localhost:11434/v1/models.
• Kesalahan 404 atau protokol dari penyedia yang dihosting. Bentuk base_url salah, atau endpoint tidak berbicara protokol Respons. Periksa apakah vendor mendokumentasikan jalur yang kompatibel dengan Respons.
• Kegagalan autentikasi. env_key menamai variabel lingkungan; Codex membaca kunci dari lingkungan shell Anda saat peluncuran. Ekspor di shell yang sama, dan ingat bahwa shell launchd atau CI mungkin tidak memuat dotfile Anda.
• Stream mati di tengah generasi pada model lokal yang lambat. Tingkatkan stream_idle_timeout_ms dan stream_max_retries di blok penyedia.
• Perubahan konfigurasi diabaikan. Periksa apakah ada .codex/config.toml tingkat proyek yang menimpa konfigurasi pengguna Anda, dan ingat bahwa profil berlapis di atas keduanya.

FAQ

Apakah mode OSS Codex berfungsi di ekstensi IDE atau cloud Codex?

Dokumen-dokumen tersebut mendokumentasikan mode OSS dan penyedia kustom sebagai bagian dari sistem konfigurasi CLI. Dukungan IDE atau cloud untuk penyedia lokal tidak didokumentasikan, jadi perlakukan ini sebagai fitur CLI. [VERIFIKASI sebelum mengandalkan dukungan IDE.]

Model mana yang paling baik bekerja dengan Codex dalam mode OSS?

Apa pun yang dapat disajikan Ollama atau LM Studio di perangkat keras Anda. gpt-oss:20b adalah default yang rendah gesekan. Pilihan pengodean open-weight yang kuat meliputi keluarga Qwen 3.8 dan GLM; untuk model raksasa seperti Kimi K3, periksa perhitungan perangkat keras di panduan Kimi K3 lokal kami terlebih dahulu.

Bisakah saya menggunakan OpenRouter atau aggregator lain dengan Codex?

Aggregator apa pun yang mengekspos endpoint yang kompatibel sesuai dengan pola [model_providers.<id>]: atur base_url dan env_key, lalu pilih dengan model_provider. Pertanyaan yang belum terjawab adalah protokol: referensi konfigurasi mencantumkan responses sebagai satu-satunya wire_api yang didukung, jadi pastikan aggregator Anda menyajikan Responses API.

Apakah saya memerlukan kunci API OpenAI untuk menjalankan Codex dengan model sumber terbuka?

Tidak ada kunci yang diperlukan untuk mode OSS dengan server Ollama atau LM Studio lokal. Penyedia yang dihosting kustom menggunakan kunci mereka sendiri melalui env_key. Anda tetap masuk ke Codex seperti biasa untuk apa pun yang terkait dengan layanan OpenAI.

Jalankan pengaturan yang sesuai dengan tugas. gpt-oss lokal untuk perulangan murah, DeepSeek atau Qwen saat Anda menginginkan kecepatan yang dihosting dengan biaya lebih rendah, dan model frontier OpenAI saat masalahnya sulit. Konfigurasi Codex menjadikan ketiganya hanya terpisah satu flag, dan dengan Apidog menangani verifikasi di sisi API, model menjadi bagian yang dapat ditukar alih-alih komitmen.