Langsung ke konten utama

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

T&J model dan profil autentikasi. Untuk penyiapan, sesi, gateway, channel, dan pemecahan masalah, lihat FAQ utama.

​
Model: default, pemilihan, alias, pengalihan

Model default OpenClaw adalah apa pun yang Anda tetapkan sebagai:
agents.defaults.model.primary
Model dirujuk sebagai provider/model (contoh: openai/gpt-5.5 atau anthropic/claude-sonnet-4-6). Jika Anda menghilangkan penyedia, OpenClaw pertama-tama mencoba alias, lalu kecocokan penyedia-terkonfigurasi unik untuk id model persis tersebut, dan baru kemudian kembali ke penyedia default yang dikonfigurasi sebagai jalur kompatibilitas yang sudah usang. Jika penyedia tersebut tidak lagi mengekspos model default yang dikonfigurasi, OpenClaw kembali ke penyedia/model terkonfigurasi pertama alih-alih menampilkan default penyedia-terhapus yang basi. Anda tetap sebaiknya menetapkan provider/model secara eksplisit.
Default yang direkomendasikan: gunakan model generasi terbaru terkuat yang tersedia di tumpukan penyedia Anda. Untuk agen dengan alat aktif atau input tidak tepercaya: prioritaskan kekuatan model daripada biaya. Untuk chat rutin/berisiko rendah: gunakan model cadangan yang lebih murah dan rutekan berdasarkan peran agen.MiniMax memiliki dokumentasinya sendiri: MiniMax dan Model lokal.Aturan praktis: gunakan model terbaik yang mampu Anda bayar untuk pekerjaan berisiko tinggi, dan model yang lebih murah untuk chat rutin atau ringkasan. Anda dapat merutekan model per agen dan menggunakan sub-agen untuk memparalelkan tugas panjang (setiap sub-agen mengonsumsi token). Lihat Model dan Sub-agen.Peringatan keras: model yang lebih lemah/terkuantisasi berlebihan lebih rentan terhadap prompt injection dan perilaku tidak aman. Lihat Keamanan.Konteks lebih lanjut: Model.
Gunakan perintah model atau edit hanya bidang model. Hindari penggantian konfigurasi penuh.Opsi aman:
  • /model dalam chat (cepat, per sesi)
  • openclaw models set ... (hanya memperbarui konfigurasi model)
  • openclaw configure --section model (interaktif)
  • edit agents.defaults.model di ~/.openclaw/openclaw.json
Hindari config.apply dengan objek parsial kecuali Anda memang ingin mengganti seluruh konfigurasi. Untuk edit RPC, periksa dengan config.schema.lookup terlebih dahulu dan lebih utamakan config.patch. Payload lookup memberi Anda path yang dinormalisasi, dokumentasi/kendala skema dangkal, dan ringkasan turunan langsung. untuk pembaruan parsial. Jika Anda sudah menimpa konfigurasi, pulihkan dari cadangan atau jalankan ulang openclaw doctor untuk memperbaiki.Dokumentasi: Model, Konfigurasi, Config, Doctor.
Ya. Ollama adalah jalur termudah untuk model lokal.Penyiapan tercepat:
  1. Instal Ollama dari https://ollama.com/download
  2. Tarik model lokal seperti ollama pull gemma4
  3. Jika Anda juga menginginkan model cloud, jalankan ollama signin
  4. Jalankan openclaw onboard dan pilih Ollama
  5. Pilih Local atau Cloud + Local
Catatan:
  • Cloud + Local memberi Anda model cloud plus model Ollama lokal Anda
  • model cloud seperti kimi-k2.5:cloud tidak memerlukan penarikan lokal
  • untuk pengalihan manual, gunakan openclaw models list dan openclaw models set ollama/<model>
Catatan keamanan: model yang lebih kecil atau sangat terkuantisasi lebih rentan terhadap prompt injection. Kami sangat merekomendasikan model besar untuk bot apa pun yang dapat menggunakan alat. Jika Anda tetap menginginkan model kecil, aktifkan sandboxing dan allowlist alat yang ketat.Dokumentasi: Ollama, Model lokal, Penyedia model, Keamanan, Sandboxing.
  • Deployment ini dapat berbeda dan dapat berubah seiring waktu; tidak ada rekomendasi penyedia tetap.
  • Periksa pengaturan runtime saat ini pada setiap Gateway dengan openclaw models status.
  • Untuk agen yang sensitif terhadap keamanan/mengaktifkan alat, gunakan model generasi terbaru terkuat yang tersedia.
