FAQ: model dan autentikasi

Atur dengan:

agents.defaults.model.primary

Model adalah ref provider/model (contoh: openai/gpt-5.5, anthropic/claude-sonnet-4-6). Selalu atur provider/model secara eksplisit. Jika penyedia tidak dicantumkan, OpenClaw terlebih dahulu mencoba pencocokan alias, lalu pencocokan penyedia terkonfigurasi yang unik untuk id model tersebut, kemudian beralih ke penyedia default terkonfigurasi (jalur kompatibilitas yang tidak digunakan lagi). Jika penyedia tersebut tidak lagi memiliki model default yang dikonfigurasi, OpenClaw akan beralih ke penyedia/model terkonfigurasi pertama, bukan menggunakan default yang sudah usang.

Gunakan model generasi terbaru terkuat yang ditawarkan tumpukan penyedia Anda, terutama untuk agen yang mengaktifkan alat atau menerima masukan yang tidak tepercaya — model yang lebih lemah atau dikuantisasi secara berlebihan lebih rentan terhadap injeksi prompt dan perilaku tidak aman (lihat Keamanan). Arahkan model yang lebih murah ke percakapan rutin/berisiko rendah berdasarkan peran agen.

Arahkan model per agen dan gunakan subagen untuk memparalelkan tugas panjang (setiap subagen menggunakan tokennya sendiri). Lihat Model, Subagen, MiniMax, dan Model lokal.

Ubah hanya bidang model — hindari mengganti seluruh konfigurasi.

• /model dalam percakapan (per sesi, lihat Perintah garis miring)
• openclaw models set ... (hanya memperbarui konfigurasi model)
• openclaw configure --section model (interaktif)
• edit agents.defaults.model dalam ~/.openclaw/openclaw.json secara langsung

Untuk pengeditan RPC, periksa terlebih dahulu dengan config.schema.lookup (jalur yang dinormalisasi, dokumentasi skema ringkas, ringkasan turunan), lalu utamakan config.patch daripada config.apply dengan objek parsial. Jika konfigurasi sudah tertimpa, pulihkan dari cadangan atau jalankan openclaw doctor untuk memperbaikinya.

Dokumentasi: Model, Konfigurasi, Konfigurasi, Doctor.

Ya — Ollama adalah jalur termudah. Penyiapan cepat:

1. Instal Ollama dari https://ollama.com/download
2. Tarik model lokal, misalnya ollama pull gemma4
3. Untuk model cloud juga, jalankan ollama signin
4. Jalankan openclaw onboard, pilih Ollama, lalu Local atau Cloud + Local

Cloud + Local memberi Anda model cloud beserta model Ollama lokal; model cloud seperti kimi-k2.5:cloud tidak perlu ditarik secara lokal. Untuk beralih secara manual: openclaw models list, lalu openclaw models set ollama/<model>.

Model yang lebih kecil/sangat terkuantisasi lebih rentan terhadap injeksi prompt. Gunakan model besar untuk bot apa pun yang memiliki akses alat; jika tetap menggunakan model kecil, aktifkan sandbox dan daftar izin alat yang ketat.

Dokumentasi: Ollama, Model lokal, Penyedia model, Keamanan, Sandbox.

Kirim /model <name> sebagai pesan tersendiri. Lihat Perintah garis miring untuk daftar perintah lengkap, termasuk pemilih bernomor (/model, /model list, /model 3), /model default untuk menghapus penggantian sesi, dan /model status untuk detail titik akhir/mode API.

Paksa profil autentikasi tertentu per sesi dengan @profile:

/model opus@anthropic:default/model opus@anthropic:work

Untuk melepaskan penyematan profil yang diatur dengan @profile, jalankan ulang /model tanpa sufiks (misalnya /model anthropic/claude-opus-4-6), atau pilih default dari /model. Gunakan /model status untuk mengonfirmasi profil autentikasi aktif.

/model provider/model memilih rute penyedia tersebut secara persis. Misalnya, qianfan/deepseek-v4-flash dan deepseek/deepseek-v4-flash adalah ref yang berbeda meskipun id modelnya cocok — OpenClaw tidak secara diam-diam beralih penyedia hanya berdasarkan kecocokan id.

Ref /model yang dipilih pengguna bersifat ketat untuk fallback: jika penyedia/model tersebut tidak tersedia, balasan akan gagal secara terlihat alih-alih beralih ke agents.defaults.model.fallbacks. Rantai fallback yang dikonfigurasi tetap berlaku untuk default terkonfigurasi, model utama tugas cron, dan status fallback yang dipilih secara otomatis. Ketika proses tanpa penggantian sesi diizinkan menggunakan fallback, OpenClaw terlebih dahulu mencoba penyedia/model yang diminta, kemudian fallback yang dikonfigurasi, lalu model utama terkonfigurasi — sehingga id model polos yang duplikat tidak pernah langsung kembali ke penyedia default.

