From a1afd87bfe28521edb47e8eda0b02edbf342641f Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Thu, 9 Apr 2026 01:32:39 +0000 Subject: [PATCH] chore(i18n): refresh id translations --- docs/id/channels/matrix.md | 624 ++++---- docs/id/concepts/agent-loop.md | 147 +- docs/id/concepts/dreaming.md | 111 +- docs/id/concepts/memory.md | 140 +- docs/id/concepts/model-providers.md | 386 +++-- docs/id/concepts/qa-e2e-automation.md | 97 +- docs/id/gateway/cli-backends.md | 117 +- docs/id/gateway/configuration-reference.md | 1038 ++++++------- docs/id/gateway/doctor.md | 416 ++--- docs/id/help/testing.md | 504 +++--- ...refactor-real-plugin-sdk-workspace-plan.md | 584 ------- docs/id/plugins/architecture.md | 1355 +++++++++-------- docs/id/plugins/manifest.md | 360 ++--- docs/id/plugins/sdk-migration.md | 311 ++-- docs/id/plugins/sdk-overview.md | 540 +++---- docs/id/plugins/sdk-provider-plugins.md | 247 +-- docs/id/providers/inferrs.md | 72 +- docs/id/providers/qwen.md | 122 +- 18 files changed, 3386 insertions(+), 3785 deletions(-) delete mode 100644 docs/id/plans/2026-04-05-002-refactor-real-plugin-sdk-workspace-plan.md diff --git a/docs/id/channels/matrix.md b/docs/id/channels/matrix.md index 1b7852c38..a70b0df56 100644 --- a/docs/id/channels/matrix.md +++ b/docs/id/channels/matrix.md @@ -5,26 +5,24 @@ read_when: summary: Status dukungan Matrix, penyiapan, dan contoh konfigurasi title: Matrix x-i18n: - generated_at: "2026-04-08T02:16:08Z" + generated_at: "2026-04-09T01:29:46Z" model: gpt-5.4 provider: openai - source_hash: ec926df79a41fa296d63f0ec7219d0f32e075628d76df9ea490e93e4c5030f83 + source_hash: 28fc13c7620c1152200315ae69c94205da6de3180c53c814dd8ce03b5cb1758f source_path: channels/matrix.md workflow: 15 --- # Matrix -Matrix adalah plugin channel bundel Matrix untuk OpenClaw. -Plugin ini menggunakan `matrix-js-sdk` resmi dan mendukung DM, room, thread, media, reaction, polling, lokasi, dan E2EE. +Matrix adalah plugin saluran bawaan untuk OpenClaw. +Ini menggunakan `matrix-js-sdk` resmi dan mendukung DM, room, thread, media, reaksi, polling, lokasi, dan E2EE. -## Plugin bundel +## Plugin bawaan -Matrix dikirim sebagai plugin bundel di rilis OpenClaw saat ini, jadi build paket normal -tidak memerlukan instalasi terpisah. +Matrix tersedia sebagai plugin bawaan di rilis OpenClaw saat ini, jadi build paket normal tidak memerlukan instalasi terpisah. -Jika Anda menggunakan build lama atau instalasi kustom yang tidak menyertakan Matrix, instal -secara manual: +Jika Anda menggunakan build lama atau instalasi kustom yang tidak menyertakan Matrix, instal secara manual: Instal dari npm: @@ -43,15 +41,15 @@ Lihat [Plugins](/id/tools/plugin) untuk perilaku plugin dan aturan instalasi. ## Penyiapan 1. Pastikan plugin Matrix tersedia. - - Rilis OpenClaw paket saat ini sudah membundelnya. + - Rilis OpenClaw paket saat ini sudah menyertakannya. - Instalasi 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 - `homeserver` + `userId` + `password`. 4. Mulai ulang gateway. -5. Mulai DM dengan bot atau undang bot ke room. - - Undangan Matrix baru hanya berfungsi ketika `channels.matrix.autoJoin` mengizinkannya. +5. Mulai DM dengan bot atau undang ke room. + - Undangan Matrix baru hanya berfungsi jika `channels.matrix.autoJoin` mengizinkannya. Jalur penyiapan interaktif: @@ -60,32 +58,28 @@ openclaw channels add openclaw configure --section channels ``` -Yang sebenarnya ditanyakan wizard Matrix: +Wizard Matrix akan meminta: - URL homeserver -- metode auth: access token atau password -- ID pengguna hanya ketika Anda memilih auth password +- metode autentikasi: access token atau password +- ID pengguna (hanya autentikasi password) - nama perangkat opsional - apakah akan mengaktifkan E2EE -- apakah akan mengonfigurasi akses room Matrix sekarang -- apakah akan mengonfigurasi auto-join undangan Matrix sekarang -- saat auto-join undangan diaktifkan, apakah harus `allowlist`, `always`, atau `off` +- apakah akan mengonfigurasi akses room dan gabung otomatis undangan -Perilaku wizard yang penting: +Perilaku utama wizard: -- Jika env var auth Matrix sudah ada untuk akun yang dipilih, dan akun itu belum memiliki auth yang disimpan di config, wizard menawarkan pintasan env agar penyiapan dapat menyimpan auth di env vars alih-alih menyalin secret ke config. -- Saat Anda menambahkan akun Matrix lain secara interaktif, nama akun yang dimasukkan dinormalisasi menjadi ID akun yang digunakan di config dan env vars. Misalnya, `Ops Bot` menjadi `ops-bot`. -- Prompt allowlist DM langsung menerima nilai `@user:server` lengkap. Nama tampilan hanya berfungsi ketika pencarian direktori langsung menemukan satu kecocokan yang persis; jika tidak, wizard meminta Anda mencoba lagi dengan ID Matrix lengkap. -- Prompt allowlist room menerima ID room dan alias secara langsung. Prompt ini juga dapat menyelesaikan nama room yang sudah diikuti secara live, tetapi nama yang tidak terselesaikan hanya disimpan sebagaimana diketik selama penyiapan dan diabaikan nanti oleh resolusi allowlist saat runtime. Gunakan `!room:server` atau `#alias:server`. -- Wizard sekarang menampilkan peringatan eksplisit sebelum langkah auto-join undangan karena `channels.matrix.autoJoin` default-nya adalah `off`; agen tidak akan bergabung ke room yang diundang atau undangan gaya DM baru kecuali Anda mengaturnya. -- Dalam mode allowlist auto-join undangan, gunakan hanya target undangan yang stabil: `!roomId:server`, `#alias:server`, atau `*`. Nama room biasa ditolak. -- 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"`. +- Jika env vars autentikasi Matrix sudah ada dan akun tersebut belum menyimpan autentikasi di config, wizard menawarkan pintasan env untuk mempertahankan autentikasi di env vars. +- Nama akun dinormalisasi menjadi ID akun. Misalnya, `Ops Bot` menjadi `ops-bot`. +- Entri allowlist DM menerima `@user:server` secara langsung; nama tampilan hanya berfungsi saat pencarian direktori live menemukan satu kecocokan yang tepat. +- Entri allowlist room menerima ID room dan alias secara langsung. Pilih `!room:server` atau `#alias:server`; nama yang tidak dapat diselesaikan diabaikan saat runtime oleh resolusi allowlist. +- Dalam mode allowlist gabung otomatis undangan, gunakan hanya target undangan yang stabil: `!roomId:server`, `#alias:server`, atau `*`. Nama room biasa ditolak. +- Untuk menyelesaikan nama room sebelum menyimpan, gunakan `openclaw channels resolve --channel matrix "Project Room"`. -`channels.matrix.autoJoin` default-nya adalah `off`. +`channels.matrix.autoJoin` secara default adalah `off`. -Jika Anda membiarkannya tidak diatur, bot tidak akan bergabung ke room yang diundang atau undangan gaya DM baru, sehingga bot tidak akan muncul di grup baru atau DM undangan kecuali Anda bergabung secara manual terlebih dahulu. +Jika Anda membiarkannya tidak diatur, bot tidak akan bergabung ke room yang diundang atau undangan gaya DM baru, jadi bot tidak akan muncul di grup baru atau DM yang diundang kecuali Anda bergabung secara manual terlebih dahulu. Setel `autoJoin: "allowlist"` bersama `autoJoinAllowlist` untuk membatasi undangan mana yang diterima, atau setel `autoJoin: "always"` jika Anda ingin bot bergabung ke setiap undangan. @@ -155,9 +149,9 @@ Penyiapan berbasis password (token di-cache setelah login): Matrix menyimpan kredensial cache di `~/.openclaw/credentials/matrix/`. Akun default menggunakan `credentials.json`; akun bernama menggunakan `credentials-.json`. -Ketika kredensial cache ada di sana, OpenClaw memperlakukan Matrix sebagai sudah dikonfigurasi untuk penyiapan, doctor, dan penemuan status channel meskipun auth saat ini tidak disetel langsung di config. +Saat kredensial cache ada di sana, OpenClaw menganggap Matrix telah dikonfigurasi untuk penyiapan, doctor, dan penemuan status saluran meskipun autentikasi saat ini tidak diatur langsung di config. -Padanan env var (digunakan ketika key config tidak disetel): +Padanan env var (digunakan saat kunci config tidak diatur): - `MATRIX_HOMESERVER` - `MATRIX_ACCESS_TOKEN` @@ -180,19 +174,19 @@ Contoh untuk akun `ops`: - `MATRIX_OPS_HOMESERVER` - `MATRIX_OPS_ACCESS_TOKEN` -Untuk ID akun yang dinormalisasi `ops-bot`, gunakan: +Untuk ID akun ternormalisasi `ops-bot`, gunakan: - `MATRIX_OPS_X2D_BOT_HOMESERVER` - `MATRIX_OPS_X2D_BOT_ACCESS_TOKEN` -Matrix melakukan escape pada tanda baca di ID akun agar env vars bercakupan tetap bebas tabrakan. -Misalnya, `-` menjadi `_X2D_`, jadi `ops-prod` dipetakan ke `MATRIX_OPS_X2D_PROD_*`. +Matrix melakukan escape pada tanda baca di ID akun agar env vars bercakupan tetap bebas benturan. +Sebagai contoh, `-` menjadi `_X2D_`, sehingga `ops-prod` dipetakan ke `MATRIX_OPS_X2D_PROD_*`. -Wizard interaktif hanya menawarkan pintasan env-var ketika env vars auth tersebut sudah ada dan akun yang dipilih belum memiliki auth Matrix yang disimpan di config. +Wizard interaktif hanya menawarkan pintasan env-var saat env vars autentikasi tersebut sudah ada dan akun yang dipilih belum menyimpan autentikasi Matrix di config. ## Contoh konfigurasi -Ini adalah config baseline praktis dengan pairing DM, allowlist room, dan E2EE diaktifkan: +Ini adalah config dasar praktis dengan pairing DM, allowlist room, dan E2EE diaktifkan: ```json5 { @@ -227,20 +221,13 @@ 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 gaya DM baru. Pada saat undangan, OpenClaw tidak dapat mengetahui secara andal apakah -room yang diundang pada akhirnya akan diperlakukan sebagai DM atau grup, jadi semua undangan melalui keputusan -`autoJoin` yang sama terlebih dahulu. `dm.policy` tetap berlaku setelah bot bergabung dan room -diklasifikasikan sebagai DM, jadi `autoJoin` mengontrol perilaku bergabung sementara `dm.policy` mengontrol perilaku -balasan/akses. +`autoJoin` berlaku untuk semua undangan Matrix, termasuk undangan bergaya DM. OpenClaw tidak dapat secara andal mengklasifikasikan room yang diundang sebagai DM atau grup pada saat undangan, jadi semua undangan diproses melalui `autoJoin` terlebih dahulu. `dm.policy` berlaku setelah bot bergabung dan room diklasifikasikan sebagai DM. ## Pratinjau streaming Streaming balasan Matrix bersifat opt-in. -Setel `channels.matrix.streaming` ke `"partial"` ketika Anda ingin OpenClaw mengirim satu balasan -pratinjau langsung, mengedit pratinjau itu di tempat saat model sedang menghasilkan teks, lalu memfinalkannya saat -balasan selesai: +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 balasan selesai: ```json5 { @@ -252,36 +239,35 @@ balasan selesai: } ``` -- `streaming: "off"` adalah default. OpenClaw menunggu balasan akhir lalu 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 pratinjau-dulu Matrix lama, sehingga klien bawaan dapat mengirim notifikasi pada teks pratinjau streaming pertama, bukan blok yang sudah selesai. -- `streaming: "quiet"` membuat satu pemberitahuan pratinjau senyap yang dapat diedit untuk blok asisten saat ini. Gunakan ini hanya ketika Anda juga mengonfigurasi aturan push penerima untuk edit pratinjau yang sudah difinalkan. -- `blockStreaming: true` mengaktifkan pesan progres Matrix terpisah. Dengan streaming pratinjau diaktifkan, Matrix menyimpan 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 akhir normal. -- Balasan media tetap mengirim lampiran seperti biasa. Jika pratinjau usang tidak lagi dapat digunakan kembali dengan aman, OpenClaw meredaksinya sebelum mengirim balasan media akhir. -- Edit pratinjau memerlukan panggilan API Matrix tambahan. Biarkan streaming nonaktif jika Anda menginginkan perilaku rate limit yang paling konservatif. +- `streaming: "off"` adalah default. OpenClaw menunggu balasan akhir dan mengirimnya 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 warisan Matrix yang mengutamakan pratinjau, sehingga klien bawaan dapat memberi notifikasi pada teks pratinjau pertama yang di-stream alih-alih blok yang telah selesai. +- `streaming: "quiet"` membuat satu pemberitahuan pratinjau senyap yang dapat diedit untuk blok asisten saat ini. Gunakan ini hanya jika Anda juga mengonfigurasi aturan push penerima untuk edit pratinjau yang telah difinalkan. +- `blockStreaming: true` mengaktifkan pesan progres Matrix terpisah. Dengan streaming pratinjau aktif, Matrix mempertahankan draf live untuk blok saat ini dan menyimpan blok yang telah 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. +- 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 basi tidak lagi dapat digunakan kembali dengan aman, OpenClaw akan meredaksinya sebelum mengirim balasan media final. +- Edit pratinjau menimbulkan panggilan API Matrix tambahan. Biarkan streaming nonaktif jika Anda menginginkan perilaku rate-limit yang paling konservatif. -`blockStreaming` tidak mengaktifkan pratinjau draft dengan sendirinya. +`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 asisten yang sudah selesai tetap terlihat sebagai pesan progres terpisah. -Jika Anda memerlukan notifikasi Matrix bawaan tanpa aturan push kustom, gunakan `streaming: "partial"` untuk perilaku pratinjau-dulu atau biarkan `streaming` nonaktif untuk pengiriman akhir saja. Dengan `streaming: "off"`: +Jika Anda memerlukan notifikasi Matrix bawaan tanpa aturan push kustom, gunakan `streaming: "partial"` untuk perilaku yang mengutamakan pratinjau 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 yang senyap +### Aturan push self-hosted untuk pratinjau final senyap -Jika Anda menjalankan infrastruktur Matrix sendiri dan ingin pratinjau senyap hanya memicu notifikasi saat blok atau -balasan akhir 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 hanya memberi notifikasi saat satu blok atau balasan akhir selesai, setel `streaming: "quiet"` dan tambahkan aturan push per pengguna untuk edit pratinjau yang telah difinalkan. -Biasanya ini adalah penyiapan pengguna penerima, bukan perubahan config global homeserver: +Ini biasanya merupakan penyiapan pengguna penerima, bukan perubahan config global homeserver: -Peta singkat sebelum memulai: +Pemetaan cepat sebelum memulai: - 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 +- cocokan `sender` dalam aturan push dengan MXID lengkap pengguna bot 1. Konfigurasikan OpenClaw untuk menggunakan pratinjau senyap: @@ -295,12 +281,11 @@ Peta singkat sebelum memulai: } ``` -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. Aturan 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 ada biasanya paling mudah. + - Menggunakan kembali token sesi klien yang ada biasanya paling mudah. - Jika Anda perlu membuat token baru, Anda dapat login melalui API Client-Server Matrix standar: ```bash @@ -325,10 +310,9 @@ curl -sS \ "https://matrix.example.org/_matrix/client/v3/pushers" ``` -Jika ini tidak mengembalikan pusher/perangkat aktif, perbaiki notifikasi Matrix normal terlebih dahulu sebelum menambahkan -aturan OpenClaw di bawah. +Jika ini tidak mengembalikan pusher/perangkat aktif, perbaiki notifikasi Matrix normal terlebih dahulu sebelum menambahkan aturan OpenClaw di bawah. -OpenClaw menandai edit pratinjau final teks-saja dengan: +OpenClaw menandai edit pratinjau teks-saja yang telah difinalkan dengan: ```json { @@ -366,25 +350,25 @@ curl -sS -X PUT \ }' ``` -Ganti nilai ini sebelum Anda menjalankan perintah: +Ganti nilai-nilai ini sebelum menjalankan perintah: - `https://matrix.example.org`: URL dasar homeserver Anda - `$USER_ACCESS_TOKEN`: access token pengguna penerima -- `openclaw-finalized-preview-botname`: rule ID yang unik untuk bot ini bagi pengguna penerima ini +- `openclaw-finalized-preview-botname`: ID aturan 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 `ruleId` sebagai key. Menjalankan ulang `PUT` terhadap rule ID yang sama akan memperbarui satu aturan tersebut. -- Jika satu pengguna penerima harus menerima notifikasi untuk beberapa akun bot Matrix OpenClaw, buat satu aturan per bot dengan rule ID unik untuk setiap kecocokan sender. +- Aturan push diindeks berdasarkan `ruleId`. Menjalankan kembali `PUT` terhadap ID aturan yang sama akan memperbarui aturan itu. +- Jika satu pengguna penerima harus memberi notifikasi untuk beberapa akun bot Matrix OpenClaw, buat satu aturan per bot dengan ID aturan unik untuk setiap kecocokan sender. - Pola sederhana adalah `openclaw-finalized-preview-`, seperti `openclaw-finalized-preview-ops` atau `openclaw-finalized-preview-support`. Aturan dievaluasi terhadap pengirim event: - autentikasi dengan token pengguna penerima -- cocokkan `sender` dengan MXID bot OpenClaw +- cocokan `sender` dengan MXID bot OpenClaw -6. Verifikasi bahwa aturan ada: +6. Verifikasi bahwa aturan tersebut ada: ```bash curl -sS \ @@ -392,10 +376,9 @@ curl -sS \ "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" ``` -7. Uji balasan streaming. Dalam mode senyap, room harus menampilkan pratinjau draft senyap dan edit akhir - di tempat harus memicu notifikasi saat blok atau giliran selesai. +7. Uji balasan yang di-stream. Dalam mode senyap, room seharusnya menampilkan pratinjau draf senyap dan edit final di tempat seharusnya memberi notifikasi saat blok atau giliran selesai. -Jika Anda perlu menghapus aturan nanti, hapus rule ID yang sama itu dengan token pengguna penerima: +Jika Anda perlu menghapus aturan nanti, hapus ID aturan yang sama dengan token pengguna penerima: ```bash curl -sS -X DELETE \ @@ -406,36 +389,32 @@ curl -sS -X DELETE \ Catatan: - Buat aturan dengan access token pengguna penerima, bukan token bot. -- Aturan `override` buatan pengguna yang baru dimasukkan di depan aturan penekanan default, jadi tidak perlu 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. +- Aturan `override` baru yang ditentukan pengguna dimasukkan sebelum aturan penekanan default, jadi tidak diperlukan parameter pengurutan tambahan. +- Ini hanya memengaruhi edit pratinjau teks-saja yang dapat difinalkan OpenClaw dengan aman di tempat. Fallback media dan fallback pratinjau basi tetap menggunakan pengiriman Matrix normal. +- Jika `GET /_matrix/client/v3/pushers` tidak menampilkan pusher, berarti 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 final. +- 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 utama. -- Jika Anda menjalankan Synapse di belakang reverse proxy atau worker, pastikan `/_matrix/client/.../pushrules/` mencapai Synapse dengan benar. +- 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 `pushrules` yang sama seperti yang ditunjukkan 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 marker pratinjau final itu sendiri. -- Jika notifikasi Matrix normal sudah berfungsi untuk pengguna itu, token pengguna + panggilan `pushrules` di atas adalah langkah penyiapan utama. -- 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 sedang aktif. +- Tidak diperlukan config khusus Tuwunel untuk penanda pratinjau yang telah 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 secara sengaja menekan push ke perangkat lain saat satu perangkat aktif. -## Enkripsi dan verifikasi +## Room bot-ke-bot -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. +Secara default, pesan Matrix dari akun Matrix OpenClaw lain yang dikonfigurasi diabaikan. -### Room bot ke bot - -Secara default, pesan Matrix dari akun Matrix OpenClaw lain yang telah dikonfigurasi akan diabaikan. - -Gunakan `allowBots` ketika Anda memang menginginkan lalu lintas Matrix antar-agen: +Gunakan `allowBots` saat Anda memang menginginkan lalu lintas Matrix antar-agen: ```json5 { @@ -452,14 +431,18 @@ Gunakan `allowBots` ketika Anda memang menginginkan lalu lintas Matrix antar-age } ``` -- `allowBots: true` menerima pesan dari akun bot Matrix terkonfigurasi lain di room dan DM yang diizinkan. -- `allowBots: "mentions"` hanya menerima pesan tersebut ketika pesan itu secara terlihat menyebut bot ini di room. DM tetap diizinkan. -- `groups..allowBots` menimpa pengaturan tingkat akun untuk satu room. -- OpenClaw tetap mengabaikan pesan dari user ID Matrix yang sama untuk menghindari loop balasan ke diri sendiri. -- Matrix tidak mengekspos flag bot bawaan di sini; OpenClaw memperlakukan "ditulis bot" sebagai "dikirim oleh akun Matrix lain yang telah dikonfigurasi pada gateway OpenClaw ini". +- `allowBots: true` menerima pesan dari akun bot Matrix lain yang dikonfigurasi di room dan DM yang diizinkan. +- `allowBots: "mentions"` menerima pesan tersebut hanya saat mereka secara terlihat menyebut bot ini di room. DM tetap diizinkan. +- `groups..allowBots` menimpa setelan tingkat akun untuk satu room. +- OpenClaw tetap mengabaikan pesan dari ID pengguna Matrix yang sama untuk menghindari loop balasan diri. +- 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. +## Enkripsi dan verifikasi + +Di room terenkripsi (E2EE), event gambar keluar menggunakan `thumbnail_file` sehingga pratinjau gambar terenkripsi bersama lampiran penuh. Room tidak terenkripsi tetap menggunakan `thumbnail_url` biasa. Tidak diperlukan konfigurasi — plugin mendeteksi status E2EE secara otomatis. + Aktifkan enkripsi: ```json5 @@ -500,8 +483,6 @@ Bootstrap cross-signing dan status verifikasi: openclaw matrix verify bootstrap ``` -Dukungan multi-akun: gunakan `channels.matrix.accounts` dengan kredensial per akun dan `name` opsional. Lihat [Referensi konfigurasi](/id/gateway/configuration-reference#multi-account-all-channels) untuk pola bersama. - Diagnostik bootstrap verbose: ```bash @@ -550,18 +531,16 @@ Diagnostik pemulihan verbose: openclaw matrix verify backup restore --verbose ``` -Hapus backup server saat ini dan buat baseline backup baru. Jika key backup yang tersimpan -tidak dapat dimuat dengan bersih, reset ini juga dapat membuat ulang secret storage sehingga -cold start mendatang dapat memuat key backup yang baru: +Hapus backup server saat ini dan buat baseline backup baru. Jika key backup yang tersimpan tidak dapat dimuat dengan bersih, reset ini juga dapat membuat ulang secret storage sehingga cold start mendatang dapat memuat key backup baru: ```bash openclaw matrix verify backup reset --yes ``` 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 script. +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 `. +Dalam penyiapan multi-akun, perintah CLI Matrix menggunakan akun default Matrix implisit kecuali Anda memberikan `--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: @@ -571,43 +550,40 @@ openclaw matrix verify backup restore --account assistant openclaw matrix devices list --account assistant ``` -Ketika enkripsi dinonaktifkan atau tidak tersedia untuk akun bernama, peringatan Matrix dan error verifikasi menunjuk ke key config akun tersebut, misalnya `channels.matrix.accounts.assistant.encryption`. +Saat enkripsi dinonaktifkan atau tidak tersedia untuk akun bernama, peringatan Matrix dan error verifikasi menunjuk ke kunci config akun tersebut, misalnya `channels.matrix.accounts.assistant.encryption`. -### Apa arti "verified" +### Arti "verified" -OpenClaw memperlakukan perangkat Matrix ini sebagai terverifikasi hanya ketika perangkat ini diverifikasi oleh identitas cross-signing Anda sendiri. +OpenClaw memperlakukan perangkat Matrix ini sebagai terverifikasi hanya jika perangkat tersebut 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 sebagai terverifikasi melalui cross-signing -- `Signed by owner`: perangkat ini ditandatangani oleh self-signing key milik Anda sendiri +- `Signed by owner`: perangkat ditandatangani oleh self-signing key Anda sendiri -`Verified by owner` menjadi `yes` hanya ketika verifikasi cross-signing atau owner-signing ada. -Kepercayaan lokal saja tidak cukup agar OpenClaw memperlakukan perangkat sebagai sepenuhnya terverifikasi. +`Verified by owner` menjadi `yes` hanya saat verifikasi cross-signing atau owner-signing ada. +Kepercayaan lokal saja tidak cukup bagi OpenClaw untuk memperlakukan perangkat sebagai sepenuhnya terverifikasi. -### Apa yang dilakukan bootstrap +### Fungsi bootstrap `openclaw matrix verify bootstrap` adalah perintah perbaikan dan penyiapan untuk akun Matrix terenkripsi. Perintah ini melakukan semua hal berikut secara berurutan: -- melakukan bootstrap secret storage, menggunakan kembali recovery key yang ada bila memungkinkan -- melakukan bootstrap cross-signing dan mengunggah public cross-signing keys yang belum ada -- mencoba menandai dan melakukan cross-sign pada perangkat saat ini +- mem-bootstrap secret storage, menggunakan kembali recovery key yang ada bila memungkinkan +- mem-bootstrap cross-signing dan mengunggah public cross-signing keys yang hilang +- mencoba menandai dan men-cross-sign perangkat saat ini - membuat backup room-key sisi server baru jika belum ada -Jika homeserver memerlukan auth interaktif untuk mengunggah cross-signing keys, OpenClaw mencoba pengunggahan tanpa auth terlebih dahulu, lalu dengan `m.login.dummy`, lalu dengan `m.login.password` saat `channels.matrix.password` dikonfigurasi. +Jika homeserver memerlukan autentikasi interaktif untuk mengunggah cross-signing keys, OpenClaw mencoba unggah tanpa autentikasi terlebih dahulu, lalu dengan `m.login.dummy`, lalu dengan `m.login.password` saat `channels.matrix.password` dikonfigurasi. -Gunakan `--force-reset-cross-signing` hanya ketika Anda memang ingin membuang identitas cross-signing saat ini dan membuat yang baru. +Gunakan `--force-reset-cross-signing` hanya saat 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 di masa mendatang, gunakan `openclaw matrix verify backup reset --yes`. -Lakukan ini hanya jika Anda menerima bahwa riwayat terenkripsi lama yang tidak dapat dipulihkan akan tetap -tidak tersedia dan bahwa OpenClaw mungkin membuat ulang secret storage jika secret backup saat ini -tidak dapat dimuat dengan aman. +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 tidak tersedia dan bahwa OpenClaw dapat membuat ulang secret storage jika rahasia backup saat ini tidak dapat dimuat dengan aman. ### Baseline backup baru -Jika Anda ingin menjaga pesan terenkripsi di masa depan tetap berfungsi dan menerima kehilangan riwayat lama yang tidak dapat dipulihkan, jalankan perintah ini secara berurutan: +Jika Anda ingin menjaga agar pesan terenkripsi mendatang tetap berfungsi dan menerima kehilangan riwayat lama yang tidak dapat dipulihkan, jalankan perintah ini secara berurutan: ```bash openclaw matrix verify backup reset --yes @@ -615,96 +591,41 @@ openclaw matrix verify backup status --verbose openclaw matrix verify status ``` -Tambahkan `--account ` ke setiap perintah ketika Anda ingin menargetkan akun Matrix bernama secara eksplisit. +Tambahkan `--account ` ke setiap perintah jika Anda ingin secara eksplisit menargetkan akun Matrix bernama. ### Perilaku startup -Saat `encryption: true`, Matrix default `startupVerification` ke `"if-unverified"`. -Saat startup, jika perangkat ini masih belum terverifikasi, Matrix akan meminta verifikasi mandiri di klien Matrix lain, -melewati permintaan duplikat saat satu sudah tertunda, dan menerapkan cooldown lokal sebelum mencoba lagi setelah restart. -Upaya permintaan yang gagal mencoba ulang lebih cepat daripada pembuatan permintaan yang berhasil secara default. -Setel `startupVerification: "off"` untuk menonaktifkan permintaan startup otomatis, atau sesuaikan `startupVerificationCooldownHours` -jika Anda menginginkan jendela percobaan ulang yang lebih pendek atau lebih panjang. +Saat `encryption: true`, Matrix secara default mengatur `startupVerification` ke `"if-unverified"`. +Saat startup, jika perangkat ini masih belum terverifikasi, Matrix akan meminta self-verification di klien Matrix lain, melewati permintaan duplikat saat satu sudah tertunda, dan menerapkan cooldown lokal sebelum mencoba lagi setelah restart. +Secara default, upaya permintaan yang gagal dicoba ulang 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. -Startup juga menjalankan proses bootstrap crypto konservatif secara otomatis. -Proses itu mencoba menggunakan kembali secret storage dan identitas cross-signing saat ini terlebih dahulu, dan menghindari reset cross-signing kecuali Anda menjalankan alur perbaikan bootstrap eksplisit. +Startup juga melakukan pass bootstrap crypto konservatif secara otomatis. +Pass itu mencoba menggunakan kembali secret storage dan identitas cross-signing saat ini terlebih dahulu, dan menghindari reset cross-signing kecuali Anda menjalankan alur perbaikan bootstrap 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 owner, OpenClaw mempertahankan identitas itu alih-alih meresetnya secara otomatis. -Upgrade dari plugin Matrix publik sebelumnya: +Lihat [Migrasi Matrix](/id/install/migrating-matrix) untuk alur upgrade lengkap, batasan, perintah pemulihan, dan pesan migrasi umum. -- OpenClaw secara otomatis menggunakan kembali akun Matrix, access token, dan identitas perangkat yang sama bila memungkinkan. -- Sebelum perubahan migrasi Matrix yang dapat ditindaklanjuti dijalankan, OpenClaw membuat atau menggunakan kembali 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 mengetahui akun mana yang harus menerima state lama 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 serumpun untuk state pemulihan lama 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 kembali root penyimpanan hash token yang paling lengkap yang sudah ada daripada memulai dari direktori state Matrix kosong. -- Pada start gateway berikutnya, room key yang sudah di-backup dipulihkan secara otomatis ke crypto store baru. -- Jika plugin lama memiliki room key lokal saja yang tidak pernah di-backup, OpenClaw akan memberi peringatan dengan jelas. Key tersebut tidak dapat diekspor secara otomatis dari rust crypto store sebelumnya, jadi beberapa riwayat terenkripsi lama mungkin tetap tidak tersedia sampai dipulihkan secara manual. -- Lihat [Migrasi Matrix](/id/install/migrating-matrix) untuk alur upgrade lengkap, batasan, perintah pemulihan, dan pesan migrasi umum. +### Pemberitahuan verifikasi -State runtime terenkripsi diatur di bawah root hash token per akun dan per pengguna di -`~/.openclaw/matrix/accounts//__//`. -Direktori itu berisi sync store (`bot-storage.json`), crypto store (`crypto/`), -file recovery key (`recovery-key.json`), snapshot IndexedDB (`crypto-idb-snapshot.json`), -thread binding (`thread-bindings.json`), dan state verifikasi startup (`startup-verification.json`) -ketika fitur tersebut digunakan. -Ketika token berubah tetapi identitas akun tetap sama, OpenClaw menggunakan kembali root yang ada terbaik -untuk tuple akun/homeserver/pengguna tersebut sehingga state sync sebelumnya, state crypto, thread binding, -dan state verifikasi startup tetap terlihat. - -### Model crypto store Node - -Matrix E2EE di plugin ini menggunakan jalur Rust crypto resmi `matrix-js-sdk` di Node. -Jalur itu mengharapkan persistensi berbasis IndexedDB ketika Anda ingin state crypto tetap bertahan setelah restart. - -Saat ini OpenClaw menyediakannya di Node dengan cara: - -- menggunakan `fake-indexeddb` sebagai shim API IndexedDB yang diharapkan SDK -- memulihkan isi IndexedDB Rust crypto dari `crypto-idb-snapshot.json` sebelum `initRustCrypto` -- mempertahankan isi IndexedDB yang diperbarui kembali ke `crypto-idb-snapshot.json` setelah init dan selama runtime -- melakukan serialisasi 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, jadi ini terutama merupakan masalah durabilitas operasional, bukan batas kepercayaan remote yang terpisah. - -Peningkatan yang direncanakan: - -- menambahkan dukungan SecretRef untuk material key Matrix persisten sehingga recovery key dan secret enkripsi penyimpanan terkait dapat bersumber dari penyedia secret OpenClaw, bukan hanya file lokal - -## Manajemen profil - -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. - -Matrix menerima URL avatar `mxc://` secara langsung. Saat Anda meneruskan URL avatar `http://` atau `https://`, OpenClaw akan mengunggahnya ke Matrix terlebih dahulu dan menyimpan kembali URL `mxc://` yang sudah diselesaikan 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`. +Matrix memposting pemberitahuan siklus hidup verifikasi langsung ke room verifikasi DM ketat sebagai pesan `m.notice`. Itu 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 +- mulai dan selesai verifikasi +- detail SAS (emoji dan desimal) saat tersedia -Permintaan verifikasi masuk dari klien Matrix lain dilacak dan diterima secara otomatis oleh OpenClaw. -Untuk alur verifikasi mandiri, OpenClaw juga memulai alur SAS secara otomatis ketika verifikasi emoji tersedia dan mengonfirmasi sisi miliknya sendiri. +Permintaan verifikasi masuk dari klien Matrix lain dilacak dan diterima otomatis oleh OpenClaw. +Untuk alur self-verification, 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. Anda tetap perlu membandingkan emoji atau SAS desimal di klien Matrix Anda dan mengonfirmasi "They match" di sana untuk menyelesaikan verifikasi. -OpenClaw tidak secara buta menerima alur duplikat yang dimulai sendiri. Startup melewati pembuatan permintaan baru ketika permintaan verifikasi mandiri sudah tertunda. +OpenClaw tidak serta-merta menerima otomatis alur duplikat yang dimulai sendiri secara buta. Startup melewati pembuatan permintaan baru saat permintaan self-verification sudah tertunda. -Pemberitahuan protokol/sistem verifikasi tidak diteruskan ke pipeline chat agen, sehingga tidak menghasilkan `NO_REPLY`. +Pemberitahuan protokol/sistem verifikasi tidak diteruskan ke pipeline chat agen, jadi tidak menghasilkan `NO_REPLY`. ### Kebersihan perangkat @@ -715,73 +636,77 @@ Daftarkan dengan: openclaw matrix devices list ``` -Hapus perangkat yang dikelola OpenClaw dan sudah usang dengan: +Hapus perangkat basi yang dikelola OpenClaw dengan: ```bash openclaw matrix devices prune-stale ``` -### Perbaikan Room Langsung +### Penyimpanan crypto -Jika state direct-message tidak sinkron, OpenClaw dapat berakhir dengan pemetaan `m.direct` usang yang menunjuk ke solo room lama alih-alih DM aktif. Periksa pemetaan saat ini untuk peer dengan: +Matrix E2EE menggunakan jalur Rust crypto `matrix-js-sdk` resmi di Node, dengan `fake-indexeddb` sebagai shim IndexedDB. Status crypto dipertahankan ke file snapshot (`crypto-idb-snapshot.json`) dan dipulihkan saat startup. File snapshot adalah status runtime sensitif yang disimpan dengan izin file yang ketat. + +Status runtime terenkripsi berada di bawah root per-akun, per-pengguna, per-hash-token di +`~/.openclaw/matrix/accounts//__//`. +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 status verifikasi startup (`startup-verification.json`). +Saat token berubah tetapi identitas akun tetap sama, OpenClaw menggunakan kembali root terbaik yang ada +untuk tupel akun/homeserver/pengguna tersebut sehingga status sinkronisasi sebelumnya, status crypto, binding thread, +dan status verifikasi startup tetap terlihat. + +## Manajemen profil + +Perbarui self-profile Matrix untuk akun yang dipilih dengan: ```bash -openclaw matrix direct inspect --user-id @alice:example.org +openclaw matrix profile set --name "OpenClaw Assistant" +openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png ``` -Perbaiki dengan: +Tambahkan `--account ` jika Anda ingin secara eksplisit menargetkan akun Matrix bernama. -```bash -openclaw matrix direct repair --user-id @alice:example.org -``` - -Perbaikan menjaga logika khusus Matrix tetap di dalam plugin: - -- perbaikan lebih memilih DM 1:1 ketat yang sudah dipetakan di `m.direct` -- jika tidak, perbaikan kembali ke DM 1:1 ketat yang saat ini diikuti dengan pengguna itu -- jika tidak ada DM sehat, perbaikan membuat direct room baru dan menulis ulang `m.direct` agar menunjuk ke room itu - -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 lainnya menargetkan room yang benar lagi. +Matrix menerima URL avatar `mxc://` secara langsung. Saat Anda memberikan 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). ## Thread -Matrix mendukung thread Matrix native untuk balasan otomatis maupun pengiriman message-tool. +Matrix mendukung thread Matrix asli untuk balasan otomatis maupun pengiriman message-tool. -- `dm.sessionScope: "per-user"` (default) menjaga perutean DM Matrix tetap berbasis pengirim, sehingga beberapa room DM dapat berbagi satu sesi saat semuanya diselesaikan ke peer yang sama. -- `dm.sessionScope: "per-room"` mengisolasi setiap room DM Matrix ke key sesinya sendiri sambil tetap menggunakan auth DM normal dan pemeriksaan allowlist. -- Binding percakapan Matrix eksplisit tetap menang atas `dm.sessionScope`, sehingga room dan thread yang dibinding mempertahankan sesi target pilihannya. -- `threadReplies: "off"` menjaga balasan tetap top-level dan menjaga pesan thread masuk pada sesi induk. -- `threadReplies: "inbound"` membalas di dalam thread hanya ketika pesan masuk memang sudah berada di thread itu. -- `threadReplies: "always"` menjaga balasan room tetap dalam thread yang berakar pada pesan pemicu dan merutekan percakapan itu melalui sesi bercakupan 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 thread masuk menyertakan pesan root thread sebagai konteks agen 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 sesi-sama hanya aktif ketika metadata sesi saat ini membuktikan peer DM yang sama pada akun Matrix yang sama; jika tidak, OpenClaw kembali ke perutean normal berbasis 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 tersebut dengan jalur keluar `/focus` saat thread binding diaktifkan dan petunjuk `dm.sessionScope`. -- Binding thread runtime didukung untuk Matrix. `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, dan `/acp spawn` yang dibinding thread kini berfungsi di room dan DM Matrix. -- `/focus` room/DM Matrix top-level membuat thread Matrix baru dan membindkannya ke sesi target ketika `threadBindings.spawnSubagentSessions=true`. -- Menjalankan `/focus` atau `/acp spawn --thread here` di dalam thread Matrix yang sudah ada akan membinding thread saat ini itu. +- `dm.sessionScope: "per-user"` (default) menjaga routing DM Matrix tetap berbasis pengirim, sehingga beberapa room DM dapat berbagi satu sesi saat semuanya mengarah ke peer yang sama. +- `dm.sessionScope: "per-room"` mengisolasi setiap room DM Matrix ke dalam kunci sesinya sendiri sambil tetap menggunakan pemeriksaan autentikasi DM dan allowlist normal. +- Binding percakapan Matrix eksplisit tetap menang atas `dm.sessionScope`, sehingga room dan thread yang terikat mempertahankan sesi target yang dipilih. +- `threadReplies: "off"` menjaga balasan tetap level atas dan menjaga pesan thread masuk tetap pada sesi induk. +- `threadReplies: "inbound"` membalas di dalam thread hanya jika pesan masuk sudah berada di thread tersebut. +- `threadReplies: "always"` menjaga balasan room dalam thread yang berakar pada pesan pemicu dan merutekan percakapan itu melalui sesi bercakupan thread yang cocok dari pesan pemicu pertama. +- `dm.threadReplies` menimpa setelan tingkat atas hanya untuk DM. Misalnya, Anda dapat menjaga thread room tetap terisolasi sambil menjaga DM tetap datar. +- Pesan thread masuk menyertakan pesan akar thread sebagai konteks agen tambahan. +- Pengiriman message-tool otomatis mewarisi thread Matrix saat ini ketika target adalah room yang sama, atau target pengguna DM yang sama, kecuali `threadId` eksplisit diberikan. +- Penggunaan ulang target pengguna DM dengan sesi yang sama hanya berlaku saat metadata sesi saat ini membuktikan peer DM yang sama pada akun Matrix yang sama; jika tidak, OpenClaw kembali ke routing normal dengan cakupan 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 escape hatch `/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 terikat thread berfungsi di room dan DM Matrix. +- `/focus` level atas pada 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. ## Binding percakapan ACP -Room Matrix, DM, dan thread Matrix yang sudah ada dapat diubah menjadi workspace ACP yang tahan lama tanpa mengubah permukaan chat. +Room, DM, dan thread Matrix yang sudah ada dapat diubah menjadi workspace ACP yang tahan lama tanpa mengubah permukaan chat. Alur operator cepat: - 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 top-level, DM/room saat ini tetap menjadi permukaan chat dan pesan berikutnya dirutekan ke sesi ACP yang dihasilkan. -- Di dalam thread Matrix yang sudah ada, `--bind here` membinding thread saat ini di tempat. +- Di DM atau room Matrix level atas, DM/room saat ini tetap menjadi permukaan chat dan pesan mendatang dirutekan ke sesi ACP yang dibuat. +- 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. +- `--bind here` tidak membuat thread Matrix anak. +- `threadBindings.spawnAcpSessions` hanya diperlukan untuk `/acp spawn --thread auto|here`, saat OpenClaw perlu membuat atau mengikat thread Matrix anak. -### Konfigurasi Thread Binding +### Config binding thread -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` @@ -789,67 +714,66 @@ Matrix mewarisi default global dari `session.threadBindings`, dan juga mendukung - `threadBindings.spawnSubagentSessions` - `threadBindings.spawnAcpSessions` -Flag spawn terikat-thread Matrix bersifat opt-in: +Flag pembuatan thread-bound Matrix bersifat opt-in: -- Setel `threadBindings.spawnSubagentSessions: true` untuk mengizinkan `/focus` top-level membuat dan membinding thread Matrix baru. -- Setel `threadBindings.spawnAcpSessions: true` untuk mengizinkan `/acp spawn --thread auto|here` membinding sesi ACP ke thread Matrix. +- Setel `threadBindings.spawnSubagentSessions: true` untuk mengizinkan `/focus` level atas membuat dan mengikat thread Matrix baru. +- Setel `threadBindings.spawnAcpSessions: true` untuk mengizinkan `/acp spawn --thread auto|here` mengikat sesi ACP ke thread Matrix. -## Reaction +## Reaksi -Matrix mendukung action reaction keluar, pemberitahuan reaction masuk, dan reaction ack masuk. +Matrix mendukung aksi reaksi keluar, notifikasi reaksi masuk, dan reaksi ack masuk. -- Tooling reaction keluar dibatasi oleh `channels["matrix"].actions.reactions`. -- `react` menambahkan reaction ke event Matrix tertentu. -- `reactions` mencantumkan ringkasan reaction saat ini untuk event Matrix tertentu. -- `emoji=""` menghapus reaction milik akun bot sendiri pada event itu. -- `remove: true` hanya menghapus reaction emoji yang ditentukan dari akun bot. +- Tooling reaksi keluar dibatasi oleh `channels["matrix"].actions.reactions`. +- `react` menambahkan reaksi ke event Matrix tertentu. +- `reactions` menampilkan ringkasan reaksi saat ini untuk event Matrix tertentu. +- `emoji=""` menghapus reaksi milik akun bot sendiri pada event tersebut. +- `remove: true` hanya menghapus reaksi emoji yang ditentukan dari akun bot. -Cakupan reaction ack diselesaikan dalam urutan standar OpenClaw: +Cakupan reaksi ack diselesaikan dengan urutan resolusi OpenClaw standar: - `channels["matrix"].accounts..ackReaction` - `channels["matrix"].ackReaction` - `messages.ackReaction` - fallback emoji identitas agen -Cakupan reaction ack diselesaikan dalam urutan ini: +Cakupan ack reaction diselesaikan dengan urutan ini: - `channels["matrix"].accounts..ackReactionScope` - `channels["matrix"].ackReactionScope` - `messages.ackReactionScope` -Mode pemberitahuan reaction diselesaikan dalam urutan ini: +Mode notifikasi reaksi diselesaikan dengan urutan ini: - `channels["matrix"].accounts..reactionNotifications` - `channels["matrix"].reactionNotifications` - default: `own` -Perilaku saat ini: +Perilaku: -- `reactionNotifications: "own"` meneruskan event `m.reaction` yang ditambahkan ketika event tersebut menargetkan pesan Matrix yang ditulis bot. -- `reactionNotifications: "off"` menonaktifkan event sistem reaction. -- Penghapusan reaction masih belum disintesis menjadi event sistem karena Matrix menampilkannya sebagai redaksi, bukan sebagai penghapusan `m.reaction` mandiri. +- `reactionNotifications: "own"` meneruskan event `m.reaction` yang ditambahkan saat menargetkan pesan Matrix yang ditulis bot. +- `reactionNotifications: "off"` menonaktifkan event sistem reaksi. +- Penghapusan reaksi tidak disintesis menjadi event sistem karena Matrix menampilkan itu sebagai redaksi, bukan sebagai penghapusan `m.reaction` mandiri. ## Konteks riwayat -- `channels.matrix.historyLimit` mengontrol berapa banyak pesan room terbaru yang disertakan sebagai `InboundHistory` saat pesan room Matrix memicu agen. -- Nilai ini fallback ke `messages.groupChat.historyLimit`. Jika keduanya tidak disetel, default efektifnya adalah `0`, sehingga pesan room yang dibatasi mention tidak dibuffer. Setel `0` untuk menonaktifkan. -- Riwayat room Matrix hanya untuk room. DM tetap menggunakan riwayat sesi normal. -- Riwayat room Matrix bersifat pending-only: OpenClaw membuffer pesan room yang belum memicu balasan, lalu mengambil snapshot jendela itu saat 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 kembali snapshot riwayat asli alih-alih bergeser maju ke pesan room yang lebih baru. +- `channels.matrix.historyLimit` mengontrol berapa banyak pesan room terbaru yang disertakan sebagai `InboundHistory` saat pesan room Matrix memicu agen. Fallback ke `messages.groupChat.historyLimit`; jika keduanya tidak diatur, default efektifnya adalah `0`. Setel `0` untuk menonaktifkan. +- Riwayat room Matrix hanya berlaku untuk room. DM tetap menggunakan riwayat sesi normal. +- Riwayat room Matrix bersifat pending-only: OpenClaw membuffer pesan room yang belum memicu balasan, lalu mengambil snapshot jendela itu saat mention atau pemicu lain tiba. +- Pesan pemicu saat ini tidak disertakan dalam `InboundHistory`; pesan tersebut tetap berada di body masuk utama untuk giliran itu. +- Pengulangan event Matrix yang sama menggunakan kembali snapshot riwayat asli alih-alih bergeser maju ke pesan room yang lebih baru. ## Visibilitas konteks -Matrix mendukung kontrol bersama `contextVisibility` 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, akar thread, dan riwayat tertunda. -- `contextVisibility: "all"` adalah default. Konteks tambahan dipertahankan sebagaimana diterima. +- `contextVisibility: "all"` adalah default. Konteks tambahan disimpan 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. -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. +Setelan ini memengaruhi visibilitas konteks tambahan, bukan apakah pesan masuk itu sendiri dapat memicu balasan. +Otorisasi pemicu tetap berasal dari `groupPolicy`, `groups`, `groupAllowFrom`, dan setelan kebijakan DM. -## Contoh kebijakan DM dan room +## Kebijakan DM dan room ```json5 { @@ -872,7 +796,7 @@ Otorisasi pemicu tetap berasal dari pengaturan `groupPolicy`, `groups`, `groupAl } ``` -Lihat [Groups](/id/channels/groups) untuk perilaku pembatasan mention dan allowlist. +Lihat [Groups](/id/channels/groups) untuk perilaku mention-gating dan allowlist. Contoh pairing untuk DM Matrix: @@ -881,14 +805,36 @@ openclaw pairing list matrix openclaw pairing approve matrix ``` -Jika pengguna Matrix yang belum disetujui terus mengirim pesan kepada Anda sebelum persetujuan, OpenClaw menggunakan kembali 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 kembali kode pairing tertunda yang sama dan dapat mengirim balasan pengingat lagi setelah cooldown singkat alih-alih membuat kode baru. Lihat [Pairing](/id/channels/pairing) untuk alur pairing DM bersama dan tata letak penyimpanan. +## Perbaikan direct room + +Jika status direct-message tidak sinkron, OpenClaw dapat berakhir dengan pemetaan `m.direct` basi yang menunjuk ke room solo lama alih-alih DM live. Periksa pemetaan saat ini untuk peer dengan: + +```bash +openclaw matrix direct inspect --user-id @alice:example.org +``` + +Perbaiki dengan: + +```bash +openclaw matrix direct repair --user-id @alice:example.org +``` + +Alur perbaikan: + +- memilih DM 1:1 ketat yang sudah dipetakan di `m.direct` +- fallback ke DM 1:1 ketat yang saat ini telah bergabung dengan pengguna tersebut +- membuat direct room baru dan menulis ulang `m.direct` jika tidak ada DM sehat + +Alur perbaikan tidak menghapus room lama secara otomatis. 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. + ## Persetujuan exec -Matrix dapat bertindak sebagai klien persetujuan native untuk akun Matrix. Tombol -perutean DM/channel native tetap berada di bawah config persetujuan exec: +Matrix dapat bertindak sebagai klien persetujuan asli untuk akun Matrix. Tombol +routing DM/saluran asli tetap berada di bawah config persetujuan exec: - `channels.matrix.execApprovals.enabled` - `channels.matrix.execApprovals.approvers` (opsional; fallback ke `channels.matrix.dm.allowFrom`) @@ -896,14 +842,14 @@ perutean DM/channel native tetap berada di bawah config persetujuan exec: - `channels.matrix.execApprovals.agentFilter` - `channels.matrix.execApprovals.sessionFilter` -Approver harus berupa user ID Matrix seperti `@owner:example.org`. Matrix mengaktifkan persetujuan native secara otomatis ketika `enabled` tidak disetel atau `"auto"` dan setidaknya satu approver dapat diselesaikan. Persetujuan exec menggunakan `execApprovals.approvers` terlebih dahulu dan dapat fallback ke `channels.matrix.dm.allowFrom`. Persetujuan plugin mengotorisasi melalui `channels.matrix.dm.allowFrom`. Setel `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. +Pemberi persetujuan harus berupa ID pengguna Matrix seperti `@owner:example.org`. Matrix mengaktifkan persetujuan asli secara otomatis saat `enabled` tidak diatur atau `"auto"` dan setidaknya satu pemberi persetujuan dapat diselesaikan. Persetujuan exec menggunakan `execApprovals.approvers` terlebih dahulu dan dapat fallback ke `channels.matrix.dm.allowFrom`. Persetujuan plugin memberi otorisasi melalui `channels.matrix.dm.allowFrom`. Setel `enabled: false` untuk menonaktifkan Matrix sebagai klien persetujuan asli secara eksplisit. Permintaan persetujuan jika tidak akan fallback ke rute persetujuan lain yang dikonfigurasi atau kebijakan fallback persetujuan. -Perutean native Matrix kini mendukung kedua jenis persetujuan: +Routing asli Matrix mendukung kedua jenis persetujuan: -- `channels.matrix.execApprovals.*` mengontrol mode fanout DM/channel native untuk prompt persetujuan Matrix. -- Persetujuan exec menggunakan set approver exec dari `execApprovals.approvers` atau `channels.matrix.dm.allowFrom`. +- `channels.matrix.execApprovals.*` mengontrol mode fanout DM/saluran asli untuk prompt persetujuan Matrix. +- Persetujuan exec menggunakan kumpulan approver exec dari `execApprovals.approvers` atau `channels.matrix.dm.allowFrom`. - Persetujuan plugin menggunakan allowlist DM Matrix dari `channels.matrix.dm.allowFrom`. -- Pintasan reaction Matrix dan pembaruan pesan berlaku untuk persetujuan exec maupun plugin. +- Pintasan reaksi Matrix dan pembaruan pesan berlaku untuk persetujuan exec maupun plugin. Aturan pengiriman: @@ -911,25 +857,23 @@ 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 reaction pada pesan persetujuan utama: +Prompt persetujuan Matrix menanamkan pintasan reaksi pada pesan persetujuan utama: - `✅` = izinkan sekali - `❌` = tolak -- `♾️` = selalu izinkan saat keputusan itu diizinkan oleh kebijakan exec efektif +- `♾️` = izinkan selalu bila keputusan tersebut diizinkan oleh kebijakan exec efektif -Approver dapat bereaksi pada pesan tersebut atau menggunakan slash command cadangan: `/approve allow-once`, `/approve allow-always`, atau `/approve deny`. +Approver dapat bereaksi pada pesan itu atau menggunakan fallback slash command: `/approve allow-once`, `/approve allow-always`, atau `/approve deny`. -Hanya approver yang telah diselesaikan yang dapat menyetujui atau menolak. Untuk persetujuan exec, pengiriman channel menyertakan teks perintah, jadi aktifkan `channel` atau `both` hanya di room tepercaya. +Hanya approver yang telah diselesaikan yang dapat menyetujui atau menolak. Untuk persetujuan exec, pengiriman saluran menyertakan teks perintah, jadi aktifkan `channel` atau `both` hanya di room tepercaya. -Prompt persetujuan Matrix menggunakan kembali planner persetujuan inti bersama. Permukaan native khusus Matrix menangani perutean room/DM, reaction, dan perilaku kirim/perbarui/hapus pesan untuk persetujuan exec maupun plugin. - -Override per akun: +Override per-akun: - `channels.matrix.accounts..execApprovals` Dokumentasi terkait: [Persetujuan exec](/id/tools/exec-approvals) -## Contoh multi-akun +## Multi-akun ```json5 { @@ -960,18 +904,19 @@ Dokumentasi terkait: [Persetujuan exec](/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 yang diwarisi 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 ketika akun default dikonfigurasi langsung di `channels.matrix.*` tingkat atas. -Default auth bersama parsial tidak dengan sendirinya membuat akun default implisit 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 tetap dapat terdeteksi dari `homeserver` plus `userId` ketika kredensial cache memenuhi auth nanti. -Jika Matrix sudah memiliki tepat satu akun bernama, atau `defaultAccount` menunjuk ke key akun bernama yang sudah ada, promosi perbaikan/penyiapan dari satu akun ke multi-akun mempertahankan akun itu alih-alih membuat entri `accounts.default` baru. Hanya key auth/bootstrap Matrix yang dipindahkan ke akun hasil promosi itu; key kebijakan pengiriman bersama tetap di tingkat atas. -Setel `defaultAccount` ketika 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 ...` ketika Anda ingin menimpa pemilihan implisit itu untuk satu perintah. +Anda dapat memberi cakupan entri room turunan ke satu akun Matrix dengan `groups..account`. +Entri tanpa `account` tetap dibagikan ke semua akun Matrix, dan entri dengan `account: "default"` tetap berfungsi saat akun default dikonfigurasi langsung di `channels.matrix.*` tingkat atas. +Default autentikasi bersama parsial tidak dengan sendirinya membuat akun default implisit terpisah. OpenClaw hanya mensintesis akun `default` tingkat atas saat default tersebut memiliki autentikasi baru (`homeserver` plus `accessToken`, atau `homeserver` plus `userId` dan `password`); akun bernama tetap dapat ditemukan dari `homeserver` plus `userId` saat kredensial cache memenuhi autentikasi nanti. +Jika Matrix sudah memiliki tepat satu akun bernama, atau `defaultAccount` menunjuk ke kunci akun bernama yang ada, promosi perbaikan/penyiapan dari satu akun ke multi-akun mempertahankan akun itu alih-alih membuat entri `accounts.default` baru. Hanya kunci autentikasi/bootstrap Matrix yang dipindahkan ke akun yang dipromosikan itu; kunci kebijakan pengiriman bersama tetap berada di tingkat atas. +Setel `defaultAccount` saat Anda ingin OpenClaw memilih satu akun Matrix bernama untuk routing implisit, probing, dan operasi CLI. +Jika Anda mengonfigurasi beberapa akun bernama, setel `defaultAccount` atau berikan `--account ` untuk perintah CLI yang bergantung pada pemilihan akun implisit. +Berikan `--account ` ke `openclaw matrix verify ...` dan `openclaw matrix devices ...` saat Anda ingin menimpa pemilihan implisit itu untuk satu perintah. + +Lihat [Referensi konfigurasi](/id/gateway/configuration-reference#multi-account-all-channels) untuk pola multi-akun bersama. ## Homeserver privat/LAN -Secara default, OpenClaw memblokir homeserver Matrix privat/internal untuk perlindungan SSRF kecuali Anda -secara eksplisit memilih ikut per akun. +Secara default, OpenClaw memblokir homeserver Matrix privat/internal untuk perlindungan SSRF kecuali Anda secara eksplisit memilih untuk mengizinkannya per akun. Jika homeserver Anda berjalan di localhost, IP LAN/Tailscale, atau hostname internal, aktifkan `network.dangerouslyAllowPrivateNetwork` untuk akun Matrix tersebut: @@ -1000,8 +945,8 @@ openclaw matrix account add \ --access-token syt_ops_xxx ``` -Opt-in ini hanya mengizinkan target privat/internal yang tepercaya. Homeserver cleartext publik seperti -`http://matrix.example.org:8008` tetap diblokir. Sebisa mungkin, gunakan `https://`. +Opt-in ini hanya mengizinkan target privat/internal tepercaya. Homeserver cleartext publik seperti +`http://matrix.example.org:8008` tetap diblokir. Pilih `https://` bila memungkinkan. ## Proxy lalu lintas Matrix @@ -1020,11 +965,11 @@ Jika deployment Matrix Anda memerlukan proxy HTTP(S) keluar eksplisit, setel `ch ``` 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. +OpenClaw menggunakan setelan proxy yang sama untuk lalu lintas Matrix runtime dan probe status akun. ## Resolusi target -Matrix menerima bentuk target berikut di mana pun OpenClaw meminta target room atau pengguna: +Matrix menerima bentuk target ini di mana pun OpenClaw meminta target room atau pengguna: - Pengguna: `@user:server`, `user:@user:server`, atau `matrix:user:@user:server` - Room: `!room:server`, `room:!room:server`, atau `matrix:room:!room:server` @@ -1032,74 +977,73 @@ Matrix menerima bentuk target berikut di mana pun OpenClaw meminta target room a Pencarian direktori live menggunakan akun Matrix yang sedang login: -- Pencarian pengguna mengkueri direktori pengguna Matrix di homeserver tersebut. -- Pencarian room menerima ID room dan alias eksplisit secara langsung, lalu fallback ke pencarian nama room yang sudah diikuti untuk akun tersebut. -- Pencarian nama room yang sudah diikuti bersifat best-effort. Jika nama room tidak dapat diselesaikan ke ID atau alias, nama itu diabaikan oleh resolusi allowlist runtime. +- Pencarian pengguna mengueri direktori pengguna Matrix pada homeserver tersebut. +- Pencarian room menerima ID room dan alias eksplisit secara langsung, lalu fallback ke pencarian nama room yang sudah digabung untuk akun tersebut. +- Pencarian nama room yang sudah digabung bersifat best-effort. Jika nama room tidak dapat diselesaikan menjadi 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 yang dipilih saat beberapa akun Matrix dikonfigurasi. +- `defaultAccount`: ID akun pilihan saat beberapa akun Matrix dikonfigurasi. - `homeserver`: URL homeserver, misalnya `https://matrix.example.org`. -- `network.dangerouslyAllowPrivateNetwork`: 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`. +- `network.dangerouslyAllowPrivateNetwork`: izinkan akun Matrix ini terhubung ke homeserver privat/internal. Aktifkan ini saat homeserver mengarah 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 penyedia env/file/exec. Lihat [Secrets Management](/id/gateway/secrets). +- `accessToken`: access token untuk autentikasi 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). - `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 diri yang disimpan untuk sinkronisasi profil dan pembaruan `set-profile`. -- `initialSyncLimit`: batas event sync saat startup. +- `avatarUrl`: URL avatar diri yang tersimpan untuk sinkronisasi profil dan pembaruan `profile set`. +- `initialSyncLimit`: jumlah maksimum event yang diambil selama sinkronisasi startup. - `encryption`: aktifkan E2EE. -- `allowlistOnly`: paksa perilaku hanya-allowlist untuk DM dan room. -- `allowBots`: izinkan pesan dari akun Matrix OpenClaw lain yang telah dikonfigurasi (`true` atau `"mentions"`). +- `allowlistOnly`: saat `true`, meningkatkan kebijakan room `open` menjadi `allowlist`, dan memaksa semua kebijakan DM aktif kecuali `disabled` (termasuk `pairing` dan `open`) menjadi `allowlist`. Tidak memengaruhi kebijakan `disabled`. +- `allowBots`: izinkan pesan dari akun Matrix OpenClaw lain yang dikonfigurasi (`true` atau `"mentions"`). - `groupPolicy`: `open`, `allowlist`, atau `disabled`. - `contextVisibility`: mode visibilitas konteks room tambahan (`all`, `allowlist`, `allowlist_quote`). -- `groupAllowFrom`: allowlist user ID untuk lalu lintas room. -- Entri `groupAllowFrom` harus berupa user ID Matrix lengkap. Nama yang tidak terselesaikan diabaikan saat runtime. -- `historyLimit`: jumlah maksimum pesan room yang disertakan sebagai konteks riwayat grup. Fallback ke `messages.groupChat.historyLimit`; jika keduanya tidak disetel, default efektifnya adalah `0`. Setel `0` untuk menonaktifkan. +- `groupAllowFrom`: allowlist ID pengguna untuk lalu lintas room. Entri sebaiknya 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`; jika keduanya tidak diatur, default efektifnya adalah `0`. Setel `0` untuk menonaktifkan. - `replyToMode`: `off`, `first`, `all`, atau `batched`. -- `markdown`: konfigurasi rendering Markdown opsional untuk teks Matrix keluar. -- `streaming`: `off` (default), `partial`, `quiet`, `true`, atau `false`. `partial` dan `true` mengaktifkan pembaruan draft pratinjau-dulu dengan pesan teks Matrix normal. `quiet` menggunakan pemberitahuan pratinjau tanpa notifikasi untuk penyiapan aturan push self-hosted. -- `blockStreaming`: `true` mengaktifkan pesan progres terpisah untuk blok asisten yang telah selesai saat streaming draft pratinjau aktif. +- `markdown`: config rendering Markdown opsional untuk teks Matrix keluar. +- `streaming`: `off` (default), `"partial"`, `"quiet"`, `true`, atau `false`. `"partial"` dan `true` mengaktifkan pembaruan draf yang mengutamakan pratinjau dengan pesan teks Matrix normal. `"quiet"` menggunakan pemberitahuan pratinjau tanpa notifikasi untuk penyiapan push-rule self-hosted. `false` setara dengan `"off"`. +- `blockStreaming`: `true` mengaktifkan pesan progres terpisah untuk blok asisten yang telah selesai saat streaming pratinjau draf aktif. - `threadReplies`: `off`, `inbound`, atau `always`. -- `threadBindings`: override per-channel untuk perutean dan siklus hidup sesi terikat-thread. -- `startupVerification`: mode permintaan verifikasi mandiri otomatis saat startup (`if-unverified`, `off`). -- `startupVerificationCooldownHours`: cooldown sebelum mencoba ulang permintaan verifikasi startup otomatis. -- `textChunkLimit`: ukuran chunk pesan keluar. -- `chunkMode`: `length` atau `newline`. -- `responsePrefix`: prefix pesan opsional untuk balasan keluar. -- `ackReaction`: override reaction ack opsional untuk channel/akun ini. -- `ackReactionScope`: override cakupan reaction ack opsional (`group-mentions`, `group-all`, `direct`, `all`, `none`, `off`). -- `reactionNotifications`: mode pemberitahuan reaction masuk (`own`, `off`). -- `mediaMaxMb`: batas ukuran media dalam MB untuk penanganan media Matrix. Berlaku untuk pengiriman keluar dan pemrosesan media masuk. -- `autoJoin`: kebijakan auto-join undangan (`always`, `allowlist`, `off`). Default: `off`. Berlaku untuk undangan Matrix secara umum, termasuk undangan gaya DM, bukan hanya undangan room/grup. OpenClaw membuat keputusan ini pada saat undangan, sebelum dapat secara andal mengklasifikasikan room yang diikuti sebagai DM atau grup. -- `autoJoinAllowlist`: room/alias yang diizinkan ketika `autoJoin` adalah `allowlist`. Entri alias diselesaikan ke ID room selama penanganan undangan; OpenClaw tidak memercayai state alias yang diklaim oleh room undangan. +- `threadBindings`: override per-saluran untuk routing dan siklus hidup sesi yang terikat thread. +- `startupVerification`: mode permintaan self-verification otomatis saat startup (`if-unverified`, `off`). +- `startupVerificationCooldownHours`: cooldown sebelum mencoba lagi permintaan verifikasi startup otomatis. +- `textChunkLimit`: ukuran chunk pesan keluar dalam karakter (berlaku saat `chunkMode` adalah `length`). +- `chunkMode`: `length` memecah pesan berdasarkan jumlah karakter; `newline` memecah di batas baris. +- `responsePrefix`: string opsional yang ditambahkan di depan semua balasan keluar untuk saluran ini. +- `ackReaction`: override ack reaction opsional untuk saluran/akun ini. +- `ackReactionScope`: override cakupan ack reaction opsional (`group-mentions`, `group-all`, `direct`, `all`, `none`, `off`). +- `reactionNotifications`: mode notifikasi reaksi masuk (`own`, `off`). +- `mediaMaxMb`: batas ukuran media dalam MB untuk pengiriman keluar dan pemrosesan media masuk. +- `autoJoin`: kebijakan gabung otomatis undangan (`always`, `allowlist`, `off`). Default: `off`. Berlaku untuk semua undangan Matrix, termasuk undangan bergaya DM. +- `autoJoinAllowlist`: room/alias yang diizinkan saat `autoJoin` adalah `allowlist`. Entri alias diselesaikan ke ID room selama penanganan undangan; OpenClaw tidak mempercayai status alias yang diklaim oleh room yang diundang. - `dm`: blok kebijakan DM (`enabled`, `policy`, `allowFrom`, `sessionScope`, `threadReplies`). -- `dm.policy`: mengontrol akses DM setelah OpenClaw bergabung ke room dan mengklasifikasikannya sebagai DM. Ini tidak mengubah apakah undangan akan di-auto-join. -- Entri `dm.allowFrom` harus berupa user ID Matrix lengkap kecuali Anda sudah menyelesaikannya melalui pencarian direktori live. -- `dm.sessionScope`: `per-user` (default) atau `per-room`. Gunakan `per-room` ketika Anda ingin setiap room DM Matrix mempertahankan konteks terpisah meskipun peer-nya sama. -- `dm.threadReplies`: override kebijakan thread khusus DM (`off`, `inbound`, `always`). 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`: user ID Matrix yang diizinkan menyetujui permintaan exec. Opsional ketika `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 otomatis digabung. +- `dm.allowFrom`: entri sebaiknya 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 peer-nya sama. +- `dm.threadReplies`: override kebijakan thread khusus DM (`off`, `inbound`, `always`). Ini menimpa setelan `threadReplies` tingkat atas untuk penempatan balasan maupun isolasi sesi di DM. +- `execApprovals`: pengiriman persetujuan exec asli Matrix (`enabled`, `approvers`, `target`, `agentFilter`, `sessionFilter`). +- `execApprovals.approvers`: ID pengguna Matrix yang diizinkan menyetujui permintaan exec. Opsional jika `dm.allowFrom` sudah mengidentifikasi para 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 terselesaikan diabaikan saat runtime. Identitas sesi/grup menggunakan ID room yang stabil setelah resolusi, sementara label yang dapat 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 terkonfigurasi (`true` atau `"mentions"`). -- `groups..users`: allowlist pengirim per room. -- `groups..tools`: override izin/tolak tool per room. -- `groups..autoReply`: override pembatasan mention tingkat room. `true` menonaktifkan persyaratan mention untuk room itu; `false` memaksanya aktif kembali. -- `groups..skills`: filter skill opsional tingkat room. -- `groups..systemPrompt`: cuplikan system prompt opsional tingkat room. +- `accounts`: override per-akun bernama. Nilai `channels.matrix` tingkat atas bertindak sebagai default untuk entri ini. +- `groups`: peta kebijakan per-room. Pilih ID room atau alias; nama room yang tidak dapat diselesaikan diabaikan saat runtime. Identitas sesi/grup menggunakan ID room stabil setelah resolusi. +- `groups..account`: batasi satu entri room turunan 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 allow/deny 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`: cuplikan system prompt tingkat room opsional. - `rooms`: alias lama untuk `groups`. -- `actions`: pembatasan tool per action (`messages`, `reactions`, `pins`, `profile`, `memberInfo`, `channelInfo`, `verification`). +- `actions`: pembatasan tool per-aksi (`messages`, `reactions`, `pins`, `profile`, `memberInfo`, `channelInfo`, `verification`). ## Terkait -- [Gambaran Umum Channels](/id/channels) — semua channel yang didukung -- [Pairing](/id/channels/pairing) — auth DM dan alur pairing -- [Groups](/id/channels/groups) — perilaku chat grup dan pembatasan mention -- [Perutean Channel](/id/channels/channel-routing) — perutean sesi untuk pesan -- [Security](/id/gateway/security) — model akses dan hardening +- [Ikhtisar Saluran](/id/channels) — semua saluran yang didukung +- [Pairing](/id/channels/pairing) — autentikasi DM dan alur pairing +- [Groups](/id/channels/groups) — perilaku group chat dan mention gating +- [Routing Saluran](/id/channels/channel-routing) — routing sesi untuk pesan +- [Keamanan](/id/gateway/security) — model akses dan hardening diff --git a/docs/id/concepts/agent-loop.md b/docs/id/concepts/agent-loop.md index 77ac7854c..0d270b8e1 100644 --- a/docs/id/concepts/agent-loop.md +++ b/docs/id/concepts/agent-loop.md @@ -1,25 +1,25 @@ --- read_when: - Anda memerlukan panduan langkah demi langkah yang tepat tentang loop agen atau peristiwa siklus hidup -summary: Siklus hidup loop agen, stream, dan semantik wait +summary: Siklus hidup loop agen, aliran, dan semantik penantian title: Loop Agen x-i18n: - generated_at: "2026-04-05T13:50:47Z" + generated_at: "2026-04-09T01:27:55Z" model: gpt-5.4 provider: openai - source_hash: 8e562e63c494881e9c345efcb93c5f972d69aaec61445afc3d4ad026b2d26883 + source_hash: 32d3a73df8dabf449211a6183a70dcfd2a9b6f584dc76d0c4c9147582b2ca6a1 source_path: concepts/agent-loop.md workflow: 15 --- # Loop Agen (OpenClaw) -Loop agentik adalah eksekusi “nyata” penuh dari sebuah agen: intake → perakitan konteks → inferensi model → -eksekusi tool → balasan streaming → persistensi. Ini adalah jalur otoritatif yang mengubah sebuah pesan +Loop agentik adalah keseluruhan proses “nyata” agen: intake → perakitan konteks → inferensi model → +eksekusi alat → balasan streaming → persistensi. Ini adalah jalur otoritatif yang mengubah pesan menjadi tindakan dan balasan akhir, sambil menjaga status sesi tetap konsisten. -Di OpenClaw, sebuah loop adalah satu eksekusi terserialisasi per sesi yang memancarkan peristiwa siklus hidup dan stream -saat model berpikir, memanggil tool, dan melakukan streaming output. Dokumen ini menjelaskan bagaimana loop autentik tersebut +Di OpenClaw, loop adalah satu proses tunggal yang diserialkan per sesi yang memancarkan peristiwa siklus hidup dan stream +saat model berpikir, memanggil alat, dan melakukan streaming output. Dokumen ini menjelaskan bagaimana loop autentik tersebut dirangkai dari ujung ke ujung. ## Titik masuk @@ -29,147 +29,148 @@ dirangkai dari ujung ke ujung. ## Cara kerjanya (tingkat tinggi) -1. RPC `agent` memvalidasi parameter, menyelesaikan sesi (sessionKey/sessionId), menyimpan metadata sesi, dan langsung mengembalikan `{ runId, acceptedAt }`. +1. RPC `agent` memvalidasi parameter, menyelesaikan sesi (sessionKey/sessionId), menyimpan metadata sesi, dan segera mengembalikan `{ runId, acceptedAt }`. 2. `agentCommand` menjalankan agen: - menyelesaikan default model + thinking/verbose - memuat snapshot Skills - memanggil `runEmbeddedPiAgent` (runtime pi-agent-core) - - memancarkan **lifecycle end/error** jika loop tersemat tidak memancarkan salah satunya + - memancarkan **akhir/error siklus hidup** jika loop tersemat tidak memancarkan salah satunya 3. `runEmbeddedPiAgent`: - - menserialisasi eksekusi melalui antrean per sesi + global + - menserialkan proses melalui antrean per sesi + global - menyelesaikan model + profil auth dan membangun sesi pi - - berlangganan ke peristiwa pi dan melakukan streaming delta assistant/tool - - menerapkan timeout -> membatalkan eksekusi jika terlampaui + - berlangganan ke peristiwa pi dan melakukan streaming delta asisten/alat + - menegakkan batas waktu -> membatalkan proses jika terlampaui - mengembalikan payload + metadata penggunaan 4. `subscribeEmbeddedPiSession` menjembatani peristiwa pi-agent-core ke stream `agent` OpenClaw: - - peristiwa tool => `stream: "tool"` - - delta assistant => `stream: "assistant"` - - peristiwa lifecycle => `stream: "lifecycle"` (`phase: "start" | "end" | "error"`) + - peristiwa alat => `stream: "tool"` + - delta asisten => `stream: "assistant"` + - peristiwa siklus hidup => `stream: "lifecycle"` (`phase: "start" | "end" | "error"`) 5. `agent.wait` menggunakan `waitForAgentRun`: - - menunggu **lifecycle end/error** untuk `runId` + - menunggu **akhir/error siklus hidup** untuk `runId` - mengembalikan `{ status: ok|error|timeout, startedAt, endedAt, error? }` ## Antrean + konkurensi -- Eksekusi diserialisasi per kunci sesi (jalur sesi) dan secara opsional melalui jalur global. -- Ini mencegah race tool/sesi dan menjaga riwayat sesi tetap konsisten. +- Proses diserialkan per kunci sesi (jalur sesi) dan secara opsional melalui jalur global. +- Ini mencegah race pada alat/sesi dan menjaga riwayat sesi tetap konsisten. - Kanal pesan dapat memilih mode antrean (collect/steer/followup) yang masuk ke sistem jalur ini. - Lihat [Antrean Perintah](/concepts/queue). + Lihat [Antrean Perintah](/id/concepts/queue). ## Persiapan sesi + workspace -- Workspace diselesaikan dan dibuat; eksekusi tersandbox dapat mengalihkan ke root workspace sandbox. +- Workspace diselesaikan dan dibuat; proses tersandbox dapat dialihkan ke root workspace sandbox. - Skills dimuat (atau digunakan kembali dari snapshot) dan disuntikkan ke env dan prompt. - File bootstrap/konteks diselesaikan dan disuntikkan ke laporan system prompt. -- Lock tulis sesi diperoleh; `SessionManager` dibuka dan disiapkan sebelum streaming. +- Kunci tulis sesi diperoleh; `SessionManager` dibuka dan disiapkan sebelum streaming. ## Perakitan prompt + system prompt -- System prompt dibangun dari prompt dasar OpenClaw, prompt Skills, konteks bootstrap, dan override per eksekusi. +- System prompt dibangun dari prompt dasar OpenClaw, prompt Skills, konteks bootstrap, dan override per proses. - Batas khusus model dan token cadangan compaction diterapkan. -- Lihat [System prompt](/concepts/system-prompt) untuk mengetahui apa yang dilihat model. +- Lihat [System prompt](/id/concepts/system-prompt) untuk apa yang dilihat model. ## Titik hook (tempat Anda dapat mencegat) OpenClaw memiliki dua sistem hook: -- **Internal hooks** (Gateway hooks): skrip berbasis peristiwa untuk perintah dan peristiwa siklus hidup. -- **Plugin hooks**: titik ekstensi di dalam siklus hidup agen/tool dan pipeline gateway. +- **Hook internal** (hook Gateway): skrip berbasis peristiwa untuk perintah dan peristiwa siklus hidup. +- **Hook plugin**: titik ekstensi di dalam siklus hidup agen/alat dan pipeline gateway. -### Internal hooks (Gateway hooks) +### Hook internal (hook Gateway) - **`agent:bootstrap`**: berjalan saat membangun file bootstrap sebelum system prompt difinalkan. - Gunakan ini untuk menambahkan/menghapus file konteks bootstrap. -- **Command hooks**: `/new`, `/reset`, `/stop`, dan peristiwa perintah lainnya (lihat dokumen Hooks). + Gunakan ini untuk menambah/menghapus file konteks bootstrap. +- **Hook perintah**: `/new`, `/reset`, `/stop`, dan peristiwa perintah lainnya (lihat dokumen Hooks). Lihat [Hooks](/id/automation/hooks) untuk penyiapan dan contoh. -### Plugin hooks (siklus hidup agen + gateway) +### Hook plugin (siklus hidup agen + gateway) Hook ini berjalan di dalam loop agen atau pipeline gateway: -- **`before_model_resolve`**: berjalan sebelum sesi (tanpa `messages`) untuk meng-override provider/model secara deterministik sebelum penyelesaian model. -- **`before_prompt_build`**: berjalan setelah sesi dimuat (dengan `messages`) untuk menyuntikkan `prependContext`, `systemPrompt`, `prependSystemContext`, atau `appendSystemContext` sebelum prompt dikirim. Gunakan `prependContext` untuk teks dinamis per giliran dan field system-context untuk panduan stabil yang seharusnya berada di ruang system prompt. -- **`before_agent_start`**: hook kompatibilitas lama yang dapat berjalan di salah satu fase; pilih hook eksplisit di atas. -- **`before_agent_reply`**: berjalan setelah tindakan inline dan sebelum panggilan LLM, memungkinkan plugin mengklaim giliran dan mengembalikan balasan sintetis atau membisukan giliran sepenuhnya. -- **`agent_end`**: memeriksa daftar pesan akhir dan metadata eksekusi setelah selesai. +- **`before_model_resolve`**: berjalan pra-sesi (tanpa `messages`) untuk mengganti provider/model secara deterministik sebelum resolusi model. +- **`before_prompt_build`**: berjalan setelah sesi dimuat (dengan `messages`) untuk menyuntikkan `prependContext`, `systemPrompt`, `prependSystemContext`, atau `appendSystemContext` sebelum prompt dikirim. Gunakan `prependContext` untuk teks dinamis per giliran dan field konteks sistem untuk panduan stabil yang seharusnya berada di ruang system prompt. +- **`before_agent_start`**: hook kompatibilitas lama yang dapat berjalan pada salah satu fase; gunakan hook eksplisit di atas jika memungkinkan. +- **`before_agent_reply`**: berjalan setelah tindakan inline dan sebelum pemanggilan LLM, memungkinkan plugin mengklaim giliran dan mengembalikan balasan sintetis atau membisukan giliran sepenuhnya. +- **`agent_end`**: memeriksa daftar pesan akhir dan metadata proses setelah selesai. - **`before_compaction` / `after_compaction`**: mengamati atau memberi anotasi pada siklus compaction. -- **`before_tool_call` / `after_tool_call`**: mencegat parameter/hasil tool. +- **`before_tool_call` / `after_tool_call`**: mencegat parameter/hasil alat. - **`before_install`**: memeriksa temuan pemindaian bawaan dan secara opsional memblokir instalasi skill atau plugin. -- **`tool_result_persist`**: secara sinkron mentransformasi hasil tool sebelum ditulis ke transkrip sesi. +- **`tool_result_persist`**: secara sinkron mengubah hasil alat sebelum ditulis ke transkrip sesi. - **`message_received` / `message_sending` / `message_sent`**: hook pesan masuk + keluar. - **`session_start` / `session_end`**: batas siklus hidup sesi. - **`gateway_start` / `gateway_stop`**: peristiwa siklus hidup gateway. -Aturan keputusan hook untuk pengaman keluar/tool: +Aturan keputusan hook untuk pengaman keluar/alat: -- `before_tool_call`: `{ block: true }` bersifat terminal dan menghentikan handler dengan prioritas lebih rendah. +- `before_tool_call`: `{ block: true }` bersifat terminal dan menghentikan handler prioritas lebih rendah. - `before_tool_call`: `{ block: false }` adalah no-op dan tidak menghapus blok sebelumnya. -- `before_install`: `{ block: true }` bersifat terminal dan menghentikan handler dengan prioritas lebih rendah. +- `before_install`: `{ block: true }` bersifat terminal dan menghentikan handler prioritas lebih rendah. - `before_install`: `{ block: false }` adalah no-op dan tidak menghapus blok sebelumnya. -- `message_sending`: `{ cancel: true }` bersifat terminal dan menghentikan handler dengan prioritas lebih rendah. +- `message_sending`: `{ cancel: true }` bersifat terminal dan menghentikan handler prioritas lebih rendah. - `message_sending`: `{ cancel: false }` adalah no-op dan tidak menghapus cancel sebelumnya. -Lihat [Plugin hooks](/plugins/architecture#provider-runtime-hooks) untuk API hook dan detail pendaftaran. +Lihat [Hook plugin](/id/plugins/architecture#provider-runtime-hooks) untuk API hook dan detail pendaftaran. ## Streaming + balasan parsial -- Delta assistant di-stream dari pi-agent-core dan dipancarkan sebagai peristiwa `assistant`. -- Block streaming dapat memancarkan balasan parsial baik pada `text_end` maupun `message_end`. +- Delta asisten di-stream dari pi-agent-core dan dipancarkan sebagai peristiwa `assistant`. +- Streaming blok dapat memancarkan balasan parsial pada `text_end` atau `message_end`. - Streaming reasoning dapat dipancarkan sebagai stream terpisah atau sebagai balasan blok. -- Lihat [Streaming](/concepts/streaming) untuk perilaku chunking dan balasan blok. +- Lihat [Streaming](/id/concepts/streaming) untuk perilaku chunking dan balasan blok. -## Eksekusi tool + tool pesan +## Eksekusi alat + alat pesan -- Peristiwa mulai/pembaruan/akhir tool dipancarkan pada stream `tool`. -- Hasil tool disanitasi untuk ukuran dan payload gambar sebelum dicatat/dipancarkan. -- Pengiriman tool pesan dilacak untuk menekan konfirmasi assistant duplikat. +- Peristiwa mulai/pembaruan/akhir alat dipancarkan pada stream `tool`. +- Hasil alat disanitasi untuk ukuran dan payload gambar sebelum dicatat/dipancarkan. +- Pengiriman alat pesan dilacak untuk menekan konfirmasi asisten duplikat. ## Pembentukan balasan + penekanan - Payload akhir dirakit dari: - - teks assistant (dan reasoning opsional) - - ringkasan tool inline (saat verbose + diizinkan) - - teks error assistant saat model mengalami error -- Token senyap persis `NO_REPLY` / `no_reply` difilter dari - payload keluar. -- Duplikat tool pesan dihapus dari daftar payload akhir. -- Jika tidak ada payload yang dapat dirender tersisa dan sebuah tool mengalami error, balasan error tool fallback dipancarkan - (kecuali tool pesan sudah mengirim balasan yang terlihat oleh pengguna). + - teks asisten (dan reasoning opsional) + - ringkasan alat inline (saat verbose + diizinkan) + - teks error asisten saat model mengalami error +- Token senyap yang tepat `NO_REPLY` / `no_reply` difilter dari payload + keluar. +- Duplikat alat pesan dihapus dari daftar payload akhir. +- Jika tidak ada payload yang dapat dirender yang tersisa dan alat mengalami error, balasan error alat fallback dipancarkan + (kecuali alat pesan sudah mengirim balasan yang terlihat oleh pengguna). ## Compaction + percobaan ulang - Auto-compaction memancarkan peristiwa stream `compaction` dan dapat memicu percobaan ulang. -- Saat percobaan ulang, buffer dalam memori dan ringkasan tool direset untuk menghindari output duplikat. -- Lihat [Compaction](/concepts/compaction) untuk pipeline compaction. +- Saat percobaan ulang, buffer dalam memori dan ringkasan alat direset untuk menghindari output duplikat. +- Lihat [Compaction](/id/concepts/compaction) untuk pipeline compaction. ## Stream peristiwa (saat ini) - `lifecycle`: dipancarkan oleh `subscribeEmbeddedPiSession` (dan sebagai fallback oleh `agentCommand`) - `assistant`: delta streaming dari pi-agent-core -- `tool`: peristiwa tool streaming dari pi-agent-core +- `tool`: peristiwa alat streaming dari pi-agent-core ## Penanganan kanal chat -- Delta assistant dibuffer menjadi pesan chat `delta`. -- Chat `final` dipancarkan pada **lifecycle end/error**. +- Delta asisten dibuffer ke dalam pesan chat `delta`. +- Chat `final` dipancarkan pada **akhir/error siklus hidup**. -## Timeout +## Batas waktu -- Default `agent.wait`: 30 dtk (hanya wait). Parameter `timeoutMs` menimpa. -- Runtime agen: default `agents.defaults.timeoutSeconds` adalah 172800 dtk (48 jam); diterapkan di timer abort `runEmbeddedPiAgent`. +- Default `agent.wait`: 30 detik (hanya penantian). Parameter `timeoutMs` menimpa. +- Runtime agen: default `agents.defaults.timeoutSeconds` adalah 172800 dtk (48 jam); ditegakkan dalam timer abort `runEmbeddedPiAgent`. +- Batas waktu idle LLM: `agents.defaults.llm.idleTimeoutSeconds` membatalkan permintaan model saat tidak ada potongan respons yang tiba sebelum jendela idle berakhir. Tetapkan ini secara eksplisit untuk model lokal lambat atau provider reasoning/pemanggilan alat; tetapkan ke 0 untuk menonaktifkan. Jika tidak ditetapkan, OpenClaw menggunakan `agents.defaults.timeoutSeconds` jika dikonfigurasi, atau 60 dtk jika tidak. Proses yang dipicu cron tanpa batas waktu LLM atau agen eksplisit menonaktifkan watchdog idle dan bergantung pada batas waktu luar cron. -## Tempat proses dapat berakhir lebih awal +## Tempat proses bisa berakhir lebih awal -- Timeout agen (abort) -- AbortSignal (cancel) -- Gateway terputus atau timeout RPC -- Timeout `agent.wait` (hanya wait, tidak menghentikan agen) +- Batas waktu agen (abort) +- AbortSignal (batal) +- Gateway terputus atau batas waktu RPC +- Batas waktu `agent.wait` (hanya penantian, tidak menghentikan agen) ## Terkait -- [Tools](/tools) — tool agen yang tersedia +- [Tools](/id/tools) — alat agen yang tersedia - [Hooks](/id/automation/hooks) — skrip berbasis peristiwa yang dipicu oleh peristiwa siklus hidup agen -- [Compaction](/concepts/compaction) — bagaimana percakapan panjang diringkas -- [Exec Approvals](/tools/exec-approvals) — gerbang persetujuan untuk perintah shell -- [Thinking](/tools/thinking) — konfigurasi tingkat thinking/reasoning +- [Compaction](/id/concepts/compaction) — cara percakapan panjang diringkas +- [Exec Approvals](/id/tools/exec-approvals) — gerbang persetujuan untuk perintah shell +- [Thinking](/id/tools/thinking) — konfigurasi tingkat thinking/reasoning diff --git a/docs/id/concepts/dreaming.md b/docs/id/concepts/dreaming.md index 9a9ef8aa1..7cb150710 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-08T09:12:40Z" + generated_at: "2026-04-09T01:27:50Z" model: gpt-5.4 provider: openai - source_hash: 0254f3b0949158264e583c12f36f2b1a83d1b44dc4da01a1b272422d38e8655d + source_hash: 26476eddb8260e1554098a6adbb069cf7f5e284cf2e09479c6d9d8f8b93280ef source_path: concepts/dreaming.md workflow: 15 --- @@ -17,17 +17,17 @@ 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 -menjaga prosesnya tetap dapat dijelaskan dan ditinjau. +Sistem ini membantu OpenClaw memindahkan sinyal jangka pendek yang kuat ke memori tahan lama sambil +menjaga agar prosesnya tetap dapat dijelaskan dan ditinjau. Dreaming bersifat **opt-in** dan dinonaktifkan secara default. ## Apa yang ditulis oleh dreaming -Dreaming menyimpan dua jenis output: +Dreaming menyimpan dua jenis keluaran: -- **Status mesin** di `memory/.dreams/` (penyimpanan recall, sinyal fase, checkpoint ingestion, lock). -- **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`. +- **Status mesin** di `memory/.dreams/` (penyimpanan recall, sinyal fase, checkpoint ingestion, kunci). +- **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`. Promosi jangka panjang tetap hanya menulis ke `MEMORY.md`. @@ -35,41 +35,42 @@ Promosi jangka panjang tetap hanya menulis ke `MEMORY.md`. Dreaming menggunakan tiga fase kooperatif: -| Fase | Tujuan | Penulisan tahan lama | -| ----- | ----------------------------------------- | -------------------- | +| Phase | Purpose | Durable write | +| ----- | ----------------------------------------- | ----------------- | | Light | Mengurutkan dan menyiapkan materi jangka pendek terbaru | Tidak | -| Deep | Menilai dan mempromosikan kandidat tahan lama | Ya (`MEMORY.md`) | -| REM | Merefleksikan tema dan ide yang berulang | 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 pengguna. +Fase-fase ini adalah detail implementasi internal, bukan "mode" terpisah +yang dikonfigurasi pengguna. ### Fase light Fase light mengingest sinyal memori harian terbaru dan jejak recall, menghapus duplikasi, dan menyiapkan baris kandidat. -- Membaca dari status recall jangka pendek, file memori harian terbaru, dan transkrip sesi yang telah disunting bila tersedia. -- Menulis blok `## Light Sleep` yang dikelola ketika penyimpanan menyertakan output inline. -- Mencatat sinyal reinforcement untuk pemeringkatan deep nanti. +- Membaca dari status recall jangka pendek, file memori harian terbaru, dan transkrip sesi yang telah disunting jika tersedia. +- Menulis blok `## Light Sleep` yang dikelola ketika penyimpanan mencakup keluaran inline. +- Mencatat sinyal penguatan untuk peringkat deep berikutnya. - Tidak pernah menulis ke `MEMORY.md`. ### Fase deep Fase deep menentukan apa yang menjadi memori jangka panjang. -- Memberi peringkat kandidat menggunakan penilaian berbobot dan ambang batas gerbang. +- Memberi peringkat kandidat menggunakan skor berbobot dan ambang batas. - Mengharuskan `minScore`, `minRecallCount`, dan `minUniqueQueries` terpenuhi. -- Merehidrasi cuplikan dari file harian aktif sebelum menulis, sehingga cuplikan yang usang/dihapus dilewati. +- Melakukan rehidrasi cuplikan dari file harian aktif sebelum menulis, sehingga cuplikan 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`. +- Menulis ringkasan `## Deep Sleep` ke dalam `DREAMS.md` dan secara opsional menulis `memory/dreaming/deep/YYYY-MM-DD.md`. ### Fase REM 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 menyertakan output inline. -- Mencatat sinyal reinforcement REM yang digunakan oleh pemeringkatan deep. +- Menulis blok `## REM Sleep` yang dikelola ketika penyimpanan mencakup keluaran inline. +- Mencatat sinyal penguatan REM yang digunakan oleh peringkat deep. - Tidak pernah menulis ke `MEMORY.md`. ## Ingestion transkrip sesi @@ -82,34 +83,49 @@ sebelum ingestion. ## Dream Diary Dreaming juga menyimpan **Dream Diary** naratif di `DREAMS.md`. -Setelah setiap fase memiliki cukup materi, `memory-core` menjalankan giliran subagen latar belakang best-effort -(menggunakan model runtime default) dan menambahkan entri diary singkat. +Setelah setiap fase memiliki cukup materi, `memory-core` menjalankan giliran subagent latar belakang +best-effort (menggunakan model runtime default) dan menambahkan entri diary singkat. Diary ini untuk dibaca manusia di UI Dreams, bukan sumber promosi. -## Sinyal pemeringkatan deep +Ada juga jalur backfill historis yang grounded untuk pekerjaan peninjauan dan pemulihan: -Pemeringkatan deep menggunakan enam sinyal dasar berbobot ditambah reinforcement fase: +- `memory rem-harness --path ... --grounded` mempratinjau keluaran diary grounded dari catatan historis `YYYY-MM-DD.md`. +- `memory rem-backfill --path ...` menulis entri diary grounded yang reversibel ke dalam `DREAMS.md`. +- `memory rem-backfill --path ... --stage-short-term` menyiapkan kandidat tahan lama yang grounded ke dalam penyimpanan bukti jangka pendek yang sama yang sudah digunakan oleh fase deep normal. +- `memory rem-backfill --rollback` dan `--rollback-short-term` menghapus artefak backfill yang telah disiapkan tanpa menyentuh entri diary biasa atau recall jangka pendek aktif. -| Sinyal | Bobot | Deskripsi | +Control UI menyediakan alur backfill/reset diary yang sama sehingga Anda dapat memeriksa +hasilnya di scene Dreams sebelum memutuskan apakah kandidat grounded +layak dipromosikan. Scene juga menampilkan jalur grounded yang berbeda sehingga Anda dapat melihat +entri jangka pendek yang disiapkan mana yang berasal dari replay historis, item yang dipromosikan +mana yang dipandu grounded, dan hanya menghapus entri yang disiapkan khusus grounded tanpa +menyentuh status jangka pendek aktif biasa. + +## Sinyal peringkat deep + +Peringkat deep menggunakan enam sinyal dasar berbobot ditambah penguatan fase: + +| Signal | Weight | Description | | ------------------- | ------ | ------------------------------------------------- | -| Frekuensi | 0.24 | Berapa banyak sinyal jangka pendek yang dikumpulkan entri | -| Relevansi | 0.30 | Rata-rata kualitas pengambilan untuk entri | -| Keragaman kueri | 0.15 | Konteks kueri/hari berbeda yang memunculkannya | -| Kebaruan | 0.15 | Skor kesegaran yang menurun seiring waktu | -| Konsolidasi | 0.10 | Kekuatan kemunculan ulang lintas hari | -| Kekayaan konseptual | 0.06 | Kepadatan tag konsep dari cuplikan/path | +| Frequency | 0.24 | Berapa banyak sinyal jangka pendek yang dikumpulkan entri | +| Relevance | 0.30 | Kualitas pengambilan rata-rata untuk entri | +| Query diversity | 0.15 | Konteks kueri/hari berbeda yang memunculkannya | +| Recency | 0.15 | Skor kesegaran dengan peluruhan waktu | +| Consolidation | 0.10 | Kekuatan kemunculan ulang multi-hari | +| Conceptual richness | 0.06 | Kepadatan tag konsep dari cuplikan/path | -Hit fase Light dan REM menambahkan dorongan kecil yang menurun seiring waktu dari +Hit fase light dan REM menambahkan peningkatan kecil dengan peluruhan recency dari `memory/.dreams/phase-signals.json`. ## Penjadwalan -Saat diaktifkan, `memory-core` mengelola secara 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 cron job untuk sapuan dreaming +penuh. Setiap sapuan menjalankan fase secara berurutan: light -> REM -> deep. -Perilaku kadens default: +Perilaku cadence default: -| Pengaturan | Default | +| Setting | Default | | -------------------- | ----------- | | `dreaming.frequency` | `0 3 * * *` | @@ -133,7 +149,7 @@ Aktifkan dreaming: } ``` -Aktifkan dreaming dengan kadens sapuan kustom: +Aktifkan dreaming dengan cadence sapuan kustom: ```json { @@ -173,7 +189,7 @@ openclaw memory promote --limit 5 openclaw memory status --deep ``` -`memory promote` manual menggunakan ambang fase deep secara default kecuali dioverride +`memory promote` manual menggunakan ambang fase deep secara default kecuali ditimpa dengan flag CLI. Jelaskan mengapa kandidat tertentu akan atau tidak akan dipromosikan: @@ -183,7 +199,7 @@ openclaw memory promote-explain "router vlan" openclaw memory promote-explain "router vlan" --json ``` -Pratinjau refleksi REM, candidate truths, dan output promosi deep tanpa +Pratinjau refleksi REM, candidate truths, dan keluaran promosi deep tanpa menulis apa pun: ```bash @@ -201,24 +217,25 @@ 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 dihadapkan ke pengguna). +(bukan konfigurasi yang ditujukan untuk pengguna). -Lihat [Referensi konfigurasi memory](/id/reference/memory-config#dreaming-experimental) -untuk daftar key lengkap. +Lihat [Referensi konfigurasi Memory](/id/reference/memory-config#dreaming-experimental) +untuk daftar kunci lengkap. ## UI Dreams -Saat diaktifkan, tab **Dreams** di Gateway menampilkan: +Saat diaktifkan, tab **Dreams** Gateway menampilkan: - status dreaming aktif saat ini -- status tingkat fase dan keberadaan managed-sweep -- jumlah jangka pendek, jangka panjang, dan yang dipromosikan hari ini -- waktu proses terjadwal berikutnya +- status tingkat fase dan keberadaan sapuan terkelola +- jumlah jangka pendek, grounded, sinyal, dan yang dipromosikan hari ini +- waktu eksekusi terjadwal berikutnya +- jalur Scene grounded yang berbeda untuk entri replay historis yang disiapkan - pembaca Dream Diary yang dapat diperluas yang didukung oleh `doctor.memory.dreamDiary` ## Terkait - [Memory](/id/concepts/memory) -- [Pencarian Memory](/id/concepts/memory-search) +- [Memory Search](/id/concepts/memory-search) - [CLI memory](/cli/memory) -- [Referensi konfigurasi memory](/id/reference/memory-config) +- [Referensi konfigurasi Memory](/id/reference/memory-config) diff --git a/docs/id/concepts/memory.md b/docs/id/concepts/memory.md index 2faf39f79..5995009a1 100644 --- a/docs/id/concepts/memory.md +++ b/docs/id/concepts/memory.md @@ -2,101 +2,84 @@ read_when: - Anda ingin memahami cara kerja memori - Anda ingin mengetahui file memori apa yang harus ditulis -summary: Bagaimana OpenClaw mengingat berbagai hal di seluruh sesi +summary: Bagaimana OpenClaw mengingat hal-hal di berbagai sesi title: Ikhtisar Memori x-i18n: - generated_at: "2026-04-08T06:00:59Z" + generated_at: "2026-04-09T01:27:51Z" model: gpt-5.4 provider: openai - source_hash: 3bb8552341b0b651609edaaae826a22fdc535d240aed4fad4af4b069454004af + source_hash: 2fe47910f5bf1c44be379e971c605f1cb3a29befcf2a7ee11fb3833cbe3b9059 source_path: concepts/memory.md workflow: 15 --- # Ikhtisar Memori -OpenClaw mengingat berbagai hal dengan menulis **file Markdown biasa** di -workspace agen Anda. Model hanya "mengingat" apa yang disimpan ke disk -- tidak ada -status tersembunyi. +OpenClaw mengingat berbagai hal dengan menulis **file Markdown biasa** di workspace agen Anda. Model hanya "mengingat" apa yang disimpan ke disk -- tidak ada status tersembunyi. ## Cara kerjanya -Agen Anda memiliki tiga file yang terkait dengan memori: +Agen Anda memiliki tiga file terkait memori: -- **`MEMORY.md`** -- memori jangka panjang. Fakta, preferensi, dan - keputusan yang tahan lama. Dimuat pada awal setiap sesi DM. -- **`memory/YYYY-MM-DD.md`** -- catatan harian. Konteks berjalan dan pengamatan. - Catatan hari ini dan kemarin dimuat secara otomatis. -- **`DREAMS.md`** (eksperimental, opsional) -- Buku Harian Mimpi dan ringkasan - penyapuan dreaming untuk ditinjau manusia. +- **`MEMORY.md`** -- memori jangka panjang. Fakta, preferensi, dan keputusan yang tahan lama. Dimuat saat awal setiap sesi DM. +- **`memory/YYYY-MM-DD.md`** -- catatan harian. Konteks berjalan dan pengamatan. Catatan hari ini dan kemarin dimuat secara otomatis. +- **`DREAMS.md`** (eksperimental, opsional) -- Dream Diary dan ringkasan penyapuan dreaming untuk ditinjau manusia, termasuk entri backfill historis yang berlandaskan data. File-file ini berada di workspace agen (default `~/.openclaw/workspace`). Jika Anda ingin agen Anda mengingat sesuatu, cukup minta: "Ingat bahwa saya -lebih memilih TypeScript." Agen akan menuliskannya ke file yang sesuai. +lebih menyukai TypeScript." Agen akan menuliskannya ke file yang sesuai. -## Alat memori +## Tool memori -Agen memiliki dua alat untuk bekerja dengan memori: +Agen memiliki dua tool untuk bekerja dengan memori: -- **`memory_search`** -- menemukan catatan yang relevan menggunakan pencarian semantik, bahkan saat - kata-katanya berbeda dari aslinya. -- **`memory_get`** -- membaca file memori tertentu atau rentang baris. +- **`memory_search`** -- menemukan catatan yang relevan menggunakan pencarian semantik, bahkan ketika susunan katanya berbeda dari aslinya. +- **`memory_get`** -- membaca file memori tertentu atau rentang baris tertentu. -Kedua alat ini disediakan oleh plugin memori yang aktif (default: `memory-core`). +Kedua tool disediakan oleh plugin memori yang aktif (default: `memory-core`). ## Plugin pendamping Memory Wiki -Jika Anda ingin memori tahan lama berperilaku lebih seperti basis pengetahuan yang dipelihara daripada -sekadar catatan mentah, gunakan plugin bawaan `memory-wiki`. +Jika Anda ingin memori tahan lama berfungsi lebih seperti basis pengetahuan yang dipelihara daripada sekadar catatan mentah, gunakan plugin bawaan `memory-wiki`. -`memory-wiki` menyusun pengetahuan tahan lama ke dalam vault wiki dengan: +`memory-wiki` mengompilasi pengetahuan tahan lama ke dalam vault wiki dengan: - struktur halaman yang deterministik - klaim dan bukti yang terstruktur - pelacakan kontradiksi dan kebaruan - dasbor yang dihasilkan - ringkasan terkompilasi untuk konsumen agen/runtime -- alat native wiki seperti `wiki_search`, `wiki_get`, `wiki_apply`, dan `wiki_lint` +- tool native wiki seperti `wiki_search`, `wiki_get`, `wiki_apply`, dan `wiki_lint` -Ini tidak menggantikan plugin memori aktif. Plugin memori aktif tetap -memiliki recall, promosi, dan dreaming. `memory-wiki` menambahkan -lapisan pengetahuan kaya provenance di sampingnya. +Plugin ini tidak menggantikan plugin memori yang aktif. Plugin memori yang aktif tetap memiliki kendali atas recall, promosi, dan dreaming. `memory-wiki` menambahkan lapisan pengetahuan kaya provenance di sampingnya. Lihat [Memory Wiki](/id/plugins/memory-wiki). ## Pencarian memori -Saat penyedia embedding dikonfigurasi, `memory_search` menggunakan **pencarian -hibrida** -- menggabungkan kemiripan vektor (makna semantik) dengan pencocokan kata kunci -(istilah persis seperti ID dan simbol kode). Ini langsung berfungsi setelah Anda memiliki -kunci API untuk penyedia yang didukung. +Ketika penyedia embedding dikonfigurasi, `memory_search` menggunakan **pencarian hibrida** -- menggabungkan kemiripan vektor (makna semantik) dengan pencocokan kata kunci (istilah persis seperti ID dan simbol kode). Ini berfungsi langsung tanpa konfigurasi tambahan setelah Anda memiliki API key untuk penyedia yang didukung. -OpenClaw mendeteksi otomatis penyedia embedding Anda dari kunci API yang tersedia. Jika Anda -telah mengonfigurasi kunci OpenAI, Gemini, Voyage, atau Mistral, pencarian memori -diaktifkan secara otomatis. +OpenClaw mendeteksi otomatis penyedia embedding Anda dari API key yang tersedia. Jika Anda memiliki key OpenAI, Gemini, Voyage, atau Mistral yang dikonfigurasi, pencarian memori akan diaktifkan secara otomatis. -Untuk detail tentang cara kerja pencarian, opsi penyesuaian, dan penyiapan penyedia, lihat -[Pencarian Memori](/id/concepts/memory-search). +Untuk detail tentang cara kerja pencarian, opsi penyetelan, dan penyiapan penyedia, lihat +[Memory Search](/id/concepts/memory-search). ## Backend memori -Berbasis SQLite. Berfungsi langsung dengan pencarian kata kunci, kemiripan vektor, dan -pencarian hibrida. Tanpa dependensi tambahan. +Berbasis SQLite. Berfungsi langsung dengan pencarian kata kunci, kemiripan vektor, dan pencarian hibrida. Tanpa dependensi tambahan. -Sidecar local-first dengan reranking, perluasan kueri, dan kemampuan untuk mengindeks -direktori di luar workspace. +Sidecar local-first dengan reranking, perluasan kueri, dan kemampuan untuk mengindeks direktori di luar workspace. -Memori lintas sesi native AI dengan pemodelan pengguna, pencarian semantik, dan -kesadaran multi-agen. Instalasi plugin. +Memori lintas sesi yang AI-native dengan pemodelan pengguna, pencarian semantik, dan kesadaran multi-agen. Instal plugin. @@ -104,41 +87,60 @@ kesadaran multi-agen. Instalasi plugin. -Menyusun memori tahan lama menjadi vault wiki kaya provenance dengan klaim, -dasbor, mode bridge, dan alur kerja yang ramah Obsidian. +Mengompilasi memori tahan lama menjadi vault wiki kaya provenance dengan klaim, dasbor, mode bridge, dan alur kerja yang ramah Obsidian. ## Flush memori otomatis -Sebelum [compaction](/id/concepts/compaction) merangkum percakapan Anda, OpenClaw -menjalankan giliran senyap yang mengingatkan agen untuk menyimpan konteks penting ke file -memori. Ini aktif secara default -- Anda tidak perlu mengonfigurasi apa pun. +Sebelum [compaction](/id/concepts/compaction) merangkum percakapan Anda, OpenClaw menjalankan giliran diam-diam yang mengingatkan agen untuk menyimpan konteks penting ke file memori. Ini aktif secara default -- Anda tidak perlu mengonfigurasi apa pun. -Flush memori mencegah hilangnya konteks selama compaction. Jika agen Anda memiliki -fakta penting dalam percakapan yang belum ditulis ke file, fakta tersebut -akan disimpan secara otomatis sebelum ringkasan dibuat. +Flush memori mencegah hilangnya konteks selama compaction. Jika agen Anda memiliki fakta penting dalam percakapan yang belum ditulis ke file, fakta tersebut akan disimpan secara otomatis sebelum peringkasan terjadi. ## Dreaming (eksperimental) -Dreaming adalah proses konsolidasi latar belakang opsional untuk memori. Ini mengumpulkan -sinyal jangka pendek, memberi skor pada kandidat, dan hanya mempromosikan item yang memenuhi syarat ke -memori jangka panjang (`MEMORY.md`). +Dreaming adalah proses konsolidasi latar belakang opsional untuk memori. Sistem ini mengumpulkan sinyal jangka pendek, memberi skor pada kandidat, dan hanya mempromosikan item yang memenuhi syarat ke memori jangka panjang (`MEMORY.md`). -Ini dirancang untuk menjaga memori jangka panjang tetap bernilai tinggi: +Sistem ini dirancang untuk menjaga memori jangka panjang tetap bernilai tinggi: - **Opt-in**: dinonaktifkan secara default. -- **Terjadwal**: saat diaktifkan, `memory-core` mengelola otomatis satu pekerjaan cron berulang - untuk penyapuan dreaming penuh. -- **Berambang batas**: promosi harus lolos gerbang skor, frekuensi recall, dan - keragaman kueri. -- **Dapat ditinjau**: ringkasan fase dan entri buku harian ditulis ke `DREAMS.md` - untuk ditinjau manusia. +- **Terjadwal**: ketika diaktifkan, `memory-core` mengelola otomatis satu cron job berulang untuk penyapuan dreaming penuh. +- **Berambang**: promosi harus melewati gerbang skor, frekuensi recall, dan keragaman kueri. +- **Dapat ditinjau**: ringkasan fase dan entri buku harian ditulis ke `DREAMS.md` untuk ditinjau manusia. -Untuk perilaku fase, sinyal penilaian, dan detail Buku Harian Mimpi, lihat -[Dreaming (eksperimental)](/id/concepts/dreaming). +Untuk perilaku fase, sinyal penilaian, dan detail Dream Diary, lihat +[Dreaming (experimental)](/id/concepts/dreaming). + +## Grounded backfill dan promosi langsung + +Sistem dreaming sekarang memiliki dua jalur tinjauan yang sangat terkait: + +- **Live dreaming** bekerja dari penyimpanan dreaming jangka pendek di bawah + `memory/.dreams/` dan inilah yang digunakan fase mendalam normal saat memutuskan apa yang dapat lulus ke `MEMORY.md`. +- **Grounded backfill** membaca catatan historis `memory/YYYY-MM-DD.md` sebagai file harian mandiri dan menulis keluaran tinjauan terstruktur ke `DREAMS.md`. + +Grounded backfill berguna saat Anda ingin memutar ulang catatan lama dan memeriksa apa yang menurut sistem bersifat tahan lama tanpa mengedit `MEMORY.md` secara manual. + +Saat Anda menggunakan: + +```bash +openclaw memory rem-backfill --path ./memory --stage-short-term +``` + +kandidat tahan lama yang berlandaskan data tidak dipromosikan secara langsung. Kandidat tersebut dipentaskan ke penyimpanan dreaming jangka pendek yang sama yang sudah digunakan oleh fase mendalam normal. Artinya: + +- `DREAMS.md` tetap menjadi permukaan tinjauan manusia. +- penyimpanan jangka pendek tetap menjadi permukaan pemeringkatan yang berhadapan dengan mesin. +- `MEMORY.md` tetap hanya ditulis oleh promosi mendalam. + +Jika Anda memutuskan pemutaran ulang itu tidak berguna, Anda dapat menghapus artefak yang dipentaskan tanpa menyentuh entri buku harian biasa atau status recall normal: + +```bash +openclaw memory rem-backfill --rollback +openclaw memory rem-backfill --rollback-short-term +``` ## CLI @@ -148,15 +150,15 @@ openclaw memory search "query" # Cari dari baris perintah openclaw memory index --force # Bangun ulang indeks ``` -## Bacaan lebih lanjut +## Bacaan lanjutan - [Builtin Memory Engine](/id/concepts/memory-builtin) -- backend SQLite default -- [QMD Memory Engine](/id/concepts/memory-qmd) -- sidecar local-first lanjutan -- [Honcho Memory](/id/concepts/memory-honcho) -- memori lintas sesi native AI -- [Memory Wiki](/id/plugins/memory-wiki) -- vault pengetahuan terkompilasi dan alat native wiki +- [QMD Memory Engine](/id/concepts/memory-qmd) -- sidecar local-first tingkat lanjut +- [Honcho Memory](/id/concepts/memory-honcho) -- memori lintas sesi AI-native +- [Memory Wiki](/id/plugins/memory-wiki) -- vault pengetahuan terkompilasi dan tool native wiki - [Memory Search](/id/concepts/memory-search) -- pipeline pencarian, penyedia, dan - penyesuaian -- [Dreaming (eksperimental)](/id/concepts/dreaming) -- promosi latar belakang + penyetelan +- [Dreaming (experimental)](/id/concepts/dreaming) -- promosi latar belakang dari recall jangka pendek ke memori jangka panjang -- [Referensi konfigurasi memori](/id/reference/memory-config) -- semua opsi konfigurasi +- [Memory configuration reference](/id/reference/memory-config) -- semua opsi konfigurasi - [Compaction](/id/concepts/compaction) -- bagaimana compaction berinteraksi dengan memori diff --git a/docs/id/concepts/model-providers.md b/docs/id/concepts/model-providers.md index dbc34eada..de09c641a 100644 --- a/docs/id/concepts/model-providers.md +++ b/docs/id/concepts/model-providers.md @@ -5,17 +5,17 @@ read_when: summary: Ikhtisar penyedia model dengan contoh konfigurasi + alur CLI title: Penyedia Model x-i18n: - generated_at: "2026-04-08T06:02:39Z" + generated_at: "2026-04-09T01:29:50Z" model: gpt-5.4 provider: openai - source_hash: 558ac9e34b67fcc3dd6791a01bebc17e1c34152fa6c5611593d681e8cfa532d9 + source_hash: 53e3141256781002bbe1d7e7b78724a18d061fcf36a203baae04a091b8c9ea1b source_path: concepts/model-providers.md workflow: 15 --- # Penyedia model -Halaman ini membahas **LLM/penyedia model** (bukan saluran chat seperti WhatsApp/Telegram). +Halaman ini membahas **penyedia LLM/model** (bukan saluran chat seperti WhatsApp/Telegram). Untuk aturan pemilihan model, lihat [/concepts/models](/id/concepts/models). ## Aturan cepat @@ -23,17 +23,18 @@ Untuk aturan pemilihan model, lihat [/concepts/models](/id/concepts/models). - Referensi model menggunakan `provider/model` (contoh: `opencode/claude-opus-4-6`). - Jika Anda menetapkan `agents.defaults.models`, itu menjadi allowlist. - Pembantu CLI: `openclaw onboard`, `openclaw models list`, `openclaw models set `. -- Aturan runtime fallback, probe cooldown, dan persistensi override sesi +- Aturan runtime fallback, probe cooldown, dan persistensi penggantian sesi didokumentasikan di [/concepts/model-failover](/id/concepts/model-failover). - `models.providers.*.models[].contextWindow` adalah metadata model native; `models.providers.*.models[].contextTokens` adalah batas runtime efektif. - Plugin penyedia dapat menyuntikkan katalog model melalui `registerProvider({ catalog })`; - OpenClaw menggabungkan output tersebut ke `models.providers` sebelum menulis + OpenClaw menggabungkan output itu ke dalam `models.providers` sebelum menulis `models.json`. -- Manifest penyedia dapat mendeklarasikan `providerAuthEnvVars` sehingga probe auth - berbasis env generik tidak perlu memuat runtime plugin. Peta env-var inti yang - tersisa sekarang hanya untuk penyedia inti/non-plugin dan beberapa kasus - prioritas generik seperti onboarding Anthropic dengan API key lebih dulu. +- Manifest penyedia dapat mendeklarasikan `providerAuthEnvVars` dan + `providerAuthAliases` sehingga probe autentikasi berbasis env generik dan varian penyedia + tidak perlu memuat runtime plugin. Peta env-var inti yang tersisa sekarang + hanya untuk penyedia non-plugin/inti dan beberapa kasus prioritas generik + seperti onboarding Anthropic yang mengutamakan API key. - Plugin penyedia juga dapat memiliki perilaku runtime penyedia melalui `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, @@ -52,17 +53,16 @@ Untuk aturan pemilihan model, lihat [/concepts/models](/id/concepts/models). `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`, `prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot`, dan `onModelSelected`. -- Catatan: `capabilities` runtime penyedia adalah metadata runner bersama (keluarga penyedia, - keanehan transkrip/perkakas, petunjuk transport/cache). Ini bukan - hal yang sama dengan [model capability publik](/id/plugins/architecture#public-capability-model) - yang menjelaskan apa yang didaftarkan sebuah plugin (inferensi teks, ucapan, dll.). +- Catatan: runtime penyedia `capabilities` adalah metadata runner bersama (keluarga penyedia, kekhasan transkrip/tooling, petunjuk transport/cache). Ini bukan + hal yang sama dengan [model kapabilitas publik](/id/plugins/architecture#public-capability-model) + yang menjelaskan apa yang didaftarkan plugin (inferensi teks, ucapan, dll.). ## Perilaku penyedia yang dimiliki plugin -Plugin penyedia kini dapat memiliki sebagian besar logika khusus penyedia sementara OpenClaw mempertahankan +Plugin penyedia sekarang dapat memiliki sebagian besar logika spesifik penyedia sementara OpenClaw tetap menjaga loop inferensi generik. -Pemisahan tipikal: +Pembagian umum: - `auth[].run` / `auth[].runNonInteractive`: penyedia memiliki alur onboarding/login untuk `openclaw onboard`, `openclaw models auth`, dan penyiapan headless @@ -73,156 +73,156 @@ Pemisahan tipikal: lookup atau kanonisasi - `normalizeTransport`: penyedia menormalkan keluarga transport `api` / `baseUrl` sebelum perakitan model generik; OpenClaw memeriksa penyedia yang cocok terlebih dahulu, - lalu plugin penyedia lain yang mendukung hook sampai salah satunya benar-benar mengubah + lalu plugin penyedia lain yang mampu hook sampai salah satunya benar-benar mengubah transport - `normalizeConfig`: penyedia menormalkan konfigurasi `models.providers.` sebelum - digunakan runtime; OpenClaw memeriksa penyedia yang cocok terlebih dahulu, lalu plugin penyedia lain - yang mendukung hook sampai salah satunya benar-benar mengubah konfigurasi. Jika tidak ada - hook penyedia yang menulis ulang konfigurasi, helper keluarga Google bawaan yang dibundel tetap + runtime menggunakannya; OpenClaw memeriksa penyedia yang cocok terlebih dahulu, lalu plugin penyedia lain yang + mampu hook sampai salah satunya benar-benar mengubah konfigurasi. Jika tidak ada + hook penyedia yang menulis ulang konfigurasi, pembantu keluarga Google bawaan yang dibundel masih menormalkan entri penyedia Google yang didukung. -- `applyNativeStreamingUsageCompat`: penyedia menerapkan penulisan ulang kompatibilitas penggunaan streaming native berbasis endpoint untuk penyedia konfigurasi -- `resolveConfigApiKey`: penyedia menyelesaikan auth penanda env untuk penyedia konfigurasi +- `applyNativeStreamingUsageCompat`: penyedia menerapkan penulisan ulang kompatibilitas native streaming-usage berbasis endpoint untuk penyedia konfigurasi +- `resolveConfigApiKey`: penyedia menyelesaikan autentikasi penanda env untuk penyedia konfigurasi tanpa memaksa pemuatan auth runtime penuh. `amazon-bedrock` juga memiliki resolver penanda env AWS bawaan di sini, meskipun auth runtime Bedrock menggunakan rantai default AWS SDK. - `resolveSyntheticAuth`: penyedia dapat mengekspos ketersediaan auth lokal/self-hosted atau auth berbasis konfigurasi lainnya tanpa menyimpan secret plaintext -- `shouldDeferSyntheticProfileAuth`: penyedia dapat menandai placeholder profil sintetis yang tersimpan - memiliki prioritas lebih rendah daripada auth berbasis env/konfigurasi +- `shouldDeferSyntheticProfileAuth`: penyedia dapat menandai placeholder profil sintetis yang disimpan + sebagai prioritas lebih rendah daripada auth berbasis env/konfigurasi - `resolveDynamicModel`: penyedia menerima id model yang belum ada di katalog statis lokal -- `prepareDynamicModel`: penyedia memerlukan refresh metadata sebelum mencoba lagi - resolusi dinamis +- `prepareDynamicModel`: penyedia memerlukan penyegaran metadata sebelum mencoba ulang + resolusi model dinamis - `normalizeResolvedModel`: penyedia memerlukan penulisan ulang transport atau base URL - `contributeResolvedModelCompat`: penyedia menyumbangkan flag compat untuk - model vendornya bahkan ketika model itu datang melalui transport kompatibel lain -- `capabilities`: penyedia menerbitkan keanehan transkrip/perkakas/keluarga penyedia -- `normalizeToolSchemas`: penyedia membersihkan schema tool sebelum runner - tersemat melihatnya -- `inspectToolSchemas`: penyedia memunculkan peringatan schema khusus transport + model vendor miliknya bahkan ketika model itu datang melalui transport kompatibel lain +- `capabilities`: penyedia menerbitkan kekhasan transkrip/tooling/keluarga penyedia +- `normalizeToolSchemas`: penyedia membersihkan skema tool sebelum runner tertanam + melihatnya +- `inspectToolSchemas`: penyedia menampilkan peringatan skema spesifik transport setelah normalisasi - `resolveReasoningOutputMode`: penyedia memilih kontrak output reasoning native vs bertag - `prepareExtraParams`: penyedia menetapkan default atau menormalkan parameter permintaan per model -- `createStreamFn`: penyedia mengganti jalur stream normal dengan transport kustom sepenuhnya -- `wrapStreamFn`: penyedia menerapkan wrapper kompatibilitas header/body/model permintaan -- `resolveTransportTurnState`: penyedia memasok header atau metadata +- `createStreamFn`: penyedia mengganti jalur stream normal dengan transport + kustom penuh +- `wrapStreamFn`: penyedia menerapkan wrapper kompatibilitas request header/body/model +- `resolveTransportTurnState`: penyedia menyuplai header atau metadata transport native per giliran -- `resolveWebSocketSessionPolicy`: penyedia memasok header sesi WebSocket native - atau kebijakan cooldown sesi -- `createEmbeddingProvider`: penyedia memiliki perilaku embedding memori ketika - hal itu lebih tepat berada di plugin penyedia daripada switchboard embedding inti -- `formatApiKey`: penyedia memformat profil auth yang tersimpan ke dalam string - `apiKey` runtime yang diharapkan transport -- `refreshOAuth`: penyedia memiliki refresh OAuth ketika refresher bersama `pi-ai` +- `resolveWebSocketSessionPolicy`: penyedia menyuplai header sesi native WebSocket + atau kebijakan cool-down sesi +- `createEmbeddingProvider`: penyedia memiliki perilaku embedding memori ketika itu + lebih tepat ditempatkan bersama plugin penyedia daripada switchboard embedding inti +- `formatApiKey`: penyedia memformat profil auth yang disimpan ke dalam string + `apiKey` runtime yang diharapkan oleh transport +- `refreshOAuth`: penyedia memiliki penyegaran OAuth ketika penyegar bersama `pi-ai` tidak memadai -- `buildAuthDoctorHint`: penyedia menambahkan panduan perbaikan ketika refresh OAuth +- `buildAuthDoctorHint`: penyedia menambahkan panduan perbaikan ketika penyegaran OAuth gagal -- `matchesContextOverflowError`: penyedia mengenali error overflow jendela konteks - khusus penyedia yang akan terlewat oleh heuristik generik -- `classifyFailoverReason`: penyedia memetakan error mentah transport/API - khusus penyedia ke alasan failover seperti rate limit atau overload +- `matchesContextOverflowError`: penyedia mengenali error luapan context-window spesifik penyedia + yang akan terlewat oleh heuristik generik +- `classifyFailoverReason`: penyedia memetakan error mentah transport/API spesifik penyedia + ke alasan failover seperti rate limit atau overload - `isCacheTtlEligible`: penyedia menentukan id model upstream mana yang mendukung TTL prompt-cache - `buildMissingAuthMessage`: penyedia mengganti error auth-store generik - dengan petunjuk pemulihan khusus penyedia -- `suppressBuiltInModel`: penyedia menyembunyikan baris upstream yang usang dan dapat mengembalikan + dengan petunjuk pemulihan spesifik penyedia +- `suppressBuiltInModel`: penyedia menyembunyikan baris upstream usang dan dapat mengembalikan error milik vendor untuk kegagalan resolusi langsung - `augmentModelCatalog`: penyedia menambahkan baris katalog sintetis/final setelah discovery dan penggabungan konfigurasi -- `isBinaryThinking`: penyedia memiliki UX thinking biner nyala/mati -- `supportsXHighThinking`: penyedia mengikutkan model terpilih ke `xhigh` +- `isBinaryThinking`: penyedia memiliki UX thinking on/off biner +- `supportsXHighThinking`: penyedia memilih model tertentu agar ikut ke `xhigh` - `resolveDefaultThinkingLevel`: penyedia memiliki kebijakan default `/think` untuk keluarga model -- `applyConfigDefaults`: penyedia menerapkan default global khusus penyedia +- `applyConfigDefaults`: penyedia menerapkan default global spesifik penyedia selama materialisasi konfigurasi berdasarkan mode auth, env, atau keluarga model - `isModernModelRef`: penyedia memiliki pencocokan model pilihan live/smoke -- `prepareRuntimeAuth`: penyedia mengubah kredensial terkonfigurasi menjadi token runtime - berumur singkat -- `resolveUsageAuth`: penyedia menyelesaikan kredensial usage/kuota untuk `/usage` +- `prepareRuntimeAuth`: penyedia mengubah kredensial yang dikonfigurasi menjadi token runtime berdurasi pendek +- `resolveUsageAuth`: penyedia menyelesaikan kredensial penggunaan/kuota untuk `/usage` dan permukaan status/pelaporan terkait -- `fetchUsageSnapshot`: penyedia memiliki pengambilan/parsing endpoint usage sementara - inti tetap memiliki shell ringkasan dan pemformatannya +- `fetchUsageSnapshot`: penyedia memiliki pengambilan/penguraian endpoint penggunaan sementara + inti tetap memiliki shell ringkasan dan pemformatan - `onModelSelected`: penyedia menjalankan efek samping pasca-pemilihan seperti - telemetri atau pencatatan sesi milik penyedia + telemetri atau pembukuan sesi milik penyedia Contoh bundel saat ini: -- `anthropic`: fallback kompatibilitas maju Claude 4.6, petunjuk perbaikan auth, pengambilan - endpoint usage, metadata cache-TTL/keluarga penyedia, dan default konfigurasi global +- `anthropic`: fallback kompatibilitas-maju Claude 4.6, petunjuk perbaikan auth, pengambilan + endpoint penggunaan, metadata cache-TTL/keluarga penyedia, dan default konfigurasi global yang sadar auth -- `amazon-bedrock`: pencocokan context-overflow milik penyedia dan klasifikasi - alasan failover untuk error throttle/not-ready khusus Bedrock, ditambah +- `amazon-bedrock`: pencocokan context-overflow milik penyedia dan klasifikasi alasan + failover untuk error throttle/belum-siap khusus Bedrock, ditambah keluarga replay bersama `anthropic-by-model` untuk guard kebijakan replay khusus Claude - pada lalu lintas Anthropic -- `anthropic-vertex`: guard kebijakan replay khusus Claude pada lalu lintas + pada trafik Anthropic +- `anthropic-vertex`: guard kebijakan replay khusus Claude pada trafik pesan Anthropic -- `openrouter`: id model pass-through, wrapper permintaan, petunjuk capability penyedia, - sanitasi thought-signature Gemini pada lalu lintas proxy Gemini, injeksi reasoning proxy - melalui keluarga stream `openrouter-thinking`, penerusan metadata routing, - dan kebijakan cache-TTL -- `github-copilot`: onboarding/login perangkat, fallback model kompatibilitas maju, - petunjuk transkrip Claude-thinking, pertukaran token runtime, dan pengambilan endpoint - usage -- `openai`: fallback kompatibilitas maju GPT-5.4, normalisasi transport OpenAI langsung, - petunjuk auth hilang yang sadar Codex, penekanan Spark, baris katalog sintetis - OpenAI/Codex, kebijakan thinking/model live, normalisasi alias token usage +- `openrouter`: id model pass-through, wrapper request, petunjuk kemampuan penyedia, + sanitasi thought-signature Gemini pada trafik proxy Gemini, injeksi reasoning + proxy melalui keluarga stream `openrouter-thinking`, penerusan metadata + routing, dan kebijakan cache-TTL +- `github-copilot`: onboarding/login perangkat, fallback model kompatibilitas-maju, + petunjuk transkrip Claude-thinking, pertukaran token runtime, dan pengambilan + endpoint penggunaan +- `openai`: fallback kompatibilitas-maju GPT-5.4, normalisasi transport OpenAI langsung, + petunjuk auth hilang yang sadar Codex, suppression Spark, baris katalog + OpenAI/Codex sintetis, kebijakan thinking/live-model, normalisasi alias token penggunaan (`input` / `output` dan keluarga `prompt` / `completion`), keluarga stream bersama - `openai-responses-defaults` untuk wrapper OpenAI/Codex native, metadata keluarga penyedia, - registrasi penyedia pembuatan gambar bundel untuk `gpt-image-1`, dan registrasi penyedia - pembuatan video bundel untuk `sora-2` -- `google` dan `google-gemini-cli`: fallback kompatibilitas maju Gemini 3.1, - validasi replay Gemini native, sanitasi replay bootstrap, mode output - reasoning bertag, pencocokan model modern, registrasi penyedia pembuatan gambar bundel - untuk model pratinjau gambar Gemini, dan registrasi penyedia pembuatan - video bundel untuk model Veo; OAuth Gemini CLI juga memiliki pemformatan token profil auth, - parsing token usage, dan pengambilan endpoint kuota untuk permukaan usage + `openai-responses-defaults` untuk wrapper native OpenAI/Codex, + metadata keluarga penyedia, pendaftaran penyedia pembuatan gambar bundel + untuk `gpt-image-1`, dan pendaftaran penyedia pembuatan video bundel + untuk `sora-2` +- `google` dan `google-gemini-cli`: fallback kompatibilitas-maju Gemini 3.1, + validasi replay Gemini native, sanitasi replay bootstrap, mode + output reasoning bertag, pencocokan model modern, pendaftaran penyedia pembuatan gambar bundel + untuk model pratinjau gambar Gemini, dan pendaftaran + penyedia pembuatan video bundel untuk model Veo; Gemini CLI OAuth juga + memiliki pemformatan token profil auth, penguraian token penggunaan, dan pengambilan + endpoint kuota untuk permukaan penggunaan - `moonshot`: transport bersama, normalisasi payload thinking milik plugin -- `kilocode`: transport bersama, header permintaan milik plugin, normalisasi payload reasoning, +- `kilocode`: transport bersama, header request milik plugin, normalisasi payload reasoning, sanitasi thought-signature proxy-Gemini, dan kebijakan cache-TTL -- `zai`: fallback kompatibilitas maju GLM-5, default `tool_stream`, kebijakan cache-TTL, - kebijakan thinking biner/model live, serta auth usage + pengambilan kuota; - id `glm-5*` yang tidak dikenal disintesis dari templat `glm-4.7` bawaan +- `zai`: fallback kompatibilitas-maju GLM-5, default `tool_stream`, kebijakan cache-TTL, + kebijakan binary-thinking/live-model, dan auth penggunaan + pengambilan kuota; + id `glm-5*` yang tidak dikenal disintesis dari templat `glm-4.7` yang dibundel - `xai`: normalisasi transport Responses native, penulisan ulang alias `/fast` untuk - varian cepat Grok, default `tool_stream`, pembersihan schema tool / - payload reasoning khusus xAI, dan registrasi penyedia pembuatan video bundel + varian cepat Grok, default `tool_stream`, pembersihan skema tool / + payload reasoning khusus xAI, dan pendaftaran penyedia pembuatan video bundel untuk `grok-imagine-video` -- `mistral`: metadata capability milik plugin -- `opencode` dan `opencode-go`: metadata capability milik plugin plus +- `mistral`: metadata kemampuan milik plugin +- `opencode` dan `opencode-go`: metadata kemampuan milik plugin plus sanitasi thought-signature proxy-Gemini -- `alibaba`: katalog pembuatan video milik plugin untuk referensi model Wan langsung +- `alibaba`: katalog video-generation milik plugin untuk referensi model Wan langsung seperti `alibaba/wan2.6-t2v` -- `byteplus`: katalog milik plugin plus registrasi penyedia pembuatan video bundel +- `byteplus`: katalog milik plugin plus pendaftaran penyedia video-generation bundel untuk model text-to-video/image-to-video Seedance -- `fal`: registrasi penyedia pembuatan video bundel untuk image-generation pihak ketiga terhosting - registrasi penyedia pembuatan gambar untuk model gambar FLUX plus registrasi penyedia - pembuatan video bundel untuk model video pihak ketiga terhosting +- `fal`: pendaftaran penyedia video-generation bundel untuk provider image-generation pihak ketiga terhosting + bagi model gambar FLUX plus pendaftaran penyedia video-generation bundel untuk model video pihak ketiga terhosting - `cloudflare-ai-gateway`, `huggingface`, `kimi`, `nvidia`, `qianfan`, `stepfun`, `synthetic`, `venice`, `vercel-ai-gateway`, dan `volcengine`: hanya katalog milik plugin -- `qwen`: katalog milik plugin untuk model teks plus registrasi penyedia - media-understanding dan pembuatan video bersama untuk permukaan multimodalnya; - pembuatan video Qwen menggunakan endpoint video DashScope Standar dengan model Wan - bundel seperti `wan2.6-t2v` dan `wan2.7-r2v` -- `runway`: registrasi penyedia pembuatan video milik plugin untuk model native - berbasis tugas Runway seperti `gen4.5` -- `minimax`: katalog milik plugin, registrasi penyedia pembuatan video bundel - untuk model video Hailuo, registrasi penyedia pembuatan gambar bundel - untuk `image-01`, pemilihan kebijakan replay Anthropic/OpenAI hibrida, - dan logika auth/snapshot usage -- `together`: katalog milik plugin plus registrasi penyedia pembuatan video bundel +- `qwen`: katalog milik plugin untuk model teks plus pendaftaran provider + media-understanding dan video-generation bersama untuk permukaan multimodalnya; + pembuatan video Qwen menggunakan endpoint video DashScope Standar dengan + model Wan bundel seperti `wan2.6-t2v` dan `wan2.7-r2v` +- `runway`: pendaftaran penyedia video-generation milik plugin untuk model native + Runway berbasis tugas seperti `gen4.5` +- `minimax`: katalog milik plugin, pendaftaran penyedia video-generation bundel + untuk model video Hailuo, pendaftaran penyedia image-generation bundel + untuk `image-01`, pemilihan kebijakan replay Anthropic/OpenAI hibrida, dan logika auth/snapshot penggunaan +- `together`: katalog milik plugin plus pendaftaran penyedia video-generation bundel untuk model video Wan -- `xiaomi`: katalog milik plugin plus logika auth/snapshot usage +- `xiaomi`: katalog milik plugin plus logika auth/snapshot penggunaan Plugin `openai` yang dibundel sekarang memiliki kedua id penyedia: `openai` dan `openai-codex`. Itu mencakup penyedia yang masih sesuai dengan transport normal OpenClaw. Penyedia -yang membutuhkan eksekutor permintaan kustom sepenuhnya adalah permukaan ekstensi -terpisah yang lebih dalam. +yang memerlukan eksekutor permintaan kustom sepenuhnya adalah permukaan ekstensi +yang terpisah dan lebih dalam. ## Rotasi API key -- Mendukung rotasi penyedia generik untuk penyedia tertentu yang dipilih. +- Mendukung rotasi penyedia generik untuk penyedia tertentu. - Konfigurasikan beberapa key melalui: - - `OPENCLAW_LIVE__KEY` (override live tunggal, prioritas tertinggi) + - `OPENCLAW_LIVE__KEY` (satu override live, prioritas tertinggi) - `_API_KEYS` (daftar dipisahkan koma atau titik koma) - `_API_KEY` (key utama) - `_API_KEY_*` (daftar bernomor, misalnya `_API_KEY_1`) @@ -237,28 +237,28 @@ concurrent requests`, `ThrottlingException`, `concurrency limit reached`, ## Penyedia bawaan (katalog pi-ai) -OpenClaw disertakan dengan katalog pi‑ai. Penyedia ini tidak memerlukan konfigurasi -`models.providers`; cukup tetapkan auth + pilih model. +OpenClaw dikirim dengan katalog pi-ai. Penyedia ini tidak memerlukan +konfigurasi `models.providers`; cukup tetapkan auth + pilih model. ### OpenAI - Penyedia: `openai` - Auth: `OPENAI_API_KEY` -- Rotasi opsional: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, plus `OPENCLAW_LIVE_OPENAI_KEY` (override tunggal) +- Rotasi opsional: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, plus `OPENCLAW_LIVE_OPENAI_KEY` (satu override) - Contoh model: `openai/gpt-5.4`, `openai/gpt-5.4-pro` - CLI: `openclaw onboard --auth-choice openai-api-key` -- Transport default adalah `auto` (WebSocket lebih dulu, fallback SSE) -- Override per model melalui `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"`, atau `"auto"`) -- Pemanasan WebSocket OpenAI Responses secara default aktif melalui `params.openaiWsWarmup` (`true`/`false`) +- Transport default adalah `auto` (mengutamakan WebSocket, fallback SSE) +- Ganti per model melalui `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"`, atau `"auto"`) +- Warm-up WebSocket OpenAI Responses secara default diaktifkan melalui `params.openaiWsWarmup` (`true`/`false`) - Pemrosesan prioritas OpenAI dapat diaktifkan melalui `agents.defaults.models["openai/"].params.serviceTier` -- `/fast` dan `params.fastMode` memetakan permintaan Responses `openai/*` langsung ke `service_tier=priority` pada `api.openai.com` -- Gunakan `params.serviceTier` bila Anda menginginkan tier eksplisit alih-alih toggle `/fast` bersama +- `/fast` dan `params.fastMode` memetakan permintaan Responses `openai/*` langsung ke `service_tier=priority` di `api.openai.com` +- Gunakan `params.serviceTier` ketika Anda menginginkan tier eksplisit alih-alih toggle bersama `/fast` - Header atribusi OpenClaw tersembunyi (`originator`, `version`, - `User-Agent`) hanya berlaku pada lalu lintas OpenAI native ke `api.openai.com`, bukan + `User-Agent`) hanya berlaku pada trafik OpenAI native ke `api.openai.com`, bukan proxy generik yang kompatibel dengan OpenAI - Rute OpenAI native juga mempertahankan `store` Responses, petunjuk prompt-cache, dan pembentukan payload kompatibilitas reasoning OpenAI; rute proxy tidak -- `openai/gpt-5.3-codex-spark` sengaja ditekan di OpenClaw karena API OpenAI live menolaknya; Spark diperlakukan sebagai khusus Codex +- `openai/gpt-5.3-codex-spark` sengaja disuppress di OpenClaw karena OpenAI API live menolaknya; Spark diperlakukan hanya sebagai Codex ```json5 { @@ -270,12 +270,12 @@ OpenClaw disertakan dengan katalog pi‑ai. Penyedia ini tidak memerlukan konfig - Penyedia: `anthropic` - Auth: `ANTHROPIC_API_KEY` -- Rotasi opsional: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, plus `OPENCLAW_LIVE_ANTHROPIC_KEY` (override tunggal) +- Rotasi opsional: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, plus `OPENCLAW_LIVE_ANTHROPIC_KEY` (satu override) - Contoh model: `anthropic/claude-opus-4-6` - CLI: `openclaw onboard --auth-choice apiKey` -- Permintaan Anthropic publik langsung mendukung toggle `/fast` bersama dan `params.fastMode`, termasuk lalu lintas terautentikasi API key dan OAuth yang dikirim ke `api.anthropic.com`; OpenClaw memetakannya ke Anthropic `service_tier` (`auto` vs `standard_only`) -- Catatan Anthropic: staf Anthropic memberi tahu kami bahwa penggunaan Claude CLI gaya OpenClaw diizinkan lagi, jadi OpenClaw memperlakukan penggunaan ulang Claude CLI dan penggunaan `claude -p` sebagai diizinkan untuk integrasi ini kecuali Anthropic menerbitkan kebijakan baru. -- Token setup Anthropic tetap tersedia sebagai jalur token OpenClaw yang didukung, tetapi OpenClaw sekarang lebih mengutamakan penggunaan ulang Claude CLI dan `claude -p` saat tersedia. +- Permintaan Anthropic publik langsung mendukung toggle bersama `/fast` dan `params.fastMode`, termasuk trafik yang diautentikasi dengan API key dan OAuth yang dikirim ke `api.anthropic.com`; OpenClaw memetakannya ke Anthropic `service_tier` (`auto` vs `standard_only`) +- Catatan Anthropic: staf Anthropic memberi tahu kami bahwa penggunaan Claude CLI bergaya OpenClaw diizinkan lagi, jadi OpenClaw memperlakukan penggunaan ulang Claude CLI dan penggunaan `claude -p` sebagai diizinkan untuk integrasi ini kecuali Anthropic menerbitkan kebijakan baru. +- Setup-token Anthropic tetap tersedia sebagai jalur token OpenClaw yang didukung, tetapi OpenClaw sekarang lebih mengutamakan penggunaan ulang Claude CLI dan `claude -p` bila tersedia. ```json5 { @@ -289,16 +289,16 @@ OpenClaw disertakan dengan katalog pi‑ai. Penyedia ini tidak memerlukan konfig - Auth: OAuth (ChatGPT) - Contoh model: `openai-codex/gpt-5.4` - CLI: `openclaw onboard --auth-choice openai-codex` atau `openclaw models auth login --provider openai-codex` -- Transport default adalah `auto` (WebSocket lebih dulu, fallback SSE) -- Override per model melalui `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"`, atau `"auto"`) +- Transport default adalah `auto` (mengutamakan WebSocket, fallback SSE) +- Ganti per model melalui `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"`, atau `"auto"`) - `params.serviceTier` juga diteruskan pada permintaan Responses Codex native (`chatgpt.com/backend-api`) - Header atribusi OpenClaw tersembunyi (`originator`, `version`, - `User-Agent`) hanya dilampirkan pada lalu lintas Codex native ke + `User-Agent`) hanya dilampirkan pada trafik Codex native ke `chatgpt.com/backend-api`, bukan proxy generik yang kompatibel dengan OpenAI - Berbagi toggle `/fast` dan konfigurasi `params.fastMode` yang sama seperti `openai/*` langsung; OpenClaw memetakannya ke `service_tier=priority` - `openai-codex/gpt-5.3-codex-spark` tetap tersedia ketika katalog OAuth Codex mengeksposnya; bergantung pada entitlement -- `openai-codex/gpt-5.4` mempertahankan `contextWindow = 1050000` native dan runtime default `contextTokens = 272000`; override batas runtime dengan `models.providers.openai-codex.models[].contextTokens` -- Catatan kebijakan: OAuth OpenAI Codex secara eksplisit didukung untuk tool/alur kerja eksternal seperti OpenClaw. +- `openai-codex/gpt-5.4` mempertahankan `contextWindow = 1050000` native dan default runtime `contextTokens = 272000`; ganti batas runtime dengan `models.providers.openai-codex.models[].contextTokens` +- Catatan kebijakan: OpenAI Codex OAuth secara eksplisit didukung untuk tool/alur kerja eksternal seperti OpenClaw. ```json5 { @@ -318,7 +318,7 @@ OpenClaw disertakan dengan katalog pi‑ai. Penyedia ini tidak memerlukan konfig } ``` -### Opsi terhosting bergaya langganan lainnya +### Opsi hosted bergaya langganan lainnya - [Qwen Cloud](/id/providers/qwen): permukaan penyedia Qwen Cloud plus pemetaan endpoint Alibaba DashScope dan Coding Plan - [MiniMax](/id/providers/minimax): akses OAuth atau API key MiniMax Coding Plan @@ -342,30 +342,30 @@ OpenClaw disertakan dengan katalog pi‑ai. Penyedia ini tidak memerlukan konfig - Penyedia: `google` - Auth: `GEMINI_API_KEY` -- Rotasi opsional: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, fallback `GOOGLE_API_KEY`, dan `OPENCLAW_LIVE_GEMINI_KEY` (override tunggal) +- Rotasi opsional: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, fallback `GOOGLE_API_KEY`, dan `OPENCLAW_LIVE_GEMINI_KEY` (satu override) - Contoh model: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview` - Kompatibilitas: konfigurasi OpenClaw lama yang menggunakan `google/gemini-3.1-flash-preview` dinormalkan menjadi `google/gemini-3-flash-preview` - CLI: `openclaw onboard --auth-choice gemini-api-key` - Eksekusi Gemini langsung juga menerima `agents.defaults.models["google/"].params.cachedContent` - (atau `cached_content` lama) untuk meneruskan handle `cachedContents/...` - native penyedia; cache hit Gemini muncul sebagai OpenClaw `cacheRead` + (atau `cached_content` lama) untuk meneruskan handle + `cachedContents/...` native penyedia; hit cache Gemini muncul sebagai OpenClaw `cacheRead` ### Google Vertex dan Gemini CLI - Penyedia: `google-vertex`, `google-gemini-cli` -- Auth: Vertex menggunakan gcloud ADC; Gemini CLI menggunakan alur OAuth-nya -- Peringatan: OAuth Gemini CLI di OpenClaw adalah integrasi tidak resmi. Beberapa pengguna melaporkan pembatasan akun Google setelah menggunakan klien pihak ketiga. Tinjau persyaratan Google dan gunakan akun yang tidak kritis jika Anda memilih untuk melanjutkan. -- OAuth Gemini CLI dikirim sebagai bagian dari plugin `google` yang dibundel. +- Auth: Vertex menggunakan ADC gcloud; Gemini CLI menggunakan alur OAuth-nya +- Perhatian: Gemini CLI OAuth di OpenClaw adalah integrasi tidak resmi. Beberapa pengguna melaporkan pembatasan akun Google setelah menggunakan klien pihak ketiga. Tinjau ketentuan Google dan gunakan akun yang tidak kritis jika Anda memilih untuk melanjutkan. +- Gemini CLI OAuth dikirim sebagai bagian dari plugin `google` yang dibundel. - Instal Gemini CLI terlebih dahulu: - `brew install gemini-cli` - atau `npm install -g @google/gemini-cli` - Aktifkan: `openclaw plugins enable google` - Login: `openclaw models auth login --provider google-gemini-cli --set-default` - Model default: `google-gemini-cli/gemini-3-flash-preview` - - Catatan: Anda **tidak** menempelkan client id atau secret ke dalam `openclaw.json`. Alur login CLI menyimpan - token di profil auth pada host gateway. - - Jika permintaan gagal setelah login, tetapkan `GOOGLE_CLOUD_PROJECT` atau `GOOGLE_CLOUD_PROJECT_ID` pada host gateway. - - Balasan JSON Gemini CLI diparsing dari `response`; usage menggunakan fallback ke + - Catatan: Anda **tidak** menempelkan client id atau secret ke `openclaw.json`. Alur login CLI menyimpan + token dalam profil auth di host gateway. + - Jika permintaan gagal setelah login, tetapkan `GOOGLE_CLOUD_PROJECT` atau `GOOGLE_CLOUD_PROJECT_ID` di host gateway. + - Balasan JSON Gemini CLI diurai dari `response`; penggunaan fallback ke `stats`, dengan `stats.cached` dinormalkan menjadi OpenClaw `cacheRead`. ### Z.AI (GLM) @@ -391,11 +391,11 @@ OpenClaw disertakan dengan katalog pi‑ai. Penyedia ini tidak memerlukan konfig - Contoh model: `kilocode/kilo/auto` - CLI: `openclaw onboard --auth-choice kilocode-api-key` - Base URL: `https://api.kilo.ai/api/gateway/` -- Katalog fallback statis mengirim `kilocode/kilo/auto`; discovery live +- Katalog fallback statis dikirim dengan `kilocode/kilo/auto`; discovery live `https://api.kilo.ai/api/gateway/models` dapat memperluas katalog runtime lebih lanjut. - Routing upstream yang tepat di balik `kilocode/kilo/auto` dimiliki oleh Kilo Gateway, - bukan di-hardcode di OpenClaw. + bukan di-hardcode dalam OpenClaw. Lihat [/providers/kilocode](/id/providers/kilocode) untuk detail penyiapan. @@ -403,26 +403,25 @@ Lihat [/providers/kilocode](/id/providers/kilocode) untuk detail penyiapan. - OpenRouter: `openrouter` (`OPENROUTER_API_KEY`) - Contoh model: `openrouter/auto` -- OpenClaw menerapkan header atribusi aplikasi yang didokumentasikan OpenRouter hanya ketika +- OpenClaw menerapkan header atribusi aplikasi OpenRouter yang terdokumentasi hanya ketika permintaan benar-benar menargetkan `openrouter.ai` - Penanda `cache_control` Anthropic khusus OpenRouter juga dibatasi ke - rute OpenRouter yang terverifikasi, bukan URL proxy sembarang -- OpenRouter tetap berada pada jalur kompatibel OpenAI bergaya proxy, jadi pembentukan permintaan - native khusus OpenAI (`serviceTier`, Responses `store`, + rute OpenRouter terverifikasi, bukan URL proxy sembarang +- OpenRouter tetap berada di jalur kompatibel OpenAI bergaya proxy, sehingga pembentukan permintaan khusus OpenAI native (`serviceTier`, Responses `store`, petunjuk prompt-cache, payload kompatibilitas reasoning OpenAI) tidak diteruskan - Referensi OpenRouter berbasis Gemini hanya mempertahankan sanitasi thought-signature proxy-Gemini; validasi replay Gemini native dan penulisan ulang bootstrap tetap nonaktif - Kilo Gateway: `kilocode` (`KILOCODE_API_KEY`) - Contoh model: `kilocode/kilo/auto` - Referensi Kilo berbasis Gemini mempertahankan jalur sanitasi thought-signature - proxy-Gemini yang sama; `kilocode/kilo/auto` dan petunjuk lain yang tidak mendukung proxy-reasoning + proxy-Gemini yang sama; `kilocode/kilo/auto` dan petunjuk lain yang tidak mendukung reasoning-proxy melewati injeksi reasoning proxy - MiniMax: `minimax` (API key) dan `minimax-portal` (OAuth) - Auth: `MINIMAX_API_KEY` untuk `minimax`; `MINIMAX_OAUTH_TOKEN` atau `MINIMAX_API_KEY` untuk `minimax-portal` - Contoh model: `minimax/MiniMax-M2.7` atau `minimax-portal/MiniMax-M2.7` - Penyiapan onboarding/API key MiniMax menulis definisi model M2.7 eksplisit dengan - `input: ["text", "image"]`; katalog penyedia bundel mempertahankan referensi chat - hanya teks sampai konfigurasi penyedia itu dimaterialisasikan + `input: ["text", "image"]`; katalog penyedia bundel menjaga referensi chat + tetap teks-saja sampai konfigurasi penyedia itu dimaterialisasikan - Moonshot: `moonshot` (`MOONSHOT_API_KEY`) - Contoh model: `moonshot/kimi-k2.5` - Kimi Coding: `kimi` (`KIMI_API_KEY` atau `KIMICODE_API_KEY`) @@ -448,7 +447,7 @@ Lihat [/providers/kilocode](/id/providers/kilocode) untuk detail penyiapan. - BytePlus: `byteplus` (`BYTEPLUS_API_KEY`) - Contoh model: `byteplus-plan/ark-code-latest` - xAI: `xai` (`XAI_API_KEY`) - - Permintaan xAI bundel native menggunakan jalur xAI Responses + - Permintaan xAI native bundel menggunakan jalur xAI Responses - `/fast` atau `params.fastMode: true` menulis ulang `grok-3`, `grok-3-mini`, `grok-4`, dan `grok-4-0709` ke varian `*-fast` mereka - `tool_stream` default aktif; tetapkan @@ -459,25 +458,25 @@ Lihat [/providers/kilocode](/id/providers/kilocode) untuk detail penyiapan. - CLI: `openclaw onboard --auth-choice mistral-api-key` - Groq: `groq` (`GROQ_API_KEY`) - Cerebras: `cerebras` (`CEREBRAS_API_KEY`) - - Model GLM pada Cerebras menggunakan id `zai-glm-4.7` dan `zai-glm-4.6`. + - Model GLM di Cerebras menggunakan id `zai-glm-4.7` dan `zai-glm-4.6`. - Base URL kompatibel OpenAI: `https://api.cerebras.ai/v1`. - GitHub Copilot: `github-copilot` (`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`) - Contoh model Hugging Face Inference: `huggingface/deepseek-ai/DeepSeek-R1`; CLI: `openclaw onboard --auth-choice huggingface-api-key`. Lihat [Hugging Face (Inference)](/id/providers/huggingface). -## Penyedia melalui `models.providers` (kustom/base URL) +## Penyedia melalui `models.providers` (custom/base URL) -Gunakan `models.providers` (atau `models.json`) untuk menambahkan penyedia **kustom** -atau proxy yang kompatibel dengan OpenAI/Anthropic. +Gunakan `models.providers` (atau `models.json`) untuk menambahkan penyedia **kustom** atau +proxy yang kompatibel dengan OpenAI/Anthropic. Banyak plugin penyedia bundel di bawah ini sudah menerbitkan katalog default. -Gunakan entri `models.providers.` yang eksplisit hanya ketika Anda ingin menimpa -base URL, header, atau daftar model default. +Gunakan entri `models.providers.` eksplisit hanya ketika Anda ingin mengganti +default base URL, header, atau daftar model. ### Moonshot AI (Kimi) Moonshot dikirim sebagai plugin penyedia bundel. Gunakan penyedia bawaan secara -default, dan tambahkan entri `models.providers.moonshot` yang eksplisit hanya ketika Anda -perlu menimpa base URL atau metadata model: +default, dan tambahkan entri `models.providers.moonshot` eksplisit hanya ketika Anda +perlu mengganti base URL atau metadata model: - Penyedia: `moonshot` - Auth: `MOONSHOT_API_KEY` @@ -550,13 +549,13 @@ Volcano Engine (火山引擎) menyediakan akses ke Doubao dan model lain di Tion } ``` -Onboarding default ke permukaan coding, tetapi katalog umum `volcengine/*` +Onboarding secara default menggunakan permukaan coding, tetapi katalog umum `volcengine/*` didaftarkan pada saat yang sama. -Dalam pemilih model onboarding/konfigurasi, pilihan auth Volcengine lebih mengutamakan kedua -baris `volcengine/*` dan `volcengine-plan/*`. Jika model-model itu belum dimuat, -OpenClaw kembali ke katalog yang tidak difilter alih-alih menampilkan pemilih -bercakupan penyedia yang kosong. +Dalam pemilih model onboarding/konfigurasi, pilihan auth Volcengine mengutamakan kedua +baris `volcengine/*` dan `volcengine-plan/*`. Jika model tersebut belum dimuat, +OpenClaw fallback ke katalog tanpa filter alih-alih menampilkan pemilih +yang dibatasi penyedia namun kosong. Model yang tersedia: @@ -576,7 +575,7 @@ Model coding (`volcengine-plan`): ### BytePlus (Internasional) -BytePlus ARK menyediakan akses ke model yang sama seperti Volcano Engine untuk pengguna internasional. +BytePlus ARK menyediakan akses ke model yang sama dengan Volcano Engine untuk pengguna internasional. - Penyedia: `byteplus` (coding: `byteplus-plan`) - Auth: `BYTEPLUS_API_KEY` @@ -591,13 +590,13 @@ BytePlus ARK menyediakan akses ke model yang sama seperti Volcano Engine untuk p } ``` -Onboarding default ke permukaan coding, tetapi katalog umum `byteplus/*` +Onboarding secara default menggunakan permukaan coding, tetapi katalog umum `byteplus/*` didaftarkan pada saat yang sama. -Dalam pemilih model onboarding/konfigurasi, pilihan auth BytePlus lebih mengutamakan kedua -baris `byteplus/*` dan `byteplus-plan/*`. Jika model-model itu belum dimuat, -OpenClaw kembali ke katalog yang tidak difilter alih-alih menampilkan pemilih -bercakupan penyedia yang kosong. +Dalam pemilih model onboarding/konfigurasi, pilihan auth BytePlus mengutamakan kedua +baris `byteplus/*` dan `byteplus-plan/*`. Jika model tersebut belum dimuat, +OpenClaw fallback ke katalog tanpa filter alih-alih menampilkan pemilih +yang dibatasi penyedia namun kosong. Model yang tersedia: @@ -647,23 +646,23 @@ MiniMax dikonfigurasi melalui `models.providers` karena menggunakan endpoint kus - MiniMax OAuth (Global): `--auth-choice minimax-global-oauth` - MiniMax OAuth (CN): `--auth-choice minimax-cn-oauth` -- API key MiniMax (Global): `--auth-choice minimax-global-api` -- API key MiniMax (CN): `--auth-choice minimax-cn-api` +- MiniMax API key (Global): `--auth-choice minimax-global-api` +- MiniMax API key (CN): `--auth-choice minimax-cn-api` - Auth: `MINIMAX_API_KEY` untuk `minimax`; `MINIMAX_OAUTH_TOKEN` atau `MINIMAX_API_KEY` untuk `minimax-portal` -Lihat [/providers/minimax](/id/providers/minimax) untuk detail penyiapan, opsi model, dan snippet konfigurasi. +Lihat [/providers/minimax](/id/providers/minimax) untuk detail penyiapan, opsi model, dan cuplikan konfigurasi. Pada jalur streaming MiniMax yang kompatibel dengan Anthropic, OpenClaw menonaktifkan thinking secara -default kecuali Anda menetapkannya secara eksplisit, dan `/fast on` menulis ulang +default kecuali Anda secara eksplisit menetapkannya, dan `/fast on` menulis ulang `MiniMax-M2.7` menjadi `MiniMax-M2.7-highspeed`. -Pemisahan capability milik plugin: +Pembagian kapabilitas milik plugin: - Default teks/chat tetap pada `minimax/MiniMax-M2.7` - Pembuatan gambar adalah `minimax/image-01` atau `minimax-portal/image-01` - Pemahaman gambar adalah `MiniMax-VL-01` milik plugin pada kedua jalur auth MiniMax -- Web search tetap pada id penyedia `minimax` +- Pencarian web tetap pada id penyedia `minimax` ### Ollama @@ -675,7 +674,7 @@ Ollama dikirim sebagai plugin penyedia bundel dan menggunakan API native Ollama: - Instalasi: [https://ollama.com/download](https://ollama.com/download) ```bash -# Install Ollama, then pull a model: +# Instal Ollama, lalu tarik model: ollama pull llama3.3 ``` @@ -687,20 +686,20 @@ ollama pull llama3.3 } ``` -Ollama terdeteksi secara lokal di `http://127.0.0.1:11434` ketika Anda memilih ikut serta dengan +Ollama dideteksi secara lokal di `http://127.0.0.1:11434` ketika Anda ikut serta dengan `OLLAMA_API_KEY`, dan plugin penyedia bundel menambahkan Ollama langsung ke `openclaw onboard` dan pemilih model. Lihat [/providers/ollama](/id/providers/ollama) untuk onboarding, mode cloud/lokal, dan konfigurasi kustom. ### vLLM -vLLM dikirim sebagai plugin penyedia bundel untuk server OpenAI-compatible lokal/self-hosted: +vLLM dikirim sebagai plugin penyedia bundel untuk server lokal/self-hosted yang kompatibel dengan OpenAI: - Penyedia: `vllm` -- Auth: Opsional (tergantung server Anda) +- Auth: Opsional (bergantung pada server Anda) - Base URL default: `http://127.0.0.1:8000/v1` -Untuk ikut serta dalam auto-discovery secara lokal (nilai apa pun bisa digunakan jika server Anda tidak memaksa auth): +Untuk ikut serta dalam auto-discovery secara lokal (nilai apa pun berfungsi jika server Anda tidak menerapkan auth): ```bash export VLLM_API_KEY="vllm-local" @@ -720,15 +719,14 @@ Lihat [/providers/vllm](/id/providers/vllm) untuk detail. ### SGLang -SGLang dikirim sebagai plugin penyedia bundel untuk server -OpenAI-compatible self-hosted yang cepat: +SGLang dikirim sebagai plugin penyedia bundel untuk server self-hosted cepat yang kompatibel dengan OpenAI: - Penyedia: `sglang` -- Auth: Opsional (tergantung server Anda) +- Auth: Opsional (bergantung pada server Anda) - Base URL default: `http://127.0.0.1:30000/v1` -Untuk ikut serta dalam auto-discovery secara lokal (nilai apa pun bisa digunakan jika server Anda tidak -memaksa auth): +Untuk ikut serta dalam auto-discovery secara lokal (nilai apa pun berfungsi jika server Anda tidak +menerapkan auth): ```bash export SGLANG_API_KEY="sglang-local" @@ -748,7 +746,7 @@ Lihat [/providers/sglang](/id/providers/sglang) untuk detail. ### Proxy lokal (LM Studio, vLLM, LiteLLM, dll.) -Contoh (kompatibel OpenAI): +Contoh (kompatibel dengan OpenAI): ```json5 { @@ -784,19 +782,19 @@ Contoh (kompatibel OpenAI): Catatan: - Untuk penyedia kustom, `reasoning`, `input`, `cost`, `contextWindow`, dan `maxTokens` bersifat opsional. - Jika dihilangkan, default OpenClaw adalah: + Jika dihilangkan, OpenClaw menggunakan default: - `reasoning: false` - `input: ["text"]` - `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }` - `contextWindow: 200000` - `maxTokens: 8192` - Disarankan: tetapkan nilai eksplisit yang sesuai dengan batas proxy/model Anda. -- Untuk `api: "openai-completions"` pada endpoint non-native (setiap `baseUrl` tidak kosong yang host-nya bukan `api.openai.com`), OpenClaw memaksa `compat.supportsDeveloperRole: false` untuk menghindari error 400 penyedia untuk role `developer` yang tidak didukung. -- Rute kompatibel OpenAI bergaya proxy juga melewati pembentukan permintaan native khusus OpenAI: +- Untuk `api: "openai-completions"` pada endpoint non-native (setiap `baseUrl` tidak kosong yang host-nya bukan `api.openai.com`), OpenClaw memaksa `compat.supportsDeveloperRole: false` untuk menghindari error 400 dari penyedia atas peran `developer` yang tidak didukung. +- Rute kompatibel OpenAI bergaya proxy juga melewati pembentukan permintaan khusus OpenAI native: tidak ada `service_tier`, tidak ada Responses `store`, tidak ada petunjuk prompt-cache, tidak ada - pembentukan payload kompatibilitas reasoning OpenAI, dan tidak ada header atribusi OpenClaw - tersembunyi. -- Jika `baseUrl` kosong/dihilangkan, OpenClaw mempertahankan perilaku default OpenAI (yang diselesaikan ke `api.openai.com`). + pembentukan payload kompatibilitas reasoning OpenAI, dan tidak ada header + atribusi OpenClaw tersembunyi. +- Jika `baseUrl` kosong/dihilangkan, OpenClaw mempertahankan perilaku OpenAI default (yang mengarah ke `api.openai.com`). - Demi keamanan, `compat.supportsDeveloperRole: true` yang eksplisit tetap ditimpa pada endpoint `openai-completions` non-native. ## Contoh CLI @@ -812,6 +810,6 @@ Lihat juga: [/gateway/configuration](/id/gateway/configuration) untuk contoh kon ## Terkait - [Models](/id/concepts/models) — konfigurasi model dan alias -- [Model Failover](/id/concepts/model-failover) — rantai fallback dan perilaku percobaan ulang -- [Configuration Reference](/id/gateway/configuration-reference#agent-defaults) — kunci konfigurasi model +- [Model Failover](/id/concepts/model-failover) — rantai fallback dan perilaku retry +- [Configuration Reference](/id/gateway/configuration-reference#agent-defaults) — key konfigurasi model - [Providers](/id/providers) — panduan penyiapan per penyedia diff --git a/docs/id/concepts/qa-e2e-automation.md b/docs/id/concepts/qa-e2e-automation.md index 9b541b9e2..29843878c 100644 --- a/docs/id/concepts/qa-e2e-automation.md +++ b/docs/id/concepts/qa-e2e-automation.md @@ -2,36 +2,36 @@ read_when: - Memperluas qa-lab atau qa-channel - Menambahkan skenario QA yang didukung repo - - Membangun otomasi QA dengan realisme lebih tinggi di sekitar Dashboard Gateway -summary: Bentuk otomasi QA privat untuk qa-lab, qa-channel, skenario seeded, dan laporan protokol -title: Otomasi E2E QA + - Membangun otomatisasi QA dengan realisme lebih tinggi di sekitar dasbor Gateway +summary: Bentuk otomatisasi QA privat untuk qa-lab, qa-channel, skenario ber-seed, dan laporan protokol +title: Otomatisasi QA E2E x-i18n: - generated_at: "2026-04-08T06:00:49Z" + generated_at: "2026-04-09T01:27:42Z" model: gpt-5.4 provider: openai - source_hash: 57da147dc06abf9620290104e01a83b42182db1806514114fd9e8467492cda99 + source_hash: c922607d67e0f3a2489ac82bc9f510f7294ced039c1014c15b676d826441d833 source_path: concepts/qa-e2e-automation.md workflow: 15 --- -# Otomasi E2E QA +# Otomatisasi QA E2E -Stack QA privat dimaksudkan untuk menguji OpenClaw dengan cara yang lebih realistis -dan menyerupai channel dibandingkan yang dapat dilakukan oleh satu unit test. +Stack QA privat dimaksudkan untuk menguji OpenClaw dengan cara yang lebih realistis, +berbentuk kanal, dibandingkan yang dapat dicapai oleh satu unit test. Komponen saat ini: -- `extensions/qa-channel`: channel pesan sintetis dengan permukaan DM, channel, thread, - reaksi, edit, dan hapus. +- `extensions/qa-channel`: kanal pesan sintetis dengan permukaan DM, channel, thread, + reaction, edit, dan delete. - `extensions/qa-lab`: UI debugger dan bus QA untuk mengamati transkrip, menyuntikkan pesan masuk, dan mengekspor laporan Markdown. -- `qa/`: aset seed yang didukung repo untuk tugas awal dan skenario QA +- `qa/`: aset seed yang didukung repo untuk tugas kickoff dan skenario QA dasar. Alur operator QA saat ini adalah situs QA dua panel: -- Kiri: Dashboard Gateway (Control UI) dengan agen. -- Kanan: QA Lab, menampilkan transkrip bergaya Slack dan rencana skenario. +- Kiri: dasbor Gateway (Control UI) dengan agen. +- Kanan: QA Lab, yang menampilkan transkrip bergaya Slack dan rencana skenario. Jalankan dengan: @@ -39,9 +39,9 @@ Jalankan dengan: pnpm qa:lab:up ``` -Itu membangun situs QA, memulai lane gateway berbasis Docker, dan mengekspos -halaman QA Lab tempat operator atau loop otomasi dapat memberi agen misi QA, -mengamati perilaku channel nyata, dan mencatat apa yang berhasil, gagal, atau +Perintah itu membangun situs QA, memulai lane gateway berbasis Docker, dan menampilkan +halaman QA Lab tempat operator atau loop otomatisasi dapat memberi agen misi QA, +mengamati perilaku kanal nyata, dan mencatat apa yang berhasil, gagal, atau tetap terblokir. Untuk iterasi UI QA Lab yang lebih cepat tanpa membangun ulang image Docker setiap kali, @@ -54,9 +54,9 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast` menjaga layanan Docker tetap berjalan pada image yang sudah dibangun sebelumnya dan me-bind-mount +`qa:lab:up:fast` menjaga layanan Docker tetap berjalan pada image yang sudah dibangun sebelumnya dan melakukan bind-mount `extensions/qa-lab/web/dist` ke dalam container `qa-lab`. `qa:lab:watch` -membangun ulang bundle tersebut saat ada perubahan, dan browser memuat ulang otomatis ketika hash aset QA Lab berubah. +membangun ulang bundle itu saat ada perubahan, dan browser memuat ulang otomatis saat hash aset QA Lab berubah. ## Seed yang didukung repo @@ -68,19 +68,19 @@ Aset seed berada di `qa/`: Ini sengaja disimpan di git agar rencana QA terlihat oleh manusia maupun agen. Daftar dasar harus tetap cukup luas untuk mencakup: -- obrolan DM dan channel +- chat DM dan channel - perilaku thread - siklus hidup aksi pesan - callback cron -- pemanggilan memori +- recall memori - pergantian model - handoff subagen -- membaca repo dan membaca dokumen +- pembacaan repo dan pembacaan dokumen - satu tugas build kecil seperti Lobster Invaders ## Pelaporan -`qa-lab` mengekspor laporan protokol Markdown dari linimasa bus yang diamati. +`qa-lab` mengekspor laporan protokol Markdown dari timeline bus yang diamati. Laporan tersebut harus menjawab: - Apa yang berhasil @@ -88,6 +88,59 @@ Laporan tersebut harus menjawab: - Apa yang tetap terblokir - Skenario tindak lanjut apa yang layak ditambahkan +Untuk pemeriksaan karakter dan gaya, jalankan skenario yang sama di beberapa ref model live +dan tulis laporan Markdown yang dinilai: + +```bash +pnpm openclaw qa character-eval \ + --model openai/gpt-5.4,thinking=xhigh \ + --model openai/gpt-5.2,thinking=xhigh \ + --model openai/gpt-5,thinking=xhigh \ + --model anthropic/claude-opus-4-6,thinking=high \ + --model anthropic/claude-sonnet-4-6,thinking=high \ + --model zai/glm-5.1,thinking=high \ + --model moonshot/kimi-k2.5,thinking=high \ + --model google/gemini-3.1-pro-preview,thinking=high \ + --judge-model openai/gpt-5.4,thinking=xhigh,fast \ + --judge-model anthropic/claude-opus-4-6,thinking=high \ + --blind-judge-models \ + --concurrency 16 \ + --judge-concurrency 16 +``` + +Perintah ini menjalankan child process gateway QA lokal, bukan Docker. Skenario evaluasi karakter +harus menetapkan persona melalui `SOUL.md`, lalu menjalankan giliran pengguna biasa +seperti chat, bantuan workspace, dan tugas file kecil. Model kandidat +tidak boleh diberi tahu bahwa model tersebut sedang dievaluasi. Perintah ini mempertahankan setiap +transkrip lengkap, mencatat statistik dasar run, lalu meminta model penilai dalam mode cepat dengan +penalaran `xhigh` untuk memberi peringkat pada run berdasarkan kealamian, vibe, dan humor. +Gunakan `--blind-judge-models` saat membandingkan provider: prompt penilai tetap menerima +setiap transkrip dan status run, tetapi ref kandidat diganti dengan label netral +seperti `candidate-01`; laporan memetakan kembali peringkat ke ref sebenarnya setelah +parsing. +Run kandidat secara default menggunakan thinking `high`, dengan `xhigh` untuk model OpenAI yang +mendukungnya. Ganti kandidat tertentu secara inline dengan +`--model provider/model,thinking=`. `--thinking ` tetap menetapkan +fallback global, dan bentuk lama `--model-thinking ` tetap +dipertahankan untuk kompatibilitas. +Ref kandidat OpenAI secara default menggunakan mode cepat agar pemrosesan prioritas dipakai jika +provider mendukungnya. Tambahkan `,fast`, `,no-fast`, atau `,fast=false` secara inline ketika +satu kandidat atau penilai memerlukan override. Berikan `--fast` hanya jika Anda ingin +memaksa mode cepat aktif untuk setiap model kandidat. Durasi kandidat dan penilai +dicatat dalam laporan untuk analisis benchmark, tetapi prompt penilai secara eksplisit menyatakan +agar tidak memberi peringkat berdasarkan kecepatan. +Run model kandidat dan penilai keduanya secara default menggunakan concurrency 16. Turunkan +`--concurrency` atau `--judge-concurrency` ketika batas provider atau tekanan gateway lokal +membuat run terlalu bising. +Saat tidak ada kandidat `--model` yang diberikan, evaluasi karakter secara default menggunakan +`openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`, +`anthropic/claude-sonnet-4-6`, `zai/glm-5.1`, +`moonshot/kimi-k2.5`, dan +`google/gemini-3.1-pro-preview` saat tidak ada `--model` yang diberikan. +Saat tidak ada `--judge-model` yang diberikan, penilai secara default menggunakan +`openai/gpt-5.4,thinking=xhigh,fast` dan +`anthropic/claude-opus-4-6,thinking=high`. + ## Dokumen terkait - [Testing](/id/help/testing) diff --git a/docs/id/gateway/cli-backends.md b/docs/id/gateway/cli-backends.md index 158deebfe..7452db292 100644 --- a/docs/id/gateway/cli-backends.md +++ b/docs/id/gateway/cli-backends.md @@ -1,26 +1,26 @@ --- read_when: - Anda menginginkan fallback yang andal saat penyedia API gagal - - Anda menjalankan Codex CLI atau CLI AI lokal lain dan ingin menggunakannya kembali + - Anda menjalankan Codex CLI atau CLI AI lokal lainnya dan ingin menggunakannya kembali - Anda ingin memahami jembatan loopback MCP untuk akses alat backend CLI summary: 'Backend CLI: fallback CLI AI lokal dengan jembatan alat MCP opsional' title: Backend CLI x-i18n: - generated_at: "2026-04-08T02:14:26Z" + generated_at: "2026-04-09T01:27:54Z" model: gpt-5.4 provider: openai - source_hash: b0e8c41f5f5a8e34466f6b765e5c08585ef1788fa9e9d953257324bcc6cbc414 + source_hash: 9b458f9fe6fa64c47864c8c180f3dedfd35c5647de470a2a4d31c26165663c20 source_path: gateway/cli-backends.md workflow: 15 --- # Backend CLI (runtime fallback) -OpenClaw dapat menjalankan **CLI AI lokal** sebagai **fallback hanya-teks** saat penyedia API sedang down, -terkena pembatasan laju, atau sementara berperilaku tidak semestinya. Ini sengaja dibuat konservatif: +OpenClaw dapat menjalankan **CLI AI lokal** sebagai **fallback hanya-teks** saat penyedia API sedang tidak tersedia, +terkena pembatasan laju, atau untuk sementara berperilaku tidak semestinya. Ini sengaja dibuat konservatif: - **Alat OpenClaw tidak disuntikkan secara langsung**, tetapi backend dengan `bundleMcp: true` - dapat menerima alat gateway melalui jembatan MCP loopback. + dapat menerima alat gateway melalui jembatan loopback MCP. - **Streaming JSONL** untuk CLI yang mendukungnya. - **Sesi didukung** (agar giliran lanjutan tetap koheren). - **Gambar dapat diteruskan** jika CLI menerima path gambar. @@ -28,11 +28,11 @@ terkena pembatasan laju, atau sementara berperilaku tidak semestinya. Ini sengaj Ini dirancang sebagai **jaring pengaman** alih-alih jalur utama. Gunakan ini saat Anda menginginkan respons teks yang “selalu berfungsi” tanpa bergantung pada API eksternal. -Jika Anda menginginkan runtime harness penuh dengan kontrol sesi ACP, tugas latar belakang, +Jika Anda menginginkan runtime harness lengkap dengan kontrol sesi ACP, tugas latar belakang, pengikatan thread/percakapan, dan sesi coding eksternal persisten, gunakan [ACP Agents](/id/tools/acp-agents) sebagai gantinya. Backend CLI bukan ACP. -## Mulai cepat yang ramah pemula +## Memulai cepat yang ramah pemula Anda dapat menggunakan Codex CLI **tanpa konfigurasi apa pun** (plugin OpenAI bawaan mendaftarkan backend default): @@ -42,7 +42,7 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.4 ``` Jika gateway Anda berjalan di bawah launchd/systemd dan PATH minimal, tambahkan hanya -path perintahnya: +path perintah: ```json5 { @@ -58,11 +58,11 @@ path perintahnya: } ``` -Itu saja. Tidak perlu key, tidak perlu konfigurasi auth tambahan selain yang dibutuhkan oleh CLI itu sendiri. +Itu saja. Tidak ada key, tidak ada konfigurasi auth tambahan selain yang dibutuhkan oleh CLI itu sendiri. Jika Anda menggunakan backend CLI bawaan sebagai **penyedia pesan utama** pada -host gateway, OpenClaw sekarang otomatis memuat plugin bawaan pemilik saat konfigurasi Anda -secara eksplisit merujuk backend tersebut dalam model ref atau di bawah +host gateway, OpenClaw kini memuat otomatis plugin bawaan pemiliknya saat konfigurasi Anda +secara eksplisit mereferensikan backend tersebut dalam referensi model atau di bawah `agents.defaults.cliBackends`. ## Menggunakannya sebagai fallback @@ -92,7 +92,7 @@ Catatan: - Jika penyedia utama gagal (auth, pembatasan laju, timeout), OpenClaw akan mencoba backend CLI berikutnya. -## Gambaran umum konfigurasi +## Ringkasan konfigurasi Semua backend CLI berada di bawah: @@ -100,8 +100,8 @@ Semua backend CLI berada di bawah: agents.defaults.cliBackends ``` -Setiap entri diberi key dengan **id penyedia** (misalnya `codex-cli`, `my-cli`). -Id penyedia menjadi sisi kiri dari model ref Anda: +Setiap entri diberi key oleh **id penyedia** (misalnya `codex-cli`, `my-cli`). +Id penyedia menjadi sisi kiri dari referensi model Anda: ``` / @@ -131,6 +131,9 @@ Id penyedia menjadi sisi kiri dari model ref Anda: sessionMode: "existing", sessionIdFields: ["session_id", "conversation_id"], systemPromptArg: "--system", + // CLI bergaya Codex dapat diarahkan ke file prompt sebagai gantinya: + // systemPromptFileConfigArg: "-c", + // systemPromptFileConfigKey: "model_instructions_file", systemPromptWhen: "first", imageArg: "--image", imageMode: "repeat", @@ -145,49 +148,55 @@ Id penyedia menjadi sisi kiri dari model ref Anda: ## Cara kerjanya 1. **Memilih backend** berdasarkan prefiks penyedia (`codex-cli/...`). -2. **Membangun system prompt** menggunakan prompt OpenClaw + konteks workspace yang sama. +2. **Menyusun prompt sistem** menggunakan prompt OpenClaw + konteks workspace yang sama. 3. **Menjalankan CLI** dengan id sesi (jika didukung) agar riwayat tetap konsisten. 4. **Mengurai output** (JSON atau teks biasa) dan mengembalikan teks akhir. 5. **Menyimpan id sesi** per backend, sehingga tindak lanjut menggunakan kembali sesi CLI yang sama. -Backend `claude-cli` Anthropic bawaan sekarang didukung kembali. Staf Anthropic -memberi tahu kami bahwa penggunaan Claude CLI gaya OpenClaw diizinkan kembali, jadi OpenClaw menganggap -penggunaan `claude -p` sebagai penggunaan yang disetujui untuk integrasi ini kecuali Anthropic menerbitkan +Backend `claude-cli` Anthropic bawaan kini didukung lagi. Staf Anthropic +memberi tahu kami bahwa penggunaan Claude CLI bergaya OpenClaw kini diperbolehkan lagi, jadi OpenClaw menganggap +penggunaan `claude -p` disetujui untuk integrasi ini kecuali Anthropic menerbitkan kebijakan baru. +Backend `codex-cli` OpenAI bawaan meneruskan prompt sistem OpenClaw melalui +override konfigurasi `model_instructions_file` Codex (`-c +model_instructions_file="..."`). Codex tidak menyediakan flag +`--append-system-prompt` seperti Claude, jadi OpenClaw menulis prompt yang telah dirakit ke +file sementara untuk setiap sesi Codex CLI baru. + ## Sesi -- Jika CLI mendukung sesi, atur `sessionArg` (misalnya `--session-id`) atau +- Jika CLI mendukung sesi, setel `sessionArg` (misalnya `--session-id`) atau `sessionArgs` (placeholder `{sessionId}`) saat ID perlu disisipkan - ke dalam beberapa flag. -- Jika CLI menggunakan **subperintah resume** dengan flag yang berbeda, atur - `resumeArgs` (menggantikan `args` saat melanjutkan) dan opsional `resumeOutput` + ke beberapa flag. +- Jika CLI menggunakan **subperintah resume** dengan flag yang berbeda, setel + `resumeArgs` (menggantikan `args` saat melanjutkan) dan secara opsional `resumeOutput` (untuk resume non-JSON). - `sessionMode`: - - `always`: selalu kirim id sesi (UUID baru jika belum ada yang tersimpan). + - `always`: selalu kirim id sesi (UUID baru jika tidak ada yang tersimpan). - `existing`: hanya kirim id sesi jika sebelumnya sudah tersimpan. - `none`: jangan pernah kirim id sesi. Catatan serialisasi: -- `serialize: true` menjaga urutan eksekusi pada lane yang sama. +- `serialize: true` menjaga eksekusi pada lane yang sama tetap berurutan. - Sebagian besar CLI melakukan serialisasi pada satu lane penyedia. -- OpenClaw membuang penggunaan ulang sesi CLI yang tersimpan ketika status auth backend berubah, termasuk login ulang, rotasi token, atau kredensial profil auth yang berubah. +- OpenClaw membuang penggunaan ulang sesi CLI yang tersimpan saat status auth backend berubah, termasuk login ulang, rotasi token, atau perubahan kredensial profil auth. ## Gambar (pass-through) -Jika CLI Anda menerima path gambar, atur `imageArg`: +Jika CLI Anda menerima path gambar, setel `imageArg`: ```json5 imageArg: "--image", imageMode: "repeat" ``` -OpenClaw akan menulis gambar base64 ke file sementara. Jika `imageArg` diatur, path tersebut -diteruskan sebagai argumen CLI. Jika `imageArg` tidak ada, OpenClaw menambahkan -path file ke prompt (injeksi path), yang cukup untuk CLI yang otomatis +OpenClaw akan menulis gambar base64 ke file sementara. Jika `imageArg` disetel, path tersebut +diteruskan sebagai arg CLI. Jika `imageArg` tidak ada, OpenClaw menambahkan +path file ke prompt (penyuntikan path), yang cukup untuk CLI yang otomatis memuat file lokal dari path biasa. ## Input / output @@ -195,15 +204,15 @@ memuat file lokal dari path biasa. - `output: "json"` (default) mencoba mengurai JSON dan mengekstrak teks + id sesi. - Untuk output JSON Gemini CLI, OpenClaw membaca teks balasan dari `response` dan penggunaan dari `stats` saat `usage` tidak ada atau kosong. -- `output: "jsonl"` mengurai stream JSONL (misalnya Codex CLI `--json`) dan mengekstrak pesan agen akhir serta pengenal sesi - saat tersedia. +- `output: "jsonl"` mengurai stream JSONL (misalnya Codex CLI `--json`) dan mengekstrak pesan agen akhir serta + pengenal sesi jika ada. - `output: "text"` memperlakukan stdout sebagai respons akhir. Mode input: -- `input: "arg"` (default) meneruskan prompt sebagai argumen CLI terakhir. +- `input: "arg"` (default) meneruskan prompt sebagai arg CLI terakhir. - `input: "stdin"` mengirim prompt melalui stdin. -- Jika prompt sangat panjang dan `maxPromptArgChars` diatur, stdin digunakan. +- Jika prompt sangat panjang dan `maxPromptArgChars` disetel, stdin digunakan. ## Default (dimiliki plugin) @@ -237,26 +246,26 @@ Catatan JSON Gemini CLI: - Teks balasan dibaca dari field JSON `response`. - Penggunaan mengambil fallback ke `stats` saat `usage` tidak ada atau kosong. -- `stats.cached` dinormalisasi menjadi OpenClaw `cacheRead`. +- `stats.cached` dinormalisasi menjadi `cacheRead` OpenClaw. - Jika `stats.input` tidak ada, OpenClaw menurunkan token input dari `stats.input_tokens - stats.cached`. Override hanya jika diperlukan (umumnya: path `command` absolut). -## Default milik plugin +## Default yang dimiliki plugin -Default backend CLI sekarang merupakan bagian dari permukaan plugin: +Default backend CLI kini menjadi bagian dari surface plugin: - Plugin mendaftarkannya dengan `api.registerCliBackend(...)`. -- `id` backend menjadi prefiks penyedia dalam model ref. -- Konfigurasi pengguna di `agents.defaults.cliBackends.` tetap meng-override default plugin. +- `id` backend menjadi prefiks penyedia dalam referensi model. +- Konfigurasi pengguna di `agents.defaults.cliBackends.` tetap menimpa default plugin. - Pembersihan konfigurasi khusus backend tetap dimiliki plugin melalui hook `normalizeConfig` opsional. ## Overlay bundle MCP Backend CLI **tidak** menerima panggilan alat OpenClaw secara langsung, tetapi backend dapat -memilih untuk menggunakan overlay konfigurasi MCP yang dihasilkan dengan `bundleMcp: true`. +memilih ikut serta dalam overlay konfigurasi MCP yang dihasilkan dengan `bundleMcp: true`. Perilaku bawaan saat ini: @@ -266,32 +275,32 @@ Perilaku bawaan saat ini: Saat bundle MCP diaktifkan, OpenClaw: -- memunculkan server MCP HTTP loopback yang mengekspos alat gateway ke proses CLI +- memunculkan server HTTP MCP loopback yang mengekspos alat gateway ke proses CLI - mengautentikasi jembatan dengan token per sesi (`OPENCLAW_MCP_TOKEN`) - membatasi akses alat ke sesi, akun, dan konteks channel saat ini - memuat server bundle-MCP yang diaktifkan untuk workspace saat ini - menggabungkannya dengan bentuk konfigurasi/pengaturan MCP backend yang sudah ada -- menulis ulang konfigurasi peluncuran menggunakan mode integrasi milik backend dari ekstensi pemilik +- menulis ulang konfigurasi peluncuran menggunakan mode integrasi milik backend dari extension pemiliknya -Jika tidak ada server MCP yang diaktifkan, OpenClaw tetap menyuntikkan konfigurasi ketat saat sebuah -backend memilih bundle MCP agar eksekusi latar belakang tetap terisolasi. +Jika tidak ada server MCP yang diaktifkan, OpenClaw tetap menyuntikkan konfigurasi ketat saat +backend memilih ikut serta dalam bundle MCP agar eksekusi latar belakang tetap terisolasi. -## Batasan +## Keterbatasan -- **Tidak ada panggilan alat OpenClaw langsung.** OpenClaw tidak menyuntikkan panggilan alat ke dalam - protokol backend CLI. Backend hanya melihat alat gateway saat mereka memilih +- **Tidak ada panggilan alat OpenClaw langsung.** OpenClaw tidak menyuntikkan panggilan alat ke + protokol backend CLI. Backend hanya melihat alat gateway saat mereka memilih ikut serta pada `bundleMcp: true`. -- **Streaming bersifat khusus backend.** Beberapa backend melakukan stream JSONL; yang lain menahan output - sampai proses selesai. +- **Streaming bersifat khusus backend.** Beberapa backend melakukan streaming JSONL; yang lain menahan buffer + hingga keluar. - **Output terstruktur** bergantung pada format JSON CLI. -- **Sesi Codex CLI** melanjutkan melalui output teks (tanpa JSONL), yang kurang +- **Sesi Codex CLI** dilanjutkan melalui output teks (tanpa JSONL), yang kurang terstruktur dibandingkan eksekusi awal `--json`. Sesi OpenClaw tetap berfungsi - secara normal. + normal. ## Pemecahan masalah -- **CLI tidak ditemukan**: atur `command` ke path lengkap. +- **CLI tidak ditemukan**: setel `command` ke path lengkap. - **Nama model salah**: gunakan `modelAliases` untuk memetakan `provider/model` → model CLI. -- **Tidak ada kontinuitas sesi**: pastikan `sessionArg` diatur dan `sessionMode` bukan +- **Tidak ada kontinuitas sesi**: pastikan `sessionArg` disetel dan `sessionMode` bukan `none` (Codex CLI saat ini tidak dapat melanjutkan dengan output JSON). -- **Gambar diabaikan**: atur `imageArg` (dan verifikasi bahwa CLI mendukung path file). +- **Gambar diabaikan**: setel `imageArg` (dan pastikan CLI mendukung path file). diff --git a/docs/id/gateway/configuration-reference.md b/docs/id/gateway/configuration-reference.md index 4f05af9fd..8f44dc179 100644 --- a/docs/id/gateway/configuration-reference.md +++ b/docs/id/gateway/configuration-reference.md @@ -1,37 +1,37 @@ --- read_when: - - Anda memerlukan semantik atau nilai default konfigurasi yang tepat pada tingkat field + - Anda memerlukan semantik konfigurasi tingkat field atau nilai default yang tepat - Anda sedang memvalidasi blok konfigurasi channel, model, gateway, atau tool summary: Referensi konfigurasi Gateway untuk kunci inti OpenClaw, nilai default, dan tautan ke referensi subsistem khusus title: Referensi Konfigurasi x-i18n: - generated_at: "2026-04-08T09:18:00Z" + generated_at: "2026-04-09T01:32:38Z" model: gpt-5.4 provider: openai - source_hash: fd5f69050455e610fc7c825d95f546a16aa867b8a9c0d692a48de36419b0afc2 + source_hash: a9d6d0c542b9874809491978fdcf8e1a7bb35a4873db56aa797963d03af4453c source_path: gateway/configuration-reference.md workflow: 15 --- # Referensi Konfigurasi -Referensi konfigurasi inti untuk `~/.openclaw/openclaw.json`. Untuk gambaran umum berbasis tugas, lihat [Configuration](/id/gateway/configuration). +Referensi konfigurasi inti untuk `~/.openclaw/openclaw.json`. Untuk ringkasan berbasis tugas, lihat [Configuration](/id/gateway/configuration). -Halaman ini mencakup permukaan konfigurasi utama OpenClaw dan menautkan ke luar saat sebuah subsistem memiliki referensi lebih mendalamnya sendiri. Halaman ini **tidak** mencoba menyisipkan setiap katalog perintah milik channel/plugin atau setiap knob memori/QMD mendalam ke dalam satu halaman. +Halaman ini mencakup permukaan konfigurasi utama OpenClaw dan menautkan ke referensi lain ketika suatu subsistem memiliki referensi lebih mendalam sendiri. Halaman ini **tidak** berupaya menyisipkan setiap katalog perintah milik channel/plugin atau setiap knob memori/QMD mendalam dalam satu halaman. Sumber kebenaran kode: -- `openclaw config schema` mencetak JSON Schema langsung yang digunakan untuk validasi dan Control UI, dengan metadata bundled/plugin/channel digabungkan saat tersedia -- `config.schema.lookup` mengembalikan satu node skema yang dicakup jalur untuk tool penelusuran mendalam -- `pnpm config:docs:check` / `pnpm config:docs:gen` memvalidasi hash baseline dokumen konfigurasi terhadap permukaan skema saat ini +- `openclaw config schema` mencetak JSON Schema live yang digunakan untuk validasi dan UI Kontrol, dengan metadata bundled/plugin/channel digabungkan saat tersedia +- `config.schema.lookup` mengembalikan satu node schema yang dibatasi path untuk tool penelusuran detail +- `pnpm config:docs:check` / `pnpm config:docs:gen` memvalidasi hash baseline dokumen konfigurasi terhadap permukaan schema saat ini Referensi mendalam khusus: - [Referensi konfigurasi memori](/id/reference/memory-config) untuk `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations`, dan konfigurasi dreaming di bawah `plugins.entries.memory-core.config.dreaming` - [Slash Commands](/id/tools/slash-commands) untuk katalog perintah built-in + bundled saat ini -- halaman channel/plugin pemilik untuk permukaan perintah khusus channel +- halaman channel/plugin pemilik untuk permukaan perintah spesifik channel -Format konfigurasi adalah **JSON5** (komentar + koma di akhir diperbolehkan). Semua field bersifat opsional — OpenClaw menggunakan nilai default aman saat dihilangkan. +Format konfigurasi adalah **JSON5** (komentar + trailing comma diperbolehkan). Semua field bersifat opsional — OpenClaw menggunakan default aman saat dihilangkan. --- @@ -43,28 +43,28 @@ Setiap channel dimulai secara otomatis saat bagian konfigurasinya ada (kecuali ` Semua channel mendukung kebijakan DM dan kebijakan grup: -| Kebijakan DM | Perilaku | -| ------------------- | ------------------------------------------------------------ | +| Kebijakan DM | Perilaku | +| ------------------- | ------------------------------------------------------------- | | `pairing` (default) | Pengirim tidak dikenal mendapat kode pairing sekali pakai; pemilik harus menyetujui | -| `allowlist` | Hanya pengirim di `allowFrom` (atau penyimpanan izin pairing) | -| `open` | Izinkan semua DM masuk (memerlukan `allowFrom: ["*"]`) | -| `disabled` | Abaikan semua DM masuk | +| `allowlist` | Hanya pengirim di `allowFrom` (atau paired allow store) | +| `open` | Izinkan semua DM masuk (memerlukan `allowFrom: ["*"]`) | +| `disabled` | Abaikan semua DM masuk | -| Kebijakan grup | Perilaku | -| --------------------- | ----------------------------------------------------- | -| `allowlist` (default) | Hanya grup yang cocok dengan allowlist yang dikonfigurasi | -| `open` | Lewati allowlist grup (gating mention tetap berlaku) | +| Kebijakan grup | Perilaku | +| --------------------- | ---------------------------------------------------- | +| `allowlist` (default) | Hanya grup yang cocok dengan allowlist terkonfigurasi | +| `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. -Kode pairing kedaluwarsa setelah 1 jam. Permintaan pairing DM yang tertunda dibatasi **3 per channel**. -Jika sebuah blok provider tidak ada sama sekali (`channels.` tidak ada), kebijakan grup runtime kembali ke `allowlist` (gagal-tertutup) dengan peringatan saat startup. +`channels.defaults.groupPolicy` menetapkan default saat `groupPolicy` suatu provider tidak disetel. +Kode pairing kedaluwarsa setelah 1 jam. Permintaan pairing DM yang tertunda dibatasi hingga **3 per channel**. +Jika blok provider tidak ada sama sekali (`channels.` tidak ada), kebijakan grup runtime fallback ke `allowlist` (fail-closed) dengan peringatan saat startup. ### Override model channel -Gunakan `channels.modelByChannel` untuk menetapkan ID channel tertentu ke sebuah model. Nilai menerima `provider/model` atau alias model yang dikonfigurasi. Pemetaan channel diterapkan saat sebuah sesi belum memiliki override model (misalnya, disetel melalui `/model`). +Gunakan `channels.modelByChannel` untuk menetapkan ID channel tertentu ke model tertentu. Nilai menerima `provider/model` atau alias model yang dikonfigurasi. Pemetaan channel diterapkan saat sesi belum memiliki override model (misalnya, disetel melalui `/model`). ```json5 { @@ -87,7 +87,7 @@ Gunakan `channels.modelByChannel` untuk menetapkan ID channel tertentu ke sebuah ### Default channel dan heartbeat -Gunakan `channels.defaults` untuk perilaku kebijakan grup dan heartbeat bersama di semua provider: +Gunakan `channels.defaults` untuk perilaku group-policy dan heartbeat bersama di seluruh provider: ```json5 { @@ -106,14 +106,14 @@ 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 dalam allowlist), `allowlist_quote` (sama seperti allowlist tetapi pertahankan konteks kutip/balas yang eksplisit). Override per-channel: `channels..contextVisibility`. +- `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 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 yang sehat dalam output heartbeat. -- `channels.defaults.heartbeat.showAlerts`: sertakan status yang menurun/error dalam output heartbeat. -- `channels.defaults.heartbeat.useIndicator`: tampilkan output heartbeat bergaya indikator ringkas. +- `channels.defaults.heartbeat.showAlerts`: sertakan status degraded/error dalam output heartbeat. +- `channels.defaults.heartbeat.useIndicator`: render output heartbeat bergaya indikator yang ringkas. ### WhatsApp -WhatsApp berjalan melalui channel web gateway (Baileys Web). Ini dimulai secara otomatis saat ada sesi tertaut. +WhatsApp berjalan melalui channel web gateway (Baileys Web). Channel ini dimulai secara otomatis saat sesi tertaut ada. ```json5 { @@ -164,9 +164,9 @@ WhatsApp berjalan melalui channel web gateway (Baileys Web). Ini dimulai secara } ``` -- Perintah outbound secara default memakai akun `default` jika ada; jika tidak, ID akun pertama yang dikonfigurasi (diurutkan). -- `channels.whatsapp.defaultAccount` opsional menggantikan fallback pemilihan akun default itu saat cocok dengan ID akun yang dikonfigurasi. -- Direktori auth Baileys satu akun lama dimigrasikan oleh `openclaw doctor` ke `whatsapp/default`. +- Perintah outbound default ke akun `default` jika ada; jika tidak, ke id akun terkonfigurasi pertama (diurutkan). +- `channels.whatsapp.defaultAccount` opsional menggantikan fallback pemilihan akun default itu bila cocok dengan id akun yang dikonfigurasi. +- Direktori auth Baileys single-account lama dimigrasikan oleh `openclaw doctor` ke `whatsapp/default`. - Override per-akun: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -225,11 +225,11 @@ WhatsApp berjalan melalui channel web gateway (Baileys Web). Ini dimulai secara } ``` -- Token bot: `channels.telegram.botToken` atau `channels.telegram.tokenFile` (hanya file reguler; symlink ditolak), dengan `TELEGRAM_BOT_TOKEN` sebagai fallback untuk akun default. -- `channels.telegram.defaultAccount` opsional menggantikan 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 fallback routing; `openclaw doctor` memperingatkan bila ini hilang atau tidak valid. +- 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 menggantikan pemilihan akun default bila cocok dengan id akun yang dikonfigurasi. +- Dalam setup multi-akun (2+ id akun), set default eksplisit (`channels.telegram.defaultAccount` atau `channels.telegram.accounts.default`) untuk menghindari routing fallback; `openclaw doctor` memberi peringatan bila ini hilang atau tidak valid. - `configWrites: false` memblokir penulisan konfigurasi 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). +- Entri `bindings[]` level 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). @@ -297,7 +297,7 @@ WhatsApp berjalan melalui channel web gateway (Baileys Web). Ini dimulai secara enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // opt-in untuk sessions_spawn({ thread: true }) + spawnSubagentSessions: false, // opt-in for sessions_spawn({ thread: true }) }, voice: { enabled: true, @@ -334,33 +334,33 @@ WhatsApp berjalan melalui channel web gateway (Baileys Web). Ini dimulai secara ``` - Token: `channels.discord.token`, dengan `DISCORD_BOT_TOKEN` sebagai fallback untuk akun default. -- Panggilan outbound langsung yang memberikan `token` Discord eksplisit memakai token itu untuk panggilan; pengaturan retry/kebijakan akun tetap berasal dari akun yang dipilih dalam snapshot runtime aktif. -- `channels.discord.defaultAccount` opsional menggantikan pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi. +- Panggilan outbound langsung yang menyediakan `token` Discord eksplisit menggunakan token itu untuk panggilan; pengaturan retry/kebijakan akun tetap berasal dari akun terpilih dalam snapshot runtime aktif. +- `channels.discord.defaultAccount` opsional menggantikan pemilihan akun default bila cocok dengan id akun yang dikonfigurasi. - Gunakan `user:` (DM) atau `channel:` (channel guild) untuk target pengiriman; ID numerik polos ditolak. -- Slug guild berupa huruf kecil dengan spasi diganti `-`; kunci channel memakai nama yang sudah di-slug (tanpa `#`). Gunakan 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 disaring). -- `channels.discord.guilds..ignoreOtherMentions` (dan override channel) menjatuhkan pesan yang menyebut pengguna atau role lain tetapi bukan bot (tidak termasuk @everyone/@here). -- `maxLinesPerMessage` (default 17) memecah pesan tinggi meski di bawah 2000 karakter. -- `channels.discord.threadBindings` mengontrol routing terikat thread Discord: +- Slug guild huruf kecil dengan spasi diganti `-`; kunci channel menggunakan nama yang sudah di-slug (tanpa `#`). Sebaiknya gunakan 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 peran lain tetapi tidak menyebut bot (tidak termasuk @everyone/@here). +- `maxLinesPerMessage` (default 17) membagi pesan tinggi bahkan saat 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) + - `idleHours`: override Discord untuk auto-unfocus karena inaktivitas dalam jam (`0` menonaktifkan) - `maxAgeHours`: override Discord untuk usia maksimum keras dalam jam (`0` menonaktifkan) - `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 container komponen Discord v2. +- Entri `bindings[]` level 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 komponen Discord 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` (`true` dan `24` secara default). -- OpenClaw juga mencoba pemulihan penerimaan suara dengan keluar/masuk kembali ke sesi suara setelah kegagalan dekripsi berulang. +- OpenClaw juga mencoba pemulihan penerimaan suara dengan keluar/bergabung ulang 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 (sehat => online, menurun => idle, habis => dnd) dan mengizinkan override teks status opsional. -- `channels.discord.dangerouslyAllowNameMatching` mengaktifkan kembali pencocokan nama/tag yang dapat berubah (mode kompatibilitas darurat). -- `channels.discord.execApprovals`: pengiriman approval exec native Discord dan otorisasi approver. - - `enabled`: `true`, `false`, atau `"auto"` (default). Dalam mode auto, approval exec aktif saat approver dapat di-resolve dari `approvers` atau `commands.ownerAllowFrom`. - - `approvers`: ID pengguna Discord yang diizinkan menyetujui permintaan exec. Menggunakan fallback ke `commands.ownerAllowFrom` jika dihilangkan. - - `agentFilter`: allowlist ID agen opsional. Hilangkan untuk meneruskan approval untuk semua agen. +- `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 penyetuju. + - `enabled`: `true`, `false`, atau `"auto"` (default). Dalam mode auto, persetujuan exec aktif saat penyetuju dapat di-resolve dari `approvers` atau `commands.ownerAllowFrom`. + - `approvers`: ID pengguna Discord yang diizinkan menyetujui permintaan exec. Fallback ke `commands.ownerAllowFrom` bila dihilangkan. + - `agentFilter`: allowlist ID agen opsional. Hilangkan untuk meneruskan persetujuan untuk semua agen. - `sessionFilter`: pola kunci sesi opsional (substring atau regex). - - `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 dapat digunakan oleh approver yang berhasil di-resolve. - - `cleanupAfterResolve`: saat `true`, menghapus DM approval setelah disetujui, ditolak, atau timeout. + - `target`: tempat mengirim prompt persetujuan. `"dm"` (default) mengirim ke DM penyetuju, `"channel"` mengirim ke channel asal, `"both"` mengirim ke keduanya. Saat target mencakup `"channel"`, tombol hanya dapat digunakan oleh penyetuju yang berhasil di-resolve. + - `cleanupAfterResolve`: saat `true`, menghapus DM persetujuan setelah disetujui, ditolak, atau timeout. **Mode notifikasi reaksi:** `off` (tidak ada), `own` (pesan bot, default), `all` (semua pesan), `allowlist` (dari `guilds..users` pada semua pesan). @@ -397,7 +397,7 @@ WhatsApp berjalan melalui channel web gateway (Baileys Web). Ini dimulai secara - SecretRef service account juga didukung (`serviceAccountRef`). - Fallback env: `GOOGLE_CHAT_SERVICE_ACCOUNT` atau `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. - Gunakan `spaces/` atau `users/` untuk target pengiriman. -- `channels.googlechat.dangerouslyAllowNameMatching` mengaktifkan kembali pencocokan principal email yang dapat berubah (mode kompatibilitas darurat). +- `channels.googlechat.dangerouslyAllowNameMatching` mengaktifkan kembali pencocokan email principal yang dapat berubah (mode kompatibilitas break-glass). ### Slack @@ -449,7 +449,7 @@ WhatsApp berjalan melalui channel web gateway (Baileys Web). Ini dimulai secara chunkMode: "length", streaming: { mode: "partial", // off | partial | block | progress - nativeTransport: true, // gunakan API streaming native Slack saat mode=partial + nativeTransport: true, // use Slack native streaming API when mode=partial }, mediaMaxMb: 20, execApprovals: { @@ -466,33 +466,33 @@ WhatsApp berjalan melalui channel web gateway (Baileys Web). Ini dimulai secara - **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-akun). -- `botToken`, `appToken`, `signingSecret`, dan `userToken` menerima string plaintext - atau objek SecretRef. -- Snapshot akun Slack mengekspos field sumber/status per-kredensial seperti +- `botToken`, `appToken`, `signingSecret`, dan `userToken` menerima string + plaintext atau objek SecretRef. +- Snapshot akun Slack menampilkan field sumber/status per-kredensial seperti `botTokenSource`, `botTokenStatus`, `appTokenStatus`, dan, dalam mode HTTP, `signingSecretStatus`. `configured_unavailable` berarti akun - dikonfigurasi melalui SecretRef tetapi jalur perintah/runtime saat ini tidak dapat - me-resolve nilai rahasia. + dikonfigurasi melalui SecretRef tetapi path perintah/runtime saat ini tidak dapat + me-resolve nilai secret. - `configWrites: false` memblokir penulisan konfigurasi yang dipicu Slack. -- `channels.slack.defaultAccount` opsional menggantikan pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi. +- `channels.slack.defaultAccount` opsional menggantikan pemilihan akun default bila cocok dengan id akun yang dikonfigurasi. - `channels.slack.streaming.mode` adalah kunci mode stream Slack kanonis. `channels.slack.streaming.nativeTransport` mengontrol transport streaming native Slack. Nilai lama `streamMode`, boolean `streaming`, dan `nativeStreaming` dimigrasikan otomatis. - Gunakan `user:` (DM) atau `channel:` untuk target pengiriman. **Mode notifikasi reaksi:** `off`, `own` (default), `all`, `allowlist` (dari `reactionAllowlist`). -**Isolasi sesi thread:** `thread.historyScope` adalah per-thread (default) atau dibagi di seluruh channel. `thread.inheritParent` menyalin transkrip channel induk ke thread baru. +**Isolasi sesi thread:** `thread.historyScope` bersifat per-thread (default) atau dibagikan di seluruh channel. `thread.inheritParent` menyalin transkrip channel induk ke thread baru. -- Streaming native Slack plus status thread gaya asisten Slack "is typing..." memerlukan target thread balasan. DM tingkat atas tetap di luar thread secara default, jadi mereka menggunakan `typingReaction` atau pengiriman normal alih-alih pratinjau bergaya thread. +- Streaming native Slack plus status thread gaya asisten Slack "is typing..." memerlukan target thread balasan. DM tingkat atas secara default tetap di luar thread, sehingga mereka menggunakan `typingReaction` atau pengiriman normal alih-alih pratinjau gaya thread. - `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 approval exec native Slack dan otorisasi approver. Skema yang sama seperti Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ID pengguna Slack), `agentFilter`, `sessionFilter`, dan `target` (`"dm"`, `"channel"`, atau `"both"`). +- `channels.slack.execApprovals`: pengiriman persetujuan exec native Slack dan otorisasi penyetuju. Schema 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 | Sematkan/lepas/daftar | -| memberInfo | enabled | Info anggota | -| emojiList | enabled | Daftar emoji kustom | +| Grup aksi | Default | Catatan | +| ------------ | ------- | ---------------------- | +| reactions | enabled | React + daftar reaksi | +| messages | enabled | Baca/kirim/edit/hapus | +| pins | enabled | Sematkan/lepas/list | +| memberInfo | enabled | Info anggota | +| emojiList | enabled | Daftar emoji kustom | ### Mattermost @@ -516,7 +516,7 @@ Mattermost dikirim sebagai plugin: `openclaw plugins install @openclaw/mattermos native: true, // opt-in nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // URL eksplisit opsional untuk deployment reverse-proxy/publik + // Optional explicit URL for reverse-proxy/public deployments callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -526,23 +526,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 pada @-mention, default), `onmessage` (setiap pesan), `onchar` (pesan yang diawali 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.callbackPath` harus berupa path (misalnya `/api/channels/mattermost/command`), bukan URL penuh. +- `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 registrasi slash command. Jika registrasi gagal atau tidak ada + 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` untuk mencakup host/domain callback. - Gunakan nilai host/domain, bukan URL lengkap. +- Untuk host callback private/tailnet/internal, Mattermost mungkin memerlukan + `ServiceSettings.AllowedUntrustedInternalConnections` agar mencakup host/domain callback. + Gunakan nilai host/domain, bukan URL penuh. - `channels.mattermost.configWrites`: izinkan atau tolak penulisan konfigurasi 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 menggantikan pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi. +- `channels.mattermost.requireMention`: mewajibkan `@mention` sebelum membalas di channel. +- `channels.mattermost.groups..requireMention`: override mention-gating per-channel (`"*"` untuk default). +- `channels.mattermost.defaultAccount` opsional menggantikan pemilihan akun default bila cocok dengan id akun yang dikonfigurasi. ### Signal @@ -551,7 +551,7 @@ Saat perintah native Mattermost diaktifkan: channels: { signal: { enabled: true, - account: "+15555550123", // binding akun opsional + account: "+15555550123", // optional account binding dmPolicy: "pairing", allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"], configWrites: true, @@ -567,7 +567,7 @@ Saat perintah native Mattermost diaktifkan: - `channels.signal.account`: sematkan startup channel ke identitas akun Signal tertentu. - `channels.signal.configWrites`: izinkan atau tolak penulisan konfigurasi yang dipicu Signal. -- `channels.signal.defaultAccount` opsional menggantikan pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi. +- `channels.signal.defaultAccount` opsional menggantikan pemilihan akun default bila cocok dengan id akun yang dikonfigurasi. ### BlueBubbles @@ -579,16 +579,16 @@ BlueBubbles adalah jalur iMessage yang direkomendasikan (didukung plugin, dikonf bluebubbles: { enabled: true, dmPolicy: "pairing", - // serverUrl, password, webhookPath, kontrol grup, dan action lanjutan: - // lihat /channels/bluebubbles + // serverUrl, password, webhookPath, group controls, and advanced actions: + // see /channels/bluebubbles }, }, } ``` -- Jalur kunci inti yang dicakup di sini: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. -- `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). +- Path kunci inti yang dibahas di sini: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. +- `channels.bluebubbles.defaultAccount` opsional menggantikan pemilihan akun default bila cocok dengan id akun yang dikonfigurasi. +- Entri `bindings[]` level atas dengan `type: "acp"` dapat mengikat percakapan BlueBubbles ke sesi ACP persisten. Gunakan string handle atau 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 channel BlueBubbles lengkap didokumentasikan di [BlueBubbles](/id/channels/bluebubbles). ### iMessage @@ -617,17 +617,17 @@ OpenClaw menjalankan `imsg rpc` (JSON-RPC melalui stdio). Tidak memerlukan daemo } ``` -- `channels.imessage.defaultAccount` opsional menggantikan pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi. +- `channels.imessage.defaultAccount` opsional menggantikan pemilihan akun default bila cocok dengan id akun yang dikonfigurasi. - Memerlukan Full Disk Access ke DB Messages. -- 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. +- Sebaiknya gunakan target `chat_id:`. Gunakan `imsg chats --limit 20` untuk mencantumkan chat. +- `cliPath` dapat menunjuk ke pembungkus SSH; set `remoteHost` (`host` atau `user@host`) untuk pengambilan lampiran via SCP. - `attachmentRoots` dan `remoteAttachmentRoots` membatasi path lampiran masuk (default: `/Users/*/Library/Messages/Attachments`). -- SCP menggunakan pemeriksaan host-key yang ketat, jadi pastikan host key relay sudah ada di `~/.ssh/known_hosts`. +- 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 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). +- Entri `bindings[]` level 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). - + ```bash #!/usr/bin/env bash @@ -669,19 +669,19 @@ Matrix didukung extension 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 meng-override-nya dengan `channels.matrix.accounts..proxy`. -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` mengizinkan homeserver privat/internal. `proxy` dan opt-in jaringan ini adalah kontrol yang independen. -- `channels.matrix.defaultAccount` memilih akun yang diutamakan dalam pengaturan multi-akun. -- `channels.matrix.autoJoin` default ke `off`, jadi room undangan dan undangan gaya DM baru diabaikan sampai Anda menyetel `autoJoin: "allowlist"` dengan `autoJoinAllowlist` atau `autoJoin: "always"`. -- `channels.matrix.execApprovals`: pengiriman approval exec native Matrix dan otorisasi approver. - - `enabled`: `true`, `false`, atau `"auto"` (default). Dalam mode auto, approval exec aktif saat approver dapat di-resolve dari `approvers` atau `commands.ownerAllowFrom`. - - `approvers`: ID pengguna Matrix (misalnya `@owner:example.org`) yang diizinkan menyetujui permintaan exec. - - `agentFilter`: allowlist ID agen opsional. Hilangkan untuk meneruskan approval untuk semua agen. +- `channels.matrix.proxy` merutekan trafik HTTP Matrix melalui proxy HTTP(S) eksplisit. Akun bernama dapat meng-override dengan `channels.matrix.accounts..proxy`. +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` mengizinkan homeserver private/internal. `proxy` dan opt-in jaringan ini adalah kontrol independen. +- `channels.matrix.defaultAccount` memilih akun yang disukai dalam setup multi-akun. +- `channels.matrix.autoJoin` default ke `off`, jadi room undangan dan undangan bergaya DM baru diabaikan sampai Anda menyetel `autoJoin: "allowlist"` dengan `autoJoinAllowlist` atau `autoJoin: "always"`. +- `channels.matrix.execApprovals`: pengiriman persetujuan exec native Matrix dan otorisasi penyetuju. + - `enabled`: `true`, `false`, atau `"auto"` (default). Dalam mode auto, persetujuan exec aktif saat penyetuju 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 untuk semua agen. - `sessionFilter`: pola kunci sesi opsional (substring atau regex). - - `target`: tempat mengirim prompt approval. `"dm"` (default), `"channel"` (room asal), atau `"both"`. + - `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) dibagi berdasarkan peer yang dirutekan, sedangkan `per-room` mengisolasi setiap room DM. -- Probe status Matrix dan lookup direktori langsung menggunakan kebijakan proxy yang sama seperti lalu lintas runtime. +- `channels.matrix.dm.sessionScope` mengontrol bagaimana DM Matrix dikelompokkan ke dalam sesi: `per-user` (default) berbagi berdasarkan peer yang dirutekan, sedangkan `per-room` mengisolasi tiap room DM. +- Probe status Matrix dan pencarian direktori live menggunakan kebijakan proxy yang sama seperti trafik runtime. - Konfigurasi Matrix lengkap, aturan penargetan, dan contoh setup didokumentasikan di [Matrix](/id/channels/matrix). ### Microsoft Teams @@ -694,14 +694,14 @@ Microsoft Teams didukung extension dan dikonfigurasi di bawah `channels.msteams` msteams: { enabled: true, configWrites: true, - // appId, appPassword, tenantId, webhook, kebijakan team/channel: - // lihat /channels/msteams + // appId, appPassword, tenantId, webhook, team/channel policies: + // see /channels/msteams }, }, } ``` -- Jalur kunci inti yang dicakup di sini: `channels.msteams`, `channels.msteams.configWrites`. +- Path kunci inti yang dibahas di sini: `channels.msteams`, `channels.msteams.configWrites`. - Konfigurasi Teams lengkap (kredensial, webhook, kebijakan DM/grup, override per-team/per-channel) didokumentasikan di [Microsoft Teams](/id/channels/msteams). ### IRC @@ -727,9 +727,9 @@ IRC didukung extension 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 menggantikan 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). +- Path kunci inti yang dibahas di sini: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. +- `channels.irc.defaultAccount` opsional menggantikan pemilihan akun default bila 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) @@ -757,25 +757,25 @@ 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 di-override 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 berada pada konfigurasi channel tingkat atas satu akun, OpenClaw terlebih dahulu mempromosikan nilai satu akun tingkat atas yang dicakup akun ke dalam map akun channel agar akun asli tetap berfungsi. Sebagian besar channel memindahkannya ke `channels..accounts.default`; Matrix dapat mempertahankan target bernama/default yang sudah cocok. -- Binding channel-only yang sudah ada (tanpa `accountId`) tetap cocok dengan akun default; binding yang dicakup akun tetap opsional. -- `openclaw doctor --fix` juga memperbaiki bentuk campuran dengan memindahkan nilai satu akun tingkat atas yang dicakup akun ke akun yang dipromosikan yang dipilih untuk channel itu. Sebagian besar channel menggunakan `accounts.default`; Matrix dapat mempertahankan target bernama/default yang sudah cocok. +- Gunakan `bindings[].match.accountId` untuk merutekan setiap akun ke agen berbeda. +- Jika Anda menambahkan akun non-default melalui `openclaw channels add` (atau onboarding channel) saat masih menggunakan konfigurasi channel top-level single-account, OpenClaw terlebih dahulu mempromosikan nilai single-account top-level 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 yang sudah ada. +- Binding channel-only yang ada (tanpa `accountId`) tetap cocok dengan akun default; binding account-scoped tetap opsional. +- `openclaw doctor --fix` juga memperbaiki shape campuran dengan memindahkan nilai single-account top-level yang bersifat account-scoped ke akun yang dipromosikan yang dipilih untuk channel tersebut. Sebagian besar channel menggunakan `accounts.default`; Matrix dapat mempertahankan target bernama/default yang cocok yang sudah ada. -### Channel extension lainnya +### Channel extension lain -Banyak channel extension dikonfigurasi sebagai `channels.` dan didokumentasikan di halaman channel khususnya (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. +Pesan grup default ke **require mention** (metadata mention 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 di `agents.list[].groupChat.mentionPatterns`. Pola tidak valid dan repetisi bertingkat yang tidak aman diabaikan. -- Gating mention diterapkan hanya saat deteksi dimungkinkan (mention native atau setidaknya satu pola). +- **Metadata mentions**: @-mention native platform. Diabaikan dalam mode self-chat WhatsApp. +- **Text patterns**: pola regex aman di `agents.list[].groupChat.mentionPatterns`. Pola tidak valid dan nested repetition yang tidak aman diabaikan. +- Mention gating hanya diterapkan saat deteksi memungkinkan (mention native atau setidaknya satu pola). ```json5 { @@ -788,7 +788,7 @@ Pesan grup secara default **memerlukan mention** (mention metadata atau pola reg } ``` -`messages.groupChat.historyLimit` menetapkan default global. Channel dapat meng-override 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-akun). Set `0` untuk menonaktifkan. #### Batas riwayat DM @@ -837,16 +837,16 @@ Sertakan nomor Anda sendiri di `allowFrom` untuk mengaktifkan mode self-chat (me ```json5 { commands: { - native: "auto", // daftarkan perintah native saat didukung - nativeSkills: "auto", // daftarkan perintah skill native saat didukung - text: true, // parse /commands dalam pesan chat - bash: false, // izinkan ! (alias: /bash) + native: "auto", // register native commands when supported + nativeSkills: "auto", // register native skill commands when supported + text: true, // parse /commands in chat messages + bash: false, // allow ! (alias: /bash) bashForegroundMs: 2000, - config: false, // izinkan /config - mcp: false, // izinkan /mcp - plugins: false, // izinkan /plugins - debug: false, // izinkan /debug - restart: true, // izinkan /restart + tool restart gateway + config: false, // allow /config + mcp: false, // allow /mcp + plugins: false, // allow /plugins + debug: false, // allow /debug + restart: true, // allow /restart + gateway restart tool ownerAllowFrom: ["discord:123456789012345678"], ownerDisplay: "raw", // raw | hash ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", @@ -861,31 +861,31 @@ Sertakan nomor Anda sendiri di `allowFrom` untuk mengaktifkan mode self-chat (me -- Blok ini mengonfigurasi permukaan perintah. Untuk katalog built-in + bundled saat ini, lihat [Slash Commands](/id/tools/slash-commands). -- Halaman ini adalah **referensi kunci konfigurasi**, bukan katalog perintah lengkap. Perintah milik channel/plugin seperti QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone`, dan Talk `/voice` didokumentasikan di halaman channel/plugin mereka ditambah [Slash Commands](/id/tools/slash-commands). +- Blok ini mengonfigurasi permukaan perintah. Untuk katalog perintah built-in + bundled saat ini, lihat [Slash Commands](/id/tools/slash-commands). +- Halaman ini adalah **referensi kunci konfigurasi**, bukan katalog perintah lengkap. Perintah milik channel/plugin seperti QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone`, dan Talk `/voice` didokumentasikan di halaman channel/plugin masing-masing plus [Slash Commands](/id/tools/slash-commands). - Perintah teks harus berupa pesan **mandiri** dengan awalan `/`. -- `native: "auto"` mengaktifkan perintah native untuk Discord/Telegram, membiarkan Slack nonaktif. -- `nativeSkills: "auto"` mengaktifkan perintah skill native untuk Discord/Telegram, membiarkan Slack nonaktif. +- `native: "auto"` menyalakan perintah native untuk Discord/Telegram, membiarkan Slack nonaktif. +- `nativeSkills: "auto"` menyalakan perintah skill native untuk Discord/Telegram, membiarkan Slack nonaktif. - Override per channel: `channels.discord.commands.native` (bool atau `"auto"`). `false` menghapus perintah yang sebelumnya terdaftar. - Override pendaftaran skill native per channel dengan `channels..commands.nativeSkills`. -- `channels.telegram.customCommands` menambahkan entri menu bot Telegram tambahan. -- `bash: true` mengaktifkan `! ` untuk shell host. Memerlukan `tools.elevated.enabled` dan pengirim berada di `tools.elevated.allowFrom.`. -- `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 dengan cakupan tulis normal. +- `channels.telegram.customCommands` menambahkan entri menu bot Telegram ekstra. +- `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 `chat.send` gateway, penulisan persisten `/config set|unset` juga memerlukan `operator.admin`; `/config show` hanya-baca tetap tersedia untuk klien operator write-scoped normal. - `mcp: true` mengaktifkan `/mcp` untuk konfigurasi server MCP yang dikelola OpenClaw di bawah `mcp.servers`. -- `plugins: true` mengaktifkan `/plugins` untuk penemuan, instalasi, dan kontrol enable/disable plugin. +- `plugins: true` mengaktifkan `/plugins` untuk discovery, install, dan kontrol enable/disable plugin. - `channels..configWrites` mengontrol mutasi konfigurasi per channel (default: true). -- Untuk channel multi-akun, `channels..accounts..configWrites` juga mengontrol penulisan yang menargetkan akun tersebut (misalnya `/allowlist --config --account ` atau `/config set channels..accounts....`). -- `restart: false` menonaktifkan `/restart` dan action tool restart gateway. Default: `true`. +- Untuk channel multi-akun, `channels..accounts..configWrites` juga mengontrol penulisan yang menargetkan akun itu (misalnya `/allowlist --config --account ` atau `/config set channels..accounts....`). +- `restart: false` menonaktifkan `/restart` dan aksi tool restart gateway. Default: `true`. - `ownerAllowFrom` adalah allowlist pemilik eksplisit untuk perintah/tool khusus pemilik. Ini terpisah dari `allowFrom`. -- `ownerDisplay: "hash"` meng-hash ID pemilik di system prompt. Setel `ownerDisplaySecret` untuk mengontrol hashing. -- `allowFrom` bersifat per-provider. Saat disetel, ini adalah **satu-satunya** sumber otorisasi (allowlist/pairing channel dan `useAccessGroups` diabaikan). -- `useAccessGroups: false` memungkinkan perintah melewati kebijakan grup akses saat `allowFrom` tidak disetel. -- Peta dokumen perintah: +- `ownerDisplay: "hash"` meng-hash ID pemilik dalam system prompt. Set `ownerDisplaySecret` untuk mengontrol hashing. +- `allowFrom` bersifat per-provider. Saat disetel, inilah **satu-satunya** sumber otorisasi (allowlist/pairing channel dan `useAccessGroups` diabaikan). +- `useAccessGroups: false` mengizinkan perintah melewati kebijakan access-group saat `allowFrom` tidak disetel. +- Peta dokumentasi perintah: - katalog built-in + bundled: [Slash Commands](/id/tools/slash-commands) - - permukaan perintah khusus channel: [Channels](/id/channels) + - permukaan perintah spesifik channel: [Channels](/id/channels) - perintah QQ Bot: [QQ Bot](/id/channels/qqbot) - perintah pairing: [Pairing](/id/channels/pairing) - - perintah kartu LINE: [LINE](/id/channels/line) + - perintah card LINE: [LINE](/id/channels/line) - memory dreaming: [Dreaming](/id/concepts/dreaming) @@ -906,7 +906,7 @@ Default: `~/.openclaw/workspace`. ### `agents.defaults.repoRoot` -Root repository opsional yang ditampilkan dalam baris Runtime pada system prompt. Jika tidak disetel, OpenClaw mendeteksi otomatis dengan menelusuri ke atas dari workspace. +Root repositori opsional yang ditampilkan di baris Runtime system prompt. Jika tidak disetel, OpenClaw mendeteksi otomatis dengan berjalan ke atas dari workspace. ```json5 { @@ -916,7 +916,7 @@ Root repository opsional yang ditampilkan dalam baris Runtime pada system prompt ### `agents.defaults.skills` -Allowlist skill default opsional untuk agen yang tidak menyetel +Allowlist Skills default opsional untuk agen yang tidak menyetel `agents.list[].skills`. ```json5 @@ -924,19 +924,18 @@ Allowlist skill default opsional untuk agen yang tidak menyetel agents: { defaults: { skills: ["github", "weather"] }, list: [ - { id: "writer" }, // mewarisi github, weather - { id: "docs", skills: ["docs-search"] }, // menggantikan default - { id: "locked-down", skills: [] }, // tanpa skill + { id: "writer" }, // inherits github, weather + { id: "docs", skills: ["docs-search"] }, // replaces defaults + { id: "locked-down", skills: [] }, // no skills ], }, } ``` -- Hilangkan `agents.defaults.skills` untuk skill tak dibatasi secara default. +- Hilangkan `agents.defaults.skills` agar Skills tidak dibatasi secara default. - Hilangkan `agents.list[].skills` untuk mewarisi default. -- Setel `agents.list[].skills: []` untuk tanpa skill. -- Daftar `agents.list[].skills` yang tidak kosong adalah set final untuk agen itu; daftar ini - tidak digabungkan dengan default. +- Set `agents.list[].skills: []` untuk tanpa Skills. +- Daftar `agents.list[].skills` yang tidak kosong adalah set akhir untuk agen itu; tidak digabung dengan default. ### `agents.defaults.skipBootstrap` @@ -952,7 +951,7 @@ Menonaktifkan pembuatan otomatis file bootstrap workspace (`AGENTS.md`, `SOUL.md Mengontrol kapan file bootstrap workspace disisipkan ke system prompt. Default: `"always"`. -- `"continuation-skip"`: giliran lanjutan yang aman (setelah respons asisten selesai) melewati penyisipan ulang bootstrap workspace, mengurangi ukuran prompt. Eksekusi heartbeat dan percobaan ulang pasca-compaction tetap membangun ulang konteks. +- `"continuation-skip"`: giliran lanjutan yang aman (setelah respons asisten selesai) melewati penyisipan ulang bootstrap workspace, sehingga mengurangi ukuran prompt. Proses heartbeat dan retry pasca-compaction tetap membangun ulang konteks. ```json5 { @@ -986,8 +985,8 @@ Mengontrol teks peringatan yang terlihat oleh agen saat konteks bootstrap dipoto Default: `"once"`. - `"off"`: jangan pernah menyisipkan teks peringatan ke system prompt. -- `"once"`: sisipkan peringatan sekali per tanda tangan pemotongan unik (disarankan). -- `"always"`: sisipkan peringatan pada setiap eksekusi saat ada pemotongan. +- `"once"`: sisipkan peringatan sekali per signature truncation unik (direkomendasikan). +- `"always"`: sisipkan peringatan pada setiap run saat truncation ada. ```json5 { @@ -997,10 +996,10 @@ Default: `"once"`. ### `agents.defaults.imageMaxDimensionPx` -Ukuran piksel maksimum untuk sisi terpanjang gambar dalam blok gambar transkrip/tool sebelum pemanggilan provider. +Ukuran piksel maksimum untuk sisi gambar terpanjang dalam blok gambar transcript/tool sebelum panggilan provider. Default: `1200`. -Nilai yang lebih rendah biasanya mengurangi penggunaan vision-token dan ukuran payload permintaan untuk eksekusi dengan banyak tangkapan layar. +Nilai yang lebih rendah biasanya mengurangi penggunaan vision-token dan ukuran payload permintaan untuk run yang banyak tangkapan layar. Nilai yang lebih tinggi mempertahankan lebih banyak detail visual. ```json5 @@ -1011,7 +1010,7 @@ Nilai yang lebih tinggi mempertahankan lebih banyak detail visual. ### `agents.defaults.userTimezone` -Zona waktu untuk konteks system prompt (bukan timestamp pesan). Menggunakan fallback ke zona waktu host. +Timezone untuk konteks system prompt (bukan timestamp pesan). Fallback ke timezone host. ```json5 { @@ -1059,7 +1058,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" }, // param provider default global + params: { cacheRetention: "long" }, // global default provider params pdfMaxBytesMb: 10, pdfMaxPages: 20, thinkingDefault: "low", @@ -1075,42 +1074,42 @@ Format waktu dalam system prompt. Default: `auto` (preferensi OS). ``` - `model`: menerima string (`"provider/model"`) atau objek (`{ primary, fallbacks }`). - - Bentuk string hanya menetapkan model utama. - - Bentuk objek menetapkan model utama plus model failover berurutan. + - Bentuk string hanya menyetel model utama. + - Bentuk objek menyetel model utama plus model failover berurutan. - `imageModel`: menerima string (`"provider/model"`) atau objek (`{ primary, fallbacks }`). - - Digunakan oleh jalur tool `image` sebagai konfigurasi model-vision-nya. - - Juga digunakan sebagai routing fallback saat model yang dipilih/default tidak dapat menerima input gambar. + - Digunakan oleh path tool `image` sebagai konfigurasi vision-model. + - Juga digunakan sebagai routing fallback ketika 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 masa depan apa pun 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 sesuai (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 memiliki auth. Pertama mencoba provider default saat ini, lalu provider pembuatan gambar terdaftar lainnya dalam urutan provider-id. + - Digunakan oleh kapabilitas generasi gambar bersama dan setiap permukaan tool/plugin masa depan yang menghasilkan gambar. + - Nilai umum: `google/gemini-3.1-flash-image-preview` untuk generasi 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 auth/API key provider yang sesuai juga (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 menginfer provider default yang didukung auth. Tool ini mencoba provider default saat ini terlebih dahulu, lalu provider generasi gambar terdaftar lainnya dalam urutan provider-id. - `musicGenerationModel`: menerima string (`"provider/model"`) atau objek (`{ primary, fallbacks }`). - - Digunakan oleh kapabilitas pembuatan musik bersama dan tool built-in `music_generate`. + - Digunakan oleh kapabilitas generasi musik bersama dan tool built-in `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 memiliki auth. Pertama mencoba provider default saat ini, 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. + - Jika dihilangkan, `music_generate` tetap dapat menginfer provider default yang didukung auth. Tool ini mencoba provider default saat ini terlebih dahulu, lalu provider generasi musik terdaftar lainnya dalam urutan provider-id. + - Jika Anda memilih provider/model secara langsung, konfigurasikan auth/API key provider yang sesuai juga. - `videoGenerationModel`: menerima string (`"provider/model"`) atau objek (`{ primary, fallbacks }`). - - Digunakan oleh kapabilitas pembuatan video bersama dan tool built-in `video_generate`. + - Digunakan oleh kapabilitas generasi video bersama dan tool built-in `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 memiliki auth. Pertama mencoba provider default saat ini, 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 bundled Qwen saat ini mendukung hingga 1 video output, 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 menginfer provider default yang didukung auth. Tool ini mencoba provider default saat ini terlebih dahulu, lalu provider generasi video terdaftar lainnya dalam urutan provider-id. + - Jika Anda memilih provider/model secara langsung, konfigurasikan auth/API key provider yang sesuai juga. + - Provider generasi video Qwen bundled mendukung hingga 1 video output, 1 gambar input, 4 video input, durasi 10 detik, dan opsi tingkat provider `size`, `aspectRatio`, `resolution`, `audio`, dan `watermark`. - `pdfModel`: menerima string (`"provider/model"`) atau objek (`{ primary, fallbacks }`). - Digunakan oleh tool `pdf` untuk routing model. - - Jika dihilangkan, tool PDF menggunakan fallback ke `imageModel`, lalu ke model sesi/default yang di-resolve. -- `pdfMaxBytesMb`: batas ukuran PDF default untuk tool `pdf` saat `maxBytesMb` tidak diberikan saat pemanggilan. -- `pdfMaxPages`: jumlah halaman maksimum default yang dipertimbangkan oleh mode fallback ekstraksi di 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 terlebih dahulu mencoba alias, lalu kecocokan provider-terkonfigurasi yang unik untuk ID model yang tepat, dan baru setelah itu menggunakan fallback ke provider default yang dikonfigurasi (perilaku kompatibilitas lama yang sudah deprecated, jadi gunakan `provider/model` eksplisit). Jika provider itu tidak lagi mengekspos model default yang dikonfigurasi, OpenClaw menggunakan 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. Setel di `agents.defaults.params` (mis. `{ cacheRetention: "long" }`). -- Prioritas penggabungan `params` (konfigurasi): `agents.defaults.params` (basis global) dioverride oleh `agents.defaults.models["provider/model"].params` (per-model), lalu `agents.list[].params` (ID agen yang cocok) mengoverride per kunci. Lihat [Prompt Caching](/id/reference/prompt-caching) untuk detail. + - Jika dihilangkan, tool PDF fallback ke `imageModel`, lalu ke model sesi/default yang ter-resolve. +- `pdfMaxBytesMb`: batas ukuran PDF default untuk tool `pdf` saat `maxBytesMb` tidak diberikan pada waktu panggilan. +- `pdfMaxPages`: jumlah halaman maksimum default yang dipertimbangkan oleh mode fallback ekstraksi dalam tool `pdf`. +- `verboseDefault`: tingkat verbose default untuk agen. Nilai: `"off"`, `"on"`, `"full"`. Default: `"off"`. +- `elevatedDefault`: tingkat 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 pencocokan configured-provider unik untuk model id yang tepat, dan baru kemudian fallback ke default provider yang dikonfigurasi (perilaku kompatibilitas lama yang deprecated, jadi sebaiknya gunakan `provider/model` eksplisit). Jika provider itu tidak lagi mengekspos model default yang dikonfigurasi, OpenClaw fallback ke provider/model pertama yang dikonfigurasi alih-alih menampilkan default provider lama yang sudah dihapus. +- `models`: katalog model terkonfigurasi dan allowlist untuk `/model`. Tiap entri dapat mencakup `alias` (shortcut) dan `params` (spesifik provider, misalnya `temperature`, `maxTokens`, `cacheRetention`, `context1m`). +- `params`: parameter provider default global yang diterapkan ke semua model. Set di `agents.defaults.params` (mis. `{ cacheRetention: "long" }`). +- Precedensi penggabungan `params` (konfigurasi): `agents.defaults.params` (basis global) dioverride oleh `agents.defaults.models["provider/model"].params` (per-model), lalu `agents.list[].params` (id agen yang cocok) override berdasarkan 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 di seluruh sesi (setiap sesi tetap diserialisasi). Default: 4. +- `maxConcurrent`: jumlah maksimum run agen paralel di seluruh sesi (setiap sesi tetap diserialisasi). Default: 4. -**Singkatan alias built-in** (hanya berlaku saat model ada di `agents.defaults.models`): +**Shorthand alias built-in** (hanya berlaku saat model ada di `agents.defaults.models`): | Alias | Model | | ------------------- | -------------------------------------- | @@ -1123,15 +1122,15 @@ 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 selalu menang atas default. +Alias yang Anda konfigurasikan selalu menang atas default. -Model Z.AI GLM-4.x secara otomatis mengaktifkan mode thinking kecuali Anda menetapkan `--thinking off` atau menentukan sendiri `agents.defaults.models["zai/"].params.thinking`. -Model Z.AI mengaktifkan `tool_stream` secara default untuk streaming pemanggilan tool. Setel `agents.defaults.models["zai/"].params.tool_stream` ke `false` untuk menonaktifkannya. -Model Anthropic Claude 4.6 default ke thinking `adaptive` saat tidak ada level thinking eksplisit yang disetel. +Model Z.AI GLM-4.x otomatis mengaktifkan mode thinking kecuali Anda menyetel `--thinking off` atau mendefinisikan `agents.defaults.models["zai/"].params.thinking` sendiri. +Model Z.AI mengaktifkan `tool_stream` secara default untuk streaming panggilan tool. Set `agents.defaults.models["zai/"].params.tool_stream` ke `false` untuk menonaktifkannya. +Model Anthropic Claude 4.6 default ke thinking `adaptive` ketika tidak ada tingkat thinking eksplisit yang disetel. ### `agents.defaults.cliBackends` -Backend CLI opsional untuk eksekusi fallback teks saja (tanpa pemanggilan tool). Berguna sebagai cadangan saat provider API gagal. +Backend CLI opsional untuk run fallback teks saja (tanpa panggilan tool). Berguna sebagai cadangan ketika provider API gagal. ```json5 { @@ -1159,13 +1158,13 @@ Backend CLI opsional untuk eksekusi fallback teks saja (tanpa pemanggilan tool). } ``` -- Backend CLI bersifat text-first; tool selalu dinonaktifkan. -- Sesi didukung saat `sessionArg` disetel. +- Backend CLI berfokus pada teks; tool selalu dinonaktifkan. +- Sesi didukung ketika `sessionArg` disetel. - Pass-through gambar didukung saat `imageArg` menerima path file. ### `agents.defaults.systemPromptOverride` -Gantikan seluruh system prompt yang dirakit OpenClaw dengan string tetap. Setel pada level default (`agents.defaults.systemPromptOverride`) atau per agen (`agents.list[].systemPromptOverride`). Nilai per-agen memiliki prioritas lebih tinggi; nilai kosong atau hanya whitespace diabaikan. Berguna untuk eksperimen prompt yang terkontrol. +Ganti seluruh system prompt rakitan OpenClaw dengan string tetap. Set di level default (`agents.defaults.systemPromptOverride`) atau per agen (`agents.list[].systemPromptOverride`). Nilai per-agen mendapat prioritas; nilai kosong atau hanya whitespace diabaikan. Berguna untuk eksperimen prompt terkontrol. ```json5 { @@ -1179,23 +1178,23 @@ Gantikan seluruh system prompt yang dirakit OpenClaw dengan string tetap. Setel ### `agents.defaults.heartbeat` -Eksekusi heartbeat berkala. +Run heartbeat berkala. ```json5 { agents: { defaults: { heartbeat: { - every: "30m", // 0m menonaktifkan + every: "30m", // 0m disables model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // default: true; false menghilangkan bagian Heartbeat dari system prompt - lightContext: false, // default: false; true hanya mempertahankan HEARTBEAT.md dari file bootstrap workspace - isolatedSession: false, // default: false; true menjalankan setiap heartbeat di sesi baru (tanpa riwayat percakapan) + includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt + lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files + isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history) session: "main", to: "+15555550123", directPolicy: "allow", // allow (default) | block - target: "none", // default: none | opsi: last | whatsapp | telegram | discord | ... + target: "none", // default: none | options: last | whatsapp | telegram | discord | ... prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, suppressToolErrorWarnings: false, @@ -1205,13 +1204,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. +- `every`: string durasi (ms/s/m/h). Default: `30m` (auth API-key) atau `1h` (auth OAuth). Set ke `0m` untuk menonaktifkan. - `includeSystemPromptSection`: saat false, menghilangkan bagian Heartbeat dari system prompt dan melewati penyisipan `HEARTBEAT.md` ke konteks bootstrap. Default: `true`. -- `suppressToolErrorWarnings`: saat true, menekan payload peringatan error tool selama eksekusi heartbeat. -- `directPolicy`: kebijakan pengiriman langsung/DM. `allow` (default) mengizinkan pengiriman target langsung. `block` menekan pengiriman target langsung dan memunculkan `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 berjalan di 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. +- `suppressToolErrorWarnings`: saat true, menekan payload peringatan error tool selama run heartbeat. +- `directPolicy`: kebijakan pengiriman langsung/DM. `allow` (default) mengizinkan pengiriman target langsung. `block` menekan pengiriman target langsung dan menghasilkan `reason=dm-blocked`. +- `lightContext`: saat true, run heartbeat menggunakan konteks bootstrap ringan dan hanya mempertahankan `HEARTBEAT.md` dari file bootstrap workspace. +- `isolatedSession`: saat true, setiap run 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-agen: set `agents.list[].heartbeat`. Saat agen mana pun mendefinisikan `heartbeat`, **hanya agen tersebut** yang menjalankan heartbeat. - Heartbeat menjalankan giliran agen penuh — interval yang lebih pendek membakar lebih banyak token. ### `agents.defaults.compaction` @@ -1222,14 +1221,14 @@ Eksekusi heartbeat berkala. defaults: { compaction: { mode: "safeguard", // default | safeguard - provider: "my-provider", // id plugin provider compaction terdaftar (opsional) + provider: "my-provider", // id of a registered compaction provider plugin (optional) timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // digunakan saat identifierPolicy=custom - postCompactionSections: ["Session Startup", "Red Lines"], // [] menonaktifkan penyisipan ulang - model: "openrouter/anthropic/claude-sonnet-4-6", // override model khusus compaction opsional - notifyUser: true, // kirim pemberitahuan singkat saat compaction dimulai (default: false) + identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom + postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection + model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override + notifyUser: true, // send a brief notice when compaction starts (default: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, @@ -1242,15 +1241,15 @@ Eksekusi heartbeat berkala. } ``` -- `mode`: `default` atau `safeguard` (ringkasan bertahap untuk riwayat panjang). Lihat [Compaction](/id/concepts/compaction). -- `provider`: id plugin provider compaction terdaftar. Saat disetel, `summarize()` milik provider dipanggil alih-alih ringkasan LLM built-in. Menggunakan fallback ke built-in saat gagal. Menyetel provider memaksa `mode: "safeguard"`. Lihat [Compaction](/id/concepts/compaction). +- `mode`: `default` atau `safeguard` (ringkasan terpotong per-bagian untuk riwayat panjang). Lihat [Compaction](/id/concepts/compaction). +- `provider`: id plugin provider compaction terdaftar. Saat disetel, `summarize()` milik provider dipanggil alih-alih ringkasan LLM built-in. Fallback ke built-in saat gagal. Menyetel provider memaksa `mode: "safeguard"`. Lihat [Compaction](/id/concepts/compaction). - `timeoutSeconds`: jumlah detik maksimum 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 kustom opsional untuk preservasi identifier yang digunakan saat `identifierPolicy=custom`. -- `postCompactionSections`: nama bagian AGENTS.md H2/H3 opsional untuk disisipkan ulang setelah compaction. Default ke `["Session Startup", "Red Lines"]`; setel `[]` untuk menonaktifkan penyisipan ulang. Saat tidak disetel atau secara eksplisit disetel ke pasangan default itu, heading lama `Every Session`/`Safety` juga diterima sebagai fallback kompatibilitas lama. -- `model`: override `provider/model-id` opsional hanya untuk ringkasan compaction. Gunakan ini saat sesi utama harus tetap memakai satu model tetapi ringkasan compaction harus berjalan di model lain; saat tidak disetel, compaction memakai model utama sesi. +- `identifierPolicy`: `strict` (default), `off`, atau `custom`. `strict` menambahkan panduan retensi identifier opak built-in selama summarization compaction. +- `identifierInstructions`: teks pelestarian identifier kustom opsional yang digunakan saat `identifierPolicy=custom`. +- `postCompactionSections`: nama bagian H2/H3 AGENTS.md opsional yang disisipkan ulang setelah compaction. Default ke `["Session Startup", "Red Lines"]`; set `[]` untuk menonaktifkan reinjection. Saat tidak disetel atau secara eksplisit disetel ke pasangan default itu, heading lama `Every Session`/`Safety` juga diterima sebagai fallback lama. +- `model`: override `provider/model-id` opsional hanya untuk summarization compaction. Gunakan ini saat sesi utama harus tetap memakai satu model tetapi ringkasan compaction harus berjalan pada model lain; saat tidak disetel, compaction menggunakan model utama 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 hanya-baca. +- `memoryFlush`: giliran agentic senyap sebelum auto-compaction untuk menyimpan memori yang tahan lama. Dilewati saat workspace read-only. ### `agents.defaults.contextPruning` @@ -1262,7 +1261,7 @@ Memangkas **hasil tool lama** dari konteks dalam memori sebelum dikirim ke LLM. defaults: { contextPruning: { mode: "cache-ttl", // off | cache-ttl - ttl: "1h", // durasi (ms/s/m/h), unit default: menit + ttl: "1h", // duration (ms/s/m/h), default unit: minutes keepLastAssistants: 3, softTrimRatio: 0.3, hardClearRatio: 0.5, @@ -1279,16 +1278,16 @@ Memangkas **hasil tool lama** dari konteks dalam memori sebelum dikirim ke LLM. - `mode: "cache-ttl"` mengaktifkan pass pruning. -- `ttl` mengontrol seberapa sering pruning dapat berjalan lagi (setelah sentuhan cache terakhir). -- Pruning melakukan soft-trim pada hasil tool besar terlebih dahulu, lalu hard-clear pada hasil tool yang lebih lama jika diperlukan. +- `ttl` mengontrol seberapa sering pruning dapat dijalankan lagi (setelah sentuhan cache terakhir). +- Pruning terlebih dahulu melakukan soft-trim pada hasil tool yang terlalu besar, lalu hard-clear pada hasil tool yang lebih lama bila 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/dibersihkan. +- Blok gambar tidak pernah dipotong/dikosongkan. - Rasio berbasis karakter (perkiraan), bukan hitungan token yang tepat. - Jika ada kurang dari `keepLastAssistants` pesan asisten, pruning dilewati. @@ -1306,7 +1305,7 @@ Lihat [Session Pruning](/id/concepts/session-pruning) untuk detail perilaku. blockStreamingBreak: "text_end", // text_end | message_end blockStreamingChunk: { minChars: 800, maxChars: 1200 }, blockStreamingCoalesce: { idleMs: 1000 }, - humanDelay: { mode: "natural" }, // off | natural | custom (gunakan minMs/maxMs) + humanDelay: { mode: "natural" }, // off | natural | custom (use minMs/maxMs) }, }, } @@ -1314,11 +1313,11 @@ 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 di antara balasan blok. `natural` = 800–2500ms. Override per-agen: `agents.list[].humanDelay`. +- `humanDelay`: jeda acak antar balasan blok. `natural` = 800–2500ms. Override per-agen: `agents.list[].humanDelay`. -Lihat [Streaming](/id/concepts/streaming) untuk detail perilaku + chunking. +Lihat [Streaming](/id/concepts/streaming) untuk perilaku + detail chunking. -### Indikator pengetikan +### Indikator mengetik ```json5 { @@ -1340,7 +1339,7 @@ Lihat [Typing Indicators](/id/concepts/typing-indicators). ### `agents.defaults.sandbox` -Sandboxing opsional untuk agen tertanam. Lihat [Sandboxing](/id/gateway/sandboxing) untuk panduan lengkap. +Sandboxing opsional untuk agen tersemat. Lihat [Sandboxing](/id/gateway/sandboxing) untuk panduan lengkap. ```json5 { @@ -1386,7 +1385,7 @@ Sandboxing opsional untuk agen tertanam. Lihat [Sandboxing](/id/gateway/sandboxi identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // SecretRef / konten inline juga didukung: + // SecretRefs / inline contents also supported: // 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" }, @@ -1440,7 +1439,7 @@ Sandboxing opsional untuk agen tertanam. Lihat [Sandboxing](/id/gateway/sandboxi **Backend:** - `docker`: runtime Docker lokal (default) -- `ssh`: runtime jarak jauh umum berbasis SSH +- `ssh`: runtime jarak jauh berbasis SSH generik - `openshell`: runtime OpenShell Saat `backend: "openshell"` dipilih, pengaturan khusus runtime dipindahkan ke @@ -1452,10 +1451,10 @@ Saat `backend: "openshell"` dipilih, pengaturan khusus runtime dipindahkan ke - `command`: perintah klien SSH (default: `ssh`) - `workspaceRoot`: root jarak jauh 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 dimaterialisasi OpenClaw menjadi file sementara saat runtime +- `identityData` / `certificateData` / `knownHostsData`: konten inline atau SecretRef yang dimaterialisasikan OpenClaw ke file sementara saat runtime - `strictHostKeyChecking` / `updateHostKeys`: knob kebijakan host-key OpenSSH -**Prioritas auth SSH:** +**Precedensi auth SSH:** - `identityData` menang atas `identityFile` - `certificateData` menang atas `certificateFile` @@ -1464,23 +1463,23 @@ Saat `backend: "openshell"` dipilih, pengaturan khusus runtime dipindahkan ke **Perilaku backend SSH:** -- mengisi workspace jarak jauh sekali setelah create atau recreate -- lalu mempertahankan workspace SSH jarak jauh sebagai kanonis -- merutekan `exec`, tool file, dan jalur media melalui SSH +- menanam workspace jarak jauh sekali setelah create atau recreate +- lalu mempertahankan workspace SSH jarak jauh sebagai yang kanonis +- merutekan `exec`, file tools, dan path media melalui SSH - tidak menyinkronkan perubahan jarak jauh kembali ke host secara otomatis -- tidak mendukung container browser sandbox +- tidak mendukung kontainer browser sandbox **Akses workspace:** - `none`: workspace sandbox per-scope di bawah `~/.openclaw/sandboxes` -- `ro`: workspace sandbox di `/workspace`, workspace agen dipasang hanya-baca di `/agent` -- `rw`: workspace agen dipasang baca/tulis di `/workspace` +- `ro`: workspace sandbox di `/workspace`, workspace agen di-mount read-only di `/agent` +- `rw`: workspace agen di-mount read/write di `/workspace` **Scope:** -- `session`: container + workspace per-sesi -- `agent`: satu container + workspace per agen (default) -- `shared`: container dan workspace bersama (tanpa isolasi lintas sesi) +- `session`: kontainer + workspace per-sesi +- `agent`: satu kontainer + workspace per agen (default) +- `shared`: kontainer dan workspace bersama (tanpa isolasi lintas sesi) **Konfigurasi plugin OpenShell:** @@ -1495,10 +1494,10 @@ Saat `backend: "openshell"` dipilih, pengaturan khusus runtime dipindahkan ke from: "openclaw", remoteWorkspaceDir: "/sandbox", remoteAgentWorkspaceDir: "/agent", - gateway: "lab", // opsional - gatewayEndpoint: "https://lab.example", // opsional - policy: "strict", // id kebijakan OpenShell opsional - providers: ["openai"], // opsional + gateway: "lab", // optional + gatewayEndpoint: "https://lab.example", // optional + policy: "strict", // optional OpenShell policy id + providers: ["openai"], // optional autoProviders: true, timeoutSeconds: 120, }, @@ -1510,30 +1509,30 @@ Saat `backend: "openshell"` dipilih, pengaturan khusus runtime dipindahkan ke **Mode OpenShell:** -- `mirror`: isi jarak jauh dari lokal sebelum exec, sinkronkan balik setelah exec; workspace lokal tetap kanonis -- `remote`: isi jarak jauh sekali saat sandbox dibuat, lalu pertahankan workspace jarak jauh sebagai kanonis +- `mirror`: tanam remote dari lokal sebelum exec, sinkronkan balik setelah exec; workspace lokal tetap kanonis +- `remote`: tanam remote sekali saat sandbox dibuat, lalu pertahankan workspace remote sebagai yang kanonis -Dalam mode `remote`, edit host-lokal yang dibuat di luar OpenClaw tidak disinkronkan ke sandbox secara otomatis setelah langkah seed. +Dalam mode `remote`, edit lokal host yang dibuat di luar OpenClaw tidak disinkronkan ke sandbox secara otomatis setelah langkah seed. Transport menggunakan SSH ke sandbox OpenShell, tetapi plugin memiliki lifecycle sandbox dan sinkronisasi mirror opsional. -**`setupCommand`** berjalan sekali setelah pembuatan container (melalui `sh -lc`). Memerlukan egress jaringan, root yang bisa ditulis, pengguna root. +**`setupCommand`** berjalan sekali setelah pembuatan kontainer (melalui `sh -lc`). Memerlukan egress jaringan, root yang dapat ditulis, pengguna root. -**Container default ke `network: "none"`** — setel ke `"bridge"` (atau jaringan bridge kustom) jika agen membutuhkan akses keluar. +**Kontainer default ke `network: "none"`** — set ke `"bridge"` (atau jaringan bridge kustom) jika agen memerlukan akses keluar. `"host"` diblokir. `"container:"` diblokir secara default kecuali Anda secara eksplisit menyetel -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (darurat). +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (break-glass). **Lampiran masuk** ditempatkan ke `media/inbound/*` dalam workspace aktif. -**`docker.binds`** memasang direktori host tambahan; bind global dan per-agen digabungkan. +**`docker.binds`** me-mount direktori host tambahan; bind global dan per-agen digabung. -**Browser sandbox** (`sandbox.browser.enabled`): Chromium + CDP dalam container. URL noVNC disisipkan ke system prompt. Tidak memerlukan `browser.enabled` di `openclaw.json`. -Akses pengamat noVNC menggunakan auth VNC secara default dan OpenClaw memancarkan URL token berumur pendek (alih-alih mengekspos kata sandi di URL bersama). +**Browser sandbox** (`sandbox.browser.enabled`): Chromium + CDP dalam kontainer. URL noVNC disisipkan ke system prompt. Tidak memerlukan `browser.enabled` di `openclaw.json`. +Akses pengamat noVNC secara default menggunakan auth VNC dan OpenClaw mengeluarkan URL token jangka pendek (alih-alih mengekspos password dalam URL bersama). -- `allowHostControl: false` (default) memblokir sesi sandbox agar tidak menargetkan browser host. -- `network` default ke `openclaw-sandbox-browser` (jaringan bridge khusus). Setel ke `bridge` hanya jika Anda memang menginginkan konektivitas bridge global. -- `cdpSourceRange` secara opsional membatasi ingress CDP di tepi container ke rentang CIDR (misalnya `172.21.0.1/32`). -- `sandbox.browser.binds` memasang direktori host tambahan hanya ke container browser sandbox. Saat disetel (termasuk `[]`), ini menggantikan `docker.binds` untuk container browser. -- Default peluncuran ditetapkan dalam `scripts/sandbox-browser-entrypoint.sh` dan disetel untuk host container: +- `allowHostControl: false` (default) memblokir sesi sandbox menargetkan browser host. +- `network` default ke `openclaw-sandbox-browser` (jaringan bridge khusus). Set ke `bridge` hanya bila Anda secara eksplisit menginginkan konektivitas bridge global. +- `cdpSourceRange` secara opsional membatasi ingress CDP pada 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: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1550,28 +1549,28 @@ Akses pengamat noVNC menggunakan auth VNC secara default dan OpenClaw memancarka - `--renderer-process-limit=2` - `--no-zygote` - `--metrics-recording-only` - - `--disable-extensions` (aktif secara default) + - `--disable-extensions` (default aktif) - `--disable-3d-apis`, `--disable-software-rasterizer`, dan `--disable-gpu` - aktif secara default dan dapat dinonaktifkan dengan + diaktifkan secara default dan dapat dinonaktifkan dengan `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` jika penggunaan WebGL/3D memerlukannya. - `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 memakai + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; set `0` untuk menggunakan batas proses default Chromium. - - plus `--no-sandbox` dan `--disable-setuid-sandbox` saat `noSandbox` diaktifkan. - - Default adalah baseline image container; gunakan image browser kustom dengan entrypoint kustom - untuk mengubah default container. + - ditambah `--no-sandbox` dan `--disable-setuid-sandbox` saat `noSandbox` diaktifkan. + - Default adalah baseline image kontainer; gunakan image browser kustom dengan + entrypoint kustom untuk mengubah default kontainer. -Sandboxing browser dan `sandbox.docker.binds` saat ini hanya Docker. +Browser sandboxing dan `sandbox.docker.binds` hanya untuk Docker. -Bangun image: +Build image: ```bash -scripts/sandbox-setup.sh # image sandbox utama -scripts/sandbox-browser-setup.sh # image browser opsional +scripts/sandbox-setup.sh # main sandbox image +scripts/sandbox-browser-setup.sh # optional browser image ``` ### `agents.list` (override per-agen) @@ -1586,12 +1585,12 @@ scripts/sandbox-browser-setup.sh # image browser opsional name: "Main Agent", 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" }, // mengoverride defaults.models yang cocok per kunci - skills: ["docs-search"], // menggantikan agents.defaults.skills saat disetel + model: "anthropic/claude-opus-4-6", // or { primary, fallbacks } + thinkingDefault: "high", // per-agent thinking level override + reasoningDefault: "on", // per-agent reasoning visibility override + fastModeDefault: false, // per-agent fast mode override + params: { cacheRetention: "none" }, // overrides matching defaults.models params by key + skills: ["docs-search"], // replaces agents.defaults.skills when set identity: { name: "Samantha", theme: "helpful sloth", @@ -1622,26 +1621,26 @@ scripts/sandbox-browser-setup.sh # image browser opsional } ``` -- `id`: ID agen stabil (wajib). +- `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 mengoverride `primary`; bentuk objek `{ primary, fallbacks }` mengoverride keduanya (`[]` menonaktifkan fallback global). Tugas cron yang hanya mengoverride `primary` tetap mewarisi fallback default kecuali Anda menyetel `fallbacks: []`. -- `params`: parameter stream per-agen yang digabungkan di atas entri model yang dipilih 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 skill. -- `thinkingDefault`: level thinking default per-agen opsional (`off | minimal | low | medium | high | xhigh | adaptive`). Mengoverride `agents.defaults.thinkingDefault` untuk agen ini saat tidak ada override per-pesan atau per-sesi. -- `reasoningDefault`: visibilitas reasoning default per-agen opsional (`on | off | stream`). Berlaku saat tidak ada override reasoning per-pesan atau per-sesi. -- `fastModeDefault`: default per-agen opsional untuk fast mode (`true | false`). Berlaku saat tidak ada override fast-mode per-pesan atau per-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. -- `identity.avatar`: path relatif-workspace, URL `http(s)`, atau URI `data:`. +- `model`: bentuk string hanya meng-override `primary`; bentuk objek `{ primary, fallbacks }` meng-override keduanya (`[]` menonaktifkan fallback global). Job cron yang hanya meng-override `primary` tetap mewarisi fallback default kecuali Anda menyetel `fallbacks: []`. +- `params`: parameter stream per-agen yang digabung di atas entri model terpilih di `agents.defaults.models`. Gunakan ini untuk override spesifik agen seperti `cacheRetention`, `temperature`, atau `maxTokens` tanpa menduplikasi seluruh katalog model. +- `skills`: allowlist Skills per-agen opsional. Jika dihilangkan, agen mewarisi `agents.defaults.skills` bila disetel; daftar eksplisit menggantikan default alih-alih digabung, dan `[]` berarti tanpa Skills. +- `thinkingDefault`: default tingkat thinking per-agen opsional (`off | minimal | low | medium | high | xhigh | adaptive`). Meng-override `agents.defaults.thinkingDefault` untuk agen ini saat tidak ada override per-pesan atau per-sesi. +- `reasoningDefault`: default visibilitas reasoning per-agen opsional (`on | off | stream`). Berlaku saat tidak ada override reasoning per-pesan atau per-sesi. +- `fastModeDefault`: default mode cepat per-agen opsional (`true | false`). Berlaku saat tidak ada override mode cepat per-pesan atau per-sesi. +- `runtime`: descriptor runtime per-agen opsional. Gunakan `type: "acp"` dengan default `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) saat agen 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 pun; default: agen yang sama saja). -- Guard pewarisan sandbox: jika sesi peminta berada dalam sandbox, `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 agen untuk `sessions_spawn` (`["*"]` = apa pun; default: hanya agen yang sama). +- Guard pewarisan sandbox: jika sesi peminta disandbox, `sessions_spawn` menolak target yang akan berjalan tanpa sandbox. +- `subagents.requireAgentId`: saat true, blokir panggilan `sessions_spawn` yang menghilangkan `agentId` (memaksa pemilihan profil eksplisit; default: false). --- ## Routing multi-agen -Jalankan beberapa agen terisolasi di dalam satu Gateway. Lihat [Multi-Agent](/id/concepts/multi-agent). +Jalankan beberapa agen terisolasi dalam satu Gateway. Lihat [Multi-Agent](/id/concepts/multi-agent). ```json5 { @@ -1660,25 +1659,25 @@ Jalankan beberapa agen terisolasi di dalam satu Gateway. Lihat [Multi-Agent](/id ### Field kecocokan binding -- `type` (opsional): `route` untuk routing normal (type yang hilang default ke route), `acp` untuk binding percakapan ACP persisten. +- `type` (opsional): `route` untuk routing normal (tanpa type default ke route), `acp` untuk binding percakapan ACP persisten. - `match.channel` (wajib) -- `match.accountId` (opsional; `*` = akun apa saja; dihilangkan = akun default) +- `match.accountId` (opsional; `*` = akun apa pun; dihilangkan = akun default) - `match.peer` (opsional; `{ kind: direct|group|channel, id }`) -- `match.guildId` / `match.teamId` (opsional; khusus channel) +- `match.guildId` / `match.teamId` (opsional; spesifik channel) - `acp` (opsional; hanya untuk entri `type: "acp"`): `{ mode, label, cwd, backend }` -**Urutan kecocokan deterministik:** +**Urutan pencocokan deterministik:** 1. `match.peer` 2. `match.guildId` 3. `match.teamId` -4. `match.accountId` (tepat, tanpa peer/guild/team) -5. `match.accountId: "*"` (seluruh channel) +4. `match.accountId` (persis, tanpa peer/guild/team) +5. `match.accountId: "*"` (cakupan channel) 6. Agen default -Dalam setiap tier, entri `bindings` pertama yang cocok akan menang. +Dalam tiap 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 binding route di atas. ### Profil akses per-agen @@ -1700,7 +1699,7 @@ Untuk entri `type: "acp"`, OpenClaw me-resolve berdasarkan identitas percakapan - + ```json5 { @@ -1729,7 +1728,7 @@ Untuk entri `type: "acp"`, OpenClaw me-resolve berdasarkan identitas percakapan - + ```json5 { @@ -1775,11 +1774,11 @@ Untuk entri `type: "acp"`, OpenClaw me-resolve berdasarkan identitas percakapan -Lihat [Multi-Agent Sandbox & Tools](/id/tools/multi-agent-sandbox-tools) untuk detail prioritas. +Lihat [Multi-Agent Sandbox & Tools](/id/tools/multi-agent-sandbox-tools) untuk detail precedensi. --- -## Session +## Sesi ```json5 { @@ -1801,22 +1800,22 @@ Lihat [Multi-Agent Sandbox & Tools](/id/tools/multi-agent-sandbox-tools) untuk d }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // lewati fork parent-thread di atas jumlah token ini (0 menonaktifkan) + parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables) maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", maxEntries: 500, rotateBytes: "10mb", - resetArchiveRetention: "30d", // durasi atau false - maxDiskBytes: "500mb", // opsional hard budget - highWaterBytes: "400mb", // target cleanup opsional + resetArchiveRetention: "30d", // duration or false + maxDiskBytes: "500mb", // optional hard budget + highWaterBytes: "400mb", // optional cleanup target }, threadBindings: { enabled: true, - idleHours: 24, // auto-unfocus tidak aktif default dalam jam (`0` menonaktifkan) - maxAgeHours: 0, // usia maksimum keras default dalam jam (`0` menonaktifkan) + idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables) + maxAgeHours: 0, // default hard max age in hours (`0` disables) }, - mainKey: "main", // lama (runtime selalu menggunakan "main") + mainKey: "main", // legacy (runtime always uses "main") agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -1826,48 +1825,48 @@ 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 jika konteks bersama memang diinginkan). -- **`dmScope`**: cara DM dikelompokkan. + - `per-sender` (default): tiap pengirim mendapat sesi terisolasi 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`**: memetakan 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 akan menang. -- **`resetByType`**: override per-jenis (`direct`, `group`, `thread`). `dm` lama diterima sebagai alias untuk `direct`. -- **`parentForkMaxTokens`**: `totalTokens` sesi induk maksimum yang diizinkan saat membuat sesi thread hasil fork (default `100000`). - - Jika `totalTokens` parent di atas nilai ini, OpenClaw memulai sesi thread baru alih-alih mewarisi riwayat transkrip parent. - - Setel `0` untuk menonaktifkan guard ini dan selalu mengizinkan forking parent. -- **`mainKey`**: field lama. Runtime sekarang selalu menggunakan `"main"` untuk bucket chat langsung utama. -- **`agentToAgent.maxPingPongTurns`**: jumlah maksimum giliran balas-balik antar agen selama pertukaran agent-to-agent (bilangan bulat, 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 penyimpanan sesi. - - `mode`: `warn` hanya memunculkan peringatan; `enforce` menerapkan cleanup. - - `pruneAfter`: cutoff usia untuk entri usang (default `30d`). + - `per-peer`: isolasi berdasarkan id pengirim lintas channel. + - `per-channel-peer`: isolasi per channel + pengirim (direkomendasikan untuk inbox multi-pengguna). + - `per-account-channel-peer`: isolasi per akun + channel + pengirim (direkomendasikan untuk multi-akun). +- **`identityLinks`**: peta id kanonis ke peer berprefiks 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 menang. +- **`resetByType`**: override per-tipe (`direct`, `group`, `thread`). `dm` lama diterima sebagai alias untuk `direct`. +- **`parentForkMaxTokens`**: `totalTokens` sesi induk maksimum yang diizinkan saat membuat sesi thread yang di-fork (default `100000`). + - Jika `totalTokens` induk di atas nilai ini, OpenClaw memulai sesi thread baru alih-alih mewarisi riwayat transkrip induk. + - Set `0` untuk menonaktifkan guard ini dan selalu mengizinkan forking induk. +- **`mainKey`**: field lama. Runtime selalu menggunakan `"main"` untuk bucket chat langsung utama. +- **`agentToAgent.maxPingPongTurns`**: jumlah maksimum giliran balas-balik 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 menang. +- **`maintenance`**: kontrol pembersihan + retensi penyimpanan sesi. + - `mode`: `warn` hanya mengeluarkan peringatan; `enforce` menerapkan pembersihan. + - `pruneAfter`: batas usia untuk entri basi (default `30d`). - `maxEntries`: jumlah maksimum entri dalam `sessions.json` (default `500`). - - `rotateBytes`: rotasikan `sessions.json` saat melebihi ukuran ini (default `10mb`). - - `resetArchiveRetention`: retensi untuk arsip transkrip `*.reset.`. Default ke `pruneAfter`; setel `false` untuk menonaktifkan. - - `maxDiskBytes`: budget disk direktori sesi opsional. Dalam mode `warn` akan mencatat peringatan; dalam mode `enforce` akan menghapus artefak/sesi tertua lebih dulu. - - `highWaterBytes`: target opsional setelah cleanup budget. Default ke `80%` dari `maxDiskBytes`. + - `rotateBytes`: rotasi `sessions.json` saat melampaui ukuran ini (default `10mb`). + - `resetArchiveRetention`: retensi untuk arsip transkrip `*.reset.`. Default ke `pruneAfter`; set `false` untuk menonaktifkan. + - `maxDiskBytes`: anggaran disk direktori sesi keras 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`. - **`threadBindings`**: default global untuk fitur sesi terikat thread. - - `enabled`: sakelar default master (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) + - `enabled`: sakelar default utama (provider dapat meng-override; Discord menggunakan `channels.discord.threadBindings.enabled`) + - `idleHours`: default auto-unfocus karena inaktivitas dalam jam (`0` menonaktifkan; provider dapat meng-override) + - `maxAgeHours`: default usia maksimum keras dalam jam (`0` menonaktifkan; provider dapat meng-override) --- -## Messages +## Pesan ```json5 { messages: { - responsePrefix: "🦞", // atau "auto" + responsePrefix: "🦞", // or "auto" ackReaction: "👀", ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all removeAckAfterReply: false, @@ -1882,7 +1881,7 @@ Lihat [Multi-Agent Sandbox & Tools](/id/tools/multi-agent-sandbox-tools) untuk d }, }, inbound: { - debounceMs: 2000, // 0 menonaktifkan + debounceMs: 2000, // 0 disables byChannel: { whatsapp: 5000, slack: 1500, @@ -1892,7 +1891,7 @@ 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`. @@ -1900,26 +1899,26 @@ Resolusi (yang paling spesifik menang): akun → channel → global. `""` menona **Variabel template:** -| Variabel | Deskripsi | Contoh | -| ----------------- | ---------------------- | --------------------------- | -| `{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"`) | +| Variabel | Deskripsi | Contoh | +| ----------------- | --------------------- | --------------------------- | +| `{model}` | Nama model pendek | `claude-opus-4-6` | +| `{modelFull}` | Identifier model penuh| `anthropic/claude-opus-4-6` | +| `{provider}` | Nama provider | `anthropic` | +| `{thinkingLevel}` | Tingkat thinking saat ini | `high`, `low`, `off` | +| `{identity.name}` | Nama identitas agen | (sama seperti `"auto"`) | Variabel tidak peka huruf besar/kecil. `{think}` adalah alias untuk `{thinkingLevel}`. ### Reaksi ack -- Default ke `identity.emoji` agen aktif, jika tidak `"👀"`. Setel `""` untuk menonaktifkan. +- Default ke `identity.emoji` agen aktif, jika tidak `"👀"`. Set `""` untuk menonaktifkan. - Override per-channel: `channels..ackReaction`, `channels..accounts..ackReaction`. - Urutan resolusi: akun → channel → `messages.ackReaction` → fallback identitas. - Scope: `group-mentions` (default), `group-all`, `direct`, `all`. - `removeAckAfterReply`: menghapus ack setelah balasan di Slack, Discord, dan Telegram. - `messages.statusReactions.enabled`: mengaktifkan reaksi status lifecycle di Slack, Discord, dan Telegram. - Di Slack dan Discord, jika tidak disetel maka reaksi status tetap aktif saat reaksi ack aktif. - Di Telegram, setel secara eksplisit ke `true` untuk mengaktifkan reaksi status lifecycle. + Di Slack dan Discord, jika tidak disetel maka status reactions tetap aktif ketika ack reactions aktif. + Di Telegram, set secara eksplisit ke `true` untuk mengaktifkan lifecycle status reactions. ### Debounce inbound @@ -1966,12 +1965,12 @@ Mengelompokkan pesan teks cepat dari pengirim yang sama menjadi satu giliran age } ``` -- `auto` mengontrol mode auto-TTS default: `off`, `always`, `inbound`, atau `tagged`. `/tts on|off` dapat mengoverride preferensi lokal, dan `/tts status` menampilkan status efektif. -- `summaryModel` mengoverride `agents.defaults.model.primary` untuk ringkasan otomatis. +- `auto` mengontrol mode auto-TTS default: `off`, `always`, `inbound`, atau `tagged`. `/tts on|off` dapat meng-override preferensi lokal, dan `/tts status` menampilkan status efektif. +- `summaryModel` meng-override `agents.defaults.model.primary` untuk auto-summary. - `modelOverrides` aktif secara default; `modelOverrides.allowProvider` default ke `false` (opt-in). -- API key menggunakan fallback ke `ELEVENLABS_API_KEY`/`XI_API_KEY` dan `OPENAI_API_KEY`. -- `openai.baseUrl` mengoverride endpoint OpenAI TTS. Urutan resolusi adalah konfigurasi, 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. +- API key fallback ke `ELEVENLABS_API_KEY`/`XI_API_KEY` dan `OPENAI_API_KEY`. +- `openai.baseUrl` meng-override 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 yang kompatibel dengan OpenAI dan melonggarkan validasi model/voice. --- @@ -2002,33 +2001,33 @@ 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 ke `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 direktif Talk menggunakan nama yang ramah. -- `silenceTimeoutMs` mengontrol berapa lama mode Talk menunggu setelah pengguna diam sebelum mengirim transkrip. Jika tidak disetel, tetap memakai jendela jeda default platform (`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 disetel, 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 ada dipertahankan). +Onboarding lokal default mengatur konfigurasi lokal baru ke `tools.profile: "coding"` saat tidak disetel (profil eksplisit yang sudah ada dipertahankan). -| Profil | Mencakup | -| ----------- | ------------------------------------------------------------------------------------------------------------------------------- | -| `minimal` | hanya `session_status` | +| 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 pembatasan (sama seperti tidak disetel) | +| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | +| `full` | Tanpa pembatasan (sama seperti tidak disetel) | ### Grup tool -| Grup | Tools | +| Grup | Tool | | ------------------ | ----------------------------------------------------------------------------------------------------------------------- | | `group:runtime` | `exec`, `process`, `code_execution` (`bash` diterima sebagai alias untuk `exec`) | | `group:fs` | `read`, `write`, `edit`, `apply_patch` | @@ -2045,7 +2044,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 allow/deny tool global (deny menang). Tidak peka huruf besar/kecil, mendukung wildcard `*`. Diterapkan bahkan saat sandbox Docker mati. ```json5 { @@ -2055,7 +2054,7 @@ Kebijakan allow/deny tool global (deny menang). Tidak peka huruf besar/kecil, me ### `tools.byProvider` -Membatasi tool lebih lanjut untuk provider atau model tertentu. Urutan: profil dasar → profil provider → allow/deny. +Batasi lebih lanjut tool untuk provider atau model tertentu. Urutan: profil dasar → profil provider → allow/deny. ```json5 { @@ -2088,7 +2087,7 @@ Mengontrol akses exec elevated di luar sandbox: ``` - Override per-agen (`agents.list[].tools.elevated`) hanya dapat membatasi lebih lanjut. -- `/elevated on|off|ask|full` menyimpan status per sesi; directive inline berlaku untuk satu pesan. +- `/elevated on|off|ask|full` menyimpan state per sesi; directive inline berlaku untuk satu pesan. - `exec` elevated melewati sandboxing dan menggunakan jalur escape yang dikonfigurasi (`gateway` secara default, atau `node` saat target exec adalah `node`). ### `tools.exec` @@ -2113,8 +2112,8 @@ Mengontrol akses exec elevated di luar sandbox: ### `tools.loopDetection` -Pemeriksaan keamanan loop tool **dinonaktifkan secara default**. Setel `enabled: true` untuk mengaktifkan deteksi. -Pengaturan dapat ditentukan secara global di `tools.loopDetection` dan dioverride per-agen di `agents.list[].tools.loopDetection`. +Pemeriksaan keamanan loop tool **nonaktif secara default**. Set `enabled: true` untuk mengaktifkan deteksi. +Pengaturan dapat didefinisikan secara global di `tools.loopDetection` dan dioverride per-agen di `agents.list[].tools.loopDetection`. ```json5 { @@ -2135,13 +2134,13 @@ Pengaturan dapat ditentukan secara global di `tools.loopDetection` dan dioverrid } ``` -- `historySize`: riwayat pemanggilan tool maksimum yang dipertahankan untuk analisis loop. -- `warningThreshold`: ambang pola berulang tanpa progres untuk peringatan. +- `historySize`: riwayat panggilan tool maksimum yang dipertahankan untuk analisis loop. +- `warningThreshold`: ambang pola berulang tanpa kemajuan untuk peringatan. - `criticalThreshold`: ambang berulang yang lebih tinggi untuk memblokir loop kritis. -- `globalCircuitBreakerThreshold`: ambang hard stop untuk eksekusi tanpa progres apa pun. -- `detectors.genericRepeat`: beri peringatan pada panggilan tool yang berulang dengan argumen yang sama. -- `detectors.knownPollNoProgress`: beri peringatan/blokir pada tool poll yang dikenal (`process.poll`, `command_status`, dll.). -- `detectors.pingPong`: beri peringatan/blokir pada pola pasangan bolak-balik tanpa progres. +- `globalCircuitBreakerThreshold`: ambang penghentian keras untuk run tanpa kemajuan apa pun. +- `detectors.genericRepeat`: peringatkan pada panggilan tool yang sama/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 tanpa kemajuan yang bergantian. - Jika `warningThreshold >= criticalThreshold` atau `criticalThreshold >= globalCircuitBreakerThreshold`, validasi gagal. ### `tools.web` @@ -2152,14 +2151,14 @@ Pengaturan dapat ditentukan secara global di `tools.loopDetection` dan dioverrid web: { search: { enabled: true, - apiKey: "brave_api_key", // atau env BRAVE_API_KEY + apiKey: "brave_api_key", // or BRAVE_API_KEY env maxResults: 5, timeoutSeconds: 30, cacheTtlMinutes: 15, }, fetch: { enabled: true, - provider: "firecrawl", // opsional; hilangkan untuk auto-detect + provider: "firecrawl", // optional; omit for auto-detect maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -2184,7 +2183,7 @@ Mengonfigurasi pemahaman media masuk (gambar/audio/video): media: { concurrency: 2, asyncCompletion: { - directSend: false, // opt-in: kirim musik/video async yang selesai langsung ke channel + directSend: false, // opt-in: send finished async music/video directly to the channel }, audio: { enabled: true, @@ -2212,28 +2211,28 @@ 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 +- `provider`: id provider API (`openai`, `anthropic`, `google`/`gemini`, `groq`, dll.) +- `model`: override model id - `profile` / `preferredProfile`: pemilihan profil `auth-profiles.json` **Entri CLI** (`type: "cli"`): -- `command`: executable untuk dijalankan -- `args`: argumen bertemplate (mendukung `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, dll.) +- `command`: executable yang dijalankan +- `args`: arg templat (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 menggunakan fallback ke entri berikutnya. +- Kegagalan fallback ke entri berikutnya. Auth provider mengikuti urutan standar: `auth-profiles.json` → env vars → `models.providers.*.apiKey`. -**Field async completion:** +**Field penyelesaian async:** - `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). + (jalur wake/model-delivery sesi peminta lama). @@ -2252,7 +2251,7 @@ 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 dibuat olehnya, seperti subagen). @@ -2271,9 +2270,9 @@ Catatan: - `self`: hanya kunci sesi saat ini. - `tree`: sesi saat ini + sesi yang dibuat oleh sesi saat ini (subagen). -- `agent`: sesi mana pun yang milik ID agen saat ini (dapat mencakup pengguna lain jika Anda menjalankan sesi per-pengirim di bawah ID agen yang sama). +- `agent`: sesi apa pun milik id agen saat ini (dapat mencakup pengguna lain jika Anda menjalankan sesi per-pengirim di bawah id agen yang sama). - `all`: sesi apa pun. Penargetan lintas agen tetap memerlukan `tools.agentToAgent`. -- Clamp sandbox: saat sesi saat ini berada dalam sandbox dan `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, visibilitas dipaksa ke `tree` bahkan jika `tools.sessions.visibility="all"`. +- Clamp sandbox: saat sesi saat ini disandbox dan `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, visibilitas dipaksa ke `tree` walaupun `tools.sessions.visibility="all"`. ### `tools.sessions_spawn` @@ -2284,11 +2283,11 @@ Mengontrol dukungan lampiran inline untuk `sessions_spawn`. tools: { sessions_spawn: { attachments: { - enabled: false, // opt-in: setel true untuk mengizinkan lampiran file inline - maxTotalBytes: 5242880, // total 5 MB di semua file + enabled: false, // opt-in: set true to allow inline file attachments + maxTotalBytes: 5242880, // 5 MB total across all files maxFiles: 50, maxFileBytes: 1048576, // 1 MB per file - retainOnSessionKeep: false, // pertahankan lampiran saat cleanup="keep" + retainOnSessionKeep: false, // keep attachments when cleanup="keep" }, }, }, @@ -2298,21 +2297,21 @@ Mengontrol dukungan lampiran inline untuk `sessions_spawn`. Catatan: - Lampiran hanya didukung untuk `runtime: "subagent"`. Runtime ACP menolaknya. -- File dimaterialisasi ke workspace anak di `.openclaw/attachments//` dengan `.manifest.json`. +- File dimaterialisasikan ke workspace child 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. +- Input base64 divalidasi dengan pemeriksaan alfabet/padding ketat dan guard ukuran sebelum decode. - Izin file adalah `0700` untuk direktori dan `0600` untuk file. -- Cleanup mengikuti kebijakan `cleanup`: `delete` selalu menghapus lampiran; `keep` mempertahankannya hanya saat `retainOnSessionKeep: true`. +- Pembersihan mengikuti kebijakan `cleanup`: `delete` selalu menghapus lampiran; `keep` mempertahankannya hanya jika `retainOnSessionKeep: true`. ### `tools.experimental` -Flag tool built-in eksperimental. Default nonaktif kecuali berlaku aturan auto-enable khusus runtime. +Flag tool built-in eksperimental. Default nonaktif kecuali aturan auto-enable khusus runtime berlaku. ```json5 { tools: { experimental: { - planTool: true, // aktifkan update_plan eksperimental + planTool: true, // enable experimental update_plan }, }, } @@ -2320,9 +2319,9 @@ Flag tool built-in eksperimental. Default nonaktif kecuali berlaku aturan auto-e Catatan: -- `planTool`: mengaktifkan tool terstruktur `update_plan` untuk pelacakan pekerjaan multi-langkah yang tidak sepele. -- Default: `false` untuk provider non-OpenAI. Eksekusi OpenAI dan OpenAI Codex mengaktifkannya secara otomatis saat tidak disetel; setel `false` untuk menonaktifkan auto-enable itu. -- Saat diaktifkan, system prompt juga menambahkan panduan penggunaan agar model hanya memakainya untuk pekerjaan substansial dan mempertahankan maksimal satu langkah `in_progress`. +- `planTool`: mengaktifkan tool `update_plan` terstruktur eksperimental untuk pelacakan pekerjaan multi-langkah yang tidak sepele. +- Default: `false` untuk provider non-OpenAI. Run OpenAI dan OpenAI Codex mengaktifkannya otomatis saat tidak disetel; set `false` untuk menonaktifkan auto-enable itu. +- Saat diaktifkan, system prompt juga menambahkan panduan penggunaan agar model hanya menggunakannya untuk pekerjaan substansial dan mempertahankan paling banyak satu langkah `in_progress`. ### `agents.defaults.subagents` @@ -2342,9 +2341,9 @@ Catatan: } ``` -- `model`: model default untuk sub-agen yang di-spawn. Jika dihilangkan, sub-agen mewarisi model pemanggil. -- `allowAgents`: allowlist default ID agen target untuk `sessions_spawn` saat agen peminta tidak menyetel `subagents.allowAgents` sendiri (`["*"]` = apa pun; default: agen yang sama saja). -- `runTimeoutSeconds`: timeout default (detik) untuk `sessions_spawn` saat pemanggilan tool menghilangkan `runTimeoutSeconds`. `0` berarti tanpa timeout. +- `model`: model default untuk sub-agen yang dibuat. Jika dihilangkan, sub-agen mewarisi model pemanggil. +- `allowAgents`: allowlist default id agen target untuk `sessions_spawn` saat agen peminta tidak menyetel `subagents.allowAgents` sendiri (`["*"]` = apa pun; default: hanya agen yang sama). +- `runTimeoutSeconds`: timeout default (detik) untuk `sessions_spawn` saat panggilan tool menghilangkan `runTimeoutSeconds`. `0` berarti tanpa timeout. - Kebijakan tool per-subagen: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- @@ -2381,45 +2380,45 @@ OpenClaw menggunakan katalog model built-in. Tambahkan provider kustom melalui ` ``` - Gunakan `authHeader: true` + `headers` untuk kebutuhan auth kustom. -- Override root konfigurasi agen dengan `OPENCLAW_AGENT_DIR` (atau `PI_CODING_AGENT_DIR`, alias variabel lingkungan lama). -- 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 itu tidak dikelola SecretRef dalam konteks auth-profile/config saat ini. - - Nilai `apiKey` provider yang dikelola SecretRef disegarkan dari penanda sumber (`ENV_VAR_NAME` untuk ref env, `secretref-managed` untuk ref file/exec) alih-alih menyimpan rahasia yang sudah di-resolve. - - Nilai header provider yang dikelola SecretRef disegarkan dari penanda sumber (`secretref-env:ENV_VAR_NAME` untuk ref env, `secretref-managed` untuk ref file/exec). - - `apiKey`/`baseUrl` agen yang kosong atau hilang menggunakan fallback ke `models.providers` dalam konfigurasi. - - `contextWindow`/`maxTokens` model yang cocok memakai nilai yang lebih tinggi antara konfigurasi 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. +- Override root konfigurasi agen dengan `OPENCLAW_AGENT_DIR` (atau `PI_CODING_AGENT_DIR`, alias environment variable lama). +- Precedensi penggabungan untuk provider ID yang cocok: + - Nilai `baseUrl` agen `models.json` yang tidak kosong menang. + - Nilai `apiKey` agen yang tidak kosong menang hanya bila provider itu tidak dikelola SecretRef dalam konteks konfigurasi/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 sudah 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` agen yang kosong atau hilang fallback ke `models.providers` di 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"` saat Anda ingin konfigurasi menulis ulang `models.json` sepenuhnya. - - Persistensi penanda bersifat source-authoritative: penanda ditulis dari snapshot konfigurasi sumber aktif (pra-resolusi), bukan dari nilai secret runtime yang telah di-resolve. + - Persistensi marker bersifat source-authoritative: marker ditulis dari snapshot konfigurasi sumber aktif (pra-resolusi), bukan dari nilai secret runtime yang sudah di-resolve. ### Detail field provider - `models.mode`: perilaku katalog provider (`merge` atau `replace`). -- `models.providers`: map provider kustom yang dikunci dengan ID provider. +- `models.providers`: peta provider kustom yang dikunci dengan provider id. - `models.providers.*.api`: adapter permintaan (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai`, dll). -- `models.providers.*.apiKey`: kredensial provider (utamakan SecretRef/substitusi env). +- `models.providers.*.apiKey`: kredensial provider (sebaiknya SecretRef/substitusi env). - `models.providers.*.auth`: strategi auth (`api-key`, `token`, `oauth`, `aws-sdk`). - `models.providers.*.injectNumCtxForOpenAICompat`: untuk Ollama + `openai-completions`, sisipkan `options.num_ctx` ke permintaan (default: `true`). -- `models.providers.*.authHeader`: paksa transport kredensial di header `Authorization` bila diperlukan. +- `models.providers.*.authHeader`: paksa transport kredensial di header `Authorization` saat diperlukan. - `models.providers.*.baseUrl`: base URL API upstream. - `models.providers.*.headers`: header statis tambahan untuk routing proxy/tenant. - `models.providers.*.request`: override transport untuk permintaan 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 subobjek `tls` opsional. + - `request.headers`: header tambahan (digabung dengan default provider). Nilai menerima SecretRef. + - `request.auth`: override strategi auth. Mode: `"provider-default"` (gunakan auth built-in provider), `"authorization-bearer"` (dengan `token`), `"header"` (dengan `headerName`, `value`, `prefix` opsional). + - `request.proxy`: override proxy HTTP. Mode: `"env-proxy"` (gunakan env vars `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` (semua menerima SecretRef), `serverName`, `insecureSkipVerify`. - `models.providers.*.models`: entri katalog model provider eksplisit. -- `models.providers.*.models.*.contextWindow`: metadata jendela konteks model native. +- `models.providers.*.models.*.contextWindow`: metadata context window model native. - `models.providers.*.models.*.contextTokens`: batas konteks runtime opsional. Gunakan ini saat Anda menginginkan 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 memaksa ini menjadi `false` saat runtime. `baseUrl` kosong/dihilangkan mempertahankan perilaku default OpenAI. -- `models.providers.*.models.*.compat.requiresStringContent`: petunjuk kompatibilitas opsional untuk endpoint chat kompatibel OpenAI yang hanya menerima string. Saat `true`, OpenClaw meratakan array `messages[].content` yang hanya teks menjadi string biasa sebelum mengirim permintaan. +- `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 memaksa ini menjadi `false` saat runtime. `baseUrl` kosong/tidak ada mempertahankan perilaku default OpenAI. +- `models.providers.*.models.*.compat.requiresStringContent`: petunjuk kompatibilitas opsional untuk endpoint chat string-only yang kompatibel dengan OpenAI. Saat `true`, OpenClaw meratakan array `messages[].content` teks murni menjadi string biasa sebelum mengirim permintaan. - `plugins.entries.amazon-bedrock.config.discovery`: root pengaturan auto-discovery Bedrock. -- `plugins.entries.amazon-bedrock.config.discovery.enabled`: aktifkan/nonaktifkan discovery implisit. +- `plugins.entries.amazon-bedrock.config.discovery.enabled`: aktifkan/nonaktifkan 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 yang ditargetkan. -- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: interval polling untuk refresh discovery. -- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: jendela konteks fallback untuk model yang ditemukan. +- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: interval polling untuk penyegaran discovery. +- `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 @@ -2458,7 +2457,7 @@ OpenClaw menggunakan katalog model built-in. Tambahkan provider kustom melalui ` } ``` -Gunakan `cerebras/zai-glm-4.7` untuk Cerebras; `zai/glm-4.7` untuk Z.AI langsung. +Gunakan `cerebras/zai-glm-4.7` untuk Cerebras; `zai/glm-4.7` untuk Z.AI direct. @@ -2475,7 +2474,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`. +Set `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`. @@ -2492,7 +2491,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`. +Set `ZAI_API_KEY`. `z.ai/*` dan `z-ai/*` diterima sebagai alias. 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` @@ -2537,9 +2536,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 kini mengaitkannya berdasarkan -kapabilitas endpoint alih-alih hanya ID provider built-in. +Endpoint Moonshot native mengiklankan kompatibilitas penggunaan streaming pada +transport bersama `openai-completions`, dan OpenClaw mengacu pada kapabilitas endpoint itu +bukan hanya provider id built-in. @@ -2557,11 +2556,11 @@ kapabilitas endpoint alih-alih hanya ID provider built-in. } ``` -Kompatibel Anthropic, provider built-in. Shortcut: `openclaw onboard --auth-choice kimi-code-api-key`. +Kompatibel dengan Anthropic, provider built-in. Shortcut: `openclaw onboard --auth-choice kimi-code-api-key`. - + ```json5 { @@ -2600,7 +2599,7 @@ Base URL harus menghilangkan `/v1` (klien Anthropic menambahkannya). Shortcut: ` - + ```json5 { @@ -2636,11 +2635,11 @@ Base URL harus menghilangkan `/v1` (klien Anthropic menambahkannya). Shortcut: ` } ``` -Setel `MINIMAX_API_KEY`. Shortcut: +Set `MINIMAX_API_KEY`. Shortcut: `openclaw onboard --auth-choice minimax-global-api` atau `openclaw onboard --auth-choice minimax-cn-api`. -Katalog model sekarang default hanya ke M2.7. -Pada jalur streaming yang kompatibel Anthropic, OpenClaw menonaktifkan thinking MiniMax +Katalog model default hanya ke M2.7. +Pada jalur streaming yang kompatibel dengan Anthropic, OpenClaw menonaktifkan thinking MiniMax secara default kecuali Anda secara eksplisit menyetel `thinking` sendiri. `/fast on` atau `params.fastMode: true` menulis ulang `MiniMax-M2.7` menjadi `MiniMax-M2.7-highspeed`. @@ -2649,7 +2648,7 @@ secara default kecuali Anda secara eksplisit menyetel `thinking` sendiri. `/fast -Lihat [Local Models](/id/gateway/local-models). Singkatnya: jalankan model lokal besar melalui LM Studio Responses API pada perangkat keras yang serius; pertahankan model yang di-host tetap tergabung untuk fallback. +Lihat [Local Models](/id/gateway/local-models). Singkatnya: jalankan model lokal besar melalui LM Studio Responses API pada perangkat keras serius; pertahankan model hosted tetap digabung untuk fallback. @@ -2670,7 +2669,7 @@ Lihat [Local Models](/id/gateway/local-models). Singkatnya: jalankan model lokal }, entries: { "image-lab": { - apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // atau string plaintext + apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, }, peekaboo: { enabled: true }, @@ -2680,18 +2679,18 @@ Lihat [Local Models](/id/gateway/local-models). Singkatnya: jalankan model lokal } ``` -- `allowBundled`: allowlist opsional hanya untuk skill bundled (skill managed/workspace tidak terpengaruh). -- `load.extraDirs`: root skill bersama tambahan (prioritas terendah). -- `install.preferBrew`: saat true, utamakan installer Homebrew saat `brew` +- `allowBundled`: allowlist opsional hanya untuk Skills bundled (Skills managed/workspace tidak terpengaruh). +- `load.extraDirs`: root Skills bersama tambahan (precedensi terendah). +- `install.preferBrew`: saat true, prioritaskan installer Homebrew saat `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 skill meskipun bundled/terinstal. -- `entries..apiKey`: kemudahan API key tingkat skill (saat didukung oleh skill). +- `install.nodeManager`: preferensi installer node untuk spesifikasi `metadata.openclaw.install` + (`npm` | `pnpm` | `yarn` | `bun`). +- `entries..enabled: false` menonaktifkan sebuah skill meskipun bundled/terinstal. +- `entries..apiKey`: field kenyamanan API key tingkat skill (bila didukung skill tersebut). --- -## Plugins +## Plugin ```json5 { @@ -2716,17 +2715,17 @@ 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 yang kompatibel dan bundle Claude, termasuk bundle Claude tata letak default tanpa manifest. +- Discovery menerima plugin OpenClaw native plus bundle Codex yang kompatibel dan bundle Claude, termasuk bundle Claude default-layout tanpa manifest. - **Perubahan konfigurasi memerlukan restart gateway.** - `allow`: allowlist opsional (hanya plugin yang tercantum yang dimuat). `deny` menang. -- `plugins.entries..apiKey`: field kemudahan API key tingkat plugin (saat didukung plugin). -- `plugins.entries..env`: map env var yang dicakup plugin. -- `plugins.entries..hooks.allowPromptInjection`: saat `false`, inti memblokir `before_prompt_build` dan mengabaikan field yang memutasi 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 background subagent. -- `plugins.entries..subagent.allowedModels`: allowlist opsional target kanonis `provider/model` untuk override subagent tepercaya. Gunakan `"*"` hanya jika Anda memang ingin mengizinkan model apa pun. -- `plugins.entries..config`: objek konfigurasi yang didefinisikan plugin (divalidasi oleh skema plugin OpenClaw native saat tersedia). +- `plugins.entries..apiKey`: field kenyamanan API key tingkat plugin (saat didukung plugin). +- `plugins.entries..env`: peta env var yang dicakup plugin. +- `plugins.entries..hooks.allowPromptInjection`: saat `false`, inti memblokir `before_prompt_build` dan mengabaikan field legacy `before_agent_start` yang memutasi prompt, sambil mempertahankan `modelOverride` dan `providerOverride` lama. Berlaku pada 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-run untuk run subagen latar belakang. +- `plugins.entries..subagent.allowedModels`: allowlist opsional target `provider/model` kanonis untuk override subagen tepercaya. Gunakan `"*"` hanya bila Anda memang ingin mengizinkan model apa pun. +- `plugins.entries..config`: objek konfigurasi yang ditentukan plugin (divalidasi oleh schema plugin OpenClaw native bila tersedia). - `plugins.entries.firecrawl.config.webFetch`: pengaturan provider web-fetch Firecrawl. - - `apiKey`: API key Firecrawl (menerima SecretRef). Menggunakan fallback ke `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). @@ -2735,21 +2734,21 @@ Lihat [Local Models](/id/gateway/local-models). Singkatnya: jalankan model lokal - `enabled`: aktifkan provider X Search. - `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 (`"0 3 * * *"` secara default). - - kebijakan fase dan ambang adalah detail implementasi (bukan kunci konfigurasi yang menghadap pengguna). + - `enabled`: sakelar dreaming utama (default `false`). + - `frequency`: cadence cron untuk tiap sweep dreaming penuh (`"0 3 * * *"` secara default). + - kebijakan fase dan ambang adalah detail implementasi (bukan kunci konfigurasi yang dihadapkan ke pengguna). - Konfigurasi memori lengkap ada di [Referensi konfigurasi memori](/id/reference/memory-config): - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- Plugin bundle Claude yang diaktifkan juga dapat menyumbangkan default Pi tertanam dari `settings.json`; OpenClaw menerapkannya sebagai pengaturan agen yang sudah disanitasi, bukan sebagai patch konfigurasi OpenClaw mentah. -- `plugins.slots.memory`: pilih ID plugin memori aktif, atau `"none"` untuk menonaktifkan plugin memori. -- `plugins.slots.contextEngine`: pilih ID plugin context engine aktif; default ke `"legacy"` kecuali Anda menginstal dan memilih engine lain. +- Plugin bundle Claude yang aktif juga dapat menyumbang default Pi tersemat dari `settings.json`; OpenClaw menerapkannya sebagai pengaturan agen yang disanitasi, bukan sebagai patch konfigurasi OpenClaw mentah. +- `plugins.slots.memory`: pilih id plugin memori aktif, atau `"none"` untuk menonaktifkan plugin memori. +- `plugins.slots.contextEngine`: pilih id plugin context engine aktif; default ke `"legacy"` kecuali Anda menginstal dan memilih engine lain. - `plugins.installs`: metadata instalasi yang dikelola CLI yang digunakan oleh `openclaw plugins update`. - Mencakup `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`. - - Perlakukan `plugins.installs.*` sebagai state yang dikelola; utamakan perintah CLI daripada edit manual. + - Perlakukan `plugins.installs.*` sebagai state terkelola; sebaiknya gunakan perintah CLI alih-alih edit manual. Lihat [Plugins](/id/tools/plugin). @@ -2764,8 +2763,8 @@ Lihat [Plugins](/id/tools/plugin). evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - dangerouslyAllowPrivateNetwork: true, // mode jaringan tepercaya default - // allowPrivateNetwork: true, // alias lama + dangerouslyAllowPrivateNetwork: true, // default trusted-network mode + // allowPrivateNetwork: true, // legacy alias // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, @@ -2792,26 +2791,26 @@ 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 profil CDP jarak jauh (`profiles.*.cdpUrl`) tunduk pada pemblokiran jaringan privat yang sama selama pemeriksaan reachability/discovery. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` default ke `true` saat tidak disetel (model trusted-network). +- Set `ssrfPolicy.dangerouslyAllowPrivateNetwork: false` untuk navigasi browser publik-saja yang ketat. +- Dalam mode ketat, endpoint profil CDP remote (`profiles.*.cdpUrl`) tunduk pada pemblokiran private-network yang sama selama pemeriksaan reachability/discovery. - `ssrfPolicy.allowPrivateNetwork` tetap didukung sebagai alias lama. - Dalam mode ketat, gunakan `ssrfPolicy.hostnameAllowlist` dan `ssrfPolicy.allowedHostnames` untuk pengecualian eksplisit. -- Profil jarak jauh 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) saat Anda ingin OpenClaw menemukan `/json/version`; gunakan WS(S) saat provider Anda memberi URL WebSocket DevTools langsung. -- Profil `existing-session` hanya-host dan menggunakan Chrome MCP alih-alih CDP. -- Profil `existing-session` dapat menyetel `userDataDir` untuk menargetkan profil browser berbasis Chromium tertentu - seperti Brave atau Edge. -- Profil `existing-session` mempertahankan batas route Chrome MCP saat ini: - action berbasis snapshot/ref alih-alih penargetan selector CSS, hook unggah satu-file, +- Profil `existing-session` hanya untuk host dan menggunakan Chrome MCP alih-alih CDP. +- Profil `existing-session` dapat menyetel `userDataDir` untuk menargetkan profil browser + berbasis Chromium tertentu seperti Brave atau Edge. +- Profil `existing-session` mempertahankan batas rute Chrome MCP saat ini: + aksi berbasis snapshot/ref alih-alih penargetan CSS selector, hook upload satu file, tanpa override timeout dialog, tanpa `wait --load networkidle`, dan tanpa - `responsebody`, ekspor PDF, intersepsi unduhan, atau action batch. -- Profil `openclaw` yang dikelola lokal otomatis menetapkan `cdpPort` dan `cdpUrl`; hanya - setel `cdpUrl` secara eksplisit untuk CDP jarak jauh. -- Urutan auto-detect: browser default jika berbasis Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. -- Layanan kontrol: loopback saja (port diturunkan dari `gateway.port`, default `18791`). + `responsebody`, ekspor PDF, intersepsi unduhan, atau aksi batch. +- Profil `openclaw` yang dikelola lokal menetapkan otomatis `cdpPort` dan `cdpUrl`; hanya + set `cdpUrl` secara eksplisit untuk CDP remote. +- Urutan auto-detect: browser default bila berbasis Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. +- Layanan kontrol: 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). @@ -2825,14 +2824,14 @@ Lihat [Plugins](/id/tools/plugin). seamColor: "#FF4500", assistant: { name: "OpenClaw", - avatar: "CB", // emoji, teks singkat, URL gambar, atau data URI + avatar: "CB", // emoji, short text, image URL, or data URI }, }, } ``` -- `seamColor`: warna aksen untuk chrome UI aplikasi native (warna gelembung Talk Mode, dll.). -- `assistant`: override identitas Control UI. Menggunakan fallback ke identitas agen aktif. +- `seamColor`: warna aksen untuk chrome UI aplikasi native (warna bubble Talk Mode, dll.). +- `assistant`: override identitas UI Kontrol. Fallback ke identitas agen aktif. --- @@ -2847,8 +2846,8 @@ Lihat [Plugins](/id/tools/plugin). auth: { mode: "token", // none | token | password | trusted-proxy token: "your-token", - // password: "your-password", // atau OPENCLAW_GATEWAY_PASSWORD - // trustedProxy: { userHeader: "x-forwarded-user" }, // untuk mode=trusted-proxy; lihat /gateway/trusted-proxy-auth + // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD + // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth allowTailscale: true, rateLimit: { maxAttempts: 10, @@ -2865,8 +2864,8 @@ Lihat [Plugins](/id/tools/plugin). enabled: true, basePath: "/openclaw", // root: "dist/control-ui", - // allowedOrigins: ["https://control.example.com"], // wajib untuk Control UI non-loopback - // dangerouslyAllowHostHeaderOriginFallback: false, // mode fallback origin Host-header yang berbahaya + // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI + // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -2877,12 +2876,12 @@ Lihat [Plugins](/id/tools/plugin). // password: "your-password", }, trustedProxies: ["10.0.0.1"], - // Opsional. Default false. + // Optional. Default false. allowRealIpFallback: false, tools: { - // Deny HTTP /tools/invoke tambahan + // Additional /tools/invoke HTTP denies deny: ["browser"], - // Hapus tool dari daftar deny HTTP default + // Remove tools from the default HTTP deny list allow: ["gateway"], }, push: { @@ -2899,32 +2898,37 @@ Lihat [Plugins](/id/tools/plugin). -- `mode`: `local` (jalankan gateway) atau `remote` (terhubung ke gateway jarak jauh). Gateway menolak start kecuali `local`. -- `port`: port tunggal multipleks untuk WS + HTTP. Prioritas: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. +- `mode`: `local` (jalankan gateway) atau `remote` (hubungkan ke gateway jarak jauh). Gateway menolak start kecuali `local`. +- `port`: satu port multipleks untuk WS + HTTP. Precedensi: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. - `bind`: `auto`, `loopback` (default), `lan` (`0.0.0.0`), `tailnet` (hanya IP Tailscale), atau `custom`. - **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 `loopback` default mendengarkan di `127.0.0.1` di dalam container. Dengan jaringan bridge Docker (`-p 18789:18789`), lalu lintas datang di `eth0`, jadi gateway tidak dapat dijangkau. Gunakan `--network host`, atau setel `bind: "lan"` (atau `bind: "custom"` dengan `customBindHost: "0.0.0.0"`) untuk mendengarkan di semua antarmuka. -- **Auth**: wajib secara default. Bind non-loopback memerlukan auth gateway. Dalam praktiknya itu berarti token/password bersama atau reverse proxy berbasis identitas dengan `gateway.auth.mode: "trusted-proxy"`. Wizard onboarding menghasilkan token secara default. -- Jika `gateway.auth.token` dan `gateway.auth.password` sama-sama dikonfigurasi (termasuk SecretRef), setel `gateway.auth.mode` secara eksplisit ke `token` atau `password`. Alur startup dan instalasi/perbaikan layanan gagal saat keduanya dikonfigurasi dan mode tidak disetel. +- **Catatan Docker**: bind default `loopback` mendengarkan pada `127.0.0.1` di dalam kontainer. Dengan jaringan bridge Docker (`-p 18789:18789`), trafik tiba di `eth0`, sehingga gateway tidak dapat dijangkau. Gunakan `--network host`, atau set `bind: "lan"` (atau `bind: "custom"` dengan `customBindHost: "0.0.0.0"`) untuk mendengarkan di semua interface. +- **Auth**: diwajibkan secara default. Bind non-loopback memerlukan auth gateway. Dalam praktiknya ini berarti token/password bersama atau reverse proxy yang sadar identitas dengan `gateway.auth.mode: "trusted-proxy"`. Wizard onboarding menghasilkan token secara default. +- Jika `gateway.auth.token` dan `gateway.auth.password` sama-sama dikonfigurasi (termasuk SecretRef), set `gateway.auth.mode` secara eksplisit ke `token` atau `password`. Startup dan alur install/perbaikan layanan gagal bila 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 berbasis 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 di host yang sama tidak memenuhi auth trusted-proxy. -- `gateway.auth.allowTailscale`: saat `true`, header identitas Tailscale Serve dapat memenuhi auth Control UI/WebSocket (diverifikasi melalui `tailscale whois`). Endpoint API HTTP **tidak** menggunakan auth header Tailscale itu; 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 kegagalan auth opsional. Berlaku per IP klien dan per cakupan auth (shared-secret dan device-token dilacak secara independen). Upaya yang diblokir mengembalikan `429` + `Retry-After`. - - Pada jalur async Tailscale Serve Control UI, upaya gagal untuk `{scope, clientIp}` yang sama diserialisasi sebelum penulisan kegagalan. Oleh karena itu, upaya buruk bersamaan dari klien yang sama dapat memicu limiter pada permintaan kedua alih-alih keduanya lolos sebagai mismatch biasa. - - `gateway.auth.rateLimit.exemptLoopback` default ke `true`; setel `false` saat Anda sengaja ingin lalu lintas localhost juga terkena rate limit (untuk setup pengujian atau deployment proxy yang ketat). +- `gateway.auth.mode: "trusted-proxy"`: delegasikan auth ke reverse proxy yang 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 UI Kontrol/WebSocket (diverifikasi via `tailscale whois`). Endpoint HTTP API **tidak** menggunakan auth header Tailscale itu; 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 gagal-auth opsional. Berlaku per IP klien dan per scope auth (shared-secret dan device-token dilacak secara independen). Upaya yang diblokir mengembalikan `429` + `Retry-After`. + - Pada jalur UI Kontrol async Tailscale Serve, upaya gagal untuk `{scope, clientIp}` yang sama diserialisasi sebelum penulisan kegagalan. Upaya buruk serentak dari klien yang sama karena itu dapat memicu limiter pada permintaan kedua alih-alih keduanya lolos begitu saja sebagai mismatch biasa. + - `gateway.auth.rateLimit.exemptLoopback` default ke `true`; set `false` bila Anda sengaja ingin trafik localhost juga terkena rate-limit (untuk setup pengujian atau deployment proxy ketat). - Upaya auth WS asal browser selalu dibatasi dengan pengecualian loopback dinonaktifkan (pertahanan berlapis terhadap brute force localhost berbasis browser). -- Pada loopback, lockout asal-browser itu diisolasi per nilai `Origin` +- Pada loopback, lockout asal browser itu 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 Host-header untuk deployment yang sengaja bergantung pada kebijakan origin Host-header. -- `remote.transport`: `ssh` (default) atau `direct` (ws/wss). Untuk `direct`, `remote.url` harus berupa `ws://` atau `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: override darurat sisi klien yang mengizinkan plaintext `ws://` ke IP jaringan privat tepercaya; default tetap hanya loopback untuk plaintext. -- `gateway.remote.token` / `.password` adalah field kredensial klien jarak jauh. 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 registrasi berbasis relay ke gateway. URL ini harus cocok dengan URL relay yang dikompilasi ke build iOS. + mengunci origin lain. +- `tailscale.mode`: `serve` (hanya tailnet, loopback bind) atau `funnel` (publik, memerlukan auth). +- `controlUi.allowedOrigins`: allowlist browser-origin eksplisit untuk koneksi WebSocket Gateway. Diperlukan saat klien browser diharapkan berasal dari origin non-loopback. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: mode berbahaya yang mengaktifkan fallback origin berbasis Host-header untuk deployment yang sengaja bergantung pada kebijakan origin Host-header. +- `remote.transport`: `ssh` (default) atau `direct` (ws/wss). Untuk `direct`, `remote.url` harus `ws://` atau `wss://`. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: override break-glass sisi klien yang mengizinkan `ws://` plaintext ke IP private-network tepercaya; default tetap loopback-only untuk plaintext. +- `gateway.remote.token` / `.password` adalah field kredensial remote-client. Field ini tidak mengonfigurasi auth gateway dengan sendirinya. +- `gateway.push.apns.relay.baseUrl`: base HTTPS URL untuk relay APNs eksternal yang digunakan build iOS official/TestFlight setelah mereka mempublikasikan 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 dipasangkan mengambil `gateway.identity.get`, menyertakan identitas itu dalam registrasi relay, dan meneruskan izin kirim yang dicakup registrasi ke gateway. Gateway lain tidak dapat menggunakan ulang registrasi tersimpan itu. +- Registrasi berbasis relay didelegasikan ke identitas gateway tertentu. Aplikasi iOS yang dipasangkan mengambil `gateway.identity.get`, menyertakan identitas itu dalam registrasi relay, dan meneruskan grant pengiriman yang dibatasi registrasi ke gateway. Gateway lain tidak dapat menggunakan ulang registrasi tersimpan itu. - `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 ` \ No newline at end of file +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: escape hatch hanya untuk pengembangan bagi URL relay HTTP loopback. URL relay produksi sebaiknya tetap HTTPS. +- `gateway.channelHealthCheckMinutes`: interval pemantau kesehatan channel dalam menit. Set `0` untuk menonaktifkan restart health-monitor secara global. Default: `5`. +- `gateway.channelStaleEventThresholdMinutes`: ambang stale-socket dalam menit. Pertahankan 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, ini mengalahkan override tingkat channel. +- Jalur panggilan gateway \ No newline at end of file diff --git a/docs/id/gateway/doctor.md b/docs/id/gateway/doctor.md index 103a29ed8..4415e3dd4 100644 --- a/docs/id/gateway/doctor.md +++ b/docs/id/gateway/doctor.md @@ -1,14 +1,14 @@ --- read_when: - Menambahkan atau mengubah migrasi doctor - - Memperkenalkan perubahan konfigurasi yang bersifat breaking + - Memperkenalkan perubahan konfigurasi yang breaking summary: 'Perintah Doctor: pemeriksaan kesehatan, migrasi konfigurasi, dan langkah perbaikan' title: Doctor x-i18n: - generated_at: "2026-04-08T02:15:14Z" + generated_at: "2026-04-09T01:28:58Z" model: gpt-5.4 provider: openai - source_hash: 3761a222d9db7088f78215575fa84e5896794ad701aa716e8bf9039a4424dca6 + source_hash: 75d321bd1ad0e16c29f2382e249c51edfc3a8d33b55bdceea39e7dbcd4901fce source_path: gateway/doctor.md workflow: 15 --- @@ -16,7 +16,8 @@ x-i18n: # Doctor `openclaw doctor` adalah alat perbaikan + migrasi untuk OpenClaw. Alat ini memperbaiki -config/status yang usang, memeriksa kesehatan, dan memberikan langkah perbaikan yang dapat ditindaklanjuti. +konfigurasi/status yang usang, memeriksa kesehatan, dan menyediakan langkah +perbaikan yang dapat ditindaklanjuti. ## Mulai cepat @@ -36,20 +37,20 @@ Terima default tanpa prompt (termasuk langkah perbaikan restart/layanan/sandbox openclaw doctor --repair ``` -Terapkan perbaikan yang direkomendasikan tanpa prompt (perbaikan + restart jika aman). +Terapkan perbaikan yang direkomendasikan tanpa prompt (perbaikan + restart bila aman). ```bash openclaw doctor --repair --force ``` -Terapkan juga perbaikan agresif (menimpa config supervisor kustom). +Terapkan juga perbaikan agresif (menimpa konfigurasi supervisor kustom). ```bash openclaw doctor --non-interactive ``` -Jalankan tanpa prompt dan hanya terapkan migrasi yang aman (normalisasi config + pemindahan state di disk). Melewati tindakan restart/layanan/sandbox yang memerlukan konfirmasi manusia. -Migrasi state lama berjalan otomatis saat terdeteksi. +Jalankan tanpa prompt dan hanya terapkan migrasi yang aman (normalisasi konfigurasi + pemindahan status di disk). Melewati tindakan restart/layanan/sandbox yang memerlukan konfirmasi manusia. +Migrasi status lama berjalan otomatis saat terdeteksi. ```bash openclaw doctor --deep @@ -57,7 +58,7 @@ openclaw doctor --deep Pindai layanan sistem untuk instalasi gateway tambahan (launchd/systemd/schtasks). -Jika Anda ingin meninjau perubahan sebelum menulis, buka dulu file config: +Jika Anda ingin meninjau perubahan sebelum menulis, buka file konfigurasi terlebih dahulu: ```bash cat ~/.openclaw/openclaw.json @@ -65,73 +66,107 @@ cat ~/.openclaw/openclaw.json ## Apa yang dilakukan (ringkasan) -- Pembaruan pra-penerbangan opsional untuk instalasi git (hanya interaktif). -- Pemeriksaan kebaruan protokol UI (membangun ulang Control UI ketika skema protokol lebih baru). +- Pembaruan pre-flight opsional untuk instalasi git (hanya interaktif). +- Pemeriksaan kesegaran protokol UI (membangun ulang Control UI bila skema protokol lebih baru). - Pemeriksaan kesehatan + prompt restart. - Ringkasan status Skills (eligible/missing/blocked) dan status plugin. -- Normalisasi config untuk nilai lama. -- Migrasi config Talk dari field datar lama `talk.*` ke `talk.provider` + `talk.providers.`. -- Pemeriksaan migrasi browser untuk config ekstensi Chrome lama dan kesiapan Chrome MCP. +- Normalisasi konfigurasi untuk nilai lama. +- Migrasi konfigurasi Talk dari field datar lama `talk.*` ke `talk.provider` + `talk.providers.`. +- Pemeriksaan migrasi browser untuk konfigurasi ekstensi Chrome lama dan kesiapan Chrome MCP. - Peringatan override provider OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). -- Peringatan shadowing OAuth Codex (`models.providers.openai-codex`). -- Pemeriksaan prasyarat TLS OAuth untuk profil OAuth OpenAI Codex. -- Migrasi state lama di disk (sessions/agent dir/auth WhatsApp). -- Migrasi key kontrak manifest plugin lama (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). -- Migrasi penyimpanan cron lama (`jobId`, `schedule.cron`, field delivery/payload tingkat atas, payload `provider`, job fallback webhook sederhana `notify: true`). +- Peringatan shadowing Codex OAuth (`models.providers.openai-codex`). +- Pemeriksaan prasyarat OAuth TLS untuk profil OpenAI Codex OAuth. +- Migrasi status lama di disk (sesi/dir agen/auth WhatsApp). +- Migrasi kunci kontrak manifest plugin lama (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). +- Migrasi penyimpanan cron lama (`jobId`, `schedule.cron`, field delivery/payload tingkat atas, payload `provider`, pekerjaan fallback webhook `notify: true` sederhana). - Inspeksi file lock sesi dan pembersihan lock usang. -- Pemeriksaan integritas state dan izin akses (sessions, transcript, state dir). -- Pemeriksaan izin file config (chmod 600) saat berjalan secara lokal. +- Pemeriksaan integritas dan izin status (sessions, transcripts, state dir). +- Pemeriksaan izin file konfigurasi (chmod 600) saat berjalan secara lokal. - Kesehatan auth model: memeriksa kedaluwarsa OAuth, dapat me-refresh token yang akan kedaluwarsa, dan melaporkan status cooldown/nonaktif profil auth. -- Deteksi direktori workspace tambahan (`~/openclaw`). +- Deteksi dir workspace tambahan (`~/openclaw`). - Perbaikan image sandbox saat sandboxing diaktifkan. - Migrasi layanan lama dan deteksi gateway tambahan. -- Migrasi state lama channel Matrix (dalam mode `--fix` / `--repair`). -- Pemeriksaan runtime gateway (layanan terinstal tetapi tidak berjalan; label launchd yang di-cache). -- Peringatan status channel (diprobe dari gateway yang sedang berjalan). -- Audit config supervisor (launchd/systemd/schtasks) dengan perbaikan opsional. -- Pemeriksaan praktik terbaik runtime gateway (Node vs Bun, path version manager). +- Migrasi status lama kanal Matrix (dalam mode `--fix` / `--repair`). +- Pemeriksaan runtime gateway (layanan terpasang tetapi tidak berjalan; label launchd yang di-cache). +- Peringatan status kanal (diprobe dari gateway yang berjalan). +- Audit konfigurasi supervisor (launchd/systemd/schtasks) dengan perbaikan opsional. +- Pemeriksaan best practice runtime gateway (Node vs Bun, path version manager). - Diagnostik benturan port gateway (default `18789`). -- Peringatan keamanan untuk kebijakan DM yang terbuka. -- Pemeriksaan auth gateway untuk mode token lokal (menawarkan pembuatan token saat tidak ada sumber token; tidak menimpa config token SecretRef). -- Pemeriksaan `linger` systemd di Linux. +- Peringatan keamanan untuk kebijakan DM terbuka. +- Pemeriksaan auth gateway untuk mode token lokal (menawarkan pembuatan token saat tidak ada sumber token; tidak menimpa konfigurasi token SecretRef). +- Pemeriksaan linger systemd di Linux. - Pemeriksaan ukuran file bootstrap workspace (peringatan pemotongan/hampir batas untuk file konteks). - Pemeriksaan status shell completion dan auto-install/upgrade. -- Pemeriksaan kesiapan provider embedding memory search (model lokal, API key jarak jauh, atau biner QMD). +- Pemeriksaan kesiapan provider embedding memory search (model lokal, kunci API jarak jauh, atau biner QMD). - Pemeriksaan instalasi sumber (ketidakcocokan workspace pnpm, aset UI hilang, biner tsx hilang). -- Menulis config yang diperbarui + metadata wizard. +- Menulis konfigurasi yang diperbarui + metadata wizard. -## Perilaku rinci dan alasannya +## Backfill dan reset UI Dreams + +Scene Dreams di Control UI mencakup tindakan **Backfill**, **Reset**, dan **Clear Grounded** +untuk alur grounded dreaming. Tindakan ini menggunakan metode RPC +bergaya gateway doctor, tetapi **bukan** bagian dari perbaikan/migrasi CLI +`openclaw doctor`. + +Yang dilakukan: + +- **Backfill** memindai file `memory/YYYY-MM-DD.md` historis di + workspace aktif, menjalankan pass diary REM grounded, dan menulis entri + backfill yang dapat dibalik ke `DREAMS.md`. +- **Reset** hanya menghapus entri diary backfill bertanda tersebut dari `DREAMS.md`. +- **Clear Grounded** hanya menghapus entri jangka pendek staged khusus grounded yang + berasal dari replay historis dan belum mengakumulasi recall live atau dukungan + harian. + +Yang **tidak** dilakukan dengan sendirinya: + +- tindakan tersebut tidak mengedit `MEMORY.md` +- tindakan tersebut tidak menjalankan migrasi doctor penuh +- tindakan tersebut tidak otomatis men-stage kandidat grounded ke dalam penyimpanan + promosi jangka pendek live kecuali Anda secara eksplisit menjalankan path CLI staged terlebih dahulu + +Jika Anda ingin replay historis grounded memengaruhi lane deep promotion +normal, gunakan alur CLI berikut: + +```bash +openclaw memory rem-backfill --path ./memory --stage-short-term +``` + +Perintah itu men-stage kandidat durable grounded ke penyimpanan dreaming jangka pendek sambil +tetap menjadikan `DREAMS.md` sebagai permukaan peninjauan. + +## Perilaku dan alasan terperinci ### 0) Pembaruan opsional (instalasi git) -Jika ini adalah checkout git dan doctor berjalan secara interaktif, doctor akan menawarkan -untuk memperbarui (fetch/rebase/build) sebelum menjalankan doctor. +Jika ini adalah checkout git dan doctor berjalan secara interaktif, doctor menawarkan untuk +memperbarui (fetch/rebase/build) sebelum menjalankan doctor. -### 1) Normalisasi config +### 1) Normalisasi konfigurasi -Jika config berisi bentuk nilai lama (misalnya `messages.ackReaction` -tanpa override spesifik channel), doctor menormalkannya ke skema +Jika konfigurasi berisi bentuk nilai lama (misalnya `messages.ackReaction` +tanpa override spesifik kanal), doctor menormalisasikannya ke dalam skema saat ini. -Itu termasuk field datar Talk lama. Config Talk publik saat ini adalah +Itu termasuk field datar Talk lama. Konfigurasi Talk publik saat ini adalah `talk.provider` + `talk.providers.`. Doctor menulis ulang bentuk lama `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` ke dalam peta provider. -### 2) Migrasi key config lama +### 2) Migrasi kunci konfigurasi lama -Saat config berisi key yang sudah tidak digunakan lagi, perintah lain akan menolak berjalan dan meminta -Anda untuk menjalankan `openclaw doctor`. +Saat konfigurasi berisi kunci yang sudah deprecated, perintah lain menolak berjalan dan meminta +Anda menjalankan `openclaw doctor`. Doctor akan: -- Menjelaskan key lama mana yang ditemukan. +- Menjelaskan kunci lama mana yang ditemukan. - Menampilkan migrasi yang diterapkannya. - Menulis ulang `~/.openclaw/openclaw.json` dengan skema yang diperbarui. Gateway juga otomatis menjalankan migrasi doctor saat startup ketika mendeteksi -format config lama, sehingga config usang diperbaiki tanpa intervensi manual. -Migrasi penyimpanan job cron ditangani oleh `openclaw doctor --fix`. +format konfigurasi lama, sehingga konfigurasi usang diperbaiki tanpa intervensi manual. +Migrasi penyimpanan pekerjaan cron ditangani oleh `openclaw doctor --fix`. Migrasi saat ini: @@ -155,7 +190,7 @@ Migrasi saat ini: - `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*` - `bindings[].match.accountID` → `bindings[].match.accountId` -- Untuk channel dengan `accounts` bernama tetapi masih memiliki nilai channel tingkat atas single-account, pindahkan nilai dengan cakupan akun tersebut ke akun yang dipromosikan yang dipilih untuk channel itu (`accounts.default` untuk sebagian besar channel; Matrix dapat mempertahankan target bernama/default yang cocok yang sudah ada) +- Untuk kanal dengan `accounts` bernama tetapi masih memiliki nilai kanal tingkat atas akun tunggal, pindahkan nilai yang dicakup akun tersebut ke akun yang dipromosikan dan dipilih untuk kanal itu (`accounts.default` untuk sebagian besar kanal; Matrix dapat mempertahankan target bernama/default yang sudah cocok) - `identity` → `agents.list[].identity` - `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents) - `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` @@ -164,108 +199,108 @@ Migrasi saat ini: - `browser.profiles.*.driver: "extension"` → `"existing-session"` - hapus `browser.relayBindHost` (pengaturan relay ekstensi lama) -Peringatan doctor juga mencakup panduan default akun untuk channel multi-akun: +Peringatan doctor juga mencakup panduan account-default untuk kanal multi-akun: -- Jika dua atau lebih entri `channels..accounts` dikonfigurasi tanpa `channels..defaultAccount` atau `accounts.default`, doctor memperingatkan bahwa routing fallback dapat memilih akun yang tidak diharapkan. -- Jika `channels..defaultAccount` disetel ke ID akun yang tidak dikenal, doctor memperingatkan dan mencantumkan ID akun yang dikonfigurasi. +- Jika dua atau lebih entri `channels..accounts` dikonfigurasi tanpa `channels..defaultAccount` atau `accounts.default`, doctor memperingatkan bahwa fallback routing dapat memilih akun yang tidak terduga. +- Jika `channels..defaultAccount` diatur ke ID akun yang tidak dikenal, doctor memperingatkan dan mencantumkan ID akun yang dikonfigurasi. ### 2b) Override provider OpenCode Jika Anda menambahkan `models.providers.opencode`, `opencode-zen`, atau `opencode-go` secara manual, itu akan menimpa katalog OpenCode bawaan dari `@mariozechner/pi-ai`. -Hal itu dapat memaksa model ke API yang salah atau membuat biaya menjadi nol. Doctor memperingatkan agar Anda -dapat menghapus override tersebut dan memulihkan routing API + biaya per model. +Hal itu dapat memaksa model ke API yang salah atau men-nol-kan biaya. Doctor memperingatkan agar Anda +dapat menghapus override dan memulihkan perutean API + biaya per model. ### 2c) Migrasi browser dan kesiapan Chrome MCP -Jika config browser Anda masih menunjuk ke jalur ekstensi Chrome yang sudah dihapus, doctor -menormalkannya ke model attach Chrome MCP lokal-host saat ini: +Jika konfigurasi browser Anda masih menunjuk ke path ekstensi Chrome yang sudah dihapus, doctor +menormalisasikannya ke model attach Chrome MCP host-lokal saat ini: - `browser.profiles.*.driver: "extension"` menjadi `"existing-session"` - `browser.relayBindHost` dihapus -Doctor juga mengaudit jalur Chrome MCP lokal-host saat Anda menggunakan `defaultProfile: +Doctor juga mengaudit path Chrome MCP host-lokal saat Anda menggunakan `defaultProfile: "user"` atau profil `existing-session` yang dikonfigurasi: - memeriksa apakah Google Chrome terinstal pada host yang sama untuk profil auto-connect default -- memeriksa versi Chrome yang terdeteksi dan memperingatkan jika di bawah Chrome 144 +- memeriksa versi Chrome yang terdeteksi dan memperingatkan bila di bawah Chrome 144 - mengingatkan Anda untuk mengaktifkan remote debugging di halaman inspect browser (misalnya `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`, atau `edge://inspect/#remote-debugging`) -Doctor tidak dapat mengaktifkan pengaturan sisi Chrome untuk Anda. Chrome MCP lokal-host +Doctor tidak dapat mengaktifkan pengaturan sisi Chrome untuk Anda. Chrome MCP host-lokal tetap memerlukan: - browser berbasis Chromium 144+ pada host gateway/node - browser berjalan secara lokal -- remote debugging diaktifkan pada browser tersebut +- remote debugging diaktifkan di browser tersebut - menyetujui prompt persetujuan attach pertama di browser Kesiapan di sini hanya tentang prasyarat attach lokal. Existing-session mempertahankan -batas rute Chrome MCP saat ini; rute lanjutan seperti `responsebody`, ekspor PDF, -intersepsi unduhan, dan tindakan batch tetap memerlukan browser terkelola +batas route Chrome MCP saat ini; route lanjutan seperti `responsebody`, ekspor PDF, +intersepsi unduhan, dan tindakan batch tetap memerlukan browser yang dikelola atau profil CDP mentah. Pemeriksaan ini **tidak** berlaku untuk Docker, sandbox, remote-browser, atau alur -headless lainnya. Alur tersebut tetap menggunakan CDP mentah. +headless lainnya. Semua itu tetap menggunakan CDP mentah. -### 2d) Prasyarat TLS OAuth +### 2d) Prasyarat OAuth TLS -Saat profil OAuth OpenAI Codex dikonfigurasi, doctor mem-probe endpoint otorisasi OpenAI -untuk memverifikasi bahwa stack TLS Node/OpenSSL lokal dapat +Saat profil OpenAI Codex OAuth dikonfigurasi, doctor mem-probe endpoint +otorisasi OpenAI untuk memverifikasi bahwa stack TLS Node/OpenSSL lokal dapat memvalidasi rantai sertifikat. Jika probe gagal dengan kesalahan sertifikat (misalnya -`UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, sertifikat kedaluwarsa, atau sertifikat self-signed), +`UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, sertifikat kedaluwarsa, atau self-signed cert), doctor mencetak panduan perbaikan spesifik platform. Di macOS dengan Homebrew Node, -perbaikannya biasanya `brew postinstall ca-certificates`. Dengan `--deep`, probe dijalankan +perbaikannya biasanya `brew postinstall ca-certificates`. Dengan `--deep`, probe berjalan bahkan jika gateway sehat. -### 2c) Override provider OAuth Codex +### 2c) Override provider Codex OAuth Jika sebelumnya Anda menambahkan pengaturan transport OpenAI lama di bawah -`models.providers.openai-codex`, pengaturan tersebut dapat membayangi jalur -provider OAuth Codex bawaan yang digunakan rilis lebih baru secara otomatis. Doctor memperingatkan saat melihat -pengaturan transport lama tersebut bersamaan dengan OAuth Codex agar Anda dapat menghapus atau menulis ulang +`models.providers.openai-codex`, pengaturan itu dapat membayangi path provider Codex OAuth +bawaan yang digunakan otomatis oleh rilis yang lebih baru. Doctor memperingatkan saat melihat +pengaturan transport lama tersebut bersama Codex OAuth agar Anda dapat menghapus atau menulis ulang override transport usang dan mendapatkan kembali perilaku routing/fallback bawaan. -Proxy kustom dan override header-only tetap didukung dan tidak +Proxy kustom dan override hanya-header tetap didukung dan tidak memicu peringatan ini. -### 3) Migrasi state lama (tata letak disk) +### 3) Migrasi status lama (layout disk) -Doctor dapat memigrasikan tata letak lama di disk ke struktur saat ini: +Doctor dapat memigrasikan layout lama di disk ke struktur saat ini: -- Penyimpanan sesi + transcript: +- Penyimpanan sesi + transkrip: - dari `~/.openclaw/sessions/` ke `~/.openclaw/agents//sessions/` -- Direktori agent: +- Dir agen: - dari `~/.openclaw/agent/` ke `~/.openclaw/agents//agent/` -- State auth WhatsApp (Baileys): +- Status auth WhatsApp (Baileys): - dari `~/.openclaw/credentials/*.json` lama (kecuali `oauth.json`) - ke `~/.openclaw/credentials/whatsapp//...` (ID akun default: `default`) Migrasi ini bersifat best-effort dan idempoten; doctor akan mengeluarkan peringatan saat -masih menyisakan folder lama sebagai cadangan. Gateway/CLI juga memigrasikan otomatis -sesi lama + direktori agent saat startup sehingga riwayat/auth/model berada di -jalur per-agent tanpa perlu menjalankan doctor secara manual. Auth WhatsApp sengaja hanya -dimigrasikan melalui `openclaw doctor`. Normalisasi Talk provider/peta provider kini -membandingkan dengan kesetaraan struktural, sehingga perbedaan urutan key saja tidak lagi memicu -perubahan no-op `doctor --fix` yang berulang. +meninggalkan folder lama sebagai cadangan. Gateway/CLI juga memigrasikan otomatis +sesi lama + dir agen saat startup sehingga riwayat/auth/model berada di +path per-agen tanpa perlu menjalankan doctor secara manual. Auth WhatsApp sengaja hanya +dimigrasikan melalui `openclaw doctor`. Normalisasi provider/peta provider Talk kini +membandingkan berdasarkan kesetaraan struktural, sehingga perbedaan urutan kunci saja tidak lagi +memicu perubahan no-op `doctor --fix` yang berulang. ### 3a) Migrasi manifest plugin lama -Doctor memindai semua manifest plugin yang terinstal untuk key kapabilitas tingkat atas yang sudah usang -(`speechProviders`, `realtimeTranscriptionProviders`, +Doctor memindai semua manifest plugin yang terinstal untuk kunci kapabilitas tingkat atas +yang sudah deprecated (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Saat ditemukan, doctor menawarkan untuk memindahkannya ke objek `contracts` -dan menulis ulang file manifest secara langsung. Migrasi ini idempoten; -jika key `contracts` sudah memiliki nilai yang sama, key lama akan dihapus +dan menulis ulang file manifest di tempat. Migrasi ini idempoten; +jika kunci `contracts` sudah memiliki nilai yang sama, kunci lama dihapus tanpa menduplikasi data. ### 3b) Migrasi penyimpanan cron lama -Doctor juga memeriksa penyimpanan job cron (`~/.openclaw/cron/jobs.json` secara default, -atau `cron.store` bila dioverride) untuk bentuk job lama yang masih -diterima scheduler demi kompatibilitas. +Doctor juga memeriksa penyimpanan pekerjaan cron (`~/.openclaw/cron/jobs.json` secara default, +atau `cron.store` jika di-override) untuk bentuk pekerjaan lama yang masih diterima +scheduler demi kompatibilitas. Pembersihan cron saat ini mencakup: @@ -273,76 +308,82 @@ Pembersihan cron saat ini mencakup: - `schedule.cron` → `schedule.expr` - field payload tingkat atas (`message`, `model`, `thinking`, ...) → `payload` - field delivery tingkat atas (`deliver`, `channel`, `to`, `provider`, ...) → `delivery` -- alias delivery `provider` payload → `delivery.channel` yang eksplisit -- job fallback webhook lama sederhana `notify: true` → `delivery.mode="webhook"` yang eksplisit dengan `delivery.to=cron.webhook` +- alias delivery `provider` pada payload → `delivery.channel` eksplisit +- pekerjaan fallback webhook lama `notify: true` sederhana → `delivery.mode="webhook"` eksplisit dengan `delivery.to=cron.webhook` -Doctor hanya memigrasikan otomatis job `notify: true` bila dapat dilakukan tanpa -mengubah perilaku. Jika sebuah job menggabungkan fallback notify lama dengan mode -delivery non-webhook yang sudah ada, doctor akan memperingatkan dan membiarkan job itu untuk ditinjau manual. +Doctor hanya otomatis memigrasikan pekerjaan `notify: true` bila hal itu dapat dilakukan tanpa +mengubah perilaku. Jika suatu pekerjaan menggabungkan fallback notify lama dengan mode +delivery non-webhook yang sudah ada, doctor memperingatkan dan membiarkan pekerjaan tersebut untuk ditinjau manual. ### 3c) Pembersihan lock sesi -Doctor memindai setiap direktori sesi agent untuk file write-lock usang — file yang tertinggal -ketika sebuah sesi berakhir secara abnormal. Untuk setiap file lock yang ditemukan, doctor melaporkan: -path, PID, apakah PID masih hidup, usia lock, dan apakah -dianggap usang (PID mati atau lebih lama dari 30 menit). Dalam mode `--fix` / `--repair` +Doctor memindai setiap direktori sesi agen untuk file write-lock usang — file yang tertinggal +saat suatu sesi keluar secara abnormal. Untuk setiap file lock yang ditemukan, doctor melaporkan: +path, PID, apakah PID masih hidup, usia lock, dan apakah lock tersebut +dianggap usang (PID mati atau lebih tua dari 30 menit). Dalam mode `--fix` / `--repair` doctor menghapus file lock usang secara otomatis; jika tidak, doctor mencetak catatan dan menginstruksikan Anda untuk menjalankan ulang dengan `--fix`. -### 4) Pemeriksaan integritas state (persistensi sesi, routing, dan keamanan) +### 4) Pemeriksaan integritas status (persistensi sesi, routing, dan keamanan) -Direktori state adalah pusat operasional. Jika hilang, Anda akan kehilangan -sesi, kredensial, log, dan config (kecuali jika Anda memiliki cadangan di tempat lain). +Direktori status adalah batang otak operasional. Jika direktori ini hilang, Anda akan kehilangan +sesi, kredensial, log, dan konfigurasi (kecuali Anda memiliki cadangan di tempat lain). Doctor memeriksa: -- **Direktori state hilang**: memperingatkan tentang kehilangan state yang katastrofik, meminta untuk membuat ulang +- **State dir hilang**: memperingatkan kehilangan status yang katastrofik, meminta untuk membuat ulang direktori, dan mengingatkan bahwa doctor tidak dapat memulihkan data yang hilang. -- **Izin direktori state**: memverifikasi dapat ditulisi; menawarkan untuk memperbaiki izin +- **Izin state dir**: memverifikasi dapat ditulis; menawarkan untuk memperbaiki izin (dan mengeluarkan petunjuk `chown` saat terdeteksi ketidakcocokan owner/group). -- **Direktori state tersinkron cloud macOS**: memperingatkan saat state berada di bawah iCloud Drive +- **State dir tersinkron cloud di macOS**: memperingatkan saat status ter-resolve di bawah iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) atau - `~/Library/CloudStorage/...` karena path berbasis sinkronisasi dapat menyebabkan I/O lebih lambat + `~/Library/CloudStorage/...` karena path yang didukung sinkronisasi dapat menyebabkan I/O lebih lambat dan race lock/sinkronisasi. -- **Direktori state pada SD atau eMMC Linux**: memperingatkan saat state berada pada sumber mount `mmcblk*`, - karena random I/O berbasis SD atau eMMC bisa lebih lambat dan lebih cepat aus - akibat penulisan sesi dan kredensial. -- **Direktori sesi hilang**: `sessions/` dan direktori penyimpanan sesi diperlukan - untuk mempertahankan riwayat dan menghindari crash `ENOENT`. -- **Ketidakcocokan transcript**: memperingatkan saat entri sesi terbaru memiliki - file transcript yang hilang. -- **Sesi utama “1-line JSONL”**: menandai saat transcript utama hanya memiliki satu - baris (riwayat tidak bertambah). -- **Beberapa direktori state**: memperingatkan saat ada beberapa folder `~/.openclaw` di - berbagai home directory atau saat `OPENCLAW_STATE_DIR` menunjuk ke tempat lain (riwayat dapat terbelah antar instalasi). +- **State dir Linux di SD atau eMMC**: memperingatkan saat status ter-resolve ke sumber mount `mmcblk*`, + karena random I/O yang didukung SD atau eMMC bisa lebih lambat dan lebih cepat aus + di bawah penulisan sesi dan kredensial. +- **Dir sesi hilang**: `sessions/` dan direktori penyimpanan sesi + diperlukan untuk mempertahankan riwayat dan menghindari crash `ENOENT`. +- **Ketidakcocokan transkrip**: memperingatkan saat entri sesi terbaru memiliki file + transkrip yang hilang. +- **Sesi utama “1-line JSONL”**: menandai saat transkrip utama hanya memiliki satu + baris (riwayat tidak terakumulasi). +- **Beberapa state dir**: memperingatkan saat beberapa folder `~/.openclaw` ada di berbagai + direktori home atau saat `OPENCLAW_STATE_DIR` menunjuk ke tempat lain (riwayat dapat + terpecah antar instalasi). - **Pengingat mode remote**: jika `gateway.mode=remote`, doctor mengingatkan Anda untuk menjalankannya - di host remote (state berada di sana). -- **Izin file config**: memperingatkan jika `~/.openclaw/openclaw.json` dapat dibaca - oleh group/world dan menawarkan untuk mengetatkannya ke `600`. + di host remote (status berada di sana). +- **Izin file konfigurasi**: memperingatkan jika `~/.openclaw/openclaw.json` dapat + dibaca group/world dan menawarkan untuk memperketat ke `600`. ### 5) Kesehatan auth model (kedaluwarsa OAuth) -Doctor memeriksa profil OAuth dalam penyimpanan auth, memperingatkan saat token -akan kedaluwarsa/sudah kedaluwarsa, dan dapat me-refresh-nya bila aman. Jika profil -OAuth/token Anthropic usang, doctor menyarankan Anthropic API key atau -jalur setup-token Anthropic. +Doctor memeriksa profil OAuth di penyimpanan auth, memperingatkan saat token akan +kedaluwarsa/sudah kedaluwarsa, dan dapat me-refresh token saat aman. Jika profil +OAuth/token Anthropic usang, doctor menyarankan Anthropic API key atau path +setup-token Anthropic. Prompt refresh hanya muncul saat berjalan secara interaktif (TTY); `--non-interactive` melewati upaya refresh. +Saat refresh OAuth gagal permanen (misalnya `refresh_token_reused`, +`invalid_grant`, atau provider memberi tahu Anda untuk sign in lagi), doctor melaporkan +bahwa re-auth diperlukan dan mencetak perintah `openclaw models auth login --provider ...` +yang tepat untuk dijalankan. + Doctor juga melaporkan profil auth yang sementara tidak dapat digunakan karena: - cooldown singkat (rate limit/timeout/kegagalan auth) -- penonaktifan yang lebih lama (kegagalan billing/kredit) +- penonaktifan lebih lama (kegagalan billing/kredit) ### 6) Validasi model hooks -Jika `hooks.gmail.model` disetel, doctor memvalidasi referensi model terhadap -katalog dan allowlist serta memperingatkan bila model tidak akan ter-resolve atau tidak diizinkan. +Jika `hooks.gmail.model` diatur, doctor memvalidasi referensi model terhadap +katalog dan allowlist serta memperingatkan saat referensi itu tidak akan ter-resolve atau tidak diizinkan. ### 7) Perbaikan image sandbox Saat sandboxing diaktifkan, doctor memeriksa image Docker dan menawarkan untuk membangun atau -beralih ke nama lama jika image saat ini tidak ada. +beralih ke nama lama jika image saat ini hilang. ### 7b) Dependensi runtime plugin bawaan @@ -354,51 +395,52 @@ mode `openclaw doctor --fix` / `openclaw doctor --repair`. ### 8) Migrasi layanan gateway dan petunjuk pembersihan Doctor mendeteksi layanan gateway lama (launchd/systemd/schtasks) dan -menawarkan untuk menghapusnya serta menginstal layanan OpenClaw menggunakan port gateway -saat ini. Doctor juga dapat memindai layanan tambahan yang mirip gateway dan mencetak petunjuk pembersihan. -Layanan gateway OpenClaw bernama profil dianggap kelas satu dan tidak -ditandai sebagai "tambahan." +menawarkan untuk menghapusnya serta memasang layanan OpenClaw menggunakan port gateway +saat ini. Doctor juga dapat memindai layanan mirip gateway tambahan dan mencetak petunjuk pembersihan. +Layanan gateway OpenClaw bernama profil dianggap first-class dan tidak +ditandai sebagai "tambahan". -### 8b) Migrasi Matrix saat startup +### 8b) Migrasi startup Matrix -Saat akun channel Matrix memiliki migrasi state lama yang tertunda atau dapat ditindaklanjuti, +Saat akun kanal Matrix memiliki migrasi status lama yang tertunda atau dapat ditindaklanjuti, doctor (dalam mode `--fix` / `--repair`) membuat snapshot pra-migrasi lalu -menjalankan langkah migrasi best-effort: migrasi state Matrix lama dan persiapan state terenkripsi lama. -Kedua langkah bersifat non-fatal; error dicatat dan startup berlanjut. Dalam mode read-only (`openclaw doctor` tanpa `--fix`) pemeriksaan -ini dilewati sepenuhnya. +menjalankan langkah migrasi best-effort: migrasi status Matrix lama dan persiapan +status terenkripsi lama. Kedua langkah bersifat non-fatal; kesalahan dicatat dan +startup berlanjut. Dalam mode baca-saja (`openclaw doctor` tanpa `--fix`) pemeriksaan ini +dilewati sepenuhnya. ### 9) Peringatan keamanan -Doctor mengeluarkan peringatan saat sebuah provider terbuka untuk DM tanpa allowlist, atau +Doctor mengeluarkan peringatan saat suatu provider terbuka untuk DM tanpa allowlist, atau saat suatu kebijakan dikonfigurasi dengan cara yang berbahaya. -### 10) `linger` systemd (Linux) +### 10) systemd linger (Linux) Jika berjalan sebagai layanan pengguna systemd, doctor memastikan lingering diaktifkan agar gateway tetap hidup setelah logout. -### 11) Status workspace (Skills, plugin, dan direktori lama) +### 11) Status workspace (Skills, plugin, dan dir lama) -Doctor mencetak ringkasan state workspace untuk agent default: +Doctor mencetak ringkasan status workspace untuk agen default: -- **Status Skills**: menghitung skill yang eligible, missing-requirements, dan allowlist-blocked. -- **Direktori workspace lama**: memperingatkan saat `~/openclaw` atau direktori workspace lama lainnya - ada berdampingan dengan workspace saat ini. -- **Status plugin**: menghitung plugin loaded/disabled/errored; mencantumkan ID plugin untuk setiap - error; melaporkan kapabilitas bundled plugin. +- **Status Skills**: menghitung Skills yang eligible, missing-requirements, dan allowlist-blocked. +- **Dir workspace lama**: memperingatkan saat `~/openclaw` atau direktori workspace lama lain + ada bersama workspace saat ini. +- **Status plugin**: menghitung plugin loaded/disabled/errored; mencantumkan ID plugin untuk + error apa pun; melaporkan kapabilitas bundle plugin. - **Peringatan kompatibilitas plugin**: menandai plugin yang memiliki masalah kompatibilitas dengan runtime saat ini. -- **Diagnostik plugin**: menampilkan peringatan atau error waktu muat yang dikeluarkan oleh +- **Diagnostik plugin**: menampilkan peringatan atau error saat load yang dikeluarkan oleh registry plugin. ### 11b) Ukuran file bootstrap Doctor memeriksa apakah file bootstrap workspace (misalnya `AGENTS.md`, -`CLAUDE.md`, atau file konteks lain yang diinjeksi) mendekati atau melebihi -anggaran karakter yang dikonfigurasi. Doctor melaporkan jumlah karakter mentah vs. yang diinjeksi per file, persentase +`CLAUDE.md`, atau file konteks injeksi lainnya) mendekati atau melebihi budget karakter +yang dikonfigurasi. Doctor melaporkan jumlah karakter mentah vs. yang diinjeksi per file, persentase pemotongan, penyebab pemotongan (`max/file` atau `max/total`), dan total karakter -yang diinjeksi sebagai bagian dari total anggaran. Saat file dipotong atau mendekati -batas, doctor mencetak tips untuk menyesuaikan `agents.defaults.bootstrapMaxChars` +yang diinjeksi sebagai fraksi dari total budget. Saat file dipotong atau mendekati +batas, doctor mencetak tips untuk menyetel `agents.defaults.bootstrapMaxChars` dan `agents.defaults.bootstrapTotalMaxChars`. ### 11c) Shell completion @@ -407,9 +449,9 @@ Doctor memeriksa apakah tab completion terinstal untuk shell saat ini (zsh, bash, fish, atau PowerShell): - Jika profil shell menggunakan pola dynamic completion yang lambat - (`source <(openclaw completion ...)`), doctor meng-upgrade-nya ke - varian file cache yang lebih cepat. -- Jika completion dikonfigurasi di profil tetapi file cache tidak ada, + (`source <(openclaw completion ...)`), doctor meningkatkannya ke varian file cache + yang lebih cepat. +- Jika completion dikonfigurasi di profil tetapi file cache hilang, doctor meregenerasi cache secara otomatis. - Jika tidak ada completion yang dikonfigurasi sama sekali, doctor meminta untuk menginstalnya (hanya mode interaktif; dilewati dengan `--non-interactive`). @@ -420,90 +462,90 @@ Jalankan `openclaw completion --write-state` untuk meregenerasi cache secara man Doctor memeriksa kesiapan auth token gateway lokal. -- Jika mode token membutuhkan token dan tidak ada sumber token, doctor menawarkan untuk membuatnya. +- Jika mode token memerlukan token dan tidak ada sumber token, doctor menawarkan untuk membuatnya. - Jika `gateway.auth.token` dikelola SecretRef tetapi tidak tersedia, doctor memperingatkan dan tidak menimpanya dengan plaintext. - `openclaw doctor --generate-gateway-token` memaksa pembuatan hanya saat tidak ada token SecretRef yang dikonfigurasi. -### 12b) Perbaikan read-only yang sadar SecretRef +### 12b) Perbaikan sadar-SecretRef baca-saja -Beberapa alur perbaikan perlu memeriksa kredensial yang dikonfigurasi tanpa melemahkan perilaku fail-fast runtime. +Beberapa alur perbaikan perlu memeriksa kredensial yang dikonfigurasi tanpa melemahkan perilaku fail-fast saat runtime. -- `openclaw doctor --fix` kini menggunakan model ringkasan SecretRef read-only yang sama seperti keluarga perintah status untuk perbaikan config yang ditargetkan. -- Contoh: perbaikan Telegram `allowFrom` / `groupAllowFrom` `@username` mencoba menggunakan kredensial bot yang dikonfigurasi jika tersedia. -- Jika token bot Telegram dikonfigurasi melalui SecretRef tetapi tidak tersedia di jalur perintah saat ini, doctor melaporkan bahwa kredensial dikonfigurasi-tetapi-tidak-tersedia dan melewati auto-resolution alih-alih crash atau salah melaporkan token sebagai hilang. +- `openclaw doctor --fix` sekarang menggunakan model ringkasan SecretRef baca-saja yang sama seperti keluarga perintah status untuk perbaikan konfigurasi yang terarah. +- Contoh: perbaikan Telegram `allowFrom` / `groupAllowFrom` `@username` mencoba menggunakan kredensial bot yang dikonfigurasi bila tersedia. +- Jika token bot Telegram dikonfigurasi melalui SecretRef tetapi tidak tersedia dalam path perintah saat ini, doctor melaporkan bahwa kredensial tersebut dikonfigurasi-tetapi-tidak-tersedia dan melewati auto-resolution alih-alih crash atau salah melaporkan token sebagai hilang. ### 13) Pemeriksaan kesehatan gateway + restart -Doctor menjalankan pemeriksaan kesehatan dan menawarkan untuk me-restart gateway saat gateway terlihat +Doctor menjalankan pemeriksaan kesehatan dan menawarkan untuk merestart gateway saat terlihat tidak sehat. ### 13b) Kesiapan memory search Doctor memeriksa apakah provider embedding memory search yang dikonfigurasi siap -untuk agent default. Perilakunya bergantung pada backend dan provider yang dikonfigurasi: +untuk agen default. Perilakunya bergantung pada backend dan provider yang dikonfigurasi: - **Backend QMD**: mem-probe apakah biner `qmd` tersedia dan dapat dijalankan. Jika tidak, doctor mencetak panduan perbaikan termasuk paket npm dan opsi path biner manual. - **Provider lokal eksplisit**: memeriksa file model lokal atau URL model - jarak jauh/dapat diunduh yang dikenali. Jika tidak ada, doctor menyarankan beralih ke provider jarak jauh. -- **Provider jarak jauh eksplisit** (`openai`, `voyage`, dll.): memverifikasi bahwa API key - ada di environment atau penyimpanan auth. Mencetak petunjuk perbaikan yang dapat ditindaklanjuti jika tidak ada. -- **Provider otomatis**: memeriksa ketersediaan model lokal terlebih dahulu, lalu mencoba setiap provider - jarak jauh sesuai urutan auto-selection. + remote/dapat-diunduh yang dikenali. Jika hilang, doctor menyarankan beralih ke provider remote. +- **Provider remote eksplisit** (`openai`, `voyage`, dll.): memverifikasi bahwa API key + ada di environment atau penyimpanan auth. Mencetak petunjuk perbaikan yang dapat ditindaklanjuti jika hilang. +- **Provider auto**: memeriksa ketersediaan model lokal terlebih dahulu, lalu mencoba setiap + provider remote dalam urutan auto-selection. Saat hasil probe gateway tersedia (gateway sehat pada saat -pemeriksaan), doctor mereferensikan silang hasilnya dengan config yang terlihat oleh CLI dan mencatat +pemeriksaan), doctor melakukan cross-reference hasilnya dengan konfigurasi yang terlihat oleh CLI dan mencatat setiap ketidaksesuaian. Gunakan `openclaw memory status --deep` untuk memverifikasi kesiapan embedding saat runtime. -### 14) Peringatan status channel +### 14) Peringatan status kanal -Jika gateway sehat, doctor menjalankan probe status channel dan melaporkan -peringatan beserta saran perbaikan. +Jika gateway sehat, doctor menjalankan probe status kanal dan melaporkan +peringatan dengan perbaikan yang disarankan. -### 15) Audit + perbaikan config supervisor +### 15) Audit konfigurasi supervisor + perbaikan -Doctor memeriksa config supervisor yang terinstal (launchd/systemd/schtasks) untuk +Doctor memeriksa konfigurasi supervisor yang terpasang (launchd/systemd/schtasks) untuk default yang hilang atau usang (misalnya dependensi systemd network-online dan -jeda restart). Saat menemukan ketidakcocokan, doctor merekomendasikan pembaruan dan dapat -menulis ulang file layanan/task ke default saat ini. +restart delay). Saat menemukan ketidakcocokan, doctor merekomendasikan pembaruan dan dapat +menulis ulang file/task layanan ke default saat ini. Catatan: -- `openclaw doctor` meminta konfirmasi sebelum menulis ulang config supervisor. +- `openclaw doctor` meminta konfirmasi sebelum menulis ulang konfigurasi supervisor. - `openclaw doctor --yes` menerima prompt perbaikan default. - `openclaw doctor --repair` menerapkan perbaikan yang direkomendasikan tanpa prompt. -- `openclaw doctor --repair --force` menimpa config supervisor kustom. -- Jika auth token memerlukan token dan `gateway.auth.token` dikelola SecretRef, jalur instalasi/perbaikan layanan doctor memvalidasi SecretRef tetapi tidak menyimpan nilai token plaintext yang telah di-resolve ke metadata environment layanan supervisor. -- Jika auth token memerlukan token dan token SecretRef yang dikonfigurasi tidak ter-resolve, doctor memblokir jalur instalasi/perbaikan dengan panduan yang dapat ditindaklanjuti. -- Jika `gateway.auth.token` dan `gateway.auth.password` keduanya dikonfigurasi dan `gateway.auth.mode` tidak disetel, doctor memblokir instalasi/perbaikan sampai mode disetel secara eksplisit. +- `openclaw doctor --repair --force` menimpa konfigurasi supervisor kustom. +- Jika auth token memerlukan token dan `gateway.auth.token` dikelola SecretRef, install/perbaikan layanan doctor memvalidasi SecretRef tetapi tidak menyimpan nilai token plaintext yang telah di-resolve ke metadata environment layanan supervisor. +- Jika auth token memerlukan token dan token SecretRef yang dikonfigurasi tidak ter-resolve, doctor memblokir path install/perbaikan dengan panduan yang dapat ditindaklanjuti. +- Jika `gateway.auth.token` dan `gateway.auth.password` sama-sama dikonfigurasi dan `gateway.auth.mode` tidak diatur, doctor memblokir install/perbaikan sampai mode diatur secara eksplisit. - Untuk unit user-systemd Linux, pemeriksaan drift token doctor kini mencakup sumber `Environment=` dan `EnvironmentFile=` saat membandingkan metadata auth layanan. - Anda selalu dapat memaksa penulisan ulang penuh melalui `openclaw gateway install --force`. ### 16) Diagnostik runtime + port gateway -Doctor memeriksa runtime layanan (PID, status keluar terakhir) dan memperingatkan saat -layanan terinstal tetapi sebenarnya tidak berjalan. Doctor juga memeriksa benturan port +Doctor memeriksa runtime layanan (PID, status exit terakhir) dan memperingatkan saat +layanan terpasang tetapi sebenarnya tidak berjalan. Doctor juga memeriksa benturan port pada port gateway (default `18789`) dan melaporkan kemungkinan penyebabnya (gateway sudah berjalan, tunnel SSH). -### 17) Praktik terbaik runtime gateway +### 17) Best practice runtime gateway Doctor memperingatkan saat layanan gateway berjalan di Bun atau path Node yang dikelola version manager -(`nvm`, `fnm`, `volta`, `asdf`, dll.). Channel WhatsApp + Telegram memerlukan Node, +(`nvm`, `fnm`, `volta`, `asdf`, dll.). Kanal WhatsApp + Telegram memerlukan Node, dan path version manager dapat rusak setelah upgrade karena layanan tidak -memuat init shell Anda. Doctor menawarkan untuk memigrasikan ke instalasi Node sistem saat +memuat init shell Anda. Doctor menawarkan untuk memigrasikan ke instalasi Node sistem bila tersedia (Homebrew/apt/choco). -### 18) Penulisan config + metadata wizard +### 18) Penulisan konfigurasi + metadata wizard -Doctor menyimpan perubahan config dan menandai metadata wizard untuk mencatat -jalannya doctor. +Doctor menyimpan setiap perubahan konfigurasi dan memberi cap metadata wizard untuk mencatat +run doctor. ### 19) Tips workspace (cadangan + sistem memori) -Doctor menyarankan sistem memori workspace bila belum ada dan mencetak tip cadangan +Doctor menyarankan sistem memori workspace jika belum ada dan mencetak tip cadangan jika workspace belum berada di bawah git. Lihat [/concepts/agent-workspace](/id/concepts/agent-workspace) untuk panduan lengkap tentang diff --git a/docs/id/help/testing.md b/docs/id/help/testing.md index 53527bd99..99028e794 100644 --- a/docs/id/help/testing.md +++ b/docs/id/help/testing.md @@ -6,31 +6,31 @@ read_when: summary: 'Kit pengujian: suite unit/e2e/live, runner Docker, dan cakupan tiap pengujian' title: Pengujian x-i18n: - generated_at: "2026-04-08T02:17:42Z" + generated_at: "2026-04-09T01:30:28Z" model: gpt-5.4 provider: openai - source_hash: ace2c19bfc350780475f4348264a4b55be2b4ccbb26f0d33b4a6af34510943b5 + source_hash: 01117f41d8b171a4f1da11ed78486ee700e70ae70af54eb6060c57baf64ab21b source_path: help/testing.md workflow: 15 --- # Pengujian -OpenClaw memiliki tiga suite Vitest (unit/integration, e2e, live) dan sekumpulan kecil runner Docker. +OpenClaw memiliki tiga suite Vitest (unit/integrasi, e2e, live) dan sekumpulan kecil runner Docker. -Dokumen ini adalah panduan “cara kami menguji”: +Dokumen ini adalah panduan “cara kami melakukan pengujian”: -- Apa yang dicakup tiap suite (dan apa yang sengaja _tidak_ dicakup) -- Perintah mana yang dijalankan untuk alur kerja umum (lokal, pra-push, debugging) +- Apa yang dicakup oleh setiap suite (dan apa yang sengaja _tidak_ dicakup) +- Perintah mana yang dijalankan untuk alur kerja umum (lokal, sebelum push, debugging) - Cara live test menemukan kredensial dan memilih model/provider - Cara menambahkan regresi untuk masalah model/provider di dunia nyata ## Mulai cepat -Sebagian besar hari: +Hampir setiap hari: - Gate penuh (diharapkan sebelum push): `pnpm build && pnpm check && pnpm test` -- Menjalankan suite penuh lokal yang lebih cepat pada mesin yang lapang: `pnpm test:max` +- Eksekusi full-suite lokal yang lebih cepat pada mesin yang lega: `pnpm test:max` - Loop watch Vitest langsung: `pnpm test:watch` - Penargetan file langsung kini juga merutekan path extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` - Situs QA berbasis Docker: `pnpm qa:lab:up` @@ -42,125 +42,125 @@ Saat Anda menyentuh pengujian atau ingin keyakinan tambahan: Saat men-debug provider/model nyata (memerlukan kredensial nyata): -- Suite live (model + probe tool/image gateway): `pnpm test:live` +- Suite live (probe model + tool/image gateway): `pnpm test:live` - Targetkan satu file live secara senyap: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -Tip: ketika Anda hanya memerlukan satu kasus gagal, lebih baik mempersempit live test melalui env var allowlist yang dijelaskan di bawah. +Tip: ketika Anda hanya memerlukan satu kasus gagal, sebaiknya persempit live test melalui env var allowlist yang dijelaskan di bawah. ## Suite pengujian (apa yang berjalan di mana) -Anggap suite sebagai “realisme yang meningkat” (dan flakiness/biaya yang meningkat): +Anggap suite-suite ini sebagai “realisme yang semakin meningkat” (dan flakiness/biaya yang juga meningkat): -### Unit / integration (default) +### Unit / integrasi (default) - Perintah: `pnpm test` -- Config: sepuluh kali shard run berurutan (`vitest.full-*.config.ts`) di atas project Vitest terlingkup yang ada +- Konfigurasi: sepuluh eksekusi shard berurutan (`vitest.full-*.config.ts`) di atas project Vitest terlingkup yang ada - File: inventaris core/unit di bawah `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts`, dan pengujian node `ui` yang di-whitelist yang dicakup oleh `vitest.unit.config.ts` - Cakupan: - Pengujian unit murni - Pengujian integrasi in-process (auth gateway, routing, tooling, parsing, config) - - Regresi deterministik untuk bug yang diketahui + - Regresi deterministik untuk bug yang sudah diketahui - Ekspektasi: - Berjalan di CI - Tidak memerlukan key nyata - Harus cepat dan stabil - Catatan project: - - `pnpm test` tanpa target kini menjalankan sebelas config shard yang lebih kecil (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) alih-alih satu proses giant native root-project. Ini mengurangi puncak RSS pada mesin yang sibuk dan mencegah pekerjaan auto-reply/extension membuat suite yang tidak terkait kelaparan sumber daya. - - `pnpm test --watch` masih menggunakan graf project `vitest.config.ts` root native, karena loop watch multi-shard tidak praktis. - - `pnpm test`, `pnpm test:watch`, dan `pnpm test:perf:imports` merutekan target file/direktori eksplisit melalui lane terlingkup terlebih dahulu, sehingga `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` tidak perlu membayar biaya startup root project penuh. - - `pnpm test:changed` memperluas path git yang berubah ke lane terlingkup yang sama ketika diff hanya menyentuh file source/test yang dapat dirutekan; edit config/setup tetap kembali ke rerun root-project yang lebih luas. - - Pengujian `plugin-sdk` dan `commands` terpilih juga dirutekan melalui lane ringan khusus yang melewati `test/setup-openclaw-runtime.ts`; file stateful/runtime-heavy tetap berada di lane yang ada. - - File source helper `plugin-sdk` dan `commands` terpilih juga memetakan run mode-changed ke pengujian sibling eksplisit di lane ringan tersebut, sehingga edit helper tidak memicu rerun suite berat penuh untuk direktori itu. - - `auto-reply` kini memiliki tiga bucket khusus: helper core tingkat atas, pengujian integrasi `reply.*` tingkat atas, dan subtree `src/auto-reply/reply/**`. Ini menjaga pekerjaan harness balasan terberat tetap terpisah dari pengujian status/chunk/token yang murah. + - `pnpm test` tanpa target kini menjalankan sebelas konfigurasi shard yang lebih kecil (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) alih-alih satu proses root-project native yang sangat besar. Ini mengurangi puncak RSS pada mesin yang sibuk dan mencegah pekerjaan auto-reply/extension mengganggu suite lain yang tidak terkait. + - `pnpm test --watch` tetap menggunakan graf project `vitest.config.ts` root native, karena loop watch multi-shard tidak praktis. + - `pnpm test`, `pnpm test:watch`, dan `pnpm test:perf:imports` merutekan target file/direktori eksplisit melalui lane terlingkup terlebih dahulu, sehingga `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` tidak perlu membayar biaya startup penuh root project. + - `pnpm test:changed` memperluas path git yang berubah ke lane terlingkup yang sama saat diff hanya menyentuh file source/test yang dapat dirutekan; edit config/setup tetap fallback ke rerun root-project yang luas. + - Pengujian `plugin-sdk` dan `commands` tertentu juga dirutekan melalui lane ringan khusus yang melewati `test/setup-openclaw-runtime.ts`; file stateful/runtime-heavy tetap berada di lane yang ada. + - File source helper `plugin-sdk` dan `commands` tertentu juga memetakan eksekusi mode-changed ke pengujian saudara eksplisit di lane ringan tersebut, sehingga edit helper tidak memicu rerun suite berat penuh untuk direktori itu. + - `auto-reply` sekarang memiliki tiga bucket khusus: helper core tingkat atas, pengujian integrasi `reply.*` tingkat atas, dan subtree `src/auto-reply/reply/**`. Ini menjaga pekerjaan harness reply terberat tetap terpisah dari pengujian status/chunk/token yang murah. - Catatan embedded runner: - Saat Anda mengubah input penemuan message-tool atau konteks runtime compaction, pertahankan kedua tingkat cakupan. - - Tambahkan regresi helper yang terfokus untuk boundary routing/normalisasi murni. + - Tambahkan regresi helper yang terfokus untuk batas routing/normalisasi murni. - Jaga juga suite integrasi embedded runner tetap sehat: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts`, dan `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Suite tersebut memverifikasi bahwa id terlingkup dan perilaku compaction tetap mengalir + - Suite-suite tersebut memverifikasi bahwa id terlingkup dan perilaku compaction tetap mengalir melalui path `run.ts` / `compact.ts` yang nyata; pengujian helper saja bukan pengganti yang memadai untuk path integrasi tersebut. - Catatan pool: - - Config dasar Vitest kini default ke `threads`. - - Config Vitest bersama juga menetapkan `isolate: false` dan menggunakan runner non-isolated di root projects, config e2e, dan live. - - Lane UI root mempertahankan setup dan optimizer `jsdom`-nya, tetapi kini juga berjalan pada runner non-isolated bersama. - - Setiap shard `pnpm test` mewarisi default `threads` + `isolate: false` yang sama dari config Vitest bersama. - - Launcher bersama `scripts/run-vitest.mjs` kini juga menambahkan `--no-maglev` untuk proses Node anak Vitest secara default guna mengurangi compile churn V8 selama run lokal besar. Setel `OPENCLAW_VITEST_ENABLE_MAGLEV=1` jika Anda perlu membandingkan dengan perilaku V8 bawaan. + - Konfigurasi dasar Vitest sekarang menggunakan `threads` secara default. + - Konfigurasi Vitest bersama juga menetapkan `isolate: false` dan menggunakan runner non-isolated di seluruh konfigurasi root project, e2e, dan live. + - Lane UI root mempertahankan setup dan optimizer `jsdom`, tetapi sekarang juga berjalan pada runner non-isolated bersama. + - Setiap shard `pnpm test` mewarisi default `threads` + `isolate: false` yang sama dari konfigurasi Vitest bersama. + - Launcher bersama `scripts/run-vitest.mjs` sekarang juga menambahkan `--no-maglev` untuk proses Node anak Vitest secara default guna mengurangi churn kompilasi V8 selama eksekusi lokal besar. Tetapkan `OPENCLAW_VITEST_ENABLE_MAGLEV=1` jika Anda perlu membandingkan dengan perilaku V8 bawaan. - Catatan iterasi lokal cepat: - - `pnpm test:changed` merutekan melalui lane terlingkup ketika path yang berubah terpetakan dengan bersih ke suite yang lebih kecil. + - `pnpm test:changed` merutekan melalui lane terlingkup saat path yang berubah dipetakan dengan bersih ke suite yang lebih kecil. - `pnpm test:max` dan `pnpm test:changed:max` mempertahankan perilaku routing yang sama, hanya dengan batas worker yang lebih tinggi. - - Auto-scaling worker lokal sekarang memang sengaja konservatif dan juga mundur ketika load average host sudah tinggi, sehingga beberapa run Vitest serentak secara default menyebabkan kerusakan yang lebih kecil. - - Config dasar Vitest menandai file project/config sebagai `forceRerunTriggers` agar rerun mode-changed tetap benar saat wiring pengujian berubah. - - Config mempertahankan `OPENCLAW_VITEST_FS_MODULE_CACHE` aktif pada host yang didukung; setel `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` jika Anda menginginkan satu lokasi cache eksplisit untuk profiling langsung. + - Auto-scaling worker lokal kini sengaja lebih konservatif dan juga mundur saat load average host sudah tinggi, sehingga beberapa eksekusi Vitest bersamaan menimbulkan dampak yang lebih kecil secara default. + - Konfigurasi dasar Vitest menandai file projects/config sebagai `forceRerunTriggers` agar rerun mode-changed tetap benar saat wiring pengujian berubah. + - Konfigurasi mempertahankan `OPENCLAW_VITEST_FS_MODULE_CACHE` tetap aktif pada host yang didukung; tetapkan `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` jika Anda ingin satu lokasi cache eksplisit untuk profiling langsung. - Catatan debug performa: - - `pnpm test:perf:imports` mengaktifkan pelaporan durasi import Vitest plus output rincian import. + - `pnpm test:perf:imports` mengaktifkan pelaporan durasi impor Vitest beserta keluaran rincian impor. - `pnpm test:perf:imports:changed` membatasi tampilan profiling yang sama ke file yang berubah sejak `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` membandingkan `test:changed` yang dirutekan dengan path root-project native untuk diff yang di-commit tersebut dan mencetak wall time plus max RSS macOS. -- `pnpm test:perf:changed:bench -- --worktree` membenchmark dirty tree saat ini dengan merutekan daftar file yang berubah melalui `scripts/test-projects.mjs` dan config Vitest root. +- `pnpm test:perf:changed:bench -- --ref ` membandingkan `test:changed` yang dirutekan dengan path root-project native untuk diff yang telah di-commit tersebut dan mencetak wall time beserta max RSS macOS. +- `pnpm test:perf:changed:bench -- --worktree` melakukan benchmark pada tree kotor saat ini dengan merutekan daftar file yang berubah melalui `scripts/test-projects.mjs` dan konfigurasi Vitest root. - `pnpm test:perf:profile:main` menulis profil CPU main-thread untuk overhead startup dan transform Vitest/Vite. - `pnpm test:perf:profile:runner` menulis profil CPU+heap runner untuk suite unit dengan paralelisme file dinonaktifkan. ### E2E (smoke gateway) - Perintah: `pnpm test:e2e` -- Config: `vitest.e2e.config.ts` +- Konfigurasi: `vitest.e2e.config.ts` - File: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` - Default runtime: - - Menggunakan Vitest `threads` dengan `isolate: false`, selaras dengan bagian repo lainnya. + - Menggunakan Vitest `threads` dengan `isolate: false`, konsisten dengan bagian repo lainnya. - Menggunakan worker adaptif (CI: hingga 2, lokal: 1 secara default). - Berjalan dalam mode senyap secara default untuk mengurangi overhead I/O konsol. - Override yang berguna: - `OPENCLAW_E2E_WORKERS=` untuk memaksa jumlah worker (dibatasi hingga 16). - - `OPENCLAW_E2E_VERBOSE=1` untuk mengaktifkan kembali output konsol verbose. + - `OPENCLAW_E2E_VERBOSE=1` untuk mengaktifkan kembali keluaran konsol verbose. - Cakupan: - - Perilaku end-to-end gateway multi-instans + - Perilaku end-to-end gateway multi-instance - Surface WebSocket/HTTP, pairing node, dan jaringan yang lebih berat - Ekspektasi: - Berjalan di CI (saat diaktifkan dalam pipeline) - Tidak memerlukan key nyata - - Memiliki lebih banyak bagian bergerak dibanding pengujian unit (bisa lebih lambat) + - Lebih banyak bagian bergerak dibanding pengujian unit (bisa lebih lambat) ### E2E: smoke backend OpenShell - Perintah: `pnpm test:e2e:openshell` - File: `test/openshell-sandbox.e2e.test.ts` - Cakupan: - - Menjalankan gateway OpenShell terisolasi di host melalui Docker + - Memulai gateway OpenShell terisolasi pada host melalui Docker - Membuat sandbox dari Dockerfile lokal sementara - Menjalankan backend OpenShell OpenClaw melalui `sandbox ssh-config` + eksekusi SSH yang nyata - Memverifikasi perilaku filesystem remote-canonical melalui bridge fs sandbox - Ekspektasi: - - Hanya opt-in; bukan bagian dari run default `pnpm test:e2e` + - Hanya opt-in; bukan bagian dari eksekusi default `pnpm test:e2e` - Memerlukan CLI `openshell` lokal plus daemon Docker yang berfungsi - - Menggunakan `HOME` / `XDG_CONFIG_HOME` yang terisolasi, lalu menghancurkan gateway uji dan sandbox + - Menggunakan `HOME` / `XDG_CONFIG_HOME` yang terisolasi, lalu menghancurkan gateway dan sandbox pengujian - Override yang berguna: - `OPENCLAW_E2E_OPENSHELL=1` untuk mengaktifkan pengujian saat menjalankan suite e2e yang lebih luas secara manual - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` untuk menunjuk ke biner CLI non-default atau wrapper script + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` untuk menunjuk ke biner CLI non-default atau skrip wrapper ### Live (provider nyata + model nyata) - Perintah: `pnpm test:live` -- Config: `vitest.live.config.ts` +- Konfigurasi: `vitest.live.config.ts` - File: `src/**/*.live.test.ts` -- Default: **aktif** melalui `pnpm test:live` (menyetel `OPENCLAW_LIVE_TEST=1`) +- Default: **diaktifkan** oleh `pnpm test:live` (menetapkan `OPENCLAW_LIVE_TEST=1`) - Cakupan: - - “Apakah provider/model ini benar-benar berfungsi _hari ini_ dengan kredensial nyata?” + - “Apakah provider/model ini benar-benar bekerja _hari ini_ dengan kredensial nyata?” - Menangkap perubahan format provider, keanehan tool-calling, masalah auth, dan perilaku rate limit - Ekspektasi: - - Tidak stabil untuk CI secara sengaja (jaringan nyata, kebijakan provider nyata, kuota, outage) - - Menghabiskan uang / menggunakan rate limit - - Lebih baik menjalankan subset yang dipersempit daripada “semuanya” -- Live run melakukan source `~/.profile` untuk mengambil API key yang hilang. + - Memang tidak stabil untuk CI (jaringan nyata, kebijakan provider nyata, kuota, outage) + - Menghabiskan biaya / menggunakan rate limit + - Sebaiknya menjalankan subset yang dipersempit, bukan “semuanya” +- Live run melakukan source `~/.profile` untuk mengambil API key yang belum ada. - Secara default, live run tetap mengisolasi `HOME` dan menyalin materi config/auth ke home pengujian sementara agar fixture unit tidak dapat mengubah `~/.openclaw` asli Anda. -- Setel `OPENCLAW_LIVE_USE_REAL_HOME=1` hanya jika Anda memang sengaja memerlukan live test menggunakan home directory asli Anda. -- `pnpm test:live` kini default ke mode yang lebih senyap: tetap mempertahankan output progres `[live] ...`, tetapi menekan notifikasi `~/.profile` tambahan dan membisukan log bootstrap gateway/chatter Bonjour. Setel `OPENCLAW_LIVE_TEST_QUIET=0` jika Anda ingin log startup penuh kembali. -- Rotasi API key (spesifik provider): setel `*_API_KEYS` dengan format koma/titik koma atau `*_API_KEY_1`, `*_API_KEY_2` (misalnya `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) atau override per-live melalui `OPENCLAW_LIVE_*_KEY`; pengujian akan retry saat menerima respons rate limit. -- Output progres/heartbeat: - - Suite live kini mengeluarkan baris progres ke stderr sehingga panggilan provider yang lama terlihat aktif meskipun penangkapan konsol Vitest sedang senyap. - - `vitest.live.config.ts` menonaktifkan intersepsi konsol Vitest sehingga baris progres provider/gateway mengalir langsung selama live run. +- Tetapkan `OPENCLAW_LIVE_USE_REAL_HOME=1` hanya saat Anda memang ingin live test menggunakan direktori home asli Anda. +- `pnpm test:live` kini default ke mode yang lebih senyap: tetap mempertahankan keluaran progres `[live] ...`, tetapi menekan notifikasi `~/.profile` tambahan dan membisukan log bootstrap gateway/chatter Bonjour. Tetapkan `OPENCLAW_LIVE_TEST_QUIET=0` jika Anda ingin log startup penuh kembali. +- Rotasi API key (spesifik provider): tetapkan `*_API_KEYS` dengan format koma/titik koma atau `*_API_KEY_1`, `*_API_KEY_2` (misalnya `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) atau override per-live melalui `OPENCLAW_LIVE_*_KEY`; pengujian akan mencoba ulang saat mendapat respons rate limit. +- Keluaran progres/heartbeat: + - Suite live sekarang mengeluarkan baris progres ke stderr sehingga pemanggilan provider yang lama tetap tampak aktif meskipun capture konsol Vitest senyap. + - `vitest.live.config.ts` menonaktifkan intersepsi konsol Vitest sehingga baris progres provider/gateway mengalir segera selama live run. - Atur heartbeat direct-model dengan `OPENCLAW_LIVE_HEARTBEAT_MS`. - Atur heartbeat gateway/probe dengan `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. @@ -168,103 +168,105 @@ Anggap suite sebagai “realisme yang meningkat” (dan flakiness/biaya yang men Gunakan tabel keputusan ini: -- Mengedit logika/pengujian: jalankan `pnpm test` (dan `pnpm test:coverage` jika Anda banyak mengubah) +- Mengedit logika/pengujian: jalankan `pnpm test` (dan `pnpm test:coverage` jika Anda mengubah banyak hal) - Menyentuh jaringan gateway / protokol WS / pairing: tambahkan `pnpm test:e2e` -- Men-debug “bot saya mati” / kegagalan spesifik provider / tool calling: jalankan `pnpm test:live` yang dipersempit +- Men-debug “bot saya down” / kegagalan spesifik provider / tool calling: jalankan `pnpm test:live` yang dipersempit -## Live: penyapuan kapabilitas node Android +## Live: sweep kapabilitas node Android - Pengujian: `src/gateway/android-node.capabilities.live.test.ts` -- Script: `pnpm android:test:integration` -- Tujuan: memanggil **setiap perintah yang saat ini diiklankan** oleh node Android yang terhubung dan menegaskan perilaku kontrak perintah. +- Skrip: `pnpm android:test:integration` +- Tujuan: memanggil **setiap perintah yang saat ini diiklankan** oleh node Android yang terhubung dan memverifikasi perilaku kontrak perintah. - Cakupan: - - Setup manual/prasyarat (suite tidak menginstal/menjalankan/memasangkan aplikasi). - - Validasi `node.invoke` gateway per perintah untuk node Android yang dipilih. + - Setup manual dengan prasyarat (suite ini tidak memasang/menjalankan/mem-pair aplikasi). + - Validasi gateway `node.invoke` per perintah untuk node Android yang dipilih. - Pra-setup yang diperlukan: - - Aplikasi Android sudah terhubung + dipasangkan ke gateway. + - Aplikasi Android sudah terhubung + ter-pair ke gateway. - Aplikasi tetap berada di foreground. - Izin/persetujuan capture diberikan untuk kapabilitas yang Anda harapkan lolos. - Override target opsional: - `OPENCLAW_ANDROID_NODE_ID` atau `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. -- Detail setup Android lengkap: [Aplikasi Android](/id/platforms/android) +- Detail setup Android lengkap: [Android App](/id/platforms/android) ## Live: smoke model (key profil) Live test dibagi menjadi dua lapisan agar kita dapat mengisolasi kegagalan: -- “Direct model” memberi tahu kita apakah provider/model dapat merespons sama sekali dengan key yang diberikan. -- “Gateway smoke” memberi tahu kita apakah pipeline gateway+agent penuh berfungsi untuk model itu (session, riwayat, tool, kebijakan sandbox, dll.). +- “Direct model” memberi tahu kita apakah provider/model dapat menjawab sama sekali dengan key yang diberikan. +- “Gateway smoke” memberi tahu kita apakah seluruh pipeline gateway+agent bekerja untuk model itu (session, history, tools, kebijakan sandbox, dan sebagainya). -### Lapisan 1: penyelesaian model langsung (tanpa gateway) +### Lapisan 1: Penyelesaian direct model (tanpa gateway) - Pengujian: `src/agents/models.profiles.live.test.ts` - Tujuan: - Mengenumerasi model yang ditemukan - - Menggunakan `getApiKeyForModel` untuk memilih model yang kredensialnya Anda miliki - - Menjalankan completion kecil per model (dan regresi yang ditargetkan bila perlu) + - Menggunakan `getApiKeyForModel` untuk memilih model yang Anda miliki kredensialnya + - Menjalankan penyelesaian kecil per model (dan regresi terarah bila perlu) - Cara mengaktifkan: - `pnpm test:live` (atau `OPENCLAW_LIVE_TEST=1` jika memanggil Vitest secara langsung) -- Setel `OPENCLAW_LIVE_MODELS=modern` (atau `all`, alias untuk modern) agar suite ini benar-benar berjalan; jika tidak, suite akan skip agar `pnpm test:live` tetap berfokus pada gateway smoke +- Tetapkan `OPENCLAW_LIVE_MODELS=modern` (atau `all`, alias untuk modern) agar suite ini benar-benar berjalan; jika tidak, suite ini akan di-skip agar `pnpm test:live` tetap fokus pada gateway smoke - Cara memilih model: - `OPENCLAW_LIVE_MODELS=modern` untuk menjalankan allowlist modern (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - `OPENCLAW_LIVE_MODELS=all` adalah alias untuk allowlist modern - - atau `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist dipisah koma) + - atau `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist dipisahkan koma) + - Sweep modern/all default ke batas kurasi dengan sinyal tinggi; tetapkan `OPENCLAW_LIVE_MAX_MODELS=0` untuk sweep modern lengkap atau angka positif untuk batas yang lebih kecil. - Cara memilih provider: - - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist dipisah koma) + - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist dipisahkan koma) - Dari mana key berasal: - - Secara default: profile store dan fallback env - - Setel `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` untuk memaksakan **hanya profile store** + - Default: profile store dan fallback env + - Tetapkan `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` untuk memaksa hanya **profile store** - Mengapa ini ada: - Memisahkan “API provider rusak / key tidak valid” dari “pipeline agent gateway rusak” - - Memuat regresi kecil dan terisolasi (contoh: replay reasoning OpenAI Responses/Codex Responses + alur tool-call) + - Menampung regresi kecil yang terisolasi (contoh: replay reasoning OpenAI Responses/Codex Responses + alur tool-call) -### Lapisan 2: smoke gateway + agent dev (apa yang sebenarnya dilakukan "@openclaw") +### Lapisan 2: Gateway + smoke dev agent (apa yang sebenarnya dilakukan "@openclaw") - Pengujian: `src/gateway/gateway-models.profiles.live.test.ts` - Tujuan: - Menjalankan gateway in-process - - Membuat/menambal session `agent:dev:*` (override model per run) - - Mengiterasi model-dengan-key dan menegaskan: - - respons yang “bermakna” (tanpa tools) + - Membuat/menambal session `agent:dev:*` (override model per eksekusi) + - Mengiterasi model-dengan-key dan memverifikasi: + - respons “bermakna” (tanpa tools) - pemanggilan tool nyata berfungsi (probe read) - probe tool tambahan opsional (probe exec+read) - path regresi OpenAI (hanya tool-call → tindak lanjut) tetap berfungsi -- Detail probe (agar Anda bisa menjelaskan kegagalan dengan cepat): - - probe `read`: pengujian menulis file nonce di workspace lalu meminta agent untuk `read` file itu dan menggemakan nonce kembali. - - probe `exec+read`: pengujian meminta agent untuk menulis nonce ke file sementara lewat `exec`, lalu `read` kembali. - - probe image: pengujian melampirkan PNG yang dibuat (kucing + kode acak) dan mengharapkan model mengembalikan `cat `. +- Detail probe (agar Anda dapat menjelaskan kegagalan dengan cepat): + - probe `read`: pengujian menulis file nonce di workspace lalu meminta agent `read` file tersebut dan mengembalikan nonce. + - probe `exec+read`: pengujian meminta agent menulis nonce ke file sementara via `exec`, lalu `read` kembali. + - probe gambar: pengujian melampirkan PNG yang dihasilkan (kucing + kode acak) dan mengharapkan model mengembalikan `cat `. - Referensi implementasi: `src/gateway/gateway-models.profiles.live.test.ts` dan `src/gateway/live-image-probe.ts`. - Cara mengaktifkan: - `pnpm test:live` (atau `OPENCLAW_LIVE_TEST=1` jika memanggil Vitest secara langsung) - Cara memilih model: - Default: allowlist modern (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - `OPENCLAW_LIVE_GATEWAY_MODELS=all` adalah alias untuk allowlist modern - - Atau setel `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (atau daftar dipisah koma) untuk mempersempit + - Atau tetapkan `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (atau daftar dipisahkan koma) untuk mempersempit + - Sweep gateway modern/all default ke batas kurasi dengan sinyal tinggi; tetapkan `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` untuk sweep modern lengkap atau angka positif untuk batas yang lebih kecil. - Cara memilih provider (hindari “semua OpenRouter”): - - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist dipisah koma) -- Probe tool + image selalu aktif dalam live test ini: + - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist dipisahkan koma) +- Probe tool + gambar selalu aktif di live test ini: - probe `read` + probe `exec+read` (stress tool) - - probe image berjalan saat model mengiklankan dukungan input image + - probe gambar berjalan saat model mengiklankan dukungan input gambar - Alur (tingkat tinggi): - Pengujian menghasilkan PNG kecil dengan “CAT” + kode acak (`src/gateway/live-image-probe.ts`) - - Mengirimnya melalui `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - - Gateway mem-parsing attachment ke `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - Mengirimkannya melalui `agent` `attachments: [{ mimeType: "image/png", content: "" }]` + - Gateway mem-parsing attachment menjadi `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - Embedded agent meneruskan pesan pengguna multimodal ke model - Asersi: balasan berisi `cat` + kode tersebut (toleransi OCR: kesalahan kecil diperbolehkan) -Tip: untuk melihat apa yang dapat Anda uji di mesin Anda (dan id `provider/model` yang tepat), jalankan: +Tip: untuk melihat apa yang bisa Anda uji pada mesin Anda (dan id `provider/model` yang tepat), jalankan: ```bash openclaw models list openclaw models list --json ``` -## Live: smoke backend CLI (Claude, Codex, Gemini, atau CLI lokal lainnya) +## Live: smoke backend CLI (Claude, Codex, Gemini, atau CLI lokal lain) - Pengujian: `src/gateway/gateway-cli-backend.live.test.ts` - Tujuan: memvalidasi pipeline Gateway + agent menggunakan backend CLI lokal, tanpa menyentuh config default Anda. -- Default smoke spesifik backend berada bersama definisi `cli-backend.ts` milik extension yang memilikinya. +- Default smoke spesifik backend berada bersama definisi `cli-backend.ts` milik extension yang bersangkutan. - Aktifkan: - `pnpm test:live` (atau `OPENCLAW_LIVE_TEST=1` jika memanggil Vitest secara langsung) - `OPENCLAW_LIVE_CLI_BACKEND=1` @@ -275,11 +277,11 @@ openclaw models list --json - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` untuk mengirim attachment image nyata (path diinjeksi ke prompt). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` untuk meneruskan path file image sebagai argumen CLI alih-alih injeksi prompt. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (atau `"list"`) untuk mengontrol cara argumen image diteruskan saat `IMAGE_ARG` disetel. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` untuk mengirim attachment gambar nyata (path disuntikkan ke prompt). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` untuk meneruskan path file gambar sebagai argumen CLI alih-alih injeksi prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (atau `"list"`) untuk mengendalikan cara argumen gambar diteruskan saat `IMAGE_ARG` ditetapkan. - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` untuk mengirim giliran kedua dan memvalidasi alur resume. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` untuk menonaktifkan probe kontinuitas session yang sama Claude Sonnet -> Opus secara default (setel ke `1` untuk memaksanya aktif saat model yang dipilih mendukung target switch). + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` untuk menonaktifkan probe kontinuitas satu session default Claude Sonnet -> Opus (tetapkan ke `1` untuk memaksanya aktif saat model yang dipilih mendukung target switch). Contoh: @@ -295,7 +297,7 @@ Resep Docker: pnpm test:docker:live-cli-backend ``` -Resep Docker provider tunggal: +Resep Docker penyedia tunggal: ```bash pnpm test:docker:live-cli-backend:claude @@ -307,8 +309,8 @@ Catatan: - Runner Docker berada di `scripts/test-live-cli-backend-docker.sh`. - Runner ini menjalankan smoke CLI-backend live di dalam image Docker repo sebagai pengguna non-root `node`. -- Runner ini me-resolve metadata smoke CLI dari extension yang memilikinya, lalu menginstal paket CLI Linux yang cocok (`@anthropic-ai/claude-code`, `@openai/codex`, atau `@google/gemini-cli`) ke prefix writable yang di-cache di `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (default: `~/.cache/openclaw/docker-cli-tools`). -- Smoke CLI-backend live kini menjalankan alur end-to-end yang sama untuk Claude, Codex, dan Gemini: giliran teks, giliran klasifikasi image, lalu pemanggilan tool MCP `cron` yang diverifikasi melalui gateway CLI. +- Runner ini me-resolve metadata smoke CLI dari extension yang memilikinya, lalu memasang paket CLI Linux yang sesuai (`@anthropic-ai/claude-code`, `@openai/codex`, atau `@google/gemini-cli`) ke prefix writable yang di-cache di `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (default: `~/.cache/openclaw/docker-cli-tools`). +- Smoke CLI-backend live sekarang menjalankan alur end-to-end yang sama untuk Claude, Codex, dan Gemini: giliran teks, giliran klasifikasi gambar, lalu pemanggilan tool MCP `cron` yang diverifikasi melalui CLI gateway. - Smoke default Claude juga menambal session dari Sonnet ke Opus dan memverifikasi session yang dilanjutkan masih mengingat catatan sebelumnya. ## Live: smoke bind ACP (`/acp spawn ... --bind here`) @@ -316,16 +318,16 @@ Catatan: - Pengujian: `src/gateway/gateway-acp-bind.live.test.ts` - Tujuan: memvalidasi alur bind percakapan ACP nyata dengan agent ACP live: - kirim `/acp spawn --bind here` - - bind percakapan message-channel sintetis secara in-place + - bind percakapan message-channel sintetis di tempat - kirim tindak lanjut normal pada percakapan yang sama - - verifikasi tindak lanjut mendarat di transcript session ACP yang dibind + - verifikasi tindak lanjut masuk ke transkrip session ACP yang terikat - Aktifkan: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - Default: - Agent ACP di Docker: `claude,codex,gemini` - Agent ACP untuk `pnpm test:live ...` langsung: `claude` - - Channel sintetis: konteks percakapan gaya Slack DM + - Channel sintetis: konteks percakapan bergaya Slack DM - Backend ACP: `acpx` - Override: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` @@ -334,8 +336,8 @@ Catatan: - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - Catatan: - - Lane ini menggunakan surface gateway `chat.send` dengan field originating-route sintetis admin-only agar pengujian dapat melampirkan konteks message-channel tanpa berpura-pura melakukan pengiriman eksternal. - - Saat `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` tidak disetel, pengujian menggunakan registry agent bawaan plugin `acpx` embedded untuk agent harness ACP yang dipilih. + - Lane ini menggunakan surface gateway `chat.send` dengan field originating-route sintetis khusus admin agar pengujian dapat melampirkan konteks message-channel tanpa berpura-pura melakukan pengiriman eksternal. + - Saat `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` tidak ditetapkan, pengujian ini menggunakan registry agent bawaan plugin `acpx` embedded untuk agent harness ACP yang dipilih. Contoh: @@ -351,7 +353,7 @@ Resep Docker: pnpm test:docker:live-acp-bind ``` -Resep Docker single-agent: +Resep Docker agen tunggal: ```bash pnpm test:docker:live-acp-bind:claude @@ -364,42 +366,42 @@ Catatan Docker: - Runner Docker berada di `scripts/test-live-acp-bind-docker.sh`. - Secara default, runner ini menjalankan smoke bind ACP terhadap semua agent CLI live yang didukung secara berurutan: `claude`, `codex`, lalu `gemini`. - Gunakan `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`, atau `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` untuk mempersempit matriks. -- Runner ini melakukan source `~/.profile`, men-stage materi auth CLI yang cocok ke dalam container, menginstal `acpx` ke prefix npm yang writable, lalu menginstal CLI live yang diminta (`@anthropic-ai/claude-code`, `@openai/codex`, atau `@google/gemini-cli`) jika belum ada. -- Di dalam Docker, runner menyetel `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` agar acpx mempertahankan env var provider dari profile yang di-source tetap tersedia untuk CLI harness anak. +- Runner ini melakukan source `~/.profile`, men-stage materi auth CLI yang sesuai ke container, memasang `acpx` ke prefix npm yang writable, lalu memasang CLI live yang diminta (`@anthropic-ai/claude-code`, `@openai/codex`, atau `@google/gemini-cli`) jika belum ada. +- Di dalam Docker, runner menetapkan `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` agar acpx mempertahankan env var provider dari profile yang telah di-source tetap tersedia untuk CLI harness anak. ### Resep live yang direkomendasikan -Allowlist yang sempit dan eksplisit adalah yang tercepat dan paling tidak flaky: +Allowlist yang sempit dan eksplisit paling cepat dan paling sedikit flakey: -- Model tunggal, langsung (tanpa gateway): +- Satu model, direct (tanpa gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- Model tunggal, gateway smoke: +- Satu model, gateway smoke: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Tool calling di beberapa provider: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Fokus Google (Gemini API key + Antigravity): +- Fokus Google (API key Gemini + Antigravity): - Gemini (API key): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Antigravity (OAuth): `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` Catatan: -- `google/...` menggunakan API Gemini (API key). +- `google/...` menggunakan Gemini API (API key). - `google-antigravity/...` menggunakan bridge OAuth Antigravity (endpoint agent bergaya Cloud Code Assist). -- `google-gemini-cli/...` menggunakan Gemini CLI lokal pada mesin Anda (auth terpisah + keanehan tooling). +- `google-gemini-cli/...` menggunakan CLI Gemini lokal di mesin Anda (auth dan keanehan tooling terpisah). - Gemini API vs Gemini CLI: - - API: OpenClaw memanggil API Gemini yang di-host Google melalui HTTP (auth API key / profil); inilah yang dimaksud sebagian besar pengguna dengan “Gemini”. - - CLI: OpenClaw men-shell out ke biner `gemini` lokal; ia memiliki auth sendiri dan dapat berperilaku berbeda (dukungan streaming/tool/version skew). + - API: OpenClaw memanggil Gemini API yang di-host Google melalui HTTP (API key / auth profil); inilah yang biasanya dimaksud kebanyakan pengguna dengan “Gemini”. + - CLI: OpenClaw melakukan shell out ke biner `gemini` lokal; ini memiliki auth sendiri dan dapat berperilaku berbeda (streaming/dukungan tool/perbedaan versi). ## Live: matriks model (apa yang kami cakup) -Tidak ada “daftar model CI” yang tetap (live bersifat opt-in), tetapi ini adalah model **yang direkomendasikan** untuk dicakup secara rutin pada mesin dev dengan key. +Tidak ada “daftar model CI” yang tetap (live bersifat opt-in), tetapi ini adalah model-model **yang direkomendasikan** untuk dicakup secara rutin di mesin pengembang dengan key. -### Set smoke modern (tool calling + image) +### Set smoke modern (tool calling + gambar) -Ini adalah run “model umum” yang kami harapkan tetap berfungsi: +Ini adalah eksekusi “model umum” yang kami harapkan tetap berfungsi: - OpenAI (non-Codex): `openai/gpt-5.4` (opsional: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` @@ -409,7 +411,7 @@ Ini adalah run “model umum” yang kami harapkan tetap berfungsi: - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Jalankan gateway smoke dengan tools + image: +Jalankan gateway smoke dengan tools + gambar: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` ### Baseline: tool calling (Read + Exec opsional) @@ -422,44 +424,44 @@ Pilih setidaknya satu per keluarga provider: - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Cakupan tambahan opsional (bagus jika ada): +Cakupan tambahan opsional (bagus untuk dimiliki): - xAI: `xai/grok-4` (atau versi terbaru yang tersedia) -- Mistral: `mistral/`… (pilih satu model yang mampu `tools` yang Anda aktifkan) +- Mistral: `mistral/`… (pilih satu model yang mampu menggunakan tools dan Anda aktifkan) - Cerebras: `cerebras/`… (jika Anda memiliki akses) - LM Studio: `lmstudio/`… (lokal; tool calling bergantung pada mode API) -### Visi: pengiriman image (attachment → pesan multimodal) +### Vision: pengiriman gambar (attachment → pesan multimodal) -Sertakan setidaknya satu model yang mendukung image di `OPENCLAW_LIVE_GATEWAY_MODELS` (varian Claude/Gemini/OpenAI yang mendukung vision, dsb.) untuk menjalankan probe image. +Sertakan setidaknya satu model yang mendukung gambar di `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/varian OpenAI yang mendukung vision, dan sebagainya) untuk menjalankan probe gambar. ### Agregator / gateway alternatif Jika Anda mengaktifkan key, kami juga mendukung pengujian melalui: -- OpenRouter: `openrouter/...` (ratusan model; gunakan `openclaw models scan` untuk menemukan kandidat yang mendukung tool+image) +- OpenRouter: `openrouter/...` (ratusan model; gunakan `openclaw models scan` untuk menemukan kandidat yang mendukung tool+gambar) - OpenCode: `opencode/...` untuk Zen dan `opencode-go/...` untuk Go (auth melalui `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) Provider lain yang dapat Anda sertakan dalam matriks live (jika Anda memiliki kredensial/config): -- Bawaan: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- Melalui `models.providers` (endpoint kustom): `minimax` (cloud/API), ditambah proxy yang kompatibel dengan OpenAI/Anthropic (LM Studio, vLLM, LiteLLM, dll.) +- Built-in: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` +- Melalui `models.providers` (endpoint kustom): `minimax` (cloud/API), plus proxy apa pun yang kompatibel dengan OpenAI/Anthropic (LM Studio, vLLM, LiteLLM, dll.) -Tip: jangan mencoba melakukan hardcode “semua model” di dokumen. Daftar yang berwenang adalah apa pun yang dikembalikan `discoverModels(...)` pada mesin Anda + key apa pun yang tersedia. +Tip: jangan mencoba meng-hardcode “semua model” di dokumentasi. Daftar otoritatif adalah apa pun yang dikembalikan `discoverModels(...)` di mesin Anda + key apa pun yang tersedia. -## Kredensial (jangan pernah commit) +## Kredensial (jangan pernah di-commit) -Live test menemukan kredensial dengan cara yang sama seperti CLI. Implikasi praktis: +Live test menemukan kredensial dengan cara yang sama seperti CLI. Implikasi praktisnya: - Jika CLI berfungsi, live test seharusnya menemukan key yang sama. -- Jika live test mengatakan “tidak ada kredensial”, debug dengan cara yang sama seperti saat Anda men-debug `openclaw models list` / pemilihan model. +- Jika live test mengatakan “tidak ada kredensial”, debug dengan cara yang sama seperti Anda men-debug `openclaw models list` / pemilihan model. -- Profil auth per-agent: `~/.openclaw/agents//agent/auth-profiles.json` (inilah yang dimaksud “key profil” pada live test) +- Profil auth per-agent: `~/.openclaw/agents//agent/auth-profiles.json` (inilah yang dimaksud dengan “profile keys” di live test) - Config: `~/.openclaw/openclaw.json` (atau `OPENCLAW_CONFIG_PATH`) -- Direktori state lama: `~/.openclaw/credentials/` (disalin ke home live yang di-stage jika ada, tetapi bukan profile-key store utama) -- Run live lokal menyalin config aktif, file `auth-profiles.json` per-agent, `credentials/` lama, dan direktori auth CLI eksternal yang didukung ke home pengujian sementara secara default; home live yang di-stage melewati `workspace/` dan `sandboxes/`, dan override path `agents.*.workspace` / `agentDir` dihapus agar probe tidak menyentuh workspace host asli Anda. +- Direktori status lama: `~/.openclaw/credentials/` (disalin ke home live yang di-stage jika ada, tetapi bukan penyimpanan utama profile-key) +- Eksekusi lokal live secara default menyalin config aktif, file `auth-profiles.json` per-agent, `credentials/` lama, dan direktori auth CLI eksternal yang didukung ke home pengujian sementara; home live yang di-stage melewati `workspace/` dan `sandboxes/`, dan override path `agents.*.workspace` / `agentDir` dihapus agar probe tidak menyentuh workspace host asli Anda. -Jika Anda ingin mengandalkan env key (misalnya diekspor dalam `~/.profile`), jalankan pengujian lokal setelah `source ~/.profile`, atau gunakan runner Docker di bawah (runner tersebut dapat me-mount `~/.profile` ke dalam container). +Jika Anda ingin mengandalkan key env (misalnya diekspor di `~/.profile`), jalankan pengujian lokal setelah `source ~/.profile`, atau gunakan runner Docker di bawah (runner tersebut dapat me-mount `~/.profile` ke container). ## Live Deepgram (transkripsi audio) @@ -479,19 +481,19 @@ Jika Anda ingin mengandalkan env key (misalnya diekspor dalam `~/.profile`), jal - Cakupan: - Menjalankan path image, video, dan `music_generate` comfy bawaan - Melewati setiap kapabilitas kecuali `models.providers.comfy.` dikonfigurasi - - Berguna setelah mengubah pengiriman workflow comfy, polling, unduhan, atau registrasi plugin + - Berguna setelah mengubah pengiriman workflow comfy, polling, download, atau registrasi plugin -## Live pembuatan image +## Live pembuatan gambar - Pengujian: `src/image-generation/runtime.live.test.ts` - Perintah: `pnpm test:live src/image-generation/runtime.live.test.ts` - Harness: `pnpm test:live:media image` - Cakupan: - - Mengenumerasi setiap plugin provider pembuatan image yang terdaftar - - Memuat env var provider yang hilang dari shell login Anda (`~/.profile`) sebelum probing - - Menggunakan API key live/env mendahului profil auth yang tersimpan secara default, sehingga key pengujian usang dalam `auth-profiles.json` tidak menutupi kredensial shell nyata - - Melewati provider tanpa auth/profil/model yang dapat digunakan - - Menjalankan varian stock image-generation melalui kapabilitas runtime bersama: + - Mengenumerasi setiap plugin provider image-generation yang terdaftar + - Memuat env var provider yang hilang dari login shell Anda (`~/.profile`) sebelum melakukan probe + - Secara default menggunakan API key live/env lebih dahulu daripada profil auth yang disimpan, sehingga key pengujian lama di `auth-profiles.json` tidak menutupi kredensial shell asli + - Melewati provider yang tidak memiliki auth/profil/model yang dapat digunakan + - Menjalankan varian image-generation bawaan melalui kapabilitas runtime bersama: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` @@ -504,7 +506,7 @@ Jika Anda ingin mengandalkan env key (misalnya diekspor dalam `~/.profile`), jal - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` - Perilaku auth opsional: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` untuk memaksakan auth profile-store dan mengabaikan override env-only + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` untuk memaksa auth profile-store dan mengabaikan override khusus env ## Live pembuatan musik @@ -512,23 +514,23 @@ Jika Anda ingin mengandalkan env key (misalnya diekspor dalam `~/.profile`), jal - Aktifkan: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Harness: `pnpm test:live:media music` - Cakupan: - - Menjalankan path provider pembuatan musik bawaan bersama + - Menjalankan path provider music-generation bawaan bersama - Saat ini mencakup Google dan MiniMax - - Memuat env var provider dari shell login Anda (`~/.profile`) sebelum probing - - Menggunakan API key live/env mendahului profil auth yang tersimpan secara default, sehingga key pengujian usang dalam `auth-profiles.json` tidak menutupi kredensial shell nyata - - Melewati provider tanpa auth/profil/model yang dapat digunakan + - Memuat env var provider dari login shell Anda (`~/.profile`) sebelum melakukan probe + - Secara default menggunakan API key live/env lebih dahulu daripada profil auth yang disimpan, sehingga key pengujian lama di `auth-profiles.json` tidak menutupi kredensial shell asli + - Melewati provider yang tidak memiliki auth/profil/model yang dapat digunakan - Menjalankan kedua mode runtime yang dideklarasikan jika tersedia: - - `generate` dengan input prompt-only + - `generate` dengan input prompt saja - `edit` saat provider mendeklarasikan `capabilities.edit.enabled` - - Cakupan shared-lane saat ini: + - Cakupan current shared-lane: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: file live Comfy terpisah, bukan sapuan bersama ini + - `comfy`: file live Comfy terpisah, bukan sweep bersama ini - Penyempitan opsional: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` - Perilaku auth opsional: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` untuk memaksakan auth profile-store dan mengabaikan override env-only + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` untuk memaksa auth profile-store dan mengabaikan override khusus env ## Live pembuatan video @@ -536,163 +538,163 @@ Jika Anda ingin mengandalkan env key (misalnya diekspor dalam `~/.profile`), jal - Aktifkan: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harness: `pnpm test:live:media video` - Cakupan: - - Menjalankan path provider pembuatan video bawaan bersama - - Memuat env var provider dari shell login Anda (`~/.profile`) sebelum probing - - Menggunakan API key live/env mendahului profil auth yang tersimpan secara default, sehingga key pengujian usang dalam `auth-profiles.json` tidak menutupi kredensial shell nyata - - Melewati provider tanpa auth/profil/model yang dapat digunakan + - Menjalankan path provider video-generation bawaan bersama + - Memuat env var provider dari login shell Anda (`~/.profile`) sebelum melakukan probe + - Secara default menggunakan API key live/env lebih dahulu daripada profil auth yang disimpan, sehingga key pengujian lama di `auth-profiles.json` tidak menutupi kredensial shell asli + - Melewati provider yang tidak memiliki auth/profil/model yang dapat digunakan - Menjalankan kedua mode runtime yang dideklarasikan jika tersedia: - - `generate` dengan input prompt-only - - `imageToVideo` saat provider mendeklarasikan `capabilities.imageToVideo.enabled` dan provider/model yang dipilih menerima input image lokal berbasis buffer dalam sapuan bersama - - `videoToVideo` saat provider mendeklarasikan `capabilities.videoToVideo.enabled` dan provider/model yang dipilih menerima input video lokal berbasis buffer dalam sapuan bersama - - Provider `imageToVideo` saat ini yang dideklarasikan tetapi dilewati dalam sapuan bersama: - - `vydra` karena `veo3` bawaan hanya teks dan `kling` bawaan memerlukan URL image jarak jauh + - `generate` dengan input prompt saja + - `imageToVideo` saat provider mendeklarasikan `capabilities.imageToVideo.enabled` dan provider/model yang dipilih menerima input gambar lokal berbasis buffer dalam sweep bersama + - `videoToVideo` saat provider mendeklarasikan `capabilities.videoToVideo.enabled` dan provider/model yang dipilih menerima input video lokal berbasis buffer dalam sweep bersama + - Provider `imageToVideo` yang saat ini dideklarasikan tetapi di-skip dalam sweep bersama: + - `vydra` karena `veo3` bawaan hanya mendukung teks dan `kling` bawaan memerlukan URL gambar jarak jauh - Cakupan Vydra spesifik provider: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - file tersebut menjalankan text-to-video `veo3` ditambah lane `kling` yang secara default menggunakan fixture URL image jarak jauh + - file itu menjalankan lane text-to-video `veo3` plus lane `kling` yang secara default menggunakan fixture URL gambar jarak jauh - Cakupan live `videoToVideo` saat ini: - - `runway` hanya ketika model yang dipilih adalah `runway/gen4_aleph` - - Provider `videoToVideo` saat ini yang dideklarasikan tetapi dilewati dalam sapuan bersama: + - `runway` hanya saat model yang dipilih adalah `runway/gen4_aleph` + - Provider `videoToVideo` yang saat ini dideklarasikan tetapi di-skip dalam sweep bersama: - `alibaba`, `qwen`, `xai` karena path tersebut saat ini memerlukan URL referensi `http(s)` / MP4 jarak jauh - - `google` karena lane Gemini/Veo bersama saat ini menggunakan input lokal berbasis buffer dan path itu tidak diterima dalam sapuan bersama - - `openai` karena lane bersama saat ini tidak memiliki jaminan akses video inpaint/remix spesifik organisasi + - `google` karena lane Gemini/Veo bersama saat ini menggunakan input lokal berbasis buffer dan path itu tidak diterima dalam sweep bersama + - `openai` karena lane bersama saat ini tidak memiliki jaminan akses video inpaint/remix spesifik org - Penyempitan opsional: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - Perilaku auth opsional: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` untuk memaksakan auth profile-store dan mengabaikan override env-only + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` untuk memaksa auth profile-store dan mengabaikan override khusus env ## Harness live media - Perintah: `pnpm test:live:media` - Tujuan: - - Menjalankan suite live image, music, dan video bersama melalui entrypoint native repo tunggal + - Menjalankan suite live gambar, musik, dan video bersama melalui satu entrypoint native repo - Memuat otomatis env var provider yang hilang dari `~/.profile` - - Mempersempit otomatis tiap suite ke provider yang saat ini memiliki auth yang dapat digunakan secara default - - Menggunakan ulang `scripts/test-live.mjs`, sehingga perilaku heartbeat dan quiet-mode tetap konsisten + - Secara default mempersempit otomatis setiap suite ke provider yang saat ini memiliki auth yang dapat digunakan + - Menggunakan kembali `scripts/test-live.mjs`, sehingga perilaku heartbeat dan quiet-mode tetap konsisten - Contoh: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## Runner Docker (opsional, pemeriksaan "berfungsi di Linux") +## Runner Docker (opsional untuk pemeriksaan "berfungsi di Linux") Runner Docker ini terbagi menjadi dua kelompok: -- Runner live-model: `test:docker:live-models` dan `test:docker:live-gateway` hanya menjalankan file live profile-key yang cocok di dalam image Docker repo (`src/agents/models.profiles.live.test.ts` dan `src/gateway/gateway-models.profiles.live.test.ts`), me-mount direktori config lokal dan workspace Anda (serta melakukan source `~/.profile` jika di-mount). Entrypoint lokal yang sesuai adalah `test:live:models-profiles` dan `test:live:gateway-profiles`. -- Runner live Docker secara default menggunakan batas smoke yang lebih kecil agar sapuan Docker penuh tetap praktis: +- Runner live-model: `test:docker:live-models` dan `test:docker:live-gateway` hanya menjalankan file live profile-key yang cocok di dalam image Docker repo (`src/agents/models.profiles.live.test.ts` dan `src/gateway/gateway-models.profiles.live.test.ts`), dengan me-mount direktori config dan workspace lokal Anda (serta melakukan source `~/.profile` jika di-mount). Entrypoint lokal yang sesuai adalah `test:live:models-profiles` dan `test:live:gateway-profiles`. +- Runner live Docker secara default menggunakan batas smoke yang lebih kecil agar sweep Docker penuh tetap praktis: `test:docker:live-models` default ke `OPENCLAW_LIVE_MAX_MODELS=12`, dan `test:docker:live-gateway` default ke `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000`, dan `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Override env var tersebut saat Anda - memang menginginkan pemindaian yang lebih besar dan menyeluruh. -- `test:docker:all` membangun image live Docker sekali melalui `test:docker:live-build`, lalu menggunakannya kembali untuk dua lane live Docker. -- Runner smoke container: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels`, dan `test:docker:plugins` menjalankan satu atau lebih container nyata dan memverifikasi path integrasi tingkat lebih tinggi. + memang ingin pemindaian lengkap yang lebih besar. +- `test:docker:all` membangun image live Docker sekali melalui `test:docker:live-build`, lalu menggunakannya kembali untuk dua lane live Docker tersebut. +- Runner smoke container: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels`, dan `test:docker:plugins` mem-boot satu atau lebih container nyata dan memverifikasi path integrasi tingkat lebih tinggi. -Runner Docker live-model juga hanya bind-mount home auth CLI yang diperlukan (atau semua yang didukung saat run tidak dipersempit), lalu menyalinnya ke home container sebelum run sehingga OAuth CLI eksternal dapat me-refresh token tanpa mengubah auth store host: +Runner Docker live-model juga me-mount hanya home auth CLI yang diperlukan (atau semua yang didukung saat eksekusi tidak dipersempit), lalu menyalinnya ke home container sebelum eksekusi agar OAuth CLI eksternal dapat menyegarkan token tanpa mengubah penyimpanan auth host: -- Model langsung: `pnpm test:docker:live-models` (script: `scripts/test-live-models-docker.sh`) -- Smoke bind ACP: `pnpm test:docker:live-acp-bind` (script: `scripts/test-live-acp-bind-docker.sh`) -- Smoke backend CLI: `pnpm test:docker:live-cli-backend` (script: `scripts/test-live-cli-backend-docker.sh`) -- Gateway + agent dev: `pnpm test:docker:live-gateway` (script: `scripts/test-live-gateway-models-docker.sh`) -- Smoke live Open WebUI: `pnpm test:docker:openwebui` (script: `scripts/e2e/openwebui-docker.sh`) -- Wizard onboarding (TTY, scaffolding penuh): `pnpm test:docker:onboard` (script: `scripts/e2e/onboard-docker.sh`) -- Jaringan gateway (dua container, auth + health WS): `pnpm test:docker:gateway-network` (script: `scripts/e2e/gateway-network-docker.sh`) -- Bridge channel MCP (Gateway ter-seed + bridge stdio + smoke notification-frame Claude mentah): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`) -- Plugin (smoke instalasi + alias `/plugin` + semantik restart bundle Claude): `pnpm test:docker:plugins` (script: `scripts/e2e/plugins-docker.sh`) +- Model direct: `pnpm test:docker:live-models` (skrip: `scripts/test-live-models-docker.sh`) +- Smoke bind ACP: `pnpm test:docker:live-acp-bind` (skrip: `scripts/test-live-acp-bind-docker.sh`) +- Smoke backend CLI: `pnpm test:docker:live-cli-backend` (skrip: `scripts/test-live-cli-backend-docker.sh`) +- Gateway + dev agent: `pnpm test:docker:live-gateway` (skrip: `scripts/test-live-gateway-models-docker.sh`) +- Smoke live Open WebUI: `pnpm test:docker:openwebui` (skrip: `scripts/e2e/openwebui-docker.sh`) +- Wizard onboarding (TTY, scaffolding penuh): `pnpm test:docker:onboard` (skrip: `scripts/e2e/onboard-docker.sh`) +- Jaringan gateway (dua container, auth + health WS): `pnpm test:docker:gateway-network` (skrip: `scripts/e2e/gateway-network-docker.sh`) +- Bridge channel MCP (Gateway seed + bridge stdio + smoke raw Claude notification-frame): `pnpm test:docker:mcp-channels` (skrip: `scripts/e2e/mcp-channels-docker.sh`) +- Plugins (smoke instalasi + alias `/plugin` + semantik restart Claude-bundle): `pnpm test:docker:plugins` (skrip: `scripts/e2e/plugins-docker.sh`) -Runner Docker live-model juga me-bind-mount checkout saat ini sebagai read-only dan +Runner Docker live-model juga me-mount checkout saat ini sebagai read-only dan men-stage-nya ke workdir sementara di dalam container. Ini menjaga image runtime -tetap ramping sambil tetap menjalankan Vitest terhadap source/config lokal Anda yang tepat. +tetap ramping sambil tetap menjalankan Vitest terhadap source/config lokal Anda secara persis. Langkah staging melewati cache lokal besar dan output build aplikasi seperti -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, dan direktori output -`.build` lokal aplikasi atau Gradle sehingga run live Docker tidak menghabiskan waktu ber menit-menit menyalin -artefak spesifik mesin. -Runner ini juga menyetel `OPENCLAW_SKIP_CHANNELS=1` agar probe live gateway tidak memulai +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, serta +direktori output `.build` lokal aplikasi atau Gradle sehingga Docker live run tidak +menghabiskan waktu beberapa menit untuk menyalin artefak spesifik mesin. +Runner ini juga menetapkan `OPENCLAW_SKIP_CHANNELS=1` sehingga probe live gateway tidak memulai worker channel Telegram/Discord/dll. nyata di dalam container. `test:docker:live-models` tetap menjalankan `pnpm test:live`, jadi teruskan juga -`OPENCLAW_LIVE_GATEWAY_*` saat Anda perlu mempersempit atau mengecualikan cakupan live -gateway dari lane Docker tersebut. -`test:docker:openwebui` adalah smoke kompatibilitas tingkat lebih tinggi: ia menjalankan -container gateway OpenClaw dengan endpoint HTTP yang kompatibel OpenAI diaktifkan, -menjalankan container Open WebUI yang dipin terhadap gateway tersebut, masuk melalui +`OPENCLAW_LIVE_GATEWAY_*` saat Anda perlu mempersempit atau mengecualikan cakupan +live gateway dari lane Docker tersebut. +`test:docker:openwebui` adalah smoke kompatibilitas tingkat lebih tinggi: runner ini memulai +container gateway OpenClaw dengan endpoint HTTP yang kompatibel dengan OpenAI diaktifkan, +memulai container Open WebUI yang dipatok terhadap gateway tersebut, melakukan sign in melalui Open WebUI, memverifikasi `/api/models` mengekspos `openclaw/default`, lalu mengirim permintaan chat nyata melalui proxy `/api/chat/completions` milik Open WebUI. -Run pertama bisa terasa lebih lambat karena Docker mungkin perlu menarik -image Open WebUI dan Open WebUI mungkin perlu menyelesaikan cold-start setup-nya sendiri. +Eksekusi pertama bisa terasa lebih lambat karena Docker mungkin perlu menarik image +Open WebUI dan Open WebUI mungkin perlu menyelesaikan setup cold-start-nya sendiri. Lane ini mengharapkan key model live yang dapat digunakan, dan `OPENCLAW_PROFILE_FILE` -(`~/.profile` secara default) adalah cara utama untuk menyediakannya pada run yang di-Docker-kan. -Run yang berhasil mencetak payload JSON kecil seperti `{ "ok": true, "model": +(`~/.profile` secara default) adalah cara utama untuk menyediakannya dalam eksekusi berbasis Docker. +Eksekusi yang berhasil mencetak payload JSON kecil seperti `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` sengaja dibuat deterministik dan tidak memerlukan -akun Telegram, Discord, atau iMessage nyata. Ia menjalankan container Gateway -ter-seed, memulai container kedua yang memunculkan `openclaw mcp serve`, lalu -memverifikasi penemuan percakapan yang dirutekan, pembacaan transcript, metadata attachment, +akun Telegram, Discord, atau iMessage nyata. Runner ini mem-boot Gateway seed +container, memulai container kedua yang memunculkan `openclaw mcp serve`, lalu +memverifikasi penemuan percakapan yang dirutekan, pembacaan transkrip, metadata attachment, perilaku antrean event live, routing pengiriman keluar, serta notifikasi channel + -izin bergaya Claude melalui bridge stdio MCP yang nyata. Pemeriksaan notifikasi +izin bergaya Claude melalui bridge MCP stdio yang nyata. Pemeriksaan notifikasi memeriksa frame MCP stdio mentah secara langsung sehingga smoke memvalidasi apa yang -benar-benar dikeluarkan oleh bridge, bukan sekadar apa yang kebetulan diekspos oleh SDK klien tertentu. +sebenarnya dipancarkan bridge, bukan hanya apa yang kebetulan diekspos oleh SDK klien tertentu. -Smoke thread plain-language ACP manual (bukan CI): +Smoke thread bahasa alami ACP manual (bukan CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Pertahankan script ini untuk alur kerja regresi/debug. Script ini mungkin diperlukan lagi untuk validasi routing thread ACP, jadi jangan dihapus. +- Pertahankan skrip ini untuk alur kerja regresi/debug. Skrip ini mungkin diperlukan lagi untuk validasi routing thread ACP, jadi jangan dihapus. Env var yang berguna: - `OPENCLAW_CONFIG_DIR=...` (default: `~/.openclaw`) di-mount ke `/home/node/.openclaw` - `OPENCLAW_WORKSPACE_DIR=...` (default: `~/.openclaw/workspace`) di-mount ke `/home/node/.openclaw/workspace` - `OPENCLAW_PROFILE_FILE=...` (default: `~/.profile`) di-mount ke `/home/node/.profile` dan di-source sebelum menjalankan pengujian -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (default: `~/.cache/openclaw/docker-cli-tools`) di-mount ke `/home/node/.npm-global` untuk instalasi CLI cache di dalam Docker -- Direktori/file auth CLI eksternal di bawah `$HOME` di-mount read-only di bawah `/host-auth...`, lalu disalin ke `/home/node/...` sebelum pengujian dimulai +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (default: `~/.cache/openclaw/docker-cli-tools`) di-mount ke `/home/node/.npm-global` untuk instalasi CLI yang di-cache di dalam Docker +- Direktori/file auth CLI eksternal di bawah `$HOME` di-mount sebagai read-only di bawah `/host-auth...`, lalu disalin ke `/home/node/...` sebelum pengujian dimulai - Direktori default: `.minimax` - File default: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Run provider yang dipersempit hanya me-mount direktori/file yang diperlukan sesuai inferensi dari `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Override manual dengan `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none`, atau daftar dipisah koma seperti `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` -- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` untuk mempersempit run + - Eksekusi provider yang dipersempit hanya me-mount direktori/file yang diperlukan yang diinferensikan dari `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - Override manual dengan `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none`, atau daftar dipisahkan koma seperti `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` +- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` untuk mempersempit eksekusi - `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` untuk memfilter provider di dalam container - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` untuk memastikan kredensial berasal dari profile store (bukan env) -- `OPENCLAW_OPENWEBUI_MODEL=...` untuk memilih model yang diekspos gateway bagi smoke Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...` untuk menimpa prompt pemeriksaan nonce yang digunakan smoke Open WebUI -- `OPENWEBUI_IMAGE=...` untuk menimpa tag image Open WebUI yang dipin +- `OPENCLAW_OPENWEBUI_MODEL=...` untuk memilih model yang diekspos gateway untuk smoke Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...` untuk mengganti prompt pemeriksaan nonce yang digunakan oleh smoke Open WebUI +- `OPENWEBUI_IMAGE=...` untuk mengganti tag image Open WebUI yang dipatok -## Kewarasan dokumen +## Pemeriksaan dokumentasi -Jalankan pemeriksaan dokumen setelah pengeditan dokumen: `pnpm check:docs`. -Jalankan validasi anchor Mintlify penuh saat Anda juga memerlukan pemeriksaan heading dalam halaman: `pnpm docs:check-links:anchors`. +Jalankan pemeriksaan dokumen setelah mengedit dokumen: `pnpm check:docs`. +Jalankan validasi anchor Mintlify penuh saat Anda juga memerlukan pemeriksaan heading di dalam halaman: `pnpm docs:check-links:anchors`. ## Regresi offline (aman untuk CI) Ini adalah regresi “pipeline nyata” tanpa provider nyata: -- Tool calling gateway (OpenAI tiruan, gateway nyata + loop agent): `src/gateway/gateway.test.ts` (kasus: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Tool calling gateway (mock OpenAI, gateway + loop agent nyata): `src/gateway/gateway.test.ts` (kasus: "runs a mock OpenAI tool call end-to-end via gateway agent loop") - Wizard gateway (WS `wizard.start`/`wizard.next`, menulis config + auth dipaksakan): `src/gateway/gateway.test.ts` (kasus: "runs wizard over ws and writes auth token config") -## Evaluasi keandalan agent (Skills) +## Evals keandalan agent (Skills) -Kami sudah memiliki beberapa pengujian aman-CI yang berperilaku seperti “evaluasi keandalan agent”: +Kami sudah memiliki beberapa pengujian aman untuk CI yang berperilaku seperti “evals keandalan agent”: -- Tool-calling tiruan melalui gateway nyata + loop agent (`src/gateway/gateway.test.ts`). +- Mock tool-calling melalui gateway + loop agent nyata (`src/gateway/gateway.test.ts`). - Alur wizard end-to-end yang memvalidasi wiring session dan efek config (`src/gateway/gateway.test.ts`). -Yang masih kurang untuk skills (lihat [Skills](/id/tools/skills)): +Yang masih kurang untuk Skills (lihat [Skills](/id/tools/skills)): -- **Pengambilan keputusan:** ketika skill dicantumkan dalam prompt, apakah agent memilih skill yang tepat (atau menghindari yang tidak relevan)? +- **Pengambilan keputusan:** saat Skills dicantumkan dalam prompt, apakah agent memilih skill yang tepat (atau menghindari yang tidak relevan)? - **Kepatuhan:** apakah agent membaca `SKILL.md` sebelum digunakan dan mengikuti langkah/argumen yang diwajibkan? -- **Kontrak alur kerja:** skenario multi-giliran yang menegaskan urutan tool, carryover riwayat session, dan boundary sandbox. +- **Kontrak alur kerja:** skenario multi-giliran yang menegaskan urutan tool, carryover riwayat session, dan batas sandbox. -Evaluasi di masa depan harus tetap deterministik terlebih dahulu: +Evals di masa mendatang sebaiknya tetap deterministik terlebih dahulu: -- Scenario runner menggunakan provider tiruan untuk menegaskan pemanggilan tool + urutan, pembacaan file skill, dan wiring session. -- Suite kecil berisi skenario berfokus pada skill (gunakan vs hindari, gating, injeksi prompt). -- Evaluasi live opsional (opt-in, di-gate oleh env) hanya setelah suite aman-CI tersedia. +- Runner skenario menggunakan provider mock untuk menegaskan pemanggilan tool + urutan, pembacaan file skill, dan wiring session. +- Suite kecil skenario yang berfokus pada skill (gunakan vs hindari, gating, prompt injection). +- Evals live opsional (opt-in, dibatasi env) hanya setelah suite aman untuk CI tersedia. -## Contract test (bentuk plugin dan channel) +## Contract tests (bentuk plugin dan channel) -Contract test memverifikasi bahwa setiap plugin dan channel yang terdaftar mematuhi -kontrak interface-nya. Contract test mengiterasi semua plugin yang ditemukan dan menjalankan serangkaian -asersi bentuk dan perilaku. Lane unit default `pnpm test` sengaja +Contract tests memverifikasi bahwa setiap plugin dan channel yang terdaftar mematuhi +kontrak antarmukanya. Contract tests mengiterasi semua plugin yang ditemukan dan menjalankan +serangkaian asersi bentuk dan perilaku. Lane unit default `pnpm test` sengaja melewati file seam bersama dan smoke ini; jalankan perintah contract secara eksplisit saat Anda menyentuh surface channel atau provider bersama. @@ -706,9 +708,9 @@ saat Anda menyentuh surface channel atau provider bersama. Terletak di `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - Bentuk plugin dasar (id, name, capabilities) -- **setup** - Kontrak setup wizard -- **session-binding** - Perilaku session binding +- **plugin** - Bentuk plugin dasar (id, nama, kapabilitas) +- **setup** - Kontrak wizard setup +- **session-binding** - Perilaku pengikatan session - **outbound-payload** - Struktur payload pesan - **inbound** - Penanganan pesan masuk - **actions** - Handler aksi channel @@ -733,26 +735,26 @@ Terletak di `src/plugins/contracts/*.contract.test.ts`: - **discovery** - Penemuan plugin - **loader** - Pemuatan plugin - **runtime** - Runtime provider -- **shape** - Bentuk/interface plugin -- **wizard** - Setup wizard +- **shape** - Bentuk/antarmuka plugin +- **wizard** - Wizard setup -### Kapan dijalankan +### Kapan menjalankannya - Setelah mengubah ekspor atau subpath plugin-sdk -- Setelah menambahkan atau mengubah plugin channel atau provider -- Setelah merombak registrasi atau penemuan plugin +- Setelah menambahkan atau memodifikasi channel atau plugin provider +- Setelah merefaktor registrasi atau penemuan plugin -Contract test berjalan di CI dan tidak memerlukan API key nyata. +Contract tests berjalan di CI dan tidak memerlukan API key nyata. ## Menambahkan regresi (panduan) -Saat Anda memperbaiki masalah provider/model yang ditemukan di live: +Saat Anda memperbaiki masalah provider/model yang ditemukan secara live: -- Tambahkan regresi aman-CI jika memungkinkan (provider tiruan/stub, atau tangkap transformasi bentuk request yang tepat) -- Jika masalah itu secara inheren hanya live (rate limit, kebijakan auth), buat live test tetap sempit dan opt-in melalui env var -- Lebih baik menargetkan lapisan terkecil yang menangkap bug: - - bug konversi/replay request provider → direct models test - - bug pipeline session/riwayat/tool gateway → gateway live smoke atau pengujian tiruan gateway yang aman-CI +- Tambahkan regresi yang aman untuk CI jika memungkinkan (mock/stub provider, atau tangkap transformasi bentuk permintaan yang tepat) +- Jika secara inheren hanya bisa live (rate limit, kebijakan auth), pertahankan live test tetap sempit dan opt-in melalui env var +- Sebaiknya targetkan lapisan terkecil yang menangkap bug: + - bug konversi/replay permintaan provider → direct models test + - bug pipeline gateway session/history/tool → gateway live smoke atau pengujian mock gateway yang aman untuk CI - Guardrail traversal SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` menurunkan satu target sampel per kelas SecretRef dari metadata registry (`listSecretTargetRegistryEntries()`), lalu menegaskan bahwa id exec segmen traversal ditolak. - - Jika Anda menambahkan keluarga target SecretRef `includeInPlan` baru di `src/secrets/target-registry-data.ts`, perbarui `classifyTargetClass` dalam pengujian tersebut. Pengujian sengaja gagal pada id target yang tidak terklasifikasi sehingga kelas baru tidak bisa dilewati secara diam-diam. + - `src/secrets/exec-secret-ref-id-parity.test.ts` menurunkan satu target sampel per kelas SecretRef dari metadata registry (`listSecretTargetRegistryEntries()`), lalu menegaskan id exec traversal-segment ditolak. + - Jika Anda menambahkan keluarga target SecretRef `includeInPlan` baru di `src/secrets/target-registry-data.ts`, perbarui `classifyTargetClass` dalam pengujian itu. Pengujian ini sengaja gagal pada id target yang tidak terklasifikasi sehingga kelas baru tidak bisa dilewati secara diam-diam. diff --git a/docs/id/plans/2026-04-05-002-refactor-real-plugin-sdk-workspace-plan.md b/docs/id/plans/2026-04-05-002-refactor-real-plugin-sdk-workspace-plan.md deleted file mode 100644 index 86e626adc..000000000 --- a/docs/id/plans/2026-04-05-002-refactor-real-plugin-sdk-workspace-plan.md +++ /dev/null @@ -1,584 +0,0 @@ ---- -date: 2026-04-05T00:00:00Z -status: active -title: 'refactor: Menjadikan plugin-sdk paket workspace nyata secara bertahap' -type: refactor -x-i18n: - generated_at: "2026-04-07T09:15:50Z" - model: gpt-5.4 - provider: openai - source_hash: ea1ca41846363c506a0db6dbca746e840d7c71ca82bbfc5277af9e2ae7f6b070 - source_path: plans/2026-04-05-002-refactor-real-plugin-sdk-workspace-plan.md - workflow: 15 ---- - -# refactor: Menjadikan plugin-sdk paket workspace nyata secara bertahap - -## Ringkasan - -Rencana ini memperkenalkan paket workspace nyata untuk plugin SDK di -`packages/plugin-sdk` dan menggunakannya untuk mengikutsertakan gelombang kecil -pertama dari ekstensi ke batas paket yang ditegakkan compiler. Tujuannya adalah -membuat impor relatif ilegal gagal di bawah `tsc` normal untuk sekumpulan -ekstensi provider bawaan yang dipilih, tanpa memaksakan migrasi seluruh repo -atau permukaan konflik merge yang besar. - -Langkah inkremental kuncinya adalah menjalankan dua mode secara paralel untuk -sementara waktu: - -| Mode | Bentuk impor | Siapa yang menggunakannya | Penegakan | -| ----------- | ----------------------- | ------------------------------------ | -------------------------------------------- | -| Mode lama | `openclaw/plugin-sdk/*` | semua ekstensi yang belum ikut serta | perilaku permisif saat ini tetap dipertahankan | -| Mode opt-in | `@openclaw/plugin-sdk/*` | hanya ekstensi gelombang pertama | `rootDir` lokal-paket + referensi project | - -## Kerangka masalah - -Repo saat ini mengekspor permukaan plugin SDK publik yang besar, tetapi itu -bukan paket workspace nyata. Sebaliknya: - -- `tsconfig.json` root memetakan `openclaw/plugin-sdk/*` langsung ke - `src/plugin-sdk/*.ts` -- ekstensi yang belum ikut serta dalam eksperimen sebelumnya masih berbagi - perilaku alias source global tersebut -- menambahkan `rootDir` hanya bekerja ketika impor SDK yang diizinkan berhenti - di-resolve ke source repo mentah - -Itu berarti repo dapat mendeskripsikan kebijakan batas yang diinginkan, tetapi -TypeScript tidak menegakkannya secara bersih untuk sebagian besar ekstensi. - -Yang Anda inginkan adalah jalur inkremental yang: - -- menjadikan `plugin-sdk` nyata -- memindahkan SDK menuju paket workspace bernama `@openclaw/plugin-sdk` -- hanya mengubah sekitar 10 ekstensi dalam PR pertama -- membiarkan sisa tree ekstensi tetap memakai skema lama sampai pembersihan berikutnya -- menghindari alur kerja `tsconfig.plugin-sdk.dts.json` + deklarasi hasil generate postinstall - sebagai mekanisme utama untuk rollout gelombang pertama - -## Jejak kebutuhan - -- R1. Buat paket workspace nyata untuk plugin SDK di bawah `packages/`. -- R2. Beri nama paket baru `@openclaw/plugin-sdk`. -- R3. Berikan paket SDK baru `package.json` dan `tsconfig.json` miliknya sendiri. -- R4. Tetap buat impor lama `openclaw/plugin-sdk/*` berfungsi untuk ekstensi - yang belum ikut serta selama masa migrasi. -- R5. Ikutsertakan hanya gelombang kecil pertama ekstensi dalam PR pertama. -- R6. Ekstensi gelombang pertama harus gagal tertutup untuk impor relatif yang keluar - dari root paket mereka. -- R7. Ekstensi gelombang pertama harus mengonsumsi SDK melalui dependensi paket - dan referensi project TS, bukan melalui alias `paths` root. -- R8. Rencana ini harus menghindari langkah wajib generate postinstall seluruh repo - untuk kebenaran editor. -- R9. Rollout gelombang pertama harus dapat ditinjau dan dapat di-merge sebagai PR - berukuran sedang, bukan refaktor seluruh repo dengan 300+ file. - -## Batas cakupan - -- Tidak ada migrasi penuh semua ekstensi bawaan dalam PR pertama. -- Tidak ada keharusan menghapus `src/plugin-sdk` dalam PR pertama. -- Tidak ada keharusan memasang ulang setiap path build atau test root agar - segera menggunakan paket baru. -- Tidak ada upaya memaksa squiggle VS Code untuk setiap ekstensi yang belum ikut serta. -- Tidak ada pembersihan lint luas untuk sisa tree ekstensi. -- Tidak ada perubahan perilaku runtime besar di luar resolusi impor, kepemilikan - paket, dan penegakan batas untuk ekstensi yang ikut serta. - -## Konteks & riset - -### Kode dan pola yang relevan - -- `pnpm-workspace.yaml` sudah mencakup `packages/*` dan `extensions/*`, jadi - paket workspace baru di bawah `packages/plugin-sdk` sesuai dengan tata letak - repo yang ada. -- Paket workspace yang ada seperti `packages/memory-host-sdk/package.json` - dan `packages/plugin-package-contract/package.json` sudah menggunakan peta - `exports` lokal-paket yang berakar di `src/*.ts`. -- `package.json` root saat ini memublikasikan permukaan SDK melalui `./plugin-sdk` - dan `./plugin-sdk/*` exports yang didukung oleh `dist/plugin-sdk/*.js` dan - `dist/plugin-sdk/*.d.ts`. -- `src/plugin-sdk/entrypoints.ts` dan `scripts/lib/plugin-sdk-entrypoints.json` - sudah bertindak sebagai inventaris entrypoint kanonis untuk permukaan SDK. -- `tsconfig.json` root saat ini memetakan: - - `openclaw/plugin-sdk` -> `src/plugin-sdk/index.ts` - - `openclaw/plugin-sdk/*` -> `src/plugin-sdk/*.ts` -- Eksperimen batas sebelumnya menunjukkan bahwa `rootDir` lokal-paket bekerja untuk - impor relatif ilegal hanya setelah impor SDK yang diizinkan berhenti di-resolve ke source mentah - di luar paket ekstensi. - -### Kumpulan ekstensi gelombang pertama - -Rencana ini mengasumsikan gelombang pertama adalah kumpulan yang berat di provider -dan paling kecil kemungkinannya menarik edge case runtime channel yang kompleks: - -- `extensions/anthropic` -- `extensions/exa` -- `extensions/firecrawl` -- `extensions/groq` -- `extensions/mistral` -- `extensions/openai` -- `extensions/perplexity` -- `extensions/tavily` -- `extensions/together` -- `extensions/xai` - -### Inventaris permukaan SDK gelombang pertama - -Ekstensi gelombang pertama saat ini mengimpor subset subpath SDK yang dapat -dikelola. Paket `@openclaw/plugin-sdk` awal hanya perlu mencakup yang berikut: - -- `agent-runtime` -- `cli-runtime` -- `config-runtime` -- `core` -- `image-generation` -- `media-runtime` -- `media-understanding` -- `plugin-entry` -- `plugin-runtime` -- `provider-auth` -- `provider-auth-api-key` -- `provider-auth-login` -- `provider-auth-runtime` -- `provider-catalog-shared` -- `provider-entry` -- `provider-http` -- `provider-model-shared` -- `provider-onboard` -- `provider-stream-family` -- `provider-stream-shared` -- `provider-tools` -- `provider-usage` -- `provider-web-fetch` -- `provider-web-search` -- `realtime-transcription` -- `realtime-voice` -- `runtime-env` -- `secret-input` -- `security-runtime` -- `speech` -- `testing` - -### Pembelajaran institusional - -- Tidak ada entri `docs/solutions/` yang relevan di worktree ini. - -### Referensi eksternal - -- Tidak diperlukan riset eksternal untuk rencana ini. Repo sudah berisi pola - paket workspace dan ekspor SDK yang relevan. - -## Keputusan teknis utama - -- Perkenalkan `@openclaw/plugin-sdk` sebagai paket workspace baru sambil - mempertahankan permukaan lama root `openclaw/plugin-sdk/*` selama migrasi. - Alasan: ini memungkinkan sekumpulan ekstensi gelombang pertama berpindah ke - resolusi paket nyata tanpa memaksa setiap ekstensi dan setiap path build root - berubah sekaligus. - -- Gunakan config basis batas opt-in khusus seperti - `extensions/tsconfig.package-boundary.base.json` alih-alih mengganti basis - ekstensi yang ada untuk semua orang. - Alasan: repo perlu mendukung mode ekstensi lama dan opt-in secara bersamaan - selama migrasi. - -- Gunakan referensi project TS dari ekstensi gelombang pertama ke - `packages/plugin-sdk/tsconfig.json` dan set - `disableSourceOfProjectReferenceRedirect` untuk mode batas opt-in. - Alasan: ini memberi `tsc` graf paket nyata sambil mengurangi fallback editor dan - compiler ke penelusuran source mentah. - -- Pertahankan `@openclaw/plugin-sdk` sebagai private pada gelombang pertama. - Alasan: tujuan langsungnya adalah penegakan batas internal dan keamanan - migrasi, bukan memublikasikan kontrak SDK eksternal kedua sebelum permukaannya - stabil. - -- Pindahkan hanya subpath SDK gelombang pertama dalam irisan implementasi pertama, - dan pertahankan jembatan kompatibilitas untuk sisanya. - Alasan: memindahkan secara fisik semua 315 file `src/plugin-sdk/*.ts` dalam - satu PR justru menciptakan permukaan konflik merge yang coba dihindari rencana ini. - -- Jangan mengandalkan `scripts/postinstall-bundled-plugins.mjs` untuk membangun - deklarasi SDK pada gelombang pertama. - Alasan: alur build/referensi yang eksplisit lebih mudah dipahami dan membuat - perilaku repo lebih dapat diprediksi. - -## Pertanyaan terbuka - -### Diselesaikan selama perencanaan - -- Ekstensi mana yang harus masuk gelombang pertama? - Gunakan 10 ekstensi provider/web-search yang tercantum di atas karena secara - struktural lebih terisolasi dibanding paket channel yang lebih berat. - -- Haruskah PR pertama mengganti seluruh tree ekstensi? - Tidak. PR pertama harus mendukung dua mode secara paralel dan hanya - mengikutsertakan gelombang pertama. - -- Haruskah gelombang pertama memerlukan build deklarasi postinstall? - Tidak. Graf paket/referensi harus eksplisit, dan CI harus menjalankan - typecheck lokal-paket yang relevan secara sengaja. - -### Ditunda ke implementasi - -- Apakah paket gelombang pertama dapat menunjuk langsung ke `src/*.ts` - lokal-paket hanya melalui referensi project, atau apakah langkah kecil emisi deklarasi - masih diperlukan untuk paket `@openclaw/plugin-sdk`. - Ini adalah pertanyaan validasi graf TS yang dimiliki implementasi. - -- Apakah paket root `openclaw` seharusnya memproksikan subpath SDK gelombang pertama ke - output `packages/plugin-sdk` segera atau tetap menggunakan shim kompatibilitas hasil generate - di bawah `src/plugin-sdk`. - Ini adalah detail kompatibilitas dan bentuk build yang bergantung pada jalur - implementasi minimal yang menjaga CI tetap hijau. - -## Desain teknis tingkat tinggi - -> Ini menggambarkan pendekatan yang dimaksud dan merupakan panduan arah untuk peninjauan, bukan spesifikasi implementasi. Agen pelaksana harus memperlakukannya sebagai konteks, bukan kode yang harus direproduksi. - -```mermaid -flowchart TB - subgraph Legacy["Ekstensi lama (tidak berubah)"] - L1["extensions/*\nopenclaw/plugin-sdk/*"] - L2["paths tsconfig root"] - L1 --> L2 - L2 --> L3["src/plugin-sdk/*"] - end - - subgraph OptIn["Ekstensi gelombang pertama"] - O1["10 ekstensi yang ikut serta"] - O2["extensions/tsconfig.package-boundary.base.json"] - O3["rootDir = '.'\nreferensi project"] - O4["@openclaw/plugin-sdk"] - O1 --> O2 - O2 --> O3 - O3 --> O4 - end - - subgraph SDK["Paket workspace baru"] - P1["packages/plugin-sdk/package.json"] - P2["packages/plugin-sdk/tsconfig.json"] - P3["packages/plugin-sdk/src/.ts"] - P1 --> P2 - P2 --> P3 - end - - O4 --> SDK -``` - -## Unit implementasi - -- [ ] **Unit 1: Perkenalkan paket workspace nyata `@openclaw/plugin-sdk`** - -**Tujuan:** Buat paket workspace nyata untuk SDK yang dapat memiliki -permukaan gelombang pertama tanpa memaksakan migrasi seluruh repo. - -**Kebutuhan:** R1, R2, R3, R8, R9 - -**Dependensi:** Tidak ada - -**File:** - -- Buat: `packages/plugin-sdk/package.json` -- Buat: `packages/plugin-sdk/tsconfig.json` -- Buat: `packages/plugin-sdk/src/index.ts` -- Buat: `packages/plugin-sdk/src/*.ts` untuk subpath SDK gelombang pertama -- Ubah: `pnpm-workspace.yaml` hanya jika penyesuaian glob paket diperlukan -- Ubah: `package.json` -- Ubah: `src/plugin-sdk/entrypoints.ts` -- Ubah: `scripts/lib/plugin-sdk-entrypoints.json` -- Test: `src/plugins/contracts/plugin-sdk-workspace-package.contract.test.ts` - -**Pendekatan:** - -- Tambahkan paket workspace baru bernama `@openclaw/plugin-sdk`. -- Mulai hanya dengan subpath SDK gelombang pertama, bukan seluruh tree 315 file. -- Jika memindahkan entrypoint gelombang pertama secara langsung akan menciptakan diff yang terlalu besar, - PR pertama dapat memperkenalkan subpath tersebut di `packages/plugin-sdk/src` sebagai wrapper paket tipis terlebih dahulu - lalu membalik source of truth ke paket dalam PR lanjutan untuk klaster subpath itu. -- Gunakan kembali machinery inventaris entrypoint yang ada agar permukaan paket gelombang pertama - dideklarasikan di satu tempat kanonis. -- Pertahankan ekspor paket root tetap hidup untuk pengguna lama sementara paket workspace - menjadi kontrak opt-in yang baru. - -**Pola yang harus diikuti:** - -- `packages/memory-host-sdk/package.json` -- `packages/plugin-package-contract/package.json` -- `src/plugin-sdk/entrypoints.ts` - -**Skenario test:** - -- Jalur berhasil: paket workspace mengekspor setiap subpath gelombang pertama yang - tercantum dalam rencana dan tidak ada ekspor gelombang pertama yang wajib hilang. -- Edge case: metadata ekspor paket tetap stabil saat daftar entry gelombang pertama - di-generate ulang atau dibandingkan terhadap inventaris kanonis. -- Integrasi: ekspor SDK root lama tetap ada setelah memperkenalkan paket workspace baru. - -**Verifikasi:** - -- Repo berisi paket workspace `@openclaw/plugin-sdk` yang valid dengan peta ekspor gelombang pertama - yang stabil dan tanpa regresi ekspor lama di `package.json` root. - -- [ ] **Unit 2: Tambahkan mode batas TS opt-in untuk ekstensi yang ditegakkan paket** - -**Tujuan:** Definisikan mode konfigurasi TS yang akan digunakan oleh ekstensi -yang ikut serta, sambil membiarkan perilaku TS ekstensi yang ada tidak berubah -untuk semua yang lain. - -**Kebutuhan:** R4, R6, R7, R8, R9 - -**Dependensi:** Unit 1 - -**File:** - -- Buat: `extensions/tsconfig.package-boundary.base.json` -- Buat: `tsconfig.boundary-optin.json` -- Ubah: `extensions/xai/tsconfig.json` -- Ubah: `extensions/openai/tsconfig.json` -- Ubah: `extensions/anthropic/tsconfig.json` -- Ubah: `extensions/mistral/tsconfig.json` -- Ubah: `extensions/groq/tsconfig.json` -- Ubah: `extensions/together/tsconfig.json` -- Ubah: `extensions/perplexity/tsconfig.json` -- Ubah: `extensions/tavily/tsconfig.json` -- Ubah: `extensions/exa/tsconfig.json` -- Ubah: `extensions/firecrawl/tsconfig.json` -- Test: `src/plugins/contracts/extension-package-project-boundaries.test.ts` -- Test: `test/extension-package-tsc-boundary.test.ts` - -**Pendekatan:** - -- Biarkan `extensions/tsconfig.base.json` tetap ada untuk ekstensi lama. -- Tambahkan config basis opt-in baru yang: - - menetapkan `rootDir: "."` - - mereferensikan `packages/plugin-sdk` - - mengaktifkan `composite` - - menonaktifkan pengalihan source referensi project bila diperlukan -- Tambahkan config solution khusus untuk graf typecheck gelombang pertama alih-alih - membentuk ulang project TS repo root dalam PR yang sama. - -**Catatan eksekusi:** Mulailah dengan typecheck canary lokal-paket yang gagal untuk satu -ekstensi yang ikut serta sebelum menerapkan pola tersebut ke semua 10 ekstensi. - -**Pola yang harus diikuti:** - -- Pola `tsconfig.json` lokal-ekstensi yang ada dari pekerjaan batas sebelumnya -- Pola paket workspace dari `packages/memory-host-sdk` - -**Skenario test:** - -- Jalur berhasil: setiap ekstensi yang ikut serta berhasil typecheck melalui - config TS batas paket. -- Jalur error: impor relatif canary dari `../../src/cli/acp-cli.ts` gagal - dengan `TS6059` untuk ekstensi yang ikut serta. -- Integrasi: ekstensi yang belum ikut serta tetap tidak berubah dan tidak perlu - berpartisipasi dalam config solution baru. - -**Verifikasi:** - -- Ada graf typecheck khusus untuk 10 ekstensi yang ikut serta, dan impor relatif - buruk dari salah satu di antaranya gagal melalui `tsc` normal. - -- [ ] **Unit 3: Migrasikan ekstensi gelombang pertama ke `@openclaw/plugin-sdk`** - -**Tujuan:** Ubah ekstensi gelombang pertama agar mengonsumsi paket SDK nyata -melalui metadata dependensi, referensi project, dan impor nama paket. - -**Kebutuhan:** R5, R6, R7, R9 - -**Dependensi:** Unit 2 - -**File:** - -- Ubah: `extensions/anthropic/package.json` -- Ubah: `extensions/exa/package.json` -- Ubah: `extensions/firecrawl/package.json` -- Ubah: `extensions/groq/package.json` -- Ubah: `extensions/mistral/package.json` -- Ubah: `extensions/openai/package.json` -- Ubah: `extensions/perplexity/package.json` -- Ubah: `extensions/tavily/package.json` -- Ubah: `extensions/together/package.json` -- Ubah: `extensions/xai/package.json` -- Ubah: impor produksi dan test di bawah masing-masing dari 10 root ekstensi yang - saat ini mereferensikan `openclaw/plugin-sdk/*` - -**Pendekatan:** - -- Tambahkan `@openclaw/plugin-sdk: workspace:*` ke `devDependencies` - ekstensi gelombang pertama. -- Ganti impor `openclaw/plugin-sdk/*` di paket tersebut dengan - `@openclaw/plugin-sdk/*`. -- Pertahankan impor internal-lokal ekstensi pada barrel lokal seperti `./api.ts` dan - `./runtime-api.ts`. -- Jangan ubah ekstensi yang belum ikut serta dalam PR ini. - -**Pola yang harus diikuti:** - -- Barrel impor lokal-ekstensi yang ada (`api.ts`, `runtime-api.ts`) -- Bentuk dependensi paket yang digunakan oleh paket workspace `@openclaw/*` lainnya - -**Skenario test:** - -- Jalur berhasil: setiap ekstensi yang dimigrasikan tetap mendaftar/memuat melalui - test plugin yang ada setelah penulisan ulang impor. -- Edge case: impor SDK hanya-untuk-test di kumpulan ekstensi yang ikut serta tetap - di-resolve dengan benar melalui paket baru. -- Integrasi: ekstensi yang dimigrasikan tidak memerlukan alias root - `openclaw/plugin-sdk/*` untuk typecheck. - -**Verifikasi:** - -- Ekstensi gelombang pertama build dan test terhadap `@openclaw/plugin-sdk` - tanpa memerlukan path alias SDK root lama. - -- [ ] **Unit 4: Pertahankan kompatibilitas lama saat migrasi masih parsial** - -**Tujuan:** Pertahankan sisa repo tetap berfungsi saat SDK ada dalam bentuk lama -dan paket baru selama migrasi. - -**Kebutuhan:** R4, R8, R9 - -**Dependensi:** Unit 1-3 - -**File:** - -- Ubah: `src/plugin-sdk/*.ts` untuk shim kompatibilitas gelombang pertama bila diperlukan -- Ubah: `package.json` -- Ubah: plumbing build atau ekspor yang merakit artefak SDK -- Test: `src/plugins/contracts/plugin-sdk-runtime-api-guardrails.test.ts` -- Test: `src/plugins/contracts/plugin-sdk-index.bundle.test.ts` - -**Pendekatan:** - -- Pertahankan root `openclaw/plugin-sdk/*` sebagai permukaan kompatibilitas untuk - ekstensi lama dan untuk konsumen eksternal yang belum berpindah. -- Gunakan shim hasil generate atau wiring proksi ekspor root untuk subpath - gelombang pertama yang sudah dipindahkan ke `packages/plugin-sdk`. -- Jangan mencoba memensiunkan permukaan SDK root pada fase ini. - -**Pola yang harus diikuti:** - -- Generate ekspor SDK root yang ada melalui `src/plugin-sdk/entrypoints.ts` -- Kompatibilitas ekspor paket yang ada di `package.json` root - -**Skenario test:** - -- Jalur berhasil: impor SDK root lama masih di-resolve untuk ekstensi yang belum ikut serta - setelah paket baru ada. -- Edge case: subpath gelombang pertama bekerja melalui permukaan root lama dan - permukaan paket baru selama masa migrasi. -- Integrasi: test kontrak indeks/bundle plugin-sdk tetap melihat permukaan publik - yang koheren. - -**Verifikasi:** - -- Repo mendukung mode konsumsi SDK lama dan opt-in tanpa - merusak ekstensi yang tidak berubah. - -- [ ] **Unit 5: Tambahkan penegakan terarah dan dokumentasikan kontrak migrasi** - -**Tujuan:** Terapkan panduan CI dan kontributor yang menegakkan perilaku baru untuk -gelombang pertama tanpa berpura-pura seluruh tree ekstensi sudah dimigrasikan. - -**Kebutuhan:** R5, R6, R8, R9 - -**Dependensi:** Unit 1-4 - -**File:** - -- Ubah: `package.json` -- Ubah: file workflow CI yang harus menjalankan typecheck batas opt-in -- Ubah: `AGENTS.md` -- Ubah: `docs/plugins/sdk-overview.md` -- Ubah: `docs/plugins/sdk-entrypoints.md` -- Ubah: `docs/plans/2026-04-05-001-refactor-extension-package-resolution-boundary-plan.md` - -**Pendekatan:** - -- Tambahkan gate gelombang pertama yang eksplisit, seperti solution `tsc -b` khusus untuk - `packages/plugin-sdk` plus 10 ekstensi yang ikut serta. -- Dokumentasikan bahwa repo sekarang mendukung mode ekstensi lama dan opt-in, - dan bahwa pekerjaan batas ekstensi baru sebaiknya memilih jalur paket baru. -- Catat aturan migrasi gelombang berikutnya agar PR berikutnya dapat menambahkan lebih banyak ekstensi - tanpa memperdebatkan ulang arsitekturnya. - -**Pola yang harus diikuti:** - -- Test kontrak yang ada di bawah `src/plugins/contracts/` -- Pembaruan docs yang ada yang menjelaskan migrasi bertahap - -**Skenario test:** - -- Jalur berhasil: gate typecheck gelombang pertama yang baru lolos untuk paket workspace - dan ekstensi yang ikut serta. -- Jalur error: memperkenalkan impor relatif ilegal baru di ekstensi yang ikut serta - menggagalkan gate typecheck terarah. -- Integrasi: CI belum mengharuskan ekstensi yang belum ikut serta memenuhi mode - batas paket baru. - -**Verifikasi:** - -- Jalur penegakan gelombang pertama terdokumentasi, teruji, dan dapat dijalankan - tanpa memaksa seluruh tree ekstensi bermigrasi. - -## Dampak seluruh sistem - -- **Graf interaksi:** pekerjaan ini menyentuh source of truth SDK, ekspor paket - root, metadata paket ekstensi, tata letak graf TS, dan verifikasi CI. -- **Propagasi error:** mode kegagalan utama yang dimaksud menjadi error TS saat compile-time - (`TS6059`) pada ekstensi yang ikut serta alih-alih kegagalan khusus berbasis script. -- **Risiko siklus hidup state:** migrasi dua permukaan memperkenalkan risiko drift antara - ekspor kompatibilitas root dan paket workspace baru. -- **Paritas permukaan API:** subpath gelombang pertama harus tetap identik secara semantik - melalui `openclaw/plugin-sdk/*` dan `@openclaw/plugin-sdk/*` selama - transisi. -- **Cakupan integrasi:** test unit tidak cukup; typecheck graf paket terarah - diperlukan untuk membuktikan batas. -- **Invarian yang tidak berubah:** ekstensi yang belum ikut serta mempertahankan perilaku saat ini - di PR 1. Rencana ini tidak mengklaim penegakan batas impor seluruh repo. - -## Risiko & dependensi - -| Risiko | Mitigasi | -| -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | -| Paket gelombang pertama masih di-resolve kembali ke source mentah dan `rootDir` tidak benar-benar gagal tertutup | Jadikan langkah implementasi pertama sebagai canary referensi paket pada satu ekstensi yang ikut serta sebelum diperluas ke set penuh | -| Memindahkan terlalu banyak source SDK sekaligus menciptakan kembali masalah konflik merge semula | Pindahkan hanya subpath gelombang pertama dalam PR pertama dan pertahankan jembatan kompatibilitas root | -| Permukaan SDK lama dan baru menyimpang secara semantik | Pertahankan inventaris entrypoint tunggal, tambahkan test kontrak kompatibilitas, dan buat paritas dua permukaan menjadi eksplisit | -| Path build/test repo root tanpa sengaja mulai bergantung pada paket baru dengan cara yang tidak terkendali | Gunakan config solution opt-in khusus dan jauhkan perubahan topologi TS seluruh root dari PR pertama | - -## Pengiriman bertahap - -### Fase 1 - -- Perkenalkan `@openclaw/plugin-sdk` -- Definisikan permukaan subpath gelombang pertama -- Buktikan satu ekstensi yang ikut serta dapat gagal tertutup melalui `rootDir` - -### Fase 2 - -- Ikutsertakan 10 ekstensi gelombang pertama -- Pertahankan kompatibilitas root untuk semua yang lain - -### Fase 3 - -- Tambahkan lebih banyak ekstensi di PR berikutnya -- Pindahkan lebih banyak subpath SDK ke paket workspace -- Pensiunkan kompatibilitas root hanya setelah kumpulan ekstensi lama sudah tidak ada - -## Catatan dokumentasi / operasional - -- PR pertama harus secara eksplisit mendeskripsikan dirinya sebagai migrasi dual-mode, bukan - penyelesaian penegakan seluruh repo. -- Panduan migrasi harus memudahkan PR berikutnya untuk menambahkan lebih banyak ekstensi - dengan mengikuti pola paket/dependensi/referensi yang sama. - -## Sumber & referensi - -- Rencana sebelumnya: `docs/plans/2026-04-05-001-refactor-extension-package-resolution-boundary-plan.md` -- Konfigurasi workspace: `pnpm-workspace.yaml` -- Inventaris entrypoint SDK yang ada: `src/plugin-sdk/entrypoints.ts` -- Ekspor SDK root yang ada: `package.json` -- Pola paket workspace yang ada: - - `packages/memory-host-sdk/package.json` - - `packages/plugin-package-contract/package.json` diff --git a/docs/id/plugins/architecture.md b/docs/id/plugins/architecture.md index 195890fc0..4bdc16b1f 100644 --- a/docs/id/plugins/architecture.md +++ b/docs/id/plugins/architecture.md @@ -1,17 +1,17 @@ --- read_when: - - Membangun atau men-debug plugin OpenClaw native + - Membangun atau men-debug plugin native OpenClaw - Memahami model kapabilitas plugin atau batas kepemilikan - Mengerjakan pipeline pemuatan plugin atau registry - - Mengimplementasikan hook runtime penyedia atau plugin channel + - Mengimplementasikan hook runtime provider atau plugin channel sidebarTitle: Internals summary: 'Internal plugin: model kapabilitas, kepemilikan, kontrak, pipeline pemuatan, dan helper runtime' title: Internal Plugin x-i18n: - generated_at: "2026-04-08T02:19:08Z" + generated_at: "2026-04-09T01:32:15Z" model: gpt-5.4 provider: openai - source_hash: c40ecf14e2a0b2b8d332027aed939cd61fb4289a489f4cd4c076c96d707d1138 + source_hash: 2575791f835990589219bb06d8ca92e16a8c38b317f0bfe50b421682f253ef18 source_path: plugins/architecture.md workflow: 15 --- @@ -20,11 +20,11 @@ x-i18n: Ini adalah **referensi arsitektur mendalam**. Untuk panduan praktis, lihat: - - [Instal dan gunakan plugin](/id/tools/plugin) — panduan pengguna - - [Memulai](/id/plugins/building-plugins) — tutorial plugin pertama - - [Plugin Channel](/id/plugins/sdk-channel-plugins) — bangun channel pesan - - [Plugin Penyedia](/id/plugins/sdk-provider-plugins) — bangun penyedia model - - [Gambaran Umum SDK](/id/plugins/sdk-overview) — peta import dan API pendaftaran + - [Install and use plugins](/id/tools/plugin) — panduan pengguna + - [Getting Started](/id/plugins/building-plugins) — tutorial plugin pertama + - [Channel Plugins](/id/plugins/sdk-channel-plugins) — membangun channel pesan + - [Provider Plugins](/id/plugins/sdk-provider-plugins) — membangun provider model + - [SDK Overview](/id/plugins/sdk-overview) — peta impor dan API pendaftaran Halaman ini membahas arsitektur internal sistem plugin OpenClaw. @@ -32,7 +32,7 @@ Halaman ini membahas arsitektur internal sistem plugin OpenClaw. ## Model kapabilitas publik Kapabilitas adalah model **plugin native** publik di dalam OpenClaw. Setiap -plugin OpenClaw native mendaftar ke satu atau lebih jenis kapabilitas: +plugin native OpenClaw mendaftar ke satu atau lebih tipe kapabilitas: | Capability | Registration method | Example plugins | | ---------------------- | ------------------------------------------------ | ------------------------------------ | @@ -47,139 +47,151 @@ plugin OpenClaw native mendaftar ke satu atau lebih jenis kapabilitas: | Pembuatan video | `api.registerVideoGenerationProvider(...)` | `qwen` | | Pengambilan web | `api.registerWebFetchProvider(...)` | `firecrawl` | | Pencarian web | `api.registerWebSearchProvider(...)` | `google` | -| Channel / pesan | `api.registerChannel(...)` | `msteams`, `matrix` | +| Channel / perpesanan | `api.registerChannel(...)` | `msteams`, `matrix` | -Plugin yang mendaftarkan nol kapabilitas tetapi menyediakan hook, alat, atau -layanan adalah plugin **legacy hook-only**. Pola itu masih sepenuhnya didukung. +Plugin yang mendaftarkan nol kapabilitas tetapi menyediakan hook, tool, atau +layanan adalah plugin **legacy hook-only**. Pola tersebut masih didukung +sepenuhnya. ### Sikap kompatibilitas eksternal Model kapabilitas sudah diterapkan di core dan digunakan oleh plugin -bundled/native saat ini, tetapi kompatibilitas plugin eksternal masih memerlukan standar -yang lebih ketat daripada “ini diekspor, berarti dibekukan.” +bundled/native saat ini, tetapi kompatibilitas plugin eksternal masih +memerlukan standar yang lebih ketat daripada "ini diekspor, maka ini beku." Panduan saat ini: -- **plugin eksternal yang sudah ada:** jaga integrasi berbasis hook tetap berfungsi; perlakukan - ini sebagai dasar kompatibilitas -- **plugin bundled/native baru:** utamakan pendaftaran kapabilitas yang eksplisit daripada - reach-in khusus vendor atau desain hook-only baru -- **plugin eksternal yang mengadopsi pendaftaran kapabilitas:** diperbolehkan, tetapi perlakukan - permukaan helper khusus kapabilitas sebagai sesuatu yang masih berkembang kecuali dokumentasi secara eksplisit menandai sebuah kontrak sebagai stabil +- **plugin eksternal yang sudah ada:** pertahankan integrasi berbasis hook tetap + berfungsi; anggap ini sebagai baseline kompatibilitas +- **plugin bundled/native baru:** utamakan pendaftaran kapabilitas yang + eksplisit daripada reach-in spesifik vendor atau desain hook-only baru +- **plugin eksternal yang mengadopsi pendaftaran kapabilitas:** diperbolehkan, + tetapi anggap surface helper spesifik kapabilitas masih berkembang kecuali + dokumentasi secara eksplisit menandai kontrak sebagai stabil Aturan praktis: - API pendaftaran kapabilitas adalah arah yang dituju -- hook legacy tetap menjadi jalur paling aman dari kerusakan untuk plugin eksternal selama - masa transisi -- subpath helper yang diekspor tidak semuanya setara; utamakan kontrak sempit yang terdokumentasi, - bukan ekspor helper yang kebetulan ada +- hook lama tetap menjadi jalur paling aman tanpa kerusakan untuk plugin + eksternal selama masa transisi +- subpath helper yang diekspor tidak semuanya setara; utamakan kontrak sempit + yang terdokumentasi, bukan ekspor helper insidental ### Bentuk plugin -OpenClaw mengklasifikasikan setiap plugin yang dimuat ke dalam sebuah bentuk berdasarkan perilaku -pendaftarannya yang aktual (bukan hanya metadata statis): +OpenClaw mengklasifikasikan setiap plugin yang dimuat ke dalam suatu bentuk +berdasarkan perilaku pendaftarannya yang sebenarnya (bukan hanya metadata +statis): - **plain-capability** -- mendaftarkan tepat satu jenis kapabilitas (misalnya - plugin hanya-penyedia seperti `mistral`) + plugin khusus provider seperti `mistral`) - **hybrid-capability** -- mendaftarkan beberapa jenis kapabilitas (misalnya `openai` memiliki inferensi teks, ucapan, pemahaman media, dan pembuatan gambar) -- **hook-only** -- hanya mendaftarkan hook (typed atau custom), tanpa kapabilitas, - alat, perintah, atau layanan -- **non-capability** -- mendaftarkan alat, perintah, layanan, atau rute tetapi tanpa - kapabilitas +- **hook-only** -- hanya mendaftarkan hook (typed atau custom), tanpa + kapabilitas, tool, perintah, atau layanan +- **non-capability** -- mendaftarkan tool, perintah, layanan, atau rute tetapi + tanpa kapabilitas Gunakan `openclaw plugins inspect ` untuk melihat bentuk plugin dan rincian -kapabilitasnya. Lihat [referensi CLI](/cli/plugins#inspect) untuk detail. +kapabilitasnya. Lihat [CLI reference](/cli/plugins#inspect) untuk detail. -### Hook legacy +### Hook lama Hook `before_agent_start` tetap didukung sebagai jalur kompatibilitas untuk -plugin hook-only. Plugin nyata lama masih bergantung padanya. +plugin hook-only. Plugin dunia nyata lama masih bergantung padanya. Arah ke depan: -- tetap fungsional +- pertahankan agar tetap berfungsi - dokumentasikan sebagai legacy -- utamakan `before_model_resolve` untuk pekerjaan override model/penyedia +- utamakan `before_model_resolve` untuk pekerjaan override model/provider - utamakan `before_prompt_build` untuk pekerjaan mutasi prompt -- hapus hanya setelah penggunaan nyata menurun dan cakupan fixture membuktikan keamanan migrasi +- hapus hanya setelah penggunaan nyata menurun dan cakupan fixture membuktikan + keamanan migrasi ### Sinyal kompatibilitas -Saat Anda menjalankan `openclaw doctor` atau `openclaw plugins inspect `, Anda mungkin melihat -salah satu label ini: +Saat Anda menjalankan `openclaw doctor` atau `openclaw plugins inspect `, +Anda mungkin melihat salah satu label berikut: | Signal | Meaning | | -------------------------- | ------------------------------------------------------------ | -| **config valid** | Konfigurasi berhasil diurai dan plugin ter-resolve | -| **compatibility advisory** | Plugin menggunakan pola yang didukung tetapi lebih lama (mis. `hook-only`) | -| **legacy warning** | Plugin menggunakan `before_agent_start`, yang sudah deprecated | -| **hard error** | Konfigurasi tidak valid atau plugin gagal dimuat | +| **config valid** | Config berhasil di-parse dan plugin berhasil di-resolve | +| **compatibility advisory** | Plugin menggunakan pola lama yang masih didukung (mis. `hook-only`) | +| **legacy warning** | Plugin menggunakan `before_agent_start`, yang sudah deprecated | +| **hard error** | Config tidak valid atau plugin gagal dimuat | -Baik `hook-only` maupun `before_agent_start` tidak akan merusak plugin Anda saat ini -- -`hook-only` bersifat advisory, dan `before_agent_start` hanya memicu peringatan. Sinyal-sinyal ini -juga muncul di `openclaw status --all` dan `openclaw plugins doctor`. +Baik `hook-only` maupun `before_agent_start` tidak akan merusak plugin Anda saat +ini -- `hook-only` bersifat advisory, dan `before_agent_start` hanya memicu +peringatan. Sinyal ini juga muncul di `openclaw status --all` dan +`openclaw plugins doctor`. -## Gambaran umum arsitektur +## Ikhtisar arsitektur Sistem plugin OpenClaw memiliki empat lapisan: 1. **Manifest + discovery** - OpenClaw menemukan kandidat plugin dari path yang dikonfigurasi, root workspace, - root ekstensi global, dan ekstensi bundled. Discovery membaca manifest native - `openclaw.plugin.json` ditambah manifest bundle yang didukung terlebih dahulu. + OpenClaw menemukan kandidat plugin dari path yang dikonfigurasi, root + workspace, root ekstensi global, dan ekstensi bundled. Discovery membaca + manifest native `openclaw.plugin.json` serta manifest bundle yang didukung + terlebih dahulu. 2. **Enablement + validation** - Core memutuskan apakah plugin yang ditemukan diaktifkan, dinonaktifkan, diblokir, atau - dipilih untuk slot eksklusif seperti memori. + Core memutuskan apakah plugin yang ditemukan diaktifkan, dinonaktifkan, + diblokir, atau dipilih untuk slot eksklusif seperti memori. 3. **Runtime loading** - Plugin OpenClaw native dimuat in-process melalui jiti dan mendaftarkan - kapabilitas ke registry pusat. Bundle yang kompatibel dinormalisasi menjadi - catatan registry tanpa mengimpor kode runtime. + Plugin native OpenClaw dimuat in-process melalui jiti dan mendaftarkan + kapabilitas ke dalam registry pusat. Bundle yang kompatibel dinormalisasi + menjadi record registry tanpa mengimpor kode runtime. 4. **Surface consumption** - Bagian lain dari OpenClaw membaca registry untuk mengekspos alat, channel, setup - penyedia, hook, rute HTTP, perintah CLI, dan layanan. + Bagian lain OpenClaw membaca registry untuk mengekspos tool, channel, + penyiapan provider, hook, rute HTTP, perintah CLI, dan layanan. -Khusus untuk CLI plugin, discovery perintah root dibagi menjadi dua fase: +Khusus untuk plugin CLI, discovery perintah root dibagi menjadi dua fase: -- metadata saat parse berasal dari `registerCli(..., { descriptors: [...] })` -- modul CLI plugin yang sebenarnya dapat tetap lazy dan mendaftar pada pemanggilan pertama +- metadata waktu parse berasal dari `registerCli(..., { descriptors: [...] })` +- modul CLI plugin yang sebenarnya dapat tetap lazy dan mendaftar saat pertama + kali dipanggil -Ini menjaga kode CLI milik plugin tetap berada di dalam plugin sambil tetap memungkinkan OpenClaw -mencadangkan nama perintah root sebelum parsing. +Ini menjaga kode CLI milik plugin tetap berada di dalam plugin sambil tetap +memungkinkan OpenClaw mencadangkan nama perintah root sebelum parsing. Batas desain yang penting: -- discovery + validasi konfigurasi harus bekerja dari **metadata manifest/schema** +- discovery + validasi config harus bekerja dari **metadata manifest/schema** tanpa mengeksekusi kode plugin - perilaku runtime native berasal dari jalur `register(api)` modul plugin -Pemisahan ini memungkinkan OpenClaw memvalidasi konfigurasi, menjelaskan plugin yang hilang/dinonaktifkan, dan -membangun petunjuk UI/schema sebelum runtime penuh aktif. +Pemisahan ini memungkinkan OpenClaw memvalidasi config, menjelaskan plugin yang +hilang/dinonaktifkan, dan membangun petunjuk UI/schema sebelum runtime penuh +aktif. -### Plugin channel dan alat message bersama +### Plugin channel dan tool message bersama -Plugin channel tidak perlu mendaftarkan alat send/edit/react terpisah untuk -aksi chat normal. OpenClaw mempertahankan satu alat `message` bersama di core, dan -plugin channel memiliki discovery dan eksekusi khusus channel di baliknya. +Plugin channel tidak perlu mendaftarkan tool send/edit/react terpisah untuk +aksi chat normal. OpenClaw mempertahankan satu tool `message` bersama di core, +dan plugin channel memiliki discovery dan eksekusi yang spesifik channel di +baliknya. Batas saat ini adalah: -- core memiliki host alat `message` bersama, wiring prompt, pembukuan sesi/thread, - dan dispatch eksekusi -- plugin channel memiliki discovery aksi berscope, discovery kapabilitas, dan fragmen schema - khusus channel -- plugin channel memiliki grammar percakapan sesi khusus penyedia, seperti - bagaimana id percakapan mengodekan id thread atau diwariskan dari percakapan induk +- core memiliki host tool `message` bersama, wiring prompt, pembukuan + sesi/thread, dan dispatch eksekusi +- plugin channel memiliki discovery aksi terlingkup, discovery kapabilitas, dan + fragmen schema spesifik channel +- plugin channel memiliki grammar percakapan sesi yang spesifik provider, + seperti bagaimana id percakapan mengodekan id thread atau mewarisi dari + percakapan induk - plugin channel mengeksekusi aksi akhir melalui action adapter mereka -Untuk plugin channel, permukaan SDK-nya adalah -`ChannelMessageActionAdapter.describeMessageTool(...)`. Panggilan discovery terpadu -itu memungkinkan plugin mengembalikan aksi yang terlihat, kapabilitas, dan kontribusi -schema secara bersamaan agar bagian-bagian itu tidak saling menyimpang. +Untuk plugin channel, surface SDK-nya adalah +`ChannelMessageActionAdapter.describeMessageTool(...)`. Panggilan discovery +terpadu itu memungkinkan plugin mengembalikan aksi yang terlihat, kapabilitas, +dan kontribusi schema secara bersama-sama agar bagian-bagian tersebut tidak +menyimpang. -Core meneruskan scope runtime ke langkah discovery tersebut. Field penting meliputi: +Core meneruskan runtime scope ke langkah discovery tersebut. Field penting +mencakup: - `accountId` - `currentChannelId` @@ -188,127 +200,131 @@ Core meneruskan scope runtime ke langkah discovery tersebut. Field penting melip - `sessionKey` - `sessionId` - `agentId` -- `requesterSenderId` masuk yang tepercaya +- `requesterSenderId` inbound tepercaya -Ini penting untuk plugin yang sensitif terhadap konteks. Sebuah channel dapat menyembunyikan atau mengekspos -aksi message berdasarkan akun aktif, room/thread/message saat ini, atau -identitas requester tepercaya tanpa hardcode branch khusus channel di -alat `message` core. +Ini penting untuk plugin yang peka konteks. Sebuah channel dapat menyembunyikan +atau mengekspos aksi message berdasarkan akun aktif, room/thread/message saat +ini, atau identitas requester tepercaya tanpa hardcode percabangan spesifik +channel di tool `message` core. -Inilah sebabnya perubahan routing embedded-runner masih merupakan pekerjaan plugin: runner bertanggung jawab -meneruskan identitas chat/sesi saat ini ke batas discovery plugin -agar alat `message` bersama mengekspos permukaan milik channel yang benar -untuk giliran saat ini. +Inilah sebabnya perubahan routing embedded-runner tetap merupakan pekerjaan +plugin: runner bertanggung jawab meneruskan identitas chat/sesi saat ini ke +batas discovery plugin agar tool `message` bersama mengekspos surface milik +channel yang tepat untuk giliran saat ini. -Untuk helper eksekusi milik channel, plugin bundled sebaiknya mempertahankan runtime -eksekusi di dalam modul ekstensi milik mereka sendiri. Core tidak lagi memiliki runtime -aksi-message Discord, Slack, Telegram, atau WhatsApp di bawah `src/agents/tools`. -Kami tidak menerbitkan subpath `plugin-sdk/*-action-runtime` terpisah, dan plugin -bundled sebaiknya mengimpor kode runtime lokal mereka sendiri langsung dari -modul milik ekstensi mereka. +Untuk helper eksekusi milik channel, plugin bundled harus menyimpan runtime +eksekusi di dalam modul ekstensi mereka sendiri. Core tidak lagi memiliki +runtime message-action Discord, Slack, Telegram, atau WhatsApp di bawah +`src/agents/tools`. Kami tidak menerbitkan subpath `plugin-sdk/*-action-runtime` +terpisah, dan plugin bundled harus mengimpor kode runtime lokal mereka sendiri +langsung dari modul milik ekstensi mereka. -Batas yang sama berlaku untuk seam SDK bernama penyedia secara umum: core tidak boleh -mengimpor convenience barrel khusus channel untuk Slack, Discord, Signal, -WhatsApp, atau ekstensi serupa. Jika core memerlukan suatu perilaku, gunakan -barrel `api.ts` / `runtime-api.ts` milik plugin bundled itu sendiri atau promosikan -kebutuhan tersebut ke kapabilitas generik yang sempit di SDK bersama. +Batas yang sama berlaku untuk seam SDK bernama provider secara umum: core tidak +boleh mengimpor convenience barrel spesifik channel untuk ekstensi Slack, +Discord, Signal, WhatsApp, atau serupa. Jika core memerlukan suatu perilaku, +gunakan barrel `api.ts` / `runtime-api.ts` milik plugin bundled itu sendiri +atau naikkan kebutuhan tersebut menjadi kapabilitas generik yang sempit dalam +SDK bersama. Khusus untuk poll, ada dua jalur eksekusi: -- `outbound.sendPoll` adalah dasar bersama untuk channel yang cocok dengan model - poll umum -- `actions.handleAction("poll")` adalah jalur yang diutamakan untuk semantik poll - khusus channel atau parameter poll tambahan +- `outbound.sendPoll` adalah baseline bersama untuk channel yang cocok dengan + model poll umum +- `actions.handleAction("poll")` adalah jalur yang diutamakan untuk semantik + poll spesifik channel atau parameter poll tambahan -Core sekarang menunda parsing poll bersama sampai setelah dispatch poll plugin menolak -aksi tersebut, sehingga handler poll milik plugin dapat menerima field poll -khusus channel tanpa terlebih dahulu diblokir oleh parser poll generik. +Core sekarang menunda parsing poll bersama sampai setelah dispatch poll plugin +menolak aksi tersebut, sehingga handler poll milik plugin dapat menerima field +poll spesifik channel tanpa diblokir terlebih dahulu oleh parser poll generik. Lihat [Load pipeline](#load-pipeline) untuk urutan startup lengkap. ## Model kepemilikan kapabilitas -OpenClaw memperlakukan plugin native sebagai batas kepemilikan untuk sebuah **perusahaan** atau -sebuah **fitur**, bukan sebagai kumpulan integrasi tak terkait. +OpenClaw memperlakukan plugin native sebagai batas kepemilikan untuk sebuah +**perusahaan** atau sebuah **fitur**, bukan sebagai kumpulan integrasi yang +tidak terkait. Artinya: -- plugin perusahaan biasanya harus memiliki semua permukaan OpenClaw-facing milik perusahaan itu -- plugin fitur biasanya harus memiliki permukaan fitur penuh yang diperkenalkannya -- channel harus mengonsumsi kapabilitas core bersama alih-alih mengimplementasikan ulang - perilaku penyedia secara ad hoc +- plugin perusahaan biasanya harus memiliki semua surface OpenClaw yang + berhadapan dengan perusahaan tersebut +- plugin fitur biasanya harus memiliki seluruh surface fitur yang diperkenalkannya +- channel harus mengonsumsi kapabilitas core bersama alih-alih mengimplementasikan + ulang perilaku provider secara ad hoc Contoh: -- plugin bundled `openai` memiliki perilaku model-provider OpenAI dan perilaku OpenAI - speech + realtime-voice + media-understanding + image-generation +- plugin bundled `openai` memiliki perilaku model-provider OpenAI dan perilaku + OpenAI speech + realtime-voice + media-understanding + image-generation - plugin bundled `elevenlabs` memiliki perilaku speech ElevenLabs - plugin bundled `microsoft` memiliki perilaku speech Microsoft -- plugin bundled `google` memiliki perilaku model-provider Google plus perilaku Google - media-understanding + image-generation + web-search +- plugin bundled `google` memiliki perilaku model-provider Google ditambah + perilaku Google media-understanding + image-generation + web-search - plugin bundled `firecrawl` memiliki perilaku web-fetch Firecrawl - plugin bundled `minimax`, `mistral`, `moonshot`, dan `zai` memiliki backend media-understanding mereka -- plugin bundled `qwen` memiliki perilaku text-provider Qwen plus - perilaku media-understanding dan video-generation -- plugin `voice-call` adalah plugin fitur: ia memiliki transport panggilan, alat, - CLI, rute, dan bridging media-stream Twilio, tetapi ia mengonsumsi speech bersama - plus kapabilitas realtime-transcription dan realtime-voice alih-alih - mengimpor plugin vendor secara langsung +- plugin `voice-call` adalah plugin fitur: plugin ini memiliki transport + panggilan, tool, CLI, rute, dan bridge media-stream Twilio, tetapi mengonsumsi + kapabilitas speech bersama serta realtime-transcription dan realtime-voice + alih-alih mengimpor plugin vendor secara langsung Kondisi akhir yang dituju adalah: -- OpenAI berada dalam satu plugin meskipun mencakup model teks, speech, gambar, dan - video di masa depan -- vendor lain dapat melakukan hal yang sama untuk area permukaan mereka sendiri -- channel tidak peduli plugin vendor mana yang memiliki penyedia; mereka mengonsumsi - kontrak kapabilitas bersama yang diekspos oleh core +- OpenAI berada dalam satu plugin meskipun mencakup model teks, speech, gambar, + dan video di masa depan +- vendor lain dapat melakukan hal yang sama untuk area surface mereka sendiri +- channel tidak peduli plugin vendor mana yang memiliki provider; mereka + mengonsumsi kontrak kapabilitas bersama yang diekspos oleh core -Inilah perbedaan utamanya: +Inilah perbedaan kuncinya: - **plugin** = batas kepemilikan -- **capability** = kontrak core yang dapat diimplementasikan atau dikonsumsi oleh beberapa plugin +- **capability** = kontrak core yang dapat diimplementasikan atau dikonsumsi + oleh beberapa plugin -Jadi jika OpenClaw menambahkan domain baru seperti video, pertanyaan pertama bukanlah -“penyedia mana yang harus meng-hardcode penanganan video?” Pertanyaan pertama adalah -“apa kontrak kapabilitas video core?” Setelah kontrak itu ada, plugin vendor -dapat mendaftar ke sana dan plugin channel/fitur dapat mengonsumsinya. +Jadi jika OpenClaw menambahkan domain baru seperti video, pertanyaan pertama +bukan "provider mana yang harus melakukan hardcode penanganan video?" Pertanyaan +pertama adalah "apa kontrak kapabilitas video di core?" Setelah kontrak itu +ada, plugin vendor dapat mendaftar terhadapnya dan plugin channel/fitur dapat +mengonsumsinya. -Jika kapabilitasnya belum ada, langkah yang benar biasanya adalah: +Jika kapabilitasnya belum ada, langkah yang tepat biasanya adalah: 1. definisikan kapabilitas yang hilang di core -2. ekspos melalui API/runtime plugin dengan tipe yang jelas -3. hubungkan channel/fitur ke kapabilitas itu -4. biarkan plugin vendor mendaftarkan implementasinya +2. ekspos melalui API/runtime plugin dengan cara yang typed +3. wiring channel/fitur terhadap kapabilitas itu +4. biarkan plugin vendor mendaftarkan implementasi -Ini menjaga kepemilikan tetap eksplisit sambil menghindari perilaku core yang bergantung pada -satu vendor atau jalur kode khusus plugin yang hanya sekali pakai. +Ini menjaga kepemilikan tetap eksplisit sambil menghindari perilaku core yang +bergantung pada satu vendor atau jalur kode plugin-spesifik sekali pakai. ### Pelapisan kapabilitas -Gunakan model mental ini saat memutuskan di mana kode seharusnya berada: +Gunakan model mental ini saat memutuskan tempat kode berada: - **lapisan kapabilitas core**: orkestrasi bersama, kebijakan, fallback, aturan - penggabungan konfigurasi, semantik pengiriman, dan kontrak bertipe -- **lapisan plugin vendor**: API khusus vendor, auth, katalog model, speech - synthesis, pembuatan gambar, backend video di masa depan, endpoint penggunaan + merge config, semantik pengiriman, dan kontrak yang typed +- **lapisan plugin vendor**: API spesifik vendor, autentikasi, katalog model, + sintesis ucapan, pembuatan gambar, backend video masa depan, endpoint usage - **lapisan plugin channel/fitur**: integrasi Slack/Discord/voice-call/dll. - yang mengonsumsi kapabilitas core dan menyajikannya pada suatu permukaan + yang mengonsumsi kapabilitas core dan menampilkannya pada suatu surface Misalnya, TTS mengikuti bentuk ini: -- core memiliki kebijakan TTS saat balasan, urutan fallback, preferensi, dan pengiriman channel -- `openai`, `elevenlabs`, dan `microsoft` memiliki implementasi synthesis +- core memiliki kebijakan TTS saat reply, urutan fallback, preferensi, dan + pengiriman channel +- `openai`, `elevenlabs`, dan `microsoft` memiliki implementasi sintesis - `voice-call` mengonsumsi helper runtime TTS telephony -Pola yang sama sebaiknya diutamakan untuk kapabilitas di masa depan. +Pola yang sama sebaiknya diutamakan untuk kapabilitas masa depan. ### Contoh plugin perusahaan multi-kapabilitas -Plugin perusahaan seharusnya terasa kohesif dari luar. Jika OpenClaw memiliki kontrak bersama -untuk model, speech, realtime transcription, realtime voice, media -understanding, image generation, video generation, web fetch, dan web search, -sebuah vendor dapat memiliki semua permukaannya di satu tempat: +Plugin perusahaan harus terasa kohesif dari luar. Jika OpenClaw memiliki +kontrak bersama untuk model, speech, transkripsi realtime, suara realtime, +pemahaman media, pembuatan gambar, pembuatan video, pengambilan web, dan +pencarian web, vendor dapat memiliki semua surface mereka di satu tempat: ```ts import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry"; @@ -323,12 +339,12 @@ const plugin: OpenClawPluginDefinition = { register(api) { api.registerProvider({ id: "exampleai", - // auth/model catalog/runtime hooks + // hook auth/katalog model/runtime }); api.registerSpeechProvider({ id: "exampleai", - // vendor speech config — implement the SpeechProviderPlugin interface directly + // config speech vendor — implementasikan interface SpeechProviderPlugin secara langsung }); api.registerMediaUnderstandingProvider({ @@ -353,7 +369,7 @@ const plugin: OpenClawPluginDefinition = { api.registerWebSearchProvider( createPluginBackedWebSearchProvider({ id: "exampleai-search", - // credential + fetch logic + // logika kredensial + fetch }), ); }, @@ -362,68 +378,73 @@ const plugin: OpenClawPluginDefinition = { export default plugin; ``` -Yang penting bukan nama helper yang persis sama. Bentuknya yang penting: +Yang penting bukan nama helper yang persis. Bentuknya yang penting: -- satu plugin memiliki permukaan vendor +- satu plugin memiliki surface vendor - core tetap memiliki kontrak kapabilitas - channel dan plugin fitur mengonsumsi helper `api.runtime.*`, bukan kode vendor -- test kontrak dapat memastikan bahwa plugin telah mendaftarkan kapabilitas yang - diklaimnya dimiliki +- pengujian kontrak dapat menegaskan bahwa plugin mendaftarkan kapabilitas yang + diklaimnya miliki ### Contoh kapabilitas: pemahaman video OpenClaw sudah memperlakukan pemahaman gambar/audio/video sebagai satu -kapabilitas bersama. Model kepemilikan yang sama juga berlaku di sana: +kapabilitas bersama. Model kepemilikan yang sama berlaku di sana: 1. core mendefinisikan kontrak media-understanding 2. plugin vendor mendaftarkan `describeImage`, `transcribeAudio`, dan `describeVideo` sesuai kebutuhan 3. channel dan plugin fitur mengonsumsi perilaku core bersama alih-alih - terhubung langsung ke kode vendor + melakukan wiring langsung ke kode vendor -Ini menghindari asumsi video dari satu penyedia tertanam di core. Plugin memiliki -permukaan vendor; core memiliki kontrak kapabilitas dan perilaku fallback. +Ini menghindari asumsi video satu provider tertanam di core. Plugin memiliki +surface vendor; core memiliki kontrak kapabilitas dan perilaku fallback. Pembuatan video sudah menggunakan urutan yang sama: core memiliki kontrak -kapabilitas bertipe dan helper runtime, dan plugin vendor mendaftarkan -implementasi `api.registerVideoGenerationProvider(...)` untuknya. +kapabilitas dan helper runtime yang typed, dan plugin vendor mendaftarkan +implementasi `api.registerVideoGenerationProvider(...)` terhadapnya. -Butuh daftar periksa rollout yang konkret? Lihat +Butuh checklist rollout yang konkret? Lihat [Capability Cookbook](/id/plugins/architecture). ## Kontrak dan penegakan -Permukaan API plugin sengaja dibuat bertipe dan tersentralisasi di -`OpenClawPluginApi`. Kontrak itu mendefinisikan titik pendaftaran yang didukung dan -helper runtime yang dapat diandalkan oleh sebuah plugin. +Surface API plugin sengaja dibuat typed dan terpusat di +`OpenClawPluginApi`. Kontrak tersebut mendefinisikan titik pendaftaran yang +didukung dan helper runtime yang boleh diandalkan plugin. Mengapa ini penting: - penulis plugin mendapatkan satu standar internal yang stabil -- core dapat menolak kepemilikan ganda seperti dua plugin yang mendaftarkan provider id yang sama -- startup dapat menampilkan diagnostik yang dapat ditindaklanjuti untuk pendaftaran yang salah bentuk -- test kontrak dapat menegakkan kepemilikan plugin bundled dan mencegah drift diam-diam +- core dapat menolak kepemilikan duplikat seperti dua plugin yang + mendaftarkan id provider yang sama +- startup dapat menampilkan diagnostik yang dapat ditindaklanjuti untuk + pendaftaran yang salah bentuk +- pengujian kontrak dapat menegakkan kepemilikan plugin bundled dan mencegah + drift diam-diam Ada dua lapisan penegakan: 1. **penegakan pendaftaran runtime** Registry plugin memvalidasi pendaftaran saat plugin dimuat. Contoh: - provider id duplikat, speech provider id duplikat, dan pendaftaran yang salah bentuk - menghasilkan diagnostik plugin alih-alih perilaku yang tidak terdefinisi. -2. **test kontrak** - Plugin bundled ditangkap dalam contract registries selama test berjalan sehingga - OpenClaw dapat menegaskan kepemilikan secara eksplisit. Saat ini ini digunakan untuk model - provider, speech provider, web search provider, dan kepemilikan pendaftaran bundled. + id provider duplikat, id speech provider duplikat, dan pendaftaran yang + salah bentuk menghasilkan diagnostik plugin alih-alih perilaku tak + terdefinisi. +2. **pengujian kontrak** + Plugin bundled ditangkap dalam registry kontrak selama pengujian berjalan + sehingga OpenClaw dapat menegaskan kepemilikan secara eksplisit. Saat ini + ini digunakan untuk model provider, speech provider, web search provider, + dan kepemilikan pendaftaran bundled. -Efek praktisnya adalah OpenClaw mengetahui, sejak awal, plugin mana yang memiliki permukaan yang mana. -Ini memungkinkan core dan channel menyusun integrasi dengan mulus karena kepemilikan -dinyatakan, bertipe, dan dapat diuji alih-alih implisit. +Efek praktisnya adalah bahwa OpenClaw mengetahui, sejak awal, plugin mana yang +memiliki surface mana. Ini memungkinkan core dan channel tersusun mulus karena +kepemilikan dinyatakan, typed, dan dapat diuji, bukan implisit. -### Apa yang termasuk dalam sebuah kontrak +### Apa yang termasuk dalam kontrak Kontrak plugin yang baik adalah: -- bertipe +- typed - kecil - spesifik kapabilitas - dimiliki oleh core @@ -432,150 +453,158 @@ Kontrak plugin yang baik adalah: Kontrak plugin yang buruk adalah: -- kebijakan spesifik vendor yang tersembunyi di core +- kebijakan spesifik vendor yang disembunyikan di core - escape hatch plugin sekali pakai yang melewati registry - kode channel yang langsung menjangkau implementasi vendor - objek runtime ad hoc yang bukan bagian dari `OpenClawPluginApi` atau `api.runtime` Jika ragu, naikkan tingkat abstraksinya: definisikan dulu kapabilitasnya, lalu -biarkan plugin masuk ke sana. +biarkan plugin tersambung ke sana. ## Model eksekusi -Plugin OpenClaw native berjalan **in-process** dengan Gateway. Mereka tidak -disandbox. Plugin native yang dimuat memiliki batas kepercayaan tingkat proses yang sama dengan -kode core. +Plugin native OpenClaw berjalan **in-process** bersama Gateway. Plugin ini +tidak disandbox. Plugin native yang dimuat memiliki batas kepercayaan level +proses yang sama dengan kode core. Implikasinya: -- plugin native dapat mendaftarkan alat, handler jaringan, hook, dan layanan -- bug plugin native dapat membuat gateway crash atau tidak stabil +- plugin native dapat mendaftarkan tool, handler jaringan, hook, dan layanan +- bug plugin native dapat menyebabkan gateway crash atau tidak stabil - plugin native yang berbahaya setara dengan eksekusi kode arbitrer di dalam proses OpenClaw -Bundle yang kompatibel lebih aman secara default karena OpenClaw saat ini memperlakukan mereka -sebagai paket metadata/konten. Pada rilis saat ini, itu sebagian besar berarti -Skills yang dibundel. +Bundle yang kompatibel lebih aman secara default karena OpenClaw saat ini +memperlakukannya sebagai paket metadata/konten. Dalam rilis saat ini, itu +kebanyakan berarti skills bundled. -Gunakan allowlist dan path instalasi/pemuatan yang eksplisit untuk plugin non-bundled. -Perlakukan plugin workspace sebagai kode saat pengembangan, bukan default produksi. +Gunakan allowlist dan path install/load yang eksplisit untuk plugin yang tidak +dibundel. Perlakukan plugin workspace sebagai kode waktu pengembangan, bukan +default produksi. -Untuk nama paket workspace plugin bundled, pertahankan plugin id terikat di nama npm: -`@openclaw/` secara default, atau sufiks bertipe yang disetujui seperti -`-provider`, `-plugin`, `-speech`, `-sandbox`, atau `-media-understanding` saat -paket memang sengaja mengekspos peran plugin yang lebih sempit. +Untuk nama paket workspace bundled plugin, pertahankan id plugin tetap +tertambat pada nama npm: `@openclaw/` secara default, atau akhiran typed +yang disetujui seperti `-provider`, `-plugin`, `-speech`, `-sandbox`, atau +`-media-understanding` ketika paket memang mengekspos peran plugin yang lebih +sempit. Catatan kepercayaan penting: -- `plugins.allow` mempercayai **plugin ids**, bukan asal sumber. -- Plugin workspace dengan id yang sama seperti plugin bundled sengaja menimpa - salinan bundled saat plugin workspace itu diaktifkan/masuk allowlist. +- `plugins.allow` mempercayai **id plugin**, bukan asal sumber. +- Plugin workspace dengan id yang sama seperti plugin bundled sengaja + membayangi salinan bundled ketika plugin workspace tersebut + diaktifkan/di-allowlist. - Ini normal dan berguna untuk pengembangan lokal, pengujian patch, dan hotfix. ## Batas ekspor -OpenClaw mengekspor kapabilitas, bukan convenience implementasi. +OpenClaw mengekspor kapabilitas, bukan kemudahan implementasi. -Pertahankan pendaftaran kapabilitas tetap publik. Pangkas ekspor helper non-kontrak: +Pertahankan pendaftaran kapabilitas tetap publik. Pangkas ekspor helper yang +bukan kontrak: -- subpath helper khusus plugin bundled +- subpath helper spesifik bundled-plugin - subpath plumbing runtime yang tidak dimaksudkan sebagai API publik - helper convenience spesifik vendor - helper setup/onboarding yang merupakan detail implementasi -Beberapa subpath helper plugin bundled masih tetap ada di peta ekspor SDK yang dihasilkan -demi kompatibilitas dan pemeliharaan plugin bundled. Contoh saat ini termasuk -`plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, -`plugin-sdk/zalo-setup`, dan beberapa seam `plugin-sdk/matrix*`. Perlakukan itu sebagai -ekspor detail implementasi yang dicadangkan, bukan sebagai pola SDK yang direkomendasikan -untuk plugin pihak ketiga yang baru. +Beberapa subpath helper bundled-plugin masih tetap ada dalam peta ekspor SDK +yang dihasilkan demi kompatibilitas dan pemeliharaan bundled-plugin. Contoh saat +ini mencakup `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, +`plugin-sdk/zalo-setup`, dan beberapa seam `plugin-sdk/matrix*`. Perlakukan ini +sebagai ekspor detail implementasi yang dicadangkan, bukan pola SDK yang +direkomendasikan untuk plugin pihak ketiga baru. ## Load pipeline -Saat startup, OpenClaw kira-kira melakukan ini: +Saat startup, OpenClaw secara kasar melakukan ini: 1. menemukan root plugin kandidat -2. membaca manifest native atau bundle yang kompatibel dan metadata paket +2. membaca manifest native atau bundle yang kompatibel dan metadata package 3. menolak kandidat yang tidak aman -4. menormalkan konfigurasi plugin (`plugins.enabled`, `allow`, `deny`, `entries`, +4. menormalisasi config plugin (`plugins.enabled`, `allow`, `deny`, `entries`, `slots`, `load.paths`) 5. memutuskan enablement untuk setiap kandidat 6. memuat modul native yang diaktifkan melalui jiti -7. memanggil hook native `register(api)` (atau `activate(api)` — alias legacy) dan mengumpulkan pendaftaran ke dalam registry plugin -8. mengekspos registry ke permukaan perintah/runtime +7. memanggil hook native `register(api)` (atau `activate(api)` — alias lama) + dan mengumpulkan pendaftaran ke dalam registry plugin +8. mengekspos registry ke surface perintah/runtime -`activate` adalah alias legacy untuk `register` — loader me-resolve mana pun yang ada (`def.register ?? def.activate`) dan memanggilnya pada titik yang sama. Semua plugin bundled menggunakan `register`; utamakan `register` untuk plugin baru. +`activate` adalah alias lama untuk `register` — loader me-resolve mana pun yang ada (`def.register ?? def.activate`) dan memanggilnya pada titik yang sama. Semua plugin bundled menggunakan `register`; gunakan `register` untuk plugin baru. -Gerbang keamanan terjadi **sebelum** eksekusi runtime. Kandidat diblokir -saat entry keluar dari root plugin, path dapat ditulis oleh semua orang, atau kepemilikan path -terlihat mencurigakan untuk plugin non-bundled. +Gerbang keamanan terjadi **sebelum** eksekusi runtime. Kandidat diblokir ketika +entry keluar dari root plugin, path dapat ditulisi oleh semua orang, atau +kepemilikan path tampak mencurigakan untuk plugin yang tidak dibundel. ### Perilaku manifest-first Manifest adalah sumber kebenaran control-plane. OpenClaw menggunakannya untuk: - mengidentifikasi plugin -- menemukan channel/Skills/schema konfigurasi yang dideklarasikan atau kapabilitas bundle +- menemukan schema config/channel/skills yang dideklarasikan atau kapabilitas + bundle - memvalidasi `plugins.entries..config` - menambah label/placeholder Control UI -- menampilkan metadata instalasi/katalog +- menampilkan metadata install/katalog -Untuk plugin native, modul runtime adalah bagian data-plane. Ia mendaftarkan -perilaku aktual seperti hook, alat, perintah, atau alur penyedia. +Untuk plugin native, modul runtime adalah bagian data-plane. Modul ini +mendaftarkan perilaku aktual seperti hook, tool, perintah, atau alur provider. -### Apa yang di-cache loader +### Apa yang di-cache oleh loader -OpenClaw menyimpan cache in-process singkat untuk: +OpenClaw menyimpan cache in-process jangka pendek untuk: - hasil discovery - data registry manifest -- registries plugin yang dimuat +- registry plugin yang dimuat -Cache ini mengurangi startup yang meledak-ledak dan overhead perintah berulang. Aman -untuk dianggap sebagai cache performa jangka pendek, bukan persistensi. +Cache ini mengurangi startup yang melonjak dan overhead perintah berulang. Cache +ini aman untuk dianggap sebagai cache performa berumur pendek, bukan persistensi. Catatan performa: - Atur `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` atau `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1` untuk menonaktifkan cache ini. -- Sesuaikan jendela cache dengan `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` dan +- Atur jendela cache dengan `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` dan `OPENCLAW_PLUGIN_MANIFEST_CACHE_MS`. ## Model registry -Plugin yang dimuat tidak langsung memutasi global core sembarang. Mereka mendaftar ke -registry plugin pusat. +Plugin yang dimuat tidak langsung memodifikasi global core acak. Plugin ini +mendaftar ke registry plugin pusat. Registry melacak: -- catatan plugin (identitas, sumber, asal, status, diagnostik) -- alat -- hook legacy dan typed hook -- channels -- providers -- gateway RPC handlers +- record plugin (identitas, sumber, origin, status, diagnostik) +- tool +- hook lama dan typed hook +- channel +- provider +- handler Gateway RPC - rute HTTP -- CLI registrars +- registrar CLI - layanan latar belakang - perintah milik plugin -Fitur core kemudian membaca dari registry itu alih-alih berbicara ke modul plugin -secara langsung. Ini menjaga pemuatan tetap searah: +Fitur core kemudian membaca dari registry itu alih-alih berbicara langsung +dengan modul plugin. Ini menjaga pemuatan tetap satu arah: - modul plugin -> pendaftaran registry - runtime core -> konsumsi registry -Pemisahan ini penting untuk maintainability. Ini berarti sebagian besar permukaan core hanya -memerlukan satu titik integrasi: “baca registry”, bukan “buat special-case untuk setiap modul plugin”. +Pemisahan ini penting untuk kemudahan pemeliharaan. Artinya, sebagian besar +surface core hanya memerlukan satu titik integrasi: "baca registry", bukan +"special-case setiap modul plugin". ## Callback pengikatan percakapan -Plugin yang mengikat percakapan dapat bereaksi saat sebuah approval diselesaikan. +Plugin yang mengikat percakapan dapat bereaksi ketika sebuah persetujuan +diselesaikan. -Gunakan `api.onConversationBindingResolved(...)` untuk menerima callback setelah sebuah +Gunakan `api.onConversationBindingResolved(...)` untuk menerima callback setelah permintaan bind disetujui atau ditolak: ```ts @@ -584,12 +613,12 @@ export default { register(api) { api.onConversationBindingResolved(async (event) => { if (event.status === "approved") { - // A binding now exists for this plugin + conversation. + // Sebuah binding sekarang ada untuk plugin + percakapan ini. console.log(event.binding?.conversationId); return; } - // The request was denied; clear any local pending state. + // Permintaan ditolak; bersihkan status pending lokal. console.log(event.request.conversation.conversationId); }); }, @@ -600,22 +629,24 @@ Field payload callback: - `status`: `"approved"` atau `"denied"` - `decision`: `"allow-once"`, `"allow-always"`, atau `"deny"` -- `binding`: binding yang terselesaikan untuk permintaan yang disetujui -- `request`: ringkasan permintaan asli, petunjuk detach, sender id, dan +- `binding`: binding yang telah di-resolve untuk permintaan yang disetujui +- `request`: ringkasan permintaan asli, petunjuk detach, id pengirim, dan metadata percakapan -Callback ini hanya untuk notifikasi. Ini tidak mengubah siapa yang diizinkan untuk mengikat -percakapan, dan berjalan setelah penanganan approval core selesai. +Callback ini hanya untuk notifikasi. Callback ini tidak mengubah siapa yang +diizinkan mengikat percakapan, dan berjalan setelah penanganan persetujuan core +selesai. -## Hook runtime penyedia +## Hook runtime provider -Plugin penyedia sekarang memiliki dua lapisan: +Plugin provider sekarang memiliki dua lapisan: -- metadata manifest: `providerAuthEnvVars` untuk lookup auth env penyedia yang murah - sebelum runtime dimuat, `channelEnvVars` untuk lookup env/setup channel yang murah - sebelum runtime dimuat, ditambah `providerAuthChoices` untuk label onboarding/auth-choice yang murah - serta metadata flag CLI sebelum runtime dimuat -- hook saat konfigurasi: `catalog` / legacy `discovery` plus `applyConfigDefaults` +- metadata manifest: `providerAuthEnvVars` untuk lookup env-auth provider yang + murah sebelum runtime dimuat, `providerAuthAliases` untuk varian provider yang + berbagi auth, `channelEnvVars` untuk lookup env/setup channel yang murah + sebelum runtime dimuat, serta `providerAuthChoices` untuk label pilihan + onboarding/auth yang murah dan metadata flag CLI sebelum runtime dimuat +- hook waktu config: `catalog` / `discovery` lama plus `applyConfigDefaults` - hook runtime: `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, @@ -637,87 +668,91 @@ Plugin penyedia sekarang memiliki dua lapisan: `sanitizeReplayHistory`, `validateReplayTurns`, `onModelSelected` OpenClaw tetap memiliki loop agen generik, failover, penanganan transkrip, dan -kebijakan alat. Hook ini adalah permukaan ekstensi untuk perilaku khusus penyedia tanpa -memerlukan transport inferensi kustom penuh. +kebijakan tool. Hook ini adalah surface ekstensi untuk perilaku spesifik +provider tanpa memerlukan transport inferensi kustom sepenuhnya. -Gunakan manifest `providerAuthEnvVars` saat penyedia memiliki kredensial berbasis env -yang harus terlihat oleh jalur auth/status/model-picker generik tanpa memuat runtime plugin. -Gunakan manifest `providerAuthChoices` saat permukaan onboarding/auth-choice CLI -harus mengetahui choice id penyedia, label grup, dan wiring auth satu-flag sederhana -tanpa memuat runtime penyedia. Simpan runtime penyedia `envVars` untuk petunjuk -yang terlihat operator seperti label onboarding atau variabel setup +Gunakan manifest `providerAuthEnvVars` ketika provider memiliki kredensial +berbasis env yang harus dapat dilihat jalur auth/status/model-picker generik +tanpa memuat runtime plugin. Gunakan manifest `providerAuthAliases` ketika satu +id provider harus menggunakan kembali env vars, auth profile, auth berbasis +config, dan pilihan onboarding API-key milik id provider lain. Gunakan manifest +`providerAuthChoices` ketika surface CLI onboarding/pilihan auth harus +mengetahui choice id provider, label grup, dan wiring auth satu-flag sederhana +tanpa memuat runtime provider. Pertahankan `envVars` runtime provider untuk +petunjuk yang berhadapan dengan operator seperti label onboarding atau var setup OAuth client-id/client-secret. -Gunakan manifest `channelEnvVars` saat sebuah channel memiliki auth atau setup berbasis env -yang harus terlihat oleh fallback shell-env generik, pemeriksaan config/status, atau prompt setup -tanpa memuat runtime channel. +Gunakan manifest `channelEnvVars` ketika suatu channel memiliki auth atau setup +yang digerakkan env yang harus dapat dilihat shell-env fallback generik, +pemeriksaan config/status, atau prompt setup tanpa memuat runtime channel. ### Urutan hook dan penggunaannya -Untuk plugin model/penyedia, OpenClaw memanggil hook dalam urutan kasar ini. -Kolom “When to use” adalah panduan keputusan cepat. +Untuk plugin model/provider, OpenClaw memanggil hook dalam urutan kasar ini. +Kolom "Kapan digunakan" adalah panduan keputusan singkat. -| # | Hook | What it does | When to use | +| # | Hook | Fungsi | Kapan digunakan | | --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | Publikasikan config penyedia ke `models.providers` selama pembuatan `models.json` | Penyedia memiliki katalog atau default base URL | -| 2 | `applyConfigDefaults` | Terapkan default config global milik penyedia selama materialisasi konfigurasi | Default bergantung pada mode auth, env, atau semantik keluarga model penyedia | -| -- | _(pencarian built-in model)_ | OpenClaw mencoba jalur registry/katalog normal terlebih dahulu | _(bukan hook plugin)_ | -| 3 | `normalizeModelId` | Normalkan alias model-id legacy atau preview sebelum lookup | Penyedia memiliki pembersihan alias sebelum resolusi model kanonis | -| 4 | `normalizeTransport` | Normalkan `api` / `baseUrl` keluarga penyedia sebelum perakitan model generik | Penyedia memiliki pembersihan transport untuk provider id kustom dalam keluarga transport yang sama | -| 5 | `normalizeConfig` | Normalkan `models.providers.` sebelum resolusi runtime/penyedia | Penyedia memerlukan pembersihan config yang sebaiknya berada bersama plugin; helper keluarga Google bundled juga menjadi backstop untuk entri config Google yang didukung | -| 6 | `applyNativeStreamingUsageCompat` | Terapkan penulisan ulang compat penggunaan streaming native ke penyedia config | Penyedia memerlukan perbaikan metadata penggunaan streaming native yang dipicu endpoint | -| 7 | `resolveConfigApiKey` | Resolve auth env-marker untuk penyedia config sebelum runtime auth dimuat | Penyedia memiliki resolusi API key env-marker milik penyedia; `amazon-bedrock` juga memiliki resolver env-marker AWS bawaan di sini | -| 8 | `resolveSyntheticAuth` | Tampilkan auth lokal/self-hosted atau berbasis config tanpa menyimpan plaintext | Penyedia dapat beroperasi dengan penanda kredensial sintetis/lokal | -| 9 | `resolveExternalAuthProfiles` | Overlay profil auth eksternal milik penyedia; default `persistence` adalah `runtime-only` untuk kredensial milik CLI/aplikasi | Penyedia memakai ulang kredensial auth eksternal tanpa menyimpan refresh token yang disalin | -| 10 | `shouldDeferSyntheticProfileAuth` | Turunkan placeholder profil sintetis yang tersimpan di bawah auth berbasis env/config | Penyedia menyimpan profil placeholder sintetis yang tidak seharusnya menang dalam prioritas | -| 11 | `resolveDynamicModel` | Fallback sinkron untuk model id milik penyedia yang belum ada di registry lokal | Penyedia menerima model id upstream arbitrer | -| 12 | `prepareDynamicModel` | Warm-up async, lalu `resolveDynamicModel` dijalankan lagi | Penyedia memerlukan metadata jaringan sebelum me-resolve id yang tidak dikenal | -| 13 | `normalizeResolvedModel` | Penulisan ulang akhir sebelum embedded runner menggunakan model yang sudah ter-resolve | Penyedia memerlukan penulisan ulang transport tetapi tetap menggunakan transport core | -| 14 | `contributeResolvedModelCompat` | Kontribusikan flag compat untuk model vendor di balik transport kompatibel lain | Penyedia mengenali modelnya sendiri pada transport proxy tanpa mengambil alih penyedia | -| 15 | `capabilities` | Metadata transkrip/tooling milik penyedia yang digunakan oleh logika core bersama | Penyedia memerlukan keunikan transkrip/keluarga penyedia | -| 16 | `normalizeToolSchemas` | Normalkan tool schema sebelum embedded runner melihatnya | Penyedia memerlukan pembersihan schema keluarga transport | -| 17 | `inspectToolSchemas` | Tampilkan diagnostik schema milik penyedia setelah normalisasi | Penyedia menginginkan peringatan keyword tanpa mengajarkan aturan khusus penyedia ke core | -| 18 | `resolveReasoningOutputMode` | Pilih kontrak output reasoning native vs bertag | Penyedia memerlukan output reasoning/akhir bertag alih-alih field native | -| 19 | `prepareExtraParams` | Normalisasi parameter request sebelum wrapper opsi stream generik | Penyedia memerlukan parameter request default atau pembersihan param per penyedia | -| 20 | `createStreamFn` | Gantikan sepenuhnya jalur stream normal dengan transport kustom | Penyedia memerlukan wire protocol kustom, bukan sekadar wrapper | -| 21 | `wrapStreamFn` | Wrapper stream setelah wrapper generik diterapkan | Penyedia memerlukan wrapper compat header/body/model request tanpa transport kustom | -| 22 | `resolveTransportTurnState` | Lampirkan header atau metadata transport per-turn native | Penyedia ingin transport generik mengirim identitas turn native penyedia | -| 23 | `resolveWebSocketSessionPolicy` | Lampirkan header WebSocket native atau kebijakan cool-down sesi | Penyedia ingin transport WS generik menyetel header sesi atau kebijakan fallback | -| 24 | `formatApiKey` | Formatter auth-profile: profil tersimpan menjadi string `apiKey` runtime | Penyedia menyimpan metadata auth tambahan dan memerlukan bentuk token runtime kustom | -| 25 | `refreshOAuth` | Override refresh OAuth untuk endpoint refresh kustom atau kebijakan kegagalan refresh | Penyedia tidak cocok dengan penyegar `pi-ai` bersama | -| 26 | `buildAuthDoctorHint` | Petunjuk perbaikan yang ditambahkan saat refresh OAuth gagal | Penyedia memerlukan panduan perbaikan auth milik penyedia setelah kegagalan refresh | -| 27 | `matchesContextOverflowError` | Matcher overflow context-window milik penyedia | Penyedia memiliki error overflow mentah yang tidak akan terdeteksi heuristik generik | -| 28 | `classifyFailoverReason` | Klasifikasi alasan failover milik penyedia | Penyedia dapat memetakan error API/transport mentah ke rate-limit/overload/dll | -| 29 | `isCacheTtlEligible` | Kebijakan prompt-cache untuk penyedia proxy/backhaul | Penyedia memerlukan gating TTL cache khusus proxy | -| 30 | `buildMissingAuthMessage` | Pengganti pesan pemulihan missing-auth generik | Penyedia memerlukan petunjuk pemulihan missing-auth khusus penyedia | -| 31 | `suppressBuiltInModel` | Penekanan model upstream yang stale plus petunjuk error yang menghadap pengguna secara opsional | Penyedia perlu menyembunyikan baris upstream yang stale atau menggantinya dengan petunjuk vendor | -| 32 | `augmentModelCatalog` | Baris katalog sintetis/akhir ditambahkan setelah discovery | Penyedia memerlukan baris forward-compat sintetis di `models list` dan picker | -| 33 | `isBinaryThinking` | Toggle reasoning on/off untuk penyedia binary-thinking | Penyedia hanya mengekspos binary thinking hidup/mati | -| 34 | `supportsXHighThinking` | Dukungan reasoning `xhigh` untuk model tertentu | Penyedia menginginkan `xhigh` hanya pada subset model tertentu | -| 35 | `resolveDefaultThinkingLevel` | Level `/think` default untuk keluarga model tertentu | Penyedia memiliki kebijakan `/think` default untuk keluarga model tertentu | -| 36 | `isModernModelRef` | Matcher model modern untuk filter profil live dan seleksi smoke | Penyedia memiliki pencocokan model pilihan live/smoke | -| 37 | `prepareRuntimeAuth` | Tukarkan kredensial yang dikonfigurasi menjadi token/key runtime sebenarnya tepat sebelum inferensi | Penyedia memerlukan pertukaran token atau kredensial request berumur pendek | -| 38 | `resolveUsageAuth` | Resolve kredensial penggunaan/billing untuk `/usage` dan permukaan status terkait | Penyedia memerlukan parsing token usage/quota kustom atau kredensial penggunaan yang berbeda | -| 39 | `fetchUsageSnapshot` | Ambil dan normalkan snapshot penggunaan/quota khusus penyedia setelah auth ter-resolve | Penyedia memerlukan endpoint penggunaan atau parser payload khusus penyedia | -| 40 | `createEmbeddingProvider` | Bangun adapter embedding milik penyedia untuk memori/pencarian | Perilaku embedding memori seharusnya berada bersama plugin penyedia | -| 41 | `buildReplayPolicy` | Kembalikan kebijakan replay yang mengontrol penanganan transkrip untuk penyedia | Penyedia memerlukan kebijakan transkrip kustom (misalnya, pembuangan blok thinking) | -| 42 | `sanitizeReplayHistory` | Tulis ulang riwayat replay setelah pembersihan transkrip generik | Penyedia memerlukan penulisan ulang replay khusus penyedia di luar helper compaction bersama | -| 43 | `validateReplayTurns` | Validasi atau pembentukan ulang replay-turn akhir sebelum embedded runner | Transport penyedia memerlukan validasi turn yang lebih ketat setelah sanitasi generik | -| 44 | `onModelSelected` | Jalankan efek samping pasca-seleksi milik penyedia | Penyedia memerlukan telemetry atau status milik penyedia saat sebuah model menjadi aktif | +| 1 | `catalog` | Menerbitkan config provider ke `models.providers` selama pembuatan `models.json` | Provider memiliki katalog atau default base URL | +| 2 | `applyConfigDefaults` | Menerapkan default config global milik provider selama materialisasi config | Default bergantung pada mode auth, env, atau semantik keluarga model provider | +| -- | _(lookup model bawaan)_ | OpenClaw lebih dulu mencoba jalur registry/katalog normal | _(bukan hook plugin)_ | +| 3 | `normalizeModelId` | Menormalisasi alias model-id lama atau pratinjau sebelum lookup | Provider memiliki pembersihan alias sebelum resolusi model kanonis | +| 4 | `normalizeTransport` | Menormalisasi `api` / `baseUrl` keluarga provider sebelum perakitan model generik | Provider memiliki pembersihan transport untuk id provider kustom dalam keluarga transport yang sama | +| 5 | `normalizeConfig` | Menormalisasi `models.providers.` sebelum resolusi runtime/provider | Provider memerlukan pembersihan config yang harus berada bersama plugin; helper keluarga Google bundled juga menjadi backstop untuk entri config Google yang didukung | +| 6 | `applyNativeStreamingUsageCompat` | Menerapkan penulisan ulang kompatibilitas streaming-usage native ke provider config | Provider memerlukan perbaikan metadata streaming usage native yang digerakkan endpoint | +| 7 | `resolveConfigApiKey` | Me-resolve auth env-marker untuk provider config sebelum pemuatan auth runtime | Provider memiliki resolusi API-key env-marker milik provider; `amazon-bedrock` juga memiliki resolver env-marker AWS bawaan di sini | +| 8 | `resolveSyntheticAuth` | Menampilkan auth lokal/self-hosted atau berbasis config tanpa menyimpan plaintext | Provider dapat beroperasi dengan marker kredensial sintetis/lokal | +| 9 | `resolveExternalAuthProfiles` | Melapiskan auth profile eksternal milik provider; default `persistence` adalah `runtime-only` untuk kredensial milik CLI/app | Provider menggunakan ulang kredensial auth eksternal tanpa menyimpan refresh token yang disalin | +| 10 | `shouldDeferSyntheticProfileAuth` | Menurunkan placeholder profile sintetis yang tersimpan di bawah auth berbasis env/config | Provider menyimpan profile placeholder sintetis yang seharusnya tidak menang prioritas | +| 11 | `resolveDynamicModel` | Fallback sinkron untuk model id milik provider yang belum ada di registry lokal | Provider menerima model id upstream arbitrer | +| 12 | `prepareDynamicModel` | Pemanasan async, lalu `resolveDynamicModel` dijalankan lagi | Provider memerlukan metadata jaringan sebelum me-resolve id yang tidak dikenal | +| 13 | `normalizeResolvedModel` | Penulisan ulang akhir sebelum embedded runner menggunakan model yang telah di-resolve | Provider memerlukan penulisan ulang transport tetapi tetap menggunakan transport core | +| 14 | `contributeResolvedModelCompat` | Menyumbangkan flag kompatibilitas untuk model vendor di balik transport kompatibel lain | Provider mengenali modelnya sendiri pada transport proxy tanpa mengambil alih provider | +| 15 | `capabilities` | Metadata transkrip/tooling milik provider yang digunakan oleh logika core bersama | Provider memerlukan kekhususan transkrip/keluarga provider | +| 16 | `normalizeToolSchemas` | Menormalisasi schema tool sebelum embedded runner melihatnya | Provider memerlukan pembersihan schema keluarga transport | +| 17 | `inspectToolSchemas` | Menampilkan diagnostik schema milik provider setelah normalisasi | Provider menginginkan peringatan keyword tanpa mengajarkan aturan spesifik provider ke core | +| 18 | `resolveReasoningOutputMode` | Memilih kontrak keluaran reasoning native vs tagged | Provider memerlukan keluaran reasoning/final yang bertag alih-alih field native | +| 19 | `prepareExtraParams` | Normalisasi parameter request sebelum wrapper opsi stream generik | Provider memerlukan default parameter request atau pembersihan parameter per-provider | +| 20 | `createStreamFn` | Menggantikan sepenuhnya jalur stream normal dengan transport kustom | Provider memerlukan wire protocol kustom, bukan hanya wrapper | +| 21 | `wrapStreamFn` | Wrapper stream setelah wrapper generik diterapkan | Provider memerlukan wrapper kompatibilitas header/body/model request tanpa transport kustom | +| 22 | `resolveTransportTurnState` | Melampirkan header atau metadata transport native per-giliran | Provider ingin transport generik mengirim identitas giliran native provider | +| 23 | `resolveWebSocketSessionPolicy` | Melampirkan header WebSocket native atau kebijakan cool-down sesi | Provider ingin transport WS generik menyetel header sesi atau kebijakan fallback | +| 24 | `formatApiKey` | Formatter auth-profile: profile yang disimpan menjadi string `apiKey` runtime | Provider menyimpan metadata auth tambahan dan memerlukan bentuk token runtime kustom | +| 25 | `refreshOAuth` | Override refresh OAuth untuk endpoint refresh kustom atau kebijakan kegagalan refresh | Provider tidak cocok dengan refresher `pi-ai` bersama | +| 26 | `buildAuthDoctorHint` | Petunjuk perbaikan yang ditambahkan saat refresh OAuth gagal | Provider memerlukan panduan perbaikan auth milik provider setelah kegagalan refresh | +| 27 | `matchesContextOverflowError` | Pencocok overflow jendela konteks milik provider | Provider memiliki error overflow mentah yang terlewat oleh heuristik generik | +| 28 | `classifyFailoverReason` | Klasifikasi alasan failover milik provider | Provider dapat memetakan error API/transport mentah ke rate-limit/overload/dll. | +| 29 | `isCacheTtlEligible` | Kebijakan prompt-cache untuk provider proxy/backhaul | Provider memerlukan gating TTL cache yang spesifik proxy | +| 30 | `buildMissingAuthMessage` | Pengganti pesan pemulihan missing-auth generik | Provider memerlukan petunjuk pemulihan missing-auth yang spesifik provider | +| 31 | `suppressBuiltInModel` | Penekanan model upstream usang plus petunjuk error yang opsional untuk pengguna | Provider perlu menyembunyikan baris upstream usang atau menggantinya dengan petunjuk vendor | +| 32 | `augmentModelCatalog` | Baris katalog sintetis/akhir yang ditambahkan setelah discovery | Provider memerlukan baris forward-compat sintetis di `models list` dan picker | +| 33 | `isBinaryThinking` | Toggle reasoning on/off untuk provider binary-thinking | Provider hanya mengekspos thinking biner on/off | +| 34 | `supportsXHighThinking` | Dukungan reasoning `xhigh` untuk model tertentu | Provider menginginkan `xhigh` hanya pada subset model tertentu | +| 35 | `resolveDefaultThinkingLevel` | Level `/think` default untuk keluarga model tertentu | Provider memiliki kebijakan default `/think` untuk keluarga model | +| 36 | `isModernModelRef` | Pencocok modern-model untuk filter profile live dan pemilihan smoke | Provider memiliki pencocokan preferred-model live/smoke | +| 37 | `prepareRuntimeAuth` | Menukar kredensial yang dikonfigurasi menjadi token/key runtime aktual tepat sebelum inferensi | Provider memerlukan pertukaran token atau kredensial request berumur pendek | +| 38 | `resolveUsageAuth` | Me-resolve kredensial usage/billing untuk `/usage` dan surface status terkait | Provider memerlukan parsing token usage/quota kustom atau kredensial usage yang berbeda | +| 39 | `fetchUsageSnapshot` | Mengambil dan menormalisasi snapshot usage/quota spesifik provider setelah auth di-resolve | Provider memerlukan endpoint usage atau parser payload yang spesifik provider | +| 40 | `createEmbeddingProvider` | Membangun adapter embedding milik provider untuk memory/search | Perilaku embedding memori harus berada bersama plugin provider | +| 41 | `buildReplayPolicy` | Mengembalikan kebijakan replay yang mengendalikan penanganan transkrip untuk provider | Provider memerlukan kebijakan transkrip kustom (misalnya, menghapus thinking-block) | +| 42 | `sanitizeReplayHistory` | Menulis ulang riwayat replay setelah pembersihan transkrip generik | Provider memerlukan penulisan ulang replay spesifik provider di luar helper compaction bersama | +| 43 | `validateReplayTurns` | Validasi atau pembentukan ulang replay-turn akhir sebelum embedded runner | Transport provider memerlukan validasi giliran yang lebih ketat setelah sanitasi generik | +| 44 | `onModelSelected` | Menjalankan efek samping pasca-pemilihan milik provider | Provider memerlukan telemetri atau status milik provider saat model menjadi aktif | -`normalizeModelId`, `normalizeTransport`, dan `normalizeConfig` terlebih dahulu memeriksa -plugin penyedia yang cocok, lalu meneruskan ke plugin penyedia lain yang mampu menangani hook -sampai salah satunya benar-benar mengubah model id atau transport/config. Ini menjaga -shim alias/compat penyedia tetap berfungsi tanpa mengharuskan pemanggil mengetahui plugin -bundled mana yang memiliki penulisan ulang tersebut. Jika tidak ada hook penyedia yang menulis ulang -entri config keluarga Google yang didukung, normalizer config Google bundled tetap menerapkan -pembersihan kompatibilitas tersebut. +`normalizeModelId`, `normalizeTransport`, dan `normalizeConfig` pertama-tama +memeriksa plugin provider yang cocok, lalu meneruskan ke plugin provider lain +yang mampu melakukan hook sampai salah satu benar-benar mengubah model id atau +transport/config. Ini menjaga shim provider alias/compat tetap berfungsi tanpa +mengharuskan pemanggil mengetahui plugin bundled mana yang memiliki penulisan +ulang tersebut. Jika tidak ada hook provider yang menulis ulang entri config +keluarga Google yang didukung, normalizer config Google bundled tetap +menerapkan pembersihan kompatibilitas itu. -Jika penyedia memerlukan wire protocol yang sepenuhnya kustom atau eksekutor request kustom, -itu adalah kelas ekstensi yang berbeda. Hook ini ditujukan untuk perilaku penyedia -yang tetap berjalan pada loop inferensi normal OpenClaw. +Jika provider memerlukan wire protocol yang sepenuhnya kustom atau executor +request kustom, itu adalah kelas ekstensi yang berbeda. Hook ini ditujukan +untuk perilaku provider yang tetap berjalan pada loop inferensi normal OpenClaw. -### Contoh penyedia +### Contoh provider ```ts api.registerProvider({ @@ -776,106 +811,118 @@ api.registerProvider({ - Anthropic menggunakan `resolveDynamicModel`, `capabilities`, `buildAuthDoctorHint`, `resolveUsageAuth`, `fetchUsageSnapshot`, `isCacheTtlEligible`, `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`, - dan `wrapStreamFn` karena ia memiliki forward-compat Claude 4.6, - petunjuk keluarga penyedia, panduan perbaikan auth, integrasi endpoint penggunaan, - kelayakan prompt-cache, default config yang sadar-auth, kebijakan thinking - default/adaptif Claude, dan pembentukan stream khusus Anthropic untuk - beta header, `/fast` / `serviceTier`, dan `context1m`. -- Helper stream khusus Claude milik Anthropic untuk saat ini tetap berada di - seam `api.ts` / `contract-api.ts` publik milik plugin bundled itu sendiri. Permukaan - paket itu mengekspor `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, + dan `wrapStreamFn` karena memiliki forward-compat Claude 4.6, + petunjuk keluarga provider, panduan perbaikan auth, integrasi endpoint usage, + kelayakan prompt-cache, default config yang sadar auth, kebijakan thinking + default/adaptif Claude, dan pembentukan stream spesifik Anthropic untuk + header beta, `/fast` / `serviceTier`, dan `context1m`. +- Helper stream spesifik Claude milik Anthropic untuk sementara tetap berada di + seam `api.ts` / `contract-api.ts` publik milik plugin bundled itu sendiri. + Surface paket itu mengekspor `wrapAnthropicProviderStream`, + `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier`, dan builder wrapper - Anthropic tingkat lebih rendah alih-alih memperlebar SDK generik di sekitar - aturan beta-header satu penyedia. + Anthropic tingkat rendah alih-alih memperluas SDK generik di sekitar aturan + beta-header satu provider. - OpenAI menggunakan `resolveDynamicModel`, `normalizeResolvedModel`, dan `capabilities` plus `buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`, `supportsXHighThinking`, dan `isModernModelRef` - karena ia memiliki forward-compat GPT-5.4, normalisasi langsung OpenAI - `openai-completions` -> `openai-responses`, petunjuk auth yang sadar Codex, - penekanan Spark, baris list OpenAI sintetis, dan kebijakan thinking / - live-model GPT-5; keluarga stream `openai-responses-defaults` memiliki - wrapper OpenAI Responses native bersama untuk attribution headers, - `/fast`/`serviceTier`, text verbosity, pencarian web Codex native, - pembentukan payload reasoning-compat, dan manajemen konteks Responses. + karena memiliki forward-compat GPT-5.4, normalisasi langsung + `openai-completions` -> `openai-responses` untuk OpenAI, + petunjuk auth yang sadar Codex, penekanan Spark, baris daftar OpenAI sintetis, + serta kebijakan thinking / live-model GPT-5; keluarga stream + `openai-responses-defaults` memiliki wrapper Responses OpenAI native bersama + untuk header atribusi, `/fast`/`serviceTier`, verbositas teks, + pencarian web native Codex, pembentukan payload reasoning-compat, dan + manajemen konteks Responses. - OpenRouter menggunakan `catalog` plus `resolveDynamicModel` dan - `prepareDynamicModel` karena penyedianya adalah pass-through dan dapat mengekspos - model id baru sebelum katalog statis OpenClaw diperbarui; ia juga menggunakan - `capabilities`, `wrapStreamFn`, dan `isCacheTtlEligible` untuk menjaga - header request, metadata routing, patch reasoning, dan kebijakan prompt-cache khusus penyedia tetap keluar dari core. Kebijakan replay-nya berasal dari keluarga - `passthrough-gemini`, sementara keluarga stream `openrouter-thinking` - memiliki injeksi reasoning proxy dan skip untuk model yang tidak didukung / `auto`. + `prepareDynamicModel` karena provider bersifat pass-through dan dapat + mengekspos model id baru sebelum katalog statis OpenClaw diperbarui; provider + ini juga menggunakan `capabilities`, `wrapStreamFn`, dan + `isCacheTtlEligible` untuk menjaga header request spesifik provider, + metadata routing, patch reasoning, dan kebijakan prompt-cache tetap di luar + core. Kebijakan replay-nya berasal dari keluarga `passthrough-gemini`, + sementara keluarga stream `openrouter-thinking` memiliki injection reasoning + proxy dan skip model yang tidak didukung / `auto`. - GitHub Copilot menggunakan `catalog`, `auth`, `resolveDynamicModel`, dan - `capabilities` plus `prepareRuntimeAuth` dan `fetchUsageSnapshot` karena ia - membutuhkan login perangkat milik penyedia, perilaku fallback model, keunikan - transkrip Claude, pertukaran token GitHub -> token Copilot, dan endpoint penggunaan milik penyedia. + `capabilities` plus `prepareRuntimeAuth` dan `fetchUsageSnapshot` karena + memerlukan login perangkat milik provider, perilaku fallback model, + kekhususan transkrip Claude, pertukaran token GitHub -> token Copilot, dan + endpoint usage milik provider. - OpenAI Codex menggunakan `catalog`, `resolveDynamicModel`, `normalizeResolvedModel`, `refreshOAuth`, dan `augmentModelCatalog` plus - `prepareExtraParams`, `resolveUsageAuth`, dan `fetchUsageSnapshot` karena ia + `prepareExtraParams`, `resolveUsageAuth`, dan `fetchUsageSnapshot` karena masih berjalan pada transport OpenAI core tetapi memiliki normalisasi - transport/base URL, kebijakan fallback refresh OAuth, pilihan transport default, - baris katalog Codex sintetis, dan integrasi endpoint penggunaan ChatGPT; ia - berbagi keluarga stream `openai-responses-defaults` yang sama dengan OpenAI langsung. -- Google AI Studio dan OAuth Gemini CLI menggunakan `resolveDynamicModel`, + transport/base URL, kebijakan fallback refresh OAuth, pilihan transport + default, baris katalog Codex sintetis, dan integrasi endpoint usage ChatGPT; + provider ini berbagi keluarga stream `openai-responses-defaults` yang sama + dengan OpenAI langsung. +- Google AI Studio dan Gemini CLI OAuth menggunakan `resolveDynamicModel`, `buildReplayPolicy`, `sanitizeReplayHistory`, - `resolveReasoningOutputMode`, `wrapStreamFn`, dan `isModernModelRef` karena keluarga replay - `google-gemini` memiliki fallback forward-compat Gemini 3.1, - validasi replay Gemini native, sanitasi replay bootstrap, - mode output reasoning bertag, dan pencocokan model modern, sementara - keluarga stream `google-thinking` memiliki normalisasi payload thinking Gemini; - OAuth Gemini CLI juga menggunakan `formatApiKey`, `resolveUsageAuth`, dan - `fetchUsageSnapshot` untuk format token, parsing token, dan wiring endpoint kuota. + `resolveReasoningOutputMode`, `wrapStreamFn`, dan `isModernModelRef` karena + keluarga replay `google-gemini` memiliki fallback forward-compat Gemini 3.1, + validasi replay Gemini native, sanitasi replay bootstrap, mode keluaran + reasoning bertag, dan pencocokan modern-model, sementara keluarga stream + `google-thinking` memiliki normalisasi payload thinking Gemini; + Gemini CLI OAuth juga menggunakan `formatApiKey`, `resolveUsageAuth`, dan + `fetchUsageSnapshot` untuk pemformatan token, parsing token, dan wiring + endpoint kuota. - Anthropic Vertex menggunakan `buildReplayPolicy` melalui keluarga replay - `anthropic-by-model` sehingga pembersihan replay khusus Claude tetap - dibatasi ke id Claude alih-alih setiap transport `anthropic-messages`. + `anthropic-by-model` sehingga pembersihan replay spesifik Claude tetap + terlingkup pada id Claude, bukan pada setiap transport `anthropic-messages`. - Amazon Bedrock menggunakan `buildReplayPolicy`, `matchesContextOverflowError`, - `classifyFailoverReason`, dan `resolveDefaultThinkingLevel` karena ia memiliki - klasifikasi error throttle/not-ready/context-overflow khusus Bedrock - untuk traffic Anthropic-on-Bedrock; kebijakan replay-nya masih berbagi guard - khusus Claude `anthropic-by-model` yang sama. + `classifyFailoverReason`, dan `resolveDefaultThinkingLevel` karena memiliki + klasifikasi error throttle/not-ready/context-overflow spesifik Bedrock untuk + trafik Anthropic-on-Bedrock; kebijakan replay-nya tetap berbagi guard + `anthropic-by-model` khusus Claude yang sama. - OpenRouter, Kilocode, Opencode, dan Opencode Go menggunakan `buildReplayPolicy` - melalui keluarga replay `passthrough-gemini` karena mereka memproksikan model + melalui keluarga replay `passthrough-gemini` karena mereka mem-proxy model Gemini melalui transport yang kompatibel dengan OpenAI dan memerlukan sanitasi thought-signature Gemini tanpa validasi replay Gemini native atau penulisan ulang bootstrap. - MiniMax menggunakan `buildReplayPolicy` melalui keluarga replay - `hybrid-anthropic-openai` karena satu penyedia memiliki semantik - anthrophic-message dan OpenAI-compatible sekaligus; ia menjaga pembuangan - thinking-block khusus Claude pada sisi Anthropic sambil meng-override mode - output reasoning kembali ke native, dan keluarga stream `minimax-fast-mode` memiliki - penulisan ulang model fast-mode pada jalur stream bersama. -- Moonshot menggunakan `catalog` plus `wrapStreamFn` karena ia masih menggunakan - transport OpenAI bersama tetapi memerlukan normalisasi payload thinking milik penyedia; keluarga stream `moonshot-thinking` memetakan config plus status `/think` ke payload binary thinking native miliknya. + `hybrid-anthropic-openai` karena satu provider memiliki semantik + pesan-Anthropic dan kompatibel-OpenAI; provider ini tetap mempertahankan + penghapusan thinking-block khusus Claude di sisi Anthropic sambil + meng-override mode keluaran reasoning kembali ke native, dan keluarga stream + `minimax-fast-mode` memiliki penulisan ulang model fast-mode pada jalur + stream bersama. +- Moonshot menggunakan `catalog` plus `wrapStreamFn` karena masih menggunakan + transport OpenAI bersama tetapi membutuhkan normalisasi payload thinking milik + provider; keluarga stream `moonshot-thinking` memetakan config plus status + `/think` ke payload thinking biner native. - Kilocode menggunakan `catalog`, `capabilities`, `wrapStreamFn`, dan - `isCacheTtlEligible` karena ia memerlukan header request milik penyedia, - normalisasi payload reasoning, petunjuk transkrip Gemini, dan gating - cache-TTL Anthropic; keluarga stream `kilocode-thinking` menjaga injeksi - Kilo thinking tetap pada jalur stream proxy bersama sambil melewati `kilo/auto` dan - model id proxy lain yang tidak mendukung payload reasoning eksplisit. + `isCacheTtlEligible` karena memerlukan header request milik provider, + normalisasi payload reasoning, petunjuk transkrip Gemini, dan gating TTL + cache Anthropic; keluarga stream `kilocode-thinking` menjaga injection + Kilo thinking pada jalur stream proxy bersama sambil melewati `kilo/auto` + dan id model proxy lain yang tidak mendukung payload reasoning eksplisit. - Z.AI menggunakan `resolveDynamicModel`, `prepareExtraParams`, `wrapStreamFn`, `isCacheTtlEligible`, `isBinaryThinking`, `isModernModelRef`, - `resolveUsageAuth`, dan `fetchUsageSnapshot` karena ia memiliki fallback GLM-5, - default `tool_stream`, UX binary thinking, pencocokan model modern, serta - auth penggunaan + pengambilan kuota; keluarga stream `tool-stream-default-on` menjaga - wrapper `tool_stream` default-on tetap keluar dari glue tulisan tangan per penyedia. + `resolveUsageAuth`, dan `fetchUsageSnapshot` karena memiliki fallback GLM-5, + default `tool_stream`, UX thinking biner, pencocokan modern-model, serta + auth usage + pengambilan kuota; keluarga stream `tool-stream-default-on` + menjaga wrapper `tool_stream` default-on tetap di luar glue tulisan tangan + per-provider. - xAI menggunakan `normalizeResolvedModel`, `normalizeTransport`, `contributeResolvedModelCompat`, `prepareExtraParams`, `wrapStreamFn`, `resolveSyntheticAuth`, `resolveDynamicModel`, dan `isModernModelRef` - karena ia memiliki normalisasi transport xAI Responses native, penulisan ulang alias - Grok fast-mode, default `tool_stream`, pembersihan strict-tool / reasoning-payload, - penggunaan ulang auth fallback untuk alat milik plugin, resolusi model Grok forward-compat, - dan patch compat milik penyedia seperti profil tool-schema xAI, - keyword schema yang tidak didukung, `web_search` native, dan decoding argumen - tool-call entitas HTML. -- Mistral, OpenCode Zen, dan OpenCode Go hanya menggunakan `capabilities` untuk - menjaga keunikan transkrip/tooling tetap keluar dari core. -- Penyedia bundled hanya-katalog seperti `byteplus`, `cloudflare-ai-gateway`, + karena memiliki normalisasi transport xAI Responses native, penulisan ulang + alias Grok fast-mode, default `tool_stream`, pembersihan strict-tool / + payload reasoning, penggunaan ulang auth fallback untuk tool milik plugin, + resolusi model Grok forward-compat, dan patch kompatibilitas milik provider + seperti profil tool-schema xAI, keyword schema yang tidak didukung, + `web_search` native, dan decoding argumen tool-call entitas HTML. +- Mistral, OpenCode Zen, dan OpenCode Go hanya menggunakan `capabilities` + untuk menjaga kekhususan transkrip/tooling tetap di luar core. +- Provider bundled khusus katalog seperti `byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`, `qianfan`, - `synthetic`, `together`, `venice`, `vercel-ai-gateway`, dan `volcengine` menggunakan - `catalog` saja. -- Qwen menggunakan `catalog` untuk text provider-nya plus pendaftaran bersama - media-understanding dan video-generation untuk permukaan multimodalnya. -- MiniMax dan Xiaomi menggunakan `catalog` plus hook penggunaan karena perilaku `/usage` - mereka dimiliki plugin meskipun inferensi tetap berjalan melalui transport bersama. + `synthetic`, `together`, `venice`, `vercel-ai-gateway`, dan `volcengine` + hanya menggunakan `catalog`. +- Qwen menggunakan `catalog` untuk provider teksnya plus pendaftaran + media-understanding dan video-generation bersama untuk surface multimodalnya. +- MiniMax dan Xiaomi menggunakan `catalog` plus hook usage karena perilaku + `/usage` mereka dimiliki plugin meskipun inferensi tetap berjalan melalui + transport bersama. ## Helper runtime @@ -900,14 +947,15 @@ const voices = await api.runtime.tts.listVoices({ Catatan: -- `textToSpeech` mengembalikan payload output TTS core normal untuk permukaan file/voice-note. -- Menggunakan konfigurasi core `messages.tts` dan pemilihan penyedia. -- Mengembalikan buffer audio PCM + sample rate. Plugin harus melakukan resample/encode untuk penyedia. -- `listVoices` bersifat opsional per penyedia. Gunakan ini untuk voice picker atau alur setup milik vendor. -- Daftar suara dapat menyertakan metadata yang lebih kaya seperti locale, gender, dan tag personality untuk picker yang sadar penyedia. +- `textToSpeech` mengembalikan payload keluaran TTS core normal untuk surface file/voice-note. +- Menggunakan konfigurasi `messages.tts` core dan pemilihan provider. +- Mengembalikan buffer audio PCM + sample rate. Plugin harus melakukan resample/encode untuk provider. +- `listVoices` bersifat opsional per provider. Gunakan untuk voice picker milik vendor atau alur setup. +- Daftar suara dapat mencakup metadata yang lebih kaya seperti locale, gender, dan tag personality untuk picker yang sadar provider. - OpenAI dan ElevenLabs saat ini mendukung telephony. Microsoft tidak. -Plugin juga dapat mendaftarkan speech provider melalui `api.registerSpeechProvider(...)`. +Plugin juga dapat mendaftarkan speech provider melalui +`api.registerSpeechProvider(...)`. ```ts api.registerSpeechProvider({ @@ -927,14 +975,15 @@ api.registerSpeechProvider({ Catatan: -- Simpan kebijakan TTS, fallback, dan pengiriman balasan di core. -- Gunakan speech provider untuk perilaku synthesis milik vendor. -- Input legacy Microsoft `edge` dinormalisasi ke provider id `microsoft`. -- Model kepemilikan yang diutamakan berorientasi perusahaan: satu plugin vendor dapat memiliki - text, speech, image, dan penyedia media masa depan saat OpenClaw menambahkan kontrak kapabilitas tersebut. +- Pertahankan kebijakan TTS, fallback, dan pengiriman balasan di core. +- Gunakan speech provider untuk perilaku sintesis milik vendor. +- Input `edge` Microsoft lama dinormalisasi menjadi id provider `microsoft`. +- Model kepemilikan yang diutamakan berorientasi perusahaan: satu plugin vendor + dapat memiliki provider teks, speech, gambar, dan media masa depan saat + OpenClaw menambahkan kontrak kapabilitas tersebut. Untuk pemahaman gambar/audio/video, plugin mendaftarkan satu provider -media-understanding bertipe alih-alih kumpulan key/value generik: +media-understanding yang typed alih-alih bag key/value generik: ```ts api.registerMediaUnderstandingProvider({ @@ -948,9 +997,10 @@ api.registerMediaUnderstandingProvider({ Catatan: -- Simpan orkestrasi, fallback, config, dan wiring channel di core. -- Simpan perilaku vendor di plugin penyedia. -- Ekspansi aditif harus tetap bertipe: metode opsional baru, field hasil opsional baru, kapabilitas opsional baru. +- Pertahankan orkestrasi, fallback, config, dan wiring channel di core. +- Pertahankan perilaku vendor di plugin provider. +- Ekspansi aditif harus tetap typed: metode opsional baru, field hasil opsional + baru, kapabilitas opsional baru. - Pembuatan video sudah mengikuti pola yang sama: - core memiliki kontrak kapabilitas dan helper runtime - plugin vendor mendaftarkan `api.registerVideoGenerationProvider(...)` @@ -978,20 +1028,21 @@ atau alias STT yang lebih lama: const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ filePath: "/tmp/inbound-audio.ogg", cfg: api.config, - // Optional when MIME cannot be inferred reliably: + // Opsional saat MIME tidak dapat diinferensikan secara andal: mime: "audio/ogg", }); ``` Catatan: -- `api.runtime.mediaUnderstanding.*` adalah permukaan bersama yang diutamakan untuk - pemahaman gambar/audio/video. -- Menggunakan konfigurasi audio media-understanding core (`tools.media.audio`) dan urutan fallback penyedia. -- Mengembalikan `{ text: undefined }` ketika tidak ada output transkripsi yang dihasilkan (misalnya input dilewati/tidak didukung). -- `api.runtime.stt.transcribeAudioFile(...)` tetap tersedia sebagai alias kompatibilitas. +- `api.runtime.mediaUnderstanding.*` adalah surface bersama yang diutamakan + untuk pemahaman gambar/audio/video. +- Menggunakan konfigurasi audio media-understanding core (`tools.media.audio`) dan urutan fallback provider. +- Mengembalikan `{ text: undefined }` ketika tidak ada keluaran transkripsi yang dihasilkan (misalnya input dilewati/tidak didukung). +- `api.runtime.stt.transcribeAudioFile(...)` tetap ada sebagai alias kompatibilitas. -Plugin juga dapat meluncurkan eksekusi subagent latar belakang melalui `api.runtime.subagent`: +Plugin juga dapat meluncurkan run subagen latar belakang melalui +`api.runtime.subagent`: ```ts const result = await api.runtime.subagent.run({ @@ -1005,14 +1056,14 @@ const result = await api.runtime.subagent.run({ Catatan: -- `provider` dan `model` adalah override per-eksekusi opsional, bukan perubahan sesi persisten. +- `provider` dan `model` adalah override per-run yang opsional, bukan perubahan sesi yang persisten. - OpenClaw hanya menghormati field override tersebut untuk pemanggil tepercaya. -- Untuk eksekusi fallback milik plugin, operator harus ikut serta dengan `plugins.entries..subagent.allowModelOverride: true`. +- Untuk run fallback milik plugin, operator harus memilih ikut serta dengan `plugins.entries..subagent.allowModelOverride: true`. - Gunakan `plugins.entries..subagent.allowedModels` untuk membatasi plugin tepercaya ke target `provider/model` kanonis tertentu, atau `"*"` untuk mengizinkan target apa pun secara eksplisit. -- Eksekusi subagent plugin yang tidak tepercaya tetap berfungsi, tetapi permintaan override ditolak alih-alih diam-diam fallback. +- Run subagen plugin yang tidak tepercaya tetap berfungsi, tetapi permintaan override ditolak alih-alih diam-diam fallback. Untuk pencarian web, plugin dapat mengonsumsi helper runtime bersama alih-alih -menjangkau wiring alat agen: +menjangkau wiring tool agen: ```ts const providers = api.runtime.webSearch.listProviders({ @@ -1028,14 +1079,14 @@ const result = await api.runtime.webSearch.search({ }); ``` -Plugin juga dapat mendaftarkan web-search providers melalui +Plugin juga dapat mendaftarkan web-search provider melalui `api.registerWebSearchProvider(...)`. Catatan: -- Simpan pemilihan penyedia, resolusi kredensial, dan semantik request bersama di core. -- Gunakan web-search providers untuk transport pencarian khusus vendor. -- `api.runtime.webSearch.*` adalah permukaan bersama yang diutamakan untuk plugin fitur/channel yang memerlukan perilaku pencarian tanpa bergantung pada wrapper alat agen. +- Pertahankan pemilihan provider, resolusi kredensial, dan semantik request bersama di core. +- Gunakan web-search provider untuk transport pencarian spesifik vendor. +- `api.runtime.webSearch.*` adalah surface bersama yang diutamakan untuk plugin fitur/channel yang memerlukan perilaku pencarian tanpa bergantung pada wrapper tool agen. ### `api.runtime.imageGeneration` @@ -1050,8 +1101,8 @@ const providers = api.runtime.imageGeneration.listProviders({ }); ``` -- `generate(...)`: hasilkan gambar menggunakan rantai penyedia image-generation yang dikonfigurasi. -- `listProviders(...)`: daftar penyedia image-generation yang tersedia dan kapabilitasnya. +- `generate(...)`: menghasilkan gambar menggunakan rantai provider pembuatan gambar yang dikonfigurasi. +- `listProviders(...)`: menampilkan daftar provider pembuatan gambar yang tersedia dan kapabilitasnya. ## Rute HTTP Gateway @@ -1075,31 +1126,31 @@ Field rute: - `path`: path rute di bawah server HTTP gateway. - `auth`: wajib. Gunakan `"gateway"` untuk mewajibkan auth gateway normal, atau `"plugin"` untuk auth/verifikasi webhook yang dikelola plugin. - `match`: opsional. `"exact"` (default) atau `"prefix"`. -- `replaceExisting`: opsional. Memungkinkan plugin yang sama mengganti pendaftaran rute miliknya sendiri yang sudah ada. -- `handler`: kembalikan `true` saat rute menangani request. +- `replaceExisting`: opsional. Mengizinkan plugin yang sama mengganti pendaftaran rute miliknya sendiri yang sudah ada. +- `handler`: kembalikan `true` saat rute menangani permintaan. Catatan: -- `api.registerHttpHandler(...)` telah dihapus dan akan menyebabkan error pemuatan plugin. Gunakan `api.registerHttpRoute(...)`. +- `api.registerHttpHandler(...)` telah dihapus dan akan menyebabkan error pemuatan plugin. Gunakan `api.registerHttpRoute(...)` sebagai gantinya. - Rute plugin harus mendeklarasikan `auth` secara eksplisit. - Konflik `path + match` exact ditolak kecuali `replaceExisting: true`, dan satu plugin tidak dapat mengganti rute milik plugin lain. - Rute yang tumpang tindih dengan level `auth` berbeda ditolak. Pertahankan rantai fallthrough `exact`/`prefix` hanya pada level auth yang sama. -- Rute `auth: "plugin"` **tidak** otomatis menerima runtime scope operator. Rute ini ditujukan untuk webhook/verifikasi signature yang dikelola plugin, bukan panggilan helper Gateway yang istimewa. -- Rute `auth: "gateway"` berjalan di dalam runtime scope request Gateway, tetapi scope itu sengaja konservatif: - - bearer auth shared-secret (`gateway.auth.mode = "token"` / `"password"`) menjaga runtime scope rute plugin tetap terkunci pada `operator.write`, meskipun pemanggil mengirim `x-openclaw-scopes` - - mode HTTP tepercaya yang membawa identitas (misalnya `trusted-proxy` atau `gateway.auth.mode = "none"` pada ingress privat) hanya menghormati `x-openclaw-scopes` bila header itu hadir secara eksplisit - - jika `x-openclaw-scopes` tidak ada pada request rute plugin yang membawa identitas tersebut, runtime scope akan fallback ke `operator.write` -- Aturan praktis: jangan mengasumsikan rute plugin dengan gateway-auth adalah permukaan admin implisit. Jika rute Anda memerlukan perilaku khusus admin, wajibkan mode auth yang membawa identitas dan dokumentasikan kontrak header `x-openclaw-scopes` yang eksplisit. +- Rute `auth: "plugin"` **tidak** menerima runtime scope operator secara otomatis. Rute ini untuk webhook/verifikasi signature yang dikelola plugin, bukan untuk panggilan helper Gateway yang berhak istimewa. +- Rute `auth: "gateway"` berjalan di dalam runtime scope permintaan Gateway, tetapi scope tersebut sengaja konservatif: + - shared-secret bearer auth (`gateway.auth.mode = "token"` / `"password"`) menjaga scope runtime rute-plugin tetap dipatok pada `operator.write`, bahkan jika pemanggil mengirim `x-openclaw-scopes` + - mode HTTP tepercaya yang membawa identitas (misalnya `trusted-proxy` atau `gateway.auth.mode = "none"` pada ingress privat) menghormati `x-openclaw-scopes` hanya ketika header tersebut memang ada + - jika `x-openclaw-scopes` tidak ada pada permintaan rute-plugin yang membawa identitas tersebut, scope runtime fallback ke `operator.write` +- Aturan praktis: jangan berasumsi rute plugin dengan auth gateway adalah surface admin implisit. Jika rute Anda memerlukan perilaku khusus admin, wajibkan mode auth yang membawa identitas dan dokumentasikan kontrak header `x-openclaw-scopes` yang eksplisit. -## Path import Plugin SDK +## Path impor Plugin SDK -Gunakan subpath SDK alih-alih import monolitik `openclaw/plugin-sdk` saat +Gunakan subpath SDK alih-alih impor monolitik `openclaw/plugin-sdk` saat menulis plugin: - `openclaw/plugin-sdk/plugin-entry` untuk primitif pendaftaran plugin. -- `openclaw/plugin-sdk/core` untuk kontrak generik bersama yang menghadap plugin. -- `openclaw/plugin-sdk/config-schema` untuk ekspor schema Zod root `openclaw.json` - (`OpenClawSchema`). +- `openclaw/plugin-sdk/core` untuk kontrak umum yang berhadapan dengan plugin. +- `openclaw/plugin-sdk/config-schema` untuk ekspor schema Zod `openclaw.json` + root (`OpenClawSchema`). - Primitif channel stabil seperti `openclaw/plugin-sdk/channel-setup`, `openclaw/plugin-sdk/setup-runtime`, `openclaw/plugin-sdk/setup-adapter-runtime`, @@ -1112,14 +1163,15 @@ menulis plugin: `openclaw/plugin-sdk/channel-reply-pipeline`, `openclaw/plugin-sdk/command-auth`, `openclaw/plugin-sdk/secret-input`, dan - `openclaw/plugin-sdk/webhook-ingress` untuk wiring - setup/auth/reply/webhook bersama. `channel-inbound` adalah rumah bersama - untuk debounce, mention matching, helper kebijakan mention masuk, formatting envelope, dan helper konteks envelope masuk. + `openclaw/plugin-sdk/webhook-ingress` untuk wiring setup/auth/reply/webhook + bersama. `channel-inbound` adalah rumah bersama untuk debounce, mention matching, + helper kebijakan mention inbound, pemformatan envelope, dan helper konteks + envelope inbound. `channel-setup` adalah seam setup optional-install yang sempit. - `setup-runtime` adalah permukaan setup yang aman untuk runtime yang digunakan oleh `setupEntry` / + `setup-runtime` adalah surface setup yang aman untuk runtime yang digunakan oleh `setupEntry` / startup tertunda, termasuk adapter patch setup yang aman untuk import. - `setup-adapter-runtime` adalah seam adapter setup akun yang sadar-env. - `setup-tools` adalah seam helper CLI/archive/docs kecil (`formatCliCommand`, + `setup-adapter-runtime` adalah seam adapter account-setup yang sadar env. + `setup-tools` adalah seam helper kecil CLI/archive/docs (`formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR`). - Subpath domain seperti `openclaw/plugin-sdk/channel-config-helpers`, @@ -1141,163 +1193,202 @@ menulis plugin: `openclaw/plugin-sdk/text-runtime`, `openclaw/plugin-sdk/runtime-store`, dan `openclaw/plugin-sdk/directory-runtime` untuk helper runtime/config bersama. - `telegram-command-config` adalah seam publik sempit untuk normalisasi/validasi perintah kustom Telegram dan tetap tersedia bahkan jika permukaan kontrak Telegram bundled sementara tidak tersedia. - `text-runtime` adalah seam bersama text/markdown/logging, termasuk - penghilangan teks yang terlihat oleh assistant, helper render/chunking markdown, helper redaction, helper directive-tag, dan utilitas safe-text. -- Seam channel khusus approval sebaiknya mengutamakan satu kontrak `approvalCapability` pada plugin. Core kemudian membaca auth approval, pengiriman, render, native-routing, dan perilaku lazy native-handler melalui satu kapabilitas itu alih-alih mencampur perilaku approval ke field plugin yang tidak terkait. -- `openclaw/plugin-sdk/channel-runtime` sudah deprecated dan tetap ada hanya sebagai shim kompatibilitas untuk plugin yang lebih lama. Kode baru sebaiknya mengimpor primitif generik yang lebih sempit, dan kode repo tidak boleh menambahkan import baru dari shim ini. -- Internal ekstensi bundled tetap privat. Plugin eksternal sebaiknya hanya menggunakan subpath `openclaw/plugin-sdk/*`. Kode core/test OpenClaw dapat menggunakan entry point publik repo di bawah root paket plugin seperti `index.js`, `api.js`, `runtime-api.js`, `setup-entry.js`, dan file bercakupan sempit seperti `login-qr-api.js`. Jangan pernah mengimpor `src/*` milik paket plugin dari core atau dari ekstensi lain. + `telegram-command-config` adalah seam publik sempit untuk normalisasi/validasi + perintah kustom Telegram dan tetap tersedia bahkan jika surface kontrak + Telegram bundled sementara tidak tersedia. + `text-runtime` adalah seam teks/markdown/logging bersama, termasuk + penghapusan teks yang terlihat oleh assistant, helper render/chunking markdown, + helper redaksi, helper directive-tag, dan utilitas teks aman. +- Seam channel spesifik approval harus lebih memilih satu kontrak + `approvalCapability` pada plugin. Core kemudian membaca auth approval, + pengiriman, render, native-routing, dan perilaku lazy native-handler melalui + satu kapabilitas tersebut alih-alih mencampur perilaku approval ke field + plugin yang tidak terkait. +- `openclaw/plugin-sdk/channel-runtime` sudah deprecated dan hanya tersisa + sebagai shim kompatibilitas untuk plugin lama. Kode baru sebaiknya mengimpor + primitif generik yang lebih sempit, dan kode repo tidak boleh menambahkan + impor baru dari shim tersebut. +- Internal ekstensi bundled tetap privat. Plugin eksternal sebaiknya hanya + menggunakan subpath `openclaw/plugin-sdk/*`. Kode core/test OpenClaw dapat + menggunakan entry point publik repo di bawah root paket plugin seperti + `index.js`, `api.js`, `runtime-api.js`, `setup-entry.js`, dan file yang sempit + seperti `login-qr-api.js`. Jangan pernah mengimpor `src/*` paket plugin dari + core atau dari ekstensi lain. - Pemisahan entry point repo: `/api.js` adalah barrel helper/types, `/runtime-api.js` adalah barrel khusus runtime, `/index.js` adalah entry plugin bundled, dan `/setup-entry.js` adalah entry plugin setup. -- Contoh penyedia bundled saat ini: +- Contoh provider bundled saat ini: - Anthropic menggunakan `api.js` / `contract-api.js` untuk helper stream Claude seperti `wrapAnthropicProviderStream`, helper beta-header, dan parsing `service_tier`. - - OpenAI menggunakan `api.js` untuk builder penyedia, helper model default, dan - builder penyedia realtime. - - OpenRouter menggunakan `api.js` untuk builder penyedianya plus helper onboarding/config, sementara `register.runtime.js` masih dapat mengekspor ulang helper generik `plugin-sdk/provider-stream` untuk penggunaan lokal repo. -- Entry point publik yang dimuat facade mengutamakan snapshot config runtime aktif - jika ada, lalu fallback ke file config ter-resolve di disk saat - OpenClaw belum melayani snapshot runtime. -- Primitif bersama generik tetap menjadi kontrak SDK publik yang diutamakan. Satu set kompatibilitas kecil yang dicadangkan dari seam helper berlabel channel bundled masih ada. Perlakukan itu sebagai seam pemeliharaan bundled/kompatibilitas, bukan target import pihak ketiga yang baru; kontrak lintas-channel baru tetap harus ditempatkan pada subpath `plugin-sdk/*` generik atau barrel `api.js` / `runtime-api.js` lokal plugin. + - OpenAI menggunakan `api.js` untuk builder provider, helper model default, dan builder provider realtime. + - OpenRouter menggunakan `api.js` untuk builder provider serta helper + onboarding/config, sementara `register.runtime.js` masih dapat mengekspor + ulang helper generik `plugin-sdk/provider-stream` untuk penggunaan lokal repo. +- Entry point publik yang dimuat melalui facade lebih memilih snapshot config + runtime aktif ketika ada, lalu fallback ke file config yang telah di-resolve + di disk saat OpenClaw belum menyajikan snapshot runtime. +- Primitif generik bersama tetap menjadi kontrak SDK publik yang diutamakan. + Sekumpulan kecil seam helper bermerek channel bundled yang dicadangkan masih + ada. Perlakukan ini sebagai seam pemeliharaan/kompatibilitas bundled, bukan + target impor pihak ketiga baru; kontrak lintas channel baru tetap harus + diterapkan pada subpath generik `plugin-sdk/*` atau barrel lokal plugin + `api.js` / `runtime-api.js`. Catatan kompatibilitas: - Hindari barrel root `openclaw/plugin-sdk` untuk kode baru. - Utamakan primitif stabil yang sempit terlebih dahulu. Subpath setup/pairing/reply/ feedback/contract/inbound/threading/command/secret-input/webhook/infra/ - allowlist/status/message-tool yang lebih baru adalah kontrak yang dituju untuk pekerjaan plugin bundled dan eksternal yang baru. - Parsing/matching target seharusnya berada di `openclaw/plugin-sdk/channel-targets`. - Gate aksi message dan helper message-id reaction seharusnya berada di + allowlist/status/message-tool yang lebih baru adalah kontrak yang dituju untuk + pekerjaan plugin bundled dan eksternal baru. + Parsing/matching target berada di `openclaw/plugin-sdk/channel-targets`. + Gerbang aksi message dan helper message-id reaction berada di `openclaw/plugin-sdk/channel-actions`. -- Barrel helper khusus ekstensi bundled tidak stabil secara default. Jika sebuah - helper hanya diperlukan oleh ekstensi bundled, simpan di balik seam - `api.js` atau `runtime-api.js` lokal ekstensi itu alih-alih mempromosikannya ke - `openclaw/plugin-sdk/`. -- Seam helper bersama yang baru harus generik, bukan berlabel channel. Parsing target bersama berada di `openclaw/plugin-sdk/channel-targets`; internal khusus channel tetap berada di balik seam `api.js` atau `runtime-api.js` lokal milik plugin yang bersangkutan. +- Barrel helper spesifik ekstensi bundled tidak stabil secara default. Jika + helper hanya dibutuhkan oleh ekstensi bundled, simpan helper itu di balik + seam lokal `api.js` atau `runtime-api.js` milik ekstensi tersebut alih-alih + mempromosikannya ke `openclaw/plugin-sdk/`. +- Seam helper bersama baru harus generik, bukan bermerek channel. Parsing target + bersama berada di `openclaw/plugin-sdk/channel-targets`; internal spesifik + channel tetap berada di balik seam lokal `api.js` atau `runtime-api.js` + milik plugin tersebut. - Subpath spesifik kapabilitas seperti `image-generation`, `media-understanding`, dan `speech` ada karena plugin bundled/native - menggunakannya saat ini. Keberadaannya sendiri tidak otomatis berarti setiap helper yang diekspor adalah kontrak eksternal jangka panjang yang dibekukan. + menggunakannya saat ini. Keberadaannya tidak dengan sendirinya berarti setiap + helper yang diekspor adalah kontrak eksternal jangka panjang yang dibekukan. -## Schema alat message +## Schema tool message -Plugin sebaiknya memiliki kontribusi schema `describeMessageTool(...)` khusus channel. -Simpan field khusus penyedia di plugin, bukan di core bersama. +Plugin harus memiliki kontribusi schema `describeMessageTool(...)` yang +spesifik channel. Simpan field spesifik provider di plugin, bukan di core +bersama. -Untuk fragmen schema portabel bersama, gunakan ulang helper generik yang diekspor melalui -`openclaw/plugin-sdk/channel-actions`: +Untuk fragmen schema portabel bersama, gunakan ulang helper generik yang +diekspor melalui `openclaw/plugin-sdk/channel-actions`: - `createMessageToolButtonsSchema()` untuk payload gaya grid tombol -- `createMessageToolCardSchema()` untuk payload kartu terstruktur +- `createMessageToolCardSchema()` untuk payload card terstruktur -Jika sebuah bentuk schema hanya masuk akal untuk satu penyedia, definisikan di source -plugin itu sendiri alih-alih mempromosikannya ke SDK bersama. +Jika suatu bentuk schema hanya masuk akal untuk satu provider, definisikan di +sumber plugin itu sendiri alih-alih mempromosikannya ke SDK bersama. ## Resolusi target channel -Plugin channel sebaiknya memiliki semantik target khusus channel. Simpan host -outbound bersama tetap generik dan gunakan permukaan messaging adapter untuk aturan penyedia: +Plugin channel harus memiliki semantik target spesifik channel. Pertahankan host +outbound bersama tetap generik dan gunakan surface messaging adapter untuk +aturan provider: -- `messaging.inferTargetChatType({ to })` memutuskan apakah target yang dinormalisasi - harus diperlakukan sebagai `direct`, `group`, atau `channel` sebelum lookup direktori. -- `messaging.targetResolver.looksLikeId(raw, normalized)` memberi tahu core apakah sebuah - input harus langsung melewati ke resolusi mirip-id alih-alih pencarian direktori. -- `messaging.targetResolver.resolveTarget(...)` adalah fallback plugin saat - core memerlukan resolusi akhir milik penyedia setelah normalisasi atau setelah - direktori gagal menemukan hasil. -- `messaging.resolveOutboundSessionRoute(...)` memiliki konstruksi rute sesi - khusus penyedia setelah target di-resolve. +- `messaging.inferTargetChatType({ to })` memutuskan apakah target yang telah + dinormalisasi harus diperlakukan sebagai `direct`, `group`, atau `channel` + sebelum lookup direktori. +- `messaging.targetResolver.looksLikeId(raw, normalized)` memberi tahu core + apakah input harus langsung melewati ke resolusi mirip-id alih-alih pencarian + direktori. +- `messaging.targetResolver.resolveTarget(...)` adalah fallback plugin ketika + core memerlukan resolusi akhir milik provider setelah normalisasi atau + setelah miss pada direktori. +- `messaging.resolveOutboundSessionRoute(...)` memiliki konstruksi route sesi + spesifik provider setelah target di-resolve. -Pemisahan yang direkomendasikan: +Pembagian yang direkomendasikan: -- Gunakan `inferTargetChatType` untuk keputusan kategori yang seharusnya terjadi sebelum - mencari peer/grup. -- Gunakan `looksLikeId` untuk pemeriksaan “perlakukan ini sebagai id target eksplisit/native”. -- Gunakan `resolveTarget` untuk fallback normalisasi khusus penyedia, bukan untuk - pencarian direktori yang luas. -- Simpan id native penyedia seperti chat id, thread id, JID, handle, dan room - id di dalam nilai `target` atau parameter khusus penyedia, bukan di field SDK generik. +- Gunakan `inferTargetChatType` untuk keputusan kategori yang harus terjadi + sebelum mencari peer/group. +- Gunakan `looksLikeId` untuk pemeriksaan "perlakukan ini sebagai id target + eksplisit/native". +- Gunakan `resolveTarget` untuk fallback normalisasi spesifik provider, bukan + untuk pencarian direktori yang luas. +- Pertahankan id native provider seperti chat id, thread id, JID, handle, dan room + id di dalam nilai `target` atau parameter spesifik provider, bukan di field + SDK generik. -## Direktori berbasis konfigurasi +## Direktori berbasis config -Plugin yang menurunkan entri direktori dari konfigurasi sebaiknya menyimpan logika itu di -plugin dan menggunakan ulang helper bersama dari +Plugin yang menurunkan entri direktori dari config harus menjaga logika itu di +dalam plugin dan menggunakan kembali helper bersama dari `openclaw/plugin-sdk/directory-runtime`. -Gunakan ini saat sebuah channel memerlukan peer/grup berbasis konfigurasi seperti: +Gunakan ini ketika suatu channel memerlukan peer/group berbasis config seperti: - peer DM yang digerakkan allowlist -- peta channel/grup yang dikonfigurasi -- fallback direktori statis yang dibatasi per akun +- peta channel/group yang dikonfigurasi +- fallback direktori statis yang terlingkup akun Helper bersama di `directory-runtime` hanya menangani operasi generik: - pemfilteran query -- penerapan batas -- helper dedupe/normalisasi +- penerapan limit +- helper deduplikasi/normalisasi - membangun `ChannelDirectoryEntry[]` -Inspeksi akun khusus channel dan normalisasi id sebaiknya tetap berada di implementasi plugin. +Inspeksi akun dan normalisasi id yang spesifik channel harus tetap berada di +implementasi plugin. -## Katalog penyedia +## Katalog provider -Plugin penyedia dapat mendefinisikan katalog model untuk inferensi dengan +Plugin provider dapat mendefinisikan katalog model untuk inferensi dengan `registerProvider({ catalog: { run(...) { ... } } })`. -`catalog.run(...)` mengembalikan bentuk yang sama seperti yang ditulis OpenClaw ke dalam -`models.providers`: +`catalog.run(...)` mengembalikan bentuk yang sama dengan yang ditulis OpenClaw +ke `models.providers`: - `{ provider }` untuk satu entri provider - `{ providers }` untuk beberapa entri provider -Gunakan `catalog` saat plugin memiliki model id, default base URL, atau metadata model -yang digating oleh auth. +Gunakan `catalog` ketika plugin memiliki model id spesifik provider, default +base URL, atau metadata model yang dijaga oleh auth. -`catalog.order` mengontrol kapan katalog plugin digabung relatif terhadap -penyedia implisit bawaan OpenClaw: +`catalog.order` mengontrol kapan katalog plugin digabungkan relatif terhadap +provider implisit bawaan OpenClaw: -- `simple`: penyedia API-key biasa atau yang digerakkan env -- `profile`: penyedia yang muncul saat profil auth ada -- `paired`: penyedia yang mensintesis beberapa entri provider terkait -- `late`: lintasan terakhir, setelah penyedia implisit lain +- `simple`: provider API-key biasa atau berbasis env +- `profile`: provider yang muncul saat auth profile ada +- `paired`: provider yang mensintesis beberapa entri provider terkait +- `late`: lintasan terakhir, setelah provider implisit lainnya -Penyedia yang lebih akhir menang pada tabrakan key, sehingga plugin dapat dengan sengaja -meng-override entri provider bawaan dengan provider id yang sama. +Provider yang lebih akhir menang pada tabrakan key, sehingga plugin dapat +secara sengaja meng-override entri provider bawaan dengan id provider yang sama. Kompatibilitas: -- `discovery` masih berfungsi sebagai alias legacy -- jika `catalog` dan `discovery` keduanya didaftarkan, OpenClaw menggunakan `catalog` +- `discovery` tetap berfungsi sebagai alias lama +- jika `catalog` dan `discovery` sama-sama didaftarkan, OpenClaw menggunakan `catalog` ## Inspeksi channel read-only -Jika plugin Anda mendaftarkan sebuah channel, utamakan implementasi +Jika plugin Anda mendaftarkan channel, sebaiknya implementasikan `plugin.config.inspectAccount(cfg, accountId)` bersama `resolveAccount(...)`. Mengapa: -- `resolveAccount(...)` adalah jalur runtime. Ia boleh mengasumsikan kredensial - telah dimaterialisasi sepenuhnya dan dapat gagal cepat saat secret yang diperlukan tidak ada. +- `resolveAccount(...)` adalah jalur runtime. Jalur ini boleh berasumsi bahwa + kredensial telah sepenuhnya dimaterialisasi dan dapat gagal cepat ketika + secret yang diperlukan tidak ada. - Jalur perintah read-only seperti `openclaw status`, `openclaw status --all`, - `openclaw channels status`, `openclaw channels resolve`, dan alur doctor/config - repair tidak seharusnya perlu mematerialisasi kredensial runtime hanya untuk - mendeskripsikan konfigurasi. + `openclaw channels status`, `openclaw channels resolve`, dan alur perbaikan + doctor/config tidak seharusnya perlu mematerialisasi kredensial runtime hanya + untuk mendeskripsikan konfigurasi. Perilaku `inspectAccount(...)` yang direkomendasikan: - Kembalikan hanya status akun yang deskriptif. - Pertahankan `enabled` dan `configured`. -- Sertakan field sumber/status kredensial jika relevan, seperti: +- Sertakan field sumber/status kredensial bila relevan, seperti: - `tokenSource`, `tokenStatus` - `botTokenSource`, `botTokenStatus` - `appTokenSource`, `appTokenStatus` - `signingSecretSource`, `signingSecretStatus` -- Anda tidak perlu mengembalikan nilai token mentah hanya untuk melaporkan ketersediaan read-only. Mengembalikan `tokenStatus: "available"` (dan field sumber yang cocok) sudah cukup untuk perintah bergaya status. -- Gunakan `configured_unavailable` saat kredensial dikonfigurasi melalui SecretRef tetapi tidak tersedia pada jalur perintah saat ini. +- Anda tidak perlu mengembalikan nilai token mentah hanya untuk melaporkan + ketersediaan read-only. Mengembalikan `tokenStatus: "available"` (dan field + sumber yang cocok) sudah cukup untuk perintah bergaya status. +- Gunakan `configured_unavailable` ketika kredensial dikonfigurasi melalui SecretRef tetapi + tidak tersedia di jalur perintah saat ini. -Ini memungkinkan perintah read-only melaporkan “dikonfigurasi tetapi tidak tersedia pada jalur perintah ini” alih-alih crash atau salah melaporkan akun sebagai tidak dikonfigurasi. +Ini memungkinkan perintah read-only melaporkan "configured but unavailable in +this command path" alih-alih crash atau salah melaporkan akun sebagai belum +dikonfigurasi. ## Package pack @@ -1313,63 +1404,67 @@ Direktori plugin dapat menyertakan `package.json` dengan `openclaw.extensions`: } ``` -Setiap entry menjadi plugin. Jika pack mencantumkan beberapa ekstensi, plugin id -menjadi `name/`. +Setiap entri menjadi sebuah plugin. Jika pack mencantumkan beberapa ekstensi, +id plugin menjadi `name/`. -Jika plugin Anda mengimpor dependency npm, instal dependency tersebut di direktori itu agar -`node_modules` tersedia (`npm install` / `pnpm install`). +Jika plugin Anda mengimpor dependensi npm, instal dependensi tersebut di +direktori itu agar `node_modules` tersedia (`npm install` / `pnpm install`). -Guardrail keamanan: setiap entri `openclaw.extensions` harus tetap berada di dalam direktori plugin -setelah resolusi symlink. Entri yang keluar dari direktori paket akan -ditolak. +Guardrail keamanan: setiap entri `openclaw.extensions` harus tetap berada di +dalam direktori plugin setelah resolusi symlink. Entri yang keluar dari +direktori paket akan ditolak. -Catatan keamanan: `openclaw plugins install` menginstal dependency plugin dengan -`npm install --omit=dev --ignore-scripts` (tanpa lifecycle scripts, tanpa dev dependencies saat runtime). Pertahankan pohon dependency plugin tetap “pure JS/TS” dan hindari paket yang memerlukan build `postinstall`. +Catatan keamanan: `openclaw plugins install` menginstal dependensi plugin dengan +`npm install --omit=dev --ignore-scripts` (tanpa lifecycle scripts, tanpa dependensi dev saat runtime). Pertahankan pohon dependensi plugin tetap "pure JS/TS" dan hindari paket yang memerlukan build `postinstall`. Opsional: `openclaw.setupEntry` dapat menunjuk ke modul ringan khusus setup. -Saat OpenClaw memerlukan permukaan setup untuk plugin channel yang dinonaktifkan, atau -saat plugin channel diaktifkan tetapi belum dikonfigurasi, ia memuat `setupEntry` -alih-alih entry plugin penuh. Ini menjaga startup dan setup lebih ringan -saat entry plugin utama Anda juga memasang alat, hook, atau kode khusus runtime lainnya. +Saat OpenClaw memerlukan surface setup untuk plugin channel yang dinonaktifkan, +atau ketika plugin channel diaktifkan tetapi masih belum dikonfigurasi, OpenClaw +memuat `setupEntry` alih-alih entri plugin penuh. Ini membuat startup dan setup +lebih ringan ketika entri plugin utama Anda juga melakukan wiring tool, hook, +atau kode khusus runtime lainnya. Opsional: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -dapat memasukkan plugin channel ke jalur `setupEntry` yang sama selama fase +dapat memilihkan plugin channel ke jalur `setupEntry` yang sama selama fase startup pra-listen gateway, bahkan ketika channel sudah dikonfigurasi. -Gunakan ini hanya saat `setupEntry` sepenuhnya mencakup permukaan startup yang harus ada -sebelum gateway mulai mendengarkan. Dalam praktiknya, itu berarti entry setup -harus mendaftarkan setiap kapabilitas milik channel yang dibutuhkan startup, seperti: +Gunakan ini hanya ketika `setupEntry` sepenuhnya mencakup surface startup yang +harus ada sebelum gateway mulai mendengarkan. Dalam praktiknya, itu berarti +entri setup harus mendaftarkan setiap kapabilitas milik channel yang dibutuhkan +startup, seperti: - pendaftaran channel itu sendiri -- setiap rute HTTP yang harus tersedia sebelum gateway mulai mendengarkan -- setiap metode gateway, alat, atau layanan yang harus ada selama jendela yang sama +- rute HTTP apa pun yang harus tersedia sebelum gateway mulai mendengarkan +- method gateway, tool, atau layanan apa pun yang harus ada selama jendela itu -Jika full entry Anda masih memiliki kapabilitas startup yang dibutuhkan, jangan aktifkan +Jika entri penuh Anda masih memiliki kapabilitas startup wajib, jangan aktifkan flag ini. Pertahankan plugin pada perilaku default dan biarkan OpenClaw memuat -full entry saat startup. +entri penuh saat startup. -Channel bundled juga dapat menerbitkan helper permukaan kontrak khusus setup yang -dapat dikonsultasikan core sebelum runtime channel penuh dimuat. Permukaan promotion setup saat ini adalah: +Channel bundled juga dapat menerbitkan helper surface kontrak khusus setup yang +dapat dikonsultasikan core sebelum runtime channel penuh dimuat. Surface promosi +setup saat ini adalah: - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -Core menggunakan permukaan itu saat perlu mempromosikan konfigurasi channel legacy single-account -ke `channels..accounts.*` tanpa memuat full entry plugin. -Matrix adalah contoh bundled saat ini: ia hanya memindahkan key auth/bootstrap ke -akun yang dipromosikan bernama saat named accounts sudah ada, dan ia dapat mempertahankan -key default-account non-kanonis yang sudah dikonfigurasi alih-alih selalu membuat -`accounts.default`. +Core menggunakan surface itu ketika perlu mempromosikan config channel +legacy akun tunggal ke `channels..accounts.*` tanpa memuat entri plugin +penuh. Matrix adalah contoh bundled saat ini: plugin ini hanya memindahkan key +auth/bootstrap ke akun bernama yang dipromosikan ketika akun bernama sudah ada, +dan dapat mempertahankan key default-account non-kanonis yang telah +dikonfigurasi alih-alih selalu membuat `accounts.default`. -Adapter patch setup itu menjaga discovery permukaan kontrak bundled tetap lazy. Waktu -import tetap ringan; permukaan promotion dimuat hanya pada penggunaan pertama alih-alih -masuk kembali ke startup channel bundled saat import modul. +Adapter patch setup tersebut menjaga discovery surface kontrak bundled tetap +lazy. Waktu import tetap ringan; surface promosi dimuat hanya saat pertama kali +digunakan alih-alih memasuki kembali startup channel bundled saat import modul. -Saat permukaan startup itu mencakup metode gateway RPC, simpan pada -prefix khusus plugin. Namespace admin core (`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`) tetap dicadangkan dan selalu di-resolve -ke `operator.admin`, bahkan jika plugin meminta scope yang lebih sempit. +Ketika surface startup tersebut mencakup method Gateway RPC, pertahankan method +itu pada prefix spesifik plugin. Namespace admin core (`config.*`, +`exec.approvals.*`, `wizard.*`, `update.*`) tetap dicadangkan dan selalu +di-resolve ke `operator.admin`, bahkan jika plugin meminta scope yang lebih +sempit. Contoh: @@ -1389,7 +1484,8 @@ Contoh: ### Metadata katalog channel Plugin channel dapat mengiklankan metadata setup/discovery melalui `openclaw.channel` dan -petunjuk instalasi melalui `openclaw.install`. Ini menjaga data katalog core tetap kosong dari data tetap. +petunjuk instalasi melalui `openclaw.install`. Ini menjaga data katalog core +tetap bebas data. Contoh: @@ -1404,7 +1500,7 @@ Contoh: "selectionLabel": "Nextcloud Talk (self-hosted)", "docsPath": "/channels/nextcloud-talk", "docsLabel": "nextcloud-talk", - "blurb": "Chat self-hosted melalui webhook bot Nextcloud Talk.", + "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.", "order": 65, "aliases": ["nc-talk", "nc"] }, @@ -1419,39 +1515,39 @@ Contoh: Field `openclaw.channel` yang berguna di luar contoh minimal: -- `detailLabel`: label sekunder untuk permukaan katalog/status yang lebih kaya -- `docsLabel`: ganti teks tautan untuk tautan dokumentasi -- `preferOver`: plugin/channel id prioritas lebih rendah yang seharusnya dikalahkan oleh entri katalog ini -- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: kontrol salinan untuk permukaan seleksi -- `markdownCapable`: menandai channel sebagai mampu markdown untuk keputusan formatting outbound -- `exposure.configured`: sembunyikan channel dari permukaan daftar channel yang dikonfigurasi saat diatur ke `false` -- `exposure.setup`: sembunyikan channel dari picker setup/configure interaktif saat diatur ke `false` -- `exposure.docs`: tandai channel sebagai internal/private untuk permukaan navigasi docs -- `showConfigured` / `showInSetup`: alias legacy masih diterima demi kompatibilitas; utamakan `exposure` -- `quickstartAllowFrom`: ikutkan channel ke alur quickstart `allowFrom` standar -- `forceAccountBinding`: wajibkan account binding eksplisit bahkan saat hanya ada satu akun -- `preferSessionLookupForAnnounceTarget`: utamakan lookup sesi saat me-resolve target announce +- `detailLabel`: label sekunder untuk surface katalog/status yang lebih kaya +- `docsLabel`: override teks tautan untuk tautan dokumentasi +- `preferOver`: id plugin/channel prioritas lebih rendah yang harus dikalahkan oleh entri katalog ini +- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: kontrol copy surface pemilihan +- `markdownCapable`: menandai channel sebagai mampu markdown untuk keputusan pemformatan outbound +- `exposure.configured`: sembunyikan channel dari surface daftar channel yang dikonfigurasi saat disetel ke `false` +- `exposure.setup`: sembunyikan channel dari picker setup/configure interaktif saat disetel ke `false` +- `exposure.docs`: tandai channel sebagai internal/private untuk surface navigasi dokumentasi +- `showConfigured` / `showInSetup`: alias lama yang masih diterima untuk kompatibilitas; utamakan `exposure` +- `quickstartAllowFrom`: memilihkan channel ke alur `allowFrom` quickstart standar +- `forceAccountBinding`: mewajibkan pengikatan akun eksplisit bahkan ketika hanya ada satu akun +- `preferSessionLookupForAnnounceTarget`: lebih memilih lookup sesi saat me-resolve target announce -OpenClaw juga dapat menggabungkan **katalog channel eksternal** (misalnya, ekspor registry MPM). -Letakkan file JSON di salah satu lokasi berikut: +OpenClaw juga dapat menggabungkan **katalog channel eksternal** (misalnya, ekspor +registry MPM). Letakkan file JSON di salah satu lokasi berikut: - `~/.openclaw/mpm/plugins.json` - `~/.openclaw/mpm/catalog.json` - `~/.openclaw/plugins/catalog.json` Atau arahkan `OPENCLAW_PLUGIN_CATALOG_PATHS` (atau `OPENCLAW_MPM_CATALOG_PATHS`) ke -satu atau lebih file JSON (dipisahkan dengan koma/titik koma/`PATH`). Setiap file harus -berisi `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Parser juga menerima `"packages"` atau `"plugins"` sebagai alias legacy untuk key `"entries"`. +satu atau lebih file JSON (dipisahkan koma/titik koma/`PATH`). Setiap file harus +berisi `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Parser juga menerima `"packages"` atau `"plugins"` sebagai alias lama untuk key `"entries"`. -## Plugin engine konteks +## Plugin context engine -Plugin engine konteks memiliki orkestrasi konteks sesi untuk ingest, assembly, +Plugin context engine memiliki orkestrasi konteks sesi untuk ingest, assembly, dan compaction. Daftarkan dari plugin Anda dengan `api.registerContextEngine(id, factory)`, lalu pilih engine aktif dengan `plugins.slots.contextEngine`. -Gunakan ini saat plugin Anda perlu mengganti atau memperluas pipeline konteks default -alih-alih hanya menambahkan pencarian memori atau hook. +Gunakan ini ketika plugin Anda perlu mengganti atau memperluas pipeline konteks +default alih-alih hanya menambahkan memory search atau hook. ```ts import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; @@ -1479,8 +1575,8 @@ export default function (api) { } ``` -Jika engine Anda **tidak** memiliki algoritme compaction, tetap implementasikan `compact()` -dan delegasikan secara eksplisit: +Jika engine Anda **tidak** memiliki algoritma compaction, tetap implementasikan +`compact()` dan delegasikan secara eksplisit: ```ts import { @@ -1517,45 +1613,46 @@ export default function (api) { ## Menambahkan kapabilitas baru -Saat sebuah plugin memerlukan perilaku yang tidak cocok dengan API saat ini, jangan melewati -sistem plugin dengan reach-in privat. Tambahkan kapabilitas yang hilang. +Ketika plugin membutuhkan perilaku yang tidak cocok dengan API saat ini, jangan +melewati sistem plugin dengan reach-in privat. Tambahkan kapabilitas yang hilang. Urutan yang direkomendasikan: 1. definisikan kontrak core - Putuskan perilaku bersama apa yang harus dimiliki core: kebijakan, fallback, penggabungan config, - lifecycle, semantik yang menghadap channel, dan bentuk helper runtime. -2. tambahkan permukaan pendaftaran/runtime plugin yang bertipe - Perluas `OpenClawPluginApi` dan/atau `api.runtime` dengan permukaan kapabilitas bertipe - yang paling kecil namun berguna. -3. hubungkan konsumen core + channel/fitur - Channel dan plugin fitur seharusnya mengonsumsi kapabilitas baru melalui core, + Putuskan perilaku bersama apa yang harus dimiliki core: kebijakan, fallback, merge config, + lifecycle, semantik yang berhadapan dengan channel, dan bentuk helper runtime. +2. tambahkan surface pendaftaran/runtime plugin yang typed + Perluas `OpenClawPluginApi` dan/atau `api.runtime` dengan surface kapabilitas + typed terkecil yang berguna. +3. wiring core + konsumen channel/fitur + Channel dan plugin fitur harus mengonsumsi kapabilitas baru melalui core, bukan dengan mengimpor implementasi vendor secara langsung. 4. daftarkan implementasi vendor - Plugin vendor kemudian mendaftarkan backend mereka terhadap kapabilitas tersebut. + Plugin vendor kemudian mendaftarkan backend mereka terhadap kapabilitas itu. 5. tambahkan cakupan kontrak - Tambahkan test agar bentuk kepemilikan dan pendaftaran tetap eksplisit dari waktu ke waktu. + Tambahkan pengujian agar bentuk kepemilikan dan pendaftaran tetap eksplisit + seiring waktu. -Inilah cara OpenClaw tetap opinionated tanpa menjadi hardcoded pada -sudut pandang satu penyedia. Lihat [Capability Cookbook](/id/plugins/architecture) -untuk daftar periksa file yang konkret dan contoh kerja. +Inilah cara OpenClaw tetap opinionated tanpa menjadi hardcoded ke worldview satu +provider. Lihat [Capability Cookbook](/id/plugins/architecture) +untuk checklist file yang konkret dan contoh yang dikerjakan. -### Daftar periksa kapabilitas +### Checklist kapabilitas Saat Anda menambahkan kapabilitas baru, implementasinya biasanya harus menyentuh -permukaan ini secara bersamaan: +surface-surface ini bersama-sama: -- jenis kontrak core di `src//types.ts` -- runner/helper runtime core di `src//runtime.ts` -- permukaan pendaftaran API plugin di `src/plugins/types.ts` +- tipe kontrak core di `src//types.ts` +- helper runner/runtime core di `src//runtime.ts` +- surface pendaftaran API plugin di `src/plugins/types.ts` - wiring registry plugin di `src/plugins/registry.ts` -- eksposur runtime plugin di `src/plugins/runtime/*` saat plugin fitur/channel +- ekspos runtime plugin di `src/plugins/runtime/*` ketika plugin fitur/channel perlu mengonsumsinya - helper capture/test di `src/test-utils/plugin-registration.ts` - assertion kepemilikan/kontrak di `src/plugins/contracts/registry.ts` -- docs operator/plugin di `docs/` +- dokumentasi operator/plugin di `docs/` -Jika salah satu permukaan itu hilang, biasanya itu merupakan tanda bahwa kapabilitasnya +Jika salah satu surface tersebut hilang, biasanya itu pertanda bahwa kapabilitas belum sepenuhnya terintegrasi. ### Templat kapabilitas @@ -1563,14 +1660,14 @@ belum sepenuhnya terintegrasi. Pola minimal: ```ts -// core contract +// kontrak core export type VideoGenerationProviderPlugin = { id: string; label: string; generateVideo: (req: VideoGenerationRequest) => Promise; }; -// plugin API +// API plugin api.registerVideoGenerationProvider({ id: "openai", label: "OpenAI", @@ -1579,14 +1676,14 @@ api.registerVideoGenerationProvider({ }, }); -// shared runtime helper for feature/channel plugins +// helper runtime bersama untuk plugin fitur/channel const clip = await api.runtime.videoGeneration.generate({ prompt: "Show the robot walking through the lab.", cfg, }); ``` -Pola test kontrak: +Pola pengujian kontrak: ```ts expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); @@ -1597,4 +1694,4 @@ Ini menjaga aturannya tetap sederhana: - core memiliki kontrak kapabilitas + orkestrasi - plugin vendor memiliki implementasi vendor - plugin fitur/channel mengonsumsi helper runtime -- test kontrak menjaga kepemilikan tetap eksplisit +- pengujian kontrak menjaga kepemilikan tetap eksplisit diff --git a/docs/id/plugins/manifest.md b/docs/id/plugins/manifest.md index c5f92f8e8..ee86dfaa6 100644 --- a/docs/id/plugins/manifest.md +++ b/docs/id/plugins/manifest.md @@ -1,67 +1,67 @@ --- read_when: - Anda sedang membangun plugin OpenClaw - - Anda perlu merilis skema config plugin atau men-debug error validasi plugin -summary: Manifest plugin + persyaratan skema JSON (validasi config ketat) -title: Manifest Plugin + - Anda perlu merilis skema konfigurasi plugin atau men-debug error validasi plugin +summary: Manifes plugin + persyaratan skema JSON (validasi konfigurasi ketat) +title: Manifes Plugin x-i18n: - generated_at: "2026-04-07T09:16:21Z" + generated_at: "2026-04-09T01:28:53Z" model: gpt-5.4 provider: openai - source_hash: 22d41b9f8748b1b1b066ee856be4a8f41e88b9a8bc073d74fc79d2bb0982f01a + source_hash: 9a7ee4b621a801d2a8f32f8976b0e1d9433c7810eb360aca466031fc0ffb286a source_path: plugins/manifest.md workflow: 15 --- -# Manifest plugin (openclaw.plugin.json) +# Manifes plugin (openclaw.plugin.json) -Halaman ini hanya untuk **manifest plugin OpenClaw native**. +Halaman ini hanya untuk **manifes plugin OpenClaw native**. -Untuk tata letak bundle yang kompatibel, lihat [Plugin bundles](/id/plugins/bundles). +Untuk layout bundle yang kompatibel, lihat [Bundle plugin](/id/plugins/bundles). -Format bundle yang kompatibel menggunakan file manifest yang berbeda: +Format bundle yang kompatibel menggunakan file manifes yang berbeda: - Bundle Codex: `.codex-plugin/plugin.json` -- Bundle Claude: `.claude-plugin/plugin.json` atau tata letak komponen Claude - default tanpa manifest +- Bundle Claude: `.claude-plugin/plugin.json` atau layout komponen Claude default + tanpa manifes - Bundle Cursor: `.cursor-plugin/plugin.json` -OpenClaw juga mendeteksi otomatis tata letak bundle tersebut, tetapi tidak divalidasi +OpenClaw juga mendeteksi otomatis layout bundle tersebut, tetapi tidak divalidasi terhadap skema `openclaw.plugin.json` yang dijelaskan di sini. -Untuk bundle yang kompatibel, OpenClaw saat ini membaca metadata bundle plus root -skill yang dideklarasikan, root perintah Claude, default `settings.json` bundle Claude, -default LSP bundle Claude, dan hook pack yang didukung saat tata letaknya cocok +Untuk bundle yang kompatibel, OpenClaw saat ini membaca metadata bundle serta +root Skills yang dideklarasikan, root perintah Claude, default `settings.json` bundle Claude, +default LSP bundle Claude, dan pack hook yang didukung saat layout sesuai dengan ekspektasi runtime OpenClaw. Setiap plugin OpenClaw native **harus** menyertakan file `openclaw.plugin.json` di -**root plugin**. OpenClaw menggunakan manifest ini untuk memvalidasi konfigurasi -**tanpa mengeksekusi kode plugin**. Manifest yang hilang atau tidak valid diperlakukan sebagai -error plugin dan memblokir validasi config. +**root plugin**. OpenClaw menggunakan manifes ini untuk memvalidasi konfigurasi +**tanpa menjalankan kode plugin**. Manifes yang hilang atau tidak valid diperlakukan sebagai +error plugin dan memblokir validasi konfigurasi. Lihat panduan lengkap sistem plugin: [Plugins](/id/tools/plugin). Untuk model kapabilitas native dan panduan kompatibilitas eksternal saat ini: -[Capability model](/id/plugins/architecture#public-capability-model). +[Model kapabilitas](/id/plugins/architecture#public-capability-model). ## Fungsi file ini -`openclaw.plugin.json` adalah metadata yang dibaca OpenClaw sebelum memuat kode -plugin Anda. +`openclaw.plugin.json` adalah metadata yang dibaca OpenClaw sebelum memuat +kode plugin Anda. Gunakan untuk: - identitas plugin -- validasi config -- metadata auth dan onboarding yang harus tersedia tanpa menjalankan runtime +- validasi konfigurasi +- metadata auth dan onboarding yang harus tersedia tanpa mem-boot runtime plugin -- metadata alias dan auto-enable yang harus di-resolve sebelum runtime plugin dimuat -- metadata kepemilikan shorthand model-family yang seharusnya mengaktifkan - plugin secara otomatis sebelum runtime dimuat -- snapshot kepemilikan kapabilitas statis yang digunakan untuk wiring kompatibilitas - bawaan dan cakupan kontrak -- metadata config khusus channel yang harus digabungkan ke permukaan katalog dan validasi +- metadata alias dan auto-enable yang harus diselesaikan sebelum runtime plugin dimuat +- metadata kepemilikan keluarga model shorthand yang harus mengaktifkan otomatis + plugin sebelum runtime dimuat +- snapshot kepemilikan kapabilitas statis yang digunakan untuk wiring kompatibilitas bawaan dan + cakupan kontrak +- metadata konfigurasi khusus channel yang harus digabungkan ke surface katalog dan validasi tanpa memuat runtime -- petunjuk UI config +- petunjuk UI konfigurasi Jangan gunakan untuk: @@ -69,7 +69,7 @@ Jangan gunakan untuk: - mendeklarasikan entrypoint kode - metadata instalasi npm -Hal-hal tersebut milik kode plugin Anda dan `package.json`. +Hal-hal tersebut termasuk dalam kode plugin Anda dan `package.json`. ## Contoh minimal @@ -90,7 +90,7 @@ Hal-hal tersebut milik kode plugin Anda dan `package.json`. { "id": "openrouter", "name": "OpenRouter", - "description": "Plugin provider OpenRouter", + "description": "Plugin penyedia OpenRouter", "version": "1.0.0", "providers": ["openrouter"], "modelSupport": { @@ -100,6 +100,9 @@ Hal-hal tersebut milik kode plugin Anda dan `package.json`. "providerAuthEnvVars": { "openrouter": ["OPENROUTER_API_KEY"] }, + "providerAuthAliases": { + "openrouter-coding": "openrouter" + }, "channelEnvVars": { "openrouter-chatops": ["OPENROUTER_CHATOPS_TOKEN"] }, @@ -137,58 +140,59 @@ Hal-hal tersebut milik kode plugin Anda dan `package.json`. } ``` -## Referensi field tingkat atas +## Referensi field level teratas -| Field | Wajib | Tipe | Artinya | -| ----------------------------------- | -------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | Ya | `string` | ID plugin kanonis. Ini adalah ID yang digunakan di `plugins.entries.`. | -| `configSchema` | Ya | `object` | JSON Schema inline untuk config plugin ini. | -| `enabledByDefault` | Tidak | `true` | Menandai plugin bawaan sebagai aktif secara default. Hilangkan, atau atur ke nilai selain `true`, agar plugin tetap nonaktif secara default. | -| `legacyPluginIds` | Tidak | `string[]` | ID lama yang dinormalisasi ke ID plugin kanonis ini. | -| `autoEnableWhenConfiguredProviders` | Tidak | `string[]` | ID provider yang seharusnya mengaktifkan plugin ini secara otomatis saat auth, config, atau referensi model menyebutkannya. | -| `kind` | Tidak | `"memory"` \| `"context-engine"` | Mendeklarasikan jenis plugin eksklusif yang digunakan oleh `plugins.slots.*`. | -| `channels` | Tidak | `string[]` | ID channel yang dimiliki plugin ini. Digunakan untuk discovery dan validasi config. | -| `providers` | Tidak | `string[]` | ID provider yang dimiliki plugin ini. | -| `modelSupport` | Tidak | `object` | Metadata shorthand model-family milik manifest yang digunakan untuk auto-load plugin sebelum runtime. | -| `cliBackends` | Tidak | `string[]` | ID backend inferensi CLI yang dimiliki plugin ini. Digunakan untuk auto-activation saat startup dari referensi config eksplisit. | -| `providerAuthEnvVars` | Tidak | `Record` | Metadata env auth provider yang ringan yang dapat diperiksa OpenClaw tanpa memuat kode plugin. | -| `channelEnvVars` | Tidak | `Record` | Metadata env channel yang ringan yang dapat diperiksa OpenClaw tanpa memuat kode plugin. Gunakan ini untuk permukaan penyiapan channel atau auth berbasis env yang harus terlihat oleh helper startup/config generik. | -| `providerAuthChoices` | Tidak | `object[]` | Metadata pilihan auth ringan untuk picker onboarding, resolusi provider pilihan, dan wiring flag CLI sederhana. | -| `contracts` | Tidak | `object` | Snapshot kapabilitas bawaan statis untuk speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search, dan kepemilikan tool. | -| `channelConfigs` | Tidak | `Record` | Metadata config channel milik manifest yang digabungkan ke permukaan discovery dan validasi sebelum runtime dimuat. | -| `skills` | Tidak | `string[]` | Direktori Skills yang akan dimuat, relatif terhadap root plugin. | -| `name` | Tidak | `string` | Nama plugin yang dapat dibaca manusia. | -| `description` | Tidak | `string` | Ringkasan singkat yang ditampilkan di permukaan plugin. | -| `version` | Tidak | `string` | Versi plugin informasional. | -| `uiHints` | Tidak | `Record` | Label UI, placeholder, dan petunjuk sensitivitas untuk field config. | +| Field | Wajib | Tipe | Artinya | +| ----------------------------------- | -------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `id` | Ya | `string` | Id plugin kanonis. Ini adalah id yang digunakan di `plugins.entries.`. | +| `configSchema` | Ya | `object` | JSON Schema inline untuk konfigurasi plugin ini. | +| `enabledByDefault` | Tidak | `true` | Menandai plugin bawaan sebagai aktif secara default. Hilangkan field ini, atau setel nilai apa pun selain `true`, agar plugin tetap nonaktif secara default. | +| `legacyPluginIds` | Tidak | `string[]` | Id lama yang dinormalisasi ke id plugin kanonis ini. | +| `autoEnableWhenConfiguredProviders` | Tidak | `string[]` | Id penyedia yang harus mengaktifkan otomatis plugin ini saat auth, konfigurasi, atau referensi model menyebutkannya. | +| `kind` | Tidak | `"memory"` \| `"context-engine"` | Mendeklarasikan jenis plugin eksklusif yang digunakan oleh `plugins.slots.*`. | +| `channels` | Tidak | `string[]` | Id channel yang dimiliki plugin ini. Digunakan untuk discovery dan validasi konfigurasi. | +| `providers` | Tidak | `string[]` | Id penyedia yang dimiliki plugin ini. | +| `modelSupport` | Tidak | `object` | Metadata keluarga model shorthand yang dimiliki manifes dan digunakan untuk memuat otomatis plugin sebelum runtime. | +| `cliBackends` | Tidak | `string[]` | Id backend inferensi CLI yang dimiliki plugin ini. Digunakan untuk auto-aktivasi saat startup dari referensi konfigurasi eksplisit. | +| `providerAuthEnvVars` | Tidak | `Record` | Metadata env auth penyedia ringan yang dapat diperiksa OpenClaw tanpa memuat kode plugin. | +| `providerAuthAliases` | Tidak | `Record` | Id penyedia yang harus menggunakan ulang id penyedia lain untuk lookup auth, misalnya penyedia coding yang berbagi kunci API penyedia dasar dan profil auth. | +| `channelEnvVars` | Tidak | `Record` | Metadata env channel ringan yang dapat diperiksa OpenClaw tanpa memuat kode plugin. Gunakan ini untuk penyiapan channel berbasis env atau surface auth yang perlu terlihat oleh helper startup/konfigurasi generik. | +| `providerAuthChoices` | Tidak | `object[]` | Metadata pilihan auth ringan untuk picker onboarding, resolusi preferred-provider, dan wiring flag CLI sederhana. | +| `contracts` | Tidak | `object` | Snapshot kapabilitas bawaan statis untuk speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search, dan kepemilikan alat. | +| `channelConfigs` | Tidak | `Record` | Metadata konfigurasi channel milik manifes yang digabungkan ke surface discovery dan validasi sebelum runtime dimuat. | +| `skills` | Tidak | `string[]` | Direktori Skills yang akan dimuat, relatif ke root plugin. | +| `name` | Tidak | `string` | Nama plugin yang dapat dibaca manusia. | +| `description` | Tidak | `string` | Ringkasan singkat yang ditampilkan di surface plugin. | +| `version` | Tidak | `string` | Versi plugin informasional. | +| `uiHints` | Tidak | `Record` | Label UI, placeholder, dan petunjuk sensitivitas untuk field konfigurasi. | -## Referensi `providerAuthChoices` +## Referensi providerAuthChoices Setiap entri `providerAuthChoices` menjelaskan satu pilihan onboarding atau auth. -OpenClaw membacanya sebelum runtime provider dimuat. +OpenClaw membacanya sebelum runtime penyedia dimuat. -| Field | Wajib | Tipe | Artinya | -| --------------------- | -------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -| `provider` | Ya | `string` | ID provider tempat pilihan ini berada. | -| `method` | Ya | `string` | ID metode auth untuk dispatch. | -| `choiceId` | Ya | `string` | ID pilihan auth stabil yang digunakan oleh alur onboarding dan CLI. | -| `choiceLabel` | Tidak | `string` | Label yang ditampilkan ke pengguna. Jika dihilangkan, OpenClaw akan fallback ke `choiceId`. | -| `choiceHint` | Tidak | `string` | Teks bantuan singkat untuk picker. | -| `assistantPriority` | Tidak | `number` | Nilai yang lebih rendah diurutkan lebih awal di picker interaktif yang digerakkan asisten. | -| `assistantVisibility` | Tidak | `"visible"` \| `"manual-only"` | Menyembunyikan pilihan dari picker asisten sambil tetap mengizinkan pemilihan CLI manual. | -| `deprecatedChoiceIds` | Tidak | `string[]` | ID pilihan lama yang harus mengarahkan pengguna ke pilihan pengganti ini. | -| `groupId` | Tidak | `string` | ID grup opsional untuk mengelompokkan pilihan terkait. | -| `groupLabel` | Tidak | `string` | Label yang ditampilkan ke pengguna untuk grup tersebut. | -| `groupHint` | Tidak | `string` | Teks bantuan singkat untuk grup tersebut. | -| `optionKey` | Tidak | `string` | Kunci opsi internal untuk alur auth satu-flag sederhana. | -| `cliFlag` | Tidak | `string` | Nama flag CLI, seperti `--openrouter-api-key`. | -| `cliOption` | Tidak | `string` | Bentuk opsi CLI lengkap, seperti `--openrouter-api-key `. | -| `cliDescription` | Tidak | `string` | Deskripsi yang digunakan dalam bantuan CLI. | -| `onboardingScopes` | Tidak | `Array<"text-inference" \| "image-generation">` | Permukaan onboarding tempat pilihan ini harus muncul. Jika dihilangkan, default-nya `["text-inference"]`. | +| Field | Wajib | Tipe | Artinya | +| --------------------- | -------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| `provider` | Ya | `string` | Id penyedia tempat pilihan ini berada. | +| `method` | Ya | `string` | Id metode auth yang akan digunakan untuk dispatch. | +| `choiceId` | Ya | `string` | Id pilihan auth stabil yang digunakan oleh alur onboarding dan CLI. | +| `choiceLabel` | Tidak | `string` | Label untuk pengguna. Jika dihilangkan, OpenClaw menggunakan fallback ke `choiceId`. | +| `choiceHint` | Tidak | `string` | Teks bantuan singkat untuk picker. | +| `assistantPriority` | Tidak | `number` | Nilai yang lebih rendah diurutkan lebih awal dalam picker interaktif yang digerakkan asisten. | +| `assistantVisibility` | Tidak | `"visible"` \| `"manual-only"` | Sembunyikan pilihan dari picker asisten sambil tetap mengizinkan pemilihan CLI manual. | +| `deprecatedChoiceIds` | Tidak | `string[]` | Id pilihan lama yang harus mengarahkan pengguna ke pilihan pengganti ini. | +| `groupId` | Tidak | `string` | Id grup opsional untuk mengelompokkan pilihan yang terkait. | +| `groupLabel` | Tidak | `string` | Label untuk pengguna bagi grup tersebut. | +| `groupHint` | Tidak | `string` | Teks bantuan singkat untuk grup tersebut. | +| `optionKey` | Tidak | `string` | Key opsi internal untuk alur auth sederhana dengan satu flag. | +| `cliFlag` | Tidak | `string` | Nama flag CLI, seperti `--openrouter-api-key`. | +| `cliOption` | Tidak | `string` | Bentuk opsi CLI lengkap, seperti `--openrouter-api-key `. | +| `cliDescription` | Tidak | `string` | Deskripsi yang digunakan dalam bantuan CLI. | +| `onboardingScopes` | Tidak | `Array<"text-inference" \| "image-generation">` | Surface onboarding tempat pilihan ini harus ditampilkan. Jika dihilangkan, defaultnya adalah `["text-inference"]`. | -## Referensi `uiHints` +## Referensi uiHints -`uiHints` adalah peta dari nama field config ke petunjuk rendering kecil. +`uiHints` adalah peta dari nama field konfigurasi ke petunjuk rendering kecil. ```json { @@ -205,16 +209,16 @@ OpenClaw membacanya sebelum runtime provider dimuat. Setiap petunjuk field dapat mencakup: -| Field | Tipe | Artinya | -| ------------- | ---------- | ---------------------------------------- | -| `label` | `string` | Label field yang ditampilkan ke pengguna. | -| `help` | `string` | Teks bantuan singkat. | -| `tags` | `string[]` | Tag UI opsional. | -| `advanced` | `boolean` | Menandai field sebagai lanjutan. | +| Field | Tipe | Artinya | +| ------------- | ---------- | --------------------------------------- | +| `label` | `string` | Label field untuk pengguna. | +| `help` | `string` | Teks bantuan singkat. | +| `tags` | `string[]` | Tag UI opsional. | +| `advanced` | `boolean` | Menandai field sebagai lanjutan. | | `sensitive` | `boolean` | Menandai field sebagai rahasia atau sensitif. | -| `placeholder` | `string` | Teks placeholder untuk input formulir. | +| `placeholder` | `string` | Teks placeholder untuk input formulir. | -## Referensi `contracts` +## Referensi contracts Gunakan `contracts` hanya untuk metadata kepemilikan kapabilitas statis yang dapat dibaca OpenClaw tanpa mengimpor runtime plugin. @@ -237,21 +241,21 @@ dibaca OpenClaw tanpa mengimpor runtime plugin. Setiap daftar bersifat opsional: -| Field | Tipe | Artinya | -| -------------------------------- | ---------- | ------------------------------------------------------------- | -| `speechProviders` | `string[]` | ID provider speech yang dimiliki plugin ini. | -| `realtimeTranscriptionProviders` | `string[]` | ID provider realtime-transcription yang dimiliki plugin ini. | -| `realtimeVoiceProviders` | `string[]` | ID provider realtime-voice yang dimiliki plugin ini. | -| `mediaUnderstandingProviders` | `string[]` | ID provider media-understanding yang dimiliki plugin ini. | -| `imageGenerationProviders` | `string[]` | ID provider image-generation yang dimiliki plugin ini. | -| `videoGenerationProviders` | `string[]` | ID provider video-generation yang dimiliki plugin ini. | -| `webFetchProviders` | `string[]` | ID provider web-fetch yang dimiliki plugin ini. | -| `webSearchProviders` | `string[]` | ID provider web-search yang dimiliki plugin ini. | -| `tools` | `string[]` | Nama tool agen yang dimiliki plugin ini untuk pemeriksaan kontrak bawaan. | +| Field | Tipe | Artinya | +| -------------------------------- | ---------- | ---------------------------------------------------------- | +| `speechProviders` | `string[]` | Id penyedia speech yang dimiliki plugin ini. | +| `realtimeTranscriptionProviders` | `string[]` | Id penyedia transkripsi realtime yang dimiliki plugin ini. | +| `realtimeVoiceProviders` | `string[]` | Id penyedia suara realtime yang dimiliki plugin ini. | +| `mediaUnderstandingProviders` | `string[]` | Id penyedia pemahaman media yang dimiliki plugin ini. | +| `imageGenerationProviders` | `string[]` | Id penyedia pembuatan gambar yang dimiliki plugin ini. | +| `videoGenerationProviders` | `string[]` | Id penyedia pembuatan video yang dimiliki plugin ini. | +| `webFetchProviders` | `string[]` | Id penyedia pengambilan web yang dimiliki plugin ini. | +| `webSearchProviders` | `string[]` | Id penyedia pencarian web yang dimiliki plugin ini. | +| `tools` | `string[]` | Nama alat agen yang dimiliki plugin ini untuk pemeriksaan kontrak bawaan. | -## Referensi `channelConfigs` +## Referensi channelConfigs -Gunakan `channelConfigs` saat plugin channel memerlukan metadata config ringan sebelum +Gunakan `channelConfigs` saat plugin channel memerlukan metadata konfigurasi ringan sebelum runtime dimuat. ```json @@ -281,18 +285,18 @@ runtime dimuat. Setiap entri channel dapat mencakup: -| Field | Tipe | Artinya | -| ------------- | ------------------------ | ---------------------------------------------------------------------------------------- | -| `schema` | `object` | JSON Schema untuk `channels.`. Wajib untuk setiap entri config channel yang dideklarasikan. | -| `uiHints` | `Record` | Label UI/placeholders/petunjuk sensitif opsional untuk bagian config channel tersebut. | -| `label` | `string` | Label channel yang digabungkan ke permukaan picker dan inspect saat metadata runtime belum siap. | -| `description` | `string` | Deskripsi channel singkat untuk permukaan inspect dan katalog. | -| `preferOver` | `string[]` | ID plugin lama atau berprioritas lebih rendah yang harus dikalahkan channel ini di permukaan pemilihan. | +| Field | Tipe | Artinya | +| ------------- | ------------------------ | ----------------------------------------------------------------------------------------- | +| `schema` | `object` | JSON Schema untuk `channels.`. Wajib untuk setiap entri konfigurasi channel yang dideklarasikan. | +| `uiHints` | `Record` | Label UI/placeholder/petunjuk sensitif opsional untuk bagian konfigurasi channel tersebut. | +| `label` | `string` | Label channel yang digabungkan ke picker dan surface inspect saat metadata runtime belum siap. | +| `description` | `string` | Deskripsi channel singkat untuk surface inspect dan katalog. | +| `preferOver` | `string[]` | Id plugin lama atau prioritas lebih rendah yang harus dikalahkan channel ini di surface pemilihan. | -## Referensi `modelSupport` +## Referensi modelSupport -Gunakan `modelSupport` saat OpenClaw harus menyimpulkan plugin provider Anda dari -ID model shorthand seperti `gpt-5.4` atau `claude-sonnet-4.6` sebelum runtime plugin +Gunakan `modelSupport` saat OpenClaw harus menyimpulkan plugin penyedia Anda dari +id model shorthand seperti `gpt-5.4` atau `claude-sonnet-4.6` sebelum runtime plugin dimuat. ```json @@ -306,37 +310,37 @@ dimuat. OpenClaw menerapkan prioritas berikut: -- referensi eksplisit `provider/model` menggunakan metadata manifest `providers` yang memilikinya +- referensi `provider/model` eksplisit menggunakan metadata manifes `providers` milik plugin - `modelPatterns` mengalahkan `modelPrefixes` - jika satu plugin non-bawaan dan satu plugin bawaan sama-sama cocok, plugin non-bawaan - menang -- ambiguitas yang tersisa diabaikan sampai pengguna atau config menentukan provider + yang menang +- ambiguitas yang tersisa diabaikan sampai pengguna atau konfigurasi menentukan penyedia Field: -| Field | Tipe | Artinya | -| --------------- | ---------- | ------------------------------------------------------------------------------ | -| `modelPrefixes` | `string[]` | Prefix yang dicocokkan dengan `startsWith` terhadap ID model shorthand. | -| `modelPatterns` | `string[]` | Sumber regex yang dicocokkan terhadap ID model shorthand setelah penghapusan suffix profil. | +| Field | Tipe | Artinya | +| --------------- | ---------- | ------------------------------------------------------------------------------- | +| `modelPrefixes` | `string[]` | Prefiks yang dicocokkan dengan `startsWith` terhadap id model shorthand. | +| `modelPatterns` | `string[]` | Sumber regex yang dicocokkan terhadap id model shorthand setelah penghapusan sufiks profil. | -Kunci kapabilitas tingkat atas lama sudah deprecated. Gunakan `openclaw doctor --fix` untuk +Key kapabilitas level teratas lama sudah deprecated. Gunakan `openclaw doctor --fix` untuk memindahkan `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, dan `webSearchProviders` ke bawah `contracts`; pemuatan -manifest normal აღარ memperlakukan field tingkat atas tersebut sebagai +manifes normal tidak lagi memperlakukan field level teratas tersebut sebagai kepemilikan kapabilitas. -## Manifest versus package.json +## Manifes versus package.json Kedua file ini memiliki fungsi yang berbeda: -| File | Gunakan untuk | -| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Discovery, validasi config, metadata pilihan auth, dan petunjuk UI yang harus ada sebelum kode plugin berjalan | -| `package.json` | Metadata npm, instalasi dependensi, dan blok `openclaw` yang digunakan untuk entrypoint, gating instalasi, penyiapan, atau metadata katalog | +| File | Gunakan untuk | +| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.plugin.json` | Discovery, validasi konfigurasi, metadata pilihan auth, dan petunjuk UI yang harus ada sebelum kode plugin berjalan | +| `package.json` | Metadata npm, instalasi dependensi, dan blok `openclaw` yang digunakan untuk entrypoint, gating instalasi, setup, atau metadata katalog | -Jika Anda tidak yakin metadata tertentu harus ditempatkan di mana, gunakan aturan ini: +Jika Anda tidak yakin metadata tertentu harus diletakkan di mana, gunakan aturan ini: - jika OpenClaw harus mengetahuinya sebelum memuat kode plugin, letakkan di `openclaw.plugin.json` - jika itu terkait packaging, file entry, atau perilaku instalasi npm, letakkan di `package.json` @@ -348,30 +352,32 @@ Beberapa metadata plugin pra-runtime memang sengaja ditempatkan di `package.json Contoh penting: -| Field | Artinya | -| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.extensions` | Mendeklarasikan entrypoint plugin native. | -| `openclaw.setupEntry` | Entrypoint ringan khusus penyiapan yang digunakan saat onboarding dan startup channel yang ditangguhkan. | -| `openclaw.channel` | Metadata katalog channel ringan seperti label, path docs, alias, dan copy pemilihan. | -| `openclaw.channel.configuredState` | Metadata pemeriksa configured-state ringan yang dapat menjawab "apakah penyiapan env-only sudah ada?" tanpa memuat runtime channel penuh. | -| `openclaw.channel.persistedAuthState` | Metadata pemeriksa persisted-auth ringan yang dapat menjawab "apakah ada sesuatu yang sudah login?" tanpa memuat runtime channel penuh. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Petunjuk instalasi/pembaruan untuk plugin bawaan dan plugin yang dipublikasikan secara eksternal. | -| `openclaw.install.defaultChoice` | Jalur instalasi yang dipilih saat tersedia beberapa sumber instalasi. | -| `openclaw.install.minHostVersion` | Versi host OpenClaw minimum yang didukung, menggunakan batas bawah semver seperti `>=2026.3.22`. | -| `openclaw.install.allowInvalidConfigRecovery` | Mengizinkan jalur pemulihan reinstal plugin bawaan yang sempit saat config tidak valid. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Memungkinkan permukaan channel khusus penyiapan dimuat sebelum plugin channel penuh saat startup. | +| Field | Artinya | +| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.extensions` | Mendeklarasikan entrypoint plugin native. | +| `openclaw.setupEntry` | Entrypoint ringan khusus setup yang digunakan saat onboarding dan startup channel tertunda. | +| `openclaw.channel` | Metadata katalog channel ringan seperti label, path dokumen, alias, dan copy pemilihan. | +| `openclaw.channel.configuredState` | Metadata pemeriksa status terkonfigurasi ringan yang dapat menjawab "apakah setup khusus-env sudah ada?" tanpa memuat runtime channel penuh. | +| `openclaw.channel.persistedAuthState` | Metadata pemeriksa auth tersimpan ringan yang dapat menjawab "apakah sudah ada yang login?" tanpa memuat runtime channel penuh. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Petunjuk instalasi/pembaruan untuk plugin bawaan dan plugin yang dipublikasikan secara eksternal. | +| `openclaw.install.defaultChoice` | Jalur instalasi yang dipilih saat beberapa sumber instalasi tersedia. | +| `openclaw.install.minHostVersion` | Versi host OpenClaw minimum yang didukung, menggunakan floor semver seperti `>=2026.3.22`. | +| `openclaw.install.allowInvalidConfigRecovery` | Mengizinkan jalur pemulihan reinstalasi plugin bawaan yang sempit saat konfigurasi tidak valid. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Mengizinkan surface channel khusus setup dimuat sebelum plugin channel penuh saat startup. | -`openclaw.install.minHostVersion` ditegakkan selama instalasi dan pemuatan registry -manifest. Nilai yang tidak valid ditolak; nilai yang valid tetapi lebih baru akan melewati +`openclaw.install.minHostVersion` ditegakkan selama instalasi dan pemuatan registri +manifes. Nilai yang tidak valid ditolak; nilai yang valid tetapi lebih baru akan melewati plugin pada host yang lebih lama. `openclaw.install.allowInvalidConfigRecovery` sengaja dibuat sempit. Ini -tidak membuat config rusak arbitrer menjadi dapat diinstal. Saat ini fitur ini hanya mengizinkan alur instalasi -memulihkan kegagalan peningkatan plugin bawaan usang tertentu, seperti path plugin bawaan yang hilang atau entri `channels.` usang untuk plugin bawaan yang sama tersebut. -Error config yang tidak terkait tetap memblokir instalasi dan mengarahkan operator +tidak membuat konfigurasi rusak sembarang menjadi dapat diinstal. Saat ini ini hanya memungkinkan alur instalasi +memulihkan kegagalan upgrade plugin bawaan lama yang spesifik, seperti +path plugin bawaan yang hilang atau entri `channels.` lama untuk plugin bawaan yang sama. +Error konfigurasi yang tidak terkait tetap memblokir instalasi dan mengarahkan operator ke `openclaw doctor --fix`. -`openclaw.channel.persistedAuthState` adalah metadata package untuk modul pemeriksa kecil: +`openclaw.channel.persistedAuthState` adalah metadata package untuk modul pemeriksa +kecil: ```json { @@ -387,13 +393,12 @@ ke `openclaw doctor --fix`. } ``` -Gunakan saat alur penyiapan, doctor, atau configured-state memerlukan probe auth ya/tidak yang ringan +Gunakan ini saat alur setup, doctor, atau configured-state memerlukan probe auth ya/tidak yang ringan sebelum plugin channel penuh dimuat. Export target harus berupa fungsi kecil -yang hanya membaca persisted state; jangan merutekannya melalui barrel runtime -channel penuh. +yang hanya membaca state tersimpan; jangan arahkan melalui barrel runtime channel penuh. -`openclaw.channel.configuredState` mengikuti bentuk yang sama untuk pemeriksaan configured -berbasis env yang ringan: +`openclaw.channel.configuredState` mengikuti bentuk yang sama untuk pemeriksaan terkonfigurasi +khusus-env yang ringan: ```json { @@ -409,61 +414,64 @@ berbasis env yang ringan: } ``` -Gunakan saat channel dapat menjawab configured-state dari env atau input kecil non-runtime -lainnya. Jika pemeriksaan memerlukan resolusi config penuh atau runtime channel -yang sebenarnya, simpan logika tersebut di hook plugin `config.hasConfiguredState`. +Gunakan ini saat sebuah channel dapat menjawab configured-state dari env atau input +non-runtime kecil lainnya. Jika pemeriksaannya memerlukan resolusi konfigurasi penuh atau runtime +channel yang sesungguhnya, simpan logika itu di hook plugin `config.hasConfiguredState`. ## Persyaratan JSON Schema -- **Setiap plugin harus menyertakan JSON Schema**, meskipun tidak menerima config apa pun. +- **Setiap plugin harus menyertakan JSON Schema**, bahkan jika tidak menerima konfigurasi. - Skema kosong dapat diterima (misalnya, `{ "type": "object", "additionalProperties": false }`). -- Skema divalidasi pada waktu baca/tulis config, bukan saat runtime. +- Skema divalidasi saat pembacaan/penulisan konfigurasi, bukan saat runtime. ## Perilaku validasi -- Kunci `channels.*` yang tidak dikenal adalah **error**, kecuali ID channel tersebut dideklarasikan oleh - manifest plugin. +- Key `channels.*` yang tidak dikenal adalah **error**, kecuali id channel tersebut dideklarasikan oleh + manifes plugin. - `plugins.entries.`, `plugins.allow`, `plugins.deny`, dan `plugins.slots.*` - harus mereferensikan ID plugin yang **dapat ditemukan**. ID yang tidak dikenal adalah **error**. -- Jika plugin terinstal tetapi memiliki manifest atau skema yang rusak atau hilang, - validasi gagal dan Doctor melaporkan error plugin. -- Jika config plugin ada tetapi plugin **dinonaktifkan**, config tetap dipertahankan dan + harus mereferensikan id plugin yang **dapat ditemukan**. Id yang tidak dikenal adalah **error**. +- Jika plugin terinstal tetapi memiliki manifes atau skema yang rusak atau hilang, + validasi gagal dan Doctor melaporkan error plugin tersebut. +- Jika konfigurasi plugin ada tetapi plugin tersebut **nonaktif**, konfigurasi tetap dipertahankan dan **peringatan** ditampilkan di Doctor + log. Lihat [Referensi konfigurasi](/id/gateway/configuration) untuk skema `plugins.*` lengkap. ## Catatan -- Manifest ini **wajib untuk plugin OpenClaw native**, termasuk pemuatan dari filesystem lokal. -- Runtime tetap memuat modul plugin secara terpisah; manifest hanya untuk +- Manifes ini **wajib untuk plugin OpenClaw native**, termasuk pemuatan filesystem lokal. +- Runtime tetap memuat modul plugin secara terpisah; manifes hanya untuk discovery + validasi. -- Manifest native diparse dengan JSON5, sehingga komentar, trailing comma, dan - kunci tanpa tanda kutip diterima selama nilai akhirnya tetap berupa object. -- Hanya field manifest yang terdokumentasi yang dibaca oleh manifest loader. Hindari menambahkan - kunci tingkat atas kustom di sini. +- Manifes native diurai dengan JSON5, jadi komentar, koma penutup, dan + key tanpa tanda kutip diterima selama nilai akhirnya tetap berupa objek. +- Hanya field manifes yang terdokumentasi yang dibaca oleh pemuat manifes. Hindari menambahkan + key level teratas kustom di sini. - `providerAuthEnvVars` adalah jalur metadata ringan untuk probe auth, validasi - penanda env, dan permukaan auth provider serupa yang tidak seharusnya menjalankan runtime - plugin hanya untuk memeriksa nama env. -- `channelEnvVars` adalah jalur metadata ringan untuk fallback shell-env, prompt penyiapan, - dan permukaan channel serupa yang tidak seharusnya menjalankan runtime plugin + penanda env, dan surface auth penyedia serupa yang tidak seharusnya mem-boot runtime plugin + hanya untuk memeriksa nama env. +- `providerAuthAliases` memungkinkan varian penyedia menggunakan ulang auth + env vars, profil auth, auth berbasis konfigurasi, dan pilihan onboarding kunci API + dari penyedia lain tanpa melakukan hardcode hubungan tersebut di core. +- `channelEnvVars` adalah jalur metadata ringan untuk fallback shell-env, prompt setup, + dan surface channel serupa yang tidak seharusnya mem-boot runtime plugin hanya untuk memeriksa nama env. - `providerAuthChoices` adalah jalur metadata ringan untuk picker pilihan auth, - resolusi `--auth-choice`, pemetaan provider pilihan, dan pendaftaran flag CLI onboarding - sederhana sebelum runtime provider dimuat. Untuk metadata wizard runtime - yang memerlukan kode provider, lihat - [Provider runtime hooks](/id/plugins/architecture#provider-runtime-hooks). + resolusi `--auth-choice`, pemetaan preferred-provider, dan pendaftaran flag CLI + onboarding sederhana sebelum runtime penyedia dimuat. Untuk metadata wizard runtime + yang memerlukan kode penyedia, lihat + [Hook runtime penyedia](/id/plugins/architecture#provider-runtime-hooks). - Jenis plugin eksklusif dipilih melalui `plugins.slots.*`. - `kind: "memory"` dipilih oleh `plugins.slots.memory`. - `kind: "context-engine"` dipilih oleh `plugins.slots.contextEngine` (default: `legacy` bawaan). - `channels`, `providers`, `cliBackends`, dan `skills` dapat dihilangkan saat - plugin tidak memerlukannya. + plugin tidak membutuhkannya. - Jika plugin Anda bergantung pada modul native, dokumentasikan langkah build dan - persyaratan allowlist package-manager apa pun (misalnya, pnpm `allow-build-scripts` + persyaratan allowlist package manager apa pun (misalnya, pnpm `allow-build-scripts` - `pnpm rebuild `). ## Terkait -- [Building Plugins](/id/plugins/building-plugins) — memulai dengan plugin -- [Plugin Architecture](/id/plugins/architecture) — arsitektur internal -- [SDK Overview](/id/plugins/sdk-overview) — referensi Plugin SDK +- [Membangun Plugin](/id/plugins/building-plugins) — memulai dengan plugin +- [Arsitektur Plugin](/id/plugins/architecture) — arsitektur internal +- [Ikhtisar SDK](/id/plugins/sdk-overview) — referensi Plugin SDK diff --git a/docs/id/plugins/sdk-migration.md b/docs/id/plugins/sdk-migration.md index 8c95d7d66..3d633a7b7 100644 --- a/docs/id/plugins/sdk-migration.md +++ b/docs/id/plugins/sdk-migration.md @@ -5,62 +5,62 @@ 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-08T09:13:47Z" + generated_at: "2026-04-09T01:29:13Z" model: gpt-5.4 provider: openai - source_hash: d9a2ce7f5553563516a549ca87e776a6a71e8dd8533a773c5ddbecfae43e7b77 + source_hash: 60cbb6c8be30d17770887d490c14e3a4538563339a5206fb419e51e0558bbc07 source_path: plugins/sdk-migration.md workflow: 15 --- # Migrasi Plugin SDK -OpenClaw telah beralih dari lapisan kompatibilitas mundur yang luas ke arsitektur -plugin modern dengan impor yang terfokus dan terdokumentasi. Jika plugin Anda -dibangun sebelum arsitektur baru ini, panduan ini membantu Anda bermigrasi. +OpenClaw telah beralih dari lapisan kompatibilitas mundur yang luas ke arsitektur plugin +modern dengan impor yang terfokus dan terdokumentasi. Jika plugin Anda dibuat sebelum +arsitektur baru, panduan ini membantu Anda bermigrasi. ## Apa yang berubah -Sistem plugin lama menyediakan dua surface yang sangat terbuka yang memungkinkan -plugin mengimpor apa pun yang mereka perlukan dari satu titik masuk: +Sistem plugin lama menyediakan dua permukaan yang sangat terbuka yang memungkinkan plugin mengimpor +apa pun yang mereka butuhkan dari satu titik masuk: - **`openclaw/plugin-sdk/compat`** — satu impor yang mengekspor ulang puluhan - helper. Ini diperkenalkan untuk menjaga plugin berbasis hook lama tetap - berfungsi saat arsitektur plugin baru sedang dibangun. -- **`openclaw/extension-api`** — sebuah jembatan yang memberi plugin akses - langsung ke helper sisi host seperti embedded agent runner. + helper. Ini diperkenalkan untuk menjaga plugin berbasis hook yang lebih lama tetap berfungsi saat + arsitektur plugin baru sedang dibangun. +- **`openclaw/extension-api`** — sebuah jembatan yang memberi plugin akses langsung ke + helper sisi host seperti runner agen tersemat. -Kedua surface sekarang **deprecated**. Keduanya masih berfungsi saat runtime, -tetapi plugin baru tidak boleh menggunakannya, dan plugin yang sudah ada harus -bermigrasi sebelum rilis mayor berikutnya menghapusnya. +Kedua permukaan kini **deprecated**. Keduanya masih berfungsi saat runtime, tetapi plugin +baru tidak boleh menggunakannya, dan plugin yang ada harus bermigrasi sebelum rilis mayor +berikutnya menghapusnya. Lapisan kompatibilitas mundur akan dihapus pada rilis mayor mendatang. - Plugin yang masih mengimpor dari surface ini akan rusak ketika itu terjadi. + Plugin yang masih mengimpor dari permukaan ini akan rusak ketika 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 terbentuknya siklus impor -- **Surface API yang tidak jelas** — tidak ada cara untuk mengetahui ekspor mana yang stabil vs internal +- **Dependensi sirkular** — ekspor ulang yang luas memudahkan pembuatan siklus impor +- **Permukaan API tidak jelas** — tidak ada cara untuk mengetahui ekspor mana yang stabil vs internal Plugin SDK modern memperbaikinya: setiap path impor (`openclaw/plugin-sdk/\`) adalah modul kecil yang mandiri dengan tujuan yang jelas dan kontrak yang terdokumentasi. -Seam kenyamanan provider lama untuk channel bawaan juga sudah dihapus. Impor +Seam kemudahan provider lama untuk kanal bawaan juga sudah tidak ada. Impor seperti `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, -seam helper berlabel channel, dan +seam helper bermerek kanal, 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 milik 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` plugin tersebut. Contoh provider bawaan saat ini: @@ -74,9 +74,9 @@ Contoh provider bawaan saat ini: ## Cara bermigrasi - - Plugin channel yang mendukung approval sekarang mengekspos perilaku approval native melalui - `approvalCapability.nativeRuntime` ditambah registry runtime-context bersama. + + Plugin kanal yang mendukung approval sekarang mengekspos perilaku approval native melalui + `approvalCapability.nativeRuntime` ditambah registry konteks runtime bersama. Perubahan utama: @@ -84,25 +84,25 @@ Contoh provider bawaan saat ini: `approvalCapability.nativeRuntime` - Pindahkan auth/pengiriman khusus approval dari wiring lama `plugin.auth` / `plugin.approvals` ke `approvalCapability` - - `ChannelPlugin.approvals` telah dihapus dari kontrak publik - plugin channel; pindahkan field delivery/native/render ke `approvalCapability` - - `plugin.auth` tetap dipakai hanya untuk alur login/logout channel; hook auth - approval di sana tidak lagi dibaca oleh core - - Daftarkan objek runtime milik channel seperti client, token, atau aplikasi - Bolt melalui `openclaw/plugin-sdk/channel-runtime-context` - - Jangan kirim pemberitahuan reroute milik plugin dari handler approval native; - core sekarang menangani pemberitahuan dialihkan-ke-tempat-lain dari hasil pengiriman yang sebenarnya + - `ChannelPlugin.approvals` telah dihapus dari kontrak publik channel-plugin; + pindahkan field delivery/native/render ke `approvalCapability` + - `plugin.auth` tetap ada hanya untuk alur login/logout kanal; hook auth approval + di sana tidak lagi dibaca oleh core + - Daftarkan objek runtime milik kanal seperti klien, token, atau aplikasi Bolt + melalui `openclaw/plugin-sdk/channel-runtime-context` + - Jangan kirim pemberitahuan pengalihan milik plugin dari handler approval native; + core kini menangani pemberitahuan dialihkan-ke-tempat-lain dari hasil pengiriman aktual - Saat meneruskan `channelRuntime` ke `createChannelManager(...)`, sediakan - surface `createPluginRuntime().channel` yang nyata. Stub parsial akan ditolak. + permukaan `createPluginRuntime().channel` yang nyata. Stub parsial ditolak. - Lihat `/plugins/sdk-channel-plugins` untuk tata letak capability - approval saat ini. + Lihat `/plugins/sdk-channel-plugins` untuk + tata letak capability approval saat ini. - Jika plugin Anda menggunakan `openclaw/plugin-sdk/windows-spawn`, wrapper - Windows `.cmd`/`.bat` yang tidak terpecahkan sekarang gagal tertutup kecuali Anda secara eksplisit meneruskan + Jika plugin Anda menggunakan `openclaw/plugin-sdk/windows-spawn`, wrapper Windows + `.cmd`/`.bat` yang tidak terselesaikan sekarang gagal secara tertutup kecuali Anda secara eksplisit meneruskan `allowShellFallback: true`. ```typescript @@ -112,19 +112,19 @@ Contoh provider bawaan saat ini: // Sesudah const program = applyWindowsSpawnProgramPolicy({ candidate, - // Hanya setel ini untuk pemanggil kompatibilitas tepercaya yang secara sengaja - // menerima fallback yang dimediasi shell. + // Hanya setel ini untuk pemanggil kompatibilitas tepercaya yang memang + // menerima fallback melalui shell. allowShellFallback: true, }); ``` - Jika pemanggil Anda tidak secara sengaja bergantung pada shell fallback, jangan setel + Jika pemanggil Anda tidak secara sengaja bergantung pada fallback shell, jangan setel `allowShellFallback` dan tangani error yang dilempar sebagai gantinya. - - Cari plugin Anda untuk impor dari salah satu surface deprecated: + + Cari di plugin Anda impor dari salah satu permukaan deprecated: ```bash grep -r "plugin-sdk/compat" my-plugin/ @@ -134,7 +134,7 @@ Contoh provider bawaan saat ini: - Setiap ekspor dari surface lama dipetakan ke path impor modern tertentu: + Setiap ekspor dari permukaan lama dipetakan ke path impor modern tertentu: ```typescript // Sebelum (lapisan kompatibilitas mundur deprecated) @@ -150,7 +150,7 @@ Contoh provider bawaan saat ini: import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth"; ``` - Untuk helper sisi host, gunakan runtime plugin yang diinjeksi alih-alih mengimpor + Untuk helper sisi host, gunakan runtime plugin yang disuntikkan alih-alih mengimpor secara langsung: ```typescript @@ -158,7 +158,7 @@ Contoh provider bawaan saat ini: import { runEmbeddedPiAgent } from "openclaw/extension-api"; const result = await runEmbeddedPiAgent({ sessionId, prompt }); - // Sesudah (runtime yang diinjeksi) + // Sesudah (runtime yang disuntikkan) const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt }); ``` @@ -190,179 +190,180 @@ Contoh provider bawaan saat ini: | Path impor | Tujuan | Ekspor utama | | --- | --- | --- | | `plugin-sdk/plugin-entry` | Helper entri plugin kanonis | `definePluginEntry` | - | `plugin-sdk/core` | Ekspor ulang payung lama untuk definisi/builder entri channel | `defineChannelPluginEntry`, `createChatChannelPlugin` | - | `plugin-sdk/config-schema` | Ekspor skema config root | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | Helper entri single-provider | `defineSingleProviderPluginEntry` | - | `plugin-sdk/channel-core` | Definisi dan builder entri channel yang terfokus | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | + | `plugin-sdk/core` | Ekspor ulang payung lama untuk definisi/builder entri kanal | `defineChannelPluginEntry`, `createChatChannelPlugin` | + | `plugin-sdk/config-schema` | Ekspor schema config root | `OpenClawSchema` | + | `plugin-sdk/provider-entry` | Helper entri provider tunggal | `defineSingleProviderPluginEntry` | + | `plugin-sdk/channel-core` | Definisi dan builder entri kanal yang terfokus | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | | `plugin-sdk/setup` | Helper wizard setup bersama | Prompt allowlist, builder status setup | - | `plugin-sdk/setup-runtime` | Helper runtime saat setup | Adapter patch setup yang aman untuk impor, helper catatan lookup, `promptResolvedAllowFrom`, `splitSetupEntries`, proxy setup terdelegasi | + | `plugin-sdk/setup-runtime` | Helper runtime saat setup | Adapter patch setup yang aman untuk impor, helper catatan pencarian, `promptResolvedAllowFrom`, `splitSetupEntries`, proxy setup yang didelegasikan | | `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-account | Helper daftar/config/action-gate akun | + | `plugin-sdk/account-core` | Helper multi-akun | Helper daftar/config/gerbang-tindakan akun | | `plugin-sdk/account-id` | Helper account-id | `DEFAULT_ACCOUNT_ID`, normalisasi account-id | - | `plugin-sdk/account-resolution` | Helper lookup akun | Helper lookup akun + fallback default | - | `plugin-sdk/account-helpers` | Helper akun yang sempit | Helper daftar akun/action akun | + | `plugin-sdk/account-resolution` | Helper pencarian akun | Helper pencarian akun + fallback default | + | `plugin-sdk/account-helpers` | Helper akun yang sempit | Helper daftar akun/tindakan 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 + pengetikan | `createChannelReplyPipeline` | - | `plugin-sdk/channel-config-helpers` | Factory adapter config | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Builder skema config | Tipe skema config channel | - | `plugin-sdk/telegram-command-config` | Helper config perintah Telegram | Normalisasi nama perintah, pemangkasan deskripsi, validasi duplikasi/konflik | + | `plugin-sdk/channel-config-helpers` | Pabrik adapter config | `createHybridChannelConfigAdapter` | + | `plugin-sdk/channel-config-schema` | Builder schema config | Tipe schema config kanal | + | `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 inbound | Helper route bersama + builder envelope | - | `plugin-sdk/inbound-reply-dispatch` | Helper balasan inbound | Helper record-and-dispatch bersama | + | `plugin-sdk/inbound-envelope` | Helper envelope masuk | Helper route bersama + builder envelope | + | `plugin-sdk/inbound-reply-dispatch` | Helper balasan masuk | Helper rekam-dan-dispatch bersama | | `plugin-sdk/messaging-targets` | Parsing target pesan | Helper parsing/pencocokan target | - | `plugin-sdk/outbound-media` | Helper media outbound | Pemuatan media outbound bersama | - | `plugin-sdk/outbound-runtime` | Helper runtime outbound | Helper identitas/delegasi pengiriman outbound | - | `plugin-sdk/thread-bindings-runtime` | Helper thread-binding | Lifecycle thread-binding dan helper adapter | - | `plugin-sdk/agent-media-payload` | Helper payload media lama | Builder payload media agent untuk tata letak field lama | - | `plugin-sdk/channel-runtime` | Shim kompatibilitas deprecated | Hanya utilitas runtime channel lama | + | `plugin-sdk/outbound-media` | Helper media keluar | Pemuatan media keluar bersama | + | `plugin-sdk/outbound-runtime` | Helper runtime keluar | Helper identitas keluar/delegasi kirim | + | `plugin-sdk/thread-bindings-runtime` | Helper thread-binding | Siklus hidup thread-binding dan helper adapter | + | `plugin-sdk/agent-media-payload` | Helper payload media lama | Builder payload media agen untuk tata letak field lama | + | `plugin-sdk/channel-runtime` | Shim kompatibilitas deprecated | Hanya utilitas runtime kanal lama | | `plugin-sdk/channel-send-result` | Tipe hasil kirim | Tipe hasil balasan | | `plugin-sdk/runtime-store` | Penyimpanan plugin persisten | `createPluginRuntimeStore` | | `plugin-sdk/runtime` | Helper runtime yang luas | Helper runtime/logging/backup/instalasi plugin | - | `plugin-sdk/runtime-env` | Helper env runtime yang sempit | Helper logger/runtime env, timeout, retry, dan backoff | - | `plugin-sdk/plugin-runtime` | Helper runtime plugin bersama | Helper perintah/hook/http/interaktif plugin | - | `plugin-sdk/hook-runtime` | Helper pipeline hook | Helper pipeline webhook/internal hook bersama | + | `plugin-sdk/runtime-env` | Helper env runtime yang sempit | Logger/env runtime, 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/hook internal bersama | | `plugin-sdk/lazy-runtime` | Helper runtime lazy | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | | `plugin-sdk/process-runtime` | Helper proses | Helper exec bersama | - | `plugin-sdk/cli-runtime` | Helper runtime CLI | Pemformatan perintah, wait, helper versi | - | `plugin-sdk/gateway-runtime` | Helper gateway | Helper client gateway dan patch status channel | - | `plugin-sdk/config-runtime` | Helper config | Helper load/write config | - | `plugin-sdk/telegram-command-config` | Helper perintah Telegram | Helper validasi perintah Telegram yang stabil-fallback ketika surface kontrak Telegram bawaan tidak tersedia | + | `plugin-sdk/cli-runtime` | Helper runtime CLI | Pemformatan perintah, waits, helper versi | + | `plugin-sdk/gateway-runtime` | Helper gateway | Helper klien gateway dan patch status kanal | + | `plugin-sdk/config-runtime` | Helper config | Helper muat/tulis config | + | `plugin-sdk/telegram-command-config` | Helper perintah Telegram | Helper validasi perintah Telegram stabil-fallback saat permukaan kontrak Telegram bawaan tidak tersedia | | `plugin-sdk/approval-runtime` | Helper prompt approval | Payload approval exec/plugin, helper capability/profile approval, helper routing/runtime approval native | - | `plugin-sdk/approval-auth-runtime` | Helper auth approval | Resolusi approver, auth aksi same-chat | - | `plugin-sdk/approval-client-runtime` | Helper client approval | Helper profile/filter approval exec native | + | `plugin-sdk/approval-auth-runtime` | Helper auth approval | Resolusi approver, auth tindakan chat yang sama | + | `plugin-sdk/approval-client-runtime` | Helper klien approval | Helper profile/filter approval exec native | | `plugin-sdk/approval-delivery-runtime` | Helper pengiriman approval | Adapter capability/pengiriman approval native | - | `plugin-sdk/approval-gateway-runtime` | Helper gateway approval | Helper resolusi-gateway approval bersama | - | `plugin-sdk/approval-handler-adapter-runtime` | Helper adapter approval | Helper pemuatan adapter approval native yang ringan untuk entrypoint channel yang panas | - | `plugin-sdk/approval-handler-runtime` | Helper handler approval | Helper runtime handler approval yang lebih luas; prioritaskan seam adapter/gateway yang lebih sempit bila itu sudah cukup | + | `plugin-sdk/approval-gateway-runtime` | Helper gateway approval | Helper bersama resolusi gateway approval | + | `plugin-sdk/approval-handler-adapter-runtime` | Helper adapter approval | Helper pemuatan adapter approval native yang ringan untuk entrypoint kanal hot | + | `plugin-sdk/approval-handler-runtime` | Helper handler approval | Helper runtime handler approval yang lebih luas; utamakan seam adapter/gateway yang lebih sempit jika itu sudah cukup | | `plugin-sdk/approval-native-runtime` | Helper target approval | Helper binding target/akun approval native | | `plugin-sdk/approval-reply-runtime` | Helper balasan approval | Helper payload balasan approval exec/plugin | - | `plugin-sdk/channel-runtime-context` | Helper runtime-context channel | Helper register/get/watch runtime-context channel generik | - | `plugin-sdk/security-runtime` | Helper keamanan | Helper trust, gating DM, konten eksternal, dan pengumpulan secret bersama | + | `plugin-sdk/channel-runtime-context` | Helper konteks runtime kanal | Helper generik register/get/watch konteks runtime kanal | + | `plugin-sdk/security-runtime` | Helper keamanan | Helper trust, DM gating, konten eksternal, dan pengumpulan secret bersama | | `plugin-sdk/ssrf-policy` | Helper kebijakan SSRF | Helper allowlist host dan kebijakan jaringan privat | - | `plugin-sdk/ssrf-runtime` | Helper runtime SSRF | Helper pinned-dispatcher, guarded fetch, kebijakan SSRF | + | `plugin-sdk/ssrf-runtime` | Helper runtime SSRF | Dispatcher tersemat, fetch terlindungi, 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 wrapped fetch/proxy | `resolveFetch`, helper proxy | + | `plugin-sdk/fetch-runtime` | Helper fetch/proxy terbungkus | `resolveFetch`, helper proxy | | `plugin-sdk/host-runtime` | Helper normalisasi host | `normalizeHostname`, `normalizeScpRemoteHost` | - | `plugin-sdk/retry-runtime` | Helper retry | `RetryConfig`, `retryAsync`, runner kebijakan | + | `plugin-sdk/retry-runtime` | Helper retry | `RetryConfig`, `retryAsync`, pelaksana kebijakan | | `plugin-sdk/allow-from` | Pemformatan allowlist | `formatAllowFromLowercase` | | `plugin-sdk/allowlist-resolution` | Pemetaan input allowlist | `mapAllowlistResolutionInputs` | - | `plugin-sdk/command-auth` | Gating perintah dan helper surface perintah | `resolveControlCommandGate`, helper otorisasi pengirim, helper registry perintah | + | `plugin-sdk/command-auth` | Gating perintah dan helper permukaan perintah | `resolveControlCommandGate`, helper otorisasi pengirim, helper registry perintah | + | `plugin-sdk/command-status` | Perender status/bantuan perintah | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | | `plugin-sdk/secret-input` | Parsing input secret | Helper input secret | - | `plugin-sdk/webhook-ingress` | Helper request webhook | Utilitas target webhook | - | `plugin-sdk/webhook-request-guards` | Helper guard body webhook | Helper baca/batas body request | - | `plugin-sdk/reply-runtime` | Runtime balasan bersama | Dispatch inbound, heartbeat, planner balasan, chunking | - | `plugin-sdk/reply-dispatch-runtime` | Helper dispatch balasan yang sempit | Helper finalisasi + dispatch provider | + | `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 yang sempit | Helper finalize + dispatch provider | | `plugin-sdk/reply-history` | Helper riwayat balasan | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | Perencanaan referensi balasan | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Helper potongan balasan | Helper chunking teks/markdown | + | `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/state-paths` | Helper path state | Helper direktori state dan OAuth | + | `plugin-sdk/state-paths` | Helper path status | Helper direktori state dan OAuth | | `plugin-sdk/routing` | Helper routing/session-key | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, helper normalisasi session-key | - | `plugin-sdk/status-helpers` | Helper status channel | Builder ringkasan status channel/akun, default runtime-state, helper metadata issue | - | `plugin-sdk/target-resolver-runtime` | Helper target resolver | Helper target resolver bersama | + | `plugin-sdk/status-helpers` | Helper status kanal | Builder ringkasan status kanal/akun, default status runtime, helper metadata isu | + | `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 request | Mengekstrak URL string dari input mirip request | - | `plugin-sdk/run-command` | Helper perintah bertempo | Runner perintah bertempo dengan stdout/stderr ternormalisasi | + | `plugin-sdk/request-url` | Helper URL permintaan | Ekstrak URL string dari input mirip request | + | `plugin-sdk/run-command` | Helper perintah terwaktu | Runner perintah terwaktu dengan stdout/stderr ternormalisasi | | `plugin-sdk/param-readers` | Pembaca parameter | Pembaca parameter tool/CLI umum | - | `plugin-sdk/tool-payload` | Ekstraksi payload tool | Mengekstrak payload ternormalisasi dari objek hasil tool | - | `plugin-sdk/tool-send` | Ekstraksi pengiriman tool | Mengekstrak field target kirim kanonis dari argumen tool | - | `plugin-sdk/temp-path` | Helper path temp | Helper path unduhan sementara bersama | - | `plugin-sdk/logging-core` | Helper logging | Helper logger subsistem dan redaksi | - | `plugin-sdk/markdown-table-runtime` | Helper tabel markdown | Helper mode tabel markdown | + | `plugin-sdk/tool-payload` | Ekstraksi payload tool | Ekstrak payload ternormalisasi dari objek hasil tool | + | `plugin-sdk/tool-send` | Ekstraksi pengiriman tool | Ekstrak field target kirim 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 markdown-table | Helper mode tabel markdown | | `plugin-sdk/reply-payload` | Tipe balasan pesan | Tipe payload balasan | - | `plugin-sdk/provider-setup` | Helper setup provider lokal/self-hosted yang terkurasi | Helper penemuan/config provider self-hosted | + | `plugin-sdk/provider-setup` | Helper setup provider lokal/self-hosted terkurasi | Helper penemuan/config provider self-hosted | | `plugin-sdk/self-hosted-provider-setup` | Helper setup provider self-hosted kompatibel OpenAI yang 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 setup API key provider | Helper onboarding/profile-write API key | - | `plugin-sdk/provider-auth-result` | Helper hasil auth provider | Builder standar hasil auth OAuth | + | `plugin-sdk/provider-auth-api-key` | Helper setup API key provider | Helper onboarding/tulis profil API key | + | `plugin-sdk/provider-auth-result` | Helper hasil auth provider | Builder hasil auth OAuth standar | | `plugin-sdk/provider-auth-login` | Helper login interaktif provider | Helper login interaktif bersama | - | `plugin-sdk/provider-env-vars` | Helper env var provider | Helper lookup env var auth provider | + | `plugin-sdk/provider-env-vars` | Helper env var provider | Helper pencarian env var 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-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 kemampuan HTTP/endpoint provider generik | + | `plugin-sdk/provider-http` | Helper HTTP provider | Helper generik kemampuan HTTP/endpoint provider | | `plugin-sdk/provider-web-fetch` | Helper web-fetch provider | Helper registrasi/cache provider web-fetch | - | `plugin-sdk/provider-web-search-config-contract` | Helper config web-search provider | Helper config/kredensial web-search yang sempit untuk provider yang tidak memerlukan wiring enable plugin | - | `plugin-sdk/provider-web-search-contract` | Helper kontrak web-search provider | Helper kontrak config/kredensial web-search yang sempit seperti `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`, dan setter/getter kredensial terlingkup | + | `plugin-sdk/provider-web-search-config-contract` | Helper config web-search provider | Helper config/kredensial web-search sempit untuk provider yang tidak memerlukan wiring enable plugin | + | `plugin-sdk/provider-web-search-contract` | Helper kontrak web-search provider | Helper kontrak config/kredensial web-search sempit seperti `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`, dan setter/getter kredensial berskala | | `plugin-sdk/provider-web-search` | Helper web-search provider | Helper registrasi/cache/runtime provider web-search | - | `plugin-sdk/provider-tools` | Helper kompatibilitas tool/skema provider | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, pembersihan skema Gemini + diagnostik, dan helper kompatibilitas xAI seperti `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-tools` | Helper kompat schema/tool provider | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, pembersihan schema 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 pembungkus stream provider | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipe pembungkus stream, dan helper pembungkus bersama Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/keyed-async-queue` | Queue async terurut | `KeyedAsyncQueue` | + | `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/media-runtime` | Helper media bersama | Helper fetch/transform/store media plus builder payload media | - | `plugin-sdk/media-generation-runtime` | Helper pembuatan media bersama | Helper failover bersama, pemilihan kandidat, dan pesan model hilang untuk pembuatan gambar/video/musik | - | `plugin-sdk/media-understanding` | Helper pemahaman media | Tipe provider pemahaman media plus ekspor helper gambar/audio untuk provider | - | `plugin-sdk/text-runtime` | Helper teks bersama | Penghapusan teks yang terlihat oleh asisten, helper render/chunking/table markdown, helper redaksi, helper tag direktif, utilitas safe-text, dan helper teks/logging terkait | - | `plugin-sdk/text-chunking` | Helper chunking teks | Helper chunking teks outbound | + | `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 untuk provider | + | `plugin-sdk/text-runtime` | Helper teks bersama | Penghapusan teks yang terlihat asisten, helper render/chunking/tabel markdown, helper redaksi, helper tag direktif, utilitas teks aman, 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 ekspor helper direktif, registry, dan validasi untuk provider | - | `plugin-sdk/speech-core` | Inti speech bersama | Tipe provider speech, registry, direktif, normalisasi | + | `plugin-sdk/speech-core` | Core speech bersama | Tipe provider speech, registry, direktif, normalisasi | | `plugin-sdk/realtime-transcription` | Helper transkripsi realtime | Tipe provider dan helper registry | | `plugin-sdk/realtime-voice` | Helper suara realtime | Tipe provider dan helper registry | - | `plugin-sdk/image-generation-core` | Inti image-generation bersama | Tipe image-generation, failover, auth, dan helper registry | - | `plugin-sdk/music-generation` | Helper music-generation | Tipe provider/request/result music-generation | - | `plugin-sdk/music-generation-core` | Inti music-generation bersama | Tipe music-generation, helper failover, lookup provider, dan parsing model-ref | - | `plugin-sdk/video-generation` | Helper video-generation | Tipe provider/request/result video-generation | - | `plugin-sdk/video-generation-core` | Inti video-generation bersama | Tipe video-generation, helper failover, lookup provider, dan parsing model-ref | + | `plugin-sdk/image-generation-core` | Core image-generation bersama | Tipe image-generation, failover, auth, dan helper registry | + | `plugin-sdk/music-generation` | Helper music-generation | Tipe provider/permintaan/hasil music-generation | + | `plugin-sdk/music-generation-core` | Core music-generation bersama | Tipe music-generation, helper failover, pencarian provider, dan parsing model-ref | + | `plugin-sdk/video-generation` | Helper video-generation | Tipe provider/permintaan/hasil video-generation | + | `plugin-sdk/video-generation-core` | Core video-generation bersama | Tipe video-generation, helper failover, pencarian provider, dan parsing model-ref | | `plugin-sdk/interactive-runtime` | Helper balasan interaktif | Normalisasi/reduksi payload balasan interaktif | - | `plugin-sdk/channel-config-primitives` | Primitive config channel | Primitive 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/channel-config-primitives` | Primitive config kanal | Primitive channel config-schema yang sempit | + | `plugin-sdk/channel-config-writes` | Helper penulisan config kanal | Helper otorisasi penulisan config kanal | + | `plugin-sdk/channel-plugin-common` | Prelude kanal bersama | Ekspor prelude plugin kanal bersama | + | `plugin-sdk/channel-status` | Helper status kanal | Helper snapshot/ringkasan status kanal 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/direct-dm` | Helper DM langsung | Helper auth/guard DM langsung bersama | - | `plugin-sdk/extension-shared` | Helper extension bersama | Primitive helper passive-channel/status dan ambient proxy | - | `plugin-sdk/webhook-targets` | Helper target webhook | Registry target webhook dan helper pemasangan route | + | `plugin-sdk/extension-shared` | Helper ekstensi bersama | Primitive helper kanal/status pasif dan proxy ambient | + | `plugin-sdk/webhook-targets` | Helper target webhook | Registry 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 jarak jauh/lokal | + | `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 | Surface helper manajer/config/file/CLI memory | - | `plugin-sdk/memory-core-engine-runtime` | Fasad runtime engine memory | Fasad runtime index/search memory | + | `plugin-sdk/memory-core` | Helper memory-core bawaan | Permukaan helper memory manager/config/file/CLI | + | `plugin-sdk/memory-core-engine-runtime` | Fasad runtime engine memory | Fasad runtime indeks/pencarian 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-engine-storage` | Engine storage host memory | Ekspor engine storage host memory | | `plugin-sdk/memory-core-host-multimodal` | Helper multimodal host memory | Helper multimodal host memory | | `plugin-sdk/memory-core-host-query` | Helper query host memory | Helper query host memory | | `plugin-sdk/memory-core-host-secret` | Helper secret host memory | Helper secret host memory | - | `plugin-sdk/memory-core-host-events` | Helper jurnal event host memory | Helper jurnal event host memory | + | `plugin-sdk/memory-core-host-events` | Helper jurnal peristiwa host memory | Helper jurnal peristiwa host memory | | `plugin-sdk/memory-core-host-status` | Helper status host memory | Helper status host memory | | `plugin-sdk/memory-core-host-runtime-cli` | Runtime CLI host memory | Helper runtime CLI host memory | - | `plugin-sdk/memory-core-host-runtime-core` | Runtime inti host memory | Helper runtime inti host memory | + | `plugin-sdk/memory-core-host-runtime-core` | Runtime core host memory | Helper runtime core 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-core` | Alias runtime core host memory | Alias netral-vendor untuk helper runtime core host memory | + | `plugin-sdk/memory-host-events` | Alias jurnal peristiwa host memory | Alias netral-vendor untuk helper jurnal peristiwa 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 pencarian memory aktif | Fasad runtime search-manager active-memory lazy | + | `plugin-sdk/memory-host-search` | Fasad pencarian memory aktif | 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 | Surface helper memory-lancedb | - | `plugin-sdk/testing` | Utilitas pengujian | Helper pengujian dan mock | + | `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 -surface SDK. Daftar lengkap 200+ entrypoint ada di +permukaan SDK. Daftar lengkap 200+ entrypoint berada di `scripts/lib/plugin-sdk-entrypoints.json`. 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*`. Itu tetap diekspor untuk +`plugin-sdk/zalo-setup`, dan `plugin-sdk/matrix*`. Semuanya 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*` - LINE: `plugin-sdk/line*` - IRC: `plugin-sdk/irc*` -- surface helper/plugin bawaan seperti `plugin-sdk/googlechat`, +- permukaan helper/plugin bawaan seperti `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles*`, `plugin-sdk/mattermost*`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, @@ -372,38 +373,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 -surface helper token yang sempit `DEFAULT_COPILOT_API_BASE_URL`, +permukaan helper token yang sempit `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken`, dan `resolveCopilotApiToken`. -Gunakan impor tersempit yang sesuai dengan pekerjaan Anda. Jika Anda tidak dapat menemukan ekspor, -periksa source di `src/plugin-sdk/` atau tanyakan di Discord. +Gunakan impor tersempit yang sesuai dengan pekerjaan. Jika Anda tidak dapat menemukan ekspor, +periksa sumber di `src/plugin-sdk/` atau tanyakan di Discord. ## Linimasa penghapusan -| Kapan | Apa yang terjadi | -| ---------------------- | --------------------------------------------------------------------- | -| **Sekarang** | Surface deprecated mengeluarkan peringatan runtime | -| **Rilis mayor berikutnya** | Surface deprecated akan dihapus; plugin yang masih menggunakannya akan gagal | +| Kapan | Apa yang terjadi | +| ---------------------- | ----------------------------------------------------------------------- | +| **Sekarang** | Permukaan deprecated memancarkan peringatan runtime | +| **Rilis mayor berikutnya** | Permukaan deprecated akan dihapus; plugin yang masih menggunakannya akan gagal | -Semua plugin core sudah dimigrasikan. Plugin eksternal sebaiknya bermigrasi +Semua plugin core sudah dimigrasikan. Plugin eksternal harus bermigrasi sebelum rilis mayor berikutnya. ## Menyembunyikan peringatan sementara -Setel variabel environment ini saat Anda sedang melakukan migrasi: +Setel variabel environment 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 celah keluar sementara, bukan solusi permanen. +Ini adalah jalan keluar sementara, bukan solusi permanen. ## Terkait -- [Getting Started](/id/plugins/building-plugins) — bangun 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 +- [Memulai](/id/plugins/building-plugins) — buat plugin pertama Anda +- [Ikhtisar SDK](/id/plugins/sdk-overview) — referensi impor subpath lengkap +- [Plugin Kanal](/id/plugins/sdk-channel-plugins) — membangun plugin kanal +- [Plugin Provider](/id/plugins/sdk-provider-plugins) — membangun plugin provider +- [Internal Plugin](/id/plugins/architecture) — pendalaman arsitektur +- [Manifest Plugin](/id/plugins/manifest) — referensi schema manifest diff --git a/docs/id/plugins/sdk-overview.md b/docs/id/plugins/sdk-overview.md index deb90b61b..c4226a5fc 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 dari + - Anda perlu mengetahui subpath SDK mana yang harus diimpor - Anda menginginkan referensi untuk semua metode pendaftaran pada OpenClawPluginApi - - Anda sedang mencari ekspor SDK tertentu + - Anda sedang mencari export SDK tertentu sidebarTitle: SDK Overview -summary: Peta impor, referensi API pendaftaran, dan arsitektur SDK +summary: Peta import, referensi API pendaftaran, dan arsitektur SDK title: Ikhtisar Plugin SDK x-i18n: - generated_at: "2026-04-08T09:13:46Z" + generated_at: "2026-04-09T01:30:24Z" model: gpt-5.4 provider: openai - source_hash: 6e7b420eb0f3faa8916357d52df949f6c9a46f1c843a1e6a0c0b8bb26db6cbff + source_hash: bf205af060971931df97dca4af5110ce173d2b7c12f56ad7c62d664a402f2381 source_path: plugins/sdk-overview.md workflow: 15 --- @@ -22,9 +22,9 @@ referensi untuk **apa yang harus diimpor** dan **apa yang dapat Anda daftarkan** **Mencari panduan cara melakukannya?** - - Plugin pertama? Mulai dengan [Getting Started](/id/plugins/building-plugins) - - Plugin channel? Lihat [Channel Plugins](/id/plugins/sdk-channel-plugins) - - Plugin provider? Lihat [Provider Plugins](/id/plugins/sdk-provider-plugins) + - Plugin pertama? Mulai dari [Getting Started](/id/plugins/building-plugins) + - Plugin channel? Lihat [Plugin Channel](/id/plugins/sdk-channel-plugins) + - Plugin penyedia? Lihat [Plugin Penyedia](/id/plugins/sdk-provider-plugins) ## Konvensi impor @@ -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 dependensi melingkar. Untuk helper entry/build khusus channel, -utamakan `openclaw/plugin-sdk/channel-core`; gunakan `openclaw/plugin-sdk/core` untuk -permukaan payung yang lebih luas dan helper bersama seperti +Setiap subpath adalah modul kecil yang mandiri. Ini menjaga startup tetap cepat dan +mencegah masalah dependensi sirkular. Untuk helper entry/build khusus channel, +pilih `openclaw/plugin-sdk/channel-core`; gunakan `openclaw/plugin-sdk/core` untuk +surface payung yang lebih luas dan helper bersama seperti `buildChannelConfigSchema`. -Jangan tambahkan atau bergantung pada seam kemudahan bernama provider seperti +Jangan menambahkan atau bergantung pada seam kenyamanan bernama penyedia seperti `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, atau seam helper bermerek channel. Plugin bawaan harus menyusun subpath -SDK generik di dalam barrel `api.ts` atau `runtime-api.ts` mereka sendiri, dan core -harus menggunakan barrel lokal plugin tersebut atau menambahkan kontrak SDK generik -yang sempit saat kebutuhannya benar-benar lintas channel. +SDK generik di dalam barrel `api.ts` atau `runtime-api.ts` miliknya sendiri, dan core +harus menggunakan barrel lokal plugin tersebut atau menambahkan kontrak SDK generik sempit +saat kebutuhannya benar-benar lintas channel. -Peta ekspor yang dihasilkan masih memuat sejumlah kecil seam helper plugin bawaan -seperti `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, +Peta export yang dihasilkan masih memuat 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 plugin bawaan; subpath itu -sengaja tidak dimasukkan dari tabel umum di bawah dan bukan jalur impor yang -direkomendasikan untuk plugin pihak ketiga yang baru. +tersebut ada hanya untuk pemeliharaan dan kompatibilitas plugin bawaan; sengaja tidak dicantumkan +dalam tabel umum di bawah ini dan bukan jalur impor yang direkomendasikan untuk plugin pihak ketiga baru. ## Referensi subpath -Subpath yang paling umum digunakan, dikelompokkan berdasarkan tujuan. Daftar lengkap yang dihasilkan -berisi lebih dari 200 subpath ada di `scripts/lib/plugin-sdk-entrypoints.json`. +Subpath yang paling umum digunakan, dikelompokkan berdasarkan tujuan. Daftar lengkap yang dihasilkan berisi +200+ subpath berada di `scripts/lib/plugin-sdk-entrypoints.json`. -Subpath helper plugin bawaan yang dicadangkan masih muncul dalam daftar yang dihasilkan itu. -Perlakukan itu sebagai permukaan detail implementasi/kompatibilitas kecuali suatu halaman dokumentasi +Subpath helper plugin bawaan yang dicadangkan masih muncul dalam daftar yang dihasilkan tersebut. +Perlakukan itu sebagai detail implementasi/surface kompatibilitas kecuali sebuah halaman dokumen secara eksplisit mempromosikannya sebagai publik. ### Entri plugin -| Subpath | Ekspor utama | +| Subpath | Export utama | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `plugin-sdk/plugin-entry` | `definePluginEntry` | | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | @@ -77,10 +76,10 @@ secara eksplisit mempromosikannya sebagai publik. - | Subpath | Ekspor utama | + | Subpath | Export utama | | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/config-schema` | Ekspor skema Zod root `openclaw.json` (`OpenClawSchema`) | + | `plugin-sdk/config-schema` | Export skema Zod root `openclaw.json` (`OpenClawSchema`) | | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, serta `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` | @@ -88,215 +87,216 @@ secara eksplisit mempromosikannya sebagai publik. | `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-id` | `DEFAULT_ACCOUNT_ID`, helper normalisasi account-id | - | `plugin-sdk/account-resolution` | Helper pencarian akun + fallback default | - | `plugin-sdk/account-helpers` | Helper sempit untuk daftar akun/tindakan akun | + | `plugin-sdk/account-resolution` | Helper lookup akun + fallback default | + | `plugin-sdk/account-helpers` | Helper sempit daftar-aksi akun/aksi akun | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Tipe skema config channel | - | `plugin-sdk/telegram-command-config` | Helper normalisasi/validasi custom command Telegram dengan fallback kontrak bawaan | + | `plugin-sdk/channel-config-schema` | Tipe skema konfigurasi channel | + | `plugin-sdk/telegram-command-config` | Helper normalisasi/validasi perintah kustom Telegram dengan fallback kontrak bawaan | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | Helper rute inbound + builder envelope bersama | - | `plugin-sdk/inbound-reply-dispatch` | Helper record-and-dispatch inbound bersama | + | `plugin-sdk/inbound-envelope` | Helper route inbound + builder envelope bersama | + | `plugin-sdk/inbound-reply-dispatch` | Helper pencatatan-dan-dispatch inbound bersama | | `plugin-sdk/messaging-targets` | Helper parsing/pencocokan target | | `plugin-sdk/outbound-media` | Helper pemuatan media outbound bersama | - | `plugin-sdk/outbound-runtime` | Helper identitas outbound/delegasi pengiriman | + | `plugin-sdk/outbound-runtime` | Helper delegasi identitas/kirim outbound | | `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` | Helper binding percakapan/thread, pairing, dan configured-binding | - | `plugin-sdk/runtime-config-snapshot` | Helper snapshot config runtime | - | `plugin-sdk/runtime-group-policy` | Helper resolusi group-policy runtime | + | `plugin-sdk/agent-media-payload` | Builder payload media agen lama | + | `plugin-sdk/conversation-runtime` | Helper pengikatan percakapan/thread, pairing, dan configured-binding | + | `plugin-sdk/runtime-config-snapshot` | Helper snapshot konfigurasi runtime | + | `plugin-sdk/runtime-group-policy` | Helper resolusi kebijakan grup runtime | | `plugin-sdk/channel-status` | Helper snapshot/ringkasan status channel bersama | - | `plugin-sdk/channel-config-primitives` | 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/channel-config-primitives` | Primitif skema konfigurasi channel yang sempit | + | `plugin-sdk/channel-config-writes` | Helper otorisasi penulisan konfigurasi channel | + | `plugin-sdk/channel-plugin-common` | Export prelude plugin channel bersama | + | `plugin-sdk/allowlist-config-edit` | Helper edit/baca konfigurasi allowlist | | `plugin-sdk/group-access` | Helper keputusan akses grup bersama | - | `plugin-sdk/direct-dm` | Helper auth/guard direct-DM bersama | + | `plugin-sdk/direct-dm` | Helper auth/guard DM langsung bersama | | `plugin-sdk/interactive-runtime` | Helper normalisasi/reduksi payload balasan interaktif | - | `plugin-sdk/channel-inbound` | Debounce inbound, pencocokan mention, helper kebijakan mention, dan helper envelope | + | `plugin-sdk/channel-inbound` | Helper debounce inbound, pencocokan mention, kebijakan mention, dan helper envelope | | `plugin-sdk/channel-send-result` | Tipe hasil balasan | | `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` | | `plugin-sdk/channel-targets` | Helper parsing/pencocokan target | | `plugin-sdk/channel-contract` | Tipe kontrak channel | | `plugin-sdk/channel-feedback` | Wiring feedback/reaksi | - | `plugin-sdk/channel-secret-runtime` | Helper kontrak secret yang sempit seperti `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, dan tipe target secret | + | `plugin-sdk/channel-secret-runtime` | Helper kontrak rahasia sempit seperti `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, dan tipe target rahasia | - - | Subpath | Ekspor utama | + + | Subpath | Export utama | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/provider-setup` | Helper setup provider lokal/self-hosted yang terkurasi | - | `plugin-sdk/self-hosted-provider-setup` | Helper setup provider self-hosted kompatibel OpenAI yang terfokus | + | `plugin-sdk/provider-setup` | Helper setup penyedia lokal/self-hosted terkurasi | + | `plugin-sdk/self-hosted-provider-setup` | Helper setup penyedia self-hosted kompatibel OpenAI yang terfokus | | `plugin-sdk/cli-backend` | Default backend CLI + konstanta watchdog | - | `plugin-sdk/provider-auth-runtime` | Helper resolusi API key runtime untuk plugin provider | + | `plugin-sdk/provider-auth-runtime` | Helper resolusi API key runtime untuk plugin penyedia | | `plugin-sdk/provider-auth-api-key` | Helper onboarding/penulisan profil API key seperti `upsertApiKeyProfile` | | `plugin-sdk/provider-auth-result` | Builder hasil auth OAuth standar | - | `plugin-sdk/provider-auth-login` | Helper login interaktif bersama untuk plugin provider | - | `plugin-sdk/provider-env-vars` | Helper pencarian env var auth provider | + | `plugin-sdk/provider-auth-login` | Helper login interaktif bersama untuk plugin penyedia | + | `plugin-sdk/provider-env-vars` | Helper lookup env var auth penyedia | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, builder kebijakan replay bersama, helper endpoint provider, dan helper normalisasi model-id seperti `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, builder kebijakan replay bersama, helper endpoint penyedia, dan helper normalisasi model-id seperti `normalizeNativeXaiModelId` | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | Helper kapabilitas HTTP/endpoint provider generik | - | `plugin-sdk/provider-web-fetch-contract` | Helper kontrak config/seleksi web-fetch yang sempit seperti `enablePluginInConfig` dan `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | Helper pendaftaran/cache provider web-fetch | - | `plugin-sdk/provider-web-search-config-contract` | Helper config/kredensial web-search yang sempit untuk provider yang tidak memerlukan wiring enable plugin | - | `plugin-sdk/provider-web-search-contract` | Helper kontrak config/kredensial web-search yang sempit seperti `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`, dan setter/getter kredensial berpencakupan | - | `plugin-sdk/provider-web-search` | Helper pendaftaran/cache/runtime provider web-search | + | `plugin-sdk/provider-http` | Helper kapabilitas HTTP/endpoint penyedia generik | + | `plugin-sdk/provider-web-fetch-contract` | Helper kontrak konfigurasi/seleksi web-fetch sempit seperti `enablePluginInConfig` dan `WebFetchProviderPlugin` | + | `plugin-sdk/provider-web-fetch` | Helper pendaftaran/cache penyedia web-fetch | + | `plugin-sdk/provider-web-search-config-contract` | Helper sempit konfigurasi/kredensial web search untuk penyedia yang tidak memerlukan wiring plugin-enable | + | `plugin-sdk/provider-web-search-contract` | Helper kontrak konfigurasi/kredensial web search sempit seperti `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`, dan setter/getter kredensial terlingkup | + | `plugin-sdk/provider-web-search` | Helper pendaftaran/cache/runtime penyedia web search | | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, pembersihan skema Gemini + diagnostik, dan helper kompatibilitas xAI seperti `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | `fetchClaudeUsage` dan yang serupa | + | `plugin-sdk/provider-usage` | `fetchClaudeUsage` dan sejenisnya | | `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/provider-onboard` | Helper patch konfigurasi onboarding | + | `plugin-sdk/global-singleton` | Helper singleton/peta/cache lokal proses | - | Subpath | Ekspor utama | + | Subpath | Export utama | | --- | --- | - | `plugin-sdk/command-auth` | `resolveControlCommandGate`, helper registri command, helper otorisasi pengirim | - | `plugin-sdk/approval-auth-runtime` | Helper resolusi approver dan auth tindakan obrolan yang sama | + | `plugin-sdk/command-auth` | `resolveControlCommandGate`, helper registri perintah, helper otorisasi pengirim | + | `plugin-sdk/command-status` | Builder pesan perintah/bantuan seperti `buildCommandsMessagePaginated` dan `buildHelpMessage` | + | `plugin-sdk/approval-auth-runtime` | Helper resolusi approver dan auth aksi same-chat | | `plugin-sdk/approval-client-runtime` | Helper profil/filter approval exec native | - | `plugin-sdk/approval-delivery-runtime` | Adapter kapabilitas/pengiriman approval native | + | `plugin-sdk/approval-delivery-runtime` | Adapter kemampuan/pengiriman approval native | | `plugin-sdk/approval-gateway-runtime` | Helper resolusi gateway approval bersama | - | `plugin-sdk/approval-handler-adapter-runtime` | Helper pemuatan adapter approval native ringan untuk entrypoint channel yang sering dipanggil | - | `plugin-sdk/approval-handler-runtime` | Helper runtime handler approval yang lebih luas; utamakan seam adapter/gateway yang lebih sempit bila itu sudah cukup | - | `plugin-sdk/approval-native-runtime` | Helper target approval native + binding akun | + | `plugin-sdk/approval-handler-adapter-runtime` | Helper ringan pemuatan adapter approval native untuk entrypoint channel panas | + | `plugin-sdk/approval-handler-runtime` | Helper runtime approval handler yang lebih luas; pilih seam adapter/gateway yang lebih sempit bila sudah cukup | + | `plugin-sdk/approval-native-runtime` | Helper target approval native + account-binding | | `plugin-sdk/approval-reply-runtime` | Helper payload balasan approval exec/plugin | - | `plugin-sdk/command-auth-native` | Auth command native + helper target sesi native | - | `plugin-sdk/command-detection` | Helper deteksi command bersama | - | `plugin-sdk/command-surface` | Helper normalisasi badan command dan permukaan command | + | `plugin-sdk/command-auth-native` | Helper auth perintah native + target sesi native | + | `plugin-sdk/command-detection` | Helper deteksi perintah bersama | + | `plugin-sdk/command-surface` | Helper normalisasi badan perintah dan surface perintah | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | Helper koleksi kontrak secret yang sempit untuk permukaan secret channel/plugin | - | `plugin-sdk/secret-ref-runtime` | Helper `coerceSecretRef` yang sempit dan helper tipe SecretRef untuk parsing kontrak secret/config | - | `plugin-sdk/security-runtime` | Helper trust, gating DM, konten eksternal, dan pengumpulan secret bersama | + | `plugin-sdk/channel-secret-runtime` | Helper pengumpulan kontrak rahasia sempit untuk surface rahasia channel/plugin | + | `plugin-sdk/secret-ref-runtime` | Helper sempit `coerceSecretRef` dan typing SecretRef untuk parsing kontrak rahasia/konfigurasi | + | `plugin-sdk/security-runtime` | Helper trust, gating DM, konten eksternal, dan pengumpulan rahasia bersama | | `plugin-sdk/ssrf-policy` | Helper allowlist host dan kebijakan SSRF jaringan privat | - | `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/timeout request | + | `plugin-sdk/ssrf-runtime` | Helper pinned-dispatcher, fetch berpenjaga SSRF, dan kebijakan SSRF | + | `plugin-sdk/secret-input` | Helper parsing input rahasia | + | `plugin-sdk/webhook-ingress` | Helper permintaan/target webhook | + | `plugin-sdk/webhook-request-guards` | Helper ukuran body request/timeout | - - | Subpath | Ekspor utama | + + | Subpath | Export utama | | --- | --- | - | `plugin-sdk/runtime` | Helper runtime/logging/backup/instal plugin yang luas | - | `plugin-sdk/runtime-env` | Helper env runtime, logger, timeout, retry, dan backoff yang sempit | - | `plugin-sdk/channel-runtime-context` | Helper generik untuk pendaftaran dan pencarian konteks runtime channel | + | `plugin-sdk/runtime` | Helper luas runtime/logging/backup/instalasi plugin | + | `plugin-sdk/runtime-env` | Helper sempit env runtime, logger, timeout, retry, dan backoff | + | `plugin-sdk/channel-runtime-context` | Helper generik pendaftaran dan lookup konteks runtime channel | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `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 eksekusi proses | - | `plugin-sdk/cli-runtime` | Helper format, tunggu, dan versi CLI | - | `plugin-sdk/gateway-runtime` | Helper client gateway dan patch status channel | - | `plugin-sdk/config-runtime` | Helper pemuatan/penulisan 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 kapabilitas approval, helper auth/profil, helper routing/runtime native | + | `plugin-sdk/plugin-runtime` | Helper bersama perintah/hook/http/interaktif plugin | + | `plugin-sdk/hook-runtime` | Helper pipeline webhook/internal hook bersama | + | `plugin-sdk/lazy-runtime` | Helper impor/pengikatan runtime lazy seperti `createLazyRuntimeModule`, `createLazyRuntimeMethod`, dan `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | Helper exec proses | + | `plugin-sdk/cli-runtime` | Helper formatting, wait, dan versi CLI | + | `plugin-sdk/gateway-runtime` | Helper klien gateway dan patch status channel | + | `plugin-sdk/config-runtime` | Helper pemuatan/penulisan konfigurasi | + | `plugin-sdk/telegram-command-config` | Normalisasi nama/deskripsi perintah Telegram dan pemeriksaan duplikat/konflik, bahkan saat surface 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 dispatch/finalisasi balasan yang sempit | - | `plugin-sdk/reply-history` | Helper riwayat balasan jendela pendek bersama seperti `buildHistoryContext`, `recordPendingHistoryEntry`, dan `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/reply-dispatch-runtime` | Helper sempit dispatch/finalize balasan | + | `plugin-sdk/reply-history` | Helper bersama riwayat balasan jendela pendek seperti `buildHistoryContext`, `recordPendingHistoryEntry`, dan `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Helper chunking teks/markdown yang sempit | - | `plugin-sdk/session-store-runtime` | Helper path penyimpanan sesi + updated-at | + | `plugin-sdk/reply-chunking` | Helper sempit chunking teks/markdown | + | `plugin-sdk/session-store-runtime` | Helper path store sesi + updated-at | | `plugin-sdk/state-paths` | Helper path direktori state/OAuth | - | `plugin-sdk/routing` | Helper rute/kunci sesi/binding akun seperti `resolveAgentRoute`, `buildAgentSessionKey`, dan `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | Helper ringkasan status channel/akun bersama, default state runtime, dan helper metadata isu | + | `plugin-sdk/routing` | Helper route/session-key/account binding seperti `resolveAgentRoute`, `buildAgentSessionKey`, dan `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | Helper ringkasan status channel/akun bersama, default state runtime, dan helper metadata issue | | `plugin-sdk/target-resolver-runtime` | Helper resolver target bersama | | `plugin-sdk/string-normalization-runtime` | Helper normalisasi slug/string | | `plugin-sdk/request-url` | Ekstrak URL string dari input mirip fetch/request | - | `plugin-sdk/run-command` | Runner command bertimer dengan hasil stdout/stderr yang dinormalisasi | - | `plugin-sdk/param-readers` | Pembaca param umum untuk tool/CLI | - | `plugin-sdk/tool-payload` | Ekstrak payload yang dinormalisasi dari objek hasil tool | - | `plugin-sdk/tool-send` | Ekstrak field target pengiriman kanonis dari argumen tool | + | `plugin-sdk/run-command` | Runner perintah bertimer dengan hasil stdout/stderr ternormalisasi | + | `plugin-sdk/param-readers` | Pembaca param tool/CLI umum | + | `plugin-sdk/tool-payload` | Ekstrak payload ternormalisasi dari objek hasil tool | + | `plugin-sdk/tool-send` | Ekstrak field target kirim kanonis dari arg tool | | `plugin-sdk/temp-path` | Helper path 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 baca/tulis state JSON kecil | + | `plugin-sdk/json-store` | Helper kecil baca/tulis state JSON | | `plugin-sdk/file-lock` | Helper file-lock re-entrant | | `plugin-sdk/persistent-dedupe` | Helper cache dedupe berbasis disk | - | `plugin-sdk/acp-runtime` | Helper ACP runtime/sesi dan reply-dispatch | - | `plugin-sdk/agent-config-primitives` | Primitive sempit skema config runtime agent | + | `plugin-sdk/acp-runtime` | Helper runtime/sesi ACP dan reply-dispatch | + | `plugin-sdk/agent-config-primitives` | Primitif skema konfigurasi runtime agen yang sempit | | `plugin-sdk/boolean-param` | Pembaca param boolean longgar | | `plugin-sdk/dangerous-name-runtime` | Helper resolusi pencocokan nama berbahaya | | `plugin-sdk/device-bootstrap` | Helper bootstrap perangkat dan token pairing | - | `plugin-sdk/extension-shared` | Primitive helper bersama untuk passive-channel, status, dan ambient proxy | - | `plugin-sdk/models-provider-runtime` | Helper balasan command/provider `/models` | - | `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.AI | - | `plugin-sdk/infra-runtime` | Helper event sistem/heartbeat | - | `plugin-sdk/collection-runtime` | Helper cache kecil yang dibatasi | + | `plugin-sdk/extension-shared` | Primitif helper proksi ambient, status, dan passive-channel bersama | + | `plugin-sdk/models-provider-runtime` | Helper balasan perintah/penyedia `/models` | + | `plugin-sdk/skill-commands-runtime` | Helper daftar perintah Skills | + | `plugin-sdk/native-command-registry` | Helper registri/build/serialize perintah 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 terbatas | | `plugin-sdk/diagnostic-runtime` | Helper flag dan event diagnostik | - | `plugin-sdk/error-runtime` | Helper graf error, formatting, klasifikasi error bersama, `isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | Helper fetch terbungkus, proxy, dan pencarian pinned | + | `plugin-sdk/error-runtime` | Grafik error, formatting, helper klasifikasi error bersama, `isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | Helper wrapped fetch, 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 direktori/identitas/workspace agent | - | `plugin-sdk/directory-runtime` | Query/dedup direktori berbasis config | + | `plugin-sdk/retry-runtime` | Helper konfigurasi retry dan runner retry | + | `plugin-sdk/agent-runtime` | Helper direktori/identitas/workspace agen | + | `plugin-sdk/directory-runtime` | Query/deduplikasi direktori berbasis konfigurasi | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | - | Subpath | Ekspor utama | + | Subpath | Export utama | | --- | --- | - | `plugin-sdk/media-runtime` | Helper fetch/transform/store media bersama plus builder payload media | - | `plugin-sdk/media-generation-runtime` | Helper failover media-generation bersama, pemilihan kandidat, dan pesan model yang hilang | - | `plugin-sdk/media-understanding` | Tipe provider media understanding plus 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 tag arahan, dan utilitas safe-text | + | `plugin-sdk/media-runtime` | Helper bersama fetch/transform/store media plus builder payload media | + | `plugin-sdk/media-generation-runtime` | Helper bersama failover pembuatan media, pemilihan kandidat, dan pesan model yang hilang | + | `plugin-sdk/media-understanding` | Tipe penyedia pemahaman media plus export helper gambar/audio untuk penyedia | + | `plugin-sdk/text-runtime` | Helper bersama teks/markdown/logging seperti penghapusan teks yang terlihat oleh asisten, helper render/chunking/tabel markdown, helper redaksi, helper directive-tag, dan utilitas safe-text | | `plugin-sdk/text-chunking` | Helper chunking teks outbound | - | `plugin-sdk/speech` | Tipe provider speech plus ekspor helper arahan, registri, dan validasi yang menghadap provider | - | `plugin-sdk/speech-core` | Tipe provider speech bersama, registri, arahan, dan helper normalisasi | - | `plugin-sdk/realtime-transcription` | Tipe provider realtime transcription dan helper registri | - | `plugin-sdk/realtime-voice` | Tipe provider realtime voice dan helper registri | - | `plugin-sdk/image-generation` | Tipe provider image generation | - | `plugin-sdk/image-generation-core` | Tipe image-generation bersama, failover, auth, dan helper registri | - | `plugin-sdk/music-generation` | Tipe provider/request/result music generation | - | `plugin-sdk/music-generation-core` | Tipe music-generation bersama, helper failover, pencarian provider, dan parsing model-ref | - | `plugin-sdk/video-generation` | Tipe provider/request/result video generation | - | `plugin-sdk/video-generation-core` | Tipe video-generation bersama, helper failover, pencarian provider, dan parsing model-ref | - | `plugin-sdk/webhook-targets` | Registry target webhook dan helper pemasangan rute | + | `plugin-sdk/speech` | Tipe penyedia speech plus helper directive, registri, dan validasi untuk penyedia | + | `plugin-sdk/speech-core` | Tipe penyedia speech bersama, helper registri, directive, dan normalisasi | + | `plugin-sdk/realtime-transcription` | Tipe penyedia transkripsi realtime dan helper registri | + | `plugin-sdk/realtime-voice` | Tipe penyedia suara realtime dan helper registri | + | `plugin-sdk/image-generation` | Tipe penyedia pembuatan gambar | + | `plugin-sdk/image-generation-core` | Tipe pembuatan gambar bersama, failover, auth, dan helper registri | + | `plugin-sdk/music-generation` | Tipe permintaan/hasil/penyedia pembuatan musik | + | `plugin-sdk/music-generation-core` | Tipe pembuatan musik bersama, helper failover, lookup penyedia, dan parsing model-ref | + | `plugin-sdk/video-generation` | Tipe penyedia/permintaan/hasil pembuatan video | + | `plugin-sdk/video-generation-core` | Tipe pembuatan video bersama, helper failover, lookup penyedia, dan parsing model-ref | + | `plugin-sdk/webhook-targets` | Registri target webhook dan helper pemasangan route | | `plugin-sdk/webhook-path` | Helper normalisasi path webhook | - | `plugin-sdk/web-media` | Helper pemuatan media remote/lokal bersama | - | `plugin-sdk/zod` | `zod` yang diekspor ulang untuk konsumen plugin SDK | + | `plugin-sdk/web-media` | Helper bersama pemuatan media remote/lokal | + | `plugin-sdk/zod` | `zod` yang diekspor ulang untuk konsumen Plugin SDK | | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | - - | Subpath | Ekspor utama | + + | Subpath | Export utama | | --- | --- | - | `plugin-sdk/memory-core` | Permukaan helper memory-core bawaan untuk helper manager/config/file/CLI | - | `plugin-sdk/memory-core-engine-runtime` | Fasad runtime indeks/pencarian memori | - | `plugin-sdk/memory-core-host-engine-foundation` | Ekspor engine fondasi host memori | - | `plugin-sdk/memory-core-host-engine-embeddings` | Ekspor engine embedding host memori | - | `plugin-sdk/memory-core-host-engine-qmd` | Ekspor engine QMD host memori | - | `plugin-sdk/memory-core-host-engine-storage` | Ekspor engine penyimpanan host memori | - | `plugin-sdk/memory-core-host-multimodal` | Helper multimodal host memori | - | `plugin-sdk/memory-core-host-query` | Helper query host memori | - | `plugin-sdk/memory-core-host-secret` | Helper secret host memori | - | `plugin-sdk/memory-core-host-events` | Helper jurnal event host memori | - | `plugin-sdk/memory-core-host-status` | Helper status host memori | - | `plugin-sdk/memory-core-host-runtime-cli` | Helper runtime CLI host memori | - | `plugin-sdk/memory-core-host-runtime-core` | Helper runtime core host memori | - | `plugin-sdk/memory-core-host-runtime-files` | Helper file/runtime host memori | - | `plugin-sdk/memory-host-core` | Alias netral-vendor untuk helper runtime inti host memori | - | `plugin-sdk/memory-host-events` | Alias netral-vendor untuk helper jurnal event host memori | - | `plugin-sdk/memory-host-files` | Alias netral-vendor untuk helper file/runtime host memori | - | `plugin-sdk/memory-host-markdown` | Helper managed-markdown bersama untuk plugin yang berdekatan dengan memori | - | `plugin-sdk/memory-host-search` | Fasad runtime memori aktif untuk akses search-manager | - | `plugin-sdk/memory-host-status` | Alias netral-vendor untuk helper status host memori | - | `plugin-sdk/memory-lancedb` | Permukaan helper memory-lancedb bawaan | + | `plugin-sdk/memory-core` | Surface 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-multimodal` | Helper multimodal host memory | + | `plugin-sdk/memory-core-host-query` | Helper query host memory | + | `plugin-sdk/memory-core-host-secret` | Helper rahasia host memory | + | `plugin-sdk/memory-core-host-events` | Helper jurnal event host memory | + | `plugin-sdk/memory-core-host-status` | Helper status host memory | + | `plugin-sdk/memory-core-host-runtime-cli` | Helper runtime CLI host memory | + | `plugin-sdk/memory-core-host-runtime-core` | Helper runtime core host memory | + | `plugin-sdk/memory-core-host-runtime-files` | Helper file/runtime host memory | + | `plugin-sdk/memory-host-core` | Alias netral vendor untuk helper runtime core host memory | + | `plugin-sdk/memory-host-events` | Alias netral vendor untuk helper jurnal event host memory | + | `plugin-sdk/memory-host-files` | Alias netral vendor untuk helper file/runtime host memory | + | `plugin-sdk/memory-host-markdown` | Helper managed-markdown bersama untuk plugin yang berdekatan dengan memory | + | `plugin-sdk/memory-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` | Surface helper memory-lancedb bawaan | - | Family | Subpath saat ini | Penggunaan yang dimaksudkan | + | Family | Subpath saat ini | Penggunaan yang dimaksud | | --- | --- | --- | | 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) | - | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Permukaan helper/runtime Matrix bawaan | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Permukaan helper/runtime LINE bawaan | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Permukaan helper IRC bawaan | - | Helper khusus channel | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Seam kompatibilitas/helper channel bawaan | + | 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` | Surface helper/runtime Matrix bawaan | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Surface helper/runtime LINE bawaan | + | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Surface 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 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` | @@ -308,56 +308,56 @@ berikut: ### Pendaftaran kapabilitas -| Method | Apa yang didaftarkan | +| Metode | Yang didaftarkan | | ------------------------------------------------ | -------------------------------- | | `api.registerProvider(...)` | Inferensi teks (LLM) | | `api.registerCliBackend(...)` | Backend inferensi CLI lokal | -| `api.registerChannel(...)` | Channel pesan | -| `api.registerSpeechProvider(...)` | Sintesis teks-ke-suara / STT | -| `api.registerRealtimeTranscriptionProvider(...)` | Transkripsi realtime streaming | -| `api.registerRealtimeVoiceProvider(...)` | Sesi suara realtime dupleks | -| `api.registerMediaUnderstandingProvider(...)` | Analisis gambar/audio/video | +| `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 web fetch / scrape | -| `api.registerWebSearchProvider(...)` | Pencarian web | +| `api.registerMusicGenerationProvider(...)` | Pembuatan musik | +| `api.registerVideoGenerationProvider(...)` | Pembuatan video | +| `api.registerWebFetchProvider(...)` | Penyedia fetch / scrape web | +| `api.registerWebSearchProvider(...)` | Pencarian web | -### Tools dan command +### Alat dan perintah -| Method | Apa yang didaftarkan | -| ------------------------------- | --------------------------------------------- | -| `api.registerTool(tool, opts?)` | Tool agent (wajib atau `{ optional: true }`) | -| `api.registerCommand(def)` | Command kustom (melewati LLM) | +| Metode | Yang didaftarkan | +| ------------------------------- | ---------------------------------------------- | +| `api.registerTool(tool, opts?)` | Alat agen (wajib atau `{ optional: true }`) | +| `api.registerCommand(def)` | Perintah kustom (melewati LLM) | ### Infrastruktur -| Method | Apa 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 memori | -| `api.registerMemoryCorpusSupplement(adapter)` | Korpus pencarian/baca memori aditif | +| Metode | Yang didaftarkan | +| ---------------------------------------------- | ----------------------------------- | +| `api.registerHook(events, handler, opts?)` | Hook event | +| `api.registerHttpRoute(params)` | Endpoint HTTP gateway | +| `api.registerGatewayMethod(name, handler)` | Metode RPC gateway | +| `api.registerCli(registrar, opts?)` | Subperintah CLI | +| `api.registerService(service)` | Layanan latar belakang | +| `api.registerInteractiveHandler(registration)` | Handler interaktif | +| `api.registerMemoryPromptSupplement(builder)` | Bagian prompt memory-adjacent aditif | +| `api.registerMemoryCorpusSupplement(adapter)` | Korpus 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 -metode yang dimiliki plugin. +`update.*`) selalu tetap `operator.admin`, meskipun plugin mencoba menetapkan scope +metode gateway yang lebih sempit. Pilih prefiks khusus plugin untuk +metode milik plugin. ### Metadata pendaftaran CLI -`api.registerCli(registrar, opts?)` menerima dua jenis metadata tingkat atas: +`api.registerCli(registrar, opts?)` menerima dua jenis metadata level teratas: -- `commands`: root command eksplisit yang dimiliki registrar -- `descriptors`: deskriptor command saat parse yang digunakan untuk bantuan CLI root, +- `commands`: root perintah eksplisit yang dimiliki registrar +- `descriptors`: deskriptor perintah saat parse-time yang digunakan untuk bantuan CLI root, routing, dan pendaftaran 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 +Jika Anda ingin perintah plugin tetap dimuat secara lazy di jalur CLI root normal, +berikan `descriptors` yang mencakup setiap root perintah level teratas yang diekspos oleh registrar tersebut. ```typescript @@ -370,7 +370,7 @@ api.registerCli( descriptors: [ { name: "matrix", - description: "Kelola akun Matrix, verifikasi, perangkat, dan status profil", + description: "Kelola akun Matrix, verifikasi, perangkat, dan state profil", hasSubcommands: true, }, ], @@ -378,83 +378,83 @@ api.registerCli( ); ``` -Gunakan `commands` saja hanya ketika Anda tidak memerlukan pendaftaran CLI root secara lazy. +Gunakan `commands` saja hanya ketika Anda tidak memerlukan pendaftaran CLI root lazy. Jalur kompatibilitas eager tersebut tetap didukung, tetapi tidak memasang -placeholder berbasis descriptor untuk pemuatan lazy saat parse-time. +placeholder berbasis descriptor untuk pemuatan lazy pada parse-time. ### Pendaftaran backend CLI -`api.registerCliBackend(...)` memungkinkan plugin memiliki config default untuk backend +`api.registerCliBackend(...)` memungkinkan plugin memiliki konfigurasi default untuk backend CLI AI lokal seperti `codex-cli`. -- `id` backend menjadi prefiks provider dalam model ref seperti `codex-cli/gpt-5`. +- `id` backend menjadi prefiks penyedia dalam referensi model seperti `codex-cli/gpt-5`. - `config` backend menggunakan bentuk yang sama seperti `agents.defaults.cliBackends.`. -- Config pengguna tetap menang. OpenClaw menggabungkan `agents.defaults.cliBackends.` di atas default - plugin sebelum menjalankan CLI. +- Konfigurasi pengguna tetap menang. OpenClaw menggabungkan `agents.defaults.cliBackends.` di atas + default plugin sebelum menjalankan CLI. - Gunakan `normalizeConfig` saat backend memerlukan penulisan ulang kompatibilitas setelah penggabungan - (misalnya menormalisasi bentuk flag lama). + (misalnya menormalkan bentuk flag lama). ### Slot eksklusif -| Method | Apa yang didaftarkan | +| Metode | Yang didaftarkan | | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `api.registerContextEngine(id, factory)` | Engine konteks (satu aktif pada satu waktu). Callback `assemble()` menerima `availableTools` dan `citationsMode` sehingga engine dapat menyesuaikan penambahan prompt. | -| `api.registerMemoryCapability(capability)` | Kapabilitas memori terpadu | -| `api.registerMemoryPromptSection(builder)` | Builder bagian prompt memori | -| `api.registerMemoryFlushPlan(resolver)` | Resolver rencana flush memori | -| `api.registerMemoryRuntime(runtime)` | Adapter runtime memori | +| `api.registerContextEngine(id, factory)` | Context engine (satu aktif pada satu waktu). Callback `assemble()` menerima `availableTools` dan `citationsMode` agar engine dapat menyesuaikan tambahan prompt. | +| `api.registerMemoryCapability(capability)` | Kapabilitas memory terpadu | +| `api.registerMemoryPromptSection(builder)` | Builder bagian prompt memory | +| `api.registerMemoryFlushPlan(resolver)` | Resolver rencana flush memory | +| `api.registerMemoryRuntime(runtime)` | Adapter runtime memory | -### Adapter embedding memori +### Adapter embedding memory -| Method | Apa yang didaftarkan | +| Metode | Yang didaftarkan | | ---------------------------------------------- | ---------------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | Adapter embedding memori untuk plugin aktif | +| `api.registerMemoryEmbeddingProvider(adapter)` | Adapter embedding memory untuk plugin aktif | -- `registerMemoryCapability` adalah API plugin memori eksklusif yang diutamakan. +- `registerMemoryCapability` adalah API plugin memory eksklusif yang direkomendasikan. - `registerMemoryCapability` juga dapat mengekspos `publicArtifacts.listArtifacts(...)` - sehingga plugin pendamping dapat menggunakan artefak memori yang diekspor melalui - `openclaw/plugin-sdk/memory-host-core` alih-alih menjangkau tata letak privat - plugin memori tertentu. + agar plugin pendamping dapat mengonsumsi artefak memory yang diekspor melalui + `openclaw/plugin-sdk/memory-host-core` alih-alih menjangkau layout privat + plugin memory tertentu. - `registerMemoryPromptSection`, `registerMemoryFlushPlan`, dan - `registerMemoryRuntime` adalah API plugin memori eksklusif yang kompatibel dengan versi lama. -- `registerMemoryEmbeddingProvider` memungkinkan plugin memori aktif mendaftarkan satu - atau lebih id adapter embedding (misalnya `openai`, `gemini`, atau id yang ditentukan plugin secara kustom). -- Config pengguna seperti `agents.defaults.memorySearch.provider` dan - `agents.defaults.memorySearch.fallback` diselesaikan terhadap id adapter yang terdaftar tersebut. + `registerMemoryRuntime` adalah API plugin memory eksklusif yang kompatibel dengan versi lama. +- `registerMemoryEmbeddingProvider` memungkinkan plugin memory aktif mendaftarkan satu + atau lebih id adapter embedding (misalnya `openai`, `gemini`, atau id khusus plugin kustom). +- Konfigurasi pengguna seperti `agents.defaults.memorySearch.provider` dan + `agents.defaults.memorySearch.fallback` diselesaikan terhadap id adapter terdaftar tersebut. ### Event dan siklus hidup -| Method | Fungsinya | +| Metode | Fungsinya | | -------------------------------------------- | ----------------------------- | -| `api.on(hookName, handler, opts?)` | Hook siklus hidup bertipe | -| `api.onConversationBindingResolved(handler)` | Callback binding percakapan | +| `api.on(hookName, handler, opts?)` | Hook siklus hidup bertipe | +| `api.onConversationBindingResolved(handler)` | Callback pengikatan percakapan | ### Semantik keputusan hook -- `before_tool_call`: mengembalikan `{ block: true }` bersifat terminal. Setelah handler mana pun menetapkannya, handler dengan prioritas lebih rendah dilewati. +- `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 menghilangkan `block`), bukan sebagai override. -- `before_install`: mengembalikan `{ block: true }` bersifat terminal. Setelah handler mana pun menetapkannya, handler dengan prioritas lebih rendah dilewati. +- `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 menghilangkan `block`), bukan sebagai override. -- `reply_dispatch`: mengembalikan `{ handled: true, ... }` bersifat terminal. Setelah handler mana pun mengklaim dispatch, handler dengan prioritas lebih rendah dan jalur dispatch model default dilewati. -- `message_sending`: mengembalikan `{ cancel: true }` bersifat terminal. Setelah handler mana pun menetapkannya, handler dengan prioritas lebih rendah dilewati. +- `reply_dispatch`: mengembalikan `{ handled: true, ... }` bersifat terminal. Setelah ada handler yang mengklaim dispatch, handler prioritas lebih rendah dan jalur dispatch model default 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 menghilangkan `cancel`), bukan sebagai override. ### Field objek API -| Field | Type | Deskripsi | +| Field | Tipe | Deskripsi | | ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | | `api.id` | `string` | Id plugin | | `api.name` | `string` | Nama tampilan | -| `api.version` | `string?` | Versi plugin (opsional) | -| `api.description` | `string?` | Deskripsi plugin (opsional) | +| `api.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 dalam memori yang 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 berpencakupan (`debug`, `info`, `warn`, `error`) | +| `api.config` | `OpenClawConfig` | Snapshot konfigurasi saat ini (snapshot runtime dalam memori yang aktif jika tersedia) | +| `api.pluginConfig` | `Record` | Konfigurasi 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 pemuatan saat ini; `"setup-runtime"` adalah jendela startup/setup ringan sebelum entri penuh | -| `api.resolvePath(input)` | `(string) => string` | Menyelesaikan path relatif terhadap root plugin | +| `api.resolvePath(input)` | `(string) => string` | Menyelesaikan path relatif terhadap root plugin | ## Konvensi modul internal @@ -462,49 +462,49 @@ Di dalam plugin Anda, gunakan file barrel lokal untuk impor internal: ``` my-plugin/ - api.ts # Ekspor publik untuk konsumen eksternal - runtime-api.ts # Ekspor runtime khusus internal - index.ts # Entry point plugin - setup-entry.ts # Entri setup ringan saja (opsional) + api.ts # Export publik untuk konsumen eksternal + runtime-api.ts # Export runtime khusus internal + index.ts # Titik masuk plugin + setup-entry.ts # Entri ringan khusus setup (opsional) ``` Jangan pernah mengimpor plugin Anda sendiri melalui `openclaw/plugin-sdk/` - dari kode production. Arahkan impor 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 plugin bawaan yang dimuat melalui fasad (`api.ts`, `runtime-api.ts`, -`index.ts`, `setup-entry.ts`, dan file entri publik serupa) kini mengutamakan -snapshot config runtime aktif saat OpenClaw sudah berjalan. Jika snapshot runtime -belum ada, permukaan tersebut akan fallback ke file config di disk yang telah diselesaikan. +Surface publik plugin bawaan yang dimuat melalui facade (`api.ts`, `runtime-api.ts`, +`index.ts`, `setup-entry.ts`, dan file entri publik serupa) kini memilih +snapshot konfigurasi runtime aktif saat OpenClaw sudah berjalan. Jika snapshot runtime +belum ada, surface tersebut menggunakan fallback ke file konfigurasi ter-resolve di disk. -Plugin provider juga dapat mengekspos barrel kontrak lokal plugin yang sempit ketika suatu -helper memang khusus provider dan belum cocok ditempatkan 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 logika header beta Anthropic dan `service_tier` ke dalam kontrak -`plugin-sdk/*` generik. +Plugin penyedia juga dapat mengekspos barrel kontrak lokal plugin yang sempit ketika sebuah +helper memang khusus penyedia dan belum layak dimasukkan ke subpath SDK generik. +Contoh bawaan saat ini: penyedia Anthropic menyimpan helper stream Claude di seam +publik `api.ts` / `contract-api.ts` miliknya sendiri alih-alih mempromosikan logika +header beta Anthropic dan `service_tier` ke kontrak generik +`plugin-sdk/*`. -Contoh bawaan lain 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 - helper onboarding/config +- `@openclaw/openai-provider`: `api.ts` mengekspor builder penyedia, + helper model default, dan builder penyedia realtime +- `@openclaw/openrouter-provider`: `api.ts` mengekspor builder penyedia plus + helper onboarding/konfigurasi - Kode production extension juga harus menghindari impor `openclaw/plugin-sdk/`. - Jika suatu helper benar-benar dibagikan, promosikan helper tersebut ke subpath SDK netral - seperti `openclaw/plugin-sdk/speech`, `.../provider-model-shared`, atau - permukaan berorientasi kapabilitas lainnya alih-alih memasangkan dua plugin secara langsung. + Kode produksi extension juga harus 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 surface + berorientasi kapabilitas lainnya alih-alih menggabungkan dua plugin secara erat. ## Terkait -- [Entry Points](/id/plugins/sdk-entrypoints) — opsi `definePluginEntry` dan `defineChannelPluginEntry` -- [Runtime Helpers](/id/plugins/sdk-runtime) — referensi namespace `api.runtime` lengkap -- [Setup and Config](/id/plugins/sdk-setup) — packaging, manifes, skema config -- [Testing](/id/plugins/sdk-testing) — utilitas pengujian dan aturan lint -- [SDK Migration](/id/plugins/sdk-migration) — migrasi dari permukaan yang sudah usang -- [Plugin Internals](/id/plugins/architecture) — arsitektur mendalam dan model kapabilitas +- [Titik Entri](/id/plugins/sdk-entrypoints) — opsi `definePluginEntry` dan `defineChannelPluginEntry` +- [Helper Runtime](/id/plugins/sdk-runtime) — referensi lengkap namespace `api.runtime` +- [Setup dan Konfigurasi](/id/plugins/sdk-setup) — packaging, manifes, skema konfigurasi +- [Pengujian](/id/plugins/sdk-testing) — utilitas pengujian dan aturan lint +- [Migrasi SDK](/id/plugins/sdk-migration) — migrasi dari surface yang deprecated +- [Internal Plugin](/id/plugins/architecture) — arsitektur mendalam dan model kapabilitas diff --git a/docs/id/plugins/sdk-provider-plugins.md b/docs/id/plugins/sdk-provider-plugins.md index 16c6c1fc4..2bd885ee9 100644 --- a/docs/id/plugins/sdk-provider-plugins.md +++ b/docs/id/plugins/sdk-provider-plugins.md @@ -1,29 +1,29 @@ --- read_when: - - Anda sedang membangun plugin penyedia model baru + - Anda sedang membangun plugin provider model baru - Anda ingin menambahkan proxy yang kompatibel dengan OpenAI atau LLM kustom ke OpenClaw - - Anda perlu memahami autentikasi provider, katalog, dan hook runtime + - Anda perlu memahami auth provider, katalog, dan hook runtime sidebarTitle: Provider Plugins -summary: Panduan langkah demi langkah untuk membangun plugin penyedia model untuk OpenClaw +summary: Panduan langkah demi langkah untuk membangun plugin provider model untuk OpenClaw title: Membangun Plugin Provider x-i18n: - generated_at: "2026-04-07T09:18:38Z" + generated_at: "2026-04-09T01:30:17Z" model: gpt-5.4 provider: openai - source_hash: 4da82a353e1bf4fe6dc09e14b8614133ac96565679627de51415926014bd3990 + source_hash: 38d9af522dc19e49c81203a83a4096f01c2398b1df771c848a30ad98f251e9e1 source_path: plugins/sdk-provider-plugins.md workflow: 15 --- # Membangun Plugin Provider -Panduan ini memandu Anda melalui pembangunan plugin provider yang menambahkan provider model -(LLM) ke OpenClaw. Di akhir panduan, Anda akan memiliki provider dengan katalog model, -autentikasi kunci API, dan resolusi model dinamis. +Panduan ini memandu Anda membangun plugin provider yang menambahkan provider model +(LLM) ke OpenClaw. Pada akhirnya Anda akan memiliki provider dengan katalog model, +auth API key, dan resolusi model dinamis. - Jika Anda belum pernah membuat plugin OpenClaw sebelumnya, baca - [Memulai](/id/plugins/building-plugins) terlebih dahulu untuk struktur paket + Jika Anda belum pernah membangun plugin OpenClaw sebelumnya, baca + [Getting Started](/id/plugins/building-plugins) terlebih dahulu untuk struktur paket dasar dan penyiapan manifest. @@ -65,6 +65,9 @@ autentikasi kunci API, dan resolusi model dinamis. "providerAuthEnvVars": { "acme-ai": ["ACME_AI_API_KEY"] }, + "providerAuthAliases": { + "acme-ai-coding": "acme-ai" + }, "providerAuthChoices": [ { "provider": "acme-ai", @@ -87,9 +90,10 @@ autentikasi kunci API, dan resolusi model dinamis. Manifest mendeklarasikan `providerAuthEnvVars` agar OpenClaw dapat mendeteksi - kredensial tanpa memuat runtime plugin Anda. `modelSupport` bersifat opsional - dan memungkinkan OpenClaw memuat otomatis plugin provider Anda dari ID model singkat - seperti `acme-large` sebelum hook runtime tersedia. Jika Anda memublikasikan + kredensial tanpa memuat runtime plugin Anda. Tambahkan `providerAuthAliases` + saat sebuah varian provider harus menggunakan ulang auth milik id provider lain. `modelSupport` + bersifat opsional dan memungkinkan OpenClaw memuat otomatis plugin provider Anda dari shorthand + model id seperti `acme-large` sebelum hook runtime tersedia. Jika Anda menerbitkan provider di ClawHub, field `openclaw.compat` dan `openclaw.build` tersebut wajib ada di `package.json`. @@ -171,8 +175,8 @@ autentikasi kunci API, dan resolusi model dinamis. `openclaw onboard --acme-ai-api-key ` dan memilih `acme-ai/acme-large` sebagai model mereka. - Untuk provider bawaan yang hanya mendaftarkan satu provider teks dengan autentikasi - kunci API ditambah satu runtime berbasis katalog, gunakan helper yang lebih sempit + Untuk provider bawaan yang hanya mendaftarkan satu provider teks dengan API-key + auth ditambah satu runtime berbasis katalog, pilih helper yang lebih sempit `defineSingleProviderPluginEntry(...)`: ```typescript @@ -208,30 +212,30 @@ autentikasi kunci API, dan resolusi model dinamis. }); ``` - Jika alur autentikasi Anda juga perlu menambal `models.providers.*`, alias, dan + Jika alur auth Anda juga perlu menambal `models.providers.*`, alias, dan model default agen selama onboarding, gunakan helper preset dari `openclaw/plugin-sdk/provider-onboard`. Helper yang paling sempit adalah `createDefaultModelPresetAppliers(...)`, `createDefaultModelsPresetAppliers(...)`, dan `createModelCatalogPresetAppliers(...)`. - Ketika endpoint native suatu provider mendukung blok penggunaan yang di-streaming pada - transport `openai-completions` normal, gunakan helper katalog bersama di + Saat endpoint native provider mendukung blok usage streaming pada + transport `openai-completions` normal, pilih helper katalog bersama di `openclaw/plugin-sdk/provider-catalog-shared` alih-alih melakukan hardcode pemeriksaan provider-id. `supportsNativeStreamingUsageCompat(...)` dan - `applyProviderNativeStreamingUsageCompat(...)` mendeteksi dukungan dari peta kapabilitas - endpoint, sehingga endpoint native bergaya Moonshot/DashScope tetap ikut serta - bahkan ketika plugin menggunakan provider id kustom. + `applyProviderNativeStreamingUsageCompat(...)` mendeteksi dukungan dari + peta kapabilitas endpoint, sehingga endpoint native bergaya Moonshot/DashScope tetap + ikut serta meskipun plugin menggunakan id provider kustom. - Jika provider Anda menerima ID model arbitrer (seperti proxy atau router), + Jika provider Anda menerima model ID arbitrer (seperti proxy atau router), tambahkan `resolveDynamicModel`: ```typescript api.registerProvider({ - // ... id, label, auth, catalog from above + // ... id, label, auth, dan catalog dari atas resolveDynamicModel: (ctx) => ({ id: ctx.modelId, @@ -249,7 +253,7 @@ autentikasi kunci API, dan resolusi model dinamis. ``` Jika resolusi memerlukan panggilan jaringan, gunakan `prepareDynamicModel` untuk - pemanasan asinkron — `resolveDynamicModel` akan dijalankan lagi setelah itu selesai. + warm-up async — `resolveDynamicModel` berjalan lagi setelah itu selesai. @@ -283,10 +287,10 @@ autentikasi kunci API, dan resolusi model dinamis. | Family | Yang dihubungkan | | --- | --- | | `openai-compatible` | Kebijakan replay bergaya OpenAI bersama untuk transport yang kompatibel dengan OpenAI, termasuk sanitasi tool-call-id, perbaikan urutan assistant-first, dan validasi turn Gemini generik saat transport memerlukannya | - | `anthropic-by-model` | Kebijakan replay sadar-Claude yang dipilih berdasarkan `modelId`, sehingga transport Anthropic-message hanya mendapatkan pembersihan blok thinking khusus Claude saat model yang di-resolve benar-benar merupakan id Claude | - | `google-gemini` | Kebijakan replay Gemini native plus sanitasi replay bootstrap dan mode output reasoning bertag | + | `anthropic-by-model` | Kebijakan replay sadar-Claude yang dipilih berdasarkan `modelId`, sehingga transport pesan Anthropic hanya menerima pembersihan thinking-block spesifik Claude saat model yang di-resolve benar-benar merupakan id Claude | + | `google-gemini` | Kebijakan replay Gemini native ditambah sanitasi replay bootstrap dan mode reasoning-output bertag | | `passthrough-gemini` | Sanitasi thought-signature Gemini untuk model Gemini yang berjalan melalui transport proxy yang kompatibel dengan OpenAI; tidak mengaktifkan validasi replay Gemini native atau penulisan ulang bootstrap | - | `hybrid-anthropic-openai` | Kebijakan hibrida untuk provider yang mencampurkan permukaan model Anthropic-message dan OpenAI-compatible dalam satu plugin; penghapusan blok thinking opsional yang hanya untuk Claude tetap dibatasi pada sisi Anthropic | + | `hybrid-anthropic-openai` | Kebijakan hybrid untuk provider yang mencampurkan permukaan model pesan Anthropic dan yang kompatibel dengan OpenAI dalam satu plugin; penghapusan thinking-block khusus Claude yang opsional tetap dibatasi ke sisi Anthropic | Contoh bawaan nyata: @@ -300,13 +304,13 @@ autentikasi kunci API, dan resolusi model dinamis. | Family | Yang dihubungkan | | --- | --- | - | `google-thinking` | Normalisasi payload thinking Gemini pada jalur stream bersama | - | `kilocode-thinking` | Wrapper reasoning Kilo pada jalur stream proxy bersama, dengan `kilo/auto` dan reasoning id proxy yang tidak didukung melewati thinking yang disuntikkan | - | `moonshot-thinking` | Pemetaan payload native-thinking biner Moonshot dari konfigurasi + level `/think` | - | `minimax-fast-mode` | Penulisan ulang model fast-mode MiniMax pada jalur stream bersama | - | `openai-responses-defaults` | Wrapper native OpenAI/Codex Responses bersama: header atribusi, `/fast`/`serviceTier`, verbositas teks, pencarian web Codex native, pembentukan payload kompatibilitas reasoning, dan pengelolaan konteks Responses | - | `openrouter-thinking` | Wrapper reasoning OpenRouter untuk rute proxy, dengan lompatan unsupported-model/`auto` ditangani secara terpusat | - | `tool-stream-default-on` | Wrapper `tool_stream` aktif secara default untuk provider seperti Z.AI yang menginginkan streaming tool kecuali dinonaktifkan secara eksplisit | + | `google-thinking` | Normalisasi payload thinking Gemini pada path stream bersama | + | `kilocode-thinking` | Wrapper reasoning Kilo pada path stream proxy bersama, dengan `kilo/auto` dan id reasoning proxy yang tidak didukung melewati thinking yang diinjeksi | + | `moonshot-thinking` | Pemetaan payload native-thinking biner Moonshot dari config + level `/think` | + | `minimax-fast-mode` | Penulisan ulang model fast-mode MiniMax pada path stream bersama | + | `openai-responses-defaults` | Wrapper native OpenAI/Codex Responses bersama: attribution headers, `/fast`/`serviceTier`, text verbosity, web search Codex native, pembentukan payload reasoning-compat, dan manajemen konteks Responses | + | `openrouter-thinking` | Wrapper reasoning OpenRouter untuk route proxy, dengan skip unsupported-model/`auto` ditangani secara terpusat | + | `tool-stream-default-on` | Wrapper `tool_stream` default aktif untuk provider seperti Z.AI yang menginginkan tool streaming kecuali dinonaktifkan secara eksplisit | Contoh bawaan nyata: @@ -319,8 +323,8 @@ autentikasi kunci API, dan resolusi model dinamis. - `zai`: `tool-stream-default-on` `openclaw/plugin-sdk/provider-model-shared` juga mengekspor enum replay-family - beserta helper bersama yang menjadi dasar keluarga tersebut. Ekspor publik - yang umum mencakup: + plus helper bersama yang menjadi dasar keluarga tersebut. Ekspor publik yang umum + mencakup: - `ProviderReplayFamily` - `buildProviderReplayFamilyHooks(...)` @@ -334,9 +338,9 @@ autentikasi kunci API, dan resolusi model dinamis. `normalizeProviderId(...)`, `normalizeGooglePreviewModelId(...)`, dan `normalizeNativeXaiModelId(...)` - `openclaw/plugin-sdk/provider-stream` mengekspor builder family dan - helper wrapper publik yang digunakan kembali oleh family tersebut. Ekspor publik - yang umum mencakup: + `openclaw/plugin-sdk/provider-stream` mengekspos builder keluarga dan + helper wrapper publik yang digunakan ulang oleh keluarga tersebut. Ekspor publik umum + mencakup: - `ProviderStreamFamily` - `buildProviderStreamFamilyHooks(...)` @@ -354,41 +358,41 @@ autentikasi kunci API, dan resolusi model dinamis. saat ini: `@openclaw/anthropic-provider` mengekspor `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier`, dan - builder wrapper Anthropic tingkat lebih rendah dari seam publik `api.ts` / + builder wrapper Anthropic level rendah dari seam publik `api.ts` / `contract-api.ts`. Helper tersebut tetap spesifik Anthropic karena - juga mengenkode penanganan beta OAuth Claude dan gating `context1m`. + juga mengodekan penanganan beta Claude OAuth dan gating `context1m`. - Provider bawaan lain juga mempertahankan wrapper spesifik transport secara lokal ketika - perilakunya tidak dapat dibagikan secara bersih antar family. Contoh saat ini: plugin xAI - bawaan menyimpan pembentukan Responses xAI native dalam + Provider bawaan lain juga menjaga wrapper spesifik transport tetap lokal saat + perilakunya tidak dapat dibagikan dengan bersih lintas keluarga. Contoh saat ini: plugin xAI + bawaan menyimpan pembentukan Responses xAI native di `wrapStreamFn` miliknya sendiri, termasuk penulisan ulang alias `/fast`, `tool_stream` default, pembersihan strict-tool yang tidak didukung, dan penghapusan payload reasoning khusus xAI. - `openclaw/plugin-sdk/provider-tools` saat ini mengekspos satu family - schema tool bersama plus helper schema/compat bersama: + `openclaw/plugin-sdk/provider-tools` saat ini mengekspos satu + keluarga tool-schema bersama plus helper schema/compat bersama: - - `ProviderToolCompatFamily` mendokumentasikan inventaris family bersama saat ini. - - `buildProviderToolCompatFamilyHooks("gemini")` menghubungkan pembersihan - schema Gemini + diagnostik untuk provider yang memerlukan schema tool aman-Gemini. + - `ProviderToolCompatFamily` mendokumentasikan inventaris keluarga bersama saat ini. + - `buildProviderToolCompatFamilyHooks("gemini")` menghubungkan pembersihan schema Gemini + + diagnostik untuk provider yang memerlukan schema tool yang aman untuk Gemini. - `normalizeGeminiToolSchemas(...)` dan `inspectGeminiToolSchemas(...)` adalah helper schema Gemini publik yang mendasarinya. - - `resolveXaiModelCompatPatch()` mengembalikan patch kompatibilitas xAI bawaan: + - `resolveXaiModelCompatPatch()` mengembalikan patch compat xAI bawaan: `toolSchemaProfile: "xai"`, keyword schema yang tidak didukung, dukungan `web_search` native, dan dekode argumen tool-call entitas HTML. - - `applyXaiModelCompat(model)` menerapkan patch kompatibilitas xAI yang sama ke model - yang sudah di-resolve sebelum mencapai runner. + - `applyXaiModelCompat(model)` menerapkan patch compat xAI yang sama itu pada + model yang di-resolve sebelum mencapai runner. Contoh bawaan nyata: plugin xAI menggunakan `normalizeResolvedModel` plus - `contributeResolvedModelCompat` untuk menjaga metadata kompatibilitas itu tetap dimiliki oleh + `contributeResolvedModelCompat` untuk menjaga metadata compat itu tetap dimiliki oleh provider alih-alih melakukan hardcode aturan xAI di core. - Pola package-root yang sama juga mendasari provider bawaan lainnya: + Pola package-root yang sama juga mendukung provider bawaan 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 helper onboarding/konfigurasi + plus helper onboarding/config @@ -409,7 +413,7 @@ autentikasi kunci API, dan resolusi model dinamis. Untuk provider yang memerlukan header permintaan kustom atau modifikasi body: ```typescript - // wrapStreamFn returns a StreamFn derived from ctx.streamFn + // wrapStreamFn mengembalikan StreamFn yang diturunkan dari ctx.streamFn wrapStreamFn: (ctx) => { if (!ctx.streamFn) return undefined; const inner = ctx.streamFn; @@ -424,7 +428,7 @@ autentikasi kunci API, dan resolusi model dinamis. ``` - Untuk provider yang memerlukan header atau metadata permintaan/sesi native pada + Untuk provider yang memerlukan header atau metadata request/session native pada transport HTTP atau WebSocket generik: ```typescript @@ -445,8 +449,8 @@ autentikasi kunci API, dan resolusi model dinamis. }), ``` - - Untuk provider yang mengekspos data penggunaan/penagihan: + + Untuk provider yang mengekspos data usage/penagihan: ```typescript resolveUsageAuth: async (ctx) => { @@ -465,69 +469,70 @@ autentikasi kunci API, dan resolusi model dinamis. | # | Hook | Kapan digunakan | | --- | --- | --- | - | 1 | `catalog` | Katalog model atau default `baseUrl` | + | 1 | `catalog` | Katalog model atau default base URL | | 2 | `applyConfigDefaults` | Default global milik provider selama materialisasi konfigurasi | - | 3 | `normalizeModelId` | Pembersihan alias model-id legacy/preview sebelum pencarian | - | 4 | `normalizeTransport` | Pembersihan `api` / `baseUrl` family-provider sebelum perakitan model generik | - | 5 | `normalizeConfig` | Normalisasi konfigurasi `models.providers.` | - | 6 | `applyNativeStreamingUsageCompat` | Penulisan ulang kompatibilitas streaming-usage native untuk provider konfigurasi | - | 7 | `resolveConfigApiKey` | Resolusi autentikasi env-marker milik provider | - | 8 | `resolveSyntheticAuth` | Autentikasi sintetis berbasis lokal/self-hosted atau konfigurasi | - | 9 | `shouldDeferSyntheticProfileAuth` | Menurunkan placeholder profil tersimpan sintetis di bawah autentikasi env/config | - | 10 | `resolveDynamicModel` | Menerima ID model upstream arbitrer | - | 11 | `prepareDynamicModel` | Pengambilan metadata asinkron sebelum resolusi | + | 3 | `normalizeModelId` | Pembersihan alias model-id lama/pratinjau sebelum lookup | + | 4 | `normalizeTransport` | Pembersihan `api` / `baseUrl` keluarga provider sebelum perakitan model generik | + | 5 | `normalizeConfig` | Menormalisasi konfigurasi `models.providers.` | + | 6 | `applyNativeStreamingUsageCompat` | Penulisan ulang compat streaming-usage native untuk provider config | + | 7 | `resolveConfigApiKey` | Resolusi auth env-marker milik provider | + | 8 | `resolveSyntheticAuth` | Auth sintetis lokal/self-hosted atau berbasis config | + | 9 | `shouldDeferSyntheticProfileAuth` | Turunkan placeholder profil tersimpan sintetis di bawah auth env/config | + | 10 | `resolveDynamicModel` | Menerima model ID upstream arbitrer | + | 11 | `prepareDynamicModel` | Pengambilan metadata async sebelum resolusi | | 12 | `normalizeResolvedModel` | Penulisan ulang transport sebelum runner | - Catatan fallback runtime: + Catatan fallback runtime: - - `normalizeConfig` memeriksa provider yang cocok terlebih dahulu, lalu plugin provider lain - yang mendukung hook sampai salah satunya benar-benar mengubah konfigurasi. - Jika tidak ada hook provider yang menulis ulang entri konfigurasi keluarga Google yang didukung, normalizer konfigurasi Google bawaan - tetap diterapkan. - - `resolveConfigApiKey` menggunakan hook provider jika diekspos. Jalur bawaan - `amazon-bedrock` juga memiliki resolver env-marker AWS bawaan di sini, - meskipun autentikasi runtime Bedrock sendiri masih menggunakan rantai default AWS SDK. - | 13 | `contributeResolvedModelCompat` | Flag kompatibilitas untuk model vendor di balik transport kompatibel lainnya | - | 14 | `capabilities` | Kantong kapabilitas statis legacy; hanya untuk kompatibilitas | - | 15 | `normalizeToolSchemas` | Pembersihan schema tool milik provider sebelum pendaftaran | - | 16 | `inspectToolSchemas` | Diagnostik schema tool milik provider | - | 17 | `resolveReasoningOutputMode` | Kontrak output reasoning bertag vs native | - | 18 | `prepareExtraParams` | Parameter permintaan default | + - `normalizeConfig` memeriksa provider yang cocok terlebih dahulu, lalu + plugin provider lain yang mampu menangani hook sampai salah satunya benar-benar + mengubah konfigurasi. + Jika tidak ada hook provider yang menulis ulang entri konfigurasi keluarga Google yang didukung, + normalizer konfigurasi Google bawaan tetap diterapkan. + - `resolveConfigApiKey` menggunakan hook provider saat diekspos. Path bawaan + `amazon-bedrock` juga memiliki resolver env-marker AWS bawaan di sini, + meskipun auth runtime Bedrock sendiri masih menggunakan rantai default AWS SDK. + | 13 | `contributeResolvedModelCompat` | Flag compat untuk model vendor di balik transport kompatibel lain | + | 14 | `capabilities` | Kumpulan kapabilitas statis lama; hanya untuk kompatibilitas | + | 15 | `normalizeToolSchemas` | Pembersihan tool-schema milik provider sebelum registrasi | + | 16 | `inspectToolSchemas` | Diagnostik tool-schema milik provider | + | 17 | `resolveReasoningOutputMode` | Kontrak reasoning-output bertag vs native | + | 18 | `prepareExtraParams` | Parameter request default | | 19 | `createStreamFn` | Transport StreamFn kustom sepenuhnya | - | 20 | `wrapStreamFn` | Wrapper header/body kustom pada jalur stream normal | + | 20 | `wrapStreamFn` | Wrapper header/body kustom pada path stream normal | | 21 | `resolveTransportTurnState` | Header/metadata native per-turn | - | 22 | `resolveWebSocketSessionPolicy` | Header sesi WS native/cool-down | + | 22 | `resolveWebSocketSessionPolicy` | Header/cool-down sesi WS native | | 23 | `formatApiKey` | Bentuk token runtime kustom | | 24 | `refreshOAuth` | Refresh OAuth kustom | - | 25 | `buildAuthDoctorHint` | Panduan perbaikan autentikasi | + | 25 | `buildAuthDoctorHint` | Panduan perbaikan auth | | 26 | `matchesContextOverflowError` | Deteksi overflow milik provider | | 27 | `classifyFailoverReason` | Klasifikasi rate-limit/overload milik provider | | 28 | `isCacheTtlEligible` | Gating TTL cache prompt | - | 29 | `buildMissingAuthMessage` | Petunjuk ketiadaan autentikasi kustom | + | 29 | `buildMissingAuthMessage` | Petunjuk auth yang hilang kustom | | 30 | `suppressBuiltInModel` | Sembunyikan baris upstream usang | - | 31 | `augmentModelCatalog` | Baris sintetis forward-compat | - | 32 | `isBinaryThinking` | Thinking biner hidup/mati | + | 31 | `augmentModelCatalog` | Baris kompatibilitas maju sintetis | + | 32 | `isBinaryThinking` | Thinking biner aktif/nonaktif | | 33 | `supportsXHighThinking` | Dukungan reasoning `xhigh` | | 34 | `resolveDefaultThinkingLevel` | Kebijakan default `/think` | | 35 | `isModernModelRef` | Pencocokan model live/smoke | | 36 | `prepareRuntimeAuth` | Pertukaran token sebelum inferensi | - | 37 | `resolveUsageAuth` | Penguraian kredensial penggunaan kustom | - | 38 | `fetchUsageSnapshot` | Endpoint penggunaan kustom | - | 39 | `createEmbeddingProvider` | Adapter embedding milik provider untuk memori/pencarian | + | 37 | `resolveUsageAuth` | Parsing kredensial usage kustom | + | 38 | `fetchUsageSnapshot` | Endpoint usage kustom | + | 39 | `createEmbeddingProvider` | Adapter embedding milik provider untuk memory/search | | 40 | `buildReplayPolicy` | Kebijakan replay/pemadatan transkrip kustom | | 41 | `sanitizeReplayHistory` | Penulisan ulang replay spesifik provider setelah pembersihan generik | - | 42 | `validateReplayTurns` | Validasi replay-turn ketat sebelum runner tersemat | - | 43 | `onModelSelected` | Callback pasca-pemilihan (mis. telemetri) | + | 42 | `validateReplayTurns` | Validasi replay-turn ketat sebelum runner tertanam | + | 43 | `onModelSelected` | Callback pasca-pemilihan (misalnya telemetri) | - Catatan penyetelan prompt: + Catatan tuning prompt: - `resolveSystemPromptContribution` memungkinkan provider menyuntikkan - panduan system-prompt yang sadar-cache untuk family model. Utamakan ini dibanding - `before_prompt_build` ketika perilaku tersebut dimiliki oleh satu family provider/model - dan harus mempertahankan pemisahan cache stabil/dinamis. + panduan system-prompt yang sadar-cache untuk keluarga model. Pilih ini alih-alih + `before_prompt_build` saat perilaku tersebut milik satu keluarga provider/model + dan harus mempertahankan pemisahan cache stable/dynamic yang stabil. - Untuk deskripsi mendetail dan contoh dunia nyata, lihat - [Internal: Hook Runtime Provider](/id/plugins/architecture#provider-runtime-hooks). + Untuk deskripsi terperinci dan contoh dunia nyata, lihat + [Internals: Provider Runtime Hooks](/id/plugins/architecture#provider-runtime-hooks). @@ -536,7 +541,7 @@ autentikasi kunci API, dan resolusi model dinamis. Plugin provider dapat mendaftarkan speech, transkripsi realtime, voice realtime, pemahaman media, pembuatan gambar, pembuatan video, web fetch, - dan web search di samping inferensi teks: + dan web search bersama inferensi teks: ```typescript register(api) { @@ -646,18 +651,18 @@ autentikasi kunci API, dan resolusi model dinamis. OpenClaw mengklasifikasikan ini sebagai plugin **hybrid-capability**. Ini adalah pola yang direkomendasikan untuk plugin perusahaan (satu plugin per vendor). Lihat - [Internal: Kepemilikan Kapabilitas](/id/plugins/architecture#capability-ownership-model). + [Internals: Capability Ownership](/id/plugins/architecture#capability-ownership-model). - Untuk pembuatan video, utamakan bentuk kapabilitas yang sadar-mode seperti ditunjukkan di atas: + Untuk pembuatan video, pilih bentuk kapabilitas yang sadar mode seperti ditunjukkan di atas: `generate`, `imageToVideo`, dan `videoToVideo`. Field agregat datar seperti `maxInputImages`, `maxInputVideos`, dan `maxDurationSeconds` tidak - cukup untuk mengiklankan dukungan mode transformasi atau mode yang dinonaktifkan dengan rapi. + cukup untuk mengiklankan dukungan mode transform atau mode yang dinonaktifkan dengan jelas. Provider pembuatan musik harus mengikuti pola yang sama: `generate` untuk pembuatan berbasis prompt saja dan `edit` untuk pembuatan berbasis gambar referensi. Field agregat datar seperti `maxInputImages`, - `supportsLyrics`, dan `supportsFormat` tidak cukup untuk mengiklankan - dukungan edit; blok `generate` / `edit` eksplisit adalah kontrak yang diharapkan. + `supportsLyrics`, dan `supportsFormat` tidak cukup untuk mengiklankan dukungan + edit; blok `generate` / `edit` eksplisit adalah kontrak yang diharapkan. @@ -665,7 +670,7 @@ autentikasi kunci API, dan resolusi model dinamis. ```typescript src/provider.test.ts import { describe, it, expect } from "vitest"; - // Export your provider config object from index.ts or a dedicated file + // Ekspor objek konfigurasi provider Anda dari index.ts atau file khusus import { acmeProvider } from "./provider.js"; describe("acme-ai provider", () => { @@ -696,16 +701,16 @@ autentikasi kunci API, dan resolusi model dinamis. -## Publikasikan ke ClawHub +## Terbitkan ke ClawHub -Plugin provider dipublikasikan dengan cara yang sama seperti plugin kode eksternal lainnya: +Plugin provider diterbitkan dengan cara yang sama seperti plugin kode eksternal lainnya: ```bash clawhub package publish your-org/your-plugin --dry-run clawhub package publish your-org/your-plugin ``` -Jangan gunakan alias publish legacy yang hanya untuk skill di sini; paket plugin harus menggunakan +Jangan gunakan alias publish lama yang khusus Skills di sini; paket plugin harus menggunakan `clawhub package publish`. ## Struktur file @@ -713,11 +718,11 @@ Jangan gunakan alias publish legacy yang hanya untuk skill di sini; paket plugin ``` /acme-ai/ ├── package.json # metadata openclaw.providers -├── openclaw.plugin.json # Manifest dengan providerAuthEnvVars +├── openclaw.plugin.json # Manifest dengan metadata auth provider ├── index.ts # definePluginEntry + registerProvider └── src/ - ├── provider.test.ts # Pengujian - └── usage.ts # Endpoint penggunaan (opsional) + ├── provider.test.ts # Tes + └── usage.ts # Endpoint usage (opsional) ``` ## Referensi urutan katalog @@ -727,14 +732,14 @@ provider bawaan: | Order | Kapan | Kasus penggunaan | | --------- | ------------- | ---------------------------------------------- | -| `simple` | Lintasan awal | Provider kunci API biasa | -| `profile` | Setelah simple | Provider yang digating oleh profil autentikasi | -| `paired` | Setelah profile | Mensintesis beberapa entri terkait | -| `late` | Lintasan terakhir | Menimpa provider yang ada (menang saat bentrok) | +| `simple` | Pass pertama | Provider API-key biasa | +| `profile` | Setelah simple | Provider yang digating pada profil auth | +| `paired` | Setelah profile | Menyintesis beberapa entri terkait | +| `late` | Pass terakhir | Menimpa provider yang ada (menang saat bentrok) | ## Langkah berikutnya -- [Plugin Channel](/id/plugins/sdk-channel-plugins) — jika plugin Anda juga menyediakan channel -- [SDK Runtime](/id/plugins/sdk-runtime) — helper `api.runtime` (TTS, pencarian, subagen) -- [Ikhtisar SDK](/id/plugins/sdk-overview) — referensi impor subpath lengkap -- [Internal Plugin](/id/plugins/architecture#provider-runtime-hooks) — detail hook dan contoh bawaan +- [Channel Plugins](/id/plugins/sdk-channel-plugins) — jika plugin Anda juga menyediakan channel +- [SDK Runtime](/id/plugins/sdk-runtime) — helper `api.runtime` (TTS, search, subagent) +- [SDK Overview](/id/plugins/sdk-overview) — referensi impor subpath lengkap +- [Plugin Internals](/id/plugins/architecture#provider-runtime-hooks) — detail hook dan contoh bawaan diff --git a/docs/id/providers/inferrs.md b/docs/id/providers/inferrs.md index d288b23ec..ec10b20b0 100644 --- a/docs/id/providers/inferrs.md +++ b/docs/id/providers/inferrs.md @@ -6,10 +6,10 @@ read_when: summary: Jalankan OpenClaw melalui inferrs (server lokal yang kompatibel dengan OpenAI) title: inferrs x-i18n: - generated_at: "2026-04-08T02:16:58Z" + generated_at: "2026-04-09T01:29:31Z" model: gpt-5.4 provider: openai - source_hash: d84f660d49a682d0c0878707eebe1bc1e83dd115850687076ea3938b9f9c86c6 + source_hash: 03b9d5a9935c75fd369068bacb7807a5308cd0bd74303b664227fb664c3a2098 source_path: providers/inferrs.md workflow: 15 --- @@ -17,11 +17,11 @@ x-i18n: # inferrs [inferrs](https://github.com/ericcurtin/inferrs) dapat menyajikan model lokal di balik -API `/v1` yang kompatibel dengan OpenAI. OpenClaw bekerja dengan `inferrs` melalui jalur -`openai-completions` generik. +API `/v1` yang kompatibel dengan OpenAI. OpenClaw bekerja dengan `inferrs` melalui jalur generik +`openai-completions`. -Saat ini, `inferrs` paling baik diperlakukan sebagai backend OpenAI-compatible self-hosted -kustom, bukan plugin provider OpenClaw khusus. +Saat ini, `inferrs` paling baik diperlakukan sebagai +backend OpenAI-compatible self-hosted kustom, bukan plugin provider OpenClaw khusus. ## Mulai cepat @@ -30,7 +30,7 @@ kustom, bukan plugin provider OpenClaw khusus. Contoh: ```bash -inferrs serve gg-hf-gg/gemma-4-E2B-it \ +inferrs serve google/gemma-4-E2B-it \ --host 127.0.0.1 \ --port 8080 \ --device metal @@ -43,9 +43,9 @@ curl http://127.0.0.1:8080/health curl http://127.0.0.1:8080/v1/models ``` -3. Tambahkan entri provider OpenClaw eksplisit dan arahkan model default Anda ke entri itu. +3. Tambahkan entri provider OpenClaw eksplisit dan arahkan model default Anda ke sana. -## Contoh konfigurasi lengkap +## Contoh config lengkap Contoh ini menggunakan Gemma 4 pada server `inferrs` lokal. @@ -53,9 +53,9 @@ Contoh ini menggunakan Gemma 4 pada server `inferrs` lokal. { agents: { defaults: { - model: { primary: "inferrs/gg-hf-gg/gemma-4-E2B-it" }, + model: { primary: "inferrs/google/gemma-4-E2B-it" }, models: { - "inferrs/gg-hf-gg/gemma-4-E2B-it": { + "inferrs/google/gemma-4-E2B-it": { alias: "Gemma 4 (inferrs)", }, }, @@ -70,7 +70,7 @@ Contoh ini menggunakan Gemma 4 pada server `inferrs` lokal. api: "openai-completions", models: [ { - id: "gg-hf-gg/gemma-4-E2B-it", + id: "google/gemma-4-E2B-it", name: "Gemma 4 E2B (inferrs)", reasoning: false, input: ["text"], @@ -90,10 +90,10 @@ Contoh ini menggunakan Gemma 4 pada server `inferrs` lokal. ## Mengapa `requiresStringContent` penting -Beberapa rute Chat Completions `inferrs` hanya menerima string pada -`messages[].content`, bukan array content-part terstruktur. +Beberapa rute `inferrs` Chat Completions hanya menerima +`messages[].content` berupa string, bukan array bagian-konten terstruktur. -Jika eksekusi OpenClaw gagal dengan error seperti: +Jika proses OpenClaw gagal dengan error seperti: ```text messages[1].content: invalid type: sequence, expected a string @@ -107,14 +107,14 @@ compat: { } ``` -OpenClaw akan meratakan content part teks murni menjadi string biasa sebelum mengirim +OpenClaw akan meratakan bagian konten teks murni menjadi string biasa sebelum mengirim permintaan. -## Gemma dan catatan skema tool +## Gemma dan catatan tentang schema tool -Beberapa kombinasi `inferrs` + Gemma saat ini menerima permintaan -`/v1/chat/completions` langsung yang kecil, tetapi tetap gagal pada giliran runtime agen -OpenClaw penuh. +Beberapa kombinasi `inferrs` + Gemma saat ini menerima permintaan kecil langsung ke +`/v1/chat/completions` tetapi tetap gagal pada giliran runtime agen OpenClaw +penuh. Jika itu terjadi, coba ini terlebih dahulu: @@ -125,12 +125,12 @@ compat: { } ``` -Itu menonaktifkan permukaan skema tool OpenClaw untuk model tersebut dan dapat mengurangi tekanan prompt +Itu menonaktifkan permukaan schema tool OpenClaw untuk model tersebut dan dapat mengurangi tekanan prompt pada backend lokal yang lebih ketat. -Jika permintaan langsung kecil masih berfungsi tetapi giliran agen OpenClaw normal tetap -crash di dalam `inferrs`, masalah yang tersisa biasanya adalah perilaku model/server upstream, -bukan lapisan transport OpenClaw. +Jika permintaan langsung kecil tetap berfungsi tetapi giliran agen OpenClaw normal terus +crash di dalam `inferrs`, masalah yang tersisa biasanya adalah perilaku model/server hulu +daripada lapisan transport OpenClaw. ## Uji smoke manual @@ -139,39 +139,39 @@ Setelah dikonfigurasi, uji kedua lapisan: ```bash curl http://127.0.0.1:8080/v1/chat/completions \ -H 'content-type: application/json' \ - -d '{"model":"gg-hf-gg/gemma-4-E2B-it","messages":[{"role":"user","content":"What is 2 + 2?"}],"stream":false}' + -d '{"model":"google/gemma-4-E2B-it","messages":[{"role":"user","content":"What is 2 + 2?"}],"stream":false}' openclaw infer model run \ - --model inferrs/gg-hf-gg/gemma-4-E2B-it \ + --model inferrs/google/gemma-4-E2B-it \ --prompt "What is 2 + 2? Reply with one short sentence." \ --json ``` -Jika perintah pertama berfungsi tetapi yang kedua gagal, gunakan catatan pemecahan masalah -di bawah. +Jika perintah pertama berhasil tetapi yang kedua gagal, gunakan catatan pemecahan masalah +di bawah ini. ## Pemecahan masalah - `curl /v1/models` gagal: `inferrs` tidak berjalan, tidak dapat dijangkau, atau tidak - terikat pada host/port yang diharapkan. + terikat ke host/port yang diharapkan. - `messages[].content ... expected a string`: setel `compat.requiresStringContent: true`. -- Panggilan `/v1/chat/completions` langsung yang kecil berhasil, tetapi `openclaw infer model run` +- Panggilan langsung `/v1/chat/completions` kecil lolos, tetapi `openclaw infer model run` gagal: coba `compat.supportsTools: false`. -- OpenClaw tidak lagi mendapatkan error skema, tetapi `inferrs` masih crash pada giliran - agen yang lebih besar: perlakukan ini sebagai batasan `inferrs` atau model upstream dan kurangi +- OpenClaw tidak lagi mendapatkan error schema, tetapi `inferrs` masih crash pada + giliran agen yang lebih besar: perlakukan ini sebagai keterbatasan `inferrs` atau model hulu dan kurangi tekanan prompt atau ganti backend/model lokal. -## Perilaku gaya proxy +## Perilaku bergaya proxy -`inferrs` diperlakukan sebagai backend `/v1` gaya proxy yang kompatibel dengan OpenAI, bukan +`inferrs` diperlakukan sebagai backend `/v1` OpenAI-compatible bergaya proxy, bukan endpoint OpenAI native. - pembentukan permintaan khusus OpenAI native tidak berlaku di sini -- tidak ada `service_tier`, tidak ada Responses `store`, tidak ada hint prompt-cache, dan tidak ada +- tidak ada `service_tier`, tidak ada Responses `store`, tidak ada petunjuk prompt-cache, dan tidak ada pembentukan payload kompatibilitas reasoning OpenAI - header atribusi OpenClaw tersembunyi (`originator`, `version`, `User-Agent`) - tidak disisipkan pada base URL `inferrs` kustom + tidak disuntikkan pada base URL `inferrs` kustom ## Lihat juga diff --git a/docs/id/providers/qwen.md b/docs/id/providers/qwen.md index 9b5470003..15cf45ccb 100644 --- a/docs/id/providers/qwen.md +++ b/docs/id/providers/qwen.md @@ -5,10 +5,10 @@ read_when: summary: Gunakan Qwen Cloud melalui provider qwen bawaan OpenClaw title: Qwen x-i18n: - generated_at: "2026-04-06T03:10:43Z" + generated_at: "2026-04-09T01:30:01Z" model: gpt-5.4 provider: openai - source_hash: f175793693ab6a4c3f1f4d42040e673c15faf7603a500757423e9e06977c989d + source_hash: 4786df2cb6ec1ab29d191d012c61dcb0e5468bf0f8561fbbb50eed741efad325 source_path: providers/qwen.md workflow: 15 --- @@ -20,15 +20,15 @@ x-i18n: **Qwen OAuth telah dihapus.** Integrasi OAuth tingkat gratis (`qwen-portal`) yang menggunakan endpoint `portal.qwen.ai` tidak lagi tersedia. Lihat [Issue #49557](https://github.com/openclaw/openclaw/issues/49557) untuk -latar belakangnya. +latar belakang. ## Rekomendasi: Qwen Cloud -OpenClaw sekarang memperlakukan Qwen sebagai provider bawaan kelas satu dengan id kanonis +OpenClaw kini memperlakukan Qwen sebagai provider bawaan kelas satu dengan id kanonis `qwen`. Provider bawaan ini menargetkan endpoint Qwen Cloud / Alibaba DashScope dan -Coding Plan serta tetap mendukung id `modelstudio` lama sebagai +Coding Plan serta menjaga id lama `modelstudio` tetap berfungsi sebagai alias kompatibilitas. - Provider: `qwen` @@ -40,24 +40,24 @@ Jika Anda ingin `qwen3.6-plus`, gunakan endpoint **Standard (pay-as-you-go)**. Dukungan Coding Plan dapat tertinggal dari katalog publik. ```bash -# Global Coding Plan endpoint +# Endpoint Coding Plan Global openclaw onboard --auth-choice qwen-api-key -# China Coding Plan endpoint +# Endpoint Coding Plan China openclaw onboard --auth-choice qwen-api-key-cn -# Global Standard (pay-as-you-go) endpoint +# Endpoint Standard (pay-as-you-go) Global openclaw onboard --auth-choice qwen-standard-api-key -# China Standard (pay-as-you-go) endpoint +# Endpoint Standard (pay-as-you-go) China openclaw onboard --auth-choice qwen-standard-api-key-cn ``` -Id `auth-choice` `modelstudio-*` lama dan referensi model `modelstudio/...` masih -berfungsi sebagai alias kompatibilitas, tetapi alur penyiapan baru sebaiknya menggunakan -id `auth-choice` `qwen-*` kanonis dan referensi model `qwen/...`. +Id `auth-choice` lama `modelstudio-*` dan ref model `modelstudio/...` masih +berfungsi sebagai alias kompatibilitas, tetapi alur setup baru sebaiknya menggunakan +id `auth-choice` kanonis `qwen-*` dan ref model `qwen/...`. -Setelah onboarding, tetapkan model default: +Setelah onboarding, setel model default: ```json5 { @@ -71,22 +71,22 @@ Setelah onboarding, tetapkan model default: ## Jenis paket dan endpoint -| Paket | Wilayah | Auth choice | Endpoint | -| -------------------------- | ------- | -------------------------- | ------------------------------------------------ | -| Standard (pay-as-you-go) | China | `qwen-standard-api-key-cn` | `dashscope.aliyuncs.com/compatible-mode/v1` | -| Standard (pay-as-you-go) | Global | `qwen-standard-api-key` | `dashscope-intl.aliyuncs.com/compatible-mode/v1` | -| Coding Plan (langganan) | China | `qwen-api-key-cn` | `coding.dashscope.aliyuncs.com/v1` | -| Coding Plan (langganan) | Global | `qwen-api-key` | `coding-intl.dashscope.aliyuncs.com/v1` | +| Paket | Wilayah | Pilihan auth | Endpoint | +| -------------------------- | ------ | -------------------------- | ------------------------------------------------ | +| Standard (pay-as-you-go) | China | `qwen-standard-api-key-cn` | `dashscope.aliyuncs.com/compatible-mode/v1` | +| Standard (pay-as-you-go) | Global | `qwen-standard-api-key` | `dashscope-intl.aliyuncs.com/compatible-mode/v1` | +| Coding Plan (langganan) | China | `qwen-api-key-cn` | `coding.dashscope.aliyuncs.com/v1` | +| Coding Plan (langganan) | Global | `qwen-api-key` | `coding-intl.dashscope.aliyuncs.com/v1` | -Provider secara otomatis memilih endpoint berdasarkan auth choice Anda. Pilihan -kanonis menggunakan keluarga `qwen-*`; `modelstudio-*` tetap hanya untuk kompatibilitas. +Provider secara otomatis memilih endpoint berdasarkan pilihan auth Anda. Pilihan kanonis +menggunakan keluarga `qwen-*`; `modelstudio-*` tetap khusus untuk kompatibilitas. Anda dapat menimpa dengan `baseUrl` kustom di config. -Endpoint Model Studio native mengiklankan kompatibilitas penggunaan streaming pada -transport bersama `openai-completions`. OpenClaw sekarang mengaitkannya berdasarkan -kapabilitas endpoint, sehingga id provider kustom yang kompatibel dengan DashScope dan menargetkan +Endpoint native Model Studio mengiklankan kompatibilitas penggunaan streaming pada +transport bersama `openai-completions`. OpenClaw kini mengaitkannya ke +kapabilitas endpoint, sehingga id provider kustom DashScope-compatible yang menargetkan host native yang sama mewarisi perilaku penggunaan streaming yang sama alih-alih -mewajibkan id provider bawaan `qwen` secara khusus. +secara khusus mewajibkan id provider bawaan `qwen`. ## Dapatkan API key Anda @@ -95,21 +95,23 @@ mewajibkan id provider bawaan `qwen` secara khusus. ## Katalog bawaan -OpenClaw saat ini menyediakan katalog Qwen bawaan berikut: +OpenClaw saat ini menyediakan katalog Qwen bawaan ini. Katalog yang dikonfigurasi +bergantung pada endpoint: config Coding Plan menghilangkan model yang hanya diketahui berfungsi pada +endpoint Standard. -| Referensi model | Input | Konteks | Catatan | -| -------------------------- | ----------- | --------- | -------------------------------------------------- | -| `qwen/qwen3.5-plus` | text, image | 1,000,000 | Model default | -| `qwen/qwen3.6-plus` | text, image | 1,000,000 | Gunakan endpoint Standard saat memerlukan model ini | -| `qwen/qwen3-max-2026-01-23`| text | 262,144 | Lini Qwen Max | -| `qwen/qwen3-coder-next` | text | 262,144 | Coding | -| `qwen/qwen3-coder-plus` | text | 1,000,000 | Coding | -| `qwen/MiniMax-M2.5` | text | 1,000,000 | Reasoning diaktifkan | -| `qwen/glm-5` | text | 202,752 | GLM | -| `qwen/glm-4.7` | text | 202,752 | GLM | -| `qwen/kimi-k2.5` | text, image | 262,144 | Moonshot AI via Alibaba | +| Ref model | Input | Konteks | Catatan | +| --------------------------- | ----------- | --------- | -------------------------------------------------- | +| `qwen/qwen3.5-plus` | text, image | 1,000,000 | Model default | +| `qwen/qwen3.6-plus` | text, image | 1,000,000 | Gunakan endpoint Standard jika Anda memerlukan model ini | +| `qwen/qwen3-max-2026-01-23` | text | 262,144 | Lini Qwen Max | +| `qwen/qwen3-coder-next` | text | 262,144 | Coding | +| `qwen/qwen3-coder-plus` | text | 1,000,000 | Coding | +| `qwen/MiniMax-M2.5` | text | 1,000,000 | Reasoning diaktifkan | +| `qwen/glm-5` | text | 202,752 | GLM | +| `qwen/glm-4.7` | text | 202,752 | GLM | +| `qwen/kimi-k2.5` | text, image | 262,144 | Moonshot AI melalui Alibaba | -Ketersediaan tetap dapat berbeda menurut endpoint dan paket penagihan meskipun suatu model +Ketersediaan tetap dapat bervariasi menurut endpoint dan paket penagihan meskipun suatu model ada dalam katalog bawaan. Kompatibilitas penggunaan native-streaming berlaku untuk host Coding Plan dan @@ -134,15 +136,15 @@ endpoint/key Coding Plan. ## Rencana kapabilitas Ekstensi `qwen` sedang diposisikan sebagai rumah vendor untuk seluruh permukaan Qwen -Cloud, bukan hanya model coding/teks. +Cloud, bukan hanya model coding/text. -- Model teks/chat: sudah dibundel -- Tool calling, output terstruktur, thinking: diwariskan dari transport yang kompatibel dengan OpenAI +- Model text/chat: sudah bawaan sekarang +- Pemanggilan tool, output terstruktur, thinking: diwarisi dari transport yang kompatibel dengan OpenAI - Pembuatan gambar: direncanakan di lapisan provider-plugin -- Pemahaman gambar/video: sudah dibundel pada endpoint Standard +- Pemahaman gambar/video: sudah bawaan sekarang pada endpoint Standard - Speech/audio: direncanakan di lapisan provider-plugin -- Embedding/reranking memori: direncanakan melalui permukaan adapter embedding -- Pembuatan video: sudah dibundel melalui kapabilitas video-generation bersama +- Embedding/reranking memory: direncanakan melalui permukaan adapter embedding +- Pembuatan video: sudah bawaan sekarang melalui capability video-generation bersama ## Add-on multimodal @@ -159,20 +161,20 @@ Ekstensi `qwen` sekarang juga mengekspos: Permukaan multimodal ini menggunakan endpoint DashScope **Standard**, bukan endpoint Coding Plan. -- URL dasar Standard Global/Intl: `https://dashscope-intl.aliyuncs.com/compatible-mode/v1` -- URL dasar Standard China: `https://dashscope.aliyuncs.com/compatible-mode/v1` +- Base URL Standard Global/Intl: `https://dashscope-intl.aliyuncs.com/compatible-mode/v1` +- Base URL Standard China: `https://dashscope.aliyuncs.com/compatible-mode/v1` -Untuk pembuatan video, OpenClaw memetakan wilayah Qwen yang dikonfigurasi ke host -DashScope AIGC regional yang sesuai sebelum mengirim job: +Untuk pembuatan video, OpenClaw memetakan wilayah Qwen yang dikonfigurasi ke +host AIGC DashScope yang sesuai sebelum mengirimkan pekerjaan: - Global/Intl: `https://dashscope-intl.aliyuncs.com` - China: `https://dashscope.aliyuncs.com` -Artinya `models.providers.qwen.baseUrl` normal yang menunjuk ke salah satu host -Qwen Coding Plan atau Standard tetap menjaga pembuatan video berada pada endpoint video DashScope +Itu berarti `models.providers.qwen.baseUrl` normal yang menunjuk ke salah satu +host Qwen Coding Plan atau Standard tetap menjaga pembuatan video pada endpoint video DashScope regional yang benar. -Untuk pembuatan video, tetapkan model default secara eksplisit: +Untuk pembuatan video, setel model default secara eksplisit: ```json5 { @@ -186,20 +188,20 @@ Untuk pembuatan video, tetapkan model default secara eksplisit: Batas pembuatan video Qwen bawaan saat ini: -- Maksimal **1** video output per permintaan -- Maksimal **1** gambar input -- Maksimal **4** video input -- Durasi maksimal **10 detik** +- Hingga **1** video output per permintaan +- Hingga **1** gambar input +- Hingga **4** video input +- Durasi hingga **10 detik** - Mendukung `size`, `aspectRatio`, `resolution`, `audio`, dan `watermark` -- Mode gambar/video referensi saat ini mewajibkan **URL http(s) jarak jauh**. Path - file lokal ditolak di awal karena endpoint video DashScope tidak +- Mode gambar/video referensi saat ini memerlukan **URL http(s) jarak jauh**. Path file lokal + ditolak di awal karena endpoint video DashScope tidak menerima buffer lokal yang diunggah untuk referensi tersebut. -Lihat [Video Generation](/tools/video-generation) untuk parameter tool -bersama, pemilihan provider, dan perilaku failover. +Lihat [Pembuatan Video](/id/tools/video-generation) untuk +parameter tool bersama, pemilihan provider, dan perilaku failover. ## Catatan environment Jika Gateway berjalan sebagai daemon (launchd/systemd), pastikan `QWEN_API_KEY` -tersedia bagi proses tersebut (misalnya, di `~/.openclaw/.env` atau melalui +tersedia untuk proses tersebut (misalnya, di `~/.openclaw/.env` atau melalui `env.shellEnv`).