English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Concepts and configuration

CLI Model

Failover model

Rotasi profil autentikasi, masa cooldown, dan bagaimana hal itu berinteraksi dengan fallback.
Penyedia model

Ikhtisar dan contoh singkat penyedia.
Runtime agen

PI, Codex, dan runtime loop agen lainnya.
Referensi konfigurasi

Kunci konfigurasi model.

Ref model memilih penyedia dan model. Ref biasanya tidak memilih runtime agen tingkat rendah. Misalnya, openai/gpt-5.5 dapat berjalan melalui jalur penyedia OpenAI normal atau melalui runtime server aplikasi Codex, bergantung pada agents.defaults.agentRuntime.id. Dalam mode runtime Codex, ref openai/gpt-* tidak menyiratkan penagihan kunci API; autentikasi dapat berasal dari akun Codex atau profil autentikasi openai-codex. Lihat Runtime agen.

Cara kerja pemilihan model

OpenClaw memilih model dalam urutan ini:

  • Model utama

    agents.defaults.model.primary (atau agents.defaults.model).

  • Fallback

    agents.defaults.model.fallbacks (sesuai urutan).

  • Failover autentikasi penyedia

    Failover autentikasi terjadi di dalam penyedia sebelum berpindah ke model berikutnya.

    • Permukaan model terkait
    • agents.defaults.models adalah allowlist/katalog model yang dapat digunakan OpenClaw (ditambah alias).
    • agents.defaults.imageModel digunakan hanya ketika model utama tidak dapat menerima gambar.
    • agents.defaults.pdfModel digunakan oleh alat pdf. Jika dihilangkan, alat tersebut kembali ke agents.defaults.imageModel, lalu model sesi/default yang diselesaikan.
    • agents.defaults.imageGenerationModel digunakan oleh kapabilitas pembuatan gambar bersama. Jika dihilangkan, image_generate masih dapat menyimpulkan default penyedia yang didukung autentikasi. Ini mencoba penyedia default saat ini terlebih dahulu, lalu penyedia pembuatan gambar terdaftar lainnya dalam urutan ID penyedia. Jika Anda menetapkan penyedia/model tertentu, konfigurasikan juga autentikasi/kunci API penyedia tersebut.
    • agents.defaults.musicGenerationModel digunakan oleh kapabilitas pembuatan musik bersama. Jika dihilangkan, music_generate masih dapat menyimpulkan default penyedia yang didukung autentikasi. Ini mencoba penyedia default saat ini terlebih dahulu, lalu penyedia pembuatan musik terdaftar lainnya dalam urutan ID penyedia. Jika Anda menetapkan penyedia/model tertentu, konfigurasikan juga autentikasi/kunci API penyedia tersebut.
    • agents.defaults.videoGenerationModel digunakan oleh kapabilitas pembuatan video bersama. Jika dihilangkan, video_generate masih dapat menyimpulkan default penyedia yang didukung autentikasi. Ini mencoba penyedia default saat ini terlebih dahulu, lalu penyedia pembuatan video terdaftar lainnya dalam urutan ID penyedia. Jika Anda menetapkan penyedia/model tertentu, konfigurasikan juga autentikasi/kunci API penyedia tersebut.
    • Default per agen dapat menimpa agents.defaults.model melalui agents.list[].model ditambah binding (lihat Perutean multi-agen).

    Sumber pemilihan dan perilaku fallback

    provider/model yang sama dapat berarti hal berbeda tergantung asalnya:

    • Default yang dikonfigurasi (agents.defaults.model.primary dan model utama khusus agen) adalah titik awal normal dan menggunakan agents.defaults.model.fallbacks.
    • Pilihan fallback otomatis adalah status pemulihan sementara. Pilihan tersebut disimpan dengan modelOverrideSource: "auto" sehingga giliran berikutnya dapat terus menggunakan rantai fallback tanpa menguji model utama yang diketahui bermasalah terlebih dahulu.
    • Pilihan sesi pengguna bersifat eksak. /model, pemilih model, session_status(model=...), dan sessions.patch menyimpan modelOverrideSource: "user"; jika penyedia/model yang dipilih tidak dapat dijangkau, OpenClaw gagal secara terlihat alih-alih jatuh ke model lain yang dikonfigurasi.
    • Cron --model / payload model adalah model utama per pekerjaan. Ini tetap menggunakan fallback yang dikonfigurasi kecuali pekerjaan menyediakan payload fallbacks eksplisit (gunakan fallbacks: [] untuk proses cron yang ketat).
    • CLI default-model dan pemilih allowlist menghormati models.mode: "replace" dengan mencantumkan models.providers.*.models eksplisit alih-alih memuat katalog bawaan lengkap.
    • Pemilih model Control UI meminta Gateway untuk tampilan model yang dikonfigurasi: agents.defaults.models jika ada, jika tidak models.providers.*.models eksplisit ditambah penyedia dengan autentikasi yang dapat digunakan. Katalog bawaan lengkap dicadangkan untuk tampilan jelajah eksplisit seperti models.list dengan view: "all" atau openclaw models list --all.

    Kebijakan model singkat

    • Atur model utama Anda ke model generasi terbaru terkuat yang tersedia untuk Anda.
    • Gunakan fallback untuk tugas yang sensitif biaya/latensi dan obrolan berisiko lebih rendah.
    • Untuk agen yang mengaktifkan alat atau input yang tidak tepercaya, hindari tingkat model yang lebih lama/lebih lemah.

    Onboarding (direkomendasikan)

    Jika Anda tidak ingin mengedit konfigurasi secara manual, jalankan onboarding:

    openclaw onboard

    Ini dapat menyiapkan model + autentikasi untuk penyedia umum, termasuk langganan OpenAI Code (Codex) (OAuth) dan Anthropic (kunci API atau Claude CLI).

    Kunci konfigurasi (ikhtisar)

    • agents.defaults.model.primary dan agents.defaults.model.fallbacks
    • agents.defaults.imageModel.primary dan agents.defaults.imageModel.fallbacks
    • agents.defaults.pdfModel.primary dan agents.defaults.pdfModel.fallbacks
    • agents.defaults.imageGenerationModel.primary dan agents.defaults.imageGenerationModel.fallbacks
    • agents.defaults.videoGenerationModel.primary dan agents.defaults.videoGenerationModel.fallbacks
    • agents.defaults.models (allowlist + alias + parameter penyedia)
    • models.providers (penyedia kustom yang ditulis ke models.json)

    Edit allowlist yang aman

    Gunakan penulisan aditif saat memperbarui agents.defaults.models secara manual:

    openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
    Aturan perlindungan penimpaan

    openclaw config set melindungi peta model/penyedia dari penimpaan tidak disengaja. Penetapan objek biasa ke agents.defaults.models, models.providers, atau models.providers.<id>.models ditolak jika akan menghapus entri yang sudah ada. Gunakan --merge untuk perubahan aditif; gunakan --replace hanya ketika nilai yang diberikan harus menjadi nilai target lengkap.

    Penyiapan penyedia interaktif dan openclaw configure --section model juga menggabungkan pilihan yang dicakup penyedia ke allowlist yang sudah ada, sehingga menambahkan Codex, Ollama, atau penyedia lain tidak menghapus entri model yang tidak terkait. Configure mempertahankan agents.defaults.model.primary yang sudah ada ketika autentikasi penyedia diterapkan ulang. Perintah penetapan default eksplisit seperti openclaw models auth login --provider <id> --set-default dan openclaw models set <model> tetap mengganti agents.defaults.model.primary.

    "Model tidak diizinkan" (dan mengapa balasan berhenti)

    Jika agents.defaults.models ditetapkan, itu menjadi allowlist untuk /model dan untuk penimpaan sesi. Ketika pengguna memilih model yang tidak ada dalam allowlist tersebut, OpenClaw mengembalikan:

    Model "provider/model" is not allowed. Use /models to list providers, or /models <provider> to list models.
Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge

    Ketika perintah yang ditolak menyertakan penimpaan runtime seperti /model openai/gpt-5.5 --runtime codex, perbaiki allowlist terlebih dahulu, lalu coba lagi perintah /model ... --runtime ... yang sama. Untuk eksekusi Codex native, model yang dipilih tetap openai/gpt-5.5; runtime codex memilih harness dan menggunakan autentikasi Codex secara terpisah.

    Untuk model lokal/GGUF, simpan ref lengkap berprefiks penyedia dalam allowlist, misalnya ollama/gemma4:26b, lmstudio/Gemma4-26b-a4-it-gguf, atau penyedia/model persis yang ditampilkan oleh openclaw models list --provider <provider>. Nama file lokal polos atau nama tampilan tidak cukup ketika allowlist aktif.

    Contoh konfigurasi allowlist:

    {
  agent: {
    model: { primary: "anthropic/claude-sonnet-4-6" },
    models: {
      "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
      "anthropic/claude-opus-4-6": { alias: "Opus" },
    },
  },
}

    Beralih model di obrolan (/model)

    Anda dapat beralih model untuk sesi saat ini tanpa memulai ulang:

    /model
