chore(i18n): refresh id translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
67ee16d9d3
commit
2543340e26
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- Menyiapkan Zalo Personal untuk OpenClaw
|
||||
- Memecahkan masalah alur masuk atau pesan Zalo Personal
|
||||
- Men-debug login Zalo Personal atau alur pesan
|
||||
summary: Dukungan akun pribadi Zalo melalui zca-js native (login QR), kemampuan, dan konfigurasi
|
||||
title: Zalo pribadi
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T22:17:18Z"
|
||||
generated_at: "2026-05-04T18:23:31Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 0096775e0017e504130f2e19e05ab8114eadb873a9e11f79ea8f0dd91297567f
|
||||
source_hash: 0f6d27f0ca502e6426abe21d609efd0a168a0b6b0fafe8d52d59f1a717da1ed5
|
||||
source_path: channels/zalouser.md
|
||||
workflow: 16
|
||||
---
|
||||
@ -21,25 +21,25 @@ Ini adalah integrasi tidak resmi dan dapat mengakibatkan akun ditangguhkan atau
|
||||
|
||||
## Plugin bawaan
|
||||
|
||||
Zalo Personal disertakan sebagai Plugin bawaan dalam rilis OpenClaw saat ini, sehingga build
|
||||
terpaket normal tidak memerlukan instalasi terpisah.
|
||||
Zalo Personal dikirim sebagai Plugin bawaan dalam rilis OpenClaw saat ini, sehingga build
|
||||
paket normal tidak memerlukan instalasi terpisah.
|
||||
|
||||
Jika Anda menggunakan build lama atau instalasi kustom yang mengecualikan Zalo Personal,
|
||||
instal paket npm secara langsung:
|
||||
|
||||
- Instal melalui CLI: `openclaw plugins install @openclaw/zalouser`
|
||||
- Versi yang dipin: `openclaw plugins install @openclaw/zalouser@2026.5.2`
|
||||
- Versi yang dipatok: `openclaw plugins install @openclaw/zalouser@2026.5.2`
|
||||
- Atau dari checkout sumber: `openclaw plugins install ./path/to/local/zalouser-plugin`
|
||||
- Detail: [Plugins](/id/tools/plugin)
|
||||
- Detail: [Plugin](/id/tools/plugin)
|
||||
|
||||
Tidak diperlukan binary CLI eksternal `zca`/`openzca`.
|
||||
Binary CLI eksternal `zca`/`openzca` tidak diperlukan.
|
||||
|
||||
## Penyiapan cepat (pemula)
|
||||
|
||||
1. Pastikan Plugin Zalo Personal tersedia.
|
||||
- Rilis OpenClaw terpaket saat ini sudah menyertakannya.
|
||||
- Rilis OpenClaw paket saat ini sudah membundelnya.
|
||||
- Instalasi lama/kustom dapat menambahkannya secara manual dengan perintah di atas.
|
||||
2. Login (QR, pada mesin Gateway):
|
||||
2. Login (QR, di mesin Gateway):
|
||||
- `openclaw channels login --channel zalouser`
|
||||
- Pindai kode QR dengan aplikasi seluler Zalo.
|
||||
3. Aktifkan channel:
|
||||
@ -62,12 +62,12 @@ Tidak diperlukan binary CLI eksternal `zca`/`openzca`.
|
||||
|
||||
- Berjalan sepenuhnya dalam proses melalui `zca-js`.
|
||||
- Menggunakan listener event native untuk menerima pesan masuk.
|
||||
- Mengirim balasan langsung melalui API JS (teks/media/tautan).
|
||||
- Mengirim balasan langsung melalui JS API (teks/media/link).
|
||||
- Dirancang untuk kasus penggunaan “akun pribadi” ketika Zalo Bot API tidak tersedia.
|
||||
|
||||
## Penamaan
|
||||
|
||||
ID channel adalah `zalouser` untuk memperjelas bahwa ini mengotomatiskan **akun pengguna Zalo pribadi** (tidak resmi). Kami mempertahankan `zalo` untuk kemungkinan integrasi API Zalo resmi di masa mendatang.
|
||||
ID channel adalah `zalouser` untuk memperjelas bahwa ini mengotomatiskan **akun pengguna Zalo pribadi** (tidak resmi). Kami menjaga `zalo` tetap dicadangkan untuk kemungkinan integrasi Zalo API resmi di masa mendatang.
|
||||
|
||||
## Menemukan ID (direktori)
|
||||
|
||||
@ -81,14 +81,16 @@ openclaw directory groups list --channel zalouser --query "work"
|
||||
|
||||
## Batasan
|
||||
|
||||
- Teks keluar dipecah menjadi potongan sekitar 2000 karakter (batas klien Zalo).
|
||||
- Teks keluar dipecah menjadi sekitar 2000 karakter (batas klien Zalo).
|
||||
- Streaming diblokir secara default.
|
||||
|
||||
## Kontrol akses (DM)
|
||||
|
||||
`channels.zalouser.dmPolicy` mendukung: `pairing | allowlist | open | disabled` (default: `pairing`).
|
||||
|
||||
`channels.zalouser.allowFrom` menerima ID pengguna atau nama. Selama penyiapan, nama diselesaikan menjadi ID menggunakan lookup kontak dalam proses milik Plugin.
|
||||
`channels.zalouser.allowFrom` sebaiknya menggunakan ID pengguna Zalo yang stabil. Selama penyiapan interaktif, nama yang dimasukkan dapat di-resolve ke ID menggunakan pencarian kontak dalam proses milik Plugin.
|
||||
|
||||
Jika nama mentah tetap ada di config, startup hanya me-resolve-nya ketika `channels.zalouser.dangerouslyAllowNameMatching: true` diaktifkan. Tanpa opt-in itu, pemeriksaan pengirim runtime hanya berbasis ID dan nama mentah diabaikan untuk otorisasi.
|
||||
|
||||
Setujui melalui:
|
||||
|
||||
@ -97,16 +99,16 @@ Setujui melalui:
|
||||
|
||||
## Akses grup (opsional)
|
||||
|
||||
- Default: `channels.zalouser.groupPolicy = "open"` (grup diizinkan). Gunakan `channels.defaults.groupPolicy` untuk menimpa default ketika belum diatur.
|
||||
- Default: `channels.zalouser.groupPolicy = "open"` (grup diizinkan). Gunakan `channels.defaults.groupPolicy` untuk mengganti default ketika belum diatur.
|
||||
- Batasi ke allowlist dengan:
|
||||
- `channels.zalouser.groupPolicy = "allowlist"`
|
||||
- `channels.zalouser.groups` (key sebaiknya berupa ID grup yang stabil; nama diselesaikan menjadi ID saat startup jika memungkinkan)
|
||||
- `channels.zalouser.groups` (key sebaiknya berupa ID grup yang stabil; nama di-resolve ke ID saat startup hanya ketika `channels.zalouser.dangerouslyAllowNameMatching: true` diaktifkan)
|
||||
- `channels.zalouser.groupAllowFrom` (mengontrol pengirim mana dalam grup yang diizinkan yang dapat memicu bot)
|
||||
- Blokir semua grup: `channels.zalouser.groupPolicy = "disabled"`.
|
||||
- Wizard konfigurasi dapat meminta allowlist grup.
|
||||
- Saat startup, OpenClaw menyelesaikan nama grup/pengguna dalam allowlist menjadi ID dan mencatat pemetaannya di log.
|
||||
- Pencocokan allowlist grup secara default hanya berdasarkan ID. Nama yang tidak terselesaikan diabaikan untuk auth kecuali `channels.zalouser.dangerouslyAllowNameMatching: true` diaktifkan.
|
||||
- `channels.zalouser.dangerouslyAllowNameMatching: true` adalah mode kompatibilitas break-glass yang mengaktifkan kembali pencocokan nama grup yang dapat berubah.
|
||||
- Saat startup, OpenClaw me-resolve nama grup/pengguna dalam allowlist ke ID dan mencatat mapping hanya ketika `channels.zalouser.dangerouslyAllowNameMatching: true` diaktifkan.
|
||||
- Pencocokan allowlist grup hanya berbasis ID secara default. Nama yang tidak ter-resolve diabaikan untuk auth kecuali `channels.zalouser.dangerouslyAllowNameMatching: true` diaktifkan.
|
||||
- `channels.zalouser.dangerouslyAllowNameMatching: true` adalah mode kompatibilitas break-glass yang mengaktifkan kembali resolusi nama startup yang dapat berubah dan pencocokan nama grup runtime.
|
||||
- Jika `groupAllowFrom` belum diatur, runtime fallback ke `allowFrom` untuk pemeriksaan pengirim grup.
|
||||
- Pemeriksaan pengirim berlaku untuk pesan grup normal dan perintah kontrol (misalnya `/new`, `/reset`).
|
||||
|
||||
@ -127,15 +129,15 @@ Contoh:
|
||||
}
|
||||
```
|
||||
|
||||
### Gating mention grup
|
||||
### Gerbang mention grup
|
||||
|
||||
- `channels.zalouser.groups.<group>.requireMention` mengontrol apakah balasan grup memerlukan mention.
|
||||
- Urutan resolusi: ID/nama grup persis -> slug grup ternormalisasi -> `*` -> default (`true`).
|
||||
- Ini berlaku baik untuk grup dalam allowlist maupun mode grup terbuka.
|
||||
- Mengutip pesan bot dihitung sebagai mention implisit untuk aktivasi grup.
|
||||
- Perintah kontrol yang terotorisasi (misalnya `/new`) dapat melewati gating mention.
|
||||
- Ketika pesan grup dilewati karena mention diperlukan, OpenClaw menyimpannya sebagai riwayat grup tertunda dan menyertakannya pada pesan grup berikutnya yang diproses.
|
||||
- Batas riwayat grup default ke `messages.groupChat.historyLimit` (fallback `50`). Anda dapat menimpanya per akun dengan `channels.zalouser.historyLimit`.
|
||||
- Perintah kontrol terotorisasi (misalnya `/new`) dapat melewati gerbang mention.
|
||||
- Ketika pesan grup dilewati karena mention diperlukan, OpenClaw menyimpannya sebagai riwayat grup pending dan menyertakannya pada pesan grup berikutnya yang diproses.
|
||||
- Batas riwayat grup default ke `messages.groupChat.historyLimit` (fallback `50`). Anda dapat mengganti per akun dengan `channels.zalouser.historyLimit`.
|
||||
|
||||
Contoh:
|
||||
|
||||
@ -171,34 +173,34 @@ Akun dipetakan ke profil `zalouser` dalam state OpenClaw. Contoh:
|
||||
}
|
||||
```
|
||||
|
||||
## Pengetikan, reaksi, dan pengakuan pengiriman
|
||||
## Pengetikan, reaksi, dan acknowledgement pengiriman
|
||||
|
||||
- OpenClaw mengirim event pengetikan sebelum mengirim balasan (upaya terbaik).
|
||||
- Action reaksi pesan `react` didukung untuk `zalouser` dalam action channel.
|
||||
- Gunakan `remove: true` untuk menghapus emoji reaksi tertentu dari sebuah pesan.
|
||||
- OpenClaw mengirim event pengetikan sebelum mengirimkan balasan (best-effort).
|
||||
- Aksi reaksi pesan `react` didukung untuk `zalouser` dalam aksi channel.
|
||||
- Gunakan `remove: true` untuk menghapus emoji reaksi tertentu dari pesan.
|
||||
- Semantik reaksi: [Reaksi](/id/tools/reactions)
|
||||
- Untuk pesan masuk yang menyertakan metadata event, OpenClaw mengirim pengakuan terkirim + terlihat (upaya terbaik).
|
||||
- Untuk pesan masuk yang menyertakan metadata event, OpenClaw mengirim acknowledgement terkirim + terlihat (best-effort).
|
||||
|
||||
## Pemecahan masalah
|
||||
|
||||
**Login tidak tersimpan:**
|
||||
**Login tidak bertahan:**
|
||||
|
||||
- `openclaw channels status --probe`
|
||||
- Login ulang: `openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser`
|
||||
|
||||
**Allowlist/nama grup tidak terselesaikan:**
|
||||
**Nama allowlist/grup tidak ter-resolve:**
|
||||
|
||||
- Gunakan ID numerik di `allowFrom`/`groupAllowFrom`/`groups`, atau nama teman/grup yang persis.
|
||||
- Gunakan ID numerik di `allowFrom`/`groupAllowFrom` dan ID grup yang stabil di `groups`. Jika Anda memang membutuhkan nama teman/grup yang persis, aktifkan `channels.zalouser.dangerouslyAllowNameMatching: true`.
|
||||
|
||||
**Di-upgrade dari penyiapan lama berbasis CLI:**
|
||||
**Ditingkatkan dari penyiapan lama berbasis CLI:**
|
||||
|
||||
- Hapus asumsi proses `zca` eksternal lama apa pun.
|
||||
- Hapus asumsi proses eksternal `zca` lama.
|
||||
- Channel sekarang berjalan sepenuhnya di OpenClaw tanpa binary CLI eksternal.
|
||||
|
||||
## Terkait
|
||||
|
||||
- [Ikhtisar Channel](/id/channels) — semua channel yang didukung
|
||||
- [Pairing](/id/channels/pairing) — autentikasi DM dan alur pairing
|
||||
- [Grup](/id/channels/groups) — perilaku chat grup dan gating mention
|
||||
- [Grup](/id/channels/groups) — perilaku chat grup dan gerbang mention
|
||||
- [Perutean Channel](/id/channels/channel-routing) — perutean sesi untuk pesan
|
||||
- [Keamanan](/id/gateway/security) — model akses dan hardening
|
||||
|
||||
@ -3,12 +3,12 @@ read_when:
|
||||
- Anda masih menggunakan `openclaw daemon ...` dalam skrip
|
||||
- Anda memerlukan perintah siklus hidup layanan (install/start/stop/restart/status)
|
||||
summary: Referensi CLI untuk `openclaw daemon` (alias lama untuk pengelolaan layanan Gateway)
|
||||
title: Daemon
|
||||
title: Proses latar belakang
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T22:17:40Z"
|
||||
generated_at: "2026-05-04T18:23:35Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 3f11b75bf2781e69f6f59b23364f06cf359f9f24407f25f19b9d2186f7158512
|
||||
source_hash: f84e11fc50bdf38da518a8fcf415ae461a2688c2299f996eee384357c0d04a05
|
||||
source_path: cli/daemon.md
|
||||
workflow: 16
|
||||
---
|
||||
@ -17,7 +17,7 @@ x-i18n:
|
||||
|
||||
Alias lama untuk perintah pengelolaan layanan Gateway.
|
||||
|
||||
`openclaw daemon ...` dipetakan ke permukaan kontrol layanan yang sama seperti perintah layanan `openclaw gateway ...`.
|
||||
`openclaw daemon ...` dipetakan ke permukaan kontrol layanan yang sama dengan perintah layanan `openclaw gateway ...`.
|
||||
|
||||
## Penggunaan
|
||||
|
||||
@ -43,25 +43,26 @@ openclaw daemon uninstall
|
||||
|
||||
- `status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json`
|
||||
- `install`: `--port`, `--runtime <node|bun>`, `--token`, `--force`, `--json`
|
||||
- `restart`: `--force`, `--wait <duration>`, `--json`
|
||||
- `restart`: `--safe`, `--force`, `--wait <duration>`, `--json`
|
||||
- siklus hidup (`uninstall|start|stop`): `--json`
|
||||
|
||||
Catatan:
|
||||
|
||||
- `status` menyelesaikan SecretRefs autentikasi yang dikonfigurasi untuk autentikasi pemeriksaan jika memungkinkan.
|
||||
- Jika SecretRef autentikasi yang diperlukan tidak terselesaikan di jalur perintah ini, `daemon status --json` melaporkan `rpc.authWarning` saat konektivitas/autentikasi pemeriksaan gagal; berikan `--token`/`--password` secara eksplisit atau selesaikan sumber rahasia terlebih dahulu.
|
||||
- Jika pemeriksaan berhasil, peringatan auth-ref yang belum terselesaikan disembunyikan untuk menghindari positif palsu.
|
||||
- `status --deep` menambahkan pemindaian layanan tingkat sistem dengan upaya terbaik. Saat menemukan layanan lain yang mirip Gateway, keluaran untuk manusia mencetak petunjuk pembersihan dan memperingatkan bahwa satu Gateway per mesin masih menjadi rekomendasi normal.
|
||||
- Pada pemasangan systemd Linux, pemeriksaan token-drift `status` mencakup sumber unit `Environment=` dan `EnvironmentFile=`.
|
||||
- Jika pemeriksaan berhasil, peringatan auth-ref yang tidak terselesaikan ditekan untuk menghindari positif palsu.
|
||||
- `status --deep` menambahkan pemindaian layanan tingkat sistem dengan upaya terbaik. Saat menemukan layanan lain yang mirip Gateway, keluaran untuk manusia menampilkan petunjuk pembersihan dan memperingatkan bahwa satu Gateway per mesin tetap menjadi rekomendasi normal.
|
||||
- Pada pemasangan systemd Linux, pemeriksaan drift token `status` mencakup sumber unit `Environment=` dan `EnvironmentFile=`.
|
||||
- Pemeriksaan drift menyelesaikan SecretRefs `gateway.auth.token` menggunakan env runtime gabungan (env perintah layanan terlebih dahulu, lalu fallback env proses).
|
||||
- Jika autentikasi token tidak aktif secara efektif (`gateway.auth.mode` eksplisit berupa `password`/`none`/`trusted-proxy`, atau mode tidak disetel ketika kata sandi dapat menang dan tidak ada kandidat token yang dapat menang), pemeriksaan token-drift melewati penyelesaian token konfigurasi.
|
||||
- Jika autentikasi token tidak aktif secara efektif (`gateway.auth.mode` eksplisit berupa `password`/`none`/`trusted-proxy`, atau mode tidak disetel saat kata sandi dapat menang dan tidak ada kandidat token yang dapat menang), pemeriksaan drift token melewati penyelesaian token config.
|
||||
- Saat autentikasi token memerlukan token dan `gateway.auth.token` dikelola SecretRef, `install` memvalidasi bahwa SecretRef dapat diselesaikan tetapi tidak mempertahankan token yang terselesaikan ke metadata lingkungan layanan.
|
||||
- Jika autentikasi token memerlukan token dan SecretRef token yang dikonfigurasi tidak terselesaikan, pemasangan gagal tertutup.
|
||||
- Jika `gateway.auth.token` dan `gateway.auth.password` sama-sama dikonfigurasi dan `gateway.auth.mode` tidak disetel, pemasangan diblokir hingga mode disetel secara eksplisit.
|
||||
- Pada macOS, `install` menjaga plist LaunchAgent hanya untuk pemilik dan memuat nilai lingkungan layanan terkelola melalui file dan pembungkus khusus pemilik, alih-alih menserialisasi kunci API atau ref env profil autentikasi ke dalam `EnvironmentVariables`.
|
||||
- Jika Anda sengaja menjalankan beberapa Gateway pada satu host, isolasikan port, konfigurasi/status, dan workspace; lihat [/gateway#multiple-gateways-same-host](/id/gateway#multiple-gateways-same-host).
|
||||
- Jika `gateway.auth.token` dan `gateway.auth.password` sama-sama dikonfigurasi dan `gateway.auth.mode` tidak disetel, pemasangan diblokir sampai mode disetel secara eksplisit.
|
||||
- Pada macOS, `install` menjaga plist LaunchAgent hanya dimiliki pemilik dan memuat nilai lingkungan layanan terkelola melalui file dan wrapper khusus pemilik, bukan menyerialkan kunci API atau ref env auth-profile ke dalam `EnvironmentVariables`.
|
||||
- Jika Anda sengaja menjalankan beberapa Gateway pada satu host, isolasi port, config/status, dan workspace; lihat [/gateway#multiple-gateways-same-host](/id/gateway#multiple-gateways-same-host).
|
||||
- `restart --safe` meminta Gateway yang sedang berjalan untuk melakukan preflight pekerjaan aktif dan menjadwalkan satu mulai ulang tergabung setelah pekerjaan aktif selesai. `restart` biasa mempertahankan perilaku pengelola layanan yang ada; `--force` tetap menjadi jalur override langsung.
|
||||
|
||||
## Lebih disarankan
|
||||
## Disarankan
|
||||
|
||||
Gunakan [`openclaw gateway`](/id/cli/gateway) untuk dokumentasi dan contoh saat ini.
|
||||
|
||||
|
||||
@ -1,30 +1,30 @@
|
||||
---
|
||||
read_when:
|
||||
- Menjalankan Gateway dari CLI (pengembangan atau server)
|
||||
- Men-debug autentikasi Gateway, mode bind, dan konektivitas
|
||||
- Men-debug autentikasi Gateway, mode pengikatan, dan konektivitas
|
||||
- Menemukan Gateway melalui Bonjour (DNS-SD lokal + area luas)
|
||||
sidebarTitle: Gateway
|
||||
summary: OpenClaw Gateway CLI (`openclaw gateway`) — jalankan, kueri, dan temukan Gateway
|
||||
title: Gateway
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T22:17:48Z"
|
||||
generated_at: "2026-05-04T18:23:42Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: f7f948a8f0ee6e065afa02f354e690ad5cc4f71bdb8b8674f1b0396c439ab242
|
||||
source_hash: 310867c59148577f2e8ce6f708da6bce936e09243ce7fbe5daeb453c6b3b370d
|
||||
source_path: cli/gateway.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Gateway adalah server WebSocket OpenClaw (channels, nodes, sessions, hooks). Subperintah di halaman ini berada di bawah `openclaw gateway …`.
|
||||
Gateway adalah server WebSocket OpenClaw (saluran, node, sesi, hook). Subperintah di halaman ini berada di bawah `openclaw gateway …`.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Bonjour discovery" href="/id/gateway/bonjour">
|
||||
<Card title="Penemuan Bonjour" href="/id/gateway/bonjour">
|
||||
Penyiapan mDNS lokal + DNS-SD area luas.
|
||||
</Card>
|
||||
<Card title="Discovery overview" href="/id/gateway/discovery">
|
||||
<Card title="Ikhtisar penemuan" href="/id/gateway/discovery">
|
||||
Cara OpenClaw mengiklankan dan menemukan gateway.
|
||||
</Card>
|
||||
<Card title="Configuration" href="/id/gateway/configuration">
|
||||
<Card title="Konfigurasi" href="/id/gateway/configuration">
|
||||
Kunci konfigurasi gateway tingkat atas.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@ -44,12 +44,12 @@ openclaw gateway run
|
||||
```
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Startup behavior">
|
||||
- Secara default, Gateway menolak untuk dimulai kecuali `gateway.mode=local` diatur di `~/.openclaw/openclaw.json`. Gunakan `--allow-unconfigured` untuk proses ad-hoc/dev.
|
||||
- `openclaw onboard --mode local` dan `openclaw setup` diharapkan menulis `gateway.mode=local`. Jika file ada tetapi `gateway.mode` hilang, perlakukan itu sebagai konfigurasi yang rusak atau tertimpa dan perbaiki, alih-alih mengasumsikan mode lokal secara implisit.
|
||||
- Jika file ada dan `gateway.mode` hilang, Gateway memperlakukannya sebagai kerusakan konfigurasi yang mencurigakan dan menolak untuk "menebak lokal" untuk Anda.
|
||||
- Binding di luar loopback tanpa auth diblokir (pembatas keamanan).
|
||||
- `SIGUSR1` memicu restart dalam proses saat diotorisasi (`commands.restart` diaktifkan secara default; atur `commands.restart: false` untuk memblokir restart manual, sementara apply/update tool/config gateway tetap diizinkan).
|
||||
<Accordion title="Perilaku startup">
|
||||
- Secara default, Gateway menolak untuk dimulai kecuali `gateway.mode=local` diatur di `~/.openclaw/openclaw.json`. Gunakan `--allow-unconfigured` untuk eksekusi ad-hoc/dev.
|
||||
- `openclaw onboard --mode local` dan `openclaw setup` diharapkan menulis `gateway.mode=local`. Jika file ada tetapi `gateway.mode` tidak ada, perlakukan itu sebagai konfigurasi yang rusak atau tertimpa dan perbaiki, alih-alih mengasumsikan mode lokal secara implisit.
|
||||
- Jika file ada dan `gateway.mode` tidak ada, Gateway memperlakukan itu sebagai kerusakan konfigurasi yang mencurigakan dan menolak untuk "menebak lokal" untuk Anda.
|
||||
- Binding di luar loopback tanpa autentikasi diblokir (pagar pengaman).
|
||||
- `SIGUSR1` memicu restart dalam proses saat diotorisasi (`commands.restart` diaktifkan secara default; atur `commands.restart: false` untuk memblokir restart manual, sementara penerapan/pembaruan alat/konfigurasi gateway tetap diizinkan).
|
||||
- Handler `SIGINT`/`SIGTERM` menghentikan proses gateway, tetapi tidak memulihkan status terminal kustom apa pun. Jika Anda membungkus CLI dengan TUI atau input raw-mode, pulihkan terminal sebelum keluar.
|
||||
|
||||
</Accordion>
|
||||
@ -58,13 +58,13 @@ openclaw gateway run
|
||||
### Opsi
|
||||
|
||||
<ParamField path="--port <port>" type="number">
|
||||
Port WebSocket (default berasal dari config/env; biasanya `18789`).
|
||||
Port WebSocket (default berasal dari konfigurasi/env; biasanya `18789`).
|
||||
</ParamField>
|
||||
<ParamField path="--bind <loopback|lan|tailnet|auto|custom>" type="string">
|
||||
Mode bind listener.
|
||||
</ParamField>
|
||||
<ParamField path="--auth <token|password>" type="string">
|
||||
Override mode auth.
|
||||
Override mode autentikasi.
|
||||
</ParamField>
|
||||
<ParamField path="--token <token>" type="string">
|
||||
Override token (juga mengatur `OPENCLAW_GATEWAY_TOKEN` untuk proses).
|
||||
@ -79,19 +79,19 @@ openclaw gateway run
|
||||
Ekspos Gateway melalui Tailscale.
|
||||
</ParamField>
|
||||
<ParamField path="--tailscale-reset-on-exit" type="boolean">
|
||||
Reset config serve/funnel Tailscale saat shutdown.
|
||||
Reset konfigurasi serve/funnel Tailscale saat shutdown.
|
||||
</ParamField>
|
||||
<ParamField path="--allow-unconfigured" type="boolean">
|
||||
Izinkan gateway dimulai tanpa `gateway.mode=local` dalam config. Hanya melewati guard startup untuk bootstrap ad-hoc/dev; tidak menulis atau memperbaiki file config.
|
||||
Izinkan gateway dimulai tanpa `gateway.mode=local` dalam konfigurasi. Hanya melewati guard startup untuk bootstrap ad-hoc/dev; tidak menulis atau memperbaiki file konfigurasi.
|
||||
</ParamField>
|
||||
<ParamField path="--dev" type="boolean">
|
||||
Buat config dev + workspace jika belum ada (melewati BOOTSTRAP.md).
|
||||
Buat konfigurasi dev + ruang kerja jika tidak ada (melewati BOOTSTRAP.md).
|
||||
</ParamField>
|
||||
<ParamField path="--reset" type="boolean">
|
||||
Reset config dev + kredensial + sesi + workspace (memerlukan `--dev`).
|
||||
Reset konfigurasi dev + kredensial + sesi + ruang kerja (memerlukan `--dev`).
|
||||
</ParamField>
|
||||
<ParamField path="--force" type="boolean">
|
||||
Matikan listener yang sudah ada di port yang dipilih sebelum memulai.
|
||||
Matikan listener yang ada pada port yang dipilih sebelum memulai.
|
||||
</ParamField>
|
||||
<ParamField path="--verbose" type="boolean">
|
||||
Log verbose.
|
||||
@ -100,51 +100,61 @@ openclaw gateway run
|
||||
Hanya tampilkan log backend CLI di konsol (dan aktifkan stdout/stderr).
|
||||
</ParamField>
|
||||
<ParamField path="--ws-log <auto|full|compact>" type="string" default="auto">
|
||||
Gaya log WebSocket.
|
||||
Gaya log Websocket.
|
||||
</ParamField>
|
||||
<ParamField path="--compact" type="boolean">
|
||||
Alias untuk `--ws-log compact`.
|
||||
</ParamField>
|
||||
<ParamField path="--raw-stream" type="boolean">
|
||||
Catat event stream model mentah ke jsonl.
|
||||
Catat peristiwa stream model mentah ke jsonl.
|
||||
</ParamField>
|
||||
<ParamField path="--raw-stream-path <path>" type="string">
|
||||
Path jsonl stream mentah.
|
||||
</ParamField>
|
||||
|
||||
## Restart Gateway
|
||||
|
||||
```bash
|
||||
openclaw gateway restart
|
||||
openclaw gateway restart --safe
|
||||
openclaw gateway restart --force
|
||||
```
|
||||
|
||||
`openclaw gateway restart --safe` meminta Gateway yang sedang berjalan untuk melakukan preflight pekerjaan OpenClaw yang aktif sebelum restart. Jika operasi antrean, pengiriman balasan, eksekusi tertanam, atau eksekusi tugas aktif, Gateway melaporkan pemblokirnya, menggabungkan permintaan restart aman yang duplikat, dan restart setelah pekerjaan aktif selesai. `restart` biasa mempertahankan perilaku manajer layanan yang ada untuk kompatibilitas. Gunakan `--force` hanya saat Anda secara eksplisit menginginkan jalur override segera.
|
||||
|
||||
<Warning>
|
||||
`--password` inline dapat terekspos dalam daftar proses lokal. Lebih baik gunakan `--password-file`, env, atau `gateway.auth.password` yang didukung SecretRef.
|
||||
`--password` inline dapat terlihat dalam daftar proses lokal. Lebih baik gunakan `--password-file`, env, atau `gateway.auth.password` yang didukung SecretRef.
|
||||
</Warning>
|
||||
|
||||
### Profiling startup
|
||||
|
||||
- Atur `OPENCLAW_GATEWAY_STARTUP_TRACE=1` untuk mencatat timing fase selama startup Gateway, termasuk delay `eventLoopMax` per fase dan timing lookup table plugin untuk installed-index, manifest registry, startup planning, dan pekerjaan owner-map.
|
||||
- Atur `OPENCLAW_DIAGNOSTICS=timeline` dengan `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>` untuk menulis timeline diagnostik startup JSONL best-effort bagi harness QA eksternal. Anda juga dapat mengaktifkan flag dengan `diagnostics.flags: ["timeline"]` dalam config; path tetap diberikan melalui env. Tambahkan `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` untuk menyertakan sampel event-loop.
|
||||
- Jalankan `pnpm test:startup:gateway -- --runs 5 --warmup 1` untuk melakukan benchmark startup Gateway. Benchmark mencatat output proses pertama, `/healthz`, `/readyz`, timing trace startup, delay event-loop, dan detail timing lookup table plugin.
|
||||
- Atur `OPENCLAW_GATEWAY_STARTUP_TRACE=1` untuk mencatat timing fase selama startup Gateway, termasuk penundaan `eventLoopMax` per fase dan timing tabel lookup plugin untuk installed-index, registri manifest, perencanaan startup, dan pekerjaan owner-map.
|
||||
- Atur `OPENCLAW_DIAGNOSTICS=timeline` dengan `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>` untuk menulis timeline diagnostik startup JSONL best-effort untuk harness QA eksternal. Anda juga dapat mengaktifkan flag dengan `diagnostics.flags: ["timeline"]` dalam konfigurasi; path tetap disediakan melalui env. Tambahkan `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` untuk menyertakan sampel event-loop.
|
||||
- Jalankan `pnpm test:startup:gateway -- --runs 5 --warmup 1` untuk melakukan benchmark startup Gateway. Benchmark merekam output proses pertama, `/healthz`, `/readyz`, timing trace startup, penundaan event-loop, dan detail timing tabel lookup plugin.
|
||||
|
||||
## Kueri Gateway yang sedang berjalan
|
||||
|
||||
Semua perintah kueri menggunakan RPC WebSocket.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Output modes">
|
||||
<Tab title="Mode output">
|
||||
- Default: mudah dibaca manusia (berwarna di TTY).
|
||||
- `--json`: JSON yang dapat dibaca mesin (tanpa styling/spinner).
|
||||
- `--json`: JSON yang dapat dibaca mesin (tanpa gaya/spinner).
|
||||
- `--no-color` (atau `NO_COLOR=1`): nonaktifkan ANSI sambil mempertahankan tata letak manusia.
|
||||
|
||||
</Tab>
|
||||
<Tab title="Shared options">
|
||||
<Tab title="Opsi bersama">
|
||||
- `--url <url>`: URL WebSocket Gateway.
|
||||
- `--token <token>`: token Gateway.
|
||||
- `--password <password>`: kata sandi Gateway.
|
||||
- `--timeout <ms>`: timeout/anggaran (bervariasi per perintah).
|
||||
- `--expect-final`: tunggu respons "final" (panggilan agent).
|
||||
- `--timeout <ms>`: timeout/anggaran (berbeda per perintah).
|
||||
- `--expect-final`: tunggu respons "final" (panggilan agen).
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
<Note>
|
||||
Saat Anda mengatur `--url`, CLI tidak fallback ke config atau kredensial environment. Teruskan `--token` atau `--password` secara eksplisit. Kredensial eksplisit yang hilang adalah error.
|
||||
Saat Anda mengatur `--url`, CLI tidak fallback ke kredensial konfigurasi atau lingkungan. Berikan `--token` atau `--password` secara eksplisit. Kredensial eksplisit yang tidak ada adalah error.
|
||||
</Note>
|
||||
|
||||
### `gateway health`
|
||||
@ -153,7 +163,7 @@ Saat Anda mengatur `--url`, CLI tidak fallback ke config atau kredensial environ
|
||||
openclaw gateway health --url ws://127.0.0.1:18789
|
||||
```
|
||||
|
||||
Endpoint HTTP `/healthz` adalah probe liveness: endpoint ini mengembalikan respons setelah server dapat menjawab HTTP. Endpoint HTTP `/readyz` lebih ketat dan tetap merah saat sidecar plugin startup, channel, atau hook yang dikonfigurasi masih stabil. Respons readiness terperinci yang lokal atau terautentikasi menyertakan blok diagnostik `eventLoop` dengan delay event-loop, utilisasi event-loop, rasio core CPU, dan flag `degraded`.
|
||||
Endpoint HTTP `/healthz` adalah probe liveness: endpoint ini kembali setelah server dapat menjawab HTTP. Endpoint HTTP `/readyz` lebih ketat dan tetap merah saat sidecar plugin startup, saluran, atau hook yang dikonfigurasi masih stabil. Respons readiness detail lokal atau terautentikasi menyertakan blok diagnostik `eventLoop` dengan penundaan event-loop, utilisasi event-loop, rasio core CPU, dan flag `degraded`.
|
||||
|
||||
### `gateway usage-cost`
|
||||
|
||||
@ -166,7 +176,7 @@ openclaw gateway usage-cost --json
|
||||
```
|
||||
|
||||
<ParamField path="--days <days>" type="number" default="30">
|
||||
Jumlah hari yang disertakan.
|
||||
Jumlah hari yang akan disertakan.
|
||||
</ParamField>
|
||||
|
||||
### `gateway stability`
|
||||
@ -182,16 +192,16 @@ openclaw gateway stability --json
|
||||
```
|
||||
|
||||
<ParamField path="--limit <limit>" type="number" default="25">
|
||||
Jumlah maksimum event terbaru yang disertakan (maks `1000`).
|
||||
Jumlah maksimum peristiwa terbaru yang disertakan (maks `1000`).
|
||||
</ParamField>
|
||||
<ParamField path="--type <type>" type="string">
|
||||
Filter berdasarkan tipe event diagnostik, seperti `payload.large` atau `diagnostic.memory.pressure`.
|
||||
Filter berdasarkan jenis peristiwa diagnostik, seperti `payload.large` atau `diagnostic.memory.pressure`.
|
||||
</ParamField>
|
||||
<ParamField path="--since-seq <seq>" type="number">
|
||||
Hanya sertakan event setelah nomor urutan diagnostik.
|
||||
Sertakan hanya peristiwa setelah nomor urut diagnostik.
|
||||
</ParamField>
|
||||
<ParamField path="--bundle [path]" type="string">
|
||||
Baca bundle stabilitas yang dipersist alih-alih memanggil Gateway yang sedang berjalan. Gunakan `--bundle latest` (atau cukup `--bundle`) untuk bundle terbaru di bawah direktori status, atau teruskan path JSON bundle secara langsung.
|
||||
Baca bundle stabilitas yang dipersistenkan alih-alih memanggil Gateway yang sedang berjalan. Gunakan `--bundle latest` (atau cukup `--bundle`) untuk bundle terbaru di bawah direktori status, atau berikan path JSON bundle secara langsung.
|
||||
</ParamField>
|
||||
<ParamField path="--export" type="boolean">
|
||||
Tulis zip diagnostik dukungan yang dapat dibagikan alih-alih mencetak detail stabilitas.
|
||||
@ -201,9 +211,9 @@ openclaw gateway stability --json
|
||||
</ParamField>
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Privacy and bundle behavior">
|
||||
- Record menyimpan metadata operasional: nama event, hitungan, ukuran byte, pembacaan memori, status antrean/sesi, nama channel/plugin, dan ringkasan sesi yang diredaksi. Record tidak menyimpan teks chat, body webhook, output tool, body request atau respons mentah, token, cookie, nilai rahasia, hostname, atau id sesi mentah. Atur `diagnostics.enabled: false` untuk menonaktifkan perekam sepenuhnya.
|
||||
- Saat Gateway keluar secara fatal, timeout shutdown, dan kegagalan startup restart, OpenClaw menulis snapshot diagnostik yang sama ke `~/.openclaw/logs/stability/openclaw-stability-*.json` saat perekam memiliki event. Periksa bundle terbaru dengan `openclaw gateway stability --bundle latest`; `--limit`, `--type`, dan `--since-seq` juga berlaku untuk output bundle.
|
||||
<Accordion title="Privasi dan perilaku bundle">
|
||||
- Catatan menyimpan metadata operasional: nama peristiwa, hitungan, ukuran byte, pembacaan memori, status antrean/sesi, nama saluran/plugin, dan ringkasan sesi yang disunting. Catatan tidak menyimpan teks chat, body webhook, output alat, body permintaan atau respons mentah, token, cookie, nilai rahasia, hostname, atau id sesi mentah. Atur `diagnostics.enabled: false` untuk menonaktifkan perekam sepenuhnya.
|
||||
- Pada exit Gateway yang fatal, timeout shutdown, dan kegagalan startup restart, OpenClaw menulis snapshot diagnostik yang sama ke `~/.openclaw/logs/stability/openclaw-stability-*.json` saat perekam memiliki peristiwa. Periksa bundle terbaru dengan `openclaw gateway stability --bundle latest`; `--limit`, `--type`, dan `--since-seq` juga berlaku untuk output bundle.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -225,34 +235,34 @@ openclaw gateway diagnostics export --json
|
||||
Jumlah maksimum baris log tersanitasi yang disertakan.
|
||||
</ParamField>
|
||||
<ParamField path="--log-bytes <bytes>" type="number" default="1000000">
|
||||
Byte log maksimum untuk diperiksa.
|
||||
Jumlah maksimum byte log yang diperiksa.
|
||||
</ParamField>
|
||||
<ParamField path="--url <url>" type="string">
|
||||
URL WebSocket Gateway untuk snapshot health.
|
||||
URL WebSocket Gateway untuk snapshot kesehatan.
|
||||
</ParamField>
|
||||
<ParamField path="--token <token>" type="string">
|
||||
Token Gateway untuk snapshot health.
|
||||
Token Gateway untuk snapshot kesehatan.
|
||||
</ParamField>
|
||||
<ParamField path="--password <password>" type="string">
|
||||
Kata sandi Gateway untuk snapshot health.
|
||||
Kata sandi Gateway untuk snapshot kesehatan.
|
||||
</ParamField>
|
||||
<ParamField path="--timeout <ms>" type="number" default="3000">
|
||||
Timeout snapshot status/health.
|
||||
Timeout snapshot status/kesehatan.
|
||||
</ParamField>
|
||||
<ParamField path="--no-stability-bundle" type="boolean">
|
||||
Lewati pencarian bundle stabilitas yang dipersist.
|
||||
Lewati lookup bundle stabilitas yang dipersistenkan.
|
||||
</ParamField>
|
||||
<ParamField path="--json" type="boolean">
|
||||
Cetak path tertulis, ukuran, dan manifest sebagai JSON.
|
||||
</ParamField>
|
||||
|
||||
Ekspor berisi manifest, ringkasan Markdown, bentuk config, detail config tersanitasi, ringkasan log tersanitasi, snapshot status/health Gateway tersanitasi, dan bundle stabilitas terbaru jika ada.
|
||||
Ekspor berisi manifest, ringkasan Markdown, bentuk konfigurasi, detail konfigurasi tersanitasi, ringkasan log tersanitasi, snapshot status/kesehatan Gateway tersanitasi, dan bundle stabilitas terbaru jika ada.
|
||||
|
||||
Ekspor ini dimaksudkan untuk dibagikan. Ekspor menyimpan detail operasional yang membantu debugging, seperti field log OpenClaw yang aman, nama subsistem, kode status, durasi, mode yang dikonfigurasi, port, id plugin, id provider, pengaturan fitur non-rahasia, dan pesan log operasional yang diredaksi. Ekspor menghilangkan atau meredaksi teks chat, body webhook, output tool, kredensial, cookie, pengenal akun/pesan, teks prompt/instruksi, hostname, dan nilai rahasia. Saat pesan bergaya LogTape tampak seperti teks payload pengguna/chat/tool, ekspor hanya menyimpan bahwa pesan dihilangkan beserta jumlah byte-nya.
|
||||
Ekspor ini dimaksudkan untuk dibagikan. Ekspor menyimpan detail operasional yang membantu debugging, seperti field log OpenClaw yang aman, nama subsistem, kode status, durasi, mode yang dikonfigurasi, port, id plugin, id penyedia, pengaturan fitur non-rahasia, dan pesan log operasional yang disunting. Ekspor menghilangkan atau menyunting teks chat, body webhook, output alat, kredensial, cookie, pengidentifikasi akun/pesan, teks prompt/instruksi, hostname, dan nilai rahasia. Saat pesan bergaya LogTape terlihat seperti teks payload pengguna/chat/alat, ekspor hanya menyimpan bahwa pesan tersebut dihilangkan beserta jumlah byte-nya.
|
||||
|
||||
### `gateway status`
|
||||
|
||||
`gateway status` menampilkan layanan Gateway (launchd/systemd/schtasks) plus probe opsional untuk kemampuan konektivitas/auth.
|
||||
`gateway status` menampilkan layanan Gateway (launchd/systemd/schtasks) plus probe opsional untuk kemampuan konektivitas/autentikasi.
|
||||
|
||||
```bash
|
||||
openclaw gateway status
|
||||
@ -261,63 +271,63 @@ openclaw gateway status --require-rpc
|
||||
```
|
||||
|
||||
<ParamField path="--url <url>" type="string">
|
||||
Tambahkan target probe eksplisit. Remote yang dikonfigurasi + localhost tetap diprobe.
|
||||
Tambahkan target pemeriksaan eksplisit. Remote yang dikonfigurasi + localhost tetap diperiksa.
|
||||
</ParamField>
|
||||
<ParamField path="--token <token>" type="string">
|
||||
Auth token untuk probe.
|
||||
Autentikasi token untuk pemeriksaan.
|
||||
</ParamField>
|
||||
<ParamField path="--password <password>" type="string">
|
||||
Auth kata sandi untuk probe.
|
||||
Autentikasi kata sandi untuk pemeriksaan.
|
||||
</ParamField>
|
||||
<ParamField path="--timeout <ms>" type="number" default="10000">
|
||||
Timeout probe.
|
||||
Batas waktu pemeriksaan.
|
||||
</ParamField>
|
||||
<ParamField path="--no-probe" type="boolean">
|
||||
Lewati probe konektivitas (tampilan hanya layanan).
|
||||
Lewati pemeriksaan konektivitas (tampilan khusus layanan).
|
||||
</ParamField>
|
||||
<ParamField path="--deep" type="boolean">
|
||||
Pindai layanan tingkat sistem juga.
|
||||
Pindai juga layanan tingkat sistem.
|
||||
</ParamField>
|
||||
<ParamField path="--require-rpc" type="boolean">
|
||||
Tingkatkan probe konektivitas default menjadi probe baca dan keluar non-zero saat probe baca tersebut gagal. Tidak dapat digabungkan dengan `--no-probe`.
|
||||
Tingkatkan pemeriksaan konektivitas default menjadi pemeriksaan baca dan keluar dengan nilai bukan nol saat pemeriksaan baca tersebut gagal. Tidak dapat digabungkan dengan `--no-probe`.
|
||||
</ParamField>
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Semantik status">
|
||||
- `gateway status` tetap tersedia untuk diagnostik bahkan ketika konfigurasi CLI lokal hilang atau tidak valid.
|
||||
- `gateway status` bawaan membuktikan status layanan, koneksi WebSocket, dan kapabilitas autentikasi yang terlihat saat handshake. Perintah ini tidak membuktikan operasi baca/tulis/admin.
|
||||
- Probe diagnostik tidak melakukan mutasi untuk autentikasi perangkat pertama kali: probe menggunakan ulang token perangkat cache yang sudah ada jika tersedia, tetapi tidak membuat identitas perangkat CLI baru atau catatan pairing perangkat baca-saja baru hanya untuk memeriksa status.
|
||||
- `gateway status` menyelesaikan SecretRefs autentikasi yang dikonfigurasi untuk autentikasi probe jika memungkinkan.
|
||||
- Jika SecretRef autentikasi yang wajib tidak terselesaikan di jalur perintah ini, `gateway status --json` melaporkan `rpc.authWarning` ketika konektivitas/autentikasi probe gagal; berikan `--token`/`--password` secara eksplisit atau selesaikan sumber rahasia terlebih dahulu.
|
||||
- Jika probe berhasil, peringatan auth-ref yang tidak terselesaikan disembunyikan untuk menghindari positif palsu.
|
||||
- Gunakan `--require-rpc` dalam skrip dan otomasi ketika layanan yang mendengarkan saja tidak cukup dan Anda juga memerlukan panggilan RPC cakupan baca yang sehat.
|
||||
- `--deep` menambahkan pemindaian upaya terbaik untuk instalasi launchd/systemd/schtasks tambahan. Ketika beberapa layanan mirip gateway terdeteksi, keluaran manusia mencetak petunjuk pembersihan dan memperingatkan bahwa sebagian besar penyiapan sebaiknya menjalankan satu gateway per mesin.
|
||||
- Keluaran manusia menyertakan jalur log file yang telah diselesaikan ditambah snapshot jalur/validitas konfigurasi CLI-vs-service untuk membantu mendiagnosis drift profil atau state-dir.
|
||||
- `gateway status` tetap tersedia untuk diagnostik meskipun konfigurasi CLI lokal hilang atau tidak valid.
|
||||
- `gateway status` default membuktikan status layanan, koneksi WebSocket, dan kapabilitas autentikasi yang terlihat saat handshake. Ini tidak membuktikan operasi baca/tulis/admin.
|
||||
- Pemeriksaan diagnostik tidak mengubah apa pun untuk autentikasi perangkat pertama kali: pemeriksaan menggunakan ulang token perangkat yang sudah ada di cache saat tersedia, tetapi tidak membuat identitas perangkat CLI baru atau catatan pairing perangkat baca-saja hanya untuk memeriksa status.
|
||||
- `gateway status` menyelesaikan SecretRefs autentikasi yang dikonfigurasi untuk autentikasi pemeriksaan jika memungkinkan.
|
||||
- Jika SecretRef autentikasi yang diperlukan tidak terselesaikan di jalur perintah ini, `gateway status --json` melaporkan `rpc.authWarning` saat konektivitas/autentikasi pemeriksaan gagal; teruskan `--token`/`--password` secara eksplisit atau selesaikan sumber rahasia terlebih dahulu.
|
||||
- Jika pemeriksaan berhasil, peringatan auth-ref yang belum terselesaikan disembunyikan untuk menghindari positif palsu.
|
||||
- Gunakan `--require-rpc` dalam skrip dan otomatisasi saat layanan yang mendengarkan saja tidak cukup dan Anda juga memerlukan panggilan RPC cakupan baca yang sehat.
|
||||
- `--deep` menambahkan pemindaian upaya terbaik untuk instalasi launchd/systemd/schtasks tambahan. Saat beberapa layanan mirip gateway terdeteksi, output manusia mencetak petunjuk pembersihan dan memperingatkan bahwa sebagian besar penyiapan sebaiknya menjalankan satu gateway per mesin.
|
||||
- Output manusia menyertakan jalur log file yang terselesaikan ditambah snapshot jalur/validitas konfigurasi CLI-vs-layanan untuk membantu mendiagnosis penyimpangan profil atau state-dir.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Pemeriksaan auth-drift Linux systemd">
|
||||
- Pada instalasi Linux systemd, pemeriksaan drift autentikasi layanan membaca nilai `Environment=` dan `EnvironmentFile=` dari unit (termasuk `%h`, jalur berpetik, beberapa file, dan file opsional `-`).
|
||||
- Pemeriksaan drift menyelesaikan SecretRefs `gateway.auth.token` menggunakan env runtime gabungan (env perintah layanan terlebih dahulu, lalu fallback env proses).
|
||||
- Jika autentikasi token tidak aktif secara efektif (`gateway.auth.mode` eksplisit berupa `password`/`none`/`trusted-proxy`, atau mode tidak disetel ketika kata sandi dapat menang dan tidak ada kandidat token yang dapat menang), pemeriksaan token-drift melewati penyelesaian token konfigurasi.
|
||||
<Accordion title="Pemeriksaan penyimpangan autentikasi systemd Linux">
|
||||
- Pada instalasi systemd Linux, pemeriksaan penyimpangan autentikasi layanan membaca nilai `Environment=` dan `EnvironmentFile=` dari unit (termasuk `%h`, jalur bertanda kutip, beberapa file, dan file opsional `-`).
|
||||
- Pemeriksaan penyimpangan menyelesaikan SecretRefs `gateway.auth.token` menggunakan env runtime gabungan (env perintah layanan terlebih dahulu, lalu fallback env proses).
|
||||
- Jika autentikasi token tidak aktif secara efektif (`gateway.auth.mode` eksplisit berupa `password`/`none`/`trusted-proxy`, atau mode tidak diatur ketika kata sandi dapat menang dan tidak ada kandidat token yang dapat menang), pemeriksaan token-drift melewati penyelesaian token konfigurasi.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### `gateway probe`
|
||||
|
||||
`gateway probe` adalah perintah "debug semuanya". Perintah ini selalu mem-probe:
|
||||
`gateway probe` adalah perintah "debug semuanya". Perintah ini selalu memeriksa:
|
||||
|
||||
- gateway remote yang Anda konfigurasi (jika disetel), dan
|
||||
- gateway remote yang Anda konfigurasi (jika diatur), dan
|
||||
- localhost (loopback) **meskipun remote dikonfigurasi**.
|
||||
|
||||
Jika Anda meneruskan `--url`, target eksplisit tersebut ditambahkan sebelum keduanya. Keluaran manusia memberi label target sebagai:
|
||||
Jika Anda meneruskan `--url`, target eksplisit tersebut ditambahkan di depan keduanya. Output manusia melabeli target sebagai:
|
||||
|
||||
- `URL (explicit)`
|
||||
- `Remote (configured)` atau `Remote (configured, inactive)`
|
||||
- `Local loopback`
|
||||
|
||||
<Note>
|
||||
Jika beberapa gateway dapat dijangkau, perintah ini mencetak semuanya. Beberapa gateway didukung ketika Anda menggunakan profil/port terisolasi (misalnya, bot penyelamat), tetapi sebagian besar instalasi tetap menjalankan satu gateway.
|
||||
Jika beberapa gateway dapat dijangkau, perintah ini mencetak semuanya. Beberapa gateway didukung saat Anda menggunakan profil/port terisolasi (misalnya, bot penyelamat), tetapi sebagian besar instalasi tetap menjalankan satu gateway.
|
||||
</Note>
|
||||
|
||||
```bash
|
||||
@ -328,50 +338,50 @@ openclaw gateway probe --json
|
||||
<AccordionGroup>
|
||||
<Accordion title="Interpretasi">
|
||||
- `Reachable: yes` berarti setidaknya satu target menerima koneksi WebSocket.
|
||||
- `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` melaporkan apa yang dapat dibuktikan probe tentang autentikasi. Ini terpisah dari keterjangkauan.
|
||||
- `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` melaporkan apa yang dapat dibuktikan pemeriksaan tentang autentikasi. Ini terpisah dari keterjangkauan.
|
||||
- `Read probe: ok` berarti panggilan RPC detail cakupan baca (`health`/`status`/`system-presence`/`config.get`) juga berhasil.
|
||||
- `Read probe: limited - missing scope: operator.read` berarti koneksi berhasil tetapi RPC cakupan baca terbatas. Ini dilaporkan sebagai keterjangkauan **terdegradasi**, bukan kegagalan penuh.
|
||||
- `Read probe: failed` setelah `Connect: ok` berarti Gateway menerima koneksi WebSocket, tetapi diagnostik baca lanjutan kehabisan waktu atau gagal. Ini juga merupakan keterjangkauan **terdegradasi**, bukan Gateway yang tidak dapat dijangkau.
|
||||
- Seperti `gateway status`, probe menggunakan ulang autentikasi perangkat cache yang sudah ada tetapi tidak membuat identitas perangkat pertama kali atau status pairing.
|
||||
- Kode keluar hanya non-nol ketika tidak ada target yang di-probe yang dapat dijangkau.
|
||||
- `Read probe: failed` setelah `Connect: ok` berarti Gateway menerima koneksi WebSocket, tetapi diagnostik baca lanjutan mengalami waktu habis atau gagal. Ini juga merupakan keterjangkauan **terdegradasi**, bukan Gateway yang tidak dapat dijangkau.
|
||||
- Seperti `gateway status`, pemeriksaan menggunakan ulang autentikasi perangkat yang sudah ada di cache tetapi tidak membuat identitas perangkat pertama kali atau status pairing.
|
||||
- Kode keluar bukan nol hanya saat tidak ada target yang diperiksa dapat dijangkau.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Keluaran JSON">
|
||||
Tingkat atas:
|
||||
<Accordion title="Output JSON">
|
||||
Tingkat teratas:
|
||||
|
||||
- `ok`: setidaknya satu target dapat dijangkau.
|
||||
- `degraded`: setidaknya satu target menerima koneksi tetapi tidak menyelesaikan diagnostik RPC detail penuh.
|
||||
- `capability`: kapabilitas terbaik yang terlihat di seluruh target yang dapat dijangkau (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope`, atau `unknown`).
|
||||
- `primaryTargetId`: target terbaik untuk diperlakukan sebagai pemenang aktif dalam urutan ini: URL eksplisit, tunnel SSH, remote yang dikonfigurasi, lalu local loopback.
|
||||
- `primaryTargetId`: target terbaik untuk dianggap sebagai pemenang aktif dalam urutan ini: URL eksplisit, tunnel SSH, remote yang dikonfigurasi, lalu local loopback.
|
||||
- `warnings[]`: catatan peringatan upaya terbaik dengan `code`, `message`, dan `targetIds` opsional.
|
||||
- `network`: petunjuk URL local loopback/tailnet yang diturunkan dari konfigurasi saat ini dan jaringan host.
|
||||
- `discovery.timeoutMs` dan `discovery.count`: anggaran/jumlah hasil discovery aktual yang digunakan untuk pass probe ini.
|
||||
- `discovery.timeoutMs` dan `discovery.count`: anggaran/jumlah hasil discovery aktual yang digunakan untuk lintasan pemeriksaan ini.
|
||||
|
||||
Per target (`targets[].connect`):
|
||||
|
||||
- `ok`: keterjangkauan setelah koneksi + klasifikasi terdegradasi.
|
||||
- `ok`: keterjangkauan setelah klasifikasi connect + degraded.
|
||||
- `rpcOk`: keberhasilan RPC detail penuh.
|
||||
- `scopeLimited`: RPC detail gagal karena cakupan operator tidak ada.
|
||||
- `scopeLimited`: RPC detail gagal karena cakupan operator hilang.
|
||||
|
||||
Per target (`targets[].auth`):
|
||||
|
||||
- `role`: peran autentikasi yang dilaporkan dalam `hello-ok` jika tersedia.
|
||||
- `scopes`: cakupan yang diberikan yang dilaporkan dalam `hello-ok` jika tersedia.
|
||||
- `role`: peran autentikasi yang dilaporkan di `hello-ok` saat tersedia.
|
||||
- `scopes`: cakupan yang diberikan dan dilaporkan di `hello-ok` saat tersedia.
|
||||
- `capability`: klasifikasi kapabilitas autentikasi yang ditampilkan untuk target tersebut.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Kode peringatan umum">
|
||||
- `ssh_tunnel_failed`: penyiapan tunnel SSH gagal; perintah kembali ke probe langsung.
|
||||
- `ssh_tunnel_failed`: penyiapan tunnel SSH gagal; perintah beralih kembali ke pemeriksaan langsung.
|
||||
- `multiple_gateways`: lebih dari satu target dapat dijangkau; ini tidak biasa kecuali Anda sengaja menjalankan profil terisolasi, seperti bot penyelamat.
|
||||
- `auth_secretref_unresolved`: SecretRef autentikasi yang dikonfigurasi tidak dapat diselesaikan untuk target yang gagal.
|
||||
- `probe_scope_limited`: koneksi WebSocket berhasil, tetapi probe baca dibatasi oleh `operator.read` yang tidak ada.
|
||||
- `probe_scope_limited`: koneksi WebSocket berhasil, tetapi pemeriksaan baca dibatasi oleh `operator.read` yang hilang.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
#### Remote melalui SSH (paritas aplikasi Mac)
|
||||
|
||||
Mode "Remote over SSH" aplikasi macOS menggunakan port-forward lokal sehingga gateway remote (yang mungkin hanya terikat ke loopback) dapat dijangkau di `ws://127.0.0.1:<port>`.
|
||||
Mode "Remote melalui SSH" aplikasi macOS menggunakan port-forward lokal sehingga gateway remote (yang mungkin hanya terikat ke loopback) dapat dijangkau di `ws://127.0.0.1:<port>`.
|
||||
|
||||
Padanan CLI:
|
||||
|
||||
@ -380,23 +390,23 @@ openclaw gateway probe --ssh user@gateway-host
|
||||
```
|
||||
|
||||
<ParamField path="--ssh <target>" type="string">
|
||||
`user@host` atau `user@host:port` (port bawaan adalah `22`).
|
||||
`user@host` atau `user@host:port` (port default ke `22`).
|
||||
</ParamField>
|
||||
<ParamField path="--ssh-identity <path>" type="string">
|
||||
File identitas.
|
||||
</ParamField>
|
||||
<ParamField path="--ssh-auto" type="boolean">
|
||||
Pilih host gateway pertama yang ditemukan sebagai target SSH dari endpoint discovery yang telah diselesaikan (`local.` ditambah domain area luas yang dikonfigurasi, jika ada). Petunjuk khusus TXT diabaikan.
|
||||
Pilih host gateway pertama yang ditemukan sebagai target SSH dari endpoint discovery yang terselesaikan (`local.` ditambah domain area luas yang dikonfigurasi, jika ada). Petunjuk khusus TXT diabaikan.
|
||||
</ParamField>
|
||||
|
||||
Konfigurasi (opsional, digunakan sebagai bawaan):
|
||||
Konfigurasi (opsional, digunakan sebagai default):
|
||||
|
||||
- `gateway.remote.sshTarget`
|
||||
- `gateway.remote.sshIdentity`
|
||||
|
||||
### `gateway call <method>`
|
||||
|
||||
Pembantu RPC tingkat rendah.
|
||||
Helper RPC tingkat rendah.
|
||||
|
||||
```bash
|
||||
openclaw gateway call status
|
||||
@ -419,10 +429,10 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
|
||||
Anggaran waktu habis.
|
||||
</ParamField>
|
||||
<ParamField path="--expect-final" type="boolean">
|
||||
Terutama untuk RPC bergaya agen yang melakukan streaming peristiwa perantara sebelum payload final.
|
||||
Terutama untuk RPC bergaya agen yang mengalirkan peristiwa perantara sebelum payload final.
|
||||
</ParamField>
|
||||
<ParamField path="--json" type="boolean">
|
||||
Keluaran JSON yang dapat dibaca mesin.
|
||||
Output JSON yang dapat dibaca mesin.
|
||||
</ParamField>
|
||||
|
||||
<Note>
|
||||
@ -441,7 +451,7 @@ openclaw gateway uninstall
|
||||
|
||||
### Instal dengan wrapper
|
||||
|
||||
Gunakan `--wrapper` ketika layanan terkelola harus dimulai melalui executable lain, misalnya shim pengelola rahasia atau pembantu run-as. Wrapper menerima argumen Gateway normal dan bertanggung jawab untuk akhirnya mengeksekusi `openclaw` atau Node dengan argumen tersebut.
|
||||
Gunakan `--wrapper` saat layanan terkelola harus dimulai melalui executable lain, misalnya shim manajer rahasia atau helper run-as. Wrapper menerima argumen Gateway normal dan bertanggung jawab untuk akhirnya mengeksekusi `openclaw` atau Node dengan argumen tersebut.
|
||||
|
||||
```bash
|
||||
cat > ~/.local/bin/openclaw-doppler <<'EOF'
|
||||
@ -455,7 +465,7 @@ openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --force
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
Anda juga dapat menyetel wrapper melalui environment. `gateway install` memvalidasi bahwa jalur tersebut adalah file executable, menulis wrapper ke `ProgramArguments` layanan, dan mempertahankan `OPENCLAW_WRAPPER` di environment layanan untuk instalasi ulang paksa, pembaruan, dan perbaikan doctor berikutnya.
|
||||
Anda juga dapat mengatur wrapper melalui environment. `gateway install` memvalidasi bahwa jalur tersebut adalah file executable, menulis wrapper ke `ProgramArguments` layanan, dan mempertahankan `OPENCLAW_WRAPPER` di environment layanan untuk instalasi ulang paksa, pembaruan, dan perbaikan doctor berikutnya.
|
||||
|
||||
```bash
|
||||
OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --force
|
||||
@ -477,19 +487,19 @@ openclaw gateway restart
|
||||
- `gateway uninstall|start|stop`: `--json`
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Perilaku daur hidup">
|
||||
- Gunakan `gateway restart` untuk memulai ulang layanan terkelola. Jangan merangkai `gateway stop` dan `gateway start` sebagai pengganti restart; pada macOS, `gateway stop` sengaja menonaktifkan LaunchAgent sebelum menghentikannya.
|
||||
<Accordion title="Perilaku siklus hidup">
|
||||
- Gunakan `gateway restart` untuk memulai ulang layanan terkelola. Jangan merangkai `gateway stop` dan `gateway start` sebagai pengganti restart; di macOS, `gateway stop` sengaja menonaktifkan LaunchAgent sebelum menghentikannya.
|
||||
- `gateway restart --wait 30s` mengganti anggaran drain restart yang dikonfigurasi untuk restart tersebut. Angka tanpa unit adalah milidetik; unit seperti `s`, `m`, dan `h` diterima. `--wait 0` menunggu tanpa batas.
|
||||
- `gateway restart --force` melewati drain pekerjaan aktif dan langsung memulai ulang. Gunakan ketika operator sudah memeriksa penghalang tugas yang tercantum dan menginginkan gateway kembali sekarang.
|
||||
- Perintah daur hidup menerima `--json` untuk skrip.
|
||||
- `gateway restart --force` melewati drain pekerjaan aktif dan langsung memulai ulang. Gunakan ini saat operator sudah memeriksa pemblokir tugas yang tercantum dan menginginkan gateway kembali sekarang.
|
||||
- Perintah siklus hidup menerima `--json` untuk scripting.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Autentikasi dan SecretRefs saat instalasi">
|
||||
- Ketika autentikasi token memerlukan token dan `gateway.auth.token` dikelola SecretRef, `gateway install` memvalidasi bahwa SecretRef dapat diselesaikan tetapi tidak mempertahankan token yang diselesaikan ke metadata environment layanan.
|
||||
- Saat autentikasi token memerlukan token dan `gateway.auth.token` dikelola SecretRef, `gateway install` memvalidasi bahwa SecretRef dapat diselesaikan tetapi tidak mempertahankan token yang terselesaikan ke metadata environment layanan.
|
||||
- Jika autentikasi token memerlukan token dan SecretRef token yang dikonfigurasi tidak terselesaikan, instalasi gagal tertutup alih-alih mempertahankan fallback plaintext.
|
||||
- Untuk autentikasi kata sandi pada `gateway run`, utamakan `OPENCLAW_GATEWAY_PASSWORD`, `--password-file`, atau `gateway.auth.password` yang didukung SecretRef daripada `--password` inline.
|
||||
- Dalam mode autentikasi inferensial, `OPENCLAW_GATEWAY_PASSWORD` khusus shell tidak melonggarkan persyaratan token instalasi; gunakan konfigurasi tahan lama (`gateway.auth.password` atau config `env`) saat memasang layanan terkelola.
|
||||
- Jika `gateway.auth.token` dan `gateway.auth.password` sama-sama dikonfigurasi dan `gateway.auth.mode` tidak disetel, instalasi diblokir hingga mode disetel secara eksplisit.
|
||||
- Untuk autentikasi kata sandi pada `gateway run`, pilih `OPENCLAW_GATEWAY_PASSWORD`, `--password-file`, atau `gateway.auth.password` berbasis SecretRef daripada `--password` inline.
|
||||
- Dalam mode autentikasi tersimpul, `OPENCLAW_GATEWAY_PASSWORD` yang hanya ada di shell tidak melonggarkan persyaratan token instalasi; gunakan konfigurasi tahan lama (`gateway.auth.password` atau `env` konfigurasi) saat menginstal layanan terkelola.
|
||||
- Jika `gateway.auth.token` dan `gateway.auth.password` sama-sama dikonfigurasi dan `gateway.auth.mode` tidak diatur, instalasi diblokir sampai mode diatur secara eksplisit.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -498,20 +508,20 @@ openclaw gateway restart
|
||||
|
||||
`gateway discover` memindai beacon Gateway (`_openclaw-gw._tcp`).
|
||||
|
||||
- Multicast DNS-SD: `local.`
|
||||
- Unicast DNS-SD (Wide-Area Bonjour): pilih domain (contoh: `openclaw.internal.`) dan siapkan split DNS + server DNS; lihat [Bonjour](/id/gateway/bonjour).
|
||||
- DNS-SD multicast: `local.`
|
||||
- DNS-SD unicast (Bonjour area luas): pilih domain (contoh: `openclaw.internal.`) dan siapkan DNS split + server DNS; lihat [Bonjour](/id/gateway/bonjour).
|
||||
|
||||
Hanya gateway dengan discovery Bonjour yang diaktifkan (bawaan) yang mengiklankan beacon.
|
||||
Hanya Gateway dengan penemuan Bonjour yang diaktifkan (default) yang mengiklankan beacon.
|
||||
|
||||
Catatan discovery Wide-Area mencakup (TXT):
|
||||
Rekaman penemuan area luas mencakup (TXT):
|
||||
|
||||
- `role` (petunjuk peran gateway)
|
||||
- `transport` (petunjuk transport, misalnya `gateway`)
|
||||
- `role` (petunjuk peran Gateway)
|
||||
- `transport` (petunjuk transport, mis. `gateway`)
|
||||
- `gatewayPort` (port WebSocket, biasanya `18789`)
|
||||
- `sshPort` (opsional; klien menetapkan target SSH bawaan ke `22` ketika ini tidak ada)
|
||||
- `tailnetDns` (nama host MagicDNS, jika tersedia)
|
||||
- `gatewayTls` / `gatewayTlsSha256` (TLS diaktifkan + fingerprint sertifikat)
|
||||
- `cliPath` (petunjuk instalasi remote yang ditulis ke zona area luas)
|
||||
- `sshPort` (opsional; klien menetapkan target SSH default ke `22` saat tidak ada)
|
||||
- `tailnetDns` (nama host MagicDNS, bila tersedia)
|
||||
- `gatewayTls` / `gatewayTlsSha256` (TLS diaktifkan + sidik jari sertifikat)
|
||||
- `cliPath` (petunjuk pemasangan jarak jauh yang ditulis ke zona area luas)
|
||||
|
||||
### `gateway discover`
|
||||
|
||||
@ -520,10 +530,10 @@ openclaw gateway discover
|
||||
```
|
||||
|
||||
<ParamField path="--timeout <ms>" type="number" default="2000">
|
||||
Batas waktu per perintah (browse/resolve).
|
||||
Batas waktu perintah (browse/resolve).
|
||||
</ParamField>
|
||||
<ParamField path="--json" type="boolean">
|
||||
Keluaran yang dapat dibaca mesin (juga menonaktifkan gaya/spinner).
|
||||
Keluaran yang dapat dibaca mesin (juga menonaktifkan styling/spinner).
|
||||
</ParamField>
|
||||
|
||||
Contoh:
|
||||
@ -534,9 +544,9 @@ openclaw gateway discover --json | jq '.beacons[].wsUrl'
|
||||
```
|
||||
|
||||
<Note>
|
||||
- CLI memindai `local.` ditambah domain area luas yang dikonfigurasi saat diaktifkan.
|
||||
- `wsUrl` dalam keluaran JSON diturunkan dari endpoint layanan hasil resolve, bukan dari petunjuk khusus TXT seperti `lanHost` atau `tailnetDns`.
|
||||
- Pada mDNS `local.`, `sshPort` dan `cliPath` hanya disiarkan ketika `discovery.mdns.mode` adalah `full`. DNS-SD area luas tetap menulis `cliPath`; `sshPort` juga tetap opsional di sana.
|
||||
- CLI memindai `local.` ditambah domain area luas yang dikonfigurasi saat salah satunya diaktifkan.
|
||||
- `wsUrl` dalam keluaran JSON diturunkan dari endpoint layanan yang berhasil di-resolve, bukan dari petunjuk khusus TXT seperti `lanHost` atau `tailnetDns`.
|
||||
- Pada mDNS `local.`, `sshPort` dan `cliPath` hanya disiarkan saat `discovery.mdns.mode` adalah `full`. DNS-SD area luas tetap menulis `cliPath`; `sshPort` juga tetap opsional di sana.
|
||||
|
||||
</Note>
|
||||
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- Anda ingin mengubah model default atau melihat status autentikasi penyedia
|
||||
- Anda ingin memindai model/penyedia yang tersedia dan menelusuri masalah pada profil autentikasi
|
||||
summary: Referensi CLI untuk `openclaw models` (status/list/set/scan, alias, fallback, auth)
|
||||
- Anda ingin memindai model/penyedia yang tersedia dan menelusuri kesalahan pada profil autentikasi
|
||||
summary: Referensi CLI untuk `openclaw models` (status/list/set/scan, alias, fallback, autentikasi)
|
||||
title: Model
|
||||
x-i18n:
|
||||
generated_at: "2026-05-01T09:22:45Z"
|
||||
generated_at: "2026-05-04T18:23:34Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 538d3e4808329737fdc044dc6e14e5c7c78052e75d8a8b3b257b1ebd821c84d1
|
||||
source_hash: dc7842f02e29aa0ac2ae88f3d42bba71f1890a58ab22d818dbee0585bc562fea
|
||||
source_path: cli/models.md
|
||||
workflow: 16
|
||||
---
|
||||
@ -32,15 +32,15 @@ openclaw models set <model-or-alias>
|
||||
openclaw models scan
|
||||
```
|
||||
|
||||
`openclaw models status` menampilkan default/fallback yang telah di-resolve plus ikhtisar autentikasi.
|
||||
`openclaw models status` menampilkan default/fallback yang telah di-resolve beserta ringkasan autentikasi.
|
||||
Saat snapshot penggunaan penyedia tersedia, bagian status OAuth/kunci API menyertakan
|
||||
jendela penggunaan penyedia dan snapshot kuota.
|
||||
Penyedia jendela penggunaan saat ini: Anthropic, GitHub Copilot, Gemini CLI, OpenAI
|
||||
Codex, MiniMax, Xiaomi, dan z.ai. Auth penggunaan berasal dari hook khusus penyedia
|
||||
jika tersedia; jika tidak, OpenClaw fallback ke kredensial OAuth/kunci API yang cocok
|
||||
Codex, MiniMax, Xiaomi, dan z.ai. Autentikasi penggunaan berasal dari hook khusus penyedia
|
||||
jika tersedia; jika tidak, OpenClaw akan beralih ke kredensial OAuth/kunci API yang cocok
|
||||
dari profil autentikasi, env, atau konfigurasi.
|
||||
Dalam output `--json`, `auth.providers` adalah ikhtisar penyedia yang sadar env/config/store,
|
||||
sementara `auth.oauth` hanya kesehatan profil auth-store.
|
||||
Dalam keluaran `--json`, `auth.providers` adalah ringkasan penyedia yang sadar
|
||||
env/konfigurasi/store, sedangkan `auth.oauth` hanya kesehatan profil auth-store.
|
||||
Tambahkan `--probe` untuk menjalankan probe autentikasi live terhadap setiap profil penyedia yang dikonfigurasi.
|
||||
Probe adalah permintaan nyata (dapat mengonsumsi token dan memicu batas laju).
|
||||
Gunakan `--agent <id>` untuk memeriksa status model/autentikasi agen yang dikonfigurasi. Jika dihilangkan,
|
||||
@ -51,53 +51,52 @@ Baris probe dapat berasal dari profil autentikasi, kredensial env, atau `models.
|
||||
Catatan:
|
||||
|
||||
- `models set <model-or-alias>` menerima `provider/model` atau alias.
|
||||
- `models list` bersifat hanya-baca: membaca konfigurasi, profil autentikasi, state katalog yang ada,
|
||||
- `models list` bersifat hanya baca: perintah ini membaca konfigurasi, profil autentikasi, status katalog yang ada,
|
||||
dan baris katalog milik penyedia, tetapi tidak menulis ulang
|
||||
`models.json`.
|
||||
- Kolom `Auth` berada pada level penyedia dan hanya-baca. Kolom ini dihitung dari metadata profil
|
||||
autentikasi lokal, penanda env, kunci penyedia yang dikonfigurasi, penanda penyedia lokal,
|
||||
penanda env/profil AWS Bedrock, dan metadata synthetic-auth Plugin;
|
||||
ini tidak memuat runtime penyedia, membaca rahasia keychain, memanggil API
|
||||
penyedia, atau membuktikan kesiapan eksekusi per-model secara persis.
|
||||
- Kolom `Auth` berada pada tingkat penyedia dan hanya baca. Kolom ini dihitung dari metadata profil autentikasi lokal,
|
||||
penanda env, kunci penyedia yang dikonfigurasi, penanda penyedia lokal, penanda env/profil AWS Bedrock, dan metadata autentikasi sintetis Plugin;
|
||||
kolom ini tidak memuat runtime penyedia, membaca rahasia keychain, memanggil API penyedia,
|
||||
atau membuktikan kesiapan eksekusi per model secara tepat.
|
||||
- `models list --all --provider <id>` dapat menyertakan baris katalog statis milik penyedia
|
||||
dari manifes Plugin atau metadata katalog penyedia bawaan meskipun Anda
|
||||
belum melakukan autentikasi dengan penyedia tersebut. Baris tersebut tetap ditampilkan sebagai
|
||||
tidak tersedia sampai auth yang cocok dikonfigurasi.
|
||||
dari manifes Plugin atau metadata katalog penyedia bawaan bahkan saat Anda
|
||||
belum melakukan autentikasi dengan penyedia tersebut. Baris tersebut tetap ditampilkan
|
||||
tidak tersedia sampai autentikasi yang cocok dikonfigurasi.
|
||||
- `models list` menjaga control plane tetap responsif saat penemuan katalog penyedia
|
||||
lambat. Tampilan default dan terkonfigurasi fallback ke baris model yang dikonfigurasi atau
|
||||
sintetis setelah jeda singkat dan membiarkan penemuan selesai di
|
||||
latar belakang. Gunakan `--all` saat Anda membutuhkan katalog lengkap hasil penemuan yang persis dan
|
||||
lambat. Tampilan default dan yang dikonfigurasi beralih ke baris model yang dikonfigurasi atau
|
||||
sintetis setelah penantian singkat dan membiarkan penemuan selesai di
|
||||
latar belakang. Gunakan `--all` saat Anda membutuhkan katalog lengkap hasil penemuan yang tepat dan
|
||||
bersedia menunggu penemuan penyedia.
|
||||
- `models list --all` yang luas menggabungkan baris katalog manifes di atas baris registry
|
||||
tanpa memuat hook pelengkap runtime penyedia. Fast path manifes yang difilter penyedia
|
||||
- `models list --all` yang luas menggabungkan baris katalog manifes di atas baris registri
|
||||
tanpa memuat hook suplemen runtime penyedia. Jalur cepat manifes yang difilter penyedia
|
||||
hanya menggunakan penyedia yang ditandai `static`; penyedia yang ditandai `refreshable`
|
||||
tetap berbasis registry/cache dan menambahkan baris manifes sebagai pelengkap, sementara
|
||||
penyedia yang ditandai `runtime` tetap memakai penemuan registry/runtime.
|
||||
- `models list` menjaga metadata model native dan batas runtime tetap terpisah. Dalam output tabel,
|
||||
tetap berbasis registri/cache dan menambahkan baris manifes sebagai suplemen, sedangkan
|
||||
penyedia yang ditandai `runtime` tetap menggunakan penemuan registri/runtime.
|
||||
- `models list` menjaga metadata model native dan batas runtime tetap terpisah. Dalam keluaran tabel,
|
||||
`Ctx` menampilkan `contextTokens/contextWindow` saat batas runtime efektif
|
||||
berbeda dari context window native; baris JSON menyertakan `contextTokens`
|
||||
berbeda dari jendela konteks native; baris JSON menyertakan `contextTokens`
|
||||
saat penyedia mengekspos batas tersebut.
|
||||
- `models list --provider <id>` memfilter berdasarkan id penyedia, seperti `moonshot` atau
|
||||
`openai-codex`. Perintah ini tidak menerima label tampilan dari picker penyedia interaktif,
|
||||
`openai-codex`. Perintah ini tidak menerima label tampilan dari pemilih penyedia interaktif,
|
||||
seperti `Moonshot AI`.
|
||||
- Ref model diurai dengan memisahkan pada `/` **pertama**. Jika ID model menyertakan `/` (gaya OpenRouter), sertakan prefiks penyedia (contoh: `openrouter/moonshotai/kimi-k2`).
|
||||
- Referensi model diurai dengan membagi pada `/` **pertama**. Jika ID model menyertakan `/` (gaya OpenRouter), sertakan prefiks penyedia (contoh: `openrouter/moonshotai/kimi-k2`).
|
||||
- Jika Anda menghilangkan penyedia, OpenClaw me-resolve input sebagai alias terlebih dahulu, lalu
|
||||
sebagai kecocokan penyedia-terkonfigurasi yang unik untuk id model persis tersebut, dan baru kemudian
|
||||
fallback ke penyedia default yang dikonfigurasi dengan peringatan depresiasi.
|
||||
Jika penyedia itu tidak lagi mengekspos model default yang dikonfigurasi, OpenClaw
|
||||
fallback ke penyedia/model terkonfigurasi pertama alih-alih menampilkan default
|
||||
penyedia-terhapus yang usang.
|
||||
- `models status` dapat menampilkan `marker(<value>)` dalam output autentikasi untuk placeholder non-rahasia (misalnya `OPENAI_API_KEY`, `secretref-managed`, `minimax-oauth`, `oauth:chutes`, `ollama-local`) alih-alih menyamarkannya sebagai rahasia.
|
||||
sebagai kecocokan penyedia terkonfigurasi yang unik untuk id model persis tersebut, dan baru kemudian
|
||||
beralih ke penyedia default yang dikonfigurasi dengan peringatan deprekasi.
|
||||
Jika penyedia tersebut tidak lagi mengekspos model default yang dikonfigurasi, OpenClaw
|
||||
beralih ke penyedia/model terkonfigurasi pertama alih-alih menampilkan
|
||||
default penyedia yang sudah dihapus dan usang.
|
||||
- `models status` dapat menampilkan `marker(<value>)` dalam keluaran autentikasi untuk placeholder nonrahasia (misalnya `OPENAI_API_KEY`, `secretref-managed`, `minimax-oauth`, `oauth:chutes`, `ollama-local`) alih-alih menyamarkannya sebagai rahasia.
|
||||
|
||||
### Pemindaian model
|
||||
|
||||
`models scan` membaca katalog publik `:free` milik OpenRouter dan memberi peringkat kandidat untuk
|
||||
penggunaan fallback. Katalog itu sendiri bersifat publik, sehingga pemindaian hanya-metadata tidak memerlukan
|
||||
`models scan` membaca katalog publik `:free` milik OpenRouter dan memeringkat kandidat untuk
|
||||
penggunaan fallback. Katalog itu sendiri publik, sehingga pemindaian metadata saja tidak membutuhkan
|
||||
kunci OpenRouter.
|
||||
|
||||
Secara default OpenClaw mencoba mem-probe dukungan alat dan gambar dengan panggilan model live.
|
||||
Jika tidak ada kunci OpenRouter yang dikonfigurasi, perintah fallback ke output hanya-metadata
|
||||
dan menjelaskan bahwa model `:free` tetap memerlukan `OPENROUTER_API_KEY` untuk
|
||||
Secara default OpenClaw mencoba mem-probe dukungan tool dan gambar dengan panggilan model live.
|
||||
Jika tidak ada kunci OpenRouter yang dikonfigurasi, perintah beralih ke keluaran metadata saja
|
||||
dan menjelaskan bahwa model `:free` tetap membutuhkan `OPENROUTER_API_KEY` untuk
|
||||
probe dan inferensi.
|
||||
|
||||
Opsi:
|
||||
@ -107,7 +106,7 @@ Opsi:
|
||||
- `--max-age-days <days>`
|
||||
- `--provider <name>`
|
||||
- `--max-candidates <n>`
|
||||
- `--timeout <ms>` (permintaan katalog dan timeout per-probe)
|
||||
- `--timeout <ms>` (permintaan katalog dan timeout per probe)
|
||||
- `--concurrency <n>`
|
||||
- `--yes`
|
||||
- `--no-input`
|
||||
@ -115,8 +114,8 @@ Opsi:
|
||||
- `--set-image`
|
||||
- `--json`
|
||||
|
||||
`--set-default` dan `--set-image` memerlukan probe live; hasil pemindaian hanya-metadata
|
||||
bersifat informasional dan tidak diterapkan ke konfigurasi.
|
||||
`--set-default` dan `--set-image` membutuhkan probe live; hasil pemindaian metadata saja
|
||||
bersifat informatif dan tidak diterapkan ke konfigurasi.
|
||||
|
||||
### Status model
|
||||
|
||||
@ -125,19 +124,19 @@ Opsi:
|
||||
- `--json`
|
||||
- `--plain`
|
||||
- `--check` (keluar 1=kedaluwarsa/hilang, 2=akan kedaluwarsa)
|
||||
- `--probe` (probe live terhadap profil autentikasi yang dikonfigurasi)
|
||||
- `--probe` (probe live atas profil autentikasi yang dikonfigurasi)
|
||||
- `--probe-provider <name>` (probe satu penyedia)
|
||||
- `--probe-profile <id>` (id profil berulang atau dipisahkan koma)
|
||||
- `--probe-profile <id>` (ulang atau id profil dipisahkan koma)
|
||||
- `--probe-timeout <ms>`
|
||||
- `--probe-concurrency <n>`
|
||||
- `--probe-max-tokens <n>`
|
||||
- `--agent <id>` (id agen yang dikonfigurasi; menimpa `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`)
|
||||
- `--agent <id>` (id agen yang dikonfigurasi; mengesampingkan `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`)
|
||||
|
||||
`--json` menjaga stdout khusus untuk payload JSON. Diagnostik profil autentikasi, penyedia,
|
||||
dan startup dirutekan ke stderr sehingga skrip dapat menyalurkan stdout langsung
|
||||
ke alat seperti `jq`.
|
||||
dan startup diarahkan ke stderr sehingga skrip dapat menyalurkan stdout langsung
|
||||
ke tool seperti `jq`.
|
||||
|
||||
Bucket status probe:
|
||||
Kelompok status probe:
|
||||
|
||||
- `ok`
|
||||
- `auth`
|
||||
@ -148,10 +147,10 @@ Bucket status probe:
|
||||
- `unknown`
|
||||
- `no_model`
|
||||
|
||||
Kasus detail/kode alasan probe yang perlu diantisipasi:
|
||||
Kasus detail/kode alasan probe yang perlu diperkirakan:
|
||||
|
||||
- `excluded_by_auth_order`: profil tersimpan ada, tetapi
|
||||
`auth.order.<provider>` eksplisit menghilangkannya, sehingga probe melaporkan pengecualian tersebut alih-alih
|
||||
`auth.order.<provider>` eksplisit menghilangkannya, sehingga probe melaporkan pengecualian alih-alih
|
||||
mencobanya.
|
||||
- `missing_credential`, `invalid_expires`, `expired`, `unresolved_ref`:
|
||||
profil ada tetapi tidak memenuhi syarat/dapat di-resolve.
|
||||
@ -169,42 +168,48 @@ openclaw models fallbacks list
|
||||
|
||||
```bash
|
||||
openclaw models auth add
|
||||
openclaw models auth list [--provider <id>] [--json]
|
||||
openclaw models auth login --provider <id>
|
||||
openclaw models auth setup-token --provider <id>
|
||||
openclaw models auth paste-token
|
||||
```
|
||||
|
||||
`models auth add` adalah helper autentikasi interaktif. Ini dapat meluncurkan alur autentikasi penyedia
|
||||
(OAuth/kunci API) atau memandu Anda untuk menempel token secara manual, tergantung pada
|
||||
`models auth add` adalah helper autentikasi interaktif. Perintah ini dapat meluncurkan alur autentikasi penyedia
|
||||
(OAuth/kunci API) atau memandu Anda ke penempelan token manual, bergantung pada
|
||||
penyedia yang Anda pilih.
|
||||
|
||||
`models auth list` mencantumkan profil autentikasi tersimpan untuk agen yang dipilih tanpa
|
||||
mencetak token, kunci API, atau materi rahasia OAuth. Gunakan `--provider <id>` untuk
|
||||
memfilter ke satu penyedia, seperti `openai-codex`, dan `--json` untuk scripting.
|
||||
|
||||
`models auth login` menjalankan alur autentikasi Plugin penyedia (OAuth/kunci API). Gunakan
|
||||
`openclaw plugins list` untuk melihat penyedia mana yang terinstal.
|
||||
`openclaw plugins list` untuk melihat penyedia mana yang terpasang.
|
||||
Gunakan `openclaw models auth --agent <id> <subcommand>` untuk menulis hasil autentikasi ke
|
||||
store agen terkonfigurasi tertentu. Flag induk `--agent` dihormati oleh
|
||||
`add`, `login`, `setup-token`, `paste-token`, dan `login-github-copilot`.
|
||||
store agen terkonfigurasi tertentu. Flag induk `--agent` dipatuhi oleh
|
||||
`add`, `list`, `login`, `setup-token`, `paste-token`, dan
|
||||
`login-github-copilot`.
|
||||
|
||||
Contoh:
|
||||
|
||||
```bash
|
||||
openclaw models auth login --provider openai-codex --set-default
|
||||
openclaw models auth list --provider openai-codex
|
||||
```
|
||||
|
||||
Catatan:
|
||||
|
||||
- `setup-token` dan `paste-token` tetap menjadi perintah token generik untuk penyedia
|
||||
- `setup-token` dan `paste-token` tetap merupakan perintah token generik untuk penyedia
|
||||
yang mengekspos metode autentikasi token.
|
||||
- `setup-token` memerlukan TTY interaktif dan menjalankan metode token-auth milik penyedia
|
||||
(default ke metode `setup-token` penyedia tersebut saat penyedia mengekspos
|
||||
metode itu).
|
||||
- `setup-token` membutuhkan TTY interaktif dan menjalankan metode autentikasi token milik penyedia
|
||||
(secara default menggunakan metode `setup-token` penyedia tersebut saat penyedia mengeksposnya).
|
||||
- `paste-token` menerima string token yang dibuat di tempat lain atau dari otomasi.
|
||||
- `paste-token` memerlukan `--provider`, meminta nilai token, dan menuliskannya
|
||||
- `paste-token` membutuhkan `--provider`, meminta nilai token, dan menuliskannya
|
||||
ke id profil default `<provider>:manual` kecuali Anda meneruskan
|
||||
`--profile-id`.
|
||||
- `paste-token --expires-in <duration>` menyimpan kedaluwarsa token absolut dari
|
||||
durasi relatif seperti `365d` atau `12h`.
|
||||
- Catatan Anthropic: staf Anthropic memberi tahu kami bahwa penggunaan Claude CLI bergaya OpenClaw diizinkan lagi, sehingga OpenClaw memperlakukan penggunaan ulang Claude CLI dan penggunaan `claude -p` sebagai disetujui untuk integrasi ini kecuali Anthropic menerbitkan kebijakan baru.
|
||||
- `setup-token` / `paste-token` Anthropic tetap tersedia sebagai jalur token OpenClaw yang didukung, tetapi OpenClaw kini lebih memilih penggunaan ulang Claude CLI dan `claude -p` saat tersedia.
|
||||
- Catatan Anthropic: staf Anthropic memberi tahu kami bahwa penggunaan Claude CLI bergaya OpenClaw diizinkan lagi, sehingga OpenClaw memperlakukan penggunaan ulang Claude CLI dan penggunaan `claude -p` sebagai sah untuk integrasi ini kecuali Anthropic menerbitkan kebijakan baru.
|
||||
- Anthropic `setup-token` / `paste-token` tetap tersedia sebagai jalur token OpenClaw yang didukung, tetapi OpenClaw sekarang lebih memilih penggunaan ulang Claude CLI dan `claude -p` saat tersedia.
|
||||
|
||||
## Terkait
|
||||
|
||||
|
||||
@ -1,36 +1,36 @@
|
||||
---
|
||||
read_when:
|
||||
- Anda perlu memvalidasi perutean proxy yang dikelola operator sebelum penerapan
|
||||
- Anda perlu memvalidasi perutean proksi yang dikelola operator sebelum penerapan
|
||||
- Anda perlu menangkap lalu lintas transport OpenClaw secara lokal untuk pemecahan masalah
|
||||
- Anda ingin memeriksa sesi proksi debug, blob, atau preset kueri bawaan
|
||||
summary: Referensi CLI untuk `openclaw proxy`, termasuk validasi proxy yang dikelola operator dan pemeriksa tangkapan proxy debug lokal
|
||||
- Anda ingin memeriksa sesi proksi pengawakutuan, blob, atau prasetel kueri bawaan
|
||||
summary: Referensi CLI untuk `openclaw proxy`, termasuk validasi proksi yang dikelola operator dan pemeriksa tangkapan proksi awakutu lokal
|
||||
title: Proksi
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T07:02:57Z"
|
||||
generated_at: "2026-05-04T18:23:46Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 9589bedafb97c31bcb6536a04307cd0c6550e1f307693bd4401785d79f34a1eb
|
||||
source_hash: 092c4e946dcab5e78e37d6fc77bb067b7a649368f8571fa127e462a85fa14ce5
|
||||
source_path: cli/proxy.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
# `openclaw proxy`
|
||||
|
||||
Validasi perutean proxy yang dikelola operator, atau jalankan proxy debug eksplisit lokal
|
||||
Validasi perutean proksi yang dikelola operator, atau jalankan proksi debug eksplisit lokal
|
||||
dan periksa lalu lintas yang ditangkap.
|
||||
|
||||
Gunakan `validate` untuk melakukan preflight pada proxy forward yang dikelola operator sebelum mengaktifkan
|
||||
perutean proxy OpenClaw. Perintah lainnya adalah alat debug untuk
|
||||
investigasi tingkat transport: alat tersebut dapat memulai proxy lokal, menjalankan perintah turunan
|
||||
Gunakan `validate` untuk melakukan preflight pada proksi maju yang dikelola operator sebelum mengaktifkan
|
||||
perutean proksi OpenClaw. Perintah lainnya adalah alat debugging untuk
|
||||
investigasi tingkat transport: alat tersebut dapat memulai proksi lokal, menjalankan perintah turunan
|
||||
dengan penangkapan diaktifkan, mencantumkan sesi penangkapan, mengkueri pola lalu lintas umum, membaca
|
||||
blob yang ditangkap, dan membersihkan data penangkapan lokal.
|
||||
blob yang ditangkap, dan menghapus data penangkapan lokal.
|
||||
|
||||
## Perintah
|
||||
|
||||
```bash
|
||||
openclaw proxy start [--host <host>] [--port <port>]
|
||||
openclaw proxy run [--host <host>] [--port <port>] -- <cmd...>
|
||||
openclaw proxy validate [--json] [--proxy-url <url>] [--allowed-url <url>] [--denied-url <url>] [--timeout-ms <ms>]
|
||||
openclaw proxy validate [--json] [--proxy-url <url>] [--allowed-url <url>] [--denied-url <url>] [--apns-reachable] [--apns-authority <url>] [--timeout-ms <ms>]
|
||||
openclaw proxy coverage
|
||||
openclaw proxy sessions [--limit <count>]
|
||||
openclaw proxy query --preset <name> [--session <id>]
|
||||
@ -40,25 +40,30 @@ openclaw proxy purge
|
||||
|
||||
## Validasi
|
||||
|
||||
`openclaw proxy validate` memeriksa URL proxy yang dikelola operator yang efektif dari
|
||||
`--proxy-url`, konfigurasi, atau `OPENCLAW_PROXY_URL`. Perintah ini melaporkan masalah konfigurasi ketika
|
||||
tidak ada proxy yang diaktifkan dan dikonfigurasi; gunakan `--proxy-url` untuk preflight sekali jalan
|
||||
sebelum mengubah konfigurasi. Secara default, perintah ini memverifikasi bahwa tujuan publik berhasil
|
||||
melalui proxy dan bahwa proxy tidak dapat menjangkau canary loopback sementara.
|
||||
`openclaw proxy validate` memeriksa URL proksi efektif yang dikelola operator dari
|
||||
`--proxy-url`, config, atau `OPENCLAW_PROXY_URL`. Perintah ini melaporkan masalah config ketika
|
||||
tidak ada proksi yang diaktifkan dan dikonfigurasi; gunakan `--proxy-url` untuk preflight satu kali
|
||||
sebelum mengubah config. Secara default, perintah ini memverifikasi bahwa tujuan publik berhasil
|
||||
melalui proksi dan bahwa proksi tidak dapat menjangkau canary loopback sementara.
|
||||
Tujuan khusus yang ditolak bersifat fail-closed: respons HTTP dan kegagalan
|
||||
transport yang ambigu sama-sama gagal kecuali Anda dapat memverifikasi sinyal penolakan khusus deployment
|
||||
secara terpisah.
|
||||
secara terpisah. Tambahkan `--apns-reachable` untuk juga membuka tunnel APNs HTTP/2 CONNECT
|
||||
melalui proksi dan mengonfirmasi bahwa sandbox APNs merespons; probe menggunakan token penyedia
|
||||
yang sengaja tidak valid, sehingga respons APNs `403 InvalidProviderToken`
|
||||
adalah sinyal keterjangkauan yang berhasil.
|
||||
|
||||
Opsi:
|
||||
|
||||
- `--json`: cetak JSON yang dapat dibaca mesin.
|
||||
- `--proxy-url <url>`: validasi URL proxy ini alih-alih konfigurasi atau env.
|
||||
- `--allowed-url <url>`: tambahkan tujuan yang diharapkan berhasil melalui proxy. Ulangi untuk memeriksa beberapa tujuan.
|
||||
- `--denied-url <url>`: tambahkan tujuan yang diharapkan diblokir oleh proxy. Ulangi untuk memeriksa beberapa tujuan.
|
||||
- `--proxy-url <url>`: validasi URL proksi ini, bukan config atau env.
|
||||
- `--allowed-url <url>`: tambahkan tujuan yang diharapkan berhasil melalui proksi. Ulangi untuk memeriksa beberapa tujuan.
|
||||
- `--denied-url <url>`: tambahkan tujuan yang diharapkan diblokir oleh proksi. Ulangi untuk memeriksa beberapa tujuan.
|
||||
- `--apns-reachable`: juga verifikasi bahwa sandbox APNs HTTP/2 dapat dijangkau melalui proksi.
|
||||
- `--apns-authority <url>`: otoritas APNs untuk diprobe dengan `--apns-reachable` (`https://api.sandbox.push.apple.com` secara default; produksi adalah `https://api.push.apple.com`).
|
||||
- `--timeout-ms <ms>`: batas waktu per permintaan dalam milidetik.
|
||||
|
||||
Lihat [Proxy Jaringan](/id/security/network-proxy) untuk panduan deployment dan semantik
|
||||
penolakan.
|
||||
Lihat [Proksi Jaringan](/id/security/network-proxy) untuk panduan deployment dan
|
||||
semantik penolakan.
|
||||
|
||||
## Preset kueri
|
||||
|
||||
@ -73,14 +78,14 @@ penolakan.
|
||||
|
||||
## Catatan
|
||||
|
||||
- `start` default ke `127.0.0.1` kecuali `--host` ditetapkan.
|
||||
- `run` memulai proxy debug lokal lalu menjalankan perintah setelah `--`.
|
||||
- Penerusan upstream langsung milik proxy debug membuka soket upstream untuk diagnostik. Ketika mode proxy terkelola OpenClaw aktif, penerusan langsung untuk permintaan proxy dan tunnel CONNECT dinonaktifkan secara default; tetapkan `OPENCLAW_DEBUG_PROXY_ALLOW_DIRECT_CONNECT_WITH_MANAGED_PROXY=1` hanya untuk diagnostik lokal yang disetujui.
|
||||
- `validate` keluar dengan kode 1 ketika konfigurasi proxy atau pemeriksaan tujuan gagal.
|
||||
- Penangkapan adalah data debug lokal; gunakan `openclaw proxy purge` setelah selesai.
|
||||
- `start` menggunakan default `127.0.0.1` kecuali `--host` ditetapkan.
|
||||
- `run` memulai proksi debug lokal lalu menjalankan perintah setelah `--`.
|
||||
- Penerusan upstream langsung milik proksi debug membuka soket upstream untuk diagnostik. Saat mode proksi terkelola OpenClaw aktif, penerusan langsung untuk permintaan proksi dan tunnel CONNECT dinonaktifkan secara default; tetapkan `OPENCLAW_DEBUG_PROXY_ALLOW_DIRECT_CONNECT_WITH_MANAGED_PROXY=1` hanya untuk diagnostik lokal yang disetujui.
|
||||
- `validate` keluar dengan kode 1 saat config proksi atau pemeriksaan tujuan gagal.
|
||||
- Tangkapan adalah data debugging lokal; gunakan `openclaw proxy purge` saat selesai.
|
||||
|
||||
## Terkait
|
||||
|
||||
- [Referensi CLI](/id/cli)
|
||||
- [Proxy Jaringan](/id/security/network-proxy)
|
||||
- [Autentikasi proxy tepercaya](/id/gateway/trusted-proxy-auth)
|
||||
- [Proksi Jaringan](/id/security/network-proxy)
|
||||
- [Autentikasi proksi tepercaya](/id/gateway/trusted-proxy-auth)
|
||||
|
||||
@ -1,36 +1,36 @@
|
||||
---
|
||||
read_when:
|
||||
- Anda menginginkan fallback yang andal saat penyedia API gagal
|
||||
- Anda menginginkan mekanisme cadangan yang andal saat 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'
|
||||
summary: 'Backend CLI: cadangan CLI AI lokal dengan jembatan alat MCP opsional'
|
||||
title: Backend CLI
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T09:19:31Z"
|
||||
generated_at: "2026-05-04T18:23:37Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: f343469d6a42dc6146196355dc2ba3feed045515c3d8446941b90971aadc9a16
|
||||
source_hash: 55534c48c5e226857b9320fd369416583e5c2efc80eabd4746f939afdd027dc1
|
||||
source_path: gateway/cli-backends.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw dapat menjalankan **CLI AI lokal** sebagai **fallback hanya teks** saat penyedia API sedang down,
|
||||
dibatasi laju, atau sementara bermasalah. Ini sengaja dibuat konservatif:
|
||||
OpenClaw dapat menjalankan **CLI AI lokal** sebagai **fallback hanya teks** saat penyedia API sedang tidak aktif,
|
||||
terkena batas laju, atau sementara tidak berperilaku semestinya. Ini sengaja dibuat konservatif:
|
||||
|
||||
- **Tool OpenClaw tidak diinjeksi secara langsung**, tetapi backend dengan `bundleMcp: true`
|
||||
dapat menerima tool Gateway melalui jembatan MCP loopback.
|
||||
- **Alat OpenClaw tidak disuntikkan secara langsung**, tetapi backend dengan `bundleMcp: true`
|
||||
dapat menerima alat Gateway melalui jembatan MCP loopback.
|
||||
- **Streaming JSONL** untuk CLI yang mendukungnya.
|
||||
- **Sesi didukung** (jadi giliran lanjutan tetap koheren).
|
||||
- **Gambar dapat diteruskan** jika CLI menerima path gambar.
|
||||
- **Gambar dapat diteruskan** jika CLI menerima jalur gambar.
|
||||
|
||||
Ini dirancang sebagai **jaring pengaman**, bukan jalur utama. Gunakan 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,
|
||||
pengikatan thread/percakapan, dan sesi pengodean eksternal persisten, gunakan
|
||||
[Agen ACP](/id/tools/acp-agents) sebagai gantinya. Backend CLI bukan ACP.
|
||||
Jika Anda menginginkan runtime harness lengkap dengan kontrol sesi ACP, tugas latar belakang,
|
||||
pengikatan utas/percakapan, dan sesi coding eksternal yang persisten, gunakan
|
||||
[ACP Agents](/id/tools/acp-agents) sebagai gantinya. Backend CLI bukan ACP.
|
||||
|
||||
## Mulai cepat ramah pemula
|
||||
## Mulai cepat yang ramah pemula
|
||||
|
||||
Anda dapat menggunakan Codex CLI **tanpa konfigurasi apa pun** (Plugin OpenAI bawaan
|
||||
mendaftarkan backend default):
|
||||
@ -40,7 +40,7 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.5
|
||||
```
|
||||
|
||||
Jika Gateway Anda berjalan di bawah launchd/systemd dan PATH minimal, cukup tambahkan
|
||||
path perintah:
|
||||
jalur perintah:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -56,11 +56,11 @@ path perintah:
|
||||
}
|
||||
```
|
||||
|
||||
Selesai. Tidak perlu kunci, tidak perlu konfigurasi auth tambahan selain CLI itu sendiri.
|
||||
Itu saja. Tidak perlu kunci, tidak perlu konfigurasi auth tambahan selain 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 mereferensikan backend tersebut dalam ref model atau di bawah
|
||||
Jika Anda menggunakan backend CLI bawaan sebagai **penyedia pesan utama** pada
|
||||
host Gateway, OpenClaw sekarang memuat otomatis Plugin bawaan pemiliknya saat konfigurasi Anda
|
||||
secara eksplisit mereferensikan backend tersebut dalam referensi model atau di bawah
|
||||
`agents.defaults.cliBackends`.
|
||||
|
||||
## Menggunakannya sebagai fallback
|
||||
@ -98,8 +98,8 @@ Semua backend CLI berada di bawah:
|
||||
agents.defaults.cliBackends
|
||||
```
|
||||
|
||||
Setiap entri diberi kunci berupa **id penyedia** (misalnya `codex-cli`, `my-cli`).
|
||||
Id penyedia menjadi sisi kiri ref model Anda:
|
||||
Setiap entri diberi kunci oleh **id penyedia** (misalnya `codex-cli`, `my-cli`).
|
||||
Id penyedia menjadi sisi kiri referensi model Anda:
|
||||
|
||||
```
|
||||
<provider>/<model>
|
||||
@ -148,36 +148,36 @@ Id penyedia menjadi sisi kiri ref model Anda:
|
||||
## Cara kerjanya
|
||||
|
||||
1. **Memilih backend** berdasarkan prefiks penyedia (`codex-cli/...`).
|
||||
2. **Menyusun prompt sistem** menggunakan prompt OpenClaw dan konteks workspace yang sama.
|
||||
3. **Menjalankan CLI** dengan id sesi (jika didukung) agar riwayat tetap konsisten.
|
||||
Backend `claude-cli` bawaan menjaga proses stdio Claude tetap hidup per
|
||||
2. **Membangun prompt sistem** menggunakan prompt OpenClaw + konteks workspace yang sama.
|
||||
3. **Mengeksekusi CLI** dengan id sesi (jika didukung) agar riwayat tetap konsisten.
|
||||
Backend `claude-cli` bawaan mempertahankan proses stdio Claude tetap hidup per
|
||||
sesi OpenClaw dan mengirim giliran lanjutan melalui stdin stream-json.
|
||||
4. **Mengurai output** (JSON atau teks biasa) dan mengembalikan teks akhir.
|
||||
5. **Menyimpan id sesi** per backend, sehingga giliran lanjutan menggunakan kembali sesi CLI yang sama.
|
||||
5. **Menyimpan id sesi** per backend, sehingga giliran lanjutan menggunakan ulang sesi CLI yang sama.
|
||||
|
||||
<Note>
|
||||
Backend Anthropic `claude-cli` bawaan didukung lagi. Staf Anthropic
|
||||
memberi tahu kami bahwa penggunaan Claude CLI gaya OpenClaw diizinkan lagi, jadi OpenClaw memperlakukan
|
||||
penggunaan `claude -p` sebagai disetujui untuk integrasi ini kecuali Anthropic menerbitkan
|
||||
memberi tahu kami bahwa penggunaan Claude CLI ala OpenClaw diizinkan lagi, jadi OpenClaw memperlakukan
|
||||
penggunaan `claude -p` sebagai penggunaan yang disetujui untuk integrasi ini kecuali Anthropic menerbitkan
|
||||
kebijakan baru.
|
||||
</Note>
|
||||
|
||||
Backend OpenAI `codex-cli` bawaan meneruskan prompt sistem OpenClaw melalui
|
||||
override konfigurasi `model_instructions_file` milik Codex (`-c
|
||||
model_instructions_file="..."`). Codex tidak menyediakan flag bergaya Claude
|
||||
`--append-system-prompt`, jadi OpenClaw menulis prompt yang telah dirakit ke
|
||||
model_instructions_file="..."`). Codex tidak mengekspos flag ala Claude
|
||||
`--append-system-prompt`, jadi OpenClaw menulis prompt yang sudah dirakit ke
|
||||
file sementara untuk setiap sesi Codex CLI baru.
|
||||
|
||||
Backend Anthropic `claude-cli` bawaan menerima snapshot Skills OpenClaw
|
||||
dengan dua cara: katalog Skills OpenClaw ringkas dalam prompt sistem yang ditambahkan, dan
|
||||
melalui dua cara: katalog Skills OpenClaw ringkas dalam prompt sistem yang ditambahkan, dan
|
||||
Plugin Claude Code sementara yang diteruskan dengan `--plugin-dir`. Plugin tersebut hanya berisi
|
||||
Skills yang memenuhi syarat untuk agen/sesi tersebut, sehingga resolver skill native Claude Code
|
||||
melihat set terfilter yang sama seperti yang sebaliknya akan diiklankan OpenClaw dalam
|
||||
melihat kumpulan terfilter yang sama seperti yang sebaliknya akan diiklankan OpenClaw dalam
|
||||
prompt. Override env/kunci API skill tetap diterapkan oleh OpenClaw ke
|
||||
lingkungan proses child untuk run tersebut.
|
||||
lingkungan proses anak untuk proses berjalan tersebut.
|
||||
|
||||
Claude CLI juga memiliki mode izin noninteraktifnya sendiri. OpenClaw memetakannya
|
||||
ke kebijakan exec yang sudah ada alih-alih menambahkan konfigurasi khusus Claude: saat
|
||||
ke kebijakan exec yang ada alih-alih menambahkan konfigurasi khusus Claude: saat
|
||||
kebijakan exec efektif yang diminta adalah YOLO (`tools.exec.security: "full"` dan
|
||||
`tools.exec.ask: "off"`), OpenClaw menambahkan `--permission-mode bypassPermissions`.
|
||||
Pengaturan per agen `agents.list[].tools.exec` menimpa `tools.exec` global untuk
|
||||
@ -185,8 +185,14 @@ agen tersebut. Untuk memaksa mode Claude yang berbeda, tetapkan arg backend ment
|
||||
seperti `--permission-mode default` atau `--permission-mode acceptEdits` di bawah
|
||||
`agents.defaults.cliBackends.claude-cli.args` dan `resumeArgs` yang cocok.
|
||||
|
||||
Sebelum OpenClaw dapat menggunakan backend `claude-cli` bawaan, Claude Code sendiri
|
||||
harus sudah login pada host yang sama:
|
||||
Backend Anthropic `claude-cli` bawaan juga memetakan level OpenClaw `/think`
|
||||
ke flag native Claude Code `--effort` untuk level yang bukan off. `minimal` dan
|
||||
`low` dipetakan ke `low`, `adaptive` dan `medium` dipetakan ke `medium`, dan `high`,
|
||||
`xhigh`, serta `max` dipetakan langsung. Backend CLI lain memerlukan Plugin pemiliknya untuk
|
||||
mendeklarasikan pemeta argv yang setara sebelum `/think` dapat memengaruhi CLI yang dibuat.
|
||||
|
||||
Sebelum OpenClaw dapat menggunakan backend `claude-cli` bawaan, Claude Code itu sendiri
|
||||
harus sudah login di host yang sama:
|
||||
|
||||
```bash
|
||||
claude auth login
|
||||
@ -194,8 +200,8 @@ claude auth status --text
|
||||
openclaw models auth login --provider anthropic --method cli --set-default
|
||||
```
|
||||
|
||||
Gunakan `agents.defaults.cliBackends.claude-cli.command` hanya saat binary `claude`
|
||||
belum tersedia di `PATH`.
|
||||
Gunakan `agents.defaults.cliBackends.claude-cli.command` hanya saat biner `claude`
|
||||
belum ada di `PATH`.
|
||||
|
||||
## Sesi
|
||||
|
||||
@ -203,23 +209,23 @@ belum tersedia di `PATH`.
|
||||
`sessionArgs` (placeholder `{sessionId}`) saat ID perlu disisipkan
|
||||
ke beberapa flag.
|
||||
- Jika CLI menggunakan **subperintah resume** dengan flag berbeda, tetapkan
|
||||
`resumeArgs` (menggantikan `args` saat melanjutkan) dan opsional `resumeOutput`
|
||||
`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 mengirim id sesi.
|
||||
- `existing`: hanya kirim id sesi jika sebelumnya sudah ada yang tersimpan.
|
||||
- `none`: jangan pernah kirim id sesi.
|
||||
- `claude-cli` default ke `liveSession: "claude-stdio"`, `output: "jsonl"`,
|
||||
dan `input: "stdin"` sehingga giliran lanjutan menggunakan kembali proses Claude live saat
|
||||
proses itu aktif. Stdio hangat kini menjadi default, termasuk untuk konfigurasi kustom
|
||||
yang menghilangkan field transport. Jika Gateway dimulai ulang atau proses idle
|
||||
dan `input: "stdin"` sehingga giliran lanjutan menggunakan ulang proses Claude aktif saat
|
||||
masih aktif. Stdio hangat kini menjadi default, termasuk untuk konfigurasi kustom
|
||||
yang menghilangkan kolom transport. Jika Gateway dimulai ulang atau proses idle
|
||||
keluar, OpenClaw melanjutkan dari id sesi Claude yang tersimpan. Id sesi
|
||||
tersimpan diverifikasi terhadap transkrip proyek yang ada dan dapat dibaca sebelum
|
||||
resume, sehingga pengikatan semu dibersihkan dengan `reason=transcript-missing`
|
||||
resume, sehingga pengikatan bayangan dibersihkan dengan `reason=transcript-missing`
|
||||
alih-alih diam-diam memulai sesi Claude CLI baru di bawah `--resume`.
|
||||
- Sesi live Claude mempertahankan guard output JSONL berbatas. Default mengizinkan hingga
|
||||
8 MiB dan 20.000 baris JSONL mentah per giliran. Giliran Claude yang berat tool dapat menaikkan
|
||||
ini per backend dengan
|
||||
- Sesi langsung Claude mempertahankan penjaga output JSONL berbatas. Default mengizinkan hingga
|
||||
8 MiB dan 20.000 baris JSONL mentah per giliran. Giliran Claude yang berat alat dapat menaikkannya
|
||||
per backend dengan
|
||||
`agents.defaults.cliBackends.claude-cli.reliability.outputLimits.maxTurnRawChars`
|
||||
dan `maxTurnLines`; OpenClaw membatasi pengaturan tersebut ke 64 MiB dan 100.000
|
||||
baris.
|
||||
@ -229,64 +235,64 @@ belum tersedia di `PATH`.
|
||||
|
||||
Catatan serialisasi:
|
||||
|
||||
- `serialize: true` menjaga run pada lane yang sama tetap berurutan.
|
||||
- `serialize: true` menjaga proses berjalan pada lane yang sama tetap berurutan.
|
||||
- Sebagian besar CLI melakukan serialisasi pada satu lane penyedia.
|
||||
- OpenClaw membatalkan penggunaan ulang sesi CLI tersimpan saat identitas auth yang dipilih berubah,
|
||||
termasuk perubahan id profil auth, kunci API statis, token statis, atau identitas
|
||||
akun OAuth saat CLI mengekspose salah satunya. Rotasi token akses dan refresh OAuth
|
||||
tidak memotong sesi CLI tersimpan. Jika sebuah CLI tidak mengekspose id akun OAuth
|
||||
yang stabil, OpenClaw membiarkan CLI tersebut menegakkan izin resume.
|
||||
termasuk id profil auth yang berubah, kunci API statis, token statis, atau identitas
|
||||
akun OAuth saat CLI mengeksposnya. Rotasi token akses dan refresh OAuth
|
||||
tidak memotong sesi CLI tersimpan. Jika CLI tidak mengekspos
|
||||
id akun OAuth yang stabil, OpenClaw membiarkan CLI tersebut menegakkan izin resume.
|
||||
|
||||
## Prelude fallback dari sesi claude-cli
|
||||
|
||||
Saat percobaan `claude-cli` gagal beralih ke kandidat non-CLI dalam
|
||||
Saat upaya `claude-cli` beralih gagal ke kandidat non-CLI dalam
|
||||
[`agents.defaults.model.fallbacks`](/id/concepts/model-failover), OpenClaw menyemai
|
||||
percobaan berikutnya dengan prelude konteks yang dipanen dari transkrip JSONL lokal
|
||||
upaya berikutnya dengan prelude konteks yang dipanen dari transkrip JSONL lokal
|
||||
Claude Code di `~/.claude/projects/`. Tanpa seed ini, penyedia fallback
|
||||
akan mulai dari kosong karena transkrip sesi milik OpenClaw sendiri kosong
|
||||
untuk run `claude-cli`.
|
||||
akan mulai dari nol karena transkrip sesi OpenClaw sendiri kosong
|
||||
untuk proses berjalan `claude-cli`.
|
||||
|
||||
- Prelude lebih memilih ringkasan `/compact` terbaru atau penanda `compact_boundary`,
|
||||
lalu menambahkan giliran pascabatas terbaru hingga anggaran karakter.
|
||||
Giliran prabatas dibuang karena ringkasan sudah merepresentasikannya.
|
||||
- Blok tool digabung menjadi petunjuk ringkas `(tool call: name)` dan
|
||||
`(tool result: …)` agar anggaran prompt tetap jujur. Ringkasan diberi label
|
||||
- Prelude memilih ringkasan `/compact` terbaru atau penanda `compact_boundary`
|
||||
terlebih dahulu, lalu menambahkan giliran pascabatas terbaru hingga anggaran
|
||||
karakter. Giliran prabatas dibuang karena ringkasan sudah merepresentasikannya.
|
||||
- Blok alat digabung menjadi petunjuk ringkas `(tool call: name)` dan
|
||||
`(tool result: …)` untuk menjaga anggaran prompt tetap jujur. Ringkasan diberi label
|
||||
`(truncated)` jika meluap.
|
||||
- Fallback penyedia yang sama dari `claude-cli` ke `claude-cli` mengandalkan
|
||||
`--resume` milik Claude sendiri dan melewati prelude.
|
||||
- Seed menggunakan kembali validasi path file sesi Claude yang ada, sehingga
|
||||
path arbitrer tidak dapat dibaca.
|
||||
- Fallback sesama penyedia `claude-cli` ke `claude-cli` mengandalkan `--resume`
|
||||
milik Claude sendiri dan melewati prelude.
|
||||
- Seed menggunakan ulang validasi jalur file sesi Claude yang ada, sehingga
|
||||
jalur arbitrer tidak dapat dibaca.
|
||||
|
||||
## Gambar (pass-through)
|
||||
|
||||
Jika CLI Anda menerima path gambar, tetapkan `imageArg`:
|
||||
Jika CLI Anda menerima jalur gambar, tetapkan `imageArg`:
|
||||
|
||||
```json5
|
||||
imageArg: "--image",
|
||||
imageMode: "repeat"
|
||||
```
|
||||
|
||||
OpenClaw akan menulis gambar base64 ke file sementara. Jika `imageArg` ditetapkan, path
|
||||
tersebut diteruskan sebagai arg CLI. Jika `imageArg` tidak ada, OpenClaw menambahkan
|
||||
path file ke prompt (injeksi path), yang cukup untuk CLI yang otomatis
|
||||
memuat file lokal dari path biasa.
|
||||
OpenClaw akan menulis gambar base64 ke file temp. Jika `imageArg` disetel, jalur tersebut
|
||||
diteruskan sebagai arg CLI. Jika `imageArg` tidak ada, OpenClaw menambahkan
|
||||
jalur file ke prompt (injeksi jalur), yang cukup untuk CLI yang otomatis
|
||||
memuat file lokal dari jalur biasa.
|
||||
|
||||
## Input / output
|
||||
|
||||
- `output: "json"` (default) mencoba mengurai 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"` mengurai stream JSONL (misalnya Codex CLI `--json`) dan mengekstrak pesan agen akhir plus
|
||||
pengenal sesi jika ada.
|
||||
- `output: "jsonl"` mengurai stream JSONL (misalnya Codex CLI `--json`) dan mengekstrak pesan agen akhir plus pengenal sesi
|
||||
saat ada.
|
||||
- `output: "text"` memperlakukan stdout sebagai respons akhir.
|
||||
|
||||
Mode input:
|
||||
|
||||
- `input: "arg"` (default) meneruskan prompt sebagai arg CLI terakhir.
|
||||
- `input: "stdin"` mengirim prompt melalui stdin.
|
||||
- Jika prompt sangat panjang dan `maxPromptArgChars` ditetapkan, stdin digunakan.
|
||||
- Jika prompt sangat panjang dan `maxPromptArgChars` disetel, stdin digunakan.
|
||||
|
||||
## Default (milik Plugin)
|
||||
## Default (dimiliki Plugin)
|
||||
|
||||
Plugin OpenAI bawaan juga mendaftarkan default untuk `codex-cli`:
|
||||
|
||||
@ -310,31 +316,31 @@ Plugin Google bawaan juga mendaftarkan default untuk `google-gemini-cli`:
|
||||
- `sessionMode: "existing"`
|
||||
- `sessionIdFields: ["session_id", "sessionId"]`
|
||||
|
||||
Prasyarat: Gemini CLI lokal harus terinstal dan tersedia sebagai
|
||||
Prasyarat: Gemini CLI lokal harus sudah terpasang 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 `cacheRead` OpenClaw.
|
||||
- Teks balasan dibaca dari bidang JSON `response`.
|
||||
- Penggunaan menggunakan fallback ke `stats` ketika `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).
|
||||
Timpa hanya jika diperlukan (umum: path `command` absolut).
|
||||
|
||||
## Default milik Plugin
|
||||
|
||||
Default backend CLI kini menjadi bagian dari surface Plugin:
|
||||
Default backend CLI kini menjadi bagian dari permukaan plugin:
|
||||
|
||||
- Plugin mendaftarkannya dengan `api.registerCliBackend(...)`.
|
||||
- Backend `id` menjadi prefiks penyedia dalam referensi model.
|
||||
- `id` backend menjadi prefiks penyedia dalam referensi model.
|
||||
- Konfigurasi pengguna di `agents.defaults.cliBackends.<id>` tetap menimpa default plugin.
|
||||
- Pembersihan konfigurasi khusus backend tetap dimiliki plugin melalui hook opsional
|
||||
`normalizeConfig`.
|
||||
- Pembersihan konfigurasi khusus backend tetap dimiliki plugin melalui hook
|
||||
`normalizeConfig` opsional.
|
||||
|
||||
Plugin yang membutuhkan shim kompatibilitas prompt/pesan kecil dapat mendeklarasikan
|
||||
Plugin yang memerlukan shim kompatibilitas prompt/pesan kecil dapat mendeklarasikan
|
||||
transformasi teks dua arah tanpa mengganti penyedia atau backend CLI:
|
||||
|
||||
```typescript
|
||||
@ -354,52 +360,52 @@ api.registerTextTransforms({
|
||||
|
||||
`input` menulis ulang prompt sistem dan prompt pengguna yang diteruskan ke CLI. `output`
|
||||
menulis ulang delta asisten yang dialirkan dan teks akhir yang diurai sebelum OpenClaw menangani
|
||||
penanda kontrolnya sendiri dan pengiriman saluran.
|
||||
penanda kontrolnya sendiri dan pengiriman channel.
|
||||
|
||||
Untuk CLI yang memancarkan JSONL kompatibel stream-json Claude Code, tetapkan
|
||||
Untuk CLI yang mengeluarkan JSONL yang kompatibel dengan Claude Code stream-json, tetapkan
|
||||
`jsonlDialect: "claude-stream-json"` pada konfigurasi backend tersebut.
|
||||
|
||||
## Overlay MCP bundel
|
||||
## Overlay MCP Bundel
|
||||
|
||||
Backend CLI **tidak** menerima panggilan alat OpenClaw secara langsung, tetapi backend dapat
|
||||
memilih ikut menggunakan overlay konfigurasi MCP yang dihasilkan dengan `bundleMcp: true`.
|
||||
ikut menggunakan overlay konfigurasi MCP yang dihasilkan dengan `bundleMcp: true`.
|
||||
|
||||
Perilaku bundel saat ini:
|
||||
|
||||
- `claude-cli`: file konfigurasi MCP ketat yang dihasilkan
|
||||
- `codex-cli`: penimpaan konfigurasi inline untuk `mcp_servers`; server loopback
|
||||
OpenClaw yang dihasilkan ditandai dengan mode persetujuan alat per-server milik Codex
|
||||
sehingga panggilan MCP tidak dapat tertahan oleh prompt persetujuan lokal
|
||||
OpenClaw yang dihasilkan ditandai dengan mode persetujuan alat per server milik Codex
|
||||
sehingga panggilan MCP tidak dapat terhenti pada prompt persetujuan lokal
|
||||
- `google-gemini-cli`: file pengaturan sistem Gemini yang dihasilkan
|
||||
|
||||
Saat MCP bundel diaktifkan, OpenClaw:
|
||||
Ketika MCP bundel diaktifkan, OpenClaw:
|
||||
|
||||
- menjalankan server MCP HTTP loopback yang mengekspos alat Gateway ke proses CLI
|
||||
- memunculkan server MCP HTTP loopback yang mengekspos alat gateway ke proses CLI
|
||||
- mengautentikasi bridge dengan token per sesi (`OPENCLAW_MCP_TOKEN`)
|
||||
- membatasi akses alat ke konteks sesi, akun, dan saluran saat ini
|
||||
- memuat server bundle-MCP yang diaktifkan untuk ruang kerja saat ini
|
||||
- membatasi akses alat ke konteks sesi, akun, dan channel saat ini
|
||||
- memuat server bundle-MCP yang diaktifkan untuk workspace saat ini
|
||||
- menggabungkannya dengan bentuk konfigurasi/pengaturan MCP backend yang sudah ada
|
||||
- menulis ulang konfigurasi peluncuran menggunakan mode integrasi milik backend dari ekstensi pemilik
|
||||
|
||||
Jika tidak ada server MCP yang diaktifkan, OpenClaw tetap menyuntikkan konfigurasi ketat ketika
|
||||
backend memilih ikut menggunakan MCP bundel agar eksekusi latar belakang tetap terisolasi.
|
||||
backend ikut menggunakan MCP bundel agar eksekusi latar belakang tetap terisolasi.
|
||||
|
||||
Runtime MCP bundel bercakupan sesi disimpan dalam cache untuk digunakan kembali dalam satu sesi, lalu
|
||||
dibersihkan setelah `mcp.sessionIdleTtlMs` milidetik waktu menganggur (default 10
|
||||
menit; tetapkan `0` untuk menonaktifkan). Eksekusi tertanam sekali jalan seperti probe auth,
|
||||
pembuatan slug, dan permintaan recall active-memory dibersihkan pada akhir eksekusi agar anak
|
||||
stdio dan aliran HTTP/SSE Streamable tidak hidup lebih lama dari eksekusi.
|
||||
Runtime MCP bundel yang dibatasi per sesi di-cache untuk digunakan ulang dalam satu sesi, lalu
|
||||
dibersihkan setelah `mcp.sessionIdleTtlMs` milidetik waktu idle (default 10
|
||||
menit; tetapkan `0` untuk menonaktifkan). Eksekusi tertanam sekali pakai seperti probe auth,
|
||||
pembuatan slug, dan recall active-memory meminta pembersihan pada akhir eksekusi agar turunan stdio
|
||||
dan aliran Streamable HTTP/SSE tidak hidup lebih lama dari eksekusi.
|
||||
|
||||
## Batasan
|
||||
|
||||
- **Tidak ada panggilan alat OpenClaw langsung.** OpenClaw tidak menyuntikkan panggilan alat ke
|
||||
protokol backend CLI. Backend hanya melihat alat Gateway ketika mereka memilih ikut menggunakan
|
||||
- **Tidak ada panggilan alat OpenClaw langsung.** OpenClaw tidak menyuntikkan panggilan alat ke dalam
|
||||
protokol backend CLI. Backend hanya melihat alat gateway ketika ikut menggunakan
|
||||
`bundleMcp: true`.
|
||||
- **Streaming bersifat khusus backend.** Beberapa backend melakukan streaming JSONL; yang lain menyangga
|
||||
- **Streaming khusus untuk setiap backend.** Sebagian backend mengalirkan JSONL; yang lain melakukan buffer
|
||||
hingga keluar.
|
||||
- **Keluaran terstruktur** bergantung pada format JSON CLI.
|
||||
- **Sesi CLI Codex** dilanjutkan melalui keluaran teks (tanpa JSONL), yang kurang
|
||||
terstruktur dibanding eksekusi awal `--json`. Sesi OpenClaw tetap berfungsi
|
||||
- **Output terstruktur** bergantung pada format JSON CLI.
|
||||
- **Sesi Codex CLI** dilanjutkan melalui output teks (tanpa JSONL), yang kurang
|
||||
terstruktur dibandingkan eksekusi awal `--json`. Sesi OpenClaw tetap berfungsi
|
||||
normal.
|
||||
|
||||
## Pemecahan Masalah
|
||||
@ -407,7 +413,7 @@ stdio dan aliran HTTP/SSE Streamable tidak hidup lebih lama dari eksekusi.
|
||||
- **CLI tidak ditemukan**: tetapkan `command` ke path lengkap.
|
||||
- **Nama model salah**: gunakan `modelAliases` untuk memetakan `provider/model` → model CLI.
|
||||
- **Tidak ada kontinuitas sesi**: pastikan `sessionArg` ditetapkan dan `sessionMode` bukan
|
||||
`none` (CLI Codex saat ini tidak dapat melanjutkan dengan keluaran JSON).
|
||||
`none` (Codex CLI saat ini tidak dapat melanjutkan dengan output JSON).
|
||||
- **Gambar diabaikan**: tetapkan `imageArg` (dan verifikasi CLI mendukung path file).
|
||||
|
||||
## Terkait
|
||||
|
||||
@ -1,35 +1,35 @@
|
||||
---
|
||||
read_when:
|
||||
- Menjalankan matriks model langsung / backend CLI / ACP / uji smoke penyedia media
|
||||
- Menjalankan matriks model langsung / backend CLI / ACP / uji asap penyedia media
|
||||
- Men-debug resolusi kredensial pengujian langsung
|
||||
- Menambahkan pengujian langsung baru yang khusus untuk penyedia
|
||||
- Menambahkan pengujian langsung khusus penyedia baru
|
||||
sidebarTitle: Live tests
|
||||
summary: 'Pengujian langsung (yang menyentuh jaringan): matriks model, backend CLI, ACP, penyedia media, kredensial'
|
||||
title: 'Pengujian: rangkaian pengujian langsung'
|
||||
summary: 'Pengujian live (menyentuh jaringan): matriks model, backend CLI, ACP, penyedia media, kredensial'
|
||||
title: 'Pengujian: rangkaian uji langsung'
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T09:17:22Z"
|
||||
generated_at: "2026-05-04T18:23:43Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 4057d8875fa3404108e89e4381c1dd14e96abbc2af13c4934fc6c0dbf878fc00
|
||||
source_hash: 03b8ca6348137a55c8d5f67c9c166a130a75a744f6a433cb00496756b29d7016
|
||||
source_path: help/testing-live.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Untuk mulai cepat, runner QA, rangkaian unit/integrasi, dan alur Docker, lihat
|
||||
[Pengujian](/id/help/testing). Halaman ini membahas rangkaian pengujian **langsung** (menyentuh jaringan):
|
||||
matriks model, backend CLI, ACP, dan pengujian langsung penyedia media, plus
|
||||
Untuk mulai cepat, runner QA, suite unit/integrasi, dan alur Docker, lihat
|
||||
[Pengujian](/id/help/testing). Halaman ini membahas suite pengujian **live** (menyentuh jaringan):
|
||||
matriks model, backend CLI, ACP, dan pengujian live penyedia media, ditambah
|
||||
penanganan kredensial.
|
||||
|
||||
## Langsung: perintah pemeriksaan awal profil lokal
|
||||
## Live: perintah smoke profil lokal
|
||||
|
||||
Source `~/.profile` sebelum pemeriksaan langsung ad hoc agar kunci penyedia dan path alat lokal
|
||||
sesuai dengan shell Anda:
|
||||
Muat `~/.profile` sebelum pemeriksaan live ad hoc agar kunci penyedia dan path
|
||||
alat lokal sesuai dengan shell Anda:
|
||||
|
||||
```bash
|
||||
source ~/.profile
|
||||
```
|
||||
|
||||
Pemeriksaan awal media yang aman:
|
||||
Smoke media yang aman:
|
||||
|
||||
```bash
|
||||
pnpm openclaw infer tts convert --local --json \
|
||||
@ -37,41 +37,41 @@ pnpm openclaw infer tts convert --local --json \
|
||||
--output /tmp/openclaw-live-smoke.mp3
|
||||
```
|
||||
|
||||
Pemeriksaan awal kesiapan panggilan suara yang aman:
|
||||
Smoke kesiapan panggilan suara yang aman:
|
||||
|
||||
```bash
|
||||
pnpm openclaw voicecall setup --json
|
||||
pnpm openclaw voicecall smoke --to "+15555550123"
|
||||
```
|
||||
|
||||
`voicecall smoke` adalah dry run kecuali `--yes` juga ada. Gunakan `--yes` hanya
|
||||
ketika Anda sengaja ingin melakukan panggilan notifikasi nyata. Untuk Twilio, Telnyx, dan
|
||||
`voicecall smoke` adalah dry run kecuali `--yes` juga disertakan. Gunakan `--yes` hanya
|
||||
saat Anda memang ingin melakukan panggilan notifikasi sungguhan. Untuk Twilio, Telnyx, dan
|
||||
Plivo, pemeriksaan kesiapan yang berhasil memerlukan URL webhook publik; fallback
|
||||
loopback/pribadi yang hanya lokal ditolak sesuai desain.
|
||||
loopback lokal saja/pribadi ditolak sesuai desain.
|
||||
|
||||
## Langsung: penyapuan kapabilitas node Android
|
||||
## Live: sweep kapabilitas node Android
|
||||
|
||||
- Pengujian: `src/gateway/android-node.capabilities.live.test.ts`
|
||||
- Skrip: `pnpm android:test:integration`
|
||||
- Tujuan: memanggil **setiap perintah yang saat ini diiklankan** oleh node Android yang terhubung dan memeriksa perilaku kontrak perintah.
|
||||
- Tujuan: memanggil **setiap perintah yang saat ini diiklankan** oleh node Android yang terhubung dan memastikan perilaku kontrak perintah.
|
||||
- Cakupan:
|
||||
- Penyiapan manual/berprasyarat (rangkaian ini tidak menginstal/menjalankan/menyandingkan aplikasi).
|
||||
- Validasi Gateway `node.invoke` per perintah untuk node Android yang dipilih.
|
||||
- Prapenyiapan yang diperlukan:
|
||||
- Aplikasi Android sudah terhubung + disandingkan ke gateway.
|
||||
- Aplikasi tetap berada di foreground.
|
||||
- Izin/persetujuan capture diberikan untuk kapabilitas yang Anda harapkan lulus.
|
||||
- Penyiapan prasyarat/manual (suite tidak menginstal/menjalankan/memasangkan aplikasi).
|
||||
- Validasi `node.invoke` gateway per perintah untuk node Android yang dipilih.
|
||||
- Prasyarat penyiapan yang diperlukan:
|
||||
- Aplikasi Android sudah terhubung + dipasangkan ke gateway.
|
||||
- Aplikasi tetap berada di latar depan.
|
||||
- Izin/persetujuan tangkapan diberikan untuk kapabilitas yang Anda harapkan lolos.
|
||||
- Override target opsional:
|
||||
- `OPENCLAW_ANDROID_NODE_ID` atau `OPENCLAW_ANDROID_NODE_NAME`.
|
||||
- `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`.
|
||||
- Detail penyiapan Android lengkap: [Aplikasi Android](/id/platforms/android)
|
||||
- Detail lengkap penyiapan Android: [Aplikasi Android](/id/platforms/android)
|
||||
|
||||
## Langsung: pemeriksaan awal model (kunci profil)
|
||||
## Live: smoke model (kunci profil)
|
||||
|
||||
Pengujian langsung dibagi menjadi dua lapisan agar kami dapat mengisolasi kegagalan:
|
||||
Pengujian live dibagi menjadi dua lapisan agar kita dapat mengisolasi kegagalan:
|
||||
|
||||
- “Model langsung” memberi tahu kami bahwa penyedia/model dapat menjawab sama sekali dengan kunci yang diberikan.
|
||||
- “Pemeriksaan awal Gateway” memberi tahu kami bahwa seluruh pipeline gateway+agent berfungsi untuk model tersebut (sesi, riwayat, alat, kebijakan sandbox, dll.).
|
||||
- “Model langsung” memberi tahu kita bahwa penyedia/model dapat menjawab sama sekali dengan kunci yang diberikan.
|
||||
- “Smoke Gateway” memberi tahu kita bahwa pipeline gateway+agent penuh berfungsi untuk model tersebut (sesi, riwayat, alat, kebijakan sandbox, dll.).
|
||||
|
||||
### Lapisan 1: Penyelesaian model langsung (tanpa gateway)
|
||||
|
||||
@ -82,60 +82,60 @@ Pengujian langsung dibagi menjadi dua lapisan agar kami dapat mengisolasi kegaga
|
||||
- Menjalankan penyelesaian kecil per model (dan regresi tertarget bila diperlukan)
|
||||
- Cara mengaktifkan:
|
||||
- `pnpm test:live` (atau `OPENCLAW_LIVE_TEST=1` jika memanggil Vitest secara langsung)
|
||||
- Atur `OPENCLAW_LIVE_MODELS=modern` (atau `all`, alias untuk modern) untuk benar-benar menjalankan rangkaian ini; jika tidak, rangkaian akan dilewati agar `pnpm test:live` tetap berfokus pada pemeriksaan awal gateway
|
||||
- Setel `OPENCLAW_LIVE_MODELS=modern` (atau `all`, alias untuk modern) untuk benar-benar menjalankan suite ini; jika tidak, suite akan dilewati agar `pnpm test:live` tetap berfokus pada smoke gateway
|
||||
- Cara memilih model:
|
||||
- `OPENCLAW_LIVE_MODELS=modern` untuk menjalankan allowlist modern (Opus/Sonnet 4.6+, GPT-5.2 + Codex, Gemini 3, DeepSeek V4, GLM 4.7, MiniMax M2.7, Grok 4.3)
|
||||
- `OPENCLAW_LIVE_MODELS=all` adalah alias untuk allowlist modern
|
||||
- atau `OPENCLAW_LIVE_MODELS="openai/gpt-5.5,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,..."` (allowlist koma)
|
||||
- Penyapuan modern/all default menggunakan batas kurasi bersinyal tinggi; atur `OPENCLAW_LIVE_MAX_MODELS=0` untuk penyapuan modern menyeluruh atau angka positif untuk batas yang lebih kecil.
|
||||
- Penyapuan menyeluruh menggunakan `OPENCLAW_LIVE_TEST_TIMEOUT_MS` untuk timeout seluruh pengujian model langsung. Default: 60 menit.
|
||||
- Probe model langsung berjalan dengan paralelisme 20-arah secara default; atur `OPENCLAW_LIVE_MODEL_CONCURRENCY` untuk override.
|
||||
- Sweep modern/all secara default memakai batas terkurasi dengan sinyal tinggi; setel `OPENCLAW_LIVE_MAX_MODELS=0` untuk sweep modern menyeluruh atau angka positif untuk batas yang lebih kecil.
|
||||
- Sweep menyeluruh menggunakan `OPENCLAW_LIVE_TEST_TIMEOUT_MS` untuk timeout seluruh pengujian model langsung. Default: 60 menit.
|
||||
- Probe model langsung berjalan dengan paralelisme 20 arah secara default; setel `OPENCLAW_LIVE_MODEL_CONCURRENCY` untuk melakukan override.
|
||||
- Cara memilih penyedia:
|
||||
- `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist koma)
|
||||
- Dari mana kunci berasal:
|
||||
- Secara default: penyimpanan profil dan fallback env
|
||||
- Atur `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` untuk memberlakukan **penyimpanan profil** saja
|
||||
- Mengapa ini ada:
|
||||
- Setel `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` untuk memberlakukan **penyimpanan profil** saja
|
||||
- Alasan ini ada:
|
||||
- Memisahkan “API penyedia rusak / kunci tidak valid” dari “pipeline agent gateway rusak”
|
||||
- Berisi regresi kecil yang terisolasi (contoh: replay reasoning OpenAI Responses/Codex Responses + alur tool-call)
|
||||
- Berisi regresi kecil yang terisolasi (contoh: alur replay reasoning OpenAI Responses/Codex Responses + tool-call)
|
||||
|
||||
### Lapisan 2: Pemeriksaan awal Gateway + agent dev (apa yang sebenarnya dilakukan "@openclaw")
|
||||
### Lapisan 2: Smoke Gateway + agent dev (yang sebenarnya dilakukan oleh "@openclaw")
|
||||
|
||||
- Pengujian: `src/gateway/gateway-models.profiles.live.test.ts`
|
||||
- Tujuan:
|
||||
- Menjalankan gateway dalam proses
|
||||
- Membuat/menambal sesi `agent:dev:*` (override model per run)
|
||||
- Mengiterasi model-dengan-kunci dan memeriksa:
|
||||
- Mengiterasi model-dengan-kunci dan memastikan:
|
||||
- respons “bermakna” (tanpa alat)
|
||||
- pemanggilan alat nyata berfungsi (probe baca)
|
||||
- probe alat tambahan opsional (probe exec+baca)
|
||||
- path regresi OpenAI (hanya-tool-call → tindak lanjut) tetap berfungsi
|
||||
- probe alat ekstra opsional (probe exec+baca)
|
||||
- jalur regresi OpenAI (hanya tool-call → tindak lanjut) tetap berfungsi
|
||||
- Detail probe (agar Anda dapat menjelaskan kegagalan dengan cepat):
|
||||
- Probe `read`: pengujian menulis file nonce di workspace dan meminta agent untuk `read` file itu lalu menggemakan nonce kembali.
|
||||
- Probe `exec+read`: pengujian meminta agent untuk menulis nonce dengan `exec` ke file temp, lalu `read` kembali.
|
||||
- Probe gambar: pengujian melampirkan PNG yang dibuat (cat + kode acak) dan mengharapkan model mengembalikan `cat <CODE>`.
|
||||
- Probe gambar: pengujian melampirkan PNG yang dihasilkan (cat + kode acak) dan mengharapkan model mengembalikan `cat <CODE>`.
|
||||
- Referensi implementasi: `src/gateway/gateway-models.profiles.live.test.ts` dan `src/gateway/live-image-probe.ts`.
|
||||
- Cara mengaktifkan:
|
||||
- `pnpm test:live` (atau `OPENCLAW_LIVE_TEST=1` jika memanggil Vitest secara langsung)
|
||||
- Cara memilih model:
|
||||
- Default: allowlist modern (Opus/Sonnet 4.6+, GPT-5.2 + Codex, Gemini 3, DeepSeek V4, GLM 4.7, MiniMax M2.7, Grok 4.3)
|
||||
- `OPENCLAW_LIVE_GATEWAY_MODELS=all` adalah alias untuk allowlist modern
|
||||
- Atau atur `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (atau daftar koma) untuk mempersempit
|
||||
- Penyapuan gateway modern/all default menggunakan batas kurasi bersinyal tinggi; atur `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` untuk penyapuan modern menyeluruh atau angka positif untuk batas yang lebih kecil.
|
||||
- Atau setel `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (atau daftar koma) untuk mempersempit
|
||||
- Sweep gateway modern/all secara default memakai batas terkurasi dengan sinyal tinggi; setel `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` untuk sweep modern menyeluruh atau angka positif untuk batas yang lebih kecil.
|
||||
- Cara memilih penyedia (hindari “semua OpenRouter”):
|
||||
- `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist koma)
|
||||
- Probe alat + gambar selalu aktif dalam pengujian langsung ini:
|
||||
- Probe alat + gambar selalu aktif dalam pengujian live ini:
|
||||
- Probe `read` + probe `exec+read` (stres alat)
|
||||
- Probe gambar berjalan ketika model mengiklankan dukungan input gambar
|
||||
- Probe gambar berjalan saat model mengiklankan dukungan input gambar
|
||||
- Alur (tingkat tinggi):
|
||||
- Pengujian membuat PNG kecil dengan “CAT” + kode acak (`src/gateway/live-image-probe.ts`)
|
||||
- Mengirimkannya melalui `agent` `attachments: [{ mimeType: "image/png", content: "<base64>" }]`
|
||||
- Gateway mem-parse lampiran menjadi `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`)
|
||||
- Pengujian menghasilkan PNG kecil dengan “CAT” + kode acak (`src/gateway/live-image-probe.ts`)
|
||||
- Mengirimnya melalui `agent` `attachments: [{ mimeType: "image/png", content: "<base64>" }]`
|
||||
- Gateway mengurai lampiran menjadi `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`)
|
||||
- Agent tertanam meneruskan pesan pengguna multimodal ke model
|
||||
- Asersi: balasan berisi `cat` + kode tersebut (toleransi OCR: kesalahan kecil diizinkan)
|
||||
- Asersi: balasan berisi `cat` + kode (toleransi OCR: kesalahan kecil diperbolehkan)
|
||||
|
||||
<Tip>
|
||||
Untuk melihat apa yang dapat Anda uji di mesin Anda (dan id `provider/model` yang tepat), jalankan:
|
||||
Untuk melihat apa yang dapat Anda uji di mesin Anda (dan id `provider/model` persisnya), jalankan:
|
||||
|
||||
```bash
|
||||
openclaw models list
|
||||
@ -144,27 +144,27 @@ openclaw models list --json
|
||||
|
||||
</Tip>
|
||||
|
||||
## Langsung: pemeriksaan awal backend CLI (Claude, Codex, Gemini, atau CLI lokal lain)
|
||||
## Live: smoke backend CLI (Claude, Codex, Gemini, atau CLI lokal lain)
|
||||
|
||||
- Pengujian: `src/gateway/gateway-cli-backend.live.test.ts`
|
||||
- Tujuan: memvalidasi pipeline Gateway + agent menggunakan backend CLI lokal, tanpa menyentuh konfigurasi default Anda.
|
||||
- Default pemeriksaan awal khusus backend berada bersama definisi `cli-backend.ts` milik Plugin pemilik.
|
||||
- Default smoke khusus backend berada bersama definisi `cli-backend.ts` milik extension pemilik.
|
||||
- Aktifkan:
|
||||
- `pnpm test:live` (atau `OPENCLAW_LIVE_TEST=1` jika memanggil Vitest secara langsung)
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND=1`
|
||||
- Default:
|
||||
- Penyedia/model default: `claude-cli/claude-sonnet-4-6`
|
||||
- Perilaku perintah/args/gambar berasal dari metadata Plugin backend CLI pemilik.
|
||||
- Perilaku perintah/argumen/gambar berasal dari metadata plugin backend CLI pemilik.
|
||||
- Override (opsional):
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.5"`
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"`
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'`
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` untuk mengirim lampiran gambar nyata (path diinjeksi ke prompt). Resep Docker default menonaktifkan ini kecuali diminta secara eksplisit.
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` untuk meneruskan path file gambar sebagai arg CLI, bukan injeksi prompt.
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (atau `"list"`) untuk mengontrol bagaimana arg gambar diteruskan ketika `IMAGE_ARG` diatur.
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` untuk mengirim lampiran gambar nyata (path disuntikkan ke prompt). Resep Docker menonaktifkan ini secara default kecuali diminta secara eksplisit.
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` untuk meneruskan path file gambar sebagai argumen CLI alih-alih injeksi prompt.
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (atau `"list"`) untuk mengontrol cara argumen gambar diteruskan saat `IMAGE_ARG` disetel.
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` untuk mengirim giliran kedua dan memvalidasi alur resume.
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=1` untuk ikut serta dalam probe kontinuitas sesi yang sama Claude Sonnet -> Opus ketika model yang dipilih mendukung target switch. Resep Docker default menonaktifkan ini demi reliabilitas agregat.
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_MCP_PROBE=1` untuk ikut serta dalam probe loopback MCP/alat. Resep Docker default menonaktifkan ini kecuali diminta secara eksplisit.
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=1` untuk ikut serta dalam probe kontinuitas sesi yang sama Claude Sonnet -> Opus saat model yang dipilih mendukung target switch. Resep Docker menonaktifkan ini secara default demi keandalan agregat.
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_MCP_PROBE=1` untuk ikut serta dalam probe loopback MCP/alat. Resep Docker menonaktifkan ini secara default kecuali diminta secara eksplisit.
|
||||
|
||||
Contoh:
|
||||
|
||||
@ -174,17 +174,17 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \
|
||||
pnpm test:live src/gateway/gateway-cli-backend.live.test.ts
|
||||
```
|
||||
|
||||
Pemeriksaan awal konfigurasi MCP Gemini yang murah:
|
||||
Smoke konfigurasi MCP Gemini yang murah:
|
||||
|
||||
```bash
|
||||
OPENCLAW_LIVE_TEST=1 \
|
||||
pnpm test:live src/agents/cli-runner/bundle-mcp.gemini.live.test.ts
|
||||
```
|
||||
|
||||
Ini tidak meminta Gemini menghasilkan respons. Ini menulis pengaturan sistem yang sama
|
||||
yang diberikan OpenClaw kepada Gemini, lalu menjalankan `gemini --debug mcp list` untuk membuktikan
|
||||
server `transport: "streamable-http"` yang tersimpan dinormalisasi ke bentuk HTTP MCP
|
||||
Gemini dan dapat terhubung ke server MCP streamable-HTTP lokal.
|
||||
Ini tidak meminta Gemini untuk menghasilkan respons. Ini menulis pengaturan sistem yang sama
|
||||
yang diberikan OpenClaw kepada Gemini, lalu menjalankan `gemini --debug mcp list` untuk membuktikan bahwa server
|
||||
`transport: "streamable-http"` yang tersimpan dinormalisasi ke bentuk MCP HTTP milik Gemini
|
||||
dan dapat terhubung ke server MCP streamable-HTTP lokal.
|
||||
|
||||
Resep Docker:
|
||||
|
||||
@ -204,27 +204,36 @@ pnpm test:docker:live-cli-backend:gemini
|
||||
Catatan:
|
||||
|
||||
- Runner Docker berada di `scripts/test-live-cli-backend-docker.sh`.
|
||||
- Runner ini menjalankan pemeriksaan awal CLI-backend langsung di dalam image Docker repo sebagai pengguna `node` non-root.
|
||||
- Runner ini menyelesaikan metadata pemeriksaan awal CLI dari Plugin pemilik, lalu menginstal paket CLI Linux yang cocok (`@anthropic-ai/claude-code`, `@openai/codex`, atau `@google/gemini-cli`) ke prefix dapat ditulis yang di-cache di `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (default: `~/.cache/openclaw/docker-cli-tools`).
|
||||
- `pnpm test:docker:live-cli-backend:claude-subscription` memerlukan OAuth langganan Claude Code portabel melalui `~/.claude/.credentials.json` dengan `claudeAiOauth.subscriptionType` atau `CLAUDE_CODE_OAUTH_TOKEN` dari `claude setup-token`. Ini pertama-tama membuktikan `claude -p` langsung di Docker, lalu menjalankan dua giliran backend CLI Gateway tanpa mempertahankan variabel env kunci API Anthropic. Lane langganan ini menonaktifkan probe MCP/alat dan gambar Claude secara default karena Claude saat ini merutekan penggunaan aplikasi pihak ketiga melalui penagihan penggunaan ekstra, bukan batas paket langganan normal.
|
||||
- Pemeriksaan awal CLI-backend langsung sekarang menjalankan alur end-to-end yang sama untuk Claude, Codex, dan Gemini: giliran teks, giliran klasifikasi gambar, lalu pemanggilan alat MCP `cron` yang diverifikasi melalui CLI gateway.
|
||||
- Pemeriksaan awal default Claude juga menambal sesi dari Sonnet ke Opus dan memverifikasi sesi yang dilanjutkan masih mengingat catatan sebelumnya.
|
||||
- Runner menjalankan smoke backend CLI live di dalam image Docker repo sebagai pengguna non-root `node`.
|
||||
- Runner menyelesaikan metadata smoke CLI dari extension pemilik, lalu menginstal paket CLI Linux yang sesuai (`@anthropic-ai/claude-code`, `@openai/codex`, atau `@google/gemini-cli`) ke prefix tulis yang di-cache di `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (default: `~/.cache/openclaw/docker-cli-tools`).
|
||||
- `pnpm test:docker:live-cli-backend:claude-subscription` memerlukan OAuth langganan Claude Code portabel melalui `~/.claude/.credentials.json` dengan `claudeAiOauth.subscriptionType` atau `CLAUDE_CODE_OAUTH_TOKEN` dari `claude setup-token`. Ini pertama-tama membuktikan `claude -p` langsung di Docker, lalu menjalankan dua giliran backend CLI Gateway tanpa mempertahankan env vars kunci API Anthropic. Lane langganan ini menonaktifkan probe MCP/alat dan gambar Claude secara default karena Claude saat ini merutekan penggunaan aplikasi pihak ketiga melalui penagihan penggunaan ekstra, bukan batas paket langganan normal.
|
||||
- Smoke backend CLI live kini menjalankan alur end-to-end yang sama untuk Claude, Codex, dan Gemini: giliran teks, giliran klasifikasi gambar, lalu panggilan alat MCP `cron` yang diverifikasi melalui CLI gateway.
|
||||
- Smoke default Claude juga menambal sesi dari Sonnet ke Opus dan memverifikasi bahwa sesi yang dilanjutkan masih mengingat catatan sebelumnya.
|
||||
|
||||
## Langsung: pemeriksaan awal bind ACP (`/acp spawn ... --bind here`)
|
||||
## Live: keterjangkauan proxy HTTP/2 APNs
|
||||
|
||||
- Pengujian: `src/infra/push-apns-http2.live.test.ts`
|
||||
- Tujuan: melakukan tunnel melalui proxy HTTP CONNECT lokal ke endpoint APNs sandbox Apple, mengirim permintaan validasi HTTP/2 APNs, dan memastikan respons nyata `403 InvalidProviderToken` dari Apple kembali melalui jalur proxy.
|
||||
- Aktifkan:
|
||||
- `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_APNS_REACHABILITY=1 pnpm test:live src/infra/push-apns-http2.live.test.ts`
|
||||
- Timeout opsional:
|
||||
- `OPENCLAW_LIVE_APNS_TIMEOUT_MS=30000`
|
||||
|
||||
## Live: smoke bind ACP (`/acp spawn ... --bind here`)
|
||||
|
||||
- Pengujian: `src/gateway/gateway-acp-bind.live.test.ts`
|
||||
- Tujuan: memvalidasi alur conversation-bind ACP nyata dengan agen ACP langsung:
|
||||
- Tujuan: memvalidasi alur conversation-bind ACP nyata dengan agen ACP live:
|
||||
- kirim `/acp spawn <agent> --bind here`
|
||||
- ikat percakapan message-channel sintetis di tempat
|
||||
- bind percakapan kanal pesan sintetis di tempat
|
||||
- kirim tindak lanjut normal pada percakapan yang sama
|
||||
- verifikasi tindak lanjut masuk ke transkrip sesi ACP terikat
|
||||
- verifikasi tindak lanjut masuk ke transkrip sesi ACP yang telah di-bind
|
||||
- Aktifkan:
|
||||
- `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts`
|
||||
- `OPENCLAW_LIVE_ACP_BIND=1`
|
||||
- Bawaan:
|
||||
- Default:
|
||||
- Agen ACP di Docker: `claude,codex,gemini`
|
||||
- Agen ACP untuk `pnpm test:live ...` langsung: `claude`
|
||||
- Channel sintetis: konteks percakapan bergaya Slack DM
|
||||
- Kanal sintetis: konteks percakapan bergaya Slack DM
|
||||
- Backend ACP: `acpx`
|
||||
- Override:
|
||||
- `OPENCLAW_LIVE_ACP_BIND_AGENT=claude`
|
||||
@ -240,9 +249,9 @@ Catatan:
|
||||
- `OPENCLAW_LIVE_ACP_BIND_REQUIRE_CRON=1`
|
||||
- `OPENCLAW_LIVE_ACP_BIND_PARENT_MODEL=openai/gpt-5.5`
|
||||
- Catatan:
|
||||
- Lane ini menggunakan surface `chat.send` Gateway dengan field originating-route sintetis khusus admin sehingga pengujian dapat melampirkan konteks message-channel tanpa berpura-pura mengirim secara eksternal.
|
||||
- Ketika `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` tidak disetel, pengujian menggunakan registri agen bawaan Plugin `acpx` tertanam untuk agen harness ACP yang dipilih.
|
||||
- Pembuatan MCP cron sesi terikat bersifat upaya terbaik secara bawaan karena harness ACP eksternal dapat membatalkan panggilan MCP setelah bukti bind/image lulus; setel `OPENCLAW_LIVE_ACP_BIND_REQUIRE_CRON=1` untuk membuat probe cron pasca-bind tersebut ketat.
|
||||
- Lane ini menggunakan surface Gateway `chat.send` dengan field originating-route sintetis khusus admin agar pengujian dapat melampirkan konteks kanal pesan tanpa berpura-pura mengirim secara eksternal.
|
||||
- Saat `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` tidak disetel, pengujian menggunakan registry agen bawaan Plugin `acpx` tersemat untuk agen harness ACP yang dipilih.
|
||||
- Pembuatan MCP Cron sesi ter-bind bersifat upaya terbaik secara default karena harness ACP eksternal dapat membatalkan panggilan MCP setelah bukti bind/gambar lulus; setel `OPENCLAW_LIVE_ACP_BIND_REQUIRE_CRON=1` untuk membuat probe Cron pasca-bind itu ketat.
|
||||
|
||||
Contoh:
|
||||
|
||||
@ -271,18 +280,18 @@ pnpm test:docker:live-acp-bind:opencode
|
||||
Catatan Docker:
|
||||
|
||||
- Runner Docker berada di `scripts/test-live-acp-bind-docker.sh`.
|
||||
- Secara bawaan, runner menjalankan smoke bind ACP terhadap agen CLI langsung agregat secara berurutan: `claude`, `codex`, lalu `gemini`.
|
||||
- Secara default, runner menjalankan smoke ACP bind terhadap agen CLI live agregat secara berurutan: `claude`, `codex`, lalu `gemini`.
|
||||
- Gunakan `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=droid`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`, atau `OPENCLAW_LIVE_ACP_BIND_AGENTS=opencode` untuk mempersempit matriks.
|
||||
- Runner memuat `~/.profile`, menyiapkan material auth CLI yang sesuai ke dalam kontainer, lalu menginstal CLI langsung yang diminta (`@anthropic-ai/claude-code`, `@openai/codex`, Factory Droid melalui `https://app.factory.ai/cli`, `@google/gemini-cli`, atau `opencode-ai`) jika belum ada. Backend ACP itu sendiri adalah paket `acpx/runtime` tertanam dari Plugin resmi `acpx`.
|
||||
- Varian Docker Droid menyiapkan `~/.factory` untuk pengaturan, meneruskan `FACTORY_API_KEY`, dan memerlukan API key tersebut karena auth OAuth/keyring Factory lokal tidak portabel ke dalam kontainer. Varian ini menggunakan entri registri bawaan ACPX `droid exec --output-format acp`.
|
||||
- Varian Docker OpenCode adalah lane regresi agen tunggal yang ketat. Varian ini menulis model bawaan sementara `OPENCODE_CONFIG_CONTENT` dari `OPENCLAW_LIVE_ACP_BIND_OPENCODE_MODEL` (bawaan `opencode/kimi-k2.6`) setelah memuat `~/.profile`, dan `pnpm test:docker:live-acp-bind:opencode` memerlukan transkrip asisten terikat alih-alih menerima skip pasca-bind generik.
|
||||
- Panggilan CLI `acpx` langsung hanya merupakan jalur manual/solusi sementara untuk membandingkan perilaku di luar Gateway. Smoke bind ACP Docker menguji backend runtime `acpx` tertanam milik OpenClaw.
|
||||
- Runner memuat `~/.profile`, men-stage material auth CLI yang sesuai ke dalam container, lalu menginstal CLI live yang diminta (`@anthropic-ai/claude-code`, `@openai/codex`, Factory Droid melalui `https://app.factory.ai/cli`, `@google/gemini-cli`, atau `opencode-ai`) jika belum ada. Backend ACP sendiri adalah paket `acpx/runtime` tersemat dari Plugin `acpx` resmi.
|
||||
- Varian Docker Droid men-stage `~/.factory` untuk pengaturan, meneruskan `FACTORY_API_KEY`, dan memerlukan kunci API tersebut karena auth OAuth/keyring Factory lokal tidak portabel ke dalam container. Varian ini menggunakan entri registry bawaan ACPX `droid exec --output-format acp`.
|
||||
- Varian Docker OpenCode adalah lane regresi agen tunggal yang ketat. Varian ini menulis model default sementara `OPENCODE_CONFIG_CONTENT` dari `OPENCLAW_LIVE_ACP_BIND_OPENCODE_MODEL` (default `opencode/kimi-k2.6`) setelah memuat `~/.profile`, dan `pnpm test:docker:live-acp-bind:opencode` memerlukan transkrip asisten ter-bind alih-alih menerima skip pasca-bind generik.
|
||||
- Panggilan CLI `acpx` langsung hanya merupakan jalur manual/solusi sementara untuk membandingkan perilaku di luar Gateway. Smoke ACP bind Docker menguji backend runtime `acpx` tersemat OpenClaw.
|
||||
|
||||
## Langsung: smoke harness app-server Codex
|
||||
## Live: smoke harness app-server Codex
|
||||
|
||||
- Tujuan: memvalidasi harness Codex milik Plugin melalui metode Gateway
|
||||
`agent` normal:
|
||||
- muat Plugin `codex` bawaan
|
||||
- muat Plugin `codex` yang dibundel
|
||||
- pilih `OPENCLAW_AGENT_RUNTIME=codex`
|
||||
- kirim giliran agen Gateway pertama ke `openai/gpt-5.5` dengan harness Codex dipaksa
|
||||
- kirim giliran kedua ke sesi OpenClaw yang sama dan verifikasi thread app-server
|
||||
@ -290,16 +299,16 @@ Catatan Docker:
|
||||
- jalankan `/codex status` dan `/codex models` melalui jalur perintah Gateway
|
||||
yang sama
|
||||
- secara opsional jalankan dua probe shell terekskalasi yang ditinjau Guardian: satu
|
||||
perintah aman yang seharusnya disetujui dan satu unggahan fake-secret yang seharusnya
|
||||
ditolak sehingga agen bertanya balik
|
||||
perintah aman yang seharusnya disetujui dan satu unggahan rahasia palsu yang seharusnya
|
||||
ditolak sehingga agen bertanya kembali
|
||||
- Pengujian: `src/gateway/gateway-codex-harness.live.test.ts`
|
||||
- Aktifkan: `OPENCLAW_LIVE_CODEX_HARNESS=1`
|
||||
- Model bawaan: `openai/gpt-5.5`
|
||||
- Probe image opsional: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1`
|
||||
- Probe MCP/tool opsional: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1`
|
||||
- Model default: `openai/gpt-5.5`
|
||||
- Probe gambar opsional: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1`
|
||||
- Probe MCP/alat opsional: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1`
|
||||
- Probe Guardian opsional: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1`
|
||||
- Smoke menggunakan `agentRuntime.id: "codex"` sehingga harness Codex yang rusak tidak dapat
|
||||
lolos dengan diam-diam fallback ke PI.
|
||||
lulus dengan diam-diam fallback ke PI.
|
||||
- Auth: auth app-server Codex dari login langganan Codex lokal. Smoke Docker
|
||||
juga dapat menyediakan `OPENAI_API_KEY` untuk probe non-Codex bila berlaku,
|
||||
plus salinan opsional `~/.codex/auth.json` dan `~/.codex/config.toml`.
|
||||
@ -326,18 +335,18 @@ pnpm test:docker:live-codex-harness
|
||||
Catatan Docker:
|
||||
|
||||
- Runner Docker berada di `scripts/test-live-codex-harness-docker.sh`.
|
||||
- Runner memuat `~/.profile` yang dipasang, meneruskan `OPENAI_API_KEY`, menyalin file
|
||||
auth CLI Codex bila ada, menginstal `@openai/codex` ke prefiks npm terpasang yang
|
||||
dapat ditulis, menyiapkan source tree, lalu hanya menjalankan pengujian langsung harness Codex.
|
||||
- Docker mengaktifkan probe image, MCP/tool, dan Guardian secara bawaan. Setel
|
||||
- Runner memuat `~/.profile` yang di-mount, meneruskan `OPENAI_API_KEY`, menyalin file auth CLI Codex
|
||||
saat ada, menginstal `@openai/codex` ke prefix npm ter-mount yang dapat ditulis,
|
||||
men-stage pohon sumber, lalu hanya menjalankan pengujian live harness Codex.
|
||||
- Docker mengaktifkan probe gambar, MCP/alat, dan Guardian secara default. Setel
|
||||
`OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` atau
|
||||
`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` atau
|
||||
`OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0` ketika Anda membutuhkan run debug
|
||||
`OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0` saat Anda memerlukan run debug
|
||||
yang lebih sempit.
|
||||
- Docker menggunakan konfigurasi runtime Codex eksplisit yang sama, sehingga alias lama atau fallback PI
|
||||
tidak dapat menyembunyikan regresi harness Codex.
|
||||
|
||||
### Resep langsung yang direkomendasikan
|
||||
### Resep live yang direkomendasikan
|
||||
|
||||
Allowlist yang sempit dan eksplisit adalah yang tercepat dan paling tidak flakey:
|
||||
|
||||
@ -347,32 +356,32 @@ Allowlist yang sempit dan eksplisit adalah yang tercepat dan paling tidak flakey
|
||||
- Model tunggal, smoke Gateway:
|
||||
- `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
|
||||
|
||||
- Pemanggilan tool di beberapa provider:
|
||||
- Pemanggilan alat lintas beberapa penyedia:
|
||||
- `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,deepseek/deepseek-v4-flash,zai/glm-5.1,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
|
||||
|
||||
- Fokus Google (API key Gemini + Antigravity):
|
||||
- Gemini (API key): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
|
||||
- Fokus Google (kunci API Gemini + Antigravity):
|
||||
- Gemini (kunci API): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
|
||||
- Antigravity (OAuth): `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
|
||||
|
||||
- Smoke adaptive thinking Google:
|
||||
- Jika key lokal berada di profil shell: `source ~/.profile`
|
||||
- Bawaan dinamis Gemini 3: `pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-3.1-pro-preview --alt-model google/gemini-3.1-pro-preview --message '/think adaptive Reply exactly: GEMINI_ADAPTIVE_OK' --timeout-ms 180000`
|
||||
- Jika kunci lokal berada di profil shell: `source ~/.profile`
|
||||
- Default dinamis Gemini 3: `pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-3.1-pro-preview --alt-model google/gemini-3.1-pro-preview --message '/think adaptive Reply exactly: GEMINI_ADAPTIVE_OK' --timeout-ms 180000`
|
||||
- Anggaran dinamis Gemini 2.5: `pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-2.5-flash --alt-model google/gemini-2.5-flash --message '/think adaptive Reply exactly: GEMINI25_ADAPTIVE_OK' --timeout-ms 180000`
|
||||
|
||||
Catatan:
|
||||
|
||||
- `google/...` menggunakan API Gemini (API key).
|
||||
- `google/...` menggunakan API Gemini (kunci API).
|
||||
- `google-antigravity/...` menggunakan bridge OAuth Antigravity (endpoint agen bergaya Cloud Code Assist).
|
||||
- `google-gemini-cli/...` menggunakan CLI Gemini lokal di mesin Anda (auth terpisah + keunikan tooling).
|
||||
- `google-gemini-cli/...` menggunakan CLI Gemini lokal di mesin Anda (auth terpisah + kekhasan tooling).
|
||||
- API Gemini vs CLI Gemini:
|
||||
- API: OpenClaw memanggil API Gemini terhosting milik Google melalui HTTP (API key / auth profil); inilah yang dimaksud sebagian besar pengguna dengan “Gemini”.
|
||||
- CLI: OpenClaw menjalankan binary `gemini` lokal melalui shell; ia memiliki auth sendiri dan dapat berperilaku berbeda (dukungan streaming/tool/perbedaan versi).
|
||||
- API: OpenClaw memanggil API Gemini ter-host Google melalui HTTP (kunci API / auth profil); inilah yang dimaksud sebagian besar pengguna dengan “Gemini”.
|
||||
- CLI: OpenClaw menjalankan binary `gemini` lokal melalui shell; CLI ini memiliki auth sendiri dan dapat berperilaku berbeda (streaming/dukungan alat/perbedaan versi).
|
||||
|
||||
## Langsung: matriks model (yang kami cakup)
|
||||
## Live: matriks model (yang kami cakup)
|
||||
|
||||
Tidak ada “daftar model CI” tetap (langsung bersifat opt-in), tetapi ini adalah model **yang direkomendasikan** untuk dicakup secara rutin di mesin pengembang dengan key.
|
||||
Tidak ada “daftar model CI” tetap (live bersifat opt-in), tetapi berikut adalah model **yang direkomendasikan** untuk dicakup secara berkala di mesin dev dengan kunci.
|
||||
|
||||
### Set smoke modern (pemanggilan tool + image)
|
||||
### Set smoke modern (pemanggilan alat + gambar)
|
||||
|
||||
Ini adalah run “model umum” yang kami harapkan tetap berfungsi:
|
||||
|
||||
@ -385,12 +394,12 @@ Ini adalah run “model umum” yang kami harapkan tetap berfungsi:
|
||||
- Z.AI (GLM): `zai/glm-5.1`
|
||||
- MiniMax: `minimax/MiniMax-M2.7`
|
||||
|
||||
Jalankan smoke Gateway dengan tool + image:
|
||||
Jalankan smoke Gateway dengan alat + gambar:
|
||||
`OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,deepseek/deepseek-v4-flash,zai/glm-5.1,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
|
||||
|
||||
### Baseline: pemanggilan tool (Read + Exec opsional)
|
||||
### Baseline: pemanggilan alat (Read + Exec opsional)
|
||||
|
||||
Pilih setidaknya satu per keluarga provider:
|
||||
Pilih setidaknya satu per keluarga penyedia:
|
||||
|
||||
- OpenAI: `openai/gpt-5.5`
|
||||
- Anthropic: `anthropic/claude-opus-4-6` (atau `anthropic/claude-sonnet-4-6`)
|
||||
@ -399,81 +408,81 @@ Pilih setidaknya satu per keluarga provider:
|
||||
- Z.AI (GLM): `zai/glm-5.1`
|
||||
- MiniMax: `minimax/MiniMax-M2.7`
|
||||
|
||||
Cakupan tambahan opsional (bagus jika ada):
|
||||
Cakupan tambahan opsional (baik untuk dimiliki):
|
||||
|
||||
- xAI: `xai/grok-4.3` (atau yang terbaru tersedia)
|
||||
- Mistral: `mistral/`… (pilih satu model berkemampuan “tools” yang telah Anda aktifkan)
|
||||
- Cerebras: `cerebras/`… (jika Anda memiliki akses)
|
||||
- LM Studio: `lmstudio/`… (lokal; pemanggilan tool bergantung pada mode API)
|
||||
- LM Studio: `lmstudio/`… (lokal; pemanggilan alat bergantung pada mode API)
|
||||
|
||||
### Vision: kirim image (lampiran → pesan multimodal)
|
||||
### Vision: kirim gambar (lampiran → pesan multimodal)
|
||||
|
||||
Sertakan setidaknya satu model berkemampuan image dalam `OPENCLAW_LIVE_GATEWAY_MODELS` (varian berkemampuan vision Claude/Gemini/OpenAI, dll.) untuk menguji probe image.
|
||||
Sertakan setidaknya satu model berkemampuan gambar di `OPENCLAW_LIVE_GATEWAY_MODELS` (varian Claude/Gemini/OpenAI berkemampuan vision, dll.) untuk menguji probe gambar.
|
||||
|
||||
### Agregator / Gateway alternatif
|
||||
|
||||
Jika Anda memiliki key yang diaktifkan, kami juga mendukung pengujian melalui:
|
||||
Jika Anda memiliki kunci yang diaktifkan, kami juga mendukung pengujian melalui:
|
||||
|
||||
- OpenRouter: `openrouter/...` (ratusan model; gunakan `openclaw models scan` untuk menemukan kandidat berkemampuan tool+image)
|
||||
- OpenRouter: `openrouter/...` (ratusan model; gunakan `openclaw models scan` untuk menemukan kandidat yang mampu alat+gambar)
|
||||
- OpenCode: `opencode/...` untuk Zen dan `opencode-go/...` untuk Go (auth melalui `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`)
|
||||
|
||||
Provider lain yang dapat Anda sertakan dalam matriks langsung (jika Anda memiliki kredensial/konfigurasi):
|
||||
Lebih banyak penyedia yang dapat Anda sertakan dalam matriks live (jika Anda memiliki kredensial/konfigurasi):
|
||||
|
||||
- Bawaan: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot`
|
||||
- Melalui `models.providers` (endpoint kustom): `minimax` (cloud/API), plus proxy apa pun yang kompatibel dengan OpenAI/Anthropic (LM Studio, vLLM, LiteLLM, dll.)
|
||||
- Melalui `models.providers` (endpoint khusus): `minimax` (cloud/API), plus proxy kompatibel OpenAI/Anthropic apa pun (LM Studio, vLLM, LiteLLM, dll.)
|
||||
|
||||
<Tip>
|
||||
Jangan hardcode "all models" dalam dokumentasi. Daftar otoritatif adalah apa pun yang dikembalikan `discoverModels(...)` di mesin Anda plus key apa pun yang tersedia.
|
||||
Jangan hardcode "all models" di dokumen. Daftar otoritatif adalah apa pun yang dikembalikan `discoverModels(...)` di mesin Anda plus kunci apa pun yang tersedia.
|
||||
</Tip>
|
||||
|
||||
## Kredensial (jangan pernah commit)
|
||||
|
||||
Pengujian langsung menemukan kredensial dengan cara yang sama seperti CLI. Implikasi praktis:
|
||||
Pengujian live menemukan kredensial dengan cara yang sama seperti CLI. Implikasi praktis:
|
||||
|
||||
- Jika CLI berfungsi, pengujian live seharusnya menemukan kunci yang sama.
|
||||
- Jika pengujian live mengatakan “tidak ada kredensial”, debug dengan cara yang sama seperti saat Anda men-debug `openclaw models list` / pemilihan model.
|
||||
- Jika pengujian live mengatakan “no creds”, debug dengan cara yang sama seperti Anda men-debug `openclaw models list` / pemilihan model.
|
||||
|
||||
- Profil autentikasi per agen: `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (inilah yang dimaksud “kunci profil” dalam pengujian live)
|
||||
- Profil autentikasi per agen: `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (inilah yang dimaksud “profile keys” dalam pengujian live)
|
||||
- Konfigurasi: `~/.openclaw/openclaw.json` (atau `OPENCLAW_CONFIG_PATH`)
|
||||
- Direktori status lama: `~/.openclaw/credentials/` (disalin ke home live staged saat ada, tetapi bukan penyimpanan kunci profil utama)
|
||||
- Jalankan live lokal menyalin konfigurasi aktif, file `auth-profiles.json` per agen, `credentials/` lama, dan direktori autentikasi CLI eksternal yang didukung ke home pengujian sementara secara default; home live staged melewati `workspace/` dan `sandboxes/`, dan override jalur `agents.*.workspace` / `agentDir` dihapus agar probe tetap berada di luar workspace host asli Anda.
|
||||
- Direktori status lama: `~/.openclaw/credentials/` (disalin ke home live bertahap saat ada, tetapi bukan penyimpanan utama profile-key)
|
||||
- Eksekusi live lokal secara default menyalin konfigurasi aktif, file `auth-profiles.json` per agen, `credentials/` lama, dan direktori autentikasi CLI eksternal yang didukung ke home pengujian sementara; home live bertahap melewati `workspace/` dan `sandboxes/`, dan penggantian jalur `agents.*.workspace` / `agentDir` dihapus agar probe tetap tidak menyentuh workspace host asli Anda.
|
||||
|
||||
Jika Anda ingin mengandalkan kunci env (misalnya diekspor di `~/.profile` Anda), jalankan pengujian lokal setelah `source ~/.profile`, atau gunakan runner Docker di bawah (runner dapat memasang `~/.profile` ke dalam kontainer).
|
||||
Jika Anda ingin mengandalkan kunci env (misalnya diekspor di `~/.profile` Anda), jalankan pengujian lokal setelah `source ~/.profile`, atau gunakan runner Docker di bawah ini (runner tersebut dapat memasang `~/.profile` ke dalam container).
|
||||
|
||||
## Deepgram live (transkripsi audio)
|
||||
## Live Deepgram (transkripsi audio)
|
||||
|
||||
- Pengujian: `extensions/deepgram/audio.live.test.ts`
|
||||
- Aktifkan: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live extensions/deepgram/audio.live.test.ts`
|
||||
|
||||
## Rencana coding BytePlus live
|
||||
## Live rencana coding BytePlus
|
||||
|
||||
- Pengujian: `extensions/byteplus/live.test.ts`
|
||||
- Aktifkan: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live extensions/byteplus/live.test.ts`
|
||||
- Override model opsional: `BYTEPLUS_CODING_MODEL=ark-code-latest`
|
||||
- Penggantian model opsional: `BYTEPLUS_CODING_MODEL=ark-code-latest`
|
||||
|
||||
## Media workflow ComfyUI live
|
||||
## Live media workflow ComfyUI
|
||||
|
||||
- Pengujian: `extensions/comfy/comfy.live.test.ts`
|
||||
- Aktifkan: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts`
|
||||
- Cakupan:
|
||||
- Menjalankan jalur gambar, video, dan `music_generate` comfy bawaan
|
||||
- Menguji jalur gambar, video, dan `music_generate` comfy bawaan
|
||||
- Melewati setiap kapabilitas kecuali `plugins.entries.comfy.config.<capability>` dikonfigurasi
|
||||
- Berguna setelah mengubah pengiriman workflow comfy, polling, unduhan, atau pendaftaran Plugin
|
||||
- Berguna setelah mengubah pengiriman workflow comfy, polling, unduhan, atau pendaftaran plugin
|
||||
|
||||
## Pembuatan gambar live
|
||||
## Live pembuatan gambar
|
||||
|
||||
- Pengujian: `test/image-generation.runtime.live.test.ts`
|
||||
- Perintah: `pnpm test:live test/image-generation.runtime.live.test.ts`
|
||||
- Harness: `pnpm test:live:media image`
|
||||
- Cakupan:
|
||||
- Mengenumerasi setiap Plugin penyedia pembuatan gambar yang terdaftar
|
||||
- Memuat env var penyedia yang belum ada dari shell login Anda (`~/.profile`) sebelum melakukan probe
|
||||
- Menggunakan kunci API live/env sebelum profil autentikasi tersimpan secara default, sehingga kunci pengujian lama di `auth-profiles.json` tidak menutupi kredensial shell asli
|
||||
- Menginventarisasi setiap plugin penyedia pembuatan gambar yang terdaftar
|
||||
- Memuat env var penyedia yang hilang dari shell login Anda (`~/.profile`) sebelum melakukan probe
|
||||
- Secara default menggunakan kunci API live/env sebelum profil autentikasi tersimpan, sehingga kunci pengujian usang di `auth-profiles.json` tidak menutupi kredensial shell asli
|
||||
- Melewati penyedia tanpa autentikasi/profil/model yang dapat digunakan
|
||||
- Menjalankan setiap penyedia yang dikonfigurasi melalui runtime pembuatan gambar bersama:
|
||||
- `<provider>:generate`
|
||||
- `<provider>:edit` saat penyedia menyatakan dukungan edit
|
||||
- Penyedia bawaan saat ini yang tercakup:
|
||||
- `<provider>:edit` saat penyedia mendeklarasikan dukungan edit
|
||||
- Penyedia bawaan saat ini yang dicakup:
|
||||
- `deepinfra`
|
||||
- `fal`
|
||||
- `google`
|
||||
@ -482,15 +491,15 @@ Jika Anda ingin mengandalkan kunci env (misalnya diekspor di `~/.profile` Anda),
|
||||
- `openrouter`
|
||||
- `vydra`
|
||||
- `xai`
|
||||
- Pembatasan opsional:
|
||||
- Penyempitan opsional:
|
||||
- `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google,openrouter,xai"`
|
||||
- `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="deepinfra"`
|
||||
- `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-2,google/gemini-3.1-flash-image-preview,openrouter/google/gemini-3.1-flash-image-preview,xai/grok-imagine-image"`
|
||||
- `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit,openrouter:generate,xai:default-generate,xai:default-edit"`
|
||||
- Perilaku autentikasi opsional:
|
||||
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` untuk memaksa autentikasi penyimpanan profil dan mengabaikan override khusus env
|
||||
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` untuk memaksa autentikasi penyimpanan profil dan mengabaikan penggantian khusus env
|
||||
|
||||
Untuk jalur CLI yang dikirimkan, tambahkan smoke `infer` setelah pengujian live penyedia/runtime berhasil:
|
||||
Untuk jalur CLI yang dikirimkan, tambahkan smoke `infer` setelah pengujian live penyedia/runtime lulus:
|
||||
|
||||
```bash
|
||||
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_INFER_CLI_TEST=1 pnpm test:live -- test/image-generation.infer-cli.live.test.ts
|
||||
@ -502,77 +511,77 @@ openclaw infer image generate \
|
||||
--json
|
||||
```
|
||||
|
||||
Ini mencakup parsing argumen CLI, resolusi konfigurasi/agen default, aktivasi
|
||||
Plugin bawaan, runtime pembuatan gambar bersama, dan permintaan penyedia live.
|
||||
Dependensi Plugin diharapkan sudah ada sebelum pemuatan runtime.
|
||||
Ini mencakup parsing argumen CLI, resolusi konfigurasi/default-agent, aktivasi
|
||||
plugin bawaan, runtime pembuatan gambar bersama, dan permintaan penyedia live.
|
||||
Dependensi plugin diharapkan sudah ada sebelum pemuatan runtime.
|
||||
|
||||
## Pembuatan musik live
|
||||
## Live pembuatan musik
|
||||
|
||||
- Pengujian: `extensions/music-generation-providers.live.test.ts`
|
||||
- Aktifkan: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts`
|
||||
- Harness: `pnpm test:live:media music`
|
||||
- Cakupan:
|
||||
- Menjalankan jalur penyedia pembuatan musik bawaan bersama
|
||||
- Menguji jalur penyedia pembuatan musik bawaan bersama
|
||||
- Saat ini mencakup Google dan MiniMax
|
||||
- Memuat env var penyedia dari shell login Anda (`~/.profile`) sebelum melakukan probe
|
||||
- Menggunakan kunci API live/env sebelum profil autentikasi tersimpan secara default, sehingga kunci pengujian lama di `auth-profiles.json` tidak menutupi kredensial shell asli
|
||||
- Secara default menggunakan kunci API live/env sebelum profil autentikasi tersimpan, sehingga kunci pengujian usang di `auth-profiles.json` tidak menutupi kredensial shell asli
|
||||
- Melewati penyedia tanpa autentikasi/profil/model yang dapat digunakan
|
||||
- Menjalankan kedua mode runtime yang dinyatakan saat tersedia:
|
||||
- `generate` dengan input hanya prompt
|
||||
- `edit` saat penyedia menyatakan `capabilities.edit.enabled`
|
||||
- Menjalankan kedua mode runtime yang dideklarasikan saat tersedia:
|
||||
- `generate` dengan input prompt saja
|
||||
- `edit` saat penyedia mendeklarasikan `capabilities.edit.enabled`
|
||||
- Cakupan lane bersama saat ini:
|
||||
- `google`: `generate`, `edit`
|
||||
- `minimax`: `generate`
|
||||
- `comfy`: file live Comfy terpisah, bukan sweep bersama ini
|
||||
- Pembatasan opsional:
|
||||
- Penyempitan opsional:
|
||||
- `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"`
|
||||
- `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.6"`
|
||||
- Perilaku autentikasi opsional:
|
||||
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` untuk memaksa autentikasi penyimpanan profil dan mengabaikan override khusus env
|
||||
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` untuk memaksa autentikasi penyimpanan profil dan mengabaikan penggantian khusus env
|
||||
|
||||
## Pembuatan video live
|
||||
## Live pembuatan video
|
||||
|
||||
- Pengujian: `extensions/video-generation-providers.live.test.ts`
|
||||
- Aktifkan: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts`
|
||||
- Harness: `pnpm test:live:media video`
|
||||
- Cakupan:
|
||||
- Menjalankan jalur penyedia pembuatan video bawaan bersama
|
||||
- Secara default menggunakan jalur smoke yang aman untuk rilis: penyedia non-FAL, satu permintaan teks-ke-video per penyedia, prompt lobster satu detik, dan batas operasi per penyedia dari `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` secara default)
|
||||
- Melewati FAL secara default karena latensi antrean sisi penyedia dapat mendominasi waktu rilis; teruskan `--video-providers fal` atau `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` untuk menjalankannya secara eksplisit
|
||||
- Menguji jalur penyedia pembuatan video bawaan bersama
|
||||
- Secara default menggunakan jalur smoke yang aman untuk rilis: penyedia non-FAL, satu permintaan text-to-video per penyedia, prompt lobster satu detik, dan batas operasi per penyedia dari `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` secara default)
|
||||
- Secara default melewati FAL karena latensi antrean sisi penyedia dapat mendominasi waktu rilis; berikan `--video-providers fal` atau `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` untuk menjalankannya secara eksplisit
|
||||
- Memuat env var penyedia dari shell login Anda (`~/.profile`) sebelum melakukan probe
|
||||
- Menggunakan kunci API live/env sebelum profil autentikasi tersimpan secara default, sehingga kunci pengujian lama di `auth-profiles.json` tidak menutupi kredensial shell asli
|
||||
- Secara default menggunakan kunci API live/env sebelum profil autentikasi tersimpan, sehingga kunci pengujian usang di `auth-profiles.json` tidak menutupi kredensial shell asli
|
||||
- Melewati penyedia tanpa autentikasi/profil/model yang dapat digunakan
|
||||
- Hanya menjalankan `generate` secara default
|
||||
- Tetapkan `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` untuk juga menjalankan mode transformasi yang dinyatakan saat tersedia:
|
||||
- `imageToVideo` saat penyedia menyatakan `capabilities.imageToVideo.enabled` dan penyedia/model yang dipilih menerima input gambar lokal berbasis buffer dalam sweep bersama
|
||||
- `videoToVideo` saat penyedia menyatakan `capabilities.videoToVideo.enabled` dan penyedia/model yang dipilih menerima input video lokal berbasis buffer dalam sweep bersama
|
||||
- Penyedia `imageToVideo` yang dinyatakan tetapi dilewati saat ini dalam sweep bersama:
|
||||
- Secara default hanya menjalankan `generate`
|
||||
- Tetapkan `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` untuk juga menjalankan mode transform yang dideklarasikan saat tersedia:
|
||||
- `imageToVideo` saat penyedia mendeklarasikan `capabilities.imageToVideo.enabled` dan penyedia/model yang dipilih menerima input gambar lokal berbasis buffer dalam sweep bersama
|
||||
- `videoToVideo` saat penyedia mendeklarasikan `capabilities.videoToVideo.enabled` dan penyedia/model yang dipilih menerima input video lokal berbasis buffer dalam sweep bersama
|
||||
- Penyedia `imageToVideo` yang saat ini dideklarasikan tetapi dilewati dalam sweep bersama:
|
||||
- `vydra` karena `veo3` bawaan hanya teks dan `kling` bawaan memerlukan URL gambar jarak jauh
|
||||
- Cakupan Vydra spesifik penyedia:
|
||||
- `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts`
|
||||
- file tersebut menjalankan teks-ke-video `veo3` ditambah lane `kling` yang menggunakan fixture URL gambar jarak jauh secara default
|
||||
- file tersebut menjalankan text-to-video `veo3` ditambah lane `kling` yang secara default menggunakan fixture URL gambar jarak jauh
|
||||
- Cakupan live `videoToVideo` saat ini:
|
||||
- `runway` hanya saat model yang dipilih adalah `runway/gen4_aleph`
|
||||
- Penyedia `videoToVideo` yang dinyatakan tetapi dilewati saat ini dalam sweep bersama:
|
||||
- Penyedia `videoToVideo` yang saat ini dideklarasikan tetapi dilewati dalam sweep bersama:
|
||||
- `alibaba`, `qwen`, `xai` karena jalur tersebut saat ini memerlukan URL referensi `http(s)` / MP4 jarak jauh
|
||||
- `google` karena lane Gemini/Veo bersama saat ini menggunakan input lokal berbasis buffer dan jalur tersebut tidak diterima dalam sweep bersama
|
||||
- `openai` karena lane bersama saat ini tidak memiliki jaminan akses inpaint/remix video spesifik org
|
||||
- Pembatasan opsional:
|
||||
- `google` karena lane Gemini/Veo bersama saat ini menggunakan input lokal berbasis buffer dan jalur itu tidak diterima dalam sweep bersama
|
||||
- `openai` karena lane bersama saat ini tidak memiliki jaminan akses inpaint/remix video khusus org
|
||||
- Penyempitan opsional:
|
||||
- `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="deepinfra,google,openai,runway"`
|
||||
- `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"`
|
||||
- `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` untuk menyertakan setiap penyedia dalam sweep default, termasuk FAL
|
||||
- `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` untuk mengurangi batas operasi setiap penyedia bagi run smoke agresif
|
||||
- `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` untuk mengurangi batas setiap operasi penyedia bagi eksekusi smoke yang agresif
|
||||
- Perilaku autentikasi opsional:
|
||||
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` untuk memaksa autentikasi penyimpanan profil dan mengabaikan override khusus env
|
||||
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` untuk memaksa autentikasi penyimpanan profil dan mengabaikan penggantian khusus env
|
||||
|
||||
## Harness media live
|
||||
## Harness live media
|
||||
|
||||
- Perintah: `pnpm test:live:media`
|
||||
- Tujuan:
|
||||
- Menjalankan suite live gambar, musik, dan video bersama melalui satu entrypoint asli repo
|
||||
- Memuat otomatis env var penyedia yang belum ada dari `~/.profile`
|
||||
- Menjalankan suite live gambar, musik, dan video bersama melalui satu entrypoint native repo
|
||||
- Memuat otomatis env var penyedia yang hilang dari `~/.profile`
|
||||
- Secara default mempersempit otomatis setiap suite ke penyedia yang saat ini memiliki autentikasi yang dapat digunakan
|
||||
- Menggunakan ulang `scripts/test-live.mjs`, sehingga perilaku Heartbeat dan mode senyap tetap konsisten
|
||||
- Menggunakan ulang `scripts/test-live.mjs`, sehingga perilaku heartbeat dan mode senyap tetap konsisten
|
||||
- Contoh:
|
||||
- `pnpm test:live:media`
|
||||
- `pnpm test:live:media image video --providers openai,google,minimax`
|
||||
|
||||
@ -1,22 +1,26 @@
|
||||
---
|
||||
read_when:
|
||||
- Anda sedang membangun Plugin yang memerlukan before_tool_call, before_agent_reply, hook pesan, atau hook siklus hidup
|
||||
- Anda perlu memblokir, menulis ulang, atau mewajibkan persetujuan untuk panggilan alat dari Plugin
|
||||
- Anda perlu memblokir, menulis ulang, atau mewajibkan persetujuan untuk pemanggilan alat dari Plugin
|
||||
- Anda sedang memilih antara hook internal dan hook Plugin
|
||||
summary: 'Hook Plugin: mencegat peristiwa siklus hidup agen, alat, pesan, sesi, dan Gateway'
|
||||
summary: 'Kait Plugin: mencegat peristiwa siklus hidup agen, alat, pesan, sesi, dan Gateway'
|
||||
title: Kait Plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:35:33Z"
|
||||
generated_at: "2026-05-04T18:23:45Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 2c4ed060f1b89917e1f2f46d2da9448cd562edbcd6ce03bc9b1a83da3ed9a591
|
||||
source_hash: 37c7273036463c87e478db5678822b676c89447caee65f2f3f47a45194d1e37b
|
||||
source_path: plugins/hooks.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Hook Plugin adalah titik ekstensi dalam proses untuk Plugin OpenClaw. Gunakan saat Plugin perlu memeriksa atau mengubah eksekusi agen, pemanggilan alat, alur pesan, siklus hidup sesi, perutean subagen, instalasi, atau startup Gateway.
|
||||
Hook Plugin adalah titik ekstensi dalam proses untuk Plugin OpenClaw. Gunakan hook
|
||||
ketika sebuah Plugin perlu memeriksa atau mengubah run agen, panggilan tool, alur pesan,
|
||||
siklus hidup sesi, perutean subagen, instalasi, atau startup Gateway.
|
||||
|
||||
Gunakan [hook internal](/id/automation/hooks) sebagai gantinya saat Anda menginginkan skrip `HOOK.md` kecil yang dipasang operator untuk perintah dan peristiwa Gateway seperti `/new`, `/reset`, `/stop`, `agent:bootstrap`, atau `gateway:startup`.
|
||||
Gunakan [hook internal](/id/automation/hooks) sebagai gantinya ketika Anda menginginkan skrip
|
||||
`HOOK.md` kecil yang dipasang operator untuk event perintah dan Gateway seperti
|
||||
`/new`, `/reset`, `/stop`, `agent:bootstrap`, atau `gateway:startup`.
|
||||
|
||||
## Mulai cepat
|
||||
|
||||
@ -52,14 +56,19 @@ export default definePluginEntry({
|
||||
});
|
||||
```
|
||||
|
||||
Handler hook berjalan berurutan berdasarkan `priority` menurun. Hook dengan prioritas yang sama mempertahankan urutan pendaftaran.
|
||||
Handler hook berjalan berurutan berdasarkan `priority` menurun. Hook dengan prioritas
|
||||
yang sama mempertahankan urutan pendaftaran.
|
||||
|
||||
`api.on(name, handler, opts?)` menerima:
|
||||
|
||||
- `priority` — pengurutan handler (nilai lebih tinggi berjalan lebih dulu).
|
||||
- `timeoutMs` — anggaran opsional per hook. Saat diatur, runner hook membatalkan handler tersebut setelah anggaran habis dan melanjutkan ke handler berikutnya, alih-alih membiarkan penyiapan lambat atau pekerjaan pengingatan memakai timeout model yang dikonfigurasi pemanggil. Hilangkan ini untuk menggunakan timeout observasi/keputusan default yang diterapkan runner hook secara umum.
|
||||
- `timeoutMs` — anggaran opsional per hook. Jika diatur, runner hook membatalkan
|
||||
handler tersebut setelah anggaran terlampaui dan melanjutkan ke hook berikutnya, alih-alih
|
||||
membiarkan penyiapan lambat atau pekerjaan recall menghabiskan timeout model yang
|
||||
dikonfigurasi pemanggil. Hilangkan untuk menggunakan timeout observasi/keputusan default yang
|
||||
diterapkan runner hook secara umum.
|
||||
|
||||
Operator juga dapat mengatur anggaran hook tanpa mem-patch kode Plugin:
|
||||
Operator juga dapat menetapkan anggaran hook tanpa mem-patch kode Plugin:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -79,52 +88,61 @@ Operator juga dapat mengatur anggaran hook tanpa mem-patch kode Plugin:
|
||||
}
|
||||
```
|
||||
|
||||
`hooks.timeouts.<hookName>` menimpa `hooks.timeoutMs`, yang menimpa nilai `api.on(..., { timeoutMs })` yang ditulis Plugin. Setiap nilai yang dikonfigurasi harus berupa bilangan bulat positif tidak lebih dari 600000 milidetik. Pilih override per hook untuk hook yang diketahui lambat agar satu Plugin tidak mendapat anggaran lebih panjang di semua tempat.
|
||||
`hooks.timeouts.<hookName>` menggantikan `hooks.timeoutMs`, yang menggantikan nilai
|
||||
`api.on(..., { timeoutMs })` yang ditulis oleh Plugin. Setiap nilai yang dikonfigurasi harus
|
||||
berupa bilangan bulat positif tidak lebih dari 600000 milidetik. Utamakan override per hook
|
||||
untuk hook yang diketahui lambat agar satu Plugin tidak mendapat anggaran lebih panjang
|
||||
di semua tempat.
|
||||
|
||||
Setiap hook menerima `event.context.pluginConfig`, konfigurasi terselesaikan untuk Plugin yang mendaftarkan handler tersebut. Gunakan ini untuk keputusan hook yang memerlukan opsi Plugin saat ini; OpenClaw menyuntikkannya per handler tanpa mengubah objek peristiwa bersama yang dilihat Plugin lain.
|
||||
Setiap hook menerima `event.context.pluginConfig`, konfigurasi terselesaikan untuk
|
||||
Plugin yang mendaftarkan handler tersebut. Gunakan untuk keputusan hook yang memerlukan
|
||||
opsi Plugin saat ini; OpenClaw menyuntikkannya per handler tanpa memutasi objek event
|
||||
bersama yang dilihat oleh Plugin lain.
|
||||
|
||||
## Katalog hook
|
||||
|
||||
Hook dikelompokkan berdasarkan permukaan yang diperluas. Nama dalam **tebal** menerima hasil keputusan (blokir, batalkan, override, atau wajibkan persetujuan); yang lain hanya observasi.
|
||||
Hook dikelompokkan berdasarkan surface yang diperluas. Nama dalam **tebal** menerima
|
||||
hasil keputusan (blokir, batalkan, override, atau minta persetujuan); semua lainnya
|
||||
hanya observasi.
|
||||
|
||||
**Giliran agen**
|
||||
|
||||
- `before_model_resolve` — override penyedia atau model sebelum pesan sesi dimuat
|
||||
- `agent_turn_prepare` — gunakan injeksi giliran Plugin yang mengantre dan tambahkan konteks giliran yang sama sebelum hook prompt
|
||||
- `before_prompt_build` — tambahkan konteks dinamis atau teks prompt sistem sebelum pemanggilan model
|
||||
- `before_agent_start` — fase gabungan hanya untuk kompatibilitas; pilih dua hook di atas
|
||||
- `before_model_resolve` — override provider atau model sebelum pesan sesi dimuat
|
||||
- `agent_turn_prepare` — konsumsi injeksi giliran Plugin yang diantrekan dan tambahkan konteks giliran yang sama sebelum hook prompt
|
||||
- `before_prompt_build` — tambahkan konteks dinamis atau teks prompt sistem sebelum panggilan model
|
||||
- `before_agent_start` — fase gabungan hanya untuk kompatibilitas; utamakan dua hook di atas
|
||||
- **`before_agent_reply`** — pintaskan giliran model dengan balasan sintetis atau diam
|
||||
- **`before_agent_finalize`** — periksa jawaban akhir alami dan minta satu lintasan model lagi
|
||||
- `agent_end` — amati pesan akhir, status keberhasilan, dan durasi eksekusi
|
||||
- **`before_agent_finalize`** — periksa jawaban final alami dan minta satu pass model lagi
|
||||
- `agent_end` — amati pesan final, status berhasil, dan durasi run
|
||||
- `heartbeat_prompt_contribution` — tambahkan konteks khusus Heartbeat untuk monitor latar belakang dan Plugin siklus hidup
|
||||
|
||||
**Observasi percakapan**
|
||||
|
||||
- `model_call_started` / `model_call_ended` — amati metadata pemanggilan penyedia/model yang telah disanitasi, waktu, hasil, dan hash id permintaan terbatas tanpa konten prompt atau respons
|
||||
- `llm_input` — amati input penyedia (prompt sistem, prompt, riwayat)
|
||||
- `llm_output` — amati output penyedia
|
||||
- `model_call_started` / `model_call_ended` — amati metadata panggilan provider/model yang sudah disanitasi, timing, hasil, dan hash request-id terbatas tanpa konten prompt atau respons
|
||||
- `llm_input` — amati input provider (prompt sistem, prompt, riwayat)
|
||||
- `llm_output` — amati output provider
|
||||
|
||||
**Alat**
|
||||
**Tool**
|
||||
|
||||
- **`before_tool_call`** — tulis ulang parameter alat, blokir eksekusi, atau wajibkan persetujuan
|
||||
- `after_tool_call` — amati hasil alat, kesalahan, dan durasi
|
||||
- **`tool_result_persist`** — tulis ulang pesan asisten yang dihasilkan dari hasil alat
|
||||
- **`before_tool_call`** — tulis ulang parameter tool, blokir eksekusi, atau minta persetujuan
|
||||
- `after_tool_call` — amati hasil tool, error, dan durasi
|
||||
- **`tool_result_persist`** — tulis ulang pesan asisten yang dihasilkan dari hasil tool
|
||||
- **`before_message_write`** — periksa atau blokir penulisan pesan yang sedang berlangsung (jarang)
|
||||
|
||||
**Pesan dan pengiriman**
|
||||
|
||||
- **`inbound_claim`** — klaim pesan masuk sebelum perutean agen (balasan sintetis)
|
||||
- `message_received` — amati konten masuk, pengirim, utas, dan metadata
|
||||
- `message_received` — amati konten masuk, pengirim, thread, dan metadata
|
||||
- **`message_sending`** — tulis ulang konten keluar atau batalkan pengiriman
|
||||
- `message_sent` — amati keberhasilan atau kegagalan pengiriman keluar
|
||||
- **`before_dispatch`** — periksa atau tulis ulang dispatch keluar sebelum serah terima kanal
|
||||
- **`reply_dispatch`** — berpartisipasi dalam pipeline dispatch balasan akhir
|
||||
- **`before_dispatch`** — periksa atau tulis ulang dispatch keluar sebelum handoff channel
|
||||
- **`reply_dispatch`** — ikut serta dalam pipeline dispatch balasan final
|
||||
|
||||
**Sesi dan Compaction**
|
||||
|
||||
- `session_start` / `session_end` — lacak batas siklus hidup sesi
|
||||
- `before_compaction` / `after_compaction` — amati atau anotasi siklus Compaction
|
||||
- `before_reset` — amati peristiwa reset sesi (`/reset`, reset programatik)
|
||||
- `before_reset` — amati event reset sesi (`/reset`, reset programatik)
|
||||
|
||||
**Subagen**
|
||||
|
||||
@ -134,9 +152,9 @@ Hook dikelompokkan berdasarkan permukaan yang diperluas. Nama dalam **tebal** me
|
||||
|
||||
- `gateway_start` / `gateway_stop` — mulai atau hentikan layanan milik Plugin bersama Gateway
|
||||
- `cron_changed` — amati perubahan siklus hidup Cron milik Gateway (ditambahkan, diperbarui, dihapus, dimulai, selesai, dijadwalkan)
|
||||
- **`before_install`** — periksa pemindaian pemasangan skill atau Plugin dan blokir secara opsional
|
||||
- **`before_install`** — periksa pemindaian instalasi Skills atau Plugin dan secara opsional blokir
|
||||
|
||||
## Kebijakan pemanggilan alat
|
||||
## Kebijakan panggilan tool
|
||||
|
||||
`before_tool_call` menerima:
|
||||
|
||||
@ -144,9 +162,10 @@ Hook dikelompokkan berdasarkan permukaan yang diperluas. Nama dalam **tebal** me
|
||||
- `event.params`
|
||||
- `event.runId` opsional
|
||||
- `event.toolCallId` opsional
|
||||
- bidang konteks seperti `ctx.agentId`, `ctx.sessionKey`, `ctx.sessionId`, `ctx.runId`, `ctx.jobId` (diatur pada eksekusi yang digerakkan Cron), dan diagnostik `ctx.trace`
|
||||
- field konteks seperti `ctx.agentId`, `ctx.sessionKey`, `ctx.sessionId`,
|
||||
`ctx.runId`, `ctx.jobId` (diatur pada run yang digerakkan Cron), dan diagnostik `ctx.trace`
|
||||
|
||||
Ini dapat mengembalikan:
|
||||
Hook ini dapat mengembalikan:
|
||||
|
||||
```typescript
|
||||
type BeforeToolCallResult = {
|
||||
@ -171,43 +190,104 @@ Aturan:
|
||||
|
||||
- `block: true` bersifat terminal dan melewati handler berprioritas lebih rendah.
|
||||
- `block: false` diperlakukan sebagai tanpa keputusan.
|
||||
- `params` menulis ulang parameter alat untuk eksekusi.
|
||||
- `requireApproval` menjeda eksekusi agen dan meminta pengguna melalui persetujuan Plugin. Perintah `/approve` dapat menyetujui persetujuan exec dan Plugin.
|
||||
- `block: true` berprioritas lebih rendah masih dapat memblokir setelah hook berprioritas lebih tinggi meminta persetujuan.
|
||||
- `onResolution` menerima keputusan persetujuan yang terselesaikan — `allow-once`, `allow-always`, `deny`, `timeout`, atau `cancelled`.
|
||||
- `params` menulis ulang parameter tool untuk eksekusi.
|
||||
- `requireApproval` menjeda run agen dan meminta pengguna melalui persetujuan Plugin.
|
||||
Perintah `/approve` dapat menyetujui persetujuan exec dan Plugin.
|
||||
- `block: true` berprioritas lebih rendah masih dapat memblokir setelah hook berprioritas lebih tinggi
|
||||
meminta persetujuan.
|
||||
- `onResolution` menerima keputusan persetujuan terselesaikan — `allow-once`,
|
||||
`allow-always`, `deny`, `timeout`, atau `cancelled`.
|
||||
|
||||
Plugin bawaan yang memerlukan kebijakan tingkat host dapat mendaftarkan kebijakan alat tepercaya dengan `api.registerTrustedToolPolicy(...)`. Ini berjalan sebelum hook `before_tool_call` biasa dan sebelum keputusan Plugin eksternal. Gunakan hanya untuk gerbang yang dipercaya host seperti kebijakan workspace, penegakan anggaran, atau keselamatan alur kerja cadangan. Plugin eksternal sebaiknya menggunakan hook `before_tool_call` normal.
|
||||
Plugin bawaan yang memerlukan kebijakan tingkat host dapat mendaftarkan kebijakan tool tepercaya
|
||||
dengan `api.registerTrustedToolPolicy(...)`. Kebijakan ini berjalan sebelum hook
|
||||
`before_tool_call` biasa dan sebelum keputusan Plugin eksternal. Gunakan hanya
|
||||
untuk gate yang dipercaya host seperti kebijakan workspace, penegakan anggaran, atau
|
||||
keselamatan workflow yang dicadangkan. Plugin eksternal harus menggunakan hook `before_tool_call`
|
||||
normal.
|
||||
|
||||
### Persistensi hasil alat
|
||||
### Persistensi hasil tool
|
||||
|
||||
Hasil alat dapat menyertakan `details` terstruktur untuk rendering UI, diagnostik, perutean media, atau metadata milik Plugin. Perlakukan `details` sebagai metadata runtime, bukan konten prompt:
|
||||
Hasil tool dapat menyertakan `details` terstruktur untuk rendering UI, diagnostik,
|
||||
perutean media, atau metadata milik Plugin. Perlakukan `details` sebagai metadata runtime,
|
||||
bukan konten prompt:
|
||||
|
||||
- OpenClaw menghapus `toolResult.details` sebelum replay penyedia dan input Compaction agar metadata tidak menjadi konteks model.
|
||||
- Entri sesi yang dipersistensikan hanya menyimpan `details` terbatas. Detail yang terlalu besar diganti dengan ringkasan ringkas dan `persistedDetailsTruncated: true`.
|
||||
- `tool_result_persist` dan `before_message_write` berjalan sebelum batas persistensi akhir. Hook tetap harus menjaga `details` yang dikembalikan tetap kecil dan menghindari penempatan teks yang relevan dengan prompt hanya di `details`; letakkan output alat yang terlihat oleh model di `content`.
|
||||
- OpenClaw menghapus `toolResult.details` sebelum replay provider dan input Compaction
|
||||
agar metadata tidak menjadi konteks model.
|
||||
- Entri sesi yang dipersistensikan hanya menyimpan `details` terbatas. Detail yang terlalu besar
|
||||
diganti dengan ringkasan ringkas dan `persistedDetailsTruncated: true`.
|
||||
- `tool_result_persist` dan `before_message_write` berjalan sebelum batas persistensi final.
|
||||
Hook tetap harus menjaga `details` yang dikembalikan tetap kecil dan menghindari
|
||||
penempatan teks relevan prompt hanya di `details`; letakkan output tool yang terlihat model
|
||||
di `content`.
|
||||
|
||||
## Hook prompt dan model
|
||||
|
||||
Gunakan hook khusus fase untuk Plugin baru:
|
||||
|
||||
- `before_model_resolve`: hanya menerima prompt saat ini dan metadata lampiran. Kembalikan `providerOverride` atau `modelOverride`.
|
||||
- `agent_turn_prepare`: menerima prompt saat ini, pesan sesi yang disiapkan, dan injeksi antrean tepat-sekali apa pun yang dikuras untuk sesi ini. Kembalikan `prependContext` atau `appendContext`.
|
||||
- `before_prompt_build`: menerima prompt saat ini dan pesan sesi. Kembalikan `prependContext`, `appendContext`, `systemPrompt`, `prependSystemContext`, atau `appendSystemContext`.
|
||||
- `heartbeat_prompt_contribution`: berjalan hanya untuk giliran Heartbeat dan mengembalikan `prependContext` atau `appendContext`. Ini ditujukan untuk monitor latar belakang yang perlu merangkum status saat ini tanpa mengubah giliran yang diinisiasi pengguna.
|
||||
- `before_model_resolve`: hanya menerima prompt saat ini dan metadata lampiran.
|
||||
Kembalikan `providerOverride` atau `modelOverride`.
|
||||
- `agent_turn_prepare`: menerima prompt saat ini, pesan sesi yang sudah disiapkan,
|
||||
dan injeksi antrean exactly-once apa pun yang dikuras untuk sesi ini. Kembalikan
|
||||
`prependContext` atau `appendContext`.
|
||||
- `before_prompt_build`: menerima prompt saat ini dan pesan sesi.
|
||||
Kembalikan `prependContext`, `appendContext`, `systemPrompt`,
|
||||
`prependSystemContext`, atau `appendSystemContext`.
|
||||
- `heartbeat_prompt_contribution`: berjalan hanya untuk giliran Heartbeat dan mengembalikan
|
||||
`prependContext` atau `appendContext`. Ini ditujukan untuk monitor latar belakang
|
||||
yang perlu meringkas status saat ini tanpa mengubah giliran yang dimulai pengguna.
|
||||
|
||||
`before_agent_start` tetap ada untuk kompatibilitas. Pilih hook eksplisit di atas agar Plugin Anda tidak bergantung pada fase gabungan lama.
|
||||
`before_agent_start` tetap tersedia untuk kompatibilitas. Utamakan hook eksplisit di atas
|
||||
agar Plugin Anda tidak bergantung pada fase gabungan lama.
|
||||
|
||||
`before_agent_start` dan `agent_end` menyertakan `event.runId` saat OpenClaw dapat mengidentifikasi eksekusi aktif. Nilai yang sama juga tersedia pada `ctx.runId`. Eksekusi yang digerakkan Cron juga mengekspos `ctx.jobId` (id job Cron asal) agar hook Plugin dapat membatasi metrik, efek samping, atau status ke job terjadwal tertentu.
|
||||
`before_agent_start` dan `agent_end` menyertakan `event.runId` ketika OpenClaw dapat
|
||||
mengidentifikasi run aktif. Nilai yang sama juga tersedia di `ctx.runId`.
|
||||
Run yang digerakkan Cron juga mengekspos `ctx.jobId` (id job Cron asal) sehingga
|
||||
hook Plugin dapat membatasi metrik, efek samping, atau status ke job terjadwal
|
||||
tertentu.
|
||||
|
||||
Untuk eksekusi yang berasal dari kanal, `ctx.messageProvider` adalah permukaan penyedia seperti `discord` atau `telegram`, sedangkan `ctx.channelId` adalah pengenal target percakapan saat OpenClaw dapat menurunkannya dari kunci sesi atau metadata pengiriman.
|
||||
Untuk run yang berasal dari channel, `ctx.messageProvider` adalah surface provider seperti
|
||||
`discord` atau `telegram`, sedangkan `ctx.channelId` adalah pengidentifikasi target percakapan
|
||||
ketika OpenClaw dapat menurunkannya dari kunci sesi atau metadata pengiriman.
|
||||
|
||||
`agent_end` adalah hook observasi dan berjalan fire-and-forget setelah giliran. Runner hook menerapkan timeout 30 detik agar Plugin atau endpoint embedding yang macet tidak membuat promise hook tertunda selamanya. Timeout dicatat dan OpenClaw melanjutkan; ini tidak membatalkan pekerjaan jaringan milik Plugin kecuali Plugin juga menggunakan sinyal abort-nya sendiri.
|
||||
`agent_end` adalah hook observasi dan berjalan fire-and-forget setelah giliran. Runner
|
||||
hook menerapkan timeout 30 detik agar Plugin yang macet atau endpoint embedding
|
||||
tidak dapat membuat promise hook tertunda selamanya. Timeout dicatat dan
|
||||
OpenClaw melanjutkan; timeout tidak membatalkan pekerjaan jaringan milik Plugin kecuali
|
||||
Plugin juga menggunakan sinyal abort miliknya sendiri.
|
||||
|
||||
Gunakan `model_call_started` dan `model_call_ended` untuk telemetri pemanggilan penyedia yang tidak boleh menerima prompt mentah, riwayat, respons, header, body permintaan, atau ID permintaan penyedia. Hook ini menyertakan metadata stabil seperti `runId`, `callId`, `provider`, `model`, `api`/`transport` opsional, `durationMs`/`outcome` terminal, dan `upstreamRequestIdHash` saat OpenClaw dapat menurunkan hash id permintaan penyedia terbatas.
|
||||
Gunakan `model_call_started` dan `model_call_ended` untuk telemetri panggilan provider
|
||||
yang tidak boleh menerima prompt mentah, riwayat, respons, header, body request,
|
||||
atau ID request provider. Hook ini menyertakan metadata stabil seperti
|
||||
`runId`, `callId`, `provider`, `model`, `api`/`transport` opsional, terminal
|
||||
`durationMs`/`outcome`, dan `upstreamRequestIdHash` ketika OpenClaw dapat menurunkan
|
||||
hash request-id provider yang terbatas.
|
||||
|
||||
`before_agent_finalize` berjalan hanya saat harness akan menerima jawaban akhir asisten alami. Ini bukan jalur pembatalan `/stop` dan tidak berjalan saat pengguna membatalkan giliran. Kembalikan `{ action: "revise", reason }` untuk meminta harness melakukan satu lintasan model lagi sebelum finalisasi, `{ action: "finalize", reason? }` untuk memaksa finalisasi, atau hilangkan hasil untuk melanjutkan. Hook `Stop` native Codex diteruskan ke hook ini sebagai keputusan `before_agent_finalize` OpenClaw.
|
||||
`before_agent_finalize` berjalan hanya ketika harness akan menerima jawaban asisten final
|
||||
alami. Ini bukan jalur pembatalan `/stop` dan tidak berjalan ketika pengguna membatalkan
|
||||
sebuah giliran. Kembalikan `{ action: "revise", reason }` untuk meminta harness
|
||||
melakukan satu pass model lagi sebelum finalisasi, `{ action:
|
||||
"finalize", reason? }` untuk memaksa finalisasi, atau hilangkan hasil untuk melanjutkan.
|
||||
Hook `Stop` native Codex diteruskan ke hook ini sebagai keputusan
|
||||
`before_agent_finalize` OpenClaw.
|
||||
|
||||
Plugin non-bawaan yang memerlukan `llm_input`, `llm_output`, `before_agent_finalize`, atau `agent_end` harus mengatur:
|
||||
Saat mengembalikan `action: "revise"`, Plugin dapat menyertakan metadata `retry` untuk membuat
|
||||
pass model tambahan terbatas dan aman di-replay:
|
||||
|
||||
```typescript
|
||||
type BeforeAgentFinalizeRetry = {
|
||||
instruction: string;
|
||||
idempotencyKey?: string;
|
||||
maxAttempts?: number;
|
||||
};
|
||||
```
|
||||
|
||||
`instruction` ditambahkan ke alasan revisi yang dikirim ke harness.
|
||||
`idempotencyKey` memungkinkan host menghitung retry untuk permintaan Plugin yang sama di seluruh
|
||||
keputusan finalize yang ekuivalen, dan `maxAttempts` membatasi berapa banyak pass tambahan yang
|
||||
akan diizinkan host sebelum melanjutkan dengan jawaban final alami.
|
||||
|
||||
Plugin non-bawaan yang memerlukan `llm_input`, `llm_output`,
|
||||
`before_agent_finalize`, atau `agent_end` harus mengatur:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -223,29 +303,34 @@ Plugin non-bawaan yang memerlukan `llm_input`, `llm_output`, `before_agent_final
|
||||
}
|
||||
```
|
||||
|
||||
Hook yang mengubah prompt dan injeksi giliran berikutnya yang tahan lama dapat dinonaktifkan per Plugin dengan `plugins.entries.<id>.hooks.allowPromptInjection=false`.
|
||||
Hook yang memutasi prompt dan injeksi giliran berikutnya yang tahan lama dapat dinonaktifkan per Plugin
|
||||
dengan `plugins.entries.<id>.hooks.allowPromptInjection=false`.
|
||||
|
||||
### Ekstensi sesi dan injeksi giliran berikutnya
|
||||
|
||||
Plugin alur kerja dapat mempertahankan status sesi kecil yang kompatibel dengan JSON menggunakan `api.registerSessionExtension(...)` dan memperbaruinya melalui metode `sessions.pluginPatch` Gateway. Baris sesi memproyeksikan status ekstensi terdaftar melalui `pluginExtensions`, sehingga Control UI dan klien lain dapat merender status milik Plugin tanpa mempelajari internal Plugin.
|
||||
Plugin alur kerja dapat mempertahankan status sesi kecil yang kompatibel dengan JSON menggunakan
|
||||
`api.registerSessionExtension(...)` dan memperbaruinya melalui metode Gateway
|
||||
`sessions.pluginPatch`. Baris sesi memproyeksikan status ekstensi terdaftar
|
||||
melalui `pluginExtensions`, sehingga Control UI dan klien lain dapat merender
|
||||
status milik plugin tanpa perlu mengetahui internal plugin.
|
||||
|
||||
Gunakan `api.enqueueNextTurnInjection(...)` saat plugin memerlukan konteks tahan lama untuk
|
||||
mencapai giliran model berikutnya tepat satu kali. OpenClaw mengosongkan injeksi yang antre sebelum
|
||||
Gunakan `api.enqueueNextTurnInjection(...)` saat plugin memerlukan konteks tahan lama agar
|
||||
mencapai giliran model berikutnya tepat satu kali. OpenClaw mengosongkan injeksi yang diantrekan sebelum
|
||||
hook prompt, membuang injeksi yang kedaluwarsa, dan melakukan deduplikasi berdasarkan `idempotencyKey`
|
||||
per plugin. Ini adalah seam yang tepat untuk melanjutkan persetujuan, ringkasan kebijakan,
|
||||
delta monitor latar belakang, dan kelanjutan perintah yang harus terlihat oleh
|
||||
per plugin. Ini adalah seam yang tepat untuk resume persetujuan, ringkasan kebijakan,
|
||||
delta pemantau latar belakang, dan kelanjutan perintah yang harus terlihat oleh
|
||||
model pada giliran berikutnya tetapi tidak boleh menjadi teks prompt sistem permanen.
|
||||
|
||||
Semantik pembersihan adalah bagian dari kontrak. Pembersihan ekstensi sesi dan
|
||||
callback pembersihan siklus hidup runtime menerima `reset`, `delete`, `disable`, atau
|
||||
`restart`. Host menghapus state ekstensi sesi persisten milik plugin
|
||||
`restart`. Host menghapus status ekstensi sesi persisten milik plugin pemilik
|
||||
dan injeksi giliran berikutnya yang tertunda untuk reset/delete/disable; restart mempertahankan
|
||||
state sesi tahan lama sementara callback pembersihan memungkinkan plugin melepas job penjadwal,
|
||||
konteks run, dan resource out-of-band lain untuk generasi runtime lama.
|
||||
status sesi tahan lama sementara callback pembersihan memungkinkan plugin melepas pekerjaan scheduler,
|
||||
konteks run, dan sumber daya out-of-band lain untuk generasi runtime lama.
|
||||
|
||||
## Hook pesan
|
||||
|
||||
Gunakan hook pesan untuk perutean tingkat kanal dan kebijakan pengiriman:
|
||||
Gunakan hook pesan untuk routing tingkat kanal dan kebijakan pengiriman:
|
||||
|
||||
- `message_received`: mengamati konten masuk, pengirim, `threadId`, `messageId`,
|
||||
`senderId`, korelasi run/sesi opsional, dan metadata.
|
||||
@ -253,16 +338,16 @@ Gunakan hook pesan untuk perutean tingkat kanal dan kebijakan pengiriman:
|
||||
- `message_sent`: mengamati keberhasilan atau kegagalan akhir.
|
||||
|
||||
Untuk balasan TTS khusus audio, `content` dapat berisi transkrip lisan tersembunyi
|
||||
bahkan saat payload kanal tidak memiliki teks/caption yang terlihat. Menulis ulang
|
||||
meskipun payload kanal tidak memiliki teks/caption yang terlihat. Menulis ulang
|
||||
`content` tersebut hanya memperbarui transkrip yang terlihat oleh hook; itu tidak dirender sebagai
|
||||
caption media.
|
||||
|
||||
Konteks hook pesan mengekspos field korelasi stabil saat tersedia:
|
||||
Konteks hook pesan mengekspos kolom korelasi stabil saat tersedia:
|
||||
`ctx.sessionKey`, `ctx.runId`, `ctx.messageId`, `ctx.senderId`, `ctx.trace`,
|
||||
`ctx.traceId`, `ctx.spanId`, `ctx.parentSpanId`, dan `ctx.callDepth`. Utamakan
|
||||
field kelas satu ini sebelum membaca metadata lama.
|
||||
kolom kelas satu ini sebelum membaca metadata legacy.
|
||||
|
||||
Utamakan field `threadId` dan `replyToId` bertipe sebelum menggunakan metadata
|
||||
Utamakan kolom `threadId` dan `replyToId` bertipe sebelum menggunakan metadata
|
||||
khusus kanal.
|
||||
|
||||
Aturan keputusan:
|
||||
@ -282,50 +367,51 @@ instalasi.
|
||||
|
||||
## Siklus hidup Gateway
|
||||
|
||||
Gunakan `gateway_start` untuk layanan plugin yang memerlukan state milik Gateway. Konteks
|
||||
Gunakan `gateway_start` untuk layanan plugin yang memerlukan status milik Gateway. Konteks
|
||||
mengekspos `ctx.config`, `ctx.workspaceDir`, dan `ctx.getCron?.()` untuk
|
||||
inspeksi dan pembaruan cron. Gunakan `gateway_stop` untuk membersihkan resource
|
||||
yang berjalan lama.
|
||||
inspeksi dan pembaruan cron. Gunakan `gateway_stop` untuk membersihkan
|
||||
sumber daya yang berjalan lama.
|
||||
|
||||
Jangan bergantung pada hook internal `gateway:startup` untuk layanan runtime
|
||||
Jangan mengandalkan hook internal `gateway:startup` untuk layanan runtime
|
||||
milik plugin.
|
||||
|
||||
`cron_changed` dipicu untuk peristiwa siklus hidup cron milik gateway dengan payload
|
||||
peristiwa bertipe yang mencakup alasan `added`, `updated`, `removed`, `started`, `finished`,
|
||||
dan `scheduled`. Peristiwa membawa snapshot `PluginHookGatewayCronJob`
|
||||
dan `scheduled`. Peristiwa tersebut membawa snapshot `PluginHookGatewayCronJob`
|
||||
(termasuk `state.nextRunAtMs`, `state.lastRunStatus`, dan
|
||||
`state.lastError` saat ada) plus `PluginHookGatewayCronDeliveryStatus`
|
||||
`state.lastError` saat ada) ditambah `PluginHookGatewayCronDeliveryStatus`
|
||||
bernilai `not-requested` | `delivered` | `not-delivered` | `unknown`. Peristiwa yang dihapus
|
||||
tetap membawa snapshot job yang dihapus agar penjadwal eksternal dapat
|
||||
menyelaraskan state. Gunakan `ctx.getCron?.()` dan `ctx.config` dari konteks
|
||||
runtime saat menyinkronkan penjadwal wake eksternal, dan jadikan OpenClaw sebagai
|
||||
tetap membawa snapshot pekerjaan yang dihapus sehingga scheduler eksternal dapat
|
||||
merekonsiliasi status. Gunakan `ctx.getCron?.()` dan `ctx.config` dari konteks
|
||||
runtime saat menyinkronkan scheduler wake eksternal, dan jadikan OpenClaw sebagai
|
||||
sumber kebenaran untuk pemeriksaan jatuh tempo dan eksekusi.
|
||||
|
||||
## Penghentian dukungan mendatang
|
||||
## Depresiasi mendatang
|
||||
|
||||
Beberapa surface yang berdekatan dengan hook sudah deprecated tetapi masih didukung. Migrasikan
|
||||
Beberapa surface yang berdekatan dengan hook sudah didepresiasi tetapi masih didukung. Migrasikan
|
||||
sebelum rilis mayor berikutnya:
|
||||
|
||||
- **Envelope kanal plaintext** di handler `inbound_claim` dan `message_received`.
|
||||
- **Envelope kanal plaintext** dalam handler `inbound_claim` dan `message_received`.
|
||||
Baca `BodyForAgent` dan blok konteks pengguna terstruktur
|
||||
alih-alih mengurai teks envelope datar. Lihat
|
||||
[Envelope kanal plaintext → BodyForAgent](/id/plugins/sdk-migration#active-deprecations).
|
||||
- **`before_agent_start`** tetap ada untuk kompatibilitas. Plugin baru sebaiknya menggunakan
|
||||
`before_model_resolve` dan `before_prompt_build` alih-alih fase gabungan.
|
||||
- **`before_agent_start`** tetap ada untuk kompatibilitas. Plugin baru harus menggunakan
|
||||
`before_model_resolve` dan `before_prompt_build` alih-alih fase gabungan
|
||||
tersebut.
|
||||
- **`onResolution` dalam `before_tool_call`** kini menggunakan union bertipe
|
||||
`PluginApprovalResolution` (`allow-once` / `allow-always` / `deny` /
|
||||
`timeout` / `cancelled`) alih-alih `string` bentuk bebas.
|
||||
`timeout` / `cancelled`) alih-alih `string` bebas.
|
||||
|
||||
Untuk daftar lengkapnya — pendaftaran kapabilitas memori, profil berpikir provider,
|
||||
provider auth eksternal, tipe penemuan provider, accessor runtime tugas, dan penggantian nama
|
||||
`command-auth` → `command-status` — lihat
|
||||
[Migrasi Plugin SDK → Penghentian dukungan aktif](/id/plugins/sdk-migration#active-deprecations).
|
||||
Untuk daftar lengkapnya — pendaftaran kapabilitas memori, profil thinking
|
||||
provider, provider auth eksternal, tipe penemuan provider, accessor runtime tugas,
|
||||
dan penggantian nama `command-auth` → `command-status` — lihat
|
||||
[Migrasi Plugin SDK → Depresiasi aktif](/id/plugins/sdk-migration#active-deprecations).
|
||||
|
||||
## Terkait
|
||||
|
||||
- [Migrasi Plugin SDK](/id/plugins/sdk-migration) — penghentian dukungan aktif dan linimasa penghapusan
|
||||
- [Migrasi Plugin SDK](/id/plugins/sdk-migration) — depresiasi aktif dan timeline penghapusan
|
||||
- [Membangun plugin](/id/plugins/building-plugins)
|
||||
- [Ikhtisar Plugin SDK](/id/plugins/sdk-overview)
|
||||
- [Titik masuk Plugin](/id/plugins/sdk-entrypoints)
|
||||
- [Hook internal](/id/automation/hooks)
|
||||
- [Internal arsitektur Plugin](/id/plugins/architecture-internals)
|
||||
- [Internal arsitektur plugin](/id/plugins/architecture-internals)
|
||||
|
||||
@ -1,33 +1,33 @@
|
||||
---
|
||||
read_when:
|
||||
- Anda perlu mengetahui subpath SDK mana yang harus digunakan untuk mengimpor
|
||||
- Anda menginginkan referensi untuk semua metode registrasi pada OpenClawPluginApi
|
||||
- Anda perlu mengetahui subjalur SDK mana yang harus digunakan untuk impor
|
||||
- Anda menginginkan referensi untuk semua metode pendaftaran pada OpenClawPluginApi
|
||||
- Anda sedang mencari ekspor SDK tertentu
|
||||
sidebarTitle: Plugin SDK overview
|
||||
summary: Peta impor, referensi API pendaftaran, dan arsitektur SDK
|
||||
title: Ikhtisar Plugin SDK
|
||||
title: Gambaran umum Plugin SDK
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T09:29:00Z"
|
||||
generated_at: "2026-05-04T18:24:29Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: be5fa531e603fb6d87f84e3193ebd61be1431b57b8f284871ae15f34ca93fc69
|
||||
source_hash: 8187e7d4cfb9d6fb19bbdebfbaea0bb4d98fa5cea4742d0f82a765ae5bc60127
|
||||
source_path: plugins/sdk-overview.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
SDK Plugin adalah kontrak bertipe antara Plugin dan inti. Halaman ini adalah
|
||||
referensi untuk **apa yang harus diimpor** dan **apa yang dapat Anda daftarkan**.
|
||||
referensi untuk **apa yang perlu diimpor** dan **apa yang dapat Anda daftarkan**.
|
||||
|
||||
<Note>
|
||||
Halaman ini ditujukan untuk penulis Plugin yang menggunakan `openclaw/plugin-sdk/*` di dalam
|
||||
Halaman ini untuk penulis Plugin yang menggunakan `openclaw/plugin-sdk/*` di dalam
|
||||
OpenClaw. Untuk aplikasi eksternal, skrip, dasbor, pekerjaan CI, dan ekstensi IDE
|
||||
yang ingin menjalankan agen melalui Gateway, gunakan
|
||||
[OpenClaw App SDK](/id/concepts/openclaw-sdk) dan paket `@openclaw/sdk`
|
||||
[SDK Aplikasi OpenClaw](/id/concepts/openclaw-sdk) dan paket `@openclaw/sdk`
|
||||
sebagai gantinya.
|
||||
</Note>
|
||||
|
||||
<Tip>
|
||||
Mencari panduan cara penggunaan? Mulailah dengan [Membangun Plugin](/id/plugins/building-plugins), gunakan [Plugin kanal](/id/plugins/sdk-channel-plugins) untuk Plugin kanal, [Plugin penyedia](/id/plugins/sdk-provider-plugins) untuk Plugin penyedia, dan [Hook Plugin](/id/plugins/hooks) untuk Plugin hook alat atau siklus hidup.
|
||||
Mencari panduan cara penggunaan? Mulailah dengan [Membangun Plugin](/id/plugins/building-plugins), gunakan [Plugin channel](/id/plugins/sdk-channel-plugins) untuk Plugin channel, [Plugin provider](/id/plugins/sdk-provider-plugins) untuk Plugin provider, dan [Hook Plugin](/id/plugins/hooks) untuk Plugin hook alat atau siklus hidup.
|
||||
</Tip>
|
||||
|
||||
## Konvensi impor
|
||||
@ -40,162 +40,163 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
```
|
||||
|
||||
Setiap subpath adalah modul kecil yang mandiri. Ini menjaga startup tetap cepat dan
|
||||
mencegah masalah dependensi sirkular. Untuk helper entri/build khusus kanal,
|
||||
utamakan `openclaw/plugin-sdk/channel-core`; pertahankan `openclaw/plugin-sdk/core` untuk
|
||||
mencegah masalah dependensi melingkar. Untuk helper entry/build khusus channel,
|
||||
utamakan `openclaw/plugin-sdk/channel-core`; gunakan `openclaw/plugin-sdk/core` untuk
|
||||
permukaan payung yang lebih luas dan helper bersama seperti
|
||||
`buildChannelConfigSchema`.
|
||||
|
||||
Untuk konfigurasi kanal, terbitkan JSON Schema milik kanal melalui
|
||||
Untuk konfigurasi channel, publikasikan JSON Schema milik channel melalui
|
||||
`openclaw.plugin.json#channelConfigs`. Subpath `plugin-sdk/channel-config-schema`
|
||||
ditujukan untuk primitif skema bersama dan builder generik. Plugin bawaan OpenClaw
|
||||
menggunakan `plugin-sdk/bundled-channel-config-schema` untuk skema kanal bawaan
|
||||
yang dipertahankan. Ekspor kompatibilitas yang sudah tidak digunakan tetap ada di
|
||||
`plugin-sdk/channel-config-schema-legacy`; tidak satu pun subpath skema bawaan
|
||||
menggunakan `plugin-sdk/bundled-channel-config-schema` untuk skema channel bawaan
|
||||
yang dipertahankan. Ekspor kompatibilitas yang tidak digunakan lagi tetap ada di
|
||||
`plugin-sdk/channel-config-schema-legacy`; tidak satu pun subpath skema bawaan ini
|
||||
menjadi pola untuk Plugin baru.
|
||||
|
||||
<Warning>
|
||||
Jangan impor seam kemudahan bermerek penyedia atau kanal (misalnya
|
||||
Jangan impor seam kemudahan bermerek provider atau channel (misalnya
|
||||
`openclaw/plugin-sdk/slack`, `.../discord`, `.../signal`, `.../whatsapp`).
|
||||
Plugin bawaan menyusun subpath SDK generik di dalam barrel `api.ts` /
|
||||
`runtime-api.ts` mereka sendiri; konsumen inti harus menggunakan barrel lokal Plugin
|
||||
tersebut atau menambahkan kontrak SDK generik yang sempit saat kebutuhan benar-benar
|
||||
lintas kanal.
|
||||
`runtime-api.ts` milik mereka sendiri; konsumen inti harus menggunakan barrel lokal Plugin tersebut
|
||||
atau menambahkan kontrak SDK generik yang sempit ketika kebutuhan benar-benar
|
||||
lintas-channel.
|
||||
|
||||
Sekumpulan kecil seam helper Plugin bawaan masih muncul di peta ekspor yang dihasilkan
|
||||
ketika memiliki penggunaan pemilik yang dilacak. Seam tersebut hanya ada untuk
|
||||
pemeliharaan Plugin bawaan dan bukan path impor yang direkomendasikan untuk Plugin
|
||||
pihak ketiga baru.
|
||||
ketika seam tersebut memiliki penggunaan pemilik yang terlacak. Seam tersebut ada hanya untuk pemeliharaan
|
||||
Plugin bawaan dan tidak direkomendasikan sebagai path impor untuk Plugin pihak ketiga baru.
|
||||
|
||||
`openclaw/plugin-sdk/discord` dan `openclaw/plugin-sdk/telegram-account` juga
|
||||
dipertahankan sebagai fasad kompatibilitas yang sudah tidak digunakan untuk penggunaan
|
||||
pemilik yang dilacak. Jangan salin path impor tersebut ke Plugin baru; gunakan helper
|
||||
runtime yang diinjeksi dan subpath SDK kanal generik sebagai gantinya.
|
||||
dipertahankan sebagai facade kompatibilitas yang tidak digunakan lagi untuk penggunaan pemilik yang terlacak. Jangan
|
||||
menyalin path impor tersebut ke Plugin baru; gunakan helper runtime yang diinjeksi dan
|
||||
subpath SDK channel generik sebagai gantinya.
|
||||
</Warning>
|
||||
|
||||
## Referensi subpath
|
||||
|
||||
SDK Plugin diekspos sebagai sekumpulan subpath sempit yang dikelompokkan berdasarkan area (entri
|
||||
Plugin, kanal, penyedia, auth, runtime, kapabilitas, memori, dan helper
|
||||
SDK Plugin diekspos sebagai sekumpulan subpath sempit yang dikelompokkan menurut area (entry Plugin,
|
||||
channel, provider, auth, runtime, capability, memory, dan helper
|
||||
Plugin bawaan yang dicadangkan). Untuk katalog lengkap — dikelompokkan dan ditautkan — lihat
|
||||
[Subpath SDK Plugin](/id/plugins/sdk-subpaths).
|
||||
|
||||
Daftar yang dihasilkan berisi 200+ subpath berada di `scripts/lib/plugin-sdk-entrypoints.json`.
|
||||
Daftar 200+ subpath yang dihasilkan berada di `scripts/lib/plugin-sdk-entrypoints.json`.
|
||||
|
||||
## API pendaftaran
|
||||
|
||||
Callback `register(api)` menerima objek `OpenClawPluginApi` dengan metode
|
||||
berikut:
|
||||
Callback `register(api)` menerima objek `OpenClawPluginApi` dengan metode berikut:
|
||||
|
||||
### Pendaftaran kapabilitas
|
||||
### Pendaftaran capability
|
||||
|
||||
| Metode | Yang didaftarkan |
|
||||
| ------------------------------------------------ | ------------------------------------- |
|
||||
| `api.registerProvider(...)` | Inferensi teks (LLM) |
|
||||
| `api.registerAgentHarness(...)` | Eksekutor agen tingkat rendah eksperimental |
|
||||
| `api.registerCliBackend(...)` | Backend inferensi CLI lokal |
|
||||
| `api.registerChannel(...)` | Kanal pesan |
|
||||
| `api.registerSpeechProvider(...)` | Sintesis text-to-speech / STT |
|
||||
| `api.registerRealtimeTranscriptionProvider(...)` | Transkripsi real-time streaming |
|
||||
| `api.registerRealtimeVoiceProvider(...)` | Sesi suara real-time dupleks |
|
||||
| `api.registerMediaUnderstandingProvider(...)` | Analisis gambar/audio/video |
|
||||
| `api.registerImageGenerationProvider(...)` | Pembuatan gambar |
|
||||
| `api.registerMusicGenerationProvider(...)` | Pembuatan musik |
|
||||
| `api.registerVideoGenerationProvider(...)` | Pembuatan video |
|
||||
| `api.registerWebFetchProvider(...)` | Penyedia fetch / scrape web |
|
||||
| `api.registerWebSearchProvider(...)` | Pencarian web |
|
||||
| Metode | Yang didaftarkan |
|
||||
| ------------------------------------------------ | -------------------------------------- |
|
||||
| `api.registerProvider(...)` | Inferensi teks (LLM) |
|
||||
| `api.registerAgentHarness(...)` | Eksekutor agen level rendah eksperimental |
|
||||
| `api.registerCliBackend(...)` | Backend inferensi CLI lokal |
|
||||
| `api.registerChannel(...)` | Channel pesan |
|
||||
| `api.registerSpeechProvider(...)` | Sintesis teks-ke-ucapan / STT |
|
||||
| `api.registerRealtimeTranscriptionProvider(...)` | Transkripsi realtime streaming |
|
||||
| `api.registerRealtimeVoiceProvider(...)` | Sesi suara realtime dupleks |
|
||||
| `api.registerMediaUnderstandingProvider(...)` | Analisis gambar/audio/video |
|
||||
| `api.registerImageGenerationProvider(...)` | Pembuatan gambar |
|
||||
| `api.registerMusicGenerationProvider(...)` | Pembuatan musik |
|
||||
| `api.registerVideoGenerationProvider(...)` | Pembuatan video |
|
||||
| `api.registerWebFetchProvider(...)` | Provider pengambilan / scrape web |
|
||||
| `api.registerWebSearchProvider(...)` | Pencarian web |
|
||||
|
||||
### Alat dan perintah
|
||||
|
||||
| Metode | Yang didaftarkan |
|
||||
| ------------------------------- | --------------------------------------------- |
|
||||
| `api.registerTool(tool, opts?)` | Alat agen (wajib atau `{ optional: true }`) |
|
||||
| `api.registerCommand(def)` | Perintah kustom (melewati LLM) |
|
||||
| Metode | Yang didaftarkan |
|
||||
| ------------------------------ | ------------------------------------------------- |
|
||||
| `api.registerTool(tool, opts?)` | Alat agen (wajib atau `{ optional: true }`) |
|
||||
| `api.registerCommand(def)` | Perintah kustom (melewati LLM) |
|
||||
|
||||
Perintah Plugin dapat mengatur `agentPromptGuidance` saat agen membutuhkan petunjuk
|
||||
routing singkat milik perintah. Pertahankan teks tersebut tentang perintah itu sendiri; jangan tambahkan
|
||||
kebijakan khusus penyedia atau Plugin ke builder prompt inti.
|
||||
Perintah Plugin dapat menetapkan `agentPromptGuidance` ketika agen membutuhkan petunjuk routing singkat
|
||||
milik perintah. Pertahankan teks itu tentang perintah itu sendiri; jangan tambahkan
|
||||
kebijakan khusus provider atau Plugin ke builder prompt inti.
|
||||
|
||||
### Infrastruktur
|
||||
|
||||
| Metode | Yang didaftarkan |
|
||||
| ---------------------------------------------- | --------------------------------------- |
|
||||
| `api.registerHook(events, handler, opts?)` | Hook peristiwa |
|
||||
| `api.registerHttpRoute(params)` | Endpoint HTTP Gateway |
|
||||
| `api.registerGatewayMethod(name, handler)` | Metode RPC Gateway |
|
||||
| `api.registerGatewayDiscoveryService(service)` | Pengiklan penemuan Gateway lokal |
|
||||
| `api.registerCli(registrar, opts?)` | Subperintah CLI |
|
||||
| `api.registerService(service)` | Layanan latar belakang |
|
||||
| `api.registerInteractiveHandler(registration)` | Handler interaktif |
|
||||
| `api.registerAgentToolResultMiddleware(...)` | Middleware hasil-alat runtime |
|
||||
| `api.registerMemoryPromptSupplement(builder)` | Bagian prompt aditif yang berdekatan dengan memori |
|
||||
| `api.registerMemoryCorpusSupplement(adapter)` | Korpus pencarian/baca memori aditif |
|
||||
| Metode | Yang didaftarkan |
|
||||
| ---------------------------------------------- | ---------------------------------------- |
|
||||
| `api.registerHook(events, handler, opts?)` | Hook event |
|
||||
| `api.registerHttpRoute(params)` | Endpoint HTTP Gateway |
|
||||
| `api.registerGatewayMethod(name, handler)` | Metode RPC Gateway |
|
||||
| `api.registerGatewayDiscoveryService(service)` | Pengiklan discovery Gateway lokal |
|
||||
| `api.registerCli(registrar, opts?)` | Subperintah CLI |
|
||||
| `api.registerService(service)` | Layanan latar belakang |
|
||||
| `api.registerInteractiveHandler(registration)` | Handler interaktif |
|
||||
| `api.registerAgentToolResultMiddleware(...)` | Middleware hasil alat runtime |
|
||||
| `api.registerMemoryPromptSupplement(builder)` | Bagian prompt tambahan yang berdekatan dengan memory |
|
||||
| `api.registerMemoryCorpusSupplement(adapter)` | Korpus pencarian/baca memory tambahan |
|
||||
|
||||
### Hook host untuk Plugin alur kerja
|
||||
### Hook host untuk Plugin workflow
|
||||
|
||||
Hook host adalah seam SDK untuk Plugin yang perlu berpartisipasi dalam siklus hidup
|
||||
host, bukan hanya menambahkan penyedia, kanal, atau alat. Hook ini adalah
|
||||
kontrak generik; Plan Mode dapat menggunakannya, begitu juga alur kerja persetujuan,
|
||||
gerbang kebijakan workspace, monitor latar belakang, wizard penyiapan, dan Plugin pendamping UI.
|
||||
Hook host adalah seam SDK untuk Plugin yang perlu berpartisipasi dalam siklus hidup host
|
||||
alih-alih hanya menambahkan provider, channel, atau alat. Hook ini adalah
|
||||
kontrak generik; Plan Mode dapat menggunakannya, begitu juga workflow persetujuan,
|
||||
gate kebijakan workspace, monitor latar belakang, wizard setup, dan Plugin pendamping UI.
|
||||
|
||||
| Metode | Kontrak yang dimilikinya |
|
||||
| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `api.registerSessionExtension(...)` | State sesi milik Plugin yang kompatibel dengan JSON dan diproyeksikan melalui sesi Gateway |
|
||||
| `api.enqueueNextTurnInjection(...)` | Konteks durable exactly-once yang diinjeksi ke giliran agen berikutnya untuk satu sesi |
|
||||
| `api.registerTrustedToolPolicy(...)` | Kebijakan alat pra-Plugin bawaan/tepercaya yang dapat memblokir atau menulis ulang parameter alat |
|
||||
| `api.registerToolMetadata(...)` | Metadata tampilan katalog alat tanpa mengubah implementasi alat |
|
||||
| `api.registerCommand(...)` | Perintah Plugin berscope; hasil perintah dapat mengatur `continueAgent: true`; perintah native Discord mendukung `descriptionLocalizations` |
|
||||
| `api.registerControlUiDescriptor(...)` | Deskriptor kontribusi Control UI untuk permukaan sesi, alat, run, atau pengaturan |
|
||||
| `api.registerRuntimeLifecycle(...)` | Callback pembersihan untuk sumber daya runtime milik Plugin pada path reset/delete/reload |
|
||||
| `api.registerAgentEventSubscription(...)` | Langganan peristiwa tersanitasi untuk state alur kerja dan monitor |
|
||||
| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | State scratch Plugin per-run yang dibersihkan pada siklus hidup run terminal |
|
||||
| `api.registerSessionSchedulerJob(...)` | Rekaman pekerjaan penjadwal sesi milik Plugin dengan pembersihan deterministik |
|
||||
| Metode | Kontrak yang dimilikinya |
|
||||
| ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `api.registerSessionExtension(...)` | State sesi milik Plugin yang kompatibel dengan JSON dan diproyeksikan melalui sesi Gateway |
|
||||
| `api.enqueueNextTurnInjection(...)` | Konteks exactly-once yang tahan lama, diinjeksi ke giliran agen berikutnya untuk satu sesi |
|
||||
| `api.registerTrustedToolPolicy(...)` | Kebijakan alat pra-Plugin bawaan/tepercaya yang dapat memblokir atau menulis ulang params alat |
|
||||
| `api.registerToolMetadata(...)` | Metadata tampilan katalog alat tanpa mengubah implementasi alat |
|
||||
| `api.registerCommand(...)` | Perintah Plugin berscope; hasil perintah dapat menetapkan `continueAgent: true`; perintah native Discord mendukung `descriptionLocalizations` |
|
||||
| `api.registerControlUiDescriptor(...)` | Descriptor kontribusi Control UI untuk permukaan sesi, alat, run, atau pengaturan |
|
||||
| `api.registerRuntimeLifecycle(...)` | Callback cleanup untuk resource runtime milik Plugin pada path reset/delete/reload |
|
||||
| `api.registerAgentEventSubscription(...)` | Langganan event yang disanitasi untuk state workflow dan monitor |
|
||||
| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | State scratch Plugin per-run yang dibersihkan pada siklus hidup run terminal |
|
||||
| `api.registerSessionSchedulerJob(...)` | Record pekerjaan scheduler sesi milik Plugin dengan cleanup deterministik |
|
||||
|
||||
Kontrak sengaja memisahkan otoritas:
|
||||
Kontrak ini sengaja membagi otoritas:
|
||||
|
||||
- Plugin eksternal dapat memiliki ekstensi sesi, deskriptor UI, perintah, metadata alat, injeksi giliran berikutnya, dan hook normal.
|
||||
- Kebijakan alat tepercaya berjalan sebelum hook `before_tool_call` biasa dan hanya untuk bawaan karena berpartisipasi dalam kebijakan keselamatan host.
|
||||
- Kepemilikan perintah yang dicadangkan hanya untuk bawaan. Plugin eksternal harus menggunakan nama perintah atau alias mereka sendiri.
|
||||
- `allowPromptInjection=false` menonaktifkan hook yang memutasi prompt termasuk
|
||||
- Plugin eksternal dapat memiliki ekstensi sesi, descriptor UI, perintah, metadata alat,
|
||||
injeksi giliran berikutnya, dan hook normal.
|
||||
- Kebijakan alat tepercaya berjalan sebelum hook `before_tool_call` biasa dan
|
||||
hanya untuk bawaan karena berpartisipasi dalam kebijakan keamanan host.
|
||||
- Kepemilikan perintah yang dicadangkan hanya untuk bawaan. Plugin eksternal harus menggunakan
|
||||
nama perintah atau alias mereka sendiri.
|
||||
- `allowPromptInjection=false` menonaktifkan hook yang mengubah prompt termasuk
|
||||
`agent_turn_prepare`, `before_prompt_build`, `heartbeat_prompt_contribution`,
|
||||
field prompt dari `before_agent_start` lama, dan
|
||||
field prompt dari `before_agent_start` legacy, dan
|
||||
`enqueueNextTurnInjection`.
|
||||
|
||||
Contoh konsumen non-Plan:
|
||||
|
||||
| Arketipe Plugin | Hook yang digunakan |
|
||||
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Alur kerja persetujuan | Ekstensi sesi, kelanjutan perintah, injeksi giliran berikutnya, deskriptor UI |
|
||||
| Gerbang kebijakan anggaran/workspace | Kebijakan alat tepercaya, metadata alat, proyeksi sesi |
|
||||
| Monitor siklus hidup latar belakang | Pembersihan siklus hidup runtime, langganan peristiwa agen, kepemilikan/pembersihan penjadwal sesi, kontribusi prompt Heartbeat, deskriptor UI |
|
||||
| Wizard penyiapan atau onboarding | Ekstensi sesi, perintah berscope, deskriptor Control UI |
|
||||
| Arketipe Plugin | Hook yang digunakan |
|
||||
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Workflow persetujuan | Ekstensi sesi, kelanjutan perintah, injeksi giliran berikutnya, descriptor UI |
|
||||
| Gate kebijakan anggaran/workspace | Kebijakan alat tepercaya, metadata alat, proyeksi sesi |
|
||||
| Monitor siklus hidup latar belakang | Cleanup siklus hidup runtime, langganan event agen, kepemilikan/cleanup scheduler sesi, kontribusi prompt Heartbeat, descriptor UI |
|
||||
| Wizard setup atau onboarding | Ekstensi sesi, perintah berscope, descriptor Control UI |
|
||||
|
||||
<Note>
|
||||
Namespace admin inti yang dicadangkan (`config.*`, `exec.approvals.*`, `wizard.*`,
|
||||
`update.*`) selalu tetap `operator.admin`, meskipun Plugin mencoba menetapkan
|
||||
scope metode gateway yang lebih sempit. Utamakan prefiks khusus Plugin untuk
|
||||
scope metode Gateway yang lebih sempit. Utamakan prefiks khusus Plugin untuk
|
||||
metode milik Plugin.
|
||||
</Note>
|
||||
|
||||
<Accordion title="Kapan menggunakan middleware hasil-alat">
|
||||
Plugin bawaan dapat menggunakan `api.registerAgentToolResultMiddleware(...)` saat
|
||||
<Accordion title="Kapan menggunakan middleware hasil alat">
|
||||
Plugin bawaan dapat menggunakan `api.registerAgentToolResultMiddleware(...)` ketika
|
||||
mereka perlu menulis ulang hasil alat setelah eksekusi dan sebelum runtime
|
||||
memasukkan hasil tersebut kembali ke model. Ini adalah seam tepercaya yang netral terhadap runtime
|
||||
untuk pereduksi output asinkron seperti tokenjuice.
|
||||
untuk reducer output asinkron seperti tokenjuice.
|
||||
|
||||
Plugin bawaan harus mendeklarasikan `contracts.agentToolResultMiddleware` untuk setiap
|
||||
runtime target, misalnya `["pi", "codex"]`. Plugin eksternal
|
||||
tidak dapat mendaftarkan middleware ini; pertahankan hook Plugin OpenClaw normal untuk pekerjaan
|
||||
yang tidak memerlukan timing hasil-alat pra-model. Path pendaftaran factory ekstensi tertanam
|
||||
runtime yang ditargetkan, misalnya `["pi", "codex"]`. Plugin eksternal
|
||||
tidak dapat mendaftarkan middleware ini; gunakan hook Plugin OpenClaw normal untuk pekerjaan
|
||||
yang tidak membutuhkan timing hasil alat pra-model. Path pendaftaran factory ekstensi tertanam
|
||||
khusus Pi yang lama telah dihapus.
|
||||
</Accordion>
|
||||
|
||||
### Pendaftaran penemuan Gateway
|
||||
### Pendaftaran discovery Gateway
|
||||
|
||||
`api.registerGatewayDiscoveryService(...)` memungkinkan plugin mengiklankan Gateway aktif
|
||||
pada transport penemuan lokal seperti mDNS/Bonjour. OpenClaw memanggil
|
||||
layanan selama startup Gateway ketika penemuan lokal diaktifkan, meneruskan
|
||||
port Gateway saat ini dan data petunjuk TXT non-rahasia, serta memanggil
|
||||
handler `stop` yang dikembalikan selama shutdown Gateway.
|
||||
`api.registerGatewayDiscoveryService(...)` memungkinkan Plugin mengiklankan Gateway aktif
|
||||
pada transport discovery lokal seperti mDNS/Bonjour. OpenClaw memanggil
|
||||
service selama startup Gateway ketika discovery lokal diaktifkan, meneruskan
|
||||
port Gateway saat ini dan data petunjuk TXT non-rahasia, lalu memanggil handler
|
||||
`stop` yang dikembalikan selama shutdown Gateway.
|
||||
|
||||
```typescript
|
||||
api.registerGatewayDiscoveryService({
|
||||
@ -211,21 +212,21 @@ api.registerGatewayDiscoveryService({
|
||||
});
|
||||
```
|
||||
|
||||
Plugin penemuan Gateway tidak boleh memperlakukan nilai TXT yang diiklankan
|
||||
sebagai rahasia atau autentikasi. Penemuan adalah petunjuk perutean; autentikasi
|
||||
Gateway dan pinning TLS tetap memiliki kepercayaan.
|
||||
Plugin discovery Gateway tidak boleh memperlakukan nilai TXT yang diiklankan sebagai rahasia atau
|
||||
autentikasi. Discovery adalah petunjuk perutean; autentikasi Gateway dan penyematan TLS tetap
|
||||
memiliki kepercayaan.
|
||||
|
||||
### Metadata registrasi CLI
|
||||
### Metadata pendaftaran CLI
|
||||
|
||||
`api.registerCli(registrar, opts?)` menerima dua jenis metadata tingkat atas:
|
||||
|
||||
- `commands`: root perintah eksplisit yang dimiliki oleh registrar
|
||||
- `descriptors`: deskriptor perintah waktu-parse yang digunakan untuk bantuan
|
||||
root CLI, perutean, dan registrasi CLI plugin secara malas
|
||||
- `descriptors`: deskriptor perintah waktu parse yang digunakan untuk bantuan CLI root,
|
||||
perutean, dan pendaftaran CLI Plugin secara lazy
|
||||
|
||||
Jika Anda ingin perintah plugin tetap dimuat secara malas di jalur root CLI normal,
|
||||
sediakan `descriptors` yang mencakup setiap root perintah tingkat atas yang
|
||||
diekspos oleh registrar tersebut.
|
||||
Jika Anda ingin perintah Plugin tetap dimuat secara lazy di jalur CLI root normal,
|
||||
sediakan `descriptors` yang mencakup setiap root perintah tingkat atas yang diekspos oleh
|
||||
registrar tersebut.
|
||||
|
||||
```typescript
|
||||
api.registerCli(
|
||||
@ -245,98 +246,99 @@ api.registerCli(
|
||||
);
|
||||
```
|
||||
|
||||
Gunakan `commands` saja hanya ketika Anda tidak memerlukan registrasi root CLI
|
||||
secara malas. Jalur kompatibilitas eager tersebut tetap didukung, tetapi tidak
|
||||
memasang placeholder berbasis deskriptor untuk pemuatan malas waktu-parse.
|
||||
Gunakan `commands` saja hanya ketika Anda tidak memerlukan pendaftaran CLI root secara lazy.
|
||||
Jalur kompatibilitas eager itu tetap didukung, tetapi tidak memasang
|
||||
placeholder berbasis deskriptor untuk pemuatan lazy waktu parse.
|
||||
|
||||
### Registrasi backend CLI
|
||||
### Pendaftaran backend CLI
|
||||
|
||||
`api.registerCliBackend(...)` memungkinkan plugin memiliki konfigurasi default
|
||||
untuk backend CLI AI lokal seperti `codex-cli`.
|
||||
`api.registerCliBackend(...)` memungkinkan Plugin memiliki config default untuk backend
|
||||
CLI AI lokal seperti `codex-cli`.
|
||||
|
||||
- `id` backend menjadi prefiks provider dalam referensi model seperti `codex-cli/gpt-5`.
|
||||
- `config` backend menggunakan bentuk yang sama seperti `agents.defaults.cliBackends.<id>`.
|
||||
- Konfigurasi pengguna tetap menang. OpenClaw menggabungkan `agents.defaults.cliBackends.<id>` di atas
|
||||
default plugin sebelum menjalankan CLI.
|
||||
- `config` backend menggunakan bentuk yang sama dengan `agents.defaults.cliBackends.<id>`.
|
||||
- Config pengguna tetap menang. OpenClaw menggabungkan `agents.defaults.cliBackends.<id>` di atas
|
||||
default Plugin sebelum menjalankan CLI.
|
||||
- Gunakan `normalizeConfig` ketika backend memerlukan penulisan ulang kompatibilitas setelah penggabungan
|
||||
(misalnya menormalkan bentuk flag lama).
|
||||
(misalnya menormalisasi bentuk flag lama).
|
||||
- Gunakan `resolveExecutionArgs` untuk penulisan ulang argv bercakupan permintaan yang termasuk dalam
|
||||
dialek CLI, seperti memetakan tingkat berpikir OpenClaw ke flag upaya native.
|
||||
|
||||
### Slot eksklusif
|
||||
|
||||
| Metode | Yang didaftarkan |
|
||||
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `api.registerContextEngine(id, factory)` | Mesin konteks (satu aktif pada satu waktu). Callback `assemble()` menerima `availableTools` dan `citationsMode` agar mesin dapat menyesuaikan tambahan prompt. |
|
||||
| `api.registerMemoryCapability(capability)` | Kapabilitas memori terpadu |
|
||||
| `api.registerMemoryPromptSection(builder)` | Builder bagian prompt memori |
|
||||
| `api.registerMemoryFlushPlan(resolver)` | Resolver rencana flush memori |
|
||||
| `api.registerMemoryRuntime(runtime)` | Adapter runtime memori |
|
||||
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `api.registerContextEngine(id, factory)` | Mesin konteks (satu aktif pada satu waktu). Callback `assemble()` menerima `availableTools` dan `citationsMode` sehingga mesin dapat menyesuaikan penambahan prompt. |
|
||||
| `api.registerMemoryCapability(capability)` | Kapabilitas memori terpadu |
|
||||
| `api.registerMemoryPromptSection(builder)` | Builder bagian prompt memori |
|
||||
| `api.registerMemoryFlushPlan(resolver)` | Resolver rencana flush memori |
|
||||
| `api.registerMemoryRuntime(runtime)` | Adapter runtime memori |
|
||||
|
||||
### Adapter embedding memori
|
||||
|
||||
| Metode | Yang didaftarkan |
|
||||
| ---------------------------------------------- | --------------------------------------------- |
|
||||
| `api.registerMemoryEmbeddingProvider(adapter)` | Adapter embedding memori untuk plugin aktif |
|
||||
| ---------------------------------------------- | ---------------------------------------------- |
|
||||
| `api.registerMemoryEmbeddingProvider(adapter)` | Adapter embedding memori untuk Plugin aktif |
|
||||
|
||||
- `registerMemoryCapability` adalah API plugin memori eksklusif yang disarankan.
|
||||
- `registerMemoryCapability` adalah API Plugin memori eksklusif yang disarankan.
|
||||
- `registerMemoryCapability` juga dapat mengekspos `publicArtifacts.listArtifacts(...)`
|
||||
agar plugin pendamping dapat memakai artefak memori yang diekspor melalui
|
||||
`openclaw/plugin-sdk/memory-host-core` alih-alih masuk ke tata letak privat
|
||||
plugin memori tertentu.
|
||||
sehingga Plugin pendamping dapat mengonsumsi artefak memori yang diekspor melalui
|
||||
`openclaw/plugin-sdk/memory-host-core` alih-alih mengakses layout privat
|
||||
Plugin memori tertentu.
|
||||
- `registerMemoryPromptSection`, `registerMemoryFlushPlan`, dan
|
||||
`registerMemoryRuntime` adalah API plugin memori eksklusif yang kompatibel dengan legacy.
|
||||
- `MemoryFlushPlan.model` dapat menyematkan giliran flush ke referensi
|
||||
`provider/model` yang persis, seperti `ollama/qwen3:8b`, tanpa mewarisi rantai
|
||||
fallback aktif.
|
||||
- `registerMemoryEmbeddingProvider` memungkinkan plugin memori aktif mendaftarkan satu
|
||||
atau beberapa id adapter embedding (misalnya `openai`, `gemini`, atau id kustom
|
||||
yang ditentukan plugin).
|
||||
- Konfigurasi pengguna seperti `agents.defaults.memorySearch.provider` dan
|
||||
`agents.defaults.memorySearch.fallback` diselesaikan terhadap id adapter yang
|
||||
terdaftar tersebut.
|
||||
`registerMemoryRuntime` adalah API Plugin memori eksklusif yang kompatibel dengan legacy.
|
||||
- `MemoryFlushPlan.model` dapat menyematkan giliran flush ke referensi `provider/model`
|
||||
persis, seperti `ollama/qwen3:8b`, tanpa mewarisi rantai fallback aktif.
|
||||
- `registerMemoryEmbeddingProvider` memungkinkan Plugin memori aktif mendaftarkan satu
|
||||
atau lebih id adapter embedding (misalnya `openai`, `gemini`, atau id kustom
|
||||
yang ditentukan Plugin).
|
||||
- Config pengguna seperti `agents.defaults.memorySearch.provider` dan
|
||||
`agents.defaults.memorySearch.fallback` diselesaikan terhadap id adapter
|
||||
yang terdaftar tersebut.
|
||||
|
||||
### Peristiwa dan siklus hidup
|
||||
### Event dan siklus hidup
|
||||
|
||||
| Metode | Yang dilakukan |
|
||||
| Metode | Yang dilakukan |
|
||||
| -------------------------------------------- | ----------------------------- |
|
||||
| `api.on(hookName, handler, opts?)` | Hook siklus hidup bertipe |
|
||||
| `api.onConversationBindingResolved(handler)` | Callback binding percakapan |
|
||||
| `api.on(hookName, handler, opts?)` | Hook siklus hidup bertipe |
|
||||
| `api.onConversationBindingResolved(handler)` | Callback binding percakapan |
|
||||
|
||||
Lihat [Hook plugin](/id/plugins/hooks) untuk contoh, nama hook umum, dan semantik guard.
|
||||
Lihat [Hook Plugin](/id/plugins/hooks) untuk contoh, nama hook umum, dan semantik guard.
|
||||
|
||||
### Semantik keputusan hook
|
||||
|
||||
- `before_tool_call`: mengembalikan `{ block: true }` bersifat terminal. Setelah handler mana pun mengaturnya, handler dengan prioritas lebih rendah dilewati.
|
||||
- `before_tool_call`: mengembalikan `{ block: true }` bersifat terminal. Setelah handler mana pun mengaturnya, handler berprioritas lebih rendah dilewati.
|
||||
- `before_tool_call`: mengembalikan `{ block: false }` diperlakukan sebagai tanpa keputusan (sama seperti menghilangkan `block`), bukan sebagai override.
|
||||
- `before_install`: mengembalikan `{ block: true }` bersifat terminal. Setelah handler mana pun mengaturnya, handler dengan prioritas lebih rendah dilewati.
|
||||
- `before_install`: mengembalikan `{ block: true }` bersifat terminal. Setelah handler mana pun mengaturnya, handler berprioritas lebih rendah dilewati.
|
||||
- `before_install`: mengembalikan `{ block: false }` diperlakukan sebagai tanpa keputusan (sama seperti menghilangkan `block`), bukan sebagai override.
|
||||
- `reply_dispatch`: mengembalikan `{ handled: true, ... }` bersifat terminal. Setelah handler mana pun mengklaim dispatch, handler dengan prioritas lebih rendah dan jalur dispatch model default dilewati.
|
||||
- `message_sending`: mengembalikan `{ cancel: true }` bersifat terminal. Setelah handler mana pun mengaturnya, handler dengan prioritas lebih rendah dilewati.
|
||||
- `reply_dispatch`: mengembalikan `{ handled: true, ... }` bersifat terminal. Setelah handler mana pun mengklaim dispatch, handler berprioritas lebih rendah dan jalur dispatch model default dilewati.
|
||||
- `message_sending`: mengembalikan `{ cancel: true }` bersifat terminal. Setelah handler mana pun mengaturnya, handler berprioritas lebih rendah dilewati.
|
||||
- `message_sending`: mengembalikan `{ cancel: false }` diperlakukan sebagai tanpa keputusan (sama seperti menghilangkan `cancel`), bukan sebagai override.
|
||||
- `message_received`: gunakan field bertipe `threadId` saat Anda memerlukan perutean thread/topik masuk. Pertahankan `metadata` untuk tambahan khusus channel.
|
||||
- `message_received`: gunakan field bertipe `threadId` ketika Anda memerlukan perutean thread/topik masuk. Simpan `metadata` untuk tambahan khusus channel.
|
||||
- `message_sending`: gunakan field perutean bertipe `replyToId` / `threadId` sebelum fallback ke `metadata` khusus channel.
|
||||
- `gateway_start`: gunakan `ctx.config`, `ctx.workspaceDir`, dan `ctx.getCron?.()` untuk state startup milik gateway alih-alih bergantung pada hook internal `gateway:startup`.
|
||||
- `cron_changed`: amati perubahan siklus hidup cron milik gateway. Gunakan `event.job?.state?.nextRunAtMs` dan `ctx.getCron?.()` saat menyinkronkan penjadwal bangun eksternal, dan pertahankan OpenClaw sebagai sumber kebenaran untuk pemeriksaan jatuh tempo dan eksekusi.
|
||||
- `gateway_start`: gunakan `ctx.config`, `ctx.workspaceDir`, dan `ctx.getCron?.()` untuk status startup milik Gateway alih-alih bergantung pada hook internal `gateway:startup`.
|
||||
- `cron_changed`: amati perubahan siklus hidup Cron milik Gateway. Gunakan `event.job?.state?.nextRunAtMs` dan `ctx.getCron?.()` saat menyinkronkan scheduler bangun eksternal, dan pertahankan OpenClaw sebagai sumber kebenaran untuk pemeriksaan jatuh tempo dan eksekusi.
|
||||
|
||||
### Field objek API
|
||||
|
||||
| Field | Tipe | Deskripsi |
|
||||
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------ |
|
||||
| `api.id` | `string` | Id plugin |
|
||||
| `api.name` | `string` | Nama tampilan |
|
||||
| `api.version` | `string?` | Versi plugin (opsional) |
|
||||
| `api.description` | `string?` | Deskripsi plugin (opsional) |
|
||||
| `api.source` | `string` | Jalur sumber plugin |
|
||||
| `api.rootDir` | `string?` | Direktori root plugin (opsional) |
|
||||
| `api.config` | `OpenClawConfig` | Snapshot konfigurasi saat ini (snapshot runtime dalam memori aktif bila tersedia) |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | Konfigurasi khusus plugin dari `plugins.entries.<id>.config` |
|
||||
| Field | Tipe | Deskripsi |
|
||||
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
|
||||
| `api.id` | `string` | Id Plugin |
|
||||
| `api.name` | `string` | Nama tampilan |
|
||||
| `api.version` | `string?` | Versi Plugin (opsional) |
|
||||
| `api.description` | `string?` | Deskripsi Plugin (opsional) |
|
||||
| `api.source` | `string` | Jalur sumber Plugin |
|
||||
| `api.rootDir` | `string?` | Direktori root Plugin (opsional) |
|
||||
| `api.config` | `OpenClawConfig` | Snapshot config saat ini (snapshot runtime in-memory aktif jika tersedia) |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | Config khusus Plugin dari `plugins.entries.<id>.config` |
|
||||
| `api.runtime` | `PluginRuntime` | [Helper runtime](/id/plugins/sdk-runtime) |
|
||||
| `api.logger` | `PluginLogger` | Logger berscope (`debug`, `info`, `warn`, `error`) |
|
||||
| `api.registrationMode` | `PluginRegistrationMode` | Mode muat saat ini; `"setup-runtime"` adalah jendela startup/setup ringan sebelum entri penuh |
|
||||
| `api.resolvePath(input)` | `(string) => string` | Selesaikan jalur relatif terhadap root plugin |
|
||||
| `api.logger` | `PluginLogger` | Logger bercakupan (`debug`, `info`, `warn`, `error`) |
|
||||
| `api.registrationMode` | `PluginRegistrationMode` | Mode pemuatan saat ini; `"setup-runtime"` adalah jendela startup/setup ringan sebelum entri penuh |
|
||||
| `api.resolvePath(input)` | `(string) => string` | Selesaikan jalur relatif terhadap root Plugin |
|
||||
|
||||
## Konvensi modul internal
|
||||
|
||||
Di dalam plugin Anda, gunakan file barrel lokal untuk impor internal:
|
||||
Di dalam Plugin Anda, gunakan file barrel lokal untuk import internal:
|
||||
|
||||
```
|
||||
my-plugin/
|
||||
@ -347,35 +349,35 @@ my-plugin/
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Jangan pernah mengimpor plugin Anda sendiri melalui `openclaw/plugin-sdk/<your-plugin>`
|
||||
dari kode produksi. Arahkan impor internal melalui `./api.ts` atau
|
||||
`./runtime-api.ts`. Jalur SDK hanya kontrak eksternal.
|
||||
Jangan pernah mengimpor Plugin Anda sendiri melalui `openclaw/plugin-sdk/<your-plugin>`
|
||||
dari kode produksi. Rutekan import internal melalui `./api.ts` atau
|
||||
`./runtime-api.ts`. Jalur SDK hanyalah kontrak eksternal.
|
||||
</Warning>
|
||||
|
||||
Permukaan publik plugin bawaan yang dimuat melalui facade (`api.ts`, `runtime-api.ts`,
|
||||
Permukaan publik Plugin bundled yang dimuat facade (`api.ts`, `runtime-api.ts`,
|
||||
`index.ts`, `setup-entry.ts`, dan file entri publik serupa) lebih memilih
|
||||
snapshot konfigurasi runtime aktif ketika OpenClaw sudah berjalan. Jika belum ada
|
||||
snapshot runtime, permukaan tersebut fallback ke file konfigurasi yang diselesaikan di disk.
|
||||
Facade plugin bawaan dalam paket harus dimuat melalui loader facade plugin
|
||||
OpenClaw; impor langsung dari `dist/extensions/...` melewati pemeriksaan manifest
|
||||
dan sidecar runtime yang digunakan instalasi paket untuk kode milik plugin.
|
||||
snapshot config runtime aktif ketika OpenClaw sudah berjalan. Jika belum ada snapshot
|
||||
runtime, permukaan tersebut fallback ke file config yang diselesaikan di disk.
|
||||
Facade Plugin bundled yang dikemas harus dimuat melalui loader facade Plugin
|
||||
OpenClaw; import langsung dari `dist/extensions/...` melewati pemeriksaan manifest
|
||||
dan runtime sidecar yang digunakan instalasi terkemas untuk kode milik Plugin.
|
||||
|
||||
Plugin provider dapat mengekspos barrel kontrak lokal plugin yang sempit ketika
|
||||
helper memang khusus provider dan belum termasuk dalam subpath SDK generik.
|
||||
Contoh bawaan:
|
||||
Plugin provider dapat mengekspos barrel kontrak lokal Plugin yang sempit ketika
|
||||
helper sengaja khusus provider dan belum cocok masuk ke subpath SDK generik.
|
||||
Contoh bundled:
|
||||
|
||||
- **Anthropic**: seam publik `api.ts` / `contract-api.ts` untuk helper stream
|
||||
beta-header Claude dan `service_tier`.
|
||||
- **Anthropic**: seam publik `api.ts` / `contract-api.ts` untuk header beta Claude
|
||||
dan helper stream `service_tier`.
|
||||
- **`@openclaw/openai-provider`**: `api.ts` mengekspor builder provider,
|
||||
helper model default, dan builder provider realtime.
|
||||
- **`@openclaw/openrouter-provider`**: `api.ts` mengekspor builder provider
|
||||
plus helper onboarding/konfigurasi.
|
||||
beserta helper onboarding/config.
|
||||
|
||||
<Warning>
|
||||
Kode produksi ekstensi juga harus menghindari impor `openclaw/plugin-sdk/<other-plugin>`.
|
||||
Jika helper benar-benar dibagikan, promosikan helper tersebut ke subpath SDK netral
|
||||
Kode produksi extension juga sebaiknya menghindari import `openclaw/plugin-sdk/<other-plugin>`.
|
||||
Jika sebuah helper benar-benar digunakan bersama, promosikan ke subpath SDK netral
|
||||
seperti `openclaw/plugin-sdk/speech`, `.../provider-model-shared`, atau permukaan
|
||||
berorientasi kapabilitas lain alih-alih mengikat dua plugin menjadi satu.
|
||||
berorientasi kapabilitas lain alih-alih menggandengkan dua Plugin.
|
||||
</Warning>
|
||||
|
||||
## Terkait
|
||||
@ -384,17 +386,17 @@ Contoh bawaan:
|
||||
<Card title="Titik masuk" icon="door-open" href="/id/plugins/sdk-entrypoints">
|
||||
Opsi `definePluginEntry` dan `defineChannelPluginEntry`.
|
||||
</Card>
|
||||
<Card title="Pembantu waktu eksekusi" icon="gears" href="/id/plugins/sdk-runtime">
|
||||
<Card title="Helper runtime" icon="gears" href="/id/plugins/sdk-runtime">
|
||||
Referensi namespace `api.runtime` lengkap.
|
||||
</Card>
|
||||
<Card title="Penyiapan dan konfigurasi" icon="sliders" href="/id/plugins/sdk-setup">
|
||||
Pengemasan, manifes, dan skema konfigurasi.
|
||||
Pemaketan, manifes, dan skema konfigurasi.
|
||||
</Card>
|
||||
<Card title="Pengujian" icon="vial" href="/id/plugins/sdk-testing">
|
||||
Utilitas pengujian dan aturan lint.
|
||||
</Card>
|
||||
<Card title="Migrasi SDK" icon="arrows-turn-right" href="/id/plugins/sdk-migration">
|
||||
Bermigrasi dari permukaan yang sudah tidak digunakan.
|
||||
Bermigrasi dari antarmuka yang sudah tidak digunakan.
|
||||
</Card>
|
||||
<Card title="Internal Plugin" icon="diagram-project" href="/id/plugins/architecture">
|
||||
Arsitektur mendalam dan model kapabilitas.
|
||||
|
||||
@ -1,40 +1,40 @@
|
||||
---
|
||||
read_when:
|
||||
- Anda menginginkan pertahanan berlapis terhadap serangan SSRF dan DNS rebinding
|
||||
- Mengonfigurasi proxy penerus eksternal untuk lalu lintas waktu eksekusi OpenClaw
|
||||
summary: Cara merutekan lalu lintas HTTP dan WebSocket waktu jalan OpenClaw melalui proksi pemfilteran yang dikelola operator
|
||||
- Anda menginginkan pertahanan berlapis terhadap serangan SSRF dan pengikatan ulang DNS
|
||||
- Mengonfigurasi proksi penerusan eksternal untuk lalu lintas waktu proses OpenClaw
|
||||
summary: Cara merutekan lalu lintas HTTP dan WebSocket runtime OpenClaw melalui proksi pemfilteran yang dikelola operator
|
||||
title: Proksi jaringan
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T07:08:13Z"
|
||||
generated_at: "2026-05-04T18:24:26Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: fc7140c5ced0e7454a6f85d1ea8f3256bbd28cc0cb42eeafe8e5e6439b90e3f0
|
||||
source_hash: eedbf3bac14800c34c7ca2e3b6879dac360a88d51b5b7449ddf41a4dd471648b
|
||||
source_path: security/network-proxy.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
# Proxy Jaringan
|
||||
# Proksi Jaringan
|
||||
|
||||
OpenClaw dapat merutekan lalu lintas HTTP dan WebSocket runtime melalui forward proxy yang dikelola operator. Ini adalah pertahanan berlapis opsional untuk deployment yang menginginkan kontrol egress terpusat, perlindungan SSRF yang lebih kuat, dan auditabilitas jaringan yang lebih baik.
|
||||
OpenClaw dapat merutekan lalu lintas HTTP dan WebSocket runtime melalui proksi penerusan yang dikelola operator. Ini adalah pertahanan berlapis opsional untuk deployment yang menginginkan kontrol egress terpusat, perlindungan SSRF yang lebih kuat, dan auditabilitas jaringan yang lebih baik.
|
||||
|
||||
OpenClaw tidak menyertakan, mengunduh, memulai, mengonfigurasi, atau mensertifikasi proxy. Anda menjalankan teknologi proxy yang sesuai dengan lingkungan Anda, dan OpenClaw merutekan klien HTTP dan WebSocket process-local normal melaluinya.
|
||||
OpenClaw tidak menyertakan, mengunduh, memulai, mengonfigurasi, atau menyertifikasi proksi. Anda menjalankan teknologi proksi yang sesuai dengan lingkungan Anda, dan OpenClaw merutekan klien HTTP dan WebSocket lokal proses yang normal melaluinya.
|
||||
|
||||
## Mengapa Menggunakan Proxy?
|
||||
## Mengapa Menggunakan Proksi?
|
||||
|
||||
Proxy memberi operator satu titik kontrol jaringan untuk lalu lintas HTTP dan WebSocket keluar. Itu dapat berguna bahkan di luar pengerasan SSRF:
|
||||
Proksi memberi operator satu titik kontrol jaringan untuk lalu lintas HTTP dan WebSocket keluar. Itu dapat berguna bahkan di luar pengerasan SSRF:
|
||||
|
||||
- Kebijakan terpusat: pelihara satu kebijakan egress alih-alih mengandalkan setiap call site HTTP aplikasi untuk menerapkan aturan jaringan dengan benar.
|
||||
- Pemeriksaan saat koneksi: evaluasi tujuan setelah resolusi DNS dan tepat sebelum proxy membuka koneksi upstream.
|
||||
- Pertahanan DNS rebinding: kurangi celah antara pemeriksaan DNS tingkat aplikasi dan koneksi keluar yang sebenarnya.
|
||||
- Cakupan JavaScript yang lebih luas: rute klien biasa seperti `fetch`, `node:http`, `node:https`, WebSocket, axios, got, node-fetch, dan klien serupa melalui jalur yang sama.
|
||||
- Kebijakan terpusat: kelola satu kebijakan egress alih-alih bergantung pada setiap lokasi panggilan HTTP aplikasi untuk menerapkan aturan jaringan dengan benar.
|
||||
- Pemeriksaan saat koneksi: evaluasi tujuan setelah resolusi DNS dan tepat sebelum proksi membuka koneksi upstream.
|
||||
- Pertahanan terhadap DNS rebinding: kurangi celah antara pemeriksaan DNS tingkat aplikasi dan koneksi keluar yang sebenarnya.
|
||||
- Cakupan JavaScript yang lebih luas: rutekan klien biasa seperti `fetch`, `node:http`, `node:https`, WebSocket, axios, got, node-fetch, dan klien serupa melalui jalur yang sama.
|
||||
- Auditabilitas: catat tujuan yang diizinkan dan ditolak di batas egress.
|
||||
- Kontrol operasional: terapkan aturan tujuan, segmentasi jaringan, batas laju, atau allowlist keluar tanpa membangun ulang OpenClaw.
|
||||
|
||||
Perutean proxy adalah guardrail tingkat proses untuk egress HTTP dan WebSocket normal. Ini memberi operator jalur fail-closed untuk merutekan klien HTTP JavaScript yang didukung melalui proxy penyaringan milik mereka sendiri, tetapi ini bukan sandbox jaringan tingkat OS dan tidak membuat OpenClaw mensertifikasi kebijakan tujuan proxy.
|
||||
Perutean proksi adalah guardrail tingkat proses untuk egress HTTP dan WebSocket normal. Ini memberi operator jalur gagal-tertutup untuk merutekan klien HTTP JavaScript yang didukung melalui proksi pemfilteran mereka sendiri, tetapi ini bukan sandbox jaringan tingkat OS dan tidak membuat OpenClaw menyertifikasi kebijakan tujuan proksi.
|
||||
|
||||
## Cara OpenClaw Merutekan Lalu Lintas
|
||||
|
||||
Ketika `proxy.enabled=true` dan URL proxy dikonfigurasi, proses runtime terlindungi seperti `openclaw gateway run`, `openclaw node run`, dan `openclaw agent --local` merutekan egress HTTP dan WebSocket normal melalui proxy yang dikonfigurasi:
|
||||
Ketika `proxy.enabled=true` dan URL proksi dikonfigurasi, proses runtime yang dilindungi seperti `openclaw gateway run`, `openclaw node run`, dan `openclaw agent --local` merutekan egress HTTP dan WebSocket normal melalui proksi yang dikonfigurasi:
|
||||
|
||||
```text
|
||||
OpenClaw process
|
||||
@ -43,27 +43,27 @@ OpenClaw process
|
||||
WebSocket clients -> operator-managed filtering proxy -> public internet
|
||||
```
|
||||
|
||||
Kontrak publiknya adalah perilaku perutean, bukan hook Node internal yang digunakan untuk mengimplementasikannya. Klien WebSocket control-plane OpenClaw Gateway menggunakan jalur langsung yang sempit untuk lalu lintas RPC Gateway local loopback ketika URL Gateway menggunakan `localhost` atau IP loopback literal seperti `127.0.0.1` atau `[::1]`. Jalur control-plane itu harus dapat menjangkau Gateway loopback bahkan ketika proxy operator memblokir tujuan loopback. Permintaan HTTP dan WebSocket runtime normal tetap menggunakan proxy yang dikonfigurasi.
|
||||
Kontrak publiknya adalah perilaku perutean, bukan hook Node internal yang digunakan untuk mengimplementasikannya. Klien WebSocket control-plane OpenClaw Gateway menggunakan jalur langsung yang sempit untuk lalu lintas RPC Gateway local loopback saat URL Gateway menggunakan `localhost` atau IP loopback literal seperti `127.0.0.1` atau `[::1]`. Jalur control-plane itu harus dapat menjangkau Gateway loopback bahkan ketika proksi operator memblokir tujuan loopback. Permintaan HTTP dan WebSocket runtime normal tetap menggunakan proksi yang dikonfigurasi.
|
||||
|
||||
Secara internal, OpenClaw menggunakan dua hook perutean tingkat proses untuk fitur ini:
|
||||
|
||||
- Perutean dispatcher Undici mencakup `fetch`, klien berbasis undici, dan transport yang menyediakan dispatcher undici miliknya sendiri.
|
||||
- Perutean `global-agent` mencakup pemanggil Node core `node:http` dan `node:https`, termasuk banyak library yang berlapis di atas `http.request`, `https.request`, `http.get`, dan `https.get`. Mode proxy terkelola memaksa agen global itu agar agen HTTP Node eksplisit tidak secara tidak sengaja melewati proxy operator.
|
||||
- Perutean dispatcher Undici mencakup `fetch`, klien berbasis undici, dan transport yang menyediakan dispatcher undici mereka sendiri.
|
||||
- Perutean `global-agent` mencakup pemanggil Node core `node:http` dan `node:https`, termasuk banyak pustaka yang dibangun di atas `http.request`, `https.request`, `http.get`, dan `https.get`. Mode proksi terkelola memaksa agent global itu agar agent HTTP Node eksplisit tidak secara tidak sengaja melewati proksi operator.
|
||||
|
||||
Beberapa Plugin memiliki transport kustom yang memerlukan wiring proxy eksplisit meskipun perutean tingkat proses sudah ada. Misalnya, transport Bot API Telegram menggunakan dispatcher undici HTTP/1 miliknya sendiri sehingga menghormati env proxy proses ditambah fallback `OPENCLAW_PROXY_URL` terkelola di jalur transport khusus pemilik tersebut.
|
||||
Beberapa Plugin memiliki transport kustom yang memerlukan penyambungan proksi eksplisit bahkan ketika perutean tingkat proses sudah ada. Misalnya, transport Bot API Telegram menggunakan dispatcher undici HTTP/1 miliknya sendiri sehingga menghormati env proksi proses plus fallback `OPENCLAW_PROXY_URL` terkelola di jalur transport khusus pemilik tersebut.
|
||||
|
||||
URL proxy itu sendiri harus menggunakan `http://`. Tujuan HTTPS tetap didukung melalui proxy dengan HTTP `CONNECT`; ini hanya berarti OpenClaw mengharapkan listener forward-proxy HTTP biasa seperti `http://127.0.0.1:3128`.
|
||||
URL proksi itu sendiri harus menggunakan `http://`. Tujuan HTTPS tetap didukung melalui proksi dengan HTTP `CONNECT`; ini hanya berarti OpenClaw mengharapkan listener proksi penerusan HTTP biasa seperti `http://127.0.0.1:3128`.
|
||||
|
||||
Saat proxy aktif, OpenClaw menghapus `no_proxy`, `NO_PROXY`, dan `GLOBAL_AGENT_NO_PROXY`. Daftar bypass tersebut berbasis tujuan, jadi membiarkan `localhost` atau `127.0.0.1` di sana akan membuat target SSRF berisiko tinggi melewati proxy penyaringan.
|
||||
Saat proksi aktif, OpenClaw mengosongkan `no_proxy`, `NO_PROXY`, dan `GLOBAL_AGENT_NO_PROXY`. Daftar bypass tersebut berbasis tujuan, sehingga membiarkan `localhost` atau `127.0.0.1` di sana akan memungkinkan target SSRF berisiko tinggi melewati proksi pemfilteran.
|
||||
|
||||
Saat shutdown, OpenClaw memulihkan lingkungan proxy sebelumnya dan mengatur ulang status perutean proses yang di-cache.
|
||||
Saat shutdown, OpenClaw memulihkan lingkungan proksi sebelumnya dan mereset status perutean proses yang di-cache.
|
||||
|
||||
## Istilah Proxy Terkait
|
||||
## Istilah Proksi Terkait
|
||||
|
||||
- `proxy.enabled` / `proxy.proxyUrl`: perutean forward-proxy keluar untuk egress runtime OpenClaw. Halaman ini mendokumentasikan fitur tersebut.
|
||||
- `gateway.auth.mode: "trusted-proxy"`: autentikasi reverse-proxy masuk yang sadar identitas untuk akses Gateway. Lihat [Autentikasi proxy tepercaya](/id/gateway/trusted-proxy-auth).
|
||||
- `openclaw proxy`: proxy debug lokal dan inspektur capture untuk pengembangan dan dukungan. Lihat [openclaw proxy](/id/cli/proxy).
|
||||
- Pengaturan proxy khusus kanal atau provider: override khusus pemilik untuk transport tertentu. Gunakan proxy jaringan terkelola ketika tujuannya adalah kontrol egress terpusat di seluruh runtime.
|
||||
- `proxy.enabled` / `proxy.proxyUrl`: perutean proksi penerusan keluar untuk egress runtime OpenClaw. Halaman ini mendokumentasikan fitur tersebut.
|
||||
- `gateway.auth.mode: "trusted-proxy"`: autentikasi proksi balik sadar identitas masuk untuk akses Gateway. Lihat [Autentikasi proksi tepercaya](/id/gateway/trusted-proxy-auth).
|
||||
- `openclaw proxy`: proksi debug lokal dan pemeriksa capture untuk pengembangan dan dukungan. Lihat [openclaw proxy](/id/cli/proxy).
|
||||
- Pengaturan proksi khusus saluran atau penyedia: override khusus pemilik untuk transport tertentu. Utamakan proksi jaringan terkelola saat tujuannya adalah kontrol egress terpusat di seluruh runtime.
|
||||
|
||||
## Konfigurasi
|
||||
|
||||
@ -73,17 +73,17 @@ proxy:
|
||||
proxyUrl: http://127.0.0.1:3128
|
||||
```
|
||||
|
||||
Anda juga dapat menyediakan URL melalui lingkungan, sambil tetap menjaga `proxy.enabled=true` di config:
|
||||
Anda juga dapat menyediakan URL melalui lingkungan, sambil tetap mempertahankan `proxy.enabled=true` dalam konfigurasi:
|
||||
|
||||
```bash
|
||||
OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run
|
||||
```
|
||||
|
||||
`proxy.proxyUrl` memiliki prioritas atas `OPENCLAW_PROXY_URL`.
|
||||
`proxy.proxyUrl` lebih diprioritaskan daripada `OPENCLAW_PROXY_URL`.
|
||||
|
||||
Jika `enabled=true` tetapi tidak ada URL proxy valid yang dikonfigurasi, perintah terlindungi gagal saat startup alih-alih kembali ke akses jaringan langsung.
|
||||
Jika `enabled=true` tetapi tidak ada URL proksi valid yang dikonfigurasi, perintah yang dilindungi akan gagal saat startup alih-alih kembali ke akses jaringan langsung.
|
||||
|
||||
Untuk layanan gateway terkelola yang dimulai dengan `openclaw gateway start`, sebaiknya simpan URL di config:
|
||||
Untuk layanan gateway terkelola yang dimulai dengan `openclaw gateway start`, sebaiknya simpan URL dalam konfigurasi:
|
||||
|
||||
```bash
|
||||
openclaw config set proxy.enabled true
|
||||
@ -92,63 +92,63 @@ openclaw gateway install --force
|
||||
openclaw gateway start
|
||||
```
|
||||
|
||||
Fallback lingkungan paling cocok untuk proses foreground. Jika Anda menggunakannya dengan layanan terinstal, letakkan `OPENCLAW_PROXY_URL` di lingkungan tahan lama layanan, seperti `$OPENCLAW_STATE_DIR/.env` atau `~/.openclaw/.env`, lalu instal ulang layanan agar launchd, systemd, atau Scheduled Tasks memulai gateway dengan nilai tersebut.
|
||||
Fallback lingkungan paling cocok untuk proses foreground. Jika Anda menggunakannya dengan layanan terpasang, letakkan `OPENCLAW_PROXY_URL` di lingkungan tahan lama layanan, seperti `$OPENCLAW_STATE_DIR/.env` atau `~/.openclaw/.env`, lalu pasang ulang layanan agar launchd, systemd, atau Scheduled Tasks memulai gateway dengan nilai tersebut.
|
||||
|
||||
Untuk perintah `openclaw --container ...`, OpenClaw meneruskan `OPENCLAW_PROXY_URL` ke CLI child yang ditargetkan ke container ketika variabel itu disetel. URL harus dapat dijangkau dari dalam container; `127.0.0.1` merujuk ke container itu sendiri, bukan host. OpenClaw menolak URL proxy loopback untuk perintah yang ditargetkan ke container kecuali Anda secara eksplisit mengoverride pemeriksaan keamanan itu.
|
||||
Untuk perintah `openclaw --container ...`, OpenClaw meneruskan `OPENCLAW_PROXY_URL` ke CLI turunan yang ditargetkan ke kontainer saat nilai itu disetel. URL harus dapat dijangkau dari dalam kontainer; `127.0.0.1` merujuk ke kontainer itu sendiri, bukan host. OpenClaw menolak URL proksi loopback untuk perintah yang ditargetkan ke kontainer kecuali Anda secara eksplisit mengganti pemeriksaan keamanan tersebut.
|
||||
|
||||
## Persyaratan Proxy
|
||||
## Persyaratan Proksi
|
||||
|
||||
Kebijakan proxy adalah batas keamanan. OpenClaw tidak dapat memverifikasi bahwa proxy memblokir target yang benar.
|
||||
Kebijakan proksi adalah batas keamanan. OpenClaw tidak dapat memverifikasi bahwa proksi memblokir target yang tepat.
|
||||
|
||||
Konfigurasikan proxy untuk:
|
||||
Konfigurasikan proksi untuk:
|
||||
|
||||
- Mengikat hanya ke loopback atau antarmuka privat tepercaya.
|
||||
- Membatasi akses sehingga hanya proses, host, container, atau akun layanan OpenClaw yang dapat menggunakannya.
|
||||
- Hanya bind ke loopback atau antarmuka privat tepercaya.
|
||||
- Membatasi akses sehingga hanya proses, host, kontainer, atau akun layanan OpenClaw yang dapat menggunakannya.
|
||||
- Meresolusi tujuan sendiri dan memblokir IP tujuan setelah resolusi DNS.
|
||||
- Menerapkan kebijakan saat koneksi untuk permintaan HTTP biasa maupun tunnel HTTPS `CONNECT`.
|
||||
- Menerapkan kebijakan pada saat koneksi untuk permintaan HTTP biasa dan tunnel HTTPS `CONNECT`.
|
||||
- Menolak bypass berbasis tujuan untuk rentang loopback, privat, link-local, metadata, multicast, reserved, atau dokumentasi.
|
||||
- Menghindari allowlist hostname kecuali Anda sepenuhnya memercayai jalur resolusi DNS.
|
||||
- Mencatat tujuan, keputusan, status, dan alasan tanpa mencatat body permintaan, header otorisasi, cookie, atau secret lainnya.
|
||||
- Menyimpan kebijakan proxy di bawah version control dan meninjau perubahan seperti konfigurasi sensitif keamanan.
|
||||
- Menghindari allowlist nama host kecuali Anda sepenuhnya memercayai jalur resolusi DNS.
|
||||
- Mencatat tujuan, keputusan, status, dan alasan tanpa mencatat body permintaan, header otorisasi, cookie, atau rahasia lainnya.
|
||||
- Menyimpan kebijakan proksi di bawah kontrol versi dan meninjau perubahan seperti konfigurasi yang sensitif terhadap keamanan.
|
||||
|
||||
## Tujuan Terblokir yang Direkomendasikan
|
||||
## Tujuan yang Direkomendasikan untuk Diblokir
|
||||
|
||||
Gunakan denylist ini sebagai titik awal untuk forward proxy, firewall, atau kebijakan egress apa pun.
|
||||
Gunakan denylist ini sebagai titik awal untuk setiap proksi penerusan, firewall, atau kebijakan egress.
|
||||
|
||||
Logika classifier tingkat aplikasi OpenClaw berada di `src/infra/net/ssrf.ts` dan `src/shared/net/ip.ts`. Hook paritas yang relevan adalah `BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, `RFC2544_BENCHMARK_PREFIX`, dan penanganan sentinel IPv4 tertanam untuk NAT64, 6to4, Teredo, ISATAP, dan bentuk IPv4-mapped. File-file tersebut adalah referensi yang berguna saat memelihara kebijakan proxy eksternal, tetapi OpenClaw tidak secara otomatis mengekspor atau menerapkan aturan tersebut di proxy Anda.
|
||||
Logika classifier tingkat aplikasi OpenClaw berada di `src/infra/net/ssrf.ts` dan `src/shared/net/ip.ts`. Hook paritas yang relevan adalah `BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, `RFC2544_BENCHMARK_PREFIX`, dan penanganan sentinel IPv4 tertanam untuk bentuk NAT64, 6to4, Teredo, ISATAP, dan IPv4-mapped. File-file tersebut adalah referensi berguna saat memelihara kebijakan proksi eksternal, tetapi OpenClaw tidak otomatis mengekspor atau menerapkan aturan tersebut di proksi Anda.
|
||||
|
||||
| Rentang atau host | Alasan memblokir |
|
||||
| Rentang atau host | Alasan untuk memblokir |
|
||||
| ------------------------------------------------------------------------------------ | --------------------------------------------------- |
|
||||
| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | Loopback IPv4 |
|
||||
| `::1/128` | Loopback IPv6 |
|
||||
| `0.0.0.0/8`, `::/128` | Alamat unspecified dan this-network |
|
||||
| `0.0.0.0/8`, `::/128` | Alamat tidak ditentukan dan jaringan-ini |
|
||||
| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | Jaringan privat RFC1918 |
|
||||
| `169.254.0.0/16`, `fe80::/10` | Alamat link-local dan jalur metadata cloud umum |
|
||||
| `169.254.0.0/16`, `fe80::/10` | Alamat link-local dan jalur metadata cloud umum |
|
||||
| `169.254.169.254`, `metadata.google.internal` | Layanan metadata cloud |
|
||||
| `100.64.0.0/10` | Ruang alamat bersama NAT carrier-grade |
|
||||
| `100.64.0.0/10` | Ruang alamat bersama NAT carrier-grade |
|
||||
| `198.18.0.0/15`, `2001:2::/48` | Rentang benchmarking |
|
||||
| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | Rentang penggunaan khusus dan dokumentasi |
|
||||
| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | Rentang penggunaan khusus dan dokumentasi |
|
||||
| `224.0.0.0/4`, `ff00::/8` | Multicast |
|
||||
| `240.0.0.0/4` | IPv4 reserved |
|
||||
| `fc00::/7`, `fec0::/10` | Rentang lokal/privat IPv6 |
|
||||
| `100::/64`, `2001:20::/28` | Rentang discard IPv6 dan ORCHIDv2 |
|
||||
| `64:ff9b::/96`, `64:ff9b:1::/48` | Prefiks NAT64 dengan IPv4 tertanam |
|
||||
| `2002::/16`, `2001::/32` | 6to4 dan Teredo dengan IPv4 tertanam |
|
||||
| `::/96`, `::ffff:0:0/96` | IPv6 kompatibel IPv4 dan IPv4-mapped |
|
||||
| `fc00::/7`, `fec0::/10` | Rentang lokal/privat IPv6 |
|
||||
| `100::/64`, `2001:20::/28` | Rentang discard IPv6 dan ORCHIDv2 |
|
||||
| `64:ff9b::/96`, `64:ff9b:1::/48` | Prefiks NAT64 dengan IPv4 tertanam |
|
||||
| `2002::/16`, `2001::/32` | 6to4 dan Teredo dengan IPv4 tertanam |
|
||||
| `::/96`, `::ffff:0:0/96` | IPv6 kompatibel IPv4 dan IPv6 IPv4-mapped |
|
||||
|
||||
Jika penyedia cloud atau platform jaringan Anda mendokumentasikan host metadata atau rentang reserved tambahan, tambahkan juga.
|
||||
|
||||
## Validasi
|
||||
|
||||
Validasi proxy dari host, container, atau akun layanan yang sama yang menjalankan OpenClaw:
|
||||
Validasikan proksi dari host, kontainer, atau akun layanan yang sama yang menjalankan OpenClaw:
|
||||
|
||||
```bash
|
||||
openclaw proxy validate --proxy-url http://127.0.0.1:3128
|
||||
```
|
||||
|
||||
Secara default, ketika tidak ada tujuan kustom yang diberikan, perintah memeriksa bahwa `https://example.com/` berhasil dan memulai canary loopback sementara yang tidak boleh dijangkau proxy. Pemeriksaan penolakan default lulus ketika proxy mengembalikan respons penolakan non-2xx atau memblokir canary dengan kegagalan transport; pemeriksaan gagal jika respons berhasil mencapai canary. Jika tidak ada proxy yang diaktifkan dan dikonfigurasi, validasi melaporkan masalah config; gunakan `--proxy-url` untuk preflight sekali jalan sebelum mengubah config. Gunakan `--allowed-url` dan `--denied-url` untuk menguji ekspektasi khusus deployment. Tujuan penolakan kustom bersifat fail-closed: respons HTTP apa pun berarti tujuan dapat dijangkau melalui proxy, dan error transport apa pun dilaporkan sebagai inkonklusif karena OpenClaw tidak dapat membuktikan proxy memblokir origin yang dapat dijangkau. Saat validasi gagal, perintah keluar dengan kode 1.
|
||||
Secara default, ketika tidak ada tujuan kustom yang disediakan, perintah memeriksa bahwa `https://example.com/` berhasil dan memulai canary loopback sementara yang tidak boleh dijangkau proksi. Pemeriksaan ditolak default lulus ketika proksi mengembalikan respons penolakan non-2xx atau memblokir canary dengan kegagalan transport; pemeriksaan gagal jika respons berhasil mencapai canary. Jika tidak ada proksi yang diaktifkan dan dikonfigurasi, validasi melaporkan masalah konfigurasi; gunakan `--proxy-url` untuk preflight sekali jalan sebelum mengubah konfigurasi. Gunakan `--allowed-url` dan `--denied-url` untuk menguji ekspektasi khusus deployment. Tambahkan `--apns-reachable` untuk juga memverifikasi bahwa pengiriman HTTP/2 APNs langsung dapat membuka tunnel CONNECT melalui proksi dan menerima respons APNs sandbox; probe menggunakan token penyedia yang sengaja tidak valid, sehingga `403 InvalidProviderToken` diharapkan dan dihitung sebagai dapat dijangkau. Tujuan ditolak kustom bersifat gagal-tertutup: respons HTTP apa pun berarti tujuan dapat dijangkau melalui proksi, dan setiap error transport dilaporkan sebagai tidak meyakinkan karena OpenClaw tidak dapat membuktikan proksi memblokir origin yang dapat dijangkau. Pada kegagalan validasi, perintah keluar dengan kode 1.
|
||||
|
||||
Gunakan `--json` untuk otomasi. Output JSON berisi hasil keseluruhan, sumber config proxy efektif, error config apa pun, dan setiap pemeriksaan tujuan. Kredensial URL proxy disunting dalam output teks dan JSON:
|
||||
Gunakan `--json` untuk otomatisasi. Output JSON berisi hasil keseluruhan, sumber konfigurasi proksi efektif, setiap error konfigurasi, dan setiap pemeriksaan tujuan. Kredensial URL proksi disensor dalam output teks dan JSON:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -165,6 +165,12 @@ Gunakan `--json` untuk otomasi. Output JSON berisi hasil keseluruhan, sumber con
|
||||
"url": "https://example.com/",
|
||||
"ok": true,
|
||||
"status": 200
|
||||
},
|
||||
{
|
||||
"kind": "apns",
|
||||
"url": "https://api.sandbox.push.apple.com",
|
||||
"ok": true,
|
||||
"status": 403
|
||||
}
|
||||
]
|
||||
}
|
||||
@ -178,9 +184,9 @@ curl -x http://127.0.0.1:3128 http://127.0.0.1/
|
||||
curl -x http://127.0.0.1:3128 http://169.254.169.254/
|
||||
```
|
||||
|
||||
Permintaan publik seharusnya berhasil. Permintaan loopback dan metadata seharusnya diblokir oleh proksi. Untuk `openclaw proxy validate`, canary loopback bawaan dapat membedakan penolakan proksi dari origin yang dapat dijangkau. Pemeriksaan `--denied-url` kustom tidak memiliki canary tersebut, jadi perlakukan respons HTTP dan kegagalan transport yang ambigu sebagai kegagalan validasi kecuali proksi Anda mengekspos sinyal penolakan khusus deployment yang dapat Anda verifikasi secara terpisah.
|
||||
Permintaan publik seharusnya berhasil. Permintaan loopback dan metadata seharusnya diblokir oleh proxy. Untuk `openclaw proxy validate`, canary loopback bawaan dapat membedakan penolakan proxy dari origin yang dapat dijangkau. Pemeriksaan `--denied-url` khusus tidak memiliki canary tersebut, jadi perlakukan baik respons HTTP maupun kegagalan transport yang ambigu sebagai kegagalan validasi kecuali proxy Anda mengekspos sinyal penolakan khusus penerapan yang dapat Anda verifikasi secara terpisah.
|
||||
|
||||
Lalu aktifkan perutean proksi OpenClaw:
|
||||
Lalu aktifkan perutean proxy OpenClaw:
|
||||
|
||||
```bash
|
||||
openclaw config set proxy.enabled true
|
||||
@ -188,7 +194,7 @@ openclaw config set proxy.proxyUrl http://127.0.0.1:3128
|
||||
openclaw gateway run
|
||||
```
|
||||
|
||||
atau tetapkan:
|
||||
atau atur:
|
||||
|
||||
```yaml
|
||||
proxy:
|
||||
@ -198,11 +204,11 @@ proxy:
|
||||
|
||||
## Batasan
|
||||
|
||||
- Proksi meningkatkan cakupan untuk klien HTTP dan WebSocket JavaScript lokal proses, tetapi bukan sandbox jaringan tingkat OS.
|
||||
- Socket `net`, `tls`, dan `http2` mentah, addon native, dan proses anak dapat melewati perutean proksi tingkat Node kecuali mereka mewarisi dan mematuhi variabel lingkungan proksi.
|
||||
- IRC adalah kanal TCP/TLS mentah di luar perutean proksi penerusan yang dikelola operator. Dalam deployment yang mewajibkan semua egress melalui proksi penerusan tersebut, tetapkan `channels.irc.enabled=false` kecuali egress IRC langsung disetujui secara eksplisit.
|
||||
- Proksi debug lokal adalah alat diagnostik dan penerusan upstream langsungnya untuk permintaan proksi serta tunnel CONNECT dinonaktifkan secara default saat mode proksi terkelola aktif; aktifkan penerusan langsung hanya untuk diagnostik lokal yang disetujui.
|
||||
- WebUI lokal pengguna dan server model lokal harus dimasukkan ke allowlist dalam kebijakan proksi operator bila diperlukan; OpenClaw tidak mengekspos bypass jaringan lokal umum untuk keduanya.
|
||||
- Bypass proksi bidang kontrol Gateway sengaja dibatasi pada URL `localhost` dan IP loopback literal. Gunakan `ws://127.0.0.1:18789`, `ws://[::1]:18789`, atau `ws://localhost:18789` untuk koneksi bidang kontrol Gateway langsung lokal; hostname lain dirutekan seperti lalu lintas berbasis hostname biasa.
|
||||
- OpenClaw tidak memeriksa, menguji, atau menyertifikasi kebijakan proksi Anda.
|
||||
- Perlakukan perubahan kebijakan proksi sebagai perubahan operasional yang sensitif terhadap keamanan.
|
||||
- Proxy meningkatkan cakupan untuk klien HTTP JavaScript dan WebSocket lokal proses, tetapi ini bukan sandbox jaringan tingkat OS.
|
||||
- Soket mentah `net`, `tls`, dan `http2`, addon native, serta proses anak dapat melewati perutean proxy tingkat Node kecuali mereka mewarisi dan mematuhi variabel lingkungan proxy.
|
||||
- IRC adalah kanal TCP/TLS mentah di luar perutean proxy maju yang dikelola operator. Dalam deployment yang mengharuskan semua egress melalui proxy maju tersebut, atur `channels.irc.enabled=false` kecuali egress IRC langsung disetujui secara eksplisit.
|
||||
- Proxy debug lokal adalah alat diagnostik dan penerusan upstream langsungnya untuk permintaan proxy dan tunnel CONNECT dinonaktifkan secara default saat mode proxy terkelola aktif; aktifkan penerusan langsung hanya untuk diagnostik lokal yang disetujui.
|
||||
- WebUI lokal pengguna dan server model lokal sebaiknya dimasukkan ke daftar izin dalam kebijakan proxy operator saat diperlukan; OpenClaw tidak mengekspos bypass jaringan lokal umum untuk keduanya.
|
||||
- Bypass proxy control-plane Gateway sengaja dibatasi ke URL `localhost` dan IP loopback literal. Gunakan `ws://127.0.0.1:18789`, `ws://[::1]:18789`, atau `ws://localhost:18789` untuk koneksi control-plane Gateway langsung lokal; nama host lain dirutekan seperti lalu lintas berbasis nama host biasa.
|
||||
- OpenClaw tidak memeriksa, menguji, atau mensertifikasi kebijakan proxy Anda.
|
||||
- Perlakukan perubahan kebijakan proxy sebagai perubahan operasional yang sensitif terhadap keamanan.
|
||||
|
||||
@ -1,143 +1,144 @@
|
||||
---
|
||||
read_when:
|
||||
- Menyesuaikan penguraian atau nilai bawaan direktif thinking, fast-mode, atau verbose
|
||||
- Menyesuaikan penguraian atau nilai bawaan direktif `thinking`, `fast-mode`, atau `verbose`
|
||||
summary: Sintaks direktif untuk /think, /fast, /verbose, /trace, dan visibilitas penalaran
|
||||
title: Tingkat berpikir
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T07:09:01Z"
|
||||
generated_at: "2026-05-04T18:24:29Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 6fa1b0a2b5f7b93a706488c3ad39dfe08c08eed0bdd30880eb4c07d730ee4d4f
|
||||
source_hash: fcd1cd76ca5d0b08656e0629df656ad8aa037201d8de68093b3e46eb0708f811
|
||||
source_path: tools/thinking.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
## Fungsinya
|
||||
## Apa yang dilakukan
|
||||
|
||||
- Arahan inline dalam body masuk apa pun: `/t <level>`, `/think:<level>`, atau `/thinking <level>`.
|
||||
- Arahan inline dalam isi masuk apa pun: `/t <level>`, `/think:<level>`, atau `/thinking <level>`.
|
||||
- Level (alias): `off | minimal | low | medium | high | xhigh | adaptive | max`
|
||||
- minimal → “think”
|
||||
- low → “think hard”
|
||||
- medium → “think harder”
|
||||
- high → “ultrathink” (anggaran maksimum)
|
||||
- minimal → “berpikir”
|
||||
- low → “berpikir keras”
|
||||
- medium → “berpikir lebih keras”
|
||||
- high → “ultrathink” (anggaran maks)
|
||||
- xhigh → “ultrathink+” (model GPT-5.2+ dan Codex, ditambah upaya Anthropic Claude Opus 4.7)
|
||||
- adaptive → pemikiran adaptif yang dikelola penyedia (didukung untuk Claude 4.6 di Anthropic/Bedrock, Anthropic Claude Opus 4.7, dan pemikiran dinamis Google Gemini)
|
||||
- max → penalaran maksimum penyedia (Anthropic Claude Opus 4.7; Ollama memetakannya ke upaya `think` native tertingginya)
|
||||
- max → penalaran maks penyedia (Anthropic Claude Opus 4.7; Ollama memetakan ini ke upaya native `think` tertingginya)
|
||||
- `x-high`, `x_high`, `extra-high`, `extra high`, dan `extra_high` dipetakan ke `xhigh`.
|
||||
- `highest` dipetakan ke `high`.
|
||||
- Catatan penyedia:
|
||||
- Menu dan pemilih pemikiran digerakkan oleh profil penyedia. Plugin penyedia mendeklarasikan set level persis untuk model yang dipilih, termasuk label seperti `on` biner.
|
||||
- `adaptive`, `xhigh`, dan `max` hanya diiklankan untuk profil penyedia/model yang mendukungnya. Arahan yang diketik untuk level yang tidak didukung ditolak dengan opsi valid model tersebut.
|
||||
- Level tersimpan yang sudah ada tetapi tidak didukung dipetakan ulang berdasarkan peringkat profil penyedia. `adaptive` kembali ke `medium` pada model non-adaptif, sementara `xhigh` dan `max` kembali ke level non-`off` terbesar yang didukung untuk model yang dipilih.
|
||||
- Menu dan pemilih pemikiran digerakkan oleh profil penyedia. Plugin penyedia mendeklarasikan set level persis untuk model yang dipilih, termasuk label seperti biner `on`.
|
||||
- `adaptive`, `xhigh`, dan `max` hanya ditampilkan untuk profil penyedia/model yang mendukungnya. Arahan yang diketik untuk level yang tidak didukung ditolak dengan opsi valid model tersebut.
|
||||
- Level tidak didukung yang tersimpan sebelumnya dipetakan ulang berdasarkan peringkat profil penyedia. `adaptive` kembali ke `medium` pada model non-adaptif, sedangkan `xhigh` dan `max` kembali ke level non-`off` terbesar yang didukung untuk model yang dipilih.
|
||||
- Model Anthropic Claude 4.6 default ke `adaptive` saat tidak ada level pemikiran eksplisit yang ditetapkan.
|
||||
- Anthropic Claude Opus 4.7 tidak default ke pemikiran adaptif. Default upaya API-nya tetap dimiliki penyedia kecuali Anda menetapkan level pemikiran secara eksplisit.
|
||||
- Anthropic Claude Opus 4.7 memetakan `/think xhigh` ke pemikiran adaptif plus `output_config.effort: "xhigh"`, karena `/think` adalah arahan pemikiran dan `xhigh` adalah pengaturan upaya Opus 4.7.
|
||||
- Anthropic Claude Opus 4.7 juga mengekspos `/think max`; ini dipetakan ke jalur upaya maksimum yang sama-sama dimiliki penyedia.
|
||||
- Model DeepSeek V4 mengekspos `/think xhigh|max`; keduanya dipetakan ke DeepSeek `reasoning_effort: "max"` sementara level non-`off` yang lebih rendah dipetakan ke `high`.
|
||||
- Model Ollama yang mampu berpikir mengekspos `/think low|medium|high|max`; `max` dipetakan ke `think: "high"` native karena API native Ollama menerima string upaya `low`, `medium`, dan `high`.
|
||||
- Model OpenAI GPT memetakan `/think` melalui dukungan upaya Responses API yang spesifik model. `/think off` mengirim `reasoning.effort: "none"` hanya saat model target mendukungnya; jika tidak, OpenClaw menghilangkan payload penalaran yang dinonaktifkan alih-alih mengirim nilai yang tidak didukung.
|
||||
- Entri katalog kompatibel OpenAI kustom dapat ikut mengaktifkan `/think xhigh` dengan mengatur `models.providers.<provider>.models[].compat.supportedReasoningEfforts` agar menyertakan `"xhigh"`. Ini menggunakan metadata kompatibilitas yang sama yang memetakan payload upaya penalaran OpenAI keluar, sehingga menu, validasi sesi, CLI agen, dan `llm-task` selaras dengan perilaku transport.
|
||||
- Ref OpenRouter Hunter Alpha yang dikonfigurasi tetapi kedaluwarsa melewati injeksi penalaran proxy karena rute yang sudah dihentikan itu dapat mengembalikan teks jawaban final melalui bidang penalaran.
|
||||
- Google Gemini memetakan `/think adaptive` ke pemikiran dinamis milik penyedia Gemini. Permintaan Gemini 3 menghilangkan `thinkingLevel` tetap, sementara permintaan Gemini 2.5 mengirim `thinkingBudget: -1`; level tetap tetap dipetakan ke `thinkingLevel` atau anggaran Gemini terdekat untuk keluarga model tersebut.
|
||||
- MiniMax (`minimax/*`) pada jalur streaming kompatibel Anthropic default ke `thinking: { type: "disabled" }` kecuali Anda secara eksplisit menetapkan pemikiran di parameter model atau parameter permintaan. Ini menghindari delta `reasoning_content` yang bocor dari format stream Anthropic non-native milik MiniMax.
|
||||
- Anthropic Claude Opus 4.7 tidak default ke pemikiran adaptif. Default upaya API-nya tetap dimiliki penyedia kecuali Anda secara eksplisit menetapkan level pemikiran.
|
||||
- Anthropic Claude Opus 4.7 memetakan `/think xhigh` ke pemikiran adaptif ditambah `output_config.effort: "xhigh"`, karena `/think` adalah arahan pemikiran dan `xhigh` adalah pengaturan upaya Opus 4.7.
|
||||
- Anthropic Claude Opus 4.7 juga mengekspos `/think max`; ini dipetakan ke jalur upaya maks yang sama milik penyedia.
|
||||
- Model DeepSeek V4 mengekspos `/think xhigh|max`; keduanya dipetakan ke DeepSeek `reasoning_effort: "max"` sedangkan level non-`off` yang lebih rendah dipetakan ke `high`.
|
||||
- Model Ollama yang mampu berpikir mengekspos `/think low|medium|high|max`; `max` dipetakan ke native `think: "high"` karena API native Ollama menerima string upaya `low`, `medium`, dan `high`.
|
||||
- Model OpenAI GPT memetakan `/think` melalui dukungan upaya Responses API khusus model. `/think off` mengirim `reasoning.effort: "none"` hanya saat model target mendukungnya; jika tidak, OpenClaw menghilangkan payload penalaran yang dinonaktifkan alih-alih mengirim nilai yang tidak didukung.
|
||||
- Entri katalog kustom yang kompatibel dengan OpenAI dapat ikut memakai `/think xhigh` dengan menetapkan `models.providers.<provider>.models[].compat.supportedReasoningEfforts` agar menyertakan `"xhigh"`. Ini menggunakan metadata kompat yang sama yang memetakan payload upaya penalaran OpenAI keluar, sehingga menu, validasi sesi, CLI agen, dan `llm-task` selaras dengan perilaku transport.
|
||||
- Ref OpenRouter Hunter Alpha terkonfigurasi yang usang melewati injeksi penalaran proxy karena rute yang sudah dihentikan itu dapat mengembalikan teks jawaban akhir melalui field penalaran.
|
||||
- Google Gemini memetakan `/think adaptive` ke pemikiran dinamis milik penyedia Gemini. Permintaan Gemini 3 menghilangkan `thinkingLevel` tetap, sedangkan permintaan Gemini 2.5 mengirim `thinkingBudget: -1`; level tetap tetap dipetakan ke `thinkingLevel` atau anggaran Gemini terdekat untuk keluarga model tersebut.
|
||||
- MiniMax (`minimax/*`) pada jalur streaming yang kompatibel dengan Anthropic default ke `thinking: { type: "disabled" }` kecuali Anda secara eksplisit menetapkan pemikiran di parameter model atau parameter permintaan. Ini menghindari delta `reasoning_content` yang bocor dari format stream Anthropic non-native milik MiniMax.
|
||||
- Z.AI (`zai/*`) hanya mendukung pemikiran biner (`on`/`off`). Level non-`off` apa pun diperlakukan sebagai `on` (dipetakan ke `low`).
|
||||
- Moonshot (`moonshot/*`) memetakan `/think off` ke `thinking: { type: "disabled" }` dan level non-`off` apa pun ke `thinking: { type: "enabled" }`. Saat pemikiran diaktifkan, Moonshot hanya menerima `tool_choice` `auto|none`; OpenClaw menormalkan nilai yang tidak kompatibel ke `auto`.
|
||||
- Moonshot (`moonshot/*`) memetakan `/think off` ke `thinking: { type: "disabled" }` dan level non-`off` apa pun ke `thinking: { type: "enabled" }`. Saat pemikiran diaktifkan, Moonshot hanya menerima `tool_choice` `auto|none`; OpenClaw menormalkan nilai yang tidak kompatibel menjadi `auto`.
|
||||
|
||||
## Urutan resolusi
|
||||
|
||||
1. Arahan inline pada pesan (berlaku hanya untuk pesan tersebut).
|
||||
1. Arahan inline pada pesan (berlaku hanya untuk pesan itu).
|
||||
2. Override sesi (ditetapkan dengan mengirim pesan yang hanya berisi arahan).
|
||||
3. Default per agen (`agents.list[].thinkingDefault` dalam config).
|
||||
4. Default global (`agents.defaults.thinkingDefault` dalam config).
|
||||
5. Fallback: default yang dideklarasikan penyedia saat tersedia; jika tidak, model yang mampu bernalar diresolusikan ke `medium` atau level non-`off` terdekat yang didukung untuk model tersebut, dan model yang tidak bernalar tetap `off`.
|
||||
3. Default per agen (`agents.list[].thinkingDefault` dalam konfigurasi).
|
||||
4. Default global (`agents.defaults.thinkingDefault` dalam konfigurasi).
|
||||
5. Fallback: default yang dideklarasikan penyedia saat tersedia; jika tidak, model yang mampu bernalar diselesaikan ke `medium` atau level non-`off` terdekat yang didukung untuk model tersebut, dan model non-penalaran tetap `off`.
|
||||
|
||||
## Menetapkan default sesi
|
||||
|
||||
- Kirim pesan yang **hanya** berisi arahan (spasi kosong diperbolehkan), misalnya `/think:medium` atau `/t high`.
|
||||
- Itu berlaku untuk sesi saat ini (default per pengirim); dibersihkan oleh `/think:off` atau reset idle sesi.
|
||||
- Itu berlaku untuk sesi saat ini (default per pengirim); dihapus oleh `/think:off` atau reset sesi menganggur.
|
||||
- Balasan konfirmasi dikirim (`Thinking level set to high.` / `Thinking disabled.`). Jika level tidak valid (misalnya `/thinking big`), perintah ditolak dengan petunjuk dan status sesi dibiarkan tidak berubah.
|
||||
- Kirim `/think` (atau `/think:`) tanpa argumen untuk melihat level pemikiran saat ini.
|
||||
|
||||
## Penerapan berdasarkan agen
|
||||
|
||||
- **Pi Tersemat**: level yang diresolusikan diteruskan ke runtime agen Pi dalam proses.
|
||||
- **Pi tertanam**: level yang diselesaikan diteruskan ke runtime agen Pi dalam proses.
|
||||
- **Backend Claude CLI**: level non-off diteruskan ke Claude Code sebagai `--effort` saat menggunakan `claude-cli`; lihat [Backend CLI](/id/gateway/cli-backends).
|
||||
|
||||
## Mode cepat (/fast)
|
||||
|
||||
- Level: `on|off`.
|
||||
- Pesan yang hanya berisi arahan mengalihkan override mode cepat sesi dan membalas `Fast mode enabled.` / `Fast mode disabled.`.
|
||||
- Pesan yang hanya berisi arahan mengaktifkan/menonaktifkan override mode cepat sesi dan membalas `Fast mode enabled.` / `Fast mode disabled.`.
|
||||
- Kirim `/fast` (atau `/fast status`) tanpa mode untuk melihat status mode cepat efektif saat ini.
|
||||
- OpenClaw meresolusikan mode cepat dalam urutan ini:
|
||||
1. Inline/hanya arahan `/fast on|off`
|
||||
- OpenClaw menyelesaikan mode cepat dalam urutan ini:
|
||||
1. Inline/hanya-arahan `/fast on|off`
|
||||
2. Override sesi
|
||||
3. Default per agen (`agents.list[].fastModeDefault`)
|
||||
4. Config per model: `agents.defaults.models["<provider>/<model>"].params.fastMode`
|
||||
4. Konfigurasi per model: `agents.defaults.models["<provider>/<model>"].params.fastMode`
|
||||
5. Fallback: `off`
|
||||
- Untuk `openai/*`, mode cepat dipetakan ke pemrosesan prioritas OpenAI dengan mengirim `service_tier=priority` pada permintaan Responses yang didukung.
|
||||
- Untuk `openai-codex/*`, mode cepat mengirim flag `service_tier=priority` yang sama pada Codex Responses. OpenClaw mempertahankan satu toggle `/fast` bersama di kedua jalur autentikasi.
|
||||
- Untuk permintaan publik langsung `anthropic/*`, termasuk lalu lintas terautentikasi OAuth yang dikirim ke `api.anthropic.com`, mode cepat dipetakan ke tingkat layanan Anthropic: `/fast on` mengatur `service_tier=auto`, `/fast off` mengatur `service_tier=standard_only`.
|
||||
- Untuk `minimax/*` pada jalur kompatibel Anthropic, `/fast on` (atau `params.fastMode: true`) menulis ulang `MiniMax-M2.7` menjadi `MiniMax-M2.7-highspeed`.
|
||||
- Parameter model Anthropic `serviceTier` / `service_tier` eksplisit mengesampingkan default mode cepat saat keduanya ditetapkan. OpenClaw tetap melewati injeksi tingkat layanan Anthropic untuk URL dasar proxy non-Anthropic.
|
||||
- Untuk permintaan publik langsung `anthropic/*`, termasuk lalu lintas terautentikasi OAuth yang dikirim ke `api.anthropic.com`, mode cepat dipetakan ke tingkat layanan Anthropic: `/fast on` menetapkan `service_tier=auto`, `/fast off` menetapkan `service_tier=standard_only`.
|
||||
- Untuk `minimax/*` pada jalur yang kompatibel dengan Anthropic, `/fast on` (atau `params.fastMode: true`) menulis ulang `MiniMax-M2.7` menjadi `MiniMax-M2.7-highspeed`.
|
||||
- Parameter model Anthropic `serviceTier` / `service_tier` eksplisit meng-override default mode cepat saat keduanya ditetapkan. OpenClaw tetap melewati injeksi tingkat layanan Anthropic untuk URL dasar proxy non-Anthropic.
|
||||
- `/status` menampilkan `Fast` hanya saat mode cepat diaktifkan.
|
||||
|
||||
## Arahan verbose (/verbose atau /v)
|
||||
|
||||
- Level: `on` (minimal) | `full` | `off` (default).
|
||||
- Pesan yang hanya berisi arahan mengalihkan verbose sesi dan membalas `Verbose logging enabled.` / `Verbose logging disabled.`; level tidak valid mengembalikan petunjuk tanpa mengubah status.
|
||||
- `/verbose off` menyimpan override sesi eksplisit; bersihkan melalui UI Sessions dengan memilih `inherit`.
|
||||
- Arahan inline hanya memengaruhi pesan tersebut; default sesi/global berlaku jika tidak.
|
||||
- Pesan yang hanya berisi arahan mengaktifkan/menonaktifkan verbose sesi dan membalas `Verbose logging enabled.` / `Verbose logging disabled.`; level tidak valid mengembalikan petunjuk tanpa mengubah status.
|
||||
- `/verbose off` menyimpan override sesi eksplisit; hapus melalui UI Sesi dengan memilih `inherit`.
|
||||
- Arahan inline hanya memengaruhi pesan itu; default sesi/global berlaku selain itu.
|
||||
- Kirim `/verbose` (atau `/verbose:`) tanpa argumen untuk melihat level verbose saat ini.
|
||||
- Saat verbose aktif, agen yang memancarkan hasil alat terstruktur (Pi, agen JSON lain) mengirim setiap panggilan alat kembali sebagai pesan metadata-saja sendiri, diawali dengan `<emoji> <tool-name>: <arg>` saat tersedia. Ringkasan alat ini dikirim segera saat tiap alat dimulai (bubble terpisah), bukan sebagai delta streaming.
|
||||
- Ringkasan kegagalan alat tetap terlihat dalam mode normal, tetapi sufiks detail error mentah disembunyikan kecuali verbose adalah `on` atau `full`.
|
||||
- Saat verbose adalah `full`, output alat juga diteruskan setelah selesai (bubble terpisah, dipotong hingga panjang aman). Jika Anda mengalihkan `/verbose on|full|off` saat run sedang berjalan, bubble alat berikutnya mengikuti pengaturan baru.
|
||||
- `agents.defaults.toolProgressDetail` mengontrol bentuk ringkasan alat `/verbose` dan baris alat draf progres. Gunakan `"explain"` (default) untuk label manusia ringkas seperti `🛠️ Exec: checking JS syntax`; gunakan `"raw"` saat Anda juga ingin perintah/detail mentah ditambahkan untuk debugging. `agents.list[].toolProgressDetail` per agen mengesampingkan default.
|
||||
- Saat verbose aktif, agen yang memancarkan hasil alat terstruktur (Pi, agen JSON lain) mengirim setiap panggilan alat kembali sebagai pesan metadata-saja miliknya sendiri, diawali dengan `<emoji> <tool-name>: <arg>` saat tersedia. Ringkasan alat ini dikirim segera saat setiap alat dimulai (bubble terpisah), bukan sebagai delta streaming.
|
||||
- Ringkasan kegagalan alat tetap terlihat dalam mode normal, tetapi sufiks detail kesalahan mentah disembunyikan kecuali verbose adalah `on` atau `full`.
|
||||
- Saat verbose adalah `full`, output alat juga diteruskan setelah selesai (bubble terpisah, dipotong ke panjang aman). Jika Anda mengalihkan `/verbose on|full|off` saat run sedang berjalan, bubble alat berikutnya mengikuti pengaturan baru.
|
||||
- `agents.defaults.toolProgressDetail` mengontrol bentuk ringkasan alat `/verbose` dan baris alat draft progres. Gunakan `"explain"` (default) untuk label manusia ringkas seperti `🛠️ Exec: checking JS syntax`; gunakan `"raw"` saat Anda juga menginginkan perintah/detail mentah ditambahkan untuk debugging. `agents.list[].toolProgressDetail` per agen meng-override default.
|
||||
- `explain`: `🛠️ Exec: check JS syntax for /tmp/app.js`
|
||||
- `raw`: `🛠️ Exec: check JS syntax for /tmp/app.js, node --check /tmp/app.js`
|
||||
|
||||
## Arahan trace Plugin (/trace)
|
||||
|
||||
- Level: `on` | `off` (default).
|
||||
- Pesan yang hanya berisi arahan mengalihkan output trace Plugin sesi dan membalas `Plugin trace enabled.` / `Plugin trace disabled.`.
|
||||
- Arahan inline hanya memengaruhi pesan tersebut; default sesi/global berlaku jika tidak.
|
||||
- Pesan yang hanya berisi arahan mengaktifkan/menonaktifkan output trace Plugin sesi dan membalas `Plugin trace enabled.` / `Plugin trace disabled.`.
|
||||
- Arahan inline hanya memengaruhi pesan itu; default sesi/global berlaku selain itu.
|
||||
- Kirim `/trace` (atau `/trace:`) tanpa argumen untuk melihat level trace saat ini.
|
||||
- `/trace` lebih sempit daripada `/verbose`: ini hanya mengekspos baris trace/debug milik plugin seperti ringkasan debug Active Memory.
|
||||
- `/trace` lebih sempit daripada `/verbose`: ini hanya mengekspos baris trace/debug milik Plugin seperti ringkasan debug Active Memory.
|
||||
- Baris trace dapat muncul di `/status` dan sebagai pesan diagnostik lanjutan setelah balasan asisten normal.
|
||||
|
||||
## Visibilitas penalaran (/reasoning)
|
||||
|
||||
- Level: `on|off|stream`.
|
||||
- Pesan yang hanya berisi arahan mengalihkan apakah blok pemikiran ditampilkan dalam balasan.
|
||||
- Saat diaktifkan, penalaran dikirim sebagai **pesan terpisah** dengan awalan `Reasoning:`.
|
||||
- `stream` (khusus Telegram): men-stream penalaran ke bubble draf Telegram saat balasan sedang dibuat, lalu mengirim jawaban final tanpa penalaran.
|
||||
- Pesan yang hanya berisi arahan mengaktifkan/menonaktifkan apakah blok pemikiran ditampilkan dalam balasan.
|
||||
- Saat diaktifkan, penalaran dikirim sebagai **pesan terpisah** dengan prefiks `Reasoning:`.
|
||||
- `stream` (khusus Telegram): mengalirkan penalaran ke bubble draft Telegram saat balasan sedang dibuat, lalu mengirim jawaban akhir tanpa penalaran.
|
||||
- Alias: `/reason`.
|
||||
- Kirim `/reasoning` (atau `/reasoning:`) tanpa argumen untuk melihat level penalaran saat ini.
|
||||
- Urutan resolusi: arahan inline, lalu override sesi, lalu default per agen (`agents.list[].reasoningDefault`), lalu fallback (`off`).
|
||||
|
||||
Tag penalaran model lokal yang cacat ditangani secara konservatif. Blok `<think>...</think>` yang tertutup tetap disembunyikan pada balasan normal, dan penalaran yang tidak tertutup setelah teks yang sudah terlihat juga disembunyikan. Jika balasan sepenuhnya dibungkus dalam satu tag pembuka yang tidak tertutup dan jika tidak akan dikirim sebagai teks kosong, OpenClaw menghapus tag pembuka yang cacat dan mengirim teks sisanya.
|
||||
Tag penalaran model lokal yang salah bentuk ditangani secara konservatif. Blok `<think>...</think>` tertutup tetap tersembunyi pada balasan normal, dan penalaran yang tidak tertutup setelah teks yang sudah terlihat juga disembunyikan. Jika balasan sepenuhnya dibungkus dalam satu tag pembuka yang tidak tertutup dan jika tidak akan dikirim sebagai teks kosong, OpenClaw menghapus tag pembuka yang salah bentuk dan mengirim teks yang tersisa.
|
||||
|
||||
## Terkait
|
||||
|
||||
- Dokumentasi mode elevated ada di [Mode elevated](/id/tools/elevated).
|
||||
- Dokumentasi mode tinggi tersedia di [Mode tinggi](/id/tools/elevated).
|
||||
|
||||
## Heartbeat
|
||||
|
||||
- Body probe Heartbeat adalah prompt Heartbeat yang dikonfigurasi (default: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Arahan inline dalam pesan Heartbeat berlaku seperti biasa (tetapi hindari mengubah default sesi dari Heartbeat).
|
||||
- Pengiriman Heartbeat default hanya ke payload final. Untuk juga mengirim pesan `Reasoning:` terpisah (saat tersedia), tetapkan `agents.defaults.heartbeat.includeReasoning: true` atau per agen `agents.list[].heartbeat.includeReasoning: true`.
|
||||
- Isi probe Heartbeat adalah prompt heartbeat yang dikonfigurasi (default: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Arahan inline dalam pesan heartbeat berlaku seperti biasa (tetapi hindari mengubah default sesi dari heartbeat).
|
||||
- Pengiriman Heartbeat default hanya ke payload akhir. Untuk juga mengirim pesan `Reasoning:` terpisah (saat tersedia), tetapkan `agents.defaults.heartbeat.includeReasoning: true` atau per agen `agents.list[].heartbeat.includeReasoning: true`.
|
||||
|
||||
## UI chat web
|
||||
|
||||
- Pemilih pemikiran chat web mencerminkan level tersimpan sesi dari penyimpanan/config sesi masuk saat halaman dimuat.
|
||||
- Memilih level lain segera menulis override sesi melalui `sessions.patch`; itu tidak menunggu pengiriman berikutnya dan bukan override sekali pakai `thinkingOnce`.
|
||||
- Opsi pertama selalu `Default (<resolved level>)`, tempat default yang diresolusikan berasal dari profil pemikiran penyedia model sesi aktif plus logika fallback yang sama yang digunakan `/status` dan `session_status`.
|
||||
- Pemilih menggunakan `thinkingLevels` yang dikembalikan oleh baris/default sesi Gateway, dengan `thinkingOptions` dipertahankan sebagai daftar label lama. UI browser tidak mempertahankan daftar regex penyedia sendiri; plugin memiliki set level spesifik model.
|
||||
- Pemilih pemikiran chat web mencerminkan level tersimpan sesi dari penyimpanan/konfigurasi sesi masuk saat halaman dimuat.
|
||||
- Memilih level lain langsung menulis override sesi melalui `sessions.patch`; ini tidak menunggu pengiriman berikutnya dan bukan override sekali pakai `thinkingOnce`.
|
||||
- Opsi pertama selalu `Default (<resolved level>)`, dengan default terselesaikan berasal dari profil pemikiran penyedia model sesi aktif ditambah logika fallback yang sama yang digunakan `/status` dan `session_status`.
|
||||
- Pemilih menggunakan `thinkingLevels` yang dikembalikan oleh baris/default sesi Gateway, dengan `thinkingOptions` dipertahankan sebagai daftar label lama. UI browser tidak menyimpan daftar regex penyedianya sendiri; Plugin memiliki set level khusus model.
|
||||
- `/think:<level>` tetap berfungsi dan memperbarui level sesi tersimpan yang sama, sehingga arahan chat dan pemilih tetap sinkron.
|
||||
|
||||
## Profil penyedia
|
||||
|
||||
- Plugin penyedia dapat mengekspos `resolveThinkingProfile(ctx)` untuk menentukan level yang didukung model dan default-nya.
|
||||
- Plugin penyedia yang mem-proxy model Claude sebaiknya menggunakan kembali `resolveClaudeThinkingProfile(modelId)` dari `openclaw/plugin-sdk/provider-model-shared` agar katalog Anthropic langsung dan proxy tetap selaras.
|
||||
- Setiap level profil memiliki `id` kanonis tersimpan (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `adaptive`, atau `max`) dan dapat menyertakan `label` tampilan. Penyedia biner menggunakan `{ id: "low", label: "on" }`.
|
||||
- Plugin alat yang perlu memvalidasi override penalaran eksplisit sebaiknya menggunakan `api.runtime.agent.resolveThinkingPolicy({ provider, model })` plus `api.runtime.agent.normalizeThinkingLevel(...)`; mereka tidak boleh menyimpan daftar level penyedia/model sendiri.
|
||||
- Plugin alat yang memiliki akses ke metadata model kustom yang dikonfigurasi dapat meneruskan `catalog` ke `resolveThinkingPolicy` sehingga opt-in `compat.supportedReasoningEfforts` tercermin dalam validasi di sisi Plugin.
|
||||
- Hook lama yang dipublikasikan (`supportsXHighThinking`, `isBinaryThinking`, dan `resolveDefaultThinkingLevel`) tetap tersedia sebagai adaptor kompatibilitas, tetapi kumpulan level kustom baru sebaiknya menggunakan `resolveThinkingProfile`.
|
||||
- Baris/default Gateway mengekspos `thinkingLevels`, `thinkingOptions`, dan `thinkingDefault` sehingga klien ACP/chat merender id dan label profil yang sama dengan yang digunakan validasi runtime.
|
||||
- Plugin penyedia dapat mengekspos `resolveThinkingProfile(ctx)` untuk mendefinisikan tingkat yang didukung model dan bawaannya.
|
||||
- Plugin penyedia yang memproksikan model Claude sebaiknya menggunakan kembali `resolveClaudeThinkingProfile(modelId)` dari `openclaw/plugin-sdk/provider-model-shared` agar katalog Anthropic langsung dan proksi tetap selaras.
|
||||
- Setiap tingkat profil memiliki `id` kanonis yang disimpan (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `adaptive`, atau `max`) dan dapat menyertakan `label` tampilan. Penyedia biner menggunakan `{ id: "low", label: "on" }`.
|
||||
- Plugin alat yang perlu memvalidasi penggantian berpikir eksplisit sebaiknya menggunakan `api.runtime.agent.resolveThinkingPolicy({ provider, model })` plus `api.runtime.agent.normalizeThinkingLevel(...)`; mereka tidak sebaiknya menyimpan daftar tingkat penyedia/model sendiri.
|
||||
- Plugin alat dengan akses ke metadata model kustom yang dikonfigurasi dapat meneruskan `catalog` ke `resolveThinkingPolicy` agar opt-in `compat.supportedReasoningEfforts` tercermin dalam validasi sisi Plugin.
|
||||
- Hook lama yang dipublikasikan (`supportsXHighThinking`, `isBinaryThinking`, dan `resolveDefaultThinkingLevel`) tetap ada sebagai adaptor kompatibilitas, tetapi set tingkat kustom baru sebaiknya menggunakan `resolveThinkingProfile`.
|
||||
- Baris/bawaan Gateway mengekspos `thinkingLevels`, `thinkingOptions`, dan `thinkingDefault` agar klien ACP/chat merender id dan label profil yang sama dengan yang digunakan validasi runtime.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user