From cf5e90b1c672c8ae654941fc2abda135decf077b Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Fri, 17 Apr 2026 09:17:40 +0000 Subject: [PATCH] chore(i18n): refresh id translations --- docs/id/concepts/qa-e2e-automation.md | 120 ++--- docs/id/gateway/protocol.md | 423 +++++++++--------- docs/id/help/testing.md | 602 +++++++++++++------------- docs/id/platforms/macos.md | 160 +++---- docs/id/plugins/sdk-migration.md | 305 ++++++------- docs/id/plugins/sdk-overview.md | 448 ++++++++++--------- docs/id/tools/thinking.md | 133 +++--- 7 files changed, 1101 insertions(+), 1090 deletions(-) diff --git a/docs/id/concepts/qa-e2e-automation.md b/docs/id/concepts/qa-e2e-automation.md index c82d27bcb..3eff7e825 100644 --- a/docs/id/concepts/qa-e2e-automation.md +++ b/docs/id/concepts/qa-e2e-automation.md @@ -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=` 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=` 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 ` 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 ` 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=`. `--thinking ` tetap menetapkan fallback global, dan bentuk lama `--model-thinking ` 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=`. `--thinking ` tetap menetapkan fallback global, dan format lama `--model-thinking ` 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`. diff --git a/docs/id/gateway/protocol.md b/docs/id/gateway/protocol.md index 2542b409c..bd953675a 100644 --- a/docs/id/gateway/protocol.md +++ b/docs/id/gateway/protocol.md @@ -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 `...`, `...`, `...`, `...`, 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.` seperti `enabled`, + - Mode config menambal nilai `skills.entries.` 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`. diff --git a/docs/id/help/testing.md b/docs/id/help/testing.md index 2b5219086..dd3146be6 100644 --- a/docs/id/help/testing.md +++ b/docs/id/help/testing.md @@ -3,13 +3,13 @@ read_when: - Menjalankan pengujian secara lokal atau di CI - Menambahkan regresi untuk bug model/provider - Men-debug perilaku gateway + agen -summary: 'Perangkat pengujian: suite unit/e2e/live, runner Docker, dan apa yang dicakup oleh setiap pengujian' +summary: 'Kit pengujian: suite unit/e2e/live, runner Docker, dan apa yang dicakup oleh setiap pengujian' title: Pengujian x-i18n: - generated_at: "2026-04-16T21:51:22Z" + generated_at: "2026-04-17T09:14:20Z" model: gpt-5.4 provider: openai - source_hash: af2bc0e9b5e08ca3119806d355b517290f6078fda430109e7a0b153586215e34 + source_hash: 55483bc68d3b24daca3189fba3af1e896f39b8e83068d102fed06eac05b36102 source_path: help/testing.md workflow: 15 --- @@ -20,8 +20,8 @@ OpenClaw memiliki tiga suite Vitest (unit/integrasi, e2e, live) dan sejumlah kec Dokumen ini adalah panduan “cara kami menguji”: -- Apa yang dicakup oleh setiap suite (dan apa yang secara sengaja _tidak_ dicakup) -- Perintah mana yang dijalankan untuk alur kerja umum (lokal, pra-push, debugging) +- Apa yang dicakup oleh setiap suite (dan apa yang sengaja _tidak_ dicakup) +- Perintah mana yang dijalankan untuk alur kerja umum (lokal, sebelum push, debugging) - Bagaimana pengujian live menemukan kredensial dan memilih model/provider - Cara menambahkan regresi untuk masalah model/provider di dunia nyata @@ -30,75 +30,79 @@ Dokumen ini adalah panduan “cara kami menguji”: Hampir setiap hari: - Gate penuh (diharapkan sebelum push): `pnpm build && pnpm check && pnpm test` -- Menjalankan full-suite lokal yang lebih cepat di mesin yang lapang: `pnpm test:max` +- Menjalankan suite penuh lokal yang lebih cepat pada mesin yang lapang: `pnpm test:max` - Loop watch Vitest langsung: `pnpm test:watch` -- Penargetan file langsung kini juga merutekan path ekstensi/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Utamakan run yang ditargetkan terlebih dahulu saat Anda sedang mengiterasi satu kegagalan. +- Penargetan file langsung kini juga merutekan path extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- Utamakan run yang terarah terlebih dahulu saat Anda sedang mengiterasi satu kegagalan. - Situs QA berbasis Docker: `pnpm qa:lab:up` - Lane QA berbasis Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Saat Anda menyentuh pengujian atau menginginkan keyakinan tambahan: +Saat Anda menyentuh pengujian atau ingin keyakinan tambahan: - Gate cakupan: `pnpm test:coverage` - Suite E2E: `pnpm test:e2e` Saat men-debug provider/model nyata (memerlukan kredensial nyata): -- Suite live (probe model + alat/image gateway): `pnpm test:live` -- Target satu file live secara senyap: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Suite live (probe model + tool/image gateway): `pnpm test:live` +- Targetkan satu file live secara senyap: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -Tip: saat Anda hanya memerlukan satu kasus gagal, utamakan mempersempit pengujian live melalui env var allowlist yang dijelaskan di bawah. +Tip: ketika Anda hanya memerlukan satu kasus gagal, lebih baik mempersempit pengujian live melalui env var allowlist yang dijelaskan di bawah. ## Runner khusus QA Perintah-perintah ini berada di samping suite pengujian utama saat Anda memerlukan realisme QA-lab: - `pnpm openclaw qa suite` - - Menjalankan skenario QA berbasis repo langsung di host. - - Menjalankan beberapa skenario yang dipilih secara paralel secara default dengan worker gateway terisolasi, hingga 64 worker atau sejumlah skenario yang dipilih. Gunakan `--concurrency ` untuk menyesuaikan jumlah worker, atau `--concurrency 1` untuk lane serial yang lebih lama. + - Menjalankan skenario QA berbasis repo langsung pada host. + - Menjalankan beberapa skenario yang dipilih secara paralel secara default dengan worker gateway terisolasi, hingga 64 worker atau sebanyak jumlah skenario yang dipilih. Gunakan `--concurrency ` untuk menyesuaikan jumlah worker, atau `--concurrency 1` untuk lane serial lama. + - Mendukung mode provider `live-frontier`, `mock-openai`, dan `aimock`. + `aimock` memulai server provider lokal berbasis AIMock untuk cakupan fixture eksperimental dan protocol-mock tanpa menggantikan lane `mock-openai` yang sadar skenario. - `pnpm openclaw qa suite --runner multipass` - Menjalankan suite QA yang sama di dalam VM Linux Multipass sekali pakai. - - Mempertahankan perilaku pemilihan skenario yang sama seperti `qa suite` di host. + - Mempertahankan perilaku pemilihan skenario yang sama seperti `qa suite` pada host. - Menggunakan ulang flag pemilihan provider/model yang sama seperti `qa suite`. - - Run live meneruskan input autentikasi QA yang didukung dan praktis untuk guest: + - Run live meneruskan input auth QA yang didukung dan praktis untuk guest: kunci provider berbasis env, path konfigurasi provider live QA, dan `CODEX_HOME` jika ada. - Direktori output harus tetap berada di bawah root repo agar guest dapat menulis kembali melalui workspace yang di-mount. - - Menulis report + ringkasan QA normal plus log Multipass di bawah + - Menulis laporan + ringkasan QA normal serta log Multipass di bawah `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Memulai situs QA berbasis Docker untuk pekerjaan QA gaya operator. + - Memulai situs QA berbasis Docker untuk pekerjaan QA bergaya operator. +- `pnpm openclaw qa aimock` + - Hanya memulai server provider AIMock lokal untuk pengujian smoke protokol secara langsung. - `pnpm openclaw qa matrix` - Menjalankan lane QA live Matrix terhadap homeserver Tuwunel berbasis Docker yang sekali pakai. - - Host QA ini saat ini hanya untuk repo/dev. Instalasi OpenClaw yang dipaketkan tidak mengirimkan `qa-lab`, sehingga tidak mengekspos `openclaw qa`. - - Checkout repo memuat bundled runner secara langsung; tidak diperlukan langkah instalasi plugin terpisah. - - Menyediakan tiga pengguna Matrix sementara (`driver`, `sut`, `observer`) plus satu room privat, lalu memulai child gateway QA dengan plugin Matrix nyata sebagai transport SUT. - - Menggunakan image Tuwunel stabil yang dipin `ghcr.io/matrix-construct/tuwunel:v1.5.1` secara default. Override dengan `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` saat Anda perlu menguji image yang berbeda. + - Host QA ini saat ini hanya untuk repo/dev. Instalasi OpenClaw yang dipaketkan tidak menyertakan `qa-lab`, sehingga tidak mengekspos `openclaw qa`. + - Checkout repo memuat runner bawaan secara langsung; tidak diperlukan langkah instalasi Plugin terpisah. + - Menyediakan tiga pengguna Matrix sementara (`driver`, `sut`, `observer`) ditambah satu room privat, lalu memulai child gateway QA dengan Plugin Matrix nyata sebagai transport SUT. + - Menggunakan image Tuwunel stabil yang dipin `ghcr.io/matrix-construct/tuwunel:v1.5.1` secara default. Ganti dengan `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` saat Anda perlu menguji image lain. - Matrix tidak mengekspos flag sumber kredensial bersama karena lane ini menyediakan pengguna sekali pakai secara lokal. - - Menulis report QA Matrix, ringkasan, artefak observed-events, dan log output stdout/stderr gabungan di bawah `.artifacts/qa-e2e/...`. + - Menulis laporan QA Matrix, ringkasan, artefak observed-events, dan log output stdout/stderr gabungan di bawah `.artifacts/qa-e2e/...`. - `pnpm openclaw qa telegram` - Menjalankan lane QA live Telegram terhadap grup privat nyata menggunakan token bot driver dan SUT dari env. - - Memerlukan `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`, dan `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Group id harus berupa id chat Telegram numerik. - - Mendukung `--credential-source convex` untuk kredensial bersama yang dipool. Gunakan mode env secara default, atau set `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` untuk ikut serta dalam lease yang dipool. - - Memerlukan dua bot yang berbeda di grup privat yang sama, dengan bot SUT mengekspos username Telegram. - - Untuk observasi bot-ke-bot yang stabil, aktifkan Bot-to-Bot Communication Mode di `@BotFather` untuk kedua bot dan pastikan bot driver dapat mengamati trafik bot grup. - - Menulis report QA Telegram, ringkasan, dan artefak observed-messages di bawah `.artifacts/qa-e2e/...`. + - Memerlukan `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`, dan `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. ID grup harus berupa ID chat Telegram numerik. + - Mendukung `--credential-source convex` untuk kredensial bersama yang dipool. Gunakan mode env secara default, atau set `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` untuk memilih lease yang dipool. + - Memerlukan dua bot berbeda dalam grup privat yang sama, dengan bot SUT mengekspos username Telegram. + - Untuk observasi bot-ke-bot yang stabil, aktifkan Bot-to-Bot Communication Mode di `@BotFather` untuk kedua bot dan pastikan bot driver dapat mengamati lalu lintas bot grup. + - Menulis laporan QA Telegram, ringkasan, dan artefak observed-messages di bawah `.artifacts/qa-e2e/...`. Lane transport live berbagi satu kontrak standar sehingga transport baru tidak menyimpang: `qa-channel` tetap menjadi suite QA sintetis yang luas dan bukan bagian dari matriks cakupan transport live. -| Lane | Canary | Mention gating | Blok allowlist | Balasan tingkat atas | Lanjutkan setelah restart | Tindak lanjut thread | Isolasi thread | Observasi reaksi | Perintah help | -| -------- | ------ | -------------- | --------------- | -------------------- | ------------------------- | -------------------- | -------------- | ---------------- | ------------- | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Lane | Canary | Gating mention | Blok allowlist | Balasan tingkat atas | Lanjutkan setelah restart | Tindak lanjut thread | Isolasi thread | Observasi reaksi | Perintah bantuan | +| -------- | ------ | -------------- | --------------- | -------------------- | ------------------------- | -------------------- | -------------- | ---------------- | ---------------- | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | ### Kredensial Telegram bersama melalui Convex (v1) Saat `--credential-source convex` (atau `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) diaktifkan untuk -`openclaw qa telegram`, QA lab memperoleh lease eksklusif dari pool yang didukung Convex, mengirim heartbeat -untuk lease tersebut selama lane berjalan, dan melepaskan lease saat shutdown. +`openclaw qa telegram`, QA lab memperoleh lease eksklusif dari pool berbasis Convex, mengirim Heartbeat +untuk lease tersebut selama lane berjalan, dan melepaskan lease saat dimatikan. -Scaffold project Convex referensi: +Scaffold proyek Convex referensi: - `qa/convex-credential-broker/` @@ -119,13 +123,13 @@ Env var opsional: - `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (default `90000`) - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (default `15000`) - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (default `/qa-credentials/v1`) -- `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (id pelacakan opsional) -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` mengizinkan URL Convex `http://` loopback untuk pengembangan lokal saja. +- `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (ID pelacakan opsional) +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` mengizinkan URL Convex loopback `http://` untuk pengembangan lokal saja. -`OPENCLAW_QA_CONVEX_SITE_URL` sebaiknya menggunakan `https://` dalam operasi normal. +`OPENCLAW_QA_CONVEX_SITE_URL` seharusnya menggunakan `https://` dalam operasi normal. -Perintah admin maintainer (tambah/hapus/daftar pool) memerlukan -`OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` secara khusus. +Perintah admin maintainer (tambah/hapus/daftar pool) secara khusus memerlukan +`OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. Helper CLI untuk maintainer: @@ -142,7 +146,7 @@ Kontrak endpoint default (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): - `POST /acquire` - Permintaan: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` - Berhasil: `{ status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }` - - Habis/dapat dicoba lagi: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` + - Habis/dapat dicoba ulang: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` - `POST /heartbeat` - Permintaan: `{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }` - Berhasil: `{ status: "ok" }` (atau `2xx` kosong) @@ -155,7 +159,7 @@ Kontrak endpoint default (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): - `POST /admin/remove` (khusus secret maintainer) - Permintaan: `{ credentialId, actorId }` - Berhasil: `{ status: "ok", changed, credential }` - - Perlindungan lease aktif: `{ status: "error", code: "LEASE_ACTIVE", ... }` + - Pelindung lease aktif: `{ status: "error", code: "LEASE_ACTIVE", ... }` - `POST /admin/list` (khusus secret maintainer) - Permintaan: `{ kind?, status?, includePayload?, limit? }` - Berhasil: `{ status: "ok", credentials, count }` @@ -163,7 +167,7 @@ Kontrak endpoint default (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): Bentuk payload untuk jenis Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` harus berupa string id chat Telegram numerik. +- `groupId` harus berupa string ID chat Telegram numerik. - `admin/add` memvalidasi bentuk ini untuk `kind: "telegram"` dan menolak payload yang tidak valid. ### Menambahkan channel ke QA @@ -173,8 +177,8 @@ Menambahkan channel ke sistem QA markdown memerlukan tepat dua hal: 1. Adapter transport untuk channel tersebut. 2. Paket skenario yang menjalankan kontrak channel. -Jangan menambahkan root perintah QA tingkat atas baru ketika host bersama `qa-lab` dapat -memiliki alurnya. +Jangan tambahkan root perintah QA tingkat atas yang baru ketika host `qa-lab` bersama +dapat memiliki alur tersebut. `qa-lab` memiliki mekanisme host bersama: @@ -182,41 +186,41 @@ memiliki alurnya. - startup dan teardown suite - konkurensi worker - penulisan artefak -- pembuatan report +- pembuatan laporan - eksekusi skenario - alias kompatibilitas untuk skenario `qa-channel` yang lebih lama Plugin runner memiliki kontrak transport: -- bagaimana `openclaw qa ` dipasang di bawah root bersama `qa` +- bagaimana `openclaw qa ` dipasang di bawah root `qa` bersama - bagaimana gateway dikonfigurasi untuk transport tersebut - bagaimana kesiapan diperiksa -- bagaimana event inbound disuntikkan +- bagaimana event inbound diinjeksi - bagaimana pesan outbound diamati - bagaimana transkrip dan status transport yang dinormalisasi diekspos -- bagaimana aksi yang didukung transport dijalankan -- bagaimana reset atau pembersihan spesifik transport ditangani +- bagaimana tindakan yang didukung transport dijalankan +- bagaimana reset atau cleanup yang spesifik transport ditangani Batas adopsi minimum untuk channel baru adalah: -1. Tetap jadikan `qa-lab` sebagai pemilik root bersama `qa`. -2. Implementasikan runner transport pada seam host bersama `qa-lab`. -3. Simpan mekanisme spesifik transport di dalam plugin runner atau harness channel. +1. Tetap jadikan `qa-lab` sebagai pemilik root `qa` bersama. +2. Implementasikan runner transport pada seam host `qa-lab` bersama. +3. Simpan mekanisme yang spesifik transport di dalam Plugin runner atau harness channel. 4. Pasang runner sebagai `openclaw qa ` alih-alih mendaftarkan root perintah pesaing. Plugin runner harus mendeklarasikan `qaRunners` di `openclaw.plugin.json` dan mengekspor array `qaRunnerCliRegistrations` yang sesuai dari `runtime-api.ts`. - Jaga `runtime-api.ts` tetap ringan; CLI lazy dan eksekusi runner harus tetap berada di balik entrypoint terpisah. -5. Tulis atau adaptasikan skenario markdown di bawah `qa/scenarios/`. + Jaga agar `runtime-api.ts` tetap ringan; eksekusi CLI dan runner yang lazy harus tetap berada di balik entrypoint terpisah. +5. Tulis atau adaptasi skenario markdown di bawah `qa/scenarios/`. 6. Gunakan helper skenario generik untuk skenario baru. 7. Pertahankan alias kompatibilitas yang ada tetap berfungsi kecuali repo sedang melakukan migrasi yang disengaja. -Aturan keputusan ini ketat: +Aturan pengambilannya ketat: -- Jika perilaku dapat diekspresikan sekali di `qa-lab`, letakkan di `qa-lab`. -- Jika perilaku bergantung pada satu transport channel, simpan di plugin runner atau harness plugin tersebut. +- Jika perilaku dapat diekspresikan sekali di `qa-lab`, tempatkan di `qa-lab`. +- Jika perilaku bergantung pada satu transport channel, simpan di Plugin runner atau harness plugin tersebut. - Jika sebuah skenario memerlukan kapabilitas baru yang dapat digunakan oleh lebih dari satu channel, tambahkan helper generik alih-alih cabang spesifik channel di `suite.ts`. -- Jika sebuah perilaku hanya bermakna untuk satu transport, pertahankan skenario tetap spesifik transport dan nyatakan itu secara eksplisit dalam kontrak skenario. +- Jika suatu perilaku hanya bermakna untuk satu transport, pertahankan skenario tersebut spesifik transport dan buat itu eksplisit dalam kontrak skenario. -Nama helper generik yang disarankan untuk skenario baru adalah: +Nama helper generik yang disukai untuk skenario baru adalah: - `waitForTransportReady` - `waitForChannelReady` @@ -239,63 +243,63 @@ Alias kompatibilitas tetap tersedia untuk skenario yang ada, termasuk: - `formatConversationTranscript` - `resetBus` -Pekerjaan channel baru sebaiknya menggunakan nama helper generik. -Alias kompatibilitas ada untuk menghindari migrasi serentak, bukan sebagai model untuk +Pekerjaan channel baru harus menggunakan nama helper generik. +Alias kompatibilitas ada untuk menghindari migrasi sekaligus, bukan sebagai model untuk penulisan skenario baru. ## Suite pengujian (apa yang berjalan di mana) -Anggap suite sebagai “realisme yang meningkat” (dan flakiness/biaya yang juga meningkat): +Anggap suite-suite ini sebagai “realisme yang meningkat” (dan peningkatan flakiness/biaya): ### Unit / integrasi (default) - Perintah: `pnpm test` -- Konfigurasi: sepuluh run shard berurutan (`vitest.full-*.config.ts`) di atas project Vitest scoped yang ada +- Konfigurasi: sepuluh run shard berurutan (`vitest.full-*.config.ts`) di atas project Vitest scoped yang sudah ada - File: inventaris core/unit di bawah `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts`, dan pengujian node `ui` yang di-whitelist yang dicakup oleh `vitest.unit.config.ts` - Cakupan: - Pengujian unit murni - - Pengujian integrasi in-process (autentikasi gateway, routing, tooling, parsing, config) + - Pengujian integrasi in-process (auth gateway, routing, tooling, parsing, config) - Regresi deterministik untuk bug yang diketahui - Ekspektasi: - Berjalan di CI - Tidak memerlukan kunci nyata - Harus cepat dan stabil - Catatan project: - - `pnpm test` tanpa target kini menjalankan sebelas konfigurasi shard kecil (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) alih-alih satu proses root-project native yang besar. Ini mengurangi puncak RSS pada mesin yang sibuk dan mencegah pekerjaan auto-reply/ekstensi menghambat suite yang tidak terkait. - - `pnpm test --watch` tetap menggunakan graf project `vitest.config.ts` root native, karena loop watch multi-shard tidak praktis. - - `pnpm test`, `pnpm test:watch`, dan `pnpm test:perf:imports` merutekan target file/direktori eksplisit melalui lane scoped terlebih dahulu, sehingga `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` tidak perlu membayar biaya startup penuh root project. - - `pnpm test:changed` memperluas path git yang berubah ke lane scoped yang sama ketika diff hanya menyentuh file source/test yang dapat dirutekan; edit config/setup tetap kembali ke rerun root-project yang luas. - - Pengujian unit ringan dari agen, perintah, plugin, helper auto-reply, `plugin-sdk`, dan area utilitas murni serupa dirutekan melalui lane `unit-fast`, yang melewati `test/setup-openclaw-runtime.ts`; file stateful/berat-runtime tetap berada di lane yang ada. - - File source helper `plugin-sdk` dan `commands` tertentu juga memetakan run mode changed ke pengujian sibling eksplisit di lane ringan tersebut, sehingga edit helper tidak perlu menjalankan ulang full suite berat untuk direktori itu. - - `auto-reply` kini memiliki tiga bucket khusus: helper core tingkat atas, pengujian integrasi `reply.*` tingkat atas, dan subtree `src/auto-reply/reply/**`. Ini menjaga pekerjaan harness reply terberat tetap terpisah dari pengujian status/chunk/token yang murah. + - `pnpm test` tanpa target sekarang menjalankan sebelas konfigurasi shard yang lebih kecil (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) alih-alih satu proses root-project native yang sangat besar. Ini mengurangi RSS puncak pada mesin yang sibuk dan mencegah pekerjaan auto-reply/extension membuat suite lain yang tidak terkait kekurangan sumber daya. + - `pnpm test --watch` tetap menggunakan grafik project `vitest.config.ts` root native, karena loop watch multi-shard tidak praktis. + - `pnpm test`, `pnpm test:watch`, dan `pnpm test:perf:imports` merutekan target file/direktori eksplisit melalui lane scoped terlebih dahulu, sehingga `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` tidak perlu menanggung biaya startup root project penuh. + - `pnpm test:changed` memperluas path git yang berubah ke lane scoped yang sama ketika diff hanya menyentuh file sumber/pengujian yang dapat dirutekan; edit config/setup tetap fallback ke rerun root-project yang luas. + - Pengujian unit ringan impor dari agen, perintah, Plugin, helper auto-reply, `plugin-sdk`, dan area utilitas murni serupa dirutekan melalui lane `unit-fast`, yang melewati `test/setup-openclaw-runtime.ts`; file stateful/berat pada runtime tetap berada di lane yang ada. + - Beberapa file sumber helper `plugin-sdk` dan `commands` yang dipilih juga memetakan run mode changed ke pengujian sibling eksplisit di lane ringan tersebut, sehingga edit helper tidak perlu memicu ulang suite berat penuh untuk direktori itu. + - `auto-reply` sekarang memiliki tiga bucket khusus: helper core tingkat atas, pengujian integrasi `reply.*` tingkat atas, dan subtree `src/auto-reply/reply/**`. Ini menjaga pekerjaan harness reply yang paling berat tetap terpisah dari pengujian status/chunk/token yang murah. - Catatan embedded runner: - Saat Anda mengubah input penemuan message-tool atau konteks runtime Compaction, pertahankan kedua tingkat cakupan. - Tambahkan regresi helper yang terfokus untuk batas routing/normalisasi murni. - - Juga pertahankan suite integrasi embedded runner tetap sehat: + - Pastikan juga suite integrasi embedded runner tetap sehat: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts`, dan `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Suite tersebut memverifikasi bahwa scoped id dan perilaku Compaction tetap mengalir + - Suite tersebut memverifikasi bahwa ID yang di-scope dan perilaku Compaction tetap mengalir melalui path `run.ts` / `compact.ts` yang nyata; pengujian helper saja bukan pengganti yang memadai untuk path integrasi tersebut. - Catatan pool: - - Konfigurasi dasar Vitest kini default ke `threads`. - - Konfigurasi Vitest bersama juga menetapkan `isolate: false` dan menggunakan runner non-isolated di seluruh konfigurasi root project, e2e, dan live. - - Lane UI root mempertahankan setup dan optimizer `jsdom`-nya, tetapi kini juga berjalan di runner non-isolated bersama. + - Konfigurasi dasar Vitest sekarang default ke `threads`. + - Konfigurasi Vitest bersama juga menetapkan `isolate: false` dan menggunakan runner non-isolated di seluruh root project, konfigurasi e2e, dan live. + - Lane UI root mempertahankan setup dan optimizer `jsdom`, tetapi sekarang juga berjalan pada runner non-isolated bersama. - Setiap shard `pnpm test` mewarisi default `threads` + `isolate: false` yang sama dari konfigurasi Vitest bersama. - - Launcher bersama `scripts/run-vitest.mjs` kini juga menambahkan `--no-maglev` untuk proses child Node Vitest secara default guna mengurangi churn kompilasi V8 selama run lokal besar. Set `OPENCLAW_VITEST_ENABLE_MAGLEV=1` jika Anda perlu membandingkan dengan perilaku V8 bawaan. + - Launcher bersama `scripts/run-vitest.mjs` sekarang juga menambahkan `--no-maglev` untuk proses child Node Vitest secara default guna mengurangi churn kompilasi V8 selama run lokal yang besar. Setel `OPENCLAW_VITEST_ENABLE_MAGLEV=1` jika Anda perlu membandingkan dengan perilaku V8 bawaan. - Catatan iterasi lokal cepat: - - `pnpm test:changed` merutekan melalui lane scoped ketika path yang berubah dipetakan dengan bersih ke suite yang lebih kecil. + - `pnpm test:changed` merutekan melalui lane scoped ketika path yang berubah dipetakan secara bersih ke suite yang lebih kecil. - `pnpm test:max` dan `pnpm test:changed:max` mempertahankan perilaku routing yang sama, hanya dengan batas worker yang lebih tinggi. - - Auto-scaling worker lokal kini sengaja lebih konservatif dan juga mengurangi skala ketika load average host sudah tinggi, sehingga beberapa run Vitest bersamaan secara default menimbulkan dampak yang lebih kecil. - - Konfigurasi dasar Vitest menandai file project/config sebagai `forceRerunTriggers` agar rerun mode changed tetap benar ketika wiring pengujian berubah. - - Konfigurasi mempertahankan `OPENCLAW_VITEST_FS_MODULE_CACHE` tetap aktif pada host yang didukung; set `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` jika Anda ingin satu lokasi cache eksplisit untuk profiling langsung. + - Auto-scaling worker lokal sekarang sengaja lebih konservatif dan juga mengurangi skala ketika load average host sudah tinggi, sehingga beberapa run Vitest bersamaan secara default mengurangi dampak. + - Konfigurasi dasar Vitest menandai file project/konfigurasi sebagai `forceRerunTriggers` agar rerun mode changed tetap benar ketika wiring pengujian berubah. + - Konfigurasi ini mempertahankan `OPENCLAW_VITEST_FS_MODULE_CACHE` tetap aktif pada host yang didukung; setel `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` jika Anda ingin satu lokasi cache eksplisit untuk profiling langsung. - Catatan debug performa: - - `pnpm test:perf:imports` mengaktifkan pelaporan durasi impor Vitest plus output rincian impor. + - `pnpm test:perf:imports` mengaktifkan pelaporan durasi impor Vitest beserta output rincian impor. - `pnpm test:perf:imports:changed` membatasi tampilan profiling yang sama ke file yang berubah sejak `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` membandingkan `test:changed` yang dirutekan dengan path root-project native untuk diff yang sudah di-commit tersebut dan mencetak wall time plus RSS maksimum macOS. -- `pnpm test:perf:changed:bench -- --worktree` melakukan benchmark pada tree kotor saat ini dengan merutekan daftar file yang berubah melalui `scripts/test-projects.mjs` dan konfigurasi root Vitest. +- `pnpm test:perf:changed:bench -- --ref ` membandingkan `test:changed` yang dirutekan dengan jalur root-project native untuk diff yang sudah di-commit tersebut dan mencetak wall time beserta max RSS macOS. +- `pnpm test:perf:changed:bench -- --worktree` membenchmark tree kotor saat ini dengan merutekan daftar file yang berubah melalui `scripts/test-projects.mjs` dan konfigurasi Vitest root. - `pnpm test:perf:profile:main` menulis profil CPU main-thread untuk overhead startup dan transform Vitest/Vite. - `pnpm test:perf:profile:runner` menulis profil CPU+heap runner untuk suite unit dengan paralelisme file dinonaktifkan. @@ -307,128 +311,128 @@ Anggap suite sebagai “realisme yang meningkat” (dan flakiness/biaya yang jug - Default runtime: - Menggunakan Vitest `threads` dengan `isolate: false`, sama seperti bagian repo lainnya. - Menggunakan worker adaptif (CI: hingga 2, lokal: 1 secara default). - - Berjalan dalam mode silent secara default untuk mengurangi overhead I/O konsol. + - Berjalan dalam mode senyap secara default untuk mengurangi overhead I/O konsol. - Override yang berguna: - `OPENCLAW_E2E_WORKERS=` untuk memaksa jumlah worker (dibatasi hingga 16). - `OPENCLAW_E2E_VERBOSE=1` untuk mengaktifkan kembali output konsol verbose. - Cakupan: - - Perilaku end-to-end gateway multi-instans - - Surface WebSocket/HTTP, pairing node, dan jaringan yang lebih berat + - Perilaku end-to-end gateway multi-instance + - Surface WebSocket/HTTP, pairing Node, dan jaringan yang lebih berat - Ekspektasi: - - Berjalan di CI (saat diaktifkan di pipeline) + - Berjalan di CI (saat diaktifkan dalam pipeline) - Tidak memerlukan kunci nyata - - Lebih banyak komponen bergerak dibanding pengujian unit (bisa lebih lambat) + - Lebih banyak bagian bergerak dibanding pengujian unit (bisa lebih lambat) ### E2E: smoke backend OpenShell - Perintah: `pnpm test:e2e:openshell` - File: `test/openshell-sandbox.e2e.test.ts` - Cakupan: - - Memulai gateway OpenShell terisolasi di host melalui Docker + - Memulai gateway OpenShell terisolasi pada host melalui Docker - Membuat sandbox dari Dockerfile lokal sementara - - Menjalankan backend OpenShell milik OpenClaw melalui `sandbox ssh-config` + SSH exec nyata + - Menjalankan backend OpenShell OpenClaw melalui `sandbox ssh-config` + eksekusi SSH yang nyata - Memverifikasi perilaku filesystem remote-canonical melalui bridge fs sandbox - Ekspektasi: - Hanya opt-in; bukan bagian dari run default `pnpm test:e2e` - - Memerlukan CLI `openshell` lokal plus daemon Docker yang berfungsi - - Menggunakan `HOME` / `XDG_CONFIG_HOME` terisolasi, lalu menghancurkan gateway uji dan sandbox + - Memerlukan CLI `openshell` lokal serta daemon Docker yang berfungsi + - Menggunakan `HOME` / `XDG_CONFIG_HOME` terisolasi, lalu menghancurkan gateway pengujian dan sandbox - Override yang berguna: - `OPENCLAW_E2E_OPENSHELL=1` untuk mengaktifkan pengujian saat menjalankan suite e2e yang lebih luas secara manual - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` untuk menunjuk ke binary CLI non-default atau skrip wrapper + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` untuk menunjuk ke biner CLI non-default atau skrip wrapper ### Live (provider nyata + model nyata) - Perintah: `pnpm test:live` - Konfigurasi: `vitest.live.config.ts` - File: `src/**/*.live.test.ts` -- Default: **diaktifkan** oleh `pnpm test:live` (mengatur `OPENCLAW_LIVE_TEST=1`) +- Default: **diaktifkan** oleh `pnpm test:live` (menetapkan `OPENCLAW_LIVE_TEST=1`) - Cakupan: - “Apakah provider/model ini benar-benar berfungsi _hari ini_ dengan kredensial nyata?” - - Menangkap perubahan format provider, kekhasan pemanggilan tool, masalah autentikasi, dan perilaku rate limit + - Menangkap perubahan format provider, keanehan pemanggilan tool, masalah auth, dan perilaku rate limit - Ekspektasi: - - Tidak stabil untuk CI secara desain (jaringan nyata, kebijakan provider nyata, kuota, outage) - - Menghabiskan biaya / menggunakan rate limit - - Utamakan menjalankan subset yang dipersempit alih-alih “semuanya” -- Run live mengambil source dari `~/.profile` untuk mengambil API key yang belum ada. -- Secara default, run live tetap mengisolasi `HOME` dan menyalin materi config/auth ke home pengujian sementara agar fixture unit tidak dapat memodifikasi `~/.openclaw` Anda yang nyata. -- Set `OPENCLAW_LIVE_USE_REAL_HOME=1` hanya ketika Anda memang ingin pengujian live menggunakan direktori home nyata Anda. -- `pnpm test:live` kini default ke mode yang lebih senyap: ia mempertahankan output progres `[live] ...`, tetapi menekan pemberitahuan `~/.profile` tambahan dan membisukan log bootstrap gateway/Bonjour. Set `OPENCLAW_LIVE_TEST_QUIET=0` jika Anda ingin log startup lengkap kembali. -- Rotasi API key (spesifik provider): set `*_API_KEYS` dengan format koma/titik koma atau `*_API_KEY_1`, `*_API_KEY_2` (misalnya `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) atau override per-live melalui `OPENCLAW_LIVE_*_KEY`; pengujian mencoba ulang pada respons rate limit. -- Output progres/heartbeat: - - Suite live kini memancarkan baris progres ke stderr sehingga panggilan provider yang lama tampak aktif bahkan ketika capture konsol Vitest senyap. - - `vitest.live.config.ts` menonaktifkan intersepsi konsol Vitest sehingga baris progres provider/gateway mengalir segera selama run live. - - Atur heartbeat direct-model dengan `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Atur heartbeat gateway/probe dengan `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Secara desain tidak stabil untuk CI (jaringan nyata, kebijakan provider nyata, kuota, gangguan) + - Berbiaya / menggunakan rate limit + - Lebih baik menjalankan subset yang dipersempit daripada “semuanya” +- Run live mengambil `~/.profile` untuk mengambil API key yang belum ada. +- Secara default, run live tetap mengisolasi `HOME` dan menyalin materi config/auth ke home pengujian sementara agar fixture unit tidak dapat mengubah `~/.openclaw` Anda yang nyata. +- Setel `OPENCLAW_LIVE_USE_REAL_HOME=1` hanya saat Anda memang sengaja memerlukan pengujian live menggunakan direktori home nyata Anda. +- `pnpm test:live` sekarang default ke mode yang lebih senyap: tetap mempertahankan output progres `[live] ...`, tetapi menekan notifikasi `~/.profile` tambahan dan membisukan log bootstrap gateway/chatter Bonjour. Setel `OPENCLAW_LIVE_TEST_QUIET=0` jika Anda ingin log startup lengkap kembali. +- Rotasi API key (spesifik provider): setel `*_API_KEYS` dengan format koma/titik koma atau `*_API_KEY_1`, `*_API_KEY_2` (misalnya `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) atau override per-live melalui `OPENCLAW_LIVE_*_KEY`; pengujian akan retry pada respons rate limit. +- Output progres/Heartbeat: + - Suite live sekarang mengeluarkan baris progres ke stderr sehingga panggilan provider yang lama tampak aktif meskipun capture konsol Vitest senyap. + - `vitest.live.config.ts` menonaktifkan intersepsi konsol Vitest sehingga baris progres provider/gateway mengalir langsung selama run live. + - Sesuaikan Heartbeat direct-model dengan `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Sesuaikan Heartbeat gateway/probe dengan `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Suite mana yang harus saya jalankan? Gunakan tabel keputusan ini: -- Mengedit logika/pengujian: jalankan `pnpm test` (dan `pnpm test:coverage` jika Anda mengubah banyak hal) +- Mengedit logika/pengujian: jalankan `pnpm test` (dan `pnpm test:coverage` jika Anda banyak mengubah) - Menyentuh jaringan gateway / protokol WS / pairing: tambahkan `pnpm test:e2e` -- Men-debug “bot saya mati” / kegagalan spesifik provider / pemanggilan tool: jalankan `pnpm test:live` yang dipersempit +- Men-debug “bot saya down” / kegagalan spesifik provider / pemanggilan tool: jalankan `pnpm test:live` yang dipersempit -## Live: penyapuan kapabilitas node Android +## Live: sapuan kapabilitas Node Android - Pengujian: `src/gateway/android-node.capabilities.live.test.ts` - Skrip: `pnpm android:test:integration` -- Tujuan: memanggil **setiap perintah yang saat ini diiklankan** oleh node Android yang terhubung dan menegaskan perilaku kontrak perintah. +- Tujuan: memanggil **setiap perintah yang saat ini diiklankan** oleh Node Android yang terhubung dan menegaskan perilaku kontrak perintah. - Cakupan: - - Setup manual/prasyarat (suite tidak menginstal/menjalankan/melakukan pairing aplikasi). - - Validasi `node.invoke` gateway per perintah untuk node Android yang dipilih. + - Setup manual dengan prasyarat (suite ini tidak menginstal/menjalankan/memasangkan aplikasi). + - Validasi gateway `node.invoke` per perintah untuk Node Android yang dipilih. - Pra-setup yang diperlukan: - - Aplikasi Android sudah terhubung + dipasangkan ke gateway. + - Aplikasi Android sudah terhubung + paired ke gateway. - Aplikasi tetap berada di foreground. - - Izin/persetujuan capture diberikan untuk kapabilitas yang Anda harapkan lolos. + - Izin/persetujuan capture telah diberikan untuk kapabilitas yang Anda harapkan lolos. - Override target opsional: - `OPENCLAW_ANDROID_NODE_ID` atau `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. -- Detail setup Android lengkap: [Aplikasi Android](/id/platforms/android) +- Detail setup Android lengkap: [Android App](/id/platforms/android) ## Live: smoke model (kunci profil) Pengujian live dibagi menjadi dua lapisan agar kita dapat mengisolasi kegagalan: -- “Direct model” memberi tahu kita apakah provider/model dapat menjawab sama sekali dengan kunci yang diberikan. -- “Gateway smoke” memberi tahu kita apakah pipeline penuh gateway+agen berfungsi untuk model tersebut (sesi, riwayat, tool, kebijakan sandbox, dll.). +- “Direct model” memberi tahu kita apakah provider/model dapat merespons sama sekali dengan kunci yang diberikan. +- “Gateway smoke” memberi tahu kita apakah pipeline gateway+agen penuh berfungsi untuk model tersebut (sesi, riwayat, tool, kebijakan sandbox, dll.). ### Lapisan 1: Penyelesaian model langsung (tanpa gateway) - Pengujian: `src/agents/models.profiles.live.test.ts` - Tujuan: - - Menginventarisasi model yang ditemukan + - Mengenumerasi model yang ditemukan - Menggunakan `getApiKeyForModel` untuk memilih model yang Anda miliki kredensialnya - Menjalankan completion kecil per model (dan regresi terarah bila diperlukan) - Cara mengaktifkan: - `pnpm test:live` (atau `OPENCLAW_LIVE_TEST=1` jika memanggil Vitest secara langsung) -- Set `OPENCLAW_LIVE_MODELS=modern` (atau `all`, alias untuk modern) untuk benar-benar menjalankan suite ini; jika tidak, suite akan dilewati agar `pnpm test:live` tetap fokus pada gateway smoke +- Setel `OPENCLAW_LIVE_MODELS=modern` (atau `all`, alias untuk modern) untuk benar-benar menjalankan suite ini; jika tidak, suite ini akan skip agar `pnpm test:live` tetap fokus pada gateway smoke - Cara memilih model: - `OPENCLAW_LIVE_MODELS=modern` untuk menjalankan allowlist modern (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - `OPENCLAW_LIVE_MODELS=all` adalah alias untuk allowlist modern - atau `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist dipisahkan koma) - - Penyapuan modern/all secara default menggunakan batas terkurasi dengan sinyal tinggi; set `OPENCLAW_LIVE_MAX_MODELS=0` untuk penyapuan modern yang menyeluruh atau angka positif untuk batas yang lebih kecil. + - Sapuan modern/all secara default menggunakan batas curated dengan sinyal tinggi; setel `OPENCLAW_LIVE_MAX_MODELS=0` untuk sapuan modern lengkap atau angka positif untuk batas yang lebih kecil. - Cara memilih provider: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist dipisahkan koma) -- Dari mana kunci berasal: - - Secara default: profile store dan fallback env - - Set `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` untuk menegakkan hanya **profile store** -- Mengapa ini ada: +- Asal kunci: + - Secara default: penyimpanan profil dan fallback env + - Setel `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` untuk memaksa **hanya** penyimpanan profil +- Alasan ini ada: - Memisahkan “API provider rusak / kunci tidak valid” dari “pipeline agen gateway rusak” - - Menampung regresi kecil dan terisolasi (contoh: reasoning replay OpenAI Responses/Codex Responses + alur tool-call) + - Menampung regresi kecil yang terisolasi (contoh: replay reasoning OpenAI Responses/Codex Responses + alur tool-call) -### Lapisan 2: Gateway + smoke agen dev (apa yang sebenarnya dilakukan oleh "@openclaw") +### Lapisan 2: smoke Gateway + agen dev (apa yang sebenarnya dilakukan `@openclaw`) - Pengujian: `src/gateway/gateway-models.profiles.live.test.ts` - Tujuan: - Menyalakan gateway in-process - Membuat/menambal sesi `agent:dev:*` (override model per run) - - Mengiterasi model-with-keys dan menegaskan: + - Mengiterasi model-dengan-kunci dan menegaskan: - respons yang “bermakna” (tanpa tool) - - pemanggilan tool nyata berfungsi (probe read) - - probe tool tambahan opsional (probe exec+read) - - path regresi OpenAI (hanya tool-call → tindak lanjut) tetap berfungsi -- Detail probe (agar Anda dapat menjelaskan kegagalan dengan cepat): - - probe `read`: pengujian menulis file nonce di workspace lalu meminta agen untuk `read` file tersebut dan menggemakan nonce kembali. + - satu pemanggilan tool nyata berfungsi (probe baca) + - probe tool tambahan opsional (probe exec+baca) + - path regresi OpenAI (hanya-tool-call → tindak lanjut) tetap berfungsi +- Detail probe (agar Anda bisa menjelaskan kegagalan dengan cepat): + - probe `read`: pengujian menulis file nonce di workspace lalu meminta agen untuk `read` file tersebut dan mengembalikan nonce. - probe `exec+read`: pengujian meminta agen untuk menulis nonce ke file sementara melalui `exec`, lalu membacanya kembali dengan `read`. - probe image: pengujian melampirkan PNG yang dihasilkan (kucing + kode acak) dan mengharapkan model mengembalikan `cat `. - Referensi implementasi: `src/gateway/gateway-models.profiles.live.test.ts` dan `src/gateway/live-image-probe.ts`. @@ -437,21 +441,21 @@ Pengujian live dibagi menjadi dua lapisan agar kita dapat mengisolasi kegagalan: - Cara memilih model: - Default: allowlist modern (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - `OPENCLAW_LIVE_GATEWAY_MODELS=all` adalah alias untuk allowlist modern - - Atau set `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (atau daftar dipisahkan koma) untuk mempersempit - - Penyapuan gateway modern/all secara default menggunakan batas terkurasi dengan sinyal tinggi; set `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` untuk penyapuan modern yang menyeluruh atau angka positif untuk batas yang lebih kecil. -- Cara memilih provider (hindari “OpenRouter semuanya”): + - Atau setel `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (atau daftar dipisahkan koma) untuk mempersempit + - Sapuan gateway modern/all secara default menggunakan batas curated dengan sinyal tinggi; setel `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` untuk sapuan modern lengkap atau angka positif untuk batas yang lebih kecil. +- Cara memilih provider (hindari “semua OpenRouter”): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist dipisahkan koma) -- Probe tool + image selalu aktif di pengujian live ini: - - probe `read` + probe `exec+read` (stres tool) - - probe image berjalan saat model mengiklankan dukungan input gambar +- Probe tool + image selalu aktif dalam pengujian live ini: + - probe `read` + probe `exec+read` (stress tool) + - probe image berjalan saat model mengiklankan dukungan input image - Alur (tingkat tinggi): - Pengujian menghasilkan PNG kecil dengan “CAT” + kode acak (`src/gateway/live-image-probe.ts`) - Mengirimkannya melalui `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - - Gateway mem-parse lampiran menjadi `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - Agen tersemat meneruskan pesan pengguna multimodal ke model - - Penegasan: balasan berisi `cat` + kode tersebut (toleransi OCR: kesalahan kecil diperbolehkan) + - Gateway mengurai lampiran menjadi `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - Agen embedded meneruskan pesan pengguna multimodal ke model + - Asersi: balasan berisi `cat` + kode tersebut (toleransi OCR: kesalahan kecil diperbolehkan) -Tip: untuk melihat apa yang dapat Anda uji di mesin Anda (dan id `provider/model` yang tepat), jalankan: +Tip: untuk melihat apa yang bisa Anda uji di mesin Anda (dan ID `provider/model` yang tepat), jalankan: ```bash openclaw models list @@ -462,22 +466,22 @@ openclaw models list --json - Pengujian: `src/gateway/gateway-cli-backend.live.test.ts` - Tujuan: memvalidasi pipeline Gateway + agen menggunakan backend CLI lokal, tanpa menyentuh config default Anda. -- Default smoke spesifik backend berada pada definisi `cli-backend.ts` milik ekstensi yang memiliki. +- Default smoke backend-spesifik berada bersama definisi `cli-backend.ts` milik extension yang memilikinya. - Aktifkan: - `pnpm test:live` (atau `OPENCLAW_LIVE_TEST=1` jika memanggil Vitest secara langsung) - `OPENCLAW_LIVE_CLI_BACKEND=1` - Default: - Provider/model default: `claude-cli/claude-sonnet-4-6` - - Perilaku command/args/image berasal dari metadata plugin backend CLI yang memiliki. + - Perilaku command/args/image berasal dari metadata Plugin backend CLI yang memilikinya. - Override (opsional): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` untuk mengirim lampiran image nyata (path disuntikkan ke prompt). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` untuk meneruskan path file image sebagai arg CLI alih-alih injeksi prompt. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (atau `"list"`) untuk mengontrol bagaimana arg image diteruskan saat `IMAGE_ARG` diatur. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` untuk mengirim lampiran image nyata (path diinjeksi ke prompt). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` untuk meneruskan path file image sebagai argumen CLI alih-alih injeksi prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (atau `"list"`) untuk mengontrol bagaimana argumen image diteruskan saat `IMAGE_ARG` disetel. - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` untuk mengirim giliran kedua dan memvalidasi alur resume. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` untuk menonaktifkan probe kontinuitas sesi yang sama Claude Sonnet -> Opus default (set ke `1` untuk memaksanya aktif saat model yang dipilih mendukung target switch). + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` untuk menonaktifkan probe kontinuitas sesi yang sama Claude Sonnet -> Opus default (setel ke `1` untuk memaksanya aktif saat model yang dipilih mendukung target switch). Contoh: @@ -493,7 +497,7 @@ Resep Docker: pnpm test:docker:live-cli-backend ``` -Resep Docker provider tunggal: +Resep Docker penyedia tunggal: ```bash pnpm test:docker:live-cli-backend:claude @@ -505,10 +509,10 @@ pnpm test:docker:live-cli-backend:gemini Catatan: - Runner Docker berada di `scripts/test-live-cli-backend-docker.sh`. -- Ia menjalankan smoke CLI-backend live di dalam image Docker repo sebagai pengguna non-root `node`. -- Ia me-resolve metadata smoke CLI dari ekstensi yang memiliki, lalu menginstal paket CLI Linux yang sesuai (`@anthropic-ai/claude-code`, `@openai/codex`, atau `@google/gemini-cli`) ke prefix writable yang di-cache di `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (default: `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` memerlukan OAuth subscription Claude Code portabel melalui `~/.claude/.credentials.json` dengan `claudeAiOauth.subscriptionType` atau `CLAUDE_CODE_OAUTH_TOKEN` dari `claude setup-token`. Ia terlebih dahulu membuktikan `claude -p` langsung di Docker, lalu menjalankan dua giliran Gateway CLI-backend tanpa mempertahankan env var API key Anthropic. Lane subscription ini menonaktifkan probe Claude MCP/tool dan image secara default karena Claude saat ini merutekan penggunaan aplikasi pihak ketiga melalui penagihan penggunaan tambahan alih-alih batas paket subscription normal. -- Smoke CLI-backend live kini menjalankan alur end-to-end yang sama untuk Claude, Codex, dan Gemini: giliran teks, giliran klasifikasi image, lalu pemanggilan tool MCP `cron` yang diverifikasi melalui CLI gateway. +- Runner ini menjalankan smoke backend CLI live di dalam image Docker repo sebagai pengguna non-root `node`. +- Runner ini menyelesaikan metadata smoke CLI dari extension yang memilikinya, lalu memasang paket CLI Linux yang sesuai (`@anthropic-ai/claude-code`, `@openai/codex`, atau `@google/gemini-cli`) ke prefix writable yang di-cache di `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (default: `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` memerlukan OAuth subscription Claude Code portabel melalui `~/.claude/.credentials.json` dengan `claudeAiOauth.subscriptionType` atau `CLAUDE_CODE_OAUTH_TOKEN` dari `claude setup-token`. Resep ini terlebih dahulu membuktikan `claude -p` langsung di Docker, lalu menjalankan dua giliran Gateway CLI-backend tanpa mempertahankan env API key Anthropic. Lane subscription ini menonaktifkan probe MCP/tool Claude dan image secara default karena Claude saat ini merutekan penggunaan aplikasi pihak ketiga melalui penagihan penggunaan tambahan, bukan batas paket subscription normal. +- Smoke backend CLI live sekarang menjalankan alur end-to-end yang sama untuk Claude, Codex, dan Gemini: giliran teks, giliran klasifikasi image, lalu pemanggilan tool MCP `cron` yang diverifikasi melalui CLI gateway. - Smoke default Claude juga menambal sesi dari Sonnet ke Opus dan memverifikasi bahwa sesi yang di-resume masih mengingat catatan sebelumnya. ## Live: smoke bind ACP (`/acp spawn ... --bind here`) @@ -516,9 +520,9 @@ Catatan: - Pengujian: `src/gateway/gateway-acp-bind.live.test.ts` - Tujuan: memvalidasi alur bind percakapan ACP nyata dengan agen ACP live: - kirim `/acp spawn --bind here` - - bind percakapan message-channel sintetis di tempat + - bind percakapan channel-pesan sintetis secara in-place - kirim tindak lanjut normal pada percakapan yang sama - - verifikasi bahwa tindak lanjut masuk ke transkrip sesi ACP yang terikat + - verifikasi bahwa tindak lanjut masuk ke transkrip sesi ACP yang di-bind - Aktifkan: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` @@ -534,8 +538,8 @@ Catatan: - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - Catatan: - - Lane ini menggunakan surface gateway `chat.send` dengan field originating-route sintetis khusus admin agar pengujian dapat melampirkan konteks message-channel tanpa berpura-pura mengirim secara eksternal. - - Saat `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` tidak diatur, pengujian menggunakan registri agen bawaan plugin `acpx` tersemat untuk agen harness ACP yang dipilih. + - Lane ini menggunakan surface gateway `chat.send` dengan field originating-route sintetis khusus admin sehingga pengujian dapat melampirkan konteks channel-pesan tanpa berpura-pura mengirim secara eksternal. + - Saat `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` tidak disetel, pengujian menggunakan registri agen bawaan milik Plugin `acpx` embedded untuk agen harness ACP yang dipilih. Contoh: @@ -562,19 +566,19 @@ pnpm test:docker:live-acp-bind:gemini Catatan Docker: - Runner Docker berada di `scripts/test-live-acp-bind-docker.sh`. -- Secara default, ia menjalankan smoke bind ACP terhadap semua agen CLI live yang didukung secara berurutan: `claude`, `codex`, lalu `gemini`. +- Secara default, runner ini menjalankan smoke bind ACP terhadap semua agen CLI live yang didukung secara berurutan: `claude`, `codex`, lalu `gemini`. - Gunakan `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`, atau `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` untuk mempersempit matriks. -- Ia mengambil source dari `~/.profile`, men-stage materi auth CLI yang sesuai ke dalam container, menginstal `acpx` ke prefix npm writable, lalu menginstal CLI live yang diminta (`@anthropic-ai/claude-code`, `@openai/codex`, atau `@google/gemini-cli`) jika belum ada. -- Di dalam Docker, runner mengatur `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` sehingga acpx mempertahankan env var provider dari profile yang di-source tetap tersedia bagi harness CLI child. +- Runner ini mengambil `~/.profile`, menyiapkan materi auth CLI yang sesuai ke dalam container, memasang `acpx` ke prefix npm writable, lalu memasang CLI live yang diminta (`@anthropic-ai/claude-code`, `@openai/codex`, atau `@google/gemini-cli`) jika belum ada. +- Di dalam Docker, runner menetapkan `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` agar acpx tetap menyediakan env var provider dari profile yang diambil untuk CLI child harness. -## Live: smoke harness app-server Codex +## Live: smoke harness server-aplikasi Codex -- Tujuan: memvalidasi harness Codex milik plugin melalui metode +- Tujuan: memvalidasi harness Codex milik Plugin melalui metode `agent` gateway normal: - - memuat plugin `codex` yang dibundel + - memuat Plugin `codex` bawaan - memilih `OPENCLAW_AGENT_RUNTIME=codex` - mengirim giliran agen gateway pertama ke `codex/gpt-5.4` - - mengirim giliran kedua ke sesi OpenClaw yang sama dan memverifikasi thread app-server + - mengirim giliran kedua ke sesi OpenClaw yang sama dan memverifikasi thread server-aplikasi dapat di-resume - menjalankan `/codex status` dan `/codex models` melalui path perintah gateway yang sama @@ -583,9 +587,9 @@ Catatan Docker: - Model default: `codex/gpt-5.4` - Probe image opsional: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` - Probe MCP/tool opsional: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` -- Smoke ini mengatur `OPENCLAW_AGENT_HARNESS_FALLBACK=none` sehingga harness Codex +- Smoke ini menetapkan `OPENCLAW_AGENT_HARNESS_FALLBACK=none` sehingga harness Codex yang rusak tidak bisa lolos dengan diam-diam fallback ke PI. -- Auth: `OPENAI_API_KEY` dari shell/profile, plus opsional salinan +- Auth: `OPENAI_API_KEY` dari shell/profile, ditambah salinan opsional `~/.codex/auth.json` dan `~/.codex/config.toml` Resep lokal: @@ -609,45 +613,45 @@ pnpm test:docker:live-codex-harness Catatan Docker: - Runner Docker berada di `scripts/test-live-codex-harness-docker.sh`. -- Ia mengambil source dari `~/.profile` yang di-mount, meneruskan `OPENAI_API_KEY`, menyalin file - auth CLI Codex jika ada, menginstal `@openai/codex` ke prefix npm writable yang di-mount, - men-stage source tree, lalu hanya menjalankan pengujian live Codex-harness. -- Docker mengaktifkan probe image dan MCP/tool secara default. Set +- Runner ini mengambil `~/.profile` yang di-mount, meneruskan `OPENAI_API_KEY`, menyalin file + auth Codex CLI saat tersedia, memasang `@openai/codex` ke prefix npm writable + yang di-mount, menyiapkan source tree, lalu hanya menjalankan pengujian live Codex-harness. +- Docker mengaktifkan probe image dan MCP/tool secara default. Setel `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` atau `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` saat Anda memerlukan run debug yang lebih sempit. -- Docker juga mengekspor `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, sesuai dengan konfigurasi +- Docker juga mengekspor `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, sama seperti konfigurasi pengujian live sehingga fallback `openai-codex/*` atau PI tidak dapat menyembunyikan regresi harness Codex. ### Resep live yang direkomendasikan -Allowlist yang sempit dan eksplisit adalah yang tercepat dan paling tidak flaky: +Allowlist yang sempit dan eksplisit adalah yang tercepat dan paling sedikit flakiness: -- Model tunggal, langsung (tanpa gateway): +- Satu model, langsung (tanpa gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- Model tunggal, gateway smoke: +- Satu model, gateway smoke: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Pemanggilan tool di beberapa provider: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Fokus Google (Gemini API key + Antigravity): +- Fokus Google (API key Gemini + Antigravity): - Gemini (API key): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Antigravity (OAuth): `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` Catatan: -- `google/...` menggunakan API Gemini (API key). +- `google/...` menggunakan Gemini API (API key). - `google-antigravity/...` menggunakan bridge OAuth Antigravity (endpoint agen bergaya Cloud Code Assist). -- `google-gemini-cli/...` menggunakan Gemini CLI lokal di mesin Anda (autentikasi terpisah + kekhasan tooling). -- API Gemini vs Gemini CLI: - - API: OpenClaw memanggil API Gemini yang di-host oleh Google melalui HTTP (API key / autentikasi profil); inilah yang dimaksud sebagian besar pengguna dengan “Gemini”. - - CLI: OpenClaw melakukan shell out ke binary `gemini` lokal; ia memiliki autentikasi sendiri dan dapat berperilaku berbeda (streaming/dukungan tool/ketidaksesuaian versi). +- `google-gemini-cli/...` menggunakan Gemini CLI lokal di mesin Anda (auth + keanehan tooling yang terpisah). +- Gemini API vs Gemini CLI: + - API: OpenClaw memanggil Gemini API yang di-host Google melalui HTTP (API key / auth profil); inilah yang biasanya dimaksud kebanyakan pengguna dengan “Gemini”. + - CLI: OpenClaw melakukan shell out ke biner `gemini` lokal; ia memiliki auth sendiri dan dapat berperilaku berbeda (streaming/dukungan tool/ketidaksinkronan versi). ## Live: matriks model (apa yang kami cakup) -Tidak ada “daftar model CI” tetap (live bersifat opt-in), tetapi inilah model-model **yang direkomendasikan** untuk dicakup secara rutin pada mesin dev dengan kunci. +Tidak ada “daftar model CI” tetap (live bersifat opt-in), tetapi ini adalah model **yang direkomendasikan** untuk dicakup secara rutin pada mesin dev dengan kunci. ### Set smoke modern (tool calling + image) @@ -656,15 +660,15 @@ Ini adalah run “model umum” yang kami harapkan tetap berfungsi: - OpenAI (non-Codex): `openai/gpt-5.4` (opsional: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` - Anthropic: `anthropic/claude-opus-4-6` (atau `anthropic/claude-sonnet-4-6`) -- Google (API Gemini): `google/gemini-3.1-pro-preview` dan `google/gemini-3-flash-preview` (hindari model Gemini 2.x yang lebih lama) +- Google (Gemini API): `google/gemini-3.1-pro-preview` dan `google/gemini-3-flash-preview` (hindari model Gemini 2.x yang lebih lama) - Google (Antigravity): `google-antigravity/claude-opus-4-6-thinking` dan `google-antigravity/gemini-3-flash` - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Jalankan gateway smoke dengan tool + image: +Jalankan gateway smoke dengan tools + image: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### Baseline: tool calling (Read + Exec opsional) +### Dasar: tool calling (Read + Exec opsional) Pilih setidaknya satu per keluarga provider: @@ -674,44 +678,44 @@ Pilih setidaknya satu per keluarga provider: - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Cakupan tambahan opsional (bagus untuk dimiliki): +Cakupan tambahan opsional (bagus jika ada): -- xAI: `xai/grok-4` (atau versi terbaru yang tersedia) -- Mistral: `mistral/`… (pilih satu model yang kapabel `tools` yang telah Anda aktifkan) +- xAI: `xai/grok-4` (atau yang terbaru tersedia) +- Mistral: `mistral/`… (pilih satu model yang mendukung “tools” yang Anda aktifkan) - Cerebras: `cerebras/`… (jika Anda memiliki akses) - LM Studio: `lmstudio/`… (lokal; tool calling bergantung pada mode API) -### Vision: pengiriman image (attachment → pesan multimodal) +### Vision: pengiriman image (lampiran → pesan multimodal) -Sertakan setidaknya satu model yang mampu memproses image di `OPENCLAW_LIVE_GATEWAY_MODELS` (varian Claude/Gemini/OpenAI yang mendukung vision, dll.) untuk menjalankan probe image. +Sertakan setidaknya satu model yang mendukung image dalam `OPENCLAW_LIVE_GATEWAY_MODELS` (varian Claude/Gemini/OpenAI yang mendukung vision, dll.) untuk menjalankan probe image. ### Aggregator / gateway alternatif Jika Anda memiliki kunci yang diaktifkan, kami juga mendukung pengujian melalui: -- OpenRouter: `openrouter/...` (ratusan model; gunakan `openclaw models scan` untuk menemukan kandidat yang mampu tool+image) +- OpenRouter: `openrouter/...` (ratusan model; gunakan `openclaw models scan` untuk menemukan kandidat yang mendukung tool+image) - OpenCode: `opencode/...` untuk Zen dan `opencode-go/...` untuk Go (auth melalui `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Lebih banyak provider yang dapat Anda sertakan dalam matriks live (jika Anda memiliki kredensial/config): +Provider lain yang dapat Anda sertakan dalam matriks live (jika Anda memiliki kredensial/config): -- Built-in: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- Melalui `models.providers` (endpoint kustom): `minimax` (cloud/API), ditambah proxy apa pun yang kompatibel dengan OpenAI/Anthropic (LM Studio, vLLM, LiteLLM, dll.) +- Bawaan: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` +- Melalui `models.providers` (endpoint kustom): `minimax` (cloud/API), ditambah proxy yang kompatibel dengan OpenAI/Anthropic (LM Studio, vLLM, LiteLLM, dll.) -Tip: jangan mencoba meng-hardcode “semua model” dalam dokumen. Daftar otoritatif adalah apa pun yang dikembalikan oleh `discoverModels(...)` di mesin Anda + kunci apa pun yang tersedia. +Tip: jangan mencoba meng-hardcode “semua model” dalam dokumen. Daftar yang otoritatif adalah apa pun yang dikembalikan `discoverModels(...)` di mesin Anda + kunci apa pun yang tersedia. ## Kredensial (jangan pernah commit) -Pengujian live menemukan kredensial dengan cara yang sama seperti CLI. Implikasi praktis: +Pengujian live menemukan kredensial dengan cara yang sama seperti CLI. Implikasi praktisnya: - Jika CLI berfungsi, pengujian live seharusnya menemukan kunci yang sama. -- Jika pengujian live mengatakan “tidak ada kredensial”, debug-lah dengan cara yang sama seperti saat men-debug `openclaw models list` / pemilihan model. +- Jika pengujian live mengatakan “no creds”, debug dengan cara yang sama seperti Anda men-debug `openclaw models list` / pemilihan model. -- Profil auth per-agen: `~/.openclaw/agents//agent/auth-profiles.json` (inilah yang dimaksud “profile keys” dalam pengujian live) +- Profil auth per agen: `~/.openclaw/agents//agent/auth-profiles.json` (inilah arti “profile keys” dalam pengujian live) - Config: `~/.openclaw/openclaw.json` (atau `OPENCLAW_CONFIG_PATH`) -- Direktori state lawas: `~/.openclaw/credentials/` (disalin ke home live yang di-stage saat ada, tetapi bukan penyimpanan utama profile-key) -- Run lokal live secara default menyalin config aktif, file `auth-profiles.json` per-agen, `credentials/` lawas, dan direktori auth CLI eksternal yang didukung ke home pengujian sementara; home live yang di-stage melewati `workspace/` dan `sandboxes/`, dan override path `agents.*.workspace` / `agentDir` dihapus agar probe tidak menyentuh workspace host nyata Anda. +- Direktori state legacy: `~/.openclaw/credentials/` (disalin ke home live staged saat ada, tetapi bukan penyimpanan utama kunci profil) +- Run lokal live secara default menyalin config aktif, file `auth-profiles.json` per agen, `credentials/` legacy, dan direktori auth CLI eksternal yang didukung ke home pengujian sementara; home live staged melewati `workspace/` dan `sandboxes/`, dan override path `agents.*.workspace` / `agentDir` dihapus agar probe tetap tidak menyentuh workspace host nyata Anda. -Jika Anda ingin mengandalkan env key (misalnya diekspor di `~/.profile` Anda), jalankan pengujian lokal setelah `source ~/.profile`, atau gunakan runner Docker di bawah (mereka dapat me-mount `~/.profile` ke dalam container). +Jika Anda ingin mengandalkan env key (misalnya diekspor di `~/.profile` Anda), jalankan pengujian lokal setelah `source ~/.profile`, atau gunakan runner Docker di bawah (runner tersebut dapat me-mount `~/.profile` ke dalam container). ## Live Deepgram (transkripsi audio) @@ -729,9 +733,9 @@ Jika Anda ingin mengandalkan env key (misalnya diekspor di `~/.profile` Anda), j - Pengujian: `extensions/comfy/comfy.live.test.ts` - Aktifkan: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Cakupan: - - Menjalankan path image, video, dan `music_generate` comfy yang dibundel + - Menjalankan path image, video, dan `music_generate` comfy bawaan - Melewati setiap kapabilitas kecuali `models.providers.comfy.` dikonfigurasi - - Berguna setelah mengubah pengiriman workflow comfy, polling, unduhan, atau registrasi plugin + - Berguna setelah mengubah pengiriman workflow comfy, polling, unduhan, atau registrasi Plugin ## Live pembuatan image @@ -739,16 +743,16 @@ Jika Anda ingin mengandalkan env key (misalnya diekspor di `~/.profile` Anda), j - Perintah: `pnpm test:live src/image-generation/runtime.live.test.ts` - Harness: `pnpm test:live:media image` - Cakupan: - - Menginventarisasi setiap plugin provider pembuatan image yang terdaftar - - Memuat env var provider yang hilang dari login shell Anda (`~/.profile`) sebelum probe - - Secara default menggunakan API key live/env sebelum profil auth yang disimpan, sehingga test key basi di `auth-profiles.json` tidak menutupi kredensial shell nyata + - Mengenumerasi setiap Plugin provider pembuatan image yang terdaftar + - Memuat env var provider yang hilang dari login shell Anda (`~/.profile`) sebelum melakukan probe + - Secara default menggunakan API key live/env sebelum profil auth yang tersimpan, sehingga kunci pengujian lama di `auth-profiles.json` tidak menutupi kredensial shell nyata - Melewati provider tanpa auth/profil/model yang dapat digunakan - - Menjalankan varian stok pembuatan image melalui kapabilitas runtime bersama: + - Menjalankan varian pembuatan image bawaan melalui kapabilitas runtime bersama: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Provider bundled saat ini yang dicakup: +- Provider bawaan saat ini yang dicakup: - `openai` - `google` - Penyempitan opsional: @@ -756,7 +760,7 @@ Jika Anda ingin mengandalkan env key (misalnya diekspor di `~/.profile` Anda), j - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` - Perilaku auth opsional: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` untuk memaksa auth profile-store dan mengabaikan override hanya-env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` untuk memaksa auth penyimpanan profil dan mengabaikan override hanya-env ## Live pembuatan musik @@ -764,23 +768,23 @@ Jika Anda ingin mengandalkan env key (misalnya diekspor di `~/.profile` Anda), j - Aktifkan: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Harness: `pnpm test:live:media music` - Cakupan: - - Menjalankan path provider pembuatan musik bundled bersama + - Menjalankan path provider pembuatan musik bawaan bersama - Saat ini mencakup Google dan MiniMax - - Memuat env var provider dari login shell Anda (`~/.profile`) sebelum probe - - Secara default menggunakan API key live/env sebelum profil auth yang disimpan, sehingga test key basi di `auth-profiles.json` tidak menutupi kredensial shell nyata + - Memuat env var provider dari login shell Anda (`~/.profile`) sebelum melakukan probe + - Secara default menggunakan API key live/env sebelum profil auth yang tersimpan, sehingga kunci pengujian lama di `auth-profiles.json` tidak menutupi kredensial shell nyata - Melewati provider tanpa auth/profil/model yang dapat digunakan - Menjalankan kedua mode runtime yang dideklarasikan saat tersedia: - `generate` dengan input hanya prompt - `edit` saat provider mendeklarasikan `capabilities.edit.enabled` - - Cakupan current shared-lane: + - Cakupan lane bersama saat ini: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: file live Comfy terpisah, bukan penyapuan bersama ini + - `comfy`: file live Comfy terpisah, bukan sapuan bersama ini - Penyempitan opsional: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` - Perilaku auth opsional: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` untuk memaksa auth profile-store dan mengabaikan override hanya-env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` untuk memaksa auth penyimpanan profil dan mengabaikan override hanya-env ## Live pembuatan video @@ -788,34 +792,34 @@ Jika Anda ingin mengandalkan env key (misalnya diekspor di `~/.profile` Anda), j - Aktifkan: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harness: `pnpm test:live:media video` - Cakupan: - - Menjalankan path provider pembuatan video bundled bersama - - Secara default menggunakan path smoke yang aman untuk rilis: provider non-FAL, satu permintaan text-to-video per provider, prompt lobster satu detik, dan batas operasi per-provider dari `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` secara default) - - Melewati FAL secara default karena latensi antrean sisi provider dapat mendominasi waktu rilis; gunakan `--video-providers fal` atau `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` untuk menjalankannya secara eksplisit - - Memuat env var provider dari login shell Anda (`~/.profile`) sebelum probe - - Secara default menggunakan API key live/env sebelum profil auth yang disimpan, sehingga test key basi di `auth-profiles.json` tidak menutupi kredensial shell nyata + - Menjalankan path provider pembuatan video bawaan bersama + - Default ke path smoke yang aman untuk rilis: provider non-FAL, satu permintaan text-to-video per provider, prompt lobster satu detik, dan batas operasi per provider dari `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` secara default) + - Melewati FAL secara default karena latensi antrean di sisi provider dapat mendominasi waktu rilis; kirim `--video-providers fal` atau `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` untuk menjalankannya secara eksplisit + - Memuat env var provider dari login shell Anda (`~/.profile`) sebelum melakukan probe + - Secara default menggunakan API key live/env sebelum profil auth yang tersimpan, sehingga kunci pengujian lama di `auth-profiles.json` tidak menutupi kredensial shell nyata - Melewati provider tanpa auth/profil/model yang dapat digunakan - Secara default hanya menjalankan `generate` - - Set `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` untuk juga menjalankan mode transform yang dideklarasikan saat tersedia: - - `imageToVideo` saat provider mendeklarasikan `capabilities.imageToVideo.enabled` dan provider/model yang dipilih menerima input image lokal berbasis buffer dalam penyapuan bersama - - `videoToVideo` saat provider mendeklarasikan `capabilities.videoToVideo.enabled` dan provider/model yang dipilih menerima input video lokal berbasis buffer dalam penyapuan bersama - - Provider `imageToVideo` saat ini yang dideklarasikan tetapi dilewati dalam penyapuan bersama: - - `vydra` karena `veo3` bundled hanya mendukung teks dan `kling` bundled memerlukan URL image jarak jauh + - Setel `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` untuk juga menjalankan mode transform yang dideklarasikan saat tersedia: + - `imageToVideo` saat provider mendeklarasikan `capabilities.imageToVideo.enabled` dan provider/model terpilih menerima input image lokal berbasis buffer dalam sapuan bersama + - `videoToVideo` saat provider mendeklarasikan `capabilities.videoToVideo.enabled` dan provider/model terpilih menerima input video lokal berbasis buffer dalam sapuan bersama + - Provider `imageToVideo` yang saat ini dideklarasikan tetapi dilewati dalam sapuan bersama: + - `vydra` karena `veo3` bawaan hanya teks dan `kling` bawaan memerlukan URL image jarak jauh - Cakupan Vydra spesifik provider: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - file tersebut menjalankan `veo3` text-to-video plus lane `kling` yang secara default menggunakan fixture URL image jarak jauh + - file tersebut menjalankan `veo3` text-to-video ditambah lane `kling` yang secara default menggunakan fixture URL image jarak jauh - Cakupan live `videoToVideo` saat ini: - hanya `runway` saat model yang dipilih adalah `runway/gen4_aleph` - - Provider `videoToVideo` saat ini yang dideklarasikan tetapi dilewati dalam penyapuan bersama: + - Provider `videoToVideo` yang saat ini dideklarasikan tetapi dilewati dalam sapuan bersama: - `alibaba`, `qwen`, `xai` karena path tersebut saat ini memerlukan URL referensi `http(s)` / MP4 jarak jauh - - `google` karena lane Gemini/Veo bersama saat ini menggunakan input berbasis buffer lokal dan path tersebut tidak diterima dalam penyapuan bersama - - `openai` karena lane bersama saat ini tidak memiliki jaminan akses video inpaint/remix spesifik organisasi + - `google` karena lane Gemini/Veo bersama saat ini menggunakan input lokal berbasis buffer dan path itu tidak diterima dalam sapuan bersama + - `openai` karena lane bersama saat ini tidak memiliki jaminan akses video inpaint/remix yang spesifik organisasi - Penyempitan opsional: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` untuk menyertakan setiap provider dalam penyapuan default, termasuk FAL + - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` untuk menyertakan setiap provider dalam sapuan default, termasuk FAL - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` untuk mengurangi batas operasi tiap provider demi run smoke yang agresif - Perilaku auth opsional: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` untuk memaksa auth profile-store dan mengabaikan override hanya-env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` untuk memaksa auth penyimpanan profil dan mengabaikan override hanya-env ## Harness media live @@ -824,77 +828,77 @@ Jika Anda ingin mengandalkan env key (misalnya diekspor di `~/.profile` Anda), j - Menjalankan suite live image, musik, dan video bersama melalui satu entrypoint native repo - Memuat otomatis env var provider yang hilang dari `~/.profile` - Secara default mempersempit otomatis setiap suite ke provider yang saat ini memiliki auth yang dapat digunakan - - Menggunakan ulang `scripts/test-live.mjs`, sehingga perilaku heartbeat dan mode senyap tetap konsisten + - Menggunakan ulang `scripts/test-live.mjs`, sehingga perilaku Heartbeat dan mode senyap tetap konsisten - Contoh: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## Runner Docker (opsional untuk pemeriksaan "berfungsi di Linux") +## Runner Docker (opsional untuk pemeriksaan “berfungsi di Linux”) Runner Docker ini terbagi menjadi dua kelompok: -- Runner live-model: `test:docker:live-models` dan `test:docker:live-gateway` hanya menjalankan file live profile-key yang sesuai di dalam image Docker repo (`src/agents/models.profiles.live.test.ts` dan `src/gateway/gateway-models.profiles.live.test.ts`), dengan me-mount direktori config dan workspace lokal Anda (serta mengambil source `~/.profile` jika di-mount). Entrypoint lokal yang sesuai adalah `test:live:models-profiles` dan `test:live:gateway-profiles`. -- Runner live Docker secara default menggunakan batas smoke yang lebih kecil agar penyapuan Docker penuh tetap praktis: +- Runner live-model: `test:docker:live-models` dan `test:docker:live-gateway` hanya menjalankan file live profile-key yang sesuai di dalam image Docker repo (`src/agents/models.profiles.live.test.ts` dan `src/gateway/gateway-models.profiles.live.test.ts`), dengan me-mount direktori config dan workspace lokal Anda (serta mengambil `~/.profile` jika di-mount). Entrypoint lokal yang sesuai adalah `test:live:models-profiles` dan `test:live:gateway-profiles`. +- Runner live Docker secara default menggunakan batas smoke yang lebih kecil agar sapuan Docker penuh tetap praktis: `test:docker:live-models` secara default menggunakan `OPENCLAW_LIVE_MAX_MODELS=12`, dan `test:docker:live-gateway` secara default menggunakan `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000`, dan `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Override env var tersebut saat Anda - memang menginginkan pemindaian lengkap yang lebih besar. -- `test:docker:all` membangun image Docker live sekali melalui `test:docker:live-build`, lalu menggunakannya kembali untuk dua lane live Docker tersebut. + secara eksplisit menginginkan pemindaian lengkap yang lebih besar. +- `test:docker:all` membangun image live Docker satu kali melalui `test:docker:live-build`, lalu menggunakannya kembali untuk dua lane Docker live tersebut. - Runner smoke container: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels`, dan `test:docker:plugins` menyalakan satu atau lebih container nyata dan memverifikasi path integrasi tingkat lebih tinggi. -Runner Docker live-model juga hanya melakukan bind-mount pada home auth CLI yang diperlukan (atau semua yang didukung ketika run tidak dipersempit), lalu menyalinnya ke home container sebelum run agar OAuth CLI eksternal dapat memperbarui token tanpa memodifikasi penyimpanan auth host: +Runner Docker live-model juga bind-mount hanya home auth CLI yang diperlukan (atau semuanya yang didukung bila run tidak dipersempit), lalu menyalinnya ke home container sebelum run sehingga OAuth CLI eksternal dapat me-refresh token tanpa mengubah penyimpanan auth host: - Model langsung: `pnpm test:docker:live-models` (skrip: `scripts/test-live-models-docker.sh`) - Smoke bind ACP: `pnpm test:docker:live-acp-bind` (skrip: `scripts/test-live-acp-bind-docker.sh`) - Smoke backend CLI: `pnpm test:docker:live-cli-backend` (skrip: `scripts/test-live-cli-backend-docker.sh`) -- Smoke harness app-server Codex: `pnpm test:docker:live-codex-harness` (skrip: `scripts/test-live-codex-harness-docker.sh`) +- Smoke harness server-aplikasi Codex: `pnpm test:docker:live-codex-harness` (skrip: `scripts/test-live-codex-harness-docker.sh`) - Gateway + agen dev: `pnpm test:docker:live-gateway` (skrip: `scripts/test-live-gateway-models-docker.sh`) - Smoke live Open WebUI: `pnpm test:docker:openwebui` (skrip: `scripts/e2e/openwebui-docker.sh`) - Wizard onboarding (TTY, scaffolding penuh): `pnpm test:docker:onboard` (skrip: `scripts/e2e/onboard-docker.sh`) -- Jaringan gateway (dua container, auth + health WS): `pnpm test:docker:gateway-network` (skrip: `scripts/e2e/gateway-network-docker.sh`) -- Bridge channel MCP (Gateway yang di-seed + bridge stdio + smoke notification-frame Claude mentah): `pnpm test:docker:mcp-channels` (skrip: `scripts/e2e/mcp-channels-docker.sh`) -- Plugins (smoke instalasi + alias `/plugin` + semantik restart Claude-bundle): `pnpm test:docker:plugins` (skrip: `scripts/e2e/plugins-docker.sh`) +- Jaringan gateway (dua container, auth WS + health): `pnpm test:docker:gateway-network` (skrip: `scripts/e2e/gateway-network-docker.sh`) +- Bridge channel MCP (Gateway berisi seed + bridge stdio + smoke raw Claude notification-frame): `pnpm test:docker:mcp-channels` (skrip: `scripts/e2e/mcp-channels-docker.sh`) +- Plugin (smoke install + alias `/plugin` + semantik restart bundle Claude): `pnpm test:docker:plugins` (skrip: `scripts/e2e/plugins-docker.sh`) -Runner Docker live-model juga melakukan bind-mount checkout saat ini sebagai read-only dan +Runner Docker live-model juga bind-mount checkout saat ini sebagai read-only dan men-stage-nya ke workdir sementara di dalam container. Ini menjaga image runtime tetap ramping sambil tetap menjalankan Vitest terhadap source/config lokal Anda yang persis. Langkah staging melewati cache lokal besar dan output build aplikasi seperti -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, dan direktori output `.build` atau -Gradle lokal aplikasi sehingga run live Docker tidak menghabiskan waktu bermenit-menit untuk menyalin +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, dan direktori output `.build` lokal aplikasi atau +Gradle sehingga run live Docker tidak menghabiskan waktu ber menit-menit untuk menyalin artefak yang spesifik mesin. -Mereka juga mengatur `OPENCLAW_SKIP_CHANNELS=1` sehingga probe live gateway tidak memulai +Runner ini juga menetapkan `OPENCLAW_SKIP_CHANNELS=1` sehingga probe live gateway tidak menyalakan worker channel Telegram/Discord/dll. nyata di dalam container. `test:docker:live-models` tetap menjalankan `pnpm test:live`, jadi teruskan juga `OPENCLAW_LIVE_GATEWAY_*` saat Anda perlu mempersempit atau mengecualikan cakupan live gateway dari lane Docker tersebut. -`test:docker:openwebui` adalah smoke kompatibilitas tingkat lebih tinggi: ia memulai +`test:docker:openwebui` adalah smoke kompatibilitas tingkat lebih tinggi: ia menyalakan container gateway OpenClaw dengan endpoint HTTP yang kompatibel dengan OpenAI diaktifkan, -memulai container Open WebUI yang dipin terhadap gateway tersebut, masuk melalui +menyalakan container Open WebUI yang dipin terhadap gateway tersebut, masuk melalui Open WebUI, memverifikasi `/api/models` mengekspos `openclaw/default`, lalu mengirim permintaan chat nyata melalui proxy `/api/chat/completions` milik Open WebUI. -Run pertama bisa terasa jauh lebih lambat karena Docker mungkin perlu menarik image -Open WebUI dan Open WebUI mungkin perlu menyelesaikan setup cold-start-nya sendiri. -Lane ini mengharapkan live model key yang dapat digunakan, dan `OPENCLAW_PROFILE_FILE` -(`~/.profile` secara default) adalah cara utama untuk menyediakannya dalam run yang didockerisasi. +Run pertama bisa terasa lebih lambat karena Docker mungkin perlu menarik +image Open WebUI dan Open WebUI mungkin perlu menyelesaikan setup cold-start miliknya sendiri. +Lane ini mengharapkan kunci model live yang dapat digunakan, dan `OPENCLAW_PROFILE_FILE` +(`~/.profile` secara default) adalah cara utama untuk menyediakannya dalam run berbasis Docker. Run yang berhasil mencetak payload JSON kecil seperti `{ "ok": true, "model": "openclaw/default", ... }`. -`test:docker:mcp-channels` sengaja deterministik dan tidak memerlukan akun -Telegram, Discord, atau iMessage nyata. Ia menyalakan container Gateway yang -di-seed, memulai container kedua yang menjalankan `openclaw mcp serve`, lalu -memverifikasi penemuan percakapan yang dirutekan, pembacaan transkrip, metadata attachment, -perilaku antrean event live, routing pengiriman outbound, dan notifikasi gaya Claude -tentang channel + izin melalui bridge MCP stdio nyata. Pemeriksaan notifikasi -memeriksa frame MCP stdio mentah secara langsung sehingga smoke memvalidasi apa yang -sebenarnya dipancarkan bridge, bukan hanya apa yang kebetulan diekspos oleh SDK klien tertentu. +`test:docker:mcp-channels` sengaja dibuat deterministik dan tidak memerlukan +akun Telegram, Discord, atau iMessage nyata. Ia menyalakan +container Gateway berisi seed, memulai container kedua yang menjalankan `openclaw mcp serve`, lalu +memverifikasi penemuan percakapan yang dirutekan, pembacaan transkrip, metadata lampiran, +perilaku antrean event live, routing pengiriman outbound, serta notifikasi channel + +izin bergaya Claude melalui bridge MCP stdio yang nyata. Pemeriksaan notifikasi +menginspeksi frame MCP stdio mentah secara langsung sehingga smoke memvalidasi apa yang benar-benar +dikeluarkan bridge, bukan hanya apa yang kebetulan ditampilkan oleh SDK klien tertentu. Smoke thread plain-language ACP manual (bukan CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Pertahankan skrip ini untuk alur kerja regresi/debug. Skrip ini mungkin dibutuhkan lagi untuk validasi routing thread ACP, jadi jangan hapus. +- Simpan skrip ini untuk alur kerja regresi/debug. Skrip ini mungkin diperlukan lagi untuk validasi routing thread ACP, jadi jangan hapus. Env var yang berguna: @@ -902,35 +906,35 @@ Env var yang berguna: - `OPENCLAW_WORKSPACE_DIR=...` (default: `~/.openclaw/workspace`) di-mount ke `/home/node/.openclaw/workspace` - `OPENCLAW_PROFILE_FILE=...` (default: `~/.profile`) di-mount ke `/home/node/.profile` dan di-source sebelum menjalankan pengujian - `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` untuk memverifikasi hanya env var yang di-source dari `OPENCLAW_PROFILE_FILE`, menggunakan direktori config/workspace sementara dan tanpa mount auth CLI eksternal -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (default: `~/.cache/openclaw/docker-cli-tools`) di-mount ke `/home/node/.npm-global` untuk instalasi CLI cache di dalam Docker -- Direktori/file auth CLI eksternal di bawah `$HOME` di-mount read-only di bawah `/host-auth...`, lalu disalin ke `/home/node/...` sebelum pengujian dimulai +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (default: `~/.cache/openclaw/docker-cli-tools`) di-mount ke `/home/node/.npm-global` untuk instalasi CLI yang di-cache di dalam Docker +- Direktori/file auth CLI eksternal di bawah `$HOME` di-mount sebagai read-only di bawah `/host-auth...`, lalu disalin ke `/home/node/...` sebelum pengujian dimulai - Direktori default: `.minimax` - File default: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Run provider yang dipersempit hanya me-mount direktori/file yang dibutuhkan yang diinferensikan dari `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Override secara manual dengan `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none`, atau daftar koma seperti `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` + - Run provider yang dipersempit hanya me-mount direktori/file yang diperlukan yang diinferensikan dari `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - Override manual dengan `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none`, atau daftar dipisahkan koma seperti `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` untuk mempersempit run - `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` untuk memfilter provider di dalam container -- `OPENCLAW_SKIP_DOCKER_BUILD=1` untuk menggunakan ulang image `openclaw:local-live` yang ada untuk rerun yang tidak memerlukan rebuild -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` untuk memastikan kredensial berasal dari profile store (bukan env) +- `OPENCLAW_SKIP_DOCKER_BUILD=1` untuk menggunakan ulang image `openclaw:local-live` yang sudah ada untuk rerun yang tidak memerlukan rebuild +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` untuk memastikan kredensial berasal dari penyimpanan profil (bukan env) - `OPENCLAW_OPENWEBUI_MODEL=...` untuk memilih model yang diekspos oleh gateway untuk smoke Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...` untuk meng-override prompt pemeriksaan nonce yang digunakan oleh smoke Open WebUI -- `OPENWEBUI_IMAGE=...` untuk meng-override tag image Open WebUI yang dipin +- `OPENCLAW_OPENWEBUI_PROMPT=...` untuk mengoverride prompt pemeriksaan nonce yang digunakan oleh smoke Open WebUI +- `OPENWEBUI_IMAGE=...` untuk mengoverride tag image Open WebUI yang dipin -## Kewajaran dokumen +## Kewarasan docs -Jalankan pemeriksaan dokumen setelah edit dokumen: `pnpm check:docs`. -Jalankan validasi anchor Mintlify penuh saat Anda juga memerlukan pemeriksaan heading dalam halaman: `pnpm docs:check-links:anchors`. +Jalankan pemeriksaan docs setelah mengedit docs: `pnpm check:docs`. +Jalankan validasi anchor Mintlify penuh ketika Anda juga memerlukan pemeriksaan heading dalam halaman: `pnpm docs:check-links:anchors`. ## Regresi offline (aman untuk CI) Ini adalah regresi “pipeline nyata” tanpa provider nyata: -- Tool calling gateway (mock OpenAI, gateway + loop agen nyata): `src/gateway/gateway.test.ts` (kasus: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Tool calling gateway (mock OpenAI, gateway nyata + loop agen): `src/gateway/gateway.test.ts` (kasus: "runs a mock OpenAI tool call end-to-end via gateway agent loop") - Wizard gateway (WS `wizard.start`/`wizard.next`, menulis config + auth ditegakkan): `src/gateway/gateway.test.ts` (kasus: "runs wizard over ws and writes auth token config") ## Evaluasi keandalan agen (Skills) -Kami sudah memiliki beberapa pengujian aman-CI yang berperilaku seperti “evaluasi keandalan agen”: +Kami sudah memiliki beberapa pengujian aman untuk CI yang berperilaku seperti “evaluasi keandalan agen”: - Mock tool-calling melalui gateway nyata + loop agen (`src/gateway/gateway.test.ts`). - Alur wizard end-to-end yang memvalidasi wiring sesi dan efek config (`src/gateway/gateway.test.ts`). @@ -938,21 +942,21 @@ Kami sudah memiliki beberapa pengujian aman-CI yang berperilaku seperti “evalu Yang masih kurang untuk Skills (lihat [Skills](/id/tools/skills)): - **Pengambilan keputusan:** saat Skills dicantumkan dalam prompt, apakah agen memilih skill yang tepat (atau menghindari yang tidak relevan)? -- **Kepatuhan:** apakah agen membaca `SKILL.md` sebelum digunakan dan mengikuti langkah/arg yang diwajibkan? -- **Kontrak alur kerja:** skenario multi-giliran yang menegaskan urutan tool, carryover riwayat sesi, dan batas sandbox. +- **Kepatuhan:** apakah agen membaca `SKILL.md` sebelum digunakan dan mengikuti langkah/argumen yang diwajibkan? +- **Kontrak alur kerja:** skenario multi-giliran yang menegaskan urutan tool, keterusan riwayat sesi, dan batas sandbox. -Evaluasi masa depan sebaiknya tetap deterministik terlebih dahulu: +Evaluasi mendatang harus tetap deterministik terlebih dahulu: -- Runner skenario menggunakan mock provider untuk menegaskan pemanggilan tool + urutan, pembacaan file skill, dan wiring sesi. +- Runner skenario yang menggunakan provider mock untuk menegaskan pemanggilan tool + urutannya, pembacaan file skill, dan wiring sesi. - Suite kecil skenario yang berfokus pada skill (gunakan vs hindari, gating, prompt injection). -- Evaluasi live opsional (opt-in, dijaga env) hanya setelah suite aman-CI tersedia. +- Evaluasi live opsional (opt-in, digerbangkan env) hanya setelah suite aman untuk CI tersedia. ## Pengujian kontrak (bentuk plugin dan channel) -Pengujian kontrak memverifikasi bahwa setiap plugin dan channel yang terdaftar sesuai -dengan kontrak interfacenya. Mereka mengiterasi semua plugin yang ditemukan dan menjalankan serangkaian -penegasan bentuk dan perilaku. Lane unit default `pnpm test` dengan sengaja -melewati file seam bersama dan smoke ini; jalankan perintah kontrak secara eksplisit +Pengujian kontrak memverifikasi bahwa setiap plugin dan channel yang terdaftar sesuai dengan +kontrak interfacenya. Pengujian ini mengiterasi seluruh plugin yang ditemukan dan menjalankan +serangkaian asersi bentuk dan perilaku. Lane unit default `pnpm test` +sengaja melewati file seam dan smoke bersama ini; jalankan perintah kontrak secara eksplisit saat Anda menyentuh surface channel atau provider bersama. ### Perintah @@ -963,11 +967,11 @@ saat Anda menyentuh surface channel atau provider bersama. ### Kontrak channel -Terletak di `src/channels/plugins/contracts/*.contract.test.ts`: +Berada di `src/channels/plugins/contracts/*.contract.test.ts`: - **plugin** - Bentuk plugin dasar (id, nama, kapabilitas) - **setup** - Kontrak wizard setup -- **session-binding** - Perilaku binding sesi +- **session-binding** - Perilaku pengikatan sesi - **outbound-payload** - Struktur payload pesan - **inbound** - Penanganan pesan inbound - **actions** - Handler aksi channel @@ -977,14 +981,14 @@ Terletak di `src/channels/plugins/contracts/*.contract.test.ts`: ### Kontrak status provider -Terletak di `src/plugins/contracts/*.contract.test.ts`. +Berada di `src/plugins/contracts/*.contract.test.ts`. - **status** - Probe status channel - **registry** - Bentuk registri plugin ### Kontrak provider -Terletak di `src/plugins/contracts/*.contract.test.ts`: +Berada di `src/plugins/contracts/*.contract.test.ts`: - **auth** - Kontrak alur auth - **auth-choice** - Pilihan/seleksi auth @@ -995,11 +999,11 @@ Terletak di `src/plugins/contracts/*.contract.test.ts`: - **shape** - Bentuk/interface plugin - **wizard** - Wizard setup -### Kapan dijalankan +### Kapan menjalankan -- Setelah mengubah export atau subpath Plugin SDK -- Setelah menambahkan atau memodifikasi plugin channel atau provider -- Setelah melakukan refactor registrasi atau penemuan plugin +- Setelah mengubah ekspor atau subpath plugin-sdk +- Setelah menambahkan atau memodifikasi channel atau Plugin provider +- Setelah merombak registrasi atau penemuan plugin Pengujian kontrak berjalan di CI dan tidak memerlukan API key nyata. @@ -1007,11 +1011,11 @@ Pengujian kontrak berjalan di CI dan tidak memerlukan API key nyata. Saat Anda memperbaiki masalah provider/model yang ditemukan di live: -- Tambahkan regresi aman-CI jika memungkinkan (mock/stub provider, atau tangkap transformasi bentuk permintaan yang tepat) +- Tambahkan regresi yang aman untuk CI jika memungkinkan (provider mock/stub, atau tangkap transformasi bentuk permintaan yang tepat) - Jika secara inheren hanya live (rate limit, kebijakan auth), pertahankan pengujian live tetap sempit dan opt-in melalui env var -- Utamakan menargetkan lapisan terkecil yang menangkap bug: +- Utamakan penargetan lapisan terkecil yang menangkap bug: - bug konversi/replay permintaan provider → pengujian model langsung - - bug pipeline sesi/riwayat/tool gateway → gateway live smoke atau pengujian mock gateway aman-CI + - bug pipeline sesi/riwayat/tool gateway → gateway live smoke atau pengujian mock gateway yang aman untuk CI - Guardrail traversal SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` menurunkan satu target sampel per kelas SecretRef dari metadata registri (`listSecretTargetRegistryEntries()`), lalu menegaskan bahwa exec id segmen traversal ditolak. - - Jika Anda menambahkan keluarga target SecretRef `includeInPlan` baru di `src/secrets/target-registry-data.ts`, perbarui `classifyTargetClass` di pengujian tersebut. Pengujian ini sengaja gagal pada target id yang tidak terklasifikasi sehingga kelas baru tidak dapat dilewati secara diam-diam. + - `src/secrets/exec-secret-ref-id-parity.test.ts` menurunkan satu target sampel per kelas SecretRef dari metadata registri (`listSecretTargetRegistryEntries()`), lalu menegaskan ID exec traversal-segment ditolak. + - Jika Anda menambahkan keluarga target SecretRef `includeInPlan` baru di `src/secrets/target-registry-data.ts`, perbarui `classifyTargetClass` dalam pengujian tersebut. Pengujian ini sengaja gagal pada ID target yang tidak terklasifikasi sehingga kelas baru tidak dapat dilewati secara diam-diam. diff --git a/docs/id/platforms/macos.md b/docs/id/platforms/macos.md index f8499d9c1..2934865a7 100644 --- a/docs/id/platforms/macos.md +++ b/docs/id/platforms/macos.md @@ -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.` 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.` 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.` 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 `: override config - `--mode `: resolve dari config (default: config atau local) - `--probe`: paksa health probe baru -- `--timeout `: timeout permintaan (default: `15000`) +- `--timeout `: 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 `: 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 :127.0.0.1:` 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) diff --git a/docs/id/plugins/sdk-migration.md b/docs/id/plugins/sdk-migration.md index 3d633a7b7..b43262e19 100644 --- a/docs/id/plugins/sdk-migration.md +++ b/docs/id/plugins/sdk-migration.md @@ -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. 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/\`) -adalah modul kecil yang mandiri dengan tujuan yang jelas dan kontrak yang terdokumentasi. +Plugin SDK modern memperbaiki ini: setiap jalur impor (`openclaw/plugin-sdk/\`) 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 - - Plugin kanal yang mendukung approval sekarang mengekspos perilaku approval native melalui + + 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. @@ -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. - 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: - 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: -## Referensi path impor +## Referensi jalur impor - - | Path impor | Tujuan | Ekspor utama | + + | 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 | -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 diff --git a/docs/id/plugins/sdk-overview.md b/docs/id/plugins/sdk-overview.md index 8b536fb26..065ddd6d5 100644 --- a/docs/id/plugins/sdk-overview.md +++ b/docs/id/plugins/sdk-overview.md @@ -1,16 +1,16 @@ --- read_when: - Anda perlu mengetahui subpath SDK mana yang harus diimpor dari 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 | | 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 | @@ -154,113 +155,113 @@ secara eksplisit mempromosikannya sebagai publik. | 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 | | 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` | | 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` | @@ -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 | - | 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` | @@ -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.`. - Config pengguna tetap menang. OpenClaw menggabungkan `agents.defaults.cliBackends.` 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` | Config khusus plugin dari `plugins.entries..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) ``` Jangan pernah mengimpor plugin Anda sendiri melalui `openclaw/plugin-sdk/` 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. -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 Kode produksi extension juga harus menghindari impor `openclaw/plugin-sdk/`. - 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. ## 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 diff --git a/docs/id/tools/thinking.md b/docs/id/tools/thinking.md index 40dbdfe2c..77eb41cb8 100644 --- a/docs/id/tools/thinking.md +++ b/docs/id/tools/thinking.md @@ -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 `, `/think:`, atau `/thinking `. +- Direktif inline di badan pesan masuk apa pun: `/t `, `/think:`, atau `/thinking `. - 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["/"].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 ` : ` 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 ` : ` 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 ()`, 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 ()`, 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:` tetap berfungsi dan memperbarui level sesi tersimpan yang sama, sehingga directive chat dan picker tetap sinkron. +- `/think:` tetap berfungsi dan memperbarui level sesi tersimpan yang sama, sehingga direktif chat dan pemilih tetap sinkron.