CLI Model

Referensi model (provider/model) memilih penyedia dan model, bukan runtime agen tingkat rendah. Saat kebijakan runtime tidak ditetapkan atau bernilai auto, kebijakan rute milik penyedia OpenAI dapat memilih Codex hanya untuk rute resmi HTTPS Platform Responses atau ChatGPT Responses yang sama persis tanpa penggantian permintaan yang ditulis pengguna; prefiks openai/* saja tidak pernah memilih Codex. Adaptor Completions, endpoint khusus, dan perilaku permintaan yang ditulis pengguna tetap menggunakan OpenClaw. Endpoint resmi HTTP teks biasa ditolak. Lihat Runtime agen implisit OpenAI.

Referensi Copilot langganan (github-copilot/*) dapat diikutsertakan dalam plugin runtime agen GitHub Copilot eksternal, tetapi jalur tersebut selalu eksplisit (tidak pernah dipilih oleh auto). Penggantian runtime berada dalam kebijakan penyedia/model, bukan pada seluruh agen atau sesi. Pemilihan runtime tidak menentukan penagihan: kredensial kunci API OpenAI dan langganan ChatGPT/Codex tetap terpisah. Lihat Runtime agen dan Runtime agen GitHub Copilot.

Urutan pemilihan

Permukaan konfigurasi model terkait:

• agents.defaults.models menyimpan alias dan pengaturan per model. Menambahkan entri tidak membatasi penggantian model.
• agents.defaults.modelPolicy.allow adalah daftar izin penggantian opsional. Gunakan referensi yang sama persis atau wildcard prefiks di bagian akhir seperti provider/* dan provider/namespace/*; hilangkan atau tetapkan [] untuk mengizinkan model apa pun. agents.list[].modelPolicy.allow per agen menggantikan kebijakan default untuk agen tersebut.
• agents.defaults.utilityModel adalah model opsional berbiaya lebih rendah untuk tugas internal singkat seperti judul sesi dasbor yang dihasilkan, judul utas/topik kanal yang didukung, dan narasi progres. agents.list[].utilityModel per agen menggantikannya. Saat tidak ditetapkan, OpenClaw menggunakan default model kecil yang dideklarasikan oleh penyedia utama jika tersedia (OpenAI → gpt-5.6-luna, Anthropic → claude-haiku-4-5), atau model utama agen jika tidak tersedia; tetapkan ke string kosong untuk menonaktifkan perutean utilitas. Judul yang dihasilkan mencoba ulang satu kali dengan model utama ketika model utilitas yang berbeda gagal. Untuk judul dasbor, derivasi utilitas otomatis dan fallback biasa mengikuti penyedia sesi dan profil autentikasi yang berlaku; model utilitas eksplisit mempertahankan penyedia/autentikasi yang dikonfigurasi. Model utilitas kosong hanya melewati rute model kecil alternatif, bukan pembuatan judul dasbor. Tugas utilitas merupakan panggilan model terpisah dan dapat mengirimkan konten tugas terbatas kepada penyedia model yang dipilih.
• agents.defaults.imageModel hanya digunakan ketika model utama tidak dapat menerima gambar.
• agents.defaults.pdfModel digunakan oleh alat pdf. Jika tidak ditetapkan, alat menggunakan fallback ke imageModel, lalu model sesi/default yang telah diuraikan.
• agents.defaults.imageGenerationModel, musicGenerationModel, dan videoGenerationModel mendukung alat pembuatan media bersama. Jika tidak ditetapkan, setiap alat menyimpulkan default penyedia yang didukung autentikasi: penyedia default saat ini terlebih dahulu, lalu penyedia terdaftar lainnya untuk kapabilitas tersebut berdasarkan urutan ID penyedia. Tetapkan agents.defaults.mediaGenerationAutoProviderFallback: false untuk menonaktifkan inferensi lintas penyedia tersebut sambil mempertahankan fallback eksplisit.
• agents.list[].model per agen (beserta pengikatan) menggantikan agents.defaults.model — lihat Perutean multiagen.

Referensi lengkap kunci, nilai default, dan contoh JSON5: Referensi konfigurasi.

Sumber pemilihan dan ketegasan fallback

provider/model yang sama berperilaku berbeda tergantung asalnya:

Aturan pemilihan lainnya:

• Mengubah agents.defaults.model.primary tidak menulis ulang pin sesi yang sudah ada. Jika status melaporkan This session is pinned to X; config primary Y will apply to new/unpinned sessions., jalankan /model default untuk menghapus pin.
• Pemilih model default dan daftar izin CLI mematuhi models.mode: "replace" dengan hanya mencantumkan models.providers.*.models, bukan seluruh katalog bawaan.
• Pemilih model Control UI meminta tampilan model yang dikonfigurasi dari Gateway. modelPolicy.allow eksplisit memfilternya, termasuk entri wildcard prefiks di bagian akhir; jika tidak ada, pemilih menampilkan model yang dikonfigurasi beserta penyedia yang memiliki autentikasi yang dapat digunakan. Katalog bawaan lengkap hanya tersedia untuk tampilan penelusuran eksplisit (models.list dengan view: "all", atau openclaw models list --all).
• UI inventaris penyedia menggunakan models.list dengan view: "provider-config" untuk menampilkan baris models.providers.*.models yang ditulis sumber tanpa menerapkan daftar izin pemilih.

Mekanisme lengkap: Pengalihan model saat gagal.

Kebijakan model singkat

• Tetapkan model utama Anda ke model generasi terbaru terkuat yang tersedia bagi Anda.
• Gunakan fallback untuk tugas yang sensitif terhadap biaya/latensi dan percakapan dengan risiko lebih rendah.
• Untuk agen yang mendukung alat atau input yang tidak tepercaya, hindari tingkatan model yang lebih lama/lemah.

Orientasi awal

openclaw onboard

Menyiapkan model dan autentikasi untuk penyedia umum tanpa mengedit konfigurasi secara manual, termasuk OAuth langganan OpenAI Codex dan Anthropic (kunci API atau penggunaan ulang Claude CLI).

Jika tidak ada model utama yang dikonfigurasi, penyiapan baru dengan kunci API OpenAI memilih openai/gpt-5.6; ID API langsung tanpa kualifikasi diuraikan ke tingkatan Sol. Penyiapan baru OAuth ChatGPT/Codex memilih referensi katalog openai/gpt-5.6-sol yang sama persis. Autentikasi ulang mempertahankan model utama eksplisit yang sudah ada, termasuk openai/gpt-5.5. Jika GPT-5.6 tidak tersedia untuk akun tersebut, pilih openai/gpt-5.5 secara eksplisit; OpenClaw tidak menurunkan versinya secara diam-diam.

"Model tidak diizinkan" (dan alasan balasan berhenti)

Jika agents.defaults.modelPolicy.allow tidak kosong, nilai tersebut menjadi daftar izin untuk /model, penggantian sesi, dan --model. Memilih model di luar daftar izin tersebut mengembalikan hasil sebelum balasan normal dihasilkan. agents.list[].modelPolicy.allow per agen menggantikan kebijakan default untuk agen tersebut.

Penggantian model "provider/model" tidak diizinkan oleh agents.defaults.modelPolicy.allow.Tambahkan "provider/model", "provider/*", atau prefiks "provider/namespace/*" yang lebih sempit ke agents.defaults.modelPolicy.allow, atau hapus/kosongkan daftar tersebut untuk mengizinkan model apa pun.

Perbaiki dengan menambahkan model atau wildcard penyedia ke kunci modelPolicy.allow yang disebutkan, menghapus/mengosongkan daftar tersebut, atau memilih model dari /model list. Jika perintah yang ditolak menyertakan penggantian runtime seperti /model openai/gpt-5.5 --runtime codex, perbaiki daftar izin terlebih dahulu, lalu coba lagi perintah yang sama.

Untuk model lokal/GGUF, daftar izin memerlukan referensi lengkap dengan prefiks penyedia, misalnya ollama/gemma4:26b atau lmstudio/Gemma4-26b-a4-it-gguf — periksa openclaw models list --provider <provider> untuk string yang sama persis. Nama file tanpa prefiks atau nama tampilan tidak cukup setelah daftar izin aktif.

Untuk membatasi penyedia tanpa mencantumkan setiap model, gunakan entri wildcard prefiks di bagian akhir. provider/* tingkat penyedia cocok dengan setiap model di bawah penyedia tersebut; prefiks yang lebih sempit seperti clawrouter/anthropic/* hanya cocok dengan namespace tersebut:

{  agents: {    defaults: {      modelPolicy: {        allow: ["openai/*", "vllm/*"],      },    },  },}

/model, /models, dan pemilih model kemudian hanya menampilkan katalog yang ditemukan untuk penyedia tersebut, dan model baru dapat muncul tanpa mengedit daftar izin. Gabungkan entri provider/model yang sama persis dengan entri provider/* untuk menyertakan satu model tertentu dari penyedia lain.

Contoh daftar izin dengan alias dan pengaturan per model:

{  agents: {    defaults: {      model: { primary: "anthropic/claude-sonnet-4-6" },      modelPolicy: {        allow: ["anthropic/claude-sonnet-4-6", "anthropic/claude-opus-4-6"],      },      models: {        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },        "anthropic/claude-opus-4-6": { alias: "Opus" },      },    },  },}

openclaw config set agents.defaults.modelPolicy.allow '["openai/gpt-5.4","anthropic/*"]' --strict-json

/model dalam percakapan

/model/model list/model 3/model openai/gpt-5.4/model default/model status

• /model dan /model list menampilkan pemilih bernomor ringkas (keluarga model + penyedia yang tersedia); /model <#> memilih darinya. Di Discord, tindakan ini membuka menu tarik-turun penyedia/model dengan langkah Submit; di Telegram, pilihan pemilih dibatasi pada sesi dan tidak pernah menulis ulang nilai default persisten agen di openclaw.json. /models add sudah tidak digunakan dan mengembalikan pesan alih-alih mendaftarkan model dari obrolan.
• /model segera menyimpan pilihan sesi baru. Jika agen sedang menganggur, eksekusi berikutnya langsung menggunakannya; jika eksekusi sudah aktif, peralihan diantrekan untuk titik percobaan ulang bersih berikutnya (atau titik yang lebih kemudian, jika aktivitas alat atau keluaran balasan sudah dimulai).
• /model default menghapus pilihan sesi agar kembali mewarisi model utama yang dikonfigurasi.
• Referensi /model yang dipilih pengguna berlaku ketat untuk sesi tersebut: jika referensi itu tidak dapat dijangkau, balasan gagal secara kasatmata alih-alih beralih diam-diam melalui agents.defaults.model.fallbacks. Nilai default yang dikonfigurasi dan model utama tugas cron tetap menggunakan rantai fallback.
• /model status adalah tampilan terperinci: kandidat autentikasi per penyedia, serta (jika dikonfigurasi) titik akhir penyedia baseUrl beserta mode api.
• Referensi model diurai dengan memisahkannya pada / pertama; ketik provider/model. Jika ID model itu sendiri berisi / (gaya OpenRouter), sertakan prefiks penyedia, misalnya /model openrouter/moonshotai/kimi-k2. Jika penyedia tidak dicantumkan, OpenClaw mencoba: (1) kecocokan alias, (2) kecocokan penyedia terkonfigurasi yang unik untuk ID model tanpa prefiks tersebut, (3) penyedia default yang dikonfigurasi (fallback yang sudah tidak digunakan) — dan jika penyedia itu tidak lagi menyediakan model default yang dikonfigurasi, gunakan penyedia/model terkonfigurasi pertama sebagai gantinya agar nilai default penyedia yang telah dihapus dan kedaluwarsa tidak ditampilkan.
• Referensi model dinormalisasi menjadi huruf kecil; selain itu, ID penyedia harus persis, jadi gunakan ID yang diumumkan oleh plugin.

Perilaku perintah dan konfigurasi lengkap: Perintah garis miring.

CLI

openclaw models statusopenclaw models listopenclaw models set <provider/model>openclaw models set-image <provider/model>openclaw models scanopenclaw models aliases list|add|removeopenclaw models fallbacks list|add|remove|clearopenclaw models image-fallbacks list|add|remove|clearopenclaw models auth list|add|login|paste-api-key|paste-token|setup-token|order

openclaw models tanpa subperintah merupakan pintasan untuk models status, yang juga menampilkan masa berlaku OAuth untuk profil penyimpanan autentikasi (secara default memperingatkan dalam 24 jam). Flag lengkap, struktur JSON, dan subperintah profil autentikasi: Referensi CLI model.

Registri model (models.json)

Penyedia kustom yang dikonfigurasi di bawah models.providers ditulis ke models.json dalam direktori agen (nilai default ~/.openclaw/agents/<agentId>/agent/models.json). Katalog plugin penyedia disimpan secara terpisah sebagai serpihan katalog milik plugin yang dihasilkan dan dimuat secara otomatis. Secara default, berkas ini digabungkan dengan konfigurasi; atur models.mode: "replace" agar hanya menggunakan penyedia yang Anda konfigurasi.

Persistensi penanda menjadikan sumber sebagai otoritas: OpenClaw menulis penanda dari snapshot konfigurasi sumber yang aktif (sebelum resolusi), bukan dari nilai rahasia runtime yang telah diresolusikan, setiap kali menghasilkan ulang models.json — termasuk jalur yang digerakkan oleh perintah seperti openclaw agent.

Terkait

• Runtime agen — OpenClaw, Codex, dan runtime loop agen lainnya
• Referensi konfigurasi — kunci konfigurasi model
• Pembuatan gambar — konfigurasi model gambar
• Failover model — rantai fallback
• Penyedia model — perutean penyedia dan autentikasi
• Referensi CLI model — referensi lengkap perintah dan flag
• Pembuatan musik — konfigurasi model musik
• Pembuatan video — konfigurasi model video