/model list
/model 3
/model openai/gpt-5.4
/model status
    Perilaku pemilih
    • /model (dan /model list) adalah pemilih ringkas bernomor (keluarga model + penyedia yang tersedia).
    • Di Discord, /model dan /models membuka pemilih interaktif dengan dropdown penyedia dan model ditambah langkah Kirim.
    • Di Telegram, pilihan pemilih /models dicakup ke sesi; pilihan tersebut tidak mengubah default persisten agen di openclaw.json.
    • /models add sudah tidak digunakan lagi dan sekarang mengembalikan pesan penghentian penggunaan alih-alih mendaftarkan model dari obrolan.
    • /model <#> memilih dari pemilih tersebut.
    Persistensi dan peralihan langsung
    • /model mempertahankan pilihan sesi baru segera.
    • Jika agen sedang idle, proses berikutnya langsung menggunakan model baru.
    • Jika proses sudah aktif, OpenClaw menandai peralihan langsung sebagai tertunda dan hanya memulai ulang ke model baru pada titik percobaan ulang yang bersih.
    • Jika aktivitas alat atau output balasan sudah dimulai, peralihan tertunda dapat tetap mengantre hingga peluang percobaan ulang berikutnya atau giliran pengguna berikutnya.
    • Ref /model yang dipilih pengguna bersifat ketat untuk sesi tersebut: jika penyedia/model yang dipilih tidak dapat dijangkau, balasan gagal secara terlihat alih-alih diam-diam menjawab dari agents.defaults.model.fallbacks. Ini berbeda dari default yang dikonfigurasi dan model utama pekerjaan cron, yang masih dapat menggunakan rantai fallback.
    • /model status adalah tampilan terperinci (kandidat autentikasi dan, jika dikonfigurasi, endpoint penyedia baseUrl + mode api).
    Penguraian ref
    • Ref model diurai dengan memisahkan pada / pertama. Gunakan provider/model saat mengetik /model <ref>.
    • Jika ID model itu sendiri berisi / (gaya OpenRouter), Anda harus menyertakan prefiks penyedia (contoh: /model openrouter/moonshotai/kimi-k2).
    • Jika Anda menghilangkan penyedia, OpenClaw menyelesaikan input dalam urutan ini:
      1. kecocokan alias
      2. kecocokan penyedia-terkonfigurasi unik untuk ID model tanpa prefiks yang persis itu
      3. fallback lama ke penyedia default yang dikonfigurasi — jika penyedia tersebut tidak lagi mengekspos model default yang dikonfigurasi, OpenClaw sebagai gantinya kembali ke penyedia/model terkonfigurasi pertama untuk menghindari menampilkan default penyedia lama yang sudah dihapus.

    Perilaku/konfigurasi perintah lengkap: Perintah slash.

    Perintah CLI

    openclaw models list