Lihat Model dan Failover model.

Ya — pilihan model dan pilihan runtime adalah hal yang terpisah:

• Agen pemrograman Codex native: atur agents.defaults.model.primary ke openai/gpt-5.5. Masuk dengan openclaw models auth login --provider openai untuk autentikasi langganan ChatGPT/Codex.
• Tugas OpenAI API langsung di luar loop agen: konfigurasikan OPENAI_API_KEY untuk gambar, penyematan, ucapan, waktu nyata, dan permukaan OpenAI API nonagen lainnya.
• Autentikasi kunci API agen OpenAI: /model openai/gpt-5.5 dengan profil kunci API openai yang terurut.
• Subagen: arahkan tugas pemrograman ke agen yang berfokus pada Codex dengan model openai/gpt-5.5 miliknya sendiri.

Lihat Model dan Perintah garis miring.

• Per sesi: kirim /fast on saat menggunakan openai/gpt-5.5.
• Default per model: atur agents.defaults.models["openai/gpt-5.5"].params.fastMode ke true.
• Batas otomatis: /fast auto atau params.fastMode: "auto" menjalankan panggilan model baru dengan cepat hingga batas tercapai, kemudian menjalankan percobaan ulang, fallback, hasil alat, atau panggilan lanjutan berikutnya tanpa mode cepat. Batas defaultnya adalah 60 detik; ganti dengan params.fastAutoOnSeconds pada model.

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": {          params: {            fastMode: "auto",            fastAutoOnSeconds: 30,          },        },      },    },  },}

Mode cepat dipetakan ke service_tier = "priority" pada permintaan OpenAI Responses native; nilai service_tier yang ada dipertahankan dan mode cepat tidak menulis ulang reasoning atau text.verbosity. Penggantian /fast sesi mengungguli default konfigurasi.

Lihat Pemikiran dan mode cepat serta bagian Mode cepat di bawah Konfigurasi lanjutan pada halaman penyedia OpenAI.

Jika agents.defaults.modelPolicy.allow tidak kosong, nilai tersebut menjadi daftar izin untuk /model, penggantian sesi, dan --model. Memilih model di luar daftar tersebut akan mengembalikan pesan berikut, bukan balasan biasa:

Penggantian model "provider/model" tidak diizinkan oleh agents.defaults.modelPolicy.allow.

Perbaikan: tambahkan model yang tepat atau wildcard penyedia seperti "provider/*" ke daftar modelPolicy.allow yang disebutkan, hapus/kosongkan daftar tersebut, atau pilih model dari /model list. Jika perintah juga menyertakan --runtime codex, perbarui daftar izin terlebih dahulu, lalu coba kembali perintah /model provider/model --runtime codex yang sama.

Jika Anda menggunakan rilis OpenClaw yang lebih lama, tingkatkan terlebih dahulu (atau jalankan dari sumber main) dan mulai ulang gateway — MiniMax-M3 mungkin belum tercantum dalam katalog rilis yang terinstal. Jika tidak, penyedia MiniMax belum dikonfigurasi (entri penyedia atau profil autentikasi tidak ditemukan), sehingga model tidak dapat diresolusikan. Lihat bagian Pemecahan Masalah pada halaman penyedia MiniMax untuk daftar periksa perbaikan lengkap, tabel id penyedia/model, dan contoh blok konfigurasi.

Ya. Gunakan MiniMax sebagai default dan alihkan model per sesi — fallback ditujukan untuk kesalahan, bukan "tugas sulit", jadi gunakan /model atau agen terpisah.

Opsi A: beralih per sesi

{  env: { MINIMAX_API_KEY: "sk-...", OPENAI_API_KEY: "sk-..." },  agents: {    defaults: {      model: { primary: "minimax/MiniMax-M3" },      models: {        "minimax/MiniMax-M3": { alias: "minimax" },        "openai/gpt-5.5": { alias: "gpt" },      },    },  },}

Kemudian /model gpt.

Opsi B: agen terpisah — Agen A menggunakan MiniMax secara default, Agen B menggunakan OpenAI secara default; arahkan berdasarkan agen atau gunakan /agent untuk beralih.

Dokumentasi: Model, Perutean Multiagen, MiniMax, OpenAI.

Ya — singkatan bawaan, yang hanya diterapkan ketika model target tersedia di agents.defaults.models:

Alias Anda sendiri dengan nama yang sama akan menggantikan alias bawaan.

Alias berada di agents.defaults.models.<modelId>.alias:

