Backend CLI

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

​

Mulai cepat

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

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

​

Menggunakannya sebagai fallback

{
  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": {},
      },
    },
  },
}

​

Konfigurasi

{
  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 file prompt:
          // systemPromptFileArg: "--system-file",
          // Atau gunakan flag penggantian konfigurasi bergaya Codex:
          // systemPromptFileConfigArg: "-c",
          // systemPromptFileConfigKey: "model_instructions_file",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          // Aktifkan hanya jika backend ini boleh menyemai 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 OpenClaw dan konteks ruang kerja yang sama.
3. Menjalankan CLI dengan id sesi (jika didukung) agar riwayat tetap konsisten. Backend claude-cli bawaan mempertahankan proses stdio Claude tetap aktif untuk setiap 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 giliran lanjutan menggunakan kembali sesi CLI yang sama.

​

Batas waktu dan pekerjaan jangka panjang

• agents.defaults.timeoutSeconds membatasi keseluruhan giliran agen. Giliran Gateway normal mewarisi nilai default 48 jam; 0 membuat anggaran giliran tidak terbatas. Penggantian yang tersimpan seperti 600 menggantikan nilai default tersebut.
• Pengawas tanpa keluaran CLI menghentikan subproses yang tetap tidak mengeluarkan apa pun. Pengawas ini menggunakan profil baru/lanjutan terpisah di bawah agents.defaults.cliBackends.<id>.reliability.watchdog dan tetap aktif meskipun anggaran giliran keseluruhan tidak terbatas.

# Kembali ke nilai default 48 jam:
openclaw config unset agents.defaults.timeoutSeconds

# Atau pilih batas eksplisit 12 jam:
openclaw config set agents.defaults.timeoutSeconds 43200

​

Detail khusus Claude CLI

claude auth login
claude auth status --text
openclaw models auth login --provider anthropic --method cli --set-default

​

Sesi

• Jika CLI mendukung sesi, tetapkan sessionArg (misalnya --session-id), atau sessionArgs (placeholder {sessionId}) ketika id perlu ditempatkan dalam beberapa flag.
• Jika CLI menggunakan subperintah lanjutan dengan flag berbeda, tetapkan resumeArgs (menggantikan args saat melanjutkan) dan secara opsional resumeOutput untuk proses lanjutan non-JSON.
• sessionMode:
  • always: selalu kirim id sesi (UUID baru jika tidak ada yang tersimpan).
  • existing: hanya kirim id sesi jika sebelumnya sudah tersimpan.
  • none: jangan pernah mengirim id sesi.
• claude-cli secara default menggunakan liveSession: "claude-stdio", output: "jsonl", dan input: "stdin", sehingga giliran lanjutan menggunakan kembali proses Claude langsung selama proses tersebut aktif, termasuk untuk konfigurasi khusus yang tidak menyertakan 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 hilang menghapus pengikatan (dicatat sebagai reason=transcript-missing) alih-alih diam-diam memulai sesi baru di bawah --resume.
• Sesi langsung Claude mempertahankan pelindung keluaran JSONL yang dibatasi: 8 MiB dan 20.000 baris JSONL mentah per giliran.
• Sesi CLI yang tersimpan merupakan kontinuitas milik penyedia. Reset otomatis dinonaktifkan secara default; /reset dan kebijakan harian atau menganggur session.reset yang eksplisit tetap memutuskannya.
• Sesi CLI baru biasanya hanya disemai ulang dari ringkasan compaction OpenClaw beserta bagian setelah compaction. Untuk memulihkan sesi singkat yang dibatalkan sebelum compaction, backend dapat mengaktifkan reseedFromRawTranscriptWhenUncompacted: true. Penyemaian ulang transkrip mentah tetap dibatasi dan hanya berlaku untuk pembatalan yang aman, seperti transkrip CLI yang hilang, bagian akhir penggunaan alat yang yatim, perubahan kebijakan pesan/prompt sistem/cwd/MCP, atau percobaan ulang karena sesi kedaluwarsa; perubahan profil autentikasi atau epoch kredensial tidak pernah menyemai ulang riwayat transkrip mentah.

​

Pendahuluan fallback dari sesi claude-cli

• Prelude memprioritaskan ringkasan /compact terbaru atau penanda compact_boundary, lalu menambahkan giliran terbaru setelah batas hingga mencapai batas karakter. Giliran sebelum batas dibuang karena sudah direpresentasikan oleh ringkasan.
• Blok alat digabungkan menjadi petunjuk ringkas (tool call: name) dan (tool result: …) agar anggaran prompt tetap akurat; ringkasan yang terlalu besar dipangkas dan diberi label (truncated).
• Fallback dari claude-cli ke claude-cli dalam penyedia yang sama mengandalkan --resume milik Claude sendiri dan melewati prelude.
• Seed menggunakan kembali validasi jalur file sesi Claude yang sudah ada, sehingga jalur sembarang tidak dapat dibaca.

​

Gambar

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

​

Masukan dan keluaran

• output: "text" (default) memperlakukan stdout sebagai respons akhir.
• output: "json" mencoba mengurai JSON dan mengekstrak teks beserta ID sesi.
• output: "jsonl" mengurai aliran JSONL dan mengekstrak pesan agen terakhir beserta pengidentifikasi sesi jika tersedia.
• 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 masih menggunakan pengurai JSON.

• 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

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

• Pengurai default stream-json membaca peristiwa message asisten, peristiwa alat, penggunaan akhir result, dan peristiwa kesalahan 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 JSON response.
• Penggunaan beralih ke stats ketika usage tidak ada atau kosong; stats.cached dinormalkan menjadi cacheRead OpenClaw, dan jika stats.input tidak ada, token masukan diturunkan dari stats.input_tokens - stats.cached.

​

Overlay transformasi teks

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

​

Kepemilikan Compaction native

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

​

Overlay MCP bundel

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

• menjalankan server MCP HTTP loopback yang mengekspos alat Gateway kepada proses CLI, diautentikasi dengan pemberian konteks per proses (OPENCLAW_MCP_TOKEN) yang hanya aktif untuk upaya 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.

​

Batas riwayat reseed

​

Keterbatasan

• Tidak ada pemanggilan alat OpenClaw secara langsung: OpenClaw tidak menyisipkan pemanggilan alat ke dalam protokol backend CLI. Backend hanya melihat alat Gateway saat memilih untuk menggunakan bundleMcp: true.
• Streaming bergantung pada backend: beberapa backend melakukan streaming JSONL, sedangkan yang lain menampung data hingga proses selesai.
• Keluaran terstruktur bergantung pada format JSON milik CLI sendiri.

​

Pemecahan masalah

​

Terkait

• Panduan operasional Gateway
• Model lokal