openclaw models status
openclaw models set <provider/model>
openclaw models set-image <provider/model>

openclaw models aliases list
openclaw models aliases add <alias> <provider/model>
openclaw models aliases remove <alias>

openclaw models fallbacks list
openclaw models fallbacks add <provider/model>
openclaw models fallbacks remove <provider/model>
openclaw models fallbacks clear

openclaw models image-fallbacks list
openclaw models image-fallbacks add <provider/model>
openclaw models image-fallbacks remove <provider/model>
openclaw models image-fallbacks clear

    openclaw models (tanpa subperintah) adalah pintasan untuk models status.

    models list

    Menampilkan model yang dikonfigurasi/tersedia-auth secara default. Flag yang berguna:

    --allboolean

    Katalog lengkap. Menyertakan baris katalog statis bawaan milik penyedia sebelum auth dikonfigurasi, sehingga tampilan khusus penemuan dapat menampilkan model yang tidak tersedia sampai Anda menambahkan kredensial penyedia yang sesuai.

    --localboolean

    Hanya penyedia lokal.

    OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcHJvdmlkZXIgPGlk " type="string"> Filter berdasarkan id penyedia, misalnya moonshot. Label tampilan dari pemilih interaktif tidak diterima.

    --plainboolean

    Satu model per baris.

    --jsonboolean

    Output yang dapat dibaca mesin.

    models status

    Menampilkan model primer yang diselesaikan, fallback, model gambar, dan ikhtisar auth dari penyedia yang dikonfigurasi. Ini juga menampilkan status kedaluwarsa OAuth untuk profil yang ditemukan di penyimpanan auth (memperingatkan dalam 24 jam secara default). --plain hanya mencetak model primer yang diselesaikan.

    Perilaku auth dan probe
    • Status OAuth selalu ditampilkan (dan disertakan dalam output --json). Jika penyedia yang dikonfigurasi tidak memiliki kredensial, models status mencetak bagian Auth hilang.
    • JSON menyertakan auth.oauth (jendela peringatan + profil) dan auth.providers (auth efektif per penyedia, termasuk kredensial berbasis env). auth.oauth hanya kesehatan profil penyimpanan-auth; penyedia khusus env tidak muncul di sana.
    • Gunakan --check untuk otomatisasi (exit 1 saat hilang/kedaluwarsa, 2 saat akan kedaluwarsa).
    • Gunakan --probe untuk pemeriksaan auth langsung; baris probe dapat berasal dari profil auth, kredensial env, atau models.json.
    • Jika auth.order.<provider> eksplisit menghilangkan profil tersimpan, probe melaporkan excluded_by_auth_order alih-alih mencobanya. Jika auth ada tetapi tidak ada model yang dapat diprobe yang bisa diselesaikan untuk penyedia tersebut, probe melaporkan status: no_model.

    Contoh (Claude CLI):

    claude auth login