{  agents: {    defaults: {      model: { primary: "anthropic/claude-opus-4-6" },      models: {        "anthropic/claude-opus-4-6": { alias: "opus" },        "anthropic/claude-sonnet-4-6": { alias: "sonnet" },      },    },  },}

Kemudian /model sonnet (atau /<alias> jika didukung) diresolusikan ke id model tersebut.

OpenRouter (bayar per token; banyak model):

{  agents: {    defaults: {      model: { primary: "openrouter/anthropic/claude-sonnet-4-6" },      models: { "openrouter/anthropic/claude-sonnet-4-6": {} },    },  },  env: { OPENROUTER_API_KEY: "sk-or-..." },}

Z.AI (model GLM):

{  agents: {    defaults: {      model: { primary: "zai/glm-5.1" },      models: { "zai/glm-5.1": {} },    },  },  env: { ZAI_API_KEY: "..." },}

Kunci penyedia yang tidak tersedia untuk penyedia/model yang dirujuk akan memicu kesalahan autentikasi runtime (misalnya No API key found for provider "zai").

Kunci API untuk penyedia tidak ditemukan setelah menambahkan agen baru

Agen baru memiliki penyimpanan autentikasi kosong — autentikasi disimpan per agen di:

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Perbaikan: jalankan openclaw agents add <id> dan konfigurasikan autentikasi dalam wizard, atau salin hanya profil statis portabel api_key/token dari penyimpanan agen utama. Untuk OAuth, masuk dari agen baru saat agen tersebut memerlukan akunnya sendiri. Lihat Perutean Multi-Agen untuk aturan lengkap penggunaan kembali agentDir dan berbagi kredensial — jangan pernah menggunakan kembali agentDir di antara agen.

Dua tahap:

1. Rotasi profil autentikasi dalam penyedia yang sama.
2. Fallback model ke model berikutnya dalam agents.defaults.model.fallbacks.

Masa cooldown diterapkan pada profil yang gagal (backoff eksponensial), sehingga OpenClaw tetap merespons saat penyedia terkena pembatasan laju atau mengalami kegagalan sementara.

Kelompok pembatasan laju mencakup lebih dari sekadar 429: Too many concurrent requests, ThrottlingException, concurrency limit reached, workers_ai ... quota limit exceeded, resource exhausted, dan batas jendela penggunaan berkala (weekly/monthly limit reached) semuanya dianggap sebagai pembatasan laju yang layak memicu failover.

Respons penagihan tidak selalu berupa 402, dan beberapa 402 tetap berada dalam kelompok sementara/pembatasan laju, bukan jalur penagihan. Teks penagihan eksplisit pada 401/403 masih dapat diarahkan ke penagihan; pencocok teks khusus penyedia (misalnya Key limit exceeded OpenRouter) tetap terbatas pada penyedianya sendiri. 402 yang tampak seperti jendela penggunaan yang dapat dicoba ulang atau batas pengeluaran organisasi/ruang kerja (daily limit reached, resets tomorrow, organization spending limit exceeded) diperlakukan sebagai rate_limit, bukan penonaktifan lama akibat penagihan.

Error luapan konteks sepenuhnya tidak masuk jalur fallback — ciri seperti request_too_large, input exceeds the maximum number of tokens, input token count exceeds the maximum number of input tokens, input is too long for the model, atau ollama error: context length exceeded diarahkan ke compaction/percobaan ulang, bukan melanjutkan fallback model.

Teks error server generik memiliki cakupan yang lebih sempit daripada "apa pun yang memuat unknown/error di dalamnya". Bentuk sementara yang terbatas pada penyedia dan dianggap sebagai sinyal failover: An unknown error occurred polos dari Anthropic, Provider returned error polos dari OpenRouter, error alasan berhenti seperti Unhandled stop reason: error, payload JSON api_error dengan teks server sementara (internal server error, unknown error, 520, upstream error, backend error), dan error penyedia sibuk seperti ModelNotReadyException saat konteks penyedia cocok. Teks fallback internal generik seperti LLM request failed with an unknown error. tetap diperlakukan secara konservatif dan tidak memicu fallback dengan sendirinya.

ID profil autentikasi anthropic:default tidak memiliki kredensial dalam penyimpanan autentikasi yang diharapkan.

Daftar periksa perbaikan:

