Langsung ke konten utama

​
Backend CLI (runtime fallback)

OpenClaw dapat menjalankan CLI AI lokal sebagai fallback khusus teks saat penyedia API sedang tidak tersedia, terkena rate limit, atau sementara bermasalah. Pendekatan ini sengaja dibuat konservatif:
  • Alat OpenClaw tidak disuntikkan secara langsung, tetapi backend dengan bundleMcp: true dapat menerima alat gateway melalui bridge MCP local loopback.
  • Streaming JSONL untuk CLI yang mendukungnya.
  • Sesi didukung (agar giliran tindak lanjut tetap koheren).
  • Gambar dapat diteruskan jika CLI menerima path gambar.
Ini dirancang sebagai jaring pengaman alih-alih jalur utama. Gunakan ini saat Anda menginginkan respons teks yang “selalu berfungsi” tanpa bergantung pada API eksternal. Jika Anda menginginkan runtime harness penuh dengan kontrol sesi ACP, tugas latar belakang, binding thread/percakapan, dan sesi coding eksternal persisten, gunakan ACP Agents sebagai gantinya. Backend CLI bukan ACP.

​
Mulai cepat yang ramah pemula

Anda dapat menggunakan Codex CLI tanpa konfigurasi apa pun (Plugin OpenAI bawaan mendaftarkan backend default): 
openclaw agent --message "hi" --model codex-cli/gpt-5.4
Jika gateway Anda berjalan di bawah launchd/systemd dan PATH minimal, tambahkan hanya path perintahnya: 
{
  agents: {
    defaults: {
      cliBackends: {
        "codex-cli": {
          command: "/opt/homebrew/bin/codex",
        },
      },
    },
  },
}
Itu saja. Tidak diperlukan key maupun konfigurasi autentikasi tambahan selain yang dimiliki CLI itu sendiri. Jika Anda menggunakan backend CLI bawaan sebagai penyedia pesan utama pada host gateway, OpenClaw kini otomatis memuat Plugin bawaan pemiliknya saat konfigurasi Anda secara eksplisit merujuk backend tersebut dalam model ref atau di bawah agents.defaults.cliBackends.

​
Menggunakannya sebagai fallback

Tambahkan backend CLI ke daftar fallback Anda agar hanya dijalankan saat model utama gagal: 
{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["codex-cli/gpt-5.4"],
      },
      models: {
        "anthropic/claude-opus-4-6": { alias: "Opus" },
        "codex-cli/gpt-5.4": {},
      },
    },
  },
}
Catatan:
  • Jika Anda menggunakan agents.defaults.models (allowlist), Anda juga harus menyertakan model backend CLI di sana.
  • Jika penyedia utama gagal (autentikasi, rate limit, timeout), OpenClaw akan mencoba backend CLI berikutnya.

​
Ikhtisar konfigurasi

Semua backend CLI berada di bawah: 
agents.defaults.cliBackends
Setiap entri dikunci dengan id penyedia (misalnya codex-cli, my-cli). Id penyedia menjadi sisi kiri model ref Anda: 
<provider>/<model>

​
Contoh konfigurasi

{
  agents: {
    defaults: {
      cliBackends: {
        "codex-cli": {
          command: "/opt/homebrew/bin/codex",
        },
        "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",
          // CLI bergaya Codex dapat menunjuk ke file prompt sebagai gantinya:
          // systemPromptFileConfigArg: "-c",
          // systemPromptFileConfigKey: "model_instructions_file",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          serialize: true,
        },
      },
    },
  },
}

​
Cara kerjanya

  1. Memilih backend berdasarkan prefiks penyedia (codex-cli/...).
  2. Membangun system prompt menggunakan prompt OpenClaw yang sama + konteks workspace.
  3. Menjalankan CLI dengan id sesi (jika didukung) agar riwayat tetap konsisten.
  4. Mem-parsing output (JSON atau teks biasa) dan mengembalikan teks akhir.
  5. Menyimpan id sesi per backend, sehingga tindak lanjut menggunakan kembali sesi CLI yang sama.
