diff --git a/docs/id/ci.md b/docs/id/ci.md index 06e7b0d28..0fd1603ae 100644 --- a/docs/id/ci.md +++ b/docs/id/ci.md @@ -1,89 +1,90 @@ --- read_when: - - Anda perlu memahami mengapa sebuah job CI berjalan atau tidak berjalan + - Anda perlu memahami mengapa sebuah pekerjaan CI berjalan atau tidak berjalan - Anda sedang men-debug pemeriksaan GitHub Actions yang gagal -summary: Grafik job CI, gate cakupan, dan padanan perintah lokal +summary: Grafik pekerjaan CI, gerbang cakupan, dan padanan perintah lokal title: Pipeline CI x-i18n: - generated_at: "2026-04-22T04:21:11Z" + generated_at: "2026-04-22T09:14:36Z" model: gpt-5.4 provider: openai - source_hash: ae08bad6cbd0f2eced6c88a792a11bc1c2b1a2bfb003a56f70ff328a2739d3fc + source_hash: fc7ec59123aee65634736320dbf1cf5cdfb08786a78cca82ce9596fedc68b3cc source_path: ci.md workflow: 15 --- # Pipeline CI -CI berjalan pada setiap push ke `main` dan setiap pull request. CI menggunakan scoping cerdas untuk melewati job mahal saat hanya area yang tidak terkait yang berubah. +CI berjalan pada setiap push ke `main` dan setiap pull request. CI menggunakan cakupan cerdas untuk melewati pekerjaan mahal ketika hanya area yang tidak terkait yang berubah. -## Ikhtisar job +## Ikhtisar Pekerjaan -| Job | Tujuan | Kapan berjalan | -| -------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------ | -| `preflight` | Mendeteksi perubahan docs-only, cakupan yang berubah, extension yang berubah, dan membangun manifes CI | Selalu pada push dan PR non-draft | -| `security-scm-fast` | Deteksi private key dan audit workflow melalui `zizmor` | Selalu pada push dan PR non-draft | -| `security-dependency-audit` | Audit lockfile produksi tanpa dependensi terhadap advisory npm | Selalu pada push dan PR non-draft | -| `security-fast` | Agregat wajib untuk job keamanan cepat | Selalu pada push dan PR non-draft | -| `build-artifacts` | Membangun `dist/` dan UI Control satu kali, mengunggah artifact yang dapat dipakai ulang untuk job hilir | Perubahan yang relevan dengan Node | -| `checks-fast-core` | Lane korektness Linux cepat seperti pemeriksaan bundled/plugin-contract/protocol | Perubahan yang relevan dengan Node | -| `checks-fast-contracts-channels` | Pemeriksaan kontrak channel yang di-shard dengan hasil pemeriksaan agregat yang stabil | Perubahan yang relevan dengan Node | -| `checks-node-extensions` | Shard pengujian Plugin bawaan penuh di seluruh suite extension | Perubahan yang relevan dengan Node | -| `checks-node-core-test` | Shard pengujian Node inti, tidak termasuk lane channel, bundled, contract, dan extension | Perubahan yang relevan dengan Node | -| `extension-fast` | Pengujian terfokus hanya untuk plugin bawaan yang berubah | Saat perubahan extension terdeteksi | -| `check` | Padanan gate lokal utama yang di-shard: prod types, lint, guard, test types, dan smoke ketat | Perubahan yang relevan dengan Node | -| `check-additional` | Guard arsitektur, boundary, extension-surface, package-boundary, dan shard gateway-watch | Perubahan yang relevan dengan Node | -| `build-smoke` | Smoke test CLI hasil build dan smoke memori startup | Perubahan yang relevan dengan Node | -| `checks` | Lane Linux Node yang tersisa: pengujian channel dan kompatibilitas Node 22 khusus push | Perubahan yang relevan dengan Node | -| `check-docs` | Pemeriksaan formatting, lint, dan broken-link docs | Docs berubah | +| Pekerjaan | Tujuan | Kapan berjalan | +| -------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------- | +| `preflight` | Mendeteksi perubahan khusus docs, cakupan yang berubah, extension yang berubah, dan membangun manifes CI | Selalu pada push dan PR non-draf | +| `security-scm-fast` | Deteksi private key dan audit workflow melalui `zizmor` | Selalu pada push dan PR non-draf | +| `security-dependency-audit` | Audit lockfile produksi tanpa dependensi terhadap advisory npm | Selalu pada push dan PR non-draf | +| `security-fast` | Agregat wajib untuk pekerjaan security cepat | Selalu pada push dan PR non-draf | +| `build-artifacts` | Membangun `dist/` dan UI Control satu kali, mengunggah artifact yang dapat digunakan ulang untuk pekerjaan turunan | Perubahan yang relevan dengan Node | +| `checks-fast-core` | Lane korektness Linux cepat seperti pemeriksaan bundled/plugin-contract/protocol | Perubahan yang relevan dengan Node | +| `checks-fast-contracts-channels` | Pemeriksaan kontrak channel yang di-shard dengan hasil pemeriksaan agregat yang stabil | Perubahan yang relevan dengan Node | +| `checks-node-extensions` | Shard pengujian bundled-plugin penuh di seluruh suite extension | Perubahan yang relevan dengan Node | +| `checks-node-core-test` | Shard pengujian core Node, tidak termasuk lane channel, bundled, contract, dan extension | Perubahan yang relevan dengan Node | +| `extension-fast` | Pengujian terfokus hanya untuk bundled plugin yang berubah | Saat perubahan extension terdeteksi | +| `check` | Padanan gerbang lokal utama yang di-shard: tipe prod, lint, guard, tipe uji, dan smoke ketat | Perubahan yang relevan dengan Node | +| `check-additional` | Guard arsitektur, boundary, extension-surface, package-boundary, dan shard gateway-watch | Perubahan yang relevan dengan Node | +| `build-smoke` | Pengujian smoke CLI hasil build dan smoke startup-memory | Perubahan yang relevan dengan Node | +| `checks` | Lane Linux Node yang tersisa: pengujian channel dan kompatibilitas Node 22 khusus push | Perubahan yang relevan dengan Node | +| `check-docs` | Pemeriksaan pemformatan, lint, dan tautan rusak docs | Docs berubah | | `skills-python` | Ruff + pytest untuk Skills berbasis Python | Perubahan yang relevan dengan skill Python | | `checks-windows` | Lane pengujian khusus Windows | Perubahan yang relevan dengan Windows | -| `macos-node` | Lane pengujian TypeScript macOS menggunakan artifact hasil build bersama | Perubahan yang relevan dengan macOS | -| `macos-swift` | Swift lint, build, dan test untuk aplikasi macOS | Perubahan yang relevan dengan macOS | -| `android` | Matriks build dan test Android | Perubahan yang relevan dengan Android | +| `macos-node` | Lane pengujian TypeScript macOS menggunakan artifact hasil build bersama | Perubahan yang relevan dengan macOS | +| `macos-swift` | Lint, build, dan pengujian Swift untuk aplikasi macOS | Perubahan yang relevan dengan macOS | +| `android` | Matriks build dan pengujian Android | Perubahan yang relevan dengan Android | -## Urutan fail-fast +## Urutan Fail-Fast -Job diurutkan agar pemeriksaan murah gagal sebelum job mahal berjalan: +Pekerjaan diurutkan agar pemeriksaan murah gagal lebih dulu sebelum pekerjaan mahal berjalan: -1. `preflight` menentukan lane mana yang ada sama sekali. Logika `docs-scope` dan `changed-scope` adalah step di dalam job ini, bukan job terpisah. -2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs`, dan `skills-python` gagal cepat tanpa menunggu job artifact dan matriks platform yang lebih berat. -3. `build-artifacts` berjalan tumpang tindih dengan lane Linux cepat agar consumer hilir dapat mulai segera setelah build bersama siap. -4. Lane platform dan runtime yang lebih berat kemudian menyebar: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, `extension-fast`, `checks`, `checks-windows`, `macos-node`, `macos-swift`, dan `android`. +1. `preflight` menentukan lane mana yang ada sama sekali. Logika `docs-scope` dan `changed-scope` adalah langkah di dalam pekerjaan ini, bukan pekerjaan terpisah. +2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs`, dan `skills-python` gagal cepat tanpa menunggu pekerjaan artifact dan matriks platform yang lebih berat. +3. `build-artifacts` berjalan tumpang tindih dengan lane Linux cepat agar konsumen turunan dapat mulai segera setelah build bersama siap. +4. Setelah itu, lane platform dan runtime yang lebih berat menyebar: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, `extension-fast`, `checks`, `checks-windows`, `macos-node`, `macos-swift`, dan `android`. Logika cakupan berada di `scripts/ci-changed-scope.mjs` dan dicakup oleh unit test di `src/scripts/ci-changed-scope.test.ts`. -Workflow `install-smoke` yang terpisah menggunakan ulang skrip cakupan yang sama melalui job `preflight` miliknya sendiri. Workflow ini menghitung `run_install_smoke` dari sinyal changed-smoke yang lebih sempit, sehingga smoke Docker/install hanya berjalan untuk perubahan yang relevan dengan install, packaging, dan container. +Workflow `install-smoke` yang terpisah menggunakan kembali skrip cakupan yang sama melalui pekerjaan `preflight` miliknya sendiri. Workflow ini menghitung `run_install_smoke` dari sinyal changed-smoke yang lebih sempit, sehingga smoke Docker/install hanya berjalan untuk perubahan yang relevan dengan install, packaging, dan container. -Logika lane-perubahan lokal berada di `scripts/changed-lanes.mjs` dan dijalankan oleh `scripts/check-changed.mjs`. Gate lokal tersebut lebih ketat terhadap boundary arsitektur dibanding cakupan platform CI yang luas: perubahan produksi inti menjalankan typecheck prod inti ditambah pengujian inti, perubahan test-only inti hanya menjalankan typecheck/test inti, perubahan produksi extension menjalankan typecheck prod extension ditambah pengujian extension, dan perubahan test-only extension hanya menjalankan typecheck/test extension. Perubahan public Plugin SDK atau plugin-contract diperluas ke validasi extension karena extension bergantung pada kontrak inti tersebut. Kenaikan versi metadata-only rilis menjalankan pemeriksaan versi/konfigurasi/dependensi root yang terarah. Perubahan root/konfigurasi yang tidak diketahui gagal-aman ke semua lane. +Logika changed-lane lokal berada di `scripts/changed-lanes.mjs` dan dijalankan oleh `scripts/check-changed.mjs`. Gerbang lokal itu lebih ketat terhadap boundary arsitektur dibanding cakupan platform CI yang luas: perubahan produksi core menjalankan typecheck prod core plus pengujian core, perubahan khusus pengujian core hanya menjalankan typecheck/pengujian core test, perubahan produksi extension menjalankan typecheck prod extension plus pengujian extension, dan perubahan khusus pengujian extension hanya menjalankan typecheck/pengujian extension test. Perubahan pada Plugin SDK publik atau plugin-contract memperluas validasi ke extension karena extension bergantung pada kontrak core tersebut. Kenaikan versi khusus metadata rilis menjalankan pemeriksaan versi/konfigurasi/dependensi root yang ditargetkan. Perubahan root/konfigurasi yang tidak dikenal akan fail-safe ke semua lane. -Pada push, matriks `checks` menambahkan lane `compat-node22` yang khusus push. Pada pull request, lane tersebut dilewati dan matriks tetap fokus pada lane test/channel normal. +Pada push, matriks `checks` menambahkan lane `compat-node22` khusus push. Pada pull request, lane itu dilewati dan matriks tetap berfokus pada lane test/channel normal. -Keluarga pengujian Node yang paling lambat dibagi menjadi shard include-file agar setiap job tetap kecil: kontrak channel membagi cakupan registry dan core menjadi masing-masing delapan shard berbobot, pengujian perintah reply auto-reply dibagi menjadi empat shard include-pattern, dan grup prefix reply auto-reply besar lainnya dibagi menjadi masing-masing dua shard. `check-additional` juga memisahkan pekerjaan package-boundary compile/canary dari pekerjaan runtime topology gateway/architecture. +Keluarga pengujian Node yang paling lambat dibagi menjadi shard include-file agar setiap pekerjaan tetap kecil: kontrak channel membagi cakupan registry dan core menjadi masing-masing delapan shard berbobot, pengujian perintah balasan auto-reply dibagi menjadi empat shard include-pattern, dan kelompok prefix balasan auto-reply besar lainnya dibagi menjadi masing-masing dua shard. `check-additional` juga memisahkan pekerjaan compile/canary package-boundary dari pekerjaan runtime topology gateway/architecture. -GitHub dapat menandai job yang tergantikan sebagai `cancelled` saat push yang lebih baru masuk pada PR atau ref `main` yang sama. Perlakukan ini sebagai noise CI kecuali run terbaru untuk ref yang sama juga gagal. Pemeriksaan shard agregat secara eksplisit menyebut kasus pembatalan ini agar lebih mudah dibedakan dari kegagalan test. +GitHub dapat menandai pekerjaan yang sudah digantikan sebagai `cancelled` ketika push yang lebih baru masuk pada PR atau ref `main` yang sama. Anggap itu sebagai noise CI kecuali run terbaru untuk ref yang sama juga gagal. Pemeriksaan shard agregat secara eksplisit menandai kasus pembatalan ini agar lebih mudah dibedakan dari kegagalan pengujian. ## Runner -| Runner | Job | -| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -| `blacksmith-16vcpu-ubuntu-2404` | `preflight`, `security-scm-fast`, `security-dependency-audit`, `security-fast`, `build-artifacts`, pemeriksaan Linux, pemeriksaan docs, Skills Python, `android` | -| `blacksmith-32vcpu-windows-2025` | `checks-windows` | -| `blacksmith-12vcpu-macos-latest` | `macos-node`, `macos-swift` pada `openclaw/openclaw`; fork menggunakan fallback ke `macos-latest` | +| Runner | Pekerjaan | +| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| `ubuntu-24.04` | `preflight`; preflight install-smoke juga menggunakan Ubuntu yang di-host GitHub agar matriks Blacksmith dapat antre lebih awal | +| `blacksmith-16vcpu-ubuntu-2404` | `security-scm-fast`, `security-dependency-audit`, `security-fast`, `build-artifacts`, pemeriksaan Linux, pemeriksaan docs, Skills Python, `android` | +| `blacksmith-32vcpu-windows-2025` | `checks-windows` | +| `blacksmith-12vcpu-macos-latest` | `macos-node`, `macos-swift` pada `openclaw/openclaw`; fork kembali menggunakan `macos-latest` | -## Padanan lokal +## Padanan Lokal ```bash -pnpm changed:lanes # periksa classifier lane-perubahan lokal untuk origin/main...HEAD -pnpm check:changed # gate lokal cerdas: typecheck/lint/test yang berubah per lane boundary -pnpm check # gate lokal cepat: tsgo produksi + lint yang di-shard + fast guard paralel +pnpm changed:lanes # periksa classifier changed-lane lokal untuk origin/main...HEAD +pnpm check:changed # gerbang lokal cerdas: typecheck/lint/pengujian yang berubah menurut boundary lane +pnpm check # gerbang lokal cepat: tsgo produksi + lint yang di-shard + fast guard paralel pnpm check:test-types -pnpm check:timed # gate yang sama dengan timing per tahap +pnpm check:timed # gerbang yang sama dengan timing per tahap pnpm build:strict-smoke pnpm check:architecture pnpm test:gateway:watch-regression -pnpm test # test vitest +pnpm test # pengujian vitest pnpm test:channels pnpm test:contracts:channels -pnpm check:docs # format + lint + broken links docs -pnpm build # build dist saat lane artifact/build-smoke CI relevan +pnpm check:docs # format docs + lint + tautan rusak +pnpm build # bangun dist saat lane CI artifact/build-smoke relevan ``` diff --git a/docs/id/concepts/typing-indicators.md b/docs/id/concepts/typing-indicators.md index 3888dd42c..ae9d0b7a2 100644 --- a/docs/id/concepts/typing-indicators.md +++ b/docs/id/concepts/typing-indicators.md @@ -4,42 +4,43 @@ read_when: summary: Kapan OpenClaw menampilkan indikator mengetik dan cara menyesuaikannya title: Indikator Mengetik x-i18n: - generated_at: "2026-04-05T13:52:34Z" + generated_at: "2026-04-22T09:14:45Z" model: gpt-5.4 provider: openai - source_hash: 28c8c395a135fc0745181aab66a93582177e6acd0b3496debcbb98159a4f11dc + source_hash: 2e7e8ca448b6706b6f53fcb6a582be6d4a84715c82dfde3d53abe4268af3ae0d source_path: concepts/typing-indicators.md workflow: 15 --- # Indikator mengetik -Indikator mengetik dikirim ke channel chat selama sebuah run aktif. Gunakan +Indikator mengetik dikirim ke saluran chat saat sebuah run aktif. Gunakan `agents.defaults.typingMode` untuk mengontrol **kapan** pengetikan dimulai dan `typingIntervalSeconds` -untuk mengontrol **seberapa sering** indikator itu diperbarui. +untuk mengontrol **seberapa sering** indikator tersebut diperbarui. ## Default -Saat `agents.defaults.typingMode` **tidak diatur**, OpenClaw mempertahankan perilaku lama: +Ketika `agents.defaults.typingMode` **tidak disetel**, OpenClaw mempertahankan perilaku lama: - **Chat langsung**: pengetikan dimulai segera setelah loop model dimulai. - **Chat grup dengan mention**: pengetikan dimulai segera. -- **Chat grup tanpa mention**: pengetikan dimulai hanya saat teks pesan mulai di-stream. -- **Run heartbeat**: pengetikan dinonaktifkan. +- **Chat grup tanpa mention**: pengetikan dimulai hanya ketika teks pesan mulai di-streaming. +- **Run Heartbeat**: pengetikan dimulai saat run heartbeat dimulai jika + target heartbeat yang di-resolve adalah chat yang mendukung pengetikan dan pengetikan tidak dinonaktifkan. ## Mode -Atur `agents.defaults.typingMode` ke salah satu dari: +Setel `agents.defaults.typingMode` ke salah satu dari: -- `never` — tidak ada indikator mengetik, kapan pun. +- `never` — tidak pernah menampilkan indikator mengetik. - `instant` — mulai mengetik **segera setelah loop model dimulai**, meskipun run nantinya hanya mengembalikan token balasan senyap. -- `thinking` — mulai mengetik pada **delta reasoning pertama** (memerlukan +- `thinking` — mulai mengetik pada **delta penalaran pertama** (memerlukan `reasoningLevel: "stream"` untuk run tersebut). - `message` — mulai mengetik pada **delta teks non-senyap pertama** (mengabaikan token senyap `NO_REPLY`). -Urutan berdasarkan “seberapa cepat indikator muncul”: +Urutan berdasarkan “seberapa cepat indikator aktif”: `never` → `message` → `thinking` → `instant` ## Konfigurasi @@ -53,7 +54,7 @@ Urutan berdasarkan “seberapa cepat indikator muncul”: } ``` -Anda dapat menimpa mode atau jeda per sesi: +Anda dapat menimpa mode atau frekuensi per sesi: ```json5 { @@ -66,11 +67,16 @@ Anda dapat menimpa mode atau jeda per sesi: ## Catatan -- Mode `message` tidak akan menampilkan indikator mengetik untuk balasan yang hanya senyap jika seluruh - payload adalah token senyap yang persis sama (misalnya `NO_REPLY` / `no_reply`, - dicocokkan tanpa peka huruf besar-kecil). -- `thinking` hanya aktif jika run melakukan streaming reasoning (`reasoningLevel: "stream"`). - Jika model tidak mengeluarkan delta reasoning, indikator mengetik tidak akan dimulai. -- Heartbeat tidak pernah menampilkan indikator mengetik, apa pun modenya. -- `typingIntervalSeconds` mengontrol **irama pembaruan**, bukan waktu mulai. +- Mode `message` tidak akan menampilkan indikator mengetik untuk balasan yang hanya senyap ketika seluruh + payload adalah token senyap yang sama persis (misalnya `NO_REPLY` / `no_reply`, + dicocokkan tanpa membedakan huruf besar-kecil). +- `thinking` hanya aktif jika run melakukan streaming penalaran (`reasoningLevel: "stream"`). + Jika model tidak menghasilkan delta penalaran, pengetikan tidak akan dimulai. +- Pengetikan Heartbeat adalah sinyal liveness untuk target pengiriman yang telah di-resolve. Ini + dimulai pada awal run heartbeat alih-alih mengikuti waktu streaming `message` atau `thinking`. + Setel `typingMode: "never"` untuk menonaktifkannya. +- Heartbeat tidak menampilkan indikator mengetik saat `target: "none"`, saat target tidak dapat + di-resolve, saat pengiriman chat dinonaktifkan untuk heartbeat, atau saat + saluran tidak mendukung pengetikan. +- `typingIntervalSeconds` mengontrol **frekuensi pembaruan**, bukan waktu mulai. Default-nya adalah 6 detik. diff --git a/docs/id/gateway/cli-backends.md b/docs/id/gateway/cli-backends.md index f5fe27586..2dea2425e 100644 --- a/docs/id/gateway/cli-backends.md +++ b/docs/id/gateway/cli-backends.md @@ -1,47 +1,47 @@ --- read_when: - Anda menginginkan fallback yang andal saat penyedia API gagal - - Anda menjalankan Codex CLI atau CLI AI lokal lain dan ingin menggunakannya kembali - - Anda ingin memahami bridge local loopback MCP untuk akses alat backend CLI -summary: 'Backend CLI: fallback CLI AI lokal dengan bridge alat MCP opsional' + - Anda menjalankan Codex CLI atau CLI AI lokal lainnya dan ingin menggunakannya kembali + - Anda ingin memahami jembatan loopback MCP untuk akses alat backend CLI +summary: 'Backend CLI: fallback CLI AI lokal dengan jembatan alat MCP opsional' title: Backend CLI x-i18n: - generated_at: "2026-04-16T19:31:01Z" + generated_at: "2026-04-22T09:14:37Z" model: gpt-5.4 provider: openai - source_hash: 381273532a8622bc4628000a6fb999712b12af08faade2b5f2b7ac4cc7d23efe + source_hash: 3566d4f2b7a841473a4ed6379c1abd8dbd06c392dbff15ca37c4f8ea1e1ead51 source_path: gateway/cli-backends.md workflow: 15 --- # Backend CLI (runtime fallback) -OpenClaw dapat menjalankan **CLI AI lokal** sebagai **fallback khusus teks** saat penyedia API sedang tidak tersedia, -terkena rate limit, atau sementara bermasalah. Pendekatan ini sengaja dibuat konservatif: +OpenClaw dapat menjalankan **CLI AI lokal** sebagai **fallback hanya-teks** ketika penyedia API sedang down, +terkena pembatasan laju, atau sementara bermasalah. Ini sengaja dibuat konservatif: - **Alat OpenClaw tidak disuntikkan secara langsung**, tetapi backend dengan `bundleMcp: true` - dapat menerima alat gateway melalui bridge MCP local loopback. + dapat menerima alat gateway melalui jembatan MCP loopback. - **Streaming JSONL** untuk CLI yang mendukungnya. -- **Sesi didukung** (agar giliran tindak lanjut tetap koheren). +- **Sesi didukung** (sehingga giliran lanjutan tetap koheren). - **Gambar dapat diteruskan** jika CLI menerima path gambar. Ini dirancang sebagai **jaring pengaman** alih-alih jalur utama. Gunakan ini saat Anda -menginginkan respons teks yang “selalu berfungsi” tanpa bergantung pada API eksternal. +menginginkan respons teks “selalu berfungsi” tanpa bergantung pada API eksternal. Jika Anda menginginkan runtime harness penuh dengan kontrol sesi ACP, tugas latar belakang, -binding thread/percakapan, dan sesi coding eksternal persisten, gunakan -[ACP Agents](/id/tools/acp-agents) sebagai gantinya. Backend CLI bukan ACP. +pengikatan thread/percakapan, dan sesi coding eksternal persisten, gunakan +[ACP Agents](/id/tools/acp-agents). Backend CLI bukan ACP. ## Mulai cepat yang ramah pemula -Anda dapat menggunakan Codex CLI **tanpa konfigurasi apa pun** (Plugin OpenAI bawaan +Anda dapat menggunakan Codex CLI **tanpa konfigurasi apa pun** (plugin OpenAI bawaan mendaftarkan backend default): ```bash openclaw agent --message "hi" --model codex-cli/gpt-5.4 ``` -Jika gateway Anda berjalan di bawah launchd/systemd dan PATH minimal, tambahkan hanya +Jika Gateway Anda berjalan di bawah launchd/systemd dan PATH minimal, tambahkan hanya path perintahnya: ```json5 @@ -58,16 +58,16 @@ path perintahnya: } ``` -Itu saja. Tidak diperlukan key maupun konfigurasi autentikasi tambahan selain yang dimiliki CLI itu sendiri. +Selesai. Tidak perlu kunci, tidak perlu konfigurasi autentikasi tambahan selain yang dibutuhkan oleh CLI itu sendiri. Jika Anda menggunakan backend CLI bawaan sebagai **penyedia pesan utama** pada host -gateway, OpenClaw kini otomatis memuat Plugin bawaan pemiliknya saat konfigurasi Anda -secara eksplisit merujuk backend tersebut dalam model ref atau di bawah +Gateway, OpenClaw sekarang otomatis memuat plugin bawaan pemiliknya ketika konfigurasi Anda +secara eksplisit merujuk backend tersebut dalam ref model atau di bawah `agents.defaults.cliBackends`. ## Menggunakannya sebagai fallback -Tambahkan backend CLI ke daftar fallback Anda agar hanya dijalankan saat model utama gagal: +Tambahkan backend CLI ke daftar fallback Anda agar hanya berjalan saat model utama gagal: ```json5 { @@ -89,10 +89,10 @@ Tambahkan backend CLI ke daftar fallback Anda agar hanya dijalankan saat model u Catatan: - Jika Anda menggunakan `agents.defaults.models` (allowlist), Anda juga harus menyertakan model backend CLI di sana. -- Jika penyedia utama gagal (autentikasi, rate limit, timeout), OpenClaw akan +- Jika penyedia utama gagal (autentikasi, pembatasan laju, timeout), OpenClaw akan mencoba backend CLI berikutnya. -## Ikhtisar konfigurasi +## Ringkasan konfigurasi Semua backend CLI berada di bawah: @@ -100,8 +100,8 @@ Semua backend CLI berada di bawah: agents.defaults.cliBackends ``` -Setiap entri dikunci dengan **id penyedia** (misalnya `codex-cli`, `my-cli`). -Id penyedia menjadi sisi kiri model ref Anda: +Setiap entri diberi kunci berupa **id penyedia** (misalnya `codex-cli`, `my-cli`). +Id penyedia menjadi sisi kiri dari ref model Anda: ``` / @@ -148,69 +148,76 @@ Id penyedia menjadi sisi kiri model ref Anda: ## Cara kerjanya 1. **Memilih backend** berdasarkan prefiks penyedia (`codex-cli/...`). -2. **Membangun system prompt** menggunakan prompt OpenClaw yang sama + konteks workspace. +2. **Membangun prompt sistem** menggunakan prompt OpenClaw + konteks workspace yang sama. 3. **Menjalankan CLI** dengan id sesi (jika didukung) agar riwayat tetap konsisten. -4. **Mem-parsing output** (JSON atau teks biasa) dan mengembalikan teks akhir. -5. **Menyimpan id sesi** per backend, sehingga tindak lanjut menggunakan kembali sesi CLI yang sama. + Backend `claude-cli` bawaan mempertahankan proses stdio Claude tetap hidup per + sesi OpenClaw dan mengirim giliran lanjutan melalui stdin stream-json. +4. **Mengurai output** (JSON atau teks biasa) dan mengembalikan teks akhir. +5. **Menyimpan id sesi** per backend, sehingga giliran lanjutan menggunakan kembali sesi CLI yang sama. -Backend `claude-cli` Anthropic bawaan kembali didukung. Staf Anthropic -memberi tahu kami bahwa penggunaan Claude CLI bergaya OpenClaw kembali diizinkan, sehingga OpenClaw memperlakukan penggunaan -`claude -p` sebagai penggunaan yang disetujui untuk integrasi ini kecuali Anthropic menerbitkan +Backend `claude-cli` Anthropic bawaan kini didukung lagi. Staf Anthropic +memberi tahu kami bahwa penggunaan Claude CLI bergaya OpenClaw diizinkan lagi, sehingga OpenClaw memperlakukan +penggunaan `claude -p` sebagai sesuatu yang disetujui untuk integrasi ini kecuali Anthropic menerbitkan kebijakan baru. -Backend `codex-cli` OpenAI bawaan meneruskan system prompt OpenClaw melalui +Backend `codex-cli` OpenAI bawaan meneruskan prompt sistem OpenClaw melalui override konfigurasi `model_instructions_file` Codex (`-c -model_instructions_file="..."`). Codex tidak menyediakan flag -`--append-system-prompt` seperti Claude, sehingga OpenClaw menulis prompt yang dirangkai ke sebuah +model_instructions_file="..."`). Codex tidak menyediakan flag bergaya Claude +`--append-system-prompt`, jadi OpenClaw menulis prompt yang telah dirakit ke file sementara untuk setiap sesi Codex CLI baru. Backend `claude-cli` Anthropic bawaan menerima snapshot Skills OpenClaw -dengan dua cara: katalog Skills OpenClaw ringkas di appended system prompt, dan -Plugin Claude Code sementara yang diteruskan dengan `--plugin-dir`. Plugin tersebut hanya berisi -Skills yang memenuhi syarat untuk agen/sesi itu, sehingga resolver skill native Claude Code melihat set terfilter yang sama -yang seharusnya akan diiklankan OpenClaw dalam prompt. Override env/API key Skill tetap diterapkan oleh OpenClaw ke environment proses anak untuk eksekusi tersebut. +dengan dua cara: katalog Skills OpenClaw ringkas dalam prompt sistem yang ditambahkan, dan +Plugin Claude Code sementara yang diberikan dengan `--plugin-dir`. Plugin tersebut hanya berisi +Skills yang memenuhi syarat untuk agen/sesi itu, sehingga resolver skill native Claude Code +melihat set terfilter yang sama yang seharusnya diiklankan OpenClaw dalam +prompt. Override env/kunci API Skill tetap diterapkan oleh OpenClaw ke lingkungan proses turunan untuk proses tersebut. ## Sesi -- Jika CLI mendukung sesi, atur `sessionArg` (misalnya `--session-id`) atau - `sessionArgs` (placeholder `{sessionId}`) saat ID perlu disisipkan +- Jika CLI mendukung sesi, setel `sessionArg` (misalnya `--session-id`) atau + `sessionArgs` (placeholder `{sessionId}`) ketika ID perlu disisipkan ke beberapa flag. -- Jika CLI menggunakan **subperintah resume** dengan flag yang berbeda, atur - `resumeArgs` (menggantikan `args` saat melanjutkan) dan secara opsional `resumeOutput` +- Jika CLI menggunakan **subperintah resume** dengan flag yang berbeda, setel + `resumeArgs` (menggantikan `args` saat melanjutkan) dan opsional `resumeOutput` (untuk resume non-JSON). - `sessionMode`: - `always`: selalu kirim id sesi (UUID baru jika belum ada yang tersimpan). - `existing`: hanya kirim id sesi jika sebelumnya sudah tersimpan. - `none`: jangan pernah kirim id sesi. +- Backend `claude-cli` bawaan menggunakan `liveSession: "claude-stdio"` sehingga + giliran lanjutan menggunakan kembali proses Claude aktif selama masih aktif. Jika + Gateway dimulai ulang atau proses idle berhenti, OpenClaw melanjutkan dari + id sesi Claude yang tersimpan. Catatan serialisasi: - `serialize: true` menjaga urutan eksekusi pada lane yang sama. - Sebagian besar CLI melakukan serialisasi pada satu lane penyedia. -- OpenClaw membuang penggunaan ulang sesi CLI yang tersimpan saat status autentikasi backend berubah, termasuk login ulang, rotasi token, atau perubahan kredensial profil autentikasi. +- OpenClaw menghentikan penggunaan ulang sesi CLI yang tersimpan ketika status autentikasi backend berubah, termasuk login ulang, rotasi token, atau perubahan kredensial profil autentikasi. ## Gambar (pass-through) -Jika CLI Anda menerima path gambar, atur `imageArg`: +Jika CLI Anda menerima path gambar, setel `imageArg`: ```json5 imageArg: "--image", imageMode: "repeat" ``` -OpenClaw akan menulis gambar base64 ke file sementara. Jika `imageArg` diatur, path tersebut +OpenClaw akan menulis gambar base64 ke file sementara. Jika `imageArg` disetel, path tersebut diteruskan sebagai argumen CLI. Jika `imageArg` tidak ada, OpenClaw menambahkan path file ke prompt (path injection), yang cukup untuk CLI yang otomatis memuat file lokal dari path biasa. ## Input / output -- `output: "json"` (default) mencoba mem-parsing JSON dan mengekstrak teks + id sesi. +- `output: "json"` (default) mencoba mengurai JSON dan mengekstrak teks + id sesi. - Untuk output JSON Gemini CLI, OpenClaw membaca teks balasan dari `response` dan - penggunaan dari `stats` saat `usage` tidak ada atau kosong. -- `output: "jsonl"` mem-parsing stream JSONL (misalnya Codex CLI `--json`) dan mengekstrak pesan agen akhir serta pengenal sesi + penggunaan dari `stats` ketika `usage` tidak ada atau kosong. +- `output: "jsonl"` mengurai stream JSONL (misalnya Codex CLI `--json`) dan mengekstrak pesan agen akhir beserta pengenal sesi jika ada. - `output: "text"` memperlakukan stdout sebagai respons akhir. @@ -218,9 +225,9 @@ Mode input: - `input: "arg"` (default) meneruskan prompt sebagai argumen CLI terakhir. - `input: "stdin"` mengirim prompt melalui stdin. -- Jika prompt sangat panjang dan `maxPromptArgChars` diatur, stdin digunakan. +- Jika prompt sangat panjang dan `maxPromptArgChars` disetel, stdin akan digunakan. -## Default (dimiliki Plugin) +## Default (dimiliki plugin) Plugin OpenAI bawaan juga mendaftarkan default untuk `codex-cli`: @@ -244,29 +251,29 @@ Plugin Google bawaan juga mendaftarkan default untuk `google-gemini-cli`: - `sessionMode: "existing"` - `sessionIdFields: ["session_id", "sessionId"]` -Prasyarat: Gemini CLI lokal harus terinstal dan tersedia sebagai +Prasyarat: Gemini CLI lokal harus terpasang dan tersedia sebagai `gemini` di `PATH` (`brew install gemini-cli` atau `npm install -g @google/gemini-cli`). Catatan JSON Gemini CLI: - Teks balasan dibaca dari field JSON `response`. -- Penggunaan fallback ke `stats` saat `usage` tidak ada atau kosong. +- Penggunaan akan fallback ke `stats` saat `usage` tidak ada atau kosong. - `stats.cached` dinormalisasi menjadi OpenClaw `cacheRead`. - Jika `stats.input` tidak ada, OpenClaw menurunkan token input dari `stats.input_tokens - stats.cached`. -Lakukan override hanya jika diperlukan (umumnya: path `command` absolut). +Override hanya jika diperlukan (umumnya: path `command` absolut). -## Default yang dimiliki Plugin +## Default milik Plugin -Default backend CLI kini menjadi bagian dari permukaan Plugin: +Default backend CLI sekarang menjadi bagian dari permukaan Plugin: - Plugin mendaftarkannya dengan `api.registerCliBackend(...)`. -- `id` backend menjadi prefiks penyedia dalam model ref. -- Konfigurasi pengguna di `agents.defaults.cliBackends.` tetap menimpa default Plugin. -- Pembersihan konfigurasi khusus backend tetap dimiliki Plugin melalui hook - `normalizeConfig` opsional. +- `id` backend menjadi prefiks penyedia dalam ref model. +- Konfigurasi pengguna di `agents.defaults.cliBackends.` tetap meng-override default plugin. +- Pembersihan konfigurasi khusus-backend tetap dimiliki plugin melalui hook + opsional `normalizeConfig`. Plugin yang memerlukan shim kompatibilitas prompt/pesan kecil dapat mendeklarasikan transformasi teks dua arah tanpa mengganti penyedia atau backend CLI: @@ -286,17 +293,17 @@ api.registerTextTransforms({ }); ``` -`input` menulis ulang system prompt dan prompt pengguna yang diteruskan ke CLI. `output` -menulis ulang delta asisten yang di-streaming dan teks akhir yang sudah di-parse sebelum OpenClaw menangani -marker kontrolnya sendiri dan pengiriman kanal. +`input` menulis ulang prompt sistem dan prompt pengguna yang diteruskan ke CLI. `output` +menulis ulang delta asisten yang di-stream dan teks akhir yang diurai sebelum OpenClaw menangani +marker kontrolnya sendiri dan pengiriman channel. -Untuk CLI yang mengeluarkan JSONL yang kompatibel dengan Claude Code stream-json, atur +Untuk CLI yang mengeluarkan JSONL yang kompatibel dengan Claude Code stream-json, setel `jsonlDialect: "claude-stream-json"` pada konfigurasi backend tersebut. ## Overlay bundle MCP -Backend CLI **tidak** menerima pemanggilan alat OpenClaw secara langsung, tetapi backend dapat -ikut serta dalam overlay konfigurasi MCP yang dihasilkan dengan `bundleMcp: true`. +Backend CLI **tidak** menerima panggilan alat OpenClaw secara langsung, tetapi sebuah backend dapat +ikut serta pada overlay konfigurasi MCP yang dihasilkan dengan `bundleMcp: true`. Perilaku bawaan saat ini: @@ -306,32 +313,32 @@ Perilaku bawaan saat ini: Saat bundle MCP diaktifkan, OpenClaw: -- menjalankan server MCP HTTP local loopback yang mengekspos alat gateway ke proses CLI -- mengautentikasi bridge dengan token per sesi (`OPENCLAW_MCP_TOKEN`) -- membatasi akses alat ke sesi, akun, dan konteks kanal saat ini +- menjalankan server MCP HTTP loopback yang mengekspos alat gateway ke proses CLI +- mengautentikasi jembatan dengan token per-sesi (`OPENCLAW_MCP_TOKEN`) +- membatasi akses alat ke sesi, akun, dan konteks channel saat ini - memuat server bundle-MCP yang diaktifkan untuk workspace saat ini -- menggabungkannya dengan bentuk konfigurasi/pengaturan MCP backend yang ada -- menulis ulang konfigurasi peluncuran menggunakan mode integrasi milik backend dari extension pemilik +- menggabungkannya dengan bentuk konfigurasi/pengaturan MCP backend yang sudah ada +- menulis ulang konfigurasi peluncuran menggunakan mode integrasi milik backend dari extension pemiliknya -Jika tidak ada server MCP yang diaktifkan, OpenClaw tetap menyuntikkan konfigurasi strict saat sebuah -backend ikut serta dalam bundle MCP agar eksekusi latar belakang tetap terisolasi. +Jika tidak ada server MCP yang diaktifkan, OpenClaw tetap menyuntikkan konfigurasi strict ketika sebuah +backend ikut serta dalam bundle MCP agar proses latar belakang tetap terisolasi. -## Keterbatasan +## Batasan -- **Tidak ada pemanggilan alat OpenClaw secara langsung.** OpenClaw tidak menyuntikkan pemanggilan alat ke +- **Tidak ada panggilan alat OpenClaw langsung.** OpenClaw tidak menyuntikkan panggilan alat ke protokol backend CLI. Backend hanya melihat alat gateway saat mereka ikut serta dalam `bundleMcp: true`. -- **Streaming bersifat spesifik backend.** Beberapa backend melakukan stream JSONL; yang lain menahan buffer - hingga keluar. -- **Output terstruktur** bergantung pada format JSON milik CLI. -- **Sesi Codex CLI** dilanjutkan melalui output teks (tanpa JSONL), yang kurang - terstruktur dibanding eksekusi awal `--json`. Sesi OpenClaw tetap bekerja +- **Streaming bersifat khusus-backend.** Beberapa backend melakukan stream JSONL; yang lain melakukan buffer + hingga proses keluar. +- **Output terstruktur** bergantung pada format JSON CLI. +- **Sesi Codex CLI** dilanjutkan melalui output teks (bukan JSONL), yang kurang + terstruktur dibandingkan eksekusi awal `--json`. Sesi OpenClaw tetap bekerja secara normal. ## Pemecahan masalah -- **CLI tidak ditemukan**: atur `command` ke path lengkap. +- **CLI tidak ditemukan**: setel `command` ke path lengkap. - **Nama model salah**: gunakan `modelAliases` untuk memetakan `provider/model` → model CLI. -- **Tidak ada kesinambungan sesi**: pastikan `sessionArg` diatur dan `sessionMode` bukan +- **Tidak ada kelanjutan sesi**: pastikan `sessionArg` disetel dan `sessionMode` bukan `none` (Codex CLI saat ini tidak dapat melanjutkan dengan output JSON). -- **Gambar diabaikan**: atur `imageArg` (dan verifikasi CLI mendukung path file). +- **Gambar diabaikan**: setel `imageArg` (dan verifikasi CLI mendukung path file). diff --git a/docs/id/gateway/configuration-reference.md b/docs/id/gateway/configuration-reference.md index 783272886..6245655e1 100644 --- a/docs/id/gateway/configuration-reference.md +++ b/docs/id/gateway/configuration-reference.md @@ -1,70 +1,70 @@ --- read_when: - - Anda memerlukan semantik konfigurasi atau default yang tepat di tingkat field - - Anda sedang memvalidasi blok konfigurasi channel, model, gateway, atau alat -summary: Referensi konfigurasi Gateway untuk key inti OpenClaw, default, dan tautan ke referensi subsistem khusus + - Anda memerlukan semantik konfigurasi tingkat field yang tepat atau nilai default + - Anda sedang memvalidasi blok konfigurasi channel, model, gateway, atau tool +summary: Referensi konfigurasi Gateway untuk kunci inti OpenClaw, nilai default, dan tautan ke referensi subsistem khusus title: Referensi Konfigurasi x-i18n: - generated_at: "2026-04-22T04:21:52Z" + generated_at: "2026-04-22T09:14:37Z" model: gpt-5.4 provider: openai - source_hash: 0313f47079536b93385b4e9c7680a896098ac05dce4e368d389a33e31b4649ac + source_hash: f0d6fc076f54e84bef5beefbcc42d8f172cc79792c716f76103894303e3042ac source_path: gateway/configuration-reference.md workflow: 15 --- # Referensi Konfigurasi -Referensi konfigurasi inti untuk `~/.openclaw/openclaw.json`. Untuk ikhtisar berbasis tugas, lihat [Konfigurasi](/id/gateway/configuration). +Referensi konfigurasi inti untuk `~/.openclaw/openclaw.json`. Untuk ikhtisar berbasis tugas, lihat [Configuration](/id/gateway/configuration). -Halaman ini mencakup permukaan konfigurasi utama OpenClaw dan memberikan tautan keluar ketika sebuah subsistem memiliki referensi lebih mendalamnya sendiri. Halaman ini **tidak** mencoba memasukkan setiap katalog perintah milik channel/plugin atau setiap knob memori/QMD mendalam dalam satu halaman. +Halaman ini mencakup permukaan konfigurasi utama OpenClaw dan menautkan keluar saat sebuah subsistem memiliki referensi yang lebih mendalam sendiri. Halaman ini **tidak** mencoba menyisipkan setiap katalog perintah milik channel/plugin atau setiap pengaturan memory/QMD mendalam dalam satu halaman. Sumber kebenaran kode: -- `openclaw config schema` mencetak JSON Schema live yang digunakan untuk validasi dan UI Control, dengan metadata bawaan/plugin/channel digabungkan bila tersedia -- `config.schema.lookup` mengembalikan satu node schema yang dibatasi path untuk alat drill-down -- `pnpm config:docs:check` / `pnpm config:docs:gen` memvalidasi hash baseline dokumen konfigurasi terhadap permukaan schema saat ini +- `openclaw config schema` mencetak JSON Schema live yang digunakan untuk validasi dan UI Control, dengan metadata bundled/plugin/channel digabungkan saat tersedia +- `config.schema.lookup` mengembalikan satu node schema dengan cakupan path untuk alat drill-down +- `pnpm config:docs:check` / `pnpm config:docs:gen` memvalidasi hash baseline doc konfigurasi terhadap permukaan schema saat ini Referensi mendalam khusus: -- [Referensi konfigurasi Memory](/id/reference/memory-config) untuk `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations`, dan konfigurasi dreaming di bawah `plugins.entries.memory-core.config.dreaming` -- [Perintah Slash](/id/tools/slash-commands) untuk katalog perintah bawaan + bawaan bundel saat ini +- [Referensi konfigurasi memory](/id/reference/memory-config) untuk `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations`, dan konfigurasi Dreaming di bawah `plugins.entries.memory-core.config.dreaming` +- [Slash Commands](/id/tools/slash-commands) untuk katalog perintah built-in + bundled saat ini - halaman channel/plugin pemilik untuk permukaan perintah khusus channel -Format konfigurasi adalah **JSON5** (komentar + koma di akhir diizinkan). Semua field bersifat opsional — OpenClaw menggunakan default yang aman saat dihilangkan. +Format konfigurasi adalah **JSON5** (komentar + koma di akhir diperbolehkan). Semua field bersifat opsional — OpenClaw menggunakan nilai default yang aman saat dihilangkan. --- ## Channels -Setiap channel dimulai secara otomatis saat bagian konfigurasinya ada (kecuali `enabled: false`). +Setiap channel mulai secara otomatis saat bagian konfigurasinya ada (kecuali `enabled: false`). ### Akses DM dan grup Semua channel mendukung kebijakan DM dan kebijakan grup: -| DM policy | Perilaku | +| Kebijakan DM | Perilaku | | ------------------- | ------------------------------------------------------------- | -| `pairing` (default) | Pengirim tak dikenal mendapat kode pairing sekali pakai; pemilik harus menyetujui | -| `allowlist` | Hanya pengirim dalam `allowFrom` (atau penyimpanan allow hasil pairing) | +| `pairing` (default) | Pengirim yang tidak dikenal mendapat kode pairing satu kali; pemilik harus menyetujui | +| `allowlist` | Hanya pengirim di `allowFrom` (atau penyimpanan izin pairing) | | `open` | Izinkan semua DM masuk (memerlukan `allowFrom: ["*"]`) | | `disabled` | Abaikan semua DM masuk | -| Group policy | Perilaku | +| Kebijakan grup | Perilaku | | --------------------- | ----------------------------------------------------- | -| `allowlist` (default) | Hanya grup yang cocok dengan allowlist terkonfigurasi | -| `open` | Lewati allowlist grup (gating mention tetap berlaku) | -| `disabled` | Blokir semua pesan grup/room | +| `allowlist` (default) | Hanya grup yang cocok dengan allowlist yang dikonfigurasi | +| `open` | Lewati allowlist grup (mention gating tetap berlaku) | +| `disabled` | Blokir semua pesan grup/room | -`channels.defaults.groupPolicy` menetapkan default saat `groupPolicy` provider tidak diatur. +`channels.defaults.groupPolicy` menetapkan default saat `groupPolicy` milik provider tidak diatur. Kode pairing kedaluwarsa setelah 1 jam. Permintaan pairing DM yang tertunda dibatasi hingga **3 per channel**. -Jika blok provider hilang sepenuhnya (`channels.` tidak ada), kebijakan grup runtime fallback ke `allowlist` (fail-closed) dengan peringatan saat startup. +Jika blok provider tidak ada sama sekali (`channels.` tidak ada), kebijakan grup runtime kembali ke `allowlist` (fail-closed) dengan peringatan saat startup. ### Override model channel -Gunakan `channels.modelByChannel` untuk menetapkan ID channel tertentu ke sebuah model. Nilai menerima `provider/model` atau alias model yang telah dikonfigurasi. Pemetaan channel diterapkan saat sebuah sesi belum memiliki override model (misalnya, diatur melalui `/model`). +Gunakan `channels.modelByChannel` untuk menetapkan model bagi ID channel tertentu. Nilai menerima `provider/model` atau alias model yang dikonfigurasi. Pemetaan channel diterapkan saat sesi belum memiliki override model (misalnya, disetel melalui `/model`). ```json5 { @@ -107,13 +107,13 @@ Gunakan `channels.defaults` untuk perilaku kebijakan grup dan Heartbeat bersama - `channels.defaults.groupPolicy`: kebijakan grup fallback saat `groupPolicy` tingkat provider tidak diatur. - `channels.defaults.contextVisibility`: mode visibilitas konteks tambahan default untuk semua channel. Nilai: `all` (default, sertakan semua konteks kutipan/thread/riwayat), `allowlist` (hanya sertakan konteks dari pengirim yang ada di allowlist), `allowlist_quote` (sama seperti allowlist tetapi pertahankan konteks kutipan/balasan eksplisit). Override per channel: `channels..contextVisibility`. -- `channels.defaults.heartbeat.showOk`: sertakan status channel sehat dalam output Heartbeat. -- `channels.defaults.heartbeat.showAlerts`: sertakan status menurun/error dalam output Heartbeat. -- `channels.defaults.heartbeat.useIndicator`: tampilkan output Heartbeat bergaya indikator yang ringkas. +- `channels.defaults.heartbeat.showOk`: sertakan status channel yang sehat dalam output Heartbeat. +- `channels.defaults.heartbeat.showAlerts`: sertakan status terdegradasi/error dalam output Heartbeat. +- `channels.defaults.heartbeat.useIndicator`: render output Heartbeat bergaya indikator yang ringkas. ### WhatsApp -WhatsApp berjalan melalui channel web gateway (Baileys Web). Channel ini dimulai secara otomatis saat sesi yang ditautkan ada. +WhatsApp berjalan melalui web channel gateway (Baileys Web). Channel ini mulai secara otomatis saat sesi tertaut sudah ada. ```json5 { @@ -164,9 +164,9 @@ WhatsApp berjalan melalui channel web gateway (Baileys Web). Channel ini dimulai } ``` -- Perintah keluar default ke akun `default` jika ada; jika tidak, ke ID akun pertama yang dikonfigurasi (diurutkan). -- `channels.whatsapp.defaultAccount` opsional mengoverride pemilihan akun default fallback itu saat cocok dengan ID akun yang dikonfigurasi. -- Direktori auth Baileys akun tunggal lama dimigrasikan oleh `openclaw doctor` ke `whatsapp/default`. +- Perintah outbound menggunakan akun `default` secara default jika ada; jika tidak, gunakan ID akun pertama yang dikonfigurasi (diurutkan). +- `channels.whatsapp.defaultAccount` opsional menimpa pemilihan akun default fallback tersebut saat cocok dengan ID akun yang dikonfigurasi. +- Direktori autentikasi Baileys multi-akun lama dimigrasikan oleh `openclaw doctor` ke `whatsapp/default`. - Override per akun: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -225,13 +225,13 @@ WhatsApp berjalan melalui channel web gateway (Baileys Web). Channel ini dimulai } ``` -- Bot token: `channels.telegram.botToken` atau `channels.telegram.tokenFile` (hanya file biasa; symlink ditolak), dengan `TELEGRAM_BOT_TOKEN` sebagai fallback untuk akun default. -- `channels.telegram.defaultAccount` opsional mengoverride pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi. -- Dalam penyiapan multi-akun (2+ ID akun), atur default eksplisit (`channels.telegram.defaultAccount` atau `channels.telegram.accounts.default`) untuk menghindari fallback routing; `openclaw doctor` memperingatkan saat ini hilang atau tidak valid. -- `configWrites: false` memblokir penulisan konfigurasi yang dipicu Telegram (migrasi ID supergroup, `/config set|unset`). +- Token bot: `channels.telegram.botToken` atau `channels.telegram.tokenFile` (hanya file biasa; symlink ditolak), dengan `TELEGRAM_BOT_TOKEN` sebagai fallback untuk akun default. +- `channels.telegram.defaultAccount` opsional menimpa pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi. +- Dalam penyiapan multi-akun (2+ ID akun), tetapkan default eksplisit (`channels.telegram.defaultAccount` atau `channels.telegram.accounts.default`) untuk menghindari fallback routing; `openclaw doctor` memperingatkan saat ini hilang atau tidak valid. +- `configWrites: false` memblokir penulisan konfigurasi yang dimulai Telegram (migrasi ID supergroup, `/config set|unset`). - Entri `bindings[]` tingkat atas dengan `type: "acp"` mengonfigurasi binding ACP persisten untuk topik forum (gunakan `chatId:topic:topicId` kanonis di `match.peer.id`). Semantik field dibagikan di [ACP Agents](/id/tools/acp-agents#channel-specific-settings). - Pratinjau stream Telegram menggunakan `sendMessage` + `editMessageText` (berfungsi di chat langsung dan grup). -- Kebijakan retry: lihat [Kebijakan retry](/id/concepts/retry). +- Kebijakan retry: lihat [Retry policy](/id/concepts/retry). ### Discord @@ -334,35 +334,35 @@ WhatsApp berjalan melalui channel web gateway (Baileys Web). Channel ini dimulai ``` - Token: `channels.discord.token`, dengan `DISCORD_BOT_TOKEN` sebagai fallback untuk akun default. -- Panggilan keluar langsung yang menyediakan `token` Discord eksplisit menggunakan token tersebut untuk panggilan; pengaturan retry/kebijakan akun tetap berasal dari akun yang dipilih dalam snapshot runtime aktif. -- `channels.discord.defaultAccount` opsional mengoverride pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi. +- Panggilan outbound langsung yang memberikan `token` Discord eksplisit menggunakan token tersebut untuk panggilan; pengaturan retry/kebijakan akun tetap berasal dari akun yang dipilih dalam snapshot runtime aktif. +- `channels.discord.defaultAccount` opsional menimpa pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi. - Gunakan `user:` (DM) atau `channel:` (channel guild) untuk target pengiriman; ID numerik tanpa awalan ditolak. -- Slug guild menggunakan huruf kecil dengan spasi diganti `-`; key channel menggunakan nama yang sudah di-slug (tanpa `#`). Gunakan ID guild jika memungkinkan. -- Pesan yang ditulis bot diabaikan secara default. `allowBots: true` mengaktifkannya; gunakan `allowBots: "mentions"` untuk hanya menerima pesan bot yang menyebut bot (pesan bot sendiri tetap difilter). -- `channels.discord.guilds..ignoreOtherMentions` (dan override channel) membuang pesan yang menyebut pengguna atau role lain tetapi tidak menyebut bot (tidak termasuk @everyone/@here). -- `maxLinesPerMessage` (default 17) memecah pesan tinggi bahkan saat panjangnya di bawah 2000 karakter. -- `channels.discord.threadBindings` mengontrol perutean terikat thread Discord: - - `enabled`: override Discord untuk fitur sesi terikat thread (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, dan pengiriman/perutean terikat) +- Slug guild menggunakan huruf kecil dengan spasi diganti `-`; kunci channel menggunakan nama yang sudah di-slug (tanpa `#`). Sebaiknya gunakan ID guild. +- Pesan yang dibuat bot diabaikan secara default. `allowBots: true` mengaktifkannya; gunakan `allowBots: "mentions"` untuk hanya menerima pesan bot yang menyebut bot (pesan sendiri tetap difilter). +- `channels.discord.guilds..ignoreOtherMentions` (dan override tingkat channel) membuang pesan yang menyebut pengguna atau role lain tetapi tidak menyebut bot (tidak termasuk @everyone/@here). +- `maxLinesPerMessage` (default 17) memecah pesan yang tinggi bahkan saat di bawah 2000 karakter. +- `channels.discord.threadBindings` mengontrol routing terikat thread Discord: + - `enabled`: override Discord untuk fitur sesi terikat thread (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, dan pengiriman/routing terikat) - `idleHours`: override Discord untuk auto-unfocus karena tidak aktif dalam jam (`0` menonaktifkan) - `maxAgeHours`: override Discord untuk usia maksimum keras dalam jam (`0` menonaktifkan) - `spawnSubagentSessions`: sakelar opt-in untuk pembuatan/pengikatan thread otomatis `sessions_spawn({ thread: true })` - Entri `bindings[]` tingkat atas dengan `type: "acp"` mengonfigurasi binding ACP persisten untuk channel dan thread (gunakan id channel/thread di `match.peer.id`). Semantik field dibagikan di [ACP Agents](/id/tools/acp-agents#channel-specific-settings). -- `channels.discord.ui.components.accentColor` menetapkan warna aksen untuk container Discord components v2. +- `channels.discord.ui.components.accentColor` menetapkan warna aksen untuk container komponen Discord v2. - `channels.discord.voice` mengaktifkan percakapan channel suara Discord dan override auto-join + TTS opsional. -- `channels.discord.voice.daveEncryption` dan `channels.discord.voice.decryptionFailureTolerance` diteruskan ke opsi DAVE `@discordjs/voice` (`true` dan `24` secara default). +- `channels.discord.voice.daveEncryption` dan `channels.discord.voice.decryptionFailureTolerance` diteruskan ke opsi DAVE `@discordjs/voice` (default `true` dan `24`). - OpenClaw juga mencoba pemulihan penerimaan suara dengan keluar/bergabung ulang ke sesi suara setelah kegagalan dekripsi berulang. -- `channels.discord.streaming` adalah key mode stream kanonis. Nilai lama `streamMode` dan boolean `streaming` dimigrasikan secara otomatis. -- `channels.discord.autoPresence` memetakan ketersediaan runtime ke presence bot (sehat => online, menurun => idle, habis => dnd) dan memungkinkan override teks status opsional. +- `channels.discord.streaming` adalah kunci mode stream kanonis. Nilai lama `streamMode` dan `streaming` boolean dimigrasikan secara otomatis. +- `channels.discord.autoPresence` memetakan ketersediaan runtime ke presence bot (healthy => online, degraded => idle, exhausted => dnd) dan mengizinkan override teks status opsional. - `channels.discord.dangerouslyAllowNameMatching` mengaktifkan kembali pencocokan nama/tag yang dapat berubah (mode kompatibilitas break-glass). - `channels.discord.execApprovals`: pengiriman persetujuan exec native Discord dan otorisasi approver. - `enabled`: `true`, `false`, atau `"auto"` (default). Dalam mode auto, persetujuan exec aktif saat approver dapat di-resolve dari `approvers` atau `commands.ownerAllowFrom`. - - `approvers`: ID pengguna Discord yang diizinkan menyetujui permintaan exec. Fallback ke `commands.ownerAllowFrom` jika dihilangkan. - - `agentFilter`: allowlist ID agen opsional. Hilangkan untuk meneruskan persetujuan bagi semua agen. - - `sessionFilter`: pola key sesi opsional (substring atau regex). - - `target`: tempat mengirim prompt persetujuan. `"dm"` (default) mengirim ke DM approver, `"channel"` mengirim ke channel asal, `"both"` mengirim ke keduanya. Saat target menyertakan `"channel"`, tombol hanya dapat digunakan oleh approver yang berhasil di-resolve. + - `approvers`: ID pengguna Discord yang diizinkan menyetujui permintaan exec. Menggunakan fallback ke `commands.ownerAllowFrom` jika tidak diatur. + - `agentFilter`: allowlist ID agent opsional. Hilangkan untuk meneruskan persetujuan bagi semua agent. + - `sessionFilter`: pola kunci sesi opsional (substring atau regex). + - `target`: tempat mengirim prompt persetujuan. `"dm"` (default) mengirim ke DM approver, `"channel"` mengirim ke channel asal, `"both"` mengirim ke keduanya. Saat target mencakup `"channel"`, tombol hanya dapat digunakan oleh approver yang berhasil di-resolve. - `cleanupAfterResolve`: saat `true`, menghapus DM persetujuan setelah disetujui, ditolak, atau timeout. -**Mode notifikasi reaksi:** `off` (tidak ada), `own` (pesan bot, default), `all` (semua pesan), `allowlist` (dari `guilds..users` pada semua pesan). +**Mode notifikasi reaction:** `off` (tidak ada), `own` (pesan bot, default), `all` (semua pesan), `allowlist` (dari `guilds..users` pada semua pesan). ### Google Chat @@ -449,7 +449,7 @@ WhatsApp berjalan melalui channel web gateway (Baileys Web). Channel ini dimulai chunkMode: "length", streaming: { mode: "partial", // off | partial | block | progress - nativeTransport: true, // gunakan API streaming native Slack saat mode=partial + nativeTransport: true, // use Slack native streaming API when mode=partial }, mediaMaxMb: 20, execApprovals: { @@ -466,37 +466,32 @@ WhatsApp berjalan melalui channel web gateway (Baileys Web). Channel ini dimulai - **Socket mode** memerlukan `botToken` dan `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` untuk fallback env akun default). - **HTTP mode** memerlukan `botToken` plus `signingSecret` (di root atau per akun). -- `botToken`, `appToken`, `signingSecret`, dan `userToken` menerima string - plaintext atau objek SecretRef. -- Snapshot akun Slack menampilkan field sumber/status per kredensial seperti - `botTokenSource`, `botTokenStatus`, `appTokenStatus`, dan, dalam mode HTTP, - `signingSecretStatus`. `configured_unavailable` berarti akun tersebut - dikonfigurasi melalui SecretRef tetapi jalur perintah/runtime saat ini tidak dapat - me-resolve nilai secret. -- `configWrites: false` memblokir penulisan konfigurasi yang dipicu Slack. -- `channels.slack.defaultAccount` opsional mengoverride pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi. -- `channels.slack.streaming.mode` adalah key mode stream Slack kanonis. `channels.slack.streaming.nativeTransport` mengontrol transport streaming native Slack. Nilai lama `streamMode`, boolean `streaming`, dan `nativeStreaming` dimigrasikan secara otomatis. +- `botToken`, `appToken`, `signingSecret`, dan `userToken` menerima string plaintext atau objek SecretRef. +- Snapshot akun Slack mengekspos field sumber/status per kredensial seperti `botTokenSource`, `botTokenStatus`, `appTokenStatus`, dan, dalam mode HTTP, `signingSecretStatus`. `configured_unavailable` berarti akun dikonfigurasi melalui SecretRef tetapi path perintah/runtime saat ini tidak dapat me-resolve nilai secret. +- `configWrites: false` memblokir penulisan konfigurasi yang dimulai Slack. +- `channels.slack.defaultAccount` opsional menimpa pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi. +- `channels.slack.streaming.mode` adalah kunci mode stream Slack kanonis. `channels.slack.streaming.nativeTransport` mengontrol transport streaming native Slack. Nilai lama `streamMode`, `streaming` boolean, dan `nativeStreaming` dimigrasikan secara otomatis. - Gunakan `user:` (DM) atau `channel:` untuk target pengiriman. -**Mode notifikasi reaksi:** `off`, `own` (default), `all`, `allowlist` (dari `reactionAllowlist`). +**Mode notifikasi reaction:** `off`, `own` (default), `all`, `allowlist` (dari `reactionAllowlist`). -**Isolasi sesi thread:** `thread.historyScope` per thread (default) atau dibagikan di seluruh channel. `thread.inheritParent` menyalin transkrip channel induk ke thread baru. +**Isolasi sesi thread:** `thread.historyScope` per-thread (default) atau dibagikan di seluruh channel. `thread.inheritParent` menyalin transkrip channel induk ke thread baru. -- Streaming native Slack plus status thread gaya asisten Slack "is typing..." memerlukan target thread balasan. DM tingkat atas secara default tetap di luar thread, jadi menggunakan `typingReaction` atau pengiriman normal alih-alih pratinjau bergaya thread. -- `typingReaction` menambahkan reaksi sementara ke pesan Slack masuk saat balasan sedang berjalan, lalu menghapusnya setelah selesai. Gunakan shortcode emoji Slack seperti `"hourglass_flowing_sand"`. +- Streaming native Slack ditambah status thread bergaya asisten Slack "is typing..." memerlukan target thread balasan. DM tingkat atas tetap off-thread secara default, sehingga menggunakan `typingReaction` atau pengiriman normal alih-alih pratinjau bergaya thread. +- `typingReaction` menambahkan reaction sementara ke pesan Slack masuk saat balasan sedang berjalan, lalu menghapusnya setelah selesai. Gunakan shortcode emoji Slack seperti `"hourglass_flowing_sand"`. - `channels.slack.execApprovals`: pengiriman persetujuan exec native Slack dan otorisasi approver. Schema sama seperti Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ID pengguna Slack), `agentFilter`, `sessionFilter`, dan `target` (`"dm"`, `"channel"`, atau `"both"`). -| Action group | Default | Catatan | -| ------------ | ------- | ---------------------- | -| reactions | enabled | React + daftar reaksi | -| messages | enabled | Baca/kirim/edit/hapus | -| pins | enabled | Sematkan/lepas/list | -| memberInfo | enabled | Info anggota | -| emojiList | enabled | Daftar emoji kustom | +| Grup action | Default | Catatan | +| ----------- | ------- | --------------------- | +| reactions | enabled | React + daftar reaction | +| messages | enabled | Baca/kirim/edit/hapus | +| pins | enabled | Pin/unpin/daftar | +| memberInfo | enabled | Info anggota | +| emojiList | enabled | Daftar emoji kustom | ### Mattermost -Mattermost dikirim sebagai plugin: `openclaw plugins install @openclaw/mattermost`. +Mattermost dikirim sebagai Plugin: `openclaw plugins install @openclaw/mattermost`. ```json5 { @@ -526,23 +521,19 @@ Mattermost dikirim sebagai plugin: `openclaw plugins install @openclaw/mattermos } ``` -Mode chat: `oncall` (merespons saat @-mention, default), `onmessage` (setiap pesan), `onchar` (pesan yang diawali prefix pemicu). +Mode chat: `oncall` (merespons pada @-mention, default), `onmessage` (setiap pesan), `onchar` (pesan yang dimulai dengan prefiks pemicu). Saat perintah native Mattermost diaktifkan: - `commands.callbackPath` harus berupa path (misalnya `/api/channels/mattermost/command`), bukan URL lengkap. -- `commands.callbackUrl` harus me-resolve ke endpoint gateway OpenClaw dan dapat dijangkau dari server Mattermost. -- Callback slash native diautentikasi dengan token per perintah yang dikembalikan - oleh Mattermost saat pendaftaran slash command. Jika pendaftaran gagal atau tidak - ada perintah yang diaktifkan, OpenClaw menolak callback dengan - `Unauthorized: invalid command token.` -- Untuk host callback private/tailnet/internal, Mattermost mungkin memerlukan - `ServiceSettings.AllowedUntrustedInternalConnections` untuk menyertakan host/domain callback. +- `commands.callbackUrl` harus di-resolve ke endpoint Gateway OpenClaw dan dapat dijangkau dari server Mattermost. +- Callback slash native diautentikasi dengan token per-perintah yang dikembalikan oleh Mattermost selama pendaftaran slash command. Jika pendaftaran gagal atau tidak ada perintah yang diaktifkan, OpenClaw menolak callback dengan `Unauthorized: invalid command token.` +- Untuk host callback private/tailnet/internal, Mattermost mungkin memerlukan `ServiceSettings.AllowedUntrustedInternalConnections` agar menyertakan host/domain callback. Gunakan nilai host/domain, bukan URL lengkap. -- `channels.mattermost.configWrites`: izinkan atau tolak penulisan konfigurasi yang dipicu Mattermost. -- `channels.mattermost.requireMention`: mengharuskan `@mention` sebelum membalas di channel. -- `channels.mattermost.groups..requireMention`: override gating mention per channel (`"*"` untuk default). -- `channels.mattermost.defaultAccount` opsional mengoverride pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi. +- `channels.mattermost.configWrites`: izinkan atau tolak penulisan konfigurasi yang dimulai Mattermost. +- `channels.mattermost.requireMention`: memerlukan `@mention` sebelum membalas di channel. +- `channels.mattermost.groups..requireMention`: override mention-gating per channel (`"*"` untuk default). +- `channels.mattermost.defaultAccount` opsional menimpa pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi. ### Signal @@ -563,11 +554,11 @@ Saat perintah native Mattermost diaktifkan: } ``` -**Mode notifikasi reaksi:** `off`, `own` (default), `all`, `allowlist` (dari `reactionAllowlist`). +**Mode notifikasi reaction:** `off`, `own` (default), `all`, `allowlist` (dari `reactionAllowlist`). -- `channels.signal.account`: sematkan startup channel ke identitas akun Signal tertentu. -- `channels.signal.configWrites`: izinkan atau tolak penulisan konfigurasi yang dipicu Signal. -- `channels.signal.defaultAccount` opsional mengoverride pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi. +- `channels.signal.account`: tetapkan startup channel ke identitas akun Signal tertentu. +- `channels.signal.configWrites`: izinkan atau tolak penulisan konfigurasi yang dimulai Signal. +- `channels.signal.defaultAccount` opsional menimpa pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi. ### BlueBubbles @@ -579,21 +570,21 @@ BlueBubbles adalah jalur iMessage yang direkomendasikan (didukung Plugin, dikonf bluebubbles: { enabled: true, dmPolicy: "pairing", - // serverUrl, password, webhookPath, kontrol grup, dan tindakan lanjutan: + // serverUrl, password, webhookPath, kontrol grup, dan action lanjutan: // lihat /channels/bluebubbles }, }, } ``` -- Path key inti yang dicakup di sini: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. -- `channels.bluebubbles.defaultAccount` opsional mengoverride pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi. +- Path kunci inti yang dicakup di sini: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. +- `channels.bluebubbles.defaultAccount` opsional menimpa pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi. - Entri `bindings[]` tingkat atas dengan `type: "acp"` dapat mengikat percakapan BlueBubbles ke sesi ACP persisten. Gunakan handle atau string target BlueBubbles (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) di `match.peer.id`. Semantik field bersama: [ACP Agents](/id/tools/acp-agents#channel-specific-settings). -- Konfigurasi channel BlueBubbles lengkap didokumentasikan di [BlueBubbles](/id/channels/bluebubbles). +- Konfigurasi lengkap channel BlueBubbles didokumentasikan di [BlueBubbles](/id/channels/bluebubbles). ### iMessage -OpenClaw menjalankan `imsg rpc` (`JSON-RPC` melalui stdio). Tidak memerlukan daemon atau port. +OpenClaw menjalankan `imsg rpc` (JSON-RPC melalui stdio). Tidak memerlukan daemon atau port. ```json5 { @@ -617,14 +608,14 @@ OpenClaw menjalankan `imsg rpc` (`JSON-RPC` melalui stdio). Tidak memerlukan dae } ``` -- `channels.imessage.defaultAccount` opsional mengoverride pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi. +- `channels.imessage.defaultAccount` opsional menimpa pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi. - Memerlukan Full Disk Access ke DB Messages. - Sebaiknya gunakan target `chat_id:`. Gunakan `imsg chats --limit 20` untuk mencantumkan chat. -- `cliPath` dapat menunjuk ke wrapper SSH; atur `remoteHost` (`host` atau `user@host`) untuk pengambilan lampiran SCP. +- `cliPath` dapat mengarah ke wrapper SSH; tetapkan `remoteHost` (`host` atau `user@host`) untuk pengambilan lampiran SCP. - `attachmentRoots` dan `remoteAttachmentRoots` membatasi path lampiran masuk (default: `/Users/*/Library/Messages/Attachments`). - SCP menggunakan pemeriksaan host-key yang ketat, jadi pastikan host key relay sudah ada di `~/.ssh/known_hosts`. -- `channels.imessage.configWrites`: izinkan atau tolak penulisan konfigurasi yang dipicu iMessage. +- `channels.imessage.configWrites`: izinkan atau tolak penulisan konfigurasi yang dimulai iMessage. - Entri `bindings[]` tingkat atas dengan `type: "acp"` dapat mengikat percakapan iMessage ke sesi ACP persisten. Gunakan handle yang dinormalisasi atau target chat eksplisit (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) di `match.peer.id`. Semantik field bersama: [ACP Agents](/id/tools/acp-agents#channel-specific-settings). @@ -669,19 +660,19 @@ Matrix didukung Plugin dan dikonfigurasi di bawah `channels.matrix`. ``` - Autentikasi token menggunakan `accessToken`; autentikasi kata sandi menggunakan `userId` + `password`. -- `channels.matrix.proxy` merutekan lalu lintas HTTP Matrix melalui proxy HTTP(S) eksplisit. Akun bernama dapat mengoverridenya dengan `channels.matrix.accounts..proxy`. -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` mengizinkan homeserver privat/internal. `proxy` dan opt-in jaringan ini adalah kontrol yang independen. +- `channels.matrix.proxy` merutekan lalu lintas HTTP Matrix melalui proxy HTTP(S) eksplisit. Akun bernama dapat menimpanya dengan `channels.matrix.accounts..proxy`. +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` mengizinkan homeserver private/internal. `proxy` dan opt-in jaringan ini adalah kontrol yang independen. - `channels.matrix.defaultAccount` memilih akun yang diprioritaskan dalam penyiapan multi-akun. -- `channels.matrix.autoJoin` default-nya `off`, sehingga room undangan dan undangan bergaya DM baru diabaikan sampai Anda mengatur `autoJoin: "allowlist"` dengan `autoJoinAllowlist` atau `autoJoin: "always"`. +- `channels.matrix.autoJoin` default-nya `off`, sehingga room undangan dan undangan bergaya DM baru diabaikan sampai Anda menetapkan `autoJoin: "allowlist"` dengan `autoJoinAllowlist` atau `autoJoin: "always"`. - `channels.matrix.execApprovals`: pengiriman persetujuan exec native Matrix dan otorisasi approver. - `enabled`: `true`, `false`, atau `"auto"` (default). Dalam mode auto, persetujuan exec aktif saat approver dapat di-resolve dari `approvers` atau `commands.ownerAllowFrom`. - `approvers`: ID pengguna Matrix (mis. `@owner:example.org`) yang diizinkan menyetujui permintaan exec. - - `agentFilter`: allowlist ID agen opsional. Hilangkan untuk meneruskan persetujuan bagi semua agen. - - `sessionFilter`: pola key sesi opsional (substring atau regex). + - `agentFilter`: allowlist ID agent opsional. Hilangkan untuk meneruskan persetujuan bagi semua agent. + - `sessionFilter`: pola kunci sesi opsional (substring atau regex). - `target`: tempat mengirim prompt persetujuan. `"dm"` (default), `"channel"` (room asal), atau `"both"`. - Override per akun: `channels.matrix.accounts..execApprovals`. - `channels.matrix.dm.sessionScope` mengontrol cara DM Matrix dikelompokkan ke dalam sesi: `per-user` (default) berbagi berdasarkan peer yang dirutekan, sedangkan `per-room` mengisolasi setiap room DM. -- Probe status Matrix dan lookup direktori live menggunakan kebijakan proxy yang sama dengan lalu lintas runtime. +- Probe status Matrix dan pencarian direktori live menggunakan kebijakan proxy yang sama seperti lalu lintas runtime. - Konfigurasi Matrix lengkap, aturan penargetan, dan contoh penyiapan didokumentasikan di [Matrix](/id/channels/matrix). ### Microsoft Teams @@ -694,15 +685,15 @@ Microsoft Teams didukung Plugin dan dikonfigurasi di bawah `channels.msteams`. msteams: { enabled: true, configWrites: true, - // appId, appPassword, tenantId, webhook, kebijakan tim/channel: + // appId, appPassword, tenantId, webhook, kebijakan team/channel: // lihat /channels/msteams }, }, } ``` -- Path key inti yang dicakup di sini: `channels.msteams`, `channels.msteams.configWrites`. -- Konfigurasi Teams lengkap (kredensial, webhook, kebijakan DM/grup, override per tim/per channel) didokumentasikan di [Microsoft Teams](/id/channels/msteams). +- Path kunci inti yang dicakup di sini: `channels.msteams`, `channels.msteams.configWrites`. +- Konfigurasi Teams lengkap (kredensial, webhook, kebijakan DM/grup, override per-team/per-channel) didokumentasikan di [Microsoft Teams](/id/channels/msteams). ### IRC @@ -727,11 +718,11 @@ IRC didukung Plugin dan dikonfigurasi di bawah `channels.irc`. } ``` -- Path key inti yang dicakup di sini: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. -- `channels.irc.defaultAccount` opsional mengoverride pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi. -- Konfigurasi channel IRC lengkap (host/port/TLS/channels/allowlist/gating mention) didokumentasikan di [IRC](/id/channels/irc). +- Path kunci inti yang dicakup di sini: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. +- `channels.irc.defaultAccount` opsional menimpa pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi. +- Konfigurasi channel IRC lengkap (host/port/TLS/channels/allowlist/mention gating) didokumentasikan di [IRC](/id/channels/irc). -### Multi-akun (semua channel) +### Multi-account (semua channel) Jalankan beberapa akun per channel (masing-masing dengan `accountId` sendiri): @@ -741,11 +732,11 @@ Jalankan beberapa akun per channel (masing-masing dengan `accountId` sendiri): telegram: { accounts: { default: { - name: "Bot utama", + name: "Primary bot", botToken: "123456:ABC...", }, alerts: { - name: "Bot alert", + name: "Alerts bot", botToken: "987654:XYZ...", }, }, @@ -754,28 +745,28 @@ Jalankan beberapa akun per channel (masing-masing dengan `accountId` sendiri): } ``` -- `default` digunakan saat `accountId` dihilangkan (CLI + perutean). +- `default` digunakan saat `accountId` dihilangkan (CLI + routing). - Token env hanya berlaku untuk akun **default**. -- Pengaturan channel dasar berlaku untuk semua akun kecuali dioverride per akun. -- Gunakan `bindings[].match.accountId` untuk merutekan setiap akun ke agen yang berbeda. -- Jika Anda menambahkan akun non-default melalui `openclaw channels add` (atau onboarding channel) saat masih menggunakan konfigurasi channel tingkat atas akun tunggal, OpenClaw terlebih dahulu mempromosikan nilai akun tunggal tingkat atas yang dicakup akun ke dalam peta akun channel agar akun asli tetap berfungsi. Sebagian besar channel memindahkannya ke `channels..accounts.default`; Matrix dapat mempertahankan target bernama/default yang cocok yang sudah ada. -- Binding khusus channel yang sudah ada (tanpa `accountId`) tetap cocok dengan akun default; binding yang dicakup akun tetap opsional. -- `openclaw doctor --fix` juga memperbaiki bentuk campuran dengan memindahkan nilai akun tunggal tingkat atas yang dicakup akun ke akun hasil promosi yang dipilih untuk channel tersebut. Sebagian besar channel menggunakan `accounts.default`; Matrix dapat mempertahankan target bernama/default yang cocok yang sudah ada. +- Pengaturan channel dasar berlaku untuk semua akun kecuali ditimpa per akun. +- Gunakan `bindings[].match.accountId` untuk merutekan setiap akun ke agent yang berbeda. +- Jika Anda menambahkan akun non-default melalui `openclaw channels add` (atau onboarding channel) saat masih berada pada konfigurasi channel tingkat atas single-account, OpenClaw terlebih dahulu mempromosikan nilai single-account tingkat atas yang bercakupan akun ke dalam map akun channel agar akun asli tetap berfungsi. Sebagian besar channel memindahkannya ke `channels..accounts.default`; Matrix dapat mempertahankan target bernama/default yang sudah ada dan cocok. +- Binding khusus channel yang sudah ada (tanpa `accountId`) tetap cocok dengan akun default; binding bercakupan akun tetap opsional. +- `openclaw doctor --fix` juga memperbaiki bentuk campuran dengan memindahkan nilai single-account tingkat atas bercakupan akun ke akun hasil promosi yang dipilih untuk channel tersebut. Sebagian besar channel menggunakan `accounts.default`; Matrix dapat mempertahankan target bernama/default yang sudah ada dan cocok. ### Channel Plugin lainnya Banyak channel Plugin dikonfigurasi sebagai `channels.` dan didokumentasikan di halaman channel khusus masing-masing (misalnya Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat, dan Twitch). Lihat indeks channel lengkap: [Channels](/id/channels). -### Gating mention chat grup +### Mention gating chat grup Pesan grup default-nya **memerlukan mention** (mention metadata atau pola regex aman). Berlaku untuk chat grup WhatsApp, Telegram, Discord, Google Chat, dan iMessage. **Jenis mention:** -- **Metadata mentions**: @-mention native platform. Diabaikan dalam mode self-chat WhatsApp. -- **Text patterns**: pola regex aman dalam `agents.list[].groupChat.mentionPatterns`. Pola tidak valid dan pengulangan bertingkat yang tidak aman diabaikan. -- Gating mention hanya diberlakukan saat deteksi memungkinkan (mention native atau setidaknya satu pola). +- **Mention metadata**: @-mention native platform. Diabaikan dalam mode self-chat WhatsApp. +- **Pola teks**: Pola regex aman dalam `agents.list[].groupChat.mentionPatterns`. Pola tidak valid dan pengulangan bertingkat yang tidak aman diabaikan. +- Mention gating hanya diterapkan saat deteksi dimungkinkan (mention native atau setidaknya satu pola). ```json5 { @@ -788,7 +779,7 @@ Pesan grup default-nya **memerlukan mention** (mention metadata atau pola regex } ``` -`messages.groupChat.historyLimit` menetapkan default global. Channel dapat mengoverridenya dengan `channels..historyLimit` (atau per akun). Atur `0` untuk menonaktifkan. +`messages.groupChat.historyLimit` menetapkan default global. Channels dapat menimpanya dengan `channels..historyLimit` (atau per akun). Tetapkan `0` untuk menonaktifkan. #### Batas riwayat DM @@ -805,7 +796,7 @@ Pesan grup default-nya **memerlukan mention** (mention metadata atau pola regex } ``` -Resolusi: override per-DM → default provider → tidak ada batas (semua dipertahankan). +Resolusi: override per-DM → default provider → tanpa batas (semua dipertahankan). Didukung: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. @@ -839,14 +830,14 @@ Sertakan nomor Anda sendiri dalam `allowFrom` untuk mengaktifkan mode self-chat commands: { native: "auto", // daftarkan perintah native saat didukung nativeSkills: "auto", // daftarkan perintah Skills native saat didukung - text: true, // parse /commands dalam pesan chat + text: true, // parse /commands di pesan chat bash: false, // izinkan ! (alias: /bash) bashForegroundMs: 2000, config: false, // izinkan /config mcp: false, // izinkan /mcp plugins: false, // izinkan /plugins debug: false, // izinkan /debug - restart: true, // izinkan /restart + alat restart gateway + restart: true, // izinkan /restart + tool restart gateway ownerAllowFrom: ["discord:123456789012345678"], ownerDisplay: "raw", // raw | hash ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", @@ -861,38 +852,38 @@ Sertakan nomor Anda sendiri dalam `allowFrom` untuk mengaktifkan mode self-chat -- Blok ini mengonfigurasi permukaan perintah. Untuk katalog perintah bawaan + bawaan bundel saat ini, lihat [Perintah Slash](/id/tools/slash-commands). -- Halaman ini adalah **referensi key konfigurasi**, bukan katalog perintah lengkap. Perintah milik channel/plugin seperti QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone`, dan Talk `/voice` didokumentasikan di halaman channel/plugin masing-masing serta [Perintah Slash](/id/tools/slash-commands). +- Blok ini mengonfigurasi permukaan perintah. Untuk katalog perintah built-in + bundled saat ini, lihat [Slash Commands](/id/tools/slash-commands). +- Halaman ini adalah **referensi kunci konfigurasi**, bukan katalog perintah lengkap. Perintah milik channel/plugin seperti QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone`, dan Talk `/voice` didokumentasikan di halaman channel/plugin masing-masing serta [Slash Commands](/id/tools/slash-commands). - Perintah teks harus berupa pesan **mandiri** dengan awalan `/`. -- `native: "auto"` mengaktifkan perintah native untuk Discord/Telegram, membiarkan Slack nonaktif. -- `nativeSkills: "auto"` mengaktifkan perintah Skills native untuk Discord/Telegram, membiarkan Slack nonaktif. +- `native: "auto"` menyalakan perintah native untuk Discord/Telegram, dan membiarkan Slack nonaktif. +- `nativeSkills: "auto"` menyalakan perintah Skills native untuk Discord/Telegram, dan membiarkan Slack nonaktif. - Override per channel: `channels.discord.commands.native` (bool atau `"auto"`). `false` menghapus perintah yang sebelumnya terdaftar. -- Override pendaftaran Skills native per channel dengan `channels..commands.nativeSkills`. +- Override pendaftaran skill native per channel dengan `channels..commands.nativeSkills`. - `channels.telegram.customCommands` menambahkan entri menu bot Telegram tambahan. - `bash: true` mengaktifkan `! ` untuk shell host. Memerlukan `tools.elevated.enabled` dan pengirim ada di `tools.elevated.allowFrom.`. -- `config: true` mengaktifkan `/config` (membaca/menulis `openclaw.json`). Untuk klien gateway `chat.send`, penulisan persisten `/config set|unset` juga memerlukan `operator.admin`; `/config show` yang hanya-baca tetap tersedia untuk klien operator dengan cakupan tulis normal. +- `config: true` mengaktifkan `/config` (membaca/menulis `openclaw.json`). Untuk klien gateway `chat.send`, penulisan persisten `/config set|unset` juga memerlukan `operator.admin`; `/config show` baca-saja tetap tersedia untuk klien operator biasa dengan cakupan tulis. - `mcp: true` mengaktifkan `/mcp` untuk konfigurasi server MCP yang dikelola OpenClaw di bawah `mcp.servers`. -- `plugins: true` mengaktifkan `/plugins` untuk penemuan, instalasi, dan kontrol aktif/nonaktif Plugin. +- `plugins: true` mengaktifkan `/plugins` untuk penemuan Plugin, instalasi, dan kontrol aktif/nonaktif. - `channels..configWrites` mengatur mutasi konfigurasi per channel (default: true). - Untuk channel multi-akun, `channels..accounts..configWrites` juga mengatur penulisan yang menargetkan akun tersebut (misalnya `/allowlist --config --account ` atau `/config set channels..accounts....`). -- `restart: false` menonaktifkan `/restart` dan tindakan alat restart gateway. Default: `true`. -- `ownerAllowFrom` adalah allowlist pemilik eksplisit untuk perintah/alat khusus pemilik. Ini terpisah dari `allowFrom`. -- `ownerDisplay: "hash"` melakukan hash pada id pemilik di system prompt. Atur `ownerDisplaySecret` untuk mengontrol hashing. -- `allowFrom` bersifat per-provider. Saat diatur, itu adalah **satu-satunya** sumber otorisasi (allowlist/pairing channel dan `useAccessGroups` diabaikan). -- `useAccessGroups: false` memungkinkan perintah melewati kebijakan grup akses saat `allowFrom` tidak diatur. -- Peta dokumen perintah: - - katalog bawaan + bawaan bundel: [Perintah Slash](/id/tools/slash-commands) +- `restart: false` menonaktifkan `/restart` dan action tool restart gateway. Default: `true`. +- `ownerAllowFrom` adalah allowlist pemilik eksplisit untuk perintah/tool khusus pemilik. Ini terpisah dari `allowFrom`. +- `ownerDisplay: "hash"` melakukan hash pada ID pemilik dalam system prompt. Atur `ownerDisplaySecret` untuk mengontrol hashing. +- `allowFrom` bersifat per-provider. Jika diatur, ini adalah **satu-satunya** sumber otorisasi (allowlist/pairing channel dan `useAccessGroups` diabaikan). +- `useAccessGroups: false` memungkinkan perintah melewati kebijakan access-group saat `allowFrom` tidak diatur. +- Peta docs perintah: + - katalog built-in + bundled: [Slash Commands](/id/tools/slash-commands) - permukaan perintah khusus channel: [Channels](/id/channels) - - perintah QQ Bot: [Bot QQ](/id/channels/qqbot) + - perintah QQ Bot: [QQ Bot](/id/channels/qqbot) - perintah pairing: [Pairing](/id/channels/pairing) - perintah kartu LINE: [LINE](/id/channels/line) - - memory dreaming: [Dreaming](/id/concepts/dreaming) + - dreaming memory: [Dreaming](/id/concepts/dreaming) --- -## Default agen +## Default agent ### `agents.defaults.workspace` @@ -906,7 +897,7 @@ Default: `~/.openclaw/workspace`. ### `agents.defaults.repoRoot` -Root repositori opsional yang ditampilkan di baris Runtime pada system prompt. Jika tidak diatur, OpenClaw mendeteksi otomatis dengan berjalan ke atas dari workspace. +Root repositori opsional yang ditampilkan dalam baris Runtime pada system prompt. Jika tidak diatur, OpenClaw mendeteksi otomatis dengan menelusuri ke atas dari workspace. ```json5 { @@ -916,7 +907,7 @@ Root repositori opsional yang ditampilkan di baris Runtime pada system prompt. J ### `agents.defaults.skills` -Allowlist Skills default opsional untuk agen yang tidak mengatur +Allowlist skill default opsional untuk agent yang tidak mengatur `agents.list[].skills`. ```json5 @@ -926,17 +917,16 @@ Allowlist Skills default opsional untuk agen yang tidak mengatur list: [ { id: "writer" }, // mewarisi github, weather { id: "docs", skills: ["docs-search"] }, // menggantikan default - { id: "locked-down", skills: [] }, // tanpa Skills + { id: "locked-down", skills: [] }, // tanpa skill ], }, } ``` -- Hilangkan `agents.defaults.skills` agar Skills tidak dibatasi secara default. +- Hilangkan `agents.defaults.skills` untuk Skills tanpa pembatasan secara default. - Hilangkan `agents.list[].skills` untuk mewarisi default. -- Atur `agents.list[].skills: []` untuk tanpa Skills. -- Daftar `agents.list[].skills` yang tidak kosong adalah set final untuk agen tersebut; daftar itu - tidak digabung dengan default. +- Atur `agents.list[].skills: []` untuk tanpa skill. +- Daftar `agents.list[].skills` yang tidak kosong adalah set akhir untuk agent tersebut; daftar ini tidak digabungkan dengan default. ### `agents.defaults.skipBootstrap` @@ -950,9 +940,9 @@ Menonaktifkan pembuatan otomatis file bootstrap workspace (`AGENTS.md`, `SOUL.md ### `agents.defaults.contextInjection` -Mengontrol kapan file bootstrap workspace dimasukkan ke system prompt. Default: `"always"`. +Mengontrol kapan file bootstrap workspace disuntikkan ke system prompt. Default: `"always"`. -- `"continuation-skip"`: turn lanjutan yang aman (setelah respons asisten selesai) melewati injeksi ulang bootstrap workspace, sehingga mengurangi ukuran prompt. Proses Heartbeat dan percobaan ulang pasca-Compaction tetap membangun ulang konteks. +- `"continuation-skip"`: giliran lanjutan yang aman (setelah respons asisten selesai) melewati penyuntikan ulang bootstrap workspace, sehingga mengurangi ukuran prompt. Proses Heartbeat dan percobaan ulang pasca-Compaction tetap membangun ulang konteks. ```json5 { @@ -962,7 +952,7 @@ Mengontrol kapan file bootstrap workspace dimasukkan ke system prompt. Default: ### `agents.defaults.bootstrapMaxChars` -Jumlah karakter maksimum per file bootstrap workspace sebelum dipotong. Default: `12000`. +Karakter maksimum per file bootstrap workspace sebelum dipotong. Default: `12000`. ```json5 { @@ -972,7 +962,7 @@ Jumlah karakter maksimum per file bootstrap workspace sebelum dipotong. Default: ### `agents.defaults.bootstrapTotalMaxChars` -Jumlah karakter total maksimum yang dimasukkan di seluruh file bootstrap workspace. Default: `60000`. +Total karakter maksimum yang disuntikkan di seluruh file bootstrap workspace. Default: `60000`. ```json5 { @@ -982,12 +972,12 @@ Jumlah karakter total maksimum yang dimasukkan di seluruh file bootstrap workspa ### `agents.defaults.bootstrapPromptTruncationWarning` -Mengontrol teks peringatan yang terlihat oleh agen saat konteks bootstrap dipotong. +Mengontrol teks peringatan yang terlihat oleh agent saat konteks bootstrap dipotong. Default: `"once"`. -- `"off"`: jangan pernah memasukkan teks peringatan ke system prompt. -- `"once"`: masukkan peringatan sekali per signature pemotongan unik (disarankan). -- `"always"`: masukkan peringatan pada setiap proses saat pemotongan ada. +- `"off"`: jangan pernah menyuntikkan teks peringatan ke system prompt. +- `"once"`: suntikkan peringatan satu kali per signature pemotongan unik (disarankan). +- `"always"`: suntikkan peringatan di setiap proses saat pemotongan ada. ```json5 { @@ -997,24 +987,24 @@ Default: `"once"`. ### Peta kepemilikan anggaran konteks -OpenClaw memiliki beberapa anggaran prompt/konteks bervolume tinggi, dan anggaran tersebut -sengaja dipisahkan menurut subsistem alih-alih semuanya mengalir melalui satu knob -generik. +OpenClaw memiliki beberapa anggaran prompt/konteks berukuran besar, dan +secara sengaja dipisah per subsistem alih-alih semuanya mengalir melalui satu +pengaturan generik. - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`: - injeksi bootstrap workspace normal. + penyuntikan bootstrap workspace normal. - `agents.defaults.startupContext.*`: - prelude startup sekali jalan untuk `/new` dan `/reset`, termasuk file + prelude startup satu kali untuk proses `/new` dan `/reset`, termasuk file `memory/*.md` harian terbaru. - `skills.limits.*`: - daftar Skills ringkas yang dimasukkan ke system prompt. + daftar Skills ringkas yang disuntikkan ke system prompt. - `agents.defaults.contextLimits.*`: - kutipan runtime yang dibatasi dan blok milik runtime yang dimasukkan. + kutipan runtime terbatas dan blok milik runtime yang disuntikkan. - `memory.qmd.limits.*`: - snippet pencarian memori terindeks dan ukuran injeksi. + pengindeksan snippet pencarian memory dan ukuran penyuntikan. -Gunakan override per agen yang sesuai hanya saat satu agen memerlukan +Gunakan override per-agent yang sesuai hanya saat satu agent memerlukan anggaran yang berbeda: - `agents.list[].skillsLimits.maxSkillsPromptChars` @@ -1022,8 +1012,7 @@ anggaran yang berbeda: #### `agents.defaults.startupContext` -Mengontrol prelude startup turn pertama yang dimasukkan pada proses `/new` dan `/reset` -tanpa tambahan apa pun. +Mengontrol prelude startup giliran pertama yang disuntikkan pada proses `/new` dan `/reset` kosong. ```json5 { @@ -1061,17 +1050,18 @@ Default bersama untuk permukaan konteks runtime yang dibatasi. } ``` -- `memoryGetMaxChars`: batas kutipan default `memory_get` sebelum metadata - pemotongan dan pemberitahuan kelanjutan ditambahkan. +- `memoryGetMaxChars`: batas kutipan default `memory_get` sebelum metadata pemotongan + dan pemberitahuan lanjutan ditambahkan. - `memoryGetDefaultLines`: jendela baris default `memory_get` saat `lines` dihilangkan. -- `toolResultMaxChars`: batas hasil alat live yang digunakan untuk hasil yang dipersistenkan dan +- `toolResultMaxChars`: batas hasil tool live yang digunakan untuk hasil persisten dan pemulihan overflow. -- `postCompactionMaxChars`: batas kutipan `AGENTS.md` yang digunakan selama injeksi refresh pasca-Compaction. +- `postCompactionMaxChars`: batas kutipan AGENTS.md yang digunakan saat penyuntikan + refresh pasca-Compaction. #### `agents.list[].contextLimits` -Override per agen untuk knob `contextLimits` bersama. Field yang dihilangkan mewarisi +Override per-agent untuk pengaturan `contextLimits` bersama. Field yang dihilangkan mewarisi dari `agents.defaults.contextLimits`. ```json5 @@ -1098,7 +1088,7 @@ dari `agents.defaults.contextLimits`. #### `skills.limits.maxSkillsPromptChars` -Batas global untuk daftar Skills ringkas yang dimasukkan ke system prompt. Ini +Batas global untuk daftar Skills ringkas yang disuntikkan ke system prompt. Ini tidak memengaruhi pembacaan file `SKILL.md` sesuai permintaan. ```json5 @@ -1113,7 +1103,7 @@ tidak memengaruhi pembacaan file `SKILL.md` sesuai permintaan. #### `agents.list[].skillsLimits.maxSkillsPromptChars` -Override per agen untuk anggaran prompt Skills. +Override per-agent untuk anggaran prompt skill. ```json5 { @@ -1132,11 +1122,11 @@ Override per agen untuk anggaran prompt Skills. ### `agents.defaults.imageMaxDimensionPx` -Ukuran piksel maksimum untuk sisi gambar terpanjang dalam blok gambar transkrip/alat sebelum panggilan provider. +Ukuran piksel maksimum untuk sisi gambar terpanjang pada blok gambar transkrip/tool sebelum panggilan provider. Default: `1200`. -Nilai yang lebih rendah biasanya mengurangi penggunaan vision-token dan ukuran payload permintaan untuk proses yang banyak screenshot. -Nilai yang lebih tinggi mempertahankan lebih banyak detail visual. +Nilai yang lebih rendah biasanya mengurangi penggunaan token vision dan ukuran payload permintaan untuk proses yang banyak menggunakan screenshot. +Nilai yang lebih tinggi mempertahankan detail visual lebih banyak. ```json5 { @@ -1146,7 +1136,7 @@ Nilai yang lebih tinggi mempertahankan lebih banyak detail visual. ### `agents.defaults.userTimezone` -Zona waktu untuk konteks system prompt (bukan timestamp pesan). Fallback ke zona waktu host. +Zona waktu untuk konteks system prompt (bukan timestamp pesan). Menggunakan fallback ke zona waktu host. ```json5 { @@ -1156,7 +1146,7 @@ Zona waktu untuk konteks system prompt (bukan timestamp pesan). Fallback ke zona ### `agents.defaults.timeFormat` -Format waktu di system prompt. Default: `auto` (preferensi OS). +Format waktu dalam system prompt. Default: `auto` (preferensi OS). ```json5 { @@ -1194,9 +1184,9 @@ Format waktu di system prompt. Default: `auto` (preferensi OS). primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // params provider default global + params: { cacheRetention: "long" }, // parameter provider default global embeddedHarness: { - runtime: "auto", // auto | pi | id harness terdaftar, mis. codex + runtime: "auto", // auto | pi | registered harness id, mis. codex fallback: "pi", // pi | none }, pdfMaxBytesMb: 10, @@ -1214,48 +1204,48 @@ Format waktu di system prompt. Default: `auto` (preferensi OS). ``` - `model`: menerima string (`"provider/model"`) atau objek (`{ primary, fallbacks }`). - - Bentuk string hanya menetapkan model primary. - - Bentuk objek menetapkan model primary plus model failover berurutan. + - Bentuk string hanya menetapkan model utama. + - Bentuk objek menetapkan model utama plus model failover berurutan. - `imageModel`: menerima string (`"provider/model"`) atau objek (`{ primary, fallbacks }`). - - Digunakan oleh jalur alat `image` sebagai konfigurasi model vision. - - Juga digunakan sebagai perutean fallback saat model yang dipilih/default tidak dapat menerima input gambar. + - Digunakan oleh jalur tool `image` sebagai konfigurasi model vision. + - Juga digunakan sebagai routing fallback saat model yang dipilih/default tidak dapat menerima input gambar. - `imageGenerationModel`: menerima string (`"provider/model"`) atau objek (`{ primary, fallbacks }`). - - Digunakan oleh kapabilitas pembuatan gambar bersama dan permukaan alat/plugin masa depan yang menghasilkan gambar. + - Digunakan oleh kapabilitas pembuatan gambar bersama dan permukaan tool/plugin mendatang yang menghasilkan gambar. - Nilai umum: `google/gemini-3.1-flash-image-preview` untuk pembuatan gambar Gemini native, `fal/fal-ai/flux/dev` untuk fal, atau `openai/gpt-image-2` untuk OpenAI Images. - - Jika Anda memilih provider/model secara langsung, konfigurasikan juga auth/API key provider yang cocok (misalnya `GEMINI_API_KEY` atau `GOOGLE_API_KEY` untuk `google/*`, `OPENAI_API_KEY` untuk `openai/*`, `FAL_KEY` untuk `fal/*`). - - Jika dihilangkan, `image_generate` tetap dapat menyimpulkan default provider yang didukung auth. Ia mencoba provider default saat ini terlebih dahulu, lalu provider pembuatan gambar terdaftar lainnya berdasarkan urutan ID provider. + - Jika Anda memilih provider/model secara langsung, konfigurasikan juga autentikasi/API key provider yang sesuai (misalnya `GEMINI_API_KEY` atau `GOOGLE_API_KEY` untuk `google/*`, `OPENAI_API_KEY` untuk `openai/*`, `FAL_KEY` untuk `fal/*`). + - Jika dihilangkan, `image_generate` tetap dapat menyimpulkan default provider yang didukung autentikasi. Tool ini mencoba provider default saat ini terlebih dahulu, lalu provider pembuatan gambar terdaftar lainnya dalam urutan provider-id. - `musicGenerationModel`: menerima string (`"provider/model"`) atau objek (`{ primary, fallbacks }`). - - Digunakan oleh kapabilitas pembuatan musik bersama dan alat bawaan `music_generate`. + - Digunakan oleh kapabilitas pembuatan musik bersama dan tool bawaan `music_generate`. - Nilai umum: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview`, atau `minimax/music-2.5+`. - - Jika dihilangkan, `music_generate` tetap dapat menyimpulkan default provider yang didukung auth. Ia mencoba provider default saat ini terlebih dahulu, lalu provider pembuatan musik terdaftar lainnya berdasarkan urutan ID provider. - - Jika Anda memilih provider/model secara langsung, konfigurasikan juga auth/API key provider yang cocok. + - Jika dihilangkan, `music_generate` tetap dapat menyimpulkan default provider yang didukung autentikasi. Tool ini mencoba provider default saat ini terlebih dahulu, lalu provider pembuatan musik terdaftar lainnya dalam urutan provider-id. + - Jika Anda memilih provider/model secara langsung, konfigurasikan juga autentikasi/API key provider yang sesuai. - `videoGenerationModel`: menerima string (`"provider/model"`) atau objek (`{ primary, fallbacks }`). - - Digunakan oleh kapabilitas pembuatan video bersama dan alat bawaan `video_generate`. + - Digunakan oleh kapabilitas pembuatan video bersama dan tool bawaan `video_generate`. - Nilai umum: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash`, atau `qwen/wan2.7-r2v`. - - Jika dihilangkan, `video_generate` tetap dapat menyimpulkan default provider yang didukung auth. Ia mencoba provider default saat ini terlebih dahulu, lalu provider pembuatan video terdaftar lainnya berdasarkan urutan ID provider. - - Jika Anda memilih provider/model secara langsung, konfigurasikan juga auth/API key provider yang cocok. - - Provider pembuatan video Qwen bawaan mendukung hingga 1 video output, 1 gambar input, 4 video input, durasi 10 detik, dan opsi tingkat provider `size`, `aspectRatio`, `resolution`, `audio`, serta `watermark`. + - Jika dihilangkan, `video_generate` tetap dapat menyimpulkan default provider yang didukung autentikasi. Tool ini mencoba provider default saat ini terlebih dahulu, lalu provider pembuatan video terdaftar lainnya dalam urutan provider-id. + - Jika Anda memilih provider/model secara langsung, konfigurasikan juga autentikasi/API key provider yang sesuai. + - Provider pembuatan video Qwen bawaan mendukung hingga 1 video output, 1 gambar input, 4 video input, durasi 10 detik, serta opsi tingkat provider `size`, `aspectRatio`, `resolution`, `audio`, dan `watermark`. - `pdfModel`: menerima string (`"provider/model"`) atau objek (`{ primary, fallbacks }`). - - Digunakan oleh alat `pdf` untuk perutean model. - - Jika dihilangkan, alat PDF fallback ke `imageModel`, lalu ke model sesi/default yang telah di-resolve. -- `pdfMaxBytesMb`: batas ukuran PDF default untuk alat `pdf` saat `maxBytesMb` tidak diberikan pada waktu pemanggilan. -- `pdfMaxPages`: jumlah halaman maksimum default yang dipertimbangkan oleh mode fallback ekstraksi pada alat `pdf`. -- `verboseDefault`: level verbose default untuk agen. Nilai: `"off"`, `"on"`, `"full"`. Default: `"off"`. -- `elevatedDefault`: level output elevated default untuk agen. Nilai: `"off"`, `"on"`, `"ask"`, `"full"`. Default: `"on"`. -- `model.primary`: format `provider/model` (mis. `openai/gpt-5.4`). Jika Anda menghilangkan provider, OpenClaw mencoba alias terlebih dahulu, lalu kecocokan provider terkonfigurasi yang unik untuk ID model persis itu, dan baru kemudian fallback ke provider default yang dikonfigurasi (perilaku kompatibilitas lama, jadi sebaiknya gunakan `provider/model` eksplisit). Jika provider itu tidak lagi mengekspos model default terkonfigurasi, OpenClaw fallback ke provider/model terkonfigurasi pertama alih-alih menampilkan default provider lama yang sudah dihapus. -- `models`: katalog model terkonfigurasi dan allowlist untuk `/model`. Setiap entri dapat menyertakan `alias` (shortcut) dan `params` (khusus provider, misalnya `temperature`, `maxTokens`, `cacheRetention`, `context1m`). -- `params`: parameter provider default global yang diterapkan ke semua model. Diatur pada `agents.defaults.params` (mis. `{ cacheRetention: "long" }`). -- Prioritas penggabungan `params` (config): `agents.defaults.params` (dasar global) dioverride oleh `agents.defaults.models["provider/model"].params` (per model), lalu `agents.list[].params` (ID agen yang cocok) mengoverride per key. Lihat [Prompt Caching](/id/reference/prompt-caching) untuk detail. -- `embeddedHarness`: kebijakan runtime agen embedded tingkat rendah default. Gunakan `runtime: "auto"` agar harness Plugin terdaftar dapat mengklaim model yang didukung, `runtime: "pi"` untuk memaksa harness PI bawaan, atau ID harness terdaftar seperti `runtime: "codex"`. Atur `fallback: "none"` untuk menonaktifkan fallback PI otomatis. -- Penulis config yang memutasi field ini (misalnya `/models set`, `/models set-image`, dan perintah tambah/hapus fallback) menyimpan bentuk objek kanonis dan mempertahankan daftar fallback yang sudah ada bila memungkinkan. -- `maxConcurrent`: jumlah maksimum proses agen paralel di seluruh sesi (setiap sesi tetap diserialkan). Default: 4. + - Digunakan oleh tool `pdf` untuk routing model. + - Jika dihilangkan, tool PDF menggunakan fallback ke `imageModel`, lalu ke model sesi/default yang sudah di-resolve. +- `pdfMaxBytesMb`: batas ukuran PDF default untuk tool `pdf` saat `maxBytesMb` tidak diberikan pada waktu pemanggilan. +- `pdfMaxPages`: jumlah halaman maksimum default yang dipertimbangkan oleh mode fallback ekstraksi pada tool `pdf`. +- `verboseDefault`: level verbose default untuk agent. Nilai: `"off"`, `"on"`, `"full"`. Default: `"off"`. +- `elevatedDefault`: level output elevated default untuk agent. Nilai: `"off"`, `"on"`, `"ask"`, `"full"`. Default: `"on"`. +- `model.primary`: format `provider/model` (mis. `openai/gpt-5.4`). Jika Anda menghilangkan provider, OpenClaw mencoba alias terlebih dahulu, lalu kecocokan configured-provider unik untuk model id persis itu, dan baru setelah itu menggunakan fallback ke provider default yang dikonfigurasi (perilaku kompatibilitas yang deprecated, jadi sebaiknya gunakan `provider/model` eksplisit). Jika provider tersebut tidak lagi mengekspos model default yang dikonfigurasi, OpenClaw menggunakan fallback ke provider/model terkonfigurasi pertama alih-alih menampilkan default provider lama yang sudah dihapus. +- `models`: katalog model yang dikonfigurasi dan allowlist untuk `/model`. Setiap entri dapat menyertakan `alias` (shortcut) dan `params` (spesifik provider, misalnya `temperature`, `maxTokens`, `cacheRetention`, `context1m`). +- `params`: parameter provider default global yang diterapkan ke semua model. Tetapkan di `agents.defaults.params` (mis. `{ cacheRetention: "long" }`). +- Urutan prioritas penggabungan `params` (config): `agents.defaults.params` (basis global) ditimpa oleh `agents.defaults.models["provider/model"].params` (per-model), lalu `agents.list[].params` (agent id yang cocok) menimpa per kunci. Lihat [Prompt Caching](/id/reference/prompt-caching) untuk detail. +- `embeddedHarness`: kebijakan runtime agent embedded tingkat rendah default. Gunakan `runtime: "auto"` agar harness Plugin terdaftar dapat mengklaim model yang didukung, `runtime: "pi"` untuk memaksa harness PI bawaan, atau id harness terdaftar seperti `runtime: "codex"`. Tetapkan `fallback: "none"` untuk menonaktifkan fallback PI otomatis. +- Penulis konfigurasi yang memutasi field ini (misalnya `/models set`, `/models set-image`, dan perintah tambah/hapus fallback) menyimpan bentuk objek kanonis dan mempertahankan daftar fallback yang ada bila memungkinkan. +- `maxConcurrent`: jumlah maksimum proses agent paralel di seluruh sesi (setiap sesi tetap diserialkan). Default: 4. ### `agents.defaults.embeddedHarness` -`embeddedHarness` mengontrol executor tingkat rendah mana yang menjalankan turn agen embedded. +`embeddedHarness` mengontrol executor tingkat rendah mana yang menjalankan giliran agent embedded. Sebagian besar deployment sebaiknya mempertahankan default `{ runtime: "auto", fallback: "pi" }`. Gunakan ini saat Plugin tepercaya menyediakan harness native, seperti harness -app-server Codex bawaan bundel. +app-server Codex bawaan. ```json5 { @@ -1271,10 +1261,10 @@ app-server Codex bawaan bundel. } ``` -- `runtime`: `"auto"`, `"pi"`, atau ID harness Plugin terdaftar. Plugin Codex bawaan bundel mendaftarkan `codex`. -- `fallback`: `"pi"` atau `"none"`. `"pi"` mempertahankan harness PI bawaan sebagai fallback kompatibilitas. `"none"` membuat pemilihan harness Plugin yang hilang atau tidak didukung gagal alih-alih diam-diam menggunakan PI. -- Override lingkungan: `OPENCLAW_AGENT_RUNTIME=` mengoverride `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` menonaktifkan fallback PI untuk proses itu. -- Untuk deployment khusus Codex, atur `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"`, dan `embeddedHarness.fallback: "none"`. +- `runtime`: `"auto"`, `"pi"`, atau id harness Plugin terdaftar. Plugin Codex bawaan mendaftarkan `codex`. +- `fallback`: `"pi"` atau `"none"`. `"pi"` mempertahankan harness PI bawaan sebagai fallback kompatibilitas saat tidak ada harness Plugin yang dipilih. `"none"` membuat pemilihan harness Plugin yang hilang atau tidak didukung gagal alih-alih diam-diam menggunakan PI. Kegagalan harness Plugin yang dipilih selalu ditampilkan secara langsung. +- Override env: `OPENCLAW_AGENT_RUNTIME=` menimpa `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` menonaktifkan fallback PI untuk proses tersebut. +- Untuk deployment khusus Codex, tetapkan `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"`, dan `embeddedHarness.fallback: "none"`. - Ini hanya mengontrol harness chat embedded. Pembuatan media, vision, PDF, musik, video, dan TTS tetap menggunakan pengaturan provider/model masing-masing. **Singkatan alias bawaan** (hanya berlaku saat model ada di `agents.defaults.models`): @@ -1290,15 +1280,15 @@ app-server Codex bawaan bundel. | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -Alias yang Anda konfigurasikan selalu mengalahkan default. +Alias yang Anda konfigurasi selalu mengalahkan default. -Model Z.AI GLM-4.x otomatis mengaktifkan mode thinking kecuali Anda mengatur `--thinking off` atau mendefinisikan sendiri `agents.defaults.models["zai/"].params.thinking`. -Model Z.AI mengaktifkan `tool_stream` secara default untuk streaming pemanggilan alat. Atur `agents.defaults.models["zai/"].params.tool_stream` ke `false` untuk menonaktifkannya. -Model Anthropic Claude 4.6 default ke thinking `adaptive` saat tidak ada level thinking eksplisit yang diatur. +Model Z.AI GLM-4.x secara otomatis mengaktifkan mode thinking kecuali Anda menetapkan `--thinking off` atau mendefinisikan sendiri `agents.defaults.models["zai/"].params.thinking`. +Model Z.AI mengaktifkan `tool_stream` secara default untuk streaming pemanggilan tool. Tetapkan `agents.defaults.models["zai/"].params.tool_stream` ke `false` untuk menonaktifkannya. +Model Anthropic Claude 4.6 default ke thinking `adaptive` saat tidak ada level thinking eksplisit yang ditetapkan. ### `agents.defaults.cliBackends` -Backend CLI opsional untuk proses fallback hanya-teks (tanpa pemanggilan alat). Berguna sebagai cadangan saat provider API gagal. +Backend CLI opsional untuk proses fallback hanya teks (tanpa pemanggilan tool). Berguna sebagai cadangan saat provider API gagal. ```json5 { @@ -1326,13 +1316,13 @@ Backend CLI opsional untuk proses fallback hanya-teks (tanpa pemanggilan alat). } ``` -- Backend CLI bersifat text-first; alat selalu dinonaktifkan. +- Backend CLI mengutamakan teks; tool selalu dinonaktifkan. - Sesi didukung saat `sessionArg` diatur. - Pass-through gambar didukung saat `imageArg` menerima path file. ### `agents.defaults.systemPromptOverride` -Gantikan seluruh system prompt rakitan OpenClaw dengan string tetap. Atur di level default (`agents.defaults.systemPromptOverride`) atau per agen (`agents.list[].systemPromptOverride`). Nilai per agen diprioritaskan; nilai kosong atau yang hanya berisi spasi diabaikan. Berguna untuk eksperimen prompt terkontrol. +Ganti seluruh system prompt yang dirakit OpenClaw dengan string tetap. Tetapkan pada level default (`agents.defaults.systemPromptOverride`) atau per agent (`agents.list[].systemPromptOverride`). Nilai per-agent memiliki prioritas lebih tinggi; nilai kosong atau hanya whitespace diabaikan. Berguna untuk eksperimen prompt terkontrol. ```json5 { @@ -1373,15 +1363,15 @@ Proses Heartbeat berkala. } ``` -- `every`: string durasi (ms/s/m/h). Default: `30m` (auth API-key) atau `1h` (auth OAuth). Atur ke `0m` untuk menonaktifkan. -- `includeSystemPromptSection`: saat false, menghilangkan bagian Heartbeat dari system prompt dan melewati injeksi `HEARTBEAT.md` ke konteks bootstrap. Default: `true`. -- `suppressToolErrorWarnings`: saat true, menekan payload peringatan error alat selama proses Heartbeat. -- `timeoutSeconds`: waktu maksimum dalam detik yang diizinkan untuk satu turn agen Heartbeat sebelum dibatalkan. Biarkan tidak diatur untuk menggunakan `agents.defaults.timeoutSeconds`. -- `directPolicy`: kebijakan pengiriman langsung/DM. `allow` (default) mengizinkan pengiriman target langsung. `block` menekan pengiriman target langsung dan mengeluarkan `reason=dm-blocked`. -- `lightContext`: saat true, proses Heartbeat menggunakan konteks bootstrap ringan dan hanya mempertahankan `HEARTBEAT.md` dari file bootstrap workspace. -- `isolatedSession`: saat true, setiap Heartbeat berjalan dalam sesi baru tanpa riwayat percakapan sebelumnya. Pola isolasi yang sama seperti Cron `sessionTarget: "isolated"`. Mengurangi biaya token per Heartbeat dari ~100K menjadi ~2-5K token. -- Per agen: atur `agents.list[].heartbeat`. Saat agen mana pun mendefinisikan `heartbeat`, **hanya agen tersebut** yang menjalankan Heartbeat. -- Heartbeat menjalankan turn agen penuh — interval yang lebih pendek membakar lebih banyak token. +- `every`: string durasi (ms/s/m/h). Default: `30m` (autentikasi API-key) atau `1h` (autentikasi OAuth). Tetapkan ke `0m` untuk menonaktifkan. +- `includeSystemPromptSection`: saat false, menghilangkan bagian Heartbeat dari system prompt dan melewati penyuntikan `HEARTBEAT.md` ke konteks bootstrap. Default: `true`. +- `suppressToolErrorWarnings`: saat true, menekan payload peringatan error tool selama proses heartbeat. +- `timeoutSeconds`: waktu maksimum dalam detik yang diizinkan untuk satu giliran agent heartbeat sebelum dibatalkan. Biarkan tidak diatur untuk menggunakan `agents.defaults.timeoutSeconds`. +- `directPolicy`: kebijakan pengiriman langsung/DM. `allow` (default) mengizinkan pengiriman target langsung. `block` menekan pengiriman target langsung dan menghasilkan `reason=dm-blocked`. +- `lightContext`: saat true, proses heartbeat menggunakan konteks bootstrap ringan dan hanya mempertahankan `HEARTBEAT.md` dari file bootstrap workspace. +- `isolatedSession`: saat true, setiap heartbeat berjalan dalam sesi baru tanpa riwayat percakapan sebelumnya. Pola isolasi yang sama seperti Cron `sessionTarget: "isolated"`. Mengurangi biaya token per heartbeat dari ~100K menjadi ~2-5K token. +- Per-agent: tetapkan `agents.list[].heartbeat`. Saat ada agent yang mendefinisikan `heartbeat`, **hanya agent tersebut** yang menjalankan heartbeat. +- Heartbeat menjalankan giliran agent penuh — interval yang lebih pendek menghabiskan lebih banyak token. ### `agents.defaults.compaction` @@ -1391,12 +1381,12 @@ Proses Heartbeat berkala. defaults: { compaction: { mode: "safeguard", // default | safeguard - provider: "my-provider", // id Plugin provider Compaction terdaftar (opsional) + provider: "my-provider", // id dari plugin provider Compaction terdaftar (opsional) timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // digunakan saat identifierPolicy=custom - postCompactionSections: ["Session Startup", "Red Lines"], // [] menonaktifkan reinjeksi + postCompactionSections: ["Session Startup", "Red Lines"], // [] menonaktifkan penyuntikan ulang model: "openrouter/anthropic/claude-sonnet-4-6", // override model khusus Compaction opsional notifyUser: true, // kirim pemberitahuan singkat saat Compaction dimulai dan selesai (default: false) memoryFlush: { @@ -1412,18 +1402,18 @@ Proses Heartbeat berkala. ``` - `mode`: `default` atau `safeguard` (ringkasan bertahap untuk riwayat panjang). Lihat [Compaction](/id/concepts/compaction). -- `provider`: id Plugin provider Compaction terdaftar. Saat diatur, `summarize()` milik provider dipanggil alih-alih ringkasan LLM bawaan. Fallback ke bawaan jika gagal. Menetapkan provider memaksa `mode: "safeguard"`. Lihat [Compaction](/id/concepts/compaction). +- `provider`: id dari plugin provider Compaction terdaftar. Saat diatur, `summarize()` milik provider dipanggil sebagai pengganti peringkasan LLM bawaan. Jika gagal, menggunakan fallback ke bawaan. Menetapkan provider memaksa `mode: "safeguard"`. Lihat [Compaction](/id/concepts/compaction). - `timeoutSeconds`: jumlah detik maksimum yang diizinkan untuk satu operasi Compaction sebelum OpenClaw membatalkannya. Default: `900`. - `identifierPolicy`: `strict` (default), `off`, atau `custom`. `strict` menambahkan panduan bawaan untuk mempertahankan identifier opak selama peringkasan Compaction. -- `identifierInstructions`: teks kustom opsional untuk pelestarian identifier yang digunakan saat `identifierPolicy=custom`. -- `postCompactionSections`: nama bagian H2/H3 `AGENTS.md` opsional untuk diinjeksi ulang setelah Compaction. Default ke `["Session Startup", "Red Lines"]`; atur `[]` untuk menonaktifkan reinjeksi. Saat tidak diatur atau secara eksplisit diatur ke pasangan default itu, heading lama `Every Session`/`Safety` juga diterima sebagai fallback warisan. -- `model`: override `provider/model-id` opsional hanya untuk peringkasan Compaction. Gunakan ini saat sesi utama harus tetap menggunakan satu model tetapi ringkasan Compaction harus berjalan pada model lain; jika tidak diatur, Compaction menggunakan model primary sesi. -- `notifyUser`: saat `true`, mengirim pemberitahuan singkat kepada pengguna ketika Compaction dimulai dan selesai (misalnya, "Compacting context..." dan "Compaction complete"). Dinonaktifkan secara default agar Compaction tetap senyap. -- `memoryFlush`: turn agentik senyap sebelum auto-Compaction untuk menyimpan memori tahan lama. Dilewati saat workspace hanya-baca. +- `identifierInstructions`: teks kustom opsional untuk mempertahankan identifier yang digunakan saat `identifierPolicy=custom`. +- `postCompactionSections`: nama bagian H2/H3 AGENTS.md opsional yang akan disuntikkan ulang setelah Compaction. Default ke `["Session Startup", "Red Lines"]`; atur `[]` untuk menonaktifkan penyuntikan ulang. Saat tidak diatur atau secara eksplisit diatur ke pasangan default tersebut, heading lama `Every Session`/`Safety` juga diterima sebagai fallback lama. +- `model`: override `provider/model-id` opsional hanya untuk peringkasan Compaction. Gunakan ini saat sesi utama harus tetap memakai satu model tetapi ringkasan Compaction harus dijalankan di model lain; jika tidak diatur, Compaction menggunakan model utama sesi. +- `notifyUser`: saat `true`, mengirim pemberitahuan singkat ke pengguna saat Compaction dimulai dan saat selesai (misalnya, "Compacting context..." dan "Compaction complete"). Dinonaktifkan secara default agar Compaction tetap senyap. +- `memoryFlush`: giliran agentic senyap sebelum auto-Compaction untuk menyimpan memory yang tahan lama. Dilewati saat workspace read-only. ### `agents.defaults.contextPruning` -Memangkas **hasil alat lama** dari konteks dalam memori sebelum dikirim ke LLM. **Tidak** memodifikasi riwayat sesi di disk. +Memangkas **hasil tool lama** dari konteks dalam memori sebelum dikirim ke LLM. **Tidak** memodifikasi riwayat sesi di disk. ```json5 { @@ -1447,19 +1437,19 @@ Memangkas **hasil alat lama** dari konteks dalam memori sebelum dikirim ke LLM. -- `mode: "cache-ttl"` mengaktifkan pass pemangkasan. -- `ttl` mengontrol seberapa sering pemangkasan dapat dijalankan lagi (setelah sentuhan cache terakhir). -- Pemangkasan lebih dulu melakukan soft-trim pada hasil alat yang terlalu besar, lalu hard-clear pada hasil alat yang lebih lama jika diperlukan. +- `mode: "cache-ttl"` mengaktifkan proses pemangkasan. +- `ttl` mengontrol seberapa sering pemangkasan dapat dijalankan kembali (setelah cache terakhir disentuh). +- Pemangkasan terlebih dahulu melakukan soft-trim pada hasil tool yang terlalu besar, lalu hard-clear pada hasil tool yang lebih lama jika diperlukan. **Soft-trim** mempertahankan bagian awal + akhir dan menyisipkan `...` di tengah. -**Hard-clear** mengganti seluruh hasil alat dengan placeholder. +**Hard-clear** mengganti seluruh hasil tool dengan placeholder. Catatan: -- Blok gambar tidak pernah dipangkas/dibersihkan. +- Blok gambar tidak pernah dipangkas/dihapus. - Rasio berbasis karakter (perkiraan), bukan jumlah token yang presisi. -- Jika pesan asisten kurang dari `keepLastAssistants`, pemangkasan dilewati. +- Jika ada kurang dari `keepLastAssistants` pesan asisten, pemangkasan dilewati. @@ -1482,10 +1472,10 @@ Lihat [Session Pruning](/id/concepts/session-pruning) untuk detail perilaku. ``` - Channel non-Telegram memerlukan `*.blockStreaming: true` eksplisit untuk mengaktifkan balasan blok. -- Override channel: `channels..blockStreamingCoalesce` (dan varian per akun). Signal/Slack/Discord/Google Chat default `minChars: 1500`. -- `humanDelay`: jeda acak antara balasan blok. `natural` = 800–2500ms. Override per agen: `agents.list[].humanDelay`. +- Override channel: `channels..blockStreamingCoalesce` (dan varian per akun). Signal/Slack/Discord/Google Chat default ke `minChars: 1500`. +- `humanDelay`: jeda acak di antara balasan blok. `natural` = 800–2500ms. Override per-agent: `agents.list[].humanDelay`. -Lihat [Streaming](/id/concepts/streaming) untuk detail perilaku + pemotongan. +Lihat [Streaming](/id/concepts/streaming) untuk detail perilaku + chunking. ### Indikator mengetik @@ -1509,7 +1499,7 @@ Lihat [Typing Indicators](/id/concepts/typing-indicators). ### `agents.defaults.sandbox` -Sandboxing opsional untuk agen embedded. Lihat [Sandboxing](/id/gateway/sandboxing) untuk panduan lengkap. +Sandbox opsional untuk agent embedded. Lihat [Sandboxing](/id/gateway/sandboxing) untuk panduan lengkap. ```json5 { @@ -1555,7 +1545,7 @@ Sandboxing opsional untuk agen embedded. Lihat [Sandboxing](/id/gateway/sandboxi identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // SecretRef / konten inline juga didukung: + // SecretRef / isi inline juga didukung: // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" }, // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" }, // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" }, @@ -1609,49 +1599,49 @@ Sandboxing opsional untuk agen embedded. Lihat [Sandboxing](/id/gateway/sandboxi **Backend:** - `docker`: runtime Docker lokal (default) -- `ssh`: runtime jarak jauh umum berbasis SSH +- `ssh`: runtime remote umum berbasis SSH - `openshell`: runtime OpenShell Saat `backend: "openshell"` dipilih, pengaturan khusus runtime dipindahkan ke `plugins.entries.openshell.config`. -**Config backend SSH:** +**Konfigurasi backend SSH:** - `target`: target SSH dalam bentuk `user@host[:port]` - `command`: perintah klien SSH (default: `ssh`) -- `workspaceRoot`: root remote absolut yang digunakan untuk workspace per cakupan -- `identityFile` / `certificateFile` / `knownHostsFile`: file lokal yang ada dan diteruskan ke OpenSSH -- `identityData` / `certificateData` / `knownHostsData`: konten inline atau SecretRef yang dimaterialisasikan OpenClaw ke file sementara saat runtime -- `strictHostKeyChecking` / `updateHostKeys`: knob kebijakan host-key OpenSSH +- `workspaceRoot`: root remote absolut yang digunakan untuk workspace per-scope +- `identityFile` / `certificateFile` / `knownHostsFile`: file lokal yang sudah ada dan diteruskan ke OpenSSH +- `identityData` / `certificateData` / `knownHostsData`: isi inline atau SecretRef yang diwujudkan OpenClaw menjadi file sementara saat runtime +- `strictHostKeyChecking` / `updateHostKeys`: pengaturan kebijakan host-key OpenSSH -**Prioritas auth SSH:** +**Prioritas autentikasi SSH:** - `identityData` mengalahkan `identityFile` - `certificateData` mengalahkan `certificateFile` - `knownHostsData` mengalahkan `knownHostsFile` -- Nilai `*Data` berbasis SecretRef di-resolve dari snapshot runtime secret aktif sebelum sesi sandbox dimulai +- Nilai `*Data` berbasis SecretRef di-resolve dari snapshot runtime secrets aktif sebelum sesi sandbox dimulai **Perilaku backend SSH:** -- menyemai workspace remote sekali setelah create atau recreate -- lalu menjaga workspace SSH remote tetap kanonis -- merutekan `exec`, alat file, dan path media melalui SSH +- melakukan seed workspace remote satu kali setelah create atau recreate +- lalu mempertahankan workspace SSH remote sebagai kanonis +- merutekan `exec`, tool file, dan path media melalui SSH - tidak menyinkronkan perubahan remote kembali ke host secara otomatis - tidak mendukung container browser sandbox **Akses workspace:** -- `none`: workspace sandbox per cakupan di bawah `~/.openclaw/sandboxes` -- `ro`: workspace sandbox di `/workspace`, workspace agen dimount read-only di `/agent` -- `rw`: workspace agen dimount baca/tulis di `/workspace` +- `none`: workspace sandbox per-scope di bawah `~/.openclaw/sandboxes` +- `ro`: workspace sandbox di `/workspace`, workspace agent dimount read-only di `/agent` +- `rw`: workspace agent dimount baca/tulis di `/workspace` -**Cakupan:** +**Scope:** - `session`: container + workspace per sesi -- `agent`: satu container + workspace per agen (default) -- `shared`: container dan workspace bersama (tanpa isolasi lintas sesi) +- `agent`: satu container + workspace per agent (default) +- `shared`: container dan workspace bersama (tanpa isolasi antar sesi) -**Config Plugin OpenShell:** +**Konfigurasi Plugin OpenShell:** ```json5 { @@ -1679,30 +1669,30 @@ Saat `backend: "openshell"` dipilih, pengaturan khusus runtime dipindahkan ke **Mode OpenShell:** -- `mirror`: semai remote dari lokal sebelum exec, sinkronkan kembali setelah exec; workspace lokal tetap kanonis -- `remote`: semai remote sekali saat sandbox dibuat, lalu pertahankan workspace remote sebagai kanonis +- `mirror`: seed remote dari lokal sebelum exec, sinkronkan kembali setelah exec; workspace lokal tetap kanonis +- `remote`: seed remote satu kali saat sandbox dibuat, lalu mempertahankan workspace remote sebagai kanonis -Dalam mode `remote`, edit host-lokal yang dibuat di luar OpenClaw tidak disinkronkan ke sandbox secara otomatis setelah langkah penyemaian. -Transport adalah SSH ke sandbox OpenShell, tetapi Plugin memiliki siklus hidup sandbox dan sinkronisasi mirror opsional. +Dalam mode `remote`, edit lokal host yang dibuat di luar OpenClaw tidak disinkronkan ke sandbox secara otomatis setelah langkah seed. +Transport menggunakan SSH ke sandbox OpenShell, tetapi Plugin memiliki lifecycle sandbox dan sinkronisasi mirror opsional. -**`setupCommand`** berjalan sekali setelah pembuatan container (melalui `sh -lc`). Memerlukan egress jaringan, root yang dapat ditulisi, dan pengguna root. +**`setupCommand`** dijalankan satu kali setelah pembuatan container (melalui `sh -lc`). Memerlukan egress jaringan, root yang dapat ditulis, dan pengguna root. -**Container default ke `network: "none"`** — atur ke `"bridge"` (atau jaringan bridge kustom) jika agen memerlukan akses keluar. -`"host"` diblokir. `"container:"` diblokir secara default kecuali Anda secara eksplisit mengatur +**Container default ke `network: "none"`** — atur ke `"bridge"` (atau jaringan bridge kustom) jika agent memerlukan akses keluar. +`"host"` diblokir. `"container:"` diblokir secara default kecuali Anda secara eksplisit menetapkan `sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (break-glass). -**Lampiran masuk** ditempatkan ke `media/inbound/*` di workspace aktif. +**Lampiran masuk** ditempatkan ke `media/inbound/*` dalam workspace aktif. -**`docker.binds`** me-mount direktori host tambahan; bind global dan per agen digabungkan. +**`docker.binds`** me-mount direktori host tambahan; bind global dan per-agent digabungkan. -**Browser sandbox** (`sandbox.browser.enabled`): Chromium + CDP dalam container. URL noVNC dimasukkan ke system prompt. Tidak memerlukan `browser.enabled` di `openclaw.json`. +**Browser tersandbox** (`sandbox.browser.enabled`): Chromium + CDP dalam container. URL noVNC disuntikkan ke system prompt. Tidak memerlukan `browser.enabled` di `openclaw.json`. Akses pengamat noVNC menggunakan autentikasi VNC secara default dan OpenClaw mengeluarkan URL token berumur pendek (alih-alih mengekspos kata sandi di URL bersama). -- `allowHostControl: false` (default) memblokir sesi sandbox agar tidak menargetkan browser host. -- `network` default ke `openclaw-sandbox-browser` (jaringan bridge khusus). Atur ke `bridge` hanya jika Anda memang menginginkan konektivitas bridge global. +- `allowHostControl: false` (default) memblokir sesi tersandbox untuk menargetkan browser host. +- `network` default-nya `openclaw-sandbox-browser` (jaringan bridge khusus). Atur ke `bridge` hanya jika Anda secara eksplisit menginginkan konektivitas bridge global. - `cdpSourceRange` secara opsional membatasi ingress CDP di tepi container ke rentang CIDR (misalnya `172.21.0.1/32`). - `sandbox.browser.binds` me-mount direktori host tambahan hanya ke container browser sandbox. Saat diatur (termasuk `[]`), ini menggantikan `docker.binds` untuk container browser. -- Default peluncuran didefinisikan di `scripts/sandbox-browser-entrypoint.sh` dan disetel untuk host container: +- Default peluncuran didefinisikan di `scripts/sandbox-browser-entrypoint.sh` dan dituning untuk host container: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1719,31 +1709,31 @@ Akses pengamat noVNC menggunakan autentikasi VNC secara default dan OpenClaw men - `--renderer-process-limit=2` - `--no-zygote` - `--metrics-recording-only` - - `--disable-extensions` (default aktif) - - `--disable-3d-apis`, `--disable-software-rasterizer`, dan `--disable-gpu` aktif - secara default dan dapat dinonaktifkan dengan + - `--disable-extensions` (aktif secara default) + - `--disable-3d-apis`, `--disable-software-rasterizer`, dan `--disable-gpu` + aktif secara default dan dapat dinonaktifkan dengan `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` jika penggunaan WebGL/3D memerlukannya. - - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` mengaktifkan kembali extension jika alur kerja Anda + - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` mengaktifkan kembali ekstensi jika alur kerja Anda bergantung padanya. - `--renderer-process-limit=2` dapat diubah dengan `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; atur `0` untuk menggunakan batas proses default Chromium. - - ditambah `--no-sandbox` dan `--disable-setuid-sandbox` saat `noSandbox` diaktifkan. - - Default adalah baseline image container; gunakan image browser kustom dengan entrypoint kustom - untuk mengubah default container. + - plus `--no-sandbox` dan `--disable-setuid-sandbox` saat `noSandbox` diaktifkan. + - Default adalah baseline image container; gunakan image browser kustom dengan + entrypoint kustom untuk mengubah default container. Browser sandboxing dan `sandbox.docker.binds` hanya untuk Docker. -Build image: +Bangun image: ```bash scripts/sandbox-setup.sh # image sandbox utama scripts/sandbox-browser-setup.sh # image browser opsional ``` -### `agents.list` (override per agen) +### `agents.list` (override per-agent) ```json5 { @@ -1756,11 +1746,11 @@ scripts/sandbox-browser-setup.sh # image browser opsional workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", model: "anthropic/claude-opus-4-6", // atau { primary, fallbacks } - thinkingDefault: "high", // override level thinking per agen - reasoningDefault: "on", // override visibilitas reasoning per agen - fastModeDefault: false, // override fast mode per agen + thinkingDefault: "high", // override level thinking per-agent + reasoningDefault: "on", // override visibilitas reasoning per-agent + fastModeDefault: false, // override fast mode per-agent embeddedHarness: { runtime: "auto", fallback: "pi" }, - params: { cacheRetention: "none" }, // mengoverride key params defaults.models yang cocok + params: { cacheRetention: "none" }, // menimpa params defaults.models yang cocok per kunci skills: ["docs-search"], // menggantikan agents.defaults.skills saat diatur identity: { name: "Samantha", @@ -1792,27 +1782,27 @@ scripts/sandbox-browser-setup.sh # image browser opsional } ``` -- `id`: ID agen stabil (wajib). -- `default`: saat ada beberapa yang diatur, yang pertama menang (peringatan dicatat). Jika tidak ada yang diatur, entri daftar pertama adalah default. -- `model`: bentuk string hanya mengoverride `primary`; bentuk objek `{ primary, fallbacks }` mengoverride keduanya (`[]` menonaktifkan fallback global). Pekerjaan Cron yang hanya mengoverride `primary` tetap mewarisi fallback default kecuali Anda mengatur `fallbacks: []`. -- `params`: params stream per agen yang digabung di atas entri model yang dipilih di `agents.defaults.models`. Gunakan ini untuk override khusus agen seperti `cacheRetention`, `temperature`, atau `maxTokens` tanpa menduplikasi seluruh katalog model. -- `skills`: allowlist Skills per agen opsional. Jika dihilangkan, agen mewarisi `agents.defaults.skills` bila diatur; daftar eksplisit menggantikan default alih-alih digabung, dan `[]` berarti tanpa Skills. -- `thinkingDefault`: level thinking default per agen opsional (`off | minimal | low | medium | high | xhigh | adaptive | max`). Mengoverride `agents.defaults.thinkingDefault` untuk agen ini saat tidak ada override per pesan atau sesi yang diatur. -- `reasoningDefault`: visibilitas reasoning default per agen opsional (`on | off | stream`). Berlaku saat tidak ada override reasoning per pesan atau sesi yang diatur. -- `fastModeDefault`: default per agen opsional untuk fast mode (`true | false`). Berlaku saat tidak ada override fast-mode per pesan atau sesi yang diatur. -- `embeddedHarness`: override kebijakan harness tingkat rendah per agen opsional. Gunakan `{ runtime: "codex", fallback: "none" }` agar satu agen khusus Codex sementara agen lain tetap menggunakan fallback PI default. -- `runtime`: deskriptor runtime per agen opsional. Gunakan `type: "acp"` dengan default `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) saat agen harus default ke sesi harness ACP. +- `id`: id agent stabil (wajib). +- `default`: saat beberapa diatur, yang pertama menang (peringatan dicatat). Jika tidak ada yang diatur, entri list pertama menjadi default. +- `model`: bentuk string hanya menimpa `primary`; bentuk objek `{ primary, fallbacks }` menimpa keduanya (`[]` menonaktifkan fallback global). Pekerjaan Cron yang hanya menimpa `primary` tetap mewarisi fallback default kecuali Anda menetapkan `fallbacks: []`. +- `params`: params stream per-agent yang digabungkan di atas entri model yang dipilih di `agents.defaults.models`. Gunakan ini untuk override khusus agent seperti `cacheRetention`, `temperature`, atau `maxTokens` tanpa menduplikasi seluruh katalog model. +- `skills`: allowlist skill per-agent opsional. Jika dihilangkan, agent mewarisi `agents.defaults.skills` saat diatur; daftar eksplisit menggantikan default alih-alih digabungkan, dan `[]` berarti tanpa Skills. +- `thinkingDefault`: override level thinking default per-agent opsional (`off | minimal | low | medium | high | xhigh | adaptive | max`). Menimpa `agents.defaults.thinkingDefault` untuk agent ini saat tidak ada override per-pesan atau sesi. +- `reasoningDefault`: override visibilitas reasoning default per-agent opsional (`on | off | stream`). Berlaku saat tidak ada override reasoning per-pesan atau sesi. +- `fastModeDefault`: default fast mode per-agent opsional (`true | false`). Berlaku saat tidak ada override fast-mode per-pesan atau sesi. +- `embeddedHarness`: override kebijakan harness tingkat rendah per-agent opsional. Gunakan `{ runtime: "codex", fallback: "none" }` agar satu agent khusus Codex sementara agent lain tetap memakai fallback PI default. +- `runtime`: deskriptor runtime per-agent opsional. Gunakan `type: "acp"` dengan default `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) saat agent harus default ke sesi harness ACP. - `identity.avatar`: path relatif workspace, URL `http(s)`, atau URI `data:`. - `identity` menurunkan default: `ackReaction` dari `emoji`, `mentionPatterns` dari `name`/`emoji`. -- `subagents.allowAgents`: allowlist ID agen untuk `sessions_spawn` (`["*"]` = apa pun; default: hanya agen yang sama). -- Guard pewarisan sandbox: jika sesi peminta berada dalam sandbox, `sessions_spawn` menolak target yang akan berjalan tanpa sandbox. +- `subagents.allowAgents`: allowlist id agent untuk `sessions_spawn` (`["*"]` = apa saja; default: hanya agent yang sama). +- Guard pewarisan sandbox: jika sesi peminta tersandbox, `sessions_spawn` menolak target yang akan berjalan tanpa sandbox. - `subagents.requireAgentId`: saat true, blokir panggilan `sessions_spawn` yang menghilangkan `agentId` (memaksa pemilihan profil eksplisit; default: false). --- -## Perutean multi-agen +## Routing multi-agent -Jalankan beberapa agen terisolasi di dalam satu Gateway. Lihat [Multi-Agent](/id/concepts/multi-agent). +Jalankan beberapa agent terisolasi di dalam satu Gateway. Lihat [Multi-Agent](/id/concepts/multi-agent). ```json5 { @@ -1829,29 +1819,29 @@ Jalankan beberapa agen terisolasi di dalam satu Gateway. Lihat [Multi-Agent](/id } ``` -### Field kecocokan binding +### Field pencocokan binding -- `type` (opsional): `route` untuk perutean normal (jika type tidak ada, default ke route), `acp` untuk binding percakapan ACP persisten. +- `type` (opsional): `route` untuk routing normal (type yang hilang default ke route), `acp` untuk binding percakapan ACP persisten. - `match.channel` (wajib) -- `match.accountId` (opsional; `*` = akun apa pun; dihilangkan = akun default) +- `match.accountId` (opsional; `*` = akun apa saja; dihilangkan = akun default) - `match.peer` (opsional; `{ kind: direct|group|channel, id }`) - `match.guildId` / `match.teamId` (opsional; khusus channel) -- `acp` (opsional; hanya untuk `type: "acp"`): `{ mode, label, cwd, backend }` +- `acp` (opsional; hanya untuk entri `type: "acp"`): `{ mode, label, cwd, backend }` -**Urutan kecocokan deterministik:** +**Urutan pencocokan deterministik:** 1. `match.peer` 2. `match.guildId` 3. `match.teamId` 4. `match.accountId` (persis, tanpa peer/guild/team) 5. `match.accountId: "*"` (seluruh channel) -6. Agen default +6. Agent default -Dalam setiap tingkat, entri `bindings` pertama yang cocok menang. +Dalam setiap tingkat, entri `bindings` pertama yang cocok akan menang. Untuk entri `type: "acp"`, OpenClaw me-resolve berdasarkan identitas percakapan persis (`match.channel` + akun + `match.peer.id`) dan tidak menggunakan urutan tingkat binding route di atas. -### Profil akses per agen +### Profil akses per-agent @@ -1871,7 +1861,7 @@ Untuk entri `type: "acp"`, OpenClaw me-resolve berdasarkan identitas percakapan - + ```json5 { @@ -1900,7 +1890,7 @@ Untuk entri `type: "acp"`, OpenClaw me-resolve berdasarkan identitas percakapan - + ```json5 { @@ -1979,15 +1969,15 @@ Lihat [Multi-Agent Sandbox & Tools](/id/tools/multi-agent-sandbox-tools) untuk d maxEntries: 500, rotateBytes: "10mb", resetArchiveRetention: "30d", // durasi atau false - maxDiskBytes: "500mb", // anggaran keras opsional - highWaterBytes: "400mb", // target cleanup opsional + maxDiskBytes: "500mb", // hard budget opsional + highWaterBytes: "400mb", // target pembersihan opsional }, threadBindings: { enabled: true, idleHours: 24, // default auto-unfocus karena tidak aktif dalam jam (`0` menonaktifkan) maxAgeHours: 0, // default usia maksimum keras dalam jam (`0` menonaktifkan) }, - mainKey: "main", // warisan (runtime selalu menggunakan "main") + mainKey: "main", // lama (runtime selalu menggunakan "main") agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -2000,34 +1990,34 @@ Lihat [Multi-Agent Sandbox & Tools](/id/tools/multi-agent-sandbox-tools) untuk d - **`scope`**: strategi pengelompokan sesi dasar untuk konteks chat grup. - - `per-sender` (default): setiap pengirim mendapat sesi terisolasi dalam konteks channel. - - `global`: semua peserta dalam konteks channel berbagi satu sesi (gunakan hanya bila konteks bersama memang diinginkan). + - `per-sender` (default): setiap pengirim mendapatkan sesi terisolasi dalam konteks channel. + - `global`: semua peserta dalam konteks channel berbagi satu sesi (gunakan hanya saat konteks bersama memang diinginkan). - **`dmScope`**: cara DM dikelompokkan. - `main`: semua DM berbagi sesi utama. - - `per-peer`: isolasi berdasarkan id pengirim lintas channel. - - `per-channel-peer`: isolasi per channel + pengirim (disarankan untuk inbox multi-pengguna). - - `per-account-channel-peer`: isolasi per akun + channel + pengirim (disarankan untuk multi-akun). -- **`identityLinks`**: petakan id kanonis ke peer berawalan provider untuk berbagi sesi lintas channel. -- **`reset`**: kebijakan reset utama. `daily` mereset pada `atHour` waktu lokal; `idle` mereset setelah `idleMinutes`. Jika keduanya dikonfigurasi, yang kedaluwarsa lebih dulu yang berlaku. + - `per-peer`: diisolasi berdasarkan id pengirim lintas channel. + - `per-channel-peer`: diisolasi per channel + pengirim (disarankan untuk inbox multi-pengguna). + - `per-account-channel-peer`: diisolasi per akun + channel + pengirim (disarankan untuk multi-akun). +- **`identityLinks`**: memetakan id kanonis ke peer berawalan provider untuk berbagi sesi lintas channel. +- **`reset`**: kebijakan reset utama. `daily` mereset pada `atHour` waktu lokal; `idle` mereset setelah `idleMinutes`. Saat keduanya dikonfigurasi, yang lebih dulu kedaluwarsa akan menang. - **`resetByType`**: override per tipe (`direct`, `group`, `thread`). `dm` lama diterima sebagai alias untuk `direct`. -- **`parentForkMaxTokens`**: `totalTokens` sesi induk maksimum yang diizinkan saat membuat sesi thread hasil fork (default `100000`). +- **`parentForkMaxTokens`**: jumlah maksimum `totalTokens` sesi induk yang diizinkan saat membuat sesi thread bercabang (default `100000`). - Jika `totalTokens` induk di atas nilai ini, OpenClaw memulai sesi thread baru alih-alih mewarisi riwayat transkrip induk. - - Atur `0` untuk menonaktifkan guard ini dan selalu mengizinkan fork dari induk. + - Atur `0` untuk menonaktifkan guard ini dan selalu mengizinkan forking induk. - **`mainKey`**: field lama. Runtime selalu menggunakan `"main"` untuk bucket chat langsung utama. -- **`agentToAgent.maxPingPongTurns`**: jumlah maksimum turn balasan balik antar agen selama pertukaran agen-ke-agen (integer, rentang: `0`–`5`). `0` menonaktifkan rantai ping-pong. -- **`sendPolicy`**: cocokkan berdasarkan `channel`, `chatType` (`direct|group|channel`, dengan alias lama `dm`), `keyPrefix`, atau `rawKeyPrefix`. Penolakan pertama yang cocok menang. -- **`maintenance`**: kontrol cleanup + retensi penyimpanan sesi. - - `mode`: `warn` hanya mengeluarkan peringatan; `enforce` menerapkan cleanup. - - `pruneAfter`: batas usia untuk entri basi (default `30d`). +- **`agentToAgent.maxPingPongTurns`**: jumlah maksimum giliran balas-balik ant agent selama pertukaran agent-ke-agent (bilangan bulat, rentang: `0`–`5`). `0` menonaktifkan rantai ping-pong. +- **`sendPolicy`**: cocokkan berdasarkan `channel`, `chatType` (`direct|group|channel`, dengan alias lama `dm`), `keyPrefix`, atau `rawKeyPrefix`. Deny pertama yang cocok akan menang. +- **`maintenance`**: kontrol pembersihan + retensi penyimpanan sesi. + - `mode`: `warn` hanya mengeluarkan peringatan; `enforce` menerapkan pembersihan. + - `pruneAfter`: batas usia untuk entri usang (default `30d`). - `maxEntries`: jumlah maksimum entri dalam `sessions.json` (default `500`). - `rotateBytes`: rotasi `sessions.json` saat melebihi ukuran ini (default `10mb`). - `resetArchiveRetention`: retensi untuk arsip transkrip `*.reset.`. Default mengikuti `pruneAfter`; atur `false` untuk menonaktifkan. - - `maxDiskBytes`: anggaran disk direktori sesi opsional. Dalam mode `warn` akan mencatat peringatan; dalam mode `enforce` akan lebih dulu menghapus artefak/sesi tertua. - - `highWaterBytes`: target opsional setelah cleanup anggaran. Default ke `80%` dari `maxDiskBytes`. + - `maxDiskBytes`: anggaran disk direktori sesi opsional. Dalam mode `warn`, ini mencatat peringatan; dalam mode `enforce`, ini menghapus artefak/sesi tertua terlebih dahulu. + - `highWaterBytes`: target opsional setelah pembersihan anggaran. Default ke `80%` dari `maxDiskBytes`. - **`threadBindings`**: default global untuk fitur sesi terikat thread. - - `enabled`: sakelar default utama (provider dapat mengoverride; Discord menggunakan `channels.discord.threadBindings.enabled`) - - `idleHours`: auto-unfocus default karena tidak aktif dalam jam (`0` menonaktifkan; provider dapat mengoverride) - - `maxAgeHours`: usia maksimum keras default dalam jam (`0` menonaktifkan; provider dapat mengoverride) + - `enabled`: sakelar default utama (provider dapat menimpa; Discord menggunakan `channels.discord.threadBindings.enabled`) + - `idleHours`: default auto-unfocus karena tidak aktif dalam jam (`0` menonaktifkan; provider dapat menimpa) + - `maxAgeHours`: default usia maksimum keras dalam jam (`0` menonaktifkan; provider dapat menimpa) @@ -2063,7 +2053,7 @@ Lihat [Multi-Agent Sandbox & Tools](/id/tools/multi-agent-sandbox-tools) untuk d } ``` -### Awalan respons +### Prefiks respons Override per channel/akun: `channels..responsePrefix`, `channels..accounts..responsePrefix`. @@ -2071,30 +2061,30 @@ Resolusi (yang paling spesifik menang): akun → channel → global. `""` menona **Variabel template:** -| Variable | Deskripsi | Example | -| ----------------- | ----------------------- | --------------------------- | -| `{model}` | Nama model singkat | `claude-opus-4-6` | -| `{modelFull}` | Identifier model lengkap | `anthropic/claude-opus-4-6` | -| `{provider}` | Nama provider | `anthropic` | -| `{thinkingLevel}` | Level thinking saat ini | `high`, `low`, `off` | -| `{identity.name}` | Nama identitas agen | (sama seperti `"auto"`) | +| Variabel | Deskripsi | Contoh | +| ----------------- | ---------------------- | --------------------------- | +| `{model}` | Nama model singkat | `claude-opus-4-6` | +| `{modelFull}` | Identifier model penuh | `anthropic/claude-opus-4-6` | +| `{provider}` | Nama provider | `anthropic` | +| `{thinkingLevel}` | Level thinking saat ini | `high`, `low`, `off` | +| `{identity.name}` | Nama identitas agent | (sama seperti `"auto"`) | Variabel tidak peka huruf besar/kecil. `{think}` adalah alias untuk `{thinkingLevel}`. -### Reaksi ack +### Ack reaction -- Default ke `identity.emoji` agen aktif, jika tidak ada maka `"👀"`. Atur `""` untuk menonaktifkan. +- Default ke `identity.emoji` milik agent aktif, jika tidak `"👀"`. Atur `""` untuk menonaktifkan. - Override per channel: `channels..ackReaction`, `channels..accounts..ackReaction`. -- Urutan resolusi: akun → channel → `messages.ackReaction` → fallback identitas. +- Urutan resolusi: akun → channel → `messages.ackReaction` → fallback identity. - Cakupan: `group-mentions` (default), `group-all`, `direct`, `all`. - `removeAckAfterReply`: menghapus ack setelah balasan di Slack, Discord, dan Telegram. -- `messages.statusReactions.enabled`: mengaktifkan reaksi status siklus hidup di Slack, Discord, dan Telegram. - Di Slack dan Discord, jika tidak diatur maka reaksi status tetap aktif saat reaksi ack aktif. - Di Telegram, atur secara eksplisit ke `true` untuk mengaktifkan reaksi status siklus hidup. +- `messages.statusReactions.enabled`: mengaktifkan reaction status lifecycle di Slack, Discord, dan Telegram. + Di Slack dan Discord, jika tidak diatur maka status reaction tetap aktif saat ack reaction aktif. + Di Telegram, atur secara eksplisit ke `true` untuk mengaktifkan status reaction lifecycle. ### Debounce masuk -Mengelompokkan pesan cepat yang hanya berisi teks dari pengirim yang sama menjadi satu turn agen. Media/lampiran langsung melakukan flush. Perintah kontrol melewati debounce. +Mengelompokkan pesan cepat hanya teks dari pengirim yang sama menjadi satu giliran agent. Media/lampiran langsung melakukan flush. Perintah kontrol melewati debounce. ### TTS (text-to-speech) @@ -2137,11 +2127,11 @@ Mengelompokkan pesan cepat yang hanya berisi teks dari pengirim yang sama menjad } ``` -- `auto` mengontrol mode auto-TTS default: `off`, `always`, `inbound`, atau `tagged`. `/tts on|off` dapat mengoverride preferensi lokal, dan `/tts status` menampilkan status efektif. -- `summaryModel` mengoverride `agents.defaults.model.primary` untuk ringkasan otomatis. +- `auto` mengontrol mode auto-TTS default: `off`, `always`, `inbound`, atau `tagged`. `/tts on|off` dapat menimpa preferensi lokal, dan `/tts status` menampilkan status efektif. +- `summaryModel` menimpa `agents.defaults.model.primary` untuk ringkasan otomatis. - `modelOverrides` aktif secara default; `modelOverrides.allowProvider` default ke `false` (opt-in). -- API key fallback ke `ELEVENLABS_API_KEY`/`XI_API_KEY` dan `OPENAI_API_KEY`. -- `openai.baseUrl` mengoverride endpoint TTS OpenAI. Urutan resolusi adalah config, lalu `OPENAI_TTS_BASE_URL`, lalu `https://api.openai.com/v1`. +- API key menggunakan fallback ke `ELEVENLABS_API_KEY`/`XI_API_KEY` dan `OPENAI_API_KEY`. +- `openai.baseUrl` menimpa endpoint OpenAI TTS. Urutan resolusi adalah config, lalu `OPENAI_TTS_BASE_URL`, lalu `https://api.openai.com/v1`. - Saat `openai.baseUrl` menunjuk ke endpoint non-OpenAI, OpenClaw memperlakukannya sebagai server TTS yang kompatibel dengan OpenAI dan melonggarkan validasi model/voice. --- @@ -2172,51 +2162,51 @@ Default untuk mode Talk (macOS/iOS/Android). } ``` -- `talk.provider` harus cocok dengan key di `talk.providers` saat beberapa provider Talk dikonfigurasi. -- Key Talk datar lama (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) hanya untuk kompatibilitas dan dimigrasikan otomatis ke `talk.providers.`. -- ID voice fallback ke `ELEVENLABS_VOICE_ID` atau `SAG_VOICE_ID`. +- `talk.provider` harus cocok dengan kunci di `talk.providers` saat beberapa provider Talk dikonfigurasi. +- Kunci Talk datar lama (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) hanya untuk kompatibilitas dan dimigrasikan otomatis ke `talk.providers.`. +- Voice ID menggunakan fallback ke `ELEVENLABS_VOICE_ID` atau `SAG_VOICE_ID`. - `providers.*.apiKey` menerima string plaintext atau objek SecretRef. - Fallback `ELEVENLABS_API_KEY` hanya berlaku saat tidak ada API key Talk yang dikonfigurasi. -- `providers.*.voiceAliases` memungkinkan directive Talk menggunakan nama yang ramah. +- `providers.*.voiceAliases` memungkinkan direktif Talk menggunakan nama yang ramah. - `silenceTimeoutMs` mengontrol berapa lama mode Talk menunggu setelah pengguna diam sebelum mengirim transkrip. Jika tidak diatur, jendela jeda default platform tetap digunakan (`700 ms di macOS dan Android, 900 ms di iOS`). --- -## Alat +## Tools -### Profil alat +### Profil tool `tools.profile` menetapkan allowlist dasar sebelum `tools.allow`/`tools.deny`: -Onboarding lokal secara default mengatur config lokal baru ke `tools.profile: "coding"` saat tidak diatur (profil eksplisit yang sudah ada dipertahankan). +Onboarding lokal membuat default konfigurasi lokal baru ke `tools.profile: "coding"` saat tidak diatur (profil eksplisit yang sudah ada dipertahankan). -| Profile | Mencakup | -| ----------- | ------------------------------------------------------------------------------------------------------------------------------ | -| `minimal` | hanya `session_status` | +| Profil | Mencakup | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `minimal` | hanya `session_status` | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | -| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `full` | Tanpa pembatasan (sama seperti tidak diatur) | +| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | +| `full` | Tidak ada pembatasan (sama seperti tidak diatur) | -### Grup alat +### Grup tool -| Group | Alat | -| ------------------ | ---------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`, `process`, `code_execution` (`bash` diterima sebagai alias untuk `exec`) | -| `group:fs` | `read`, `write`, `edit`, `apply_patch` | +| Grup | Tools | +| ------------------ | ----------------------------------------------------------------------------------------------------------------------- | +| `group:runtime` | `exec`, `process`, `code_execution` (`bash` diterima sebagai alias untuk `exec`) | +| `group:fs` | `read`, `write`, `edit`, `apply_patch` | | `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | -| `group:memory` | `memory_search`, `memory_get` | -| `group:web` | `web_search`, `x_search`, `web_fetch` | -| `group:ui` | `browser`, `canvas` | -| `group:automation` | `cron`, `gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | Semua alat bawaan (tidak termasuk Plugin provider) | +| `group:memory` | `memory_search`, `memory_get` | +| `group:web` | `web_search`, `x_search`, `web_fetch` | +| `group:ui` | `browser`, `canvas` | +| `group:automation` | `cron`, `gateway` | +| `group:messaging` | `message` | +| `group:nodes` | `nodes` | +| `group:agents` | `agents_list` | +| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | +| `group:openclaw` | Semua tool bawaan (tidak termasuk Plugin provider) | ### `tools.allow` / `tools.deny` -Kebijakan allow/deny alat global (deny menang). Tidak peka huruf besar/kecil, mendukung wildcard `*`. Diterapkan bahkan saat sandbox Docker nonaktif. +Kebijakan allow/deny tool global (deny menang). Tidak peka huruf besar/kecil, mendukung wildcard `*`. Diterapkan bahkan saat sandbox Docker nonaktif. ```json5 { @@ -2226,7 +2216,7 @@ Kebijakan allow/deny alat global (deny menang). Tidak peka huruf besar/kecil, me ### `tools.byProvider` -Membatasi alat lebih lanjut untuk provider atau model tertentu. Urutan: profil dasar → profil provider → allow/deny. +Membatasi tool lebih lanjut untuk provider atau model tertentu. Urutan: profil dasar → profil provider → allow/deny. ```json5 { @@ -2258,9 +2248,9 @@ Mengontrol akses exec elevated di luar sandbox: } ``` -- Override per agen (`agents.list[].tools.elevated`) hanya dapat membatasi lebih lanjut. -- `/elevated on|off|ask|full` menyimpan status per sesi; directive inline berlaku untuk satu pesan. -- `exec` elevated melewati sandboxing dan menggunakan jalur escape yang dikonfigurasi (`gateway` secara default, atau `node` saat target exec adalah `node`). +- Override per-agent (`agents.list[].tools.elevated`) hanya dapat membatasi lebih lanjut. +- `/elevated on|off|ask|full` menyimpan status per sesi; direktif inline berlaku untuk satu pesan. +- `exec` elevated melewati sandboxing dan menggunakan path escape yang dikonfigurasi (`gateway` secara default, atau `node` saat target exec adalah `node`). ### `tools.exec` @@ -2284,8 +2274,8 @@ Mengontrol akses exec elevated di luar sandbox: ### `tools.loopDetection` -Pemeriksaan keamanan loop alat **dinonaktifkan secara default**. Atur `enabled: true` untuk mengaktifkan deteksi. -Pengaturan dapat didefinisikan secara global di `tools.loopDetection` dan dioverride per agen di `agents.list[].tools.loopDetection`. +Pemeriksaan keamanan loop tool **dinonaktifkan secara default**. Atur `enabled: true` untuk mengaktifkan deteksi. +Pengaturan dapat didefinisikan secara global di `tools.loopDetection` dan ditimpa per-agent di `agents.list[].tools.loopDetection`. ```json5 { @@ -2306,13 +2296,13 @@ Pengaturan dapat didefinisikan secara global di `tools.loopDetection` dan diover } ``` -- `historySize`: riwayat maksimum pemanggilan alat yang disimpan untuk analisis loop. +- `historySize`: jumlah maksimum riwayat pemanggilan tool yang disimpan untuk analisis loop. - `warningThreshold`: ambang pola berulang tanpa progres untuk peringatan. - `criticalThreshold`: ambang berulang yang lebih tinggi untuk memblokir loop kritis. - `globalCircuitBreakerThreshold`: ambang hard stop untuk proses tanpa progres apa pun. -- `detectors.genericRepeat`: peringatkan untuk pemanggilan alat yang sama dengan argumen yang sama berulang-ulang. -- `detectors.knownPollNoProgress`: peringatkan/blokir alat poll yang dikenal (`process.poll`, `command_status`, dll.). -- `detectors.pingPong`: peringatkan/blokir pola pasangan bolak-balik tanpa progres. +- `detectors.genericRepeat`: beri peringatan pada pemanggilan berulang tool yang sama/argumen yang sama. +- `detectors.knownPollNoProgress`: beri peringatan/blokir pada tool polling yang dikenal (`process.poll`, `command_status`, dll.). +- `detectors.pingPong`: beri peringatan/blokir pada pola pasangan bolak-balik tanpa progres. - Jika `warningThreshold >= criticalThreshold` atau `criticalThreshold >= globalCircuitBreakerThreshold`, validasi gagal. ### `tools.web` @@ -2355,7 +2345,7 @@ Mengonfigurasi pemahaman media masuk (gambar/audio/video): media: { concurrency: 2, asyncCompletion: { - directSend: false, // opt-in: kirim musik/video async yang selesai langsung ke channel + directSend: false, // opt-in: kirim music/video async yang sudah selesai langsung ke channel }, audio: { enabled: true, @@ -2390,21 +2380,21 @@ Mengonfigurasi pemahaman media masuk (gambar/audio/video): **Entri CLI** (`type: "cli"`): - `command`: executable yang akan dijalankan -- `args`: argumen bertemplate (mendukung `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, dll.) +- `args`: arg templated (mendukung `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, dll.) **Field umum:** - `capabilities`: daftar opsional (`image`, `audio`, `video`). Default: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. - `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: override per entri. -- Jika gagal, fallback ke entri berikutnya. +- Kegagalan akan menggunakan fallback ke entri berikutnya. -Auth provider mengikuti urutan standar: `auth-profiles.json` → env vars → `models.providers.*.apiKey`. +Autentikasi provider mengikuti urutan standar: `auth-profiles.json` → env vars → `models.providers.*.apiKey`. **Field penyelesaian async:** - `asyncCompletion.directSend`: saat `true`, tugas `music_generate` - dan `video_generate` async yang selesai mencoba pengiriman channel langsung terlebih dahulu. Default: `false` - (jalur wake/model-delivery sesi peminta lama). + dan `video_generate` async yang sudah selesai mencoba pengiriman channel langsung terlebih dahulu. Default: `false` + (jalur lama requester-session wake/model-delivery). @@ -2423,9 +2413,9 @@ Auth provider mengikuti urutan standar: `auth-profiles.json` → env vars → `m ### `tools.sessions` -Mengontrol sesi mana yang dapat ditargetkan oleh alat sesi (`sessions_list`, `sessions_history`, `sessions_send`). +Mengontrol sesi mana yang dapat ditargetkan oleh tool sesi (`sessions_list`, `sessions_history`, `sessions_send`). -Default: `tree` (sesi saat ini + sesi yang dihasilkan darinya, seperti subagen). +Default: `tree` (sesi saat ini + sesi yang di-spawn olehnya, seperti subagent). ```json5 { @@ -2440,11 +2430,11 @@ Default: `tree` (sesi saat ini + sesi yang dihasilkan darinya, seperti subagen). Catatan: -- `self`: hanya key sesi saat ini. -- `tree`: sesi saat ini + sesi yang dihasilkan oleh sesi saat ini (subagen). -- `agent`: sesi apa pun milik ID agen saat ini (dapat mencakup pengguna lain jika Anda menjalankan sesi per-pengirim di bawah ID agen yang sama). -- `all`: sesi apa pun. Penargetan lintas agen tetap memerlukan `tools.agentToAgent`. -- Clamp sandbox: saat sesi saat ini berada dalam sandbox dan `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, visibilitas dipaksa ke `tree` meskipun `tools.sessions.visibility="all"`. +- `self`: hanya kunci sesi saat ini. +- `tree`: sesi saat ini + sesi yang di-spawn oleh sesi saat ini (subagent). +- `agent`: sesi apa pun yang dimiliki id agent saat ini (dapat mencakup pengguna lain jika Anda menjalankan sesi per-pengirim di bawah id agent yang sama). +- `all`: sesi apa pun. Penargetan lintas agent tetap memerlukan `tools.agentToAgent`. +- Clamp sandbox: saat sesi saat ini tersandbox dan `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, visibilitas dipaksa menjadi `tree` bahkan jika `tools.sessions.visibility="all"`. ### `tools.sessions_spawn` @@ -2456,7 +2446,7 @@ Mengontrol dukungan lampiran inline untuk `sessions_spawn`. sessions_spawn: { attachments: { enabled: false, // opt-in: atur true untuk mengizinkan lampiran file inline - maxTotalBytes: 5242880, // total 5 MB untuk semua file + maxTotalBytes: 5242880, // total 5 MB di seluruh file maxFiles: 50, maxFileBytes: 1048576, // 1 MB per file retainOnSessionKeep: false, // pertahankan lampiran saat cleanup="keep" @@ -2469,15 +2459,15 @@ Mengontrol dukungan lampiran inline untuk `sessions_spawn`. Catatan: - Lampiran hanya didukung untuk `runtime: "subagent"`. Runtime ACP menolaknya. -- File dimaterialisasikan ke workspace child di `.openclaw/attachments//` dengan `.manifest.json`. +- File diwujudkan ke dalam workspace anak di `.openclaw/attachments//` dengan `.manifest.json`. - Konten lampiran otomatis disunting dari persistensi transkrip. -- Input Base64 divalidasi dengan pemeriksaan alfabet/padding yang ketat dan guard ukuran pra-decode. +- Input Base64 divalidasi dengan pemeriksaan alfabet/padding yang ketat dan guard ukuran sebelum decode. - Izin file adalah `0700` untuk direktori dan `0600` untuk file. -- Cleanup mengikuti kebijakan `cleanup`: `delete` selalu menghapus lampiran; `keep` mempertahankannya hanya saat `retainOnSessionKeep: true`. +- Pembersihan mengikuti kebijakan `cleanup`: `delete` selalu menghapus lampiran; `keep` hanya mempertahankannya saat `retainOnSessionKeep: true`. ### `tools.experimental` -Flag alat bawaan eksperimental. Default nonaktif kecuali aturan auto-enable GPT-5 agentik-ketat berlaku. +Flag tool bawaan eksperimental. Default nonaktif kecuali berlaku aturan auto-enable GPT-5 strict-agentic. ```json5 { @@ -2491,9 +2481,9 @@ Flag alat bawaan eksperimental. Default nonaktif kecuali aturan auto-enable GPT- Catatan: -- `planTool`: mengaktifkan alat terstruktur `update_plan` untuk pelacakan pekerjaan multi-langkah yang tidak sepele. -- Default: `false` kecuali `agents.defaults.embeddedPi.executionContract` (atau override per agen) diatur ke `"strict-agentic"` untuk proses GPT-5-family OpenAI atau OpenAI Codex. Atur `true` untuk memaksa alat aktif di luar cakupan itu, atau `false` agar tetap nonaktif bahkan untuk proses GPT-5 agentik-ketat. -- Saat diaktifkan, system prompt juga menambahkan panduan penggunaan agar model hanya memakainya untuk pekerjaan yang substansial dan menjaga maksimal satu langkah `in_progress`. +- `planTool`: mengaktifkan tool terstruktur `update_plan` untuk pelacakan pekerjaan multi-langkah yang tidak sepele. +- Default: `false` kecuali `agents.defaults.embeddedPi.executionContract` (atau override per-agent) diatur ke `"strict-agentic"` untuk proses keluarga GPT-5 OpenAI atau OpenAI Codex. Atur `true` untuk memaksa tool aktif di luar cakupan itu, atau `false` untuk tetap menonaktifkannya bahkan untuk proses GPT-5 strict-agentic. +- Saat diaktifkan, system prompt juga menambahkan panduan penggunaan agar model hanya memakainya untuk pekerjaan yang substansial dan menjaga paling banyak satu langkah `in_progress`. ### `agents.defaults.subagents` @@ -2513,10 +2503,10 @@ Catatan: } ``` -- `model`: model default untuk subagen yang dihasilkan. Jika dihilangkan, subagen mewarisi model pemanggil. -- `allowAgents`: allowlist default ID agen target untuk `sessions_spawn` saat agen peminta tidak mengatur `subagents.allowAgents` sendiri (`["*"]` = apa saja; default: hanya agen yang sama). -- `runTimeoutSeconds`: timeout default (detik) untuk `sessions_spawn` saat pemanggilan alat menghilangkan `runTimeoutSeconds`. `0` berarti tanpa timeout. -- Kebijakan alat per subagen: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. +- `model`: model default untuk sub-agent yang di-spawn. Jika dihilangkan, sub-agent mewarisi model pemanggil. +- `allowAgents`: allowlist default id agent target untuk `sessions_spawn` saat agent peminta tidak menetapkan `subagents.allowAgents` sendiri (`["*"]` = apa saja; default: hanya agent yang sama). +- `runTimeoutSeconds`: timeout default (detik) untuk `sessions_spawn` saat pemanggilan tool menghilangkan `runTimeoutSeconds`. `0` berarti tanpa timeout. +- Kebijakan tool per-subagent: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- @@ -2551,48 +2541,48 @@ OpenClaw menggunakan katalog model bawaan. Tambahkan provider kustom melalui `mo } ``` -- Gunakan `authHeader: true` + `headers` untuk kebutuhan auth kustom. -- Override root config agen dengan `OPENCLAW_AGENT_DIR` (atau `PI_CODING_AGENT_DIR`, alias variabel lingkungan lama). -- Prioritas penggabungan untuk ID provider yang cocok: - - Nilai `baseUrl` `models.json` agen yang tidak kosong menang. - - Nilai `apiKey` agen yang tidak kosong menang hanya saat provider itu tidak dikelola SecretRef dalam konteks config/auth-profile saat ini. - - Nilai `apiKey` provider yang dikelola SecretRef disegarkan dari marker sumber (`ENV_VAR_NAME` untuk ref env, `secretref-managed` untuk ref file/exec) alih-alih menyimpan secret hasil resolve. - - Nilai header provider yang dikelola SecretRef disegarkan dari marker sumber (`secretref-env:ENV_VAR_NAME` untuk ref env, `secretref-managed` untuk ref file/exec). - - `apiKey`/`baseUrl` agen yang kosong atau tidak ada fallback ke `models.providers` dalam config. +- Gunakan `authHeader: true` + `headers` untuk kebutuhan autentikasi kustom. +- Timpa root config agent dengan `OPENCLAW_AGENT_DIR` (atau `PI_CODING_AGENT_DIR`, alias variabel lingkungan lama). +- Prioritas penggabungan untuk id provider yang cocok: + - Nilai `baseUrl` `models.json` agent yang tidak kosong menang. + - Nilai `apiKey` agent yang tidak kosong hanya menang saat provider tersebut tidak dikelola SecretRef dalam konteks config/auth-profile saat ini. + - Nilai `apiKey` provider yang dikelola SecretRef di-refresh dari penanda sumber (`ENV_VAR_NAME` untuk ref env, `secretref-managed` untuk ref file/exec) alih-alih menyimpan secret yang sudah di-resolve. + - Nilai header provider yang dikelola SecretRef di-refresh dari penanda sumber (`secretref-env:ENV_VAR_NAME` untuk ref env, `secretref-managed` untuk ref file/exec). + - `apiKey`/`baseUrl` agent yang kosong atau hilang menggunakan fallback ke `models.providers` di config. - `contextWindow`/`maxTokens` model yang cocok menggunakan nilai yang lebih tinggi antara config eksplisit dan nilai katalog implisit. - - `contextTokens` model yang cocok mempertahankan batas runtime eksplisit bila ada; gunakan ini untuk membatasi konteks efektif tanpa mengubah metadata model native. - - Gunakan `models.mode: "replace"` saat Anda ingin config menulis ulang sepenuhnya `models.json`. - - Persistensi marker bersifat source-authoritative: marker ditulis dari snapshot config sumber aktif (pra-resolve), bukan dari nilai secret runtime yang telah di-resolve. + - `contextTokens` model yang cocok mempertahankan batas runtime eksplisit saat ada; gunakan ini untuk membatasi konteks efektif tanpa mengubah metadata model native. + - Gunakan `models.mode: "replace"` saat Anda ingin config menulis ulang `models.json` sepenuhnya. + - Persistensi marker bersifat source-authoritative: marker ditulis dari snapshot config sumber aktif (pra-resolusi), bukan dari nilai secret runtime yang sudah di-resolve. ### Detail field provider - `models.mode`: perilaku katalog provider (`merge` atau `replace`). -- `models.providers`: peta provider kustom yang dikunci oleh id provider. +- `models.providers`: map provider kustom yang dikunci dengan id provider. - `models.providers.*.api`: adapter permintaan (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai`, dll). -- `models.providers.*.apiKey`: kredensial provider (lebih baik gunakan substitusi SecretRef/env). -- `models.providers.*.auth`: strategi auth (`api-key`, `token`, `oauth`, `aws-sdk`). -- `models.providers.*.injectNumCtxForOpenAICompat`: untuk Ollama + `openai-completions`, sisipkan `options.num_ctx` ke dalam permintaan (default: `true`). -- `models.providers.*.authHeader`: paksa transport kredensial di header `Authorization` saat diperlukan. +- `models.providers.*.apiKey`: kredensial provider (sebaiknya SecretRef/substitusi env). +- `models.providers.*.auth`: strategi autentikasi (`api-key`, `token`, `oauth`, `aws-sdk`). +- `models.providers.*.injectNumCtxForOpenAICompat`: untuk Ollama + `openai-completions`, suntikkan `options.num_ctx` ke dalam permintaan (default: `true`). +- `models.providers.*.authHeader`: paksa transport kredensial dalam header `Authorization` saat diperlukan. - `models.providers.*.baseUrl`: base URL API upstream. -- `models.providers.*.headers`: header statis tambahan untuk perutean proxy/tenant. +- `models.providers.*.headers`: header statis tambahan untuk routing proxy/tenant. - `models.providers.*.request`: override transport untuk permintaan HTTP model-provider. - - `request.headers`: header tambahan (digabung dengan default provider). Nilai menerima SecretRef. - - `request.auth`: override strategi auth. Mode: `"provider-default"` (gunakan auth bawaan provider), `"authorization-bearer"` (dengan `token`), `"header"` (dengan `headerName`, `value`, `prefix` opsional). + - `request.headers`: header tambahan (digabungkan dengan default provider). Nilai menerima SecretRef. + - `request.auth`: override strategi autentikasi. Mode: `"provider-default"` (gunakan auth bawaan provider), `"authorization-bearer"` (dengan `token`), `"header"` (dengan `headerName`, `value`, `prefix` opsional). - `request.proxy`: override proxy HTTP. Mode: `"env-proxy"` (gunakan env vars `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (dengan `url`). Kedua mode menerima sub-objek `tls` opsional. - `request.tls`: override TLS untuk koneksi langsung. Field: `ca`, `cert`, `key`, `passphrase` (semuanya menerima SecretRef), `serverName`, `insecureSkipVerify`. - - `request.allowPrivateNetwork`: saat `true`, izinkan HTTPS ke `baseUrl` ketika DNS me-resolve ke rentang privat, CGNAT, atau sejenisnya, melalui guard fetch HTTP provider (opt-in operator untuk endpoint OpenAI-compatible self-hosted tepercaya). WebSocket menggunakan `request` yang sama untuk header/TLS tetapi tidak menggunakan gate SSRF fetch itu. Default `false`. + - `request.allowPrivateNetwork`: saat `true`, izinkan HTTPS ke `baseUrl` saat DNS di-resolve ke rentang private, CGNAT, atau serupa, melalui guard fetch HTTP provider (opt-in operator untuk endpoint OpenAI-compatible self-hosted tepercaya). WebSocket menggunakan `request` yang sama untuk header/TLS tetapi tidak menggunakan gerbang SSRF fetch tersebut. Default `false`. - `models.providers.*.models`: entri katalog model provider eksplisit. -- `models.providers.*.models.*.contextWindow`: metadata jendela konteks model native. +- `models.providers.*.models.*.contextWindow`: metadata context window model native. - `models.providers.*.models.*.contextTokens`: batas konteks runtime opsional. Gunakan ini saat Anda menginginkan anggaran konteks efektif yang lebih kecil daripada `contextWindow` native model. -- `models.providers.*.models.*.compat.supportsDeveloperRole`: petunjuk kompatibilitas opsional. Untuk `api: "openai-completions"` dengan `baseUrl` non-native yang tidak kosong (host bukan `api.openai.com`), OpenClaw memaksa nilai ini menjadi `false` saat runtime. `baseUrl` kosong/tidak diatur mempertahankan perilaku OpenAI default. -- `models.providers.*.models.*.compat.requiresStringContent`: petunjuk kompatibilitas opsional untuk endpoint chat OpenAI-compatible yang hanya mendukung string. Saat `true`, OpenClaw meratakan array `messages[].content` teks murni menjadi string biasa sebelum mengirim permintaan. +- `models.providers.*.models.*.compat.supportsDeveloperRole`: petunjuk kompatibilitas opsional. Untuk `api: "openai-completions"` dengan `baseUrl` non-native yang tidak kosong (host bukan `api.openai.com`), OpenClaw memaksanya menjadi `false` saat runtime. `baseUrl` kosong/dihilangkan mempertahankan perilaku default OpenAI. +- `models.providers.*.models.*.compat.requiresStringContent`: petunjuk kompatibilitas opsional untuk endpoint chat OpenAI-compatible yang hanya mendukung string. Saat `true`, OpenClaw meratakan array `messages[].content` yang hanya berisi teks menjadi string biasa sebelum mengirim permintaan. - `plugins.entries.amazon-bedrock.config.discovery`: root pengaturan auto-discovery Bedrock. - `plugins.entries.amazon-bedrock.config.discovery.enabled`: aktifkan/nonaktifkan discovery implisit. - `plugins.entries.amazon-bedrock.config.discovery.region`: region AWS untuk discovery. - `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: filter provider-id opsional untuk discovery yang ditargetkan. - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: interval polling untuk refresh discovery. -- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: fallback jendela konteks untuk model yang ditemukan. -- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: fallback token output maksimum untuk model yang ditemukan. +- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: context window fallback untuk model yang ditemukan. +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: token output maksimum fallback untuk model yang ditemukan. ### Contoh provider @@ -2647,7 +2637,7 @@ Gunakan `cerebras/zai-glm-4.7` untuk Cerebras; `zai/glm-4.7` untuk Z.AI langsung } ``` -Atur `OPENCODE_API_KEY` (atau `OPENCODE_ZEN_API_KEY`). Gunakan referensi `opencode/...` untuk katalog Zen atau referensi `opencode-go/...` untuk katalog Go. Pintasan: `openclaw onboard --auth-choice opencode-zen` atau `openclaw onboard --auth-choice opencode-go`. +Tetapkan `OPENCODE_API_KEY` (atau `OPENCODE_ZEN_API_KEY`). Gunakan referensi `opencode/...` untuk katalog Zen atau referensi `opencode-go/...` untuk katalog Go. Pintasan: `openclaw onboard --auth-choice opencode-zen` atau `openclaw onboard --auth-choice opencode-go`. @@ -2664,7 +2654,7 @@ Atur `OPENCODE_API_KEY` (atau `OPENCODE_ZEN_API_KEY`). Gunakan referensi `openco } ``` -Atur `ZAI_API_KEY`. `z.ai/*` dan `z-ai/*` adalah alias yang diterima. Pintasan: `openclaw onboard --auth-choice zai-api-key`. +Tetapkan `ZAI_API_KEY`. `z.ai/*` dan `z-ai/*` diterima sebagai alias. Pintasan: `openclaw onboard --auth-choice zai-api-key`. - Endpoint umum: `https://api.z.ai/api/paas/v4` - Endpoint coding (default): `https://api.z.ai/api/coding/paas/v4` @@ -2710,8 +2700,8 @@ Atur `ZAI_API_KEY`. `z.ai/*` dan `z-ai/*` adalah alias yang diterima. Pintasan: Untuk endpoint China: `baseUrl: "https://api.moonshot.cn/v1"` atau `openclaw onboard --auth-choice moonshot-api-key-cn`. Endpoint Moonshot native mengiklankan kompatibilitas penggunaan streaming pada transport bersama -`openai-completions`, dan OpenClaw menguncikannya pada kapabilitas endpoint -alih-alih hanya pada id provider bawaan. +`openai-completions`, dan OpenClaw mendasarkan itu pada kapabilitas endpoint +bukan hanya id provider bawaan. @@ -2733,7 +2723,7 @@ Kompatibel dengan Anthropic, provider bawaan. Pintasan: `openclaw onboard --auth - + ```json5 { @@ -2768,7 +2758,7 @@ Kompatibel dengan Anthropic, provider bawaan. Pintasan: `openclaw onboard --auth } ``` -Base URL sebaiknya tidak menyertakan `/v1` (klien Anthropic menambahkannya). Pintasan: `openclaw onboard --auth-choice synthetic-api-key`. +Base URL harus menghilangkan `/v1` (klien Anthropic akan menambahkannya). Pintasan: `openclaw onboard --auth-choice synthetic-api-key`. @@ -2808,12 +2798,12 @@ Base URL sebaiknya tidak menyertakan `/v1` (klien Anthropic menambahkannya). Pin } ``` -Atur `MINIMAX_API_KEY`. Pintasan: +Tetapkan `MINIMAX_API_KEY`. Pintasan: `openclaw onboard --auth-choice minimax-global-api` atau `openclaw onboard --auth-choice minimax-cn-api`. -Katalog model default hanya M2.7. -Pada jalur streaming Anthropic-compatible, OpenClaw menonaktifkan thinking MiniMax -secara default kecuali Anda mengatur `thinking` sendiri secara eksplisit. `/fast on` atau +Katalog model default hanya ke M2.7. +Pada jalur streaming yang kompatibel dengan Anthropic, OpenClaw menonaktifkan thinking MiniMax +secara default kecuali Anda secara eksplisit menetapkan `thinking` sendiri. `/fast on` atau `params.fastMode: true` menulis ulang `MiniMax-M2.7` menjadi `MiniMax-M2.7-highspeed`. @@ -2821,7 +2811,7 @@ secara default kecuali Anda mengatur `thinking` sendiri secara eksplisit. `/fast -Lihat [Model Lokal](/id/gateway/local-models). Singkatnya: jalankan model lokal besar melalui LM Studio Responses API pada perangkat keras yang serius; tetap gabungkan model hosted untuk fallback. +Lihat [Local Models](/id/gateway/local-models). Singkatnya: jalankan model lokal besar melalui API LM Studio Responses pada hardware serius; pertahankan model hosted tetap digabungkan untuk fallback. @@ -2852,13 +2842,13 @@ Lihat [Model Lokal](/id/gateway/local-models). Singkatnya: jalankan model lokal } ``` -- `allowBundled`: allowlist opsional hanya untuk skill bawaan bundel (skill terkelola/workspace tidak terpengaruh). +- `allowBundled`: allowlist opsional hanya untuk Skills bundled (Skills terkelola/workspace tidak terpengaruh). - `load.extraDirs`: root skill bersama tambahan (prioritas terendah). -- `install.preferBrew`: saat true, utamakan installer Homebrew ketika `brew` - tersedia sebelum fallback ke jenis installer lain. -- `install.nodeManager`: preferensi installer node untuk spesifikasi `metadata.openclaw.install` +- `install.preferBrew`: saat true, utamakan installer Homebrew saat `brew` + tersedia sebelum menggunakan fallback ke jenis installer lain. +- `install.nodeManager`: preferensi installer node untuk spec `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). -- `entries..enabled: false` menonaktifkan sebuah skill meskipun dibundel/terinstal. +- `entries..enabled: false` menonaktifkan skill meskipun bundled/terpasang. - `entries..apiKey`: kemudahan untuk skill yang mendeklarasikan env var utama (string plaintext atau objek SecretRef). --- @@ -2887,41 +2877,41 @@ Lihat [Model Lokal](/id/gateway/local-models). Singkatnya: jalankan model lokal } ``` -- Dimuat dari `~/.openclaw/extensions`, `/.openclaw/extensions`, ditambah `plugins.load.paths`. -- Discovery menerima Plugin OpenClaw native serta bundel Codex dan bundel Claude yang kompatibel, termasuk bundel Claude tata letak default tanpa manifest. +- Dimuat dari `~/.openclaw/extensions`, `/.openclaw/extensions`, serta `plugins.load.paths`. +- Discovery menerima plugin OpenClaw native plus bundle Codex dan bundle Claude yang kompatibel, termasuk bundle Claude tata letak default tanpa manifest. - **Perubahan config memerlukan restart gateway.** -- `allow`: allowlist opsional (hanya Plugin yang terdaftar yang dimuat). `deny` menang. -- `plugins.entries..apiKey`: field kemudahan API key tingkat Plugin (saat didukung oleh Plugin). -- `plugins.entries..env`: peta env var yang dicakup Plugin. -- `plugins.entries..hooks.allowPromptInjection`: saat `false`, inti memblokir `before_prompt_build` dan mengabaikan field yang memutasi prompt dari `before_agent_start` lama, sambil tetap mempertahankan `modelOverride` dan `providerOverride` lama. Berlaku untuk hook Plugin native dan direktori hook yang disediakan bundel yang didukung. -- `plugins.entries..subagent.allowModelOverride`: secara eksplisit mempercayai Plugin ini untuk meminta override `provider` dan `model` per proses untuk proses subagen latar belakang. -- `plugins.entries..subagent.allowedModels`: allowlist opsional target `provider/model` kanonis untuk override subagen tepercaya. Gunakan `"*"` hanya jika Anda memang ingin mengizinkan model apa pun. -- `plugins.entries..config`: objek config yang ditentukan Plugin (divalidasi oleh schema Plugin OpenClaw native bila tersedia). +- `allow`: allowlist opsional (hanya plugin yang tercantum yang dimuat). `deny` menang. +- `plugins.entries..apiKey`: field kemudahan API key tingkat plugin (saat didukung oleh plugin). +- `plugins.entries..env`: map env var bercakupan plugin. +- `plugins.entries..hooks.allowPromptInjection`: saat `false`, core memblokir `before_prompt_build` dan mengabaikan field yang memutasi prompt dari `before_agent_start` lama, sambil mempertahankan `modelOverride` dan `providerOverride` lama. Berlaku untuk hook plugin native dan direktori hook yang disediakan bundle yang didukung. +- `plugins.entries..subagent.allowModelOverride`: secara eksplisit mempercayai plugin ini untuk meminta override `provider` dan `model` per proses untuk proses subagent latar belakang. +- `plugins.entries..subagent.allowedModels`: allowlist opsional target `provider/model` kanonis untuk override subagent tepercaya. Gunakan `"*"` hanya jika Anda memang ingin mengizinkan model apa pun. +- `plugins.entries..config`: objek konfigurasi yang didefinisikan plugin (divalidasi oleh schema plugin OpenClaw native saat tersedia). - `plugins.entries.firecrawl.config.webFetch`: pengaturan provider web-fetch Firecrawl. - - `apiKey`: API key Firecrawl (menerima SecretRef). Fallback ke `plugins.entries.firecrawl.config.webSearch.apiKey`, `tools.web.fetch.firecrawl.apiKey` lama, atau env var `FIRECRAWL_API_KEY`. + - `apiKey`: API key Firecrawl (menerima SecretRef). Menggunakan fallback ke `plugins.entries.firecrawl.config.webSearch.apiKey`, `tools.web.fetch.firecrawl.apiKey` lama, atau env var `FIRECRAWL_API_KEY`. - `baseUrl`: base URL API Firecrawl (default: `https://api.firecrawl.dev`). - `onlyMainContent`: ekstrak hanya konten utama dari halaman (default: `true`). - `maxAgeMs`: usia cache maksimum dalam milidetik (default: `172800000` / 2 hari). - `timeoutSeconds`: timeout permintaan scrape dalam detik (default: `60`). -- `plugins.entries.xai.config.xSearch`: pengaturan xAI X Search (pencarian web Grok). +- `plugins.entries.xai.config.xSearch`: pengaturan X Search xAI (pencarian web Grok). - `enabled`: aktifkan provider X Search. - `model`: model Grok yang digunakan untuk pencarian (mis. `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: pengaturan Dreaming memory. Lihat [Dreaming](/id/concepts/dreaming) untuk fase dan threshold. - - `enabled`: sakelar utama Dreaming (default `false`). - - `frequency`: cadence Cron untuk setiap sapuan Dreaming penuh (default `"0 3 * * *"`). - - kebijakan fase dan threshold adalah detail implementasi (bukan key config yang dihadapkan ke pengguna). -- Config Memory lengkap ada di [Referensi konfigurasi Memory](/id/reference/memory-config): +- `plugins.entries.memory-core.config.dreaming`: pengaturan dreaming memory. Lihat [Dreaming](/id/concepts/dreaming) untuk fase dan ambang. + - `enabled`: sakelar utama dreaming (default `false`). + - `frequency`: cadence Cron untuk setiap sweep dreaming penuh (default `"0 3 * * *"`). + - kebijakan fase dan ambang adalah detail implementasi (bukan kunci konfigurasi yang berhadapan dengan pengguna). +- Konfigurasi memory lengkap ada di [Referensi konfigurasi memory](/id/reference/memory-config): - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- Plugin bundel Claude yang diaktifkan juga dapat menyumbangkan default Pi embedded dari `settings.json`; OpenClaw menerapkannya sebagai pengaturan agen yang telah disanitasi, bukan sebagai patch config OpenClaw mentah. -- `plugins.slots.memory`: pilih id Plugin memory aktif, atau `"none"` untuk menonaktifkan Plugin memory. -- `plugins.slots.contextEngine`: pilih id Plugin context engine aktif; default ke `"legacy"` kecuali Anda menginstal dan memilih engine lain. +- Plugin bundle Claude yang diaktifkan juga dapat menyumbangkan default Pi embedded dari `settings.json`; OpenClaw menerapkannya sebagai pengaturan agent yang sudah disanitasi, bukan sebagai patch config OpenClaw mentah. +- `plugins.slots.memory`: pilih id plugin memory aktif, atau `"none"` untuk menonaktifkan plugin memory. +- `plugins.slots.contextEngine`: pilih id plugin context engine aktif; default ke `"legacy"` kecuali Anda menginstal dan memilih engine lain. - `plugins.installs`: metadata instalasi yang dikelola CLI dan digunakan oleh `openclaw plugins update`. - Mencakup `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`. - - Perlakukan `plugins.installs.*` sebagai status terkelola; lebih baik gunakan perintah CLI daripada edit manual. + - Perlakukan `plugins.installs.*` sebagai status yang dikelola; sebaiknya gunakan perintah CLI daripada edit manual. Lihat [Plugins](/id/tools/plugin). @@ -2936,7 +2926,7 @@ Lihat [Plugins](/id/tools/plugin). evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // pilih hanya untuk akses jaringan privat tepercaya + // dangerouslyAllowPrivateNetwork: true, // opt in hanya untuk akses jaringan private yang tepercaya // allowPrivateNetwork: true, // alias lama // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], @@ -2965,28 +2955,28 @@ Lihat [Plugins](/id/tools/plugin). - `evaluateEnabled: false` menonaktifkan `act:evaluate` dan `wait --fn`. - `ssrfPolicy.dangerouslyAllowPrivateNetwork` dinonaktifkan saat tidak diatur, sehingga navigasi browser tetap ketat secara default. -- Atur `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` hanya saat Anda memang mempercayai navigasi browser jaringan privat. -- Dalam mode ketat, endpoint profil CDP remote (`profiles.*.cdpUrl`) tunduk pada pemblokiran jaringan privat yang sama selama pemeriksaan keterjangkauan/discovery. +- Atur `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` hanya saat Anda memang mempercayai navigasi browser jaringan private. +- Dalam mode ketat, endpoint profil CDP remote (`profiles.*.cdpUrl`) tunduk pada pemblokiran jaringan private yang sama selama pemeriksaan reachability/discovery. - `ssrfPolicy.allowPrivateNetwork` tetap didukung sebagai alias lama. - Dalam mode ketat, gunakan `ssrfPolicy.hostnameAllowlist` dan `ssrfPolicy.allowedHostnames` untuk pengecualian eksplisit. - Profil remote bersifat attach-only (start/stop/reset dinonaktifkan). - `profiles.*.cdpUrl` menerima `http://`, `https://`, `ws://`, dan `wss://`. Gunakan HTTP(S) saat Anda ingin OpenClaw menemukan `/json/version`; gunakan WS(S) - saat provider Anda memberikan URL WebSocket DevTools langsung. + saat provider Anda memberi URL WebSocket DevTools langsung. - Profil `existing-session` menggunakan Chrome MCP alih-alih CDP dan dapat attach pada host yang dipilih atau melalui browser node yang terhubung. -- Profil `existing-session` dapat mengatur `userDataDir` untuk menargetkan profil browser +- Profil `existing-session` dapat menetapkan `userDataDir` untuk menargetkan profil browser berbasis Chromium tertentu seperti Brave atau Edge. -- Profil `existing-session` mempertahankan batas route Chrome MCP saat ini: - tindakan berbasis snapshot/ref alih-alih penargetan selector CSS, hook upload satu file, - tanpa override timeout dialog, tanpa `wait --load networkidle`, serta tanpa - `responsebody`, ekspor PDF, intersepsi unduhan, atau tindakan batch. -- Profil `openclaw` terkelola lokal secara otomatis menetapkan `cdpPort` dan `cdpUrl`; hanya +- Profil `existing-session` mempertahankan batas rute Chrome MCP saat ini: + action berbasis snapshot/ref alih-alih penargetan CSS-selector, hook upload + satu file, tanpa override timeout dialog, dan tanpa `wait --load networkidle`, + `responsebody`, ekspor PDF, intersepsi download, atau action batch. +- Profil `openclaw` yang dikelola lokal secara otomatis menetapkan `cdpPort` dan `cdpUrl`; hanya atur `cdpUrl` secara eksplisit untuk CDP remote. - Urutan auto-detect: browser default jika berbasis Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. -- Layanan Control: hanya loopback (port diturunkan dari `gateway.port`, default `18791`). -- `extraArgs` menambahkan flag peluncuran ekstra ke startup Chromium lokal (misalnya - `--disable-gpu`, pengaturan ukuran jendela, atau flag debug). +- Layanan kontrol: hanya loopback (port diturunkan dari `gateway.port`, default `18791`). +- `extraArgs` menambahkan flag peluncuran tambahan ke startup Chromium lokal (misalnya + `--disable-gpu`, ukuran jendela, atau flag debug). --- @@ -2998,14 +2988,14 @@ Lihat [Plugins](/id/tools/plugin). seamColor: "#FF4500", assistant: { name: "OpenClaw", - avatar: "CB", // emoji, teks singkat, URL gambar, atau URI data + avatar: "CB", // emoji, teks singkat, URL gambar, atau data URI }, }, } ``` -- `seamColor`: warna aksen untuk chrome UI aplikasi native (warna gelembung Talk Mode, dll.). -- `assistant`: override identitas UI Control. Fallback ke identitas agen aktif. +- `seamColor`: warna aksen untuk chrome UI aplikasi native (Talk Mode bubble tint, dll.). +- `assistant`: override identitas UI Control. Menggunakan fallback ke identitas agent aktif. --- @@ -3040,8 +3030,8 @@ Lihat [Plugins](/id/tools/plugin). // root: "dist/control-ui", // embedSandbox: "scripts", // strict | scripts | trusted // allowExternalEmbedUrls: false, // berbahaya: izinkan URL embed http(s) eksternal absolut - // allowedOrigins: ["https://control.example.com"], // diperlukan untuk UI Control non-loopback - // dangerouslyAllowHostHeaderOriginFallback: false, // mode fallback origin Host-header yang berbahaya + // allowedOrigins: ["https://control.example.com"], // wajib untuk UI Control non-loopback + // dangerouslyAllowHostHeaderOriginFallback: false, // mode fallback origin Host-header berbahaya // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -3055,9 +3045,9 @@ Lihat [Plugins](/id/tools/plugin). // Opsional. Default false. allowRealIpFallback: false, tools: { - // Penolakan HTTP /tools/invoke tambahan + // Deny HTTP /tools/invoke tambahan deny: ["browser"], - // Hapus alat dari daftar deny HTTP default + // Hapus tool dari daftar deny HTTP default allow: ["gateway"], }, push: { @@ -3074,60 +3064,60 @@ Lihat [Plugins](/id/tools/plugin). -- `mode`: `local` (jalankan gateway) atau `remote` (hubungkan ke gateway remote). Gateway menolak start kecuali `local`. +- `mode`: `local` (jalankan gateway) atau `remote` (terhubung ke gateway remote). Gateway menolak untuk memulai kecuali `local`. - `port`: satu port termultipleks untuk WS + HTTP. Prioritas: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. - `bind`: `auto`, `loopback` (default), `lan` (`0.0.0.0`), `tailnet` (hanya IP Tailscale), atau `custom`. - **Alias bind lama**: gunakan nilai mode bind di `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), bukan alias host (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). -- **Catatan Docker**: bind default `loopback` mendengarkan pada `127.0.0.1` di dalam container. Dengan jaringan bridge Docker (`-p 18789:18789`), traffic masuk melalui `eth0`, sehingga gateway tidak dapat dijangkau. Gunakan `--network host`, atau atur `bind: "lan"` (atau `bind: "custom"` dengan `customBindHost: "0.0.0.0"`) agar mendengarkan di semua interface. +- **Catatan Docker**: bind default `loopback` mendengarkan pada `127.0.0.1` di dalam container. Dengan jaringan bridge Docker (`-p 18789:18789`), lalu lintas tiba di `eth0`, sehingga gateway tidak dapat dijangkau. Gunakan `--network host`, atau atur `bind: "lan"` (atau `bind: "custom"` dengan `customBindHost: "0.0.0.0"`) agar mendengarkan di semua interface. - **Auth**: wajib secara default. Bind non-loopback memerlukan auth gateway. Dalam praktiknya itu berarti token/password bersama atau reverse proxy yang sadar identitas dengan `gateway.auth.mode: "trusted-proxy"`. Wizard onboarding menghasilkan token secara default. -- Jika `gateway.auth.token` dan `gateway.auth.password` keduanya dikonfigurasi (termasuk SecretRef), atur `gateway.auth.mode` secara eksplisit ke `token` atau `password`. Alur startup dan install/perbaikan layanan gagal saat keduanya dikonfigurasi dan mode tidak diatur. +- Jika `gateway.auth.token` dan `gateway.auth.password` sama-sama dikonfigurasi (termasuk SecretRef), atur `gateway.auth.mode` secara eksplisit ke `token` atau `password`. Startup dan alur instalasi/perbaikan layanan gagal saat keduanya dikonfigurasi dan mode tidak diatur. - `gateway.auth.mode: "none"`: mode tanpa auth eksplisit. Gunakan hanya untuk penyiapan local loopback tepercaya; ini sengaja tidak ditawarkan oleh prompt onboarding. -- `gateway.auth.mode: "trusted-proxy"`: delegasikan auth ke reverse proxy yang sadar identitas dan percayai header identitas dari `gateway.trustedProxies` (lihat [Auth Trusted Proxy](/id/gateway/trusted-proxy-auth)). Mode ini mengharapkan sumber proxy **non-loopback**; reverse proxy loopback pada host yang sama tidak memenuhi auth trusted-proxy. -- `gateway.auth.allowTailscale`: saat `true`, header identitas Tailscale Serve dapat memenuhi auth UI Control/WebSocket (diverifikasi melalui `tailscale whois`). Endpoint API HTTP **tidak** menggunakan auth header Tailscale itu; endpoint tersebut mengikuti mode auth HTTP gateway normal. Alur tanpa token ini mengasumsikan host gateway tepercaya. Default ke `true` saat `tailscale.mode = "serve"`. -- `gateway.auth.rateLimit`: pembatas auth gagal opsional. Berlaku per IP klien dan per cakupan auth (shared-secret dan device-token dilacak secara independen). Upaya yang diblokir mengembalikan `429` + `Retry-After`. - - Pada jalur UI Control Tailscale Serve async, upaya gagal untuk `{scope, clientIp}` yang sama diserialkan sebelum penulisan kegagalan. Upaya buruk bersamaan dari klien yang sama karena itu dapat memicu limiter pada permintaan kedua alih-alih keduanya lolos sebagai ketidakcocokan biasa. - - `gateway.auth.rateLimit.exemptLoopback` default ke `true`; atur `false` saat Anda memang ingin traffic localhost juga dibatasi (untuk penyiapan uji atau deployment proxy ketat). -- Upaya auth WS dari origin browser selalu di-throttle dengan pengecualian loopback dinonaktifkan (pertahanan berlapis terhadap brute force localhost berbasis browser). -- Pada loopback, lockout origin browser itu diisolasi per nilai `Origin` +- `gateway.auth.mode: "trusted-proxy"`: delegasikan auth ke reverse proxy yang sadar identitas dan percayai header identitas dari `gateway.trustedProxies` (lihat [Trusted Proxy Auth](/id/gateway/trusted-proxy-auth)). Mode ini mengharapkan sumber proxy **non-loopback**; reverse proxy loopback pada host yang sama tidak memenuhi trusted-proxy auth. +- `gateway.auth.allowTailscale`: saat `true`, header identitas Tailscale Serve dapat memenuhi auth UI Control/WebSocket (diverifikasi melalui `tailscale whois`). Endpoint HTTP API **tidak** menggunakan auth header Tailscale tersebut; endpoint itu mengikuti mode auth HTTP normal gateway. Alur tanpa token ini mengasumsikan host gateway tepercaya. Default ke `true` saat `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit`: limiter auth gagal opsional. Berlaku per IP klien dan per cakupan auth (shared-secret dan device-token dilacak secara independen). Upaya yang diblokir mengembalikan `429` + `Retry-After`. + - Pada jalur async Tailscale Serve UI Control, upaya gagal untuk `{scope, clientIp}` yang sama diserialkan sebelum penulisan kegagalan. Karena itu, upaya buruk serentak dari klien yang sama dapat memicu limiter pada permintaan kedua alih-alih keduanya lolos sebagai mismatch biasa. + - `gateway.auth.rateLimit.exemptLoopback` default ke `true`; atur `false` saat Anda memang ingin lalu lintas localhost juga dibatasi lajunya (untuk penyiapan pengujian atau deployment proxy yang ketat). +- Upaya auth WS yang berasal dari browser selalu di-throttle dengan pengecualian loopback dinonaktifkan (pertahanan berlapis terhadap brute force localhost berbasis browser). +- Pada loopback, lockout yang berasal dari browser tersebut diisolasi per nilai `Origin` yang dinormalisasi, sehingga kegagalan berulang dari satu origin localhost tidak otomatis - mengunci origin lain. + mengunci origin yang berbeda. - `tailscale.mode`: `serve` (hanya tailnet, bind loopback) atau `funnel` (publik, memerlukan auth). -- `controlUi.allowedOrigins`: allowlist browser-origin eksplisit untuk koneksi WebSocket Gateway. Wajib saat klien browser diharapkan datang dari origin non-loopback. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: mode berbahaya yang mengaktifkan fallback origin berbasis Host-header untuk deployment yang memang mengandalkan kebijakan origin Host-header. +- `controlUi.allowedOrigins`: allowlist origin browser eksplisit untuk koneksi Gateway WebSocket. Wajib saat klien browser diharapkan berasal dari origin non-loopback. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: mode berbahaya yang mengaktifkan fallback origin Host-header untuk deployment yang sengaja bergantung pada kebijakan origin Host-header. - `remote.transport`: `ssh` (default) atau `direct` (ws/wss). Untuk `direct`, `remote.url` harus `ws://` atau `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: override break-glass sisi klien yang mengizinkan `ws://` plaintext ke IP jaringan privat tepercaya; default tetap hanya loopback untuk plaintext. -- `gateway.remote.token` / `.password` adalah field kredensial klien remote. Field tersebut tidak dengan sendirinya mengonfigurasi auth gateway. -- `gateway.push.apns.relay.baseUrl`: base URL HTTPS untuk relay APNs eksternal yang digunakan oleh build iOS resmi/TestFlight setelah build tersebut memublikasikan registrasi berbasis relay ke gateway. URL ini harus cocok dengan URL relay yang dikompilasi ke dalam build iOS. -- `gateway.push.apns.relay.timeoutMs`: timeout kirim gateway-ke-relay dalam milidetik. Default ke `10000`. -- Registrasi berbasis relay didelegasikan ke identitas gateway tertentu. Aplikasi iOS yang dipasangkan mengambil `gateway.identity.get`, menyertakan identitas itu dalam registrasi relay, dan meneruskan grant kirim yang dicakup registrasi ke gateway. Gateway lain tidak dapat menggunakan ulang registrasi yang disimpan itu. -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: override env sementara untuk config relay di atas. -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: escape hatch khusus pengembangan untuk URL relay HTTP loopback. URL relay produksi sebaiknya tetap menggunakan HTTPS. -- `gateway.channelHealthCheckMinutes`: interval monitor kesehatan channel dalam menit. Atur `0` untuk menonaktifkan restart health-monitor secara global. Default: `5`. -- `gateway.channelStaleEventThresholdMinutes`: ambang socket basi dalam menit. Pertahankan ini lebih besar atau sama dengan `gateway.channelHealthCheckMinutes`. Default: `30`. -- `gateway.channelMaxRestartsPerHour`: jumlah maksimum restart health-monitor per channel/akun dalam satu jam berjalan. Default: `10`. -- `channels..healthMonitor.enabled`: opt-out per channel untuk restart health-monitor sambil tetap menjaga monitor global aktif. -- `channels..accounts..healthMonitor.enabled`: override per akun untuk channel multi-akun. Saat diatur, ini didahulukan atas override tingkat channel. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: override break-glass sisi klien yang mengizinkan `ws://` plaintext ke IP jaringan private tepercaya; default tetap hanya loopback untuk plaintext. +- `gateway.remote.token` / `.password` adalah field kredensial klien remote. Field ini sendiri tidak mengonfigurasi auth gateway. +- `gateway.push.apns.relay.baseUrl`: base HTTPS URL untuk relay APNs eksternal yang digunakan oleh build iOS resmi/TestFlight setelah memublikasikan registrasi berbasis relay ke gateway. URL ini harus cocok dengan URL relay yang dikompilasi ke dalam build iOS. +- `gateway.push.apns.relay.timeoutMs`: timeout pengiriman gateway-ke-relay dalam milidetik. Default ke `10000`. +- Registrasi berbasis relay didelegasikan ke identitas gateway tertentu. Aplikasi iOS yang dipasangkan mengambil `gateway.identity.get`, menyertakan identitas itu dalam registrasi relay, dan meneruskan grant pengiriman bercakupan registrasi ke gateway. Gateway lain tidak dapat menggunakan ulang registrasi tersimpan tersebut. +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: override env sementara untuk konfigurasi relay di atas. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: escape hatch khusus pengembangan untuk URL relay HTTP loopback. URL relay produksi harus tetap menggunakan HTTPS. +- `gateway.channelHealthCheckMinutes`: interval monitor kesehatan channel dalam menit. Atur `0` untuk menonaktifkan restart monitor kesehatan secara global. Default: `5`. +- `gateway.channelStaleEventThresholdMinutes`: ambang socket usang dalam menit. Pertahankan nilai ini lebih besar dari atau sama dengan `gateway.channelHealthCheckMinutes`. Default: `30`. +- `gateway.channelMaxRestartsPerHour`: jumlah maksimum restart monitor kesehatan per channel/akun dalam satu jam bergulir. Default: `10`. +- `channels..healthMonitor.enabled`: opt-out per channel untuk restart monitor kesehatan sambil tetap mempertahankan monitor global aktif. +- `channels..accounts..healthMonitor.enabled`: override per akun untuk channel multi-akun. Saat diatur, ini mendahului override tingkat channel. - Jalur panggilan gateway lokal dapat menggunakan `gateway.remote.*` sebagai fallback hanya saat `gateway.auth.*` tidak diatur. -- Jika `gateway.auth.token` / `gateway.auth.password` secara eksplisit dikonfigurasi melalui SecretRef dan tidak dapat di-resolve, resolusi gagal tertutup (tidak ada fallback remote yang menutupi). -- `trustedProxies`: IP reverse proxy yang mengakhiri TLS atau menyisipkan header klien-teruskan. Cantumkan hanya proxy yang Anda kendalikan. Entri loopback tetap valid untuk penyiapan proxy host yang sama/deteksi lokal (misalnya Tailscale Serve atau reverse proxy lokal), tetapi entri itu **tidak** membuat permintaan loopback memenuhi syarat untuk `gateway.auth.mode: "trusted-proxy"`. +- Jika `gateway.auth.token` / `gateway.auth.password` secara eksplisit dikonfigurasi melalui SecretRef dan tidak dapat di-resolve, resolusi gagal secara fail-closed (tidak ada fallback remote yang menyamarkan). +- `trustedProxies`: IP reverse proxy yang mengakhiri TLS atau menyuntikkan header forwarded-client. Cantumkan hanya proxy yang Anda kendalikan. Entri loopback tetap valid untuk penyiapan proxy lokal/deteksi lokal pada host yang sama (misalnya Tailscale Serve atau reverse proxy lokal), tetapi entri itu **tidak** membuat permintaan loopback memenuhi syarat untuk `gateway.auth.mode: "trusted-proxy"`. - `allowRealIpFallback`: saat `true`, gateway menerima `X-Real-IP` jika `X-Forwarded-For` tidak ada. Default `false` untuk perilaku fail-closed. -- `gateway.tools.deny`: nama alat tambahan yang diblokir untuk HTTP `POST /tools/invoke` (memperluas daftar deny default). -- `gateway.tools.allow`: hapus nama alat dari daftar deny HTTP default. +- `gateway.tools.deny`: nama tool tambahan yang diblokir untuk HTTP `POST /tools/invoke` (memperluas daftar deny default). +- `gateway.tools.allow`: hapus nama tool dari daftar deny HTTP default. -### Endpoint OpenAI-compatible +### Endpoint yang kompatibel dengan OpenAI -- Chat Completions: nonaktif secara default. Aktifkan dengan `gateway.http.endpoints.chatCompletions.enabled: true`. +- Chat Completions: dinonaktifkan secara default. Aktifkan dengan `gateway.http.endpoints.chatCompletions.enabled: true`. - Responses API: `gateway.http.endpoints.responses.enabled`. -- Hardening input-URL Responses: +- Hardening input URL Responses: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` Allowlist kosong diperlakukan sebagai tidak diatur; gunakan `gateway.http.endpoints.responses.files.allowUrl=false` dan/atau `gateway.http.endpoints.responses.images.allowUrl=false` untuk menonaktifkan pengambilan URL. - Header hardening respons opsional: - - `gateway.http.securityHeaders.strictTransportSecurity` (atur hanya untuk origin HTTPS yang Anda kendalikan; lihat [Auth Trusted Proxy](/id/gateway/trusted-proxy-auth#tls-termination-and-hsts)) + - `gateway.http.securityHeaders.strictTransportSecurity` (atur hanya untuk origin HTTPS yang Anda kendalikan; lihat [Trusted Proxy Auth](/id/gateway/trusted-proxy-auth#tls-termination-and-hsts)) ### Isolasi multi-instance @@ -3139,7 +3129,7 @@ OPENCLAW_STATE_DIR=~/.openclaw-a \ openclaw gateway --port 19001 ``` -Flag praktis: `--dev` (menggunakan `~/.openclaw-dev` + port `19001`), `--profile ` (menggunakan `~/.openclaw-`). +Flag kemudahan: `--dev` (menggunakan `~/.openclaw-dev` + port `19001`), `--profile ` (menggunakan `~/.openclaw-`). Lihat [Multiple Gateways](/id/gateway/multiple-gateways). @@ -3160,10 +3150,10 @@ Lihat [Multiple Gateways](/id/gateway/multiple-gateways). ``` - `enabled`: mengaktifkan terminasi TLS pada listener gateway (HTTPS/WSS) (default: `false`). -- `autoGenerate`: menghasilkan otomatis pasangan cert/key self-signed lokal saat file eksplisit tidak dikonfigurasi; hanya untuk penggunaan lokal/dev. +- `autoGenerate`: menghasilkan pasangan cert/key self-signed lokal secara otomatis saat file eksplisit tidak dikonfigurasi; hanya untuk penggunaan lokal/dev. - `certPath`: path filesystem ke file sertifikat TLS. -- `keyPath`: path filesystem ke file private key TLS; jaga agar izin aksesnya dibatasi. -- `caPath`: path bundle CA opsional untuk verifikasi klien atau rantai kepercayaan kustom. +- `keyPath`: path filesystem ke file private key TLS; pertahankan pembatasan izin. +- `caPath`: path bundel CA opsional untuk verifikasi klien atau rantai kepercayaan kustom. ### `gateway.reload` @@ -3182,9 +3172,9 @@ Lihat [Multiple Gateways](/id/gateway/multiple-gateways). - `mode`: mengontrol bagaimana edit config diterapkan saat runtime. - `"off"`: abaikan edit live; perubahan memerlukan restart eksplisit. - `"restart"`: selalu restart proses gateway saat config berubah. - - `"hot"`: terapkan perubahan di dalam proses tanpa restart. - - `"hybrid"` (default): coba hot reload terlebih dahulu; fallback ke restart bila diperlukan. -- `debounceMs`: jendela debounce dalam ms sebelum perubahan config diterapkan (integer non-negatif). + - `"hot"`: terapkan perubahan in-process tanpa restart. + - `"hybrid"` (default): coba hot reload terlebih dahulu; gunakan fallback ke restart jika diperlukan. +- `debounceMs`: jendela debounce dalam ms sebelum perubahan config diterapkan (bilangan bulat non-negatif). - `deferralTimeoutMs`: waktu maksimum dalam ms untuk menunggu operasi yang sedang berjalan sebelum memaksa restart (default: `300000` = 5 menit). --- @@ -3223,15 +3213,15 @@ Lihat [Multiple Gateways](/id/gateway/multiple-gateways). ``` Auth: `Authorization: Bearer ` atau `x-openclaw-token: `. -Token hook di query-string ditolak. +Token hook dalam query-string ditolak. Catatan validasi dan keamanan: - `hooks.enabled=true` memerlukan `hooks.token` yang tidak kosong. -- `hooks.token` harus **berbeda** dari `gateway.auth.token`; penggunaan ulang token Gateway ditolak. +- `hooks.token` harus **berbeda** dari `gateway.auth.token`; penggunaan ulang token Gateway akan ditolak. - `hooks.path` tidak boleh `/`; gunakan subpath khusus seperti `/hooks`. - Jika `hooks.allowRequestSessionKey=true`, batasi `hooks.allowedSessionKeyPrefixes` (misalnya `["hook:"]`). -- Jika mapping atau preset menggunakan `sessionKey` bertemplate, atur `hooks.allowedSessionKeyPrefixes` dan `hooks.allowRequestSessionKey=true`. Key mapping statis tidak memerlukan opt-in itu. +- Jika mapping atau preset menggunakan `sessionKey` bertemplat, atur `hooks.allowedSessionKeyPrefixes` dan `hooks.allowRequestSessionKey=true`. Kunci mapping statis tidak memerlukan opt-in tersebut. **Endpoint:** @@ -3239,30 +3229,30 @@ Catatan validasi dan keamanan: - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - `sessionKey` dari payload permintaan diterima hanya saat `hooks.allowRequestSessionKey=true` (default: `false`). - `POST /hooks/` → di-resolve melalui `hooks.mappings` - - Nilai `sessionKey` mapping yang dirender dengan template diperlakukan sebagai pasokan eksternal dan juga memerlukan `hooks.allowRequestSessionKey=true`. + - Nilai `sessionKey` mapping yang di-render dari template diperlakukan sebagai disuplai secara eksternal dan juga memerlukan `hooks.allowRequestSessionKey=true`. - `match.path` cocok dengan sub-path setelah `/hooks` (misalnya `/hooks/gmail` → `gmail`). - `match.source` cocok dengan field payload untuk path generik. - Template seperti `{{messages[0].subject}}` membaca dari payload. -- `transform` dapat menunjuk ke modul JS/TS yang mengembalikan aksi hook. - - `transform.module` harus berupa path relatif dan tetap berada dalam `hooks.transformsDir` (path absolut dan traversal ditolak). -- `agentId` merutekan ke agen tertentu; ID yang tidak dikenal fallback ke default. -- `allowedAgentIds`: membatasi perutean eksplisit (`*` atau dihilangkan = izinkan semua, `[]` = tolak semua). -- `defaultSessionKey`: key sesi tetap opsional untuk proses agen hook tanpa `sessionKey` eksplisit. -- `allowRequestSessionKey`: izinkan pemanggil `/hooks/agent` dan key sesi mapping berbasis template untuk menetapkan `sessionKey` (default: `false`). -- `allowedSessionKeyPrefixes`: allowlist prefix opsional untuk nilai `sessionKey` eksplisit (request + mapping), misalnya `["hook:"]`. Ini menjadi wajib saat mapping atau preset apa pun menggunakan `sessionKey` bertemplate. -- `deliver: true` mengirim balasan akhir ke sebuah channel; `channel` default ke `last`. -- `model` mengoverride LLM untuk proses hook ini (harus diizinkan jika katalog model diatur). +- `transform` dapat menunjuk ke modul JS/TS yang mengembalikan action hook. + - `transform.module` harus berupa path relatif dan tetap berada di dalam `hooks.transformsDir` (path absolut dan traversal ditolak). +- `agentId` merutekan ke agent tertentu; ID yang tidak dikenal menggunakan fallback ke default. +- `allowedAgentIds`: membatasi routing eksplisit (`*` atau dihilangkan = izinkan semua, `[]` = tolak semua). +- `defaultSessionKey`: kunci sesi tetap opsional untuk proses agent hook tanpa `sessionKey` eksplisit. +- `allowRequestSessionKey`: izinkan pemanggil `/hooks/agent` dan kunci sesi mapping yang digerakkan template untuk menetapkan `sessionKey` (default: `false`). +- `allowedSessionKeyPrefixes`: allowlist prefiks opsional untuk nilai `sessionKey` eksplisit (request + mapping), misalnya `["hook:"]`. Ini menjadi wajib saat ada mapping atau preset yang menggunakan `sessionKey` bertemplat. +- `deliver: true` mengirim balasan akhir ke channel; `channel` default ke `last`. +- `model` menimpa LLM untuk proses hook ini (harus diizinkan jika katalog model diatur). ### Integrasi Gmail - Preset Gmail bawaan menggunakan `sessionKey: "hook:gmail:{{messages[0].id}}"`. -- Jika Anda mempertahankan perutean per pesan itu, atur `hooks.allowRequestSessionKey: true` dan batasi `hooks.allowedSessionKeyPrefixes` agar cocok dengan namespace Gmail, misalnya `["hook:", "hook:gmail:"]`. -- Jika Anda memerlukan `hooks.allowRequestSessionKey: false`, override preset dengan `sessionKey` statis alih-alih default bertemplate. +- Jika Anda mempertahankan routing per-pesan tersebut, atur `hooks.allowRequestSessionKey: true` dan batasi `hooks.allowedSessionKeyPrefixes` agar cocok dengan namespace Gmail, misalnya `["hook:", "hook:gmail:"]`. +- Jika Anda memerlukan `hooks.allowRequestSessionKey: false`, timpa preset dengan `sessionKey` statis alih-alih default bertemplat. ```json5 { @@ -3285,12 +3275,12 @@ Catatan validasi dan keamanan: } ``` -- Gateway memulai otomatis `gog gmail watch serve` saat boot ketika dikonfigurasi. Atur `OPENCLAW_SKIP_GMAIL_WATCHER=1` untuk menonaktifkan. +- Gateway otomatis memulai `gog gmail watch serve` saat boot jika dikonfigurasi. Atur `OPENCLAW_SKIP_GMAIL_WATCHER=1` untuk menonaktifkan. - Jangan menjalankan `gog gmail watch serve` terpisah bersamaan dengan Gateway. --- -## Host canvas +## Canvas host ```json5 { @@ -3302,15 +3292,15 @@ Catatan validasi dan keamanan: } ``` -- Menyajikan HTML/CSS/JS yang dapat diedit agen dan A2UI melalui HTTP di bawah port Gateway: +- Menyajikan HTML/CSS/JS yang dapat diedit agent dan A2UI melalui HTTP di bawah port Gateway: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` - Hanya lokal: pertahankan `gateway.bind: "loopback"` (default). - Bind non-loopback: route canvas memerlukan auth Gateway (token/password/trusted-proxy), sama seperti permukaan HTTP Gateway lainnya. -- Node WebViews biasanya tidak mengirim header auth; setelah sebuah node dipasangkan dan terhubung, Gateway mengiklankan URL capability yang dicakup node untuk akses canvas/A2UI. -- URL capability terikat ke sesi WS node aktif dan cepat kedaluwarsa. Fallback berbasis IP tidak digunakan. -- Menyisipkan klien live-reload ke HTML yang disajikan. -- Membuat otomatis `index.html` awal saat kosong. +- Node WebView biasanya tidak mengirim header auth; setelah node dipasangkan dan terhubung, Gateway mengiklankan URL kapabilitas bercakupan node untuk akses canvas/A2UI. +- URL kapabilitas terikat ke sesi WS node aktif dan cepat kedaluwarsa. Fallback berbasis IP tidak digunakan. +- Menyuntikkan klien live-reload ke HTML yang disajikan. +- Secara otomatis membuat `index.html` awal saat kosong. - Juga menyajikan A2UI di `/__openclaw__/a2ui/`. - Perubahan memerlukan restart gateway. - Nonaktifkan live reload untuk direktori besar atau error `EMFILE`. @@ -3333,7 +3323,7 @@ Catatan validasi dan keamanan: - `minimal` (default): hilangkan `cliPath` + `sshPort` dari record TXT. - `full`: sertakan `cliPath` + `sshPort`. -- Hostname default ke `openclaw`. Override dengan `OPENCLAW_MDNS_HOSTNAME`. +- Hostname default ke `openclaw`. Timpa dengan `OPENCLAW_MDNS_HOSTNAME`. ### Wide-area (DNS-SD) @@ -3345,7 +3335,7 @@ Catatan validasi dan keamanan: } ``` -Menulis zona DNS-SD unicast di bawah `~/.openclaw/dns/`. Untuk discovery lintas jaringan, padukan dengan server DNS (CoreDNS direkomendasikan) + split DNS Tailscale. +Menulis zona DNS-SD unicast di bawah `~/.openclaw/dns/`. Untuk discovery lintas jaringan, pasangkan dengan server DNS (disarankan CoreDNS) + split DNS Tailscale. Penyiapan: `openclaw dns setup --apply`. @@ -3353,7 +3343,7 @@ Penyiapan: `openclaw dns setup --apply`. ## Lingkungan -### `env` (env vars inline) +### `env` (env var inline) ```json5 { @@ -3370,14 +3360,14 @@ Penyiapan: `openclaw dns setup --apply`. } ``` -- Env vars inline hanya diterapkan jika env proses tidak memiliki key tersebut. -- File `.env`: `.env` CWD + `~/.openclaw/.env` (keduanya tidak mengoverride variabel yang sudah ada). -- `shellEnv`: mengimpor key yang diharapkan tetapi belum ada dari profil shell login Anda. +- Env var inline hanya diterapkan jika env proses tidak memiliki kunci tersebut. +- File `.env`: `.env` CWD + `~/.openclaw/.env` (keduanya tidak menimpa variabel yang sudah ada). +- `shellEnv`: mengimpor kunci yang diharapkan tetapi belum ada dari profil login shell Anda. - Lihat [Environment](/id/help/environment) untuk prioritas lengkap. ### Substitusi env var -Referensikan env var di string config mana pun dengan `${VAR_NAME}`: +Referensikan env var dalam string config apa pun dengan `${VAR_NAME}`: ```json5 { @@ -3387,16 +3377,16 @@ Referensikan env var di string config mana pun dengan `${VAR_NAME}`: } ``` -- Hanya nama huruf besar yang cocok: `[A-Z_][A-Z0-9_]*`. -- Variabel yang hilang/kosong menimbulkan error saat pemuatan config. +- Hanya nama huruf besar yang dicocokkan: `[A-Z_][A-Z0-9_]*`. +- Variabel yang hilang/kosong menimbulkan error saat memuat config. - Escape dengan `$${VAR}` untuk `${VAR}` literal. -- Bekerja dengan `$include`. +- Berfungsi dengan `$include`. --- ## Secrets -Ref secret bersifat aditif: nilai plaintext tetap berfungsi. +Referensi secret bersifat aditif: nilai plaintext tetap berfungsi. ### `SecretRef` @@ -3409,18 +3399,18 @@ Gunakan satu bentuk objek: Validasi: - pola `provider`: `^[a-z][a-z0-9_-]{0,63}$` -- pola `source: "env"` untuk id: `^[A-Z][A-Z0-9_]{0,127}$` -- `source: "file"` id: pointer JSON absolut (misalnya `"/providers/openai/apiKey"`) -- pola `source: "exec"` untuk id: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- id `source: "exec"` tidak boleh mengandung segmen path slash-delimited `.` atau `..` (misalnya `a/../b` ditolak) +- pola id `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` +- id `source: "file"`: JSON pointer absolut (misalnya `"/providers/openai/apiKey"`) +- pola id `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` +- id `source: "exec"` tidak boleh mengandung segmen path yang dipisahkan garis miring `.` atau `..` (misalnya `a/../b` ditolak) ### Permukaan kredensial yang didukung - Matriks kanonis: [Permukaan Kredensial SecretRef](/id/reference/secretref-credential-surface) - `secrets apply` menargetkan path kredensial `openclaw.json` yang didukung. -- Ref `auth-profiles.json` disertakan dalam resolusi runtime dan cakupan audit. +- Referensi `auth-profiles.json` disertakan dalam resolusi runtime dan cakupan audit. -### Config provider secret +### Konfigurasi provider secret ```json5 { @@ -3452,11 +3442,11 @@ Catatan: - Provider `file` mendukung `mode: "json"` dan `mode: "singleValue"` (`id` harus `"value"` dalam mode singleValue). - Provider `exec` memerlukan path `command` absolut dan menggunakan payload protokol pada stdin/stdout. -- Secara default, path perintah symlink ditolak. Atur `allowSymlinkCommand: true` untuk mengizinkan path symlink sambil memvalidasi path target yang telah di-resolve. -- Jika `trustedDirs` dikonfigurasi, pemeriksaan trusted-dir berlaku untuk path target yang telah di-resolve. +- Secara default, path perintah symlink ditolak. Atur `allowSymlinkCommand: true` untuk mengizinkan path symlink sambil memvalidasi path target yang sudah di-resolve. +- Jika `trustedDirs` dikonfigurasi, pemeriksaan direktori tepercaya berlaku pada path target yang sudah di-resolve. - Lingkungan child `exec` minimal secara default; teruskan variabel yang diperlukan secara eksplisit dengan `passEnv`. -- Ref secret di-resolve pada waktu aktivasi ke dalam snapshot dalam memori, lalu jalur request hanya membaca snapshot itu. -- Pemfilteran active-surface berlaku selama aktivasi: ref yang tidak dapat di-resolve pada permukaan aktif menyebabkan startup/reload gagal, sedangkan permukaan tidak aktif dilewati dengan diagnostik. +- Referensi secret di-resolve pada saat aktivasi ke snapshot dalam memori, lalu path permintaan hanya membaca snapshot tersebut. +- Pemfilteran permukaan aktif berlaku selama aktivasi: referensi yang tidak dapat di-resolve pada permukaan yang aktif menggagalkan startup/reload, sementara permukaan yang tidak aktif dilewati dengan diagnostik. --- @@ -3478,13 +3468,13 @@ Catatan: } ``` -- Profil per agen disimpan di `/auth-profiles.json`. -- `auth-profiles.json` mendukung ref tingkat nilai (`keyRef` untuk `api_key`, `tokenRef` untuk `token`) untuk mode kredensial statis. +- Profil per-agent disimpan di `/auth-profiles.json`. +- `auth-profiles.json` mendukung referensi tingkat nilai (`keyRef` untuk `api_key`, `tokenRef` untuk `token`) untuk mode kredensial statis. - Profil mode OAuth (`auth.profiles..mode = "oauth"`) tidak mendukung kredensial auth-profile berbasis SecretRef. -- Kredensial runtime statis berasal dari snapshot hasil resolve dalam memori; entri `auth.json` statis lama dibersihkan saat ditemukan. +- Kredensial runtime statis berasal dari snapshot yang sudah di-resolve di dalam memori; entri `auth.json` statis lama dibersihkan saat ditemukan. - Impor OAuth lama dari `~/.openclaw/credentials/oauth.json`. - Lihat [OAuth](/id/concepts/oauth). -- Perilaku runtime secret dan alat `audit/configure/apply`: [Secrets Management](/id/gateway/secrets). +- Perilaku runtime secrets dan tool `audit/configure/apply`: [Secrets Management](/id/gateway/secrets). ### `auth.cooldowns` @@ -3506,20 +3496,20 @@ Catatan: } ``` -- `billingBackoffHours`: backoff dasar dalam jam saat sebuah profil gagal karena error penagihan/kredit tidak cukup yang nyata (default: `5`). Teks penagihan eksplisit tetap dapat - masuk ke sini bahkan pada respons `401`/`403`, tetapi pencocok teks - khusus provider tetap dibatasi pada provider pemiliknya (misalnya OpenRouter - `Key limit exceeded`). Pesan `402` retryable untuk jendela penggunaan atau - batas pengeluaran organisasi/workspace tetap berada di jalur `rate_limit` - sebagai gantinya. -- `billingBackoffHoursByProvider`: override per provider opsional untuk jam backoff penagihan. -- `billingMaxHours`: batas atas dalam jam untuk pertumbuhan eksponensial backoff penagihan (default: `24`). +- `billingBackoffHours`: backoff dasar dalam jam saat profil gagal karena error + billing/kredit tidak cukup yang benar-benar terjadi (default: `5`). Teks billing eksplisit masih + dapat masuk ke sini bahkan pada respons `401`/`403`, tetapi matcher teks spesifik provider + tetap dibatasi pada provider yang memilikinya (misalnya OpenRouter + `Key limit exceeded`). Pesan retryable HTTP `402` usage-window atau + spend-limit organization/workspace tetap berada di jalur `rate_limit`. +- `billingBackoffHoursByProvider`: override per-provider opsional untuk jam backoff billing. +- `billingMaxHours`: batas dalam jam untuk pertumbuhan eksponensial backoff billing (default: `24`). - `authPermanentBackoffMinutes`: backoff dasar dalam menit untuk kegagalan `auth_permanent` dengan keyakinan tinggi (default: `10`). -- `authPermanentMaxMinutes`: batas atas dalam menit untuk pertumbuhan backoff `auth_permanent` (default: `60`). -- `failureWindowHours`: jendela berjalan dalam jam yang digunakan untuk penghitung backoff (default: `24`). -- `overloadedProfileRotations`: rotasi auth-profile maksimum untuk provider yang sama pada error overload sebelum beralih ke fallback model (default: `1`). Bentuk provider sibuk seperti `ModelNotReadyException` masuk ke sini. -- `overloadedBackoffMs`: jeda tetap sebelum mencoba ulang rotasi provider/profil yang overload (default: `0`). -- `rateLimitedProfileRotations`: rotasi auth-profile maksimum untuk provider yang sama pada error rate-limit sebelum beralih ke fallback model (default: `1`). Bucket rate-limit itu mencakup teks berbentuk provider seperti `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded`, dan `resource exhausted`. +- `authPermanentMaxMinutes`: batas dalam menit untuk pertumbuhan backoff `auth_permanent` (default: `60`). +- `failureWindowHours`: jendela bergulir dalam jam yang digunakan untuk penghitung backoff (default: `24`). +- `overloadedProfileRotations`: jumlah maksimum rotasi auth-profile provider yang sama untuk error overloaded sebelum beralih ke fallback model (default: `1`). Bentuk provider-busy seperti `ModelNotReadyException` masuk ke sini. +- `overloadedBackoffMs`: penundaan tetap sebelum mencoba ulang rotasi provider/profile yang overloaded (default: `0`). +- `rateLimitedProfileRotations`: jumlah maksimum rotasi auth-profile provider yang sama untuk error rate-limit sebelum beralih ke fallback model (default: `1`). Bucket rate-limit itu mencakup teks berbentuk provider seperti `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded`, dan `resource exhausted`. --- @@ -3540,8 +3530,8 @@ Catatan: - File log default: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. - Atur `logging.file` untuk path yang stabil. -- `consoleLevel` dinaikkan ke `debug` saat `--verbose`. -- `maxFileBytes`: ukuran file log maksimum dalam byte sebelum penulisan ditekan (integer positif; default: `524288000` = 500 MB). Gunakan rotasi log eksternal untuk deployment produksi. +- `consoleLevel` naik ke `debug` saat `--verbose`. +- `maxFileBytes`: ukuran file log maksimum dalam byte sebelum penulisan ditekan (bilangan bulat positif; default: `524288000` = 500 MB). Gunakan rotasi log eksternal untuk deployment produksi. --- @@ -3579,16 +3569,16 @@ Catatan: ``` - `enabled`: sakelar utama untuk output instrumentasi (default: `true`). -- `flags`: array string flag yang mengaktifkan output log terarah (mendukung wildcard seperti `"telegram.*"` atau `"*"`). -- `stuckSessionWarnMs`: ambang usia dalam ms untuk mengeluarkan peringatan sesi macet saat sebuah sesi tetap berada dalam status pemrosesan. +- `flags`: array string flag yang mengaktifkan output log tertarget (mendukung wildcard seperti `"telegram.*"` atau `"*"`). +- `stuckSessionWarnMs`: ambang usia dalam ms untuk mengeluarkan peringatan sesi macet saat sesi tetap berada dalam status pemrosesan. - `otel.enabled`: mengaktifkan pipeline ekspor OpenTelemetry (default: `false`). - `otel.endpoint`: URL collector untuk ekspor OTel. - `otel.protocol`: `"http/protobuf"` (default) atau `"grpc"`. - `otel.headers`: header metadata HTTP/gRPC tambahan yang dikirim bersama permintaan ekspor OTel. - `otel.serviceName`: nama layanan untuk atribut resource. -- `otel.traces` / `otel.metrics` / `otel.logs`: aktifkan ekspor trace, metrik, atau log. +- `otel.traces` / `otel.metrics` / `otel.logs`: aktifkan ekspor trace, metrics, atau log. - `otel.sampleRate`: laju sampling trace `0`–`1`. -- `otel.flushIntervalMs`: interval flush telemetri periodik dalam ms. +- `otel.flushIntervalMs`: interval flush telemetri berkala dalam ms. - `cacheTrace.enabled`: catat snapshot jejak cache untuk proses embedded (default: `false`). - `cacheTrace.filePath`: path output untuk JSONL jejak cache (default: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). - `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: mengontrol apa yang disertakan dalam output jejak cache (semuanya default: `true`). @@ -3614,10 +3604,10 @@ Catatan: ``` - `channel`: channel rilis untuk instalasi npm/git — `"stable"`, `"beta"`, atau `"dev"`. -- `checkOnStart`: periksa update npm saat gateway dimulai (default: `true`). -- `auto.enabled`: aktifkan auto-update latar belakang untuk instalasi paket (default: `false`). -- `auto.stableDelayHours`: jeda minimum dalam jam sebelum penerapan otomatis channel stable (default: `6`; maks: `168`). -- `auto.stableJitterHours`: jendela sebaran rollout channel stable tambahan dalam jam (default: `12`; maks: `168`). +- `checkOnStart`: periksa pembaruan npm saat gateway dimulai (default: `true`). +- `auto.enabled`: aktifkan auto-update latar belakang untuk instalasi package (default: `false`). +- `auto.stableDelayHours`: penundaan minimum dalam jam sebelum auto-apply channel stable (default: `6`; maks: `168`). +- `auto.stableJitterHours`: jendela penyebaran rollout channel stable tambahan dalam jam (default: `12`; maks: `168`). - `auto.betaCheckIntervalHours`: seberapa sering pemeriksaan channel beta berjalan dalam jam (default: `1`; maks: `24`). --- @@ -3651,22 +3641,22 @@ Catatan: } ``` -- `enabled`: gate fitur ACP global (default: `false`). -- `dispatch.enabled`: gate independen untuk dispatch turn sesi ACP (default: `true`). Atur `false` agar perintah ACP tetap tersedia sambil memblokir eksekusi. -- `backend`: id backend runtime ACP default (harus cocok dengan Plugin runtime ACP yang terdaftar). -- `defaultAgent`: id agen target ACP fallback saat spawn tidak menentukan target eksplisit. -- `allowedAgents`: allowlist id agen yang diizinkan untuk sesi runtime ACP; kosong berarti tidak ada pembatasan tambahan. -- `maxConcurrentSessions`: jumlah maksimum sesi ACP yang aktif secara bersamaan. -- `stream.coalesceIdleMs`: jendela flush idle dalam ms untuk teks yang di-stream. -- `stream.maxChunkChars`: ukuran potongan maksimum sebelum memisahkan proyeksi blok stream. -- `stream.repeatSuppression`: tekan baris status/alat yang berulang per turn (default: `true`). -- `stream.deliveryMode`: `"live"` melakukan stream secara bertahap; `"final_only"` menahan hingga event terminal turn. -- `stream.hiddenBoundarySeparator`: pemisah sebelum teks terlihat setelah event alat tersembunyi (default: `"paragraph"`). -- `stream.maxOutputChars`: jumlah maksimum karakter output asisten yang diproyeksikan per turn ACP. +- `enabled`: feature gate ACP global (default: `false`). +- `dispatch.enabled`: gate independen untuk dispatch giliran sesi ACP (default: `true`). Atur `false` untuk menjaga perintah ACP tetap tersedia sambil memblokir eksekusi. +- `backend`: id backend runtime ACP default (harus cocok dengan plugin runtime ACP terdaftar). +- `defaultAgent`: id agent target ACP fallback saat spawn tidak menentukan target eksplisit. +- `allowedAgents`: allowlist id agent yang diizinkan untuk sesi runtime ACP; kosong berarti tidak ada pembatasan tambahan. +- `maxConcurrentSessions`: jumlah maksimum sesi ACP aktif secara bersamaan. +- `stream.coalesceIdleMs`: jendela flush idle dalam ms untuk teks streaming. +- `stream.maxChunkChars`: ukuran chunk maksimum sebelum memecah proyeksi blok streaming. +- `stream.repeatSuppression`: menekan baris status/tool yang berulang per giliran (default: `true`). +- `stream.deliveryMode`: `"live"` melakukan stream bertahap; `"final_only"` menahan sampai event terminal giliran. +- `stream.hiddenBoundarySeparator`: separator sebelum teks terlihat setelah event tool tersembunyi (default: `"paragraph"`). +- `stream.maxOutputChars`: jumlah maksimum karakter output asisten yang diproyeksikan per giliran ACP. - `stream.maxSessionUpdateChars`: jumlah maksimum karakter untuk baris status/update ACP yang diproyeksikan. -- `stream.tagVisibility`: rekaman nama tag ke override visibilitas boolean untuk event yang di-stream. -- `runtime.ttlMinutes`: TTL idle dalam menit untuk worker sesi ACP sebelum memenuhi syarat untuk cleanup. -- `runtime.installCommand`: perintah instalasi opsional untuk dijalankan saat bootstrap lingkungan runtime ACP. +- `stream.tagVisibility`: catatan nama tag ke override visibilitas boolean untuk event streaming. +- `runtime.ttlMinutes`: TTL idle dalam menit untuk worker sesi ACP sebelum memenuhi syarat untuk dibersihkan. +- `runtime.installCommand`: perintah instalasi opsional yang dijalankan saat bootstrap lingkungan runtime ACP. --- @@ -3683,7 +3673,7 @@ Catatan: ``` - `cli.banner.taglineMode` mengontrol gaya tagline banner: - - `"random"` (default): tagline lucu/musiman yang berputar. + - `"random"` (default): tagline lucu/musiman yang bergilir. - `"default"`: tagline netral tetap (`All your chats, one OpenClaw.`). - `"off"`: tanpa teks tagline (judul/versi banner tetap ditampilkan). - Untuk menyembunyikan seluruh banner (bukan hanya tagline), atur env `OPENCLAW_HIDE_BANNER=1`. @@ -3692,7 +3682,7 @@ Catatan: ## Wizard -Metadata yang ditulis oleh alur penyiapan terpandu CLI (`onboard`, `configure`, `doctor`): +Metadata yang ditulis oleh alur setup berpemandu CLI (`onboard`, `configure`, `doctor`): ```json5 { @@ -3710,15 +3700,15 @@ Metadata yang ditulis oleh alur penyiapan terpandu CLI (`onboard`, `configure`, ## Identity -Lihat field identitas `agents.list` di bawah [Default agen](#agent-defaults). +Lihat field identity `agents.list` di bawah [Default agent](#agent-defaults). --- ## Bridge (lama, dihapus) -Build saat ini tidak lagi menyertakan bridge TCP. Node terhubung melalui WebSocket Gateway. Key `bridge.*` tidak lagi menjadi bagian dari schema config (validasi gagal sampai dihapus; `openclaw doctor --fix` dapat menghapus key yang tidak dikenal). +Build saat ini tidak lagi menyertakan bridge TCP. Node terhubung melalui Gateway WebSocket. Kunci `bridge.*` tidak lagi menjadi bagian dari schema config (validasi gagal sampai dihapus; `openclaw doctor --fix` dapat menghapus kunci yang tidak dikenal). - + ```json { @@ -3745,8 +3735,8 @@ Build saat ini tidak lagi menyertakan bridge TCP. Node terhubung melalui WebSock cron: { enabled: true, maxConcurrentRuns: 2, - webhook: "https://example.invalid/legacy", // fallback deprecated untuk pekerjaan tersimpan notify:true - webhookToken: "replace-with-dedicated-token", // bearer token opsional untuk auth webhook keluar + webhook: "https://example.invalid/legacy", // fallback deprecated untuk pekerjaan notify:true yang tersimpan + webhookToken: "replace-with-dedicated-token", // bearer token opsional untuk auth webhook outbound sessionRetention: "24h", // string durasi atau false runLog: { maxBytes: "2mb", // default 2_000_000 byte @@ -3756,11 +3746,11 @@ Build saat ini tidak lagi menyertakan bridge TCP. Node terhubung melalui WebSock } ``` -- `sessionRetention`: berapa lama menyimpan sesi proses Cron terisolasi yang telah selesai sebelum dipangkas dari `sessions.json`. Juga mengontrol cleanup transkrip Cron yang dihapus dan diarsipkan. Default: `24h`; atur `false` untuk menonaktifkan. +- `sessionRetention`: berapa lama menyimpan sesi proses Cron terisolasi yang telah selesai sebelum dipangkas dari `sessions.json`. Juga mengontrol pembersihan transkrip Cron terarsip yang sudah dihapus. Default: `24h`; atur `false` untuk menonaktifkan. - `runLog.maxBytes`: ukuran maksimum per file log proses (`cron/runs/.jsonl`) sebelum dipangkas. Default: `2_000_000` byte. - `runLog.keepLines`: baris terbaru yang dipertahankan saat pemangkasan run-log dipicu. Default: `2000`. - `webhookToken`: bearer token yang digunakan untuk pengiriman POST webhook Cron (`delivery.mode = "webhook"`), jika dihilangkan tidak ada header auth yang dikirim. -- `webhook`: URL webhook fallback lama yang deprecated (http/https) dan hanya digunakan untuk pekerjaan tersimpan yang masih memiliki `notify: true`. +- `webhook`: URL webhook fallback lama yang deprecated (http/https) yang hanya digunakan untuk pekerjaan tersimpan yang masih memiliki `notify: true`. ### `cron.retry` @@ -3777,10 +3767,10 @@ Build saat ini tidak lagi menyertakan bridge TCP. Node terhubung melalui WebSock ``` - `maxAttempts`: jumlah maksimum retry untuk pekerjaan one-shot pada error sementara (default: `3`; rentang: `0`–`10`). -- `backoffMs`: array delay backoff dalam ms untuk setiap percobaan retry (default: `[30000, 60000, 300000]`; 1–10 entri). -- `retryOn`: jenis error yang memicu retry — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Hilangkan untuk retry semua jenis sementara. +- `backoffMs`: array penundaan backoff dalam ms untuk setiap upaya retry (default: `[30000, 60000, 300000]`; 1–10 entri). +- `retryOn`: jenis error yang memicu retry — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Hilangkan untuk me-retry semua jenis sementara. -Berlaku hanya untuk pekerjaan Cron one-shot. Pekerjaan berulang menggunakan penanganan kegagalan terpisah. +Hanya berlaku untuk pekerjaan Cron one-shot. Pekerjaan berulang menggunakan penanganan kegagalan terpisah. ### `cron.failureAlert` @@ -3798,11 +3788,11 @@ Berlaku hanya untuk pekerjaan Cron one-shot. Pekerjaan berulang menggunakan pena } ``` -- `enabled`: aktifkan alert kegagalan untuk pekerjaan Cron (default: `false`). -- `after`: jumlah kegagalan berurutan sebelum alert dikirim (integer positif, min: `1`). -- `cooldownMs`: milidetik minimum antara alert berulang untuk pekerjaan yang sama (integer non-negatif). +- `enabled`: aktifkan peringatan kegagalan untuk pekerjaan Cron (default: `false`). +- `after`: jumlah kegagalan berurutan sebelum peringatan dipicu (bilangan bulat positif, min: `1`). +- `cooldownMs`: milidetik minimum antara peringatan berulang untuk pekerjaan yang sama (bilangan bulat non-negatif). - `mode`: mode pengiriman — `"announce"` mengirim melalui pesan channel; `"webhook"` melakukan POST ke webhook yang dikonfigurasi. -- `accountId`: ID akun atau channel opsional untuk membatasi cakupan pengiriman alert. +- `accountId`: id akun atau channel opsional untuk memberi cakupan pengiriman peringatan. ### `cron.failureDestination` @@ -3819,13 +3809,13 @@ Berlaku hanya untuk pekerjaan Cron one-shot. Pekerjaan berulang menggunakan pena } ``` -- Tujuan default untuk notifikasi kegagalan Cron di seluruh pekerjaan. +- Tujuan default untuk notifikasi kegagalan Cron di semua pekerjaan. - `mode`: `"announce"` atau `"webhook"`; default ke `"announce"` saat data target yang cukup tersedia. -- `channel`: override channel untuk pengiriman announce. `"last"` menggunakan kembali channel pengiriman terakhir yang diketahui. +- `channel`: override channel untuk pengiriman announce. `"last"` menggunakan ulang channel pengiriman terakhir yang diketahui. - `to`: target announce eksplisit atau URL webhook. Wajib untuk mode webhook. - `accountId`: override akun opsional untuk pengiriman. -- `delivery.failureDestination` per pekerjaan mengoverride default global ini. -- Saat tujuan kegagalan global maupun per pekerjaan tidak diatur, pekerjaan yang sudah mengirim melalui `announce` akan fallback ke target announce utama itu saat gagal. +- `delivery.failureDestination` per pekerjaan menimpa default global ini. +- Saat tujuan kegagalan global maupun per pekerjaan tidak diatur, pekerjaan yang sudah mengirim melalui `announce` menggunakan fallback ke target announce utama tersebut saat gagal. - `delivery.failureDestination` hanya didukung untuk pekerjaan `sessionTarget="isolated"` kecuali `delivery.mode` utama pekerjaan adalah `"webhook"`. Lihat [Cron Jobs](/id/automation/cron-jobs). Eksekusi Cron terisolasi dilacak sebagai [background tasks](/id/automation/tasks). @@ -3834,36 +3824,36 @@ Lihat [Cron Jobs](/id/automation/cron-jobs). Eksekusi Cron terisolasi dilacak se ## Variabel template model media -Placeholder template yang diperluas dalam `tools.media.models[].args`: +Placeholder template yang diekspansi dalam `tools.media.models[].args`: -| Variable | Deskripsi | -| ------------------ | --------------------------------------------- | -| `{{Body}}` | Isi pesan masuk lengkap | -| `{{RawBody}}` | Isi mentah (tanpa pembungkus riwayat/pengirim) | -| `{{BodyStripped}}` | Isi dengan mention grup dihapus | -| `{{From}}` | Identifier pengirim | -| `{{To}}` | Identifier tujuan | -| `{{MessageSid}}` | ID pesan channel | -| `{{SessionId}}` | UUID sesi saat ini | -| `{{IsNewSession}}` | `"true"` saat sesi baru dibuat | -| `{{MediaUrl}}` | Pseudo-URL media masuk | -| `{{MediaPath}}` | Path media lokal | -| `{{MediaType}}` | Jenis media (image/audio/document/…) | -| `{{Transcript}}` | Transkrip audio | -| `{{Prompt}}` | Prompt media yang telah di-resolve untuk entri CLI | -| `{{MaxChars}}` | Jumlah maksimum karakter output yang telah di-resolve untuk entri CLI | -| `{{ChatType}}` | `"direct"` atau `"group"` | -| `{{GroupSubject}}` | Subjek grup (best effort) | -| `{{GroupMembers}}` | Pratinjau anggota grup (best effort) | -| `{{SenderName}}` | Nama tampilan pengirim (best effort) | -| `{{SenderE164}}` | Nomor telepon pengirim (best effort) | -| `{{Provider}}` | Petunjuk provider (whatsapp, telegram, discord, dll.) | +| Variabel | Deskripsi | +| ------------------ | ---------------------------------------------- | +| `{{Body}}` | Isi penuh pesan masuk | +| `{{RawBody}}` | Isi mentah (tanpa wrapper riwayat/pengirim) | +| `{{BodyStripped}}` | Isi dengan mention grup dihapus | +| `{{From}}` | Identifier pengirim | +| `{{To}}` | Identifier tujuan | +| `{{MessageSid}}` | id pesan channel | +| `{{SessionId}}` | UUID sesi saat ini | +| `{{IsNewSession}}` | `"true"` saat sesi baru dibuat | +| `{{MediaUrl}}` | pseudo-URL media masuk | +| `{{MediaPath}}` | path media lokal | +| `{{MediaType}}` | jenis media (image/audio/document/…) | +| `{{Transcript}}` | transkrip audio | +| `{{Prompt}}` | prompt media yang sudah di-resolve untuk entri CLI | +| `{{MaxChars}}` | jumlah karakter output maksimum yang sudah di-resolve untuk entri CLI | +| `{{ChatType}}` | `"direct"` atau `"group"` | +| `{{GroupSubject}}` | subjek grup (usaha terbaik) | +| `{{GroupMembers}}` | pratinjau anggota grup (usaha terbaik) | +| `{{SenderName}}` | nama tampilan pengirim (usaha terbaik) | +| `{{SenderE164}}` | nomor telepon pengirim (usaha terbaik) | +| `{{Provider}}` | petunjuk provider (whatsapp, telegram, discord, dll.) | --- ## Include config (`$include`) -Pisahkan config ke beberapa file: +Bagi config ke beberapa file: ```json5 // ~/.openclaw/openclaw.json @@ -3876,15 +3866,15 @@ Pisahkan config ke beberapa file: } ``` -**Perilaku merge:** +**Perilaku penggabungan:** -- Satu file: menggantikan objek yang memuatnya. -- Array file: di-deep-merge secara berurutan (yang belakangan mengoverride yang sebelumnya). -- Key sejajar: digabung setelah include (mengoverride nilai yang di-include). +- File tunggal: menggantikan objek yang memuatnya. +- Array file: deep-merge secara berurutan (yang belakangan menimpa yang lebih awal). +- Kunci saudara: digabungkan setelah include (menimpa nilai yang di-include). - Include bertingkat: hingga 10 level kedalaman. -- Path: di-resolve relatif terhadap file yang melakukan include, tetapi harus tetap berada di dalam direktori config tingkat atas (`dirname` dari `openclaw.json`). Bentuk absolut/`../` diizinkan hanya jika tetap me-resolve di dalam batas tersebut. -- Error: pesan yang jelas untuk file yang hilang, parse error, dan include melingkar. +- Path: di-resolve relatif terhadap file yang meng-include, tetapi harus tetap berada di dalam direktori config tingkat atas (`dirname` dari `openclaw.json`). Bentuk absolut/`../` hanya diizinkan jika tetap di-resolve di dalam batas tersebut. +- Error: pesan yang jelas untuk file yang hilang, error parse, dan include melingkar. --- -_Terkait: [Konfigurasi](/id/gateway/configuration) · [Contoh Konfigurasi](/id/gateway/configuration-examples) · [Doctor](/id/gateway/doctor)_ +_Terkait: [Configuration](/id/gateway/configuration) · [Configuration Examples](/id/gateway/configuration-examples) · [Doctor](/id/gateway/doctor)_ diff --git a/docs/id/gateway/heartbeat.md b/docs/id/gateway/heartbeat.md index 5feb730e2..856be9097 100644 --- a/docs/id/gateway/heartbeat.md +++ b/docs/id/gateway/heartbeat.md @@ -1,14 +1,14 @@ --- read_when: - - Menyesuaikan irama heartbeat atau pesannya - - Menentukan antara heartbeat dan cron untuk tugas terjadwal -summary: Pesan polling heartbeat dan aturan notifikasi + - Menyesuaikan irama Heartbeat atau pesan-pesan Heartbeat + - Memutuskan antara Heartbeat dan Cron untuk tugas terjadwal +summary: Pesan polling Heartbeat dan aturan notifikasi title: Heartbeat x-i18n: - generated_at: "2026-04-11T02:44:41Z" + generated_at: "2026-04-22T09:14:37Z" model: gpt-5.4 provider: openai - source_hash: e4485072148753076d909867a623696829bf4a82dcd0479b95d5d0cae43100b0 + source_hash: 13004e4e20b02b08aaf16f22cdf664d0b59da69446ecb30453db51ffdfd1d267 source_path: gateway/heartbeat.md workflow: 15 --- @@ -17,25 +17,25 @@ x-i18n: > **Heartbeat vs Cron?** Lihat [Automation & Tasks](/id/automation) untuk panduan kapan menggunakan masing-masing. -Heartbeat menjalankan **giliran agen berkala** di sesi utama agar model dapat -menampilkan apa pun yang perlu diperhatikan tanpa membuat Anda kewalahan. +Heartbeat menjalankan **giliran agen periodik** di sesi utama agar model dapat +menampilkan apa pun yang perlu diperhatikan tanpa membanjiri Anda. -Heartbeat adalah giliran sesi utama yang terjadwal — ini **tidak** membuat catatan [background task](/id/automation/tasks). -Catatan task digunakan untuk pekerjaan yang terlepas (ACP run, subagen, isolated cron job). +Heartbeat adalah giliran sesi utama yang terjadwal — ini **tidak** membuat record [tugas latar belakang](/id/automation/tasks). +Record tugas digunakan untuk pekerjaan terlepas (run ACP, subagen, pekerjaan Cron terisolasi). Pemecahan masalah: [Scheduled Tasks](/id/automation/cron-jobs#troubleshooting) ## Mulai cepat (pemula) -1. Biarkan heartbeat tetap aktif (default adalah `30m`, atau `1h` untuk autentikasi Anthropic OAuth/token, termasuk penggunaan ulang Claude CLI) atau atur irama Anda sendiri. +1. Biarkan heartbeat tetap aktif (default adalah `30m`, atau `1h` untuk auth OAuth/token Anthropic, termasuk penggunaan ulang Claude CLI) atau atur ritme Anda sendiri. 2. Buat checklist `HEARTBEAT.md` kecil atau blok `tasks:` di workspace agen (opsional tetapi direkomendasikan). 3. Tentukan ke mana pesan heartbeat harus dikirim (`target: "none"` adalah default; setel `target: "last"` untuk mengarahkan ke kontak terakhir). 4. Opsional: aktifkan pengiriman reasoning heartbeat untuk transparansi. -5. Opsional: gunakan konteks bootstrap ringan jika heartbeat hanya perlu menjalankan `HEARTBEAT.md`. -6. Opsional: aktifkan sesi terisolasi agar riwayat percakapan penuh tidak dikirim pada setiap heartbeat. -7. Opsional: batasi heartbeat ke jam aktif (waktu lokal). +5. Opsional: gunakan konteks bootstrap ringan jika run heartbeat hanya memerlukan `HEARTBEAT.md`. +6. Opsional: aktifkan sesi terisolasi agar tidak mengirim seluruh riwayat percakapan pada setiap heartbeat. +7. Opsional: batasi heartbeat ke jam-jam aktif (waktu lokal). -Contoh konfigurasi: +Contoh config: ```json5 { @@ -44,11 +44,11 @@ Contoh konfigurasi: heartbeat: { every: "30m", target: "last", // pengiriman eksplisit ke kontak terakhir (default adalah "none") - directPolicy: "allow", // default: izinkan target direct/DM; setel "block" untuk menekan - lightContext: true, // opsional: hanya menyisipkan HEARTBEAT.md dari file bootstrap + directPolicy: "allow", // default: izinkan target langsung/DM; setel "block" untuk menekan + lightContext: true, // opsional: hanya menyuntikkan HEARTBEAT.md dari file bootstrap isolatedSession: true, // opsional: sesi baru setiap run (tanpa riwayat percakapan) // activeHours: { start: "08:00", end: "24:00" }, - // includeReasoning: true, // opsional: kirim pesan `Reasoning:` terpisah juga + // includeReasoning: true, // opsional: kirim juga pesan `Reasoning:` terpisah }, }, }, @@ -57,47 +57,47 @@ Contoh konfigurasi: ## Default -- Interval: `30m` (atau `1h` saat autentikasi Anthropic OAuth/token adalah mode autentikasi yang terdeteksi, termasuk penggunaan ulang Claude CLI). Setel `agents.defaults.heartbeat.every` atau `agents.list[].heartbeat.every`; gunakan `0m` untuk menonaktifkan. +- Interval: `30m` (atau `1h` saat auth OAuth/token Anthropic adalah mode auth yang terdeteksi, termasuk penggunaan ulang Claude CLI). Setel `agents.defaults.heartbeat.every` atau `agents.list[].heartbeat.every` per agen; gunakan `0m` untuk menonaktifkan. - Isi prompt (dapat dikonfigurasi melalui `agents.defaults.heartbeat.prompt`): `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.` -- Prompt heartbeat dikirim **apa adanya** sebagai pesan pengguna. System - prompt hanya menyertakan bagian “Heartbeat” saat heartbeat diaktifkan untuk agen - default, dan run tersebut ditandai secara internal. +- Prompt heartbeat dikirim **secara verbatim** sebagai pesan pengguna. Prompt sistem + menyertakan bagian “Heartbeat” hanya saat heartbeat diaktifkan untuk agen + default, dan run ditandai secara internal. - Saat heartbeat dinonaktifkan dengan `0m`, run normal juga menghilangkan `HEARTBEAT.md` - dari konteks bootstrap sehingga model tidak melihat instruksi yang khusus untuk heartbeat. + dari konteks bootstrap agar model tidak melihat instruksi khusus heartbeat. - Jam aktif (`heartbeat.activeHours`) diperiksa dalam zona waktu yang dikonfigurasi. - Di luar jendela tersebut, heartbeat dilewati sampai tick berikutnya di dalam jendela. + Di luar jendela waktu tersebut, heartbeat dilewati sampai tick berikutnya di dalam jendela. ## Untuk apa prompt heartbeat digunakan Prompt default sengaja dibuat luas: -- **Background task**: “Consider outstanding tasks” mendorong agen untuk meninjau - tindak lanjut yang belum selesai (inbox, kalender, pengingat, pekerjaan dalam antrean) dan menampilkan apa pun yang mendesak. -- **Check-in ke manusia**: “Checkup sometimes on your human during day time” mendorong - pesan ringan sesekali seperti “ada yang Anda butuhkan?”, tetapi menghindari spam di malam hari - dengan menggunakan zona waktu lokal yang Anda konfigurasikan (lihat [/concepts/timezone](/id/concepts/timezone)). +- **Tugas latar belakang**: “Pertimbangkan tugas yang belum selesai” mendorong agen untuk meninjau + tindak lanjut (inbox, kalender, pengingat, pekerjaan antre) dan menampilkan apa pun yang mendesak. +- **Check-in manusia**: “Kadang-kadang cek manusia Anda pada siang hari” mendorong + pesan ringan sesekali seperti “ada yang Anda perlukan?”, tetapi menghindari spam malam hari + dengan menggunakan zona waktu lokal yang Anda konfigurasi (lihat [/concepts/timezone](/id/concepts/timezone)). -Heartbeat dapat bereaksi terhadap [background task](/id/automation/tasks) yang selesai, tetapi run heartbeat itu sendiri tidak membuat catatan task. +Heartbeat dapat bereaksi terhadap [tugas latar belakang](/id/automation/tasks) yang selesai, tetapi run heartbeat itu sendiri tidak membuat record tugas. Jika Anda ingin heartbeat melakukan sesuatu yang sangat spesifik (misalnya “periksa statistik Gmail PubSub” atau “verifikasi kesehatan gateway”), setel `agents.defaults.heartbeat.prompt` (atau -`agents.list[].heartbeat.prompt`) ke isi khusus (dikirim apa adanya). +`agents.list[].heartbeat.prompt`) ke isi kustom (dikirim secara verbatim). ## Kontrak respons - Jika tidak ada yang perlu diperhatikan, balas dengan **`HEARTBEAT_OK`**. -- Selama run heartbeat, OpenClaw memperlakukan `HEARTBEAT_OK` sebagai ack saat muncul - di **awal atau akhir** balasan. Token tersebut dihapus dan balasan dibuang jika - konten yang tersisa **≤ `ackMaxChars`** (default: 300). +- Selama run heartbeat, OpenClaw memperlakukan `HEARTBEAT_OK` sebagai ack saat token itu muncul + di **awal atau akhir** balasan. Token tersebut dihapus dan balasannya + dibuang jika konten yang tersisa **≤ `ackMaxChars`** (default: 300). - Jika `HEARTBEAT_OK` muncul di **tengah** balasan, token itu tidak diperlakukan secara khusus. - Untuk peringatan, **jangan** sertakan `HEARTBEAT_OK`; kembalikan hanya teks peringatannya. -Di luar heartbeat, `HEARTBEAT_OK` yang muncul sendiri di awal/akhir pesan akan dihapus -dan dicatat dalam log; pesan yang hanya berisi `HEARTBEAT_OK` akan dibuang. +Di luar heartbeat, `HEARTBEAT_OK` yang terselip di awal/akhir pesan akan dihapus +dan dicatat; pesan yang hanya berisi `HEARTBEAT_OK` akan dibuang. -## Konfigurasi +## Config ```json5 { @@ -107,9 +107,9 @@ dan dicatat dalam log; pesan yang hanya berisi `HEARTBEAT_OK` akan dibuang. every: "30m", // default: 30m (0m menonaktifkan) model: "anthropic/claude-opus-4-6", includeReasoning: false, // default: false (kirim pesan Reasoning: terpisah saat tersedia) - lightContext: false, // default: false; true hanya menyimpan HEARTBEAT.md dari file bootstrap workspace + lightContext: false, // default: false; true hanya mempertahankan HEARTBEAT.md dari file bootstrap workspace isolatedSession: false, // default: false; true menjalankan setiap heartbeat di sesi baru (tanpa riwayat percakapan) - target: "last", // default: none | opsi: last | none | (inti atau plugin, mis. "bluebubbles") + target: "last", // default: none | opsi: last | none | (core atau plugin, mis. "bluebubbles") to: "+15551234567", // opsional override khusus channel accountId: "ops-bot", // id channel multi-akun opsional prompt: "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.", @@ -126,7 +126,7 @@ dan dicatat dalam log; pesan yang hanya berisi `HEARTBEAT_OK` akan dibuang. - `agents.list[].heartbeat` digabungkan di atasnya; jika ada agen yang memiliki blok `heartbeat`, **hanya agen tersebut** yang menjalankan heartbeat. - `channels.defaults.heartbeat` menetapkan default visibilitas untuk semua channel. - `channels..heartbeat` menimpa default channel. -- `channels..accounts..heartbeat` (channel multi-akun) menimpa per-channel. +- `channels..accounts..heartbeat` (channel multi-akun) menimpa per channel. ### Heartbeat per agen @@ -184,14 +184,14 @@ Batasi heartbeat ke jam kerja dalam zona waktu tertentu: } ``` -Di luar jendela ini (sebelum jam 9 pagi atau setelah jam 10 malam Eastern), heartbeat dilewati. Tick terjadwal berikutnya di dalam jendela akan berjalan seperti biasa. +Di luar jendela ini (sebelum pukul 9 pagi atau setelah pukul 10 malam waktu Eastern), heartbeat dilewati. Tick terjadwal berikutnya di dalam jendela akan berjalan seperti biasa. -### Konfigurasi 24/7 +### Penyiapan 24/7 Jika Anda ingin heartbeat berjalan sepanjang hari, gunakan salah satu pola berikut: - Hilangkan `activeHours` sepenuhnya (tanpa pembatasan jendela waktu; ini adalah perilaku default). -- Setel jendela sehari penuh: `activeHours: { start: "00:00", end: "24:00" }`. +- Setel jendela sepanjang hari: `activeHours: { start: "00:00", end: "24:00" }`. Jangan setel `start` dan `end` ke waktu yang sama (misalnya `08:00` hingga `08:00`). Itu diperlakukan sebagai jendela dengan lebar nol, sehingga heartbeat selalu dilewati. @@ -209,7 +209,7 @@ Gunakan `accountId` untuk menargetkan akun tertentu pada channel multi-akun sepe heartbeat: { every: "1h", target: "telegram", - to: "12345678:topic:42", // opsional: arahkan ke topic/thread tertentu + to: "12345678:topic:42", // opsional: arahkan ke topik/thread tertentu accountId: "ops-bot", }, }, @@ -229,53 +229,56 @@ Gunakan `accountId` untuk menargetkan akun tertentu pada channel multi-akun sepe - `every`: interval heartbeat (string durasi; unit default = menit). - `model`: override model opsional untuk run heartbeat (`provider/model`). -- `includeReasoning`: saat diaktifkan, juga mengirim pesan `Reasoning:` terpisah saat tersedia (bentuk yang sama seperti `/reasoning on`). +- `includeReasoning`: saat diaktifkan, kirim juga pesan `Reasoning:` terpisah saat tersedia (bentuk yang sama seperti `/reasoning on`). - `lightContext`: saat true, run heartbeat menggunakan konteks bootstrap ringan dan hanya mempertahankan `HEARTBEAT.md` dari file bootstrap workspace. -- `isolatedSession`: saat true, setiap heartbeat berjalan di sesi baru tanpa riwayat percakapan sebelumnya. Menggunakan pola isolasi yang sama seperti cron `sessionTarget: "isolated"`. Secara drastis mengurangi biaya token per heartbeat. Gabungkan dengan `lightContext: true` untuk penghematan maksimum. Routing pengiriman tetap menggunakan konteks sesi utama. +- `isolatedSession`: saat true, setiap heartbeat berjalan di sesi baru tanpa riwayat percakapan sebelumnya. Menggunakan pola isolasi yang sama seperti Cron `sessionTarget: "isolated"`. Secara drastis mengurangi biaya token per heartbeat. Gabungkan dengan `lightContext: true` untuk penghematan maksimum. Routing pengiriman tetap menggunakan konteks sesi utama. - `session`: kunci sesi opsional untuk run heartbeat. - `main` (default): sesi utama agen. - Kunci sesi eksplisit (salin dari `openclaw sessions --json` atau [sessions CLI](/cli/sessions)). - Format kunci sesi: lihat [Sessions](/id/concepts/session) dan [Groups](/id/channels/groups). - `target`: - - `last`: kirim ke channel eksternal yang terakhir digunakan. + - `last`: kirim ke channel eksternal terakhir yang digunakan. - channel eksplisit: channel atau id plugin yang dikonfigurasi, misalnya `discord`, `matrix`, `telegram`, atau `whatsapp`. - - `none` (default): jalankan heartbeat tetapi **jangan kirimkan** secara eksternal. -- `directPolicy`: mengontrol perilaku pengiriman direct/DM: - - `allow` (default): izinkan pengiriman heartbeat direct/DM. - - `block`: tekan pengiriman direct/DM (`reason=dm-blocked`). -- `to`: override penerima opsional (id khusus channel, misalnya E.164 untuk WhatsApp atau chat id Telegram). Untuk topic/thread Telegram, gunakan `:topic:`. -- `accountId`: id akun opsional untuk channel multi-akun. Saat `target: "last"`, id akun diterapkan ke channel terakhir yang telah di-resolve jika channel tersebut mendukung akun; jika tidak, nilai ini diabaikan. Jika id akun tidak cocok dengan akun yang dikonfigurasi untuk channel yang telah di-resolve, pengiriman dilewati. + - `none` (default): jalankan heartbeat tetapi **jangan kirim** secara eksternal. +- `directPolicy`: mengontrol perilaku pengiriman langsung/DM: + - `allow` (default): izinkan pengiriman heartbeat langsung/DM. + - `block`: tekan pengiriman langsung/DM (`reason=dm-blocked`). +- `to`: override penerima opsional (id khusus channel, mis. E.164 untuk WhatsApp atau id chat Telegram). Untuk topik/thread Telegram, gunakan `:topic:`. +- `accountId`: id akun opsional untuk channel multi-akun. Saat `target: "last"`, id akun berlaku untuk channel terakhir yang di-resolve jika channel tersebut mendukung akun; jika tidak, nilai ini diabaikan. Jika id akun tidak cocok dengan akun yang dikonfigurasi untuk channel yang di-resolve, pengiriman dilewati. - `prompt`: menimpa isi prompt default (tidak digabungkan). - `ackMaxChars`: jumlah karakter maksimum yang diizinkan setelah `HEARTBEAT_OK` sebelum pengiriman. -- `suppressToolErrorWarnings`: saat true, menekan payload peringatan kesalahan tool selama run heartbeat. -- `activeHours`: membatasi run heartbeat ke jendela waktu tertentu. Objek dengan `start` (HH:MM, inklusif; gunakan `00:00` untuk awal hari), `end` (HH:MM eksklusif; `24:00` diperbolehkan untuk akhir hari), dan `timezone` opsional. +- `suppressToolErrorWarnings`: saat true, menekan payload peringatan error tool selama run heartbeat. +- `activeHours`: membatasi run heartbeat ke jendela waktu. Objek dengan `start` (HH:MM, inklusif; gunakan `00:00` untuk awal hari), `end` (HH:MM eksklusif; `24:00` diperbolehkan untuk akhir hari), dan `timezone` opsional. - Dihilangkan atau `"user"`: menggunakan `agents.defaults.userTimezone` Anda jika disetel, jika tidak kembali ke zona waktu sistem host. - `"local"`: selalu menggunakan zona waktu sistem host. - - Pengidentifikasi IANA apa pun (mis. `America/New_York`): digunakan secara langsung; jika tidak valid, kembali ke perilaku `"user"` di atas. + - Pengidentifikasi IANA apa pun (mis. `America/New_York`): digunakan langsung; jika tidak valid, kembali ke perilaku `"user"` di atas. - `start` dan `end` tidak boleh sama untuk jendela aktif; nilai yang sama diperlakukan sebagai lebar nol (selalu di luar jendela). - Di luar jendela aktif, heartbeat dilewati sampai tick berikutnya di dalam jendela. ## Perilaku pengiriman - Heartbeat berjalan di sesi utama agen secara default (`agent::`), - atau `global` saat `session.scope = "global"`. Setel `session` untuk menimpa ke + atau `global` ketika `session.scope = "global"`. Setel `session` untuk menimpa ke sesi channel tertentu (Discord/WhatsApp/dll.). - `session` hanya memengaruhi konteks run; pengiriman dikendalikan oleh `target` dan `to`. - Untuk mengirim ke channel/penerima tertentu, setel `target` + `to`. Dengan `target: "last"`, pengiriman menggunakan channel eksternal terakhir untuk sesi tersebut. -- Pengiriman heartbeat mengizinkan target direct/DM secara default. Setel `directPolicy: "block"` untuk menekan pengiriman ke target direct sambil tetap menjalankan giliran heartbeat. +- Pengiriman heartbeat mengizinkan target langsung/DM secara default. Setel `directPolicy: "block"` untuk menekan pengiriman ke target langsung sambil tetap menjalankan giliran heartbeat. - Jika antrean utama sibuk, heartbeat dilewati dan dicoba lagi nanti. -- Jika `target` tidak di-resolve ke tujuan eksternal mana pun, run tetap terjadi tetapi tidak ada +- Jika `target` di-resolve ke tidak ada tujuan eksternal, run tetap terjadi tetapi tidak ada pesan keluar yang dikirim. - Jika `showOk`, `showAlerts`, dan `useIndicator` semuanya dinonaktifkan, run dilewati sejak awal sebagai `reason=alerts-disabled`. -- Jika hanya pengiriman peringatan yang dinonaktifkan, OpenClaw tetap dapat menjalankan heartbeat, memperbarui stempel waktu due-task, memulihkan stempel waktu idle sesi, dan menekan payload peringatan keluar. -- Balasan yang hanya untuk heartbeat **tidak** menjaga sesi tetap aktif; nilai `updatedAt` - terakhir dipulihkan agar masa kedaluwarsa idle tetap berperilaku normal. -- [Background task](/id/automation/tasks) yang terlepas dapat mengantrekan system event dan membangunkan heartbeat ketika sesi utama perlu menyadari sesuatu dengan cepat. Bangun ini tidak membuat run heartbeat menjadi background task. +- Jika hanya pengiriman alert yang dinonaktifkan, OpenClaw tetap dapat menjalankan heartbeat, memperbarui stempel waktu tugas yang jatuh tempo, memulihkan stempel waktu idle sesi, dan menekan payload alert keluar. +- Jika target heartbeat yang di-resolve mendukung indikator mengetik, OpenClaw menampilkan status mengetik saat + run heartbeat aktif. Ini menggunakan target yang sama dengan tempat heartbeat akan + mengirim output chat, dan dinonaktifkan oleh `typingMode: "never"`. +- Balasan khusus heartbeat **tidak** menjaga sesi tetap hidup; `updatedAt` + terakhir dipulihkan agar kedaluwarsa idle berperilaku normal. +- [Tugas latar belakang](/id/automation/tasks) yang terlepas dapat mengantrekan peristiwa sistem dan membangunkan heartbeat saat sesi utama perlu segera menyadari sesuatu. Bangun ini tidak menjadikan run heartbeat sebagai tugas latar belakang. ## Kontrol visibilitas -Secara default, ack `HEARTBEAT_OK` ditekan sementara konten peringatan tetap +Secara default, ack `HEARTBEAT_OK` ditekan sementara konten alert tetap dikirim. Anda dapat menyesuaikannya per channel atau per akun: ```yaml @@ -283,29 +286,29 @@ channels: defaults: heartbeat: showOk: false # Sembunyikan HEARTBEAT_OK (default) - showAlerts: true # Tampilkan pesan peringatan (default) - useIndicator: true # Pancarkan event indikator (default) + showAlerts: true # Tampilkan pesan alert (default) + useIndicator: true # Pancarkan peristiwa indikator (default) telegram: heartbeat: - showOk: true # Tampilkan acknowledgment OK di Telegram + showOk: true # Tampilkan ack OK di Telegram whatsapp: accounts: work: heartbeat: - showAlerts: false # Tekan pengiriman peringatan untuk akun ini + showAlerts: false # Tekan pengiriman alert untuk akun ini ``` -Prioritas: per-akun → per-channel → default channel → default bawaan. +Prioritas: per akun → per channel → default channel → default bawaan. ### Fungsi masing-masing flag -- `showOk`: mengirim acknowledgment `HEARTBEAT_OK` saat model mengembalikan balasan yang hanya berisi OK. -- `showAlerts`: mengirim konten peringatan saat model mengembalikan balasan non-OK. -- `useIndicator`: memancarkan event indikator untuk tampilan status UI. +- `showOk`: mengirim ack `HEARTBEAT_OK` saat model mengembalikan balasan khusus OK. +- `showAlerts`: mengirim konten alert saat model mengembalikan balasan non-OK. +- `useIndicator`: memancarkan peristiwa indikator untuk permukaan status UI. -Jika **ketiganya** false, OpenClaw melewati run heartbeat sepenuhnya (tanpa pemanggilan model). +Jika **ketiganya** bernilai false, OpenClaw melewati run heartbeat sepenuhnya (tanpa pemanggilan model). -### Contoh per-channel vs per-akun +### Contoh per channel vs per akun ```yaml channels: @@ -320,7 +323,7 @@ channels: accounts: ops: heartbeat: - showAlerts: false # tekan peringatan hanya untuk akun ops + showAlerts: false # tekan alert hanya untuk akun ops telegram: heartbeat: showOk: true @@ -328,39 +331,39 @@ channels: ### Pola umum -| Tujuan | Konfigurasi | +| Tujuan | Config | | ---------------------------------------- | ---------------------------------------------------------------------------------------- | -| Perilaku default (OK senyap, peringatan aktif) | _(tidak perlu konfigurasi)_ | +| Perilaku default (OK senyap, alert aktif) | _(tidak perlu config)_ | | Sepenuhnya senyap (tanpa pesan, tanpa indikator) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }` | | Hanya indikator (tanpa pesan) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }` | | OK hanya di satu channel | `channels.telegram.heartbeat: { showOk: true }` | -## HEARTBEAT.md (opsional) +## `HEARTBEAT.md` (opsional) Jika file `HEARTBEAT.md` ada di workspace, prompt default memberi tahu agen untuk membacanya. Anggap ini sebagai “checklist heartbeat” Anda: kecil, stabil, dan aman untuk disertakan setiap 30 menit. -Pada run normal, `HEARTBEAT.md` hanya disisipkan saat panduan heartbeat -diaktifkan untuk agen default. Menonaktifkan irama heartbeat dengan `0m` atau -menyetel `includeSystemPromptSection: false` akan menghilangkannya dari konteks bootstrap -normal. +Pada run normal, `HEARTBEAT.md` hanya disuntikkan saat panduan heartbeat +diaktifkan untuk agen default. Menonaktifkan ritme heartbeat dengan `0m` atau +menyetel `includeSystemPromptSection: false` akan menghilangkannya dari konteks +bootstrap normal. -Jika `HEARTBEAT.md` ada tetapi pada dasarnya kosong (hanya baris kosong dan heading -markdown seperti `# Heading`), OpenClaw melewati run heartbeat untuk menghemat pemanggilan API. -Lewatan ini dilaporkan sebagai `reason=empty-heartbeat-file`. +Jika `HEARTBEAT.md` ada tetapi secara efektif kosong (hanya baris kosong dan header markdown +seperti `# Heading`), OpenClaw melewati run heartbeat untuk menghemat pemanggilan API. +Pelewatan itu dilaporkan sebagai `reason=empty-heartbeat-file`. Jika file tidak ada, heartbeat tetap berjalan dan model memutuskan apa yang harus dilakukan. -Pertahankan ukurannya kecil (checklist pendek atau pengingat) untuk menghindari prompt yang membengkak. +Buat tetap kecil (checklist singkat atau pengingat) agar prompt tidak membengkak. Contoh `HEARTBEAT.md`: ```md -# Checklist heartbeat +# Checklist Heartbeat -- Pindai cepat: adakah hal mendesak di inbox? +- Pemindaian cepat: ada yang mendesak di inbox? - Jika siang hari, lakukan check-in ringan jika tidak ada hal lain yang tertunda. -- Jika sebuah tugas terhambat, tuliskan _apa yang kurang_ dan tanyakan ke Peter lain kali. +- Jika sebuah tugas terblokir, tuliskan _apa yang kurang_ dan tanyakan kepada Peter lain kali. ``` ### Blok `tasks:` @@ -378,45 +381,45 @@ tasks: prompt: "Periksa email belum dibaca yang mendesak dan tandai apa pun yang sensitif terhadap waktu." - name: calendar-scan interval: 2h - prompt: "Periksa rapat mendatang yang perlu persiapan atau tindak lanjut." + prompt: "Periksa rapat mendatang yang memerlukan persiapan atau tindak lanjut." # Instruksi tambahan -- Buat peringatan tetap singkat. -- Jika tidak ada yang perlu diperhatikan setelah semua tugas jatuh tempo, balas HEARTBEAT_OK. +- Buat alert tetap singkat. +- Jika tidak ada yang perlu diperhatikan setelah semua tugas yang jatuh tempo, balas HEARTBEAT_OK. ``` Perilaku: -- OpenClaw mengurai blok `tasks:` dan memeriksa setiap tugas terhadap `interval` miliknya sendiri. +- OpenClaw mem-parsing blok `tasks:` dan memeriksa setiap tugas terhadap `interval` masing-masing. - Hanya tugas yang **jatuh tempo** yang disertakan dalam prompt heartbeat untuk tick tersebut. - Jika tidak ada tugas yang jatuh tempo, heartbeat dilewati sepenuhnya (`reason=no-tasks-due`) untuk menghindari pemanggilan model yang sia-sia. -- Konten non-task di `HEARTBEAT.md` dipertahankan dan ditambahkan sebagai konteks tambahan setelah daftar tugas yang jatuh tempo. -- Stempel waktu terakhir dijalankan untuk tugas disimpan di status sesi (`heartbeatTaskState`), sehingga interval tetap bertahan setelah restart normal. -- Stempel waktu tugas hanya dimajukan setelah run heartbeat menyelesaikan jalur balasan normalnya. Run `empty-heartbeat-file` / `no-tasks-due` yang dilewati tidak menandai tugas sebagai selesai. +- Konten non-tugas di `HEARTBEAT.md` dipertahankan dan ditambahkan sebagai konteks tambahan setelah daftar tugas yang jatuh tempo. +- Stempel waktu run terakhir tugas disimpan di state sesi (`heartbeatTaskState`), sehingga interval tetap bertahan setelah restart normal. +- Stempel waktu tugas hanya dimajukan setelah run heartbeat menyelesaikan jalur balasan normalnya. Run yang dilewati karena `empty-heartbeat-file` / `no-tasks-due` tidak menandai tugas sebagai selesai. -Mode task berguna saat Anda ingin satu file heartbeat menampung beberapa pemeriksaan berkala tanpa harus membayar semua pemeriksaan itu pada setiap tick. +Mode tugas berguna saat Anda ingin satu file heartbeat memuat beberapa pemeriksaan periodik tanpa harus membayar semuanya di setiap tick. -### Bisakah agen memperbarui HEARTBEAT.md? +### Bisakah agen memperbarui `HEARTBEAT.md`? Ya — jika Anda memintanya. -`HEARTBEAT.md` hanyalah file biasa di workspace agen, jadi Anda dapat memberi tahu +`HEARTBEAT.md` hanyalah file normal di workspace agen, jadi Anda dapat memberi tahu agen (dalam chat normal) sesuatu seperti: - “Perbarui `HEARTBEAT.md` untuk menambahkan pemeriksaan kalender harian.” - “Tulis ulang `HEARTBEAT.md` agar lebih singkat dan fokus pada tindak lanjut inbox.” Jika Anda ingin ini terjadi secara proaktif, Anda juga dapat menyertakan baris eksplisit dalam -prompt heartbeat Anda seperti: “Jika checklist mulai usang, perbarui HEARTBEAT.md +prompt heartbeat Anda seperti: “Jika checklist menjadi usang, perbarui HEARTBEAT.md dengan versi yang lebih baik.” -Catatan keamanan: jangan menaruh rahasia (API key, nomor telepon, token privat) ke dalam +Catatan keamanan: jangan masukkan rahasia (kunci API, nomor telepon, token pribadi) ke dalam `HEARTBEAT.md` — file ini menjadi bagian dari konteks prompt. ## Bangun manual (sesuai permintaan) -Anda dapat mengantrekan system event dan memicu heartbeat segera dengan: +Anda dapat mengantrekan peristiwa sistem dan memicu heartbeat segera dengan: ```bash openclaw system event --text "Check for urgent follow-ups" --mode now @@ -428,31 +431,31 @@ Gunakan `--mode next-heartbeat` untuk menunggu tick terjadwal berikutnya. ## Pengiriman reasoning (opsional) -Secara default, heartbeat hanya mengirim payload “jawaban” final. +Secara default, heartbeat hanya mengirim payload “jawaban” akhir. Jika Anda menginginkan transparansi, aktifkan: - `agents.defaults.heartbeat.includeReasoning: true` -Saat diaktifkan, heartbeat juga akan mengirim pesan terpisah yang diawali -dengan `Reasoning:` (bentuk yang sama seperti `/reasoning on`). Ini dapat berguna ketika agen -mengelola beberapa sesi/codex dan Anda ingin melihat mengapa ia memutuskan untuk menghubungi -Anda — tetapi ini juga dapat membocorkan lebih banyak detail internal daripada yang Anda inginkan. Sebaiknya biarkan tetap -nonaktif di chat grup. +Saat diaktifkan, heartbeat juga akan mengirim pesan terpisah dengan prefiks +`Reasoning:` (bentuk yang sama seperti `/reasoning on`). Ini dapat berguna saat agen +mengelola beberapa sesi/codex dan Anda ingin melihat mengapa agen memutuskan untuk menghubungi +Anda — tetapi ini juga dapat membocorkan lebih banyak detail internal daripada yang Anda inginkan. Sebaiknya tetap dimatikan +di chat grup. ## Kesadaran biaya -Heartbeat menjalankan giliran agen penuh. Interval yang lebih pendek menghabiskan lebih banyak token. Untuk mengurangi biaya: +Heartbeat menjalankan giliran agen penuh. Interval yang lebih pendek membakar lebih banyak token. Untuk mengurangi biaya: -- Gunakan `isolatedSession: true` agar tidak mengirim riwayat percakapan penuh (~100K token turun menjadi ~2-5K per run). +- Gunakan `isolatedSession: true` agar tidak mengirim seluruh riwayat percakapan (~100K token turun menjadi ~2-5K per run). - Gunakan `lightContext: true` untuk membatasi file bootstrap hanya ke `HEARTBEAT.md`. - Setel `model` yang lebih murah (mis. `ollama/llama3.2:1b`). -- Buat `HEARTBEAT.md` tetap kecil. -- Gunakan `target: "none"` jika Anda hanya ingin pembaruan status internal. +- Jaga `HEARTBEAT.md` tetap kecil. +- Gunakan `target: "none"` jika Anda hanya menginginkan pembaruan state internal. ## Terkait - [Automation & Tasks](/id/automation) — semua mekanisme otomatisasi secara ringkas -- [Background Tasks](/id/automation/tasks) — cara pekerjaan terlepas dilacak +- [Background Tasks](/id/automation/tasks) — bagaimana pekerjaan terlepas dilacak - [Timezone](/id/concepts/timezone) — bagaimana zona waktu memengaruhi penjadwalan heartbeat - [Troubleshooting](/id/automation/cron-jobs#troubleshooting) — men-debug masalah otomatisasi diff --git a/docs/id/plugins/building-plugins.md b/docs/id/plugins/building-plugins.md index 6413a4523..16eb2e989 100644 --- a/docs/id/plugins/building-plugins.md +++ b/docs/id/plugins/building-plugins.md @@ -2,64 +2,64 @@ read_when: - Anda ingin membuat plugin OpenClaw baru - Anda memerlukan panduan mulai cepat untuk pengembangan plugin - - Anda sedang menambahkan saluran, penyedia, alat, atau kapabilitas lain baru ke OpenClaw + - Anda sedang menambahkan channel, provider, tool, atau kapabilitas lain baru ke OpenClaw sidebarTitle: Getting Started summary: Buat plugin OpenClaw pertama Anda dalam hitungan menit title: Membangun Plugin x-i18n: - generated_at: "2026-04-07T09:15:56Z" + generated_at: "2026-04-22T09:14:37Z" model: gpt-5.4 provider: openai - source_hash: 509c1f5abe1a0a74966054ed79b71a1a7ee637a43b1214c424acfe62ddf48eef + source_hash: 67368be311537f984f14bea9239b88c3eccf72a76c9dd1347bb041e02697ae24 source_path: plugins/building-plugins.md workflow: 15 --- # Membangun Plugin -Plugin memperluas OpenClaw dengan kapabilitas baru: saluran, penyedia model, -speech, realtime transcription, realtime voice, media understanding, image -generation, video generation, web fetch, web search, agent tools, atau -kombinasi apa pun. +Plugin memperluas OpenClaw dengan kapabilitas baru: channel, penyedia model, +speech, transkripsi realtime, suara realtime, pemahaman media, pembuatan +gambar, pembuatan video, web fetch, web search, tool agen, atau kombinasi apa +pun. Anda tidak perlu menambahkan plugin Anda ke repositori OpenClaw. Publikasikan ke -[ClawHub](/id/tools/clawhub) atau npm dan pengguna dapat memasangnya dengan +[ClawHub](/id/tools/clawhub) atau npm dan pengguna memasang dengan `openclaw plugins install `. OpenClaw mencoba ClawHub terlebih dahulu dan -secara otomatis fallback ke npm. +secara otomatis menggunakan npm sebagai cadangan. ## Prasyarat - Node >= 22 dan package manager (npm atau pnpm) - Familiar dengan TypeScript (ESM) -- Untuk plugin di dalam repo: repositori sudah di-clone dan `pnpm install` sudah dijalankan +- Untuk plugin dalam repo: repositori sudah di-clone dan `pnpm install` sudah dijalankan ## Plugin jenis apa? - - Hubungkan OpenClaw ke platform pesan (Discord, IRC, dll.) + + Hubungkan OpenClaw ke platform perpesanan (Discord, IRC, dll.) - - Tambahkan penyedia model (LLM, proxy, atau endpoint kustom) + + Tambahkan provider model (LLM, proxy, atau endpoint kustom) - - Daftarkan agent tools, event hooks, atau service — lanjutkan di bawah + + Daftarkan tool agen, hook peristiwa, atau layanan — lanjutkan di bawah -Jika plugin saluran bersifat opsional dan mungkin belum terpasang saat onboarding/setup +Jika plugin channel bersifat opsional dan mungkin belum dipasang saat onboarding/penyiapan berjalan, gunakan `createOptionalChannelSetupSurface(...)` dari -`openclaw/plugin-sdk/channel-setup`. Fungsi ini menghasilkan pasangan adapter setup + wizard -yang mengiklankan persyaratan instalasi dan gagal secara tertutup pada penulisan config nyata +`openclaw/plugin-sdk/channel-setup`. Ini menghasilkan pasangan adapter + wizard penyiapan +yang mengiklankan persyaratan instalasi dan gagal tertutup pada penulisan konfigurasi nyata sampai plugin dipasang. -## Mulai cepat: plugin alat +## Mulai cepat: plugin tool -Panduan ini membuat plugin minimal yang mendaftarkan agent tool. Plugin saluran -dan penyedia memiliki panduan khusus yang ditautkan di atas. +Panduan ini membuat plugin minimal yang mendaftarkan tool agen. Plugin channel +dan provider memiliki panduan khusus yang ditautkan di atas. - + ```json package.json { @@ -84,7 +84,7 @@ dan penyedia memiliki panduan khusus yang ditautkan di atas. { "id": "my-plugin", "name": "My Plugin", - "description": "Adds a custom tool to OpenClaw", + "description": "Menambahkan tool kustom ke OpenClaw", "configSchema": { "type": "object", "additionalProperties": false @@ -93,13 +93,13 @@ dan penyedia memiliki panduan khusus yang ditautkan di atas. ``` - Setiap plugin memerlukan manifest, bahkan tanpa config. Lihat - [Manifest](/id/plugins/manifest) untuk skema lengkapnya. Snippet publish ClawHub - kanonis berada di `docs/snippets/plugin-publish/`. + Setiap plugin memerlukan manifes, bahkan tanpa konfigurasi. Lihat + [Manifest](/id/plugins/manifest) untuk skema lengkapnya. Cuplikan publikasi ClawHub + kanonis tersedia di `docs/snippets/plugin-publish/`. - + ```typescript // index.ts @@ -123,9 +123,9 @@ dan penyedia memiliki panduan khusus yang ditautkan di atas. }); ``` - `definePluginEntry` digunakan untuk plugin non-saluran. Untuk saluran, gunakan - `defineChannelPluginEntry` — lihat [Plugin Saluran](/id/plugins/sdk-channel-plugins). - Untuk opsi entry point lengkap, lihat [Entry Points](/id/plugins/sdk-entrypoints). + `definePluginEntry` digunakan untuk plugin non-channel. Untuk channel, gunakan + `defineChannelPluginEntry` — lihat [Plugin Channel](/id/plugins/sdk-channel-plugins). + Untuk opsi titik masuk lengkap, lihat [Titik Masuk](/id/plugins/sdk-entrypoints). @@ -139,10 +139,10 @@ dan penyedia memiliki panduan khusus yang ditautkan di atas. openclaw plugins install clawhub:@myorg/openclaw-my-plugin ``` - OpenClaw juga memeriksa ClawHub sebelum npm untuk spesifikasi package polos seperti - `@myorg/openclaw-my-plugin`. + OpenClaw juga memeriksa ClawHub sebelum npm untuk + spesifikasi paket polos seperti `@myorg/openclaw-my-plugin`. - **Plugin di dalam repo:** tempatkan di bawah pohon workspace plugin bundel — akan ditemukan secara otomatis. + **Plugin dalam repo:** tempatkan di bawah pohon workspace plugin bawaan — akan terdeteksi secara otomatis. ```bash pnpm test -- /my-plugin/ @@ -155,44 +155,49 @@ dan penyedia memiliki panduan khusus yang ditautkan di atas. Satu plugin dapat mendaftarkan sejumlah kapabilitas apa pun melalui objek `api`: -| Kapabilitas | Metode pendaftaran | Panduan terperinci | -| --------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------- | -| Inferensi teks (LLM) | `api.registerProvider(...)` | [Plugin Penyedia](/id/plugins/sdk-provider-plugins) | -| Backend inferensi CLI | `api.registerCliBackend(...)` | [Backend CLI](/id/gateway/cli-backends) | -| Saluran / pesan | `api.registerChannel(...)` | [Plugin Saluran](/id/plugins/sdk-channel-plugins) | -| Speech (TTS/STT) | `api.registerSpeechProvider(...)` | [Plugin Penyedia](/id/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Realtime transcription | `api.registerRealtimeTranscriptionProvider(...)` | [Plugin Penyedia](/id/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Realtime voice | `api.registerRealtimeVoiceProvider(...)` | [Plugin Penyedia](/id/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Media understanding | `api.registerMediaUnderstandingProvider(...)` | [Plugin Penyedia](/id/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Image generation | `api.registerImageGenerationProvider(...)` | [Plugin Penyedia](/id/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Music generation | `api.registerMusicGenerationProvider(...)` | [Plugin Penyedia](/id/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Video generation | `api.registerVideoGenerationProvider(...)` | [Plugin Penyedia](/id/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Web fetch | `api.registerWebFetchProvider(...)` | [Plugin Penyedia](/id/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Web search | `api.registerWebSearchProvider(...)` | [Plugin Penyedia](/id/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Agent tools | `api.registerTool(...)` | Di bawah | -| Perintah kustom | `api.registerCommand(...)` | [Entry Points](/id/plugins/sdk-entrypoints) | -| Event hooks | `api.registerHook(...)` | [Entry Points](/id/plugins/sdk-entrypoints) | -| Rute HTTP | `api.registerHttpRoute(...)` | [Internal](/id/plugins/architecture#gateway-http-routes) | -| Subperintah CLI | `api.registerCli(...)` | [Entry Points](/id/plugins/sdk-entrypoints) | +| Kapabilitas | Metode pendaftaran | Panduan terperinci | +| --------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------- | +| Inferensi teks (LLM) | `api.registerProvider(...)` | [Plugin Provider](/id/plugins/sdk-provider-plugins) | +| Backend inferensi CLI | `api.registerCliBackend(...)` | [Backend CLI](/id/gateway/cli-backends) | +| Channel / perpesanan | `api.registerChannel(...)` | [Plugin Channel](/id/plugins/sdk-channel-plugins) | +| Speech (TTS/STT) | `api.registerSpeechProvider(...)` | [Plugin Provider](/id/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Transkripsi realtime | `api.registerRealtimeTranscriptionProvider(...)` | [Plugin Provider](/id/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Suara realtime | `api.registerRealtimeVoiceProvider(...)` | [Plugin Provider](/id/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Pemahaman media | `api.registerMediaUnderstandingProvider(...)` | [Plugin Provider](/id/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Pembuatan gambar | `api.registerImageGenerationProvider(...)` | [Plugin Provider](/id/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Pembuatan musik | `api.registerMusicGenerationProvider(...)` | [Plugin Provider](/id/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Pembuatan video | `api.registerVideoGenerationProvider(...)` | [Plugin Provider](/id/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Web fetch | `api.registerWebFetchProvider(...)` | [Plugin Provider](/id/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Web search | `api.registerWebSearchProvider(...)` | [Plugin Provider](/id/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Ekstensi Pi tertanam | `api.registerEmbeddedExtensionFactory(...)` | [Ikhtisar SDK](/id/plugins/sdk-overview#registration-api) | +| Tool agen | `api.registerTool(...)` | Di bawah | +| Perintah kustom | `api.registerCommand(...)` | [Titik Masuk](/id/plugins/sdk-entrypoints) | +| Hook peristiwa | `api.registerHook(...)` | [Titik Masuk](/id/plugins/sdk-entrypoints) | +| Rute HTTP | `api.registerHttpRoute(...)` | [Internal](/id/plugins/architecture#gateway-http-routes) | +| Subperintah CLI | `api.registerCli(...)` | [Titik Masuk](/id/plugins/sdk-entrypoints) | Untuk API pendaftaran lengkap, lihat [Ikhtisar SDK](/id/plugins/sdk-overview#registration-api). -Jika plugin Anda mendaftarkan metode RPC gateway kustom, simpan metode tersebut pada -prefix khusus plugin. Namespace admin inti (`config.*`, +Gunakan `api.registerEmbeddedExtensionFactory(...)` saat plugin memerlukan hook embedded-runner +native Pi seperti penulisan ulang async `tool_result` sebelum pesan hasil tool akhir +dikirim. Pilih hook plugin OpenClaw biasa bila pekerjaan tersebut tidak memerlukan waktu ekstensi Pi. + +Jika plugin Anda mendaftarkan metode RPC Gateway kustom, pertahankan pada +prefiks khusus plugin. Namespace admin inti (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) tetap dicadangkan dan selalu di-resolve ke `operator.admin`, meskipun plugin meminta cakupan yang lebih sempit. Semantik guard hook yang perlu diingat: -- `before_tool_call`: `{ block: true }` bersifat terminal dan menghentikan handler dengan prioritas lebih rendah. +- `before_tool_call`: `{ block: true }` bersifat terminal dan menghentikan handler prioritas lebih rendah. - `before_tool_call`: `{ block: false }` diperlakukan sebagai tidak ada keputusan. -- `before_tool_call`: `{ requireApproval: true }` menjeda eksekusi agent dan meminta persetujuan pengguna melalui overlay persetujuan exec, tombol Telegram, interaksi Discord, atau perintah `/approve` di saluran mana pun. -- `before_install`: `{ block: true }` bersifat terminal dan menghentikan handler dengan prioritas lebih rendah. +- `before_tool_call`: `{ requireApproval: true }` menjeda eksekusi agen dan meminta persetujuan pengguna melalui overlay persetujuan exec, tombol Telegram, interaksi Discord, atau perintah `/approve` di channel mana pun. +- `before_install`: `{ block: true }` bersifat terminal dan menghentikan handler prioritas lebih rendah. - `before_install`: `{ block: false }` diperlakukan sebagai tidak ada keputusan. -- `message_sending`: `{ cancel: true }` bersifat terminal dan menghentikan handler dengan prioritas lebih rendah. +- `message_sending`: `{ cancel: true }` bersifat terminal dan menghentikan handler prioritas lebih rendah. - `message_sending`: `{ cancel: false }` diperlakukan sebagai tidak ada keputusan. -Perintah `/approve` menangani persetujuan exec dan plugin dengan fallback terbatas: ketika ID persetujuan exec tidak ditemukan, OpenClaw mencoba ulang ID yang sama melalui persetujuan plugin. Forwarding persetujuan plugin dapat dikonfigurasi secara independen melalui `approvals.plugin` di config. +Perintah `/approve` menangani persetujuan exec dan plugin dengan fallback terbatas: saat id persetujuan exec tidak ditemukan, OpenClaw mencoba lagi id yang sama melalui persetujuan plugin. Penerusan persetujuan plugin dapat dikonfigurasi secara terpisah melalui `approvals.plugin` dalam config. Jika plumbing persetujuan kustom perlu mendeteksi kasus fallback terbatas yang sama, gunakan `isApprovalNotFoundError` dari `openclaw/plugin-sdk/error-runtime` @@ -200,10 +205,10 @@ alih-alih mencocokkan string kedaluwarsa persetujuan secara manual. Lihat [Semantik keputusan hook Ikhtisar SDK](/id/plugins/sdk-overview#hook-decision-semantics) untuk detailnya. -## Mendaftarkan agent tools +## Mendaftarkan tool agen -Tools adalah fungsi bertipe yang dapat dipanggil LLM. Tools dapat bersifat wajib (selalu -tersedia) atau opsional (memerlukan opt-in pengguna): +Tool adalah fungsi bertipe yang dapat dipanggil oleh LLM. Tool dapat bersifat wajib (selalu +tersedia) atau opsional (pengguna ikut serta): ```typescript register(api) { @@ -217,7 +222,7 @@ register(api) { }, }); - // Tool opsional — pengguna harus menambahkannya ke allowlist + // Tool opsional — pengguna harus menambahkan ke allowlist api.registerTool( { name: "workflow_tool", @@ -232,7 +237,7 @@ register(api) { } ``` -Pengguna mengaktifkan tool opsional di config: +Pengguna mengaktifkan tool opsional dalam config: ```json5 { @@ -242,11 +247,11 @@ Pengguna mengaktifkan tool opsional di config: - Nama tool tidak boleh bentrok dengan tool inti (konflik akan dilewati) - Gunakan `optional: true` untuk tool dengan efek samping atau persyaratan biner tambahan -- Pengguna dapat mengaktifkan semua tool dari sebuah plugin dengan menambahkan ID plugin ke `tools.allow` +- Pengguna dapat mengaktifkan semua tool dari sebuah plugin dengan menambahkan id plugin ke `tools.allow` -## Konvensi import +## Konvensi impor -Selalu import dari path `openclaw/plugin-sdk/` yang terfokus: +Selalu impor dari path terfokus `openclaw/plugin-sdk/`: ```typescript import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; @@ -259,69 +264,69 @@ import { ... } from "openclaw/plugin-sdk"; Untuk referensi subpath lengkap, lihat [Ikhtisar SDK](/id/plugins/sdk-overview). Di dalam plugin Anda, gunakan file barrel lokal (`api.ts`, `runtime-api.ts`) untuk -import internal — jangan pernah mengimpor plugin Anda sendiri melalui path SDK-nya. +impor internal — jangan pernah mengimpor plugin Anda sendiri melalui path SDK-nya. -Untuk plugin penyedia, simpan helper khusus penyedia dalam barrel akar package tersebut -kecuali jika seam-nya benar-benar generik. Contoh bundel saat ini: +Untuk plugin provider, simpan helper khusus provider di barrel akar paket tersebut +kecuali jika seam-nya benar-benar generik. Contoh bawaan saat ini: -- Anthropic: wrapper stream Claude dan helper `service_tier` / beta -- OpenAI: builder penyedia, helper model default, penyedia realtime -- OpenRouter: builder penyedia plus helper onboarding/config +- Anthropic: pembungkus stream Claude dan helper `service_tier` / beta +- OpenAI: builder provider, helper model default, provider realtime +- OpenRouter: builder provider plus helper onboarding/config -Jika sebuah helper hanya berguna di dalam satu package penyedia bundel, simpan helper itu pada -seam akar package tersebut alih-alih mempromosikannya ke `openclaw/plugin-sdk/*`. +Jika sebuah helper hanya berguna di dalam satu paket provider bawaan, simpan di +seam akar paket tersebut alih-alih mempromosikannya ke `openclaw/plugin-sdk/*`. Beberapa seam helper `openclaw/plugin-sdk/` yang dihasilkan masih ada untuk -pemeliharaan plugin bundel dan kompatibilitas, misalnya -`plugin-sdk/feishu-setup` atau `plugin-sdk/zalo-setup`. Perlakukan itu sebagai -permukaan yang dicadangkan, bukan sebagai pola default untuk plugin pihak ketiga baru. +pemeliharaan dan kompatibilitas plugin bawaan, misalnya +`plugin-sdk/feishu-setup` atau `plugin-sdk/zalo-setup`. Anggap ini sebagai +surface yang dicadangkan, bukan pola default untuk plugin pihak ketiga baru. -## Checklist sebelum pengiriman +## Daftar periksa pra-pengiriman -**package.json** memiliki metadata `openclaw` yang benar -Manifest **openclaw.plugin.json** ada dan valid -Entry point menggunakan `defineChannelPluginEntry` atau `definePluginEntry` -Semua import menggunakan path `plugin-sdk/` yang terfokus -Import internal menggunakan modul lokal, bukan self-import SDK +Metadata `openclaw` di **package.json** sudah benar +Manifes **openclaw.plugin.json** ada dan valid +Titik masuk menggunakan `defineChannelPluginEntry` atau `definePluginEntry` +Semua impor menggunakan path terfokus `plugin-sdk/` +Impor internal menggunakan modul lokal, bukan self-import SDK Pengujian lulus (`pnpm test -- /my-plugin/`) -`pnpm check` lulus (plugin di dalam repo) +`pnpm check` lulus (plugin dalam repo) ## Pengujian Rilis Beta -1. Pantau tag rilis GitHub di [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) dan berlangganan melalui `Watch` > `Releases`. Tag beta terlihat seperti `v2026.3.N-beta.1`. Anda juga dapat mengaktifkan notifikasi untuk akun X resmi OpenClaw [@openclaw](https://x.com/openclaw) untuk pengumuman rilis. +1. Pantau tag rilis GitHub di [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) dan berlangganan melalui `Watch` > `Releases`. Tag beta terlihat seperti `v2026.3.N-beta.1`. Anda juga dapat menyalakan notifikasi untuk akun X resmi OpenClaw [@openclaw](https://x.com/openclaw) untuk pengumuman rilis. 2. Uji plugin Anda terhadap tag beta segera setelah muncul. Jendela sebelum rilis stabil biasanya hanya beberapa jam. -3. Posting di thread plugin Anda di saluran Discord `plugin-forum` setelah pengujian dengan `all good` atau apa yang rusak. Jika Anda belum memiliki thread, buat satu. -4. Jika ada yang rusak, buka atau perbarui issue berjudul `Beta blocker: - ` dan terapkan label `beta-blocker`. Letakkan tautan issue di thread Anda. -5. Buka PR ke `main` berjudul `fix(): beta blocker - ` dan tautkan issue tersebut di PR maupun thread Discord Anda. Kontributor tidak dapat memberi label pada PR, jadi judul adalah sinyal sisi-PR untuk maintainer dan otomasi. Blocker dengan PR akan digabungkan; blocker tanpa PR mungkin tetap dirilis. Maintainer memantau thread-thread ini selama pengujian beta. -6. Tidak ada kabar berarti aman. Jika Anda melewatkan jendela itu, perbaikan Anda kemungkinan masuk pada siklus berikutnya. +3. Kirim di thread plugin Anda di channel Discord `plugin-forum` setelah pengujian dengan `all good` atau apa yang rusak. Jika Anda belum memiliki thread, buat satu. +4. Jika ada yang rusak, buka atau perbarui issue berjudul `Beta blocker: - ` dan terapkan label `beta-blocker`. Cantumkan tautan issue di thread Anda. +5. Buka PR ke `main` berjudul `fix(): beta blocker - ` dan tautkan issue tersebut di PR maupun thread Discord Anda. Kontributor tidak dapat memberi label pada PR, jadi judul adalah sinyal sisi-PR untuk maintainer dan otomasi. Blocker yang memiliki PR akan digabungkan; blocker tanpa PR mungkin tetap dirilis. Maintainer memantau thread-thread ini selama pengujian beta. +6. Jika tidak ada kabar, berarti aman. Jika Anda melewatkan jendelanya, perbaikan Anda kemungkinan masuk di siklus berikutnya. ## Langkah berikutnya - - Bangun plugin saluran pesan + + Bangun plugin channel perpesanan - - Bangun plugin penyedia model + + Bangun plugin provider model - Peta import dan referensi API pendaftaran + Peta impor dan referensi API pendaftaran - TTS, pencarian, subagent melalui api.runtime + TTS, pencarian, subagen melalui api.runtime Utilitas dan pola pengujian - - Referensi skema manifest lengkap + + Referensi skema manifes lengkap ## Terkait -- [Arsitektur Plugin](/id/plugins/architecture) — penjelasan mendalam arsitektur internal -- [Ikhtisar SDK](/id/plugins/sdk-overview) — referensi Plugin SDK -- [Manifest](/id/plugins/manifest) — format manifest plugin -- [Plugin Saluran](/id/plugins/sdk-channel-plugins) — membangun plugin saluran -- [Plugin Penyedia](/id/plugins/sdk-provider-plugins) — membangun plugin penyedia +- [Arsitektur Plugin](/id/plugins/architecture) — pendalaman arsitektur internal +- [Ikhtisar SDK](/id/plugins/sdk-overview) — referensi SDK Plugin +- [Manifest](/id/plugins/manifest) — format manifes plugin +- [Plugin Channel](/id/plugins/sdk-channel-plugins) — membangun plugin channel +- [Plugin Provider](/id/plugins/sdk-provider-plugins) — membangun plugin provider diff --git a/docs/id/plugins/codex-harness.md b/docs/id/plugins/codex-harness.md index b2746174c..373988dbc 100644 --- a/docs/id/plugins/codex-harness.md +++ b/docs/id/plugins/codex-harness.md @@ -1,46 +1,44 @@ --- read_when: - Anda ingin menggunakan harness app-server Codex bawaan - - Anda memerlukan referensi model Codex dan contoh config + - Anda memerlukan referensi model Codex dan contoh konfigurasi - Anda ingin menonaktifkan fallback PI untuk deployment khusus Codex -summary: Jalankan giliran agent embedded OpenClaw melalui harness app-server Codex bawaan +summary: Jalankan giliran agen tersemat OpenClaw melalui harness app-server Codex bawaan title: Harness Codex x-i18n: - generated_at: "2026-04-21T09:20:09Z" + generated_at: "2026-04-22T09:14:37Z" model: gpt-5.4 provider: openai - source_hash: 3f0cdaf68be3b2257de1046103ff04f53f9d3a65ffc15ab7af5ab1f425643d6c + source_hash: 19bc7481bf7cdce983efe70e697f8665ace875d96f126979b95dd3f2f739fa8a source_path: plugins/codex-harness.md workflow: 15 --- # Harness Codex -Plugin `codex` bawaan memungkinkan OpenClaw menjalankan giliran agent embedded melalui -app-server Codex alih-alih harness PI bawaan. +Plugin `codex` bawaan memungkinkan OpenClaw menjalankan giliran agen tersemat melalui app-server Codex alih-alih harness PI bawaan. -Gunakan ini saat Anda ingin Codex memiliki sesi agent level rendah: penemuan -model, resume thread native, Compaction native, dan eksekusi app-server. -OpenClaw tetap memiliki channel chat, file sesi, pemilihan model, tool, -persetujuan, pengiriman media, dan cermin transkrip yang terlihat. +Gunakan ini saat Anda ingin Codex memiliki kendali atas sesi agen tingkat rendah: penemuan model, pelanjutan thread native, Compaction native, dan eksekusi app-server. +OpenClaw tetap memiliki kendali atas kanal chat, file sesi, pemilihan model, tool, +persetujuan, pengiriman media, dan cerminan transkrip yang terlihat. Harness ini nonaktif secara default. Harness ini dipilih hanya saat plugin `codex` -diaktifkan dan model yang diselesaikan adalah model `codex/*`, atau saat Anda secara eksplisit +diaktifkan dan model hasil resolusi adalah model `codex/*`, atau saat Anda secara eksplisit memaksa `embeddedHarness.runtime: "codex"` atau `OPENCLAW_AGENT_RUNTIME=codex`. -Jika Anda tidak pernah mengonfigurasi `codex/*`, run PI, OpenAI, Anthropic, Gemini, local, -dan custom-provider yang ada tetap mempertahankan perilaku saat ini. +Jika Anda tidak pernah mengonfigurasi `codex/*`, proses PI, OpenAI, Anthropic, Gemini, local, +dan custom-provider yang ada akan tetap mempertahankan perilaku saat ini. ## Pilih prefiks model yang tepat OpenClaw memiliki rute terpisah untuk akses berbentuk OpenAI dan Codex: -| Referensi model | Jalur runtime | Gunakan saat | -| --------------------- | -------------------------------------------- | ------------------------------------------------------------------------- | -| `openai/gpt-5.4` | Provider OpenAI melalui plumbing OpenClaw/PI | Anda ingin akses API OpenAI Platform langsung dengan `OPENAI_API_KEY`. | -| `openai-codex/gpt-5.4` | Provider OAuth OpenAI Codex melalui PI | Anda ingin OAuth ChatGPT/Codex tanpa harness app-server Codex. | -| `codex/gpt-5.4` | Provider Codex bawaan plus harness Codex | Anda ingin eksekusi app-server Codex native untuk giliran agent embedded. | +| Ref model | Jalur runtime | Gunakan saat | +| ---------------------- | -------------------------------------------- | ------------------------------------------------------------------------- | +| `openai/gpt-5.4` | Provider OpenAI melalui alur OpenClaw/PI | Anda ingin akses API OpenAI Platform langsung dengan `OPENAI_API_KEY`. | +| `openai-codex/gpt-5.4` | Provider OpenAI Codex OAuth melalui PI | Anda ingin ChatGPT/Codex OAuth tanpa harness app-server Codex. | +| `codex/gpt-5.4` | Provider Codex bawaan plus harness Codex | Anda ingin eksekusi app-server Codex native untuk giliran agen tersemat. | -Harness Codex hanya mengambil referensi model `codex/*`. Referensi `openai/*`, +Harness Codex hanya menangani ref model `codex/*`. Ref `openai/*`, `openai-codex/*`, Anthropic, Gemini, xAI, local, dan custom provider yang ada tetap menggunakan jalur normalnya. @@ -48,16 +46,16 @@ menggunakan jalur normalnya. - OpenClaw dengan plugin `codex` bawaan tersedia. - App-server Codex `0.118.0` atau yang lebih baru. -- Auth Codex tersedia untuk proses app-server. +- Autentikasi Codex tersedia untuk proses app-server. -Plugin ini memblokir handshake app-server yang lebih lama atau tanpa versi. Itu menjaga -OpenClaw tetap pada surface protokol yang sudah diuji. +Plugin ini memblokir handshake app-server yang lebih lama atau tanpa versi. Ini menjaga +OpenClaw tetap berada pada permukaan protokol yang sudah diuji. -Untuk smoke test live dan Docker, auth biasanya berasal dari `OPENAI_API_KEY`, ditambah +Untuk smoke test live dan Docker, autentikasi biasanya berasal dari `OPENAI_API_KEY`, ditambah file CLI Codex opsional seperti `~/.codex/auth.json` dan -`~/.codex/config.toml`. Gunakan materi auth yang sama seperti yang digunakan app-server Codex lokal Anda. +`~/.codex/config.toml`. Gunakan materi autentikasi yang sama dengan yang digunakan app-server Codex lokal Anda. -## Config minimal +## Konfigurasi minimal Gunakan `codex/gpt-5.4`, aktifkan plugin bawaan, dan paksa harness `codex`: @@ -82,7 +80,7 @@ Gunakan `codex/gpt-5.4`, aktifkan plugin bawaan, dan paksa harness `codex`: } ``` -Jika config Anda menggunakan `plugins.allow`, sertakan `codex` di sana juga: +Jika konfigurasi Anda menggunakan `plugins.allow`, sertakan juga `codex` di sana: ```json5 { @@ -97,9 +95,9 @@ Jika config Anda menggunakan `plugins.allow`, sertakan `codex` di sana juga: } ``` -Menyetel `agents.defaults.model` atau model agent ke `codex/` juga -mengaktifkan otomatis plugin `codex` bawaan. Entri plugin eksplisit tetap -berguna dalam config bersama karena membuat niat deployment menjadi jelas. +Menyetel `agents.defaults.model` atau model agen ke `codex/` juga +akan otomatis mengaktifkan plugin `codex` bawaan. Entri plugin eksplisit tetap +berguna dalam konfigurasi bersama karena membuat maksud deployment menjadi jelas. ## Tambahkan Codex tanpa mengganti model lain @@ -145,7 +143,7 @@ Dengan bentuk ini: ## Deployment khusus Codex -Nonaktifkan fallback PI saat Anda perlu membuktikan bahwa setiap giliran agent embedded menggunakan +Nonaktifkan fallback PI saat Anda perlu membuktikan bahwa setiap giliran agen tersemat menggunakan harness Codex: ```json5 @@ -162,7 +160,7 @@ harness Codex: } ``` -Override environment: +Override lingkungan: ```bash OPENCLAW_AGENT_RUNTIME=codex \ @@ -171,12 +169,12 @@ openclaw gateway run ``` Dengan fallback dinonaktifkan, OpenClaw gagal lebih awal jika plugin Codex dinonaktifkan, -model yang diminta bukan referensi `codex/*`, app-server terlalu lama, atau +model yang diminta bukan ref `codex/*`, app-server terlalu lama, atau app-server tidak dapat dimulai. -## Codex per-agent +## Codex per agen -Anda dapat membuat satu agent khusus Codex sementara agent default tetap menggunakan +Anda dapat membuat satu agen khusus Codex sementara agen default tetap menggunakan pemilihan otomatis normal: ```json5 @@ -208,20 +206,20 @@ pemilihan otomatis normal: } ``` -Gunakan perintah sesi normal untuk mengganti agent dan model. `/new` membuat -sesi OpenClaw baru dan harness Codex membuat atau me-resume thread sidecar app-server +Gunakan perintah sesi normal untuk berpindah agen dan model. `/new` membuat sesi +OpenClaw baru dan harness Codex membuat atau melanjutkan thread sidecar app-server sesuai kebutuhan. `/reset` menghapus binding sesi OpenClaw untuk thread tersebut. ## Penemuan model -Secara default, plugin Codex meminta model yang tersedia dari app-server. Jika -penemuan gagal atau timeout, plugin ini menggunakan katalog fallback bawaan: +Secara default, plugin Codex meminta model yang tersedia ke app-server. Jika +penemuan gagal atau habis waktu, plugin ini menggunakan katalog fallback bawaan: - `codex/gpt-5.4` - `codex/gpt-5.4-mini` - `codex/gpt-5.2` -Anda dapat menyesuaikan penemuan di bawah `plugins.entries.codex.config.discovery`: +Anda dapat menyetel penemuan di bawah `plugins.entries.codex.config.discovery`: ```json5 { @@ -241,7 +239,7 @@ Anda dapat menyesuaikan penemuan di bawah `plugins.entries.codex.config.discover } ``` -Nonaktifkan penemuan saat Anda ingin startup menghindari probing Codex dan tetap pada +Nonaktifkan penemuan saat Anda ingin startup menghindari probing Codex dan tetap menggunakan katalog fallback: ```json5 @@ -269,9 +267,12 @@ Secara default, plugin memulai Codex secara lokal dengan: codex app-server --listen stdio:// ``` -Secara default, OpenClaw meminta Codex untuk meminta persetujuan native. Anda dapat menyesuaikan -kebijakan itu lebih lanjut, misalnya dengan memperketatnya dan merutekan review melalui -guardian: +Secara default, OpenClaw memulai sesi harness Codex lokal sepenuhnya tanpa batas: +`approvalPolicy: "never"` dan `sandbox: "danger-full-access"`. Ini sesuai dengan +postur operator lokal tepercaya yang digunakan oleh CLI Codex dan memungkinkan +Heartbeat otonom menggunakan tool jaringan dan shell tanpa menunggu jalur +persetujuan native tak terlihat. Anda dapat memperketat kebijakan tersebut, misalnya +dengan merutekan peninjauan melalui guardian: ```json5 { @@ -319,20 +320,20 @@ Field `appServer` yang didukung: | Field | Default | Arti | | ------------------- | ---------------------------------------- | ----------------------------------------------------------------------- | -| `transport` | `"stdio"` | `"stdio"` memunculkan Codex; `"websocket"` terhubung ke `url`. | +| `transport` | `"stdio"` | `"stdio"` menjalankan Codex; `"websocket"` terhubung ke `url`. | | `command` | `"codex"` | Executable untuk transport stdio. | | `args` | `["app-server", "--listen", "stdio://"]` | Argumen untuk transport stdio. | | `url` | unset | URL app-server WebSocket. | -| `authToken` | unset | Token Bearer untuk transport WebSocket. | +| `authToken` | unset | Token bearer untuk transport WebSocket. | | `headers` | `{}` | Header WebSocket tambahan. | | `requestTimeoutMs` | `60000` | Timeout untuk panggilan control-plane app-server. | -| `approvalPolicy` | `"on-request"` | Kebijakan persetujuan Codex native yang dikirim ke start/resume/turn thread. | -| `sandbox` | `"workspace-write"` | Mode sandbox Codex native yang dikirim ke start/resume thread. | +| `approvalPolicy` | `"never"` | Kebijakan persetujuan Codex native yang dikirim ke start/resume/turn thread. | +| `sandbox` | `"danger-full-access"` | Mode sandbox Codex native yang dikirim ke start/resume thread. | | `approvalsReviewer` | `"user"` | Gunakan `"guardian_subagent"` agar guardian Codex meninjau persetujuan native. | | `serviceTier` | unset | Tingkat layanan Codex opsional, misalnya `"priority"`. | -Environment variable lama masih berfungsi sebagai fallback untuk pengujian lokal saat -field config yang cocok tidak disetel: +Variabel lingkungan lama masih berfungsi sebagai fallback untuk pengujian lokal saat +field konfigurasi yang sesuai tidak disetel: - `OPENCLAW_CODEX_APP_SERVER_BIN` - `OPENCLAW_CODEX_APP_SERVER_ARGS` @@ -340,7 +341,7 @@ field config yang cocok tidak disetel: - `OPENCLAW_CODEX_APP_SERVER_SANDBOX` - `OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` -Config lebih dipilih untuk deployment yang dapat diulang. +Konfigurasi lebih disarankan untuk deployment yang dapat diulang. ## Resep umum @@ -396,7 +397,7 @@ Persetujuan Codex yang ditinjau guardian: } ``` -App-server remote dengan header eksplisit: +App-server jarak jauh dengan header eksplisit: ```json5 { @@ -419,63 +420,65 @@ App-server remote dengan header eksplisit: } ``` -Peralihan model tetap dikendalikan oleh OpenClaw. Saat sesi OpenClaw terpasang -ke thread Codex yang sudah ada, giliran berikutnya mengirim model `codex/*`, -provider, kebijakan persetujuan, sandbox, dan service tier yang saat ini dipilih ke +Peralihan model tetap dikendalikan OpenClaw. Saat sesi OpenClaw dilampirkan +ke thread Codex yang sudah ada, giliran berikutnya mengirim model +`codex/*`, provider, kebijakan persetujuan, sandbox, dan tingkat layanan yang saat ini dipilih ke app-server lagi. Beralih dari `codex/gpt-5.4` ke `codex/gpt-5.2` mempertahankan -binding thread tetapi meminta Codex melanjutkan dengan model yang baru dipilih. +binding thread tetapi meminta Codex untuk melanjutkan dengan model yang baru dipilih. ## Perintah Codex -Plugin bawaan mendaftarkan `/codex` sebagai perintah slash yang diotorisasi. Perintah ini -generik dan berfungsi di channel apa pun yang mendukung perintah teks OpenClaw. +Plugin bawaan mendaftarkan `/codex` sebagai slash command yang diotorisasi. Perintah ini +bersifat generik dan berfungsi di kanal apa pun yang mendukung perintah teks OpenClaw. Bentuk umum: - `/codex status` menampilkan konektivitas app-server live, model, akun, rate limit, server MCP, dan Skills. -- `/codex models` mencantumkan model app-server Codex live. -- `/codex threads [filter]` mencantumkan thread Codex terbaru. -- `/codex resume ` memasang sesi OpenClaw saat ini ke thread Codex yang sudah ada. -- `/codex compact` meminta app-server Codex untuk melakukan Compaction pada thread yang terpasang. -- `/codex review` memulai review native Codex untuk thread yang terpasang. -- `/codex account` menampilkan akun dan status rate limit. -- `/codex mcp` mencantumkan status server MCP app-server Codex. -- `/codex skills` mencantumkan Skills app-server Codex. +- `/codex models` menampilkan daftar model app-server Codex live. +- `/codex threads [filter]` menampilkan daftar thread Codex terbaru. +- `/codex resume ` melampirkan sesi OpenClaw saat ini ke thread Codex yang sudah ada. +- `/codex compact` meminta app-server Codex untuk melakukan Compaction pada thread yang terlampir. +- `/codex review` memulai peninjauan native Codex untuk thread yang terlampir. +- `/codex account` menampilkan status akun dan rate limit. +- `/codex mcp` menampilkan daftar status server MCP app-server Codex. +- `/codex skills` menampilkan daftar Skills app-server Codex. -`/codex resume` menulis file binding sidecar yang sama yang digunakan harness untuk -giliran normal. Pada pesan berikutnya, OpenClaw me-resume thread Codex tersebut, meneruskan -model OpenClaw `codex/*` yang sedang dipilih ke app-server, dan tetap mengaktifkan +`/codex resume` menulis file binding sidecar yang sama seperti yang digunakan harness untuk +giliran normal. Pada pesan berikutnya, OpenClaw melanjutkan thread Codex tersebut, meneruskan model OpenClaw `codex/*` yang saat ini dipilih ke app-server, dan tetap mengaktifkan riwayat yang diperluas. -Surface perintah ini memerlukan app-server Codex `0.118.0` atau yang lebih baru. Metode kontrol individual -dilaporkan sebagai `unsupported by this Codex app-server` jika -app-server masa depan atau kustom tidak mengekspos metode JSON-RPC tersebut. +Permukaan perintah ini memerlukan app-server Codex `0.118.0` atau yang lebih baru. Metode kontrol individual dilaporkan sebagai `unsupported by this Codex app-server` jika +app-server versi masa depan atau kustom tidak mengekspos metode JSON-RPC tersebut. -## Tools, media, dan Compaction +## Tool, media, dan Compaction -Harness Codex hanya mengubah eksekutor agent embedded tingkat rendah. +Harness Codex hanya mengubah eksekutor agen tersemat tingkat rendah. OpenClaw tetap membangun daftar tool dan menerima hasil tool dinamis dari -harness. Teks, gambar, video, musik, TTS, persetujuan, dan output messaging-tool +harness. Teks, gambar, video, musik, TTS, persetujuan, dan output tool perpesanan tetap melalui jalur pengiriman OpenClaw normal. -Saat model yang dipilih menggunakan harness Codex, Compaction thread native didelegasikan -ke app-server Codex. OpenClaw mempertahankan cermin transkrip untuk riwayat channel, -pencarian, `/new`, `/reset`, dan peralihan model atau harness di masa depan. Cermin ini -mencakup prompt pengguna, teks asisten final, dan catatan reasoning atau plan Codex yang ringan saat app-server mengeluarkannya. +Saat model yang dipilih menggunakan harness Codex, Compaction thread native +didelegasikan ke app-server Codex. OpenClaw tetap menyimpan cerminan transkrip untuk +riwayat kanal, pencarian, `/new`, `/reset`, dan peralihan model atau harness di masa depan. Cerminan tersebut +mencakup prompt pengguna, teks asisten akhir, dan catatan penalaran atau rencana Codex yang ringan ketika app-server mengeluarkannya. -Generasi media tidak memerlukan PI. Gambar, video, musik, PDF, TTS, dan -pemahaman media tetap menggunakan pengaturan provider/model yang cocok seperti +Pembuatan media tidak memerlukan PI. Gambar, video, musik, PDF, TTS, dan +pemahaman media tetap menggunakan pengaturan provider/model yang sesuai seperti `agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel`, dan `messages.tts`. ## Pemecahan masalah **Codex tidak muncul di `/model`:** aktifkan `plugins.entries.codex.enabled`, -setel referensi model `codex/*`, atau periksa apakah `plugins.allow` mengecualikan `codex`. +setel ref model `codex/*`, atau periksa apakah `plugins.allow` mengecualikan `codex`. -**OpenClaw fallback ke PI:** setel `embeddedHarness.fallback: "none"` atau -`OPENCLAW_AGENT_HARNESS_FALLBACK=none` saat pengujian. +**OpenClaw menggunakan PI alih-alih Codex:** jika tidak ada harness Codex yang menangani proses ini, +OpenClaw dapat menggunakan PI sebagai backend kompatibilitas. Setel +`embeddedHarness.runtime: "codex"` untuk memaksa pemilihan Codex saat pengujian, atau +`embeddedHarness.fallback: "none"` agar gagal saat tidak ada harness plugin yang cocok. Setelah +app-server Codex dipilih, kegagalannya akan muncul langsung tanpa +konfigurasi fallback tambahan. **App-server ditolak:** upgrade Codex agar handshake app-server melaporkan versi `0.118.0` atau yang lebih baru. @@ -484,14 +487,14 @@ melaporkan versi `0.118.0` atau yang lebih baru. atau nonaktifkan penemuan. **Transport WebSocket langsung gagal:** periksa `appServer.url`, `authToken`, -dan bahwa app-server remote berbicara dengan versi protokol app-server Codex yang sama. +dan pastikan app-server jarak jauh menggunakan versi protokol app-server Codex yang sama. -**Model non-Codex menggunakan PI:** itu memang diharapkan. Harness Codex hanya mengambil -referensi model `codex/*`. +**Model non-Codex menggunakan PI:** itu memang diharapkan. Harness Codex hanya menangani +ref model `codex/*`. ## Terkait -- [Agent Harness Plugins](/id/plugins/sdk-agent-harness) -- [Model Providers](/id/concepts/model-providers) -- [Configuration Reference](/id/gateway/configuration-reference) -- [Testing](/id/help/testing#live-codex-app-server-harness-smoke) +- [Plugin Harness Agen](/id/plugins/sdk-agent-harness) +- [Provider Model](/id/concepts/model-providers) +- [Referensi Konfigurasi](/id/gateway/configuration-reference) +- [Pengujian](/id/help/testing#live-codex-app-server-harness-smoke) diff --git a/docs/id/plugins/manifest.md b/docs/id/plugins/manifest.md index 42407d6a2..7fa2902aa 100644 --- a/docs/id/plugins/manifest.md +++ b/docs/id/plugins/manifest.md @@ -1,78 +1,79 @@ --- read_when: - Anda sedang membangun plugin OpenClaw - - Anda perlu mengirimkan skema konfigurasi plugin atau men-debug error validasi plugin -summary: Manifest Plugin + persyaratan skema JSON (validasi konfigurasi ketat) -title: Manifest Plugin + - Anda perlu mengirimkan skema konfigurasi plugin atau men-debug kesalahan validasi plugin +summary: Persyaratan manifes Plugin + skema JSON (validasi konfigurasi ketat) +title: Manifes Plugin x-i18n: - generated_at: "2026-04-22T04:23:54Z" + generated_at: "2026-04-22T09:14:37Z" model: gpt-5.4 provider: openai - source_hash: 52a52f7e2c78bbef2cc51ade6eb12b6edc950237bdfc478f6e82248374c687bf + source_hash: 085c1baccb96b8e6bd4033ad11bdd5f79bdb0daec470e977fce723c3ae38cc99 source_path: plugins/manifest.md workflow: 15 --- -# Manifest Plugin (`openclaw.plugin.json`) +# Manifes Plugin (`openclaw.plugin.json`) -Halaman ini hanya untuk **manifest plugin OpenClaw native**. +Halaman ini hanya untuk **manifes plugin OpenClaw native**. -Untuk layout bundle yang kompatibel, lihat [Plugin bundles](/id/plugins/bundles). +Untuk tata letak bundle yang kompatibel, lihat [Bundle plugin](/id/plugins/bundles). -Format bundle yang kompatibel menggunakan file manifest yang berbeda: +Format bundle yang kompatibel menggunakan file manifes yang berbeda: - Bundle Codex: `.codex-plugin/plugin.json` -- Bundle Claude: `.claude-plugin/plugin.json` atau layout komponen Claude default - tanpa manifest +- Bundle Claude: `.claude-plugin/plugin.json` atau tata letak komponen Claude default + tanpa manifes - Bundle Cursor: `.cursor-plugin/plugin.json` -OpenClaw juga mendeteksi otomatis layout bundle tersebut, tetapi tidak divalidasi +OpenClaw juga mendeteksi tata letak bundle tersebut secara otomatis, tetapi tidak divalidasi terhadap skema `openclaw.plugin.json` yang dijelaskan di sini. -Untuk bundle yang kompatibel, OpenClaw saat ini membaca metadata bundle plus -root Skills yang dideklarasikan, root perintah Claude, default `settings.json` bundle Claude, -default LSP bundle Claude, dan hook pack yang didukung saat layout-nya cocok +Untuk bundle yang kompatibel, OpenClaw saat ini membaca metadata bundle beserta root +skill yang dideklarasikan, root perintah Claude, default `settings.json` bundle Claude, +default LSP bundle Claude, dan paket hook yang didukung saat tata letaknya cocok dengan ekspektasi runtime OpenClaw. Setiap plugin OpenClaw native **harus** menyertakan file `openclaw.plugin.json` di -**root plugin**. OpenClaw menggunakan manifest ini untuk memvalidasi konfigurasi -**tanpa mengeksekusi kode plugin**. Manifest yang hilang atau tidak valid diperlakukan sebagai -error plugin dan memblokir validasi konfigurasi. +**root plugin**. OpenClaw menggunakan manifes ini untuk memvalidasi konfigurasi +**tanpa mengeksekusi kode plugin**. Manifes yang hilang atau tidak valid diperlakukan sebagai +kesalahan plugin dan memblokir validasi konfigurasi. -Lihat panduan sistem plugin lengkap: [Plugins](/id/tools/plugin). +Lihat panduan lengkap sistem plugin: [Plugin](/id/tools/plugin). Untuk model kapabilitas native dan panduan kompatibilitas eksternal saat ini: -[Capability model](/id/plugins/architecture#public-capability-model). +[Model kapabilitas](/id/plugins/architecture#public-capability-model). ## Fungsi file ini -`openclaw.plugin.json` adalah metadata yang dibaca OpenClaw sebelum memuat -kode plugin Anda. +`openclaw.plugin.json` adalah metadata yang dibaca OpenClaw sebelum memuat kode +plugin Anda. Gunakan untuk: - identitas plugin - validasi konfigurasi -- metadata auth dan onboarding yang harus tersedia tanpa mem-boot runtime plugin -- petunjuk aktivasi ringan yang dapat diperiksa permukaan control-plane sebelum runtime - dimuat -- deskriptor penyiapan ringan yang dapat diperiksa permukaan setup/onboarding sebelum +- metadata auth dan onboarding yang harus tersedia tanpa menjalankan runtime plugin +- petunjuk aktivasi ringan yang dapat diperiksa oleh permukaan control-plane sebelum runtime dimuat +- deskriptor penyiapan ringan yang dapat diperiksa oleh permukaan setup/onboarding sebelum runtime dimuat -- metadata alias dan auto-enable yang harus di-resolve sebelum runtime plugin dimuat -- metadata kepemilikan keluarga model shorthand yang harus mengaktifkan otomatis - plugin sebelum runtime dimuat -- snapshot kepemilikan kapabilitas statis yang digunakan untuk wiring kompatibilitas bawaan dan cakupan kontrak -- metadata QA runner ringan yang dapat diperiksa host bersama `openclaw qa` +- metadata alias dan auto-enable yang harus diselesaikan sebelum runtime plugin dimuat +- metadata kepemilikan shorthand model-family yang harus mengaktifkan plugin secara otomatis + sebelum runtime dimuat +- snapshot kepemilikan kapabilitas statis yang digunakan untuk wiring kompatibilitas bundle + dan cakupan kontrak +- metadata runner QA ringan yang dapat diperiksa oleh host bersama `openclaw qa` sebelum runtime plugin dimuat -- metadata konfigurasi khusus channel yang harus digabungkan ke katalog dan permukaan validasi tanpa memuat runtime +- metadata konfigurasi khusus channel yang harus digabungkan ke dalam permukaan katalog dan validasi + tanpa memuat runtime - petunjuk UI konfigurasi Jangan gunakan untuk: - mendaftarkan perilaku runtime - mendeklarasikan entrypoint kode -- metadata instal npm +- metadata instalasi npm -Hal-hal tersebut berada di kode plugin Anda dan `package.json`. +Hal-hal tersebut termasuk dalam kode plugin Anda dan `package.json`. ## Contoh minimal @@ -93,7 +94,7 @@ Hal-hal tersebut berada di kode plugin Anda dan `package.json`. { "id": "openrouter", "name": "OpenRouter", - "description": "Plugin provider OpenRouter", + "description": "OpenRouter provider plugin", "version": "1.0.0", "providers": ["openrouter"], "modelSupport": { @@ -121,13 +122,13 @@ Hal-hal tersebut berada di kode plugin Anda dan `package.json`. "provider": "openrouter", "method": "api-key", "choiceId": "openrouter-api-key", - "choiceLabel": "API key OpenRouter", + "choiceLabel": "OpenRouter API key", "groupId": "openrouter", "groupLabel": "OpenRouter", "optionKey": "openrouterApiKey", "cliFlag": "--openrouter-api-key", "cliOption": "--openrouter-api-key ", - "cliDescription": "API key OpenRouter", + "cliDescription": "OpenRouter API key", "onboardingScopes": ["text-inference"] } ], @@ -152,66 +153,68 @@ Hal-hal tersebut berada di kode plugin Anda dan `package.json`. ## Referensi field tingkat atas -| Field | Wajib | Tipe | Artinya | -| ----------------------------------- | -------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `id` | Ya | `string` | ID plugin kanonis. Ini adalah ID yang digunakan di `plugins.entries.`. | -| `configSchema` | Ya | `object` | JSON Schema inline untuk konfigurasi plugin ini. | -| `enabledByDefault` | Tidak | `true` | Menandai plugin bawaan sebagai aktif secara default. Hilangkan, atau tetapkan nilai apa pun selain `true`, agar plugin tetap nonaktif secara default. | -| `legacyPluginIds` | Tidak | `string[]` | ID legacy yang dinormalisasi ke ID plugin kanonis ini. | -| `autoEnableWhenConfiguredProviders` | Tidak | `string[]` | ID provider yang harus mengaktifkan otomatis plugin ini saat auth, konfigurasi, atau referensi model menyebutkannya. | -| `kind` | Tidak | `"memory"` \| `"context-engine"` | Mendeklarasikan jenis plugin eksklusif yang digunakan oleh `plugins.slots.*`. | -| `channels` | Tidak | `string[]` | ID channel yang dimiliki plugin ini. Digunakan untuk discovery dan validasi konfigurasi. | -| `providers` | Tidak | `string[]` | ID provider yang dimiliki plugin ini. | -| `modelSupport` | Tidak | `object` | Metadata shorthand keluarga model milik manifest yang digunakan untuk memuat otomatis plugin sebelum runtime. | -| `providerEndpoints` | Tidak | `object[]` | Metadata host/baseUrl endpoint milik manifest untuk rute provider yang harus diklasifikasikan inti sebelum runtime provider dimuat. | -| `cliBackends` | Tidak | `string[]` | ID backend inferensi CLI yang dimiliki plugin ini. Digunakan untuk auto-aktivasi saat startup dari referensi konfigurasi eksplisit. | -| `syntheticAuthRefs` | Tidak | `string[]` | Referensi provider atau backend CLI yang hook auth sintetis milik pluginnya harus diprobe selama discovery model cold sebelum runtime dimuat. | -| `nonSecretAuthMarkers` | Tidak | `string[]` | Nilai API key placeholder milik plugin bawaan yang merepresentasikan status kredensial lokal, OAuth, atau ambient yang bukan rahasia. | -| `commandAliases` | Tidak | `object[]` | Nama perintah yang dimiliki plugin ini yang harus menghasilkan konfigurasi sadar-plugin dan diagnostik CLI sebelum runtime dimuat. | -| `providerAuthEnvVars` | Tidak | `Record` | Metadata env auth provider ringan yang dapat diperiksa OpenClaw tanpa memuat kode plugin. | -| `providerAuthAliases` | Tidak | `Record` | ID provider yang harus menggunakan ulang ID provider lain untuk lookup auth, misalnya provider coding yang berbagi API key dan profil auth provider dasar. | -| `channelEnvVars` | Tidak | `Record` | Metadata env channel ringan yang dapat diperiksa OpenClaw tanpa memuat kode plugin. Gunakan ini untuk penyiapan channel berbasis env atau permukaan auth yang harus terlihat oleh helper startup/konfigurasi generik. | -| `providerAuthChoices` | Tidak | `object[]` | Metadata pilihan auth ringan untuk pemilih onboarding, resolusi provider pilihan, dan wiring flag CLI sederhana. | -| `activation` | Tidak | `object` | Petunjuk aktivasi ringan untuk pemuatan yang dipicu provider, perintah, channel, rute, dan kapabilitas. Hanya metadata; runtime plugin tetap memiliki perilaku sebenarnya. | -| `setup` | Tidak | `object` | Deskriptor penyiapan/onboarding ringan yang dapat diperiksa permukaan discovery dan setup tanpa memuat runtime plugin. | -| `qaRunners` | Tidak | `object[]` | Deskriptor QA runner ringan yang digunakan oleh host bersama `openclaw qa` sebelum runtime plugin dimuat. | -| `contracts` | Tidak | `object` | Snapshot kapabilitas bawaan statis untuk speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search, dan kepemilikan tool. | -| `channelConfigs` | Tidak | `Record` | Metadata konfigurasi channel milik manifest yang digabungkan ke permukaan discovery dan validasi sebelum runtime dimuat. | -| `skills` | Tidak | `string[]` | Direktori Skills yang dimuat, relatif terhadap root plugin. | -| `name` | Tidak | `string` | Nama plugin yang mudah dibaca manusia. | -| `description` | Tidak | `string` | Ringkasan singkat yang ditampilkan di permukaan plugin. | -| `version` | Tidak | `string` | Versi plugin informasional. | -| `uiHints` | Tidak | `Record` | Label UI, placeholder, dan petunjuk sensitivitas untuk field konfigurasi. | +| Field | Wajib | Tipe | Artinya | +| ------------------------------------ | -------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `id` | Ya | `string` | ID plugin kanonis. Ini adalah ID yang digunakan dalam `plugins.entries.`. | +| `configSchema` | Ya | `object` | JSON Schema inline untuk konfigurasi plugin ini. | +| `enabledByDefault` | Tidak | `true` | Menandai plugin bawaan sebagai aktif secara default. Hilangkan field ini, atau tetapkan nilai apa pun selain `true`, agar plugin tetap nonaktif secara default. | +| `legacyPluginIds` | Tidak | `string[]` | ID lama yang dinormalisasi ke ID plugin kanonis ini. | +| `autoEnableWhenConfiguredProviders` | Tidak | `string[]` | ID provider yang harus otomatis mengaktifkan plugin ini ketika auth, konfigurasi, atau referensi model menyebutkannya. | +| `kind` | Tidak | `"memory"` \| `"context-engine"` | Mendeklarasikan jenis plugin eksklusif yang digunakan oleh `plugins.slots.*`. | +| `channels` | Tidak | `string[]` | ID channel yang dimiliki oleh plugin ini. Digunakan untuk discovery dan validasi konfigurasi. | +| `providers` | Tidak | `string[]` | ID provider yang dimiliki oleh plugin ini. | +| `modelSupport` | Tidak | `object` | Metadata shorthand model-family milik manifes yang digunakan untuk memuat plugin secara otomatis sebelum runtime. | +| `providerEndpoints` | Tidak | `object[]` | Metadata host/baseUrl endpoint milik manifes untuk rute provider yang harus diklasifikasikan core sebelum runtime provider dimuat. | +| `cliBackends` | Tidak | `string[]` | ID backend inferensi CLI yang dimiliki oleh plugin ini. Digunakan untuk aktivasi otomatis saat startup dari referensi konfigurasi eksplisit. | +| `syntheticAuthRefs` | Tidak | `string[]` | Referensi provider atau backend CLI yang hook auth sintetis milik pluginnya harus diperiksa selama discovery model cold sebelum runtime dimuat. | +| `nonSecretAuthMarkers` | Tidak | `string[]` | Nilai placeholder API key milik plugin bawaan yang merepresentasikan status kredensial non-rahasia lokal, OAuth, atau ambient. | +| `commandAliases` | Tidak | `object[]` | Nama perintah yang dimiliki oleh plugin ini dan harus menghasilkan diagnostik konfigurasi serta CLI yang sadar-plugin sebelum runtime dimuat. | +| `providerAuthEnvVars` | Tidak | `Record` | Metadata env auth provider ringan yang dapat diperiksa OpenClaw tanpa memuat kode plugin. | +| `providerAuthAliases` | Tidak | `Record` | ID provider yang harus menggunakan ulang ID provider lain untuk pencarian auth, misalnya provider coding yang berbagi API key provider dasar dan profil auth yang sama. | +| `channelEnvVars` | Tidak | `Record` | Metadata env channel ringan yang dapat diperiksa OpenClaw tanpa memuat kode plugin. Gunakan ini untuk permukaan setup atau auth channel berbasis env yang perlu terlihat oleh helper startup/konfigurasi generik. | +| `providerAuthChoices` | Tidak | `object[]` | Metadata pilihan auth ringan untuk pemilih onboarding, resolusi provider pilihan, dan wiring flag CLI sederhana. | +| `activation` | Tidak | `object` | Petunjuk aktivasi ringan untuk pemuatan yang dipicu provider, perintah, channel, rute, dan kapabilitas. Hanya metadata; runtime plugin tetap memiliki perilaku sebenarnya. | +| `setup` | Tidak | `object` | Deskriptor setup/onboarding ringan yang dapat diperiksa oleh permukaan discovery dan setup tanpa memuat runtime plugin. | +| `qaRunners` | Tidak | `object[]` | Deskriptor runner QA ringan yang digunakan oleh host bersama `openclaw qa` sebelum runtime plugin dimuat. | +| `contracts` | Tidak | `object` | Snapshot kapabilitas bawaan statis untuk kepemilikan speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search, dan tool. | +| `mediaUnderstandingProviderMetadata` | Tidak | `Record` | Default media-understanding ringan untuk ID provider yang dideklarasikan dalam `contracts.mediaUnderstandingProviders`. | +| `channelConfigs` | Tidak | `Record` | Metadata konfigurasi channel milik manifes yang digabungkan ke dalam permukaan discovery dan validasi sebelum runtime dimuat. | +| `skills` | Tidak | `string[]` | Direktori Skills yang akan dimuat, relatif terhadap root plugin. | +| `name` | Tidak | `string` | Nama plugin yang mudah dibaca manusia. | +| `description` | Tidak | `string` | Ringkasan singkat yang ditampilkan di permukaan plugin. | +| `version` | Tidak | `string` | Versi plugin informatif. | +| `uiHints` | Tidak | `Record` | Label UI, placeholder, dan petunjuk sensitivitas untuk field konfigurasi. | -## Referensi providerAuthChoices +## Referensi `providerAuthChoices` Setiap entri `providerAuthChoices` menjelaskan satu pilihan onboarding atau auth. OpenClaw membaca ini sebelum runtime provider dimuat. -| Field | Wajib | Tipe | Artinya | -| --------------------- | -------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- | -| `provider` | Ya | `string` | ID provider tempat pilihan ini berada. | -| `method` | Ya | `string` | ID metode auth tujuan dispatch. | -| `choiceId` | Ya | `string` | ID auth-choice stabil yang digunakan oleh alur onboarding dan CLI. | -| `choiceLabel` | Tidak | `string` | Label yang ditampilkan ke pengguna. Jika dihilangkan, OpenClaw fallback ke `choiceId`. | -| `choiceHint` | Tidak | `string` | Teks bantuan singkat untuk pemilih. | -| `assistantPriority` | Tidak | `number` | Nilai yang lebih rendah diurutkan lebih awal dalam pemilih interaktif yang digerakkan assistant. | -| `assistantVisibility` | Tidak | `"visible"` \| `"manual-only"` | Sembunyikan pilihan dari pemilih assistant sambil tetap mengizinkan pemilihan CLI manual. | -| `deprecatedChoiceIds` | Tidak | `string[]` | ID pilihan legacy yang harus mengarahkan pengguna ke pilihan pengganti ini. | -| `groupId` | Tidak | `string` | ID grup opsional untuk mengelompokkan pilihan terkait. | -| `groupLabel` | Tidak | `string` | Label yang ditampilkan ke pengguna untuk grup tersebut. | -| `groupHint` | Tidak | `string` | Teks bantuan singkat untuk grup. | -| `optionKey` | Tidak | `string` | Key opsi internal untuk alur auth satu-flag sederhana. | -| `cliFlag` | Tidak | `string` | Nama flag CLI, seperti `--openrouter-api-key`. | -| `cliOption` | Tidak | `string` | Bentuk opsi CLI lengkap, seperti `--openrouter-api-key `. | -| `cliDescription` | Tidak | `string` | Deskripsi yang digunakan dalam bantuan CLI. | +| Field | Wajib | Tipe | Artinya | +| --------------------- | -------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| `provider` | Ya | `string` | ID provider yang memiliki pilihan ini. | +| `method` | Ya | `string` | ID metode auth yang akan digunakan untuk dispatch. | +| `choiceId` | Ya | `string` | ID pilihan auth stabil yang digunakan oleh alur onboarding dan CLI. | +| `choiceLabel` | Tidak | `string` | Label yang ditampilkan ke pengguna. Jika dihilangkan, OpenClaw akan menggunakan `choiceId`. | +| `choiceHint` | Tidak | `string` | Teks bantuan singkat untuk pemilih. | +| `assistantPriority` | Tidak | `number` | Nilai yang lebih rendah diurutkan lebih awal dalam pemilih interaktif yang digerakkan oleh asisten. | +| `assistantVisibility` | Tidak | `"visible"` \| `"manual-only"` | Sembunyikan pilihan dari pemilih asisten sambil tetap mengizinkan pemilihan manual melalui CLI. | +| `deprecatedChoiceIds` | Tidak | `string[]` | ID pilihan lama yang harus mengarahkan pengguna ke pilihan pengganti ini. | +| `groupId` | Tidak | `string` | ID grup opsional untuk mengelompokkan pilihan yang terkait. | +| `groupLabel` | Tidak | `string` | Label yang ditampilkan ke pengguna untuk grup tersebut. | +| `groupHint` | Tidak | `string` | Teks bantuan singkat untuk grup tersebut. | +| `optionKey` | Tidak | `string` | Kunci opsi internal untuk alur auth satu-flag sederhana. | +| `cliFlag` | Tidak | `string` | Nama flag CLI, seperti `--openrouter-api-key`. | +| `cliOption` | Tidak | `string` | Bentuk opsi CLI lengkap, seperti `--openrouter-api-key `. | +| `cliDescription` | Tidak | `string` | Deskripsi yang digunakan dalam bantuan CLI. | | `onboardingScopes` | Tidak | `Array<"text-inference" \| "image-generation">` | Permukaan onboarding tempat pilihan ini harus muncul. Jika dihilangkan, default-nya adalah `["text-inference"]`. | -## Referensi commandAliases +## Referensi `commandAliases` -Gunakan `commandAliases` saat plugin memiliki nama perintah runtime yang mungkin -secara keliru dimasukkan pengguna ke `plugins.allow` atau dicoba dijalankan sebagai perintah CLI root. OpenClaw -menggunakan metadata ini untuk diagnostik tanpa mengimpor kode runtime plugin. +Gunakan `commandAliases` saat sebuah plugin memiliki nama perintah runtime yang +mungkin keliru dimasukkan pengguna ke `plugins.allow` atau coba dijalankan sebagai +perintah CLI root. OpenClaw menggunakan metadata ini untuk diagnostik tanpa +mengimpor kode runtime plugin. ```json { @@ -225,22 +228,22 @@ menggunakan metadata ini untuk diagnostik tanpa mengimpor kode runtime plugin. } ``` -| Field | Wajib | Tipe | Artinya | -| ------------ | -------- | ----------------- | ----------------------------------------------------------------------- | -| `name` | Ya | `string` | Nama perintah yang dimiliki plugin ini. | -| `kind` | Tidak | `"runtime-slash"` | Menandai alias sebagai perintah slash chat, bukan perintah CLI root. | -| `cliCommand` | Tidak | `string` | Perintah CLI root terkait yang disarankan untuk operasi CLI, jika ada. | +| Field | Wajib | Tipe | Artinya | +| ------------ | -------- | ----------------- | ---------------------------------------------------------------------------- | +| `name` | Ya | `string` | Nama perintah yang dimiliki oleh plugin ini. | +| `kind` | Tidak | `"runtime-slash"` | Menandai alias sebagai perintah slash chat, bukan perintah CLI root. | +| `cliCommand` | Tidak | `string` | Perintah CLI root terkait yang dapat disarankan untuk operasi CLI, jika ada. | -## Referensi activation +## Referensi `activation` -Gunakan `activation` saat plugin dapat mendeklarasikan secara ringan peristiwa control-plane mana -yang nantinya harus mengaktifkannya. +Gunakan `activation` ketika plugin dapat mendeklarasikan secara ringan peristiwa control-plane mana +yang harus mengaktifkannya nanti. -## Referensi qaRunners +## Referensi `qaRunners` -Gunakan `qaRunners` saat plugin menyumbangkan satu atau lebih runner transport di bawah -root bersama `openclaw qa`. Pertahankan metadata ini tetap ringan dan statis; runtime plugin -tetap memiliki registrasi CLI sebenarnya melalui permukaan +Gunakan `qaRunners` ketika sebuah plugin menyumbangkan satu atau lebih runner transport di bawah +root bersama `openclaw qa`. Jaga metadata ini tetap ringan dan statis; runtime +plugin tetap memiliki registrasi CLI yang sebenarnya melalui permukaan `runtime-api.ts` ringan yang mengekspor `qaRunnerCliRegistrations`. ```json @@ -254,16 +257,16 @@ tetap memiliki registrasi CLI sebenarnya melalui permukaan } ``` -| Field | Wajib | Tipe | Artinya | -| ------------- | -------- | -------- | ------------------------------------------------------------------- | -| `commandName` | Ya | `string` | Subperintah yang dipasang di bawah `openclaw qa`, misalnya `matrix`. | +| Field | Wajib | Tipe | Artinya | +| ------------- | -------- | -------- | ---------------------------------------------------------------------- | +| `commandName` | Ya | `string` | Subperintah yang dipasang di bawah `openclaw qa`, misalnya `matrix`. | | `description` | Tidak | `string` | Teks bantuan fallback yang digunakan saat host bersama memerlukan perintah stub. | -Blok ini hanya metadata. Ini tidak mendaftarkan perilaku runtime, dan ini tidak +Blok ini hanya metadata. Ini tidak mendaftarkan perilaku runtime, dan tidak menggantikan `register(...)`, `setupEntry`, atau entrypoint runtime/plugin lainnya. -Konsumen live saat ini menggunakannya sebagai petunjuk penyempitan sebelum pemuatan plugin yang lebih luas, jadi -metadata activation yang hilang biasanya hanya berdampak pada performa; itu seharusnya tidak -mengubah kebenaran selama fallback kepemilikan manifest legacy masih ada. +Konsumen saat ini menggunakannya sebagai petunjuk penyempitan sebelum pemuatan plugin yang lebih luas, jadi +metadata aktivasi yang hilang biasanya hanya berdampak pada performa; seharusnya tidak +mengubah kebenaran selama fallback kepemilikan manifes lama masih ada. ```json { @@ -277,27 +280,27 @@ mengubah kebenaran selama fallback kepemilikan manifest legacy masih ada. } ``` -| Field | Wajib | Tipe | Artinya | -| ---------------- | -------- | ---------------------------------------------------- | ---------------------------------------------------------------- | -| `onProviders` | Tidak | `string[]` | ID provider yang harus mengaktifkan plugin ini saat diminta. | -| `onCommands` | Tidak | `string[]` | ID perintah yang harus mengaktifkan plugin ini. | -| `onChannels` | Tidak | `string[]` | ID channel yang harus mengaktifkan plugin ini. | -| `onRoutes` | Tidak | `string[]` | Jenis rute yang harus mengaktifkan plugin ini. | -| `onCapabilities` | Tidak | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Petunjuk kapabilitas luas yang digunakan oleh perencanaan aktivasi control-plane. | +| Field | Wajib | Tipe | Artinya | +| ---------------- | -------- | ---------------------------------------------------- | ------------------------------------------------------------------ | +| `onProviders` | Tidak | `string[]` | ID provider yang harus mengaktifkan plugin ini saat diminta. | +| `onCommands` | Tidak | `string[]` | ID perintah yang harus mengaktifkan plugin ini. | +| `onChannels` | Tidak | `string[]` | ID channel yang harus mengaktifkan plugin ini. | +| `onRoutes` | Tidak | `string[]` | Jenis rute yang harus mengaktifkan plugin ini. | +| `onCapabilities` | Tidak | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Petunjuk kapabilitas umum yang digunakan oleh perencanaan aktivasi control-plane. | Konsumen live saat ini: -- perencanaan CLI yang dipicu perintah fallback ke legacy - `commandAliases[].cliCommand` atau `commandAliases[].name` -- perencanaan setup/channel yang dipicu channel fallback ke kepemilikan legacy `channels[]` - saat metadata aktivasi channel eksplisit tidak ada -- perencanaan setup/runtime yang dipicu provider fallback ke kepemilikan legacy - `providers[]` dan `cliBackends[]` tingkat atas saat metadata aktivasi provider eksplisit +- perencanaan CLI yang dipicu perintah melakukan fallback ke + `commandAliases[].cliCommand` atau `commandAliases[].name` lama +- perencanaan setup/channel yang dipicu channel melakukan fallback ke kepemilikan + `channels[]` lama saat metadata aktivasi channel eksplisit tidak ada +- perencanaan setup/runtime yang dipicu provider melakukan fallback ke kepemilikan + `providers[]` dan `cliBackends[]` tingkat atas lama saat metadata aktivasi provider eksplisit tidak ada -## Referensi setup +## Referensi `setup` -Gunakan `setup` saat permukaan setup dan onboarding memerlukan metadata ringan milik plugin +Gunakan `setup` ketika permukaan setup dan onboarding memerlukan metadata milik plugin yang ringan sebelum runtime dimuat. ```json @@ -318,40 +321,39 @@ sebelum runtime dimuat. ``` `cliBackends` tingkat atas tetap valid dan terus mendeskripsikan backend inferensi CLI. -`setup.cliBackends` adalah permukaan deskriptor khusus setup untuk -alur control-plane/setup yang harus tetap hanya metadata. +`setup.cliBackends` adalah permukaan deskriptor khusus setup untuk alur +control-plane/setup yang harus tetap hanya metadata. -Jika ada, `setup.providers` dan `setup.cliBackends` adalah permukaan lookup -berbasis deskriptor yang disukai untuk discovery setup. Jika deskriptor hanya -menyempitkan kandidat plugin dan setup masih membutuhkan hook runtime saat setup yang lebih kaya, -tetapkan `requiresRuntime: true` dan biarkan `setup-api` tetap ada sebagai -path eksekusi fallback. +Saat ada, `setup.providers` dan `setup.cliBackends` adalah permukaan lookup +descriptor-first yang lebih disukai untuk discovery setup. Jika deskriptor hanya +mempersempit kandidat plugin dan setup masih memerlukan hook runtime waktu-setup yang lebih kaya, +tetapkan `requiresRuntime: true` dan biarkan `setup-api` tetap ada sebagai jalur eksekusi fallback. -Karena lookup setup dapat mengeksekusi kode `setup-api` milik plugin, nilai -`setup.providers[].id` dan `setup.cliBackends[]` yang dinormalisasi harus tetap unik di seluruh -plugin yang ditemukan. Kepemilikan ambigu gagal tertutup alih-alih memilih +Karena lookup setup dapat mengeksekusi kode `setup-api` milik plugin, nilai yang dinormalisasi +dari `setup.providers[].id` dan `setup.cliBackends[]` harus tetap unik di seluruh +plugin yang ditemukan. Kepemilikan yang ambigu akan gagal tertutup alih-alih memilih pemenang berdasarkan urutan discovery. -### Referensi setup.providers +### Referensi `setup.providers` -| Field | Wajib | Tipe | Artinya | -| ------------- | -------- | ---------- | --------------------------------------------------------------------------------------- | -| `id` | Ya | `string` | ID provider yang diekspos selama setup atau onboarding. Pertahankan ID ternormalisasi unik secara global. | -| `authMethods` | Tidak | `string[]` | ID metode setup/auth yang didukung provider ini tanpa memuat runtime penuh. | -| `envVars` | Tidak | `string[]` | Env vars yang dapat diperiksa permukaan setup/status generik sebelum runtime plugin dimuat. | +| Field | Wajib | Tipe | Artinya | +| ------------- | -------- | ---------- | ------------------------------------------------------------------------------------- | +| `id` | Ya | `string` | ID provider yang diekspos selama setup atau onboarding. Jaga ID yang dinormalisasi tetap unik secara global. | +| `authMethods` | Tidak | `string[]` | ID metode setup/auth yang didukung provider ini tanpa memuat runtime penuh. | +| `envVars` | Tidak | `string[]` | Variabel env yang dapat diperiksa oleh permukaan setup/status generik sebelum runtime plugin dimuat. | -### Field setup +### Field `setup` -| Field | Wajib | Tipe | Artinya | -| ------------------ | -------- | ---------- | ------------------------------------------------------------------------------------------------ | -| `providers` | Tidak | `object[]` | Deskriptor setup provider yang diekspos selama setup dan onboarding. | -| `cliBackends` | Tidak | `string[]` | ID backend saat setup yang digunakan untuk lookup setup berbasis deskriptor. Pertahankan ID ternormalisasi unik secara global. | -| `configMigrations` | Tidak | `string[]` | ID migrasi konfigurasi yang dimiliki oleh permukaan setup plugin ini. | -| `requiresRuntime` | Tidak | `boolean` | Apakah setup masih memerlukan eksekusi `setup-api` setelah lookup deskriptor. | +| Field | Wajib | Tipe | Artinya | +| ------------------ | -------- | ---------- | ---------------------------------------------------------------------------------------------------- | +| `providers` | Tidak | `object[]` | Deskriptor setup provider yang diekspos selama setup dan onboarding. | +| `cliBackends` | Tidak | `string[]` | ID backend waktu-setup yang digunakan untuk lookup setup descriptor-first. Jaga ID yang dinormalisasi tetap unik secara global. | +| `configMigrations` | Tidak | `string[]` | ID migrasi konfigurasi yang dimiliki oleh permukaan setup plugin ini. | +| `requiresRuntime` | Tidak | `boolean` | Apakah setup masih memerlukan eksekusi `setup-api` setelah lookup deskriptor. | -## Referensi uiHints +## Referensi `uiHints` -`uiHints` adalah map dari nama field konfigurasi ke petunjuk rendering kecil. +`uiHints` adalah peta dari nama field konfigurasi ke petunjuk rendering kecil. ```json { @@ -377,7 +379,7 @@ Setiap petunjuk field dapat mencakup: | `sensitive` | `boolean` | Menandai field sebagai rahasia atau sensitif. | | `placeholder` | `string` | Teks placeholder untuk input formulir. | -## Referensi contracts +## Referensi `contracts` Gunakan `contracts` hanya untuk metadata kepemilikan kapabilitas statis yang dapat dibaca OpenClaw tanpa mengimpor runtime plugin. @@ -385,6 +387,7 @@ dibaca OpenClaw tanpa mengimpor runtime plugin. ```json { "contracts": { + "embeddedExtensionFactories": ["pi"], "speechProviders": ["openai"], "realtimeTranscriptionProviders": ["openai"], "realtimeVoiceProviders": ["openai"], @@ -400,21 +403,59 @@ dibaca OpenClaw tanpa mengimpor runtime plugin. Setiap daftar bersifat opsional: -| Field | Tipe | Artinya | -| -------------------------------- | ---------- | ----------------------------------------------------------- | -| `speechProviders` | `string[]` | ID provider speech yang dimiliki plugin ini. | -| `realtimeTranscriptionProviders` | `string[]` | ID provider realtime-transcription yang dimiliki plugin ini. | -| `realtimeVoiceProviders` | `string[]` | ID provider realtime-voice yang dimiliki plugin ini. | -| `mediaUnderstandingProviders` | `string[]` | ID provider media-understanding yang dimiliki plugin ini. | -| `imageGenerationProviders` | `string[]` | ID provider image-generation yang dimiliki plugin ini. | -| `videoGenerationProviders` | `string[]` | ID provider video-generation yang dimiliki plugin ini. | -| `webFetchProviders` | `string[]` | ID provider web-fetch yang dimiliki plugin ini. | -| `webSearchProviders` | `string[]` | ID provider web search yang dimiliki plugin ini. | +| Field | Tipe | Artinya | +| -------------------------------- | ---------- | ----------------------------------------------------------------- | +| `embeddedExtensionFactories` | `string[]` | ID runtime tersemat tempat plugin bawaan dapat mendaftarkan factory. | +| `speechProviders` | `string[]` | ID provider speech yang dimiliki plugin ini. | +| `realtimeTranscriptionProviders` | `string[]` | ID provider realtime-transcription yang dimiliki plugin ini. | +| `realtimeVoiceProviders` | `string[]` | ID provider realtime-voice yang dimiliki plugin ini. | +| `mediaUnderstandingProviders` | `string[]` | ID provider media-understanding yang dimiliki plugin ini. | +| `imageGenerationProviders` | `string[]` | ID provider image-generation yang dimiliki plugin ini. | +| `videoGenerationProviders` | `string[]` | ID provider video-generation yang dimiliki plugin ini. | +| `webFetchProviders` | `string[]` | ID provider web-fetch yang dimiliki plugin ini. | +| `webSearchProviders` | `string[]` | ID provider web search yang dimiliki plugin ini. | | `tools` | `string[]` | Nama tool agent yang dimiliki plugin ini untuk pemeriksaan kontrak bawaan. | -## Referensi channelConfigs +## Referensi `mediaUnderstandingProviderMetadata` -Gunakan `channelConfigs` saat plugin channel memerlukan metadata konfigurasi ringan sebelum +Gunakan `mediaUnderstandingProviderMetadata` ketika provider media-understanding memiliki +model default, prioritas fallback auto-auth, atau dukungan dokumen native yang +diperlukan helper generik core sebelum runtime dimuat. Kunci juga harus dideklarasikan di +`contracts.mediaUnderstandingProviders`. + +```json +{ + "contracts": { + "mediaUnderstandingProviders": ["example"] + }, + "mediaUnderstandingProviderMetadata": { + "example": { + "capabilities": ["image", "audio"], + "defaultModels": { + "image": "example-vision-latest", + "audio": "example-transcribe-latest" + }, + "autoPriority": { + "image": 40 + }, + "nativeDocumentInputs": ["pdf"] + } + } +} +``` + +Setiap entri provider dapat mencakup: + +| Field | Tipe | Artinya | +| ---------------------- | ----------------------------------- | ---------------------------------------------------------------------------- | +| `capabilities` | `("image" \| "audio" \| "video")[]` | Kapabilitas media yang diekspos oleh provider ini. | +| `defaultModels` | `Record` | Default kapabilitas-ke-model yang digunakan saat konfigurasi tidak menentukan model. | +| `autoPriority` | `Record` | Angka yang lebih rendah diurutkan lebih awal untuk fallback provider otomatis berbasis kredensial. | +| `nativeDocumentInputs` | `"pdf"[]` | Input dokumen native yang didukung oleh provider. | + +## Referensi `channelConfigs` + +Gunakan `channelConfigs` ketika plugin channel memerlukan metadata konfigurasi ringan sebelum runtime dimuat. ```json @@ -444,18 +485,18 @@ runtime dimuat. Setiap entri channel dapat mencakup: -| Field | Tipe | Artinya | -| ------------- | ------------------------ | ----------------------------------------------------------------------------------------- | +| Field | Tipe | Artinya | +| ------------- | ------------------------ | ---------------------------------------------------------------------------------------- | | `schema` | `object` | JSON Schema untuk `channels.`. Wajib untuk setiap entri konfigurasi channel yang dideklarasikan. | | `uiHints` | `Record` | Label UI/placeholder/petunjuk sensitif opsional untuk bagian konfigurasi channel tersebut. | -| `label` | `string` | Label channel yang digabungkan ke pemilih dan permukaan inspect saat metadata runtime belum siap. | -| `description` | `string` | Deskripsi channel singkat untuk permukaan inspect dan katalog. | -| `preferOver` | `string[]` | ID plugin legacy atau prioritas lebih rendah yang harus dikalahkan channel ini di permukaan pemilihan. | +| `label` | `string` | Label channel yang digabungkan ke dalam permukaan pemilih dan inspect saat metadata runtime belum siap. | +| `description` | `string` | Deskripsi channel singkat untuk permukaan inspect dan katalog. | +| `preferOver` | `string[]` | ID plugin lama atau prioritas lebih rendah yang harus dikalahkan channel ini di permukaan pemilihan. | -## Referensi modelSupport +## Referensi `modelSupport` -Gunakan `modelSupport` saat OpenClaw harus menyimpulkan plugin provider Anda dari -id model shorthand seperti `gpt-5.4` atau `claude-sonnet-4.6` sebelum runtime plugin +Gunakan `modelSupport` ketika OpenClaw harus menyimpulkan plugin provider Anda dari +ID model shorthand seperti `gpt-5.4` atau `claude-sonnet-4.6` sebelum runtime plugin dimuat. ```json @@ -467,9 +508,9 @@ dimuat. } ``` -OpenClaw menerapkan prioritas ini: +OpenClaw menerapkan prioritas berikut: -- referensi `provider/model` eksplisit menggunakan metadata manifest `providers` pemilik +- referensi eksplisit `provider/model` menggunakan metadata manifes `providers` yang memilikinya - `modelPatterns` mengalahkan `modelPrefixes` - jika satu plugin non-bawaan dan satu plugin bawaan sama-sama cocok, plugin non-bawaan menang @@ -477,37 +518,37 @@ OpenClaw menerapkan prioritas ini: Field: -| Field | Tipe | Artinya | -| --------------- | ---------- | -------------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | Prefiks yang dicocokkan dengan `startsWith` terhadap id model shorthand. | -| `modelPatterns` | `string[]` | Sumber regex yang dicocokkan terhadap id model shorthand setelah penghapusan sufiks profil. | +| Field | Tipe | Artinya | +| --------------- | ---------- | ------------------------------------------------------------------------------ | +| `modelPrefixes` | `string[]` | Prefiks yang dicocokkan dengan `startsWith` terhadap ID model shorthand. | +| `modelPatterns` | `string[]` | Sumber regex yang dicocokkan terhadap ID model shorthand setelah penghapusan sufiks profil. | -Key kapabilitas tingkat atas legacy sudah deprecated. Gunakan `openclaw doctor --fix` untuk +Kunci kapabilitas lama tingkat atas sudah deprecated. Gunakan `openclaw doctor --fix` untuk memindahkan `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, dan `webSearchProviders` ke bawah `contracts`; pemuatan -manifest normal tidak lagi memperlakukan field tingkat atas tersebut sebagai +manifes normal tidak lagi memperlakukan field tingkat atas tersebut sebagai kepemilikan kapabilitas. -## Manifest versus package.json +## Manifes versus package.json Kedua file memiliki fungsi yang berbeda: -| File | Gunakan untuk | -| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Discovery, validasi konfigurasi, metadata auth-choice, dan petunjuk UI yang harus ada sebelum kode plugin berjalan | -| `package.json` | Metadata npm, instalasi dependensi, dan blok `openclaw` yang digunakan untuk entrypoint, pembatas instalasi, setup, atau metadata katalog | +| File | Gunakan untuk | +| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.plugin.json` | Discovery, validasi konfigurasi, metadata pilihan auth, dan petunjuk UI yang harus ada sebelum kode plugin berjalan | +| `package.json` | Metadata npm, instalasi dependensi, dan blok `openclaw` yang digunakan untuk entrypoint, gating instalasi, setup, atau metadata katalog | Jika Anda tidak yakin metadata harus ditempatkan di mana, gunakan aturan ini: - jika OpenClaw harus mengetahuinya sebelum memuat kode plugin, letakkan di `openclaw.plugin.json` -- jika itu terkait packaging, file entry, atau perilaku instal npm, letakkan di `package.json` +- jika itu terkait packaging, file entry, atau perilaku instalasi npm, letakkan di `package.json` -### Field package.json yang memengaruhi discovery +### Field `package.json` yang memengaruhi discovery -Beberapa metadata plugin pra-runtime sengaja ditempatkan di `package.json` di bawah blok -`openclaw`, bukan `openclaw.plugin.json`. +Beberapa metadata plugin pra-runtime memang sengaja ditempatkan di `package.json` di bawah blok +`openclaw`, bukan di `openclaw.plugin.json`. Contoh penting: @@ -515,35 +556,36 @@ Contoh penting: | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `openclaw.extensions` | Mendeklarasikan entrypoint plugin native. Harus tetap berada di dalam direktori paket plugin. | | `openclaw.runtimeExtensions` | Mendeklarasikan entrypoint runtime JavaScript hasil build untuk paket yang diinstal. Harus tetap berada di dalam direktori paket plugin. | -| `openclaw.setupEntry` | Entrypoint ringan khusus setup yang digunakan selama onboarding, startup channel tertunda, dan discovery status channel/SecretRef yang hanya-baca. Harus tetap berada di dalam direktori paket plugin. | +| `openclaw.setupEntry` | Entrypoint ringan khusus setup yang digunakan selama onboarding, startup channel yang ditunda, dan discovery status channel/SecretRef hanya-baca. Harus tetap berada di dalam direktori paket plugin. | | `openclaw.runtimeSetupEntry` | Mendeklarasikan entrypoint setup JavaScript hasil build untuk paket yang diinstal. Harus tetap berada di dalam direktori paket plugin. | -| `openclaw.channel` | Metadata katalog channel ringan seperti label, path docs, alias, dan copy pemilihan. | -| `openclaw.channel.configuredState` | Metadata pemeriksa configured-state ringan yang dapat menjawab "apakah penyiapan hanya-env sudah ada?" tanpa memuat runtime channel penuh. | -| `openclaw.channel.persistedAuthState` | Metadata pemeriksa auth persisted ringan yang dapat menjawab "apakah sudah ada yang login?" tanpa memuat runtime channel penuh. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Petunjuk instal/update untuk plugin bawaan dan plugin yang dipublikasikan secara eksternal. | -| `openclaw.install.defaultChoice` | Path instalasi yang disukai saat beberapa sumber instal tersedia. | -| `openclaw.install.minHostVersion` | Versi host OpenClaw minimum yang didukung, menggunakan batas bawah semver seperti `>=2026.3.22`. | -| `openclaw.install.allowInvalidConfigRecovery` | Mengizinkan path pemulihan reinstalasi plugin bawaan yang sempit saat konfigurasi tidak valid. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Memungkinkan permukaan channel khusus setup dimuat sebelum plugin channel penuh saat startup. | +| `openclaw.channel` | Metadata katalog channel ringan seperti label, path dokumentasi, alias, dan teks pemilihan. | +| `openclaw.channel.configuredState` | Metadata pemeriksa configured-state ringan yang dapat menjawab "apakah setup hanya-env sudah ada?" tanpa memuat runtime channel penuh. | +| `openclaw.channel.persistedAuthState` | Metadata pemeriksa persisted-auth ringan yang dapat menjawab "apakah ada yang sudah login?" tanpa memuat runtime channel penuh. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Petunjuk instalasi/pembaruan untuk plugin bawaan dan plugin yang dipublikasikan secara eksternal. | +| `openclaw.install.defaultChoice` | Jalur instalasi pilihan saat beberapa sumber instalasi tersedia. | +| `openclaw.install.minHostVersion` | Versi host OpenClaw minimum yang didukung, menggunakan batas bawah semver seperti `>=2026.3.22`. | +| `openclaw.install.allowInvalidConfigRecovery` | Mengizinkan jalur pemulihan reinstall plugin bawaan yang sempit saat konfigurasi tidak valid. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Memungkinkan permukaan channel khusus setup dimuat sebelum plugin channel penuh saat startup. | -`openclaw.install.minHostVersion` diberlakukan selama instalasi dan pemuatan -registri manifest. Nilai yang tidak valid ditolak; nilai yang lebih baru tetapi valid -melewati plugin pada host yang lebih lama. +`openclaw.install.minHostVersion` diberlakukan selama instalasi dan pemuatan registry +manifes. Nilai yang tidak valid ditolak; nilai yang valid tetapi lebih baru akan melewati +plugin pada host yang lebih lama. -Plugin channel harus menyediakan `openclaw.setupEntry` saat status, daftar channel, -atau pemindaian SecretRef perlu mengidentifikasi akun yang dikonfigurasi tanpa memuat -runtime penuh. Entri setup harus mengekspos metadata channel ditambah adapter -konfigurasi, status, dan secret yang aman untuk setup; pertahankan klien jaringan, listener gateway, dan +Plugin channel harus menyediakan `openclaw.setupEntry` ketika status, daftar channel, +atau pemindaian SecretRef perlu mengidentifikasi akun yang sudah dikonfigurasi tanpa memuat +runtime penuh. Entri setup harus mengekspos metadata channel beserta adapter konfigurasi, +status, dan secret yang aman untuk setup; simpan klien jaringan, listener Gateway, dan runtime transport di entrypoint extension utama. -Field entrypoint runtime tidak menggantikan pemeriksaan batas paket untuk source -entrypoint fields. Misalnya, `openclaw.runtimeExtensions` tidak dapat membuat -path `openclaw.extensions` yang keluar batas menjadi dapat dimuat. +Field entrypoint runtime tidak menggantikan pemeriksaan batas paket untuk field +entrypoint sumber. Misalnya, `openclaw.runtimeExtensions` tidak dapat membuat +path `openclaw.extensions` yang keluar dari batas menjadi dapat dimuat. -`openclaw.install.allowInvalidConfigRecovery` sengaja sempit. Ini tidak -membuat konfigurasi rusak sembarang menjadi bisa diinstal. Saat ini ini hanya mengizinkan alur instalasi untuk pulih dari kegagalan upgrade plugin bawaan basi tertentu, seperti -path plugin bawaan yang hilang atau entri `channels.` basi untuk plugin -bawaan yang sama. Error konfigurasi yang tidak terkait tetap memblokir instalasi dan mengarahkan operator +`openclaw.install.allowInvalidConfigRecovery` sengaja dibuat sempit. Ini tidak +membuat konfigurasi rusak sembarang menjadi dapat diinstal. Saat ini, ini hanya memungkinkan +alur instalasi memulihkan kegagalan upgrade plugin bawaan usang tertentu, seperti +path plugin bawaan yang hilang atau entri `channels.` usang untuk plugin bawaan +yang sama. Kesalahan konfigurasi yang tidak terkait tetap memblokir instalasi dan mengarahkan operator ke `openclaw doctor --fix`. `openclaw.channel.persistedAuthState` adalah metadata paket untuk modul pemeriksa @@ -563,12 +605,13 @@ kecil: } ``` -Gunakan saat alur setup, doctor, atau configured-state memerlukan probe auth ya/tidak yang ringan -sebelum plugin channel penuh dimuat. Ekspor target harus berupa fungsi kecil -yang hanya membaca status persisted; jangan arahkan melalui barrel runtime channel penuh. +Gunakan ini saat alur setup, doctor, atau configured-state memerlukan probe auth +ya/tidak yang ringan sebelum plugin channel penuh dimuat. Ekspor target harus berupa +fungsi kecil yang hanya membaca status yang dipersistenkan; jangan arahkan melalui barrel +runtime channel penuh. `openclaw.channel.configuredState` mengikuti bentuk yang sama untuk pemeriksaan configured -hanya-env yang ringan: +khusus env yang ringan: ```json { @@ -584,95 +627,96 @@ hanya-env yang ringan: } ``` -Gunakan saat sebuah channel dapat menjawab configured-state dari env atau input kecil lain -yang non-runtime. Jika pemeriksaan memerlukan resolusi konfigurasi penuh atau runtime -channel yang sebenarnya, pertahankan logika tersebut di hook plugin `config.hasConfiguredState`. +Gunakan ini ketika sebuah channel dapat menjawab configured-state dari env atau input kecil +non-runtime lainnya. Jika pemeriksaan memerlukan resolusi konfigurasi penuh atau runtime +channel yang sebenarnya, simpan logika tersebut dalam hook plugin `config.hasConfiguredState` +sebagai gantinya. ## Prioritas discovery (ID plugin duplikat) -OpenClaw menemukan plugin dari beberapa root (bawaan, instalasi global, workspace, path yang dipilih secara eksplisit dalam konfigurasi). Jika dua hasil discovery berbagi `id` yang sama, hanya manifest dengan **prioritas tertinggi** yang dipertahankan; duplikat dengan prioritas lebih rendah dibuang alih-alih dimuat berdampingan. +OpenClaw menemukan plugin dari beberapa root (bawaan, instalasi global, workspace, path eksplisit yang dipilih oleh konfigurasi). Jika dua hasil discovery memiliki `id` yang sama, hanya manifes dengan **prioritas tertinggi** yang dipertahankan; duplikat dengan prioritas lebih rendah dibuang alih-alih dimuat berdampingan. Prioritas, dari tertinggi ke terendah: -1. **Dipilih dalam konfigurasi** — path yang dipin secara eksplisit di `plugins.entries.` +1. **Dipilih konfigurasi** — path yang dipin secara eksplisit di `plugins.entries.` 2. **Bawaan** — plugin yang dikirim bersama OpenClaw 3. **Instalasi global** — plugin yang diinstal ke root plugin OpenClaw global 4. **Workspace** — plugin yang ditemukan relatif terhadap workspace saat ini Implikasi: -- Salinan fork atau basi dari plugin bawaan yang berada di workspace tidak akan membayangi build bawaan. -- Untuk benar-benar menimpa plugin bawaan dengan plugin lokal, pin melalui `plugins.entries.` agar menang berdasarkan prioritas alih-alih mengandalkan discovery workspace. -- Duplikat yang dibuang dicatat ke log agar Doctor dan diagnostik startup dapat menunjuk ke salinan yang dibuang. +- Salinan bercabang atau usang dari plugin bawaan yang berada di workspace tidak akan membayangi build bawaan. +- Untuk benar-benar mengganti plugin bawaan dengan plugin lokal, pin plugin itu melalui `plugins.entries.` agar menang berdasarkan prioritas, bukan mengandalkan discovery workspace. +- Pembuangan duplikat dicatat dalam log agar Doctor dan diagnostik startup dapat menunjuk ke salinan yang dibuang. ## Persyaratan JSON Schema - **Setiap plugin harus menyertakan JSON Schema**, bahkan jika tidak menerima konfigurasi. - Skema kosong dapat diterima (misalnya, `{ "type": "object", "additionalProperties": false }`). -- Skema divalidasi pada waktu baca/tulis konfigurasi, bukan saat runtime. +- Skema divalidasi saat baca/tulis konfigurasi, bukan saat runtime. ## Perilaku validasi -- Key `channels.*` yang tidak dikenal adalah **error**, kecuali id channel tersebut dideklarasikan oleh - manifest plugin. +- Kunci `channels.*` yang tidak dikenal adalah **kesalahan**, kecuali ID channel tersebut dideklarasikan oleh + manifes plugin. - `plugins.entries.`, `plugins.allow`, `plugins.deny`, dan `plugins.slots.*` - harus mereferensikan ID plugin yang **dapat ditemukan**. ID yang tidak dikenal adalah **error**. -- Jika plugin diinstal tetapi memiliki manifest atau skema yang rusak atau hilang, - validasi gagal dan Doctor melaporkan error plugin tersebut. -- Jika konfigurasi plugin ada tetapi plugin **dinonaktifkan**, konfigurasi tetap dipertahankan dan + harus mereferensikan ID plugin yang **dapat ditemukan**. ID yang tidak dikenal adalah **kesalahan**. +- Jika plugin terinstal tetapi memiliki manifes atau skema yang rusak atau hilang, + validasi gagal dan Doctor melaporkan kesalahan plugin. +- Jika konfigurasi plugin ada tetapi pluginnya **dinonaktifkan**, konfigurasi tetap disimpan dan **peringatan** ditampilkan di Doctor + log. -Lihat [Configuration reference](/id/gateway/configuration) untuk skema `plugins.*` lengkap. +Lihat [Referensi konfigurasi](/id/gateway/configuration) untuk skema lengkap `plugins.*`. ## Catatan -- Manifest **wajib untuk plugin OpenClaw native**, termasuk pemuatan dari filesystem lokal. -- Runtime tetap memuat modul plugin secara terpisah; manifest hanya untuk +- Manifes **wajib untuk plugin OpenClaw native**, termasuk pemuatan dari filesystem lokal. +- Runtime tetap memuat modul plugin secara terpisah; manifes hanya untuk discovery + validasi. -- Manifest native di-parse dengan JSON5, sehingga komentar, trailing comma, dan - key tanpa tanda kutip diterima selama nilai akhirnya tetap berupa object. -- Hanya field manifest yang didokumentasikan yang dibaca oleh manifest loader. Hindari menambahkan - key tingkat atas kustom di sini. -- `providerAuthEnvVars` adalah path metadata ringan untuk probe auth, validasi env-marker, - dan permukaan auth provider serupa yang tidak boleh mem-boot runtime plugin - hanya untuk memeriksa nama env. -- `providerAuthAliases` memungkinkan varian provider menggunakan ulang env vars auth, - profil auth, auth berbasis konfigurasi, dan pilihan onboarding API key milik provider lain - tanpa meng-hardcode hubungan tersebut di inti. -- `providerEndpoints` memungkinkan plugin provider memiliki metadata pencocokan host/baseUrl endpoint - sederhana. Gunakan hanya untuk kelas endpoint yang sudah didukung inti; +- Manifes native diurai dengan JSON5, jadi komentar, trailing comma, dan + kunci tanpa tanda kutip diterima selama nilai akhirnya tetap berupa object. +- Hanya field manifes yang terdokumentasi yang dibaca oleh pemuat manifes. Hindari menambahkan + kunci tingkat atas kustom di sini. +- `providerAuthEnvVars` adalah jalur metadata ringan untuk probe auth, validasi + penanda env, dan permukaan auth provider serupa yang tidak boleh menyalakan runtime + plugin hanya untuk memeriksa nama env. +- `providerAuthAliases` memungkinkan varian provider menggunakan ulang variabel env auth, + profil auth, auth berbasis konfigurasi, dan pilihan onboarding API key provider lain + tanpa meng-hardcode hubungan tersebut di core. +- `providerEndpoints` memungkinkan plugin provider memiliki metadata pencocokan + host/baseUrl endpoint sederhana. Gunakan hanya untuk kelas endpoint yang sudah didukung core; plugin tetap memiliki perilaku runtime. -- `syntheticAuthRefs` adalah path metadata ringan untuk hook auth sintetis - milik provider yang harus terlihat oleh discovery model cold sebelum registri - runtime ada. Hanya cantumkan referensi yang provider runtime atau backend CLI-nya benar-benar +- `syntheticAuthRefs` adalah jalur metadata ringan untuk hook auth sintetis milik provider + yang harus terlihat oleh discovery model cold sebelum registry runtime ada. + Daftarkan hanya referensi yang provider runtime atau backend CLI-nya benar-benar mengimplementasikan `resolveSyntheticAuth`. -- `nonSecretAuthMarkers` adalah path metadata ringan untuk placeholder API key - milik plugin bawaan seperti penanda kredensial lokal, OAuth, atau ambient. - Inti memperlakukan ini sebagai non-rahasia untuk tampilan auth dan audit secret tanpa +- `nonSecretAuthMarkers` adalah jalur metadata ringan untuk placeholder API key milik plugin bawaan + seperti penanda kredensial lokal, OAuth, atau ambient. + Core memperlakukan ini sebagai non-rahasia untuk tampilan auth dan audit secret tanpa meng-hardcode provider pemiliknya. -- `channelEnvVars` adalah path metadata ringan untuk fallback shell-env, prompt - setup, dan permukaan channel serupa yang tidak boleh mem-boot runtime plugin +- `channelEnvVars` adalah jalur metadata ringan untuk fallback shell-env, prompt setup, + dan permukaan channel serupa yang tidak boleh menyalakan runtime plugin hanya untuk memeriksa nama env. Nama env adalah metadata, bukan aktivasi - dengan sendirinya: status, audit, validasi pengiriman Cron, dan permukaan hanya-baca lainnya - tetap menerapkan kebijakan kepercayaan plugin dan aktivasi efektif sebelum - memperlakukan env var sebagai channel yang dikonfigurasi. -- `providerAuthChoices` adalah path metadata ringan untuk pemilih auth-choice, - resolusi `--auth-choice`, pemetaan provider pilihan, dan registrasi flag CLI - onboarding sederhana sebelum runtime provider dimuat. Untuk metadata wizard - runtime yang memerlukan kode provider, lihat - [Provider runtime hooks](/id/plugins/architecture#provider-runtime-hooks). + dengan sendirinya: status, audit, validasi pengiriman Cron, dan permukaan hanya-baca + lainnya tetap menerapkan trust plugin dan kebijakan aktivasi efektif sebelum + mereka memperlakukan variabel env sebagai channel yang dikonfigurasi. +- `providerAuthChoices` adalah jalur metadata ringan untuk pemilih pilihan auth, + resolusi `--auth-choice`, pemetaan provider pilihan, dan registrasi flag CLI onboarding + sederhana sebelum runtime provider dimuat. Untuk metadata wizard runtime + yang memerlukan kode provider, lihat + [Hook runtime provider](/id/plugins/architecture#provider-runtime-hooks). - Jenis plugin eksklusif dipilih melalui `plugins.slots.*`. - `kind: "memory"` dipilih oleh `plugins.slots.memory`. - `kind: "context-engine"` dipilih oleh `plugins.slots.contextEngine` (default: `legacy` bawaan). - `channels`, `providers`, `cliBackends`, dan `skills` dapat dihilangkan saat - plugin tidak memerlukannya. -- Jika plugin Anda bergantung pada modul native, dokumentasikan langkah build dan - persyaratan allowlist package-manager (misalnya, pnpm `allow-build-scripts` + plugin tidak membutuhkannya. +- Jika plugin Anda bergantung pada modul native, dokumentasikan langkah build dan persyaratan allowlist + package manager apa pun (misalnya, pnpm `allow-build-scripts` - `pnpm rebuild `). ## Terkait -- [Building Plugins](/id/plugins/building-plugins) — memulai dengan plugin -- [Plugin Architecture](/id/plugins/architecture) — arsitektur internal -- [SDK Overview](/id/plugins/sdk-overview) — referensi SDK Plugin +- [Membangun Plugin](/id/plugins/building-plugins) — memulai dengan plugin +- [Arsitektur Plugin](/id/plugins/architecture) — arsitektur internal +- [Ikhtisar SDK](/id/plugins/sdk-overview) — referensi SDK Plugin diff --git a/docs/id/plugins/sdk-agent-harness.md b/docs/id/plugins/sdk-agent-harness.md index b26392e96..9fdf40e61 100644 --- a/docs/id/plugins/sdk-agent-harness.md +++ b/docs/id/plugins/sdk-agent-harness.md @@ -1,60 +1,59 @@ --- read_when: - Anda sedang mengubah runtime agen tertanam atau registry harness - - Anda sedang mendaftarkan harness agen dari plugin bawaan atau tepercaya + - Anda sedang mendaftarkan agent harness dari plugin bawaan atau tepercaya - Anda perlu memahami bagaimana plugin Codex berhubungan dengan penyedia model sidebarTitle: Agent Harness -summary: Permukaan SDK eksperimental untuk plugin yang menggantikan eksekutor agen tertanam tingkat rendah +summary: Surface SDK eksperimental untuk plugin yang menggantikan eksekutor agen tertanam level rendah title: Plugin Agent Harness x-i18n: - generated_at: "2026-04-12T00:18:57Z" + generated_at: "2026-04-22T09:14:59Z" model: gpt-5.4 provider: openai - source_hash: 62b88fd24ce8b600179db27e16e8d764a2cd7a14e5c5df76374c33121aa5e365 + source_hash: 728fef59ae3cce29a3348842820f1f71a2eac98ae6b276179bce6c85d16613df source_path: plugins/sdk-agent-harness.md workflow: 15 --- # Plugin Agent Harness -**Agent harness** adalah eksekutor tingkat rendah untuk satu giliran agen OpenClaw -yang sudah disiapkan. Ini bukan penyedia model, bukan channel, dan bukan registry tool. +**Agent harness** adalah eksekutor level rendah untuk satu giliran agen OpenClaw +yang sudah disiapkan. Ini bukan penyedia model, bukan saluran, dan bukan registry tool. -Gunakan permukaan ini hanya untuk plugin native bawaan atau tepercaya. Kontrak ini +Gunakan surface ini hanya untuk plugin native bawaan atau tepercaya. Kontrak ini masih eksperimental karena tipe parameternya sengaja mencerminkan runner tertanam saat ini. ## Kapan menggunakan harness -Daftarkan agent harness saat sebuah keluarga model memiliki runtime sesi native -sendiri dan transport penyedia OpenClaw normal adalah abstraksi yang salah. +Daftarkan agent harness ketika suatu keluarga model memiliki runtime sesi native +sendiri dan transport penyedia OpenClaw normal bukan abstraksi yang tepat. Contoh: -- server agen pengodean native yang memiliki thread dan compaction -- CLI atau daemon lokal yang harus melakukan streaming event plan/reasoning/tool native +- server coding-agent native yang memiliki thread dan Compaction +- CLI atau daemon lokal yang harus melakukan streaming event rencana/penalaran/tool native - runtime model yang memerlukan resume id sendiri selain transkrip sesi OpenClaw -Jangan mendaftarkan harness hanya untuk menambahkan API LLM baru. Untuk API model HTTP atau -WebSocket normal, bangun [plugin provider](/id/plugins/sdk-provider-plugins). +Jangan mendaftarkan harness hanya untuk menambahkan API LLM baru. Untuk API model +HTTP atau WebSocket biasa, bangun [plugin provider](/id/plugins/sdk-provider-plugins). -## Yang masih dimiliki core +## Yang tetap dimiliki core -Sebelum sebuah harness dipilih, OpenClaw sudah menyelesaikan: +Sebelum harness dipilih, OpenClaw sudah menyelesaikan: - penyedia dan model -- status auth runtime -- tingkat berpikir dan anggaran konteks +- status autentikasi runtime +- tingkat thinking dan anggaran konteks - file transkrip/sesi OpenClaw - workspace, sandbox, dan kebijakan tool -- callback balasan channel dan callback streaming +- callback balasan saluran dan callback streaming - kebijakan fallback model dan peralihan model live -Pemisahan itu disengaja. Sebuah harness menjalankan upaya yang sudah disiapkan; -ia tidak memilih penyedia, menggantikan pengiriman channel, atau diam-diam -mengganti model. +Pemisahan itu disengaja. Harness menjalankan attempt yang sudah disiapkan; harness +tidak memilih penyedia, mengganti pengiriman saluran, atau diam-diam mengganti model. -## Daftarkan harness +## Mendaftarkan harness **Import:** `openclaw/plugin-sdk/agent-harness` @@ -92,53 +91,53 @@ export default definePluginEntry({ ## Kebijakan pemilihan -OpenClaw memilih harness setelah resolusi provider/model: +OpenClaw memilih harness setelah resolusi penyedia/model: 1. `OPENCLAW_AGENT_RUNTIME=` memaksa harness terdaftar dengan id tersebut. 2. `OPENCLAW_AGENT_RUNTIME=pi` memaksa harness PI bawaan. -3. `OPENCLAW_AGENT_RUNTIME=auto` meminta harness terdaftar apakah mereka mendukung provider/model - yang telah diselesaikan. +3. `OPENCLAW_AGENT_RUNTIME=auto` meminta harness terdaftar apakah mereka mendukung + penyedia/model yang telah di-resolve. 4. Jika tidak ada harness terdaftar yang cocok, OpenClaw menggunakan PI kecuali fallback PI dinonaktifkan. -Kegagalan harness plugin yang dipaksakan akan muncul sebagai kegagalan run. Dalam mode `auto`, -OpenClaw dapat fallback ke PI ketika harness plugin terpilih gagal sebelum sebuah -giliran menghasilkan efek samping. Tetapkan `OPENCLAW_AGENT_HARNESS_FALLBACK=none` atau -`embeddedHarness.fallback: "none"` agar fallback itu menjadi kegagalan keras. +Kegagalan harness plugin ditampilkan sebagai kegagalan run. Dalam mode `auto`, +fallback PI hanya digunakan ketika tidak ada harness plugin terdaftar yang mendukung +penyedia/model yang telah di-resolve. Setelah harness plugin telah mengklaim sebuah run, +OpenClaw tidak memutar ulang giliran yang sama melalui PI karena hal itu dapat mengubah +semantik autentikasi/runtime atau menduplikasi efek samping. -Plugin Codex bawaan mendaftarkan `codex` sebagai harness id-nya. Core memperlakukan itu +Plugin Codex bawaan mendaftarkan `codex` sebagai id harness-nya. Core memperlakukan itu sebagai id harness plugin biasa; alias khusus Codex harus berada di plugin atau konfigurasi operator, bukan di selector runtime bersama. -## Pairing provider plus harness +## Pemasangan provider plus harness -Sebagian besar harness juga sebaiknya mendaftarkan provider. Provider membuat ref model, -status auth, metadata model, dan pemilihan `/model` terlihat oleh seluruh -OpenClaw. Harness kemudian mengklaim provider itu di `supports(...)`. +Sebagian besar harness juga sebaiknya mendaftarkan provider. Provider membuat referensi model, +status autentikasi, metadata model, dan pemilihan `/model` terlihat oleh bagian lain +OpenClaw. Harness kemudian mengklaim provider tersebut di `supports(...)`. Plugin Codex bawaan mengikuti pola ini: -- provider id: `codex` -- ref model pengguna: `codex/gpt-5.4`, `codex/gpt-5.2`, atau model lain yang dikembalikan +- id provider: `codex` +- referensi model pengguna: `codex/gpt-5.4`, `codex/gpt-5.2`, atau model lain yang dikembalikan oleh server aplikasi Codex -- harness id: `codex` -- auth: ketersediaan provider sintetis, karena harness Codex memiliki - login/sesi Codex native +- id harness: `codex` +- autentikasi: ketersediaan provider sintetis, karena harness Codex memiliki login/sesi Codex native - permintaan app-server: OpenClaw mengirim bare model id ke Codex dan membiarkan harness berbicara dengan protokol app-server native -Plugin Codex bersifat aditif. Ref `openai/gpt-*` biasa tetap menjadi ref provider OpenAI +Plugin Codex bersifat aditif. Referensi `openai/gpt-*` biasa tetap menjadi referensi provider OpenAI dan terus menggunakan jalur provider OpenClaw normal. Pilih `codex/gpt-*` -saat Anda menginginkan auth yang dikelola Codex, penemuan model Codex, thread native, dan -eksekusi app-server Codex. `/model` dapat beralih di antara model Codex yang -dikembalikan oleh app-server Codex tanpa memerlukan kredensial provider OpenAI. +saat Anda menginginkan autentikasi yang dikelola Codex, penemuan model Codex, thread native, dan +eksekusi app-server Codex. `/model` dapat beralih di antara model Codex yang dikembalikan +oleh app-server Codex tanpa memerlukan kredensial provider OpenAI. Untuk penyiapan operator, contoh prefiks model, dan konfigurasi khusus Codex, lihat [Codex Harness](/id/plugins/codex-harness). OpenClaw memerlukan app-server Codex `0.118.0` atau yang lebih baru. Plugin Codex memeriksa -initialize handshake app-server dan memblokir server yang lebih lama atau tanpa versi agar -OpenClaw hanya berjalan terhadap permukaan protokol yang telah diuji. +initialize handshake app-server dan memblokir server yang lebih lama atau tidak berversi agar +OpenClaw hanya berjalan terhadap surface protokol yang sudah diuji. ### Mode harness Codex native @@ -152,23 +151,23 @@ dari `openai-codex/*`: app-server. Saat mode ini berjalan, Codex memiliki thread id native, perilaku resume, -compaction, dan eksekusi app-server. OpenClaw tetap memiliki channel chat, +Compaction, dan eksekusi app-server. OpenClaw tetap memiliki saluran chat, mirror transkrip yang terlihat, kebijakan tool, persetujuan, pengiriman media, dan pemilihan sesi. Gunakan `embeddedHarness.runtime: "codex"` dengan -`embeddedHarness.fallback: "none"` saat Anda perlu membuktikan bahwa jalur -app-server Codex digunakan dan fallback PI tidak menyembunyikan harness native yang rusak. +`embeddedHarness.fallback: "none"` saat Anda perlu membuktikan bahwa hanya jalur Codex +app-server yang dapat mengklaim run. Konfigurasi itu hanyalah penjaga pemilihan: +kegagalan app-server Codex sudah langsung gagal alih-alih mencoba lagi melalui PI. -## Nonaktifkan fallback PI +## Menonaktifkan fallback PI Secara default, OpenClaw menjalankan agen tertanam dengan `agents.defaults.embeddedHarness` -diatur ke `{ runtime: "auto", fallback: "pi" }`. Dalam mode `auto`, plugin -harness yang terdaftar dapat mengklaim pasangan provider/model. Jika tidak ada yang cocok, -atau jika harness plugin yang dipilih otomatis gagal sebelum menghasilkan output, -OpenClaw fallback ke PI. +disetel ke `{ runtime: "auto", fallback: "pi" }`. Dalam mode `auto`, plugin terdaftar +harness dapat mengklaim pasangan provider/model. Jika tidak ada yang cocok, OpenClaw melakukan fallback +ke PI. -Tetapkan `fallback: "none"` saat Anda perlu membuktikan bahwa harness plugin adalah satu-satunya -runtime yang sedang diuji. Ini menonaktifkan fallback PI otomatis; ini tidak memblokir -`runtime: "pi"` yang eksplisit atau `OPENCLAW_AGENT_RUNTIME=pi`. +Setel `fallback: "none"` saat Anda perlu agar kegagalan pemilihan harness plugin yang hilang +langsung gagal alih-alih menggunakan PI. Kegagalan harness plugin yang terpilih sudah gagal keras. +Ini tidak memblokir `runtime: "pi"` eksplisit atau `OPENCLAW_AGENT_RUNTIME=pi`. Untuk run tertanam khusus Codex: @@ -187,7 +186,7 @@ Untuk run tertanam khusus Codex: ``` Jika Anda ingin harness plugin terdaftar mana pun mengklaim model yang cocok tetapi tidak pernah -ingin OpenClaw diam-diam fallback ke PI, pertahankan `runtime: "auto"` dan nonaktifkan +ingin OpenClaw diam-diam melakukan fallback ke PI, pertahankan `runtime: "auto"` dan nonaktifkan fallback: ```json @@ -238,23 +237,23 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \ openclaw gateway run ``` -Dengan fallback dinonaktifkan, sebuah sesi gagal lebih awal saat harness yang diminta tidak -terdaftar, tidak mendukung provider/model yang telah diselesaikan, atau gagal sebelum +Dengan fallback dinonaktifkan, sebuah sesi gagal lebih awal ketika harness yang diminta tidak +terdaftar, tidak mendukung provider/model yang telah di-resolve, atau gagal sebelum menghasilkan efek samping giliran. Ini disengaja untuk deployment khusus Codex dan -untuk live test yang harus membuktikan bahwa jalur app-server Codex benar-benar digunakan. +untuk pengujian live yang harus membuktikan bahwa jalur app-server Codex benar-benar digunakan. -Pengaturan ini hanya mengontrol harness agen tertanam. Ini tidak menonaktifkan +Setelan ini hanya mengontrol harness agen tertanam. Ini tidak menonaktifkan perutean model khusus provider untuk gambar, video, musik, TTS, PDF, atau yang lainnya. ## Sesi native dan mirror transkrip -Sebuah harness dapat menyimpan session id native, thread id, atau token resume di sisi daemon. -Pertahankan pengikatan itu secara eksplisit terkait dengan sesi OpenClaw, dan tetap -mirror output asisten/tool yang terlihat oleh pengguna ke dalam transkrip OpenClaw. +Harness dapat menyimpan session id native, thread id, atau token resume sisi daemon. +Pertahankan keterikatan itu secara eksplisit terkait dengan sesi OpenClaw, dan tetap +mirror output assistant/tool yang terlihat pengguna ke dalam transkrip OpenClaw. Transkrip OpenClaw tetap menjadi lapisan kompatibilitas untuk: -- riwayat sesi yang terlihat di channel +- riwayat sesi yang terlihat di saluran - pencarian dan pengindeksan transkrip - beralih kembali ke harness PI bawaan pada giliran berikutnya - perilaku `/new`, `/reset`, dan penghapusan sesi generik @@ -264,22 +263,22 @@ menghapusnya saat sesi OpenClaw pemilik di-reset. ## Hasil tool dan media -Core membangun daftar tool OpenClaw dan meneruskannya ke upaya yang sudah disiapkan. -Saat sebuah harness mengeksekusi pemanggilan tool dinamis, kembalikan hasil tool melalui -bentuk hasil harness alih-alih mengirim media channel sendiri. +Core membangun daftar tool OpenClaw dan meneruskannya ke prepared attempt. +Saat harness mengeksekusi pemanggilan tool dinamis, kembalikan hasil tool melalui +shape hasil harness alih-alih mengirim media saluran sendiri. -Ini menjaga output teks, gambar, video, musik, TTS, persetujuan, dan tool perpesanan -tetap berada pada jalur pengiriman yang sama seperti run berbasis PI. +Ini menjaga output teks, gambar, video, musik, TTS, persetujuan, dan messaging-tool +berada pada jalur pengiriman yang sama seperti run yang didukung PI. -## Batasan saat ini +## Keterbatasan saat ini - Jalur import publik bersifat generik, tetapi beberapa alias tipe attempt/result masih membawa nama `Pi` demi kompatibilitas. -- Pemasangan harness pihak ketiga masih eksperimental. Utamakan plugin provider +- Instalasi harness pihak ketiga masih eksperimental. Pilih plugin provider sampai Anda memerlukan runtime sesi native. - Peralihan harness didukung antar giliran. Jangan mengganti harness di tengah - giliran setelah tool native, persetujuan, teks asisten, atau pengiriman - pesan telah dimulai. + giliran setelah tool native, persetujuan, teks assistant, atau pengiriman pesan + telah dimulai. ## Terkait @@ -287,4 +286,4 @@ tetap berada pada jalur pengiriman yang sama seperti run berbasis PI. - [Helper Runtime](/id/plugins/sdk-runtime) - [Plugin Provider](/id/plugins/sdk-provider-plugins) - [Codex Harness](/id/plugins/codex-harness) -- [Provider Model](/id/concepts/model-providers) +- [Penyedia Model](/id/concepts/model-providers) diff --git a/docs/id/plugins/sdk-channel-plugins.md b/docs/id/plugins/sdk-channel-plugins.md index 757b662bc..4392c0144 100644 --- a/docs/id/plugins/sdk-channel-plugins.md +++ b/docs/id/plugins/sdk-channel-plugins.md @@ -1,113 +1,120 @@ --- read_when: - - Anda sedang membangun Plugin channel perpesanan baru - - Anda ingin menghubungkan OpenClaw ke sebuah platform perpesanan + - Anda sedang membangun plugin channel perpesanan baru + - Anda ingin menghubungkan OpenClaw ke platform perpesanan - Anda perlu memahami permukaan adapter ChannelPlugin sidebarTitle: Channel Plugins -summary: Panduan langkah demi langkah untuk membangun Plugin channel perpesanan bagi OpenClaw +summary: Panduan langkah demi langkah untuk membangun plugin channel perpesanan untuk OpenClaw title: Membangun Plugin Channel x-i18n: - generated_at: "2026-04-22T04:24:05Z" + generated_at: "2026-04-22T09:15:03Z" model: gpt-5.4 provider: openai - source_hash: f08bf785cd2e16ed6ce0317f4fd55c9eccecf7476d84148ad47e7be516dd71fb + source_hash: e67d8c4be8cc4a312e5480545497b139c27bed828304de251e6258a3630dd9b5 source_path: plugins/sdk-channel-plugins.md workflow: 15 --- # Membangun Plugin Channel -Panduan ini membahas langkah demi langkah membangun Plugin channel yang menghubungkan OpenClaw ke sebuah -platform perpesanan. Di akhir, Anda akan memiliki channel yang berfungsi dengan keamanan DM, -pairing, reply threading, dan pengiriman pesan outbound. +Panduan ini menjelaskan proses membangun plugin channel yang menghubungkan OpenClaw ke +platform perpesanan. Pada akhirnya Anda akan memiliki channel yang berfungsi dengan keamanan DM, +pairing, threading balasan, dan perpesanan keluar. - Jika Anda belum pernah membangun Plugin OpenClaw sebelumnya, baca - [Getting Started](/id/plugins/building-plugins) terlebih dahulu untuk struktur - package dasar dan penyiapan manifest. + Jika Anda belum pernah membangun plugin OpenClaw sebelumnya, baca + [Memulai](/id/plugins/building-plugins) terlebih dahulu untuk struktur paket dasar + dan penyiapan manifes. -## Cara kerja Plugin channel +## Cara kerja plugin channel -Plugin channel tidak memerlukan tool send/edit/react sendiri. OpenClaw mempertahankan satu +Plugin channel tidak memerlukan tool send/edit/react sendiri. OpenClaw menyimpan satu tool `message` bersama di core. Plugin Anda memiliki: - **Config** — resolusi akun dan wizard penyiapan - **Security** — kebijakan DM dan allowlist - **Pairing** — alur persetujuan DM -- **Tata bahasa sesi** — cara id percakapan khusus provider dipetakan ke chat dasar, id thread, dan fallback induk -- **Outbound** — mengirim teks, media, dan poll ke platform -- **Threading** — cara balasan di-thread +- **Session grammar** — bagaimana id percakapan khusus provider dipetakan ke chat dasar, id thread, dan fallback parent +- **Outbound** — mengirim teks, media, dan polling ke platform +- **Threading** — bagaimana balasan di-thread +- **Heartbeat typing** — sinyal typing/sibuk opsional untuk target pengiriman heartbeat -Core memiliki tool message bersama, wiring prompt, bentuk luar session-key, -pencatatan generik `:thread:`, dan dispatch. +Core memiliki tool message bersama, wiring prompt, bentuk session-key luar, +pembukuan generik `:thread:`, dan dispatch. -Jika channel Anda menambahkan parameter message-tool yang membawa sumber media, tampilkan -nama parameter tersebut melalui `describeMessageTool(...).mediaSourceParams`. Core menggunakan -daftar eksplisit itu untuk normalisasi path sandbox dan kebijakan akses media outbound, -sehingga plugin tidak memerlukan special case shared-core untuk parameter avatar, -lampiran, atau cover-image yang khusus provider. -Lebih baik mengembalikan peta berbasis action seperti -`{ "set-profile": ["avatarUrl", "avatarPath"] }` agar action yang tidak terkait tidak -mewarisi argumen media milik action lain. Array datar tetap berfungsi untuk parameter yang -memang sengaja dibagikan di semua action yang diekspos. +Jika channel Anda mendukung indikator typing di luar balasan masuk, +ekspos `heartbeat.sendTyping(...)` pada plugin channel. Core memanggilnya dengan +target pengiriman heartbeat yang sudah di-resolve sebelum model heartbeat mulai berjalan dan +menggunakan siklus hidup keepalive/cleanup typing bersama. Tambahkan `heartbeat.clearTyping(...)` +ketika platform memerlukan sinyal berhenti yang eksplisit. -Jika platform Anda menyimpan scope tambahan di dalam id percakapan, simpan parsing itu -di plugin dengan `messaging.resolveSessionConversation(...)`. Itu adalah hook kanonis +Jika channel Anda menambahkan param message-tool yang membawa sumber media, ekspos nama +param tersebut melalui `describeMessageTool(...).mediaSourceParams`. Core menggunakan +daftar eksplisit itu untuk normalisasi path sandbox dan kebijakan akses media keluar, +sehingga plugin tidak memerlukan kasus khusus shared-core untuk param avatar, +lampiran, atau cover-image khusus provider. +Sebaiknya kembalikan map yang dikunci tindakan seperti +`{ "set-profile": ["avatarUrl", "avatarPath"] }` agar tindakan yang tidak terkait tidak +mewarisi argumen media milik tindakan lain. Array datar tetap berfungsi untuk param yang +memang sengaja dibagikan di setiap tindakan yang diekspos. + +Jika platform Anda menyimpan cakupan tambahan di dalam id percakapan, simpan parsing itu +di plugin dengan `messaging.resolveSessionConversation(...)`. Itulah hook kanonis untuk memetakan `rawId` ke id percakapan dasar, id thread opsional, -`baseConversationId` eksplisit, dan `parentConversationCandidates` -apa pun. +`baseConversationId` eksplisit, dan `parentConversationCandidates` apa pun. Saat Anda mengembalikan `parentConversationCandidates`, pertahankan urutannya dari -induk yang paling sempit ke percakapan induk/dasar yang paling luas. +parent paling sempit ke percakapan paling luas/dasar. -Plugin bawaan yang memerlukan parsing yang sama sebelum registry channel boot -juga dapat mengekspos file `session-key-api.ts` tingkat atas dengan -ekspor `resolveSessionConversation(...)` yang sesuai. Core menggunakan permukaan -yang aman saat bootstrap itu hanya ketika registry plugin runtime belum tersedia. +Bundled plugin yang memerlukan parsing yang sama sebelum registry channel aktif +juga dapat mengekspos file `session-key-api.ts` tingkat atas dengan ekspor +`resolveSessionConversation(...)` yang sesuai. Core menggunakan permukaan yang aman +untuk bootstrap itu hanya saat registry plugin runtime belum tersedia. -`messaging.resolveParentConversationCandidates(...)` tetap tersedia sebagai fallback kompatibilitas legacy ketika sebuah plugin hanya memerlukan fallback induk di atas +`messaging.resolveParentConversationCandidates(...)` tetap tersedia sebagai fallback +kompatibilitas lama ketika plugin hanya memerlukan fallback parent di atas id generik/raw. Jika kedua hook ada, core menggunakan `resolveSessionConversation(...).parentConversationCandidates` terlebih dahulu dan hanya -fallback ke `resolveParentConversationCandidates(...)` ketika hook kanonis -menghilangkannya. +kembali ke `resolveParentConversationCandidates(...)` ketika hook kanonis +tidak menyediakannya. -## Persetujuan dan kemampuan channel +## Persetujuan dan kapabilitas channel Sebagian besar plugin channel tidak memerlukan kode khusus persetujuan. -- Core memiliki `/approve` di chat yang sama, payload tombol persetujuan bersama, dan pengiriman fallback generik. +- Core memiliki `/approve` chat yang sama, payload tombol persetujuan bersama, dan pengiriman fallback generik. - Pilih satu objek `approvalCapability` pada plugin channel ketika channel memerlukan perilaku khusus persetujuan. -- `ChannelPlugin.approvals` dihapus. Tempatkan fakta pengiriman/native/render/auth persetujuan di `approvalCapability`. +- `ChannelPlugin.approvals` telah dihapus. Letakkan fakta pengiriman/native/render/auth persetujuan di `approvalCapability`. - `plugin.auth` hanya untuk login/logout; core tidak lagi membaca hook auth persetujuan dari objek itu. -- `approvalCapability.authorizeActorAction` dan `approvalCapability.getActionAvailabilityState` adalah seam auth persetujuan kanonis. -- Gunakan `approvalCapability.getActionAvailabilityState` untuk ketersediaan auth persetujuan chat-yang-sama. -- Jika channel Anda mengekspos persetujuan exec native, gunakan `approvalCapability.getExecInitiatingSurfaceState` untuk status permukaan-pemicu/klien-native ketika berbeda dari auth persetujuan chat-yang-sama. Core menggunakan hook khusus exec itu untuk membedakan `enabled` vs `disabled`, memutuskan apakah channel pemicu mendukung persetujuan exec native, dan menyertakan channel tersebut dalam panduan fallback klien-native. `createApproverRestrictedNativeApprovalCapability(...)` mengisi ini untuk kasus umum. -- Gunakan `outbound.shouldSuppressLocalPayloadPrompt` atau `outbound.beforeDeliverPayload` untuk perilaku siklus hidup payload yang khusus channel seperti menyembunyikan prompt persetujuan lokal duplikat atau mengirim indikator mengetik sebelum pengiriman. -- Gunakan `approvalCapability.delivery` hanya untuk perutean persetujuan native atau penekanan fallback. -- Gunakan `approvalCapability.nativeRuntime` untuk fakta persetujuan native milik channel. Pertahankan agar tetap lazy pada entrypoint channel yang hot dengan `createLazyChannelApprovalNativeRuntimeAdapter(...)`, yang dapat mengimpor modul runtime Anda sesuai kebutuhan sambil tetap memungkinkan core merakit siklus hidup persetujuan. -- Gunakan `approvalCapability.render` hanya ketika channel benar-benar memerlukan payload persetujuan kustom alih-alih renderer bersama. -- Gunakan `approvalCapability.describeExecApprovalSetup` ketika channel ingin balasan jalur-disabled menjelaskan knob config yang tepat yang diperlukan untuk mengaktifkan persetujuan exec native. Hook menerima `{ channel, channelLabel, accountId }`; channel akun bernama sebaiknya merender path berscope akun seperti `channels..accounts..execApprovals.*` alih-alih default tingkat atas. -- Jika sebuah channel dapat menyimpulkan identitas DM yang stabil mirip owner dari config yang sudah ada, gunakan `createResolvedApproverActionAuthAdapter` dari `openclaw/plugin-sdk/approval-runtime` untuk membatasi `/approve` chat-yang-sama tanpa menambahkan logika core khusus persetujuan. -- Jika sebuah channel memerlukan pengiriman persetujuan native, pertahankan kode channel tetap berfokus pada normalisasi target plus fakta transport/presentasi. Gunakan `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver`, dan `createApproverRestrictedNativeApprovalCapability` dari `openclaw/plugin-sdk/approval-runtime`. Tempatkan fakta khusus channel di balik `approvalCapability.nativeRuntime`, idealnya melalui `createChannelApprovalNativeRuntimeAdapter(...)` atau `createLazyChannelApprovalNativeRuntimeAdapter(...)`, sehingga core dapat merakit handler dan memiliki filtering permintaan, perutean, dedupe, expiry, subscription gateway, dan pemberitahuan routed-elsewhere. `nativeRuntime` dibagi menjadi beberapa seam yang lebih kecil: -- `availability` — apakah akun dikonfigurasi dan apakah sebuah permintaan seharusnya ditangani -- `presentation` — memetakan view model persetujuan bersama ke payload native pending/resolved/expired atau action final -- `transport` — menyiapkan target plus mengirim/memperbarui/menghapus pesan persetujuan native +- `approvalCapability.authorizeActorAction` dan `approvalCapability.getActionAvailabilityState` adalah seam auth persetujuan yang kanonis. +- Gunakan `approvalCapability.getActionAvailabilityState` untuk ketersediaan auth persetujuan chat yang sama. +- Jika channel Anda mengekspos persetujuan exec native, gunakan `approvalCapability.getExecInitiatingSurfaceState` untuk status initiating-surface/native-client ketika berbeda dari auth persetujuan chat yang sama. Core menggunakan hook khusus exec itu untuk membedakan `enabled` vs `disabled`, memutuskan apakah channel pemicu mendukung persetujuan exec native, dan menyertakan channel tersebut dalam panduan fallback native-client. `createApproverRestrictedNativeApprovalCapability(...)` mengisi ini untuk kasus umum. +- Gunakan `outbound.shouldSuppressLocalPayloadPrompt` atau `outbound.beforeDeliverPayload` untuk perilaku siklus hidup payload khusus channel seperti menyembunyikan prompt persetujuan lokal duplikat atau mengirim indikator typing sebelum pengiriman. +- Gunakan `approvalCapability.delivery` hanya untuk routing persetujuan native atau penekanan fallback. +- Gunakan `approvalCapability.nativeRuntime` untuk fakta persetujuan native yang dimiliki channel. Pertahankan agar tetap lazy pada entrypoint channel yang panas dengan `createLazyChannelApprovalNativeRuntimeAdapter(...)`, yang dapat mengimpor modul runtime Anda sesuai kebutuhan sambil tetap membiarkan core merakit siklus hidup persetujuan. +- Gunakan `approvalCapability.render` hanya ketika channel benar-benar memerlukan payload persetujuan kustom, bukan renderer bersama. +- Gunakan `approvalCapability.describeExecApprovalSetup` ketika channel ingin balasan pada jalur nonaktif menjelaskan knob konfigurasi yang tepat untuk mengaktifkan persetujuan exec native. Hook menerima `{ channel, channelLabel, accountId }`; channel akun bernama harus merender path bercakupan akun seperti `channels..accounts..execApprovals.*` alih-alih default tingkat atas. +- Jika sebuah channel dapat menyimpulkan identitas DM mirip pemilik yang stabil dari config yang ada, gunakan `createResolvedApproverActionAuthAdapter` dari `openclaw/plugin-sdk/approval-runtime` untuk membatasi `/approve` chat yang sama tanpa menambahkan logika core khusus persetujuan. +- Jika channel memerlukan pengiriman persetujuan native, jaga agar kode channel tetap berfokus pada normalisasi target ditambah fakta transport/presentasi. Gunakan `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver`, dan `createApproverRestrictedNativeApprovalCapability` dari `openclaw/plugin-sdk/approval-runtime`. Letakkan fakta khusus channel di balik `approvalCapability.nativeRuntime`, idealnya melalui `createChannelApprovalNativeRuntimeAdapter(...)` atau `createLazyChannelApprovalNativeRuntimeAdapter(...)`, sehingga core dapat merakit handler dan memiliki penyaringan permintaan, routing, dedupe, expiry, subscription gateway, dan pemberitahuan dialihkan-ke-tempat-lain. `nativeRuntime` dibagi menjadi beberapa seam yang lebih kecil: +- `availability` — apakah akun sudah dikonfigurasi dan apakah sebuah permintaan harus ditangani +- `presentation` — memetakan view model persetujuan bersama ke payload native pending/resolved/expired atau tindakan final +- `transport` — menyiapkan target serta mengirim/memperbarui/menghapus pesan persetujuan native - `interactions` — hook bind/unbind/clear-action opsional untuk tombol atau reaksi native - `observe` — hook diagnostik pengiriman opsional -- Jika channel memerlukan objek milik runtime seperti client, token, Bolt app, atau penerima webhook, daftarkan objek tersebut melalui `openclaw/plugin-sdk/channel-runtime-context`. Registry runtime-context generik memungkinkan core melakukan bootstrap handler berbasis capability dari status startup channel tanpa menambahkan wrapper glue khusus persetujuan. -- Gunakan `createChannelApprovalHandler` atau `createChannelNativeApprovalRuntime` tingkat lebih rendah hanya ketika seam berbasis capability belum cukup ekspresif. -- Channel persetujuan native harus merutekan `accountId` dan `approvalKind` melalui helper tersebut. `accountId` menjaga kebijakan persetujuan multi-akun tetap terbatas pada akun bot yang benar, dan `approvalKind` menjaga perilaku persetujuan exec vs plugin tetap tersedia bagi channel tanpa cabang hardcoded di core. -- Core sekarang juga memiliki pemberitahuan pengalihan rute persetujuan. Plugin channel tidak boleh mengirim pesan tindak lanjut sendiri seperti "approval went to DMs / another channel" dari `createChannelNativeApprovalRuntime`; sebaliknya, ekspos perutean origin + DM approver yang akurat melalui helper capability persetujuan bersama dan biarkan core mengagregasi pengiriman aktual sebelum memposting pemberitahuan kembali ke chat pemicu. -- Pertahankan jenis id persetujuan yang dikirim secara end-to-end. Klien native tidak boleh - menebak atau menulis ulang perutean persetujuan exec vs plugin dari status lokal channel. -- Jenis persetujuan yang berbeda dengan sengaja dapat mengekspos permukaan native yang berbeda. - Contoh bawaan saat ini: - - Slack mempertahankan perutean persetujuan native tersedia untuk id exec dan plugin. - - Matrix mempertahankan perutean DM/channel native yang sama dan UX reaksi untuk persetujuan exec - dan plugin, sambil tetap memungkinkan auth berbeda menurut jenis persetujuan. -- `createApproverRestrictedNativeApprovalAdapter` masih ada sebagai wrapper kompatibilitas, tetapi kode baru sebaiknya memilih capability builder dan mengekspos `approvalCapability` pada plugin. +- Jika channel memerlukan objek yang dimiliki runtime seperti client, token, aplikasi Bolt, atau penerima Webhook, daftarkan objek tersebut melalui `openclaw/plugin-sdk/channel-runtime-context`. Registry runtime-context generik memungkinkan core melakukan bootstrap handler berbasis kapabilitas dari status startup channel tanpa menambahkan glue wrapper khusus persetujuan. +- Gunakan `createChannelApprovalHandler` atau `createChannelNativeApprovalRuntime` level lebih rendah hanya ketika seam berbasis kapabilitas belum cukup ekspresif. +- Channel persetujuan native harus merutekan `accountId` dan `approvalKind` melalui helper tersebut. `accountId` menjaga agar kebijakan persetujuan multi-akun tetap bercakupan pada akun bot yang tepat, dan `approvalKind` menjaga agar perilaku persetujuan exec vs plugin tetap tersedia bagi channel tanpa cabang hardcoded di core. +- Core sekarang juga memiliki pemberitahuan reroute persetujuan. Plugin channel tidak boleh mengirim pesan tindak lanjut sendiri seperti "persetujuan masuk ke DM / channel lain" dari `createChannelNativeApprovalRuntime`; sebaliknya, ekspos routing origin + approver-DM yang akurat melalui helper kapabilitas persetujuan bersama dan biarkan core mengagregasi pengiriman aktual sebelum memposting pemberitahuan kembali ke chat pemicu. +- Pertahankan jenis id persetujuan yang sudah dikirim secara end-to-end. Client native tidak boleh + menebak atau menulis ulang routing persetujuan exec vs plugin dari status lokal channel. +- Jenis persetujuan yang berbeda dapat dengan sengaja mengekspos permukaan native yang berbeda. + Contoh bundled saat ini: + - Slack tetap menyediakan routing persetujuan native untuk id exec dan plugin. + - Matrix mempertahankan routing DM/channel native dan UX reaksi yang sama untuk persetujuan exec + dan plugin, sambil tetap membiarkan auth berbeda menurut jenis persetujuan. +- `createApproverRestrictedNativeApprovalAdapter` masih ada sebagai wrapper kompatibilitas, tetapi kode baru sebaiknya memilih builder kapabilitas dan mengekspos `approvalCapability` pada plugin. -Untuk entrypoint channel yang hot, pilih subpath runtime yang lebih sempit ketika Anda hanya +Untuk entrypoint channel yang panas, pilih subpath runtime yang lebih sempit saat Anda hanya memerlukan satu bagian dari keluarga itu: - `openclaw/plugin-sdk/approval-auth-runtime` @@ -120,34 +127,39 @@ memerlukan satu bagian dari keluarga itu: - `openclaw/plugin-sdk/approval-reply-runtime` - `openclaw/plugin-sdk/channel-runtime-context` -Demikian pula, pilih `openclaw/plugin-sdk/setup-runtime`, +Demikian juga, pilih `openclaw/plugin-sdk/setup-runtime`, `openclaw/plugin-sdk/setup-adapter-runtime`, `openclaw/plugin-sdk/reply-runtime`, `openclaw/plugin-sdk/reply-dispatch-runtime`, `openclaw/plugin-sdk/reply-reference`, dan -`openclaw/plugin-sdk/reply-chunking` ketika Anda tidak memerlukan permukaan umbrella +`openclaw/plugin-sdk/reply-chunking` ketika Anda tidak memerlukan permukaan payung yang lebih luas. Khusus untuk setup: - `openclaw/plugin-sdk/setup-runtime` mencakup helper setup yang aman untuk runtime: - adapter patch setup yang aman untuk import (`createPatchedAccountSetupAdapter`, + adapter patch setup yang aman untuk impor (`createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`), output catatan lookup, `promptResolvedAllowFrom`, `splitSetupEntries`, dan builder setup-proxy yang didelegasikan -- `openclaw/plugin-sdk/setup-adapter-runtime` adalah seam adapter sadar-env yang sempit - untuk `createEnvPatchedAccountSetupAdapter` -- `openclaw/plugin-sdk/channel-setup` mencakup builder setup pemasangan-opsional +- `openclaw/plugin-sdk/setup-adapter-runtime` adalah + seam adapter sempit yang sadar env untuk `createEnvPatchedAccountSetupAdapter` +- `openclaw/plugin-sdk/channel-setup` mencakup builder setup opsional-install plus beberapa primitif yang aman untuk setup: `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, Jika channel Anda mendukung setup atau auth berbasis env dan alur startup/config generik perlu mengetahui nama env tersebut sebelum runtime dimuat, deklarasikan nama itu di -manifest plugin dengan `channelEnvVars`. Pertahankan `envVars` runtime channel atau -konstanta lokal untuk salinan yang ditujukan kepada operator saja. +manifes plugin dengan `channelEnvVars`. Pertahankan `envVars` runtime channel atau +konstanta lokal hanya untuk salinan yang ditujukan kepada operator. -Jika channel Anda dapat muncul di `status`, `channels list`, `channels status`, atau pemindaian SecretRef sebelum runtime plugin dimulai, tambahkan `openclaw.setupEntry` di `package.json`. Entrypoint itu harus aman untuk diimpor pada path perintah read-only dan harus mengembalikan metadata channel, adapter config yang aman untuk setup, adapter status, dan metadata target secret channel yang diperlukan untuk ringkasan tersebut. Jangan memulai client, listener, atau runtime transport dari entri setup. +Jika channel Anda dapat muncul di `status`, `channels list`, `channels status`, atau pemindaian +SecretRef sebelum runtime plugin dimulai, tambahkan `openclaw.setupEntry` di +`package.json`. Entrypoint itu harus aman untuk diimpor pada jalur perintah baca-saja +dan harus mengembalikan metadata channel, adapter config yang aman untuk setup, adapter status, +dan metadata target secret channel yang diperlukan untuk ringkasan tersebut. Jangan +memulai client, listener, atau runtime transport dari entri setup. `createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, dan @@ -157,10 +169,12 @@ Jika channel Anda dapat muncul di `status`, `channels list`, `channels status`, helper setup/config bersama yang lebih berat seperti `moveSingleAccountChannelSectionToDefaultAccount(...)` -Jika channel Anda hanya ingin mengiklankan "instal plugin ini terlebih dahulu" di permukaan -setup, pilih `createOptionalChannelSetupSurface(...)`. Adapter/wizard yang dihasilkan gagal tertutup pada penulisan config dan finalisasi, dan menggunakan ulang pesan install-required yang sama di validasi, finalize, dan salinan tautan dokumen. +Jika channel Anda hanya ingin mengiklankan "instal plugin ini terlebih dahulu" pada +permukaan setup, pilih `createOptionalChannelSetupSurface(...)`. Adapter/wizard yang dihasilkan +gagal-tertutup pada penulisan config dan finalisasi, dan menggunakan kembali pesan install-required +yang sama di seluruh salinan validasi, finalize, dan tautan docs. -Untuk path channel hot lainnya, pilih helper yang sempit daripada permukaan legacy yang lebih luas: +Untuk jalur channel panas lainnya, pilih helper yang sempit daripada permukaan lama yang lebih luas: - `openclaw/plugin-sdk/account-core`, `openclaw/plugin-sdk/account-id`, @@ -168,45 +182,44 @@ Untuk path channel hot lainnya, pilih helper yang sempit daripada permukaan lega `openclaw/plugin-sdk/account-helpers` untuk config multi-akun dan fallback akun default - `openclaw/plugin-sdk/inbound-envelope` dan - `openclaw/plugin-sdk/inbound-reply-dispatch` untuk route/envelope inbound dan + `openclaw/plugin-sdk/inbound-reply-dispatch` untuk route/envelope masuk dan wiring record-and-dispatch - `openclaw/plugin-sdk/messaging-targets` untuk parsing/pencocokan target - `openclaw/plugin-sdk/outbound-media` dan - `openclaw/plugin-sdk/outbound-runtime` untuk pemuatan media plus delegasi - identitas/send outbound dan perencanaan payload + `openclaw/plugin-sdk/outbound-runtime` untuk pemuatan media plus + delegasi identitas/pengiriman keluar dan perencanaan payload - `buildThreadAwareOutboundSessionRoute(...)` dari - `openclaw/plugin-sdk/channel-core` ketika route outbound harus mempertahankan + `openclaw/plugin-sdk/channel-core` saat route keluar harus mempertahankan `replyToId`/`threadId` eksplisit atau memulihkan sesi `:thread:` saat ini - setelah key sesi dasar masih cocok. Plugin provider dapat meng-override - prioritas, perilaku suffix, dan normalisasi id thread ketika platformnya + setelah kunci sesi dasar masih cocok. Plugin provider dapat mengganti + precedence, perilaku suffix, dan normalisasi id thread ketika platformnya memiliki semantik pengiriman thread native. - `openclaw/plugin-sdk/thread-bindings-runtime` untuk siklus hidup thread-binding - dan registrasi adapter + dan pendaftaran adapter - `openclaw/plugin-sdk/agent-media-payload` hanya ketika tata letak field payload - agent/media legacy masih diperlukan -- `openclaw/plugin-sdk/telegram-command-config` untuk normalisasi custom-command - Telegram, validasi duplikat/konflik, dan kontrak config command - yang stabil terhadap fallback + agent/media lama masih diperlukan +- `openclaw/plugin-sdk/telegram-command-config` untuk normalisasi custom-command Telegram, + validasi duplikat/konflik, dan kontrak config perintah yang stabil untuk fallback -Channel khusus auth biasanya dapat berhenti pada path default: core menangani persetujuan dan plugin hanya mengekspos kemampuan outbound/auth. Channel persetujuan native seperti Matrix, Slack, Telegram, dan transport chat kustom sebaiknya menggunakan helper native bersama alih-alih membuat siklus hidup persetujuan sendiri. +Channel yang hanya auth biasanya dapat berhenti di jalur default: core menangani persetujuan dan plugin hanya mengekspos kapabilitas outbound/auth. Channel persetujuan native seperti Matrix, Slack, Telegram, dan transport chat kustom sebaiknya menggunakan helper native bersama alih-alih membuat siklus hidup persetujuannya sendiri. -## Kebijakan mention inbound +## Kebijakan mention masuk -Pertahankan penanganan mention inbound tetap terpisah dalam dua lapisan: +Pertahankan penanganan mention masuk tetap terbagi dalam dua lapisan: -- pengumpulan bukti milik plugin +- pengumpulan bukti yang dimiliki plugin - evaluasi kebijakan bersama Gunakan `openclaw/plugin-sdk/channel-mention-gating` untuk keputusan kebijakan mention. -Gunakan `openclaw/plugin-sdk/channel-inbound` hanya ketika Anda memerlukan barrel helper -inbound yang lebih luas. +Gunakan `openclaw/plugin-sdk/channel-inbound` hanya saat Anda memerlukan barrel helper +masuk yang lebih luas. Cocok untuk logika lokal plugin: - deteksi reply-to-bot - deteksi quoted-bot - pemeriksaan partisipasi thread -- pengecualian pesan layanan/sistem +- pengecualian service/system-message - cache native platform yang diperlukan untuk membuktikan partisipasi bot Cocok untuk helper bersama: @@ -214,14 +227,14 @@ Cocok untuk helper bersama: - `requireMention` - hasil mention eksplisit - allowlist mention implisit -- bypass command +- bypass perintah - keputusan skip final Alur yang disarankan: 1. Hitung fakta mention lokal. 2. Teruskan fakta tersebut ke `resolveInboundMentionDecision({ facts, policy })`. -3. Gunakan `decision.effectiveWasMentioned`, `decision.shouldBypassMention`, dan `decision.shouldSkip` di gerbang inbound Anda. +3. Gunakan `decision.effectiveWasMentioned`, `decision.shouldBypassMention`, dan `decision.shouldSkip` di gerbang masuk Anda. ```typescript import { @@ -261,7 +274,7 @@ if (decision.shouldSkip) return; ``` `api.runtime.channel.mentions` mengekspos helper mention bersama yang sama untuk -plugin channel bawaan yang sudah bergantung pada runtime injection: +plugin channel bundled yang sudah bergantung pada injeksi runtime: - `buildMentionRegexes` - `matchesMentionPatterns` @@ -272,9 +285,9 @@ plugin channel bawaan yang sudah bergantung pada runtime injection: Jika Anda hanya memerlukan `implicitMentionKindWhen` dan `resolveInboundMentionDecision`, impor dari `openclaw/plugin-sdk/channel-mention-gating` untuk menghindari memuat helper runtime -inbound yang tidak terkait. +masuk lain yang tidak terkait. -Helper lama `resolveMentionGating*` tetap ada pada +Helper lama `resolveMentionGating*` tetap ada di `openclaw/plugin-sdk/channel-inbound` hanya sebagai ekspor kompatibilitas. Kode baru sebaiknya menggunakan `resolveInboundMentionDecision({ facts, policy })`. @@ -282,10 +295,10 @@ sebaiknya menggunakan `resolveInboundMentionDecision({ facts, policy })`. - - Buat file plugin standar. Field `channel` di `package.json` - adalah yang menjadikan ini Plugin channel. Untuk permukaan metadata package - lengkap, lihat [Plugin Setup and Config](/id/plugins/sdk-setup#openclaw-channel): + + Buat file plugin standar. Field `channel` di `package.json` adalah + yang menjadikan ini plugin channel. Untuk permukaan metadata paket lengkap, + lihat [Setup dan Config Plugin](/id/plugins/sdk-setup#openclaw-channel): ```json package.json @@ -299,7 +312,7 @@ sebaiknya menggunakan `resolveInboundMentionDecision({ facts, policy })`. "channel": { "id": "acme-chat", "label": "Acme Chat", - "blurb": "Hubungkan OpenClaw ke Acme Chat." + "blurb": "Connect OpenClaw to Acme Chat." } } } @@ -334,9 +347,9 @@ sebaiknya menggunakan `resolveInboundMentionDecision({ facts, policy })`. - - Interface `ChannelPlugin` memiliki banyak permukaan adapter opsional. Mulailah dari - yang minimum — `id` dan `setup` — lalu tambahkan adapter sesuai kebutuhan. + + Interface `ChannelPlugin` memiliki banyak permukaan adapter opsional. Mulailah dengan + yang minimal — `id` dan `setup` — lalu tambahkan adapter sesuai kebutuhan. Buat `src/channel.ts`: @@ -361,7 +374,7 @@ sebaiknya menggunakan `resolveInboundMentionDecision({ facts, policy })`. ): ResolvedAccount { const section = (cfg.channels as Record)?.["acme-chat"]; const token = section?.token; - if (!token) throw new Error("acme-chat: token wajib diisi"); + if (!token) throw new Error("acme-chat: token wajib ada"); return { accountId: accountId ?? null, token, @@ -387,7 +400,7 @@ sebaiknya menggunakan `resolveInboundMentionDecision({ facts, policy })`. }, }), - // Keamanan DM: siapa yang boleh mengirim pesan ke bot + // Keamanan DM: siapa yang dapat mengirim pesan ke bot security: { dm: { channelKey: "acme-chat", @@ -408,7 +421,7 @@ sebaiknya menggunakan `resolveInboundMentionDecision({ facts, policy })`. }, }, - // Threading: cara balasan dikirim + // Threading: bagaimana balasan dikirim threading: { topLevelReplyToMode: "reply" }, // Outbound: kirim pesan ke platform @@ -431,16 +444,16 @@ sebaiknya menggunakan `resolveInboundMentionDecision({ facts, policy })`. }); ``` - - Alih-alih mengimplementasikan interface adapter tingkat rendah secara manual, Anda + + Alih-alih mengimplementasikan interface adapter level rendah secara manual, Anda memberikan opsi deklaratif dan builder akan menyusunnya: - | Opsi | Yang dihubungkan | + | Opsi | Yang di-wire | | --- | --- | - | `security.dm` | Resolver keamanan DM yang dibatasi dari field config | + | `security.dm` | Resolver keamanan DM bercakupan dari field config | | `pairing.text` | Alur pairing DM berbasis teks dengan pertukaran kode | - | `threading` | Resolver mode reply-to (tetap, berscope akun, atau kustom) | - | `outbound.attachedResults` | Fungsi send yang mengembalikan metadata hasil (ID pesan) | + | `threading` | Resolver mode reply-to (tetap, bercakupan akun, atau kustom) | + | `outbound.attachedResults` | Fungsi kirim yang mengembalikan metadata hasil (ID pesan) | Anda juga dapat memberikan objek adapter mentah alih-alih opsi deklaratif jika memerlukan kontrol penuh. @@ -448,7 +461,7 @@ sebaiknya menggunakan `resolveInboundMentionDecision({ facts, policy })`. - + Buat `index.ts`: ```typescript index.ts @@ -484,16 +497,16 @@ sebaiknya menggunakan `resolveInboundMentionDecision({ facts, policy })`. }); ``` - Tempatkan descriptor CLI milik channel di `registerCliMetadata(...)` agar OpenClaw - dapat menampilkannya di bantuan root tanpa mengaktifkan runtime channel penuh, - sementara muatan penuh normal tetap mengambil descriptor yang sama untuk registrasi - perintah nyata. Pertahankan `registerFull(...)` untuk pekerjaan khusus runtime. - Jika `registerFull(...)` mendaftarkan metode Gateway RPC, gunakan - prefiks khusus plugin. Namespace admin core (`config.*`, + Letakkan descriptor CLI yang dimiliki channel di `registerCliMetadata(...)` agar OpenClaw + dapat menampilkannya dalam bantuan root tanpa mengaktifkan runtime channel penuh, + sementara pemuatan penuh normal tetap mengambil descriptor yang sama untuk pendaftaran + perintah yang sesungguhnya. Pertahankan `registerFull(...)` untuk pekerjaan khusus runtime. + Jika `registerFull(...)` mendaftarkan metode RPC Gateway, gunakan prefix + khusus plugin. Namespace admin core (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) tetap dicadangkan dan selalu - diresolusikan ke `operator.admin`. - `defineChannelPluginEntry` menangani pemisahan mode registrasi secara otomatis. Lihat - [Entry Points](/id/plugins/sdk-entrypoints#definechannelpluginentry) untuk semua + di-resolve ke `operator.admin`. + `defineChannelPluginEntry` menangani pemisahan mode pendaftaran ini secara otomatis. Lihat + [Entry Point](/id/plugins/sdk-entrypoints#definechannelpluginentry) untuk semua opsi. @@ -510,31 +523,31 @@ sebaiknya menggunakan `resolveInboundMentionDecision({ facts, policy })`. OpenClaw memuat ini alih-alih entri penuh saat channel dinonaktifkan atau belum dikonfigurasi. Ini menghindari penarikan kode runtime berat selama alur setup. - Lihat [Setup and Config](/id/plugins/sdk-setup#setup-entry) untuk detail. + Lihat [Setup dan Config](/id/plugins/sdk-setup#setup-entry) untuk detailnya. - Channel workspace bawaan yang memisahkan ekspor aman-setup ke sidecar - module dapat menggunakan `defineBundledChannelSetupEntry(...)` dari - `openclaw/plugin-sdk/channel-entry-contract` ketika juga memerlukan + Channel workspace bundled yang memisahkan ekspor aman-setup ke dalam modul sidecar + dapat menggunakan `defineBundledChannelSetupEntry(...)` dari + `openclaw/plugin-sdk/channel-entry-contract` ketika mereka juga memerlukan setter runtime eksplisit pada waktu setup. - + Plugin Anda perlu menerima pesan dari platform dan meneruskannya ke - OpenClaw. Pola yang umum adalah webhook yang memverifikasi permintaan dan - mendispatch-nya melalui handler inbound channel Anda: + OpenClaw. Pola yang umum adalah Webhook yang memverifikasi permintaan dan + melakukan dispatch melalui handler masuk channel Anda: ```typescript registerFull(api) { api.registerHttpRoute({ path: "/acme-chat/webhook", - auth: "plugin", // auth dikelola plugin (verifikasi signature sendiri) + auth: "plugin", // auth yang dikelola plugin (verifikasi signature sendiri) handler: async (req, res) => { const event = parseWebhookPayload(req); - // Handler inbound Anda mendispatch pesan ke OpenClaw. - // Wiring persisnya bergantung pada SDK platform Anda — - // lihat contoh nyata di package plugin Microsoft Teams atau Google Chat bawaan. + // Handler masuk Anda melakukan dispatch pesan ke OpenClaw. + // Wiring pastinya bergantung pada SDK platform Anda — + // lihat contoh nyata di paket plugin Microsoft Teams atau Google Chat bawaan. await handleAcmeChatInbound(api, event); res.statusCode = 200; @@ -546,9 +559,9 @@ sebaiknya menggunakan `resolveInboundMentionDecision({ facts, policy })`. ``` - Penanganan pesan inbound bersifat khusus channel. Setiap Plugin channel memiliki - pipeline inbound-nya sendiri. Lihat plugin channel bawaan - (misalnya package plugin Microsoft Teams atau Google Chat) untuk pola nyata. + Penanganan pesan masuk bersifat khusus channel. Setiap plugin channel memiliki + pipeline masuknya sendiri. Lihat plugin channel bundled + (misalnya paket plugin Microsoft Teams atau Google Chat) untuk pola nyata. @@ -562,7 +575,7 @@ Tulis pengujian yang diletakkan berdampingan di `src/channel.test.ts`: import { acmeChatPlugin } from "./channel.js"; describe("plugin acme-chat", () => { - it("meresolusikan akun dari config", () => { + it("me-resolve akun dari config", () => { const cfg = { channels: { "acme-chat": { token: "test-token", allowFrom: ["user1"] }, @@ -572,7 +585,7 @@ Tulis pengujian yang diletakkan berdampingan di `src/channel.test.ts`: expect(account.token).toBe("test-token"); }); - it("memeriksa akun tanpa mewujudkan secret", () => { + it("memeriksa akun tanpa mematerialisasi secret", () => { const cfg = { channels: { "acme-chat": { token: "test-token" } }, } as any; @@ -603,7 +616,7 @@ Tulis pengujian yang diletakkan berdampingan di `src/channel.test.ts`: ``` /acme-chat/ ├── package.json # metadata openclaw.channel -├── openclaw.plugin.json # Manifest dengan schema config +├── openclaw.plugin.json # Manifes dengan skema config ├── index.ts # defineChannelPluginEntry ├── setup-entry.ts # defineSetupPluginEntry ├── api.ts # Ekspor publik (opsional) @@ -618,30 +631,30 @@ Tulis pengujian yang diletakkan berdampingan di `src/channel.test.ts`: ## Topik lanjutan - - Mode balasan tetap, berscope akun, atau kustom + + Mode balasan tetap, bercakupan akun, atau kustom - - describeMessageTool dan penemuan action + + describeMessageTool dan penemuan tindakan - + inferTargetChatType, looksLikeId, resolveTarget - + TTS, STT, media, subagent melalui api.runtime -Beberapa seam helper bawaan masih ada untuk pemeliharaan dan -kompatibilitas plugin bawaan. Seam tersebut bukan pola yang direkomendasikan untuk Plugin channel baru; -lebih baik gunakan subpath channel/setup/reply/runtime generik dari permukaan SDK umum -kecuali Anda memang memelihara keluarga plugin bawaan tersebut secara langsung. +Beberapa seam helper bundled masih ada untuk pemeliharaan bundled-plugin dan +kompatibilitas. Seam tersebut bukan pola yang direkomendasikan untuk plugin channel baru; +pilih subpath channel/setup/reply/runtime generik dari permukaan SDK umum +kecuali Anda sedang memelihara keluarga bundled plugin tersebut secara langsung. ## Langkah berikutnya -- [Provider Plugins](/id/plugins/sdk-provider-plugins) — jika plugin Anda juga menyediakan model -- [SDK Overview](/id/plugins/sdk-overview) — referensi impor subpath lengkap -- [SDK Testing](/id/plugins/sdk-testing) — utilitas pengujian dan pengujian kontrak -- [Plugin Manifest](/id/plugins/manifest) — schema manifest lengkap +- [Plugin Provider](/id/plugins/sdk-provider-plugins) — jika plugin Anda juga menyediakan model +- [Ikhtisar SDK](/id/plugins/sdk-overview) — referensi impor subpath lengkap +- [SDK Testing](/id/plugins/sdk-testing) — utilitas pengujian dan contract test +- [Manifes Plugin](/id/plugins/manifest) — skema manifes lengkap diff --git a/docs/id/plugins/sdk-overview.md b/docs/id/plugins/sdk-overview.md index ed0bfe6ab..59bf72ee5 100644 --- a/docs/id/plugins/sdk-overview.md +++ b/docs/id/plugins/sdk-overview.md @@ -4,24 +4,24 @@ read_when: - Anda menginginkan referensi untuk semua metode pendaftaran pada OpenClawPluginApi - Anda sedang mencari ekspor SDK tertentu sidebarTitle: SDK Overview -summary: Peta impor, referensi API pendaftaran, dan arsitektur SDK -title: Ikhtisar SDK Plugin +summary: Import map, referensi API pendaftaran, dan arsitektur SDK +title: Ringkasan SDK Plugin x-i18n: - generated_at: "2026-04-22T04:24:48Z" + generated_at: "2026-04-22T09:15:30Z" model: gpt-5.4 provider: openai - source_hash: 8045c11976bbda6afe3303a0aab08caf0d0a86ebcf1aaaf927943b90cc517673 + source_hash: e57019e6f9a7fed7842ac575e025b6db41d125f5fa9d0d1de03923fdb1f6bcc3 source_path: plugins/sdk-overview.md workflow: 15 --- -# Ikhtisar SDK Plugin +# Ringkasan SDK Plugin -SDK Plugin adalah kontrak bertipe antara Plugin dan inti. Halaman ini adalah -referensi untuk **apa yang harus diimpor** dan **apa yang dapat Anda daftarkan**. +SDK plugin adalah kontrak bertipe antara plugin dan inti. Halaman ini adalah +referensi untuk **apa yang perlu diimpor** dan **apa yang dapat Anda daftarkan**. - **Mencari panduan cara?** + **Mencari panduan cara melakukannya?** - Plugin pertama? Mulai dengan [Getting Started](/id/plugins/building-plugins) - Plugin channel? Lihat [Channel Plugins](/id/plugins/sdk-channel-plugins) - Plugin provider? Lihat [Provider Plugins](/id/plugins/sdk-provider-plugins) @@ -37,38 +37,38 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` Setiap subpath adalah modul kecil yang mandiri. Ini menjaga startup tetap cepat dan -mencegah masalah dependensi melingkar. Untuk helper entri/build khusus channel, -pilih `openclaw/plugin-sdk/channel-core`; pertahankan `openclaw/plugin-sdk/core` untuk -permukaan umbrella yang lebih luas dan helper bersama seperti +mencegah masalah dependensi sirkular. Untuk helper build/entry khusus channel, +gunakan `openclaw/plugin-sdk/channel-core`; pertahankan `openclaw/plugin-sdk/core` untuk +permukaan payung yang lebih luas dan helper bersama seperti `buildChannelConfigSchema`. Jangan tambahkan 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 ber-merek channel. Plugin bawaan harus menyusun subpath -SDK generik di dalam barrel `api.ts` atau `runtime-api.ts` mereka sendiri, dan inti -harus menggunakan barrel lokal Plugin tersebut atau menambahkan kontrak SDK generik sempit -ketika kebutuhan tersebut benar-benar lintas-channel. +seam helper bermerek channel. Plugin bawaan harus menyusun subpath +SDK generik di dalam barrel `api.ts` atau `runtime-api.ts` milik mereka sendiri, dan inti +sebaiknya menggunakan barrel lokal plugin tersebut atau menambahkan kontrak SDK generik sempit +ketika kebutuhannya benar-benar lintas-channel. -Peta ekspor yang dihasilkan masih berisi sejumlah kecil seam helper Plugin bawaan -seperti `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, -`plugin-sdk/zalo`, `plugin-sdk/zalo-setup`, dan `plugin-sdk/matrix*`. Subpath -tersebut ada hanya untuk pemeliharaan dan kompatibilitas Plugin bawaan; subpath itu -sengaja dihilangkan dari tabel umum di bawah dan bukan path impor yang -direkomendasikan untuk Plugin pihak ketiga baru. +Peta ekspor yang dihasilkan masih berisi sejumlah kecil +seam helper plugin bawaan seperti `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, +`plugin-sdk/zalo`, `plugin-sdk/zalo-setup`, dan `plugin-sdk/matrix*`. Subpath tersebut +hanya ada untuk pemeliharaan dan kompatibilitas plugin bawaan; subpath itu +sengaja dihilangkan dari tabel umum di bawah ini dan bukan path impor yang direkomendasikan +untuk plugin pihak ketiga yang baru. ## Referensi subpath -Subpath yang paling umum digunakan, dikelompokkan berdasarkan tujuan. Daftar lengkap -200+ subpath yang dihasilkan berada di `scripts/lib/plugin-sdk-entrypoints.json`. +Subpath yang paling umum digunakan, dikelompokkan berdasarkan tujuan. Daftar lengkap yang dihasilkan berisi +200+ subpath ada di `scripts/lib/plugin-sdk-entrypoints.json`. -Subpath helper Plugin bawaan yang dicadangkan tetap muncul dalam daftar yang dihasilkan itu. -Perlakukan subpath tersebut sebagai detail implementasi/permukaan kompatibilitas kecuali halaman dokumen +Subpath helper plugin bawaan yang dicadangkan masih muncul dalam daftar yang dihasilkan tersebut. +Perlakukan itu sebagai detail implementasi/permukaan kompatibilitas kecuali sebuah halaman dokumentasi secara eksplisit mempromosikannya sebagai publik. -### Entri Plugin +### Entri plugin -| Subpath | Key exports | +| Subpath | Ekspor utama | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `plugin-sdk/plugin-entry` | `definePluginEntry` | | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | @@ -77,177 +77,177 @@ secara eksplisit mempromosikannya sebagai publik. - | Subpath | Key exports | + | Subpath | Ekspor utama | | --- | --- | | `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`, plus `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | Helper wizard setup bersama, prompt allowlist, builder status setup | + | `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/action-gate multi-akun, helper fallback akun default | + | `plugin-sdk/account-core` | Helper konfigurasi multi-akun/action-gate, helper fallback akun default | | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, helper normalisasi account-id | | `plugin-sdk/account-resolution` | Pencarian akun + helper fallback default | - | `plugin-sdk/account-helpers` | Helper sempit account-list/account-action | + | `plugin-sdk/account-helpers` | Helper sempit daftar-aksi akun/aksi akun | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | | `plugin-sdk/channel-config-schema` | Tipe skema konfigurasi channel | - | `plugin-sdk/telegram-command-config` | Helper normalisasi/validasi custom-command Telegram dengan fallback kontrak bawaan | - | `plugin-sdk/command-gating` | Helper gate otorisasi perintah sempit | + | `plugin-sdk/telegram-command-config` | Helper normalisasi/validasi custom command Telegram dengan fallback kontrak bawaan | + | `plugin-sdk/command-gating` | Helper sempit gerbang otorisasi perintah | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, helper siklus hidup/finalisasi draft stream | - | `plugin-sdk/inbound-envelope` | Helper bersama route masuk + builder envelope | - | `plugin-sdk/inbound-reply-dispatch` | Helper bersama pencatatan-dan-dispatch masuk | + | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, helper lifecycle/finalisasi stream draf | + | `plugin-sdk/inbound-envelope` | Helper bersama rute inbound + pembuat envelope | + | `plugin-sdk/inbound-reply-dispatch` | Helper bersama pencatatan dan dispatch inbound | | `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 pengiriman, dan perencanaan payload | - | `plugin-sdk/poll-runtime` | Helper normalisasi polling sempit | - | `plugin-sdk/thread-bindings-runtime` | Helper adapter dan siklus hidup thread-binding | - | `plugin-sdk/agent-media-payload` | Builder payload media agen lama | - | `plugin-sdk/conversation-runtime` | Helper binding percakapan/thread, pairing, dan binding terkonfigurasi | + | `plugin-sdk/outbound-media` | Helper bersama pemuatan media outbound | + | `plugin-sdk/outbound-runtime` | Helper identitas outbound, delegasi pengiriman, dan perencanaan payload | + | `plugin-sdk/poll-runtime` | Helper sempit normalisasi poll | + | `plugin-sdk/thread-bindings-runtime` | Helper lifecycle dan adapter pengikatan thread | + | `plugin-sdk/agent-media-payload` | Pembuat payload media agen lama | + | `plugin-sdk/conversation-runtime` | Helper pengikatan percakapan/thread, pairing, dan binding terkonfigurasi | | `plugin-sdk/runtime-config-snapshot` | Helper snapshot konfigurasi runtime | - | `plugin-sdk/runtime-group-policy` | Helper resolusi group-policy runtime | + | `plugin-sdk/runtime-group-policy` | Helper resolusi kebijakan grup runtime | | `plugin-sdk/channel-status` | Helper bersama snapshot/ringkasan status channel | - | `plugin-sdk/channel-config-primitives` | Primitif sempit skema konfigurasi channel | + | `plugin-sdk/channel-config-primitives` | Primitive sempit skema konfigurasi channel | | `plugin-sdk/channel-config-writes` | Helper otorisasi penulisan konfigurasi channel | - | `plugin-sdk/channel-plugin-common` | Ekspor prelude Plugin channel bersama | + | `plugin-sdk/channel-plugin-common` | Ekspor prelude plugin channel bersama | | `plugin-sdk/allowlist-config-edit` | Helper edit/baca konfigurasi allowlist | | `plugin-sdk/group-access` | Helper bersama keputusan akses grup | - | `plugin-sdk/direct-dm` | Helper bersama auth/guard direct-DM | + | `plugin-sdk/direct-dm` | Helper bersama autentikasi/guard direct-DM | | `plugin-sdk/interactive-runtime` | Presentasi pesan semantik, pengiriman, dan helper balasan interaktif lama. Lihat [Message Presentation](/id/plugins/message-presentation) | - | `plugin-sdk/channel-inbound` | Barrel kompatibilitas untuk debounce masuk, pencocokan mention, helper mention-policy, dan helper envelope | - | `plugin-sdk/channel-mention-gating` | Helper mention-policy sempit tanpa permukaan runtime masuk yang lebih luas | + | `plugin-sdk/channel-inbound` | Barrel kompatibilitas untuk debounce inbound, pencocokan mention, helper kebijakan mention, dan helper envelope | + | `plugin-sdk/channel-mention-gating` | Helper sempit kebijakan mention tanpa permukaan runtime inbound yang lebih luas | | `plugin-sdk/channel-location` | Helper konteks lokasi channel dan pemformatan | - | `plugin-sdk/channel-logging` | Helper logging channel untuk drop masuk dan kegagalan typing/ack | + | `plugin-sdk/channel-logging` | Helper logging channel untuk inbound yang dibuang dan kegagalan typing/ack | | `plugin-sdk/channel-send-result` | Tipe hasil balasan | - | `plugin-sdk/channel-actions` | Helper aksi pesan channel, plus helper skema native yang deprecated yang dipertahankan untuk kompatibilitas Plugin | + | `plugin-sdk/channel-actions` | Helper aksi pesan channel, plus helper skema native yang sudah deprecated dan dipertahankan untuk kompatibilitas plugin | | `plugin-sdk/channel-targets` | Helper parsing/pencocokan target | | `plugin-sdk/channel-contract` | Tipe kontrak channel | - | `plugin-sdk/channel-feedback` | Pengkabelan feedback/reaksi | - | `plugin-sdk/channel-secret-runtime` | Helper kontrak secret sempit seperti `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, dan tipe target secret | + | `plugin-sdk/channel-feedback` | Wiring umpan balik/reaksi | + | `plugin-sdk/channel-secret-runtime` | Helper sempit kontrak rahasia seperti `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, dan tipe target rahasia | - | Subpath | Key exports | + | Subpath | Ekspor utama | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | | `plugin-sdk/provider-setup` | Helper setup provider lokal/self-hosted yang dikurasi | - | `plugin-sdk/self-hosted-provider-setup` | Helper setup provider self-hosted yang kompatibel dengan OpenAI dan terfokus | + | `plugin-sdk/self-hosted-provider-setup` | Helper setup provider self-hosted terfokus yang kompatibel dengan OpenAI | | `plugin-sdk/cli-backend` | Default backend CLI + konstanta watchdog | - | `plugin-sdk/provider-auth-runtime` | Helper runtime resolusi API-key untuk Plugin provider | - | `plugin-sdk/provider-auth-api-key` | Helper onboarding/penulisan profil API-key seperti `upsertApiKeyProfile` | - | `plugin-sdk/provider-auth-result` | Builder hasil auth OAuth standar | - | `plugin-sdk/provider-auth-login` | Helper login interaktif bersama untuk Plugin provider | - | `plugin-sdk/provider-env-vars` | Helper pencarian variabel lingkungan auth provider | + | `plugin-sdk/provider-auth-runtime` | Helper runtime resolusi API key untuk plugin provider | + | `plugin-sdk/provider-auth-api-key` | Helper onboarding/penulisan profil API key seperti `upsertApiKeyProfile` | + | `plugin-sdk/provider-auth-result` | Pembuat auth-result OAuth standar | + | `plugin-sdk/provider-auth-login` | Helper login interaktif bersama untuk plugin provider | + | `plugin-sdk/provider-env-vars` | Helper pencarian env var autentikasi provider | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, builder replay-policy bersama, helper endpoint provider, dan helper normalisasi model-id seperti `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-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 generik kapabilitas HTTP/endpoint provider | - | `plugin-sdk/provider-web-fetch-contract` | Helper kontrak sempit konfigurasi/seleksi web-fetch seperti `enablePluginInConfig` dan `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | Helper pendaftaran/cache provider web-fetch | - | `plugin-sdk/provider-web-search-config-contract` | Helper sempit konfigurasi/kredensial web-search untuk provider yang tidak memerlukan pengkabelan pengaktifan Plugin | - | `plugin-sdk/provider-web-search-contract` | Helper kontrak sempit konfigurasi/kredensial web-search seperti `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`, dan setter/getter kredensial yang dicakup | - | `plugin-sdk/provider-web-search` | Helper pendaftaran/cache/runtime provider web-search | + | `plugin-sdk/provider-http` | Helper HTTP/kemampuan endpoint provider generik | + | `plugin-sdk/provider-web-fetch-contract` | Helper sempit kontrak konfigurasi/seleksi web-fetch seperti `enablePluginInConfig` dan `WebFetchProviderPlugin` | + | `plugin-sdk/provider-web-fetch` | Helper registrasi/cache provider web-fetch | + | `plugin-sdk/provider-web-search-config-contract` | Helper sempit konfigurasi/kredensial web-search untuk provider yang tidak memerlukan wiring plugin-enable | + | `plugin-sdk/provider-web-search-contract` | Helper sempit kontrak konfigurasi/kredensial web-search seperti `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`, dan setter/getter kredensial terlingkup | + | `plugin-sdk/provider-web-search` | Helper registrasi/cache/runtime provider web-search | | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, pembersihan skema Gemini + diagnostik, dan helper kompatibilitas xAI seperti `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | `fetchClaudeUsage` dan sejenisnya | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipe wrapper stream, dan helper wrapper bersama Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-transport-runtime` | Helper transport provider native seperti guarded fetch, transform pesan transport, dan stream event transport yang dapat ditulis | + | `plugin-sdk/provider-usage` | `fetchClaudeUsage` dan yang serupa | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipe wrapper stream, dan helper wrapper bersama untuk Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-transport-runtime` | Helper transport provider native seperti guarded fetch, transformasi pesan transport, dan writable transport event stream | | `plugin-sdk/provider-onboard` | Helper patch konfigurasi onboarding | | `plugin-sdk/global-singleton` | Helper singleton/map/cache lokal-proses | - - | Subpath | Key exports | + + | Subpath | Ekspor utama | | --- | --- | - | `plugin-sdk/command-auth` | `resolveControlCommandGate`, helper registry perintah, helper otorisasi pengirim | - | `plugin-sdk/command-status` | Builder pesan perintah/bantuan 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-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 hot | - | `plugin-sdk/approval-handler-runtime` | Helper runtime handler persetujuan yang lebih luas; pilih seam adapter/gateway yang lebih sempit bila itu sudah cukup | - | `plugin-sdk/approval-native-runtime` | Helper target persetujuan native + account-binding | - | `plugin-sdk/approval-reply-runtime` | Helper payload balasan persetujuan exec/Plugin | - | `plugin-sdk/command-auth-native` | Helper auth perintah native + target sesi native | + | `plugin-sdk/command-auth` | `resolveControlCommandGate`, helper registri perintah, helper otorisasi pengirim | + | `plugin-sdk/command-status` | Pembuat pesan perintah/bantuan seperti `buildCommandsMessagePaginated` dan `buildHelpMessage` | + | `plugin-sdk/approval-auth-runtime` | Resolusi approver dan helper autentikasi tindakan dalam chat yang sama | + | `plugin-sdk/approval-client-runtime` | Helper profil/filter approval exec native | + | `plugin-sdk/approval-delivery-runtime` | Adapter kemampuan/pengiriman approval native | + | `plugin-sdk/approval-gateway-runtime` | Helper bersama resolusi gateway approval | + | `plugin-sdk/approval-handler-adapter-runtime` | Helper ringan pemuatan adapter approval native untuk entrypoint channel yang panas | + | `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 approval native + pengikatan akun | + | `plugin-sdk/approval-reply-runtime` | Helper payload balasan approval exec/plugin | + | `plugin-sdk/command-auth-native` | Helper autentikasi perintah native + helper target sesi native | | `plugin-sdk/command-detection` | Helper bersama deteksi perintah | | `plugin-sdk/command-surface` | Normalisasi body perintah dan helper permukaan perintah | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | Helper sempit pengumpulan kontrak secret untuk permukaan secret channel/Plugin | - | `plugin-sdk/secret-ref-runtime` | `coerceSecretRef` sempit dan helper pengetikan SecretRef untuk parsing kontrak secret/konfigurasi | - | `plugin-sdk/security-runtime` | Helper bersama trust, gating DM, konten eksternal, dan pengumpulan secret | - | `plugin-sdk/ssrf-policy` | Helper kebijakan SSRF host allowlist dan jaringan privat | + | `plugin-sdk/channel-secret-runtime` | Helper sempit pengumpulan kontrak rahasia untuk permukaan rahasia channel/plugin | + | `plugin-sdk/secret-ref-runtime` | Helper sempit `coerceSecretRef` dan pengetikan SecretRef untuk parsing kontrak rahasia/konfigurasi | + | `plugin-sdk/security-runtime` | Helper bersama trust, gerbang DM, konten eksternal, dan pengumpulan rahasia | + | `plugin-sdk/ssrf-policy` | Helper allowlist host dan kebijakan SSRF jaringan privat | | `plugin-sdk/ssrf-dispatcher` | Helper sempit pinned-dispatcher tanpa permukaan runtime infra yang luas | | `plugin-sdk/ssrf-runtime` | Helper pinned-dispatcher, fetch yang dijaga SSRF, dan kebijakan SSRF | - | `plugin-sdk/secret-input` | Helper parsing input secret | + | `plugin-sdk/secret-input` | Helper parsing input rahasia | | `plugin-sdk/webhook-ingress` | Helper permintaan/target Webhook | | `plugin-sdk/webhook-request-guards` | Helper ukuran body/timeout permintaan | - | Subpath | Key exports | + | Subpath | Ekspor utama | | --- | --- | - | `plugin-sdk/runtime` | Helper runtime/logging/backup/instalasi Plugin yang luas | + | `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 generik pendaftaran dan pencarian konteks runtime channel | + | `plugin-sdk/channel-runtime-context` | Helper generik pendaftaran dan lookup konteks runtime channel | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | Helper bersama perintah/hook/http/interaktif Plugin | + | `plugin-sdk/plugin-runtime` | Helper bersama perintah/hook/http/interaktif plugin | | `plugin-sdk/hook-runtime` | Helper bersama pipeline Webhook/hook internal | - | `plugin-sdk/lazy-runtime` | Helper lazy import/binding runtime seperti `createLazyRuntimeModule`, `createLazyRuntimeMethod`, dan `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Helper exec proses | + | `plugin-sdk/lazy-runtime` | Helper impor/pengikatan runtime lazy seperti `createLazyRuntimeModule`, `createLazyRuntimeMethod`, dan `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | Helper eksekusi proses | | `plugin-sdk/cli-runtime` | Helper pemformatan, wait, dan versi CLI | - | `plugin-sdk/gateway-runtime` | Helper klien gateway dan patch status channel | - | `plugin-sdk/config-runtime` | Helper muat/tulis konfigurasi | + | `plugin-sdk/gateway-runtime` | Helper klien Gateway dan patch status channel | + | `plugin-sdk/config-runtime` | Helper memuat/menulis konfigurasi | | `plugin-sdk/telegram-command-config` | Normalisasi nama/deskripsi perintah Telegram dan pemeriksaan duplikat/konflik, bahkan saat permukaan kontrak Telegram bawaan tidak tersedia | | `plugin-sdk/text-autolink-runtime` | Deteksi autolink referensi file tanpa barrel text-runtime yang luas | - | `plugin-sdk/approval-runtime` | Helper persetujuan exec/Plugin, builder kapabilitas persetujuan, helper auth/profil, helper routing/runtime native | - | `plugin-sdk/reply-runtime` | Helper runtime masuk/balasan bersama, chunking, dispatch, Heartbeat, perencana balasan | - | `plugin-sdk/reply-dispatch-runtime` | Helper dispatch/finalisasi balasan sempit | + | `plugin-sdk/approval-runtime` | Helper approval exec/plugin, pembuat kemampuan approval, helper auth/profil, helper routing/runtime native | + | `plugin-sdk/reply-runtime` | Helper runtime inbound/balasan bersama, chunking, dispatch, Heartbeat, perencana balasan | + | `plugin-sdk/reply-dispatch-runtime` | Helper sempit dispatch/finalisasi balasan | | `plugin-sdk/reply-history` | Helper bersama riwayat balasan jendela pendek seperti `buildHistoryContext`, `recordPendingHistoryEntry`, dan `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Helper chunking teks/Markdown sempit | - | `plugin-sdk/session-store-runtime` | Helper path + updated-at session store | + | `plugin-sdk/reply-chunking` | Helper sempit chunking teks/markdown | + | `plugin-sdk/session-store-runtime` | Helper path session store + updated-at | | `plugin-sdk/state-paths` | Helper path direktori state/OAuth | - | `plugin-sdk/routing` | Helper route/session-key/account binding seperti `resolveAgentRoute`, `buildAgentSessionKey`, dan `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | Helper bersama ringkasan status channel/akun, default runtime-state, dan helper metadata issue | + | `plugin-sdk/routing` | Helper pengikatan rute/kunci sesi/akun 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/string-normalization-runtime` | Helper normalisasi slug/string | - | `plugin-sdk/request-url` | Ekstrak URL string dari input seperti fetch/request | - | `plugin-sdk/run-command` | Runner perintah bertimer dengan hasil stdout/stderr ternormalisasi | - | `plugin-sdk/param-readers` | Pembaca parameter tool/CLI umum | - | `plugin-sdk/tool-payload` | Ekstrak payload ternormalisasi dari objek hasil tool | - | `plugin-sdk/tool-send` | Ekstrak field target pengiriman kanonis dari argumen tool | + | `plugin-sdk/request-url` | Mengekstrak 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 parameter umum alat/CLI | + | `plugin-sdk/tool-payload` | Mengekstrak payload yang dinormalisasi dari objek hasil alat | + | `plugin-sdk/tool-send` | Mengekstrak field target pengiriman kanonis dari argumen alat | | `plugin-sdk/temp-path` | Helper bersama path unduhan sementara | | `plugin-sdk/logging-core` | Helper logger subsistem dan redaksi | - | `plugin-sdk/markdown-table-runtime` | Helper mode tabel Markdown | + | `plugin-sdk/markdown-table-runtime` | Helper mode tabel markdown | | `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 runtime/sesi ACP dan dispatch balasan | - | `plugin-sdk/acp-binding-resolve-runtime` | Resolusi binding ACP hanya-baca tanpa impor startup siklus hidup | - | `plugin-sdk/agent-config-primitives` | Primitif sempit skema konfigurasi runtime agen | + | `plugin-sdk/acp-binding-resolve-runtime` | Resolusi binding ACP baca-saja tanpa impor startup lifecycle | + | `plugin-sdk/agent-config-primitives` | Primitive sempit skema konfigurasi runtime agen | | `plugin-sdk/boolean-param` | Pembaca parameter boolean longgar | | `plugin-sdk/dangerous-name-runtime` | Helper resolusi pencocokan nama berbahaya | | `plugin-sdk/device-bootstrap` | Helper bootstrap perangkat dan token pairing | - | `plugin-sdk/extension-shared` | Primitif helper bersama passive-channel, status, dan ambient proxy | - | `plugin-sdk/models-provider-runtime` | Helper balasan perintah/provider `/models` | - | `plugin-sdk/skill-commands-runtime` | Helper daftar perintah skill | - | `plugin-sdk/native-command-registry` | Helper registry/build/serialize perintah native | - | `plugin-sdk/agent-harness` | Permukaan Plugin tepercaya eksperimental untuk harness agen tingkat rendah: tipe harness, helper steer/abort run aktif, helper bridge tool OpenClaw, dan utilitas hasil percobaan | - | `plugin-sdk/provider-zai-endpoint` | Helper deteksi endpoint Z.AI | + | `plugin-sdk/extension-shared` | Primitive helper bersama passive-channel, status, dan proxy ambient | + | `plugin-sdk/models-provider-runtime` | Helper balasan perintah `/models`/provider | + | `plugin-sdk/skill-commands-runtime` | Helper daftar perintah Skill | + | `plugin-sdk/native-command-registry` | Helper registri/build/serialize perintah native | + | `plugin-sdk/agent-harness` | Permukaan plugin tepercaya eksperimental untuk harness agen tingkat rendah: tipe harness, helper steer/abort run aktif, helper jembatan alat 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` | Helper grafik error, pemformatan, klasifikasi error bersama, `isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | Helper fetch, proxy, dan pencarian pinned yang dibungkus | - | `plugin-sdk/runtime-fetch` | Fetch runtime yang sadar dispatcher tanpa impor proxy/guarded-fetch | - | `plugin-sdk/response-limit-runtime` | Pembaca body respons terikat tanpa permukaan media runtime yang luas | + | `plugin-sdk/error-runtime` | Helper graph error, pemformatan, klasifikasi error bersama, `isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | Helper wrapped fetch, proxy, dan pinned lookup | + | `plugin-sdk/runtime-fetch` | Runtime fetch sadar-dispatcher tanpa impor proxy/guarded-fetch | + | `plugin-sdk/response-limit-runtime` | Pembaca body respons terbatas tanpa permukaan media runtime yang luas | | `plugin-sdk/session-binding-runtime` | Status binding percakapan saat ini tanpa routing binding terkonfigurasi atau store pairing | | `plugin-sdk/session-store-runtime` | Helper baca session-store tanpa impor penulisan/pemeliharaan konfigurasi yang luas | | `plugin-sdk/context-visibility-runtime` | Resolusi visibilitas konteks dan pemfilteran konteks tambahan tanpa impor konfigurasi/keamanan yang luas | - | `plugin-sdk/string-coerce-runtime` | Helper sempit koersi dan normalisasi record/string primitif tanpa impor Markdown/logging | + | `plugin-sdk/string-coerce-runtime` | Helper sempit record/string coercion dan normalisasi primitive tanpa impor markdown/logging | | `plugin-sdk/host-runtime` | Helper normalisasi hostname dan host SCP | | `plugin-sdk/retry-runtime` | Helper konfigurasi retry dan runner retry | | `plugin-sdk/agent-runtime` | Helper direktori/identitas/workspace agen | @@ -256,65 +256,65 @@ secara eksplisit mempromosikannya sebagai publik. - | Subpath | Key exports | + | Subpath | Ekspor utama | | --- | --- | - | `plugin-sdk/media-runtime` | Helper bersama fetch/transform/store media plus builder payload media | + | `plugin-sdk/media-runtime` | Helper bersama fetch/transform/store media plus pembuat payload media | | `plugin-sdk/media-generation-runtime` | Helper bersama failover generasi media, pemilihan kandidat, dan pesan model yang hilang | - | `plugin-sdk/media-understanding` | Tipe provider pemahaman media plus ekspor helper gambar/audio yang berhadapan dengan provider | - | `plugin-sdk/text-runtime` | Helper bersama teks/Markdown/logging seperti penghapusan teks yang terlihat oleh assistant, helper render/chunking/tabel Markdown, helper redaksi, helper directive-tag, dan utilitas teks aman | - | `plugin-sdk/text-chunking` | Helper chunking teks keluar | - | `plugin-sdk/speech` | Tipe provider speech plus helper directive, registry, dan validasi yang berhadapan dengan provider | - | `plugin-sdk/speech-core` | Helper bersama tipe provider speech, registry, directive, dan normalisasi | - | `plugin-sdk/realtime-transcription` | Tipe provider transkripsi realtime dan helper registry | - | `plugin-sdk/realtime-voice` | Tipe provider voice realtime dan helper registry | + | `plugin-sdk/media-understanding` | Tipe provider pemahaman media plus 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 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` | Helper bersama tipe provider speech, registri, direktif, dan normalisasi | + | `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 generasi gambar | - | `plugin-sdk/image-generation-core` | Helper bersama tipe generasi gambar, failover, auth, dan registry | - | `plugin-sdk/music-generation` | Tipe provider/permintaan/hasil generasi musik | - | `plugin-sdk/music-generation-core` | Helper bersama tipe generasi musik, helper failover, pencarian provider, dan parsing model-ref | - | `plugin-sdk/video-generation` | Tipe provider/permintaan/hasil generasi video | - | `plugin-sdk/video-generation-core` | Helper bersama tipe generasi video, helper failover, pencarian provider, dan parsing model-ref | - | `plugin-sdk/webhook-targets` | Registry target Webhook dan helper pemasangan route | + | `plugin-sdk/image-generation-core` | Helper bersama tipe generasi gambar, failover, auth, dan registri | + | `plugin-sdk/music-generation` | Tipe provider/request/result generasi musik | + | `plugin-sdk/music-generation-core` | Helper bersama tipe generasi musik, helper failover, lookup provider, dan parsing model-ref | + | `plugin-sdk/video-generation` | Tipe provider/request/result generasi video | + | `plugin-sdk/video-generation-core` | Helper bersama tipe generasi video, helper failover, lookup provider, dan parsing model-ref | + | `plugin-sdk/webhook-targets` | Helper registri target Webhook dan instalasi rute | | `plugin-sdk/webhook-path` | Helper normalisasi path Webhook | - | `plugin-sdk/web-media` | Helper bersama pemuatan media jarak jauh/lokal | - | `plugin-sdk/zod` | `zod` yang diekspor ulang untuk konsumen SDK Plugin | + | `plugin-sdk/web-media` | Helper bersama pemuatan media remote/lokal | + | `plugin-sdk/zod` | `zod` yang diekspor ulang untuk konsumen SDK plugin | | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | - - | Subpath | Key exports | + + | Subpath | Ekspor utama | | --- | --- | - | `plugin-sdk/memory-core` | Permukaan helper memory-core bawaan untuk helper manager/konfigurasi/file/CLI | - | `plugin-sdk/memory-core-engine-runtime` | Fasad runtime indeks/pencarian Memory | - | `plugin-sdk/memory-core-host-engine-foundation` | Ekspor engine foundation host Memory | - | `plugin-sdk/memory-core-host-engine-embeddings` | Kontrak embedding host Memory, akses registry, provider lokal, dan helper batch/jarak jauh generik | - | `plugin-sdk/memory-core-host-engine-qmd` | Ekspor engine QMD host Memory | - | `plugin-sdk/memory-core-host-engine-storage` | Ekspor engine storage host Memory | - | `plugin-sdk/memory-core-host-multimodal` | Helper multimodal host Memory | - | `plugin-sdk/memory-core-host-query` | Helper query host Memory | - | `plugin-sdk/memory-core-host-secret` | Helper secret host Memory | - | `plugin-sdk/memory-core-host-events` | Helper jurnal event host Memory | - | `plugin-sdk/memory-core-host-status` | Helper status host Memory | - | `plugin-sdk/memory-core-host-runtime-cli` | Helper runtime CLI host Memory | - | `plugin-sdk/memory-core-host-runtime-core` | Helper runtime inti host Memory | - | `plugin-sdk/memory-core-host-runtime-files` | Helper file/runtime host Memory | - | `plugin-sdk/memory-host-core` | Alias netral-vendor untuk helper runtime inti host Memory | - | `plugin-sdk/memory-host-events` | Alias netral-vendor untuk helper jurnal event host Memory | - | `plugin-sdk/memory-host-files` | Alias netral-vendor untuk helper file/runtime host Memory | - | `plugin-sdk/memory-host-markdown` | Helper managed-markdown bersama untuk Plugin yang berdekatan dengan memory | + | `plugin-sdk/memory-core` | Permukaan helper memory-core bawaan untuk helper manager/config/file/CLI | + | `plugin-sdk/memory-core-engine-runtime` | Fasad runtime indeks/pencarian memory | + | `plugin-sdk/memory-core-host-engine-foundation` | Ekspor engine fondasi host memory | + | `plugin-sdk/memory-core-host-engine-embeddings` | Kontrak embedding host memory, akses registri, provider lokal, dan helper batch/remote generik | + | `plugin-sdk/memory-core-host-engine-qmd` | Ekspor engine QMD host memory | + | `plugin-sdk/memory-core-host-engine-storage` | Ekspor engine penyimpanan host memory | + | `plugin-sdk/memory-core-host-multimodal` | Helper multimodal host memory | + | `plugin-sdk/memory-core-host-query` | Helper kueri host memory | + | `plugin-sdk/memory-core-host-secret` | Helper rahasia host memory | + | `plugin-sdk/memory-core-host-events` | Helper jurnal event host memory | + | `plugin-sdk/memory-core-host-status` | Helper status host memory | + | `plugin-sdk/memory-core-host-runtime-cli` | Helper runtime CLI host memory | + | `plugin-sdk/memory-core-host-runtime-core` | Helper runtime inti host memory | + | `plugin-sdk/memory-core-host-runtime-files` | Helper file/runtime host memory | + | `plugin-sdk/memory-host-core` | Alias netral-vendor untuk helper runtime inti host memory | + | `plugin-sdk/memory-host-events` | Alias netral-vendor untuk helper jurnal event host memory | + | `plugin-sdk/memory-host-files` | Alias netral-vendor untuk helper file/runtime host memory | + | `plugin-sdk/memory-host-markdown` | Helper managed-markdown bersama untuk plugin yang berdekatan dengan memory | | `plugin-sdk/memory-host-search` | Fasad runtime Active Memory untuk akses search-manager | - | `plugin-sdk/memory-host-status` | Alias netral-vendor untuk helper status host Memory | + | `plugin-sdk/memory-host-status` | Alias netral-vendor untuk helper status host memory | | `plugin-sdk/memory-lancedb` | Permukaan helper memory-lancedb bawaan | - | Family | Current subpaths | Intended use | + | Family | Subpath saat ini | Penggunaan yang dimaksudkan | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Helper dukungan Plugin browser bawaan (`browser-support` tetap menjadi barrel kompatibilitas) | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Helper dukungan plugin browser bawaan (`browser-support` tetap menjadi barrel kompatibilitas) | | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Permukaan helper/runtime Matrix bawaan | | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Permukaan helper/runtime LINE bawaan | | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Permukaan helper IRC bawaan | - | Helper khusus channel | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Seam helper/kompatibilitas channel bawaan | - | Helper khusus auth/Plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Seam helper fitur/Plugin bawaan; `plugin-sdk/github-copilot-token` saat ini mengekspor `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken`, dan `resolveCopilotApiToken` | + | 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` | @@ -325,56 +325,65 @@ berikut: ### Pendaftaran kapabilitas -| Method | What it registers | -| ------------------------------------------------ | ------------------------------------- | -| `api.registerProvider(...)` | Inferensi teks (LLM) | +| Method | 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(...)` | Sintesis text-to-speech / STT | -| `api.registerRealtimeTranscriptionProvider(...)` | Transkripsi realtime streaming | -| `api.registerRealtimeVoiceProvider(...)` | Sesi voice realtime dupleks | -| `api.registerMediaUnderstandingProvider(...)` | Analisis gambar/audio/video | -| `api.registerImageGenerationProvider(...)` | Generasi gambar | -| `api.registerMusicGenerationProvider(...)` | Generasi musik | -| `api.registerVideoGenerationProvider(...)` | Generasi video | -| `api.registerWebFetchProvider(...)` | Provider web fetch / scrape | -| `api.registerWebSearchProvider(...)` | Pencarian web | +| `api.registerCliBackend(...)` | Backend inferensi CLI lokal | +| `api.registerChannel(...)` | Channel perpesanan | +| `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(...)` | Generasi gambar | +| `api.registerMusicGenerationProvider(...)` | Generasi musik | +| `api.registerVideoGenerationProvider(...)` | Generasi video | +| `api.registerWebFetchProvider(...)` | Provider web fetch / scrape | +| `api.registerWebSearchProvider(...)` | Pencarian web | -### Tools dan perintah +### Alat dan perintah -| Method | What it registers | -| ------------------------------- | --------------------------------------------- | -| `api.registerTool(tool, opts?)` | Tool agen (wajib atau `{ optional: true }`) | -| `api.registerCommand(def)` | Perintah kustom (melewati LLM) | +| Method | Yang didaftarkan | +| ------------------------------- | ---------------------------------------------- | +| `api.registerTool(tool, opts?)` | Alat agen (wajib atau `{ optional: true }`) | +| `api.registerCommand(def)` | Perintah kustom (melewati LLM) | ### Infrastruktur -| Method | What it registers | -| ---------------------------------------------- | --------------------------------------- | -| `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 memory | -| `api.registerMemoryCorpusSupplement(adapter)` | Korpus pencarian/baca memory 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)` | handler interaktif | +| `api.registerEmbeddedExtensionFactory(factory)` | pabrik extension embedded-runner Pi | +| `api.registerMemoryPromptSupplement(builder)` | Bagian prompt tambahan yang berdekatan dengan memory | +| `api.registerMemoryCorpusSupplement(adapter)` | Korpus pencarian/baca memory tambahan | Namespace admin inti yang dicadangkan (`config.*`, `exec.approvals.*`, `wizard.*`, -`update.*`) selalu tetap `operator.admin`, bahkan jika Plugin mencoba menetapkan -cakupan metode gateway yang lebih sempit. Pilih prefix khusus Plugin untuk -metode milik Plugin. +`update.*`) selalu tetap `operator.admin`, bahkan jika sebuah plugin mencoba menetapkan +cakupan metode gateway yang lebih sempit. Gunakan prefiks khusus plugin untuk +metode milik plugin. + +Gunakan `api.registerEmbeddedExtensionFactory(...)` ketika sebuah plugin memerlukan +timing event native Pi selama proses embedded OpenClaw, misalnya penulisan ulang +`tool_result` async yang harus terjadi sebelum pesan hasil alat akhir dikirim. +Ini adalah seam plugin bawaan saat ini: hanya plugin bawaan yang boleh mendaftarkannya, dan +mereka harus mendeklarasikan `contracts.embeddedExtensionFactories: ["pi"]` dalam +`openclaw.plugin.json`. Tetap gunakan hook plugin OpenClaw biasa untuk semua hal +yang tidak memerlukan seam tingkat lebih rendah tersebut. ### Metadata pendaftaran CLI `api.registerCli(registrar, opts?)` menerima dua jenis metadata tingkat atas: - `commands`: root perintah eksplisit yang dimiliki registrar -- `descriptors`: deskriptor perintah saat parse yang digunakan untuk root help CLI, - routing, dan pendaftaran CLI Plugin lazy +- `descriptors`: deskriptor perintah saat parse yang digunakan untuk bantuan CLI root, + routing, dan pendaftaran CLI plugin lazy -Jika Anda ingin perintah Plugin tetap lazy-loaded pada jalur CLI root normal, +Jika Anda ingin sebuah perintah plugin tetap dimuat secara lazy pada jalur CLI root normal, berikan `descriptors` yang mencakup setiap root perintah tingkat atas yang diekspos oleh registrar tersebut. @@ -388,7 +397,7 @@ api.registerCli( descriptors: [ { name: "matrix", - description: "Manage Matrix accounts, verification, devices, and profile state", + description: "Kelola akun Matrix, verifikasi, perangkat, dan status profil", hasSubcommands: true, }, ], @@ -396,112 +405,112 @@ api.registerCli( ); ``` -Gunakan `commands` saja hanya saat Anda tidak memerlukan pendaftaran CLI root lazy. +Gunakan `commands` saja hanya jika Anda tidak memerlukan pendaftaran CLI root lazy. Jalur kompatibilitas eager tersebut tetap didukung, tetapi tidak memasang -placeholder berbasis descriptor untuk lazy loading saat parse-time. +placeholder berbasis descriptor untuk pemuatan lazy saat parse. ### Pendaftaran backend CLI -`api.registerCliBackend(...)` memungkinkan Plugin memiliki konfigurasi default untuk backend +`api.registerCliBackend(...)` memungkinkan sebuah plugin memiliki konfigurasi 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 penyedia dalam ref model seperti `codex-cli/gpt-5`. - `config` backend menggunakan bentuk yang sama seperti `agents.defaults.cliBackends.`. - Konfigurasi pengguna tetap menang. OpenClaw menggabungkan `agents.defaults.cliBackends.` di atas - default Plugin sebelum menjalankan CLI. -- Gunakan `normalizeConfig` saat backend memerlukan penulisan ulang kompatibilitas setelah merge - (misalnya menormalkan bentuk flag lama). + default plugin sebelum menjalankan CLI. +- Gunakan `normalizeConfig` ketika sebuah backend memerlukan penulisan ulang kompatibilitas setelah penggabungan + (misalnya menormalisasi bentuk flag lama). ### Slot eksklusif -| Method | What it registers | +| Method | Yang didaftarkan | | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `api.registerContextEngine(id, factory)` | Context engine (hanya satu yang aktif pada satu waktu). Callback `assemble()` menerima `availableTools` dan `citationsMode` agar engine dapat menyesuaikan tambahan prompt. | +| `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 memory terpadu | -| `api.registerMemoryPromptSection(builder)` | Builder bagian prompt memory | +| `api.registerMemoryPromptSection(builder)` | Pembuat bagian prompt memory | | `api.registerMemoryFlushPlan(resolver)` | Resolver rencana flush memory | -| `api.registerMemoryRuntime(runtime)` | Adapter runtime memory | +| `api.registerMemoryRuntime(runtime)` | Adapter runtime memory | -### Adapter embedding Memory +### Adapter embedding memory -| Method | What it registers | -| ---------------------------------------------- | ---------------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | Adapter embedding Memory untuk Plugin aktif | +| Method | Yang didaftarkan | +| ---------------------------------------------- | --------------------------------------------- | +| `api.registerMemoryEmbeddingProvider(adapter)` | Adapter embedding memory untuk plugin aktif | -- `registerMemoryCapability` adalah API Plugin memory eksklusif yang disarankan. +- `registerMemoryCapability` adalah API plugin memory eksklusif yang disarankan. - `registerMemoryCapability` juga dapat mengekspos `publicArtifacts.listArtifacts(...)` - sehingga Plugin pendamping dapat menggunakan artefak memory yang diekspor melalui - `openclaw/plugin-sdk/memory-host-core` alih-alih menjangkau layout privat Plugin memory tertentu. + agar plugin pendamping dapat menggunakan artifact memory yang diekspor melalui + `openclaw/plugin-sdk/memory-host-core` alih-alih menjangkau tata letak privat + plugin memory tertentu. - `registerMemoryPromptSection`, `registerMemoryFlushPlan`, dan - `registerMemoryRuntime` adalah API Plugin memory eksklusif yang kompatibel dengan versi lama. -- `registerMemoryEmbeddingProvider` memungkinkan Plugin memory aktif mendaftarkan satu - atau lebih id adapter embedding (misalnya `openai`, `gemini`, atau id yang didefinisikan Plugin kustom). + `registerMemoryRuntime` adalah API plugin memory eksklusif yang kompatibel dengan sistem lama. +- `registerMemoryEmbeddingProvider` memungkinkan plugin memory aktif mendaftarkan satu + atau lebih id adapter embedding (misalnya `openai`, `gemini`, atau id kustom yang ditentukan plugin). - Konfigurasi pengguna seperti `agents.defaults.memorySearch.provider` dan - `agents.defaults.memorySearch.fallback` di-resolve terhadap id adapter - yang terdaftar tersebut. + `agents.defaults.memorySearch.fallback` diresolusikan terhadap id adapter yang terdaftar tersebut. -### Event dan siklus hidup +### Event dan lifecycle -| Method | What it does | -| -------------------------------------------- | ----------------------------- | -| `api.on(hookName, handler, opts?)` | Hook siklus hidup bertipe | -| `api.onConversationBindingResolved(handler)` | Callback binding percakapan | +| Method | Fungsinya | +| -------------------------------------------- | ---------------------------- | +| `api.on(hookName, handler, opts?)` | Hook lifecycle bertipe | +| `api.onConversationBindingResolved(handler)` | Callback pengikatan percakapan | ### Semantik keputusan hook -- `before_tool_call`: mengembalikan `{ block: true }` bersifat terminal. Setelah salah satu handler menetapkannya, handler dengan prioritas lebih rendah dilewati. +- `before_tool_call`: mengembalikan `{ block: true }` bersifat terminal. Setelah ada handler yang menetapkannya, handler dengan prioritas lebih rendah dilewati. - `before_tool_call`: mengembalikan `{ block: false }` diperlakukan sebagai tidak ada keputusan (sama seperti menghilangkan `block`), bukan sebagai override. -- `before_install`: mengembalikan `{ block: true }` bersifat terminal. Setelah salah satu handler menetapkannya, handler dengan prioritas lebih rendah dilewati. +- `before_install`: mengembalikan `{ block: true }` bersifat terminal. Setelah ada handler yang menetapkannya, handler dengan prioritas lebih rendah dilewati. - `before_install`: mengembalikan `{ block: false }` diperlakukan sebagai tidak ada keputusan (sama seperti menghilangkan `block`), bukan sebagai override. -- `reply_dispatch`: mengembalikan `{ handled: true, ... }` bersifat terminal. Setelah salah satu handler mengklaim dispatch, handler dengan prioritas lebih rendah dan jalur dispatch model default dilewati. -- `message_sending`: mengembalikan `{ cancel: true }` bersifat terminal. Setelah salah satu handler menetapkannya, handler dengan prioritas lebih rendah dilewati. +- `reply_dispatch`: mengembalikan `{ handled: true, ... }` bersifat terminal. Setelah ada handler yang mengklaim dispatch, handler dengan prioritas lebih rendah dan jalur dispatch model default akan dilewati. +- `message_sending`: mengembalikan `{ cancel: true }` bersifat terminal. Setelah ada handler yang menetapkannya, handler dengan prioritas lebih rendah dilewati. - `message_sending`: mengembalikan `{ cancel: false }` diperlakukan sebagai tidak ada keputusan (sama seperti menghilangkan `cancel`), bukan sebagai override. ### Field objek API -| Field | Type | Description | -| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | -| `api.id` | `string` | ID Plugin | +| Field | Type | Deskripsi | +| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------ | +| `api.id` | `string` | id Plugin | | `api.name` | `string` | Nama tampilan | -| `api.version` | `string?` | Versi Plugin (opsional) | -| `api.description` | `string?` | Deskripsi Plugin (opsional) | +| `api.version` | `string?` | Versi Plugin (opsional) | +| `api.description` | `string?` | Deskripsi Plugin (opsional) | | `api.source` | `string` | Path sumber Plugin | | `api.rootDir` | `string?` | Direktori root Plugin (opsional) | -| `api.config` | `OpenClawConfig` | Snapshot konfigurasi saat ini (snapshot runtime in-memory aktif saat tersedia) | -| `api.pluginConfig` | `Record` | Konfigurasi khusus Plugin dari `plugins.entries..config` | -| `api.runtime` | `PluginRuntime` | [Runtime helpers](/id/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | Logger yang dicakup (`debug`, `info`, `warn`, `error`) | -| `api.registrationMode` | `PluginRegistrationMode` | Mode muat saat ini; `"setup-runtime"` adalah jendela startup/setup ringan sebelum entri penuh | -| `api.resolvePath(input)` | `(string) => string` | Resolve path relatif terhadap root Plugin | +| `api.config` | `OpenClawConfig` | Snapshot konfigurasi saat ini (snapshot runtime dalam memori yang aktif bila tersedia) | +| `api.pluginConfig` | `Record` | Konfigurasi khusus plugin dari `plugins.entries..config` | +| `api.runtime` | `PluginRuntime` | [Helper runtime](/id/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | Logger terlingkup (`debug`, `info`, `warn`, `error`) | +| `api.registrationMode` | `PluginRegistrationMode` | Mode pemuatan saat ini; `"setup-runtime"` adalah jendela startup/setup ringan sebelum entri penuh | +| `api.resolvePath(input)` | `(string) => string` | Meresolusikan path relatif terhadap root plugin | ## Konvensi modul internal -Di dalam Plugin Anda, gunakan file barrel lokal untuk impor internal: +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 # Titik entri Plugin - setup-entry.ts # Entri setup-only ringan (opsional) + runtime-api.ts # Ekspor runtime hanya-internal + index.ts # Titik masuk plugin + setup-entry.ts # Entri ringan hanya-setup (opsional) ``` - Jangan pernah mengimpor Plugin Anda sendiri melalui `openclaw/plugin-sdk/` + Jangan pernah mengimpor plugin Anda sendiri melalui `openclaw/plugin-sdk/` dari kode produksi. Arahkan impor internal melalui `./api.ts` atau - `./runtime-api.ts`. Path SDK hanya kontrak eksternal. + `./runtime-api.ts`. Path SDK hanyalah 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 konfigurasi runtime aktif saat OpenClaw sudah berjalan. Jika snapshot -runtime belum ada, permukaan tersebut menggunakan fallback ke file konfigurasi yang telah di-resolve di disk. +Permukaan publik plugin bawaan yang dimuat melalui facade (`api.ts`, `runtime-api.ts`, +`index.ts`, `setup-entry.ts`, dan file entri publik serupa) kini mengutamakan +snapshot konfigurasi runtime aktif ketika OpenClaw sudah berjalan. Jika belum ada +snapshot runtime, permukaan tersebut akan fallback ke file konfigurasi yang telah diresolusikan di disk. -Plugin provider juga dapat mengekspos barrel kontrak lokal Plugin yang sempit saat -helper memang khusus provider dan belum layak berada di subpath SDK generik. +Plugin provider juga dapat mengekspos barrel kontrak lokal-plugin yang sempit ketika sebuah +helper memang khusus provider dan belum layak ditempatkan di subpath SDK generik. Contoh bawaan saat ini: provider Anthropic menyimpan helper stream Claude di seam publik `api.ts` / `contract-api.ts` miliknya sendiri alih-alih -mempromosikan logika beta-header Anthropic dan `service_tier` ke kontrak +menaikkan logika header beta Anthropic dan `service_tier` ke kontrak `plugin-sdk/*` generik. Contoh bawaan saat ini lainnya: @@ -512,17 +521,17 @@ Contoh bawaan saat ini lainnya: helper onboarding/konfigurasi - Kode produksi ekstensi juga harus menghindari impor `openclaw/plugin-sdk/`. - Jika helper benar-benar dibagikan, promosikan ke subpath SDK netral - seperti `openclaw/plugin-sdk/speech`, `.../provider-model-shared`, atau permukaan - lain yang berorientasi kapabilitas alih-alih mengikat dua Plugin bersama. + Kode produksi extension juga sebaiknya menghindari impor `openclaw/plugin-sdk/`. + Jika sebuah helper benar-benar dipakai bersama, naikkan helper tersebut ke subpath SDK netral + seperti `openclaw/plugin-sdk/speech`, `.../provider-model-shared`, atau permukaan lain + yang berorientasi pada 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 lengkap `api.runtime` -- [Setup and Config](/id/plugins/sdk-setup) — packaging, manifest, skema konfigurasi +- [Runtime Helpers](/id/plugins/sdk-runtime) — referensi namespace `api.runtime` lengkap +- [Setup and Config](/id/plugins/sdk-setup) — packaging, manifes, skema konfigurasi - [Testing](/id/plugins/sdk-testing) — utilitas pengujian dan aturan lint -- [SDK Migration](/id/plugins/sdk-migration) — migrasi dari permukaan yang deprecated +- [SDK Migration](/id/plugins/sdk-migration) — migrasi dari permukaan yang sudah deprecated - [Plugin Internals](/id/plugins/architecture) — arsitektur mendalam dan model kapabilitas diff --git a/docs/id/providers/ollama.md b/docs/id/providers/ollama.md index f93e1306b..d9c8573fd 100644 --- a/docs/id/providers/ollama.md +++ b/docs/id/providers/ollama.md @@ -1,34 +1,34 @@ --- read_when: - - Anda ingin menjalankan OpenClaw dengan model cloud atau lokal melalui Ollama + - Anda ingin menjalankan OpenClaw dengan model cloud atau local melalui Ollama - Anda memerlukan panduan penyiapan dan konfigurasi Ollama - Anda ingin model vision Ollama untuk pemahaman gambar -summary: Jalankan OpenClaw dengan Ollama (model cloud dan lokal) +summary: Jalankan OpenClaw dengan Ollama (model cloud dan local) title: Ollama x-i18n: - generated_at: "2026-04-22T04:26:03Z" + generated_at: "2026-04-22T09:15:25Z" model: gpt-5.4 provider: openai - source_hash: 32623b6523f22930a5987fb22d2074f1e9bb274cc01ae1ad1837825cc04ec179 + source_hash: 704beed3bf988d6c2ad50b2a1533f6dcef655e44b34f23104827d2acb71b8655 source_path: providers/ollama.md workflow: 15 --- # Ollama -OpenClaw terintegrasi dengan API native Ollama (`/api/chat`) untuk model cloud yang di-host dan server Ollama lokal/self-hosted. Anda dapat menggunakan Ollama dalam tiga mode: `Cloud + Local` melalui host Ollama yang dapat dijangkau, `Cloud only` terhadap `https://ollama.com`, atau `Local only` terhadap host Ollama yang dapat dijangkau. +OpenClaw terintegrasi dengan API native Ollama (`/api/chat`) untuk model cloud terhosting dan server Ollama local/self-hosted. Anda dapat menggunakan Ollama dalam tiga mode: `Cloud + Local` melalui host Ollama yang dapat dijangkau, `Cloud only` terhadap `https://ollama.com`, atau `Local only` terhadap host Ollama yang dapat dijangkau. -**Pengguna Ollama jarak jauh**: Jangan gunakan URL kompatibel OpenAI `/v1` (`http://host:11434/v1`) dengan OpenClaw. Ini merusak tool calling dan model dapat mengeluarkan JSON alat mentah sebagai teks biasa. Gunakan URL API native Ollama sebagai gantinya: `baseUrl: "http://host:11434"` (tanpa `/v1`). +**Pengguna Ollama jarak jauh**: Jangan gunakan URL kompatibel OpenAI `/v1` (`http://host:11434/v1`) dengan OpenClaw. Ini merusak pemanggilan tool dan model dapat mengeluarkan JSON tool mentah sebagai teks biasa. Gunakan URL API native Ollama sebagai gantinya: `baseUrl: "http://host:11434"` (tanpa `/v1`). ## Memulai -Pilih metode penyiapan dan mode yang Anda sukai. +Pilih metode penyiapan dan mode yang Anda inginkan. - - **Terbaik untuk:** jalur tercepat menuju penyiapan Ollama cloud atau lokal yang berfungsi. + + **Terbaik untuk:** jalur tercepat menuju penyiapan Ollama cloud atau local yang berfungsi. @@ -36,15 +36,15 @@ Pilih metode penyiapan dan mode yang Anda sukai. openclaw onboard ``` - Pilih **Ollama** dari daftar penyedia. + Pilih **Ollama** dari daftar provider. - - **Cloud + Local** — host Ollama lokal plus model cloud yang dirutekan melalui host tersebut - - **Cloud only** — model Ollama yang di-host melalui `https://ollama.com` - - **Local only** — hanya model lokal + - **Cloud + Local** — host Ollama local plus model cloud yang dirutekan melalui host tersebut + - **Cloud only** — model Ollama terhosting melalui `https://ollama.com` + - **Local only** — hanya model local - `Cloud only` meminta `OLLAMA_API_KEY` dan menyarankan default cloud yang di-host. `Cloud + Local` dan `Local only` meminta base URL Ollama, menemukan model yang tersedia, dan otomatis menarik model lokal yang dipilih jika belum tersedia. `Cloud + Local` juga memeriksa apakah host Ollama tersebut sudah sign in untuk akses cloud. + `Cloud only` meminta `OLLAMA_API_KEY` dan menyarankan default cloud terhosting. `Cloud + Local` dan `Local only` meminta base URL Ollama, menemukan model yang tersedia, dan otomatis menarik model local yang dipilih jika belum tersedia. `Cloud + Local` juga memeriksa apakah host Ollama tersebut sudah sign in untuk akses cloud. ```bash @@ -74,15 +74,15 @@ Pilih metode penyiapan dan mode yang Anda sukai. - **Terbaik untuk:** kontrol penuh atas penyiapan cloud atau lokal. + **Terbaik untuk:** kontrol penuh atas penyiapan cloud atau local. - - - **Cloud + Local**: pasang Ollama, lakukan sign in dengan `ollama signin`, dan rutekan permintaan cloud melalui host tersebut + + - **Cloud + Local**: instal Ollama, sign in dengan `ollama signin`, dan rutekan permintaan cloud melalui host tersebut - **Cloud only**: gunakan `https://ollama.com` dengan `OLLAMA_API_KEY` - - **Local only**: pasang Ollama dari [ollama.com/download](https://ollama.com/download) + - **Local only**: instal Ollama dari [ollama.com/download](https://ollama.com/download) - + ```bash ollama pull gemma4 # atau @@ -92,16 +92,16 @@ Pilih metode penyiapan dan mode yang Anda sukai. ``` - Untuk `Cloud only`, gunakan `OLLAMA_API_KEY` asli Anda. Untuk penyiapan berbasis host, nilai placeholder apa pun dapat digunakan: + Untuk `Cloud only`, gunakan `OLLAMA_API_KEY` Anda yang sebenarnya. Untuk penyiapan berbasis host, nilai placeholder apa pun dapat digunakan: ```bash # Cloud export OLLAMA_API_KEY="your-ollama-api-key" - # Hanya lokal + # Khusus local export OLLAMA_API_KEY="ollama-local" - # Atau konfigurasikan di file config Anda + # Atau konfigurasi di file config Anda openclaw config set models.providers.ollama.apiKey "OLLAMA_API_KEY" ``` @@ -132,48 +132,48 @@ Pilih metode penyiapan dan mode yang Anda sukai. - `Cloud + Local` menggunakan host Ollama yang dapat dijangkau sebagai titik kontrol untuk model lokal dan cloud. Ini adalah alur hibrida yang disukai Ollama. + `Cloud + Local` menggunakan host Ollama yang dapat dijangkau sebagai titik kontrol untuk model local dan cloud. Ini adalah alur hibrida pilihan Ollama. - Gunakan **Cloud + Local** selama penyiapan. OpenClaw meminta base URL Ollama, menemukan model lokal dari host tersebut, dan memeriksa apakah host sudah sign in untuk akses cloud dengan `ollama signin`. Saat host sudah sign in, OpenClaw juga menyarankan default cloud yang di-host seperti `kimi-k2.5:cloud`, `minimax-m2.7:cloud`, dan `glm-5.1:cloud`. + Gunakan **Cloud + Local** selama penyiapan. OpenClaw meminta base URL Ollama, menemukan model local dari host tersebut, dan memeriksa apakah host sudah sign in untuk akses cloud dengan `ollama signin`. Saat host sudah sign in, OpenClaw juga menyarankan default cloud terhosting seperti `kimi-k2.5:cloud`, `minimax-m2.7:cloud`, dan `glm-5.1:cloud`. - Jika host belum sign in, OpenClaw mempertahankan penyiapan hanya-lokal sampai Anda menjalankan `ollama signin`. + Jika host belum sign in, OpenClaw mempertahankan penyiapan tetap khusus local sampai Anda menjalankan `ollama signin`. - `Cloud only` berjalan terhadap API yang di-host Ollama di `https://ollama.com`. + `Cloud only` berjalan terhadap API terhosting Ollama di `https://ollama.com`. - Gunakan **Cloud only** selama penyiapan. OpenClaw meminta `OLLAMA_API_KEY`, menetapkan `baseUrl: "https://ollama.com"`, dan mengisi daftar model cloud yang di-host. Jalur ini **tidak** memerlukan server Ollama lokal atau `ollama signin`. + Gunakan **Cloud only** selama penyiapan. OpenClaw meminta `OLLAMA_API_KEY`, menyetel `baseUrl: "https://ollama.com"`, dan mengisi daftar model cloud terhosting. Jalur ini **tidak** memerlukan server Ollama local atau `ollama signin`. - Daftar model cloud yang ditampilkan selama `openclaw onboard` diisi secara live dari `https://ollama.com/api/tags`, dibatasi hingga 500 entri, sehingga pemilih mencerminkan katalog yang di-host saat ini alih-alih seed statis. Jika `ollama.com` tidak dapat dijangkau atau tidak mengembalikan model pada saat penyiapan, OpenClaw menggunakan fallback ke saran hardcoded sebelumnya agar onboarding tetap selesai. + Daftar model cloud yang ditampilkan selama `openclaw onboard` diisi secara live dari `https://ollama.com/api/tags`, dibatasi hingga 500 entri, sehingga pemilih mencerminkan katalog terhosting saat ini alih-alih seed statis. Jika `ollama.com` tidak dapat dijangkau atau tidak mengembalikan model saat penyiapan, OpenClaw akan kembali ke saran hardcoded sebelumnya agar onboarding tetap selesai. - Dalam mode hanya-lokal, OpenClaw menemukan model dari instance Ollama yang dikonfigurasi. Jalur ini ditujukan untuk server Ollama lokal atau self-hosted. + Dalam mode khusus local, OpenClaw menemukan model dari instance Ollama yang dikonfigurasi. Jalur ini ditujukan untuk server Ollama local atau self-hosted. - OpenClaw saat ini menyarankan `gemma4` sebagai default lokal. + OpenClaw saat ini menyarankan `gemma4` sebagai default local. -## Penemuan model (penyedia implisit) +## Penemuan model (provider implisit) -Saat Anda menetapkan `OLLAMA_API_KEY` (atau profil auth) dan **tidak** mendefinisikan `models.providers.ollama`, OpenClaw menemukan model dari instance Ollama lokal di `http://127.0.0.1:11434`. +Saat Anda menyetel `OLLAMA_API_KEY` (atau auth profile) dan **tidak** mendefinisikan `models.providers.ollama`, OpenClaw menemukan model dari instance Ollama local di `http://127.0.0.1:11434`. -| Perilaku | Detail | -| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Query katalog | Men-query `/api/tags` | -| Deteksi kapabilitas | Menggunakan lookup `/api/show` best-effort untuk membaca `contextWindow` dan mendeteksi kapabilitas (termasuk vision) | -| Model vision | Model dengan kapabilitas `vision` yang dilaporkan oleh `/api/show` ditandai sebagai mampu gambar (`input: ["text", "image"]`), sehingga OpenClaw otomatis menyuntikkan gambar ke prompt | -| Deteksi reasoning | Menandai `reasoning` dengan heuristik nama model (`r1`, `reasoning`, `think`) | -| Batas token | Menetapkan `maxTokens` ke batas max-token Ollama default yang digunakan oleh OpenClaw | -| Biaya | Menetapkan semua biaya ke `0` | +| Perilaku | Detail | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Kueri katalog | Mengueri `/api/tags` | +| Deteksi kemampuan | Menggunakan lookup `/api/show` best-effort untuk membaca `contextWindow` dan mendeteksi kemampuan (termasuk vision) | +| Model vision | Model dengan kemampuan `vision` yang dilaporkan oleh `/api/show` ditandai sebagai mampu-gambar (`input: ["text", "image"]`), sehingga OpenClaw otomatis menyuntikkan gambar ke prompt | +| Deteksi reasoning | Menandai `reasoning` dengan heuristik nama model (`r1`, `reasoning`, `think`) | +| Batas token | Menyetel `maxTokens` ke batas maksimum token default Ollama yang digunakan oleh OpenClaw | +| Biaya | Menyetel semua biaya ke `0` | -Ini menghindari entri model manual sambil menjaga katalog tetap selaras dengan instance Ollama lokal. +Ini menghindari entri model manual sambil menjaga katalog tetap selaras dengan instance Ollama local. ```bash -# Lihat model apa saja yang tersedia +# Lihat model yang tersedia ollama list openclaw models list ``` @@ -184,17 +184,17 @@ Untuk menambahkan model baru, cukup tarik dengan Ollama: ollama pull mistral ``` -Model baru akan otomatis ditemukan dan tersedia untuk digunakan. +Model baru tersebut akan ditemukan secara otomatis dan tersedia untuk digunakan. -Jika Anda menetapkan `models.providers.ollama` secara eksplisit, penemuan otomatis dilewati dan Anda harus mendefinisikan model secara manual. Lihat bagian config eksplisit di bawah. +Jika Anda menyetel `models.providers.ollama` secara eksplisit, penemuan otomatis dilewati dan Anda harus mendefinisikan model secara manual. Lihat bagian konfigurasi eksplisit di bawah. ## Vision dan deskripsi gambar -Plugin Ollama bawaan mendaftarkan Ollama sebagai penyedia media-understanding yang mampu menangani gambar. Ini memungkinkan OpenClaw merutekan permintaan deskripsi gambar eksplisit dan default model gambar yang dikonfigurasi melalui model vision Ollama lokal atau yang di-host. +Plugin Ollama bawaan mendaftarkan Ollama sebagai provider pemahaman media yang mendukung gambar. Ini memungkinkan OpenClaw merutekan permintaan deskripsi gambar eksplisit dan default model gambar yang dikonfigurasi melalui model vision Ollama local atau terhosting. -Untuk vision lokal, tarik model yang mendukung gambar: +Untuk vision local, tarik model yang mendukung gambar: ```bash ollama pull qwen2.5vl:7b @@ -210,9 +210,9 @@ openclaw infer image describe \ --json ``` -`--model` harus berupa referensi penuh ``. Saat disetel, `openclaw infer image describe` menjalankan model itu secara langsung alih-alih melewati deskripsi karena model mendukung vision native. +`--model` harus berupa ref lengkap ``. Saat disetel, `openclaw infer image describe` menjalankan model tersebut secara langsung alih-alih melewati deskripsi karena model mendukung vision native. -Untuk menjadikan Ollama sebagai model image-understanding default untuk media masuk, konfigurasikan `agents.defaults.imageModel`: +Untuk menjadikan Ollama sebagai model default pemahaman gambar untuk media masuk, konfigurasi `agents.defaults.imageModel`: ```json5 { @@ -238,26 +238,26 @@ Jika Anda mendefinisikan `models.providers.ollama.models` secara manual, tandai } ``` -OpenClaw menolak permintaan deskripsi gambar untuk model yang tidak ditandai mampu gambar. Dengan penemuan implisit, OpenClaw membaca ini dari Ollama saat `/api/show` melaporkan kapabilitas vision. +OpenClaw menolak permintaan deskripsi gambar untuk model yang tidak ditandai mendukung gambar. Dengan penemuan implisit, OpenClaw membaca ini dari Ollama saat `/api/show` melaporkan kemampuan vision. ## Konfigurasi - Jalur aktivasi paling sederhana untuk hanya-lokal adalah melalui variabel environment: + Jalur pengaktifan khusus local yang paling sederhana adalah melalui variabel lingkungan: ```bash export OLLAMA_API_KEY="ollama-local" ``` - Jika `OLLAMA_API_KEY` disetel, Anda dapat menghilangkan `apiKey` di entri penyedia dan OpenClaw akan mengisinya untuk pemeriksaan ketersediaan. + Jika `OLLAMA_API_KEY` disetel, Anda dapat menghilangkan `apiKey` di entri provider dan OpenClaw akan mengisinya untuk pemeriksaan ketersediaan. - Gunakan config eksplisit saat Anda menginginkan penyiapan cloud yang di-host, Ollama berjalan di host/port lain, Anda ingin memaksa context window atau daftar model tertentu, atau Anda ingin definisi model sepenuhnya manual. + Gunakan konfigurasi eksplisit saat Anda menginginkan penyiapan cloud terhosting, Ollama berjalan di host/port lain, Anda ingin memaksakan context window atau daftar model tertentu, atau Anda ingin definisi model yang sepenuhnya manual. ```json5 { @@ -287,7 +287,7 @@ OpenClaw menolak permintaan deskripsi gambar untuk model yang tidak ditandai mam - Jika Ollama berjalan di host atau port yang berbeda (config eksplisit menonaktifkan penemuan otomatis, jadi definisikan model secara manual): + Jika Ollama berjalan di host atau port yang berbeda (konfigurasi eksplisit menonaktifkan penemuan otomatis, jadi definisikan model secara manual): ```json5 { @@ -296,7 +296,7 @@ OpenClaw menolak permintaan deskripsi gambar untuk model yang tidak ditandai mam ollama: { apiKey: "ollama-local", baseUrl: "http://ollama-host:11434", // Tanpa /v1 - gunakan URL API native Ollama - api: "ollama", // Setel secara eksplisit untuk menjamin perilaku tool-calling native + api: "ollama", // Setel secara eksplisit untuk menjamin perilaku pemanggilan tool native }, }, }, @@ -304,7 +304,7 @@ OpenClaw menolak permintaan deskripsi gambar untuk model yang tidak ditandai mam ``` - Jangan tambahkan `/v1` ke URL. Path `/v1` menggunakan mode yang kompatibel dengan OpenAI, di mana tool calling tidak andal. Gunakan base URL Ollama tanpa suffix path. + Jangan tambahkan `/v1` ke URL. Jalur `/v1` menggunakan mode kompatibel OpenAI, di mana pemanggilan tool tidak andal. Gunakan base URL Ollama tanpa sufiks path. @@ -329,15 +329,15 @@ Setelah dikonfigurasi, semua model Ollama Anda tersedia: ## Ollama Web Search -OpenClaw mendukung **Ollama Web Search** sebagai penyedia `web_search` bawaan. +OpenClaw mendukung **Ollama Web Search** sebagai provider `web_search` bawaan. -| Properti | Detail | -| ----------- | ------------------------------------------------------------------------------------------------------------------- | +| Properti | Detail | +| ----------- | ---------------------------------------------------------------------------------------------------------------------- | | Host | Menggunakan host Ollama yang dikonfigurasi (`models.providers.ollama.baseUrl` jika disetel, jika tidak `http://127.0.0.1:11434`) | -| Auth | Tanpa key | -| Persyaratan | Ollama harus berjalan dan sudah sign in dengan `ollama signin` | +| Auth | Tanpa kunci | +| Persyaratan | Ollama harus berjalan dan sudah sign in dengan `ollama signin` | -Pilih **Ollama Web Search** saat `openclaw onboard` atau `openclaw configure --section web`, atau setel: +Pilih **Ollama Web Search** selama `openclaw onboard` atau `openclaw configure --section web`, atau setel: ```json5 { @@ -360,10 +360,10 @@ Untuk detail penyiapan dan perilaku lengkap, lihat [Ollama Web Search](/id/tools - **Tool calling tidak andal dalam mode kompatibel OpenAI.** Gunakan mode ini hanya jika Anda memerlukan format OpenAI untuk proxy dan tidak bergantung pada perilaku tool calling native. + **Pemanggilan tool tidak andal dalam mode kompatibel OpenAI.** Gunakan mode ini hanya jika Anda memerlukan format OpenAI untuk proxy dan tidak bergantung pada perilaku pemanggilan tool native. - Jika Anda perlu menggunakan endpoint yang kompatibel dengan OpenAI sebagai gantinya (misalnya di balik proxy yang hanya mendukung format OpenAI), setel `api: "openai-completions"` secara eksplisit: + Jika Anda perlu menggunakan endpoint kompatibel OpenAI sebagai gantinya (misalnya, di balik proxy yang hanya mendukung format OpenAI), setel `api: "openai-completions"` secara eksplisit: ```json5 { @@ -381,9 +381,9 @@ Untuk detail penyiapan dan perilaku lengkap, lihat [Ollama Web Search](/id/tools } ``` - Mode ini mungkin tidak mendukung streaming dan tool calling secara bersamaan. Anda mungkin perlu menonaktifkan streaming dengan `params: { streaming: false }` di config model. + Mode ini mungkin tidak mendukung streaming dan pemanggilan tool secara bersamaan. Anda mungkin perlu menonaktifkan streaming dengan `params: { streaming: false }` di konfigurasi model. - Saat `api: "openai-completions"` digunakan dengan Ollama, OpenClaw secara default menyuntikkan `options.num_ctx` agar Ollama tidak diam-diam kembali ke context window 4096. Jika proxy/upstream Anda menolak field `options` yang tidak dikenal, nonaktifkan perilaku ini: + Saat `api: "openai-completions"` digunakan dengan Ollama, OpenClaw secara default menyuntikkan `options.num_ctx` agar Ollama tidak diam-diam fallback ke context window 4096. Jika proxy/upstream Anda menolak field `options` yang tidak dikenal, nonaktifkan perilaku ini: ```json5 { @@ -404,9 +404,9 @@ Untuk detail penyiapan dan perilaku lengkap, lihat [Ollama Web Search](/id/tools - Untuk model yang ditemukan otomatis, OpenClaw menggunakan context window yang dilaporkan oleh Ollama saat tersedia, jika tidak maka kembali ke context window default Ollama yang digunakan oleh OpenClaw. + Untuk model yang ditemukan otomatis, OpenClaw menggunakan context window yang dilaporkan oleh Ollama jika tersedia, jika tidak maka fallback ke context window default Ollama yang digunakan oleh OpenClaw. - Anda dapat mengoverride `contextWindow` dan `maxTokens` di config penyedia eksplisit: + Anda dapat mengoverride `contextWindow` dan `maxTokens` di konfigurasi provider eksplisit: ```json5 { @@ -429,7 +429,7 @@ Untuk detail penyiapan dan perilaku lengkap, lihat [Ollama Web Search](/id/tools - OpenClaw memperlakukan model dengan nama seperti `deepseek-r1`, `reasoning`, atau `think` sebagai model yang mampu reasoning secara default. + OpenClaw memperlakukan model dengan nama seperti `deepseek-r1`, `reasoning`, atau `think` sebagai model yang mendukung reasoning secara default. ```bash ollama pull deepseek-r1:32b @@ -440,20 +440,20 @@ Untuk detail penyiapan dan perilaku lengkap, lihat [Ollama Web Search](/id/tools - Ollama gratis dan berjalan secara lokal, sehingga semua biaya model disetel ke $0. Ini berlaku baik untuk model yang ditemukan otomatis maupun yang didefinisikan secara manual. + Ollama gratis dan berjalan secara local, jadi semua biaya model disetel ke $0. Ini berlaku untuk model yang ditemukan otomatis maupun yang didefinisikan secara manual. - Plugin Ollama bawaan mendaftarkan penyedia embedding memori untuk - [pencarian memori](/id/concepts/memory). Ini menggunakan base URL Ollama + Plugin Ollama bawaan mendaftarkan provider embedding memori untuk + [pencarian memori](/id/concepts/memory). Provider ini menggunakan base URL Ollama dan API key yang dikonfigurasi. - | Properti | Nilai | - | ------------- | ------------------ | - | Model default | `nomic-embed-text` | - | Auto-pull | Ya — model embedding akan ditarik secara otomatis jika belum ada secara lokal | + | Properti | Nilai | + | ------------- | -------------------- | + | Model default | `nomic-embed-text` | + | Auto-pull | Ya — model embedding ditarik secara otomatis jika belum tersedia secara local | - Untuk memilih Ollama sebagai penyedia embedding pencarian memori: + Untuk memilih Ollama sebagai provider embedding pencarian memori: ```json5 { @@ -468,10 +468,12 @@ Untuk detail penyiapan dan perilaku lengkap, lihat [Ollama Web Search](/id/tools - Integrasi Ollama OpenClaw menggunakan **API native Ollama** (`/api/chat`) secara default, yang sepenuhnya mendukung streaming dan tool calling secara bersamaan. Tidak diperlukan konfigurasi khusus. + Integrasi Ollama OpenClaw menggunakan **API native Ollama** (`/api/chat`) secara default, yang sepenuhnya mendukung streaming dan pemanggilan tool secara bersamaan. Tidak diperlukan konfigurasi khusus. + + Untuk permintaan `/api/chat` native, OpenClaw juga meneruskan kontrol thinking langsung ke Ollama: `/think off` dan `openclaw agent --thinking off` mengirim `think: false` tingkat atas, sedangkan level thinking selain `off` mengirim `think: true`. - Jika Anda perlu menggunakan endpoint yang kompatibel dengan OpenAI, lihat bagian "Mode kompatibel OpenAI lama" di atas. Streaming dan tool calling mungkin tidak berfungsi secara bersamaan dalam mode tersebut. + Jika Anda perlu menggunakan endpoint kompatibel OpenAI, lihat bagian "Mode kompatibel OpenAI lama" di atas. Streaming dan pemanggilan tool mungkin tidak berfungsi secara bersamaan dalam mode tersebut. @@ -481,7 +483,7 @@ Untuk detail penyiapan dan perilaku lengkap, lihat [Ollama Web Search](/id/tools - Pastikan Ollama berjalan dan Anda telah menetapkan `OLLAMA_API_KEY` (atau profil auth), serta Anda **tidak** mendefinisikan entri `models.providers.ollama` eksplisit: + Pastikan Ollama sedang berjalan dan Anda telah menyetel `OLLAMA_API_KEY` (atau auth profile), dan Anda **tidak** mendefinisikan entri `models.providers.ollama` eksplisit: ```bash ollama serve @@ -496,10 +498,10 @@ Untuk detail penyiapan dan perilaku lengkap, lihat [Ollama Web Search](/id/tools - Jika model Anda tidak terdaftar, tarik model tersebut secara lokal atau definisikan secara eksplisit di `models.providers.ollama`. + Jika model Anda tidak tercantum, tarik model tersebut secara local atau definisikan secara eksplisit di `models.providers.ollama`. ```bash - ollama list # Lihat apa yang sudah terpasang + ollama list # Lihat yang terinstal ollama pull gemma4 ollama pull gpt-oss:20b ollama pull llama3.3 # Atau model lain @@ -511,10 +513,10 @@ Untuk detail penyiapan dan perilaku lengkap, lihat [Ollama Web Search](/id/tools Periksa bahwa Ollama berjalan pada port yang benar: ```bash - # Periksa apakah Ollama berjalan + # Periksa apakah Ollama sedang berjalan ps aux | grep ollama - # Atau mulai ulang Ollama + # Atau restart Ollama ollama serve ``` @@ -522,22 +524,22 @@ Untuk detail penyiapan dan perilaku lengkap, lihat [Ollama Web Search](/id/tools -Bantuan lebih lanjut: [Pemecahan masalah](/id/help/troubleshooting) dan [FAQ](/id/help/faq). +Bantuan lebih lanjut: [Pemecahan Masalah](/id/help/troubleshooting) dan [FAQ](/id/help/faq). ## Terkait - - Gambaran umum semua penyedia, referensi model, dan perilaku failover. + + Ringkasan semua provider, ref model, dan perilaku failover. Cara memilih dan mengonfigurasi model. - Detail penyiapan dan perilaku lengkap untuk pencarian web yang didukung Ollama. + Detail penyiapan dan perilaku lengkap untuk pencarian web berbasis Ollama. - Referensi config lengkap. + Referensi konfigurasi lengkap. diff --git a/docs/id/providers/tencent.md b/docs/id/providers/tencent.md new file mode 100644 index 000000000..a1f407b9b --- /dev/null +++ b/docs/id/providers/tencent.md @@ -0,0 +1,67 @@ +--- +read_when: + - Anda ingin menggunakan model Tencent Hy dengan OpenClaw + - Anda memerlukan penyiapan kunci API TokenHub +summary: Penyiapan Tencent Cloud TokenHub +title: Tencent Cloud (TokenHub) +x-i18n: + generated_at: "2026-04-22T09:15:26Z" + model: gpt-5.4 + provider: openai + source_hash: 04da073973792c55dc0c2d287bfc51187bb2128bbbd5c4a483f850adeea50ab5 + source_path: providers/tencent.md + workflow: 15 +--- + +# Tencent Cloud (TokenHub) + +Provider Tencent Cloud memberikan akses ke model Tencent Hy melalui endpoint TokenHub +(`tencent-tokenhub`). + +Provider ini menggunakan API yang kompatibel dengan OpenAI. + +## Mulai cepat + +```bash +openclaw onboard --auth-choice tokenhub-api-key +``` + +## Contoh non-interaktif + +```bash +openclaw onboard --non-interactive \ + --mode local \ + --auth-choice tokenhub-api-key \ + --tokenhub-api-key "$TOKENHUB_API_KEY" \ + --skip-health \ + --accept-risk +``` + +## Provider dan endpoint + +| Provider | Endpoint | Kasus penggunaan | +| ------------------ | ----------------------------- | ----------------------- | +| `tencent-tokenhub` | `tokenhub.tencentmaas.com/v1` | Hy melalui Tencent TokenHub | + +## Model yang tersedia + +### tencent-tokenhub + +- **hy3-preview** — Pratinjau Hy3 (konteks 256K, penalaran, default) + +## Catatan + +- Referensi model TokenHub menggunakan `tencent-tokenhub/`. +- Ganti metadata harga dan konteks di `models.providers` jika diperlukan. + +## Catatan lingkungan + +Jika Gateway berjalan sebagai daemon (launchd/systemd), pastikan `TOKENHUB_API_KEY` +tersedia untuk proses tersebut (misalnya, di `~/.openclaw/.env` atau melalui +`env.shellEnv`). + +## Dokumentasi terkait + +- [Konfigurasi OpenClaw](/id/gateway/configuration) +- [Provider Model](/id/concepts/model-providers) +- [Tencent TokenHub](https://cloud.tencent.com/document/product/1823/130050) diff --git a/docs/id/tools/index.md b/docs/id/tools/index.md index ab97aa0b3..a73b612f8 100644 --- a/docs/id/tools/index.md +++ b/docs/id/tools/index.md @@ -1,15 +1,15 @@ --- read_when: - Anda ingin memahami tool apa saja yang disediakan OpenClaw - - Anda perlu mengonfigurasi, mengizinkan, atau menolak tool + - Anda perlu mengonfigurasi, mengizinkan, atau menolak tool-tool - Anda sedang memutuskan antara tool bawaan, Skills, dan plugin summary: 'Ikhtisar tool dan plugin OpenClaw: apa yang dapat dilakukan agen dan cara memperluasnya' title: Tool dan Plugin x-i18n: - generated_at: "2026-04-06T03:12:05Z" + generated_at: "2026-04-22T09:15:36Z" model: gpt-5.4 provider: openai - source_hash: b2371239316997b0fe389bfa2ec38404e1d3e177755ad81ff8035ac583d9adeb + source_hash: 6edb9e13b72e6345554f25c8d8413d167a69501e6626828d9aa3aac6907cd092 source_path: tools/index.md workflow: 15 --- @@ -20,7 +20,7 @@ Semua yang dilakukan agen selain menghasilkan teks terjadi melalui **tool**. Tool adalah cara agen membaca file, menjalankan perintah, menjelajahi web, mengirim pesan, dan berinteraksi dengan perangkat. -## Tool, skill, dan plugin +## Tool, Skills, dan plugin OpenClaw memiliki tiga lapisan yang bekerja bersama: @@ -30,99 +30,100 @@ OpenClaw memiliki tiga lapisan yang bekerja bersama: `web_search`, `message`). OpenClaw menyediakan sekumpulan **tool bawaan** dan plugin dapat mendaftarkan tool tambahan. - Agen melihat tool sebagai definisi fungsi terstruktur yang dikirim ke model API. + Agen melihat tool sebagai definisi fungsi terstruktur yang dikirim ke API model. - - Skill adalah file markdown (`SKILL.md`) yang disuntikkan ke system prompt. + + Skill adalah file markdown (`SKILL.md`) yang disuntikkan ke prompt sistem. Skills memberi agen konteks, batasan, dan panduan langkah demi langkah untuk menggunakan tool secara efektif. Skills berada di workspace Anda, di folder bersama, - atau disertakan di dalam plugin. + atau dikirim di dalam plugin. - [Referensi Skills](/id/tools/skills) | [Membuat skill](/id/tools/creating-skills) + [Referensi Skills](/id/tools/skills) | [Membuat skills](/id/tools/creating-skills) - + Plugin adalah paket yang dapat mendaftarkan kombinasi kapabilitas apa pun: - channel, provider model, tool, skill, speech, realtime transcription, - realtime voice, media understanding, image generation, video generation, - web fetch, web search, dan lainnya. Beberapa plugin bersifat **core** (disertakan bersama - OpenClaw), lainnya bersifat **external** (dipublikasikan di npm oleh komunitas). + channel, provider model, tool, Skills, speech, transkripsi realtime, + suara realtime, pemahaman media, pembuatan gambar, pembuatan video, + web fetch, web search, dan lainnya. Beberapa plugin bersifat **inti** (dikirim bersama + OpenClaw), lainnya bersifat **eksternal** (dipublikasikan di npm oleh komunitas). - [Instal dan konfigurasikan plugin](/id/tools/plugin) | [Buat milik Anda sendiri](/id/plugins/building-plugins) + [Pasang dan konfigurasikan plugin](/id/tools/plugin) | [Bangun plugin Anda sendiri](/id/plugins/building-plugins) ## Tool bawaan -Tool berikut disertakan bersama OpenClaw dan tersedia tanpa menginstal plugin apa pun: +Tool ini dikirim bersama OpenClaw dan tersedia tanpa memasang plugin apa pun: -| Tool | Fungsinya | Halaman | -| ------------------------------------------ | ---------------------------------------------------------------------- | ------------------------------------------- | -| `exec` / `process` | Menjalankan perintah shell, mengelola proses latar belakang | [Exec](/id/tools/exec) | -| `code_execution` | Menjalankan analisis Python remote dalam sandbox | [Code Execution](/id/tools/code-execution) | -| `browser` | Mengontrol browser Chromium (navigasi, klik, screenshot) | [Browser](/id/tools/browser) | -| `web_search` / `x_search` / `web_fetch` | Menelusuri web, menelusuri posting X, mengambil konten halaman | [Web](/id/tools/web) | -| `read` / `write` / `edit` | I/O file di workspace | | -| `apply_patch` | Patch file multi-hunk | [Apply Patch](/id/tools/apply-patch) | -| `message` | Mengirim pesan ke semua channel | [Agent Send](/id/tools/agent-send) | -| `canvas` | Mengendalikan node Canvas (present, eval, snapshot) | | -| `nodes` | Menemukan dan menargetkan perangkat yang telah dipasangkan | | -| `cron` / `gateway` | Mengelola job terjadwal; memeriksa, menambal, memulai ulang, atau memperbarui gateway | | -| `image` / `image_generate` | Menganalisis atau menghasilkan gambar | [Image Generation](/id/tools/image-generation) | -| `music_generate` | Menghasilkan trek musik | [Music Generation](/tools/music-generation) | -| `video_generate` | Menghasilkan video | [Video Generation](/tools/video-generation) | -| `tts` | Konversi text-to-speech sekali jalan | [TTS](/id/tools/tts) | -| `sessions_*` / `subagents` / `agents_list` | Manajemen sesi, status, dan orkestrasi sub-agent | [Sub-agents](/id/tools/subagents) | -| `session_status` | Readback ringan bergaya `/status` dan override model per sesi | [Session Tools](/id/concepts/session-tool) | +| Tool | Fungsinya | Halaman | +| ------------------------------------------ | --------------------------------------------------------------------- | ------------------------------------------- | +| `exec` / `process` | Menjalankan perintah shell, mengelola proses latar belakang | [Exec](/id/tools/exec) | +| `code_execution` | Menjalankan analisis Python jarak jauh dalam sandbox | [Code Execution](/id/tools/code-execution) | +| `browser` | Mengendalikan browser Chromium (navigasi, klik, tangkapan layar) | [Browser](/id/tools/browser) | +| `web_search` / `x_search` / `web_fetch` | Menelusuri web, menelusuri postingan X, mengambil konten halaman | [Web](/id/tools/web) | +| `read` / `write` / `edit` | I/O file di workspace | | +| `apply_patch` | Patch file multi-hunk | [Apply Patch](/id/tools/apply-patch) | +| `message` | Mengirim pesan ke semua channel | [Agent Send](/id/tools/agent-send) | +| `canvas` | Mengoperasikan node Canvas (present, eval, snapshot) | | +| `nodes` | Menemukan dan menargetkan perangkat yang dipasangkan | | +| `cron` / `gateway` | Mengelola job terjadwal; memeriksa, mem-patch, memulai ulang, atau memperbarui Gateway | | +| `image` / `image_generate` | Menganalisis atau membuat gambar | [Image Generation](/id/tools/image-generation) | +| `music_generate` | Membuat trek musik | [Music Generation](/id/tools/music-generation) | +| `video_generate` | Membuat video | [Video Generation](/id/tools/video-generation) | +| `tts` | Konversi text-to-speech sekali jalan | [TTS](/id/tools/tts) | +| `sessions_*` / `subagents` / `agents_list` | Manajemen sesi, status, dan orkestrasi subagen | [Sub-agents](/id/tools/subagents) | +| `session_status` | Pembacaan ringan bergaya `/status` dan override model sesi | [Session Tools](/id/concepts/session-tool) | -Untuk pekerjaan gambar, gunakan `image` untuk analisis dan `image_generate` untuk pembuatan atau pengeditan. Jika Anda menargetkan `openai/*`, `google/*`, `fal/*`, atau provider gambar non-default lainnya, konfigurasikan auth/API key provider tersebut terlebih dahulu. +Untuk pekerjaan gambar, gunakan `image` untuk analisis dan `image_generate` untuk pembuatan atau pengeditan. Jika Anda menargetkan `openai/*`, `google/*`, `fal/*`, atau provider gambar non-default lain, konfigurasikan autentikasi/kunci API provider tersebut terlebih dahulu. -Untuk pekerjaan musik, gunakan `music_generate`. Jika Anda menargetkan `google/*`, `minimax/*`, atau provider musik non-default lainnya, konfigurasikan auth/API key provider tersebut terlebih dahulu. +Untuk pekerjaan musik, gunakan `music_generate`. Jika Anda menargetkan `google/*`, `minimax/*`, atau provider musik non-default lain, konfigurasikan autentikasi/kunci API provider tersebut terlebih dahulu. -Untuk pekerjaan video, gunakan `video_generate`. Jika Anda menargetkan `qwen/*` atau provider video non-default lainnya, konfigurasikan auth/API key provider tersebut terlebih dahulu. +Untuk pekerjaan video, gunakan `video_generate`. Jika Anda menargetkan `qwen/*` atau provider video non-default lain, konfigurasikan autentikasi/kunci API provider tersebut terlebih dahulu. -Untuk audio generation yang digerakkan workflow, gunakan `music_generate` ketika plugin seperti +Untuk pembuatan audio berbasis workflow, gunakan `music_generate` saat plugin seperti ComfyUI mendaftarkannya. Ini terpisah dari `tts`, yang merupakan text-to-speech. -`session_status` adalah tool status/readback ringan dalam grup sessions. +`session_status` adalah tool status/pembacaan ringan dalam grup sessions. Tool ini menjawab pertanyaan bergaya `/status` tentang sesi saat ini dan dapat secara opsional menetapkan override model per sesi; `model=default` menghapus -override tersebut. Seperti `/status`, tool ini dapat mengisi kembali penghitung token/cache yang jarang +override tersebut. Seperti `/status`, tool ini dapat mengisi balik penghitung token/cache yang jarang dan label model runtime aktif dari entri penggunaan transkrip terbaru. -`gateway` adalah tool runtime khusus owner untuk operasi gateway: +`gateway` adalah tool runtime khusus pemilik untuk operasi Gateway: -- `config.schema.lookup` untuk satu subtree config yang dibatasi path sebelum pengeditan -- `config.get` untuk snapshot config saat ini + hash +- `config.schema.lookup` untuk satu subtree config yang dicakup path sebelum pengeditan +- `config.get` untuk snapshot + hash config saat ini - `config.patch` untuk pembaruan config parsial dengan restart - `config.apply` hanya untuk penggantian config penuh -- `update.run` untuk self-update + restart yang eksplisit +- `update.run` untuk self-update + restart eksplisit Untuk perubahan parsial, utamakan `config.schema.lookup` lalu `config.patch`. Gunakan -`config.apply` hanya ketika Anda memang ingin mengganti seluruh config. +`config.apply` hanya jika Anda memang sengaja mengganti seluruh config. Tool ini juga menolak mengubah `tools.exec.ask` atau `tools.exec.security`; alias lama `tools.bash.*` dinormalisasi ke path exec terlindungi yang sama. ### Tool yang disediakan plugin -Plugin dapat mendaftarkan tool tambahan. Beberapa contohnya: +Plugin dapat mendaftarkan tool tambahan. Beberapa contoh: +- [Diffs](/id/tools/diffs) — penampil dan perender diff +- [LLM Task](/id/tools/llm-task) — langkah LLM hanya-JSON untuk output terstruktur - [Lobster](/id/tools/lobster) — runtime workflow bertipe dengan persetujuan yang dapat dilanjutkan -- [LLM Task](/id/tools/llm-task) — langkah LLM khusus JSON untuk output terstruktur -- [Music Generation](/tools/music-generation) — tool bersama `music_generate` dengan provider berbasis workflow -- [Diffs](/id/tools/diffs) — penampil dan renderer diff +- [Music Generation](/id/tools/music-generation) — tool `music_generate` bersama dengan provider berbasis workflow - [OpenProse](/id/prose) — orkestrasi workflow yang mengutamakan markdown +- [Tokenjuice](/id/tools/tokenjuice) — hasil tool `exec` dan `bash` yang ringkas untuk keluaran yang berisik ## Konfigurasi tool -### Daftar allow dan deny +### Daftar izin dan tolak -Kontrol tool mana yang dapat dipanggil agen melalui `tools.allow` / `tools.deny` di -config. Deny selalu menang atas allow. +Kontrol tool mana yang dapat dipanggil agen melalui `tools.allow` / `tools.deny` dalam +config. Penolakan selalu mengalahkan izin. ```json5 { @@ -138,12 +139,12 @@ config. Deny selalu menang atas allow. `tools.profile` menetapkan allowlist dasar sebelum `allow`/`deny` diterapkan. Override per agen: `agents.list[].tools.profile`. -| Profile | Yang dicakup | +| Profil | Cakupannya | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -| `full` | Tidak ada pembatasan (sama seperti tidak diatur) | +| `full` | Tanpa pembatasan (sama seperti tidak disetel) | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `music_generate`, `video_generate` | | `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `minimal` | hanya `session_status` | +| `minimal` | Hanya `session_status` | ### Grup tool @@ -164,13 +165,13 @@ Gunakan singkatan `group:*` dalam daftar allow/deny: | `group:media` | image, image_generate, music_generate, video_generate, tts | | `group:openclaw` | Semua tool OpenClaw bawaan (tidak termasuk tool plugin) | -`sessions_history` mengembalikan tampilan recall yang dibatasi dan difilter demi keamanan. Tool ini menghapus -tag thinking, scaffolding ``, payload XML tool-call teks polos +`sessions_history` mengembalikan tampilan recall terbatas yang difilter demi keamanan. Tool ini menghapus +thinking tag, scaffolding ``, payload XML pemanggilan tool dalam teks biasa (termasuk `...`, `...`, `...`, -`...`, dan blok tool-call yang terpotong), -scaffolding tool-call yang diturunkan, token kontrol model ASCII/full-width yang bocor, -dan XML tool-call MiniMax yang tidak valid dari teks assistant, lalu menerapkan +`...`, dan blok pemanggilan tool yang dipotong), +scaffolding pemanggilan tool yang diturunkan, token kontrol model ASCII/full-width yang bocor, +serta XML pemanggilan tool MiniMax yang cacat dari teks asisten, lalu menerapkan redaksi/pemotongan dan kemungkinan placeholder baris yang terlalu besar alih-alih bertindak sebagai dump transkrip mentah. diff --git a/docs/id/tools/tokenjuice.md b/docs/id/tools/tokenjuice.md new file mode 100644 index 000000000..fd415d198 --- /dev/null +++ b/docs/id/tools/tokenjuice.md @@ -0,0 +1,83 @@ +--- +read_when: + - Anda menginginkan hasil tool `exec` atau `bash` yang lebih singkat di OpenClaw + - Anda ingin mengaktifkan plugin tokenjuice bawaan + - Anda perlu memahami apa yang diubah oleh tokenjuice dan apa yang dibiarkannya mentah +summary: Memadatkan hasil tool exec dan bash yang berisik dengan plugin bawaan opsional +title: Tokenjuice +x-i18n: + generated_at: "2026-04-22T09:15:41Z" + model: gpt-5.4 + provider: openai + source_hash: 9b9a1054c9b1cc62e43ac6d5904c7790f9b27d8e0d0700c9da6e287c00e91783 + source_path: tools/tokenjuice.md + workflow: 15 +--- + +# Tokenjuice + +`tokenjuice` adalah plugin bawaan opsional yang memadatkan hasil tool `exec` dan `bash` +yang berisik setelah perintah selesai dijalankan. + +Plugin ini mengubah `tool_result` yang dikembalikan, bukan perintah itu sendiri. Tokenjuice tidak +menulis ulang input shell, menjalankan ulang perintah, atau mengubah exit code. + +Saat ini ini berlaku untuk run tertanam Pi, tempat tokenjuice mengait ke jalur `tool_result` +tertanam dan memangkas output yang dikembalikan ke sesi. + +## Aktifkan plugin + +Cara cepat: + +```bash +openclaw config set plugins.entries.tokenjuice.enabled true +``` + +Setara: + +```bash +openclaw plugins enable tokenjuice +``` + +OpenClaw sudah menyertakan plugin ini. Tidak ada langkah terpisah `plugins install` +atau `tokenjuice install openclaw`. + +Jika Anda lebih suka mengedit konfigurasi secara langsung: + +```json5 +{ + plugins: { + entries: { + tokenjuice: { + enabled: true, + }, + }, + }, +} +``` + +## Apa yang diubah oleh tokenjuice + +- Memadatkan hasil `exec` dan `bash` yang berisik sebelum dimasukkan kembali ke sesi. +- Menjaga eksekusi perintah asli tetap tidak berubah. +- Mempertahankan pembacaan konten file yang persis sama dan perintah lain yang harus dibiarkan mentah oleh tokenjuice. +- Tetap bersifat opt-in: nonaktifkan plugin jika Anda menginginkan output verbatim di mana saja. + +## Verifikasi bahwa ini berfungsi + +1. Aktifkan plugin. +2. Mulai sesi yang dapat memanggil `exec`. +3. Jalankan perintah yang berisik seperti `git status`. +4. Periksa bahwa hasil tool yang dikembalikan lebih singkat dan lebih terstruktur daripada output shell mentah. + +## Nonaktifkan plugin + +```bash +openclaw config set plugins.entries.tokenjuice.enabled false +``` + +Atau: + +```bash +openclaw plugins disable tokenjuice +```