openclaw models status

    Pemindaian (model gratis OpenRouter)

    openclaw models scan memeriksa katalog model gratis OpenRouter dan dapat secara opsional memprobe model untuk dukungan alat dan gambar.

    --no-probeboolean

    Lewati probe langsung (hanya metadata).

    "--min-params
    "--max-age-days
    "--provider
    "--max-candidates
    --set-defaultboolean

    Tetapkan agents.defaults.model.primary ke pilihan pertama.

    --set-imageboolean

    Tetapkan agents.defaults.imageModel.primary ke pilihan gambar pertama.

    Hasil pemindaian diperingkat berdasarkan:

    1. Dukungan gambar
    2. Latensi alat
    3. Ukuran konteks
    4. Jumlah parameter

    Input:

    • Daftar /models OpenRouter (filter :free)
    • Probe langsung memerlukan kunci API OpenRouter dari profil auth atau OPENROUTER_API_KEY (lihat Variabel lingkungan)
    • Filter opsional: --max-age-days, --min-params, --provider, --max-candidates
    • Kontrol permintaan/probe: --timeout, --concurrency

    Saat probe langsung berjalan di TUI, Anda dapat memilih fallback secara interaktif. Dalam mode non-interaktif, berikan --yes untuk menerima default. Hasil hanya metadata bersifat informatif; --set-default dan --set-image memerlukan probe langsung agar OpenClaw tidak mengonfigurasi model OpenRouter tanpa kunci yang tidak dapat digunakan.

    Registry model (models.json)

    Penyedia kustom di models.providers ditulis ke models.json di bawah direktori agen (default ~/.openclaw/agents/<agentId>/agent/models.json). File ini digabungkan secara default kecuali models.mode diatur ke replace.

    Prioritas mode penggabungan

    Prioritas mode penggabungan untuk ID penyedia yang cocok:

    • baseUrl tidak kosong yang sudah ada di models.json agen menang.
    • apiKey tidak kosong di models.json agen hanya menang saat penyedia tersebut tidak dikelola SecretRef dalam konteks konfigurasi/profil-auth saat ini.
    • Nilai apiKey penyedia yang dikelola SecretRef disegarkan dari penanda sumber (ENV_VAR_NAME untuk referensi env, secretref-managed untuk referensi file/exec), bukan mempertahankan rahasia yang sudah diselesaikan.
    • Nilai header penyedia yang dikelola SecretRef disegarkan dari penanda sumber (secretref-env:ENV_VAR_NAME untuk referensi env, secretref-managed untuk referensi file/exec).
    • apiKey/baseUrl agen yang kosong atau hilang kembali ke konfigurasi models.providers.
    • Field penyedia lainnya disegarkan dari konfigurasi dan data katalog yang dinormalisasi.

    Terkait