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

chore(i18n): refresh id translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-17 09:17:40 +00:00
parent ff6c234eb8
commit cf5e90b1c6
7 changed files with 1101 additions and 1090 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

120
docs/id/concepts/qa-e2e-automation.md
View File

@ -2,27 +2,27 @@
read_when:
- Memperluas qa-lab atau qa-channel
- Menambahkan skenario QA yang didukung repo
- Membangun otomatisasi QA dengan realisme lebih tinggi di sekitar dasbor Gateway
summary: Bentuk otomatisasi QA privat untuk qa-lab, qa-channel, skenario yang di-seed, dan laporan protokol
title: Otomatisasi QA E2E
- Membangun otomasi QA dengan realisme lebih tinggi di sekitar dasbor Gateway
summary: Bentuk otomasi QA privat untuk qa-lab, qa-channel, skenario ber-seed, dan laporan protokol
title: Otomasi QA E2E
x-i18n:
generated_at: "2026-04-16T21:51:22Z"
generated_at: "2026-04-17T09:14:17Z"
model: gpt-5.4
provider: openai
source_hash: 7deefda1c90a0d2e21e2155ffd8b585fb999e7416bdbaf0ff57eb33ccc063afc
source_hash: 51f97293c184d7c04c95d9858305668fbc0f93273f587ec7e54896ad5d603ab0
source_path: concepts/qa-e2e-automation.md
workflow: 15
---
# Otomatisasi QA E2E
# Otomasi QA E2E
Stack QA privat dimaksudkan untuk menguji OpenClaw dengan cara yang lebih realistis dan berbentuk saluran dibandingkan yang bisa dilakukan oleh satu unit test.
Stack QA privat dimaksudkan untuk menguji OpenClaw dengan cara yang lebih realistis dan berbentuk kanal dibandingkan yang bisa dicapai oleh satu unit test.
Bagian yang ada saat ini:
Komponen saat ini:
- `extensions/qa-channel`: saluran pesan sintetis dengan permukaan DM, saluran, 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 kickoff dan skenario QA dasar.
- `qa/`: aset seed yang didukung repo untuk tugas kickoff dan skenario QA baseline.
Alur operator QA saat ini adalah situs QA dua panel:
@ -35,9 +35,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 otomatisasi dapat memberi agen misi QA, mengamati perilaku saluran nyata, dan mencatat apa yang berhasil, gagal, atau tetap terblokir.
Perintah itu membangun situs QA, memulai jalur Gateway berbasis Docker, dan mengekspos halaman QA Lab tempat operator atau loop otomasi 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, mulai stack dengan bundle QA Lab yang di-bind mount:
Untuk iterasi UI QA Lab yang lebih cepat tanpa membangun ulang image Docker setiap kali, mulai stack dengan bundle QA Lab yang di-bind-mount:
```bash
pnpm openclaw qa docker-build-image
@ -46,45 +46,45 @@ pnpm qa:lab:up:fast
pnpm qa:lab:watch
```
`qa:lab:up:fast` mempertahankan layanan Docker 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 akan memuat ulang otomatis ketika hash aset QA Lab berubah.
`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.
Untuk lane smoke Matrix dengan transport nyata, jalankan:
Untuk jalur smoke Matrix dengan transport nyata, jalankan:
```bash
pnpm openclaw qa matrix
```
Lane itu menyediakan homeserver Tuwunel sekali pakai di Docker, mendaftarkan pengguna driver, SUT, dan observer sementara, membuat satu room privat, lalu menjalankan Plugin Matrix nyata di dalam child gateway QA. Lane transport langsung menjaga config child tetap dibatasi pada transport yang sedang diuji, sehingga Matrix berjalan tanpa `qa-channel` di config child. Lane ini menulis artefak laporan terstruktur dan log gabungan stdout/stderr ke direktori output Matrix QA yang dipilih. Untuk juga menangkap output build/launcher luar `scripts/run-node.mjs`, set `OPENCLAW_RUN_NODE_OUTPUT_LOG=<path>` ke file log lokal repo.
Jalur ini menyediakan homeserver Tuwunel sekali pakai di Docker, mendaftarkan pengguna driver, SUT, dan observer sementara, membuat satu room privat, lalu menjalankan plugin Matrix asli di dalam child Gateway QA. Jalur transport langsung menjaga konfigurasi child tetap dibatasi pada transport yang diuji, sehingga Matrix berjalan tanpa `qa-channel` di konfigurasi child. Jalur ini menulis artefak laporan terstruktur dan log gabungan stdout/stderr ke direktori output Matrix QA yang dipilih. Untuk juga menangkap output build/launcher luar `scripts/run-node.mjs`, setel `OPENCLAW_RUN_NODE_OUTPUT_LOG=<path>` ke file log lokal repo.
Untuk lane smoke Telegram dengan transport nyata, jalankan:
Untuk jalur smoke Telegram dengan transport nyata, jalankan:
```bash
pnpm openclaw qa telegram
```
Lane itu menargetkan satu grup Telegram privat nyata alih-alih menyediakan server sekali pakai. Lane ini memerlukan `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`, dan `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, plus dua bot yang berbeda dalam grup privat yang sama. Bot SUT harus memiliki username Telegram, dan observasi bot-ke-bot bekerja paling baik ketika kedua bot mengaktifkan Bot-to-Bot Communication Mode di `@BotFather`.
Jalur ini menargetkan satu grup Telegram privat nyata alih-alih menyediakan server sekali pakai. Jalur ini memerlukan `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`, dan `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, serta dua bot berbeda di grup privat yang sama. Bot SUT harus memiliki username Telegram, dan observasi bot-ke-bot bekerja paling baik ketika kedua bot mengaktifkan Bot-to-Bot Communication Mode di `@BotFather`.
Lane transport langsung sekarang berbagi satu kontrak yang lebih kecil alih-alih masing-masing membuat bentuk daftar skenario sendiri.
Jalur transport langsung kini berbagi satu kontrak yang lebih kecil alih-alih masing-masing membuat bentuk daftar skenario sendiri.
`qa-channel` tetap menjadi suite perilaku produk sintetis yang luas dan bukan bagian dari matriks cakupan transport langsung.
`qa-channel` tetap menjadi suite luas untuk perilaku produk sintetis dan bukan bagian dari matriks cakupan transport langsung.
| Lane | Canary | Pembatasan mention | Blok allowlist | Balasan tingkat atas | Lanjut setelah restart | Tindak lanjut thread | Isolasi thread | Observasi reaksi | Perintah bantuan |
| -------- | ------ | ------------------ | -------------- | -------------------- | ---------------------- | -------------------- | -------------- | ---------------- | ---------------- |
| Matrix | x | x | x | x | x | x | x | x | |
| Telegram | x | | | | | | | | x |
| Jalur | Canary | Penyaringan mention | Blok allowlist | Balasan tingkat atas | Lanjut setelah restart | Tindak lanjut thread | Isolasi thread | Observasi reaction | Perintah help |
| -------- | ------ | ------------------- | -------------- | -------------------- | ---------------------- | -------------------- | -------------- | ------------------ | ------------- |
| Matrix | x | x | x | x | x | x | x | x | |
| Telegram | x | | | | | | | | x |
Ini menjaga `qa-channel` tetap sebagai suite perilaku produk yang luas sementara Matrix, Telegram, dan transport langsung di masa depan berbagi satu daftar periksa kontrak transport yang eksplisit.
Ini menjaga `qa-channel` sebagai suite luas untuk perilaku produk sementara Matrix, Telegram, dan transport langsung mendatang berbagi satu checklist kontrak transport yang eksplisit.
Untuk lane VM Linux sekali pakai tanpa membawa Docker ke jalur QA, jalankan:
Untuk jalur VM Linux sekali pakai tanpa membawa Docker ke jalur QA, jalankan:
```bash
pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
```
Ini mem-boot guest Multipass baru, memasang dependensi, membangun OpenClaw di dalam guest, menjalankan `qa suite`, lalu menyalin laporan dan ringkasan QA normal kembali ke `.artifacts/qa-e2e/...` di host.
Ini menggunakan kembali perilaku pemilihan skenario yang sama seperti `qa suite` di host.
Eksekusi suite di host dan Multipass menjalankan beberapa skenario terpilih secara paralel dengan worker gateway terisolasi secara default, hingga 64 worker atau sebanyak jumlah skenario yang dipilih. Gunakan `--concurrency <count>` untuk menyesuaikan jumlah worker, atau `--concurrency 1` untuk eksekusi serial.
Eksekusi langsung meneruskan input auth QA yang didukung dan praktis untuk guest: key provider berbasis env, path config provider langsung QA, dan `CODEX_HOME` jika ada. Pastikan `--output-dir` tetap di bawah root repo agar guest dapat menulis balik melalui workspace yang di-mount.
Perintah ini menyalakan guest Multipass baru, menginstal dependensi, membangun OpenClaw di dalam guest, menjalankan `qa suite`, lalu menyalin laporan QA normal dan ringkasannya kembali ke `.artifacts/qa-e2e/...` di host.
Perintah ini menggunakan ulang perilaku pemilihan skenario yang sama seperti `qa suite` di host.
Eksekusi suite di host dan Multipass menjalankan beberapa skenario terpilih secara paralel dengan worker Gateway terisolasi secara default, hingga 64 worker atau sebanyak jumlah skenario yang dipilih. Gunakan `--concurrency <count>` untuk menyesuaikan jumlah worker, atau `--concurrency 1` untuk eksekusi serial.
Eksekusi langsung meneruskan input auth QA yang didukung dan praktis untuk guest: key provider berbasis env, path konfigurasi provider langsung QA, dan `CODEX_HOME` jika ada. Pastikan `--output-dir` tetap berada di bawah root repo agar guest dapat menulis kembali melalui workspace yang di-mount.
## Seed yang didukung repo
@ -93,46 +93,58 @@ Aset seed berada di `qa/`:
- `qa/scenarios/index.md`
- `qa/scenarios/*.md`
Ini sengaja disimpan di git agar rencana QA terlihat oleh manusia maupun agen.
File-file ini sengaja disimpan di git agar rencana QA terlihat baik oleh manusia maupun agen.
`qa-lab` harus tetap menjadi runner markdown generik. Setiap file markdown skenario adalah sumber kebenaran untuk satu eksekusi test dan harus mendefinisikan:
`qa-lab` harus tetap menjadi runner markdown generik. Setiap file markdown skenario adalah sumber kebenaran untuk satu eksekusi pengujian dan harus mendefinisikan:
- metadata skenario
- referensi docs dan kode
- persyaratan Plugin opsional
- patch config gateway opsional
- persyaratan plugin opsional
- patch konfigurasi Gateway opsional
- `qa-flow` yang dapat dieksekusi
Permukaan runtime yang dapat digunakan kembali yang mendukung `qa-flow` boleh tetap generik dan lintas area. Misalnya, skenario markdown dapat menggabungkan helper sisi transport dengan helper sisi browser yang menggerakkan Control UI tertanam melalui seam Gateway `browser.request` tanpa menambahkan runner kasus khusus.
Permukaan runtime yang dapat digunakan ulang dan mendukung `qa-flow` diizinkan untuk tetap generik dan lintas potongan. Misalnya, skenario markdown dapat menggabungkan helper sisi transport dengan helper sisi browser yang menggerakkan Control UI tertanam melalui seam Gateway `browser.request` tanpa menambahkan runner kasus khusus.
Daftar dasar harus tetap cukup luas untuk mencakup:
Daftar baseline harus tetap cukup luas untuk mencakup:
- chat DM dan saluran
- chat DM dan channel
- perilaku thread
- siklus hidup aksi pesan
- callback Cron
- recall memory
- penggantian model
- penarikan kembali memory
- perpindahan model
- handoff subagen
- pembacaan repo dan pembacaan docs
- pembacaan repo dan docs
- satu tugas build kecil seperti Lobster Invaders
## Adapter transport
## Jalur mock provider
`qa suite` memiliki dua jalur mock provider lokal:
- `mock-openai` adalah mock OpenClaw yang sadar skenario. Ini tetap menjadi jalur mock deterministis default untuk QA yang didukung repo dan gate paritas.
- `aimock` memulai server provider berbasis AIMock untuk cakupan protokol, fixture, record/replay, dan chaos yang bersifat eksperimental. Ini bersifat tambahan dan tidak menggantikan dispatcher skenario `mock-openai`.
Implementasi jalur provider berada di bawah `extensions/qa-lab/src/providers/`.
Setiap provider memiliki default, startup server lokal, konfigurasi model Gateway, kebutuhan staging auth-profile, serta flag kemampuan live/mock miliknya sendiri. Suite bersama dan kode Gateway harus merutekan melalui registry provider alih-alih bercabang berdasarkan nama provider.
## Adaptor transport
`qa-lab` memiliki seam transport generik untuk skenario QA markdown.
`qa-channel` adalah adapter pertama pada seam tersebut, tetapi target desainnya lebih luas: saluran nyata atau sintetis di masa depan harus dapat dipasang ke suite runner yang sama alih-alih menambahkan runner QA khusus transport.
`qa-channel` adalah adaptor pertama pada seam itu, tetapi target desainnya lebih luas:
kanal nyata atau sintetis di masa depan harus dapat dihubungkan ke runner suite yang sama alih-alih menambahkan runner QA khusus transport.
Pada tingkat arsitektur, pembagiannya adalah:
- `qa-lab` memiliki eksekusi skenario generik, konkurensi worker, penulisan artefak, dan pelaporan.
- adapter transport memiliki config gateway, kesiapan, observasi masuk dan keluar, aksi transport, dan status transport yang dinormalisasi.
- file skenario markdown di bawah `qa/scenarios/` mendefinisikan eksekusi test; `qa-lab` menyediakan permukaan runtime yang dapat digunakan kembali yang mengeksekusinya.
- adaptor transport memiliki konfigurasi Gateway, kesiapan, observasi masuk dan keluar, aksi transport, dan status transport yang dinormalisasi.
- file skenario markdown di bawah `qa/scenarios/` mendefinisikan eksekusi pengujian; `qa-lab` menyediakan permukaan runtime yang dapat digunakan ulang untuk menjalankannya.
Panduan adopsi untuk maintainer bagi adapter saluran baru tersedia di [Testing](/id/help/testing#adding-a-channel-to-qa).
Panduan adopsi untuk maintainer yang berhadapan dengan adaptor kanal baru tersedia di
[Testing](/id/help/testing#adding-a-channel-to-qa).
## 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
@ -140,7 +152,7 @@ Laporan tersebut harus menjawab:
- Apa yang tetap terblokir
- Skenario tindak lanjut apa yang layak ditambahkan
Untuk pemeriksaan karakter dan gaya, jalankan skenario yang sama pada beberapa ref model langsung dan tulis laporan Markdown yang dinilai:
Untuk pemeriksaan karakter dan gaya, jalankan skenario yang sama di beberapa ref model langsung dan tulis laporan Markdown yang dinilai:
```bash
pnpm openclaw qa character-eval \
@ -159,17 +171,19 @@ pnpm openclaw qa character-eval \
--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 eksekusi, lalu meminta model judge dalam mode fast dengan penalaran `xhigh` untuk memberi peringkat pada hasil berdasarkan naturalitas, vibe, dan humor.
Gunakan `--blind-judge-models` saat membandingkan provider: prompt judge tetap menerima setiap transkrip dan status eksekusi, tetapi ref kandidat diganti dengan label netral seperti `candidate-01`; laporan kemudian memetakan peringkat kembali ke ref nyata setelah parsing.
Eksekusi kandidat secara default menggunakan thinking `high`, dengan `xhigh` untuk model OpenAI yang mendukungnya. Override kandidat tertentu secara inline dengan `--model provider/model,thinking=<level>`. `--thinking <level>` tetap menetapkan fallback global, dan bentuk lama `--model-thinking <provider/model=level>` tetap dipertahankan untuk kompatibilitas.
Ref kandidat OpenAI secara default menggunakan mode fast agar pemrosesan prioritas digunakan ketika provider mendukungnya. Tambahkan `,fast`, `,no-fast`, atau `,fast=false` secara inline saat satu kandidat atau judge memerlukan override. Gunakan `--fast` hanya jika Anda ingin memaksa mode fast aktif untuk setiap model kandidat. Durasi kandidat dan judge dicatat dalam laporan untuk analisis benchmark, tetapi prompt judge secara eksplisit menyatakan untuk tidak memberi peringkat berdasarkan kecepatan.
Eksekusi model kandidat dan judge keduanya secara default menggunakan konkurensi 16. Turunkan `--concurrency` atau `--judge-concurrency` ketika batas provider atau tekanan gateway lokal membuat eksekusi menjadi terlalu berisik.
Saat tidak ada kandidat `--model` yang diberikan, evaluasi karakter secara default menggunakan
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 eksekusi, lalu meminta model judge dalam mode fast dengan penalaran `xhigh` untuk memberi peringkat pada eksekusi berdasarkan naturalness, vibe, dan humor.
Gunakan `--blind-judge-models` saat membandingkan provider: prompt judge tetap menerima setiap transkrip dan status eksekusi, tetapi ref kandidat diganti dengan label netral seperti `candidate-01`; laporan memetakan kembali peringkat ke ref asli setelah parsing.
Eksekusi kandidat secara default menggunakan thinking `high`, dengan `xhigh` untuk model OpenAI yang mendukungnya. Override kandidat tertentu secara inline dengan
`--model provider/model,thinking=<level>`. `--thinking <level>` tetap menetapkan fallback global, dan format lama `--model-thinking <provider/model=level>` dipertahankan demi kompatibilitas.
Ref kandidat OpenAI secara default menggunakan mode fast sehingga pemrosesan prioritas digunakan di tempat provider mendukungnya. Tambahkan `,fast`, `,no-fast`, atau `,fast=false` secara inline ketika satu kandidat atau judge memerlukan override. Berikan `--fast` hanya ketika Anda ingin memaksa mode fast aktif untuk setiap model kandidat. Durasi kandidat dan judge dicatat di laporan untuk analisis benchmark, tetapi prompt judge secara eksplisit menyatakan agar tidak memberi peringkat berdasarkan kecepatan.
Eksekusi model kandidat dan judge keduanya menggunakan konkurensi default 16. Turunkan
`--concurrency` atau `--judge-concurrency` ketika batas provider atau tekanan Gateway lokal membuat eksekusi terlalu bising.
Jika 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` ketika tidak ada `--model` yang diberikan.
Saat tidak ada `--judge-model` yang diberikan, judge secara default menggunakan
Jika tidak ada `--judge-model` yang diberikan, judge defaultnya adalah
`openai/gpt-5.4,thinking=xhigh,fast` dan
`anthropic/claude-opus-4-6,thinking=high`.

423
docs/id/gateway/protocol.md
View File

@ -1,25 +1,25 @@
---
read_when:
- Mengimplementasikan atau memperbarui klien WS Gateway
- Mengimplementasikan atau memperbarui klien WS gateway
- Men-debug ketidakcocokan protokol atau kegagalan koneksi
- Membuat ulang skema/model protokol
summary: 'Protokol WebSocket Gateway: handshake, frame, pembuatan versi'
title: Protokol Gateway
x-i18n:
generated_at: "2026-04-16T09:14:38Z"
generated_at: "2026-04-17T09:14:18Z"
model: gpt-5.4
provider: openai
source_hash: 683e61ebe993a2d739bc34860060b0e3eda36b5c57267a2bcc03d177ec612fb3
source_hash: 4f0eebcfdd8c926c90b4753a6d96c59e3134ddb91740f65478f11eb75be85e41
source_path: gateway/protocol.md
workflow: 15
---
# Protokol Gateway (WebSocket)
Protokol WS Gateway adalah **bidang kontrol tunggal + transport node** untuk
Protokol WS Gateway adalah **control plane tunggal + transport node** untuk
OpenClaw. Semua klien (CLI, UI web, aplikasi macOS, node iOS/Android, node
headless) terhubung melalui WebSocket dan mendeklarasikan **peran** + **cakupan**
mereka saat handshake.
mereka pada saat handshake.
## Transport
@ -96,7 +96,21 @@ Gateway → Klien:
```
`server`, `features`, `snapshot`, dan `policy` semuanya wajib menurut skema
(`src/gateway/protocol/schema/frames.ts`). `auth` dan `canvasHostUrl` bersifat opsional.
(`src/gateway/protocol/schema/frames.ts`). `canvasHostUrl` bersifat opsional. `auth`
melaporkan peran/cakupan yang dinegosiasikan saat tersedia, dan menyertakan `deviceToken`
saat gateway menerbitkannya.
Saat tidak ada token perangkat yang diterbitkan, `hello-ok.auth` masih dapat melaporkan
izin yang dinegosiasikan:
```json
{
"auth": {
"role": "operator",
"scopes": ["operator.read", "operator.write"]
}
}
```
Saat token perangkat diterbitkan, `hello-ok` juga menyertakan:
@ -110,8 +124,8 @@ Saat token perangkat diterbitkan, `hello-ok` juga menyertakan:
}
```
Selama handoff bootstrap tepercaya, `hello-ok.auth` juga dapat menyertakan entri
peran tambahan yang dibatasi dalam `deviceTokens`:
Selama handoff bootstrap tepercaya, `hello-ok.auth` juga dapat menyertakan entri peran
tambahan yang dibatasi dalam `deviceTokens`:
```json
{
@ -131,8 +145,8 @@ peran tambahan yang dibatasi dalam `deviceTokens`:
```
Untuk alur bootstrap node/operator bawaan, token node utama tetap
`scopes: []` dan token operator yang di-handoff tetap dibatasi ke allowlist
operator bootstrap (`operator.approvals`, `operator.read`,
`scopes: []` dan token operator yang di-handoff tetap dibatasi pada daftar izin operator bootstrap
(`operator.approvals`, `operator.read`,
`operator.talk.secrets`, `operator.write`). Pemeriksaan cakupan bootstrap tetap
berawalan peran: entri operator hanya memenuhi permintaan operator, dan peran
non-operator tetap memerlukan cakupan di bawah awalan perannya sendiri.
@ -174,17 +188,17 @@ non-operator tetap memerlukan cakupan di bawah awalan perannya sendiri.
## Framing
- **Request**: `{type:"req", id, method, params}`
- **Response**: `{type:"res", id, ok, payload|error}`
- **Permintaan**: `{type:"req", id, method, params}`
- **Respons**: `{type:"res", id, ok, payload|error}`
- **Event**: `{type:"event", event, payload, seq?, stateVersion?}`
Method yang memiliki efek samping memerlukan **idempotency keys** (lihat skema).
Metode yang memiliki efek samping memerlukan **kunci idempotensi** (lihat skema).
## Peran + cakupan
### Peran
- `operator` = klien bidang kontrol (CLI/UI/otomasi).
- `operator` = klien control plane (CLI/UI/otomasi).
- `node` = host kapabilitas (camera/screen/canvas/system.run).
### Cakupan (operator)
@ -201,17 +215,16 @@ Cakupan umum:
`talk.config` dengan `includeSecrets: true` memerlukan `operator.talk.secrets`
(atau `operator.admin`).
Method RPC Gateway yang didaftarkan Plugin dapat meminta cakupan operatornya
sendiri, tetapi awalan admin inti yang dicadangkan (`config.*`, `exec.approvals.*`, `wizard.*`,
`update.*`) selalu di-resolve menjadi `operator.admin`.
Metode RPC gateway yang didaftarkan Plugin dapat meminta cakupan operatornya sendiri, tetapi
awalan admin inti yang dicadangkan (`config.*`, `exec.approvals.*`, `wizard.*`,
`update.*`) selalu diresolusikan ke `operator.admin`.
Cakupan method hanyalah gerbang pertama. Beberapa slash command yang dicapai
melalui `chat.send` menerapkan pemeriksaan tingkat perintah yang lebih ketat di
atasnya. Misalnya, penulisan persisten `/config set` dan `/config unset`
memerlukan `operator.admin`.
Cakupan metode hanyalah gerbang pertama. Beberapa perintah slash yang dicapai melalui
`chat.send` menerapkan pemeriksaan tingkat perintah yang lebih ketat di atasnya. Sebagai
contoh, penulisan persisten `/config set` dan `/config unset` memerlukan `operator.admin`.
`node.pair.approve` juga memiliki pemeriksaan cakupan saat persetujuan tambahan
di atas cakupan method dasar:
`node.pair.approve` juga memiliki pemeriksaan cakupan tambahan pada saat persetujuan di atas
cakupan metode dasar:
- permintaan tanpa perintah: `operator.pairing`
- permintaan dengan perintah node non-exec: `operator.pairing` + `operator.write`
@ -223,33 +236,33 @@ di atas cakupan method dasar:
Node mendeklarasikan klaim kapabilitas saat waktu connect:
- `caps`: kategori kapabilitas tingkat tinggi.
- `commands`: allowlist perintah untuk invoke.
- `permissions`: toggle granular (misalnya `screen.record`, `camera.capture`).
- `commands`: daftar izin perintah untuk invoke.
- `permissions`: toggle terperinci (misalnya `screen.record`, `camera.capture`).
Gateway memperlakukan ini sebagai **klaim** dan menegakkan allowlist di sisi server.
Gateway memperlakukan ini sebagai **klaim** dan menegakkan daftar izin di sisi server.
## Kehadiran
- `system-presence` mengembalikan entri yang dikunci berdasarkan identitas perangkat.
- Entri kehadiran mencakup `deviceId`, `roles`, dan `scopes` sehingga UI dapat menampilkan satu baris per perangkat
bahkan ketika perangkat terhubung sebagai **operator** dan **node** sekaligus.
- `system-presence` mengembalikan entri yang dikunci oleh identitas perangkat.
- Entri kehadiran mencakup `deviceId`, `roles`, dan `scopes` agar UI dapat menampilkan satu baris per perangkat
bahkan saat perangkat terhubung sebagai **operator** dan **node**.
## Keluarga method RPC umum
## Keluarga metode RPC umum
Halaman ini bukan dump penuh yang dihasilkan, tetapi permukaan WS publik lebih
luas daripada contoh handshake/auth di atas. Ini adalah keluarga method utama
yang diekspos Gateway saat ini.
Halaman ini bukan dump penuh yang dihasilkan, tetapi permukaan WS publik lebih luas
daripada contoh handshake/auth di atas. Ini adalah keluarga metode utama yang
diekspose Gateway saat ini.
`hello-ok.features.methods` adalah daftar penemuan konservatif yang dibangun dari
`src/gateway/server-methods-list.ts` ditambah ekspor method plugin/channel yang dimuat.
Perlakukan ini sebagai penemuan fitur, bukan sebagai dump yang dihasilkan dari
setiap helper yang dapat dipanggil yang diimplementasikan dalam `src/gateway/server-methods/*.ts`.
`src/gateway/server-methods-list.ts` ditambah ekspor metode Plugin/channel yang dimuat.
Perlakukan ini sebagai penemuan fitur, bukan sebagai dump yang dihasilkan dari setiap helper yang dapat dipanggil
yang diimplementasikan di `src/gateway/server-methods/*.ts`.
### Sistem dan identitas
- `health` mengembalikan snapshot kesehatan gateway yang di-cache atau baru diprobe.
- `status` mengembalikan ringkasan gateway gaya `/status`; field sensitif hanya
disertakan untuk klien operator dengan cakupan admin.
- `status` mengembalikan ringkasan gateway bergaya `/status`; field sensitif
disertakan hanya untuk klien operator dengan cakupan admin.
- `gateway.identity.get` mengembalikan identitas perangkat gateway yang digunakan oleh alur relay dan
pairing.
- `system-presence` mengembalikan snapshot kehadiran saat ini untuk perangkat
@ -257,82 +270,82 @@ setiap helper yang dapat dipanggil yang diimplementasikan dalam `src/gateway/ser
- `system-event` menambahkan event sistem dan dapat memperbarui/menyiarkan konteks
kehadiran.
- `last-heartbeat` mengembalikan event Heartbeat persisten terbaru.
- `set-heartbeats` mengaktifkan atau menonaktifkan pemrosesan Heartbeat di gateway.
- `set-heartbeats` mengaktifkan atau menonaktifkan pemrosesan Heartbeat pada gateway.
### Model dan penggunaan
- `models.list` mengembalikan katalog model yang diizinkan saat runtime.
- `usage.status` mengembalikan ringkasan jendela penggunaan provider/kuota tersisa.
- `usage.status` mengembalikan ringkasan jendela penggunaan/kuota tersisa penyedia.
- `usage.cost` mengembalikan ringkasan penggunaan biaya agregat untuk rentang tanggal.
- `doctor.memory.status` mengembalikan kesiapan vector-memory / embedding untuk
workspace agen default aktif.
workspace agen default yang aktif.
- `sessions.usage` mengembalikan ringkasan penggunaan per sesi.
- `sessions.usage.timeseries` mengembalikan penggunaan deret waktu untuk satu sesi.
- `sessions.usage.timeseries` mengembalikan deret waktu penggunaan untuk satu sesi.
- `sessions.usage.logs` mengembalikan entri log penggunaan untuk satu sesi.
### Channel dan helper login
- `channels.status` mengembalikan ringkasan status channel/plugin bawaan + bundled.
- `channels.logout` melakukan logout untuk channel/akun tertentu ketika channel
- `channels.status` mengembalikan ringkasan status channel/Plugin bawaan + bundled.
- `channels.logout` logout dari channel/akun tertentu jika channel tersebut
mendukung logout.
- `web.login.start` memulai alur login QR/web untuk provider channel web
berkemampuan QR saat ini.
- `web.login.wait` menunggu hingga alur login QR/web tersebut selesai dan memulai
- `web.login.start` memulai alur login QR/web untuk penyedia channel web
saat ini yang mendukung QR.
- `web.login.wait` menunggu alur login QR/web tersebut selesai dan memulai
channel jika berhasil.
- `push.test` mengirim push APNs uji ke node iOS yang terdaftar.
- `voicewake.get` mengembalikan trigger wake-word yang tersimpan.
- `voicewake.set` memperbarui trigger wake-word dan menyiarkan perubahannya.
- `voicewake.get` mengembalikan pemicu wake word yang tersimpan.
- `voicewake.set` memperbarui pemicu wake word dan menyiarkan perubahannya.
### Pesan dan log
- `send` adalah RPC pengiriman keluar langsung untuk pengiriman yang ditargetkan ke
channel/akun/thread di luar chat runner.
- `logs.tail` mengembalikan tail file log gateway yang dikonfigurasi dengan kontrol cursor/limit dan
max-byte.
- `logs.tail` mengembalikan tail file-log gateway yang dikonfigurasi dengan cursor/limit dan
kontrol byte maksimum.
### Talk dan TTS
- `talk.config` mengembalikan payload konfigurasi Talk yang efektif; `includeSecrets`
- `talk.config` mengembalikan payload konfigurasi Talk efektif; `includeSecrets`
memerlukan `operator.talk.secrets` (atau `operator.admin`).
- `talk.mode` menetapkan/menyiarkan status mode Talk saat ini untuk klien
WebChat/Control UI.
- `talk.speak` mensintesis ucapan melalui provider speech Talk yang aktif.
- `tts.status` mengembalikan status TTS aktif/nonaktif, provider aktif, provider fallback,
dan status konfigurasi provider.
- `tts.providers` mengembalikan inventaris provider TTS yang terlihat.
- `talk.speak` mensintesis ucapan melalui penyedia speech Talk yang aktif.
- `tts.status` mengembalikan status TTS aktif, penyedia aktif, penyedia fallback,
dan status konfigurasi penyedia.
- `tts.providers` mengembalikan inventaris penyedia TTS yang terlihat.
- `tts.enable` dan `tts.disable` mengaktifkan atau menonaktifkan status preferensi TTS.
- `tts.setProvider` memperbarui provider TTS pilihan.
- `tts.setProvider` memperbarui penyedia TTS pilihan.
- `tts.convert` menjalankan konversi text-to-speech sekali jalan.
### Secret, config, update, dan wizard
- `secrets.reload` me-resolve ulang SecretRef aktif dan menukar status secret runtime
hanya jika seluruh proses berhasil.
- `secrets.resolve` me-resolve penetapan secret yang ditargetkan perintah untuk
set perintah/target tertentu.
- `config.get` mengembalikan snapshot config dan hash saat ini.
- `secrets.reload` me-resolve ulang SecretRef aktif dan menukar state secret runtime
hanya jika sepenuhnya berhasil.
- `secrets.resolve` me-resolve penetapan secret target perintah untuk
kumpulan perintah/target tertentu.
- `config.get` mengembalikan snapshot config saat ini dan hash-nya.
- `config.set` menulis payload config yang tervalidasi.
- `config.patch` menggabungkan pembaruan config parsial.
- `config.apply` memvalidasi + mengganti seluruh payload config.
- `config.schema` mengembalikan payload skema config live yang digunakan oleh Control UI dan
tooling CLI: skema, `uiHints`, versi, dan metadata generasi, termasuk
metadata skema plugin + channel ketika runtime dapat memuatnya. Skema ini
metadata skema Plugin + channel saat runtime dapat memuatnya. Skema ini
mencakup metadata field `title` / `description` yang diturunkan dari label yang sama
dan teks bantuan yang digunakan oleh UI, termasuk object bertingkat, wildcard, array-item,
dan cabang komposisi `anyOf` / `oneOf` / `allOf` ketika dokumentasi field
yang cocok tersedia.
- `config.schema.lookup` mengembalikan payload lookup berbatas path untuk satu
path config: path yang dinormalisasi, node skema dangkal, hint yang cocok + `hintPath`, dan
dan teks bantuan yang digunakan oleh UI, termasuk object bertingkat, wildcard, item array,
dan cabang komposisi `anyOf` / `oneOf` / `allOf` saat dokumentasi field yang cocok
tersedia.
- `config.schema.lookup` mengembalikan payload lookup berbatas path untuk satu path config:
path yang dinormalisasi, node skema dangkal, hint yang cocok + `hintPath`, dan
ringkasan child langsung untuk drill-down UI/CLI.
- Node skema lookup mempertahankan dokumentasi yang berhadapan dengan pengguna dan field validasi umum:
- Node skema lookup mempertahankan dokumen yang menghadap pengguna dan field validasi umum:
`title`, `description`, `type`, `enum`, `const`, `format`, `pattern`,
batas numerik/string/array/object, dan flag boolean seperti
`additionalProperties`, `deprecated`, `readOnly`, `writeOnly`.
- Ringkasan child mengekspos `key`, `path` yang dinormalisasi, `type`, `required`,
`hasChildren`, serta `hint` / `hintPath` yang cocok.
- `update.run` menjalankan alur pembaruan gateway dan menjadwalkan restart hanya ketika
- Ringkasan child mengekspose `key`, `path` yang dinormalisasi, `type`, `required`,
`hasChildren`, ditambah `hint` / `hintPath` yang cocok.
- `update.run` menjalankan alur pembaruan gateway dan menjadwalkan restart hanya jika
pembaruan itu sendiri berhasil.
- `wizard.start`, `wizard.next`, `wizard.status`, dan `wizard.cancel` mengekspos
- `wizard.start`, `wizard.next`, `wizard.status`, dan `wizard.cancel` mengekspose
wizard onboarding melalui WS RPC.
### Keluarga utama yang sudah ada
@ -340,29 +353,29 @@ setiap helper yang dapat dipanggil yang diimplementasikan dalam `src/gateway/ser
#### Helper agen dan workspace
- `agents.list` mengembalikan entri agen yang dikonfigurasi.
- `agents.create`, `agents.update`, dan `agents.delete` mengelola record agen dan
- `agents.create`, `agents.update`, dan `agents.delete` mengelola rekaman agen dan
wiring workspace.
- `agents.files.list`, `agents.files.get`, dan `agents.files.set` mengelola file
workspace bootstrap yang diekspos untuk sebuah agen.
- `agents.files.list`, `agents.files.get`, dan `agents.files.set` mengelola file workspace
bootstrap yang diekspose untuk sebuah agen.
- `agent.identity.get` mengembalikan identitas asisten efektif untuk sebuah agen atau
sesi.
- `agent.wait` menunggu hingga sebuah run selesai dan mengembalikan snapshot terminal ketika
- `agent.wait` menunggu sebuah run selesai dan mengembalikan snapshot terminal saat
tersedia.
#### Kontrol sesi
- `sessions.list` mengembalikan indeks sesi saat ini.
- `sessions.subscribe` dan `sessions.unsubscribe` mengaktifkan atau menonaktifkan langganan event perubahan sesi
untuk klien WS saat ini.
- `sessions.subscribe` dan `sessions.unsubscribe` mengaktifkan atau menonaktifkan langganan
event perubahan sesi untuk klien WS saat ini.
- `sessions.messages.subscribe` dan `sessions.messages.unsubscribe` mengaktifkan atau menonaktifkan
langganan event transkrip/pesan untuk satu sesi.
- `sessions.preview` mengembalikan pratinjau transkrip yang dibatasi untuk kunci
sesi tertentu.
- `sessions.preview` mengembalikan pratinjau transkrip terbatas untuk key sesi
tertentu.
- `sessions.resolve` me-resolve atau mengkanonisasi target sesi.
- `sessions.create` membuat entri sesi baru.
- `sessions.send` mengirim pesan ke dalam sesi yang sudah ada.
- `sessions.steer` adalah varian interrupt-and-steer untuk sesi yang aktif.
- `sessions.abort` membatalkan pekerjaan aktif untuk suatu sesi.
- `sessions.send` mengirim pesan ke sesi yang sudah ada.
- `sessions.steer` adalah varian interrupt-and-steer untuk sesi aktif.
- `sessions.abort` membatalkan pekerjaan aktif untuk sebuah sesi.
- `sessions.patch` memperbarui metadata/override sesi.
- `sessions.reset`, `sessions.delete`, dan `sessions.compact` melakukan
pemeliharaan sesi.
@ -370,48 +383,49 @@ setiap helper yang dapat dipanggil yang diimplementasikan dalam `src/gateway/ser
- eksekusi chat tetap menggunakan `chat.history`, `chat.send`, `chat.abort`, dan
`chat.inject`.
- `chat.history` dinormalisasi untuk tampilan bagi klien UI: tag direktif inline
dihapus dari teks yang terlihat, payload XML panggilan tool teks biasa (termasuk
dihapus dari teks yang terlihat, payload XML panggilan tool dalam plain-text (termasuk
`<tool_call>...</tool_call>`, `<function_call>...</function_call>`,
`<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>`, dan
blok panggilan tool yang dipotong) serta token kontrol model ASCII/full-width yang bocor
dihapus, baris asisten token senyap murni seperti `NO_REPLY` / `no_reply`
yang persis sama dihilangkan, dan baris yang terlalu besar dapat diganti dengan placeholder.
blok panggilan tool yang terpotong) serta token kontrol model ASCII/full-width yang bocor
dihapus, baris asisten token senyap murni seperti `NO_REPLY` /
`no_reply` yang persis cocok dihilangkan, dan baris yang terlalu besar dapat diganti
dengan placeholder.
#### Pairing perangkat dan token perangkat
- `device.pair.list` mengembalikan perangkat berpasangan yang tertunda dan yang disetujui.
- `device.pair.approve`, `device.pair.reject`, dan `device.pair.remove` mengelola
record pairing perangkat.
- `device.token.rotate` memutar token perangkat yang telah dipasangkan dalam batas peran
dan cakupan yang disetujui.
- `device.token.revoke` mencabut token perangkat yang telah dipasangkan.
rekaman pairing perangkat.
- `device.token.rotate` merotasi token perangkat berpasangan dalam batas peran
dan cakupan yang telah disetujui.
- `device.token.revoke` mencabut token perangkat berpasangan.
#### Pairing node, invoke, dan pekerjaan tertunda
- `node.pair.request`, `node.pair.list`, `node.pair.approve`,
`node.pair.reject`, dan `node.pair.verify` mencakup pairing node dan verifikasi
bootstrap.
`node.pair.reject`, dan `node.pair.verify` mencakup pairing node dan
verifikasi bootstrap.
- `node.list` dan `node.describe` mengembalikan status node yang diketahui/terhubung.
- `node.rename` memperbarui label node yang telah dipasangkan.
- `node.rename` memperbarui label node berpasangan.
- `node.invoke` meneruskan perintah ke node yang terhubung.
- `node.invoke.result` mengembalikan hasil untuk permintaan invoke.
- `node.event` membawa event yang berasal dari node kembali ke gateway.
- `node.canvas.capability.refresh` menyegarkan token kapabilitas canvas yang dibatasi cakupan.
- `node.canvas.capability.refresh` me-refresh token kapabilitas canvas yang dibatasi cakupan.
- `node.pending.pull` dan `node.pending.ack` adalah API antrean node yang terhubung.
- `node.pending.enqueue` dan `node.pending.drain` mengelola pekerjaan tertunda yang tahan lama
untuk node yang offline/terputus.
untuk node offline/tidak terhubung.
#### Keluarga approval
- `exec.approval.request`, `exec.approval.get`, `exec.approval.list`, dan
`exec.approval.resolve` mencakup permintaan approval exec sekali jalan plus
lookup/replay approval yang tertunda.
lookup/replay approval tertunda.
- `exec.approval.waitDecision` menunggu satu approval exec yang tertunda dan mengembalikan
keputusan akhir (atau `null` saat timeout).
keputusan final (atau `null` saat timeout).
- `exec.approvals.get` dan `exec.approvals.set` mengelola snapshot kebijakan approval exec
gateway.
- `exec.approvals.node.get` dan `exec.approvals.node.set` mengelola kebijakan approval exec
lokal node melalui perintah relay node.
- `exec.approvals.node.get` dan `exec.approvals.node.set` mengelola kebijakan approval exec lokal node
melalui perintah relay node.
- `plugin.approval.request`, `plugin.approval.list`,
`plugin.approval.waitDecision`, dan `plugin.approval.resolve` mencakup
alur approval yang didefinisikan Plugin.
@ -422,68 +436,65 @@ setiap helper yang dapat dipanggil yang diimplementasikan dalam `src/gateway/ser
- `wake` menjadwalkan injeksi teks bangun segera atau pada Heartbeat berikutnya
- `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`,
`cron.run`, `cron.runs`
- skills/tools: `commands.list`, `skills.*`, `tools.catalog`, `tools.effective`
- Skills/tools: `commands.list`, `skills.*`, `tools.catalog`, `tools.effective`
### Keluarga event umum
- `chat`: pembaruan chat UI seperti `chat.inject` dan event chat khusus transkrip
lainnya.
- `session.message` dan `session.tool`: pembaruan transkrip/aliran event untuk sesi
yang dilanggani.
- `chat`: pembaruan chat UI seperti `chat.inject` dan event chat lain yang hanya untuk transkrip.
- `session.message` dan `session.tool`: pembaruan transkrip/aliran event untuk sesi yang
dilanggan.
- `sessions.changed`: indeks sesi atau metadata berubah.
- `presence`: pembaruan snapshot kehadiran sistem.
- `tick`: event keepalive / liveness periodik.
- `tick`: event keepalive / liveness berkala.
- `health`: pembaruan snapshot kesehatan gateway.
- `heartbeat`: pembaruan aliran event Heartbeat.
- `cron`: event perubahan job/run cron.
- `shutdown`: notifikasi shutdown gateway.
- `cron`: event perubahan job/run Cron.
- `shutdown`: notifikasi gateway shutdown.
- `node.pair.requested` / `node.pair.resolved`: siklus hidup pairing node.
- `node.invoke.request`: siaran permintaan invoke node.
- `device.pair.requested` / `device.pair.resolved`: siklus hidup perangkat yang dipasangkan.
- `voicewake.changed`: config trigger wake-word berubah.
- `device.pair.requested` / `device.pair.resolved`: siklus hidup perangkat berpasangan.
- `voicewake.changed`: config pemicu wake word berubah.
- `exec.approval.requested` / `exec.approval.resolved`: siklus hidup
approval exec.
- `plugin.approval.requested` / `plugin.approval.resolved`: siklus hidup
approval plugin.
- `plugin.approval.requested` / `plugin.approval.resolved`: siklus hidup approval Plugin.
### Method helper node
### Metode helper node
- Node dapat memanggil `skills.bins` untuk mengambil daftar executable skill saat ini
untuk pemeriksaan auto-allow.
### Method helper operator
### Metode helper operator
- Operator dapat memanggil `commands.list` (`operator.read`) untuk mengambil inventaris perintah runtime bagi sebuah
agen.
- Operator dapat memanggil `commands.list` (`operator.read`) untuk mengambil inventaris perintah runtime untuk sebuah agen.
- `agentId` bersifat opsional; hilangkan untuk membaca workspace agen default.
- `scope` mengontrol permukaan yang dituju `name` utama:
- `scope` mengontrol permukaan mana yang ditargetkan `name` utama:
- `text` mengembalikan token perintah teks utama tanpa awalan `/`
- `native` dan jalur default `both` mengembalikan nama native yang sadar-provider
jika tersedia
- `textAliases` membawa alias slash persis seperti `/model` dan `/m`.
- `nativeName` membawa nama perintah native yang sadar-provider jika ada.
- `provider` bersifat opsional dan hanya memengaruhi penamaan native plus ketersediaan perintah
Plugin native.
- `includeArgs=false` menghilangkan metadata argumen terserialisasi dari respons.
- `native` dan jalur default `both` mengembalikan nama native yang sadar penyedia
saat tersedia
- `textAliases` membawa alias slash yang persis seperti `/model` dan `/m`.
- `nativeName` membawa nama perintah native yang sadar penyedia saat tersedia.
- `provider` bersifat opsional dan hanya memengaruhi penamaan native ditambah ketersediaan
perintah Plugin native.
- `includeArgs=false` menghilangkan metadata argumen yang diserialisasi dari respons.
- Operator dapat memanggil `tools.catalog` (`operator.read`) untuk mengambil katalog tool runtime untuk sebuah
agen. Responsnya mencakup tool yang dikelompokkan dan metadata asal:
agen. Respons mencakup tool yang dikelompokkan dan metadata asal:
- `source`: `core` atau `plugin`
- `pluginId`: pemilik plugin ketika `source="plugin"`
- `pluginId`: pemilik plugin saat `source="plugin"`
- `optional`: apakah tool plugin bersifat opsional
- Operator dapat memanggil `tools.effective` (`operator.read`) untuk mengambil inventaris tool efektif-runtime
untuk suatu sesi.
- Operator dapat memanggil `tools.effective` (`operator.read`) untuk mengambil inventaris tool efektif runtime
untuk sebuah sesi.
- `sessionKey` wajib.
- Gateway menurunkan konteks runtime tepercaya dari sesi di sisi server alih-alih menerima
- Gateway menurunkan konteks runtime tepercaya dari sesi di sisi server, bukan menerima
auth atau konteks pengiriman yang disuplai pemanggil.
- Responsnya dibatasi per sesi dan mencerminkan apa yang dapat digunakan percakapan aktif saat ini,
termasuk core, plugin, dan tool channel.
- Respons dibatasi pada sesi dan mencerminkan apa yang dapat digunakan percakapan aktif saat ini,
termasuk tool core, plugin, dan channel.
- Operator dapat memanggil `skills.status` (`operator.read`) untuk mengambil inventaris
Skills yang terlihat untuk sebuah agen.
skill yang terlihat untuk sebuah agen.
- `agentId` bersifat opsional; hilangkan untuk membaca workspace agen default.
- Responsnya mencakup kelayakan, persyaratan yang hilang, pemeriksaan config, dan
opsi instalasi yang disanitasi tanpa mengekspos nilai secret mentah.
- Operator dapat memanggil `skills.search` dan `skills.detail` (`operator.read`) untuk metadata penemuan
ClawHub.
- Respons mencakup kelayakan, persyaratan yang belum terpenuhi, pemeriksaan config, dan
opsi install yang telah disanitasi tanpa mengekspos nilai secret mentah.
- Operator dapat memanggil `skills.search` dan `skills.detail` (`operator.read`) untuk
metadata penemuan ClawHub.
- Operator dapat memanggil `skills.install` (`operator.admin`) dalam dua mode:
- Mode ClawHub: `{ source: "clawhub", slug, version?, force? }` memasang folder
skill ke direktori `skills/` workspace agen default.
@ -492,25 +503,25 @@ setiap helper yang dapat dipanggil yang diimplementasikan dalam `src/gateway/ser
- Operator dapat memanggil `skills.update` (`operator.admin`) dalam dua mode:
- Mode ClawHub memperbarui satu slug yang dilacak atau semua instalasi ClawHub yang dilacak di
workspace agen default.
- Mode config mem-patch nilai `skills.entries.<skillKey>` seperti `enabled`,
- Mode config menambal nilai `skills.entries.<skillKey>` seperti `enabled`,
`apiKey`, dan `env`.
## Approval exec
- Saat permintaan exec memerlukan approval, gateway menyiarkan `exec.approval.requested`.
- Klien operator menyelesaikannya dengan memanggil `exec.approval.resolve` (memerlukan cakupan `operator.approvals`).
- Untuk `host=node`, `exec.approval.request` harus menyertakan `systemRunPlan` (`argv`/`cwd`/`rawCommand`/metadata sesi kanonis). Permintaan yang tidak memiliki `systemRunPlan` akan ditolak.
- Klien operator me-resolve dengan memanggil `exec.approval.resolve` (memerlukan cakupan `operator.approvals`).
- Untuk `host=node`, `exec.approval.request` harus menyertakan `systemRunPlan` (metadata `argv`/`cwd`/`rawCommand`/sesi kanonis). Permintaan yang tidak memiliki `systemRunPlan` akan ditolak.
- Setelah approval, panggilan `node.invoke system.run` yang diteruskan menggunakan kembali
`systemRunPlan` kanonis tersebut sebagai konteks perintah/cwd/sesi yang otoritatif.
- Jika pemanggil memodifikasi `command`, `rawCommand`, `cwd`, `agentId`, atau
`sessionKey` antara prepare dan penerusan `system.run` final yang disetujui, maka
gateway menolak eksekusi tersebut alih-alih mempercayai payload yang telah dimodifikasi.
- Jika pemanggil mengubah `command`, `rawCommand`, `cwd`, `agentId`, atau
`sessionKey` antara prepare dan penerusan `system.run` final yang disetujui, gateway
menolak eksekusi alih-alih memercayai payload yang telah diubah.
## Fallback pengiriman agen
- Permintaan `agent` dapat menyertakan `deliver=true` untuk meminta pengiriman keluar.
- `bestEffortDeliver=false` mempertahankan perilaku ketat: target pengiriman yang tidak terselesaikan atau hanya-internal mengembalikan `INVALID_REQUEST`.
- `bestEffortDeliver=true` memungkinkan fallback ke eksekusi khusus sesi ketika tidak ada rute pengiriman eksternal yang dapat diselesaikan (misalnya sesi internal/webchat atau config multi-channel yang ambigu).
- `bestEffortDeliver=false` mempertahankan perilaku ketat: target pengiriman yang tidak ter-resolve atau hanya internal mengembalikan `INVALID_REQUEST`.
- `bestEffortDeliver=true` memungkinkan fallback ke eksekusi hanya-sesi saat tidak ada rute pengiriman eksternal yang dapat di-resolve (misalnya sesi internal/webchat atau config multi-channel yang ambigu).
## Pembuatan versi
@ -523,21 +534,21 @@ setiap helper yang dapat dipanggil yang diimplementasikan dalam `src/gateway/ser
### Konstanta klien
Klien referensi di `src/gateway/client.ts` menggunakan default berikut. Nilai-nilai ini
Klien referensi di `src/gateway/client.ts` menggunakan default ini. Nilai-nilai ini
stabil di seluruh protokol v3 dan merupakan baseline yang diharapkan untuk klien pihak ketiga.
| Constant | Default | Source |
| Konstanta | Default | Sumber |
| ----------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------- |
| `PROTOCOL_VERSION` | `3` | `src/gateway/protocol/schema/protocol-schemas.ts` |
| Timeout permintaan (per RPC) | `30_000` ms | `src/gateway/client.ts` (`requestTimeoutMs`) |
| Timeout preauth / connect-challenge | `10_000` ms | `src/gateway/handshake-timeouts.ts` (clamp `250`–`10_000`) |
| Backoff reconnect awal | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) |
| Backoff reconnect maksimum | `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) |
| Clamp percobaan ulang cepat setelah device-token close | `250` ms | `src/gateway/client.ts` |
| Masa tenggang force-stop sebelum `terminate()` | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` |
| Clamp retry cepat setelah penutupan device-token | `250` ms | `src/gateway/client.ts` |
| Grace force-stop sebelum `terminate()` | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` |
| Timeout default `stopAndWait()` | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` |
| Interval tick default (pra `hello-ok`) | `30_000` ms | `src/gateway/client.ts` |
| Penutupan karena timeout tick | kode `4000` ketika senyap melebihi `tickIntervalMs * 2` | `src/gateway/client.ts` |
| Penutupan karena timeout tick | kode `4000` saat senyap melebihi `tickIntervalMs * 2` | `src/gateway/client.ts` |
| `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024` (25 MB) | `src/gateway/server-constants.ts` |
Server mengiklankan `policy.tickIntervalMs`, `policy.maxPayload`,
@ -546,103 +557,103 @@ alih-alih default pra-handshake.
## Auth
- Auth gateway shared-secret menggunakan `connect.params.auth.token` atau
- Autentikasi gateway dengan shared secret menggunakan `connect.params.auth.token` atau
`connect.params.auth.password`, bergantung pada mode auth yang dikonfigurasi.
- Mode yang membawa identitas seperti Tailscale Serve
(`gateway.auth.allowTailscale: true`) atau `gateway.auth.mode: "trusted-proxy"`
non-loopback memenuhi pemeriksaan auth connect dari header permintaan, bukan dari
`connect.params.auth.*`.
- `gateway.auth.mode: "none"` untuk private-ingress melewati auth connect shared-secret
sepenuhnya; jangan mengekspos mode tersebut pada ingress publik/tidak tepercaya.
- Setelah pairing, Gateway menerbitkan **token perangkat** yang dibatasi pada peran + cakupan
koneksi. Token ini dikembalikan dalam `hello-ok.auth.deviceToken` dan harus
disimpan oleh klien untuk koneksi berikutnya.
- Klien harus menyimpan `hello-ok.auth.deviceToken` utama setelah setiap
non-loopback memenuhi pemeriksaan auth connect dari header permintaan,
bukan dari `connect.params.auth.*`.
- `gateway.auth.mode: "none"` untuk private-ingress sepenuhnya melewati auth connect berbasis shared secret;
jangan ekspose mode tersebut pada ingress publik/tidak tepercaya.
- Setelah pairing, Gateway menerbitkan **token perangkat** yang dibatasi ke peran + cakupan
koneksi. Token ini dikembalikan di `hello-ok.auth.deviceToken` dan harus
dipersistenkan oleh klien untuk koneksi berikutnya.
- Klien harus mempersistenkan `hello-ok.auth.deviceToken` utama setelah setiap
koneksi berhasil.
- Saat menyambung kembali dengan token perangkat **tersimpan** tersebut, klien juga harus menggunakan kembali
set cakupan tersimpan yang telah disetujui untuk token tersebut. Ini mempertahankan akses
baca/probe/status yang sudah diberikan dan menghindari reconnect yang diam-diam menyusut ke
cakupan implisit khusus admin yang lebih sempit.
- Saat terhubung ulang dengan token perangkat yang **tersimpan** itu, klien juga harus
menggunakan kembali kumpulan cakupan tersetujui yang tersimpan untuk token tersebut. Ini mempertahankan
akses baca/probe/status yang sudah diberikan dan mencegah reconnect diam-diam menyusut ke
cakupan implicit admin-only yang lebih sempit.
- Perakitan auth connect sisi klien (`selectConnectAuth` di
`src/gateway/client.ts`):
- `auth.password` bersifat ortogonal dan selalu diteruskan ketika disetel.
- `auth.token` diisi berdasarkan urutan prioritas: shared token eksplisit terlebih dahulu,
lalu `deviceToken` eksplisit, lalu token per-perangkat yang tersimpan (dikunci berdasarkan
- `auth.password` bersifat ortogonal dan selalu diteruskan saat disetel.
- `auth.token` diisi dalam urutan prioritas: shared token eksplisit terlebih dahulu,
lalu `deviceToken` eksplisit, lalu token per perangkat yang tersimpan (dikunci oleh
`deviceId` + `role`).
- `auth.bootstrapToken` hanya dikirim ketika tidak satu pun dari hal di atas me-resolve
sebuah `auth.token`. Shared token atau token perangkat apa pun yang ter-resolve akan menekannya.
- Auto-promotion token perangkat tersimpan pada percobaan ulang sekali jalan
- `auth.bootstrapToken` dikirim hanya saat tidak satu pun dari yang di atas menghasilkan
`auth.token`. Shared token atau token perangkat apa pun yang berhasil di-resolve akan menekannya.
- Auto-promotion token perangkat tersimpan pada retry sekali jalan
`AUTH_TOKEN_MISMATCH` dibatasi hanya untuk **endpoint tepercaya** —
loopback, atau `wss://` dengan `tlsFingerprint` yang dipin. `wss://` publik
tanpa pinning tidak memenuhi syarat.
- Entri tambahan `hello-ok.auth.deviceTokens` adalah token handoff bootstrap.
Simpan token tersebut hanya ketika connect menggunakan auth bootstrap pada transport tepercaya
seperti `wss://` atau loopback/pairing lokal.
- Jika klien menyuplai `deviceToken` **eksplisit** atau `scopes` eksplisit, maka
set cakupan yang diminta pemanggil tersebut tetap otoritatif; cakupan cache hanya
digunakan kembali ketika klien menggunakan ulang token per-perangkat yang tersimpan.
- Token perangkat dapat diputar/dicabut melalui `device.token.rotate` dan
Persistenkan hanya jika koneksi menggunakan auth bootstrap pada transport tepercaya
seperti `wss://` atau loopback/local pairing.
- Jika klien menyuplai `deviceToken` **eksplisit** atau `scopes` eksplisit, kumpulan cakupan
yang diminta pemanggil tersebut tetap menjadi otoritatif; cakupan cache hanya
digunakan kembali saat klien menggunakan ulang token per perangkat yang tersimpan.
- Token perangkat dapat dirotasi/dicabut melalui `device.token.rotate` dan
`device.token.revoke` (memerlukan cakupan `operator.pairing`).
- Penerbitan/rotasi token tetap dibatasi pada set peran yang disetujui dan tercatat dalam
entri pairing perangkat tersebut; memutar token tidak dapat memperluas perangkat ke
peran yang tidak pernah diberikan oleh approval pairing.
- Untuk sesi token perangkat berpasangan, pengelolaan perangkat dibatasi untuk dirinya sendiri kecuali
- Penerbitan/rotasi token tetap dibatasi pada kumpulan peran tersetujui yang tercatat dalam
entri pairing perangkat tersebut; merotasi token tidak dapat memperluas perangkat ke
peran yang tidak pernah diberikan oleh persetujuan pairing.
- Untuk sesi token perangkat berpasangan, manajemen perangkat dibatasi ke diri sendiri kecuali
pemanggil juga memiliki `operator.admin`: pemanggil non-admin hanya dapat
menghapus/mencabut/memutar entri perangkat **miliknya sendiri**.
- `device.token.rotate` juga memeriksa set cakupan operator yang diminta terhadap
cakupan sesi saat ini milik pemanggil. Pemanggil non-admin tidak dapat memutar token ke
set cakupan operator yang lebih luas daripada yang sudah mereka miliki.
menghapus/mencabut/merotasi entri perangkat **miliknya sendiri**.
- `device.token.rotate` juga memeriksa kumpulan cakupan operator yang diminta terhadap
cakupan sesi pemanggil saat ini. Pemanggil non-admin tidak dapat merotasi token ke
kumpulan cakupan operator yang lebih luas daripada yang sudah mereka miliki.
- Kegagalan auth menyertakan `error.details.code` plus petunjuk pemulihan:
- `error.details.canRetryWithDeviceToken` (boolean)
- `error.details.recommendedNextStep` (`retry_with_device_token`, `update_auth_configuration`, `update_auth_credentials`, `wait_then_retry`, `review_auth_configuration`)
- Perilaku klien untuk `AUTH_TOKEN_MISMATCH`:
- Klien tepercaya dapat mencoba satu percobaan ulang terbatas dengan token per-perangkat yang di-cache.
- Jika percobaan ulang itu gagal, klien harus menghentikan loop reconnect otomatis dan menampilkan panduan tindakan operator.
- Klien tepercaya dapat mencoba satu retry terbatas dengan token per perangkat yang di-cache.
- Jika retry itu gagal, klien harus menghentikan loop reconnect otomatis dan menampilkan panduan tindakan operator.
## Identitas perangkat + pairing
- Node harus menyertakan identitas perangkat yang stabil (`device.id`) yang diturunkan dari
fingerprint keypair.
- Gateway menerbitkan token per perangkat + peran.
- Approval pairing diperlukan untuk ID perangkat baru kecuali auto-approval lokal
- Persetujuan pairing diperlukan untuk ID perangkat baru kecuali auto-approval lokal
diaktifkan.
- Auto-approval pairing berpusat pada koneksi loopback lokal langsung.
- OpenClaw juga memiliki jalur self-connect backend/container-local yang sempit untuk
alur helper shared-secret tepercaya.
- Koneksi tailnet atau LAN pada host yang sama tetap diperlakukan sebagai koneksi jarak jauh untuk pairing dan
memerlukan approval.
- OpenClaw juga memiliki jalur self-connect backend/kontainer-lokal yang sempit untuk
alur helper shared secret tepercaya.
- Koneksi tailnet atau LAN host yang sama tetap diperlakukan sebagai koneksi remote untuk pairing dan
memerlukan persetujuan.
- Semua klien WS harus menyertakan identitas `device` selama `connect` (operator + node).
Control UI hanya dapat mengabaikannya dalam mode berikut:
Control UI hanya dapat menghilangkannya dalam mode ini:
- `gateway.controlUi.allowInsecureAuth=true` untuk kompatibilitas HTTP tidak aman khusus localhost.
- auth operator `gateway.auth.mode: "trusted-proxy"` Control UI yang berhasil.
- auth operator Control UI `gateway.auth.mode: "trusted-proxy"` yang berhasil.
- `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (break-glass, penurunan keamanan yang parah).
- Semua koneksi harus menandatangani nonce `connect.challenge` yang diberikan server.
### Diagnostik migrasi auth perangkat
Untuk klien lama yang masih menggunakan perilaku penandatanganan pra-challenge, `connect` sekarang mengembalikan
Untuk klien lama yang masih menggunakan perilaku penandatanganan pra-challenge, `connect` kini mengembalikan
kode detail `DEVICE_AUTH_*` di bawah `error.details.code` dengan `error.details.reason` yang stabil.
Kegagalan migrasi umum:
| Message | details.code | details.reason | Meaning |
| --------------------------- | -------------------------------- | ------------------------ | -------------------------------------------------- |
| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | Klien mengabaikan `device.nonce` (atau mengirim kosong). |
| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | Klien menandatangani dengan nonce yang stale/salah. |
| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | Payload tanda tangan tidak cocok dengan payload v2. |
| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | Stempel waktu yang ditandatangani berada di luar skew yang diizinkan. |
| Pesan | details.code | details.reason | Arti |
| --------------------------- | -------------------------------- | ------------------------ | --------------------------------------------------- |
| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | Klien tidak menyertakan `device.nonce` (atau mengirim kosong). |
| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | Klien menandatangani dengan nonce yang basi/salah. |
| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | Payload tanda tangan tidak cocok dengan payload v2. |
| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | Timestamp yang ditandatangani berada di luar skew yang diizinkan. |
| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` tidak cocok dengan fingerprint kunci publik. |
| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | Format/kanonisasi kunci publik gagal. |
| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | Format/kanonisasi kunci publik gagal. |
Target migrasi:
- Selalu tunggu `connect.challenge`.
- Tandatangani payload v2 yang menyertakan nonce server.
- Tanda tangani payload v2 yang menyertakan nonce server.
- Kirim nonce yang sama di `connect.params.device.nonce`.
- Payload tanda tangan yang disukai adalah `v3`, yang mengikat `platform` dan `deviceFamily`
selain field perangkat/klien/peran/cakupan/token/nonce.
- Tanda tangan `v2` lama tetap diterima untuk kompatibilitas, tetapi pinning metadata
perangkat berpasangan tetap mengontrol kebijakan perintah saat reconnect.
- Payload tanda tangan yang disarankan adalah `v3`, yang mengikat `platform` dan `deviceFamily`
selain field device/client/role/scopes/token/nonce.
- Tanda tangan `v2` lama tetap diterima untuk kompatibilitas, tetapi pinning metadata perangkat berpasangan
tetap mengontrol kebijakan perintah saat reconnect.
## TLS + pinning
@ -653,5 +664,5 @@ Target migrasi:
## Cakupan
Protokol ini mengekspos **API gateway lengkap** (status, channel, model, chat,
agent, sesi, node, approval, dll.). Permukaan persisnya didefinisikan oleh
agent, sesi, node, approval, dll.). Permukaan tepatnya didefinisikan oleh
skema TypeBox di `src/gateway/protocol/schema.ts`.

602
docs/id/help/testing.md
View File

File diff suppressed because it is too large Load Diff

160
docs/id/platforms/macos.md
View File

@ -1,50 +1,50 @@
---
read_when:
- Mengimplementasikan fitur app macOS
- Mengubah siklus hidup gateway atau bridging node di macOS
summary: App pendamping macOS OpenClaw (menu bar + broker gateway)
title: App macOS
- Mengimplementasikan fitur aplikasi macOS
- Mengubah siklus hidup Gateway atau bridging Node di macOS
summary: Aplikasi pendamping OpenClaw untuk macOS (bilah menu + broker Gateway)
title: Aplikasi macOS
x-i18n:
generated_at: "2026-04-05T14:01:08Z"
generated_at: "2026-04-17T09:14:23Z"
model: gpt-5.4
provider: openai
source_hash: bfac937e352ede495f60af47edf3b8e5caa5b692ba0ea01d9fb0de9a44bbc135
source_hash: d637df2f73ced110223c48ea3c934045d782e150a46495f434cf924a6a00baf0
source_path: platforms/macos.md
workflow: 15
---
# Pendamping macOS OpenClaw (menu bar + broker gateway)
# Pendamping OpenClaw untuk macOS (bilah menu + broker Gateway)
App macOS adalah **pendamping menu bar** untuk OpenClaw. App ini memiliki izin,
mengelola/terhubung ke Gateway secara lokal (launchd atau manual), dan mengekspos
kapabilitas macOS ke agen sebagai node.
Aplikasi macOS adalah **pendamping bilah menu** untuk OpenClaw. Aplikasi ini menangani izin,
mengelola/terhubung ke Gateway secara lokal (launchd atau manual), dan mengekspos kemampuan macOS
ke agen sebagai sebuah node.
## Yang dilakukan
## Apa yang dilakukan
- Menampilkan notifikasi native dan status di menu bar.
- Memiliki prompt TCC (Notifikasi, Accessibility, Screen Recording, Microphone,
Speech Recognition, Automation/AppleScript).
- Menjalankan atau terhubung ke Gateway (lokal atau remote).
- Mengekspos tool khusus macOS (Canvas, Camera, Screen Recording, `system.run`).
- Menampilkan notifikasi native dan status di bilah menu.
- Menangani prompt TCC (Notifikasi, Aksesibilitas, Perekaman Layar, Mikrofon,
Pengenalan Ucapan, Otomatisasi/AppleScript).
- Menjalankan atau terhubung ke Gateway (lokal atau jarak jauh).
- Mengekspos tool khusus macOS (Canvas, Kamera, Perekaman Layar, `system.run`).
- Memulai layanan host node lokal dalam mode **remote** (launchd), dan menghentikannya dalam mode **local**.
- Secara opsional meng-host **PeekabooBridge** untuk otomatisasi UI.
- Menginstal CLI global (`openclaw`) sesuai permintaan melalui npm, pnpm, atau bun (app lebih memilih npm, lalu pnpm, lalu bun; Node tetap menjadi runtime Gateway yang direkomendasikan).
- Menginstal CLI global (`openclaw`) atas permintaan melalui npm, pnpm, atau bun (aplikasi memprioritaskan npm, lalu pnpm, lalu bun; Node tetap menjadi runtime Gateway yang direkomendasikan).
## Mode lokal vs remote
## Mode local vs remote
- **Local** (default): app terhubung ke Gateway lokal yang sedang berjalan jika ada;
jika tidak, app mengaktifkan layanan launchd melalui `openclaw gateway install`.
- **Remote**: app terhubung ke Gateway melalui SSH/Tailscale dan tidak pernah memulai
- **Local** (default): aplikasi terhubung ke Gateway lokal yang sedang berjalan jika ada;
jika tidak, aplikasi mengaktifkan layanan launchd melalui `openclaw gateway install`.
- **Remote**: aplikasi terhubung ke Gateway melalui SSH/Tailscale dan tidak pernah memulai
proses lokal.
App memulai **layanan host node** lokal agar Gateway remote dapat menjangkau Mac ini.
App tidak menjalankan Gateway sebagai child process.
Discovery Gateway sekarang lebih mengutamakan nama Tailscale MagicDNS daripada IP tailnet mentah,
sehingga app Mac pulih dengan lebih andal saat IP tailnet berubah.
Aplikasi memulai **layanan host node** lokal agar Gateway jarak jauh dapat menjangkau Mac ini.
Aplikasi tidak men-spawn Gateway sebagai proses anak.
Discovery Gateway sekarang memprioritaskan nama Tailscale MagicDNS dibanding IP tailnet mentah,
sehingga aplikasi Mac pulih dengan lebih andal saat IP tailnet berubah.
## Kontrol Launchd
## Kontrol launchd
App mengelola LaunchAgent per pengguna berlabel `ai.openclaw.gateway`
(atau `ai.openclaw.<profile>` saat menggunakan `--profile`/`OPENCLAW_PROFILE`; `com.openclaw.*` lama masih akan di-unload).
Aplikasi mengelola LaunchAgent per-pengguna dengan label `ai.openclaw.gateway`
(atau `ai.openclaw.<profile>` saat menggunakan `--profile`/`OPENCLAW_PROFILE`; `com.openclaw.*` lama masih di-unload).
```bash
launchctl kickstart -k gui/$UID/ai.openclaw.gateway
@ -53,24 +53,24 @@ launchctl bootout gui/$UID/ai.openclaw.gateway
Ganti label dengan `ai.openclaw.<profile>` saat menjalankan profile bernama.
Jika LaunchAgent belum terinstal, aktifkan dari app atau jalankan
Jika LaunchAgent belum terinstal, aktifkan dari aplikasi atau jalankan
`openclaw gateway install`.
## Kapabilitas node (mac)
## Kemampuan Node (mac)
App macOS menampilkan dirinya sebagai node. Perintah umum:
Aplikasi macOS menampilkan dirinya sebagai sebuah node. Perintah umum:
- Canvas: `canvas.present`, `canvas.navigate`, `canvas.eval`, `canvas.snapshot`, `canvas.a2ui.*`
- Camera: `camera.snap`, `camera.clip`
- Screen: `screen.record`
- System: `system.run`, `system.notify`
- Kamera: `camera.snap`, `camera.clip`
- Layar: `screen.snapshot`, `screen.record`
- Sistem: `system.run`, `system.notify`
Node melaporkan peta `permissions` agar agen dapat memutuskan apa yang diizinkan.
Layanan node + IPC app:
Layanan Node + IPC aplikasi:
- Saat layanan host node headless berjalan (mode remote), layanan ini terhubung ke Gateway WS sebagai node.
- `system.run` dijalankan di app macOS (konteks UI/TCC) melalui Unix socket lokal; prompt + output tetap berada di dalam app.
- Saat layanan host node headless berjalan (mode remote), layanan tersebut terhubung ke Gateway WS sebagai node.
- `system.run` dijalankan di aplikasi macOS (konteks UI/TCC) melalui socket Unix lokal; prompt + output tetap di dalam aplikasi.
Diagram (SCI):
@ -81,10 +81,10 @@ Gateway -> Node Service (WS)
Mac App (UI + TCC + system.run)
```
## Exec approvals (`system.run`)
## Persetujuan exec (`system.run`)
`system.run` dikendalikan oleh **Exec approvals** di app macOS (Settings → Exec approvals).
Security + ask + allowlist disimpan secara lokal di Mac dalam:
`system.run` dikendalikan oleh **Persetujuan exec** di aplikasi macOS (Pengaturan → Persetujuan exec).
Keamanan + tanya + allowlist disimpan secara lokal di Mac dalam:
```
~/.openclaw/exec-approvals.json
@ -111,22 +111,22 @@ Contoh:
Catatan:
- Entri `allowlist` adalah pola glob untuk jalur binary yang sudah di-resolve.
- Teks perintah shell mentah yang berisi sintaks kontrol atau ekspansi shell (`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`) diperlakukan sebagai kegagalan allowlist dan memerlukan persetujuan eksplisit (atau memasukkan binary shell ke allowlist).
- Memilih “Always Allow” pada prompt menambahkan perintah tersebut ke allowlist.
- Override environment `system.run` difilter (menghapus `PATH`, `DYLD_*`, `LD_*`, `NODE_OPTIONS`, `PYTHON*`, `PERL*`, `RUBYOPT`, `SHELLOPTS`, `PS4`) lalu digabungkan dengan environment app.
- Untuk shell wrapper (`bash|sh|zsh ... -c/-lc`), override environment dengan cakupan permintaan dikurangi menjadi allowlist eksplisit kecil (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`).
- Untuk keputusan allow-always dalam mode allowlist, wrapper dispatch yang dikenal (`env`, `nice`, `nohup`, `stdbuf`, `timeout`) menyimpan jalur executable bagian dalam, bukan jalur wrapper. Jika unwrapping tidak aman, tidak ada entri allowlist yang disimpan otomatis.
- Entri `allowlist` adalah pola glob untuk path biner yang telah di-resolve.
- Teks perintah shell mentah yang berisi sintaks kontrol atau ekspansi shell (`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`) diperlakukan sebagai allowlist miss dan memerlukan persetujuan eksplisit (atau menambahkan biner shell ke allowlist).
- Memilih “Always Allow” di prompt akan menambahkan perintah tersebut ke allowlist.
- Override environment `system.run` difilter (menghapus `PATH`, `DYLD_*`, `LD_*`, `NODE_OPTIONS`, `PYTHON*`, `PERL*`, `RUBYOPT`, `SHELLOPTS`, `PS4`) lalu digabungkan dengan environment aplikasi.
- Untuk wrapper shell (`bash|sh|zsh ... -c/-lc`), override environment dengan cakupan permintaan dikurangi menjadi allowlist eksplisit kecil (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`).
- Untuk keputusan selalu-izinkan dalam mode allowlist, wrapper dispatch yang dikenal (`env`, `nice`, `nohup`, `stdbuf`, `timeout`) menyimpan path executable internal, bukan path wrapper. Jika unwrap tidak aman, tidak ada entri allowlist yang disimpan secara otomatis.
## Deep link
App mendaftarkan skema URL `openclaw://` untuk tindakan lokal.
Aplikasi mendaftarkan skema URL `openclaw://` untuk aksi lokal.
### `openclaw://agent`
Memicu permintaan `agent` Gateway.
__OC_I18N_900004__
Parameter kueri:
Parameter query:
- `message` (wajib)
- `sessionKey` (opsional)
@ -137,86 +137,86 @@ Parameter kueri:
Keamanan:
- Tanpa `key`, app meminta konfirmasi.
- Tanpa `key`, app menerapkan batas pesan singkat untuk prompt konfirmasi dan mengabaikan `deliver` / `to` / `channel`.
- Dengan `key` yang valid, eksekusi berjalan tanpa pengawasan (ditujukan untuk otomatisasi pribadi).
- Tanpa `key`, aplikasi meminta konfirmasi.
- Tanpa `key`, aplikasi menerapkan batas pesan singkat untuk prompt konfirmasi dan mengabaikan `deliver` / `to` / `channel`.
- Dengan `key` yang valid, proses berjalan tanpa pengawasan (ditujukan untuk otomatisasi pribadi).
## Alur onboarding (umum)
1. Instal dan jalankan **OpenClaw.app**.
2. Selesaikan checklist izin (prompt TCC).
2. Selesaikan daftar periksa izin (prompt TCC).
3. Pastikan mode **Local** aktif dan Gateway berjalan.
4. Instal CLI jika Anda menginginkan akses terminal.
4. Instal CLI jika Anda ingin akses terminal.
## Penempatan state dir (macOS)
## Penempatan direktori state (macOS)
Hindari menempatkan state dir OpenClaw Anda di iCloud atau folder lain yang disinkronkan ke cloud.
Jalur yang didukung sinkronisasi dapat menambah latensi dan terkadang menyebabkan race file-lock/sinkronisasi untuk
Hindari menempatkan direktori state OpenClaw Anda di iCloud atau folder lain yang disinkronkan ke cloud.
Path yang didukung sinkronisasi dapat menambah latensi dan sesekali menyebabkan race file-lock/sinkronisasi untuk
sesi dan kredensial.
Lebih baik gunakan jalur state lokal yang tidak disinkronkan seperti:
Utamakan path state lokal yang tidak disinkronkan seperti:
__OC_I18N_900005__
Jika `openclaw doctor` mendeteksi state di bawah:
- `~/Library/Mobile Documents/com~apple~CloudDocs/...`
- `~/Library/CloudStorage/...`
maka tool tersebut akan memperingatkan dan merekomendasikan pemindahan kembali ke jalur lokal.
aplikasi akan memperingatkan dan merekomendasikan untuk memindahkannya kembali ke path lokal.
## Alur build & dev (native)
## Workflow build & pengembangan (native)
- `cd apps/macos && swift build`
- `swift run OpenClaw` (atau Xcode)
- Package app: `scripts/package-mac-app.sh`
- Paketkan aplikasi: `scripts/package-mac-app.sh`
## Debug konektivitas gateway (CLI macOS)
Gunakan CLI debug untuk menjalankan handshake WebSocket Gateway dan logika discovery yang sama
seperti yang digunakan app macOS, tanpa meluncurkan app.
Gunakan CLI debug untuk menguji logika handshake dan discovery WebSocket Gateway yang sama
dengan yang digunakan aplikasi macOS, tanpa meluncurkan aplikasi.
__OC_I18N_900006__
Opsi connect:
- `--url <ws://host:port>`: override config
- `--mode <local|remote>`: resolve dari config (default: config atau local)
- `--probe`: paksa health probe baru
- `--timeout <ms>`: timeout permintaan (default: `15000`)
- `--timeout <ms>`: request timeout (default: `15000`)
- `--json`: output terstruktur untuk diffing
Opsi discovery:
- `--include-local`: sertakan gateway yang akan difilter sebagai “local”
- `--include-local`: sertakan gateway yang seharusnya difilter sebagai “local”
- `--timeout <ms>`: jendela discovery keseluruhan (default: `2000`)
- `--json`: output terstruktur untuk diffing
Tip: bandingkan dengan `openclaw gateway discover --json` untuk melihat apakah
pipeline discovery app macOS (`local.` ditambah domain wide-area yang dikonfigurasi, dengan
Tips: bandingkan dengan `openclaw gateway discover --json` untuk melihat apakah
pipeline discovery aplikasi macOS (`local.` ditambah domain wide-area yang dikonfigurasi, dengan
fallback wide-area dan Tailscale Serve) berbeda dari
discovery berbasis `dns-sd` milik Node CLI.
discovery berbasis `dns-sd` milik CLI Node.
## Plumbing koneksi remote (tunnel SSH)
Saat app macOS berjalan dalam mode **Remote**, app membuka tunnel SSH agar komponen UI lokal
dapat berbicara dengan Gateway remote seolah-olah berada di localhost.
Saat aplikasi macOS berjalan dalam mode **Remote**, aplikasi membuka tunnel SSH agar komponen UI lokal
dapat berbicara dengan Gateway jarak jauh seolah-olah berada di localhost.
### Control tunnel (port WebSocket Gateway)
### Tunnel kontrol (port WebSocket Gateway)
- **Tujuan:** health check, status, Web Chat, config, dan panggilan control-plane lainnya.
- **Port lokal:** port Gateway (default `18789`), selalu stabil.
- **Port remote:** port Gateway yang sama pada host remote.
- **Perilaku:** tidak ada port lokal acak; app menggunakan kembali tunnel sehat yang sudah ada
atau me-restart-nya bila perlu.
- **Perilaku:** tidak ada port lokal acak; aplikasi menggunakan kembali tunnel sehat yang ada
atau memulainya ulang jika diperlukan.
- **Bentuk SSH:** `ssh -N -L <local>:127.0.0.1:<remote>` dengan opsi BatchMode +
ExitOnForwardFailure + keepalive.
- **Pelaporan IP:** tunnel SSH menggunakan loopback, jadi gateway akan melihat
IP node sebagai `127.0.0.1`. Gunakan transport **Direct (ws/wss)** jika Anda ingin
IP klien asli terlihat (lihat [akses remote macOS](/platforms/mac/remote)).
- **Pelaporan IP:** tunnel SSH menggunakan loopback, sehingga gateway akan melihat
IP node sebagai `127.0.0.1`. Gunakan transport **Direct (ws/wss)** jika Anda ingin IP klien
yang sebenarnya muncul (lihat [akses remote macOS](/id/platforms/mac/remote)).
Untuk langkah penyiapan, lihat [akses remote macOS](/platforms/mac/remote). Untuk detail
protokol, lihat [Protokol gateway](/id/gateway/protocol).
Untuk langkah penyiapan, lihat [akses remote macOS](/id/platforms/mac/remote). Untuk detail
protokol, lihat [protokol Gateway](/id/gateway/protocol).
## Dokumen terkait
- [Runbook Gateway](/id/gateway)
- [Gateway (macOS)](/platforms/mac/bundled-gateway)
- [Izin macOS](/platforms/mac/permissions)
- [Canvas](/platforms/mac/canvas)
- [Gateway (macOS)](/id/platforms/mac/bundled-gateway)
- [Izin macOS](/id/platforms/mac/permissions)
- [Canvas](/id/platforms/mac/canvas)

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

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

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

@ -1,16 +1,16 @@
---
read_when:
- Anda perlu mengetahui subpath SDK mana yang harus diimpor dari sana
- Anda menginginkan referensi untuk semua metode pendaftaran pada OpenClawPluginApi
- Anda menginginkan referensi untuk semua metode pendaftaran pada `OpenClawPluginApi`
- Anda sedang mencari ekspor SDK tertentu
sidebarTitle: SDK Overview
summary: Peta import, referensi API pendaftaran, dan arsitektur SDK
summary: Peta impor, referensi API pendaftaran, dan arsitektur SDK
title: Ikhtisar Plugin SDK
x-i18n:
generated_at: "2026-04-11T02:46:24Z"
generated_at: "2026-04-17T09:14:19Z"
model: gpt-5.4
provider: openai
source_hash: 4bfeb5896f68e3e4ee8cf434d43a019e0d1fe5af57f5bf7a5172847c476def0c
source_hash: b177fdb6830f415d998a24812bc2c7db8124d3ba77b0174c9a67ac7d747f7e5a
source_path: plugins/sdk-overview.md
workflow: 15
---
@ -38,34 +38,35 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
Setiap subpath adalah modul kecil yang berdiri sendiri. Ini menjaga startup tetap cepat dan
mencegah masalah circular dependency. Untuk helper entry/build khusus channel,
gunakan `openclaw/plugin-sdk/channel-core`; simpan `openclaw/plugin-sdk/core` untuk
gunakan `openclaw/plugin-sdk/channel-core`; gunakan `openclaw/plugin-sdk/core` untuk
permukaan 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 kemudahan bernama provider 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
ketika kebutuhan itu benar-benar lintas channel.
seam helper bermerek channel. Bundled plugin sebaiknya menyusun
subpath SDK generik di dalam barrel `api.ts` atau `runtime-api.ts` mereka sendiri, dan core
sebaiknya menggunakan barrel lokal plugin tersebut atau menambahkan kontrak SDK generik yang sempit
saat kebutuhannya benar-benar lintas channel.
Peta ekspor yang dihasilkan masih berisi sekumpulan kecil seam helper
plugin bawaan seperti `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`,
Peta ekspor yang dihasilkan masih berisi sekumpulan kecil
seam helper bundled-plugin seperti `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`,
`plugin-sdk/zalo`, `plugin-sdk/zalo-setup`, dan `plugin-sdk/matrix*`. Subpath
tersebut hanya ada untuk pemeliharaan dan kompatibilitas plugin bawaan; subpath itu
sengaja dihilangkan dari tabel umum di bawah ini dan bukan jalur impor yang direkomendasikan untuk plugin pihak ketiga yang baru.
tersebut hanya ada untuk pemeliharaan bundled-plugin dan kompatibilitas; subpath itu
sengaja tidak disertakan dari tabel umum di bawah dan bukan jalur impor yang
direkomendasikan untuk plugin pihak ketiga yang baru.
## Referensi subpath
Subpath yang paling umum digunakan, dikelompokkan berdasarkan tujuan. Daftar lengkap yang dihasilkan
berisi lebih dari 200 subpath dan berada di `scripts/lib/plugin-sdk-entrypoints.json`.
Subpath yang paling umum digunakan, dikelompokkan berdasarkan tujuan. Daftar lengkap
200+ subpath yang dihasilkan ada di `scripts/lib/plugin-sdk-entrypoints.json`.
Subpath helper plugin bawaan yang dicadangkan masih muncul dalam daftar yang dihasilkan itu.
Perlakukan itu sebagai detail implementasi/permukaan kompatibilitas kecuali sebuah halaman docs
Subpath helper bundled-plugin yang dicadangkan masih muncul dalam daftar yang dihasilkan itu.
Perlakukan itu sebagai detail implementasi/permukaan kompatibilitas kecuali suatu halaman dokumentasi
secara eksplisit mempromosikannya sebagai publik.
### Entri plugin
### Entry plugin
| Subpath | Ekspor utama |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
@ -80,73 +81,73 @@ secara eksplisit mempromosikannya sebagai publik.
| --- | --- |
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/config-schema` | Ekspor skema Zod root `openclaw.json` (`OpenClawSchema`) |
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, ditambah `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, plus `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
| `plugin-sdk/setup` | Helper wizard setup bersama, prompt allowlist, pembuat status setup |
| `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
| `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/account-core` | Helper config multi-akun/action-gate, helper fallback akun default |
| `plugin-sdk/account-core` | Helper multi-account config/action-gate, helper fallback akun default |
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, helper normalisasi account-id |
| `plugin-sdk/account-resolution` | Helper lookup akun + fallback default |
| `plugin-sdk/account-helpers` | Helper sempit daftar-aksi akun/aksi akun |
| `plugin-sdk/account-resolution` | Pencarian akun + helper fallback default |
| `plugin-sdk/account-helpers` | Helper sempit account-list/account-action |
| `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/telegram-command-config` | Helper normalisasi/validasi custom-command Telegram dengan fallback kontrak bundled |
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` |
| `plugin-sdk/inbound-envelope` | Helper bersama route masuk + pembuat envelope |
| `plugin-sdk/inbound-reply-dispatch` | Helper bersama rekam-dan-dispatch masuk |
| `plugin-sdk/inbound-envelope` | Helper rute inbound + pembuat 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 bersama pemuatan media keluar |
| `plugin-sdk/outbound-runtime` | Helper identitas keluar/delegasi kirim |
| `plugin-sdk/outbound-media` | Helper pemuatan media outbound bersama |
| `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` | Pembuat payload media agen lama |
| `plugin-sdk/conversation-runtime` | Thread binding/percakapan, pairing, dan helper configured-binding |
| `plugin-sdk/agent-media-payload` | Pembuat payload media agent lama |
| `plugin-sdk/conversation-runtime` | Helper binding percakapan/thread, pairing, dan binding yang dikonfigurasi |
| `plugin-sdk/runtime-config-snapshot` | Helper snapshot config runtime |
| `plugin-sdk/runtime-group-policy` | Helper resolusi group-policy runtime |
| `plugin-sdk/channel-status` | Helper bersama snapshot/ringkasan status channel |
| `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/group-access` | Helper bersama keputusan akses grup |
| `plugin-sdk/direct-dm` | Helper bersama auth/guard DM langsung |
| `plugin-sdk/interactive-runtime` | Helper normalisasi/reduksi payload balasan interaktif |
| `plugin-sdk/channel-inbound` | Debounce masuk, pencocokan mention, helper kebijakan mention, dan helper envelope |
| `plugin-sdk/group-access` | Helper keputusan akses grup bersama |
| `plugin-sdk/direct-dm` | Helper auth/guard direct-DM bersama |
| `plugin-sdk/interactive-runtime` | Helper normalisasi/pengurangan payload balasan interaktif |
| `plugin-sdk/channel-inbound` | Debounce inbound, pencocokan mention, helper 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-feedback` | Wiring umpan balik/reaksi |
| `plugin-sdk/channel-secret-runtime` | Helper kontrak secret sempit seperti `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, dan tipe target secret |
</Accordion>
<Accordion title="Subpath provider">
| Subpath | Ekspor 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 yang kompatibel dengan OpenAI dan terfokus |
| `plugin-sdk/provider-setup` | Helper setup provider lokal/self-hosted yang dikurasi |
| `plugin-sdk/self-hosted-provider-setup` | Helper setup provider 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-api-key` | Helper onboarding/penulisan profil API key seperti `upsertApiKeyProfile` |
| `plugin-sdk/provider-auth-result` | Pembuat hasil auth OAuth standar |
| `plugin-sdk/provider-auth-login` | Helper login interaktif bersama untuk plugin provider |
| `plugin-sdk/provider-env-vars` | Helper lookup env var auth provider |
| `plugin-sdk/provider-env-vars` | Helper pencarian env var auth provider |
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, pembuat replay-policy bersama, helper endpoint provider, dan helper normalisasi model-id seperti `normalizeNativeXaiModelId` |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, pembuat kebijakan replay bersama, helper endpoint provider, dan helper normalisasi model-id seperti `normalizeNativeXaiModelId` |
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-http` | Helper kemampuan HTTP/endpoint provider generik |
| `plugin-sdk/provider-web-fetch-contract` | Helper kontrak config/seleksi web-fetch yang sempit seperti `enablePluginInConfig` dan `WebFetchProviderPlugin` |
| `plugin-sdk/provider-http` | Helper kapabilitas HTTP/endpoint provider generik |
| `plugin-sdk/provider-web-fetch-contract` | Helper kontrak config/pemilihan web-fetch 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 plugin-enable |
| `plugin-sdk/provider-web-search-contract` | Helper kontrak config/kredensial web-search yang sempit seperti `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`, dan setter/getter kredensial yang dibatasi scope |
| `plugin-sdk/provider-web-search-config-contract` | Helper config/kredensial web-search sempit untuk provider yang tidak memerlukan wiring enable plugin |
| `plugin-sdk/provider-web-search-contract` | Helper kontrak config/kredensial web-search sempit seperti `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`, dan setter/getter kredensial berscope |
| `plugin-sdk/provider-web-search` | Helper pendaftaran/cache/runtime provider web-search |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, pembersihan + diagnostik skema Gemini, dan helper kompatibilitas xAI seperti `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` dan yang serupa |
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipe pembungkus stream, dan helper pembungkus bersama Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipe wrapper stream, dan helper wrapper bersama Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
| `plugin-sdk/provider-onboard` | Helper patch config onboarding |
| `plugin-sdk/global-singleton` | Helper singleton/map/cache lokal-proses |
</Accordion>
@ -154,113 +155,113 @@ secara eksplisit mempromosikannya sebagai publik.
<Accordion title="Subpath auth dan keamanan">
| Subpath | Ekspor utama |
| --- | --- |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`, helper registry perintah, helper otorisasi pengirim |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`, helper registri perintah, helper otorisasi pengirim |
| `plugin-sdk/command-status` | Pembuat pesan perintah/help seperti `buildCommandsMessagePaginated` dan `buildHelpMessage` |
| `plugin-sdk/approval-auth-runtime` | Resolusi approver dan helper action-auth chat yang sama |
| `plugin-sdk/approval-client-runtime` | Helper profil/filter persetujuan exec native |
| `plugin-sdk/approval-auth-runtime` | Resolusi approver dan helper action-auth dalam chat yang sama |
| `plugin-sdk/approval-client-runtime` | Helper profil/filter persetujuan native exec |
| `plugin-sdk/approval-delivery-runtime` | Adapter kapabilitas/pengiriman persetujuan native |
| `plugin-sdk/approval-gateway-runtime` | Helper bersama resolusi gateway persetujuan |
| `plugin-sdk/approval-handler-adapter-runtime` | Helper ringan pemuatan adapter persetujuan native untuk entrypoint channel yang hot |
| `plugin-sdk/approval-handler-runtime` | Helper runtime approval yang lebih luas; gunakan seam adapter/gateway yang lebih sempit bila itu sudah cukup |
| `plugin-sdk/approval-native-runtime` | Helper target persetujuan native + account-binding |
| `plugin-sdk/approval-gateway-runtime` | Helper resolusi Gateway persetujuan bersama |
| `plugin-sdk/approval-handler-adapter-runtime` | Helper pemuatan adapter persetujuan native ringan untuk entrypoint channel hot |
| `plugin-sdk/approval-handler-runtime` | Helper runtime penangan persetujuan yang lebih luas; gunakan seam adapter/gateway yang lebih sempit saat itu sudah cukup |
| `plugin-sdk/approval-native-runtime` | Helper target persetujuan native + binding akun |
| `plugin-sdk/approval-reply-runtime` | Helper payload balasan persetujuan exec/plugin |
| `plugin-sdk/command-auth-native` | Auth perintah native + helper target sesi native |
| `plugin-sdk/command-detection` | Helper bersama deteksi perintah |
| `plugin-sdk/command-auth-native` | Auth perintah native + helper session-target native |
| `plugin-sdk/command-detection` | Helper deteksi perintah bersama |
| `plugin-sdk/command-surface` | Normalisasi isi perintah dan helper permukaan perintah |
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
| `plugin-sdk/channel-secret-runtime` | Helper pengumpulan kontrak secret yang sempit untuk permukaan secret channel/plugin |
| `plugin-sdk/secret-ref-runtime` | Helper `coerceSecretRef` yang sempit dan helper pengetikan SecretRef untuk parsing kontrak secret/config |
| `plugin-sdk/security-runtime` | Helper bersama trust, gating DM, konten eksternal, dan pengumpulan secret |
| `plugin-sdk/channel-secret-runtime` | Helper pengumpulan kontrak secret sempit untuk permukaan secret channel/plugin |
| `plugin-sdk/secret-ref-runtime` | Helper `coerceSecretRef` sempit dan pengetikan SecretRef untuk parsing kontrak secret/config |
| `plugin-sdk/security-runtime` | Helper trust, gating DM, konten eksternal, dan pengumpulan secret bersama |
| `plugin-sdk/ssrf-policy` | Helper kebijakan SSRF allowlist host dan jaringan privat |
| `plugin-sdk/ssrf-runtime` | Dispatcher yang dipin, fetch yang dijaga SSRF, dan helper kebijakan SSRF |
| `plugin-sdk/ssrf-runtime` | Helper pinned-dispatcher, fetch yang dijaga SSRF, dan kebijakan SSRF |
| `plugin-sdk/secret-input` | Helper parsing input secret |
| `plugin-sdk/webhook-ingress` | Helper permintaan/target webhook |
| `plugin-sdk/webhook-request-guards` | Helper ukuran isi permintaan/timeout |
| `plugin-sdk/webhook-ingress` | Helper permintaan/target Webhook |
| `plugin-sdk/webhook-request-guards` | Helper ukuran body/timeout permintaan |
</Accordion>
<Accordion title="Subpath runtime dan penyimpanan">
| Subpath | Ekspor utama |
| --- | --- |
| `plugin-sdk/runtime` | Helper runtime/logging/backup/instalasi plugin yang luas |
| `plugin-sdk/runtime-env` | Helper sempit env runtime, logger, timeout, retry, dan backoff |
| `plugin-sdk/channel-runtime-context` | Helper registrasi dan lookup generic channel runtime-context |
| `plugin-sdk/runtime-env` | Helper runtime env, logger, timeout, retry, dan backoff yang sempit |
| `plugin-sdk/channel-runtime-context` | Helper pendaftaran dan lookup runtime-context channel generik |
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
| `plugin-sdk/plugin-runtime` | Helper bersama perintah/hook/http/interaktif plugin |
| `plugin-sdk/hook-runtime` | Helper bersama pipeline webhook/internal hook |
| `plugin-sdk/plugin-runtime` | Helper perintah/hook/http/interaktif plugin bersama |
| `plugin-sdk/hook-runtime` | Helper pipeline Webhook/hook internal bersama |
| `plugin-sdk/lazy-runtime` | Helper impor/binding runtime lazy seperti `createLazyRuntimeModule`, `createLazyRuntimeMethod`, dan `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | Helper exec proses |
| `plugin-sdk/cli-runtime` | Helper formatting, wait, dan versi CLI |
| `plugin-sdk/gateway-runtime` | Klien gateway dan helper patch status channel |
| `plugin-sdk/config-runtime` | Helper pemuatan/penulisan config |
| `plugin-sdk/gateway-runtime` | Helper klien Gateway dan patch status channel |
| `plugin-sdk/config-runtime` | Helper muat/tulis config |
| `plugin-sdk/telegram-command-config` | Normalisasi nama/deskripsi perintah Telegram dan pemeriksaan duplikat/konflik, bahkan saat permukaan kontrak Telegram bawaan tidak tersedia |
| `plugin-sdk/approval-runtime` | Helper persetujuan exec/plugin, pembuat kapabilitas persetujuan, helper auth/profil, helper routing/runtime native |
| `plugin-sdk/reply-runtime` | Helper bersama runtime inbound/balasan, chunking, dispatch, heartbeat, perencana balasan |
| `plugin-sdk/reply-dispatch-runtime` | Helper sempit dispatch/finalisasi balasan |
| `plugin-sdk/reply-history` | Helper bersama riwayat balasan jendela pendek seperti `buildHistoryContext`, `recordPendingHistoryEntry`, dan `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-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-reference` | `createReplyReferencePlanner` |
| `plugin-sdk/reply-chunking` | Helper sempit chunking teks/markdown |
| `plugin-sdk/session-store-runtime` | Helper jalur session store + updated-at |
| `plugin-sdk/state-paths` | Helper jalur direktori status/OAuth |
| `plugin-sdk/routing` | Helper route/session-key/account binding seperti `resolveAgentRoute`, `buildAgentSessionKey`, dan `resolveDefaultAgentBoundAccountId` |
| `plugin-sdk/status-helpers` | Helper bersama ringkasan status channel/akun, default status runtime, dan helper metadata issue |
| `plugin-sdk/target-resolver-runtime` | Helper bersama target resolver |
| `plugin-sdk/reply-chunking` | Helper chunking teks/markdown yang sempit |
| `plugin-sdk/session-store-runtime` | Helper path penyimpanan sesi + updated-at |
| `plugin-sdk/state-paths` | Helper path direktori state/OAuth |
| `plugin-sdk/routing` | Helper rute/session-key/binding akun seperti `resolveAgentRoute`, `buildAgentSessionKey`, dan `resolveDefaultAgentBoundAccountId` |
| `plugin-sdk/status-helpers` | Helper ringkasan status channel/akun bersama, default runtime-state, dan helper metadata issue |
| `plugin-sdk/target-resolver-runtime` | Helper resolver target bersama |
| `plugin-sdk/string-normalization-runtime` | Helper normalisasi slug/string |
| `plugin-sdk/request-url` | Mengekstrak URL string dari input mirip fetch/request |
| `plugin-sdk/run-command` | Runner perintah bertimer dengan hasil stdout/stderr ternormalisasi |
| `plugin-sdk/request-url` | Ekstrak URL string dari input mirip fetch/request |
| `plugin-sdk/run-command` | Runner perintah bertimer dengan hasil stdout/stderr yang dinormalisasi |
| `plugin-sdk/param-readers` | Pembaca param tool/CLI umum |
| `plugin-sdk/tool-payload` | Mengekstrak payload ternormalisasi dari objek hasil tool |
| `plugin-sdk/tool-send` | Mengekstrak field target pengiriman kanonis dari argumen tool |
| `plugin-sdk/temp-path` | Helper bersama jalur unduhan sementara |
| `plugin-sdk/logging-core` | Logger subsystem dan helper redaksi |
| `plugin-sdk/tool-payload` | Ekstrak payload yang dinormalisasi dari objek hasil tool |
| `plugin-sdk/tool-send` | Ekstrak field target pengiriman kanonis dari argumen tool |
| `plugin-sdk/temp-path` | Helper path unduhan sementara bersama |
| `plugin-sdk/logging-core` | Helper logger subsistem dan redaksi |
| `plugin-sdk/markdown-table-runtime` | Helper mode tabel Markdown |
| `plugin-sdk/json-store` | Helper kecil baca/tulis status JSON |
| `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 agen |
| `plugin-sdk/agent-config-primitives` | Primitive skema config runtime agent 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 token bootstrap perangkat dan pairing |
| `plugin-sdk/extension-shared` | Primitive helper bersama passive-channel, status, dan ambient proxy |
| `plugin-sdk/device-bootstrap` | Helper bootstrap perangkat dan token pairing |
| `plugin-sdk/extension-shared` | Primitive helper proxy ambient, status, dan channel pasif bersama |
| `plugin-sdk/models-provider-runtime` | Helper balasan provider/perintah `/models` |
| `plugin-sdk/skill-commands-runtime` | Helper daftar perintah Skills |
| `plugin-sdk/native-command-registry` | Helper registri/build/serialisasi perintah native |
| `plugin-sdk/agent-harness` | Permukaan plugin tepercaya eksperimental untuk agent harness tingkat rendah: tipe harness, helper steer/abort eksekusi aktif, helper jembatan tool OpenClaw, dan utilitas hasil percobaan |
| `plugin-sdk/provider-zai-endpoint` | Helper deteksi endpoint Z.AI |
| `plugin-sdk/infra-runtime` | Helper event sistem/heartbeat |
| `plugin-sdk/agent-harness` | Permukaan plugin tepercaya eksperimental untuk harness agent level rendah: tipe harness, helper steer/abort active-run, helper jembatan tool OpenClaw, dan utilitas hasil attempt |
| `plugin-sdk/provider-zai-endpoint` | Helper deteksi endpoint Z.A.I |
| `plugin-sdk/infra-runtime` | Helper event sistem/Heartbeat |
| `plugin-sdk/collection-runtime` | Helper cache kecil yang dibatasi |
| `plugin-sdk/diagnostic-runtime` | Helper flag dan event diagnostik |
| `plugin-sdk/error-runtime` | Grafik error, formatting, helper klasifikasi error bersama, `isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | Helper fetch terbungkus, proxy, dan lookup yang dipin |
| `plugin-sdk/error-runtime` | Helper graf error, formatting, klasifikasi error bersama, `isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | Wrapped fetch, proxy, dan helper lookup yang dipin |
| `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 agen |
| `plugin-sdk/directory-runtime` | Query/deduplikasi direktori berbasis config |
| `plugin-sdk/agent-runtime` | Helper direktori/identitas/workspace agent |
| `plugin-sdk/directory-runtime` | Query/dedupe direktori berbasis config |
| `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
</Accordion>
<Accordion title="Subpath kapabilitas dan pengujian">
| Subpath | Ekspor utama |
| --- | --- |
| `plugin-sdk/media-runtime` | Helper bersama fetch/transform/store media ditambah pembuat payload media |
| `plugin-sdk/media-generation-runtime` | Helper bersama failover media-generation, pemilihan kandidat, dan pesan model yang hilang |
| `plugin-sdk/media-understanding` | Tipe provider media understanding ditambah ekspor helper gambar/audio yang menghadap provider |
| `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 keluar |
| `plugin-sdk/speech` | Tipe provider speech ditambah helper directive, registry, dan validasi yang menghadap provider |
| `plugin-sdk/speech-core` | Helper bersama tipe provider speech, registry, directive, dan normalisasi |
| `plugin-sdk/realtime-transcription` | Tipe provider realtime transcription dan helper registry |
| `plugin-sdk/realtime-voice` | Tipe provider realtime voice dan helper registry |
| `plugin-sdk/image-generation` | Tipe provider image generation |
| `plugin-sdk/image-generation-core` | Helper bersama tipe image-generation, failover, auth, dan registry |
| `plugin-sdk/music-generation` | Tipe provider/request/result music generation |
| `plugin-sdk/music-generation-core` | Helper bersama tipe music-generation, helper failover, lookup provider, dan parsing model-ref |
| `plugin-sdk/video-generation` | Tipe provider/request/result video generation |
| `plugin-sdk/video-generation-core` | Helper bersama tipe video-generation, helper failover, lookup provider, dan parsing model-ref |
| `plugin-sdk/webhook-targets` | Registry target webhook dan helper instalasi route |
| `plugin-sdk/webhook-path` | Helper normalisasi jalur webhook |
| `plugin-sdk/web-media` | Helper bersama pemuatan media remote/lokal |
| `plugin-sdk/zod` | `zod` yang diekspor ulang untuk konsumen Plugin SDK |
| `plugin-sdk/media-runtime` | Helper fetch/transform/store media bersama plus pembuat payload media |
| `plugin-sdk/media-generation-runtime` | Helper failover pembuatan media bersama, pemilihan kandidat, dan pesan model yang hilang |
| `plugin-sdk/media-understanding` | Tipe provider pemahaman media 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 direktif, dan utilitas safe-text |
| `plugin-sdk/text-chunking` | Helper chunking teks outbound |
| `plugin-sdk/speech` | Tipe provider speech plus helper direktif, registri, dan validasi yang menghadap provider |
| `plugin-sdk/speech-core` | Tipe provider speech, registri, direktif, dan helper normalisasi bersama |
| `plugin-sdk/realtime-transcription` | Tipe provider transkripsi realtime dan helper registri |
| `plugin-sdk/realtime-voice` | Tipe provider suara realtime dan helper registri |
| `plugin-sdk/image-generation` | Tipe provider pembuatan gambar |
| `plugin-sdk/image-generation-core` | Tipe pembuatan gambar, failover, auth, dan helper registri bersama |
| `plugin-sdk/music-generation` | Tipe provider/permintaan/hasil pembuatan musik |
| `plugin-sdk/music-generation-core` | Tipe pembuatan musik, helper failover, lookup provider, dan parsing model-ref bersama |
| `plugin-sdk/video-generation` | Tipe provider/permintaan/hasil pembuatan video |
| `plugin-sdk/video-generation-core` | Tipe pembuatan video, helper failover, lookup provider, dan parsing model-ref bersama |
| `plugin-sdk/webhook-targets` | Registri target Webhook dan helper instalasi rute |
| `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/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` |
</Accordion>
@ -269,10 +270,10 @@ secara eksplisit mempromosikannya sebagai publik.
| --- | --- |
| `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 foundation host memori |
| `plugin-sdk/memory-core-host-engine-embeddings` | Ekspor engine embedding host memori |
| `plugin-sdk/memory-core-host-engine-foundation` | Ekspor engine fondasi host memori |
| `plugin-sdk/memory-core-host-engine-embeddings` | Kontrak embedding host memori, akses registri, provider lokal, dan helper batch/remote generik |
| `plugin-sdk/memory-core-host-engine-qmd` | Ekspor engine QMD host memori |
| `plugin-sdk/memory-core-host-engine-storage` | Ekspor engine storage 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 |
@ -281,24 +282,24 @@ secara eksplisit mempromosikannya sebagai publik.
| `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 core 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-core` | Alias netral vendor untuk helper runtime core 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-host-search` | Fasad runtime Active Memory 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 |
</Accordion>
<Accordion title="Subpath helper bawaan yang dicadangkan">
| 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 compatibility barrel) |
| 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 spesifik channel | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Seam kompatibilitas/helper channel bawaan |
| Helper spesifik auth/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Seam helper fitur/plugin bawaan; `plugin-sdk/github-copilot-token` saat ini mengekspor `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken`, dan `resolveCopilotApiToken` |
| Helper khusus channel | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Seam kompatibilitas/helper channel bawaan |
| Helper khusus auth/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Seam helper fitur/plugin bawaan; `plugin-sdk/github-copilot-token` saat ini mengekspor `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken`, dan `resolveCopilotApiToken` |
</Accordion>
</AccordionGroup>
@ -309,58 +310,58 @@ berikut:
### Pendaftaran kapabilitas
| Metode | Yang didaftarkan |
| ----------------------------------------------- | -------------------------------------- |
| `api.registerProvider(...)` | Inferensi teks (LLM) |
| `api.registerAgentHarness(...)` | Eksekutor agen tingkat rendah eksperimental |
| `api.registerCliBackend(...)` | Backend inferensi CLI lokal |
| `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 |
| Method | Yang didaftarkan |
| ------------------------------------------------ | ------------------------------------- |
| `api.registerProvider(...)` | Inferensi teks (LLM) |
| `api.registerAgentHarness(...)` | Eksekutor agent level rendah eksperimental |
| `api.registerCliBackend(...)` | Backend inferensi CLI lokal |
| `api.registerChannel(...)` | Channel perpesanan |
| `api.registerSpeechProvider(...)` | Sintesis text-to-speech / STT |
| `api.registerRealtimeTranscriptionProvider(...)` | Transkripsi realtime streaming |
| `api.registerRealtimeVoiceProvider(...)` | Sesi suara realtime dupleks |
| `api.registerMediaUnderstandingProvider(...)` | Analisis gambar/audio/video |
| `api.registerImageGenerationProvider(...)` | Pembuatan gambar |
| `api.registerMusicGenerationProvider(...)` | Pembuatan musik |
| `api.registerVideoGenerationProvider(...)` | Pembuatan video |
| `api.registerWebFetchProvider(...)` | Provider fetch / scrape web |
| `api.registerWebSearchProvider(...)` | Pencarian web |
### Tools dan perintah
### Tool dan perintah
| Metode | Yang didaftarkan |
| ----------------------------- | ---------------------------------------------- |
| `api.registerTool(tool, opts?)` | Tool agen (wajib atau `{ optional: true }`) |
| `api.registerCommand(def)` | Perintah kustom (melewati LLM) |
| Method | Yang didaftarkan |
| ------------------------------- | --------------------------------------------- |
| `api.registerTool(tool, opts?)` | Tool agent (wajib atau `{ optional: true }`) |
| `api.registerCommand(def)` | Perintah kustom (melewati LLM) |
### Infrastruktur
| Metode | Yang didaftarkan |
| --------------------------------------------- | ------------------------------------- |
| `api.registerHook(events, handler, opts?)` | Hook event |
| `api.registerHttpRoute(params)` | Endpoint HTTP Gateway |
| `api.registerGatewayMethod(name, handler)` | Metode RPC Gateway |
| `api.registerCli(registrar, opts?)` | Subperintah CLI |
| `api.registerService(service)` | Layanan latar belakang |
| `api.registerInteractiveHandler(registration)` | Handler interaktif |
| `api.registerMemoryPromptSupplement(builder)` | Bagian prompt tambahan yang berdekatan dengan memori |
| `api.registerMemoryCorpusSupplement(adapter)` | Korpus pencarian/baca memori tambahan |
| Method | Yang didaftarkan |
| ---------------------------------------------- | -------------------------------------- |
| `api.registerHook(events, handler, opts?)` | Hook event |
| `api.registerHttpRoute(params)` | Endpoint HTTP Gateway |
| `api.registerGatewayMethod(name, handler)` | Metode RPC Gateway |
| `api.registerCli(registrar, opts?)` | Subperintah CLI |
| `api.registerService(service)` | Layanan latar belakang |
| `api.registerInteractiveHandler(registration)` | Penangan interaktif |
| `api.registerMemoryPromptSupplement(builder)` | Bagian prompt tambahan yang berdekatan dengan memori |
| `api.registerMemoryCorpusSupplement(adapter)` | Korpus pencarian/baca memori tambahan |
Namespace admin core yang dicadangkan (`config.*`, `exec.approvals.*`, `wizard.*`,
`update.*`) selalu tetap `operator.admin`, meskipun plugin mencoba menetapkan
scope metode gateway yang lebih sempit. Gunakan prefix spesifik plugin untuk
cakupan metode Gateway yang lebih sempit. Gunakan prefiks khusus plugin untuk
metode yang dimiliki plugin.
### Metadata pendaftaran CLI
`api.registerCli(registrar, opts?)` menerima dua jenis metadata tingkat atas:
- `commands`: root perintah eksplisit yang dimiliki oleh registrar
- `descriptors`: descriptor perintah saat parse yang digunakan untuk bantuan root CLI,
routing, dan pendaftaran CLI plugin secara lazy
- `commands`: root perintah eksplisit yang dimiliki registrar
- `descriptors`: deskriptor perintah saat parse yang digunakan untuk help CLI root,
routing, dan pendaftaran CLI plugin lazy
Jika Anda ingin perintah plugin tetap dimuat secara lazy pada jalur root CLI normal,
berikan `descriptors` yang mencakup setiap root perintah tingkat atas yang diekspos oleh
registrar tersebut.
Jika Anda ingin perintah plugin tetap dimuat secara lazy di jalur CLI root normal,
berikan `descriptors` yang mencakup setiap root perintah tingkat atas yang diekspos
oleh registrar tersebut.
```typescript
api.registerCli(
@ -380,86 +381,83 @@ api.registerCli(
);
```
Gunakan `commands` saja hanya ketika Anda tidak memerlukan pendaftaran root CLI secara lazy.
Gunakan `commands` saja hanya saat Anda tidak memerlukan pendaftaran CLI root lazy.
Jalur kompatibilitas eager itu tetap didukung, tetapi tidak memasang
placeholder berbasis descriptor untuk pemuatan lazy saat parse-time.
placeholder berbasis deskriptor untuk pemuatan lazy saat parse-time.
### Pendaftaran backend CLI
`api.registerCliBackend(...)` memungkinkan plugin memiliki config default untuk backend
CLI AI lokal seperti `codex-cli`.
- `id` backend menjadi prefix provider dalam ref model seperti `codex-cli/gpt-5`.
- `id` backend menjadi prefiks provider dalam model ref seperti `codex-cli/gpt-5`.
- `config` backend menggunakan bentuk yang sama seperti `agents.defaults.cliBackends.<id>`.
- Config pengguna tetap menang. OpenClaw menggabungkan `agents.defaults.cliBackends.<id>` di atas
default plugin sebelum menjalankan CLI.
- Gunakan `normalizeConfig` ketika backend memerlukan penulisan ulang kompatibilitas setelah penggabungan
(misalnya menormalkan bentuk flag lama).
- Gunakan `normalizeConfig` saat backend memerlukan penulisan ulang kompatibilitas setelah penggabungan
(misalnya menormalisasi bentuk flag lama).
### Slot eksklusif
| Metode | Yang didaftarkan |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `api.registerContextEngine(id, factory)` | Engine konteks (satu aktif dalam satu waktu). Callback `assemble()` menerima `availableTools` dan `citationsMode` agar engine dapat menyesuaikan tambahan prompt. |
| `api.registerMemoryCapability(capability)` | Kapabilitas memori terpadu |
| `api.registerMemoryPromptSection(builder)` | Pembuat bagian prompt memori |
| `api.registerMemoryFlushPlan(resolver)` | Resolver rencana flush memori |
| `api.registerMemoryRuntime(runtime)` | Adapter runtime memori |
| Method | Yang didaftarkan |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api.registerContextEngine(id, factory)` | Engine konteks (hanya satu yang aktif pada satu waktu). Callback `assemble()` menerima `availableTools` dan `citationsMode` sehingga engine dapat menyesuaikan tambahan prompt. |
| `api.registerMemoryCapability(capability)` | Kapabilitas memori terpadu |
| `api.registerMemoryPromptSection(builder)` | Pembuat bagian prompt memori |
| `api.registerMemoryFlushPlan(resolver)` | Resolver rencana flush memori |
| `api.registerMemoryRuntime(runtime)` | Adapter runtime memori |
### Adapter embedding memori
| Metode | Yang didaftarkan |
| --------------------------------------------- | --------------------------------------------- |
| Method | Yang didaftarkan |
| ---------------------------------------------- | ---------------------------------------------- |
| `api.registerMemoryEmbeddingProvider(adapter)` | Adapter embedding memori untuk plugin aktif |
- `registerMemoryCapability` adalah API plugin memori eksklusif yang lebih disukai.
- `registerMemoryCapability` adalah API plugin memori eksklusif yang disukai.
- `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 layout privat plugin
memori tertentu.
agar plugin pendamping dapat menggunakan artefak memori yang diekspor melalui
`openclaw/plugin-sdk/memory-host-core` alih-alih menjangkau layout privat
plugin memori tertentu.
- `registerMemoryPromptSection`, `registerMemoryFlushPlan`, dan
`registerMemoryRuntime` adalah API plugin memori eksklusif yang kompatibel dengan
versi lama.
`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 kustom yang
ditentukan plugin).
atau lebih ID adapter embedding (misalnya `openai`, `gemini`, atau ID yang ditentukan plugin kustom).
- Config pengguna seperti `agents.defaults.memorySearch.provider` dan
`agents.defaults.memorySearch.fallback` diselesaikan terhadap id adapter yang
terdaftar tersebut.
`agents.defaults.memorySearch.fallback` diresolusikan terhadap ID adapter yang terdaftar tersebut.
### Event dan siklus hidup
| Metode | Fungsinya |
| ------------------------------------------- | ---------------------------- |
| `api.on(hookName, handler, opts?)` | Hook siklus hidup bertipe |
| `api.onConversationBindingResolved(handler)` | Callback conversation binding |
| Method | Fungsinya |
| -------------------------------------------- | ---------------------------- |
| `api.on(hookName, handler, opts?)` | Hook siklus hidup bertipe |
| `api.onConversationBindingResolved(handler)` | Callback binding percakapan |
### Semantik keputusan hook
- `before_tool_call`: mengembalikan `{ block: true }` bersifat terminal. Setelah handler mana pun menetapkannya, handler dengan prioritas lebih rendah dilewati.
- `before_tool_call`: mengembalikan `{ block: false }` diperlakukan sebagai tidak ada keputusan (sama seperti menghilangkan `block`), bukan sebagai override.
- `before_install`: mengembalikan `{ block: true }` bersifat terminal. Setelah handler mana pun menetapkannya, handler dengan prioritas lebih rendah dilewati.
- `before_install`: mengembalikan `{ block: false }` diperlakukan sebagai tidak ada keputusan (sama seperti menghilangkan `block`), bukan sebagai override.
- `reply_dispatch`: mengembalikan `{ handled: true, ... }` bersifat terminal. Setelah handler mana pun mengklaim dispatch, handler dengan prioritas lebih rendah dan jalur dispatch model default akan dilewati.
- `message_sending`: mengembalikan `{ cancel: true }` bersifat terminal. Setelah handler mana pun menetapkannya, handler dengan prioritas lebih rendah dilewati.
- `message_sending`: mengembalikan `{ cancel: false }` diperlakukan sebagai tidak ada keputusan (sama seperti menghilangkan `cancel`), bukan sebagai override.
- `before_tool_call`: mengembalikan `{ block: true }` bersifat terminal. Setelah ada handler yang menetapkannya, handler dengan prioritas lebih rendah dilewati.
- `before_tool_call`: mengembalikan `{ block: false }` diperlakukan sebagai tidak ada keputusan (sama seperti tidak menyertakan `block`), bukan sebagai override.
- `before_install`: mengembalikan `{ block: true }` bersifat terminal. Setelah ada handler yang menetapkannya, handler dengan prioritas lebih rendah dilewati.
- `before_install`: mengembalikan `{ block: false }` diperlakukan sebagai tidak ada keputusan (sama seperti tidak menyertakan `block`), bukan sebagai override.
- `reply_dispatch`: mengembalikan `{ handled: true, ... }` bersifat terminal. Setelah ada handler yang mengklaim dispatch, handler dengan prioritas lebih rendah dan jalur dispatch model default dilewati.
- `message_sending`: mengembalikan `{ cancel: true }` bersifat terminal. Setelah ada handler yang menetapkannya, handler dengan prioritas lebih rendah dilewati.
- `message_sending`: mengembalikan `{ cancel: false }` diperlakukan sebagai tidak ada keputusan (sama seperti tidak menyertakan `cancel`), bukan sebagai override.
### Field objek API
| Field | Tipe | Deskripsi |
| Field | Type | Deskripsi |
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------ |
| `api.id` | `string` | id plugin |
| `api.id` | `string` | ID plugin |
| `api.name` | `string` | Nama tampilan |
| `api.version` | `string?` | Versi plugin (opsional) |
| `api.description` | `string?` | Deskripsi plugin (opsional) |
| `api.source` | `string` | Jalur sumber plugin |
| `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 jika tersedia) |
| `api.config` | `OpenClawConfig` | Snapshot config saat ini (snapshot runtime in-memory aktif jika tersedia) |
| `api.pluginConfig` | `Record<string, unknown>` | Config khusus plugin dari `plugins.entries.<id>.config` |
| `api.runtime` | `PluginRuntime` | [Helper runtime](/id/plugins/sdk-runtime) |
| `api.logger` | `PluginLogger` | Logger yang dibatasi scope (`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 jalur relatif terhadap root plugin |
| `api.logger` | `PluginLogger` | Logger berscope (`debug`, `info`, `warn`, `error`) |
| `api.registrationMode` | `PluginRegistrationMode` | Mode pemuatan saat ini; `"setup-runtime"` adalah jendela startup/setup ringan sebelum full-entry |
| `api.resolvePath(input)` | `(string) => string` | Resolve path relatif terhadap root plugin |
## Konvensi modul internal
@ -469,47 +467,47 @@ Di dalam plugin Anda, gunakan file barrel lokal untuk impor internal:
my-plugin/
api.ts # Ekspor publik untuk konsumen eksternal
runtime-api.ts # Ekspor runtime khusus internal
index.ts # Entrypoint plugin
setup-entry.ts # Entri ringan khusus setup (opsional)
index.ts # Titik masuk plugin
setup-entry.ts # Entry khusus setup ringan (opsional)
```
<Warning>
Jangan pernah mengimpor plugin Anda sendiri melalui `openclaw/plugin-sdk/<your-plugin>`
dari kode produksi. Arahkan impor internal melalui `./api.ts` atau
`./runtime-api.ts`. Jalur SDK hanya merupakan kontrak eksternal.
`./runtime-api.ts`. Path SDK hanya merupakan kontrak eksternal.
</Warning>
Permukaan publik plugin bawaan yang dimuat melalui facade (`api.ts`, `runtime-api.ts`,
`index.ts`, `setup-entry.ts`, dan file entri publik serupa) sekarang lebih memilih
snapshot config runtime aktif saat OpenClaw sudah berjalan. Jika belum ada snapshot runtime,
permukaan itu akan fallback ke file config yang terselesaikan di disk.
Permukaan publik bundled plugin yang dimuat melalui facade (`api.ts`, `runtime-api.ts`,
`index.ts`, `setup-entry.ts`, dan file entry publik serupa) kini lebih memilih
snapshot config runtime aktif saat OpenClaw sudah berjalan. Jika snapshot runtime
belum ada, permukaan itu akan menggunakan fallback ke file config yang sudah di-resolve di disk.
Plugin provider juga dapat mengekspos contract barrel lokal-plugin yang sempit ketika sebuah
helper memang spesifik provider dan belum layak dimasukkan ke subpath SDK generik.
Plugin provider juga dapat mengekspos barrel kontrak lokal-plugin yang sempit saat suatu
helper memang khusus provider dan belum termasuk ke dalam subpath SDK generik.
Contoh bawaan saat ini: provider Anthropic menyimpan helper stream Claude-nya
di seam publik `api.ts` / `contract-api.ts` miliknya sendiri alih-alih
menaikkan logika beta-header Anthropic dan `service_tier` ke kontrak
dalam seam publik `api.ts` / `contract-api.ts` miliknya sendiri alih-alih
menaikkan logika header beta Anthropic dan `service_tier` ke dalam kontrak
`plugin-sdk/*` generik.
Contoh bawaan saat ini lainnya:
- `@openclaw/openai-provider`: `api.ts` mengekspor builder provider,
helper default-model, dan builder provider realtime
- `@openclaw/openrouter-provider`: `api.ts` mengekspor builder provider ditambah
helper model default, dan builder provider realtime
- `@openclaw/openrouter-provider`: `api.ts` mengekspor builder provider plus
helper onboarding/config
<Warning>
Kode produksi extension juga harus menghindari impor `openclaw/plugin-sdk/<other-plugin>`.
Jika sebuah helper benar-benar dipakai bersama, promosikan helper itu ke subpath SDK netral
seperti `openclaw/plugin-sdk/speech`, `.../provider-model-shared`, atau permukaan
berorientasi kapabilitas lainnya alih-alih menggandengkan dua plugin bersama.
Jika sebuah helper memang benar-benar dibagikan, promosikan helper tersebut ke subpath SDK netral
seperti `openclaw/plugin-sdk/speech`, `.../provider-model-shared`, atau permukaan lain
yang berorientasi kapabilitas alih-alih menggabungkan dua plugin secara erat.
</Warning>
## 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, manifest, 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 Masuk](/id/plugins/sdk-entrypoints) — opsi `definePluginEntry` dan `defineChannelPluginEntry`
- [Helper Runtime](/id/plugins/sdk-runtime) — referensi namespace `api.runtime` lengkap
- [Setup dan Config](/id/plugins/sdk-setup) — packaging, manifes, skema config
- [Pengujian](/id/plugins/sdk-testing) — utilitas pengujian dan aturan lint
- [Migrasi SDK](/id/plugins/sdk-migration) — migrasi dari permukaan yang sudah tidak digunakan
- [Internal Plugin](/id/plugins/architecture) — arsitektur mendalam dan model kapabilitas

133
docs/id/tools/thinking.md
View File

@ -1,118 +1,121 @@
---
read_when:
- Menyesuaikan penguraian atau default directive thinking, fast-mode, atau verbose
summary: Sintaks directive untuk /think, /fast, /verbose, /trace, dan visibilitas reasoning
title: Tingkat Thinking
- Menyesuaikan penguraian atau nilai default untuk direktif tingkat penalaran, mode cepat, atau verbose
summary: Sintaks direktif untuk /think, /fast, /verbose, /trace, dan visibilitas penalaran
title: Tingkat Penalaran
x-i18n:
generated_at: "2026-04-12T23:33:37Z"
generated_at: "2026-04-17T09:14:19Z"
model: gpt-5.4
provider: openai
source_hash: 4f3b1341281f07ba4e9061e3355845dca234be04cc0d358594312beeb7676e68
source_hash: 1cb44a7bf75546e5a8c3204e12f3297221449b881161d173dea4983da3921649
source_path: tools/thinking.md
workflow: 15
---
# Tingkat Thinking (/think directives)
# Tingkat Penalaran (direktif `/think`)
## Fungsinya
## Apa fungsinya
- Directive inline di body masuk mana pun: `/t <level>`, `/think:<level>`, atau `/thinking <level>`.
- Direktif inline di badan pesan masuk apa pun: `/t <level>`, `/think:<level>`, atau `/thinking <level>`.
- Level (alias): `off | minimal | low | medium | high | xhigh | adaptive`
- minimal → “think”
- low → “think hard”
- medium → “think harder”
- minimal → “pikir”
- low → “pikir keras”
- medium → “pikir lebih keras”
- high → “ultrathink” (anggaran maksimum)
- xhigh → “ultrathink+” (khusus model GPT-5.2 + Codex)
- adaptive → anggaran reasoning adaptif yang dikelola provider (didukung untuk keluarga model Anthropic Claude 4.6)
- xhigh → “ultrathink+” (GPT-5.2 + model Codex dan effort Anthropic Claude Opus 4.7)
- adaptive → penalaran adaptif yang dikelola penyedia (didukung untuk Anthropic Claude 4.6 dan Opus 4.7)
- `x-high`, `x_high`, `extra-high`, `extra high`, dan `extra_high` dipetakan ke `xhigh`.
- `highest`, `max` dipetakan ke `high`.
- Catatan provider:
- Model Anthropic Claude 4.6 default ke `adaptive` saat tidak ada level thinking eksplisit yang disetel.
- MiniMax (`minimax/*`) pada jalur streaming yang kompatibel dengan Anthropic default ke `thinking: { type: "disabled" }` kecuali Anda secara eksplisit menyetel thinking di param model atau param permintaan. Ini mencegah delta `reasoning_content` yang bocor dari format stream Anthropic non-native milik MiniMax.
- Z.AI (`zai/*`) hanya mendukung thinking biner (`on`/`off`). Level apa pun selain `off` diperlakukan sebagai `on` (dipetakan ke `low`).
- Moonshot (`moonshot/*`) memetakan `/think off` ke `thinking: { type: "disabled" }` dan level selain `off` ke `thinking: { type: "enabled" }`. Saat thinking diaktifkan, Moonshot hanya menerima `tool_choice` `auto|none`; OpenClaw menormalkan nilai yang tidak kompatibel ke `auto`.
- Catatan penyedia:
- Model Anthropic Claude 4.6 default ke `adaptive` saat tidak ada tingkat penalaran eksplisit yang ditetapkan.
- Anthropic Claude Opus 4.7 tidak default ke penalaran adaptif. Default effort API-nya tetap dimiliki penyedia kecuali Anda menetapkan tingkat penalaran secara eksplisit.
- Anthropic Claude Opus 4.7 memetakan `/think xhigh` ke penalaran adaptif plus `output_config.effort: "xhigh"`, karena `/think` adalah direktif penalaran dan `xhigh` adalah pengaturan effort Opus 4.7.
- MiniMax (`minimax/*`) pada path streaming yang kompatibel dengan Anthropic default ke `thinking: { type: "disabled" }` kecuali Anda secara eksplisit menetapkan thinking di parameter model atau parameter permintaan. Ini menghindari delta `reasoning_content` yang bocor dari format stream Anthropic non-native milik MiniMax.
- Z.AI (`zai/*`) hanya mendukung penalaran biner (`on`/`off`). Level apa pun selain `off` diperlakukan sebagai `on` (dipetakan ke `low`).
- Moonshot (`moonshot/*`) memetakan `/think off` ke `thinking: { type: "disabled" }` dan level apa pun selain `off` ke `thinking: { type: "enabled" }`. Saat penalaran diaktifkan, Moonshot hanya menerima `tool_choice` `auto|none`; OpenClaw menormalkan nilai yang tidak kompatibel ke `auto`.
## Urutan resolusi
1. Directive inline pada pesan (hanya berlaku untuk pesan itu).
2. Override sesi (diatur dengan mengirim pesan yang hanya berisi directive).
3. Default per agent (`agents.list[].thinkingDefault` di config).
4. Default global (`agents.defaults.thinkingDefault` di config).
5. Fallback: `adaptive` untuk model Anthropic Claude 4.6, `low` untuk model lain yang mendukung reasoning, `off` untuk selain itu.
1. Direktif inline pada pesan (hanya berlaku untuk pesan itu).
2. Override sesi (ditetapkan dengan mengirim pesan yang hanya berisi direktif).
3. Default per agen (`agents.list[].thinkingDefault` dalam config).
4. Default global (`agents.defaults.thinkingDefault` dalam config).
5. Fallback: `adaptive` untuk model Anthropic Claude 4.6, `off` untuk Anthropic Claude Opus 4.7 kecuali dikonfigurasi secara eksplisit, `low` untuk model lain yang mendukung penalaran, `off` jika tidak.
## Menetapkan default sesi
- Kirim pesan yang **hanya** berisi directive (spasi diperbolehkan), misalnya `/think:medium` atau `/t high`.
- Ini akan menempel untuk sesi saat ini (default-nya per pengirim); dibersihkan oleh `/think:off` atau reset idle sesi.
- Balasan konfirmasi dikirim (`Thinking level set to high.` / `Thinking disabled.`). Jika level tidak valid (misalnya `/thinking big`), perintah ditolak dengan petunjuk dan state sesi dibiarkan tidak berubah.
- Kirim `/think` (atau `/think:`) tanpa argumen untuk melihat level thinking saat ini.
- Kirim pesan yang **hanya** berisi direktif tersebut (spasi diperbolehkan), misalnya `/think:medium` atau `/t high`.
- Ini akan tetap berlaku untuk sesi saat ini (default-nya per pengirim); dihapus dengan `/think:off` atau reset idle sesi.
- Balasan konfirmasi akan dikirim (`Thinking level set to high.` / `Thinking disabled.`). Jika level tidak valid (misalnya `/thinking big`), perintah ditolak dengan petunjuk dan status sesi dibiarkan tidak berubah.
- Kirim `/think` (atau `/think:`) tanpa argumen untuk melihat tingkat penalaran saat ini.
## Penerapan per agent
## Penerapan per agen
- **Pi tertanam**: level yang di-resolve diteruskan ke runtime agent Pi di dalam proses.
- **Embedded Pi**: level yang dihasilkan diteruskan ke runtime agen Pi dalam proses.
## Fast mode (/fast)
## Mode cepat (`/fast`)
- Level: `on|off`.
- Pesan yang hanya berisi directive mengaktifkan/nonaktifkan override fast-mode sesi dan membalas `Fast mode enabled.` / `Fast mode disabled.`.
- Kirim `/fast` (atau `/fast status`) tanpa mode untuk melihat state fast-mode efektif saat ini.
- OpenClaw me-resolve fast mode dalam urutan berikut:
1. `/fast on|off` inline/directive-only
- Pesan yang hanya berisi direktif akan mengaktifkan override mode cepat sesi dan membalas `Fast mode enabled.` / `Fast mode disabled.`.
- Kirim `/fast` (atau `/fast status`) tanpa mode untuk melihat status mode cepat efektif saat ini.
- OpenClaw menyelesaikan mode cepat dalam urutan ini:
1. `/fast on|off` inline/hanya-direktif
2. Override sesi
3. Default per agent (`agents.list[].fastModeDefault`)
3. Default per agen (`agents.list[].fastModeDefault`)
4. Config per model: `agents.defaults.models["<provider>/<model>"].params.fastMode`
5. Fallback: `off`
- Untuk `openai/*`, fast mode dipetakan ke pemrosesan prioritas OpenAI dengan mengirim `service_tier=priority` pada permintaan Responses yang didukung.
- Untuk `openai-codex/*`, fast mode mengirim flag `service_tier=priority` yang sama pada Codex Responses. OpenClaw mempertahankan satu toggle `/fast` bersama di kedua jalur auth.
- Untuk permintaan `anthropic/*` publik langsung, termasuk lalu lintas terautentikasi OAuth yang dikirim ke `api.anthropic.com`, fast mode dipetakan ke service tier Anthropic: `/fast on` menetapkan `service_tier=auto`, `/fast off` menetapkan `service_tier=standard_only`.
- Untuk `minimax/*` pada jalur yang kompatibel dengan Anthropic, `/fast on` (atau `params.fastMode: true`) menulis ulang `MiniMax-M2.7` menjadi `MiniMax-M2.7-highspeed`.
- Param model Anthropic `serviceTier` / `service_tier` yang eksplisit akan mengoverride default fast-mode saat keduanya disetel. OpenClaw tetap melewati injeksi service-tier Anthropic untuk base URL proxy non-Anthropic.
- Untuk `openai/*`, mode cepat dipetakan ke pemrosesan prioritas OpenAI dengan mengirim `service_tier=priority` pada permintaan Responses yang didukung.
- Untuk `openai-codex/*`, mode cepat mengirim flag `service_tier=priority` yang sama pada Codex Responses. OpenClaw mempertahankan satu tombol `/fast` bersama di kedua jalur auth.
- Untuk permintaan `anthropic/*` publik langsung, termasuk trafik yang diautentikasi OAuth yang dikirim ke `api.anthropic.com`, mode cepat dipetakan ke service tier Anthropic: `/fast on` menetapkan `service_tier=auto`, `/fast off` menetapkan `service_tier=standard_only`.
- Untuk `minimax/*` pada path yang kompatibel dengan Anthropic, `/fast on` (atau `params.fastMode: true`) menulis ulang `MiniMax-M2.7` menjadi `MiniMax-M2.7-highspeed`.
- Parameter model Anthropic `serviceTier` / `service_tier` yang eksplisit mengesampingkan default mode cepat saat keduanya ditetapkan. OpenClaw tetap melewati injeksi service tier Anthropic untuk base URL proxy non-Anthropic.
## Directive verbose (/verbose atau /v)
## Direktif verbose (`/verbose` atau `/v`)
- Level: `on` (minimal) | `full` | `off` (default).
- Pesan yang hanya berisi directive mengaktifkan/nonaktifkan verbose sesi dan membalas `Verbose logging enabled.` / `Verbose logging disabled.`; level tidak valid mengembalikan petunjuk tanpa mengubah state.
- Pesan yang hanya berisi direktif mengaktifkan verbose sesi dan membalas `Verbose logging enabled.` / `Verbose logging disabled.`; level yang tidak valid mengembalikan petunjuk tanpa mengubah status.
- `/verbose off` menyimpan override sesi eksplisit; hapus melalui UI Sessions dengan memilih `inherit`.
- Directive inline hanya berlaku untuk pesan itu; default sesi/global berlaku di luar itu.
- Direktif inline hanya berlaku untuk pesan itu; default sesi/global berlaku di luar itu.
- Kirim `/verbose` (atau `/verbose:`) tanpa argumen untuk melihat level verbose saat ini.
- Saat verbose aktif, agent yang mengeluarkan hasil tool terstruktur (Pi, agent JSON lain) mengirim setiap pemanggilan tool kembali sebagai pesan khusus metadata tersendiri, diawali dengan `<emoji> <tool-name>: <arg>` bila tersedia (path/perintah). Ringkasan tool ini dikirim segera saat setiap tool dimulai (bubble terpisah), bukan sebagai delta streaming.
- Ringkasan kegagalan tool tetap terlihat dalam mode normal, tetapi sufiks detail error mentah disembunyikan kecuali verbose adalah `on` atau `full`.
- Saat verbose adalah `full`, output tool juga diteruskan setelah selesai (bubble terpisah, dipotong ke panjang yang aman). Jika Anda mengubah `/verbose on|full|off` saat eksekusi sedang berlangsung, bubble tool berikutnya akan mengikuti pengaturan baru.
- Saat verbose aktif, agen yang mengeluarkan hasil tool terstruktur (Pi, agen JSON lainnya) mengirim setiap pemanggilan tool kembali sebagai pesan khusus metadata tersendiri, diawali dengan `<emoji> <tool-name>: <arg>` jika tersedia (path/perintah). Ringkasan tool ini dikirim segera saat setiap tool dimulai (gelembung terpisah), bukan sebagai delta streaming.
- Ringkasan kegagalan tool tetap terlihat dalam mode normal, tetapi sufiks detail error mentah disembunyikan kecuali verbose bernilai `on` atau `full`.
- Saat verbose bernilai `full`, output tool juga diteruskan setelah selesai (gelembung terpisah, dipotong ke panjang aman). Jika Anda mengubah `/verbose on|full|off` saat proses sedang berjalan, gelembung tool berikutnya akan mengikuti pengaturan baru.
## Directive trace Plugin (/trace)
## Direktif trace Plugin (`/trace`)
- Level: `on` | `off` (default).
- Pesan yang hanya berisi directive mengaktifkan/nonaktifkan output trace Plugin sesi dan membalas `Plugin trace enabled.` / `Plugin trace disabled.`.
- Directive inline hanya berlaku untuk pesan itu; default sesi/global berlaku di luar itu.
- Pesan yang hanya berisi direktif mengaktifkan output trace Plugin sesi dan membalas `Plugin trace enabled.` / `Plugin trace disabled.`.
- Direktif inline hanya berlaku untuk pesan itu; default sesi/global berlaku di luar itu.
- Kirim `/trace` (atau `/trace:`) tanpa argumen untuk melihat level trace saat ini.
- `/trace` lebih sempit daripada `/verbose`: ini hanya mengekspos baris trace/debug milik Plugin seperti ringkasan debug Active Memory.
- `/trace` lebih sempit daripada `/verbose`: ini hanya mengekspos baris trace/debug milik plugin seperti ringkasan debug Active Memory.
- Baris trace dapat muncul di `/status` dan sebagai pesan diagnostik lanjutan setelah balasan asisten normal.
## Visibilitas reasoning (/reasoning)
## Visibilitas penalaran (`/reasoning`)
- Level: `on|off|stream`.
- Pesan yang hanya berisi directive mengaktifkan/nonaktifkan apakah blok thinking ditampilkan dalam balasan.
- Saat diaktifkan, reasoning dikirim sebagai **pesan terpisah** yang diawali dengan `Reasoning:`.
- `stream` (khusus Telegram): men-stream reasoning ke bubble draft Telegram saat balasan sedang dibuat, lalu mengirim jawaban akhir tanpa reasoning.
- Pesan yang hanya berisi direktif mengaktifkan apakah blok penalaran ditampilkan dalam balasan.
- Saat diaktifkan, penalaran dikirim sebagai **pesan terpisah** yang diawali dengan `Reasoning:`.
- `stream` (khusus Telegram): men-stream penalaran ke gelembung draf Telegram saat balasan sedang dibuat, lalu mengirim jawaban akhir tanpa penalaran.
- Alias: `/reason`.
- Kirim `/reasoning` (atau `/reasoning:`) tanpa argumen untuk melihat level reasoning saat ini.
- Urutan resolusi: directive inline, lalu override sesi, lalu default per agent (`agents.list[].reasoningDefault`), lalu fallback (`off`).
- Kirim `/reasoning` (atau `/reasoning:`) tanpa argumen untuk melihat level penalaran saat ini.
- Urutan resolusi: direktif inline, lalu override sesi, lalu default per agen (`agents.list[].reasoningDefault`), lalu fallback (`off`).
## Terkait
- Dokumen mode Elevated ada di [Mode Elevated](/id/tools/elevated).
- Dokumentasi mode elevated ada di [Elevated mode](/id/tools/elevated).
## Heartbeat
- Body probe Heartbeat adalah prompt heartbeat yang dikonfigurasi (default: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Directive inline dalam pesan heartbeat berlaku seperti biasa (tetapi hindari mengubah default sesi dari Heartbeat).
- Pengiriman Heartbeat default ke payload akhir saja. Untuk juga mengirim pesan `Reasoning:` terpisah (bila tersedia), set `agents.defaults.heartbeat.includeReasoning: true` atau per-agent `agents.list[].heartbeat.includeReasoning: true`.
- Isi probe Heartbeat adalah prompt heartbeat yang dikonfigurasi (default: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Direktif inline dalam pesan heartbeat berlaku seperti biasa (tetapi hindari mengubah default sesi dari heartbeat).
- Pengiriman Heartbeat default ke payload akhir saja. Untuk juga mengirim pesan `Reasoning:` terpisah (jika tersedia), tetapkan `agents.defaults.heartbeat.includeReasoning: true` atau per agen `agents.list[].heartbeat.includeReasoning: true`.
## UI chat web
- Pemilih thinking di UI chat web mencerminkan level tersimpan sesi dari penyimpanan/config sesi masuk saat halaman dimuat.
- Memilih level lain langsung menulis override sesi melalui `sessions.patch`; tidak menunggu pengiriman berikutnya dan bukan override `thinkingOnce` sekali pakai.
- Opsi pertama selalu `Default (<resolved level>)`, di mana default yang di-resolve berasal dari model sesi aktif: `adaptive` untuk Claude 4.6 di Anthropic/Bedrock, `low` untuk model lain yang mendukung reasoning, `off` untuk selain itu.
- Picker tetap sadar provider:
- sebagian besar provider menampilkan `off | minimal | low | medium | high | adaptive`
- Pemilih penalaran di chat web mencerminkan level tersimpan sesi dari penyimpanan/config sesi masuk saat halaman dimuat.
- Memilih level lain langsung menulis override sesi melalui `sessions.patch`; ini tidak menunggu pengiriman berikutnya dan bukan override sekali pakai `thinkingOnce`.
- Opsi pertama selalu `Default (<resolved level>)`, dengan default hasil resolusi berasal dari model sesi aktif: `adaptive` untuk Claude 4.6 di Anthropic, `off` untuk Anthropic Claude Opus 4.7 kecuali dikonfigurasi, `low` untuk model lain yang mendukung penalaran, `off` jika tidak.
- Pemilih tetap sadar penyedia:
- sebagian besar penyedia menampilkan `off | minimal | low | medium | high | adaptive`
- Anthropic Claude Opus 4.7 menampilkan `off | minimal | low | medium | high | xhigh | adaptive`
- Z.AI menampilkan biner `off | on`
- `/think:<level>` tetap berfungsi dan memperbarui level sesi tersimpan yang sama, sehingga directive chat dan picker tetap sinkron.
- `/think:<level>` tetap berfungsi dan memperbarui level sesi tersimpan yang sama, sehingga direktif chat dan pemilih tetap sinkron.