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

chore(i18n): refresh id translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-06 09:18:04 +00:00
parent 5c84c4bc6d
commit 868e6002af
8 changed files with 1549 additions and 1399 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

524
docs/id/channels/matrix.md
View File

@ -1,48 +1,48 @@
---
read_when:
- Menyiapkan Matrix di OpenClaw
- Mengonfigurasi E2EE dan verifikasi Matrix
- Mengonfigurasi Matrix E2EE dan verifikasi
summary: Status dukungan Matrix, penyiapan, dan contoh konfigurasi
title: Matrix
x-i18n:
generated_at: "2026-04-06T03:07:57Z"
generated_at: "2026-04-06T09:15:09Z"
model: gpt-5.4
provider: openai
source_hash: 3e2d84c08d7d5b96db14b914e54f08d25334401cdd92eb890bc8dfb37b0ca2dc
source_hash: 06f833bf0ede81bad69f140994c32e8cc5d1635764f95fc5db4fc5dc25f2b85e
source_path: channels/matrix.md
workflow: 15
---
# Matrix
Matrix adalah plugin channel bawaan Matrix untuk OpenClaw.
Plugin ini menggunakan `matrix-js-sdk` resmi dan mendukung DM, room, thread, media, reaksi, polling, lokasi, dan E2EE.
Matrix adalah plugin saluran bawaan Matrix untuk OpenClaw.
Ini menggunakan `matrix-js-sdk` resmi dan mendukung DM, room, thread, media, reaksi, polling, lokasi, dan E2EE.
## Plugin bawaan
Matrix disertakan sebagai plugin bawaan dalam rilis OpenClaw saat ini, sehingga build paket normal tidak memerlukan instalasi terpisah.
Matrix dikirim sebagai plugin bawaan dalam rilis OpenClaw saat ini, jadi build paket normal tidak memerlukan pemasangan terpisah.
Jika Anda menggunakan build lama atau instalasi kustom yang tidak menyertakan Matrix, instal secara manual:
Jika Anda menggunakan build yang lebih lama atau pemasangan kustom yang mengecualikan Matrix, pasang secara manual:
Instal dari npm:
Pasang dari npm:
```bash
openclaw plugins install @openclaw/matrix
```
Instal dari checkout lokal:
Pasang dari checkout lokal:
```bash
openclaw plugins install ./path/to/local/matrix-plugin
```
Lihat [Plugins](/id/tools/plugin) untuk perilaku plugin dan aturan instalasi.
Lihat [Plugins](/id/tools/plugin) untuk perilaku plugin dan aturan pemasangan.
## Penyiapan
1. Pastikan plugin Matrix tersedia.
- Rilis OpenClaw paket saat ini sudah menyertakannya.
- Instalasi lama/kustom dapat menambahkannya secara manual dengan perintah di atas.
- Pemasangan lama/kustom dapat menambahkannya secara manual dengan perintah di atas.
2. Buat akun Matrix di homeserver Anda.
3. Konfigurasikan `channels.matrix` dengan salah satu dari:
- `homeserver` + `accessToken`, atau
@ -68,12 +68,12 @@ Yang sebenarnya ditanyakan wizard Matrix:
Perilaku wizard yang penting:
- Jika variabel env auth Matrix sudah ada untuk akun yang dipilih, dan akun tersebut belum memiliki auth yang disimpan di config, wizard menawarkan pintasan env dan hanya menulis `enabled: true` untuk akun tersebut.
- Jika variabel env auth Matrix sudah ada untuk akun yang dipilih, dan akun itu belum memiliki auth yang disimpan di config, wizard menawarkan pintasan env dan hanya menulis `enabled: true` untuk akun tersebut.
- Saat Anda menambahkan akun Matrix lain secara interaktif, nama akun yang dimasukkan dinormalisasi menjadi ID akun yang digunakan di config dan variabel env. Misalnya, `Ops Bot` menjadi `ops-bot`.
- Prompt allowlist DM langsung menerima nilai `@user:server` lengkap. Nama tampilan hanya berfungsi saat pencarian direktori live menemukan satu kecocokan yang persis; jika tidak, wizard meminta Anda mencoba lagi dengan ID Matrix lengkap.
- Prompt allowlist room langsung menerima ID room dan alias. Prompt ini juga dapat menyelesaikan nama room yang sudah diikuti secara live, tetapi nama yang tidak dapat diselesaikan hanya disimpan sebagaimana diketik saat penyiapan dan diabaikan nanti oleh resolusi allowlist runtime. Gunakan `!room:server` atau `#alias:server`.
- Identitas room/sesi runtime menggunakan ID room Matrix yang stabil. Alias yang dideklarasikan room hanya digunakan sebagai input pencarian, bukan sebagai kunci sesi jangka panjang atau identitas grup yang stabil.
- Untuk menyelesaikan nama room sebelum menyimpannya, gunakan `openclaw channels resolve --channel matrix "Project Room"`.
- Prompt allowlist DM langsung menerima nilai penuh `@user:server`. Nama tampilan hanya berfungsi jika pencarian direktori live menemukan satu kecocokan yang tepat; jika tidak, wizard meminta Anda mencoba lagi dengan ID Matrix lengkap.
- Prompt allowlist room langsung menerima ID room dan alias. Prompt ini juga dapat me-resolve nama room yang sudah bergabung secara live, tetapi nama yang tidak ter-resolve hanya disimpan sebagaimana diketik saat penyiapan dan diabaikan nanti oleh resolusi allowlist runtime. Gunakan `!room:server` atau `#alias:server`.
- Identitas room/sesi runtime menggunakan ID room Matrix yang stabil. Alias yang dideklarasikan room hanya digunakan sebagai input lookup, bukan sebagai kunci sesi jangka panjang atau identitas grup yang stabil.
- Untuk me-resolve nama room sebelum menyimpannya, gunakan `openclaw channels resolve --channel matrix "Project Room"`.
Penyiapan minimal berbasis token:
@ -106,11 +106,11 @@ Penyiapan berbasis password (token di-cache setelah login):
}
```
Matrix menyimpan kredensial cache di `~/.openclaw/credentials/matrix/`.
Matrix menyimpan kredensial yang di-cache di `~/.openclaw/credentials/matrix/`.
Akun default menggunakan `credentials.json`; akun bernama menggunakan `credentials-<account>.json`.
Ketika kredensial cache ada di sana, OpenClaw menganggap Matrix sudah dikonfigurasi untuk penyiapan, doctor, dan penemuan status channel meskipun auth saat ini tidak disetel langsung di config.
Jika kredensial yang di-cache ada di sana, OpenClaw memperlakukan Matrix sebagai sudah dikonfigurasi untuk penyiapan, doctor, dan penemuan status saluran meskipun auth saat ini tidak diatur langsung di config.
Padanan variabel env (digunakan saat kunci config tidak disetel):
Padanan variabel environment (digunakan ketika kunci config tidak diatur):
- `MATRIX_HOMESERVER`
- `MATRIX_ACCESS_TOKEN`
@ -119,7 +119,7 @@ Padanan variabel env (digunakan saat kunci config tidak disetel):
- `MATRIX_DEVICE_ID`
- `MATRIX_DEVICE_NAME`
Untuk akun non-default, gunakan variabel env berlingkup akun:
Untuk akun non-default, gunakan variabel env yang dicakup per akun:
- `MATRIX_<ACCOUNT_ID>_HOMESERVER`
- `MATRIX_<ACCOUNT_ID>_ACCESS_TOKEN`
@ -138,14 +138,14 @@ Untuk ID akun yang dinormalisasi `ops-bot`, gunakan:
- `MATRIX_OPS_X2D_BOT_HOMESERVER`
- `MATRIX_OPS_X2D_BOT_ACCESS_TOKEN`
Matrix melakukan escape pada tanda baca dalam ID akun agar variabel env berlingkup akun bebas tabrakan.
Matrix melakukan escape tanda baca dalam ID akun agar variabel env bercakup tetap bebas tabrakan.
Misalnya, `-` menjadi `_X2D_`, sehingga `ops-prod` dipetakan ke `MATRIX_OPS_X2D_PROD_*`.
Wizard interaktif hanya menawarkan pintasan variabel env saat variabel env auth tersebut sudah ada dan akun yang dipilih belum memiliki auth Matrix yang disimpan di config.
Wizard interaktif hanya menawarkan pintasan variabel env ketika variabel env auth tersebut sudah ada dan akun yang dipilih belum memiliki auth Matrix yang disimpan di config.
## Contoh konfigurasi
Ini adalah config baseline praktis dengan pairing DM, allowlist room, dan E2EE diaktifkan:
Ini adalah baseline config praktis dengan pairing DM, allowlist room, dan E2EE diaktifkan:
```json5
{
@ -180,12 +180,19 @@ Ini adalah config baseline praktis dengan pairing DM, allowlist room, dan E2EE d
}
```
`autoJoin` berlaku untuk undangan Matrix secara umum, bukan hanya undangan room/grup.
Itu mencakup undangan bergaya DM yang baru. Pada saat undangan, OpenClaw tidak dapat mengetahui dengan andal apakah
room yang diundang nantinya akan diperlakukan sebagai DM atau grup, sehingga semua undangan melewati keputusan
`autoJoin` yang sama terlebih dahulu. `dm.policy` tetap berlaku setelah bot bergabung dan room tersebut
diklasifikasikan sebagai DM, jadi `autoJoin` mengendalikan perilaku bergabung sementara `dm.policy` mengendalikan perilaku
balasan/akses.
## Pratinjau streaming
Streaming balasan Matrix bersifat opt-in.
Setel `channels.matrix.streaming` ke `"partial"` saat Anda ingin OpenClaw mengirim satu balasan pratinjau live,
mengedit pratinjau itu di tempat saat model sedang menghasilkan teks, lalu memfinalkannya saat
Atur `channels.matrix.streaming` ke `"partial"` ketika Anda ingin OpenClaw mengirim satu balasan pratinjau live,
mengedit pratinjau tersebut di tempat saat model sedang menghasilkan teks, lalu memfinalkannya ketika
balasan selesai:
```json5
@ -198,38 +205,38 @@ balasan selesai:
}
```
- `streaming: "off"` adalah default. OpenClaw menunggu balasan final dan mengirimkannya sekali.
- `streaming: "partial"` membuat satu pesan pratinjau yang dapat diedit untuk blok assistant saat ini menggunakan pesan teks Matrix normal. Ini mempertahankan perilaku notifikasi pratinjau-dahulu Matrix lama, sehingga klien bawaan mungkin memberi notifikasi pada teks pratinjau streaming pertama, bukan pada blok yang sudah selesai.
- `streaming: "quiet"` membuat satu pemberitahuan pratinjau senyap yang dapat diedit untuk blok assistant saat ini. Gunakan ini hanya jika Anda juga mengonfigurasi aturan push penerima untuk edit pratinjau yang sudah difinalkan.
- `blockStreaming: true` mengaktifkan pesan progres Matrix terpisah. Dengan streaming pratinjau aktif, Matrix mempertahankan draf live untuk blok saat ini dan mempertahankan blok yang selesai sebagai pesan terpisah.
- Saat streaming pratinjau aktif dan `blockStreaming` nonaktif, Matrix mengedit draf live di tempat dan memfinalkan event yang sama saat blok atau giliran selesai.
- `streaming: "off"` adalah default. OpenClaw menunggu balasan final dan mengirimkannya satu kali.
- `streaming: "partial"` membuat satu pesan pratinjau yang dapat diedit untuk blok asisten saat ini menggunakan pesan teks Matrix normal. Ini mempertahankan perilaku notifikasi lawas Matrix yang mengutamakan pratinjau, sehingga klien standar dapat memberi notifikasi pada teks pratinjau streaming pertama alih-alih pada blok yang selesai.
- `streaming: "quiet"` membuat satu pemberitahuan pratinjau senyap yang dapat diedit untuk blok asisten saat ini. Gunakan ini hanya jika Anda juga mengonfigurasi push rule penerima untuk edit pratinjau yang telah difinalkan.
- `blockStreaming: true` mengaktifkan pesan progres Matrix terpisah. Dengan streaming pratinjau aktif, Matrix mempertahankan draft live untuk blok saat ini dan mempertahankan blok yang sudah selesai sebagai pesan terpisah.
- Saat streaming pratinjau aktif dan `blockStreaming` nonaktif, Matrix mengedit draft live di tempat dan memfinalkan event yang sama saat blok atau giliran selesai.
- Jika pratinjau tidak lagi muat dalam satu event Matrix, OpenClaw menghentikan streaming pratinjau dan kembali ke pengiriman final normal.
- Balasan media tetap mengirim lampiran seperti biasa. Jika pratinjau lama tidak lagi dapat digunakan ulang dengan aman, OpenClaw menghapusnya sebelum mengirim balasan media final.
- Edit pratinjau menambah panggilan API Matrix. Biarkan streaming nonaktif jika Anda menginginkan perilaku rate limit yang paling konservatif.
- Balasan media tetap mengirim lampiran secara normal. Jika pratinjau usang tidak lagi dapat digunakan ulang dengan aman, OpenClaw akan meredaksinya sebelum mengirim balasan media final.
- Edit pratinjau memerlukan panggilan API Matrix tambahan. Biarkan streaming nonaktif jika Anda menginginkan perilaku rate limit yang paling konservatif.
`blockStreaming` tidak mengaktifkan pratinjau draf dengan sendirinya.
Gunakan `streaming: "partial"` atau `streaming: "quiet"` untuk edit pratinjau; lalu tambahkan `blockStreaming: true` hanya jika Anda juga ingin blok assistant yang sudah selesai tetap terlihat sebagai pesan progres terpisah.
`blockStreaming` tidak mengaktifkan pratinjau draft dengan sendirinya.
Gunakan `streaming: "partial"` atau `streaming: "quiet"` untuk edit pratinjau; lalu tambahkan `blockStreaming: true` hanya jika Anda juga ingin blok asisten yang telah selesai tetap terlihat sebagai pesan progres terpisah.
Jika Anda memerlukan notifikasi Matrix bawaan tanpa aturan push kustom, gunakan `streaming: "partial"` untuk perilaku pratinjau-dahulu atau biarkan `streaming` nonaktif untuk pengiriman final saja. Dengan `streaming: "off"`:
Jika Anda memerlukan notifikasi Matrix standar tanpa push rule kustom, gunakan `streaming: "partial"` untuk perilaku pratinjau-terlebih-dahulu atau biarkan `streaming` nonaktif untuk pengiriman final saja. Dengan `streaming: "off"`:
- `blockStreaming: true` mengirim setiap blok yang selesai sebagai pesan Matrix normal yang memicu notifikasi.
- `blockStreaming: false` hanya mengirim balasan akhir yang sudah selesai sebagai pesan Matrix normal yang memicu notifikasi.
- `blockStreaming: false` hanya mengirim balasan final yang telah selesai sebagai pesan Matrix normal yang memicu notifikasi.
### Aturan push self-hosted untuk pratinjau final senyap
### Push rule yang di-hosting sendiri untuk pratinjau final senyap
Jika Anda menjalankan infrastruktur Matrix sendiri dan ingin pratinjau senyap hanya memberi notifikasi saat suatu blok atau
balasan final selesai, setel `streaming: "quiet"` dan tambahkan aturan push per pengguna untuk edit pratinjau yang sudah difinalkan.
Jika Anda menjalankan infrastruktur Matrix sendiri dan ingin pratinjau senyap memberi notifikasi hanya saat blok atau
balasan final selesai, atur `streaming: "quiet"` dan tambahkan push rule per pengguna untuk edit pratinjau yang telah difinalkan.
Ini biasanya merupakan penyiapan pengguna penerima, bukan perubahan config global homeserver:
Biasanya ini adalah penyiapan pengguna penerima, bukan perubahan config global homeserver:
Pemetaan singkat sebelum mulai:
Peta cepat sebelum Anda memulai:
- pengguna penerima = orang yang harus menerima notifikasi
- pengguna penerima = orang yang seharusnya menerima notifikasi
- pengguna bot = akun Matrix OpenClaw yang mengirim balasan
- gunakan access token pengguna penerima untuk panggilan API di bawah
- cocokkan `sender` dalam aturan push dengan MXID lengkap pengguna bot
- gunakan access token pengguna penerima untuk panggilan API di bawah ini
- cocokkan `sender` dalam push rule dengan MXID lengkap pengguna bot
1. Konfigurasikan OpenClaw agar menggunakan pratinjau senyap:
1. Konfigurasikan OpenClaw untuk menggunakan pratinjau senyap:
```json5
{
@ -241,13 +248,13 @@ Pemetaan singkat sebelum mulai:
}
```
2. Pastikan akun penerima sudah menerima notifikasi push Matrix normal. Aturan
pratinjau senyap hanya berfungsi jika pengguna tersebut sudah memiliki pusher/perangkat yang berfungsi.
2. Pastikan akun penerima sudah menerima notifikasi push Matrix normal. Rule pratinjau senyap
hanya berfungsi jika pengguna tersebut sudah memiliki pusher/perangkat yang berfungsi.
3. Dapatkan access token pengguna penerima.
- Gunakan token pengguna penerima, bukan token bot.
- Menggunakan ulang token sesi klien yang sudah ada biasanya paling mudah.
- Jika Anda perlu membuat token baru, Anda dapat login melalui API Client-Server Matrix standar:
- Jika Anda perlu mencetak token baru, Anda dapat login melalui API Client-Server Matrix standar:
```bash
curl -sS -X POST \
@ -271,10 +278,10 @@ curl -sS \
"https://matrix.example.org/_matrix/client/v3/pushers"
```
Jika ini tidak mengembalikan pusher/perangkat aktif, perbaiki dulu notifikasi Matrix normal sebelum menambahkan
aturan OpenClaw di bawah.
Jika ini tidak mengembalikan pusher/perangkat aktif, perbaiki notifikasi Matrix normal terlebih dahulu sebelum menambahkan
rule OpenClaw di bawah ini.
OpenClaw menandai edit pratinjau khusus teks yang sudah difinalkan dengan:
OpenClaw menandai edit pratinjau final teks saja dengan:
```json
{
@ -282,7 +289,7 @@ OpenClaw menandai edit pratinjau khusus teks yang sudah difinalkan dengan:
}
```
5. Buat aturan push override untuk setiap akun penerima yang harus menerima notifikasi ini:
5. Buat override push rule untuk setiap akun penerima yang harus menerima notifikasi ini:
```bash
curl -sS -X PUT \
@ -312,25 +319,25 @@ curl -sS -X PUT \
}'
```
Ganti nilai berikut sebelum menjalankan perintah:
Ganti nilai berikut sebelum Anda menjalankan perintah:
- `https://matrix.example.org`: URL dasar homeserver Anda
- `$USER_ACCESS_TOKEN`: access token pengguna penerima
- `openclaw-finalized-preview-botname`: ID aturan yang unik untuk bot ini bagi pengguna penerima ini
- `openclaw-finalized-preview-botname`: ID rule yang unik untuk bot ini bagi pengguna penerima ini
- `@bot:example.org`: MXID bot Matrix OpenClaw Anda, bukan MXID pengguna penerima
Penting untuk penyiapan multi-bot:
- Aturan push menggunakan kunci `ruleId`. Menjalankan ulang `PUT` terhadap rule ID yang sama akan memperbarui aturan itu.
- Jika satu pengguna penerima harus menerima notifikasi dari beberapa akun bot Matrix OpenClaw, buat satu aturan per bot dengan rule ID unik untuk setiap kecocokan sender.
- Pola sederhana adalah `openclaw-finalized-preview-<botname>`, misalnya `openclaw-finalized-preview-ops` atau `openclaw-finalized-preview-support`.
- Push rule dikunci berdasarkan `ruleId`. Menjalankan ulang `PUT` terhadap rule ID yang sama akan memperbarui rule tersebut.
- Jika satu pengguna penerima harus menerima notifikasi untuk beberapa akun bot Matrix OpenClaw, buat satu rule per bot dengan rule ID unik untuk setiap kecocokan sender.
- Pola yang sederhana adalah `openclaw-finalized-preview-<botname>`, seperti `openclaw-finalized-preview-ops` atau `openclaw-finalized-preview-support`.
Aturan dievaluasi terhadap pengirim event:
Rule dievaluasi terhadap pengirim event:
- autentikasi dengan token pengguna penerima
- cocokkan `sender` dengan MXID bot OpenClaw
6. Verifikasi bahwa aturan ada:
6. Verifikasi bahwa rule ada:
```bash
curl -sS \
@ -338,10 +345,10 @@ curl -sS \
"https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname"
```
7. Uji balasan streaming. Dalam mode senyap, room seharusnya menampilkan pratinjau draf senyap dan edit final
di tempat seharusnya memberi notifikasi sekali saat blok atau giliran selesai.
7. Uji balasan yang di-stream. Dalam mode senyap, room seharusnya menampilkan pratinjau draft senyap dan
edit final di tempat seharusnya memberi notifikasi sekali saat blok atau giliran selesai.
Jika nanti Anda perlu menghapus aturan tersebut, hapus rule ID yang sama dengan token pengguna penerima:
Jika Anda perlu menghapus rule nanti, hapus rule ID yang sama dengan token pengguna penerima:
```bash
curl -sS -X DELETE \
@ -351,37 +358,37 @@ curl -sS -X DELETE \
Catatan:
- Buat aturan dengan access token pengguna penerima, bukan token bot.
- Aturan `override` baru yang ditentukan pengguna disisipkan di depan aturan suppress default, jadi tidak diperlukan parameter urutan tambahan.
- Ini hanya memengaruhi edit pratinjau khusus teks yang dapat difinalkan OpenClaw dengan aman di tempat. Fallback media dan fallback pratinjau lama tetap menggunakan pengiriman Matrix normal.
- Buat rule dengan access token pengguna penerima, bukan token bot.
- Rule `override` baru yang didefinisikan pengguna disisipkan sebelum rule penekanan default, jadi tidak diperlukan parameter urutan tambahan.
- Ini hanya memengaruhi edit pratinjau teks saja yang dapat difinalkan OpenClaw dengan aman di tempat. Fallback media dan fallback pratinjau usang tetap menggunakan pengiriman Matrix normal.
- Jika `GET /_matrix/client/v3/pushers` tidak menampilkan pusher, pengguna tersebut belum memiliki pengiriman push Matrix yang berfungsi untuk akun/perangkat ini.
#### Synapse
Untuk Synapse, penyiapan di atas biasanya sudah cukup dengan sendirinya:
- Tidak diperlukan perubahan `homeserver.yaml` khusus untuk notifikasi pratinjau OpenClaw yang sudah difinalkan.
- Jika deployment Synapse Anda sudah mengirim notifikasi push Matrix normal, token pengguna + panggilan `pushrules` di atas adalah langkah penyiapan utama.
- Jika Anda menjalankan Synapse di belakang reverse proxy atau worker, pastikan `/_matrix/client/.../pushrules/` menjangkau Synapse dengan benar.
- Jika Anda menjalankan worker Synapse, pastikan pusher dalam kondisi sehat. Pengiriman push ditangani oleh proses utama atau `synapse.app.pusher` / worker pusher yang dikonfigurasi.
- Tidak diperlukan perubahan `homeserver.yaml` khusus untuk notifikasi pratinjau OpenClaw yang telah difinalkan.
- Jika deployment Synapse Anda sudah mengirim notifikasi push Matrix normal, token pengguna + panggilan `pushrules` di atas adalah langkah penyiapan utamanya.
- Jika Anda menjalankan Synapse di balik reverse proxy atau worker, pastikan `/_matrix/client/.../pushrules/` mencapai Synapse dengan benar.
- Jika Anda menjalankan worker Synapse, pastikan pusher sehat. Pengiriman push ditangani oleh proses utama atau `synapse.app.pusher` / worker pusher yang dikonfigurasi.
#### Tuwunel
Untuk Tuwunel, gunakan alur penyiapan dan panggilan API push-rule yang sama seperti di atas:
Untuk Tuwunel, gunakan alur penyiapan dan panggilan API push-rule yang sama seperti yang ditampilkan di atas:
- Tidak diperlukan config khusus Tuwunel untuk penanda pratinjau yang sudah difinalkan itu sendiri.
- Jika notifikasi Matrix normal sudah berfungsi untuk pengguna tersebut, token pengguna + panggilan `pushrules` di atas adalah langkah penyiapan utama.
- Jika notifikasi tampak hilang saat pengguna aktif di perangkat lain, periksa apakah `suppress_push_when_active` diaktifkan. Tuwunel menambahkan opsi ini di Tuwunel 1.4.2 pada 12 September 2025, dan ini dapat dengan sengaja menekan push ke perangkat lain saat satu perangkat aktif.
- Tidak diperlukan config khusus Tuwunel untuk penanda pratinjau final itu sendiri.
- Jika notifikasi Matrix normal sudah berfungsi untuk pengguna tersebut, token pengguna + panggilan `pushrules` di atas adalah langkah penyiapan utamanya.
- Jika notifikasi tampak menghilang saat pengguna aktif di perangkat lain, periksa apakah `suppress_push_when_active` diaktifkan. Tuwunel menambahkan opsi ini di Tuwunel 1.4.2 pada 12 September 2025, dan opsi ini dapat dengan sengaja menekan push ke perangkat lain saat satu perangkat aktif.
## Enkripsi dan verifikasi
Di room terenkripsi (E2EE), event gambar keluar menggunakan `thumbnail_file` sehingga pratinjau gambar dienkripsi bersama lampiran penuh. Room yang tidak terenkripsi tetap menggunakan `thumbnail_url` biasa. Tidak diperlukan konfigurasi — plugin mendeteksi status E2EE secara otomatis.
Di room terenkripsi (E2EE), event gambar keluar menggunakan `thumbnail_file` sehingga pratinjau gambar dienkripsi bersama lampiran penuhnya. Room yang tidak terenkripsi tetap menggunakan `thumbnail_url` biasa. Tidak diperlukan konfigurasi — plugin mendeteksi status E2EE secara otomatis.
### Room bot ke bot
Secara default, pesan Matrix dari akun Matrix OpenClaw lain yang dikonfigurasi diabaikan.
Secara default, pesan Matrix dari akun Matrix OpenClaw lain yang telah dikonfigurasi diabaikan.
Gunakan `allowBots` saat Anda memang ingin lalu lintas Matrix antar-agent:
Gunakan `allowBots` ketika Anda memang menginginkan lalu lintas Matrix antar agen:
```json5
{
@ -398,13 +405,13 @@ Gunakan `allowBots` saat Anda memang ingin lalu lintas Matrix antar-agent:
}
```
- `allowBots: true` menerima pesan dari akun bot Matrix lain yang dikonfigurasi di room dan DM yang diizinkan.
- `allowBots: "mentions"` menerima pesan tersebut hanya saat secara terlihat menyebut bot ini di room. DM tetap diizinkan.
- `groups.<room>.allowBots` menimpa setelan tingkat akun untuk satu room.
- `allowBots: true` menerima pesan dari akun bot Matrix terkonfigurasi lain di room dan DM yang diizinkan.
- `allowBots: "mentions"` menerima pesan tersebut hanya ketika mereka secara terlihat menyebut bot ini di room. DM tetap diizinkan.
- `groups.<room>.allowBots` menimpa pengaturan tingkat akun untuk satu room.
- OpenClaw tetap mengabaikan pesan dari ID pengguna Matrix yang sama untuk menghindari loop balasan ke diri sendiri.
- Matrix tidak mengekspos penanda bot bawaan di sini; OpenClaw menganggap "ditulis bot" sebagai "dikirim oleh akun Matrix lain yang dikonfigurasi pada gateway OpenClaw ini".
- Matrix tidak mengekspos penanda bot bawaan di sini; OpenClaw memperlakukan "ditulis bot" sebagai "dikirim oleh akun Matrix lain yang dikonfigurasi pada gateway OpenClaw ini".
Gunakan allowlist room yang ketat dan persyaratan mention saat mengaktifkan lalu lintas bot ke bot di room bersama.
Gunakan allowlist room yang ketat dan persyaratan mention saat mengaktifkan lalu lintas bot-ke-bot di room bersama.
Aktifkan enkripsi:
@ -434,13 +441,13 @@ Status verbose (diagnostik lengkap):
openclaw matrix verify status --verbose
```
Sertakan recovery key yang disimpan dalam output yang dapat dibaca mesin:
Sertakan recovery key yang tersimpan dalam output yang dapat dibaca mesin:
```bash
openclaw matrix verify status --include-recovery-key --json
```
Bootstrap cross-signing dan status verifikasi:
Bootstrap status cross-signing dan verifikasi:
```bash
openclaw matrix verify bootstrap
@ -498,18 +505,18 @@ openclaw matrix verify backup restore --verbose
Hapus backup server saat ini dan buat baseline backup baru. Jika backup key yang tersimpan
tidak dapat dimuat dengan bersih, reset ini juga dapat membuat ulang secret storage sehingga
cold start berikutnya dapat memuat backup key yang baru:
cold start di masa mendatang dapat memuat backup key yang baru:
```bash
openclaw matrix verify backup reset --yes
```
Semua perintah `verify` ringkas secara default (termasuk logging SDK internal yang senyap) dan hanya menampilkan diagnostik detail dengan `--verbose`.
Gunakan `--json` untuk output lengkap yang dapat dibaca mesin saat melakukan scripting.
Semua perintah `verify` ringkas secara default (termasuk logging SDK internal yang senyap) dan hanya menampilkan diagnostik terperinci dengan `--verbose`.
Gunakan `--json` untuk output lengkap yang dapat dibaca mesin saat membuat skrip.
Dalam penyiapan multi-akun, perintah CLI Matrix menggunakan akun default Matrix implisit kecuali Anda meneruskan `--account <id>`.
Jika Anda mengonfigurasi beberapa akun bernama, setel `channels.matrix.defaultAccount` terlebih dahulu atau operasi CLI implisit tersebut akan berhenti dan meminta Anda memilih akun secara eksplisit.
Gunakan `--account` kapan pun Anda ingin operasi verifikasi atau perangkat menargetkan akun bernama secara eksplisit:
Dalam penyiapan multi-akun, perintah CLI Matrix menggunakan akun default Matrix implisit kecuali Anda memberikan `--account <id>`.
Jika Anda mengonfigurasi beberapa akun bernama, atur `channels.matrix.defaultAccount` terlebih dahulu atau operasi CLI implisit tersebut akan berhenti dan meminta Anda memilih akun secara eksplisit.
Gunakan `--account` setiap kali Anda ingin operasi verifikasi atau perangkat menargetkan akun bernama secara eksplisit:
```bash
openclaw matrix verify status --account assistant
@ -517,43 +524,43 @@ openclaw matrix verify backup restore --account assistant
openclaw matrix devices list --account assistant
```
Saat enkripsi dinonaktifkan atau tidak tersedia untuk akun bernama, peringatan Matrix dan error verifikasi mengarah ke kunci config akun tersebut, misalnya `channels.matrix.accounts.assistant.encryption`.
Saat enkripsi dinonaktifkan atau tidak tersedia untuk akun bernama, peringatan Matrix dan kesalahan verifikasi menunjuk ke kunci config akun tersebut, misalnya `channels.matrix.accounts.assistant.encryption`.
### Arti "terverifikasi"
### Arti "verified"
OpenClaw menganggap perangkat Matrix ini terverifikasi hanya saat perangkat itu diverifikasi oleh identitas cross-signing Anda sendiri.
OpenClaw memperlakukan perangkat Matrix ini sebagai terverifikasi hanya ketika perangkat ini diverifikasi oleh identitas cross-signing Anda sendiri.
Dalam praktiknya, `openclaw matrix verify status --verbose` mengekspos tiga sinyal kepercayaan:
- `Locally trusted`: perangkat ini dipercaya hanya oleh klien saat ini
- `Cross-signing verified`: SDK melaporkan perangkat ini sebagai terverifikasi melalui cross-signing
- `Signed by owner`: perangkat ditandatangani oleh self-signing key Anda sendiri
- `Signed by owner`: perangkat ini ditandatangani oleh self-signing key Anda sendiri
`Verified by owner` menjadi `yes` hanya saat verifikasi cross-signing atau owner-signing ada.
Kepercayaan lokal saja tidak cukup bagi OpenClaw untuk menganggap perangkat ini sepenuhnya terverifikasi.
`Verified by owner` menjadi `yes` hanya ketika verifikasi cross-signing atau owner-signing ada.
Kepercayaan lokal saja tidak cukup bagi OpenClaw untuk memperlakukan perangkat sebagai sepenuhnya terverifikasi.
### Apa yang dilakukan bootstrap
`openclaw matrix verify bootstrap` adalah perintah perbaikan dan penyiapan untuk akun Matrix terenkripsi.
Perintah ini melakukan semua hal berikut secara berurutan:
- mem-bootstrap secret storage, menggunakan ulang recovery key yang ada bila memungkinkan
- mem-bootstrap cross-signing dan mengunggah public cross-signing key yang belum ada
- mencoba menandai dan cross-sign perangkat saat ini
- melakukan bootstrap secret storage, menggunakan ulang recovery key yang sudah ada bila memungkinkan
- melakukan bootstrap cross-signing dan mengunggah public cross-signing key yang belum ada
- mencoba menandai dan melakukan cross-sign pada perangkat saat ini
- membuat backup room-key sisi server baru jika belum ada
Jika homeserver memerlukan auth interaktif untuk mengunggah cross-signing key, OpenClaw mencoba unggahan tanpa auth terlebih dahulu, lalu dengan `m.login.dummy`, lalu dengan `m.login.password` saat `channels.matrix.password` dikonfigurasi.
Jika homeserver memerlukan auth interaktif untuk mengunggah cross-signing key, OpenClaw mencoba unggah tanpa auth terlebih dahulu, lalu dengan `m.login.dummy`, lalu dengan `m.login.password` ketika `channels.matrix.password` dikonfigurasi.
Gunakan `--force-reset-cross-signing` hanya jika Anda memang ingin membuang identitas cross-signing saat ini dan membuat yang baru.
Gunakan `--force-reset-cross-signing` hanya ketika Anda memang ingin membuang identitas cross-signing saat ini dan membuat yang baru.
Jika Anda memang ingin membuang backup room-key saat ini dan memulai baseline
backup baru untuk pesan mendatang, gunakan `openclaw matrix verify backup reset --yes`.
Lakukan ini hanya jika Anda menerima bahwa riwayat terenkripsi lama yang tidak dapat dipulihkan akan tetap
Jika Anda memang ingin membuang backup room-key saat ini dan memulai baseline backup baru
untuk pesan mendatang, gunakan `openclaw matrix verify backup reset --yes`.
Lakukan ini hanya ketika Anda menerima bahwa riwayat terenkripsi lama yang tidak dapat dipulihkan akan tetap
tidak tersedia dan bahwa OpenClaw mungkin akan membuat ulang secret storage jika secret backup saat ini
tidak dapat dimuat dengan aman.
### Baseline backup baru
Jika Anda ingin menjaga agar pesan terenkripsi mendatang tetap berfungsi dan menerima kehilangan riwayat lama yang tidak dapat dipulihkan, jalankan perintah berikut secara berurutan:
Jika Anda ingin menjaga pesan terenkripsi mendatang tetap berfungsi dan menerima kehilangan riwayat lama yang tidak dapat dipulihkan, jalankan perintah berikut secara berurutan:
```bash
openclaw matrix verify backup reset --yes
@ -561,115 +568,115 @@ openclaw matrix verify backup status --verbose
openclaw matrix verify status
```
Tambahkan `--account <id>` ke setiap perintah jika Anda ingin menargetkan akun Matrix bernama secara eksplisit.
Tambahkan `--account <id>` ke setiap perintah bila Anda ingin menargetkan akun Matrix bernama secara eksplisit.
### Perilaku saat startup
Saat `encryption: true`, Matrix secara default menetapkan `startupVerification` ke `"if-unverified"`.
Saat startup, jika perangkat ini masih belum terverifikasi, Matrix akan meminta verifikasi mandiri di klien Matrix lain,
Saat `encryption: true`, Matrix secara default mengatur `startupVerification` ke `"if-unverified"`.
Saat startup, jika perangkat ini masih belum terverifikasi, Matrix akan meminta verifikasi diri di klien Matrix lain,
melewati permintaan duplikat saat satu permintaan sudah tertunda, dan menerapkan cooldown lokal sebelum mencoba lagi setelah restart.
Secara default, percobaan permintaan yang gagal diulang lebih cepat daripada pembuatan permintaan yang berhasil.
Setel `startupVerification: "off"` untuk menonaktifkan permintaan startup otomatis, atau sesuaikan `startupVerificationCooldownHours`
jika Anda ingin jendela percobaan ulang yang lebih pendek atau lebih panjang.
Upaya permintaan yang gagal akan dicoba lagi lebih cepat daripada pembuatan permintaan yang berhasil secara default.
Atur `startupVerification: "off"` untuk menonaktifkan permintaan otomatis saat startup, atau sesuaikan `startupVerificationCooldownHours`
jika Anda menginginkan jendela percobaan ulang yang lebih pendek atau lebih panjang.
Startup juga secara otomatis melakukan proses bootstrap crypto konservatif.
Proses itu mencoba menggunakan ulang secret storage dan identitas cross-signing saat ini terlebih dahulu, dan menghindari reset cross-signing kecuali Anda menjalankan alur perbaikan bootstrap yang eksplisit.
Startup juga secara otomatis melakukan pass bootstrap crypto yang konservatif.
Pass itu mencoba menggunakan ulang secret storage dan identitas cross-signing saat ini terlebih dahulu, dan menghindari reset cross-signing kecuali Anda menjalankan alur perbaikan bootstrap yang eksplisit.
Jika startup menemukan status bootstrap yang rusak dan `channels.matrix.password` dikonfigurasi, OpenClaw dapat mencoba jalur perbaikan yang lebih ketat.
Jika perangkat saat ini sudah ditandatangani pemilik, OpenClaw mempertahankan identitas itu alih-alih meresetnya secara otomatis.
Jika perangkat saat ini sudah ditandatangani pemilik, OpenClaw mempertahankan identitas tersebut alih-alih meresetnya secara otomatis.
Upgrade dari plugin Matrix publik sebelumnya:
- OpenClaw secara otomatis menggunakan ulang akun Matrix, access token, dan identitas perangkat yang sama bila memungkinkan.
- Sebelum perubahan migrasi Matrix yang dapat ditindaklanjuti dijalankan, OpenClaw membuat atau menggunakan ulang snapshot pemulihan di `~/Backups/openclaw-migrations/`.
- Jika Anda menggunakan beberapa akun Matrix, setel `channels.matrix.defaultAccount` sebelum upgrade dari tata letak flat-store lama agar OpenClaw tahu akun mana yang harus menerima state lawas bersama tersebut.
- Jika plugin sebelumnya menyimpan key dekripsi backup room-key Matrix secara lokal, startup atau `openclaw doctor --fix` akan mengimpornya ke alur recovery-key baru secara otomatis.
- Jika access token Matrix berubah setelah migrasi disiapkan, startup sekarang memindai root penyimpanan hash token saudara untuk state pemulihan lawas yang tertunda sebelum menyerah pada pemulihan backup otomatis.
- Jika access token Matrix berubah kemudian untuk akun, homeserver, dan pengguna yang sama, OpenClaw sekarang lebih memilih menggunakan ulang root penyimpanan hash token yang paling lengkap yang ada alih-alih memulai dari direktori state Matrix kosong.
- Pada startup gateway berikutnya, room key yang dicadangkan akan dipulihkan secara otomatis ke crypto store baru.
- Jika plugin lama memiliki room key lokal saja yang tidak pernah dicadangkan, OpenClaw akan memberi peringatan dengan jelas. Key tersebut tidak dapat diekspor secara otomatis dari rust crypto store sebelumnya, sehingga beberapa riwayat terenkripsi lama mungkin tetap tidak tersedia sampai dipulihkan secara manual.
- Jika Anda menggunakan beberapa akun Matrix, atur `channels.matrix.defaultAccount` sebelum upgrade dari tata letak flat-store lama agar OpenClaw mengetahui akun mana yang harus menerima status lawas bersama tersebut.
- Jika plugin sebelumnya menyimpan backup key dekripsi room-key Matrix secara lokal, startup atau `openclaw doctor --fix` akan mengimpornya ke alur recovery-key baru secara otomatis.
- Jika access token Matrix berubah setelah migrasi disiapkan, startup sekarang memindai root penyimpanan hash token tetangga untuk status pemulihan lawas yang tertunda sebelum menyerah pada pemulihan backup otomatis.
- Jika access token Matrix berubah nanti untuk akun, homeserver, dan pengguna yang sama, OpenClaw sekarang lebih memilih menggunakan ulang root penyimpanan hash token yang paling lengkap yang ada daripada memulai dari direktori status Matrix kosong.
- Pada startup gateway berikutnya, room key yang sudah dibackup dipulihkan secara otomatis ke crypto store baru.
- Jika plugin lama memiliki room key lokal saja yang tidak pernah dibackup, OpenClaw akan memberi peringatan dengan jelas. Key tersebut tidak dapat diekspor secara otomatis dari rust crypto store sebelumnya, sehingga sebagian riwayat terenkripsi lama mungkin tetap tidak tersedia sampai dipulihkan secara manual.
- Lihat [Matrix migration](/id/install/migrating-matrix) untuk alur upgrade lengkap, batasan, perintah pemulihan, dan pesan migrasi umum.
State runtime terenkripsi diatur dalam root hash token per akun dan per pengguna di
Status runtime terenkripsi diatur dalam root hash token per akun dan per pengguna di
`~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/`.
Direktori tersebut berisi sync store (`bot-storage.json`), crypto store (`crypto/`),
Direktori itu berisi sync store (`bot-storage.json`), crypto store (`crypto/`),
file recovery key (`recovery-key.json`), snapshot IndexedDB (`crypto-idb-snapshot.json`),
binding thread (`thread-bindings.json`), dan state verifikasi startup (`startup-verification.json`)
saat fitur tersebut digunakan.
Saat token berubah tetapi identitas akun tetap sama, OpenClaw menggunakan ulang root terbaik yang ada
untuk tuple akun/homeserver/pengguna tersebut sehingga state sync sebelumnya, state crypto, binding thread,
dan state verifikasi startup tetap terlihat.
thread binding (`thread-bindings.json`), dan status verifikasi startup (`startup-verification.json`)
saat fitur-fitur tersebut digunakan.
Ketika token berubah tetapi identitas akun tetap sama, OpenClaw menggunakan ulang root terbaik yang ada
untuk tuple akun/homeserver/pengguna tersebut sehingga status sync sebelumnya, status crypto, thread binding,
dan status verifikasi startup tetap terlihat.
### Model crypto store Node
E2EE Matrix dalam plugin ini menggunakan jalur Rust crypto `matrix-js-sdk` resmi di Node.
Jalur itu mengharapkan persistensi berbasis IndexedDB saat Anda ingin state crypto bertahan setelah restart.
Matrix E2EE dalam plugin ini menggunakan jalur Rust crypto `matrix-js-sdk` resmi di Node.
Jalur itu mengharapkan persistensi berbasis IndexedDB jika Anda ingin status crypto bertahan setelah restart.
Saat ini OpenClaw menyediakannya di Node dengan cara:
OpenClaw saat ini menyediakannya di Node dengan cara:
- menggunakan `fake-indexeddb` sebagai shim API IndexedDB yang diharapkan SDK
- memulihkan konten IndexedDB Rust crypto dari `crypto-idb-snapshot.json` sebelum `initRustCrypto`
- menyimpan kembali konten IndexedDB yang diperbarui ke `crypto-idb-snapshot.json` setelah init dan selama runtime
- menserialkan pemulihan dan penyimpanan snapshot terhadap `crypto-idb-snapshot.json` dengan file lock advisori agar persistensi runtime gateway dan pemeliharaan CLI tidak saling berpacu pada file snapshot yang sama
- menggunakan `fake-indexeddb` sebagai shim API IndexedDB yang diharapkan oleh SDK
- memulihkan isi IndexedDB Rust crypto dari `crypto-idb-snapshot.json` sebelum `initRustCrypto`
- menyimpan kembali isi IndexedDB yang diperbarui ke `crypto-idb-snapshot.json` setelah init dan selama runtime
- menserialkan pemulihan dan persistensi snapshot terhadap `crypto-idb-snapshot.json` dengan file lock advisory agar persistensi runtime gateway dan pemeliharaan CLI tidak saling balapan pada file snapshot yang sama
Ini adalah plumbing kompatibilitas/penyimpanan, bukan implementasi crypto kustom.
File snapshot adalah state runtime sensitif dan disimpan dengan izin file yang ketat.
Dalam model keamanan OpenClaw, host gateway dan direktori state OpenClaw lokal sudah berada di dalam batas operator tepercaya, sehingga ini terutama merupakan persoalan ketahanan operasional, bukan batas kepercayaan jarak jauh yang terpisah.
Ini adalah plambing kompatibilitas/penyimpanan, bukan implementasi crypto kustom.
File snapshot adalah status runtime sensitif dan disimpan dengan izin file yang ketat.
Dalam model keamanan OpenClaw, host gateway dan direktori status OpenClaw lokal sudah berada di dalam batas kepercayaan operator, jadi ini terutama merupakan masalah ketahanan operasional, bukan batas kepercayaan jarak jauh yang terpisah.
Peningkatan yang direncanakan:
- menambahkan dukungan SecretRef untuk material key Matrix persisten sehingga recovery key dan secret enkripsi store terkait dapat diambil dari provider secret OpenClaw, bukan hanya file lokal
- menambahkan dukungan SecretRef untuk material key Matrix persisten sehingga recovery key dan secret enkripsi store terkait dapat bersumber dari penyedia secret OpenClaw, bukan hanya file lokal
## Pengelolaan profil
## Manajemen profil
Perbarui profil mandiri Matrix untuk akun yang dipilih dengan:
Perbarui self-profile Matrix untuk akun yang dipilih dengan:
```bash
openclaw matrix profile set --name "OpenClaw Assistant"
openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png
```
Tambahkan `--account <id>` saat Anda ingin menargetkan akun Matrix bernama secara eksplisit.
Tambahkan `--account <id>` bila Anda ingin menargetkan akun Matrix bernama secara eksplisit.
Matrix menerima URL avatar `mxc://` secara langsung. Saat Anda meneruskan URL avatar `http://` atau `https://`, OpenClaw terlebih dahulu mengunggahnya ke Matrix dan menyimpan kembali URL `mxc://` yang telah diselesaikan ke `channels.matrix.avatarUrl` (atau override akun yang dipilih).
Matrix menerima URL avatar `mxc://` secara langsung. Saat Anda memberikan URL avatar `http://` atau `https://`, OpenClaw mengunggahnya ke Matrix terlebih dahulu dan menyimpan URL `mxc://` yang telah di-resolve kembali ke `channels.matrix.avatarUrl` (atau override akun yang dipilih).
## Pemberitahuan verifikasi otomatis
Matrix sekarang memposting pemberitahuan siklus hidup verifikasi langsung ke room verifikasi DM ketat sebagai pesan `m.notice`.
Itu mencakup:
Ini mencakup:
- pemberitahuan permintaan verifikasi
- pemberitahuan verifikasi siap (dengan panduan eksplisit "Verify by emoji")
- pemberitahuan mulai dan selesai verifikasi
- detail SAS (emoji dan desimal) bila tersedia
- detail SAS (emoji dan desimal) saat tersedia
Permintaan verifikasi masuk dari klien Matrix lain dilacak dan diterima otomatis oleh OpenClaw.
Untuk alur verifikasi mandiri, OpenClaw juga memulai alur SAS secara otomatis saat verifikasi emoji tersedia dan mengonfirmasi sisinya sendiri.
Untuk permintaan verifikasi dari pengguna/perangkat Matrix lain, OpenClaw menerima permintaan secara otomatis lalu menunggu alur SAS berjalan seperti biasa.
Untuk alur verifikasi diri, OpenClaw juga memulai alur SAS secara otomatis saat verifikasi emoji tersedia dan mengonfirmasi sisinya sendiri.
Untuk permintaan verifikasi dari pengguna/perangkat Matrix lain, OpenClaw menerima otomatis permintaan tersebut lalu menunggu alur SAS berlanjut secara normal.
Anda tetap perlu membandingkan emoji atau SAS desimal di klien Matrix Anda dan mengonfirmasi "They match" di sana untuk menyelesaikan verifikasi.
OpenClaw tidak menerima otomatis alur duplikat yang dimulai sendiri secara membabi buta. Startup melewati pembuatan permintaan baru saat permintaan verifikasi mandiri sudah tertunda.
OpenClaw tidak menerima otomatis alur duplikat yang dimulai sendiri secara membabi buta. Startup melewati pembuatan permintaan baru saat permintaan verifikasi diri sudah tertunda.
Pemberitahuan protokol/sistem verifikasi tidak diteruskan ke pipeline chat agent, sehingga tidak menghasilkan `NO_REPLY`.
Pemberitahuan protokol/sistem verifikasi tidak diteruskan ke pipeline chat agen, sehingga tidak menghasilkan `NO_REPLY`.
### Kebersihan perangkat
Perangkat Matrix yang dikelola OpenClaw lama dapat menumpuk di akun dan membuat kepercayaan room terenkripsi lebih sulit dipahami.
Daftarkan perangkat dengan:
Perangkat Matrix yang dikelola OpenClaw lama dapat menumpuk pada akun dan membuat kepercayaan room terenkripsi lebih sulit dipahami.
Daftarkan dengan:
```bash
openclaw matrix devices list
```
Hapus perangkat OpenClaw lama yang sudah tidak aktif dengan:
Hapus perangkat OpenClaw yang dikelola dan sudah usang dengan:
```bash
openclaw matrix devices prune-stale
```
### Perbaikan Room Langsung
### Perbaikan Room Direct
Jika state direct-message tidak sinkron, OpenClaw dapat berakhir dengan pemetaan `m.direct` lama yang menunjuk ke room solo lama alih-alih DM live. Periksa pemetaan saat ini untuk rekan dengan:
Jika status direct-message keluar dari sinkronisasi, OpenClaw dapat berakhir dengan pemetaan `m.direct` usang yang menunjuk ke room solo lama alih-alih DM yang aktif. Periksa pemetaan saat ini untuk peer dengan:
```bash
openclaw matrix direct inspect --user-id @alice:example.org
@ -681,32 +688,32 @@ Perbaiki dengan:
openclaw matrix direct repair --user-id @alice:example.org
```
Perbaikan menjaga logika khusus Matrix tetap berada di dalam plugin:
Perbaikan menjaga logika khusus Matrix tetap di dalam plugin:
- perbaikan ini lebih memilih DM 1:1 ketat yang sudah dipetakan di `m.direct`
- jika tidak, perbaikan ini kembali ke DM 1:1 ketat mana pun yang saat ini diikuti dengan pengguna tersebut
- jika tidak ada DM sehat, perbaikan ini membuat direct room baru dan menulis ulang `m.direct` agar menunjuk ke room itu
- ini lebih memilih DM 1:1 ketat yang sudah dipetakan di `m.direct`
- jika tidak, ini kembali ke DM 1:1 ketat mana pun dengan pengguna tersebut yang saat ini sudah bergabung
- jika tidak ada DM sehat, ini membuat room direct baru dan menulis ulang `m.direct` agar menunjuk ke sana
Alur perbaikan tidak menghapus room lama secara otomatis. Alur ini hanya memilih DM yang sehat dan memperbarui pemetaan agar pengiriman Matrix baru, pemberitahuan verifikasi, dan alur direct-message lain kembali menargetkan room yang benar.
Alur perbaikan tidak menghapus room lama secara otomatis. Alur ini hanya memilih DM yang sehat dan memperbarui pemetaan sehingga pengiriman Matrix baru, pemberitahuan verifikasi, dan alur direct-message lainnya kembali menargetkan room yang benar.
## Thread
Matrix mendukung thread Matrix bawaan untuk balasan otomatis maupun pengiriman message-tool.
Matrix mendukung thread Matrix native untuk balasan otomatis maupun pengiriman alat pesan.
- `dm.sessionScope: "per-user"` (default) menjaga perutean DM Matrix tetap berbasis pengirim, sehingga beberapa room DM dapat berbagi satu sesi saat semuanya diselesaikan ke rekan yang sama.
- `dm.sessionScope: "per-room"` mengisolasi setiap room DM Matrix ke kunci sesi masing-masing sambil tetap menggunakan auth DM normal dan pemeriksaan allowlist.
- Binding percakapan Matrix eksplisit tetap lebih diutamakan daripada `dm.sessionScope`, sehingga room dan thread yang dibinding tetap menggunakan sesi target yang dipilih.
- `threadReplies: "off"` menjaga balasan tetap di level atas dan menjaga pesan threaded masuk pada sesi induk.
- `threadReplies: "inbound"` membalas di dalam thread hanya ketika pesan masuk sudah berada di thread itu.
- `threadReplies: "always"` menjaga balasan room di thread yang berakar pada pesan pemicu dan merutekan percakapan itu melalui sesi berlingkup thread yang cocok dari pesan pemicu pertama.
- `dm.threadReplies` menimpa setelan tingkat atas untuk DM saja. Misalnya, Anda dapat menjaga thread room tetap terisolasi sambil menjaga DM tetap datar.
- Pesan threaded masuk menyertakan pesan root thread sebagai konteks agent tambahan.
- Pengiriman message-tool sekarang otomatis mewarisi thread Matrix saat ini ketika targetnya adalah room yang sama, atau target pengguna DM yang sama, kecuali `threadId` eksplisit diberikan.
- Penggunaan ulang target pengguna DM dengan sesi yang sama hanya aktif saat metadata sesi saat ini membuktikan rekan DM yang sama pada akun Matrix yang sama; jika tidak, OpenClaw kembali ke perutean normal berlingkup pengguna.
- Saat OpenClaw melihat room DM Matrix bertabrakan dengan room DM lain pada sesi DM Matrix bersama yang sama, OpenClaw memposting `m.notice` satu kali di room itu dengan jalur keluar `/focus` saat binding thread diaktifkan dan petunjuk `dm.sessionScope`.
- Binding thread runtime didukung untuk Matrix. `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, dan `/acp spawn` yang dibinding ke thread kini berfungsi di room dan DM Matrix.
- `/focus` room/DM Matrix level atas membuat thread Matrix baru dan membindingnya ke sesi target saat `threadBindings.spawnSubagentSessions=true`.
- Menjalankan `/focus` atau `/acp spawn --thread here` di dalam thread Matrix yang sudah ada akan membinding thread saat ini tersebut.
- `dm.sessionScope: "per-user"` (default) menjaga perutean DM Matrix tetap bercakup pengirim, sehingga beberapa room DM dapat berbagi satu sesi saat semuanya ter-resolve ke peer yang sama.
- `dm.sessionScope: "per-room"` mengisolasi setiap room DM Matrix ke kunci sesinya sendiri sambil tetap menggunakan auth DM normal dan pemeriksaan allowlist.
- Binding percakapan Matrix eksplisit tetap lebih diutamakan dibanding `dm.sessionScope`, sehingga room dan thread yang di-bind mempertahankan sesi target yang dipilih.
- `threadReplies: "off"` menjaga balasan tetap top-level dan menjaga pesan threaded masuk pada sesi parent.
- `threadReplies: "inbound"` membalas di dalam thread hanya ketika pesan masuk memang sudah berada di thread itu.
- `threadReplies: "always"` menjaga balasan room di thread yang berakar pada pesan pemicu dan merutekan percakapan itu melalui sesi bercakup thread yang cocok dari pesan pemicu pertama.
- `dm.threadReplies` menimpa pengaturan top-level hanya untuk DM. Misalnya, Anda dapat menjaga thread room tetap terisolasi sambil menjaga DM tetap datar.
- Pesan threaded masuk menyertakan pesan root thread sebagai konteks agen tambahan.
- Pengiriman alat pesan sekarang otomatis mewarisi thread Matrix saat ini ketika targetnya adalah room yang sama, atau target pengguna DM yang sama, kecuali `threadId` eksplisit diberikan.
- Penggunaan ulang target pengguna DM dengan sesi yang sama hanya aktif ketika metadata sesi saat ini membuktikan peer DM yang sama pada akun Matrix yang sama; jika tidak, OpenClaw kembali ke perutean bercakup pengguna normal.
- Saat OpenClaw melihat room DM Matrix bertabrakan dengan room DM lain pada sesi DM Matrix bersama yang sama, OpenClaw memposting `m.notice` satu kali di room itu dengan escape hatch `/focus` saat thread binding diaktifkan dan petunjuk `dm.sessionScope`.
- Runtime thread binding didukung untuk Matrix. `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, dan `/acp spawn` yang terikat thread kini berfungsi di room dan DM Matrix.
- `/focus` top-level di room/DM Matrix membuat thread Matrix baru dan mengikatnya ke sesi target saat `threadBindings.spawnSubagentSessions=true`.
- Menjalankan `/focus` atau `/acp spawn --thread here` di dalam thread Matrix yang sudah ada akan mengikat thread saat ini tersebut.
## ACP conversation bindings
@ -714,20 +721,20 @@ Room, DM, dan thread Matrix yang sudah ada dapat diubah menjadi workspace ACP ya
Alur operator cepat:
- Jalankan `/acp spawn codex --bind here` di dalam DM, room, atau thread Matrix yang sudah ada dan ingin terus Anda gunakan.
- Di DM atau room Matrix level atas, DM/room saat ini tetap menjadi permukaan chat dan pesan berikutnya dirutekan ke sesi ACP yang di-spawn.
- Di dalam thread Matrix yang sudah ada, `--bind here` membinding thread saat ini di tempat.
- `/new` dan `/reset` mereset sesi ACP yang sama yang dibinding di tempat.
- Jalankan `/acp spawn codex --bind here` di dalam DM, room, atau thread Matrix yang sudah ada yang ingin terus Anda gunakan.
- Di DM atau room Matrix tingkat atas, DM/room saat ini tetap menjadi permukaan chat dan pesan berikutnya dirutekan ke sesi ACP yang di-spawn.
- Di dalam thread Matrix yang sudah ada, `--bind here` mengikat thread saat ini di tempat.
- `/new` dan `/reset` mereset sesi ACP terikat yang sama di tempat.
- `/acp close` menutup sesi ACP dan menghapus binding.
Catatan:
- `--bind here` tidak membuat child thread Matrix.
- `threadBindings.spawnAcpSessions` hanya diperlukan untuk `/acp spawn --thread auto|here`, saat OpenClaw perlu membuat atau membinding child thread Matrix.
- `threadBindings.spawnAcpSessions` hanya diperlukan untuk `/acp spawn --thread auto|here`, saat OpenClaw perlu membuat atau mengikat child thread Matrix.
### Config Thread Binding
Matrix mewarisi default global dari `session.threadBindings`, dan juga mendukung override per channel:
Matrix mewarisi default global dari `session.threadBindings`, dan juga mendukung override per saluran:
- `threadBindings.enabled`
- `threadBindings.idleHours`
@ -735,10 +742,10 @@ Matrix mewarisi default global dari `session.threadBindings`, dan juga mendukung
- `threadBindings.spawnSubagentSessions`
- `threadBindings.spawnAcpSessions`
Flag spawn yang dibinding ke thread Matrix bersifat opt-in:
Flag spawn terikat-thread Matrix bersifat opt-in:
- Setel `threadBindings.spawnSubagentSessions: true` untuk mengizinkan `/focus` level atas membuat dan membinding thread Matrix baru.
- Setel `threadBindings.spawnAcpSessions: true` untuk mengizinkan `/acp spawn --thread auto|here` membinding sesi ACP ke thread Matrix.
- Atur `threadBindings.spawnSubagentSessions: true` untuk mengizinkan `/focus` top-level membuat dan mengikat thread Matrix baru.
- Atur `threadBindings.spawnAcpSessions: true` untuk mengizinkan `/acp spawn --thread auto|here` mengikat sesi ACP ke thread Matrix.
## Reaksi
@ -747,23 +754,23 @@ Matrix mendukung aksi reaksi keluar, notifikasi reaksi masuk, dan reaksi ack mas
- Tooling reaksi keluar dikendalikan oleh `channels["matrix"].actions.reactions`.
- `react` menambahkan reaksi ke event Matrix tertentu.
- `reactions` mencantumkan ringkasan reaksi saat ini untuk event Matrix tertentu.
- `emoji=""` menghapus reaksi milik akun bot sendiri pada event itu.
- `emoji=""` menghapus reaksi milik akun bot sendiri pada event tersebut.
- `remove: true` hanya menghapus reaksi emoji yang ditentukan dari akun bot.
Cakupan reaksi ack diselesaikan dengan urutan resolusi OpenClaw standar:
Cakupan reaksi ack di-resolve dalam urutan standar OpenClaw:
- `channels["matrix"].accounts.<accountId>.ackReaction`
- `channels["matrix"].ackReaction`
- `messages.ackReaction`
- fallback emoji identitas agent
- fallback emoji identitas agen
Cakupan reaksi ack diselesaikan dalam urutan ini:
Cakupan scope reaksi ack di-resolve dalam urutan ini:
- `channels["matrix"].accounts.<accountId>.ackReactionScope`
- `channels["matrix"].ackReactionScope`
- `messages.ackReactionScope`
Mode notifikasi reaksi diselesaikan dalam urutan ini:
Mode notifikasi reaksi di-resolve dalam urutan ini:
- `channels["matrix"].accounts.<accountId>.reactionNotifications`
- `channels["matrix"].reactionNotifications`
@ -771,29 +778,29 @@ Mode notifikasi reaksi diselesaikan dalam urutan ini:
Perilaku saat ini:
- `reactionNotifications: "own"` meneruskan event `m.reaction` yang ditambahkan saat menargetkan pesan Matrix yang ditulis bot.
- `reactionNotifications: "own"` meneruskan event `m.reaction` yang ditambahkan ketika menargetkan pesan Matrix yang ditulis bot.
- `reactionNotifications: "off"` menonaktifkan event sistem reaksi.
- Penghapusan reaksi masih belum disintesis menjadi event sistem karena Matrix menampilkannya sebagai redaksi, bukan sebagai penghapusan `m.reaction` mandiri.
- Penghapusan reaksi masih belum disintesis menjadi event sistem karena Matrix menampilkan itu sebagai redaksi, bukan penghapusan `m.reaction` mandiri.
## Konteks riwayat
- `channels.matrix.historyLimit` mengontrol berapa banyak pesan room terbaru yang disertakan sebagai `InboundHistory` saat pesan room Matrix memicu agent.
- Nilai ini fallback ke `messages.groupChat.historyLimit`. Setel `0` untuk menonaktifkan.
- `channels.matrix.historyLimit` mengontrol berapa banyak pesan room terbaru yang disertakan sebagai `InboundHistory` ketika pesan room Matrix memicu agen.
- Ini fallback ke `messages.groupChat.historyLimit`. Jika keduanya tidak diatur, default efektifnya adalah `0`, sehingga pesan room yang dipicu mention tidak dibuffer. Atur `0` untuk menonaktifkan.
- Riwayat room Matrix hanya untuk room. DM tetap menggunakan riwayat sesi normal.
- Riwayat room Matrix hanya pending: OpenClaw menampung pesan room yang belum memicu balasan, lalu mengambil snapshot jendela itu saat mention atau pemicu lain tiba.
- Riwayat room Matrix bersifat pending-only: OpenClaw membuffer pesan room yang belum memicu balasan, lalu mengambil snapshot jendela itu ketika mention atau pemicu lain datang.
- Pesan pemicu saat ini tidak disertakan dalam `InboundHistory`; pesan itu tetap berada di body masuk utama untuk giliran tersebut.
- Percobaan ulang event Matrix yang sama menggunakan ulang snapshot riwayat asli alih-alih bergeser maju ke pesan room yang lebih baru.
## Visibilitas konteks
Matrix mendukung kontrol `contextVisibility` bersama untuk konteks room tambahan seperti teks balasan yang diambil, root thread, dan riwayat tertunda.
Matrix mendukung kontrol bersama `contextVisibility` untuk konteks room tambahan seperti teks balasan yang diambil, root thread, dan riwayat tertunda.
- `contextVisibility: "all"` adalah default. Konteks tambahan dipertahankan sebagaimana diterima.
- `contextVisibility: "allowlist"` memfilter konteks tambahan ke pengirim yang diizinkan oleh pemeriksaan allowlist room/pengguna yang aktif.
- `contextVisibility: "allowlist_quote"` berperilaku seperti `allowlist`, tetapi tetap mempertahankan satu balasan kutipan eksplisit.
Setelan ini memengaruhi visibilitas konteks tambahan, bukan apakah pesan masuk itu sendiri dapat memicu balasan.
Otorisasi pemicu tetap berasal dari setelan `groupPolicy`, `groups`, `groupAllowFrom`, dan kebijakan DM.
Pengaturan ini memengaruhi visibilitas konteks tambahan, bukan apakah pesan masuk itu sendiri dapat memicu balasan.
Otorisasi pemicu tetap berasal dari pengaturan `groupPolicy`, `groups`, `groupAllowFrom`, dan kebijakan DM.
## Contoh kebijakan DM dan room
@ -818,7 +825,7 @@ Otorisasi pemicu tetap berasal dari setelan `groupPolicy`, `groups`, `groupAllow
}
```
Lihat [Groups](/id/channels/groups) untuk perilaku mention-gating dan allowlist.
Lihat [Groups](/id/channels/groups) untuk perilaku pembatasan mention dan allowlist.
Contoh pairing untuk DM Matrix:
@ -827,13 +834,13 @@ openclaw pairing list matrix
openclaw pairing approve matrix <CODE>
```
Jika pengguna Matrix yang belum disetujui terus mengirimi Anda pesan sebelum persetujuan, OpenClaw menggunakan ulang kode pairing tertunda yang sama dan dapat mengirim balasan pengingat lagi setelah cooldown singkat alih-alih membuat kode baru.
Jika pengguna Matrix yang belum disetujui terus mengirimi Anda pesan sebelum persetujuan, OpenClaw menggunakan ulang kode pairing tertunda yang sama dan dapat mengirim balasan pengingat lagi setelah cooldown singkat alih-alih mencetak kode baru.
Lihat [Pairing](/id/channels/pairing) untuk alur pairing DM bersama dan tata letak penyimpanan.
## Persetujuan exec
Matrix dapat bertindak sebagai klien persetujuan exec untuk akun Matrix.
Matrix dapat bertindak sebagai klien persetujuan exec untuk sebuah akun Matrix.
- `channels.matrix.execApprovals.enabled`
- `channels.matrix.execApprovals.approvers` (opsional; fallback ke `channels.matrix.dm.allowFrom`)
@ -841,13 +848,13 @@ Matrix dapat bertindak sebagai klien persetujuan exec untuk akun Matrix.
- `channels.matrix.execApprovals.agentFilter`
- `channels.matrix.execApprovals.sessionFilter`
Approver harus berupa ID pengguna Matrix seperti `@owner:example.org`. Matrix otomatis mengaktifkan persetujuan exec bawaan saat `enabled` tidak disetel atau `"auto"` dan setidaknya satu approver dapat diselesaikan, baik dari `execApprovals.approvers` maupun dari `channels.matrix.dm.allowFrom`. Setel `enabled: false` untuk menonaktifkan Matrix sebagai klien persetujuan bawaan secara eksplisit. Jika tidak, permintaan persetujuan akan fallback ke rute persetujuan lain yang dikonfigurasi atau kebijakan fallback persetujuan exec.
Approver harus berupa ID pengguna Matrix seperti `@owner:example.org`. Matrix otomatis mengaktifkan persetujuan exec native ketika `enabled` tidak diatur atau `"auto"` dan setidaknya satu approver dapat di-resolve, baik dari `execApprovals.approvers` maupun dari `channels.matrix.dm.allowFrom`. Atur `enabled: false` untuk menonaktifkan Matrix sebagai klien persetujuan native secara eksplisit. Jika tidak, permintaan persetujuan akan fallback ke rute persetujuan lain yang dikonfigurasi atau kebijakan fallback persetujuan exec.
Perutean bawaan Matrix saat ini hanya untuk exec:
Perutean native Matrix saat ini hanya untuk exec:
- `channels.matrix.execApprovals.*` mengontrol perutean DM/channel bawaan untuk persetujuan exec saja.
- Persetujuan plugin tetap menggunakan `/approve` same-chat bersama ditambah penerusan `approvals.plugin` yang dikonfigurasi.
- Matrix masih dapat menggunakan ulang `channels.matrix.dm.allowFrom` untuk otorisasi persetujuan plugin ketika approver dapat diinferensikan dengan aman, tetapi tidak mengekspos jalur fanout DM/channel persetujuan plugin bawaan yang terpisah.
- `channels.matrix.execApprovals.*` mengontrol perutean DM/channel native untuk persetujuan exec saja.
- Persetujuan plugin tetap menggunakan `/approve` same-chat bersama ditambah forwarding `approvals.plugin` yang dikonfigurasi.
- Matrix tetap dapat menggunakan ulang `channels.matrix.dm.allowFrom` untuk otorisasi persetujuan plugin ketika approver dapat diinferensikan dengan aman, tetapi tidak mengekspos jalur fanout DM/channel persetujuan plugin native yang terpisah.
Aturan pengiriman:
@ -855,17 +862,17 @@ Aturan pengiriman:
- `target: "channel"` mengirim prompt kembali ke room atau DM Matrix asal
- `target: "both"` mengirim ke DM approver dan room atau DM Matrix asal
Prompt persetujuan Matrix menanamkan pintasan reaksi pada pesan persetujuan utama:
Prompt persetujuan Matrix menanam pintasan reaksi pada pesan persetujuan utama:
- `✅` = izinkan sekali
- `❌` = tolak
- `♾️` = selalu izinkan jika keputusan itu diizinkan oleh kebijakan exec efektif
- `♾️` = izinkan selalu ketika keputusan itu diizinkan oleh kebijakan exec efektif
Approver dapat bereaksi pada pesan itu atau menggunakan slash command fallback: `/approve <id> allow-once`, `/approve <id> allow-always`, atau `/approve <id> deny`.
Approver dapat bereaksi pada pesan itu atau menggunakan perintah slash fallback: `/approve <id> allow-once`, `/approve <id> allow-always`, atau `/approve <id> deny`.
Hanya approver yang diselesaikan yang dapat menyetujui atau menolak. Pengiriman channel menyertakan teks perintah, jadi aktifkan `channel` atau `both` hanya di room tepercaya.
Hanya approver yang di-resolve yang dapat menyetujui atau menolak. Pengiriman saluran menyertakan teks perintah, jadi aktifkan `channel` atau `both` hanya di room tepercaya.
Prompt persetujuan Matrix menggunakan ulang shared core approval planner. Permukaan bawaan khusus Matrix hanya merupakan transport untuk persetujuan exec: perutean room/DM dan perilaku kirim/perbarui/hapus pesan.
Prompt persetujuan Matrix menggunakan ulang planner persetujuan inti bersama. Permukaan native khusus Matrix hanyalah transport untuk persetujuan exec: perutean room/DM dan perilaku kirim/perbarui/hapus pesan.
Override per akun:
@ -903,19 +910,19 @@ Dokumentasi terkait: [Exec approvals](/id/tools/exec-approvals)
}
```
Nilai `channels.matrix` tingkat atas bertindak sebagai default untuk akun bernama kecuali suatu akun menimpanya.
Anda dapat memberi cakupan entri room turunan ke satu akun Matrix dengan `groups.<room>.account` (atau `rooms.<room>.account` lama).
Entri tanpa `account` tetap dibagikan ke semua akun Matrix, dan entri dengan `account: "default"` tetap berfungsi saat akun default dikonfigurasi langsung pada `channels.matrix.*` tingkat atas.
Default auth bersama parsial tidak dengan sendirinya membuat akun default implisit terpisah. OpenClaw hanya mensintesis akun `default` tingkat atas saat default tersebut memiliki auth baru (`homeserver` plus `accessToken`, atau `homeserver` plus `userId` dan `password`); akun bernama masih dapat tetap dapat ditemukan dari `homeserver` plus `userId` ketika kredensial cache memenuhi auth nanti.
Jika Matrix sudah memiliki tepat satu akun bernama, atau `defaultAccount` menunjuk ke kunci akun bernama yang ada, promosi perbaikan/penyiapan dari akun tunggal ke multi-akun mempertahankan akun itu alih-alih membuat entri `accounts.default` baru. Hanya kunci auth/bootstrap Matrix yang dipindahkan ke akun yang dipromosikan itu; kunci kebijakan pengiriman bersama tetap berada di tingkat atas.
Setel `defaultAccount` saat Anda ingin OpenClaw lebih memilih satu akun Matrix bernama untuk perutean implisit, probing, dan operasi CLI.
Jika Anda mengonfigurasi beberapa akun bernama, setel `defaultAccount` atau teruskan `--account <id>` untuk perintah CLI yang bergantung pada pemilihan akun implisit.
Teruskan `--account <id>` ke `openclaw matrix verify ...` dan `openclaw matrix devices ...` saat Anda ingin menimpa pemilihan implisit itu untuk satu perintah.
Nilai `channels.matrix` tingkat atas bertindak sebagai default untuk akun bernama kecuali akun menimpanya.
Anda dapat mencakup entri room yang diwarisi ke satu akun Matrix dengan `groups.<room>.account` (atau `rooms.<room>.account` lawas).
Entri tanpa `account` tetap dibagikan di semua akun Matrix, dan entri dengan `account: "default"` tetap berfungsi ketika akun default dikonfigurasi langsung di `channels.matrix.*` tingkat atas.
Default auth bersama parsial tidak dengan sendirinya membuat akun default implisit yang terpisah. OpenClaw hanya mensintesis akun `default` tingkat atas ketika default tersebut memiliki auth baru (`homeserver` plus `accessToken`, atau `homeserver` plus `userId` dan `password`); akun bernama masih dapat tetap dapat ditemukan dari `homeserver` plus `userId` ketika kredensial yang di-cache memenuhi auth nanti.
Jika Matrix sudah memiliki tepat satu akun bernama, atau `defaultAccount` menunjuk ke kunci akun bernama yang sudah ada, promosi perbaikan/penyiapan dari akun tunggal ke multi-akun mempertahankan akun tersebut alih-alih membuat entri `accounts.default` baru. Hanya kunci auth/bootstrap Matrix yang dipindahkan ke akun yang dipromosikan itu; kunci kebijakan pengiriman bersama tetap di tingkat atas.
Atur `defaultAccount` ketika Anda ingin OpenClaw lebih memilih satu akun Matrix bernama untuk perutean implisit, probing, dan operasi CLI.
Jika Anda mengonfigurasi beberapa akun bernama, atur `defaultAccount` atau berikan `--account <id>` untuk perintah CLI yang bergantung pada pemilihan akun implisit.
Berikan `--account <id>` ke `openclaw matrix verify ...` dan `openclaw matrix devices ...` ketika Anda ingin menimpa pemilihan implisit tersebut untuk satu perintah.
## Homeserver privat/LAN
Secara default, OpenClaw memblokir homeserver Matrix privat/internal untuk perlindungan SSRF kecuali Anda
secara eksplisit ikut serta per akun.
secara eksplisit melakukan opt-in per akun.
Jika homeserver Anda berjalan di localhost, IP LAN/Tailscale, atau hostname internal, aktifkan
`allowPrivateNetwork` untuk akun Matrix tersebut:
@ -947,7 +954,7 @@ Opt-in ini hanya mengizinkan target privat/internal tepercaya. Homeserver cleart
## Mem-proxy lalu lintas Matrix
Jika deployment Matrix Anda memerlukan proxy HTTP(S) keluar eksplisit, setel `channels.matrix.proxy`:
Jika deployment Matrix Anda memerlukan proxy HTTP(S) keluar eksplisit, atur `channels.matrix.proxy`:
```json5
{
@ -961,8 +968,8 @@ Jika deployment Matrix Anda memerlukan proxy HTTP(S) keluar eksplisit, setel `ch
}
```
Akun bernama dapat menimpa default tingkat atas dengan `channels.matrix.accounts.<id>.proxy` mereka sendiri.
OpenClaw menggunakan setelan proxy yang sama untuk lalu lintas Matrix runtime dan probe status akun.
Akun bernama dapat menimpa default tingkat atas dengan `channels.matrix.accounts.<id>.proxy`.
OpenClaw menggunakan pengaturan proxy yang sama untuk lalu lintas Matrix runtime dan probe status akun.
## Resolusi target
@ -972,75 +979,76 @@ Matrix menerima bentuk target berikut di mana pun OpenClaw meminta target room a
- Room: `!room:server`, `room:!room:server`, atau `matrix:room:!room:server`
- Alias: `#alias:server`, `channel:#alias:server`, atau `matrix:channel:#alias:server`
Pencarian direktori live menggunakan akun Matrix yang sedang login:
Pencarian direktori live menggunakan akun Matrix yang sudah login:
- Pencarian pengguna mengkueri direktori pengguna Matrix pada homeserver itu.
- Pencarian room menerima ID room dan alias eksplisit secara langsung, lalu fallback ke pencarian nama room yang diikuti untuk akun tersebut.
- Pencarian nama joined-room bersifat upaya terbaik. Jika nama room tidak dapat diselesaikan ke ID atau alias, nama itu diabaikan oleh resolusi allowlist runtime.
- Lookup pengguna menanyakan direktori pengguna Matrix pada homeserver tersebut.
- Lookup room langsung menerima ID room dan alias eksplisit, lalu fallback ke pencarian nama room yang sudah bergabung untuk akun tersebut.
- Lookup nama room yang sudah bergabung bersifat best-effort. Jika nama room tidak dapat di-resolve ke ID atau alias, nama itu diabaikan oleh resolusi allowlist runtime.
## Referensi konfigurasi
- `enabled`: aktifkan atau nonaktifkan channel.
- `enabled`: aktifkan atau nonaktifkan saluran.
- `name`: label opsional untuk akun.
- `defaultAccount`: ID akun pilihan saat beberapa akun Matrix dikonfigurasi.
- `defaultAccount`: ID akun yang dipilih ketika beberapa akun Matrix dikonfigurasi.
- `homeserver`: URL homeserver, misalnya `https://matrix.example.org`.
- `allowPrivateNetwork`: izinkan akun Matrix ini terhubung ke homeserver privat/internal. Aktifkan ini saat homeserver diselesaikan ke `localhost`, IP LAN/Tailscale, atau host internal seperti `matrix-synapse`.
- `allowPrivateNetwork`: izinkan akun Matrix ini terhubung ke homeserver privat/internal. Aktifkan ini ketika homeserver me-resolve ke `localhost`, IP LAN/Tailscale, atau host internal seperti `matrix-synapse`.
- `proxy`: URL proxy HTTP(S) opsional untuk lalu lintas Matrix. Akun bernama dapat menimpa default tingkat atas dengan `proxy` mereka sendiri.
- `userId`: ID pengguna Matrix lengkap, misalnya `@bot:example.org`.
- `accessToken`: access token untuk auth berbasis token. Nilai plaintext dan nilai SecretRef didukung untuk `channels.matrix.accessToken` dan `channels.matrix.accounts.<id>.accessToken` di seluruh provider env/file/exec. Lihat [Secrets Management](/id/gateway/secrets).
- `accessToken`: access token untuk auth berbasis token. Nilai plaintext dan nilai SecretRef didukung untuk `channels.matrix.accessToken` dan `channels.matrix.accounts.<id>.accessToken` di seluruh penyedia env/file/exec. Lihat [Secrets Management](/id/gateway/secrets).
- `password`: password untuk login berbasis password. Nilai plaintext dan nilai SecretRef didukung.
- `deviceId`: ID perangkat Matrix eksplisit.
- `deviceName`: nama tampilan perangkat untuk login password.
- `avatarUrl`: URL avatar mandiri yang disimpan untuk sinkronisasi profil dan pembaruan `set-profile`.
- `initialSyncLimit`: batas event sinkronisasi saat startup.
- `avatarUrl`: URL avatar diri yang tersimpan untuk sinkronisasi profil dan pembaruan `set-profile`.
- `initialSyncLimit`: batas event sync saat startup.
- `encryption`: aktifkan E2EE.
- `allowlistOnly`: paksa perilaku allowlist-only untuk DM dan room.
- `allowBots`: izinkan pesan dari akun Matrix OpenClaw lain yang dikonfigurasi (`true` atau `"mentions"`).
- `allowlistOnly`: paksa perilaku hanya-allowlist untuk DM dan room.
- `allowBots`: izinkan pesan dari akun Matrix OpenClaw lain yang terkonfigurasi (`true` atau `"mentions"`).
- `groupPolicy`: `open`, `allowlist`, atau `disabled`.
- `contextVisibility`: mode visibilitas konteks room tambahan (`all`, `allowlist`, `allowlist_quote`).
- `groupAllowFrom`: allowlist ID pengguna untuk lalu lintas room.
- Entri `groupAllowFrom` harus berupa ID pengguna Matrix lengkap. Nama yang tidak dapat diselesaikan diabaikan saat runtime.
- `historyLimit`: jumlah maksimum pesan room yang disertakan sebagai konteks riwayat grup. Fallback ke `messages.groupChat.historyLimit`. Setel `0` untuk menonaktifkan.
- Entri `groupAllowFrom` harus berupa ID pengguna Matrix lengkap. Nama yang tidak ter-resolve diabaikan saat runtime.
- `historyLimit`: jumlah maksimum pesan room yang disertakan sebagai konteks riwayat grup. Fallback ke `messages.groupChat.historyLimit`; jika keduanya tidak diatur, default efektifnya adalah `0`. Atur `0` untuk menonaktifkan.
- `replyToMode`: `off`, `first`, atau `all`.
- `markdown`: konfigurasi rendering Markdown opsional untuk teks Matrix keluar.
- `streaming`: `off` (default), `partial`, `quiet`, `true`, atau `false`. `partial` dan `true` mengaktifkan pembaruan draf pratinjau-dahulu dengan pesan teks Matrix normal. `quiet` menggunakan pemberitahuan pratinjau tanpa notifikasi untuk penyiapan push-rule self-hosted.
- `blockStreaming`: `true` mengaktifkan pesan progres terpisah untuk blok assistant yang sudah selesai saat streaming pratinjau draf aktif.
- `markdown`: konfigurasi render Markdown opsional untuk teks Matrix keluar.
- `streaming`: `off` (default), `partial`, `quiet`, `true`, atau `false`. `partial` dan `true` mengaktifkan pembaruan draft pratinjau-terlebih-dahulu dengan pesan teks Matrix normal. `quiet` menggunakan pemberitahuan pratinjau non-notifikasi untuk penyiapan push-rule yang di-hosting sendiri.
- `blockStreaming`: `true` mengaktifkan pesan progres terpisah untuk blok asisten yang sudah selesai saat streaming draft pratinjau aktif.
- `threadReplies`: `off`, `inbound`, atau `always`.
- `threadBindings`: override per channel untuk perutean dan siklus hidup sesi yang dibinding ke thread.
- `startupVerification`: mode permintaan verifikasi mandiri otomatis saat startup (`if-unverified`, `off`).
- `threadBindings`: override per saluran untuk perutean dan siklus hidup sesi terikat-thread.
- `startupVerification`: mode permintaan verifikasi diri otomatis saat startup (`if-unverified`, `off`).
- `startupVerificationCooldownHours`: cooldown sebelum mencoba lagi permintaan verifikasi startup otomatis.
- `textChunkLimit`: ukuran chunk pesan keluar.
- `chunkMode`: `length` atau `newline`.
- `responsePrefix`: prefiks pesan opsional untuk balasan keluar.
- `ackReaction`: override reaksi ack opsional untuk channel/akun ini.
- `ackReaction`: override reaksi ack opsional untuk saluran/akun ini.
- `ackReactionScope`: override cakupan reaksi ack opsional (`group-mentions`, `group-all`, `direct`, `all`, `none`, `off`).
- `reactionNotifications`: mode notifikasi reaksi masuk (`own`, `off`).
- `mediaMaxMb`: batas ukuran media dalam MB untuk penanganan media Matrix. Ini berlaku untuk pengiriman keluar dan pemrosesan media masuk.
- `autoJoin`: kebijakan auto-join undangan (`always`, `allowlist`, `off`). Default: `off`.
- `autoJoinAllowlist`: room/alias yang diizinkan saat `autoJoin` adalah `allowlist`. Entri alias diselesaikan ke ID room selama penanganan undangan; OpenClaw tidak mempercayai state alias yang diklaim oleh room yang mengundang.
- `autoJoin`: kebijakan auto-join undangan (`always`, `allowlist`, `off`). Default: `off`. Ini berlaku untuk undangan Matrix secara umum, termasuk undangan bergaya DM, bukan hanya undangan room/grup. OpenClaw membuat keputusan ini pada saat undangan, sebelum dapat mengklasifikasikan room yang digabungkan secara andal sebagai DM atau grup.
- `autoJoinAllowlist`: room/alias yang diizinkan ketika `autoJoin` adalah `allowlist`. Entri alias di-resolve ke ID room selama penanganan undangan; OpenClaw tidak mempercayai status alias yang diklaim oleh room yang mengundang.
- `dm`: blok kebijakan DM (`enabled`, `policy`, `allowFrom`, `sessionScope`, `threadReplies`).
- Entri `dm.allowFrom` harus berupa ID pengguna Matrix lengkap kecuali Anda sudah menyelesaikannya melalui pencarian direktori live.
- `dm.sessionScope`: `per-user` (default) atau `per-room`. Gunakan `per-room` saat Anda ingin setiap room DM Matrix mempertahankan konteks terpisah meskipun rekannya sama.
- `dm.threadReplies`: override kebijakan thread khusus DM (`off`, `inbound`, `always`). Ini menimpa setelan `threadReplies` tingkat atas untuk penempatan balasan dan isolasi sesi di DM.
- `execApprovals`: pengiriman persetujuan exec bawaan Matrix (`enabled`, `approvers`, `target`, `agentFilter`, `sessionFilter`).
- `execApprovals.approvers`: ID pengguna Matrix yang diizinkan menyetujui permintaan exec. Opsional saat `dm.allowFrom` sudah mengidentifikasi para approver.
- `dm.policy`: mengontrol akses DM setelah OpenClaw bergabung ke room dan mengklasifikasikannya sebagai DM. Ini tidak mengubah apakah undangan di-auto-join.
- Entri `dm.allowFrom` harus berupa ID pengguna Matrix lengkap kecuali Anda sudah me-resolve-nya melalui pencarian direktori live.
- `dm.sessionScope`: `per-user` (default) atau `per-room`. Gunakan `per-room` saat Anda ingin setiap room DM Matrix menyimpan konteks terpisah meskipun peer-nya sama.
- `dm.threadReplies`: override kebijakan thread khusus DM (`off`, `inbound`, `always`). Ini menimpa pengaturan `threadReplies` tingkat atas untuk penempatan balasan dan isolasi sesi di DM.
- `execApprovals`: pengiriman persetujuan exec native Matrix (`enabled`, `approvers`, `target`, `agentFilter`, `sessionFilter`).
- `execApprovals.approvers`: ID pengguna Matrix yang diizinkan menyetujui permintaan exec. Opsional ketika `dm.allowFrom` sudah mengidentifikasi approver.
- `execApprovals.target`: `dm | channel | both` (default: `dm`).
- `accounts`: override per akun bernama. Nilai `channels.matrix` tingkat atas bertindak sebagai default untuk entri ini.
- `groups`: peta kebijakan per room. Gunakan ID room atau alias; nama room yang tidak dapat diselesaikan diabaikan saat runtime. Identitas sesi/grup menggunakan ID room stabil setelah resolusi, sementara label yang mudah dibaca manusia tetap berasal dari nama room.
- `groups.<room>.account`: batasi satu entri room turunan ke akun Matrix tertentu dalam penyiapan multi-akun.
- `groups`: peta kebijakan per room. Gunakan ID room atau alias; nama room yang tidak ter-resolve diabaikan saat runtime. Identitas sesi/grup menggunakan ID room yang stabil setelah resolusi, sementara label yang mudah dibaca manusia tetap berasal dari nama room.
- `groups.<room>.account`: batasi satu entri room yang diwarisi ke akun Matrix tertentu dalam penyiapan multi-akun.
- `groups.<room>.allowBots`: override tingkat room untuk pengirim bot yang dikonfigurasi (`true` atau `"mentions"`).
- `groups.<room>.users`: allowlist pengirim per room.
- `groups.<room>.tools`: override izin/tolak tool per room.
- `groups.<room>.autoReply`: override mention-gating tingkat room. `true` menonaktifkan persyaratan mention untuk room itu; `false` memaksanya aktif kembali.
- `groups.<room>.skills`: filter skill tingkat room opsional.
- `groups.<room>.systemPrompt`: potongan system prompt tingkat room opsional.
- `rooms`: alias lama untuk `groups`.
- `actions`: pengendalian tool per aksi (`messages`, `reactions`, `pins`, `profile`, `memberInfo`, `channelInfo`, `verification`).
- `groups.<room>.tools`: override allow/deny tool per room.
- `groups.<room>.autoReply`: override pembatasan mention tingkat room. `true` menonaktifkan persyaratan mention untuk room tersebut; `false` memaksanya aktif kembali.
- `groups.<room>.skills`: filter skill opsional tingkat room.
- `groups.<room>.systemPrompt`: cuplikan system prompt opsional tingkat room.
- `rooms`: alias lawas untuk `groups`.
- `actions`: gating tool per aksi (`messages`, `reactions`, `pins`, `profile`, `memberInfo`, `channelInfo`, `verification`).
## Terkait
- [Channels Overview](/id/channels) — semua channel yang didukung
- [Pairing](/id/channels/pairing) — auth DM dan alur pairing
- [Groups](/id/channels/groups) — perilaku chat grup dan mention gating
- [Channels Overview](/id/channels) — semua saluran yang didukung
- [Pairing](/id/channels/pairing) — autentikasi DM dan alur pairing
- [Groups](/id/channels/groups) — perilaku chat grup dan pembatasan mention
- [Channel Routing](/id/channels/channel-routing) — perutean sesi untuk pesan
- [Security](/id/gateway/security) — model akses dan hardening
- [Security](/id/gateway/security) — model akses dan penguatan