Gunakan perintah /model sebagai pesan mandiri:
/model sonnet
/model opus
/model gpt
/model gpt-mini
/model gemini
/model gemini-flash
/model gemini-flash-lite
Ini adalah alias bawaan. Alias khusus dapat ditambahkan melalui agents.defaults.models.Anda dapat mencantumkan model yang tersedia dengan /model, /model list, atau /model status./model (dan /model list) menampilkan pemilih ringkas bernomor. Pilih berdasarkan nomor:
/model 3
Anda juga dapat memaksa profil autentikasi tertentu untuk penyedia (per sesi):
/model opus@anthropic:default
/model opus@anthropic:work
Tips: /model status menampilkan agen mana yang aktif, file auth-profiles.json mana yang digunakan, dan profil autentikasi mana yang akan dicoba berikutnya. Ini juga menampilkan endpoint penyedia yang dikonfigurasi (baseUrl) dan mode API (api) jika tersedia.Bagaimana cara melepas pin profil yang saya tetapkan dengan @profile?Jalankan ulang /model tanpa sufiks @profile:
/model anthropic/claude-opus-4-6
Jika Anda ingin kembali ke default, pilih dari /model (atau kirim /model <default provider/model>). Gunakan /model status untuk mengonfirmasi profil autentikasi mana yang aktif.
/model provider/model memilih rute penyedia persis tersebut untuk sesi.Misalnya, qianfan/deepseek-v4-flash dan deepseek/deepseek-v4-flash adalah ref model yang berbeda meskipun keduanya berisi deepseek-v4-flash. OpenClaw tidak boleh diam-diam berpindah dari satu penyedia ke penyedia lain hanya karena id model polosnya cocok.Ref /model yang dipilih pengguna juga ketat untuk kebijakan fallback. Jika penyedia/model yang dipilih tersebut tidak tersedia, balasan gagal secara terlihat alih-alih menjawab dari agents.defaults.model.fallbacks. Rantai fallback yang dikonfigurasi tetap berlaku untuk default yang dikonfigurasi, primer tugas Cron, dan status fallback yang dipilih otomatis.Jika run yang dimulai dari override non-sesi diizinkan menggunakan fallback, OpenClaw mencoba penyedia/model yang diminta terlebih dahulu, lalu fallback yang dikonfigurasi, dan baru kemudian primary yang dikonfigurasi. Ini mencegah id model polos duplikat langsung melompat kembali ke penyedia default.Lihat Model dan Failover model.
Ya. Perlakukan pilihan model dan pilihan runtime secara terpisah:
  • Agen coding Codex native: tetapkan agents.defaults.model.primary ke openai/gpt-5.5. Masuk dengan openclaw models auth login --provider openai-codex saat Anda ingin autentikasi langganan ChatGPT/Codex.
  • Tugas OpenAI API langsung di luar loop agen: konfigurasikan OPENAI_API_KEY untuk gambar, embedding, ucapan, realtime, dan surface OpenAI API non-agen lainnya.
  • Autentikasi kunci API agen OpenAI: gunakan /model openai/gpt-5.5 dengan profil kunci API openai-codex yang berurutan.
  • Sub-agen: rutekan tugas coding ke agen yang berfokus pada Codex dengan model openai/gpt-5.5 miliknya sendiri.
Lihat Model dan Perintah slash.
Gunakan toggle sesi atau default konfigurasi:
  • Per sesi: kirim /fast on saat sesi menggunakan openai/gpt-5.5.
  • Default per model: tetapkan agents.defaults.models["openai/gpt-5.5"].params.fastMode ke true.
