Backend CLI

OpenClaw dapat menjalankan CLI AI lokal sebagai cadangan khusus teks ketika penyedia API tidak tersedia, terkena pembatasan laju, atau bermasalah. Pendekatan ini sengaja dibuat konservatif:

• Alat OpenClaw tidak disuntikkan secara langsung, tetapi backend dengan bundleMcp: true dapat menerima alat Gateway melalui jembatan MCP local loopback.
• Streaming JSONL untuk CLI yang mendukungnya.
• Sesi didukung, sehingga giliran lanjutan tetap koheren.
• Gambar diteruskan jika CLI menerima jalur gambar.

Gunakan sebagai jaring pengaman untuk respons teks yang "selalu berfungsi", bukan sebagai jalur utama. Untuk runtime harness lengkap dengan kontrol sesi ACP, tugas latar belakang, pengikatan utas/percakapan, dan sesi pengodean eksternal yang persisten, gunakan Agen ACP; backend CLI bukan ACP.

Mulai cepat

Plugin Anthropic bawaan mendaftarkan backend claude-cli default, sehingga dapat digunakan tanpa konfigurasi selain memasang Claude Code dan masuk ke akun:

openclaw agent --agent main --message "hi" --model claude-cli/claude-sonnet-4-6

main adalah id agen default ketika tidak ada daftar agen eksplisit yang dikonfigurasi; jika ada, ganti dengan id agen Anda sendiri.

Jika Gateway berjalan di bawah launchd/systemd dengan PATH minimal, arahkan ke biner secara eksplisit:

{  agents: {    defaults: {      cliBackends: {        "claude-cli": {          command: "/opt/homebrew/bin/claude",        },      },    },  },}

Jika Anda menggunakan backend CLI bawaan sebagai penyedia pesan utama pada host Gateway, OpenClaw secara otomatis memuat Plugin bawaan pemiliknya ketika konfigurasi Anda merujuk backend tersebut dalam referensi model atau di bawah agents.defaults.cliBackends.

Menggunakannya sebagai cadangan

Tambahkan backend CLI ke daftar cadangan agar hanya berjalan ketika model utama gagal:

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

Jika Anda menggunakan agents.defaults.models sebagai daftar izin, sertakan juga model backend CLI Anda di sana. Ketika penyedia utama gagal (autentikasi, pembatasan laju, batas waktu), OpenClaw selanjutnya mencoba backend CLI.

Konfigurasi

Semua backend CLI berada di bawah agents.defaults.cliBackends, dengan kunci berupa id penyedia (misalnya claude-cli, my-cli). Id penyedia menjadi sisi kiri referensi model: <provider>/<model>.