• Konfirmasikan lokasi profil — saat ini: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json; lama: ~/.openclaw/agent/* (dimigrasikan oleh openclaw doctor).
• Konfirmasikan bahwa Gateway memuat variabel lingkungan Anda. ANTHROPIC_API_KEY yang hanya ditetapkan dalam shell Anda tidak akan diteruskan ke Gateway yang dijalankan melalui systemd/launchd — masukkan ke ~/.openclaw/.env atau aktifkan env.shellEnv.
• Konfirmasikan bahwa Anda mengedit agen yang benar — penyiapan multi-agen memiliki beberapa file auth-profiles.json.
• Jalankan openclaw models status untuk melihat model yang dikonfigurasi dan status autentikasi penyedia.

Untuk "Tidak ditemukan kredensial untuk profil anthropic" (tanpa akhiran email):

Proses dijepit ke profil Anthropic yang tidak dapat ditemukan oleh Gateway.

• Gunakan Claude CLI: jalankan openclaw models auth login --provider anthropic --method cli --set-default pada host gateway.

• Jika lebih memilih kunci API: masukkan ANTHROPIC_API_KEY ke ~/.openclaw/.env pada host gateway, lalu hapus urutan tersemat yang memaksa penggunaan profil yang tidak ditemukan:

  openclaw models auth order clear --provider anthropic

• Mode jarak jauh: profil autentikasi berada di mesin gateway, bukan di laptop Anda — konfirmasikan bahwa Anda menjalankan perintah di sana.

Jika konfigurasi model Anda menyertakan Google Gemini sebagai fallback (atau Anda beralih ke singkatan Gemini), OpenClaw akan mencobanya selama fallback. Tidak adanya kredensial Google yang dikonfigurasi menghasilkan No API key found for provider "google". Perbaikan: tambahkan autentikasi Google, atau hapus model Google dari agents.defaults.model.fallbacks/alias.

Permintaan LLM ditolak: tanda tangan pemikiran diperlukan (Google Antigravity)

Penyebab: riwayat sesi memiliki blok pemikiran tanpa tanda tangan (sering kali berasal dari stream yang dibatalkan/tidak lengkap); Google Antigravity mengharuskan tanda tangan pada blok pemikiran. OpenClaw menghapus blok pemikiran tanpa tanda tangan untuk Google Antigravity Claude; jika masih muncul, mulai sesi baru atau tetapkan /thinking off untuk agen tersebut.

Catatan kredensial bernama (OAuth atau kunci API) yang terkait dengan penyedia, disimpan di:

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Periksa profil yang tersimpan tanpa menampilkan rahasia: openclaw models auth list (opsional --provider <id> atau --json). Lihat CLI Model.

Diawali nama penyedia: anthropic:default (umum saat tidak ada identitas email), anthropic:<email> untuk identitas OAuth, atau ID khusus yang Anda pilih (misalnya anthropic:work).

Ya. Konfigurasi auth.order.<provider> menetapkan urutan rotasi per penyedia (hanya metadata — tidak ada rahasia yang disimpan).

OpenClaw mungkin melewati profil yang berada dalam cooldown singkat (pembatasan laju, batas waktu, kegagalan autentikasi) atau status dinonaktifkan yang lebih lama (penagihan/kredit tidak mencukupi). Periksa dengan openclaw models status --json dan periksa auth.unusableProfiles. Cooldown pembatasan laju dapat terbatas pada model — profil yang sedang dalam cooldown untuk satu model masih dapat melayani model lain pada penyedia yang sama; jendela penagihan/penonaktifan memblokir seluruh profil.

Tetapkan penggantian urutan per agen (disimpan dalam auth-state.json milik agen tersebut):

# Defaultnya adalah agen default yang dikonfigurasi (hilangkan --agent)openclaw models auth order get --provider anthropic # Kunci rotasi ke satu profilopenclaw models auth order set --provider anthropic anthropic:default # Atau tetapkan urutan eksplisit (fallback dalam penyedia)openclaw models auth order set --provider anthropic anthropic:work anthropic:default # Hapus penggantian (kembali ke auth.order konfigurasi / round-robin)openclaw models auth order clear --provider anthropic # Targetkan agen tertentuopenclaw models auth order set --provider anthropic --agent main anthropic:default

Verifikasi apa yang benar-benar akan dicoba: openclaw models status --probe. Profil tersimpan yang tidak disertakan dalam urutan eksplisit akan melaporkan excluded_by_auth_order, bukan dicoba secara diam-diam.

• Login OAuth / CLI sering kali menggunakan akses langganan jika didukung oleh penyedia. Untuk Anthropic, backend Claude CLI OpenClaw menggunakan claude -p Claude Code, yang saat ini diperlakukan Anthropic sebagai penggunaan Agent SDK/terprogram yang mengambil dari batas penggunaan langganan — lihat Anthropic untuk status jeda penagihan terkini dan tautan sumber.
• Kunci API menggunakan penagihan per token.

Wizard mendukung Anthropic Claude CLI, OAuth OpenAI Codex, dan kunci API.