Contoh:
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          params: {
            fastMode: true,
          },
        },
      },
    },
  },
}
Untuk OpenAI, mode cepat dipetakan ke service_tier = "priority" pada permintaan Responses native yang didukung. Override /fast sesi mengalahkan default konfigurasi.Lihat Thinking dan mode cepat dan Mode cepat OpenAI.
Jika agents.defaults.models ditetapkan, itu menjadi allowlist untuk /model dan override sesi apa pun. Memilih model yang tidak ada dalam daftar tersebut 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
Error itu dikembalikan sebagai pengganti balasan normal. Perbaikan: tambahkan model persis ke agents.defaults.models, tambahkan wildcard penyedia seperti "provider/*": {} untuk katalog penyedia dinamis, hapus allowlist, atau pilih model dari /model list. Jika perintah juga menyertakan --runtime codex, perbarui allowlist terlebih dahulu lalu coba lagi perintah /model provider/model --runtime codex yang sama.
Ini berarti penyedia belum dikonfigurasi (tidak ditemukan konfigurasi penyedia MiniMax atau profil autentikasi), sehingga model tidak dapat di-resolve.Daftar periksa perbaikan:
  1. Tingkatkan ke rilis OpenClaw saat ini (atau jalankan dari sumber main), lalu mulai ulang Gateway.
  2. Pastikan MiniMax dikonfigurasi (wizard atau JSON), atau autentikasi MiniMax ada di env/profil autentikasi sehingga penyedia yang cocok dapat disuntikkan (MINIMAX_API_KEY untuk minimax, MINIMAX_OAUTH_TOKEN atau OAuth MiniMax tersimpan untuk minimax-portal).
  3. Gunakan id model yang persis (peka huruf besar-kecil) untuk jalur autentikasi Anda: minimax/MiniMax-M2.7 atau minimax/MiniMax-M2.7-highspeed untuk penyiapan kunci API, atau minimax-portal/MiniMax-M2.7 / minimax-portal/MiniMax-M2.7-highspeed untuk penyiapan OAuth.
  4. Jalankan: 
    openclaw models list
    dan pilih dari daftar (atau /model list dalam chat).
Lihat MiniMax dan Model.
Ya. Gunakan MiniMax sebagai default dan ganti model per sesi saat diperlukan. Fallback adalah untuk error, 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-M2.7" },
      models: {
        "minimax/MiniMax-M2.7": { alias: "minimax" },
        "openai/gpt-5.5": { alias: "gpt" },
      },
    },
  },
}
Lalu:
/model gpt
Opsi B: agen terpisah
  • Default Agen A: MiniMax
  • Default Agen B: OpenAI
  • Rutekan berdasarkan agen atau gunakan /agent untuk beralih
Dokumentasi: Model, Perutean Multi-Agen, MiniMax, OpenAI.
Ya. OpenClaw menyertakan beberapa singkatan default (hanya diterapkan saat model ada di agents.defaults.models):
  • opus → anthropic/claude-opus-4-7
  • sonnet → anthropic/claude-sonnet-4-6
  • gpt → openai/gpt-5.4
  • gpt-mini → openai/gpt-5.4-mini
  • gpt-nano → openai/gpt-5.4-nano
  • gemini → google/gemini-3.1-pro-preview
  • gemini-flash → google/gemini-3-flash-preview
  • gemini-flash-lite → google/gemini-3.1-flash-lite-preview
Jika Anda menetapkan alias sendiri dengan nama yang sama, nilai Anda yang digunakan.
Alias berasal dari agents.defaults.models.<modelId>.alias. Contoh:
{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-4-6" },
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "anthropic/claude-sonnet-4-6": { alias: "sonnet" },
        "anthropic/claude-haiku-4-5": { alias: "haiku" },
      },
    },
  },
}
Lalu /model sonnet (atau /<alias> jika didukung) akan di-resolve 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" },
      models: { "zai/glm-5": {} },
    },
  },
  env: { ZAI_API_KEY: "..." },
}
Jika Anda merujuk penyedia/model tetapi kunci penyedia yang diperlukan tidak ada, Anda akan mendapat galat autentikasi runtime (mis. No API key found for provider "zai").Tidak ada kunci API yang ditemukan untuk penyedia setelah menambahkan agen baruIni biasanya berarti agen baru memiliki penyimpanan autentikasi kosong. Autentikasi bersifat per agen dan disimpan di:
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
Opsi perbaikan:
  • Jalankan openclaw agents add <id> dan konfigurasikan autentikasi selama wizard.
  • Atau salin hanya profil api_key / token statis portabel dari penyimpanan autentikasi agen utama ke penyimpanan autentikasi agen baru.
  • Untuk profil OAuth, masuk dari agen baru ketika agen tersebut memerlukan akunnya sendiri; jika tidak, OpenClaw dapat membaca hingga agen default/utama tanpa mengkloning token refresh.
