diff --git a/docs/id/channels/matrix.md b/docs/id/channels/matrix.md index 40c97d040..966104e95 100644 --- a/docs/id/channels/matrix.md +++ b/docs/id/channels/matrix.md @@ -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-.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__HOMESERVER` - `MATRIX__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-`, 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-`, 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..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..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 `. -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 `. +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 ` ke setiap perintah jika Anda ingin menargetkan akun Matrix bernama secara eksplisit. +Tambahkan `--account ` 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//__//`. -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 ` saat Anda ingin menargetkan akun Matrix bernama secara eksplisit. +Tambahkan `--account ` 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..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..ackReactionScope` - `channels["matrix"].ackReactionScope` - `messages.ackReactionScope` -Mode notifikasi reaksi diselesaikan dalam urutan ini: +Mode notifikasi reaksi di-resolve dalam urutan ini: - `channels["matrix"].accounts..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 ``` -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 allow-once`, `/approve allow-always`, atau `/approve deny`. +Approver dapat bereaksi pada pesan itu atau menggunakan perintah slash fallback: `/approve allow-once`, `/approve allow-always`, atau `/approve 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..account` (atau `rooms..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 ` untuk perintah CLI yang bergantung pada pemilihan akun implisit. -Teruskan `--account ` 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..account` (atau `rooms..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 ` untuk perintah CLI yang bergantung pada pemilihan akun implisit. +Berikan `--account ` 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..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..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..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..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..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..account`: batasi satu entri room yang diwarisi ke akun Matrix tertentu dalam penyiapan multi-akun. - `groups..allowBots`: override tingkat room untuk pengirim bot yang dikonfigurasi (`true` atau `"mentions"`). - `groups..users`: allowlist pengirim per room. -- `groups..tools`: override izin/tolak tool per room. -- `groups..autoReply`: override mention-gating tingkat room. `true` menonaktifkan persyaratan mention untuk room itu; `false` memaksanya aktif kembali. -- `groups..skills`: filter skill tingkat room opsional. -- `groups..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..tools`: override allow/deny tool per room. +- `groups..autoReply`: override pembatasan mention tingkat room. `true` menonaktifkan persyaratan mention untuk room tersebut; `false` memaksanya aktif kembali. +- `groups..skills`: filter skill opsional tingkat room. +- `groups..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 diff --git a/docs/id/channels/slack.md b/docs/id/channels/slack.md index b85f2da36..23354374d 100644 --- a/docs/id/channels/slack.md +++ b/docs/id/channels/slack.md @@ -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. - DM Slack secara default menggunakan mode pairing. + DM Slack default ke mode pairing. Perilaku perintah native dan katalog perintah. - Diagnostik lintas-channel dan playbook perbaikan. + Diagnostik lintas channel dan playbook perbaikan. -## Pengaturan cepat +## Penyiapan cepat @@ -89,13 +89,13 @@ openclaw gateway - + - 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`) @@ -120,17 +120,17 @@ openclaw gateway 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. -## Checklist manifes dan scope +## Manifest dan daftar periksa scope - - + + ```json { @@ -205,10 +205,101 @@ openclaw gateway } ``` - + + + +```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" + } + } +} +``` + + + + + + + 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:`. + + - 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`. -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. ## 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 `. @@ -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` - 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.`; nama hanya melalui resolusi saat startup atau `dangerouslyAllowNameMatching`): + Kontrol per channel (`channels.slack.channels.`; 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::slack:channel:`. -- Balasan thread dapat membuat sufiks sesi thread (`:thread:`) bila berlaku. +- Balasan thread dapat membuat sufiks sesi thread (`:thread:`) 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:]]` -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..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 - - 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. + + 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`. - + - 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 - Target eksplisit yang disarankan: + Target eksplisit yang diprioritaskan: - `user:` untuk DM - `channel:` 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 `/`), 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 - 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. @@ -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. @@ -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) diff --git a/docs/id/concepts/dreaming.md b/docs/id/concepts/dreaming.md index 8cedd9c91..0701a0cf6 100644 --- a/docs/id/concepts/dreaming.md +++ b/docs/id/concepts/dreaming.md @@ -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//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//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 diff --git a/docs/id/gateway/configuration-reference.md b/docs/id/gateway/configuration-reference.md index 34ef8b9bc..29ceec6c3 100644 --- a/docs/id/gateway/configuration-reference.md +++ b/docs/id/gateway/configuration-reference.md @@ -1,56 +1,56 @@ --- read_when: - - Anda memerlukan semantik konfigurasi atau nilai default yang tepat hingga tingkat field - - Anda sedang memvalidasi blok konfigurasi channel, model, gateway, atau tool -summary: Referensi lengkap untuk setiap kunci konfigurasi OpenClaw, default, dan pengaturan channel + - Anda membutuhkan semantik config atau nilai bawaan yang tepat di tingkat field + - Anda sedang memvalidasi blok config channel, model, gateway, atau tool +summary: Referensi lengkap untuk setiap kunci config OpenClaw, nilai bawaan, dan pengaturan channel title: Referensi Konfigurasi x-i18n: - generated_at: "2026-04-06T03:12:40Z" + generated_at: "2026-04-06T09:18:03Z" model: gpt-5.4 provider: openai - source_hash: 6aa6b24b593f6f07118817afabea4cc7842aca6b7c5602b45f479b40c1685230 + source_hash: 6ae6c19666f65433361e1c8b100ae710448c8aa055a60c140241a8aea09b98a5 source_path: gateway/configuration-reference.md workflow: 15 --- # Referensi Konfigurasi -Setiap field yang tersedia di `~/.openclaw/openclaw.json`. Untuk gambaran umum berbasis tugas, lihat [Configuration](/id/gateway/configuration). +Setiap field yang tersedia di `~/.openclaw/openclaw.json`. Untuk gambaran umum yang berorientasi tugas, lihat [Configuration](/id/gateway/configuration). -Format konfigurasi adalah **JSON5** (komentar + koma di akhir diperbolehkan). Semua field bersifat opsional — OpenClaw menggunakan default yang aman saat dihilangkan. +Format config adalah **JSON5** (komentar + koma di akhir diperbolehkan). Semua field bersifat opsional — OpenClaw menggunakan nilai bawaan yang aman saat dihilangkan. --- -## Channels +## Channel -Setiap channel mulai secara otomatis saat bagian konfigurasinya ada (kecuali `enabled: false`). +Setiap channel dimulai secara otomatis ketika bagian config-nya ada (kecuali `enabled: false`). ### Akses DM dan grup Semua channel mendukung kebijakan DM dan kebijakan grup: -| Kebijakan DM | Perilaku | -| ------------------- | --------------------------------------------------------------- | -| `pairing` (default) | Pengirim yang tidak dikenal mendapatkan kode pairing satu kali; pemilik harus menyetujui | -| `allowlist` | Hanya pengirim dalam `allowFrom` (atau penyimpanan allow hasil pairing) | -| `open` | Izinkan semua DM masuk (memerlukan `allowFrom: ["*"]`) | -| `disabled` | Abaikan semua DM masuk | +| Kebijakan DM | Perilaku | +| ------------------- | ------------------------------------------------------------- | +| `pairing` (default) | Pengirim yang tidak dikenal mendapat kode pairing satu kali; owner harus menyetujui | +| `allowlist` | Hanya pengirim di `allowFrom` (atau paired allow store) | +| `open` | Izinkan semua DM masuk (memerlukan `allowFrom: ["*"]`) | +| `disabled` | Abaikan semua DM masuk | -| Kebijakan grup | Perilaku | -| --------------------- | ------------------------------------------------------ | +| Kebijakan grup | Perilaku | +| --------------------- | ---------------------------------------------------- | | `allowlist` (default) | Hanya grup yang cocok dengan allowlist yang dikonfigurasi | -| `open` | Lewati allowlist grup (gating mention tetap berlaku) | -| `disabled` | Blokir semua pesan grup/room | +| `open` | Lewati allowlist grup (mention-gating tetap berlaku) | +| `disabled` | Blokir semua pesan grup/room | -`channels.defaults.groupPolicy` menetapkan default saat `groupPolicy` milik provider tidak disetel. +`channels.defaults.groupPolicy` menetapkan default ketika `groupPolicy` milik provider tidak diatur. Kode pairing kedaluwarsa setelah 1 jam. Permintaan pairing DM yang tertunda dibatasi hingga **3 per channel**. -Jika blok provider sama sekali tidak ada (`channels.` tidak ada), kebijakan grup runtime kembali ke `allowlist` (fail-closed) dengan peringatan saat startup. +Jika blok provider tidak ada sama sekali (`channels.` tidak ada), kebijakan grup runtime akan fallback ke `allowlist` (fail-closed) dengan peringatan saat startup. ### Override model channel -Gunakan `channels.modelByChannel` untuk menyematkan ID channel tertentu ke sebuah model. Nilai menerima `provider/model` atau alias model yang dikonfigurasi. Pemetaan channel diterapkan saat sesi belum memiliki override model (misalnya, disetel melalui `/model`). +Gunakan `channels.modelByChannel` untuk menetapkan ID channel tertentu ke sebuah model. Nilai menerima `provider/model` atau alias model yang dikonfigurasi. Pemetaan channel diterapkan ketika sebuah sesi belum memiliki override model (misalnya, diatur melalui `/model`). ```json5 { @@ -73,7 +73,7 @@ Gunakan `channels.modelByChannel` untuk menyematkan ID channel tertentu ke sebua ### Default channel dan heartbeat -Gunakan `channels.defaults` untuk perilaku kebijakan grup dan heartbeat bersama di seluruh provider: +Gunakan `channels.defaults` untuk perilaku group-policy dan heartbeat bersama di seluruh provider: ```json5 { @@ -91,15 +91,15 @@ Gunakan `channels.defaults` untuk perilaku kebijakan grup dan heartbeat bersama } ``` -- `channels.defaults.groupPolicy`: kebijakan grup fallback saat `groupPolicy` tingkat provider tidak disetel. -- `channels.defaults.contextVisibility`: mode visibilitas konteks tambahan default untuk semua channel. Nilai: `all` (default, sertakan semua konteks kutipan/thread/riwayat), `allowlist` (hanya sertakan konteks dari pengirim yang ada dalam allowlist), `allowlist_quote` (sama seperti allowlist tetapi mempertahankan konteks kutipan/balasan eksplisit). Override per-channel: `channels..contextVisibility`. -- `channels.defaults.heartbeat.showOk`: sertakan status channel sehat dalam output heartbeat. -- `channels.defaults.heartbeat.showAlerts`: sertakan status menurun/error dalam output heartbeat. -- `channels.defaults.heartbeat.useIndicator`: render output heartbeat bergaya indikator ringkas. +- `channels.defaults.groupPolicy`: kebijakan grup fallback saat `groupPolicy` tingkat provider tidak diatur. +- `channels.defaults.contextVisibility`: mode visibilitas konteks tambahan default untuk semua channel. Nilai: `all` (default, sertakan semua konteks kutipan/thread/riwayat), `allowlist` (hanya sertakan konteks dari pengirim yang ada di allowlist), `allowlist_quote` (sama seperti allowlist tetapi pertahankan konteks kutipan/balasan eksplisit). Override per-channel: `channels..contextVisibility`. +- `channels.defaults.heartbeat.showOk`: sertakan status channel yang sehat dalam output heartbeat. +- `channels.defaults.heartbeat.showAlerts`: sertakan status yang menurun/error dalam output heartbeat. +- `channels.defaults.heartbeat.useIndicator`: render output heartbeat bergaya indikator yang ringkas. ### WhatsApp -WhatsApp berjalan melalui channel web gateway (Baileys Web). Mulai secara otomatis saat sesi tertaut ada. +WhatsApp berjalan melalui channel web gateway (Baileys Web). Channel ini dimulai secara otomatis saat sesi yang tertaut sudah ada. ```json5 { @@ -132,7 +132,7 @@ WhatsApp berjalan melalui channel web gateway (Baileys Web). Mulai secara otomat } ``` - + ```json5 { @@ -150,10 +150,10 @@ WhatsApp berjalan melalui channel web gateway (Baileys Web). Mulai secara otomat } ``` -- Perintah keluar menggunakan akun `default` secara default jika ada; jika tidak, ID akun pertama yang dikonfigurasi (diurutkan). -- `channels.whatsapp.defaultAccount` opsional menimpa pemilihan akun default fallback tersebut saat cocok dengan ID akun yang dikonfigurasi. -- Direktori auth Baileys satu akun lama dimigrasikan oleh `openclaw doctor` ke `whatsapp/default`. -- Override per-akun: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. +- Perintah outbound default ke akun `default` jika ada; jika tidak, ke id akun pertama yang dikonfigurasi (diurutkan). +- `channels.whatsapp.defaultAccount` opsional menggantikan pemilihan akun default fallback tersebut ketika cocok dengan id akun yang dikonfigurasi. +- Auth dir Baileys lama untuk single-account dimigrasikan oleh `openclaw doctor` ke `whatsapp/default`. +- Override per-account: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -171,24 +171,24 @@ WhatsApp berjalan melalui channel web gateway (Baileys Web). Mulai secara otomat "*": { requireMention: true }, "-1001234567890": { allowFrom: ["@admin"], - systemPrompt: "Keep answers brief.", + systemPrompt: "Jaga jawaban tetap singkat.", topics: { "99": { requireMention: false, skills: ["search"], - systemPrompt: "Stay on topic.", + systemPrompt: "Tetap fokus pada topik.", }, }, }, }, customCommands: [ - { command: "backup", description: "Git backup" }, - { command: "generate", description: "Create an image" }, + { command: "backup", description: "Backup Git" }, + { command: "generate", description: "Buat gambar" }, ], historyLimit: 50, replyToMode: "first", // off | first | all | batched linkPreview: true, - streaming: "partial", // off | partial | block | progress (default: off; opt in explicitly to avoid preview-edit rate limits) + streaming: "partial", // off | partial | block | progress (default: off; aktifkan secara eksplisit untuk menghindari rate limit pratinjau-edit) actions: { reactions: true, sendMessage: true }, reactionNotifications: "own", // off | own | all mediaMaxMb: 100, @@ -212,9 +212,9 @@ WhatsApp berjalan melalui channel web gateway (Baileys Web). Mulai secara otomat ``` - Token bot: `channels.telegram.botToken` atau `channels.telegram.tokenFile` (hanya file biasa; symlink ditolak), dengan `TELEGRAM_BOT_TOKEN` sebagai fallback untuk akun default. -- `channels.telegram.defaultAccount` opsional menimpa pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi. -- Dalam pengaturan multi-akun (2+ ID akun), setel default eksplisit (`channels.telegram.defaultAccount` atau `channels.telegram.accounts.default`) untuk menghindari perutean fallback; `openclaw doctor` memberi peringatan saat ini tidak ada atau tidak valid. -- `configWrites: false` memblokir penulisan konfigurasi yang diprakarsai Telegram (migrasi ID supergroup, `/config set|unset`). +- `channels.telegram.defaultAccount` opsional menggantikan pemilihan akun default saat cocok dengan id akun yang dikonfigurasi. +- Dalam pengaturan multi-account (2+ id akun), tetapkan default eksplisit (`channels.telegram.defaultAccount` atau `channels.telegram.accounts.default`) untuk menghindari fallback routing; `openclaw doctor` memberi peringatan saat ini tidak ada atau tidak valid. +- `configWrites: false` memblokir penulisan config yang dipicu Telegram (migrasi ID supergroup, `/config set|unset`). - Entri `bindings[]` tingkat atas dengan `type: "acp"` mengonfigurasi binding ACP persisten untuk topik forum (gunakan `chatId:topic:topicId` kanonis di `match.peer.id`). Semantik field dibagikan di [ACP Agents](/id/tools/acp-agents#channel-specific-settings). - Pratinjau stream Telegram menggunakan `sendMessage` + `editMessageText` (berfungsi di chat langsung dan grup). - Kebijakan retry: lihat [Retry policy](/id/concepts/retry). @@ -264,7 +264,7 @@ WhatsApp berjalan melalui channel web gateway (Baileys Web). Mulai secara otomat requireMention: true, users: ["987654321098765432"], skills: ["docs"], - systemPrompt: "Short answers only.", + systemPrompt: "Hanya jawaban singkat.", }, }, }, @@ -272,7 +272,7 @@ WhatsApp berjalan melalui channel web gateway (Baileys Web). Mulai secara otomat historyLimit: 20, textChunkLimit: 2000, chunkMode: "length", // length | newline - streaming: "off", // off | partial | block | progress (progress maps to partial on Discord) + streaming: "off", // off | partial | block | progress (progress dipetakan ke partial di Discord) maxLinesPerMessage: 17, ui: { components: { @@ -283,7 +283,7 @@ WhatsApp berjalan melalui channel web gateway (Baileys Web). Mulai secara otomat enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // opt-in for sessions_spawn({ thread: true }) + spawnSubagentSessions: false, // opt-in untuk sessions_spawn({ thread: true }) }, voice: { enabled: true, @@ -320,33 +320,33 @@ WhatsApp berjalan melalui channel web gateway (Baileys Web). Mulai secara otomat ``` - Token: `channels.discord.token`, dengan `DISCORD_BOT_TOKEN` sebagai fallback untuk akun default. -- Panggilan keluar langsung yang memberikan `token` Discord eksplisit menggunakan token tersebut untuk panggilan; pengaturan retry/kebijakan akun tetap berasal dari akun yang dipilih dalam snapshot runtime aktif. -- `channels.discord.defaultAccount` opsional menimpa pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi. -- Gunakan `user:` (DM) atau `channel:` (channel guild) untuk target pengiriman; ID numerik polos ditolak. -- Slug guild menggunakan huruf kecil dengan spasi diganti `-`; kunci channel menggunakan nama yang sudah di-slug (tanpa `#`). Lebih baik gunakan ID guild. -- Pesan yang ditulis bot diabaikan secara default. `allowBots: true` mengaktifkannya; gunakan `allowBots: "mentions"` untuk hanya menerima pesan bot yang me-mention bot (pesan sendiri tetap difilter). -- `channels.discord.guilds..ignoreOtherMentions` (dan override channel) membuang pesan yang me-mention pengguna atau role lain tetapi tidak me-mention bot (tidak termasuk @everyone/@here). -- `maxLinesPerMessage` (default 17) membagi pesan tinggi bahkan saat kurang dari 2000 karakter. -- `channels.discord.threadBindings` mengontrol perutean terikat thread Discord: - - `enabled`: override Discord untuk fitur sesi terikat thread (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, dan pengiriman/perutean terikat) +- Panggilan outbound langsung yang menyediakan `token` Discord eksplisit menggunakan token tersebut untuk panggilan; pengaturan retry/kebijakan akun tetap berasal dari akun terpilih dalam snapshot runtime aktif. +- `channels.discord.defaultAccount` opsional menggantikan pemilihan akun default saat cocok dengan id akun yang dikonfigurasi. +- Gunakan `user:` (DM) atau `channel:` (channel guild) untuk target pengiriman; ID numerik biasa ditolak. +- Slug guild menggunakan huruf kecil dengan spasi diganti `-`; kunci channel menggunakan nama yang di-slug (tanpa `#`). Utamakan ID guild. +- Pesan yang ditulis bot diabaikan secara default. `allowBots: true` mengaktifkannya; gunakan `allowBots: "mentions"` untuk hanya menerima pesan bot yang menyebut bot (pesan sendiri tetap difilter). +- `channels.discord.guilds..ignoreOtherMentions` (dan override channel) membuang pesan yang menyebut pengguna atau role lain tetapi tidak menyebut bot (tidak termasuk @everyone/@here). +- `maxLinesPerMessage` (default 17) membagi pesan yang tinggi meskipun di bawah 2000 karakter. +- `channels.discord.threadBindings` mengontrol routing yang terikat thread Discord: + - `enabled`: override Discord untuk fitur sesi terikat thread (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, dan pengiriman/routing terikat) - `idleHours`: override Discord untuk auto-unfocus karena tidak aktif dalam jam (`0` menonaktifkan) - `maxAgeHours`: override Discord untuk usia maksimum keras dalam jam (`0` menonaktifkan) - - `spawnSubagentSessions`: sakelar opt-in untuk pembuatan/binding thread otomatis `sessions_spawn({ thread: true })` + - `spawnSubagentSessions`: sakelar opt-in untuk pembuatan/pengikatan thread otomatis `sessions_spawn({ thread: true })` - Entri `bindings[]` tingkat atas dengan `type: "acp"` mengonfigurasi binding ACP persisten untuk channel dan thread (gunakan id channel/thread di `match.peer.id`). Semantik field dibagikan di [ACP Agents](/id/tools/acp-agents#channel-specific-settings). -- `channels.discord.ui.components.accentColor` menetapkan warna aksen untuk kontainer Discord components v2. +- `channels.discord.ui.components.accentColor` menetapkan warna aksen untuk container Discord components v2. - `channels.discord.voice` mengaktifkan percakapan channel suara Discord dan override auto-join + TTS opsional. -- `channels.discord.voice.daveEncryption` dan `channels.discord.voice.decryptionFailureTolerance` diteruskan ke opsi DAVE `@discordjs/voice` (default `true` dan `24`). -- OpenClaw juga mencoba pemulihan penerimaan suara dengan keluar/bergabung kembali ke sesi suara setelah kegagalan dekripsi berulang. -- `channels.discord.streaming` adalah kunci mode stream kanonis. `streamMode` lama dan nilai boolean `streaming` dimigrasikan otomatis. +- `channels.discord.voice.daveEncryption` dan `channels.discord.voice.decryptionFailureTolerance` diteruskan ke opsi DAVE `@discordjs/voice` (`true` dan `24` secara default). +- OpenClaw juga mencoba pemulihan voice receive dengan meninggalkan/bergabung kembali ke sesi suara setelah kegagalan dekripsi berulang. +- `channels.discord.streaming` adalah kunci mode stream kanonis. Nilai lama `streamMode` dan boolean `streaming` dimigrasikan otomatis. - `channels.discord.autoPresence` memetakan ketersediaan runtime ke presence bot (healthy => online, degraded => idle, exhausted => dnd) dan memungkinkan override teks status opsional. - `channels.discord.dangerouslyAllowNameMatching` mengaktifkan kembali pencocokan nama/tag yang dapat berubah (mode kompatibilitas break-glass). -- `channels.discord.execApprovals`: pengiriman persetujuan exec native Discord dan otorisasi approver. - - `enabled`: `true`, `false`, atau `"auto"` (default). Dalam mode auto, persetujuan exec aktif saat approver dapat di-resolve dari `approvers` atau `commands.ownerAllowFrom`. - - `approvers`: ID pengguna Discord yang diizinkan menyetujui permintaan exec. Menggunakan `commands.ownerAllowFrom` sebagai fallback jika dihilangkan. - - `agentFilter`: allowlist ID agen opsional. Hilangkan untuk meneruskan persetujuan bagi semua agen. +- `channels.discord.execApprovals`: pengiriman approval exec native Discord dan otorisasi approver. + - `enabled`: `true`, `false`, atau `"auto"` (default). Dalam mode auto, approval exec aktif ketika approver dapat di-resolve dari `approvers` atau `commands.ownerAllowFrom`. + - `approvers`: ID pengguna Discord yang diizinkan menyetujui permintaan exec. Fallback ke `commands.ownerAllowFrom` ketika dihilangkan. + - `agentFilter`: allowlist ID agent opsional. Hilangkan untuk meneruskan approval untuk semua agent. - `sessionFilter`: pola kunci sesi opsional (substring atau regex). - - `target`: tempat mengirim prompt persetujuan. `"dm"` (default) mengirim ke DM approver, `"channel"` mengirim ke channel asal, `"both"` mengirim ke keduanya. Saat target mencakup `"channel"`, tombol hanya dapat digunakan oleh approver yang berhasil di-resolve. - - `cleanupAfterResolve`: saat `true`, menghapus DM persetujuan setelah persetujuan, penolakan, atau timeout. + - `target`: tempat mengirim prompt approval. `"dm"` (default) mengirim ke DM approver, `"channel"` mengirim ke channel asal, `"both"` mengirim ke keduanya. Saat target mencakup `"channel"`, tombol hanya bisa digunakan oleh approver yang berhasil di-resolve. + - `cleanupAfterResolve`: ketika `true`, menghapus DM approval setelah approval, penolakan, atau timeout. **Mode notifikasi reaksi:** `off` (tidak ada), `own` (pesan bot, default), `all` (semua pesan), `allowlist` (dari `guilds..users` pada semua pesan). @@ -405,7 +405,7 @@ WhatsApp berjalan melalui channel web gateway (Baileys Web). Mulai secara otomat allowBots: false, users: ["U123"], skills: ["docs"], - systemPrompt: "Short answers only.", + systemPrompt: "Hanya jawaban singkat.", }, }, historyLimit: 50, @@ -433,7 +433,7 @@ WhatsApp berjalan melalui channel web gateway (Baileys Web). Mulai secara otomat typingReaction: "hourglass_flowing_sand", textChunkLimit: 4000, chunkMode: "length", - streaming: "partial", // off | partial | block | progress (preview mode) + streaming: "partial", // off | partial | block | progress (mode pratinjau) nativeStreaming: true, // gunakan API streaming native Slack saat streaming=partial mediaMaxMb: 20, execApprovals: { @@ -448,18 +448,18 @@ WhatsApp berjalan melalui channel web gateway (Baileys Web). Mulai secara otomat } ``` -- **Mode socket** memerlukan `botToken` dan `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` untuk fallback env akun default). -- **Mode HTTP** memerlukan `botToken` plus `signingSecret` (di root atau per-akun). +- **Socket mode** memerlukan `botToken` dan `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` untuk fallback env akun default). +- **HTTP mode** memerlukan `botToken` plus `signingSecret` (di root atau per-account). - `botToken`, `appToken`, `signingSecret`, dan `userToken` menerima string plaintext atau objek SecretRef. - Snapshot akun Slack mengekspos field sumber/status per-kredensial seperti - `botTokenSource`, `botTokenStatus`, `appTokenStatus`, dan, dalam mode HTTP, + `botTokenSource`, `botTokenStatus`, `appTokenStatus`, dan, dalam HTTP mode, `signingSecretStatus`. `configured_unavailable` berarti akun tersebut - dikonfigurasi melalui SecretRef tetapi jalur perintah/runtime saat ini tidak dapat + dikonfigurasi melalui SecretRef tetapi jalur command/runtime saat ini tidak dapat me-resolve nilai secret. -- `configWrites: false` memblokir penulisan konfigurasi yang diprakarsai Slack. -- `channels.slack.defaultAccount` opsional menimpa pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi. -- `channels.slack.streaming` adalah kunci mode stream kanonis. `streamMode` lama dan nilai boolean `streaming` dimigrasikan otomatis. +- `configWrites: false` memblokir penulisan config yang dipicu Slack. +- `channels.slack.defaultAccount` opsional menggantikan pemilihan akun default saat cocok dengan id akun yang dikonfigurasi. +- `channels.slack.streaming` adalah kunci mode stream kanonis. Nilai lama `streamMode` dan boolean `streaming` dimigrasikan otomatis. - Gunakan `user:` (DM) atau `channel:` untuk target pengiriman. **Mode notifikasi reaksi:** `off`, `own` (default), `all`, `allowlist` (dari `reactionAllowlist`). @@ -467,15 +467,15 @@ WhatsApp berjalan melalui channel web gateway (Baileys Web). Mulai secara otomat **Isolasi sesi thread:** `thread.historyScope` bersifat per-thread (default) atau dibagikan di seluruh channel. `thread.inheritParent` menyalin transkrip channel induk ke thread baru. - `typingReaction` menambahkan reaksi sementara ke pesan Slack masuk saat balasan sedang berjalan, lalu menghapusnya saat selesai. Gunakan shortcode emoji Slack seperti `"hourglass_flowing_sand"`. -- `channels.slack.execApprovals`: pengiriman persetujuan exec native Slack dan otorisasi approver. Skema sama seperti Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ID pengguna Slack), `agentFilter`, `sessionFilter`, dan `target` (`"dm"`, `"channel"`, atau `"both"`). +- `channels.slack.execApprovals`: pengiriman approval exec native Slack dan otorisasi approver. Skema sama seperti Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ID pengguna Slack), `agentFilter`, `sessionFilter`, dan `target` (`"dm"`, `"channel"`, atau `"both"`). -| Grup action | Default | Catatan | -| ------------ | ------- | --------------------- | -| reactions | enabled | React + daftar reaksi | -| messages | enabled | Baca/kirim/edit/hapus | -| pins | enabled | Pin/unpin/daftar | -| memberInfo | enabled | Info anggota | -| emojiList | enabled | Daftar emoji kustom | +| Grup tindakan | Default | Catatan | +| ------------- | ------- | ---------------------- | +| reactions | enabled | React + daftar reaksi | +| messages | enabled | Baca/kirim/edit/hapus | +| pins | enabled | Pin/unpin/daftar | +| memberInfo | enabled | Info anggota | +| emojiList | enabled | Daftar emoji kustom | ### Mattermost @@ -509,23 +509,23 @@ Mattermost dikirim sebagai plugin: `openclaw plugins install @openclaw/mattermos } ``` -Mode chat: `oncall` (merespons pada @-mention, default), `onmessage` (setiap pesan), `onchar` (pesan yang diawali prefix pemicu). +Mode chat: `oncall` (merespons saat @-mention, default), `onmessage` (setiap pesan), `onchar` (pesan yang diawali dengan prefiks pemicu). Saat perintah native Mattermost diaktifkan: - `commands.callbackPath` harus berupa path (misalnya `/api/channels/mattermost/command`), bukan URL lengkap. -- `commands.callbackUrl` harus mengarah ke endpoint gateway OpenClaw dan dapat dijangkau dari server Mattermost. +- `commands.callbackUrl` harus me-resolve ke endpoint gateway OpenClaw dan dapat dijangkau dari server Mattermost. - Callback slash native diautentikasi dengan token per-perintah yang dikembalikan - oleh Mattermost selama pendaftaran slash command. Jika pendaftaran gagal atau tidak ada - perintah yang diaktifkan, OpenClaw menolak callback dengan + oleh Mattermost saat pendaftaran slash command. Jika pendaftaran gagal atau tidak + ada perintah yang diaktifkan, OpenClaw menolak callback dengan `Unauthorized: invalid command token.` -- Untuk host callback privat/tailnet/internal, Mattermost mungkin memerlukan - `ServiceSettings.AllowedUntrustedInternalConnections` agar menyertakan host/domain callback. +- Untuk host callback private/tailnet/internal, Mattermost mungkin memerlukan + `ServiceSettings.AllowedUntrustedInternalConnections` untuk menyertakan host/domain callback. Gunakan nilai host/domain, bukan URL lengkap. -- `channels.mattermost.configWrites`: izinkan atau tolak penulisan konfigurasi yang diprakarsai Mattermost. +- `channels.mattermost.configWrites`: izinkan atau tolak penulisan config yang dipicu Mattermost. - `channels.mattermost.requireMention`: memerlukan `@mention` sebelum membalas di channel. -- `channels.mattermost.groups..requireMention`: override gating mention per-channel (`"*"` untuk default). -- `channels.mattermost.defaultAccount` opsional menimpa pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi. +- `channels.mattermost.groups..requireMention`: override mention-gating per-channel (`"*"` untuk default). +- `channels.mattermost.defaultAccount` opsional menggantikan pemilihan akun default saat cocok dengan id akun yang dikonfigurasi. ### Signal @@ -548,13 +548,13 @@ Saat perintah native Mattermost diaktifkan: **Mode notifikasi reaksi:** `off`, `own` (default), `all`, `allowlist` (dari `reactionAllowlist`). -- `channels.signal.account`: sematkan startup channel ke identitas akun Signal tertentu. -- `channels.signal.configWrites`: izinkan atau tolak penulisan konfigurasi yang diprakarsai Signal. -- `channels.signal.defaultAccount` opsional menimpa pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi. +- `channels.signal.account`: pin startup channel ke identitas akun Signal tertentu. +- `channels.signal.configWrites`: izinkan atau tolak penulisan config yang dipicu Signal. +- `channels.signal.defaultAccount` opsional menggantikan pemilihan akun default saat cocok dengan id akun yang dikonfigurasi. ### BlueBubbles -BlueBubbles adalah jalur iMessage yang direkomendasikan (didukung plugin, dikonfigurasi di bawah `channels.bluebubbles`). +BlueBubbles adalah jalur iMessage yang direkomendasikan (berbasis plugin, dikonfigurasi di bawah `channels.bluebubbles`). ```json5 { @@ -562,7 +562,7 @@ BlueBubbles adalah jalur iMessage yang direkomendasikan (didukung plugin, dikonf bluebubbles: { enabled: true, dmPolicy: "pairing", - // serverUrl, password, webhookPath, kontrol grup, dan action lanjutan: + // serverUrl, password, webhookPath, kontrol grup, dan tindakan lanjutan: // lihat /channels/bluebubbles }, }, @@ -570,13 +570,13 @@ BlueBubbles adalah jalur iMessage yang direkomendasikan (didukung plugin, dikonf ``` - Jalur kunci inti yang dicakup di sini: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. -- `channels.bluebubbles.defaultAccount` opsional menimpa pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi. -- Entri `bindings[]` tingkat atas dengan `type: "acp"` dapat mengikat percakapan BlueBubbles ke sesi ACP persisten. Gunakan handle atau string target BlueBubbles (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) dalam `match.peer.id`. Semantik field bersama: [ACP Agents](/id/tools/acp-agents#channel-specific-settings). -- Konfigurasi channel BlueBubbles lengkap didokumentasikan di [BlueBubbles](/id/channels/bluebubbles). +- `channels.bluebubbles.defaultAccount` opsional menggantikan pemilihan akun default saat cocok dengan id akun yang dikonfigurasi. +- Entri `bindings[]` tingkat atas dengan `type: "acp"` dapat mengikat percakapan BlueBubbles ke sesi ACP persisten. Gunakan handle atau string target BlueBubbles (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) di `match.peer.id`. Semantik field bersama: [ACP Agents](/id/tools/acp-agents#channel-specific-settings). +- Konfigurasi lengkap channel BlueBubbles didokumentasikan di [BlueBubbles](/id/channels/bluebubbles). ### iMessage -OpenClaw memunculkan `imsg rpc` (JSON-RPC melalui stdio). Tidak memerlukan daemon atau port. +OpenClaw menjalankan `imsg rpc` (JSON-RPC melalui stdio). Tidak memerlukan daemon atau port. ```json5 { @@ -600,15 +600,15 @@ OpenClaw memunculkan `imsg rpc` (JSON-RPC melalui stdio). Tidak memerlukan daemo } ``` -- `channels.imessage.defaultAccount` opsional menimpa pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi. +- `channels.imessage.defaultAccount` opsional menggantikan pemilihan akun default saat cocok dengan id akun yang dikonfigurasi. - Memerlukan Full Disk Access ke DB Messages. -- Lebih baik gunakan target `chat_id:`. Gunakan `imsg chats --limit 20` untuk mencantumkan chat. -- `cliPath` dapat menunjuk ke wrapper SSH; setel `remoteHost` (`host` atau `user@host`) untuk pengambilan lampiran SCP. +- Utamakan target `chat_id:`. Gunakan `imsg chats --limit 20` untuk melihat daftar chat. +- `cliPath` dapat menunjuk ke wrapper SSH; atur `remoteHost` (`host` atau `user@host`) untuk pengambilan lampiran SCP. - `attachmentRoots` dan `remoteAttachmentRoots` membatasi path lampiran masuk (default: `/Users/*/Library/Messages/Attachments`). -- SCP menggunakan pemeriksaan host-key ketat, jadi pastikan host key relay sudah ada di `~/.ssh/known_hosts`. -- `channels.imessage.configWrites`: izinkan atau tolak penulisan konfigurasi yang diprakarsai iMessage. -- Entri `bindings[]` tingkat atas dengan `type: "acp"` dapat mengikat percakapan iMessage ke sesi ACP persisten. Gunakan handle yang dinormalisasi atau target chat eksplisit (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) dalam `match.peer.id`. Semantik field bersama: [ACP Agents](/id/tools/acp-agents#channel-specific-settings). +- SCP menggunakan strict host-key checking, jadi pastikan host key relay sudah ada di `~/.ssh/known_hosts`. +- `channels.imessage.configWrites`: izinkan atau tolak penulisan config yang dipicu iMessage. +- Entri `bindings[]` tingkat atas dengan `type: "acp"` dapat mengikat percakapan iMessage ke sesi ACP persisten. Gunakan handle yang dinormalisasi atau target chat eksplisit (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) di `match.peer.id`. Semantik field bersama: [ACP Agents](/id/tools/acp-agents#channel-specific-settings). @@ -621,7 +621,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix didukung ekstensi dan dikonfigurasi di bawah `channels.matrix`. +Matrix didukung extension dan dikonfigurasi di bawah `channels.matrix`. ```json5 { @@ -652,23 +652,23 @@ Matrix didukung ekstensi dan dikonfigurasi di bawah `channels.matrix`. ``` - Auth token menggunakan `accessToken`; auth password menggunakan `userId` + `password`. -- `channels.matrix.proxy` merutekan lalu lintas HTTP Matrix melalui proxy HTTP(S) eksplisit. Akun bernama dapat menimpanya dengan `channels.matrix.accounts..proxy`. -- `channels.matrix.allowPrivateNetwork` mengizinkan homeserver privat/internal. `proxy` dan `allowPrivateNetwork` adalah kontrol yang independen. -- `channels.matrix.defaultAccount` memilih akun yang diutamakan dalam pengaturan multi-akun. -- `channels.matrix.execApprovals`: pengiriman persetujuan exec native Matrix dan otorisasi approver. - - `enabled`: `true`, `false`, atau `"auto"` (default). Dalam mode auto, persetujuan exec aktif saat approver dapat di-resolve dari `approvers` atau `commands.ownerAllowFrom`. +- `channels.matrix.proxy` merutekan traffic HTTP Matrix melalui proxy HTTP(S) eksplisit. Akun bernama dapat meng-override-nya dengan `channels.matrix.accounts..proxy`. +- `channels.matrix.allowPrivateNetwork` mengizinkan homeserver private/internal. `proxy` dan `allowPrivateNetwork` adalah kontrol yang independen. +- `channels.matrix.defaultAccount` memilih akun yang diprioritaskan dalam setup multi-account. +- `channels.matrix.execApprovals`: pengiriman approval exec native Matrix dan otorisasi approver. + - `enabled`: `true`, `false`, atau `"auto"` (default). Dalam mode auto, approval exec aktif ketika approver dapat di-resolve dari `approvers` atau `commands.ownerAllowFrom`. - `approvers`: ID pengguna Matrix (mis. `@owner:example.org`) yang diizinkan menyetujui permintaan exec. - - `agentFilter`: allowlist ID agen opsional. Hilangkan untuk meneruskan persetujuan bagi semua agen. + - `agentFilter`: allowlist ID agent opsional. Hilangkan untuk meneruskan approval untuk semua agent. - `sessionFilter`: pola kunci sesi opsional (substring atau regex). - - `target`: tempat mengirim prompt persetujuan. `"dm"` (default), `"channel"` (room asal), atau `"both"`. - - Override per-akun: `channels.matrix.accounts..execApprovals`. -- `channels.matrix.dm.sessionScope` mengontrol bagaimana DM Matrix dikelompokkan ke dalam sesi: `per-user` (default) dibagikan berdasarkan peer yang dirutekan, sementara `per-room` mengisolasi setiap room DM. -- Probe status Matrix dan pencarian direktori live menggunakan kebijakan proxy yang sama seperti lalu lintas runtime. -- Konfigurasi Matrix lengkap, aturan penargetan, dan contoh setup didokumentasikan di [Matrix](/id/channels/matrix). + - `target`: tempat mengirim prompt approval. `"dm"` (default), `"channel"` (room asal), atau `"both"`. + - Override per-account: `channels.matrix.accounts..execApprovals`. +- `channels.matrix.dm.sessionScope` mengontrol bagaimana DM Matrix dikelompokkan ke dalam sesi: `per-user` (default) dibagikan menurut peer yang dirutekan, sedangkan `per-room` mengisolasi setiap room DM. +- Probe status Matrix dan pencarian direktori live menggunakan kebijakan proxy yang sama dengan traffic runtime. +- Konfigurasi Matrix lengkap, aturan targeting, dan contoh setup didokumentasikan di [Matrix](/id/channels/matrix). ### Microsoft Teams -Microsoft Teams didukung ekstensi dan dikonfigurasi di bawah `channels.msteams`. +Microsoft Teams didukung extension dan dikonfigurasi di bawah `channels.msteams`. ```json5 { @@ -676,7 +676,7 @@ Microsoft Teams didukung ekstensi dan dikonfigurasi di bawah `channels.msteams`. msteams: { enabled: true, configWrites: true, - // appId, appPassword, tenantId, webhook, kebijakan tim/channel: + // appId, appPassword, tenantId, webhook, kebijakan team/channel: // lihat /channels/msteams }, }, @@ -684,11 +684,11 @@ Microsoft Teams didukung ekstensi dan dikonfigurasi di bawah `channels.msteams`. ``` - Jalur kunci inti yang dicakup di sini: `channels.msteams`, `channels.msteams.configWrites`. -- Konfigurasi Teams lengkap (kredensial, webhook, kebijakan DM/grup, override per-tim/per-channel) didokumentasikan di [Microsoft Teams](/id/channels/msteams). +- Config Teams lengkap (kredensial, webhook, kebijakan DM/grup, override per-team/per-channel) didokumentasikan di [Microsoft Teams](/id/channels/msteams). ### IRC -IRC didukung ekstensi dan dikonfigurasi di bawah `channels.irc`. +IRC didukung extension dan dikonfigurasi di bawah `channels.irc`. ```json5 { @@ -710,10 +710,10 @@ IRC didukung ekstensi dan dikonfigurasi di bawah `channels.irc`. ``` - Jalur kunci inti yang dicakup di sini: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. -- `channels.irc.defaultAccount` opsional menimpa pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi. -- Konfigurasi channel IRC lengkap (host/port/TLS/channel/allowlist/gating mention) didokumentasikan di [IRC](/id/channels/irc). +- `channels.irc.defaultAccount` opsional menggantikan pemilihan akun default saat cocok dengan id akun yang dikonfigurasi. +- Konfigurasi channel IRC lengkap (host/port/TLS/channel/allowlist/mention gating) didokumentasikan di [IRC](/id/channels/irc). -### Multi-akun (semua channel) +### Multi-account (semua channel) Jalankan beberapa akun per channel (masing-masing dengan `accountId` sendiri): @@ -738,26 +738,26 @@ Jalankan beberapa akun per channel (masing-masing dengan `accountId` sendiri): - `default` digunakan saat `accountId` dihilangkan (CLI + routing). - Token env hanya berlaku untuk akun **default**. -- Pengaturan channel dasar berlaku untuk semua akun kecuali ditimpa per akun. -- Gunakan `bindings[].match.accountId` untuk merutekan setiap akun ke agen yang berbeda. -- Jika Anda menambahkan akun non-default melalui `openclaw channels add` (atau onboarding channel) saat masih menggunakan konfigurasi channel tingkat atas satu akun, OpenClaw terlebih dahulu mempromosikan nilai satu akun tingkat atas yang bersifat account-scoped ke dalam peta akun channel agar akun asli tetap berfungsi. Sebagian besar channel memindahkannya ke `channels..accounts.default`; Matrix dapat mempertahankan target bernama/default yang cocok yang sudah ada. -- Binding channel-only yang ada (tanpa `accountId`) tetap cocok dengan akun default; binding yang account-scoped tetap opsional. -- `openclaw doctor --fix` juga memperbaiki bentuk campuran dengan memindahkan nilai satu akun tingkat atas yang account-scoped ke akun yang dipromosikan dan dipilih untuk channel tersebut. Sebagian besar channel menggunakan `accounts.default`; Matrix dapat mempertahankan target bernama/default yang cocok yang sudah ada. +- Pengaturan channel dasar berlaku untuk semua akun kecuali dioverride per-account. +- Gunakan `bindings[].match.accountId` untuk merutekan setiap akun ke agent yang berbeda. +- Jika Anda menambahkan akun non-default melalui `openclaw channels add` (atau onboarding channel) saat masih berada pada config channel tingkat atas single-account, OpenClaw terlebih dahulu mempromosikan nilai single-account tingkat atas yang bersifat account-scoped ke peta akun channel agar akun asli tetap berfungsi. Sebagian besar channel memindahkannya ke `channels..accounts.default`; Matrix dapat mempertahankan target bernama/default yang cocok. +- Binding channel-only yang sudah ada (tanpa `accountId`) tetap cocok dengan akun default; binding account-scoped tetap opsional. +- `openclaw doctor --fix` juga memperbaiki bentuk campuran dengan memindahkan nilai single-account tingkat atas yang account-scoped ke akun hasil promosi yang dipilih untuk channel tersebut. Sebagian besar channel menggunakan `accounts.default`; Matrix dapat mempertahankan target bernama/default yang cocok. -### Channel ekstensi lainnya +### Channel extension lainnya -Banyak channel ekstensi dikonfigurasi sebagai `channels.` dan didokumentasikan di halaman channel khusus masing-masing (misalnya Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat, dan Twitch). +Banyak channel extension dikonfigurasi sebagai `channels.` dan didokumentasikan di halaman channel khusus mereka (misalnya Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat, dan Twitch). Lihat indeks channel lengkap: [Channels](/id/channels). -### Gating mention chat grup +### Mention gating chat grup Pesan grup secara default **memerlukan mention** (mention metadata atau pola regex aman). Berlaku untuk chat grup WhatsApp, Telegram, Discord, Google Chat, dan iMessage. **Jenis mention:** - **Mention metadata**: @-mention native platform. Diabaikan dalam mode self-chat WhatsApp. -- **Pola teks**: pola regex aman dalam `agents.list[].groupChat.mentionPatterns`. Pola tidak valid dan pengulangan bersarang yang tidak aman diabaikan. -- Gating mention hanya diterapkan saat deteksi memungkinkan (mention native atau setidaknya satu pola). +- **Pola teks**: pola regex aman di `agents.list[].groupChat.mentionPatterns`. Pola tidak valid dan repetisi bertingkat yang tidak aman diabaikan. +- Mention gating hanya ditegakkan ketika deteksi memungkinkan (mention native atau setidaknya satu pola). ```json5 { @@ -770,7 +770,7 @@ Pesan grup secara default **memerlukan mention** (mention metadata atau pola reg } ``` -`messages.groupChat.historyLimit` menetapkan default global. Channel dapat menimpa dengan `channels..historyLimit` (atau per-akun). Setel `0` untuk menonaktifkan. +`messages.groupChat.historyLimit` menetapkan default global. Channel dapat meng-override dengan `channels..historyLimit` (atau per-account). Atur `0` untuk menonaktifkan. #### Batas riwayat DM @@ -793,7 +793,7 @@ Didukung: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `mst #### Mode self-chat -Sertakan nomor Anda sendiri dalam `allowFrom` untuk mengaktifkan mode self-chat (mengabaikan @-mention native, hanya merespons pola teks): +Masukkan nomor Anda sendiri ke `allowFrom` untuk mengaktifkan mode self-chat (mengabaikan @-mention native, hanya merespons pola teks): ```json5 { @@ -814,7 +814,7 @@ Sertakan nomor Anda sendiri dalam `allowFrom` untuk mengaktifkan mode self-chat } ``` -### Commands (penanganan perintah chat) +### Commands (penanganan chat command) ```json5 { @@ -835,24 +835,24 @@ Sertakan nomor Anda sendiri dalam `allowFrom` untuk mengaktifkan mode self-chat } ``` - + -- Perintah teks harus berupa pesan **mandiri** dengan awalan `/`. +- Text command harus berupa pesan **mandiri** dengan awalan `/`. - `native: "auto"` mengaktifkan perintah native untuk Discord/Telegram, membiarkan Slack nonaktif. - Override per channel: `channels.discord.commands.native` (bool atau `"auto"`). `false` menghapus perintah yang sebelumnya terdaftar. - `channels.telegram.customCommands` menambahkan entri menu bot Telegram tambahan. - `bash: true` mengaktifkan `! ` untuk shell host. Memerlukan `tools.elevated.enabled` dan pengirim ada di `tools.elevated.allowFrom.`. -- `config: true` mengaktifkan `/config` (membaca/menulis `openclaw.json`). Untuk klien gateway `chat.send`, penulisan `/config set|unset` persisten juga memerlukan `operator.admin`; `/config show` baca-saja tetap tersedia untuk klien operator dengan cakupan penulisan normal. -- `channels..configWrites` mengatur mutasi konfigurasi per channel (default: true). -- Untuk channel multi-akun, `channels..accounts..configWrites` juga mengatur penulisan yang menargetkan akun tersebut (misalnya `/allowlist --config --account ` atau `/config set channels..accounts....`). -- `allowFrom` bersifat per-provider. Saat disetel, ini adalah **satu-satunya** sumber otorisasi (allowlist/pairing channel dan `useAccessGroups` diabaikan). -- `useAccessGroups: false` memungkinkan perintah melewati kebijakan access-group saat `allowFrom` tidak disetel. +- `config: true` mengaktifkan `/config` (membaca/menulis `openclaw.json`). Untuk klien gateway `chat.send`, penulisan persisten `/config set|unset` juga memerlukan `operator.admin`; `/config show` yang read-only tetap tersedia untuk klien operator normal dengan cakupan write. +- `channels..configWrites` mengendalikan mutasi config per channel (default: true). +- Untuk channel multi-account, `channels..accounts..configWrites` juga mengendalikan penulisan yang menargetkan akun tersebut (misalnya `/allowlist --config --account ` atau `/config set channels..accounts....`). +- `allowFrom` bersifat per-provider. Saat diatur, ini adalah **satu-satunya** sumber otorisasi (allowlist/pairing channel dan `useAccessGroups` diabaikan). +- `useAccessGroups: false` memungkinkan command melewati kebijakan access-group ketika `allowFrom` tidak diatur. --- -## Default agen +## Default agent ### `agents.defaults.workspace` @@ -866,7 +866,7 @@ Default: `~/.openclaw/workspace`. ### `agents.defaults.repoRoot` -Root repositori opsional yang ditampilkan pada baris Runtime di system prompt. Jika tidak disetel, OpenClaw mendeteksi otomatis dengan berjalan ke atas dari workspace. +Root repositori opsional yang ditampilkan di baris Runtime pada system prompt. Jika tidak diatur, OpenClaw mendeteksi otomatis dengan menelusuri ke atas dari workspace. ```json5 { @@ -876,7 +876,7 @@ Root repositori opsional yang ditampilkan pada baris Runtime di system prompt. J ### `agents.defaults.skills` -Allowlist skill default opsional untuk agen yang tidak menetapkan +Allowlist skill default opsional untuk agent yang tidak menetapkan `agents.list[].skills`. ```json5 @@ -886,17 +886,16 @@ Allowlist skill default opsional untuk agen yang tidak menetapkan list: [ { id: "writer" }, // mewarisi github, weather { id: "docs", skills: ["docs-search"] }, // menggantikan default - { id: "locked-down", skills: [] }, // tanpa skills + { id: "locked-down", skills: [] }, // tanpa skill ], }, } ``` -- Hilangkan `agents.defaults.skills` untuk skills tak terbatas secara default. -- Hilangkan `agents.list[].skills` agar mewarisi default. -- Setel `agents.list[].skills: []` agar tanpa skills. -- Daftar `agents.list[].skills` yang tidak kosong adalah set final untuk agen tersebut; daftar itu - tidak digabungkan dengan default. +- Hilangkan `agents.defaults.skills` agar skill default tidak dibatasi. +- Hilangkan `agents.list[].skills` untuk mewarisi default. +- Atur `agents.list[].skills: []` untuk tanpa skill. +- Daftar `agents.list[].skills` yang tidak kosong adalah set final untuk agent tersebut; tidak digabung dengan default. ### `agents.defaults.skipBootstrap` @@ -908,9 +907,21 @@ Menonaktifkan pembuatan otomatis file bootstrap workspace (`AGENTS.md`, `SOUL.md } ``` +### `agents.defaults.contextInjection` + +Mengontrol kapan file bootstrap workspace disuntikkan ke system prompt. Default: `"always"`. + +- `"continuation-skip"`: giliran kelanjutan yang aman (setelah respons assistant selesai) melewati injeksi ulang bootstrap workspace, sehingga ukuran prompt berkurang. Jalankan heartbeat dan retry pasca-compaction tetap membangun ulang konteks. + +```json5 +{ + agents: { defaults: { contextInjection: "continuation-skip" } }, +} +``` + ### `agents.defaults.bootstrapMaxChars` -Jumlah karakter maksimum per file bootstrap workspace sebelum dipotong. Default: `20000`. +Karakter maksimum per file bootstrap workspace sebelum dipotong. Default: `20000`. ```json5 { @@ -920,7 +931,7 @@ Jumlah karakter maksimum per file bootstrap workspace sebelum dipotong. Default: ### `agents.defaults.bootstrapTotalMaxChars` -Jumlah karakter total maksimum yang diinjeksi di semua file bootstrap workspace. Default: `150000`. +Total karakter maksimum yang disuntikkan di seluruh file bootstrap workspace. Default: `150000`. ```json5 { @@ -930,12 +941,12 @@ Jumlah karakter total maksimum yang diinjeksi di semua file bootstrap workspace. ### `agents.defaults.bootstrapPromptTruncationWarning` -Mengontrol teks peringatan yang terlihat agen saat konteks bootstrap dipotong. +Mengontrol teks peringatan yang terlihat oleh agent saat konteks bootstrap dipotong. Default: `"once"`. -- `"off"`: jangan pernah menginjeksi teks peringatan ke system prompt. -- `"once"`: injeksikan peringatan sekali per signature pemotongan unik (disarankan). -- `"always"`: injeksikan peringatan di setiap eksekusi saat ada pemotongan. +- `"off"`: jangan pernah menyuntikkan teks peringatan ke system prompt. +- `"once"`: suntikkan peringatan sekali per signature pemotongan unik (direkomendasikan). +- `"always"`: suntikkan peringatan pada setiap eksekusi saat ada pemotongan. ```json5 { @@ -945,11 +956,11 @@ Default: `"once"`. ### `agents.defaults.imageMaxDimensionPx` -Ukuran piksel maksimum untuk sisi gambar terpanjang dalam blok gambar transkrip/tool sebelum panggilan provider. +Ukuran piksel maksimum untuk sisi gambar terpanjang pada blok gambar transkrip/tool sebelum pemanggilan provider. Default: `1200`. -Nilai lebih rendah biasanya mengurangi penggunaan vision-token dan ukuran payload permintaan untuk eksekusi yang banyak screenshot. -Nilai lebih tinggi mempertahankan lebih banyak detail visual. +Nilai yang lebih rendah biasanya mengurangi penggunaan vision-token dan ukuran payload permintaan untuk eksekusi yang banyak screenshot. +Nilai yang lebih tinggi mempertahankan detail visual lebih banyak. ```json5 { @@ -959,7 +970,7 @@ Nilai lebih tinggi mempertahankan lebih banyak detail visual. ### `agents.defaults.userTimezone` -Zona waktu untuk konteks system prompt (bukan cap waktu pesan). Menggunakan zona waktu host sebagai fallback. +Timezone untuk konteks system prompt (bukan timestamp pesan). Fallback ke timezone host. ```json5 { @@ -969,7 +980,7 @@ Zona waktu untuk konteks system prompt (bukan cap waktu pesan). Menggunakan zona ### `agents.defaults.timeFormat` -Format waktu dalam system prompt. Default: `auto` (preferensi OS). +Format waktu di system prompt. Default: `auto` (preferensi OS). ```json5 { @@ -1007,7 +1018,7 @@ Format waktu dalam system prompt. Default: `auto` (preferensi OS). primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // parameter provider default global + params: { cacheRetention: "long" }, // param provider default global pdfMaxBytesMb: 10, pdfMaxPages: 20, thinkingDefault: "low", @@ -1026,39 +1037,39 @@ Format waktu dalam system prompt. Default: `auto` (preferensi OS). - Bentuk string hanya menetapkan model primary. - Bentuk objek menetapkan primary plus model failover berurutan. - `imageModel`: menerima string (`"provider/model"`) atau objek (`{ primary, fallbacks }`). - - Digunakan oleh jalur tool `image` sebagai konfigurasi model vision. - - Juga digunakan sebagai perutean fallback saat model yang dipilih/default tidak dapat menerima input gambar. + - Digunakan oleh jalur tool `image` sebagai config model vision-nya. + - Juga digunakan sebagai routing fallback saat model yang dipilih/default tidak dapat menerima input gambar. - `imageGenerationModel`: menerima string (`"provider/model"`) atau objek (`{ primary, fallbacks }`). - - Digunakan oleh kapabilitas pembuatan gambar bersama dan permukaan tool/plugin mendatang yang menghasilkan gambar. + - Digunakan oleh kemampuan pembuatan gambar bersama dan setiap permukaan tool/plugin masa depan yang menghasilkan gambar. - Nilai umum: `google/gemini-3.1-flash-image-preview` untuk pembuatan gambar Gemini native, `fal/fal-ai/flux/dev` untuk fal, atau `openai/gpt-image-1` untuk OpenAI Images. - - Jika Anda memilih provider/model secara langsung, konfigurasikan juga auth/API key provider yang cocok (misalnya `GEMINI_API_KEY` atau `GOOGLE_API_KEY` untuk `google/*`, `OPENAI_API_KEY` untuk `openai/*`, `FAL_KEY` untuk `fal/*`). - - Jika dihilangkan, `image_generate` masih dapat menyimpulkan default provider yang didukung auth. Tool ini mencoba provider default saat ini terlebih dahulu, lalu provider pembuatan gambar terdaftar lainnya dalam urutan provider-id. + - Jika Anda memilih provider/model secara langsung, konfigurasikan juga auth/API key provider yang sesuai (misalnya `GEMINI_API_KEY` atau `GOOGLE_API_KEY` untuk `google/*`, `OPENAI_API_KEY` untuk `openai/*`, `FAL_KEY` untuk `fal/*`). + - Jika dihilangkan, `image_generate` tetap dapat menyimpulkan default provider yang memiliki auth. Ia mencoba provider default saat ini terlebih dahulu, lalu provider pembuatan gambar terdaftar lainnya dalam urutan provider-id. - `musicGenerationModel`: menerima string (`"provider/model"`) atau objek (`{ primary, fallbacks }`). - - Digunakan oleh kapabilitas pembuatan musik bersama dan tool bawaan `music_generate`. + - Digunakan oleh kemampuan pembuatan musik bersama dan tool bawaan `music_generate`. - Nilai umum: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview`, atau `minimax/music-2.5+`. - - Jika dihilangkan, `music_generate` masih dapat menyimpulkan default provider yang didukung auth. Tool ini mencoba provider default saat ini terlebih dahulu, lalu provider pembuatan musik terdaftar lainnya dalam urutan provider-id. - - Jika Anda memilih provider/model secara langsung, konfigurasikan juga auth/API key provider yang cocok. + - Jika dihilangkan, `music_generate` tetap dapat menyimpulkan default provider yang memiliki auth. Ia mencoba provider default saat ini terlebih dahulu, lalu provider pembuatan musik terdaftar lainnya dalam urutan provider-id. + - Jika Anda memilih provider/model secara langsung, konfigurasikan juga auth/API key provider yang sesuai. - `videoGenerationModel`: menerima string (`"provider/model"`) atau objek (`{ primary, fallbacks }`). - - Digunakan oleh kapabilitas pembuatan video bersama dan tool bawaan `video_generate`. + - Digunakan oleh kemampuan pembuatan video bersama dan tool bawaan `video_generate`. - Nilai umum: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash`, atau `qwen/wan2.7-r2v`. - - Jika dihilangkan, `video_generate` masih dapat menyimpulkan default provider yang didukung auth. Tool ini mencoba provider default saat ini terlebih dahulu, lalu provider pembuatan video terdaftar lainnya dalam urutan provider-id. - - Jika Anda memilih provider/model secara langsung, konfigurasikan juga auth/API key provider yang cocok. - - Provider pembuatan video Qwen bawaan saat ini mendukung hingga 1 video keluaran, 1 gambar input, 4 video input, durasi 10 detik, dan opsi tingkat provider `size`, `aspectRatio`, `resolution`, `audio`, dan `watermark`. + - Jika dihilangkan, `video_generate` tetap dapat menyimpulkan default provider yang memiliki auth. Ia mencoba provider default saat ini terlebih dahulu, lalu provider pembuatan video terdaftar lainnya dalam urutan provider-id. + - Jika Anda memilih provider/model secara langsung, konfigurasikan juga auth/API key provider yang sesuai. + - Provider pembuatan video Qwen bawaan saat ini mendukung hingga 1 video output, 1 gambar input, 4 video input, durasi 10 detik, serta opsi tingkat provider `size`, `aspectRatio`, `resolution`, `audio`, dan `watermark`. - `pdfModel`: menerima string (`"provider/model"`) atau objek (`{ primary, fallbacks }`). - - Digunakan oleh tool `pdf` untuk perutean model. - - Jika dihilangkan, tool PDF kembali ke `imageModel`, lalu ke model sesi/default yang di-resolve. -- `pdfMaxBytesMb`: batas ukuran PDF default untuk tool `pdf` saat `maxBytesMb` tidak diberikan pada saat pemanggilan. -- `pdfMaxPages`: jumlah halaman maksimum default yang dipertimbangkan oleh mode fallback ekstraksi dalam tool `pdf`. -- `verboseDefault`: level verbose default untuk agen. Nilai: `"off"`, `"on"`, `"full"`. Default: `"off"`. -- `elevatedDefault`: level output elevated default untuk agen. Nilai: `"off"`, `"on"`, `"ask"`, `"full"`. Default: `"on"`. -- `model.primary`: format `provider/model` (mis. `openai/gpt-5.4`). Jika Anda menghilangkan provider, OpenClaw mencoba alias terlebih dahulu, lalu kecocokan configured-provider unik untuk id model tersebut, dan baru setelah itu kembali ke provider default yang dikonfigurasi (perilaku kompatibilitas lama yang sudah deprecated, jadi lebih baik gunakan `provider/model` eksplisit). Jika provider itu tidak lagi mengekspos model default yang dikonfigurasi, OpenClaw kembali ke provider/model pertama yang dikonfigurasi alih-alih menampilkan default provider lama yang sudah dihapus. -- `models`: katalog model yang dikonfigurasi dan allowlist untuk `/model`. Setiap entri dapat menyertakan `alias` (shortcut) dan `params` (spesifik provider, misalnya `temperature`, `maxTokens`, `cacheRetention`, `context1m`). -- `params`: parameter provider default global yang diterapkan ke semua model. Setel di `agents.defaults.params` (mis. `{ cacheRetention: "long" }`). -- Urutan penggabungan `params` (konfigurasi): `agents.defaults.params` (dasar global) ditimpa oleh `agents.defaults.models["provider/model"].params` (per-model), lalu `agents.list[].params` (id agen yang cocok) menimpa per kunci. Lihat [Prompt Caching](/id/reference/prompt-caching) untuk detail. -- Penulis konfigurasi yang memutasi field ini (misalnya `/models set`, `/models set-image`, dan perintah tambah/hapus fallback) menyimpan bentuk objek kanonis dan mempertahankan daftar fallback yang ada bila memungkinkan. -- `maxConcurrent`: jumlah maksimum eksekusi agen paralel lintas sesi (setiap sesi tetap diserialkan). Default: 4. + - Digunakan oleh tool `pdf` untuk routing model. + - Jika dihilangkan, tool PDF fallback ke `imageModel`, lalu ke model sesi/default yang berhasil di-resolve. +- `pdfMaxBytesMb`: batas ukuran PDF default untuk tool `pdf` saat `maxBytesMb` tidak diberikan pada waktu pemanggilan. +- `pdfMaxPages`: jumlah halaman maksimum default yang dipertimbangkan oleh mode fallback ekstraksi di tool `pdf`. +- `verboseDefault`: level verbose default untuk agent. Nilai: `"off"`, `"on"`, `"full"`. Default: `"off"`. +- `elevatedDefault`: level output elevated default untuk agent. Nilai: `"off"`, `"on"`, `"ask"`, `"full"`. Default: `"on"`. +- `model.primary`: format `provider/model` (mis. `openai/gpt-5.4`). Jika Anda menghilangkan provider, OpenClaw mencoba alias terlebih dahulu, lalu kecocokan unik configured-provider untuk model id persis tersebut, dan baru setelah itu fallback ke provider default yang dikonfigurasi (perilaku kompatibilitas lama yang tidak dianjurkan, jadi utamakan `provider/model` eksplisit). Jika provider tersebut tidak lagi mengekspos model default yang dikonfigurasi, OpenClaw fallback ke provider/model terkonfigurasi pertama alih-alih menampilkan default provider lama yang sudah dihapus. +- `models`: katalog model yang dikonfigurasi dan allowlist untuk `/model`. Setiap entri dapat menyertakan `alias` (shortcut) dan `params` (khusus provider, misalnya `temperature`, `maxTokens`, `cacheRetention`, `context1m`). +- `params`: parameter provider default global yang diterapkan ke semua model. Diatur di `agents.defaults.params` (mis. `{ cacheRetention: "long" }`). +- Prioritas penggabungan `params` (config): `agents.defaults.params` (basis global) dioverride oleh `agents.defaults.models["provider/model"].params` (per-model), lalu `agents.list[].params` (id agent yang cocok) mengoverride berdasarkan key. Lihat [Prompt Caching](/id/reference/prompt-caching) untuk detail. +- Penulis config yang memutasi field ini (misalnya `/models set`, `/models set-image`, dan perintah tambah/hapus fallback) menyimpan bentuk objek kanonis dan mempertahankan daftar fallback yang ada bila memungkinkan. +- `maxConcurrent`: jumlah maksimum eksekusi agent paralel di seluruh sesi (setiap sesi tetap diserialisasi). Default: 4. -**Alias shorthand bawaan** (hanya berlaku saat model ada dalam `agents.defaults.models`): +**Singkatan alias bawaan** (hanya berlaku saat model ada di `agents.defaults.models`): | Alias | Model | | ------------------- | -------------------------------------- | @@ -1071,18 +1082,18 @@ Format waktu dalam system prompt. Default: `auto` (preferensi OS). | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -Alias yang Anda konfigurasi sendiri selalu menang atas default. +Alias yang Anda konfigurasi selalu menang atas default. -Model Z.AI GLM-4.x otomatis mengaktifkan mode thinking kecuali Anda menetapkan `--thinking off` atau mendefinisikan `agents.defaults.models["zai/"].params.thinking` sendiri. -Model Z.AI mengaktifkan `tool_stream` secara default untuk streaming panggilan tool. Setel `agents.defaults.models["zai/"].params.tool_stream` ke `false` untuk menonaktifkannya. -Model Anthropic Claude 4.6 menggunakan thinking `adaptive` secara default saat tidak ada level thinking eksplisit yang disetel. +Model Z.AI GLM-4.x otomatis mengaktifkan mode thinking kecuali Anda menetapkan `--thinking off` atau mendefinisikan sendiri `agents.defaults.models["zai/"].params.thinking`. +Model Z.AI mengaktifkan `tool_stream` secara default untuk streaming tool call. Atur `agents.defaults.models["zai/"].params.tool_stream` ke `false` untuk menonaktifkannya. +Model Anthropic Claude 4.6 secara default menggunakan thinking `adaptive` ketika tidak ada level thinking eksplisit yang ditetapkan. -- Sesi didukung saat `sessionArg` disetel. +- Sesi didukung saat `sessionArg` diatur. - Pass-through gambar didukung saat `imageArg` menerima path file. ### `agents.defaults.heartbeat` -Eksekusi heartbeat berkala. +Eksekusi heartbeat periodik. ```json5 { @@ -1092,13 +1103,13 @@ Eksekusi heartbeat berkala. every: "30m", // 0m menonaktifkan model: "openai/gpt-5.4-mini", includeReasoning: false, - lightContext: false, // default: false; true hanya mempertahankan HEARTBEAT.md dari file bootstrap workspace + lightContext: false, // default: false; true hanya menyimpan HEARTBEAT.md dari file bootstrap workspace isolatedSession: false, // default: false; true menjalankan setiap heartbeat dalam sesi baru (tanpa riwayat percakapan) session: "main", to: "+15555550123", directPolicy: "allow", // allow (default) | block target: "none", // default: none | opsi: last | whatsapp | telegram | discord | ... - prompt: "Read HEARTBEAT.md if it exists...", + prompt: "Baca HEARTBEAT.md jika ada...", ackMaxChars: 300, suppressToolErrorWarnings: false, }, @@ -1107,13 +1118,13 @@ Eksekusi heartbeat berkala. } ``` -- `every`: string durasi (ms/s/m/h). Default: `30m` (auth API-key) atau `1h` (auth OAuth). Setel ke `0m` untuk menonaktifkan. -- `suppressToolErrorWarnings`: saat true, menekan payload peringatan error tool selama eksekusi heartbeat. -- `directPolicy`: kebijakan pengiriman direct/DM. `allow` (default) mengizinkan pengiriman direct-target. `block` menekan pengiriman direct-target dan menghasilkan `reason=dm-blocked`. -- `lightContext`: saat true, eksekusi heartbeat menggunakan konteks bootstrap ringan dan hanya mempertahankan `HEARTBEAT.md` dari file bootstrap workspace. -- `isolatedSession`: saat true, setiap heartbeat dijalankan dalam sesi baru tanpa riwayat percakapan sebelumnya. Pola isolasi yang sama seperti cron `sessionTarget: "isolated"`. Mengurangi biaya token per-heartbeat dari ~100K menjadi ~2-5K token. -- Per-agen: setel `agents.list[].heartbeat`. Saat agen mana pun mendefinisikan `heartbeat`, **hanya agen tersebut** yang menjalankan heartbeat. -- Heartbeat menjalankan giliran agen penuh — interval yang lebih pendek akan menghabiskan lebih banyak token. +- `every`: string durasi (ms/s/m/h). Default: `30m` (auth API-key) atau `1h` (auth OAuth). Atur ke `0m` untuk menonaktifkan. +- `suppressToolErrorWarnings`: ketika true, menekan payload peringatan error tool selama eksekusi heartbeat. +- `directPolicy`: kebijakan pengiriman direct/DM. `allow` (default) mengizinkan pengiriman direct-target. `block` menekan pengiriman direct-target dan mengeluarkan `reason=dm-blocked`. +- `lightContext`: ketika true, eksekusi heartbeat menggunakan konteks bootstrap ringan dan hanya mempertahankan `HEARTBEAT.md` dari file bootstrap workspace. +- `isolatedSession`: ketika true, setiap heartbeat berjalan dalam sesi baru tanpa riwayat percakapan sebelumnya. Pola isolasi sama seperti cron `sessionTarget: "isolated"`. Mengurangi biaya token per-heartbeat dari ~100K menjadi ~2-5K token. +- Per-agent: atur `agents.list[].heartbeat`. Ketika ada agent yang mendefinisikan `heartbeat`, **hanya agent tersebut** yang menjalankan heartbeat. +- Heartbeat menjalankan giliran agent penuh — interval yang lebih pendek membakar lebih banyak token. ### `agents.defaults.compaction` @@ -1126,15 +1137,15 @@ Eksekusi heartbeat berkala. timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // digunakan saat identifierPolicy=custom + identifierInstructions: "Pertahankan deployment ID, ticket ID, dan pasangan host:port persis seperti aslinya.", // digunakan saat identifierPolicy=custom postCompactionSections: ["Session Startup", "Red Lines"], // [] menonaktifkan reinjeksi model: "openrouter/anthropic/claude-sonnet-4-6", // override model khusus compaction opsional notifyUser: true, // kirim pemberitahuan singkat saat compaction dimulai (default: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, - systemPrompt: "Session nearing compaction. Store durable memories now.", - prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.", + systemPrompt: "Sesi mendekati compaction. Simpan memori yang tahan lama sekarang.", + prompt: "Tulis catatan yang bertahan lama ke memory/YYYY-MM-DD.md; balas dengan token senyap persis NO_REPLY jika tidak ada yang perlu disimpan.", }, }, }, @@ -1143,13 +1154,13 @@ Eksekusi heartbeat berkala. ``` - `mode`: `default` atau `safeguard` (ringkasan bertahap untuk riwayat panjang). Lihat [Compaction](/id/concepts/compaction). -- `timeoutSeconds`: detik maksimum yang diizinkan untuk satu operasi compaction sebelum OpenClaw membatalkannya. Default: `900`. -- `identifierPolicy`: `strict` (default), `off`, atau `custom`. `strict` menambahkan panduan retensi identifier opak bawaan sebelum ringkasan compaction. -- `identifierInstructions`: teks pelestarian identifier kustom opsional yang digunakan saat `identifierPolicy=custom`. -- `postCompactionSections`: nama bagian H2/H3 AGENTS.md opsional yang diinjeksi ulang setelah compaction. Default ke `["Session Startup", "Red Lines"]`; setel `[]` untuk menonaktifkan reinjeksi. Saat tidak disetel atau secara eksplisit disetel ke pasangan default tersebut, heading lama `Every Session`/`Safety` juga diterima sebagai fallback legacy. -- `model`: override `provider/model-id` opsional hanya untuk ringkasan compaction. Gunakan ini saat sesi utama harus tetap menggunakan satu model tetapi ringkasan compaction harus berjalan di model lain; jika tidak disetel, compaction menggunakan model primary sesi. -- `notifyUser`: saat `true`, mengirim pemberitahuan singkat ke pengguna saat compaction dimulai (misalnya, "Compacting context..."). Dinonaktifkan secara default agar compaction tetap senyap. -- `memoryFlush`: giliran agentic senyap sebelum auto-compaction untuk menyimpan memori yang tahan lama. Dilewati saat workspace read-only. +- `timeoutSeconds`: maksimum detik yang diizinkan untuk satu operasi compaction sebelum OpenClaw membatalkannya. Default: `900`. +- `identifierPolicy`: `strict` (default), `off`, atau `custom`. `strict` menambahkan panduan bawaan untuk mempertahankan identifier opak selama ringkasan compaction. +- `identifierInstructions`: teks khusus opsional untuk mempertahankan identifier saat `identifierPolicy=custom`. +- `postCompactionSections`: nama bagian H2/H3 `AGENTS.md` opsional untuk diinjeksi ulang setelah compaction. Default ke `["Session Startup", "Red Lines"]`; atur `[]` untuk menonaktifkan reinjeksi. Ketika tidak diatur atau secara eksplisit diatur ke pasangan default tersebut, heading lama `Every Session`/`Safety` juga diterima sebagai fallback lama. +- `model`: override `provider/model-id` opsional khusus untuk ringkasan compaction. Gunakan ini ketika sesi utama harus tetap menggunakan satu model tetapi ringkasan compaction harus berjalan pada model lain; jika tidak diatur, compaction menggunakan model primary sesi. +- `notifyUser`: ketika `true`, mengirim pemberitahuan singkat ke pengguna saat compaction dimulai (misalnya, "Compacting context..."). Dinonaktifkan secara default agar compaction tetap senyap. +- `memoryFlush`: giliran agentic senyap sebelum auto-compaction untuk menyimpan memori yang tahan lama. Dilewati saat workspace bersifat read-only. ### `agents.defaults.contextPruning` @@ -1167,7 +1178,7 @@ Memangkas **hasil tool lama** dari konteks in-memory sebelum dikirim ke LLM. **T hardClearRatio: 0.5, minPrunableToolChars: 50000, softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 }, - hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" }, + hardClear: { enabled: true, placeholder: "[Konten hasil tool lama dibersihkan]" }, tools: { deny: ["browser", "canvas"] }, }, }, @@ -1177,25 +1188,25 @@ Memangkas **hasil tool lama** dari konteks in-memory sebelum dikirim ke LLM. **T -- `mode: "cache-ttl"` mengaktifkan pass pruning. -- `ttl` mengontrol seberapa sering pruning dapat dijalankan lagi (setelah sentuhan cache terakhir). -- Pruning pertama-tama melakukan soft-trim pada hasil tool yang terlalu besar, lalu hard-clear pada hasil tool yang lebih lama jika diperlukan. +- `mode: "cache-ttl"` mengaktifkan proses pruning. +- `ttl` mengontrol seberapa sering pruning dapat berjalan lagi (setelah sentuhan cache terakhir). +- Pruning terlebih dahulu melakukan soft-trim pada hasil tool yang terlalu besar, lalu hard-clear pada hasil tool lama jika diperlukan. -**Soft-trim** mempertahankan bagian awal + akhir dan menyisipkan `...` di tengah. +**Soft-trim** mempertahankan awal + akhir dan menyisipkan `...` di tengah. **Hard-clear** mengganti seluruh hasil tool dengan placeholder. Catatan: -- Blok gambar tidak pernah dipangkas/dihapus. -- Rasio berbasis karakter (perkiraan), bukan jumlah token yang tepat. -- Jika pesan asisten yang ada kurang dari `keepLastAssistants`, pruning dilewati. +- Blok gambar tidak pernah dipangkas/dibersihkan. +- Rasio berbasis karakter (perkiraan), bukan jumlah token yang presisi. +- Jika ada lebih sedikit dari `keepLastAssistants` pesan assistant, pruning dilewati. Lihat [Session Pruning](/id/concepts/session-pruning) untuk detail perilaku. -### Block streaming +### Streaming blok ```json5 { @@ -1212,10 +1223,10 @@ Lihat [Session Pruning](/id/concepts/session-pruning) untuk detail perilaku. ``` - Channel non-Telegram memerlukan `*.blockStreaming: true` eksplisit untuk mengaktifkan balasan blok. -- Override channel: `channels..blockStreamingCoalesce` (dan varian per-akun). Signal/Slack/Discord/Google Chat default `minChars: 1500`. -- `humanDelay`: jeda acak antar balasan blok. `natural` = 800–2500ms. Override per-agen: `agents.list[].humanDelay`. +- Override channel: `channels..blockStreamingCoalesce` (dan varian per-account). Signal/Slack/Discord/Google Chat default `minChars: 1500`. +- `humanDelay`: jeda acak antara balasan blok. `natural` = 800–2500 ms. Override per-agent: `agents.list[].humanDelay`. -Lihat [Streaming](/id/concepts/streaming) untuk perilaku + detail chunking. +Lihat [Streaming](/id/concepts/streaming) untuk detail perilaku + chunking. ### Indikator mengetik @@ -1230,7 +1241,7 @@ Lihat [Streaming](/id/concepts/streaming) untuk perilaku + detail chunking. } ``` -- Default: `instant` untuk chat langsung/mention, `message` untuk chat grup tanpa mention. +- Default: `instant` untuk chat langsung/mention, `message` untuk grup tanpa mention. - Override per-sesi: `session.typingMode`, `session.typingIntervalSeconds`. Lihat [Typing Indicators](/id/concepts/typing-indicators). @@ -1239,7 +1250,7 @@ Lihat [Typing Indicators](/id/concepts/typing-indicators). ### `agents.defaults.sandbox` -Sandbox opsional untuk agen tersemat. Lihat [Sandboxing](/id/gateway/sandboxing) untuk panduan lengkap. +Sandboxing opsional untuk embedded agent. Lihat [Sandboxing](/id/gateway/sandboxing) untuk panduan lengkap. ```json5 { @@ -1285,7 +1296,7 @@ Sandbox opsional untuk agen tersemat. Lihat [Sandboxing](/id/gateway/sandboxing) identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // SecretRefs / konten inline juga didukung: + // SecretRef / konten inline juga didukung: // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" }, // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" }, // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" }, @@ -1342,46 +1353,46 @@ Sandbox opsional untuk agen tersemat. Lihat [Sandboxing](/id/gateway/sandboxing) - `ssh`: runtime remote berbasis SSH generik - `openshell`: runtime OpenShell -Saat `backend: "openshell"` dipilih, pengaturan khusus runtime dipindahkan ke +Ketika `backend: "openshell"` dipilih, pengaturan khusus runtime dipindahkan ke `plugins.entries.openshell.config`. -**Konfigurasi backend SSH:** +**Config backend SSH:** - `target`: target SSH dalam bentuk `user@host[:port]` - `command`: perintah klien SSH (default: `ssh`) - `workspaceRoot`: root remote absolut yang digunakan untuk workspace per-scope -- `identityFile` / `certificateFile` / `knownHostsFile`: file lokal yang ada yang diteruskan ke OpenSSH -- `identityData` / `certificateData` / `knownHostsData`: konten inline atau SecretRef yang dimaterialisasikan OpenClaw ke file temp saat runtime -- `strictHostKeyChecking` / `updateHostKeys`: kenop kebijakan host-key OpenSSH +- `identityFile` / `certificateFile` / `knownHostsFile`: file lokal yang sudah ada dan diteruskan ke OpenSSH +- `identityData` / `certificateData` / `knownHostsData`: konten inline atau SecretRef yang dimaterialisasi OpenClaw menjadi file sementara saat runtime +- `strictHostKeyChecking` / `updateHostKeys`: knob kebijakan host-key OpenSSH **Prioritas auth SSH:** -- `identityData` mengalahkan `identityFile` -- `certificateData` mengalahkan `certificateFile` -- `knownHostsData` mengalahkan `knownHostsFile` -- Nilai `*Data` berbasis SecretRef di-resolve dari snapshot runtime secrets aktif sebelum sesi sandbox dimulai +- `identityData` menang atas `identityFile` +- `certificateData` menang atas `certificateFile` +- `knownHostsData` menang atas `knownHostsFile` +- Nilai `*Data` berbasis SecretRef di-resolve dari snapshot runtime secret aktif sebelum sesi sandbox dimulai **Perilaku backend SSH:** -- menanam workspace remote sekali setelah create atau recreate -- lalu mempertahankan workspace SSH remote sebagai yang kanonis -- merutekan `exec`, file tools, dan path media melalui SSH +- melakukan seed workspace remote sekali setelah pembuatan atau pembuatan ulang +- lalu mempertahankan workspace SSH remote sebagai kanonis +- merutekan `exec`, file tool, dan path media melalui SSH - tidak menyinkronkan perubahan remote kembali ke host secara otomatis -- tidak mendukung kontainer browser sandbox +- tidak mendukung container browser sandbox **Akses workspace:** - `none`: workspace sandbox per-scope di bawah `~/.openclaw/sandboxes` -- `ro`: workspace sandbox di `/workspace`, workspace agen dimount read-only di `/agent` -- `rw`: workspace agen dimount read/write di `/workspace` +- `ro`: workspace sandbox di `/workspace`, workspace agent di-mount read-only di `/agent` +- `rw`: workspace agent di-mount baca/tulis di `/workspace` **Scope:** -- `session`: kontainer + workspace per-sesi -- `agent`: satu kontainer + workspace per agen (default) -- `shared`: kontainer dan workspace bersama (tanpa isolasi lintas sesi) +- `session`: container + workspace per-sesi +- `agent`: satu container + workspace per-agent (default) +- `shared`: container dan workspace bersama (tanpa isolasi lintas sesi) -**Konfigurasi plugin OpenShell:** +**Config plugin OpenShell:** ```json5 { @@ -1409,30 +1420,30 @@ Saat `backend: "openshell"` dipilih, pengaturan khusus runtime dipindahkan ke **Mode OpenShell:** -- `mirror`: tanam remote dari lokal sebelum exec, sinkronkan kembali setelah exec; workspace lokal tetap kanonis -- `remote`: tanam remote sekali saat sandbox dibuat, lalu pertahankan workspace remote sebagai yang kanonis +- `mirror`: seed remote dari lokal sebelum exec, sinkronkan kembali setelah exec; workspace lokal tetap kanonis +- `remote`: seed remote sekali saat sandbox dibuat, lalu pertahankan workspace remote sebagai kanonis Dalam mode `remote`, edit host-lokal yang dibuat di luar OpenClaw tidak disinkronkan ke sandbox secara otomatis setelah langkah seed. -Transport-nya adalah SSH ke sandbox OpenShell, tetapi plugin memiliki siklus hidup sandbox dan sinkronisasi mirror opsional. +Transport menggunakan SSH ke sandbox OpenShell, tetapi plugin yang memiliki lifecycle sandbox dan sinkronisasi mirror opsional. -**`setupCommand`** berjalan sekali setelah pembuatan kontainer (melalui `sh -lc`). Memerlukan egress jaringan, root yang dapat ditulis, pengguna root. +**`setupCommand`** berjalan sekali setelah pembuatan container (melalui `sh -lc`). Memerlukan network egress, root yang dapat ditulis, dan user root. -**Kontainer default ke `network: "none"`** — setel ke `"bridge"` (atau jaringan bridge kustom) jika agen memerlukan akses keluar. -`"host"` diblokir. `"container:"` diblokir secara default kecuali Anda secara eksplisit menetapkan +**Container default ke `network: "none"`** — atur ke `"bridge"` (atau jaringan bridge kustom) jika agent memerlukan akses keluar. +`"host"` diblokir. `"container:"` diblokir secara default kecuali Anda secara eksplisit mengatur `sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (break-glass). -**Lampiran masuk** ditempatkan ke `media/inbound/*` dalam workspace aktif. +**Lampiran masuk** di-stage ke `media/inbound/*` di workspace aktif. -**`docker.binds`** me-mount direktori host tambahan; bind global dan per-agen digabungkan. +**`docker.binds`** me-mount direktori host tambahan; bind global dan per-agent digabungkan. -**Browser tersandbox** (`sandbox.browser.enabled`): Chromium + CDP dalam kontainer. URL noVNC diinjeksi ke system prompt. Tidak memerlukan `browser.enabled` di `openclaw.json`. -Akses pengamat noVNC menggunakan auth VNC secara default dan OpenClaw mengeluarkan URL token berdurasi singkat (alih-alih mengekspos kata sandi dalam URL bersama). +**Browser tersandbox** (`sandbox.browser.enabled`): Chromium + CDP di dalam container. URL noVNC disuntikkan ke system prompt. Tidak memerlukan `browser.enabled` di `openclaw.json`. +Akses pengamat noVNC menggunakan auth VNC secara default dan OpenClaw mengeluarkan URL token jangka pendek (bukan mengekspos password di URL bersama). -- `allowHostControl: false` (default) memblokir sesi tersandbox dari menargetkan browser host. -- `network` default ke `openclaw-sandbox-browser` (jaringan bridge khusus). Setel ke `bridge` hanya saat Anda secara eksplisit menginginkan konektivitas bridge global. -- `cdpSourceRange` secara opsional membatasi ingress CDP di tepi kontainer ke rentang CIDR (misalnya `172.21.0.1/32`). -- `sandbox.browser.binds` me-mount direktori host tambahan hanya ke kontainer browser sandbox. Saat disetel (termasuk `[]`), ini menggantikan `docker.binds` untuk kontainer browser. -- Default peluncuran didefinisikan di `scripts/sandbox-browser-entrypoint.sh` dan disetel untuk host kontainer: +- `allowHostControl: false` (default) memblokir sesi tersandbox agar tidak menargetkan browser host. +- `network` default ke `openclaw-sandbox-browser` (jaringan bridge khusus). Atur ke `bridge` hanya bila Anda memang ingin konektivitas bridge global. +- `cdpSourceRange` secara opsional membatasi ingress CDP di tepi container ke rentang CIDR (misalnya `172.21.0.1/32`). +- `sandbox.browser.binds` me-mount direktori host tambahan hanya ke container browser sandbox. Saat diatur (termasuk `[]`), ia menggantikan `docker.binds` untuk container browser. +- Default peluncuran didefinisikan di `scripts/sandbox-browser-entrypoint.sh` dan di-tune untuk host container: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1449,31 +1460,31 @@ Akses pengamat noVNC menggunakan auth VNC secara default dan OpenClaw mengeluark - `--renderer-process-limit=2` - `--no-zygote` - `--metrics-recording-only` - - `--disable-extensions` (aktif secara default) + - `--disable-extensions` (default diaktifkan) - `--disable-3d-apis`, `--disable-software-rasterizer`, dan `--disable-gpu` - aktif secara default dan dapat dinonaktifkan dengan - `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` jika penggunaan WebGL/3D memerlukannya. - - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` mengaktifkan kembali ekstensi jika alur kerja Anda + diaktifkan secara default dan dapat dinonaktifkan dengan + `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` jika penggunaan WebGL/3D membutuhkannya. + - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` mengaktifkan kembali extension jika alur kerja Anda bergantung padanya. - `--renderer-process-limit=2` dapat diubah dengan - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; setel `0` untuk menggunakan + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; atur `0` untuk menggunakan batas proses default Chromium. - plus `--no-sandbox` dan `--disable-setuid-sandbox` saat `noSandbox` diaktifkan. - - Default ini adalah baseline image kontainer; gunakan image browser kustom dengan entrypoint - kustom untuk mengubah default kontainer. + - Default adalah baseline image container; gunakan image browser kustom dengan + entrypoint kustom untuk mengubah default container. -Sandbox browser dan `sandbox.docker.binds` saat ini hanya mendukung Docker. +Browser sandboxing dan `sandbox.docker.binds` saat ini hanya untuk Docker. -Bangun image: +Build image: ```bash scripts/sandbox-setup.sh # image sandbox utama scripts/sandbox-browser-setup.sh # image browser opsional ``` -### `agents.list` (override per-agen) +### `agents.list` (override per-agent) ```json5 { @@ -1482,18 +1493,18 @@ scripts/sandbox-browser-setup.sh # image browser opsional { id: "main", default: true, - name: "Agen Utama", + name: "Agent Utama", workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", model: "anthropic/claude-opus-4-6", // atau { primary, fallbacks } - thinkingDefault: "high", // override level thinking per-agen - reasoningDefault: "on", // override visibilitas reasoning per-agen - fastModeDefault: false, // override fast mode per-agen - params: { cacheRetention: "none" }, // menimpa defaults.models params yang cocok per kunci - skills: ["docs-search"], // menggantikan agents.defaults.skills saat disetel + thinkingDefault: "high", // override level thinking per-agent + reasoningDefault: "on", // override visibilitas reasoning per-agent + fastModeDefault: false, // override fast mode per-agent + params: { cacheRetention: "none" }, // mengoverride matching defaults.models params berdasarkan key + skills: ["docs-search"], // menggantikan agents.defaults.skills saat diatur identity: { name: "Samantha", - theme: "helpful sloth", + theme: "sloth yang membantu", emoji: "🦥", avatar: "avatars/samantha.png", }, @@ -1521,26 +1532,26 @@ scripts/sandbox-browser-setup.sh # image browser opsional } ``` -- `id`: id agen stabil (wajib). -- `default`: saat beberapa disetel, yang pertama menang (peringatan dicatat). Jika tidak ada yang disetel, entri daftar pertama menjadi default. -- `model`: bentuk string hanya menimpa `primary`; bentuk objek `{ primary, fallbacks }` menimpa keduanya (`[]` menonaktifkan fallback global). Pekerjaan cron yang hanya menimpa `primary` tetap mewarisi fallback default kecuali Anda menetapkan `fallbacks: []`. -- `params`: stream params per-agen yang digabungkan di atas entri model terpilih dalam `agents.defaults.models`. Gunakan ini untuk override khusus agen seperti `cacheRetention`, `temperature`, atau `maxTokens` tanpa menduplikasi seluruh katalog model. -- `skills`: allowlist skill per-agen opsional. Jika dihilangkan, agen mewarisi `agents.defaults.skills` saat disetel; daftar eksplisit menggantikan default alih-alih digabungkan, dan `[]` berarti tanpa skills. -- `thinkingDefault`: level thinking default per-agen opsional (`off | minimal | low | medium | high | xhigh | adaptive`). Menimpa `agents.defaults.thinkingDefault` untuk agen ini saat tidak ada override per-pesan atau sesi. -- `reasoningDefault`: visibilitas reasoning default per-agen opsional (`on | off | stream`). Berlaku saat tidak ada override reasoning per-pesan atau sesi. -- `fastModeDefault`: default mode cepat per-agen opsional (`true | false`). Berlaku saat tidak ada override fast-mode per-pesan atau sesi. -- `runtime`: deskriptor runtime per-agen opsional. Gunakan `type: "acp"` dengan default `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) saat agen harus default ke sesi harness ACP. +- `id`: id agent stabil (wajib). +- `default`: saat ada beberapa yang diatur, yang pertama menang (peringatan dicatat). Jika tidak ada yang diatur, entri daftar pertama adalah default. +- `model`: bentuk string hanya mengoverride `primary`; bentuk objek `{ primary, fallbacks }` mengoverride keduanya (`[]` menonaktifkan fallback global). Cron job yang hanya mengoverride `primary` tetap mewarisi fallback default kecuali Anda menetapkan `fallbacks: []`. +- `params`: stream params per-agent yang digabungkan di atas entri model terpilih dalam `agents.defaults.models`. Gunakan ini untuk override khusus agent seperti `cacheRetention`, `temperature`, atau `maxTokens` tanpa menduplikasi seluruh katalog model. +- `skills`: allowlist skill per-agent opsional. Jika dihilangkan, agent mewarisi `agents.defaults.skills` bila diatur; daftar eksplisit menggantikan default alih-alih digabung, dan `[]` berarti tanpa skill. +- `thinkingDefault`: default level thinking per-agent opsional (`off | minimal | low | medium | high | xhigh | adaptive`). Mengoverride `agents.defaults.thinkingDefault` untuk agent ini saat tidak ada override per-pesan atau per-sesi. +- `reasoningDefault`: default visibilitas reasoning per-agent opsional (`on | off | stream`). Berlaku saat tidak ada override reasoning per-pesan atau per-sesi. +- `fastModeDefault`: default fast mode per-agent opsional (`true | false`). Berlaku saat tidak ada override fast-mode per-pesan atau per-sesi. +- `runtime`: deskriptor runtime per-agent opsional. Gunakan `type: "acp"` dengan default `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) saat agent harus default ke sesi harness ACP. - `identity.avatar`: path relatif workspace, URL `http(s)`, atau URI `data:`. - `identity` menurunkan default: `ackReaction` dari `emoji`, `mentionPatterns` dari `name`/`emoji`. -- `subagents.allowAgents`: allowlist id agen untuk `sessions_spawn` (`["*"]` = apa saja; default: hanya agen yang sama). -- Pengaman pewarisan sandbox: jika sesi peminta disandbox, `sessions_spawn` menolak target yang akan berjalan tanpa sandbox. -- `subagents.requireAgentId`: saat true, blokir pemanggilan `sessions_spawn` yang menghilangkan `agentId` (memaksa pemilihan profil eksplisit; default: false). +- `subagents.allowAgents`: allowlist id agent untuk `sessions_spawn` (`["*"]` = apa saja; default: hanya agent yang sama). +- Guard pewarisan sandbox: jika sesi peminta disandbox, `sessions_spawn` menolak target yang akan berjalan tanpa sandbox. +- `subagents.requireAgentId`: ketika true, blokir pemanggilan `sessions_spawn` yang menghilangkan `agentId` (memaksa pemilihan profil eksplisit; default: false). --- -## Perutean multi-agen +## Routing multi-agent -Jalankan beberapa agen terisolasi di dalam satu Gateway. Lihat [Multi-Agent](/id/concepts/multi-agent). +Jalankan beberapa agent terisolasi di dalam satu Gateway. Lihat [Multi-Agent](/id/concepts/multi-agent). ```json5 { @@ -1557,29 +1568,29 @@ Jalankan beberapa agen terisolasi di dalam satu Gateway. Lihat [Multi-Agent](/id } ``` -### Field pencocokan binding +### Field kecocokan binding -- `type` (opsional): `route` untuk perutean normal (type yang hilang default ke route), `acp` untuk binding percakapan ACP persisten. +- `type` (opsional): `route` untuk routing normal (type yang hilang default ke route), `acp` untuk binding percakapan ACP persisten. - `match.channel` (wajib) - `match.accountId` (opsional; `*` = akun apa saja; dihilangkan = akun default) - `match.peer` (opsional; `{ kind: direct|group|channel, id }`) -- `match.guildId` / `match.teamId` (opsional; spesifik channel) +- `match.guildId` / `match.teamId` (opsional; khusus channel) - `acp` (opsional; hanya untuk entri `type: "acp"`): `{ mode, label, cwd, backend }` -**Urutan pencocokan deterministik:** +**Urutan kecocokan deterministik:** 1. `match.peer` 2. `match.guildId` 3. `match.teamId` -4. `match.accountId` (tepat, tanpa peer/guild/team) +4. `match.accountId` (persis, tanpa peer/guild/team) 5. `match.accountId: "*"` (cakupan seluruh channel) -6. Agen default +6. Agent default -Di dalam setiap tier, entri `bindings` pertama yang cocok yang menang. +Di dalam setiap tingkat, entri `bindings` pertama yang cocok akan menang. -Untuk entri `type: "acp"`, OpenClaw me-resolve berdasarkan identitas percakapan yang tepat (`match.channel` + akun + `match.peer.id`) dan tidak menggunakan urutan tier binding route di atas. +Untuk entri `type: "acp"`, OpenClaw me-resolve berdasarkan identitas percakapan yang persis (`match.channel` + akun + `match.peer.id`) dan tidak menggunakan urutan tingkat route binding di atas. -### Profil akses per-agen +### Profil akses per-agent @@ -1678,7 +1689,7 @@ Lihat [Multi-Agent Sandbox & Tools](/id/tools/multi-agent-sandbox-tools) untuk d --- -## Session +## Sesi ```json5 { @@ -1708,14 +1719,14 @@ Lihat [Multi-Agent Sandbox & Tools](/id/tools/multi-agent-sandbox-tools) untuk d rotateBytes: "10mb", resetArchiveRetention: "30d", // durasi atau false maxDiskBytes: "500mb", // hard budget opsional - highWaterBytes: "400mb", // target pembersihan opsional + highWaterBytes: "400mb", // target cleanup opsional }, threadBindings: { enabled: true, idleHours: 24, // default auto-unfocus karena tidak aktif dalam jam (`0` menonaktifkan) maxAgeHours: 0, // default usia maksimum keras dalam jam (`0` menonaktifkan) }, - mainKey: "main", // legacy (runtime selalu menggunakan "main") + mainKey: "main", // lama (runtime selalu menggunakan "main") agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -1728,40 +1739,40 @@ Lihat [Multi-Agent Sandbox & Tools](/id/tools/multi-agent-sandbox-tools) untuk d - **`scope`**: strategi pengelompokan sesi dasar untuk konteks chat grup. - - `per-sender` (default): setiap pengirim mendapat sesi terisolasi dalam konteks channel. - - `global`: semua peserta dalam konteks channel berbagi satu sesi (gunakan hanya saat konteks bersama memang diinginkan). + - `per-sender` (default): setiap pengirim mendapat sesi terisolasi di dalam konteks channel. + - `global`: semua peserta dalam konteks channel berbagi satu sesi (gunakan hanya bila konteks bersama memang diinginkan). - **`dmScope`**: bagaimana DM dikelompokkan. - `main`: semua DM berbagi sesi utama. - - `per-peer`: isolasi berdasarkan id pengirim lintas channel. - - `per-channel-peer`: isolasi per channel + pengirim (disarankan untuk inbox multi-pengguna). - - `per-account-channel-peer`: isolasi per akun + channel + pengirim (disarankan untuk multi-akun). -- **`identityLinks`**: petakan id kanonis ke peer berawalan provider untuk berbagi sesi lintas channel. -- **`reset`**: kebijakan reset utama. `daily` mereset pada `atHour` waktu lokal; `idle` mereset setelah `idleMinutes`. Saat keduanya dikonfigurasi, yang kedaluwarsa lebih dulu yang menang. + - `per-peer`: diisolasi berdasarkan id pengirim lintas channel. + - `per-channel-peer`: diisolasi per channel + pengirim (direkomendasikan untuk inbox multi-pengguna). + - `per-account-channel-peer`: diisolasi per akun + channel + pengirim (direkomendasikan untuk multi-account). +- **`identityLinks`**: peta id kanonis ke peer berawalan provider untuk berbagi sesi lintas channel. +- **`reset`**: kebijakan reset utama. `daily` melakukan reset pada `atHour` waktu lokal; `idle` melakukan reset setelah `idleMinutes`. Saat keduanya dikonfigurasi, yang kedaluwarsa lebih dulu akan menang. - **`resetByType`**: override per-jenis (`direct`, `group`, `thread`). `dm` lama diterima sebagai alias untuk `direct`. -- **`parentForkMaxTokens`**: `totalTokens` sesi parent maksimum yang diizinkan saat membuat sesi thread bercabang (default `100000`). +- **`parentForkMaxTokens`**: jumlah maksimum `totalTokens` sesi induk yang diizinkan saat membuat sesi thread bercabang (default `100000`). - Jika `totalTokens` parent di atas nilai ini, OpenClaw memulai sesi thread baru alih-alih mewarisi riwayat transkrip parent. - - Setel `0` untuk menonaktifkan pengaman ini dan selalu mengizinkan fork parent. -- **`mainKey`**: field legacy. Runtime kini selalu menggunakan `"main"` untuk bucket chat langsung utama. -- **`agentToAgent.maxPingPongTurns`**: jumlah maksimum giliran balasan antar agen selama pertukaran agent-to-agent (integer, rentang: `0`–`5`). `0` menonaktifkan rantai ping-pong. -- **`sendPolicy`**: cocokkan berdasarkan `channel`, `chatType` (`direct|group|channel`, dengan alias lama `dm`), `keyPrefix`, atau `rawKeyPrefix`. Penolakan pertama yang menang. -- **`maintenance`**: kontrol pembersihan + retensi penyimpanan sesi. - - `mode`: `warn` hanya mengeluarkan peringatan; `enforce` menerapkan pembersihan. + - Atur `0` untuk menonaktifkan guard ini dan selalu mengizinkan fork parent. +- **`mainKey`**: field lama. Runtime sekarang selalu menggunakan `"main"` untuk bucket chat langsung utama. +- **`agentToAgent.maxPingPongTurns`**: jumlah maksimum giliran balas-balik antar agent selama pertukaran agent-ke-agent (integer, rentang: `0`–`5`). `0` menonaktifkan rantai ping-pong. +- **`sendPolicy`**: cocokkan berdasarkan `channel`, `chatType` (`direct|group|channel`, dengan alias lama `dm`), `keyPrefix`, atau `rawKeyPrefix`. Deny pertama menang. +- **`maintenance`**: kontrol cleanup + retensi session-store. + - `mode`: `warn` hanya mengeluarkan peringatan; `enforce` menerapkan cleanup. - `pruneAfter`: batas usia untuk entri basi (default `30d`). - - `maxEntries`: jumlah maksimum entri dalam `sessions.json` (default `500`). + - `maxEntries`: jumlah maksimum entri di `sessions.json` (default `500`). - `rotateBytes`: rotasi `sessions.json` saat melebihi ukuran ini (default `10mb`). - - `resetArchiveRetention`: retensi untuk arsip transkrip `*.reset.`. Default ke `pruneAfter`; setel `false` untuk menonaktifkan. - - `maxDiskBytes`: anggaran disk direktori sesi opsional. Dalam mode `warn` akan mencatat peringatan; dalam mode `enforce` akan menghapus artefak/sesi tertua terlebih dahulu. - - `highWaterBytes`: target opsional setelah pembersihan anggaran. Default ke `80%` dari `maxDiskBytes`. + - `resetArchiveRetention`: retensi untuk arsip transkrip `*.reset.`. Default ke `pruneAfter`; atur `false` untuk menonaktifkan. + - `maxDiskBytes`: budget disk direktori sesi opsional. Dalam mode `warn` akan mencatat peringatan; dalam mode `enforce` akan menghapus artefak/sesi paling lama terlebih dahulu. + - `highWaterBytes`: target opsional setelah cleanup budget. Default ke `80%` dari `maxDiskBytes`. - **`threadBindings`**: default global untuk fitur sesi terikat thread. - - `enabled`: sakelar default utama (provider dapat menimpa; Discord menggunakan `channels.discord.threadBindings.enabled`) - - `idleHours`: default auto-unfocus karena tidak aktif dalam jam (`0` menonaktifkan; provider dapat menimpa) - - `maxAgeHours`: default usia maksimum keras dalam jam (`0` menonaktifkan; provider dapat menimpa) + - `enabled`: sakelar default utama (provider dapat mengoverride; Discord menggunakan `channels.discord.threadBindings.enabled`) + - `idleHours`: default auto-unfocus karena tidak aktif dalam jam (`0` menonaktifkan; provider dapat mengoverride) + - `maxAgeHours`: default usia maksimum keras dalam jam (`0` menonaktifkan; provider dapat mengoverride) --- -## Messages +## Pesan ```json5 { @@ -1791,38 +1802,38 @@ Lihat [Multi-Agent Sandbox & Tools](/id/tools/multi-agent-sandbox-tools) untuk d } ``` -### Prefix respons +### Prefiks respons -Override per channel/akun: `channels..responsePrefix`, `channels..accounts..responsePrefix`. +Override per-channel/account: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -Resolusi (yang paling spesifik menang): akun → channel → global. `""` menonaktifkan dan menghentikan kaskade. `"auto"` menurunkan `[{identity.name}]`. +Resolusi (yang paling spesifik menang): account → channel → global. `""` menonaktifkan dan menghentikan cascade. `"auto"` menurunkan `[{identity.name}]`. **Variabel template:** | Variabel | Deskripsi | Contoh | | ----------------- | ---------------------- | --------------------------- | -| `{model}` | Nama model pendek | `claude-opus-4-6` | +| `{model}` | Nama model singkat | `claude-opus-4-6` | | `{modelFull}` | Identifier model penuh | `anthropic/claude-opus-4-6` | | `{provider}` | Nama provider | `anthropic` | | `{thinkingLevel}` | Level thinking saat ini | `high`, `low`, `off` | -| `{identity.name}` | Nama identitas agen | (sama seperti `"auto"`) | +| `{identity.name}` | Nama identitas agent | (sama seperti `"auto"`) | Variabel tidak peka huruf besar/kecil. `{think}` adalah alias untuk `{thinkingLevel}`. ### Reaksi ack -- Default ke `identity.emoji` agen aktif, atau `"👀"` jika tidak ada. Setel `""` untuk menonaktifkan. -- Override per channel: `channels..ackReaction`, `channels..accounts..ackReaction`. -- Urutan resolusi: akun → channel → `messages.ackReaction` → fallback identity. +- Default ke `identity.emoji` agent aktif, jika tidak `"👀"`. Atur `""` untuk menonaktifkan. +- Override per-channel: `channels..ackReaction`, `channels..accounts..ackReaction`. +- Urutan resolusi: account → channel → `messages.ackReaction` → fallback identity. - Scope: `group-mentions` (default), `group-all`, `direct`, `all`. - `removeAckAfterReply`: menghapus ack setelah balasan pada Slack, Discord, dan Telegram. -- `messages.statusReactions.enabled`: mengaktifkan reaksi status lifecycle pada Slack, Discord, dan Telegram. - Pada Slack dan Discord, nilai tidak disetel membuat reaksi status tetap aktif saat reaksi ack aktif. - Pada Telegram, setel secara eksplisit ke `true` untuk mengaktifkan reaksi status lifecycle. +- `messages.statusReactions.enabled`: mengaktifkan reaksi status siklus hidup pada Slack, Discord, dan Telegram. + Pada Slack dan Discord, saat tidak diatur, status reaction tetap aktif ketika ack reaction aktif. + Pada Telegram, atur secara eksplisit ke `true` untuk mengaktifkan reaksi status siklus hidup. -### Debounce masuk +### Debounce inbound -Mengelompokkan pesan teks cepat dari pengirim yang sama menjadi satu giliran agen. Media/lampiran langsung di-flush. Perintah kontrol melewati debouncing. +Menggabungkan pesan teks cepat dari pengirim yang sama menjadi satu giliran agent. Media/lampiran langsung melakukan flush. Command kontrol melewati debouncing. ### TTS (text-to-speech) @@ -1865,12 +1876,12 @@ Mengelompokkan pesan teks cepat dari pengirim yang sama menjadi satu giliran age } ``` -- `auto` mengontrol auto-TTS. `/tts off|always|inbound|tagged` menimpa per sesi. -- `summaryModel` menimpa `agents.defaults.model.primary` untuk auto-summary. -- `modelOverrides` aktif secara default; `modelOverrides.allowProvider` default ke `false` (opt-in). -- API key menggunakan fallback `ELEVENLABS_API_KEY`/`XI_API_KEY` dan `OPENAI_API_KEY`. -- `openai.baseUrl` menimpa endpoint OpenAI TTS. Urutan resolusi adalah konfigurasi, lalu `OPENAI_TTS_BASE_URL`, lalu `https://api.openai.com/v1`. -- Saat `openai.baseUrl` menunjuk ke endpoint non-OpenAI, OpenClaw memperlakukannya sebagai server TTS kompatibel OpenAI dan melonggarkan validasi model/voice. +- `auto` mengontrol auto-TTS. `/tts off|always|inbound|tagged` mengoverride per sesi. +- `summaryModel` mengoverride `agents.defaults.model.primary` untuk ringkasan otomatis. +- `modelOverrides` diaktifkan secara default; `modelOverrides.allowProvider` default ke `false` (opt-in). +- API key fallback ke `ELEVENLABS_API_KEY`/`XI_API_KEY` dan `OPENAI_API_KEY`. +- `openai.baseUrl` mengoverride endpoint OpenAI TTS. Urutan resolusi adalah config, lalu `OPENAI_TTS_BASE_URL`, lalu `https://api.openai.com/v1`. +- Saat `openai.baseUrl` mengarah ke endpoint non-OpenAI, OpenClaw memperlakukannya sebagai server TTS kompatibel OpenAI dan melonggarkan validasi model/voice. --- @@ -1901,35 +1912,35 @@ Default untuk mode Talk (macOS/iOS/Android). ``` - `talk.provider` harus cocok dengan kunci di `talk.providers` saat beberapa provider Talk dikonfigurasi. -- Kunci Talk datar lama (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) hanya untuk kompatibilitas dan dimigrasikan otomatis ke `talk.providers.`. -- Voice ID menggunakan fallback `ELEVENLABS_VOICE_ID` atau `SAG_VOICE_ID`. +- Kunci Talk flat lama (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) hanya untuk kompatibilitas dan dimigrasikan otomatis ke `talk.providers.`. +- Voice ID fallback ke `ELEVENLABS_VOICE_ID` atau `SAG_VOICE_ID`. - `providers.*.apiKey` menerima string plaintext atau objek SecretRef. -- Fallback `ELEVENLABS_API_KEY` hanya berlaku saat tidak ada API key Talk yang dikonfigurasi. -- `providers.*.voiceAliases` memungkinkan directive Talk menggunakan nama ramah. -- `silenceTimeoutMs` mengontrol berapa lama mode Talk menunggu setelah pengguna diam sebelum mengirim transkrip. Jika tidak disetel, jendela jeda default platform tetap digunakan (`700 ms di macOS dan Android, 900 ms di iOS`). +- Fallback `ELEVENLABS_API_KEY` hanya berlaku ketika tidak ada API key Talk yang dikonfigurasi. +- `providers.*.voiceAliases` memungkinkan directive Talk menggunakan nama yang ramah. +- `silenceTimeoutMs` mengontrol berapa lama mode Talk menunggu setelah pengguna diam sebelum mengirim transkrip. Jika tidak diatur, jendela jeda default platform tetap dipakai (`700 ms di macOS dan Android, 900 ms di iOS`). --- -## Tools +## Tool ### Profil tool `tools.profile` menetapkan allowlist dasar sebelum `tools.allow`/`tools.deny`: -Onboarding lokal secara default menetapkan konfigurasi lokal baru ke `tools.profile: "coding"` saat tidak disetel (profil eksplisit yang sudah ada tetap dipertahankan). +Onboarding lokal secara default mengatur config lokal baru ke `tools.profile: "coding"` saat tidak diatur (profil eksplisit yang sudah ada dipertahankan). | Profil | Mencakup | | ----------- | ------------------------------------------------------------------------------------------------------------------------------- | | `minimal` | hanya `session_status` | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | -| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `full` | Tanpa batasan (sama seperti tidak disetel) | +| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | +| `full` | Tidak ada pembatasan (sama seperti tidak diatur) | ### Grup tool -| Grup | Tools | +| Grup | Tool | | ------------------ | ---------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`, `process`, `code_execution` (`bash` diterima sebagai alias untuk `exec`) | +| `group:runtime` | `exec`, `process`, `code_execution` (`bash` diterima sebagai alias untuk `exec`) | | `group:fs` | `read`, `write`, `edit`, `apply_patch` | | `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | | `group:memory` | `memory_search`, `memory_get` | @@ -1944,7 +1955,7 @@ Onboarding lokal secara default menetapkan konfigurasi lokal baru ke `tools.prof ### `tools.allow` / `tools.deny` -Kebijakan allow/deny tool global (deny menang). Tidak peka huruf besar/kecil, mendukung wildcard `*`. Diterapkan bahkan saat sandbox Docker nonaktif. +Kebijakan global izinkan/tolak tool (deny menang). Tidak peka huruf besar/kecil, mendukung wildcard `*`. Diterapkan bahkan saat sandbox Docker nonaktif. ```json5 { @@ -1954,7 +1965,7 @@ Kebijakan allow/deny tool global (deny menang). Tidak peka huruf besar/kecil, me ### `tools.byProvider` -Batasi lebih lanjut tools untuk provider atau model tertentu. Urutan: profil dasar → profil provider → allow/deny. +Lebih lanjut membatasi tool untuk provider atau model tertentu. Urutan: profil dasar → profil provider → allow/deny. ```json5 { @@ -1986,9 +1997,9 @@ Mengontrol akses exec elevated di luar sandbox: } ``` -- Override per-agen (`agents.list[].tools.elevated`) hanya dapat membatasi lebih lanjut. +- Override per-agent (`agents.list[].tools.elevated`) hanya dapat membatasi lebih jauh. - `/elevated on|off|ask|full` menyimpan status per sesi; directive inline berlaku untuk satu pesan. -- `exec` elevated melewati sandboxing dan menggunakan escape path yang dikonfigurasi (`gateway` secara default, atau `node` saat target exec adalah `node`). +- `exec` elevated melewati sandboxing dan menggunakan jalur escape yang dikonfigurasi (`gateway` secara default, atau `node` saat target exec adalah `node`). ### `tools.exec` @@ -2012,8 +2023,8 @@ Mengontrol akses exec elevated di luar sandbox: ### `tools.loopDetection` -Pemeriksaan keamanan loop tool **nonaktif secara default**. Setel `enabled: true` untuk mengaktifkan deteksi. -Pengaturan dapat didefinisikan secara global di `tools.loopDetection` dan ditimpa per-agen di `agents.list[].tools.loopDetection`. +Pemeriksaan keamanan loop tool **dinonaktifkan secara default**. Atur `enabled: true` untuk mengaktifkan deteksi. +Pengaturan dapat didefinisikan secara global di `tools.loopDetection` dan dioverride per-agent di `agents.list[].tools.loopDetection`. ```json5 { @@ -2034,13 +2045,13 @@ Pengaturan dapat didefinisikan secara global di `tools.loopDetection` dan ditimp } ``` -- `historySize`: riwayat panggilan tool maksimum yang dipertahankan untuk analisis loop. -- `warningThreshold`: ambang pola berulang tanpa progres untuk peringatan. +- `historySize`: jumlah maksimum riwayat tool-call yang disimpan untuk analisis loop. +- `warningThreshold`: ambang pola tanpa progres berulang untuk peringatan. - `criticalThreshold`: ambang berulang yang lebih tinggi untuk memblokir loop kritis. - `globalCircuitBreakerThreshold`: ambang hard stop untuk setiap eksekusi tanpa progres. -- `detectors.genericRepeat`: beri peringatan pada panggilan alat yang sama/argumen yang sama berulang. -- `detectors.knownPollNoProgress`: beri peringatan/blokir pada poll tool yang diketahui (`process.poll`, `command_status`, dll.). -- `detectors.pingPong`: beri peringatan/blokir pada pola pasangan bergantian tanpa progres. +- `detectors.genericRepeat`: peringatkan pada panggilan tool/argumen yang sama berulang. +- `detectors.knownPollNoProgress`: peringatkan/blokir pada tool poll yang dikenal (`process.poll`, `command_status`, dll.). +- `detectors.pingPong`: peringatkan/blokir pada pola pasangan bergantian tanpa progres. - Jika `warningThreshold >= criticalThreshold` atau `criticalThreshold >= globalCircuitBreakerThreshold`, validasi gagal. ### `tools.web` @@ -2112,27 +2123,27 @@ Mengonfigurasi pemahaman media masuk (gambar/audio/video): **Entri provider** (`type: "provider"` atau dihilangkan): - `provider`: id provider API (`openai`, `anthropic`, `google`/`gemini`, `groq`, dll.) -- `model`: override id model +- `model`: override model id - `profile` / `preferredProfile`: pemilihan profil `auth-profiles.json` **Entri CLI** (`type: "cli"`): -- `command`: executable yang akan dijalankan +- `command`: executable yang dijalankan - `args`: argumen bertemplate (mendukung `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, dll.) **Field umum:** - `capabilities`: daftar opsional (`image`, `audio`, `video`). Default: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. - `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: override per-entri. -- Kegagalan akan kembali ke entri berikutnya. +- Kegagalan akan fallback ke entri berikutnya. Auth provider mengikuti urutan standar: `auth-profiles.json` → env vars → `models.providers.*.apiKey`. **Field async completion:** -- `asyncCompletion.directSend`: saat `true`, tugas async `music_generate` - dan `video_generate` yang selesai akan mencoba pengiriman channel langsung terlebih dahulu. Default: `false` - (jalur wake requester-session/model-delivery lama). +- `asyncCompletion.directSend`: saat `true`, tugas `music_generate` + dan `video_generate` async yang selesai mencoba pengiriman channel langsung terlebih dahulu. Default: `false` + (jalur lama requester-session wake/model-delivery). @@ -2151,9 +2162,9 @@ Auth provider mengikuti urutan standar: `auth-profiles.json` → env vars → `m ### `tools.sessions` -Mengontrol sesi mana yang dapat ditargetkan oleh tool sesi (`sessions_list`, `sessions_history`, `sessions_send`). +Mengontrol sesi mana yang dapat ditargetkan oleh session tools (`sessions_list`, `sessions_history`, `sessions_send`). -Default: `tree` (sesi saat ini + sesi yang dipunculkan olehnya, seperti subagen). +Default: `tree` (sesi saat ini + sesi yang dibuat darinya, seperti subagent). ```json5 { @@ -2169,10 +2180,10 @@ Default: `tree` (sesi saat ini + sesi yang dipunculkan olehnya, seperti subagen) Catatan: - `self`: hanya kunci sesi saat ini. -- `tree`: sesi saat ini + sesi yang dipunculkan oleh sesi saat ini (subagen). -- `agent`: sesi mana pun yang dimiliki oleh id agen saat ini (dapat mencakup pengguna lain jika Anda menjalankan sesi per-sender di bawah id agen yang sama). -- `all`: sesi mana pun. Penargetan lintas-agen tetap memerlukan `tools.agentToAgent`. -- Pembatasan sandbox: saat sesi saat ini disandbox dan `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, visibilitas dipaksa menjadi `tree` bahkan jika `tools.sessions.visibility="all"`. +- `tree`: sesi saat ini + sesi yang dibuat dari sesi saat ini (subagent). +- `agent`: sesi apa pun yang dimiliki id agent saat ini (dapat mencakup pengguna lain jika Anda menjalankan sesi per-sender di bawah id agent yang sama). +- `all`: sesi apa pun. Penargetan lintas agent tetap memerlukan `tools.agentToAgent`. +- Clamp sandbox: saat sesi saat ini disandbox dan `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, visibilitas dipaksa ke `tree` meskipun `tools.sessions.visibility="all"`. ### `tools.sessions_spawn` @@ -2183,7 +2194,7 @@ Mengontrol dukungan lampiran inline untuk `sessions_spawn`. tools: { sessions_spawn: { attachments: { - enabled: false, // opt-in: setel true untuk mengizinkan lampiran file inline + enabled: false, // opt-in: atur true untuk mengizinkan lampiran file inline maxTotalBytes: 5242880, // total 5 MB untuk semua file maxFiles: 50, maxFileBytes: 1048576, // 1 MB per file @@ -2197,15 +2208,15 @@ Mengontrol dukungan lampiran inline untuk `sessions_spawn`. Catatan: - Lampiran hanya didukung untuk `runtime: "subagent"`. Runtime ACP menolaknya. -- File dimaterialisasikan ke workspace anak di `.openclaw/attachments//` dengan `.manifest.json`. -- Konten lampiran otomatis direduksi dari persistensi transkrip. -- Input base64 divalidasi dengan pemeriksaan alfabet/padding ketat dan pengaman ukuran pra-decode. +- File dimaterialisasi ke child workspace di `.openclaw/attachments//` dengan `.manifest.json`. +- Konten lampiran otomatis disensor dari persistensi transkrip. +- Input Base64 divalidasi dengan pemeriksaan alfabet/padding yang ketat dan guard ukuran sebelum decode. - Izin file adalah `0700` untuk direktori dan `0600` untuk file. -- Pembersihan mengikuti kebijakan `cleanup`: `delete` selalu menghapus lampiran; `keep` mempertahankannya hanya saat `retainOnSessionKeep: true`. +- Cleanup mengikuti kebijakan `cleanup`: `delete` selalu menghapus lampiran; `keep` mempertahankannya hanya ketika `retainOnSessionKeep: true`. ### `tools.experimental` -Flag tool bawaan eksperimental. Default nonaktif kecuali ada aturan auto-enable spesifik runtime. +Flag tool bawaan eksperimental. Default mati kecuali aturan auto-enable khusus runtime berlaku. ```json5 { @@ -2220,8 +2231,8 @@ Flag tool bawaan eksperimental. Default nonaktif kecuali ada aturan auto-enable Catatan: - `planTool`: mengaktifkan tool `update_plan` terstruktur untuk pelacakan pekerjaan multi-langkah yang tidak sepele. -- Default: `false` untuk provider non-OpenAI. Eksekusi OpenAI dan OpenAI Codex mengaktifkannya otomatis. -- Saat diaktifkan, system prompt juga menambahkan panduan penggunaan agar model hanya menggunakannya untuk pekerjaan substansial dan mempertahankan paling banyak satu langkah `in_progress`. +- Default: `false` untuk provider non-OpenAI. Eksekusi OpenAI dan OpenAI Codex mengaktifkannya secara otomatis. +- Saat diaktifkan, system prompt juga menambahkan panduan penggunaan sehingga model hanya menggunakannya untuk pekerjaan yang substansial dan menjaga maksimal satu langkah `in_progress`. ### `agents.defaults.subagents` @@ -2241,16 +2252,16 @@ Catatan: } ``` -- `model`: model default untuk subagen yang dipunculkan. Jika dihilangkan, subagen mewarisi model pemanggil. -- `allowAgents`: allowlist default id agen target untuk `sessions_spawn` saat agen peminta tidak menyetel `subagents.allowAgents` sendiri (`["*"]` = apa saja; default: hanya agen yang sama). +- `model`: model default untuk sub-agent yang di-spawn. Jika dihilangkan, sub-agent mewarisi model pemanggil. +- `allowAgents`: allowlist default id agent target untuk `sessions_spawn` saat agent peminta tidak menetapkan `subagents.allowAgents` sendiri (`["*"]` = apa saja; default: hanya agent yang sama). - `runTimeoutSeconds`: timeout default (detik) untuk `sessions_spawn` saat pemanggilan tool menghilangkan `runTimeoutSeconds`. `0` berarti tanpa timeout. -- Kebijakan tool per-subagen: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. +- Kebijakan tool per-subagent: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- ## Provider kustom dan base URL -OpenClaw menggunakan katalog model bawaan. Tambahkan provider kustom melalui `models.providers` di konfigurasi atau `~/.openclaw/agents//agent/models.json`. +OpenClaw menggunakan katalog model bawaan. Tambahkan provider kustom melalui `models.providers` di config atau `~/.openclaw/agents//agent/models.json`. ```json5 { @@ -2280,45 +2291,45 @@ OpenClaw menggunakan katalog model bawaan. Tambahkan provider kustom melalui `mo ``` - Gunakan `authHeader: true` + `headers` untuk kebutuhan auth kustom. -- Timpa root konfigurasi agen dengan `OPENCLAW_AGENT_DIR` (atau `PI_CODING_AGENT_DIR`, alias env legacy). -- Prioritas penggabungan untuk ID provider yang cocok: - - Nilai `baseUrl` `models.json` agen yang tidak kosong menang. - - Nilai `apiKey` agen yang tidak kosong menang hanya saat provider tersebut tidak dikelola SecretRef dalam konteks konfigurasi/auth-profile saat ini. - - Nilai `apiKey` provider yang dikelola SecretRef di-refresh dari penanda sumber (`ENV_VAR_NAME` untuk env refs, `secretref-managed` untuk file/exec refs) alih-alih mempertahankan secret hasil resolve. - - Nilai header provider yang dikelola SecretRef di-refresh dari penanda sumber (`secretref-env:ENV_VAR_NAME` untuk env refs, `secretref-managed` untuk file/exec refs). - - `apiKey`/`baseUrl` agen yang kosong atau hilang kembali ke `models.providers` dalam konfigurasi. - - `contextWindow`/`maxTokens` model yang cocok menggunakan nilai yang lebih tinggi antara konfigurasi eksplisit dan nilai katalog implisit. - - `contextTokens` model yang cocok mempertahankan batas runtime eksplisit saat ada; gunakan ini untuk membatasi konteks efektif tanpa mengubah metadata model native. - - Gunakan `models.mode: "replace"` bila Anda ingin konfigurasi sepenuhnya menulis ulang `models.json`. - - Persistensi marker bersifat source-authoritative: marker ditulis dari snapshot konfigurasi sumber aktif (pra-resolve), bukan dari nilai secret runtime yang sudah di-resolve. +- Override root config agent dengan `OPENCLAW_AGENT_DIR` (atau `PI_CODING_AGENT_DIR`, alias environment variable lama). +- Prioritas penggabungan untuk provider ID yang cocok: + - Nilai `baseUrl` `models.json` agent yang tidak kosong menang. + - Nilai `apiKey` agent yang tidak kosong menang hanya ketika provider tersebut tidak dikelola SecretRef dalam konteks config/auth-profile saat ini. + - Nilai `apiKey` provider yang dikelola SecretRef disegarkan dari penanda sumber (`ENV_VAR_NAME` untuk env ref, `secretref-managed` untuk file/exec ref) alih-alih menyimpan secret yang telah di-resolve. + - Nilai header provider yang dikelola SecretRef disegarkan dari penanda sumber (`secretref-env:ENV_VAR_NAME` untuk env ref, `secretref-managed` untuk file/exec ref). + - `apiKey`/`baseUrl` agent yang kosong atau hilang fallback ke `models.providers` di config. + - `contextWindow`/`maxTokens` model yang cocok menggunakan nilai lebih tinggi antara config eksplisit dan nilai katalog implisit. + - `contextTokens` model yang cocok mempertahankan batas runtime eksplisit bila ada; gunakan untuk membatasi konteks efektif tanpa mengubah metadata model native. + - Gunakan `models.mode: "replace"` bila Anda ingin config menulis ulang `models.json` sepenuhnya. + - Persistensi penanda bersifat source-authoritative: penanda ditulis dari snapshot config sumber aktif (pra-resolusi), bukan dari nilai secret runtime yang telah di-resolve. ### Detail field provider - `models.mode`: perilaku katalog provider (`merge` atau `replace`). -- `models.providers`: peta provider kustom yang dikunci berdasarkan id provider. -- `models.providers.*.api`: adaptor request (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai`, dll). -- `models.providers.*.apiKey`: kredensial provider (lebih baik gunakan SecretRef/substitusi env). +- `models.providers`: peta provider kustom yang dikunci dengan provider id. +- `models.providers.*.api`: adapter request (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai`, dll). +- `models.providers.*.apiKey`: kredensial provider (utamakan SecretRef/substitusi env). - `models.providers.*.auth`: strategi auth (`api-key`, `token`, `oauth`, `aws-sdk`). -- `models.providers.*.injectNumCtxForOpenAICompat`: untuk Ollama + `openai-completions`, injeksikan `options.num_ctx` ke request (default: `true`). +- `models.providers.*.injectNumCtxForOpenAICompat`: untuk Ollama + `openai-completions`, suntikkan `options.num_ctx` ke request (default: `true`). - `models.providers.*.authHeader`: paksa transport kredensial di header `Authorization` bila diperlukan. - `models.providers.*.baseUrl`: base URL API upstream. -- `models.providers.*.headers`: header statis tambahan untuk perutean proxy/tenant. +- `models.providers.*.headers`: header statis tambahan untuk routing proxy/tenant. - `models.providers.*.request`: override transport untuk request HTTP model-provider. - `request.headers`: header tambahan (digabungkan dengan default provider). Nilai menerima SecretRef. - `request.auth`: override strategi auth. Mode: `"provider-default"` (gunakan auth bawaan provider), `"authorization-bearer"` (dengan `token`), `"header"` (dengan `headerName`, `value`, `prefix` opsional). - - `request.proxy`: override proxy HTTP. Mode: `"env-proxy"` (gunakan env `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (dengan `url`). Kedua mode menerima sub-objek `tls` opsional. + - `request.proxy`: override proxy HTTP. Mode: `"env-proxy"` (gunakan env var `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (dengan `url`). Kedua mode menerima sub-objek `tls` opsional. - `request.tls`: override TLS untuk koneksi langsung. Field: `ca`, `cert`, `key`, `passphrase` (semuanya menerima SecretRef), `serverName`, `insecureSkipVerify`. - `models.providers.*.models`: entri katalog model provider eksplisit. - `models.providers.*.models.*.contextWindow`: metadata context window model native. -- `models.providers.*.models.*.contextTokens`: batas konteks runtime opsional. Gunakan ini bila Anda ingin anggaran konteks efektif lebih kecil daripada `contextWindow` native model. -- `models.providers.*.models.*.compat.supportsDeveloperRole`: petunjuk kompatibilitas opsional. Untuk `api: "openai-completions"` dengan `baseUrl` non-native yang tidak kosong (host bukan `api.openai.com`), OpenClaw memaksakan ini menjadi `false` saat runtime. `baseUrl` kosong/diabaikan mempertahankan perilaku default OpenAI. +- `models.providers.*.models.*.contextTokens`: batas konteks runtime opsional. Gunakan ini ketika Anda ingin anggaran konteks efektif yang lebih kecil daripada `contextWindow` native model. +- `models.providers.*.models.*.compat.supportsDeveloperRole`: petunjuk kompatibilitas opsional. Untuk `api: "openai-completions"` dengan `baseUrl` non-native yang tidak kosong (host bukan `api.openai.com`), OpenClaw memaksanya menjadi `false` saat runtime. `baseUrl` kosong/tidak diatur mempertahankan perilaku OpenAI default. - `plugins.entries.amazon-bedrock.config.discovery`: root pengaturan auto-discovery Bedrock. -- `plugins.entries.amazon-bedrock.config.discovery.enabled`: aktif/nonaktifkan discovery implisit. +- `plugins.entries.amazon-bedrock.config.discovery.enabled`: nyalakan/matikan implicit discovery. - `plugins.entries.amazon-bedrock.config.discovery.region`: region AWS untuk discovery. -- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: filter provider-id opsional untuk discovery tertarget. +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: filter provider-id opsional untuk discovery terarah. - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: interval polling untuk refresh discovery. -- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: context window fallback untuk model yang didiscovery. -- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: token keluaran maksimum fallback untuk model yang didiscovery. +- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: context window fallback untuk model yang ditemukan. +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: token output maksimum fallback untuk model yang ditemukan. ### Contoh provider @@ -2373,7 +2384,7 @@ Gunakan `cerebras/zai-glm-4.7` untuk Cerebras; `zai/glm-4.7` untuk Z.AI langsung } ``` -Setel `OPENCODE_API_KEY` (atau `OPENCODE_ZEN_API_KEY`). Gunakan referensi `opencode/...` untuk katalog Zen atau referensi `opencode-go/...` untuk katalog Go. Shortcut: `openclaw onboard --auth-choice opencode-zen` atau `openclaw onboard --auth-choice opencode-go`. +Atur `OPENCODE_API_KEY` (atau `OPENCODE_ZEN_API_KEY`). Gunakan referensi `opencode/...` untuk katalog Zen atau referensi `opencode-go/...` untuk katalog Go. Shortcut: `openclaw onboard --auth-choice opencode-zen` atau `openclaw onboard --auth-choice opencode-go`. @@ -2390,7 +2401,7 @@ Setel `OPENCODE_API_KEY` (atau `OPENCODE_ZEN_API_KEY`). Gunakan referensi `openc } ``` -Setel `ZAI_API_KEY`. `z.ai/*` dan `z-ai/*` diterima sebagai alias. Shortcut: `openclaw onboard --auth-choice zai-api-key`. +Atur `ZAI_API_KEY`. `z.ai/*` dan `z-ai/*` adalah alias yang diterima. Shortcut: `openclaw onboard --auth-choice zai-api-key`. - Endpoint umum: `https://api.z.ai/api/paas/v4` - Endpoint coding (default): `https://api.z.ai/api/coding/paas/v4` @@ -2435,9 +2446,9 @@ Setel `ZAI_API_KEY`. `z.ai/*` dan `z-ai/*` diterima sebagai alias. Shortcut: `op Untuk endpoint China: `baseUrl: "https://api.moonshot.cn/v1"` atau `openclaw onboard --auth-choice moonshot-api-key-cn`. -Endpoint Moonshot native mengiklankan kompatibilitas penggunaan streaming pada transport bersama -`openai-completions`, dan OpenClaw sekarang menguncikannya pada kapabilitas endpoint -daripada hanya pada provider id bawaan. +Endpoint Moonshot native mengiklankan kompatibilitas penggunaan streaming pada +transport bersama `openai-completions`, dan OpenClaw sekarang menguncinya pada +kapabilitas endpoint, bukan hanya provider id bawaan. @@ -2459,7 +2470,7 @@ Kompatibel dengan Anthropic, provider bawaan. Shortcut: `openclaw onboard --auth - + ```json5 { @@ -2494,7 +2505,7 @@ Kompatibel dengan Anthropic, provider bawaan. Shortcut: `openclaw onboard --auth } ``` -Base URL harus tanpa `/v1` (klien Anthropic menambahkannya). Shortcut: `openclaw onboard --auth-choice synthetic-api-key`. +Base URL harus menghilangkan `/v1` (klien Anthropic menambahkannya). Shortcut: `openclaw onboard --auth-choice synthetic-api-key`. @@ -2534,10 +2545,10 @@ Base URL harus tanpa `/v1` (klien Anthropic menambahkannya). Shortcut: `openclaw } ``` -Setel `MINIMAX_API_KEY`. Shortcut: +Atur `MINIMAX_API_KEY`. Shortcut: `openclaw onboard --auth-choice minimax-global-api` atau `openclaw onboard --auth-choice minimax-cn-api`. -Katalog model sekarang default ke M2.7 saja. +Katalog model sekarang default hanya ke M2.7. Pada jalur streaming kompatibel Anthropic, OpenClaw menonaktifkan thinking MiniMax secara default kecuali Anda secara eksplisit menetapkan `thinking` sendiri. `/fast on` atau `params.fastMode: true` menulis ulang `MiniMax-M2.7` menjadi @@ -2547,7 +2558,7 @@ secara default kecuali Anda secara eksplisit menetapkan `thinking` sendiri. `/fa -Lihat [Local Models](/id/gateway/local-models). Singkatnya: jalankan model lokal besar melalui LM Studio Responses API pada hardware yang serius; pertahankan model ter-host tetap digabungkan untuk fallback. +Lihat [Local Models](/id/gateway/local-models). Singkatnya: jalankan model lokal besar melalui LM Studio Responses API pada hardware yang serius; pertahankan model hosted yang digabungkan untuk fallback. @@ -2578,18 +2589,18 @@ Lihat [Local Models](/id/gateway/local-models). Singkatnya: jalankan model lokal } ``` -- `allowBundled`: allowlist opsional hanya untuk Skills bundled (Skills managed/workspace tidak terpengaruh). +- `allowBundled`: allowlist opsional hanya untuk bundled skill (skill managed/workspace tidak terpengaruh). - `load.extraDirs`: root skill bersama tambahan (prioritas terendah). -- `install.preferBrew`: saat true, lebih memilih installer Homebrew ketika `brew` - tersedia sebelum kembali ke jenis installer lain. -- `install.nodeManager`: preferensi installer node untuk spec `metadata.openclaw.install` +- `install.preferBrew`: ketika true, utamakan installer Homebrew ketika `brew` + tersedia sebelum fallback ke jenis installer lain. +- `install.nodeManager`: preferensi installer node untuk spesifikasi `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). -- `entries..enabled: false` menonaktifkan sebuah skill meskipun dibundel/terinstal. -- `entries..apiKey`: field praktis API key tingkat skill (saat didukung oleh skill). +- `entries..enabled: false` menonaktifkan skill meskipun bundled/installed. +- `entries..apiKey`: field kenyamanan API key tingkat skill (saat didukung oleh skill). --- -## Plugins +## Plugin ```json5 { @@ -2614,34 +2625,34 @@ Lihat [Local Models](/id/gateway/local-models). Singkatnya: jalankan model lokal ``` - Dimuat dari `~/.openclaw/extensions`, `/.openclaw/extensions`, plus `plugins.load.paths`. -- Discovery menerima plugin OpenClaw native plus bundle Codex dan Claude yang kompatibel, termasuk bundle Claude tata letak default tanpa manifest. -- **Perubahan konfigurasi memerlukan restart gateway.** +- Discovery menerima plugin OpenClaw native plus bundle Codex dan bundle Claude yang kompatibel, termasuk bundle Claude dengan tata letak default tanpa manifest. +- **Perubahan config memerlukan restart gateway.** - `allow`: allowlist opsional (hanya plugin yang tercantum yang dimuat). `deny` menang. -- `plugins.entries..apiKey`: field praktis API key tingkat plugin (saat didukung oleh plugin). -- `plugins.entries..env`: peta env var dengan scope plugin. -- `plugins.entries..hooks.allowPromptInjection`: saat `false`, inti memblokir `before_prompt_build` dan mengabaikan field pemodifikasi prompt dari `before_agent_start` lama, sambil mempertahankan `modelOverride` dan `providerOverride` lama. Berlaku untuk hook plugin native dan direktori hook yang disediakan bundle yang didukung. -- `plugins.entries..subagent.allowModelOverride`: secara eksplisit mempercayai plugin ini untuk meminta override `provider` dan `model` per-eksekusi untuk eksekusi subagen latar belakang. -- `plugins.entries..subagent.allowedModels`: allowlist opsional target `provider/model` kanonis untuk override subagen tepercaya. Gunakan `"*"` hanya bila Anda memang bermaksud mengizinkan model apa pun. -- `plugins.entries..config`: objek konfigurasi yang didefinisikan plugin (divalidasi oleh skema plugin OpenClaw native bila tersedia). +- `plugins.entries..apiKey`: field kenyamanan API key tingkat plugin (jika didukung oleh plugin). +- `plugins.entries..env`: peta env var khusus plugin. +- `plugins.entries..hooks.allowPromptInjection`: ketika `false`, inti memblokir `before_prompt_build` dan mengabaikan field mutasi prompt dari `before_agent_start` lama, sambil mempertahankan `modelOverride` dan `providerOverride` lama. Berlaku untuk hook plugin native dan direktori hook yang disediakan bundle yang didukung. +- `plugins.entries..subagent.allowModelOverride`: secara eksplisit mempercayai plugin ini untuk meminta override `provider` dan `model` per-eksekusi bagi subagent background. +- `plugins.entries..subagent.allowedModels`: allowlist opsional target `provider/model` kanonis untuk override subagent tepercaya. Gunakan `"*"` hanya jika Anda memang ingin mengizinkan model apa pun. +- `plugins.entries..config`: objek config yang didefinisikan plugin (divalidasi oleh skema plugin OpenClaw native bila tersedia). - `plugins.entries.firecrawl.config.webFetch`: pengaturan provider web-fetch Firecrawl. - - `apiKey`: API key Firecrawl (menerima SecretRef). Menggunakan fallback `plugins.entries.firecrawl.config.webSearch.apiKey`, `tools.web.fetch.firecrawl.apiKey` lama, atau env var `FIRECRAWL_API_KEY`. + - `apiKey`: API key Firecrawl (menerima SecretRef). Fallback ke `plugins.entries.firecrawl.config.webSearch.apiKey`, `tools.web.fetch.firecrawl.apiKey` lama, atau env var `FIRECRAWL_API_KEY`. - `baseUrl`: base URL API Firecrawl (default: `https://api.firecrawl.dev`). - `onlyMainContent`: ekstrak hanya konten utama dari halaman (default: `true`). - `maxAgeMs`: usia cache maksimum dalam milidetik (default: `172800000` / 2 hari). - - `timeoutSeconds`: timeout permintaan scrape dalam detik (default: `60`). + - `timeoutSeconds`: timeout request scrape dalam detik (default: `60`). - `plugins.entries.xai.config.xSearch`: pengaturan xAI X Search (pencarian web Grok). - `enabled`: aktifkan provider X Search. - - `model`: model Grok yang akan digunakan untuk pencarian (mis. `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: pengaturan memory dreaming (eksperimental). Lihat [Dreaming](/concepts/dreaming) untuk fase dan ambang. - - `enabled`: sakelar dreaming utama (default `false`). + - `model`: model Grok yang digunakan untuk pencarian (mis. `"grok-4-1-fast"`). +- `plugins.entries.memory-core.config.dreaming`: pengaturan memory dreaming (eksperimental). Lihat [Dreaming](/id/concepts/dreaming) untuk fase dan ambang. + - `enabled`: sakelar utama dreaming (default `false`). - `frequency`: cadence cron untuk setiap sweep dreaming penuh (default `"0 3 * * *"`). - - kebijakan fase dan ambang adalah detail implementasi (bukan kunci konfigurasi yang dihadapkan ke pengguna). -- Plugin bundle Claude yang diaktifkan juga dapat menyumbangkan default Pi tersemat dari `settings.json`; OpenClaw menerapkannya sebagai pengaturan agen yang sudah disanitasi, bukan sebagai patch konfigurasi OpenClaw mentah. + - kebijakan fase dan ambang adalah detail implementasi (bukan kunci config yang terlihat oleh pengguna). +- Plugin bundle Claude yang diaktifkan juga dapat menyumbangkan default Pi tertanam dari `settings.json`; OpenClaw menerapkannya sebagai pengaturan agent yang telah disanitasi, bukan sebagai patch config OpenClaw mentah. - `plugins.slots.memory`: pilih id plugin memori aktif, atau `"none"` untuk menonaktifkan plugin memori. -- `plugins.slots.contextEngine`: pilih id plugin mesin konteks aktif; default ke `"legacy"` kecuali Anda memasang dan memilih engine lain. -- `plugins.installs`: metadata instalasi yang dikelola CLI yang digunakan oleh `openclaw plugins update`. +- `plugins.slots.contextEngine`: pilih id plugin engine konteks aktif; default ke `"legacy"` kecuali Anda menginstal dan memilih engine lain. +- `plugins.installs`: metadata instalasi yang dikelola CLI dan digunakan oleh `openclaw plugins update`. - Mencakup `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`. - - Perlakukan `plugins.installs.*` sebagai status terkelola; lebih baik gunakan perintah CLI daripada edit manual. + - Perlakukan `plugins.installs.*` sebagai state yang dikelola; utamakan perintah CLI daripada edit manual. Lihat [Plugins](/id/tools/plugin). @@ -2656,7 +2667,7 @@ Lihat [Plugins](/id/tools/plugin). evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - dangerouslyAllowPrivateNetwork: true, // default mode jaringan tepercaya + dangerouslyAllowPrivateNetwork: true, // mode trusted-network default // allowPrivateNetwork: true, // alias lama // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], @@ -2684,27 +2695,27 @@ Lihat [Plugins](/id/tools/plugin). ``` - `evaluateEnabled: false` menonaktifkan `act:evaluate` dan `wait --fn`. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` default ke `true` saat tidak disetel (model jaringan tepercaya). -- Setel `ssrfPolicy.dangerouslyAllowPrivateNetwork: false` untuk navigasi browser publik-saja yang ketat. -- Dalam mode ketat, endpoint profile CDP remote (`profiles.*.cdpUrl`) tunduk pada pemblokiran jaringan privat yang sama selama pemeriksaan jangkauan/discovery. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` default ke `true` saat tidak diatur (model trusted-network). +- Atur `ssrfPolicy.dangerouslyAllowPrivateNetwork: false` untuk navigasi browser ketat yang hanya publik. +- Dalam mode ketat, endpoint profil CDP remote (`profiles.*.cdpUrl`) tunduk pada pemblokiran jaringan privat yang sama saat pemeriksaan reachability/discovery. - `ssrfPolicy.allowPrivateNetwork` tetap didukung sebagai alias lama. - Dalam mode ketat, gunakan `ssrfPolicy.hostnameAllowlist` dan `ssrfPolicy.allowedHostnames` untuk pengecualian eksplisit. -- Profile remote bersifat attach-only (start/stop/reset dinonaktifkan). +- Profil remote bersifat attach-only (start/stop/reset dinonaktifkan). - `profiles.*.cdpUrl` menerima `http://`, `https://`, `ws://`, dan `wss://`. - Gunakan HTTP(S) bila Anda ingin OpenClaw me-discover `/json/version`; gunakan WS(S) - bila provider Anda memberikan URL WebSocket DevTools langsung. -- Profile `existing-session` hanya untuk host dan menggunakan Chrome MCP alih-alih CDP. -- Profile `existing-session` dapat menetapkan `userDataDir` untuk menargetkan - profil browser berbasis Chromium tertentu seperti Brave atau Edge. -- Profile `existing-session` mempertahankan batas rute Chrome MCP saat ini: - action berbasis snapshot/ref alih-alih penargetan selector CSS, hook upload satu file, - tanpa override timeout dialog, tanpa `wait --load networkidle`, dan tanpa - `responsebody`, ekspor PDF, intersepsi unduhan, atau action batch. -- Profile `openclaw` lokal terkelola otomatis menetapkan `cdpPort` dan `cdpUrl`; hanya - setel `cdpUrl` secara eksplisit untuk CDP remote. + Gunakan HTTP(S) ketika Anda ingin OpenClaw menemukan `/json/version`; gunakan WS(S) + ketika provider Anda memberi URL WebSocket DevTools langsung. +- Profil `existing-session` hanya untuk host dan menggunakan Chrome MCP, bukan CDP. +- Profil `existing-session` dapat menetapkan `userDataDir` untuk menargetkan profil + browser berbasis Chromium tertentu seperti Brave atau Edge. +- Profil `existing-session` mempertahankan batas route Chrome MCP saat ini: + tindakan berbasis snapshot/ref alih-alih penargetan CSS-selector, hook upload satu file, + tidak ada override timeout dialog, tidak ada `wait --load networkidle`, dan tidak ada + `responsebody`, ekspor PDF, intersepsi download, atau tindakan batch. +- Profil `openclaw` lokal yang dikelola secara otomatis menetapkan `cdpPort` dan `cdpUrl`; hanya + atur `cdpUrl` secara eksplisit untuk CDP remote. - Urutan auto-detect: browser default jika berbasis Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. -- Layanan kontrol: hanya loopback (port diturunkan dari `gateway.port`, default `18791`). -- `extraArgs` menambahkan flag peluncuran ekstra ke startup Chromium lokal (misalnya +- Control service: hanya loopback (port diturunkan dari `gateway.port`, default `18791`). +- `extraArgs` menambahkan flag peluncuran tambahan ke startup Chromium lokal (misalnya `--disable-gpu`, ukuran jendela, atau flag debug). --- @@ -2723,8 +2734,8 @@ Lihat [Plugins](/id/tools/plugin). } ``` -- `seamColor`: warna aksen untuk chrome UI aplikasi native (tint gelembung Talk Mode, dll.). -- `assistant`: override identitas Control UI. Menggunakan identitas agen aktif sebagai fallback. +- `seamColor`: warna aksen untuk UI chrome aplikasi native (tint bubble Talk Mode, dll.). +- `assistant`: override identitas Control UI. Fallback ke identitas agent aktif. --- @@ -2772,9 +2783,9 @@ Lihat [Plugins](/id/tools/plugin). // Opsional. Default false. allowRealIpFallback: false, tools: { - // Deny HTTP /tools/invoke tambahan + // Penolakan HTTP /tools/invoke tambahan deny: ["browser"], - // Hapus tools dari daftar deny HTTP default + // Hapus tool dari daftar deny HTTP default allow: ["gateway"], }, push: { @@ -2789,66 +2800,66 @@ Lihat [Plugins](/id/tools/plugin). } ``` - + -- `mode`: `local` (jalankan gateway) atau `remote` (hubungkan ke gateway remote). Gateway menolak memulai kecuali `local`. -- `port`: satu port termultipleks untuk WS + HTTP. Prioritas: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. +- `mode`: `local` (jalankan gateway) atau `remote` (hubungkan ke gateway remote). Gateway menolak start kecuali `local`. +- `port`: satu port multipleks untuk WS + HTTP. Prioritas: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. - `bind`: `auto`, `loopback` (default), `lan` (`0.0.0.0`), `tailnet` (hanya IP Tailscale), atau `custom`. -- **Alias bind legacy**: gunakan nilai mode bind di `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), bukan alias host (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). -- **Catatan Docker**: bind default `loopback` mendengarkan di `127.0.0.1` di dalam kontainer. Dengan jaringan bridge Docker (`-p 18789:18789`), lalu lintas tiba di `eth0`, sehingga gateway tidak dapat dijangkau. Gunakan `--network host`, atau setel `bind: "lan"` (atau `bind: "custom"` dengan `customBindHost: "0.0.0.0"`) agar mendengarkan di semua interface. -- **Auth**: wajib secara default. Bind non-loopback memerlukan auth gateway. Dalam praktiknya itu berarti token/password bersama atau reverse proxy sadar identitas dengan `gateway.auth.mode: "trusted-proxy"`. Wizard onboarding secara default membuat token. -- Jika `gateway.auth.token` dan `gateway.auth.password` sama-sama dikonfigurasi (termasuk SecretRef), setel `gateway.auth.mode` secara eksplisit ke `token` atau `password`. Startup dan alur instalasi/perbaikan layanan gagal saat keduanya dikonfigurasi dan mode tidak disetel. -- `gateway.auth.mode: "none"`: mode tanpa auth eksplisit. Gunakan hanya untuk setup loopback lokal tepercaya; ini sengaja tidak ditawarkan oleh prompt onboarding. -- `gateway.auth.mode: "trusted-proxy"`: delegasikan auth ke reverse proxy sadar identitas dan percayai header identitas dari `gateway.trustedProxies` (lihat [Trusted Proxy Auth](/id/gateway/trusted-proxy-auth)). Mode ini mengharapkan sumber proxy **non-loopback**; reverse proxy loopback pada host yang sama tidak memenuhi trusted-proxy auth. -- `gateway.auth.allowTailscale`: saat `true`, header identitas Tailscale Serve dapat memenuhi auth Control UI/WebSocket (diverifikasi melalui `tailscale whois`). Endpoint HTTP API **tidak** menggunakan auth header Tailscale tersebut; endpoint mengikuti mode auth HTTP normal gateway. Alur tanpa token ini mengasumsikan host gateway tepercaya. Default ke `true` saat `tailscale.mode = "serve"`. -- `gateway.auth.rateLimit`: limiter gagal-auth opsional. Berlaku per IP klien dan per scope auth (shared-secret dan device-token dilacak secara independen). Percobaan yang diblokir mengembalikan `429` + `Retry-After`. - - Pada jalur async Tailscale Serve Control UI, percobaan gagal untuk `{scope, clientIp}` yang sama diserialkan sebelum penulisan kegagalan. Karena itu percobaan buruk bersamaan dari klien yang sama dapat memicu limiter pada permintaan kedua alih-alih keduanya lolos sebagai ketidakcocokan biasa. - - `gateway.auth.rateLimit.exemptLoopback` default ke `true`; setel `false` saat Anda sengaja ingin lalu lintas localhost juga dibatasi lajunya (untuk setup uji atau deployment proxy yang ketat). -- Percobaan auth WS yang berasal dari browser selalu di-throttle dengan pengecualian loopback dinonaktifkan (defense-in-depth terhadap brute force localhost berbasis browser). -- Pada loopback, lockout yang berasal dari browser itu diisolasi per nilai `Origin` - yang dinormalisasi, sehingga kegagalan berulang dari satu origin localhost tidak secara otomatis +- **Alias bind lama**: gunakan nilai mode bind di `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), bukan alias host (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). +- **Catatan Docker**: bind default `loopback` mendengarkan di `127.0.0.1` di dalam container. Dengan Docker bridge networking (`-p 18789:18789`), traffic datang melalui `eth0`, sehingga gateway tidak dapat dijangkau. Gunakan `--network host`, atau atur `bind: "lan"` (atau `bind: "custom"` dengan `customBindHost: "0.0.0.0"`) agar mendengarkan di semua interface. +- **Auth**: wajib secara default. Bind non-loopback memerlukan auth gateway. Dalam praktiknya itu berarti token/password bersama atau reverse proxy sadar-identitas dengan `gateway.auth.mode: "trusted-proxy"`. Wizard onboarding menghasilkan token secara default. +- Jika `gateway.auth.token` dan `gateway.auth.password` keduanya dikonfigurasi (termasuk SecretRef), tetapkan `gateway.auth.mode` secara eksplisit ke `token` atau `password`. Startup dan alur install/repair service gagal ketika keduanya dikonfigurasi dan mode tidak diatur. +- `gateway.auth.mode: "none"`: mode tanpa auth yang eksplisit. Gunakan hanya untuk setup loopback lokal tepercaya; ini sengaja tidak ditawarkan oleh prompt onboarding. +- `gateway.auth.mode: "trusted-proxy"`: delegasikan auth ke reverse proxy sadar-identitas dan percayai header identitas dari `gateway.trustedProxies` (lihat [Trusted Proxy Auth](/id/gateway/trusted-proxy-auth)). Mode ini mengharapkan sumber proxy **non-loopback**; reverse proxy loopback pada host yang sama tidak memenuhi trusted-proxy auth. +- `gateway.auth.allowTailscale`: saat `true`, header identitas Tailscale Serve dapat memenuhi auth Control UI/WebSocket (diverifikasi melalui `tailscale whois`). Endpoint HTTP API **tidak** menggunakan auth header Tailscale tersebut; mereka mengikuti mode auth HTTP normal gateway. Alur tanpa token ini mengasumsikan host gateway tepercaya. Default ke `true` saat `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit`: limiter auth gagal opsional. Berlaku per IP klien dan per scope auth (shared-secret dan device-token dilacak secara independen). Percobaan yang diblokir mengembalikan `429` + `Retry-After`. + - Pada jalur async Tailscale Serve Control UI, percobaan gagal untuk `{scope, clientIp}` yang sama diserialisasikan sebelum penulisan kegagalan. Karena itu, percobaan buruk yang bersamaan dari klien yang sama dapat memicu limiter pada request kedua alih-alih keduanya lolos sebagai mismatch biasa. + - `gateway.auth.rateLimit.exemptLoopback` default ke `true`; atur `false` bila Anda sengaja ingin traffic localhost juga dikenai rate limit (untuk setup pengujian atau deployment proxy yang ketat). +- Percobaan auth WS asal browser selalu dibatasi dengan pengecualian loopback dinonaktifkan (pertahanan berlapis terhadap brute force localhost berbasis browser). +- Pada loopback, lockout asal browser tersebut diisolasi per nilai `Origin` + yang dinormalisasi, sehingga kegagalan berulang dari satu origin localhost tidak otomatis mengunci origin yang berbeda. - `tailscale.mode`: `serve` (hanya tailnet, bind loopback) atau `funnel` (publik, memerlukan auth). -- `controlUi.allowedOrigins`: allowlist origin browser eksplisit untuk koneksi WebSocket Gateway. Wajib saat klien browser diharapkan dari origin non-loopback. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: mode berbahaya yang mengaktifkan fallback origin header Host untuk deployment yang sengaja mengandalkan kebijakan origin header Host. +- `controlUi.allowedOrigins`: allowlist browser-origin eksplisit untuk koneksi WebSocket Gateway. Wajib ketika klien browser diharapkan dari origin non-loopback. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: mode berbahaya yang mengaktifkan fallback origin header Host untuk deployment yang sengaja bergantung pada kebijakan origin header Host. - `remote.transport`: `ssh` (default) atau `direct` (ws/wss). Untuk `direct`, `remote.url` harus berupa `ws://` atau `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: override break-glass sisi klien yang mengizinkan `ws://` plaintext ke IP jaringan privat tepercaya; default tetap loopback-only untuk plaintext. -- `gateway.remote.token` / `.password` adalah field kredensial klien remote. Field tersebut tidak mengonfigurasi auth gateway dengan sendirinya. -- `gateway.push.apns.relay.baseUrl`: base HTTPS URL untuk relay APNs eksternal yang digunakan build iOS resmi/TestFlight setelah mereka memublikasikan registrasi berbasis relay ke gateway. URL ini harus cocok dengan URL relay yang dikompilasi ke dalam build iOS. -- `gateway.push.apns.relay.timeoutMs`: timeout pengiriman gateway-ke-relay dalam milidetik. Default ke `10000`. -- Registrasi berbasis relay didelegasikan ke identitas gateway tertentu. Aplikasi iOS yang ter-pair mengambil `gateway.identity.get`, menyertakan identitas itu dalam registrasi relay, dan meneruskan grant pengiriman yang dibatasi registrasi ke gateway. Gateway lain tidak dapat menggunakan kembali registrasi yang tersimpan tersebut. -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: override env sementara untuk konfigurasi relay di atas. -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: escape hatch khusus pengembangan untuk URL relay HTTP loopback. URL relay produksi harus tetap menggunakan HTTPS. -- `gateway.channelHealthCheckMinutes`: interval monitor kesehatan channel dalam menit. Setel `0` untuk menonaktifkan restart health-monitor secara global. Default: `5`. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: override break-glass sisi klien yang mengizinkan `ws://` plaintext ke IP jaringan privat tepercaya; default tetap hanya loopback untuk plaintext. +- `gateway.remote.token` / `.password` adalah field kredensial klien remote. Keduanya tidak mengonfigurasi auth gateway dengan sendirinya. +- `gateway.push.apns.relay.baseUrl`: base HTTPS URL untuk relay APNs eksternal yang digunakan oleh build iOS resmi/TestFlight setelah memublikasikan pendaftaran berbasis relay ke gateway. URL ini harus cocok dengan URL relay yang dikompilasi ke build iOS. +- `gateway.push.apns.relay.timeoutMs`: timeout kirim dari gateway ke relay dalam milidetik. Default: `10000`. +- Pendaftaran berbasis relay didelegasikan ke identitas gateway tertentu. Aplikasi iOS yang dipasangkan mengambil `gateway.identity.get`, menyertakan identitas itu dalam pendaftaran relay, dan meneruskan grant pengiriman berskala pendaftaran ke gateway. Gateway lain tidak dapat menggunakan kembali pendaftaran yang tersimpan itu. +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: override env sementara untuk config relay di atas. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: jalur keluar khusus development untuk URL relay HTTP loopback. URL relay produksi sebaiknya tetap HTTPS. +- `gateway.channelHealthCheckMinutes`: interval monitor kesehatan channel dalam menit. Atur `0` untuk menonaktifkan restart health-monitor secara global. Default: `5`. - `gateway.channelStaleEventThresholdMinutes`: ambang socket basi dalam menit. Pertahankan nilai ini lebih besar dari atau sama dengan `gateway.channelHealthCheckMinutes`. Default: `30`. -- `gateway.channelMaxRestartsPerHour`: jumlah maksimum restart health-monitor per channel/akun dalam satu jam bergulir. Default: `10`. -- `channels..healthMonitor.enabled`: opt-out per-channel untuk restart health-monitor sambil tetap mempertahankan monitor global aktif. -- `channels..accounts..healthMonitor.enabled`: override per-akun untuk channel multi-akun. Saat disetel, nilainya lebih diprioritaskan daripada override tingkat channel. -- Jalur panggilan gateway lokal dapat menggunakan `gateway.remote.*` sebagai fallback hanya saat `gateway.auth.*` tidak disetel. -- Jika `gateway.auth.token` / `gateway.auth.password` secara eksplisit dikonfigurasi melalui SecretRef dan tidak ter-resolve, resolusi gagal tertutup (tanpa fallback remote yang menutupi). -- `trustedProxies`: IP reverse proxy yang mengakhiri TLS atau menyuntikkan header forwarded-client. Cantumkan hanya proxy yang Anda kendalikan. Entri loopback tetap valid untuk setup proxy/pendeteksian lokal di host yang sama (misalnya Tailscale Serve atau reverse proxy lokal), tetapi entri tersebut **tidak** membuat permintaan loopback memenuhi syarat untuk `gateway.auth.mode: "trusted-proxy"`. -- `allowRealIpFallback`: saat `true`, gateway menerima `X-Real-IP` jika `X-Forwarded-For` tidak ada. Default `false` untuk perilaku fail-closed. +- `gateway.channelMaxRestartsPerHour`: maksimum restart health-monitor per channel/account dalam satu jam bergulir. Default: `10`. +- `channels..healthMonitor.enabled`: opt-out per-channel untuk restart health-monitor sambil tetap menjaga monitor global tetap aktif. +- `channels..accounts..healthMonitor.enabled`: override per-account untuk channel multi-account. Saat diatur, ia mengambil prioritas atas override tingkat channel. +- Jalur pemanggilan gateway lokal dapat menggunakan fallback `gateway.remote.*` hanya ketika `gateway.auth.*` tidak diatur. +- Jika `gateway.auth.token` / `gateway.auth.password` secara eksplisit dikonfigurasi melalui SecretRef dan tidak dapat di-resolve, resolusi gagal secara fail-closed (tanpa fallback remote yang menyamarkan). +- `trustedProxies`: IP reverse proxy yang mengakhiri TLS atau menyuntikkan header forwarded-client. Cantumkan hanya proxy yang Anda kendalikan. Entri loopback tetap valid untuk setup proxy/deteksi lokal pada host yang sama (misalnya Tailscale Serve atau reverse proxy lokal), tetapi entri tersebut **tidak** membuat request loopback memenuhi syarat untuk `gateway.auth.mode: "trusted-proxy"`. +- `allowRealIpFallback`: ketika `true`, gateway menerima `X-Real-IP` jika `X-Forwarded-For` tidak ada. Default `false` untuk perilaku fail-closed. - `gateway.tools.deny`: nama tool tambahan yang diblokir untuk HTTP `POST /tools/invoke` (memperluas daftar deny default). - `gateway.tools.allow`: hapus nama tool dari daftar deny HTTP default. -### Endpoint kompatibel OpenAI +### Endpoint yang kompatibel dengan OpenAI -- Chat Completions: nonaktif secara default. Aktifkan dengan `gateway.http.endpoints.chatCompletions.enabled: true`. +- Chat Completions: dinonaktifkan secara default. Aktifkan dengan `gateway.http.endpoints.chatCompletions.enabled: true`. - Responses API: `gateway.http.endpoints.responses.enabled`. - Hardening input URL Responses: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - Allowlist kosong diperlakukan sebagai tidak disetel; gunakan `gateway.http.endpoints.responses.files.allowUrl=false` + Allowlist kosong diperlakukan sebagai tidak diatur; gunakan `gateway.http.endpoints.responses.files.allowUrl=false` dan/atau `gateway.http.endpoints.responses.images.allowUrl=false` untuk menonaktifkan pengambilan URL. - Header hardening respons opsional: - - `gateway.http.securityHeaders.strictTransportSecurity` (setel hanya untuk origin HTTPS yang Anda kendalikan; lihat [Trusted Proxy Auth](/id/gateway/trusted-proxy-auth#tls-termination-and-hsts)) + - `gateway.http.securityHeaders.strictTransportSecurity` (atur hanya untuk origin HTTPS yang Anda kendalikan; lihat [Trusted Proxy Auth](/id/gateway/trusted-proxy-auth#tls-termination-and-hsts)) ### Isolasi multi-instance -Jalankan beberapa gateway pada satu host dengan port dan state dir unik: +Jalankan beberapa gateway pada satu host dengan port dan state dir yang unik: ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -2876,10 +2887,10 @@ Lihat [Multiple Gateways](/id/gateway/multiple-gateways). } ``` -- `enabled`: mengaktifkan terminasi TLS pada listener gateway (HTTPS/WSS) (default: `false`). -- `autoGenerate`: menghasilkan otomatis pasangan cert/key self-signed lokal saat file eksplisit tidak dikonfigurasi; hanya untuk penggunaan lokal/dev. +- `enabled`: mengaktifkan terminasi TLS di listener gateway (HTTPS/WSS) (default: `false`). +- `autoGenerate`: menghasilkan otomatis pasangan cert/key self-signed lokal ketika file eksplisit tidak dikonfigurasi; hanya untuk penggunaan lokal/dev. - `certPath`: path filesystem ke file sertifikat TLS. -- `keyPath`: path filesystem ke file private key TLS; pertahankan izin yang dibatasi. +- `keyPath`: path filesystem ke file private key TLS; pertahankan izin yang terbatas. - `caPath`: path bundle CA opsional untuk verifikasi klien atau rantai trust kustom. ### `gateway.reload` @@ -2896,13 +2907,13 @@ Lihat [Multiple Gateways](/id/gateway/multiple-gateways). } ``` -- `mode`: mengontrol bagaimana edit konfigurasi diterapkan saat runtime. +- `mode`: mengontrol bagaimana edit config diterapkan saat runtime. - `"off"`: abaikan edit live; perubahan memerlukan restart eksplisit. - - `"restart"`: selalu restart proses gateway saat konfigurasi berubah. + - `"restart"`: selalu restart proses gateway saat config berubah. - `"hot"`: terapkan perubahan di dalam proses tanpa restart. - `"hybrid"` (default): coba hot reload terlebih dahulu; fallback ke restart jika diperlukan. -- `debounceMs`: jendela debounce dalam ms sebelum perubahan konfigurasi diterapkan (integer non-negatif). -- `deferralTimeoutMs`: waktu maksimum dalam ms untuk menunggu operasi yang sedang berlangsung sebelum memaksa restart (default: `300000` = 5 menit). +- `debounceMs`: jendela debounce dalam ms sebelum perubahan config diterapkan (integer non-negatif). +- `deferralTimeoutMs`: waktu maksimum dalam ms untuk menunggu operasi yang sedang berjalan sebelum memaksa restart (default: `300000` = 5 menit). --- @@ -2929,7 +2940,7 @@ Lihat [Multiple Gateways](/id/gateway/multiple-gateways). wakeMode: "now", name: "Gmail", sessionKey: "hook:gmail:{{messages[0].id}}", - messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}", + messageTemplate: "Dari: {{messages[0].from}}\nSubjek: {{messages[0].subject}}\n{{messages[0].snippet}}", deliver: true, channel: "last", model: "openai/gpt-5.4-mini", @@ -2940,7 +2951,7 @@ Lihat [Multiple Gateways](/id/gateway/multiple-gateways). ``` Auth: `Authorization: Bearer ` atau `x-openclaw-token: `. -Token hook dalam query string ditolak. +Token hook di query string ditolak. Catatan validasi dan keamanan: @@ -2953,4 +2964,11 @@ Catatan validasi dan keamanan: - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - - `sessionKey` dari payload request hanya diterima saat `hooks \ No newline at end of file + - `sessionKey` dari payload request hanya diterima ketika `hooks.allowRequestSessionKey=true` (default: `false`). +- `POST /hooks/` → di-resolve melalui `hooks.mappings` + + + +- `match.path` cocok dengan sub-path setelah `/hooks` (mis. `/hooks/gmail` → `gmail`). +- `match.source` cocok dengan field payload untuk path generik. +- Template seperti `{{messages[0].subject}}` membaca \ No newline at end of file diff --git a/docs/id/plugins/sdk-migration.md b/docs/id/plugins/sdk-migration.md index 8052f2d18..f17dc8e59 100644 --- a/docs/id/plugins/sdk-migration.md +++ b/docs/id/plugins/sdk-migration.md @@ -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. - 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. ## 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/\`) -adalah modul kecil yang mandiri dengan tujuan yang jelas dan kontrak yang terdokumentasi. +Plugin SDK modern memperbaikinya: setiap jalur impor (`openclaw/plugin-sdk/\`) +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 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. - 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: - 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.*` | @@ -158,164 +158,172 @@ Contoh provider bawaan saat ini: -## Referensi path impor +## Referensi jalur impor - - | Path impor | Tujuan | Ekspor utama | + + | 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 | -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 diff --git a/docs/id/plugins/sdk-overview.md b/docs/id/plugins/sdk-overview.md index f58f4a47c..2236e78b7 100644 --- a/docs/id/plugins/sdk-overview.md +++ b/docs/id/plugins/sdk-overview.md @@ -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) -## 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. - | 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. - | 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 | - | 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 | - - | Subpath | Export utama | + + | 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` | - - | Subpath | Export utama | + + | 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` | - | 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 | - + | 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` | ## 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` | Config khusus plugin dari `plugins.entries..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` | Config khusus plugin dari `plugins.entries..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) ``` Jangan pernah mengimpor plugin Anda sendiri melalui `openclaw/plugin-sdk/` - 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. -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 - Kode production extension juga sebaiknya menghindari import `openclaw/plugin-sdk/`. - Jika suatu helper memang benar-benar dibagikan, promosikan helper itu ke subpath SDK netral + Kode produksi extension juga sebaiknya menghindari impor `openclaw/plugin-sdk/`. + 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. ## 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 diff --git a/docs/id/tools/image-generation.md b/docs/id/tools/image-generation.md index 736f74cb1..ac017bafc 100644 --- a/docs/id/tools/image-generation.md +++ b/docs/id/tools/image-generation.md @@ -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. -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. -## 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 diff --git a/docs/id/tools/video-generation.md b/docs/id/tools/video-generation.md index d0758387e..589212245 100644 --- a/docs/id/tools/video-generation.md +++ b/docs/id/tools/video-generation.md @@ -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. -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`. -## 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 ` 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 ` 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)