289
docs/id/channels/slack.md
View File

@ -1,34 +1,34 @@
---
read_when:
- Menyiapkan Slack atau men-debug mode socket/HTTP Slack
summary: Pengaturan Slack dan perilaku runtime (Socket Mode + HTTP Events API)
summary: Penyiapan Slack dan perilaku runtime (Socket Mode + HTTP Request URLs)
title: Slack
x-i18n:
generated_at: "2026-04-06T03:06:47Z"
generated_at: "2026-04-06T09:14:03Z"
model: gpt-5.4
provider: openai
source_hash: 7e4ff2ce7d92276d62f4f3d3693ddb56ca163d5fdc2f1082ff7ba3421fada69c
source_hash: 897001c13d400cc8387a27000b82dd4c0512b2b88e2fe47785634aed8b7ab7af
source_path: channels/slack.md
workflow: 15
---
# Slack
Status: siap produksi untuk DM + channel melalui integrasi aplikasi Slack. Mode default adalah Socket Mode; mode HTTP Events API juga didukung.
Status: siap produksi untuk DM + channel melalui integrasi aplikasi Slack. Mode default adalah Socket Mode; HTTP Request URLs juga didukung.
<CardGroup cols={3}>
<Card title="Pairing" icon="link" href="/id/channels/pairing">
DM Slack secara default menggunakan mode pairing.
DM Slack default ke mode pairing.
</Card>
<Card title="Slash commands" icon="terminal" href="/id/tools/slash-commands">
Perilaku perintah native dan katalog perintah.
</Card>
<Card title="Channel troubleshooting" icon="wrench" href="/id/channels/troubleshooting">
Diagnostik lintas-channel dan playbook perbaikan.
Diagnostik lintas channel dan playbook perbaikan.
</Card>
</CardGroup>
## Pengaturan cepat
## Penyiapan cepat
<Tabs>
<Tab title="Socket Mode (default)">
@ -89,13 +89,13 @@ openclaw gateway
</Tab>
<Tab title="Mode HTTP Events API">
<Tab title="HTTP Request URLs">
<Steps>
<Step title="Konfigurasikan aplikasi Slack untuk HTTP">
- setel mode ke HTTP (`channels.slack.mode="http"`)
- salin **Signing Secret** Slack
- setel Event Subscriptions + Interactivity + URL Permintaan Slash command ke path webhook yang sama (default `/slack/events`)
- setel URL Permintaan Event Subscriptions + Interactivity + Slash command ke path webhook yang sama (default `/slack/events`)
</Step>
@ -120,17 +120,17 @@ openclaw gateway
<Step title="Gunakan path webhook unik untuk HTTP multi-akun">
Mode HTTP per akun didukung.
Berikan `webhookPath` yang berbeda untuk setiap akun agar pendaftaran tidak bertabrakan.
Berikan setiap akun `webhookPath` yang berbeda agar pendaftaran tidak bentrok.
</Step>
</Steps>
</Tab>
</Tabs>
## Checklist manifes dan scope
## Manifest dan daftar periksa scope
<AccordionGroup>
<Accordion title="Contoh manifes aplikasi Slack" defaultOpen>
<Tabs>
<Tab title="Socket Mode (default)">
```json
{
@ -205,10 +205,101 @@ openclaw gateway
}
```
</Accordion>
</Tab>
<Tab title="HTTP Request URLs">
```json
{
"display_information": {
"name": "OpenClaw",
"description": "Slack connector for OpenClaw"
},
"features": {
"bot_user": {
"display_name": "OpenClaw",
"always_online": true
},
"app_home": {
"messages_tab_enabled": true,
"messages_tab_read_only_enabled": false
},
"slash_commands": [
{
"command": "/openclaw",
"description": "Send a message to OpenClaw",
"should_escape": false,
"url": "https://gateway-host.example.com/slack/events"
}
]
},
"oauth_config": {
"scopes": {
"bot": [
"app_mentions:read",
"assistant:write",
"channels:history",
"channels:read",
"chat:write",
"commands",
"emoji:read",
"files:read",
"files:write",
"groups:history",
"groups:read",
"im:history",
"im:read",
"im:write",
"mpim:history",
"mpim:read",
"mpim:write",
"pins:read",
"pins:write",
"reactions:read",
"reactions:write",
"users:read"
]
}
},
"settings": {
"event_subscriptions": {
"request_url": "https://gateway-host.example.com/slack/events",
"bot_events": [
"app_mention",
"channel_rename",
"member_joined_channel",
"member_left_channel",
"message.channels",
"message.groups",
"message.im",
"message.mpim",
"pin_added",
"pin_removed",
"reaction_added",
"reaction_removed"
]
},
"interactivity": {
"is_enabled": true,
"request_url": "https://gateway-host.example.com/slack/events",
"message_menu_options_url": "https://gateway-host.example.com/slack/events"
}
}
}
```
</Tab>
</Tabs>
<AccordionGroup>
<Accordion title="Scope authorship opsional (operasi tulis)">
Tambahkan bot scope `chat:write.customize` jika Anda ingin pesan keluar menggunakan identitas agen aktif (username dan ikon kustom) alih-alih identitas aplikasi Slack default.
Jika Anda menggunakan ikon emoji, Slack mengharapkan sintaks `:emoji_name:`.
</Accordion>
<Accordion title="Scope user-token opsional (operasi baca)">
Jika Anda mengonfigurasi `channels.slack.userToken`, scope baca yang umum adalah:
Jika Anda mengonfigurasi `channels.slack.userToken`, scope baca umum adalah:
- `channels:history`, `groups:history`, `im:history`, `mpim:history`
- `channels:read`, `groups:read`, `im:read`, `mpim:read`
@ -223,43 +314,42 @@ openclaw gateway
## Model token
- `botToken` + `appToken` diperlukan untuk Socket Mode.
- `botToken` + `appToken` wajib untuk Socket Mode.
- Mode HTTP memerlukan `botToken` + `signingSecret`.
- `botToken`, `appToken`, `signingSecret`, dan `userToken` menerima string
plaintext atau objek SecretRef.
- Token config mengesampingkan fallback env.
- `botToken`, `appToken`, `signingSecret`, dan `userToken` menerima string plaintext
atau objek SecretRef.
- Token config menimpa fallback env.
- Fallback env `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` hanya berlaku untuk akun default.
- `userToken` (`xoxp-...`) hanya config (tanpa fallback env) dan default ke perilaku hanya-baca (`userTokenReadOnly: true`).
- Opsional: tambahkan `chat:write.customize` jika Anda ingin pesan keluar menggunakan identitas agen aktif (`username` dan ikon kustom). `icon_emoji` menggunakan sintaks `:emoji_name:`.
- `userToken` (`xoxp-...`) hanya untuk config (tanpa fallback env) dan default ke perilaku hanya-baca (`userTokenReadOnly: true`).
Perilaku snapshot status:
- Inspeksi akun Slack melacak field `*Source` dan `*Status` per kredensial
(`botToken`, `appToken`, `signingSecret`, `userToken`).
- Inspeksi akun Slack melacak field `*Source` dan `*Status`
per kredensial (`botToken`, `appToken`, `signingSecret`, `userToken`).
- Status adalah `available`, `configured_unavailable`, atau `missing`.
- `configured_unavailable` berarti akun dikonfigurasi melalui SecretRef
atau sumber secret non-inline lain, tetapi jalur perintah/runtime saat ini
atau sumber secret non-inline lain, tetapi path perintah/runtime saat ini
tidak dapat me-resolve nilai sebenarnya.
- Dalam mode HTTP, `signingSecretStatus` disertakan; dalam Socket Mode,
pasangan yang diperlukan adalah `botTokenStatus` + `appTokenStatus`.
<Tip>
Untuk aksi/pembacaan direktori, user token dapat diprioritaskan jika dikonfigurasi. Untuk penulisan, bot token tetap diprioritaskan; penulisan dengan user-token hanya diizinkan ketika `userTokenReadOnly: false` dan bot token tidak tersedia.
Untuk aksi/pembacaan direktori, user token dapat diprioritaskan jika dikonfigurasi. Untuk penulisan, bot token tetap diprioritaskan; penulisan dengan user token hanya diizinkan ketika `userTokenReadOnly: false` dan bot token tidak tersedia.
</Tip>
## Aksi dan gate
Aksi Slack dikendalikan oleh `channels.slack.actions.*`.
Grup aksi yang tersedia dalam tooling Slack saat ini:
Grup aksi yang tersedia pada tooling Slack saat ini:
| Grup | Default |
| ---------- | ------- |
| messages | enabled |
| reactions | enabled |
| pins | enabled |
| memberInfo | enabled |
| emojiList | enabled |
| messages | aktif |
| reactions | aktif |
| pins | aktif |
| memberInfo | aktif |
| emojiList | aktif |
Aksi pesan Slack saat ini mencakup `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info`, dan `emoji-list`.
@ -271,7 +361,7 @@ Aksi pesan Slack saat ini mencakup `send`, `upload-file`, `download-file`, `read
- `pairing` (default)
- `allowlist`
- `open` (memerlukan `channels.slack.allowFrom` untuk menyertakan `"*"`; legacy: `channels.slack.dm.allowFrom`)
- `open` (memerlukan `channels.slack.allowFrom` menyertakan `"*"`; legacy: `channels.slack.dm.allowFrom`)
- `disabled`
Flag DM:
@ -279,13 +369,13 @@ Aksi pesan Slack saat ini mencakup `send`, `upload-file`, `download-file`, `read
- `dm.enabled` (default true)
- `channels.slack.allowFrom` (disarankan)
- `dm.allowFrom` (legacy)
- `dm.groupEnabled` (default grup DM false)
- `dm.groupEnabled` (default DM grup false)
- `dm.groupChannels` (allowlist MPIM opsional)
Prioritas multi-akun:
- `channels.slack.accounts.default.allowFrom` hanya berlaku untuk akun `default`.
- Akun bernama mewarisi `channels.slack.allowFrom` ketika `allowFrom` milik mereka sendiri tidak disetel.
- Akun bernama mewarisi `channels.slack.allowFrom` ketika `allowFrom` miliknya sendiri tidak disetel.
- Akun bernama tidak mewarisi `channels.slack.accounts.default.allowFrom`.
Pairing di DM menggunakan `openclaw pairing approve slack <code>`.
@ -301,26 +391,26 @@ Aksi pesan Slack saat ini mencakup `send`, `upload-file`, `download-file`, `read
Allowlist channel berada di bawah `channels.slack.channels` dan sebaiknya menggunakan ID channel yang stabil.
Catatan runtime: jika `channels.slack` sama sekali tidak ada (pengaturan hanya-env), runtime akan fallback ke `groupPolicy="allowlist"` dan mencatat peringatan (bahkan jika `channels.defaults.groupPolicy` disetel).
Catatan runtime: jika `channels.slack` sama sekali tidak ada (penyiapan hanya env), runtime akan fallback ke `groupPolicy="allowlist"` dan mencatat peringatan (bahkan jika `channels.defaults.groupPolicy` disetel).
Resolusi nama/ID:
- entri allowlist channel dan entri allowlist DM di-resolve saat startup ketika akses token memungkinkan
- entri nama channel yang tidak ter-resolve dipertahankan sesuai konfigurasi tetapi diabaikan untuk routing secara default
- otorisasi inbound dan routing channel menggunakan ID terlebih dahulu secara default; pencocokan langsung username/slug memerlukan `channels.slack.dangerouslyAllowNameMatching: true`
- entri nama channel yang tidak ter-resolve tetap disimpan sesuai konfigurasi tetapi diabaikan untuk routing secara default
- otorisasi inbound dan routing channel secara default berbasis ID; pencocokan langsung username/slug memerlukan `channels.slack.dangerouslyAllowNameMatching: true`
</Tab>
<Tab title="Mention dan pengguna channel">
Pesan channel digate oleh mention secara default.
Pesan channel secara default digate oleh mention.
Sumber mention:
- mention aplikasi eksplisit (`<@botId>`)
- pola regex mention (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`)
- perilaku thread balas-ke-bot implisit
- perilaku thread reply-to-bot implisit
Kontrol per channel (`channels.slack.channels.<id>`; nama hanya melalui resolusi saat startup atau `dangerouslyAllowNameMatching`):
Kontrol per channel (`channels.slack.channels.<id>`; nama hanya melalui resolusi startup atau `dangerouslyAllowNameMatching`):
- `requireMention`
- `users` (allowlist)
@ -337,9 +427,9 @@ Aksi pesan Slack saat ini mencakup `send`, `upload-file`, `download-file`, `read
## Threading, sesi, dan tag balasan
- DM dirutekan sebagai `direct`; channel sebagai `channel`; MPIM sebagai `group`.
- Dengan default `session.dmScope=main`, DM Slack digabung ke sesi utama agen.
- Dengan default `session.dmScope=main`, DM Slack digabungkan ke sesi utama agen.
- Sesi channel: `agent:<agentId>:slack:channel:<channelId>`.
- Balasan thread dapat membuat sufiks sesi thread (`:thread:<threadTs>`) bila berlaku.
- Balasan thread dapat membuat sufiks sesi thread (`:thread:<threadTs>`) jika berlaku.
- Default `channels.slack.thread.historyScope` adalah `thread`; default `thread.inheritParent` adalah `false`.
- `channels.slack.thread.initialHistoryLimit` mengontrol berapa banyak pesan thread yang sudah ada diambil saat sesi thread baru dimulai (default `20`; setel `0` untuk menonaktifkan).
@ -347,25 +437,25 @@ Kontrol threading balasan:
- `channels.slack.replyToMode`: `off|first|all|batched` (default `off`)
- `channels.slack.replyToModeByChatType`: per `direct|group|channel`
- fallback legacy untuk chat direct: `channels.slack.dm.replyToMode`
- fallback legacy untuk chat langsung: `channels.slack.dm.replyToMode`
Tag balasan manual didukung:
- `[[reply_to_current]]`
- `[[reply_to:<id>]]`
Catatan: `replyToMode="off"` menonaktifkan **semua** threading balasan di Slack, termasuk tag `[[reply_to_*]]` yang eksplisit. Ini berbeda dari Telegram, di mana tag eksplisit tetap dihormati dalam mode `"off"`. Perbedaan ini mencerminkan model threading platform: thread Slack menyembunyikan pesan dari channel, sedangkan balasan Telegram tetap terlihat dalam alur chat utama.
Catatan: `replyToMode="off"` menonaktifkan **semua** threading balasan di Slack, termasuk tag eksplisit `[[reply_to_*]]`. Ini berbeda dari Telegram, di mana tag eksplisit tetap dihormati dalam mode `"off"`. Perbedaan ini mencerminkan model threading platform: thread Slack menyembunyikan pesan dari channel, sedangkan balasan Telegram tetap terlihat dalam alur chat utama.
## Reaksi ack
`ackReaction` mengirim emoji pengakuan saat OpenClaw sedang memproses pesan inbound.
`ackReaction` mengirim emoji pengakuan saat OpenClaw sedang memproses pesan masuk.
Urutan resolusi:
- `channels.slack.accounts.<accountId>.ackReaction`
- `channels.slack.ackReaction`
- `messages.ackReaction`
- fallback emoji identitas agen (`agents.list[].identity.emoji`, atau `"👀"`)
- fallback emoji identitas agen (`agents.list[].identity.emoji`, jika tidak ada gunakan `"👀"`)
Catatan:
@ -378,12 +468,12 @@ Catatan:
- `off`: nonaktifkan streaming pratinjau langsung.
- `partial` (default): ganti teks pratinjau dengan output parsial terbaru.
- `block`: tambahkan pembaruan pratinjau yang dipotong per chunk.
- `block`: tambahkan pembaruan pratinjau bertahap.
- `progress`: tampilkan teks status progres saat menghasilkan, lalu kirim teks final.
`channels.slack.nativeStreaming` mengontrol streaming teks native Slack ketika `streaming` adalah `partial` (default: `true`).
`channels.slack.nativeStreaming` mengontrol streaming teks native Slack saat `streaming` adalah `partial` (default: `true`).
- Thread balasan harus tersedia agar streaming teks native muncul. Pemilihan thread tetap mengikuti `replyToMode`. Tanpanya, pratinjau draf normal akan digunakan.
- Thread balasan harus tersedia agar streaming teks native muncul. Pemilihan thread tetap mengikuti `replyToMode`. Tanpanya, pratinjau draf normal digunakan.
- Payload media dan non-teks fallback ke pengiriman normal.
- Jika streaming gagal di tengah balasan, OpenClaw fallback ke pengiriman normal untuk payload yang tersisa.
@ -407,7 +497,7 @@ Key legacy:
## Fallback reaksi mengetik
`typingReaction` menambahkan reaksi sementara ke pesan Slack inbound saat OpenClaw sedang memproses balasan, lalu menghapusnya saat proses selesai. Ini paling berguna di luar balasan thread, yang menggunakan indikator status default "is typing...".
`typingReaction` menambahkan reaksi sementara ke pesan Slack masuk saat OpenClaw sedang memproses balasan, lalu menghapusnya saat proses selesai. Ini paling berguna di luar balasan thread, yang menggunakan indikator status default "is typing...".
Urutan resolusi:
@ -417,27 +507,27 @@ Urutan resolusi:
Catatan:
- Slack mengharapkan shortcode (misalnya `"hourglass_flowing_sand"`).
- Reaksi ini bersifat best-effort dan pembersihan dicoba secara otomatis setelah balasan atau jalur kegagalan selesai.
- Reaksi ini bersifat best-effort dan pembersihannya dicoba secara otomatis setelah jalur balasan atau kegagalan selesai.
## Media, chunking, dan pengiriman
<AccordionGroup>
<Accordion title="Lampiran inbound">
Lampiran file Slack diunduh dari URL privat yang di-host Slack (alur permintaan terautentikasi token) dan ditulis ke media store ketika pengambilan berhasil dan batas ukuran mengizinkan.
<Accordion title="Lampiran masuk">
Lampiran file Slack diunduh dari URL privat yang di-host Slack (alur permintaan terautentikasi token) dan ditulis ke media store saat pengambilan berhasil dan batas ukuran mengizinkan.
Batas ukuran inbound runtime default adalah `20MB` kecuali dioverride oleh `channels.slack.mediaMaxMb`.
Batas ukuran masuk runtime default adalah `20MB` kecuali ditimpa oleh `channels.slack.mediaMaxMb`.
</Accordion>
<Accordion title="Teks dan file outbound">
<Accordion title="Teks dan file keluar">
- chunk teks menggunakan `channels.slack.textChunkLimit` (default 4000)
- `channels.slack.chunkMode="newline"` mengaktifkan pemisahan paragraf-terlebih-dahulu
- `channels.slack.chunkMode="newline"` mengaktifkan pemisahan berbasis paragraf terlebih dahulu
- pengiriman file menggunakan API upload Slack dan dapat menyertakan balasan thread (`thread_ts`)
- batas media outbound mengikuti `channels.slack.mediaMaxMb` jika dikonfigurasi; jika tidak, pengiriman channel menggunakan default jenis MIME dari pipeline media
- batas media keluar mengikuti `channels.slack.mediaMaxMb` saat dikonfigurasi; jika tidak, pengiriman channel menggunakan default berbasis jenis MIME dari media pipeline
</Accordion>
<Accordion title="Target pengiriman">
Target eksplisit yang disarankan:
Target eksplisit yang diprioritaskan:
- `user:<id>` untuk DM
- `channel:<id>` untuk channel
@ -449,17 +539,17 @@ Catatan:
## Perintah dan perilaku slash
- Mode otomatis perintah native **off** untuk Slack (`commands.native: "auto"` tidak mengaktifkan perintah native Slack).
- Mode otomatis perintah native adalah **off** untuk Slack (`commands.native: "auto"` tidak mengaktifkan perintah native Slack).
- Aktifkan handler perintah Slack native dengan `channels.slack.commands.native: true` (atau global `commands.native: true`).
- Saat perintah native diaktifkan, daftarkan slash command yang sesuai di Slack (nama `/<command>`), dengan satu pengecualian:
- daftarkan `/agentstatus` untuk perintah status (Slack mencadangkan `/status`)
- Jika perintah native tidak diaktifkan, Anda dapat menjalankan satu slash command yang dikonfigurasi melalui `channels.slack.slashCommand`.
- Menu arg native kini menyesuaikan strategi render-nya:
- hingga 5 opsi: blok tombol
- 6-100 opsi: menu select statis
- 6-100 opsi: menu pilih statis
- lebih dari 100 opsi: external select dengan pemfilteran opsi async saat handler opsi interaktivitas tersedia
- jika nilai opsi yang dienkode melebihi batas Slack, alur fallback ke tombol
- Untuk payload opsi yang panjang, menu argumen Slash command menggunakan dialog konfirmasi sebelum mengirim nilai yang dipilih.
- jika nilai opsi terenkode melebihi batas Slack, alur akan fallback ke tombol
- Untuk payload opsi yang panjang, menu arg slash command menggunakan dialog konfirmasi sebelum mengirim nilai yang dipilih.
Pengaturan default slash command:
@ -476,7 +566,7 @@ dan tetap merutekan eksekusi perintah terhadap sesi percakapan target (`CommandT
## Balasan interaktif
Slack dapat merender kontrol balasan interaktif yang dibuat agen, tetapi fitur ini dinonaktifkan secara default.
Slack dapat merender kontrol balasan interaktif yang ditulis agen, tetapi fitur ini dinonaktifkan secara default.
Aktifkan secara global:
@ -515,25 +605,26 @@ Saat diaktifkan, agen dapat mengeluarkan direktif balasan khusus Slack:
- `[[slack_buttons: Approve:approve, Reject:reject]]`
- `[[slack_select: Choose a target | Canary:canary, Production:production]]`
Direktif ini dikompilasi menjadi Slack Block Kit dan merutekan klik atau pilihan kembali melalui jalur event interaksi Slack yang sudah ada.
Direktif ini dikompilasi menjadi Slack Block Kit dan merutekan klik atau pilihan kembali melalui path event interaksi Slack yang ada.
Catatan:
- Ini adalah UI khusus Slack. Channel lain tidak menerjemahkan direktif Slack Block Kit ke sistem tombol mereka sendiri.
- Ini adalah UI khusus Slack. Channel lain tidak menerjemahkan direktif Slack Block Kit ke dalam sistem tombol mereka sendiri.
- Nilai callback interaktif adalah token opak yang dibuat OpenClaw, bukan nilai mentah yang ditulis agen.
- Jika blok interaktif yang dihasilkan melebihi batas Slack Block Kit, OpenClaw fallback ke balasan teks asli alih-alih mengirim payload blocks yang tidak valid.
- Jika blok interaktif yang dihasilkan akan melebihi batas Slack Block Kit, OpenClaw fallback ke balasan teks asli alih-alih mengirim payload blok yang tidak valid.
## Persetujuan exec di Slack
Slack dapat bertindak sebagai klien persetujuan native dengan tombol interaktif dan interaksi, alih-alih fallback ke UI Web atau terminal.
- Persetujuan exec menggunakan `channels.slack.execApprovals.*` untuk routing native DM/channel.
- Persetujuan plugin tetap dapat di-resolve melalui permukaan tombol native Slack yang sama ketika permintaan sudah masuk ke Slack dan jenis id persetujuan adalah `plugin:`.
- Otorisasi pemberi persetujuan tetap diberlakukan: hanya pengguna yang diidentifikasi sebagai approver yang dapat menyetujui atau menolak permintaan melalui Slack.
- Persetujuan exec menggunakan `channels.slack.execApprovals.*` untuk routing DM/channel native.
- Persetujuan plugin tetap dapat di-resolve melalui permukaan tombol native Slack yang sama ketika permintaan sudah masuk ke Slack dan jenis approval id adalah `plugin:`.
- Otorisasi approver tetap diberlakukan: hanya pengguna yang diidentifikasi sebagai approver yang dapat menyetujui atau menolak permintaan melalui Slack.
Ini menggunakan permukaan tombol persetujuan bersama yang sama seperti channel lain. Saat `interactivity` diaktifkan di pengaturan aplikasi Slack Anda, prompt persetujuan dirender sebagai tombol Block Kit langsung di percakapan.
Saat tombol tersebut ada, itulah UX persetujuan utama; OpenClaw
hanya seharusnya menyertakan perintah `/approve` manual ketika hasil tool mengatakan persetujuan chat tidak tersedia atau persetujuan manual adalah satu-satunya jalur.
hanya boleh menyertakan perintah manual `/approve` ketika hasil tool menyatakan persetujuan chat
tidak tersedia atau persetujuan manual adalah satu-satunya jalur.
Path config:
@ -542,9 +633,9 @@ Path config:
- `channels.slack.execApprovals.target` (`dm` | `channel` | `both`, default: `dm`)
- `agentFilter`, `sessionFilter`
Slack otomatis mengaktifkan persetujuan exec native ketika `enabled` tidak disetel atau `"auto"` dan setidaknya satu
approver ter-resolve. Setel `enabled: false` untuk menonaktifkan Slack sebagai klien persetujuan native secara eksplisit.
Setel `enabled: true` untuk memaksa persetujuan native aktif saat approver ter-resolve.
Slack otomatis mengaktifkan persetujuan exec native saat `enabled` tidak disetel atau `"auto"` dan setidaknya satu
approver di-resolve. Setel `enabled: false` untuk menonaktifkan Slack sebagai klien persetujuan native secara eksplisit.
Setel `enabled: true` untuk memaksa persetujuan native aktif saat approver di-resolve.
Perilaku default tanpa config persetujuan exec Slack eksplisit:
@ -556,7 +647,7 @@ Perilaku default tanpa config persetujuan exec Slack eksplisit:
}
```
Config native Slack eksplisit hanya diperlukan ketika Anda ingin mengesampingkan approver, menambahkan filter, atau
Config native Slack eksplisit hanya diperlukan saat Anda ingin menimpa approver, menambahkan filter, atau
memilih pengiriman origin-chat:
```json5
@ -573,26 +664,26 @@ memilih pengiriman origin-chat:
}
```
Penerusan bersama `approvals.exec` bersifat terpisah. Gunakan hanya ketika prompt persetujuan exec juga harus
dirutekan ke chat lain atau target luar-band eksplisit. Penerusan bersama `approvals.plugin` juga
Forwarding bersama `approvals.exec` terpisah. Gunakan hanya ketika prompt persetujuan exec juga harus
dirutekan ke chat lain atau target out-of-band yang eksplisit. Forwarding bersama `approvals.plugin` juga
terpisah; tombol native Slack tetap dapat me-resolve persetujuan plugin ketika permintaan tersebut sudah masuk
ke Slack.
`/approve` dalam chat yang sama juga berfungsi di channel dan DM Slack yang sudah mendukung perintah. Lihat [Persetujuan exec](/id/tools/exec-approvals) untuk model penerusan persetujuan lengkap.
`/approve` di chat yang sama juga berfungsi di channel dan DM Slack yang sudah mendukung perintah. Lihat [Persetujuan exec](/id/tools/exec-approvals) untuk model forwarding persetujuan lengkap.
## Event dan perilaku operasional
- Pengeditan/penghapusan pesan/thread broadcast dipetakan ke event sistem.
- Event tambah/hapus reaksi dipetakan ke event sistem.
- Event anggota masuk/keluar, channel dibuat/diubah namanya, dan tambah/hapus pin dipetakan ke event sistem.
- `channel_id_changed` dapat memigrasikan key config channel ketika `configWrites` diaktifkan.
- Metadata topik/tujuan channel diperlakukan sebagai konteks tidak tepercaya dan dapat disuntikkan ke konteks routing.
- Thread starter dan penanaman awal konteks riwayat thread difilter oleh allowlist pengirim yang dikonfigurasi jika berlaku.
- Block action dan interaksi modal menghasilkan event sistem terstruktur `Slack interaction: ...` dengan field payload yang kaya:
- block action: nilai terpilih, label, nilai picker, dan metadata `workflow_*`
- Edit/hapus pesan/thread broadcast dipetakan menjadi event sistem.
- Event tambah/hapus reaksi dipetakan menjadi event sistem.
- Event bergabung/keluar anggota, channel dibuat/diubah namanya, dan tambah/hapus pin dipetakan menjadi event sistem.
- `channel_id_changed` dapat memigrasikan key config channel saat `configWrites` diaktifkan.
- Metadata topic/purpose channel diperlakukan sebagai konteks tidak tepercaya dan dapat diinjeksi ke konteks routing.
- Thread starter dan penyemaian konteks riwayat thread awal difilter oleh allowlist pengirim yang dikonfigurasi bila berlaku.
- Block action dan interaksi modal memunculkan event sistem terstruktur `Slack interaction: ...` dengan field payload yang kaya:
- block action: nilai yang dipilih, label, nilai picker, dan metadata `workflow_*`
- event modal `view_submission` dan `view_closed` dengan metadata channel yang dirutekan dan input formulir
## Penunjuk referensi konfigurasi
## Petunjuk referensi konfigurasi
Referensi utama:
@ -601,7 +692,7 @@ Referensi utama:
Field Slack dengan sinyal tinggi:
- mode/auth: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*`
- akses DM: `dm.enabled`, `dmPolicy`, `allowFrom` (legacy: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels`
- toggle kompatibilitas: `dangerouslyAllowNameMatching` (break-glass; biarkan nonaktif kecuali diperlukan)
- toggle kompatibilitas: `dangerouslyAllowNameMatching` (pemutus kaca darurat; biarkan nonaktif kecuali diperlukan)
- akses channel: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention`
- threading/riwayat: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
- pengiriman: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `nativeStreaming`
@ -633,7 +724,7 @@ openclaw doctor
- `channels.slack.dm.enabled`
- `channels.slack.dmPolicy` (atau legacy `channels.slack.dm.policy`)
- pairing approvals / entri allowlist
- persetujuan pairing / entri allowlist
```bash
openclaw pairing list slack
@ -642,11 +733,11 @@ openclaw pairing list slack
</Accordion>
<Accordion title="Mode socket tidak terhubung">
Validasi token bot + aplikasi dan pengaktifan Socket Mode di pengaturan aplikasi Slack.
Validasi bot + app token dan pengaktifan Socket Mode di pengaturan aplikasi Slack.
Jika `openclaw channels status --probe --json` menampilkan `botTokenStatus` atau
`appTokenStatus: "configured_unavailable"`, akun Slack tersebut
sudah dikonfigurasi tetapi runtime saat ini tidak dapat me-resolve nilai
`appTokenStatus: "configured_unavailable"`, akun Slack telah
dikonfigurasi tetapi runtime saat ini tidak dapat me-resolve nilai
yang didukung SecretRef.
</Accordion>
@ -656,11 +747,11 @@ openclaw pairing list slack
- signing secret
- path webhook
- URL Permintaan Slack (Events + Interactivity + Slash Commands)
- Slack Request URLs (Events + Interactivity + Slash Commands)
- `webhookPath` unik per akun HTTP
Jika `signingSecretStatus: "configured_unavailable"` muncul dalam snapshot
akun, akun HTTP tersebut sudah dikonfigurasi tetapi runtime saat ini tidak dapat
Jika `signingSecretStatus: "configured_unavailable"` muncul di snapshot
akun, akun HTTP telah dikonfigurasi tetapi runtime saat ini tidak dapat
me-resolve signing secret yang didukung SecretRef.
</Accordion>
@ -679,9 +770,9 @@ openclaw pairing list slack
## Terkait
- [Pairing](/id/channels/pairing)
- [Grup](/id/channels/groups)
- [Keamanan](/id/gateway/security)
- [Routing channel](/id/channels/channel-routing)
- [Pemecahan masalah](/id/channels/troubleshooting)
- [Konfigurasi](/id/gateway/configuration)
- [Groups](/id/channels/groups)
- [Security](/id/gateway/security)
- [Channel routing](/id/channels/channel-routing)
- [Troubleshooting](/id/channels/troubleshooting)
- [Configuration](/id/gateway/configuration)
- [Slash commands](/id/tools/slash-commands)

91
docs/id/concepts/dreaming.md
View File

@ -6,10 +6,10 @@ read_when:
summary: Konsolidasi memori latar belakang dengan fase light, deep, dan REM serta Dream Diary
title: Dreaming (eksperimental)
x-i18n:
generated_at: "2026-04-06T03:06:13Z"
generated_at: "2026-04-06T09:13:18Z"
model: gpt-5.4
provider: openai
source_hash: f27da718176bebf59fe8a80fddd4fb5b6d814ac5647f6c1e8344bcfb328db9de
source_hash: 36c4b1e70801d662090dc8ce20608c2f141c23cd7ce53c54e3dcf332c801fd4e
source_path: concepts/dreaming.md
workflow: 15
---
@ -17,19 +17,19 @@ x-i18n:
# Dreaming (eksperimental)
Dreaming adalah sistem konsolidasi memori latar belakang di `memory-core`.
Ini membantu OpenClaw memindahkan sinyal jangka pendek yang kuat ke memori yang tahan lama sambil
Sistem ini membantu OpenClaw memindahkan sinyal jangka pendek yang kuat ke memori yang tahan lama sambil
menjaga prosesnya tetap dapat dijelaskan dan ditinjau.
Dreaming bersifat **opt-in** dan dinonaktifkan secara default.
Dreaming bersifat **opsional** dan dinonaktifkan secara default.
## Apa yang ditulis oleh dreaming
## Apa yang ditulis dreaming
Dreaming menyimpan dua jenis keluaran:
Dreaming menyimpan dua jenis output:
- **Status mesin** di `memory/.dreams/` (penyimpanan recall, sinyal fase, checkpoint ingestion, lock).
- **Keluaran yang dapat dibaca manusia** di `DREAMS.md` (atau `dreams.md` yang sudah ada) dan file laporan fase opsional di bawah `memory/dreaming/<phase>/YYYY-MM-DD.md`.
- **Output yang dapat dibaca manusia** di `DREAMS.md` (atau `dreams.md` yang sudah ada) dan file laporan fase opsional di bawah `memory/dreaming/<phase>/YYYY-MM-DD.md`.
Promosi jangka panjang masih hanya menulis ke `MEMORY.md`.
Promosi jangka panjang tetap hanya menulis ke `MEMORY.md`.
## Model fase
@ -37,12 +37,12 @@ Dreaming menggunakan tiga fase kooperatif:
| Fase | Tujuan | Penulisan permanen |
| ----- | ----------------------------------------- | ------------------ |
| Light | Menyortir dan menyiapkan materi jangka pendek terbaru | Tidak |
| Deep | Menilai dan mempromosikan kandidat yang tahan lama | Ya (`MEMORY.md`) |
| REM | Merefleksikan tema dan ide yang berulang | Tidak |
| Light | Mengurutkan dan menyiapkan materi jangka pendek terbaru | Tidak |
| Deep | Menilai dan mempromosikan kandidat yang tahan lama | Ya (`MEMORY.md`) |
| REM | Merefleksikan tema dan gagasan yang berulang | Tidak |
Fase-fase ini adalah detail implementasi internal, bukan "mode" terpisah yang
dikonfigurasi oleh pengguna.
Fase-fase ini adalah detail implementasi internal, bukan "mode" terpisah
yang dikonfigurasi pengguna.
### Fase light
@ -50,17 +50,17 @@ Fase light mengingest sinyal memori harian terbaru dan jejak recall, menghapus d
dan menyiapkan baris kandidat.
- Membaca dari status recall jangka pendek dan file memori harian terbaru.
- Menulis blok `## Light Sleep` yang dikelola ketika penyimpanan mencakup keluaran inline.
- Mencatat sinyal reinforcement untuk pemeringkatan deep nanti.
- Menulis blok `## Light Sleep` yang dikelola saat penyimpanan menyertakan output inline.
- Mencatat sinyal reinforcement untuk pemeringkatan deep berikutnya.
- Tidak pernah menulis ke `MEMORY.md`.
### Fase deep
Fase deep menentukan apa yang menjadi memori jangka panjang.
- Memeringkat kandidat menggunakan penilaian berbobot dan ambang batas.
- Memberi peringkat kandidat menggunakan penilaian berbobot dan ambang batas.
- Mengharuskan `minScore`, `minRecallCount`, dan `minUniqueQueries` terpenuhi.
- Merehidrasi cuplikan dari file harian aktif sebelum menulis, sehingga cuplikan usang/terhapus dilewati.
- Merehidrasi potongan dari file harian aktif sebelum menulis, sehingga potongan yang usang/dihapus dilewati.
- Menambahkan entri yang dipromosikan ke `MEMORY.md`.
- Menulis ringkasan `## Deep Sleep` ke `DREAMS.md` dan secara opsional menulis `memory/dreaming/deep/YYYY-MM-DD.md`.
@ -69,7 +69,7 @@ Fase deep menentukan apa yang menjadi memori jangka panjang.
Fase REM mengekstrak pola dan sinyal reflektif.
- Membangun ringkasan tema dan refleksi dari jejak jangka pendek terbaru.
- Menulis blok `## REM Sleep` yang dikelola ketika penyimpanan mencakup keluaran inline.
- Menulis blok `## REM Sleep` yang dikelola saat penyimpanan menyertakan output inline.
- Mencatat sinyal reinforcement REM yang digunakan oleh pemeringkatan deep.
- Tidak pernah menulis ke `MEMORY.md`.
@ -85,27 +85,27 @@ Diary ini untuk dibaca manusia di UI Dreams, bukan sumber promosi.
Pemeringkatan deep menggunakan enam sinyal dasar berbobot ditambah reinforcement fase:
| Sinyal | Bobot | Deskripsi |
| ------------------- | ----- | ------------------------------------------------ |
| Frekuensi | 0.24 | Berapa banyak sinyal jangka pendek yang dikumpulkan entri |
| Relevansi | 0.30 | Kualitas pengambilan rata-rata untuk entri |
| Keragaman kueri | 0.15 | Konteks kueri/hari berbeda yang memunculkannya |
| Kemutakhiran | 0.15 | Skor kesegaran dengan peluruhan waktu |
| Konsolidasi | 0.10 | Kekuatan kemunculan ulang multi-hari |
| Kekayaan konseptual | 0.06 | Kepadatan tag konsep dari cuplikan/path |
| Sinyal | Bobot | Deskripsi |
| ------------------- | ------ | ------------------------------------------------- |
| Frekuensi | 0.24 | Berapa banyak sinyal jangka pendek yang dikumpulkan entri |
| Relevansi | 0.30 | Kualitas pengambilan rata-rata untuk entri |
| Keragaman kueri | 0.15 | Konteks kueri/hari berbeda yang memunculkannya |
| Kebaruan | 0.15 | Skor kesegaran dengan peluruhan waktu |
| Konsolidasi | 0.10 | Kekuatan kemunculan berulang lintas hari |
| Kekayaan konseptual | 0.06 | Kepadatan tag konsep dari potongan/path |
Hit fase light dan REM menambahkan peningkatan kecil dengan peluruhan kemutakhiran dari
Hit fase light dan REM menambahkan peningkatan kecil dengan peluruhan kebaruan dari
`memory/.dreams/phase-signals.json`.
## Penjadwalan
Saat diaktifkan, `memory-core` mengelola otomatis satu cron job untuk satu sapuan
dreaming penuh. Setiap sapuan menjalankan fase secara berurutan: light -> REM -> deep.
Saat diaktifkan, `memory-core` mengelola secara otomatis satu pekerjaan cron untuk satu sapuan dreaming
penuh. Setiap sapuan menjalankan fase secara berurutan: light -> REM -> deep.
Perilaku cadence default:
Perilaku kadens default:
| Pengaturan | Default |
| -------------------- | ----------- |
| Pengaturan | Default |
| ------------------- | ----------- |
| `dreaming.frequency` | `0 3 * * *` |
## Mulai cepat
@ -128,7 +128,7 @@ Aktifkan dreaming:
}
```
Aktifkan dreaming dengan cadence sapuan khusus:
Aktifkan dreaming dengan kadens sapuan kustom:
```json
{
@ -168,9 +168,24 @@ openclaw memory promote --limit 5
openclaw memory status --deep
```
`memory promote` manual menggunakan ambang batas fase deep secara default kecuali dioverride
`memory promote` manual menggunakan ambang batas fase deep secara default kecuali ditimpa
dengan flag CLI.
Jelaskan mengapa kandidat tertentu akan atau tidak akan dipromosikan:
```bash
openclaw memory promote-explain "router vlan"
openclaw memory promote-explain "router vlan" --json
```
Pratinjau refleksi REM, kebenaran kandidat, dan output promosi deep tanpa
menulis apa pun:
```bash
openclaw memory rem-harness
openclaw memory rem-harness --json
```
## Default utama
Semua pengaturan berada di bawah `plugins.entries.memory-core.config.dreaming`.
@ -181,19 +196,19 @@ Semua pengaturan berada di bawah `plugins.entries.memory-core.config.dreaming`.
| `frequency` | `0 3 * * *` |
Kebijakan fase, ambang batas, dan perilaku penyimpanan adalah detail implementasi
internal (bukan konfigurasi yang ditujukan bagi pengguna).
internal (bukan konfigurasi yang ditujukan untuk pengguna).
Lihat [Referensi konfigurasi Memory](/id/reference/memory-config#dreaming-experimental)
untuk daftar kunci lengkap.
## UI Dreams
Saat diaktifkan, tab **Dreams** Gateway menampilkan:
Saat diaktifkan, tab **Dreams** di Gateway menampilkan:
- status dreaming aktif saat ini
- status aktif dreaming saat ini
- status tingkat fase dan keberadaan sapuan terkelola
- jumlah jangka pendek, jangka panjang, dan yang dipromosikan hari ini
- waktu eksekusi terjadwal berikutnya
- waktu jalan terjadwal berikutnya
- pembaca Dream Diary yang dapat diperluas yang didukung oleh `doctor.memory.dreamDiary`
## Terkait

1064
docs/id/gateway/configuration-reference.md
View File

File diff suppressed because it is too large Load Diff

252
docs/id/plugins/sdk-migration.md
View File

@ -5,13 +5,13 @@ read_when:
- Anda sedang memperbarui plugin ke arsitektur plugin modern
- Anda memelihara plugin OpenClaw eksternal
sidebarTitle: Migrate to SDK
summary: Migrasikan dari lapisan kompatibilitas mundur lama ke plugin SDK modern
summary: Bermigrasi dari lapisan kompatibilitas mundur lama ke plugin SDK modern
title: Migrasi Plugin SDK
x-i18n:
generated_at: "2026-04-06T03:09:46Z"
generated_at: "2026-04-06T09:14:12Z"
model: gpt-5.4
provider: openai
source_hash: b71ce69b30c3bb02da1b263b1d11dc3214deae5f6fc708515e23b5a1c7bb7c8f
source_hash: 94f12d1376edd8184714cc4dbea4a88fa8ed652f65e9365ede6176f3bf441b33
source_path: plugins/sdk-migration.md
workflow: 15
---
@ -24,59 +24,59 @@ arsitektur baru, 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 entry point:
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 lama tetap berfungsi saat
helper. Ini diperkenalkan untuk menjaga plugin berbasis hook yang lebih lama tetap berfungsi saat
arsitektur plugin baru sedang dibangun.
- **`openclaw/extension-api`** — jembatan yang memberi plugin akses langsung ke
helper sisi host seperti embedded agent runner.
- **`openclaw/extension-api`** — sebuah jembatan yang memberi plugin akses langsung ke
helper sisi host seperti runner agen tertanam.
Kedua permukaan ini sekarang **deprecated**. Keduanya masih berfungsi saat runtime, tetapi plugin
baru tidak boleh menggunakannya, dan plugin yang ada sebaiknya bermigrasi sebelum rilis
mayor berikutnya menghapusnya.
baru tidak boleh menggunakannya, dan plugin yang sudah ada harus bermigrasi sebelum rilis
utama berikutnya menghapusnya.
<Warning>
Lapisan kompatibilitas mundur akan dihapus dalam rilis mayor mendatang.
Lapisan kompatibilitas mundur akan dihapus pada rilis utama mendatang.
Plugin yang masih mengimpor dari permukaan ini akan rusak saat itu terjadi.
</Warning>
## Mengapa ini berubah
Pendekatan lama menimbulkan masalah:
Pendekatan lama menyebabkan 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 membedakan ekspor yang stabil dan yang internal
- **Permukaan API tidak jelas** — tidak ada cara untuk mengetahui ekspor mana yang stabil vs internal
Plugin SDK modern memperbaiki ini: setiap path 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 berdiri sendiri dengan tujuan yang jelas dan kontrak yang terdokumentasi.
Seam kemudahan provider lama untuk channel bawaan juga telah dihapus. Impor
Seam kenyamanan 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
seam helper berjenama 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 tersebut.
workspace plugin bawaan, simpan helper milik provider di `api.ts` atau `runtime-api.ts`
milik plugin tersebut.
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 dan helper onboarding/config di
`api.ts` miliknya sendiri
- OpenAI menyimpan builder provider, helper model default, dan provider realtime
builder di `api.ts` miliknya sendiri
- OpenRouter menyimpan builder provider dan helper onboarding/config di `api.ts`
miliknya sendiri
## Cara bermigrasi
<Steps>
<Step title="Audit perilaku fallback wrapper Windows">
Jika plugin Anda menggunakan `openclaw/plugin-sdk/windows-spawn`, wrapper Windows
`.cmd`/`.bat` yang tidak dapat diselesaikan sekarang gagal secara tertutup kecuali Anda secara eksplisit meneruskan
`.cmd`/`.bat` yang tidak terselesaikan sekarang gagal secara tertutup kecuali Anda secara eksplisit memberikan
`allowShellFallback: true`.
```typescript
@ -92,13 +92,13 @@ Contoh provider bawaan saat ini:
});
```
Jika pemanggil Anda tidak memang bergantung pada shell fallback, jangan setel
Jika pemanggil Anda tidak secara sengaja bergantung pada fallback shell, jangan set
`allowShellFallback` dan tangani error yang dilempar sebagai gantinya.
</Step>
<Step title="Temukan impor yang deprecated">
Cari di plugin Anda impor dari salah satu permukaan deprecated:
Cari plugin Anda untuk impor dari salah satu permukaan yang deprecated:
```bash
grep -r "plugin-sdk/compat" my-plugin/
@ -108,7 +108,7 @@ Contoh provider bawaan saat ini:
</Step>
<Step title="Ganti dengan impor yang terfokus">
Setiap ekspor dari permukaan lama dipetakan ke path impor modern tertentu:
Setiap ekspor dari permukaan lama dipetakan ke jalur impor modern tertentu:
```typescript
// Before (deprecated backwards-compatibility layer)
@ -136,7 +136,7 @@ Contoh provider bawaan saat ini:
const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });
```
Pola yang sama berlaku untuk helper bridge lama lainnya:
Pola yang sama berlaku untuk helper jembatan lama lainnya:
| Impor lama | Padanan modern |
| --- | --- |
@ -146,7 +146,7 @@ Contoh provider bawaan saat ini:
| `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` |
| `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` |
| `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` |
| helper session store | `api.runtime.agent.session.*` |
| helper penyimpanan sesi | `api.runtime.agent.session.*` |
</Step>
@ -158,164 +158,172 @@ Contoh provider bawaan saat ini:
</Step>
</Steps>
## Referensi path impor
## Referensi jalur impor
<Accordion title="Tabel path impor umum">
| Path impor | Tujuan | Ekspor utama |
<Accordion title="Tabel jalur impor umum">
| Jalur impor | Tujuan | Ekspor utama |
| --- | --- | --- |
| `plugin-sdk/plugin-entry` | Helper entry plugin kanonis | `definePluginEntry` |
| `plugin-sdk/core` | Ekspor ulang payung lama untuk definisi/builder entry channel | `defineChannelPluginEntry`, `createChatChannelPlugin` |
| `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 config root | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | Helper entry provider tunggal | `defineSingleProviderPluginEntry` |
| `plugin-sdk/channel-core` | Definisi dan builder entry channel yang terfokus | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/setup` | Helper wizard penyiapan bersama | Prompt allowlist, builder status penyiapan |
| `plugin-sdk/setup-runtime` | Helper runtime saat penyiapan | Adapter patch penyiapan yang aman untuk impor, helper catatan lookup, `promptResolvedAllowFrom`, `splitSetupEntries`, proxy penyiapan terdelegasi |
| `plugin-sdk/setup-adapter-runtime` | Helper adapter penyiapan | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | Helper tooling penyiapan | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `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 diimpor, helper catatan lookup, `promptResolvedAllowFrom`, `splitSetupEntries`, proksi 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/config/action-gate |
| `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 sempit | Helper daftar akun/aksi akun |
| `plugin-sdk/channel-setup` | Adapter wizard penyiapan | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, ditambah `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
| `plugin-sdk/channel-pairing` | Primitif pairing DM | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | Prefix balasan + wiring typing | `createChannelReplyPipeline` |
| `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` | Primitive pairing DM | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | Wiring prefiks balasan + typing | `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 route bersama + builder envelope |
| `plugin-sdk/inbound-reply-dispatch` | Helper balasan masuk | Helper record-and-dispatch bersama |
| `plugin-sdk/inbound-envelope` | Helper envelope inbound | Helper route bersama + builder envelope |
| `plugin-sdk/inbound-reply-dispatch` | Helper balasan inbound | Helper record-and-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 kirim keluar |
| `plugin-sdk/thread-bindings-runtime` | Helper thread-binding | Helper siklus hidup dan adapter thread-binding |
| `plugin-sdk/agent-media-payload` | Helper payload media lama | Builder payload media agent untuk tata letak field lama |
| `plugin-sdk/outbound-media` | Helper media outbound | Pemuatan media outbound bersama |
| `plugin-sdk/outbound-runtime` | Helper runtime outbound | Helper identitas/delegasi kirim outbound |
| `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 layout field lama |
| `plugin-sdk/channel-runtime` | Shim kompatibilitas deprecated | Hanya utilitas runtime channel lama |
| `plugin-sdk/channel-send-result` | Tipe hasil pengiriman | Tipe hasil balasan |
| `plugin-sdk/channel-send-result` | Tipe hasil kirim | Tipe hasil balasan |
| `plugin-sdk/runtime-store` | Penyimpanan plugin persisten | `createPluginRuntimeStore` |
| `plugin-sdk/runtime` | Helper runtime luas | Helper runtime/logging/backup/instalasi plugin |
| `plugin-sdk/runtime-env` | Helper env runtime sempit | Helper logger/runtime env, timeout, retry, dan backoff |
| `plugin-sdk/plugin-runtime` | Helper runtime plugin bersama | Helper plugin command/hook/http/interaktif |
| `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 plugin commands/hooks/http/interactive |
| `plugin-sdk/hook-runtime` | Helper pipeline hook | Helper pipeline webhook/internal hook 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 | Pemformatan perintah, wait, helper versi |
| `plugin-sdk/gateway-runtime` | Helper gateway | Helper klien gateway dan patch status channel |
| `plugin-sdk/config-runtime` | Helper config | Helper muat/tulis config |
| `plugin-sdk/telegram-command-config` | Helper perintah Telegram | Helper validasi perintah Telegram yang stabil untuk fallback saat permukaan kontrak Telegram bawaan tidak tersedia |
| `plugin-sdk/approval-runtime` | Helper prompt persetujuan | Payload persetujuan exec/plugin, helper kapabilitas/profil persetujuan, helper perutean/runtime persetujuan bawaan |
| `plugin-sdk/approval-auth-runtime` | Helper auth persetujuan | Resolusi approver, auth aksi same-chat |
| `plugin-sdk/approval-client-runtime` | Helper klien persetujuan | Helper profil/filter persetujuan exec bawaan |
| `plugin-sdk/approval-delivery-runtime` | Helper pengiriman persetujuan | Adapter kapabilitas/pengiriman persetujuan bawaan |
| `plugin-sdk/approval-native-runtime` | Helper target persetujuan | Helper target persetujuan bawaan/binding akun |
| `plugin-sdk/approval-reply-runtime` | Helper balasan persetujuan | Helper payload balasan persetujuan exec/plugin |
| `plugin-sdk/security-runtime` | Helper keamanan | Helper trust bersama, DM gating, external-content, dan pengumpulan secret |
| `plugin-sdk/ssrf-policy` | Helper kebijakan SSRF | Helper allowlist host dan kebijakan private-network |
| `plugin-sdk/ssrf-runtime` | Helper runtime SSRF | Helper pinned-dispatcher, guarded fetch, kebijakan SSRF |
| `plugin-sdk/config-runtime` | Helper config | Helper load/write config |
| `plugin-sdk/telegram-command-config` | Helper perintah Telegram | Helper validasi perintah Telegram yang stabil terhadap fallback 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/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-native-runtime` | Helper target approval | Helper target approval native/binding akun |
| `plugin-sdk/approval-reply-runtime` | Helper balasan approval | Helper payload balasan approval exec/plugin |
| `plugin-sdk/security-runtime` | Helper keamanan | Helper trust, gating DM, 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/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 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`, policy runner |
| `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 registri perintah |
| `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, perencana balasan, chunking |
| `plugin-sdk/reply-dispatch-runtime` | Helper dispatch balasan sempit | Helper finalize + dispatch provider |
| `plugin-sdk/webhook-request-guards` | Helper guard body webhook | Helper baca/batasi body permintaan |
| `plugin-sdk/reply-runtime` | Runtime balasan bersama | Inbound dispatch, heartbeat, perencana balasan, chunking |
| `plugin-sdk/reply-dispatch-runtime` | Helper dispatch balasan yang sempit | Helper finalize + provider dispatch |
| `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 |
| `plugin-sdk/session-store-runtime` | Helper session store | Helper path store + updated-at |
| `plugin-sdk/session-store-runtime` | Helper penyimpanan sesi | Helper path penyimpanan + updated-at |
| `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 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 bertimer | Runner perintah bertimer dengan stdout/stderr yang dinormalisasi |
| `plugin-sdk/param-readers` | Param reader | Param reader tool/CLI umum |
| `plugin-sdk/tool-send` | Ekstraksi pengiriman tool | Ekstrak field target kirim kanonis dari argumen tool |
| `plugin-sdk/run-command` | Helper perintah berwaktu | Runner perintah berwaktu dengan stdout/stderr ternormalisasi |
| `plugin-sdk/param-readers` | Pembaca param | Pembaca param tool/CLI umum |
| `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/reply-payload` | Tipe balasan pesan | Tipe payload balasan |
| `plugin-sdk/provider-setup` | Helper penyiapan provider lokal/self-hosted yang dikurasi | Helper penemuan/config provider self-hosted |
| `plugin-sdk/self-hosted-provider-setup` | Helper penyiapan provider self-hosted kompatibel OpenAI yang terfokus | Helper penemuan/config provider self-hosted yang sama |
| `plugin-sdk/provider-setup` | Helper setup provider lokal/self-hosted yang dikurasi | Helper penemuan/config provider self-hosted |
| `plugin-sdk/self-hosted-provider-setup` | Helper setup provider self-hosted yang kompatibel dengan OpenAI dan terfokus | Helper penemuan/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 penyiapan API key provider | Helper onboarding/tulis profil API key |
| `plugin-sdk/provider-auth-api-key` | Helper setup API key provider | Helper onboarding/profile-write API key |
| `plugin-sdk/provider-auth-result` | Helper auth-result provider | Builder auth-result OAuth standar |
| `plugin-sdk/provider-auth-login` | Helper login interaktif provider | Helper login interaktif bersama |
| `plugin-sdk/provider-env-vars` | Helper variabel env provider | Helper lookup variabel env auth provider |
| `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-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-catalog-shared` | Helper katalog provider bersama | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `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 pendaftaran/cache provider web-fetch |
| `plugin-sdk/provider-web-search` | Helper web-search provider | Helper pendaftaran/cache/config provider web-search |
| `plugin-sdk/provider-tools` | Helper kompat schema/tool provider | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, pembersihan schema + diagnostik Gemini, dan helper kompat xAI seperti `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-web-fetch` | Helper web-fetch provider | Helper registrasi/cache provider web-fetch |
| `plugin-sdk/provider-web-search` | Helper web-search provider | Helper registrasi/cache/config provider web-search |
| `plugin-sdk/provider-tools` | Helper kompat schema/tool provider | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, pembersihan skema Gemini + diagnostik, dan helper kompat 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/keyed-async-queue` | Antrean async berurutan | `KeyedAsyncQueue` |
| `plugin-sdk/provider-stream` | Helper wrapper stream provider | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipe wrapper stream, dan helper wrapper Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot bersama |
| `plugin-sdk/keyed-async-queue` | Queue 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 pembuatan 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 assistant, 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, registri, dan validasi yang menghadap provider |
| `plugin-sdk/speech-core` | Speech core bersama | Tipe provider speech, registri, direktif, normalisasi |
| `plugin-sdk/text-runtime` | Helper teks bersama | Penghapusan teks yang terlihat oleh asisten, helper render/chunking/table markdown, helper redaksi, helper directive-tag, utilitas safe-text, dan helper teks/logging terkait |
| `plugin-sdk/text-chunking` | Helper chunking teks | Helper chunking teks outbound |
| `plugin-sdk/speech` | Helper speech | Tipe provider speech plus helper directive, registri, dan validasi yang menghadap provider |
| `plugin-sdk/speech-core` | Inti speech bersama | Tipe provider speech, registri, directive, normalisasi |
| `plugin-sdk/realtime-transcription` | Helper transkripsi realtime | Tipe provider dan helper registri |
| `plugin-sdk/realtime-voice` | Helper suara realtime | Tipe provider dan helper registri |
| `plugin-sdk/image-generation-core` | Image-generation core bersama | Tipe image-generation, failover, auth, dan helper registri |
| `plugin-sdk/realtime-voice` | Helper voice realtime | Tipe provider dan helper registri |
| `plugin-sdk/image-generation-core` | Inti image-generation bersama | Helper tipe, failover, auth, dan registri image-generation |
| `plugin-sdk/music-generation` | Helper music-generation | Tipe provider/request/result music-generation |
| `plugin-sdk/music-generation-core` | Music-generation core bersama | Tipe music-generation, helper failover, lookup provider, dan parsing model-ref |
| `plugin-sdk/music-generation-core` | Inti music-generation bersama | Helper tipe, failover, lookup provider, dan parsing model-ref music-generation |
| `plugin-sdk/video-generation` | Helper video-generation | Tipe provider/request/result video-generation |
| `plugin-sdk/video-generation-core` | Video-generation core bersama | Tipe video-generation, helper failover, lookup provider, dan parsing model-ref |
| `plugin-sdk/video-generation-core` | Inti video-generation bersama | Helper tipe, failover, lookup provider, dan parsing model-ref video-generation |
| `plugin-sdk/interactive-runtime` | Helper balasan interaktif | Normalisasi/reduksi payload balasan interaktif |
| `plugin-sdk/channel-config-primitives` | Primitif config channel | Primitif channel config-schema sempit |
| `plugin-sdk/channel-config-primitives` | Primitif config channel | Primitif channel config-schema 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 config allowlist | Helper edit/baca config allowlist |
| `plugin-sdk/group-access` | Helper akses grup | Helper keputusan akses grup bersama |
| `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 |
| `plugin-sdk/webhook-targets` | Helper target webhook | Registri target webhook dan helper pemasangan route |
| `plugin-sdk/extension-shared` | Helper extension bersama | Primitif helper channel pasif/status |
| `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 memory manager/config/file/CLI |
| `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 memory |
| `plugin-sdk/memory-core-engine-runtime` | Fasad runtime engine memory | Fasad runtime indeks/pencarian memory |
| `plugin-sdk/memory-core-host-engine-foundation` | Engine fondasi host memory | Ekspor engine fondasi host memory |
| `plugin-sdk/memory-core-host-engine-foundation` | Engine foundation host memory | Ekspor engine foundation host memory |
| `plugin-sdk/memory-core-host-engine-embeddings` | Engine embedding host memory | Ekspor engine embedding host memory |
| `plugin-sdk/memory-core-host-engine-qmd` | Engine QMD host memory | Ekspor engine QMD host memory |
| `plugin-sdk/memory-core-host-engine-storage` | Engine penyimpanan host memory | Ekspor engine penyimpanan 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 core host memory | Helper runtime core 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/memory-host-search` | Fasad active memory search | 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-lancedb` | Helper memory-lancedb bawaan | Permukaan helper memory-lancedb |
| `plugin-sdk/testing` | Utilitas pengujian | Helper dan mock pengujian |
</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 permukaan SDK lengkap.
Daftar lengkap 200+ entrypoint ada di
`scripts/lib/plugin-sdk-entrypoints.json`.
Daftar tersebut masih mencakup beberapa seam helper plugin bawaan seperti
Daftar itu masih mencakup beberapa seam helper bundled-plugin seperti
`plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`,
`plugin-sdk/zalo-setup`, dan `plugin-sdk/matrix*`. Seam tersebut tetap diekspor untuk
pemeliharaan dan kompatibilitas plugin bawaan, tetapi sengaja
tidak dimasukkan dari tabel migrasi umum dan bukan target yang direkomendasikan untuk
`plugin-sdk/zalo-setup`, dan `plugin-sdk/matrix*`. Semua itu tetap diekspor untuk
pemeliharaan bundled-plugin dan kompatibilitas, 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:
Aturan yang sama berlaku untuk keluarga bundled-helper lainnya seperti:
- helper dukungan 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`
- Matrix: `plugin-sdk/matrix*`
@ -331,38 +339,38 @@ Aturan yang sama berlaku untuk keluarga helper bawaan lainnya seperti:
`plugin-sdk/thread-ownership`, dan `plugin-sdk/voice-call`
`plugin-sdk/github-copilot-token` saat ini mengekspos
permukaan helper token sempit `DEFAULT_COPILOT_API_BASE_URL`,
permukaan helper token yang sempit `DEFAULT_COPILOT_API_BASE_URL`,
`deriveCopilotApiBaseUrlFromToken`, dan `resolveCopilotApiToken`.
Gunakan impor yang paling sempit yang cocok dengan tugasnya. Jika Anda tidak dapat menemukan ekspor,
Gunakan impor paling sempit yang sesuai dengan tugasnya. Jika Anda tidak dapat menemukan ekspor,
periksa sumber di `src/plugin-sdk/` atau tanyakan di Discord.
## Linimasa penghapusan
| Kapan | Apa yang terjadi |
| --- | --- |
| **Sekarang** | Permukaan deprecated mengeluarkan peringatan runtime |
| **Rilis mayor berikutnya** | Permukaan deprecated akan dihapus; plugin yang masih menggunakannya akan gagal |
| Kapan | Apa yang terjadi |
| ---------------------- | ----------------------------------------------------------------------- |
| **Sekarang** | Permukaan deprecated mengeluarkan peringatan runtime |
| **Rilis utama berikutnya** | Permukaan deprecated akan dihapus; plugin yang masih menggunakannya akan gagal |
Semua plugin inti sudah dimigrasikan. Plugin eksternal sebaiknya bermigrasi
sebelum rilis mayor berikutnya.
sebelum rilis utama berikutnya.
## Menyembunyikan peringatan untuk sementara
Setel variabel environment ini saat Anda sedang mengerjakan migrasi:
Setel variabel lingkungan 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 jalan keluar sementara, bukan solusi permanen.
## Terkait
- [Getting Started](/id/plugins/building-plugins) — bangun 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
- [Internal Plugin](/id/plugins/architecture) — pendalaman arsitektur
- [Manifest Plugin](/id/plugins/manifest) — referensi skema manifest
- [Getting Started](/id/plugins/building-plugins) — buat plugin pertama Anda
- [SDK Overview](/id/plugins/sdk-overview) — referensi lengkap impor subpath
- [Channel Plugins](/id/plugins/sdk-channel-plugins) — membangun plugin channel
- [Provider Plugins](/id/plugins/sdk-provider-plugins) — membangun plugin provider
- [Plugin Internals](/id/plugins/architecture) — pendalaman arsitektur
- [Plugin Manifest](/id/plugins/manifest) — referensi skema manifest