Jangan gunakan ulang agentDir lintas agen; itu menyebabkan benturan autentikasi/sesi.

​
Failover model dan “Semua model gagal”

Failover terjadi dalam dua tahap:
  1. Rotasi profil autentikasi dalam penyedia yang sama.
  2. Fallback model ke model berikutnya di agents.defaults.model.fallbacks.
Cooldown berlaku untuk profil yang gagal (backoff eksponensial), sehingga OpenClaw dapat tetap merespons bahkan ketika penyedia terkena pembatasan laju atau gagal sementara.Bucket pembatasan laju mencakup lebih dari sekadar respons 429. OpenClaw juga memperlakukan pesan seperti Too many concurrent requests, ThrottlingException, concurrency limit reached, workers_ai ... quota limit exceeded, resource exhausted, dan batas jendela penggunaan berkala (weekly/monthly limit reached) sebagai pembatasan laju yang layak memicu failover.Beberapa respons yang tampak seperti penagihan bukan 402, dan beberapa respons HTTP 402 juga tetap berada dalam bucket sementara tersebut. Jika penyedia mengembalikan teks penagihan eksplisit pada 401 atau 403, OpenClaw tetap dapat menyimpannya di jalur penagihan, tetapi pencocok teks spesifik penyedia tetap terbatas pada penyedia pemiliknya (misalnya OpenRouter Key limit exceeded). Jika pesan 402 justru terlihat seperti jendela penggunaan yang dapat dicoba ulang atau batas belanja organisasi/ruang kerja (daily limit reached, resets tomorrow, organization spending limit exceeded), OpenClaw memperlakukannya sebagai rate_limit, bukan penonaktifan penagihan jangka panjang.Galat luapan konteks berbeda: tanda 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 tetap berada pada jalur Compaction/coba ulang, alih-alih melanjutkan fallback model.Teks galat server generik sengaja dibuat lebih sempit daripada “apa pun yang berisi unknown/error”. OpenClaw memang memperlakukan bentuk sementara yang terbatas pada penyedia seperti Anthropic polos An unknown error occurred, OpenRouter polos Provider returned error, galat 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 galat penyedia sibuk seperti ModelNotReadyException sebagai sinyal timeout/kelebihan beban yang layak memicu failover ketika konteks penyedia cocok. Teks fallback internal generik seperti LLM request failed with an unknown error. tetap konservatif dan tidak memicu fallback model dengan sendirinya.
Artinya sistem mencoba menggunakan ID profil autentikasi anthropic:default, tetapi tidak dapat menemukan kredensialnya di penyimpanan autentikasi yang diharapkan.Daftar periksa perbaikan:
  • Konfirmasi lokasi profil autentikasi berada (jalur baru vs lama)
    • Saat ini: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
    • Lama: ~/.openclaw/agent/* (dimigrasikan oleh openclaw doctor)
  • Konfirmasi env var Anda dimuat oleh Gateway
    • Jika Anda menetapkan ANTHROPIC_API_KEY di shell tetapi menjalankan Gateway melalui systemd/launchd, Gateway mungkin tidak mewarisinya. Letakkan di ~/.openclaw/.env atau aktifkan env.shellEnv.
  • Pastikan Anda mengedit agen yang benar
    • Penyiapan multi-agen berarti mungkin ada beberapa file auth-profiles.json.
  • Periksa kewajaran status model/autentikasi
    • Gunakan openclaw models status untuk melihat model yang dikonfigurasi dan apakah penyedia sudah terautentikasi.
Daftar periksa perbaikan untuk “No credentials found for profile anthropic”Ini berarti proses berjalan dipatok ke profil autentikasi Anthropic, tetapi Gateway tidak dapat menemukannya di penyimpanan autentikasinya.
  • Gunakan Claude CLI
    • Jalankan openclaw models auth login --provider anthropic --method cli --set-default pada host gateway.
  • Jika Anda ingin menggunakan kunci API
    • Letakkan ANTHROPIC_API_KEY di ~/.openclaw/.env pada host gateway.
    • Hapus urutan terpaku yang memaksa profil yang hilang: 
      openclaw models auth order clear --provider anthropic
  • Konfirmasi Anda menjalankan perintah pada host gateway
    • Dalam mode jarak jauh, profil autentikasi berada di mesin gateway, bukan laptop Anda.
Jika konfigurasi model Anda menyertakan Google Gemini sebagai fallback (atau Anda beralih ke singkatan Gemini), OpenClaw akan mencobanya selama fallback model. Jika Anda belum mengonfigurasi kredensial Google, Anda akan melihat No API key found for provider "google".Perbaikan: sediakan autentikasi Google, atau hapus/hindari model Google di agents.defaults.model.fallbacks / alias agar fallback tidak dirutekan ke sana.Permintaan LLM ditolak: tanda tangan thinking diperlukan (Google Antigravity)Penyebab: riwayat sesi berisi blok thinking tanpa tanda tangan (sering kali dari stream yang dibatalkan/parsial). Google Antigravity memerlukan tanda tangan untuk blok thinking.Perbaikan: OpenClaw sekarang menghapus blok thinking tanpa tanda tangan untuk Google Antigravity Claude. Jika masih muncul, mulai sesi baru atau tetapkan /thinking off untuk agen tersebut.

​
Profil autentikasi: apa itu dan cara mengelolanya

Terkait: /concepts/oauth (alur OAuth, penyimpanan token, pola multi-akun)
Profil autentikasi adalah catatan kredensial bernama (OAuth atau kunci API) yang terkait dengan penyedia. Profil berada di:
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
Untuk memeriksa profil tersimpan tanpa membocorkan rahasia, jalankan openclaw models auth list (opsional --provider <id> atau --json). Lihat CLI Model untuk detail.
OpenClaw menggunakan ID berawalan penyedia seperti:
  • anthropic:default (umum ketika tidak ada identitas email)
  • anthropic:<email> untuk identitas OAuth
  • ID khusus yang Anda pilih (mis. anthropic:work)
Ya. Konfigurasi mendukung metadata opsional untuk profil dan urutan per penyedia (auth.order.<provider>). Ini tidak menyimpan rahasia; ini memetakan ID ke penyedia/mode dan menetapkan urutan rotasi.OpenClaw mungkin melewati profil sementara jika profil tersebut berada dalam cooldown singkat (pembatasan laju/timeout/kegagalan autentikasi) atau status disabled yang lebih lama (penagihan/kredit tidak cukup). Untuk memeriksanya, jalankan openclaw models status --json dan periksa auth.unusableProfiles. Penyetelan: auth.cooldowns.billingBackoffHours*.Cooldown pembatasan laju dapat terbatas pada model. Profil yang sedang cooldown untuk satu model masih dapat digunakan untuk model saudara pada penyedia yang sama, sementara jendela penagihan/disabled tetap memblokir seluruh profil.Anda juga dapat menetapkan penggantian urutan per agen (disimpan di auth-state.json agen tersebut) melalui CLI:
# Defaults to the configured default agent (omit --agent)
openclaw models auth order get --provider anthropic

# Lock rotation to a single profile (only try this one)
openclaw models auth order set --provider anthropic anthropic:default

# Or set an explicit order (fallback within provider)
openclaw models auth order set --provider anthropic anthropic:work anthropic:default

# Clear override (fall back to config auth.order / round-robin)
openclaw models auth order clear --provider anthropic
Untuk menargetkan agen tertentu:
openclaw models auth order set --provider anthropic --agent main anthropic:default
Untuk memverifikasi apa yang benar-benar akan dicoba, gunakan:
openclaw models status --probe
Jika profil tersimpan dihilangkan dari urutan eksplisit, probe melaporkan excluded_by_auth_order untuk profil tersebut alih-alih mencobanya secara diam-diam.
OpenClaw mendukung keduanya:
  • OAuth sering memanfaatkan akses langganan (jika berlaku).
  • Kunci API menggunakan penagihan bayar per token.
Wizard secara eksplisit mendukung Anthropic Claude CLI, OpenAI Codex OAuth, dan kunci API.

​
Terkait