Backend claude-cli Anthropic bawaan kembali didukung. Staf Anthropic memberi tahu kami bahwa penggunaan Claude CLI bergaya OpenClaw kembali diizinkan, sehingga OpenClaw memperlakukan penggunaan claude -p sebagai penggunaan yang disetujui untuk integrasi ini kecuali Anthropic menerbitkan kebijakan baru.
Backend codex-cli OpenAI bawaan meneruskan system prompt OpenClaw melalui override konfigurasi model_instructions_file Codex (-c model_instructions_file="..."). Codex tidak menyediakan flag --append-system-prompt seperti Claude, sehingga OpenClaw menulis prompt yang dirangkai ke sebuah file sementara untuk setiap sesi Codex CLI baru. Backend claude-cli Anthropic bawaan menerima snapshot Skills OpenClaw dengan dua cara: katalog Skills OpenClaw ringkas di appended system prompt, dan Plugin Claude Code sementara yang diteruskan dengan --plugin-dir. Plugin tersebut hanya berisi Skills yang memenuhi syarat untuk agen/sesi itu, sehingga resolver skill native Claude Code melihat set terfilter yang sama yang seharusnya akan diiklankan OpenClaw dalam prompt. Override env/API key Skill tetap diterapkan oleh OpenClaw ke environment proses anak untuk eksekusi tersebut.

​
Sesi

  • Jika CLI mendukung sesi, atur sessionArg (misalnya --session-id) atau sessionArgs (placeholder {sessionId}) saat ID perlu disisipkan ke beberapa flag.
  • Jika CLI menggunakan subperintah resume dengan flag yang berbeda, atur resumeArgs (menggantikan args saat melanjutkan) dan secara opsional resumeOutput (untuk resume 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.
Catatan serialisasi:
  • serialize: true menjaga urutan eksekusi pada lane yang sama.
  • Sebagian besar CLI melakukan serialisasi pada satu lane penyedia.
  • OpenClaw membuang penggunaan ulang sesi CLI yang tersimpan saat status autentikasi backend berubah, termasuk login ulang, rotasi token, atau perubahan kredensial profil autentikasi.

​
Gambar (pass-through)

Jika CLI Anda menerima path gambar, atur imageArg: 
imageArg: "--image",
imageMode: "repeat"
OpenClaw akan menulis gambar base64 ke file sementara. Jika imageArg diatur, path tersebut diteruskan sebagai argumen CLI. Jika imageArg tidak ada, OpenClaw menambahkan path file ke prompt (path injection), yang cukup untuk CLI yang otomatis memuat file lokal dari path biasa.

​
Input / output

  • output: "json" (default) mencoba mem-parsing JSON dan mengekstrak teks + id sesi.
  • Untuk output JSON Gemini CLI, OpenClaw membaca teks balasan dari response dan penggunaan dari stats saat usage tidak ada atau kosong.
  • output: "jsonl" mem-parsing stream JSONL (misalnya Codex CLI --json) dan mengekstrak pesan agen akhir serta pengenal sesi jika ada.
  • output: "text" memperlakukan stdout sebagai respons akhir.
Mode input:
  • input: "arg" (default) meneruskan prompt sebagai argumen CLI terakhir.
  • input: "stdin" mengirim prompt melalui stdin.
  • Jika prompt sangat panjang dan maxPromptArgChars diatur, stdin digunakan.

​
Default (dimiliki Plugin)

Plugin OpenAI bawaan juga mendaftarkan default untuk codex-cli:
  • command: "codex"
  • args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]
  • resumeArgs: ["exec","resume","{sessionId}","-c","sandbox_mode=\"workspace-write\"","--skip-git-repo-check"]
  • output: "jsonl"
  • resumeOutput: "text"
  • modelArg: "--model"
  • imageArg: "--image"
  • sessionMode: "existing"
Plugin Google bawaan juga mendaftarkan default untuk google-gemini-cli:
  • command: "gemini"
  • args: ["--output-format", "json", "--prompt", "{prompt}"]
  • resumeArgs: ["--resume", "{sessionId}", "--output-format", "json", "--prompt", "{prompt}"]
  • imageArg: "@"
  • imagePathScope: "workspace"
  • modelArg: "--model"
  • sessionMode: "existing"
  • sessionIdFields: ["session_id", "sessionId"]
Prasyarat: Gemini CLI lokal harus terinstal dan tersedia sebagai gemini di PATH (brew install gemini-cli atau npm install -g @google/gemini-cli). Catatan JSON Gemini CLI:
  • Teks balasan dibaca dari field JSON response.
  • Penggunaan fallback ke stats saat usage tidak ada atau kosong.
  • stats.cached dinormalisasi menjadi OpenClaw cacheRead.
  • Jika stats.input tidak ada, OpenClaw menurunkan token input dari stats.input_tokens - stats.cached.