438
docs/id/plugins/sdk-overview.md
View File

@ -1,16 +1,16 @@
---
read_when:
- Anda perlu mengetahui subpath SDK mana yang harus diimpor
- Anda perlu mengetahui subpath SDK mana yang harus diimpor dari
- Anda menginginkan referensi untuk semua metode registrasi pada OpenClawPluginApi
- Anda sedang mencari export SDK tertentu
- Anda sedang mencari ekspor SDK tertentu
sidebarTitle: SDK Overview
summary: Referensi peta import, API registrasi, dan arsitektur SDK
summary: Peta impor, referensi API registrasi, dan arsitektur SDK
title: Ikhtisar Plugin SDK
x-i18n:
generated_at: "2026-04-06T03:10:09Z"
generated_at: "2026-04-06T09:14:16Z"
model: gpt-5.4
provider: openai
source_hash: d801641f26f39dc21490d2a69a337ff1affb147141360916b8b58a267e9f822a
source_hash: acd2887ef52c66b2f234858d812bb04197ecd0bfb3e4f7bf3622f8fdc765acad
source_path: plugins/sdk-overview.md
workflow: 15
---
@ -27,7 +27,7 @@ referensi untuk **apa yang harus diimpor** dan **apa yang dapat Anda daftarkan**
- Plugin provider? Lihat [Provider Plugins](/id/plugins/sdk-provider-plugins)
</Tip>
## Konvensi import
## Konvensi impor
Selalu impor dari subpath tertentu:
@ -36,39 +36,38 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
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 entry/build khusus channel,
utamakan `openclaw/plugin-sdk/channel-core`; gunakan `openclaw/plugin-sdk/core` untuk
permukaan umbrella yang lebih luas dan helper bersama seperti
Setiap subpath adalah modul kecil yang mandiri. Ini menjaga startup tetap cepat dan
mencegah masalah circular dependency. Untuk helper entri/build khusus channel,
gunakan `openclaw/plugin-sdk/channel-core`; pertahankan `openclaw/plugin-sdk/core` untuk
permukaan payung yang lebih luas dan helper bersama seperti
`buildChannelConfigSchema`.
Jangan menambahkan atau bergantung pada seam kenyamanan bernama provider seperti
Jangan menambahkan atau bergantung pada seam kemudahan bernama provider seperti
`openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`,
`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, atau
seam helper berlabel channel. Bundled plugin sebaiknya menyusun subpath
SDK generik di dalam barrel `api.ts` atau `runtime-api.ts` miliknya sendiri, dan core
seam helper bermerek channel. Plugin bawaan sebaiknya menyusun subpath
SDK generik di dalam barrel `api.ts` atau `runtime-api.ts` mereka sendiri, dan core
sebaiknya menggunakan barrel lokal plugin tersebut atau menambahkan kontrak SDK generik yang sempit
ketika kebutuhannya benar-benar lintas channel.
Peta export yang dihasilkan masih memuat sejumlah kecil seam helper
bundled-plugin seperti `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`,
Peta ekspor yang dihasilkan masih berisi sekumpulan kecil seam helper
plugin bawaan 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 path import yang
direkomendasikan untuk plugin pihak ketiga yang baru.
tersebut ada hanya untuk pemeliharaan dan kompatibilitas plugin bawaan; sengaja
tidak disertakan dari tabel umum di bawah dan bukan jalur impor yang direkomendasikan untuk plugin pihak ketiga baru.
## Referensi subpath
Subpath yang paling umum digunakan, dikelompokkan berdasarkan tujuan. Daftar lengkap
200+ subpath yang dihasilkan berada di `scripts/lib/plugin-sdk-entrypoints.json`.
Subpath helper bundled-plugin yang dicadangkan masih muncul dalam daftar yang dihasilkan itu.
Perlakukan subpath tersebut sebagai detail implementasi/permukaan kompatibilitas kecuali suatu halaman dokumen
Subpath helper plugin bawaan yang dicadangkan masih muncul dalam daftar yang dihasilkan itu.
Perlakukan itu sebagai detail implementasi/permukaan kompatibilitas kecuali sebuah halaman dokumen
secara eksplisit mempromosikannya sebagai publik.
### Entrypoint plugin
### Entri plugin
| Subpath | Export utama |
| Subpath | Ekspor kunci |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
@ -77,40 +76,40 @@ secara eksplisit mempromosikannya sebagai publik.
<AccordionGroup>
<Accordion title="Subpath channel">
| Subpath | Export utama |
| Subpath | Ekspor kunci |
| --- | --- |
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/config-schema` | Export skema Zod root `openclaw.json` (`OpenClawSchema`) |
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, plus `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
| `plugin-sdk/setup` | Helper wizard setup bersama, prompt allowlist, pembangun status setup |
| `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 setup bersama, prompt allowlist, builder status setup |
| `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 multi-akun config/action-gate, helper fallback akun default |
| `plugin-sdk/account-core` | Helper config/gate tindakan multi-akun, helper fallback akun default |
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, helper normalisasi account-id |
| `plugin-sdk/account-resolution` | Helper lookup akun + fallback default |
| `plugin-sdk/account-helpers` | Helper sempit account-list/account-action |
| `plugin-sdk/account-helpers` | Helper sempit daftar akun/tindakan 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 custom-command Telegram dengan fallback bundled-contract |
| `plugin-sdk/telegram-command-config` | Helper normalisasi/validasi custom command Telegram dengan fallback kontrak bawaan |
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` |
| `plugin-sdk/inbound-envelope` | Helper route inbound + pembangun envelope bersama |
| `plugin-sdk/inbound-reply-dispatch` | Helper bersama untuk pencatatan dan dispatch inbound |
| `plugin-sdk/inbound-envelope` | Helper rute inbound bersama + builder envelope |
| `plugin-sdk/inbound-reply-dispatch` | Helper pencatatan-dan-dispatch inbound bersama |
| `plugin-sdk/messaging-targets` | Helper parsing/pencocokan target |
| `plugin-sdk/outbound-media` | Helper bersama untuk pemuatan media outbound |
| `plugin-sdk/outbound-runtime` | Helper identitas outbound/send delegate |
| `plugin-sdk/thread-bindings-runtime` | Helper siklus hidup dan adapter thread-binding |
| `plugin-sdk/agent-media-payload` | Builder payload media agen lama |
| `plugin-sdk/conversation-runtime` | Helper percakapan/thread binding, pairing, dan configured-binding |
| `plugin-sdk/outbound-media` | Helper pemuatan media outbound bersama |
| `plugin-sdk/outbound-runtime` | Helper identitas outbound/delegasi send |
| `plugin-sdk/thread-bindings-runtime` | Siklus hidup thread-binding dan helper adapter |
| `plugin-sdk/agent-media-payload` | Builder payload media agent lama |
| `plugin-sdk/conversation-runtime` | Binding percakapan/thread, pairing, dan helper binding terkonfigurasi |
| `plugin-sdk/runtime-config-snapshot` | Helper snapshot config runtime |
| `plugin-sdk/runtime-group-policy` | Helper resolusi group-policy 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` | Primitive skema config channel yang sempit |
| `plugin-sdk/channel-config-writes` | Helper otorisasi config-write channel |
| `plugin-sdk/channel-plugin-common` | Export prelude plugin channel bersama |
| `plugin-sdk/channel-config-primitives` | Primitive sempit skema config channel |
| `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/guard direct-DM bersama |
@ -124,205 +123,214 @@ secara eksplisit mempromosikannya sebagai publik.
</Accordion>
<Accordion title="Subpath provider">
| Subpath | Export utama |
| Subpath | Ekspor kunci |
| --- | --- |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
| `plugin-sdk/provider-setup` | Helper setup provider lokal/self-hosted yang telah dikurasi |
| `plugin-sdk/self-hosted-provider-setup` | Helper setup provider self-hosted kompatibel OpenAI yang terfokus |
| `plugin-sdk/provider-auth-runtime` | Helper resolusi API-key runtime untuk plugin provider |
| `plugin-sdk/provider-auth-api-key` | Helper onboarding API-key/penulisan profil |
| `plugin-sdk/provider-auth-result` | Builder hasil auth OAuth standar |
| `plugin-sdk/provider-setup` | Helper setup provider lokal/self-hosted yang terkurasi |
| `plugin-sdk/self-hosted-provider-setup` | Helper setup provider self-hosted yang fokus pada kompatibilitas OpenAI |
| `plugin-sdk/provider-auth-runtime` | Helper resolusi API key runtime untuk plugin provider |
| `plugin-sdk/provider-auth-api-key` | Helper onboarding API key/penulisan profil |
| `plugin-sdk/provider-auth-result` | Builder auth-result OAuth standar |
| `plugin-sdk/provider-auth-login` | Helper login interaktif bersama untuk plugin provider |
| `plugin-sdk/provider-env-vars` | Helper lookup env-var auth provider |
| `plugin-sdk/provider-env-vars` | Helper lookup env var auth provider |
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile` |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, builder replay-policy bersama, helper endpoint provider, dan helper normalisasi model-id seperti `normalizeNativeXaiModelId` |
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-http` | Helper HTTP provider/kapabilitas endpoint generik |
| `plugin-sdk/provider-http` | Helper kemampuan HTTP/endpoint provider generik |
| `plugin-sdk/provider-web-fetch` | Helper registrasi/cache provider web-fetch |
| `plugin-sdk/provider-web-search` | Helper registrasi/cache/config provider 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 stream wrapper, dan helper wrapper bersama Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
| `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/global-singleton` | Helper singleton/map/cache lokal proses |
| `plugin-sdk/global-singleton` | Helper singleton/map/cache lokal-proses |
</Accordion>
<Accordion title="Subpath auth dan keamanan">
| Subpath | Export utama |
| Subpath | Ekspor kunci |
| --- | --- |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`, helper registry command, helper otorisasi pengirim |
| `plugin-sdk/approval-auth-runtime` | Resolusi approver dan helper action-auth same-chat |
| `plugin-sdk/approval-client-runtime` | Helper profil/filter persetujuan eksekusi native |
| `plugin-sdk/approval-delivery-runtime` | Adapter kapabilitas/pengiriman persetujuan native |
| `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` | Auth command native + helper session-target native |
| `plugin-sdk/approval-auth-runtime` | Resolusi approver dan helper action-auth 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-native-runtime` | Helper target approval native + account-binding |
| `plugin-sdk/approval-reply-runtime` | Helper payload balasan approval exec/plugin |
| `plugin-sdk/command-auth-native` | Auth command native + helper target sesi native |
| `plugin-sdk/command-detection` | Helper deteksi command bersama |
| `plugin-sdk/command-surface` | Normalisasi isi command dan helper permukaan command |
| `plugin-sdk/command-surface` | Helper normalisasi isi command dan permukaan command |
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
| `plugin-sdk/security-runtime` | Helper trust, DM gating, external-content, dan pengumpulan secret bersama |
| `plugin-sdk/security-runtime` | Helper trust, DM gating, konten eksternal, dan pengumpulan secret bersama |
| `plugin-sdk/ssrf-policy` | Helper allowlist host dan kebijakan SSRF jaringan privat |
| `plugin-sdk/ssrf-runtime` | Pinned-dispatcher, fetch dengan penjagaan SSRF, dan helper kebijakan SSRF |
| `plugin-sdk/ssrf-runtime` | Helper pinned-dispatcher, fetch yang dijaga SSRF, dan kebijakan SSRF |
| `plugin-sdk/secret-input` | Helper parsing input secret |
| `plugin-sdk/webhook-ingress` | Helper request/target webhook |
| `plugin-sdk/webhook-request-guards` | Helper ukuran body request/timeout |
| `plugin-sdk/webhook-request-guards` | Helper ukuran body/timeout request |
</Accordion>
<Accordion title="Subpath runtime dan storage">
| Subpath | Export utama |
<Accordion title="Subpath runtime dan penyimpanan">
| Subpath | Ekspor kunci |
| --- | --- |
| `plugin-sdk/runtime` | Helper runtime/logging/backup/instalasi plugin yang luas |
| `plugin-sdk/runtime-env` | Helper sempit untuk env runtime, logger, timeout, retry, dan backoff |
| `plugin-sdk/runtime-env` | Helper sempit env runtime, logger, timeout, retry, dan backoff |
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
| `plugin-sdk/plugin-runtime` | Helper bersama untuk command/hook/http/interaktif plugin |
| `plugin-sdk/hook-runtime` | Helper pipeline webhook/internal hook bersama |
| `plugin-sdk/lazy-runtime` | Helper import/binding runtime lazy seperti `createLazyRuntimeModule`, `createLazyRuntimeMethod`, dan `createLazyRuntimeSurface` |
| `plugin-sdk/plugin-runtime` | Helper command/hook/http/interaktif plugin bersama |
| `plugin-sdk/hook-runtime` | Helper pipeline hook webhook/internal bersama |
| `plugin-sdk/lazy-runtime` | Helper impor/binding runtime lazy seperti `createLazyRuntimeModule`, `createLazyRuntimeMethod`, dan `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | Helper exec proses |
| `plugin-sdk/cli-runtime` | Helper pemformatan CLI, wait, dan versi |
| `plugin-sdk/gateway-runtime` | Helper klien Gateway dan patch status channel |
| `plugin-sdk/config-runtime` | Helper load/write config |
| `plugin-sdk/telegram-command-config` | Normalisasi nama/deskripsi command Telegram dan pemeriksaan duplikat/konflik, bahkan ketika permukaan kontrak Telegram bawaan tidak tersedia |
| `plugin-sdk/approval-runtime` | Helper persetujuan exec/plugin, pembangun kapabilitas persetujuan, helper auth/profil, helper routing/runtime native |
| `plugin-sdk/reply-runtime` | Helper runtime inbound/reply bersama, chunking, dispatch, heartbeat, perencana balasan |
| `plugin-sdk/cli-runtime` | Helper format CLI, wait, dan versi |
| `plugin-sdk/gateway-runtime` | Helper klien gateway dan patch status channel |
| `plugin-sdk/config-runtime` | Helper muat/tulis config |
| `plugin-sdk/telegram-command-config` | Normalisasi nama/deskripsi command Telegram dan pemeriksaan duplikat/konflik, bahkan saat permukaan kontrak Telegram bawaan tidak tersedia |
| `plugin-sdk/approval-runtime` | Helper approval exec/plugin, builder kemampuan approval, 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 dispatch/finalisasi balasan |
| `plugin-sdk/reply-history` | Helper bersama riwayat balasan jendela pendek seperti `buildHistoryContext`, `recordPendingHistoryEntry`, dan `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-history` | Helper reply-history jendela pendek bersama seperti `buildHistoryContext`, `recordPendingHistoryEntry`, dan `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
| `plugin-sdk/reply-chunking` | Helper sempit chunking teks/markdown |
| `plugin-sdk/session-store-runtime` | Helper path penyimpanan sesi + 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 bersama ringkasan status channel/akun, default status runtime, dan helper metadata issue |
| `plugin-sdk/target-resolver-runtime` | Helper target resolver bersama |
| `plugin-sdk/session-store-runtime` | Helper jalur session store + updated-at |
| `plugin-sdk/state-paths` | Helper jalur direktori state/OAuth |
| `plugin-sdk/routing` | Helper binding rute/session-key/akun 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 resolver target bersama |
| `plugin-sdk/string-normalization-runtime` | Helper normalisasi slug/string |
| `plugin-sdk/request-url` | Mengekstrak URL string dari input mirip fetch/request |
| `plugin-sdk/run-command` | Runner command bertimer dengan hasil stdout/stderr ternormalisasi |
| `plugin-sdk/param-readers` | Pembaca parameter tool/CLI umum |
| `plugin-sdk/tool-send` | Mengekstrak field target send kanonis dari argumen tool |
| `plugin-sdk/temp-path` | Helper path unduhan sementara bersama |
| `plugin-sdk/request-url` | Ekstrak URL string dari input mirip fetch/request |
| `plugin-sdk/run-command` | Runner command bertimer dengan hasil stdout/stderr yang ternormalisasi |
| `plugin-sdk/param-readers` | Pembaca param tool/CLI umum |
| `plugin-sdk/tool-send` | Ekstrak field target send kanonis dari argumen tool |
| `plugin-sdk/temp-path` | Helper jalur unduhan sementara bersama |
| `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 baca/tulis state JSON kecil |
| `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/agent-config-primitives` | Primitive skema config runtime agen yang sempit |
| `plugin-sdk/boolean-param` | Pembaca parameter boolean longgar |
| `plugin-sdk/agent-config-primitives` | Primitive sempit skema config runtime agent |
| `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` | Primitive helper channel pasif dan status bersama |
| `plugin-sdk/models-provider-runtime` | Helper balasan command/provider `/models` |
| `plugin-sdk/skill-commands-runtime` | Helper daftar command skill |
| `plugin-sdk/skill-commands-runtime` | Helper daftar skill command |
| `plugin-sdk/native-command-registry` | Helper registry/build/serialize command native |
| `plugin-sdk/provider-zai-endpoint` | Helper deteksi endpoint Z.A.I |
| `plugin-sdk/infra-runtime` | Helper system event/heartbeat |
| `plugin-sdk/collection-runtime` | Helper cache kecil berbatas |
| `plugin-sdk/infra-runtime` | Helper event sistem/heartbeat |
| `plugin-sdk/collection-runtime` | Helper cache terikat kecil |
| `plugin-sdk/diagnostic-runtime` | Helper flag dan event diagnostik |
| `plugin-sdk/error-runtime` | Helper graph error, pemformatan, klasifikasi error bersama, `isApprovalNotFoundError` |
| `plugin-sdk/error-runtime` | Grafik error, pemformatan, helper klasifikasi error bersama, `isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | Helper fetch terbungkus, proxy, dan pinned lookup |
| `plugin-sdk/host-runtime` | Helper normalisasi hostname dan host SCP |
| `plugin-sdk/retry-runtime` | Helper config retry dan runner retry |
| `plugin-sdk/agent-runtime` | Helper dir/identitas/workspace agen |
| `plugin-sdk/retry-runtime` | Helper konfigurasi retry dan runner retry |
| `plugin-sdk/agent-runtime` | Helper direktori/identitas/workspace agent |
| `plugin-sdk/directory-runtime` | Query/dedup direktori berbasis config |
| `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
</Accordion>
<Accordion title="Subpath kapabilitas dan pengujian">
| Subpath | Export utama |
<Accordion title="Subpath kemampuan dan pengujian">
| Subpath | Ekspor kunci |
| --- | --- |
| `plugin-sdk/media-runtime` | Helper bersama untuk fetch/transform/store media plus pembangun payload media |
| `plugin-sdk/media-understanding` | Tipe provider media understanding plus export helper gambar/audio untuk provider |
| `plugin-sdk/text-runtime` | Helper bersama teks/markdown/logging seperti penghapusan teks yang terlihat oleh assistant, helper render/chunking/table markdown, helper redaksi, helper directive-tag, dan utilitas teks aman |
| `plugin-sdk/media-runtime` | Helper fetch/transform/store media bersama ditambah builder payload media |
| `plugin-sdk/media-generation-runtime` | Helper failover pembuatan media bersama, pemilihan kandidat, dan pesan model yang hilang |
| `plugin-sdk/media-understanding` | Tipe provider pemahaman media ditambah ekspor helper gambar/audio yang menghadap 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 outbound |
| `plugin-sdk/speech` | Tipe provider speech plus helper directive, registry, dan validasi untuk provider |
| `plugin-sdk/speech` | Tipe provider speech ditambah helper directive, registry, dan validasi yang menghadap provider |
| `plugin-sdk/speech-core` | Tipe provider speech bersama, helper registry, directive, dan 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 request/result/provider music generation |
| `plugin-sdk/music-generation-core` | Tipe music-generation bersama, helper failover, lookup provider, dan parsing model-ref |
| `plugin-sdk/video-generation` | Tipe request/result/provider video generation |
| `plugin-sdk/video-generation-core` | Tipe video-generation bersama, helper failover, lookup provider, dan parsing model-ref |
| `plugin-sdk/webhook-targets` | Registry target webhook dan helper instalasi route |
| `plugin-sdk/webhook-path` | Helper normalisasi path webhook |
| `plugin-sdk/web-media` | Helper bersama pemuatan media remote/lokal |
| `plugin-sdk/zod` | `zod` yang di-re-export untuk konsumen plugin SDK |
| `plugin-sdk/realtime-transcription` | Tipe provider transkripsi realtime dan helper registry |
| `plugin-sdk/realtime-voice` | Tipe provider suara realtime dan helper registry |
| `plugin-sdk/image-generation` | Tipe provider pembuatan gambar |
| `plugin-sdk/image-generation-core` | Tipe pembuatan gambar bersama, helper failover, auth, dan registry |
| `plugin-sdk/music-generation` | Tipe provider/request/result pembuatan musik |
| `plugin-sdk/music-generation-core` | Tipe pembuatan musik bersama, helper failover, lookup provider, dan parsing model-ref |
| `plugin-sdk/video-generation` | Tipe provider/request/result pembuatan video |
| `plugin-sdk/video-generation-core` | Tipe pembuatan video bersama, helper failover, lookup provider, dan parsing model-ref |
| `plugin-sdk/webhook-targets` | Helper registry target webhook dan instalasi rute |
| `plugin-sdk/webhook-path` | Helper normalisasi jalur webhook |
| `plugin-sdk/web-media` | Helper pemuatan media remote/lokal bersama |
| `plugin-sdk/zod` | `zod` yang diekspor ulang untuk konsumen plugin SDK |
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` |
</Accordion>
<Accordion title="Subpath memory">
| Subpath | Export utama |
| Subpath | Ekspor kunci |
| --- | --- |
| `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` | Export engine fondasi host memory |
| `plugin-sdk/memory-core-host-engine-embeddings` | Export engine embedding host memory |
| `plugin-sdk/memory-core-host-engine-qmd` | Export engine QMD host memory |
| `plugin-sdk/memory-core-host-engine-storage` | Export engine storage host memory |
| `plugin-sdk/memory-core-host-engine-foundation` | Ekspor engine foundation host memory |
| `plugin-sdk/memory-core-host-engine-embeddings` | Ekspor engine embedding host memory |
| `plugin-sdk/memory-core-host-engine-qmd` | Ekspor engine QMD host memory |
| `plugin-sdk/memory-core-host-engine-storage` | Ekspor engine penyimpanan host memory |
| `plugin-sdk/memory-core-host-multimodal` | Helper multimodal host memory |
| `plugin-sdk/memory-core-host-query` | Helper query 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 inti 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-host-search` | Fasad runtime memory aktif untuk akses search-manager |
| `plugin-sdk/memory-host-status` | Alias netral-vendor untuk helper status host memory |
| `plugin-sdk/memory-lancedb` | Permukaan helper memory-lancedb bawaan |
</Accordion>
<Accordion title="Subpath helper bundled 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 helper/kompatibilitas channel bawaan |
| Helper auth/plugin-spesifik | `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 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` |
</Accordion>
</AccordionGroup>
## API registrasi
Callback `register(api)` menerima objek `OpenClawPluginApi` dengan metode-metode
berikut:
Callback `register(api)` menerima objek `OpenClawPluginApi` dengan metode berikut:
### Registrasi kapabilitas
### Registrasi kemampuan
| Metode | Yang didaftarkan |
| ------------------------------------------------ | ------------------------------- |
| `api.registerProvider(...)` | Inferensi teks (LLM) |
| `api.registerChannel(...)` | Channel perpesanan |
| `api.registerSpeechProvider(...)` | Sintesis text-to-speech / STT |
| `api.registerRealtimeTranscriptionProvider(...)` | Streaming realtime transcription |
| `api.registerRealtimeVoiceProvider(...)` | Sesi suara realtime duplex |
| `api.registerMediaUnderstandingProvider(...)` | Analisis gambar/audio/video |
| `api.registerImageGenerationProvider(...)` | Image generation |
| `api.registerMusicGenerationProvider(...)` | Music generation |
| `api.registerVideoGenerationProvider(...)` | Video generation |
| `api.registerWebFetchProvider(...)` | Provider web fetch / scrape |
| `api.registerWebSearchProvider(...)` | Pencarian web |
| Method | Yang didaftarkan |
| ------------------------------------------------ | -------------------------------- |
| `api.registerProvider(...)` | Inferensi teks (LLM) |
| `api.registerChannel(...)` | Channel pesan |
| `api.registerSpeechProvider(...)` | Text-to-speech / sintesis STT |
| `api.registerRealtimeTranscriptionProvider(...)` | Transkripsi realtime streaming |
| `api.registerRealtimeVoiceProvider(...)` | Sesi suara realtime dupleks |
| `api.registerMediaUnderstandingProvider(...)` | Analisis gambar/audio/video |
| `api.registerImageGenerationProvider(...)` | Pembuatan gambar |
| `api.registerMusicGenerationProvider(...)` | Pembuatan musik |
| `api.registerVideoGenerationProvider(...)` | Pembuatan video |
| `api.registerWebFetchProvider(...)` | Provider fetch / scrape web |
| `api.registerWebSearchProvider(...)` | Pencarian web |
### Tool dan command
| Metode | Yang didaftarkan |
| Method | Yang didaftarkan |
| ------------------------------- | ----------------------------------------------- |
| `api.registerTool(tool, opts?)` | Tool agen (wajib atau `{ optional: true }`) |
| `api.registerCommand(def)` | Command kustom (melewati LLM) |
| `api.registerTool(tool, opts?)` | Tool agent (wajib atau `{ optional: true }`) |
| `api.registerCommand(def)` | Custom command (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?)` | Subcommand CLI |
| `api.registerService(service)` | Layanan latar belakang |
| `api.registerInteractiveHandler(registration)` | Handler interaktif |
| 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?)` | Subcommand 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)` | Corpus pencarian/baca memory aditif |
Namespace admin core yang dicadangkan (`config.*`, `exec.approvals.*`, `wizard.*`,
`update.*`) selalu tetap `operator.admin`, meskipun plugin mencoba menetapkan
cakupan metode gateway yang lebih sempit. Utamakan prefiks khusus plugin untuk
`update.*`) selalu tetap `operator.admin`, bahkan jika plugin mencoba menetapkan
cakupan metode gateway yang lebih sempit. Gunakan prefiks khusus plugin untuk
metode yang dimiliki plugin.
### Metadata registrasi CLI
@ -330,8 +338,8 @@ metode yang dimiliki plugin.
`api.registerCli(registrar, opts?)` menerima dua jenis metadata tingkat atas:
- `commands`: root command eksplisit yang dimiliki registrar
- `descriptors`: descriptor command pada waktu parse yang digunakan untuk help CLI root,
routing, dan registrasi CLI plugin secara lazy
- `descriptors`: descriptor command saat parse yang digunakan untuk bantuan CLI root,
routing, dan registrasi CLI plugin lazy
Jika Anda ingin command plugin tetap dimuat secara lazy di jalur CLI root normal,
sediakan `descriptors` yang mencakup setiap root command tingkat atas yang diekspos oleh
@ -347,7 +355,7 @@ api.registerCli(
descriptors: [
{
name: "matrix",
description: "Kelola akun Matrix, verifikasi, perangkat, dan state profil",
description: "Kelola akun Matrix, verifikasi, perangkat, dan status profil",
hasSubcommands: true,
},
],
@ -356,114 +364,116 @@ api.registerCli(
```
Gunakan `commands` saja hanya ketika Anda tidak memerlukan registrasi CLI root yang lazy.
Jalur kompatibilitas eager tersebut tetap didukung, tetapi jalur itu tidak memasang
placeholder berbasis descriptor untuk pemuatan lazy saat parse-time.
Jalur kompatibilitas eager tersebut tetap didukung, tetapi tidak memasang
placeholder yang didukung descriptor untuk lazy loading saat parse-time.
### Slot eksklusif
| Metode | Yang didaftarkan |
| ------------------------------------------ | ------------------------------------ |
| `api.registerContextEngine(id, factory)` | Engine konteks (hanya satu yang aktif pada satu waktu) |
| `api.registerMemoryPromptSection(builder)` | Builder bagian prompt memory |
| `api.registerMemoryFlushPlan(resolver)` | Resolver rencana flush memory |
| `api.registerMemoryRuntime(runtime)` | Adapter runtime memory |
| Method | Yang didaftarkan |
| ------------------------------------------ | ------------------------------------- |
| `api.registerContextEngine(id, factory)` | Engine konteks (satu aktif pada satu waktu) |
| `api.registerMemoryPromptSection(builder)` | Builder bagian prompt memory |
| `api.registerMemoryFlushPlan(resolver)` | Resolver rencana flush memory |
| `api.registerMemoryRuntime(runtime)` | Adapter runtime memory |
### Adapter embedding memory
| Metode | Yang didaftarkan |
| ---------------------------------------------- | ---------------------------------------------------- |
| `api.registerMemoryEmbeddingProvider(adapter)` | Adapter embedding memory untuk plugin aktif |
| Method | Yang didaftarkan |
| ---------------------------------------------- | ---------------------------------------------- |
| `api.registerMemoryEmbeddingProvider(adapter)` | Adapter embedding memory untuk plugin aktif |
- `registerMemoryPromptSection`, `registerMemoryFlushPlan`, dan
`registerMemoryRuntime` bersifat eksklusif untuk plugin memory.
- `registerMemoryEmbeddingProvider` memungkinkan plugin memory yang aktif mendaftarkan satu
atau lebih id adapter embedding (misalnya `openai`, `gemini`, atau id kustom yang didefinisikan plugin).
- `registerMemoryEmbeddingProvider` memungkinkan plugin memory aktif mendaftarkan satu
atau lebih id adapter embedding (misalnya `openai`, `gemini`, atau id kustom
yang ditentukan plugin).
- Config pengguna seperti `agents.defaults.memorySearch.provider` dan
`agents.defaults.memorySearch.fallback` diresolusikan terhadap id adapter terdaftar tersebut.
`agents.defaults.memorySearch.fallback` diselesaikan terhadap id adapter
terdaftar tersebut.
### Event dan siklus hidup
| Metode | Fungsinya |
| -------------------------------------------- | ----------------------------- |
| `api.on(hookName, handler, opts?)` | Hook siklus hidup bertipe |
| `api.onConversationBindingResolved(handler)` | Callback conversation binding |
| 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 prioritas lebih rendah dilewati.
- `before_tool_call`: mengembalikan `{ block: false }` diperlakukan sebagai tidak ada keputusan (sama seperti tidak menyertakan `block`), bukan sebagai override.
- `before_install`: mengembalikan `{ block: true }` bersifat terminal. Setelah ada handler yang menetapkannya, handler prioritas lebih rendah dilewati.
- `before_install`: mengembalikan `{ block: false }` diperlakukan sebagai tidak ada keputusan (sama seperti tidak menyertakan `block`), bukan sebagai override.
- `reply_dispatch`: mengembalikan `{ handled: true, ... }` bersifat terminal. Setelah ada handler yang mengklaim dispatch, handler prioritas lebih rendah dan jalur dispatch model default akan dilewati.
- `message_sending`: mengembalikan `{ cancel: true }` bersifat terminal. Setelah ada handler yang menetapkannya, handler prioritas lebih rendah dilewati.
- `message_sending`: mengembalikan `{ cancel: false }` diperlakukan sebagai tidak ada keputusan (sama seperti tidak menyertakan `cancel`), bukan sebagai override.
- `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_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.
- `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.
### Field objek API
| Field | Tipe | Deskripsi |
| Field | Type | Deskripsi |
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
| `api.id` | `string` | ID plugin |
| `api.name` | `string` | Nama tampilan |
| `api.version` | `string?` | Versi plugin (opsional) |
| `api.description` | `string?` | Deskripsi plugin (opsional) |
| `api.source` | `string` | Path sumber plugin |
| `api.rootDir` | `string?` | Direktori root plugin (opsional) |
| `api.config` | `OpenClawConfig` | Snapshot config saat ini (snapshot runtime in-memory aktif bila tersedia) |
| `api.pluginConfig` | `Record<string, unknown>` | Config khusus plugin dari `plugins.entries.<id>.config` |
| `api.runtime` | `PluginRuntime` | [Helper runtime](/id/plugins/sdk-runtime) |
| `api.logger` | `PluginLogger` | Logger terlingkup (`debug`, `info`, `warn`, `error`) |
| `api.registrationMode` | `PluginRegistrationMode` | Mode load saat ini; `"setup-runtime"` adalah jendela startup/setup ringan sebelum full-entry |
| `api.resolvePath(input)` | `(string) => string` | Menyelesaikan path relatif terhadap root 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` | Jalur sumber plugin |
| `api.rootDir` | `string?` | Direktori root plugin (opsional) |
| `api.config` | `OpenClawConfig` | Snapshot config saat ini (snapshot runtime in-memory aktif bila tersedia) |
| `api.pluginConfig` | `Record<string, unknown>` | Config khusus plugin dari `plugins.entries.<id>.config` |
| `api.runtime` | `PluginRuntime` | [Helper runtime](/id/plugins/sdk-runtime) |
| `api.logger` | `PluginLogger` | Logger berlingkup (`debug`, `info`, `warn`, `error`) |
| `api.registrationMode` | `PluginRegistrationMode` | Mode muat saat ini; `"setup-runtime"` adalah jendela startup/setup ringan sebelum entri penuh |
| `api.resolvePath(input)` | `(string) => string` | Selesaikan jalur relatif terhadap root plugin |
## Konvensi modul internal
Di dalam plugin Anda, gunakan file barrel lokal untuk import internal:
Di dalam plugin Anda, gunakan file barrel lokal untuk impor internal:
```
my-plugin/
api.ts # Export publik untuk konsumen eksternal
runtime-api.ts # Export runtime hanya internal
index.ts # Entrypoint plugin
setup-entry.ts # Entrypoint ringan khusus setup (opsional)
api.ts # Ekspor publik untuk konsumen eksternal
runtime-api.ts # Ekspor runtime khusus internal
index.ts # Titik masuk plugin
setup-entry.ts # Entri setup ringan saja (opsional)
```
<Warning>
Jangan pernah mengimpor plugin Anda sendiri melalui `openclaw/plugin-sdk/<your-plugin>`
dari kode production. Rutekan import internal 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 bundled plugin yang dimuat melalui fasad (`api.ts`, `runtime-api.ts`,
`index.ts`, `setup-entry.ts`, dan file entry publik serupa) kini mengutamakan
snapshot config runtime aktif ketika OpenClaw sudah berjalan. Jika belum ada snapshot
runtime, sistem akan fallback ke file config terselesaikan di disk.
Permukaan publik plugin bawaan yang dimuat melalui facade (`api.ts`, `runtime-api.ts`,
`index.ts`, `setup-entry.ts`, dan file entri publik serupa) sekarang lebih mengutamakan
snapshot config runtime aktif saat OpenClaw sudah berjalan. Jika belum ada runtime
snapshot, mereka akan fallback ke file config yang diselesaikan di disk.
Plugin provider juga dapat mengekspos barrel kontrak lokal plugin yang sempit ketika
sebuah helper memang khusus provider dan belum layak ditempatkan di subpath SDK generik.
Contoh bundled saat ini: provider Anthropic menyimpan helper stream Claude
Plugin provider juga dapat mengekspos barrel kontrak lokal plugin yang sempit saat sebuah
helper memang khusus provider dan belum pantas berada dalam subpath SDK generik.
Contoh bawaan saat ini: provider 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
mempromosikan logic beta-header Anthropic dan `service_tier` ke kontrak
`plugin-sdk/*` generik.
Contoh bundled lainnya saat ini:
Contoh bawaan saat ini lainnya:
- `@openclaw/openai-provider`: `api.ts` mengekspor builder provider,
helper model default, dan builder provider realtime
- `@openclaw/openrouter-provider`: `api.ts` mengekspor builder provider plus
- `@openclaw/openrouter-provider`: `api.ts` mengekspor builder provider ditambah
helper onboarding/config
<Warning>
Kode production extension juga sebaiknya menghindari import `openclaw/plugin-sdk/<other-plugin>`.
Jika suatu helper memang benar-benar dibagikan, promosikan helper itu ke subpath SDK netral
Kode produksi extension juga sebaiknya menghindari impor `openclaw/plugin-sdk/<other-plugin>`.
Jika sebuah helper benar-benar digunakan bersama, promosikan ke subpath SDK netral
seperti `openclaw/plugin-sdk/speech`, `.../provider-model-shared`, atau permukaan
berorientasi kapabilitas lainnya alih-alih menggabungkan dua plugin secara erat.
berorientasi kemampuan lainnya alih-alih mengikat dua plugin bersama.
</Warning>
## Terkait
- [Entry Points](/id/plugins/sdk-entrypoints) — opsi `definePluginEntry` dan `defineChannelPluginEntry`
- [Runtime Helpers](/id/plugins/sdk-runtime) — referensi penuh namespace `api.runtime`
- [Runtime Helpers](/id/plugins/sdk-runtime) — referensi namespace `api.runtime` lengkap
- [Setup and Config](/id/plugins/sdk-setup) — packaging, manifest, skema config
- [Testing](/id/plugins/sdk-testing) — utilitas pengujian dan aturan lint
- [SDK Migration](/id/plugins/sdk-migration) — migrasi dari permukaan yang sudah deprecated
- [Plugin Internals](/id/plugins/architecture) — arsitektur mendalam dan model kapabilitas
- [SDK Migration](/id/plugins/sdk-migration) — migrasi dari permukaan yang sudah usang
- [Plugin Internals](/id/plugins/architecture) — arsitektur mendalam dan model kemampuan

122
docs/id/tools/image-generation.md
View File

@ -1,31 +1,31 @@
---
read_when:
- Membuat gambar melalui agen
- Mengonfigurasi provider dan model pembuatan gambar
- Memahami parameter tool `image_generate`
summary: Buat dan edit gambar menggunakan provider yang dikonfigurasi (OpenAI, Google Gemini, fal, MiniMax, ComfyUI, Vydra)
- Mengonfigurasi penyedia dan model pembuatan gambar
- Memahami parameter tool image_generate
summary: Buat dan edit gambar menggunakan penyedia yang dikonfigurasi (OpenAI, Google Gemini, fal, MiniMax, ComfyUI, Vydra)
title: Pembuatan Gambar
x-i18n:
generated_at: "2026-04-06T03:11:55Z"
generated_at: "2026-04-06T09:13:18Z"
model: gpt-5.4
provider: openai
source_hash: dde416dd1441a06605db85b5813cf61ccfc525813d6db430b7b7dfa53d6a3134
source_hash: 903cc522c283a8da2cbd449ae3e25f349a74d00ecfdaf0f323fd8aa3f2107aea
source_path: tools/image-generation.md
workflow: 15
---
# Pembuatan Gambar
Tool `image_generate` memungkinkan agen membuat dan mengedit gambar menggunakan provider yang Anda konfigurasi. Gambar yang dihasilkan dikirimkan secara otomatis sebagai lampiran media dalam balasan agen.
Tool `image_generate` memungkinkan agen membuat dan mengedit gambar menggunakan penyedia yang telah Anda konfigurasi. Gambar yang dibuat akan dikirim secara otomatis sebagai lampiran media dalam balasan agen.
<Note>
Tool ini hanya muncul ketika setidaknya satu provider pembuatan gambar tersedia. Jika Anda tidak melihat `image_generate` dalam tool agen Anda, konfigurasikan `agents.defaults.imageGenerationModel` atau siapkan API key provider.
Tool ini hanya muncul ketika setidaknya satu penyedia pembuatan gambar tersedia. Jika Anda tidak melihat `image_generate` dalam tools agen Anda, konfigurasikan `agents.defaults.imageGenerationModel` atau siapkan kunci API penyedia.
</Note>
## Memulai cepat
## Mulai cepat
1. Tetapkan API key untuk setidaknya satu provider (misalnya `OPENAI_API_KEY` atau `GEMINI_API_KEY`).
2. Secara opsional tetapkan model pilihan Anda:
1. Tetapkan kunci API untuk setidaknya satu penyedia (misalnya `OPENAI_API_KEY` atau `GEMINI_API_KEY`).
2. Secara opsional, tetapkan model pilihan Anda:
```json5
{
@ -39,22 +39,22 @@ Tool ini hanya muncul ketika setidaknya satu provider pembuatan gambar tersedia.
}
```
3. Minta agen: _"Generate an image of a friendly lobster mascot."_
3. Minta agen: _"Buat gambar maskot lobster yang ramah."_
Agen memanggil `image_generate` secara otomatis. Tidak perlu allow-listing tool — tool ini diaktifkan secara default saat provider tersedia.
Agen memanggil `image_generate` secara otomatis. Tidak perlu allow-list tool — tool ini diaktifkan secara default saat penyedia tersedia.
## Provider yang didukung
## Penyedia yang didukung
| Provider | Model default | Dukungan edit | API key |
| -------- | -------------------------------- | ---------------------------------- | ----------------------------------------------------- |
| OpenAI | `gpt-image-1` | Ya (hingga 5 gambar) | `OPENAI_API_KEY` |
| Google | `gemini-3.1-flash-image-preview` | Ya | `GEMINI_API_KEY` atau `GOOGLE_API_KEY` |
| fal | `fal-ai/flux/dev` | Ya | `FAL_KEY` |
| MiniMax | `image-01` | Ya (referensi subjek) | `MINIMAX_API_KEY` atau OAuth MiniMax (`minimax-portal`) |
| ComfyUI | `workflow` | Ya (1 gambar, dikonfigurasi workflow) | `COMFY_API_KEY` atau `COMFY_CLOUD_API_KEY` untuk cloud |
| Vydra | `grok-imagine` | Tidak | `VYDRA_API_KEY` |
| Penyedia | Model default | Dukungan edit | Kunci API |
| -------- | -------------------------------- | ----------------------------------- | ------------------------------------------------------- |
| OpenAI | `gpt-image-1` | Ya (hingga 5 gambar) | `OPENAI_API_KEY` |
| Google | `gemini-3.1-flash-image-preview` | Ya | `GEMINI_API_KEY` atau `GOOGLE_API_KEY` |
| fal | `fal-ai/flux/dev` | Ya | `FAL_KEY` |
| MiniMax | `image-01` | Ya (referensi subjek) | `MINIMAX_API_KEY` atau OAuth MiniMax (`minimax-portal`) |
| ComfyUI | `workflow` | Ya (1 gambar, dikonfigurasi alur kerja) | `COMFY_API_KEY` atau `COMFY_CLOUD_API_KEY` untuk cloud |
| Vydra | `grok-imagine` | Tidak | `VYDRA_API_KEY` |
Gunakan `action: "list"` untuk memeriksa provider dan model yang tersedia saat runtime:
Gunakan `action: "list"` untuk memeriksa penyedia dan model yang tersedia saat runtime:
```
/tool image_generate action=list
@ -62,20 +62,20 @@ Gunakan `action: "list"` untuk memeriksa provider dan model yang tersedia saat r
## Parameter tool
| Parameter | Tipe | Deskripsi |
| ------------- | -------- | -------------------------------------------------------------------------------------- |
| `prompt` | string | Prompt pembuatan gambar (wajib untuk `action: "generate"`) |
| `action` | string | `"generate"` (default) atau `"list"` untuk memeriksa provider |
| `model` | string | Override provider/model, misalnya `openai/gpt-image-1` |
| `image` | string | Path atau URL gambar referensi tunggal untuk mode edit |
| `images` | string[] | Beberapa gambar referensi untuk mode edit (hingga 5) |
| `size` | string | Petunjuk ukuran: `1024x1024`, `1536x1024`, `1024x1536`, `1024x1792`, `1792x1024` |
| Parameter | Tipe | Deskripsi |
| ------------- | -------- | ------------------------------------------------------------------------------------ |
| `prompt` | string | Prompt pembuatan gambar (wajib untuk `action: "generate"`) |
| `action` | string | `"generate"` (default) atau `"list"` untuk memeriksa penyedia |
| `model` | string | Override penyedia/model, misalnya `openai/gpt-image-1` |
| `image` | string | Path atau URL satu gambar referensi untuk mode edit |
| `images` | string[] | Beberapa gambar referensi untuk mode edit (hingga 5) |
| `size` | string | Petunjuk ukuran: `1024x1024`, `1536x1024`, `1024x1536`, `1024x1792`, `1792x1024` |
| `aspectRatio` | string | Rasio aspek: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` |
| `resolution` | string | Petunjuk resolusi: `1K`, `2K`, atau `4K` |
| `count` | number | Jumlah gambar yang akan dibuat (1–4) |
| `filename` | string | Petunjuk nama file output |
| `resolution` | string | Petunjuk resolusi: `1K`, `2K`, atau `4K` |
| `count` | number | Jumlah gambar yang akan dibuat (1–4) |
| `filename` | string | Petunjuk nama file keluaran |
Tidak semua provider mendukung semua parameter. Tool ini meneruskan parameter yang didukung setiap provider, mengabaikan sisanya, dan melaporkan override yang dibuang dalam hasil tool.
Tidak semua penyedia mendukung semua parameter. Tool ini meneruskan parameter yang didukung setiap penyedia, mengabaikan sisanya, dan melaporkan override yang diabaikan dalam hasil tool.
## Konfigurasi
@ -94,25 +94,25 @@ Tidak semua provider mendukung semua parameter. Tool ini meneruskan parameter ya
}
```
### Urutan pemilihan provider
### Urutan pemilihan penyedia
Saat membuat gambar, OpenClaw mencoba provider dalam urutan berikut:
Saat membuat gambar, OpenClaw mencoba penyedia dalam urutan ini:
1. **Parameter `model`** dari pemanggilan tool (jika agen menentukannya)
1. Parameter **`model`** dari pemanggilan tool (jika agen menentukannya)
2. **`imageGenerationModel.primary`** dari konfigurasi
3. **`imageGenerationModel.fallbacks`** secara berurutan
4. **Deteksi otomatis** — hanya menggunakan default provider yang didukung auth:
- provider default saat ini terlebih dahulu
- provider pembuatan gambar terdaftar yang tersisa dalam urutan id provider
4. **Deteksi otomatis** — hanya menggunakan default penyedia yang didukung autentikasi:
- penyedia default saat ini terlebih dahulu
- penyedia pembuatan gambar terdaftar lainnya yang tersisa dalam urutan provider-id
Jika suatu provider gagal (error auth, rate limit, dan sebagainya), kandidat berikutnya dicoba secara otomatis. Jika semuanya gagal, error akan menyertakan detail dari setiap percobaan.
Jika suatu penyedia gagal (kesalahan autentikasi, batas laju, dll.), kandidat berikutnya akan dicoba secara otomatis. Jika semuanya gagal, kesalahan akan menyertakan detail dari setiap percobaan.
Catatan:
- Deteksi otomatis sadar auth. Default provider hanya masuk ke daftar kandidat
saat OpenClaw benar-benar dapat mengautentikasi provider tersebut.
- Gunakan `action: "list"` untuk memeriksa provider yang saat ini terdaftar, model
defaultnya, dan petunjuk env var auth.
- Deteksi otomatis bersifat sadar autentikasi. Default penyedia hanya masuk ke daftar kandidat
ketika OpenClaw benar-benar dapat mengautentikasi penyedia tersebut.
- Gunakan `action: "list"` untuk memeriksa penyedia yang saat ini terdaftar, model
default mereka, dan petunjuk env var autentikasi.
### Pengeditan gambar
@ -124,29 +124,29 @@ OpenAI, Google, fal, MiniMax, dan ComfyUI mendukung pengeditan gambar referensi.
OpenAI dan Google mendukung hingga 5 gambar referensi melalui parameter `images`. fal, MiniMax, dan ComfyUI mendukung 1.
Pembuatan gambar MiniMax tersedia melalui kedua jalur auth MiniMax bawaan:
Pembuatan gambar MiniMax tersedia melalui kedua jalur autentikasi MiniMax bawaan:
- `minimax/image-01` untuk penyiapan API key
- `minimax/image-01` untuk penyiapan kunci API
- `minimax-portal/image-01` untuk penyiapan OAuth
## Kapabilitas provider
## Kemampuan penyedia
| Kapabilitas | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra |
| -------------------- | -------------------- | -------------------- | ------------------- | -------------------------- | ---------------------------------- | ----- |
| Membuat | Ya (hingga 4) | Ya (hingga 4) | Ya (hingga 4) | Ya (hingga 9) | Ya (output ditentukan workflow) | Ya (1) |
| Edit/referensi | Ya (hingga 5 gambar) | Ya (hingga 5 gambar) | Ya (1 gambar) | Ya (1 gambar, referensi subjek) | Ya (1 gambar, dikonfigurasi workflow) | Tidak |
| Kontrol ukuran | Ya | Ya | Ya | Tidak | Tidak | Tidak |
| Rasio aspek | Tidak | Ya | Ya (hanya generate) | Ya | Tidak | Tidak |
| Resolusi (1K/2K/4K) | Tidak | Ya | Ya | Tidak | Tidak | Tidak |
| Kemampuan | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra |
| -------------------- | -------------------- | -------------------- | ------------------- | -------------------------- | ---------------------------------- | ------- |
| Buat | Ya (hingga 4) | Ya (hingga 4) | Ya (hingga 4) | Ya (hingga 9) | Ya (keluaran ditentukan alur kerja) | Ya (1) |
| Edit/referensi | Ya (hingga 5 gambar) | Ya (hingga 5 gambar) | Ya (1 gambar) | Ya (1 gambar, referensi subjek) | Ya (1 gambar, dikonfigurasi alur kerja) | Tidak |
| Kontrol ukuran | Ya | Ya | Ya | Tidak | Tidak | Tidak |
| Rasio aspek | Tidak | Ya | Ya (hanya generate) | Ya | Tidak | Tidak |
| Resolusi (1K/2K/4K) | Tidak | Ya | Ya | Tidak | Tidak | Tidak |
## Terkait
- [Ikhtisar Tools](/id/tools) — semua tool agen yang tersedia
- [fal](/providers/fal) — penyiapan provider gambar dan video fal
- [ComfyUI](/providers/comfy) — penyiapan workflow ComfyUI lokal dan Comfy Cloud
- [Google (Gemini)](/id/providers/google) — penyiapan provider gambar Gemini
- [MiniMax](/id/providers/minimax) — penyiapan provider gambar MiniMax
- [OpenAI](/id/providers/openai) — penyiapan provider OpenAI Images
- [Vydra](/providers/vydra) — penyiapan gambar, video, dan speech Vydra
- [fal](/id/providers/fal) — penyiapan penyedia gambar dan video fal
- [ComfyUI](/id/providers/comfy) — penyiapan alur kerja ComfyUI lokal dan Comfy Cloud
- [Google (Gemini)](/id/providers/google) — penyiapan penyedia gambar Gemini
- [MiniMax](/id/providers/minimax) — penyiapan penyedia gambar MiniMax
- [OpenAI](/id/providers/openai) — penyiapan penyedia OpenAI Images
- [Vydra](/id/providers/vydra) — penyiapan gambar, video, dan ucapan Vydra
- [Referensi Konfigurasi](/id/gateway/configuration-reference#agent-defaults) — konfigurasi `imageGenerationModel`
- [Models](/id/concepts/models) — konfigurasi model dan failover

168
docs/id/tools/video-generation.md
View File

@ -1,30 +1,30 @@
---
read_when:
- Membuat video melalui agen
- Mengonfigurasi provider dan model pembuatan video
- Memahami parameter tool `video_generate`
summary: Buat video dari teks, gambar, atau video yang sudah ada menggunakan 12 backend provider
- Menghasilkan video melalui agen
- Mengonfigurasi penyedia dan model pembuatan video
- Memahami parameter tool video_generate
summary: Hasilkan video dari teks, gambar, atau video yang sudah ada menggunakan 12 backend penyedia
title: Pembuatan Video
x-i18n:
generated_at: "2026-04-06T03:12:55Z"
generated_at: "2026-04-06T09:13:25Z"
model: gpt-5.4
provider: openai
source_hash: 4afec87368232221db1aa5a3980254093d6a961b17271b2dcbf724e6bd455b16
source_hash: 90d8a392b35adbd899232b02c55c10895b9d7ffc9858d6ca448f2e4e4a57f12f
source_path: tools/video-generation.md
workflow: 15
---
# Pembuatan Video
Agen OpenClaw dapat membuat video dari prompt teks, gambar referensi, atau video yang sudah ada. Dua belas backend provider didukung, masing-masing dengan opsi model, mode input, dan set fitur yang berbeda. Agen memilih provider yang tepat secara otomatis berdasarkan konfigurasi dan API key yang tersedia.
Agen OpenClaw dapat menghasilkan video dari prompt teks, gambar referensi, atau video yang sudah ada. Dua belas backend penyedia didukung, masing-masing dengan opsi model, mode input, dan kumpulan fitur yang berbeda. Agen memilih penyedia yang tepat secara otomatis berdasarkan konfigurasi Anda dan API key yang tersedia.
<Note>
Tool `video_generate` hanya muncul saat setidaknya satu provider pembuatan video tersedia. Jika Anda tidak melihatnya di tool agen Anda, tetapkan API key provider atau konfigurasikan `agents.defaults.videoGenerationModel`.
Tool `video_generate` hanya muncul ketika setidaknya satu penyedia pembuatan video tersedia. Jika Anda tidak melihatnya di tool agen Anda, tetapkan API key penyedia atau konfigurasikan `agents.defaults.videoGenerationModel`.
</Note>
## Memulai cepat
## Mulai cepat
1. Tetapkan API key untuk provider yang didukung mana pun:
1. Tetapkan API key untuk penyedia yang didukung:
```bash
export GEMINI_API_KEY="your-key"
@ -38,98 +38,98 @@ openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1
3. Minta agen:
> Buat video sinematik berdurasi 5 detik tentang lobster ramah yang sedang berselancar saat matahari terbenam.
> Hasilkan video sinematik berdurasi 5 detik tentang seekor lobster ramah yang berselancar saat matahari terbenam.
Agen memanggil `video_generate` secara otomatis. Tidak diperlukan allowlisting tool.
Agen memanggil `video_generate` secara otomatis. Tidak perlu allowlist tool.
## Apa yang terjadi saat Anda membuat video
## Apa yang terjadi saat Anda menghasilkan video
Pembuatan video bersifat asynchronous. Saat agen memanggil `video_generate` dalam sebuah sesi:
Pembuatan video bersifat asinkron. Saat agen memanggil `video_generate` dalam sebuah sesi:
1. OpenClaw mengirimkan permintaan ke provider dan langsung mengembalikan ID tugas.
2. Provider memproses pekerjaan di latar belakang (biasanya 30 detik hingga 5 menit tergantung pada provider dan resolusi).
3. Saat video siap, OpenClaw membangunkan sesi yang sama dengan event penyelesaian internal.
4. Agen mengirimkan video yang telah selesai kembali ke percakapan asli.
1. OpenClaw mengirim permintaan ke penyedia dan segera mengembalikan ID tugas.
2. Penyedia memproses pekerjaan di latar belakang (biasanya 30 detik hingga 5 menit tergantung pada penyedia dan resolusi).
3. Saat video siap, OpenClaw membangunkan sesi yang sama dengan peristiwa penyelesaian internal.
4. Agen memposting video yang sudah selesai kembali ke percakapan asli.
Saat sebuah pekerjaan sedang berjalan, pemanggilan `video_generate` duplikat dalam sesi yang sama akan mengembalikan status tugas saat ini alih-alih memulai pembuatan lain. Gunakan `openclaw tasks list` atau `openclaw tasks show <taskId>` untuk memeriksa progres dari CLI.
Saat sebuah pekerjaan sedang berjalan, panggilan `video_generate` duplikat dalam sesi yang sama mengembalikan status tugas saat ini alih-alih memulai pembuatan lain. Gunakan `openclaw tasks list` atau `openclaw tasks show <taskId>` untuk memeriksa progres dari CLI.
Di luar eksekusi agen berbasis sesi (misalnya, pemanggilan tool langsung), tool ini fallback ke pembuatan inline dan mengembalikan path media final pada giliran yang sama.
Di luar eksekusi agen berbasis sesi (misalnya, pemanggilan tool langsung), tool ini kembali ke pembuatan inline dan mengembalikan path media akhir dalam giliran yang sama.
## Provider yang didukung
## Penyedia yang didukung
| Provider | Model default | Teks | Ref gambar | Ref video | API key |
| -------- | ------------------------------- | ---- | ---------------- | ---------------- | ---------------------------------------- |
| Alibaba | `wan2.6-t2v` | Ya | Ya (URL remote) | Ya (URL remote) | `MODELSTUDIO_API_KEY` |
| BytePlus | `seedance-1-0-lite-t2v-250428` | Ya | 1 gambar | Tidak | `BYTEPLUS_API_KEY` |
| ComfyUI | `workflow` | Ya | 1 gambar | Tidak | `COMFY_API_KEY` atau `COMFY_CLOUD_API_KEY` |
| fal | `fal-ai/minimax/video-01-live` | Ya | 1 gambar | Tidak | `FAL_KEY` |
| Google | `veo-3.1-fast-generate-preview` | Ya | 1 gambar | 1 video | `GEMINI_API_KEY` |
| MiniMax | `MiniMax-Hailuo-2.3` | Ya | 1 gambar | Tidak | `MINIMAX_API_KEY` |
| OpenAI | `sora-2` | Ya | 1 gambar | 1 video | `OPENAI_API_KEY` |
| Qwen | `wan2.6-t2v` | Ya | Ya (URL remote) | Ya (URL remote) | `QWEN_API_KEY` |
| Runway | `gen4.5` | Ya | 1 gambar | 1 video | `RUNWAYML_API_SECRET` |
| Together | `Wan-AI/Wan2.2-T2V-A14B` | Ya | 1 gambar | Tidak | `TOGETHER_API_KEY` |
| Vydra | `veo3` | Ya | 1 gambar (`kling`) | Tidak | `VYDRA_API_KEY` |
| xAI | `grok-imagine-video` | Ya | 1 gambar | 1 video | `XAI_API_KEY` |
| Penyedia | Model default | Teks | Referensi gambar | Referensi video | API key |
| -------- | ------------------------------- | ---- | ----------------- | --------------- | ---------------------------------------- |
| Alibaba | `wan2.6-t2v` | Ya | Ya (URL jarak jauh) | Ya (URL jarak jauh) | `MODELSTUDIO_API_KEY` |
| BytePlus | `seedance-1-0-lite-t2v-250428` | Ya | 1 gambar | Tidak | `BYTEPLUS_API_KEY` |
| ComfyUI | `workflow` | Ya | 1 gambar | Tidak | `COMFY_API_KEY` atau `COMFY_CLOUD_API_KEY` |
| fal | `fal-ai/minimax/video-01-live` | Ya | 1 gambar | Tidak | `FAL_KEY` |
| Google | `veo-3.1-fast-generate-preview` | Ya | 1 gambar | 1 video | `GEMINI_API_KEY` |
| MiniMax | `MiniMax-Hailuo-2.3` | Ya | 1 gambar | Tidak | `MINIMAX_API_KEY` |
| OpenAI | `sora-2` | Ya | 1 gambar | 1 video | `OPENAI_API_KEY` |
| Qwen | `wan2.6-t2v` | Ya | Ya (URL jarak jauh) | Ya (URL jarak jauh) | `QWEN_API_KEY` |
| Runway | `gen4.5` | Ya | 1 gambar | 1 video | `RUNWAYML_API_SECRET` |
| Together | `Wan-AI/Wan2.2-T2V-A14B` | Ya | 1 gambar | Tidak | `TOGETHER_API_KEY` |
| Vydra | `veo3` | Ya | 1 gambar (`kling`) | Tidak | `VYDRA_API_KEY` |
| xAI | `grok-imagine-video` | Ya | 1 gambar | 1 video | `XAI_API_KEY` |
Beberapa provider menerima env var API key tambahan atau alternatif. Lihat [halaman provider](#related) masing-masing untuk detail.
Beberapa penyedia menerima variabel env API key tambahan atau alternatif. Lihat [halaman penyedia](#related) masing-masing untuk detailnya.
Jalankan `video_generate action=list` untuk memeriksa provider dan model yang tersedia saat runtime.
Jalankan `video_generate action=list` untuk memeriksa penyedia dan model yang tersedia saat runtime.
## Parameter tool
### Wajib
| Parameter | Tipe | Deskripsi |
| --------- | ------ | ----------------------------------------------------------------------------- |
| `prompt` | string | Deskripsi teks video yang akan dibuat (wajib untuk `action: "generate"`) |
| Parameter | Tipe | Deskripsi |
| --------- | ------ | ---------------------------------------------------------------------------- |
| `prompt` | string | Deskripsi teks video yang akan dihasilkan (wajib untuk `action: "generate"`) |
### Input konten
| Parameter | Tipe | Deskripsi |
| --------- | -------- | -------------------------------------- |
| `image` | string | Gambar referensi tunggal (path atau URL) |
| `images` | string[] | Beberapa gambar referensi (hingga 5) |
| `video` | string | Video referensi tunggal (path atau URL) |
| `videos` | string[] | Beberapa video referensi (hingga 4) |
| Parameter | Tipe | Deskripsi |
| --------- | -------- | ------------------------------------- |
| `image` | string | Satu gambar referensi (path atau URL) |
| `images` | string[] | Beberapa gambar referensi (hingga 5) |
| `video` | string | Satu video referensi (path atau URL) |
| `videos` | string[] | Beberapa video referensi (hingga 4) |
### Kontrol gaya
| Parameter | Tipe | Deskripsi |
| ----------------- | ------- | ----------------------------------------------------------------------- |
| `aspectRatio` | string | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` |
| `aspectRatio` | string | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` |
| `resolution` | string | `480P`, `720P`, atau `1080P` |
| `durationSeconds` | number | Durasi target dalam detik (dibulatkan ke nilai terdekat yang didukung provider) |
| `size` | string | Petunjuk ukuran saat provider mendukungnya |
| `audio` | boolean | Aktifkan audio yang dihasilkan saat didukung |
| `watermark` | boolean | Mengaktifkan/menonaktifkan watermark provider saat didukung |
| `durationSeconds` | number | Durasi target dalam detik (dibulatkan ke nilai terdekat yang didukung penyedia) |
| `size` | string | Petunjuk ukuran saat penyedia mendukungnya |
| `audio` | boolean | Aktifkan audio yang dihasilkan jika didukung |
| `watermark` | boolean | Alihkan watermark penyedia jika didukung |
### Lanjutan
| Parameter | Tipe | Deskripsi |
| ---------- | ------ | ---------------------------------------------- |
| `action` | string | `"generate"` (default), `"status"`, atau `"list"` |
| `model` | string | Override provider/model (misalnya `runway/gen4.5`) |
| `model` | string | Override penyedia/model (misalnya `runway/gen4.5`) |
| `filename` | string | Petunjuk nama file output |
Tidak semua provider mendukung semua parameter. Override yang tidak didukung diabaikan berdasarkan upaya terbaik dan dilaporkan sebagai peringatan dalam hasil tool. Batas kapabilitas yang keras (seperti terlalu banyak input referensi) gagal sebelum pengiriman.
Tidak semua penyedia mendukung semua parameter. Override yang tidak didukung diabaikan berdasarkan upaya terbaik dan dilaporkan sebagai peringatan dalam hasil tool. Batas kemampuan keras (seperti terlalu banyak input referensi) gagal sebelum pengiriman.
## Actions
## Aksi
- **generate** (default) -- membuat video dari prompt yang diberikan dan input referensi opsional.
- **status** -- memeriksa status tugas video yang sedang berjalan untuk sesi saat ini tanpa memulai pembuatan lain.
- **list** -- menampilkan provider, model, dan kapabilitasnya yang tersedia.
- **generate** (default) -- buat video dari prompt yang diberikan dan input referensi opsional.
- **status** -- periksa status tugas video yang sedang berjalan untuk sesi saat ini tanpa memulai pembuatan lain.
- **list** -- tampilkan penyedia, model, dan kapabilitasnya yang tersedia.
## Pemilihan model
Saat membuat video, OpenClaw menyelesaikan model dalam urutan berikut:
Saat menghasilkan video, OpenClaw menyelesaikan model dalam urutan ini:
1. **Parameter tool `model`** -- jika agen menentukannya dalam pemanggilan.
1. **`model` parameter tool** -- jika agen menentukannya dalam panggilan.
2. **`videoGenerationModel.primary`** -- dari konfigurasi.
3. **`videoGenerationModel.fallbacks`** -- dicoba secara berurutan.
4. **Deteksi otomatis** -- menggunakan provider yang memiliki auth valid, dimulai dari provider default saat ini, lalu provider yang tersisa dalam urutan alfabetis.
4. **Deteksi otomatis** -- menggunakan penyedia yang memiliki autentikasi valid, dimulai dari penyedia default saat ini, lalu penyedia yang tersisa dalam urutan alfabet.
Jika suatu provider gagal, kandidat berikutnya dicoba secara otomatis. Jika semua kandidat gagal, error akan menyertakan detail dari setiap percobaan.
Jika sebuah penyedia gagal, kandidat berikutnya dicoba secara otomatis. Jika semua kandidat gagal, error menyertakan detail dari setiap percobaan.
```json5
{
@ -144,26 +144,26 @@ Jika suatu provider gagal, kandidat berikutnya dicoba secara otomatis. Jika semu
}
```
## Catatan provider
## Catatan penyedia
| Provider | Catatan |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Alibaba | Menggunakan endpoint asynchronous DashScope/Model Studio. Gambar dan video referensi harus berupa URL `http(s)` remote. |
| BytePlus | Hanya satu gambar referensi. |
| ComfyUI | Eksekusi lokal atau cloud berbasis workflow. Mendukung text-to-video dan image-to-video melalui graph yang dikonfigurasi. |
| fal | Menggunakan alur berbasis antrean untuk pekerjaan berdurasi panjang. Hanya satu gambar referensi. |
| Google | Menggunakan Gemini/Veo. Mendukung satu gambar atau satu video referensi. |
| MiniMax | Hanya satu gambar referensi. |
| OpenAI | Hanya override `size` yang diteruskan. Override gaya lain (`aspectRatio`, `resolution`, `audio`, `watermark`) diabaikan dengan peringatan. |
| Qwen | Backend DashScope yang sama dengan Alibaba. Input referensi harus berupa URL `http(s)` remote; file lokal ditolak di awal. |
| Runway | Mendukung file lokal melalui data URI. Video-to-video memerlukan `runway/gen4_aleph`. Eksekusi hanya teks mengekspos rasio aspek `16:9` dan `9:16`. |
| Together | Hanya satu gambar referensi. |
| Vydra | Menggunakan `https://www.vydra.ai/api/v1` secara langsung untuk menghindari redirect yang menghilangkan auth. `veo3` dibundel hanya sebagai text-to-video; `kling` memerlukan URL gambar remote. |
| xAI | Mendukung alur text-to-video, image-to-video, dan edit/perpanjang video remote. |
| Penyedia | Catatan |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Alibaba | Menggunakan endpoint asinkron DashScope/Model Studio. Gambar dan video referensi harus berupa URL `http(s)` jarak jauh. |
| BytePlus | Hanya satu gambar referensi. |
| ComfyUI | Eksekusi lokal atau cloud berbasis workflow. Mendukung text-to-video dan image-to-video melalui graph yang dikonfigurasi. |
| fal | Menggunakan alur berbasis antrean untuk pekerjaan yang berjalan lama. Hanya satu gambar referensi. |
| Google | Menggunakan Gemini/Veo. Mendukung satu referensi gambar atau satu referensi video. |
| MiniMax | Hanya satu gambar referensi. |
| OpenAI | Hanya override `size` yang diteruskan. Override gaya lainnya (`aspectRatio`, `resolution`, `audio`, `watermark`) diabaikan dengan peringatan. |
| Qwen | Backend DashScope yang sama dengan Alibaba. Input referensi harus berupa URL `http(s)` jarak jauh; file lokal ditolak sejak awal. |
| Runway | Mendukung file lokal melalui URI data. Video-to-video memerlukan `runway/gen4_aleph`. Eksekusi khusus teks mengekspos rasio aspek `16:9` dan `9:16`. |
| Together | Hanya satu gambar referensi. |
| Vydra | Menggunakan `https://www.vydra.ai/api/v1` secara langsung untuk menghindari pengalihan yang membuang autentikasi. `veo3` dibundel hanya sebagai text-to-video; `kling` memerlukan URL gambar jarak jauh. |
| xAI | Mendukung alur text-to-video, image-to-video, dan edit/perluas video jarak jauh. |
## Konfigurasi
Tetapkan model pembuatan video default dalam konfigurasi OpenClaw Anda:
Tetapkan model pembuatan video default di konfigurasi OpenClaw Anda:
```json5
{
@ -187,18 +187,18 @@ openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2
## Terkait
- [Ikhtisar Tools](/id/tools)
- [Tugas Latar Belakang](/id/automation/tasks) -- pelacakan tugas untuk pembuatan video asynchronous
- [Alibaba Model Studio](/providers/alibaba)
- [BytePlus](/providers/byteplus)
- [ComfyUI](/providers/comfy)
- [fal](/providers/fal)
- [Tugas Latar Belakang](/id/automation/tasks) -- pelacakan tugas untuk pembuatan video asinkron
- [Alibaba Model Studio](/id/providers/alibaba)
- [BytePlus](/id/concepts/model-providers#byteplus-international)
- [ComfyUI](/id/providers/comfy)
- [fal](/id/providers/fal)
- [Google (Gemini)](/id/providers/google)
- [MiniMax](/id/providers/minimax)
- [OpenAI](/id/providers/openai)
- [Qwen](/id/providers/qwen)
- [Runway](/providers/runway)
- [Runway](/id/providers/runway)
- [Together AI](/id/providers/together)
- [Vydra](/providers/vydra)
- [Vydra](/id/providers/vydra)
- [xAI](/id/providers/xai)
- [Referensi Konfigurasi](/id/gateway/configuration-reference#agent-defaults)
- [Models](/id/concepts/models)