openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh id translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-16 19:31:34 +00:00
parent 7b352587ee
commit 03decf45c0
1 changed files with 86 additions and 87 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

173
docs/id/gateway/cli-backends.md
View File

@ -1,40 +1,40 @@
---
read_when:
- Anda menginginkan fallback yang andal ketika penyedia API gagal
- Anda menjalankan Codex CLI atau CLI AI lokal lainnya dan ingin menggunakannya kembali
- Anda ingin memahami jembatan loopback MCP untuk akses alat backend CLI
summary: 'Backend CLI: fallback CLI AI lokal dengan jembatan alat MCP opsional'
- Anda menginginkan fallback yang andal saat penyedia API gagal
- Anda menjalankan Codex CLI atau CLI AI lokal lain dan ingin menggunakannya kembali
- Anda ingin memahami bridge local loopback MCP untuk akses alat backend CLI
summary: 'Backend CLI: fallback CLI AI lokal dengan bridge alat MCP opsional'
title: Backend CLI
x-i18n:
generated_at: "2026-04-11T02:44:24Z"
generated_at: "2026-04-16T19:31:01Z"
model: gpt-5.4
provider: openai
source_hash: d108dbea043c260a80d15497639298f71a6b4d800f68d7b39bc129f7667ca608
source_hash: 381273532a8622bc4628000a6fb999712b12af08faade2b5f2b7ac4cc7d23efe
source_path: gateway/cli-backends.md
workflow: 15
---
# Backend CLI (runtime fallback)
OpenClaw dapat menjalankan **CLI AI lokal** sebagai **fallback khusus teks** ketika penyedia API sedang tidak tersedia,
terkena pembatasan laju, atau sementara bermasalah. Ini sengaja dibuat konservatif:
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 jembatan MCP loopback.
dapat menerima alat gateway melalui bridge MCP local loopback.
- **Streaming JSONL** untuk CLI yang mendukungnya.
- **Sesi didukung** (agar giliran lanjutan tetap koheren).
- **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 ketika Anda
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
[Agen ACP](/id/tools/acp-agents) sebagai gantinya. Backend CLI bukan ACP.
[ACP Agents](/id/tools/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
Anda dapat menggunakan Codex CLI **tanpa konfigurasi apa pun** (Plugin OpenAI bawaan
mendaftarkan backend default):
```bash
@ -58,16 +58,16 @@ path perintahnya:
}
```
Itu saja. Tidak diperlukan key, tidak ada konfigurasi auth tambahan selain yang dimiliki CLI itu sendiri.
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 sekarang memuat otomatis plugin bawaan pemiliknya ketika konfigurasi Anda
secara eksplisit mereferensikan backend tersebut dalam ref model atau di bawah
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 berjalan saat model utama gagal:
Tambahkan backend CLI ke daftar fallback Anda agar hanya dijalankan saat model utama gagal:
```json5
{
@ -89,7 +89,7 @@ Tambahkan backend CLI ke daftar fallback Anda agar hanya berjalan saat model uta
Catatan:
- Jika Anda menggunakan `agents.defaults.models` (allowlist), Anda juga harus menyertakan model backend CLI di sana.
- Jika penyedia utama gagal (auth, pembatasan laju, timeout), OpenClaw akan
- Jika penyedia utama gagal (autentikasi, rate limit, timeout), OpenClaw akan
mencoba backend CLI berikutnya.
## Ikhtisar konfigurasi
@ -100,8 +100,8 @@ Semua backend CLI berada di bawah:
agents.defaults.cliBackends
```
Setiap entri diberi key dengan **id penyedia** (misalnya `codex-cli`, `my-cli`).
Id penyedia menjadi sisi kiri dari ref model Anda:
Setiap entri dikunci dengan **id penyedia** (misalnya `codex-cli`, `my-cli`).
Id penyedia menjadi sisi kiri model ref Anda:
```
<provider>/<model>
@ -148,86 +148,85 @@ Id penyedia menjadi sisi kiri dari ref model Anda:
## Cara kerjanya
1. **Memilih backend** berdasarkan prefiks penyedia (`codex-cli/...`).
2. **Membangun prompt sistem** menggunakan prompt OpenClaw yang sama + konteks workspace.
2. **Membangun system prompt** menggunakan prompt OpenClaw yang sama + konteks workspace.
3. **Menjalankan CLI** dengan id sesi (jika didukung) agar riwayat tetap konsisten.
4. **Mengurai output** (JSON atau teks biasa) dan mengembalikan teks akhir.
5. **Menyimpan id sesi** per backend, agar tindak lanjut menggunakan kembali sesi CLI yang sama.
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.
<Note>
Backend `claude-cli` Anthropic bawaan kini didukung lagi. Staf Anthropic
memberi tahu kami bahwa penggunaan Claude CLI bergaya OpenClaw diizinkan lagi, jadi OpenClaw memperlakukan
penggunaan `claude -p` sebagai sesuatu yang disetujui untuk integrasi ini kecuali Anthropic menerbitkan
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.
</Note>
Backend `codex-cli` OpenAI bawaan meneruskan prompt sistem OpenClaw melalui
override config `model_instructions_file` milik Codex (`-c
model_instructions_file="..."`). Codex tidak mengekspos flag
`--append-system-prompt` seperti Claude, jadi OpenClaw menulis prompt yang dirakit ke
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 prompt sistem tambahan, 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 seperti yang seharusnya diiklankan OpenClaw dalam
prompt. Override env/API key Skill tetap diterapkan oleh OpenClaw ke lingkungan proses anak untuk eksekusi.
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, setel `sessionArg` (misalnya `--session-id`) atau
`sessionArgs` (placeholder `{sessionId}`) ketika ID perlu disisipkan
- 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, setel
`resumeArgs` (menggantikan `args` saat melanjutkan) dan opsional `resumeOutput`
- 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 sudah pernah disimpan sebelumnya.
- `existing`: hanya kirim id sesi jika sebelumnya sudah tersimpan.
- `none`: jangan pernah kirim id sesi.
Catatan serialisasi:
- `serialize: true` menjaga eksekusi pada lane yang sama tetap berurutan.
- `serialize: true` menjaga urutan eksekusi pada lane yang sama.
- Sebagian besar CLI melakukan serialisasi pada satu lane penyedia.
- OpenClaw membuang reuse sesi CLI yang tersimpan ketika status auth backend berubah, termasuk login ulang, rotasi token, atau perubahan kredensial profil auth.
- 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, setel `imageArg`:
Jika CLI Anda menerima path gambar, atur `imageArg`:
```json5
imageArg: "--image",
imageMode: "repeat"
```
OpenClaw akan menulis gambar base64 ke file sementara. Jika `imageArg` disetel, path tersebut
diteruskan sebagai arg CLI. Jika `imageArg` tidak ada, OpenClaw menambahkan
path file ke prompt (injeksi path), yang cukup untuk CLI yang secara otomatis
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 mengurai JSON dan mengekstrak teks + id sesi.
- `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` ketika `usage` tidak ada atau kosong.
- `output: "jsonl"` mengurai stream JSONL (misalnya Codex CLI `--json`) dan mengekstrak pesan agen akhir serta pengidentifikasi sesi
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 arg CLI terakhir.
- `input: "arg"` (default) meneruskan prompt sebagai argumen CLI terakhir.
- `input: "stdin"` mengirim prompt melalui stdin.
- Jika prompt sangat panjang dan `maxPromptArgChars` disetel, stdin digunakan.
- Jika prompt sangat panjang dan `maxPromptArgChars` diatur, stdin digunakan.
## Default (dimiliki plugin)
## 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}","--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"`
@ -245,28 +244,28 @@ Plugin Google bawaan juga mendaftarkan default untuk `google-gemini-cli`:
- `sessionMode: "existing"`
- `sessionIdFields: ["session_id", "sessionId"]`
Prasyarat: Gemini CLI lokal harus terpasang dan tersedia sebagai
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 akan fallback ke `stats` ketika `usage` tidak ada atau kosong.
- `stats.cached` dinormalisasi menjadi `cacheRead` OpenClaw.
- 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`.
Override hanya jika diperlukan (umum: path `command` absolut).
Lakukan override hanya jika diperlukan (umumnya: path `command` absolut).
## Default yang dimiliki plugin
## Default yang dimiliki Plugin
Default backend CLI sekarang menjadi bagian dari surface plugin:
Default backend CLI kini menjadi bagian dari permukaan Plugin:
- Plugin mendaftarkannya dengan `api.registerCliBackend(...)`.
- `id` backend menjadi prefiks penyedia dalam ref model.
- Konfigurasi pengguna di `agents.defaults.cliBackends.<id>` tetap menimpa default plugin.
- Pembersihan konfigurasi khusus backend tetap dimiliki plugin melalui hook
- `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
@ -287,52 +286,52 @@ api.registerTextTransforms({
});
```
`input` menulis ulang prompt sistem dan prompt pengguna yang diteruskan ke CLI. `output`
menulis ulang delta asisten yang di-stream dan teks akhir yang diurai sebelum OpenClaw menangani
penanda kontrolnya sendiri dan pengiriman kanal.
`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 kompatibel Claude Code stream-json, setel
Untuk CLI yang mengeluarkan JSONL yang kompatibel dengan Claude Code stream-json, atur
`jsonlDialect: "claude-stream-json"` pada konfigurasi backend tersebut.
## Overlay Bundle MCP
## Overlay bundle MCP
Backend CLI **tidak** menerima pemanggilan alat OpenClaw secara langsung, tetapi backend dapat
ikut serta dalam overlay config MCP yang dibuat secara otomatis dengan `bundleMcp: true`.
ikut serta dalam overlay konfigurasi MCP yang dihasilkan dengan `bundleMcp: true`.
Perilaku bawaan saat ini:
- `claude-cli`: file config MCP ketat yang dibuat otomatis
- `codex-cli`: override config inline untuk `mcp_servers`
- `google-gemini-cli`: file pengaturan sistem Gemini yang dibuat otomatis
- `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 loopback yang mengekspos alat gateway ke proses CLI
- mengautentikasi jembatan dengan token per sesi (`OPENCLAW_MCP_TOKEN`)
- 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 config/pengaturan MCP backend yang sudah ada
- menulis ulang config peluncuran menggunakan mode integrasi yang dimiliki backend dari extension pemilik
- 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 config ketat ketika
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 langsung.** OpenClaw tidak menyuntikkan pemanggilan alat ke
protokol backend CLI. Backend hanya melihat alat gateway saat mereka ikut serta
dalam `bundleMcp: true`.
- **Streaming bersifat khusus backend.** Beberapa backend melakukan stream JSONL; yang lain menahan output
hingga proses selesai.
- **Output terstruktur** bergantung pada format JSON CLI.
- **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 dibandingkan eksekusi awal `--json`. Sesi OpenClaw tetap bekerja
terstruktur dibanding eksekusi awal `--json`. Sesi OpenClaw tetap bekerja
secara normal.
## Pemecahan masalah
- **CLI tidak ditemukan**: setel `command` ke path lengkap.
- **CLI tidak ditemukan**: atur `command` ke path lengkap.
- **Nama model salah**: gunakan `modelAliases` untuk memetakan `provider/model` → model CLI.
- **Tidak ada kelanjutan sesi**: pastikan `sessionArg` disetel dan `sessionMode` bukan
- **Tidak ada kesinambungan sesi**: pastikan `sessionArg` diatur dan `sessionMode` bukan
`none` (Codex CLI saat ini tidak dapat melanjutkan dengan output JSON).
- **Gambar diabaikan**: setel `imageArg` (dan verifikasi CLI mendukung path file).
- **Gambar diabaikan**: atur `imageArg` (dan verifikasi CLI mendukung path file).