Lakukan override hanya jika diperlukan (umumnya: path command absolut).

​
Default yang dimiliki Plugin

Default backend CLI kini menjadi bagian dari permukaan Plugin:
  • Plugin mendaftarkannya dengan api.registerCliBackend(...).
  • id backend menjadi prefiks penyedia dalam model ref.
  • Konfigurasi pengguna di agents.defaults.cliBackends.<id> tetap menimpa default Plugin.
  • Pembersihan konfigurasi khusus backend tetap dimiliki Plugin melalui hook normalizeConfig opsional.
Plugin yang memerlukan shim kompatibilitas prompt/pesan kecil dapat mendeklarasikan transformasi teks dua arah tanpa mengganti penyedia atau backend CLI: 
api.registerTextTransforms({
  input: [
    { from: /red basket/g, to: "blue basket" },
    { from: /paper ticket/g, to: "digital ticket" },
    { from: /left shelf/g, to: "right shelf" },
  ],
  output: [
    { from: /blue basket/g, to: "red basket" },
    { from: /digital ticket/g, to: "paper ticket" },
    { from: /right shelf/g, to: "left shelf" },
  ],
});
input menulis ulang system prompt dan prompt pengguna yang diteruskan ke CLI. output menulis ulang delta asisten yang di-streaming dan teks akhir yang sudah di-parse sebelum OpenClaw menangani marker kontrolnya sendiri dan pengiriman kanal. Untuk CLI yang mengeluarkan JSONL yang kompatibel dengan Claude Code stream-json, atur jsonlDialect: "claude-stream-json" pada konfigurasi backend tersebut.

​
Overlay bundle MCP

Backend CLI tidak menerima pemanggilan alat OpenClaw secara langsung, tetapi backend dapat ikut serta dalam overlay konfigurasi MCP yang dihasilkan dengan bundleMcp: true. Perilaku bawaan saat ini:
  • claude-cli: file konfigurasi MCP strict yang dihasilkan
  • codex-cli: override konfigurasi inline untuk mcp_servers
  • google-gemini-cli: file pengaturan sistem Gemini yang dihasilkan
Saat bundle MCP diaktifkan, OpenClaw:
  • menjalankan server MCP HTTP local loopback yang mengekspos alat gateway ke proses CLI
  • mengautentikasi bridge dengan token per sesi (OPENCLAW_MCP_TOKEN)
  • membatasi akses alat ke sesi, akun, dan konteks kanal saat ini
  • memuat server bundle-MCP yang diaktifkan untuk workspace saat ini
  • menggabungkannya dengan bentuk konfigurasi/pengaturan MCP backend yang ada
  • menulis ulang konfigurasi peluncuran menggunakan mode integrasi milik backend dari extension pemilik
Jika tidak ada server MCP yang diaktifkan, OpenClaw tetap menyuntikkan konfigurasi strict saat sebuah backend ikut serta dalam bundle MCP agar eksekusi latar belakang tetap terisolasi.

​
Keterbatasan

  • Tidak ada pemanggilan alat OpenClaw secara langsung. OpenClaw tidak menyuntikkan pemanggilan alat ke protokol backend CLI. Backend hanya melihat alat gateway saat mereka ikut serta dalam bundleMcp: true.
  • Streaming bersifat spesifik backend. Beberapa backend melakukan stream JSONL; yang lain menahan buffer hingga keluar.
  • Output terstruktur bergantung pada format JSON milik CLI.
  • Sesi Codex CLI dilanjutkan melalui output teks (tanpa JSONL), yang kurang terstruktur dibanding eksekusi awal --json. Sesi OpenClaw tetap bekerja secara normal.

​
Pemecahan masalah

  • CLI tidak ditemukan: atur command ke path lengkap.
  • Nama model salah: gunakan modelAliases untuk memetakan provider/model → model CLI.
  • Tidak ada kesinambungan sesi: pastikan sessionArg diatur dan sessionMode bukan none (Codex CLI saat ini tidak dapat melanjutkan dengan output JSON).
  • Gambar diabaikan: atur imageArg (dan verifikasi CLI mendukung path file).