{  agents: {    defaults: {      cliBackends: {        "my-cli": {          command: "my-cli",          args: ["--json"],          output: "json",          input: "arg",          modelArg: "--model",          modelAliases: {            "claude-opus-4-6": "opus",            "claude-sonnet-4-6": "sonnet",          },          sessionArg: "--session",          sessionMode: "existing",          sessionIdFields: ["session_id", "conversation_id"],          systemPromptArg: "--system",          // Flag khusus untuk berkas prompt:          // systemPromptFileArg: "--system-file",          // Sebagai gantinya, flag penggantian konfigurasi bergaya Codex:          // systemPromptFileConfigArg: "-c",          // systemPromptFileConfigKey: "model_instructions_file",          systemPromptWhen: "first",          imageArg: "--image",          imageMode: "repeat",          // Aktifkan hanya jika backend ini boleh mengisi ulang sesi yang dibatalkan dari          // riwayat transkrip mentah OpenClaw yang dibatasi sebelum Compaction.          reseedFromRawTranscriptWhenUncompacted: true,          serialize: true,        },      },    },  },}

Cara kerjanya

1. Memilih backend berdasarkan prefiks penyedia (claude-cli/...).
2. Membuat prompt sistem menggunakan prompt dan konteks ruang kerja OpenClaw yang sama.
3. Menjalankan CLI dengan id sesi (jika didukung) agar riwayat tetap konsisten. Backend claude-cli bawaan mempertahankan satu proses stdio Claude tetap aktif per sesi OpenClaw dan mengirim giliran lanjutan melalui stdin stream-json.
4. Mengurai keluaran (JSON atau teks biasa) dan mengembalikan teks akhir.
5. Menyimpan id sesi per backend agar tindak lanjut menggunakan kembali sesi CLI yang sama.

Hal khusus pada Claude CLI

Backend claude-cli bawaan mengutamakan penyelesai skill native Claude Code. Ketika snapshot Skills saat ini memiliki setidaknya satu skill terpilih dengan jalur yang telah diwujudkan, OpenClaw meneruskan Plugin Claude Code sementara melalui --plugin-dir dan menghilangkan katalog Skills OpenClaw duplikat dari prompt sistem yang ditambahkan. Tanpa skill Plugin yang telah diwujudkan, OpenClaw mempertahankan katalog prompt sebagai cadangan. Penggantian variabel lingkungan/kunci API skill tetap diterapkan ke lingkungan proses anak untuk eksekusi tersebut.

Claude CLI memiliki mode izin noninteraktifnya sendiri; OpenClaw memetakannya ke kebijakan eksekusi yang sudah ada, bukan menambahkan konfigurasi khusus Claude. Untuk sesi langsung Claude yang dikelola OpenClaw, kebijakan eksekusi efektif bersifat menentukan: YOLO (tools.exec.security: "full" dan tools.exec.ask: "off") menjalankan Claude dengan --permission-mode bypassPermissions, sedangkan kebijakan yang membatasi menjalankannya dengan --permission-mode default. Pengaturan agents.list[].tools.exec per agen menggantikan tools.exec global untuk agen tersebut. Argumen backend mentah tetap dapat menyertakan --permission-mode, tetapi peluncuran langsung Claude menormalkan flag tersebut agar sesuai dengan kebijakan efektif.

Backend juga memetakan level /think OpenClaw ke flag native --effort milik Claude Code: minimal/low -> low, medium -> medium, dan high/xhigh/max diteruskan secara langsung. adaptive menghapus flag --effort yang dikonfigurasi dan tidak memberikan pengganti, sehingga Claude Code menentukan upaya efektif dari lingkungan, pengaturan, dan default modelnya sendiri. Backend CLI lain memerlukan Plugin pemiliknya untuk mendeklarasikan pemeta argv yang setara sebelum /think memengaruhi CLI yang dijalankan.

Sebelum OpenClaw dapat menggunakan claude-cli, Claude Code sendiri harus sudah masuk ke akun pada host yang sama:

claude auth loginclaude auth status --textopenclaw models auth login --provider anthropic --method cli --set-default

Instalasi Docker mengharuskan Claude Code dipasang dan sudah masuk ke akun di dalam direktori home kontainer yang dipertahankan, bukan hanya pada host; lihat Backend Claude CLI di Docker.

Atur agents.defaults.cliBackends.claude-cli.command hanya ketika biner claude belum tersedia di PATH.

Sesi

• Jika CLI mendukung sesi, atur sessionArg (misalnya --session-id), atau sessionArgs (placeholder {sessionId}) ketika id perlu ditempatkan pada beberapa flag.
• Jika CLI menggunakan subperintah pelanjutan dengan flag berbeda, atur resumeArgs (menggantikan args saat melanjutkan) dan secara opsional resumeOutput untuk pelanjutan non-JSON.
• sessionMode:
  • always: selalu kirim id sesi (UUID baru jika belum ada yang tersimpan).
  • existing: hanya kirim id sesi jika sebelumnya sudah tersimpan.
  • none: jangan pernah kirim id sesi.
• claude-cli secara default menggunakan liveSession: "claude-stdio", output: "jsonl", dan input: "stdin", sehingga giliran lanjutan menggunakan kembali proses Claude yang aktif selama proses tersebut masih berjalan, termasuk untuk konfigurasi khusus yang menghilangkan bidang transportasi. Jika Gateway dimulai ulang atau proses menganggur berhenti, OpenClaw melanjutkan dari id sesi Claude yang tersimpan. Id sesi yang tersimpan diverifikasi terhadap transkrip proyek yang dapat dibaca sebelum dilanjutkan; transkrip yang tidak ada akan menghapus pengikatan (dicatat sebagai reason=transcript-missing), alih-alih diam-diam memulai sesi baru dengan --resume.
• Sesi langsung Claude mempertahankan batas keluaran JSONL: 8 MiB dan 20.000 baris JSONL mentah per giliran secara default. Naikkan per backend dengan agents.defaults.cliBackends.claude-cli.reliability.outputLimits.maxTurnRawChars dan maxTurnLines; OpenClaw membatasi pengaturan tersebut hingga 64 MiB dan 100.000 baris.
• Sesi CLI yang tersimpan merupakan kontinuitas milik penyedia. Pengaturan ulang sesi harian implisit tidak memutusnya; /reset dan kebijakan session.reset eksplisit tetap memutusnya.
• Sesi CLI baru biasanya hanya diisi ulang dari ringkasan Compaction OpenClaw beserta bagian setelah Compaction. Untuk memulihkan sesi pendek yang dibatalkan sebelum Compaction, backend dapat mengaktifkan reseedFromRawTranscriptWhenUncompacted: true. Pengisian ulang transkrip mentah tetap dibatasi dan hanya berlaku untuk pembatalan yang aman, seperti transkrip CLI yang hilang, bagian akhir penggunaan alat yang terputus, perubahan kebijakan pesan/prompt sistem/cwd/MCP, atau percobaan ulang sesi yang kedaluwarsa; perubahan profil autentikasi atau periode kredensial tidak pernah mengisi ulang riwayat transkrip mentah.

Serialisasi: serialize: true menjaga agar eksekusi pada jalur yang sama tetap berurutan (sebagian besar CLI melakukan serialisasi pada satu jalur penyedia). OpenClaw juga membatalkan penggunaan kembali sesi CLI yang tersimpan ketika identitas autentikasi yang dipilih berubah, termasuk perubahan id profil autentikasi, kunci API statis, token statis, atau identitas akun OAuth ketika CLI mengeksposnya; rotasi token akses/penyegaran OAuth saja tidak memutus sesi. Jika CLI tidak memiliki id akun OAuth yang stabil, OpenClaw membiarkan CLI tersebut menerapkan izin pelanjutannya sendiri.

Pendahuluan cadangan dari sesi claude-cli

Ketika percobaan claude-cli beralih karena kegagalan ke kandidat non-CLI dalam agents.defaults.model.fallbacks, OpenClaw membekali percobaan berikutnya dengan pendahuluan konteks yang diambil dari transkrip JSONL lokal Claude Code (di bawah ~/.claude/projects/, dengan kunci per ruang kerja). Tanpa bekal ini, penyedia cadangan dimulai tanpa konteks, karena transkrip sesi OpenClaw sendiri kosong untuk eksekusi claude-cli.

• Pendahuluan mengutamakan ringkasan /compact terbaru atau penanda compact_boundary, lalu menambahkan giliran terbaru setelah batas tersebut hingga mencapai anggaran karakter. Giliran sebelum batas dibuang karena ringkasan sudah merepresentasikannya.
• Blok alat digabungkan menjadi petunjuk ringkas (pemanggilan alat: nama) dan (hasil alat: …) agar anggaran prompt tetap akurat; ringkasan yang terlalu besar dipotong dan diberi label (dipotong).
• Peralihan cadangan dari claude-cli ke claude-cli dengan penyedia yang sama mengandalkan --resume milik Claude dan melewati pendahuluan.
• Bekal tersebut menggunakan kembali validasi jalur berkas sesi Claude yang sudah ada, sehingga jalur sembarang tidak dapat dibaca.

Gambar

Jika CLI Anda menerima jalur gambar, atur imageArg:

imageArg: "--image",imageMode: "repeat"

OpenClaw menulis gambar base64 ke berkas sementara. Jika imageArg diatur, jalur tersebut diteruskan sebagai argumen CLI; jika tidak, OpenClaw menambahkan jalur berkas ke prompt (injeksi jalur), yang berfungsi untuk CLI yang secara otomatis memuat berkas lokal dari jalur biasa.

Masukan dan keluaran

• output: "text" (default) memperlakukan stdout sebagai respons akhir.
• output: "json" mencoba mengurai JSON dan mengekstrak teks serta id sesi.
• output: "jsonl" mengurai aliran JSONL dan mengekstrak pesan agen akhir beserta pengenal sesi jika ada.
• Untuk keluaran JSON Gemini CLI, OpenClaw membaca teks balasan dari response dan penggunaan dari stats ketika usage tidak ada atau kosong. Default Gemini CLI bawaan menggunakan stream-json; penggantian lama --output-format json tetap menggunakan pengurai JSON.

Mode masukan:

• input: "arg" (default) meneruskan prompt sebagai argumen CLI terakhir.
• input: "stdin" mengirimkan prompt melalui stdin.
• Jika prompt sangat panjang dan maxPromptArgChars diatur, stdin akan digunakan sebagai gantinya.

Default milik Plugin

Default backend CLI merupakan bagian dari permukaan Plugin:

• Plugin mendaftarkannya dengan api.registerCliBackend(...).
• id backend menjadi prefiks penyedia dalam referensi model.
• Konfigurasi pengguna di agents.defaults.cliBackends.<id> tetap menggantikan default Plugin.
• Pembersihan konfigurasi khusus backend tetap menjadi tanggung jawab Plugin melalui hook opsional normalizeConfig.

Anthropic memiliki claude-cli dan Google memiliki google-gemini-cli. Eksekusi agen OpenAI Codex menggunakan harness server aplikasi Codex melalui openai/*; OpenClaw tidak lagi mendaftarkan backend codex-cli bawaan.

Plugin Anthropic bawaan mendaftarkan hal berikut untuk claude-cli:

Plugin Google bawaan mendaftarkan diri untuk google-gemini-cli:

Prasyarat: Gemini CLI lokal harus terinstal dan tersedia di PATH sebagai gemini (brew install gemini-cli atau npm install -g @google/gemini-cli).

Catatan keluaran Gemini CLI:

• Pengurai stream-json bawaan membaca peristiwa message asisten, peristiwa alat, penggunaan result akhir, dan peristiwa galat fatal Gemini.
• Jika Anda mengganti argumen Gemini menjadi --output-format json, OpenClaw menormalkan backend tersebut kembali menjadi output: "json" dan membaca teks balasan dari bidang response JSON.
• Penggunaan beralih menggunakan stats jika usage tidak ada atau kosong; stats.cached dinormalkan menjadi cacheRead OpenClaw, dan jika stats.input tidak ada, token masukan diperoleh dari stats.input_tokens - stats.cached.

Ganti nilai bawaan hanya jika diperlukan (paling umum berupa jalur absolut command).

Lapisan transformasi teks

Plugin yang memerlukan shim kompatibilitas kecil untuk prompt/pesan dapat mendeklarasikan transformasi teks dua arah tanpa mengganti penyedia atau backend CLI:

api.registerTextTransforms({  input: [{ from: /red basket/g, to: "blue basket" }],  output: [{ from: /blue basket/g, to: "red basket" }],});

input menulis ulang prompt sistem dan prompt pengguna yang diteruskan ke CLI. output menulis ulang teks asisten yang dialirkan dan teks akhir yang telah diurai sebelum OpenClaw menangani penanda kontrol serta pengiriman kanalnya sendiri; untuk pemanggilan model berbasis penyedia, ini juga memulihkan nilai string di dalam argumen pemanggilan alat terstruktur setelah perbaikan aliran dan sebelum eksekusi alat. Fragmen JSON mentah dari penyedia tidak diubah; konsumen harus menggunakan muatan parsial, akhir, atau hasil yang terstruktur.

Untuk CLI yang memancarkan peristiwa JSONL khusus penyedia, atur jsonlDialect pada konfigurasi backend tersebut: claude-stream-json untuk aliran yang kompatibel dengan Claude Code, gemini-stream-json untuk peristiwa stream-json Gemini CLI.

Kepemilikan Compaction native

Beberapa backend CLI menjalankan agen yang melakukan Compaction pada transkripnya sendiri, sehingga OpenClaw tidak boleh menjalankan perangkum pengamannya terhadap backend tersebut—tindakan itu akan bertentangan dengan Compaction milik backend dan dapat menyebabkan giliran gagal total.

claude-cli tidak memiliki titik akhir harness (Claude Code melakukan Compaction secara internal), sehingga mendeklarasikan ownsNativeCompaction: true dan jalur Compaction OpenClaw mengembalikan entri sesi tanpa perubahan. Sebaliknya, sesi harness native seperti Codex tetap diarahkan ke titik akhir Compaction harness-nya.

api.registerCliBackend({ id: "my-cli", ownsNativeCompaction: true /* ... */ });

Deklarasikan ownsNativeCompaction hanya untuk backend yang benar-benar memiliki Compaction: backend tersebut harus secara andal membatasi transkripnya sendiri di sekitar jendela konteks dan mempertahankan sesi yang dapat dilanjutkan (misalnya --resume / --session-id), atau sesi yang ditunda dapat tetap melampaui batas anggaran.

Lapisan MCP bundel

Backend CLI tidak menerima pemanggilan alat OpenClaw secara langsung, tetapi backend dapat memilih menggunakan lapisan konfigurasi MCP yang dihasilkan dengan bundleMcp: true. Perilaku bawaan saat ini:

• claude-cli: berkas konfigurasi MCP ketat yang dihasilkan.
• google-gemini-cli: berkas pengaturan sistem Gemini yang dihasilkan.

Saat MCP bundel diaktifkan, OpenClaw:

• menjalankan server MCP HTTP local loopback yang mengekspos alat Gateway kepada proses CLI, diautentikasi dengan pemberian konteks per proses (OPENCLAW_MCP_TOKEN) yang hanya aktif untuk percobaan eksekusi saat ini;
• mengikat akses alat ke konteks sesi, akun, dan kanal yang dipilih Gateway, alih-alih memercayai header proses anak;
• memuat server MCP bundel yang diaktifkan untuk ruang kerja saat ini dan menggabungkannya dengan bentuk konfigurasi/pengaturan MCP backend yang sudah ada;
• menulis ulang konfigurasi peluncuran menggunakan mode integrasi milik backend dari Plugin pemiliknya.

Jika tidak ada server MCP yang diaktifkan, OpenClaw tetap menyisipkan konfigurasi ketat saat backend memilih menggunakan MCP bundel, sehingga proses latar belakang tetap terisolasi.

Runtime MCP bawaan dengan cakupan sesi disimpan dalam cache untuk digunakan kembali dalam satu sesi, kemudian dihentikan setelah mcp.sessionIdleTtlMs milidetik waktu menganggur (bawaan 10 menit; atur 0 untuk menonaktifkan). Proses tersemat sekali jalan seperti pemeriksaan autentikasi, pembuatan slug, dan pengambilan kembali active-memory meminta pembersihan pada akhir proses agar proses anak stdio serta aliran HTTP/SSE yang dapat dialirkan tidak bertahan lebih lama daripada proses tersebut.

Batas riwayat penyemaian ulang

Saat sesi CLI baru disemai dari transkrip OpenClaw sebelumnya (misalnya setelah percobaan ulang session_expired), blok <conversation_history> yang dirender dibatasi agar prompt penyemaian ulang tidak membengkak. Nilai bawaannya adalah 12.288 karakter (sekitar 3.000 token).

Backend Claude CLI menyesuaikan batas ini berdasarkan jendela konteks Claude yang telah ditentukan: jendela konteks yang lebih besar mendapatkan cuplikan riwayat sebelumnya yang lebih besar, hingga batas maksimum tetap; backend CLI lainnya mempertahankan nilai bawaan yang konservatif. Batas ini hanya mengatur blok riwayat sebelumnya pada prompt penyemaian ulang—batas keluaran sesi aktif disetel secara terpisah di bawah reliability.outputLimits (lihat Sesi).

Keterbatasan

• Tidak ada pemanggilan alat OpenClaw langsung: OpenClaw tidak menyisipkan pemanggilan alat ke dalam protokol backend CLI. Backend hanya melihat alat Gateway saat memilih menggunakan bundleMcp: true.
• Pengaliran bersifat khusus backend: beberapa backend mengalirkan JSONL, sedangkan yang lain menyangga hingga proses berakhir.
• Keluaran terstruktur bergantung pada format JSON milik CLI.

Pemecahan masalah

Terkait

• Panduan operasional Gateway
• Model lokal