chore(i18n): refresh id translations

This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-19 01:13:20 +00:00
parent 4912df5898
commit 4cbaec79df
10 changed files with 1262 additions and 1054 deletions

View File

@ -1,57 +1,57 @@
---
read_when:
- Anda ingin memilih chat channel untuk OpenClaw
- Anda memerlukan ikhtisar singkat tentang platform perpesanan yang didukung
summary: Platform perpesanan yang dapat dihubungkan dengan OpenClaw
title: Chat Channels
- Anda ingin memilih saluran chat untuk OpenClaw
- Anda memerlukan gambaran singkat tentang platform perpesanan yang didukung
summary: Platform perpesanan yang dapat dihubungkan oleh OpenClaw
title: Saluran Chat
x-i18n:
generated_at: "2026-04-05T13:43:03Z"
generated_at: "2026-04-19T01:11:10Z"
model: gpt-5.4
provider: openai
source_hash: 246ee6f16aebe751241f00102bb435978ed21f6158385aff5d8e222e30567416
source_hash: d41c3a37d91c07f15afd8e199a289297772331c70e38697346a373595eb2d993
source_path: channels/index.md
workflow: 15
---
# Chat Channels
# Saluran Chat
OpenClaw dapat berbicara dengan Anda di aplikasi chat apa pun yang sudah Anda gunakan. Setiap channel terhubung melalui Gateway.
Teks didukung di semua tempat; media dan reaksi berbeda-beda menurut channel.
OpenClaw dapat berbicara dengan Anda di aplikasi chat apa pun yang sudah Anda gunakan. Setiap saluran terhubung melalui Gateway.
Teks didukung di semua tempat; media dan reaksi berbeda-beda tergantung salurannya.
## Channel yang didukung
## Saluran yang didukung
- [BlueBubbles](/channels/bluebubbles) — **Direkomendasikan untuk iMessage**; menggunakan REST API server macOS BlueBubbles dengan dukungan fitur penuh (plugin bawaan; edit, unsend, efek, reaksi, manajemen grup — edit saat ini rusak di macOS 26 Tahoe).
- [Discord](/channels/discord) — Discord Bot API + Gateway; mendukung server, channel, dan DM.
- [Feishu](/channels/feishu) — Bot Feishu/Lark melalui WebSocket (plugin bawaan).
- [Google Chat](/channels/googlechat) — Aplikasi Google Chat API melalui webhook HTTP.
- [iMessage (lama)](/channels/imessage) — Integrasi macOS lama melalui CLI imsg (tidak digunakan lagi, gunakan BlueBubbles untuk penyiapan baru).
- [IRC](/channels/irc) — Server IRC klasik; channel + DM dengan kontrol pairing/allowlist.
- [LINE](/channels/line) — Bot LINE Messaging API (plugin bawaan).
- [Matrix](/channels/matrix) — Protokol Matrix (plugin bawaan).
- [Mattermost](/channels/mattermost) — Bot API + WebSocket; channel, grup, DM (plugin bawaan).
- [Microsoft Teams](/channels/msteams) — Bot Framework; dukungan enterprise (plugin bawaan).
- [Nextcloud Talk](/channels/nextcloud-talk) — Chat self-hosted melalui Nextcloud Talk (plugin bawaan).
- [Nostr](/channels/nostr) — DM terdesentralisasi melalui NIP-04 (plugin bawaan).
- [QQ Bot](/channels/qqbot) — QQ Bot API; chat privat, chat grup, dan media kaya (plugin bawaan).
- [Signal](/channels/signal) — signal-cli; berfokus pada privasi.
- [Slack](/channels/slack) — Bolt SDK; aplikasi workspace.
- [Synology Chat](/channels/synology-chat) — Chat Synology NAS melalui webhook keluar+masuk (plugin bawaan).
- [Telegram](/channels/telegram) — Bot API melalui grammY; mendukung grup.
- [Tlon](/channels/tlon) — Messenger berbasis Urbit (plugin bawaan).
- [Twitch](/channels/twitch) — Chat Twitch melalui koneksi IRC (plugin bawaan).
- [Voice Call](/plugins/voice-call) — Telepon melalui Plivo atau Twilio (plugin, dipasang secara terpisah).
- [BlueBubbles](/id/channels/bluebubbles) — **Direkomendasikan untuk iMessage**; menggunakan REST API server BlueBubbles di macOS dengan dukungan fitur penuh (Plugin bawaan; edit, batal kirim, efek, reaksi, manajemen grup — edit saat ini rusak di macOS 26 Tahoe).
- [Discord](/id/channels/discord) — Discord Bot API + Gateway; mendukung server, saluran, dan DM.
- [Feishu](/id/channels/feishu) — bot Feishu/Lark melalui WebSocket (Plugin bawaan).
- [Google Chat](/id/channels/googlechat) — aplikasi Google Chat API melalui Webhook HTTP.
- [iMessage (legacy)](/id/channels/imessage) — integrasi macOS lama melalui CLI imsg (sudah usang, gunakan BlueBubbles untuk penyiapan baru).
- [IRC](/id/channels/irc) — server IRC klasik; saluran + DM dengan kontrol pairing/allowlist.
- [LINE](/id/channels/line) — bot LINE Messaging API (Plugin bawaan).
- [Matrix](/id/channels/matrix) — protokol Matrix (Plugin bawaan).
- [Mattermost](/id/channels/mattermost) — Bot API + WebSocket; saluran, grup, DM (Plugin bawaan).
- [Microsoft Teams](/id/channels/msteams) — Bot Framework; dukungan enterprise (Plugin bawaan).
- [Nextcloud Talk](/id/channels/nextcloud-talk) — chat yang di-host sendiri melalui Nextcloud Talk (Plugin bawaan).
- [Nostr](/id/channels/nostr) — DM terdesentralisasi melalui NIP-04 (Plugin bawaan).
- [QQ Bot](/id/channels/qqbot) — QQ Bot API; chat pribadi, chat grup, dan media kaya (Plugin bawaan).
- [Signal](/id/channels/signal) — signal-cli; berfokus pada privasi.
- [Slack](/id/channels/slack) — Bolt SDK; aplikasi workspace.
- [Synology Chat](/id/channels/synology-chat) — Synology NAS Chat melalui Webhook keluar+masuk (Plugin bawaan).
- [Telegram](/id/channels/telegram) — Bot API melalui grammY; mendukung grup.
- [Tlon](/id/channels/tlon) — messenger berbasis Urbit (Plugin bawaan).
- [Twitch](/id/channels/twitch) — chat Twitch melalui koneksi IRC (Plugin bawaan).
- [Voice Call](/id/plugins/voice-call) — telepon melalui Plivo atau Twilio (plugin, dipasang terpisah).
- [WebChat](/web/webchat) — UI Gateway WebChat melalui WebSocket.
- [WeChat](https://www.npmjs.com/package/@tencent-weixin/openclaw-weixin) — Plugin Tencent iLink Bot melalui login QR; hanya chat privat.
- [WhatsApp](/channels/whatsapp) — Paling populer; menggunakan Baileys dan memerlukan pairing QR.
- [Zalo](/channels/zalo) — Zalo Bot API; messenger populer di Vietnam (plugin bawaan).
- [Zalo Personal](/channels/zalouser) — Akun pribadi Zalo melalui login QR (plugin bawaan).
- [WeChat](/id/channels/wechat) — Plugin Tencent iLink Bot melalui login QR; hanya chat pribadi (plugin eksternal).
- [WhatsApp](/id/channels/whatsapp) — Paling populer; menggunakan Baileys dan memerlukan pairing QR.
- [Zalo](/id/channels/zalo) — Zalo Bot API; messenger populer di Vietnam (Plugin bawaan).
- [Zalo Personal](/id/channels/zalouser) — akun pribadi Zalo melalui login QR (Plugin bawaan).
## Catatan
- Channel dapat berjalan secara bersamaan; konfigurasikan beberapa channel dan OpenClaw akan melakukan routing per chat.
- Saluran dapat berjalan secara bersamaan; konfigurasikan beberapa saluran dan OpenClaw akan melakukan routing per chat.
- Penyiapan tercepat biasanya **Telegram** (token bot sederhana). WhatsApp memerlukan pairing QR dan
menyimpan lebih banyak status di disk.
- Perilaku grup berbeda-beda menurut channel; lihat [Groups](/channels/groups).
- Pairing DM dan allowlist diterapkan demi keamanan; lihat [Security](/gateway/security).
- Pemecahan masalah: [Pemecahan masalah channel](/channels/troubleshooting).
- Provider model didokumentasikan secara terpisah; lihat [Model Providers](/providers/models).
- Perilaku grup berbeda-beda tergantung saluran; lihat [Groups](/id/channels/groups).
- Pairing DM dan allowlist diterapkan untuk keamanan; lihat [Security](/id/gateway/security).
- Pemecahan masalah: [Pemecahan masalah saluran](/id/channels/troubleshooting).
- Penyedia model didokumentasikan secara terpisah; lihat [Model Providers](/id/providers/models).

175
docs/id/channels/wechat.md Normal file
View File

@ -0,0 +1,175 @@
---
read_when:
- Anda ingin menghubungkan OpenClaw ke WeChat atau Weixin
- Anda sedang memasang atau memecahkan masalah Plugin channel `openclaw-weixin`
- Anda perlu memahami bagaimana Plugin channel eksternal berjalan di samping Gateway
summary: Penyiapan channel WeChat melalui Plugin `openclaw-weixin` eksternal
title: WeChat
x-i18n:
generated_at: "2026-04-19T01:11:12Z"
model: gpt-5.4
provider: openai
source_hash: ae669f2b6300e0c2b1d1dc57743a0a2ab0c05b9e277ec2ac640a03e6e7ab3b84
source_path: channels/wechat.md
workflow: 15
---
# WeChat
OpenClaw terhubung ke WeChat melalui Plugin channel eksternal milik Tencent,
`@tencent-weixin/openclaw-weixin`.
Status: Plugin eksternal. Chat langsung dan media didukung. Chat grup tidak
diiklankan oleh metadata kapabilitas Plugin saat ini.
## Penamaan
- **WeChat** adalah nama yang digunakan untuk pengguna dalam dokumentasi ini.
- **Weixin** adalah nama yang digunakan oleh paket Tencent dan oleh id Plugin.
- `openclaw-weixin` adalah id channel OpenClaw.
- `@tencent-weixin/openclaw-weixin` adalah paket npm.
Gunakan `openclaw-weixin` dalam perintah CLI dan path konfigurasi.
## Cara kerjanya
Kode WeChat tidak berada di repo inti OpenClaw. OpenClaw menyediakan kontrak
Plugin channel generik, dan Plugin eksternal menyediakan runtime khusus
WeChat:
1. `openclaw plugins install` memasang `@tencent-weixin/openclaw-weixin`.
2. Gateway menemukan manifes Plugin dan memuat entrypoint Plugin.
3. Plugin mendaftarkan id channel `openclaw-weixin`.
4. `openclaw channels login --channel openclaw-weixin` memulai login QR.
5. Plugin menyimpan kredensial akun di bawah direktori state OpenClaw.
6. Saat Gateway dimulai, Plugin memulai monitor Weixin untuk setiap
akun yang dikonfigurasi.
7. Pesan WeChat masuk dinormalisasi melalui kontrak channel, dirutekan ke
agent OpenClaw yang dipilih, lalu dikirim kembali melalui jalur keluar Plugin.
Pemisahan itu penting: inti OpenClaw harus tetap channel-agnostik. Login WeChat,
panggilan API Tencent iLink, unggah/unduh media, token konteks, dan
pemantauan akun dimiliki oleh Plugin eksternal.
## Pemasangan
Pemasangan cepat:
```bash
npx -y @tencent-weixin/openclaw-weixin-cli install
```
Pemasangan manual:
```bash
openclaw plugins install "@tencent-weixin/openclaw-weixin"
openclaw config set plugins.entries.openclaw-weixin.enabled true
```
Mulai ulang Gateway setelah pemasangan:
```bash
openclaw gateway restart
```
## Login
Jalankan login QR di mesin yang sama yang menjalankan Gateway:
```bash
openclaw channels login --channel openclaw-weixin
```
Pindai kode QR dengan WeChat di ponsel Anda dan konfirmasikan login. Plugin
menyimpan token akun secara lokal setelah pemindaian berhasil.
Untuk menambahkan akun WeChat lain, jalankan lagi perintah login yang sama. Untuk
banyak akun, isolasikan sesi pesan langsung berdasarkan akun, channel, dan pengirim:
```bash
openclaw config set session.dmScope per-account-channel-peer
```
## Kontrol akses
Pesan langsung menggunakan model pairing dan allowlist OpenClaw normal untuk
Plugin channel.
Setujui pengirim baru:
```bash
openclaw pairing list openclaw-weixin
openclaw pairing approve openclaw-weixin <CODE>
```
Untuk model kontrol akses lengkap, lihat [Pairing](/id/channels/pairing).
## Kompatibilitas
Plugin memeriksa versi host OpenClaw saat startup.
| Baris Plugin | Versi OpenClaw | Tag npm |
| ------------ | ---------------------- | -------- |
| `2.x` | `>=2026.3.22` | `latest` |
| `1.x` | `>=2026.1.0 <2026.3.22` | `legacy` |
Jika Plugin melaporkan bahwa versi OpenClaw Anda terlalu lama, perbarui
OpenClaw atau pasang baris Plugin legacy:
```bash
openclaw plugins install @tencent-weixin/openclaw-weixin@legacy
```
## Proses sidecar
Plugin WeChat dapat menjalankan pekerjaan pembantu di samping Gateway saat
memantau API Tencent iLink. Pada issue #68451, jalur pembantu itu memunculkan bug dalam
pembersihan Gateway usang generik OpenClaw: proses anak dapat mencoba membersihkan proses
Gateway induk, sehingga menyebabkan loop restart di bawah pengelola proses seperti systemd.
Pembersihan startup OpenClaw saat ini mengecualikan proses saat ini dan leluhurnya,
jadi pembantu channel tidak boleh mematikan Gateway yang meluncurkannya. Perbaikan ini
bersifat generik; ini bukan jalur khusus WeChat di inti.
## Pemecahan masalah
Periksa pemasangan dan status:
```bash
openclaw plugins list
openclaw channels status --probe
openclaw --version
```
Jika channel ditampilkan sebagai terpasang tetapi tidak terhubung, pastikan Plugin
diaktifkan lalu mulai ulang:
```bash
openclaw config set plugins.entries.openclaw-weixin.enabled true
openclaw gateway restart
```
Jika Gateway berulang kali dimulai ulang setelah mengaktifkan WeChat, perbarui OpenClaw dan
Plugin:
```bash
npm view @tencent-weixin/openclaw-weixin version
openclaw plugins install "@tencent-weixin/openclaw-weixin" --force
openclaw gateway restart
```
Nonaktifkan sementara:
```bash
openclaw config set plugins.entries.openclaw-weixin.enabled false
openclaw gateway restart
```
## Dokumentasi terkait
- Ikhtisar channel: [Chat Channels](/id/channels)
- Pairing: [Pairing](/id/channels/pairing)
- Perutean channel: [Channel Routing](/id/channels/channel-routing)
- Arsitektur Plugin: [Plugin Architecture](/id/plugins/architecture)
- SDK Plugin channel: [Channel Plugin SDK](/id/plugins/sdk-channel-plugins)
- Paket eksternal: [@tencent-weixin/openclaw-weixin](https://www.npmjs.com/package/@tencent-weixin/openclaw-weixin)

View File

@ -1,35 +1,35 @@
---
read_when:
- Anda ingin memahami untuk apa Active Memory digunakan
- Anda ingin memahami kegunaan Active Memory
- Anda ingin mengaktifkan Active Memory untuk agen percakapan
- Anda ingin menyesuaikan perilaku Active Memory tanpa mengaktifkannya di semua tempat
summary: Sub-agen memori pemblokiran milik Plugin yang menyuntikkan memori yang relevan ke dalam sesi chat interaktif
summary: Sub-agen memori pemblokiran milik Plugin yang menyuntikkan memori yang relevan ke dalam sesi obrolan interaktif
title: Active Memory
x-i18n:
generated_at: "2026-04-16T09:14:37Z"
generated_at: "2026-04-19T01:11:11Z"
model: gpt-5.4
provider: openai
source_hash: ab36c5fea1578348cc2258ea3b344cc7bdc814f337d659cdb790512b3ea45473
source_hash: 30fb5d12f1f2e3845d95b90925814faa5c84240684ebd4325c01598169088432
source_path: concepts/active-memory.md
workflow: 15
---
# Active Memory
Active memory adalah sub-agen memori pemblokiran opsional milik Plugin yang berjalan
Active Memory adalah sub-agen memori pemblokiran milik Plugin opsional yang berjalan
sebelum balasan utama untuk sesi percakapan yang memenuhi syarat.
Ini ada karena sebagian besar sistem memori mampu tetapi reaktif. Sistem tersebut bergantung pada
agen utama untuk memutuskan kapan harus menelusuri memori, atau pada pengguna untuk mengatakan hal-hal
seperti "ingat ini" atau "telusuri memori." Saat itu terjadi, momen ketika memori
seharusnya membuat balasan terasa alami sudah terlewat.
Fitur ini ada karena sebagian besar sistem memori mampu, tetapi reaktif. Mereka bergantung pada
agen utama untuk memutuskan kapan harus mencari memori, atau pada pengguna untuk mengatakan hal-hal
seperti "ingat ini" atau "cari memori." Pada saat itu, momen ketika memori akan
membuat balasan terasa alami sudah terlewat.
Active memory memberi sistem satu kesempatan terbatas untuk memunculkan memori yang relevan
sebelum balasan utama dibuat.
Active Memory memberi sistem satu kesempatan terbatas untuk menampilkan memori yang relevan
sebelum balasan utama dihasilkan.
## Tempelkan Ini Ke Dalam Agen Anda
## Tempelkan Ini ke Agen Anda
Tempelkan ini ke dalam agen Anda jika Anda ingin mengaktifkan Active Memory dengan
Tempelkan ini ke agen Anda jika Anda ingin mengaktifkan Active Memory dengan
pengaturan mandiri yang aman secara default:
```json5
@ -57,8 +57,9 @@ pengaturan mandiri yang aman secara default:
```
Ini menyalakan Plugin untuk agen `main`, menjaganya tetap terbatas pada sesi
bergaya pesan langsung secara default, memungkinkannya mewarisi model sesi saat ini terlebih dahulu, dan
menggunakan model fallback yang dikonfigurasi hanya jika tidak ada model eksplisit atau turunan yang tersedia.
bergaya pesan langsung secara default, membiarkannya mewarisi model sesi saat ini terlebih dahulu, dan
menggunakan model fallback yang dikonfigurasi hanya jika tidak ada model eksplisit atau
yang diwariskan.
Setelah itu, mulai ulang Gateway:
@ -115,17 +116,17 @@ openclaw gateway
Artinya:
- `plugins.entries.active-memory.enabled: true` menyalakan Plugin
- `config.agents: ["main"]` hanya mengikutsertakan agen `main` ke active memory
- `config.allowedChatTypes: ["direct"]` membuat active memory tetap aktif hanya untuk sesi bergaya pesan langsung secara default
- `config.agents: ["main"]` hanya memilih agen `main` untuk menggunakan active memory
- `config.allowedChatTypes: ["direct"]` membuat active memory tetap aktif untuk sesi bergaya pesan langsung saja secara default
- jika `config.model` tidak disetel, active memory mewarisi model sesi saat ini terlebih dahulu
- `config.modelFallback` secara opsional menyediakan provider/model fallback Anda sendiri untuk recall
- `config.promptStyle: "balanced"` menggunakan gaya prompt umum default untuk mode `recent`
- `config.promptStyle: "balanced"` menggunakan gaya prompt serbaguna default untuk mode `recent`
- active memory tetap hanya berjalan pada sesi chat persisten interaktif yang memenuhi syarat
## Rekomendasi kecepatan
Pengaturan paling sederhana adalah membiarkan `config.model` tidak disetel dan membiarkan Active Memory menggunakan
model yang sama yang sudah Anda gunakan untuk balasan normal. Itu adalah default paling aman
model yang sama yang sudah Anda gunakan untuk balasan normal. Itu adalah default yang paling aman
karena mengikuti preferensi provider, autentikasi, dan model yang sudah ada.
Jika Anda ingin Active Memory terasa lebih cepat, gunakan model inferensi khusus
@ -158,17 +159,17 @@ plugins: {
Opsi model cepat yang layak dipertimbangkan:
- `cerebras/gpt-oss-120b` untuk model recall khusus yang cepat dengan permukaan tool yang sempit
- `cerebras/gpt-oss-120b` untuk model recall khusus yang cepat dengan permukaan alat yang sempit
- model sesi normal Anda, dengan membiarkan `config.model` tidak disetel
- model fallback berlatensi rendah seperti `google/gemini-3-flash` saat Anda menginginkan model recall terpisah tanpa mengubah model chat utama Anda
- model fallback latensi rendah seperti `google/gemini-3-flash` saat Anda menginginkan model recall terpisah tanpa mengubah model chat utama Anda
Mengapa Cerebras merupakan opsi berorientasi kecepatan yang kuat untuk Active Memory:
Mengapa Cerebras adalah opsi berorientasi kecepatan yang kuat untuk Active Memory:
- permukaan tool Active Memory sempit: hanya memanggil `memory_search` dan `memory_get`
- kualitas recall penting, tetapi latensi lebih penting daripada pada jalur jawaban utama
- permukaan alat Active Memory sempit: hanya memanggil `memory_search` dan `memory_get`
- kualitas recall penting, tetapi latensi lebih penting dibandingkan jalur jawaban utama
- provider cepat khusus menghindari keterikatan latensi recall memori pada provider chat utama Anda
Jika Anda tidak menginginkan model terpisah yang dioptimalkan untuk kecepatan, biarkan `config.model` tidak disetel
Jika Anda tidak ingin model terpisah yang dioptimalkan untuk kecepatan, biarkan `config.model` tidak disetel
dan biarkan Active Memory mewarisi model sesi saat ini.
### Pengaturan Cerebras
@ -205,15 +206,15 @@ plugins: {
Catatan:
- pastikan API key Cerebras benar-benar memiliki akses model untuk model yang Anda pilih, karena visibilitas `/v1/models` saja tidak menjamin akses `chat/completions`
- pastikan kunci API Cerebras benar-benar memiliki akses model untuk model yang Anda pilih, karena visibilitas `/v1/models` saja tidak menjamin akses `chat/completions`
## Cara melihatnya
Active memory menyuntikkan awalan prompt tidak tepercaya tersembunyi untuk model. Fitur ini
Active memory menyuntikkan prefiks prompt tidak tepercaya tersembunyi untuk model. Fitur ini
tidak mengekspos tag mentah `<active_memory_plugin>...</active_memory_plugin>` dalam
balasan normal yang terlihat oleh klien.
## Tombol sesi
## Toggle sesi
Gunakan perintah Plugin saat Anda ingin menjeda atau melanjutkan active memory untuk
sesi chat saat ini tanpa mengedit konfigurasi:
@ -228,8 +229,8 @@ Ini berlaku pada cakupan sesi. Ini tidak mengubah
`plugins.entries.active-memory.enabled`, penargetan agen, atau konfigurasi global
lainnya.
Jika Anda ingin perintah menulis konfigurasi dan menjeda atau melanjutkan active memory untuk
semua sesi, gunakan bentuk global yang eksplisit:
Jika Anda ingin perintah tersebut menulis konfigurasi dan menjeda atau melanjutkan active memory untuk
semua sesi, gunakan bentuk global eksplisit:
```text
/active-memory status --global
@ -238,11 +239,11 @@ semua sesi, gunakan bentuk global yang eksplisit:
```
Bentuk global menulis `plugins.entries.active-memory.config.enabled`. Bentuk ini membiarkan
`plugins.entries.active-memory.enabled` tetap aktif agar perintah tetap tersedia untuk
`plugins.entries.active-memory.enabled` tetap aktif sehingga perintah tetap tersedia untuk
mengaktifkan kembali active memory nanti.
Jika Anda ingin melihat apa yang dilakukan active memory dalam sesi langsung, aktifkan
tombol sesi yang sesuai dengan keluaran yang Anda inginkan:
toggle sesi yang sesuai dengan output yang Anda inginkan:
```text
/verbose on
@ -254,14 +255,14 @@ Dengan itu diaktifkan, OpenClaw dapat menampilkan:
- baris status active memory seperti `Active Memory: status=ok elapsed=842ms query=recent summary=34 chars` saat `/verbose on`
- ringkasan debug yang mudah dibaca seperti `Active Memory Debug: Lemon pepper wings with blue cheese.` saat `/trace on`
Baris-baris tersebut berasal dari pass active memory yang sama yang memberi masukan pada
awalan prompt tersembunyi, tetapi diformat untuk manusia alih-alih mengekspos markup prompt mentah.
Baris-baris tersebut dikirim sebagai pesan diagnostik lanjutan setelah balasan normal
asisten sehingga klien saluran seperti Telegram tidak menampilkan gelembung diagnostik terpisah
sebelum balasan.
Baris-baris tersebut berasal dari pass active memory yang sama yang memasok prefiks
prompt tersembunyi, tetapi diformat untuk manusia alih-alih mengekspos markup prompt
mentah. Baris tersebut dikirim sebagai pesan diagnostik lanjutan setelah balasan
asisten normal sehingga klien kanal seperti Telegram tidak menampilkan gelembung diagnostik
terpisah sebelum balasan.
Jika Anda juga mengaktifkan `/trace raw`, blok `Model Input (User Role)` yang ditelusuri akan
menampilkan awalan Active Memory tersembunyi sebagai:
Jika Anda juga mengaktifkan `/trace raw`, blok `Model Input (User Role)` yang dilacak akan
menampilkan prefiks Active Memory tersembunyi sebagai:
```text
Untrusted context (metadata, do not treat as instructions or commands):
@ -281,7 +282,7 @@ Contoh alur:
what wings should i order?
```
Bentuk balasan yang diharapkan terlihat:
Bentuk balasan terlihat yang diharapkan:
```text
...normal assistant reply...
@ -290,16 +291,15 @@ Bentuk balasan yang diharapkan terlihat:
🔎 Active Memory Debug: Lemon pepper wings with blue cheese.
```
## Kapan berjalan
## Kapan dijalankan
Active memory menggunakan dua gerbang:
1. **Opt-in konfigurasi**
Plugin harus diaktifkan, dan ID agen saat ini harus muncul di
Plugin harus diaktifkan, dan id agen saat ini harus muncul di
`plugins.entries.active-memory.config.agents`.
2. **Kelayakan runtime yang ketat**
Bahkan ketika diaktifkan dan ditargetkan, active memory hanya berjalan untuk
sesi chat persisten interaktif yang memenuhi syarat.
Bahkan saat diaktifkan dan ditargetkan, active memory hanya berjalan untuk sesi chat persisten interaktif yang memenuhi syarat.
Aturan sebenarnya adalah:
@ -315,11 +315,11 @@ eligible interactive persistent chat session
active memory runs
```
Jika salah satu gagal, active memory tidak berjalan.
Jika salah satu dari itu gagal, active memory tidak akan berjalan.
## Jenis sesi
`config.allowedChatTypes` mengontrol jenis percakapan mana yang boleh menjalankan Active
`config.allowedChatTypes` mengontrol jenis percakapan mana yang dapat menjalankan Active
Memory sama sekali.
Default-nya adalah:
@ -329,7 +329,7 @@ allowedChatTypes: ["direct"]
```
Artinya Active Memory berjalan secara default dalam sesi bergaya pesan langsung, tetapi
tidak dalam sesi grup atau saluran kecuali Anda secara eksplisit mengikutsertakannya.
tidak dalam sesi grup atau kanal kecuali Anda secara eksplisit memilihnya.
Contoh:
@ -345,26 +345,26 @@ allowedChatTypes: ["direct", "group"]
allowedChatTypes: ["direct", "group", "channel"]
```
## Di mana berjalan
## Di mana dijalankan
Active memory adalah fitur pengayaan percakapan, bukan fitur inferensi
seluruh platform.
| Surface | Menjalankan active memory? |
| ------------------------------------------------------------------- | ------------------------------------------------------- |
| Control UI / sesi persisten web chat | Ya, jika Plugin diaktifkan dan agen ditargetkan |
| Sesi saluran interaktif lain pada jalur chat persisten yang sama | Ya, jika Plugin diaktifkan dan agen ditargetkan |
| Proses headless sekali jalan | Tidak |
| Proses Heartbeat/latar belakang | Tidak |
| Sesi persisten Control UI / web chat | Ya, jika Plugin diaktifkan dan agen ditargetkan |
| Sesi kanal interaktif lain pada jalur chat persisten yang sama | Ya, jika Plugin diaktifkan dan agen ditargetkan |
| Eksekusi headless satu kali | Tidak |
| Eksekusi Heartbeat/latar belakang | Tidak |
| Jalur internal `agent-command` generik | Tidak |
| Eksekusi sub-agen/helper internal | Tidak |
| Eksekusi helper internal/sub-agen | Tidak |
## Mengapa menggunakannya
Gunakan active memory saat:
- sesi bersifat persisten dan berhadapan dengan pengguna
- agen memiliki memori jangka panjang yang bermakna untuk ditelusuri
- agen memiliki memori jangka panjang yang bermakna untuk dicari
- kontinuitas dan personalisasi lebih penting daripada determinisme prompt mentah
Fitur ini bekerja sangat baik untuk:
@ -375,9 +375,9 @@ Fitur ini bekerja sangat baik untuk:
Fitur ini kurang cocok untuk:
- otomatisasi
- worker internal
- tugas API sekali jalan
- otomasi
- pekerja internal
- tugas API satu kali
- tempat di mana personalisasi tersembunyi akan terasa mengejutkan
## Cara kerjanya
@ -406,15 +406,15 @@ Jika koneksinya lemah, sub-agen harus mengembalikan `NONE`.
## Gaya prompt
`config.promptStyle` mengontrol seberapa antusias atau ketat sub-agen memori pemblokiran
`config.promptStyle` mengontrol seberapa agresif atau ketat sub-agen memori pemblokiran
saat memutuskan apakah akan mengembalikan memori.
Gaya yang tersedia:
- `balanced`: default serbaguna untuk mode `recent`
- `strict`: paling tidak antusias; terbaik saat Anda menginginkan sangat sedikit pengaruh dari konteks terdekat
- `contextual`: paling ramah kontinuitas; terbaik saat riwayat percakapan harus lebih diperhitungkan
- `recall-heavy`: lebih bersedia memunculkan memori pada kecocokan yang lebih lemah tetapi masih masuk akal
- `strict`: paling tidak agresif; terbaik saat Anda menginginkan sangat sedikit pengaruh dari konteks terdekat
- `contextual`: paling ramah terhadap kontinuitas; terbaik saat riwayat percakapan perlu lebih diperhatikan
- `recall-heavy`: lebih bersedia menampilkan memori pada kecocokan yang lebih lunak tetapi masih masuk akal
- `precision-heavy`: sangat memilih `NONE` kecuali kecocokannya jelas
- `preference-only`: dioptimalkan untuk favorit, kebiasaan, rutinitas, selera, dan fakta pribadi yang berulang
@ -453,17 +453,17 @@ Fallback kustom opsional:
modelFallback: "google/gemini-3-flash"
```
Jika tidak ada model eksplisit, turunan, atau fallback terkonfigurasi yang berhasil diselesaikan, Active Memory
Jika tidak ada model eksplisit, yang diwariskan, atau fallback terkonfigurasi yang dapat diselesaikan, Active Memory
melewati recall untuk giliran tersebut.
`config.modelFallbackPolicy` dipertahankan hanya sebagai field kompatibilitas
usang untuk konfigurasi lama. Field ini tidak lagi mengubah perilaku runtime.
`config.modelFallbackPolicy` dipertahankan hanya sebagai
field kompatibilitas usang untuk konfigurasi lama. Field ini tidak lagi mengubah perilaku runtime.
## Opsi lanjutan untuk situasi khusus
## Escape hatch lanjutan
Opsi ini sengaja tidak menjadi bagian dari pengaturan yang direkomendasikan.
Opsi-opsi ini sengaja tidak menjadi bagian dari pengaturan yang direkomendasikan.
`config.thinking` dapat menimpa tingkat thinking sub-agen memori pemblokiran:
`config.thinking` dapat mengganti tingkat thinking sub-agen memori pemblokiran:
```json5
thinking: "medium"
@ -475,7 +475,7 @@ Default:
thinking: "off"
```
Jangan aktifkan ini secara default. Active Memory berjalan di jalur balasan, jadi waktu
Jangan aktifkan ini secara default. Active Memory berjalan di jalur balasan, sehingga waktu
thinking tambahan secara langsung meningkatkan latensi yang terlihat oleh pengguna.
`config.promptAppend` menambahkan instruksi operator tambahan setelah prompt default Active
@ -492,7 +492,7 @@ tetap menambahkan konteks percakapan setelahnya:
promptOverride: "You are a memory search agent. Return NONE or one compact user fact."
```
Kustomisasi prompt tidak direkomendasikan kecuali Anda memang sedang menguji
Penyesuaian prompt tidak direkomendasikan kecuali Anda memang sedang menguji
kontrak recall yang berbeda. Prompt default disetel untuk mengembalikan `NONE`
atau konteks fakta pengguna yang ringkas untuk model utama.
@ -508,15 +508,15 @@ Gunakan ini ketika:
- Anda menginginkan perilaku tercepat
- Anda menginginkan bias terkuat terhadap recall preferensi yang stabil
- giliran lanjutan tidak memerlukan konteks percakapan
- giliran tindak lanjut tidak memerlukan konteks percakapan
Timeout yang direkomendasikan:
- mulai dari sekitar `3000` hingga `5000` ms
- mulai sekitar `3000` hingga `5000` md
### `recent`
Pesan pengguna terbaru ditambah ekor percakapan terbaru yang kecil akan dikirim.
Pesan pengguna terbaru ditambah ekor percakapan terbaru yang kecil dikirim.
```text
Recent conversation tail:
@ -530,12 +530,12 @@ Latest user message:
Gunakan ini ketika:
- Anda menginginkan keseimbangan yang lebih baik antara kecepatan dan pijakan percakapan
- pertanyaan lanjutan sering bergantung pada beberapa giliran terakhir
- Anda menginginkan keseimbangan yang lebih baik antara kecepatan dan landasan percakapan
- pertanyaan tindak lanjut sering bergantung pada beberapa giliran terakhir
Timeout yang direkomendasikan:
- mulai dari sekitar `15000` ms
- mulai sekitar `15000` md
### `full`
@ -556,10 +556,10 @@ Gunakan ini ketika:
Timeout yang direkomendasikan:
- tingkatkan secara signifikan dibandingkan `message` atau `recent`
- mulai dari sekitar `15000` ms atau lebih tinggi tergantung ukuran utas
- tingkatkan secara signifikan dibandingkan dengan `message` atau `recent`
- mulai sekitar `15000` md atau lebih tinggi tergantung ukuran utas
Secara umum, timeout sebaiknya meningkat seiring ukuran konteks:
Secara umum, timeout harus meningkat seiring dengan ukuran konteks:
```text
message < recent < full
@ -567,17 +567,17 @@ message < recent < full
## Persistensi transkrip
Proses sub-agen memori pemblokiran Active memory membuat transkrip `session.jsonl` nyata
selama pemanggilan sub-agen memori pemblokiran.
Eksekusi sub-agen memori pemblokiran Active Memory membuat transkrip `session.jsonl`
nyata selama pemanggilan sub-agen memori pemblokiran.
Secara default, transkrip tersebut bersifat sementara:
- ditulis ke direktori sementara
- hanya digunakan untuk proses sub-agen memori pemblokiran
- dihapus segera setelah proses selesai
- transkrip ditulis ke direktori temp
- transkrip hanya digunakan untuk eksekusi sub-agen memori pemblokiran
- transkrip dihapus segera setelah eksekusi selesai
Jika Anda ingin menyimpan transkrip sub-agen memori pemblokiran tersebut di disk untuk debugging atau
pemeriksaan, aktifkan persistensi secara eksplisit:
Jika Anda ingin menyimpan transkrip sub-agen memori pemblokiran tersebut di disk untuk debug atau
inspeksi, aktifkan persistensi secara eksplisit:
```json5
{
@ -596,10 +596,10 @@ pemeriksaan, aktifkan persistensi secara eksplisit:
}
```
Saat diaktifkan, active memory menyimpan transkrip dalam direktori terpisah di bawah
Saat diaktifkan, active memory menyimpan transkrip di direktori terpisah di bawah
folder sesi agen target, bukan di jalur transkrip percakapan pengguna utama.
Secara konseptual, tata letak default adalah:
Tata letak default secara konseptual adalah:
```text
agents/<agent>/sessions/active-memory/<blocking-memory-sub-agent-session-id>.jsonl
@ -610,8 +610,8 @@ Anda dapat mengubah subdirektori relatif dengan `config.transcriptDir`.
Gunakan ini dengan hati-hati:
- transkrip sub-agen memori pemblokiran dapat menumpuk dengan cepat pada sesi yang sibuk
- mode kueri `full` dapat menduplikasi banyak konteks percakapan
- transkrip ini berisi konteks prompt tersembunyi dan memori yang di-recall
- mode kueri `full` dapat menggandakan banyak konteks percakapan
- transkrip ini berisi konteks prompt tersembunyi dan memori yang dipanggil kembali
## Konfigurasi
@ -623,32 +623,32 @@ plugins.entries.active-memory
Field yang paling penting adalah:
| Key | Type | Arti |
| --------------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `enabled` | `boolean` | Mengaktifkan Plugin itu sendiri |
| `config.agents` | `string[]` | ID agen yang dapat menggunakan active memory |
| `config.model` | `string` | Ref model sub-agen memori pemblokiran opsional; jika tidak disetel, active memory menggunakan model sesi saat ini |
| `config.queryMode` | `"message" \| "recent" \| "full"` | Mengontrol seberapa banyak percakapan yang dilihat sub-agen memori pemblokiran |
| `config.promptStyle` | `"balanced" \| "strict" \| "contextual" \| "recall-heavy" \| "precision-heavy" \| "preference-only"` | Mengontrol seberapa antusias atau ketat sub-agen memori pemblokiran saat memutuskan apakah akan mengembalikan memori |
| `config.thinking` | `"off" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "adaptive"` | Override thinking lanjutan untuk sub-agen memori pemblokiran; default `off` demi kecepatan |
| `config.promptOverride` | `string` | Penggantian prompt penuh lanjutan; tidak direkomendasikan untuk penggunaan normal |
| `config.promptAppend` | `string` | Instruksi tambahan lanjutan yang ditambahkan ke prompt default atau yang dioverride |
| `config.timeoutMs` | `number` | Timeout keras untuk sub-agen memori pemblokiran |
| `config.maxSummaryChars` | `number` | Jumlah total karakter maksimum yang diizinkan dalam ringkasan active-memory |
| `config.logging` | `boolean` | Menghasilkan log active memory selama penyesuaian |
| `config.persistTranscripts` | `boolean` | Menyimpan transkrip sub-agen memori pemblokiran di disk alih-alih menghapus file sementara |
| `config.transcriptDir` | `string` | Direktori transkrip sub-agen memori pemblokiran relatif di bawah folder sesi agen |
| Kunci | Tipe | Arti |
| --------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `enabled` | `boolean` | Mengaktifkan Plugin itu sendiri |
| `config.agents` | `string[]` | ID agen yang boleh menggunakan active memory |
| `config.model` | `string` | Ref model sub-agen memori pemblokiran opsional; saat tidak disetel, active memory menggunakan model sesi saat ini |
| `config.queryMode` | `"message" \| "recent" \| "full"` | Mengontrol seberapa banyak percakapan yang dilihat sub-agen memori pemblokiran |
| `config.promptStyle` | `"balanced" \| "strict" \| "contextual" \| "recall-heavy" \| "precision-heavy" \| "preference-only"` | Mengontrol seberapa agresif atau ketat sub-agen memori pemblokiran saat memutuskan apakah akan mengembalikan memori |
| `config.thinking` | `"off" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "adaptive"` | Override thinking lanjutan untuk sub-agen memori pemblokiran; default `off` untuk kecepatan |
| `config.promptOverride` | `string` | Penggantian prompt penuh lanjutan; tidak direkomendasikan untuk penggunaan normal |
| `config.promptAppend` | `string` | Instruksi tambahan lanjutan yang ditambahkan ke prompt default atau prompt yang diganti |
| `config.timeoutMs` | `number` | Timeout keras untuk sub-agen memori pemblokiran, dibatasi hingga 120000 md |
| `config.maxSummaryChars` | `number` | Total karakter maksimum yang diizinkan dalam ringkasan active-memory |
| `config.logging` | `boolean` | Menghasilkan log active memory saat penyesuaian |
| `config.persistTranscripts` | `boolean` | Menyimpan transkrip sub-agen memori pemblokiran di disk alih-alih menghapus file temp |
| `config.transcriptDir` | `string` | Direktori transkrip sub-agen memori pemblokiran relatif di bawah folder sesi agen |
Field penyesuaian yang berguna:
| Key | Type | Arti |
| ----------------------------- | -------- | ------------------------------------------------------------------ |
| `config.maxSummaryChars` | `number` | Jumlah total karakter maksimum yang diizinkan dalam ringkasan active-memory |
| Kunci | Tipe | Arti |
| ----------------------------- | -------- | ------------------------------------------------------------ |
| `config.maxSummaryChars` | `number` | Total karakter maksimum yang diizinkan dalam ringkasan active-memory |
| `config.recentUserTurns` | `number` | Giliran pengguna sebelumnya yang disertakan saat `queryMode` adalah `recent` |
| `config.recentAssistantTurns` | `number` | Giliran asisten sebelumnya yang disertakan saat `queryMode` adalah `recent` |
| `config.recentUserChars` | `number` | Karakter maksimum per giliran pengguna terbaru |
| `config.recentAssistantChars` | `number` | Karakter maksimum per giliran asisten terbaru |
| `config.cacheTtlMs` | `number` | Penggunaan ulang cache untuk kueri identik berulang |
| `config.recentUserChars` | `number` | Karakter maksimum per giliran pengguna terbaru |
| `config.recentAssistantChars` | `number` | Karakter maksimum per giliran asisten terbaru |
| `config.cacheTtlMs` | `number` | Penggunaan ulang cache untuk kueri identik yang berulang |
## Pengaturan yang direkomendasikan
@ -675,26 +675,26 @@ Mulailah dengan `recent`.
```
Jika Anda ingin memeriksa perilaku langsung saat penyesuaian, gunakan `/verbose on` untuk
baris status normal dan `/trace on` untuk ringkasan debug active-memory
alih-alih mencari perintah debug active-memory terpisah. Di saluran chat, baris
diagnostik tersebut dikirim setelah balasan utama asisten, bukan sebelumnya.
baris status normal dan `/trace on` untuk ringkasan debug active-memory alih-alih
mencari perintah debug active-memory terpisah. Di kanal chat, baris diagnostik tersebut
dikirim setelah balasan asisten utama, bukan sebelumnya.
Lalu pindah ke:
Lalu beralih ke:
- `message` jika Anda menginginkan latensi yang lebih rendah
- `message` jika Anda menginginkan latensi lebih rendah
- `full` jika Anda memutuskan konteks tambahan sepadan dengan sub-agen memori pemblokiran yang lebih lambat
## Debugging
Jika active memory tidak muncul di tempat yang Anda harapkan:
1. Pastikan Plugin diaktifkan di `plugins.entries.active-memory.enabled`.
2. Pastikan ID agen saat ini tercantum di `config.agents`.
3. Pastikan Anda menguji melalui sesi chat persisten interaktif.
4. Aktifkan `config.logging: true` dan pantau log Gateway.
5. Verifikasi bahwa penelusuran memori itu sendiri berfungsi dengan `openclaw memory status --deep`.
1. Konfirmasikan Plugin diaktifkan di bawah `plugins.entries.active-memory.enabled`.
2. Konfirmasikan ID agen saat ini tercantum dalam `config.agents`.
3. Konfirmasikan Anda menguji melalui sesi chat persisten interaktif.
4. Aktifkan `config.logging: true` dan amati log Gateway.
5. Verifikasi pencarian memori itu sendiri berfungsi dengan `openclaw memory status --deep`.
Jika hasil memori terlalu bising, perketat:
Jika hit memori terlalu bising, perketat:
- `maxSummaryChars`
@ -707,21 +707,21 @@ Jika active memory terlalu lambat:
## Masalah umum
### Provider embedding berubah tanpa diduga
### Provider embedding berubah secara tidak terduga
Active Memory menggunakan pipeline `memory_search` normal di bawah
`agents.defaults.memorySearch`. Artinya, pengaturan provider embedding hanya menjadi
persyaratan saat pengaturan `memorySearch` Anda memerlukan embedding untuk perilaku
`agents.defaults.memorySearch`. Itu berarti pengaturan provider embedding hanya
merupakan persyaratan saat pengaturan `memorySearch` Anda memerlukan embedding untuk perilaku
yang Anda inginkan.
Dalam praktiknya:
- pengaturan provider eksplisit **diperlukan** jika Anda menginginkan provider yang tidak
terdeteksi otomatis, seperti `ollama`
- pengaturan provider eksplisit **diperlukan** jika deteksi otomatis tidak berhasil
menyelesaikan provider embedding yang dapat digunakan untuk lingkungan Anda
- pengaturan provider eksplisit **sangat direkomendasikan** jika Anda menginginkan
pemilihan provider yang deterministik alih-alih "yang tersedia pertama menang"
- pengaturan provider eksplisit **diperlukan** jika deteksi otomatis tidak dapat menyelesaikan
provider embedding yang dapat digunakan untuk lingkungan Anda
- pengaturan provider eksplisit **sangat direkomendasikan** jika Anda menginginkan pemilihan provider
yang deterministik alih-alih "yang tersedia pertama yang menang"
- pengaturan provider eksplisit biasanya **tidak diperlukan** jika deteksi otomatis sudah
menyelesaikan provider yang Anda inginkan dan provider tersebut stabil dalam deployment Anda
@ -730,37 +730,37 @@ embedding pertama yang tersedia.
Hal itu dapat membingungkan dalam deployment nyata:
- API key yang baru tersedia dapat mengubah provider mana yang digunakan penelusuran memori
- satu perintah atau permukaan diagnostik mungkin membuat provider yang dipilih tampak
berbeda dari jalur yang benar-benar Anda gunakan selama sinkronisasi memori langsung atau
bootstrap penelusuran
- provider ter-host dapat gagal dengan error kuota atau rate limit yang baru terlihat
setelah Active Memory mulai mengeluarkan kueri recall sebelum setiap balasan
- kunci API yang baru tersedia dapat mengubah provider yang digunakan pencarian memori
- satu perintah atau surface diagnostik dapat membuat provider yang dipilih terlihat
berbeda dari jalur yang sebenarnya Anda gunakan selama sinkronisasi memori langsung atau
bootstrap pencarian
- provider terhosting dapat gagal dengan error kuota atau batas laju yang hanya muncul
setelah Active Memory mulai mengeluarkan pencarian recall sebelum setiap balasan
Active Memory tetap dapat berjalan tanpa embedding saat `memory_search` dapat beroperasi
dalam mode degradasi leksikal saja, yang biasanya terjadi saat tidak ada provider
dalam mode degradasi leksikal saja, yang biasanya terjadi ketika tidak ada provider
embedding yang dapat diselesaikan.
Jangan berasumsi fallback yang sama berlaku pada kegagalan runtime provider seperti
kuota habis, rate limit, error jaringan/provider, atau model lokal/jarak jauh yang hilang
kuota habis, batas laju, error jaringan/provider, atau model lokal/jarak jauh yang hilang
setelah provider sudah dipilih.
Dalam praktiknya:
- jika tidak ada provider embedding yang dapat diselesaikan, `memory_search` dapat turun menjadi
pengambilan leksikal saja
- jika provider embedding berhasil diselesaikan lalu gagal saat runtime, OpenClaw saat ini
tidak menjamin fallback leksikal untuk permintaan tersebut
- jika tidak ada provider embedding yang dapat diselesaikan, `memory_search` dapat terdegradasi menjadi
pengambilan berbasis leksikal saja
- jika sebuah provider embedding berhasil diselesaikan lalu gagal saat runtime, OpenClaw
saat ini tidak menjamin fallback leksikal untuk permintaan tersebut
- jika Anda memerlukan pemilihan provider yang deterministik, pin
`agents.defaults.memorySearch.provider`
- jika Anda memerlukan failover provider saat terjadi error runtime, konfigurasikan
`agents.defaults.memorySearch.fallback` secara eksplisit
Jika Anda bergantung pada recall berbasis embedding, pengindeksan multimodal, atau provider
lokal/jarak jauh tertentu, pin provider secara eksplisit alih-alih mengandalkan
lokal/jarak jauh tertentu, pin provider tersebut secara eksplisit alih-alih mengandalkan
deteksi otomatis.
Contoh pinning yang umum:
Contoh pinning umum:
OpenAI:
@ -807,8 +807,8 @@ Ollama:
}
```
Jika Anda mengharapkan failover provider pada error runtime seperti
kuota habis, pinning provider saja tidak cukup. Konfigurasikan fallback eksplisit juga:
Jika Anda mengharapkan failover provider pada error runtime seperti kuota habis,
pinning provider saja tidak cukup. Konfigurasikan fallback eksplisit juga:
```json5
{
@ -825,20 +825,20 @@ kuota habis, pinning provider saja tidak cukup. Konfigurasikan fallback eksplisi
### Debugging masalah provider
Jika Active Memory lambat, kosong, atau tampak berpindah provider tanpa diduga:
Jika Active Memory lambat, kosong, atau tampak berganti provider secara tidak terduga:
- pantau log Gateway saat mereproduksi masalah; cari baris seperti
- amati log Gateway saat mereproduksi masalah; cari baris seperti
`active-memory: ... start|done`, `memory sync failed (search-bootstrap)`, atau
error embedding spesifik provider
error embedding khusus provider
- aktifkan `/trace on` untuk menampilkan ringkasan debug Active Memory milik Plugin di
sesi
- aktifkan `/verbose on` jika Anda juga ingin baris status normal `🧩 Active Memory: ...`
- aktifkan `/verbose on` jika Anda juga menginginkan baris status normal `🧩 Active Memory: ...`
setelah setiap balasan
- jalankan `openclaw memory status --deep` untuk memeriksa backend penelusuran memori saat ini
dan kesehatan indeks
- periksa `agents.defaults.memorySearch.provider` serta autentikasi/konfigurasi terkait untuk memastikan
- jalankan `openclaw memory status --deep` untuk memeriksa backend memory-search
saat ini dan kesehatan indeks
- periksa `agents.defaults.memorySearch.provider` dan autentikasi/konfigurasi terkait untuk memastikan
provider yang Anda harapkan benar-benar yang dapat diselesaikan saat runtime
- jika Anda menggunakan `ollama`, verifikasi bahwa model embedding yang dikonfigurasi telah terinstal, misalnya dengan
- jika Anda menggunakan `ollama`, verifikasi model embedding yang dikonfigurasi telah terpasang, misalnya dengan
`ollama list`
Contoh alur debugging:

View File

@ -5,10 +5,10 @@ read_when:
summary: Catatan crash Node + tsx "__name is not a function" dan solusinya
title: Crash Node + tsx
x-i18n:
generated_at: "2026-04-05T13:52:45Z"
generated_at: "2026-04-19T01:11:11Z"
model: gpt-5.4
provider: openai
source_hash: f5beab7cdfe7679680f65176234a617293ce495886cfffb151518adfa61dc8dc
source_hash: ca45c795c356ada8f81e75b394ec82743d3d1bf1bbe83a24ec6699946b920f01
source_path: debug/node-issue.md
workflow: 15
---
@ -25,18 +25,18 @@ Menjalankan OpenClaw melalui Node dengan `tsx` gagal saat startup dengan:
at .../src/agents/auth-profiles/constants.ts:25:20
```
Ini mulai terjadi setelah skrip dev dialihkan dari Bun ke `tsx` (commit `2871657e`, 2026-01-06). Jalur runtime yang sama sebelumnya berfungsi dengan Bun.
Ini mulai terjadi setelah skrip dev dialihkan dari Bun ke `tsx` (commit `2871657e`, 2026-01-06). Jalur runtime yang sama sebelumnya berjalan dengan Bun.
## Lingkungan
- Node: v25.x (diamati pada v25.3.0)
- Node: v25.x (teramati pada v25.3.0)
- tsx: 4.21.0
- OS: macOS (repro kemungkinan juga terjadi di platform lain yang menjalankan Node 25)
- OS: macOS (repro juga kemungkinan terjadi di platform lain yang menjalankan Node 25)
## Repro (khusus Node)
```bash
# in repo root
# di root repo
node --version
pnpm install
node --import tsx src/entry.ts status
@ -56,27 +56,27 @@ node --import tsx scripts/repro/tsx-name-repro.ts
## Catatan / hipotesis
- `tsx` menggunakan esbuild untuk mentransformasi TS/ESM. `keepNames` milik esbuild mengeluarkan helper `__name` dan membungkus definisi fungsi dengan `__name(...)`.
- Crash ini menunjukkan `__name` ada tetapi bukan function saat runtime, yang mengindikasikan helper tersebut hilang atau tertimpa untuk modul ini di jalur loader Node 25.
- Masalah helper `__name` serupa telah dilaporkan di konsumen esbuild lain ketika helper tersebut hilang atau ditulis ulang.
- `tsx` menggunakan esbuild untuk mentransformasi TS/ESM. `keepNames` milik esbuild menghasilkan helper `__name` dan membungkus definisi fungsi dengan `__name(...)`.
- Crash ini menunjukkan bahwa `__name` ada tetapi bukan fungsi saat runtime, yang mengindikasikan helper tersebut hilang atau tertimpa untuk modul ini pada jalur loader Node 25.
- Masalah helper `__name` serupa telah dilaporkan pada consumer esbuild lain ketika helper tersebut hilang atau ditulis ulang.
## Riwayat regresi
- `2871657e` (2026-01-06): skrip diubah dari Bun ke tsx agar Bun menjadi opsional.
- Sebelum itu (jalur Bun), `openclaw status` dan `gateway:watch` berfungsi.
- Sebelumnya (jalur Bun), `openclaw status` dan `gateway:watch` berjalan.
## Solusi sementara
- Gunakan Bun untuk skrip dev (revert sementara saat ini).
- Gunakan Node + tsc watch, lalu jalankan output hasil kompilasi:
- Gunakan `tsgo` untuk type checking repo, lalu jalankan output hasil build:
```bash
pnpm exec tsc --watch --preserveWatchOutput
node --watch openclaw.mjs status
pnpm tsgo
node openclaw.mjs status
```
- Dikonfirmasi secara lokal: `pnpm exec tsc -p tsconfig.json` + `node openclaw.mjs status` berfungsi di Node 25.
- Nonaktifkan `keepNames` esbuild di loader TS jika memungkinkan (mencegah penyisipan helper `__name`); saat ini tsx tidak mengekspos ini.
- Catatan historis: `tsc` digunakan di sini saat men-debug masalah Node/tsx ini, tetapi lane type-check repo sekarang menggunakan `tsgo`.
- Nonaktifkan `keepNames` esbuild di loader TS jika memungkinkan (mencegah penyisipan helper `__name`); saat ini tsx belum menyediakan opsi ini.
- Uji Node LTS (22/24) dengan `tsx` untuk melihat apakah masalah ini khusus Node 25.
## Referensi
@ -87,6 +87,6 @@ node --import tsx scripts/repro/tsx-name-repro.ts
## Langkah berikutnya
- Repro di Node 22/24 untuk mengonfirmasi regresi Node 25.
- Uji `tsx` nightly atau pin ke versi yang lebih lama jika ada regresi yang diketahui.
- Jika juga dapat direproduksi di Node LTS, ajukan repro minimal upstream dengan stack trace `__name`.
- Repro pada Node 22/24 untuk mengonfirmasi regresi Node 25.
- Uji `tsx` nightly atau pin ke versi yang lebih lama jika ada regresi yang sudah diketahui.
- Jika tetap tereproduksi pada Node LTS, kirim repro minimal ke upstream dengan stack trace `__name` tersebut.

View File

@ -1,15 +1,15 @@
---
read_when:
- Anda ingin OpenClaw berjalan 24/7 di GCP
- Anda menginginkan Gateway kelas produksi yang selalu aktif di VM milik Anda sendiri
- Anda menginginkan Gateway tingkat produksi yang selalu aktif di VM Anda sendiri
- Anda menginginkan kontrol penuh atas persistensi, biner, dan perilaku restart
summary: Jalankan OpenClaw Gateway 24/7 di GCP Compute Engine VM (Docker) dengan state yang tahan lama
summary: Jalankan Gateway OpenClaw 24/7 di VM GCP Compute Engine (Docker) dengan status yang tahan lama
title: GCP
x-i18n:
generated_at: "2026-04-05T13:57:56Z"
generated_at: "2026-04-19T01:11:32Z"
model: gpt-5.4
provider: openai
source_hash: 73daaee3de71dad5175f42abf3e11355f2603b2f9e2b2523eac4d4c7015e3ebc
source_hash: 6b4cf7924cbcfae74f268c88caedb79ed87a6ad37f4910ad65d92a5d99fe49c1
source_path: install/gcp.md
workflow: 15
---
@ -18,68 +18,68 @@ x-i18n:
## Tujuan
Jalankan OpenClaw Gateway persisten di GCP Compute Engine VM menggunakan Docker, dengan state yang tahan lama, biner yang sudah dibenamkan, dan perilaku restart yang aman.
Jalankan Gateway OpenClaw yang persisten di VM GCP Compute Engine menggunakan Docker, dengan status yang tahan lama, biner yang sudah disertakan, dan perilaku restart yang aman.
Jika Anda menginginkan "OpenClaw 24/7 seharga ~$5-12/bulan", ini adalah penyiapan yang andal di Google Cloud.
Harga bervariasi menurut jenis mesin dan region; pilih VM terkecil yang sesuai dengan beban kerja Anda dan tingkatkan jika Anda mengalami OOM.
## Apa yang kita lakukan (dengan istilah sederhana)?
## Apa yang kita lakukan (dalam istilah sederhana)?
- Membuat project GCP dan mengaktifkan penagihan
- Membuat Compute Engine VM
- Memasang Docker (runtime aplikasi yang terisolasi)
- Menjalankan OpenClaw Gateway di Docker
- Menyimpan `~/.openclaw` + `~/.openclaw/workspace` secara persisten di host (tetap ada setelah restart/rebuild)
- Mengakses Control UI dari laptop Anda melalui SSH tunnel
- Membuat project GCP dan mengaktifkan billing
- Membuat VM Compute Engine
- Menginstal Docker (runtime aplikasi yang terisolasi)
- Menjalankan Gateway OpenClaw di Docker
- Menyimpan `~/.openclaw` + `~/.openclaw/workspace` di host (tetap ada setelah restart/rebuild)
- Mengakses Control UI dari laptop Anda melalui tunnel SSH
State `~/.openclaw` yang di-mount itu mencakup `openclaw.json`, per-agent
Status `~/.openclaw` yang dipasang itu mencakup `openclaw.json`, per-agent
`agents/<agentId>/agent/auth-profiles.json`, dan `.env`.
Gateway dapat diakses melalui:
- Penerusan port SSH dari laptop Anda
- Eksposur port langsung jika Anda mengelola firewall dan token sendiri
- Ekspos port langsung jika Anda mengelola firewall dan token sendiri
Panduan ini menggunakan Debian di GCP Compute Engine.
Ubuntu juga berfungsi; sesuaikan paketnya.
Untuk alur Docker generik, lihat [Docker](/install/docker).
Untuk alur Docker umum, lihat [Docker](/id/install/docker).
---
## Jalur cepat (operator berpengalaman)
1. Buat project GCP + aktifkan Compute Engine API
2. Buat Compute Engine VM (e2-small, Debian 12, 20GB)
2. Buat VM Compute Engine (`e2-small`, Debian 12, 20GB)
3. SSH ke VM
4. Pasang Docker
5. Clone repositori OpenClaw
4. Instal Docker
5. Clone repository OpenClaw
6. Buat direktori host persisten
7. Konfigurasikan `.env` dan `docker-compose.yml`
8. Benamkan biner yang diperlukan, build, dan jalankan
8. Sertakan biner yang diperlukan, build, dan jalankan
---
## Yang Anda butuhkan
## Yang Anda perlukan
- Akun GCP (free tier memenuhi syarat untuk e2-micro)
- gcloud CLI terpasang (atau gunakan Cloud Console)
- Akun GCP (memenuhi syarat free tier untuk `e2-micro`)
- CLI `gcloud` terinstal (atau gunakan Cloud Console)
- Akses SSH dari laptop Anda
- Pemahaman dasar tentang SSH + salin/tempel
- Pemahaman dasar tentang SSH + copy/paste
- ~20-30 menit
- Docker dan Docker Compose
- Kredensial auth model
- Kredensial provider opsional
- QR WhatsApp
- token bot Telegram
- Gmail OAuth
- Token bot Telegram
- OAuth Gmail
---
<Steps>
<Step title="Pasang gcloud CLI (atau gunakan Console)">
**Opsi A: gcloud CLI** (direkomendasikan untuk otomasi)
<Step title="Instal CLI gcloud (atau gunakan Console)">
**Opsi A: CLI `gcloud`** (direkomendasikan untuk otomatisasi)
Pasang dari [https://cloud.google.com/sdk/docs/install](https://cloud.google.com/sdk/docs/install)
Instal dari [https://cloud.google.com/sdk/docs/install](https://cloud.google.com/sdk/docs/install)
Inisialisasi dan autentikasi:
@ -102,7 +102,7 @@ Untuk alur Docker generik, lihat [Docker](/install/docker).
gcloud config set project my-openclaw-project
```
Aktifkan penagihan di [https://console.cloud.google.com/billing](https://console.cloud.google.com/billing) (diperlukan untuk Compute Engine).
Aktifkan billing di [https://console.cloud.google.com/billing](https://console.cloud.google.com/billing) (diperlukan untuk Compute Engine).
Aktifkan Compute Engine API:
@ -114,7 +114,7 @@ Untuk alur Docker generik, lihat [Docker](/install/docker).
1. Buka IAM & Admin > Create Project
2. Beri nama lalu buat
3. Aktifkan penagihan untuk project tersebut
3. Aktifkan billing untuk project
4. Buka APIs & Services > Enable APIs > cari "Compute Engine API" > Enable
</Step>
@ -122,11 +122,11 @@ Untuk alur Docker generik, lihat [Docker](/install/docker).
<Step title="Buat VM">
**Jenis mesin:**
| Type | Spesifikasi | Biaya | Catatan |
| Type | Specs | Cost | Notes |
| --------- | ------------------------ | ------------------ | -------------------------------------------- |
| e2-medium | 2 vCPU, 4GB RAM | ~$25/bulan | Paling andal untuk build Docker lokal |
| e2-small | 2 vCPU, 2GB RAM | ~$12/bulan | Minimum yang direkomendasikan untuk build Docker |
| e2-micro | 2 vCPU (shared), 1GB RAM | Memenuhi syarat free tier | Sering gagal karena OOM saat build Docker (exit 137) |
| e2-micro | 2 vCPU (shared), 1GB RAM | Memenuhi syarat free tier | Sering gagal dengan OOM build Docker (`exit 137`) |
**CLI:**
@ -145,7 +145,7 @@ Untuk alur Docker generik, lihat [Docker](/install/docker).
2. Nama: `openclaw-gateway`
3. Region: `us-central1`, Zone: `us-central1-a`
4. Jenis mesin: `e2-small`
5. Boot disk: Debian 12, 20GB
5. Disk boot: Debian 12, 20GB
6. Create
</Step>
@ -159,13 +159,13 @@ Untuk alur Docker generik, lihat [Docker](/install/docker).
**Console:**
Klik tombol "SSH" di sebelah VM Anda pada dashboard Compute Engine.
Klik tombol "SSH" di sebelah VM Anda di dashboard Compute Engine.
Catatan: propagasi kunci SSH dapat memakan waktu 1-2 menit setelah pembuatan VM. Jika koneksi ditolak, tunggu lalu coba lagi.
Catatan: propagasi kunci SSH dapat memerlukan 1-2 menit setelah pembuatan VM. Jika koneksi ditolak, tunggu lalu coba lagi.
</Step>
<Step title="Pasang Docker (di VM)">
<Step title="Instal Docker (di VM)">
```bash
sudo apt-get update
sudo apt-get install -y git curl ca-certificates
@ -194,19 +194,19 @@ Untuk alur Docker generik, lihat [Docker](/install/docker).
</Step>
<Step title="Clone repositori OpenClaw">
<Step title="Clone repository OpenClaw">
```bash
git clone https://github.com/openclaw/openclaw.git
cd openclaw
```
Panduan ini mengasumsikan Anda akan membangun image kustom untuk menjamin persistensi biner.
Panduan ini mengasumsikan Anda akan build image kustom untuk menjamin persistensi biner.
</Step>
<Step title="Buat direktori host persisten">
Container Docker bersifat ephemeral.
Semua state jangka panjang harus berada di host.
Semua status jangka panjang harus berada di host.
```bash
mkdir -p ~/.openclaw
@ -215,23 +215,26 @@ Untuk alur Docker generik, lihat [Docker](/install/docker).
</Step>
<Step title="Konfigurasikan variabel lingkungan">
Buat `.env` di root repositori.
<Step title="Konfigurasikan variabel environment">
Buat `.env` di root repository.
```bash
OPENCLAW_IMAGE=openclaw:latest
OPENCLAW_GATEWAY_TOKEN=change-me-now
OPENCLAW_GATEWAY_TOKEN=
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_GATEWAY_PORT=18789
OPENCLAW_CONFIG_DIR=/home/$USER/.openclaw
OPENCLAW_WORKSPACE_DIR=/home/$USER/.openclaw/workspace
GOG_KEYRING_PASSWORD=change-me-now
GOG_KEYRING_PASSWORD=
XDG_CONFIG_HOME=/home/node/.openclaw
```
Buat secret yang kuat:
Biarkan `OPENCLAW_GATEWAY_TOKEN` kosong kecuali Anda memang ingin
mengelolanya melalui `.env`; OpenClaw menulis token gateway acak ke
config saat pertama kali dijalankan. Buat kata sandi keyring dan tempelkan ke
`GOG_KEYRING_PASSWORD`:
```bash
openssl rand -hex 32
@ -239,9 +242,9 @@ Untuk alur Docker generik, lihat [Docker](/install/docker).
**Jangan commit file ini.**
File `.env` ini digunakan untuk env container/runtime seperti `OPENCLAW_GATEWAY_TOKEN`.
Auth OAuth/kunci API provider yang disimpan berada di
`~/.openclaw/agents/<agentId>/agent/auth-profiles.json` yang di-mount.
File `.env` ini untuk env container/runtime seperti `OPENCLAW_GATEWAY_TOKEN`.
Auth OAuth/API-key provider yang tersimpan berada di
`~/.openclaw/agents/<agentId>/agent/auth-profiles.json` yang dipasang.
</Step>
@ -270,8 +273,8 @@ Untuk alur Docker generik, lihat [Docker](/install/docker).
- ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
- ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
ports:
# Direkomendasikan: biarkan Gateway hanya loopback di VM; akses melalui SSH tunnel.
# Untuk mengeksposnya secara publik, hapus awalan `127.0.0.1:` dan konfigurasikan firewall sesuai kebutuhan.
# Direkomendasikan: biarkan Gateway hanya loopback pada VM; akses melalui tunnel SSH.
# Untuk mengeksposnya secara publik, hapus prefiks `127.0.0.1:` dan atur firewall sesuai kebutuhan.
- "127.0.0.1:${OPENCLAW_GATEWAY_PORT}:18789"
command:
[
@ -286,17 +289,17 @@ Untuk alur Docker generik, lihat [Docker](/install/docker).
]
```
`--allow-unconfigured` hanya untuk kemudahan bootstrap, bukan pengganti konfigurasi gateway yang benar. Tetap setel auth (`gateway.auth.token` atau password) dan gunakan pengaturan bind yang aman untuk deployment Anda.
`--allow-unconfigured` hanya untuk kemudahan bootstrap, ini bukan pengganti konfigurasi gateway yang benar. Tetap atur auth (`gateway.auth.token` atau password) dan gunakan pengaturan bind yang aman untuk deployment Anda.
</Step>
<Step title="Langkah runtime Docker VM bersama">
Gunakan panduan runtime bersama untuk alur host Docker umum:
- [Benamkan biner yang diperlukan ke dalam image](/install/docker-vm-runtime#bake-required-binaries-into-the-image)
- [Build dan jalankan](/install/docker-vm-runtime#build-and-launch)
- [Apa yang persisten di mana](/install/docker-vm-runtime#what-persists-where)
- [Pembaruan](/install/docker-vm-runtime#updates)
- [Sertakan biner yang diperlukan ke dalam image](/id/install/docker-vm-runtime#bake-required-binaries-into-the-image)
- [Build dan jalankan](/id/install/docker-vm-runtime#build-and-launch)
- [Apa yang persisten di mana](/id/install/docker-vm-runtime#what-persists-where)
- [Pembaruan](/id/install/docker-vm-runtime#updates)
</Step>
@ -309,12 +312,12 @@ Untuk alur Docker generik, lihat [Docker](/install/docker).
docker compose run --rm openclaw-cli config set gateway.controlUi.allowedOrigins '["http://127.0.0.1:18789"]' --strict-json
```
Jika Anda mengubah port gateway, ganti `18789` dengan port yang dikonfigurasi.
Jika Anda mengubah port gateway, ganti `18789` dengan port yang Anda konfigurasi.
</Step>
<Step title="Akses dari laptop Anda">
Buat SSH tunnel untuk meneruskan port Gateway:
Buat tunnel SSH untuk meneruskan port Gateway:
```bash
gcloud compute ssh openclaw-gateway --zone=us-central1-a -- -L 18789:127.0.0.1:18789
@ -331,7 +334,8 @@ Untuk alur Docker generik, lihat [Docker](/install/docker).
```
Jika UI meminta auth shared-secret, tempel token atau
password yang sudah dikonfigurasi ke pengaturan Control UI. Alur Docker ini secara default menulis token; jika Anda mengubah konfigurasi container ke auth berbasis password, gunakan
password yang telah dikonfigurasi ke pengaturan Control UI. Alur Docker ini menulis token secara
default; jika Anda mengubah konfigurasi container ke auth berbasis password, gunakan
password tersebut.
Jika Control UI menampilkan `unauthorized` atau `disconnected (1008): pairing required`, setujui perangkat browser:
@ -341,8 +345,8 @@ Untuk alur Docker generik, lihat [Docker](/install/docker).
docker compose run --rm openclaw-cli devices approve <requestId>
```
Butuh referensi persistensi bersama dan pembaruan lagi?
Lihat [Docker VM Runtime](/install/docker-vm-runtime#what-persists-where) dan [pembaruan Docker VM Runtime](/install/docker-vm-runtime#updates).
Perlu referensi persistensi bersama dan pembaruan lagi?
Lihat [Docker VM Runtime](/id/install/docker-vm-runtime#what-persists-where) dan [pembaruan Docker VM Runtime](/id/install/docker-vm-runtime#updates).
</Step>
</Steps>
@ -353,7 +357,7 @@ Untuk alur Docker generik, lihat [Docker](/install/docker).
**Koneksi SSH ditolak**
Propagasi kunci SSH dapat memakan waktu 1-2 menit setelah pembuatan VM. Tunggu lalu coba lagi.
Propagasi kunci SSH dapat memerlukan 1-2 menit setelah pembuatan VM. Tunggu lalu coba lagi.
**Masalah OS Login**
@ -367,7 +371,7 @@ Pastikan akun Anda memiliki izin IAM yang diperlukan (Compute OS Login atau Comp
**Kehabisan memori (OOM)**
Jika build Docker gagal dengan `Killed` dan `exit code 137`, VM dihentikan oleh OOM. Tingkatkan ke e2-small (minimum) atau e2-medium (direkomendasikan untuk build lokal yang andal):
Jika build Docker gagal dengan `Killed` dan `exit code 137`, VM dihentikan karena OOM. Tingkatkan ke `e2-small` (minimum) atau `e2-medium` (direkomendasikan untuk build lokal yang andal):
```bash
# Hentikan VM terlebih dahulu
@ -378,7 +382,7 @@ gcloud compute instances set-machine-type openclaw-gateway \
--zone=us-central1-a \
--machine-type=e2-small
# Mulai VM
# Jalankan VM
gcloud compute instances start openclaw-gateway --zone=us-central1-a
```
@ -388,7 +392,7 @@ gcloud compute instances start openclaw-gateway --zone=us-central1-a
Untuk penggunaan pribadi, akun pengguna default Anda sudah cukup.
Untuk otomasi atau pipeline CI/CD, buat service account khusus dengan izin minimum:
Untuk otomatisasi atau pipeline CI/CD, buat service account khusus dengan izin minimal:
1. Buat service account:
@ -405,14 +409,14 @@ Untuk otomasi atau pipeline CI/CD, buat service account khusus dengan izin minim
--role="roles/compute.instanceAdmin.v1"
```
Hindari menggunakan peran Owner untuk otomasi. Gunakan prinsip least privilege.
Hindari menggunakan peran Owner untuk otomatisasi. Gunakan prinsip hak istimewa minimum.
Lihat [https://cloud.google.com/iam/docs/understanding-roles](https://cloud.google.com/iam/docs/understanding-roles) untuk detail peran IAM.
---
## Langkah selanjutnya
## Langkah berikutnya
- Siapkan channel pesan: [Channels](/id/channels)
- Pasangkan perangkat lokal sebagai node: [Nodes](/nodes)
- Pasangkan perangkat lokal sebagai node: [Nodes](/id/nodes)
- Konfigurasikan Gateway: [Konfigurasi Gateway](/id/gateway/configuration)

View File

@ -1,16 +1,16 @@
---
read_when:
- Anda ingin OpenClaw berjalan 24/7 di cloud VPS (bukan laptop Anda)
- Anda menginginkan Gateway production-grade yang selalu aktif di VPS Anda sendiri
- Anda ingin OpenClaw berjalan 24/7 di VPS cloud (bukan laptop Anda)
- Anda menginginkan Gateway yang selalu aktif dan siap produksi di VPS Anda sendiri
- Anda menginginkan kontrol penuh atas persistensi, biner, dan perilaku restart
- Anda menjalankan OpenClaw di Docker pada Hetzner atau penyedia serupa
summary: Jalankan OpenClaw Gateway 24/7 di VPS Hetzner murah (Docker) dengan state yang tahan lama dan biner yang sudah tertanam
summary: Jalankan Gateway OpenClaw 24/7 di VPS Hetzner murah (Docker) dengan state yang tahan lama dan biner yang sudah disertakan
title: Hetzner
x-i18n:
generated_at: "2026-04-05T13:57:44Z"
generated_at: "2026-04-19T01:11:12Z"
model: gpt-5.4
provider: openai
source_hash: d859e4c0943040b022835f320708f879a11eadef70f2816cf0f2824eaaf165ef
source_hash: 32f5e552ea87970b89c762059bc27f22e0aa3abf001307cae8829b9f1c713a42
source_path: install/hetzner.md
workflow: 15
---
@ -19,38 +19,37 @@ x-i18n:
## Tujuan
Jalankan OpenClaw Gateway persisten di VPS Hetzner menggunakan Docker, dengan state yang tahan lama, biner yang sudah tertanam, dan perilaku restart yang aman.
Jalankan Gateway OpenClaw yang persisten di VPS Hetzner menggunakan Docker, dengan state yang tahan lama, biner yang sudah disertakan, dan perilaku restart yang aman.
Jika Anda menginginkan “OpenClaw 24/7 seharga ~$5”, ini adalah setup andal yang paling sederhana.
Harga Hetzner berubah-ubah; pilih VPS Debian/Ubuntu terkecil dan naikkan skala jika Anda mengalami OOM.
Jika Anda menginginkan “OpenClaw 24/7 seharga ~$5”, ini adalah pengaturan andal paling sederhana.
Harga Hetzner berubah-ubah; pilih VPS Debian/Ubuntu terkecil dan tingkatkan jika Anda mengalami OOM.
Pengingat model keamanan:
- Agen bersama untuk perusahaan tetap aman saat semua orang berada dalam trust boundary yang sama dan runtime hanya untuk bisnis.
- Pertahankan pemisahan ketat: VPS/runtime khusus + akun khusus; jangan gunakan profil Apple/Google/browser/password manager pribadi di host tersebut.
- Jika pengguna saling adversarial, pisahkan per gateway/host/pengguna OS.
- Agen yang dibagikan dalam perusahaan tidak masalah ketika semua orang berada dalam batas kepercayaan yang sama dan runtime hanya digunakan untuk bisnis.
- Pertahankan pemisahan yang ketat: VPS/runtime khusus + akun khusus; jangan gunakan profil Apple/Google/browser/password-manager pribadi di host tersebut.
- Jika pengguna saling berlawanan satu sama lain, pisahkan berdasarkan gateway/host/pengguna OS.
Lihat [Security](/gateway/security) dan [VPS hosting](/vps).
Lihat [Keamanan](/id/gateway/security) dan [hosting VPS](/id/vps).
## Apa yang kita lakukan (secara sederhana)?
## Apa yang kita lakukan (dalam istilah sederhana)?
- Menyewa server Linux kecil (VPS Hetzner)
- Menginstal Docker (runtime aplikasi terisolasi)
- Menjalankan OpenClaw Gateway di Docker
- Menjalankan Gateway OpenClaw di Docker
- Menyimpan `~/.openclaw` + `~/.openclaw/workspace` di host (tetap ada setelah restart/rebuild)
- Mengakses UI Kontrol dari laptop Anda melalui tunnel SSH
State `~/.openclaw` yang di-mount tersebut mencakup `openclaw.json`, `agents/<agentId>/agent/auth-profiles.json`
per agen, dan `.env`.
State `~/.openclaw` yang dimount tersebut mencakup `openclaw.json`, `agents/<agentId>/agent/auth-profiles.json` per agen, dan `.env`.
Gateway dapat diakses melalui:
- Port forwarding SSH dari laptop Anda
- SSH port forwarding dari laptop Anda
- Eksposur port langsung jika Anda mengelola firewall dan token sendiri
Panduan ini mengasumsikan Ubuntu atau Debian di Hetzner.
Jika Anda menggunakan Linux VPS lain, sesuaikan paketnya.
Untuk alur Docker umum, lihat [Docker](/install/docker).
Jika Anda menggunakan VPS Linux lain, sesuaikan paketnya.
Untuk alur Docker umum, lihat [Docker](/id/install/docker).
---
@ -61,24 +60,24 @@ Untuk alur Docker umum, lihat [Docker](/install/docker).
3. Clone repositori OpenClaw
4. Buat direktori host persisten
5. Konfigurasikan `.env` dan `docker-compose.yml`
6. Tertanamkan biner yang diperlukan ke dalam image
6. Sertakan biner yang diperlukan ke dalam image
7. `docker compose up -d`
8. Verifikasi persistensi dan akses Gateway
---
## Yang Anda butuhkan
## Yang Anda perlukan
- VPS Hetzner dengan akses root
- Akses SSH dari laptop Anda
- Pemahaman dasar tentang SSH + copy/paste
- Kenyamanan dasar menggunakan SSH + salin/tempel
- ~20 menit
- Docker dan Docker Compose
- Kredensial auth model
- Kredensial autentikasi model
- Kredensial penyedia opsional
- QR WhatsApp
- token bot Telegram
- OAuth Gmail
- Gmail OAuth
---
@ -124,35 +123,38 @@ Untuk alur Docker umum, lihat [Docker](/install/docker).
</Step>
<Step title="Buat direktori host persisten">
Container Docker bersifat ephemeral.
Semua state jangka panjang harus berada di host.
Kontainer Docker bersifat ephemeral.
Semua state jangka panjang harus disimpan di host.
```bash
mkdir -p /root/.openclaw/workspace
# Atur kepemilikan ke pengguna container (uid 1000):
# Set ownership ke pengguna kontainer (uid 1000):
chown -R 1000:1000 /root/.openclaw
```
</Step>
<Step title="Konfigurasikan variabel lingkungan">
<Step title="Konfigurasikan variabel environment">
Buat `.env` di root repositori.
```bash
OPENCLAW_IMAGE=openclaw:latest
OPENCLAW_GATEWAY_TOKEN=change-me-now
OPENCLAW_GATEWAY_TOKEN=
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_GATEWAY_PORT=18789
OPENCLAW_CONFIG_DIR=/root/.openclaw
OPENCLAW_WORKSPACE_DIR=/root/.openclaw/workspace
GOG_KEYRING_PASSWORD=change-me-now
GOG_KEYRING_PASSWORD=
XDG_CONFIG_HOME=/home/node/.openclaw
```
Buat secret yang kuat:
Biarkan `OPENCLAW_GATEWAY_TOKEN` kosong kecuali Anda secara eksplisit ingin
mengelolanya melalui `.env`; OpenClaw menulis token gateway acak ke
konfigurasi saat pertama kali dijalankan. Buat kata sandi keyring dan tempelkan ke
`GOG_KEYRING_PASSWORD`:
```bash
openssl rand -hex 32
@ -160,9 +162,9 @@ Untuk alur Docker umum, lihat [Docker](/install/docker).
**Jangan commit file ini.**
File `.env` ini untuk env container/runtime seperti `OPENCLAW_GATEWAY_TOKEN`.
Auth OAuth/API key penyedia yang disimpan berada di
`~/.openclaw/agents/<agentId>/agent/auth-profiles.json` yang di-mount.
File `.env` ini digunakan untuk env kontainer/runtime seperti `OPENCLAW_GATEWAY_TOKEN`.
Autentikasi OAuth/API-key penyedia yang disimpan berada di
`~/.openclaw/agents/<agentId>/agent/auth-profiles.json` yang dimount.
</Step>
@ -191,8 +193,8 @@ Untuk alur Docker umum, lihat [Docker](/install/docker).
- ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
- ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
ports:
# Direkomendasikan: pertahankan Gateway hanya loopback di VPS; akses melalui tunnel SSH.
# Untuk mengeksposnya secara publik, hapus prefiks `127.0.0.1:` dan atur firewall sesuai kebutuhan.
# Disarankan: pertahankan Gateway hanya loopback di VPS; akses melalui tunnel SSH.
# Untuk mengeksposnya secara publik, hapus prefix `127.0.0.1:` dan atur firewall dengan tepat.
- "127.0.0.1:${OPENCLAW_GATEWAY_PORT}:18789"
command:
[
@ -207,22 +209,22 @@ Untuk alur Docker umum, lihat [Docker](/install/docker).
]
```
`--allow-unconfigured` hanya untuk kemudahan bootstrap, bukan pengganti konfigurasi gateway yang benar. Tetap setel auth (`gateway.auth.token` atau password) dan gunakan pengaturan bind yang aman untuk deployment Anda.
`--allow-unconfigured` hanya untuk kemudahan bootstrap, ini bukan pengganti konfigurasi gateway yang benar. Tetap atur autentikasi (`gateway.auth.token` atau kata sandi) dan gunakan pengaturan bind yang aman untuk deployment Anda.
</Step>
<Step title="Langkah runtime Docker VM bersama">
<Step title="Langkah runtime VM Docker bersama">
Gunakan panduan runtime bersama untuk alur host Docker umum:
- [Tertanamkan biner yang diperlukan ke dalam image](/install/docker-vm-runtime#bake-required-binaries-into-the-image)
- [Build dan jalankan](/install/docker-vm-runtime#build-and-launch)
- [Apa yang persisten di mana](/install/docker-vm-runtime#what-persists-where)
- [Pembaruan](/install/docker-vm-runtime#updates)
- [Sertakan biner yang diperlukan ke dalam image](/id/install/docker-vm-runtime#bake-required-binaries-into-the-image)
- [Build and launch](/id/install/docker-vm-runtime#build-and-launch)
- [Apa yang persisten di mana](/id/install/docker-vm-runtime#what-persists-where)
- [Pembaruan](/id/install/docker-vm-runtime#updates)
</Step>
<Step title="Akses khusus Hetzner">
Setelah langkah build dan launch bersama selesai, buat tunnel dari laptop Anda:
Setelah langkah build dan launch bersama, buat tunnel dari laptop Anda:
```bash
ssh -N -L 18789:127.0.0.1:18789 root@YOUR_VPS_IP
@ -232,22 +234,21 @@ Untuk alur Docker umum, lihat [Docker](/install/docker).
`http://127.0.0.1:18789/`
Tempelkan shared secret yang dikonfigurasi. Panduan ini menggunakan token gateway
secara default; jika Anda beralih ke auth password, gunakan password tersebut.
Tempel shared secret yang telah dikonfigurasi. Panduan ini menggunakan token gateway secara default; jika Anda beralih ke autentikasi berbasis kata sandi, gunakan kata sandi tersebut.
</Step>
</Steps>
Peta persistensi bersama ada di [Docker VM Runtime](/install/docker-vm-runtime#what-persists-where).
Peta persistensi bersama tersedia di [Docker VM Runtime](/id/install/docker-vm-runtime#what-persists-where).
## Infrastructure as Code (Terraform)
Untuk tim yang lebih memilih alur infrastructure-as-code, setup Terraform yang dikelola komunitas menyediakan:
Untuk tim yang lebih memilih alur kerja infrastructure-as-code, pengaturan Terraform yang dipelihara komunitas menyediakan:
- Konfigurasi Terraform modular dengan manajemen remote state
- Konfigurasi Terraform modular dengan pengelolaan remote state
- Provisioning otomatis melalui cloud-init
- Skrip deployment (bootstrap, deploy, backup/restore)
- Hardening keamanan (firewall, UFW, akses SSH saja)
- Hardening keamanan (firewall, UFW, akses SSH-only)
- Konfigurasi tunnel SSH untuk akses gateway
**Repositori:**
@ -255,12 +256,12 @@ Untuk tim yang lebih memilih alur infrastructure-as-code, setup Terraform yang d
- Infrastruktur: [openclaw-terraform-hetzner](https://github.com/andreesg/openclaw-terraform-hetzner)
- Konfigurasi Docker: [openclaw-docker-config](https://github.com/andreesg/openclaw-docker-config)
Pendekatan ini melengkapi setup Docker di atas dengan deployment yang dapat direproduksi, infrastruktur yang dikendalikan versi, dan pemulihan bencana otomatis.
Pendekatan ini melengkapi pengaturan Docker di atas dengan deployment yang dapat direproduksi, infrastruktur yang dikontrol versinya, dan pemulihan bencana otomatis.
> **Catatan:** Dikelola oleh komunitas. Untuk masalah atau kontribusi, lihat tautan repositori di atas.
> **Catatan:** Dipelihara oleh komunitas. Untuk masalah atau kontribusi, lihat tautan repositori di atas.
## Langkah berikutnya
- Siapkan channel pesan: [Channels](/id/channels)
- Konfigurasikan Gateway: [Konfigurasi gateway](/id/gateway/configuration)
- Selalu perbarui OpenClaw: [Updating](/install/updating)
- Siapkan saluran pesan: [Channels](/id/channels)
- Konfigurasikan Gateway: [Konfigurasi Gateway](/id/gateway/configuration)
- Pastikan OpenClaw tetap terbaru: [Updating](/id/install/updating)

View File

@ -1,21 +1,21 @@
---
read_when:
- Anda sedang membangun plugin OpenClaw
- Anda perlu mengirimkan skema konfigurasi plugin atau men-debug kesalahan validasi plugin
summary: Persyaratan manifest Plugin + skema JSON (validasi konfigurasi ketat)
- Anda sedang membangun Plugin OpenClaw
- Anda perlu mengirimkan skema config Plugin atau men-debug error validasi Plugin
summary: Manifest Plugin + persyaratan skema JSON (validasi config ketat)
title: Manifest Plugin
x-i18n:
generated_at: "2026-04-15T09:14:46Z"
generated_at: "2026-04-19T01:11:10Z"
model: gpt-5.4
provider: openai
source_hash: ba2183bfa8802871e4ef33a0ebea290606e8351e9e83e25ee72456addb768730
source_hash: 2dfc00759108ddee7bfcda8c42acf7f2d47451676447ba3caf8b5950f8a1c181
source_path: plugins/manifest.md
workflow: 15
---
# Manifest Plugin (`openclaw.plugin.json`)
Halaman ini hanya untuk **manifest plugin OpenClaw native**.
Halaman ini hanya untuk **manifest Plugin OpenClaw native**.
Untuk tata letak bundle yang kompatibel, lihat [Bundle Plugin](/id/plugins/bundles).
@ -26,56 +26,49 @@ Format bundle yang kompatibel menggunakan file manifest yang berbeda:
default tanpa manifest
- Bundle Cursor: `.cursor-plugin/plugin.json`
OpenClaw juga mendeteksi otomatis tata letak bundle tersebut, tetapi tata letak itu tidak divalidasi
OpenClaw juga mendeteksi otomatis tata letak bundle tersebut, tetapi tidak divalidasi
terhadap skema `openclaw.plugin.json` yang dijelaskan di sini.
Untuk bundle yang kompatibel, OpenClaw saat ini membaca metadata bundle ditambah root
skill yang dideklarasikan, root perintah Claude, default `settings.json` bundle Claude,
default LSP bundle Claude, dan paket hook yang didukung saat tata letaknya sesuai
dengan ekspektasi runtime OpenClaw.
Untuk bundle yang kompatibel, OpenClaw saat ini membaca metadata bundle beserta root
skill yang dideklarasikan, root perintah Claude, default `settings.json` bundle
Claude, default LSP bundle Claude, dan paket hook yang didukung saat tata letaknya
sesuai dengan ekspektasi runtime OpenClaw.
Setiap plugin OpenClaw native **harus** menyertakan file `openclaw.plugin.json` di
Setiap Plugin OpenClaw native **harus** menyertakan file `openclaw.plugin.json` di
**root plugin**. OpenClaw menggunakan manifest ini untuk memvalidasi konfigurasi
**tanpa mengeksekusi kode plugin**. Manifest yang hilang atau tidak valid diperlakukan sebagai
kesalahan plugin dan memblokir validasi konfigurasi.
**tanpa mengeksekusi kode plugin**. Manifest yang hilang atau tidak valid diperlakukan
sebagai error plugin dan memblokir validasi config.
Lihat panduan lengkap sistem plugin: [Plugin](/id/tools/plugin).
Untuk model kapabilitas native dan panduan kompatibilitas eksternal saat ini:
[Model kapabilitas](/id/plugins/architecture#public-capability-model).
## Fungsi file ini
## Apa fungsi file ini
`openclaw.plugin.json` adalah metadata yang dibaca OpenClaw sebelum memuat
kode plugin Anda.
`openclaw.plugin.json` adalah metadata yang dibaca OpenClaw sebelum memuat kode
plugin Anda.
Gunakan untuk:
Gunakan file ini untuk:
- identitas plugin
- validasi konfigurasi
- metadata auth dan onboarding yang harus tersedia tanpa mem-boot runtime
plugin
- petunjuk aktivasi ringan yang dapat diperiksa oleh permukaan control-plane sebelum runtime
dimuat
- deskriptor penyiapan ringan yang dapat diperiksa oleh permukaan setup/onboarding sebelum
runtime dimuat
- validasi config
- metadata autentikasi dan onboarding yang harus tersedia tanpa mem-boot runtime plugin
- petunjuk aktivasi ringan yang dapat diperiksa oleh permukaan control-plane sebelum runtime dimuat
- deskriptor setup ringan yang dapat diperiksa oleh permukaan setup/onboarding sebelum runtime dimuat
- metadata alias dan auto-enable yang harus diselesaikan sebelum runtime plugin dimuat
- metadata kepemilikan keluarga model shorthand yang harus mengaktifkan otomatis
plugin sebelum runtime dimuat
- snapshot kepemilikan kapabilitas statis yang digunakan untuk wiring kompatibilitas bundle dan
cakupan kontrak
- metadata runner QA ringan yang dapat diperiksa oleh host bersama `openclaw qa`
sebelum runtime plugin dimuat
- metadata konfigurasi khusus channel yang harus digabungkan ke dalam katalog dan permukaan validasi
tanpa memuat runtime
- petunjuk UI konfigurasi
- metadata kepemilikan keluarga model singkat yang harus mengaktifkan plugin secara otomatis sebelum runtime dimuat
- snapshot kepemilikan kapabilitas statis yang digunakan untuk wiring kompatibilitas bundle dan cakupan kontrak
- metadata QA runner ringan yang dapat diperiksa host bersama `openclaw qa` sebelum runtime plugin dimuat
- metadata config khusus channel yang harus digabungkan ke permukaan katalog dan validasi tanpa memuat runtime
- petunjuk UI config
Jangan gunakan untuk:
Jangan gunakan file ini untuk:
- mendaftarkan perilaku runtime
- mendeklarasikan entrypoint kode
- metadata instalasi npm
Hal-hal tersebut termasuk dalam kode plugin Anda dan `package.json`.
Semua itu harus ditempatkan di kode plugin Anda dan `package.json`.
## Contoh minimal
@ -96,13 +89,20 @@ Hal-hal tersebut termasuk dalam kode plugin Anda dan `package.json`.
{
"id": "openrouter",
"name": "OpenRouter",
"description": "Plugin provider OpenRouter",
"description": "OpenRouter provider plugin",
"version": "1.0.0",
"providers": ["openrouter"],
"modelSupport": {
"modelPrefixes": ["router-"]
},
"providerEndpoints": [
{
"endpointClass": "xai-native",
"hosts": ["api.x.ai"]
}
],
"cliBackends": ["openrouter-cli"],
"syntheticAuthRefs": ["openrouter-cli"],
"providerAuthEnvVars": {
"openrouter": ["OPENROUTER_API_KEY"]
},
@ -117,19 +117,19 @@ Hal-hal tersebut termasuk dalam kode plugin Anda dan `package.json`.
"provider": "openrouter",
"method": "api-key",
"choiceId": "openrouter-api-key",
"choiceLabel": "Kunci API OpenRouter",
"choiceLabel": "OpenRouter API key",
"groupId": "openrouter",
"groupLabel": "OpenRouter",
"optionKey": "openrouterApiKey",
"cliFlag": "--openrouter-api-key",
"cliOption": "--openrouter-api-key <key>",
"cliDescription": "Kunci API OpenRouter",
"cliDescription": "OpenRouter API key",
"onboardingScopes": ["text-inference"]
}
],
"uiHints": {
"apiKey": {
"label": "Kunci API",
"label": "API key",
"placeholder": "sk-or-v1-...",
"sensitive": true
}
@ -150,61 +150,65 @@ Hal-hal tersebut termasuk dalam kode plugin Anda dan `package.json`.
| Field | Wajib | Tipe | Artinya |
| ----------------------------------- | -------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | Ya | `string` | Id plugin kanonis. Ini adalah id yang digunakan di `plugins.entries.<id>`. |
| `configSchema` | Ya | `object` | JSON Schema inline untuk konfigurasi plugin ini. |
| `enabledByDefault` | Tidak | `true` | Menandai plugin bundle sebagai aktif secara default. Hilangkan field ini, atau setel ke nilai apa pun selain `true`, agar plugin tetap nonaktif secara default. |
| `legacyPluginIds` | Tidak | `string[]` | Id lawas yang dinormalisasi ke id plugin kanonis ini. |
| `autoEnableWhenConfiguredProviders` | Tidak | `string[]` | Id provider yang harus mengaktifkan plugin ini secara otomatis saat auth, konfigurasi, atau referensi model menyebutkannya. |
| `kind` | Tidak | `"memory"` \| `"context-engine"` | Mendeklarasikan jenis plugin eksklusif yang digunakan oleh `plugins.slots.*`. |
| `channels` | Tidak | `string[]` | Id channel yang dimiliki plugin ini. Digunakan untuk discovery dan validasi konfigurasi. |
| `providers` | Tidak | `string[]` | Id provider yang dimiliki plugin ini. |
| `modelSupport` | Tidak | `object` | Metadata keluarga model shorthand milik manifest yang digunakan untuk memuat otomatis plugin sebelum runtime. |
| `cliBackends` | Tidak | `string[]` | Id backend inferensi CLI yang dimiliki plugin ini. Digunakan untuk auto-aktivasi saat startup dari referensi konfigurasi eksplisit. |
| `commandAliases` | Tidak | `object[]` | Nama perintah yang dimiliki plugin ini yang harus menghasilkan diagnostik konfigurasi dan CLI yang sadar-plugin sebelum runtime dimuat. |
| `providerAuthEnvVars` | Tidak | `Record<string, string[]>` | Metadata env auth provider ringan yang dapat diperiksa OpenClaw tanpa memuat kode plugin. |
| `providerAuthAliases` | Tidak | `Record<string, string>` | Id provider yang harus memakai ulang id provider lain untuk pencarian auth, misalnya provider coding yang berbagi kunci API provider dasar dan profil auth. |
| `channelEnvVars` | Tidak | `Record<string, string[]>` | Metadata env channel ringan yang dapat diperiksa OpenClaw tanpa memuat kode plugin. Gunakan ini untuk penyiapan channel berbasis env atau permukaan auth yang perlu dilihat helper startup/konfigurasi umum. |
| `providerAuthChoices` | Tidak | `object[]` | Metadata pilihan auth ringan untuk pemilih onboarding, resolusi provider yang diprioritaskan, dan wiring flag CLI sederhana. |
| `activation` | Tidak | `object` | Petunjuk aktivasi ringan untuk pemuatan yang dipicu provider, perintah, channel, rute, dan kapabilitas. Hanya metadata; runtime plugin tetap memiliki perilaku sebenarnya. |
| `id` | Ya | `string` | ID Plugin kanonis. Ini adalah ID yang digunakan dalam `plugins.entries.<id>`. |
| `configSchema` | Ya | `object` | JSON Schema inline untuk config Plugin ini. |
| `enabledByDefault` | Tidak | `true` | Menandai Plugin bundle sebagai aktif secara default. Hilangkan field ini, atau tetapkan nilai apa pun selain `true`, agar Plugin tetap nonaktif secara default. |
| `legacyPluginIds` | Tidak | `string[]` | ID lama yang dinormalisasi ke ID Plugin kanonis ini. |
| `autoEnableWhenConfiguredProviders` | Tidak | `string[]` | ID provider yang harus mengaktifkan Plugin ini secara otomatis saat auth, config, atau referensi model menyebutkannya. |
| `kind` | Tidak | `"memory"` \| `"context-engine"` | Mendeklarasikan jenis Plugin eksklusif yang digunakan oleh `plugins.slots.*`. |
| `channels` | Tidak | `string[]` | ID channel yang dimiliki oleh Plugin ini. Digunakan untuk discovery dan validasi config. |
| `providers` | Tidak | `string[]` | ID provider yang dimiliki oleh Plugin ini. |
| `modelSupport` | Tidak | `object` | Metadata singkat keluarga model milik manifest yang digunakan untuk memuat otomatis Plugin sebelum runtime. |
| `providerEndpoints` | Tidak | `object[]` | Metadata host/baseUrl endpoint milik manifest untuk rute provider yang harus diklasifikasikan oleh core sebelum runtime provider dimuat. |
| `cliBackends` | Tidak | `string[]` | ID backend inferensi CLI yang dimiliki oleh Plugin ini. Digunakan untuk aktivasi otomatis saat startup dari referensi config eksplisit. |
| `syntheticAuthRefs` | Tidak | `string[]` | Referensi provider atau backend CLI yang hook auth sintetis milik Plugin-nya harus diperiksa selama discovery model cold path sebelum runtime dimuat. |
| `nonSecretAuthMarkers` | Tidak | `string[]` | Nilai placeholder API key milik Plugin bundle yang merepresentasikan status kredensial lokal, OAuth, atau ambient yang bukan rahasia. |
| `commandAliases` | Tidak | `object[]` | Nama perintah yang dimiliki oleh Plugin ini yang harus menghasilkan diagnostik config dan CLI yang sadar-Plugin sebelum runtime dimuat. |
| `providerAuthEnvVars` | Tidak | `Record<string, string[]>` | Metadata env auth provider ringan yang dapat diperiksa OpenClaw tanpa memuat kode plugin. |
| `providerAuthAliases` | Tidak | `Record<string, string>` | ID provider yang harus menggunakan ulang ID provider lain untuk pencarian auth, misalnya provider coding yang berbagi API key provider dasar dan profil auth yang sama. |
| `channelEnvVars` | Tidak | `Record<string, string[]>` | Metadata env channel ringan yang dapat diperiksa OpenClaw tanpa memuat kode plugin. Gunakan ini untuk permukaan setup atau auth channel berbasis env yang perlu dilihat helper startup/config generik. |
| `providerAuthChoices` | Tidak | `object[]` | Metadata pilihan auth ringan untuk picker onboarding, resolusi provider pilihan, dan wiring flag CLI sederhana. |
| `activation` | Tidak | `object` | Petunjuk aktivasi ringan untuk pemuatan yang dipicu oleh provider, perintah, channel, rute, dan kapabilitas. Hanya metadata; runtime plugin tetap memiliki perilaku sebenarnya. |
| `setup` | Tidak | `object` | Deskriptor setup/onboarding ringan yang dapat diperiksa oleh permukaan discovery dan setup tanpa memuat runtime plugin. |
| `qaRunners` | Tidak | `object[]` | Deskriptor runner QA ringan yang digunakan oleh host bersama `openclaw qa` sebelum runtime plugin dimuat. |
| `contracts` | Tidak | `object` | Snapshot kapabilitas bundle statis untuk kepemilikan speech, transkripsi realtime, suara realtime, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search, dan tool. |
| `channelConfigs` | Tidak | `Record<string, object>` | Metadata konfigurasi channel milik manifest yang digabungkan ke dalam permukaan discovery dan validasi sebelum runtime dimuat. |
| `skills` | Tidak | `string[]` | Direktori Skills yang akan dimuat, relatif terhadap root plugin. |
| `name` | Tidak | `string` | Nama plugin yang dapat dibaca manusia. |
| `qaRunners` | Tidak | `object[]` | Deskriptor QA runner ringan yang digunakan oleh host bersama `openclaw qa` sebelum runtime plugin dimuat. |
| `contracts` | Tidak | `object` | Snapshot kapabilitas bundle statis untuk kepemilikan speech, transkripsi realtime, voice realtime, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search, dan tool. |
| `channelConfigs` | Tidak | `Record<string, object>` | Metadata config channel milik manifest yang digabungkan ke permukaan discovery dan validasi sebelum runtime dimuat. |
| `skills` | Tidak | `string[]` | Direktori Skills yang akan dimuat, relatif terhadap root plugin. |
| `name` | Tidak | `string` | Nama Plugin yang dapat dibaca manusia. |
| `description` | Tidak | `string` | Ringkasan singkat yang ditampilkan di permukaan plugin. |
| `version` | Tidak | `string` | Versi plugin untuk keperluan informasional. |
| `uiHints` | Tidak | `Record<string, object>` | Label UI, placeholder, dan petunjuk sensitivitas untuk field konfigurasi. |
| `version` | Tidak | `string` | Versi Plugin informasional. |
| `uiHints` | Tidak | `Record<string, object>` | Label UI, placeholder, dan petunjuk sensitivitas untuk field config. |
## Referensi `providerAuthChoices`
Setiap entri `providerAuthChoices` mendeskripsikan satu pilihan onboarding atau auth.
Setiap entri `providerAuthChoices` menjelaskan satu pilihan onboarding atau auth.
OpenClaw membaca ini sebelum runtime provider dimuat.
| Field | Wajib | Tipe | Artinya |
| --------------------- | -------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `provider` | Ya | `string` | Id provider tempat pilihan ini berada. |
| `method` | Ya | `string` | Id metode auth yang akan digunakan untuk dispatch. |
| `choiceId` | Ya | `string` | Id pilihan auth stabil yang digunakan oleh alur onboarding dan CLI. |
| `choiceLabel` | Tidak | `string` | Label yang ditampilkan ke pengguna. Jika dihilangkan, OpenClaw akan menggunakan `choiceId` sebagai fallback. |
| `choiceHint` | Tidak | `string` | Teks bantuan singkat untuk pemilih. |
| `assistantPriority` | Tidak | `number` | Nilai yang lebih rendah diurutkan lebih awal dalam pemilih interaktif yang digerakkan asisten. |
| `assistantVisibility` | Tidak | `"visible"` \| `"manual-only"` | Menyembunyikan pilihan dari pemilih asisten sambil tetap mengizinkan pemilihan CLI manual. |
| `deprecatedChoiceIds` | Tidak | `string[]` | Id pilihan lawas yang harus mengarahkan pengguna ke pilihan pengganti ini. |
| `groupId` | Tidak | `string` | Id grup opsional untuk mengelompokkan pilihan yang terkait. |
| `groupLabel` | Tidak | `string` | Label yang ditampilkan ke pengguna untuk grup tersebut. |
| `groupHint` | Tidak | `string` | Teks bantuan singkat untuk grup. |
| `optionKey` | Tidak | `string` | Kunci opsi internal untuk alur auth sederhana dengan satu flag. |
| `cliFlag` | Tidak | `string` | Nama flag CLI, seperti `--openrouter-api-key`. |
| `cliOption` | Tidak | `string` | Bentuk opsi CLI lengkap, seperti `--openrouter-api-key <key>`. |
| `cliDescription` | Tidak | `string` | Deskripsi yang digunakan dalam bantuan CLI. |
| Field | Wajib | Tipe | Artinya |
| --------------------- | -------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `provider` | Ya | `string` | ID provider tempat pilihan ini berada. |
| `method` | Ya | `string` | ID metode auth yang akan digunakan untuk dispatch. |
| `choiceId` | Ya | `string` | ID pilihan auth stabil yang digunakan oleh alur onboarding dan CLI. |
| `choiceLabel` | Tidak | `string` | Label untuk pengguna. Jika dihilangkan, OpenClaw akan menggunakan `choiceId`. |
| `choiceHint` | Tidak | `string` | Teks bantuan singkat untuk picker. |
| `assistantPriority` | Tidak | `number` | Nilai yang lebih rendah diurutkan lebih awal dalam picker interaktif yang digerakkan asisten. |
| `assistantVisibility` | Tidak | `"visible"` \| `"manual-only"` | Sembunyikan pilihan dari picker asisten sambil tetap mengizinkan pemilihan CLI manual. |
| `deprecatedChoiceIds` | Tidak | `string[]` | ID pilihan lama yang harus mengarahkan pengguna ke pilihan pengganti ini. |
| `groupId` | Tidak | `string` | ID grup opsional untuk mengelompokkan pilihan yang terkait. |
| `groupLabel` | Tidak | `string` | Label untuk pengguna bagi grup tersebut. |
| `groupHint` | Tidak | `string` | Teks bantuan singkat untuk grup tersebut. |
| `optionKey` | Tidak | `string` | Kunci opsi internal untuk alur auth sederhana dengan satu flag. |
| `cliFlag` | Tidak | `string` | Nama flag CLI, seperti `--openrouter-api-key`. |
| `cliOption` | Tidak | `string` | Bentuk opsi CLI lengkap, seperti `--openrouter-api-key <key>`. |
| `cliDescription` | Tidak | `string` | Deskripsi yang digunakan dalam bantuan CLI. |
| `onboardingScopes` | Tidak | `Array<"text-inference" \| "image-generation">` | Permukaan onboarding tempat pilihan ini harus muncul. Jika dihilangkan, default-nya adalah `["text-inference"]`. |
## Referensi `commandAliases`
Gunakan `commandAliases` saat sebuah plugin memiliki nama perintah runtime yang mungkin
secara keliru dimasukkan pengguna ke dalam `plugins.allow` atau dicoba dijalankan sebagai
perintah CLI root. OpenClaw menggunakan metadata ini untuk diagnostik tanpa mengimpor kode runtime plugin.
Gunakan `commandAliases` saat sebuah Plugin memiliki nama perintah runtime yang
mungkin keliru dimasukkan pengguna ke `plugins.allow` atau coba dijalankan
sebagai perintah CLI root. OpenClaw menggunakan metadata ini untuk diagnostik
tanpa mengimpor kode runtime plugin.
```json
{
@ -218,45 +222,46 @@ perintah CLI root. OpenClaw menggunakan metadata ini untuk diagnostik tanpa meng
}
```
| Field | Wajib | Tipe | Artinya |
| ------------ | -------- | ----------------- | ------------------------------------------------------------------------ |
| `name` | Ya | `string` | Nama perintah yang dimiliki oleh plugin ini. |
| `kind` | Tidak | `"runtime-slash"` | Menandai alias sebagai perintah slash chat, bukan perintah CLI root. |
| `cliCommand` | Tidak | `string` | Perintah CLI root terkait yang disarankan untuk operasi CLI, jika ada. |
| Field | Wajib | Tipe | Artinya |
| ------------ | -------- | ----------------- | ------------------------------------------------------------------------- |
| `name` | Ya | `string` | Nama perintah yang dimiliki oleh Plugin ini. |
| `kind` | Tidak | `"runtime-slash"` | Menandai alias sebagai perintah slash chat, bukan perintah CLI root. |
| `cliCommand` | Tidak | `string` | Perintah CLI root terkait yang disarankan untuk operasi CLI, jika ada. |
## Referensi `activation`
Gunakan `activation` saat plugin dapat secara ringan mendeklarasikan event control-plane mana
yang seharusnya mengaktifkannya nanti.
Gunakan `activation` saat Plugin dapat mendeklarasikan secara ringan peristiwa
control-plane mana yang seharusnya mengaktifkannya nanti.
## Referensi `qaRunners`
Gunakan `qaRunners` saat sebuah plugin menyumbangkan satu atau lebih runner transport di bawah
root bersama `openclaw qa`. Pertahankan metadata ini tetap ringan dan statis; runtime plugin
tetap memiliki registrasi CLI yang sebenarnya melalui permukaan `runtime-api.ts`
ringan yang mengekspor `qaRunnerCliRegistrations`.
Gunakan `qaRunners` saat sebuah Plugin menyediakan satu atau lebih transport runner
di bawah root bersama `openclaw qa`. Jaga metadata ini tetap ringan dan statis;
runtime plugin tetap memiliki registrasi CLI sebenarnya melalui permukaan
`runtime-api.ts` yang ringan dan mengekspor `qaRunnerCliRegistrations`.
```json
{
"qaRunners": [
{
"commandName": "matrix",
"description": "Jalankan lane QA live Matrix berbasis Docker terhadap homeserver sementara"
"description": "Jalankan lane QA live Matrix berbasis Docker terhadap homeserver disposable"
}
]
}
```
| Field | Wajib | Tipe | Artinya |
| ------------- | -------- | -------- | ------------------------------------------------------------------ |
| Field | Wajib | Tipe | Artinya |
| ------------- | -------- | -------- | -------------------------------------------------------------------- |
| `commandName` | Ya | `string` | Subperintah yang dipasang di bawah `openclaw qa`, misalnya `matrix`. |
| `description` | Tidak | `string` | Teks bantuan fallback yang digunakan saat host bersama memerlukan perintah stub. |
| `description` | Tidak | `string` | Teks bantuan cadangan yang digunakan saat host bersama memerlukan perintah stub. |
Blok ini hanya metadata. Blok ini tidak mendaftarkan perilaku runtime, dan juga
tidak menggantikan `register(...)`, `setupEntry`, atau entrypoint runtime/plugin lainnya.
Konsumen saat ini menggunakannya sebagai petunjuk penyempitan sebelum pemuatan plugin yang lebih luas, jadi
metadata activation yang hilang biasanya hanya berdampak pada performa; hal itu seharusnya tidak
mengubah kebenaran selama fallback kepemilikan manifest lawas masih ada.
Blok ini hanya metadata. Blok ini tidak mendaftarkan perilaku runtime, dan
tidak menggantikan `register(...)`, `setupEntry`, atau entrypoint runtime/plugin
lainnya. Konsumen saat ini menggunakannya sebagai petunjuk penyempitan sebelum
pemuatan plugin yang lebih luas, jadi metadata activation yang hilang biasanya
hanya berdampak pada performa; seharusnya tidak mengubah correctness selama fallback
kepemilikan manifest lama masih ada.
```json
{
@ -270,28 +275,28 @@ mengubah kebenaran selama fallback kepemilikan manifest lawas masih ada.
}
```
| Field | Wajib | Tipe | Artinya |
| ---------------- | -------- | ---------------------------------------------------- | ------------------------------------------------------------------ |
| `onProviders` | Tidak | `string[]` | Id provider yang harus mengaktifkan plugin ini saat diminta. |
| `onCommands` | Tidak | `string[]` | Id perintah yang harus mengaktifkan plugin ini. |
| `onChannels` | Tidak | `string[]` | Id channel yang harus mengaktifkan plugin ini. |
| `onRoutes` | Tidak | `string[]` | Jenis rute yang harus mengaktifkan plugin ini. |
| Field | Wajib | Tipe | Artinya |
| ---------------- | -------- | ---------------------------------------------------- | ------------------------------------------------------------------- |
| `onProviders` | Tidak | `string[]` | ID provider yang harus mengaktifkan Plugin ini saat diminta. |
| `onCommands` | Tidak | `string[]` | ID perintah yang harus mengaktifkan Plugin ini. |
| `onChannels` | Tidak | `string[]` | ID channel yang harus mengaktifkan Plugin ini. |
| `onRoutes` | Tidak | `string[]` | Jenis rute yang harus mengaktifkan Plugin ini. |
| `onCapabilities` | Tidak | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Petunjuk kapabilitas luas yang digunakan oleh perencanaan aktivasi control-plane. |
Konsumen live saat ini:
- perencanaan CLI yang dipicu perintah menggunakan fallback ke
`commandAliases[].cliCommand` atau `commandAliases[].name` lawas
- perencanaan setup/channel yang dipicu channel menggunakan fallback ke kepemilikan
`channels[]` lawas saat metadata aktivasi channel eksplisit tidak ada
- perencanaan setup/runtime yang dipicu provider menggunakan fallback ke
kepemilikan `providers[]` dan `cliBackends[]` tingkat atas lawas saat metadata aktivasi provider eksplisit
tidak ada
- perencanaan CLI yang dipicu perintah melakukan fallback ke
`commandAliases[].cliCommand` atau `commandAliases[].name` lama
- perencanaan setup/channel yang dipicu channel melakukan fallback ke kepemilikan
`channels[]` lama saat metadata aktivasi channel eksplisit tidak ada
- perencanaan setup/runtime yang dipicu provider melakukan fallback ke kepemilikan
`providers[]` lama dan `cliBackends[]` tingkat atas saat metadata aktivasi provider
eksplisit tidak ada
## Referensi `setup`
Gunakan `setup` saat permukaan setup dan onboarding memerlukan metadata milik plugin yang ringan
sebelum runtime dimuat.
Gunakan `setup` saat permukaan setup dan onboarding memerlukan metadata milik Plugin
yang ringan sebelum runtime dimuat.
```json
{
@ -310,47 +315,47 @@ sebelum runtime dimuat.
}
```
`cliBackends` tingkat atas tetap valid dan terus mendeskripsikan backend inferensi
CLI. `setup.cliBackends` adalah permukaan deskriptor khusus setup untuk
alur control-plane/setup yang harus tetap hanya berupa metadata.
`cliBackends` tingkat atas tetap valid dan terus menjelaskan backend inferensi
CLI. `setup.cliBackends` adalah permukaan deskriptor khusus setup untuk alur
control-plane/setup yang harus tetap hanya berupa metadata.
Jika ada, `setup.providers` dan `setup.cliBackends` adalah permukaan pencarian
utama berbasis deskriptor untuk discovery setup. Jika deskriptor hanya
mempersempit kandidat plugin dan setup masih memerlukan hook runtime saat setup
yang lebih kaya, setel `requiresRuntime: true` dan tetap pertahankan `setup-api`
Jika ada, `setup.providers` dan `setup.cliBackends` adalah permukaan lookup
berbasis deskriptor yang diutamakan untuk discovery setup. Jika deskriptor hanya
mempersempit kandidat Plugin dan setup masih membutuhkan hook runtime waktu-setup
yang lebih kaya, tetapkan `requiresRuntime: true` dan pertahankan `setup-api`
sebagai jalur eksekusi fallback.
Karena pencarian setup dapat mengeksekusi kode `setup-api` milik plugin, nilai
`setup.providers[].id` dan `setup.cliBackends[]` yang telah dinormalisasi harus tetap unik di seluruh
plugin yang ditemukan. Kepemilikan yang ambigu akan gagal secara tertutup alih-alih memilih
pemenang berdasarkan urutan discovery.
Karena lookup setup dapat mengeksekusi kode `setup-api` milik Plugin, nilai
`setup.providers[].id` dan `setup.cliBackends[]` yang telah dinormalisasi harus
tetap unik di seluruh Plugin yang ditemukan. Kepemilikan ambigu akan gagal
tertutup alih-alih memilih pemenang berdasarkan urutan discovery.
### Referensi `setup.providers`
| Field | Wajib | Tipe | Artinya |
| ------------- | -------- | ---------- | ------------------------------------------------------------------------------------ |
| `id` | Ya | `string` | Id provider yang diekspos saat setup atau onboarding. Pertahankan id yang dinormalisasi tetap unik secara global. |
| `authMethods` | Tidak | `string[]` | Id metode setup/auth yang didukung provider ini tanpa memuat runtime penuh. |
| `envVars` | Tidak | `string[]` | Env vars yang dapat diperiksa oleh permukaan setup/status umum sebelum runtime plugin dimuat. |
| Field | Wajib | Tipe | Artinya |
| ------------- | -------- | ---------- | ---------------------------------------------------------------------------------- |
| `id` | Ya | `string` | ID provider yang diekspos selama setup atau onboarding. Jaga agar ID ternormalisasi tetap unik secara global. |
| `authMethods` | Tidak | `string[]` | ID metode setup/auth yang didukung provider ini tanpa memuat runtime penuh. |
| `envVars` | Tidak | `string[]` | Env var yang dapat diperiksa oleh permukaan setup/status generik sebelum runtime plugin dimuat. |
### Field `setup`
| Field | Wajib | Tipe | Artinya |
| ------------------ | -------- | ---------- | ------------------------------------------------------------------------------------------------ |
| `providers` | Tidak | `object[]` | Deskriptor setup provider yang diekspos selama setup dan onboarding. |
| `cliBackends` | Tidak | `string[]` | Id backend saat setup yang digunakan untuk pencarian setup berbasis deskriptor. Pertahankan id yang dinormalisasi tetap unik secara global. |
| `configMigrations` | Tidak | `string[]` | Id migrasi konfigurasi yang dimiliki oleh permukaan setup plugin ini. |
| `requiresRuntime` | Tidak | `boolean` | Apakah setup masih memerlukan eksekusi `setup-api` setelah pencarian deskriptor. |
| Field | Wajib | Tipe | Artinya |
| ------------------ | -------- | ---------- | --------------------------------------------------------------------------------------------------- |
| `providers` | Tidak | `object[]` | Deskriptor setup provider yang diekspos selama setup dan onboarding. |
| `cliBackends` | Tidak | `string[]` | ID backend waktu-setup yang digunakan untuk lookup setup berbasis deskriptor. Jaga agar ID ternormalisasi tetap unik secara global. |
| `configMigrations` | Tidak | `string[]` | ID migrasi config yang dimiliki oleh permukaan setup Plugin ini. |
| `requiresRuntime` | Tidak | `boolean` | Apakah setup masih memerlukan eksekusi `setup-api` setelah lookup deskriptor. |
## Referensi `uiHints`
`uiHints` adalah peta dari nama field konfigurasi ke petunjuk rendering kecil.
`uiHints` adalah map dari nama field config ke petunjuk rendering kecil.
```json
{
"uiHints": {
"apiKey": {
"label": "Kunci API",
"label": "API key",
"help": "Digunakan untuk permintaan OpenRouter",
"placeholder": "sk-or-v1-...",
"sensitive": true
@ -361,14 +366,14 @@ pemenang berdasarkan urutan discovery.
Setiap petunjuk field dapat mencakup:
| Field | Tipe | Artinya |
| ------------- | ---------- | --------------------------------------- |
| `label` | `string` | Label field yang ditampilkan ke pengguna. |
| `help` | `string` | Teks bantuan singkat. |
| `tags` | `string[]` | Tag UI opsional. |
| `advanced` | `boolean` | Menandai field sebagai lanjutan. |
| Field | Tipe | Artinya |
| ------------- | ---------- | ---------------------------------------- |
| `label` | `string` | Label field untuk pengguna. |
| `help` | `string` | Teks bantuan singkat. |
| `tags` | `string[]` | Tag UI opsional. |
| `advanced` | `boolean` | Menandai field sebagai lanjutan. |
| `sensitive` | `boolean` | Menandai field sebagai rahasia atau sensitif. |
| `placeholder` | `string` | Teks placeholder untuk input formulir. |
| `placeholder` | `string` | Teks placeholder untuk input formulir. |
## Referensi `contracts`
@ -393,22 +398,22 @@ dibaca OpenClaw tanpa mengimpor runtime plugin.
Setiap daftar bersifat opsional:
| Field | Tipe | Artinya |
| -------------------------------- | ---------- | ---------------------------------------------------------------- |
| `speechProviders` | `string[]` | Id provider speech yang dimiliki plugin ini. |
| `realtimeTranscriptionProviders` | `string[]` | Id provider transkripsi realtime yang dimiliki plugin ini. |
| `realtimeVoiceProviders` | `string[]` | Id provider suara realtime yang dimiliki plugin ini. |
| `mediaUnderstandingProviders` | `string[]` | Id provider media-understanding yang dimiliki plugin ini. |
| `imageGenerationProviders` | `string[]` | Id provider image-generation yang dimiliki plugin ini. |
| `videoGenerationProviders` | `string[]` | Id provider video-generation yang dimiliki plugin ini. |
| `webFetchProviders` | `string[]` | Id provider web-fetch yang dimiliki plugin ini. |
| `webSearchProviders` | `string[]` | Id provider web search yang dimiliki plugin ini. |
| `tools` | `string[]` | Nama tool agen yang dimiliki plugin ini untuk pemeriksaan kontrak bundle. |
| Field | Tipe | Artinya |
| -------------------------------- | ---------- | ------------------------------------------------------------ |
| `speechProviders` | `string[]` | ID provider speech yang dimiliki oleh Plugin ini. |
| `realtimeTranscriptionProviders` | `string[]` | ID provider transkripsi realtime yang dimiliki oleh Plugin ini. |
| `realtimeVoiceProviders` | `string[]` | ID provider voice realtime yang dimiliki oleh Plugin ini. |
| `mediaUnderstandingProviders` | `string[]` | ID provider media-understanding yang dimiliki oleh Plugin ini. |
| `imageGenerationProviders` | `string[]` | ID provider image-generation yang dimiliki oleh Plugin ini. |
| `videoGenerationProviders` | `string[]` | ID provider video-generation yang dimiliki oleh Plugin ini. |
| `webFetchProviders` | `string[]` | ID provider web-fetch yang dimiliki oleh Plugin ini. |
| `webSearchProviders` | `string[]` | ID provider web search yang dimiliki oleh Plugin ini. |
| `tools` | `string[]` | Nama tool agent yang dimiliki oleh Plugin ini untuk pemeriksaan kontrak bundle. |
## Referensi `channelConfigs`
Gunakan `channelConfigs` saat plugin channel memerlukan metadata konfigurasi ringan sebelum
runtime dimuat.
Gunakan `channelConfigs` saat sebuah Plugin channel memerlukan metadata config
ringan sebelum runtime dimuat.
```json
{
@ -423,7 +428,7 @@ runtime dimuat.
},
"uiHints": {
"homeserverUrl": {
"label": "URL homeserver",
"label": "Homeserver URL",
"placeholder": "https://matrix.example.com"
}
},
@ -438,17 +443,17 @@ runtime dimuat.
Setiap entri channel dapat mencakup:
| Field | Tipe | Artinya |
| ------------- | ------------------------ | ----------------------------------------------------------------------------------------- |
| `schema` | `object` | JSON Schema untuk `channels.<id>`. Wajib untuk setiap entri konfigurasi channel yang dideklarasikan. |
| `uiHints` | `Record<string, object>` | Label UI/placeholder/petunjuk sensitif opsional untuk bagian konfigurasi channel tersebut. |
| `label` | `string` | Label channel yang digabungkan ke dalam permukaan pemilih dan inspeksi saat metadata runtime belum siap. |
| `description` | `string` | Deskripsi channel singkat untuk permukaan inspeksi dan katalog. |
| `preferOver` | `string[]` | Id plugin lawas atau berprioritas lebih rendah yang harus dikalahkan channel ini dalam permukaan pemilihan. |
| ------------- | ------------------------ | ---------------------------------------------------------------------------------------- |
| `schema` | `object` | JSON Schema untuk `channels.<id>`. Wajib untuk setiap entri config channel yang dideklarasikan. |
| `uiHints` | `Record<string, object>` | Label UI/placeholder/petunjuk sensitif opsional untuk bagian config channel tersebut. |
| `label` | `string` | Label channel yang digabungkan ke permukaan picker dan inspect saat metadata runtime belum siap. |
| `description` | `string` | Deskripsi channel singkat untuk permukaan inspect dan katalog. |
| `preferOver` | `string[]` | ID Plugin lama atau berprioritas lebih rendah yang harus dikalahkan channel ini dalam permukaan pemilihan. |
## Referensi `modelSupport`
Gunakan `modelSupport` saat OpenClaw harus menyimpulkan plugin provider Anda dari
id model shorthand seperti `gpt-5.4` atau `claude-sonnet-4.6` sebelum runtime plugin
Gunakan `modelSupport` saat OpenClaw harus menyimpulkan Plugin provider Anda dari
ID model singkat seperti `gpt-5.4` atau `claude-sonnet-4.6` sebelum runtime plugin
dimuat.
```json
@ -462,21 +467,19 @@ dimuat.
OpenClaw menerapkan prioritas berikut:
- referensi `provider/model` yang eksplisit menggunakan metadata manifest `providers`
milik plugin pemilik
- referensi `provider/model` eksplisit menggunakan metadata manifest `providers` yang memilikinya
- `modelPatterns` mengalahkan `modelPrefixes`
- jika satu plugin non-bundled dan satu plugin bundled sama-sama cocok, plugin non-bundled
yang menang
- ambiguitas yang tersisa diabaikan sampai pengguna atau konfigurasi menentukan provider
- jika satu Plugin non-bundle dan satu Plugin bundle sama-sama cocok, Plugin non-bundle yang menang
- ambiguitas yang tersisa diabaikan sampai pengguna atau config menentukan provider
Field:
| Field | Tipe | Artinya |
| --------------- | ---------- | ------------------------------------------------------------------------------ |
| `modelPrefixes` | `string[]` | Prefiks yang dicocokkan dengan `startsWith` terhadap id model shorthand. |
| `modelPatterns` | `string[]` | Sumber regex yang dicocokkan terhadap id model shorthand setelah sufiks profil dihapus. |
| `modelPrefixes` | `string[]` | Prefiks yang dicocokkan dengan `startsWith` terhadap ID model singkat. |
| `modelPatterns` | `string[]` | Sumber regex yang dicocokkan terhadap ID model singkat setelah suffix profil dihapus. |
Kunci kapabilitas tingkat atas lawas sudah usang. Gunakan `openclaw doctor --fix` untuk
Kunci kapabilitas tingkat atas lama sudah deprecated. Gunakan `openclaw doctor --fix` untuk
memindahkan `speechProviders`, `realtimeTranscriptionProviders`,
`realtimeVoiceProviders`, `mediaUnderstandingProviders`,
`imageGenerationProviders`, `videoGenerationProviders`,
@ -486,50 +489,50 @@ kepemilikan kapabilitas.
## Manifest versus package.json
Kedua file ini melayani fungsi yang berbeda:
Kedua file ini memiliki fungsi yang berbeda:
| File | Gunakan untuk |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.plugin.json` | Discovery, validasi konfigurasi, metadata pilihan auth, dan petunjuk UI yang harus ada sebelum kode plugin berjalan |
| `package.json` | Metadata npm, instalasi dependensi, dan blok `openclaw` yang digunakan untuk entrypoint, pengendalian instalasi, setup, atau metadata katalog |
| File | Gunakan untuk |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.plugin.json` | Discovery, validasi config, metadata pilihan auth, dan petunjuk UI yang harus ada sebelum kode plugin dijalankan |
| `package.json` | Metadata npm, instalasi dependensi, dan blok `openclaw` yang digunakan untuk entrypoint, gating instalasi, setup, atau metadata katalog |
Jika Anda tidak yakin metadata tertentu harus ditempatkan di mana, gunakan aturan ini:
Jika Anda ragu metadata tertentu harus ditempatkan di mana, gunakan aturan ini:
- jika OpenClaw harus mengetahuinya sebelum memuat kode plugin, letakkan di `openclaw.plugin.json`
- jika itu berkaitan dengan packaging, file entry, atau perilaku instalasi npm, letakkan di `package.json`
- jika itu terkait packaging, file entry, atau perilaku instalasi npm, letakkan di `package.json`
### Field `package.json` yang memengaruhi discovery
Beberapa metadata plugin pra-runtime sengaja ditempatkan di `package.json` di bawah
blok `openclaw`, bukan di `openclaw.plugin.json`.
Sebagian metadata plugin pra-runtime sengaja ditempatkan di `package.json` di bawah
blok `openclaw`, bukan `openclaw.plugin.json`.
Contoh penting:
| Field | Artinya |
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.extensions` | Mendeklarasikan entrypoint plugin native. |
| `openclaw.setupEntry` | Entrypoint ringan khusus setup yang digunakan selama onboarding dan startup channel yang ditunda. |
| `openclaw.channel` | Metadata katalog channel ringan seperti label, path docs, alias, dan copy pemilihan. |
| `openclaw.channel.configuredState` | Metadata pemeriksa configured-state ringan yang dapat menjawab "apakah setup hanya-env sudah ada?" tanpa memuat runtime channel penuh. |
| `openclaw.channel.persistedAuthState` | Metadata pemeriksa auth tersimpan ringan yang dapat menjawab "apakah sudah ada yang login?" tanpa memuat runtime channel penuh. |
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Petunjuk instalasi/pembaruan untuk plugin bundle dan plugin yang dipublikasikan secara eksternal. |
| `openclaw.install.defaultChoice` | Jalur instalasi yang diprioritaskan saat tersedia beberapa sumber instalasi. |
| `openclaw.install.minHostVersion` | Versi minimum host OpenClaw yang didukung, menggunakan batas bawah semver seperti `>=2026.3.22`. |
| `openclaw.install.allowInvalidConfigRecovery` | Mengizinkan jalur pemulihan reinstalasi plugin bundle yang sempit saat konfigurasi tidak valid. |
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Memungkinkan permukaan channel khusus setup dimuat sebelum plugin channel penuh saat startup. |
| Field | Artinya |
| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.extensions` | Mendeklarasikan entrypoint Plugin native. |
| `openclaw.setupEntry` | Entrypoint ringan khusus setup yang digunakan selama onboarding dan startup channel tertunda. |
| `openclaw.channel` | Metadata katalog channel ringan seperti label, path docs, alias, dan copy pemilihan. |
| `openclaw.channel.configuredState` | Metadata checker configured-state ringan yang dapat menjawab "apakah setup hanya-env sudah ada?" tanpa memuat runtime channel penuh. |
| `openclaw.channel.persistedAuthState` | Metadata checker auth tersimpan ringan yang dapat menjawab "apakah sudah ada yang login?" tanpa memuat runtime channel penuh. |
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Petunjuk install/update untuk Plugin bundle dan Plugin yang dipublikasikan secara eksternal. |
| `openclaw.install.defaultChoice` | Jalur instalasi yang diutamakan saat beberapa sumber instalasi tersedia. |
| `openclaw.install.minHostVersion` | Versi host OpenClaw minimum yang didukung, menggunakan batas bawah semver seperti `>=2026.3.22`. |
| `openclaw.install.allowInvalidConfigRecovery` | Mengizinkan jalur pemulihan reinstall Plugin bundle yang sempit saat config tidak valid. |
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Memungkinkan permukaan channel khusus setup dimuat sebelum Plugin channel penuh saat startup. |
`openclaw.install.minHostVersion` diterapkan selama instalasi dan pemuatan registry
manifest. Nilai yang tidak valid ditolak; nilai yang valid tetapi lebih baru akan melewati
plugin pada host yang lebih lama.
`openclaw.install.minHostVersion` ditegakkan selama instalasi dan pemuatan registry
manifest. Nilai yang tidak valid ditolak; nilai yang valid tetapi lebih baru akan
melewati Plugin pada host yang lebih lama.
`openclaw.install.allowInvalidConfigRecovery` sengaja dibuat sempit. Nilai ini
tidak membuat konfigurasi rusak apa pun dapat diinstal. Saat ini nilai ini hanya memungkinkan
alur instalasi memulihkan kegagalan upgrade plugin bundle lama tertentu, seperti
path plugin bundle yang hilang atau entri `channels.<id>` lama untuk plugin bundle yang sama.
Kesalahan konfigurasi yang tidak terkait tetap memblokir instalasi dan mengarahkan operator
ke `openclaw doctor --fix`.
`openclaw.install.allowInvalidConfigRecovery` sengaja dibuat sempit. Ini tidak
membuat config rusak secara arbitrer menjadi dapat diinstal. Saat ini, ini hanya
memungkinkan alur instalasi memulihkan kegagalan upgrade Plugin bundle usang tertentu,
seperti path Plugin bundle yang hilang atau entri `channels.<id>` usang untuk Plugin
bundle yang sama. Error config yang tidak terkait tetap memblokir instalasi dan
mengarahkan operator ke `openclaw doctor --fix`.
`openclaw.channel.persistedAuthState` adalah metadata package untuk modul pemeriksa
`openclaw.channel.persistedAuthState` adalah metadata package untuk modul checker
kecil:
```json
@ -547,12 +550,11 @@ kecil:
```
Gunakan ini saat alur setup, doctor, atau configured-state memerlukan probe auth ya/tidak
yang ringan sebelum plugin channel penuh dimuat. Export target harus berupa fungsi kecil
yang hanya membaca state yang tersimpan; jangan arahkan melalui barrel runtime
channel penuh.
yang ringan sebelum Plugin channel penuh dimuat. Export target harus berupa fungsi kecil
yang hanya membaca state tersimpan; jangan arahkan melalui barrel runtime channel penuh.
`openclaw.channel.configuredState` mengikuti bentuk yang sama untuk pemeriksaan configured-state
hanya-env yang ringan:
`openclaw.channel.configuredState` mengikuti bentuk yang sama untuk pemeriksaan configured
khusus-env yang ringan:
```json
{
@ -569,59 +571,70 @@ hanya-env yang ringan:
```
Gunakan ini saat sebuah channel dapat menjawab configured-state dari env atau input kecil
non-runtime lainnya. Jika pemeriksaan memerlukan resolusi konfigurasi penuh atau runtime
channel yang sebenarnya, pertahankan logika itu di hook plugin `config.hasConfiguredState`.
non-runtime lainnya. Jika pemeriksaan membutuhkan resolusi config penuh atau runtime
channel sebenarnya, pertahankan logika tersebut di hook plugin `config.hasConfiguredState`.
## Persyaratan JSON Schema
- **Setiap plugin harus menyertakan JSON Schema**, bahkan jika tidak menerima konfigurasi apa pun.
- **Setiap Plugin harus menyertakan JSON Schema**, bahkan jika tidak menerima config.
- Skema kosong dapat diterima (misalnya, `{ "type": "object", "additionalProperties": false }`).
- Skema divalidasi pada saat baca/tulis konfigurasi, bukan saat runtime.
- Skema divalidasi pada saat baca/tulis config, bukan saat runtime.
## Perilaku validasi
- Kunci `channels.*` yang tidak dikenal adalah **kesalahan**, kecuali id channel tersebut dideklarasikan oleh
- Kunci `channels.*` yang tidak dikenal adalah **error**, kecuali ID channel tersebut dideklarasikan oleh
manifest plugin.
- `plugins.entries.<id>`, `plugins.allow`, `plugins.deny`, dan `plugins.slots.*`
harus merujuk ke id plugin yang **dapat ditemukan**. Id yang tidak dikenal adalah **kesalahan**.
- Jika sebuah plugin terinstal tetapi memiliki manifest atau skema yang rusak atau hilang,
validasi gagal dan Doctor melaporkan kesalahan plugin.
- Jika konfigurasi plugin ada tetapi plugin tersebut **nonaktif**, konfigurasi tetap disimpan dan
**peringatan** ditampilkan di Doctor + log.
harus mereferensikan ID Plugin yang **dapat ditemukan**. ID yang tidak dikenal adalah **error**.
- Jika sebuah Plugin terinstal tetapi memiliki manifest atau skema yang rusak atau hilang,
validasi gagal dan Doctor melaporkan error Plugin tersebut.
- Jika config Plugin ada tetapi Plugin tersebut **dinonaktifkan**, config tetap disimpan dan
**peringatan** akan ditampilkan di Doctor + log.
Lihat [Referensi konfigurasi](/id/gateway/configuration) untuk skema `plugins.*` lengkap.
## Catatan
- Manifest **wajib untuk plugin OpenClaw native**, termasuk pemuatan dari filesystem lokal.
- Runtime tetap memuat modul plugin secara terpisah; manifest hanya untuk
- Manifest ini **wajib untuk Plugin OpenClaw native**, termasuk pemuatan dari filesystem lokal.
- Runtime tetap memuat modul plugin secara terpisah; manifest hanya digunakan untuk
discovery + validasi.
- Manifest native di-parse dengan JSON5, sehingga komentar, koma di akhir, dan
kunci tanpa tanda kutip diterima selama nilai akhirnya tetap berupa objek.
- Hanya field manifest yang terdokumentasi yang dibaca oleh loader manifest. Hindari menambahkan
kunci tingkat atas kustom di sini.
- Manifest native di-parse dengan JSON5, jadi komentar, trailing comma, dan
key tanpa tanda kutip diterima selama nilai akhirnya tetap berupa object.
- Hanya field manifest yang terdokumentasi yang dibaca oleh manifest loader. Hindari menambahkan
key tingkat atas kustom di sini.
- `providerAuthEnvVars` adalah jalur metadata ringan untuk probe auth, validasi
penanda env, dan permukaan auth provider serupa yang tidak seharusnya mem-boot runtime
plugin hanya untuk memeriksa nama env.
- `providerAuthAliases` memungkinkan varian provider menggunakan kembali env vars
auth, profil auth, auth berbasis konfigurasi, dan pilihan onboarding kunci API milik provider lain
tanpa meng-hardcode hubungan tersebut di core.
- `providerAuthAliases` memungkinkan varian provider menggunakan ulang env var auth
provider lain, profil auth, auth berbasis config, dan pilihan onboarding API key
tanpa melakukan hardcode hubungan tersebut di core.
- `providerEndpoints` memungkinkan Plugin provider memiliki metadata pencocokan
host/baseUrl endpoint sederhana. Gunakan hanya untuk kelas endpoint yang sudah
didukung core; plugin tetap memiliki perilaku runtime.
- `syntheticAuthRefs` adalah jalur metadata ringan untuk hook auth sintetis milik provider
yang harus terlihat oleh discovery model cold path sebelum registry runtime ada. Cantumkan
hanya referensi yang runtime provider atau backend CLI-nya benar-benar mengimplementasikan
`resolveSyntheticAuth`.
- `nonSecretAuthMarkers` adalah jalur metadata ringan untuk placeholder API key
milik Plugin bundle seperti penanda kredensial lokal, OAuth, atau ambient.
Core memperlakukan ini sebagai non-secret untuk tampilan auth dan audit secret tanpa
melakukan hardcode pada provider pemiliknya.
- `channelEnvVars` adalah jalur metadata ringan untuk fallback shell-env, prompt
setup, dan permukaan channel serupa yang tidak seharusnya mem-boot runtime plugin
hanya untuk memeriksa nama env.
- `providerAuthChoices` adalah jalur metadata ringan untuk pemilih pilihan auth,
resolusi `--auth-choice`, pemetaan provider yang diprioritaskan, dan registrasi flag CLI onboarding
sederhana sebelum runtime provider dimuat. Untuk metadata wizard runtime
yang memerlukan kode provider, lihat
- `providerAuthChoices` adalah jalur metadata ringan untuk picker pilihan auth,
resolusi `--auth-choice`, pemetaan provider pilihan, dan registrasi flag CLI onboarding
sederhana sebelum runtime provider dimuat. Untuk metadata wizard runtime yang
memerlukan kode provider, lihat
[Hook runtime provider](/id/plugins/architecture#provider-runtime-hooks).
- Jenis plugin eksklusif dipilih melalui `plugins.slots.*`.
- Jenis Plugin eksklusif dipilih melalui `plugins.slots.*`.
- `kind: "memory"` dipilih oleh `plugins.slots.memory`.
- `kind: "context-engine"` dipilih oleh `plugins.slots.contextEngine`
(default: `legacy` bawaan).
- `channels`, `providers`, `cliBackends`, dan `skills` dapat dihilangkan saat sebuah
plugin tidak memerlukannya.
- Jika plugin Anda bergantung pada modul native, dokumentasikan langkah build dan
persyaratan allowlist package-manager apa pun (misalnya, pnpm `allow-build-scripts`
Plugin tidak memerlukannya.
- Jika Plugin Anda bergantung pada modul native, dokumentasikan langkah build dan setiap
persyaratan allowlist package manager (misalnya, pnpm `allow-build-scripts`
- `pnpm rebuild <package>`).
## Terkait

View File

@ -2,35 +2,35 @@
read_when:
- Anda melihat peringatan `OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED`
- Anda melihat peringatan `OPENCLAW_EXTENSION_API_DEPRECATED`
- Anda sedang memperbarui sebuah plugin ke arsitektur plugin modern
- Anda memelihara plugin OpenClaw eksternal
- Anda sedang memperbarui sebuah Plugin ke arsitektur Plugin modern
- Anda memelihara Plugin OpenClaw eksternal
sidebarTitle: Migrate to SDK
summary: Beralih dari lapisan kompatibilitas mundur lama ke Plugin SDK modern
summary: Migrasikan dari lapisan kompatibilitas mundur lama ke Plugin SDK modern
title: Migrasi Plugin SDK
x-i18n:
generated_at: "2026-04-17T09:14:19Z"
generated_at: "2026-04-19T01:11:32Z"
model: gpt-5.4
provider: openai
source_hash: f0283f949eec358a12a0709db846cde2a1509f28e5c60db6e563cb8a540b979d
source_hash: e0df202ed35b3e72bfec1d23201d0e83294fe09cec2caf6e276835098491a899
source_path: plugins/sdk-migration.md
workflow: 15
---
# Migrasi Plugin SDK
OpenClaw telah beralih dari lapisan kompatibilitas mundur yang luas ke arsitektur plugin modern dengan impor yang terfokus dan terdokumentasi. Jika plugin Anda dibuat sebelum arsitektur baru, panduan ini membantu Anda bermigrasi.
OpenClaw telah beralih dari lapisan kompatibilitas mundur yang luas ke arsitektur Plugin modern dengan impor yang terfokus dan terdokumentasi. Jika Plugin Anda dibuat sebelum arsitektur baru ini, panduan ini membantu Anda bermigrasi.
## Apa yang berubah
Sistem plugin lama menyediakan dua permukaan yang sangat terbuka yang memungkinkan plugin mengimpor apa pun yang mereka butuhkan dari satu titik masuk:
Sistem Plugin lama menyediakan dua permukaan yang sangat terbuka yang memungkinkan Plugin mengimpor apa pun yang mereka butuhkan dari satu titik masuk:
- **`openclaw/plugin-sdk/compat`** — satu impor yang mengekspor ulang puluhan helper. Ini diperkenalkan untuk menjaga plugin berbasis hook yang lebih lama tetap berfungsi sementara arsitektur plugin baru sedang dibangun.
- **`openclaw/extension-api`** — sebuah jembatan yang memberi plugin akses langsung ke helper sisi host seperti embedded agent runner.
- **`openclaw/plugin-sdk/compat`** — satu impor yang mengekspor ulang puluhan helper. Ini diperkenalkan untuk menjaga Plugin berbasis hook yang lebih lama tetap berfungsi saat arsitektur Plugin baru sedang dibangun.
- **`openclaw/extension-api`** — sebuah jembatan yang memberi Plugin akses langsung ke helper sisi host seperti embedded agent runner.
Kedua permukaan ini sekarang **deprecated**. Keduanya masih berfungsi saat runtime, tetapi plugin baru tidak boleh menggunakannya, dan plugin yang sudah ada harus bermigrasi sebelum rilis mayor berikutnya menghapusnya.
Kedua permukaan ini sekarang **deprecated**. Keduanya masih berfungsi saat runtime, tetapi Plugin baru tidak boleh menggunakannya, dan Plugin yang sudah ada harus bermigrasi sebelum rilis mayor berikutnya menghapusnya.
<Warning>
Lapisan kompatibilitas mundur akan dihapus pada rilis mayor mendatang.
Lapisan kompatibilitas mundur akan dihapus dalam rilis mayor mendatang.
Plugin yang masih mengimpor dari permukaan ini akan rusak ketika itu terjadi.
</Warning>
@ -38,73 +38,84 @@ Kedua permukaan ini sekarang **deprecated**. Keduanya masih berfungsi saat runti
Pendekatan lama menimbulkan masalah:
- **Startup lambat** — mengimpor satu helper memuat puluhan modul yang tidak terkait
- **Dependensi sirkular** — ekspor ulang yang luas memudahkan terciptanya siklus impor
- **Permukaan API tidak jelas** — tidak ada cara untuk mengetahui ekspor mana yang stabil dan mana yang internal
- **Startup lambat** — mengimpor satu helper memuat puluhan modul lain yang tidak terkait
- **Circular dependency** — ekspor ulang yang luas memudahkan terciptanya siklus impor
- **Permukaan API tidak jelas** — tidak ada cara untuk mengetahui ekspor mana yang stabil vs internal
Plugin SDK modern memperbaiki ini: setiap jalur impor (`openclaw/plugin-sdk/\<subpath\>`) adalah modul kecil yang mandiri dengan tujuan yang jelas dan kontrak yang terdokumentasi.
Plugin SDK modern memperbaikinya: setiap jalur impor (`openclaw/plugin-sdk/\<subpath\>`)
adalah modul kecil yang mandiri dengan tujuan yang jelas dan kontrak yang terdokumentasi.
Seam kenyamanan provider lama untuk channel bawaan juga telah dihapus. Impor seperti `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, seam helper berlabel channel, dan `openclaw/plugin-sdk/telegram-core` adalah pintasan mono-repo privat, bukan kontrak plugin yang stabil. Gunakan subpath SDK generik yang sempit sebagai gantinya. Di dalam workspace plugin bawaan, simpan helper yang dimiliki provider di `api.ts` atau `runtime-api.ts` milik plugin itu sendiri.
Seam kemudahan provider lama untuk channel bawaan juga sudah dihapus. Impor
seperti `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`,
`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`,
seam helper bermerek channel, dan
`openclaw/plugin-sdk/telegram-core` adalah shortcut mono-repo privat, bukan
kontrak Plugin yang stabil. Gunakan subpath SDK generik yang sempit sebagai gantinya. Di dalam
workspace Plugin bawaan, simpan helper milik provider di `api.ts` atau `runtime-api.ts`
Plugin tersebut sendiri.
Contoh provider bawaan saat ini:
- Anthropic menyimpan helper stream khusus Claude di seam `api.ts` / `contract-api.ts` miliknya sendiri
- OpenAI menyimpan builder provider, helper model default, dan builder provider realtime di `api.ts` miliknya sendiri
- OpenRouter menyimpan builder provider serta helper onboarding/konfigurasi di `api.ts` miliknya sendiri
- Anthropic menyimpan helper stream khusus Claude di seam `api.ts` /
`contract-api.ts` miliknya sendiri
- OpenAI menyimpan builder provider, helper model default, dan builder provider
realtime di `api.ts` miliknya sendiri
- OpenRouter menyimpan builder provider dan helper onboarding/config di
`api.ts` miliknya sendiri
## Cara bermigrasi
<Steps>
<Step title="Migrasikan handler native approval ke fakta kapabilitas">
Plugin channel yang mendukung approval sekarang mengekspos perilaku approval native melalui
`approvalCapability.nativeRuntime` ditambah registry konteks runtime bersama.
<Step title="Migrasikan handler native approval ke capability fact">
Plugin channel yang mendukung approval kini mengekspos perilaku approval native melalui
`approvalCapability.nativeRuntime` ditambah registri runtime-context bersama.
Perubahan utama:
- Ganti `approvalCapability.handler.loadRuntime(...)` dengan
`approvalCapability.nativeRuntime`
- Pindahkan auth/pengiriman khusus approval dari wiring lama `plugin.auth` /
- Pindahkan auth/delivery khusus approval dari wiring lama `plugin.auth` /
`plugin.approvals` ke `approvalCapability`
- `ChannelPlugin.approvals` telah dihapus dari kontrak publik plugin channel;
- `ChannelPlugin.approvals` telah dihapus dari kontrak publik channel-plugin;
pindahkan field delivery/native/render ke `approvalCapability`
- `plugin.auth` tetap digunakan hanya untuk alur login/logout channel; hook auth
approval di sana tidak lagi dibaca oleh core
- Daftarkan objek runtime milik channel seperti client, token, atau aplikasi Bolt
melalui `openclaw/plugin-sdk/channel-runtime-context`
- Jangan kirim pemberitahuan pengalihan milik plugin dari handler approval native;
core sekarang menangani pemberitahuan dialihkan-ke-tempat-lain dari hasil pengiriman yang sebenarnya
- Daftarkan objek runtime milik channel seperti client, token, atau Bolt
app melalui `openclaw/plugin-sdk/channel-runtime-context`
- Jangan kirim pemberitahuan reroute milik Plugin dari handler approval native;
core sekarang memiliki pemberitahuan diarahkan-ke-tempat-lain dari hasil delivery yang sebenarnya
- Saat meneruskan `channelRuntime` ke `createChannelManager(...)`, sediakan
permukaan `createPluginRuntime().channel` yang nyata. Stub parsial ditolak.
permukaan `createPluginRuntime().channel` yang nyata. Stub parsial akan ditolak.
Lihat `/plugins/sdk-channel-plugins` untuk tata letak kapabilitas approval saat ini.
Lihat `/plugins/sdk-channel-plugins` untuk tata letak capability approval saat ini.
</Step>
<Step title="Audit perilaku fallback wrapper Windows">
Jika plugin Anda menggunakan `openclaw/plugin-sdk/windows-spawn`, wrapper Windows
`.cmd`/`.bat` yang tidak terselesaikan sekarang gagal secara tertutup kecuali Anda secara eksplisit meneruskan
Jika Plugin Anda menggunakan `openclaw/plugin-sdk/windows-spawn`, wrapper Windows
`.cmd`/`.bat` yang tidak terselesaikan kini gagal secara tertutup kecuali Anda secara eksplisit meneruskan
`allowShellFallback: true`.
```typescript
// Sebelum
// Before
const program = applyWindowsSpawnProgramPolicy({ candidate });
// Sesudah
// After
const program = applyWindowsSpawnProgramPolicy({
candidate,
// Hanya set ini untuk pemanggil kompatibilitas tepercaya yang secara sengaja
// menerima fallback yang dimediasi shell.
// Only set this for trusted compatibility callers that intentionally
// accept shell-mediated fallback.
allowShellFallback: true,
});
```
Jika pemanggil Anda tidak secara sengaja bergantung pada shell fallback, jangan set
Jika pemanggil Anda tidak memang secara sengaja bergantung pada shell fallback, jangan set
`allowShellFallback` dan tangani error yang dilempar sebagai gantinya.
</Step>
<Step title="Temukan impor yang deprecated">
Cari plugin Anda untuk impor dari salah satu permukaan deprecated:
Cari di Plugin Anda untuk impor dari salah satu permukaan deprecated:
```bash
grep -r "plugin-sdk/compat" my-plugin/
@ -117,32 +128,32 @@ Contoh provider bawaan saat ini:
Setiap ekspor dari permukaan lama dipetakan ke jalur impor modern tertentu:
```typescript
// Sebelum (lapisan kompatibilitas mundur deprecated)
// Before (deprecated backwards-compatibility layer)
import {
createChannelReplyPipeline,
createPluginRuntimeStore,
resolveControlCommandGate,
} from "openclaw/plugin-sdk/compat";
// Sesudah (impor modern yang terfokus)
// After (modern focused imports)
import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth";
```
Untuk helper sisi host, gunakan runtime plugin yang diinjeksi alih-alih mengimpor
Untuk helper sisi host, gunakan runtime Plugin yang diinjeksi alih-alih mengimpor
secara langsung:
```typescript
// Sebelum (jembatan extension-api deprecated)
// Before (deprecated extension-api bridge)
import { runEmbeddedPiAgent } from "openclaw/extension-api";
const result = await runEmbeddedPiAgent({ sessionId, prompt });
// Sesudah (runtime yang diinjeksi)
// After (injected runtime)
const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });
```
Pola yang sama berlaku untuk helper jembatan lama lainnya:
Pola yang sama berlaku untuk helper bridge lama lainnya:
| Impor lama | Padanan modern |
| --- | --- |
@ -169,75 +180,75 @@ Contoh provider bawaan saat ini:
<Accordion title="Tabel jalur impor umum">
| Jalur impor | Tujuan | Ekspor utama |
| --- | --- | --- |
| `plugin-sdk/plugin-entry` | Helper entri plugin kanonis | `definePluginEntry` |
| `plugin-sdk/core` | Ekspor ulang payung lama untuk definisi/builder entri channel | `defineChannelPluginEntry`, `createChatChannelPlugin` |
| `plugin-sdk/config-schema` | Ekspor skema konfigurasi root | `OpenClawSchema` |
| `plugin-sdk/plugin-entry` | Helper titik masuk Plugin kanonis | `definePluginEntry` |
| `plugin-sdk/core` | Ekspor ulang umbrella lama untuk definisi/builder entri channel | `defineChannelPluginEntry`, `createChatChannelPlugin` |
| `plugin-sdk/config-schema` | Ekspor skema config root | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | Helper entri provider tunggal | `defineSingleProviderPluginEntry` |
| `plugin-sdk/channel-core` | Definisi dan builder entri channel yang terfokus | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/setup` | Helper wizard setup bersama | Prompt allowlist, builder status setup |
| `plugin-sdk/setup-runtime` | Helper runtime saat setup | Adapter patch setup yang aman untuk impor, helper catatan lookup, `promptResolvedAllowFrom`, `splitSetupEntries`, proksi setup yang didelegasikan |
| `plugin-sdk/setup-runtime` | Helper runtime pada saat setup | Adapter patch setup yang aman diimpor, helper catatan lookup, `promptResolvedAllowFrom`, `splitSetupEntries`, proxy setup terdelegasi |
| `plugin-sdk/setup-adapter-runtime` | Helper adapter setup | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | Helper tooling setup | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/account-core` | Helper multi-akun | Helper daftar akun/konfigurasi/action-gate |
| `plugin-sdk/account-core` | Helper multi-akun | Helper daftar/config/action-gate akun |
| `plugin-sdk/account-id` | Helper account-id | `DEFAULT_ACCOUNT_ID`, normalisasi account-id |
| `plugin-sdk/account-resolution` | Helper lookup akun | Helper lookup akun + fallback default |
| `plugin-sdk/account-helpers` | Helper akun yang sempit | Helper daftar akun/action akun |
| `plugin-sdk/account-resolution` | Helper pencarian akun | Helper pencarian akun + fallback default |
| `plugin-sdk/account-helpers` | Helper akun yang sempit | Helper daftar akun/aksi akun |
| `plugin-sdk/channel-setup` | Adapter wizard setup | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, plus `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
| `plugin-sdk/channel-pairing` | Primitif pairing DM | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | Wiring prefiks balasan + mengetik | `createChannelReplyPipeline` |
| `plugin-sdk/channel-config-helpers` | Factory adapter konfigurasi | `createHybridChannelConfigAdapter` |
| `plugin-sdk/channel-config-schema` | Builder skema konfigurasi | Tipe skema konfigurasi channel |
| `plugin-sdk/telegram-command-config` | Helper konfigurasi perintah Telegram | Normalisasi nama perintah, pemangkasan deskripsi, validasi duplikat/konflik |
| `plugin-sdk/channel-pairing` | Primtif pairing DM | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | Wiring prefiks balasan + pengetikan | `createChannelReplyPipeline` |
| `plugin-sdk/channel-config-helpers` | Factory adapter config | `createHybridChannelConfigAdapter` |
| `plugin-sdk/channel-config-schema` | Builder skema config | Tipe skema config channel |
| `plugin-sdk/telegram-command-config` | Helper config perintah Telegram | Normalisasi nama perintah, pemangkasan deskripsi, validasi duplikat/konflik |
| `plugin-sdk/channel-policy` | Resolusi kebijakan grup/DM | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | Pelacakan status akun | `createAccountStatusSink` |
| `plugin-sdk/inbound-envelope` | Helper envelope masuk | Helper rute bersama + builder envelope |
| `plugin-sdk/inbound-reply-dispatch` | Helper balasan masuk | Helper rekam-dan-dispatch bersama |
| `plugin-sdk/messaging-targets` | Penguraian target pesan | Helper parsing/pencocokan target |
| `plugin-sdk/inbound-envelope` | Helper envelope masuk | Helper route bersama + builder envelope |
| `plugin-sdk/inbound-reply-dispatch` | Helper balasan masuk | Helper pencatatan-dan-dispatch bersama |
| `plugin-sdk/messaging-targets` | Parsing target pesan | Helper parsing/pencocokan target |
| `plugin-sdk/outbound-media` | Helper media keluar | Pemuatan media keluar bersama |
| `plugin-sdk/outbound-runtime` | Helper runtime keluar | Helper identitas/delegasi pengiriman keluar |
| `plugin-sdk/thread-bindings-runtime` | Helper thread-binding | Siklus hidup thread-binding dan helper adapter |
| `plugin-sdk/agent-media-payload` | Helper payload media lama | Builder payload media agen untuk tata letak field lama |
| `plugin-sdk/agent-media-payload` | Helper payload media lama | Builder payload media agent untuk layout field lama |
| `plugin-sdk/channel-runtime` | Shim kompatibilitas deprecated | Hanya utilitas runtime channel lama |
| `plugin-sdk/channel-send-result` | Tipe hasil kirim | Tipe hasil balasan |
| `plugin-sdk/runtime-store` | Penyimpanan plugin persisten | `createPluginRuntimeStore` |
| `plugin-sdk/runtime` | Helper runtime yang luas | Helper runtime/logging/backup/instalasi plugin |
| `plugin-sdk/runtime-env` | Helper env runtime yang sempit | Logger/runtime env, timeout, retry, dan helper backoff |
| `plugin-sdk/plugin-runtime` | Helper runtime plugin bersama | Helper perintah/hook/http/interaktif plugin |
| `plugin-sdk/channel-send-result` | Tipe hasil pengiriman | Tipe hasil balasan |
| `plugin-sdk/runtime-store` | Penyimpanan Plugin persisten | `createPluginRuntimeStore` |
| `plugin-sdk/runtime` | Helper runtime yang luas | Helper runtime/logging/backup/instalasi Plugin |
| `plugin-sdk/runtime-env` | Helper environment runtime yang sempit | Logger/runtime env, helper timeout, retry, dan backoff |
| `plugin-sdk/plugin-runtime` | Helper runtime Plugin bersama | Helper perintah/hook/http/interaktif Plugin |
| `plugin-sdk/hook-runtime` | Helper pipeline hook | Helper pipeline webhook/hook internal bersama |
| `plugin-sdk/lazy-runtime` | Helper runtime lazy | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | Helper proses | Helper exec bersama |
| `plugin-sdk/cli-runtime` | Helper runtime CLI | Pemformatan perintah, waits, helper versi |
| `plugin-sdk/cli-runtime` | Helper runtime CLI | Helper format perintah, wait, versi |
| `plugin-sdk/gateway-runtime` | Helper Gateway | Helper klien Gateway dan patch status channel |
| `plugin-sdk/config-runtime` | Helper konfigurasi | Helper muat/tulis konfigurasi |
| `plugin-sdk/telegram-command-config` | Helper perintah Telegram | Helper validasi perintah Telegram fallback-stable saat permukaan kontrak Telegram bawaan tidak tersedia |
| `plugin-sdk/approval-runtime` | Helper prompt approval | Payload approval exec/plugin, helper kapabilitas/profil approval, helper routing/runtime approval native |
| `plugin-sdk/approval-auth-runtime` | Helper auth approval | Resolusi approver, auth aksi chat yang sama |
| `plugin-sdk/config-runtime` | Helper config | Helper muat/tulis config |
| `plugin-sdk/telegram-command-config` | Helper perintah Telegram | Helper validasi perintah Telegram yang fallback-stable saat permukaan kontrak Telegram bawaan tidak tersedia |
| `plugin-sdk/approval-runtime` | Helper prompt approval | Payload approval exec/Plugin, helper capability/profil approval, helper routing/runtime approval native |
| `plugin-sdk/approval-auth-runtime` | Helper auth approval | Resolusi approver, auth aksi same-chat |
| `plugin-sdk/approval-client-runtime` | Helper klien approval | Helper profil/filter approval exec native |
| `plugin-sdk/approval-delivery-runtime` | Helper pengiriman approval | Adapter kapabilitas/pengiriman approval native |
| `plugin-sdk/approval-gateway-runtime` | Helper Gateway approval | Helper resolusi Gateway approval bersama |
| `plugin-sdk/approval-handler-adapter-runtime` | Helper adapter approval | Helper pemuatan adapter approval native yang ringan untuk hot channel entrypoint |
| `plugin-sdk/approval-handler-runtime` | Helper handler approval | Helper runtime handler approval yang lebih luas; pilih seam adapter/gateway yang lebih sempit bila itu sudah cukup |
| `plugin-sdk/approval-delivery-runtime` | Helper delivery approval | Adapter capability/delivery approval native |
| `plugin-sdk/approval-gateway-runtime` | Helper Gateway approval | Helper resolusi-Gateway approval bersama |
| `plugin-sdk/approval-handler-adapter-runtime` | Helper adapter approval | Helper pemuatan adapter approval native ringan untuk entrypoint channel hot |
| `plugin-sdk/approval-handler-runtime` | Helper handler approval | Helper runtime handler approval yang lebih luas; utamakan seam adapter/Gateway yang lebih sempit jika itu sudah cukup |
| `plugin-sdk/approval-native-runtime` | Helper target approval | Helper binding target/akun approval native |
| `plugin-sdk/approval-reply-runtime` | Helper balasan approval | Helper payload balasan approval exec/plugin |
| `plugin-sdk/channel-runtime-context` | Helper konteks runtime channel | Helper register/get/watch konteks runtime channel generik |
| `plugin-sdk/security-runtime` | Helper keamanan | Helper trust, gating DM, konten eksternal, dan pengumpulan secret bersama |
| `plugin-sdk/approval-reply-runtime` | Helper balasan approval | Helper payload balasan approval exec/Plugin |
| `plugin-sdk/channel-runtime-context` | Helper runtime-context channel | Helper daftar/dapat/watch runtime-context channel generik |
| `plugin-sdk/security-runtime` | Helper keamanan | Helper trust, DM gating, konten eksternal, dan pengumpulan secret bersama |
| `plugin-sdk/ssrf-policy` | Helper kebijakan SSRF | Helper allowlist host dan kebijakan jaringan privat |
| `plugin-sdk/ssrf-runtime` | Helper runtime SSRF | Pinned-dispatcher, guarded fetch, helper kebijakan SSRF |
| `plugin-sdk/ssrf-runtime` | Helper runtime SSRF | `pinned-dispatcher`, guarded fetch, helper kebijakan SSRF |
| `plugin-sdk/collection-runtime` | Helper cache terbatas | `pruneMapToMaxSize` |
| `plugin-sdk/diagnostic-runtime` | Helper gating diagnostik | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` |
| `plugin-sdk/error-runtime` | Helper pemformatan error | `formatUncaughtError`, `isApprovalNotFoundError`, helper graf error |
| `plugin-sdk/error-runtime` | Helper pemformatan error | `formatUncaughtError`, `isApprovalNotFoundError`, helper grafik error |
| `plugin-sdk/fetch-runtime` | Helper fetch/proxy terbungkus | `resolveFetch`, helper proxy |
| `plugin-sdk/host-runtime` | Helper normalisasi host | `normalizeHostname`, `normalizeScpRemoteHost` |
| `plugin-sdk/retry-runtime` | Helper retry | `RetryConfig`, `retryAsync`, runner kebijakan |
| `plugin-sdk/allow-from` | Pemformatan allowlist | `formatAllowFromLowercase` |
| `plugin-sdk/allowlist-resolution` | Pemetaan input allowlist | `mapAllowlistResolutionInputs` |
| `plugin-sdk/command-auth` | Gating perintah dan helper permukaan perintah | `resolveControlCommandGate`, helper otorisasi pengirim, helper registry perintah |
| `plugin-sdk/command-auth` | Gating perintah dan helper permukaan perintah | `resolveControlCommandGate`, helper otorisasi pengirim, helper registri perintah |
| `plugin-sdk/command-status` | Renderer status/help perintah | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` |
| `plugin-sdk/secret-input` | Penguraian input secret | Helper input secret |
| `plugin-sdk/secret-input` | Parsing input secret | Helper input secret |
| `plugin-sdk/webhook-ingress` | Helper permintaan Webhook | Utilitas target Webhook |
| `plugin-sdk/webhook-request-guards` | Helper guard body Webhook | Helper baca/batas body permintaan |
| `plugin-sdk/reply-runtime` | Runtime balasan bersama | Dispatch masuk, Heartbeat, planner balasan, chunking |
| `plugin-sdk/reply-dispatch-runtime` | Helper dispatch balasan yang sempit | Helper finalisasi + dispatch provider |
| `plugin-sdk/reply-runtime` | Runtime balasan bersama | Dispatch masuk, Heartbeat, perencana balasan, chunking |
| `plugin-sdk/reply-dispatch-runtime` | Helper dispatch balasan yang sempit | Helper finalize + dispatch provider |
| `plugin-sdk/reply-history` | Helper riwayat balasan | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-reference` | Perencanaan referensi balasan | `createReplyReferencePlanner` |
| `plugin-sdk/reply-chunking` | Helper chunk balasan | Helper chunking teks/markdown |
@ -245,97 +256,97 @@ Contoh provider bawaan saat ini:
| `plugin-sdk/state-paths` | Helper path state | Helper direktori state dan OAuth |
| `plugin-sdk/routing` | Helper routing/session-key | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, helper normalisasi session-key |
| `plugin-sdk/status-helpers` | Helper status channel | Builder ringkasan status channel/akun, default runtime-state, helper metadata issue |
| `plugin-sdk/target-resolver-runtime` | Helper target resolver | Helper target resolver bersama |
| `plugin-sdk/target-resolver-runtime` | Helper resolver target | Helper resolver target bersama |
| `plugin-sdk/string-normalization-runtime` | Helper normalisasi string | Helper normalisasi slug/string |
| `plugin-sdk/request-url` | Helper URL permintaan | Ekstrak URL string dari input mirip request |
| `plugin-sdk/run-command` | Helper perintah berwaktu | Runner perintah berwaktu dengan stdout/stderr yang dinormalisasi |
| `plugin-sdk/param-readers` | Pembaca parameter | Pembaca parameter tool/CLI umum |
| `plugin-sdk/request-url` | Helper URL permintaan | Ekstrak URL string dari input mirip-permintaan |
| `plugin-sdk/run-command` | Helper perintah bertimer | Runner perintah bertimer dengan stdout/stderr yang dinormalisasi |
| `plugin-sdk/param-readers` | Pembaca param | Pembaca param tool/CLI umum |
| `plugin-sdk/tool-payload` | Ekstraksi payload tool | Ekstrak payload yang dinormalisasi dari objek hasil tool |
| `plugin-sdk/tool-send` | Ekstraksi pengiriman tool | Ekstrak field target kirim kanonis dari argumen tool |
| `plugin-sdk/tool-send` | Ekstraksi pengiriman tool | Ekstrak field target pengiriman kanonis dari argumen tool |
| `plugin-sdk/temp-path` | Helper path sementara | Helper path unduhan sementara bersama |
| `plugin-sdk/logging-core` | Helper logging | Logger subsistem dan helper redaksi |
| `plugin-sdk/markdown-table-runtime` | Helper tabel Markdown | Helper mode tabel Markdown |
| `plugin-sdk/markdown-table-runtime` | Helper tabel markdown | Helper mode tabel markdown |
| `plugin-sdk/reply-payload` | Tipe balasan pesan | Tipe payload balasan |
| `plugin-sdk/provider-setup` | Helper setup provider lokal/self-hosted yang terkurasi | Helper discovery/konfigurasi provider self-hosted |
| `plugin-sdk/self-hosted-provider-setup` | Helper setup provider self-hosted yang kompatibel dengan OpenAI dan terfokus | Helper discovery/konfigurasi provider self-hosted yang sama |
| `plugin-sdk/provider-auth-runtime` | Helper auth runtime provider | Helper resolusi API key saat runtime |
| `plugin-sdk/provider-setup` | Helper setup provider lokal/self-hosted yang terkurasi | Helper discovery/config provider self-hosted |
| `plugin-sdk/self-hosted-provider-setup` | Helper setup provider self-hosted kompatibel OpenAI yang terfokus | Helper discovery/config provider self-hosted yang sama |
| `plugin-sdk/provider-auth-runtime` | Helper auth runtime provider | Helper resolusi API key runtime |
| `plugin-sdk/provider-auth-api-key` | Helper setup API key provider | Helper onboarding/penulisan profil API key |
| `plugin-sdk/provider-auth-result` | Helper auth-result provider | Builder standar auth-result OAuth |
| `plugin-sdk/provider-auth-result` | Helper hasil auth provider | Builder hasil auth OAuth standar |
| `plugin-sdk/provider-auth-login` | Helper login interaktif provider | Helper login interaktif bersama |
| `plugin-sdk/provider-env-vars` | Helper env-var provider | Helper lookup env-var auth provider |
| `plugin-sdk/provider-model-shared` | Helper model/replay provider bersama | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, builder replay-policy bersama, helper endpoint provider, dan helper normalisasi model-id |
| `plugin-sdk/provider-model-shared` | Helper model/replay provider bersama | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, builder kebijakan replay bersama, helper endpoint provider, dan helper normalisasi model-id |
| `plugin-sdk/provider-catalog-shared` | Helper katalog provider bersama | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-onboard` | Patch onboarding provider | Helper konfigurasi onboarding |
| `plugin-sdk/provider-onboard` | Patch onboarding provider | Helper config onboarding |
| `plugin-sdk/provider-http` | Helper HTTP provider | Helper kapabilitas HTTP/endpoint provider generik |
| `plugin-sdk/provider-web-fetch` | Helper web-fetch provider | Helper registrasi/cache provider web-fetch |
| `plugin-sdk/provider-web-search-config-contract` | Helper konfigurasi web-search provider | Helper konfigurasi/kredensial web-search yang sempit untuk provider yang tidak memerlukan wiring enable plugin |
| `plugin-sdk/provider-web-search-contract` | Helper kontrak web-search provider | Helper kontrak konfigurasi/kredensial web-search yang sempit seperti `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`, dan setter/getter kredensial yang di-scope |
| `plugin-sdk/provider-web-search-config-contract` | Helper config web-search provider | Helper config/kredensial web-search yang sempit untuk provider yang tidak memerlukan wiring pengaktifan Plugin |
| `plugin-sdk/provider-web-search-contract` | Helper kontrak web-search provider | Helper kontrak config/kredensial web-search yang sempit seperti `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`, dan setter/getter kredensial terlingkup |
| `plugin-sdk/provider-web-search` | Helper web-search provider | Helper registrasi/cache/runtime provider web-search |
| `plugin-sdk/provider-tools` | Helper kompatibilitas tool/skema provider | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, pembersihan skema Gemini + diagnostik, dan helper kompatibilitas xAI seperti `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-tools` | Helper kompatibilitas tool/skema provider | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, cleanup + diagnostik skema Gemini, serta helper kompatibilitas xAI seperti `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | Helper penggunaan provider | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage`, dan helper penggunaan provider lainnya |
| `plugin-sdk/provider-stream` | Helper wrapper stream provider | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipe wrapper stream, dan helper wrapper bersama Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
| `plugin-sdk/provider-stream` | Helper wrapper stream provider | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipe wrapper stream, serta helper wrapper bersama Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
| `plugin-sdk/provider-transport-runtime` | Helper transport provider | Helper transport provider native seperti guarded fetch, transform pesan transport, dan stream event transport yang dapat ditulis |
| `plugin-sdk/keyed-async-queue` | Antrean async berurutan | `KeyedAsyncQueue` |
| `plugin-sdk/media-runtime` | Helper media bersama | Helper fetch/transform/store media plus builder payload media |
| `plugin-sdk/media-generation-runtime` | Helper media-generation bersama | Helper failover bersama, pemilihan kandidat, dan pesan model hilang untuk generasi gambar/video/musik |
| `plugin-sdk/media-understanding` | Helper media-understanding | Tipe provider media understanding plus ekspor helper gambar/audio yang menghadap provider |
| `plugin-sdk/text-runtime` | Helper teks bersama | Penghapusan teks-yang-terlihat-oleh-asisten, helper render/chunking/tabel markdown, helper redaksi, helper tag direktif, utilitas teks aman, dan helper teks/logging terkait |
| `plugin-sdk/media-runtime` | Helper media bersama | Helper fetch/transform/store media serta builder payload media |
| `plugin-sdk/media-generation-runtime` | Helper generation media bersama | Helper failover bersama, pemilihan kandidat, dan pesan model yang hilang untuk generation gambar/video/musik |
| `plugin-sdk/media-understanding` | Helper media-understanding | Tipe provider media understanding serta ekspor helper gambar/audio yang menghadap ke provider |
| `plugin-sdk/text-runtime` | Helper teks bersama | Penghapusan teks yang terlihat oleh asisten, helper render/chunking/tabel markdown, helper redaksi, helper tag direktif, utilitas safe-text, dan helper teks/logging terkait |
| `plugin-sdk/text-chunking` | Helper chunking teks | Helper chunking teks keluar |
| `plugin-sdk/speech` | Helper speech | Tipe provider speech plus helper direktif, registry, dan validasi yang menghadap provider |
| `plugin-sdk/speech-core` | Inti speech bersama | Tipe provider speech, registry, direktif, normalisasi |
| `plugin-sdk/realtime-transcription` | Helper transkripsi realtime | Tipe provider dan helper registry |
| `plugin-sdk/realtime-voice` | Helper voice realtime | Tipe provider dan helper registry |
| `plugin-sdk/image-generation-core` | Inti image-generation bersama | Tipe image-generation, failover, auth, dan helper registry |
| `plugin-sdk/music-generation` | Helper music-generation | Tipe provider/request/result music-generation |
| `plugin-sdk/music-generation-core` | Inti music-generation bersama | Tipe music-generation, helper failover, lookup provider, dan parsing model-ref |
| `plugin-sdk/video-generation` | Helper video-generation | Tipe provider/request/result video-generation |
| `plugin-sdk/video-generation-core` | Inti video-generation bersama | Tipe video-generation, helper failover, lookup provider, dan parsing model-ref |
| `plugin-sdk/speech` | Helper speech | Tipe provider speech serta helper direktif, registri, dan validasi yang menghadap ke provider |
| `plugin-sdk/speech-core` | Core speech bersama | Tipe provider speech, registri, direktif, normalisasi |
| `plugin-sdk/realtime-transcription` | Helper transkripsi realtime | Tipe provider dan helper registri |
| `plugin-sdk/realtime-voice` | Helper voice realtime | Tipe provider dan helper registri |
| `plugin-sdk/image-generation-core` | Core generation gambar bersama | Tipe generation gambar, failover, auth, dan helper registri |
| `plugin-sdk/music-generation` | Helper generation musik | Tipe provider/permintaan/hasil generation musik |
| `plugin-sdk/music-generation-core` | Core generation musik bersama | Tipe generation musik, helper failover, pencarian provider, dan parsing model-ref |
| `plugin-sdk/video-generation` | Helper generation video | Tipe provider/permintaan/hasil generation video |
| `plugin-sdk/video-generation-core` | Core generation video bersama | Tipe generation video, helper failover, pencarian provider, dan parsing model-ref |
| `plugin-sdk/interactive-runtime` | Helper balasan interaktif | Normalisasi/reduksi payload balasan interaktif |
| `plugin-sdk/channel-config-primitives` | Primitif konfigurasi channel | Primitif config-schema channel yang sempit |
| `plugin-sdk/channel-config-writes` | Helper penulisan konfigurasi channel | Helper otorisasi penulisan konfigurasi channel |
| `plugin-sdk/channel-plugin-common` | Prelude channel bersama | Ekspor prelude plugin channel bersama |
| `plugin-sdk/channel-config-primitives` | Primtif config channel | Primtif config-schema channel yang sempit |
| `plugin-sdk/channel-config-writes` | Helper penulisan config channel | Helper otorisasi penulisan config channel |
| `plugin-sdk/channel-plugin-common` | Prelude channel bersama | Ekspor prelude Plugin channel bersama |
| `plugin-sdk/channel-status` | Helper status channel | Helper snapshot/ringkasan status channel bersama |
| `plugin-sdk/allowlist-config-edit` | Helper konfigurasi allowlist | Helper edit/baca konfigurasi allowlist |
| `plugin-sdk/group-access` | Helper akses grup | Helper keputusan group-access bersama |
| `plugin-sdk/direct-dm` | Helper direct-DM | Helper auth/guard direct-DM bersama |
| `plugin-sdk/extension-shared` | Helper extension bersama | Primitif helper passive-channel/status dan ambient proxy |
| `plugin-sdk/webhook-targets` | Helper target Webhook | Registry target Webhook dan helper instalasi rute |
| `plugin-sdk/allowlist-config-edit` | Helper config allowlist | Helper edit/baca config allowlist |
| `plugin-sdk/group-access` | Helper akses grup | Helper keputusan akses grup bersama |
| `plugin-sdk/direct-dm` | Helper Direct-DM | Helper auth/guard Direct-DM bersama |
| `plugin-sdk/extension-shared` | Helper extension bersama | Primtif helper passive-channel/status dan ambient proxy |
| `plugin-sdk/webhook-targets` | Helper target Webhook | Registri target Webhook dan helper instalasi route |
| `plugin-sdk/webhook-path` | Helper path Webhook | Helper normalisasi path Webhook |
| `plugin-sdk/web-media` | Helper media web bersama | Helper pemuatan media remote/lokal |
| `plugin-sdk/zod` | Ekspor ulang zod | `zod` yang diekspor ulang untuk konsumen Plugin SDK |
| `plugin-sdk/memory-core` | Helper memory-core bawaan | Permukaan helper manajer/konfigurasi/file/CLI memory |
| `plugin-sdk/memory-core-engine-runtime` | Fasad runtime mesin memory | Fasad runtime indeks/pencarian memory |
| `plugin-sdk/memory-core-host-engine-foundation` | Mesin foundation host memory | Ekspor mesin foundation host memory |
| `plugin-sdk/memory-core-host-engine-embeddings` | Mesin embedding host memory | Kontrak embedding memory, akses registry, provider lokal, dan helper batch/remote generik; provider remote konkret berada di plugin pemiliknya |
| `plugin-sdk/memory-core-host-engine-qmd` | Mesin QMD host memory | Ekspor mesin QMD host memory |
| `plugin-sdk/memory-core-host-engine-storage` | Mesin storage host memory | Ekspor mesin storage host memory |
| `plugin-sdk/memory-core-host-multimodal` | Helper multimodal host memory | Helper multimodal host memory |
| `plugin-sdk/memory-core-host-query` | Helper query host memory | Helper query host memory |
| `plugin-sdk/memory-core-host-secret` | Helper secret host memory | Helper secret host memory |
| `plugin-sdk/memory-core-host-events` | Helper jurnal event host memory | Helper jurnal event host memory |
| `plugin-sdk/memory-core-host-status` | Helper status host memory | Helper status host memory |
| `plugin-sdk/memory-core-host-runtime-cli` | Runtime CLI host memory | Helper runtime CLI host memory |
| `plugin-sdk/memory-core-host-runtime-core` | Runtime inti host memory | Helper runtime inti host memory |
| `plugin-sdk/memory-core-host-runtime-files` | Helper file/runtime host memory | Helper file/runtime host memory |
| `plugin-sdk/memory-host-core` | Alias runtime inti host memory | Alias netral-vendor untuk helper runtime inti host memory |
| `plugin-sdk/memory-host-events` | Alias jurnal event host memory | Alias netral-vendor untuk helper jurnal event host memory |
| `plugin-sdk/memory-host-files` | Alias file/runtime host memory | Alias netral-vendor untuk helper file/runtime host memory |
| `plugin-sdk/memory-host-markdown` | Helper markdown terkelola | Helper managed-markdown bersama untuk plugin yang berdekatan dengan memory |
| `plugin-sdk/zod` | Ekspor ulang Zod | `zod` yang diekspor ulang untuk konsumen Plugin SDK |
| `plugin-sdk/memory-core` | Helper memory-core bawaan | Permukaan helper manajer/config/file/CLI memori |
| `plugin-sdk/memory-core-engine-runtime` | Fasad runtime engine memori | Fasad runtime indeks/pencarian memori |
| `plugin-sdk/memory-core-host-engine-foundation` | Engine fondasi host memori | Ekspor engine fondasi host memori |
| `plugin-sdk/memory-core-host-engine-embeddings` | Engine embedding host memori | Kontrak embedding memori, akses registri, provider lokal, dan helper batch/remote generik; provider remote konkret berada di Plugin pemiliknya |
| `plugin-sdk/memory-core-host-engine-qmd` | Engine QMD host memori | Ekspor engine QMD host memori |
| `plugin-sdk/memory-core-host-engine-storage` | Engine penyimpanan host memori | Ekspor engine penyimpanan host memori |
| `plugin-sdk/memory-core-host-multimodal` | Helper multimodal host memori | Helper multimodal host memori |
| `plugin-sdk/memory-core-host-query` | Helper kueri host memori | Helper kueri host memori |
| `plugin-sdk/memory-core-host-secret` | Helper secret host memori | Helper secret host memori |
| `plugin-sdk/memory-core-host-events` | Helper jurnal event host memori | Helper jurnal event host memori |
| `plugin-sdk/memory-core-host-status` | Helper status host memori | Helper status host memori |
| `plugin-sdk/memory-core-host-runtime-cli` | Runtime CLI host memori | Helper runtime CLI host memori |
| `plugin-sdk/memory-core-host-runtime-core` | Runtime core host memori | Helper runtime core host memori |
| `plugin-sdk/memory-core-host-runtime-files` | Helper file/runtime host memori | Helper file/runtime host memori |
| `plugin-sdk/memory-host-core` | Alias runtime core host memori | Alias netral-vendor untuk helper runtime core host memori |
| `plugin-sdk/memory-host-events` | Alias jurnal event host memori | Alias netral-vendor untuk helper jurnal event host memori |
| `plugin-sdk/memory-host-files` | Alias file/runtime host memori | Alias netral-vendor untuk helper file/runtime host memori |
| `plugin-sdk/memory-host-markdown` | Helper markdown terkelola | Helper managed-markdown bersama untuk Plugin yang berdekatan dengan memori |
| `plugin-sdk/memory-host-search` | Fasad pencarian Active Memory | Fasad runtime lazy active-memory search-manager |
| `plugin-sdk/memory-host-status` | Alias status host memory | Alias netral-vendor untuk helper status host memory |
| `plugin-sdk/memory-host-status` | Alias status host memori | Alias netral-vendor untuk helper status host memori |
| `plugin-sdk/memory-lancedb` | Helper memory-lancedb bawaan | Permukaan helper memory-lancedb |
| `plugin-sdk/testing` | Utilitas pengujian | Helper dan mock pengujian |
| `plugin-sdk/testing` | Utilitas pengujian | Helper uji dan mock |
</Accordion>
Tabel ini sengaja merupakan subset migrasi umum, bukan seluruh permukaan SDK.
Daftar lengkap 200+ entrypoint berada di
Tabel ini sengaja merupakan subset migrasi umum, bukan seluruh
permukaan SDK. Daftar lengkap 200+ entrypoint ada di
`scripts/lib/plugin-sdk-entrypoints.json`.
Daftar itu masih mencakup beberapa seam helper plugin bawaan seperti
Daftar itu masih mencakup beberapa seam helper Plugin bawaan seperti
`plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`,
`plugin-sdk/zalo-setup`, dan `plugin-sdk/matrix*`. Semuanya tetap diekspor untuk
pemeliharaan dan kompatibilitas plugin bawaan, tetapi sengaja
dihilangkan dari tabel migrasi umum dan bukan target yang direkomendasikan untuk
kode plugin baru.
`plugin-sdk/zalo-setup`, dan `plugin-sdk/matrix*`. Semuanya masih diekspor untuk
pemeliharaan dan kompatibilitas Plugin bawaan, tetapi sengaja dihilangkan dari tabel migrasi umum dan bukan target yang direkomendasikan untuk
kode Plugin baru.
Aturan yang sama berlaku untuk keluarga helper bawaan lainnya seperti:
@ -343,7 +354,7 @@ Aturan yang sama berlaku untuk keluarga helper bawaan lainnya seperti:
- Matrix: `plugin-sdk/matrix*`
- LINE: `plugin-sdk/line*`
- IRC: `plugin-sdk/irc*`
- permukaan helper/plugin bawaan seperti `plugin-sdk/googlechat`,
- helper bawaan/permukaan Plugin seperti `plugin-sdk/googlechat`,
`plugin-sdk/zalouser`, `plugin-sdk/bluebubbles*`,
`plugin-sdk/mattermost*`, `plugin-sdk/msteams`,
`plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`,
@ -352,12 +363,11 @@ Aturan yang sama berlaku untuk keluarga helper bawaan lainnya seperti:
`plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`,
`plugin-sdk/thread-ownership`, dan `plugin-sdk/voice-call`
`plugin-sdk/github-copilot-token` saat ini mengekspos
permukaan helper token yang sempit
`plugin-sdk/github-copilot-token` saat ini mengekspos permukaan helper token yang sempit
`DEFAULT_COPILOT_API_BASE_URL`,
`deriveCopilotApiBaseUrlFromToken`, dan `resolveCopilotApiToken`.
Gunakan impor tersempit yang sesuai dengan tugasnya. Jika Anda tidak dapat menemukan sebuah ekspor,
Gunakan impor yang paling sempit yang sesuai dengan tugasnya. Jika Anda tidak dapat menemukan sebuah ekspor,
periksa sumbernya di `src/plugin-sdk/` atau tanyakan di Discord.
## Linimasa penghapusan
@ -365,27 +375,27 @@ periksa sumbernya di `src/plugin-sdk/` atau tanyakan di Discord.
| Kapan | Apa yang terjadi |
| ---------------------- | ----------------------------------------------------------------------- |
| **Sekarang** | Permukaan deprecated mengeluarkan peringatan runtime |
| **Rilis mayor berikutnya** | Permukaan deprecated akan dihapus; plugin yang masih menggunakannya akan gagal |
| **Rilis mayor berikutnya** | Permukaan deprecated akan dihapus; Plugin yang masih menggunakannya akan gagal |
Semua plugin core sudah dimigrasikan. Plugin eksternal sebaiknya bermigrasi
Semua Plugin core sudah dimigrasikan. Plugin eksternal sebaiknya bermigrasi
sebelum rilis mayor berikutnya.
## Menonaktifkan peringatan sementara
## Menyembunyikan peringatan untuk sementara
Setel variabel environment ini saat Anda sedang mengerjakan migrasi:
Set environment variable ini saat Anda sedang mengerjakan migrasi:
```bash
OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run
```
Ini adalah jalur keluar sementara, bukan solusi permanen.
Ini adalah celah sementara, bukan solusi permanen.
## Terkait
- [Memulai](/id/plugins/building-plugins) — bangun plugin pertama Anda
- [Memulai](/id/plugins/building-plugins) — buat Plugin pertama Anda
- [Ikhtisar SDK](/id/plugins/sdk-overview) — referensi impor subpath lengkap
- [Plugin Channel](/id/plugins/sdk-channel-plugins) — membangun plugin channel
- [Plugin Provider](/id/plugins/sdk-provider-plugins) — membangun plugin provider
- [Plugin Channel](/id/plugins/sdk-channel-plugins) — membangun Plugin channel
- [Plugin Provider](/id/plugins/sdk-provider-plugins) — membangun Plugin provider
- [Internal Plugin](/id/plugins/architecture) — pendalaman arsitektur
- [Manifest Plugin](/id/plugins/manifest) — referensi skema manifest

View File

@ -1,30 +1,30 @@
---
read_when:
- Anda perlu mengetahui subpath SDK mana yang harus diimpor dari sana
- Anda menginginkan referensi untuk semua metode registrasi di `OpenClawPluginApi`
- Anda menginginkan referensi untuk semua metode pendaftaran pada OpenClawPluginApi
- Anda sedang mencari ekspor SDK tertentu
sidebarTitle: SDK Overview
summary: Peta impor, referensi API registrasi, dan arsitektur SDK
title: Ikhtisar Plugin SDK
summary: Peta impor, referensi API pendaftaran, dan arsitektur SDK
title: Ikhtisar SDK Plugin
x-i18n:
generated_at: "2026-04-18T09:05:50Z"
generated_at: "2026-04-19T01:11:27Z"
model: gpt-5.4
provider: openai
source_hash: 05d3d0022cca32d29c76f6cea01cdf4f88ac69ef0ef3d7fb8a60fbf9a6b9b331
source_hash: 522c2c542bc0ea4793541fda18931b963ad71f07e9c83e4f22f05184eb1ba91a
source_path: plugins/sdk-overview.md
workflow: 15
---
# Ikhtisar Plugin SDK
# Ikhtisar SDK Plugin
Plugin SDK adalah kontrak bertipe antara plugin dan core. Halaman ini adalah
SDK plugin adalah kontrak bertipe antara plugin dan inti. Halaman ini adalah
referensi untuk **apa yang harus diimpor** dan **apa yang dapat Anda daftarkan**.
<Tip>
**Mencari panduan cara melakukannya?**
- Plugin pertama? Mulai dengan [Memulai](/id/plugins/building-plugins)
- Plugin channel? Lihat [Plugin Channel](/id/plugins/sdk-channel-plugins)
- Plugin provider? Lihat [Plugin Provider](/id/plugins/sdk-provider-plugins)
- Plugin pertama? Mulai dengan [Getting Started](/id/plugins/building-plugins)
- Plugin saluran? Lihat [Channel Plugins](/id/plugins/sdk-channel-plugins)
- Plugin penyedia? Lihat [Provider Plugins](/id/plugins/sdk-provider-plugins)
</Tip>
## Konvensi impor
@ -37,38 +37,38 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
```
Setiap subpath adalah modul kecil yang berdiri sendiri. Ini menjaga startup tetap cepat dan
mencegah masalah circular dependency. Untuk helper entri/build khusus channel,
utamakan `openclaw/plugin-sdk/channel-core`; pertahankan `openclaw/plugin-sdk/core` untuk
permukaan payung yang lebih luas dan helper bersama seperti
mencegah masalah dependensi sirkular. Untuk helper entri/build khusus saluran,
utamakan `openclaw/plugin-sdk/channel-core`; gunakan `openclaw/plugin-sdk/core` untuk
permukaan umbrella yang lebih luas dan helper bersama seperti
`buildChannelConfigSchema`.
Jangan tambahkan atau bergantung pada seam kemudahan bernama provider seperti
Jangan menambahkan atau bergantung pada seam kemudahan bernama penyedia seperti
`openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`,
`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, atau
seam helper berlabel channel. Plugin bawaan harus menyusun subpath
SDK generik di dalam barrel `api.ts` atau `runtime-api.ts` milik mereka sendiri, dan core
harus menggunakan barrel lokal plugin tersebut atau menambahkan kontrak SDK generik yang sempit
ketika kebutuhannya benar-benar lintas channel.
seam helper bermerek saluran. Plugin bawaan sebaiknya menyusun subpath
SDK generik di dalam barrel `api.ts` atau `runtime-api.ts` milik mereka sendiri, dan inti
sebaiknya menggunakan barrel lokal plugin tersebut atau menambahkan kontrak SDK generik
yang sempit saat kebutuhannya benar-benar lintas saluran.
Peta ekspor yang dihasilkan masih memuat sejumlah kecil
Peta ekspor yang dihasilkan masih berisi sejumlah kecil
seam helper bundled-plugin seperti `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`,
`plugin-sdk/zalo`, `plugin-sdk/zalo-setup`, dan `plugin-sdk/matrix*`. Subpath tersebut
hanya ada untuk pemeliharaan dan kompatibilitas bundled-plugin; subpath itu
sengaja dihilangkan dari tabel umum di bawah dan bukan jalur impor yang
direkomendasikan untuk plugin pihak ketiga yang baru.
`plugin-sdk/zalo`, `plugin-sdk/zalo-setup`, dan `plugin-sdk/matrix*`. Subpath
tersebut ada hanya untuk pemeliharaan dan kompatibilitas bundled-plugin; subpath tersebut
sengaja dihilangkan dari tabel umum di bawah dan bukan jalur impor
yang direkomendasikan untuk plugin pihak ketiga yang baru.
## Referensi subpath
Subpath yang paling umum digunakan, dikelompokkan berdasarkan tujuan. Daftar lengkap yang dihasilkan berisi
200+ subpath ada di `scripts/lib/plugin-sdk-entrypoints.json`.
lebih dari 200 subpath berada di `scripts/lib/plugin-sdk-entrypoints.json`.
Subpath helper bundled-plugin yang dicadangkan masih muncul dalam daftar yang dihasilkan tersebut.
Perlakukan itu sebagai permukaan detail implementasi/kompatibilitas kecuali halaman dokumen
Anggap itu sebagai detail implementasi/permukaan kompatibilitas kecuali halaman dokumen
secara eksplisit mempromosikan salah satunya sebagai publik.
### Entri plugin
| Subpath | Ekspor utama |
| Subpath | Ekspor utama |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
@ -76,110 +76,111 @@ secara eksplisit mempromosikan salah satunya sebagai publik.
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
<AccordionGroup>
<Accordion title="Subpath channel">
<Accordion title="Subpath saluran">
| Subpath | Ekspor utama |
| --- | --- |
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/config-schema` | Ekspor skema Zod root `openclaw.json` (`OpenClawSchema`) |
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, ditambah `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
| `plugin-sdk/setup` | Helper wizard penyiapan bersama, prompt allowlist, pembuat status penyiapan |
| `plugin-sdk/setup` | Helper wizard penyiapan bersama, prompt allowlist, builder status penyiapan |
| `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
| `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/account-core` | Helper config/pagar tindakan multi-akun, helper fallback akun default |
| `plugin-sdk/account-core` | Helper konfigurasi multi-akun/action-gate, helper fallback akun default |
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, helper normalisasi account-id |
| `plugin-sdk/account-resolution` | Pencarian akun + helper fallback default |
| `plugin-sdk/account-helpers` | Helper sempit daftar-aksi akun/aksi akun |
| `plugin-sdk/account-helpers` | Helper sempit untuk daftar akun/aksi akun |
| `plugin-sdk/channel-pairing` | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` |
| `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` |
| `plugin-sdk/channel-config-schema` | Tipe skema config channel |
| `plugin-sdk/telegram-command-config` | Helper normalisasi/validasi perintah kustom Telegram dengan fallback kontrak bawaan |
| `plugin-sdk/command-gating` | Helper pagar otorisasi perintah yang sempit |
| `plugin-sdk/channel-config-schema` | Tipe skema konfigurasi saluran |
| `plugin-sdk/telegram-command-config` | Helper normalisasi/validasi perintah kustom Telegram dengan fallback bundled-contract |
| `plugin-sdk/command-gating` | Helper sempit untuk gerbang otorisasi perintah |
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` |
| `plugin-sdk/inbound-envelope` | Helper route masuk dan pembangun envelope bersama |
| `plugin-sdk/inbound-reply-dispatch` | Helper pencatatan-dan-dispatch masuk bersama |
| `plugin-sdk/inbound-envelope` | Helper bersama untuk route inbound + builder envelope |
| `plugin-sdk/inbound-reply-dispatch` | Helper bersama untuk mencatat dan mendispatch inbound |
| `plugin-sdk/messaging-targets` | Helper parsing/pencocokan target |
| `plugin-sdk/outbound-media` | Helper pemuatan media keluar bersama |
| `plugin-sdk/outbound-runtime` | Helper identitas keluar/delegasi pengiriman |
| `plugin-sdk/poll-runtime` | Helper normalisasi poll yang sempit |
| `plugin-sdk/thread-bindings-runtime` | Siklus hidup thread-binding dan helper adapter |
| `plugin-sdk/agent-media-payload` | Pembuat payload media agen lama |
| `plugin-sdk/conversation-runtime` | Helper percakapan/thread binding, pairing, dan binding terkonfigurasi |
| `plugin-sdk/runtime-config-snapshot` | Helper snapshot config runtime |
| `plugin-sdk/outbound-media` | Helper bersama untuk memuat media outbound |
| `plugin-sdk/outbound-runtime` | Helper identitas outbound/delegasi pengiriman |
| `plugin-sdk/poll-runtime` | Helper sempit untuk normalisasi polling |
| `plugin-sdk/thread-bindings-runtime` | Helper siklus hidup thread-binding dan adapter |
| `plugin-sdk/agent-media-payload` | Builder payload media agen lama |
| `plugin-sdk/conversation-runtime` | Helper binding percakapan/thread, pairing, dan configured-binding |
| `plugin-sdk/runtime-config-snapshot` | Helper snapshot konfigurasi runtime |
| `plugin-sdk/runtime-group-policy` | Helper resolusi kebijakan grup runtime |
| `plugin-sdk/channel-status` | Helper snapshot/ringkasan status channel bersama |
| `plugin-sdk/channel-config-primitives` | Primitif skema config channel yang sempit |
| `plugin-sdk/channel-config-writes` | Helper otorisasi penulisan config channel |
| `plugin-sdk/channel-plugin-common` | Ekspor prelude plugin channel bersama |
| `plugin-sdk/allowlist-config-edit` | Helper edit/baca config allowlist |
| `plugin-sdk/group-access` | Helper keputusan akses grup bersama |
| `plugin-sdk/direct-dm` | Helper auth/pengaman direct-DM bersama |
| `plugin-sdk/interactive-runtime` | Helper normalisasi/pengurangan payload balasan interaktif |
| `plugin-sdk/channel-inbound` | Barrel kompatibilitas untuk debounce masuk, pencocokan mention, helper kebijakan mention, dan helper envelope |
| `plugin-sdk/channel-mention-gating` | Helper kebijakan mention yang sempit tanpa permukaan runtime masuk yang lebih luas |
| `plugin-sdk/channel-location` | Helper konteks lokasi channel dan pemformatan |
| `plugin-sdk/channel-logging` | Helper logging channel untuk drop masuk dan kegagalan typing/ack |
| `plugin-sdk/channel-status` | Helper bersama untuk snapshot/ringkasan status saluran |
| `plugin-sdk/channel-config-primitives` | Primitive skema konfigurasi saluran yang sempit |
| `plugin-sdk/channel-config-writes` | Helper otorisasi penulisan konfigurasi saluran |
| `plugin-sdk/channel-plugin-common` | Ekspor prelude plugin saluran bersama |
| `plugin-sdk/allowlist-config-edit` | Helper edit/baca konfigurasi allowlist |
| `plugin-sdk/group-access` | Helper bersama untuk keputusan akses grup |
| `plugin-sdk/direct-dm` | Helper bersama untuk auth/guard direct-DM |
| `plugin-sdk/interactive-runtime` | Helper normalisasi/reduksi payload balasan interaktif |
| `plugin-sdk/channel-inbound` | Barrel kompatibilitas untuk debounce inbound, pencocokan mention, helper kebijakan mention, dan helper envelope |
| `plugin-sdk/channel-mention-gating` | Helper kebijakan mention yang sempit tanpa permukaan runtime inbound yang lebih luas |
| `plugin-sdk/channel-location` | Helper konteks lokasi saluran dan pemformatan |
| `plugin-sdk/channel-logging` | Helper logging saluran untuk inbound drop dan kegagalan typing/ack |
| `plugin-sdk/channel-send-result` | Tipe hasil balasan |
| `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` |
| `plugin-sdk/channel-targets` | Helper parsing/pencocokan target |
| `plugin-sdk/channel-contract` | Tipe kontrak channel |
| `plugin-sdk/channel-contract` | Tipe kontrak saluran |
| `plugin-sdk/channel-feedback` | Wiring umpan balik/reaksi |
| `plugin-sdk/channel-secret-runtime` | Helper kontrak secret yang sempit seperti `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, dan tipe target secret |
</Accordion>
<Accordion title="Subpath provider">
<Accordion title="Subpath penyedia">
| Subpath | Ekspor utama |
| --- | --- |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
| `plugin-sdk/provider-setup` | Helper penyiapan provider lokal/self-hosted yang dikurasi |
| `plugin-sdk/self-hosted-provider-setup` | Helper penyiapan provider self-hosted yang kompatibel dengan OpenAI dan terfokus |
| `plugin-sdk/provider-setup` | Helper penyiapan penyedia lokal/self-hosted yang dikurasi |
| `plugin-sdk/self-hosted-provider-setup` | Helper penyiapan penyedia self-hosted kompatibel OpenAI yang terfokus |
| `plugin-sdk/cli-backend` | Default backend CLI + konstanta watchdog |
| `plugin-sdk/provider-auth-runtime` | Helper resolusi API key runtime untuk plugin provider |
| `plugin-sdk/provider-auth-runtime` | Helper resolusi API key runtime untuk plugin penyedia |
| `plugin-sdk/provider-auth-api-key` | Helper onboarding/penulisan profil API key seperti `upsertApiKeyProfile` |
| `plugin-sdk/provider-auth-result` | Pembangun hasil auth OAuth standar |
| `plugin-sdk/provider-auth-login` | Helper login interaktif bersama untuk plugin provider |
| `plugin-sdk/provider-env-vars` | Helper pencarian env var auth provider |
| `plugin-sdk/provider-auth-result` | Builder hasil auth OAuth standar |
| `plugin-sdk/provider-auth-login` | Helper login interaktif bersama untuk plugin penyedia |
| `plugin-sdk/provider-env-vars` | Helper pencarian env var auth penyedia |
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, pembangun kebijakan replay bersama, helper endpoint provider, dan helper normalisasi model-id seperti `normalizeNativeXaiModelId` |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, builder kebijakan replay bersama, helper endpoint penyedia, dan helper normalisasi model-id seperti `normalizeNativeXaiModelId` |
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-http` | Helper kemampuan HTTP/endpoint provider generik |
| `plugin-sdk/provider-web-fetch-contract` | Helper kontrak config/seleksi web-fetch yang sempit seperti `enablePluginInConfig` dan `WebFetchProviderPlugin` |
| `plugin-sdk/provider-web-fetch` | Helper registrasi/cache provider web-fetch |
| `plugin-sdk/provider-web-search-config-contract` | Helper config/kredensial web-search yang sempit untuk provider yang tidak memerlukan wiring plugin-enable |
| `plugin-sdk/provider-web-search-contract` | Helper kontrak config/kredensial web-search yang sempit seperti `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`, dan setter/getter kredensial berskala |
| `plugin-sdk/provider-web-search` | Helper registrasi/cache/runtime provider web-search |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, pembersihan skema Gemini + diagnostik, dan helper kompat xAI seperti `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-http` | Helper kemampuan HTTP/endpoint penyedia generik |
| `plugin-sdk/provider-web-fetch-contract` | Helper kontrak konfigurasi/pemilihan web-fetch yang sempit seperti `enablePluginInConfig` dan `WebFetchProviderPlugin` |
| `plugin-sdk/provider-web-fetch` | Helper pendaftaran/cache penyedia web-fetch |
| `plugin-sdk/provider-web-search-config-contract` | Helper konfigurasi/kredensial web-search yang sempit untuk penyedia yang tidak memerlukan wiring plugin-enable |
| `plugin-sdk/provider-web-search-contract` | Helper kontrak konfigurasi/kredensial web-search yang sempit seperti `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`, dan setter/getter kredensial terlingkup |
| `plugin-sdk/provider-web-search` | Helper pendaftaran/cache/runtime penyedia web-search |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, pembersihan skema Gemini + diagnostik, dan helper kompatibilitas xAI seperti `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` dan yang serupa |
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipe wrapper stream, dan helper wrapper bersama Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
| `plugin-sdk/provider-onboard` | Helper patch config onboarding |
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipe wrapper stream, dan helper wrapper bersama untuk Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
| `plugin-sdk/provider-transport-runtime` | Helper transport penyedia native seperti guarded fetch, transform pesan transport, dan stream event transport yang dapat ditulis |
| `plugin-sdk/provider-onboard` | Helper patch konfigurasi onboarding |
| `plugin-sdk/global-singleton` | Helper singleton/map/cache lokal-proses |
</Accordion>
<Accordion title="Subpath auth dan keamanan">
| Subpath | Ekspor utama |
| --- | --- |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`, helper registry perintah, helper otorisasi pengirim |
| `plugin-sdk/command-status` | Pembangun pesan perintah/bantuan seperti `buildCommandsMessagePaginated` dan `buildHelpMessage` |
| `plugin-sdk/approval-auth-runtime` | Helper resolusi approver dan auth tindakan dalam chat yang sama |
| `plugin-sdk/approval-client-runtime` | Helper profil/filter approval native exec |
| `plugin-sdk/approval-delivery-runtime` | Adapter kemampuan/pengiriman approval native |
| `plugin-sdk/approval-gateway-runtime` | Helper resolusi Gateway approval bersama |
| `plugin-sdk/approval-handler-adapter-runtime` | Helper pemuatan adapter approval native yang ringan untuk entrypoint channel hot |
| `plugin-sdk/approval-handler-runtime` | Helper runtime approval handler yang lebih luas; utamakan seam adapter/gateway yang lebih sempit jika itu sudah cukup |
| `plugin-sdk/approval-native-runtime` | Helper target approval native + account-binding |
| `plugin-sdk/approval-reply-runtime` | Helper payload balasan approval exec/plugin |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`, helper registri perintah, helper otorisasi pengirim |
| `plugin-sdk/command-status` | Builder pesan perintah/bantuan seperti `buildCommandsMessagePaginated` dan `buildHelpMessage` |
| `plugin-sdk/approval-auth-runtime` | Resolusi approver dan helper action-auth chat yang sama |
| `plugin-sdk/approval-client-runtime` | Helper profil/filter persetujuan exec native |
| `plugin-sdk/approval-delivery-runtime` | Adapter kemampuan/pengiriman persetujuan native |
| `plugin-sdk/approval-gateway-runtime` | Helper bersama untuk resolusi gateway persetujuan |
| `plugin-sdk/approval-handler-adapter-runtime` | Helper ringan untuk memuat adapter persetujuan native bagi entrypoint saluran panas |
| `plugin-sdk/approval-handler-runtime` | Helper runtime handler persetujuan yang lebih luas; utamakan seam adapter/gateway yang lebih sempit jika itu sudah cukup |
| `plugin-sdk/approval-native-runtime` | Helper target persetujuan native + account-binding |
| `plugin-sdk/approval-reply-runtime` | Helper payload balasan persetujuan exec/plugin |
| `plugin-sdk/command-auth-native` | Helper auth perintah native + session-target native |
| `plugin-sdk/command-detection` | Helper deteksi perintah bersama |
| `plugin-sdk/command-surface` | Normalisasi badan perintah dan helper permukaan perintah |
| `plugin-sdk/command-detection` | Helper bersama untuk deteksi perintah |
| `plugin-sdk/command-surface` | Normalisasi body perintah dan helper permukaan perintah |
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
| `plugin-sdk/channel-secret-runtime` | Helper pengumpulan secret-contract yang sempit untuk permukaan secret channel/plugin |
| `plugin-sdk/secret-ref-runtime` | Helper `coerceSecretRef` dan pengetikan SecretRef yang sempit untuk parsing secret-contract/config |
| `plugin-sdk/security-runtime` | Helper trust, DM gating, konten eksternal, dan pengumpulan secret bersama |
| `plugin-sdk/ssrf-policy` | Helper kebijakan SSRF host allowlist dan jaringan privat |
| `plugin-sdk/channel-secret-runtime` | Helper pengumpulan secret-contract yang sempit untuk permukaan secret saluran/plugin |
| `plugin-sdk/secret-ref-runtime` | Helper pengetikan `coerceSecretRef` dan SecretRef yang sempit untuk parsing secret-contract/config |
| `plugin-sdk/security-runtime` | Helper bersama untuk trust, DM gating, konten eksternal, dan pengumpulan secret |
| `plugin-sdk/ssrf-policy` | Helper kebijakan SSRF untuk allowlist host dan jaringan privat |
| `plugin-sdk/ssrf-dispatcher` | Helper pinned-dispatcher yang sempit tanpa permukaan runtime infra yang luas |
| `plugin-sdk/ssrf-runtime` | Helper pinned-dispatcher, fetch yang dijaga SSRF, dan kebijakan SSRF |
| `plugin-sdk/ssrf-runtime` | Helper pinned-dispatcher, fetch yang dilindungi SSRF, dan kebijakan SSRF |
| `plugin-sdk/secret-input` | Helper parsing input secret |
| `plugin-sdk/webhook-ingress` | Helper permintaan/target Webhook |
| `plugin-sdk/webhook-request-guards` | Helper ukuran body/timeout permintaan |
@ -189,192 +190,192 @@ secara eksplisit mempromosikan salah satunya sebagai publik.
| Subpath | Ekspor utama |
| --- | --- |
| `plugin-sdk/runtime` | Helper runtime/logging/backup/instalasi plugin yang luas |
| `plugin-sdk/runtime-env` | Helper env runtime, logger, timeout, retry, dan backoff yang sempit |
| `plugin-sdk/channel-runtime-context` | Helper registrasi dan pencarian runtime-context channel generik |
| `plugin-sdk/runtime-env` | Helper sempit untuk env runtime, logger, timeout, retry, dan backoff |
| `plugin-sdk/channel-runtime-context` | Helper generik untuk pendaftaran dan lookup konteks runtime saluran |
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
| `plugin-sdk/plugin-runtime` | Helper perintah/hook/http/interaktif plugin bersama |
| `plugin-sdk/hook-runtime` | Helper pipeline Webhook/hook internal bersama |
| `plugin-sdk/plugin-runtime` | Helper bersama untuk perintah/hook/http/interaktif plugin |
| `plugin-sdk/hook-runtime` | Helper bersama untuk pipeline hook Webhook/internal |
| `plugin-sdk/lazy-runtime` | Helper impor/binding runtime lazy seperti `createLazyRuntimeModule`, `createLazyRuntimeMethod`, dan `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | Helper eksekusi proses |
| `plugin-sdk/cli-runtime` | Helper format, wait, dan versi CLI |
| `plugin-sdk/gateway-runtime` | Helper klien Gateway dan patch status channel |
| `plugin-sdk/config-runtime` | Helper pemuatan/penulisan config |
| `plugin-sdk/telegram-command-config` | Normalisasi nama/deskripsi perintah Telegram dan pemeriksaan duplikat/konflik, bahkan ketika permukaan kontrak Telegram bawaan tidak tersedia |
| `plugin-sdk/process-runtime` | Helper exec proses |
| `plugin-sdk/cli-runtime` | Helper pemformatan, penantian, dan versi CLI |
| `plugin-sdk/gateway-runtime` | Helper klien Gateway dan patch status saluran |
| `plugin-sdk/config-runtime` | Helper muat/tulis konfigurasi |
| `plugin-sdk/telegram-command-config` | Normalisasi nama/deskripsi perintah Telegram dan pemeriksaan duplikat/konflik, bahkan saat permukaan kontrak Telegram bawaan tidak tersedia |
| `plugin-sdk/text-autolink-runtime` | Deteksi autolink referensi file tanpa barrel text-runtime yang luas |
| `plugin-sdk/approval-runtime` | Helper approval exec/plugin, pembangun kemampuan approval, helper auth/profil, helper routing/runtime native |
| `plugin-sdk/reply-runtime` | Helper runtime masuk/balasan bersama, chunking, dispatch, Heartbeat, perencana balasan |
| `plugin-sdk/reply-dispatch-runtime` | Helper dispatch/finalisasi balasan yang sempit |
| `plugin-sdk/reply-history` | Helper riwayat balasan jendela pendek bersama seperti `buildHistoryContext`, `recordPendingHistoryEntry`, dan `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/approval-runtime` | Helper persetujuan exec/plugin, builder kemampuan persetujuan, helper auth/profil, helper routing/runtime native |
| `plugin-sdk/reply-runtime` | Helper runtime inbound/balasan bersama, chunking, dispatch, Heartbeat, perencana balasan |
| `plugin-sdk/reply-dispatch-runtime` | Helper sempit untuk dispatch/finalisasi balasan |
| `plugin-sdk/reply-history` | Helper bersama untuk riwayat balasan jendela pendek seperti `buildHistoryContext`, `recordPendingHistoryEntry`, dan `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
| `plugin-sdk/reply-chunking` | Helper chunking teks/markdown yang sempit |
| `plugin-sdk/session-store-runtime` | Helper path session store + updated-at |
| `plugin-sdk/state-paths` | Helper path direktori state/OAuth |
| `plugin-sdk/routing` | Helper route/session-key/account binding seperti `resolveAgentRoute`, `buildAgentSessionKey`, dan `resolveDefaultAgentBoundAccountId` |
| `plugin-sdk/status-helpers` | Helper ringkasan status channel/akun bersama, default state runtime, dan helper metadata issue |
| `plugin-sdk/target-resolver-runtime` | Helper target resolver bersama |
| `plugin-sdk/reply-chunking` | Helper sempit untuk chunking teks/markdown |
| `plugin-sdk/session-store-runtime` | Helper jalur penyimpanan sesi + updated-at |
| `plugin-sdk/state-paths` | Helper jalur direktori state/OAuth |
| `plugin-sdk/routing` | Helper binding route/session-key/akun seperti `resolveAgentRoute`, `buildAgentSessionKey`, dan `resolveDefaultAgentBoundAccountId` |
| `plugin-sdk/status-helpers` | Helper bersama untuk ringkasan status saluran/akun, default status runtime, dan helper metadata isu |
| `plugin-sdk/target-resolver-runtime` | Helper resolver target bersama |
| `plugin-sdk/string-normalization-runtime` | Helper normalisasi slug/string |
| `plugin-sdk/request-url` | Ekstrak URL string dari input mirip fetch/request |
| `plugin-sdk/run-command` | Runner perintah bertimer dengan hasil stdout/stderr yang dinormalisasi |
| `plugin-sdk/param-readers` | Pembaca param tool/CLI umum |
| `plugin-sdk/run-command` | Runner perintah bertimed dengan hasil stdout/stderr yang dinormalisasi |
| `plugin-sdk/param-readers` | Pembaca param umum untuk tool/CLI |
| `plugin-sdk/tool-payload` | Ekstrak payload yang dinormalisasi dari objek hasil tool |
| `plugin-sdk/tool-send` | Ekstrak field target pengiriman kanonis dari argumen tool |
| `plugin-sdk/temp-path` | Helper path unduhan sementara bersama |
| `plugin-sdk/tool-send` | Ekstrak field target kirim kanonis dari argumen tool |
| `plugin-sdk/temp-path` | Helper bersama untuk jalur unduhan sementara |
| `plugin-sdk/logging-core` | Helper logger subsistem dan redaksi |
| `plugin-sdk/markdown-table-runtime` | Helper mode tabel Markdown |
| `plugin-sdk/json-store` | Helper kecil baca/tulis state JSON |
| `plugin-sdk/json-store` | Helper kecil untuk baca/tulis state JSON |
| `plugin-sdk/file-lock` | Helper file-lock re-entrant |
| `plugin-sdk/persistent-dedupe` | Helper cache dedupe berbasis disk |
| `plugin-sdk/acp-runtime` | Helper runtime/sesi ACP dan reply-dispatch |
| `plugin-sdk/acp-binding-resolve-runtime` | Resolusi binding ACP hanya-baca tanpa impor startup siklus hidup |
| `plugin-sdk/agent-config-primitives` | Primitif skema config runtime agen yang sempit |
| `plugin-sdk/acp-runtime` | Helper ACP runtime/sesi dan reply-dispatch |
| `plugin-sdk/acp-binding-resolve-runtime` | Resolusi binding ACP hanya-baca tanpa impor startup lifecycle |
| `plugin-sdk/agent-config-primitives` | Primitive skema konfigurasi runtime agen yang sempit |
| `plugin-sdk/boolean-param` | Pembaca param boolean longgar |
| `plugin-sdk/dangerous-name-runtime` | Helper resolusi pencocokan nama berbahaya |
| `plugin-sdk/device-bootstrap` | Helper bootstrap perangkat dan token pairing |
| `plugin-sdk/extension-shared` | Primitif helper pasif-channel, status, dan proxy ambient bersama |
| `plugin-sdk/models-provider-runtime` | Helper balasan perintah `/models`/provider |
| `plugin-sdk/skill-commands-runtime` | Helper daftar perintah Skills |
| `plugin-sdk/native-command-registry` | Helper registrasi/build/serialisasi perintah native |
| `plugin-sdk/agent-harness` | Permukaan trusted-plugin eksperimental untuk agent harness level rendah: tipe harness, helper steer/abort active-run, helper bridge tool OpenClaw, dan utilitas hasil upaya |
| `plugin-sdk/provider-zai-endpoint` | Helper deteksi endpoint Z.A.I |
| `plugin-sdk/extension-shared` | Primitive helper bersama untuk passive-channel, status, dan proxy ambient |
| `plugin-sdk/models-provider-runtime` | Helper balasan perintah `/models`/penyedia |
| `plugin-sdk/skill-commands-runtime` | Helper daftar perintah skill |
| `plugin-sdk/native-command-registry` | Helper registri/build/serialisasi perintah native |
| `plugin-sdk/agent-harness` | Permukaan plugin tepercaya eksperimental untuk harness agen level rendah: tipe harness, helper steer/abort active-run, helper bridge tool OpenClaw, dan utilitas hasil upaya |
| `plugin-sdk/provider-zai-endpoint` | Helper deteksi endpoint Z.AI |
| `plugin-sdk/infra-runtime` | Helper event sistem/Heartbeat |
| `plugin-sdk/collection-runtime` | Helper cache kecil yang dibatasi |
| `plugin-sdk/diagnostic-runtime` | Helper flag dan event diagnostik |
| `plugin-sdk/error-runtime` | Helper graf error, pemformatan, klasifikasi error bersama, `isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | Helper fetch terbungkus, proxy, dan pencarian pinned |
| `plugin-sdk/runtime-fetch` | Fetch runtime yang sadar-dispatcher tanpa impor proxy/guarded-fetch |
| `plugin-sdk/error-runtime` | Graf error, pemformatan, helper klasifikasi error bersama, `isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | Helper fetch terbungkus, proxy, dan pinned lookup |
| `plugin-sdk/runtime-fetch` | Fetch runtime yang sadar dispatcher tanpa impor proxy/guarded-fetch |
| `plugin-sdk/response-limit-runtime` | Pembaca body respons terbatas tanpa permukaan media runtime yang luas |
| `plugin-sdk/session-binding-runtime` | State binding percakapan saat ini tanpa routing binding terkonfigurasi atau pairing store |
| `plugin-sdk/session-store-runtime` | Helper baca session-store tanpa impor penulisan/pemeliharaan config yang luas |
| `plugin-sdk/context-visibility-runtime` | Resolusi visibilitas konteks dan pemfilteran konteks tambahan tanpa impor config/keamanan yang luas |
| `plugin-sdk/string-coerce-runtime` | Helper sempit untuk record/string primitif, coercion, dan normalisasi tanpa impor markdown/logging |
| `plugin-sdk/session-binding-runtime` | Status binding percakapan saat ini tanpa routing configured-binding atau store pairing |
| `plugin-sdk/session-store-runtime` | Helper baca session-store tanpa impor penulisan/pemeliharaan konfigurasi yang luas |
| `plugin-sdk/context-visibility-runtime` | Resolusi visibilitas konteks dan pemfilteran konteks tambahan tanpa impor konfigurasi/keamanan yang luas |
| `plugin-sdk/string-coerce-runtime` | Helper sempit untuk koersi dan normalisasi primitive record/string tanpa impor markdown/logging |
| `plugin-sdk/host-runtime` | Helper normalisasi hostname dan host SCP |
| `plugin-sdk/retry-runtime` | Helper config retry dan runner retry |
| `plugin-sdk/retry-runtime` | Helper konfigurasi retry dan runner retry |
| `plugin-sdk/agent-runtime` | Helper direktori/identitas/workspace agen |
| `plugin-sdk/directory-runtime` | Query/dedupe direktori berbasis config |
| `plugin-sdk/directory-runtime` | Kueri/dedupe direktori berbasis konfigurasi |
| `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
</Accordion>
<Accordion title="Subpath kemampuan dan pengujian">
<Accordion title="Subpath kapabilitas dan pengujian">
| Subpath | Ekspor utama |
| --- | --- |
| `plugin-sdk/media-runtime` | Helper fetch/transform/store media bersama ditambah pembangun payload media |
| `plugin-sdk/media-generation-runtime` | Helper failover media-generation bersama, pemilihan kandidat, dan pesan model hilang |
| `plugin-sdk/media-understanding` | Tipe provider media understanding ditambah ekspor helper image/audio untuk provider |
| `plugin-sdk/text-runtime` | Helper teks/markdown/logging bersama seperti penghapusan teks yang terlihat oleh asisten, helper render/chunking/tabel Markdown, helper redaksi, helper directive-tag, dan utilitas safe-text |
| `plugin-sdk/text-chunking` | Helper chunking teks keluar |
| `plugin-sdk/speech` | Tipe provider speech ditambah helper directive, registry, dan validasi untuk provider |
| `plugin-sdk/speech-core` | Tipe provider speech bersama, registry, directive, dan helper normalisasi |
| `plugin-sdk/realtime-transcription` | Tipe provider realtime transcription dan helper registry |
| `plugin-sdk/realtime-voice` | Tipe provider realtime voice dan helper registry |
| `plugin-sdk/image-generation` | Tipe provider image generation |
| `plugin-sdk/image-generation-core` | Tipe image-generation bersama, failover, auth, dan helper registry |
| `plugin-sdk/music-generation` | Tipe provider/permintaan/hasil music generation |
| `plugin-sdk/music-generation-core` | Tipe music-generation bersama, helper failover, pencarian provider, dan parsing model-ref |
| `plugin-sdk/video-generation` | Tipe provider/permintaan/hasil video generation |
| `plugin-sdk/video-generation-core` | Tipe video-generation bersama, helper failover, pencarian provider, dan parsing model-ref |
| `plugin-sdk/webhook-targets` | Helper registrasi target Webhook dan instalasi route |
| `plugin-sdk/webhook-path` | Helper normalisasi path Webhook |
| `plugin-sdk/web-media` | Helper pemuatan media jarak jauh/lokal bersama |
| `plugin-sdk/zod` | `zod` yang diekspor ulang untuk konsumen plugin SDK |
| `plugin-sdk/media-runtime` | Helper bersama untuk fetch/transform/store media ditambah builder payload media |
| `plugin-sdk/media-generation-runtime` | Helper bersama untuk failover pembuatan media, pemilihan kandidat, dan pesan model yang hilang |
| `plugin-sdk/media-understanding` | Tipe penyedia media understanding ditambah ekspor helper gambar/audio yang menghadap penyedia |
| `plugin-sdk/text-runtime` | Helper bersama untuk teks/markdown/logging seperti penghapusan teks yang terlihat oleh asisten, helper render/chunking/tabel Markdown, helper redaksi, helper directive-tag, dan utilitas safe-text |
| `plugin-sdk/text-chunking` | Helper chunking teks outbound |
| `plugin-sdk/speech` | Tipe penyedia speech ditambah helper directive, registri, dan validasi yang menghadap penyedia |
| `plugin-sdk/speech-core` | Helper bersama untuk tipe penyedia speech, registri, directive, dan normalisasi |
| `plugin-sdk/realtime-transcription` | Tipe penyedia transkripsi realtime dan helper registri |
| `plugin-sdk/realtime-voice` | Tipe penyedia suara realtime dan helper registri |
| `plugin-sdk/image-generation` | Tipe penyedia pembuatan gambar |
| `plugin-sdk/image-generation-core` | Helper bersama untuk tipe, failover, auth, dan registri image-generation |
| `plugin-sdk/music-generation` | Tipe penyedia/permintaan/hasil pembuatan musik |
| `plugin-sdk/music-generation-core` | Helper bersama untuk tipe music-generation, failover, lookup penyedia, dan parsing model-ref |
| `plugin-sdk/video-generation` | Tipe penyedia/permintaan/hasil pembuatan video |
| `plugin-sdk/video-generation-core` | Helper bersama untuk tipe video-generation, failover, lookup penyedia, dan parsing model-ref |
| `plugin-sdk/webhook-targets` | Registri target Webhook dan helper instalasi route |
| `plugin-sdk/webhook-path` | Helper normalisasi jalur Webhook |
| `plugin-sdk/web-media` | Helper bersama untuk memuat media remote/lokal |
| `plugin-sdk/zod` | `zod` yang diekspor ulang untuk konsumen SDK plugin |
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` |
</Accordion>
<Accordion title="Subpath Memory">
<Accordion title="Subpath memori">
| Subpath | Ekspor utama |
| --- | --- |
| `plugin-sdk/memory-core` | Permukaan helper memory-core bawaan untuk helper manager/config/file/CLI |
| `plugin-sdk/memory-core-engine-runtime` | Fasad runtime indeks/pencarian Memory |
| `plugin-sdk/memory-core-host-engine-foundation` | Ekspor engine foundation host Memory |
| `plugin-sdk/memory-core-host-engine-embeddings` | Kontrak embedding host Memory, akses registry, provider lokal, dan helper batch/jarak jauh generik |
| `plugin-sdk/memory-core-host-engine-qmd` | Ekspor engine QMD host Memory |
| `plugin-sdk/memory-core-host-engine-storage` | Ekspor engine storage host Memory |
| `plugin-sdk/memory-core-host-multimodal` | Helper multimodal host Memory |
| `plugin-sdk/memory-core-host-query` | Helper kueri host Memory |
| `plugin-sdk/memory-core-host-secret` | Helper secret host Memory |
| `plugin-sdk/memory-core-host-events` | Helper jurnal event host Memory |
| `plugin-sdk/memory-core-host-status` | Helper status host Memory |
| `plugin-sdk/memory-core-host-runtime-cli` | Helper runtime CLI host Memory |
| `plugin-sdk/memory-core-host-runtime-core` | Helper runtime core host Memory |
| `plugin-sdk/memory-core-host-runtime-files` | Helper file/runtime host Memory |
| `plugin-sdk/memory-host-core` | Alias netral-vendor untuk helper runtime core host Memory |
| `plugin-sdk/memory-host-events` | Alias netral-vendor untuk helper jurnal event host Memory |
| `plugin-sdk/memory-host-files` | Alias netral-vendor untuk helper file/runtime host Memory |
| `plugin-sdk/memory-host-markdown` | Helper managed-markdown bersama untuk plugin yang berdekatan dengan memory |
| `plugin-sdk/memory-core` | Permukaan helper memory-core bawaan untuk helper manajer/konfigurasi/file/CLI |
| `plugin-sdk/memory-core-engine-runtime` | Fasad runtime indeks/pencarian memori |
| `plugin-sdk/memory-core-host-engine-foundation` | Ekspor engine fondasi host memori |
| `plugin-sdk/memory-core-host-engine-embeddings` | Kontrak embedding host memori, akses registri, penyedia lokal, dan helper batch/remote generik |
| `plugin-sdk/memory-core-host-engine-qmd` | Ekspor engine QMD host memori |
| `plugin-sdk/memory-core-host-engine-storage` | Ekspor engine penyimpanan host memori |
| `plugin-sdk/memory-core-host-multimodal` | Helper multimodal host memori |
| `plugin-sdk/memory-core-host-query` | Helper kueri host memori |
| `plugin-sdk/memory-core-host-secret` | Helper secret host memori |
| `plugin-sdk/memory-core-host-events` | Helper jurnal event host memori |
| `plugin-sdk/memory-core-host-status` | Helper status host memori |
| `plugin-sdk/memory-core-host-runtime-cli` | Helper runtime CLI host memori |
| `plugin-sdk/memory-core-host-runtime-core` | Helper runtime inti host memori |
| `plugin-sdk/memory-core-host-runtime-files` | Helper file/runtime host memori |
| `plugin-sdk/memory-host-core` | Alias netral-vendor untuk helper runtime inti host memori |
| `plugin-sdk/memory-host-events` | Alias netral-vendor untuk helper jurnal event host memori |
| `plugin-sdk/memory-host-files` | Alias netral-vendor untuk helper file/runtime host memori |
| `plugin-sdk/memory-host-markdown` | Helper managed-markdown bersama untuk plugin yang berdekatan dengan memori |
| `plugin-sdk/memory-host-search` | Fasad runtime Active Memory untuk akses search-manager |
| `plugin-sdk/memory-host-status` | Alias netral-vendor untuk helper status host Memory |
| `plugin-sdk/memory-host-status` | Alias netral-vendor untuk helper status host memori |
| `plugin-sdk/memory-lancedb` | Permukaan helper memory-lancedb bawaan |
</Accordion>
<Accordion title="Subpath helper-bawaan yang dicadangkan">
<Accordion title="Subpath helper bawaan yang dicadangkan">
| Family | Subpath saat ini | Penggunaan yang dimaksudkan |
| --- | --- | --- |
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Helper dukungan plugin Browser bawaan (`browser-support` tetap menjadi barrel kompatibilitas) |
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Helper dukungan plugin browser bawaan (`browser-support` tetap menjadi compatibility barrel) |
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Permukaan helper/runtime Matrix bawaan |
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Permukaan helper/runtime LINE bawaan |
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Permukaan helper IRC bawaan |
| Helper khusus channel | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Seam kompatibilitas/helper channel bawaan |
| Helper khusus auth/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Seam helper fitur/plugin bawaan; `plugin-sdk/github-copilot-token` saat ini mengekspor `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken`, dan `resolveCopilotApiToken` |
| Helper khusus saluran | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Seam kompatibilitas/helper saluran bawaan |
| Helper auth/plugin khusus | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Seam helper fitur/plugin bawaan; `plugin-sdk/github-copilot-token` saat ini mengekspor `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken`, dan `resolveCopilotApiToken` |
</Accordion>
</AccordionGroup>
## API registrasi
## API pendaftaran
Callback `register(api)` menerima objek `OpenClawPluginApi` dengan metode-metode
berikut:
### Registrasi kemampuan
### Pendaftaran kapabilitas
| Metode | Yang didaftarkan |
| Method | Yang didaftarkan |
| ------------------------------------------------ | -------------------------------------- |
| `api.registerProvider(...)` | Inferensi teks (LLM) |
| `api.registerAgentHarness(...)` | Eksekutor agen tingkat rendah eksperimental |
| `api.registerAgentHarness(...)` | Eksekutor agen level rendah eksperimental |
| `api.registerCliBackend(...)` | Backend inferensi CLI lokal |
| `api.registerChannel(...)` | Channel perpesanan |
| `api.registerChannel(...)` | Saluran perpesanan |
| `api.registerSpeechProvider(...)` | Text-to-speech / sintesis STT |
| `api.registerRealtimeTranscriptionProvider(...)` | Transkripsi realtime streaming |
| `api.registerRealtimeVoiceProvider(...)` | Sesi suara realtime dupleks |
| `api.registerRealtimeVoiceProvider(...)` | Sesi suara realtime duplex |
| `api.registerMediaUnderstandingProvider(...)` | Analisis gambar/audio/video |
| `api.registerImageGenerationProvider(...)` | Pembuatan gambar |
| `api.registerMusicGenerationProvider(...)` | Pembuatan musik |
| `api.registerVideoGenerationProvider(...)` | Pembuatan video |
| `api.registerWebFetchProvider(...)` | Provider fetch / scrape web |
| `api.registerWebFetchProvider(...)` | Penyedia fetch / scrape web |
| `api.registerWebSearchProvider(...)` | Pencarian web |
### Tool dan perintah
| Metode | Yang didaftarkan |
| ------------------------------- | --------------------------------------------- |
| `api.registerTool(tool, opts?)` | Tool agen (wajib atau `{ optional: true }`) |
| `api.registerCommand(def)` | Perintah kustom (melewati LLM) |
| Method | Yang didaftarkan |
| ------------------------------- | ----------------------------------------------- |
| `api.registerTool(tool, opts?)` | Tool agen (wajib atau `{ optional: true }`) |
| `api.registerCommand(def)` | Perintah kustom (melewati LLM) |
### Infrastruktur
| Metode | Yang didaftarkan |
| ---------------------------------------------- | --------------------------------------- |
| `api.registerHook(events, handler, opts?)` | Hook event |
| `api.registerHttpRoute(params)` | endpoint HTTP Gateway |
| `api.registerGatewayMethod(name, handler)` | metode RPC Gateway |
| `api.registerCli(registrar, opts?)` | subperintah CLI |
| `api.registerService(service)` | layanan latar belakang |
| `api.registerInteractiveHandler(registration)` | handler interaktif |
| `api.registerMemoryPromptSupplement(builder)` | Bagian prompt aditif yang berdekatan dengan memory |
| `api.registerMemoryCorpusSupplement(adapter)` | Korpus pencarian/baca memory aditif |
| Method | Yang didaftarkan |
| ---------------------------------------------- | ------------------------------------ |
| `api.registerHook(events, handler, opts?)` | Hook event |
| `api.registerHttpRoute(params)` | Endpoint HTTP Gateway |
| `api.registerGatewayMethod(name, handler)` | Metode RPC Gateway |
| `api.registerCli(registrar, opts?)` | Subperintah CLI |
| `api.registerService(service)` | Layanan latar belakang |
| `api.registerInteractiveHandler(registration)` | Handler interaktif |
| `api.registerMemoryPromptSupplement(builder)` | Bagian prompt tambahan yang berdekatan dengan memori |
| `api.registerMemoryCorpusSupplement(adapter)` | Korpus pencarian/baca memori tambahan |
Namespace admin core yang dicadangkan (`config.*`, `exec.approvals.*`, `wizard.*`,
Namespace admin inti yang dicadangkan (`config.*`, `exec.approvals.*`, `wizard.*`,
`update.*`) selalu tetap `operator.admin`, meskipun plugin mencoba menetapkan
cakupan metode Gateway yang lebih sempit. Utamakan prefix khusus plugin untuk
metode yang dimiliki plugin.
### Metadata registrasi CLI
### Metadata pendaftaran CLI
`api.registerCli(registrar, opts?)` menerima dua jenis metadata level atas:
`api.registerCli(registrar, opts?)` menerima dua jenis metadata tingkat atas:
- `commands`: root perintah eksplisit yang dimiliki oleh registrar
- `descriptors`: deskriptor perintah saat parse yang digunakan untuk bantuan CLI root,
routing, dan registrasi CLI plugin lazy
routing, dan pendaftaran CLI plugin secara lazy
Jika Anda ingin perintah plugin tetap dimuat secara lazy di jalur CLI root normal,
berikan `descriptors` yang mencakup setiap root perintah level atas yang diekspos oleh
berikan `descriptors` yang mencakup setiap root perintah tingkat atas yang diekspos oleh
registrar tersebut.
```typescript
@ -395,86 +396,85 @@ api.registerCli(
);
```
Gunakan `commands` saja hanya ketika Anda tidak memerlukan registrasi CLI root yang lazy.
Gunakan `commands` saja hanya ketika Anda tidak memerlukan pendaftaran CLI root secara lazy.
Jalur kompatibilitas eager itu tetap didukung, tetapi tidak memasang
placeholder berbasis descriptor untuk pemuatan lazy saat parse.
placeholder berbasis descriptor untuk lazy loading saat parse.
### Registrasi backend CLI
### Pendaftaran backend CLI
`api.registerCliBackend(...)` memungkinkan plugin memiliki config default untuk
`api.registerCliBackend(...)` memungkinkan plugin memiliki konfigurasi default untuk
backend CLI AI lokal seperti `codex-cli`.
- `id` backend menjadi prefix provider dalam model ref seperti `codex-cli/gpt-5`.
- `config` backend menggunakan bentuk yang sama dengan `agents.defaults.cliBackends.<id>`.
- Config pengguna tetap menang. OpenClaw menggabungkan `agents.defaults.cliBackends.<id>` di atas
- `id` backend menjadi prefix penyedia dalam model ref 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.
- Gunakan `normalizeConfig` ketika backend memerlukan penulisan ulang kompatibilitas setelah penggabungan
(misalnya menormalkan bentuk flag lama).
### Slot eksklusif
| Metode | Yang didaftarkan |
| Method | Yang didaftarkan |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api.registerContextEngine(id, factory)` | Engine konteks (satu aktif pada satu waktu). Callback `assemble()` menerima `availableTools` dan `citationsMode` agar engine dapat menyesuaikan tambahan prompt. |
| `api.registerMemoryCapability(capability)` | Kemampuan memory terpadu |
| `api.registerMemoryPromptSection(builder)` | Pembuat bagian prompt memory |
| `api.registerMemoryFlushPlan(resolver)` | Resolver rencana flush memory |
| `api.registerMemoryRuntime(runtime)` | Adapter runtime memory |
| `api.registerContextEngine(id, factory)` | Engine konteks (hanya satu yang aktif pada satu waktu). Callback `assemble()` menerima `availableTools` dan `citationsMode` agar engine 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 memory
### Adapter embedding memori
| Metode | Yang didaftarkan |
| ---------------------------------------------- | ---------------------------------------------- |
| `api.registerMemoryEmbeddingProvider(adapter)` | Adapter embedding memory untuk plugin aktif |
| Method | Yang didaftarkan |
| ---------------------------------------------- | -------------------------------------------- |
| `api.registerMemoryEmbeddingProvider(adapter)` | Adapter embedding memori untuk plugin aktif |
- `registerMemoryCapability` adalah API plugin memory eksklusif yang diutamakan.
- `registerMemoryCapability` adalah API plugin memori eksklusif yang diutamakan.
- `registerMemoryCapability` juga dapat mengekspos `publicArtifacts.listArtifacts(...)`
agar plugin pendamping dapat menggunakan artefak memory yang diekspor melalui
`openclaw/plugin-sdk/memory-host-core` alih-alih menjangkau layout privat
plugin memory tertentu.
sehingga plugin pendamping dapat menggunakan artefak memori yang diekspor melalui
`openclaw/plugin-sdk/memory-host-core` alih-alih menjangkau tata letak privat
plugin memori tertentu.
- `registerMemoryPromptSection`, `registerMemoryFlushPlan`, dan
`registerMemoryRuntime` adalah API plugin memory eksklusif yang kompatibel
dengan versi lama.
- `registerMemoryEmbeddingProvider` memungkinkan plugin memory aktif mendaftarkan satu
atau lebih id adapter embedding (misalnya `openai`, `gemini`, atau id kustom
`registerMemoryRuntime` adalah API plugin memori eksklusif yang kompatibel dengan sistem lama.
- `registerMemoryEmbeddingProvider` memungkinkan plugin memori aktif mendaftarkan satu
atau lebih ID adapter embedding (misalnya `openai`, `gemini`, atau ID khusus
yang didefinisikan plugin).
- Config pengguna seperti `agents.defaults.memorySearch.provider` dan
`agents.defaults.memorySearch.fallback` diresolusikan terhadap id adapter yang
terdaftar tersebut.
- Konfigurasi pengguna seperti `agents.defaults.memorySearch.provider` dan
`agents.defaults.memorySearch.fallback` diresolusikan terhadap ID adapter
yang terdaftar tersebut.
### Event dan siklus hidup
| Metode | Fungsinya |
| -------------------------------------------- | ----------------------------- |
| `api.on(hookName, handler, opts?)` | Hook siklus hidup bertipe |
| `api.onConversationBindingResolved(handler)` | Callback binding percakapan |
| Method | Fungsinya |
| -------------------------------------------- | ---------------------------- |
| `api.on(hookName, handler, opts?)` | Hook siklus hidup bertipe |
| `api.onConversationBindingResolved(handler)` | Callback binding percakapan |
### Semantik keputusan hook
- `before_tool_call`: mengembalikan `{ block: true }` bersifat terminal. Setelah ada handler yang menetapkannya, handler dengan prioritas lebih rendah dilewati.
- `before_tool_call`: mengembalikan `{ block: false }` diperlakukan sebagai tidak ada keputusan (sama seperti menghilangkan `block`), bukan sebagai override.
- `before_tool_call`: mengembalikan `{ block: false }` dianggap tidak ada keputusan (sama seperti menghilangkan `block`), bukan sebagai override.
- `before_install`: mengembalikan `{ block: true }` bersifat terminal. Setelah ada handler yang menetapkannya, handler dengan prioritas lebih rendah dilewati.
- `before_install`: mengembalikan `{ block: false }` diperlakukan sebagai tidak ada keputusan (sama seperti menghilangkan `block`), bukan sebagai override.
- `before_install`: mengembalikan `{ block: false }` dianggap tidak ada keputusan (sama seperti menghilangkan `block`), bukan sebagai override.
- `reply_dispatch`: mengembalikan `{ handled: true, ... }` bersifat terminal. Setelah ada handler yang mengklaim dispatch, handler dengan prioritas lebih rendah dan jalur dispatch model default dilewati.
- `message_sending`: mengembalikan `{ cancel: true }` bersifat terminal. Setelah ada handler yang menetapkannya, handler dengan prioritas lebih rendah dilewati.
- `message_sending`: mengembalikan `{ cancel: false }` diperlakukan sebagai tidak ada keputusan (sama seperti menghilangkan `cancel`), bukan sebagai override.
- `message_sending`: mengembalikan `{ cancel: false }` dianggap tidak ada keputusan (sama seperti menghilangkan `cancel`), bukan sebagai override.
### Field objek API
| Field | Tipe | Deskripsi |
| Field | Type | Deskripsi |
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------ |
| `api.id` | `string` | id plugin |
| `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` | Path sumber plugin |
| `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.config` | `OpenClawConfig` | Snapshot konfigurasi saat ini (snapshot runtime dalam memori yang aktif bila tersedia) |
| `api.pluginConfig` | `Record<string, unknown>` | Konfigurasi khusus plugin dari `plugins.entries.<id>.config` |
| `api.runtime` | `PluginRuntime` | [Helper runtime](/id/plugins/sdk-runtime) |
| `api.logger` | `PluginLogger` | Logger berskala (`debug`, `info`, `warn`, `error`) |
| `api.registrationMode` | `PluginRegistrationMode` | Mode pemuatan saat ini; `"setup-runtime"` adalah jendela startup/setup ringan sebelum full-entry |
| `api.resolvePath(input)` | `(string) => string` | Resolve path relatif terhadap root plugin |
| `api.logger` | `PluginLogger` | Logger dengan cakupan terbatas (`debug`, `info`, `warn`, `error`) |
| `api.registrationMode` | `PluginRegistrationMode` | Mode pemuatan saat ini; `"setup-runtime"` adalah jendela startup/penyiapan ringan sebelum entri penuh |
| `api.resolvePath(input)` | `(string) => string` | Resolusikan jalur relatif terhadap root plugin |
## Konvensi modul internal
@ -484,47 +484,47 @@ Di dalam plugin Anda, gunakan file barrel lokal untuk impor internal:
my-plugin/
api.ts # Ekspor publik untuk konsumen eksternal
runtime-api.ts # Ekspor runtime khusus internal
index.ts # Entry point plugin
setup-entry.ts # Entri khusus setup yang ringan (opsional)
index.ts # Titik masuk plugin
setup-entry.ts # Entri ringan khusus penyiapan (opsional)
```
<Warning>
Jangan pernah mengimpor plugin Anda sendiri melalui `openclaw/plugin-sdk/<your-plugin>`
dari kode production. Rute impor internal harus melalui `./api.ts` atau
`./runtime-api.ts`. Path SDK hanya merupakan kontrak eksternal.
dari kode produksi. Arahkan impor internal melalui `./api.ts` atau
`./runtime-api.ts`. Jalur SDK hanya merupakan kontrak eksternal.
</Warning>
Permukaan publik plugin bawaan yang dimuat lewat facade (`api.ts`, `runtime-api.ts`,
Permukaan publik plugin bawaan yang dimuat melalui fasad (`api.ts`, `runtime-api.ts`,
`index.ts`, `setup-entry.ts`, dan file entri publik serupa) sekarang mengutamakan
snapshot config runtime aktif ketika OpenClaw sudah berjalan. Jika belum ada snapshot
runtime, mereka akan fallback ke file config yang sudah di-resolve di disk.
snapshot konfigurasi runtime aktif ketika OpenClaw sudah berjalan. Jika belum ada snapshot
runtime, permukaan tersebut akan menggunakan fallback ke file konfigurasi yang telah diresolusikan di disk.
Plugin provider juga dapat mengekspos barrel kontrak lokal-plugin yang sempit ketika sebuah
helper memang khusus provider dan belum pantas dimasukkan ke subpath SDK
generik. Contoh bawaan saat ini: provider Anthropic menyimpan helper stream Claude
Plugin penyedia juga dapat mengekspos barrel kontrak lokal plugin yang sempit ketika
helper memang sengaja khusus untuk penyedia dan belum layak dimasukkan ke subpath
SDK generik. Contoh bawaan saat ini: penyedia Anthropic menyimpan helper stream Claude
di seam publik `api.ts` / `contract-api.ts` miliknya sendiri alih-alih
mempromosikan header beta Anthropic dan logika `service_tier` ke kontrak
menaikkan logika header beta Anthropic dan `service_tier` ke kontrak
`plugin-sdk/*` generik.
Contoh bawaan saat ini lainnya:
- `@openclaw/openai-provider`: `api.ts` mengekspor pembangun provider,
helper default-model, dan pembangun provider realtime
- `@openclaw/openrouter-provider`: `api.ts` mengekspor pembangun provider serta
helper onboarding/config
- `@openclaw/openai-provider`: `api.ts` mengekspor builder penyedia,
helper model default, dan builder penyedia realtime
- `@openclaw/openrouter-provider`: `api.ts` mengekspor builder penyedia serta
helper onboarding/konfigurasi
<Warning>
Kode production extension juga harus menghindari impor `openclaw/plugin-sdk/<other-plugin>`.
Jika suatu helper benar-benar dibagikan, promosikan ke subpath SDK netral
Kode produksi extension juga sebaiknya menghindari impor `openclaw/plugin-sdk/<other-plugin>`.
Jika suatu helper benar-benar digunakan bersama, pindahkan ke subpath SDK netral
seperti `openclaw/plugin-sdk/speech`, `.../provider-model-shared`, atau
permukaan lain yang berorientasi kemampuan alih-alih mengaitkan dua plugin secara langsung.
permukaan lain yang berorientasi kapabilitas alih-alih menggabungkan dua plugin secara erat.
</Warning>
## Terkait
- [Entry Points](/id/plugins/sdk-entrypoints) — opsi `definePluginEntry` dan `defineChannelPluginEntry`
- [Helper Runtime](/id/plugins/sdk-runtime) — referensi lengkap namespace `api.runtime`
- [Setup dan Config](/id/plugins/sdk-setup) — packaging, manifest, skema config
- [Runtime Helpers](/id/plugins/sdk-runtime) — referensi namespace `api.runtime` lengkap
- [Setup and Config](/id/plugins/sdk-setup) — packaging, manifes, skema konfigurasi
- [Testing](/id/plugins/sdk-testing) — utilitas pengujian dan aturan lint
- [Migrasi SDK](/id/plugins/sdk-migration) — migrasi dari permukaan yang sudah deprecated
- [Internal Plugin](/id/plugins/architecture) — arsitektur mendalam dan model kemampuan
- [SDK Migration](/id/plugins/sdk-migration) — migrasi dari permukaan yang sudah usang
- [Plugin Internals](/id/plugins/architecture) — arsitektur mendalam dan model kapabilitas

View File

@ -1,14 +1,14 @@
---
read_when:
- Anda ingin menggunakan model Google Gemini dengan OpenClaw
- Anda memerlukan kunci API atau alur autentikasi OAuth
- Anda memerlukan alur autentikasi kunci API atau OAuth
summary: Penyiapan Google Gemini (kunci API + OAuth, pembuatan gambar, pemahaman media, TTS, pencarian web)
title: Google (Gemini)
x-i18n:
generated_at: "2026-04-16T09:14:37Z"
generated_at: "2026-04-19T01:11:33Z"
model: gpt-5.4
provider: openai
source_hash: ec2d62855f5e80efda758aad71bcaa95c38b1e41761fa1100d47a06c62881419
source_hash: e5e055b02cc51899e11836a882f1f981fedfa5c4dbe42261ac2f2eba5e4d707c
source_path: providers/google.md
workflow: 15
---
@ -26,11 +26,11 @@ Gemini Grounding.
## Memulai
Pilih metode autentikasi yang Anda inginkan dan ikuti langkah-langkah penyiapan.
Pilih metode autentikasi yang Anda inginkan dan ikuti langkah-langkah penyiapannya.
<Tabs>
<Tab title="Kunci API">
**Terbaik untuk:** akses API Gemini standar melalui Google AI Studio.
<Tab title="API key">
**Paling cocok untuk:** akses API Gemini standar melalui Google AI Studio.
<Steps>
<Step title="Jalankan onboarding">
@ -38,7 +38,7 @@ Pilih metode autentikasi yang Anda inginkan dan ikuti langkah-langkah penyiapan.
openclaw onboard --auth-choice gemini-api-key
```
Atau berikan kunci secara langsung:
Atau berikan key secara langsung:
```bash
openclaw onboard --non-interactive \
@ -66,13 +66,13 @@ Pilih metode autentikasi yang Anda inginkan dan ikuti langkah-langkah penyiapan.
</Steps>
<Tip>
Variabel lingkungan `GEMINI_API_KEY` dan `GOOGLE_API_KEY` keduanya didukung. Gunakan mana saja yang sudah Anda konfigurasi.
Variabel lingkungan `GEMINI_API_KEY` dan `GOOGLE_API_KEY` keduanya didukung. Gunakan mana pun yang sudah Anda konfigurasi.
</Tip>
</Tab>
<Tab title="Gemini CLI (OAuth)">
**Terbaik untuk:** menggunakan kembali login Gemini CLI yang sudah ada melalui PKCE OAuth alih-alih kunci API terpisah.
**Paling cocok untuk:** menggunakan kembali login Gemini CLI yang sudah ada melalui PKCE OAuth alih-alih key API terpisah.
<Warning>
Provider `google-gemini-cli` adalah integrasi tidak resmi. Beberapa pengguna
@ -92,7 +92,7 @@ Pilih metode autentikasi yang Anda inginkan dan ikuti langkah-langkah penyiapan.
```
OpenClaw mendukung instalasi Homebrew dan instalasi npm global, termasuk
tata letak umum Windows/npm.
tata letak Windows/npm yang umum.
</Step>
<Step title="Masuk melalui OAuth">
```bash
@ -123,11 +123,11 @@ Pilih metode autentikasi yang Anda inginkan dan ikuti langkah-langkah penyiapan.
<Note>
Jika login gagal sebelum alur browser dimulai, pastikan perintah lokal `gemini`
terinstal dan ada di `PATH`.
sudah terinstal dan ada di `PATH`.
</Note>
Provider `google-gemini-cli` yang hanya mendukung OAuth adalah
surface inferensi teks terpisah. Pembuatan gambar, pemahaman media, dan Gemini Grounding tetap berada pada
Provider `google-gemini-cli` yang hanya OAuth adalah surface inferensi teks
yang terpisah. Pembuatan gambar, pemahaman media, dan Gemini Grounding tetap berada pada
id provider `google`.
</Tab>
@ -135,23 +135,28 @@ Pilih metode autentikasi yang Anda inginkan dan ikuti langkah-langkah penyiapan.
## Kemampuan
| Kemampuan | Didukung |
| ---------------------- | ----------------- |
| Penyelesaian chat | Ya |
| Pembuatan gambar | Ya |
| Pembuatan musik | Ya |
| Text-to-speech | Ya |
| Pemahaman gambar | Ya |
| Transkripsi audio | Ya |
| Pemahaman video | Ya |
| Pencarian web (Grounding) | Ya |
| Thinking/reasoning | Ya (Gemini 3.1+) |
| Model Gemma 4 | Ya |
| Capability | Supported |
| ---------------------- | ----------------------------- |
| Chat completions | Ya |
| Image generation | Ya |
| Music generation | Ya |
| Text-to-speech | Ya |
| Image understanding | Ya |
| Audio transcription | Ya |
| Video understanding | Ya |
| Web search (Grounding) | Ya |
| Thinking/reasoning | Ya (Gemini 2.5+ / Gemini 3+) |
| Gemma 4 models | Ya |
<Tip>
Model Gemini 3 menggunakan `thinkingLevel` alih-alih `thinkingBudget`. OpenClaw memetakan
kontrol penalaran untuk alias Gemini 3, Gemini 3.1, dan `gemini-*-latest` ke
`thinkingLevel` sehingga eksekusi default/latensi-rendah tidak mengirim
nilai `thinkingBudget` yang dinonaktifkan.
Model Gemma 4 (misalnya `gemma-4-26b-a4b-it`) mendukung mode thinking. OpenClaw
menulis ulang `thinkingBudget` menjadi `thinkingLevel` Google yang didukung untuk Gemma 4.
Menetapkan thinking ke `off` akan mempertahankan thinking dalam keadaan nonaktif alih-alih memetakannya ke
Mengatur thinking ke `off` mempertahankan thinking tetap dinonaktifkan alih-alih memetakannya ke
`MINIMAL`.
</Tip>
@ -161,8 +166,8 @@ Provider pembuatan gambar `google` bawaan secara default menggunakan
`google/gemini-3.1-flash-image-preview`.
- Juga mendukung `google/gemini-3-pro-image-preview`
- Hasilkan: hingga 4 gambar per permintaan
- Mode edit: diaktifkan, hingga 5 gambar masukan
- Generate: hingga 4 gambar per permintaan
- Mode edit: diaktifkan, hingga 5 gambar input
- Kontrol geometri: `size`, `aspectRatio`, dan `resolution`
Untuk menggunakan Google sebagai provider gambar default:
@ -180,16 +185,16 @@ Untuk menggunakan Google sebagai provider gambar default:
```
<Note>
Lihat [Pembuatan Gambar](/id/tools/image-generation) untuk parameter alat bersama, pemilihan provider, dan perilaku failover.
Lihat [Image Generation](/id/tools/image-generation) untuk parameter tool bersama, pemilihan provider, dan perilaku failover.
</Note>
## Pembuatan video
Plugin `google` bawaan juga mendaftarkan pembuatan video melalui alat bersama
Plugin `google` bawaan juga mendaftarkan pembuatan video melalui tool bersama
`video_generate`.
- Model video default: `google/veo-3.1-fast-generate-preview`
- Mode: text-to-video, image-to-video, dan alur referensi satu video
- Mode: text-to-video, image-to-video, dan alur referensi video tunggal
- Mendukung `aspectRatio`, `resolution`, dan `audio`
- Batas durasi saat ini: **4 hingga 8 detik**
@ -208,20 +213,20 @@ Untuk menggunakan Google sebagai provider video default:
```
<Note>
Lihat [Pembuatan Video](/id/tools/video-generation) untuk parameter alat bersama, pemilihan provider, dan perilaku failover.
Lihat [Video Generation](/id/tools/video-generation) untuk parameter tool bersama, pemilihan provider, dan perilaku failover.
</Note>
## Pembuatan musik
Plugin `google` bawaan juga mendaftarkan pembuatan musik melalui alat bersama
Plugin `google` bawaan juga mendaftarkan pembuatan musik melalui tool bersama
`music_generate`.
- Model musik default: `google/lyria-3-clip-preview`
- Juga mendukung `google/lyria-3-pro-preview`
- Kontrol prompt: `lyrics` dan `instrumental`
- Format keluaran: `mp3` secara default, ditambah `wav` pada `google/lyria-3-pro-preview`
- Masukan referensi: hingga 10 gambar
- Proses berbasis sesi dilepas melalui alur tugas/status bersama, termasuk `action: "status"`
- Format output: `mp3` secara default, serta `wav` pada `google/lyria-3-pro-preview`
- Input referensi: hingga 10 gambar
- Eksekusi berbasis sesi dipisahkan melalui alur task/status bersama, termasuk `action: "status"`
Untuk menggunakan Google sebagai provider musik default:
@ -238,18 +243,18 @@ Untuk menggunakan Google sebagai provider musik default:
```
<Note>
Lihat [Pembuatan Musik](/id/tools/music-generation) untuk parameter alat bersama, pemilihan provider, dan perilaku failover.
Lihat [Music Generation](/id/tools/music-generation) untuk parameter tool bersama, pemilihan provider, dan perilaku failover.
</Note>
## Text-to-speech
Provider ucapan `google` bawaan menggunakan jalur TTS Google Gemini API dengan
Provider speech `google` bawaan menggunakan jalur Gemini API TTS dengan
`gemini-3.1-flash-tts-preview`.
- Suara default: `Kore`
- Auth: `messages.tts.providers.google.apiKey`, `models.providers.google.apiKey`, `GEMINI_API_KEY`, atau `GOOGLE_API_KEY`
- Keluaran: WAV untuk lampiran TTS biasa, PCM untuk Talk/teleponi
- Keluaran catatan suara native: tidak didukung pada jalur Gemini API ini karena API mengembalikan PCM, bukan Opus
- Output: WAV untuk lampiran TTS biasa, PCM untuk Talk/telephony
- Output voice note native: tidak didukung pada jalur Gemini API ini karena API mengembalikan PCM, bukan Opus
Untuk menggunakan Google sebagai provider TTS default:
@ -270,8 +275,8 @@ Untuk menggunakan Google sebagai provider TTS default:
}
```
Gemini API TTS menerima tag audio ekspresif dalam tanda kurung siku di dalam teks, seperti
`[whispers]` atau `[laughs]`. Agar tag tidak muncul di balasan chat yang terlihat sambil
Gemini API TTS menerima tag audio ekspresif dalam tanda kurung siku di teks, seperti
`[whispers]` atau `[laughs]`. Untuk menjaga agar tag tidak muncul di balasan chat yang terlihat sambil
tetap mengirimkannya ke TTS, letakkan tag tersebut di dalam blok `[[tts:text]]...[[/tts:text]]`:
```text
@ -281,7 +286,7 @@ Berikut adalah teks balasan yang bersih.
```
<Note>
Kunci API Google Cloud Console yang dibatasi untuk Gemini API valid untuk
Key API Google Cloud Console yang dibatasi ke Gemini API valid untuk
provider ini. Ini bukan jalur Cloud Text-to-Speech API yang terpisah.
</Note>
@ -289,15 +294,15 @@ provider ini. Ini bukan jalur Cloud Text-to-Speech API yang terpisah.
<AccordionGroup>
<Accordion title="Penggunaan ulang cache Gemini langsung">
Untuk proses Gemini API langsung (`api: "google-generative-ai"`), OpenClaw
Untuk eksekusi Gemini API langsung (`api: "google-generative-ai"`), OpenClaw
meneruskan handle `cachedContent` yang dikonfigurasi ke permintaan Gemini.
- Konfigurasikan parameter per model atau global dengan
`cachedContent` atau `cached_content` lama
- Jika keduanya ada, `cachedContent` yang diprioritaskan
- Jika keduanya ada, `cachedContent` akan diprioritaskan
- Contoh nilai: `cachedContents/prebuilt-context`
- Penggunaan cache-hit Gemini dinormalisasi menjadi `cacheRead` OpenClaw dari
`cachedContentTokenCount` upstream
- Penggunaan cache-hit Gemini dinormalisasi ke OpenClaw `cacheRead` dari
upstream `cachedContentTokenCount`
```json5
{
@ -319,12 +324,12 @@ provider ini. Ini bukan jalur Cloud Text-to-Speech API yang terpisah.
<Accordion title="Catatan penggunaan JSON Gemini CLI">
Saat menggunakan provider OAuth `google-gemini-cli`, OpenClaw menormalisasi
keluaran JSON CLI sebagai berikut:
output JSON CLI sebagai berikut:
- Teks balasan berasal dari field `response` pada JSON CLI.
- Penggunaan akan menggunakan `stats` jika CLI membiarkan `usage` kosong.
- `stats.cached` dinormalisasi menjadi `cacheRead` OpenClaw.
- Jika `stats.input` tidak ada, OpenClaw menurunkan token masukan dari
- Teks balasan berasal dari field CLI JSON `response`.
- Usage menggunakan fallback ke `stats` saat CLI membiarkan `usage` kosong.
- `stats.cached` dinormalisasi menjadi OpenClaw `cacheRead`.
- Jika `stats.input` tidak ada, OpenClaw menurunkan token input dari
`stats.input_tokens - stats.cached`.
</Accordion>
@ -340,15 +345,15 @@ provider ini. Ini bukan jalur Cloud Text-to-Speech API yang terpisah.
<CardGroup cols={2}>
<Card title="Pemilihan model" href="/id/concepts/model-providers" icon="layers">
Memilih provider, referensi model, dan perilaku failover.
Memilih provider, ref model, dan perilaku failover.
</Card>
<Card title="Pembuatan gambar" href="/id/tools/image-generation" icon="image">
Parameter alat gambar bersama dan pemilihan provider.
Parameter tool gambar bersama dan pemilihan provider.
</Card>
<Card title="Pembuatan video" href="/id/tools/video-generation" icon="video">
Parameter alat video bersama dan pemilihan provider.
Parameter tool video bersama dan pemilihan provider.
</Card>
<Card title="Pembuatan musik" href="/id/tools/music-generation" icon="music">
Parameter alat musik bersama dan pemilihan provider.
Parameter tool musik bersama dan pemilihan provider.
</Card>
</CardGroup>