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

chore(i18n): refresh id translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-05 01:52:21 +00:00
parent 337f09b1bc
commit d54240ba65
37 changed files with 5060 additions and 4442 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

212
docs/id/automation/tasks.md
View File

@ -1,46 +1,46 @@
---
read_when:
- Memeriksa pekerjaan latar belakang yang sedang berlangsung atau baru saja selesai
- Men-debug kegagalan pengiriman untuk eksekusi agen terpisah
- Memahami bagaimana eksekusi latar belakang berkaitan dengan sesi, Cron, dan Heartbeat
- Melakukan debug kegagalan pengiriman untuk eksekusi agen terpisah
- Memahami hubungan eksekusi latar belakang dengan sesi, Cron, dan Heartbeat
sidebarTitle: Background tasks
summary: Pelacakan tugas latar belakang untuk eksekusi ACP, subagen, pekerjaan Cron terisolasi, dan operasi CLI
title: Tugas latar belakang
x-i18n:
generated_at: "2026-05-01T09:22:19Z"
generated_at: "2026-05-05T01:44:27Z"
model: gpt-5.5
provider: openai
source_hash: 8782987a79989264ae3bd1ca4b16755bdfb7e295e4f77933bf3a38c136d837f4
source_hash: 60d6ea6178535b19b95d761b8e8b05a665234584ae69852fd21097988aa32991
source_path: automation/tasks.md
workflow: 16
---
<Note>
Mencari penjadwalan? Lihat [Automasi dan tugas](/id/automation) untuk memilih mekanisme yang tepat. Halaman ini adalah buku besar aktivitas untuk pekerjaan latar belakang, bukan penjadwal.
Mencari penjadwalan? Lihat [Otomatisasi dan tugas](/id/automation) untuk memilih mekanisme yang tepat. Halaman ini adalah catatan aktivitas untuk pekerjaan latar belakang, bukan penjadwal.
</Note>
Tugas latar belakang melacak pekerjaan yang berjalan **di luar sesi percakapan utama Anda**: proses ACP, pemijahan subagen, eksekusi pekerjaan cron terisolasi, dan operasi yang dimulai oleh CLI.
Tugas latar belakang melacak pekerjaan yang berjalan **di luar sesi percakapan utama Anda**: eksekusi ACP, pemunculan subagen, eksekusi tugas cron terisolasi, dan operasi yang dimulai dari CLI.
Tugas **tidak** menggantikan sesi, pekerjaan cron, atau Heartbeat — tugas adalah **buku besar aktivitas** yang mencatat pekerjaan terlepas apa yang terjadi, kapan, dan apakah berhasil.
Tugas **tidak** menggantikan sesi, tugas cron, atau heartbeat — tugas adalah **catatan aktivitas** yang merekam pekerjaan terpisah apa yang terjadi, kapan, dan apakah berhasil.
<Note>
Tidak setiap proses agen membuat tugas. Giliran Heartbeat dan chat interaktif normal tidak membuatnya. Semua eksekusi cron, pemijahan ACP, pemijahan subagen, dan perintah agen CLI membuatnya.
Tidak setiap eksekusi agen membuat tugas. Giliran Heartbeat dan obrolan interaktif normal tidak. Semua eksekusi cron, pemunculan ACP, pemunculan subagen, dan perintah agen CLI melakukannya.
</Note>
## TL;DR
## Ringkasan
- Tugas adalah **catatan**, bukan penjadwal — cron dan Heartbeat menentukan _kapan_ pekerjaan berjalan, tugas melacak _apa yang terjadi_.
- ACP, subagen, semua pekerjaan cron, dan operasi CLI membuat tugas. Giliran Heartbeat tidak.
- Tugas adalah **catatan**, bukan penjadwal — cron dan heartbeat menentukan _kapan_ pekerjaan berjalan, tugas melacak _apa yang terjadi_.
- ACP, subagen, semua tugas cron, dan operasi CLI membuat tugas. Giliran Heartbeat tidak.
- Setiap tugas bergerak melalui `queued → running → terminal` (succeeded, failed, timed_out, cancelled, atau lost).
- Tugas cron tetap aktif selama runtime cron masih memiliki pekerjaan tersebut; jika
status runtime dalam memori hilang, pemeliharaan tugas terlebih dahulu memeriksa riwayat
proses cron yang tahan lama sebelum menandai tugas sebagai hilang.
- Penyelesaian didorong oleh push: pekerjaan terlepas dapat memberi tahu secara langsung atau membangunkan
sesi/Heartbeat peminta saat selesai, sehingga loop polling status
- Tugas cron tetap aktif selama runtime cron masih memiliki tugas tersebut; jika
status runtime dalam memori hilang, pemeliharaan tugas terlebih dahulu memeriksa
riwayat eksekusi cron yang tahan lama sebelum menandai tugas sebagai hilang.
- Penyelesaian didorong secara push: pekerjaan terpisah dapat memberi tahu secara langsung atau membangunkan
sesi/heartbeat peminta saat selesai, sehingga loop polling status
biasanya bukan bentuk yang tepat.
- Proses cron terisolasi dan penyelesaian subagen melakukan upaya terbaik untuk membersihkan tab/proses browser terlacak bagi sesi anaknya sebelum pembukuan pembersihan akhir.
- Pengiriman cron terisolasi menekan balasan induk sementara yang usang ketika pekerjaan subagen turunan masih dikuras, dan lebih memilih output turunan akhir ketika output itu tiba sebelum pengiriman.
- Notifikasi penyelesaian dikirim langsung ke channel atau diantrekan untuk Heartbeat berikutnya.
- Eksekusi cron terisolasi dan penyelesaian subagen melakukan upaya terbaik untuk membersihkan tab/proses browser yang dilacak untuk sesi anaknya sebelum pembukuan pembersihan akhir.
- Pengiriman cron terisolasi menekan balasan induk sementara yang sudah basi saat pekerjaan subagen turunan masih dikuras, dan lebih memilih output turunan akhir saat output itu tiba sebelum pengiriman.
- Notifikasi penyelesaian dikirim langsung ke saluran atau diantrekan untuk heartbeat berikutnya.
- `openclaw tasks list` menampilkan semua tugas; `openclaw tasks audit` memunculkan masalah.
- Catatan terminal disimpan selama 7 hari, lalu dipangkas secara otomatis.
@ -49,10 +49,10 @@ Tidak setiap proses agen membuat tugas. Giliran Heartbeat dan chat interaktif no
<Tabs>
<Tab title="List and filter">
```bash
# Cantumkan semua tugas (terbaru lebih dulu)
# List all tasks (newest first)
openclaw tasks list
# Filter berdasarkan runtime atau status
# Filter by runtime or status
openclaw tasks list --runtime acp
openclaw tasks list --status running
```
@ -60,26 +60,26 @@ Tidak setiap proses agen membuat tugas. Giliran Heartbeat dan chat interaktif no
</Tab>
<Tab title="Inspect">
```bash
# Tampilkan detail untuk tugas tertentu (berdasarkan ID, ID proses, atau kunci sesi)
# Show details for a specific task (by ID, run ID, or session key)
openclaw tasks show <lookup>
```
</Tab>
<Tab title="Cancel and notify">
```bash
# Batalkan tugas yang sedang berjalan (membunuh sesi anak)
# Cancel a running task (kills the child session)
openclaw tasks cancel <lookup>
# Ubah kebijakan notifikasi untuk sebuah tugas
# Change notification policy for a task
openclaw tasks notify <lookup> state_changes
```
</Tab>
<Tab title="Audit and maintenance">
```bash
# Jalankan audit kesehatan
# Run a health audit
openclaw tasks audit
# Pratinjau atau terapkan pemeliharaan
# Preview or apply maintenance
openclaw tasks maintenance
openclaw tasks maintenance --apply
```
@ -87,7 +87,7 @@ Tidak setiap proses agen membuat tugas. Giliran Heartbeat dan chat interaktif no
</Tab>
<Tab title="Task flow">
```bash
# Periksa status TaskFlow
# Inspect TaskFlow state
openclaw tasks flow list
openclaw tasks flow show <lookup>
openclaw tasks flow cancel <lookup>
@ -98,27 +98,27 @@ Tidak setiap proses agen membuat tugas. Giliran Heartbeat dan chat interaktif no
## Apa yang membuat tugas
| Sumber | Jenis runtime | Kapan catatan tugas dibuat | Kebijakan notifikasi default |
| ---------------------- | ------------ | ------------------------------------------------------ | --------------------- |
| Proses latar belakang ACP | `acp` | Memijahkan sesi ACP anak | `done_only` |
| Orkestrasi subagen | `subagent` | Memijahkan subagen melalui `sessions_spawn` | `done_only` |
| Pekerjaan cron (semua jenis) | `cron` | Setiap eksekusi cron (sesi utama dan terisolasi) | `silent` |
| Operasi CLI | `cli` | Perintah `openclaw agent` yang berjalan melalui Gateway | `silent` |
| Pekerjaan media agen | `cli` | Proses `music_generate`/`video_generate` yang didukung sesi | `silent` |
| ---------------------- | ------------ | ------------------------------------------------------ | ---------------------------- |
| Eksekusi latar belakang ACP | `acp` | Memunculkan sesi ACP anak | `done_only` |
| Orkestrasi subagen | `subagent` | Memunculkan subagen melalui `sessions_spawn` | `done_only` |
| Tugas cron (semua jenis) | `cron` | Setiap eksekusi cron (sesi utama dan terisolasi) | `silent` |
| Operasi CLI | `cli` | Perintah `openclaw agent` yang berjalan melalui gateway | `silent` |
| Tugas media agen | `cli` | Eksekusi `music_generate`/`video_generate` berbasis sesi | `silent` |
<AccordionGroup>
<Accordion title="Notify defaults for cron and media">
Tugas cron sesi utama menggunakan kebijakan notifikasi `silent` secara default — tugas tersebut membuat catatan untuk pelacakan tetapi tidak menghasilkan notifikasi. Tugas cron terisolasi juga default ke `silent` tetapi lebih terlihat karena berjalan dalam sesinya sendiri.
Tugas cron sesi utama menggunakan kebijakan notifikasi `silent` secara default — tugas membuat catatan untuk pelacakan tetapi tidak menghasilkan notifikasi. Tugas cron terisolasi juga default ke `silent` tetapi lebih terlihat karena berjalan dalam sesi mereka sendiri.
Proses `music_generate` dan `video_generate` yang didukung sesi juga menggunakan kebijakan notifikasi `silent`. Proses tersebut tetap membuat catatan tugas, tetapi penyelesaian dikembalikan ke sesi agen asli sebagai wake internal sehingga agen dapat menulis pesan tindak lanjut dan melampirkan media yang selesai itu sendiri. Jika Anda memilih `tools.media.asyncCompletion.directSend`, penyelesaian `video_generate` asinkron dapat mencoba pengiriman channel langsung terlebih dahulu; penyelesaian `music_generate` asinkron tetap berada pada jalur wake sesi peminta.
Eksekusi `music_generate` dan `video_generate` berbasis sesi juga menggunakan kebijakan notifikasi `silent`. Eksekusi tersebut tetap membuat catatan tugas, tetapi penyelesaian dikembalikan ke sesi agen asli sebagai wake internal sehingga agen dapat menulis pesan tindak lanjut dan melampirkan media yang sudah selesai itu sendiri. Penyelesaian grup/saluran mengikuti kebijakan balasan terlihat yang normal, sehingga agen menggunakan alat pesan saat pengiriman sumber memerlukannya.
</Accordion>
<Accordion title="Concurrent video_generate guardrail">
Saat tugas `video_generate` yang didukung sesi masih aktif, alat tersebut juga bertindak sebagai pagar pengaman: panggilan `video_generate` berulang dalam sesi yang sama mengembalikan status tugas aktif, bukan memulai pembuatan konkuren kedua. Gunakan `action: "status"` ketika Anda menginginkan pencarian progres/status eksplisit dari sisi agen.
Saat tugas `video_generate` berbasis sesi masih aktif, alat tersebut juga bertindak sebagai pembatas: panggilan `video_generate` berulang dalam sesi yang sama mengembalikan status tugas aktif, bukan memulai generasi konkuren kedua. Gunakan `action: "status"` saat Anda menginginkan pencarian progres/status eksplisit dari sisi agen.
</Accordion>
<Accordion title="What does not create tasks">
- Giliran Heartbeat — sesi utama; lihat [Heartbeat](/id/gateway/heartbeat)
- Giliran chat interaktif normal
- Respons `/command` langsung
- Giliran obrolan interaktif normal
- Respons langsung `/command`
</Accordion>
</AccordionGroup>
@ -137,58 +137,58 @@ stateDiagram-v2
running --> lost : session gone > 5 min
```
| Status | Artinya |
| Status | Artinya |
| ----------- | -------------------------------------------------------------------------- |
| `queued` | Dibuat, menunggu agen dimulai |
| `running` | Giliran agen sedang aktif dieksekusi |
| `queued` | Dibuat, menunggu agen dimulai |
| `running` | Giliran agen sedang aktif dieksekusi |
| `succeeded` | Selesai dengan sukses |
| `failed` | Selesai dengan kesalahan |
| `timed_out` | Melebihi batas waktu yang dikonfigurasi |
| `cancelled` | Dihentikan oleh operator melalui `openclaw tasks cancel` |
| `failed` | Selesai dengan kesalahan |
| `timed_out` | Melebihi timeout yang dikonfigurasi |
| `cancelled` | Dihentikan oleh operator melalui `openclaw tasks cancel` |
| `lost` | Runtime kehilangan status pendukung otoritatif setelah masa tenggang 5 menit |
Transisi terjadi secara otomatis — ketika proses agen terkait berakhir, status tugas diperbarui agar sesuai.
Transisi terjadi secara otomatis — saat eksekusi agen terkait berakhir, status tugas diperbarui agar sesuai.
Penyelesaian proses agen bersifat otoritatif untuk catatan tugas aktif. Proses terlepas yang berhasil diselesaikan sebagai `succeeded`, kesalahan proses biasa diselesaikan sebagai `failed`, dan hasil timeout atau abort diselesaikan sebagai `timed_out`. Jika operator sudah membatalkan tugas, atau runtime sudah mencatat status terminal yang lebih kuat seperti `failed`, `timed_out`, atau `lost`, sinyal sukses yang datang belakangan tidak menurunkan status terminal tersebut.
Penyelesaian eksekusi agen bersifat otoritatif untuk catatan tugas aktif. Eksekusi terpisah yang berhasil diselesaikan sebagai `succeeded`, kesalahan eksekusi biasa diselesaikan sebagai `failed`, dan hasil timeout atau abort diselesaikan sebagai `timed_out`. Jika operator sudah membatalkan tugas, atau runtime sudah mencatat status terminal yang lebih kuat seperti `failed`, `timed_out`, atau `lost`, sinyal sukses yang datang kemudian tidak menurunkan status terminal tersebut.
`lost` sadar runtime:
- Tugas ACP: metadata sesi anak ACP pendukung menghilang.
- Tugas subagen: sesi anak pendukung menghilang dari penyimpanan agen target.
- Tugas cron: runtime cron tidak lagi melacak pekerjaan sebagai aktif dan riwayat
proses cron yang tahan lama tidak menunjukkan hasil terminal untuk proses tersebut. Audit CLI
offline tidak memperlakukan status runtime cron dalam prosesnya sendiri yang kosong sebagai otoritas.
- Tugas CLI: tugas sesi anak terisolasi menggunakan sesi anak; CLI berbasis chat
menggunakan konteks proses live sebagai gantinya, sehingga baris sesi
channel/grup/langsung yang tersisa tidak mempertahankannya tetap hidup. Proses
`openclaw agent` yang didukung Gateway juga diselesaikan dari hasil prosesnya, sehingga proses yang selesai
tidak tetap aktif sampai penyapu menandainya `lost`.
eksekusi cron yang tahan lama tidak menunjukkan hasil terminal untuk eksekusi tersebut. Audit CLI
offline tidak memperlakukan status runtime cron dalam prosesnya yang kosong sebagai otoritas.
- Tugas CLI: tugas sesi anak terisolasi menggunakan sesi anak; tugas CLI
berbasis obrolan menggunakan konteks eksekusi langsung sebagai gantinya, sehingga baris sesi
saluran/grup/langsung yang tersisa tidak membuatnya tetap hidup. Eksekusi
`openclaw agent` berbasis Gateway juga diselesaikan dari hasil eksekusinya, sehingga eksekusi yang selesai
tidak tetap aktif sampai sweeper menandainya `lost`.
## Pengiriman dan notifikasi
Ketika sebuah tugas mencapai status terminal, OpenClaw memberi tahu Anda. Ada dua jalur pengiriman:
Saat tugas mencapai status terminal, OpenClaw memberi tahu Anda. Ada dua jalur pengiriman:
**Pengiriman langsung** — jika tugas memiliki target channel (`requesterOrigin`), pesan penyelesaian langsung masuk ke channel itu (Telegram, Discord, Slack, dll.). Untuk penyelesaian subagen, OpenClaw juga mempertahankan perutean thread/topik terikat jika tersedia dan dapat mengisi `to` / akun yang hilang dari rute tersimpan sesi peminta (`lastChannel` / `lastTo` / `lastAccountId`) sebelum menyerah pada pengiriman langsung.
**Pengiriman langsung** — jika tugas memiliki target saluran (`requesterOrigin`), pesan penyelesaian langsung masuk ke saluran tersebut (Telegram, Discord, Slack, dll.). Untuk penyelesaian subagen, OpenClaw juga mempertahankan perutean thread/topik terikat saat tersedia dan dapat mengisi `to` / akun yang hilang dari rute tersimpan sesi peminta (`lastChannel` / `lastTo` / `lastAccountId`) sebelum menyerah pada pengiriman langsung.
**Pengiriman yang diantrekan sesi** — jika pengiriman langsung gagal atau tidak ada origin yang ditetapkan, pembaruan diantrekan sebagai event sistem dalam sesi peminta dan muncul pada Heartbeat berikutnya.
**Pengiriman antrean sesi** — jika pengiriman langsung gagal atau tidak ada origin yang ditetapkan, pembaruan diantrekan sebagai peristiwa sistem dalam sesi peminta dan muncul pada heartbeat berikutnya.
<Tip>
Penyelesaian tugas memicu wake Heartbeat langsung sehingga Anda melihat hasilnya dengan cepat — Anda tidak perlu menunggu tick Heartbeat terjadwal berikutnya.
Penyelesaian tugas memicu wake heartbeat langsung sehingga Anda melihat hasilnya dengan cepat — Anda tidak perlu menunggu tick heartbeat terjadwal berikutnya.
</Tip>
Itu berarti alur kerja biasanya berbasis push: mulai pekerjaan terlepas sekali, lalu biarkan runtime membangunkan atau memberi tahu Anda saat selesai. Poll status tugas hanya ketika Anda memerlukan debugging, intervensi, atau audit eksplisit.
Artinya alur kerja biasa berbasis push: mulai pekerjaan terpisah sekali, lalu biarkan runtime membangunkan atau memberi tahu Anda saat selesai. Poll status tugas hanya saat Anda perlu debugging, intervensi, atau audit eksplisit.
### Kebijakan notifikasi
Kontrol seberapa banyak yang Anda dengar tentang setiap tugas:
| Kebijakan | Yang dikirim |
| Kebijakan | Yang dikirim |
| --------------------- | ----------------------------------------------------------------------- |
| `done_only` (default) | Hanya status terminal (succeeded, failed, dll.) — **ini adalah default** |
| `state_changes` | Setiap transisi status dan pembaruan progres |
| `silent` | Tidak ada sama sekali |
| `state_changes` | Setiap transisi status dan pembaruan progres |
| `silent` | Tidak ada sama sekali |
Ubah kebijakan saat tugas berjalan:
Ubah kebijakan saat tugas sedang berjalan:
```bash
openclaw tasks notify <lookup> state_changes
@ -202,7 +202,7 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--json]
```
Kolom output: ID Tugas, Jenis, Status, Pengiriman, ID Proses, Sesi Anak, Ringkasan.
Kolom output: ID Tugas, Jenis, Status, Pengiriman, ID Eksekusi, Sesi Anak, Ringkasan.
</Accordion>
<Accordion title="tasks show">
@ -210,7 +210,7 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks show <lookup>
```
Token pencarian menerima ID tugas, ID proses, atau kunci sesi. Menampilkan catatan lengkap termasuk waktu, status pengiriman, kesalahan, dan ringkasan terminal.
Token pencarian menerima ID tugas, ID eksekusi, atau kunci sesi. Menampilkan catatan lengkap termasuk waktu, status pengiriman, kesalahan, dan ringkasan terminal.
</Accordion>
<Accordion title="tasks cancel">
@ -218,7 +218,7 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks cancel <lookup>
```
Untuk tugas ACP dan subagen, ini membunuh sesi anak. Untuk tugas yang dilacak CLI, pembatalan dicatat di registri tugas (tidak ada handle runtime anak terpisah). Status bertransisi ke `cancelled` dan notifikasi pengiriman dikirim jika berlaku.
Untuk tugas ACP dan subagen, ini mematikan sesi anak. Untuk tugas yang dilacak CLI, pembatalan dicatat dalam registri tugas (tidak ada handle runtime anak terpisah). Status berubah menjadi `cancelled` dan notifikasi pengiriman dikirim jika berlaku.
</Accordion>
<Accordion title="tasks notify">
@ -231,59 +231,59 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks audit [--json]
```
Memunculkan masalah operasional. Temuan juga muncul di `openclaw status` ketika masalah terdeteksi.
Memunculkan masalah operasional. Temuan juga muncul di `openclaw status` saat masalah terdeteksi.
| Temuan | Tingkat keparahan | Pemicu |
| Temuan | Tingkat Keparahan | Pemicu |
| ------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------ |
| `stale_queued` | warn | Diantrekan selama lebih dari 10 menit |
| `stale_running` | error | Berjalan selama lebih dari 30 menit |
| `stale_queued` | warn | Dalam antrean lebih dari 10 menit |
| `stale_running` | error | Berjalan lebih dari 30 menit |
| `lost` | warn/error | Kepemilikan tugas yang didukung runtime menghilang; tugas hilang yang dipertahankan memberi peringatan hingga `cleanupAfter`, lalu menjadi error |
| `delivery_failed` | warn | Pengiriman gagal dan kebijakan notifikasi bukan `silent` |
| `missing_cleanup` | warn | Tugas terminal tanpa timestamp pembersihan |
| `inconsistent_timestamps` | warn | Pelanggaran lini masa (misalnya berakhir sebelum dimulai) |
| `delivery_failed` | warn | Pengiriman gagal dan kebijakan notifikasi bukan `silent` |
| `missing_cleanup` | warn | Tugas terminal tanpa stempel waktu pembersihan |
| `inconsistent_timestamps` | warn | Pelanggaran linimasa (misalnya berakhir sebelum dimulai) |
</Accordion>
<Accordion title="tasks maintenance">
<Accordion title="pemeliharaan tugas">
```bash
openclaw tasks maintenance [--json]
openclaw tasks maintenance --apply [--json]
```
Gunakan ini untuk mempratinjau atau menerapkan rekonsiliasi, pencatatan pembersihan, dan pemangkasan untuk tugas serta status Task Flow.
Gunakan ini untuk mempratinjau atau menerapkan rekonsiliasi, penandaan pembersihan, dan pemangkasan untuk tugas dan status Task Flow.
Rekonsiliasi sadar runtime:
- Tugas ACP/subagent memeriksa sesi anak yang mendukungnya.
- Tugas subagent yang sesi anaknya memiliki tombstone pemulihan-restart ditandai hilang alih-alih diperlakukan sebagai sesi pendukung yang dapat dipulihkan.
- Tugas Cron memeriksa apakah runtime cron masih memiliki job tersebut, lalu memulihkan status terminal dari log eksekusi cron/status job yang dipersistenkan sebelum kembali ke `lost`. Hanya proses Gateway yang otoritatif untuk kumpulan job aktif cron dalam memori; audit CLI offline menggunakan riwayat tahan lama tetapi tidak menandai tugas cron hilang semata-mata karena Set lokal tersebut kosong.
- Tugas CLI yang didukung chat memeriksa konteks eksekusi live pemiliknya, bukan hanya baris sesi chat.
- Tugas ACP/subagen memeriksa sesi anak yang mendukungnya.
- Tugas subagen yang sesi anaknya memiliki tombstone pemulihan-mulai-ulang ditandai hilang, bukan diperlakukan sebagai sesi pendukung yang dapat dipulihkan.
- Tugas Cron memeriksa apakah runtime cron masih memiliki pekerjaan tersebut, lalu memulihkan status terminal dari log eksekusi cron/status pekerjaan yang dipersistenkan sebelum kembali ke `lost`. Hanya proses Gateway yang otoritatif untuk set pekerjaan aktif cron dalam memori; audit CLI offline menggunakan riwayat tahan lama tetapi tidak menandai tugas cron sebagai hilang hanya karena Set lokal itu kosong.
- Tugas CLI yang didukung chat memeriksa konteks live run pemiliknya, bukan hanya baris sesi chat.
Pembersihan penyelesaian juga sadar runtime:
- Penyelesaian subagent berupaya sebaik mungkin menutup tab/proses browser yang dilacak untuk sesi anak sebelum pembersihan pengumuman berlanjut.
- Penyelesaian cron terisolasi berupaya sebaik mungkin menutup tab/proses browser yang dilacak untuk sesi cron sebelum eksekusi sepenuhnya dibongkar.
- Pengiriman cron terisolasi menunggu tindak lanjut subagent turunan bila perlu dan menekan teks pengakuan induk yang basi alih-alih mengumumkannya.
- Pengiriman penyelesaian subagent mengutamakan teks asisten terbaru yang terlihat; jika kosong, ia kembali ke teks tool/toolResult terbaru yang telah disanitasi, dan eksekusi panggilan tool yang hanya timeout dapat diringkas menjadi ringkasan kemajuan parsial singkat. Eksekusi terminal yang gagal mengumumkan status kegagalan tanpa memutar ulang teks balasan yang ditangkap.
- Kegagalan pembersihan tidak menyamarkan hasil tugas yang sebenarnya.
- Penyelesaian subagen menutup tab/proses browser yang dilacak untuk sesi anak secara best-effort sebelum pembersihan pengumuman berlanjut.
- Penyelesaian cron terisolasi menutup tab/proses browser yang dilacak untuk sesi cron secara best-effort sebelum eksekusi sepenuhnya dibongkar.
- Pengiriman cron terisolasi menunggu tindak lanjut subagen turunan bila perlu dan menekan teks pengakuan induk yang basi alih-alih mengumumkannya.
- Pengiriman penyelesaian subagen memilih teks asisten terlihat terbaru; jika kosong, ia kembali ke teks tool/toolResult terbaru yang telah disanitasi, dan eksekusi panggilan alat yang hanya timeout dapat diringkas menjadi ringkasan progres parsial singkat. Eksekusi terminal yang gagal mengumumkan status kegagalan tanpa memutar ulang teks balasan yang tertangkap.
- Kegagalan pembersihan tidak menutupi hasil tugas yang sebenarnya.
</Accordion>
<Accordion title="tasks flow list | show | cancel">
<Accordion title="daftar | tampilkan | batalkan alur tugas">
```bash
openclaw tasks flow list [--status <status>] [--json]
openclaw tasks flow show <lookup> [--json]
openclaw tasks flow cancel <lookup>
```
Gunakan ini ketika Task Flow yang mengorkestrasi adalah hal yang Anda pedulikan, bukan satu catatan tugas latar belakang individual.
Gunakan ini ketika Task Flow pengorkestrasi adalah hal yang Anda pedulikan, bukan satu catatan tugas latar belakang individual.
</Accordion>
</AccordionGroup>
## Papan tugas chat (`/tasks`)
Gunakan `/tasks` di sesi chat mana pun untuk melihat tugas latar belakang yang tertaut ke sesi tersebut. Papan menampilkan tugas aktif dan yang baru selesai beserta runtime, status, waktu, dan detail kemajuan atau error.
Gunakan `/tasks` di sesi chat mana pun untuk melihat tugas latar belakang yang ditautkan ke sesi tersebut. Papan menampilkan tugas aktif dan yang baru saja selesai beserta runtime, status, waktu, dan detail progres atau error.
Ketika sesi saat ini tidak memiliki tugas tertaut yang terlihat, `/tasks` kembali ke jumlah tugas lokal agen sehingga Anda tetap mendapat gambaran umum tanpa membocorkan detail sesi lain.
Ketika sesi saat ini tidak memiliki tugas tertaut yang terlihat, `/tasks` kembali ke jumlah tugas lokal agen sehingga Anda tetap mendapatkan ikhtisar tanpa membocorkan detail sesi lain.
Untuk ledger operator lengkap, gunakan CLI: `openclaw tasks list`.
@ -297,15 +297,15 @@ Tasks: 3 queued · 2 running · 1 issues
Ringkasan melaporkan:
- **active** — jumlah `queued` + `running`
- **failures** — jumlah `failed` + `timed_out` + `lost`
- **byRuntime** — rincian menurut `acp`, `subagent`, `cron`, `cli`
- **aktif** — jumlah `queued` + `running`
- **kegagalan** — jumlah `failed` + `timed_out` + `lost`
- **byRuntime** — perincian menurut `acp`, `subagent`, `cron`, `cli`
Baik `/status` maupun tool `session_status` menggunakan snapshot tugas yang sadar pembersihan: tugas aktif diutamakan, baris selesai yang basi disembunyikan, dan kegagalan terbaru hanya muncul ketika tidak ada pekerjaan aktif yang tersisa. Ini menjaga kartu status tetap berfokus pada hal yang penting saat ini.
Baik `/status` maupun alat `session_status` menggunakan snapshot tugas yang sadar pembersihan: tugas aktif diprioritaskan, baris selesai yang basi disembunyikan, dan kegagalan terbaru hanya ditampilkan ketika tidak ada pekerjaan aktif yang tersisa. Ini menjaga kartu status tetap fokus pada hal yang penting saat ini.
## Penyimpanan dan pemeliharaan
### Lokasi tugas berada
### Tempat tugas berada
Catatan tugas dipersistenkan di SQLite pada:
@ -313,8 +313,8 @@ Catatan tugas dipersistenkan di SQLite pada:
$OPENCLAW_STATE_DIR/tasks/runs.sqlite
```
Registry dimuat ke memori saat gateway dimulai dan menyinkronkan penulisan ke SQLite agar tahan lama lintas restart.
Gateway menjaga log write-ahead SQLite tetap terbatas dengan menggunakan ambang autocheckpoint default SQLite plus checkpoint `TRUNCATE` berkala dan saat shutdown.
Registry dimuat ke memori saat Gateway dimulai dan menyinkronkan penulisan ke SQLite untuk ketahanan lintas mulai ulang.
Gateway menjaga log write-ahead SQLite tetap terbatas dengan menggunakan ambang batas autocheckpoint default SQLite ditambah checkpoint `TRUNCATE` berkala dan saat shutdown.
### Pemeliharaan otomatis
@ -322,13 +322,13 @@ Sweeper berjalan setiap **60 detik** dan menangani empat hal:
<Steps>
<Step title="Rekonsiliasi">
Memeriksa apakah tugas aktif masih memiliki dukungan runtime otoritatif. Tugas ACP/subagent menggunakan status sesi anak, tugas cron menggunakan kepemilikan job aktif, dan tugas CLI yang didukung chat menggunakan konteks eksekusi pemilik. Jika status pendukung tersebut hilang selama lebih dari 5 menit, tugas ditandai `lost`.
Memeriksa apakah tugas aktif masih memiliki dukungan runtime otoritatif. Tugas ACP/subagen menggunakan status sesi anak, tugas cron menggunakan kepemilikan pekerjaan aktif, dan tugas CLI yang didukung chat menggunakan konteks eksekusi pemilik. Jika status pendukung itu hilang selama lebih dari 5 menit, tugas ditandai `lost`.
</Step>
<Step title="Perbaikan sesi ACP">
Menutup sesi ACP one-shot milik induk yang terminal atau yatim, dan menutup sesi ACP persisten yang terminal atau yatim yang basi hanya ketika tidak ada binding percakapan aktif yang tersisa.
Menutup sesi ACP one-shot terminal atau yatim milik induk, dan menutup sesi ACP persisten terminal atau yatim yang basi hanya ketika tidak ada binding percakapan aktif yang tersisa.
</Step>
<Step title="Pencatatan pembersihan">
Menetapkan timestamp `cleanupAfter` pada tugas terminal (endedAt + 7 hari). Selama retensi, tugas hilang masih muncul dalam audit sebagai peringatan; setelah `cleanupAfter` kedaluwarsa atau ketika metadata pembersihan hilang, tugas tersebut menjadi error.
<Step title="Penandaan pembersihan">
Menetapkan stempel waktu `cleanupAfter` pada tugas terminal (endedAt + 7 hari). Selama retensi, tugas hilang masih muncul dalam audit sebagai peringatan; setelah `cleanupAfter` kedaluwarsa atau ketika metadata pembersihan hilang, tugas tersebut menjadi error.
</Step>
<Step title="Pemangkasan">
Menghapus catatan yang melewati tanggal `cleanupAfter`.
@ -339,32 +339,32 @@ Sweeper berjalan setiap **60 detik** dan menangani empat hal:
**Retensi:** catatan tugas terminal disimpan selama **7 hari**, lalu dipangkas otomatis. Tidak perlu konfigurasi.
</Note>
## Bagaimana tugas berhubungan dengan sistem lain
## Bagaimana tugas terkait dengan sistem lain
<AccordionGroup>
<Accordion title="Tugas dan Task Flow">
[Task Flow](/id/automation/taskflow) adalah lapisan orkestrasi alur di atas tugas latar belakang. Satu alur dapat mengoordinasikan beberapa tugas selama masa hidupnya menggunakan mode sinkronisasi terkelola atau tercermin. Gunakan `openclaw tasks` untuk memeriksa catatan tugas individual dan `openclaw tasks flow` untuk memeriksa alur yang mengorkestrasi.
[Task Flow](/id/automation/taskflow) adalah lapisan orkestrasi alur di atas tugas latar belakang. Satu alur dapat mengoordinasikan beberapa tugas selama masa pakainya menggunakan mode sinkronisasi terkelola atau tercermin. Gunakan `openclaw tasks` untuk memeriksa catatan tugas individual dan `openclaw tasks flow` untuk memeriksa alur pengorkestrasi.
Lihat [Task Flow](/id/automation/taskflow) untuk detail.
</Accordion>
<Accordion title="Tugas dan cron">
**Definisi** job cron berada di `~/.openclaw/cron/jobs.json`; status eksekusi runtime berada di sebelahnya dalam `~/.openclaw/cron/jobs-state.json`. **Setiap** eksekusi cron membuat catatan tugas — baik sesi utama maupun terisolasi. Tugas cron sesi utama secara default menggunakan kebijakan notifikasi `silent` sehingga tugas dilacak tanpa menghasilkan notifikasi.
**Definisi** pekerjaan cron berada di `~/.openclaw/cron/jobs.json`; status eksekusi runtime berada di sebelahnya dalam `~/.openclaw/cron/jobs-state.json`. **Setiap** eksekusi cron membuat catatan tugas — baik sesi utama maupun terisolasi. Tugas cron sesi utama secara default menggunakan kebijakan notifikasi `silent` sehingga tugas tersebut dilacak tanpa menghasilkan notifikasi.
Lihat [Job Cron](/id/automation/cron-jobs).
Lihat [Cron Jobs](/id/automation/cron-jobs).
</Accordion>
<Accordion title="Tugas dan Heartbeat">
Eksekusi Heartbeat adalah giliran sesi utama — eksekusi tersebut tidak membuat catatan tugas. Ketika tugas selesai, tugas dapat memicu wake Heartbeat sehingga Anda segera melihat hasilnya.
<Accordion title="Tugas dan heartbeat">
Eksekusi Heartbeat adalah giliran sesi utama — eksekusi tersebut tidak membuat catatan tugas. Ketika tugas selesai, tugas dapat memicu pembangkitan heartbeat sehingga Anda melihat hasilnya dengan segera.
Lihat [Heartbeat](/id/gateway/heartbeat).
</Accordion>
<Accordion title="Tugas dan sesi">
Tugas dapat merujuk ke `childSessionKey` (tempat pekerjaan berjalan) dan `requesterSessionKey` (pihak yang memulainya). Sesi adalah konteks percakapan; tugas adalah pelacakan aktivitas di atasnya.
Tugas dapat mereferensikan `childSessionKey` (tempat pekerjaan berjalan) dan `requesterSessionKey` (yang memulainya). Sesi adalah konteks percakapan; tugas adalah pelacakan aktivitas di atasnya.
</Accordion>
<Accordion title="Tugas dan eksekusi agen">
`runId` milik tugas tertaut ke eksekusi agen yang melakukan pekerjaan. Peristiwa siklus hidup agen (mulai, selesai, error) secara otomatis memperbarui status tugas — Anda tidak perlu mengelola siklus hidup secara manual.
`runId` milik tugas ditautkan ke eksekusi agen yang melakukan pekerjaan. Peristiwa siklus hidup agen (mulai, selesai, error) secara otomatis memperbarui status tugas — Anda tidak perlu mengelola siklus hidup secara manual.
</Accordion>
</AccordionGroup>

706
docs/id/channels/slack.md
View File

File diff suppressed because it is too large Load Diff

401
docs/id/ci.md
View File

@ -1,94 +1,94 @@
---
read_when:
- Anda perlu memahami mengapa sebuah pekerjaan CI berjalan atau tidak berjalan
- Anda perlu memahami mengapa suatu pekerjaan CI berjalan atau tidak berjalan
- Anda sedang men-debug pemeriksaan GitHub Actions yang gagal
- Anda sedang mengoordinasikan pelaksanaan atau pengulangan validasi rilis
- Anda mengubah pengiriman ClawSweeper atau penerusan aktivitas GitHub
- Anda sedang mengubah pengiriman ClawSweeper atau penerusan aktivitas GitHub
summary: Graf pekerjaan CI, gerbang cakupan, payung rilis, dan padanan perintah lokal
title: Alur kerja CI
x-i18n:
generated_at: "2026-05-04T07:03:05Z"
generated_at: "2026-05-05T01:44:28Z"
model: gpt-5.5
provider: openai
source_hash: 72959d0feaf1339f01c9da263153fd89cc4727da6f928933819931991222714d
source_hash: 16771940889d1fa944a5bfafe1152a033d96625595a2d89ff2cedbd3022cee66
source_path: ci.md
workflow: 16
---
OpenClaw CI berjalan pada setiap push ke `main` dan setiap pull request. Job `preflight` mengklasifikasikan diff dan menonaktifkan lane mahal ketika hanya area yang tidak terkait yang berubah. Eksekusi manual `workflow_dispatch` sengaja melewati pemetaan cakupan cerdas dan menyebarkan graf penuh untuk kandidat rilis dan validasi luas. Lane Android tetap opsional melalui `include_android`. Cakupan plugin khusus rilis berada di workflow [`Plugin Prerelease`](#plugin-prerelease) terpisah dan hanya berjalan dari [`Full Release Validation`](#full-release-validation) atau dispatch manual eksplisit.
OpenClaw CI berjalan pada setiap push ke `main` dan setiap pull request. Job `preflight` mengklasifikasikan diff dan menonaktifkan lane yang mahal saat hanya area yang tidak terkait yang berubah. Run `workflow_dispatch` manual sengaja melewati smart scoping dan menyebarkan grafik penuh untuk kandidat rilis dan validasi luas. Lane Android tetap opt-in melalui `include_android`. Cakupan Plugin khusus rilis berada di workflow [`Plugin Prarilis`](#plugin-prerelease) terpisah dan hanya berjalan dari [`Validasi Rilis Penuh`](#full-release-validation) atau dispatch manual eksplisit.
## Ikhtisar pipeline
| Job | Tujuan | Kapan berjalan |
| -------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| `preflight` | Mendeteksi perubahan khusus docs, cakupan yang berubah, ekstensi yang berubah, dan membangun manifes CI | Selalu pada push dan PR non-draft |
| `security-scm-fast` | Deteksi kunci privat dan audit workflow melalui `zizmor` | Selalu pada push dan PR non-draft |
| `security-dependency-audit` | Audit lockfile produksi bebas dependensi terhadap advisori npm | Selalu pada push dan PR non-draft |
| `security-fast` | Agregat wajib untuk job keamanan cepat | Selalu pada push dan PR non-draft |
| `check-dependencies` | Pass Knip khusus dependensi produksi plus guard allowlist file yang tidak digunakan | Perubahan yang relevan dengan Node |
| `build-artifacts` | Membangun `dist/`, Control UI, pemeriksaan artefak build, dan artefak downstream yang dapat digunakan ulang | Perubahan yang relevan dengan Node |
| `checks-fast-core` | Lane kebenaran 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-core-test` | Shard tes Node inti, mengecualikan lane channel, bundled, contract, dan extension | Perubahan yang relevan dengan Node |
| `check` | Padanan gate lokal utama yang di-shard: tipe prod, lint, guard, tipe tes, dan smoke ketat | Perubahan yang relevan dengan Node |
| `check-additional` | Arsitektur, drift boundary/prompt yang di-shard, guard ekstensi, boundary paket, dan gateway watch | Perubahan yang relevan dengan Node |
| `build-smoke` | Tes smoke CLI hasil build dan smoke memori startup | Perubahan yang relevan dengan Node |
| `checks` | Verifikator untuk tes channel artefak build | Perubahan yang relevan dengan Node |
| `checks-node-compat-node22` | Lane build dan smoke kompatibilitas Node 22 | Dispatch CI manual untuk rilis |
| `check-docs` | Pemformatan docs, lint, dan pemeriksaan broken link | Docs berubah |
| `skills-python` | Ruff + pytest untuk skills berbasis Python | Perubahan yang relevan dengan skill Python |
| `checks-windows` | Tes proses/path khusus Windows plus regresi specifier impor runtime bersama | Perubahan yang relevan dengan Windows |
| `macos-node` | Lane tes TypeScript macOS menggunakan artefak build bersama | Perubahan yang relevan dengan macOS |
| `macos-swift` | Swift lint, build, dan tes untuk aplikasi macOS | Perubahan yang relevan dengan macOS |
| `android` | Tes unit Android untuk kedua flavor plus satu build APK debug | Perubahan yang relevan dengan Android |
| `test-performance-agent` | Optimisasi tes lambat Codex harian setelah aktivitas tepercaya | CI main berhasil atau dispatch manual |
| `openclaw-performance` | Laporan performa runtime Kova harian/berdasarkan permintaan dengan lane mock-provider, deep-profile, dan live GPT 5.4 | Terjadwal dan dispatch manual |
| Job | Tujuan | Kapan berjalan |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| `preflight` | Mendeteksi perubahan khusus docs, scope yang berubah, ekstensi 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 bebas dependensi terhadap advisori npm | Selalu pada push dan PR non-draf |
| `security-fast` | Agregat wajib untuk job keamanan cepat | Selalu pada push dan PR non-draf |
| `check-dependencies` | Pass khusus dependensi Knip produksi plus guard allowlist unused-file | Perubahan relevan Node |
| `build-artifacts` | Membangun `dist/`, Control UI, pemeriksaan artefak build, dan artefak downstream yang dapat digunakan ulang | Perubahan relevan Node |
| `checks-fast-core` | Lane kebenaran Linux cepat seperti pemeriksaan bundled/plugin-contract/protocol | Perubahan relevan Node |
| `checks-fast-contracts-channels` | Pemeriksaan kontrak channel tersharding dengan hasil pemeriksaan agregat stabil | Perubahan relevan Node |
| `checks-node-core-test` | Shard test Core Node, mengecualikan lane channel, bundled, contract, dan extension | Perubahan relevan Node |
| `check` | Ekuivalen gate lokal utama tersharding: tipe prod, lint, guard, tipe test, dan smoke ketat | Perubahan relevan Node |
| `check-additional` | Arsitektur, drift boundary/prompt tersharding, guard extension, boundary package, dan gateway watch | Perubahan relevan Node |
| `build-smoke` | Test smoke CLI hasil build dan smoke memori startup | Perubahan relevan Node |
| `checks` | Verifier untuk test channel artefak build | Perubahan relevan Node |
| `checks-node-compat-node22` | Build kompatibilitas Node 22 dan lane smoke | Dispatch CI manual untuk rilis |
| `check-docs` | Pemeriksaan format docs, lint, dan broken-link | Docs berubah |
| `skills-python` | Ruff + pytest untuk skills berbasis Python | Perubahan relevan skill Python |
| `checks-windows` | Test proses/path khusus Windows plus regresi specifier impor runtime bersama | Perubahan relevan Windows |
| `macos-node` | Lane test TypeScript macOS menggunakan artefak build bersama | Perubahan relevan macOS |
| `macos-swift` | Swift lint, build, dan test untuk aplikasi macOS | Perubahan relevan macOS |
| `android` | Test unit Android untuk kedua flavor plus satu build APK debug | Perubahan relevan Android |
| `test-performance-agent` | Optimisasi test lambat Codex harian setelah aktivitas tepercaya | Sukses CI main atau dispatch manual |
| `openclaw-performance` | Laporan performa runtime Kova harian/sesuai permintaan dengan lane mock-provider, deep-profile, dan GPT 5.4 live | Dispatch terjadwal dan manual |
## Urutan fail-fast
1. `preflight` menentukan lane mana yang ada sejak awal. Logika `docs-scope` dan `changed-scope` adalah langkah di dalam job ini, bukan job mandiri.
1. `preflight` menentukan lane mana yang ada sama sekali. Logika `docs-scope` dan `changed-scope` adalah langkah di dalam job ini, bukan job mandiri.
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs`, dan `skills-python` gagal cepat tanpa menunggu job matriks artefak dan platform yang lebih berat.
3. `build-artifacts` berjalan beririsan dengan lane Linux cepat agar konsumen downstream dapat mulai segera setelah build bersama siap.
3. `build-artifacts` berjalan tumpang tindih dengan lane Linux cepat sehingga konsumen downstream dapat mulai segera setelah build bersama siap.
4. Lane platform dan runtime yang lebih berat menyebar setelah itu: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift`, dan `android`.
GitHub dapat menandai job yang tergantikan sebagai `cancelled` ketika push yang lebih baru masuk ke PR yang sama atau ref `main`. Perlakukan itu sebagai noise CI kecuali eksekusi terbaru untuk ref yang sama juga gagal. Pemeriksaan shard agregat menggunakan `!cancelled() && always()` sehingga tetap melaporkan kegagalan shard normal tetapi tidak mengantre setelah seluruh workflow sudah tergantikan. Kunci konkurensi CI otomatis diberi versi (`CI-v7-*`) sehingga zombie di sisi GitHub dalam grup antrean lama tidak dapat memblokir eksekusi main yang lebih baru tanpa batas. Eksekusi full-suite manual menggunakan `CI-manual-v1-*` dan tidak membatalkan eksekusi yang sedang berjalan.
GitHub dapat menandai job yang tergantikan sebagai `cancelled` ketika push yang lebih baru masuk pada PR yang sama atau ref `main`. Perlakukan itu sebagai noise CI kecuali run terbaru untuk ref yang sama juga gagal. Pemeriksaan shard agregat menggunakan `!cancelled() && always()` sehingga tetap melaporkan kegagalan shard normal tetapi tidak mengantre setelah seluruh workflow sudah tergantikan. Key konkurensi CI otomatis diberi versi (`CI-v7-*`) sehingga zombie sisi GitHub dalam grup antrean lama tidak dapat memblokir run main yang lebih baru tanpa batas. Run full-suite manual menggunakan `CI-manual-v1-*` dan tidak membatalkan run yang sedang berjalan.
## Cakupan dan routing
## Scope dan routing
Logika cakupan berada di `scripts/ci-changed-scope.mjs` dan dicakup oleh tes unit di `src/scripts/ci-changed-scope.test.ts`. Dispatch manual melewati deteksi changed-scope dan membuat manifes preflight bertindak seolah setiap area bercakupan berubah.
Logika scope berada di `scripts/ci-changed-scope.mjs` dan dicakup oleh test unit di `src/scripts/ci-changed-scope.test.ts`. Dispatch manual melewati deteksi changed-scope dan membuat manifes preflight bertindak seolah setiap area terscope berubah.
- **Edit workflow CI** memvalidasi graf CI Node plus linting workflow, tetapi tidak memaksa build native Windows, Android, atau macOS dengan sendirinya; lane platform tersebut tetap dicakup ke perubahan sumber platform.
- **Edit khusus routing CI, edit fixture core-test murah tertentu, dan edit helper/test-routing kontrak plugin yang sempit** menggunakan jalur manifes cepat khusus Node: `preflight`, keamanan, dan satu tugas `checks-fast-core`. Jalur itu melewati artefak build, kompatibilitas Node 22, kontrak channel, shard inti penuh, shard bundled-plugin, dan matriks guard tambahan ketika perubahan terbatas pada permukaan routing atau helper yang langsung diuji tugas cepat.
- **Pemeriksaan Node Windows** dicakup ke wrapper proses/path khusus Windows, helper runner npm/pnpm/UI, konfigurasi package manager, dan permukaan workflow CI yang mengeksekusi lane itu; perubahan sumber, plugin, install-smoke, dan khusus tes yang tidak terkait tetap berada pada lane Node Linux.
- **Edit workflow CI** memvalidasi grafik CI Node plus linting workflow, tetapi tidak memaksa build native Windows, Android, atau macOS dengan sendirinya; lane platform tersebut tetap terscope ke perubahan sumber platform.
- **Edit khusus routing CI, edit fixture core-test murah tertentu, dan edit helper/test-routing kontrak Plugin yang sempit** menggunakan path manifes cepat khusus Node: `preflight`, keamanan, dan satu tugas `checks-fast-core`. Path itu melewati artefak build, kompatibilitas Node 22, kontrak channel, shard core penuh, shard Plugin bawaan, dan matriks guard tambahan ketika perubahan terbatas pada permukaan routing atau helper yang dilatih langsung oleh tugas cepat tersebut.
- **Pemeriksaan Node Windows** terscope ke wrapper proses/path khusus Windows, helper runner npm/pnpm/UI, konfigurasi package manager, dan permukaan workflow CI yang menjalankan lane tersebut; perubahan sumber, Plugin, install-smoke, dan khusus test yang tidak terkait tetap pada lane Linux Node.
Keluarga tes Node paling lambat dipisah atau diseimbangkan agar setiap job tetap kecil tanpa memesan runner berlebihan: kontrak channel berjalan sebagai tiga shard berbobot, lane core unit fast/support berjalan terpisah, infrastruktur runtime inti dibagi antara shard state dan process/config, auto-reply berjalan sebagai worker seimbang (dengan subtree reply dipisah menjadi shard agent-runner, dispatch, dan commands/state-routing), dan konfigurasi gateway/server agentic dipisah di lane chat/auth/model/http-plugin/runtime/startup alih-alih menunggu artefak build. Tes browser, QA, media, dan plugin lain yang luas menggunakan konfigurasi Vitest khususnya, bukan catch-all plugin bersama. Shard include-pattern mencatat entri timing menggunakan nama shard CI, sehingga `.artifacts/vitest-shard-timings.json` dapat membedakan seluruh konfigurasi dari shard terfilter. `check-additional` menjaga pekerjaan compile/canary package-boundary tetap bersama dan memisahkan arsitektur topologi runtime dari cakupan gateway watch; daftar guard boundary distriping di empat shard matriks, masing-masing menjalankan guard independen terpilih secara bersamaan dan mencetak timing per pemeriksaan, termasuk `pnpm prompt:snapshots:check` sehingga drift prompt happy-path runtime Codex dipatok ke PR yang menyebabkannya. Gateway watch, tes channel, dan shard core support-boundary berjalan bersamaan di dalam `build-artifacts` setelah `dist/` dan `dist-runtime/` sudah dibangun.
Keluarga test Node paling lambat dibagi atau diseimbangkan agar setiap job tetap kecil tanpa memesan runner berlebihan: kontrak channel berjalan sebagai tiga shard berbobot, lane core unit fast/support berjalan terpisah, infra runtime core dibagi antara shard state dan process/config, auto-reply berjalan sebagai worker seimbang (dengan subtree reply dibagi menjadi shard agent-runner, dispatch, dan commands/state-routing), dan konfigurasi gateway/server agentic dibagi di seluruh lane chat/auth/model/http-plugin/runtime/startup alih-alih menunggu artefak build. Test browser, QA, media, dan Plugin lain-lain yang luas menggunakan konfigurasi Vitest khususnya, bukan catch-all Plugin bersama. Shard include-pattern merekam entri timing menggunakan nama shard CI, sehingga `.artifacts/vitest-shard-timings.json` dapat membedakan seluruh config dari shard terfilter. `check-additional` menjaga pekerjaan compile/canary package-boundary tetap bersama dan memisahkan arsitektur topologi runtime dari cakupan gateway watch; daftar guard boundary distriping di empat shard matriks, masing-masing menjalankan guard independen terpilih secara paralel dan mencetak timing per pemeriksaan, termasuk `pnpm prompt:snapshots:check` sehingga drift prompt happy-path runtime Codex dipaku ke PR yang menyebabkannya. Gateway watch, test channel, dan shard core support-boundary berjalan bersamaan di dalam `build-artifacts` setelah `dist/` dan `dist-runtime/` sudah dibangun.
CI Android menjalankan `testPlayDebugUnitTest` dan `testThirdPartyDebugUnitTest`, lalu membangun APK debug Play. Flavor third-party tidak memiliki source set atau manifes terpisah; lane tes unitnya tetap mengompilasi flavor dengan flag BuildConfig SMS/call-log, sekaligus menghindari job packaging APK debug duplikat pada setiap push yang relevan dengan Android.
CI Android menjalankan `testPlayDebugUnitTest` dan `testThirdPartyDebugUnitTest` lalu membangun APK debug Play. Flavor third-party tidak memiliki source set atau manifes terpisah; lane unit-test-nya tetap mengompilasi flavor dengan flag BuildConfig SMS/call-log, sambil menghindari job packaging APK debug duplikat pada setiap push relevan Android.
Shard `check-dependencies` menjalankan `pnpm deadcode:dependencies` (pass Knip khusus dependensi produksi yang dipatok ke versi Knip terbaru, dengan usia rilis minimum pnpm dinonaktifkan untuk instalasi `dlx`) dan `pnpm deadcode:unused-files`, yang membandingkan temuan file produksi tidak terpakai dari Knip dengan `scripts/deadcode-unused-files.allowlist.mjs`. Guard file tidak terpakai gagal ketika PR menambahkan file tidak terpakai baru yang belum ditinjau atau meninggalkan entri allowlist basi, sambil mempertahankan permukaan plugin dinamis, generated, build, live-test, dan package bridge yang disengaja yang tidak dapat diselesaikan Knip secara statis.
Shard `check-dependencies` menjalankan `pnpm deadcode:dependencies` (pass khusus dependensi Knip produksi yang dipaku ke versi Knip terbaru, dengan usia rilis minimum pnpm dinonaktifkan untuk instalasi `dlx`) dan `pnpm deadcode:unused-files`, yang membandingkan temuan unused-file produksi Knip terhadap `scripts/deadcode-unused-files.allowlist.mjs`. Guard unused-file gagal ketika PR menambahkan file tidak terpakai baru yang belum ditinjau atau meninggalkan entri allowlist basi, sambil mempertahankan permukaan Plugin dinamis, generated, build, live-test, dan package bridge yang disengaja yang tidak dapat diselesaikan Knip secara statis.
## Penerusan aktivitas ClawSweeper
`.github/workflows/clawsweeper-dispatch.yml` adalah bridge sisi target dari aktivitas repository OpenClaw ke ClawSweeper. Workflow ini tidak melakukan checkout atau mengeksekusi kode pull request yang tidak tepercaya. Workflow membuat token GitHub App dari `CLAWSWEEPER_APP_PRIVATE_KEY`, lalu mengirim payload `repository_dispatch` ringkas ke `openclaw/clawsweeper`.
`.github/workflows/clawsweeper-dispatch.yml` adalah bridge sisi target dari aktivitas repositori OpenClaw ke ClawSweeper. Workflow ini tidak checkout atau mengeksekusi kode pull request tidak tepercaya. Workflow membuat token GitHub App dari `CLAWSWEEPER_APP_PRIVATE_KEY`, lalu mengirim payload `repository_dispatch` ringkas ke `openclaw/clawsweeper`.
Workflow ini memiliki empat lane:
- `clawsweeper_item` untuk permintaan tinjauan issue dan pull request yang tepat;
- `clawsweeper_comment` untuk perintah ClawSweeper eksplisit di komentar issue;
- `clawsweeper_commit_review` untuk permintaan tinjauan tingkat commit pada push `main`;
- `github_activity` untuk aktivitas GitHub umum yang dapat diperiksa agen ClawSweeper.
- `clawsweeper_item` untuk permintaan review issue dan pull request yang tepat;
- `clawsweeper_comment` untuk perintah ClawSweeper eksplisit dalam komentar issue;
- `clawsweeper_commit_review` untuk permintaan review tingkat commit pada push `main`;
- `github_activity` untuk aktivitas GitHub umum yang dapat diperiksa agent ClawSweeper.
Lane `github_activity` hanya meneruskan metadata yang dinormalisasi: jenis event, aksi, aktor, repository, nomor item, URL, judul, status, dan kutipan singkat untuk komentar atau ulasan jika ada. Lane ini sengaja menghindari penerusan seluruh body webhook. Workflow penerima di `openclaw/clawsweeper` adalah `.github/workflows/github-activity.yml`, yang mengirim event yang dinormalisasi ke hook OpenClaw Gateway untuk agen ClawSweeper.
Lane `github_activity` hanya meneruskan metadata yang dinormalisasi: jenis event, action, actor, repositori, nomor item, URL, judul, state, dan kutipan singkat untuk komentar atau review jika ada. Lane ini sengaja menghindari penerusan seluruh body webhook. Workflow penerima di `openclaw/clawsweeper` adalah `.github/workflows/github-activity.yml`, yang memposting event yang dinormalisasi ke hook OpenClaw Gateway untuk agent ClawSweeper.
Aktivitas umum adalah observasi, bukan pengiriman secara default. Agen ClawSweeper menerima target Discord di prompt-nya dan hanya boleh memposting ke `#clawsweeper` ketika event mengejutkan, dapat ditindaklanjuti, berisiko, atau berguna secara operasional. Pembukaan rutin, edit, churn bot, noise webhook duplikat, dan lalu lintas ulasan normal harus menghasilkan `NO_REPLY`.
Aktivitas umum adalah observasi, bukan pengiriman secara default. Agent ClawSweeper menerima target Discord dalam prompt-nya dan sebaiknya memposting ke `#clawsweeper` hanya ketika event tersebut mengejutkan, dapat ditindaklanjuti, berisiko, atau berguna secara operasional. Pembukaan rutin, edit, churn bot, noise webhook duplikat, dan traffic review normal sebaiknya menghasilkan `NO_REPLY`.
Perlakukan judul, komentar, body, teks ulasan, nama branch, dan pesan commit GitHub sebagai data yang tidak tepercaya di seluruh jalur ini. Semua itu adalah input untuk peringkasan dan triase, bukan instruksi untuk workflow atau runtime agen.
Perlakukan judul, komentar, body, teks review, nama branch, dan pesan commit GitHub sebagai data tidak tepercaya di seluruh path ini. Semuanya adalah input untuk peringkasan dan triage, bukan instruksi untuk workflow atau runtime agent.
## Dispatch manual
Dispatch CI manual menjalankan grafik job yang sama seperti CI normal tetapi memaksa setiap lane berscope non-Android aktif: shard Linux Node, shard plugin bawaan, kontrak channel, kompatibilitas Node 22, `check`, `check-additional`, smoke build, pemeriksaan dokumen, Python skills, Windows, macOS, dan i18n Control UI. Dispatch CI manual mandiri hanya menjalankan Android dengan `include_android=true`; umbrella rilis penuh mengaktifkan Android dengan meneruskan `include_android=true`. Pemeriksaan statis prarilis Plugin, shard `agentic-plugins` khusus rilis, sweep batch ekstensi penuh, dan lane Docker prarilis Plugin dikecualikan dari CI. Suite Docker prarilis hanya berjalan saat `Full Release Validation` men-dispatch workflow `Plugin Prerelease` terpisah dengan gate validasi rilis diaktifkan.
Dispatch CI manual menjalankan grafik job yang sama seperti CI normal, tetapi memaksa setiap lane berskop non-Android aktif: shard Linux Node, shard plugin bawaan, kontrak channel, kompatibilitas Node 22, `check`, `check-additional`, smoke build, pemeriksaan docs, Python skills, Windows, macOS, dan i18n Control UI. Dispatch CI manual mandiri hanya menjalankan Android dengan `include_android=true`; payung rilis penuh mengaktifkan Android dengan meneruskan `include_android=true`. Pemeriksaan statis prarilis Plugin, shard khusus rilis `agentic-plugins`, sweep batch ekstensi penuh, dan lane Docker prarilis plugin dikecualikan dari CI. Suite Docker prarilis hanya berjalan ketika `Full Release Validation` men-dispatch workflow `Plugin Prerelease` terpisah dengan gate validasi rilis diaktifkan.
Run manual menggunakan grup konkurensi unik sehingga suite penuh kandidat rilis tidak dibatalkan oleh run push atau PR lain pada ref yang sama. Input opsional `target_ref` memungkinkan caller tepercaya menjalankan grafik tersebut terhadap branch, tag, atau SHA commit penuh sambil menggunakan file workflow dari ref dispatch yang dipilih.
Run manual menggunakan grup konkurensi unik sehingga suite penuh kandidat rilis tidak dibatalkan oleh run push atau PR lain pada ref yang sama. Input opsional `target_ref` memungkinkan caller tepercaya menjalankan grafik itu terhadap branch, tag, atau SHA commit penuh sambil menggunakan file workflow dari ref dispatch yang dipilih.
```bash
gh workflow run ci.yml --ref release/YYYY.M.D
@ -98,17 +98,17 @@ gh workflow run full-release-validation.yml --ref main -f ref=<branch-or-sha>
## Runner
| Runner | Job |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubuntu-24.04` | `preflight`, job dan agregat keamanan cepat (`security-scm-fast`, `security-dependency-audit`, `security-fast`), pemeriksaan protokol/kontrak/bundled cepat, pemeriksaan kontrak channel tershard, shard `check` kecuali lint, shard dan agregat `check-additional`, verifier agregat pengujian Node, pemeriksaan dokumen, Python skills, workflow-sanity, labeler, auto-response; preflight install-smoke juga menggunakan Ubuntu yang dihosting GitHub agar matriks Blacksmith dapat antre lebih awal |
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, shard ekstensi berbobot lebih rendah, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types`, dan `check-test-types` |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, shard pengujian Linux Node, shard pengujian plugin bawaan, `android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (cukup sensitif CPU sehingga 8 vCPU memakan biaya lebih besar daripada penghematannya); build Docker install-smoke (waktu antre 32-vCPU memakan biaya lebih besar daripada penghematannya) |
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
| `blacksmith-6vcpu-macos-latest` | `macos-node` pada `openclaw/openclaw`; fork fallback ke `macos-latest` |
| `blacksmith-12vcpu-macos-latest` | `macos-swift` pada `openclaw/openclaw`; fork fallback ke `macos-latest` |
| Runner | Job |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubuntu-24.04` | `preflight`, job keamanan cepat dan agregat (`security-scm-fast`, `security-dependency-audit`, `security-fast`), pemeriksaan protokol/kontrak/bawaan cepat, pemeriksaan kontrak channel yang di-shard, shard `check` kecuali lint, shard dan agregat `check-additional`, verifier agregat pengujian Node, pemeriksaan docs, Python skills, workflow-sanity, labeler, auto-response; preflight install-smoke juga menggunakan Ubuntu yang dihosting GitHub agar matriks Blacksmith bisa mengantre lebih awal |
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, shard ekstensi berbobot lebih ringan, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types`, dan `check-test-types` |
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, shard pengujian Linux Node, shard pengujian plugin bawaan, `android` |
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (cukup sensitif CPU sehingga 8 vCPU lebih mahal daripada penghematannya); build Docker install-smoke (biaya waktu antre 32-vCPU lebih mahal daripada penghematannya) |
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
| `blacksmith-6vcpu-macos-latest` | `macos-node` pada `openclaw/openclaw`; fork fallback ke `macos-latest` |
| `blacksmith-12vcpu-macos-latest` | `macos-swift` pada `openclaw/openclaw`; fork fallback ke `macos-latest` |
## Padanan Lokal
## Padanan lokal
```bash
pnpm changed:lanes # inspect the local changed-lane classifier for origin/main...HEAD
@ -137,7 +137,7 @@ pnpm perf:kova:summary --report .artifacts/kova/reports/mock-provider/report.jso
## Performa OpenClaw
`OpenClaw Performance` adalah workflow performa produk/runtime. Workflow ini berjalan setiap hari pada `main` dan dapat di-dispatch secara manual:
`OpenClaw Performance` adalah workflow performa produk/runtime. Workflow ini berjalan harian pada `main` dan dapat di-dispatch secara manual:
```bash
gh workflow run openclaw-performance.yml --ref main -f profile=diagnostic -f repeat=3
@ -145,27 +145,27 @@ gh workflow run openclaw-performance.yml --ref main -f profile=smoke -f repeat=1
gh workflow run openclaw-performance.yml --ref main -f target_ref=v2026.5.2 -f profile=diagnostic -f repeat=3
```
Dispatch manual biasanya melakukan benchmark terhadap ref workflow. Tetapkan `target_ref` untuk melakukan benchmark terhadap tag rilis atau branch lain dengan implementasi workflow saat ini. Path laporan yang diterbitkan dan pointer terbaru dikunci berdasarkan ref yang diuji, dan setiap `index.md` mencatat ref/SHA yang diuji, ref/SHA workflow, ref Kova, profil, mode auth lane, model, jumlah pengulangan, dan filter skenario.
Dispatch manual biasanya melakukan benchmark pada ref workflow. Atur `target_ref` untuk melakukan benchmark pada tag rilis atau branch lain dengan implementasi workflow saat ini. Path laporan yang dipublikasikan dan pointer terbaru diberi kunci berdasarkan ref yang diuji, dan setiap `index.md` mencatat ref/SHA yang diuji, ref/SHA workflow, ref Kova, profil, mode auth lane, model, jumlah pengulangan, dan filter skenario.
Workflow menginstal OCM dari rilis yang dipin dan Kova dari `openclaw/Kova` pada input `kova_ref` yang dipin, lalu menjalankan tiga lane:
- `mock-provider`: Skenario diagnostik Kova terhadap runtime build lokal dengan auth palsu kompatibel OpenAI yang deterministik.
- `mock-deep-profile`: Profiling CPU/heap/trace untuk hotspot startup, gateway, dan giliran agen.
- `live-gpt54`: Giliran agen OpenAI `openai/gpt-5.4` nyata, dilewati saat `OPENAI_API_KEY` tidak tersedia.
- `mock-provider`: skenario diagnostik Kova terhadap runtime build lokal dengan auth kompatibel OpenAI palsu yang deterministik.
- `mock-deep-profile`: profiling CPU/heap/trace untuk hotspot startup, gateway, dan agent-turn.
- `live-gpt54`: satu turn agen OpenAI `openai/gpt-5.4` nyata, dilewati ketika `OPENAI_API_KEY` tidak tersedia.
Lane mock-provider juga menjalankan probe sumber native OpenClaw setelah pass Kova: timing boot gateway dan memori pada kasus startup default, hook, dan 50-plugin; loop hello `channel-chat-baseline` mock-OpenAI berulang; dan perintah startup CLI terhadap gateway yang sudah boot. Ringkasan Markdown probe sumber berada di `source/index.md` dalam bundle laporan, dengan JSON mentah di sebelahnya.
Lane mock-provider juga menjalankan probe sumber asli OpenClaw setelah pass Kova: timing boot gateway dan memori pada kasus startup default, hook, dan 50-plugin; loop hello `channel-chat-baseline` mock-OpenAI berulang; serta perintah startup CLI terhadap gateway yang sudah di-boot. Ringkasan Markdown probe sumber berada di `source/index.md` dalam bundle laporan, dengan JSON mentah di sampingnya.
Setiap lane mengunggah artefak GitHub. Saat `CLAWGRIT_REPORTS_TOKEN` dikonfigurasi, workflow juga meng-commit `report.json`, `report.md`, bundle, `index.md`, dan artefak probe sumber ke `openclaw/clawgrit-reports` di bawah `openclaw-performance/<tested-ref>/<run-id>-<attempt>/<lane>/`. Pointer ref yang sedang diuji ditulis sebagai `openclaw-performance/<tested-ref>/latest-<lane>.json`.
Setiap lane mengunggah artefak GitHub. Ketika `CLAWGRIT_REPORTS_TOKEN` dikonfigurasi, workflow juga meng-commit `report.json`, `report.md`, bundle, `index.md`, dan artefak source-probe ke `openclaw/clawgrit-reports` di bawah `openclaw-performance/<tested-ref>/<run-id>-<attempt>/<lane>/`. Pointer ref teruji saat ini ditulis sebagai `openclaw-performance/<tested-ref>/latest-<lane>.json`.
## Validasi Rilis Penuh
`Full Release Validation` adalah workflow umbrella manual untuk "menjalankan semuanya sebelum rilis." Workflow ini menerima branch, tag, atau SHA commit penuh, men-dispatch workflow manual `CI` dengan target tersebut, men-dispatch `Plugin Prerelease` untuk bukti plugin/paket/statis/Docker khusus rilis, dan men-dispatch `OpenClaw Release Checks` untuk install smoke, penerimaan paket, suite jalur rilis Docker, live/E2E, OpenWebUI, paritas QA Lab, Matrix, dan lane Telegram. Dengan `rerun_group=all` dan `release_profile=full`, workflow ini juga menjalankan `NPM Telegram Beta E2E` terhadap artefak `release-package-under-test` dari pemeriksaan rilis. Setelah penerbitan, teruskan `npm_telegram_package_spec` untuk menjalankan ulang lane paket Telegram yang sama terhadap paket npm yang sudah diterbitkan.
`Full Release Validation` adalah workflow payung manual untuk "menjalankan semuanya sebelum rilis." Workflow ini menerima branch, tag, atau SHA commit penuh, men-dispatch workflow manual `CI` dengan target tersebut, men-dispatch `Plugin Prerelease` untuk pembuktian plugin/paket/statis/Docker khusus rilis, dan men-dispatch `OpenClaw Release Checks` untuk smoke install, penerimaan paket, pemeriksaan paket lintas OS, paritas QA Lab, Matrix, dan lane Telegram. Run stabil/default menjaga cakupan live/E2E dan jalur rilis Docker yang menyeluruh di balik `run_release_soak=true`; `release_profile=full` memaksa cakupan soak itu aktif agar validasi advisory luas tetap luas. Dengan `rerun_group=all` dan `release_profile=full`, workflow ini juga menjalankan `NPM Telegram Beta E2E` terhadap artefak `release-package-under-test` dari pemeriksaan rilis. Setelah publikasi, teruskan `npm_telegram_package_spec` untuk menjalankan ulang lane paket Telegram yang sama terhadap paket npm yang dipublikasikan.
Lihat [validasi rilis penuh](/id/reference/full-release-validation) untuk
matriks tahap, nama job workflow persis, perbedaan profil, artefak, dan
Lihat [Validasi rilis penuh](/id/reference/full-release-validation) untuk
matriks tahap, nama job workflow yang tepat, perbedaan profil, artefak, dan
handle rerun terfokus.
`OpenClaw Release Publish` adalah workflow rilis manual yang mengubah state. Dispatch dari `release/YYYY.M.D` atau `main` setelah tag rilis ada dan setelah preflight npm OpenClaw berhasil. Workflow ini memverifikasi `pnpm plugins:sync:check`, men-dispatch `Plugin NPM Release` untuk semua paket plugin yang dapat diterbitkan, men-dispatch `Plugin ClawHub Release` untuk SHA rilis yang sama, dan baru kemudian men-dispatch `OpenClaw NPM Release` dengan `preflight_run_id` yang disimpan.
`OpenClaw Release Publish` adalah workflow rilis manual yang mengubah keadaan. Dispatch dari `release/YYYY.M.D` atau `main` setelah tag rilis ada dan setelah preflight npm OpenClaw berhasil. Workflow ini memverifikasi `pnpm plugins:sync:check`, men-dispatch `Plugin NPM Release` untuk semua paket plugin yang dapat dipublikasikan, men-dispatch `Plugin ClawHub Release` untuk SHA rilis yang sama, dan baru kemudian men-dispatch `OpenClaw NPM Release` dengan `preflight_run_id` yang disimpan.
```bash
gh workflow run openclaw-release-publish.yml \
@ -182,38 +182,33 @@ Untuk bukti commit yang dipin pada branch yang bergerak cepat, gunakan helper al
pnpm ci:full-release --sha <full-sha>
```
Ref dispatch workflow GitHub harus berupa branch atau tag, bukan SHA commit mentah. Helper
mendorong branch sementara `release-ci/<sha>-...` pada SHA target,
men-dispatch `Full Release Validation` dari ref yang dipin tersebut, memverifikasi setiap
workflow turunan `headSha` cocok dengan target, dan menghapus branch sementara saat
run selesai. Verifier umbrella juga gagal jika workflow turunan mana pun berjalan pada
SHA yang berbeda.
Ref dispatch workflow GitHub harus berupa branch atau tag, bukan SHA commit mentah. Helper mendorong branch sementara `release-ci/<sha>-...` pada SHA target, men-dispatch `Full Release Validation` dari ref yang dipin itu, memverifikasi setiap `headSha` workflow anak cocok dengan target, dan menghapus branch sementara ketika run selesai. Verifier payung juga gagal jika ada workflow anak yang berjalan pada SHA berbeda.
`release_profile` mengontrol cakupan langsung/penyedia yang diteruskan ke pemeriksaan rilis. Alur kerja rilis manual default ke `stable`; gunakan `full` hanya saat Anda memang menginginkan matriks penasihat penyedia/media yang luas.
`release_profile` mengontrol cakupan live/penyedia yang diteruskan ke pemeriksaan rilis. Alur kerja rilis manual secara default menggunakan `stable`; gunakan `full` hanya ketika Anda sengaja menginginkan matriks penyedia/media advisori yang luas. `run_release_soak` mengontrol apakah pemeriksaan rilis stable/default menjalankan soak jalur rilis live/E2E dan Docker yang menyeluruh; `full` memaksa soak aktif.
- `minimum` mempertahankan jalur OpenAI/inti yang paling cepat dan kritis untuk rilis.
- `minimum` mempertahankan lane OpenAI/core paling cepat yang kritis untuk rilis.
- `stable` menambahkan set penyedia/backend stabil.
- `full` menjalankan matriks penasihat penyedia/media yang luas.
- `full` menjalankan matriks penyedia/media advisori yang luas.
Umbrella mencatat id proses anak yang dikirim, dan pekerjaan akhir `Verify full validation` memeriksa ulang kesimpulan proses anak saat ini serta menambahkan tabel pekerjaan paling lambat untuk setiap proses anak. Jika alur kerja anak dijalankan ulang dan menjadi hijau, jalankan ulang hanya pekerjaan pemverifikasi induk untuk menyegarkan hasil umbrella dan ringkasan waktunya.
Payung mencatat ID run anak yang didispatch, dan job final `Verify full validation` memeriksa ulang kesimpulan run anak saat ini dan menambahkan tabel job terlambat untuk setiap run anak. Jika alur kerja anak dijalankan ulang dan menjadi hijau, jalankan ulang hanya job verifier induk untuk menyegarkan hasil payung dan ringkasan waktunya.
Untuk pemulihan, `Full Release Validation` dan `OpenClaw Release Checks` sama-sama menerima `rerun_group`. Gunakan `all` untuk kandidat rilis, `ci` hanya untuk anak CI penuh normal, `plugin-prerelease` hanya untuk anak prarilis Plugin, `release-checks` untuk setiap anak rilis, atau grup yang lebih sempit: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live`, atau `npm-telegram` pada umbrella. Ini menjaga proses ulang kotak rilis yang gagal tetap terbatas setelah perbaikan terfokus.
Untuk pemulihan, baik `Full Release Validation` maupun `OpenClaw Release Checks` menerima `rerun_group`. Gunakan `all` untuk kandidat rilis, `ci` hanya untuk anak CI penuh normal, `plugin-prerelease` hanya untuk anak prarilis plugin, `release-checks` untuk setiap anak rilis, atau grup yang lebih sempit: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live`, atau `npm-telegram` pada payung. Ini menjaga agar rerun kotak rilis yang gagal tetap terbatas setelah perbaikan terfokus. Untuk satu lane cross-OS yang gagal, gabungkan `rerun_group=cross-os` dengan `cross_os_suite_filter`, misalnya `windows/packaged-upgrade`; perintah cross-OS yang panjang memancarkan baris Heartbeat dan ringkasan packaged-upgrade menyertakan timing per fase. Lane QA release-check bersifat advisori, jadi kegagalan khusus QA memberi peringatan tetapi tidak memblokir verifier release-check.
`OpenClaw Release Checks` menggunakan ref alur kerja tepercaya untuk menyelesaikan ref yang dipilih satu kali menjadi tarball `release-package-under-test`, lalu meneruskan artefak itu ke alur kerja Docker jalur rilis langsung/E2E dan shard penerimaan paket. Ini menjaga byte paket tetap konsisten di seluruh kotak rilis dan menghindari pengemasan ulang kandidat yang sama di beberapa pekerjaan anak.
`OpenClaw Release Checks` menggunakan ref alur kerja tepercaya untuk me-resolve ref terpilih satu kali menjadi tarball `release-package-under-test`, lalu meneruskan artefak itu ke pemeriksaan cross-OS dan Package Acceptance, ditambah alur kerja Docker jalur rilis live/E2E ketika cakupan soak berjalan. Ini menjaga byte paket tetap konsisten di seluruh kotak rilis dan menghindari pengemasan ulang kandidat yang sama di beberapa job anak.
Proses `Full Release Validation` duplikat untuk `ref=main` dan `rerun_group=all`
menggantikan umbrella yang lebih lama. Pemantau induk membatalkan setiap alur kerja anak yang
telah dikirim saat induk dibatalkan, sehingga validasi main yang lebih baru
tidak tertahan di belakang proses pemeriksaan rilis usang berdurasi dua jam. Validasi cabang/tag
rilis dan grup proses ulang terfokus mempertahankan `cancel-in-progress: false`.
Duplikat run `Full Release Validation` untuk `ref=main` dan `rerun_group=all`
menggantikan payung yang lebih lama. Monitor induk membatalkan alur kerja anak mana pun yang
telah didispatch ketika induk dibatalkan, sehingga validasi main yang lebih baru
tidak tertahan di belakang run release-check dua jam yang basi. Validasi branch/tag
rilis dan grup rerun terfokus mempertahankan `cancel-in-progress: false`.
## Shard Langsung dan E2E
## Shard Live dan E2E
Anak langsung/E2E rilis mempertahankan cakupan native `pnpm test:live` yang luas, tetapi menjalankannya sebagai shard bernama melalui `scripts/test-live-shard.mjs`, bukan sebagai satu pekerjaan serial:
Anak live/E2E rilis mempertahankan cakupan native `pnpm test:live` yang luas, tetapi menjalankannya sebagai shard bernama melalui `scripts/test-live-shard.mjs` alih-alih satu job serial:
- `native-live-src-agents`
- `native-live-src-gateway-core`
- pekerjaan `native-live-src-gateway-profiles` yang difilter penyedia
- job `native-live-src-gateway-profiles` yang difilter berdasarkan penyedia
- `native-live-src-gateway-backends`
- `native-live-test`
- `native-live-extensions-a-k`
@ -221,61 +216,61 @@ Anak langsung/E2E rilis mempertahankan cakupan native `pnpm test:live` yang luas
- `native-live-extensions-openai`
- `native-live-extensions-o-z-other`
- `native-live-extensions-xai`
- shard audio/video media terpisah dan shard musik yang difilter penyedia
- shard audio/video media terpisah dan shard musik yang difilter berdasarkan penyedia
Ini mempertahankan cakupan file yang sama sekaligus membuat kegagalan penyedia langsung yang lambat lebih mudah dijalankan ulang dan didiagnosis. Nama shard agregat `native-live-extensions-o-z`, `native-live-extensions-media`, dan `native-live-extensions-media-music` tetap valid untuk proses ulang sekali jalan secara manual.
Ini mempertahankan cakupan file yang sama sambil membuat kegagalan penyedia live yang lambat lebih mudah dijalankan ulang dan didiagnosis. Nama shard agregat `native-live-extensions-o-z`, `native-live-extensions-media`, dan `native-live-extensions-media-music` tetap valid untuk rerun sekali jalan manual.
Shard media langsung native berjalan di `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, yang dibangun oleh alur kerja `Live Media Runner Image`. Image itu memasang `ffmpeg` dan `ffprobe` terlebih dahulu; pekerjaan media hanya memverifikasi biner sebelum penyiapan. Pertahankan suite langsung berbasis Docker pada runner Blacksmith normal — pekerjaan container bukan tempat yang tepat untuk meluncurkan pengujian Docker bersarang.
Shard media live native berjalan di `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, yang dibangun oleh alur kerja `Live Media Runner Image`. Image itu sudah memasang `ffmpeg` dan `ffprobe`; job media hanya memverifikasi biner sebelum setup. Pertahankan suite live berbasis Docker pada runner Blacksmith normal — job container adalah tempat yang salah untuk meluncurkan pengujian Docker bertingkat.
Shard model/backend langsung berbasis Docker menggunakan image bersama terpisah `ghcr.io/openclaw/openclaw-live-test:<sha>` per commit yang dipilih. Alur kerja rilis langsung membangun dan mendorong image itu satu kali, lalu shard model langsung Docker, Gateway yang di-shard menurut penyedia, backend CLI, bind ACP, dan harness Codex berjalan dengan `OPENCLAW_SKIP_DOCKER_BUILD=1`. Shard Docker Gateway membawa batas `timeout` tingkat skrip eksplisit di bawah batas waktu pekerjaan alur kerja, sehingga container yang macet atau jalur pembersihan gagal cepat alih-alih menghabiskan seluruh anggaran pemeriksaan rilis. Jika shard tersebut membangun ulang target Docker sumber penuh secara independen, proses rilis salah konfigurasi dan akan membuang waktu pada build image duplikat.
Shard model/backend live berbasis Docker menggunakan image bersama terpisah `ghcr.io/openclaw/openclaw-live-test:<sha>` per commit terpilih. Alur kerja rilis live membangun dan mendorong image itu sekali, lalu shard model live Docker, gateway yang di-shard per penyedia, backend CLI, bind ACP, dan harness Codex berjalan dengan `OPENCLAW_SKIP_DOCKER_BUILD=1`. Shard Gateway Docker membawa batas `timeout` eksplisit di level skrip di bawah timeout job alur kerja sehingga container yang macet atau jalur cleanup gagal cepat alih-alih menghabiskan seluruh anggaran release-check. Jika shard tersebut membangun ulang target Docker sumber penuh secara independen, run rilis salah konfigurasi dan akan membuang waktu dinding pada build image duplikat.
## Penerimaan Paket
## Package Acceptance
Gunakan `Package Acceptance` saat pertanyaannya adalah "apakah paket OpenClaw yang dapat diinstal ini berfungsi sebagai produk?" Ini berbeda dari CI normal: CI normal memvalidasi pohon sumber, sedangkan penerimaan paket memvalidasi satu tarball melalui harness Docker E2E yang sama dengan yang digunakan pengguna setelah memasang atau memperbarui.
Gunakan `Package Acceptance` ketika pertanyaannya adalah "apakah paket OpenClaw yang dapat diinstal ini berfungsi sebagai produk?" Ini berbeda dari CI normal: CI normal memvalidasi pohon sumber, sedangkan package acceptance memvalidasi satu tarball melalui harness Docker E2E yang sama yang dijalankan pengguna setelah instalasi atau pembaruan.
### Pekerjaan
### Job
1. `resolve_package` melakukan checkout `workflow_ref`, menyelesaikan satu kandidat paket, menulis `.artifacts/docker-e2e-package/openclaw-current.tgz`, menulis `.artifacts/docker-e2e-package/package-candidate.json`, mengunggah keduanya sebagai artefak `package-under-test`, dan mencetak sumber, ref alur kerja, ref paket, versi, SHA-256, dan profil dalam ringkasan langkah GitHub.
2. `docker_acceptance` memanggil `openclaw-live-and-e2e-checks-reusable.yml` dengan `ref=workflow_ref` dan `package_artifact_name=package-under-test`. Alur kerja reusable mengunduh artefak itu, memvalidasi inventaris tarball, menyiapkan image Docker digest paket bila diperlukan, dan menjalankan jalur Docker yang dipilih terhadap paket tersebut alih-alih mengemas checkout alur kerja. Saat sebuah profil memilih beberapa `docker_lanes` bertarget, alur kerja reusable menyiapkan paket dan image bersama satu kali, lalu menyebarkan jalur tersebut sebagai pekerjaan Docker bertarget paralel dengan artefak unik.
3. `package_telegram` secara opsional memanggil `NPM Telegram Beta E2E`. Ini berjalan saat `telegram_mode` bukan `none` dan memasang artefak `package-under-test` yang sama saat Penerimaan Paket menyelesaikannya; dispatch Telegram mandiri masih dapat memasang spesifikasi npm yang diterbitkan.
4. `summary` menggagalkan alur kerja jika penyelesaian paket, penerimaan Docker, atau jalur Telegram opsional gagal.
1. `resolve_package` melakukan checkout `workflow_ref`, me-resolve satu kandidat paket, menulis `.artifacts/docker-e2e-package/openclaw-current.tgz`, menulis `.artifacts/docker-e2e-package/package-candidate.json`, mengunggah keduanya sebagai artefak `package-under-test`, dan mencetak sumber, ref alur kerja, ref paket, versi, SHA-256, dan profil di ringkasan langkah GitHub.
2. `docker_acceptance` memanggil `openclaw-live-and-e2e-checks-reusable.yml` dengan `ref=workflow_ref` dan `package_artifact_name=package-under-test`. Alur kerja reusable mengunduh artefak itu, memvalidasi inventaris tarball, menyiapkan image Docker package-digest bila diperlukan, dan menjalankan lane Docker terpilih terhadap paket itu alih-alih mengemas checkout alur kerja. Ketika profil memilih beberapa `docker_lanes` tertarget, alur kerja reusable menyiapkan paket dan image bersama satu kali, lalu menyebarkan lane tersebut sebagai job Docker tertarget paralel dengan artefak unik.
3. `package_telegram` secara opsional memanggil `NPM Telegram Beta E2E`. Ini berjalan ketika `telegram_mode` bukan `none` dan memasang artefak `package-under-test` yang sama ketika Package Acceptance me-resolve satu; dispatch Telegram mandiri masih dapat memasang spesifikasi npm yang sudah dipublikasikan.
4. `summary` menggagalkan alur kerja jika resolusi paket, Docker acceptance, atau lane Telegram opsional gagal.
### Sumber Kandidat
### Sumber kandidat
- `source=npm` hanya menerima `openclaw@beta`, `openclaw@latest`, atau versi rilis OpenClaw yang persis seperti `openclaw@2026.4.27-beta.2`. Gunakan ini untuk penerimaan prarilis/stabil yang telah diterbitkan.
- `source=ref` mengemas cabang, tag, atau SHA commit penuh `package_ref` tepercaya. Resolver mengambil cabang/tag OpenClaw, memverifikasi commit yang dipilih dapat dijangkau dari riwayat cabang repositori atau tag rilis, memasang dependensi dalam worktree terlepas, dan mengemasnya dengan `scripts/package-openclaw-for-docker.mjs`.
- `source=npm` hanya menerima `openclaw@beta`, `openclaw@latest`, atau versi rilis OpenClaw persis seperti `openclaw@2026.4.27-beta.2`. Gunakan ini untuk acceptance prarilis/stable yang sudah dipublikasikan.
- `source=ref` mengemas branch, tag, atau SHA commit lengkap `package_ref` tepercaya. Resolver mengambil branch/tag OpenClaw, memverifikasi commit terpilih dapat dijangkau dari riwayat branch repositori atau tag rilis, memasang dependensi di worktree terlepas, dan mengemasnya dengan `scripts/package-openclaw-for-docker.mjs`.
- `source=url` mengunduh `.tgz` HTTPS; `package_sha256` wajib.
- `source=artifact` mengunduh satu `.tgz` dari `artifact_run_id` dan `artifact_name`; `package_sha256` opsional tetapi sebaiknya diberikan untuk artefak yang dibagikan secara eksternal.
Pisahkan `workflow_ref` dan `package_ref`. `workflow_ref` adalah kode alur kerja/harness tepercaya yang menjalankan pengujian. `package_ref` adalah commit sumber yang dikemas saat `source=ref`. Ini memungkinkan harness pengujian saat ini memvalidasi commit sumber tepercaya yang lebih lama tanpa menjalankan logika alur kerja lama.
Pisahkan `workflow_ref` dan `package_ref`. `workflow_ref` adalah kode alur kerja/harness tepercaya yang menjalankan pengujian. `package_ref` adalah commit sumber yang dikemas ketika `source=ref`. Ini memungkinkan harness pengujian saat ini memvalidasi commit sumber tepercaya yang lebih lama tanpa menjalankan logika alur kerja lama.
### Profil Suite
### Profil suite
- `smoke` — `npm-onboard-channel-agent`, `gateway-network`, `config-reload`
- `package` — `npm-onboard-channel-agent`, `doctor-switch`, `update-channel-switch`, `upgrade-survivor`, `published-upgrade-survivor`, `plugins-offline`, `plugin-update`
- `product` — `package` plus `mcp-channels`, `cron-mcp-cleanup`, `openai-web-search-minimal`, `openwebui`
- `full` — potongan jalur rilis Docker penuh dengan OpenWebUI
- `custom` — `docker_lanes` persis; wajib saat `suite_profile=custom`
- `product` — `package` ditambah `mcp-channels`, `cron-mcp-cleanup`, `openai-web-search-minimal`, `openwebui`
- `full` — chunk jalur rilis Docker penuh dengan OpenWebUI
- `custom` — `docker_lanes` persis; wajib ketika `suite_profile=custom`
Profil `package` menggunakan cakupan Plugin offline sehingga validasi paket yang diterbitkan tidak bergantung pada ketersediaan ClawHub langsung. Jalur Telegram opsional menggunakan kembali artefak `package-under-test` di `NPM Telegram Beta E2E`, dengan jalur spesifikasi npm yang diterbitkan tetap dipertahankan untuk dispatch mandiri.
Profil `package` menggunakan cakupan plugin offline sehingga validasi paket yang dipublikasikan tidak bergantung pada ketersediaan live ClawHub. Lane Telegram opsional menggunakan ulang artefak `package-under-test` di `NPM Telegram Beta E2E`, dengan jalur spesifikasi npm yang dipublikasikan tetap dipertahankan untuk dispatch mandiri.
Untuk kebijakan pembaruan dan pengujian Plugin khusus, termasuk perintah lokal,
jalur Docker, input Penerimaan Paket, default rilis, dan triase kegagalan,
lihat [Menguji pembaruan dan Plugin](/id/help/testing-updates-plugins).
Untuk kebijakan pengujian pembaruan dan plugin khusus, termasuk perintah lokal,
lane Docker, input Package Acceptance, default rilis, dan triase kegagalan,
lihat [Menguji pembaruan dan plugin](/id/help/testing-updates-plugins).
Pemeriksaan rilis memanggil Penerimaan Paket dengan `source=artifact`, artefak paket rilis yang disiapkan, `suite_profile=custom`, `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`, `published_upgrade_survivor_baselines=all-since-2026.4.23`, `published_upgrade_survivor_scenarios=reported-issues`, dan `telegram_mode=mock-openai`. Ini menjaga migrasi paket, pembaruan, pembersihan dependensi Plugin usang, perbaikan pemasangan Plugin yang dikonfigurasi, Plugin offline, pembaruan Plugin, dan bukti Telegram pada tarball paket terselesaikan yang sama. Atur `package_acceptance_package_spec` pada Full Release Validation atau OpenClaw Release Checks untuk menjalankan matriks yang sama terhadap paket npm yang telah dikirim, bukan artefak yang dibangun dari SHA. Pemeriksaan rilis lintas-OS tetap mencakup onboarding, installer, dan perilaku platform khusus OS; validasi produk paket/pembaruan harus dimulai dengan Penerimaan Paket. Jalur Docker `published-upgrade-survivor` memvalidasi satu baseline paket yang diterbitkan per proses. Dalam Penerimaan Paket, tarball `package-under-test` yang diselesaikan selalu menjadi kandidat dan `published_upgrade_survivor_baseline` memilih baseline terbitan fallback, dengan default `openclaw@latest`; perintah proses ulang jalur gagal mempertahankan baseline itu. Atur `published_upgrade_survivor_baselines=all-since-2026.4.23` untuk memperluas CI Rilis Penuh ke setiap rilis npm stabil dari `2026.4.23` hingga `latest`; `release-history` tetap tersedia untuk pengambilan sampel manual yang lebih luas dengan jangkar tanggal lama. Atur `published_upgrade_survivor_scenarios=reported-issues` untuk memperluas baseline yang sama ke seluruh fixture berbentuk isu untuk konfigurasi Feishu, file bootstrap/persona yang dipertahankan, pemasangan Plugin OpenClaw yang dikonfigurasi, jalur log tilde, dan root dependensi Plugin lama yang usang. Alur kerja terpisah `Update Migration` menggunakan jalur Docker `update-migration` dengan `all-since-2026.4.23` dan `plugin-deps-cleanup` saat pertanyaannya adalah pembersihan pembaruan terbitan yang menyeluruh, bukan cakupan CI Rilis Penuh normal. Proses agregat lokal dapat meneruskan spesifikasi paket persis dengan `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS`, mempertahankan satu jalur dengan `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` seperti `openclaw@2026.4.15`, atau mengatur `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` untuk matriks skenario. Jalur terbitan mengonfigurasi baseline dengan resep perintah `openclaw config set` yang sudah dipanggang, mencatat langkah resep di `summary.json`, dan memeriksa `/healthz`, `/readyz`, plus status RPC setelah Gateway dimulai. Jalur paket Windows dan installer baru juga memverifikasi bahwa paket terpasang dapat mengimpor override kontrol browser dari jalur Windows absolut mentah. Smoke giliran agen lintas-OS OpenAI menggunakan default `OPENCLAW_CROSS_OS_OPENAI_MODEL` saat disetel, jika tidak `openai/gpt-5.4`, sehingga bukti pemasangan dan Gateway tetap memakai model pengujian GPT-5 sambil menghindari default GPT-4.x.
Release checks memanggil Package Acceptance dengan `source=artifact`, artefak paket rilis yang disiapkan, `suite_profile=custom`, `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`, dan `telegram_mode=mock-openai`. Ini menjaga bukti migrasi paket, pembaruan, cleanup dependensi plugin basi, perbaikan instal plugin terkonfigurasi, plugin offline, plugin-update, dan Telegram pada tarball paket terselesaikan yang sama. Setel `package_acceptance_package_spec` pada Full Release Validation atau OpenClaw Release Checks untuk menjalankan matriks yang sama terhadap paket npm yang sudah dikirim alih-alih artefak yang dibangun dari SHA. Pemeriksaan rilis cross-OS tetap mencakup onboarding spesifik OS, installer, dan perilaku platform; validasi produk paket/pembaruan harus dimulai dengan Package Acceptance. Lane Docker `published-upgrade-survivor` memvalidasi satu baseline paket yang dipublikasikan per run di jalur rilis pemblokir. Dalam Package Acceptance, tarball `package-under-test` yang di-resolve selalu menjadi kandidat dan `published_upgrade_survivor_baseline` memilih baseline publikasi fallback, default ke `openclaw@latest`; perintah rerun lane gagal mempertahankan baseline tersebut. Full Release Validation dengan `run_release_soak=true` atau `release_profile=full` menyetel `published_upgrade_survivor_baselines=all-since-2026.4.23` dan `published_upgrade_survivor_scenarios=reported-issues` untuk memperluas ke setiap rilis npm stable dari `2026.4.23` hingga `latest` dan fixture berbentuk isu untuk konfigurasi Feishu, file bootstrap/persona yang dipertahankan, instal plugin OpenClaw terkonfigurasi, jalur log tilde, dan root dependensi plugin legacy yang basi. Alur kerja `Update Migration` terpisah menggunakan lane Docker `update-migration` dengan `all-since-2026.4.23` dan `plugin-deps-cleanup` ketika pertanyaannya adalah cleanup pembaruan publikasi yang menyeluruh, bukan cakupan CI Full Release normal. Run agregat lokal dapat meneruskan spesifikasi paket persis dengan `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS`, mempertahankan satu lane dengan `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` seperti `openclaw@2026.4.15`, atau menyetel `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` untuk matriks skenario. Lane publikasi mengonfigurasi baseline dengan resep perintah `openclaw config set` yang sudah dibaked, mencatat langkah resep di `summary.json`, dan memeriksa `/healthz`, `/readyz`, plus status RPC setelah Gateway mulai. Lane fresh Windows packaged dan installer juga memverifikasi bahwa paket terinstal dapat mengimpor override browser-control dari jalur Windows absolut mentah. Smoke agent-turn cross-OS OpenAI default ke `OPENCLAW_CROSS_OS_OPENAI_MODEL` ketika disetel, jika tidak `openai/gpt-5.4`, sehingga bukti instalasi dan gateway tetap menggunakan model pengujian GPT-5 sambil menghindari default GPT-4.x.
### Jendela Kompatibilitas Lama
### Jendela kompatibilitas legacy
Penerimaan Paket memiliki jendela kompatibilitas lama yang terbatas untuk paket yang sudah diterbitkan. Paket hingga `2026.4.25`, termasuk `2026.4.25-beta.*`, dapat menggunakan jalur kompatibilitas:
Package Acceptance memiliki jendela kompatibilitas legacy terbatas untuk paket yang sudah dipublikasikan. Paket hingga `2026.4.25`, termasuk `2026.4.25-beta.*`, dapat menggunakan jalur kompatibilitas:
- entri QA privat yang diketahui dalam `dist/postinstall-inventory.json` dapat mengarah ke file yang dihilangkan dari tarball;
- `doctor-switch` dapat melewati subkasus persistensi `gateway install --wrapper` saat paket tidak mengekspos flag tersebut;
- `update-channel-switch` dapat memangkas `pnpm.patchedDependencies` yang hilang dari fixture git palsu turunan tarball dan dapat mencatat `update.channel` persisten yang hilang;
- smoke Plugin dapat membaca lokasi catatan pemasangan lama atau menerima persistensi catatan pemasangan marketplace yang hilang;
- `plugin-update` dapat mengizinkan migrasi metadata konfigurasi sambil tetap mewajibkan catatan pemasangan dan perilaku tanpa pemasangan ulang tetap tidak berubah.
- entri QA privat yang diketahui di `dist/postinstall-inventory.json` dapat mengarah ke file yang dihilangkan dari tarball;
- `doctor-switch` dapat melewati subkasus persistensi `gateway install --wrapper` ketika paket tidak mengekspos flag tersebut;
- `update-channel-switch` dapat memangkas `pnpm.patchedDependencies` yang hilang dari fixture git palsu turunan tarball dan dapat mencatat `update.channel` tersimpan yang hilang;
- smoke plugin dapat membaca lokasi install-record legacy atau menerima persistensi install-record marketplace yang hilang;
- `plugin-update` dapat mengizinkan migrasi metadata konfigurasi sambil tetap mewajibkan install record dan perilaku tanpa-reinstall tetap tidak berubah.
Paket `2026.4.26` yang diterbitkan juga dapat memperingatkan untuk file cap metadata build lokal yang sudah dikirim. Paket yang lebih baru harus memenuhi kontrak modern; kondisi yang sama gagal alih-alih memperingatkan atau melewati.
Paket `2026.4.26` yang dipublikasikan juga dapat memperingatkan untuk file cap metadata build lokal yang sudah dikirim. Paket setelahnya harus memenuhi kontrak modern; kondisi yang sama gagal alih-alih memperingatkan atau melewati.
### Contoh
@ -318,18 +313,18 @@ gh workflow run package-acceptance.yml \
-f docker_lanes='install-e2e plugin-update'
```
Saat men-debug proses penerimaan paket yang gagal, mulai dari ringkasan `resolve_package` untuk mengonfirmasi sumber paket, versi, dan SHA-256. Lalu periksa proses turunan `docker_acceptance` dan artefak Docker-nya: `.artifacts/docker-tests/**/summary.json`, `failures.json`, log lane, pengaturan waktu fase, dan perintah rerun. Lebih baik menjalankan ulang profil paket yang gagal atau lane Docker persisnya daripada menjalankan ulang validasi rilis penuh.
Saat men-debug eksekusi package acceptance yang gagal, mulai dari ringkasan `resolve_package` untuk mengonfirmasi sumber paket, versi, dan SHA-256. Lalu periksa eksekusi turunan `docker_acceptance` dan artefak Docker-nya: `.artifacts/docker-tests/**/summary.json`, `failures.json`, log lane, timing fase, dan perintah eksekusi ulang. Utamakan menjalankan ulang profil paket yang gagal atau lane Docker yang persis, bukan menjalankan ulang validasi rilis penuh.
## Smoke instalasi
## Install smoke
Workflow `Install Smoke` yang terpisah menggunakan kembali skrip cakupan yang sama melalui job `preflight` miliknya sendiri. Workflow ini membagi cakupan smoke menjadi `run_fast_install_smoke` dan `run_full_install_smoke`.
Workflow `Install Smoke` terpisah menggunakan ulang skrip cakupan yang sama melalui job `preflight` miliknya. Ini membagi cakupan smoke menjadi `run_fast_install_smoke` dan `run_full_install_smoke`.
- **Jalur cepat** berjalan untuk pull request yang menyentuh permukaan Docker/paket, perubahan paket/manifest Plugin yang dibundel, atau permukaan inti Plugin/channel/gateway/Plugin SDK yang diuji oleh job smoke Docker. Perubahan Plugin bundel yang hanya menyentuh sumber, edit khusus pengujian, dan edit khusus dokumentasi tidak memesan worker Docker. Jalur cepat membangun image Dockerfile root satu kali, memeriksa CLI, menjalankan smoke CLI agents delete shared-workspace, menjalankan e2e gateway-network container, memverifikasi argumen build ekstensi bundel, dan menjalankan profil Docker Plugin bundel terbatas di bawah timeout perintah agregat 240 detik (setiap proses Docker skenario dibatasi secara terpisah).
- **Jalur penuh** mempertahankan instalasi paket QR dan cakupan Docker/update installer untuk proses terjadwal malam hari, dispatch manual, pemeriksaan rilis workflow-call, dan pull request yang benar-benar menyentuh permukaan installer/paket/Docker. Dalam mode penuh, install-smoke menyiapkan atau menggunakan kembali satu image smoke Dockerfile root GHCR target-SHA, lalu menjalankan instalasi paket QR, smoke Dockerfile root/gateway, smoke installer/update, dan E2E Docker Plugin bundel cepat sebagai job terpisah agar pekerjaan installer tidak menunggu di belakang smoke image root.
- **Jalur cepat** berjalan untuk pull request yang menyentuh permukaan Docker/paket, perubahan paket/manifes plugin bawaan, atau permukaan plugin/channel/gateway inti/Plugin SDK yang diuji oleh job Docker smoke. Perubahan plugin bawaan yang hanya source, edit hanya test, dan edit hanya docs tidak memesan worker Docker. Jalur cepat membangun image Dockerfile root satu kali, memeriksa CLI, menjalankan smoke CLI agents delete shared-workspace, menjalankan e2e gateway-network kontainer, memverifikasi arg build extension bawaan, dan menjalankan profil Docker plugin bawaan terbatas di bawah timeout perintah agregat 240 detik (setiap Docker run skenario dibatasi secara terpisah).
- **Jalur penuh** mempertahankan cakupan instal paket QR dan Docker/update installer untuk eksekusi terjadwal malam, dispatch manual, pemeriksaan rilis workflow-call, dan pull request yang benar-benar menyentuh permukaan installer/paket/Docker. Dalam mode penuh, install-smoke menyiapkan atau menggunakan ulang satu image smoke Dockerfile root GHCR target-SHA, lalu menjalankan instal paket QR, smoke Dockerfile/Gateway root, smoke installer/update, dan E2E Docker plugin bawaan cepat sebagai job terpisah agar pekerjaan installer tidak menunggu di belakang smoke image root.
Push ke `main` (termasuk commit merge) tidak memaksa jalur penuh; ketika logika cakupan perubahan akan meminta cakupan penuh pada push, workflow mempertahankan smoke Docker cepat dan menyerahkan smoke instalasi penuh ke validasi malam hari atau rilis.
Push `main` (termasuk merge commit) tidak memaksa jalur penuh; ketika logika changed-scope akan meminta cakupan penuh pada push, workflow mempertahankan Docker smoke cepat dan menyerahkan install smoke penuh ke validasi malam atau rilis.
Smoke image-provider instalasi global Bun yang lambat digate secara terpisah oleh `run_bun_global_install_smoke`. Ini berjalan pada jadwal malam hari dan dari workflow pemeriksaan rilis, dan dispatch manual `Install Smoke` dapat ikut mengaktifkannya, tetapi pull request dan push ke `main` tidak. Pengujian Docker QR dan installer mempertahankan Dockerfile yang berfokus pada instalasi masing-masing.
Smoke image-provider instal global Bun yang lambat digate secara terpisah oleh `run_bun_global_install_smoke`. Ini berjalan pada jadwal malam dan dari workflow pemeriksaan rilis, dan dispatch manual `Install Smoke` dapat ikut mengaktifkannya, tetapi pull request dan push `main` tidak. Test Docker QR dan installer mempertahankan Dockerfile yang berfokus pada instal milik mereka sendiri.
## E2E Docker Lokal
@ -338,40 +333,40 @@ Smoke image-provider instalasi global Bun yang lambat digate secara terpisah ole
- runner Node/Git polos untuk lane installer/update/plugin-dependency;
- image fungsional yang menginstal tarball yang sama ke `/app` untuk lane fungsionalitas normal.
Definisi lane Docker berada di `scripts/lib/docker-e2e-scenarios.mjs`, logika planner berada di `scripts/lib/docker-e2e-plan.mjs`, dan runner hanya menjalankan rencana yang dipilih. Scheduler memilih image per lane dengan `OPENCLAW_DOCKER_E2E_BARE_IMAGE` dan `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, lalu menjalankan lane dengan `OPENCLAW_SKIP_DOCKER_BUILD=1`.
Definisi lane Docker berada di `scripts/lib/docker-e2e-scenarios.mjs`, logika planner berada di `scripts/lib/docker-e2e-plan.mjs`, dan runner hanya mengeksekusi plan yang dipilih. Scheduler memilih image per lane dengan `OPENCLAW_DOCKER_E2E_BARE_IMAGE` dan `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, lalu menjalankan lane dengan `OPENCLAW_SKIP_DOCKER_BUILD=1`.
### Penyetelan
### Yang Dapat Disetel
| Variabel | Default | Tujuan |
| Variabel | Default | Tujuan |
| -------------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Jumlah slot pool utama untuk lane normal. |
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Jumlah slot pool ekor yang sensitif terhadap penyedia. |
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Batas lane live serentak agar penyedia tidak melakukan throttle. |
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Batas lane instalasi npm serentak. |
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Batas lane multi-layanan serentak. |
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Jeda bertahap antar-start lane untuk menghindari badai create daemon Docker; setel `0` untuk tanpa jeda. |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Timeout fallback per lane (120 menit); lane live/ekor terpilih memakai batas yang lebih ketat. |
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` mencetak rencana scheduler tanpa menjalankan lane. |
| `OPENCLAW_DOCKER_ALL_LANES` | unset | Daftar lane persis yang dipisahkan koma; melewati smoke pembersihan agar agen dapat mereproduksi satu lane yang gagal. |
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Jumlah slot main-pool untuk lane normal. |
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Jumlah slot tail-pool yang sensitif terhadap provider. |
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Batas lane live bersamaan agar provider tidak melakukan throttle. |
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Batas lane instal npm bersamaan. |
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Batas lane multi-service bersamaan. |
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Jeda antar-start lane untuk menghindari lonjakan create daemon Docker; setel `0` untuk tanpa jeda. |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Timeout fallback per lane (120 menit); lane live/tail terpilih memakai batas yang lebih ketat. |
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` mencetak plan scheduler tanpa menjalankan lane. |
| `OPENCLAW_DOCKER_ALL_LANES` | unset | Daftar lane persis yang dipisahkan koma; melewati smoke cleanup agar agent dapat mereproduksi satu lane gagal. |
Lane yang lebih berat daripada batas efektifnya masih dapat dimulai dari pool kosong, lalu berjalan sendiri sampai melepaskan kapasitas. Preflight agregat lokal memeriksa Docker, menghapus container E2E OpenClaw yang basi, memancarkan status lane aktif, menyimpan pengaturan waktu lane untuk pengurutan terlama lebih dulu, dan secara default berhenti menjadwalkan lane pool baru setelah kegagalan pertama.
Lane yang lebih berat dari batas efektifnya tetap dapat dimulai dari pool kosong, lalu berjalan sendiri sampai melepas kapasitas. Agregat lokal melakukan preflight Docker, menghapus kontainer E2E OpenClaw usang, mengeluarkan status lane aktif, menyimpan timing lane untuk pengurutan longest-first, dan secara default berhenti menjadwalkan lane pooled baru setelah kegagalan pertama.
### Workflow live/E2E yang dapat digunakan kembali
### Workflow live/E2E yang dapat digunakan ulang
Workflow live/E2E yang dapat digunakan kembali menanyakan `scripts/test-docker-all.mjs --plan-json` paket, jenis image, image live, lane, dan cakupan kredensial yang diperlukan. `scripts/docker-e2e.mjs` kemudian mengubah rencana itu menjadi output dan ringkasan GitHub. Workflow ini mengemas OpenClaw melalui `scripts/package-openclaw-for-docker.mjs`, mengunduh artefak paket dari proses saat ini, atau mengunduh artefak paket dari `package_artifact_run_id`; memvalidasi inventaris tarball; membangun dan mendorong image E2E Docker GHCR bare/fungsional bertag digest paket melalui cache layer Docker Blacksmith saat rencana membutuhkan lane dengan paket terinstal; dan menggunakan kembali input `docker_e2e_bare_image`/`docker_e2e_functional_image` yang disediakan atau image digest paket yang sudah ada alih-alih membangun ulang. Pull image Docker dicoba ulang dengan timeout terbatas 180 detik per percobaan agar stream registry/cache yang macet cepat dicoba ulang alih-alih menghabiskan sebagian besar jalur kritis CI.
Workflow live/E2E yang dapat digunakan ulang menanyakan `scripts/test-docker-all.mjs --plan-json` tentang paket, jenis image, image live, lane, dan cakupan kredensial yang dibutuhkan. `scripts/docker-e2e.mjs` lalu mengonversi plan itu menjadi output dan ringkasan GitHub. Ini mengemas OpenClaw melalui `scripts/package-openclaw-for-docker.mjs`, mengunduh artefak paket current-run, atau mengunduh artefak paket dari `package_artifact_run_id`; memvalidasi inventaris tarball; membangun dan mendorong image E2E Docker GHCR bare/functional bertag package-digest melalui cache layer Docker Blacksmith saat plan membutuhkan lane dengan paket terinstal; dan menggunakan ulang input `docker_e2e_bare_image`/`docker_e2e_functional_image` yang disediakan atau image package-digest yang sudah ada alih-alih membangun ulang. Pull image Docker dicoba ulang dengan timeout terbatas 180 detik per percobaan agar stream registry/cache yang macet cepat dicoba ulang, bukan menghabiskan sebagian besar jalur kritis CI.
### Chunk jalur rilis
Cakupan Docker rilis menjalankan job chunk yang lebih kecil dengan `OPENCLAW_SKIP_DOCKER_BUILD=1` sehingga setiap chunk hanya menarik jenis image yang dibutuhkannya dan menjalankan beberapa lane melalui scheduler berbobot yang sama:
Cakupan Docker rilis menjalankan job chunk yang lebih kecil dengan `OPENCLAW_SKIP_DOCKER_BUILD=1` sehingga setiap chunk hanya menarik jenis image yang dibutuhkan dan mengeksekusi beberapa lane melalui scheduler berbobot yang sama:
- `OPENCLAW_DOCKER_ALL_PROFILE=release-path`
- `OPENCLAW_DOCKER_ALL_CHUNK=core | package-update-openai | package-update-anthropic | package-update-core | plugins-runtime-plugins | plugins-runtime-services | plugins-runtime-install-a..h`
Chunk Docker rilis saat ini adalah `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services`, dan `plugins-runtime-install-a` hingga `plugins-runtime-install-h`. `plugins-runtime-core`, `plugins-runtime`, dan `plugins-integrations` tetap menjadi alias agregat Plugin/runtime. Alias lane `install-e2e` tetap menjadi alias rerun manual agregat untuk kedua lane installer penyedia.
Chunk Docker rilis saat ini adalah `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services`, dan `plugins-runtime-install-a` hingga `plugins-runtime-install-h`. `plugins-runtime-core`, `plugins-runtime`, dan `plugins-integrations` tetap menjadi alias agregat plugin/runtime. Alias lane `install-e2e` tetap menjadi alias eksekusi ulang manual agregat untuk kedua lane installer provider.
OpenWebUI digabungkan ke `plugins-runtime-services` ketika cakupan release-path penuh memintanya, dan mempertahankan chunk mandiri `openwebui` hanya untuk dispatch khusus OpenWebUI. Lane update channel bundel mencoba ulang satu kali untuk kegagalan jaringan npm sementara.
OpenWebUI digabungkan ke `plugins-runtime-services` ketika cakupan release-path penuh memintanya, dan mempertahankan chunk mandiri `openwebui` hanya untuk dispatch khusus OpenWebUI. Lane update bundled-channel mencoba ulang sekali untuk kegagalan jaringan npm sementara.
Setiap chunk mengunggah `.artifacts/docker-tests/` dengan log lane, pengaturan waktu, `summary.json`, `failures.json`, pengaturan waktu fase, JSON rencana scheduler, tabel lane lambat, dan perintah rerun per lane. Input `docker_lanes` workflow menjalankan lane terpilih terhadap image yang sudah disiapkan alih-alih job chunk, sehingga debug lane gagal tetap terbatas pada satu job Docker tertarget dan menyiapkan, mengunduh, atau menggunakan kembali artefak paket untuk proses tersebut; jika lane terpilih adalah lane Docker live, job tertarget membangun image live-test secara lokal untuk rerun itu. Perintah rerun GitHub per lane yang dihasilkan menyertakan `package_artifact_run_id`, `package_artifact_name`, dan input image yang disiapkan saat nilai tersebut ada, sehingga lane yang gagal dapat menggunakan kembali paket dan image persis dari proses yang gagal.
Setiap chunk mengunggah `.artifacts/docker-tests/` dengan log lane, timing, `summary.json`, `failures.json`, timing fase, JSON plan scheduler, tabel lane lambat, dan perintah eksekusi ulang per lane. Input workflow `docker_lanes` menjalankan lane terpilih terhadap image yang sudah disiapkan alih-alih job chunk, yang menjaga debugging lane gagal tetap terbatas pada satu job Docker tertarget dan menyiapkan, mengunduh, atau menggunakan ulang artefak paket untuk eksekusi itu; jika lane terpilih adalah lane Docker live, job tertarget membangun image live-test secara lokal untuk eksekusi ulang itu. Perintah eksekusi ulang GitHub per lane yang dihasilkan menyertakan `package_artifact_run_id`, `package_artifact_name`, dan input image yang sudah disiapkan saat nilai tersebut ada, sehingga lane gagal dapat menggunakan ulang paket dan image persis dari eksekusi yang gagal.
```bash
pnpm test:docker:rerun <run-id> # download Docker artifacts and print combined/per-lane targeted rerun commands
@ -380,48 +375,48 @@ pnpm test:docker:timings <summary> # slow-lane and phase critical-path summari
Workflow live/E2E terjadwal menjalankan suite Docker release-path penuh setiap hari.
## Prarilis Plugin
## Plugin Prarilis
`Plugin Prerelease` adalah cakupan produk/paket yang lebih mahal, jadi ini adalah workflow terpisah yang didispatch oleh `Full Release Validation` atau oleh operator eksplisit. Pull request normal, push ke `main`, dan dispatch CI manual mandiri menonaktifkan suite itu. Workflow ini menyeimbangkan pengujian Plugin bundel di delapan worker ekstensi; job shard ekstensi tersebut menjalankan hingga dua grup konfigurasi Plugin sekaligus dengan satu worker Vitest per grup dan heap Node yang lebih besar agar batch Plugin yang berat impor tidak membuat job CI tambahan. Jalur prarilis Docker khusus rilis mengelompokkan lane Docker tertarget dalam grup kecil untuk menghindari pemesanan puluhan runner bagi job berdurasi satu hingga tiga menit.
`Plugin Prerelease` adalah cakupan produk/paket yang lebih mahal, sehingga menjadi workflow terpisah yang didispatch oleh `Full Release Validation` atau oleh operator eksplisit. Pull request normal, push `main`, dan dispatch CI manual mandiri menonaktifkan suite tersebut. Ini menyeimbangkan test plugin bawaan di delapan worker extension; job shard extension tersebut menjalankan hingga dua grup config plugin sekaligus dengan satu worker Vitest per grup dan heap Node yang lebih besar agar batch plugin yang berat impor tidak membuat job CI tambahan. Jalur prarilis Docker khusus rilis membatch lane Docker tertarget dalam grup kecil untuk menghindari pemesanan puluhan runner untuk job berdurasi satu hingga tiga menit.
## Lab QA
## QA Lab
Lab QA memiliki lane CI khusus di luar workflow utama yang dicakup secara cerdas. Paritas agentik disarangkan di bawah harness QA dan rilis yang luas, bukan workflow PR mandiri. Gunakan `Full Release Validation` dengan `rerun_group=qa-parity` ketika paritas harus ikut dalam proses validasi luas.
QA Lab memiliki lane CI khusus di luar workflow smart-scoped utama. Paritas agentic bersarang di bawah harness QA dan rilis yang luas, bukan workflow PR mandiri. Gunakan `Full Release Validation` dengan `rerun_group=qa-parity` saat paritas harus ikut dalam eksekusi validasi luas.
- Workflow `QA-Lab - All Lanes` berjalan setiap malam pada `main` dan pada dispatch manual; workflow ini menyebarkan lane paritas mock, lane Matrix live, serta lane Telegram dan Discord live sebagai job paralel. Job live menggunakan environment `qa-live-shared`, dan Telegram/Discord menggunakan lease Convex.
- Workflow `QA-Lab - All Lanes` berjalan setiap malam pada `main` dan pada dispatch manual; ini menyebarkan lane paritas mock, lane Matrix live, serta lane Telegram dan Discord live sebagai job paralel. Job live menggunakan environment `qa-live-shared`, dan Telegram/Discord menggunakan lease Convex.
Pemeriksaan rilis menjalankan lane transport live Matrix dan Telegram dengan penyedia mock deterministik dan model yang memenuhi syarat mock (`mock-openai/gpt-5.5` dan `mock-openai/gpt-5.5-alt`) sehingga kontrak channel diisolasi dari latensi model live dan startup Plugin penyedia normal. Gateway transport live menonaktifkan pencarian memori karena paritas QA mencakup perilaku memori secara terpisah; konektivitas penyedia dicakup oleh suite model live, penyedia native, dan penyedia Docker yang terpisah.
Pemeriksaan rilis menjalankan lane transport live Matrix dan Telegram dengan provider mock deterministik dan model mock-qualified (`mock-openai/gpt-5.5` dan `mock-openai/gpt-5.5-alt`) sehingga kontrak channel terisolasi dari latensi model live dan startup plugin provider normal. Gateway transport live menonaktifkan pencarian memori karena paritas QA mencakup perilaku memori secara terpisah; konektivitas provider dicakup oleh suite model live, provider native, dan provider Docker yang terpisah.
Matrix menggunakan `--profile fast` untuk gate terjadwal dan rilis, menambahkan `--fail-fast` hanya ketika CLI yang di-checkout mendukungnya. Default CLI dan input workflow manual tetap `all`; dispatch manual `matrix_profile=all` selalu melakukan shard cakupan Matrix penuh ke job `transport`, `media`, `e2ee-smoke`, `e2ee-deep`, dan `e2ee-cli`.
Matrix menggunakan `--profile fast` untuk gate terjadwal dan rilis, menambahkan `--fail-fast` hanya ketika CLI yang di-checkout mendukungnya. Default CLI dan input workflow manual tetap `all`; dispatch manual `matrix_profile=all` selalu men-shard cakupan Matrix penuh menjadi job `transport`, `media`, `e2ee-smoke`, `e2ee-deep`, dan `e2ee-cli`.
`OpenClaw Release Checks` juga menjalankan lane Lab QA yang kritis untuk rilis sebelum persetujuan rilis; gate paritas QA-nya menjalankan paket kandidat dan baseline sebagai job lane paralel, lalu mengunduh kedua artefak ke job laporan kecil untuk perbandingan paritas akhir.
`OpenClaw Release Checks` juga menjalankan lane QA Lab yang kritis untuk rilis sebelum persetujuan rilis; gate paritas QA-nya menjalankan pack kandidat dan baseline sebagai job lane paralel, lalu mengunduh kedua artefak ke job laporan kecil untuk perbandingan paritas final.
Untuk PR normal, ikuti bukti CI/pemeriksaan tercakup alih-alih memperlakukan paritas sebagai status wajib.
Untuk PR normal, ikuti bukti CI/check bercakupan alih-alih memperlakukan paritas sebagai status wajib.
## CodeQL
Alur kerja `CodeQL` sengaja dibuat sebagai pemindai keamanan tahap awal yang sempit, bukan sapuan repositori penuh. Setiap hari, manual, dan pada guard pull request non-draf, pemindaian menjalankan kode workflow Actions ditambah permukaan JavaScript/TypeScript berisiko tertinggi dengan kueri keamanan berkeyakinan tinggi yang difilter ke `security-severity` tinggi/kritis.
Alur kerja `CodeQL` secara sengaja merupakan pemindai keamanan lintasan pertama yang sempit, bukan pemindaian seluruh repositori. Harian, manual, dan penjaga pull request non-draf memindai kode alur kerja Actions ditambah permukaan JavaScript/TypeScript berisiko tertinggi dengan kueri keamanan berkeyakinan tinggi yang difilter ke `security-severity` tinggi/kritis.
Guard pull request tetap ringan: guard ini hanya dimulai untuk perubahan di bawah `.github/actions`, `.github/codeql`, `.github/workflows`, `packages`, atau `src`, dan menjalankan matriks keamanan berkeyakinan tinggi yang sama seperti workflow terjadwal. CodeQL Android dan macOS tetap di luar default PR.
Penjaga pull request tetap ringan: ia hanya dimulai untuk perubahan di bawah `.github/actions`, `.github/codeql`, `.github/workflows`, `packages`, atau `src`, dan menjalankan matriks keamanan berkeyakinan tinggi yang sama seperti alur kerja terjadwal. CodeQL Android dan macOS tetap berada di luar default PR.
### Kategori keamanan
| Kategori | Permukaan |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-security-high/core-auth-secrets` | Auth, rahasia, sandbox, cron, dan baseline gateway |
| `/codeql-security-high/channel-runtime-boundary` | Kontrak implementasi channel inti ditambah runtime Plugin channel, Gateway, Plugin SDK, rahasia, titik sentuh audit |
| `/codeql-security-high/core-auth-secrets` | Auth, secret, sandbox, cron, dan baseline gateway |
| `/codeql-security-high/channel-runtime-boundary` | Kontrak implementasi channel inti ditambah runtime plugin channel, gateway, Plugin SDK, secret, titik sentuh audit |
| `/codeql-security-high/network-ssrf-boundary` | Permukaan kebijakan SSRF inti, parsing IP, penjaga jaringan, web-fetch, dan SSRF Plugin SDK |
| `/codeql-security-high/mcp-process-tool-boundary` | Server MCP, helper eksekusi proses, pengiriman keluar, dan gate eksekusi tool agen |
| `/codeql-security-high/plugin-trust-boundary` | Permukaan kepercayaan instalasi Plugin, loader, manifest, registry, instalasi package-manager, source-loading, dan kontrak paket Plugin SDK |
| `/codeql-security-high/mcp-process-tool-boundary` | Server MCP, helper eksekusi proses, pengiriman keluar, dan gerbang eksekusi tool agen |
| `/codeql-security-high/plugin-trust-boundary` | Permukaan kepercayaan instalasi Plugin, loader, manifes, registry, instalasi package-manager, pemuatan sumber, dan kontrak paket Plugin SDK |
### Shard keamanan khusus platform
- `CodeQL Android Critical Security` — shard keamanan Android terjadwal. Membangun aplikasi Android secara manual untuk CodeQL pada runner Blacksmith Linux terkecil yang diterima oleh sanity workflow. Mengunggah di bawah `/codeql-critical-security/android`.
- `CodeQL macOS Critical Security` — shard keamanan macOS mingguan/manual. Membangun aplikasi macOS secara manual untuk CodeQL di Blacksmith macOS, memfilter hasil build dependensi dari SARIF yang diunggah, dan mengunggah di bawah `/codeql-critical-security/macos`. Dipertahankan di luar default harian karena build macOS mendominasi runtime bahkan saat bersih.
- `CodeQL Android Critical Security` — shard keamanan Android terjadwal. Membangun aplikasi Android secara manual untuk CodeQL pada runner Blacksmith Linux terkecil yang diterima oleh kewarasan alur kerja. Mengunggah di bawah `/codeql-critical-security/android`.
- `CodeQL macOS Critical Security` — shard keamanan macOS mingguan/manual. Membangun aplikasi macOS secara manual untuk CodeQL di Blacksmith macOS, memfilter hasil build dependensi dari SARIF yang diunggah, dan mengunggah di bawah `/codeql-critical-security/macos`. Tetap berada di luar default harian karena build macOS mendominasi runtime bahkan saat bersih.
### Kategori Critical Quality
### Kategori Kualitas Kritis
`CodeQL Critical Quality` adalah shard non-keamanan yang sepadan. Ini hanya menjalankan kueri kualitas JavaScript/TypeScript non-keamanan dengan tingkat keparahan error di permukaan sempit bernilai tinggi pada runner Blacksmith Linux yang lebih kecil. Guard pull request-nya sengaja lebih kecil daripada profil terjadwal: PR non-draf hanya menjalankan shard `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract`, dan `plugin-sdk-reply-runtime` yang sesuai untuk perubahan pada kode eksekusi perintah/model/tool agen dan dispatch balasan, kode skema/migrasi/IO config, kode auth/rahasia/sandbox/keamanan, runtime channel inti dan Plugin channel bawaan, metode server/protokol gateway, runtime memori/perekat SDK, MCP/proses/pengiriman keluar, katalog model/runtime provider, antrean diagnostik/pengiriman sesi, loader Plugin, kontrak paket/Plugin SDK, atau runtime balasan Plugin SDK. Perubahan config CodeQL dan workflow kualitas menjalankan semua dua belas shard kualitas PR.
`CodeQL Critical Quality` adalah shard non-keamanan yang sepadan. Ia hanya menjalankan kueri kualitas JavaScript/TypeScript non-keamanan dengan tingkat keparahan error pada permukaan bernilai tinggi yang sempit di runner Blacksmith Linux yang lebih kecil. Penjaga pull request-nya sengaja lebih kecil daripada profil terjadwal: PR non-draf hanya menjalankan shard `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract`, dan `plugin-sdk-reply-runtime` yang sesuai untuk perubahan kode eksekusi perintah/model/tool agen dan dispatch balasan, kode skema/migrasi/IO config, kode auth/secret/sandbox/keamanan, channel inti dan runtime plugin channel bawaan, protokol/metode-server gateway, perekat runtime memori/SDK, MCP/proses/pengiriman keluar, katalog runtime/model provider, diagnostik sesi/antrean pengiriman, loader plugin, kontrak Plugin SDK/paket, atau runtime balasan Plugin SDK. Perubahan config CodeQL dan alur kerja kualitas menjalankan semua dua belas shard kualitas PR.
Dispatch manual menerima:
@ -433,36 +428,36 @@ Profil sempit adalah hook pengajaran/iterasi untuk menjalankan satu shard kualit
| Kategori | Permukaan |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-critical-quality/core-auth-secrets` | Auth, rahasia, sandbox, cron, dan kode batas keamanan gateway |
| `/codeql-critical-quality/config-boundary` | Skema config, migrasi, normalisasi, dan kontrak IO |
| `/codeql-critical-quality/core-auth-secrets` | Kode batas keamanan auth, secret, sandbox, cron, dan gateway |
| `/codeql-critical-quality/config-boundary` | Kontrak skema config, migrasi, normalisasi, dan IO |
| `/codeql-critical-quality/gateway-runtime-boundary` | Skema protokol Gateway dan kontrak metode server |
| `/codeql-critical-quality/channel-runtime-boundary` | Kontrak implementasi channel inti dan Plugin channel bawaan |
| `/codeql-critical-quality/agent-runtime-boundary` | Eksekusi perintah, dispatch model/provider, dispatch dan antrean auto-reply, serta kontrak runtime control-plane ACP |
| `/codeql-critical-quality/mcp-process-runtime-boundary` | Server MCP dan bridge tool, helper supervisi proses, serta kontrak pengiriman keluar |
| `/codeql-critical-quality/channel-runtime-boundary` | Kontrak implementasi channel inti dan plugin channel bawaan |
| `/codeql-critical-quality/agent-runtime-boundary` | Kontrak runtime eksekusi perintah, dispatch model/provider, dispatch dan antrean auto-reply, serta control-plane ACP |
| `/codeql-critical-quality/mcp-process-runtime-boundary` | Server MCP dan jembatan tool, helper supervisi proses, dan kontrak pengiriman keluar |
| `/codeql-critical-quality/memory-runtime-boundary` | SDK host memori, facade runtime memori, alias Plugin SDK memori, perekat aktivasi runtime memori, dan perintah doctor memori |
| `/codeql-critical-quality/session-diagnostics-boundary` | Internal antrean balasan, antrean pengiriman sesi, helper binding/pengiriman sesi keluar, permukaan bundle event/log diagnostik, dan kontrak CLI doctor sesi |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Dispatch balasan masuk Plugin SDK, helper payload/chunking/runtime balasan, opsi balasan channel, antrean pengiriman, dan helper binding sesi/thread |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Dispatch balasan masuk Plugin SDK, helper payload/pemotongan/runtime balasan, opsi balasan channel, antrean pengiriman, dan helper binding sesi/thread |
| `/codeql-critical-quality/provider-runtime-boundary` | Normalisasi katalog model, auth dan discovery provider, registrasi runtime provider, default/katalog provider, serta registry web/search/fetch/embedding |
| `/codeql-critical-quality/ui-control-plane` | Bootstrap UI kontrol, persistensi lokal, flow kontrol Gateway, dan kontrak runtime control-plane tugas |
| `/codeql-critical-quality/ui-control-plane` | Bootstrap UI kontrol, persistensi lokal, alur kontrol gateway, dan kontrak runtime control-plane tugas |
| `/codeql-critical-quality/web-media-runtime-boundary` | Kontrak runtime fetch/search web inti, IO media, pemahaman media, image-generation, dan media-generation |
| `/codeql-critical-quality/plugin-boundary` | Kontrak loader, registry, public-surface, dan entrypoint Plugin SDK |
| `/codeql-critical-quality/plugin-boundary` | Kontrak loader, registry, permukaan publik, dan entrypoint Plugin SDK |
| `/codeql-critical-quality/plugin-sdk-package-contract` | Sumber Plugin SDK sisi paket yang dipublikasikan dan helper kontrak paket plugin |
Kualitas tetap dipisahkan dari keamanan agar temuan kualitas dapat dijadwalkan, diukur, dinonaktifkan, atau diperluas tanpa mengaburkan sinyal keamanan. Ekspansi CodeQL Swift, Python, dan bundled-plugin harus ditambahkan kembali sebagai pekerjaan lanjutan yang terskop atau di-shard hanya setelah profil sempit memiliki runtime dan sinyal yang stabil.
Kualitas tetap dipisahkan dari keamanan agar temuan kualitas dapat dijadwalkan, diukur, dinonaktifkan, atau diperluas tanpa mengaburkan sinyal keamanan. Ekspansi CodeQL Swift, Python, dan plugin bawaan sebaiknya ditambahkan kembali sebagai pekerjaan lanjutan yang tercakup atau di-shard hanya setelah profil sempit memiliki runtime dan sinyal yang stabil.
## Workflow pemeliharaan
## Alur kerja pemeliharaan
### Docs Agent
### Agen Docs
Workflow `Docs Agent` adalah lane pemeliharaan Codex berbasis event untuk menjaga dokumen yang ada tetap selaras dengan perubahan yang baru mendarat. Workflow ini tidak memiliki jadwal murni: run CI push non-bot yang berhasil di `main` dapat memicunya, dan dispatch manual dapat menjalankannya langsung. Invokasi workflow-run dilewati saat `main` sudah bergerak maju atau saat run Docs Agent non-skip lain dibuat dalam satu jam terakhir. Saat berjalan, workflow ini meninjau rentang commit dari SHA sumber Docs Agent non-skip sebelumnya ke `main` saat ini, sehingga satu run per jam dapat mencakup semua perubahan main yang terkumpul sejak pass dokumen terakhir.
Alur kerja `Docs Agent` adalah lane pemeliharaan Codex berbasis event untuk menjaga dokumen yang ada tetap selaras dengan perubahan yang baru saja mendarat. Ia tidak memiliki jadwal murni: run CI push non-bot yang berhasil pada `main` dapat memicunya, dan dispatch manual dapat menjalankannya langsung. Invocation workflow-run dilewati saat `main` sudah bergerak maju atau saat run Docs Agent non-terlewati lainnya dibuat dalam satu jam terakhir. Saat berjalan, ia meninjau rentang commit dari SHA sumber Docs Agent non-terlewati sebelumnya hingga `main` saat ini, sehingga satu run per jam dapat mencakup semua perubahan main yang terkumpul sejak lintasan docs terakhir.
### Test Performance Agent
### Agen Performa Test
Workflow `Test Performance Agent` adalah lane pemeliharaan Codex berbasis event untuk test lambat. Workflow ini tidak memiliki jadwal murni: run CI push non-bot yang berhasil di `main` dapat memicunya, tetapi dilewati jika invokasi workflow-run lain sudah berjalan atau sedang berjalan pada hari UTC tersebut. Dispatch manual melewati gate aktivitas harian itu. Lane ini membangun laporan performa Vitest full-suite yang dikelompokkan, mengizinkan Codex hanya membuat perbaikan performa test kecil yang mempertahankan cakupan alih-alih refactor luas, lalu menjalankan ulang laporan full-suite dan menolak perubahan yang mengurangi jumlah test baseline yang lolos. Jika baseline memiliki test yang gagal, Codex hanya boleh memperbaiki kegagalan yang jelas dan laporan full-suite setelah agen harus lolos sebelum apa pun di-commit. Saat `main` bergerak maju sebelum push bot mendarat, lane ini melakukan rebase patch yang telah divalidasi, menjalankan ulang `pnpm check:changed`, dan mencoba push lagi; patch usang yang konflik dilewati. Workflow ini menggunakan Ubuntu yang di-host GitHub agar action Codex dapat mempertahankan postur keselamatan drop-sudo yang sama seperti docs agent.
Alur kerja `Test Performance Agent` adalah lane pemeliharaan Codex berbasis event untuk test yang lambat. Ia tidak memiliki jadwal murni: run CI push non-bot yang berhasil pada `main` dapat memicunya, tetapi ia melewati jika invocation workflow-run lain sudah berjalan atau sedang berjalan pada hari UTC tersebut. Dispatch manual melewati gerbang aktivitas harian itu. Lane ini membuat laporan performa Vitest full-suite yang dikelompokkan, mengizinkan Codex hanya membuat perbaikan performa test kecil yang mempertahankan cakupan alih-alih refactor luas, lalu menjalankan ulang laporan full-suite dan menolak perubahan yang mengurangi jumlah test baseline yang lulus. Jika baseline memiliki test yang gagal, Codex hanya boleh memperbaiki kegagalan yang jelas dan laporan full-suite pasca-agen harus lulus sebelum apa pun di-commit. Saat `main` maju sebelum push bot mendarat, lane me-rebase patch yang sudah divalidasi, menjalankan ulang `pnpm check:changed`, dan mencoba ulang push; patch basi yang konflik dilewati. Ini menggunakan Ubuntu yang di-host GitHub agar action Codex dapat mempertahankan postur keselamatan drop-sudo yang sama seperti agen docs.
### PR Duplikat Setelah Merge
Workflow `Duplicate PRs After Merge` adalah workflow maintainer manual untuk pembersihan duplikat pasca-land. Default-nya dry-run dan hanya menutup PR yang dicantumkan secara eksplisit saat `apply=true`. Sebelum memutasi GitHub, workflow ini memverifikasi bahwa PR yang mendarat sudah di-merge dan bahwa setiap duplikat memiliki issue referensi bersama atau hunk perubahan yang tumpang tindih.
Alur kerja `Duplicate PRs After Merge` adalah alur kerja maintainer manual untuk pembersihan duplikat pasca-land. Default-nya dry-run dan hanya menutup PR yang dicantumkan secara eksplisit saat `apply=true`. Sebelum memutasi GitHub, ia memverifikasi bahwa PR yang mendarat sudah di-merge dan bahwa setiap duplikat memiliki issue rujukan bersama atau hunk perubahan yang tumpang tindih.
```bash
gh workflow run duplicate-after-merge.yml \
@ -471,31 +466,31 @@ gh workflow run duplicate-after-merge.yml \
-f apply=true
```
## Gate check lokal dan routing perubahan
## Gerbang pemeriksaan lokal dan routing perubahan
Logika changed-lane lokal berada di `scripts/changed-lanes.mjs` dan dieksekusi oleh `scripts/check-changed.mjs`. Gate check lokal itu lebih ketat tentang batas arsitektur daripada cakupan platform CI yang luas:
Logika changed-lane lokal berada di `scripts/changed-lanes.mjs` dan dieksekusi oleh `scripts/check-changed.mjs`. Gerbang pemeriksaan lokal itu lebih ketat tentang batas arsitektur daripada cakupan platform CI yang luas:
- perubahan produksi inti menjalankan typecheck prod inti dan test inti ditambah lint/guard inti;
- perubahan khusus test inti hanya menjalankan typecheck test inti ditambah lint inti;
- perubahan produksi extension menjalankan typecheck prod extension dan test extension ditambah lint extension;
- perubahan khusus test extension menjalankan typecheck test extension ditambah lint extension;
- perubahan Plugin SDK publik atau kontrak plugin meluas ke typecheck extension karena extension bergantung pada kontrak inti tersebut (sapuan extension Vitest tetap berupa pekerjaan test eksplisit);
- bump versi khusus metadata rilis menjalankan check versi/config/dependensi-root yang ditargetkan;
- perubahan root/config yang tidak dikenal fail safe ke semua lane check.
- perubahan produksi ekstensi menjalankan typecheck prod ekstensi dan test ekstensi ditambah lint ekstensi;
- perubahan khusus test ekstensi menjalankan typecheck test ekstensi ditambah lint ekstensi;
- perubahan Plugin SDK publik atau kontrak plugin meluas ke typecheck ekstensi karena ekstensi bergantung pada kontrak inti tersebut (sweep ekstensi Vitest tetap menjadi pekerjaan test eksplisit);
- bump versi khusus metadata rilis menjalankan pemeriksaan versi/config/dependensi-root yang ditargetkan;
- perubahan root/config yang tidak diketahui fail safe ke semua lane pemeriksaan.
Routing changed-test lokal berada di `scripts/test-projects.test-support.mjs` dan sengaja lebih murah daripada `check:changed`: edit test langsung menjalankan dirinya sendiri, edit source memprioritaskan pemetaan eksplisit, lalu test saudara dan dependen import-graph. Config pengiriman group-room bersama adalah salah satu pemetaan eksplisit: perubahan pada config visible-reply grup, mode pengiriman balasan sumber, atau prompt sistem message-tool dirutekan melalui test balasan inti ditambah regresi pengiriman Discord dan Slack sehingga perubahan default bersama gagal sebelum push PR pertama. Gunakan `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` hanya saat perubahan cukup luas di harness sehingga set terpetakan murah bukan proxy yang dapat dipercaya.
Routing changed-test lokal berada di `scripts/test-projects.test-support.mjs` dan secara sengaja lebih murah daripada `check:changed`: edit test langsung menjalankan dirinya sendiri, edit sumber memprioritaskan pemetaan eksplisit, lalu test saudara dan dependen import-graph. Config pengiriman ruang-grup bersama adalah salah satu pemetaan eksplisit: perubahan pada config visible-reply grup, mode pengiriman balasan sumber, atau prompt sistem message-tool dirutekan melalui test balasan inti ditambah regresi pengiriman Discord dan Slack sehingga perubahan default bersama gagal sebelum push PR pertama. Gunakan `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` hanya saat perubahan cukup luas di harness sehingga set terpetakan yang murah bukan proksi yang dapat dipercaya.
## Validasi Testbox
Jalankan Testbox dari root repo dan utamakan box baru yang sudah di-warm untuk pembuktian luas. Sebelum menghabiskan gate yang lambat pada box yang digunakan ulang, kedaluwarsa, atau baru saja melaporkan sync yang ukurannya tak terduga besar, jalankan `pnpm testbox:sanity` di dalam box terlebih dahulu.
Jalankan Testbox dari root repo dan utamakan box baru yang sudah di-warm untuk bukti luas. Sebelum menghabiskan gate yang lambat pada box yang digunakan ulang, kedaluwarsa, atau baru saja melaporkan sinkronisasi yang ukurannya tidak terduga besar, jalankan `pnpm testbox:sanity` di dalam box terlebih dahulu.
Pemeriksaan sanity gagal cepat saat file root wajib seperti `pnpm-lock.yaml` menghilang atau saat `git status --short` menampilkan setidaknya 200 penghapusan terlacak. Itu biasanya berarti status sync jarak jauh bukan salinan PR yang dapat dipercaya; hentikan box itu dan warm box baru alih-alih men-debug kegagalan pengujian produk. Untuk PR penghapusan besar yang disengaja, setel `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` untuk run sanity tersebut.
Pemeriksaan sanity gagal cepat saat file root yang wajib ada seperti `pnpm-lock.yaml` hilang atau saat `git status --short` menunjukkan setidaknya 200 penghapusan terlacak. Itu biasanya berarti status sinkronisasi jarak jauh bukan salinan PR yang dapat dipercaya; hentikan box tersebut dan warm box baru alih-alih men-debug kegagalan pengujian produk. Untuk PR penghapusan besar yang disengaja, setel `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` untuk proses sanity tersebut.
`pnpm testbox:run` juga menghentikan invocation Blacksmith CLI lokal yang tetap berada dalam fase sync selama lebih dari lima menit tanpa output pasca-sync. Setel `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` untuk menonaktifkan guard itu, atau gunakan nilai milidetik yang lebih besar untuk diff lokal yang sangat besar.
`pnpm testbox:run` juga menghentikan pemanggilan Blacksmith CLI lokal yang tetap berada di fase sinkronisasi selama lebih dari lima menit tanpa keluaran pascasinkronisasi. Setel `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` untuk menonaktifkan guard tersebut, atau gunakan nilai milidetik yang lebih besar untuk diff lokal yang luar biasa besar.
Crabbox adalah wrapper remote-box milik repo untuk pembuktian Linux maintainer. Gunakan saat sebuah pemeriksaan terlalu luas untuk local edit loop, saat paritas CI penting, atau saat pembuktian membutuhkan secret, Docker, package lane, box yang dapat digunakan ulang, atau log jarak jauh. Backend OpenClaw normal adalah `blacksmith-testbox`; kapasitas AWS/Hetzner milik sendiri adalah fallback untuk gangguan Blacksmith, masalah kuota, atau pengujian kapasitas milik sendiri secara eksplisit.
Crabbox adalah wrapper remote-box milik repo untuk bukti Linux maintainer. Gunakan saat pemeriksaan terlalu luas untuk local loopback edit, saat paritas CI penting, atau saat bukti memerlukan secret, Docker, lane paket, box yang dapat digunakan ulang, atau log jarak jauh. Backend OpenClaw normal adalah `blacksmith-testbox`; kapasitas AWS/Hetzner milik sendiri adalah fallback untuk gangguan Blacksmith, masalah kuota, atau pengujian kapasitas milik sendiri secara eksplisit.
Sebelum run pertama, periksa wrapper dari root repo:
Sebelum menjalankan untuk pertama kalinya, periksa wrapper dari root repo:
```bash
pnpm crabbox:run -- --help | sed -n '1,120p'
@ -518,7 +513,7 @@ pnpm crabbox:run -- --provider blacksmith-testbox \
"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm check:changed"
```
Rerun pengujian terfokus:
Jalankan ulang pengujian terfokus:
```bash
pnpm crabbox:run -- --provider blacksmith-testbox \
@ -533,7 +528,7 @@ pnpm crabbox:run -- --provider blacksmith-testbox \
"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test <path-or-filter>"
```
Suite penuh:
Suite lengkap:
```bash
pnpm crabbox:run -- --provider blacksmith-testbox \
@ -548,14 +543,14 @@ pnpm crabbox:run -- --provider blacksmith-testbox \
"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test"
```
Baca ringkasan JSON akhir. Field yang berguna adalah `provider`, `leaseId`, `syncDelegated`, `exitCode`, `commandMs`, dan `totalMs`. Run Crabbox sekali jalan yang didukung Blacksmith seharusnya menghentikan Testbox secara otomatis; jika sebuah run terinterupsi atau cleanup tidak jelas, inspeksi box live dan hentikan hanya box yang Anda buat:
Baca ringkasan JSON akhir. Field yang berguna adalah `provider`, `leaseId`, `syncDelegated`, `exitCode`, `commandMs`, dan `totalMs`. Proses Crabbox sekali jalan yang didukung Blacksmith seharusnya menghentikan Testbox secara otomatis; jika proses terinterupsi atau pembersihan tidak jelas, periksa box aktif dan hentikan hanya box yang Anda buat:
```bash
blacksmith testbox list
blacksmith testbox stop --id <tbx_id>
```
Gunakan reuse hanya saat Anda sengaja membutuhkan beberapa perintah pada box terhidrasi yang sama:
Gunakan reuse hanya saat Anda memang membutuhkan beberapa perintah pada box terhidrasi yang sama:
```bash
pnpm crabbox:run -- --provider blacksmith-testbox --id <tbx_id> --no-sync --timing-json --shell -- "pnpm test <path-or-filter>"
@ -570,7 +565,7 @@ blacksmith testbox run --id <tbx_id> "env CI=1 NODE_OPTIONS=--max-old-space-size
blacksmith testbox stop --id <tbx_id>
```
Eskalasi ke kapasitas Crabbox milik sendiri hanya saat Blacksmith sedang down, dibatasi kuota, tidak memiliki environment yang dibutuhkan, atau kapasitas milik sendiri secara eksplisit menjadi tujuan:
Eskalasi ke kapasitas Crabbox milik sendiri hanya saat Blacksmith down, dibatasi kuota, tidak memiliki lingkungan yang dibutuhkan, atau kapasitas milik sendiri memang menjadi tujuannya secara eksplisit:
```bash
pnpm crabbox:warmup -- --provider aws --class beast --market on-demand --idle-timeout 90m
@ -579,9 +574,9 @@ pnpm crabbox:run -- --id <cbx_id-or-slug> --timing-json --shell -- "env NODE_OPT
pnpm crabbox:stop -- <cbx_id-or-slug>
```
`.crabbox.yaml` memiliki default provider, sync, dan hidrasi GitHub Actions untuk lane owned-cloud. File ini mengecualikan `.git` lokal agar checkout Actions terhidrasi mempertahankan metadata Git jarak jauhnya sendiri alih-alih menyinkronkan remote lokal maintainer dan object store, serta mengecualikan artefak runtime/build lokal yang tidak boleh pernah ditransfer. `.github/workflows/crabbox-hydrate.yml` memiliki checkout, penyiapan Node/pnpm, fetch `origin/main`, dan handoff environment non-secret untuk perintah owned-cloud `crabbox run --id <cbx_id>`.
`.crabbox.yaml` memiliki default provider, sinkronisasi, dan hidrasi GitHub Actions untuk lane owned-cloud. File ini mengecualikan `.git` lokal agar checkout Actions yang terhidrasi mempertahankan metadata Git jarak jauhnya sendiri alih-alih menyinkronkan remote lokal maintainer dan object store, serta mengecualikan artefak runtime/build lokal yang tidak boleh pernah ditransfer. `.github/workflows/crabbox-hydrate.yml` memiliki checkout, penyiapan Node/pnpm, fetch `origin/main`, dan handoff lingkungan non-secret untuk perintah owned-cloud `crabbox run --id <cbx_id>`.
## Terkait
- [Ringkasan instalasi](/id/install)
- [Ikhtisar instalasi](/id/install)
- [Channel pengembangan](/id/install/development-channels)

26
docs/id/cli/dashboard.md
View File

@ -1,16 +1,16 @@
---
read_when:
- Anda ingin membuka UI Kontrol dengan token Anda saat ini
- Anda ingin mencetak URL tanpa meluncurkan browser
summary: Referensi CLI untuk `openclaw dashboard` (buka UI Kontrol)
- Anda ingin membuka Control UI dengan token Anda saat ini
- Anda ingin mencetak URL tanpa membuka peramban
summary: Referensi CLI untuk `openclaw dashboard` (buka Control UI)
title: Dasbor
x-i18n:
generated_at: "2026-04-25T13:43:32Z"
model: gpt-5.4
generated_at: "2026-05-05T01:44:14Z"
model: gpt-5.5
provider: openai
source_hash: ce485388465fb93551be8ccf0aa01ea52e4feb949ef0d48c96b4f8ea65a6551c
source_hash: 51b3326b3884013ebcf570b417e66efe62ea89dcdedb5ab3173f39fb021de89f
source_path: cli/dashboard.md
workflow: 15
workflow: 16
---
# `openclaw dashboard`
@ -24,10 +24,14 @@ openclaw dashboard --no-open
Catatan:
- `dashboard` me-resolve SecretRef `gateway.auth.token` yang dikonfigurasi bila memungkinkan.
- `dashboard` mengikuti `gateway.tls.enabled`: gateway dengan TLS aktif mencetak/membuka URL UI Kontrol `https://` dan terhubung melalui `wss://`.
- Untuk token yang dikelola SecretRef (yang berhasil maupun tidak berhasil di-resolve), `dashboard` mencetak/menyalin/membuka URL tanpa token untuk menghindari pemaparan rahasia eksternal dalam output terminal, riwayat clipboard, atau argumen peluncuran browser.
- Jika `gateway.auth.token` dikelola SecretRef tetapi tidak berhasil di-resolve pada jalur perintah ini, perintah mencetak URL tanpa token dan panduan perbaikan yang eksplisit, alih-alih menyematkan placeholder token yang tidak valid.
- `dashboard` menyelesaikan SecretRef `gateway.auth.token` yang dikonfigurasi jika memungkinkan.
- `dashboard` mengikuti `gateway.tls.enabled`: gateway dengan TLS diaktifkan mencetak/membuka URL UI Kontrol
`https://` dan terhubung melalui `wss://`.
- Jika pengiriman melalui clipboard/browser gagal untuk URL dashboard yang diautentikasi token,
`dashboard` mencatat petunjuk autentikasi manual yang aman dengan menyebut `OPENCLAW_GATEWAY_TOKEN`,
`gateway.auth.token`, dan kunci fragmen `token` tanpa mencetak nilai token.
- Untuk token yang dikelola SecretRef (terselesaikan atau belum terselesaikan), `dashboard` mencetak/menyalin/membuka URL tanpa token untuk menghindari pemaparan secret eksternal dalam output terminal, riwayat clipboard, atau argumen peluncuran browser.
- Jika `gateway.auth.token` dikelola SecretRef tetapi tidak terselesaikan di jalur perintah ini, perintah mencetak URL tanpa token dan panduan remediasi eksplisit alih-alih menyematkan placeholder token yang tidak valid.
## Terkait

66
docs/id/cli/doctor.md
View File

@ -3,23 +3,23 @@ read_when:
- Anda mengalami masalah konektivitas/autentikasi dan menginginkan perbaikan terpandu
- Anda telah memperbarui dan ingin pemeriksaan kewajaran
summary: Referensi CLI untuk `openclaw doctor` (pemeriksaan kesehatan + perbaikan terpandu)
title: Diagnostik
title: Dokter
x-i18n:
generated_at: "2026-05-04T02:22:33Z"
generated_at: "2026-05-05T01:44:17Z"
model: gpt-5.5
provider: openai
source_hash: cd7fb09d373c313e4be45ad9e3b19ceb187a5787ef3e70fcd2b1f1f01b50c905
source_hash: 079d7674ae2a259a0430e30e7577ac532135ad5461c57c4b3a6514a007bc9ea5
source_path: cli/doctor.md
workflow: 16
---
# `openclaw doctor`
Pemeriksaan kesehatan + perbaikan cepat untuk Gateway dan channel.
Pemeriksaan kesehatan + perbaikan cepat untuk Gateway dan saluran.
Terkait:
- Pemecahan masalah: [Pemecahan masalah](/id/gateway/troubleshooting)
- Pemecahan masalah: [Pemecahan Masalah](/id/gateway/troubleshooting)
- Audit keamanan: [Keamanan](/id/gateway/security)
## Contoh
@ -35,44 +35,44 @@ openclaw doctor --generate-gateway-token
## Opsi
- `--no-workspace-suggestions`: nonaktifkan saran memori/pencarian workspace
- `--yes`: terima nilai default tanpa prompt
- `--yes`: terima default tanpa prompt
- `--repair`: terapkan perbaikan non-layanan yang direkomendasikan tanpa prompt; pemasangan dan penulisan ulang layanan Gateway tetap memerlukan konfirmasi interaktif atau perintah Gateway eksplisit
- `--fix`: alias untuk `--repair`
- `--force`: terapkan perbaikan agresif, termasuk menimpa konfigurasi layanan kustom jika diperlukan
- `--force`: terapkan perbaikan agresif, termasuk menimpa konfigurasi layanan kustom bila diperlukan
- `--non-interactive`: jalankan tanpa prompt; hanya migrasi aman dan perbaikan non-layanan
- `--generate-gateway-token`: buat dan konfigurasikan token Gateway
- `--deep`: pindai layanan sistem untuk pemasangan Gateway tambahan
Catatan:
- Prompt interaktif (seperti perbaikan keychain/OAuth) hanya berjalan ketika stdin adalah TTY dan `--non-interactive` **tidak** disetel. Eksekusi headless (cron, Telegram, tanpa terminal) akan melewati prompt.
- Performa: eksekusi `doctor` non-interaktif melewati pemuatan Plugin secara eager agar pemeriksaan kesehatan headless tetap cepat. Sesi interaktif tetap memuat Plugin sepenuhnya ketika pemeriksaan membutuhkan kontribusinya.
- `--fix` (alias untuk `--repair`) menulis cadangan ke `~/.openclaw/openclaw.json.bak` dan menghapus kunci konfigurasi yang tidak dikenal, dengan mencantumkan setiap penghapusan.
- `doctor --fix --non-interactive` melaporkan definisi layanan Gateway yang hilang atau usang tetapi tidak memasang atau menulis ulang definisi tersebut di luar mode perbaikan pembaruan. Jalankan `openclaw gateway install` untuk layanan yang hilang, atau `openclaw gateway install --force` ketika Anda memang ingin mengganti launcher.
- Pemeriksaan integritas status kini mendeteksi file transkrip yatim di direktori sesi. Mengarsipkannya sebagai `.deleted.<timestamp>` memerlukan konfirmasi interaktif; `--fix`, `--yes`, dan eksekusi headless membiarkannya tetap di tempat.
- Doctor juga memindai `~/.openclaw/cron/jobs.json` (atau `cron.store`) untuk bentuk job cron lama dan dapat menulis ulang secara langsung sebelum scheduler harus melakukan normalisasi otomatis saat runtime.
- Di Linux, doctor memperingatkan ketika crontab pengguna masih menjalankan `~/.openclaw/bin/ensure-whatsapp.sh` lama; skrip tersebut tidak lagi dipelihara dan dapat mencatat gangguan Gateway WhatsApp palsu ketika cron tidak memiliki lingkungan user-bus systemd.
- Doctor membersihkan status staging dependensi Plugin lama yang dibuat oleh versi OpenClaw yang lebih lama. Doctor juga memperbaiki Plugin unduhan terkonfigurasi yang hilang ketika registry dapat menyelesaikannya, dan proses doctor 2026.5.2 secara otomatis memasang Plugin unduhan yang sudah digunakan konfigurasi lama sebelum menandai konfigurasi tersentuh untuk rilis tersebut. Jika unduhan gagal, doctor melaporkan error pemasangan dan mempertahankan entri Plugin terkonfigurasi untuk upaya perbaikan berikutnya.
- Doctor memperbaiki konfigurasi Plugin usang dengan menghapus id Plugin yang hilang dari `plugins.allow`/`plugins.entries`, serta konfigurasi channel yang menggantung, target Heartbeat, dan override model channel yang cocok ketika penemuan Plugin sehat.
- Doctor mengarantina konfigurasi Plugin yang tidak valid dengan menonaktifkan entri `plugins.entries.<id>` yang terdampak dan menghapus payload `config` yang tidak valid. Startup Gateway sudah melewati hanya Plugin bermasalah tersebut sehingga Plugin dan channel lain dapat tetap berjalan.
- Setel `OPENCLAW_SERVICE_REPAIR_POLICY=external` ketika supervisor lain memiliki siklus hidup Gateway. Doctor tetap melaporkan kesehatan Gateway/layanan dan menerapkan perbaikan non-layanan, tetapi melewati pemasangan/start/restart/bootstrap layanan dan pembersihan layanan lama.
- Di Linux, doctor mengabaikan unit systemd tambahan mirip Gateway yang tidak aktif dan tidak menulis ulang metadata command/entrypoint untuk layanan Gateway systemd yang sedang berjalan selama perbaikan. Hentikan layanan terlebih dahulu atau gunakan `openclaw gateway install --force` ketika Anda memang ingin mengganti launcher aktif.
- Doctor melakukan migrasi otomatis konfigurasi Talk datar lama (`talk.voiceId`, `talk.modelId`, dan sejenisnya) ke `talk.provider` + `talk.providers.<provider>`.
- Eksekusi `doctor --fix` berulang tidak lagi melaporkan/menerapkan normalisasi Talk ketika satu-satunya perbedaan adalah urutan kunci objek.
- Doctor menyertakan pemeriksaan kesiapan pencarian memori dan dapat merekomendasikan `openclaw configure --section model` ketika kredensial embedding hilang.
- Doctor memperingatkan ketika tidak ada pemilik command yang dikonfigurasi. Pemilik command adalah akun operator manusia yang diizinkan menjalankan command khusus pemilik dan menyetujui tindakan berbahaya. Pairing DM hanya memungkinkan seseorang berbicara dengan bot; jika Anda menyetujui pengirim sebelum bootstrap pemilik pertama ada, setel `commands.ownerAllowFrom` secara eksplisit.
- Doctor memperingatkan ketika agen mode Codex dikonfigurasi dan aset CLI Codex pribadi ada di home Codex operator. Peluncuran server aplikasi Codex lokal menggunakan home per-agen yang terisolasi, jadi gunakan `openclaw migrate codex --dry-run` untuk menginventarisasi aset yang harus dipromosikan secara sengaja.
- Doctor memperingatkan ketika Skills yang diizinkan untuk agen default tidak tersedia di lingkungan runtime saat ini karena bin, env vars, konfigurasi, atau persyaratan OS hilang. `doctor --fix` dapat menonaktifkan Skills yang tidak tersedia tersebut dengan `skills.entries.<skill>.enabled=false`; pasang/konfigurasikan persyaratan yang hilang sebagai gantinya ketika Anda ingin mempertahankan skill tetap aktif.
- Jika mode sandbox diaktifkan tetapi Docker tidak tersedia, doctor melaporkan peringatan bernilai tinggi dengan remediasi (`install Docker` atau `openclaw config set agents.defaults.sandbox.mode off`).
- Jika file registry sandbox lama (`~/.openclaw/sandbox/containers.json` atau `~/.openclaw/sandbox/browsers.json`) ada, doctor melaporkannya; `openclaw doctor --fix` memigrasikan entri valid ke direktori registry bershard dan mengarantina file lama yang tidak valid.
- Jika `gateway.auth.token`/`gateway.auth.password` dikelola SecretRef dan tidak tersedia di jalur command saat ini, doctor melaporkan peringatan hanya-baca dan tidak menulis kredensial fallback plaintext.
- Jika inspeksi SecretRef channel gagal di jalur perbaikan, doctor melanjutkan dan melaporkan peringatan alih-alih keluar lebih awal.
- Setelah migrasi direktori status, doctor memperingatkan ketika akun Telegram atau Discord default yang diaktifkan bergantung pada fallback env dan `TELEGRAM_BOT_TOKEN` atau `DISCORD_BOT_TOKEN` tidak tersedia untuk proses doctor.
- Resolusi otomatis username `allowFrom` Telegram (`doctor --fix`) memerlukan token Telegram yang dapat di-resolve di jalur command saat ini. Jika inspeksi token tidak tersedia, doctor melaporkan peringatan dan melewati resolusi otomatis untuk proses tersebut.
- Prompt interaktif (seperti perbaikan keychain/OAuth) hanya berjalan saat stdin adalah TTY dan `--non-interactive` **tidak** disetel. Proses tanpa antarmuka (cron, Telegram, tanpa terminal) akan melewati prompt.
- Performa: proses `doctor` non-interaktif melewati pemuatan Plugin secara eager agar pemeriksaan kesehatan tanpa antarmuka tetap cepat. Sesi interaktif tetap memuat Plugin sepenuhnya saat suatu pemeriksaan membutuhkan kontribusinya.
- `--fix` (alias untuk `--repair`) menulis cadangan ke `~/.openclaw/openclaw.json.bak` dan membuang kunci konfigurasi yang tidak dikenal, dengan mencantumkan setiap penghapusan.
- `doctor --fix --non-interactive` melaporkan definisi layanan Gateway yang hilang atau kedaluwarsa tetapi tidak memasang atau menulis ulang definisi tersebut di luar mode perbaikan pembaruan. Jalankan `openclaw gateway install` untuk layanan yang hilang, atau `openclaw gateway install --force` saat Anda memang ingin mengganti launcher.
- Pemeriksaan integritas state sekarang mendeteksi file transkrip yatim piatu di direktori sesi. Mengarsipkannya sebagai `.deleted.<timestamp>` memerlukan konfirmasi interaktif; `--fix`, `--yes`, dan proses tanpa antarmuka membiarkannya tetap ada.
- Doctor juga memindai `~/.openclaw/cron/jobs.json` (atau `cron.store`) untuk bentuk job Cron lama dan dapat menulis ulang di tempat sebelum scheduler harus menormalisasinya otomatis saat runtime.
- Di Linux, doctor memperingatkan saat crontab pengguna masih menjalankan `~/.openclaw/bin/ensure-whatsapp.sh` lama; skrip itu tidak lagi dipelihara dan dapat mencatat gangguan Gateway WhatsApp palsu saat cron tidak memiliki lingkungan systemd user-bus.
- Doctor membersihkan state staging dependensi Plugin lama yang dibuat oleh versi OpenClaw yang lebih lama. Doctor juga memperbaiki Plugin unduhan yang hilang dan direferensikan oleh konfigurasi, seperti `plugins.entries`, saluran terkonfigurasi, pengaturan provider/pencarian terkonfigurasi, atau runtime agen terkonfigurasi. Selama pembaruan paket, doctor melewati perbaikan Plugin package-manager sampai penukaran paket selesai; jalankan ulang `openclaw doctor --fix` setelahnya jika Plugin terkonfigurasi masih perlu dipulihkan. Jika unduhan gagal, doctor melaporkan kesalahan pemasangan dan mempertahankan entri Plugin terkonfigurasi untuk percobaan perbaikan berikutnya.
- Doctor memperbaiki konfigurasi Plugin kedaluwarsa dengan menghapus id Plugin yang hilang dari `plugins.allow`/`plugins.entries`, serta konfigurasi saluran menggantung yang cocok, target Heartbeat, dan override model saluran saat penemuan Plugin sehat.
- Doctor mengarantina konfigurasi Plugin yang tidak valid dengan menonaktifkan entri `plugins.entries.<id>` yang terdampak dan menghapus payload `config` yang tidak valid. Startup Gateway sudah melewati hanya Plugin bermasalah itu sehingga Plugin dan saluran lain dapat tetap berjalan.
- Setel `OPENCLAW_SERVICE_REPAIR_POLICY=external` saat supervisor lain memiliki siklus hidup Gateway. Doctor tetap melaporkan kesehatan Gateway/layanan dan menerapkan perbaikan non-layanan, tetapi melewati pemasangan/mulai/mulai ulang/bootstrap layanan dan pembersihan layanan lama.
- Di Linux, doctor mengabaikan unit systemd tambahan mirip Gateway yang tidak aktif dan tidak menulis ulang metadata perintah/entrypoint untuk layanan Gateway systemd yang sedang berjalan selama perbaikan. Hentikan layanan terlebih dahulu atau gunakan `openclaw gateway install --force` saat Anda memang ingin mengganti launcher aktif.
- Doctor memigrasikan otomatis konfigurasi Talk datar lama (`talk.voiceId`, `talk.modelId`, dan lainnya) ke `talk.provider` + `talk.providers.<provider>`.
- Proses `doctor --fix` berulang tidak lagi melaporkan/menerapkan normalisasi Talk saat satu-satunya perbedaan adalah urutan kunci objek.
- Doctor menyertakan pemeriksaan kesiapan pencarian memori dan dapat merekomendasikan `openclaw configure --section model` saat kredensial embedding hilang.
- Doctor memperingatkan saat tidak ada pemilik perintah yang dikonfigurasi. Pemilik perintah adalah akun operator manusia yang diizinkan menjalankan perintah khusus pemilik dan menyetujui tindakan berbahaya. Pairing DM hanya memungkinkan seseorang berbicara dengan bot; jika Anda menyetujui pengirim sebelum bootstrap pemilik pertama ada, setel `commands.ownerAllowFrom` secara eksplisit.
- Doctor memperingatkan saat agen mode Codex dikonfigurasi dan aset Codex CLI pribadi ada di home Codex milik operator. Peluncuran app-server Codex lokal menggunakan home per agen yang terisolasi, jadi gunakan `openclaw migrate codex --dry-run` untuk menginventarisasi aset yang harus dipromosikan secara sengaja.
- Doctor memperingatkan saat skills yang diizinkan untuk agen default tidak tersedia di lingkungan runtime saat ini karena bin, variabel env, konfigurasi, atau persyaratan OS hilang. `doctor --fix` dapat menonaktifkan skills yang tidak tersedia tersebut dengan `skills.entries.<skill>.enabled=false`; pasang/konfigurasikan persyaratan yang hilang sebagai gantinya saat Anda ingin skill tetap aktif.
- Jika mode sandbox diaktifkan tetapi Docker tidak tersedia, doctor melaporkan peringatan bersinyal tinggi dengan remediasi (`install Docker` atau `openclaw config set agents.defaults.sandbox.mode off`).
- Jika file registri sandbox lama (`~/.openclaw/sandbox/containers.json` atau `~/.openclaw/sandbox/browsers.json`) ada, doctor melaporkannya; `openclaw doctor --fix` memigrasikan entri valid ke direktori registri tersharding dan mengarantina file lama yang tidak valid.
- Jika `gateway.auth.token`/`gateway.auth.password` dikelola SecretRef dan tidak tersedia di jalur perintah saat ini, doctor melaporkan peringatan baca-saja dan tidak menulis kredensial fallback plaintext.
- Jika inspeksi SecretRef saluran gagal di jalur perbaikan, doctor melanjutkan dan melaporkan peringatan alih-alih keluar lebih awal.
- Setelah migrasi direktori state, doctor memperingatkan saat akun default Telegram atau Discord yang diaktifkan bergantung pada fallback env dan `TELEGRAM_BOT_TOKEN` atau `DISCORD_BOT_TOKEN` tidak tersedia bagi proses doctor.
- Resolusi otomatis username `allowFrom` Telegram (`doctor --fix`) memerlukan token Telegram yang dapat di-resolve di jalur perintah saat ini. Jika inspeksi token tidak tersedia, doctor melaporkan peringatan dan melewati resolusi otomatis untuk proses tersebut.
## macOS: override env `launchctl`
Jika sebelumnya Anda menjalankan `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (atau `...PASSWORD`), nilai tersebut menimpa file konfigurasi Anda dan dapat menyebabkan error “tidak terotorisasi” yang persisten.
Jika sebelumnya Anda menjalankan `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (atau `...PASSWORD`), nilai tersebut menimpa file konfigurasi Anda dan dapat menyebabkan kesalahan “tidak terotorisasi” yang persisten.
```bash
launchctl getenv OPENCLAW_GATEWAY_TOKEN
@ -85,4 +85,4 @@ launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD
## Terkait
- [Referensi CLI](/id/cli)
- [Gateway doctor](/id/gateway/doctor)
- [Doctor Gateway](/id/gateway/doctor)

215
docs/id/cli/gateway.md
View File

@ -1,16 +1,16 @@
---
read_when:
- Menjalankan Gateway dari CLI (pengembangan atau server)
- Men-debug autentikasi Gateway, mode pengikatan, dan konektivitas
- Mendiagnosis autentikasi Gateway, mode pengikatan, dan konektivitas
- Menemukan Gateway melalui Bonjour (DNS-SD lokal + area luas)
sidebarTitle: Gateway
summary: OpenClaw Gateway CLI (`openclaw gateway`) — jalankan, kueri, dan temukan Gateway
title: Gateway
x-i18n:
generated_at: "2026-05-04T18:23:42Z"
generated_at: "2026-05-05T01:44:23Z"
model: gpt-5.5
provider: openai
source_hash: 310867c59148577f2e8ce6f708da6bce936e09243ce7fbe5daeb453c6b3b370d
source_hash: 521558189b150b2faa22f95ec32419ac9e02c5f47c72b9095f40d1432840c038
source_path: cli/gateway.md
workflow: 16
---
@ -37,7 +37,7 @@ Jalankan proses Gateway lokal:
openclaw gateway
```
Alias foreground:
Alias latar depan:
```bash
openclaw gateway run
@ -46,11 +46,11 @@ openclaw gateway run
<AccordionGroup>
<Accordion title="Perilaku startup">
- Secara default, Gateway menolak untuk dimulai kecuali `gateway.mode=local` diatur di `~/.openclaw/openclaw.json`. Gunakan `--allow-unconfigured` untuk eksekusi ad-hoc/dev.
- `openclaw onboard --mode local` dan `openclaw setup` diharapkan menulis `gateway.mode=local`. Jika file ada tetapi `gateway.mode` tidak ada, perlakukan itu sebagai konfigurasi yang rusak atau tertimpa dan perbaiki, alih-alih mengasumsikan mode lokal secara implisit.
- Jika file ada dan `gateway.mode` tidak ada, Gateway memperlakukan itu sebagai kerusakan konfigurasi yang mencurigakan dan menolak untuk "menebak lokal" untuk Anda.
- Binding di luar loopback tanpa autentikasi diblokir (pagar pengaman).
- `SIGUSR1` memicu restart dalam proses saat diotorisasi (`commands.restart` diaktifkan secara default; atur `commands.restart: false` untuk memblokir restart manual, sementara penerapan/pembaruan alat/konfigurasi gateway tetap diizinkan).
- Handler `SIGINT`/`SIGTERM` menghentikan proses gateway, tetapi tidak memulihkan status terminal kustom apa pun. Jika Anda membungkus CLI dengan TUI atau input raw-mode, pulihkan terminal sebelum keluar.
- `openclaw onboard --mode local` dan `openclaw setup` diharapkan menulis `gateway.mode=local`. Jika file ada tetapi `gateway.mode` hilang, anggap itu sebagai konfigurasi yang rusak atau tertimpa dan perbaiki, bukan mengasumsikan mode lokal secara implisit.
- Jika file ada dan `gateway.mode` hilang, Gateway menganggapnya sebagai kerusakan konfigurasi yang mencurigakan dan menolak untuk "menebak lokal" untuk Anda.
- Pengikatan di luar loopback tanpa autentikasi diblokir (pagar pengaman).
- `SIGUSR1` memicu restart dalam proses saat diotorisasi (`commands.restart` diaktifkan secara default; atur `commands.restart: false` untuk memblokir restart manual, sementara penerapan/pembaruan tool/config gateway tetap diizinkan).
- Handler `SIGINT`/`SIGTERM` menghentikan proses gateway, tetapi tidak memulihkan status terminal kustom apa pun. Jika Anda membungkus CLI dengan TUI atau input mode raw, pulihkan terminal sebelum keluar.
</Accordion>
</AccordionGroup>
@ -58,7 +58,7 @@ openclaw gateway run
### Opsi
<ParamField path="--port <port>" type="number">
Port WebSocket (default berasal dari konfigurasi/env; biasanya `18789`).
Port WebSocket (default berasal dari config/env; biasanya `18789`).
</ParamField>
<ParamField path="--bind <loopback|lan|tailnet|auto|custom>" type="string">
Mode bind listener.
@ -79,19 +79,19 @@ openclaw gateway run
Ekspos Gateway melalui Tailscale.
</ParamField>
<ParamField path="--tailscale-reset-on-exit" type="boolean">
Reset konfigurasi serve/funnel Tailscale saat shutdown.
Reset config serve/funnel Tailscale saat shutdown.
</ParamField>
<ParamField path="--allow-unconfigured" type="boolean">
Izinkan gateway dimulai tanpa `gateway.mode=local` dalam konfigurasi. Hanya melewati guard startup untuk bootstrap ad-hoc/dev; tidak menulis atau memperbaiki file konfigurasi.
Izinkan gateway dimulai tanpa `gateway.mode=local` dalam config. Hanya melewati pelindung startup untuk bootstrap ad-hoc/dev; tidak menulis atau memperbaiki file config.
</ParamField>
<ParamField path="--dev" type="boolean">
Buat konfigurasi dev + ruang kerja jika tidak ada (melewati BOOTSTRAP.md).
Buat config dev + workspace jika belum ada (melewati BOOTSTRAP.md).
</ParamField>
<ParamField path="--reset" type="boolean">
Reset konfigurasi dev + kredensial + sesi + ruang kerja (memerlukan `--dev`).
Reset config dev + kredensial + sesi + workspace (memerlukan `--dev`).
</ParamField>
<ParamField path="--force" type="boolean">
Matikan listener yang ada pada port yang dipilih sebelum memulai.
Matikan listener yang sudah ada pada port yang dipilih sebelum memulai.
</ParamField>
<ParamField path="--verbose" type="boolean">
Log verbose.
@ -100,16 +100,16 @@ openclaw gateway run
Hanya tampilkan log backend CLI di konsol (dan aktifkan stdout/stderr).
</ParamField>
<ParamField path="--ws-log <auto|full|compact>" type="string" default="auto">
Gaya log Websocket.
Gaya log WebSocket.
</ParamField>
<ParamField path="--compact" type="boolean">
Alias untuk `--ws-log compact`.
</ParamField>
<ParamField path="--raw-stream" type="boolean">
Catat peristiwa stream model mentah ke jsonl.
Catat event stream model raw ke jsonl.
</ParamField>
<ParamField path="--raw-stream-path <path>" type="string">
Path jsonl stream mentah.
Path jsonl stream raw.
</ParamField>
## Restart Gateway
@ -120,17 +120,17 @@ openclaw gateway restart --safe
openclaw gateway restart --force
```
`openclaw gateway restart --safe` meminta Gateway yang sedang berjalan untuk melakukan preflight pekerjaan OpenClaw yang aktif sebelum restart. Jika operasi antrean, pengiriman balasan, eksekusi tertanam, atau eksekusi tugas aktif, Gateway melaporkan pemblokirnya, menggabungkan permintaan restart aman yang duplikat, dan restart setelah pekerjaan aktif selesai. `restart` biasa mempertahankan perilaku manajer layanan yang ada untuk kompatibilitas. Gunakan `--force` hanya saat Anda secara eksplisit menginginkan jalur override segera.
`openclaw gateway restart --safe` meminta Gateway yang sedang berjalan untuk melakukan preflight pada pekerjaan OpenClaw aktif sebelum restart. Jika operasi antrean, pengiriman balasan, eksekusi tertanam, atau eksekusi tugas aktif, Gateway melaporkan pemblokir, menggabungkan permintaan restart aman duplikat, dan restart setelah pekerjaan aktif selesai. `restart` biasa mempertahankan perilaku service-manager yang sudah ada untuk kompatibilitas. Gunakan `--force` hanya saat Anda secara eksplisit menginginkan jalur override langsung.
<Warning>
`--password` inline dapat terlihat dalam daftar proses lokal. Lebih baik gunakan `--password-file`, env, atau `gateway.auth.password` yang didukung SecretRef.
`--password` inline dapat terekspos dalam daftar proses lokal. Utamakan `--password-file`, env, atau `gateway.auth.password` berbasis SecretRef.
</Warning>
### Profiling startup
- Atur `OPENCLAW_GATEWAY_STARTUP_TRACE=1` untuk mencatat timing fase selama startup Gateway, termasuk penundaan `eventLoopMax` per fase dan timing tabel lookup plugin untuk installed-index, registri manifest, perencanaan startup, dan pekerjaan owner-map.
- Atur `OPENCLAW_DIAGNOSTICS=timeline` dengan `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>` untuk menulis timeline diagnostik startup JSONL best-effort untuk harness QA eksternal. Anda juga dapat mengaktifkan flag dengan `diagnostics.flags: ["timeline"]` dalam konfigurasi; path tetap disediakan melalui env. Tambahkan `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` untuk menyertakan sampel event-loop.
- Jalankan `pnpm test:startup:gateway -- --runs 5 --warmup 1` untuk melakukan benchmark startup Gateway. Benchmark merekam output proses pertama, `/healthz`, `/readyz`, timing trace startup, penundaan event-loop, dan detail timing tabel lookup plugin.
- Atur `OPENCLAW_GATEWAY_STARTUP_TRACE=1` untuk mencatat timing fase selama startup Gateway, termasuk delay `eventLoopMax` per fase dan timing tabel lookup Plugin untuk installed-index, registry manifest, perencanaan startup, dan pekerjaan owner-map.
- Atur `OPENCLAW_DIAGNOSTICS=timeline` dengan `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>` untuk menulis timeline diagnostik startup JSONL best-effort bagi harness QA eksternal. Anda juga dapat mengaktifkan flag dengan `diagnostics.flags: ["timeline"]` di config; path tetap disediakan lewat env. Tambahkan `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1` untuk menyertakan sampel event-loop.
- Jalankan `pnpm test:startup:gateway -- --runs 5 --warmup 1` untuk membenchmark startup Gateway. Benchmark merekam output proses pertama, `/healthz`, `/readyz`, timing trace startup, delay event-loop, dan detail timing tabel lookup Plugin.
## Kueri Gateway yang sedang berjalan
@ -139,7 +139,7 @@ Semua perintah kueri menggunakan RPC WebSocket.
<Tabs>
<Tab title="Mode output">
- Default: mudah dibaca manusia (berwarna di TTY).
- `--json`: JSON yang dapat dibaca mesin (tanpa gaya/spinner).
- `--json`: JSON yang dapat dibaca mesin (tanpa styling/spinner).
- `--no-color` (atau `NO_COLOR=1`): nonaktifkan ANSI sambil mempertahankan tata letak manusia.
</Tab>
@ -147,14 +147,14 @@ Semua perintah kueri menggunakan RPC WebSocket.
- `--url <url>`: URL WebSocket Gateway.
- `--token <token>`: token Gateway.
- `--password <password>`: kata sandi Gateway.
- `--timeout <ms>`: timeout/anggaran (berbeda per perintah).
- `--timeout <ms>`: timeout/anggaran (bervariasi per perintah).
- `--expect-final`: tunggu respons "final" (panggilan agen).
</Tab>
</Tabs>
<Note>
Saat Anda mengatur `--url`, CLI tidak fallback ke kredensial konfigurasi atau lingkungan. Berikan `--token` atau `--password` secara eksplisit. Kredensial eksplisit yang tidak ada adalah error.
Saat Anda mengatur `--url`, CLI tidak fallback ke kredensial config atau environment. Berikan `--token` atau `--password` secara eksplisit. Kredensial eksplisit yang hilang adalah error.
</Note>
### `gateway health`
@ -163,7 +163,7 @@ Saat Anda mengatur `--url`, CLI tidak fallback ke kredensial konfigurasi atau li
openclaw gateway health --url ws://127.0.0.1:18789
```
Endpoint HTTP `/healthz` adalah probe liveness: endpoint ini kembali setelah server dapat menjawab HTTP. Endpoint HTTP `/readyz` lebih ketat dan tetap merah saat sidecar plugin startup, saluran, atau hook yang dikonfigurasi masih stabil. Respons readiness detail lokal atau terautentikasi menyertakan blok diagnostik `eventLoop` dengan penundaan event-loop, utilisasi event-loop, rasio core CPU, dan flag `degraded`.
Endpoint HTTP `/healthz` adalah probe liveness: endpoint ini mengembalikan respons begitu server dapat menjawab HTTP. Endpoint HTTP `/readyz` lebih ketat dan tetap merah saat sidecar Plugin startup, saluran, atau hook yang dikonfigurasi masih dalam proses stabil. Respons kesiapan detail lokal atau terautentikasi menyertakan blok diagnostik `eventLoop` dengan delay event-loop, utilisasi event-loop, rasio core CPU, dan flag `degraded`.
### `gateway usage-cost`
@ -176,7 +176,7 @@ openclaw gateway usage-cost --json
```
<ParamField path="--days <days>" type="number" default="30">
Jumlah hari yang akan disertakan.
Jumlah hari yang disertakan.
</ParamField>
### `gateway stability`
@ -192,16 +192,16 @@ openclaw gateway stability --json
```
<ParamField path="--limit <limit>" type="number" default="25">
Jumlah maksimum peristiwa terbaru yang disertakan (maks `1000`).
Jumlah maksimum event terbaru yang disertakan (maks `1000`).
</ParamField>
<ParamField path="--type <type>" type="string">
Filter berdasarkan jenis peristiwa diagnostik, seperti `payload.large` atau `diagnostic.memory.pressure`.
Filter berdasarkan tipe event diagnostik, seperti `payload.large` atau `diagnostic.memory.pressure`.
</ParamField>
<ParamField path="--since-seq <seq>" type="number">
Sertakan hanya peristiwa setelah nomor urut diagnostik.
Hanya sertakan event setelah nomor urut diagnostik.
</ParamField>
<ParamField path="--bundle [path]" type="string">
Baca bundle stabilitas yang dipersistenkan alih-alih memanggil Gateway yang sedang berjalan. Gunakan `--bundle latest` (atau cukup `--bundle`) untuk bundle terbaru di bawah direktori status, atau berikan path JSON bundle secara langsung.
Baca bundle stabilitas persisten alih-alih memanggil Gateway yang sedang berjalan. Gunakan `--bundle latest` (atau cukup `--bundle`) untuk bundle terbaru di bawah direktori state, atau berikan path JSON bundle secara langsung.
</ParamField>
<ParamField path="--export" type="boolean">
Tulis zip diagnostik dukungan yang dapat dibagikan alih-alih mencetak detail stabilitas.
@ -212,8 +212,8 @@ openclaw gateway stability --json
<AccordionGroup>
<Accordion title="Privasi dan perilaku bundle">
- Catatan menyimpan metadata operasional: nama peristiwa, hitungan, ukuran byte, pembacaan memori, status antrean/sesi, nama saluran/plugin, dan ringkasan sesi yang disunting. Catatan tidak menyimpan teks chat, body webhook, output alat, body permintaan atau respons mentah, token, cookie, nilai rahasia, hostname, atau id sesi mentah. Atur `diagnostics.enabled: false` untuk menonaktifkan perekam sepenuhnya.
- Pada exit Gateway yang fatal, timeout shutdown, dan kegagalan startup restart, OpenClaw menulis snapshot diagnostik yang sama ke `~/.openclaw/logs/stability/openclaw-stability-*.json` saat perekam memiliki peristiwa. Periksa bundle terbaru dengan `openclaw gateway stability --bundle latest`; `--limit`, `--type`, dan `--since-seq` juga berlaku untuk output bundle.
- Rekaman menyimpan metadata operasional: nama event, hitungan, ukuran byte, pembacaan memori, status antrean/sesi, nama saluran/Plugin, dan ringkasan sesi yang disunting. Rekaman tidak menyimpan teks chat, body webhook, output tool, body request atau response raw, token, cookie, nilai rahasia, hostname, atau id sesi raw. Atur `diagnostics.enabled: false` untuk menonaktifkan perekam sepenuhnya.
- Pada exit fatal Gateway, timeout shutdown, dan kegagalan startup restart, OpenClaw menulis snapshot diagnostik yang sama ke `~/.openclaw/logs/stability/openclaw-stability-*.json` saat perekam memiliki event. Periksa bundle terbaru dengan `openclaw gateway stability --bundle latest`; `--limit`, `--type`, dan `--since-seq` juga berlaku untuk output bundle.
</Accordion>
</AccordionGroup>
@ -229,7 +229,7 @@ openclaw gateway diagnostics export --json
```
<ParamField path="--output <path>" type="string">
Path zip output. Default ke ekspor dukungan di bawah direktori status.
Path zip output. Default ke ekspor dukungan di bawah direktori state.
</ParamField>
<ParamField path="--log-lines <count>" type="number" default="5000">
Jumlah maksimum baris log tersanitasi yang disertakan.
@ -238,31 +238,31 @@ openclaw gateway diagnostics export --json
Jumlah maksimum byte log yang diperiksa.
</ParamField>
<ParamField path="--url <url>" type="string">
URL WebSocket Gateway untuk snapshot kesehatan.
URL WebSocket Gateway untuk snapshot health.
</ParamField>
<ParamField path="--token <token>" type="string">
Token Gateway untuk snapshot kesehatan.
Token Gateway untuk snapshot health.
</ParamField>
<ParamField path="--password <password>" type="string">
Kata sandi Gateway untuk snapshot kesehatan.
Kata sandi Gateway untuk snapshot health.
</ParamField>
<ParamField path="--timeout <ms>" type="number" default="3000">
Timeout snapshot status/kesehatan.
Timeout snapshot status/health.
</ParamField>
<ParamField path="--no-stability-bundle" type="boolean">
Lewati lookup bundle stabilitas yang dipersistenkan.
Lewati lookup bundle stabilitas persisten.
</ParamField>
<ParamField path="--json" type="boolean">
Cetak path tertulis, ukuran, dan manifest sebagai JSON.
</ParamField>
Ekspor berisi manifest, ringkasan Markdown, bentuk konfigurasi, detail konfigurasi tersanitasi, ringkasan log tersanitasi, snapshot status/kesehatan Gateway tersanitasi, dan bundle stabilitas terbaru jika ada.
Ekspor berisi manifest, ringkasan Markdown, bentuk config, detail config tersanitasi, ringkasan log tersanitasi, snapshot status/health Gateway tersanitasi, dan bundle stabilitas terbaru saat tersedia.
Ekspor ini dimaksudkan untuk dibagikan. Ekspor menyimpan detail operasional yang membantu debugging, seperti field log OpenClaw yang aman, nama subsistem, kode status, durasi, mode yang dikonfigurasi, port, id plugin, id penyedia, pengaturan fitur non-rahasia, dan pesan log operasional yang disunting. Ekspor menghilangkan atau menyunting teks chat, body webhook, output alat, kredensial, cookie, pengidentifikasi akun/pesan, teks prompt/instruksi, hostname, dan nilai rahasia. Saat pesan bergaya LogTape terlihat seperti teks payload pengguna/chat/alat, ekspor hanya menyimpan bahwa pesan tersebut dihilangkan beserta jumlah byte-nya.
Ini dimaksudkan untuk dibagikan. Ekspor mempertahankan detail operasional yang membantu debugging, seperti field log OpenClaw yang aman, nama subsistem, kode status, durasi, mode yang dikonfigurasi, port, id Plugin, id provider, pengaturan fitur non-rahasia, dan pesan log operasional yang disunting. Ekspor menghilangkan atau menyunting teks chat, body webhook, output tool, kredensial, cookie, identifier akun/pesan, teks prompt/instruksi, hostname, dan nilai rahasia. Saat pesan bergaya LogTape terlihat seperti teks payload pengguna/chat/tool, ekspor hanya mempertahankan bahwa suatu pesan dihilangkan beserta jumlah byte-nya.
### `gateway status`
`gateway status` menampilkan layanan Gateway (launchd/systemd/schtasks) plus probe opsional untuk kemampuan konektivitas/autentikasi.
`gateway status` menampilkan layanan Gateway (launchd/systemd/schtasks) plus probe opsional untuk kapabilitas konektivitas/autentikasi.
```bash
openclaw gateway status
@ -271,63 +271,63 @@ openclaw gateway status --require-rpc
```
<ParamField path="--url <url>" type="string">
Tambahkan target pemeriksaan eksplisit. Remote yang dikonfigurasi + localhost tetap diperiksa.
Tambahkan target probe eksplisit. Remote yang dikonfigurasi + localhost tetap di-probe.
</ParamField>
<ParamField path="--token <token>" type="string">
Autentikasi token untuk pemeriksaan.
Autentikasi token untuk probe.
</ParamField>
<ParamField path="--password <password>" type="string">
Autentikasi kata sandi untuk pemeriksaan.
Autentikasi kata sandi untuk probe.
</ParamField>
<ParamField path="--timeout <ms>" type="number" default="10000">
Batas waktu pemeriksaan.
Timeout probe.
</ParamField>
<ParamField path="--no-probe" type="boolean">
Lewati pemeriksaan konektivitas (tampilan khusus layanan).
Lewati probe konektivitas (tampilan layanan saja).
</ParamField>
<ParamField path="--deep" type="boolean">
Pindai juga layanan tingkat sistem.
</ParamField>
<ParamField path="--require-rpc" type="boolean">
Tingkatkan pemeriksaan konektivitas default menjadi pemeriksaan baca dan keluar dengan nilai bukan nol saat pemeriksaan baca tersebut gagal. Tidak dapat digabungkan dengan `--no-probe`.
Tingkatkan probe konektivitas default menjadi probe baca dan keluar dengan nilai non-zero ketika probe baca itu gagal. Tidak dapat digabungkan dengan `--no-probe`.
</ParamField>
<AccordionGroup>
<Accordion title="Semantik status">
- `gateway status` tetap tersedia untuk diagnostik meskipun konfigurasi CLI lokal hilang atau tidak valid.
- `gateway status` default membuktikan status layanan, koneksi WebSocket, dan kapabilitas autentikasi yang terlihat saat handshake. Ini tidak membuktikan operasi baca/tulis/admin.
- Pemeriksaan diagnostik tidak mengubah apa pun untuk autentikasi perangkat pertama kali: pemeriksaan menggunakan ulang token perangkat yang sudah ada di cache saat tersedia, tetapi tidak membuat identitas perangkat CLI baru atau catatan pairing perangkat baca-saja hanya untuk memeriksa status.
- `gateway status` menyelesaikan SecretRefs autentikasi yang dikonfigurasi untuk autentikasi pemeriksaan jika memungkinkan.
- Jika SecretRef autentikasi yang diperlukan tidak terselesaikan di jalur perintah ini, `gateway status --json` melaporkan `rpc.authWarning` saat konektivitas/autentikasi pemeriksaan gagal; teruskan `--token`/`--password` secara eksplisit atau selesaikan sumber rahasia terlebih dahulu.
- Jika pemeriksaan berhasil, peringatan auth-ref yang belum terselesaikan disembunyikan untuk menghindari positif palsu.
- Gunakan `--require-rpc` dalam skrip dan otomatisasi saat layanan yang mendengarkan saja tidak cukup dan Anda juga memerlukan panggilan RPC cakupan baca yang sehat.
- `--deep` menambahkan pemindaian upaya terbaik untuk instalasi launchd/systemd/schtasks tambahan. Saat beberapa layanan mirip gateway terdeteksi, output manusia mencetak petunjuk pembersihan dan memperingatkan bahwa sebagian besar penyiapan sebaiknya menjalankan satu gateway per mesin.
- Output manusia menyertakan jalur log file yang terselesaikan ditambah snapshot jalur/validitas konfigurasi CLI-vs-layanan untuk membantu mendiagnosis penyimpangan profil atau state-dir.
- `gateway status` default membuktikan status layanan, koneksi WebSocket, dan kapabilitas autentikasi yang terlihat pada waktu handshake. Ini tidak membuktikan operasi baca/tulis/admin.
- Probe diagnostik tidak melakukan mutasi untuk autentikasi perangkat pertama kali: probe menggunakan kembali token perangkat yang sudah di-cache jika ada, tetapi tidak membuat identitas perangkat CLI baru atau catatan pairing perangkat read-only hanya untuk memeriksa status.
- `gateway status` menyelesaikan SecretRefs autentikasi yang dikonfigurasi untuk autentikasi probe bila memungkinkan.
- Jika SecretRef autentikasi yang diperlukan tidak terselesaikan di jalur perintah ini, `gateway status --json` melaporkan `rpc.authWarning` ketika konektivitas/autentikasi probe gagal; berikan `--token`/`--password` secara eksplisit atau selesaikan sumber secret terlebih dahulu.
- Jika probe berhasil, peringatan auth-ref yang tidak terselesaikan disembunyikan untuk menghindari false positive.
- Gunakan `--require-rpc` di skrip dan otomatisasi ketika layanan yang listening saja tidak cukup dan Anda juga perlu panggilan RPC cakupan baca dalam kondisi sehat.
- `--deep` menambahkan pemindaian best-effort untuk instalasi launchd/systemd/schtasks tambahan. Ketika beberapa layanan mirip Gateway terdeteksi, output manusia mencetak petunjuk pembersihan dan memperingatkan bahwa sebagian besar setup sebaiknya menjalankan satu Gateway per mesin.
- Output manusia menyertakan path log file yang terselesaikan plus snapshot path/validitas konfigurasi CLI-vs-layanan untuk membantu mendiagnosis drift profil atau state-dir.
</Accordion>
<Accordion title="Pemeriksaan penyimpangan autentikasi systemd Linux">
- Pada instalasi systemd Linux, pemeriksaan penyimpangan autentikasi layanan membaca nilai `Environment=` dan `EnvironmentFile=` dari unit (termasuk `%h`, jalur bertanda kutip, beberapa file, dan file opsional `-`).
- Pemeriksaan penyimpangan menyelesaikan SecretRefs `gateway.auth.token` menggunakan env runtime gabungan (env perintah layanan terlebih dahulu, lalu fallback env proses).
- Jika autentikasi token tidak aktif secara efektif (`gateway.auth.mode` eksplisit berupa `password`/`none`/`trusted-proxy`, atau mode tidak diatur ketika kata sandi dapat menang dan tidak ada kandidat token yang dapat menang), pemeriksaan token-drift melewati penyelesaian token konfigurasi.
<Accordion title="Pemeriksaan auth-drift Linux systemd">
- Pada instalasi Linux systemd, pemeriksaan drift autentikasi layanan membaca nilai `Environment=` dan `EnvironmentFile=` dari unit (termasuk `%h`, path yang dikutip, beberapa file, dan file opsional `-`).
- Pemeriksaan drift menyelesaikan SecretRefs `gateway.auth.token` menggunakan env runtime gabungan (env perintah layanan terlebih dahulu, lalu fallback env proses).
- Jika autentikasi token tidak aktif secara efektif (`gateway.auth.mode` eksplisit berupa `password`/`none`/`trusted-proxy`, atau mode tidak disetel ketika kata sandi dapat menang dan tidak ada kandidat token yang dapat menang), pemeriksaan token-drift melewati resolusi token konfigurasi.
</Accordion>
</AccordionGroup>
### `gateway probe`
`gateway probe` adalah perintah "debug semuanya". Perintah ini selalu memeriksa:
`gateway probe` adalah perintah "debug semuanya". Perintah ini selalu mem-probe:
- gateway remote yang Anda konfigurasi (jika diatur), dan
- Gateway remote Anda yang dikonfigurasi (jika disetel), dan
- localhost (loopback) **meskipun remote dikonfigurasi**.
Jika Anda meneruskan `--url`, target eksplisit tersebut ditambahkan di depan keduanya. Output manusia melabeli target sebagai:
Jika Anda memberikan `--url`, target eksplisit itu ditambahkan di depan keduanya. Output manusia memberi label target sebagai:
- `URL (explicit)`
- `Remote (configured)` atau `Remote (configured, inactive)`
- `URL (eksplisit)`
- `Remote (dikonfigurasi)` atau `Remote (dikonfigurasi, tidak aktif)`
- `Local loopback`
<Note>
Jika beberapa gateway dapat dijangkau, perintah ini mencetak semuanya. Beberapa gateway didukung saat Anda menggunakan profil/port terisolasi (misalnya, bot penyelamat), tetapi sebagian besar instalasi tetap menjalankan satu gateway.
Jika beberapa Gateway dapat dijangkau, perintah ini mencetak semuanya. Beberapa Gateway didukung ketika Anda menggunakan profil/port terisolasi (misalnya, bot penyelamat), tetapi sebagian besar instalasi tetap menjalankan satu Gateway.
</Note>
```bash
@ -338,50 +338,50 @@ openclaw gateway probe --json
<AccordionGroup>
<Accordion title="Interpretasi">
- `Reachable: yes` berarti setidaknya satu target menerima koneksi WebSocket.
- `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` melaporkan apa yang dapat dibuktikan pemeriksaan tentang autentikasi. Ini terpisah dari keterjangkauan.
- `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` melaporkan apa yang dapat dibuktikan probe tentang autentikasi. Ini terpisah dari keterjangkauan.
- `Read probe: ok` berarti panggilan RPC detail cakupan baca (`health`/`status`/`system-presence`/`config.get`) juga berhasil.
- `Read probe: limited - missing scope: operator.read` berarti koneksi berhasil tetapi RPC cakupan baca terbatas. Ini dilaporkan sebagai keterjangkauan **terdegradasi**, bukan kegagalan penuh.
- `Read probe: failed` setelah `Connect: ok` berarti Gateway menerima koneksi WebSocket, tetapi diagnostik baca lanjutan mengalami waktu habis atau gagal. Ini juga merupakan keterjangkauan **terdegradasi**, bukan Gateway yang tidak dapat dijangkau.
- Seperti `gateway status`, pemeriksaan menggunakan ulang autentikasi perangkat yang sudah ada di cache tetapi tidak membuat identitas perangkat pertama kali atau status pairing.
- Kode keluar bukan nol hanya saat tidak ada target yang diperiksa dapat dijangkau.
- `Read probe: failed` setelah `Connect: ok` berarti Gateway menerima koneksi WebSocket, tetapi diagnostik baca lanjutan timeout atau gagal. Ini juga merupakan keterjangkauan **terdegradasi**, bukan Gateway yang tidak dapat dijangkau.
- Seperti `gateway status`, probe menggunakan kembali autentikasi perangkat yang sudah di-cache tetapi tidak membuat identitas perangkat pertama kali atau status pairing.
- Kode keluar bernilai non-zero hanya ketika tidak ada target yang di-probe yang dapat dijangkau.
</Accordion>
<Accordion title="Output JSON">
Tingkat teratas:
Tingkat atas:
- `ok`: setidaknya satu target dapat dijangkau.
- `degraded`: setidaknya satu target menerima koneksi tetapi tidak menyelesaikan diagnostik RPC detail penuh.
- `capability`: kapabilitas terbaik yang terlihat di seluruh target yang dapat dijangkau (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope`, atau `unknown`).
- `primaryTargetId`: target terbaik untuk dianggap sebagai pemenang aktif dalam urutan ini: URL eksplisit, tunnel SSH, remote yang dikonfigurasi, lalu local loopback.
- `warnings[]`: catatan peringatan upaya terbaik dengan `code`, `message`, dan `targetIds` opsional.
- `primaryTargetId`: target terbaik untuk diperlakukan sebagai pemenang aktif dalam urutan ini: URL eksplisit, tunnel SSH, remote yang dikonfigurasi, lalu local loopback.
- `warnings[]`: catatan peringatan best-effort dengan `code`, `message`, dan `targetIds` opsional.
- `network`: petunjuk URL local loopback/tailnet yang diturunkan dari konfigurasi saat ini dan jaringan host.
- `discovery.timeoutMs` dan `discovery.count`: anggaran/jumlah hasil discovery aktual yang digunakan untuk lintasan pemeriksaan ini.
- `discovery.timeoutMs` dan `discovery.count`: anggaran discovery/jumlah hasil aktual yang digunakan untuk pass probe ini.
Per target (`targets[].connect`):
- `ok`: keterjangkauan setelah klasifikasi connect + degraded.
- `ok`: keterjangkauan setelah connect + klasifikasi terdegradasi.
- `rpcOk`: keberhasilan RPC detail penuh.
- `scopeLimited`: RPC detail gagal karena cakupan operator hilang.
- `scopeLimited`: RPC detail gagal karena cakupan operator tidak ada.
Per target (`targets[].auth`):
- `role`: peran autentikasi yang dilaporkan di `hello-ok` saat tersedia.
- `scopes`: cakupan yang diberikan dan dilaporkan di `hello-ok` saat tersedia.
- `role`: peran autentikasi yang dilaporkan dalam `hello-ok` bila tersedia.
- `scopes`: cakupan yang diberikan yang dilaporkan dalam `hello-ok` bila tersedia.
- `capability`: klasifikasi kapabilitas autentikasi yang ditampilkan untuk target tersebut.
</Accordion>
<Accordion title="Kode peringatan umum">
- `ssh_tunnel_failed`: penyiapan tunnel SSH gagal; perintah beralih kembali ke pemeriksaan langsung.
- `ssh_tunnel_failed`: setup tunnel SSH gagal; perintah fallback ke probe langsung.
- `multiple_gateways`: lebih dari satu target dapat dijangkau; ini tidak biasa kecuali Anda sengaja menjalankan profil terisolasi, seperti bot penyelamat.
- `auth_secretref_unresolved`: SecretRef autentikasi yang dikonfigurasi tidak dapat diselesaikan untuk target yang gagal.
- `probe_scope_limited`: koneksi WebSocket berhasil, tetapi pemeriksaan baca dibatasi oleh `operator.read` yang hilang.
- `probe_scope_limited`: koneksi WebSocket berhasil, tetapi probe baca dibatasi oleh `operator.read` yang tidak ada.
</Accordion>
</AccordionGroup>
#### Remote melalui SSH (paritas aplikasi Mac)
Mode "Remote melalui SSH" aplikasi macOS menggunakan port-forward lokal sehingga gateway remote (yang mungkin hanya terikat ke loopback) dapat dijangkau di `ws://127.0.0.1:<port>`.
Mode "Remote over SSH" aplikasi macOS menggunakan port-forward lokal sehingga Gateway remote (yang mungkin hanya terikat ke loopback) dapat dijangkau di `ws://127.0.0.1:<port>`.
Padanan CLI:
@ -396,7 +396,7 @@ openclaw gateway probe --ssh user@gateway-host
File identitas.
</ParamField>
<ParamField path="--ssh-auto" type="boolean">
Pilih host gateway pertama yang ditemukan sebagai target SSH dari endpoint discovery yang terselesaikan (`local.` ditambah domain area luas yang dikonfigurasi, jika ada). Petunjuk khusus TXT diabaikan.
Pilih host Gateway pertama yang ditemukan sebagai target SSH dari endpoint discovery yang terselesaikan (`local.` plus domain wide-area yang dikonfigurasi, jika ada). Petunjuk khusus TXT diabaikan.
</ParamField>
Konfigurasi (opsional, digunakan sebagai default):
@ -426,10 +426,10 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
Kata sandi Gateway.
</ParamField>
<ParamField path="--timeout <ms>" type="number">
Anggaran waktu habis.
Anggaran timeout.
</ParamField>
<ParamField path="--expect-final" type="boolean">
Terutama untuk RPC bergaya agen yang mengalirkan peristiwa perantara sebelum payload final.
Terutama untuk RPC bergaya agent yang melakukan stream event antara sebelum payload final.
</ParamField>
<ParamField path="--json" type="boolean">
Output JSON yang dapat dibaca mesin.
@ -451,7 +451,7 @@ openclaw gateway uninstall
### Instal dengan wrapper
Gunakan `--wrapper` saat layanan terkelola harus dimulai melalui executable lain, misalnya shim manajer rahasia atau helper run-as. Wrapper menerima argumen Gateway normal dan bertanggung jawab untuk akhirnya mengeksekusi `openclaw` atau Node dengan argumen tersebut.
Gunakan `--wrapper` ketika layanan terkelola harus dimulai melalui executable lain, misalnya shim pengelola secret atau helper run-as. Wrapper menerima argumen Gateway normal dan bertanggung jawab untuk pada akhirnya menjalankan exec `openclaw` atau Node dengan argumen tersebut.
```bash
cat > ~/.local/bin/openclaw-doppler <<'EOF'
@ -465,7 +465,7 @@ openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --force
openclaw gateway restart
```
Anda juga dapat mengatur wrapper melalui environment. `gateway install` memvalidasi bahwa jalur tersebut adalah file executable, menulis wrapper ke `ProgramArguments` layanan, dan mempertahankan `OPENCLAW_WRAPPER` di environment layanan untuk instalasi ulang paksa, pembaruan, dan perbaikan doctor berikutnya.
Anda juga dapat menyetel wrapper melalui environment. `gateway install` memvalidasi bahwa path adalah file executable, menulis wrapper ke `ProgramArguments` layanan, dan mempertahankan `OPENCLAW_WRAPPER` di environment layanan untuk reinstall paksa, pembaruan, dan perbaikan doctor berikutnya.
```bash
OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --force
@ -483,23 +483,24 @@ openclaw gateway restart
<Accordion title="Opsi perintah">
- `gateway status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json`
- `gateway install`: `--port`, `--runtime <node|bun>`, `--token`, `--wrapper <path>`, `--force`, `--json`
- `gateway restart`: `--force`, `--wait <duration>`, `--json`
- `gateway restart`: `--safe`, `--force`, `--wait <duration>`, `--json`
- `gateway uninstall|start|stop`: `--json`
</Accordion>
<Accordion title="Perilaku siklus hidup">
- Gunakan `gateway restart` untuk memulai ulang layanan terkelola. Jangan merangkai `gateway stop` dan `gateway start` sebagai pengganti restart; di macOS, `gateway stop` sengaja menonaktifkan LaunchAgent sebelum menghentikannya.
- `gateway restart --wait 30s` mengganti anggaran drain restart yang dikonfigurasi untuk restart tersebut. Angka tanpa unit adalah milidetik; unit seperti `s`, `m`, dan `h` diterima. `--wait 0` menunggu tanpa batas.
- `gateway restart --force` melewati drain pekerjaan aktif dan langsung memulai ulang. Gunakan ini saat operator sudah memeriksa pemblokir tugas yang tercantum dan menginginkan gateway kembali sekarang.
- `gateway restart --safe` meminta Gateway yang sedang berjalan untuk melakukan preflight pekerjaan OpenClaw aktif dan menunda restart sampai pengiriman balasan, run tertanam, dan run tugas selesai. `--safe` tidak dapat digabungkan dengan `--force` atau `--wait`.
- `gateway restart --wait 30s` mengesampingkan anggaran drain restart yang dikonfigurasi untuk restart tersebut. Angka tanpa satuan berarti milidetik; satuan seperti `s`, `m`, dan `h` diterima. `--wait 0` menunggu tanpa batas waktu.
- `gateway restart --force` melewati drain pekerjaan aktif dan langsung memulai ulang. Gunakan ini ketika operator sudah memeriksa blocker tugas yang terdaftar dan menginginkan Gateway kembali sekarang.
- Perintah siklus hidup menerima `--json` untuk scripting.
</Accordion>
<Accordion title="Autentikasi dan SecretRefs saat instalasi">
- Saat autentikasi token memerlukan token dan `gateway.auth.token` dikelola SecretRef, `gateway install` memvalidasi bahwa SecretRef dapat diselesaikan tetapi tidak mempertahankan token yang terselesaikan ke metadata environment layanan.
- Jika autentikasi token memerlukan token dan SecretRef token yang dikonfigurasi tidak terselesaikan, instalasi gagal tertutup alih-alih mempertahankan fallback plaintext.
- Untuk autentikasi kata sandi pada `gateway run`, pilih `OPENCLAW_GATEWAY_PASSWORD`, `--password-file`, atau `gateway.auth.password` berbasis SecretRef daripada `--password` inline.
- Dalam mode autentikasi tersimpul, `OPENCLAW_GATEWAY_PASSWORD` yang hanya ada di shell tidak melonggarkan persyaratan token instalasi; gunakan konfigurasi tahan lama (`gateway.auth.password` atau `env` konfigurasi) saat menginstal layanan terkelola.
- Jika `gateway.auth.token` dan `gateway.auth.password` sama-sama dikonfigurasi dan `gateway.auth.mode` tidak diatur, instalasi diblokir sampai mode diatur secara eksplisit.
- Ketika autentikasi token memerlukan token dan `gateway.auth.token` dikelola SecretRef, `gateway install` memvalidasi bahwa SecretRef dapat di-resolve tetapi tidak menyimpan token yang sudah di-resolve ke metadata lingkungan layanan.
- Jika autentikasi token memerlukan token dan SecretRef token yang dikonfigurasi belum ter-resolve, instalasi gagal secara tertutup alih-alih menyimpan fallback teks biasa.
- Untuk autentikasi kata sandi pada `gateway run`, utamakan `OPENCLAW_GATEWAY_PASSWORD`, `--password-file`, atau `gateway.auth.password` berbasis SecretRef daripada `--password` inline.
- Dalam mode autentikasi yang disimpulkan, `OPENCLAW_GATEWAY_PASSWORD` khusus shell tidak melonggarkan persyaratan token instalasi; gunakan konfigurasi tahan lama (`gateway.auth.password` atau `env` konfigurasi) saat menginstal layanan terkelola.
- Jika `gateway.auth.token` dan `gateway.auth.password` sama-sama dikonfigurasi dan `gateway.auth.mode` belum ditetapkan, instalasi diblokir hingga mode ditetapkan secara eksplisit.
</Accordion>
</AccordionGroup>
@ -509,19 +510,19 @@ openclaw gateway restart
`gateway discover` memindai beacon Gateway (`_openclaw-gw._tcp`).
- DNS-SD multicast: `local.`
- DNS-SD unicast (Bonjour area luas): pilih domain (contoh: `openclaw.internal.`) dan siapkan DNS split + server DNS; lihat [Bonjour](/id/gateway/bonjour).
- DNS-SD unicast (Wide-Area Bonjour): pilih domain (contoh: `openclaw.internal.`) dan siapkan DNS terbagi + server DNS; lihat [Bonjour](/id/gateway/bonjour).
Hanya Gateway dengan penemuan Bonjour yang diaktifkan (default) yang mengiklankan beacon.
Hanya gateway dengan penemuan Bonjour yang diaktifkan (default) yang mengiklankan beacon.
Rekaman penemuan area luas mencakup (TXT):
Catatan penemuan Wide-Area mencakup (TXT):
- `role` (petunjuk peran Gateway)
- `role` (petunjuk peran gateway)
- `transport` (petunjuk transport, mis. `gateway`)
- `gatewayPort` (port WebSocket, biasanya `18789`)
- `sshPort` (opsional; klien menetapkan target SSH default ke `22` saat tidak ada)
- `tailnetDns` (nama host MagicDNS, bila tersedia)
- `sshPort` (opsional; klien menggunakan target SSH default `22` saat ini tidak ada)
- `tailnetDns` (nama host MagicDNS, jika tersedia)
- `gatewayTls` / `gatewayTlsSha256` (TLS diaktifkan + sidik jari sertifikat)
- `cliPath` (petunjuk pemasangan jarak jauh yang ditulis ke zona area luas)
- `cliPath` (petunjuk instalasi jarak jauh yang ditulis ke zona wide-area)
### `gateway discover`
@ -530,10 +531,10 @@ openclaw gateway discover
```
<ParamField path="--timeout <ms>" type="number" default="2000">
Batas waktu perintah (browse/resolve).
Timeout per perintah (browse/resolve).
</ParamField>
<ParamField path="--json" type="boolean">
Keluaran yang dapat dibaca mesin (juga menonaktifkan styling/spinner).
Output yang dapat dibaca mesin (juga menonaktifkan styling/spinner).
</ParamField>
Contoh:
@ -544,9 +545,9 @@ openclaw gateway discover --json | jq '.beacons[].wsUrl'
```
<Note>
- CLI memindai `local.` ditambah domain area luas yang dikonfigurasi saat salah satunya diaktifkan.
- `wsUrl` dalam keluaran JSON diturunkan dari endpoint layanan yang berhasil di-resolve, bukan dari petunjuk khusus TXT seperti `lanHost` atau `tailnetDns`.
- Pada mDNS `local.`, `sshPort` dan `cliPath` hanya disiarkan saat `discovery.mdns.mode` adalah `full`. DNS-SD area luas tetap menulis `cliPath`; `sshPort` juga tetap opsional di sana.
- CLI memindai `local.` ditambah domain wide-area yang dikonfigurasi saat ada yang diaktifkan.
- `wsUrl` dalam output JSON diturunkan dari endpoint layanan yang di-resolve, bukan dari petunjuk khusus TXT seperti `lanHost` atau `tailnetDns`.
- Pada mDNS `local.`, `sshPort` dan `cliPath` hanya disiarkan saat `discovery.mdns.mode` adalah `full`. DNS-SD Wide-area tetap menulis `cliPath`; `sshPort` juga tetap opsional di sana.
</Note>

217
docs/id/cli/plugins.md
View File

@ -1,36 +1,36 @@
---
read_when:
- Anda ingin memasang atau mengelola Plugin Gateway atau bundel yang kompatibel
- Anda ingin menginstal atau mengelola Plugin Gateway atau bundel yang kompatibel
- Anda ingin men-debug kegagalan pemuatan Plugin
sidebarTitle: Plugins
summary: Referensi CLI untuk `openclaw plugins` (daftar, instal, marketplace, hapus instalasi, aktifkan/nonaktifkan, doctor)
summary: Referensi CLI untuk `openclaw plugins` (list, install, marketplace, uninstall, enable/disable, doctor)
title: Plugin
x-i18n:
generated_at: "2026-05-04T09:33:28Z"
generated_at: "2026-05-05T01:44:23Z"
model: gpt-5.5
provider: openai
source_hash: f561ce098181b07f25db3520b1726162863469ac05fb4a3e786915257d97c9a4
source_hash: 24d274f33213231eaed48ac848a9266802a2179ba0311ab18462ad783219095a
source_path: cli/plugins.md
workflow: 16
---
Kelola Plugin Gateway, paket hook, dan bundle yang kompatibel.
Kelola Plugin Gateway, paket hook, dan bundel yang kompatibel.
<CardGroup cols={2}>
<Card title="Sistem Plugin" href="/id/tools/plugin">
Panduan pengguna akhir untuk menginstal, mengaktifkan, dan memecahkan masalah Plugin.
Panduan pengguna akhir untuk memasang, mengaktifkan, dan memecahkan masalah plugin.
</Card>
<Card title="Kelola Plugin" href="/id/plugins/manage-plugins">
Contoh cepat untuk install, list, update, uninstall, dan penerbitan.
<Card title="Kelola plugin" href="/id/plugins/manage-plugins">
Contoh cepat untuk memasang, mencantumkan, memperbarui, menghapus pemasangan, dan menerbitkan.
</Card>
<Card title="Bundle Plugin" href="/id/plugins/bundles">
Model kompatibilitas bundle.
<Card title="Bundel Plugin" href="/id/plugins/bundles">
Model kompatibilitas bundel.
</Card>
<Card title="Manifest Plugin" href="/id/plugins/manifest">
Bidang manifest dan skema konfigurasi.
Bidang manifest dan skema config.
</Card>
<Card title="Keamanan" href="/id/gateway/security">
Penguatan keamanan untuk instalasi Plugin.
Pengerasan keamanan untuk pemasangan plugin.
</Card>
</CardGroup>
@ -62,19 +62,19 @@ openclaw plugins marketplace list <marketplace>
openclaw plugins marketplace list <marketplace> --json
```
Untuk investigasi instalasi, inspeksi, uninstall, atau penyegaran registri yang lambat, jalankan
perintah dengan `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`. Trace menulis waktu fase
ke stderr dan menjaga keluaran JSON tetap dapat diurai. Lihat [Debugging](/id/help/debugging#plugin-lifecycle-trace).
Untuk investigasi pemasangan, inspeksi, penghapusan pemasangan, atau penyegaran registry yang lambat, jalankan
perintah dengan `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`. Trace menulis timing fase
ke stderr dan menjaga output JSON tetap dapat di-parse. Lihat [Debugging](/id/help/debugging#plugin-lifecycle-trace).
<Note>
Plugin bawaan dikirim bersama OpenClaw. Beberapa diaktifkan secara default (misalnya penyedia model bawaan, penyedia ucapan bawaan, dan Plugin browser bawaan); yang lain memerlukan `plugins enable`.
Plugin bawaan dikirim bersama OpenClaw. Sebagian diaktifkan secara default (misalnya penyedia model bawaan, penyedia speech bawaan, dan plugin browser bawaan); yang lain memerlukan `plugins enable`.
Plugin OpenClaw native harus mengirim `openclaw.plugin.json` dengan JSON Schema inline (`configSchema`, meskipun kosong). Bundle kompatibel menggunakan manifest bundle mereka sendiri sebagai gantinya.
Plugin OpenClaw native harus menyertakan `openclaw.plugin.json` dengan JSON Schema inline (`configSchema`, meskipun kosong). Bundel yang kompatibel menggunakan manifest bundelnya sendiri.
`plugins list` menampilkan `Format: openclaw` atau `Format: bundle`. Keluaran list/info verbose juga menampilkan subtipe bundle (`codex`, `claude`, atau `cursor`) beserta kemampuan bundle yang terdeteksi.
`plugins list` menampilkan `Format: openclaw` atau `Format: bundle`. Output list/info verbose juga menampilkan subtipe bundel (`codex`, `claude`, atau `cursor`) plus kapabilitas bundel yang terdeteksi.
</Note>
### Install
### Pasang
```bash
openclaw plugins search "calendar" # search ClawHub plugins
@ -93,83 +93,83 @@ openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo
```
<Warning>
Nama paket polos diinstal dari npm secara default selama peralihan peluncuran. Gunakan `clawhub:<package>` untuk ClawHub. Perlakukan instalasi Plugin seperti menjalankan kode. Utamakan versi yang dipin.
Nama paket bare dipasang dari npm secara default selama cutover peluncuran. Gunakan `clawhub:<package>` untuk ClawHub. Perlakukan pemasangan plugin seperti menjalankan kode. Utamakan versi yang di-pin.
</Warning>
`plugins search` mengueri ClawHub untuk paket Plugin yang dapat diinstal dan mencetak
nama paket yang siap diinstal. Ini mencari paket code-plugin dan bundle-plugin,
`plugins search` mengkueri ClawHub untuk paket plugin yang dapat dipasang dan mencetak
nama paket yang siap dipasang. Perintah ini mencari paket code-plugin dan bundle-plugin,
bukan Skills. Gunakan `openclaw skills search` untuk Skills ClawHub.
<Note>
ClawHub adalah permukaan distribusi dan penemuan utama untuk sebagian besar Plugin. Npm
tetap menjadi fallback dan jalur instalasi langsung yang didukung. Paket Plugin milik OpenClaw
`@openclaw/*` diterbitkan kembali di npm; lihat daftar saat ini
ClawHub adalah permukaan distribusi dan discovery utama untuk sebagian besar plugin. Npm
tetap menjadi fallback dan jalur pemasangan langsung yang didukung. Paket plugin
`@openclaw/*` milik OpenClaw diterbitkan di npm lagi; lihat daftar saat ini
di [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) atau
[inventaris Plugin](/id/plugins/plugin-inventory). Instalasi stabil menggunakan `latest`.
Instalasi dan pembaruan kanal beta mengutamakan dist-tag npm `beta` ketika tag tersebut
[inventaris plugin](/id/plugins/plugin-inventory). Pemasangan stabil menggunakan `latest`.
Pemasangan dan pembaruan kanal beta mengutamakan dist-tag npm `beta` saat tag tersebut
tersedia, lalu fallback ke `latest`.
</Note>
<AccordionGroup>
<Accordion title="Config includes and invalid-config repair">
Jika bagian `plugins` Anda didukung oleh `$include` satu file, `plugins install/update/enable/disable/uninstall` menulis melalui file yang disertakan tersebut dan membiarkan `openclaw.json` tidak berubah. Include root, array include, dan include dengan override saudara gagal secara tertutup alih-alih diratakan. Lihat [Include konfigurasi](/id/gateway/configuration) untuk bentuk yang didukung.
<Accordion title="Config includes dan perbaikan config tidak valid">
Jika bagian `plugins` Anda didukung oleh `$include` satu file, `plugins install/update/enable/disable/uninstall` menulis melalui file yang disertakan itu dan membiarkan `openclaw.json` tidak tersentuh. Include root, array include, dan include dengan override sibling gagal tertutup alih-alih diratakan. Lihat [Config includes](/id/gateway/configuration) untuk bentuk yang didukung.
Jika konfigurasi tidak valid saat instalasi, `plugins install` biasanya gagal secara tertutup dan meminta Anda menjalankan `openclaw doctor --fix` terlebih dahulu. Selama startup Gateway dan hot reload, konfigurasi Plugin yang tidak valid gagal secara tertutup seperti konfigurasi tidak valid lainnya; `openclaw doctor --fix` dapat mengarantina entri Plugin yang tidak valid. Satu-satunya pengecualian waktu instalasi yang terdokumentasi adalah jalur pemulihan sempit untuk Plugin bawaan bagi Plugin yang secara eksplisit memilih ikut ke `openclaw.install.allowInvalidConfigRecovery`.
Jika config tidak valid selama pemasangan, `plugins install` biasanya gagal tertutup dan meminta Anda menjalankan `openclaw doctor --fix` terlebih dahulu. Selama startup Gateway dan hot reload, config plugin yang tidak valid gagal tertutup seperti config tidak valid lainnya; `openclaw doctor --fix` dapat mengkarantina entri plugin yang tidak valid. Satu-satunya pengecualian waktu pemasangan yang terdokumentasi adalah jalur pemulihan plugin bawaan yang sempit untuk plugin yang secara eksplisit ikut serta dalam `openclaw.install.allowInvalidConfigRecovery`.
</Accordion>
<Accordion title="--force and reinstall vs update">
`--force` menggunakan kembali target instalasi yang ada dan menimpa Plugin atau paket hook yang sudah terinstal di tempat. Gunakan ketika Anda sengaja menginstal ulang id yang sama dari jalur lokal, arsip, paket ClawHub, atau artefak npm baru. Untuk peningkatan rutin Plugin npm yang sudah dilacak, utamakan `openclaw plugins update <id-or-npm-spec>`.
<Accordion title="--force dan pemasangan ulang vs pembaruan">
`--force` menggunakan kembali target pemasangan yang ada dan menimpa plugin atau paket hook yang sudah terpasang di tempatnya. Gunakan ini saat Anda sengaja memasang ulang id yang sama dari jalur lokal, arsip, paket ClawHub, atau artefak npm baru. Untuk upgrade rutin plugin npm yang sudah dilacak, utamakan `openclaw plugins update <id-or-npm-spec>`.
Jika Anda menjalankan `plugins install` untuk id Plugin yang sudah terinstal, OpenClaw berhenti dan mengarahkan Anda ke `plugins update <id-or-npm-spec>` untuk peningkatan normal, atau ke `plugins install <package> --force` ketika Anda benar-benar ingin menimpa instalasi saat ini dari sumber lain.
Jika Anda menjalankan `plugins install` untuk id plugin yang sudah terpasang, OpenClaw berhenti dan mengarahkan Anda ke `plugins update <id-or-npm-spec>` untuk upgrade normal, atau ke `plugins install <package> --force` saat Anda benar-benar ingin menimpa pemasangan saat ini dari sumber lain.
</Accordion>
<Accordion title="--pin scope">
`--pin` hanya berlaku untuk instalasi npm. Ini tidak didukung dengan instalasi `git:`; gunakan ref git eksplisit seperti `git:github.com/acme/plugin@v1.2.3` ketika Anda menginginkan sumber yang dipin. Ini tidak didukung dengan `--marketplace`, karena instalasi marketplace mempertahankan metadata sumber marketplace alih-alih spesifikasi npm.
<Accordion title="Cakupan --pin">
`--pin` hanya berlaku untuk pemasangan npm. Ini tidak didukung dengan pemasangan `git:`; gunakan ref git eksplisit seperti `git:github.com/acme/plugin@v1.2.3` saat Anda menginginkan sumber yang di-pin. Ini tidak didukung dengan `--marketplace`, karena pemasangan marketplace mempertahankan metadata sumber marketplace alih-alih spec npm.
</Accordion>
<Accordion title="--dangerously-force-unsafe-install">
`--dangerously-force-unsafe-install` adalah opsi darurat untuk false positive dalam pemindai kode berbahaya bawaan. Ini memungkinkan instalasi berlanjut bahkan ketika pemindai bawaan melaporkan temuan `critical`, tetapi **tidak** melewati blok kebijakan hook `before_install` Plugin dan **tidak** melewati kegagalan pemindaian.
`--dangerously-force-unsafe-install` adalah opsi darurat untuk false positive di pemindai kode berbahaya bawaan. Opsi ini mengizinkan pemasangan berlanjut bahkan saat pemindai bawaan melaporkan temuan `critical`, tetapi **tidak** melewati blok kebijakan hook `before_install` plugin dan **tidak** melewati kegagalan pemindaian.
Flag CLI ini berlaku untuk alur install/update Plugin. Instalasi dependensi skill yang didukung Gateway menggunakan override permintaan `dangerouslyForceUnsafeInstall` yang sesuai, sementara `openclaw skills install` tetap merupakan alur unduh/install skill ClawHub yang terpisah.
Flag CLI ini berlaku untuk alur pemasangan/pembaruan plugin. Pemasangan dependensi skill yang didukung Gateway menggunakan override request `dangerouslyForceUnsafeInstall` yang sepadan, sedangkan `openclaw skills install` tetap menjadi alur unduh/pasang skill ClawHub yang terpisah.
Jika Plugin yang Anda terbitkan di ClawHub diblokir oleh pemindaian registri, gunakan langkah penerbit di [ClawHub](/id/tools/clawhub).
Jika plugin yang Anda terbitkan di ClawHub diblokir oleh pemindaian registry, gunakan langkah penerbit di [ClawHub](/id/tools/clawhub).
</Accordion>
<Accordion title="Hook packs and npm specs">
`plugins install` juga merupakan permukaan instalasi untuk paket hook yang mengekspos `openclaw.hooks` di `package.json`. Gunakan `openclaw hooks` untuk visibilitas hook terfilter dan pengaktifan per hook, bukan instalasi paket.
<Accordion title="Paket hook dan spec npm">
`plugins install` juga merupakan permukaan pemasangan untuk paket hook yang mengekspos `openclaw.hooks` di `package.json`. Gunakan `openclaw hooks` untuk visibilitas hook terfilter dan pengaktifan per hook, bukan pemasangan paket.
Spesifikasi npm **hanya registri** (nama paket + **versi persis** opsional atau **dist-tag**). Spesifikasi Git/URL/file dan rentang semver ditolak. Instalasi dependensi berjalan secara lokal proyek dengan `--ignore-scripts` demi keamanan, meskipun shell Anda memiliki pengaturan install npm global.
Spec npm bersifat **hanya registry** (nama paket + **versi persis** opsional atau **dist-tag**). Spec Git/URL/file dan rentang semver ditolak. Pemasangan dependensi berjalan project-local dengan `--ignore-scripts` demi keamanan, bahkan saat shell Anda memiliki pengaturan pemasangan npm global.
Gunakan `npm:<package>` ketika Anda ingin membuat resolusi npm eksplisit. Spesifikasi paket polos juga diinstal langsung dari npm selama peralihan peluncuran.
Gunakan `npm:<package>` saat Anda ingin membuat resolusi npm eksplisit. Spec paket bare juga dipasang langsung dari npm selama cutover peluncuran.
Spesifikasi polos dan `@latest` tetap berada di jalur stabil. Versi koreksi bertanggal OpenClaw seperti `2026.5.3-1` adalah rilis stabil untuk pemeriksaan ini. Jika npm menyelesaikan salah satunya ke prerelease, OpenClaw berhenti dan meminta Anda memilih ikut secara eksplisit dengan tag prerelease seperti `@beta`/`@rc` atau versi prerelease persis seperti `@1.2.3-beta.4`.
Spec bare dan `@latest` tetap berada di track stabil. Versi koreksi bertanggal OpenClaw seperti `2026.5.3-1` adalah rilis stabil untuk pemeriksaan ini. Jika npm me-resolve salah satunya ke prerelease, OpenClaw berhenti dan meminta Anda ikut serta secara eksplisit dengan tag prerelease seperti `@beta`/`@rc` atau versi prerelease persis seperti `@1.2.3-beta.4`.
Jika spesifikasi install polos cocok dengan id Plugin resmi (misalnya `diffs`), OpenClaw menginstal entri katalog secara langsung. Untuk menginstal paket npm dengan nama yang sama, gunakan spesifikasi scoped eksplisit (misalnya `@scope/diffs`).
Jika spec pemasangan bare cocok dengan id plugin resmi (misalnya `diffs`), OpenClaw memasang entri katalog secara langsung. Untuk memasang paket npm dengan nama yang sama, gunakan spec scoped eksplisit (misalnya `@scope/diffs`).
</Accordion>
<Accordion title="Git repositories">
Gunakan `git:<repo>` untuk menginstal langsung dari repositori git. Bentuk yang didukung mencakup `git:github.com/owner/repo`, `git:owner/repo`, URL clone penuh `https://`, `ssh://`, `git://`, `file://`, dan `git@host:owner/repo.git`. Tambahkan `@<ref>` atau `#<ref>` untuk check out branch, tag, atau commit sebelum instalasi.
<Accordion title="Repositori Git">
Gunakan `git:<repo>` untuk memasang langsung dari repositori git. Bentuk yang didukung mencakup `git:github.com/owner/repo`, `git:owner/repo`, URL clone lengkap `https://`, `ssh://`, `git://`, `file://`, dan `git@host:owner/repo.git`. Tambahkan `@<ref>` atau `#<ref>` untuk melakukan checkout branch, tag, atau commit sebelum pemasangan.
Instalasi Git meng-clone ke direktori sementara, check out ref yang diminta jika ada, lalu menggunakan installer direktori Plugin normal. Itu berarti validasi manifest, pemindaian kode berbahaya, pekerjaan install package-manager, dan catatan instalasi berperilaku seperti instalasi npm. Instalasi git yang tercatat mencakup URL/ref sumber plus commit yang di-resolve sehingga `openclaw plugins update` dapat me-resolve ulang sumber nanti.
Pemasangan git melakukan clone ke direktori sementara, melakukan checkout ref yang diminta jika ada, lalu menggunakan installer direktori plugin normal. Itu berarti validasi manifest, pemindaian kode berbahaya, pekerjaan pemasangan package-manager, dan record pemasangan berperilaku seperti pemasangan npm. Pemasangan git yang direkam mencakup URL/ref sumber plus commit yang di-resolve agar `openclaw plugins update` dapat me-resolve ulang sumber nanti.
Setelah menginstal dari git, gunakan `openclaw plugins inspect <id> --runtime --json` untuk memverifikasi registrasi runtime seperti metode Gateway dan perintah CLI. Jika Plugin mendaftarkan root CLI dengan `api.registerCli`, jalankan perintah itu langsung melalui CLI root OpenClaw, misalnya `openclaw demo-plugin ping`.
Setelah memasang dari git, gunakan `openclaw plugins inspect <id> --runtime --json` untuk memverifikasi registrasi runtime seperti metode gateway dan perintah CLI. Jika plugin mendaftarkan root CLI dengan `api.registerCli`, jalankan perintah itu langsung melalui root CLI OpenClaw, misalnya `openclaw demo-plugin ping`.
</Accordion>
<Accordion title="Archives">
Arsip yang didukung: `.zip`, `.tgz`, `.tar.gz`, `.tar`. Arsip Plugin OpenClaw native harus berisi `openclaw.plugin.json` yang valid di root Plugin yang diekstrak; arsip yang hanya berisi `package.json` ditolak sebelum OpenClaw menulis catatan instalasi.
<Accordion title="Arsip">
Arsip yang didukung: `.zip`, `.tgz`, `.tar.gz`, `.tar`. Arsip plugin OpenClaw native harus berisi `openclaw.plugin.json` yang valid di root plugin yang diekstrak; arsip yang hanya berisi `package.json` ditolak sebelum OpenClaw menulis record pemasangan.
Instalasi marketplace Claude juga didukung.
Pemasangan marketplace Claude juga didukung.
</Accordion>
</AccordionGroup>
Instalasi ClawHub menggunakan locator eksplisit `clawhub:<package>`:
Pemasangan ClawHub menggunakan locator `clawhub:<package>` eksplisit:
```bash
openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
```
Spesifikasi Plugin aman npm polos diinstal dari npm secara default selama peralihan peluncuran:
Spec plugin yang aman untuk npm secara bare dipasang dari npm secara default selama cutover peluncuran:
```bash
openclaw plugins install openclaw-codex-app-server
@ -182,19 +182,19 @@ openclaw plugins install npm:openclaw-codex-app-server
openclaw plugins install npm:@scope/plugin-name@1.0.1
```
OpenClaw memeriksa API Plugin yang diiklankan / kompatibilitas Gateway minimum sebelum instalasi. Ketika versi ClawHub yang dipilih menerbitkan artefak ClawPack, OpenClaw mengunduh `.tgz` npm-pack berversi, memverifikasi header digest ClawHub dan digest artefak, lalu menginstalnya melalui jalur arsip normal. Versi ClawHub lama tanpa metadata ClawPack tetap diinstal melalui jalur verifikasi arsip paket legacy. Instalasi yang tercatat mempertahankan metadata sumber ClawHub, jenis artefak, integritas npm, shasum npm, nama tarball, dan fakta digest ClawPack untuk pembaruan berikutnya.
Instalasi ClawHub tanpa versi mempertahankan spesifikasi tercatat tanpa versi sehingga `openclaw plugins update` dapat mengikuti rilis ClawHub yang lebih baru; pemilih versi atau tag eksplisit seperti `clawhub:pkg@1.2.3` dan `clawhub:pkg@beta` tetap dipin ke pemilih tersebut.
OpenClaw memeriksa kompatibilitas plugin API / minimum gateway yang diiklankan sebelum pemasangan. Saat versi ClawHub yang dipilih menerbitkan artefak ClawPack, OpenClaw mengunduh `.tgz` npm-pack berversi, memverifikasi header digest ClawHub dan digest artefak, lalu memasangnya melalui jalur arsip normal. Versi ClawHub lama tanpa metadata ClawPack tetap dipasang melalui jalur verifikasi arsip paket legacy. Pemasangan yang direkam menyimpan metadata sumber ClawHub, jenis artefak, integritas npm, shasum npm, nama tarball, dan fakta digest ClawPack untuk pembaruan nanti.
Pemasangan ClawHub tanpa versi menyimpan spec terekam tanpa versi agar `openclaw plugins update` dapat mengikuti rilis ClawHub yang lebih baru; selector versi atau tag eksplisit seperti `clawhub:pkg@1.2.3` dan `clawhub:pkg@beta` tetap di-pin ke selector tersebut.
#### Singkatan marketplace
#### Shorthand marketplace
Gunakan singkatan `plugin@marketplace` ketika nama marketplace ada di cache registri lokal Claude di `~/.claude/plugins/known_marketplaces.json`:
Gunakan shorthand `plugin@marketplace` saat nama marketplace ada di cache registry lokal Claude di `~/.claude/plugins/known_marketplaces.json`:
```bash
openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>
```
Gunakan `--marketplace` ketika Anda ingin meneruskan sumber marketplace secara eksplisit:
Gunakan `--marketplace` saat Anda ingin meneruskan sumber marketplace secara eksplisit:
```bash
openclaw plugins install <plugin-name> --marketplace <marketplace-name>
@ -205,27 +205,27 @@ openclaw plugins install <plugin-name> --marketplace ./my-marketplace
<Tabs>
<Tab title="Marketplace sources">
- nama marketplace Claude yang diketahui dari `~/.claude/plugins/known_marketplaces.json`
- root marketplace lokal atau jalur `marketplace.json`
- nama marketplace Claude yang dikenal dari `~/.claude/plugins/known_marketplaces.json`
- root marketplace lokal atau path `marketplace.json`
- singkatan repo GitHub seperti `owner/repo`
- URL repo GitHub seperti `https://github.com/owner/repo`
- URL git
</Tab>
<Tab title="Remote marketplace rules">
Untuk marketplace jarak jauh yang dimuat dari GitHub atau git, entri plugin harus tetap berada di dalam repo marketplace hasil kloning. OpenClaw menerima sumber jalur relatif dari repo tersebut dan menolak sumber plugin HTTP(S), jalur absolut, git, GitHub, dan sumber plugin non-jalur lainnya dari manifes jarak jauh.
Untuk marketplace jarak jauh yang dimuat dari GitHub atau git, entri plugin harus tetap berada di dalam repo marketplace yang dikloning. OpenClaw menerima sumber path relatif dari repo tersebut dan menolak sumber plugin HTTP(S), path absolut, git, GitHub, dan sumber plugin non-path lain dari manifes jarak jauh.
</Tab>
</Tabs>
Untuk jalur lokal dan arsip, OpenClaw mendeteksi otomatis:
Untuk path dan arsip lokal, OpenClaw mendeteksi otomatis:
- Plugin OpenClaw native (`openclaw.plugin.json`)
- bundel yang kompatibel dengan Codex (`.codex-plugin/plugin.json`)
- bundel yang kompatibel dengan Claude (`.claude-plugin/plugin.json` atau tata letak komponen Claude default)
- bundel yang kompatibel dengan Cursor (`.cursor-plugin/plugin.json`)
- plugin OpenClaw native (`openclaw.plugin.json`)
- bundle yang kompatibel dengan Codex (`.codex-plugin/plugin.json`)
- bundle yang kompatibel dengan Claude (`.claude-plugin/plugin.json` atau tata letak komponen Claude default)
- bundle yang kompatibel dengan Cursor (`.cursor-plugin/plugin.json`)
<Note>
Bundel yang kompatibel dipasang ke root plugin normal dan ikut serta dalam alur daftar/info/aktifkan/nonaktifkan yang sama. Saat ini, Skills bundel, command-skills Claude, default `settings.json` Claude, default `.lsp.json` Claude / `lspServers` yang dideklarasikan manifes, command-skills Cursor, dan direktori hook Codex yang kompatibel didukung; kapabilitas bundel terdeteksi lainnya ditampilkan dalam diagnostik/info tetapi belum dihubungkan ke eksekusi runtime.
Bundle yang kompatibel diinstal ke root plugin normal dan ikut dalam alur list/info/enable/disable yang sama. Saat ini, bundle skills, command-skills Claude, default `settings.json` Claude, default `.lsp.json` Claude / `lspServers` yang dideklarasikan manifes, command-skills Cursor, dan direktori hook Codex yang kompatibel didukung; kapabilitas bundle lain yang terdeteksi ditampilkan dalam diagnostik/info tetapi belum tersambung ke eksekusi runtime.
</Note>
### Daftar
@ -247,27 +247,34 @@ openclaw plugins search <query> --json
Beralih dari tampilan tabel ke baris detail per plugin dengan metadata sumber/asal/versi/aktivasi.
</ParamField>
<ParamField path="--json" type="boolean">
Inventaris yang dapat dibaca mesin plus diagnostik registri dan status pemasangan dependensi paket.
Inventaris yang dapat dibaca mesin plus diagnostik registry dan status instalasi dependensi paket.
</ParamField>
<Note>
`plugins list` membaca registri plugin lokal yang tersimpan terlebih dahulu, dengan fallback turunan berbasis manifes saja saat registri hilang atau tidak valid. Ini berguna untuk memeriksa apakah plugin terpasang, diaktifkan, dan terlihat oleh perencanaan startup dingin, tetapi ini bukan probe runtime langsung terhadap proses Gateway yang sudah berjalan. Setelah mengubah kode plugin, status aktif, kebijakan hook, atau `plugins.load.paths`, mulai ulang Gateway yang melayani channel sebelum mengharapkan kode `register(api)` atau hook baru berjalan. Untuk deployment jarak jauh/container, pastikan Anda memulai ulang child `openclaw gateway run` yang sebenarnya, bukan hanya proses wrapper.
`plugins list` membaca registry plugin lokal yang dipersist terlebih dahulu, dengan fallback turunan khusus manifes ketika registry hilang atau tidak valid. Ini berguna untuk memeriksa apakah plugin terinstal, diaktifkan, dan terlihat oleh perencanaan startup dingin, tetapi ini bukan probe runtime langsung dari proses Gateway yang sudah berjalan. Setelah mengubah kode plugin, enablement, kebijakan hook, atau `plugins.load.paths`, mulai ulang Gateway yang melayani channel sebelum mengharapkan kode `register(api)` atau hook baru berjalan. Untuk deployment jarak jauh/container, pastikan Anda memulai ulang child `openclaw gateway run` yang sebenarnya, bukan hanya proses wrapper.
`plugins list --json` menyertakan `dependencyStatus` setiap plugin dari `package.json`
`dependencies` dan `optionalDependencies`. OpenClaw memeriksa apakah nama paket tersebut
ada di sepanjang jalur pencarian Node `node_modules` normal milik plugin; ini
ada di sepanjang path lookup `node_modules` Node normal milik plugin; ia
tidak mengimpor kode runtime plugin, menjalankan package manager, atau memperbaiki
dependensi yang hilang.
</Note>
`plugins search` adalah pencarian katalog ClawHub jarak jauh. Ini tidak memeriksa state lokal, mengubah config, memasang paket, atau memuat kode runtime plugin. Hasil pencarian menyertakan nama paket ClawHub, family, channel, versi, ringkasan, dan petunjuk pemasangan seperti `openclaw plugins install clawhub:<package>`.
`plugins search` adalah lookup katalog ClawHub jarak jauh. Ini tidak memeriksa status
lokal, mengubah konfigurasi, menginstal paket, atau memuat kode runtime plugin. Hasil
pencarian menyertakan nama paket ClawHub, family, channel, versi, ringkasan, dan
petunjuk instalasi seperti `openclaw plugins install clawhub:<package>`.
Untuk pekerjaan plugin bawaan di dalam image Docker terpaket, bind-mount direktori sumber plugin di atas jalur sumber terpaket yang cocok, seperti `/app/extensions/synology-chat`. OpenClaw akan menemukan overlay sumber ter-mount tersebut sebelum `/app/dist/extensions/synology-chat`; direktori sumber yang sekadar disalin tetap inert sehingga pemasangan terpaket normal masih menggunakan dist terkompilasi.
Untuk pekerjaan plugin bawaan di dalam image Docker terpaket, bind-mount direktori
sumber plugin di atas path sumber terpaket yang cocok, seperti
`/app/extensions/synology-chat`. OpenClaw akan menemukan overlay sumber yang di-mount
tersebut sebelum `/app/dist/extensions/synology-chat`; direktori sumber yang hanya disalin
tetap inert sehingga instalasi terpaket normal tetap memakai dist yang sudah dikompilasi.
Untuk debugging hook runtime:
- `openclaw plugins inspect <id> --runtime --json` menampilkan hook terdaftar dan diagnostik dari pass inspeksi yang memuat modul. Inspeksi runtime tidak pernah memasang dependensi; gunakan `openclaw doctor --fix` untuk membersihkan state dependensi legacy atau memasang plugin unduhan terkonfigurasi yang hilang.
- `openclaw gateway status --deep --require-rpc` mengonfirmasi Gateway yang dapat dijangkau, petunjuk service/proses, jalur config, dan kesehatan RPC.
- `openclaw plugins inspect <id> --runtime --json` menampilkan hook terdaftar dan diagnostik dari pass inspeksi yang memuat modul. Inspeksi runtime tidak pernah menginstal dependensi; gunakan `openclaw doctor --fix` untuk membersihkan status dependensi lama atau memulihkan plugin unduhan yang hilang dan dirujuk oleh konfigurasi.
- `openclaw gateway status --deep --require-rpc` mengonfirmasi Gateway yang dapat dijangkau, petunjuk layanan/proses, path konfigurasi, dan kesehatan RPC.
- Hook percakapan non-bawaan (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) memerlukan `plugins.entries.<id>.hooks.allowConversationAccess=true`.
Gunakan `--link` untuk menghindari penyalinan direktori lokal (menambahkan ke `plugins.load.paths`):
@ -277,16 +284,16 @@ openclaw plugins install -l ./my-plugin
```
<Note>
`--force` tidak didukung dengan `--link` karena pemasangan tertaut menggunakan ulang jalur sumber alih-alih menyalin ke atas target pemasangan terkelola.
`--force` tidak didukung dengan `--link` karena instalasi tertaut menggunakan ulang path sumber alih-alih menyalin ke target instalasi terkelola.
Gunakan `--pin` pada pemasangan npm untuk menyimpan spec persis yang diselesaikan (`name@version`) di indeks plugin terkelola sambil mempertahankan perilaku default tidak dipin.
Gunakan `--pin` pada instalasi npm untuk menyimpan spec tepat yang diselesaikan (`name@version`) di indeks plugin terkelola sambil mempertahankan perilaku default tanpa pin.
</Note>
### Indeks Plugin
### Indeks plugin
Metadata pemasangan plugin adalah state yang dikelola mesin, bukan config pengguna. Pemasangan dan pembaruan menuliskannya ke `plugins/installs.json` di bawah direktori state OpenClaw aktif. Map `installRecords` tingkat atasnya adalah sumber tahan lama untuk metadata pemasangan, termasuk record untuk manifes plugin yang rusak atau hilang. Array `plugins` adalah cache registri dingin yang diturunkan dari manifes. File ini menyertakan peringatan jangan diedit dan digunakan oleh `openclaw plugins update`, uninstall, diagnostik, dan registri plugin dingin.
Metadata instalasi plugin adalah status yang dikelola mesin, bukan konfigurasi pengguna. Instalasi dan pembaruan menulisnya ke `plugins/installs.json` di bawah direktori status OpenClaw aktif. Map `installRecords` tingkat atasnya adalah sumber metadata instalasi yang tahan lama, termasuk record untuk manifes plugin yang rusak atau hilang. Array `plugins` adalah cache registry dingin turunan manifes. File ini menyertakan peringatan jangan diedit dan digunakan oleh `openclaw plugins update`, uninstall, diagnostik, dan registry plugin dingin.
Saat OpenClaw melihat record `plugins.installs` legacy terkirim dalam config, OpenClaw memindahkannya ke indeks plugin dan menghapus key config; jika salah satu penulisan gagal, record config dipertahankan agar metadata pemasangan tidak hilang.
Ketika OpenClaw melihat record `plugins.installs` lama yang dikirim dalam konfigurasi, ia memindahkannya ke indeks plugin dan menghapus key konfigurasi; jika salah satu penulisan gagal, record konfigurasi dipertahankan agar metadata instalasi tidak hilang.
### Uninstall
@ -296,7 +303,7 @@ openclaw plugins uninstall <id> --dry-run
openclaw plugins uninstall <id> --keep-files
```
`uninstall` menghapus record plugin dari `plugins.entries`, indeks plugin tersimpan, entri daftar allow/deny plugin, dan entri `plugins.load.paths` tertaut saat berlaku. Kecuali `--keep-files` ditetapkan, uninstall juga menghapus direktori pemasangan terkelola terlacak saat berada di dalam root ekstensi plugin OpenClaw. Untuk plugin memori aktif, slot memori direset ke `memory-core`.
`uninstall` menghapus record plugin dari `plugins.entries`, indeks plugin yang dipersist, entri daftar allow/deny plugin, dan entri `plugins.load.paths` tertaut jika berlaku. Kecuali `--keep-files` diatur, uninstall juga menghapus direktori instalasi terkelola yang dilacak ketika berada di dalam root ekstensi plugin OpenClaw. Untuk plugin active memory, slot memori direset ke `memory-core`.
<Note>
`--keep-config` didukung sebagai alias usang untuk `--keep-files`.
@ -312,29 +319,29 @@ openclaw plugins update @openclaw/voice-call
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install
```
Pembaruan berlaku untuk pemasangan plugin terlacak di indeks plugin terkelola dan pemasangan hook-pack terlacak di `hooks.internal.installs`.
Pembaruan diterapkan pada instalasi plugin yang dilacak di indeks plugin terkelola dan instalasi hook-pack yang dilacak di `hooks.internal.installs`.
<AccordionGroup>
<Accordion title="Resolving plugin id vs npm spec">
Saat Anda meneruskan id plugin, OpenClaw menggunakan ulang spec pemasangan yang tercatat untuk plugin tersebut. Itu berarti dist-tag yang sebelumnya tersimpan seperti `@beta` dan versi persis yang dipin terus digunakan pada proses `update <id>` berikutnya.
Ketika Anda meneruskan id plugin, OpenClaw menggunakan ulang spec instalasi yang direkam untuk plugin tersebut. Artinya dist-tag yang disimpan sebelumnya seperti `@beta` dan versi tepat yang dipin tetap digunakan pada eksekusi `update <id>` berikutnya.
Untuk pemasangan npm, Anda juga dapat meneruskan spec paket npm eksplisit dengan dist-tag atau versi persis. OpenClaw menyelesaikan nama paket tersebut kembali ke record plugin terlacak, memperbarui plugin terpasang tersebut, dan mencatat spec npm baru untuk pembaruan berbasis id di masa mendatang.
Untuk instalasi npm, Anda juga dapat meneruskan spec paket npm eksplisit dengan dist-tag atau versi tepat. OpenClaw menyelesaikan nama paket tersebut kembali ke record plugin yang dilacak, memperbarui plugin terinstal tersebut, dan merekam spec npm baru untuk pembaruan berbasis id di masa mendatang.
Meneruskan nama paket npm tanpa versi atau tag juga diselesaikan kembali ke record plugin terlacak. Gunakan ini saat plugin dipin ke versi persis dan Anda ingin memindahkannya kembali ke jalur rilis default registri.
Meneruskan nama paket npm tanpa versi atau tag juga diselesaikan kembali ke record plugin yang dilacak. Gunakan ini ketika plugin dipin ke versi tepat dan Anda ingin memindahkannya kembali ke jalur rilis default registry.
</Accordion>
<Accordion title="Beta channel updates">
`openclaw plugins update` menggunakan ulang spec plugin terlacak kecuali Anda meneruskan spec baru. `openclaw update` juga mengetahui channel pembaruan OpenClaw aktif: pada channel beta, record plugin npm dan ClawHub jalur default mencoba `@beta` terlebih dahulu, lalu fallback ke spec default/latest yang tercatat jika tidak ada rilis beta plugin. Versi persis dan tag eksplisit tetap dipin ke selector tersebut.
`openclaw plugins update` menggunakan ulang spec plugin yang dilacak kecuali Anda meneruskan spec baru. `openclaw update` juga mengetahui channel pembaruan OpenClaw aktif: pada channel beta, record plugin npm dan ClawHub jalur default mencoba `@beta` terlebih dahulu, lalu fallback ke spec default/latest yang direkam jika tidak ada rilis beta plugin. Versi tepat dan tag eksplisit tetap dipin ke selector tersebut.
</Accordion>
<Accordion title="Version checks and integrity drift">
Sebelum pembaruan npm live, OpenClaw memeriksa versi paket terpasang terhadap metadata registry npm. Jika versi terpasang dan identitas artefak tercatat sudah cocok dengan target yang diselesaikan, pembaruan dilewati tanpa mengunduh, memasang ulang, atau menulis ulang `openclaw.json`.
Sebelum pembaruan npm langsung, OpenClaw memeriksa versi paket yang terinstal terhadap metadata registry npm. Jika versi terinstal dan identitas artefak yang direkam sudah cocok dengan target yang diselesaikan, pembaruan dilewati tanpa mengunduh, menginstal ulang, atau menulis ulang `openclaw.json`.
Saat hash integritas tersimpan ada dan hash artefak yang diambil berubah, OpenClaw memperlakukannya sebagai drift artefak npm. Perintah interaktif `openclaw plugins update` mencetak hash yang diharapkan dan aktual serta meminta konfirmasi sebelum melanjutkan. Helper pembaruan non-interaktif gagal tertutup kecuali pemanggil menyediakan kebijakan kelanjutan eksplisit.
Ketika hash integritas tersimpan ada dan hash artefak yang diambil berubah, OpenClaw memperlakukan itu sebagai drift artefak npm. Perintah interaktif `openclaw plugins update` mencetak hash yang diharapkan dan aktual lalu meminta konfirmasi sebelum melanjutkan. Helper pembaruan non-interaktif gagal tertutup kecuali pemanggil menyediakan kebijakan kelanjutan eksplisit.
</Accordion>
<Accordion title="--dangerously-force-unsafe-install on update">
`--dangerously-force-unsafe-install` juga tersedia pada `plugins update` sebagai override darurat untuk false positive pemindaian kode berbahaya bawaan selama pembaruan plugin. Ini tetap tidak melewati blok kebijakan `before_install` plugin atau pemblokiran kegagalan pemindaian, dan hanya berlaku untuk pembaruan plugin, bukan pembaruan hook-pack.
`--dangerously-force-unsafe-install` juga tersedia pada `plugins update` sebagai override darurat untuk positif palsu pemindaian kode berbahaya bawaan selama pembaruan plugin. Ini tetap tidak melewati blok kebijakan `before_install` plugin atau pemblokiran kegagalan pemindaian, dan hanya berlaku untuk pembaruan plugin, bukan pembaruan hook-pack.
</Accordion>
</AccordionGroup>
@ -346,21 +353,21 @@ openclaw plugins inspect <id> --runtime
openclaw plugins inspect <id> --json
```
Inspect menampilkan identitas, status muat, sumber, kapabilitas manifes, flag kebijakan, diagnostik, metadata pemasangan, kapabilitas bundel, dan dukungan server MCP atau LSP apa pun yang terdeteksi tanpa mengimpor runtime plugin secara default. Tambahkan `--runtime` untuk memuat modul plugin dan menyertakan hook, tools, commands, services, metode gateway, dan rute HTTP terdaftar. Inspeksi runtime melaporkan dependensi plugin yang hilang secara langsung; pemasangan dan perbaikan tetap berada di `openclaw plugins install`, `openclaw plugins update`, dan `openclaw doctor --fix`.
Inspect menampilkan identitas, status pemuatan, sumber, kapabilitas manifes, flag kebijakan, diagnostik, metadata instalasi, kapabilitas bundle, dan dukungan server MCP atau LSP yang terdeteksi tanpa mengimpor runtime plugin secara default. Tambahkan `--runtime` untuk memuat modul plugin dan menyertakan hook, tool, command, service, metode gateway, dan route HTTP yang terdaftar. Inspeksi runtime melaporkan dependensi plugin yang hilang secara langsung; instalasi dan perbaikan tetap berada di `openclaw plugins install`, `openclaw plugins update`, dan `openclaw doctor --fix`.
Perintah CLI milik plugin dipasang sebagai grup perintah root `openclaw`. Setelah `inspect --runtime` menampilkan perintah di bawah `cliCommands`, jalankan sebagai `openclaw <command> ...`; misalnya plugin yang mendaftarkan `demo-git` dapat diverifikasi dengan `openclaw demo-git ping`.
Command CLI milik plugin diinstal sebagai grup command root `openclaw`. Setelah `inspect --runtime` menampilkan command di bawah `cliCommands`, jalankan sebagai `openclaw <command> ...`; misalnya plugin yang mendaftarkan `demo-git` dapat diverifikasi dengan `openclaw demo-git ping`.
Setiap plugin diklasifikasikan berdasarkan apa yang benar-benar didaftarkannya saat runtime:
- **plain-capability** — satu jenis kapabilitas (misalnya plugin khusus provider)
- **hybrid-capability** — beberapa jenis kapabilitas (misalnya teks + ucapan + gambar)
- **plain-capability** — satu jenis kapabilitas (mis. plugin khusus provider)
- **hybrid-capability** — beberapa jenis kapabilitas (mis. teks + ucapan + gambar)
- **hook-only** — hanya hook, tanpa kapabilitas atau surface
- **non-capability** — tools/commands/services tetapi tanpa kapabilitas
- **non-capability** — tool/command/service tetapi tanpa kapabilitas
Lihat [Bentuk Plugin](/id/plugins/architecture#plugin-shapes) untuk informasi lebih lanjut tentang model kapabilitas.
Lihat [Bentuk plugin](/id/plugins/architecture#plugin-shapes) untuk informasi lebih lanjut tentang model kapabilitas.
<Note>
Flag `--json` mengeluarkan laporan yang dapat dibaca mesin dan cocok untuk scripting serta audit. `inspect --all` merender tabel seluruh armada dengan kolom bentuk, jenis kapabilitas, pemberitahuan kompatibilitas, kapabilitas bundel, dan ringkasan hook. `info` adalah alias untuk `inspect`.
Flag `--json` menghasilkan laporan yang dapat dibaca mesin dan cocok untuk scripting serta audit. `inspect --all` merender tabel seluruh fleet dengan kolom bentuk, jenis kapabilitas, pemberitahuan kompatibilitas, kapabilitas bundle, dan ringkasan hook. `info` adalah alias untuk `inspect`.
</Note>
### Doctor
@ -369,13 +376,13 @@ Flag `--json` mengeluarkan laporan yang dapat dibaca mesin dan cocok untuk scrip
openclaw plugins doctor
```
`doctor` melaporkan error pemuatan plugin, diagnostik manifes/discovery, dan pemberitahuan kompatibilitas. Saat semuanya bersih, ia mencetak `No plugin issues detected.`
`doctor` melaporkan error pemuatan plugin, diagnostik manifes/discovery, dan pemberitahuan kompatibilitas. Ketika semuanya bersih, ia mencetak `No plugin issues detected.`
Jika plugin terkonfigurasi ada di disk tetapi diblokir oleh pemeriksaan keamanan jalur loader, validasi config mempertahankan entri plugin dan melaporkannya sebagai `present but blocked`. Perbaiki diagnostik plugin terblokir sebelumnya, seperti kepemilikan jalur atau izin world-writable, alih-alih menghapus config `plugins.entries.<id>` atau `plugins.allow`.
Jika plugin yang dikonfigurasi ada di disk tetapi diblokir oleh pemeriksaan keamanan path milik loader, validasi konfigurasi mempertahankan entri plugin dan melaporkannya sebagai `present but blocked`. Perbaiki diagnostik plugin terblokir sebelumnya, seperti kepemilikan path atau izin world-writable, alih-alih menghapus konfigurasi `plugins.entries.<id>` atau `plugins.allow`.
Untuk kegagalan bentuk modul seperti ekspor `register`/`activate` yang hilang, jalankan ulang dengan `OPENCLAW_PLUGIN_LOAD_DEBUG=1` untuk menyertakan ringkasan bentuk ekspor ringkas dalam output diagnostik.
Untuk kegagalan bentuk modul seperti ekspor `register`/`activate` yang hilang, jalankan ulang dengan `OPENCLAW_PLUGIN_LOAD_DEBUG=1` untuk menyertakan ringkasan bentuk ekspor yang ringkas dalam output diagnostik.
### Registri
### Registry
```bash
openclaw plugins registry
@ -383,14 +390,14 @@ openclaw plugins registry --refresh
openclaw plugins registry --json
```
Registri plugin lokal adalah model baca dingin tersimpan OpenClaw untuk identitas plugin terpasang, status aktif, metadata sumber, dan kepemilikan kontribusi. Startup normal, pencarian pemilik provider, klasifikasi penyiapan channel, dan inventaris plugin dapat membacanya tanpa mengimpor modul runtime plugin.
Registry plugin lokal adalah model baca dingin terpersist milik OpenClaw untuk identitas plugin terinstal, enablement, metadata sumber, dan kepemilikan kontribusi. Startup normal, lookup owner provider, klasifikasi setup channel, dan inventaris plugin dapat membacanya tanpa mengimpor modul runtime plugin.
Gunakan `plugins registry` untuk memeriksa apakah registri yang dipersisten ada, mutakhir, atau kedaluwarsa. Gunakan `--refresh` untuk membangunnya ulang dari indeks Plugin yang dipersisten, kebijakan konfigurasi, dan metadata manifest/paket. Ini adalah jalur perbaikan, bukan jalur aktivasi runtime.
Gunakan `plugins registry` untuk memeriksa apakah registry yang dipertahankan ada, terkini, atau usang. Gunakan `--refresh` untuk membangunnya ulang dari indeks Plugin yang dipertahankan, kebijakan konfigurasi, serta metadata manifest/paket. Ini adalah jalur perbaikan, bukan jalur aktivasi runtime.
`openclaw doctor --fix` juga memperbaiki penyimpangan npm terkelola yang berdekatan dengan registri: jika paket `@openclaw/*` yang yatim atau dipulihkan di bawah root npm Plugin terkelola membayangi Plugin bawaan, doctor menghapus paket kedaluwarsa tersebut dan membangun ulang registri sehingga startup memvalidasi terhadap manifest bawaan.
`openclaw doctor --fix` juga memperbaiki drift npm terkelola yang berdekatan dengan registry: jika paket `@openclaw/*` yang yatim atau dipulihkan di bawah root npm Plugin terkelola menutupi Plugin bawaan, doctor menghapus paket usang tersebut dan membangun ulang registry agar startup memvalidasi terhadap manifest bawaan.
<Warning>
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` adalah sakelar kompatibilitas darurat yang tidak digunakan lagi untuk kegagalan baca registri. Utamakan `plugins registry --refresh` atau `openclaw doctor --fix`; fallback env hanya untuk pemulihan startup darurat selama migrasi diluncurkan.
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` adalah sakelar kompatibilitas darurat yang sudah tidak digunakan lagi untuk kegagalan baca registry. Utamakan `plugins registry --refresh` atau `openclaw doctor --fix`; fallback env hanya untuk pemulihan startup darurat saat migrasi diluncurkan.
</Warning>
### Marketplace
@ -400,10 +407,10 @@ openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
```
Daftar marketplace menerima jalur marketplace lokal, jalur `marketplace.json`, singkatan GitHub seperti `owner/repo`, URL repo GitHub, atau URL git. `--json` mencetak label sumber yang diselesaikan beserta manifest marketplace dan entri Plugin yang diurai.
Daftar marketplace menerima jalur marketplace lokal, jalur `marketplace.json`, singkatan GitHub seperti `owner/repo`, URL repo GitHub, atau URL git. `--json` mencetak label sumber yang diselesaikan beserta manifest marketplace yang diurai dan entri Plugin.
## Terkait
- [Membangun Plugin](/id/plugins/building-plugins)
- [Referensi CLI](/id/cli)
- [Plugin komunitas](/id/plugins/community)
- [Plugin Komunitas](/id/plugins/community)

68
docs/id/cli/sessions.md
View File

@ -1,67 +1,54 @@
---
read_when:
- Anda ingin menampilkan daftar sesi yang tersimpan dan melihat aktivitas terbaru
summary: Referensi CLI untuk `openclaw sessions` (mencantumkan sesi tersimpan + penggunaan)
summary: Referensi CLI untuk `openclaw sessions` (daftar sesi tersimpan + penggunaan)
title: Sesi
x-i18n:
generated_at: "2026-05-04T07:02:43Z"
generated_at: "2026-05-05T01:44:13Z"
model: gpt-5.5
provider: openai
source_hash: 8dc90344f40c53513bd6db3696bc709279155f26e7c3b6ea27e81a07a2f9f15e
source_hash: 6eb484ab1fa7686cf42dd00e640c4ae8616c4ea1c29873ea72694d72b9c680e7
source_path: cli/sessions.md
workflow: 16
---
# `openclaw sessions`
Cantumkan sesi percakapan yang disimpan.
Cantumkan sesi percakapan yang tersimpan.
Daftar sesi bukan pemeriksaan keaktifan channel/provider. Daftar ini menampilkan baris
percakapan yang dipertahankan dari penyimpanan sesi. Discord, Slack, Telegram, atau
channel lain yang senyap dapat tersambung kembali dengan sukses tanpa membuat baris sesi
baru sampai sebuah pesan diproses. Gunakan `openclaw channels status --probe`,
`openclaw status --deep`, atau `openclaw health --verbose` saat Anda memerlukan
konektivitas channel langsung.
Daftar sesi bukan pemeriksaan keaktifan channel/provider. Daftar ini menampilkan baris percakapan yang dipersisten dari penyimpanan sesi. Discord, Slack, Telegram, atau channel lain yang sepi dapat tersambung ulang dengan sukses tanpa membuat baris sesi baru sampai pesan diproses. Gunakan `openclaw channels status --probe`, `openclaw status --deep`, atau `openclaw health --verbose` saat Anda membutuhkan konektivitas channel langsung.
Respons Gateway `sessions.list` dibatasi secara bawaan agar store besar yang berumur panjang
tidak dapat memonopoli loop peristiwa Gateway. Berikan `limit` positif eksplisit
dari klien RPC saat jendela hasil yang berbeda diperlukan; respons menyertakan
`totalCount`, `limitApplied`, dan `hasMore` saat pemanggil perlu menunjukkan
bahwa ada lebih banyak baris.
Respons `openclaw sessions` dan Gateway `sessions.list` dibatasi secara default agar penyimpanan besar yang berumur panjang tidak memonopoli proses CLI atau event loop Gateway. CLI mengembalikan 100 sesi terbaru secara default; berikan `--limit <n>` untuk jendela yang lebih kecil/besar atau `--limit all` saat Anda sengaja membutuhkan seluruh penyimpanan. Respons JSON menyertakan `totalCount`, `limitApplied`, dan `hasMore` saat pemanggil perlu menunjukkan bahwa ada lebih banyak baris.
```bash
openclaw sessions
openclaw sessions --agent work
openclaw sessions --all-agents
openclaw sessions --active 120
openclaw sessions --limit 25
openclaw sessions --verbose
openclaw sessions --json
```
Pemilihan cakupan:
- bawaan: store agen bawaan yang dikonfigurasi
- `--verbose`: pencatatan log verbose
- `--agent <id>`: satu store agen yang dikonfigurasi
- `--all-agents`: agregasikan semua store agen yang dikonfigurasi
- `--store <path>`: jalur store eksplisit (tidak dapat digabungkan dengan `--agent` atau `--all-agents`)
- default: penyimpanan agen default yang dikonfigurasi
- `--verbose`: pencatatan verbose
- `--agent <id>`: satu penyimpanan agen yang dikonfigurasi
- `--all-agents`: gabungkan semua penyimpanan agen yang dikonfigurasi
- `--store <path>`: jalur penyimpanan eksplisit (tidak dapat digabungkan dengan `--agent` atau `--all-agents`)
- `--limit <n|all>`: jumlah baris maksimum untuk dikeluarkan (default `100`; `all` memulihkan keluaran penuh)
Ekspor bundel trajectory untuk sesi yang disimpan:
Ekspor bundel trajektori untuk sesi tersimpan:
```bash
openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --workspace .
openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --output bug-123 --json
```
Ini adalah jalur perintah yang digunakan oleh perintah slash `/export-trajectory` setelah
pemilik menyetujui permintaan eksekusi. Direktori output selalu di-resolve
di dalam `.openclaw/trajectory-exports/` di bawah workspace yang dipilih.
Ini adalah jalur perintah yang digunakan oleh perintah slash `/export-trajectory` setelah pemilik menyetujui permintaan eksekusi. Direktori keluaran selalu diselesaikan di dalam `.openclaw/trajectory-exports/` di bawah workspace yang dipilih.
`openclaw sessions --all-agents` membaca store agen yang dikonfigurasi. Penemuan sesi
Gateway dan ACP lebih luas: keduanya juga menyertakan store yang hanya ada di disk yang ditemukan di bawah
root `agents/` bawaan atau root `session.store` bertemplat. Store yang ditemukan tersebut
harus di-resolve menjadi file `sessions.json` reguler di dalam root
agen; symlink dan jalur di luar root dilewati.
`openclaw sessions --all-agents` membaca penyimpanan agen yang dikonfigurasi. Penemuan sesi Gateway dan ACP lebih luas: keduanya juga menyertakan penyimpanan yang hanya ada di disk yang ditemukan di bawah root `agents/` default atau root `session.store` bertemplat. Penyimpanan yang ditemukan tersebut harus diselesaikan menjadi file `sessions.json` reguler di dalam root agen; symlink dan jalur di luar root dilewati.
Contoh JSON:
@ -76,6 +63,9 @@ Contoh JSON:
],
"allAgents": true,
"count": 2,
"totalCount": 2,
"limitApplied": 100,
"hasMore": false,
"activeMinutes": null,
"sessions": [
{ "agentId": "main", "key": "agent:main:main", "model": "gpt-5" },
@ -86,7 +76,7 @@ Contoh JSON:
## Pemeliharaan pembersihan
Jalankan pemeliharaan sekarang (alih-alih menunggu siklus tulis berikutnya):
Jalankan pemeliharaan sekarang (alih-alih menunggu siklus penulisan berikutnya):
```bash
openclaw sessions cleanup --dry-run
@ -99,21 +89,19 @@ openclaw sessions cleanup --json
`openclaw sessions cleanup` menggunakan pengaturan `session.maintenance` dari konfigurasi:
- Catatan cakupan: `openclaw sessions cleanup` memelihara store sesi, transkrip, dan sidecar trajectory. Perintah ini tidak memangkas log eksekusi cron (`cron/runs/<jobId>.jsonl`), yang dikelola oleh `cron.runLog.maxBytes` dan `cron.runLog.keepLines` dalam [konfigurasi Cron](/id/automation/cron-jobs#configuration) dan dijelaskan dalam [pemeliharaan Cron](/id/automation/cron-jobs#maintenance).
- Catatan cakupan: `openclaw sessions cleanup` memelihara penyimpanan sesi, transkrip, dan sidecar trajektori. Perintah ini tidak memangkas log run cron (`cron/runs/<jobId>.jsonl`), yang dikelola oleh `cron.runLog.maxBytes` dan `cron.runLog.keepLines` dalam [Konfigurasi Cron](/id/automation/cron-jobs#configuration) dan dijelaskan dalam [Pemeliharaan Cron](/id/automation/cron-jobs#maintenance).
- `--dry-run`: pratinjau berapa banyak entri yang akan dipangkas/dibatasi tanpa menulis.
- Dalam mode teks, dry-run mencetak tabel tindakan per sesi (`Action`, `Key`, `Age`, `Model`, `Flags`) sehingga Anda dapat melihat apa yang akan dipertahankan vs dihapus.
- `--enforce`: terapkan pemeliharaan meskipun `session.maintenance.mode` adalah `warn`.
- `--fix-missing`: hapus entri yang file transkripnya hilang, meskipun biasanya entri tersebut belum keluar karena usia/jumlah.
- `--active-key <key>`: lindungi kunci aktif tertentu dari pengusiran karena anggaran disk. Pointer percakapan eksternal yang tahan lama, seperti sesi grup dan sesi chat bercakupan thread, juga dipertahankan oleh pemeliharaan usia/jumlah/anggaran disk.
- `--agent <id>`: jalankan pembersihan untuk satu store agen yang dikonfigurasi.
- `--all-agents`: jalankan pembersihan untuk semua store agen yang dikonfigurasi.
- `--enforce`: terapkan pemeliharaan bahkan saat `session.maintenance.mode` bernilai `warn`.
- `--fix-missing`: hapus entri yang file transkripnya hilang, meskipun biasanya entri tersebut belum akan dikeluarkan berdasarkan usia/jumlah.
- `--active-key <key>`: lindungi kunci aktif tertentu dari penggusuran karena anggaran disk. Penunjuk percakapan eksternal yang tahan lama, seperti sesi grup dan sesi chat bercakupan thread, juga dipertahankan oleh pemeliharaan usia/jumlah/anggaran disk.
- `--agent <id>`: jalankan pembersihan untuk satu penyimpanan agen yang dikonfigurasi.
- `--all-agents`: jalankan pembersihan untuk semua penyimpanan agen yang dikonfigurasi.
- `--store <path>`: jalankan terhadap file `sessions.json` tertentu.
- `--json`: cetak ringkasan JSON. Dengan `--all-agents`, output menyertakan satu ringkasan per store.
- `--json`: cetak ringkasan JSON. Dengan `--all-agents`, keluaran menyertakan satu ringkasan per penyimpanan.
Saat Gateway dapat dijangkau, pembersihan non-dry-run untuk store agen yang dikonfigurasi
dikirim melalui Gateway sehingga berbagi penulis store sesi yang sama dengan lalu lintas
runtime. Gunakan `--store <path>` untuk perbaikan offline eksplisit pada file store.
Saat Gateway dapat dijangkau, pembersihan non-dry-run untuk penyimpanan agen yang dikonfigurasi dikirim melalui Gateway agar menggunakan penulis penyimpanan sesi yang sama dengan lalu lintas runtime. Gunakan `--store <path>` untuk perbaikan offline eksplisit atas file penyimpanan.
`openclaw sessions cleanup --all-agents --dry-run --json`:

125
docs/id/cli/update.md
View File

@ -1,15 +1,15 @@
---
read_when:
- Anda ingin memperbarui checkout kode sumber dengan aman
- Anda sedang menelusuri galat pada keluaran atau opsi `openclaw update`
- Anda sedang menelusuri kesalahan pada keluaran atau opsi `openclaw update`
- Anda perlu memahami perilaku singkatan `--update`
summary: Referensi CLI untuk `openclaw update` (pembaruan sumber yang relatif aman + mulai ulang otomatis Gateway)
title: Perbarui
x-i18n:
generated_at: "2026-05-03T21:29:37Z"
generated_at: "2026-05-05T01:45:03Z"
model: gpt-5.5
provider: openai
source_hash: 53ec06b8db5e2aba4000922f92a36834e8782986a77f6b5889bb19031a59f1b8
source_hash: b12b1837ae80a3688fb7805d78d5a354f07dccdaba175cfa429e18145e543a1f
source_path: cli/update.md
workflow: 16
---
@ -18,8 +18,8 @@ x-i18n:
Perbarui OpenClaw dengan aman dan beralih antara kanal stable/beta/dev.
Jika Anda memasang melalui **npm/pnpm/bun** (instalasi global, tanpa metadata git),
pembaruan dilakukan melalui alur manajer paket di [Memperbarui](/id/install/updating).
Jika Anda menginstal melalui **npm/pnpm/bun** (instalasi global, tanpa metadata git),
pembaruan dilakukan melalui alur pengelola paket di [Memperbarui](/id/install/updating).
## Penggunaan
@ -40,31 +40,31 @@ openclaw --update
## Opsi
- `--no-restart`: lewati memulai ulang layanan Gateway setelah pembaruan berhasil. Pembaruan manajer paket yang memulai ulang Gateway memverifikasi bahwa layanan yang dimulai ulang melaporkan versi terbaru yang diharapkan sebelum perintah berhasil.
- `--no-restart`: lewati pemulaian ulang layanan Gateway setelah pembaruan berhasil. Pembaruan pengelola paket yang memang memulai ulang Gateway memverifikasi bahwa layanan yang dimulai ulang melaporkan versi terbaru yang diharapkan sebelum perintah berhasil.
- `--channel <stable|beta|dev>`: atur kanal pembaruan (git + npm; disimpan dalam konfigurasi).
- `--tag <dist-tag|version|spec>`: timpa target paket hanya untuk pembaruan ini. Untuk instalasi paket, `main` dipetakan ke `github:openclaw/openclaw#main`.
- `--dry-run`: pratinjau tindakan pembaruan yang direncanakan (alur kanal/tag/target/mulai ulang) tanpa menulis konfigurasi, memasang, menyinkronkan plugin, atau memulai ulang.
- `--dry-run`: pratinjau tindakan pembaruan yang direncanakan (alur kanal/tag/target/mulai ulang) tanpa menulis konfigurasi, menginstal, menyinkronkan Plugin, atau memulai ulang.
- `--json`: cetak JSON `UpdateRunResult` yang dapat dibaca mesin, termasuk
`postUpdate.plugins.integrityDrifts` saat drift artefak plugin npm
terdeteksi selama sinkronisasi plugin pascapembaruan.
`postUpdate.plugins.integrityDrifts` saat drift artefak Plugin npm
terdeteksi selama sinkronisasi Plugin pascapembaruan.
- `--timeout <seconds>`: batas waktu per langkah (default 1800 dtk).
- `--yes`: lewati prompt konfirmasi (misalnya konfirmasi downgrade).
`openclaw update` tidak memiliki flag `--verbose`. Gunakan `--dry-run` untuk mempratinjau
tindakan kanal/tag/instal/mulai ulang yang direncanakan, `--json` untuk hasil
yang dapat dibaca mesin, dan `openclaw update status --json` saat Anda hanya memerlukan detail
kanal dan ketersediaan. Jika Anda men-debug log Gateway di sekitar pembaruan,
verbositas konsol dan level log file terpisah: Gateway `--verbose` memengaruhi
keluaran terminal/WebSocket, sementara log file memerlukan `logging.level: "debug"` atau
tindakan kanal/tag/instal/mulai ulang yang direncanakan, `--json` untuk hasil yang
dapat dibaca mesin, dan `openclaw update status --json` saat Anda hanya membutuhkan
detail kanal dan ketersediaan. Jika Anda men-debug log Gateway di sekitar pembaruan,
verbositas konsol dan level log file terpisah: `--verbose` Gateway memengaruhi
keluaran terminal/WebSocket, sedangkan log file memerlukan `logging.level: "debug"` atau
`"trace"` dalam konfigurasi. Lihat [logging Gateway](/id/gateway/logging).
<Warning>
Downgrade memerlukan konfirmasi karena versi lama dapat merusak konfigurasi.
Downgrade memerlukan konfirmasi karena versi yang lebih lama dapat merusak konfigurasi.
</Warning>
## `update status`
Tampilkan kanal pembaruan aktif + tag/branch/SHA git (untuk checkout sumber), serta ketersediaan pembaruan.
Tampilkan kanal pembaruan aktif + tag/cabang/SHA git (untuk checkout sumber), ditambah ketersediaan pembaruan.
```bash
openclaw update status
@ -80,7 +80,7 @@ Opsi:
## `update wizard`
Alur interaktif untuk memilih kanal pembaruan dan mengonfirmasi apakah akan memulai ulang Gateway
setelah pembaruan (default-nya memulai ulang). Jika Anda memilih `dev` tanpa checkout git, alur ini
setelah memperbarui (default-nya adalah memulai ulang). Jika Anda memilih `dev` tanpa checkout git, alur ini
menawarkan untuk membuatnya.
Opsi:
@ -93,62 +93,62 @@ Saat Anda beralih kanal secara eksplisit (`--channel ...`), OpenClaw juga menjag
metode instalasi tetap selaras:
- `dev` → memastikan checkout git (default: `~/openclaw`, timpa dengan `OPENCLAW_GIT_DIR`),
memperbaruinya, dan memasang CLI global dari checkout tersebut.
- `stable` → memasang dari npm menggunakan `latest`.
- `beta` → memprioritaskan dist-tag npm `beta`, tetapi fallback ke `latest` saat beta
tidak ada atau lebih lama daripada rilis stable saat ini.
memperbaruinya, dan menginstal CLI global dari checkout tersebut.
- `stable` → menginstal dari npm menggunakan `latest`.
- `beta` → mengutamakan dist-tag npm `beta`, tetapi mundur ke `latest` saat beta
tidak ada atau lebih lama dari rilis stable saat ini.
Pembaruan otomatis inti Gateway (saat diaktifkan melalui konfigurasi) meluncurkan jalur pembaruan CLI
di luar handler permintaan Gateway yang sedang aktif. Pembaruan manajer paket control-plane `update.run`
memaksa mulai ulang pembaruan yang tidak ditunda dan tanpa cooldown setelah penggantian paket,
di luar handler permintaan Gateway yang sedang berjalan. Pembaruan pengelola paket
`update.run` pada control plane memaksa pemulaian ulang pembaruan tanpa penundaan dan tanpa cooldown setelah penukaran paket,
karena proses Gateway lama mungkin masih memiliki chunk dalam memori yang menunjuk ke
file yang dihapus oleh paket baru.
Untuk instalasi manajer paket, `openclaw update` menyelesaikan versi paket target
sebelum memanggil manajer paket. Instalasi global npm menggunakan instalasi bertahap:
OpenClaw memasang paket baru ke prefix npm sementara, memverifikasi inventaris
`dist` yang dipaketkan di sana, lalu menukar pohon paket bersih itu ke prefix
global asli. Jika verifikasi gagal, doctor pascapembaruan, sinkronisasi plugin, dan
pekerjaan mulai ulang tidak dijalankan dari pohon yang dicurigai. Bahkan saat versi terpasang
sudah cocok dengan target, perintah ini menyegarkan instalasi paket global,
lalu menjalankan sinkronisasi plugin, penyegaran penyelesaian perintah inti, dan pekerjaan mulai ulang. Ini
menjaga sidecar terpaketkan dan catatan plugin milik kanal tetap selaras dengan
build OpenClaw yang terpasang sambil menyerahkan pembangunan ulang penyelesaian perintah plugin penuh ke
eksekusi `openclaw completion --write-state` eksplisit.
Untuk instalasi pengelola paket, `openclaw update` menyelesaikan versi paket target
sebelum menjalankan pengelola paket. Instalasi global npm menggunakan instalasi bertahap:
OpenClaw menginstal paket baru ke prefiks npm sementara, memverifikasi inventaris
`dist` yang dipaketkan di sana, lalu menukar pohon paket bersih itu ke
prefiks global sebenarnya. Jika verifikasi gagal, doctor pascapembaruan, sinkronisasi Plugin, dan
pekerjaan mulai ulang tidak dijalankan dari pohon yang dicurigai. Bahkan saat versi terinstal
sudah cocok dengan target, perintah menyegarkan instalasi paket global,
lalu menjalankan sinkronisasi Plugin, penyegaran penyelesaian perintah inti, dan pekerjaan mulai ulang. Ini
menjaga sidecar yang dipaketkan dan catatan Plugin milik kanal tetap selaras dengan
build OpenClaw yang terinstal sambil menyerahkan pembuatan ulang penyelesaian perintah Plugin penuh ke
pemanggilan eksplisit `openclaw completion --write-state`.
Saat layanan Gateway terkelola lokal terpasang dan mulai ulang diaktifkan,
pembaruan manajer paket menghentikan layanan yang berjalan sebelum mengganti pohon paket,
Saat layanan Gateway terkelola lokal terinstal dan mulai ulang diaktifkan,
pembaruan pengelola paket menghentikan layanan yang berjalan sebelum mengganti pohon paket,
lalu menyegarkan metadata layanan dari instalasi yang diperbarui, memulai ulang
layanan, dan memverifikasi Gateway yang dimulai ulang melaporkan versi yang diharapkan sebelum
melaporkan keberhasilan. Di macOS, pemeriksaan pascapembaruan juga memverifikasi LaunchAgent
melaporkan keberhasilan. Di macOS, pemeriksaan pascapembaruan juga memverifikasi bahwa LaunchAgent
dimuat/berjalan untuk profil aktif dan port loopback yang dikonfigurasi
sehat. Jika plist terpasang tetapi launchd tidak mengawasinya, OpenClaw
mem-bootstrap ulang LaunchAgent secara otomatis, lalu menjalankan ulang
sehat. Jika plist terinstal tetapi launchd tidak mengawasinya, OpenClaw
melakukan bootstrap ulang LaunchAgent secara otomatis, lalu menjalankan ulang
pemeriksaan kesiapan kesehatan/versi/kanal. Bootstrap baru memuat job RunAtLoad
secara langsung, sehingga pemulihan pembaruan tidak langsung `kickstart -k` Gateway
secara langsung, sehingga pemulihan pembaruan tidak segera menjalankan `kickstart -k` pada Gateway
yang baru dibuat. Jika Gateway tetap tidak menjadi sehat, perintah keluar
non-zero dan mencetak path log mulai ulang plus instruksi mulai ulang, instal ulang, dan
rollback paket yang eksplisit. Dengan `--no-restart`,
dengan non-zero dan mencetak jalur log mulai ulang serta instruksi mulai ulang, instal ulang, dan
rollback paket secara eksplisit. Dengan `--no-restart`,
penggantian paket tetap berjalan tetapi layanan terkelola tidak dihentikan atau
dimulai ulang, sehingga Gateway yang sedang berjalan mungkin tetap memakai kode lama sampai Anda memulai ulang
dimulai ulang, sehingga Gateway yang berjalan mungkin tetap menggunakan kode lama sampai Anda memulai ulang
secara manual.
## Alur checkout git
## Alur checkout Git
### Pemilihan kanal
- `stable`: checkout tag non-beta terbaru, lalu build dan doctor.
- `beta`: prioritaskan tag `-beta` terbaru, tetapi fallback ke tag stable terbaru saat beta tidak ada atau lebih lama.
- `beta`: utamakan tag `-beta` terbaru, tetapi mundur ke tag stable terbaru saat beta tidak ada atau lebih lama.
- `dev`: checkout `main`, lalu fetch dan rebase.
### Langkah pembaruan
<Steps>
<Step title="Verifikasi worktree bersih">
Mengharuskan tidak ada perubahan yang belum di-commit.
Memerlukan tidak ada perubahan yang belum di-commit.
</Step>
<Step title="Beralih kanal">
Beralih ke kanal yang dipilih (tag atau branch).
Beralih ke kanal yang dipilih (tag atau cabang).
</Step>
<Step title="Fetch upstream">
Hanya dev.
@ -159,44 +159,45 @@ secara manual.
<Step title="Rebase">
Melakukan rebase ke commit yang dipilih (hanya dev).
</Step>
<Step title="Pasang dependensi">
Menggunakan manajer paket repo. Untuk checkout pnpm, updater mem-bootstrap `pnpm` sesuai kebutuhan (melalui `corepack` terlebih dahulu, lalu fallback `npm install pnpm@10` sementara) alih-alih menjalankan `npm run build` di dalam workspace pnpm.
<Step title="Instal dependensi">
Menggunakan pengelola paket repo. Untuk checkout pnpm, updater melakukan bootstrap `pnpm` sesuai kebutuhan (melalui `corepack` terlebih dahulu, lalu fallback `npm install pnpm@10` sementara) alih-alih menjalankan `npm run build` di dalam workspace pnpm.
</Step>
<Step title="Build Control UI">
Mem-build gateway dan Control UI.
Membangun gateway dan Control UI.
</Step>
<Step title="Jalankan doctor">
`openclaw doctor` berjalan sebagai pemeriksaan pembaruan aman terakhir.
</Step>
<Step title="Sinkronkan plugin">
Menyinkronkan plugin ke kanal aktif. Dev menggunakan plugin bawaan; stable dan beta menggunakan npm. Memperbarui instalasi plugin yang dilacak.
<Step title="Sinkronkan Plugin">
Menyinkronkan Plugin ke kanal aktif. Dev menggunakan Plugin bawaan; stable dan beta menggunakan npm. Memperbarui instalasi Plugin yang dilacak.
</Step>
</Steps>
Pada kanal pembaruan beta, instalasi plugin npm dan ClawHub yang dilacak yang mengikuti
baris default/latest mencoba rilis plugin `@beta` terlebih dahulu. Jika plugin tidak memiliki
rilis beta, OpenClaw fallback ke spesifikasi default/latest yang tercatat. Versi eksak
dan tag eksplisit tidak ditulis ulang.
Pada kanal pembaruan beta, instalasi Plugin npm dan ClawHub yang dilacak dan mengikuti
jalur default/latest mencoba rilis Plugin `@beta` terlebih dahulu. Jika Plugin tidak memiliki
rilis beta, OpenClaw mundur ke spesifikasi default/latest yang direkam. Untuk Plugin npm,
OpenClaw juga mundur saat paket beta ada tetapi gagal validasi instalasi.
Versi persis dan tag eksplisit tidak ditulis ulang.
<Warning>
Jika pembaruan plugin npm yang dipin secara eksak diselesaikan ke artefak yang integritasnya berbeda dari catatan instalasi tersimpan, `openclaw update` membatalkan pembaruan artefak plugin tersebut alih-alih memasangnya. Instal ulang atau perbarui plugin secara eksplisit hanya setelah memverifikasi bahwa Anda memercayai artefak baru tersebut.
Jika pembaruan Plugin npm yang dipin secara persis diselesaikan ke artefak yang integritasnya berbeda dari catatan instalasi tersimpan, `openclaw update` membatalkan pembaruan artefak Plugin tersebut alih-alih menginstalnya. Instal ulang atau perbarui Plugin secara eksplisit hanya setelah memverifikasi bahwa Anda memercayai artefak baru tersebut.
</Warning>
<Note>
Kegagalan sinkronisasi plugin pascapembaruan menggagalkan hasil pembaruan dan menghentikan pekerjaan lanjutan mulai ulang. Perbaiki kesalahan instalasi atau pembaruan plugin, lalu jalankan ulang `openclaw update`.
Kegagalan sinkronisasi Plugin pascapembaruan menggagalkan hasil pembaruan dan menghentikan pekerjaan lanjutan mulai ulang. Perbaiki kesalahan instalasi atau pembaruan Plugin, lalu jalankan ulang `openclaw update`.
Saat Gateway yang diperbarui dimulai, pemuatan plugin bersifat hanya verifikasi: startup tidak menjalankan manajer paket atau mengubah pohon dependensi. Mulai ulang `update.run` manajer paket melewati penundaan idle normal dan cooldown mulai ulang setelah pohon paket ditukar, sehingga proses lama tidak dapat terus lazy-load chunk yang telah dihapus.
Saat Gateway yang diperbarui dimulai, pemuatan Plugin bersifat hanya verifikasi: startup tidak menjalankan pengelola paket atau mengubah pohon dependensi. Pemulaian ulang `update.run` pengelola paket melewati penundaan idle normal dan cooldown mulai ulang setelah pohon paket ditukar, sehingga proses lama tidak dapat terus memuat lambat chunk yang sudah dihapus.
Jika bootstrap pnpm tetap gagal, updater berhenti lebih awal dengan kesalahan khusus manajer paket alih-alih mencoba `npm run build` di dalam checkout.
Jika bootstrap pnpm tetap gagal, updater berhenti lebih awal dengan kesalahan khusus pengelola paket alih-alih mencoba `npm run build` di dalam checkout.
</Note>
## Singkatan `--update`
## Pintasan `--update`
`openclaw --update` ditulis ulang menjadi `openclaw update` (berguna untuk shell dan skrip launcher).
## Terkait
- `openclaw doctor` (menawarkan untuk menjalankan update terlebih dahulu pada checkout git)
- `openclaw doctor` (menawarkan menjalankan pembaruan terlebih dahulu pada checkout git)
- [Kanal pengembangan](/id/install/development-channels)
- [Memperbarui](/id/install/updating)
- [Referensi CLI](/id/cli)

141
docs/id/concepts/models.md
View File

@ -1,26 +1,26 @@
---
read_when:
- Menambahkan atau memodifikasi CLI models (models list/set/scan/aliases/fallbacks)
- Mengubah perilaku penggunaan model cadangan atau pengalaman pengguna saat memilih
- Menambahkan atau memodifikasi CLI model (models list/set/scan/aliases/fallbacks)
- Mengubah perilaku fallback model atau UX pemilihan
- Memperbarui probe pemindaian model (alat/gambar)
sidebarTitle: Models CLI
summary: 'CLI Model: daftar, atur, alias, alternatif cadangan, pindai, status'
summary: 'CLI Model: daftar, tetapkan, alias, fallback, pindai, status'
title: CLI Model
x-i18n:
generated_at: "2026-05-02T09:18:44Z"
generated_at: "2026-05-05T01:45:11Z"
model: gpt-5.5
provider: openai
source_hash: d362c8cc41801b5e480560c8d34be53e1ada53a23c49af99adb7874e265ddb1f
source_hash: 8a1dcdb046b914d35513974d4b69fec03a415118d11860dd1c5107efc754ed4f
source_path: concepts/models.md
workflow: 16
---
<CardGroup cols={2}>
<Card title="Failover model" href="/id/concepts/model-failover">
Rotasi profil autentikasi, cooldown, dan bagaimana hal itu berinteraksi dengan fallback.
Rotasi profil autentikasi, masa cooldown, dan bagaimana hal itu berinteraksi dengan fallback.
</Card>
<Card title="Penyedia model" href="/id/concepts/model-providers">
Ikhtisar singkat penyedia dan contoh.
Ikhtisar dan contoh singkat penyedia.
</Card>
<Card title="Runtime agen" href="/id/concepts/agent-runtimes">
PI, Codex, dan runtime loop agen lainnya.
@ -30,7 +30,7 @@ x-i18n:
</Card>
</CardGroup>
Ref model memilih penyedia dan model. Ref tersebut biasanya tidak memilih runtime agen tingkat rendah. Misalnya, `openai/gpt-5.5` dapat berjalan melalui jalur penyedia OpenAI normal atau melalui runtime server aplikasi Codex, bergantung pada `agents.defaults.agentRuntime.id`. Dalam mode runtime Codex, ref `openai/gpt-*` tidak menyiratkan penagihan kunci API; autentikasi dapat berasal dari akun Codex atau profil autentikasi `openai-codex`. Lihat [Runtime agen](/id/concepts/agent-runtimes).
Ref model memilih penyedia dan model. Ref biasanya tidak memilih runtime agen tingkat rendah. Misalnya, `openai/gpt-5.5` dapat berjalan melalui jalur penyedia OpenAI normal atau melalui runtime server aplikasi Codex, bergantung pada `agents.defaults.agentRuntime.id`. Dalam mode runtime Codex, ref `openai/gpt-*` tidak menyiratkan penagihan kunci API; autentikasi dapat berasal dari akun Codex atau profil autentikasi `openai-codex`. Lihat [Runtime agen](/id/concepts/agent-runtimes).
## Cara kerja pemilihan model
@ -41,7 +41,7 @@ OpenClaw memilih model dalam urutan ini:
`agents.defaults.model.primary` (atau `agents.defaults.model`).
</Step>
<Step title="Fallback">
`agents.defaults.model.fallbacks` (berurutan).
`agents.defaults.model.fallbacks` (sesuai urutan).
</Step>
<Step title="Failover autentikasi penyedia">
Failover autentikasi terjadi di dalam penyedia sebelum berpindah ke model berikutnya.
@ -52,31 +52,31 @@ OpenClaw memilih model dalam urutan ini:
<Accordion title="Permukaan model terkait">
- `agents.defaults.models` adalah allowlist/katalog model yang dapat digunakan OpenClaw (ditambah alias).
- `agents.defaults.imageModel` digunakan **hanya ketika** model utama tidak dapat menerima gambar.
- `agents.defaults.pdfModel` digunakan oleh alat `pdf`. Jika dihilangkan, alat akan fallback ke `agents.defaults.imageModel`, lalu model sesi/default yang sudah diselesaikan.
- `agents.defaults.imageGenerationModel` digunakan oleh kapabilitas pembuatan gambar bersama. Jika dihilangkan, `image_generate` masih dapat menyimpulkan default penyedia yang didukung autentikasi. Ini mencoba penyedia default saat ini terlebih dahulu, lalu penyedia pembuatan gambar terdaftar yang tersisa dalam urutan ID penyedia. Jika Anda menetapkan penyedia/model tertentu, konfigurasikan juga autentikasi/kunci API penyedia tersebut.
- `agents.defaults.musicGenerationModel` digunakan oleh kapabilitas pembuatan musik bersama. Jika dihilangkan, `music_generate` masih dapat menyimpulkan default penyedia yang didukung autentikasi. Ini mencoba penyedia default saat ini terlebih dahulu, lalu penyedia pembuatan musik terdaftar yang tersisa dalam urutan ID penyedia. Jika Anda menetapkan penyedia/model tertentu, konfigurasikan juga autentikasi/kunci API penyedia tersebut.
- `agents.defaults.videoGenerationModel` digunakan oleh kapabilitas pembuatan video bersama. Jika dihilangkan, `video_generate` masih dapat menyimpulkan default penyedia yang didukung autentikasi. Ini mencoba penyedia default saat ini terlebih dahulu, lalu penyedia pembuatan video terdaftar yang tersisa dalam urutan ID penyedia. Jika Anda menetapkan penyedia/model tertentu, konfigurasikan juga autentikasi/kunci API penyedia tersebut.
- Default per agen dapat mengganti `agents.defaults.model` melalui `agents.list[].model` plus binding (lihat [Perutean multi-agen](/id/concepts/multi-agent)).
- `agents.defaults.pdfModel` digunakan oleh alat `pdf`. Jika dihilangkan, alat tersebut kembali ke `agents.defaults.imageModel`, lalu model sesi/default yang diselesaikan.
- `agents.defaults.imageGenerationModel` digunakan oleh kapabilitas pembuatan gambar bersama. Jika dihilangkan, `image_generate` masih dapat menyimpulkan default penyedia yang didukung autentikasi. Ini mencoba penyedia default saat ini terlebih dahulu, lalu penyedia pembuatan gambar terdaftar lainnya dalam urutan ID penyedia. Jika Anda menetapkan penyedia/model tertentu, konfigurasikan juga autentikasi/kunci API penyedia tersebut.
- `agents.defaults.musicGenerationModel` digunakan oleh kapabilitas pembuatan musik bersama. Jika dihilangkan, `music_generate` masih dapat menyimpulkan default penyedia yang didukung autentikasi. Ini mencoba penyedia default saat ini terlebih dahulu, lalu penyedia pembuatan musik terdaftar lainnya dalam urutan ID penyedia. Jika Anda menetapkan penyedia/model tertentu, konfigurasikan juga autentikasi/kunci API penyedia tersebut.
- `agents.defaults.videoGenerationModel` digunakan oleh kapabilitas pembuatan video bersama. Jika dihilangkan, `video_generate` masih dapat menyimpulkan default penyedia yang didukung autentikasi. Ini mencoba penyedia default saat ini terlebih dahulu, lalu penyedia pembuatan video terdaftar lainnya dalam urutan ID penyedia. Jika Anda menetapkan penyedia/model tertentu, konfigurasikan juga autentikasi/kunci API penyedia tersebut.
- Default per agen dapat menimpa `agents.defaults.model` melalui `agents.list[].model` ditambah binding (lihat [Perutean multi-agen](/id/concepts/multi-agent)).
</Accordion>
</AccordionGroup>
## Sumber pemilihan dan perilaku fallback
`provider/model` yang sama dapat berarti hal berbeda bergantung pada asalnya:
`provider/model` yang sama dapat berarti hal berbeda tergantung asalnya:
- Default yang dikonfigurasi (`agents.defaults.model.primary` dan utama khusus agen) adalah titik awal normal dan menggunakan `agents.defaults.model.fallbacks`.
- Pemilihan fallback otomatis adalah status pemulihan sementara. Pemilihan ini disimpan dengan `modelOverrideSource: "auto"` sehingga giliran berikutnya dapat terus menggunakan rantai fallback tanpa memeriksa model utama yang diketahui bermasalah terlebih dahulu.
- Pemilihan sesi pengguna bersifat persis. `/model`, pemilih model, `session_status(model=...)`, dan `sessions.patch` menyimpan `modelOverrideSource: "user"`; jika penyedia/model yang dipilih tersebut tidak dapat dijangkau, OpenClaw gagal secara terlihat alih-alih jatuh ke model lain yang dikonfigurasi.
- Cron `--model` / payload `model` adalah model utama per pekerjaan. Ini tetap menggunakan fallback yang dikonfigurasi kecuali pekerjaan menyediakan payload `fallbacks` eksplisit (gunakan `fallbacks: []` untuk run cron ketat).
- Pemilih model default CLI dan allowlist menghormati `models.mode: "replace"` dengan mencantumkan `models.providers.*.models` eksplisit alih-alih memuat katalog bawaan lengkap.
- Pemilih model Control UI meminta tampilan model yang dikonfigurasi dari Gateway: `agents.defaults.models` jika ada, jika tidak `models.providers.*.models` eksplisit plus penyedia dengan autentikasi yang dapat digunakan. Katalog bawaan lengkap dicadangkan untuk tampilan jelajah eksplisit seperti `models.list` dengan `view: "all"` atau `openclaw models list --all`.
- Default yang dikonfigurasi (`agents.defaults.model.primary` dan model utama khusus agen) adalah titik awal normal dan menggunakan `agents.defaults.model.fallbacks`.
- Pilihan fallback otomatis adalah status pemulihan sementara. Pilihan tersebut disimpan dengan `modelOverrideSource: "auto"` sehingga giliran berikutnya dapat terus menggunakan rantai fallback tanpa menguji model utama yang diketahui bermasalah terlebih dahulu.
- Pilihan sesi pengguna bersifat eksak. `/model`, pemilih model, `session_status(model=...)`, dan `sessions.patch` menyimpan `modelOverrideSource: "user"`; jika penyedia/model yang dipilih tidak dapat dijangkau, OpenClaw gagal secara terlihat alih-alih jatuh ke model lain yang dikonfigurasi.
- Cron `--model` / payload `model` adalah model utama per pekerjaan. Ini tetap menggunakan fallback yang dikonfigurasi kecuali pekerjaan menyediakan payload `fallbacks` eksplisit (gunakan `fallbacks: []` untuk proses cron yang ketat).
- CLI default-model dan pemilih allowlist menghormati `models.mode: "replace"` dengan mencantumkan `models.providers.*.models` eksplisit alih-alih memuat katalog bawaan lengkap.
- Pemilih model Control UI meminta Gateway untuk tampilan model yang dikonfigurasi: `agents.defaults.models` jika ada, jika tidak `models.providers.*.models` eksplisit ditambah penyedia dengan autentikasi yang dapat digunakan. Katalog bawaan lengkap dicadangkan untuk tampilan jelajah eksplisit seperti `models.list` dengan `view: "all"` atau `openclaw models list --all`.
## Kebijakan model cepat
## Kebijakan model singkat
- Atur model utama Anda ke model generasi terbaru terkuat yang tersedia untuk Anda.
- Gunakan fallback untuk tugas yang sensitif biaya/latensi dan obrolan dengan risiko lebih rendah.
- Untuk agen yang mengaktifkan alat atau input tidak tepercaya, hindari tingkat model yang lebih lama/lebih lemah.
- Gunakan fallback untuk tugas yang sensitif biaya/latensi dan obrolan berisiko lebih rendah.
- Untuk agen yang mengaktifkan alat atau input yang tidak tepercaya, hindari tingkat model yang lebih lama/lebih lemah.
## Onboarding (direkomendasikan)
@ -99,7 +99,7 @@ Ini dapat menyiapkan model + autentikasi untuk penyedia umum, termasuk **langgan
- `models.providers` (penyedia kustom yang ditulis ke `models.json`)
<Note>
Ref model dinormalisasi ke huruf kecil. Alias penyedia seperti `z.ai/*` dinormalisasi menjadi `zai/*`.
Ref model dinormalisasi menjadi huruf kecil. Alias penyedia seperti `z.ai/*` dinormalisasi menjadi `zai/*`.
Contoh konfigurasi penyedia (termasuk OpenCode) tersedia di [OpenCode](/id/providers/opencode).
</Note>
@ -114,23 +114,24 @@ openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json
<AccordionGroup>
<Accordion title="Aturan perlindungan penimpaan">
`openclaw config set` melindungi peta model/penyedia dari penimpaan yang tidak disengaja. Penetapan objek biasa ke `agents.defaults.models`, `models.providers`, atau `models.providers.<id>.models` ditolak jika akan menghapus entri yang sudah ada. Gunakan `--merge` untuk perubahan aditif; gunakan `--replace` hanya ketika nilai yang diberikan harus menjadi nilai target lengkap.
`openclaw config set` melindungi peta model/penyedia dari penimpaan tidak disengaja. Penetapan objek biasa ke `agents.defaults.models`, `models.providers`, atau `models.providers.<id>.models` ditolak jika akan menghapus entri yang sudah ada. Gunakan `--merge` untuk perubahan aditif; gunakan `--replace` hanya ketika nilai yang diberikan harus menjadi nilai target lengkap.
Penyiapan penyedia interaktif dan `openclaw configure --section model` juga menggabungkan pemilihan berskala penyedia ke allowlist yang sudah ada, sehingga menambahkan Codex, Ollama, atau penyedia lain tidak menghapus entri model yang tidak terkait. Configure mempertahankan `agents.defaults.model.primary` yang sudah ada ketika autentikasi penyedia diterapkan ulang. Perintah pengaturan default eksplisit seperti `openclaw models auth login --provider <id> --set-default` dan `openclaw models set <model>` tetap mengganti `agents.defaults.model.primary`.
Penyiapan penyedia interaktif dan `openclaw configure --section model` juga menggabungkan pilihan yang dicakup penyedia ke allowlist yang sudah ada, sehingga menambahkan Codex, Ollama, atau penyedia lain tidak menghapus entri model yang tidak terkait. Configure mempertahankan `agents.defaults.model.primary` yang sudah ada ketika autentikasi penyedia diterapkan ulang. Perintah penetapan default eksplisit seperti `openclaw models auth login --provider <id> --set-default` dan `openclaw models set <model>` tetap mengganti `agents.defaults.model.primary`.
</Accordion>
</AccordionGroup>
## "Model tidak diizinkan" (dan mengapa balasan berhenti)
Jika `agents.defaults.models` diatur, itu menjadi **allowlist** untuk `/model` dan untuk override sesi. Ketika pengguna memilih model yang tidak ada dalam allowlist tersebut, OpenClaw mengembalikan:
Jika `agents.defaults.models` ditetapkan, itu menjadi **allowlist** untuk `/model` dan untuk penimpaan sesi. Ketika pengguna memilih model yang tidak ada dalam allowlist tersebut, OpenClaw mengembalikan:
```
Model "provider/model" is not allowed. Use /model to list available models.
Model "provider/model" is not allowed. Use /models to list providers, or /models <provider> to list models.
Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge
```
<Warning>
Ini terjadi **sebelum** balasan normal dibuat, sehingga pesan dapat terasa seperti "tidak merespons." Perbaikannya adalah salah satu dari:
Ini terjadi **sebelum** balasan normal dibuat, sehingga pesan dapat terasa seperti "tidak merespons." Perbaikannya adalah salah satu dari berikut:
- Tambahkan model ke `agents.defaults.models`, atau
- Kosongkan allowlist (hapus `agents.defaults.models`), atau
@ -138,9 +139,11 @@ Ini terjadi **sebelum** balasan normal dibuat, sehingga pesan dapat terasa seper
</Warning>
Untuk model lokal/GGUF, simpan ref lengkap berprefiks penyedia di allowlist,
Ketika perintah yang ditolak menyertakan penimpaan runtime seperti `/model openai/gpt-5.5 --runtime codex`, perbaiki allowlist terlebih dahulu, lalu coba lagi perintah `/model ... --runtime ...` yang sama. Untuk eksekusi Codex native, model yang dipilih tetap `openai/gpt-5.5`; runtime `codex` memilih harness dan menggunakan autentikasi Codex secara terpisah.
Untuk model lokal/GGUF, simpan ref lengkap berprefiks penyedia dalam allowlist,
misalnya `ollama/gemma4:26b`, `lmstudio/Gemma4-26b-a4-it-gguf`, atau
provider/model persis yang ditampilkan oleh `openclaw models list --provider <provider>`.
penyedia/model persis yang ditampilkan oleh `openclaw models list --provider <provider>`.
Nama file lokal polos atau nama tampilan tidak cukup ketika allowlist
aktif.
@ -158,7 +161,7 @@ Contoh konfigurasi allowlist:
}
```
## Beralih model di chat (`/model`)
## Beralih model di obrolan (`/model`)
Anda dapat beralih model untuk sesi saat ini tanpa memulai ulang:
@ -173,28 +176,28 @@ Anda dapat beralih model untuk sesi saat ini tanpa memulai ulang:
<AccordionGroup>
<Accordion title="Perilaku pemilih">
- `/model` (dan `/model list`) adalah pemilih ringkas bernomor (keluarga model + penyedia yang tersedia).
- Di Discord, `/model` dan `/models` membuka pemilih interaktif dengan dropdown penyedia dan model plus langkah Submit.
- Di Telegram, pemilihan pemilih `/models` berskala sesi; pemilihan tersebut tidak mengubah default persisten agen di `openclaw.json`.
- `/models add` sudah tidak digunakan dan sekarang mengembalikan pesan penghentian penggunaan alih-alih mendaftarkan model dari chat.
- Di Discord, `/model` dan `/models` membuka pemilih interaktif dengan dropdown penyedia dan model ditambah langkah Kirim.
- Di Telegram, pilihan pemilih `/models` dicakup ke sesi; pilihan tersebut tidak mengubah default persisten agen di `openclaw.json`.
- `/models add` sudah tidak digunakan lagi dan sekarang mengembalikan pesan penghentian penggunaan alih-alih mendaftarkan model dari obrolan.
- `/model <#>` memilih dari pemilih tersebut.
</Accordion>
<Accordion title="Persistensi dan peralihan langsung">
- `/model` langsung mempertahankan pemilihan sesi baru.
- Jika agen idle, run berikutnya langsung menggunakan model baru.
- Jika run sudah aktif, OpenClaw menandai peralihan langsung sebagai tertunda dan hanya memulai ulang ke model baru pada titik retry yang bersih.
- Jika aktivitas alat atau output balasan sudah dimulai, peralihan tertunda dapat tetap mengantre hingga kesempatan retry berikutnya atau giliran pengguna berikutnya.
- `/model` mempertahankan pilihan sesi baru segera.
- Jika agen sedang idle, proses berikutnya langsung menggunakan model baru.
- Jika proses sudah aktif, OpenClaw menandai peralihan langsung sebagai tertunda dan hanya memulai ulang ke model baru pada titik percobaan ulang yang bersih.
- Jika aktivitas alat atau output balasan sudah dimulai, peralihan tertunda dapat tetap mengantre hingga peluang percobaan ulang berikutnya atau giliran pengguna berikutnya.
- Ref `/model` yang dipilih pengguna bersifat ketat untuk sesi tersebut: jika penyedia/model yang dipilih tidak dapat dijangkau, balasan gagal secara terlihat alih-alih diam-diam menjawab dari `agents.defaults.model.fallbacks`. Ini berbeda dari default yang dikonfigurasi dan model utama pekerjaan cron, yang masih dapat menggunakan rantai fallback.
- `/model status` adalah tampilan terperinci (kandidat autentikasi dan, jika dikonfigurasi, endpoint penyedia `baseUrl` + mode `api`).
</Accordion>
<Accordion title="Parsing ref">
- Ref model di-parse dengan memisahkan pada `/` **pertama**. Gunakan `provider/model` saat mengetik `/model <ref>`.
<Accordion title="Penguraian ref">
- Ref model diurai dengan memisahkan pada `/` **pertama**. Gunakan `provider/model` saat mengetik `/model <ref>`.
- Jika ID model itu sendiri berisi `/` (gaya OpenRouter), Anda harus menyertakan prefiks penyedia (contoh: `/model openrouter/moonshotai/kimi-k2`).
- Jika Anda menghilangkan penyedia, OpenClaw menyelesaikan input dalam urutan ini:
1. kecocokan alias
2. kecocokan penyedia-terkonfigurasi unik untuk ID model tanpa prefiks yang persis itu
3. fallback usang ke penyedia default yang dikonfigurasi — jika penyedia tersebut tidak lagi mengekspos model default yang dikonfigurasi, OpenClaw sebagai gantinya fallback ke penyedia/model terkonfigurasi pertama untuk menghindari menampilkan default penyedia terhapus yang sudah basi.
3. fallback lama ke penyedia default yang dikonfigurasi — jika penyedia tersebut tidak lagi mengekspos model default yang dikonfigurasi, OpenClaw sebagai gantinya kembali ke penyedia/model terkonfigurasi pertama untuk menghindari menampilkan default penyedia lama yang sudah dihapus.
</Accordion>
</AccordionGroup>
@ -227,10 +230,10 @@ openclaw models image-fallbacks clear
### `models list`
Menampilkan model yang dikonfigurasi/tersedia autentikasi secara default. Flag yang berguna:
Menampilkan model yang dikonfigurasi/tersedia-auth secara default. Flag yang berguna:
<ParamField path="--all" type="boolean">
Katalog lengkap. Menyertakan baris katalog statis milik penyedia bawaan sebelum autentikasi dikonfigurasi, sehingga tampilan khusus penemuan dapat menampilkan model yang tidak tersedia sampai Anda menambahkan kredensial penyedia yang sesuai.
Katalog lengkap. Menyertakan baris katalog statis bawaan milik penyedia sebelum auth dikonfigurasi, sehingga tampilan khusus penemuan dapat menampilkan model yang tidak tersedia sampai Anda menambahkan kredensial penyedia yang sesuai.
</ParamField>
<ParamField path="--local" type="boolean">
Hanya penyedia lokal.
@ -242,26 +245,26 @@ Menampilkan model yang dikonfigurasi/tersedia autentikasi secara default. Flag y
Satu model per baris.
</ParamField>
<ParamField path="--json" type="boolean">
Keluaran yang dapat dibaca mesin.
Output yang dapat dibaca mesin.
</ParamField>
### `models status`
Menampilkan model utama yang diselesaikan, fallback, model gambar, dan ringkasan autentikasi penyedia yang dikonfigurasi. Perintah ini juga menampilkan status kedaluwarsa OAuth untuk profil yang ditemukan di penyimpanan autentikasi (memperingatkan dalam 24 jam secara bawaan). `--plain` hanya mencetak model utama yang diselesaikan.
Menampilkan model primer yang diselesaikan, fallback, model gambar, dan ikhtisar auth dari penyedia yang dikonfigurasi. Ini juga menampilkan status kedaluwarsa OAuth untuk profil yang ditemukan di penyimpanan auth (memperingatkan dalam 24 jam secara default). `--plain` hanya mencetak model primer yang diselesaikan.
<AccordionGroup>
<Accordion title="Perilaku autentikasi dan pemeriksaan">
- Status OAuth selalu ditampilkan (dan disertakan dalam keluaran `--json`). Jika penyedia yang dikonfigurasi tidak memiliki kredensial, `models status` mencetak bagian **Autentikasi hilang**.
- JSON menyertakan `auth.oauth` (jendela peringatan + profil) dan `auth.providers` (autentikasi efektif per penyedia, termasuk kredensial berbasis env). `auth.oauth` hanya untuk kesehatan profil penyimpanan autentikasi; penyedia khusus env tidak muncul di sana.
- Gunakan `--check` untuk otomatisasi (keluar dengan `1` saat hilang/kedaluwarsa, `2` saat akan kedaluwarsa).
- Gunakan `--probe` untuk pemeriksaan autentikasi langsung; baris pemeriksaan dapat berasal dari profil autentikasi, kredensial env, atau `models.json`.
- Jika `auth.order.<provider>` eksplisit menghilangkan profil yang tersimpan, pemeriksaan melaporkan `excluded_by_auth_order` alih-alih mencobanya. Jika autentikasi ada tetapi tidak ada model yang dapat diperiksa untuk penyedia tersebut, pemeriksaan melaporkan `status: no_model`.
<Accordion title="Perilaku auth dan probe">
- Status OAuth selalu ditampilkan (dan disertakan dalam output `--json`). Jika penyedia yang dikonfigurasi tidak memiliki kredensial, `models status` mencetak bagian **Auth hilang**.
- JSON menyertakan `auth.oauth` (jendela peringatan + profil) dan `auth.providers` (auth efektif per penyedia, termasuk kredensial berbasis env). `auth.oauth` hanya kesehatan profil penyimpanan-auth; penyedia khusus env tidak muncul di sana.
- Gunakan `--check` untuk otomatisasi (exit `1` saat hilang/kedaluwarsa, `2` saat akan kedaluwarsa).
- Gunakan `--probe` untuk pemeriksaan auth langsung; baris probe dapat berasal dari profil auth, kredensial env, atau `models.json`.
- Jika `auth.order.<provider>` eksplisit menghilangkan profil tersimpan, probe melaporkan `excluded_by_auth_order` alih-alih mencobanya. Jika auth ada tetapi tidak ada model yang dapat diprobe yang bisa diselesaikan untuk penyedia tersebut, probe melaporkan `status: no_model`.
</Accordion>
</AccordionGroup>
<Note>
Pilihan autentikasi bergantung pada penyedia/akun. Untuk host gateway yang selalu aktif, kunci API biasanya paling dapat diprediksi; penggunaan ulang Claude CLI dan profil OAuth/token Anthropic yang ada juga didukung.
Pilihan auth bergantung pada penyedia/akun. Untuk host gateway yang selalu aktif, kunci API biasanya paling dapat diprediksi; penggunaan ulang Claude CLI serta profil OAuth/token Anthropic yang sudah ada juga didukung.
</Note>
Contoh (Claude CLI):
@ -273,10 +276,10 @@ openclaw models status
## Pemindaian (model gratis OpenRouter)
`openclaw models scan` memeriksa **katalog model gratis** OpenRouter dan dapat secara opsional memeriksa dukungan alat dan gambar pada model.
`openclaw models scan` memeriksa **katalog model gratis** OpenRouter dan dapat secara opsional memprobe model untuk dukungan alat dan gambar.
<ParamField path="--no-probe" type="boolean">
Lewati pemeriksaan langsung (hanya metadata).
Lewati probe langsung (hanya metadata).
</ParamField>
<ParamField path="--min-params <b>" type="number">
Ukuran parameter minimum (miliar).
@ -298,10 +301,10 @@ openclaw models status
</ParamField>
<Note>
Katalog `/models` OpenRouter bersifat publik, sehingga pemindaian khusus metadata dapat mencantumkan kandidat gratis tanpa kunci. Pemeriksaan dan inferensi tetap memerlukan kunci API OpenRouter (dari profil autentikasi atau `OPENROUTER_API_KEY`). Jika tidak ada kunci yang tersedia, `openclaw models scan` kembali ke keluaran khusus metadata dan membiarkan konfigurasi tidak berubah. Gunakan `--no-probe` untuk meminta mode khusus metadata secara eksplisit.
Katalog `/models` OpenRouter bersifat publik, sehingga pemindaian hanya metadata dapat mencantumkan kandidat gratis tanpa kunci. Probe dan inferensi tetap memerlukan kunci API OpenRouter (dari profil auth atau `OPENROUTER_API_KEY`). Jika tidak ada kunci yang tersedia, `openclaw models scan` kembali ke output hanya metadata dan membiarkan konfigurasi tidak berubah. Gunakan `--no-probe` untuk meminta mode hanya metadata secara eksplisit.
</Note>
Hasil pemindaian diberi peringkat berdasarkan:
Hasil pemindaian diperingkat berdasarkan:
1. Dukungan gambar
2. Latensi alat
@ -311,32 +314,32 @@ Hasil pemindaian diberi peringkat berdasarkan:
Input:
- Daftar `/models` OpenRouter (filter `:free`)
- Pemeriksaan langsung memerlukan kunci API OpenRouter dari profil autentikasi atau `OPENROUTER_API_KEY` (lihat [Variabel lingkungan](/id/help/environment))
- Probe langsung memerlukan kunci API OpenRouter dari profil auth atau `OPENROUTER_API_KEY` (lihat [Variabel lingkungan](/id/help/environment))
- Filter opsional: `--max-age-days`, `--min-params`, `--provider`, `--max-candidates`
- Kontrol permintaan/pemeriksaan: `--timeout`, `--concurrency`
- Kontrol permintaan/probe: `--timeout`, `--concurrency`
Saat pemeriksaan langsung berjalan di TTY, Anda dapat memilih fallback secara interaktif. Dalam mode non-interaktif, berikan `--yes` untuk menerima bawaan. Hasil khusus metadata bersifat informatif; `--set-default` dan `--set-image` memerlukan pemeriksaan langsung agar OpenClaw tidak mengonfigurasi model OpenRouter tanpa kunci yang tidak dapat digunakan.
Saat probe langsung berjalan di TUI, Anda dapat memilih fallback secara interaktif. Dalam mode non-interaktif, berikan `--yes` untuk menerima default. Hasil hanya metadata bersifat informatif; `--set-default` dan `--set-image` memerlukan probe langsung agar OpenClaw tidak mengonfigurasi model OpenRouter tanpa kunci yang tidak dapat digunakan.
## Registri model (`models.json`)
## Registry model (`models.json`)
Penyedia khusus di `models.providers` ditulis ke dalam `models.json` di bawah direktori agen (bawaan `~/.openclaw/agents/<agentId>/agent/models.json`). File ini digabungkan secara bawaan kecuali `models.mode` diatur ke `replace`.
Penyedia kustom di `models.providers` ditulis ke `models.json` di bawah direktori agen (default `~/.openclaw/agents/<agentId>/agent/models.json`). File ini digabungkan secara default kecuali `models.mode` diatur ke `replace`.
<AccordionGroup>
<Accordion title="Prioritas mode penggabungan">
Prioritas mode penggabungan untuk ID penyedia yang cocok:
- `baseUrl` tidak kosong yang sudah ada di `models.json` agen menang.
- `apiKey` tidak kosong di `models.json` agen hanya menang ketika penyedia tersebut tidak dikelola SecretRef dalam konteks konfigurasi/profil autentikasi saat ini.
- Nilai `apiKey` penyedia yang dikelola SecretRef disegarkan dari penanda sumber (`ENV_VAR_NAME` untuk referensi env, `secretref-managed` untuk referensi file/exec) alih-alih mempertahankan rahasia yang telah diselesaikan.
- `apiKey` tidak kosong di `models.json` agen hanya menang saat penyedia tersebut tidak dikelola SecretRef dalam konteks konfigurasi/profil-auth saat ini.
- Nilai `apiKey` penyedia yang dikelola SecretRef disegarkan dari penanda sumber (`ENV_VAR_NAME` untuk referensi env, `secretref-managed` untuk referensi file/exec), bukan mempertahankan rahasia yang sudah diselesaikan.
- Nilai header penyedia yang dikelola SecretRef disegarkan dari penanda sumber (`secretref-env:ENV_VAR_NAME` untuk referensi env, `secretref-managed` untuk referensi file/exec).
- `apiKey`/`baseUrl` agen yang kosong atau hilang fallback ke konfigurasi `models.providers`.
- Kolom penyedia lainnya disegarkan dari konfigurasi dan data katalog yang dinormalisasi.
- `apiKey`/`baseUrl` agen yang kosong atau hilang kembali ke konfigurasi `models.providers`.
- Field penyedia lainnya disegarkan dari konfigurasi dan data katalog yang dinormalisasi.
</Accordion>
</AccordionGroup>
<Note>
Persistensi penanda bersumber otoritatif: OpenClaw menulis penanda dari snapshot konfigurasi sumber aktif (pra-resolusi), bukan dari nilai rahasia runtime yang telah diselesaikan. Ini berlaku setiap kali OpenClaw membuat ulang `models.json`, termasuk jalur yang didorong perintah seperti `openclaw agent`.
Persistensi penanda bersifat otoritatif-sumber: OpenClaw menulis penanda dari snapshot konfigurasi sumber aktif (pra-resolusi), bukan dari nilai rahasia runtime yang sudah diselesaikan. Ini berlaku setiap kali OpenClaw meregenerasi `models.json`, termasuk jalur berbasis perintah seperti `openclaw agent`.
</Note>
## Terkait
@ -345,6 +348,6 @@ Persistensi penanda bersumber otoritatif: OpenClaw menulis penanda dari snapshot
- [Referensi konfigurasi](/id/gateway/config-agents#agent-defaults) — kunci konfigurasi model
- [Pembuatan gambar](/id/tools/image-generation) — konfigurasi model gambar
- [Failover model](/id/concepts/model-failover) — rantai fallback
- [Penyedia model](/id/concepts/model-providers) — perutean dan autentikasi penyedia
- [Penyedia model](/id/concepts/model-providers) — perutean penyedia dan auth
- [Pembuatan musik](/id/tools/music-generation) — konfigurasi model musik
- [Pembuatan video](/id/tools/video-generation) — konfigurasi model video

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

@ -1,60 +1,66 @@
---
read_when:
- Memahami bagaimana susunan QA saling terintegrasi
- Memahami bagaimana stack QA saling terkait
- Memperluas qa-lab, qa-channel, atau adapter transport
- Menambahkan skenario QA yang didukung repo
- Membangun otomatisasi QA dengan realisme lebih tinggi untuk dasbor Gateway
summary: 'Ikhtisar stack QA: qa-lab, qa-channel, skenario berbasis repo, lane transport live, adaptor transport, dan pelaporan.'
title: Ikhtisar QA
- Menambahkan skenario QA berbasis repo
- Membangun otomatisasi QA dengan tingkat realisme lebih tinggi di seputar dasbor Gateway
summary: 'Ikhtisar tumpukan QA: qa-lab, qa-channel, skenario berbasis repo, jalur transport langsung, adapter transport, dan pelaporan.'
title: Gambaran umum QA
x-i18n:
generated_at: "2026-05-04T07:04:32Z"
generated_at: "2026-05-05T01:45:14Z"
model: gpt-5.5
provider: openai
source_hash: 067f5aa0831724659ae36d548ef2e7bd28b40aad9cef45f325a01a2748003b29
source_hash: 83adbe934d73265a1b47ee463c98fdd3eddfb1cd063d3a46a83dfc7568df0a96
source_path: concepts/qa-e2e-automation.md
workflow: 16
---
Stack QA privat dimaksudkan untuk menguji OpenClaw dengan cara yang lebih realistis dan berbentuk channel daripada yang bisa dilakukan oleh satu pengujian unit.
Stack QA privat dimaksudkan untuk menguji OpenClaw dengan cara yang lebih realistis dan
berbentuk kanal dibandingkan yang dapat dilakukan satu pengujian unit.
Bagian saat ini:
- `extensions/qa-channel`: channel pesan sintetis dengan permukaan DM, channel, thread, reaksi, edit, dan hapus.
- `extensions/qa-lab`: UI debugger dan bus QA untuk mengamati transkrip, menyuntikkan pesan masuk, dan mengekspor laporan Markdown.
- `extensions/qa-matrix`, Plugin runner mendatang: adaptor transport langsung yang menggerakkan channel nyata di dalam Gateway QA anak.
- `qa/`: aset seed berbasis repo untuk tugas kickoff dan skenario QA baseline.
- [Mantis](/id/concepts/mantis): verifikasi langsung sebelum dan sesudah untuk bug yang membutuhkan transport nyata, tangkapan layar browser, status VM, dan bukti PR.
- `extensions/qa-channel`: kanal pesan sintetis dengan permukaan DM, kanal, thread,
reaksi, edit, dan hapus.
- `extensions/qa-lab`: UI debugger dan bus QA untuk mengamati transkrip,
menyuntikkan pesan masuk, dan mengekspor laporan Markdown.
- `extensions/qa-matrix`, plugin runner mendatang: adapter transport langsung yang
menggerakkan kanal nyata di dalam Gateway QA anak.
- `qa/`: aset seed berbasis repo untuk tugas kickoff dan skenario QA
baseline.
- [Mantis](/id/concepts/mantis): verifikasi langsung sebelum dan sesudah untuk bug yang
memerlukan transport nyata, tangkapan layar browser, status VM, dan bukti PR.
## Permukaan perintah
Setiap alur QA berjalan di bawah `pnpm openclaw qa <subcommand>`. Banyak yang memiliki alias skrip `pnpm qa:*`; kedua bentuk didukung.
| Perintah | Tujuan |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `qa run` | Pemeriksaan mandiri QA bawaan; menulis laporan Markdown. |
| `qa suite` | Jalankan skenario berbasis repo terhadap lane Gateway QA. Alias: `pnpm openclaw qa suite --runner multipass` untuk VM Linux sekali pakai. |
| `qa coverage` | Cetak inventaris cakupan skenario markdown (`--json` untuk output mesin). |
| `qa parity-report` | Bandingkan dua berkas `qa-suite-summary.json` dan tulis laporan paritas agentik. |
| `qa character-eval` | Jalankan skenario QA karakter di beberapa model langsung dengan laporan yang dinilai. Lihat [Pelaporan](#reporting). |
| `qa manual` | Jalankan prompt sekali pakai terhadap lane penyedia/model yang dipilih. |
| `qa ui` | Mulai UI debugger QA dan bus QA lokal (alias: `pnpm qa:lab:ui`). |
| `qa docker-build-image` | Bangun image Docker QA prapaket. |
| `qa docker-scaffold` | Tulis scaffold docker-compose untuk dasbor QA + lane Gateway. |
| `qa up` | Bangun situs QA, mulai stack yang didukung Docker, cetak URL (alias: `pnpm qa:lab:up`; varian `:fast` menambahkan `--use-prebuilt-image --bind-ui-dist --skip-ui-build`). |
| `qa aimock` | Mulai hanya server penyedia AIMock. |
| `qa mock-openai` | Mulai hanya server penyedia `mock-openai` yang sadar skenario. |
| `qa credentials doctor` / `add` / `list` / `remove` | Kelola pool kredensial Convex bersama. |
| `qa matrix` | Lane transport langsung terhadap homeserver Tuwunel sekali pakai. Lihat [QA Matrix](/id/concepts/qa-matrix). |
| `qa telegram` | Lane transport langsung terhadap grup Telegram privat nyata. |
| `qa discord` | Lane transport langsung terhadap channel guild Discord privat nyata. |
| `qa slack` | Lane transport langsung terhadap channel Slack privat nyata. |
| `qa mantis` | Runner verifikasi sebelum dan sesudah untuk bug transport langsung, dengan bukti reaksi status Discord, smoke desktop/browser Crabbox, dan smoke Slack-di-VNC. Lihat [Mantis](/id/concepts/mantis). |
| Perintah | Tujuan |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `qa run` | Pemeriksaan mandiri QA bawaan; menulis laporan Markdown. |
| `qa suite` | Menjalankan skenario berbasis repo terhadap jalur Gateway QA. Alias: `pnpm openclaw qa suite --runner multipass` untuk VM Linux sekali pakai. |
| `qa coverage` | Mencetak inventaris cakupan skenario markdown (`--json` untuk keluaran mesin). |
| `qa parity-report` | Membandingkan dua file `qa-suite-summary.json` dan menulis laporan paritas agentik. |
| `qa character-eval` | Menjalankan skenario QA karakter di beberapa model langsung dengan laporan yang dinilai. Lihat [Pelaporan](#reporting). |
| `qa manual` | Menjalankan prompt sekali jalan terhadap jalur provider/model yang dipilih. |
| `qa ui` | Memulai UI debugger QA dan bus QA lokal (alias: `pnpm qa:lab:ui`). |
| `qa docker-build-image` | Membangun image Docker QA yang sudah dipanggang sebelumnya. |
| `qa docker-scaffold` | Menulis scaffold docker-compose untuk dasbor QA + jalur Gateway. |
| `qa up` | Membangun situs QA, memulai stack berbasis Docker, mencetak URL (alias: `pnpm qa:lab:up`; varian `:fast` menambahkan `--use-prebuilt-image --bind-ui-dist --skip-ui-build`). |
| `qa aimock` | Memulai hanya server provider AIMock. |
| `qa mock-openai` | Memulai hanya server provider `mock-openai` yang sadar skenario. |
| `qa credentials doctor` / `add` / `list` / `remove` | Mengelola pool kredensial Convex bersama. |
| `qa matrix` | Jalur transport langsung terhadap homeserver Tuwunel sekali pakai. Lihat [QA Matrix](/id/concepts/qa-matrix). |
| `qa telegram` | Jalur transport langsung terhadap grup Telegram privat nyata. |
| `qa discord` | Jalur transport langsung terhadap kanal guild Discord privat nyata. |
| `qa slack` | Jalur transport langsung terhadap kanal Slack privat nyata. |
| `qa mantis` | Runner verifikasi sebelum dan sesudah untuk bug transport langsung, dengan bukti reaksi status Discord, smoke desktop/browser Crabbox, dan smoke Slack-di-VNC. Lihat [Mantis](/id/concepts/mantis). |
## Alur operator
Alur operator QA saat ini adalah situs QA dua panel:
- Kiri: dasbor Gateway (Control UI) dengan agent.
- Kiri: dasbor Gateway (UI Kontrol) dengan agen.
- Kanan: QA Lab, menampilkan transkrip bergaya Slack dan rencana skenario.
Jalankan dengan:
@ -63,9 +69,13 @@ Jalankan dengan:
pnpm qa:lab:up
```
Itu membangun situs QA, memulai lane Gateway yang didukung Docker, dan mengekspos halaman QA Lab tempat operator atau loop otomasi dapat memberi agent misi QA, mengamati perilaku channel nyata, serta mencatat apa yang berhasil, gagal, atau tetap terblokir.
Itu membangun situs QA, memulai jalur Gateway berbasis Docker, dan mengekspos
halaman QA Lab tempat operator atau loop otomasi dapat memberi agen sebuah misi
QA, mengamati perilaku kanal nyata, dan mencatat apa yang berhasil, gagal, atau
tetap terblokir.
Untuk iterasi UI QA Lab yang lebih cepat tanpa membangun ulang image Docker setiap kali, mulai stack dengan bundle QA Lab yang di-bind-mount:
Untuk iterasi UI QA Lab lokal yang lebih cepat tanpa membangun ulang image Docker setiap kali,
mulai stack dengan bundel QA Lab yang di-mount melalui bind:
```bash
pnpm openclaw qa docker-build-image
@ -74,7 +84,9 @@ pnpm qa:lab:up:fast
pnpm qa:lab:watch
```
`qa:lab:up:fast` mempertahankan layanan Docker pada image prabangun dan melakukan bind-mount `extensions/qa-lab/web/dist` ke dalam container `qa-lab`. `qa:lab:watch` membangun ulang bundle tersebut saat berubah, dan browser memuat ulang otomatis ketika hash aset QA Lab berubah.
`qa:lab:up:fast` mempertahankan layanan Docker pada image yang sudah dibangun sebelumnya dan melakukan bind-mount
`extensions/qa-lab/web/dist` ke dalam container `qa-lab`. `qa:lab:watch`
membangun ulang bundel tersebut saat ada perubahan, dan browser otomatis memuat ulang ketika hash aset QA Lab berubah.
Untuk smoke trace OpenTelemetry lokal, jalankan:
@ -82,19 +94,29 @@ Untuk smoke trace OpenTelemetry lokal, jalankan:
pnpm qa:otel:smoke
```
Skrip tersebut memulai receiver trace OTLP/HTTP lokal, menjalankan skenario QA `otel-trace-smoke` dengan Plugin `diagnostics-otel` diaktifkan, lalu mendekode span protobuf yang diekspor dan menegaskan bentuk yang kritis untuk rilis: `openclaw.run`, `openclaw.harness.run`, `openclaw.model.call`, `openclaw.context.assembled`, dan `openclaw.message.delivery` harus ada; panggilan model tidak boleh mengekspor `StreamAbandoned` pada turn yang berhasil; ID diagnostik mentah dan atribut `openclaw.content.*` harus tetap berada di luar trace. Ini menulis `otel-smoke-summary.json` di sebelah artefak suite QA.
Skrip itu memulai receiver trace OTLP/HTTP lokal, menjalankan
skenario QA `otel-trace-smoke` dengan plugin `diagnostics-otel` diaktifkan, lalu
mendekode span protobuf yang diekspor dan menegaskan bentuk penting-rilis:
`openclaw.run`, `openclaw.harness.run`, `openclaw.model.call`,
`openclaw.context.assembled`, dan `openclaw.message.delivery` harus ada;
pemanggilan model tidak boleh mengekspor `StreamAbandoned` pada giliran yang berhasil; ID diagnostik mentah dan
atribut `openclaw.content.*` harus tetap berada di luar trace. Skrip ini menulis
`otel-smoke-summary.json` di sebelah artefak suite QA.
QA observabilitas tetap hanya untuk checkout sumber. Tarball npm sengaja menghilangkan QA Lab, sehingga lane rilis Docker paket tidak menjalankan perintah `qa`. Gunakan `pnpm qa:otel:smoke` dari checkout sumber yang sudah dibangun saat mengubah instrumentasi diagnostik.
QA observabilitas tetap hanya untuk checkout sumber. Tarball npm sengaja menghilangkan
QA Lab, sehingga jalur rilis Docker paket tidak menjalankan perintah `qa`. Gunakan
`pnpm qa:otel:smoke` dari checkout sumber yang sudah dibangun saat mengubah instrumentasi
diagnostik.
Untuk lane smoke Matrix dengan transport nyata, jalankan:
Untuk jalur smoke Matrix yang benar-benar memakai transport nyata, jalankan:
```bash
pnpm openclaw qa matrix --profile fast --fail-fast
```
Referensi CLI lengkap, katalog profil/skenario, variabel env, dan tata letak artefak untuk lane ini ada di [QA Matrix](/id/concepts/qa-matrix). Sekilas: ini menyediakan homeserver Tuwunel sekali pakai di Docker, mendaftarkan pengguna driver/SUT/observer sementara, menjalankan Plugin Matrix nyata di dalam Gateway QA anak yang dicakup untuk transport tersebut (tanpa `qa-channel`), lalu menulis laporan Markdown, ringkasan JSON, artefak observed-events, dan log output gabungan di bawah `.artifacts/qa-e2e/matrix-<timestamp>/`.
Referensi CLI lengkap, katalog profil/skenario, env vars, dan tata letak artefak untuk jalur ini ada di [QA Matrix](/id/concepts/qa-matrix). Sekilas: jalur ini menyediakan homeserver Tuwunel sekali pakai di Docker, mendaftarkan pengguna driver/SUT/observer sementara, menjalankan plugin Matrix nyata di dalam Gateway QA anak yang dibatasi ke transport tersebut (tanpa `qa-channel`), lalu menulis laporan Markdown, ringkasan JSON, artefak observed-events, dan log keluaran gabungan di bawah `.artifacts/qa-e2e/matrix-<timestamp>/`.
Untuk lane smoke Telegram, Discord, dan Slack dengan transport nyata:
Untuk jalur smoke Telegram, Discord, dan Slack yang benar-benar memakai transport nyata:
```bash
pnpm openclaw qa telegram
@ -102,9 +124,9 @@ pnpm openclaw qa discord
pnpm openclaw qa slack
```
Mereka menargetkan channel nyata yang sudah ada dengan dua bot (driver + SUT). Variabel env yang diperlukan, daftar skenario, artefak output, dan pool kredensial Convex didokumentasikan dalam [Referensi QA Telegram, Discord, dan Slack](#telegram-discord-and-slack-qa-reference) di bawah.
Jalur tersebut menargetkan kanal nyata yang sudah ada dengan dua bot (driver + SUT). Env vars yang diperlukan, daftar skenario, artefak keluaran, dan pool kredensial Convex didokumentasikan dalam [Referensi QA Telegram, Discord, dan Slack](#telegram-discord-and-slack-qa-reference) di bawah.
Untuk run VM desktop Slack penuh dengan penyelamatan VNC, jalankan:
Untuk menjalankan VM desktop Slack penuh dengan penyelamatan VNC, jalankan:
```bash
pnpm openclaw qa mantis slack-desktop-smoke \
@ -113,48 +135,56 @@ pnpm openclaw qa mantis slack-desktop-smoke \
--keep-lease
```
Perintah itu menyewa mesin desktop/browser Crabbox, menjalankan lane langsung Slack di dalam VM, membuka Slack Web di browser VNC, menangkap desktop, dan menyalin `slack-qa/` plus `slack-desktop-smoke.png` kembali ke direktori artefak Mantis. Gunakan ulang `--lease-id <cbx_...>` setelah masuk ke Slack Web secara manual melalui VNC. Dengan `--gateway-setup`, Mantis meninggalkan Gateway Slack OpenClaw persisten yang berjalan di dalam VM pada port `38973`; tanpa itu, perintah menjalankan lane QA Slack bot-ke-bot normal dan keluar setelah penangkapan artefak.
Perintah itu menyewa mesin desktop/browser Crabbox, menjalankan jalur langsung Slack
di dalam VM, membuka Slack Web di browser VNC, menangkap desktop, dan
menyalin `slack-qa/` serta `slack-desktop-smoke.png` kembali ke direktori artefak
Mantis. Gunakan ulang `--lease-id <cbx_...>` setelah masuk ke Slack Web secara manual
melalui VNC. Dengan `--gateway-setup`, Mantis meninggalkan Gateway Slack OpenClaw
persisten yang berjalan di dalam VM pada port `38973`; tanpa itu, perintah menjalankan
jalur QA Slack bot-ke-bot normal dan keluar setelah pengambilan artefak.
Sebelum menggunakan kredensial langsung yang dipool, jalankan:
Sebelum menggunakan kredensial langsung dari pool, jalankan:
```bash
pnpm openclaw qa credentials doctor
```
Doctor memeriksa env broker Convex, memvalidasi pengaturan endpoint, dan memverifikasi keterjangkauan admin/list saat rahasia maintainer tersedia. Ini hanya melaporkan status ditetapkan/hilang untuk rahasia.
Doctor memeriksa env broker Convex, memvalidasi pengaturan endpoint, dan memverifikasi keterjangkauan admin/list ketika rahasia maintainer ada. Ini hanya melaporkan status tersetel/hilang untuk rahasia.
## Cakupan transport langsung
Lane transport langsung berbagi satu kontrak alih-alih masing-masing menciptakan bentuk daftar skenario sendiri. `qa-channel` adalah suite perilaku produk sintetis yang luas dan bukan bagian dari matriks cakupan transport langsung.
Jalur transport langsung berbagi satu kontrak alih-alih masing-masing membuat bentuk daftar skenarionya sendiri. `qa-channel` adalah suite perilaku produk sintetis yang luas dan bukan bagian dari matriks cakupan transport langsung.
| Lane | Canary | Gating mention | Bot-ke-bot | Blokir allowlist | Balasan tingkat atas | Lanjutkan setelah restart | Tindak lanjut thread | Isolasi thread | Pengamatan reaksi | Perintah bantuan | Registrasi perintah native |
| -------- | ------ | -------------- | ---------- | ---------------- | -------------------- | ------------------------- | --------------------- | -------------- | ----------------- | ---------------- | -------------------------- |
| Matrix | x | x | x | x | x | x | x | x | x | | |
| Telegram | x | x | x | | | | | | | x | |
| Discord | x | x | x | | | | | | | | x |
| Slack | x | x | x | | | | | | | | |
| Jalur | Canary | Gating mention | Bot-ke-bot | Blokir allowlist | Balasan level atas | Lanjut setelah restart | Tindak lanjut thread | Isolasi thread | Pengamatan reaksi | Perintah bantuan | Registrasi perintah native |
| -------- | ------ | -------------- | ---------- | ---------------- | ------------------ | ---------------------- | -------------------- | -------------- | ----------------- | ---------------- | -------------------------- |
| Matrix | x | x | x | x | x | x | x | x | x | | |
| Telegram | x | x | x | | | | | | | x | |
| Discord | x | x | x | | | | | | | | x |
| Slack | x | x | x | | | | | | | | |
Ini mempertahankan `qa-channel` sebagai suite perilaku produk yang luas, sementara Matrix, Telegram, dan transport langsung mendatang berbagi satu checklist kontrak transport yang eksplisit.
Ini mempertahankan `qa-channel` sebagai suite perilaku produk yang luas sementara Matrix,
Telegram, dan transport langsung mendatang berbagi satu checklist kontrak transport yang
eksplisit.
Untuk lane VM Linux sekali pakai tanpa membawa Docker ke jalur QA, jalankan:
Untuk jalur VM Linux sekali pakai tanpa membawa Docker ke jalur QA, jalankan:
```bash
pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
```
Ini mem-boot guest Multipass baru, menginstal dependensi, membangun OpenClaw
Ini mem-boot guest Multipass baru, memasang dependensi, membangun OpenClaw
di dalam guest, menjalankan `qa suite`, lalu menyalin laporan QA normal dan
ringkasan kembali ke `.artifacts/qa-e2e/...` pada host.
Ini menggunakan kembali perilaku pemilihan skenario yang sama seperti `qa suite` pada host.
ringkasan kembali ke `.artifacts/qa-e2e/...` di host.
Ini menggunakan ulang perilaku pemilihan skenario yang sama seperti `qa suite` di host.
Eksekusi suite host dan Multipass menjalankan beberapa skenario terpilih secara paralel
dengan worker Gateway yang terisolasi secara default. `qa-channel` secara default menggunakan konkurensi
dengan worker gateway terisolasi secara bawaan. `qa-channel` secara bawaan memakai konkurensi
4, dibatasi oleh jumlah skenario yang dipilih. Gunakan `--concurrency <count>` untuk menyesuaikan
jumlah worker, atau `--concurrency 1` untuk eksekusi serial.
Perintah keluar dengan kode non-nol ketika ada skenario yang gagal. Gunakan `--allow-failures` ketika
Perintah keluar dengan non-zero ketika skenario mana pun gagal. Gunakan `--allow-failures` ketika
Anda menginginkan artefak tanpa kode keluar gagal.
Eksekusi live meneruskan input auth QA yang didukung dan praktis untuk
guest: kunci provider berbasis env, path konfigurasi provider live QA, dan
`CODEX_HOME` ketika ada. Simpan `--output-dir` di bawah root repo agar guest
guest: kunci penyedia berbasis env, jalur config penyedia live QA, dan
`CODEX_HOME` jika ada. Simpan `--output-dir` di bawah root repo agar guest
dapat menulis kembali melalui workspace yang di-mount.
## Referensi QA Telegram, Discord, dan Slack
@ -165,19 +195,19 @@ Matrix memiliki [halaman khusus](/id/concepts/qa-matrix) karena jumlah skenarion
Lane ini didaftarkan melalui `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` dan menerima flag yang sama:
| Flag | Default | Deskripsi |
| Flag | Bawaan | Deskripsi |
| ------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `--scenario <id>` | — | Jalankan hanya skenario ini. Dapat diulang. |
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/{telegram,discord,slack}-<timestamp>` | Tempat laporan/ringkasan/pesan teramati dan log output ditulis. Path relatif di-resolve terhadap `--repo-root`. |
| `--repo-root <path>` | `process.cwd()` | Root repositori ketika dipanggil dari cwd netral. |
| `--sut-account <id>` | `sut` | Id akun sementara di dalam konfigurasi Gateway QA. |
| `--provider-mode <mode>` | `live-frontier` | `mock-openai` atau `live-frontier` (`live-openai` lama masih berfungsi). |
| `--model <ref>` / `--alt-model <ref>` | default provider | Ref model utama/alternatif. |
| `--fast` | mati | Mode cepat provider jika didukung. |
| `--credential-source <env\|convex>` | `env` | Lihat [pool kredensial Convex](#convex-credential-pool). |
| `--credential-role <maintainer\|ci>` | `ci` di CI, selain itu `maintainer` | Peran yang digunakan ketika `--credential-source convex`. |
| `--scenario <id>` | — | Jalankan hanya skenario ini. Dapat diulang. |
| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/{telegram,discord,slack}-<timestamp>` | Tempat laporan/ringkasan/pesan teramati dan log output ditulis. Jalur relatif diselesaikan terhadap `--repo-root`. |
| `--repo-root <path>` | `process.cwd()` | Root repositori saat memanggil dari cwd netral. |
| `--sut-account <id>` | `sut` | Id akun sementara di dalam config gateway QA. |
| `--provider-mode <mode>` | `live-frontier` | `mock-openai` atau `live-frontier` (`live-openai` legacy masih berfungsi). |
| `--model <ref>` / `--alt-model <ref>` | bawaan penyedia | Ref model utama/alternatif. |
| `--fast` | nonaktif | Mode cepat penyedia jika didukung. |
| `--credential-source <env\|convex>` | `env` | Lihat [pool kredensial Convex](#convex-credential-pool). |
| `--credential-role <maintainer\|ci>` | `ci` di CI, selain itu `maintainer` | Role yang digunakan ketika `--credential-source convex`. |
Setiap lane keluar dengan kode non-nol pada skenario yang gagal. `--allow-failures` menulis artefak tanpa menetapkan kode keluar gagal.
Setiap lane keluar dengan non-zero pada skenario yang gagal. `--allow-failures` menulis artefak tanpa menetapkan kode keluar gagal.
### QA Telegram
@ -185,9 +215,9 @@ Setiap lane keluar dengan kode non-nol pada skenario yang gagal. `--allow-failur
pnpm openclaw qa telegram
```
Menargetkan satu grup Telegram privat nyata dengan dua bot berbeda (driver + SUT). Bot SUT harus memiliki nama pengguna Telegram; observasi bot-ke-bot bekerja paling baik ketika kedua bot mengaktifkan **Bot-to-Bot Communication Mode** di `@BotFather`.
Menargetkan satu grup Telegram privat nyata dengan dua bot berbeda (driver + SUT). Bot SUT harus memiliki username Telegram; observasi bot-ke-bot bekerja paling baik ketika kedua bot mengaktifkan **Bot-to-Bot Communication Mode** di `@BotFather`.
Env wajib ketika `--credential-source env`:
Env yang diperlukan ketika `--credential-source env`:
- `OPENCLAW_QA_TELEGRAM_GROUP_ID` — id chat numerik (string).
- `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`
@ -195,7 +225,7 @@ Env wajib ketika `--credential-source env`:
Opsional:
- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` mempertahankan isi pesan dalam artefak pesan teramati (default menyunting).
- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` mempertahankan body pesan dalam artefak pesan teramati (bawaan menyamarkan).
Skenario (`extensions/qa-lab/src/live-transports/telegram/telegram-live.runtime.ts:44`):
@ -211,8 +241,8 @@ Skenario (`extensions/qa-lab/src/live-transports/telegram/telegram-live.runtime.
Artefak output:
- `telegram-qa-report.md`
- `telegram-qa-summary.json` — menyertakan RTT per-balasan (driver mengirim → balasan SUT teramati) dimulai dari canary.
- `telegram-qa-observed-messages.json` — isi disunting kecuali `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1`.
- `telegram-qa-summary.json` — mencakup RTT per-balasan (driver mengirim → balasan SUT teramati) dimulai dengan canary.
- `telegram-qa-observed-messages.json` — body disamarkan kecuali `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1`.
### QA Discord
@ -220,28 +250,28 @@ Artefak output:
pnpm openclaw qa discord
```
Menargetkan satu channel guild Discord privat nyata dengan dua bot: bot driver yang dikendalikan oleh harness dan bot SUT yang dimulai oleh Gateway OpenClaw anak melalui Plugin Discord bawaan. Memverifikasi penanganan mention channel, bahwa bot SUT telah mendaftarkan perintah native `/help` dengan Discord, dan skenario bukti Mantis opt-in.
Menargetkan satu channel guild Discord privat nyata dengan dua bot: bot driver yang dikontrol oleh harness dan bot SUT yang dimulai oleh Gateway OpenClaw anak melalui Plugin Discord yang dibundel. Memverifikasi penanganan mention channel, bahwa bot SUT telah mendaftarkan perintah native `/help` dengan Discord, dan skenario bukti Mantis opt-in.
Env wajib ketika `--credential-source env`:
Env yang diperlukan ketika `--credential-source env`:
- `OPENCLAW_QA_DISCORD_GUILD_ID`
- `OPENCLAW_QA_DISCORD_CHANNEL_ID`
- `OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN`
- `OPENCLAW_QA_DISCORD_SUT_BOT_TOKEN`
- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — harus cocok dengan id pengguna bot SUT yang dikembalikan oleh Discord (lane gagal cepat jika tidak).
- `OPENCLAW_QA_DISCORD_SUT_APPLICATION_ID` — harus cocok dengan id pengguna bot SUT yang dikembalikan oleh Discord (jika tidak, lane gagal cepat).
Opsional:
- `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` mempertahankan isi pesan dalam artefak pesan teramati.
- `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1` mempertahankan body pesan dalam artefak pesan teramati.
Skenario (`extensions/qa-lab/src/live-transports/discord/discord-live.runtime.ts:36`):
- `discord-canary`
- `discord-mention-gating`
- `discord-native-help-command-registration`
- `discord-status-reactions-tool-only` — skenario Mantis opt-in. Berjalan sendiri karena mengalihkan SUT ke balasan guild selalu aktif, hanya tool, dengan `messages.statusReactions.enabled=true`, lalu menangkap timeline reaksi REST plus artefak visual HTML/PNG.
- `discord-status-reactions-tool-only` — skenario Mantis opt-in. Berjalan sendiri karena mengalihkan SUT ke balasan guild selalu aktif, hanya tool dengan `messages.statusReactions.enabled=true`, lalu menangkap timeline reaksi REST plus artefak visual HTML/PNG.
Jalankan skenario reaksi status Mantis secara eksplisit:
Jalankan skenario reaksi-status Mantis secara eksplisit:
```bash
pnpm openclaw qa discord \
@ -256,8 +286,8 @@ Artefak output:
- `discord-qa-report.md`
- `discord-qa-summary.json`
- `discord-qa-observed-messages.json` — isi disunting kecuali `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1`.
- `discord-qa-reaction-timelines.json` dan `discord-status-reactions-tool-only-timeline.png` ketika skenario reaksi status berjalan.
- `discord-qa-observed-messages.json` — body disamarkan kecuali `OPENCLAW_QA_DISCORD_CAPTURE_CONTENT=1`.
- `discord-qa-reaction-timelines.json` dan `discord-status-reactions-tool-only-timeline.png` ketika skenario reaksi-status berjalan.
### QA Slack
@ -265,9 +295,9 @@ Artefak output:
pnpm openclaw qa slack
```
Menargetkan satu channel Slack privat nyata dengan dua bot berbeda: bot driver yang dikendalikan oleh harness dan bot SUT yang dimulai oleh Gateway OpenClaw anak melalui Plugin Slack bawaan.
Menargetkan satu channel Slack privat nyata dengan dua bot berbeda: bot driver yang dikontrol oleh harness dan bot SUT yang dimulai oleh Gateway OpenClaw anak melalui Plugin Slack yang dibundel.
Env wajib ketika `--credential-source env`:
Env yang diperlukan ketika `--credential-source env`:
- `OPENCLAW_QA_SLACK_CHANNEL_ID`
- `OPENCLAW_QA_SLACK_DRIVER_BOT_TOKEN`
@ -276,7 +306,7 @@ Env wajib ketika `--credential-source env`:
Opsional:
- `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` mempertahankan isi pesan dalam artefak pesan teramati.
- `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1` mempertahankan body pesan dalam artefak pesan teramati.
Skenario (`extensions/qa-lab/src/live-transports/slack/slack-live.runtime.ts:39`):
@ -287,18 +317,193 @@ Artefak output:
- `slack-qa-report.md`
- `slack-qa-summary.json`
- `slack-qa-observed-messages.json` — isi disunting kecuali `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1`.
- `slack-qa-observed-messages.json` — body disamarkan kecuali `OPENCLAW_QA_SLACK_CAPTURE_CONTENT=1`.
#### Menyiapkan workspace Slack
Lane memerlukan dua aplikasi Slack berbeda dalam satu workspace, plus channel yang diikuti kedua bot:
- `channelId` — id `Cxxxxxxxxxx` dari channel tempat kedua bot telah diundang. Gunakan channel khusus; lane memposting pada setiap eksekusi.
- `driverBotToken` — token bot (`xoxb-...`) dari aplikasi **Driver**.
- `sutBotToken` — token bot (`xoxb-...`) dari aplikasi **SUT**, yang harus berupa aplikasi Slack terpisah dari driver agar id pengguna botnya berbeda.
- `sutAppToken` — token tingkat aplikasi (`xapp-...`) dari aplikasi SUT dengan `connections:write`, digunakan oleh Socket Mode agar aplikasi SUT dapat menerima event.
Lebih baik gunakan workspace Slack khusus untuk QA daripada menggunakan ulang workspace produksi.
Manifest SUT di bawah mencerminkan instalasi produksi Plugin Slack yang dibundel (`extensions/slack/src/setup-shared.ts:10`). Untuk penyiapan channel produksi seperti yang dilihat pengguna, lihat [penyiapan cepat channel Slack](/id/channels/slack#quick-setup); pasangan Driver/SUT QA sengaja dipisahkan karena lane memerlukan dua id pengguna bot berbeda dalam satu workspace.
**1. Buat aplikasi Driver**
Buka [api.slack.com/apps](https://api.slack.com/apps) → _Create New App_ → _From a manifest_ → pilih workspace QA, tempel manifest berikut, lalu _Install to Workspace_:
```json
{
"display_information": {
"name": "OpenClaw QA Driver",
"description": "Test driver bot for OpenClaw QA Slack live lane"
},
"features": {
"bot_user": {
"display_name": "OpenClaw QA Driver",
"always_online": true
}
},
"oauth_config": {
"scopes": {
"bot": ["chat:write", "channels:history", "groups:history", "users:read"]
}
},
"settings": {
"socket_mode_enabled": false
}
}
```
Salin _Bot User OAuth Token_ (`xoxb-...`) — itu menjadi `driverBotToken`. Driver hanya perlu memposting pesan dan mengidentifikasi dirinya; tidak ada event, tidak ada Socket Mode.
**2. Buat aplikasi SUT**
Ulangi _Create New App → From a manifest_ di workspace yang sama. Set scope mencerminkan instalasi produksi Plugin Slack yang dibundel (`extensions/slack/src/setup-shared.ts:10`):
```json
{
"display_information": {
"name": "OpenClaw QA SUT",
"description": "OpenClaw QA SUT connector for OpenClaw"
},
"features": {
"bot_user": {
"display_name": "OpenClaw QA SUT",
"always_online": true
},
"app_home": {
"home_tab_enabled": true,
"messages_tab_enabled": true,
"messages_tab_read_only_enabled": false
}
},
"oauth_config": {
"scopes": {
"bot": [
"app_mentions:read",
"assistant:write",
"channels:history",
"channels:read",
"chat:write",
"commands",
"emoji:read",
"files:read",
"files:write",
"groups:history",
"groups:read",
"im:history",
"im:read",
"im:write",
"mpim:history",
"mpim:read",
"mpim:write",
"pins:read",
"pins:write",
"reactions:read",
"reactions:write",
"usergroups:read",
"users:read"
]
}
},
"settings": {
"socket_mode_enabled": true,
"event_subscriptions": {
"bot_events": [
"app_home_opened",
"app_mention",
"channel_rename",
"member_joined_channel",
"member_left_channel",
"message.channels",
"message.groups",
"message.im",
"message.mpim",
"pin_added",
"pin_removed",
"reaction_added",
"reaction_removed"
]
}
}
}
```
Setelah Slack membuat aplikasi, lakukan dua hal di halaman pengaturannya:
- _Install to Workspace_ → salin _Bot User OAuth Token_ → itu menjadi `sutBotToken`.
- _Basic Information → App-Level Tokens → Generate Token and Scopes_ → tambahkan scope `connections:write` → simpan → salin nilai `xapp-...` → itu menjadi `sutAppToken`.
Verifikasi bahwa kedua bot memiliki id pengguna yang berbeda dengan memanggil `auth.test` pada setiap token. Runtime membedakan driver dan SUT berdasarkan id pengguna; menggunakan ulang satu aplikasi untuk keduanya akan langsung membuat gating sebutan gagal.
**3. Buat channel**
Di workspace QA, buat channel (mis. `#openclaw-qa`) dan undang kedua bot dari dalam channel:
```
/invite @OpenClaw QA Driver
/invite @OpenClaw QA SUT
```
Salin id `Cxxxxxxxxxx` dari _channel info → About → Channel ID_ — itu menjadi `channelId`. Channel publik bisa digunakan; jika Anda memakai channel privat, kedua aplikasi sudah memiliki `groups:history` sehingga pembacaan riwayat harness tetap akan berhasil.
**4. Daftarkan kredensial**
Ada dua opsi. Gunakan variabel env untuk debugging satu mesin (atur empat variabel `OPENCLAW_QA_SLACK_*` dan teruskan `--credential-source env`), atau isi pool Convex bersama agar CI dan maintainer lain dapat menyewanya.
Untuk pool Convex, tulis empat field ke file JSON:
```json
{
"channelId": "Cxxxxxxxxxx",
"driverBotToken": "xoxb-...",
"sutBotToken": "xoxb-...",
"sutAppToken": "xapp-..."
}
```
Dengan `OPENCLAW_QA_CONVEX_SITE_URL` dan `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` diekspor di shell Anda, daftarkan dan verifikasi:
```bash
pnpm openclaw qa credentials add \
--kind slack \
--payload-file slack-creds.json \
--note "QA Slack pool seed"
pnpm openclaw qa credentials list --kind slack --status all --json
```
Harapkan `count: 1`, `status: "active"`, tanpa field `lease`.
**5. Verifikasi ujung ke ujung**
Jalankan lane secara lokal untuk mengonfirmasi kedua bot dapat saling berbicara melalui broker:
```bash
pnpm openclaw qa slack \
--credential-source convex \
--credential-role maintainer \
--output-dir .artifacts/qa-e2e/slack-local
```
Run hijau selesai jauh di bawah 30 detik dan `slack-qa-report.md` menampilkan `slack-canary` dan `slack-mention-gating` dengan status `pass`. Jika lane menggantung selama sekitar 90 detik dan keluar dengan `Convex credential pool exhausted for kind "slack"`, berarti pool kosong atau setiap baris sedang disewa — `qa credentials list --kind slack --status all --json` akan memberi tahu Anda yang mana.
### Pool kredensial Convex
Lane Telegram, Discord, dan Slack dapat menyewa kredensial dari pool Convex bersama alih-alih membaca env var di atas. Berikan `--credential-source convex` (atau tetapkan `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`); QA Lab memperoleh lease eksklusif, mengirim Heartbeat selama durasi eksekusi, dan melepaskannya saat shutdown. Jenis pool adalah `"telegram"`, `"discord"`, dan `"slack"`.
Lane Telegram, Discord, dan Slack dapat menyewa kredensial dari pool Convex bersama, bukan membaca variabel env di atas. Teruskan `--credential-source convex` (atau atur `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`); QA Lab memperoleh lease eksklusif, mengirim heartbeat selama durasi run, dan merilisnya saat shutdown. Jenis pool adalah `"telegram"`, `"discord"`, dan `"slack"`.
Bentuk payload yang divalidasi broker pada `admin/add`:
- Telegram (`kind: "telegram"`): `{ groupId: string, driverToken: string, sutToken: string }` — `groupId` harus berupa string chat-id numerik.
- Discord (`kind: "discord"`): `{ guildId: string, channelId: string, driverBotToken: string, sutBotToken: string, sutApplicationId: string }`.
- Slack (`kind: "slack"`): `{ channelId: string, driverBotToken: string, sutBotToken: string, sutAppToken: string }` — `channelId` harus cocok dengan `^[A-Z][A-Z0-9]+$` (id Slack seperti `Cxxxxxxxxxx`). Lihat [Menyiapkan workspace Slack](#setting-up-the-slack-workspace) untuk penyediaan aplikasi dan scope.
Env var operasional dan kontrak endpoint broker Convex ada di [Pengujian → Kredensial Telegram bersama melalui Convex](/id/help/testing#shared-telegram-credentials-via-convex-v1) (nama bagian mendahului dukungan Discord; semantik broker identik untuk kedua jenis).
Variabel env operasional dan kontrak endpoint broker Convex berada di [Pengujian → Kredensial Telegram bersama melalui Convex](/id/help/testing#shared-telegram-credentials-via-convex-v1) (nama bagian mendahului dukungan Discord; semantik broker identik untuk kedua jenis).
## Seed berbasis repo
@ -307,76 +512,76 @@ Aset seed berada di `qa/`:
- `qa/scenarios/index.md`
- `qa/scenarios/<theme>/*.md`
Ini sengaja ada di git sehingga rencana QA terlihat oleh manusia maupun
agent.
Ini sengaja berada di git agar rencana QA terlihat oleh manusia maupun
agen.
`qa-lab` harus tetap menjadi runner markdown generik. Setiap file markdown skenario adalah
sumber kebenaran untuk satu eksekusi pengujian dan harus mendefinisikan:
sumber kebenaran untuk satu run pengujian dan harus mendefinisikan:
- metadata skenario
- metadata kategori, kapabilitas, lane, dan risiko opsional
- ref docs dan kode
- metadata kategori, kemampuan, lane, dan risiko opsional
- referensi docs dan kode
- persyaratan Plugin opsional
- patch konfigurasi Gateway opsional
- `qa-flow` yang dapat dieksekusi
Permukaan runtime yang dapat digunakan ulang yang mendukung `qa-flow` boleh tetap generik
dan lintas area. Misalnya, skenario markdown dapat menggabungkan helper sisi transport
dengan helper sisi browser yang mengendalikan Control UI tertanam melalui
seam Gateway `browser.request` tanpa menambahkan runner kasus khusus.
dengan helper sisi browser yang menggerakkan Control UI tertanam melalui seam
Gateway `browser.request` tanpa menambahkan runner kasus khusus.
File skenario harus dikelompokkan berdasarkan kapabilitas produk, bukan folder
source tree. Pertahankan ID skenario tetap stabil ketika file dipindahkan; gunakan `docsRefs` dan `codeRefs`
untuk ketertelusuran implementasi.
File skenario harus dikelompokkan berdasarkan kemampuan produk, bukan folder
source tree. Pertahankan ID skenario tetap stabil saat file dipindahkan; gunakan `docsRefs` dan `codeRefs`
untuk keterlacakan implementasi.
Daftar baseline harus tetap cukup luas untuk mencakup:
- DM dan chat channel
- chat DM dan channel
- perilaku thread
- siklus hidup tindakan pesan
- callback Cron
- recall memory
- pengalihan model
- handoff subagent
- siklus hidup aksi pesan
- callback cron
- pemanggilan kembali memori
- pergantian model
- handoff subagen
- pembacaan repo dan pembacaan docs
- satu tugas build kecil seperti Lobster Invaders
## Lane mock provider
## Lane mock penyedia
`qa suite` memiliki dua lane mock provider lokal:
`qa suite` memiliki dua lane mock penyedia lokal:
- `mock-openai` adalah mock OpenClaw yang sadar skenario. Ini tetap menjadi lane mock
deterministik default untuk QA berbasis repo dan gate paritas.
- `aimock` memulai server provider berbasis AIMock untuk cakupan protokol eksperimental,
fixture, record/replay, dan chaos. Ini bersifat aditif dan tidak
- `aimock` memulai server penyedia berbasis AIMock untuk cakupan protokol,
fixture, record/replay, dan chaos eksperimental. Ini bersifat aditif dan tidak
menggantikan dispatcher skenario `mock-openai`.
Implementasi lane provider berada di bawah `extensions/qa-lab/src/providers/`.
Setiap provider memiliki defaultnya sendiri, startup server lokal, konfigurasi model Gateway,
kebutuhan staging auth-profile, dan flag kapabilitas live/mock. Kode suite bersama dan
Gateway harus merutekan melalui registri provider alih-alih bercabang berdasarkan
nama provider.
Implementasi lane penyedia berada di bawah `extensions/qa-lab/src/providers/`.
Setiap penyedia memiliki defaultnya sendiri, startup server lokal, konfigurasi model gateway,
kebutuhan staging auth-profile, dan flag kemampuan live/mock. Kode suite dan
Gateway bersama harus merutekan melalui registry penyedia, bukan membuat branch berdasarkan
nama penyedia.
## Adapter transport
`qa-lab` memiliki seam transport generik untuk skenario QA markdown. `qa-channel` adalah adapter pertama pada seam itu, tetapi target desainnya lebih luas: channel nyata atau sintetis di masa depan harus tersambung ke runner suite yang sama alih-alih menambahkan runner QA khusus transport.
`qa-lab` memiliki seam transport generik untuk skenario QA markdown. `qa-channel` adalah adapter pertama pada seam itu, tetapi target desainnya lebih luas: channel nyata atau sintetis di masa depan harus terhubung ke runner suite yang sama, bukan menambahkan runner QA khusus transport.
Pada level arsitektur, pembagiannya adalah:
Pada tingkat arsitektur, pemisahannya adalah:
- `qa-lab` memiliki eksekusi skenario generik, konkurensi worker, penulisan artefak, dan pelaporan.
- Adapter transport memiliki konfigurasi Gateway, kesiapan, observasi masuk dan keluar, tindakan transport, dan status transport yang dinormalisasi.
- File skenario markdown di bawah `qa/scenarios/` mendefinisikan eksekusi pengujian; `qa-lab` menyediakan permukaan runtime yang dapat digunakan ulang untuk mengeksekusinya.
- Adapter transport memiliki konfigurasi Gateway, kesiapan, observasi inbound dan outbound, aksi transport, dan state transport ternormalisasi.
- File skenario markdown di bawah `qa/scenarios/` mendefinisikan run pengujian; `qa-lab` menyediakan permukaan runtime yang dapat digunakan ulang untuk mengeksekusinya.
### Menambahkan channel
Menambahkan channel ke sistem QA markdown memerlukan tepat dua hal:
Menambahkan channel ke sistem QA markdown membutuhkan tepat dua hal:
1. Adapter transport untuk channel tersebut.
2. Paket skenario yang menguji kontrak channel.
Jangan tambahkan root perintah QA top-level baru ketika host `qa-lab` bersama dapat memiliki flow.
Jangan tambahkan root perintah QA tingkat atas baru ketika host bersama `qa-lab` dapat memiliki alur tersebut.
`qa-lab` memiliki mekanisme host bersama:
`qa-lab` memiliki mekanik host bersama:
- root perintah `openclaw qa`
- startup dan teardown suite
@ -388,21 +593,21 @@ Jangan tambahkan root perintah QA top-level baru ketika host `qa-lab` bersama da
Plugin runner memiliki kontrak transport:
- cara `openclaw qa <runner>` dipasang di bawah root `qa` bersama
- cara gateway dikonfigurasi untuk transport tersebut
- cara kesiapan diperiksa
- cara event masuk diinjeksi
- cara pesan keluar diamati
- cara transkrip dan status transport yang dinormalisasi diekspos
- cara tindakan berbasis transport dieksekusi
- cara reset atau pembersihan khusus transport ditangani
- bagaimana `openclaw qa <runner>` dipasang di bawah root `qa` bersama
- bagaimana Gateway dikonfigurasi untuk transport tersebut
- bagaimana kesiapan diperiksa
- bagaimana event inbound diinjeksi
- bagaimana pesan outbound diamati
- bagaimana transkrip dan state transport ternormalisasi diekspos
- bagaimana aksi berbasis transport dieksekusi
- bagaimana reset atau pembersihan khusus transport ditangani
Batas minimum adopsi untuk channel baru:
Bar adopsi minimum untuk channel baru:
1. Pertahankan `qa-lab` sebagai pemilik root `qa` bersama.
2. Implementasikan runner transport pada seam host `qa-lab` bersama.
3. Pertahankan mekanisme khusus transport di dalam Plugin runner atau harness channel.
4. Pasang runner sebagai `openclaw qa <runner>`, bukan mendaftarkan perintah root tandingan. Plugin runner harus mendeklarasikan `qaRunners` di `openclaw.plugin.json` dan mengekspor array `qaRunnerCliRegistrations` yang cocok dari `runtime-api.ts`. Jaga agar `runtime-api.ts` tetap ringan; CLI lazy dan eksekusi runner harus tetap berada di balik entrypoint terpisah.
3. Simpan mekanik khusus transport di dalam Plugin runner atau harness channel.
4. Pasang runner sebagai `openclaw qa <runner>`, bukan mendaftarkan root perintah yang bersaing. Plugin runner harus mendeklarasikan `qaRunners` di `openclaw.plugin.json` dan mengekspor array `qaRunnerCliRegistrations` yang cocok dari `runtime-api.ts`. Jaga `runtime-api.ts` tetap ringan; eksekusi CLI dan runner yang lazy harus tetap berada di balik entrypoint terpisah.
5. Tulis atau adaptasi skenario markdown di bawah direktori bertema `qa/scenarios/`.
6. Gunakan helper skenario generik untuk skenario baru.
7. Pertahankan alias kompatibilitas yang ada tetap berfungsi kecuali repo sedang melakukan migrasi yang disengaja.
@ -410,9 +615,9 @@ Batas minimum adopsi untuk channel baru:
Aturan keputusannya ketat:
- Jika perilaku dapat diekspresikan sekali di `qa-lab`, letakkan di `qa-lab`.
- Jika perilaku bergantung pada satu transport channel, pertahankan di Plugin runner atau harness Plugin tersebut.
- Jika sebuah skenario membutuhkan kemampuan baru yang dapat digunakan lebih dari satu channel, tambahkan helper generik alih-alih cabang khusus channel di `suite.ts`.
- Jika suatu perilaku hanya bermakna untuk satu transport, pertahankan skenario tersebut khusus transport dan buat hal itu eksplisit dalam kontrak skenario.
- Jika perilaku bergantung pada satu transport channel, simpan di Plugin runner atau harness Plugin tersebut.
- Jika skenario membutuhkan kemampuan baru yang dapat digunakan oleh lebih dari satu channel, tambahkan helper generik, bukan branch khusus channel di `suite.ts`.
- Jika suatu perilaku hanya bermakna untuk satu transport, pertahankan skenario khusus transport dan nyatakan itu secara eksplisit dalam kontrak skenario.
### Nama helper skenario
@ -431,7 +636,7 @@ Helper generik yang disarankan untuk skenario baru:
- `formatTransportTranscript`
- `resetTransport`
Alias kompatibilitas tetap tersedia untuk skenario yang ada — `waitForQaChannelReady`, `waitForOutboundMessage`, `waitForNoOutbound`, `formatConversationTranscript`, `resetBus` — tetapi penulisan skenario baru harus menggunakan nama generik. Alias ada untuk menghindari migrasi serentak, bukan sebagai model ke depannya.
Alias kompatibilitas tetap tersedia untuk skenario yang ada — `waitForQaChannelReady`, `waitForOutboundMessage`, `waitForNoOutbound`, `formatConversationTranscript`, `resetBus` — tetapi penulisan skenario baru harus menggunakan nama generik. Alias ada untuk menghindari migrasi serentak, bukan sebagai model ke depan.
## Pelaporan
@ -443,7 +648,7 @@ Laporan harus menjawab:
- Apa yang tetap terblokir
- Skenario tindak lanjut apa yang layak ditambahkan
Untuk inventaris skenario yang tersedia — berguna saat memperkirakan pekerjaan tindak lanjut atau menyambungkan transport baru — jalankan `pnpm openclaw qa coverage` (tambahkan `--json` untuk output yang dapat dibaca mesin).
Untuk inventaris skenario yang tersedia — berguna saat mengukur pekerjaan tindak lanjut atau menghubungkan transport baru — jalankan `pnpm openclaw qa coverage` (tambahkan `--json` untuk output yang dapat dibaca mesin).
Untuk pemeriksaan karakter dan gaya, jalankan skenario yang sama di beberapa ref model live
dan tulis laporan Markdown yang dinilai:
@ -465,42 +670,21 @@ pnpm openclaw qa character-eval \
--judge-concurrency 16
```
Perintah tersebut menjalankan proses anak Gateway QA lokal, bukan Docker. Skenario evaluasi karakter
harus menetapkan persona melalui `SOUL.md`, lalu menjalankan giliran pengguna biasa
seperti chat, bantuan workspace, dan tugas file kecil. Model kandidat tidak boleh
diberi tahu bahwa ia sedang dievaluasi. Perintah ini mempertahankan setiap
transkrip lengkap, mencatat statistik run dasar, lalu meminta model juri dalam mode cepat dengan
penalaran `xhigh` jika didukung untuk memberi peringkat run berdasarkan kewajaran, nuansa, dan humor.
Gunakan `--blind-judge-models` saat membandingkan provider: prompt juri tetap mendapatkan
setiap transkrip dan status run, tetapi ref kandidat diganti dengan label netral
seperti `candidate-01`; laporan memetakan peringkat kembali ke ref sebenarnya setelah
parsing.
Run kandidat secara default menggunakan thinking `high`, dengan `medium` untuk GPT-5.5 dan `xhigh`
untuk ref evaluasi OpenAI lama yang mendukungnya. Timpa kandidat tertentu secara inline dengan
`--model provider/model,thinking=<level>`. `--thinking <level>` masih menetapkan
fallback global, dan bentuk lama `--model-thinking <provider/model=level>` tetap
dipertahankan untuk kompatibilitas.
Ref kandidat OpenAI secara default menggunakan mode cepat agar pemrosesan prioritas digunakan jika
provider mendukungnya. Tambahkan `,fast`, `,no-fast`, atau `,fast=false` secara inline ketika
satu kandidat atau juri membutuhkan override. Berikan `--fast` hanya ketika Anda ingin
memaksa mode cepat aktif untuk setiap model kandidat. Durasi kandidat dan juri
dicatat dalam laporan untuk analisis benchmark, tetapi prompt juri secara eksplisit mengatakan
untuk tidak memberi peringkat berdasarkan kecepatan.
Run model kandidat dan juri keduanya secara default menggunakan konkurensi 16. Turunkan
`--concurrency` atau `--judge-concurrency` ketika batas provider atau tekanan Gateway lokal
membuat run terlalu berisik.
Jika tidak ada kandidat `--model` yang diberikan, evaluasi karakter secara default menggunakan
`openai/gpt-5.5`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`,
`anthropic/claude-sonnet-4-6`, `zai/glm-5.1`,
Perintah ini menjalankan proses anak Gateway QA lokal, bukan Docker. Skenario evaluasi karakter harus menetapkan persona melalui `SOUL.md`, lalu menjalankan giliran pengguna biasa seperti chat, bantuan ruang kerja, dan tugas file kecil. Model kandidat tidak boleh diberi tahu bahwa model tersebut sedang dievaluasi. Perintah ini menyimpan setiap transkrip lengkap, mencatat statistik dasar proses, lalu meminta model penilai dalam mode cepat dengan penalaran `xhigh` jika didukung untuk memeringkat proses berdasarkan kewajaran, nuansa, dan humor.
Gunakan `--blind-judge-models` saat membandingkan penyedia: prompt penilai tetap mendapatkan setiap transkrip dan status proses, tetapi referensi kandidat diganti dengan label netral seperti `candidate-01`; laporan memetakan peringkat kembali ke referensi asli setelah parsing.
Proses kandidat secara default menggunakan tingkat berpikir `high`, dengan `medium` untuk GPT-5.5 dan `xhigh` untuk referensi evaluasi OpenAI lama yang mendukungnya. Timpa kandidat tertentu secara inline dengan `--model provider/model,thinking=<level>`. `--thinking <level>` tetap menetapkan fallback global, dan bentuk lama `--model-thinking <provider/model=level>` dipertahankan untuk kompatibilitas.
Referensi kandidat OpenAI secara default menggunakan mode cepat sehingga pemrosesan prioritas digunakan jika penyedia mendukungnya. Tambahkan `,fast`, `,no-fast`, atau `,fast=false` secara inline saat satu kandidat atau penilai memerlukan penimpaan. Berikan `--fast` hanya saat Anda ingin memaksa mode cepat aktif untuk setiap model kandidat. Durasi kandidat dan penilai dicatat dalam laporan untuk analisis benchmark, tetapi prompt penilai secara eksplisit mengatakan untuk tidak memeringkat berdasarkan kecepatan.
Proses model kandidat dan penilai sama-sama default ke konkurensi 16. Turunkan `--concurrency` atau `--judge-concurrency` saat batas penyedia atau tekanan Gateway lokal membuat proses terlalu bising.
Saat tidak ada kandidat `--model` yang diberikan, evaluasi karakter secara default menggunakan `openai/gpt-5.5`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-6`, `zai/glm-5.1`,
`moonshot/kimi-k2.5`, dan
`google/gemini-3.1-pro-preview` ketika tidak ada `--model` yang diberikan.
Jika tidak ada `--judge-model` yang diberikan, juri secara default menggunakan
`google/gemini-3.1-pro-preview` saat tidak ada `--model` yang diberikan.
Saat tidak ada `--judge-model` yang diberikan, penilai secara default menggunakan
`openai/gpt-5.5,thinking=xhigh,fast` dan
`anthropic/claude-opus-4-6,thinking=high`.
## Dokumen terkait
- [QA Matriks](/id/concepts/qa-matrix)
- [Channel QA](/id/channels/qa-channel)
- [Matriks QA](/id/concepts/qa-matrix)
- [Kanal QA](/id/channels/qa-channel)
- [Pengujian](/id/help/testing)
- [Dasbor](/id/web/dashboard)

170
docs/id/gateway/config-tools.md
View File

@ -1,35 +1,35 @@
---
read_when:
- Mengonfigurasi kebijakan `tools.*`, daftar izin, atau fitur eksperimental
- Mengonfigurasi kebijakan `tools.*`, daftar yang diizinkan, atau fitur eksperimental
- Mendaftarkan penyedia kustom atau mengganti URL dasar
- Menyiapkan endpoint yang dihosting sendiri dan kompatibel dengan OpenAI
sidebarTitle: Tools and custom providers
summary: Konfigurasi alat (kebijakan, sakelar eksperimental, alat yang didukung penyedia) dan penyiapan penyedia/URL dasar kustom
summary: Konfigurasi alat (kebijakan, toggle eksperimental, alat yang didukung provider) dan penyiapan provider/URL dasar kustom
title: Konfigurasi — alat dan penyedia kustom
x-i18n:
generated_at: "2026-05-03T21:31:32Z"
generated_at: "2026-05-05T01:45:54Z"
model: gpt-5.5
provider: openai
source_hash: 75a39342f40e9c329a7c61855e805ec43532cbdb89fbe801acc26830fd63b4da
source_hash: 9196bff46d8b0f9447fb46b47fc764f5bbc4f0b19eb252d4db611e94e57b4883
source_path: gateway/config-tools.md
workflow: 16
---
`tools.*` kunci konfigurasi dan penyiapan penyedia kustom / URL dasar. Untuk agen, channel, dan kunci konfigurasi tingkat atas lainnya, lihat [Referensi konfigurasi](/id/gateway/configuration-reference).
`tools.*` kunci konfigurasi dan penyiapan penyedia kustom / base-URL. Untuk agent, channel, dan kunci konfigurasi tingkat atas lainnya, lihat [Referensi konfigurasi](/id/gateway/configuration-reference).
## Alat
### Profil alat
`tools.profile` menetapkan allowlist dasar sebelum `tools.allow`/`tools.deny`:
`tools.profile` menetapkan daftar izin dasar sebelum `tools.allow`/`tools.deny`:
<Note>
Orientasi lokal menetapkan default konfigurasi lokal baru ke `tools.profile: "coding"` saat belum disetel (profil eksplisit yang sudah ada dipertahankan).
Onboarding lokal menetapkan default konfigurasi lokal baru ke `tools.profile: "coding"` saat belum disetel (profil eksplisit yang sudah ada dipertahankan).
</Note>
| Profil | Mencakup |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `minimal` | `session_status` saja |
| `minimal` | Hanya `session_status` |
| `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` |
| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` |
| `full` | Tanpa pembatasan (sama seperti tidak disetel) |
@ -38,7 +38,7 @@ Orientasi lokal menetapkan default konfigurasi lokal baru ke `tools.profile: "co
| Grup | Alat |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `group:runtime` | `exec`, `process`, `code_execution` (`bash` diterima sebagai alias untuk `exec`) |
| `group:runtime` | `exec`, `process`, `code_execution` (`bash` diterima sebagai alias untuk `exec`) |
| `group:fs` | `read`, `write`, `edit`, `apply_patch` |
| `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` |
| `group:memory` | `memory_search`, `memory_get` |
@ -49,11 +49,11 @@ Orientasi lokal menetapkan default konfigurasi lokal baru ke `tools.profile: "co
| `group:nodes` | `nodes` |
| `group:agents` | `agents_list` |
| `group:media` | `image`, `image_generate`, `video_generate`, `tts` |
| `group:openclaw` | Semua alat bawaan (tidak termasuk Plugin penyedia) |
| `group:openclaw` | Semua alat bawaan (mengecualikan Plugin penyedia) |
### `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 izinkan/tolak alat global (tolak menang). Tidak peka huruf besar/kecil, mendukung wildcard `*`. Diterapkan bahkan saat sandbox Docker nonaktif.
```json5
{
@ -71,7 +71,7 @@ Kebijakan allow/deny alat global (deny menang). Tidak peka huruf besar/kecil, me
### `tools.byProvider`
Batasi alat lebih lanjut untuk penyedia atau model tertentu. Urutan: profil dasar → profil penyedia → allow/deny.
Membatasi alat lebih lanjut untuk penyedia atau model tertentu. Urutan: profil dasar → profil penyedia → izinkan/tolak.
```json5
{
@ -103,7 +103,7 @@ Mengontrol akses exec yang ditingkatkan di luar sandbox:
}
```
- Override per agen (`agents.list[].tools.elevated`) hanya dapat memperketat pembatasan.
- Penggantian 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` yang ditingkatkan melewati sandboxing dan menggunakan jalur escape yang dikonfigurasi (`gateway` secara default, atau `node` saat target exec adalah `node`).
@ -129,7 +129,7 @@ Mengontrol akses exec yang ditingkatkan di luar sandbox:
### `tools.loopDetection`
Pemeriksaan keamanan loop alat **dinonaktifkan secara default**. Setel `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 alat **dinonaktifkan secara default**. Setel `enabled: true` untuk mengaktifkan deteksi. Pengaturan dapat didefinisikan secara global di `tools.loopDetection` dan diganti per-agent di `agents.list[].tools.loopDetection`.
```json5
{
@ -151,25 +151,25 @@ Pemeriksaan keamanan loop alat **dinonaktifkan secara default**. Setel `enabled:
```
<ParamField path="historySize" type="number">
Riwayat maksimum pemanggilan alat yang dipertahankan untuk analisis loop.
Riwayat panggilan alat maksimum yang dipertahankan untuk analisis loop.
</ParamField>
<ParamField path="warningThreshold" type="number">
Ambang pola berulang tanpa progres untuk peringatan.
</ParamField>
<ParamField path="criticalThreshold" type="number">
Ambang berulang yang lebih tinggi untuk memblokir loop kritis.
Ambang pengulangan yang lebih tinggi untuk memblokir loop kritis.
</ParamField>
<ParamField path="globalCircuitBreakerThreshold" type="number">
Ambang penghentian paksa untuk run tanpa progres apa pun.
Ambang penghentian paksa untuk proses apa pun yang tanpa progres.
</ParamField>
<ParamField path="detectors.genericRepeat" type="boolean">
Peringatkan pada pemanggilan alat yang sama/argumen yang sama secara berulang.
Peringatkan pada panggilan alat yang sama/argumen yang sama secara berulang.
</ParamField>
<ParamField path="detectors.knownPollNoProgress" type="boolean">
Peringatkan/blokir pada alat polling yang dikenal (`process.poll`, `command_status`, dll.).
</ParamField>
<ParamField path="detectors.pingPong" type="boolean">
Peringatkan/blokir pada pola pasangan tanpa progres yang bergantian.
Peringatkan/blokir pada pola pasangan bergantian tanpa progres.
</ParamField>
<Warning>
@ -216,7 +216,7 @@ Mengonfigurasi pemahaman media masuk (gambar/audio/video):
media: {
concurrency: 2,
asyncCompletion: {
directSend: false, // opt-in: send finished async video directly to the channel
directSend: false, // deprecated: completions stay agent-mediated
},
audio: {
enabled: true,
@ -246,30 +246,30 @@ Mengonfigurasi pemahaman media masuk (gambar/audio/video):
```
<AccordionGroup>
<Accordion title="Media model entry fields">
<Accordion title="Bidang entri model media">
**Entri penyedia** (`type: "provider"` atau dihilangkan):
- `provider`: id penyedia API (`openai`, `anthropic`, `google`/`gemini`, `groq`, dll.)
- `model`: penggantian id model
- `model`: pengganti id model
- `profile` / `preferredProfile`: pemilihan profil `auth-profiles.json`
**Entri CLI** (`type: "cli"`):
- `command`: executable yang akan dijalankan
- `args`: argumen bertemplat (mendukung `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, dll.; `openclaw doctor --fix` memigrasikan placeholder `{input}` yang tidak digunakan lagi ke `{{MediaPath}}`)
- `args`: argumen berbasis templat (mendukung `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, dll.; `openclaw doctor --fix` memigrasikan placeholder `{input}` yang sudah usang ke `{{MediaPath}}`)
**Kolom umum:**
**Bidang umum:**
- `capabilities`: daftar opsional (`image`, `audio`, `video`). Default: `openai`/`anthropic`/`minimax` → gambar, `google` → gambar+audio+video, `groq` → audio.
- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: penggantian per entri.
- `tools.media.image.timeoutSeconds` dan entri `timeoutSeconds` model gambar yang cocok juga berlaku saat agen memanggil alat `image` eksplisit.
- Kegagalan beralih ke entri berikutnya.
- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: pengganti per entri.
- Entri `tools.media.image.timeoutSeconds` dan `timeoutSeconds` model gambar yang cocok juga berlaku saat agen memanggil alat `image` eksplisit.
- Kegagalan akan beralih ke entri berikutnya.
Auth penyedia mengikuti urutan standar: `auth-profiles.json` → env vars → `models.providers.*.apiKey`.
Autentikasi penyedia mengikuti urutan standar: `auth-profiles.json` → variabel env → `models.providers.*.apiKey`.
**Kolom penyelesaian async:**
**Bidang penyelesaian asinkron:**
- `asyncCompletion.directSend`: saat `true`, tugas media async selesai yang mendukung pengiriman penyelesaian langsung akan mencoba pengiriman channel langsung terlebih dahulu. Default: `false` (jalur bangun sesi peminta/pengiriman model). Saat ini ini berlaku untuk `video_generate` async; penyelesaian `music_generate` async tetap dimediasi sesi peminta bahkan saat ini diaktifkan.
- `asyncCompletion.directSend`: flag kompatibilitas yang sudah usang. Tugas media asinkron yang selesai tetap dimediasi oleh sesi peminta sehingga agen menerima hasilnya, memutuskan cara memberi tahu pengguna, dan menggunakan alat pesan saat pengiriman sumber memerlukannya.
</Accordion>
</AccordionGroup>
@ -305,12 +305,12 @@ Default: `tree` (sesi saat ini + sesi yang dibuat olehnya, seperti subagen).
```
<AccordionGroup>
<Accordion title="Visibility scopes">
<Accordion title="Cakupan visibilitas">
- `self`: hanya kunci sesi saat ini.
- `tree`: sesi saat ini + sesi yang dibuat oleh sesi saat ini (subagen).
- `agent`: sesi apa pun yang termasuk dalam id agen saat ini (dapat mencakup pengguna lain jika Anda menjalankan sesi per pengirim di bawah id agen yang sama).
- `agent`: sesi apa pun milik id agen saat ini (dapat mencakup pengguna lain jika Anda menjalankan sesi per pengirim di bawah id agen yang sama).
- `all`: sesi apa pun. Penargetan lintas agen tetap memerlukan `tools.agentToAgent`.
- Penjepitan sandbox: saat sesi saat ini berada dalam sandbox dan `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, visibilitas dipaksa menjadi `tree` meskipun `tools.sessions.visibility="all"`.
- Pembatasan sandbox: saat sesi saat ini berada dalam sandbox dan `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, visibilitas dipaksa menjadi `tree` meskipun `tools.sessions.visibility="all"`.
</Accordion>
</AccordionGroup>
@ -338,9 +338,9 @@ Mengontrol dukungan lampiran inline untuk `sessions_spawn`.
<AccordionGroup>
<Accordion title="Catatan lampiran">
- Lampiran hanya didukung untuk `runtime: "subagent"`. Runtime ACP menolaknya.
- File dimaterialisasikan ke workspace anak di `.openclaw/attachments/<uuid>/` dengan `.manifest.json`.
- File dimaterialisasikan ke ruang kerja anak di `.openclaw/attachments/<uuid>/` dengan `.manifest.json`.
- Konten lampiran otomatis disunting dari persistensi transkrip.
- Input Base64 divalidasi dengan pemeriksaan alfabet/padding yang ketat dan pelindung ukuran pra-dekode.
- Input Base64 divalidasi dengan pemeriksaan alfabet/padding yang ketat dan pengaman ukuran pra-dekode.
- Izin file adalah `0700` untuk direktori dan `0600` untuk file.
- Pembersihan mengikuti kebijakan `cleanup`: `delete` selalu menghapus lampiran; `keep` mempertahankannya hanya ketika `retainOnSessionKeep: true`.
@ -351,7 +351,7 @@ Mengontrol dukungan lampiran inline untuk `sessions_spawn`.
### `tools.experimental`
Flag alat bawaan eksperimental. Default nonaktif kecuali aturan aktif otomatis GPT-5 strict-agentic berlaku.
Flag alat bawaan eksperimental. Nonaktif secara default kecuali aturan pengaktifan otomatis GPT-5 strict-agentic berlaku.
```json5
{
@ -363,9 +363,9 @@ Flag alat bawaan eksperimental. Default nonaktif kecuali aturan aktif otomatis G
}
```
- `planTool`: mengaktifkan alat `update_plan` terstruktur untuk pelacakan pekerjaan multi-langkah yang tidak sepele.
- Default: `false` kecuali `agents.defaults.embeddedPi.executionContract` (atau override per agen) diatur ke `"strict-agentic"` untuk run OpenAI atau OpenAI Codex keluarga GPT-5. Atur `true` untuk memaksa alat aktif di luar cakupan tersebut, atau `false` agar tetap nonaktif bahkan untuk run GPT-5 strict-agentic.
- Saat diaktifkan, prompt sistem juga menambahkan panduan penggunaan agar model hanya menggunakannya untuk pekerjaan substansial dan menjaga paling banyak satu langkah `in_progress`.
- `planTool`: mengaktifkan alat `update_plan` terstruktur untuk pelacakan pekerjaan multi-langkah non-trivial.
- Default: `false` kecuali `agents.defaults.embeddedPi.executionContract` (atau override per-agen) disetel ke `"strict-agentic"` untuk eksekusi keluarga GPT-5 OpenAI atau OpenAI Codex. Setel `true` untuk memaksa alat aktif di luar cakupan itu, atau `false` agar tetap nonaktif bahkan untuk eksekusi GPT-5 strict-agentic.
- Ketika diaktifkan, prompt sistem juga menambahkan panduan penggunaan agar model hanya menggunakannya untuk pekerjaan substansial dan mempertahankan paling banyak satu langkah `in_progress`.
### `agents.defaults.subagents`
@ -386,15 +386,15 @@ Flag alat bawaan eksperimental. Default nonaktif kecuali aturan aktif otomatis G
```
- `model`: model default untuk sub-agen yang dibuat. Jika dihilangkan, sub-agen mewarisi model pemanggil.
- `allowAgents`: allowlist default ID agen target untuk `sessions_spawn` ketika agen pemohon tidak menetapkan `subagents.allowAgents` miliknya sendiri (`["*"]` = apa pun; default: hanya agen yang sama).
- `allowAgents`: allowlist default ID agen target untuk `sessions_spawn` ketika agen peminta tidak menetapkan `subagents.allowAgents` miliknya sendiri (`["*"]` = apa pun; default: hanya agen yang sama).
- `runTimeoutSeconds`: timeout default (detik) untuk `sessions_spawn` ketika panggilan alat menghilangkan `runTimeoutSeconds`. `0` berarti tanpa timeout.
- Kebijakan alat per subagen: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`.
- Kebijakan alat per-subagen: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`.
---
## Penyedia kustom dan URL dasar
## Penyedia khusus dan URL dasar
OpenClaw menggunakan katalog model bawaan. Tambahkan penyedia kustom melalui `models.providers` dalam config atau `~/.openclaw/agents/<agentId>/agent/models.json`.
OpenClaw menggunakan katalog model bawaan. Tambahkan penyedia khusus melalui `models.providers` di konfigurasi atau `~/.openclaw/agents/<agentId>/agent/models.json`.
```json5
{
@ -424,19 +424,19 @@ OpenClaw menggunakan katalog model bawaan. Tambahkan penyedia kustom melalui `mo
```
<AccordionGroup>
<Accordion title="Prioritas auth dan merge">
- Gunakan `authHeader: true` + `headers` untuk kebutuhan auth kustom.
- Override root config agen dengan `OPENCLAW_AGENT_DIR` (atau `PI_CODING_AGENT_DIR`, alias variabel lingkungan legacy).
- Prioritas merge untuk ID penyedia yang cocok:
- Nilai `baseUrl` `models.json` agen yang tidak kosong menang.
- Nilai `apiKey` agen yang tidak kosong menang hanya ketika penyedia tersebut tidak dikelola SecretRef dalam konteks config/profil-auth saat ini.
- Nilai `apiKey` penyedia yang dikelola SecretRef disegarkan dari penanda sumber (`ENV_VAR_NAME` untuk ref env, `secretref-managed` untuk ref file/exec), alih-alih mempertahankan secret yang sudah di-resolve.
- Nilai header penyedia yang dikelola SecretRef disegarkan dari penanda sumber (`secretref-env:ENV_VAR_NAME` untuk ref env, `secretref-managed` untuk ref file/exec).
- `apiKey`/`baseUrl` agen yang kosong atau hilang fallback ke `models.providers` dalam 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 jika ada; gunakan ini untuk membatasi konteks efektif tanpa mengubah metadata model native.
- Gunakan `models.mode: "replace"` ketika Anda ingin config sepenuhnya menulis ulang `models.json`.
- Persistensi penanda bersifat otoritatif sumber: penanda ditulis dari snapshot config sumber aktif (pra-resolusi), bukan dari nilai secret runtime yang sudah di-resolve.
<Accordion title="Autentikasi dan prioritas penggabungan">
- Gunakan `authHeader: true` + `headers` untuk kebutuhan autentikasi khusus.
- Timpa root konfigurasi agen dengan `OPENCLAW_AGENT_DIR` (atau `PI_CODING_AGENT_DIR`, alias variabel lingkungan lama).
- Prioritas penggabungan untuk ID penyedia yang cocok:
- Nilai `baseUrl` `models.json` agen yang tidak kosong diutamakan.
- Nilai `apiKey` agen yang tidak kosong diutamakan hanya ketika penyedia tersebut tidak dikelola SecretRef dalam konteks konfigurasi/profil autentikasi saat ini.
- Nilai `apiKey` penyedia yang dikelola SecretRef disegarkan dari penanda sumber (`ENV_VAR_NAME` untuk referensi env, `secretref-managed` untuk referensi file/exec), bukan menyimpan rahasia yang sudah diresolusi.
- Nilai header penyedia yang dikelola SecretRef disegarkan dari penanda sumber (`secretref-env:ENV_VAR_NAME` untuk referensi env, `secretref-managed` untuk referensi file/exec).
- `apiKey`/`baseUrl` agen yang kosong atau tidak ada beralih ke `models.providers` dalam konfigurasi.
- `contextWindow`/`maxTokens` model yang cocok menggunakan nilai yang lebih tinggi antara konfigurasi eksplisit dan nilai katalog implisit.
- `contextTokens` model yang cocok mempertahankan batas runtime eksplisit ketika ada; gunakan ini untuk membatasi konteks efektif tanpa mengubah metadata model native.
- Gunakan `models.mode: "replace"` ketika Anda ingin konfigurasi menulis ulang `models.json` sepenuhnya.
- Persistensi penanda bersifat otoritatif terhadap sumber: penanda ditulis dari snapshot konfigurasi sumber aktif (pra-resolusi), bukan dari nilai rahasia runtime yang sudah diresolusi.
</Accordion>
</AccordionGroup>
@ -446,20 +446,20 @@ OpenClaw menggunakan katalog model bawaan. Tambahkan penyedia kustom melalui `mo
<AccordionGroup>
<Accordion title="Katalog tingkat atas">
- `models.mode`: perilaku katalog penyedia (`merge` atau `replace`).
- `models.providers`: peta penyedia kustom yang dikunci berdasarkan ID penyedia.
- Edit aman: gunakan `openclaw config set models.providers.<id> '<json>' --strict-json --merge` atau `openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge` untuk pembaruan aditif. `config set` menolak penggantian destruktif kecuali Anda meneruskan `--replace`.
- `models.providers`: peta penyedia khusus yang dikunci oleh ID penyedia.
- Pengeditan aman: gunakan `openclaw config set models.providers.<id> '<json>' --strict-json --merge` atau `openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge` untuk pembaruan aditif. `config set` menolak penggantian destruktif kecuali Anda meneruskan `--replace`.
</Accordion>
<Accordion title="Koneksi penyedia dan auth">
- `models.providers.*.api`: adaptor permintaan (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai`, dll). Untuk backend `/v1/chat/completions` yang di-host sendiri seperti MLX, vLLM, SGLang, dan sebagian besar server lokal yang kompatibel dengan OpenAI, gunakan `openai-completions`. Penyedia kustom dengan `baseUrl` tetapi tanpa `api` default ke `openai-completions`; atur `openai-responses` hanya ketika backend mendukung `/v1/responses`.
- `models.providers.*.apiKey`: kredensial penyedia (utamakan SecretRef/substitusi env).
- `models.providers.*.auth`: strategi auth (`api-key`, `token`, `oauth`, `aws-sdk`).
<Accordion title="Koneksi dan autentikasi penyedia">
- `models.providers.*.api`: adapter permintaan (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai`, dll). Untuk backend `/v1/chat/completions` self-hosted seperti MLX, vLLM, SGLang, dan sebagian besar server lokal kompatibel OpenAI, gunakan `openai-completions`. Penyedia khusus dengan `baseUrl` tetapi tanpa `api` bernilai default ke `openai-completions`; setel `openai-responses` hanya ketika backend mendukung `/v1/responses`.
- `models.providers.*.apiKey`: kredensial penyedia (utamakan substitusi SecretRef/env).
- `models.providers.*.auth`: strategi autentikasi (`api-key`, `token`, `oauth`, `aws-sdk`).
- `models.providers.*.contextWindow`: jendela konteks native default untuk model di bawah penyedia ini ketika entri model tidak menetapkan `contextWindow`.
- `models.providers.*.contextTokens`: batas konteks runtime efektif default untuk model di bawah penyedia ini ketika entri model tidak menetapkan `contextTokens`.
- `models.providers.*.maxTokens`: batas token output default untuk model di bawah penyedia ini ketika entri model tidak menetapkan `maxTokens`.
- `models.providers.*.timeoutSeconds`: timeout opsional per penyedia untuk permintaan HTTP model dalam detik, mencakup connect, header, body, dan penanganan pembatalan total permintaan.
- `models.providers.*.maxTokens`: batas token keluaran default untuk model di bawah penyedia ini ketika entri model tidak menetapkan `maxTokens`.
- `models.providers.*.timeoutSeconds`: timeout permintaan HTTP model per-penyedia opsional dalam detik, mencakup koneksi, header, body, dan penanganan pembatalan permintaan total.
- `models.providers.*.injectNumCtxForOpenAICompat`: untuk Ollama + `openai-completions`, injeksikan `options.num_ctx` ke permintaan (default: `true`).
- `models.providers.*.authHeader`: paksa transport kredensial di header `Authorization` ketika diperlukan.
- `models.providers.*.authHeader`: paksa transport kredensial dalam header `Authorization` ketika diperlukan.
- `models.providers.*.baseUrl`: URL dasar API upstream.
- `models.providers.*.headers`: header statis tambahan untuk routing proxy/tenant.
@ -468,40 +468,40 @@ OpenClaw menggunakan katalog model bawaan. Tambahkan penyedia kustom melalui `mo
`models.providers.*.request`: override transport untuk permintaan HTTP penyedia-model.
- `request.headers`: header tambahan (digabungkan dengan default penyedia). Nilai menerima SecretRef.
- `request.auth`: override strategi auth. Mode: `"provider-default"` (gunakan auth bawaan penyedia), `"authorization-bearer"` (dengan `token`), `"header"` (dengan `headerName`, `value`, `prefix` opsional).
- `request.auth`: override strategi autentikasi. Mode: `"provider-default"` (gunakan autentikasi bawaan penyedia), `"authorization-bearer"` (dengan `token`), `"header"` (dengan `headerName`, `value`, `prefix` opsional).
- `request.proxy`: override proxy HTTP. Mode: `"env-proxy"` (gunakan variabel env `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (dengan `url`). Kedua mode menerima sub-objek `tls` opsional.
- `request.tls`: override TLS untuk koneksi langsung. Bidang: `ca`, `cert`, `key`, `passphrase` (semua menerima SecretRef), `serverName`, `insecureSkipVerify`.
- `request.allowPrivateNetwork`: ketika `true`, izinkan HTTPS ke `baseUrl` ketika DNS di-resolve ke rentang privat, CGNAT, atau rentang serupa, melalui guard fetch HTTP penyedia (opt-in operator untuk endpoint yang di-host sendiri dan tepercaya yang kompatibel dengan OpenAI). URL stream penyedia-model loopback seperti `localhost`, `127.0.0.1`, dan `[::1]` diizinkan secara otomatis kecuali ini secara eksplisit diatur ke `false`; host LAN, tailnet, dan DNS privat tetap memerlukan opt-in. WebSocket menggunakan `request` yang sama untuk header/TLS tetapi bukan gate SSRF fetch tersebut. Default `false`.
- `request.tls`: override TLS untuk koneksi langsung. Bidang: `ca`, `cert`, `key`, `passphrase` (semuanya menerima SecretRef), `serverName`, `insecureSkipVerify`.
- `request.allowPrivateNetwork`: ketika `true`, izinkan HTTPS ke `baseUrl` ketika DNS diresolusi ke rentang privat, CGNAT, atau serupa, melalui pengaman fetch HTTP penyedia (opt-in operator untuk endpoint self-hosted tepercaya yang kompatibel OpenAI). URL stream penyedia model loopback seperti `localhost`, `127.0.0.1`, dan `[::1]` diizinkan otomatis kecuali ini secara eksplisit disetel ke `false`; host LAN, tailnet, dan DNS privat tetap memerlukan opt-in. WebSocket menggunakan `request` yang sama untuk header/TLS tetapi bukan gerbang SSRF fetch tersebut. Default `false`.
</Accordion>
<Accordion title="Entri katalog model">
- `models.providers.*.models`: entri katalog model penyedia eksplisit.
- `models.providers.*.models.*.input`: modalitas input model. Gunakan `["text"]` untuk model khusus teks dan `["text", "image"]` untuk model gambar/vision native. Lampiran gambar hanya diinjeksi ke giliran agen ketika model yang dipilih ditandai mampu gambar.
- `models.providers.*.models.*.contextWindow`: metadata jendela konteks model native. Ini meng-override `contextWindow` tingkat penyedia untuk model tersebut.
- `models.providers.*.models.*.contextTokens`: batas konteks runtime opsional. Ini meng-override `contextTokens` tingkat penyedia; gunakan ketika Anda menginginkan anggaran konteks efektif yang lebih kecil daripada `contextWindow` native model; `openclaw models list` menampilkan kedua nilai ketika berbeda.
- `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 OpenAI default.
- `models.providers.*.models.*.compat.requiresStringContent`: petunjuk kompatibilitas opsional untuk endpoint chat khusus string yang kompatibel dengan OpenAI. Ketika `true`, OpenClaw meratakan array `messages[].content` teks murni menjadi string biasa sebelum mengirim permintaan.
- `models.providers.*.models.*.input`: modalitas input model. Gunakan `["text"]` untuk model hanya teks dan `["text", "image"]` untuk model gambar/vision native. Lampiran gambar hanya diinjeksikan ke giliran agen ketika model yang dipilih ditandai mampu gambar.
- `models.providers.*.models.*.contextWindow`: metadata jendela konteks model native. Ini menimpa `contextWindow` tingkat penyedia untuk model tersebut.
- `models.providers.*.models.*.contextTokens`: batas konteks runtime opsional. Ini menimpa `contextTokens` tingkat penyedia; gunakan ketika Anda menginginkan anggaran konteks efektif yang lebih kecil daripada `contextWindow` native model; `openclaw models list` menampilkan kedua nilai ketika berbeda.
- `models.providers.*.models.*.compat.supportsDeveloperRole`: petunjuk kompatibilitas opsional. Untuk `api: "openai-completions"` dengan `baseUrl` non-native yang tidak kosong (host bukan `api.openai.com`), OpenClaw memaksa ini menjadi `false` saat runtime. `baseUrl` kosong/dihilangkan mempertahankan perilaku default OpenAI.
- `models.providers.*.models.*.compat.requiresStringContent`: petunjuk kompatibilitas opsional untuk endpoint chat kompatibel OpenAI yang hanya-string. Ketika `true`, OpenClaw meratakan array `messages[].content` teks murni menjadi string polos sebelum mengirim permintaan.
</Accordion>
<Accordion title="Penemuan Amazon Bedrock">
- `plugins.entries.amazon-bedrock.config.discovery`: root pengaturan penemuan otomatis Bedrock.
- `plugins.entries.amazon-bedrock.config.discovery.enabled`: aktifkan/nonaktifkan penemuan implisit.
- `plugins.entries.amazon-bedrock.config.discovery.enabled`: nyalakan/matikan penemuan implisit.
- `plugins.entries.amazon-bedrock.config.discovery.region`: region AWS untuk penemuan.
- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: filter ID penyedia opsional untuk penemuan tertarget.
- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: interval polling untuk penyegaran penemuan.
- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: jendela konteks fallback untuk model yang ditemukan.
- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: token output maksimum fallback untuk model yang ditemukan.
- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: token keluaran maksimum fallback untuk model yang ditemukan.
</Accordion>
</AccordionGroup>
Onboarding penyedia kustom interaktif menyimpulkan input gambar untuk ID model vision umum seperti GPT-4o, Claude, Gemini, Qwen-VL, LLaVA, Pixtral, InternVL, Mllama, MiniCPM-V, dan GLM-4V, serta melewati pertanyaan tambahan untuk keluarga khusus teks yang dikenal. ID model yang tidak dikenal tetap meminta dukungan gambar. Onboarding noninteraktif menggunakan inferensi yang sama; teruskan `--custom-image-input` untuk memaksa metadata mampu gambar atau `--custom-text-input` untuk memaksa metadata khusus teks.
Onboarding penyedia khusus interaktif menyimpulkan input gambar untuk ID model vision umum seperti GPT-4o, Claude, Gemini, Qwen-VL, LLaVA, Pixtral, InternVL, Mllama, MiniCPM-V, dan GLM-4V, serta melewati pertanyaan tambahan untuk keluarga yang diketahui hanya teks. ID model yang tidak dikenal tetap meminta dukungan gambar. Onboarding non-interaktif menggunakan inferensi yang sama; teruskan `--custom-image-input` untuk memaksa metadata mampu gambar atau `--custom-text-input` untuk memaksa metadata hanya teks.
### Contoh penyedia
<AccordionGroup>
<Accordion title="Cerebras (GLM 4.7 / GPT OSS)">
Plugin penyedia `cerebras` bawaan dapat mengonfigurasi ini melalui `openclaw onboard --auth-choice cerebras-api-key`. Gunakan config penyedia eksplisit hanya ketika meng-override default.
Plugin penyedia `cerebras` bawaan dapat mengonfigurasi ini melalui `openclaw onboard --auth-choice cerebras-api-key`. Gunakan konfigurasi penyedia eksplisit hanya ketika menimpa default.
```json5
{
@ -554,10 +554,10 @@ Onboarding penyedia kustom interaktif menyimpulkan input gambar untuk ID model v
Kompatibel dengan Anthropic, penyedia bawaan. Pintasan: `openclaw onboard --auth-choice kimi-code-api-key`.
</Accordion>
<Accordion title="Model lokal (LM Studio)">
Lihat [Model Lokal](/id/gateway/local-models). Ringkasnya: jalankan model lokal besar melalui LM Studio Responses API pada perangkat keras yang serius; biarkan model terhosting tetap digabungkan sebagai fallback.
<Accordion title="Local models (LM Studio)">
Lihat [Model Lokal](/id/gateway/local-models). Ringkasnya: jalankan model lokal besar melalui LM Studio Responses API pada perangkat keras yang serius; biarkan model hosted tetap digabungkan sebagai fallback.
</Accordion>
<Accordion title="MiniMax M2.7 (langsung)">
<Accordion title="MiniMax M2.7 (direct)">
```json5
{
agents: {
@ -592,7 +592,7 @@ Onboarding penyedia kustom interaktif menyimpulkan input gambar untuk ID model v
}
```
Tetapkan `MINIMAX_API_KEY`. Pintasan: `openclaw onboard --auth-choice minimax-global-api` atau `openclaw onboard --auth-choice minimax-cn-api`. Katalog model secara default hanya menggunakan M2.7. Pada jalur streaming yang kompatibel dengan Anthropic, OpenClaw menonaktifkan pemikiran MiniMax secara default kecuali Anda menetapkan `thinking` sendiri secara eksplisit. `/fast on` atau `params.fastMode: true` menulis ulang `MiniMax-M2.7` menjadi `MiniMax-M2.7-highspeed`.
Tetapkan `MINIMAX_API_KEY`. Pintasan: `openclaw onboard --auth-choice minimax-global-api` atau `openclaw onboard --auth-choice minimax-cn-api`. Katalog model secara default hanya menggunakan M2.7. Pada jalur streaming yang kompatibel dengan Anthropic, OpenClaw menonaktifkan penalaran MiniMax secara default kecuali Anda menetapkan `thinking` sendiri secara eksplisit. `/fast on` atau `params.fastMode: true` menulis ulang `MiniMax-M2.7` menjadi `MiniMax-M2.7-highspeed`.
</Accordion>
<Accordion title="Moonshot AI (Kimi)">
@ -631,7 +631,7 @@ Onboarding penyedia kustom interaktif menyimpulkan input gambar untuk ID model v
Untuk endpoint Tiongkok: `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 menentukannya berdasarkan kemampuan endpoint, bukan hanya id penyedia bawaan.
Endpoint Moonshot native mengiklankan kompatibilitas penggunaan streaming pada transport bersama `openai-completions`, dan OpenClaw menentukannya dari kapabilitas endpoint, bukan hanya dari id penyedia bawaan.
</Accordion>
<Accordion title="OpenCode">
@ -646,10 +646,10 @@ Onboarding penyedia kustom interaktif menyimpulkan input gambar untuk ID model v
}
```
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`.
Tetapkan `OPENCODE_API_KEY` (atau `OPENCODE_ZEN_API_KEY`). Gunakan ref `opencode/...` untuk katalog Zen atau ref `opencode-go/...` untuk katalog Go. Pintasan: `openclaw onboard --auth-choice opencode-zen` atau `openclaw onboard --auth-choice opencode-go`.
</Accordion>
<Accordion title="Synthetic (kompatibel dengan Anthropic)">
<Accordion title="Synthetic (Anthropic-compatible)">
```json5
{
env: { SYNTHETIC_API_KEY: "sk-..." },
@ -712,6 +712,6 @@ Onboarding penyedia kustom interaktif menyimpulkan input gambar untuk ID model v
## Terkait
- [Konfigurasi — agen](/id/gateway/config-agents)
- [Konfigurasi — saluran](/id/gateway/config-channels)
- [Konfigurasi — channel](/id/gateway/config-channels)
- [Referensi konfigurasi](/id/gateway/configuration-reference) — kunci tingkat atas lainnya
- [Alat dan plugin](/id/tools)

544
docs/id/gateway/configuration-reference.md
View File

@ -1,73 +1,73 @@
---
read_when:
- Anda memerlukan semantik konfigurasi tingkat bidang atau nilai default yang tepat
- Anda sedang memvalidasi blok konfigurasi kanal, model, Gateway, atau alat
summary: Referensi konfigurasi Gateway untuk kunci inti OpenClaw, nilai bawaan, dan tautan ke referensi subsistem khusus
- Anda sedang memvalidasi blok konfigurasi saluran, model, Gateway, atau alat
summary: Referensi konfigurasi Gateway untuk kunci inti OpenClaw, nilai default, dan tautan ke referensi subsistem khusus
title: Referensi konfigurasi
x-i18n:
generated_at: "2026-05-03T21:31:45Z"
generated_at: "2026-05-05T01:45:54Z"
model: gpt-5.5
provider: openai
source_hash: 52fa15e85a41ed5ed39102fb641bd33f0aec2e8f244c9d7b3d12b3a1b6dc62a9
source_hash: 82164a3ea7592f667573b643ee9e0ec840b9b622c9d86c382a3feaf192e75684
source_path: gateway/configuration-reference.md
workflow: 16
---
Referensi konfigurasi inti untuk `~/.openclaw/openclaw.json`. Untuk ikhtisar berorientasi tugas, lihat [Konfigurasi](/id/gateway/configuration).
Mencakup permukaan konfigurasi utama OpenClaw dan menautkan ke luar saat suatu subsistem memiliki referensi yang lebih mendalam. Katalog perintah milik channel dan plugin serta pengaturan mendalam memory/QMD berada di halaman masing-masing, bukan di halaman ini.
Mencakup permukaan konfigurasi utama OpenClaw dan menautkan keluar ketika sebuah subsistem memiliki referensi yang lebih mendalam sendiri. Katalog perintah milik saluran dan Plugin serta kenop memori mendalam/QMD berada di halaman masing-masing, bukan di halaman ini.
Kebenaran kode:
Sumber kebenaran kode:
- `openclaw config schema` mencetak JSON Schema langsung yang digunakan untuk validasi dan Control UI, dengan metadata bawaan/plugin/channel digabungkan saat tersedia
- `config.schema.lookup` mengembalikan satu node skema berbasis path untuk tooling drill-down
- `openclaw config schema` mencetak JSON Schema langsung yang digunakan untuk validasi dan Control UI, dengan metadata bawaan/Plugin/saluran digabungkan saat tersedia
- `config.schema.lookup` mengembalikan satu node skema berlingkup jalur untuk alat penelusuran mendalam
- `pnpm config:docs:check` / `pnpm config:docs:gen` memvalidasi hash baseline dokumen konfigurasi terhadap permukaan skema saat ini
Jalur pencarian agen: gunakan aksi tool `gateway` `config.schema.lookup` untuk
dokumentasi dan batasan tingkat bidang yang tepat sebelum pengeditan. Gunakan
Jalur pencarian agen: gunakan aksi alat `gateway` `config.schema.lookup` untuk
dokumentasi dan batasan tingkat bidang yang tepat sebelum mengedit. Gunakan
[Konfigurasi](/id/gateway/configuration) untuk panduan berorientasi tugas dan halaman ini
untuk peta bidang yang lebih luas, nilai default, dan tautan ke referensi subsistem.
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 + terbundel saat ini
- halaman channel/plugin pemilik untuk permukaan perintah khusus channel
- [Referensi konfigurasi memori](/id/reference/memory-config) untuk `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations`, dan konfigurasi dreaming di bawah `plugins.entries.memory-core.config.dreaming`
- [Perintah slash](/id/tools/slash-commands) untuk katalog perintah bawaan + paket saat ini
- halaman saluran/Plugin pemilik untuk permukaan perintah khusus saluran
Format konfigurasi adalah **JSON5** (komentar + koma akhir diizinkan). Semua bidang bersifat opsional — OpenClaw menggunakan default aman saat dihilangkan.
Format konfigurasi adalah **JSON5** (komentar + koma akhir diizinkan). Semua bidang bersifat opsional — OpenClaw menggunakan nilai default yang aman saat dihilangkan.
---
## Channel
## Saluran
Kunci konfigurasi per channel dipindahkan ke halaman khusus — lihat
[Konfigurasi — channel](/id/gateway/config-channels) untuk `channels.*`,
termasuk Slack, Discord, Telegram, WhatsApp, Matrix, iMessage, dan channel
terbundel lainnya (auth, kontrol akses, multi-akun, gating mention).
Kunci konfigurasi per saluran dipindahkan ke halaman khusus — lihat
[Konfigurasi — saluran](/id/gateway/config-channels) untuk `channels.*`,
termasuk Slack, Discord, Telegram, WhatsApp, Matrix, iMessage, dan saluran
paket lainnya (autentikasi, kontrol akses, multi-akun, gating sebutan).
## Default agen, multi-agen, sesi, dan pesan
Dipindahkan ke halaman khusus — lihat
[Konfigurasi — agen](/id/gateway/config-agents) untuk:
- `agents.defaults.*` (workspace, model, thinking, Heartbeat, memory, media, Skills, sandbox)
- `multiAgent.*` (routing dan binding multi-agen)
- `session.*` (siklus hidup sesi, Compaction, pruning)
- `agents.defaults.*` (workspace, model, pemikiran, Heartbeat, memori, media, Skills, sandbox)
- `multiAgent.*` (perutean dan binding multi-agen)
- `session.*` (siklus hidup sesi, Compaction, pemangkasan)
- `messages.*` (pengiriman pesan, TTS, rendering markdown)
- `talk.*` (mode Talk)
- `talk.speechLocale`: id lokal BCP 47 opsional untuk pengenalan ucapan Talk di iOS/macOS
- `talk.silenceTimeoutMs`: saat tidak diatur, Talk mempertahankan jendela jeda default platform sebelum mengirim transkrip (`700 ms on macOS and Android, 900 ms on iOS`)
- `talk.silenceTimeoutMs`: saat tidak disetel, Talk mempertahankan jendela jeda default platform sebelum mengirim transkrip (`700 ms on macOS and Android, 900 ms on iOS`)
## Tool dan penyedia kustom
## Alat dan penyedia khusus
Kebijakan tool, toggle eksperimental, konfigurasi tool yang didukung penyedia, dan penyiapan
penyedia kustom / URL dasar dipindahkan ke halaman khusus — lihat
[Konfigurasi — tool dan penyedia kustom](/id/gateway/config-tools).
Kebijakan alat, toggle eksperimental, konfigurasi alat yang didukung penyedia, dan penyiapan
penyedia khusus / URL dasar dipindahkan ke halaman khusus — lihat
[Konfigurasi — alat dan penyedia khusus](/id/gateway/config-tools).
## Model
Definisi penyedia, allowlist model, dan penyiapan penyedia kustom berada di
[Konfigurasi — tool dan penyedia kustom](/id/gateway/config-tools#custom-providers-and-base-urls).
Definisi penyedia, allowlist model, dan penyiapan penyedia khusus berada di
[Konfigurasi — alat dan penyedia khusus](/id/gateway/config-tools#custom-providers-and-base-urls).
Root `models` juga memiliki perilaku katalog model global.
```json5
@ -80,16 +80,16 @@ Root `models` juga memiliki perilaku katalog model global.
```
- `models.mode`: perilaku katalog penyedia (`merge` atau `replace`).
- `models.providers`: peta penyedia kustom yang dikunci berdasarkan id penyedia.
- `models.providers`: peta penyedia khusus yang dikunci berdasarkan id penyedia.
- `models.pricing.enabled`: mengontrol bootstrap harga latar belakang yang
dimulai setelah sidecar dan channel mencapai jalur siap Gateway. Saat `false`,
dimulai setelah sidecar dan saluran mencapai jalur siap Gateway. Saat `false`,
Gateway melewati pengambilan katalog harga OpenRouter dan LiteLLM; nilai
`models.providers.*.models[].cost` yang dikonfigurasi tetap berfungsi untuk estimasi biaya lokal.
## MCP
Definisi server MCP yang dikelola OpenClaw berada di bawah `mcp.servers` dan
digunakan oleh Pi tertanam serta adapter runtime lainnya. Perintah `openclaw mcp list`,
digunakan oleh Pi tertanam serta adaptor runtime lainnya. Perintah `openclaw mcp list`,
`show`, `set`, dan `unset` mengelola blok ini tanpa terhubung ke
server target selama pengeditan konfigurasi.
@ -116,16 +116,16 @@ server target selama pengeditan konfigurasi.
```
- `mcp.servers`: definisi server MCP stdio atau jarak jauh bernama untuk runtime yang
mengekspos tool MCP yang dikonfigurasi.
mengekspos alat MCP yang dikonfigurasi.
Entri jarak jauh menggunakan `transport: "streamable-http"` atau `transport: "sse"`;
`type: "http"` adalah alias native CLI yang dinormalisasi oleh `openclaw mcp set` dan
`openclaw doctor --fix` ke dalam bidang kanonis `transport`.
- `mcp.sessionIdleTtlMs`: TTL idle untuk runtime MCP terbundel berbasis sesi.
Eksekusi tertanam sekali jalan meminta pembersihan akhir eksekusi; TTL ini adalah cadangan untuk
- `mcp.sessionIdleTtlMs`: TTL idle untuk runtime MCP paket yang berlingkup sesi.
Eksekusi tertanam satu kali meminta pembersihan akhir eksekusi; TTL ini adalah pengaman untuk
sesi berumur panjang dan pemanggil masa depan.
- Perubahan di bawah `mcp.*` diterapkan panas dengan membuang runtime MCP sesi yang di-cache.
Penemuan/penggunaan tool berikutnya membuat ulangnya dari konfigurasi baru, sehingga entri
`mcp.servers` yang dihapus dipanen segera alih-alih menunggu TTL idle.
Penemuan/penggunaan alat berikutnya membuatnya ulang dari konfigurasi baru, sehingga entri
`mcp.servers` yang dihapus dibereskan segera alih-alih menunggu TTL idle.
Lihat [MCP](/id/cli/mcp#openclaw-as-an-mcp-client-registry) dan
[Backend CLI](/id/gateway/cli-backends#bundle-mcp-overlays) untuk perilaku runtime.
@ -155,24 +155,25 @@ Lihat [MCP](/id/cli/mcp#openclaw-as-an-mcp-client-registry) dan
}
```
- `allowBundled`: allowlist opsional hanya untuk Skills terbundel (Skills terkelola/workspace tidak terpengaruh).
- `allowBundled`: allowlist opsional hanya untuk Skills paket (Skills terkelola/workspace tidak terpengaruh).
- `load.extraDirs`: root skill bersama tambahan (presedensi terendah).
- `install.preferBrew`: saat true, utamakan installer Homebrew ketika `brew` tersedia
- `install.preferBrew`: saat true, prioritaskan installer Homebrew saat `brew` tersedia
sebelum fallback ke jenis installer lain.
- `install.nodeManager`: preferensi installer node untuk spesifikasi `metadata.openclaw.install`
- `install.nodeManager`: preferensi installer Node untuk spesifikasi `metadata.openclaw.install`
(`npm` | `pnpm` | `yarn` | `bun`).
- `entries.<skillKey>.enabled: false` menonaktifkan skill meski terbundel/terinstal.
- `entries.<skillKey>.apiKey`: kemudahan untuk Skills yang mendeklarasikan env var utama (string plaintext atau objek SecretRef).
- `entries.<skillKey>.enabled: false` menonaktifkan skill meskipun dibundel/diinstal.
- `entries.<skillKey>.apiKey`: kemudahan untuk Skills yang mendeklarasikan variabel env utama (string plaintext atau objek SecretRef).
---
## Plugin
## Plugins
```json5
{
plugins: {
enabled: true,
allow: ["voice-call"],
bundledDiscovery: "allowlist",
deny: [],
load: {
paths: ["~/Projects/oss/voice-call-plugin"],
@ -190,54 +191,58 @@ Lihat [MCP](/id/cli/mcp#openclaw-as-an-mcp-client-registry) dan
}
```
- Dimuat dari `~/.openclaw/extensions`, `<workspace>/.openclaw/extensions`, plus `plugins.load.paths`.
- Discovery menerima Plugin native OpenClaw serta bundle Codex yang kompatibel dan bundle Claude, termasuk bundle tata letak default Claude tanpa manifest.
- **Perubahan konfigurasi memerlukan restart gateway.**
- `allow`: allowlist opsional (hanya Plugin yang terdaftar yang dimuat). `deny` menang.
- Dimuat dari `~/.openclaw/extensions`, `<workspace>/.openclaw/extensions`, ditambah `plugins.load.paths`.
- Penemuan menerima Plugin OpenClaw native serta bundle Codex dan bundle Claude yang kompatibel, termasuk bundle tata letak default Claude tanpa manifest.
- **Perubahan konfigurasi memerlukan restart Gateway.**
- `allow`: allowlist opsional (hanya Plugin yang terdaftar dimuat). `deny` menang.
- `bundledDiscovery`: default ke `"allowlist"` untuk konfigurasi baru, sehingga `plugins.allow`
yang tidak kosong juga membatasi Plugin penyedia paket, termasuk penyedia runtime
web-search. Doctor menulis `"compat"` untuk konfigurasi allowlist lama yang dimigrasikan
untuk mempertahankan perilaku penyedia paket yang ada sampai Anda memilih ikut serta.
- `plugins.entries.<id>.apiKey`: bidang kemudahan kunci API tingkat Plugin (saat didukung oleh Plugin).
- `plugins.entries.<id>.env`: peta env var berskopa Plugin.
- `plugins.entries.<id>.hooks.allowPromptInjection`: saat `false`, core memblokir `before_prompt_build` dan mengabaikan bidang yang memutasi prompt dari `before_agent_start` legacy, sambil mempertahankan `modelOverride` dan `providerOverride` legacy. Berlaku untuk hook Plugin native dan direktori hook yang disediakan bundle yang didukung.
- `plugins.entries.<id>.hooks.allowConversationAccess`: saat `true`, Plugin non-terbundel tepercaya dapat membaca konten percakapan mentah dari hook bertipe seperti `llm_input`, `llm_output`, `before_agent_finalize`, dan `agent_end`.
- `plugins.entries.<id>.env`: peta variabel env berlingkup Plugin.
- `plugins.entries.<id>.hooks.allowPromptInjection`: saat `false`, core memblokir `before_prompt_build` dan mengabaikan bidang pengubah prompt dari `before_agent_start` lama, sambil mempertahankan `modelOverride` dan `providerOverride` lama. Berlaku untuk hook Plugin native dan direktori hook yang disediakan bundle dan didukung.
- `plugins.entries.<id>.hooks.allowConversationAccess`: saat `true`, Plugin non-paket tepercaya dapat membaca konten percakapan mentah dari hook bertipe seperti `llm_input`, `llm_output`, `before_agent_finalize`, dan `agent_end`.
- `plugins.entries.<id>.subagent.allowModelOverride`: percayai Plugin ini secara eksplisit untuk meminta override `provider` dan `model` per eksekusi untuk eksekusi subagen latar belakang.
- `plugins.entries.<id>.subagent.allowedModels`: allowlist opsional target `provider/model` kanonis untuk override subagen tepercaya. Gunakan `"*"` hanya saat Anda memang ingin mengizinkan model apa pun.
- `plugins.entries.<id>.config`: objek konfigurasi yang ditentukan Plugin (divalidasi oleh skema Plugin native OpenClaw saat tersedia).
- Pengaturan akun/runtime Plugin channel berada di bawah `channels.<id>` dan harus dijelaskan oleh metadata `channelConfigs` manifest Plugin pemilik, bukan oleh registry opsi OpenClaw pusat.
- `plugins.entries.<id>.subagent.allowedModels`: allowlist opsional target `provider/model` kanonis untuk override subagen tepercaya. Gunakan `"*"` hanya ketika Anda sengaja ingin mengizinkan model apa pun.
- `plugins.entries.<id>.config`: objek konfigurasi yang didefinisikan Plugin (divalidasi oleh skema Plugin OpenClaw native saat tersedia).
- Pengaturan akun/runtime Plugin saluran berada di bawah `channels.<id>` dan harus dideskripsikan oleh metadata `channelConfigs` manifest Plugin pemilik, bukan oleh registry opsi OpenClaw pusat.
- `plugins.entries.firecrawl.config.webFetch`: pengaturan penyedia web-fetch Firecrawl.
- `apiKey`: kunci API Firecrawl (menerima SecretRef). Fallback ke `plugins.entries.firecrawl.config.webSearch.apiKey`, `tools.web.fetch.firecrawl.apiKey` legacy, atau env var `FIRECRAWL_API_KEY`.
- `apiKey`: kunci API Firecrawl (menerima SecretRef). Fallback ke `plugins.entries.firecrawl.config.webSearch.apiKey`, `tools.web.fetch.firecrawl.apiKey` lama, atau variabel env `FIRECRAWL_API_KEY`.
- `baseUrl`: URL dasar API Firecrawl (default: `https://api.firecrawl.dev`; override self-hosted harus menargetkan endpoint privat/internal).
- `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`).
- `maxAgeMs`: umur cache maksimum dalam milidetik (default: `172800000` / 2 hari).
- `timeoutSeconds`: batas waktu permintaan scrape dalam detik (default: `60`).
- `plugins.entries.xai.config.xSearch`: pengaturan xAI X Search (pencarian web Grok).
- `enabled`: aktifkan penyedia 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`: irama Cron untuk setiap sweep Dreaming penuh (`"0 3 * * *"` secara default).
- `model`: override model subagen Dream Diary opsional. Memerlukan `plugins.entries.memory-core.subagent.allowModelOverride: true`; pasangkan dengan `allowedModels` untuk membatasi target. Error model tidak tersedia dicoba ulang sekali dengan model default sesi; kegagalan trust atau allowlist tidak fallback secara diam-diam.
- kebijakan fase dan threshold adalah detail implementasi (bukan kunci konfigurasi yang menghadap pengguna).
- Konfigurasi memory penuh berada di [Referensi konfigurasi memory](/id/reference/memory-config):
- `plugins.entries.memory-core.config.dreaming`: pengaturan memory dreaming. Lihat [Dreaming](/id/concepts/dreaming) untuk fase dan ambang.
- `enabled`: sakelar utama dreaming (default `false`).
- `frequency`: irama Cron untuk setiap sweep dreaming penuh (`"0 3 * * *"` secara default).
- `model`: override model subagen Dream Diary opsional. Memerlukan `plugins.entries.memory-core.subagent.allowModelOverride: true`; pasangkan dengan `allowedModels` untuk membatasi target. Error model-tidak-tersedia mencoba ulang satu kali dengan model default sesi; kegagalan kepercayaan atau allowlist tidak fallback secara diam-diam.
- kebijakan fase dan ambang adalah detail implementasi (bukan kunci konfigurasi yang ditampilkan ke pengguna).
- Konfigurasi memori lengkap berada di [Referensi konfigurasi memori](/id/reference/memory-config):
- `agents.defaults.memorySearch.*`
- `memory.backend`
- `memory.citations`
- `memory.qmd.*`
- `plugins.entries.memory-core.config.dreaming`
- Plugin bundle Claude yang diaktifkan juga dapat menyumbangkan default Pi tertanam dari `settings.json`; OpenClaw menerapkannya sebagai pengaturan agen yang disanitasi, bukan sebagai patch konfigurasi 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.slots.memory`: pilih id Plugin memori aktif, atau `"none"` untuk menonaktifkan Plugin memori.
- `plugins.slots.contextEngine`: pilih id Plugin mesin konteks aktif; default ke `"legacy"` kecuali Anda menginstal dan memilih mesin lain.
Lihat [Plugin](/id/tools/plugin).
Lihat [Plugins](/id/tools/plugin).
---
## Komitmen
`commitments` mengontrol memory tindak lanjut yang diinferensikan: OpenClaw dapat mendeteksi check-in dari giliran percakapan dan mengirimkannya melalui eksekusi Heartbeat.
`commitments` mengontrol memori tindak lanjut yang disimpulkan: OpenClaw dapat mendeteksi check-in dari giliran percakapan dan mengirimkannya melalui eksekusi Heartbeat.
- `commitments.enabled`: aktifkan ekstraksi LLM tersembunyi, penyimpanan, dan pengiriman Heartbeat untuk komitmen tindak lanjut yang diinferensikan. Default: `false`.
- `commitments.maxPerDay`: jumlah maksimum komitmen tindak lanjut yang diinferensikan yang dikirim per sesi agen dalam hari bergulir. Default: `3`.
- `commitments.enabled`: aktifkan ekstraksi LLM tersembunyi, penyimpanan, dan pengiriman Heartbeat untuk komitmen tindak lanjut yang disimpulkan. Default: `false`.
- `commitments.maxPerDay`: jumlah maksimum komitmen tindak lanjut yang disimpulkan yang dikirim per sesi agen dalam satu hari bergulir. Default: `3`.
Lihat [Komitmen yang diinferensikan](/id/concepts/commitments).
Lihat [Komitmen yang disimpulkan](/id/concepts/commitments).
---
@ -288,42 +293,44 @@ Lihat [Komitmen yang diinferensikan](/id/concepts/commitments).
```
- `evaluateEnabled: false` menonaktifkan `act:evaluate` dan `wait --fn`.
- `tabCleanup` mengklaim kembali tab agen utama yang dilacak setelah waktu tidak aktif atau ketika sebuah sesi melebihi batasnya. Tetapkan `idleMinutes: 0` atau `maxTabsPerSession: 0` untuk menonaktifkan mode pembersihan individual tersebut.
- `ssrfPolicy.dangerouslyAllowPrivateNetwork` dinonaktifkan saat tidak ditetapkan, sehingga navigasi browser tetap ketat secara default.
- Tetapkan `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` hanya saat Anda secara sengaja memercayai navigasi browser jaringan privat.
- `tabCleanup` mengambil kembali tab agen utama yang dilacak setelah waktu menganggur atau saat suatu
sesi melampaui batasnya. Atur `idleMinutes: 0` atau `maxTabsPerSession: 0` untuk
menonaktifkan mode pembersihan individual tersebut.
- `ssrfPolicy.dangerouslyAllowPrivateNetwork` dinonaktifkan saat tidak disetel, sehingga navigasi browser tetap ketat secara default.
- Setel `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` hanya saat Anda sengaja memercayai navigasi browser jaringan privat.
- Dalam mode ketat, endpoint profil CDP jarak jauh (`profiles.*.cdpUrl`) tunduk pada pemblokiran jaringan privat yang sama selama pemeriksaan keterjangkauan/penemuan.
- `ssrfPolicy.allowPrivateNetwork` tetap didukung sebagai alias lama.
- Dalam mode ketat, gunakan `ssrfPolicy.hostnameAllowlist` dan `ssrfPolicy.allowedHostnames` untuk pengecualian eksplisit.
- Profil jarak jauh bersifat attach-only (mulai/berhenti/reset dinonaktifkan).
- Profil jarak jauh hanya-attach (mulai/hentikan/reset dinonaktifkan).
- `profiles.*.cdpUrl` menerima `http://`, `https://`, `ws://`, dan `wss://`.
Gunakan HTTP(S) saat Anda ingin OpenClaw menemukan `/json/version`; gunakan WS(S)
saat penyedia Anda memberi URL WebSocket DevTools langsung.
saat penyedia Anda memberi Anda URL WebSocket DevTools langsung.
- `remoteCdpTimeoutMs` dan `remoteCdpHandshakeTimeoutMs` berlaku untuk keterjangkauan CDP jarak jauh dan
`attachOnly` serta permintaan pembukaan tab. Profil loopback terkelola
mempertahankan default CDP lokal.
- Jika layanan CDP yang dikelola secara eksternal dapat dijangkau melalui loopback, tetapkan
`attachOnly` beserta permintaan pembukaan tab. Profil local loopback
terkelola mempertahankan default CDP lokal.
- Jika layanan CDP yang dikelola secara eksternal dapat dijangkau melalui loopback, setel
`attachOnly: true` profil tersebut; jika tidak, OpenClaw memperlakukan port loopback sebagai
profil browser lokal terkelola dan dapat melaporkan kesalahan kepemilikan port lokal.
- Profil `existing-session` menggunakan Chrome MCP alih-alih CDP dan dapat terhubung pada
- Profil `existing-session` menggunakan Chrome MCP alih-alih CDP dan dapat attach pada
host yang dipilih atau melalui node browser yang terhubung.
- Profil `existing-session` dapat menetapkan `userDataDir` untuk menargetkan profil
browser berbasis Chromium tertentu seperti Brave atau Edge.
- Profil `existing-session` dapat menyetel `userDataDir` untuk menargetkan
profil browser berbasis Chromium tertentu seperti Brave atau Edge.
- Profil `existing-session` mempertahankan batas rute Chrome MCP saat ini:
tindakan berbasis snapshot/ref alih-alih penargetan selector CSS, hook unggah satu file,
tanpa override timeout dialog, tanpa `wait --load networkidle`, dan tanpa
tanpa override batas waktu dialog, tanpa `wait --load networkidle`, dan tanpa
`responsebody`, ekspor PDF, intersepsi unduhan, atau tindakan batch.
- Profil `openclaw` lokal terkelola menetapkan `cdpPort` dan `cdpUrl` secara otomatis; hanya
tetapkan `cdpUrl` secara eksplisit untuk CDP jarak jauh.
- Profil lokal terkelola dapat menetapkan `executablePath` untuk mengganti
`browser.executablePath` global untuk profil tersebut. Gunakan ini untuk menjalankan satu profil di
- Profil `openclaw` lokal terkelola menetapkan otomatis `cdpPort` dan `cdpUrl`; hanya
setel `cdpUrl` secara eksplisit untuk CDP jarak jauh.
- Profil lokal terkelola dapat menyetel `executablePath` untuk menimpa
`browser.executablePath` global bagi profil tersebut. Gunakan ini untuk menjalankan satu profil di
Chrome dan profil lain di Brave.
- Profil lokal terkelola menggunakan `browser.localLaunchTimeoutMs` untuk penemuan HTTP CDP Chrome
setelah proses dimulai dan `browser.localCdpReadyTimeoutMs` untuk
kesiapan websocket CDP setelah peluncuran. Naikkan nilainya pada host yang lebih lambat ketika Chrome
kesiapan websocket CDP pascapeluncuran. Naikkan nilainya pada host yang lebih lambat tempat Chrome
berhasil dimulai tetapi pemeriksaan kesiapan berpacu dengan startup. Kedua nilai harus berupa
bilangan bulat positif hingga `120000` ms; nilai config yang tidak valid ditolak.
bilangan bulat positif hingga `120000` md; nilai konfigurasi yang tidak valid akan ditolak.
- Urutan deteksi otomatis: browser default jika berbasis Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary.
- `browser.executablePath` dan `browser.profiles.<name>.executablePath` sama-sama
- `browser.executablePath` dan `browser.profiles.<name>.executablePath` keduanya
menerima `~` dan `~/...` untuk direktori home OS Anda sebelum peluncuran Chromium.
`userDataDir` per profil pada profil `existing-session` juga diperluas dari tilde.
- Layanan kontrol: hanya loopback (port diturunkan dari `gateway.port`, default `18791`).
@ -346,8 +353,8 @@ Lihat [Komitmen yang diinferensikan](/id/concepts/commitments).
}
```
- `seamColor`: warna aksen untuk chrome UI aplikasi native (warna gelembung Talk Mode, dll.).
- `assistant`: override identitas Control UI. Kembali ke identitas agen aktif.
- `seamColor`: warna aksen untuk chrome UI aplikasi native (rona gelembung Mode Bicara, dll.).
- `assistant`: override identitas UI Kontrol. Kembali ke identitas agen aktif.
---
@ -423,59 +430,60 @@ Lihat [Komitmen yang diinferensikan](/id/concepts/commitments).
}
```
<Accordion title="Gateway field details">
<Accordion title="Detail bidang Gateway">
- `mode`: `local` (menjalankan gateway) atau `remote` (terhubung ke gateway jarak jauh). Gateway menolak untuk berjalan kecuali `local`.
- `port`: port tunggal termultipleks untuk WS + HTTP. Prioritas: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`.
- `mode`: `local` (jalankan Gateway) atau `remote` (terhubung ke Gateway jarak jauh). Gateway menolak untuk dimulai kecuali `local`.
- `port`: port termultipleks tunggal untuk WS + HTTP. Prioritas: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`.
- `bind`: `auto`, `loopback` (default), `lan` (`0.0.0.0`), `tailnet` (hanya IP Tailscale), atau `custom`.
- **Alias bind legacy**: gunakan nilai mode bind di `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), bukan alias host (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`).
- **Catatan Docker**: bind `loopback` default mendengarkan pada `127.0.0.1` di dalam kontainer. Dengan jaringan bridge Docker (`-p 18789:18789`), lalu lintas masuk melalui `eth0`, sehingga gateway tidak dapat dijangkau. Gunakan `--network host`, atau tetapkan `bind: "lan"` (atau `bind: "custom"` dengan `customBindHost: "0.0.0.0"`) untuk mendengarkan pada semua antarmuka.
- **Auth**: wajib secara default. Bind non-loopback memerlukan auth gateway. Dalam praktiknya, ini berarti token/kata sandi bersama atau reverse proxy sadar-identitas dengan `gateway.auth.mode: "trusted-proxy"`. Wizard onboarding menghasilkan token secara default.
- Jika `gateway.auth.token` dan `gateway.auth.password` sama-sama dikonfigurasi (termasuk SecretRefs), tetapkan `gateway.auth.mode` secara eksplisit ke `token` atau `password`. Alur startup dan instalasi/perbaikan layanan gagal ketika keduanya dikonfigurasi dan mode belum ditetapkan.
- `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 browser/pengguna ke reverse proxy sadar-identitas dan percayai header identitas dari `gateway.trustedProxies` (lihat [Auth Proxy Tepercaya](/id/gateway/trusted-proxy-auth)). Mode ini mengharapkan sumber proxy **non-loopback** secara default; reverse proxy loopback pada host yang sama memerlukan `gateway.auth.trustedProxy.allowLoopback = true` secara eksplisit. Pemanggil internal pada host yang sama dapat menggunakan `gateway.auth.password` sebagai fallback langsung lokal; `gateway.auth.token` tetap saling eksklusif dengan mode trusted-proxy.
- `gateway.auth.allowTailscale`: ketika `true`, header identitas Tailscale Serve dapat memenuhi auth Control UI/WebSocket (diverifikasi melalui `tailscale whois`). Endpoint HTTP API **tidak** menggunakan auth header Tailscale tersebut; endpoint mengikuti mode auth HTTP normal gateway. Alur tanpa token ini mengasumsikan host gateway tepercaya. Default ke `true` ketika `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 terpisah). Percobaan yang diblokir mengembalikan `429` + `Retry-After`.
- Pada jalur async Tailscale Serve Control UI, percobaan gagal untuk `{scope, clientIp}` yang sama diserialkan sebelum penulisan kegagalan. Karena itu, percobaan buruk serentak dari klien yang sama dapat memicu pembatas pada permintaan kedua alih-alih keduanya berpacu sebagai ketidakcocokan biasa.
- `gateway.auth.rateLimit.exemptLoopback` default ke `true`; tetapkan `false` ketika Anda sengaja ingin lalu lintas localhost juga dibatasi lajunya (untuk penyiapan pengujian atau deployment proxy ketat).
- Percobaan auth WS dari origin browser selalu dibatasi dengan pengecualian loopback dinonaktifkan (pertahanan berlapis terhadap brute force localhost berbasis browser).
- Pada loopback, lockout dari origin browser tersebut diisolasi per nilai `Origin`
- **Alias bind lama**: gunakan nilai mode bind di `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), bukan alias host (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`).
- **Catatan Docker**: bind `loopback` default mendengarkan pada `127.0.0.1` di dalam kontainer. Dengan jaringan bridge Docker (`-p 18789:18789`), lalu lintas masuk melalui `eth0`, sehingga Gateway tidak dapat dijangkau. Gunakan `--network host`, atau atur `bind: "lan"` (atau `bind: "custom"` dengan `customBindHost: "0.0.0.0"`) untuk mendengarkan pada semua antarmuka.
- **Auth**: diwajibkan secara default. Bind non-loopback memerlukan auth Gateway. Dalam praktiknya, ini berarti token/kata sandi bersama atau reverse proxy sadar identitas dengan `gateway.auth.mode: "trusted-proxy"`. Wizard onboarding menghasilkan token secara default.
- Jika `gateway.auth.token` dan `gateway.auth.password` sama-sama dikonfigurasi (termasuk SecretRef), atur `gateway.auth.mode` secara eksplisit ke `token` atau `password`. Alur startup serta pemasangan/perbaikan layanan gagal ketika keduanya dikonfigurasi dan mode belum 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 browser/pengguna ke reverse proxy sadar identitas dan percayai header identitas dari `gateway.trustedProxies` (lihat [Auth Proxy Tepercaya](/id/gateway/trusted-proxy-auth)). Mode ini mengharapkan sumber proxy **non-loopback** secara default; reverse proxy loopback pada host yang sama memerlukan `gateway.auth.trustedProxy.allowLoopback = true` secara eksplisit. Pemanggil internal pada host yang sama dapat menggunakan `gateway.auth.password` sebagai fallback langsung lokal; `gateway.auth.token` tetap saling eksklusif dengan mode trusted-proxy.
- `gateway.auth.allowTailscale`: ketika `true`, header identitas Tailscale Serve dapat memenuhi auth Control UI/WebSocket (diverifikasi melalui `tailscale whois`). Endpoint HTTP API **tidak** menggunakan auth header Tailscale tersebut; endpoint mengikuti mode auth HTTP normal Gateway. Alur tanpa token ini mengasumsikan host Gateway tepercaya. Default ke `true` ketika `tailscale.mode = "serve"`.
- `gateway.auth.rateLimit`: pembatas gagal-auth opsional. Berlaku per IP klien dan per cakupan auth (shared-secret dan device-token dilacak secara independen). Upaya yang diblokir mengembalikan `429` + `Retry-After`.
- Pada jalur Control UI Tailscale Serve asinkron, upaya gagal untuk `{scope, clientIp}` yang sama diserialkan sebelum penulisan kegagalan. Karena itu, upaya buruk serentak dari klien yang sama dapat memicu pembatas pada permintaan kedua alih-alih keduanya berlomba lolos sebagai ketidakcocokan biasa.
- `gateway.auth.rateLimit.exemptLoopback` default ke `true`; atur `false` ketika Anda sengaja ingin lalu lintas localhost juga dibatasi lajunya (untuk penyiapan pengujian atau deployment proxy ketat).
- Upaya auth WS asal browser selalu dibatasi lajunya dengan pengecualian loopback dinonaktifkan (pertahanan berlapis terhadap brute force localhost berbasis browser).
- Pada loopback, lockout asal browser tersebut diisolasi per nilai `Origin`
yang dinormalisasi, sehingga kegagalan berulang dari satu origin localhost tidak otomatis
mengunci origin berbeda.
mengunci origin lain.
- `tailscale.mode`: `serve` (hanya tailnet, bind loopback) atau `funnel` (publik, memerlukan auth).
- `controlUi.allowedOrigins`: allowlist origin browser eksplisit untuk koneksi WebSocket Gateway. Wajib ketika klien browser diharapkan berasal dari origin non-loopback.
- `controlUi.chatMessageMaxWidth`: max-width opsional untuk pesan chat Control UI yang dikelompokkan. Menerima nilai lebar CSS terbatas seperti `960px`, `82%`, `min(1280px, 82%)`, dan `calc(100% - 2rem)`.
- `controlUi.allowedOrigins`: allowlist asal browser eksplisit untuk koneksi WebSocket Gateway. Diperlukan ketika klien browser diharapkan berasal dari origin non-loopback.
- `controlUi.chatMessageMaxWidth`: lebar maksimum opsional untuk pesan chat Control UI yang dikelompokkan. Menerima nilai lebar CSS terbatas seperti `960px`, `82%`, `min(1280px, 82%)`, dan `calc(100% - 2rem)`.
- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: mode berbahaya yang mengaktifkan fallback origin header Host untuk deployment yang sengaja mengandalkan kebijakan origin header Host.
- `remote.transport`: `ssh` (default) atau `direct` (ws/wss). Untuk `direct`, `remote.url` harus berupa `ws://` atau `wss://`.
- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: override darurat lingkungan-proses sisi klien
yang mengizinkan plaintext `ws://` ke IP jaringan privat tepercaya; default tetap hanya
loopback untuk plaintext. Tidak ada padanan `openclaw.json`, dan konfigurasi jaringan privat
browser seperti `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` tidak memengaruhi klien
WebSocket Gateway.
- `gateway.remote.token` / `.password` adalah field kredensial klien jarak jauh. Field ini tidak mengonfigurasi auth gateway dengan sendirinya.
- `gateway.push.apns.relay.baseUrl`: URL HTTPS dasar untuk relay APNs eksternal yang digunakan build iOS resmi/TestFlight setelah build tersebut menerbitkan 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 tersebut dalam registrasi relay, dan meneruskan izin kirim bercakupan registrasi ke gateway. Gateway lain tidak dapat menggunakan ulang registrasi tersimpan tersebut.
- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: override darurat lingkungan proses sisi klien
yang mengizinkan plaintext `ws://` ke IP jaringan privat tepercaya; default tetap hanya loopback
untuk plaintext. Tidak ada padanan `openclaw.json`,
dan konfigurasi jaringan privat browser seperti
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` tidak memengaruhi klien WebSocket
Gateway.
- `gateway.remote.token` / `.password` adalah field kredensial klien jarak jauh. Field ini tidak mengonfigurasi auth Gateway dengan sendirinya.
- `gateway.push.apns.relay.baseUrl`: URL HTTPS dasar untuk relay APNs eksternal yang digunakan oleh build iOS resmi/TestFlight setelah build tersebut menerbitkan 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 tersebut 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 sebaiknya tetap menggunakan HTTPS.
- `gateway.handshakeTimeoutMs`: timeout handshake WebSocket Gateway pra-auth dalam milidetik. Default: `15000`. `OPENCLAW_HANDSHAKE_TIMEOUT_MS` diprioritaskan ketika ditetapkan. Naikkan nilai ini pada host berbeban atau berdaya rendah ketika klien lokal dapat terhubung sementara pemanasan startup masih belum stabil.
- `gateway.channelHealthCheckMinutes`: interval monitor kesehatan channel dalam menit. Tetapkan `0` untuk menonaktifkan restart monitor kesehatan secara global. Default: `5`.
- `gateway.channelStaleEventThresholdMinutes`: ambang socket usang dalam menit. Pertahankan ini lebih besar dari atau sama dengan `gateway.channelHealthCheckMinutes`. Default: `30`.
- `gateway.channelMaxRestartsPerHour`: restart monitor kesehatan maksimum per channel/akun dalam jam berjalan. Default: `10`.
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: celah khusus pengembangan untuk URL relay HTTP loopback. URL relay produksi sebaiknya tetap menggunakan HTTPS.
- `gateway.handshakeTimeoutMs`: timeout handshake WebSocket Gateway pra-auth dalam milidetik. Default: `15000`. `OPENCLAW_HANDSHAKE_TIMEOUT_MS` diprioritaskan ketika diatur. Tingkatkan ini pada host berbeban atau berdaya rendah ketika klien lokal dapat terhubung sementara pemanasan startup masih stabil.
- `gateway.channelHealthCheckMinutes`: interval monitor kesehatan channel dalam menit. Atur `0` untuk menonaktifkan restart monitor kesehatan secara global. Default: `5`.
- `gateway.channelStaleEventThresholdMinutes`: ambang soket stale dalam menit. Pastikan ini lebih besar dari atau sama dengan `gateway.channelHealthCheckMinutes`. Default: `30`.
- `gateway.channelMaxRestartsPerHour`: jumlah maksimum restart monitor kesehatan per channel/akun dalam satu jam berjalan. Default: `10`.
- `channels.<provider>.healthMonitor.enabled`: opt-out per channel untuk restart monitor kesehatan sambil tetap mengaktifkan monitor global.
- `channels.<provider>.accounts.<accountId>.healthMonitor.enabled`: override per akun untuk channel multi-akun. Ketika ditetapkan, ini diprioritaskan atas override level channel.
- Jalur panggilan gateway lokal dapat menggunakan `gateway.remote.*` sebagai fallback hanya ketika `gateway.auth.*` belum ditetapkan.
- Jika `gateway.auth.token` / `gateway.auth.password` secara eksplisit dikonfigurasi melalui SecretRef dan tidak terselesaikan, resolusi gagal tertutup (tanpa masking fallback jarak jauh).
- `trustedProxies`: IP reverse proxy yang mengakhiri TLS atau menyuntikkan header klien-terusan. Hanya cantumkan proxy yang Anda kendalikan. Entri loopback tetap valid untuk penyiapan proxy/deteksi-lokal pada host yang sama (misalnya Tailscale Serve atau reverse proxy lokal), tetapi entri tersebut **tidak** membuat permintaan loopback memenuhi syarat untuk `gateway.auth.mode: "trusted-proxy"`.
- `allowRealIpFallback`: ketika `true`, gateway menerima `X-Real-IP` jika `X-Forwarded-For` tidak ada. Default `false` untuk perilaku gagal-tertutup.
- `gateway.nodes.pairing.autoApproveCidrs`: allowlist CIDR/IP opsional untuk menyetujui otomatis pairing perangkat node pertama kali tanpa cakupan yang diminta. Dinonaktifkan ketika belum ditetapkan. Ini tidak menyetujui otomatis pairing operator/browser/Control UI/WebChat, dan tidak menyetujui otomatis peningkatan role, cakupan, metadata, atau kunci publik.
- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: pembentukan allow/deny global untuk perintah node yang dideklarasikan setelah pairing dan evaluasi allowlist platform. Gunakan `allowCommands` untuk memilih masuk ke perintah node berbahaya seperti `camera.snap`, `camera.clip`, dan `screen.record`; `denyCommands` menghapus perintah bahkan jika default platform atau allow eksplisit seharusnya menyertakannya. Setelah node mengubah daftar perintah yang dideklarasikan, tolak dan setujui ulang pairing perangkat tersebut agar gateway menyimpan snapshot perintah yang diperbarui.
- `channels.<provider>.accounts.<accountId>.healthMonitor.enabled`: override per akun untuk channel multi-akun. Ketika diatur, ini diprioritaskan daripada override tingkat channel.
- Jalur panggilan Gateway lokal dapat menggunakan `gateway.remote.*` sebagai fallback hanya ketika `gateway.auth.*` belum diatur.
- Jika `gateway.auth.token` / `gateway.auth.password` secara eksplisit dikonfigurasi melalui SecretRef dan tidak terselesaikan, resolusi gagal tertutup (tanpa fallback jarak jauh yang menyamarkan).
- `trustedProxies`: IP reverse proxy yang mengakhiri TLS atau menyuntikkan header klien yang diteruskan. Hanya cantumkan proxy yang Anda kontrol. Entri loopback tetap valid untuk penyiapan proxy/deteksi lokal pada host yang sama (misalnya Tailscale Serve atau reverse proxy lokal), tetapi entri tersebut **tidak** membuat permintaan loopback memenuhi syarat untuk `gateway.auth.mode: "trusted-proxy"`.
- `allowRealIpFallback`: ketika `true`, Gateway menerima `X-Real-IP` jika `X-Forwarded-For` tidak ada. Default `false` untuk perilaku gagal tertutup.
- `gateway.nodes.pairing.autoApproveCidrs`: allowlist CIDR/IP opsional untuk menyetujui otomatis pairing perangkat node pertama kali tanpa cakupan yang diminta. Ini dinonaktifkan ketika belum diatur. Ini tidak menyetujui otomatis pairing operator/browser/Control UI/WebChat, dan tidak menyetujui otomatis peningkatan peran, cakupan, metadata, atau kunci publik.
- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: pembentukan allow/deny global untuk perintah node yang dideklarasikan setelah pairing dan evaluasi allowlist platform. Gunakan `allowCommands` untuk ikut mengaktifkan perintah node berbahaya seperti `camera.snap`, `camera.clip`, dan `screen.record`; `denyCommands` menghapus perintah meskipun default platform atau allow eksplisit sebaliknya akan menyertakannya. Setelah sebuah node mengubah daftar perintah yang dideklarasikan, tolak dan setujui ulang pairing perangkat tersebut agar Gateway menyimpan snapshot perintah yang diperbarui.
- `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.
</Accordion>
### Endpoint kompatibel OpenAI
### Endpoint yang kompatibel dengan OpenAI
- Chat Completions: dinonaktifkan secara default. Aktifkan dengan `gateway.http.endpoints.chatCompletions.enabled: true`.
- Responses API: `gateway.http.endpoints.responses.enabled`.
@ -483,14 +491,14 @@ Lihat [Komitmen yang diinferensikan](/id/concepts/commitments).
- `gateway.http.endpoints.responses.maxUrlParts`
- `gateway.http.endpoints.responses.files.urlAllowlist`
- `gateway.http.endpoints.responses.images.urlAllowlist`
Allowlist kosong diperlakukan sebagai belum ditetapkan; gunakan `gateway.http.endpoints.responses.files.allowUrl=false`
Allowlist kosong diperlakukan sebagai belum diatur; gunakan `gateway.http.endpoints.responses.files.allowUrl=false`
dan/atau `gateway.http.endpoints.responses.images.allowUrl=false` untuk menonaktifkan pengambilan URL.
- Header penguatan respons opsional:
- `gateway.http.securityHeaders.strictTransportSecurity` (tetapkan hanya untuk origin HTTPS yang Anda kendalikan; lihat [Auth Proxy Tepercaya](/id/gateway/trusted-proxy-auth#tls-termination-and-hsts))
- `gateway.http.securityHeaders.strictTransportSecurity` (atur hanya untuk origin HTTPS yang Anda kontrol; lihat [Auth Proxy Tepercaya](/id/gateway/trusted-proxy-auth#tls-termination-and-hsts))
### Isolasi multi-instans
Jalankan beberapa gateway pada satu host dengan port dan direktori state unik:
Jalankan beberapa Gateway pada satu host dengan port dan direktori state yang unik:
```bash
OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
@ -498,7 +506,7 @@ OPENCLAW_STATE_DIR=~/.openclaw-a \
openclaw gateway --port 19001
```
Flag praktis: `--dev` (menggunakan `~/.openclaw-dev` + port `19001`), `--profile <name>` (menggunakan `~/.openclaw-<name>`).
Flag kemudahan: `--dev` (menggunakan `~/.openclaw-dev` + port `19001`), `--profile <name>` (menggunakan `~/.openclaw-<name>`).
Lihat [Beberapa Gateway](/id/gateway/multiple-gateways).
@ -518,11 +526,11 @@ Lihat [Beberapa Gateway](/id/gateway/multiple-gateways).
}
```
- `enabled`: mengaktifkan terminasi TLS pada listener gateway (HTTPS/WSS) (default: `false`).
- `autoGenerate`: menghasilkan otomatis pasangan sertifikat/kunci self-signed lokal ketika file eksplisit tidak dikonfigurasi; hanya untuk penggunaan lokal/dev.
- `certPath`: path sistem file ke file sertifikat TLS.
- `keyPath`: path sistem file ke file kunci privat TLS; pertahankan izin tetap terbatas.
- `caPath`: path bundle CA opsional untuk verifikasi klien atau rantai kepercayaan kustom.
- `enabled`: mengaktifkan terminasi TLS pada listener Gateway (HTTPS/WSS) (default: `false`).
- `autoGenerate`: menghasilkan otomatis pasangan cert/key self-signed lokal ketika file eksplisit tidak dikonfigurasi; hanya untuk penggunaan lokal/dev.
- `certPath`: path filesystem ke file sertifikat TLS.
- `keyPath`: path filesystem ke file kunci privat TLS; batasi izinnya.
- `caPath`: path bundel CA opsional untuk verifikasi klien atau rantai trust khusus.
### `gateway.reload`
@ -538,17 +546,17 @@ Lihat [Beberapa Gateway](/id/gateway/multiple-gateways).
}
```
- `mode`: mengontrol bagaimana edit konfigurasi diterapkan saat runtime.
- `"off"`: abaikan edit langsung; perubahan memerlukan restart eksplisit.
- `"restart"`: selalu restart proses gateway saat konfigurasi berubah.
- `"hot"`: terapkan perubahan dalam-proses tanpa restart.
- `mode`: mengontrol cara edit konfigurasi diterapkan saat runtime.
- `"off"`: abaikan edit live; perubahan memerlukan restart eksplisit.
- `"restart"`: selalu restart proses Gateway saat konfigurasi berubah.
- `"hot"`: terapkan perubahan di dalam proses tanpa restart.
- `"hybrid"` (default): coba hot reload terlebih dahulu; fallback ke restart jika diperlukan.
- `debounceMs`: jendela debounce dalam ms sebelum perubahan konfigurasi diterapkan (bilangan bulat non-negatif).
- `deferralTimeoutMs`: waktu maksimum opsional dalam ms untuk menunggu operasi yang sedang berjalan sebelum memaksa restart. Hilangkan untuk menggunakan tunggu terbatas default (`300000`); tetapkan `0` untuk menunggu tanpa batas dan mencatat peringatan masih-tertunda secara berkala.
- `deferralTimeoutMs`: waktu maksimum opsional dalam ms untuk menunggu operasi yang sedang berjalan sebelum memaksa restart. Hilangkan untuk menggunakan waktu tunggu terbatas default (`300000`); atur `0` untuk menunggu tanpa batas dan mencatat peringatan masih-tertunda secara berkala.
---
## Kait
## Hook
```json5
{
@ -582,47 +590,47 @@ Lihat [Beberapa Gateway](/id/gateway/multiple-gateways).
```
Autentikasi: `Authorization: Bearer <token>` atau `x-openclaw-token: <token>`.
Token hook string kueri 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.path` tidak boleh `/`; gunakan subjalur khusus seperti `/hooks`.
- `hooks.path` tidak boleh `/`; gunakan subpath khusus seperti `/hooks`.
- Jika `hooks.allowRequestSessionKey=true`, batasi `hooks.allowedSessionKeyPrefixes` (misalnya `["hook:"]`).
- Jika pemetaan atau preset menggunakan `sessionKey` bertemplat, tetapkan `hooks.allowedSessionKeyPrefixes` dan `hooks.allowRequestSessionKey=true`. Kunci pemetaan statis tidak memerlukan opt-in tersebut.
- Jika pemetaan atau preset menggunakan `sessionKey` bertemplat, atur `hooks.allowedSessionKeyPrefixes` dan `hooks.allowRequestSessionKey=true`. Kunci pemetaan statis tidak memerlukan opt-in tersebut.
**Endpoint:**
**Titik akhir:**
- `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }`
- `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }`
- `sessionKey` dari payload permintaan hanya diterima saat `hooks.allowRequestSessionKey=true` (default: `false`).
- `sessionKey` dari payload permintaan hanya diterima ketika `hooks.allowRequestSessionKey=true` (bawaan: `false`).
- `POST /hooks/<name>` → diselesaikan melalui `hooks.mappings`
- Nilai `sessionKey` pemetaan yang dirender dari templat diperlakukan sebagai nilai yang dipasok secara eksternal dan juga memerlukan `hooks.allowRequestSessionKey=true`.
<Accordion title="Detail pemetaan">
<Accordion title="Mapping details">
- `match.path` mencocokkan subjalur setelah `/hooks` (mis. `/hooks/gmail` → `gmail`).
- `match.source` mencocokkan kolom payload untuk jalur generik.
- `match.path` mencocokkan subpath setelah `/hooks` (misalnya `/hooks/gmail` → `gmail`).
- `match.source` mencocokkan kolom payload untuk path generik.
- Templat seperti `{{messages[0].subject}}` membaca dari payload.
- `transform` dapat mengarah ke modul JS/TS yang mengembalikan aksi hook.
- `transform.module` harus berupa jalur relatif dan tetap berada dalam `hooks.transformsDir` (jalur absolut dan traversal ditolak).
- Simpan `hooks.transformsDir` di bawah `~/.openclaw/hooks/transforms`; direktori skill workspace ditolak. Jika `openclaw doctor` melaporkan jalur ini tidak valid, pindahkan modul transform ke direktori transform hook atau hapus `hooks.transformsDir`.
- `agentId` merutekan ke agen tertentu; ID yang tidak dikenal kembali ke default.
- `transform` dapat menunjuk ke modul JS/TS yang mengembalikan tindakan hook.
- `transform.module` harus berupa path relatif dan tetap berada di dalam `hooks.transformsDir` (path absolut dan traversal ditolak).
- Simpan `hooks.transformsDir` di bawah `~/.openclaw/hooks/transforms`; direktori skill workspace ditolak. Jika `openclaw doctor` melaporkan path ini tidak valid, pindahkan modul transform ke direktori transform hook atau hapus `hooks.transformsDir`.
- `agentId` merutekan ke agen tertentu; ID yang tidak dikenal kembali ke bawaan.
- `allowedAgentIds`: membatasi perutean eksplisit (`*` atau dihilangkan = izinkan semua, `[]` = tolak semua).
- `defaultSessionKey`: kunci sesi tetap opsional untuk eksekusi agen hook tanpa `sessionKey` eksplisit.
- `allowRequestSessionKey`: mengizinkan pemanggil `/hooks/agent` dan kunci sesi pemetaan berbasis templat untuk menetapkan `sessionKey` (default: `false`).
- `allowedSessionKeyPrefixes`: allowlist prefiks opsional untuk nilai `sessionKey` eksplisit (permintaan + pemetaan), mis. `["hook:"]`. Ini menjadi wajib saat pemetaan atau preset apa pun menggunakan `sessionKey` bertemplat.
- `deliver: true` mengirim balasan akhir ke channel; `channel` default ke `last`.
- `model` mengganti LLM untuk eksekusi hook ini (harus diizinkan jika katalog model ditetapkan).
- `defaultSessionKey`: kunci sesi tetap opsional untuk proses agen hook tanpa `sessionKey` eksplisit.
- `allowRequestSessionKey`: izinkan pemanggil `/hooks/agent` dan kunci sesi pemetaan berbasis templat untuk mengatur `sessionKey` (bawaan: `false`).
- `allowedSessionKeyPrefixes`: allowlist prefiks opsional untuk nilai `sessionKey` eksplisit (permintaan + pemetaan), misalnya `["hook:"]`. Ini menjadi wajib ketika pemetaan atau preset apa pun menggunakan `sessionKey` bertemplat.
- `deliver: true` mengirim balasan final ke channel; `channel` bawaan ke `last`.
- `model` menimpa LLM untuk proses hook ini (harus diizinkan jika katalog model diatur).
</Accordion>
### Integrasi Gmail
- Preset Gmail bawaan menggunakan `sessionKey: "hook:gmail:{{messages[0].id}}"`.
- Jika Anda mempertahankan perutean per pesan tersebut, tetapkan `hooks.allowRequestSessionKey: true` dan batasi `hooks.allowedSessionKeyPrefixes` agar cocok dengan namespace Gmail, misalnya `["hook:", "hook:gmail:"]`.
- Jika Anda membutuhkan `hooks.allowRequestSessionKey: false`, timpa preset dengan `sessionKey` statis alih-alih default bertemplat.
- Jika Anda mempertahankan perutean 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 bawaan bertemplat.
```json5
{
@ -645,12 +653,12 @@ Catatan validasi dan keamanan:
}
```
- Gateway otomatis memulai `gog gmail watch serve` saat boot ketika dikonfigurasi. Tetapkan `OPENCLAW_SKIP_GMAIL_WATCHER=1` untuk menonaktifkan.
- Jangan menjalankan `gog gmail watch serve` terpisah bersamaan dengan Gateway.
- Gateway otomatis menjalankan `gog gmail watch serve` saat boot ketika dikonfigurasi. Atur `OPENCLAW_SKIP_GMAIL_WATCHER=1` untuk menonaktifkan.
- Jangan jalankan `gog gmail watch serve` terpisah bersamaan dengan Gateway.
---
## Host canvas
## Host kanvas
```json5
{
@ -665,15 +673,15 @@ Catatan validasi dan keamanan:
- Menyajikan HTML/CSS/JS yang dapat diedit agen dan A2UI melalui HTTP di bawah port Gateway:
- `http://<gateway-host>:<gateway.port>/__openclaw__/canvas/`
- `http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/`
- Hanya lokal: pertahankan `gateway.bind: "loopback"` (default).
- Bind non-loopback: rute canvas memerlukan autentikasi Gateway (token/password/trusted-proxy), sama seperti surface HTTP Gateway lainnya.
- Node WebViews biasanya tidak mengirim header autentikasi; setelah sebuah node dipasangkan dan terhubung, Gateway mengiklankan URL kapabilitas berscope node untuk akses canvas/A2UI.
- Hanya lokal: pertahankan `gateway.bind: "loopback"` (bawaan).
- Bind non-loopback: rute kanvas memerlukan autentikasi Gateway (token/kata sandi/proksi tepercaya), sama seperti permukaan HTTP Gateway lainnya.
- WebView Node biasanya tidak mengirim header autentikasi; setelah node dipasangkan dan terhubung, Gateway mengiklankan URL kapabilitas bercakupan node untuk akses kanvas/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.
- Otomatis membuat `index.html` awal saat kosong.
- Otomatis membuat `index.html` awal ketika kosong.
- Juga menyajikan A2UI di `/__openclaw__/a2ui/`.
- Perubahan memerlukan restart gateway.
- Nonaktifkan live reload untuk direktori besar atau kesalahan `EMFILE`.
- Nonaktifkan pemuatan ulang langsung untuk direktori besar atau kesalahan `EMFILE`.
---
@ -691,11 +699,11 @@ Catatan validasi dan keamanan:
}
```
- `minimal` (default saat Plugin `bonjour` bawaan diaktifkan): hilangkan `cliPath` + `sshPort` dari catatan TXT.
- `full`: sertakan `cliPath` + `sshPort`; iklan multicast LAN tetap memerlukan Plugin `bonjour` bawaan diaktifkan.
- `off`: menekan iklan multicast LAN tanpa mengubah pengaktifan Plugin.
- Plugin `bonjour` bawaan otomatis dimulai pada host macOS dan bersifat opt-in pada Linux, Windows, dan deployment Gateway dalam container.
- Hostname default ke hostname sistem saat merupakan label DNS yang valid, dengan fallback ke `openclaw`. Timpa dengan `OPENCLAW_MDNS_HOSTNAME`.
- `minimal` (bawaan ketika plugin `bonjour` yang dibundel diaktifkan): hilangkan `cliPath` + `sshPort` dari catatan TXT.
- `full`: sertakan `cliPath` + `sshPort`; iklan multicast LAN tetap memerlukan plugin `bonjour` yang dibundel untuk diaktifkan.
- `off`: menekan iklan multicast LAN tanpa mengubah pengaktifan plugin.
- Plugin `bonjour` yang dibundel otomatis berjalan di host macOS dan bersifat opt-in di Linux, Windows, serta deployment Gateway dalam kontainer.
- Nama host bawaan ke nama host sistem ketika merupakan label DNS yang valid, dengan fallback ke `openclaw`. Timpa dengan `OPENCLAW_MDNS_HOSTNAME`.
### Area luas (DNS-SD)
@ -707,7 +715,7 @@ Catatan validasi dan keamanan:
}
```
Menulis zona DNS-SD unicast di bawah `~/.openclaw/dns/`. Untuk penemuan lintas jaringan, pasangkan dengan server DNS (CoreDNS direkomendasikan) + DNS split Tailscale.
Menulis zona DNS-SD unicast di bawah `~/.openclaw/dns/`. Untuk penemuan lintas jaringan, pasangkan dengan server DNS (CoreDNS direkomendasikan) + DNS terpisah Tailscale.
Penyiapan: `openclaw dns setup --apply`.
@ -739,7 +747,7 @@ Penyiapan: `openclaw dns setup --apply`.
### Substitusi variabel env
Rujuk variabel env dalam string konfigurasi apa pun dengan `${VAR_NAME}`:
Referensikan variabel env dalam string konfigurasi apa pun dengan `${VAR_NAME}`:
```json5
{
@ -758,7 +766,7 @@ Rujuk variabel env dalam string konfigurasi apa pun dengan `${VAR_NAME}`:
## Rahasia
Referensi rahasia bersifat aditif: nilai plaintext tetap berfungsi.
Referensi rahasia bersifat aditif: nilai teks biasa tetap berfungsi.
### `SecretRef`
@ -772,9 +780,9 @@ Validasi:
- Pola `provider`: `^[a-z][a-z0-9_-]{0,63}$`
- Pola id `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$`
- id `source: "file"`: pointer JSON absolut (misalnya `"/providers/openai/apiKey"`)
- Id `source: "file"`: pointer JSON absolut (misalnya `"/providers/openai/apiKey"`)
- Pola id `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`
- id `source: "exec"` tidak boleh berisi segmen path berbatas slash `.` atau `..` (misalnya `a/../b` ditolak)
- Id `source: "exec"` tidak boleh berisi segmen path berbatas slash `.` atau `..` (misalnya `a/../b` ditolak)
### Permukaan kredensial yang didukung
@ -812,14 +820,14 @@ Validasi:
Catatan:
- Penyedia `file` mendukung `mode: "json"` dan `mode: "singleValue"` (`id` harus `"value"` dalam mode singleValue).
- Path penyedia file dan exec gagal tertutup saat verifikasi ACL Windows tidak tersedia. Tetapkan `allowInsecurePath: true` hanya untuk path tepercaya yang tidak dapat diverifikasi.
- Penyedia `file` mendukung `mode: "json"` dan `mode: "singleValue"` (`id` harus berupa `"value"` dalam mode singleValue).
- Path penyedia file dan exec gagal tertutup saat verifikasi ACL Windows tidak tersedia. Atur `allowInsecurePath: true` hanya untuk path tepercaya yang tidak dapat diverifikasi.
- Penyedia `exec` memerlukan path `command` absolut dan menggunakan payload protokol pada stdin/stdout.
- Secara default, path perintah symlink ditolak. Tetapkan `allowSymlinkCommand: true` untuk mengizinkan path symlink sambil memvalidasi path target yang di-resolve.
- Jika `trustedDirs` dikonfigurasi, pemeriksaan direktori tepercaya berlaku pada path target yang di-resolve.
- Environment child `exec` minimal secara default; teruskan variabel yang diperlukan secara eksplisit dengan `passEnv`.
- 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 direktori tepercaya berlaku pada path target yang telah di-resolve.
- Lingkungan child `exec` minimal secara default; teruskan variabel yang diperlukan secara eksplisit dengan `passEnv`.
- Referensi rahasia di-resolve pada waktu aktivasi menjadi snapshot dalam memori, lalu path permintaan hanya membaca snapshot tersebut.
- Pemfilteran permukaan aktif berlaku selama aktivasi: referensi yang belum di-resolve pada permukaan yang diaktifkan menggagalkan startup/reload, sementara permukaan tidak aktif dilewati dengan diagnostik.
- Pemfilteran permukaan aktif berlaku selama aktivasi: referensi yang belum di-resolve pada permukaan yang diaktifkan menggagalkan startup/reload, sedangkan permukaan yang tidak aktif dilewati dengan diagnostik.
---
@ -843,12 +851,12 @@ Catatan:
- Profil per agen disimpan di `<agentDir>/auth-profiles.json`.
- `auth-profiles.json` mendukung referensi tingkat nilai (`keyRef` untuk `api_key`, `tokenRef` untuk `token`) untuk mode kredensial statis.
- Peta datar lama `auth-profiles.json` seperti `{ "provider": { "apiKey": "..." } }` bukan format runtime; `openclaw doctor --fix` menulis ulangnya menjadi profil API-key `provider:default` kanonis dengan cadangan `.legacy-flat.*.bak`.
- Profil mode OAuth (`auth.profiles.<id>.mode = "oauth"`) tidak mendukung kredensial profil auth yang didukung SecretRef.
- Peta datar `auth-profiles.json` lama seperti `{ "provider": { "apiKey": "..." } }` bukan format runtime; `openclaw doctor --fix` menulis ulangnya menjadi profil API-key `provider:default` kanonis dengan cadangan `.legacy-flat.*.bak`.
- Profil mode OAuth (`auth.profiles.<id>.mode = "oauth"`) tidak mendukung kredensial auth-profile yang didukung SecretRef.
- Kredensial runtime statis berasal dari snapshot yang telah di-resolve dalam memori; entri `auth.json` statis lama dibersihkan saat ditemukan.
- Impor OAuth lama berasal dari `~/.openclaw/credentials/oauth.json`.
- Impor OAuth lama dari `~/.openclaw/credentials/oauth.json`.
- Lihat [OAuth](/id/concepts/oauth).
- Perilaku runtime rahasia dan tooling `audit/configure/apply`: [Manajemen Rahasia](/id/gateway/secrets).
- Perilaku runtime rahasia dan alat `audit/configure/apply`: [Manajemen Rahasia](/id/gateway/secrets).
### `auth.cooldowns`
@ -870,15 +878,15 @@ Catatan:
}
```
- `billingBackoffHours`: backoff dasar dalam jam saat profil gagal karena kesalahan penagihan/kredit-tidak-mencukupi yang benar-benar terjadi (default: `5`). Teks penagihan eksplisit masih bisa masuk ke sini bahkan pada respons `401`/`403`, tetapi pencocok teks spesifik penyedia tetap dibatasi pada penyedia yang memilikinya (misalnya OpenRouter `Key limit exceeded`). Pesan HTTP `402` yang dapat dicoba ulang untuk usage-window atau batas belanja organisasi/workspace tetap berada di jalur `rate_limit`.
- `billingBackoffHours`: backoff dasar dalam jam saat profil gagal karena error penagihan/kredit-tidak-mencukupi yang sebenarnya (default: `5`). Teks penagihan eksplisit masih dapat masuk ke sini bahkan pada respons `401`/`403`, tetapi pencocok teks khusus penyedia tetap dibatasi pada penyedia yang memilikinya (misalnya OpenRouter `Key limit exceeded`). Pesan HTTP `402` usage-window atau batas pembelanjaan organisasi/workspace yang dapat dicoba ulang tetap berada di jalur `rate_limit`.
- `billingBackoffHoursByProvider`: override opsional per penyedia untuk jam backoff penagihan.
- `billingMaxHours`: batas dalam jam untuk pertumbuhan eksponensial backoff penagihan (default: `24`).
- `authPermanentBackoffMinutes`: backoff dasar dalam menit untuk kegagalan `auth_permanent` dengan keyakinan tinggi (default: `10`).
- `authPermanentMaxMinutes`: batas dalam menit untuk pertumbuhan backoff `auth_permanent` (default: `60`).
- `failureWindowHours`: jendela bergulir dalam jam yang digunakan untuk penghitung backoff (default: `24`).
- `overloadedProfileRotations`: rotasi auth-profile penyedia-sama maksimum untuk kesalahan kelebihan beban sebelum beralih ke fallback model (default: `1`). Bentuk penyedia-sibuk seperti `ModelNotReadyException` masuk ke sini.
- `overloadedBackoffMs`: jeda tetap sebelum mencoba ulang rotasi penyedia/profil yang kelebihan beban (default: `0`).
- `rateLimitedProfileRotations`: rotasi auth-profile penyedia-sama maksimum untuk kesalahan batas laju sebelum beralih ke fallback model (default: `1`). Bucket batas laju itu mencakup teks berbentuk penyedia seperti `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded`, dan `resource exhausted`.
- `overloadedProfileRotations`: maksimum rotasi profil autentikasi penyedia yang sama untuk error kelebihan beban sebelum beralih ke fallback model (default: `1`). Bentuk penyedia-sibuk seperti `ModelNotReadyException` masuk ke sini.
- `overloadedBackoffMs`: penundaan tetap sebelum mencoba ulang rotasi penyedia/profil yang kelebihan beban (default: `0`).
- `rateLimitedProfileRotations`: maksimum rotasi profil autentikasi penyedia yang sama untuk error batas laju sebelum beralih ke fallback model (default: `1`). Bucket batas laju tersebut mencakup teks berbentuk penyedia seperti `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded`, dan `resource exhausted`.
---
@ -900,8 +908,8 @@ Catatan:
- File log default: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`.
- Atur `logging.file` untuk jalur yang stabil.
- `consoleLevel` naik ke `debug` saat `--verbose`.
- `maxFileBytes`: ukuran maksimum file log aktif dalam byte sebelum rotasi (bilangan bulat positif; default: `104857600` = 100 MB). OpenClaw mempertahankan hingga lima arsip bernomor di samping file aktif.
- `redactSensitive` / `redactPatterns`: penyamaran upaya-terbaik untuk output konsol, log file, rekaman log OTLP, dan teks transkrip sesi yang disimpan. `redactSensitive: "off"` hanya menonaktifkan kebijakan log/transkrip umum ini; permukaan keamanan UI/alat/diagnostik tetap meredaksi rahasia sebelum emisi.
- `maxFileBytes`: ukuran maksimum file log aktif dalam byte sebelum rotasi (bilangan bulat positif; default: `104857600` = 100 MB). OpenClaw menyimpan hingga lima arsip bernomor di samping file aktif.
- `redactSensitive` / `redactPatterns`: penyamaran upaya terbaik untuk output konsol, log file, rekaman log OTLP, dan teks transkrip sesi yang dipersistenkan. `redactSensitive: "off"` hanya menonaktifkan kebijakan log/transkrip umum ini; permukaan keamanan UI/tool/diagnostik tetap menyamarkan rahasia sebelum emisi.
---
@ -949,23 +957,23 @@ Catatan:
}
```
- `enabled`: pengalih utama untuk output instrumentasi (default: `true`).
- `flags`: array string flag yang mengaktifkan output log bertarget (mendukung wildcard seperti `"telegram.*"` atau `"*"`).
- `stuckSessionWarnMs`: ambang usia tanpa progres dalam ms untuk mengklasifikasikan sesi pemrosesan berjalan lama sebagai `session.long_running`, `session.stalled`, atau `session.stuck`. Balasan, alat, status, blok, dan progres ACP mereset timer; diagnostik `session.stuck` berulang melakukan backoff selama tidak berubah.
- `enabled`: toggle utama untuk output instrumentasi (default: `true`).
- `flags`: array string flag yang mengaktifkan output log tertarget (mendukung wildcard seperti `"telegram.*"` atau `"*"`).
- `stuckSessionWarnMs`: ambang usia tanpa progres dalam ms untuk mengklasifikasikan sesi pemrosesan yang berjalan lama sebagai `session.long_running`, `session.stalled`, atau `session.stuck`. Balasan, tool, status, blok, dan progres ACP mengatur ulang timer; diagnostik `session.stuck` berulang melakukan backoff selama tidak berubah.
- `otel.enabled`: mengaktifkan pipeline ekspor OpenTelemetry (default: `false`). Untuk konfigurasi lengkap, katalog sinyal, dan model privasi, lihat [ekspor OpenTelemetry](/id/gateway/opentelemetry).
- `otel.endpoint`: URL kolektor untuk ekspor OTel.
- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`: endpoint OTLP opsional spesifik sinyal. Saat diatur, nilai tersebut menimpa `otel.endpoint` hanya untuk sinyal itu.
- `otel.tracesEndpoint` / `otel.metricsEndpoint` / `otel.logsEndpoint`: endpoint OTLP khusus sinyal opsional. Jika diatur, ini menggantikan `otel.endpoint` hanya untuk sinyal tersebut.
- `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.sampleRate`: laju sampling trace `0`-`1`.
- `otel.sampleRate`: laju sampling trace `0`–`1`.
- `otel.flushIntervalMs`: interval flush telemetri berkala dalam ms.
- `otel.captureContent`: pengambilan konten mentah yang harus diikutsertakan secara eksplisit untuk atribut span OTEL. Defaultnya nonaktif. Boolean `true` menangkap konten pesan/alat non-sistem; bentuk objek memungkinkan Anda mengaktifkan `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs`, dan `systemPrompt` secara eksplisit.
- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`: pengalih lingkungan untuk atribut penyedia span GenAI eksperimental terbaru. Secara default span mempertahankan atribut `gen_ai.system` lama untuk kompatibilitas; metrik GenAI menggunakan atribut semantik terbatas.
- `OPENCLAW_OTEL_PRELOADED=1`: pengalih lingkungan untuk host yang sudah mendaftarkan SDK OpenTelemetry global. OpenClaw kemudian melewati startup/shutdown SDK milik plugin sambil tetap menjaga listener diagnostik aktif.
- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`, dan `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`: variabel lingkungan endpoint spesifik sinyal yang digunakan saat kunci konfigurasi yang cocok tidak diatur.
- `cacheTrace.enabled`: catat snapshot trace cache untuk eksekusi tertanam (default: `false`).
- `otel.captureContent`: keikutsertaan eksplisit untuk menangkap konten mentah bagi atribut span OTEL. Defaultnya nonaktif. Boolean `true` menangkap konten pesan/tool non-sistem; bentuk objek memungkinkan Anda mengaktifkan `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs`, dan `systemPrompt` secara eksplisit.
- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`: toggle environment untuk atribut penyedia span GenAI eksperimental terbaru. Secara default, span mempertahankan atribut legacy `gen_ai.system` demi kompatibilitas; metrik GenAI menggunakan atribut semantik berbatas.
- `OPENCLAW_OTEL_PRELOADED=1`: toggle environment untuk host yang sudah mendaftarkan SDK OpenTelemetry global. OpenClaw lalu melewati startup/shutdown SDK milik Plugin sambil menjaga listener diagnostik tetap aktif.
- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`, dan `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`: env var endpoint khusus sinyal yang digunakan saat kunci konfigurasi yang sesuai tidak diatur.
- `cacheTrace.enabled`: catat snapshot trace cache untuk run tertanam (default: `false`).
- `cacheTrace.filePath`: jalur output untuk JSONL trace cache (default: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`).
- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: mengontrol apa yang disertakan dalam output trace cache (semua default: `true`).
@ -990,9 +998,9 @@ Catatan:
```
- `channel`: kanal rilis untuk instalasi npm/git — `"stable"`, `"beta"`, atau `"dev"`.
- `checkOnStart`: periksa pembaruan npm saat gateway dimulai (default: `true`).
- `checkOnStart`: periksa pembaruan npm saat Gateway dimulai (default: `true`).
- `auto.enabled`: aktifkan pembaruan otomatis latar belakang untuk instalasi paket (default: `false`).
- `auto.stableDelayHours`: jeda minimum dalam jam sebelum penerapan otomatis kanal stable (default: `6`; maks: `168`).
- `auto.stableDelayHours`: penundaan minimum dalam jam sebelum penerapan otomatis kanal stable (default: `6`; maks: `168`).
- `auto.stableJitterHours`: jendela sebaran rollout tambahan kanal stable dalam jam (default: `12`; maks: `168`).
- `auto.betaCheckIntervalHours`: seberapa sering pemeriksaan kanal beta berjalan dalam jam (default: `1`; maks: `24`).
@ -1027,23 +1035,23 @@ Catatan:
}
```
- `enabled`: gerbang fitur ACP global (default: `true`; atur `false` untuk menyembunyikan affordance dispatch dan spawn ACP).
- `dispatch.enabled`: gerbang independen untuk dispatch giliran sesi ACP (default: `true`). Atur `false` untuk mempertahankan perintah ACP tersedia sambil memblokir eksekusi.
- `backend`: id backend runtime ACP default (harus cocok dengan plugin runtime ACP terdaftar).
Instal plugin backend terlebih dahulu, dan jika `plugins.allow` diatur, sertakan id plugin backend (misalnya `acpx`) atau backend ACP tidak akan dimuat.
- `enabled`: gate fitur ACP global (default: `true`; atur `false` untuk menyembunyikan dispatch ACP dan affordance spawn).
- `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 yang terdaftar).
Instal Plugin backend terlebih dahulu, dan jika `plugins.allow` diatur, sertakan id Plugin backend (misalnya `acpx`) atau backend ACP tidak akan dimuat.
- `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 bersamaan.
- `maxConcurrentSessions`: jumlah maksimum sesi ACP aktif secara bersamaan.
- `stream.coalesceIdleMs`: jendela flush idle dalam ms untuk teks yang di-stream.
- `stream.maxChunkChars`: ukuran chunk maksimum sebelum membagi proyeksi blok streaming.
- `stream.repeatSuppression`: tekan baris status/alat berulang per giliran (default: `true`).
- `stream.deliveryMode`: `"live"` melakukan stream secara bertahap; `"final_only"` menahan buffer sampai peristiwa terminal giliran.
- `stream.hiddenBoundarySeparator`: pemisah sebelum teks terlihat setelah peristiwa alat tersembunyi (default: `"paragraph"`).
- `stream.maxChunkChars`: ukuran chunk maksimum sebelum membagi proyeksi blok yang di-stream.
- `stream.repeatSuppression`: tekan baris status/tool berulang per giliran (default: `true`).
- `stream.deliveryMode`: `"live"` melakukan stream secara inkremental; `"final_only"` menahan buffer hingga event terminal giliran.
- `stream.hiddenBoundarySeparator`: pemisah sebelum teks terlihat setelah event tool tersembunyi (default: `"paragraph"`).
- `stream.maxOutputChars`: karakter output asisten maksimum yang diproyeksikan per giliran ACP.
- `stream.maxSessionUpdateChars`: karakter maksimum untuk baris status/pembaruan ACP yang diproyeksikan.
- `stream.tagVisibility`: rekaman nama tag ke override visibilitas boolean untuk peristiwa yang di-stream.
- `runtime.ttlMinutes`: TTL idle dalam menit untuk worker sesi ACP sebelum layak dibersihkan.
- `runtime.installCommand`: perintah instal opsional untuk dijalankan saat melakukan bootstrap lingkungan runtime ACP.
- `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 pembersihan.
- `runtime.installCommand`: perintah instal opsional untuk dijalankan saat melakukan bootstrap environment runtime ACP.
---
@ -1060,14 +1068,14 @@ Catatan:
```
- `cli.banner.taglineMode` mengontrol gaya tagline banner:
- `"random"` (default): tagline lucu/musiman yang berputar.
- `"random"` (default): tagline lucu/musiman yang berotasi.
- `"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`.
---
## Pemandu
## Wizard
Metadata yang ditulis oleh alur penyiapan terpandu CLI (`onboard`, `configure`, `doctor`):
@ -1087,15 +1095,15 @@ Metadata yang ditulis oleh alur penyiapan terpandu CLI (`onboard`, `configure`,
## Identitas
Lihat bidang identitas `agents.list` di bawah [Default agen](/id/gateway/config-agents#agent-defaults).
Lihat bidang identitas `agents.list` di bawah [default Agen](/id/gateway/config-agents#agent-defaults).
---
## Bridge (warisan, dihapus)
## Bridge (legacy, dihapus)
Build saat ini tidak lagi menyertakan bridge TCP. Node terhubung melalui WebSocket Gateway. Kunci `bridge.*` tidak lagi menjadi bagian dari skema konfigurasi (validasi gagal sampai dihapus; `openclaw doctor --fix` dapat menghapus kunci yang tidak dikenal).
Build saat ini tidak lagi menyertakan bridge TCP. Node terhubung melalui WebSocket Gateway. Kunci `bridge.*` tidak lagi menjadi bagian dari skema konfigurasi (validasi gagal hingga dihapus; `openclaw doctor --fix` dapat menghapus kunci yang tidak dikenal).
<Accordion title="Konfigurasi bridge warisan (referensi historis)">
<Accordion title="Konfigurasi bridge legacy (referensi historis)">
```json
{
@ -1133,11 +1141,11 @@ Build saat ini tidak lagi menyertakan bridge TCP. Node terhubung melalui WebSock
}
```
- `sessionRetention`: berapa lama mempertahankan sesi eksekusi cron terisolasi yang selesai sebelum dipangkas dari `sessions.json`. Juga mengontrol pembersihan transkrip cron terhapus yang diarsipkan. Default: `24h`; atur `false` untuk menonaktifkan.
- `runLog.maxBytes`: ukuran maksimum per file log eksekusi (`cron/runs/<jobId>.jsonl`) sebelum pemangkasan. Default: `2_000_000` byte.
- `runLog.keepLines`: baris terbaru yang dipertahankan saat pemangkasan log eksekusi dipicu. Default: `2000`.
- `webhookToken`: token bearer yang digunakan untuk pengiriman POST webhook cron (`delivery.mode = "webhook"`), jika dihilangkan tidak ada header auth yang dikirim.
- `webhook`: URL webhook fallback warisan yang tidak digunakan lagi (http/https), hanya digunakan untuk pekerjaan tersimpan yang masih memiliki `notify: true`.
- `sessionRetention`: berapa lama menyimpan sesi run cron terisolasi yang selesai sebelum dipangkas dari `sessions.json`. Juga mengontrol pembersihan transkrip cron terhapus yang diarsipkan. Default: `24h`; atur `false` untuk menonaktifkan.
- `runLog.maxBytes`: ukuran maksimum per file log run (`cron/runs/<jobId>.jsonl`) sebelum pemangkasan. Default: `2_000_000` byte.
- `runLog.keepLines`: baris terbaru yang dipertahankan saat pemangkasan run-log dipicu. Default: `2000`.
- `webhookToken`: token bearer yang digunakan untuk pengiriman POST Webhook cron (`delivery.mode = "webhook"`), jika dihilangkan tidak ada header autentikasi yang dikirim.
- `webhook`: URL Webhook fallback legacy yang deprecated (http/https) yang hanya digunakan untuk job tersimpan yang masih memiliki `notify: true`.
### `cron.retry`
@ -1153,11 +1161,11 @@ Build saat ini tidak lagi menyertakan bridge TCP. Node terhubung melalui WebSock
}
```
- `maxAttempts`: percobaan ulang maksimum untuk pekerjaan sekali jalan pada kesalahan sementara (bawaan: `3`; rentang: `0`–`10`).
- `backoffMs`: array jeda backoff dalam ms untuk setiap percobaan ulang (bawaan: `[30000, 60000, 300000]`; 1–10 entri).
- `retryOn`: jenis kesalahan yang memicu percobaan ulang — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Hilangkan untuk mencoba ulang semua jenis sementara.
- `maxAttempts`: jumlah percobaan ulang maksimum untuk job sekali jalan pada error sementara (default: `3`; rentang: `0`–`10`).
- `backoffMs`: array jeda backoff dalam ms untuk setiap percobaan ulang (default: `[30000, 60000, 300000]`; 1–10 entri).
- `retryOn`: jenis error yang memicu percobaan ulang — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Abaikan untuk mencoba ulang semua jenis sementara.
Berlaku hanya untuk pekerjaan cron sekali jalan. Pekerjaan berulang menggunakan penanganan kegagalan terpisah.
Hanya berlaku untuk job Cron sekali jalan. Job berulang menggunakan penanganan kegagalan terpisah.
### `cron.failureAlert`
@ -1176,12 +1184,12 @@ Berlaku hanya untuk pekerjaan cron sekali jalan. Pekerjaan berulang menggunakan
}
```
- `enabled`: aktifkan peringatan kegagalan untuk pekerjaan cron (bawaan: `false`).
- `after`: kegagalan berturut-turut sebelum peringatan dipicu (bilangan bulat positif, min: `1`).
- `cooldownMs`: milidetik minimum di antara peringatan berulang untuk pekerjaan yang sama (bilangan bulat non-negatif).
- `includeSkipped`: hitung eksekusi yang dilewati secara berturut-turut terhadap ambang peringatan (bawaan: `false`). Eksekusi yang dilewati dilacak secara terpisah dan tidak memengaruhi backoff kesalahan eksekusi.
- `mode`: mode pengiriman — `"announce"` mengirim melalui pesan channel; `"webhook"` memposting ke Webhook yang dikonfigurasi.
- `accountId`: akun atau id channel opsional untuk membatasi cakupan pengiriman peringatan.
- `enabled`: aktifkan peringatan kegagalan untuk job Cron (default: `false`).
- `after`: kegagalan beruntun sebelum peringatan dipicu (bilangan bulat positif, min: `1`).
- `cooldownMs`: milidetik minimum antara peringatan berulang untuk job yang sama (bilangan bulat non-negatif).
- `includeSkipped`: hitung run yang dilewati secara beruntun ke ambang peringatan (default: `false`). Run yang dilewati dilacak terpisah dan tidak memengaruhi backoff error eksekusi.
- `mode`: mode pengiriman — `"announce"` mengirim melalui pesan kanal; `"webhook"` memposting ke Webhook yang dikonfigurasi.
- `accountId`: id akun atau kanal opsional untuk membatasi cakupan pengiriman peringatan.
### `cron.failureDestination`
@ -1198,51 +1206,51 @@ Berlaku hanya untuk pekerjaan cron sekali jalan. Pekerjaan berulang menggunakan
}
```
- Tujuan bawaan untuk notifikasi kegagalan cron di semua pekerjaan.
- `mode`: `"announce"` atau `"webhook"`; bawaan ke `"announce"` ketika data target yang cukup tersedia.
- `channel`: penggantian channel untuk pengiriman announce. `"last"` menggunakan kembali channel pengiriman terakhir yang diketahui.
- Tujuan default untuk notifikasi kegagalan Cron di semua job.
- `mode`: `"announce"` atau `"webhook"`; default ke `"announce"` saat data target cukup tersedia.
- `channel`: override kanal untuk pengiriman announce. `"last"` menggunakan kembali kanal pengiriman terakhir yang diketahui.
- `to`: target announce eksplisit atau URL Webhook. Wajib untuk mode Webhook.
- `accountId`: penggantian akun opsional untuk pengiriman.
- `delivery.failureDestination` per pekerjaan menggantikan bawaan global ini.
- Ketika tujuan kegagalan global maupun per pekerjaan tidak ditetapkan, pekerjaan yang sudah mengirim melalui `announce` kembali menggunakan target announce utama tersebut saat gagal.
- `delivery.failureDestination` hanya didukung untuk pekerjaan `sessionTarget="isolated"` kecuali `delivery.mode` utama pekerjaan adalah `"webhook"`.
- `accountId`: override akun opsional untuk pengiriman.
- `delivery.failureDestination` per job menggantikan default global ini.
- Saat tujuan kegagalan global maupun per job tidak diatur, job yang sudah mengirim melalui `announce` akan fallback ke target announce utama tersebut saat gagal.
- `delivery.failureDestination` hanya didukung untuk job `sessionTarget="isolated"` kecuali `delivery.mode` utama job adalah `"webhook"`.
Lihat [Pekerjaan Cron](/id/automation/cron-jobs). Eksekusi cron terisolasi dilacak sebagai [tugas latar belakang](/id/automation/tasks).
Lihat [Job Cron](/id/automation/cron-jobs). Eksekusi Cron terisolasi dilacak sebagai [tugas latar belakang](/id/automation/tasks).
---
## Variabel templat model media
Placeholder templat diperluas di `tools.media.models[].args`:
Placeholder templat yang diperluas di `tools.media.models[].args`:
| Variabel | Deskripsi |
| ------------------ | ------------------------------------------------- |
| `{{Body}}` | Isi lengkap pesan masuk |
| `{{Body}}` | Isi pesan masuk lengkap |
| `{{RawBody}}` | Isi mentah (tanpa pembungkus riwayat/pengirim) |
| `{{BodyStripped}}` | Isi dengan mention grup dihapus |
| `{{From}}` | Pengidentifikasi pengirim |
| `{{To}}` | Pengidentifikasi tujuan |
| `{{MessageSid}}` | id pesan channel |
| `{{MessageSid}}` | id pesan kanal |
| `{{SessionId}}` | UUID sesi saat ini |
| `{{IsNewSession}}` | `"true"` ketika sesi baru dibuat |
| `{{MediaUrl}}` | URL semu media masuk |
| `{{IsNewSession}}` | `"true"` saat sesi baru dibuat |
| `{{MediaUrl}}` | Pseudo-URL media masuk |
| `{{MediaPath}}` | Path media lokal |
| `{{MediaType}}` | Jenis media (gambar/audio/dokumen/…) |
| `{{Transcript}}` | Transkrip audio |
| `{{Prompt}}` | Prompt media yang diselesaikan untuk entri CLI |
| `{{MaxChars}}` | Karakter output maks yang diselesaikan untuk entri CLI |
| `{{MaxChars}}` | Karakter output maksimum yang diselesaikan untuk entri CLI |
| `{{ChatType}}` | `"direct"` atau `"group"` |
| `{{GroupSubject}}` | Subjek grup (upaya terbaik) |
| `{{GroupMembers}}` | Pratinjau anggota grup (upaya terbaik) |
| `{{SenderName}}` | Nama tampilan pengirim (upaya terbaik) |
| `{{SenderE164}}` | Nomor telepon pengirim (upaya terbaik) |
| `{{Provider}}` | Petunjuk provider (whatsapp, telegram, discord, dll.) |
| `{{Provider}}` | Petunjuk penyedia (whatsapp, telegram, discord, dll.) |
---
## Penyertaan konfigurasi (`$include`)
Pisahkan konfigurasi ke beberapa file:
Pecah konfigurasi menjadi beberapa file:
```json5
// ~/.openclaw/openclaw.json
@ -1255,16 +1263,16 @@ Pisahkan konfigurasi ke beberapa file:
}
```
**Perilaku penggabungan:**
**Perilaku merge:**
- Satu file: menggantikan objek yang memuatnya.
- Array file: digabung mendalam sesuai urutan (yang belakangan menggantikan yang sebelumnya).
- Kunci saudara: digabung setelah penyertaan (mengganti nilai yang disertakan).
- Penyertaan bersarang: hingga 10 tingkat.
- Path: diselesaikan relatif terhadap file yang menyertakan, tetapi harus tetap berada di dalam direktori konfigurasi tingkat atas (`dirname` dari `openclaw.json`). Bentuk absolut/`../` diizinkan hanya ketika tetap terselesaikan di dalam batas tersebut.
- Penulisan milik OpenClaw yang hanya mengubah satu bagian tingkat atas yang didukung oleh penyertaan satu file ditulis langsung ke file yang disertakan tersebut. Misalnya, `plugins install` memperbarui `plugins: { $include: "./plugins.json5" }` di `plugins.json5` dan membiarkan `openclaw.json` tetap utuh.
- Penyertaan root, array penyertaan, dan penyertaan dengan penggantian kunci saudara bersifat hanya-baca untuk penulisan milik OpenClaw; penulisan tersebut gagal tertutup alih-alih meratakan konfigurasi.
- Kesalahan: pesan jelas untuk file yang hilang, kesalahan parsing, dan penyertaan melingkar.
- Satu file: mengganti objek yang memuatnya.
- Array file: di-deep-merge sesuai urutan (yang lebih akhir menggantikan yang lebih awal).
- Kunci sibling: digabung setelah include (menggantikan nilai yang disertakan).
- Include bertingkat: hingga kedalaman 10 level.
- Path: diselesaikan relatif terhadap file yang menyertakan, tetapi harus tetap berada di dalam direktori konfigurasi tingkat atas (`dirname` dari `openclaw.json`). Bentuk absolut/`../` hanya diizinkan saat masih terselesaikan di dalam batas tersebut.
- Penulisan milik OpenClaw yang hanya mengubah satu bagian tingkat atas yang didukung oleh include satu file menulis langsung ke file yang disertakan itu. Misalnya, `plugins install` memperbarui `plugins: { $include: "./plugins.json5" }` di `plugins.json5` dan membiarkan `openclaw.json` tetap utuh.
- Include root, array include, dan include dengan override sibling bersifat hanya-baca untuk penulisan milik OpenClaw; penulisan tersebut gagal tertutup alih-alih meratakan konfigurasi.
- Error: pesan yang jelas untuk file yang hilang, error parsing, dan include melingkar.
---

97
docs/id/gateway/diagnostics.md
View File

@ -1,22 +1,22 @@
---
read_when:
- Menyiapkan laporan bug atau permintaan dukungan
- Men-debug kegagalan, mulai ulang, tekanan memori, atau muatan yang terlalu besar pada Gateway
- Meninjau data diagnostik apa yang dicatat atau disamarkan
- Men-debug kegagalan Gateway, mulai ulang, tekanan memori, atau muatan berukuran terlalu besar
- Meninjau data diagnostik mana yang direkam atau diredaksi
summary: Buat bundel diagnostik Gateway yang dapat dibagikan untuk laporan bug
title: Ekspor diagnostik
x-i18n:
generated_at: "2026-05-03T21:32:02Z"
generated_at: "2026-05-05T01:46:04Z"
model: gpt-5.5
provider: openai
source_hash: f6cf8e00fe8033e339b5c947ce3dd10fdee736048a358ad3a0c2ccb77e939f4b
source_hash: 56539280bc7a7868063328626e63b2576feb5578e2651d3a2976ee9c34243382
source_path: gateway/diagnostics.md
workflow: 16
---
OpenClaw dapat membuat zip diagnostik lokal untuk laporan bug. Zip ini menggabungkan
status Gateway yang sudah disanitasi, kesehatan, log, bentuk konfigurasi, dan
peristiwa stabilitas terbaru tanpa payload.
status Gateway, kesehatan, log, bentuk konfigurasi, dan peristiwa stabilitas
terbaru tanpa payload yang sudah disanitasi.
Perlakukan bundel diagnostik seperti rahasia sampai Anda meninjaunya. Bundel ini
dirancang untuk menghilangkan atau menyamarkan payload dan kredensial, tetapi
@ -34,7 +34,7 @@ Perintah ini mencetak path zip yang ditulis. Untuk memilih path:
openclaw gateway diagnostics export --output openclaw-diagnostics.zip
```
Untuk otomatisasi:
Untuk automasi:
```bash
openclaw gateway diagnostics export --json
@ -46,20 +46,20 @@ Pemilik dapat menggunakan `/diagnostics [note]` di chat untuk meminta ekspor Gat
Gunakan ini saat bug terjadi dalam percakapan nyata dan Anda menginginkan satu
laporan yang dapat disalin-tempel untuk dukungan:
1. Kirim `/diagnostics` dalam percakapan tempat Anda melihat masalah. Tambahkan
1. Kirim `/diagnostics` dalam percakapan tempat Anda melihat masalahnya. Tambahkan
catatan singkat jika membantu, misalnya `/diagnostics bad tool choice`.
2. OpenClaw mengirim pembuka diagnostik dan meminta satu persetujuan exec
eksplisit. Persetujuan menjalankan `openclaw gateway diagnostics export --json`.
Jangan setujui diagnostik melalui aturan izinkan-semua.
3. Setelah disetujui, OpenClaw membalas dengan laporan yang dapat ditempel berisi
path bundel lokal, ringkasan manifes, catatan privasi, dan id sesi yang relevan.
2. OpenClaw mengirim pembuka diagnostik dan meminta satu persetujuan exec eksplisit.
Persetujuan tersebut menjalankan `openclaw gateway diagnostics export --json`.
Jangan menyetujui diagnostik melalui aturan izinkan-semua.
3. Setelah disetujui, OpenClaw membalas dengan laporan yang dapat ditempel berisi path
bundel lokal, ringkasan manifes, catatan privasi, dan id sesi yang relevan.
Dalam chat grup, pemilik masih dapat menjalankan `/diagnostics`, tetapi OpenClaw tidak
memposting detail diagnostik kembali ke chat bersama. OpenClaw mengirim pembuka,
prompt persetujuan, hasil ekspor Gateway, dan rincian sesi/thread Codex kepada
pemilik melalui rute persetujuan privat. Grup hanya mendapat pemberitahuan singkat
Dalam chat grup, pemilik tetap dapat menjalankan `/diagnostics`, tetapi OpenClaw tidak
mengirim detail diagnostik kembali ke chat bersama. OpenClaw mengirim pembuka,
prompt persetujuan, hasil ekspor Gateway, dan perincian sesi/thread Codex kepada
pemilik melalui rute persetujuan privat. Grup hanya menerima pemberitahuan singkat
bahwa alur diagnostik dikirim secara privat. Jika OpenClaw tidak dapat menemukan rute
pemilik privat, perintah gagal tertutup dan meminta pemilik menjalankannya dari DM.
pemilik privat, perintah gagal secara tertutup dan meminta pemilik menjalankannya dari DM.
Saat sesi OpenClaw aktif menggunakan harness OpenAI Codex native,
persetujuan exec yang sama juga mencakup unggahan umpan balik OpenAI untuk thread
@ -72,29 +72,29 @@ yang dikirim ke server OpenAI. Jika Anda menolak atau mengabaikan persetujuan,
OpenClaw tidak menjalankan ekspor, tidak mengirim umpan balik Codex, dan tidak
mencetak id Codex.
Itu membuat loop debugging Codex yang umum menjadi singkat: lihat perilaku buruk di
Itu membuat loop debugging Codex umum menjadi singkat: lihat perilaku buruk di
Telegram, Discord, atau channel lain, jalankan `/diagnostics`, setujui sekali, bagikan
laporan kepada dukungan, lalu jalankan perintah `codex resume <thread-id>` yang dicetak
laporan dengan dukungan, lalu jalankan perintah `codex resume <thread-id>` yang dicetak
secara lokal jika Anda ingin memeriksa sendiri thread Codex native. Lihat
[Harness Codex](/id/plugins/codex-harness#inspect-a-codex-thread-from-the-cli) untuk
[harness Codex](/id/plugins/codex-harness#inspect-a-codex-thread-from-the-cli) untuk
alur kerja pemeriksaan tersebut.
## Isi ekspor
Zip mencakup:
- `summary.md`: ikhtisar yang mudah dibaca manusia untuk dukungan.
- `summary.md`: ikhtisar yang dapat dibaca manusia untuk dukungan.
- `diagnostics.json`: ringkasan yang dapat dibaca mesin tentang konfigurasi, log, status, kesehatan,
dan data stabilitas.
- `manifest.json`: metadata ekspor dan daftar file.
- Bentuk konfigurasi yang disanitasi dan detail konfigurasi non-rahasia.
- Ringkasan log yang disanitasi dan baris log terbaru yang disunting.
- Bentuk konfigurasi yang disanitasi dan detail konfigurasi nonrahasia.
- Ringkasan log yang disanitasi dan baris log terbaru yang disamarkan.
- Snapshot status dan kesehatan Gateway upaya-terbaik.
- `stability/latest.json`: bundel stabilitas tersimpan terbaru, bila tersedia.
- `stability/latest.json`: bundel stabilitas tersimpan terbaru, jika tersedia.
Ekspor tetap berguna bahkan saat Gateway tidak sehat. Jika Gateway tidak dapat
menjawab permintaan status atau kesehatan, log lokal, bentuk konfigurasi, dan bundel
stabilitas terbaru tetap dikumpulkan bila tersedia.
Ekspor tetap berguna meski Gateway tidak sehat. Jika Gateway tidak dapat
menjawab permintaan status atau kesehatan, log lokal, bentuk konfigurasi, dan
bundel stabilitas terbaru tetap dikumpulkan jika tersedia.
## Model privasi
@ -103,18 +103,18 @@ yang membantu debugging, seperti:
- nama subsistem, id plugin, id penyedia, id channel, dan mode yang dikonfigurasi
- kode status, durasi, jumlah byte, status antrean, dan pembacaan memori
- metadata log yang disanitasi dan pesan operasional yang disunting
- bentuk konfigurasi dan pengaturan fitur non-rahasia
- metadata log yang disanitasi dan pesan operasional yang disamarkan
- bentuk konfigurasi dan pengaturan fitur nonrahasia
Ekspor menghilangkan atau menyamarkan:
- teks chat, prompt, instruksi, body webhook, dan output tool
- teks chat, prompt, instruksi, isi webhook, dan keluaran tool
- kredensial, kunci API, token, cookie, dan nilai rahasia
- body permintaan atau respons mentah
- isi permintaan atau respons mentah
- id akun, id pesan, id sesi mentah, hostname, dan nama pengguna lokal
Saat pesan log tampak seperti teks pengguna, chat, prompt, atau payload tool,
ekspor hanya mempertahankan bahwa sebuah pesan dihilangkan dan jumlah byte.
ekspor hanya mempertahankan bahwa sebuah pesan dihilangkan beserta jumlah byte-nya.
## Perekam stabilitas
@ -122,14 +122,21 @@ Gateway merekam stream stabilitas terbatas tanpa payload secara default saat
diagnostik diaktifkan. Ini untuk fakta operasional, bukan konten.
Heartbeat diagnostik yang sama merekam sampel liveness saat Gateway tetap
berjalan tetapi event loop Node.js atau CPU tampak jenuh. Peristiwa
`diagnostic.liveness.warning` ini mencakup keterlambatan event-loop, utilisasi
event-loop, rasio core CPU, dan jumlah sesi aktif/menunggu/antre. Sampel idle
tetap berada di telemetri pada level `info`. Sampel liveness menjadi peringatan
Gateway hanya saat pekerjaan menunggu atau mengantre, atau saat pekerjaan aktif
tumpang tindih dengan keterlambatan event-loop yang berkelanjutan. Lonjakan
max-delay sementara selama pekerjaan latar belakang yang sehat tetap berada di
log debug. Peristiwa itu tidak memulai ulang Gateway dengan sendirinya.
berjalan tetapi event loop Node.js atau CPU terlihat jenuh. Peristiwa
`diagnostic.liveness.warning` ini mencakup jeda event-loop, utilisasi event-loop,
rasio inti CPU, jumlah sesi aktif/menunggu/diantrekan, fase startup/runtime saat ini
jika diketahui, rentang fase terbaru, dan label kerja aktif/diantrekan yang dibatasi.
Sampel idle tetap berada di telemetri pada level `info`. Sampel liveness menjadi
peringatan Gateway hanya saat ada pekerjaan yang menunggu atau diantrekan, atau
saat pekerjaan aktif bertumpang tindih dengan jeda event-loop berkelanjutan. Lonjakan
max-delay sementara selama pekerjaan latar belakang yang sehat tetap berada di log
debug. Lonjakan itu tidak me-restart Gateway dengan sendirinya.
Fase startup juga memancarkan peristiwa `diagnostic.phase.completed` dengan timing
wall-clock dan CPU. Diagnostik embedded-run yang macet menandai
`terminalProgressStale=true` saat progres bridge terakhir tampak terminal, seperti
item respons mentah atau peristiwa penyelesaian respons, tetapi Gateway masih
menganggap embedded run aktif.
Periksa perekam live:
@ -139,7 +146,7 @@ openclaw gateway stability --type payload.large
openclaw gateway stability --json
```
Periksa bundel stabilitas tersimpan terbaru setelah exit fatal, timeout shutdown,
Periksa bundel stabilitas tersimpan terbaru setelah keluar fatal, timeout shutdown,
atau kegagalan startup restart:
```bash
@ -152,7 +159,7 @@ Buat zip diagnostik dari bundel tersimpan terbaru:
openclaw gateway stability --bundle latest --export
```
Bundel tersimpan berada di bawah `~/.openclaw/logs/stability/` saat peristiwa ada.
Bundel tersimpan berada di bawah `~/.openclaw/logs/stability/` saat ada peristiwa.
## Opsi berguna
@ -164,11 +171,11 @@ openclaw gateway diagnostics export \
```
- `--output <path>`: tulis ke path zip tertentu.
- `--log-lines <count>`: jumlah maksimum baris log yang disanitasi untuk disertakan.
- `--log-lines <count>`: jumlah maksimum baris log tersanitasi yang disertakan.
- `--log-bytes <bytes>`: byte log maksimum untuk diperiksa.
- `--url <url>`: URL WebSocket Gateway untuk snapshot status dan kesehatan.
- `--token <token>`: token Gateway untuk snapshot status dan kesehatan.
- `--password <password>`: kata sandi Gateway untuk snapshot status dan kesehatan.
- `--password <password>`: sandi Gateway untuk snapshot status dan kesehatan.
- `--timeout <ms>`: timeout snapshot status dan kesehatan.
- `--no-stability-bundle`: lewati pencarian bundel stabilitas tersimpan.
- `--json`: cetak metadata ekspor yang dapat dibaca mesin.

370
docs/id/gateway/doctor.md
View File

@ -1,15 +1,15 @@
---
read_when:
- Menambahkan atau memodifikasi migrasi doctor
- Memperkenalkan perubahan konfigurasi yang merusak kompatibilitas
- Menambahkan atau mengubah migrasi doctor
- Memperkenalkan perubahan konfigurasi yang tidak kompatibel
sidebarTitle: Doctor
summary: 'Perintah doctor: pemeriksaan kesehatan, migrasi konfigurasi, dan langkah perbaikan'
title: Dokter
x-i18n:
generated_at: "2026-05-04T09:33:29Z"
generated_at: "2026-05-05T01:45:59Z"
model: gpt-5.5
provider: openai
source_hash: 1bc8615f5e49e8c20785a9dc9779c447fd0d5794c80663d2396b0a20b4187798
source_hash: 3e374f91d00d4b43a3852de6f746b044471e80af936d464a789061a31cadd09d
source_path: gateway/doctor.md
workflow: 16
---
@ -30,7 +30,7 @@ openclaw doctor
openclaw doctor --yes
```
Terima default tanpa prompt (termasuk langkah perbaikan restart/layanan/sandbox saat berlaku).
Terima default tanpa meminta konfirmasi (termasuk langkah perbaikan restart/service/sandbox bila berlaku).
</Tab>
<Tab title="--repair">
@ -38,7 +38,7 @@ openclaw doctor
openclaw doctor --repair
```
Terapkan perbaikan yang direkomendasikan tanpa prompt (perbaikan + restart jika aman).
Terapkan perbaikan yang direkomendasikan tanpa meminta konfirmasi (perbaikan + restart jika aman).
</Tab>
<Tab title="--repair --force">
@ -46,7 +46,7 @@ openclaw doctor
openclaw doctor --repair --force
```
Terapkan juga perbaikan agresif (menimpa konfigurasi supervisor kustom).
Terapkan juga perbaikan agresif (menimpa konfigurasi supervisor khusus).
</Tab>
<Tab title="--non-interactive">
@ -54,7 +54,7 @@ openclaw doctor
openclaw doctor --non-interactive
```
Jalankan tanpa prompt dan hanya terapkan migrasi yang aman (normalisasi konfigurasi + pemindahan status di disk). Melewati tindakan restart/layanan/sandbox yang memerlukan konfirmasi manusia. Migrasi status lama berjalan otomatis saat terdeteksi.
Jalankan tanpa prompt dan hanya terapkan migrasi aman (normalisasi konfigurasi + pemindahan status di disk). Melewati tindakan restart/service/sandbox yang memerlukan konfirmasi manusia. Migrasi status lama berjalan otomatis saat terdeteksi.
</Tab>
<Tab title="--deep">
@ -62,7 +62,7 @@ openclaw doctor
openclaw doctor --deep
```
Pindai layanan sistem untuk instalasi gateway tambahan (launchd/systemd/schtasks).
Pindai service sistem untuk instalasi gateway tambahan (launchd/systemd/schtasks).
</Tab>
</Tabs>
@ -78,61 +78,61 @@ cat ~/.openclaw/openclaw.json
<AccordionGroup>
<Accordion title="Kesehatan, UI, dan pembaruan">
- Pembaruan pra-jalan opsional untuk instalasi git (hanya interaktif).
- Pemeriksaan kebaruan protokol UI (membangun ulang UI Kontrol saat skema protokol lebih baru).
- Pemeriksaan kesegaran protokol UI (membangun ulang UI Kontrol saat skema protokol lebih baru).
- Pemeriksaan kesehatan + prompt restart.
- Ringkasan status Skills (memenuhi syarat/hilang/diblokir) dan status Plugin.
- Ringkasan status Skills (memenuhi syarat/hilang/diblokir) dan status plugin.
</Accordion>
<Accordion title="Konfigurasi dan migrasi">
- Normalisasi konfigurasi untuk nilai lama.
- Migrasi konfigurasi Talk dari bidang datar lama `talk.*` ke `talk.provider` + `talk.providers.<provider>`.
- Pemeriksaan migrasi browser untuk konfigurasi ekstensi Chrome lama dan kesiapan Chrome MCP.
- Migrasi konfigurasi Talk dari field datar `talk.*` lama ke `talk.provider` + `talk.providers.<provider>`.
- Pemeriksaan migrasi browser untuk konfigurasi Chrome extension lama dan kesiapan Chrome MCP.
- Peringatan override penyedia OpenCode (`models.providers.opencode` / `models.providers.opencode-go`).
- Peringatan shadowing OAuth Codex (`models.providers.openai-codex`).
- Pemeriksaan prasyarat TLS OAuth untuk profil OAuth OpenAI Codex.
- Peringatan allowlist Plugin/alat saat `plugins.allow` bersifat membatasi tetapi kebijakan alat masih meminta wildcard atau alat milik Plugin.
- Migrasi status lama di disk (sessions/agent dir/autentikasi WhatsApp).
- Migrasi kunci kontrak manifes Plugin lama (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
- Migrasi penyimpanan Cron lama (`jobId`, `schedule.cron`, bidang delivery/payload tingkat atas, payload `provider`, pekerjaan fallback Webhook sederhana `notify: true`).
- Migrasi kebijakan runtime agen lama ke `agents.defaults.agentRuntime` dan `agents.list[].agentRuntime`.
- Pembersihan konfigurasi Plugin usang saat Plugin diaktifkan; saat `plugins.enabled=false`, referensi Plugin usang diperlakukan sebagai konfigurasi containment inert dan dipertahankan.
- Peringatan bayangan OAuth Codex (`models.providers.openai-codex`).
- Pemeriksaan prasyarat OAuth TLS untuk profil OAuth OpenAI Codex.
- Peringatan allowlist plugin/alat saat `plugins.allow` bersifat membatasi tetapi kebijakan alat masih meminta wildcard atau alat milik plugin.
- Migrasi status lama di disk (sessions/agent dir/auth WhatsApp).
- Migrasi kunci kontrak manifest plugin lama (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
- Migrasi penyimpanan Cron lama (`jobId`, `schedule.cron`, field delivery/payload tingkat atas, payload `provider`, job fallback webhook sederhana `notify: true`).
- Migrasi runtime-policy agent lama ke `agents.defaults.agentRuntime` dan `agents.list[].agentRuntime`.
- Pembersihan konfigurasi plugin usang saat plugin diaktifkan; saat `plugins.enabled=false`, referensi plugin usang diperlakukan sebagai konfigurasi kontainmen inert dan dipertahankan.
</Accordion>
<Accordion title="Status dan integritas">
- Inspeksi file kunci sesi dan pembersihan kunci usang.
- Inspeksi file lock sesi dan pembersihan lock usang.
- Perbaikan transkrip sesi untuk cabang prompt-rewrite duplikat yang dibuat oleh build 2026.4.24 yang terdampak.
- Deteksi tombstone pemulihan-restart subagen yang macet, dengan dukungan `--fix` untuk menghapus flag pemulihan abort usang agar startup tidak terus memperlakukan child sebagai restart-aborted.
- Pemeriksaan integritas status dan izin (sesi, transkrip, direktori status).
- Deteksi tombstone restart-recovery subagent yang macet, dengan dukungan `--fix` untuk membersihkan flag pemulihan dibatalkan yang usang agar startup tidak terus memperlakukan child sebagai restart-aborted.
- Pemeriksaan integritas status dan izin (sessions, transcripts, state dir).
- Pemeriksaan izin file konfigurasi (chmod 600) saat berjalan secara lokal.
- Kesehatan autentikasi model: memeriksa kedaluwarsa OAuth, dapat menyegarkan token yang hampir kedaluwarsa, dan melaporkan status cooldown/dinonaktifkan auth-profile.
- Deteksi direktori workspace tambahan (`~/openclaw`).
- Kesehatan auth model: memeriksa kedaluwarsa OAuth, dapat menyegarkan token yang hampir kedaluwarsa, dan melaporkan status cooldown/dinonaktifkan auth-profile.
- Deteksi dir workspace tambahan (`~/openclaw`).
</Accordion>
<Accordion title="Gateway, layanan, dan supervisor">
<Accordion title="Gateway, service, dan supervisor">
- Perbaikan image sandbox saat sandboxing diaktifkan.
- Migrasi layanan lama dan deteksi gateway tambahan.
- Migrasi service lama dan deteksi gateway tambahan.
- Migrasi status lama channel Matrix (dalam mode `--fix` / `--repair`).
- Pemeriksaan runtime Gateway (layanan terpasang tetapi tidak berjalan; label launchd yang di-cache).
- Peringatan status channel (di-probe dari gateway yang sedang berjalan).
- Pemeriksaan runtime Gateway (service terinstal tetapi tidak berjalan; label launchd yang di-cache).
- Peringatan status channel (diprobe dari gateway yang sedang berjalan).
- Audit konfigurasi supervisor (launchd/systemd/schtasks) dengan perbaikan opsional.
- Pembersihan lingkungan proxy tertanam untuk layanan gateway yang menangkap nilai shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` selama instalasi atau pembaruan.
- Pemeriksaan praktik terbaik runtime Gateway (Node vs Bun, path version-manager).
- Diagnostik tabrakan port Gateway (default `18789`).
- Pembersihan lingkungan proxy tertanam untuk service gateway yang menangkap nilai shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` selama instalasi atau pembaruan.
- Pemeriksaan praktik terbaik runtime Gateway (Node vs Bun, jalur version-manager).
- Diagnostik konflik port Gateway (default `18789`).
</Accordion>
<Accordion title="Autentikasi, keamanan, dan pemasangan">
<Accordion title="Auth, keamanan, dan pairing">
- Peringatan keamanan untuk kebijakan DM terbuka.
- Pemeriksaan autentikasi Gateway untuk mode token lokal (menawarkan pembuatan token saat tidak ada sumber token; tidak menimpa konfigurasi SecretRef token).
- Deteksi masalah pemasangan perangkat (permintaan pemasangan pertama kali yang tertunda, peningkatan peran/cakupan yang tertunda, drift cache token perangkat lokal yang usang, dan drift autentikasi catatan terpasang).
- Pemeriksaan auth Gateway untuk mode token lokal (menawarkan pembuatan token saat tidak ada sumber token; tidak menimpa konfigurasi token SecretRef).
- Deteksi masalah pairing perangkat (permintaan pair pertama kali yang tertunda, peningkatan peran/cakupan yang tertunda, drift cache device-token lokal yang usang, dan drift auth paired-record).
</Accordion>
<Accordion title="Workspace dan shell">
- Pemeriksaan systemd linger di Linux.
- Pemeriksaan ukuran file bootstrap workspace (peringatan pemotongan/hampir batas untuk file konteks).
- Pemeriksaan kesiapan Skills untuk agen default; melaporkan skill yang diizinkan dengan bin, env, konfigurasi, atau persyaratan OS yang hilang, dan `--fix` dapat menonaktifkan skill yang tidak tersedia di `skills.entries`.
- Pemeriksaan status shell completion dan pemasangan/peningkatan otomatis.
- Pemeriksaan kesiapan penyedia embedding pencarian memori (model lokal, kunci API jarak jauh, atau biner QMD).
- Pemeriksaan instalasi source (ketidakcocokan workspace pnpm, aset UI hilang, biner tsx hilang).
- Pemeriksaan kesiapan Skills untuk agent default; melaporkan skills yang diizinkan dengan bin, env, konfigurasi, atau persyaratan OS yang hilang, dan `--fix` dapat menonaktifkan skills yang tidak tersedia di `skills.entries`.
- Pemeriksaan status penyelesaian shell dan pemasangan/peningkatan otomatis.
- Pemeriksaan kesiapan penyedia embedding pencarian memori (model lokal, kunci API jarak jauh, atau binary QMD).
- Pemeriksaan instalasi sumber (ketidakcocokan workspace pnpm, aset UI hilang, binary tsx hilang).
- Menulis konfigurasi yang diperbarui + metadata wizard.
</Accordion>
@ -140,54 +140,57 @@ cat ~/.openclaw/openclaw.json
## Backfill dan reset UI Dreams
Adegan Dreams UI Kontrol mencakup tindakan **Backfill**, **Reset**, dan **Clear Grounded** untuk alur kerja dreaming grounded. Tindakan ini menggunakan metode RPC bergaya doctor gateway, tetapi **bukan** bagian dari perbaikan/migrasi CLI `openclaw doctor`.
Scene Dreams UI Kontrol menyertakan tindakan **Backfill**, **Reset**, dan **Clear Grounded** untuk alur kerja grounded Dreaming. Tindakan ini menggunakan metode RPC bergaya doctor gateway, tetapi tindakan tersebut **bukan** bagian dari perbaikan/migrasi CLI `openclaw doctor`.
Yang dilakukan:
- **Backfill** memindai file historis `memory/YYYY-MM-DD.md` di workspace aktif, menjalankan pass grounded REM diary, dan menulis entri backfill yang dapat dibalik ke `DREAMS.md`.
- **Reset** hanya menghapus entri diary backfill bertanda tersebut dari `DREAMS.md`.
- **Clear Grounded** hanya menghapus entri jangka pendek staged khusus grounded yang berasal dari pemutaran ulang historis dan belum mengakumulasi recall live atau dukungan harian.
- **Backfill** memindai file historis `memory/YYYY-MM-DD.md` di workspace aktif, menjalankan pass diary REM grounded, dan menulis entri backfill yang dapat dibalik ke `DREAMS.md`.
- **Reset** hanya menghapus entri diary backfill yang ditandai tersebut dari `DREAMS.md`.
- **Clear Grounded** hanya menghapus entri jangka pendek khusus grounded yang sudah di-stage, yang berasal dari replay historis dan belum mengakumulasi recall langsung atau dukungan harian.
Yang **tidak** dilakukan sendiri:
- tidak mengedit `MEMORY.md`
- tidak menjalankan migrasi doctor penuh
- tidak secara otomatis men-stage kandidat grounded ke penyimpanan promosi jangka pendek live kecuali Anda secara eksplisit menjalankan path CLI staged terlebih dahulu
- tindakan tersebut tidak mengedit `MEMORY.md`
- tindakan tersebut tidak menjalankan migrasi doctor penuh
- tindakan tersebut tidak otomatis men-stage kandidat grounded ke penyimpanan promosi jangka pendek live kecuali Anda secara eksplisit menjalankan jalur CLI staged terlebih dahulu
Jika Anda ingin pemutaran ulang historis grounded memengaruhi jalur promosi mendalam normal, gunakan alur CLI sebagai gantinya:
Jika Anda ingin replay historis grounded memengaruhi lane promosi mendalam normal, gunakan alur CLI sebagai gantinya:
```bash
openclaw memory rem-backfill --path ./memory --stage-short-term
```
Itu men-stage kandidat durable grounded ke penyimpanan dreaming jangka pendek sambil mempertahankan `DREAMS.md` sebagai permukaan peninjauan.
Perintah tersebut men-stage kandidat tahan lama grounded ke penyimpanan Dreaming jangka pendek sambil menjaga `DREAMS.md` sebagai permukaan tinjauan.
## Perilaku terperinci dan alasan
## Perilaku dan alasan terperinci
<AccordionGroup>
<Accordion title="0. Pembaruan opsional (instalasi git)">
Jika ini adalah checkout git dan doctor berjalan secara interaktif, ia menawarkan pembaruan (fetch/rebase/build) sebelum menjalankan doctor.
Jika ini adalah checkout git dan doctor berjalan secara interaktif, doctor menawarkan pembaruan (fetch/rebase/build) sebelum menjalankan doctor.
</Accordion>
<Accordion title="1. Normalisasi konfigurasi">
Jika konfigurasi berisi bentuk nilai lama (misalnya `messages.ackReaction` tanpa override khusus channel), doctor menormalkannya ke skema saat ini.
Jika konfigurasi berisi bentuk nilai lama (misalnya `messages.ackReaction` tanpa override khusus channel), doctor menormalisasinya ke skema saat ini.
Itu mencakup bidang datar Talk lama. Konfigurasi Talk publik saat ini adalah `talk.provider` + `talk.providers.<provider>`. Doctor menulis ulang bentuk lama `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` ke dalam peta penyedia.
Itu mencakup field datar Talk lama. Konfigurasi Talk publik saat ini adalah `talk.provider` + `talk.providers.<provider>`. Doctor menulis ulang bentuk `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` lama ke peta penyedia.
Doctor juga memperingatkan saat `plugins.allow` tidak kosong dan kebijakan alat menggunakan
entri wildcard atau alat milik Plugin. `tools.allow: ["*"]` hanya mencocokkan alat
dari Plugin yang benar-benar dimuat; itu tidak melewati allowlist Plugin eksklusif.
entri alat wildcard atau milik plugin. `tools.allow: ["*"]` hanya mencocokkan alat
dari plugin yang benar-benar dimuat; itu tidak melewati allowlist plugin eksklusif.
Doctor menulis `plugins.bundledDiscovery: "compat"` untuk konfigurasi allowlist
lama yang dimigrasikan demi mempertahankan perilaku penyedia bundled yang ada, lalu
mengarahkan ke pengaturan `"allowlist"` yang lebih ketat.
</Accordion>
<Accordion title="2. Migrasi kunci konfigurasi lama">
Saat konfigurasi berisi kunci yang tidak digunakan lagi, perintah lain menolak berjalan dan meminta Anda menjalankan `openclaw doctor`.
Saat konfigurasi berisi kunci yang tidak berlaku lagi, perintah lain menolak berjalan dan meminta Anda menjalankan `openclaw doctor`.
Doctor akan:
- Menjelaskan kunci lama mana yang ditemukan.
- Menampilkan migrasi yang diterapkannya.
- Menampilkan migrasi yang diterapkan.
- Menulis ulang `~/.openclaw/openclaw.json` dengan skema yang diperbarui.
Gateway juga menjalankan otomatis migrasi doctor saat startup ketika mendeteksi format konfigurasi lama, sehingga konfigurasi usang diperbaiki tanpa intervensi manual. Migrasi penyimpanan pekerjaan Cron ditangani oleh `openclaw doctor --fix`.
Gateway juga menjalankan otomatis migrasi doctor saat startup ketika mendeteksi format konfigurasi lama, sehingga konfigurasi usang diperbaiki tanpa intervensi manual. Migrasi penyimpanan job Cron ditangani oleh `openclaw doctor --fix`.
Migrasi saat ini:
@ -195,7 +198,8 @@ Itu men-stage kandidat durable grounded ke penyimpanan dreaming jangka pendek sa
- `routing.groupChat.requireMention` → `channels.whatsapp/telegram/imessage.groups."*".requireMention`
- `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit`
- `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns`
- konfigurasi configured-channel yang tidak memiliki kebijakan balasan terlihat → `messages.groupChat.visibleReplies: "message_tool"`
- `channels.telegram.requireMention` → `channels.telegram.groups."*".requireMention`
- konfigurasi kanal yang dikonfigurasi tidak memiliki kebijakan balasan terlihat → `messages.groupChat.visibleReplies: "message_tool"`
- `routing.queue` → `messages.queue`
- `routing.bindings` → `bindings` tingkat atas
- `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default`
@ -213,129 +217,135 @@ Itu men-stage kandidat durable grounded ke penyimpanan dreaming jangka pendek sa
- `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider`
- `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*`
- `bindings[].match.accountID` → `bindings[].match.accountId`
- Untuk channel dengan `accounts` bernama tetapi masih memiliki nilai channel tingkat atas akun tunggal, pindahkan nilai yang cakupannya akun itu ke akun yang dipromosikan yang dipilih untuk channel tersebut (`accounts.default` untuk sebagian besar channel; Matrix dapat mempertahankan target bernama/default yang cocok jika sudah ada)
- Untuk kanal dengan `accounts` bernama tetapi masih memiliki nilai kanal tingkat atas akun tunggal lama, pindahkan nilai bercakupan akun tersebut ke akun yang dipromosikan yang dipilih untuk kanal itu (`accounts.default` untuk sebagian besar kanal; Matrix dapat mempertahankan target bernama/default yang sudah ada dan cocok)
- `identity` → `agents.list[].identity`
- `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents)
- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
- hapus `agents.defaults.llm`; gunakan `models.providers.<id>.timeoutSeconds` untuk batas waktu provider/model yang lambat
- `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
- `browser.profiles.*.driver: "extension"` → `"existing-session"`
- hapus `browser.relayBindHost` (pengaturan relay extension lama)
- `models.providers.*.api: "openai"` lama → `"openai-completions"` (startup gateway juga melewati provider yang `api`-nya disetel ke nilai enum masa depan atau tidak dikenal, alih-alih gagal tertutup)
- hapus `browser.relayBindHost` (pengaturan relay ekstensi lama)
- `models.providers.*.api: "openai"` lama → `"openai-completions"` (startup Gateway juga melewati provider yang `api`-nya disetel ke nilai enum masa depan atau tidak dikenal, alih-alih gagal tertutup)
Peringatan doctor juga menyertakan panduan default akun untuk channel multi-akun:
Peringatan doctor juga mencakup panduan default akun untuk kanal multi-akun:
- Jika dua atau lebih entri `channels.<channel>.accounts` dikonfigurasi tanpa `channels.<channel>.defaultAccount` atau `accounts.default`, doctor memperingatkan bahwa routing cadangan dapat memilih akun yang tidak terduga.
- Jika dua atau lebih entri `channels.<channel>.accounts` dikonfigurasi tanpa `channels.<channel>.defaultAccount` atau `accounts.default`, doctor memperingatkan bahwa perutean fallback dapat memilih akun yang tidak terduga.
- Jika `channels.<channel>.defaultAccount` disetel ke ID akun yang tidak dikenal, doctor memperingatkan dan mencantumkan ID akun yang dikonfigurasi.
</Accordion>
<Accordion title="2b. OpenCode provider overrides">
Jika Anda menambahkan `models.providers.opencode`, `opencode-zen`, atau `opencode-go` secara manual, itu menimpa katalog OpenCode bawaan dari `@mariozechner/pi-ai`. Hal itu dapat memaksa model memakai API yang salah atau mengosongkan biaya. Doctor memperingatkan agar Anda dapat menghapus override dan memulihkan routing API + biaya per model.
<Accordion title="2b. Override provider OpenCode">
Jika Anda menambahkan `models.providers.opencode`, `opencode-zen`, atau `opencode-go` secara manual, itu akan menggantikan katalog OpenCode bawaan dari `@mariozechner/pi-ai`. Hal itu dapat memaksa model menggunakan API yang salah atau mengosongkan biaya. Doctor memperingatkan agar Anda dapat menghapus override dan memulihkan perutean API + biaya per model.
</Accordion>
<Accordion title="2c. Browser migration and Chrome MCP readiness">
Jika konfigurasi browser Anda masih menunjuk ke jalur extension Chrome yang telah dihapus, doctor menormalkannya ke model attach Chrome MCP lokal host saat ini:
<Accordion title="2c. Migrasi browser dan kesiapan Chrome MCP">
Jika konfigurasi browser Anda masih mengarah ke jalur ekstensi Chrome yang sudah dihapus, doctor menormalkannya ke model attach Chrome MCP host-lokal saat ini:
- `browser.profiles.*.driver: "extension"` menjadi `"existing-session"`
- `browser.relayBindHost` dihapus
Doctor juga mengaudit jalur Chrome MCP lokal host saat Anda menggunakan `defaultProfile: "user"` atau profil `existing-session` yang dikonfigurasi:
Doctor juga mengaudit jalur Chrome MCP host-lokal saat Anda menggunakan `defaultProfile: "user"` atau profil `existing-session` yang dikonfigurasi:
- memeriksa apakah Google Chrome terpasang di host yang sama untuk profil auto-connect default
- memeriksa versi Chrome yang terdeteksi dan memperingatkan jika versinya di bawah Chrome 144
- mengingatkan Anda untuk mengaktifkan remote debugging di halaman inspect browser (misalnya `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`, atau `edge://inspect/#remote-debugging`)
- memeriksa apakah Google Chrome terinstal pada host yang sama untuk profil koneksi otomatis default
- memeriksa versi Chrome yang terdeteksi dan memperingatkan ketika versinya di bawah Chrome 144
- mengingatkan Anda untuk mengaktifkan debugging jarak jauh di halaman inspeksi browser (misalnya `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`, atau `edge://inspect/#remote-debugging`)
Doctor tidak dapat mengaktifkan pengaturan sisi Chrome untuk Anda. Chrome MCP lokal host tetap memerlukan:
Doctor tidak dapat mengaktifkan pengaturan sisi Chrome untuk Anda. Chrome MCP host-lokal tetap memerlukan:
- browser berbasis Chromium 144+ pada host gateway/node
- browser berjalan secara lokal
- remote debugging diaktifkan di browser tersebut
- debugging jarak jauh diaktifkan di browser tersebut
- menyetujui prompt persetujuan attach pertama di browser
Kesiapan di sini hanya tentang prasyarat attach lokal. Existing-session mempertahankan batas rute Chrome MCP saat ini; rute lanjutan seperti `responsebody`, ekspor PDF, intersepsi unduhan, dan tindakan batch tetap memerlukan browser terkelola atau profil CDP mentah.
Kesiapan di sini hanya tentang prasyarat attach lokal. Existing-session mempertahankan batas rute Chrome MCP saat ini; rute lanjutan seperti `responsebody`, ekspor PDF, intersepsi unduhan, dan tindakan batch masih memerlukan browser terkelola atau profil CDP mentah.
Pemeriksaan ini **tidak** berlaku untuk Docker, sandbox, remote-browser, atau alur headless lainnya. Alur tersebut tetap menggunakan CDP mentah.
</Accordion>
<Accordion title="2d. OAuth TLS prerequisites">
<Accordion title="2d. Prasyarat TLS OAuth">
Saat profil OAuth OpenAI Codex dikonfigurasi, doctor memeriksa endpoint otorisasi OpenAI untuk memverifikasi bahwa stack TLS Node/OpenSSL lokal dapat memvalidasi rantai sertifikat. Jika pemeriksaan gagal dengan kesalahan sertifikat (misalnya `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, sertifikat kedaluwarsa, atau sertifikat self-signed), doctor mencetak panduan perbaikan khusus platform. Di macOS dengan Node Homebrew, perbaikannya biasanya `brew postinstall ca-certificates`. Dengan `--deep`, pemeriksaan berjalan meskipun gateway sehat.
</Accordion>
<Accordion title="2e. Codex OAuth provider overrides">
Jika sebelumnya Anda menambahkan pengaturan transport OpenAI lama di bawah `models.providers.openai-codex`, pengaturan itu dapat membayangi jalur provider OAuth Codex bawaan yang digunakan rilis yang lebih baru secara otomatis. Doctor memperingatkan saat melihat pengaturan transport lama tersebut berdampingan dengan OAuth Codex agar Anda dapat menghapus atau menulis ulang override transport usang dan mendapatkan kembali perilaku routing/cadangan bawaan. Proxy kustom dan override hanya-header tetap didukung dan tidak memicu peringatan ini.
<Accordion title="2e. Override provider OAuth Codex">
Jika sebelumnya Anda menambahkan pengaturan transport OpenAI lama di bawah `models.providers.openai-codex`, pengaturan tersebut dapat membayangi jalur provider OAuth Codex bawaan yang digunakan otomatis oleh rilis yang lebih baru. Doctor memperingatkan saat melihat pengaturan transport lama tersebut bersama OAuth Codex agar Anda dapat menghapus atau menulis ulang override transport yang usang dan mendapatkan kembali perilaku perutean/fallback bawaan. Proksi kustom dan override khusus header tetap didukung dan tidak memicu peringatan ini.
</Accordion>
<Accordion title="2f. Codex plugin route warnings">
Saat Plugin Codex bawaan diaktifkan, doctor juga memeriksa apakah referensi model utama `openai-codex/*` masih diselesaikan melalui runner PI default. Kombinasi itu valid saat Anda menginginkan autentikasi OAuth/langganan Codex melalui PI, tetapi mudah tertukar dengan harness app-server Codex native. Doctor memperingatkan dan menunjuk ke bentuk app-server eksplisit: `openai/*` plus `agentRuntime.id: "codex"` atau `OPENCLAW_AGENT_RUNTIME=codex`.
<Accordion title="2f. Peringatan rute Plugin Codex">
Saat Plugin Codex bawaan diaktifkan, doctor juga memeriksa apakah ref model utama `openai-codex/*` masih di-resolve melalui runner PI default. Kombinasi itu valid ketika Anda menginginkan auth OAuth/langganan Codex melalui PI, tetapi mudah tertukar dengan harness app-server Codex native. Doctor memperingatkan dan menunjuk ke bentuk app-server eksplisit: `openai/*` plus `agentRuntime.id: "codex"` atau `OPENCLAW_AGENT_RUNTIME=codex`.
Doctor tidak memperbaikinya secara otomatis karena kedua rute valid:
Doctor tidak memperbaiki ini secara otomatis karena kedua rute valid:
- `openai-codex/*` + PI berarti "gunakan autentikasi OAuth/langganan Codex melalui runner OpenClaw normal."
- `openai/*` + `agentRuntime.id: "codex"` berarti "jalankan turn tertanam melalui app-server Codex native."
- `/codex ...` berarti "kontrol atau bind percakapan Codex native dari chat."
- `openai/*` + `agentRuntime.id: "codex"` berarti "jalankan turn tersemat melalui app-server Codex native."
- `/codex ...` berarti "kontrol atau kaitkan percakapan Codex native dari chat."
- `/acp ...` atau `runtime: "acp"` berarti "gunakan adapter ACP/acpx eksternal."
Jika peringatan muncul, pilih rute yang Anda maksud dan edit konfigurasi secara manual. Pertahankan peringatan apa adanya saat OAuth PI Codex memang disengaja.
Jika peringatan muncul, pilih rute yang Anda maksud dan edit konfigurasi secara manual. Pertahankan peringatan apa adanya ketika OAuth PI Codex memang disengaja.
</Accordion>
<Accordion title="3. Legacy state migrations (disk layout)">
<Accordion title="2g. Pembersihan rute sesi">
Doctor juga memindai penyimpanan sesi aktif untuk status rute lama yang dibuat otomatis setelah Anda memindahkan model atau runtime default/fallback yang dikonfigurasi dari rute milik Plugin seperti Codex.
`openclaw doctor --fix` dapat menghapus status lama yang dibuat otomatis seperti pin model `modelOverrideSource: "auto"`, metadata model runtime, id harness yang dipin, binding sesi CLI, dan override profil autentikasi otomatis ketika rute pemiliknya tidak lagi dikonfigurasi. Pilihan model sesi eksplisit dari pengguna atau legacy dilaporkan untuk ditinjau manual dan dibiarkan apa adanya; ganti dengan `/model ...`, `/new`, atau reset sesi ketika rute tersebut tidak lagi dimaksudkan.
</Accordion>
<Accordion title="3. Migrasi status legacy (tata letak disk)">
Doctor dapat memigrasikan tata letak lama di disk ke struktur saat ini:
- Penyimpanan sesi + transkrip:
- dari `~/.openclaw/sessions/` ke `~/.openclaw/agents/<agentId>/sessions/`
- Direktori agent:
- Direktori agen:
- dari `~/.openclaw/agent/` ke `~/.openclaw/agents/<agentId>/agent/`
- Status auth WhatsApp (Baileys):
- dari `~/.openclaw/credentials/*.json` lama (kecuali `oauth.json`)
- ke `~/.openclaw/credentials/whatsapp/<accountId>/...` (ID akun default: `default`)
- Status autentikasi WhatsApp (Baileys):
- dari legacy `~/.openclaw/credentials/*.json` (kecuali `oauth.json`)
- ke `~/.openclaw/credentials/whatsapp/<accountId>/...` (id akun default: `default`)
Migrasi ini bersifat best-effort dan idempoten; doctor akan memunculkan peringatan saat meninggalkan folder lama sebagai cadangan. Gateway/CLI juga otomatis memigrasikan sesi lama + direktori agent saat startup sehingga riwayat/auth/model masuk ke jalur per-agent tanpa perlu menjalankan doctor secara manual. Normalisasi provider/peta-provider Talk kini membandingkan berdasarkan kesetaraan struktural, sehingga perbedaan urutan-key saja tidak lagi memicu perubahan `doctor --fix` tanpa efek yang berulang.
Migrasi ini bersifat upaya terbaik dan idempoten; doctor akan mengeluarkan peringatan ketika meninggalkan folder legacy apa pun sebagai cadangan. Gateway/CLI juga memigrasikan otomatis sesi legacy + direktori agen saat startup sehingga riwayat/autentikasi/model masuk ke jalur per-agen tanpa perlu menjalankan doctor secara manual. Autentikasi WhatsApp sengaja hanya dimigrasikan melalui `openclaw doctor`. Normalisasi penyedia/peta-penyedia percakapan kini membandingkan berdasarkan kesetaraan struktural, sehingga perbedaan yang hanya berupa urutan kunci tidak lagi memicu perubahan `doctor --fix` no-op berulang.
</Accordion>
<Accordion title="3a. Legacy plugin manifest migrations">
Doctor memindai semua manifest Plugin yang terpasang untuk key kapabilitas tingkat atas yang sudah usang (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Saat ditemukan, doctor menawarkan untuk memindahkannya ke objek `contracts` dan menulis ulang file manifest di tempat. Migrasi ini idempoten; jika key `contracts` sudah memiliki nilai yang sama, key lama dihapus tanpa menduplikasi data.
<Accordion title="3a. Migrasi manifes Plugin legacy">
Doctor memindai semua manifes Plugin yang terinstal untuk kunci kapabilitas tingkat atas yang sudah tidak digunakan (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Jika ditemukan, doctor menawarkan untuk memindahkannya ke objek `contracts` dan menulis ulang file manifes di tempat. Migrasi ini idempoten; jika kunci `contracts` sudah memiliki nilai yang sama, kunci legacy dihapus tanpa menduplikasi data.
</Accordion>
<Accordion title="3b. Legacy cron store migrations">
Doctor juga memeriksa penyimpanan job cron (`~/.openclaw/cron/jobs.json` secara default, atau `cron.store` saat ditimpa) untuk bentuk job lama yang masih diterima scheduler demi kompatibilitas.
<Accordion title="3b. Migrasi penyimpanan Cron legacy">
Doctor juga memeriksa penyimpanan pekerjaan Cron (`~/.openclaw/cron/jobs.json` secara default, atau `cron.store` saat ditimpa) untuk bentuk pekerjaan lama yang masih diterima scheduler demi kompatibilitas.
Pembersihan cron saat ini meliputi:
Pembersihan Cron saat ini mencakup:
- `jobId` → `id`
- `schedule.cron` → `schedule.expr`
- field payload tingkat atas (`message`, `model`, `thinking`, ...) → `payload`
- field pengiriman tingkat atas (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
- alias pengiriman `provider` payload → `delivery.channel` eksplisit
- job fallback webhook `notify: true` lama yang sederhana → `delivery.mode="webhook"` eksplisit dengan `delivery.to=cron.webhook`
- pekerjaan fallback Webhook `notify: true` legacy sederhana → `delivery.mode="webhook"` eksplisit dengan `delivery.to=cron.webhook`
Doctor hanya memigrasikan otomatis job `notify: true` saat dapat melakukannya tanpa mengubah perilaku. Jika job menggabungkan fallback notify lama dengan mode pengiriman non-webhook yang sudah ada, doctor memperingatkan dan membiarkan job tersebut untuk ditinjau manual.
Doctor hanya memigrasikan otomatis pekerjaan `notify: true` ketika dapat melakukannya tanpa mengubah perilaku. Jika sebuah pekerjaan menggabungkan fallback notify legacy dengan mode pengiriman non-Webhook yang sudah ada, doctor memperingatkan dan membiarkan pekerjaan tersebut untuk ditinjau manual.
Di Linux, doctor juga memperingatkan saat crontab pengguna masih memanggil `~/.openclaw/bin/ensure-whatsapp.sh` lama. Skrip lokal host itu tidak dipelihara oleh OpenClaw saat ini dan dapat menulis pesan `Gateway inactive` palsu ke `~/.openclaw/logs/whatsapp-health.log` saat cron tidak dapat menjangkau bus pengguna systemd. Hapus entri crontab usang dengan `crontab -e`; gunakan `openclaw channels status --probe`, `openclaw doctor`, dan `openclaw gateway status` untuk pemeriksaan kesehatan saat ini.
Di Linux, doctor juga memperingatkan ketika crontab pengguna masih memanggil `~/.openclaw/bin/ensure-whatsapp.sh` lama. Skrip lokal-host itu tidak dipelihara oleh OpenClaw saat ini dan dapat menulis pesan `Gateway inactive` palsu ke `~/.openclaw/logs/whatsapp-health.log` ketika cron tidak dapat menjangkau bus pengguna systemd. Hapus entri crontab usang dengan `crontab -e`; gunakan `openclaw channels status --probe`, `openclaw doctor`, dan `openclaw gateway status` untuk pemeriksaan kesehatan saat ini.
</Accordion>
<Accordion title="3c. Pembersihan kunci sesi">
Doctor memindai setiap direktori sesi agen untuk menemukan file kunci tulis yang usang — file yang tertinggal saat sesi keluar secara tidak normal. Untuk setiap file kunci yang ditemukan, Doctor melaporkan: jalur, PID, apakah PID masih hidup, usia kunci, dan apakah file tersebut dianggap usang (PID mati atau lebih lama dari 30 menit). Dalam mode `--fix` / `--repair`, Doctor menghapus file kunci usang secara otomatis; jika tidak, Doctor mencetak catatan dan menginstruksikan Anda untuk menjalankan ulang dengan `--fix`.
Doctor memindai setiap direktori sesi agen untuk file kunci tulis yang usang — file yang tertinggal ketika sesi keluar secara tidak normal. Untuk setiap file kunci yang ditemukan, ia melaporkan: jalur, PID, apakah PID masih hidup, usia kunci, dan apakah file tersebut dianggap usang (PID mati atau lebih lama dari 30 menit). Dalam mode `--fix` / `--repair`, ia menghapus file kunci usang secara otomatis; jika tidak, ia mencetak catatan dan menginstruksikan Anda untuk menjalankan ulang dengan `--fix`.
</Accordion>
<Accordion title="3d. Perbaikan cabang transkrip sesi">
Doctor memindai file JSONL sesi agen untuk bentuk cabang terduplikasi yang dibuat oleh bug penulisan ulang transkrip prompt 2026.4.24: giliran pengguna yang ditinggalkan dengan konteks runtime internal OpenClaw ditambah saudara aktif yang berisi prompt pengguna terlihat yang sama. Dalam mode `--fix` / `--repair`, Doctor mencadangkan setiap file terdampak di samping file asli dan menulis ulang transkrip ke cabang aktif sehingga riwayat gateway dan pembaca memori tidak lagi melihat giliran duplikat.
Doctor memindai file JSONL sesi agen untuk bentuk cabang duplikat yang dibuat oleh bug penulisan ulang transkrip prompt 2026.4.24: giliran pengguna yang ditinggalkan dengan konteks runtime internal OpenClaw ditambah saudara aktif yang berisi prompt pengguna terlihat yang sama. Dalam mode `--fix` / `--repair`, doctor mencadangkan setiap file terdampak di sebelah file asli dan menulis ulang transkrip ke cabang aktif sehingga riwayat gateway dan pembaca memori tidak lagi melihat giliran duplikat.
</Accordion>
<Accordion title="4. Pemeriksaan integritas status (persistensi sesi, perutean, dan keamanan)">
Direktori status adalah batang otak operasional. Jika menghilang, Anda kehilangan sesi, kredensial, log, dan konfigurasi (kecuali Anda memiliki cadangan di tempat lain).
<Accordion title="4. Pemeriksaan integritas status (persistensi sesi, routing, dan keselamatan)">
Direktori status adalah batang otak operasional. Jika hilang, Anda kehilangan sesi, kredensial, log, dan konfigurasi (kecuali Anda memiliki cadangan di tempat lain).
Doctor memeriksa:
- **Direktori status hilang**: memperingatkan tentang kehilangan status yang katastrofik, meminta untuk membuat ulang direktori, dan mengingatkan Anda bahwa data yang hilang tidak dapat dipulihkan.
- **Izin direktori status**: memverifikasi kemampuan tulis; menawarkan perbaikan izin (dan mengeluarkan petunjuk `chown` saat ketidakcocokan pemilik/grup terdeteksi).
- **Direktori status tersinkron cloud macOS**: memperingatkan saat status berada di bawah iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) atau `~/Library/CloudStorage/...` karena jalur yang didukung sinkronisasi dapat menyebabkan I/O lebih lambat dan perlombaan kunci/sinkronisasi.
- **Direktori status SD atau eMMC Linux**: memperingatkan saat status berada pada sumber mount `mmcblk*`, karena I/O acak berbasis SD atau eMMC dapat lebih lambat dan lebih cepat aus di bawah penulisan sesi dan kredensial.
- **Direktori status hilang**: memperingatkan tentang kehilangan status yang katastrofik, meminta untuk membuat ulang direktori, dan mengingatkan bahwa ia tidak dapat memulihkan data yang hilang.
- **Izin direktori status**: memverifikasi kemampuan tulis; menawarkan untuk memperbaiki izin (dan mengeluarkan petunjuk `chown` ketika ketidakcocokan pemilik/grup terdeteksi).
- **Direktori status yang disinkronkan cloud macOS**: memperingatkan ketika status terselesaikan di bawah iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) atau `~/Library/CloudStorage/...` karena jalur berbasis sinkronisasi dapat menyebabkan I/O lebih lambat dan race kunci/sinkronisasi.
- **Direktori status SD atau eMMC Linux**: memperingatkan ketika status terselesaikan ke sumber mount `mmcblk*`, karena I/O acak berbasis SD atau eMMC dapat lebih lambat dan lebih cepat aus saat penulisan sesi dan kredensial.
- **Direktori sesi hilang**: `sessions/` dan direktori penyimpanan sesi diperlukan untuk mempertahankan riwayat dan menghindari crash `ENOENT`.
- **Ketidakcocokan transkrip**: memperingatkan saat entri sesi terbaru memiliki file transkrip yang hilang.
- **Sesi utama "JSONL 1 baris"**: menandai saat transkrip utama hanya memiliki satu baris (riwayat tidak bertambah).
- **Beberapa direktori status**: memperingatkan saat beberapa folder `~/.openclaw` ada di berbagai direktori home atau saat `OPENCLAW_STATE_DIR` menunjuk ke tempat lain (riwayat dapat terpecah antar instalasi).
- **Pengingat mode jarak jauh**: jika `gateway.mode=remote`, Doctor mengingatkan Anda untuk menjalankannya di host jarak jauh (status berada di sana).
- **Izin file konfigurasi**: memperingatkan jika `~/.openclaw/openclaw.json` dapat dibaca oleh grup/dunia dan menawarkan untuk memperketatnya ke `600`.
- **Ketidakcocokan transkrip**: memperingatkan ketika entri sesi terbaru memiliki file transkrip yang hilang.
- **Sesi utama "JSONL 1 baris"**: menandai ketika transkrip utama hanya memiliki satu baris (riwayat tidak terakumulasi).
- **Beberapa direktori status**: memperingatkan ketika beberapa folder `~/.openclaw` ada di berbagai direktori home atau ketika `OPENCLAW_STATE_DIR` menunjuk ke tempat lain (riwayat dapat terpecah antarinstalasi).
- **Pengingat mode jarak jauh**: jika `gateway.mode=remote`, doctor mengingatkan Anda untuk menjalankannya di host jarak jauh (status berada di sana).
- **Izin file konfigurasi**: memperingatkan jika `~/.openclaw/openclaw.json` dapat dibaca grup/dunia dan menawarkan untuk memperketat ke `600`.
</Accordion>
<Accordion title="5. Kesehatan autentikasi model (kedaluwarsa OAuth)">
Doctor memeriksa profil OAuth di penyimpanan autentikasi, memperingatkan saat token akan kedaluwarsa/sudah kedaluwarsa, dan dapat menyegarkannya saat aman. Jika profil OAuth/token Anthropic sudah usang, Doctor menyarankan kunci API Anthropic atau jalur setup-token Anthropic. Prompt penyegaran hanya muncul saat berjalan secara interaktif (TTY); `--non-interactive` melewati upaya penyegaran.
Doctor memeriksa profil OAuth di penyimpanan autentikasi, memperingatkan ketika token akan kedaluwarsa/sudah kedaluwarsa, dan dapat menyegarkannya ketika aman. Jika profil OAuth/token Anthropic usang, ia menyarankan kunci API Anthropic atau jalur setup-token Anthropic. Prompt penyegaran hanya muncul saat berjalan secara interaktif (TTY); `--non-interactive` melewati upaya penyegaran.
Saat penyegaran OAuth gagal permanen (misalnya `refresh_token_reused`, `invalid_grant`, atau penyedia meminta Anda masuk lagi), Doctor melaporkan bahwa autentikasi ulang diperlukan dan mencetak perintah `openclaw models auth login --provider ...` persis yang harus dijalankan.
Ketika penyegaran OAuth gagal permanen (misalnya `refresh_token_reused`, `invalid_grant`, atau penyedia meminta Anda masuk lagi), doctor melaporkan bahwa autentikasi ulang diperlukan dan mencetak perintah `openclaw models auth login --provider ...` yang tepat untuk dijalankan.
Doctor juga melaporkan profil autentikasi yang sementara tidak dapat digunakan karena:
@ -343,119 +353,119 @@ Itu men-stage kandidat durable grounded ke penyimpanan dreaming jangka pendek sa
- penonaktifan lebih lama (kegagalan penagihan/kredit)
</Accordion>
<Accordion title="6. Validasi model hook">
Jika `hooks.gmail.model` diatur, Doctor memvalidasi referensi model terhadap katalog dan daftar izin serta memperingatkan saat model tidak dapat di-resolve atau tidak diizinkan.
<Accordion title="6. Validasi model hooks">
Jika `hooks.gmail.model` diatur, doctor memvalidasi referensi model terhadap katalog dan daftar izin serta memperingatkan ketika referensi itu tidak akan terselesaikan atau tidak diizinkan.
</Accordion>
<Accordion title="7. Perbaikan image sandbox">
Saat sandboxing diaktifkan, Doctor memeriksa image Docker dan menawarkan untuk membangun atau beralih ke nama lama jika image saat ini hilang.
Ketika sandboxing diaktifkan, doctor memeriksa image Docker dan menawarkan untuk membangun atau beralih ke nama lama jika image saat ini hilang.
</Accordion>
<Accordion title="7b. Pembersihan instalasi Plugin">
Doctor menghapus status staging dependensi Plugin lama yang dihasilkan OpenClaw dalam mode `openclaw doctor --fix` / `openclaw doctor --repair`. Ini mencakup root dependensi usang yang dihasilkan, direktori tahap instalasi lama, sisa lokal paket dari kode perbaikan dependensi Plugin bawaan sebelumnya, dan salinan npm terkelola yatim atau dipulihkan dari Plugin `@openclaw/*` bawaan yang dapat membayangi manifes bawaan saat ini.
Doctor menghapus status staging dependensi Plugin lama yang dihasilkan OpenClaw dalam mode `openclaw doctor --fix` / `openclaw doctor --repair`. Ini mencakup akar dependensi lama yang dihasilkan, direktori tahap-instal lama, sisa paket-lokal dari kode perbaikan dependensi bundled-plugin sebelumnya, dan salinan npm terkelola dari Plugin `@openclaw/*` bundel yang yatim atau dipulihkan yang dapat membayangi manifes bundel saat ini.
Doctor juga dapat menginstal ulang Plugin unduhan yang dikonfigurasi saat konfigurasi merujuknya tetapi registri Plugin lokal tidak dapat menemukannya. Untuk eksternalisasi Plugin bawaan 2026.5.2, Doctor secara otomatis menginstal Plugin unduhan yang sudah digunakan konfigurasi yang ada lalu mengandalkan `meta.lastTouchedVersion` untuk menjalankan pass rilis itu hanya sekali. Startup Gateway dan pemuatan ulang konfigurasi tidak menjalankan manajer paket; instalasi Plugin tetap merupakan pekerjaan doctor/install/update yang eksplisit.
Doctor juga dapat menginstal ulang Plugin yang dapat diunduh yang hilang ketika konfigurasi mereferensikannya tetapi registry Plugin lokal tidak dapat menemukannya. Contohnya mencakup `plugins.entries` material, pengaturan kanal/penyedia/pencarian yang dikonfigurasi, dan runtime agen yang dikonfigurasi. Selama pembaruan paket, doctor menghindari menjalankan perbaikan Plugin manajer paket saat paket inti sedang diganti; jalankan `openclaw doctor --fix` lagi setelah pembaruan jika Plugin yang dikonfigurasi masih perlu pemulihan. Startup Gateway dan pemuatan ulang konfigurasi tidak menjalankan manajer paket; instalasi Plugin tetap merupakan pekerjaan doctor/install/update eksplisit.
</Accordion>
<Accordion title="8. Migrasi layanan Gateway dan petunjuk pembersihan">
Doctor mendeteksi layanan Gateway lama (launchd/systemd/schtasks) dan menawarkan untuk menghapusnya serta menginstal layanan OpenClaw menggunakan port Gateway saat ini. Doctor juga dapat memindai layanan tambahan yang mirip Gateway dan mencetak petunjuk pembersihan. Layanan Gateway OpenClaw bernama profil dianggap kelas utama dan tidak ditandai sebagai "tambahan."
Doctor mendeteksi layanan gateway lama (launchd/systemd/schtasks) dan menawarkan untuk menghapusnya serta menginstal layanan OpenClaw menggunakan port gateway saat ini. Ia juga dapat memindai layanan tambahan yang mirip gateway dan mencetak petunjuk pembersihan. Layanan gateway OpenClaw bernama profil dianggap kelas utama dan tidak ditandai sebagai "tambahan."
Di Linux, jika layanan Gateway tingkat pengguna hilang tetapi layanan Gateway OpenClaw tingkat sistem ada, Doctor tidak menginstal layanan tingkat pengguna kedua secara otomatis. Periksa dengan `openclaw gateway status --deep` atau `openclaw doctor --deep`, lalu hapus duplikatnya atau atur `OPENCLAW_SERVICE_REPAIR_POLICY=external` saat supervisor sistem memiliki siklus hidup Gateway.
Di Linux, jika layanan gateway tingkat pengguna hilang tetapi layanan gateway OpenClaw tingkat sistem ada, doctor tidak menginstal layanan tingkat pengguna kedua secara otomatis. Periksa dengan `openclaw gateway status --deep` atau `openclaw doctor --deep`, lalu hapus duplikat atau atur `OPENCLAW_SERVICE_REPAIR_POLICY=external` ketika supervisor sistem memiliki lifecycle gateway.
</Accordion>
<Accordion title="8b. Migrasi Startup Matrix">
Saat akun kanal Matrix memiliki migrasi status lama yang tertunda atau dapat ditindaklanjuti, Doctor (dalam mode `--fix` / `--repair`) membuat snapshot pra-migrasi lalu menjalankan langkah migrasi upaya terbaik: migrasi status Matrix lama dan persiapan status terenkripsi lama. Kedua langkah tidak fatal; kesalahan dicatat dan startup berlanjut. Dalam mode baca-saja (`openclaw doctor` tanpa `--fix`) pemeriksaan ini dilewati sepenuhnya.
<Accordion title="8b. Migrasi startup Matrix">
Ketika akun kanal Matrix memiliki migrasi status lama yang tertunda atau dapat ditindaklanjuti, doctor (dalam mode `--fix` / `--repair`) membuat snapshot pra-migrasi lalu menjalankan langkah migrasi upaya-terbaik: migrasi status Matrix lama dan persiapan status terenkripsi lama. Kedua langkah tidak fatal; kesalahan dicatat dan startup berlanjut. Dalam mode hanya-baca (`openclaw doctor` tanpa `--fix`) pemeriksaan ini dilewati sepenuhnya.
</Accordion>
<Accordion title="8c. Penyandingan perangkat dan penyimpangan autentikasi">
Doctor sekarang memeriksa status penyandingan perangkat sebagai bagian dari pass kesehatan normal.
<Accordion title="8c. Pairing perangkat dan drift autentikasi">
Doctor sekarang memeriksa status pairing perangkat sebagai bagian dari pemeriksaan kesehatan normal.
Yang dilaporkan:
Yang dilaporkannya:
- permintaan penyandingan pertama kali yang tertunda
- peningkatan peran yang tertunda untuk perangkat yang sudah disandingkan
- peningkatan cakupan yang tertunda untuk perangkat yang sudah disandingkan
- permintaan pairing pertama kali yang tertunda
- peningkatan peran yang tertunda untuk perangkat yang sudah dipairing
- peningkatan cakupan yang tertunda untuk perangkat yang sudah dipairing
- perbaikan ketidakcocokan kunci publik ketika id perangkat masih cocok tetapi identitas perangkat tidak lagi cocok dengan catatan yang disetujui
- catatan yang sudah disandingkan yang tidak memiliki token aktif untuk peran yang disetujui
- token yang sudah disandingkan yang cakupannya bergeser di luar baseline penyandingan yang disetujui
- entri token-perangkat yang di-cache secara lokal untuk mesin saat ini yang lebih lama daripada rotasi token sisi Gateway atau membawa metadata cakupan yang usang
- catatan yang dipairing kehilangan token aktif untuk peran yang disetujui
- token yang dipairing yang cakupannya drift di luar baseline pairing yang disetujui
- entri token perangkat cache lokal untuk mesin saat ini yang lebih lama daripada rotasi token sisi gateway atau membawa metadata cakupan usang
Doctor tidak menyetujui permintaan penyandingan secara otomatis atau merotasi token perangkat secara otomatis. Sebaliknya, ia mencetak langkah berikutnya yang tepat:
Doctor tidak menyetujui otomatis permintaan pairing atau merotasi otomatis token perangkat. Ia mencetak langkah berikutnya yang tepat sebagai gantinya:
- periksa permintaan tertunda dengan `openclaw devices list`
- setujui permintaan yang tepat dengan `openclaw devices approve <requestId>`
- rotasi token baru dengan `openclaw devices rotate --device <deviceId> --role <role>`
- hapus dan setujui ulang catatan usang dengan `openclaw devices remove <deviceId>`
Ini menutup celah umum "sudah disandingkan tetapi masih mendapat pairing required": doctor kini membedakan penyandingan pertama kali dari peningkatan peran/cakupan yang tertunda serta dari pergeseran token/identitas perangkat yang usang.
Ini menutup celah umum "sudah dipairing tetapi masih mendapat pairing required": doctor sekarang membedakan pairing pertama kali dari peningkatan peran/cakupan yang tertunda dan dari drift token/identitas-perangkat yang usang.
</Accordion>
<Accordion title="9. Peringatan keamanan">
Doctor memunculkan peringatan ketika penyedia terbuka untuk DM tanpa daftar izin, atau ketika kebijakan dikonfigurasi dengan cara yang berbahaya.
Doctor mengeluarkan peringatan ketika penyedia terbuka untuk DM tanpa daftar izin, atau ketika kebijakan dikonfigurasi dengan cara yang berbahaya.
</Accordion>
<Accordion title="10. systemd linger (Linux)">
Jika berjalan sebagai layanan pengguna systemd, doctor memastikan lingering diaktifkan agar Gateway tetap aktif setelah logout.
Jika berjalan sebagai layanan pengguna systemd, doctor memastikan lingering diaktifkan sehingga gateway tetap hidup setelah logout.
</Accordion>
<Accordion title="11. Status workspace (skills, plugins, dan direktori lama)">
<Accordion title="11. Status workspace (skills, Plugin, dan direktori lama)">
Doctor mencetak ringkasan status workspace untuk agen default:
- **Status Skills**: menghitung skill yang memenuhi syarat, persyaratan-hilang, dan diblokir-daftar-izin.
- **Status Skills**: menghitung skill yang memenuhi syarat, persyaratan hilang, dan diblokir daftar izin.
- **Direktori workspace lama**: memperingatkan ketika `~/openclaw` atau direktori workspace lama lainnya ada berdampingan dengan workspace saat ini.
- **Status Plugin**: menghitung Plugin yang diaktifkan/dinonaktifkan/error; mencantumkan ID Plugin untuk setiap error; melaporkan kemampuan Plugin bundel.
- **Status Plugin**: menghitung Plugin yang diaktifkan/dinonaktifkan/error; mencantumkan ID Plugin untuk error apa pun; melaporkan kapabilitas Plugin bundel.
- **Peringatan kompatibilitas Plugin**: menandai Plugin yang memiliki masalah kompatibilitas dengan runtime saat ini.
- **Diagnostik Plugin**: menampilkan peringatan atau error waktu-muat apa pun yang dikeluarkan oleh registri Plugin.
- **Diagnostik Plugin**: menampilkan peringatan atau error saat pemuatan yang dikeluarkan oleh registry Plugin.
</Accordion>
<Accordion title="11b. Ukuran file bootstrap">
Doctor memeriksa apakah file bootstrap workspace (misalnya `AGENTS.md`, `CLAUDE.md`, atau file konteks lain yang disuntikkan) mendekati atau melampaui anggaran karakter yang dikonfigurasi. Ia melaporkan hitungan karakter mentah vs. tersuntik per file, persentase pemotongan, penyebab pemotongan (`max/file` atau `max/total`), dan total karakter tersuntik sebagai pecahan dari total anggaran. Ketika file dipotong atau mendekati batas, doctor mencetak kiat untuk menyesuaikan `agents.defaults.bootstrapMaxChars` dan `agents.defaults.bootstrapTotalMaxChars`.
Doctor memeriksa apakah file bootstrap workspace (misalnya `AGENTS.md`, `CLAUDE.md`, atau file konteks injeksi lainnya) mendekati atau melebihi anggaran karakter yang dikonfigurasi. Ia melaporkan jumlah karakter mentah vs. injeksi per file, persentase pemotongan, penyebab pemotongan (`max/file` atau `max/total`), dan total karakter injeksi sebagai fraksi dari total anggaran. Ketika file dipotong atau mendekati batas, doctor mencetak tips untuk menyesuaikan `agents.defaults.bootstrapMaxChars` dan `agents.defaults.bootstrapTotalMaxChars`.
</Accordion>
<Accordion title="11d. Pembersihan Plugin saluran usang">
Ketika `openclaw doctor --fix` menghapus Plugin saluran yang hilang, ia juga menghapus config bercakupan saluran yang menggantung yang merujuk ke Plugin tersebut: entri `channels.<id>`, target Heartbeat yang menamai saluran, dan override `agents.*.models["<channel>/*"]`. Ini mencegah loop boot Gateway ketika runtime saluran sudah hilang tetapi config masih meminta gateway untuk mengikat ke sana.
<Accordion title="11d. Pembersihan Plugin kanal usang">
Ketika `openclaw doctor --fix` menghapus Plugin kanal yang hilang, ia juga menghapus konfigurasi berskup kanal yang menggantung yang mereferensikan Plugin tersebut: entri `channels.<id>`, target Heartbeat yang menamai kanal, dan override `agents.*.models["<channel>/*"]`. Ini mencegah boot loop Gateway ketika runtime kanal sudah hilang tetapi konfigurasi masih meminta gateway untuk mengikatnya.
</Accordion>
<Accordion title="11c. Pelengkapan shell">
Doctor memeriksa apakah pelengkapan tab terpasang untuk shell saat ini (zsh, bash, fish, atau PowerShell):
Doctor memeriksa apakah pelengkapan tab terinstal untuk shell saat ini (zsh, bash, fish, atau PowerShell):
- Jika profil shell menggunakan pola pelengkapan dinamis yang lambat (`source <(openclaw completion ...)`), doctor meningkatkannya ke varian file cache yang lebih cepat.
- Jika pelengkapan dikonfigurasi di profil tetapi file cache hilang, doctor membuat ulang cache secara otomatis.
- Jika tidak ada pelengkapan yang dikonfigurasi sama sekali, doctor meminta untuk memasangnya (hanya mode interaktif; dilewati dengan `--non-interactive`).
- Jika profil shell menggunakan pola pelengkapan dinamis lambat (`source <(openclaw completion ...)`), doctor meningkatkannya ke varian file cache yang lebih cepat.
- Jika pelengkapan dikonfigurasi di profil tetapi file cache hilang, doctor meregenerasi cache secara otomatis.
- Jika tidak ada pelengkapan yang dikonfigurasi sama sekali, doctor meminta untuk menginstalnya (hanya mode interaktif; dilewati dengan `--non-interactive`).
Jalankan `openclaw completion --write-state` untuk membuat ulang cache secara manual.
Jalankan `openclaw completion --write-state` untuk meregenerasi cache secara manual.
</Accordion>
<Accordion title="12. Pemeriksaan auth Gateway (token lokal)">
Doctor memeriksa kesiapan auth token gateway lokal.
<Accordion title="12. Pemeriksaan autentikasi Gateway (token lokal)">
Doctor memeriksa kesiapan autentikasi token gateway lokal.
- Jika mode token membutuhkan token dan tidak ada sumber token, doctor menawarkan untuk membuatnya.
- Jika mode token memerlukan token dan tidak ada sumber token, doctor menawarkan untuk membuatnya.
- Jika `gateway.auth.token` dikelola SecretRef tetapi tidak tersedia, doctor memperingatkan dan tidak menimpanya dengan plaintext.
- `openclaw doctor --generate-gateway-token` memaksa pembuatan hanya ketika tidak ada SecretRef token yang dikonfigurasi.
</Accordion>
<Accordion title="12b. Perbaikan sadar SecretRef yang read-only">
Beberapa alur perbaikan perlu memeriksa kredensial yang dikonfigurasi tanpa melemahkan perilaku runtime fail-fast.
<Accordion title="12b. Perbaikan hanya-baca yang sadar SecretRef">
Beberapa alur perbaikan perlu memeriksa kredensial yang dikonfigurasi tanpa melemahkan perilaku fail-fast runtime.
- `openclaw doctor --fix` kini menggunakan model ringkasan SecretRef read-only yang sama seperti perintah keluarga status untuk perbaikan config tertarget.
- Contoh: perbaikan `allowFrom` / `groupAllowFrom` `@username` Telegram mencoba menggunakan kredensial bot yang dikonfigurasi ketika tersedia.
- Jika token bot Telegram dikonfigurasi melalui SecretRef tetapi tidak tersedia di jalur perintah saat ini, doctor melaporkan bahwa kredensial dikonfigurasi-tetapi-tidak-tersedia dan melewati resolusi otomatis alih-alih crash atau salah melaporkan token sebagai hilang.
- `openclaw doctor --fix` kini menggunakan model ringkasan SecretRef baca-saja yang sama seperti perintah keluarga status untuk perbaikan konfigurasi tertarget.
- Contoh: perbaikan Telegram `allowFrom` / `groupAllowFrom` `@username` mencoba menggunakan kredensial bot yang dikonfigurasi saat tersedia.
- Jika token bot Telegram dikonfigurasi melalui SecretRef tetapi tidak tersedia di jalur perintah saat ini, doctor melaporkan bahwa kredensial sudah dikonfigurasi tetapi tidak tersedia, lalu melewati resolusi otomatis alih-alih crash atau salah melaporkan token sebagai hilang.
</Accordion>
<Accordion title="13. Pemeriksaan kesehatan Gateway + mulai ulang">
Doctor menjalankan pemeriksaan kesehatan dan menawarkan untuk memulai ulang gateway ketika tampak tidak sehat.
Doctor menjalankan pemeriksaan kesehatan dan menawarkan untuk memulai ulang gateway ketika terlihat tidak sehat.
</Accordion>
<Accordion title="13b. Kesiapan pencarian memori">
Doctor memeriksa apakah penyedia embedding pencarian memori yang dikonfigurasi siap untuk agen default. Perilakunya bergantung pada backend dan penyedia yang dikonfigurasi:
- **Backend QMD**: memeriksa apakah biner `qmd` tersedia dan dapat dijalankan. Jika tidak, mencetak panduan perbaikan termasuk paket npm dan opsi jalur biner manual.
- **Penyedia lokal eksplisit**: memeriksa file model lokal atau URL model jarak jauh/dapat diunduh yang dikenali. Jika tidak ada, menyarankan untuk beralih ke penyedia jarak jauh.
- **Penyedia jarak jauh eksplisit** (`openai`, `voyage`, dll.): memverifikasi bahwa kunci API tersedia di lingkungan atau penyimpanan autentikasi. Mencetak petunjuk perbaikan yang dapat ditindaklanjuti jika tidak ada.
- **Penyedia otomatis**: memeriksa ketersediaan model lokal terlebih dahulu, lalu mencoba setiap penyedia jarak jauh sesuai urutan pemilihan otomatis.
- **Penyedia lokal eksplisit**: memeriksa file model lokal atau URL model jarak jauh/yang dapat diunduh yang dikenali. Jika hilang, menyarankan beralih ke penyedia jarak jauh.
- **Penyedia jarak jauh eksplisit** (`openai`, `voyage`, dll.): memverifikasi bahwa kunci API ada di lingkungan atau penyimpanan auth. Mencetak petunjuk perbaikan yang dapat ditindaklanjuti jika hilang.
- **Penyedia otomatis**: memeriksa ketersediaan model lokal terlebih dahulu, lalu mencoba setiap penyedia jarak jauh dalam urutan pemilihan otomatis.
Ketika hasil probe gateway yang di-cache tersedia (gateway sehat pada saat pemeriksaan), doctor mencocokkan hasilnya dengan konfigurasi yang terlihat oleh CLI dan mencatat setiap perbedaan. Doctor tidak memulai ping embedding baru pada jalur default; gunakan perintah status memori mendalam saat Anda menginginkan pemeriksaan penyedia langsung.
Saat hasil probe gateway yang di-cache tersedia (gateway sehat pada saat pemeriksaan), doctor mencocokkan hasilnya dengan konfigurasi yang terlihat oleh CLI dan mencatat setiap ketidaksesuaian. Doctor tidak memulai ping embedding baru pada jalur default; gunakan perintah status memori mendalam saat Anda menginginkan pemeriksaan penyedia langsung.
Gunakan `openclaw memory status --deep` untuk memverifikasi kesiapan embedding saat runtime.
</Accordion>
<Accordion title="14. Peringatan status channel">
Jika gateway sehat, doctor menjalankan probe status channel dan melaporkan peringatan dengan perbaikan yang disarankan.
<Accordion title="14. Peringatan status saluran">
Jika gateway sehat, doctor menjalankan probe status saluran dan melaporkan peringatan dengan perbaikan yang disarankan.
</Accordion>
<Accordion title="15. Audit + perbaikan konfigurasi supervisor">
Doctor memeriksa konfigurasi supervisor yang terpasang (launchd/systemd/schtasks) untuk default yang hilang atau usang (misalnya, dependensi systemd network-online dan jeda mulai ulang). Saat menemukan ketidakcocokan, doctor merekomendasikan pembaruan dan dapat menulis ulang file layanan/tugas ke default saat ini.
<Accordion title="15. Audit konfigurasi supervisor + perbaikan">
Doctor memeriksa konfigurasi supervisor yang terpasang (launchd/systemd/schtasks) untuk default yang hilang atau usang (misalnya, dependensi systemd network-online dan penundaan mulai ulang). Saat menemukan ketidakcocokan, doctor merekomendasikan pembaruan dan dapat menulis ulang file layanan/tugas ke default saat ini.
Catatan:
@ -463,34 +473,34 @@ Itu men-stage kandidat durable grounded ke penyimpanan dreaming jangka pendek sa
- `openclaw doctor --yes` menerima prompt perbaikan default.
- `openclaw doctor --repair` menerapkan perbaikan yang direkomendasikan tanpa prompt.
- `openclaw doctor --repair --force` menimpa konfigurasi supervisor kustom.
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` menjaga doctor tetap hanya-baca untuk siklus hidup layanan gateway. Doctor tetap melaporkan kesehatan layanan dan menjalankan perbaikan non-layanan, tetapi melewati pemasangan/mulai/mulai ulang/bootstrap layanan, penulisan ulang konfigurasi supervisor, dan pembersihan layanan lama karena supervisor eksternal memiliki siklus hidup tersebut.
- Di Linux, doctor tidak menulis ulang metadata perintah/entrypoint saat unit gateway systemd yang cocok aktif. Doctor juga mengabaikan unit tambahan mirip gateway non-legacy yang tidak aktif selama pemindaian layanan duplikat, sehingga file layanan pendamping tidak membuat noise pembersihan.
- Jika autentikasi token memerlukan token dan `gateway.auth.token` dikelola SecretRef, pemasangan/perbaikan layanan doctor memvalidasi SecretRef tetapi tidak menyimpan nilai token plaintext yang sudah di-resolve ke dalam metadata lingkungan layanan supervisor.
- Doctor mendeteksi nilai lingkungan layanan terkelola berbasis `.env`/SecretRef yang dipasang inline oleh instalasi LaunchAgent, systemd, atau Windows Scheduled Task lama dan menulis ulang metadata layanan agar nilai tersebut dimuat dari sumber runtime, bukan dari definisi supervisor.
- Doctor mendeteksi saat perintah layanan masih mengunci `--port` lama setelah `gateway.port` berubah dan menulis ulang metadata layanan ke port saat ini.
- Jika autentikasi token memerlukan token dan SecretRef token yang dikonfigurasi belum ter-resolve, doctor memblokir jalur pemasangan/perbaikan dengan panduan yang dapat ditindaklanjuti.
- Jika `gateway.auth.token` dan `gateway.auth.password` sama-sama dikonfigurasi dan `gateway.auth.mode` belum disetel, doctor memblokir pemasangan/perbaikan hingga mode disetel secara eksplisit.
- Untuk unit user-systemd Linux, pemeriksaan drift token doctor kini menyertakan sumber `Environment=` dan `EnvironmentFile=` saat membandingkan metadata autentikasi layanan.
- Perbaikan layanan Doctor menolak menulis ulang, menghentikan, atau memulai ulang layanan gateway dari biner OpenClaw yang lebih lama ketika konfigurasi terakhir ditulis oleh versi yang lebih baru. Lihat [Pemecahan masalah Gateway](/id/gateway/troubleshooting#split-brain-installs-and-newer-config-guard).
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` menjaga doctor tetap baca-saja untuk siklus hidup layanan gateway. Doctor tetap melaporkan kesehatan layanan dan menjalankan perbaikan non-layanan, tetapi melewati pemasangan/mulai/mulai ulang/bootstrap layanan, penulisan ulang konfigurasi supervisor, dan pembersihan layanan legacy karena supervisor eksternal memiliki siklus hidup tersebut.
- Di Linux, doctor tidak menulis ulang metadata perintah/entrypoint saat unit gateway systemd yang cocok aktif. Doctor juga mengabaikan unit tambahan mirip gateway non-legacy yang tidak aktif selama pemindaian layanan duplikat agar file layanan pendamping tidak membuat noise pembersihan.
- Jika auth token memerlukan token dan `gateway.auth.token` dikelola SecretRef, pemasangan/perbaikan layanan doctor memvalidasi SecretRef tetapi tidak menyimpan nilai token plaintext yang diselesaikan ke dalam metadata lingkungan layanan supervisor.
- Doctor mendeteksi nilai lingkungan layanan yang dikelola `.env`/didukung SecretRef yang disematkan inline oleh pemasangan LaunchAgent, systemd, atau Windows Scheduled Task lama, lalu menulis ulang metadata layanan agar nilai tersebut dimuat dari sumber runtime, bukan dari definisi supervisor.
- Doctor mendeteksi ketika perintah layanan masih mematok `--port` lama setelah `gateway.port` berubah dan menulis ulang metadata layanan ke port saat ini.
- Jika auth token memerlukan token dan SecretRef token yang dikonfigurasi belum terselesaikan, doctor memblokir jalur pemasangan/perbaikan dengan panduan yang dapat ditindaklanjuti.
- Jika `gateway.auth.token` dan `gateway.auth.password` sama-sama dikonfigurasi dan `gateway.auth.mode` belum disetel, doctor memblokir pemasangan/perbaikan sampai mode disetel secara eksplisit.
- Untuk unit user-systemd Linux, pemeriksaan drift token doctor kini menyertakan sumber `Environment=` dan `EnvironmentFile=` saat membandingkan metadata auth layanan.
- Perbaikan layanan Doctor menolak menulis ulang, menghentikan, atau memulai ulang layanan gateway dari biner OpenClaw lama ketika konfigurasi terakhir ditulis oleh versi yang lebih baru. Lihat [Pemecahan masalah Gateway](/id/gateway/troubleshooting#split-brain-installs-and-newer-config-guard).
- Anda selalu dapat memaksa penulisan ulang penuh melalui `openclaw gateway install --force`.
</Accordion>
<Accordion title="16. Diagnostik runtime + port Gateway">
Doctor memeriksa runtime layanan (PID, status keluar terakhir) dan memperingatkan saat layanan terpasang tetapi sebenarnya tidak berjalan. Doctor juga memeriksa bentrokan port pada port gateway (default `18789`) dan melaporkan kemungkinan penyebabnya (gateway sudah berjalan, tunnel SSH).
<Accordion title="16. Diagnostik runtime Gateway + port">
Doctor memeriksa runtime layanan (PID, status keluar terakhir) dan memperingatkan saat layanan terpasang tetapi tidak benar-benar berjalan. Doctor juga memeriksa tabrakan port pada port gateway (default `18789`) dan melaporkan kemungkinan penyebab (gateway sudah berjalan, tunnel SSH).
</Accordion>
<Accordion title="17. Praktik terbaik runtime Gateway">
Doctor memperingatkan saat layanan gateway berjalan di Bun atau jalur Node yang dikelola versi (`nvm`, `fnm`, `volta`, `asdf`, dll.). Channel WhatsApp + Telegram memerlukan Node, dan jalur pengelola versi dapat rusak setelah peningkatan karena layanan tidak memuat init shell Anda. Doctor menawarkan migrasi ke instalasi Node sistem jika tersedia (Homebrew/apt/choco).
Doctor memperingatkan saat layanan gateway berjalan di Bun atau jalur Node yang dikelola versi (`nvm`, `fnm`, `volta`, `asdf`, dll.). Saluran WhatsApp + Telegram memerlukan Node, dan jalur manajer versi dapat rusak setelah upgrade karena layanan tidak memuat init shell Anda. Doctor menawarkan migrasi ke instalasi Node sistem saat tersedia (Homebrew/apt/choco).
LaunchAgent macOS yang baru dipasang atau diperbaiki menggunakan PATH sistem kanonis (`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`) alih-alih menyalin PATH shell interaktif, sehingga direktori Volta, asdf, fnm, pnpm, dan pengelola versi lain tidak mengubah Node mana yang di-resolve oleh proses anak. Layanan Linux tetap mempertahankan root lingkungan eksplisit (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) dan direktori user-bin yang stabil, tetapi direktori fallback pengelola versi yang ditebak hanya ditulis ke PATH layanan saat direktori tersebut ada di disk.
LaunchAgent macOS yang baru dipasang atau diperbaiki menggunakan PATH sistem kanonis (`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`) alih-alih menyalin PATH shell interaktif, sehingga Volta, asdf, fnm, pnpm, dan direktori manajer versi lain tidak mengubah Node mana yang diselesaikan oleh proses anak. Layanan Linux tetap mempertahankan root lingkungan eksplisit (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) dan direktori user-bin yang stabil, tetapi direktori fallback manajer versi yang ditebak hanya ditulis ke PATH layanan saat direktori tersebut ada di disk.
</Accordion>
<Accordion title="18. Penulisan konfigurasi + metadata wizard">
Doctor menyimpan perubahan konfigurasi apa pun dan memberi cap metadata wizard untuk mencatat proses doctor.
Doctor mempertahankan setiap perubahan konfigurasi dan memberi cap metadata wizard untuk merekam jalannya doctor.
</Accordion>
<Accordion title="19. Tips workspace (cadangan + sistem memori)">
Doctor menyarankan sistem memori workspace saat belum ada dan mencetak tips cadangan jika workspace belum berada di bawah git.
Doctor menyarankan sistem memori workspace saat hilang dan mencetak tips cadangan jika workspace belum berada di bawah git.
Lihat [/concepts/agent-workspace](/id/concepts/agent-workspace) untuk panduan lengkap tentang struktur workspace dan cadangan git (GitHub atau GitLab privat direkomendasikan).
Lihat [/concepts/agent-workspace](/id/concepts/agent-workspace) untuk panduan lengkap tentang struktur workspace dan cadangan git (GitHub atau GitLab pribadi direkomendasikan).
</Accordion>
</AccordionGroup>

91
docs/id/gateway/logging.md
View File

@ -1,40 +1,51 @@
---
read_when:
- Mengubah keluaran atau format pencatatan log
- Mengubah keluaran atau format log
- Pemecahan masalah keluaran CLI atau Gateway
summary: Permukaan pencatatan log, log berbasis berkas, gaya log WS, dan pemformatan konsol
summary: Permukaan pencatatan log, log file, gaya log WS, dan pemformatan konsol
title: Pencatatan log Gateway
x-i18n:
generated_at: "2026-05-02T09:21:11Z"
generated_at: "2026-05-05T01:46:26Z"
model: gpt-5.5
provider: openai
source_hash: eb5f5ccd77909e82bd2938a33514ce8361c69910eb945c731d9b2c8266174c13
source_hash: d49ca112d3cc4ec76ecfc8b14d16dae64f74ca1f761fdb2b7bb470f73b66a246
source_path: gateway/logging.md
workflow: 16
---
# Logging
# Pencatatan Log
Untuk ringkasan yang ditujukan bagi pengguna (CLI + Control UI + config), lihat [/logging](/id/logging).
Untuk ikhtisar yang ditujukan bagi pengguna (CLI + Control UI + konfigurasi), lihat [/logging](/id/logging).
OpenClaw memiliki dua “permukaan” log:
- **Output konsol** (yang Anda lihat di terminal / Debug UI).
- **Log file** (baris JSON) yang ditulis oleh logger Gateway.
- **Log file** (baris JSON) yang ditulis oleh logger gateway.
Saat startup, Gateway mencatat model agen default yang telah diselesaikan bersama dengan
default mode yang memengaruhi sesi baru, misalnya:
```text
agent model: openai-codex/gpt-5.5 (thinking=medium, fast=on)
```
`thinking` berasal dari agen default, parameter model, atau default agen global;
ketika tidak diatur, ringkasan startup menampilkan `medium`. `fast` berasal dari
parameter `fastMode` agen default atau model.
## Logger berbasis file
- File log bergulir bawaan berada di bawah `/tmp/openclaw/` (satu file per hari): `openclaw-YYYY-MM-DD.log`
- Tanggal menggunakan zona waktu lokal host Gateway.
- File log aktif berotasi pada `logging.maxFileBytes` (bawaan: 100 MB), menyimpan
hingga lima arsip bernomor dan terus menulis ke file aktif baru.
- File log bergulir default berada di bawah `/tmp/openclaw/` (satu file per hari): `openclaw-YYYY-MM-DD.log`
- Tanggal menggunakan zona waktu lokal host gateway.
- File log aktif berotasi pada `logging.maxFileBytes` (default: 100 MB), mempertahankan
hingga lima arsip bernomor dan terus menulis file aktif baru.
- Jalur dan level file log dapat dikonfigurasi melalui `~/.openclaw/openclaw.json`:
- `logging.file`
- `logging.level`
Format file adalah satu objek JSON per baris.
Tab Log Control UI mengikuti file ini melalui Gateway (`logs.tail`).
Tab Log Control UI mengikuti file ini melalui gateway (`logs.tail`).
CLI dapat melakukan hal yang sama:
```bash
@ -43,13 +54,13 @@ openclaw logs --follow
**Verbose vs. level log**
- **Log file** dikendalikan secara eksklusif oleh `logging.level`.
- `--verbose` hanya memengaruhi **kerincian konsol** (dan gaya log WS); ini **tidak**
- **Log file** dikontrol secara eksklusif oleh `logging.level`.
- `--verbose` hanya memengaruhi **verbositas konsol** (dan gaya log WS); ini **tidak**
menaikkan level log file.
- Untuk menangkap detail khusus verbose dalam log file, atur `logging.level` ke `debug` atau
- Untuk menangkap detail yang hanya muncul dalam mode verbose di log file, atur `logging.level` ke `debug` atau
`trace`.
- Logging trace juga mencakup ringkasan waktu diagnostik untuk jalur panas tertentu,
seperti persiapan factory tool Plugin. Lihat
- Pencatatan log trace juga mencakup ringkasan waktu diagnostik untuk hot path tertentu,
seperti persiapan factory tool plugin. Lihat
[/tools/plugin#slow-plugin-tool-setup](/id/tools/plugin#slow-plugin-tool-setup).
## Penangkapan konsol
@ -57,30 +68,30 @@ openclaw logs --follow
CLI menangkap `console.log/info/warn/error/debug/trace` dan menuliskannya ke log file,
sambil tetap mencetak ke stdout/stderr.
Anda dapat menyetel kerincian konsol secara terpisah melalui:
Anda dapat menyesuaikan verbositas konsol secara independen melalui:
- `logging.consoleLevel` (bawaan `info`)
- `logging.consoleLevel` (default `info`)
- `logging.consoleStyle` (`pretty` | `compact` | `json`)
## Redaksi
OpenClaw dapat menyamarkan token sensitif sebelum output log atau transkrip keluar dari
proses. Kebijakan redaksi logging ini diterapkan pada konsol, log file, catatan log OTLP,
dan sink teks transkrip sesi, sehingga nilai rahasia yang cocok disamarkan
proses. Kebijakan redaksi pencatatan log ini diterapkan pada sink teks konsol, file-log, rekaman-log OTLP,
dan transkrip sesi, sehingga nilai rahasia yang cocok disamarkan
sebelum baris JSONL atau pesan ditulis ke disk.
- `logging.redactSensitive`: `off` | `tools` (bawaan: `tools`)
- `logging.redactPatterns`: array string regex (menimpa bawaan)
- `logging.redactSensitive`: `off` | `tools` (default: `tools`)
- `logging.redactPatterns`: array string regex (menimpa default)
- Gunakan string regex mentah (otomatis `gi`), atau `/pattern/flags` jika Anda memerlukan flag khusus.
- Kecocokan disamarkan dengan mempertahankan 6 karakter pertama + 4 karakter terakhir (panjang >= 18), jika tidak `***`.
- Bawaan mencakup assignment key umum, flag CLI, field JSON, header bearer, blok PEM, prefix token populer, dan nama field kredensial pembayaran seperti nomor kartu, CVC/CVV, token pembayaran bersama, dan kredensial pembayaran.
- Default mencakup penugasan kunci umum, flag CLI, field JSON, header bearer, blok PEM, prefiks token populer, dan nama field kredensial pembayaran seperti nomor kartu, CVC/CVV, token pembayaran bersama, dan kredensial pembayaran.
Beberapa batas keamanan selalu melakukan redaksi terlepas dari `logging.redactSensitive`.
Beberapa batas keamanan selalu meredaksi terlepas dari `logging.redactSensitive`.
Ini mencakup event tool-call Control UI, output tool `sessions_history`,
ekspor dukungan diagnostik, observasi error penyedia, tampilan perintah persetujuan exec,
dan log protokol WebSocket Gateway. Permukaan ini masih dapat menggunakan
`logging.redactPatterns` sebagai pola tambahan, tetapi `redactSensitive: "off"`
tidak membuatnya mengeluarkan rahasia mentah.
tidak membuatnya memancarkan rahasia mentah.
## Log WebSocket Gateway
@ -88,17 +99,17 @@ Gateway mencetak log protokol WebSocket dalam dua mode:
- **Mode normal (tanpa `--verbose`)**: hanya hasil RPC yang “menarik” yang dicetak:
- error (`ok=false`)
- panggilan lambat (ambang bawaan: `>= 50ms`)
- error parse
- **Mode verbose (`--verbose`)**: mencetak semua lalu lintas request/response WS.
- panggilan lambat (ambang default: `>= 50ms`)
- error penguraian
- **Mode verbose (`--verbose`)**: mencetak semua traffic permintaan/respons WS.
### Gaya log WS
`openclaw gateway` mendukung switch gaya per Gateway:
`openclaw gateway` mendukung sakelar gaya per-gateway:
- `--ws-log auto` (bawaan): mode normal dioptimalkan; mode verbose menggunakan output ringkas
- `--ws-log compact`: output ringkas (request/response berpasangan) saat verbose
- `--ws-log full`: output penuh per frame saat verbose
- `--ws-log auto` (default): mode normal dioptimalkan; mode verbose menggunakan output ringkas
- `--ws-log compact`: output ringkas (pasangan permintaan/respons) saat verbose
- `--ws-log full`: output penuh per-frame saat verbose
- `--compact`: alias untuk `--ws-log compact`
Contoh:
@ -114,27 +125,27 @@ openclaw gateway --verbose --ws-log compact
openclaw gateway --verbose --ws-log full
```
## Pemformatan konsol (logging subsistem)
## Pemformatan konsol (pencatatan log subsistem)
Formatter konsol **sadar TTY** dan mencetak baris berprefiks yang konsisten.
Pemformat konsol **TTY-aware** dan mencetak baris yang konsisten dengan prefiks.
Logger subsistem menjaga output tetap terkelompok dan mudah dipindai.
Perilaku:
- **Prefiks subsistem** pada setiap baris (mis. `[gateway]`, `[canvas]`, `[tailscale]`)
- **Warna subsistem** (stabil per subsistem) ditambah pewarnaan level
- **Warna saat output adalah TTY atau lingkungan terlihat seperti terminal kaya** (`TERM`/`COLORTERM`/`TERM_PROGRAM`), menghormati `NO_COLOR`
- **Prefiks subsistem yang dipersingkat**: menghapus awalan `gateway/` + `channels/`, mempertahankan 2 segmen terakhir (mis. `whatsapp/outbound`)
- **Warna subsistem** (stabil per subsistem) plus pewarnaan level
- **Warna ketika output adalah TTY atau lingkungan tampak seperti terminal kaya** (`TERM`/`COLORTERM`/`TERM_PROGRAM`), menghormati `NO_COLOR`
- **Prefiks subsistem yang dipersingkat**: menghapus `gateway/` + `channels/` di depan, mempertahankan 2 segmen terakhir (mis. `whatsapp/outbound`)
- **Sub-logger berdasarkan subsistem** (prefiks otomatis + field terstruktur `{ subsystem }`)
- **`logRaw()`** untuk output QR/UX (tanpa prefiks, tanpa pemformatan)
- **Gaya konsol** (mis. `pretty | compact | json`)
- **Level log konsol** terpisah dari level log file (file mempertahankan detail penuh saat `logging.level` diatur ke `debug`/`trace`)
- **Level log konsol** terpisah dari level log file (file mempertahankan detail penuh ketika `logging.level` diatur ke `debug`/`trace`)
- **Isi pesan WhatsApp** dicatat pada `debug` (gunakan `--verbose` untuk melihatnya)
Ini menjaga log file yang ada tetap stabil sekaligus membuat output interaktif mudah dipindai.
## Terkait
- [Logging](/id/logging)
- [Pencatatan Log](/id/logging)
- [Ekspor OpenTelemetry](/id/gateway/opentelemetry)
- [Ekspor diagnostik](/id/gateway/diagnostics)

148
docs/id/help/debugging.md
View File

@ -1,26 +1,26 @@
---
read_when:
- Anda perlu memeriksa keluaran mentah model untuk kebocoran penalaran
- Anda ingin menjalankan Gateway dalam mode watch saat melakukan iterasi
- Anda memerlukan alur kerja penelusuran kesalahan yang dapat diulang
summary: 'Alat pemecahan masalah: mode pantau, aliran model mentah, dan penelusuran kebocoran penalaran'
title: Penelusuran Kesalahan
- Anda perlu memeriksa keluaran mentah model untuk mendeteksi kebocoran penalaran
- Anda ingin menjalankan Gateway dalam mode pemantauan saat melakukan iterasi
- Anda memerlukan alur kerja debugging yang dapat diulang
summary: 'Alat penelusuran kesalahan: mode pemantauan, aliran model mentah, dan pelacakan kebocoran penalaran'
title: Penelusuran Galat
x-i18n:
generated_at: "2026-05-03T21:33:56Z"
generated_at: "2026-05-05T01:47:03Z"
model: gpt-5.5
provider: openai
source_hash: 7230112013a8db8d6a3853b765f4302a61609051ac4ffaf35a6f09de328deafc
source_hash: 9d86bd9b5dd08615d3c283f3fcb2a885f5134fa7e1cdece86b6a796d08a659ec
source_path: help/debugging.md
workflow: 16
---
Pembantu debugging untuk output streaming, terutama saat provider mencampurkan reasoning ke dalam teks normal.
Pembantu debugging untuk keluaran streaming, terutama ketika provider mencampur reasoning ke dalam teks normal.
## Override debug runtime
Gunakan `/debug` di chat untuk mengatur override konfigurasi **khusus runtime** (memori, bukan disk).
Gunakan `/debug` di chat untuk menetapkan override konfigurasi **khusus runtime** (memori, bukan disk).
`/debug` dinonaktifkan secara default; aktifkan dengan `commands.debug: true`.
Ini berguna saat Anda perlu mengaktifkan atau menonaktifkan pengaturan yang jarang digunakan tanpa mengedit `openclaw.json`.
Ini berguna saat Anda perlu mengaktifkan atau menonaktifkan pengaturan yang jarang dipakai tanpa mengedit `openclaw.json`.
Contoh:
@ -33,7 +33,7 @@ Contoh:
`/debug reset` menghapus semua override dan kembali ke konfigurasi di disk.
## Output jejak sesi
## Keluaran jejak sesi
Gunakan `/trace` saat Anda ingin melihat baris trace/debug milik Plugin dalam satu sesi
tanpa mengaktifkan mode verbose penuh.
@ -47,15 +47,15 @@ Contoh:
```
Gunakan `/trace` untuk diagnostik Plugin seperti ringkasan debug Active Memory.
Tetap gunakan `/verbose` untuk output status/tool verbose normal, dan tetap gunakan
Tetap gunakan `/verbose` untuk keluaran status/tool verbose normal, dan tetap gunakan
`/debug` untuk override konfigurasi khusus runtime.
## Jejak siklus hidup Plugin
Gunakan `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` saat perintah siklus hidup Plugin terasa lambat
dan Anda memerlukan rincian fase bawaan untuk metadata Plugin, discovery, registry,
runtime mirror, mutasi konfigurasi, dan pekerjaan refresh. Trace ini bersifat opt-in dan menulis
ke stderr, sehingga output perintah JSON tetap dapat di-parse.
dan Anda membutuhkan pemecahan fase bawaan untuk metadata Plugin, discovery, registry,
runtime mirror, mutasi konfigurasi, dan pekerjaan refresh. Jejak ini bersifat opt-in dan menulis
ke stderr, sehingga keluaran perintah JSON tetap dapat di-parse.
Contoh:
@ -63,7 +63,7 @@ Contoh:
OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force
```
Contoh output:
Contoh keluaran:
```text
[plugins:lifecycle] phase="config read" ms=6.83 status=ok command="install"
@ -71,14 +71,14 @@ Contoh output:
[plugins:lifecycle] phase="registry refresh" ms=51.56 status=ok command="install" reason="source-changed"
```
Gunakan ini untuk investigasi siklus hidup Plugin sebelum memakai CPU profiler.
Jika perintah berjalan dari source checkout, sebaiknya ukur runtime hasil build
Gunakan ini untuk investigasi siklus hidup Plugin sebelum memakai profiler CPU.
Jika perintah dijalankan dari checkout sumber, lebih baik ukur runtime hasil build
dengan `node dist/entry.js ...` setelah `pnpm build`; `pnpm openclaw ...`
juga mengukur overhead source-runner.
## Startup CLI dan profiling perintah
Gunakan benchmark startup yang sudah disertakan saat sebuah perintah terasa lambat:
Gunakan benchmark startup yang sudah disertakan saat perintah terasa lambat:
```bash
pnpm test:startup:bench:smoke
@ -86,7 +86,7 @@ pnpm tsx scripts/bench-cli-startup.ts --preset real --case status --runs 3
pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu
```
Untuk profiling sekali pakai melalui source runner normal, atur
Untuk profiling sekali pakai melalui source runner normal, tetapkan
`OPENCLAW_RUN_NODE_CPU_PROF_DIR`:
```bash
@ -96,6 +96,16 @@ OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status
Source runner menambahkan flag profil CPU Node dan menulis `.cpuprofile` untuk
perintah tersebut. Gunakan ini sebelum menambahkan instrumentasi sementara ke kode perintah.
Untuk stall startup yang terlihat seperti pekerjaan filesystem sinkron atau module-loader,
tambahkan flag trace I/O sinkron Node melalui source runner:
```bash
OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force
```
`pnpm gateway:watch` mengaktifkan flag ini secara default untuk child Gateway yang dipantau.
Tetapkan `OPENCLAW_TRACE_SYNC_IO=0` untuk menekan keluaran trace I/O sinkron Node dalam mode watch.
## Mode watch Gateway
Untuk iterasi cepat, jalankan gateway di bawah file watcher:
@ -104,17 +114,17 @@ Untuk iterasi cepat, jalankan gateway di bawah file watcher:
pnpm gateway:watch
```
Secara default, ini memulai atau memulai ulang sesi tmux bernama
Secara default, ini memulai atau me-restart sesi tmux bernama
`openclaw-gateway-watch-main` (atau varian khusus profil/port seperti
`openclaw-gateway-watch-dev-19001`) dan otomatis attach dari terminal interaktif.
Shell noninteraktif, CI, dan panggilan exec agen tetap detached dan mencetak
instruksi attach sebagai gantinya. Attach secara manual saat diperlukan:
`openclaw-gateway-watch-dev-19001`) dan auto-attach dari terminal interaktif.
Shell non-interaktif, CI, dan panggilan exec agent tetap detached dan mencetak
instruksi attach sebagai gantinya. Attach secara manual bila perlu:
```bash
tmux attach -t openclaw-gateway-watch-main
```
Panel tmux menjalankan watcher mentah:
Pane tmux menjalankan watcher mentah:
```bash
node scripts/watch-node.mjs gateway --force
@ -134,57 +144,61 @@ Nonaktifkan auto-attach sambil tetap mempertahankan manajemen tmux:
OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch
```
Profilkan waktu CPU Gateway yang diawasi saat men-debug hotspot startup/runtime:
Profilkan waktu CPU Gateway yang dipantau saat men-debug hotspot startup/runtime:
```bash
pnpm gateway:watch --benchmark
```
Wrapper watch mengonsumsi `--benchmark` sebelum memanggil Gateway dan menulis
satu `.cpuprofile` V8 per exit child Gateway di bawah
`.artifacts/gateway-watch-profiles/`. Hentikan atau mulai ulang gateway yang diawasi untuk
flush profil saat ini, lalu buka dengan Chrome DevTools atau Speedscope:
Wrapper watch memakai `--benchmark` sebelum memanggil Gateway dan menulis
satu `.cpuprofile` V8 per keluarnya child Gateway di bawah
`.artifacts/gateway-watch-profiles/`. Hentikan atau restart gateway yang dipantau untuk
mengosongkan profil saat ini, lalu buka dengan Chrome DevTools atau Speedscope:
```bash
npx speedscope .artifacts/gateway-watch-profiles/*.cpuprofile
```
Gunakan `--benchmark-dir <path>` saat Anda ingin profil berada di tempat lain.
Gunakan `--benchmark-no-force` saat Anda ingin child yang di-benchmark melewati
pembersihan port default `--force` dan gagal cepat jika port Gateway sudah
digunakan.
Gunakan `--benchmark-dir <path>` saat Anda ingin menyimpan profil di tempat lain.
Gunakan `--benchmark-no-force` saat Anda ingin child yang dibenchmark melewati
cleanup port `--force` default dan gagal cepat jika port Gateway sudah digunakan.
Mode benchmark menekan spam trace sync-I/O secara default. Tetapkan
`OPENCLAW_TRACE_SYNC_IO=1` dengan `--benchmark` saat Anda secara eksplisit menginginkan profil CPU
dan stack trace sync-I/O Node sekaligus. Dalam mode benchmark, blok trace tersebut
ditulis ke `gateway-watch-output.log` di bawah direktori benchmark dan
difilter dari pane terminal; log Gateway normal tetap terlihat.
Wrapper tmux membawa selector runtime nonrahasia umum seperti
Wrapper tmux membawa selector runtime non-rahasia yang umum seperti
`OPENCLAW_PROFILE`, `OPENCLAW_CONFIG_PATH`, `OPENCLAW_STATE_DIR`,
`OPENCLAW_GATEWAY_PORT`, dan `OPENCLAW_SKIP_CHANNELS` ke dalam panel. Letakkan
`OPENCLAW_GATEWAY_PORT`, dan `OPENCLAW_SKIP_CHANNELS` ke dalam pane. Letakkan
kredensial provider di profil/konfigurasi normal Anda, atau gunakan mode foreground mentah
untuk secret sementara sekali pakai.
Jika Gateway yang diawasi keluar saat startup, watcher menjalankan
`openclaw doctor --fix --non-interactive` sekali dan memulai ulang child Gateway.
Gunakan `OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0` saat Anda menginginkan kegagalan startup
asli tanpa pass perbaikan khusus dev.
Panel tmux terkelola juga default-nya menggunakan log Gateway berwarna agar mudah dibaca;
atur `FORCE_COLOR=0` saat memulai `pnpm gateway:watch` untuk menonaktifkan output ANSI.
untuk rahasia ephemeral sekali pakai.
Jika Gateway yang dipantau keluar saat startup, watcher menjalankan
`openclaw doctor --fix --non-interactive` sekali dan me-restart child Gateway.
Gunakan `OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0` saat Anda menginginkan kegagalan startup asli
tanpa pass perbaikan khusus dev.
Pane tmux terkelola juga default ke log Gateway berwarna agar mudah dibaca;
tetapkan `FORCE_COLOR=0` saat memulai `pnpm gateway:watch` untuk menonaktifkan keluaran ANSI.
Watcher memulai ulang saat ada file relevan-build di bawah `src/`, file sumber extension,
Watcher me-restart pada file yang relevan dengan build di bawah `src/`, file sumber extension,
metadata `package.json` dan `openclaw.plugin.json` extension, `tsconfig.json`,
`package.json`, dan `tsdown.config.ts`. Perubahan metadata extension memulai ulang
`package.json`, dan `tsdown.config.ts`. Perubahan metadata extension me-restart
gateway tanpa memaksa rebuild `tsdown`; perubahan sumber dan konfigurasi tetap
membangun ulang `dist` terlebih dahulu.
Tambahkan flag CLI gateway apa pun setelah `gateway:watch` dan flag tersebut akan diteruskan pada
setiap restart. Menjalankan ulang perintah watch yang sama akan respawn panel tmux bernama, dan
watcher mentah tetap mempertahankan kunci single-watcher sehingga parent watcher duplikat
diganti, bukan menumpuk.
setiap restart. Menjalankan ulang perintah watch yang sama akan respawn pane tmux bernama tersebut, dan
watcher mentah tetap menjaga single-watcher lock sehingga parent watcher duplikat
diganti alih-alih menumpuk.
## Profil dev + Gateway dev (--dev)
## Profil dev + gateway dev (--dev)
Gunakan profil dev untuk mengisolasi state dan menjalankan setup yang aman dan dapat dibuang untuk
Gunakan profil dev untuk mengisolasi state dan menjalankan setup aman yang dapat dibuang untuk
debugging. Ada **dua** flag `--dev`:
- **`--dev` global (profil):** mengisolasi state di bawah `~/.openclaw-dev` dan
default port gateway ke `19001` (port turunan bergeser bersamanya).
- **`gateway --dev`: memberi tahu Gateway untuk otomatis membuat konfigurasi +
- **Global `--dev` (profil):** mengisolasi state di bawah `~/.openclaw-dev` dan
menetapkan port gateway default ke `19001` (port turunan ikut bergeser).
- **`gateway --dev`: memberi tahu Gateway untuk membuat otomatis konfigurasi +
workspace default** saat belum ada (dan melewati BOOTSTRAP.md).
Alur yang direkomendasikan (profil dev + bootstrap dev):
@ -198,29 +212,29 @@ Jika Anda belum memiliki instalasi global, jalankan CLI melalui `pnpm openclaw .
Yang dilakukan ini:
1. **Isolasi profil** (`--dev` global)
1. **Isolasi profil** (global `--dev`)
- `OPENCLAW_PROFILE=dev`
- `OPENCLAW_STATE_DIR=~/.openclaw-dev`
- `OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json`
- `OPENCLAW_GATEWAY_PORT=19001` (browser/canvas bergeser sesuai itu)
- `OPENCLAW_GATEWAY_PORT=19001` (browser/canvas ikut bergeser)
2. **Bootstrap dev** (`gateway --dev`)
- Menulis konfigurasi minimal jika belum ada (`gateway.mode=local`, bind loopback).
- Mengatur `agent.workspace` ke workspace dev.
- Mengatur `agent.skipBootstrap=true` (tanpa BOOTSTRAP.md).
- Menanam file workspace jika belum ada:
- Menetapkan `agent.workspace` ke workspace dev.
- Menetapkan `agent.skipBootstrap=true` (tanpa BOOTSTRAP.md).
- Menyemai file workspace jika belum ada:
`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`.
- Identitas default: **C3‑PO** (droid protokol).
- Melewati provider channel dalam mode dev (`OPENCLAW_SKIP_CHANNELS=1`).
Alur reset (mulai baru):
Alur reset (awal baru):
```bash
pnpm gateway:dev:reset
```
<Note>
`--dev` adalah flag profil **global** dan dimakan oleh beberapa runner. Jika Anda perlu menuliskannya secara eksplisit, gunakan bentuk env var:
`--dev` adalah flag profil **global** dan dimakan oleh beberapa runner. Jika Anda perlu menuliskannya eksplisit, gunakan bentuk env var:
```bash
OPENCLAW_PROFILE=dev openclaw gateway --dev --reset
@ -240,9 +254,9 @@ openclaw gateway stop
</Tip>
## Pencatatan stream mentah (OpenClaw)
## Logging stream mentah (OpenClaw)
OpenClaw dapat mencatat **stream assistant mentah** sebelum pemfilteran/pemformatan apa pun.
OpenClaw dapat mencatat **stream assistant mentah** sebelum filtering/formatting apa pun.
Ini adalah cara terbaik untuk melihat apakah reasoning datang sebagai delta teks biasa
(atau sebagai blok thinking terpisah).
@ -269,7 +283,7 @@ File default:
`~/.openclaw/logs/raw-stream.jsonl`
## Pencatatan chunk mentah (pi-mono)
## Logging chunk mentah (pi-mono)
Untuk menangkap **chunk kompatibel OpenAI mentah** sebelum di-parse menjadi blok,
pi-mono mengekspos logger terpisah:
@ -288,14 +302,14 @@ File default:
`~/.pi-mono/logs/raw-openai-completions.jsonl`
> Catatan: ini hanya dipancarkan oleh proses yang menggunakan provider
> Catatan: ini hanya dikeluarkan oleh proses yang menggunakan provider
> `openai-completions` milik pi-mono.
## Catatan keamanan
## Catatan keselamatan
- Log stream mentah dapat menyertakan prompt lengkap, output tool, dan data pengguna.
- Log stream mentah dapat mencakup prompt lengkap, keluaran tool, dan data pengguna.
- Simpan log secara lokal dan hapus setelah debugging.
- Jika Anda membagikan log, bersihkan secret dan PII terlebih dahulu.
- Jika Anda membagikan log, bersihkan rahasia dan PII terlebih dahulu.
## Terkait

235
docs/id/help/faq-models.md
View File

@ -1,24 +1,24 @@
---
read_when:
- Memilih atau beralih model, mengonfigurasi alias
- Debugging failover model / "Semua model gagal"
- Pemecahan masalah pengalihan kegagalan model / "Semua model gagal"
- Memahami profil autentikasi dan cara mengelolanya
sidebarTitle: Models FAQ
summary: 'FAQ: pengaturan bawaan model, pemilihan, alias, penggantian, peralihan saat gagal, dan profil autentikasi'
summary: 'FAQ: default model, pemilihan, alias, pergantian, failover, dan profil auth'
title: 'Tanya Jawab: model dan autentikasi'
x-i18n:
generated_at: "2026-05-02T09:23:19Z"
generated_at: "2026-05-05T01:47:04Z"
model: gpt-5.5
provider: openai
source_hash: 1bf7a6bb4a0e2bf791c73dbb4005ba4628afc2c20e06417f8147f4c65583e884
source_hash: 1e60abcd6aa99121200de0e45cc3efa6334e668cbe6a4b590610c53d17e03a54
source_path: help/faq-models.md
workflow: 16
---
Tanya jawab model dan profil autentikasi. Untuk penyiapan, sesi, Gateway, channel, dan
Tanya jawab model dan profil autentikasi. Untuk penyiapan, sesi, gateway, saluran, dan
pemecahan masalah, lihat [FAQ](/id/help/faq) utama.
## Model: default, pemilihan, alias, pergantian
## Model: default, pemilihan, alias, peralihan
<AccordionGroup>
<Accordion title='Apa itu "model default"?'>
@ -28,51 +28,51 @@ x-i18n:
agents.defaults.model.primary
```
Model dirujuk sebagai `provider/model` (contoh: `openai/gpt-5.5` atau `openai-codex/gpt-5.5`). Jika Anda menghilangkan provider, OpenClaw pertama-tama mencoba alias, lalu kecocokan provider terkonfigurasi yang unik untuk id model persis tersebut, dan baru setelah itu kembali ke provider default terkonfigurasi sebagai jalur kompatibilitas yang sudah tidak disarankan. Jika provider tersebut tidak lagi mengekspos model default terkonfigurasi, OpenClaw kembali ke provider/model terkonfigurasi pertama alih-alih menampilkan default provider yang sudah dihapus dan usang. Anda tetap sebaiknya menetapkan `provider/model` secara **eksplisit**.
Model direferensikan sebagai `provider/model` (contoh: `openai/gpt-5.5` atau `openai-codex/gpt-5.5`). Jika Anda menghilangkan penyedia, OpenClaw pertama-tama mencoba alias, lalu kecocokan penyedia terkonfigurasi unik untuk id model persis tersebut, dan baru setelah itu beralih ke penyedia default terkonfigurasi sebagai jalur kompatibilitas yang tidak lagi direkomendasikan. Jika penyedia tersebut tidak lagi mengekspos model default terkonfigurasi, OpenClaw beralih ke penyedia/model terkonfigurasi pertama alih-alih menampilkan default penyedia lama yang sudah dihapus. Anda tetap sebaiknya menetapkan `provider/model` secara **eksplisit**.
</Accordion>
<Accordion title="Model apa yang Anda rekomendasikan?">
**Default yang direkomendasikan:** gunakan model generasi terbaru terkuat yang tersedia di tumpukan provider Anda.
**Untuk agent yang mengaktifkan alat atau input yang tidak tepercaya:** prioritaskan kekuatan model di atas biaya.
**Untuk chat rutin/berisiko rendah:** gunakan model fallback yang lebih murah dan rutekan berdasarkan peran agent.
**Default yang direkomendasikan:** gunakan model generasi terbaru terkuat yang tersedia di tumpukan penyedia Anda.
**Untuk agen dengan alat aktif atau input tidak tepercaya:** prioritaskan kekuatan model dibanding biaya.
**Untuk obrolan rutin/risiko rendah:** gunakan model fallback yang lebih murah dan rutekan berdasarkan peran agen.
MiniMax memiliki dokumentasinya sendiri: [MiniMax](/id/providers/minimax) dan
[Model lokal](/id/gateway/local-models).
Aturan praktis: gunakan **model terbaik yang mampu Anda biayai** untuk pekerjaan berisiko tinggi, dan model yang lebih murah
untuk chat atau ringkasan rutin. Anda dapat merutekan model per agent dan menggunakan sub-agent untuk
memparalelkan tugas panjang (setiap sub-agent mengonsumsi token). Lihat [Model](/id/concepts/models) dan
[Sub-agent](/id/tools/subagents).
untuk obrolan rutin atau ringkasan. Anda dapat merutekan model per agen dan menggunakan sub-agen untuk
memparalelkan tugas panjang (setiap sub-agen menggunakan token). Lihat [Model](/id/concepts/models) dan
[Sub-agen](/id/tools/subagents).
Peringatan kuat: model yang lebih lemah/terkuantisasi berlebihan lebih rentan terhadap prompt
injection dan perilaku tidak aman. Lihat [Keamanan](/id/gateway/security).
Peringatan kuat: model yang lebih lemah/terlalu terkuantisasi lebih rentan terhadap injeksi prompt
dan perilaku tidak aman. Lihat [Keamanan](/id/gateway/security).
Konteks lebih lanjut: [Model](/id/concepts/models).
Konteks tambahan: [Model](/id/concepts/models).
</Accordion>
<Accordion title="Bagaimana cara mengganti model tanpa menghapus config saya?">
Gunakan **perintah model** atau edit hanya bidang **model**. Hindari penggantian config penuh.
<Accordion title="Bagaimana cara mengganti model tanpa menghapus konfigurasi saya?">
Gunakan **perintah model** atau edit hanya kolom **model**. Hindari penggantian konfigurasi penuh.
Opsi aman:
- `/model` di chat (cepat, per sesi)
- `openclaw models set ...` (hanya memperbarui config model)
- `/model` di obrolan (cepat, per sesi)
- `openclaw models set ...` (hanya memperbarui konfigurasi model)
- `openclaw configure --section model` (interaktif)
- edit `agents.defaults.model` di `~/.openclaw/openclaw.json`
Hindari `config.apply` dengan objek parsial kecuali Anda memang ingin mengganti seluruh config.
Untuk edit RPC, periksa dengan `config.schema.lookup` terlebih dahulu dan lebih pilih `config.patch`. Payload lookup memberi Anda jalur ternormalisasi, dokumen/kendala skema dangkal, dan ringkasan child langsung.
Hindari `config.apply` dengan objek parsial kecuali Anda memang bermaksud mengganti seluruh konfigurasi.
Untuk edit RPC, inspeksi terlebih dahulu dengan `config.schema.lookup` dan utamakan `config.patch`. Payload lookup memberi Anda jalur yang dinormalisasi, dokumentasi/kendala skema dangkal, dan ringkasan turunan langsung.
untuk pembaruan parsial.
Jika Anda menimpa config, pulihkan dari cadangan atau jalankan ulang `openclaw doctor` untuk memperbaiki.
Jika Anda menimpa konfigurasi, pulihkan dari cadangan atau jalankan ulang `openclaw doctor` untuk memperbaikinya.
Dokumentasi: [Model](/id/concepts/models), [Configure](/id/cli/configure), [Config](/id/cli/config), [Doctor](/id/gateway/doctor).
</Accordion>
<Accordion title="Bisakah saya menggunakan model yang di-host sendiri (llama.cpp, vLLM, Ollama)?">
Ya. Ollama adalah jalur termudah untuk model lokal.
Bisa. Ollama adalah jalur termudah untuk model lokal.
Penyiapan tercepat:
@ -85,23 +85,23 @@ x-i18n:
Catatan:
- `Cloud + Local` memberi Anda model cloud plus model Ollama lokal Anda
- model cloud seperti `kimi-k2.5:cloud` tidak memerlukan pull lokal
- untuk pergantian manual, gunakan `openclaw models list` dan `openclaw models set ollama/<model>`
- model cloud seperti `kimi-k2.5:cloud` tidak memerlukan penarikan lokal
- untuk peralihan manual, gunakan `openclaw models list` dan `openclaw models set ollama/<model>`
Catatan keamanan: model yang lebih kecil atau sangat terkuantisasi lebih rentan terhadap prompt
injection. Kami sangat merekomendasikan **model besar** untuk bot apa pun yang dapat menggunakan alat.
Catatan keamanan: model yang lebih kecil atau sangat terkuantisasi lebih rentan terhadap injeksi prompt.
Kami sangat merekomendasikan **model besar** untuk bot apa pun yang dapat menggunakan alat.
Jika Anda tetap ingin model kecil, aktifkan sandboxing dan allowlist alat yang ketat.
Dokumentasi: [Ollama](/id/providers/ollama), [Model lokal](/id/gateway/local-models),
[Provider model](/id/concepts/model-providers), [Keamanan](/id/gateway/security),
[Penyedia model](/id/concepts/model-providers), [Keamanan](/id/gateway/security),
[Sandboxing](/id/gateway/sandboxing).
</Accordion>
<Accordion title="Apa yang digunakan OpenClaw, Flawd, dan Krill untuk model?">
- Deployment ini dapat berbeda dan dapat berubah seiring waktu; tidak ada rekomendasi provider tetap.
- Periksa pengaturan runtime saat ini di setiap Gateway dengan `openclaw models status`.
- Untuk agent yang sensitif keamanan/mengaktifkan alat, gunakan model generasi terbaru terkuat yang tersedia.
<Accordion title="Model apa yang digunakan OpenClaw, Flawd, dan Krill?">
- Deployment ini dapat berbeda dan dapat berubah seiring waktu; tidak ada rekomendasi penyedia tetap.
- Periksa pengaturan runtime saat ini pada setiap gateway dengan `openclaw models status`.
- Untuk agen yang sensitif terhadap keamanan/menggunakan alat, gunakan model generasi terbaru terkuat yang tersedia.
</Accordion>
@ -118,29 +118,29 @@ x-i18n:
/model gemini-flash-lite
```
Ini adalah alias bawaan. Alias kustom dapat ditambahkan melalui `agents.defaults.models`.
Ini adalah alias bawaan. Alias khusus dapat ditambahkan melalui `agents.defaults.models`.
Anda dapat mencantumkan model yang tersedia dengan `/model`, `/model list`, atau `/model status`.
`/model` (dan `/model list`) menampilkan pemilih ringkas bernomor. Pilih berdasarkan nomor:
`/model` (dan `/model list`) menampilkan pemilih bernomor yang ringkas. Pilih berdasarkan nomor:
```
/model 3
```
Anda juga dapat memaksa profil autentikasi tertentu untuk provider (per sesi):
Anda juga dapat memaksa profil autentikasi tertentu untuk penyedia (per sesi):
```
/model opus@anthropic:default
/model opus@anthropic:work
```
Tip: `/model status` menampilkan agent mana yang aktif, file `auth-profiles.json` mana yang digunakan, dan profil autentikasi mana yang akan dicoba berikutnya.
Ini juga menampilkan endpoint provider terkonfigurasi (`baseUrl`) dan mode API (`api`) jika tersedia.
Tip: `/model status` menampilkan agen mana yang aktif, file `auth-profiles.json` mana yang digunakan, dan profil autentikasi mana yang akan dicoba berikutnya.
Perintah ini juga menampilkan endpoint penyedia terkonfigurasi (`baseUrl`) dan mode API (`api`) jika tersedia.
**Bagaimana cara melepas pin profil yang saya tetapkan dengan @profile?**
**Bagaimana cara melepas sematan profil yang saya tetapkan dengan @profile?**
Jalankan ulang `/model` **tanpa** sufiks `@profile`:
Jalankan ulang `/model` **tanpa** akhiran `@profile`:
```
/model anthropic/claude-opus-4-6
@ -152,19 +152,19 @@ x-i18n:
</Accordion>
<Accordion title="Bisakah saya menggunakan GPT 5.5 untuk tugas harian dan Codex 5.5 untuk coding?">
Ya. Perlakukan pilihan model dan pilihan runtime secara terpisah:
Bisa. Perlakukan pilihan model dan pilihan runtime secara terpisah:
- **Agent coding Codex native:** tetapkan `agents.defaults.model.primary` ke `openai/gpt-5.5` dan `agents.defaults.agentRuntime.id` ke `"codex"`. Masuk dengan `openclaw models auth login --provider openai-codex` ketika Anda ingin autentikasi langganan ChatGPT/Codex.
- **Agen coding Codex native:** tetapkan `agents.defaults.model.primary` ke `openai/gpt-5.5` dan `agents.defaults.agentRuntime.id` ke `"codex"`. Masuk dengan `openclaw models auth login --provider openai-codex` saat Anda ingin autentikasi langganan ChatGPT/Codex.
- **Tugas OpenAI API langsung melalui PI:** gunakan `/model openai/gpt-5.5` tanpa override runtime Codex dan konfigurasikan `OPENAI_API_KEY`.
- **Codex OAuth melalui PI:** gunakan `/model openai-codex/gpt-5.5` hanya ketika Anda sengaja menginginkan runner PI normal dengan Codex OAuth.
- **Sub-agent:** rutekan tugas coding ke agent khusus Codex dengan model dan default `agentRuntime` miliknya sendiri.
- **Codex OAuth melalui PI:** gunakan `/model openai-codex/gpt-5.5` hanya saat Anda sengaja menginginkan runner PI normal dengan Codex OAuth.
- **Sub-agen:** rutekan tugas coding ke agen khusus Codex dengan model dan default `agentRuntime` miliknya sendiri.
Lihat [Model](/id/concepts/models) dan [Perintah slash](/id/tools/slash-commands).
</Accordion>
<Accordion title="Bagaimana cara mengonfigurasi mode cepat untuk GPT 5.5?">
Gunakan toggle sesi atau default config:
Gunakan toggle sesi atau default konfigurasi:
- **Per sesi:** kirim `/fast on` saat sesi menggunakan `openai/gpt-5.5` atau `openai-codex/gpt-5.5`.
- **Default per model:** tetapkan `agents.defaults.models["openai/gpt-5.5"].params.fastMode` atau `agents.defaults.models["openai-codex/gpt-5.5"].params.fastMode` ke `true`.
@ -187,39 +187,42 @@ x-i18n:
}
```
Untuk OpenAI, mode cepat dipetakan ke `service_tier = "priority"` pada permintaan Responses native yang didukung. Override sesi `/fast` mengalahkan default config.
Untuk OpenAI, mode cepat dipetakan ke `service_tier = "priority"` pada permintaan Responses native yang didukung. Override `/fast` sesi mengungguli default konfigurasi.
Lihat [Thinking dan mode cepat](/id/tools/thinking) dan [mode cepat OpenAI](/id/providers/openai#fast-mode).
Lihat [Berpikir dan mode cepat](/id/tools/thinking) dan [Mode cepat OpenAI](/id/providers/openai#fast-mode).
</Accordion>
<Accordion title='Mengapa saya melihat "Model ... is not allowed" lalu tidak ada balasan?'>
Jika `agents.defaults.models` ditetapkan, itu menjadi **allowlist** untuk `/model` dan override
sesi apa pun. Memilih model yang tidak ada dalam daftar tersebut menghasilkan:
sesi apa pun. Memilih model yang tidak ada dalam daftar tersebut mengembalikan:
```
Model "provider/model" is not allowed. Use /model to list available models.
Model "provider/model" is not allowed. Use /models to list providers, or /models <provider> to list models.
Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge
```
Error tersebut dikembalikan **alih-alih** balasan normal. Perbaikan: tambahkan model ke
Error tersebut dikembalikan **sebagai pengganti** balasan normal. Perbaikan: tambahkan model ke
`agents.defaults.models`, hapus allowlist, atau pilih model dari `/model list`.
Jika perintah juga menyertakan `--runtime codex`, tambahkan model terlebih dahulu lalu coba ulang
perintah `/model provider/model --runtime codex` yang sama.
</Accordion>
<Accordion title='Mengapa saya melihat "Unknown model: minimax/MiniMax-M2.7"?'>
Ini berarti **provider belum dikonfigurasi** (tidak ditemukan config provider MiniMax atau profil
autentikasi), sehingga model tidak dapat di-resolve.
Ini berarti **penyedia belum dikonfigurasi** (tidak ada konfigurasi penyedia MiniMax atau profil autentikasi
yang ditemukan), sehingga model tidak dapat di-resolve.
Daftar periksa perbaikan:
Checklist perbaikan:
1. Tingkatkan ke rilis OpenClaw saat ini (atau jalankan dari source `main`), lalu mulai ulang Gateway.
1. Tingkatkan ke rilis OpenClaw saat ini (atau jalankan dari source `main`), lalu mulai ulang gateway.
2. Pastikan MiniMax dikonfigurasi (wizard atau JSON), atau autentikasi MiniMax
ada di env/profil autentikasi sehingga provider yang cocok dapat diinjeksi
ada di profil env/autentikasi sehingga penyedia yang cocok dapat diinjeksi
(`MINIMAX_API_KEY` untuk `minimax`, `MINIMAX_OAUTH_TOKEN` atau OAuth MiniMax
tersimpan untuk `minimax-portal`).
3. Gunakan id model persis (peka huruf besar-kecil) untuk jalur autentikasi Anda:
3. Gunakan id model persis (peka huruf besar/kecil) untuk jalur autentikasi Anda:
`minimax/MiniMax-M2.7` atau `minimax/MiniMax-M2.7-highspeed` untuk penyiapan
API key, atau `minimax-portal/MiniMax-M2.7` /
kunci API, atau `minimax-portal/MiniMax-M2.7` /
`minimax-portal/MiniMax-M2.7-highspeed` untuk penyiapan OAuth.
4. Jalankan:
@ -227,15 +230,15 @@ x-i18n:
openclaw models list
```
dan pilih dari daftar (atau `/model list` di chat).
dan pilih dari daftar (atau `/model list` di obrolan).
Lihat [MiniMax](/id/providers/minimax) dan [Model](/id/concepts/models).
</Accordion>
<Accordion title="Bisakah saya menggunakan MiniMax sebagai default dan OpenAI untuk tugas kompleks?">
Ya. Gunakan **MiniMax sebagai default** dan ganti model **per sesi** saat diperlukan.
Fallback adalah untuk **error**, bukan "tugas sulit", jadi gunakan `/model` atau agent terpisah.
Bisa. Gunakan **MiniMax sebagai default** dan ganti model **per sesi** saat diperlukan.
Fallback adalah untuk **error**, bukan "tugas sulit", jadi gunakan `/model` atau agen terpisah.
**Opsi A: ganti per sesi**
@ -260,22 +263,22 @@ x-i18n:
/model gpt
```
**Opsi B: agent terpisah**
**Opsi B: agen terpisah**
- Default Agent A: MiniMax
- Default Agent B: OpenAI
- Rutekan berdasarkan agent atau gunakan `/agent` untuk beralih
- Default Agen A: MiniMax
- Default Agen B: OpenAI
- Rutekan berdasarkan agen atau gunakan `/agent` untuk beralih
Dokumentasi: [Model](/id/concepts/models), [Routing Multi-Agent](/id/concepts/multi-agent), [MiniMax](/id/providers/minimax), [OpenAI](/id/providers/openai).
Dokumentasi: [Model](/id/concepts/models), [Perutean Multi-Agen](/id/concepts/multi-agent), [MiniMax](/id/providers/minimax), [OpenAI](/id/providers/openai).
</Accordion>
<Accordion title="Apakah opus / sonnet / gpt adalah pintasan bawaan?">
Ya. OpenClaw menyertakan beberapa singkatan default (hanya diterapkan ketika model ada di `agents.defaults.models`):
Ya. OpenClaw menyertakan beberapa singkatan default (hanya diterapkan saat model ada di `agents.defaults.models`):
- `opus` → `anthropic/claude-opus-4-6`
- `sonnet` → `anthropic/claude-sonnet-4-6`
- `gpt` → `openai/gpt-5.5` untuk penyiapan API key, atau `openai-codex/gpt-5.5` ketika dikonfigurasi untuk Codex OAuth
- `gpt` → `openai/gpt-5.5` untuk penyiapan kunci API, atau `openai-codex/gpt-5.5` saat dikonfigurasi untuk Codex OAuth
- `gpt-mini` → `openai/gpt-5.4-mini`
- `gpt-nano` → `openai/gpt-5.4-nano`
- `gemini` → `google/gemini-3.1-pro-preview`
@ -304,11 +307,11 @@ x-i18n:
}
```
Lalu `/model sonnet` (atau `/<alias>` jika didukung) di-resolve ke ID model tersebut.
Lalu `/model sonnet` (atau `/<alias>` saat didukung) di-resolve ke ID model tersebut.
</Accordion>
<Accordion title="Bagaimana cara menambahkan model dari provider lain seperti OpenRouter atau Z.AI?">
<Accordion title="Bagaimana cara menambahkan model dari penyedia lain seperti OpenRouter atau Z.AI?">
OpenRouter (bayar per token; banyak model):
```json5
@ -337,11 +340,11 @@ x-i18n:
}
```
Jika Anda merujuk penyedia/model tetapi kunci penyedia yang diperlukan tidak ada, Anda akan mendapatkan error autentikasi runtime (mis. `No API key found for provider "zai"`).
Jika Anda mereferensikan penyedia/model tetapi kunci penyedia yang diperlukan tidak ada, Anda akan mendapatkan kesalahan autentikasi runtime (misalnya `No API key found for provider "zai"`).
**Tidak ada kunci API yang ditemukan untuk penyedia setelah menambahkan agen baru**
**Tidak ditemukan kunci API untuk penyedia setelah menambahkan agen baru**
Ini biasanya berarti **agen baru** memiliki penyimpanan autentikasi kosong. Autentikasi bersifat per agen dan
Ini biasanya berarti **agen baru** memiliki penyimpanan autentikasi kosong. Autentikasi berlaku per agen dan
disimpan di:
```
@ -351,10 +354,10 @@ x-i18n:
Opsi perbaikan:
- Jalankan `openclaw agents add <id>` dan konfigurasikan autentikasi selama wizard.
- Atau salin hanya profil `api_key` / `token` statis portabel dari penyimpanan autentikasi agen utama ke penyimpanan autentikasi agen baru.
- Untuk profil OAuth, masuk dari agen baru ketika agen tersebut memerlukan akunnya sendiri; jika tidak, OpenClaw dapat membaca melalui agen default/utama tanpa mengkloning token refresh.
- Atau salin hanya profil `api_key` / `token` statis yang portabel dari penyimpanan autentikasi agen utama ke penyimpanan autentikasi agen baru.
- Untuk profil OAuth, masuk dari agen baru ketika agen tersebut membutuhkan akunnya sendiri; jika tidak, OpenClaw dapat membaca melalui agen default/utama tanpa mengkloning token refresh.
Jangan **gunakan ulang** `agentDir` di beberapa agen; itu menyebabkan benturan autentikasi/sesi.
Jangan **gunakan ulang** `agentDir` lintas agen; hal itu menyebabkan tabrakan autentikasi/sesi.
</Accordion>
</AccordionGroup>
@ -368,39 +371,39 @@ x-i18n:
1. **Rotasi profil autentikasi** dalam penyedia yang sama.
2. **Fallback model** ke model berikutnya di `agents.defaults.model.fallbacks`.
Cooldown berlaku untuk profil yang gagal (backoff eksponensial), sehingga OpenClaw dapat tetap merespons bahkan saat penyedia terkena pembatasan laju atau gagal sementara.
Cooldown berlaku untuk profil yang gagal (backoff eksponensial), sehingga OpenClaw dapat tetap merespons meskipun penyedia terkena rate limit atau gagal sementara.
Bucket pembatasan laju mencakup lebih dari respons `429` biasa. OpenClaw
Bucket rate-limit mencakup lebih dari sekadar respons `429`. OpenClaw
juga memperlakukan pesan seperti `Too many concurrent requests`,
`ThrottlingException`, `concurrency limit reached`,
`workers_ai ... quota limit exceeded`, `resource exhausted`, dan batas
jendela penggunaan berkala (`weekly/monthly limit reached`) sebagai
pembatasan laju yang layak memicu failover.
rate limit yang layak memicu failover.
Beberapa respons yang terlihat seperti penagihan bukan `402`, dan beberapa respons HTTP `402`
Sebagian respons yang tampak seperti penagihan bukan `402`, dan sebagian respons HTTP `402`
juga tetap berada dalam bucket sementara tersebut. Jika penyedia mengembalikan
teks penagihan eksplisit pada `401` atau `403`, OpenClaw masih dapat menempatkannya
di jalur penagihan, tetapi pencocok teks khusus penyedia tetap dibatasi pada
penyedia pemiliknya (misalnya OpenRouter `Key limit exceeded`). Jika pesan `402`
justru terlihat seperti jendela penggunaan yang dapat dicoba ulang atau
batas pengeluaran organisasi/ruang kerja (`daily limit reached, resets tomorrow`,
teks penagihan eksplisit pada `401` atau `403`, OpenClaw masih dapat tetap menempatkannya di
jalur penagihan, tetapi pencocok teks khusus penyedia tetap dibatasi pada
penyedia yang memilikinya (misalnya OpenRouter `Key limit exceeded`). Jika pesan `402`
malah terlihat seperti jendela penggunaan yang dapat dicoba ulang atau
batas pembelanjaan organisasi/workspace (`daily limit reached, resets tomorrow`,
`organization spending limit exceeded`), OpenClaw memperlakukannya sebagai
`rate_limit`, bukan penonaktifan penagihan jangka panjang.
Error kelebihan konteks berbeda: tanda seperti
Kesalahan luapan konteks berbeda: tanda seperti
`request_too_large`, `input exceeds the maximum number of tokens`,
`input token count exceeds the maximum number of input tokens`,
`input is too long for the model`, atau `ollama error: context length
exceeded` tetap berada di jalur Compaction/coba ulang alih-alih melanjutkan ke
exceeded` tetap berada pada jalur Compaction/coba ulang alih-alih melanjutkan
fallback model.
Teks error server generik sengaja dibuat lebih sempit daripada "apa pun yang
berisi unknown/error". OpenClaw memang memperlakukan bentuk sementara yang
dibatasi penyedia seperti Anthropic mentah `An unknown error occurred`, OpenRouter mentah
`Provider returned error`, error alasan berhenti seperti `Unhandled stop reason:
Teks kesalahan server generik sengaja lebih sempit daripada "apa pun yang berisi
unknown/error". OpenClaw memang memperlakukan bentuk sementara yang dibatasi penyedia
seperti Anthropic polos `An unknown error occurred`, OpenRouter polos
`Provider returned error`, kesalahan alasan berhenti seperti `Unhandled stop reason:
error`, payload JSON `api_error` dengan teks server sementara
(`internal server error`, `unknown error, 520`, `upstream error`, `backend
error`), dan error penyedia sibuk seperti `ModelNotReadyException` sebagai
error`), dan kesalahan penyedia sibuk seperti `ModelNotReadyException` sebagai
sinyal timeout/kelebihan beban yang layak memicu failover ketika konteks penyedia
cocok.
Teks fallback internal generik seperti `LLM request failed with an unknown
@ -408,89 +411,91 @@ x-i18n:
</Accordion>
<Accordion title='Apa arti "No credentials found for profile anthropic:default"?'>
Ini berarti sistem mencoba menggunakan ID profil autentikasi `anthropic:default`, tetapi tidak dapat menemukan kredensial untuknya di penyimpanan autentikasi yang diharapkan.
<Accordion title='Apa arti "Tidak ditemukan kredensial untuk profil anthropic:default"?'>
Ini berarti sistem mencoba menggunakan ID profil autentikasi `anthropic:default`, tetapi tidak dapat menemukan kredensialnya di penyimpanan autentikasi yang diharapkan.
**Daftar periksa perbaikan:**
- **Konfirmasi lokasi profil autentikasi berada** (jalur baru vs legacy)
- **Konfirmasi lokasi profil autentikasi berada** (jalur baru vs lama)
- Saat ini: `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
- Legacy: `~/.openclaw/agent/*` (dimigrasikan oleh `openclaw doctor`)
- Lama: `~/.openclaw/agent/*` (dimigrasikan oleh `openclaw doctor`)
- **Konfirmasi env var Anda dimuat oleh Gateway**
- Jika Anda menetapkan `ANTHROPIC_API_KEY` di shell tetapi menjalankan Gateway melalui systemd/launchd, Gateway mungkin tidak mewarisinya. Letakkan di `~/.openclaw/.env` atau aktifkan `env.shellEnv`.
- Jika Anda menetapkan `ANTHROPIC_API_KEY` di shell tetapi menjalankan Gateway melalui systemd/launchd, variabel itu mungkin tidak diwarisi. Letakkan di `~/.openclaw/.env` atau aktifkan `env.shellEnv`.
- **Pastikan Anda mengedit agen yang benar**
- Penyiapan multi-agen berarti bisa ada beberapa file `auth-profiles.json`.
- **Periksa kewajaran status model/autentikasi**
- Gunakan `openclaw models status` untuk melihat model yang dikonfigurasi dan apakah penyedia sudah diautentikasi.
**Daftar periksa perbaikan untuk "No credentials found for profile anthropic"**
**Daftar periksa perbaikan untuk "Tidak ditemukan kredensial untuk profil anthropic"**
Ini berarti proses run dipatok ke profil autentikasi Anthropic, tetapi Gateway
Ini berarti proses dijepit ke profil autentikasi Anthropic, tetapi Gateway
tidak dapat menemukannya di penyimpanan autentikasinya.
- **Gunakan Claude CLI**
- Jalankan `openclaw models auth login --provider anthropic --method cli --set-default` pada host gateway.
- **Jika Anda ingin menggunakan kunci API sebagai gantinya**
- Letakkan `ANTHROPIC_API_KEY` di `~/.openclaw/.env` pada **host gateway**.
- Hapus urutan terpancang yang memaksa profil yang tidak ada:
- Bersihkan urutan terpancang yang memaksa profil yang hilang:
```bash
openclaw models auth order clear --provider anthropic
```
- **Konfirmasi Anda menjalankan perintah pada host gateway**
- **Konfirmasi bahwa Anda menjalankan perintah pada host gateway**
- Dalam mode jarak jauh, profil autentikasi berada di mesin gateway, bukan laptop Anda.
</Accordion>
<Accordion title="Mengapa ia juga mencoba Google Gemini dan gagal?">
Jika konfigurasi model Anda menyertakan Google Gemini sebagai fallback (atau Anda beralih ke shorthand Gemini), OpenClaw akan mencobanya selama fallback model. Jika Anda belum mengonfigurasi kredensial Google, Anda akan melihat `No API key found for provider "google"`.
<Accordion title="Mengapa sistem juga mencoba Google Gemini dan gagal?">
Jika konfigurasi model Anda mencakup Google Gemini sebagai fallback (atau Anda beralih ke singkatan Gemini), OpenClaw akan mencobanya selama fallback model. Jika Anda belum mengonfigurasi kredensial Google, Anda akan melihat `No API key found for provider "google"`.
Perbaikan: sediakan autentikasi Google, atau hapus/hindari model Google di `agents.defaults.model.fallbacks` / alias agar fallback tidak diarahkan ke sana.
Perbaikan: sediakan autentikasi Google, atau hapus/hindari model Google di `agents.defaults.model.fallbacks` / alias agar fallback tidak merutekan ke sana.
**Permintaan LLM ditolak: tanda tangan thinking diperlukan (Google Antigravity)**
Penyebab: riwayat sesi berisi **blok thinking tanpa tanda tangan** (sering kali dari
stream yang dibatalkan/sebagian). Google Antigravity memerlukan tanda tangan untuk blok thinking.
Perbaikan: OpenClaw sekarang menghapus blok thinking tanpa tanda tangan untuk Google Antigravity Claude. Jika masih muncul, mulai **sesi baru** atau atur `/thinking off` untuk agen tersebut.
Perbaikan: OpenClaw kini menghapus blok thinking yang tidak bertanda tangan untuk Google Antigravity Claude. Jika masih muncul, mulai **sesi baru** atau tetapkan `/thinking off` untuk agen tersebut.
</Accordion>
</AccordionGroup>
## Profil autentikasi: apa itu dan cara mengelolanya
Terkait: [/konsep/oauth](/id/concepts/oauth) (alur OAuth, penyimpanan token, pola multi-akun)
Terkait: [/concepts/oauth](/id/concepts/oauth) (alur OAuth, penyimpanan token, pola multi-akun)
<AccordionGroup>
<Accordion title="Apa itu profil autentikasi?">
Profil autentikasi adalah catatan kredensial bernama (OAuth atau kunci API) yang terkait dengan penyedia. Profil berada di:
Profil autentikasi adalah catatan kredensial bernama (OAuth atau kunci API) yang terikat ke penyedia. Profil berada di:
```
~/.openclaw/agents/<agentId>/agent/auth-profiles.json
```
Untuk memeriksa profil tersimpan tanpa menampilkan rahasia, jalankan `openclaw models auth list` (opsional `--provider <id>` atau `--json`). Lihat [CLI Model](/id/cli/models#openclaw-models-auth-list) untuk detail.
</Accordion>
<Accordion title="Apa saja ID profil yang umum?">
OpenClaw menggunakan ID berawalan penyedia seperti:
OpenClaw menggunakan ID berprefiks penyedia seperti:
- `anthropic:default` (umum ketika tidak ada identitas email)
- `anthropic:<email>` untuk identitas OAuth
- ID kustom yang Anda pilih (mis. `anthropic:work`)
- ID khusus yang Anda pilih (misalnya `anthropic:work`)
</Accordion>
<Accordion title="Bisakah saya mengontrol profil autentikasi mana yang dicoba lebih dulu?">
<Accordion title="Bisakah saya mengontrol profil autentikasi mana yang dicoba terlebih dahulu?">
Ya. Konfigurasi mendukung metadata opsional untuk profil dan pengurutan per penyedia (`auth.order.<provider>`). Ini **tidak** menyimpan rahasia; ini memetakan ID ke penyedia/mode dan menetapkan urutan rotasi.
OpenClaw dapat melewati profil sementara jika profil tersebut berada dalam **cooldown** singkat (pembatasan laju/timeout/kegagalan autentikasi) atau status **dinonaktifkan** yang lebih lama (penagihan/kredit tidak mencukupi). Untuk memeriksanya, jalankan `openclaw models status --json` dan periksa `auth.unusableProfiles`. Penyetelan: `auth.cooldowns.billingBackoffHours*`.
OpenClaw dapat melewati profil untuk sementara jika profil berada dalam **cooldown** singkat (rate limit/timeout/kegagalan autentikasi) atau status **disabled** yang lebih lama (penagihan/kredit tidak cukup). Untuk memeriksanya, jalankan `openclaw models status --json` dan periksa `auth.unusableProfiles`. Penyetelan: `auth.cooldowns.billingBackoffHours*`.
Cooldown pembatasan laju dapat dibatasi per model. Profil yang sedang cooling down
Cooldown rate-limit dapat dibatasi per model. Profil yang sedang cooldown
untuk satu model masih dapat digunakan untuk model saudara pada penyedia yang sama,
sementara jendela penagihan/dinonaktifkan tetap memblokir seluruh profil.
sementara jendela penagihan/disabled tetap memblokir seluruh profil.
Anda juga dapat menetapkan override urutan **per agen** (disimpan di `auth-state.json` milik agen tersebut) melalui CLI:
Anda juga dapat menetapkan override urutan **per agen** (disimpan di `auth-state.json` agen tersebut) melalui CLI:
```bash
# Defaults to the configured default agent (omit --agent)
@ -519,7 +524,7 @@ Terkait: [/konsep/oauth](/id/concepts/oauth) (alur OAuth, penyimpanan token, pol
```
Jika profil tersimpan dihilangkan dari urutan eksplisit, probe melaporkan
`excluded_by_auth_order` untuk profil tersebut alih-alih mencobanya secara diam-diam.
`excluded_by_auth_order` untuk profil tersebut alih-alih mencobanya diam-diam.
</Accordion>
@ -537,6 +542,6 @@ Terkait: [/konsep/oauth](/id/concepts/oauth) (alur OAuth, penyimpanan token, pol
## Terkait
- [FAQ](/id/help/faq) — FAQ utama
- [FAQ — mulai cepat dan penyiapan run pertama](/id/help/faq-first-run)
- [FAQ — mulai cepat dan penyiapan pertama kali](/id/help/faq-first-run)
- [Pemilihan model](/id/concepts/model-providers)
- [Failover model](/id/concepts/model-failover)

246
docs/id/help/testing-updates-plugins.md
View File

@ -1,52 +1,53 @@
---
read_when:
- Mengubah perilaku pembaruan OpenClaw, doctor, penerimaan paket, atau pemasangan plugin
- Mengubah perilaku pembaruan, doctor, penerimaan paket, atau penginstalan Plugin OpenClaw
- Menyiapkan atau menyetujui kandidat rilis
- Men-debug regresi pembaruan paket, pembersihan dependensi Plugin, atau instalasi Plugin
- Men-debug pembaruan paket, pembersihan dependensi Plugin, atau regresi instalasi Plugin
sidebarTitle: Update and plugin tests
summary: Cara OpenClaw memvalidasi jalur pembaruan, migrasi paket, dan perilaku instalasi/pembaruan Plugin
summary: Cara OpenClaw memvalidasi jalur pembaruan, migrasi paket, dan perilaku pemasangan/pembaruan Plugin
title: 'Pengujian: pembaruan dan Plugin'
x-i18n:
generated_at: "2026-05-03T09:17:26Z"
generated_at: "2026-05-05T01:47:24Z"
model: gpt-5.5
provider: openai
source_hash: 309ac7785a8d49db241989d28580887d3f6739982108af7148b624082c5f23dd
source_hash: e83a847c76f424199b5fccbd9a2b30d0bf01e4f466c4f9822bf7693d1c2ad286
source_path: help/testing-updates-plugins.md
workflow: 16
---
Ini adalah daftar periksa khusus untuk validasi pembaruan dan Plugin. Tujuannya
sederhana: membuktikan bahwa paket yang dapat diinstal dapat memperbarui status
pengguna nyata, memperbaiki status warisan yang usang melalui `doctor`, dan tetap
dapat menginstal, memuat, memperbarui, serta menghapus Plugin dari sumber yang
didukung.
pengguna nyata, memperbaiki status legacy yang basi melalui `doctor`, dan tetap
dapat menginstal, memuat, memperbarui, serta menghapus instalasi
Plugin dari sumber yang didukung.
Untuk peta runner pengujian yang lebih luas, lihat [Pengujian](/id/help/testing). Untuk kunci penyedia langsung
dan suite yang menyentuh jaringan, lihat [Pengujian langsung](/id/help/testing-live).
Untuk peta test runner yang lebih luas, lihat [Pengujian](/id/help/testing). Untuk
kunci penyedia live dan rangkaian yang menyentuh jaringan, lihat [Pengujian live](/id/help/testing-live).
## Yang kami lindungi
Pengujian pembaruan dan Plugin melindungi kontrak berikut:
- Tarball paket lengkap, memiliki `dist/postinstall-inventory.json` yang valid,
dan tidak bergantung pada file repo yang belum dikemas.
dan tidak bergantung pada file repo yang belum dipaketkan.
- Pengguna dapat berpindah dari paket terbitan lama ke paket kandidat
tanpa kehilangan konfigurasi, agen, sesi, workspace, daftar izin Plugin, atau
konfigurasi channel.
- `openclaw doctor --fix --non-interactive` memiliki jalur pembersihan dan perbaikan
warisan. Startup tidak boleh menambahkan migrasi kompatibilitas tersembunyi untuk status
Plugin yang usang.
- Instalasi Plugin berfungsi dari direktori lokal, repo git, paket npm, dan jalur
registri ClawHub.
tanpa kehilangan config, agent, sesi, workspace, allowlist Plugin, atau
config channel.
- `openclaw doctor --fix --non-interactive` memiliki jalur pembersihan dan
perbaikan legacy. Startup tidak boleh menambah migrasi kompatibilitas
tersembunyi untuk status Plugin yang basi.
- Instalasi Plugin berfungsi dari direktori lokal, repo git, paket npm, dan
jalur registri ClawHub.
- Dependensi npm Plugin diinstal di root npm terkelola, dipindai sebelum
dipercaya, dan dihapus melalui npm saat uninstall agar dependensi hoisted tidak
tertinggal.
- Pembaruan Plugin stabil ketika tidak ada yang berubah: catatan instalasi, sumber
yang di-resolve, tata letak dependensi terinstal, dan status aktif tetap utuh.
dipercaya, dan dihapus melalui npm saat uninstall sehingga dependensi yang
dihoist tidak tertinggal.
- Pembaruan Plugin stabil ketika tidak ada yang berubah: catatan instalasi,
sumber yang di-resolve, tata letak dependensi terinstal, dan status aktif
tetap utuh.
## Pembuktian lokal selama pengembangan
## Bukti lokal selama pengembangan
Mulai secara sempit:
Mulai dari yang sempit:
```bash
pnpm changed:lanes --json
@ -54,8 +55,8 @@ pnpm check:changed
pnpm test:changed
```
Untuk perubahan instalasi, uninstall, dependensi, atau inventaris paket Plugin, jalankan juga
pengujian terfokus yang mencakup seam yang diedit:
Untuk perubahan instalasi Plugin, uninstall, dependensi, atau inventaris paket,
jalankan juga pengujian terfokus yang mencakup seam yang diedit:
```bash
pnpm test src/plugins/uninstall.test.ts src/infra/package-dist-inventory.test.ts test/scripts/package-acceptance-workflow.test.ts
@ -67,16 +68,16 @@ Sebelum lane Docker paket mana pun menggunakan tarball, buktikan artefak paket:
pnpm release:check
```
`release:check` menjalankan pemeriksaan drift konfigurasi/dokumen/API, menulis inventaris dist
paket, menjalankan `npm pack --dry-run`, menolak file terlarang yang terkema, menginstal
tarball ke prefix sementara, menjalankan postinstall, dan melakukan smoke pada entrypoint channel
bawaan.
`release:check` menjalankan pemeriksaan drift config/docs/API, menulis inventaris
dist paket, menjalankan `npm pack --dry-run`, menolak file terlarang yang ikut
dipaketkan, menginstal tarball ke prefix sementara, menjalankan postinstall, dan
melakukan smoke pada entrypoint channel bawaan.
## Lane Docker
Lane Docker adalah pembuktian tingkat produk. Lane ini menginstal atau memperbarui paket nyata
di dalam container Linux dan menegaskan perilaku melalui perintah CLI,
startup Gateway, probe HTTP, status RPC, dan status filesystem.
Lane Docker adalah bukti tingkat produk. Lane ini menginstal atau memperbarui
paket nyata di dalam container Linux dan menegaskan perilaku melalui perintah
CLI, startup Gateway, probe HTTP, status RPC, dan status filesystem.
Gunakan lane terfokus saat iterasi:
@ -92,33 +93,36 @@ pnpm test:docker:update-migration
Lane penting:
- `test:docker:plugins` memvalidasi smoke instalasi Plugin, instalasi folder lokal,
perilaku lewati pembaruan folder lokal, folder lokal dengan dependensi yang sudah
terinstal, instalasi paket `file:`, instalasi git dengan eksekusi CLI, pembaruan
moving-ref git, instalasi registri npm dengan dependensi transitif hoisted,
no-op pembaruan npm, instalasi fixture ClawHub lokal dan no-op pembaruan,
perilaku pembaruan marketplace, serta enable/inspect bundle Claude. Setel
`OPENCLAW_PLUGINS_E2E_CLAWHUB=0` agar blok ClawHub tetap hermetik/offline.
perilaku lewati pembaruan folder lokal, folder lokal dengan dependensi yang
sudah terinstal, instalasi paket `file:`, instalasi git dengan eksekusi CLI,
pembaruan moving-ref git, instalasi registri npm dengan dependensi transitif
yang dihoist, no-op pembaruan npm, instalasi fixture ClawHub lokal dan no-op
pembaruan, perilaku pembaruan marketplace, serta enable/inspect bundle Claude. Setel
`OPENCLAW_PLUGINS_E2E_CLAWHUB=0` agar blok ClawHub tetap hermetic/offline.
- `test:docker:plugin-lifecycle-matrix` menginstal paket kandidat di container
kosong, menjalankan Plugin npm melalui instalasi, inspect, disable, enable,
kosong, menjalankan Plugin npm melalui install, inspect, disable, enable,
upgrade eksplisit, downgrade eksplisit, dan uninstall setelah menghapus kode
Plugin. Lane ini mencatat metrik RSS dan CPU untuk setiap fase.
- `test:docker:plugin-update` memvalidasi bahwa Plugin terinstal yang tidak berubah
tidak diinstal ulang atau kehilangan metadata instalasi selama `openclaw plugins update`.
- `test:docker:plugin-update` memvalidasi bahwa Plugin terinstal yang tidak
berubah tidak diinstal ulang atau kehilangan metadata instalasi selama
`openclaw plugins update`.
- `test:docker:upgrade-survivor` menginstal tarball kandidat di atas fixture
pengguna lama yang kotor, menjalankan pembaruan paket plus doctor non-interaktif, lalu memulai
Gateway loopback dan memeriksa pelestarian status.
- `test:docker:published-upgrade-survivor` terlebih dahulu menginstal baseline terbitan,
mengonfigurasinya melalui resep `openclaw config set` yang sudah dipanggang, memperbaruinya ke
tarball kandidat, menjalankan doctor, memeriksa pembersihan warisan, memulai Gateway, dan
melakukan probe `/healthz`, `/readyz`, serta status RPC.
- `test:docker:update-migration` adalah lane pembaruan terbitan yang berat pembersihan. Lane ini
dimulai dari status pengguna bergaya Discord/Telegram yang sudah dikonfigurasi, menjalankan
doctor baseline agar dependensi Plugin terkonfigurasi punya kesempatan untuk terwujud, menanam
sisa dependensi Plugin warisan untuk Plugin paket yang dikonfigurasi, memperbarui ke
tarball kandidat, dan mewajibkan doctor pascapembaruan untuk menghapus root dependensi
warisan.
pengguna lama yang kotor, menjalankan pembaruan paket plus doctor noninteraktif,
lalu memulai Gateway loopback dan memeriksa preservasi status.
- `test:docker:published-upgrade-survivor` pertama-tama menginstal baseline yang
sudah diterbitkan, mengonfigurasinya melalui resep `openclaw config set`
bawaan, memperbaruinya ke tarball kandidat, menjalankan doctor, memeriksa
pembersihan legacy, memulai Gateway, dan mem-probe `/healthz`, `/readyz`, serta
status RPC.
- `test:docker:update-migration` adalah lane pembaruan terbitan yang berat pada
pembersihan. Lane ini dimulai dari status pengguna bergaya Discord/Telegram yang
sudah dikonfigurasi, menjalankan doctor baseline agar dependensi Plugin yang
dikonfigurasi punya kesempatan untuk terwujud, menanam debris dependensi
Plugin legacy untuk Plugin paket yang dikonfigurasi, memperbarui ke tarball
kandidat, dan mewajibkan doctor pascapembaruan untuk menghapus root dependensi
legacy.
Varian published-upgrade survivor yang berguna:
Varian survivor pembaruan terbitan yang berguna:
```bash
OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@2026.4.23 \
@ -131,15 +135,16 @@ pnpm test:docker:published-upgrade-survivor
```
Skenario yang tersedia adalah `base`, `feishu-channel`, `bootstrap-persona`,
`plugin-deps-cleanup`, `configured-plugin-installs`, `tilde-log-path`, dan
`versioned-runtime-deps`. Dalam run agregat,
`OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues` diperluas menjadi semua skenario
berbentuk issue yang dilaporkan, termasuk migrasi instalasi Plugin terkonfigurasi.
`plugin-deps-cleanup`, `configured-plugin-installs`,
`stale-source-plugin-shadow`, `tilde-log-path`, dan `versioned-runtime-deps`. Dalam run agregat,
`OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues` diperluas menjadi semua
skenario berbentuk isu yang dilaporkan, termasuk migrasi instalasi Plugin yang
dikonfigurasi.
Migrasi pembaruan penuh sengaja dipisahkan dari Full Release CI. Gunakan
workflow manual `Update Migration` ketika pertanyaan rilisnya adalah "bisakah setiap
rilis stabil terbitan dari 2026.4.23 dan seterusnya memperbarui ke kandidat ini dan
membersihkan sisa dependensi Plugin?":
Migrasi pembaruan penuh sengaja dipisahkan dari CI Full Release. Gunakan workflow
manual `Update Migration` ketika pertanyaan rilisnya adalah "apakah setiap rilis
stabil terbitan dari 2026.4.23 dan seterusnya dapat diperbarui ke kandidat ini dan
membersihkan debris dependensi Plugin?":
```bash
gh workflow run update-migration.yml \
@ -152,23 +157,23 @@ gh workflow run update-migration.yml \
## Package Acceptance
Package Acceptance adalah gate paket native GitHub. Gate ini me-resolve satu paket kandidat
menjadi tarball `package-under-test`, mencatat versi dan SHA-256, lalu
menjalankan lane Docker E2E reusable terhadap tarball persis tersebut. Ref harness workflow
terpisah dari ref sumber paket, sehingga logika pengujian saat ini dapat memvalidasi
rilis tepercaya yang lebih lama.
Package Acceptance adalah gate paket native GitHub. Ia me-resolve satu paket
kandidat menjadi tarball `package-under-test`, mencatat versi dan SHA-256, lalu
menjalankan lane Docker E2E yang dapat digunakan ulang terhadap tarball persis
itu. Ref harness workflow terpisah dari ref sumber paket, sehingga logika
pengujian saat ini dapat memvalidasi rilis tepercaya yang lebih lama.
Sumber kandidat:
- `source=npm`: validasi `openclaw@beta`, `openclaw@latest`, atau versi
terbitan persis.
- `source=ref`: kemas branch, tag, atau commit tepercaya dengan harness saat ini
terbitan yang persis.
- `source=ref`: pack branch, tag, atau commit tepercaya dengan harness saat ini
yang dipilih.
- `source=url`: validasi tarball HTTPS dengan `package_sha256` wajib.
- `source=artifact`: gunakan kembali tarball yang diunggah oleh run Actions lain.
- `source=artifact`: gunakan ulang tarball yang diunggah oleh run Actions lain.
Full Release Validation menggunakan `source=artifact` secara default, dibuat dari
SHA rilis yang di-resolve. Untuk pembuktian pascapublikasi, teruskan
Full Release Validation menggunakan `source=artifact` secara default, dibangun
dari SHA rilis yang di-resolve. Untuk bukti pascapublikasi, teruskan
`package_acceptance_package_spec=openclaw@YYYY.M.D` agar matriks upgrade yang sama
menargetkan paket npm yang sudah dikirim.
@ -186,15 +191,16 @@ published_upgrade_survivor_scenarios=reported-issues
telegram_mode=mock-openai
```
Ini menjaga migrasi paket, perpindahan channel pembaruan, pembersihan dependensi
Plugin usang, cakupan Plugin offline, perilaku pembaruan Plugin, dan QA paket Telegram
pada artefak yang sama yang sudah di-resolve.
Ini menjaga migrasi paket, pengalihan channel pembaruan, pembersihan dependensi
Plugin basi, cakupan Plugin offline, perilaku pembaruan Plugin, dan QA paket
Telegram pada artefak yang di-resolve sama.
`all-since-2026.4.23` adalah sampel upgrade Full Release CI: setiap rilis stabil yang dipublikasikan ke npm dari `2026.4.23` hingga `latest`. Untuk cakupan migrasi pembaruan terbitan
yang menyeluruh, gunakan `all-since-2026.4.23` di workflow Update
Migration terpisah, bukan Full Release CI. `release-history` tetap
tersedia untuk sampling manual yang lebih luas ketika Anda juga menginginkan anchor warisan
pra-tanggal.
`all-since-2026.4.23` adalah sampel upgrade CI Full Release: setiap rilis stabil
yang diterbitkan di npm dari `2026.4.23` hingga `latest`. Untuk cakupan migrasi
pembaruan terbitan yang menyeluruh, gunakan `all-since-2026.4.23` dalam workflow
Update Migration terpisah, bukan CI Full Release. `release-history` tetap
tersedia untuk sampling manual yang lebih luas ketika Anda juga menginginkan
anchor legacy sebelum tanggal tersebut.
Jalankan profil paket secara manual saat memvalidasi kandidat sebelum rilis:
@ -211,70 +217,72 @@ gh workflow run package-acceptance.yml \
```
Gunakan `suite_profile=product` ketika pertanyaan rilis mencakup channel MCP,
pembersihan cron/subagent, pencarian web OpenAI, atau OpenWebUI. Gunakan `suite_profile=full`
hanya ketika Anda memerlukan cakupan jalur rilis Docker penuh.
pembersihan cron/subagent, pencarian web OpenAI, atau OpenWebUI. Gunakan
`suite_profile=full` hanya ketika Anda memerlukan cakupan penuh jalur rilis
Docker.
## Default rilis
Untuk kandidat rilis, stack pembuktian default adalah:
Untuk kandidat rilis, stack bukti default adalah:
1. `pnpm check:changed` dan `pnpm test:changed` untuk regresi tingkat sumber.
2. `pnpm release:check` untuk integritas artefak paket.
3. Profil Package Acceptance `package` atau lane paket kustom release-check
untuk kontrak instalasi/pembaruan/Plugin.
4. Pemeriksaan rilis lintas-OS untuk installer, onboarding, dan perilaku platform
3. Profil `package` Package Acceptance atau lane paket kustom release-check
untuk kontrak install/update/Plugin.
4. Pemeriksaan rilis lintas OS untuk perilaku installer, onboarding, dan platform
yang spesifik OS.
5. Suite langsung hanya ketika permukaan yang berubah menyentuh perilaku penyedia atau layanan
terhosting.
5. Rangkaian live hanya ketika permukaan yang berubah menyentuh perilaku
penyedia atau hosted-service.
Pada mesin maintainer, gate luas dan pembuktian produk Docker/paket harus berjalan
di Testbox kecuali secara eksplisit melakukan pembuktian lokal.
Pada mesin maintainer, gate luas dan bukti produk Docker/paket harus berjalan di
Testbox kecuali secara eksplisit melakukan bukti lokal.
## Kompatibilitas warisan
## Kompatibilitas legacy
Kelonggaran kompatibilitas bersifat sempit dan dibatasi waktu:
Kelonggaran kompatibilitas sempit dan dibatasi waktu:
- Paket hingga `2026.4.25`, termasuk `2026.4.25-beta.*`, dapat menoleransi
celah metadata paket yang sudah dikirim dalam Package Acceptance.
- Paket `2026.4.26` yang diterbitkan dapat memperingatkan untuk file stempel metadata build lokal
yang sudah dikirim.
- Paket berikutnya harus memenuhi kontrak modern. Celah yang sama akan gagal, bukan
- Paket hingga `2026.4.25`, termasuk `2026.4.25-beta.*`, boleh menoleransi
celah metadata paket yang sudah dikirim di Package Acceptance.
- Paket `2026.4.26` yang diterbitkan boleh memperingatkan untuk file stamp
metadata build lokal yang sudah dikirim.
- Paket berikutnya harus memenuhi kontrak modern. Celah yang sama gagal, bukan
memperingatkan atau dilewati.
Jangan menambahkan migrasi startup baru untuk bentuk lama ini. Tambahkan atau perluas perbaikan
doctor, lalu buktikan dengan `upgrade-survivor` atau `published-upgrade-survivor`.
Jangan tambahkan migrasi startup baru untuk bentuk lama ini. Tambahkan atau
perluas perbaikan doctor, lalu buktikan dengan `upgrade-survivor` atau
`published-upgrade-survivor`.
## Menambahkan cakupan
Saat mengubah perilaku pembaruan atau Plugin, tambahkan cakupan pada lapisan terendah yang
dapat gagal karena alasan yang tepat:
Saat mengubah perilaku pembaruan atau Plugin, tambahkan cakupan pada lapisan
terendah yang dapat gagal karena alasan yang tepat:
- Logika path atau metadata murni: pengujian unit di samping sumber.
- Perilaku inventaris paket atau file yang dikemas: pengujian `package-dist-inventory` atau pemeriksa
tarball.
- Perilaku instalasi/pembaruan CLI: assertion atau fixture lane Docker.
- Logika path atau metadata murni: unit test di samping sumber.
- Perilaku inventaris paket atau file yang dipaketkan: `package-dist-inventory` atau pengujian
checker tarball.
- Perilaku install/update CLI: assertion atau fixture lane Docker.
- Perilaku migrasi rilis terbitan: skenario `published-upgrade-survivor`.
- Perilaku sumber registri/paket: fixture `test:docker:plugins` atau server fixture
ClawHub.
- Perilaku tata letak atau pembersihan dependensi: tegaskan eksekusi runtime dan batas
filesystem. Dependensi npm dapat di-hoist di bawah root npm terkelola, jadi pengujian
harus membuktikan bahwa root dipindai/dibersihkan, bukan mengasumsikan pohon `node_modules`
lokal paket.
- Perilaku sumber registri/paket: fixture `test:docker:plugins` atau server
fixture ClawHub.
- Perilaku tata letak atau pembersihan dependensi: assert eksekusi runtime dan
batas filesystem. Dependensi npm dapat dihoist di bawah root npm terkelola,
sehingga pengujian harus membuktikan root dipindai/dibersihkan alih-alih
mengasumsikan pohon `node_modules` lokal paket.
Jaga fixture Docker baru tetap hermetik secara default. Gunakan registri fixture lokal dan
paket palsu kecuali tujuan pengujian adalah perilaku registri langsung.
Jaga fixture Docker baru tetap hermetic secara default. Gunakan registri fixture
lokal dan paket palsu kecuali tujuan pengujian adalah perilaku registri live.
## Triage kegagalan
Mulai dengan identitas artefak:
- Ringkasan Package Acceptance `resolve_package`: sumber, versi, SHA-256, dan
- Ringkasan `resolve_package` Package Acceptance: sumber, versi, SHA-256, dan
nama artefak.
- Artefak Docker: `.artifacts/docker-tests/**/summary.json`,
`failures.json`, log lane, dan perintah rerun.
- Ringkasan upgrade survivor: `.artifacts/upgrade-survivor/summary.json`,
termasuk versi baseline, versi kandidat, skenario, timing fase, dan
langkah resep.
termasuk versi baseline, versi kandidat, skenario, timing fase, dan langkah
resep.
Lebih baik menjalankan ulang lane persis yang gagal dengan artefak paket yang sama daripada
menjalankan ulang seluruh payung rilis.
Utamakan menjalankan ulang lane persis yang gagal dengan artefak paket yang sama
daripada menjalankan ulang seluruh umbrella rilis.

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

File diff suppressed because it is too large Load Diff

186
docs/id/plugins/bundles.md
View File

@ -1,35 +1,35 @@
---
read_when:
- Anda ingin menginstal bundel yang kompatibel dengan Codex, Claude, atau Cursor
- Anda ingin menginstal paket yang kompatibel dengan Codex, Claude, atau Cursor
- Anda perlu memahami bagaimana OpenClaw memetakan konten bundel ke fitur bawaan
- Anda sedang menelusuri masalah deteksi bundel atau kemampuan yang hilang
summary: Instal dan gunakan bundel Codex, Claude, dan Cursor sebagai Plugin OpenClaw
- Anda sedang men-debug deteksi bundel atau kapabilitas yang hilang
summary: Instal dan gunakan bundle Codex, Claude, dan Cursor sebagai Plugin OpenClaw
title: Bundel Plugin
x-i18n:
generated_at: "2026-05-02T09:26:29Z"
generated_at: "2026-05-05T01:47:50Z"
model: gpt-5.5
provider: openai
source_hash: 4b949ad70881714a30ab136261441687b439e39b516638ffa052efeab6b75bd4
source_hash: 5bc06300e765e2faaf51800462003e242d29d4102ac9feaa47f86d4ad35bf157
source_path: plugins/bundles.md
workflow: 16
---
OpenClaw dapat menginstal plugin dari tiga ekosistem eksternal: **Codex**, **Claude**,
dan **Cursor**. Ini disebut **bundles** — paket konten dan metadata yang
dipetakan OpenClaw ke fitur native seperti skills, hooks, dan alat MCP.
OpenClaw dapat menginstal Plugin dari tiga ekosistem eksternal: **Codex**, **Claude**,
dan **Cursor**. Ini disebut **bundle** — paket konten dan metadata yang
dipetakan OpenClaw ke fitur native seperti skill, hook, dan tool MCP.
<Info>
Bundles **tidak** sama dengan plugin native OpenClaw. Plugin native berjalan
dalam proses dan dapat mendaftarkan capability apa pun. Bundles adalah paket konten dengan
Bundle **tidak** sama dengan Plugin native OpenClaw. Plugin native berjalan
dalam proses dan dapat mendaftarkan kemampuan apa pun. Bundle adalah paket konten dengan
pemetaan fitur selektif dan batas kepercayaan yang lebih sempit.
</Info>
## Mengapa bundles ada
## Mengapa bundle ada
Banyak plugin berguna diterbitkan dalam format Codex, Claude, atau Cursor. Alih-alih
mengharuskan pembuat menulis ulang plugin tersebut sebagai plugin native OpenClaw, OpenClaw
mendeteksi format ini dan memetakan konten yang didukungnya ke rangkaian fitur
native. Artinya, Anda dapat menginstal paket perintah Claude atau bundle skill Codex
Banyak Plugin berguna diterbitkan dalam format Codex, Claude, atau Cursor. Alih-alih
mengharuskan pembuatnya menulis ulang sebagai Plugin native OpenClaw, OpenClaw
mendeteksi format ini dan memetakan konten yang didukung ke kumpulan fitur
native. Ini berarti Anda dapat menginstal paket perintah Claude atau bundle skill Codex
dan langsung menggunakannya.
## Instal bundle
@ -56,7 +56,7 @@ dan langsung menggunakannya.
openclaw plugins inspect <id>
```
Bundles ditampilkan sebagai `Format: bundle` dengan subtype `codex`, `claude`, atau `cursor`.
Bundle ditampilkan sebagai `Format: bundle` dengan subtipe `codex`, `claude`, atau `cursor`.
</Step>
@ -65,26 +65,26 @@ dan langsung menggunakannya.
openclaw gateway restart
```
Fitur yang dipetakan (skills, hooks, alat MCP, default LSP) tersedia di sesi berikutnya.
Fitur yang dipetakan (skill, hook, tool MCP, default LSP) tersedia di sesi berikutnya.
</Step>
</Steps>
## Apa yang dipetakan OpenClaw dari bundles
## Yang dipetakan OpenClaw dari bundle
Tidak setiap fitur bundle berjalan di OpenClaw saat ini. Berikut yang berfungsi dan yang
Tidak semua fitur bundle berjalan di OpenClaw saat ini. Berikut yang berfungsi dan yang
terdeteksi tetapi belum dihubungkan.
### Didukung saat ini
### Didukung sekarang
| Fitur | Cara pemetaannya | Berlaku untuk |
| ------------- | -------------------------------------------------------------------------------------------- | -------------- |
| Konten skill | Root skill bundle dimuat sebagai skill OpenClaw normal | Semua format |
| Perintah | `commands/` dan `.cursor/commands/` diperlakukan sebagai root skill | Claude, Cursor |
| Paket hook | Layout `HOOK.md` + `handler.ts` bergaya OpenClaw | Codex |
| Alat MCP | Konfigurasi MCP bundle digabungkan ke pengaturan Pi tertanam; server stdio dan HTTP yang didukung dimuat | Semua format |
| Server LSP | `.lsp.json` Claude dan `lspServers` yang dideklarasikan manifest digabungkan ke default LSP Pi tertanam | Claude |
| Pengaturan | `settings.json` Claude diimpor sebagai default Pi tertanam | Claude |
| Fitur | Cara pemetaannya | Berlaku untuk |
| ------------- | ------------------------------------------------------------------------------------------- | -------------- |
| Konten skill | Root skill bundle dimuat sebagai skill OpenClaw normal | Semua format |
| Perintah | `commands/` dan `.cursor/commands/` diperlakukan sebagai root skill | Claude, Cursor |
| Paket hook | Tata letak `HOOK.md` + `handler.ts` bergaya OpenClaw | Codex |
| Tool MCP | Konfigurasi MCP bundle digabungkan ke pengaturan Pi tertanam; server stdio dan HTTP yang didukung dimuat | Semua format |
| Server LSP | `.lsp.json` Claude dan `lspServers` yang dideklarasikan manifes digabungkan ke default LSP Pi tertanam | Claude |
| Pengaturan | `settings.json` Claude diimpor sebagai default Pi tertanam | Claude |
#### Konten skill
@ -92,13 +92,13 @@ terdeteksi tetapi belum dihubungkan.
- root `commands` Claude diperlakukan sebagai root skill tambahan
- root `.cursor/commands` Cursor diperlakukan sebagai root skill tambahan
Artinya file perintah markdown Claude bekerja melalui loader skill OpenClaw
Ini berarti file perintah markdown Claude bekerja melalui pemuat skill OpenClaw
normal. Markdown perintah Cursor bekerja melalui jalur yang sama.
#### Paket hook
- root hook bundle berfungsi **hanya** ketika menggunakan layout hook-pack OpenClaw
normal. Saat ini ini terutama kasus yang kompatibel dengan Codex:
- root hook bundle berfungsi **hanya** saat menggunakan tata letak hook-pack
OpenClaw normal. Saat ini ini terutama kasus yang kompatibel dengan Codex:
- `HOOK.md`
- `handler.ts` atau `handler.js`
@ -107,14 +107,14 @@ normal. Markdown perintah Cursor bekerja melalui jalur yang sama.
- bundle yang diaktifkan dapat menyumbangkan konfigurasi server MCP
- OpenClaw menggabungkan konfigurasi MCP bundle ke pengaturan Pi tertanam efektif sebagai
`mcpServers`
- OpenClaw mengekspos alat MCP bundle yang didukung selama giliran agen Pi tertanam dengan
meluncurkan server stdio atau menyambung ke server HTTP
- profil alat `coding` dan `messaging` menyertakan alat MCP bundle secara
default; gunakan `tools.deny: ["bundle-mcp"]` untuk menolak ikut serta bagi agen atau gateway
- OpenClaw mengekspos tool MCP bundle yang didukung selama giliran agen Pi tertanam dengan
meluncurkan server stdio atau tersambung ke server HTTP
- profil tool `coding` dan `messaging` menyertakan tool MCP bundle secara
default; gunakan `tools.deny: ["bundle-mcp"]` untuk tidak ikut serta bagi agen atau Gateway
- pengaturan Pi lokal proyek tetap berlaku setelah default bundle, sehingga pengaturan
workspace dapat mengganti entri MCP bundle saat diperlukan
- katalog alat MCP bundle diurutkan secara deterministik sebelum pendaftaran, sehingga
perubahan urutan `listTools()` upstream tidak mengacak blok alat prompt-cache
workspace dapat menimpa entri MCP bundle saat diperlukan
- katalog tool MCP bundle diurutkan secara deterministik sebelum pendaftaran, sehingga
perubahan urutan `listTools()` upstream tidak mengacaukan blok tool cache prompt
##### Transport
@ -136,7 +136,7 @@ Server MCP dapat menggunakan transport stdio atau HTTP:
}
```
**HTTP** tersambung ke server MCP yang sedang berjalan melalui `sse` secara default, atau `streamable-http` jika diminta:
**HTTP** tersambung ke server MCP yang sedang berjalan melalui `sse` secara default, atau `streamable-http` saat diminta:
```json
{
@ -155,40 +155,40 @@ Server MCP dapat menggunakan transport stdio atau HTTP:
}
```
- `transport` dapat diatur ke `"streamable-http"` atau `"sse"`; jika dihilangkan, OpenClaw menggunakan `sse`
- `type: "http"` adalah bentuk hilir native CLI; gunakan `transport: "streamable-http"` dalam konfigurasi OpenClaw. `openclaw mcp set` dan `openclaw doctor --fix` menormalkan alias umum.
- `transport` dapat diatur ke `"streamable-http"` atau `"sse"`; saat dihilangkan, OpenClaw menggunakan `sse`
- `type: "http"` adalah bentuk downstream native CLI; gunakan `transport: "streamable-http"` dalam konfigurasi OpenClaw. `openclaw mcp set` dan `openclaw doctor --fix` menormalkan alias umum.
- hanya skema URL `http:` dan `https:` yang diizinkan
- nilai `headers` mendukung interpolasi `${ENV_VAR}`
- entri server dengan `command` dan `url` sekaligus ditolak
- kredensial URL (userinfo dan parameter kueri) disamarkan dari deskripsi alat
- kredensial URL (userinfo dan parameter kueri) disamarkan dari deskripsi tool
dan log
- `connectionTimeoutMs` mengganti timeout koneksi default 30 detik untuk
- `connectionTimeoutMs` menimpa timeout koneksi default 30 detik untuk
transport stdio dan HTTP
##### Penamaan alat
##### Penamaan tool
OpenClaw mendaftarkan alat MCP bundle dengan nama yang aman untuk provider dalam bentuk
`serverName__toolName`. Misalnya, server dengan key `"vigil-harbor"` yang mengekspos
alat `memory_search` didaftarkan sebagai `vigil-harbor__memory_search`.
OpenClaw mendaftarkan tool MCP bundle dengan nama yang aman untuk penyedia dalam bentuk
`serverName__toolName`. Misalnya, server dengan kunci `"vigil-harbor"` yang mengekspos tool
`memory_search` didaftarkan sebagai `vigil-harbor__memory_search`.
- karakter di luar `A-Za-z0-9_-` diganti dengan `-`
- prefiks server dibatasi hingga 30 karakter
- nama alat lengkap dibatasi hingga 64 karakter
- nama server kosong fallback ke `mcp`
- nama tool lengkap dibatasi hingga 64 karakter
- nama server kosong menggunakan fallback `mcp`
- nama tersanitasi yang bertabrakan dibedakan dengan sufiks numerik
- urutan alat akhir yang diekspos deterministik berdasarkan nama aman agar giliran Pi
berulang tetap stabil cache
- pemfilteran profil memperlakukan semua alat dari satu server MCP bundle sebagai milik plugin
- urutan tool akhir yang diekspos deterministik berdasarkan nama aman untuk menjaga giliran Pi
berulang tetap stabil terhadap cache
- pemfilteran profil memperlakukan semua tool dari satu server MCP bundle sebagai milik Plugin
oleh `bundle-mcp`, sehingga allowlist dan daftar deny profil dapat menyertakan
nama alat terekspos individual atau key plugin `bundle-mcp`
nama tool terekspos individual atau kunci Plugin `bundle-mcp`
#### Pengaturan Pi tertanam
- `settings.json` Claude diimpor sebagai pengaturan Pi tertanam default saat
bundle diaktifkan
- OpenClaw membersihkan key override shell sebelum menerapkannya
- OpenClaw membersihkan kunci override shell sebelum menerapkannya
Key yang disanitasi:
Kunci yang dibersihkan:
- `shellPath`
- `shellCommandPrefix`
@ -196,28 +196,28 @@ Key yang disanitasi:
#### LSP Pi tertanam
- bundle Claude yang diaktifkan dapat menyumbangkan konfigurasi server LSP
- OpenClaw memuat `.lsp.json` ditambah path `lspServers` yang dideklarasikan manifest
- OpenClaw memuat `.lsp.json` plus jalur `lspServers` yang dideklarasikan manifes
- konfigurasi LSP bundle digabungkan ke default LSP Pi tertanam yang efektif
- hanya server LSP berbasis stdio yang didukung yang dapat dijalankan saat ini; transport
yang tidak didukung tetap muncul di `openclaw plugins inspect <id>`
- hanya server LSP berbasis stdio yang didukung yang dapat dijalankan saat ini; transport yang tidak didukung
tetap muncul di `openclaw plugins inspect <id>`
### Terdeteksi tetapi tidak dieksekusi
Ini dikenali dan ditampilkan dalam diagnostik, tetapi OpenClaw tidak menjalankannya:
- `agents`, automasi `hooks.json`, `outputStyles` Claude
- `agents`, otomasi `hooks.json`, `outputStyles` Claude
- `.cursor/agents`, `.cursor/hooks.json`, `.cursor/rules` Cursor
- metadata inline/app Codex di luar pelaporan capability
- metadata inline/app Codex di luar pelaporan kemampuan
## Format bundle
<AccordionGroup>
<Accordion title="Bundle Codex">
Marker: `.codex-plugin/plugin.json`
Penanda: `.codex-plugin/plugin.json`
Konten opsional: `skills/`, `hooks/`, `.mcp.json`, `.app.json`
Bundle Codex paling cocok dengan OpenClaw ketika menggunakan root skill dan direktori
Bundle Codex paling cocok dengan OpenClaw saat menggunakan root skill dan direktori
hook-pack bergaya OpenClaw (`HOOK.md` + `handler.ts`).
</Accordion>
@ -225,22 +225,22 @@ Ini dikenali dan ditampilkan dalam diagnostik, tetapi OpenClaw tidak menjalankan
<Accordion title="Bundle Claude">
Dua mode deteksi:
- **Berbasis manifest:** `.claude-plugin/plugin.json`
- **Tanpa manifest:** layout Claude default (`skills/`, `commands/`, `agents/`, `hooks/`, `.mcp.json`, `.lsp.json`, `settings.json`)
- **Berbasis manifes:** `.claude-plugin/plugin.json`
- **Tanpa manifes:** tata letak Claude default (`skills/`, `commands/`, `agents/`, `hooks/`, `.mcp.json`, `.lsp.json`, `settings.json`)
Perilaku khusus Claude:
- `commands/` diperlakukan sebagai konten skill
- `settings.json` diimpor ke pengaturan Pi tertanam (key override shell disanitasi)
- `.mcp.json` mengekspos alat stdio yang didukung ke Pi tertanam
- `.lsp.json` ditambah path `lspServers` yang dideklarasikan manifest dimuat ke default LSP Pi tertanam
- `settings.json` diimpor ke pengaturan Pi tertanam (kunci override shell dibersihkan)
- `.mcp.json` mengekspos tool stdio yang didukung ke Pi tertanam
- `.lsp.json` plus jalur `lspServers` yang dideklarasikan manifes dimuat ke default LSP Pi tertanam
- `hooks/hooks.json` terdeteksi tetapi tidak dieksekusi
- Path komponen kustom dalam manifest bersifat aditif (memperluas default, bukan menggantikannya)
- Jalur komponen kustom dalam manifes bersifat aditif (memperluas default, bukan menggantikannya)
</Accordion>
<Accordion title="Bundle Cursor">
Marker: `.cursor-plugin/plugin.json`
Penanda: `.cursor-plugin/plugin.json`
Konten opsional: `skills/`, `.cursor/commands/`, `.cursor/agents/`, `.cursor/rules/`, `.cursor/hooks.json`, `.mcp.json`
@ -252,44 +252,44 @@ Ini dikenali dan ditampilkan dalam diagnostik, tetapi OpenClaw tidak menjalankan
## Prioritas deteksi
OpenClaw memeriksa format plugin native terlebih dahulu:
OpenClaw memeriksa format Plugin native terlebih dahulu:
1. `openclaw.plugin.json` atau `package.json` valid dengan `openclaw.extensions` — diperlakukan sebagai **plugin native**
2. Marker bundle (`.codex-plugin/`, `.claude-plugin/`, atau layout default Claude/Cursor) — diperlakukan sebagai **bundle**
1. `openclaw.plugin.json` atau `package.json` yang valid dengan `openclaw.extensions` — diperlakukan sebagai **Plugin native**
2. Penanda bundle (`.codex-plugin/`, `.claude-plugin/`, atau tata letak Claude/Cursor default) — diperlakukan sebagai **bundle**
Jika direktori memuat keduanya, OpenClaw menggunakan jalur native. Ini mencegah
paket berformat ganda diinstal sebagian sebagai bundles.
Jika sebuah direktori berisi keduanya, OpenClaw menggunakan jalur native. Ini mencegah
paket format ganda diinstal sebagian sebagai bundle.
## Dependensi runtime dan pembersihan
- Bundle kompatibel pihak ketiga tidak mendapatkan perbaikan `npm install` saat startup. Bundle tersebut
harus diinstal melalui `openclaw plugins install` dan menyertakan semua yang
dibutuhkan di direktori plugin terinstal.
- Plugin bundled milik OpenClaw dikirim ringan dalam core atau
dapat diunduh melalui penginstal plugin. Startup Gateway tidak pernah menjalankan
package manager untuk plugin tersebut.
dibutuhkan di direktori Plugin terinstal.
- Plugin bundle milik OpenClaw dikirim ringan di core atau
dapat diunduh melalui penginstal Plugin. Startup Gateway tidak pernah menjalankan
manajer paket untuknya.
- `openclaw doctor --fix` menghapus direktori dependensi staged lama dan dapat
menginstal plugin unduhan terkonfigurasi yang hilang dari indeks plugin
lokal.
memulihkan Plugin yang dapat diunduh yang hilang dari indeks Plugin lokal saat
konfigurasi merujuknya.
## Keamanan
Bundles memiliki batas kepercayaan yang lebih sempit daripada plugin native:
Bundle memiliki batas kepercayaan yang lebih sempit daripada Plugin native:
- OpenClaw **tidak** memuat modul runtime bundle arbitrer dalam proses
- Path Skills dan hook-pack harus tetap berada di dalam root plugin (diperiksa batasnya)
- Skills dan jalur hook-pack harus tetap berada di dalam root Plugin (diperiksa batasnya)
- File pengaturan dibaca dengan pemeriksaan batas yang sama
- Server MCP stdio yang didukung dapat diluncurkan sebagai subprocess
Ini membuat bundles lebih aman secara default, tetapi Anda tetap harus memperlakukan bundle
pihak ketiga sebagai konten tepercaya untuk fitur yang memang dieksposnya.
Ini membuat bundle lebih aman secara default, tetapi Anda tetap harus memperlakukan bundle
pihak ketiga sebagai konten tepercaya untuk fitur yang dieksposnya.
## Pemecahan masalah
<AccordionGroup>
<Accordion title="Bundle terdeteksi tetapi capability tidak berjalan">
Jalankan `openclaw plugins inspect <id>`. Jika capability terdaftar tetapi ditandai sebagai
belum dihubungkan, itu adalah batas produk — bukan instalasi rusak.
<Accordion title="Bundle terdeteksi tetapi kemampuan tidak berjalan">
Jalankan `openclaw plugins inspect <id>`. Jika sebuah kemampuan tercantum tetapi ditandai sebagai
belum dihubungkan, itu adalah batasan produk — bukan instalasi yang rusak.
</Accordion>
<Accordion title="File perintah Claude tidak muncul">
@ -297,19 +297,19 @@ pihak ketiga sebagai konten tepercaya untuk fitur yang memang dieksposnya.
`commands/` atau `skills/` yang terdeteksi.
</Accordion>
<Accordion title="Pengaturan Claude tidak berlaku">
<Accordion title="Pengaturan Claude tidak diterapkan">
Hanya pengaturan Pi tertanam dari `settings.json` yang didukung. OpenClaw tidak
memperlakukan pengaturan bundle sebagai patch konfigurasi mentah.
</Accordion>
<Accordion title="Hook Claude tidak dieksekusi">
`hooks/hooks.json` hanya dideteksi. Jika membutuhkan hook yang dapat berjalan, gunakan
layout hook-pack OpenClaw atau kirim plugin native.
`hooks/hooks.json` hanya dideteksi. Jika Anda membutuhkan hook yang dapat dijalankan, gunakan
tata letak hook-pack OpenClaw atau kirim Plugin native.
</Accordion>
</AccordionGroup>
## Terkait
- [Instal dan Konfigurasikan Plugin](/id/tools/plugin)
- [Membangun Plugin](/id/plugins/building-plugins) — buat plugin native
- [Manifest Plugin](/id/plugins/manifest) — skema manifest native
- [Instal dan Konfigurasi Plugin](/id/tools/plugin)
- [Membangun Plugin](/id/plugins/building-plugins) — buat Plugin native
- [Manifes Plugin](/id/plugins/manifest) — skema manifes native

801
docs/id/plugins/codex-harness.md
View File

File diff suppressed because it is too large Load Diff

102
docs/id/plugins/dependency-resolution.md
View File

@ -1,62 +1,61 @@
---
read_when:
- Anda sedang melakukan debug instalasi paket Plugin
- Anda mengubah perilaku inisialisasi Plugin, doctor, atau pemasangan pengelola paket
- Anda memelihara instalasi OpenClaw terpaket atau manifest Plugin yang dibundel
- Anda sedang memecahkan masalah instalasi paket Plugin
- Anda sedang mengubah perilaku startup Plugin, doctor, atau instalasi pengelola paket
- Anda memelihara instalasi OpenClaw terpaket atau manifest Plugin bawaan
sidebarTitle: Dependencies
summary: Cara OpenClaw menginstal paket Plugin dan menyelesaikan dependensi Plugin
title: Resolusi dependensi Plugin
x-i18n:
generated_at: "2026-05-03T21:35:29Z"
generated_at: "2026-05-05T01:48:24Z"
model: gpt-5.5
provider: openai
source_hash: 46af62ff866d50cb53bb2761d9928f0fd2a25bdb945040885ec6bfb85be35c6d
source_hash: 1a832f705e51bba8ac77e2a8715a7213fd2caf10bfa42059d53db4a6d5ad8c20
source_path: plugins/dependency-resolution.md
workflow: 16
---
# Resolusi dependensi Plugin
OpenClaw menangani pekerjaan dependensi Plugin pada waktu instalasi/pembaruan. Pemuatan waktu jalan
tidak menjalankan manajer paket, memperbaiki pohon dependensi, atau mengubah direktori paket
OpenClaw menjalankan pekerjaan dependensi Plugin pada waktu instalasi/pembaruan. Pemuatan runtime
tidak menjalankan pengelola paket, memperbaiki pohon dependensi, atau memutasi direktori paket
OpenClaw.
## Pembagian tanggung jawab
Paket Plugin memiliki grafik dependensinya sendiri:
- dependensi waktu jalan berada di `dependencies` atau `optionalDependencies`
paket Plugin
- impor SDK/core adalah impor peer atau impor yang disediakan OpenClaw
- Plugin pengembangan lokal membawa dependensi yang sudah terinstal sendiri
- Plugin npm dan git diinstal ke root paket milik OpenClaw
- dependensi runtime berada di `dependencies` atau `optionalDependencies` paket Plugin
- import SDK/core adalah peer atau import OpenClaw yang disediakan
- Plugin pengembangan lokal membawa dependensinya sendiri yang sudah terpasang
- Plugin npm dan git dipasang ke root paket milik OpenClaw
OpenClaw hanya memiliki siklus hidup Plugin:
- menemukan sumber Plugin
- menginstal atau memperbarui paket saat diminta secara eksplisit
- memasang atau memperbarui paket saat diminta secara eksplisit
- mencatat metadata instalasi
- memuat titik masuk Plugin
- gagal dengan kesalahan yang dapat ditindaklanjuti saat dependensi hilang
- memuat entrypoint Plugin
- gagal dengan galat yang dapat ditindaklanjuti saat dependensi hilang
## Root instalasi
OpenClaw menggunakan root stabil per sumber:
- paket npm diinstal di bawah `~/.openclaw/npm`
- paket npm dipasang di bawah `~/.openclaw/npm`
- paket git dikloning di bawah `~/.openclaw/git`
- instalasi lokal/path/arsip disalin atau direferensikan tanpa perbaikan dependensi
- instalasi lokal/path/archive disalin atau direferensikan tanpa perbaikan dependensi
Instalasi npm dijalankan di root npm dengan:
Instalasi npm berjalan di root npm dengan:
```bash
npm install --prefix ~/.openclaw/npm <spec> --omit=dev --ignore-scripts --no-audit --no-fund
```
npm dapat mengangkat dependensi transitif ke `~/.openclaw/npm/node_modules` di samping
npm dapat meng-hoist dependensi transitif ke `~/.openclaw/npm/node_modules` di samping
paket Plugin. OpenClaw memindai root npm terkelola sebelum memercayai
instalasi dan menggunakan npm untuk menghapus paket yang dikelola npm saat penghapusan instalasi, sehingga dependensi
waktu jalan yang diangkat tetap berada di dalam batas pembersihan terkelola.
instalasi dan menggunakan npm untuk menghapus paket yang dikelola npm saat uninstall, sehingga dependensi
runtime yang di-hoist tetap berada di dalam batas pembersihan terkelola.
Instalasi git mengkloning atau menyegarkan repositori, lalu menjalankan:
@ -64,26 +63,26 @@ Instalasi git mengkloning atau menyegarkan repositori, lalu menjalankan:
npm install --omit=dev --ignore-scripts --no-audit --no-fund
```
Plugin yang terinstal lalu dimuat dari direktori paket tersebut, sehingga resolusi
Plugin yang terpasang kemudian dimuat dari direktori paket tersebut, sehingga resolusi
`node_modules` lokal paket dan induk bekerja dengan cara yang sama seperti pada paket
Node normal.
Node biasa.
## Plugin lokal
Plugin lokal diperlakukan sebagai direktori yang dikendalikan pengembang. OpenClaw tidak
Plugin lokal diperlakukan sebagai direktori yang dikendalikan developer. OpenClaw tidak
menjalankan `npm install`, `pnpm install`, atau perbaikan dependensi untuknya. Jika Plugin
lokal memiliki dependensi, instal dependensi tersebut di Plugin itu sebelum memuatnya.
lokal memiliki dependensi, pasang dependensi tersebut di Plugin itu sebelum memuatnya.
Plugin lokal TypeScript pihak ketiga dapat menggunakan jalur darurat Jiti. Plugin
JavaScript terpaket dan Plugin internal bawaan dimuat melalui
import/require native, bukan Jiti.
## Startup dan pemuatan ulang
## Startup dan muat ulang
Startup Gateway dan pemuatan ulang konfigurasi tidak pernah menginstal dependensi Plugin. Keduanya membaca
catatan instalasi Plugin, menghitung titik masuk, dan memuatnya.
Startup Gateway dan muat ulang konfigurasi tidak pernah memasang dependensi Plugin. Keduanya membaca
catatan instalasi Plugin, menghitung entrypoint, dan memuatnya.
Jika dependensi hilang pada waktu jalan, Plugin gagal dimuat dan kesalahan
Jika dependensi hilang saat runtime, Plugin gagal dimuat dan galatnya
harus mengarahkan operator ke perbaikan eksplisit:
```bash
@ -92,33 +91,34 @@ openclaw plugins install <source>
openclaw doctor --fix
```
`doctor --fix` dapat membersihkan status dependensi lama yang dibuat OpenClaw dan menginstal
Plugin unduhan terkonfigurasi yang hilang dari catatan instalasi lokal.
Perintah ini tidak memperbaiki dependensi untuk Plugin lokal yang sudah terinstal.
`doctor --fix` dapat membersihkan status dependensi lama yang dibuat OpenClaw dan memulihkan
Plugin yang dapat diunduh yang hilang dari catatan instalasi lokal saat konfigurasi
mereferensikannya. Doctor tidak memperbaiki dependensi untuk Plugin lokal
yang sudah terpasang.
## Plugin bawaan
Plugin bawaan yang ringan dan penting bagi core dikirim sebagai bagian dari OpenClaw.
Plugin tersebut sebaiknya tidak memiliki pohon dependensi waktu jalan yang berat atau dipindahkan ke
paket unduhan di ClawHub/npm.
Plugin bawaan yang ringan dan kritis untuk core dikirim sebagai bagian dari OpenClaw.
Plugin tersebut sebaiknya tidak memiliki pohon dependensi runtime yang berat atau dipindahkan ke
paket yang dapat diunduh di ClawHub/npm.
Untuk daftar terbuat saat ini berisi Plugin yang dikirim dalam paket core, diinstal
Untuk daftar terbuat saat ini tentang Plugin yang dikirim dalam paket core, dipasang
secara eksternal, atau tetap hanya sebagai sumber, lihat [Inventaris Plugin](/id/plugins/plugin-inventory).
Manifes Plugin bawaan tidak boleh meminta staging dependensi. Fungsionalitas Plugin
besar atau opsional sebaiknya dikemas sebagai Plugin normal dan diinstal melalui
Manifes Plugin bawaan tidak boleh meminta staging dependensi. Fungsionalitas
Plugin yang besar atau opsional sebaiknya dikemas sebagai Plugin normal dan dipasang melalui
jalur npm/git/ClawHub yang sama seperti Plugin pihak ketiga.
Dalam checkout sumber, OpenClaw memperlakukan repositori sebagai monorepo pnpm. Setelah
`pnpm install`, Plugin bawaan dimuat dari `extensions/<id>` sehingga dependensi workspace
lokal paket tersedia dan perubahan langsung diambil. Pengembangan checkout
sumber hanya mendukung pnpm; `npm install` biasa di root repositori bukan
cara yang didukung untuk menyiapkan dependensi Plugin bawaan.
`pnpm install`, Plugin bawaan dimuat dari `extensions/<id>` sehingga dependensi
workspace lokal paket tersedia dan perubahan langsung ikut terbaca. Pengembangan
checkout sumber hanya mendukung pnpm; `npm install` biasa di root repositori
bukan cara yang didukung untuk menyiapkan dependensi Plugin bawaan.
| Bentuk instalasi | Lokasi Plugin bawaan | Pemilik dependensi |
| -------------------------------- | ------------------------------------- | -------------------------------------------------------------------- |
| `npm install -g openclaw` | Pohon waktu jalan bawaan di dalam paket | Paket OpenClaw dan alur instalasi/pembaruan/doctor Plugin eksplisit |
| Checkout Git plus `pnpm install` | Paket workspace `extensions/<id>` | Workspace pnpm, termasuk dependensi milik tiap paket Plugin |
| Bentuk instalasi | Lokasi Plugin bawaan | Pemilik dependensi |
| -------------------------------- | ------------------------------------ | -------------------------------------------------------------------- |
| `npm install -g openclaw` | Pohon runtime terbangun di dalam paket | Paket OpenClaw dan alur instalasi/pembaruan/doctor Plugin eksplisit |
| Checkout Git plus `pnpm install` | Paket workspace `extensions/<id>` | Workspace pnpm, termasuk dependensi masing-masing paket Plugin |
| `openclaw plugins install ...` | Root Plugin npm/git/ClawHub terkelola | Alur instalasi/pembaruan Plugin |
## Pembersihan lama
@ -127,9 +127,9 @@ Versi OpenClaw lama membuat root dependensi Plugin bawaan saat startup atau
selama perbaikan doctor. Pembersihan doctor saat ini menghapus direktori dan
symlink usang tersebut saat `--fix` digunakan, termasuk root `plugin-runtime-deps` lama, symlink
paket prefix Node global yang menunjuk ke target `plugin-runtime-deps` yang telah dipangkas,
manifes `.openclaw-runtime-deps*`, `node_modules` Plugin yang dibuat, direktori stage
instalasi, dan store pnpm lokal paket. Postinstall terpaket juga
menghapus symlink global tersebut sebelum memangkas root target lama agar peningkatan versi
tidak meninggalkan impor paket ESM yang menggantung.
manifes `.openclaw-runtime-deps*`, `node_modules` Plugin yang dihasilkan, direktori
stage instalasi, dan store pnpm lokal paket. Postinstall terpaket juga
menghapus symlink global tersebut sebelum memangkas root target lama agar upgrade
tidak meninggalkan import paket ESM yang menggantung.
Jalur ini hanyalah sisa lama. Instalasi baru tidak boleh membuatnya.
Path ini hanya sisa lama. Instalasi baru tidak boleh membuatnya.

92
docs/id/plugins/manage-plugins.md
View File

@ -1,24 +1,24 @@
---
read_when:
- Anda membutuhkan contoh cepat untuk menginstal, menampilkan daftar, memperbarui, atau menghapus instalasi Plugin
- Anda ingin memilih antara ClawHub dan distribusi Plugin npm
- Anda ingin contoh cepat untuk memasang, menampilkan daftar, memperbarui, atau menghapus Plugin
- Anda ingin memilih antara distribusi Plugin melalui ClawHub dan npm
- Anda sedang menerbitkan paket Plugin
sidebarTitle: Manage plugins
summary: Contoh cepat untuk menginstal, menampilkan daftar, menghapus instalasi, memperbarui, dan menerbitkan Plugin OpenClaw
title: Kelola Plugin
x-i18n:
generated_at: "2026-05-02T22:19:53Z"
generated_at: "2026-05-05T01:48:26Z"
model: gpt-5.5
provider: openai
source_hash: ec25a811b942f155f5d5e4cac475dbef74f0616bc85ff182c74598184e910320
source_hash: 7fa7aa78c1ba9c83ba09bea073987ed5e037031f7c7f29307fe18934b0bd2a1c
source_path: plugins/manage-plugins.md
workflow: 16
---
Sebagian besar alur kerja plugin terdiri dari beberapa perintah: cari, instal, mulai ulang Gateway,
verifikasi, dan hapus instalasi saat Anda tidak lagi membutuhkan plugin tersebut.
Sebagian besar alur kerja Plugin hanya terdiri dari beberapa perintah: cari, instal, mulai ulang Gateway,
verifikasi, dan hapus instalasi saat Anda tidak lagi memerlukan Plugin tersebut.
## Daftar plugin
## Daftar Plugin
```bash
openclaw plugins list
@ -27,20 +27,20 @@ openclaw plugins list --verbose
openclaw plugins list --json
```
Gunakan `--json` untuk skrip. Ini mencakup diagnostik registry dan
`dependencyStatus` statis setiap plugin saat paket plugin mendeklarasikan
`dependencies` atau `optionalDependencies`.
Gunakan `--json` untuk skrip. Ini menyertakan diagnostik registri dan
`dependencyStatus` statis setiap Plugin saat paket Plugin mendeklarasikan `dependencies` atau
`optionalDependencies`.
```bash
openclaw plugins list --json \
| jq '.plugins[] | {id, enabled, format, source, dependencyStatus}'
```
`plugins list` adalah pemeriksaan inventaris dingin. Ini menunjukkan apa yang dapat ditemukan OpenClaw
dari konfigurasi, manifes, dan registry plugin; ini tidak membuktikan bahwa
proses Gateway yang sudah berjalan telah mengimpor runtime plugin.
`plugins list` adalah pemeriksaan inventaris dingin. Ini menampilkan apa yang dapat ditemukan OpenClaw
dari konfigurasi, manifest, dan registri Plugin; ini tidak membuktikan bahwa
proses Gateway yang sudah berjalan telah mengimpor runtime Plugin.
## Instal plugin
## Instal Plugin
```bash
# Search ClawHub for plugin packages.
@ -65,18 +65,18 @@ openclaw plugins install ./my-plugin
openclaw plugins install --link ./my-plugin
```
Setelah menginstal kode plugin, mulai ulang Gateway yang melayani saluran Anda:
Setelah menginstal kode Plugin, mulai ulang Gateway yang melayani saluran Anda:
```bash
openclaw gateway restart
openclaw plugins inspect <plugin-id> --runtime --json
```
Gunakan `inspect --runtime` saat Anda membutuhkan bukti bahwa plugin mendaftarkan permukaan
Gunakan `inspect --runtime` saat Anda memerlukan bukti bahwa Plugin telah mendaftarkan permukaan
runtime seperti alat, hook, layanan, metode Gateway, atau perintah CLI
milik plugin.
milik Plugin.
## Perbarui plugin
## Perbarui Plugin
```bash
openclaw plugins update <plugin-id>
@ -84,24 +84,26 @@ openclaw plugins update <npm-package-or-spec>
openclaw plugins update --all
```
Jika plugin diinstal dari dist-tag npm seperti `@beta`, pemanggilan
`update <plugin-id>` berikutnya menggunakan kembali tag yang tercatat tersebut. Meneruskan spesifikasi npm eksplisit
mengalihkan instalasi yang dilacak ke spesifikasi tersebut untuk pembaruan mendatang.
Jika sebuah Plugin diinstal dari dist-tag npm seperti `@beta`, panggilan
`update <plugin-id>` berikutnya akan menggunakan kembali tag yang tercatat tersebut. Meneruskan spec npm eksplisit
mengalihkan instalasi yang dilacak ke spec tersebut untuk pembaruan mendatang.
```bash
openclaw plugins update @scope/openclaw-plugin@beta
openclaw plugins update @scope/openclaw-plugin
```
Perintah kedua memindahkan plugin kembali ke jalur rilis default registry
saat sebelumnya dipasangkan ke versi atau tag yang tepat.
Perintah kedua memindahkan Plugin kembali ke jalur rilis default registri
saat sebelumnya dipin ke versi atau tag tertentu.
Saat `openclaw update` berjalan pada saluran beta, catatan plugin npm jalur default dan ClawHub
mencoba rilis plugin `@beta` yang cocok terlebih dahulu. Jika rilis beta tersebut
tidak ada, OpenClaw kembali ke spesifikasi default/latest yang tercatat.
Versi tepat dan tag eksplisit seperti `@rc` atau `@beta` dipertahankan.
Saat `openclaw update` berjalan di saluran beta, catatan Plugin npm dan ClawHub
jalur default akan mencoba rilis Plugin `@beta` yang sesuai terlebih dahulu. Jika rilis beta tersebut
tidak ada, OpenClaw kembali ke spec default/latest yang tercatat.
Untuk Plugin npm, OpenClaw juga kembali saat paket beta ada tetapi gagal
validasi instalasi. Versi tepat dan tag eksplisit seperti `@rc` atau `@beta`
dipertahankan.
## Hapus instalasi plugin
## Hapus Instalasi Plugin
```bash
openclaw plugins uninstall <plugin-id> --dry-run
@ -110,19 +112,19 @@ openclaw plugins uninstall <plugin-id> --keep-files
openclaw gateway restart
```
Penghapusan instalasi menghapus entri konfigurasi plugin, catatan indeks plugin, entri daftar izinkan/tolak,
dan jalur muat tertaut saat berlaku. Direktori instalasi terkelola
Hapus instalasi menghapus entri konfigurasi Plugin, catatan indeks Plugin, entri daftar
izinkan/tolak, dan jalur muat tertaut jika berlaku. Direktori instalasi terkelola akan
dihapus kecuali Anda meneruskan `--keep-files`.
## Publikasikan plugin
## Publikasikan Plugin
Anda dapat memublikasikan plugin eksternal ke [ClawHub](https://clawhub.ai), npmjs.com, atau
Anda dapat memublikasikan Plugin eksternal ke [ClawHub](https://clawhub.ai), npmjs.com, atau
keduanya.
### Publikasikan ke ClawHub
ClawHub adalah permukaan penemuan publik utama untuk plugin OpenClaw. Ini memberi
pengguna metadata yang dapat dicari, riwayat versi, dan hasil pemindaian registry sebelum
ClawHub adalah permukaan penemuan publik utama untuk Plugin OpenClaw. Ini memberi
pengguna metadata yang dapat dicari, riwayat versi, dan hasil pemindaian registri sebelum
instalasi.
```bash
@ -140,11 +142,11 @@ openclaw plugins install clawhub:<package>
openclaw plugins install <package>
```
Bentuk polos tetap memeriksa ClawHub terlebih dahulu.
Bentuk tanpa awalan tetap memeriksa ClawHub terlebih dahulu.
### Publikasikan ke npmjs.com
Plugin npm native harus menyertakan manifes plugin dan metadata titik masuk OpenClaw
Plugin npm native harus menyertakan manifest Plugin dan metadata entrypoint OpenClaw
`package.json`.
```json package.json
@ -162,7 +164,7 @@ Plugin npm native harus menyertakan manifes plugin dan metadata titik masuk Open
npm publish --access public
```
Pengguna menginstal khusus npm dengan:
Pengguna menginstal yang hanya npm dengan:
```bash
openclaw plugins install npm:@acme/openclaw-plugin
@ -173,19 +175,19 @@ openclaw plugins install npm:@acme/openclaw-plugin@1.0.0
Jika paket yang sama juga tersedia di ClawHub, `npm:` melewati pencarian ClawHub dan
memaksa resolusi npm.
## Pilihan sumber
## Pilihan Sumber
- **ClawHub**: gunakan saat Anda menginginkan penemuan native OpenClaw, ringkasan pemindaian,
versi, dan petunjuk instalasi.
- **npmjs.com**: gunakan saat Anda sudah mengirimkan paket JavaScript atau membutuhkan alur kerja
dist-tag/registry privat npm.
- **npmjs.com**: gunakan saat Anda sudah mengirimkan paket JavaScript atau memerlukan alur kerja
dist-tag npm/registri privat.
- **Git**: gunakan saat Anda ingin menginstal langsung dari branch, tag, atau commit.
- **Jalur lokal**: gunakan saat Anda sedang mengembangkan atau menguji plugin pada mesin yang sama.
- **Jalur lokal**: gunakan saat Anda sedang mengembangkan atau menguji Plugin di mesin yang sama.
## Terkait
- [Plugin](/id/tools/plugin) - ikhtisar dan pemecahan masalah
- [Plugin](/id/tools/plugin) - gambaran umum dan pemecahan masalah
- [`openclaw plugins`](/id/cli/plugins) - referensi CLI lengkap
- [ClawHub](/id/tools/clawhub) - publikasi dan operasi registry
- [Membangun plugin](/id/plugins/building-plugins) - buat paket plugin
- [Manifes plugin](/id/plugins/manifest) - manifes dan metadata paket
- [ClawHub](/id/tools/clawhub) - publikasi dan operasi registri
- [Membangun Plugin](/id/plugins/building-plugins) - buat paket Plugin
- [Manifest Plugin](/id/plugins/manifest) - manifest dan metadata paket

89
docs/id/providers/openrouter.md
View File

@ -1,22 +1,22 @@
---
read_when:
- Anda ingin satu kunci API untuk banyak LLM
- Anda menginginkan satu kunci API untuk banyak LLM
- Anda ingin menjalankan model melalui OpenRouter di OpenClaw
- Anda ingin menggunakan OpenRouter untuk pembuatan gambar
- Anda ingin menggunakan OpenRouter untuk pembuatan video
summary: Gunakan API terpadu OpenRouter untuk mengakses banyak model di OpenClaw
title: OpenRouter
x-i18n:
generated_at: "2026-05-04T07:07:50Z"
generated_at: "2026-05-05T01:48:33Z"
model: gpt-5.5
provider: openai
source_hash: f6b7299408aa0de7530e2248c7fa5dae8c09095e2d20a0e9d12a64cab83966fc
source_hash: b2876669c6fcc958ac13c19930cd23977b8ec27ae57069d9231932cc13c75244
source_path: providers/openrouter.md
workflow: 16
---
OpenRouter menyediakan **API terpadu** yang merutekan permintaan ke banyak model di balik satu
endpoint dan kunci API. Ini kompatibel dengan OpenAI, sehingga sebagian besar SDK OpenAI berfungsi dengan mengganti URL dasar.
endpoint dan kunci API. API ini kompatibel dengan OpenAI, sehingga sebagian besar SDK OpenAI berfungsi dengan mengganti URL dasar.
## Memulai
@ -30,7 +30,7 @@ endpoint dan kunci API. Ini kompatibel dengan OpenAI, sehingga sebagian besar SD
```
</Step>
<Step title="(Opsional) Beralih ke model tertentu">
Onboarding default ke `openrouter/auto`. Pilih model konkret nanti:
Onboarding menggunakan `openrouter/auto` secara default. Pilih model konkret nanti:
```bash
openclaw models set openrouter/<provider>/<model>
@ -62,9 +62,9 @@ penyedia dan model yang tersedia, lihat [/concepts/model-providers](/id/concepts
Contoh fallback bawaan:
| Referensi model | Catatan |
| --------------------------------- | ---------------------------- |
| `openrouter/auto` | Perutean otomatis OpenRouter |
| `openrouter/moonshotai/kimi-k2.6` | Kimi K2.6 melalui MoonshotAI |
| -------------------------------- | ------------------------------ |
| `openrouter/auto` | Perutean otomatis OpenRouter |
| `openrouter/moonshotai/kimi-k2.6` | Kimi K2.6 melalui MoonshotAI |
## Pembuatan gambar
@ -84,7 +84,7 @@ OpenRouter juga dapat mendukung alat `image_generate`. Gunakan model gambar Open
}
```
OpenClaw mengirim permintaan gambar ke API gambar chat completions OpenRouter dengan `modalities: ["image", "text"]`. Model gambar Gemini menerima petunjuk `aspectRatio` dan `resolution` yang didukung melalui `image_config` OpenRouter. Gunakan `agents.defaults.imageGenerationModel.timeoutMs` untuk model gambar OpenRouter yang lebih lambat; parameter `timeoutMs` per panggilan milik alat `image_generate` tetap diprioritaskan.
OpenClaw mengirim permintaan gambar ke API gambar chat completions OpenRouter dengan `modalities: ["image", "text"]`. Model gambar Gemini menerima petunjuk `aspectRatio` dan `resolution` yang didukung melalui `image_config` OpenRouter. Gunakan `agents.defaults.imageGenerationModel.timeoutMs` untuk model gambar OpenRouter yang lebih lambat; parameter `timeoutMs` per-panggilan milik alat `image_generate` tetap diutamakan.
## Pembuatan video
@ -103,15 +103,15 @@ OpenRouter juga dapat mendukung alat `video_generate` melalui API `/videos` asin
}
```
OpenClaw mengirim pekerjaan teks-ke-video dan gambar-ke-video ke OpenRouter, melakukan polling
OpenClaw mengirim tugas teks-ke-video dan gambar-ke-video ke OpenRouter, melakukan polling
pada `polling_url` yang dikembalikan, dan mengunduh video yang selesai dari
`unsigned_urls` OpenRouter atau endpoint konten pekerjaan yang terdokumentasi.
`unsigned_urls` OpenRouter atau endpoint konten tugas yang terdokumentasi.
Gambar referensi dikirim sebagai gambar frame pertama/terakhir secara default; gambar
yang diberi tag `reference_image` dikirim sebagai referensi input OpenRouter. Default
bawaan `google/veo-3.1-fast` mengiklankan durasi 4/6/8 detik yang saat ini didukung,
resolusi `720P`/`1080P`, dan rasio aspek `16:9`/`9:16`.
Video-ke-video tidak didaftarkan untuk OpenRouter karena API pembuatan video upstream
saat ini menerima referensi teks dan gambar.
yang ditandai dengan `reference_image` dikirim sebagai referensi input OpenRouter. Default
bawaan `google/veo-3.1-fast` mengiklankan durasi 4/6/8
detik yang saat ini didukung, resolusi `720P`/`1080P`, dan rasio aspek
`16:9`/`9:16`. Video-ke-video tidak didaftarkan untuk OpenRouter karena API
pembuatan video upstream saat ini menerima teks dan referensi gambar.
## Teks-ke-ucapan
@ -136,7 +136,7 @@ OpenRouter juga dapat digunakan sebagai penyedia TTS melalui endpoint
}
```
Jika `messages.tts.providers.openrouter.apiKey` dihilangkan, TTS menggunakan ulang
Jika `messages.tts.providers.openrouter.apiKey` dihilangkan, TTS menggunakan kembali
`models.providers.openrouter.apiKey`, lalu `OPENROUTER_API_KEY`.
## Autentikasi dan header
@ -144,7 +144,7 @@ Jika `messages.tts.providers.openrouter.apiKey` dihilangkan, TTS menggunakan ula
OpenRouter menggunakan token Bearer dengan kunci API Anda di balik layar.
Pada permintaan OpenRouter nyata (`https://openrouter.ai/api/v1`), OpenClaw juga menambahkan
header atribusi aplikasi yang terdokumentasi milik OpenRouter:
header atribusi aplikasi yang terdokumentasi oleh OpenRouter:
| Header | Nilai |
| ------------------------- | ------------------------------------------------------------------------------------------------------ |
@ -160,8 +160,8 @@ Jika Anda mengarahkan ulang penyedia OpenRouter ke proxy atau URL dasar lain, Op
## Konfigurasi lanjutan
<AccordionGroup>
<Accordion title="Cache respons">
Cache respons OpenRouter bersifat opt-in. Aktifkan per model OpenRouter dengan
<Accordion title="Caching respons">
Caching respons OpenRouter bersifat opt-in. Aktifkan per model OpenRouter dengan
parameter model:
```json5
@ -183,11 +183,11 @@ Jika Anda mengarahkan ulang penyedia OpenRouter ke proxy atau URL dasar lain, Op
OpenClaw mengirim `X-OpenRouter-Cache: true` dan, saat dikonfigurasi,
`X-OpenRouter-Cache-TTL`. `responseCacheClear: true` memaksa penyegaran untuk
permintaan saat ini dan menyimpan respons penggantinya. Alias snake_case
permintaan saat ini dan menyimpan respons pengganti. Alias snake_case
(`response_cache`, `response_cache_ttl_seconds`, dan
`response_cache_clear`) juga diterima.
Ini terpisah dari cache prompt penyedia dan dari penanda
Ini terpisah dari caching prompt penyedia dan dari penanda
`cache_control` Anthropic milik OpenRouter. Ini hanya diterapkan pada rute
`openrouter.ai` yang terverifikasi, bukan URL dasar proxy khusus.
@ -196,45 +196,48 @@ Jika Anda mengarahkan ulang penyedia OpenRouter ke proxy atau URL dasar lain, Op
<Accordion title="Penanda cache Anthropic">
Pada rute OpenRouter yang terverifikasi, referensi model Anthropic mempertahankan
penanda `cache_control` Anthropic khusus OpenRouter yang digunakan OpenClaw untuk
penggunaan ulang cache prompt yang lebih baik pada blok prompt sistem/developer.
penggunaan ulang prompt-cache yang lebih baik pada blok prompt sistem/developer.
</Accordion>
<Accordion title="Prefill penalaran Anthropic">
Pada rute OpenRouter yang terverifikasi, referensi model Anthropic dengan penalaran aktif
menghapus giliran prefill assistant di akhir sebelum permintaan mencapai OpenRouter,
sesuai dengan persyaratan Anthropic bahwa percakapan penalaran berakhir dengan giliran pengguna.
<Accordion title="Prefill reasoning Anthropic">
Pada rute OpenRouter yang terverifikasi, referensi model Anthropic dengan reasoning aktif
menghapus giliran prefill asisten di akhir sebelum permintaan mencapai OpenRouter,
sesuai dengan persyaratan Anthropic bahwa percakapan reasoning diakhiri dengan giliran
pengguna.
</Accordion>
<Accordion title="Injeksi thinking / penalaran">
Pada rute non-`auto` yang didukung, OpenClaw memetakan tingkat thinking yang dipilih ke
payload penalaran proxy OpenRouter. Petunjuk model yang tidak didukung dan
`openrouter/auto` melewati injeksi penalaran tersebut. Hunter Alpha juga melewati
penalaran proxy untuk referensi model terkonfigurasi yang sudah usang karena OpenRouter dapat
mengembalikan teks jawaban akhir dalam bidang penalaran untuk rute yang sudah dihentikan itu.
<Accordion title="Injeksi thinking / reasoning">
Pada rute non-`auto` yang didukung, OpenClaw memetakan level thinking yang dipilih ke
payload reasoning proxy OpenRouter. Petunjuk model yang tidak didukung dan
`openrouter/auto` melewati injeksi reasoning tersebut. Hunter Alpha juga melewati
reasoning proxy untuk referensi model terkonfigurasi yang usang karena OpenRouter dapat
mengembalikan teks jawaban akhir di kolom reasoning untuk rute yang sudah dihentikan itu.
</Accordion>
<Accordion title="Replay penalaran DeepSeek V4">
<Accordion title="Replay reasoning DeepSeek V4">
Pada rute OpenRouter yang terverifikasi, `openrouter/deepseek/deepseek-v4-flash` dan
`openrouter/deepseek/deepseek-v4-pro` mengisi `reasoning_content` yang hilang pada
giliran assistant yang diputar ulang agar percakapan thinking/alat mempertahankan bentuk
tindak lanjut yang diperlukan DeepSeek V4.
giliran asisten yang diputar ulang agar percakapan thinking/tool mempertahankan bentuk
tindak lanjut yang diwajibkan DeepSeek V4. OpenClaw mengirim nilai
`reasoning_effort` yang didukung OpenRouter untuk rute ini; `xhigh` adalah level
tertinggi yang diiklankan, dan override `max` yang usang dipetakan ke `xhigh`.
</Accordion>
<Accordion title="Pembentukan permintaan khusus OpenAI">
OpenRouter masih berjalan melalui jalur proxy bergaya kompatibel OpenAI, sehingga
pembentukan permintaan khusus OpenAI native seperti `serviceTier`, Responses `store`,
payload kompat penalaran OpenAI, dan petunjuk cache prompt tidak diteruskan.
OpenRouter tetap berjalan melalui jalur kompatibel OpenAI bergaya proxy, sehingga
pembentukan permintaan khusus OpenAI native seperti `serviceTier`, `store` Responses,
payload kompatibilitas reasoning OpenAI, dan petunjuk prompt-cache tidak diteruskan.
</Accordion>
<Accordion title="Rute yang didukung Gemini">
Referensi OpenRouter yang didukung Gemini tetap berada di jalur proxy-Gemini: OpenClaw mempertahankan
<Accordion title="Rute berbasis Gemini">
Referensi OpenRouter berbasis Gemini tetap berada pada jalur proxy-Gemini: OpenClaw mempertahankan
sanitasi thought-signature Gemini di sana, tetapi tidak mengaktifkan validasi replay Gemini native
atau penulisan ulang bootstrap.
</Accordion>
<Accordion title="Metadata perutean penyedia">
Jika Anda meneruskan perutean penyedia OpenRouter di bawah parameter model, OpenClaw meneruskannya
sebagai metadata perutean OpenRouter sebelum wrapper stream bersama berjalan.
sebagai metadata perutean OpenRouter sebelum pembungkus stream bersama berjalan.
</Accordion>
</AccordionGroup>
@ -245,6 +248,6 @@ Jika Anda mengarahkan ulang penyedia OpenRouter ke proxy atau URL dasar lain, Op
Memilih penyedia, referensi model, dan perilaku failover.
</Card>
<Card title="Referensi konfigurasi" href="/id/gateway/configuration-reference" icon="gear">
Referensi konfigurasi lengkap untuk agent, model, dan penyedia.
Referensi konfigurasi lengkap untuk agen, model, dan penyedia.
</Card>
</CardGroup>

636
docs/id/reference/RELEASING.md
View File

@ -2,14 +2,14 @@
read_when:
- Mencari definisi saluran rilis publik
- Menjalankan validasi rilis atau penerimaan paket
- Mencari penamaan versi dan irama rilis
summary: Jalur rilis, daftar periksa operator, kotak validasi, penamaan versi, dan kadensi
- Mencari penamaan versi dan ritme rilis
summary: Jalur rilis, daftar periksa operator, mesin validasi, penamaan versi, dan ritme rilis
title: Kebijakan rilis
x-i18n:
generated_at: "2026-05-04T07:07:42Z"
generated_at: "2026-05-05T01:48:48Z"
model: gpt-5.5
provider: openai
source_hash: ef50d3ef5d1e23b4e2c2b097fc4ca9f6d46bf8acb9aea0c9bca6d14e213b88b6
source_hash: 41886d3bb2f970e6a86944e5ff207b1b29b1b64b1f234d45f626fed19cf032b3
source_path: reference/RELEASING.md
workflow: 16
---
@ -18,185 +18,189 @@ OpenClaw memiliki tiga jalur rilis publik:
- stable: rilis bertag yang dipublikasikan ke npm `beta` secara default, atau ke npm `latest` saat diminta secara eksplisit
- beta: tag prarilis yang dipublikasikan ke npm `beta`
- dev: ujung bergerak dari `main`
- dev: head bergerak dari `main`
## Penamaan versi
- Versi rilis stable: `YYYY.M.D`
- Versi rilis stabil: `YYYY.M.D`
- Tag Git: `vYYYY.M.D`
- Versi rilis koreksi stable: `YYYY.M.D-N`
- Versi rilis koreksi stabil: `YYYY.M.D-N`
- Tag Git: `vYYYY.M.D-N`
- Versi prarilis beta: `YYYY.M.D-beta.N`
- Tag Git: `vYYYY.M.D-beta.N`
- Jangan tambahkan nol di depan bulan atau hari
- `latest` berarti rilis npm stable yang saat ini dipromosikan
- `beta` berarti target instalasi beta saat ini
- Rilis stable dan koreksi stable dipublikasikan ke npm `beta` secara default; operator rilis dapat menargetkan `latest` secara eksplisit, atau mempromosikan build beta yang sudah diverifikasi nanti
- Setiap rilis stable OpenClaw mengirimkan paket npm dan aplikasi macOS bersama-sama;
- Jangan menambahkan nol di depan bulan atau hari
- `latest` berarti rilis npm stabil yang saat ini dipromosikan
- `beta` berarti target pemasangan beta saat ini
- Rilis stabil dan rilis koreksi stabil dipublikasikan ke npm `beta` secara default; operator rilis dapat menargetkan `latest` secara eksplisit, atau mempromosikan build beta yang sudah diperiksa nanti
- Setiap rilis stabil OpenClaw mengirim paket npm dan aplikasi macOS bersama-sama;
rilis beta biasanya memvalidasi dan memublikasikan jalur npm/paket terlebih dahulu, dengan
build/sign/notarize aplikasi Mac disisihkan untuk stable kecuali diminta secara eksplisit
build/tanda tangan/notarisasi aplikasi mac dicadangkan untuk stabil kecuali diminta secara eksplisit
## Irama rilis
## Kadensi rilis
- Rilis bergerak dengan beta terlebih dahulu
- Stable menyusul hanya setelah beta terbaru divalidasi
- Pemelihara biasanya membuat rilis dari cabang `release/YYYY.M.D` yang dibuat
- Stabil menyusul hanya setelah beta terbaru divalidasi
- Maintainer biasanya memotong rilis dari cabang `release/YYYY.M.D` yang dibuat
dari `main` saat ini, sehingga validasi dan perbaikan rilis tidak memblokir
pengembangan baru di `main`
- Jika tag beta telah di-push atau dipublikasikan dan memerlukan perbaikan, pemelihara membuat
- Jika tag beta telah di-push atau dipublikasikan dan membutuhkan perbaikan, maintainer memotong
tag `-beta.N` berikutnya alih-alih menghapus atau membuat ulang tag beta lama
- Prosedur rilis terperinci, persetujuan, kredensial, dan catatan pemulihan bersifat
khusus pemelihara
- Prosedur rilis terperinci, persetujuan, kredensial, dan catatan pemulihan
hanya untuk maintainer
## Daftar periksa operator rilis
Daftar periksa ini adalah bentuk publik dari alur rilis. Kredensial privat,
penandatanganan, notarisasi, pemulihan dist-tag, dan detail rollback darurat tetap berada di
runbook rilis khusus pemelihara.
runbook rilis khusus maintainer.
1. Mulai dari `main` saat ini: tarik yang terbaru, konfirmasi commit target telah di-push,
1. Mulai dari `main` saat ini: tarik versi terbaru, konfirmasi commit target telah di-push,
dan konfirmasi CI `main` saat ini cukup hijau untuk membuat cabang darinya.
2. Tulis ulang bagian teratas `CHANGELOG.md` dari riwayat commit nyata dengan
`/changelog`, jaga entri tetap berorientasi pengguna, commit, push, dan rebase/pull
`/changelog`, jaga entri tetap menghadap pengguna, commit, push, lalu rebase/pull
sekali lagi sebelum membuat cabang.
3. Tinjau catatan kompatibilitas rilis di
`src/plugins/compat/registry.ts` dan
`src/commands/doctor/shared/deprecation-compat.ts`. Hapus kompatibilitas yang kedaluwarsa
hanya ketika jalur peningkatan tetap tercakup, atau catat mengapa kompatibilitas itu
`src/commands/doctor/shared/deprecation-compat.ts`. Hapus
kompatibilitas yang kedaluwarsa hanya saat jalur peningkatan tetap tercakup, atau catat mengapa kompatibilitas itu
sengaja dipertahankan.
4. Buat `release/YYYY.M.D` dari `main` saat ini; jangan lakukan pekerjaan rilis normal
langsung di `main`.
5. Naikkan setiap lokasi versi yang diperlukan untuk tag yang dimaksud, jalankan
5. Naikkan setiap lokasi versi yang diperlukan untuk tag yang dituju, jalankan
`pnpm plugins:sync` agar paket Plugin yang dapat dipublikasikan berbagi versi rilis
dan metadata kompatibilitas, lalu jalankan preflight deterministik lokal:
`pnpm check:test-types`, `pnpm check:architecture`,
`pnpm build && pnpm ui:build`, `pnpm plugins:sync:check`, dan
`pnpm release:check`.
6. Jalankan `OpenClaw NPM Release` dengan `preflight_only=true`. Sebelum tag ada,
SHA cabang rilis penuh 40 karakter diperbolehkan untuk preflight khusus validasi.
SHA cabang rilis lengkap 40 karakter diperbolehkan untuk preflight khusus validasi.
Simpan `preflight_run_id` yang berhasil.
7. Mulai semua pengujian prarilis dengan `Full Release Validation` untuk cabang rilis,
tag, atau SHA commit penuh. Ini adalah satu-satunya entrypoint manual
7. Mulai semua pengujian prarilis dengan `Full Release Validation` untuk
cabang rilis, tag, atau SHA commit lengkap. Ini adalah satu titik masuk manual
untuk empat kotak pengujian rilis besar: Vitest, Docker, QA Lab, dan Package.
8. Jika validasi gagal, perbaiki di cabang rilis dan jalankan ulang file, jalur,
job workflow, profil paket, penyedia, atau daftar izin model terkecil yang gagal
dan membuktikan perbaikan. Jalankan ulang payung penuh hanya ketika permukaan yang berubah membuat
8. Jika validasi gagal, perbaiki di cabang rilis dan jalankan ulang file, lane, job workflow,
profil paket, penyedia, atau allowlist model terkecil yang gagal dan
membuktikan perbaikan. Jalankan ulang payung penuh hanya saat permukaan yang berubah membuat
bukti sebelumnya kedaluwarsa.
9. Untuk beta, tag `vYYYY.M.D-beta.N`, lalu jalankan `OpenClaw Release Publish` dari
cabang `release/YYYY.M.D` yang sesuai. Ini memverifikasi `pnpm plugins:sync:check`,
cabang `release/YYYY.M.D` yang cocok. Ini memverifikasi `pnpm plugins:sync:check`,
memublikasikan semua paket Plugin yang dapat dipublikasikan ke npm terlebih dahulu, memublikasikan set yang sama
ke ClawHub kedua sebagai tarball ClawPack npm-pack, lalu mempromosikan
artefak preflight npm OpenClaw yang disiapkan dengan dist-tag yang sesuai. Setelah
publikasi, jalankan penerimaan paket pascapublikasi
artefak preflight npm OpenClaw yang disiapkan dengan dist-tag yang cocok. Setelah
publikasi, jalankan acceptance paket pascapublikasi
terhadap paket `openclaw@YYYY.M.D-beta.N` atau
`openclaw@beta` yang dipublikasikan. Jika prarilis yang telah di-push atau dipublikasikan memerlukan perbaikan,
buat nomor prarilis berikutnya yang sesuai; jangan hapus atau tulis ulang prarilis lama.
10. Untuk stable, lanjutkan hanya setelah beta atau kandidat rilis yang telah diverifikasi memiliki
bukti validasi yang diperlukan. Publikasi npm stable juga melalui
`openclaw@beta` yang dipublikasikan. Jika prarilis yang telah di-push atau dipublikasikan membutuhkan perbaikan,
potong nomor prarilis cocok berikutnya; jangan hapus atau tulis ulang prarilis lama.
10. Untuk stabil, lanjutkan hanya setelah beta atau kandidat rilis yang telah diperiksa memiliki
bukti validasi yang diperlukan. Publikasi npm stabil juga melalui
`OpenClaw Release Publish`, menggunakan kembali artefak preflight yang berhasil melalui
`preflight_run_id`; kesiapan rilis macOS stable juga memerlukan
`.zip`, `.dmg`, `.dSYM.zip` yang telah dipaketkan, dan `appcast.xml` yang diperbarui di `main`.
11. Setelah publikasi, jalankan pemverifikasi pascapublikasi npm, E2E Telegram npm terpublikasi
mandiri opsional saat Anda memerlukan bukti kanal pascapublikasi,
`preflight_run_id`; kesiapan rilis macOS stabil juga memerlukan
`.zip`, `.dmg`, `.dSYM.zip` yang dipaketkan, dan `appcast.xml` yang diperbarui di `main`.
11. Setelah publikasi, jalankan pemverifikasi npm pascapublikasi, E2E Telegram
npm-terpublikasi mandiri opsional saat Anda membutuhkan bukti kanal pascapublikasi,
promosi dist-tag saat diperlukan, catatan rilis/prarilis GitHub dari
bagian `CHANGELOG.md` lengkap yang sesuai, dan langkah pengumuman rilis.
bagian `CHANGELOG.md` lengkap yang cocok, dan langkah-langkah pengumuman rilis.
## Preflight rilis
- Jalankan `pnpm check:test-types` sebelum preflight rilis agar TypeScript pengujian tetap
tercakup di luar gate lokal `pnpm check` yang lebih cepat
- Jalankan `pnpm check:architecture` sebelum preflight rilis agar pemeriksaan siklus
impor yang lebih luas dan batas arsitektur berstatus hijau di luar gate lokal yang lebih cepat
impor dan batas arsitektur yang lebih luas hijau di luar gate lokal yang lebih cepat
- Jalankan `pnpm build && pnpm ui:build` sebelum `pnpm release:check` agar artefak
rilis `dist/*` yang diharapkan dan bundel Control UI tersedia untuk langkah
validasi paket
- Jalankan `pnpm plugins:sync` setelah bump versi root dan sebelum tagging. Ini
memperbarui versi paket Plugin yang dapat dipublikasikan, metadata kompatibilitas
peer/API OpenClaw, metadata build, dan stub changelog Plugin agar sesuai dengan versi
rilis inti. `pnpm plugins:sync:check` adalah guard rilis non-mutasi;
rilis `dist/*` yang diharapkan dan bundle Control UI tersedia untuk langkah
validasi pack
- Jalankan `pnpm plugins:sync` setelah kenaikan versi root dan sebelum tagging. Perintah ini
memperbarui versi paket plugin yang dapat dipublikasikan, metadata kompatibilitas
peer/API OpenClaw, metadata build, dan stub changelog plugin agar cocok dengan versi
rilis core. `pnpm plugins:sync:check` adalah penjaga rilis non-mutasi;
workflow publikasi gagal sebelum mutasi registry apa pun jika langkah ini
terlupakan.
- Jalankan workflow manual `Full Release Validation` sebelum persetujuan rilis untuk
memulai semua kotak pengujian prarilis dari satu entrypoint. Workflow ini menerima branch,
memulai semua kotak pengujian pra-rilis dari satu entrypoint. Workflow ini menerima branch,
tag, atau SHA commit penuh, menjalankan manual `CI`, dan menjalankan
`OpenClaw Release Checks` untuk smoke instalasi, package acceptance, suite jalur rilis
Docker, live/E2E, OpenWebUI, paritas QA Lab, Matrix, dan lane Telegram. Dengan
`release_profile=full` dan `rerun_group=all`, workflow ini juga menjalankan package
Telegram E2E terhadap artefak `release-package-under-test` dari release
checks. Berikan `npm_telegram_package_spec` setelah publikasi ketika Telegram E2E
yang sama juga harus membuktikan paket npm yang dipublikasikan. Berikan
`OpenClaw Release Checks` untuk install smoke, package acceptance, pemeriksaan paket
lintas-OS, paritas QA Lab, Matrix, dan lane Telegram. Jalankan stabil/default
mempertahankan live/E2E menyeluruh dan soak jalur rilis Docker di balik
`run_release_soak=true`; `release_profile=full` memaksa soak aktif. Dengan
`release_profile=full` dan `rerun_group=all`, workflow ini juga menjalankan package Telegram
E2E terhadap artefak `release-package-under-test` dari release checks.
Berikan `npm_telegram_package_spec` setelah publikasi ketika Telegram E2E yang sama
juga harus membuktikan paket npm yang telah dipublikasikan. Berikan
`package_acceptance_package_spec` setelah publikasi ketika Package Acceptance
harus menjalankan matriks paket/update terhadap paket npm yang dikirim, bukan
artefak yang dibangun dari SHA. Berikan
harus menjalankan matriks paket/pembaruan terhadap paket npm yang dikirim
alih-alih artefak yang dibangun dari SHA. Berikan
`evidence_package_spec` ketika laporan bukti privat harus membuktikan bahwa
validasi cocok dengan paket npm yang dipublikasikan tanpa memaksa Telegram E2E.
Contoh:
`gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D`
- Jalankan workflow manual `Package Acceptance` ketika Anda menginginkan bukti
side-channel untuk kandidat paket sementara pekerjaan rilis berlanjut. Gunakan `source=npm` untuk
- Jalankan workflow manual `Package Acceptance` ketika Anda menginginkan bukti side-channel
untuk kandidat paket sementara pekerjaan rilis berlanjut. Gunakan `source=npm` untuk
`openclaw@beta`, `openclaw@latest`, atau versi rilis persis; `source=ref`
untuk mengemas branch/tag/SHA `package_ref` tepercaya dengan harness
`workflow_ref` saat ini; `source=url` untuk tarball HTTPS dengan
SHA-256 wajib; atau `source=artifact` untuk tarball yang diunggah oleh run
GitHub Actions lain. Workflow ini menyelesaikan kandidat menjadi
`package-under-test`, menggunakan ulang penjadwal rilis Docker E2E terhadap
`workflow_ref` saat ini; `source=url` untuk tarball HTTPS dengan SHA-256
wajib; atau `source=artifact` untuk tarball yang diunggah oleh run GitHub
Actions lain. Workflow menyelesaikan kandidat menjadi
`package-under-test`, menggunakan kembali penjadwal rilis Docker E2E terhadap
tarball tersebut, dan dapat menjalankan QA Telegram terhadap tarball yang sama dengan
`telegram_mode=mock-openai` atau `telegram_mode=live-frontier`. Ketika lane
Docker yang dipilih mencakup `published-upgrade-survivor`, artefak paket adalah
kandidat dan `published_upgrade_survivor_baseline` memilih baseline yang dipublikasikan.
`telegram_mode=mock-openai` atau `telegram_mode=live-frontier`. Ketika lane Docker
terpilih mencakup `published-upgrade-survivor`, artefak paket adalah kandidat dan
`published_upgrade_survivor_baseline` memilih baseline yang telah dipublikasikan.
Contoh: `gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f published_upgrade_survivor_baseline=openclaw@2026.4.26 -f telegram_mode=mock-openai`
Profil umum:
- `smoke`: lane instal/channel/agent, jaringan Gateway, dan reload konfigurasi
- `package`: lane paket/update/Plugin berbasis artefak tanpa OpenWebUI atau ClawHub live
- `smoke`: lane instalasi/channel/agent, jaringan Gateway, dan reload konfigurasi
- `package`: lane paket/pembaruan/plugin native artefak tanpa OpenWebUI atau ClawHub live
- `product`: profil paket ditambah channel MCP, pembersihan cron/subagent,
pencarian web OpenAI, dan OpenWebUI
- `full`: chunk jalur rilis Docker dengan OpenWebUI
- `custom`: pemilihan `docker_lanes` persis untuk rerun terfokus
- Jalankan workflow manual `CI` secara langsung ketika Anda hanya membutuhkan cakupan
CI normal penuh untuk kandidat rilis. Dispatch CI manual melewati scope changed
dan memaksa shard Linux Node, shard Plugin bawaan, kontrak channel,
kompatibilitas Node 22, `check`, `check-additional`, smoke build,
pemeriksaan docs, Python skills, Windows, macOS, Android, dan lane i18n Control UI.
- Jalankan workflow manual `CI` secara langsung ketika Anda hanya membutuhkan cakupan CI normal penuh
untuk kandidat rilis. Dispatch CI manual melewati scoping changed
dan memaksa shard Linux Node, shard plugin bawaan, kontrak channel,
kompatibilitas Node 22, `check`, `check-additional`, build smoke,
pemeriksaan docs, Python skills, Windows, macOS, Android, dan lane i18n
Control UI.
Contoh: `gh workflow run ci.yml --ref release/YYYY.M.D`
- Jalankan `pnpm qa:otel:smoke` saat memvalidasi telemetri rilis. Ini menjalankan
QA-lab melalui receiver OTLP/HTTP lokal dan memverifikasi nama span trace yang diekspor,
atribut berbatas, serta redaksi konten/pengidentifikasi tanpa memerlukan
Opik, Langfuse, atau kolektor eksternal lain.
- Jalankan `pnpm qa:otel:smoke` ketika memvalidasi telemetri rilis. Perintah ini menjalankan
QA-lab melalui receiver OTLP/HTTP lokal dan memverifikasi nama span trace
yang diekspor, atribut berbatas, serta redaksi konten/pengenal tanpa
memerlukan Opik, Langfuse, atau kolektor eksternal lain.
- Jalankan `pnpm release:check` sebelum setiap rilis bertag
- Jalankan `OpenClaw Release Publish` untuk urutan publikasi yang melakukan mutasi setelah
tag tersedia. Dispatch dari `release/YYYY.M.D` (atau `main` saat memublikasikan tag
yang dapat dijangkau main), berikan tag rilis dan `preflight_run_id` npm OpenClaw
yang berhasil, dan pertahankan scope publikasi Plugin default
`all-publishable` kecuali Anda sengaja menjalankan perbaikan terfokus. Workflow ini
menserialkan publikasi npm Plugin, publikasi ClawHub Plugin, dan publikasi npm OpenClaw
agar paket inti tidak dipublikasikan sebelum Plugin eksternalnya.
- Pemeriksaan rilis sekarang berjalan dalam workflow manual terpisah:
- Jalankan `OpenClaw Release Publish` untuk urutan publikasi yang bermutasi setelah
tag tersedia. Dispatch dari `release/YYYY.M.D` (atau `main` ketika memublikasikan
tag yang dapat dijangkau main), berikan tag rilis dan OpenClaw npm
`preflight_run_id` yang berhasil, dan pertahankan cakupan publikasi plugin default
`all-publishable` kecuali Anda sengaja menjalankan perbaikan terfokus. Workflow
menyerialkan publikasi npm plugin, publikasi ClawHub plugin, dan publikasi npm OpenClaw
sehingga paket core tidak dipublikasikan sebelum plugin yang dieksternalisasi.
- Release checks sekarang berjalan dalam workflow manual terpisah:
`OpenClaw Release Checks`
- `OpenClaw Release Checks` juga menjalankan lane paritas mock QA Lab ditambah profil
Matrix live cepat dan lane QA Telegram sebelum persetujuan rilis. Lane live
- `OpenClaw Release Checks` juga menjalankan lane paritas mock QA Lab plus profil
live Matrix cepat dan lane QA Telegram sebelum persetujuan rilis. Lane live
menggunakan environment `qa-live-shared`; Telegram juga menggunakan lease kredensial
Convex CI. Jalankan workflow manual `QA-Lab - All Lanes` dengan
`matrix_profile=all` dan `matrix_shards=true` ketika Anda menginginkan inventaris
transport, media, dan E2EE Matrix penuh secara paralel.
`matrix_profile=all` dan `matrix_shards=true` ketika Anda menginginkan inventaris Matrix
transport, media, dan E2EE penuh secara paralel.
- Validasi runtime instalasi dan upgrade lintas-OS adalah bagian dari
`OpenClaw Release Checks` publik dan `Full Release Validation`, yang memanggil
`OpenClaw Release Checks` dan `Full Release Validation` publik, yang memanggil
workflow reusable
`.github/workflows/openclaw-cross-os-release-checks-reusable.yml` secara langsung
- Pemisahan ini disengaja: pertahankan jalur rilis npm nyata tetap singkat,
deterministik, dan berfokus pada artefak, sementara pemeriksaan live yang lebih lambat tetap berada
deterministik, dan berfokus artefak, sementara pemeriksaan live yang lebih lambat tetap berada
di lane sendiri agar tidak menahan atau memblokir publikasi
- Pemeriksaan rilis yang membawa secret harus di-dispatch melalui `Full Release
Validation` atau dari workflow ref `main`/rilis agar logika workflow dan
- Release checks yang membawa secret harus dijalankan melalui `Full Release
Validation` atau dari ref workflow `main`/release agar logika workflow dan
secret tetap terkendali
- `OpenClaw Release Checks` menerima branch, tag, atau SHA commit penuh selama
commit yang diselesaikan dapat dijangkau dari branch OpenClaw atau tag rilis
- Preflight hanya-validasi `OpenClaw NPM Release` juga menerima SHA commit branch-workflow
penuh 40 karakter saat ini tanpa memerlukan tag yang sudah di-push
- Preflight validation-only `OpenClaw NPM Release` juga menerima SHA commit
branch-workflow 40 karakter penuh saat ini tanpa memerlukan tag yang telah dipush
- Jalur SHA tersebut hanya untuk validasi dan tidak dapat dipromosikan menjadi publikasi nyata
- Dalam mode SHA, workflow mensintesis `v<package.json version>` hanya untuk
- Dalam mode SHA, workflow menyintesis `v<package.json version>` hanya untuk
pemeriksaan metadata paket; publikasi nyata tetap memerlukan tag rilis nyata
- Kedua workflow menjaga jalur publikasi dan promosi nyata pada runner yang di-host GitHub,
sementara jalur validasi non-mutasi dapat menggunakan runner Linux Blacksmith yang lebih besar
- Kedua workflow mempertahankan jalur publikasi dan promosi nyata pada runner
GitHub-hosted, sementara jalur validasi non-mutasi dapat menggunakan runner
Blacksmith Linux yang lebih besar
- Workflow tersebut menjalankan
`OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache`
menggunakan secret workflow `OPENAI_API_KEY` dan `ANTHROPIC_API_KEY`
@ -206,76 +210,76 @@ Validation` atau dari workflow ref `main`/rilis agar logika workflow dan
- Setelah publikasi npm, jalankan
`node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`
(atau versi beta/koreksi yang sesuai) untuk memverifikasi jalur instalasi registry
yang dipublikasikan dalam prefix temp baru
yang telah dipublikasikan dalam prefix temp yang baru
- Setelah publikasi beta, jalankan `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`
untuk memverifikasi onboarding paket terinstal, penyiapan Telegram, dan Telegram E2E nyata
terhadap paket npm yang dipublikasikan menggunakan pool kredensial Telegram ber-lease bersama.
One-off maintainer lokal dapat menghilangkan var Convex dan memberikan tiga
terhadap paket npm yang telah dipublikasikan menggunakan pool kredensial Telegram ber-lease
bersama. One-off maintainer lokal boleh menghilangkan var Convex dan meneruskan tiga
kredensial env `OPENCLAW_QA_TELEGRAM_*` secara langsung.
- Untuk menjalankan smoke beta pascapublikasi penuh dari mesin maintainer, gunakan `pnpm release:beta-smoke -- --beta betaN`. Helper menjalankan validasi update npm Parallels/target baru, menjalankan `NPM Telegram Beta E2E`, melakukan polling run workflow persis, mengunduh artefak, dan mencetak laporan Telegram.
- Maintainer dapat menjalankan pemeriksaan pascapublikasi yang sama dari GitHub Actions melalui
- Untuk menjalankan smoke beta pasca-publikasi penuh dari mesin maintainer, gunakan `pnpm release:beta-smoke -- --beta betaN`. Helper menjalankan validasi pembaruan npm Parallels/target-baru, mendispatch `NPM Telegram Beta E2E`, melakukan polling run workflow persis, mengunduh artefak, dan mencetak laporan Telegram.
- Maintainer dapat menjalankan pemeriksaan pasca-publikasi yang sama dari GitHub Actions melalui
workflow manual `NPM Telegram Beta E2E`. Workflow ini sengaja hanya manual dan
tidak berjalan pada setiap merge.
- Otomasi rilis maintainer sekarang menggunakan preflight-lalu-promote:
- publikasi npm nyata harus melewati `preflight_run_id` npm yang berhasil
- publikasi npm nyata harus di-dispatch dari branch `main` atau
- publikasi npm nyata harus dijalankan dari branch `main` atau
`release/YYYY.M.D` yang sama dengan run preflight yang berhasil
- rilis npm stabil default ke `beta`
- publikasi npm stabil dapat menargetkan `latest` secara eksplisit melalui input workflow
- mutasi dist-tag npm berbasis token sekarang berada di
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
untuk keamanan, karena `npm dist-tag add` masih memerlukan `NPM_TOKEN` sementara repo
publik mempertahankan publikasi hanya OIDC
- `macOS Release` publik hanya-validasi; ketika tag hanya berada pada
branch rilis tetapi workflow di-dispatch dari `main`, tetapkan
demi keamanan, karena `npm dist-tag add` masih memerlukan `NPM_TOKEN` sementara
repo publik mempertahankan publikasi hanya OIDC
- `macOS Release` publik hanya untuk validasi; ketika tag hanya berada di
branch rilis tetapi workflow dijalankan dari `main`, setel
`public_release_branch=release/YYYY.M.D`
- publikasi mac privat nyata harus melewati `preflight_run_id` dan `validate_run_id`
mac privat yang berhasil
- publikasi mac privat nyata harus melewati private mac
`preflight_run_id` dan `validate_run_id` yang berhasil
- jalur publikasi nyata mempromosikan artefak yang telah disiapkan alih-alih membangunnya
lagi
- Untuk rilis koreksi stabil seperti `YYYY.M.D-N`, verifier pascapublikasi
- Untuk rilis koreksi stabil seperti `YYYY.M.D-N`, verifier pasca-publikasi
juga memeriksa jalur upgrade prefix-temp yang sama dari `YYYY.M.D` ke `YYYY.M.D-N`
agar koreksi rilis tidak diam-diam meninggalkan instalasi global lama pada payload
stabil dasar
- Preflight rilis npm gagal tertutup kecuali tarball menyertakan
sehingga koreksi rilis tidak dapat diam-diam membiarkan instalasi global lama pada
payload stabil dasar
- Preflight rilis npm gagal tertutup kecuali tarball mencakup
`dist/control-ui/index.html` dan payload `dist/control-ui/assets/` yang tidak kosong
agar kita tidak mengirim dashboard browser kosong lagi
- Verifikasi pascapublikasi juga memeriksa bahwa entrypoint Plugin yang dipublikasikan dan
metadata paket tersedia dalam layout registry terinstal. Rilis yang
mengirim payload runtime Plugin yang hilang gagal pada verifier pascapublikasi dan
sehingga kita tidak mengirim dashboard browser kosong lagi
- Verifikasi pasca-publikasi juga memeriksa bahwa entrypoint plugin dan
metadata paket yang dipublikasikan tersedia dalam layout registry terinstal. Rilis yang
mengirim payload runtime plugin yang hilang akan menggagalkan verifier postpublish dan
tidak dapat dipromosikan ke `latest`.
- `pnpm test:install:smoke` juga menegakkan anggaran `unpackedSize` npm pack pada
tarball update kandidat, sehingga installer e2e menangkap pembengkakan pack yang tidak disengaja
- `pnpm test:install:smoke` juga memberlakukan anggaran `unpackedSize` pack npm pada
tarball pembaruan kandidat, sehingga installer e2e menangkap pembengkakan pack yang tidak disengaja
sebelum jalur publikasi rilis
- Jika pekerjaan rilis menyentuh perencanaan CI, manifest timing Plugin, atau
matriks pengujian Plugin, buat ulang dan tinjau output matriks
`plugin-prerelease-extension-shard` milik planner dari
`.github/workflows/plugin-prerelease.yml` sebelum persetujuan agar catatan rilis tidak
menggambarkan layout CI yang sudah kedaluwarsa
- Kesiapan rilis macOS stabil juga mencakup surface updater:
- rilis GitHub harus berakhir dengan `.zip`, `.dmg`, dan `.dSYM.zip` yang dipaketkan
- Jika pekerjaan rilis menyentuh perencanaan CI, manifest timing extension, atau
matriks pengujian extension, regenerasikan dan tinjau output matriks milik planner
`plugin-prerelease-extension-shard` dari
`.github/workflows/plugin-prerelease.yml` sebelum persetujuan agar release notes tidak
menggambarkan layout CI yang usang
- Kesiapan rilis macOS stabil juga mencakup permukaan updater:
- GitHub release harus berakhir dengan `.zip`, `.dmg`, dan `.dSYM.zip` yang telah dikemas
- `appcast.xml` pada `main` harus menunjuk ke zip stabil baru setelah publikasi
- aplikasi yang dipaketkan harus mempertahankan bundle id non-debug, URL feed Sparkle
- app yang dikemas harus mempertahankan bundle id non-debug, URL feed Sparkle
yang tidak kosong, dan `CFBundleVersion` pada atau di atas floor build Sparkle kanonis
untuk versi rilis tersebut
## Kotak pengujian rilis
`Full Release Validation` adalah cara operator memulai semua pengujian prarilis dari
satu entrypoint. Untuk bukti commit yang di-pin pada branch yang bergerak cepat, gunakan
helper agar setiap workflow turunan berjalan dari branch sementara yang dikunci pada
SHA target:
`Full Release Validation` adalah cara operator memulai semua pengujian pra-rilis dari
satu entrypoint. Untuk bukti commit yang dipin pada branch yang bergerak cepat, gunakan
helper agar setiap workflow anak berjalan dari branch sementara yang ditetapkan pada SHA
target:
```bash
pnpm ci:full-release --sha <full-sha>
```
Helper ini mendorong `release-ci/<sha>-...`, menjalankan `Full Release Validation`
dari branch tersebut dengan `ref=<sha>`, memverifikasi setiap `headSha` workflow turunan
cocok dengan target, lalu menghapus branch sementara. Ini menghindari pembuktian run
turunan `main` yang lebih baru secara tidak sengaja.
Helper mendorong `release-ci/<sha>-...`, mendispatch `Full Release Validation`
dari branch tersebut dengan `ref=<sha>`, memverifikasi setiap `headSha` workflow anak
cocok dengan target, lalu menghapus branch sementara. Ini menghindari pembuktian run anak
`main` yang lebih baru secara tidak sengaja.
Untuk validasi branch rilis atau tag, jalankan dari workflow ref `main` tepercaya
Untuk validasi branch rilis atau tag, jalankan dari ref workflow `main` yang tepercaya
dan berikan branch rilis atau tag sebagai `ref`:
```bash
@ -288,48 +292,51 @@ gh workflow run full-release-validation.yml \
-f evidence_package_spec=openclaw@YYYY.M.D-beta.N
```
Alur kerja menyelesaikan ref target, memicu `CI` manual dengan
`target_ref=<release-ref>`, memicu `OpenClaw Release Checks`, menyiapkan artefak
induk `release-package-under-test` untuk pemeriksaan yang berhadapan dengan paket,
dan memicu E2E Telegram paket mandiri ketika `release_profile=full` dengan
`rerun_group=all` atau ketika `npm_telegram_package_spec` disetel. `OpenClaw Release
Checks` kemudian menyebar ke install smoke, pemeriksaan rilis lintas-OS, cakupan
jalur rilis Docker live/E2E, Package Acceptance dengan QA paket Telegram, paritas
QA Lab, Matrix live, dan Telegram live. Run penuh hanya dapat diterima ketika
Alur kerja menyelesaikan ref target, menjalankan `CI` manual dengan
`target_ref=<release-ref>`, menjalankan `OpenClaw Release Checks`, menyiapkan
artefak induk `release-package-under-test` untuk pemeriksaan yang berhadapan
dengan paket, dan menjalankan E2E Telegram paket mandiri saat `release_profile=full` dengan
`rerun_group=all` atau saat `npm_telegram_package_spec` ditetapkan. `OpenClaw Release
Checks` kemudian menyebar ke install smoke, pemeriksaan rilis lintas OS, cakupan
jalur rilis Docker live/E2E saat soak diaktifkan, Package Acceptance dengan QA
paket Telegram, paritas QA Lab, Matrix live, dan Telegram live. Run penuh hanya dapat diterima saat
ringkasan `Full Release Validation`
menampilkan `normal_ci` dan `release_checks` berhasil. Dalam mode full/all,
child `npm_telegram` juga harus berhasil; di luar full/all, itu dilewati kecuali
`npm_telegram_package_spec` yang telah diterbitkan diberikan. Ringkasan verifier
akhir menyertakan tabel pekerjaan paling lambat untuk setiap child run, sehingga
manajer rilis dapat melihat critical path saat ini tanpa mengunduh log.
Lihat [Validasi rilis penuh](/id/reference/full-release-validation) untuk matriks
tahap lengkap, nama job workflow yang tepat, perbedaan profil stable versus full,
artefak, dan handle rerun terfokus.
Child workflow dipicu dari ref tepercaya yang menjalankan `Full Release
Validation`, biasanya `--ref main`, bahkan ketika target `ref` menunjuk ke branch
atau tag rilis yang lebih lama. Tidak ada input workflow-ref Full Release Validation
terpisah; pilih harness tepercaya dengan memilih ref run workflow.
Jangan gunakan `--ref main -f ref=<sha>` untuk bukti commit persis pada `main`
yang bergerak; SHA commit mentah tidak dapat menjadi ref dispatch workflow, jadi
gunakan `pnpm ci:full-release --sha <sha>` untuk membuat branch sementara yang
dipin.
menunjukkan `normal_ci` dan `release_checks` berhasil. Dalam mode full/all,
anak `npm_telegram` juga harus berhasil; di luar full/all, itu dilewati
kecuali `npm_telegram_package_spec` yang telah dipublikasikan disediakan. Ringkasan
verifier akhir menyertakan tabel pekerjaan terlambat untuk setiap run anak, sehingga manajer rilis
dapat melihat jalur kritis saat ini tanpa mengunduh log.
Lihat [Validasi rilis penuh](/id/reference/full-release-validation) untuk
matriks tahap lengkap, nama pekerjaan alur kerja yang persis, perbedaan profil
stable versus full, artefak, dan handle rerun terfokus.
Alur kerja anak dijalankan dari ref tepercaya yang menjalankan `Full Release
Validation`, biasanya `--ref main`, bahkan saat `ref` target menunjuk ke
branch atau tag rilis yang lebih lama. Tidak ada input ref alur kerja Full Release Validation
terpisah; pilih harness tepercaya dengan memilih ref run alur kerja.
Jangan gunakan `--ref main -f ref=<sha>` untuk bukti commit persis pada `main` yang bergerak;
SHA commit mentah tidak dapat menjadi ref dispatch alur kerja, jadi gunakan
`pnpm ci:full-release --sha <sha>` untuk membuat branch sementara yang dipin.
Gunakan `release_profile` untuk memilih cakupan live/provider:
Gunakan `release_profile` untuk memilih keluasan live/provider:
- `minimum`: jalur live dan Docker OpenAI/core yang tercepat dan kritis untuk rilis
- `stable`: minimum ditambah cakupan provider/backend stable untuk persetujuan rilis
- `full`: stable ditambah cakupan provider/media advisory yang luas
- `minimum`: jalur Docker dan live OpenAI/core yang tercepat dan kritis untuk rilis
- `stable`: minimum plus cakupan provider/backend stabil untuk persetujuan rilis
- `full`: stable plus cakupan provider/media advisory yang luas
`OpenClaw Release Checks` menggunakan ref workflow tepercaya untuk menyelesaikan
ref target sekali sebagai `release-package-under-test` dan menggunakan ulang
artefak itu dalam pemeriksaan Docker jalur rilis maupun Package Acceptance. Ini
menjaga semua box yang berhadapan dengan paket pada byte yang sama dan menghindari
build paket berulang. Install smoke OpenAI lintas-OS menggunakan
`OPENCLAW_CROSS_OS_OPENAI_MODEL` ketika variabel repo/org disetel, jika tidak
`openai/gpt-5.4`, karena lane ini membuktikan instalasi paket, onboarding,
startup gateway, dan satu giliran agen live, bukan melakukan benchmark pada model
default yang paling lambat. Matriks provider live yang lebih luas tetap menjadi
tempat untuk cakupan spesifik model.
Gunakan `run_release_soak=true` dengan `stable` saat lane yang memblokir rilis
hijau dan Anda menginginkan sapuan menyeluruh live/E2E, jalur rilis Docker, dan
upgrade-survivor all-since-2026.4.23 sebelum promosi. `full` menyiratkan
`run_release_soak=true`.
`OpenClaw Release Checks` menggunakan ref alur kerja tepercaya untuk menyelesaikan ref target
sekali sebagai `release-package-under-test` dan menggunakan ulang artefak itu di pemeriksaan lintas OS,
Package Acceptance, dan Docker jalur rilis saat soak berjalan. Ini menjaga
semua box yang berhadapan dengan paket pada byte yang sama dan menghindari build paket berulang.
Install smoke OpenAI lintas OS menggunakan `OPENCLAW_CROSS_OS_OPENAI_MODEL` saat
variabel repo/org ditetapkan, jika tidak `openai/gpt-5.4`, karena lane ini
membuktikan instalasi paket, onboarding, startup Gateway, dan satu giliran agen live
alih-alih membenchmark model default yang paling lambat. Matriks provider live
yang lebih luas tetap menjadi tempat cakupan khusus model.
Gunakan varian ini tergantung tahap rilis:
@ -361,43 +368,44 @@ gh workflow run full-release-validation.yml \
-f npm_telegram_provider_mode=mock-openai
```
Jangan gunakan payung penuh sebagai rerun pertama setelah perbaikan terfokus. Jika
satu box gagal, gunakan child workflow, job, lane Docker, profil paket, provider
model, atau lane QA yang gagal untuk bukti berikutnya. Jalankan payung penuh lagi
hanya ketika perbaikan mengubah orkestrasi rilis bersama atau membuat bukti semua
box sebelumnya menjadi usang. Verifier akhir payung memeriksa ulang id run child
workflow yang direkam, jadi setelah child workflow berhasil direrun, rerun hanya
job induk `Verify full validation` yang gagal.
Jangan gunakan umbrella penuh sebagai rerun pertama setelah perbaikan terfokus. Jika satu box
gagal, gunakan alur kerja anak, pekerjaan, lane Docker, profil paket, provider
model, atau lane QA yang gagal untuk bukti berikutnya. Jalankan umbrella penuh lagi hanya saat
perbaikan mengubah orkestrasi rilis bersama atau membuat bukti semua box sebelumnya
usang. Verifier akhir umbrella memeriksa ulang id run alur kerja anak yang direkam,
jadi setelah alur kerja anak dijalankan ulang dengan berhasil, jalankan ulang hanya pekerjaan induk
`Verify full validation` yang gagal.
Untuk pemulihan terbatas, berikan `rerun_group` ke payung. `all` adalah run
release-candidate sebenarnya, `ci` hanya menjalankan child CI normal,
`plugin-prerelease` hanya menjalankan child Plugin khusus rilis, `release-checks`
menjalankan setiap box rilis, dan grup rilis yang lebih sempit adalah
`install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live`,
dan `npm-telegram`. Rerun `npm-telegram` terfokus memerlukan
`npm_telegram_package_spec`; run full/all dengan `release_profile=full` menggunakan
artefak paket release-checks.
Untuk pemulihan terbatas, berikan `rerun_group` ke umbrella. `all` adalah run
kandidat rilis yang sebenarnya, `ci` hanya menjalankan anak CI normal, `plugin-prerelease`
hanya menjalankan anak Plugin khusus rilis, `release-checks` menjalankan setiap box rilis,
dan grup rilis yang lebih sempit adalah `install-smoke`, `cross-os`,
`live-e2e`, `package`, `qa`, `qa-parity`, `qa-live`, dan `npm-telegram`.
Rerun `npm-telegram` terfokus memerlukan `npm_telegram_package_spec`; run full/all
dengan `release_profile=full` menggunakan artefak paket release-checks. Rerun
lintas OS terfokus dapat menambahkan `cross_os_suite_filter=windows/packaged-upgrade` atau
filter OS/suite lain. Kegagalan QA release-check bersifat advisory; kegagalan khusus QA
tidak memblokir validasi rilis.
### Vitest
Box Vitest adalah child workflow `CI` manual. CI manual sengaja melewati scoping
perubahan dan memaksa graph tes normal untuk kandidat rilis: shard Node Linux,
shard Plugin bundled, kontrak channel, kompatibilitas Node 22, `check`,
`check-additional`, build smoke, pemeriksaan docs, Skills Python, Windows, macOS,
Android, dan i18n Control UI.
Box Vitest adalah alur kerja anak `CI` manual. CI manual sengaja
melewati cakupan changed dan memaksa grafik tes normal untuk kandidat rilis:
shard Linux Node, shard Plugin bundled, kontrak channel, kompatibilitas Node 22,
`check`, `check-additional`, build smoke, pemeriksaan docs, Skills Python,
Windows, macOS, Android, dan i18n Control UI.
Gunakan box ini untuk menjawab "apakah source tree lulus suite tes normal penuh?"
Gunakan box ini untuk menjawab "apakah pohon sumber lolos suite tes normal penuh?"
Ini tidak sama dengan validasi produk jalur rilis. Bukti yang perlu disimpan:
- ringkasan `Full Release Validation` yang menampilkan URL run `CI` yang dipicu
- run `CI` hijau pada SHA target yang tepat
- nama shard yang gagal atau lambat dari job CI saat menyelidiki regresi
- artefak timing Vitest seperti `.artifacts/vitest-shard-timings.json` ketika
- ringkasan `Full Release Validation` yang menunjukkan URL run `CI` yang dijalankan
- run `CI` hijau pada SHA target yang persis
- nama shard yang gagal atau lambat dari pekerjaan CI saat menyelidiki regresi
- artefak timing Vitest seperti `.artifacts/vitest-shard-timings.json` saat
suatu run memerlukan analisis performa
Jalankan CI manual secara langsung hanya ketika rilis memerlukan CI normal yang
deterministik tetapi tidak memerlukan box Docker, QA Lab, live, lintas-OS, atau
paket:
Jalankan CI manual secara langsung hanya saat rilis memerlukan CI normal yang deterministik tetapi
bukan box Docker, QA Lab, live, lintas OS, atau paket:
```bash
gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
@ -406,16 +414,15 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
### Docker
Box Docker berada di `OpenClaw Release Checks` melalui
`openclaw-live-and-e2e-checks-reusable.yml`, ditambah workflow `install-smoke`
mode rilis. Ini memvalidasi kandidat rilis melalui lingkungan Docker berpacak
paket, bukan hanya tes tingkat source.
`openclaw-live-and-e2e-checks-reusable.yml`, plus alur kerja
`install-smoke` mode rilis. Ini memvalidasi kandidat rilis melalui lingkungan
Docker terpaket alih-alih hanya tes tingkat sumber.
Cakupan Docker rilis mencakup:
- install smoke penuh dengan install smoke global Bun yang lambat diaktifkan
- persiapan/penggunaan ulang image smoke Dockerfile root berdasarkan SHA target,
dengan job smoke QR, root/gateway, dan installer/Bun berjalan sebagai shard
install-smoke terpisah
- install smoke penuh dengan smoke install global Bun yang lambat diaktifkan
- persiapan/penggunaan ulang image smoke Dockerfile root berdasarkan SHA target, dengan pekerjaan QR,
root/Gateway, dan smoke installer/Bun berjalan sebagai shard install-smoke terpisah
- lane E2E repositori
- chunk Docker jalur rilis: `core`, `package-update-openai`,
`package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`,
@ -424,96 +431,94 @@ Cakupan Docker rilis mencakup:
`plugins-runtime-install-c`, `plugins-runtime-install-d`,
`plugins-runtime-install-e`, `plugins-runtime-install-f`,
`plugins-runtime-install-g`, dan `plugins-runtime-install-h`
- cakupan OpenWebUI di dalam chunk `plugins-runtime-services` ketika diminta
- lane install/uninstall Plugin bundled yang dibagi
`bundled-plugin-install-uninstall-0` sampai
- cakupan OpenWebUI di dalam chunk `plugins-runtime-services` saat diminta
- lane install/uninstall Plugin bundled yang dipisah
`bundled-plugin-install-uninstall-0` hingga
`bundled-plugin-install-uninstall-23`
- suite provider live/E2E dan cakupan model live Docker ketika release checks
- suite provider live/E2E dan cakupan model live Docker saat pemeriksaan rilis
menyertakan suite live
Gunakan artefak Docker sebelum melakukan rerun. Scheduler jalur rilis mengunggah
Gunakan artefak Docker sebelum menjalankan ulang. Scheduler jalur rilis mengunggah
`.artifacts/docker-tests/` dengan log lane, `summary.json`, `failures.json`,
timing fase, JSON rencana scheduler, dan perintah rerun. Untuk pemulihan terfokus,
gunakan `docker_lanes=<lane[,lane]>` pada workflow live/E2E reusable alih-alih
mererun semua chunk rilis. Perintah rerun yang dihasilkan menyertakan
`package_artifact_run_id` sebelumnya dan input image Docker yang disiapkan ketika
tersedia, sehingga lane yang gagal dapat menggunakan ulang tarball dan image GHCR
yang sama.
gunakan `docker_lanes=<lane[,lane]>` pada alur kerja live/E2E reusable alih-alih
menjalankan ulang semua chunk rilis. Perintah rerun yang dihasilkan menyertakan
`package_artifact_run_id` sebelumnya dan input image Docker yang disiapkan bila tersedia, sehingga
lane yang gagal dapat menggunakan ulang tarball dan image GHCR yang sama.
### QA Lab
Box QA Lab juga merupakan bagian dari `OpenClaw Release Checks`. Ini adalah gate
rilis perilaku agentic dan tingkat channel, terpisah dari mekanika paket Vitest
dan Docker.
Box QA Lab juga merupakan bagian dari `OpenClaw Release Checks`. Ini adalah gate rilis
perilaku agentic dan tingkat channel, terpisah dari mekanika paket Vitest dan Docker.
Cakupan QA Lab rilis mencakup:
- lane paritas mock yang membandingkan lane kandidat OpenAI dengan baseline Opus 4.6
menggunakan paket paritas agentic
- profil QA Matrix live cepat menggunakan environment `qa-live-shared`
- lane QA Telegram live menggunakan sewa kredensial Convex CI
- `pnpm qa:otel:smoke` ketika telemetri rilis memerlukan bukti lokal eksplisit
- profil QA Matrix live cepat menggunakan lingkungan `qa-live-shared`
- lane QA Telegram live menggunakan lease kredensial CI Convex
- `pnpm qa:otel:smoke` saat telemetri rilis memerlukan bukti lokal eksplisit
Gunakan box ini untuk menjawab "apakah rilis berperilaku benar dalam skenario QA
dan alur channel live?" Simpan URL artefak untuk lane paritas, Matrix, dan Telegram
Gunakan box ini untuk menjawab "apakah rilis berperilaku benar dalam skenario QA dan
alur channel live?" Simpan URL artefak untuk lane paritas, Matrix, dan Telegram
saat menyetujui rilis. Cakupan Matrix penuh tetap tersedia sebagai run QA-Lab
sharded manual, bukan lane kritis rilis default.
manual bershard, bukan lane default yang kritis untuk rilis.
### Package
### Paket
Box Package adalah gate produk yang dapat diinstal. Ini didukung oleh
Box Paket adalah gate produk yang dapat diinstal. Ini didukung oleh
`Package Acceptance` dan resolver
`scripts/resolve-openclaw-package-candidate.mjs`. Resolver menormalkan kandidat
menjadi tarball `package-under-test` yang dikonsumsi oleh Docker E2E, memvalidasi
inventaris paket, mencatat versi paket dan SHA-256, serta menjaga ref harness
workflow terpisah dari ref sumber paket.
`scripts/resolve-openclaw-package-candidate.mjs`. Resolver menormalisasi
kandidat menjadi tarball `package-under-test` yang dikonsumsi oleh Docker E2E, memvalidasi
inventaris paket, merekam versi paket dan SHA-256, serta menjaga
ref harness alur kerja terpisah dari ref sumber paket.
Sumber kandidat yang didukung:
- `source=npm`: `openclaw@beta`, `openclaw@latest`, atau versi rilis OpenClaw yang tepat
- `source=ref`: kemas branch, tag, atau SHA commit penuh `package_ref` tepercaya
- `source=npm`: `openclaw@beta`, `openclaw@latest`, atau versi rilis OpenClaw
yang persis
- `source=ref`: pack branch, tag, atau SHA commit penuh `package_ref` tepercaya
dengan harness `workflow_ref` yang dipilih
- `source=url`: unduh `.tgz` HTTPS dengan `package_sha256` wajib
- `source=artifact`: gunakan ulang `.tgz` yang diunggah oleh run GitHub Actions lain
`OpenClaw Release Checks` menjalankan Package Acceptance dengan `source=artifact`,
artefak paket rilis yang disiapkan, `suite_profile=custom`,
`OpenClaw Release Checks` menjalankan Package Acceptance dengan `source=artifact`, artefak
paket rilis yang disiapkan, `suite_profile=custom`,
`docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`,
`published_upgrade_survivor_baselines=all-since-2026.4.23`,
`published_upgrade_survivor_scenarios=reported-issues`, dan
`telegram_mode=mock-openai`. Package Acceptance menjaga migrasi, pembaruan,
pembersihan dependensi Plugin usang, fixture Plugin offline, pembaruan Plugin,
dan QA paket Telegram terhadap tarball terselesaikan yang sama. Matriks upgrade
mencakup setiap baseline stable yang dipublikasikan npm dari `2026.4.23` sampai
`latest`; gunakan Package Acceptance dengan `source=npm` untuk kandidat yang
sudah dikirim, atau `source=ref`/`source=artifact` untuk tarball npm lokal
berbasis SHA sebelum publish. Ini adalah pengganti native GitHub untuk sebagian
besar cakupan package/update yang sebelumnya memerlukan Parallels. Pemeriksaan
rilis lintas-OS tetap penting untuk onboarding, installer, dan perilaku platform
spesifik OS, tetapi validasi produk package/update sebaiknya mengutamakan
Package Acceptance.
`telegram_mode=mock-openai`. Package Acceptance menjaga migrasi, update, pembersihan
dependensi Plugin basi, fixture Plugin offline, update Plugin, dan QA paket Telegram
terhadap tarball terselesaikan yang sama. Pemeriksaan rilis yang memblokir menggunakan
baseline paket terbaru yang telah dipublikasikan secara default; `run_release_soak=true` atau
`release_profile=full` memperluas ke setiap baseline stabil yang dipublikasikan npm dari
`2026.4.23` hingga `latest` plus fixture isu yang dilaporkan. Gunakan
Package Acceptance dengan `source=npm` untuk kandidat yang sudah dikirim, atau
`source=ref`/`source=artifact` untuk tarball npm lokal berbasis SHA sebelum
publikasi. Ini adalah pengganti GitHub-native
untuk sebagian besar cakupan paket/update yang sebelumnya memerlukan
Parallels. Pemeriksaan rilis lintas OS masih penting untuk onboarding, installer,
dan perilaku platform khusus OS, tetapi validasi produk paket/update sebaiknya
memilih Package Acceptance.
Checklist kanonis untuk validasi pembaruan dan Plugin adalah
[Menguji pembaruan dan Plugin](/id/help/testing-updates-plugins). Gunakan ini saat
memutuskan lane lokal, Docker, Package Acceptance, atau release-check mana yang
membuktikan perubahan install/update Plugin, cleanup doctor, atau migrasi paket
yang dipublikasikan. Migrasi pembaruan publikasi lengkap dari setiap paket stable
`2026.4.23+` adalah workflow `Update Migration` manual terpisah, bukan bagian
dari Full Release CI.
Checklist kanonis untuk validasi update dan Plugin adalah
[Menguji update dan Plugin](/id/help/testing-updates-plugins). Gunakan itu saat
menentukan lane lokal, Docker, Package Acceptance, atau release-check mana yang membuktikan
instalasi/update Plugin, pembersihan doctor, atau perubahan migrasi paket yang dipublikasikan.
Migrasi update publikasi menyeluruh dari setiap paket stabil `2026.4.23+` adalah
alur kerja `Update Migration` manual terpisah, bukan bagian dari Full Release CI.
Kelonggaran package-acceptance legacy sengaja dibatasi waktu. Paket hingga
`2026.4.25` dapat menggunakan jalur kompatibilitas untuk celah metadata yang sudah
dipublikasikan ke npm: entri inventaris QA privat yang hilang dari tarball,
`gateway install --wrapper` yang hilang, file patch yang hilang dalam fixture git
turunan tarball, `update.channel` tersimpan yang hilang, lokasi install-record
Plugin legacy, persistensi install-record marketplace yang hilang, dan migrasi
metadata config selama `plugins update`. Paket `2026.4.26` yang dipublikasikan
dapat memberi peringatan untuk file stamp metadata build lokal yang sudah
dikirim. Paket berikutnya harus memenuhi kontrak paket modern; celah yang sama
akan menggagalkan validasi rilis.
`2026.4.25` dapat menggunakan jalur kompatibilitas untuk celah metadata yang sudah dipublikasikan
ke npm: entri inventaris QA privat yang hilang dari tarball, `gateway install --wrapper`
yang hilang, file patch yang hilang dalam fixture git turunan tarball,
`update.channel` yang tidak dipertahankan, lokasi install-record Plugin legacy,
persistensi install-record marketplace yang hilang, dan migrasi metadata konfigurasi
selama `plugins update`. Paket `2026.4.26` yang dipublikasikan dapat memberi peringatan
untuk file stamp metadata build lokal yang sudah dikirim. Paket berikutnya
harus memenuhi kontrak paket modern; celah yang sama menggagalkan validasi
rilis.
Gunakan profil Package Acceptance yang lebih luas ketika pertanyaan rilis adalah
tentang paket yang benar-benar dapat diinstal:
Gunakan profil Package Acceptance yang lebih luas saat pertanyaan rilis adalah tentang
paket aktual yang dapat diinstal:
```bash
gh workflow run package-acceptance.yml \
@ -529,31 +534,31 @@ Profil paket umum:
- `smoke`: jalur pemasangan paket/kanal/agen cepat, jaringan Gateway, dan pemuatan ulang
konfigurasi
- `package`: kontrak pemasangan/pembaruan/paket Plugin tanpa ClawHub langsung; ini adalah
bawaan release-check
- `package`: kontrak pemasangan/pembaruan/paket Plugin tanpa ClawHub langsung; ini adalah default
pemeriksaan rilis
- `product`: `package` ditambah kanal MCP, pembersihan cron/subagen, pencarian web
OpenAI, dan OpenWebUI
- `full`: potongan jalur rilis Docker dengan OpenWebUI
- `custom`: daftar `docker_lanes` persis untuk pengulangan terfokus
Untuk bukti Telegram kandidat paket, aktifkan `telegram_mode=mock-openai` atau
`telegram_mode=live-frontier` pada Package Acceptance. Alur kerja meneruskan
tarball `package-under-test` yang telah diselesaikan ke jalur Telegram; alur kerja
Telegram mandiri tetap menerima spesifikasi npm yang telah dipublikasikan untuk pemeriksaan pascapublikasi.
`telegram_mode=live-frontier` di Package Acceptance. Alur kerja meneruskan tarball
`package-under-test` yang diselesaikan ke jalur Telegram; alur kerja Telegram mandiri
tetap menerima spesifikasi npm yang sudah diterbitkan untuk pemeriksaan pascapublikasi.
## Otomatisasi publikasi rilis
## Otomasi publikasi rilis
`OpenClaw Release Publish` adalah titik masuk publikasi bermutasi normal. Ini
mengorkestrasi alur kerja trusted-publisher sesuai urutan yang dibutuhkan rilis:
`OpenClaw Release Publish` adalah titik masuk publikasi mutatif normal. Ia
mengorkestrasi alur kerja penerbit tepercaya dalam urutan yang dibutuhkan rilis:
1. Check out tag rilis dan selesaikan SHA commit-nya.
2. Verifikasi tag dapat dijangkau dari `main` atau `release/*`.
1. Checkout tag rilis dan selesaikan SHA commit-nya.
2. Verifikasi bahwa tag dapat dijangkau dari `main` atau `release/*`.
3. Jalankan `pnpm plugins:sync:check`.
4. Dispatch `Plugin NPM Release` dengan `publish_scope=all-publishable` dan
`ref=<release-sha>`.
5. Dispatch `Plugin ClawHub Release` dengan cakupan dan SHA yang sama.
6. Dispatch `OpenClaw NPM Release` dengan tag rilis, dist-tag npm, dan
`preflight_run_id` yang tersimpan.
`preflight_run_id` yang disimpan.
Contoh publikasi beta:
@ -565,7 +570,7 @@ gh workflow run openclaw-release-publish.yml \
-f npm_dist_tag=beta
```
Publikasi stabil ke dist-tag beta bawaan:
Publikasi stabil ke dist-tag beta default:
```bash
gh workflow run openclaw-release-publish.yml \
@ -586,90 +591,93 @@ gh workflow run openclaw-release-publish.yml \
```
Gunakan alur kerja tingkat lebih rendah `Plugin NPM Release` dan `Plugin ClawHub Release`
hanya untuk pekerjaan perbaikan atau publikasi ulang yang terfokus. Untuk perbaikan Plugin
terpilih, berikan `plugin_publish_scope=selected` dan `plugins=@openclaw/name` ke
`OpenClaw Release Publish`, atau dispatch alur kerja anak secara langsung ketika paket
OpenClaw tidak boleh dipublikasikan.
hanya untuk pekerjaan perbaikan atau publikasi ulang terfokus. Untuk perbaikan Plugin terpilih, berikan
`plugin_publish_scope=selected` dan `plugins=@openclaw/name` ke
`OpenClaw Release Publish`, atau dispatch alur kerja anak secara langsung saat paket
OpenClaw tidak boleh diterbitkan.
## Input alur kerja NPM
`OpenClaw NPM Release` menerima input yang dikendalikan operator berikut:
- `tag`: tag rilis wajib seperti `v2026.4.2`, `v2026.4.2-1`, atau
`v2026.4.2-beta.1`; saat `preflight_only=true`, ini juga dapat berupa SHA commit
cabang alur kerja lengkap 40 karakter saat ini untuk preflight khusus validasi
- `preflight_only`: `true` hanya untuk validasi/build/paket, `false` untuk jalur
publikasi sebenarnya
`v2026.4.2-beta.1`; ketika `preflight_only=true`, ini juga dapat berupa SHA commit
40 karakter penuh cabang alur kerja saat ini untuk preflight khusus validasi
- `preflight_only`: `true` hanya untuk validasi/build/paket, `false` untuk
jalur publikasi sebenarnya
- `preflight_run_id`: wajib pada jalur publikasi sebenarnya agar alur kerja menggunakan kembali
tarball yang telah disiapkan dari proses preflight yang berhasil
- `npm_dist_tag`: tag target npm untuk jalur publikasi; bawaan ke `beta`
tarball yang disiapkan dari proses preflight yang berhasil
- `npm_dist_tag`: tag target npm untuk jalur publikasi; default ke `beta`
`OpenClaw Release Publish` menerima input yang dikendalikan operator berikut:
- `tag`: tag rilis wajib; harus sudah ada
- `preflight_run_id`: id proses preflight `OpenClaw NPM Release` yang berhasil;
wajib saat `publish_openclaw_npm=true`
wajib ketika `publish_openclaw_npm=true`
- `npm_dist_tag`: tag target npm untuk paket OpenClaw
- `plugin_publish_scope`: bawaan ke `all-publishable`; gunakan `selected` hanya
- `plugin_publish_scope`: default ke `all-publishable`; gunakan `selected` hanya
untuk pekerjaan perbaikan terfokus
- `plugins`: nama paket `@openclaw/*` yang dipisahkan koma saat
- `plugins`: nama paket `@openclaw/*` yang dipisahkan koma ketika
`plugin_publish_scope=selected`
- `publish_openclaw_npm`: bawaan ke `true`; tetapkan `false` hanya saat menggunakan
- `publish_openclaw_npm`: default ke `true`; setel `false` hanya saat menggunakan
alur kerja sebagai orkestrator perbaikan khusus Plugin
`OpenClaw Release Checks` menerima input yang dikendalikan operator berikut:
- `ref`: cabang, tag, atau SHA commit lengkap yang akan divalidasi. Pemeriksaan yang memuat rahasia
- `ref`: cabang, tag, atau SHA commit penuh untuk divalidasi. Pemeriksaan yang membawa secret
mengharuskan commit yang diselesaikan dapat dijangkau dari cabang OpenClaw atau
tag rilis.
- `run_release_soak`: ikut serta dalam soak live/E2E menyeluruh, jalur rilis Docker, dan
upgrade-survivor sejak awal pada pemeriksaan rilis stabil/default. Ini dipaksa
aktif oleh `release_profile=full`.
Aturan:
- Tag stabil dan koreksi dapat dipublikasikan ke `beta` atau `latest`
- Tag prarilis beta hanya dapat dipublikasikan ke `beta`
- Untuk `OpenClaw NPM Release`, input SHA commit lengkap hanya diizinkan saat
- Untuk `OpenClaw NPM Release`, input SHA commit penuh hanya diizinkan ketika
`preflight_only=true`
- `OpenClaw Release Checks` dan `Full Release Validation` selalu
khusus validasi
hanya validasi
- Jalur publikasi sebenarnya harus menggunakan `npm_dist_tag` yang sama dengan yang digunakan selama preflight;
alur kerja memverifikasi metadata tersebut sebelum publikasi berlanjut
alur kerja memverifikasi metadata tersebut sebelum publikasi dilanjutkan
## Urutan rilis npm stabil
Saat membuat rilis npm stabil:
1. Jalankan `OpenClaw NPM Release` dengan `preflight_only=true`
- Sebelum tag ada, Anda dapat menggunakan SHA commit cabang alur kerja lengkap saat ini
- Sebelum tag ada, Anda dapat menggunakan SHA commit penuh cabang alur kerja saat ini
untuk dry run khusus validasi dari alur kerja preflight
2. Pilih `npm_dist_tag=beta` untuk alur normal beta-terlebih-dahulu, atau `latest` hanya
saat Anda sengaja menginginkan publikasi stabil langsung
3. Jalankan `Full Release Validation` pada cabang rilis, tag rilis, atau SHA commit lengkap
saat Anda menginginkan CI normal ditambah cakupan cache prompt langsung, Docker, QA Lab,
ketika Anda sengaja menginginkan publikasi stabil langsung
3. Jalankan `Full Release Validation` pada cabang rilis, tag rilis, atau SHA
commit penuh saat Anda menginginkan CI normal ditambah cakupan cache prompt live, Docker, QA Lab,
Matrix, dan Telegram dari satu alur kerja manual
4. Jika Anda sengaja hanya membutuhkan grafik pengujian normal yang deterministik, jalankan
alur kerja manual `CI` pada ref rilis sebagai gantinya
5. Simpan `preflight_run_id` yang berhasil
6. Jalankan `OpenClaw Release Publish` dengan `tag` yang sama, `npm_dist_tag` yang sama,
dan `preflight_run_id` yang tersimpan; ini memublikasikan Plugin yang dieksternalisasi ke npm
dan `preflight_run_id` yang disimpan; ini menerbitkan Plugin yang dieksternalisasi ke npm
dan ClawHub sebelum mempromosikan paket npm OpenClaw
7. Jika rilis mendarat di `beta`, gunakan alur kerja privat
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
untuk mempromosikan versi stabil tersebut dari `beta` ke `latest`
8. Jika rilis sengaja dipublikasikan langsung ke `latest` dan `beta`
harus segera mengikuti build stabil yang sama, gunakan alur kerja privat yang sama
untuk mengarahkan kedua dist-tag ke versi stabil, atau biarkan sinkronisasi
pemulihan mandiri terjadwalnya memindahkan `beta` nanti
untuk mengarahkan kedua dist-tag ke versi stabil, atau biarkan sinkronisasi pemulihan mandiri
terjadwalnya memindahkan `beta` nanti
Mutasi dist-tag berada di repo privat demi keamanan karena masih
memerlukan `NPM_TOKEN`, sementara repo publik mempertahankan publikasi khusus OIDC.
memerlukan `NPM_TOKEN`, sementara repo publik mempertahankan publikasi hanya OIDC.
Itu membuat jalur publikasi langsung dan jalur promosi beta-terlebih-dahulu sama-sama
Itu menjaga jalur publikasi langsung dan jalur promosi beta-terlebih-dahulu tetap
terdokumentasi dan terlihat oleh operator.
Jika maintainer harus fallback ke autentikasi npm lokal, jalankan perintah CLI 1Password
(`op`) hanya di dalam sesi tmux khusus. Jangan panggil `op`
langsung dari shell agen utama; menempatkannya di dalam tmux membuat prompt,
peringatan, dan penanganan OTP dapat diamati dan mencegah peringatan host berulang.
(`op`) apa pun hanya di dalam sesi tmux khusus. Jangan panggil `op`
langsung dari shell agen utama; menjaganya di dalam tmux membuat prompt,
peringatan, dan penanganan OTP dapat diamati serta mencegah peringatan host berulang.
## Referensi publik

191
docs/id/reference/full-release-validation.md
View File

@ -2,24 +2,21 @@
read_when:
- Menjalankan atau menjalankan ulang Validasi Rilis Penuh
- Membandingkan profil validasi rilis stabil dan lengkap
- Memecahkan masalah kegagalan tahap validasi rilis
summary: Tahapan Validasi Rilis Penuh, alur kerja turunan, profil rilis, pegangan jalankan ulang, dan bukti
- Men-debug kegagalan tahap validasi rilis
summary: Tahapan Validasi Rilis Lengkap, alur kerja turunan, profil rilis, rujukan untuk menjalankan ulang, dan bukti
title: Validasi rilis penuh
x-i18n:
generated_at: "2026-05-03T21:36:23Z"
generated_at: "2026-05-05T01:49:17Z"
model: gpt-5.5
provider: openai
source_hash: 038901ad751c00b35f69d7ec5caf74e577dcf2350d7658037c3ecc9ff5fab6d7
source_hash: 6cf696761f516fc7f8e9606a2a06fab61a644731330eb484a388f276767a9e0d
source_path: reference/full-release-validation.md
workflow: 16
---
`Full Release Validation` adalah payung rilis. Ini adalah titik masuk manual tunggal
untuk bukti pra-rilis, tetapi sebagian besar pekerjaan terjadi di workflow anak sehingga
kotak yang gagal dapat dijalankan ulang tanpa memulai ulang seluruh rilis.
`Full Release Validation` adalah payung rilis. Ini adalah satu titik masuk manual untuk bukti pra-rilis, tetapi sebagian besar pekerjaan terjadi di workflow anak agar kotak yang gagal dapat dijalankan ulang tanpa memulai ulang seluruh rilis.
Jalankan dari ref workflow tepercaya, biasanya `main`, dan teruskan cabang rilis,
tag, atau SHA commit lengkap sebagai `ref`:
Jalankan dari ref workflow tepercaya, biasanya `main`, dan teruskan branch rilis, tag, atau SHA commit lengkap sebagai `ref`:
```bash
gh workflow run full-release-validation.yml \
@ -30,97 +27,90 @@ gh workflow run full-release-validation.yml \
-f release_profile=stable
```
Workflow anak menggunakan ref workflow tepercaya untuk harness dan input
`ref` untuk kandidat yang sedang diuji. Ini membuat logika validasi baru tetap tersedia
saat memvalidasi cabang atau tag rilis yang lebih lama.
Workflow anak menggunakan ref workflow tepercaya untuk harness dan input `ref` untuk kandidat yang diuji. Itu membuat logika validasi baru tetap tersedia saat memvalidasi branch atau tag rilis yang lebih lama.
Package Acceptance biasanya membangun tarball kandidat dari
`ref` yang telah di-resolve, termasuk run SHA lengkap yang dikirim dengan `pnpm ci:full-release`. Setelah
publish, teruskan `package_acceptance_package_spec=openclaw@YYYY.M.D` (atau
`openclaw@beta`/`openclaw@latest`) untuk menjalankan matriks package/update yang sama terhadap
package npm yang sudah dikirim sebagai gantinya.
Secara default, `release_profile=stable` menjalankan lane pemblokir rilis dan melewati soak live/Docker yang menyeluruh. Teruskan `run_release_soak=true` untuk menyertakan lane soak pada run stabil. `release_profile=full` selalu mengaktifkan lane soak sehingga profil advisory yang luas tidak pernah kehilangan cakupan secara diam-diam.
Package Acceptance biasanya membangun tarball kandidat dari `ref` yang telah di-resolve, termasuk run SHA lengkap yang dikirim dengan `pnpm ci:full-release`. Setelah publish, teruskan `package_acceptance_package_spec=openclaw@YYYY.M.D` (atau `openclaw@beta`/`openclaw@latest`) untuk menjalankan matriks package/update yang sama terhadap package npm yang telah dikirim sebagai gantinya.
## Tahap tingkat atas
| Tahap | Detail |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Resolusi target | **Job:** `Resolve target ref`<br />**Workflow anak:** tidak ada<br />**Membuktikan:** me-resolve cabang rilis, tag, atau SHA commit lengkap dan mencatat input yang dipilih.<br />**Jalankan ulang:** jalankan ulang payung jika ini gagal. |
| Vitest dan CI normal | **Job:** `Run normal full CI`<br />**Workflow anak:** `CI`<br />**Membuktikan:** grafik CI penuh manual terhadap ref target, termasuk lane Node Linux, shard Plugin terbundel, kontrak channel, kompatibilitas Node 22, `check`, `check-additional`, smoke build, pemeriksaan docs, Skills Python, Windows, macOS, i18n Control UI, dan Android melalui payung.<br />**Jalankan ulang:** `rerun_group=ci`. |
| Pra-rilis Plugin | **Job:** `Run plugin prerelease validation`<br />**Workflow anak:** `Plugin Prerelease`<br />**Membuktikan:** pemeriksaan statis Plugin khusus rilis, cakupan Plugin agentik, shard batch ekstensi penuh, dan lane Docker pra-rilis Plugin.<br />**Jalankan ulang:** `rerun_group=plugin-prerelease`. |
| Pemeriksaan rilis | **Job:** `Run release/live/Docker/QA validation`<br />**Workflow anak:** `OpenClaw Release Checks`<br />**Membuktikan:** smoke instalasi, pemeriksaan package lintas OS, suite live/E2E, potongan jalur rilis Docker, Package Acceptance, paritas QA Lab, Matrix live, dan Telegram live.<br />**Jalankan ulang:** `rerun_group=release-checks` atau handle release-checks yang lebih sempit. |
| Artefak package | **Job:** `Prepare release package artifact`<br />**Workflow anak:** tidak ada<br />**Membuktikan:** membuat tarball induk `release-package-under-test` cukup awal untuk pemeriksaan yang menghadap package yang tidak perlu menunggu `OpenClaw Release Checks`.<br />**Jalankan ulang:** jalankan ulang payung atau berikan `npm_telegram_package_spec` untuk `rerun_group=npm-telegram`. |
| Package Telegram | **Job:** `Run package Telegram E2E`<br />**Workflow anak:** `NPM Telegram Beta E2E`<br />**Membuktikan:** bukti package Telegram yang didukung artefak induk untuk `rerun_group=all` dengan `release_profile=full`, atau bukti Telegram package yang dipublikasikan saat `npm_telegram_package_spec` disetel.<br />**Jalankan ulang:** `rerun_group=npm-telegram` dengan `npm_telegram_package_spec`. |
| Verifikator payung | **Job:** `Verify full validation`<br />**Workflow anak:** tidak ada<br />**Membuktikan:** memeriksa ulang kesimpulan run anak yang tercatat dan menambahkan tabel job paling lambat dari workflow anak.<br />**Jalankan ulang:** jalankan ulang hanya job ini setelah menjalankan ulang anak yang gagal hingga hijau. |
| Tahap | Detail |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Resolusi target | **Tugas:** `Resolve target ref`<br />**Workflow anak:** tidak ada<br />**Membuktikan:** me-resolve branch rilis, tag, atau SHA commit lengkap dan mencatat input yang dipilih.<br />**Jalankan ulang:** jalankan ulang payung jika ini gagal. |
| Vitest dan CI normal | **Tugas:** `Run normal full CI`<br />**Workflow anak:** `CI`<br />**Membuktikan:** grafik CI penuh manual terhadap ref target, termasuk lane Linux Node, shard Plugin bawaan, kontrak channel, kompatibilitas Node 22, `check`, `check-additional`, smoke build, pemeriksaan docs, Skills Python, Windows, macOS, i18n Control UI, dan Android melalui payung.<br />**Jalankan ulang:** `rerun_group=ci`. |
| Prarilis Plugin | **Tugas:** `Run plugin prerelease validation`<br />**Workflow anak:** `Plugin Prerelease`<br />**Membuktikan:** pemeriksaan statis Plugin khusus rilis, cakupan Plugin agentik, shard batch ekstensi penuh, dan lane Docker prarilis Plugin.<br />**Jalankan ulang:** `rerun_group=plugin-prerelease`. |
| Pemeriksaan rilis | **Tugas:** `Run release/live/Docker/QA validation`<br />**Workflow anak:** `OpenClaw Release Checks`<br />**Membuktikan:** smoke install, pemeriksaan package lintas OS, Package Acceptance, paritas QA Lab, Matrix live, dan Telegram live. Dengan `run_release_soak=true` atau `release_profile=full`, juga menjalankan suite live/E2E menyeluruh dan chunk jalur rilis Docker.<br />**Jalankan ulang:** `rerun_group=release-checks` atau handle release-checks yang lebih sempit. |
| Artefak package | **Tugas:** `Prepare release package artifact`<br />**Workflow anak:** tidak ada<br />**Membuktikan:** membuat tarball induk `release-package-under-test` cukup awal untuk pemeriksaan yang menghadap package yang tidak perlu menunggu `OpenClaw Release Checks`.<br />**Jalankan ulang:** jalankan ulang payung atau berikan `npm_telegram_package_spec` untuk `rerun_group=npm-telegram`. |
| Package Telegram | **Tugas:** `Run package Telegram E2E`<br />**Workflow anak:** `NPM Telegram Beta E2E`<br />**Membuktikan:** bukti package Telegram berbasis artefak induk untuk `rerun_group=all` dengan `release_profile=full`, atau bukti Telegram package yang dipublikasikan saat `npm_telegram_package_spec` disetel.<br />**Jalankan ulang:** `rerun_group=npm-telegram` dengan `npm_telegram_package_spec`. |
| Verifier payung | **Tugas:** `Verify full validation`<br />**Workflow anak:** tidak ada<br />**Membuktikan:** memeriksa ulang kesimpulan run anak yang dicatat dan menambahkan tabel tugas terlambat dari workflow anak.<br />**Jalankan ulang:** jalankan ulang hanya tugas ini setelah menjalankan ulang anak yang gagal hingga hijau. |
Untuk `ref=main` dan `rerun_group=all`, payung yang lebih baru menggantikan yang lebih lama.
Saat induk dibatalkan, monitornya membatalkan workflow anak apa pun yang sudah
dikirim. Run validasi cabang dan tag rilis tidak saling membatalkan secara
default.
Untuk `ref=main` dan `rerun_group=all`, payung yang lebih baru menggantikan yang lebih lama. Saat induk dibatalkan, monitornya membatalkan workflow anak apa pun yang sudah dikirim. Run validasi branch rilis dan tag tidak saling membatalkan secara default.
## Tahap pemeriksaan rilis
`OpenClaw Release Checks` adalah workflow anak terbesar. Ini me-resolve target
sekali dan menyiapkan artefak `release-package-under-test` bersama saat tahap yang menghadap package
atau Docker membutuhkannya.
`OpenClaw Release Checks` adalah workflow anak terbesar. Ini me-resolve target sekali dan menyiapkan artefak bersama `release-package-under-test` saat tahap yang menghadap package atau Docker membutuhkannya.
| Tahap | Detail |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Target rilis | **Job:** `Resolve target ref`<br />**Workflow pendukung:** tidak ada<br />**Menguji:** ref yang dipilih, SHA yang diharapkan opsional, profil, grup run ulang, dan filter suite live terfokus.<br />**Jalankan ulang:** `rerun_group=release-checks`. |
| Artefak package | **Job:** `Prepare release package artifact`<br />**Workflow pendukung:** tidak ada<br />**Menguji:** mengemas atau me-resolve satu tarball kandidat dan mengunggah `release-package-under-test` untuk pemeriksaan downstream yang menghadap package.<br />**Jalankan ulang:** grup package, lintas OS, atau live/E2E yang terdampak. |
| Smoke instalasi | **Job:** `Run install smoke`<br />**Workflow pendukung:** `Install Smoke`<br />**Menguji:** jalur instalasi penuh dengan penggunaan ulang image smoke Dockerfile root, instalasi package QR, smoke Docker root dan Gateway, pengujian Docker installer, smoke penyedia image instalasi global Bun, dan E2E instalasi/uninstal Plugin terbundel cepat.<br />**Jalankan ulang:** `rerun_group=install-smoke`. |
| Lintas OS | **Job:** `cross_os_release_checks`<br />**Workflow pendukung:** `OpenClaw Cross-OS Release Checks (Reusable)`<br />**Menguji:** lane fresh dan upgrade di Linux, Windows, dan macOS untuk penyedia dan mode yang dipilih, menggunakan tarball kandidat ditambah package baseline.<br />**Jalankan ulang:** `rerun_group=cross-os`. |
| Repo dan live E2E | **Job:** `Run repo/live E2E validation`<br />**Workflow pendukung:** `OpenClaw Live And E2E Checks (Reusable)`<br />**Menguji:** E2E repositori, cache live, streaming websocket OpenAI, penyedia live native dan shard Plugin, serta harness model/backend/Gateway live yang didukung Docker dan dipilih oleh `release_profile`.<br />**Jalankan ulang:** `rerun_group=live-e2e`, opsional dengan `live_suite_filter`. |
| Jalur rilis Docker | **Job:** `Run Docker release-path validation`<br />**Workflow pendukung:** `OpenClaw Live And E2E Checks (Reusable)`<br />**Menguji:** potongan Docker jalur rilis terhadap artefak package bersama.<br />**Jalankan ulang:** `rerun_group=live-e2e`. |
| Package Acceptance | **Job:** `Run package acceptance`<br />**Workflow pendukung:** `Package Acceptance`<br />**Menguji:** fixture package Plugin offline, update Plugin, penerimaan package Telegram mock-OpenAI, dan pemeriksaan penyintas upgrade-terpublikasi dari setiap rilis npm stabil pada atau setelah `2026.4.23` terhadap tarball yang sama.<br />**Jalankan ulang:** `rerun_group=package`. |
| Paritas QA | **Job:** `Run QA Lab parity lane` dan `Run QA Lab parity report`<br />**Workflow pendukung:** job langsung<br />**Menguji:** pack paritas agentik kandidat dan baseline, lalu laporan paritas.<br />**Jalankan ulang:** `rerun_group=qa-parity` atau `rerun_group=qa`. |
| Matrix live QA | **Job:** `Run QA Lab live Matrix lane`<br />**Workflow pendukung:** job langsung<br />**Menguji:** profil QA Matrix live cepat di environment `qa-live-shared`.<br />**Jalankan ulang:** `rerun_group=qa-live` atau `rerun_group=qa`. |
| Telegram live QA | **Job:** `Run QA Lab live Telegram lane`<br />**Workflow pendukung:** job langsung<br />**Menguji:** QA Telegram live dengan sewa kredensial Convex CI.<br />**Jalankan ulang:** `rerun_group=qa-live` atau `rerun_group=qa`. |
| Verifikator rilis | **Job:** `Verify release checks`<br />**Workflow pendukung:** tidak ada<br />**Menguji:** job release-check yang diperlukan untuk grup run ulang yang dipilih.<br />**Jalankan ulang:** jalankan ulang setelah job anak terfokus lulus. |
| Tahap | Detail |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Target rilis | **Pekerjaan:** `Resolve target ref`<br />**Alur kerja pendukung:** tidak ada<br />**Pengujian:** ref yang dipilih, SHA yang diharapkan opsional, profil, grup rerun, dan filter suite live terfokus.<br />**Rerun:** `rerun_group=release-checks`. |
| Artefak paket | **Pekerjaan:** `Prepare release package artifact`<br />**Alur kerja pendukung:** tidak ada<br />**Pengujian:** mengemas atau menyelesaikan satu kandidat tarball dan mengunggah `release-package-under-test` untuk pemeriksaan hilir yang berhadapan dengan paket.<br />**Rerun:** paket yang terdampak, lintas-OS, atau grup live/E2E. |
| Smoke instalasi | **Pekerjaan:** `Run install smoke`<br />**Alur kerja pendukung:** `Install Smoke`<br />**Pengujian:** jalur instalasi penuh dengan penggunaan ulang image smoke Dockerfile root, instalasi paket QR, smoke Docker root dan Gateway, pengujian Docker installer, smoke penyedia image instalasi global Bun, dan E2E instalasi/pencopotan Plugin bundel yang cepat.<br />**Rerun:** `rerun_group=install-smoke`. |
| Lintas-OS | **Pekerjaan:** `cross_os_release_checks`<br />**Alur kerja pendukung:** `OpenClaw Cross-OS Release Checks (Reusable)`<br />**Pengujian:** lane fresh dan upgrade di Linux, Windows, dan macOS untuk penyedia dan mode yang dipilih, menggunakan tarball kandidat plus paket baseline.<br />**Rerun:** `rerun_group=cross-os`. |
| Repo dan live E2E | **Pekerjaan:** `Run repo/live E2E validation`<br />**Alur kerja pendukung:** `OpenClaw Live And E2E Checks (Reusable)`<br />**Pengujian:** E2E repositori, cache live, streaming websocket OpenAI, shard penyedia dan Plugin live native, serta harness model/backend/Gateway live yang didukung Docker yang dipilih oleh `release_profile`.<br />**Berjalan:** `run_release_soak=true`, `release_profile=full`, atau `rerun_group=live-e2e` terfokus.<br />**Rerun:** `rerun_group=live-e2e`, opsional dengan `live_suite_filter`. |
| Jalur rilis Docker | **Pekerjaan:** `Run Docker release-path validation`<br />**Alur kerja pendukung:** `OpenClaw Live And E2E Checks (Reusable)`<br />**Pengujian:** chunk Docker jalur rilis terhadap artefak paket bersama.<br />**Berjalan:** `run_release_soak=true`, `release_profile=full`, atau `rerun_group=live-e2e` terfokus.<br />**Rerun:** `rerun_group=live-e2e`. |
| Penerimaan Paket | **Pekerjaan:** `Run package acceptance`<br />**Alur kerja pendukung:** `Package Acceptance`<br />**Pengujian:** fixture paket Plugin offline, pembaruan Plugin, penerimaan paket Telegram mock-OpenAI, dan pemeriksaan survivor upgrade-terpublikasi terhadap tarball yang sama. Pemeriksaan rilis pemblokir menggunakan baseline terpublikasi terbaru default; pemeriksaan soak diperluas ke setiap rilis npm stabil pada atau setelah `2026.4.23` plus fixture isu yang dilaporkan.<br />**Rerun:** `rerun_group=package`. |
| Paritas QA | **Pekerjaan:** `Run QA Lab parity lane` dan `Run QA Lab parity report`<br />**Alur kerja pendukung:** pekerjaan langsung<br />**Pengujian:** paket paritas agentic kandidat dan baseline, lalu laporan paritas.<br />**Rerun:** `rerun_group=qa-parity` atau `rerun_group=qa`. |
| Matrix live QA | **Pekerjaan:** `Run QA Lab live Matrix lane`<br />**Alur kerja pendukung:** pekerjaan langsung<br />**Pengujian:** profil QA Matrix live cepat di lingkungan `qa-live-shared`.<br />**Rerun:** `rerun_group=qa-live` atau `rerun_group=qa`. |
| Telegram live QA | **Pekerjaan:** `Run QA Lab live Telegram lane`<br />**Alur kerja pendukung:** pekerjaan langsung<br />**Pengujian:** QA Telegram live dengan lease kredensial CI Convex.<br />**Rerun:** `rerun_group=qa-live` atau `rerun_group=qa`. |
| Verifikator rilis | **Pekerjaan:** `Verify release checks`<br />**Alur kerja pendukung:** tidak ada<br />**Pengujian:** pekerjaan pemeriksaan rilis yang diwajibkan untuk grup rerun yang dipilih.<br />**Rerun:** rerun setelah pekerjaan anak terfokus lulus. |
## Potongan jalur rilis Docker
## Chunk jalur rilis Docker
Tahap jalur rilis Docker menjalankan potongan ini saat `live_suite_filter` kosong:
Tahap jalur rilis Docker menjalankan chunk ini saat `live_suite_filter`
kosong:
| Potongan | Cakupan |
| Chunk | Cakupan |
| --------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `core` | Lane smoke jalur rilis Docker inti. |
| `package-update-openai` | Perilaku instalasi dan update package OpenAI. |
| `package-update-anthropic` | Perilaku instalasi dan update package Anthropic. |
| `package-update-core` | Perilaku package dan update yang netral penyedia. |
| `plugins-runtime-plugins` | Lane runtime Plugin yang melatih perilaku Plugin. |
| `core` | Lane smoke jalur rilis Docker core. |
| `package-update-openai` | Perilaku instalasi dan pembaruan paket OpenAI. |
| `package-update-anthropic` | Perilaku instalasi dan pembaruan paket Anthropic. |
| `package-update-core` | Perilaku paket dan pembaruan yang netral penyedia. |
| `plugins-runtime-plugins` | Lane runtime Plugin yang menjalankan perilaku Plugin. |
| `plugins-runtime-services` | Lane runtime Plugin yang didukung layanan; mencakup OpenWebUI saat diminta. |
| `plugins-runtime-install-a` through `plugins-runtime-install-h` | Batch instalasi/runtime Plugin yang dibagi untuk validasi rilis paralel. |
| `plugins-runtime-install-a` hingga `plugins-runtime-install-h` | Batch instalasi/runtime Plugin yang dipisah untuk validasi rilis paralel. |
Gunakan `docker_lanes=<lane[,lane]>` yang ditargetkan pada workflow live/E2E yang dapat digunakan ulang ketika
hanya satu lane Docker yang gagal. Artefak rilis menyertakan perintah rerun
per lane dengan input penggunaan ulang artefak paket dan image jika tersedia.
Gunakan `docker_lanes=<lane[,lane]>` terarah pada alur kerja live/E2E reusable saat
hanya satu lane Docker yang gagal. Artefak rilis menyertakan perintah rerun per-lane
dengan input artefak paket dan penggunaan ulang image saat tersedia.
## Profil rilis
`release_profile` sebagian besar mengontrol cakupan live/provider di dalam pemeriksaan rilis.
Ini tidak menghapus CI penuh normal, Plugin Prerelease, install smoke, package
acceptance, QA Lab, atau bagian jalur rilis Docker. `full` juga membuat
umbrella menjalankan paket Telegram E2E terhadap artefak paket rilis induk ketika
`rerun_group=all`, sehingga kandidat penuh pra-publikasi tidak diam-diam melewati
lane paket Telegram tersebut.
`release_profile` terutama mengontrol keluasan live/penyedia di dalam pemeriksaan rilis.
Ini tidak menghapus CI penuh normal, Prarilis Plugin, smoke instalasi, penerimaan
paket, atau QA Lab. Untuk `stable`, E2E repo/live yang menyeluruh dan chunk
jalur rilis Docker adalah cakupan soak dan berjalan saat `run_release_soak=true`.
`full` memaksa cakupan soak aktif dan juga membuat run payung menjalankan E2E paket
Telegram terhadap artefak paket rilis induk saat `rerun_group=all`, sehingga kandidat
pra-publikasi penuh tidak diam-diam melewati lane paket Telegram tersebut.
| Profil | Penggunaan yang dituju | Cakupan live/provider yang disertakan |
| --------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `minimum` | Smoke paling cepat yang kritis untuk rilis. | Jalur live OpenAI/core, model live Docker untuk OpenAI, inti Gateway native, profil Gateway OpenAI native, Plugin OpenAI native, dan Gateway OpenAI live Docker. |
| `stable` | Profil persetujuan rilis default. | `minimum` ditambah smoke Anthropic, Google, MiniMax, backend, harness pengujian live native, backend CLI live Docker, bind ACP Docker, harness Codex Docker, dan shard smoke OpenCode Go. |
| `full` | Sweep advisory luas. | `stable` ditambah provider advisory, shard live Plugin, dan shard live media. |
| Profil | Penggunaan yang dimaksudkan | Cakupan live/penyedia yang disertakan |
| --------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `minimum` | Smoke kritis-rilis tercepat. | Jalur live OpenAI/core, model live Docker untuk OpenAI, core Gateway native, profil Gateway OpenAI native, Plugin OpenAI native, dan Gateway live Docker OpenAI. |
| `stable` | Profil persetujuan rilis default. | `minimum` plus smoke Anthropic, Google, MiniMax, backend, harness pengujian live native, backend CLI live Docker, bind ACP Docker, harness Codex Docker, dan shard smoke OpenCode Go. |
| `full` | Sweep advisori luas. | `stable` plus penyedia advisori, shard live Plugin, dan shard live media. |
## Tambahan khusus full
Suite ini dilewati oleh `stable` dan disertakan oleh `full`:
| Area | Cakupan khusus full |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Model live Docker | OpenCode Go, OpenRouter, xAI, Z.ai, dan Fireworks. |
| Gateway live Docker | Provider advisory dibagi menjadi shard DeepSeek/Fireworks, OpenCode Go/OpenRouter, dan xAI/Z.ai. |
| Profil provider Gateway native | Shard Anthropic Opus penuh dan Sonnet/Haiku, Fireworks, DeepSeek, shard model OpenCode Go penuh, OpenRouter, xAI, dan Z.ai. |
| Shard live Plugin native | Plugin A-K, L-N, O-Z lainnya, Moonshot, dan xAI. |
| Shard live media native | Audio, musik Google, musik MiniMax, dan grup video A-D. |
| Area | Cakupan khusus full |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Model live Docker | OpenCode Go, OpenRouter, xAI, Z.ai, dan Fireworks. |
| Gateway live Docker | Penyedia advisori dipisah menjadi shard DeepSeek/Fireworks, OpenCode Go/OpenRouter, dan xAI/Z.ai. |
| Profil penyedia Gateway native | Shard Anthropic Opus dan Sonnet/Haiku penuh, Fireworks, DeepSeek, shard model OpenCode Go penuh, OpenRouter, xAI, dan Z.ai. |
| Shard live Plugin native | Plugin A-K, L-N, O-Z lainnya, Moonshot, dan xAI. |
| Shard live media native | Grup audio, Google music, MiniMax music, dan video A-D. |
`stable` menyertakan `native-live-src-gateway-profiles-anthropic-smoke` dan
`native-live-src-gateway-profiles-opencode-go-smoke`; `full` menggunakan shard
@ -130,49 +120,60 @@ handle agregat `native-live-src-gateway-profiles-anthropic` atau
## Rerun terfokus
Gunakan `rerun_group` untuk menghindari pengulangan box rilis yang tidak terkait:
Gunakan `rerun_group` untuk menghindari pengulangan kotak rilis yang tidak terkait:
| Handle | Cakupan |
| ------------------- | --------------------------------------------------------------------- |
| `all` | Semua tahap Full Release Validation. |
| `ci` | Hanya child CI penuh manual. |
| `plugin-prerelease` | Hanya child Plugin Prerelease. |
| `release-checks` | Semua tahap OpenClaw Release Checks. |
| `all` | Semua tahap Validasi Rilis Penuh. |
| `ci` | Hanya turunan CI penuh manual. |
| `plugin-prerelease` | Hanya turunan prarilis Plugin. |
| `release-checks` | Semua tahap Pemeriksaan Rilis OpenClaw. |
| `install-smoke` | Install Smoke melalui pemeriksaan rilis. |
| `cross-os` | Pemeriksaan rilis lintas OS. |
| `live-e2e` | Validasi E2E repo/live dan jalur rilis Docker. |
| `package` | Package Acceptance. |
| `qa` | Paritas QA ditambah lane live QA. |
| `qa-parity` | Hanya lane dan laporan paritas QA. |
| `package` | Penerimaan Paket. |
| `qa` | Paritas QA plus jalur live QA. |
| `qa-parity` | Hanya jalur paritas QA dan laporan. |
| `qa-live` | Hanya Matrix dan Telegram live QA. |
| `npm-telegram` | E2E Telegram paket yang dipublikasikan; memerlukan `npm_telegram_package_spec`. |
Gunakan `live_suite_filter` dengan `rerun_group=live-e2e` ketika satu suite live gagal.
ID filter yang valid didefinisikan dalam workflow live/E2E yang dapat digunakan ulang, termasuk
Gunakan `live_suite_filter` dengan `rerun_group=live-e2e` saat satu suite live gagal.
ID filter yang valid didefinisikan dalam alur kerja live/E2E yang dapat digunakan ulang, termasuk
`docker-live-models`, `live-gateway-docker`,
`live-gateway-anthropic-docker`, `live-gateway-google-docker`,
`live-gateway-minimax-docker`, `live-gateway-advisory-docker`,
`live-cli-backend-docker`, `live-acp-bind-docker`, dan
`live-codex-harness-docker`.
Handle `live-gateway-advisory-docker` adalah handle rerun agregat untuk
tiga shard providernya, sehingga masih menyebar ke semua job Gateway Docker advisory.
Handle `live-gateway-advisory-docker` adalah handle rerun agregat untuk tiga
shard providernya, jadi handle ini tetap menyebar ke semua pekerjaan Gateway Docker advisory.
Gunakan `cross_os_suite_filter` dengan `rerun_group=cross-os` saat satu jalur lintas OS
gagal. Filter menerima ID OS, ID suite, atau pasangan OS/suite, misalnya
`windows/packaged-upgrade`, `windows`, atau `packaged-fresh`. Ringkasan lintas OS
mencakup waktu per fase untuk jalur peningkatan terpaket, dan perintah yang berjalan lama
mencetak baris Heartbeat sehingga pembaruan Windows yang macet terlihat sebelum
batas waktu pekerjaan.
Jalur pemeriksaan rilis QA bersifat advisory. Kegagalan yang hanya terjadi pada QA dilaporkan sebagai peringatan
dan tidak memblokir pemverifikasi pemeriksaan rilis; jalankan ulang `rerun_group=qa`,
`qa-parity`, atau `qa-live` saat Anda memerlukan bukti QA yang baru.
## Bukti yang perlu disimpan
Simpan ringkasan `Full Release Validation` sebagai indeks tingkat rilis. Ringkasan itu menautkan
ID run child dan menyertakan tabel job paling lambat. Untuk kegagalan, periksa workflow child
terlebih dahulu, lalu rerun handle terkecil yang cocok di atas.
Simpan ringkasan `Full Release Validation` sebagai indeks tingkat rilis. Ringkasan ini menautkan
ID run turunan dan menyertakan tabel pekerjaan paling lambat. Untuk kegagalan, periksa alur kerja
turunan terlebih dahulu, lalu jalankan ulang handle terkecil yang cocok di atas.
Artefak berguna:
Artefak yang berguna:
- `release-package-under-test` dari parent Full Release Validation dan `OpenClaw Release Checks`
- `release-package-under-test` dari induk Validasi Rilis Penuh dan `OpenClaw Release Checks`
- Artefak jalur rilis Docker di bawah `.artifacts/docker-tests/`
- Package Acceptance `package-under-test` dan artefak acceptance Docker
- Artefak Penerimaan Paket `package-under-test` dan penerimaan Docker
- Artefak pemeriksaan rilis lintas OS untuk setiap OS dan suite
- Artefak paritas QA, Matrix, dan Telegram
## File workflow
## File alur kerja
- `.github/workflows/full-release-validation.yml`
- `.github/workflows/openclaw-release-checks.yml`

100
docs/id/reference/test.md
View File

@ -4,60 +4,60 @@ read_when:
summary: Cara menjalankan pengujian secara lokal (vitest) dan kapan menggunakan mode force/coverage
title: Pengujian
x-i18n:
generated_at: "2026-05-02T21:00:14Z"
generated_at: "2026-05-05T01:48:58Z"
model: gpt-5.5
provider: openai
source_hash: 8a88599d079e1ca42d73d354b582d67dd85be40fc92eed5abe6dcef37dc21f4f
source_hash: 7e8421518d63cade24ce8c2a08fa10538b66d2332b1eb5744e47c6d5a5e84605
source_path: reference/test.md
workflow: 16
---
- Perangkat pengujian lengkap (suite, live, Docker): [Pengujian](/id/help/testing)
- Validasi pembaruan dan paket Plugin: [Menguji pembaruan dan Plugin](/id/help/testing-updates-plugins)
- Paket pengujian lengkap (suite, langsung, Docker): [Pengujian](/id/help/testing)
- Validasi pembaruan dan paket Plugin: [Pengujian pembaruan dan Plugin](/id/help/testing-updates-plugins)
- `pnpm test:force`: Menghentikan proses gateway tersisa yang menahan port kontrol default, lalu menjalankan suite Vitest penuh dengan port gateway terisolasi agar pengujian server tidak bertabrakan dengan instance yang sedang berjalan. Gunakan ini saat proses gateway sebelumnya membuat port 18789 tetap terpakai.
- `pnpm test:coverage`: Menjalankan suite unit dengan cakupan V8 (melalui `vitest.unit.config.ts`). Ini adalah gerbang cakupan unit untuk berkas yang dimuat, bukan cakupan seluruh berkas di seluruh repo. Ambangnya adalah 70% untuk baris/fungsi/pernyataan dan 55% untuk cabang. Karena `coverage.all` bernilai false, gerbang ini mengukur berkas yang dimuat oleh suite cakupan unit, bukan menganggap setiap berkas sumber split-lane sebagai tidak tercakup.
- `pnpm test:coverage:changed`: Menjalankan cakupan unit hanya untuk berkas yang berubah sejak `origin/main`.
- `pnpm test:changed`: eksekusi pengujian perubahan cerdas yang murah. Ini menjalankan target presisi dari edit pengujian langsung, berkas saudara `*.test.ts`, pemetaan sumber eksplisit, dan grafik impor lokal. Perubahan luas/config/package dilewati kecuali perubahan itu memetakan ke pengujian presisi.
- `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`: eksekusi pengujian perubahan luas yang eksplisit. Gunakan ini saat edit harness/config/package pengujian perlu jatuh balik ke perilaku changed-test Vitest yang lebih luas.
- `pnpm test:force`: Menghentikan proses gateway tersisa yang menahan port kontrol default, lalu menjalankan seluruh suite Vitest dengan port gateway terisolasi agar pengujian server tidak bertabrakan dengan instance yang sedang berjalan. Gunakan ini ketika eksekusi gateway sebelumnya meninggalkan port 18789 dalam keadaan terpakai.
- `pnpm test:coverage`: Menjalankan suite unit dengan cakupan V8 (melalui `vitest.unit.config.ts`). Ini adalah gate cakupan unit file yang dimuat, bukan cakupan semua file seluruh repo. Ambangnya adalah 70% untuk baris/fungsi/pernyataan dan 55% untuk cabang. Karena `coverage.all` bernilai false, gate ini mengukur file yang dimuat oleh suite cakupan unit, alih-alih memperlakukan setiap file sumber split-lane sebagai tidak tercakup.
- `pnpm test:coverage:changed`: Menjalankan cakupan unit hanya untuk file yang berubah sejak `origin/main`.
- `pnpm test:changed`: eksekusi pengujian perubahan cerdas yang murah. Ini menjalankan target presisi dari edit pengujian langsung, file sibling `*.test.ts`, pemetaan sumber eksplisit, dan grafik impor lokal. Perubahan luas/config/package dilewati kecuali dipetakan ke pengujian presisi.
- `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`: eksekusi pengujian perubahan luas eksplisit. Gunakan ini ketika edit test harness/config/package seharusnya fallback ke perilaku changed-test Vitest yang lebih luas.
- `pnpm changed:lanes`: menampilkan lane arsitektural yang dipicu oleh diff terhadap `origin/main`.
- `pnpm check:changed`: menjalankan gerbang pemeriksaan perubahan cerdas untuk diff terhadap `origin/main`. Ini menjalankan typecheck, lint, dan perintah guard untuk lane arsitektural yang terdampak, tetapi tidak menjalankan pengujian Vitest. Gunakan `pnpm test:changed` atau `pnpm test <target>` eksplisit untuk bukti pengujian.
- `pnpm test`: merutekan target berkas/direktori eksplisit melalui lane Vitest berskup. Eksekusi tanpa target memakai grup shard tetap dan diperluas ke config leaf untuk eksekusi paralel lokal; grup ekstensi selalu diperluas ke config shard per ekstensi, bukan satu proses root-project besar.
- Eksekusi pembungkus pengujian berakhir dengan ringkasan singkat `[test] passed|failed|skipped ... in ...`. Baris durasi milik Vitest tetap menjadi detail per shard.
- Status pengujian OpenClaw bersama: gunakan `src/test-utils/openclaw-test-state.ts` dari Vitest saat pengujian memerlukan `HOME`, `OPENCLAW_STATE_DIR`, `OPENCLAW_CONFIG_PATH`, fixture config, workspace, direktori agen, atau penyimpanan auth-profile yang terisolasi.
- Helper E2E proses: gunakan `test/helpers/openclaw-test-instance.ts` saat pengujian E2E level proses Vitest memerlukan Gateway yang berjalan, env CLI, penangkapan log, dan pembersihan di satu tempat.
- Helper E2E Docker/Bash: lane yang melakukan source `scripts/lib/docker-e2e-image.sh` dapat meneruskan `docker_e2e_test_state_shell_b64 <label> <scenario>` ke dalam container dan mendekodenya dengan `scripts/lib/openclaw-e2e-instance.sh`; skrip multi-home dapat meneruskan `docker_e2e_test_state_function_b64` dan memanggil `openclaw_test_state_create <label> <scenario>` di setiap alur. Pemanggil tingkat lebih rendah dapat menggunakan `scripts/lib/openclaw-test-state.mjs shell --label <name> --scenario <name>` untuk snippet shell dalam container, atau `node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json` untuk berkas env host yang dapat di-source. `--` sebelum `create` mencegah runtime Node yang lebih baru memperlakukan `--env-file` sebagai flag Node. Lane Docker/Bash yang meluncurkan Gateway dapat melakukan source `scripts/lib/openclaw-e2e-instance.sh` di dalam container untuk resolusi entrypoint, startup OpenAI tiruan, peluncuran Gateway foreground/background, probe kesiapan, ekspor env status, dump log, dan pembersihan proses.
- Eksekusi shard penuh, ekstensi, dan include-pattern memperbarui data timing lokal di `.artifacts/vitest-shard-timings.json`; eksekusi whole-config berikutnya memakai timing tersebut untuk menyeimbangkan shard lambat dan cepat. Shard CI include-pattern menambahkan nama shard ke kunci timing, sehingga timing shard terfilter tetap terlihat tanpa mengganti data timing whole-config. Setel `OPENCLAW_TEST_PROJECTS_TIMINGS=0` untuk mengabaikan artefak timing lokal.
- Berkas pengujian `plugin-sdk` dan `commands` terpilih kini dirutekan melalui lane ringan khusus yang hanya mempertahankan `test/setup.ts`, sementara kasus berat-runtime tetap berada di lane yang sudah ada.
- Berkas sumber dengan pengujian saudara dipetakan ke saudara tersebut sebelum jatuh balik ke glob direktori yang lebih luas. Edit helper di bawah `src/channels/plugins/contracts/test-helpers`, `src/plugin-sdk/test-helpers`, dan `src/plugins/contracts` memakai grafik impor lokal untuk menjalankan pengujian yang mengimpor, bukan menjalankan luas setiap shard ketika jalur dependensi presisi.
- `auto-reply` kini juga dibagi menjadi tiga config khusus (`core`, `top-level`, `reply`) sehingga harness reply tidak mendominasi pengujian status/token/helper top-level yang lebih ringan.
- Config dasar Vitest kini default ke `pool: "threads"` dan `isolate: false`, dengan runner non-terisolasi bersama diaktifkan di seluruh config repo.
- `pnpm check:changed`: menjalankan gate pemeriksaan perubahan cerdas untuk diff terhadap `origin/main`. Ini menjalankan typecheck, lint, dan perintah guard untuk lane arsitektural yang terdampak, tetapi tidak menjalankan pengujian Vitest. Gunakan `pnpm test:changed` atau `pnpm test <target>` eksplisit untuk bukti pengujian.
- `pnpm test`: merutekan target file/direktori eksplisit melalui lane Vitest yang terskop. Eksekusi tanpa target menggunakan grup shard tetap dan diperluas ke konfigurasi leaf untuk eksekusi paralel lokal; grup plugin selalu diperluas ke konfigurasi shard per-plugin, bukan satu proses root-project raksasa.
- Eksekusi wrapper pengujian berakhir dengan ringkasan singkat `[test] passed|failed|skipped ... in ...`. Baris durasi milik Vitest sendiri tetap menjadi detail per-shard.
- State pengujian OpenClaw bersama: gunakan `src/test-utils/openclaw-test-state.ts` dari Vitest ketika suatu pengujian memerlukan `HOME`, `OPENCLAW_STATE_DIR`, `OPENCLAW_CONFIG_PATH`, fixture config, workspace, direktori agent, atau penyimpanan auth-profile yang terisolasi.
- Helper E2E proses: gunakan `test/helpers/openclaw-test-instance.ts` ketika pengujian E2E level proses Vitest memerlukan Gateway yang berjalan, env CLI, penangkapan log, dan cleanup dalam satu tempat.
- Helper E2E Docker/Bash: lane yang melakukan source `scripts/lib/docker-e2e-image.sh` dapat meneruskan `docker_e2e_test_state_shell_b64 <label> <scenario>` ke dalam container dan mendekodenya dengan `scripts/lib/openclaw-e2e-instance.sh`; skrip multi-home dapat meneruskan `docker_e2e_test_state_function_b64` dan memanggil `openclaw_test_state_create <label> <scenario>` di setiap flow. Pemanggil level lebih rendah dapat menggunakan `scripts/lib/openclaw-test-state.mjs shell --label <name> --scenario <name>` untuk snippet shell di dalam container, atau `node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json` untuk file env host yang dapat di-source. `--` sebelum `create` mencegah runtime Node yang lebih baru memperlakukan `--env-file` sebagai flag Node. Lane Docker/Bash yang meluncurkan Gateway dapat melakukan source `scripts/lib/openclaw-e2e-instance.sh` di dalam container untuk resolusi entrypoint, startup mock OpenAI, peluncuran Gateway foreground/background, readiness probe, ekspor env state, dump log, dan cleanup proses.
- Eksekusi shard penuh, plugin, dan include-pattern memperbarui data timing lokal di `.artifacts/vitest-shard-timings.json`; eksekusi whole-config berikutnya menggunakan timing tersebut untuk menyeimbangkan shard lambat dan cepat. Shard CI include-pattern menambahkan nama shard ke kunci timing, sehingga timing shard yang difilter tetap terlihat tanpa menggantikan data timing whole-config. Set `OPENCLAW_TEST_PROJECTS_TIMINGS=0` untuk mengabaikan artefak timing lokal.
- File pengujian `plugin-sdk` dan `commands` terpilih sekarang dirutekan melalui lane ringan khusus yang hanya mempertahankan `test/setup.ts`, sementara kasus yang berat runtime tetap berada di lane yang sudah ada.
- File sumber dengan pengujian sibling dipetakan ke sibling tersebut sebelum fallback ke glob direktori yang lebih luas. Edit helper di bawah `src/channels/plugins/contracts/test-helpers`, `src/plugin-sdk/test-helpers`, dan `src/plugins/contracts` menggunakan grafik impor lokal untuk menjalankan pengujian yang mengimpor, bukan menjalankan luas setiap shard ketika path dependensi presisi.
- `auto-reply` sekarang juga dipecah menjadi tiga konfigurasi khusus (`core`, `top-level`, `reply`) sehingga harness reply tidak mendominasi pengujian status/token/helper top-level yang lebih ringan.
- Config dasar Vitest sekarang default ke `pool: "threads"` dan `isolate: false`, dengan runner non-terisolasi bersama diaktifkan di seluruh config repo.
- `pnpm test:channels` menjalankan `vitest.channels.config.ts`.
- `pnpm test:extensions` dan `pnpm test extensions` menjalankan semua shard ekstensi/plugin. Plugin kanal berat, Plugin browser, dan OpenAI berjalan sebagai shard khusus; grup Plugin lain tetap dibatch. Gunakan `pnpm test extensions/<id>` untuk satu lane Plugin bundel.
- `pnpm test:perf:imports`: mengaktifkan pelaporan durasi impor + rincian impor Vitest, sambil tetap memakai routing lane berskup untuk target berkas/direktori eksplisit.
- `pnpm test:perf:imports:changed`: profiling impor yang sama, tetapi hanya untuk berkas yang berubah sejak `origin/main`.
- `pnpm test:perf:changed:bench -- --ref <git-ref>` membenchmark jalur changed-mode yang dirutekan terhadap eksekusi root-project native untuk diff git committed yang sama.
- `pnpm test:extensions` dan `pnpm test extensions` menjalankan semua shard plugin. Plugin channel berat, Plugin browser, dan OpenAI berjalan sebagai shard khusus; grup Plugin lainnya tetap dibatch. Gunakan `pnpm test extensions/<id>` untuk satu lane Plugin bawaan.
- `pnpm test:perf:imports`: mengaktifkan pelaporan durasi impor + rincian impor Vitest, sambil tetap menggunakan perutean lane terskop untuk target file/direktori eksplisit.
- `pnpm test:perf:imports:changed`: profiling impor yang sama, tetapi hanya untuk file yang berubah sejak `origin/main`.
- `pnpm test:perf:changed:bench -- --ref <git-ref>` membenchmark path changed-mode yang dirutekan terhadap eksekusi root-project native untuk diff git committed yang sama.
- `pnpm test:perf:changed:bench -- --worktree` membenchmark set perubahan worktree saat ini tanpa perlu commit terlebih dahulu.
- `pnpm test:perf:profile:main`: menulis profil CPU untuk thread utama Vitest (`.artifacts/vitest-main-profile`).
- `pnpm test:perf:profile:runner`: menulis profil CPU + heap untuk runner unit (`.artifacts/vitest-runner-profile`).
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: menjalankan setiap config leaf Vitest full-suite secara serial dan menulis data durasi terkelompok plus artefak JSON/log per config. Test Performance Agent memakai ini sebagai baseline sebelum mencoba perbaikan pengujian lambat.
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: menjalankan setiap config leaf Vitest full-suite secara serial dan menulis data durasi terkelompok plus artefak JSON/log per-config. Test Performance Agent menggunakan ini sebagai baseline sebelum mencoba perbaikan pengujian lambat.
- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`: membandingkan laporan terkelompok setelah perubahan yang berfokus pada performa.
- Integrasi Gateway: ikut serta melalui `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` atau `pnpm test:gateway`.
- `pnpm test:e2e`: Menjalankan smoke test end-to-end gateway (pairing multi-instance WS/HTTP/node). Default ke `threads` + `isolate: false` dengan worker adaptif di `vitest.e2e.config.ts`; sesuaikan dengan `OPENCLAW_E2E_WORKERS=<n>` dan setel `OPENCLAW_E2E_VERBOSE=1` untuk log verbose.
- `pnpm test:live`: Menjalankan pengujian live provider (minimax/zai). Memerlukan kunci API dan `LIVE=1` (atau `*_LIVE_TEST=1` khusus provider) agar tidak dilewati.
- `pnpm test:docker:all`: Membangun image live-test bersama, mengemas OpenClaw sekali sebagai tarball npm, membangun/memakai ulang image runner Node/Git kosong plus image fungsional yang memasang tarball itu ke `/app`, lalu menjalankan lane smoke Docker dengan `OPENCLAW_SKIP_DOCKER_BUILD=1` melalui scheduler berbobot. Image kosong (`OPENCLAW_DOCKER_E2E_BARE_IMAGE`) dipakai untuk lane installer/update/plugin-dependency; lane tersebut memasang tarball prabangun, bukan memakai sumber repo yang disalin. Image fungsional (`OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`) dipakai untuk lane fungsionalitas built-app normal. `scripts/package-openclaw-for-docker.mjs` adalah satu-satunya packer package lokal/CI dan memvalidasi tarball plus `dist/postinstall-inventory.json` sebelum Docker mengonsumsinya. Definisi lane Docker berada di `scripts/lib/docker-e2e-scenarios.mjs`; logika planner berada di `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` mengeksekusi rencana terpilih. `node scripts/test-docker-all.mjs --plan-json` memancarkan rencana CI milik scheduler untuk lane terpilih, jenis image, kebutuhan package/live-image, skenario status, dan pemeriksaan kredensial tanpa membangun atau menjalankan Docker. `OPENCLAW_DOCKER_ALL_PARALLELISM=<n>` mengontrol slot proses dan default ke 10; `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n>` mengontrol pool tail sensitif-provider dan default ke 10. Batas lane berat default ke `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10`, dan `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; batas provider default ke satu lane berat per provider melalui `OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4`, `OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4`, dan `OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4`. Gunakan `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` atau `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` untuk host yang lebih besar. Jika satu lane melebihi batas bobot atau sumber daya efektif pada host dengan paralelisme rendah, lane itu masih dapat dimulai dari pool kosong dan akan berjalan sendiri sampai melepaskan kapasitas. Mulai lane dijeda 2 detik secara default untuk menghindari lonjakan create daemon Docker lokal; timpa dengan `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=<ms>`. Runner melakukan preflight Docker secara default, membersihkan container E2E OpenClaw yang usang, memancarkan status active-lane setiap 30 detik, berbagi cache tool CLI provider antar lane yang kompatibel, mencoba ulang kegagalan live-provider sementara satu kali secara default (`OPENCLAW_DOCKER_ALL_LIVE_RETRIES=<n>`), dan menyimpan timing lane di `.artifacts/docker-tests/lane-timings.json` untuk pengurutan paling lama terlebih dahulu pada eksekusi berikutnya. Gunakan `OPENCLAW_DOCKER_ALL_DRY_RUN=1` untuk mencetak manifes lane tanpa menjalankan Docker, `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=<ms>` untuk menyesuaikan output status, atau `OPENCLAW_DOCKER_ALL_TIMINGS=0` untuk menonaktifkan penggunaan ulang timing. Gunakan `OPENCLAW_DOCKER_ALL_LIVE_MODE=skip` hanya untuk lane deterministik/lokal atau `OPENCLAW_DOCKER_ALL_LIVE_MODE=only` hanya untuk lane live-provider; alias package adalah `pnpm test:docker:local:all` dan `pnpm test:docker:live:all`. Mode live-only menggabungkan lane live utama dan tail menjadi satu pool paling lama terlebih dahulu sehingga bucket provider dapat memadatkan pekerjaan Claude, Codex, dan Gemini bersama-sama. Runner berhenti menjadwalkan lane pooled baru setelah kegagalan pertama kecuali `OPENCLAW_DOCKER_ALL_FAIL_FAST=0` disetel, dan setiap lane memiliki timeout fallback 120 menit yang dapat ditimpa dengan `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`; lane live/tail terpilih memakai batas per-lane yang lebih ketat. Perintah setup Docker backend CLI memiliki timeout sendiri melalui `OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS` (default 180). Log per lane, `summary.json`, `failures.json`, dan timing fase ditulis di bawah `.artifacts/docker-tests/<run-id>/`; gunakan `pnpm test:docker:timings <summary.json>` untuk memeriksa lane lambat dan `pnpm test:docker:rerun <run-id|summary.json|failures.json>` untuk mencetak perintah rerun tertarget yang murah.
- `pnpm test:docker:browser-cdp-snapshot`: Membangun container E2E sumber berbasis Chromium, memulai CDP mentah plus Gateway terisolasi, menjalankan `browser doctor --deep`, dan memverifikasi snapshot peran CDP menyertakan URL tautan, clickable yang dipromosikan kursor, ref iframe, dan metadata frame.
- Probe Docker live backend CLI dapat dijalankan sebagai lane terfokus, misalnya `pnpm test:docker:live-cli-backend:codex`, `pnpm test:docker:live-cli-backend:codex:resume`, atau `pnpm test:docker:live-cli-backend:codex:mcp`. Claude dan Gemini memiliki alias `:resume` dan `:mcp` yang sesuai.
- `pnpm test:docker:openwebui`: Memulai OpenClaw + Open WebUI dalam Docker, masuk melalui Open WebUI, memeriksa `/api/models`, lalu menjalankan chat terproksi nyata melalui `/api/chat/completions`. Memerlukan kunci model live yang dapat digunakan (misalnya OpenAI di `~/.profile`), menarik image Open WebUI eksternal, dan tidak diharapkan stabil untuk CI seperti suite unit/e2e normal.
- `pnpm test:docker:mcp-channels`: Memulai container Gateway berseed dan container klien kedua yang menjalankan `openclaw mcp serve`, lalu memverifikasi penemuan percakapan yang dirutekan, pembacaan transkrip, metadata lampiran, perilaku antrean event live, routing kirim outbound, serta notifikasi kanal + izin bergaya Claude melalui bridge stdio nyata. Assertion notifikasi Claude membaca frame MCP stdio mentah secara langsung sehingga smoke mencerminkan apa yang benar-benar dipancarkan bridge.
- `pnpm test:docker:upgrade-survivor`: Menginstal tarball OpenClaw yang sudah dipaketkan di atas fixture pengguna lama yang kotor, menjalankan pembaruan paket plus `doctor` non-interaktif tanpa kunci penyedia atau kanal live, lalu memulai Gateway loopback dan memeriksa bahwa agen, konfigurasi kanal, daftar izin Plugin, file workspace/sesi, status dependensi Plugin lama yang usang, startup, dan status RPC tetap bertahan.
- `pnpm test:docker:published-upgrade-survivor`: Menginstal `openclaw@latest` secara default, melakukan seed file pengguna yang sudah ada secara realistis tanpa kunci penyedia atau kanal live, mengonfigurasi baseline tersebut dengan resep perintah `openclaw config set` bawaan, memperbarui instalasi terbitan tersebut ke tarball OpenClaw yang sudah dipaketkan, menjalankan `doctor` non-interaktif, menulis `.artifacts/upgrade-survivor/summary.json`, lalu memulai Gateway loopback dan memeriksa bahwa intent yang dikonfigurasi, file workspace/sesi, konfigurasi Plugin usang dan status dependensi lama, startup, `/healthz`, `/readyz`, dan status RPC tetap bertahan atau diperbaiki dengan bersih. Timpa satu baseline dengan `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, perluas matriks persis dengan `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` seperti `all-since-2026.4.23`, atau tambahkan fixture skenario dengan `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues`; set reported-issues mencakup `configured-plugin-installs` untuk memverifikasi bahwa Plugin OpenClaw eksternal yang dikonfigurasi terinstal secara otomatis selama pemutakhiran. Package Acceptance mengeksposnya sebagai `published_upgrade_survivor_baseline`, `published_upgrade_survivor_baselines`, dan `published_upgrade_survivor_scenarios`.
- `pnpm test:docker:update-migration`: Menjalankan harness published-upgrade survivor dalam skenario `plugin-deps-cleanup` yang berat pembersihan, dimulai dari `openclaw@2026.4.23` secara default. Workflow `Update Migration` terpisah memperluas lane ini dengan `baselines=all-since-2026.4.23` sehingga setiap paket stabil yang sudah diterbitkan dari `.23` dan seterusnya diperbarui ke kandidat dan membuktikan pembersihan dependensi Plugin yang dikonfigurasi di luar Full Release CI.
- `pnpm test:docker:plugins`: Menjalankan smoke instal/pembaruan untuk path lokal, paket registry npm `file:` dengan dependensi yang di-hoist, ref git yang bergerak, fixture ClawHub, pembaruan marketplace, serta enable/inspect bundle Claude.
- `pnpm test:e2e`: Menjalankan pengujian smoke end-to-end gateway (pairing multi-instance WS/HTTP/node). Default ke `threads` + `isolate: false` dengan worker adaptif di `vitest.e2e.config.ts`; sesuaikan dengan `OPENCLAW_E2E_WORKERS=<n>` dan set `OPENCLAW_E2E_VERBOSE=1` untuk log verbose.
- `pnpm test:live`: Menjalankan pengujian live provider (minimax/zai). Memerlukan API key dan `LIVE=1` (atau `*_LIVE_TEST=1` khusus provider) agar tidak diskip.
- `pnpm test:docker:all`: Membangun image live-test bersama, mengemas OpenClaw sekali sebagai tarball npm, membangun/menggunakan ulang image runner Node/Git bare plus image fungsional yang menginstal tarball tersebut ke `/app`, lalu menjalankan lane smoke Docker dengan `OPENCLAW_SKIP_DOCKER_BUILD=1` melalui scheduler berbobot. Image bare (`OPENCLAW_DOCKER_E2E_BARE_IMAGE`) digunakan untuk lane installer/update/plugin-dependency; lane tersebut me-mount tarball yang sudah dibangun, bukan menggunakan sumber repo yang disalin. Image fungsional (`OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`) digunakan untuk lane fungsionalitas built-app normal. `scripts/package-openclaw-for-docker.mjs` adalah satu-satunya packer package lokal/CI dan memvalidasi tarball plus `dist/postinstall-inventory.json` sebelum Docker mengonsumsinya. Definisi lane Docker berada di `scripts/lib/docker-e2e-scenarios.mjs`; logika planner berada di `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` mengeksekusi plan yang dipilih. `node scripts/test-docker-all.mjs --plan-json` mengeluarkan plan CI milik scheduler untuk lane terpilih, jenis image, kebutuhan package/live-image, skenario state, dan pemeriksaan kredensial tanpa membangun atau menjalankan Docker. `OPENCLAW_DOCKER_ALL_PARALLELISM=<n>` mengontrol slot proses dan default ke 10; `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n>` mengontrol pool tail yang sensitif provider dan default ke 10. Cap lane berat default ke `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10`, dan `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; cap provider default ke satu lane berat per provider melalui `OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4`, `OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4`, dan `OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4`. Gunakan `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` atau `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` untuk host yang lebih besar. Jika satu lane melampaui bobot efektif atau cap resource pada host dengan paralelisme rendah, lane tersebut masih dapat mulai dari pool kosong dan akan berjalan sendiri hingga melepas kapasitas. Start lane diberi jeda 2 detik secara default untuk menghindari lonjakan create daemon Docker lokal; override dengan `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=<ms>`. Runner melakukan preflight Docker secara default, membersihkan container E2E OpenClaw yang stale, mengeluarkan status active-lane setiap 30 detik, berbagi cache tool CLI provider antara lane yang kompatibel, mencoba ulang kegagalan live-provider sementara sekali secara default (`OPENCLAW_DOCKER_ALL_LIVE_RETRIES=<n>`), dan menyimpan timing lane di `.artifacts/docker-tests/lane-timings.json` untuk pengurutan longest-first pada eksekusi berikutnya. Gunakan `OPENCLAW_DOCKER_ALL_DRY_RUN=1` untuk mencetak manifest lane tanpa menjalankan Docker, `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=<ms>` untuk menyesuaikan output status, atau `OPENCLAW_DOCKER_ALL_TIMINGS=0` untuk menonaktifkan penggunaan ulang timing. Gunakan `OPENCLAW_DOCKER_ALL_LIVE_MODE=skip` hanya untuk lane deterministik/lokal atau `OPENCLAW_DOCKER_ALL_LIVE_MODE=only` hanya untuk lane live-provider; alias package adalah `pnpm test:docker:local:all` dan `pnpm test:docker:live:all`. Mode live-only menggabungkan lane live main dan tail ke dalam satu pool longest-first sehingga bucket provider dapat mengemas pekerjaan Claude, Codex, dan Gemini bersama-sama. Runner berhenti menjadwalkan lane pooled baru setelah kegagalan pertama kecuali `OPENCLAW_DOCKER_ALL_FAIL_FAST=0` diset, dan setiap lane memiliki timeout fallback 120 menit yang dapat dioverride dengan `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`; lane live/tail terpilih menggunakan cap per-lane yang lebih ketat. Perintah setup Docker backend CLI memiliki timeout sendiri melalui `OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS` (default 180). Log per-lane, `summary.json`, `failures.json`, dan timing fase ditulis di bawah `.artifacts/docker-tests/<run-id>/`; gunakan `pnpm test:docker:timings <summary.json>` untuk memeriksa lane lambat dan `pnpm test:docker:rerun <run-id|summary.json|failures.json>` untuk mencetak perintah rerun tertarget yang murah.
- `pnpm test:docker:browser-cdp-snapshot`: Membangun container E2E sumber berbasis Chromium, memulai CDP mentah plus Gateway terisolasi, menjalankan `browser doctor --deep`, dan memverifikasi snapshot peran CDP mencakup URL tautan, clickable yang dipromosikan kursor, ref iframe, dan metadata frame.
- Probe Docker live backend CLI dapat dijalankan sebagai lane terfokus, misalnya `pnpm test:docker:live-cli-backend:codex`, `pnpm test:docker:live-cli-backend:codex:resume`, atau `pnpm test:docker:live-cli-backend:codex:mcp`. Claude dan Gemini memiliki alias `:resume` dan `:mcp` yang cocok.
- `pnpm test:docker:openwebui`: Memulai OpenClaw + Open WebUI dalam Docker, masuk melalui Open WebUI, memeriksa `/api/models`, lalu menjalankan chat proxied nyata melalui `/api/chat/completions`. Memerlukan key model live yang dapat digunakan (misalnya OpenAI di `~/.profile`), menarik image Open WebUI eksternal, dan tidak diharapkan stabil di CI seperti suite unit/e2e normal.
- `pnpm test:docker:mcp-channels`: Memulai container Gateway seeded dan container klien kedua yang men-spawn `openclaw mcp serve`, lalu memverifikasi discovery percakapan terute, pembacaan transkrip, metadata lampiran, perilaku antrean event live, perutean kirim keluar, dan notifikasi channel + izin bergaya Claude melalui bridge stdio nyata. Assertion notifikasi Claude membaca frame MCP stdio mentah secara langsung sehingga smoke mencerminkan apa yang benar-benar dipancarkan bridge.
- `pnpm test:docker:upgrade-survivor`: Menginstal tarball OpenClaw yang sudah dipaketkan di atas fixture pengguna lama yang kotor, menjalankan pembaruan paket plus doctor noninteraktif tanpa kunci penyedia atau channel live, lalu memulai Gateway loopback dan memeriksa bahwa agen, konfigurasi channel, allowlist plugin, file workspace/sesi, status dependensi plugin legacy usang, startup, dan status RPC tetap bertahan.
- `pnpm test:docker:published-upgrade-survivor`: Menginstal `openclaw@latest` secara default, menanamkan file pengguna yang sudah ada secara realistis tanpa kunci penyedia atau channel live, mengonfigurasi baseline tersebut dengan resep perintah `openclaw config set` bawaan, memperbarui instalasi terpublikasi itu ke tarball OpenClaw yang sudah dipaketkan, menjalankan doctor noninteraktif, menulis `.artifacts/upgrade-survivor/summary.json`, lalu memulai Gateway loopback dan memeriksa bahwa intent yang dikonfigurasi, file workspace/sesi, konfigurasi plugin usang dan status dependensi legacy, startup, `/healthz`, `/readyz`, dan status RPC tetap bertahan atau diperbaiki dengan bersih. Timpa satu baseline dengan `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, perluas matriks persis dengan `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` seperti `all-since-2026.4.23`, atau tambahkan fixture skenario dengan `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues`; set reported-issues mencakup `configured-plugin-installs` untuk memverifikasi bahwa plugin OpenClaw eksternal yang dikonfigurasi diinstal otomatis selama upgrade dan `stale-source-plugin-shadow` untuk menjaga agar bayangan plugin khusus sumber tidak merusak startup. Package Acceptance mengeksposnya sebagai `published_upgrade_survivor_baseline`, `published_upgrade_survivor_baselines`, dan `published_upgrade_survivor_scenarios`.
- `pnpm test:docker:update-migration`: Menjalankan harness survivor upgrade terpublikasi dalam skenario `plugin-deps-cleanup` yang berat pembersihan, dimulai dari `openclaw@2026.4.23` secara default. Workflow `Update Migration` terpisah memperluas lane ini dengan `baselines=all-since-2026.4.23` sehingga setiap paket terpublikasi stabil sejak `.23` dan seterusnya diperbarui ke kandidat dan membuktikan pembersihan dependensi configured-plugin di luar CI Rilis Lengkap.
- `pnpm test:docker:plugins`: Menjalankan smoke instal/update untuk path lokal, `file:`, paket registry npm dengan dependensi yang di-hoist, ref git bergerak, fixture ClawHub, pembaruan marketplace, dan enable/inspect Claude-bundle.
## Gerbang PR lokal
## Gate PR lokal
Untuk pemeriksaan pendaratan/gerbang PR lokal, jalankan:
Untuk pemeriksaan land/gate PR lokal, jalankan:
- `pnpm check:changed`
- `pnpm check`
@ -66,7 +66,7 @@ Untuk pemeriksaan pendaratan/gerbang PR lokal, jalankan:
- `pnpm test`
- `pnpm check:docs`
Jika `pnpm test` mengalami kegagalan tidak stabil pada host berbeban tinggi, jalankan ulang sekali sebelum memperlakukannya sebagai regresi, lalu isolasi dengan `pnpm test <path/to/test>`. Untuk host dengan memori terbatas, gunakan:
Jika `pnpm test` flake pada host yang sedang berat, jalankan ulang sekali sebelum menganggapnya sebagai regresi, lalu isolasi dengan `pnpm test <path/to/test>`. Untuk host dengan memori terbatas, gunakan:
- `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test`
- `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed`
@ -81,10 +81,10 @@ Penggunaan:
- Env opsional: `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY`
- Prompt default: “Balas dengan satu kata: ok. Tanpa tanda baca atau teks tambahan.”
Jalankan terakhir (2025-12-31, 20 kali jalan):
Eksekusi terakhir (2025-12-31, 20 eksekusi):
- minimax median 1279ms (min 1114, maks 2431)
- opus median 2454ms (min 1224, maks 3170)
- median minimax 1279ms (min 1114, maks 2431)
- median opus 2454ms (min 1224, maks 3170)
## Benchmark startup CLI
@ -114,15 +114,15 @@ Preset:
- `real`: `health`, `status`, `status --json`, `sessions`, `sessions --json`, `tasks --json`, `tasks list --json`, `tasks audit --json`, `agents list --json`, `gateway status`, `gateway status --json`, `gateway health --json`, `config get gateway.port`
- `all`: kedua preset
Output mencakup `sampleCount`, rata-rata, p50, p95, min/maks, distribusi kode keluar/sinyal, dan ringkasan RSS maks untuk setiap perintah. `--cpu-prof-dir` / `--heap-prof-dir` opsional menulis profil V8 per jalan sehingga pengambilan waktu dan profil menggunakan harness yang sama.
Output mencakup `sampleCount`, rata-rata, p50, p95, min/maks, distribusi exit-code/sinyal, dan ringkasan RSS maks untuk setiap perintah. `--cpu-prof-dir` / `--heap-prof-dir` opsional menulis profil V8 per eksekusi sehingga timing dan pengambilan profil menggunakan harness yang sama.
Konvensi output tersimpan:
- `pnpm test:startup:bench:smoke` menulis artefak smoke tertarget di `.artifacts/cli-startup-bench-smoke.json`
- `pnpm test:startup:bench:save` menulis artefak suite lengkap di `.artifacts/cli-startup-bench-all.json` menggunakan `runs=5` dan `warmup=1`
- `pnpm test:startup:bench:update` menyegarkan fixture baseline yang disimpan di repo pada `test/fixtures/cli-startup-bench.json` menggunakan `runs=5` dan `warmup=1`
- `pnpm test:startup:bench:save` menulis artefak full-suite di `.artifacts/cli-startup-bench-all.json` menggunakan `runs=5` dan `warmup=1`
- `pnpm test:startup:bench:update` menyegarkan fixture baseline yang di-check-in di `test/fixtures/cli-startup-bench.json` menggunakan `runs=5` dan `warmup=1`
Fixture yang disimpan di repo:
Fixture yang di-check-in:
- `test/fixtures/cli-startup-bench.json`
- Segarkan dengan `pnpm test:startup:bench:update`
@ -130,9 +130,9 @@ Fixture yang disimpan di repo:
## E2E onboarding (Docker)
Docker bersifat opsional; ini hanya diperlukan untuk uji smoke onboarding dalam container.
Docker bersifat opsional; ini hanya diperlukan untuk uji smoke onboarding terkontainerisasi.
Alur cold-start penuh dalam container Linux yang bersih:
Alur cold-start penuh dalam kontainer Linux yang bersih:
```bash
scripts/e2e/onboard-docker.sh
@ -142,7 +142,7 @@ Skrip ini mengendalikan wizard interaktif melalui pseudo-tty, memverifikasi file
## Smoke impor QR (Docker)
Memastikan helper runtime QR yang dipelihara dimuat di runtime Docker Node yang didukung (Node 24 default, Node 22 kompatibel):
Memastikan helper runtime QR yang dipelihara dimuat pada runtime Docker Node yang didukung (Node 24 default, kompatibel dengan Node 22):
```bash
pnpm test:docker:qr
@ -152,4 +152,4 @@ pnpm test:docker:qr
- [Pengujian](/id/help/testing)
- [Pengujian live](/id/help/testing-live)
- [Menguji pembaruan dan Plugin](/id/help/testing-updates-plugins)
- [Pengujian pembaruan dan Plugin](/id/help/testing-updates-plugins)

152
docs/id/reference/transcript-hygiene.md
View File

@ -1,46 +1,52 @@
---
read_when:
- Anda sedang mendiagnosis penolakan permintaan penyedia yang terkait dengan struktur transkrip
- Anda sedang men-debug penolakan permintaan penyedia yang terkait dengan bentuk transkrip
- Anda sedang mengubah sanitasi transkrip atau logika perbaikan panggilan alat
- Anda sedang menyelidiki ketidakcocokan ID panggilan alat di berbagai penyedia
- Anda sedang menyelidiki ketidakcocokan ID pemanggilan alat di berbagai penyedia
summary: 'Referensi: aturan sanitasi dan perbaikan transkrip khusus penyedia'
title: Kebersihan transkrip
x-i18n:
generated_at: "2026-05-03T09:22:01Z"
generated_at: "2026-05-05T01:49:20Z"
model: gpt-5.5
provider: openai
source_hash: ff3a364a4c4d1c0d1e03b2860396c2d7e32c554d7acd0791ed2eaadae06d35ab
source_hash: 9441494f3e8bb18d1648acc789a40bf9501fe3f2d32b6293792e6a24710675d0
source_path: reference/transcript-hygiene.md
workflow: 16
---
OpenClaw menerapkan **perbaikan khusus penyedia** pada transkrip sebelum eksekusi (membangun konteks model). Sebagian besar perbaikan ini adalah penyesuaian **dalam memori** yang digunakan untuk memenuhi persyaratan penyedia yang ketat. Pass perbaikan file sesi terpisah juga dapat menulis ulang JSONL yang tersimpan sebelum sesi dimuat, tetapi hanya untuk baris yang rusak atau giliran tersimpan yang bukan rekaman tahan lama yang valid. Balasan asisten yang telah dikirim dipertahankan di disk; penghapusan praisi asisten khusus penyedia hanya terjadi saat menyusun payload keluar. Saat perbaikan terjadi, file asli dicadangkan di samping file sesi.
OpenClaw menerapkan **perbaikan khusus penyedia** pada transkrip sebelum sebuah run (membangun konteks model). Sebagian besar adalah penyesuaian **dalam memori** yang digunakan untuk memenuhi persyaratan penyedia yang ketat. Pass perbaikan file sesi terpisah juga dapat menulis ulang JSONL yang tersimpan sebelum sesi dimuat, tetapi hanya untuk baris yang cacat atau turn tersimpan yang merupakan rekaman tahan lama yang tidak valid. Balasan asisten yang terkirim dipertahankan di disk; penghapusan prefill asisten khusus penyedia hanya terjadi saat membangun payload keluar. Saat perbaikan terjadi, file asli dicadangkan di samping file sesi.
Cakupan meliputi:
- Konteks prompt khusus waktu berjalan tetap berada di luar giliran transkrip yang terlihat oleh pengguna
- Konteks prompt hanya-runtime yang tetap berada di luar turn transkrip yang terlihat oleh pengguna
- Sanitasi id panggilan alat
- Validasi input panggilan alat
- Perbaikan pemasangan hasil alat
- Validasi / pengurutan giliran
- Pembersihan tanda tangan pemikiran
- Validasi / pengurutan turn
- Pembersihan tanda tangan thought
- Pembersihan tanda tangan thinking
- Sanitasi payload gambar
- Pembersihan blok teks kosong sebelum pemutaran ulang penyedia
- Penandaan asal input pengguna (untuk prompt yang dirutekan antar-sesi)
- Perbaikan giliran kesalahan asisten kosong untuk pemutaran ulang Bedrock Converse
- Pembersihan blok teks kosong sebelum replay penyedia
- Penandaan asal input pengguna (untuk prompt yang dirutekan antarsesi)
- Perbaikan turn error asisten kosong untuk replay Bedrock Converse
Jika Anda memerlukan detail penyimpanan transkrip, lihat:
Jika Anda membutuhkan detail penyimpanan transkrip, lihat:
- [Pendalaman manajemen sesi](/id/reference/session-management-compaction)
---
## Aturan global: konteks waktu berjalan bukan transkrip pengguna
## Aturan global: konteks runtime bukan transkrip pengguna
Konteks waktu berjalan/sistem dapat ditambahkan ke prompt model untuk suatu giliran, tetapi itu bukan konten yang ditulis oleh pengguna akhir. OpenClaw mempertahankan badan prompt terpisah yang menghadap transkrip untuk balasan Gateway, tindak lanjut dalam antrean, ACP, CLI, dan eksekusi Pi tertanam. Giliran pengguna terlihat yang tersimpan menggunakan badan transkrip tersebut, bukan prompt yang diperkaya waktu berjalan.
Konteks runtime/sistem dapat ditambahkan ke prompt model untuk sebuah turn, tetapi itu
bukan konten yang dibuat oleh pengguna akhir. OpenClaw mempertahankan badan prompt
terpisah yang menghadap transkrip untuk balasan Gateway, followup antrean, ACP, CLI, dan run Pi
tertanam. Turn pengguna terlihat yang tersimpan menggunakan badan transkrip itu, bukan
prompt yang diperkaya runtime.
Untuk sesi lama yang sudah menyimpan pembungkus waktu berjalan, permukaan riwayat Gateway menerapkan proyeksi tampilan sebelum mengembalikan pesan ke klien WebChat, TUI, REST, atau SSE.
Untuk sesi lama yang sudah menyimpan wrapper runtime, permukaan riwayat Gateway
menerapkan proyeksi tampilan sebelum mengembalikan pesan ke klien WebChat,
TUI, REST, atau SSE.
---
@ -49,9 +55,9 @@ Untuk sesi lama yang sudah menyimpan pembungkus waktu berjalan, permukaan riwaya
Semua kebersihan transkrip dipusatkan di runner tertanam:
- Pemilihan kebijakan: `src/agents/transcript-policy.ts`
- Penerapan sanitasi/perbaikan: `sanitizeSessionHistory` di `src/agents/pi-embedded-runner/replay-history.ts`
- Aplikasi sanitasi/perbaikan: `sanitizeSessionHistory` di `src/agents/pi-embedded-runner/replay-history.ts`
Kebijakan menggunakan `provider`, `modelApi`, dan `modelId` untuk memutuskan apa yang akan diterapkan.
Kebijakan menggunakan `provider`, `modelApi`, dan `modelId` untuk memutuskan apa yang diterapkan.
Terpisah dari kebersihan transkrip, file sesi diperbaiki (jika diperlukan) sebelum dimuat:
@ -62,22 +68,28 @@ Terpisah dari kebersihan transkrip, file sesi diperbaiki (jika diperlukan) sebel
## Aturan global: sanitasi gambar
Payload gambar selalu disanitasi untuk mencegah penolakan di sisi penyedia akibat batas ukuran (mengecilkan/mengompresi ulang gambar base64 yang terlalu besar).
Payload gambar selalu disanitasi untuk mencegah penolakan di sisi penyedia akibat batas
ukuran (downscale/recompress gambar base64 yang terlalu besar).
Ini juga membantu mengendalikan tekanan token berbasis gambar untuk model yang mendukung visi. Dimensi maksimum yang lebih rendah umumnya mengurangi penggunaan token; dimensi yang lebih tinggi mempertahankan detail.
Ini juga membantu mengendalikan tekanan token yang dipicu gambar untuk model berkemampuan vision.
Dimensi maksimum yang lebih rendah umumnya mengurangi penggunaan token; dimensi yang lebih tinggi mempertahankan detail.
Implementasi:
- `sanitizeSessionMessagesImages` di `src/agents/pi-embedded-helpers/images.ts`
- `sanitizeContentBlocksImages` di `src/agents/tool-images.ts`
- Sisi gambar maksimum dapat dikonfigurasi melalui `agents.defaults.imageMaxDimensionPx` (bawaan: `1200`).
- Blok teks kosong dihapus saat pass ini menelusuri konten pemutaran ulang. Giliran asisten yang menjadi kosong dihapus dari salinan pemutaran ulang; giliran pengguna dan hasil alat yang menjadi kosong menerima placeholder konten-dihilangkan yang tidak kosong.
- Sisi gambar maksimum dapat dikonfigurasi melalui `agents.defaults.imageMaxDimensionPx` (default: `1200`).
- Blok teks kosong dihapus saat pass ini menelusuri konten replay. Turn asisten
yang menjadi kosong dihapus dari salinan replay; turn pengguna dan hasil alat
yang menjadi kosong menerima placeholder konten-yang-dihilangkan yang tidak kosong.
---
## Aturan global: panggilan alat rusak
## Aturan global: panggilan alat cacat
Blok panggilan alat asisten yang tidak memiliki `input` maupun `arguments` dihapus sebelum konteks model dibangun. Ini mencegah penolakan penyedia dari panggilan alat yang tersimpan sebagian (misalnya, setelah kegagalan batas laju).
Blok panggilan alat asisten yang tidak memiliki `input` maupun `arguments` dihapus
sebelum konteks model dibangun. Ini mencegah penolakan penyedia dari panggilan alat yang
tersimpan sebagian (misalnya, setelah kegagalan batas laju).
Implementasi:
@ -86,15 +98,22 @@ Implementasi:
---
## Aturan global: asal input antar-sesi
## Aturan global: asal input antarsesi
Saat agen mengirim prompt ke sesi lain melalui `sessions_send` (termasuk langkah balasan/pengumuman antar-agen), OpenClaw menyimpan giliran pengguna yang dibuat dengan:
Saat agen mengirim prompt ke sesi lain melalui `sessions_send` (termasuk
langkah balasan/pengumuman agen-ke-agen), OpenClaw menyimpan turn pengguna yang dibuat dengan:
- `message.provenance.kind = "inter_session"`
OpenClaw juga menambahkan marker `[Inter-session message ... isUser=false]` pada giliran yang sama sebelum teks prompt yang dirutekan agar panggilan model aktif dapat membedakan output sesi asing dari instruksi pengguna akhir eksternal. Marker ini mencakup sesi sumber, channel, dan alat bila tersedia. Transkrip tetap menggunakan `role: "user"` untuk kompatibilitas penyedia, tetapi teks terlihat dan metadata asal sama-sama menandai giliran sebagai data antar-sesi.
OpenClaw juga menambahkan marker `[Inter-session message ... isUser=false]`
pada turn yang sama sebelum teks prompt yang dirutekan sehingga panggilan model aktif dapat membedakan
output sesi asing dari instruksi pengguna akhir eksternal. Marker ini mencakup
sesi sumber, kanal, dan alat jika tersedia. Transkrip tetap menggunakan
`role: "user"` untuk kompatibilitas penyedia, tetapi teks terlihat dan metadata
asal sama-sama menandai turn sebagai data antarsesi.
Selama pembangunan ulang konteks, OpenClaw menerapkan marker yang sama pada giliran pengguna antar-sesi lama yang tersimpan dan hanya memiliki metadata asal.
Selama pembangunan ulang konteks, OpenClaw menerapkan marker yang sama pada turn pengguna
antarsesi lama yang tersimpan dan hanya memiliki metadata asal.
---
@ -103,57 +122,74 @@ Selama pembangunan ulang konteks, OpenClaw menerapkan marker yang sama pada gili
**OpenAI / OpenAI Codex**
- Hanya sanitasi gambar.
- Hapus tanda tangan penalaran yatim (item penalaran mandiri tanpa blok konten berikutnya) untuk transkrip OpenAI Responses/Codex, dan hapus penalaran OpenAI yang dapat diputar ulang setelah pengalihan rute model.
- Pertahankan payload item penalaran OpenAI Responses yang dapat diputar ulang, termasuk item ringkasan kosong terenkripsi, agar pemutaran ulang manual/WebSocket mempertahankan status `rs_*` yang diperlukan tetap berpasangan dengan item output asisten.
- Hapus tanda tangan reasoning yatim (item reasoning mandiri tanpa blok konten berikutnya) untuk transkrip OpenAI Responses/Codex, dan hapus reasoning OpenAI yang dapat direplay setelah pergantian rute model.
- Pertahankan payload item reasoning OpenAI Responses yang dapat direplay, termasuk item ringkasan-kosong terenkripsi, agar replay manual/WebSocket tetap menjaga status `rs_*` yang diperlukan berpasangan dengan item output asisten.
- Native ChatGPT Codex Responses mengikuti paritas wire Codex dengan mereplay payload reasoning/message/function Responses sebelumnya tanpa ID item sebelumnya sambil mempertahankan `prompt_cache_key` sesi.
- Tidak ada sanitasi id panggilan alat.
- Perbaikan pemasangan hasil alat dapat memindahkan output nyata yang cocok dan mensintesis output bergaya Codex `aborted` untuk panggilan alat yang hilang.
- Tidak ada validasi atau pengurutan ulang giliran.
- Output alat keluarga OpenAI Responses yang hilang disintesis sebagai `aborted` agar sesuai dengan normalisasi pemutaran ulang Codex.
- Tidak ada penghapusan tanda tangan pemikiran.
- Perbaikan pemasangan hasil alat dapat memindahkan output nyata yang cocok dan menyintesis output bergaya Codex `aborted` untuk panggilan alat yang hilang.
- Tidak ada validasi atau pengurutan ulang turn.
- Output alat keluarga OpenAI Responses yang hilang disintesis sebagai `aborted` agar sesuai dengan normalisasi replay Codex.
- Tidak ada penghapusan tanda tangan thought.
**Gemma 4 kompatibel OpenAI**
- Blok thinking/penalaran asisten historis dihapus sebelum pemutaran ulang agar server Gemma 4 lokal yang kompatibel OpenAI tidak menerima konten penalaran dari giliran sebelumnya.
- Kelanjutan panggilan alat pada giliran yang sama saat ini mempertahankan blok penalaran asisten yang terlampir pada panggilan alat hingga hasil alat telah diputar ulang.
- Blok thinking/reasoning asisten historis dihapus sebelum replay agar server Gemma 4
lokal yang kompatibel OpenAI tidak menerima konten reasoning turn sebelumnya.
- Kelanjutan panggilan alat pada turn yang sama saat ini mempertahankan blok reasoning asisten
yang melekat pada panggilan alat sampai hasil alat telah direplay.
**Google (Generative AI / Gemini CLI / Antigravity)**
- Sanitasi id panggilan alat: alfanumerik ketat.
- Perbaikan pemasangan hasil alat dan hasil alat sintetis.
- Validasi giliran (pergantian giliran bergaya Gemini).
- Perbaikan pengurutan giliran Google (tambahkan bootstrap pengguna kecil jika riwayat dimulai dengan asisten).
- Antigravity Claude: normalisasi tanda tangan thinking; hapus blok thinking tanpa tanda tangan.
- Validasi turn (alternasi turn bergaya Gemini).
- Perbaikan pengurutan turn Google (menambahkan bootstrap pengguna kecil jika riwayat dimulai dengan asisten).
- Antigravity Claude: normalkan tanda tangan thinking; hapus blok thinking yang tidak bertanda tangan.
**Anthropic / Minimax (kompatibel Anthropic)**
- Perbaikan pemasangan hasil alat dan hasil alat sintetis.
- Validasi giliran (gabungkan giliran pengguna berurutan untuk memenuhi pergantian ketat).
- Giliran praisi asisten di akhir dihapus dari payload Anthropic Messages keluar saat thinking diaktifkan, termasuk rute Cloudflare AI Gateway.
- Blok thinking dengan tanda tangan pemutaran ulang yang hilang, kosong, atau hanya spasi dihapus sebelum konversi penyedia. Jika itu membuat giliran asisten kosong, OpenClaw mempertahankan bentuk giliran dengan teks penalaran-dihilangkan yang tidak kosong.
- Giliran asisten lama yang hanya berisi thinking dan harus dihapus diganti dengan teks penalaran-dihilangkan yang tidak kosong agar adaptor penyedia tidak menghapus giliran pemutaran ulang.
- Validasi turn (gabungkan turn pengguna berurutan untuk memenuhi alternasi ketat).
- Turn prefill asisten di akhir dihapus dari payload Anthropic Messages
keluar saat thinking diaktifkan, termasuk rute Cloudflare AI Gateway.
- Blok thinking dengan tanda tangan replay yang hilang, kosong, atau blank dihapus
sebelum konversi penyedia. Jika itu mengosongkan turn asisten, OpenClaw mempertahankan
bentuk turn dengan teks reasoning-yang-dihilangkan yang tidak kosong.
- Turn asisten lama yang hanya berisi thinking dan harus dihapus diganti dengan
teks reasoning-yang-dihilangkan yang tidak kosong agar adapter penyedia tidak menghapus turn
replay.
**Amazon Bedrock (Converse API)**
- Giliran kesalahan stream asisten kosong diperbaiki menjadi blok teks fallback yang tidak kosong sebelum pemutaran ulang. Bedrock Converse menolak pesan asisten dengan `content: []`, sehingga giliran asisten tersimpan dengan `stopReason: "error"` dan konten kosong juga diperbaiki di disk sebelum dimuat.
- Giliran kesalahan stream asisten yang hanya berisi blok teks kosong dihapus dari salinan pemutaran ulang dalam memori, bukan memutar ulang blok kosong yang tidak valid.
- Blok thinking Claude dengan tanda tangan pemutaran ulang yang hilang, kosong, atau hanya spasi dihapus sebelum pemutaran ulang Converse. Jika itu membuat giliran asisten kosong, OpenClaw mempertahankan bentuk giliran dengan teks penalaran-dihilangkan yang tidak kosong.
- Giliran asisten lama yang hanya berisi thinking dan harus dihapus diganti dengan teks penalaran-dihilangkan yang tidak kosong agar pemutaran ulang Converse mempertahankan bentuk giliran ketat.
- Pemutaran ulang memfilter giliran asisten cermin-pengiriman OpenClaw dan yang disisipkan Gateway.
- Sanitasi gambar diterapkan melalui aturan global.
- Turn error-stream asisten kosong diperbaiki menjadi blok teks fallback yang tidak kosong
sebelum replay. Bedrock Converse menolak pesan asisten dengan `content: []`, sehingga
turn asisten tersimpan dengan `stopReason: "error"` dan konten kosong juga
diperbaiki di disk sebelum dimuat.
- Turn error-stream asisten yang hanya berisi blok teks kosong dihapus
dari salinan replay dalam memori alih-alih mereplay blok kosong yang tidak valid.
- Blok thinking Claude dengan tanda tangan replay yang hilang, kosong, atau blank
dihapus sebelum replay Converse. Jika itu mengosongkan turn asisten, OpenClaw
mempertahankan bentuk turn dengan teks reasoning-yang-dihilangkan yang tidak kosong.
- Turn asisten lama yang hanya berisi thinking dan harus dihapus diganti dengan
teks reasoning-yang-dihilangkan yang tidak kosong agar replay Converse menjaga bentuk turn yang ketat.
- Replay memfilter turn asisten delivery-mirror OpenClaw dan yang diinjeksi gateway.
- Sanitasi gambar berlaku melalui aturan global.
**Mistral (termasuk deteksi berbasis id model)**
**Mistral (termasuk deteksi berbasis model-id)**
- Sanitasi id panggilan alat: strict9 (alfanumerik panjang 9).
**OpenRouter Gemini**
- Pembersihan tanda tangan pemikiran: hapus nilai `thought_signature` non-base64 (pertahankan base64).
- Pembersihan tanda tangan thought: hapus nilai `thought_signature` non-base64 (pertahankan base64).
**OpenRouter Anthropic**
- Giliran praisi asisten di akhir dihapus dari payload model Anthropic kompatibel OpenAI yang terverifikasi di OpenRouter saat penalaran diaktifkan, sesuai dengan perilaku pemutaran ulang Anthropic langsung dan Cloudflare Anthropic.
- Turn prefill asisten di akhir dihapus dari payload model Anthropic kompatibel OpenAI
OpenRouter terverifikasi saat reasoning diaktifkan, sesuai dengan
perilaku replay Anthropic langsung dan Cloudflare Anthropic.
**Semua yang lain**
**Semua lainnya**
- Hanya sanitasi gambar.
@ -161,18 +197,20 @@ Selama pembangunan ulang konteks, OpenClaw menerapkan marker yang sama pada gili
## Perilaku historis (pra-2026.1.22)
Sebelum rilis 2026.1.22, OpenClaw menerapkan beberapa lapis kebersihan transkrip:
Sebelum rilis 2026.1.22, OpenClaw menerapkan beberapa lapisan kebersihan transkrip:
- **Ekstensi sanitasi transkrip** berjalan pada setiap pembangunan konteks dan dapat:
- **Plugin transcript-sanitize** berjalan pada setiap pembangunan konteks dan dapat:
- Memperbaiki pemasangan penggunaan/hasil alat.
- Menyantasi id panggilan alat (termasuk mode tidak ketat yang mempertahankan `_`/`-`).
- Menyantitasi id panggilan alat (termasuk mode tidak ketat yang mempertahankan `_`/`-`).
- Runner juga melakukan sanitasi khusus penyedia, yang menduplikasi pekerjaan.
- Mutasi tambahan terjadi di luar kebijakan penyedia, termasuk:
- Menghapus tag `<final>` dari teks asisten sebelum persistensi.
- Menghapus giliran kesalahan asisten kosong.
- Menghapus turn error asisten kosong.
- Memangkas konten asisten setelah panggilan alat.
Kompleksitas ini menyebabkan regresi lintas penyedia (terutama pemasangan `call_id|fc_id` `openai-responses`). Pembersihan 2026.1.22 menghapus ekstensi tersebut, memusatkan logika di runner, dan membuat OpenAI **tanpa sentuhan** selain sanitasi gambar.
Kompleksitas ini menyebabkan regresi lintas penyedia (terutama pemasangan `openai-responses`
`call_id|fc_id`). Pembersihan 2026.1.22 menghapus Plugin tersebut, memusatkan
logika di runner, dan menjadikan OpenAI **tanpa-sentuh** di luar sanitasi gambar.
## Terkait

119
docs/id/security/network-proxy.md
View File

@ -1,69 +1,70 @@
---
read_when:
- Anda menginginkan pertahanan berlapis terhadap serangan SSRF dan pengikatan ulang DNS
- Mengonfigurasi proksi penerusan eksternal untuk lalu lintas waktu proses OpenClaw
summary: Cara merutekan lalu lintas HTTP dan WebSocket runtime OpenClaw melalui proksi pemfilteran yang dikelola operator
- Anda menginginkan pertahanan berlapis terhadap serangan SSRF dan DNS rebinding
- Mengonfigurasi proksi penerus eksternal untuk lalu lintas runtime OpenClaw
summary: Cara merutekan lalu lintas HTTP dan WebSocket waktu jalan OpenClaw melalui proksi pemfilteran yang dikelola operator
title: Proksi jaringan
x-i18n:
generated_at: "2026-05-04T18:24:26Z"
generated_at: "2026-05-05T01:49:17Z"
model: gpt-5.5
provider: openai
source_hash: eedbf3bac14800c34c7ca2e3b6879dac360a88d51b5b7449ddf41a4dd471648b
source_hash: f7ab345d172d63e388ff1221535efd19934dcbf3173f95bc69131f9ad672e0df
source_path: security/network-proxy.md
workflow: 16
---
# Proksi Jaringan
# Proxy Jaringan
OpenClaw dapat merutekan lalu lintas HTTP dan WebSocket runtime melalui proksi penerusan yang dikelola operator. Ini adalah pertahanan berlapis opsional untuk deployment yang menginginkan kontrol egress terpusat, perlindungan SSRF yang lebih kuat, dan auditabilitas jaringan yang lebih baik.
OpenClaw dapat merutekan lalu lintas HTTP dan WebSocket runtime melalui proxy penerus yang dikelola operator. Ini adalah pertahanan berlapis opsional untuk deployment yang menginginkan kontrol egress terpusat, perlindungan SSRF yang lebih kuat, dan auditabilitas jaringan yang lebih baik.
OpenClaw tidak menyertakan, mengunduh, memulai, mengonfigurasi, atau menyertifikasi proksi. Anda menjalankan teknologi proksi yang sesuai dengan lingkungan Anda, dan OpenClaw merutekan klien HTTP dan WebSocket lokal proses yang normal melaluinya.
OpenClaw tidak mengirimkan, mengunduh, memulai, mengonfigurasi, atau mensertifikasi proxy. Anda menjalankan teknologi proxy yang sesuai dengan lingkungan Anda, dan OpenClaw merutekan klien HTTP dan WebSocket normal yang lokal terhadap proses melaluinya.
## Mengapa Menggunakan Proksi?
## Mengapa Menggunakan Proxy?
Proksi memberi operator satu titik kontrol jaringan untuk lalu lintas HTTP dan WebSocket keluar. Itu dapat berguna bahkan di luar pengerasan SSRF:
Proxy memberi operator satu titik kontrol jaringan untuk lalu lintas HTTP dan WebSocket keluar. Itu dapat berguna bahkan di luar penguatan SSRF:
- Kebijakan terpusat: kelola satu kebijakan egress alih-alih bergantung pada setiap lokasi panggilan HTTP aplikasi untuk menerapkan aturan jaringan dengan benar.
- Pemeriksaan saat koneksi: evaluasi tujuan setelah resolusi DNS dan tepat sebelum proksi membuka koneksi upstream.
- Pertahanan terhadap DNS rebinding: kurangi celah antara pemeriksaan DNS tingkat aplikasi dan koneksi keluar yang sebenarnya.
- Kebijakan terpusat: pertahankan satu kebijakan egress alih-alih mengandalkan setiap lokasi panggilan HTTP aplikasi untuk menerapkan aturan jaringan dengan benar.
- Pemeriksaan saat koneksi: evaluasi tujuan setelah resolusi DNS dan tepat sebelum proxy membuka koneksi upstream.
- Pertahanan DNS rebinding: kurangi celah antara pemeriksaan DNS tingkat aplikasi dan koneksi keluar yang sebenarnya.
- Cakupan JavaScript yang lebih luas: rutekan klien biasa seperti `fetch`, `node:http`, `node:https`, WebSocket, axios, got, node-fetch, dan klien serupa melalui jalur yang sama.
- Auditabilitas: catat tujuan yang diizinkan dan ditolak di batas egress.
- Kontrol operasional: terapkan aturan tujuan, segmentasi jaringan, batas laju, atau allowlist keluar tanpa membangun ulang OpenClaw.
Perutean proksi adalah guardrail tingkat proses untuk egress HTTP dan WebSocket normal. Ini memberi operator jalur gagal-tertutup untuk merutekan klien HTTP JavaScript yang didukung melalui proksi pemfilteran mereka sendiri, tetapi ini bukan sandbox jaringan tingkat OS dan tidak membuat OpenClaw menyertifikasi kebijakan tujuan proksi.
Perutean proxy adalah pagar pembatas tingkat proses untuk egress HTTP dan WebSocket normal. Ini memberi operator jalur gagal-tertutup untuk merutekan klien HTTP JavaScript yang didukung melalui proxy penyaring milik mereka sendiri, tetapi ini bukan sandbox jaringan tingkat OS dan tidak membuat OpenClaw mensertifikasi kebijakan tujuan proxy.
## Cara OpenClaw Merutekan Lalu Lintas
Ketika `proxy.enabled=true` dan URL proksi dikonfigurasi, proses runtime yang dilindungi seperti `openclaw gateway run`, `openclaw node run`, dan `openclaw agent --local` merutekan egress HTTP dan WebSocket normal melalui proksi yang dikonfigurasi:
Saat `proxy.enabled=true` dan URL proxy dikonfigurasi, proses runtime yang dilindungi seperti `openclaw gateway run`, `openclaw node run`, dan `openclaw agent --local` merutekan egress HTTP dan WebSocket normal melalui proxy yang dikonfigurasi:
```text
OpenClaw process
fetch -> operator-managed filtering proxy -> public internet
node:http and https -> operator-managed filtering proxy -> public internet
WebSocket clients -> operator-managed filtering proxy -> public internet
Proses OpenClaw
fetch -> proxy penyaring yang dikelola operator -> internet publik
node:http and https -> proxy penyaring yang dikelola operator -> internet publik
Klien WebSocket -> proxy penyaring yang dikelola operator -> internet publik
```
Kontrak publiknya adalah perilaku perutean, bukan hook Node internal yang digunakan untuk mengimplementasikannya. Klien WebSocket control-plane OpenClaw Gateway menggunakan jalur langsung yang sempit untuk lalu lintas RPC Gateway local loopback saat URL Gateway menggunakan `localhost` atau IP loopback literal seperti `127.0.0.1` atau `[::1]`. Jalur control-plane itu harus dapat menjangkau Gateway loopback bahkan ketika proksi operator memblokir tujuan loopback. Permintaan HTTP dan WebSocket runtime normal tetap menggunakan proksi yang dikonfigurasi.
Kontrak publiknya adalah perilaku perutean, bukan hook Node internal yang digunakan untuk menerapkannya. Klien WebSocket bidang kontrol OpenClaw Gateway menggunakan jalur langsung yang sempit untuk lalu lintas RPC Gateway local loopback saat URL Gateway menggunakan `localhost` atau IP loopback literal seperti `127.0.0.1` atau `[::1]`. Jalur bidang kontrol tersebut harus dapat menjangkau Gateway loopback bahkan saat proxy operator memblokir tujuan loopback. Permintaan HTTP dan WebSocket runtime normal tetap menggunakan proxy yang dikonfigurasi.
Secara internal, OpenClaw menggunakan dua hook perutean tingkat proses untuk fitur ini:
- Perutean dispatcher Undici mencakup `fetch`, klien berbasis undici, dan transport yang menyediakan dispatcher undici mereka sendiri.
- Perutean `global-agent` mencakup pemanggil Node core `node:http` dan `node:https`, termasuk banyak pustaka yang dibangun di atas `http.request`, `https.request`, `http.get`, dan `https.get`. Mode proksi terkelola memaksa agent global itu agar agent HTTP Node eksplisit tidak secara tidak sengaja melewati proksi operator.
- Perutean `global-agent` mencakup pemanggil inti Node `node:http` dan `node:https`, termasuk banyak pustaka yang dibangun di atas `http.request`, `https.request`, `http.get`, dan `https.get`. Mode proxy terkelola memaksa agen global tersebut sehingga agen HTTP Node eksplisit tidak secara tidak sengaja melewati proxy operator.
Beberapa Plugin memiliki transport kustom yang memerlukan penyambungan proksi eksplisit bahkan ketika perutean tingkat proses sudah ada. Misalnya, transport Bot API Telegram menggunakan dispatcher undici HTTP/1 miliknya sendiri sehingga menghormati env proksi proses plus fallback `OPENCLAW_PROXY_URL` terkelola di jalur transport khusus pemilik tersebut.
Beberapa Plugin memiliki transport kustom yang memerlukan pengkabelan proxy eksplisit bahkan saat perutean tingkat proses ada. Misalnya, transport Bot API Telegram menggunakan dispatcher HTTP/1 undici miliknya sendiri dan karena itu menghormati env proxy proses plus fallback `OPENCLAW_PROXY_URL` terkelola pada jalur transport khusus pemilik tersebut.
URL proksi itu sendiri harus menggunakan `http://`. Tujuan HTTPS tetap didukung melalui proksi dengan HTTP `CONNECT`; ini hanya berarti OpenClaw mengharapkan listener proksi penerusan HTTP biasa seperti `http://127.0.0.1:3128`.
URL proxy itu sendiri harus menggunakan `http://`. Tujuan HTTPS tetap didukung melalui proxy dengan HTTP `CONNECT`; ini hanya berarti OpenClaw mengharapkan listener proxy penerus HTTP biasa seperti `http://127.0.0.1:3128`.
Saat proksi aktif, OpenClaw mengosongkan `no_proxy`, `NO_PROXY`, dan `GLOBAL_AGENT_NO_PROXY`. Daftar bypass tersebut berbasis tujuan, sehingga membiarkan `localhost` atau `127.0.0.1` di sana akan memungkinkan target SSRF berisiko tinggi melewati proksi pemfilteran.
Saat proxy aktif, OpenClaw menghapus `no_proxy`, `NO_PROXY`, dan `GLOBAL_AGENT_NO_PROXY`. Daftar bypass tersebut berbasis tujuan, jadi membiarkan `localhost` atau `127.0.0.1` di sana akan memungkinkan target SSRF berisiko tinggi melewati proxy penyaring.
Saat shutdown, OpenClaw memulihkan lingkungan proksi sebelumnya dan mereset status perutean proses yang di-cache.
Saat shutdown, OpenClaw memulihkan lingkungan proxy sebelumnya dan mengatur ulang status perutean proses yang di-cache.
## Istilah Proksi Terkait
## Istilah Proxy Terkait
- `proxy.enabled` / `proxy.proxyUrl`: perutean proksi penerusan keluar untuk egress runtime OpenClaw. Halaman ini mendokumentasikan fitur tersebut.
- `gateway.auth.mode: "trusted-proxy"`: autentikasi proksi balik sadar identitas masuk untuk akses Gateway. Lihat [Autentikasi proksi tepercaya](/id/gateway/trusted-proxy-auth).
- `openclaw proxy`: proksi debug lokal dan pemeriksa capture untuk pengembangan dan dukungan. Lihat [openclaw proxy](/id/cli/proxy).
- Pengaturan proksi khusus saluran atau penyedia: override khusus pemilik untuk transport tertentu. Utamakan proksi jaringan terkelola saat tujuannya adalah kontrol egress terpusat di seluruh runtime.
- `proxy.enabled` / `proxy.proxyUrl`: perutean proxy penerus keluar untuk egress runtime OpenClaw. Halaman ini mendokumentasikan fitur tersebut.
- `gateway.auth.mode: "trusted-proxy"`: autentikasi reverse proxy masuk yang sadar identitas untuk akses Gateway. Lihat [Autentikasi proxy tepercaya](/id/gateway/trusted-proxy-auth).
- `openclaw proxy`: proxy debug lokal dan inspektur tangkapan untuk pengembangan dan dukungan. Lihat [openclaw proxy](/id/cli/proxy).
- `tools.web.fetch.useTrustedEnvProxy`: opt-in bagi `web_fetch` untuk memungkinkan proxy env HTTP(S) yang dikendalikan operator menyelesaikan DNS sambil mempertahankan pinning DNS ketat default dan kebijakan nama host. Lihat [Web fetch](/id/tools/web-fetch#trusted-env-proxy).
- Pengaturan proxy khusus channel atau penyedia: override khusus pemilik untuk transport tertentu. Lebih baik gunakan proxy jaringan terkelola saat tujuannya adalah kontrol egress terpusat di seluruh runtime.
## Konfigurasi
@ -81,9 +82,9 @@ OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run
`proxy.proxyUrl` lebih diprioritaskan daripada `OPENCLAW_PROXY_URL`.
Jika `enabled=true` tetapi tidak ada URL proksi valid yang dikonfigurasi, perintah yang dilindungi akan gagal saat startup alih-alih kembali ke akses jaringan langsung.
Jika `enabled=true` tetapi tidak ada URL proxy valid yang dikonfigurasi, perintah yang dilindungi akan gagal saat startup alih-alih kembali ke akses jaringan langsung.
Untuk layanan gateway terkelola yang dimulai dengan `openclaw gateway start`, sebaiknya simpan URL dalam konfigurasi:
Untuk layanan gateway terkelola yang dimulai dengan `openclaw gateway start`, lebih baik simpan URL dalam konfigurasi:
```bash
openclaw config set proxy.enabled true
@ -92,42 +93,42 @@ openclaw gateway install --force
openclaw gateway start
```
Fallback lingkungan paling cocok untuk proses foreground. Jika Anda menggunakannya dengan layanan terpasang, letakkan `OPENCLAW_PROXY_URL` di lingkungan tahan lama layanan, seperti `$OPENCLAW_STATE_DIR/.env` atau `~/.openclaw/.env`, lalu pasang ulang layanan agar launchd, systemd, atau Scheduled Tasks memulai gateway dengan nilai tersebut.
Fallback lingkungan paling cocok untuk proses foreground. Jika Anda menggunakannya dengan layanan yang terinstal, letakkan `OPENCLAW_PROXY_URL` di lingkungan tahan lama layanan, seperti `$OPENCLAW_STATE_DIR/.env` atau `~/.openclaw/.env`, lalu instal ulang layanan agar launchd, systemd, atau Scheduled Tasks memulai gateway dengan nilai tersebut.
Untuk perintah `openclaw --container ...`, OpenClaw meneruskan `OPENCLAW_PROXY_URL` ke CLI turunan yang ditargetkan ke kontainer saat nilai itu disetel. URL harus dapat dijangkau dari dalam kontainer; `127.0.0.1` merujuk ke kontainer itu sendiri, bukan host. OpenClaw menolak URL proksi loopback untuk perintah yang ditargetkan ke kontainer kecuali Anda secara eksplisit mengganti pemeriksaan keamanan tersebut.
Untuk perintah `openclaw --container ...`, OpenClaw meneruskan `OPENCLAW_PROXY_URL` ke CLI anak yang ditargetkan ke kontainer saat nilai tersebut disetel. URL harus dapat dijangkau dari dalam kontainer; `127.0.0.1` merujuk ke kontainer itu sendiri, bukan host. OpenClaw menolak URL proxy loopback untuk perintah yang ditargetkan ke kontainer kecuali Anda secara eksplisit meng-override pemeriksaan keamanan tersebut.
## Persyaratan Proksi
## Persyaratan Proxy
Kebijakan proksi adalah batas keamanan. OpenClaw tidak dapat memverifikasi bahwa proksi memblokir target yang tepat.
Kebijakan proxy adalah batas keamanan. OpenClaw tidak dapat memverifikasi bahwa proxy memblokir target yang tepat.
Konfigurasikan proksi untuk:
Konfigurasikan proxy untuk:
- Hanya bind ke loopback atau antarmuka privat tepercaya.
- Mengikat hanya ke loopback atau antarmuka privat tepercaya.
- Membatasi akses sehingga hanya proses, host, kontainer, atau akun layanan OpenClaw yang dapat menggunakannya.
- Meresolusi tujuan sendiri dan memblokir IP tujuan setelah resolusi DNS.
- Menerapkan kebijakan pada saat koneksi untuk permintaan HTTP biasa dan tunnel HTTPS `CONNECT`.
- Menolak bypass berbasis tujuan untuk rentang loopback, privat, link-local, metadata, multicast, reserved, atau dokumentasi.
- Menyelesaikan tujuan sendiri dan memblokir IP tujuan setelah resolusi DNS.
- Menerapkan kebijakan saat koneksi untuk permintaan HTTP biasa maupun tunnel HTTPS `CONNECT`.
- Menolak bypass berbasis tujuan untuk loopback, privat, link-local, metadata, multicast, reserved, atau rentang dokumentasi.
- Menghindari allowlist nama host kecuali Anda sepenuhnya memercayai jalur resolusi DNS.
- Mencatat tujuan, keputusan, status, dan alasan tanpa mencatat body permintaan, header otorisasi, cookie, atau rahasia lainnya.
- Menyimpan kebijakan proksi di bawah kontrol versi dan meninjau perubahan seperti konfigurasi yang sensitif terhadap keamanan.
- Mencatat tujuan, keputusan, status, dan alasan tanpa mencatat isi permintaan, header otorisasi, cookie, atau rahasia lainnya.
- Menyimpan kebijakan proxy dalam kontrol versi dan meninjau perubahan seperti konfigurasi yang sensitif terhadap keamanan.
## Tujuan yang Direkomendasikan untuk Diblokir
Gunakan denylist ini sebagai titik awal untuk setiap proksi penerusan, firewall, atau kebijakan egress.
Gunakan denylist ini sebagai titik awal untuk proxy penerus, firewall, atau kebijakan egress apa pun.
Logika classifier tingkat aplikasi OpenClaw berada di `src/infra/net/ssrf.ts` dan `src/shared/net/ip.ts`. Hook paritas yang relevan adalah `BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, `RFC2544_BENCHMARK_PREFIX`, dan penanganan sentinel IPv4 tertanam untuk bentuk NAT64, 6to4, Teredo, ISATAP, dan IPv4-mapped. File-file tersebut adalah referensi berguna saat memelihara kebijakan proksi eksternal, tetapi OpenClaw tidak otomatis mengekspor atau menerapkan aturan tersebut di proksi Anda.
Logika classifier tingkat aplikasi OpenClaw berada di `src/infra/net/ssrf.ts` dan `src/shared/net/ip.ts`. Hook paritas yang relevan adalah `BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, `RFC2544_BENCHMARK_PREFIX`, dan penanganan sentinel IPv4 tertanam untuk NAT64, 6to4, Teredo, ISATAP, dan bentuk IPv4-mapped. File-file tersebut adalah referensi berguna saat memelihara kebijakan proxy eksternal, tetapi OpenClaw tidak secara otomatis mengekspor atau menegakkan aturan tersebut di proxy Anda.
| Rentang atau host | Alasan untuk memblokir |
| ------------------------------------------------------------------------------------ | --------------------------------------------------- |
| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | Loopback IPv4 |
| `::1/128` | Loopback IPv6 |
| `0.0.0.0/8`, `::/128` | Alamat tidak ditentukan dan jaringan-ini |
| `0.0.0.0/8`, `::/128` | Alamat unspecified dan jaringan ini |
| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | Jaringan privat RFC1918 |
| `169.254.0.0/16`, `fe80::/10` | Alamat link-local dan jalur metadata cloud umum |
| `169.254.169.254`, `metadata.google.internal` | Layanan metadata cloud |
| `100.64.0.0/10` | Ruang alamat bersama NAT carrier-grade |
| `198.18.0.0/15`, `2001:2::/48` | Rentang benchmarking |
| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | Rentang penggunaan khusus dan dokumentasi |
| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | Rentang special-use dan dokumentasi |
| `224.0.0.0/4`, `ff00::/8` | Multicast |
| `240.0.0.0/4` | IPv4 reserved |
| `fc00::/7`, `fec0::/10` | Rentang lokal/privat IPv6 |
@ -140,15 +141,15 @@ Jika penyedia cloud atau platform jaringan Anda mendokumentasikan host metadata
## Validasi
Validasikan proksi dari host, kontainer, atau akun layanan yang sama yang menjalankan OpenClaw:
Validasi proxy dari host, kontainer, atau akun layanan yang sama yang menjalankan OpenClaw:
```bash
openclaw proxy validate --proxy-url http://127.0.0.1:3128
```
Secara default, ketika tidak ada tujuan kustom yang disediakan, perintah memeriksa bahwa `https://example.com/` berhasil dan memulai canary loopback sementara yang tidak boleh dijangkau proksi. Pemeriksaan ditolak default lulus ketika proksi mengembalikan respons penolakan non-2xx atau memblokir canary dengan kegagalan transport; pemeriksaan gagal jika respons berhasil mencapai canary. Jika tidak ada proksi yang diaktifkan dan dikonfigurasi, validasi melaporkan masalah konfigurasi; gunakan `--proxy-url` untuk preflight sekali jalan sebelum mengubah konfigurasi. Gunakan `--allowed-url` dan `--denied-url` untuk menguji ekspektasi khusus deployment. Tambahkan `--apns-reachable` untuk juga memverifikasi bahwa pengiriman HTTP/2 APNs langsung dapat membuka tunnel CONNECT melalui proksi dan menerima respons APNs sandbox; probe menggunakan token penyedia yang sengaja tidak valid, sehingga `403 InvalidProviderToken` diharapkan dan dihitung sebagai dapat dijangkau. Tujuan ditolak kustom bersifat gagal-tertutup: respons HTTP apa pun berarti tujuan dapat dijangkau melalui proksi, dan setiap error transport dilaporkan sebagai tidak meyakinkan karena OpenClaw tidak dapat membuktikan proksi memblokir origin yang dapat dijangkau. Pada kegagalan validasi, perintah keluar dengan kode 1.
Secara default, saat tidak ada tujuan kustom yang diberikan, perintah memeriksa bahwa `https://example.com/` berhasil dan memulai canary loopback sementara yang tidak boleh dijangkau oleh proxy. Pemeriksaan penolakan default lulus saat proxy mengembalikan respons penolakan non-2xx atau memblokir canary dengan kegagalan transport; pemeriksaan gagal jika respons berhasil mencapai canary. Jika tidak ada proxy yang diaktifkan dan dikonfigurasi, validasi melaporkan masalah konfigurasi; gunakan `--proxy-url` untuk preflight satu kali sebelum mengubah konfigurasi. Gunakan `--allowed-url` dan `--denied-url` untuk menguji ekspektasi khusus deployment. Tambahkan `--apns-reachable` untuk juga memverifikasi bahwa pengiriman HTTP/2 APNs langsung dapat membuka tunnel CONNECT melalui proxy dan menerima respons sandbox APNs; probe menggunakan token penyedia yang sengaja tidak valid, jadi `403 InvalidProviderToken` diharapkan dan dihitung sebagai dapat dijangkau. Tujuan penolakan kustom bersifat gagal-tertutup: respons HTTP apa pun berarti tujuan dapat dijangkau melalui proxy, dan kesalahan transport apa pun dilaporkan sebagai tidak konklusif karena OpenClaw tidak dapat membuktikan bahwa proxy memblokir origin yang dapat dijangkau. Pada kegagalan validasi, perintah keluar dengan kode 1.
Gunakan `--json` untuk otomatisasi. Output JSON berisi hasil keseluruhan, sumber konfigurasi proksi efektif, setiap error konfigurasi, dan setiap pemeriksaan tujuan. Kredensial URL proksi disensor dalam output teks dan JSON:
Gunakan `--json` untuk otomatisasi. Keluaran JSON berisi hasil keseluruhan, sumber konfigurasi proxy efektif, kesalahan konfigurasi apa pun, dan setiap pemeriksaan tujuan. Kredensial URL proxy disamarkan dalam keluaran teks dan JSON:
```json
{
@ -184,9 +185,9 @@ curl -x http://127.0.0.1:3128 http://127.0.0.1/
curl -x http://127.0.0.1:3128 http://169.254.169.254/
```
Permintaan publik seharusnya berhasil. Permintaan loopback dan metadata seharusnya diblokir oleh proxy. Untuk `openclaw proxy validate`, canary loopback bawaan dapat membedakan penolakan proxy dari origin yang dapat dijangkau. Pemeriksaan `--denied-url` khusus tidak memiliki canary tersebut, jadi perlakukan baik respons HTTP maupun kegagalan transport yang ambigu sebagai kegagalan validasi kecuali proxy Anda mengekspos sinyal penolakan khusus penerapan yang dapat Anda verifikasi secara terpisah.
Permintaan publik seharusnya berhasil. Permintaan loopback dan metadata seharusnya diblokir oleh proxy. Untuk `openclaw proxy validate`, kanari loopback bawaan dapat membedakan penolakan proxy dari origin yang dapat dijangkau. Pemeriksaan `--denied-url` khusus tidak memiliki kanari itu, jadi perlakukan respons HTTP dan kegagalan transport yang ambigu sebagai kegagalan validasi kecuali proxy Anda mengekspos sinyal penolakan khusus deployment yang dapat Anda verifikasi secara terpisah.
Lalu aktifkan perutean proxy OpenClaw:
Kemudian aktifkan perutean proxy OpenClaw:
```bash
openclaw config set proxy.enabled true
@ -202,13 +203,13 @@ proxy:
proxyUrl: http://127.0.0.1:3128
```
## Batasan
## Batas
- Proxy meningkatkan cakupan untuk klien HTTP JavaScript dan WebSocket lokal proses, tetapi ini bukan sandbox jaringan tingkat OS.
- Soket mentah `net`, `tls`, dan `http2`, addon native, serta proses anak dapat melewati perutean proxy tingkat Node kecuali mereka mewarisi dan mematuhi variabel lingkungan proxy.
- IRC adalah kanal TCP/TLS mentah di luar perutean proxy maju yang dikelola operator. Dalam deployment yang mengharuskan semua egress melalui proxy maju tersebut, atur `channels.irc.enabled=false` kecuali egress IRC langsung disetujui secara eksplisit.
- Proxy debug lokal adalah alat diagnostik dan penerusan upstream langsungnya untuk permintaan proxy dan tunnel CONNECT dinonaktifkan secara default saat mode proxy terkelola aktif; aktifkan penerusan langsung hanya untuk diagnostik lokal yang disetujui.
- WebUI lokal pengguna dan server model lokal sebaiknya dimasukkan ke daftar izin dalam kebijakan proxy operator saat diperlukan; OpenClaw tidak mengekspos bypass jaringan lokal umum untuk keduanya.
- Bypass proxy control-plane Gateway sengaja dibatasi ke URL `localhost` dan IP loopback literal. Gunakan `ws://127.0.0.1:18789`, `ws://[::1]:18789`, atau `ws://localhost:18789` untuk koneksi control-plane Gateway langsung lokal; nama host lain dirutekan seperti lalu lintas berbasis nama host biasa.
- Proxy meningkatkan cakupan untuk klien HTTP dan WebSocket JavaScript lokal proses, tetapi ini bukan sandbox jaringan tingkat OS.
- Soket mentah `net`, `tls`, dan `http2`, addon native, dan proses anak dapat melewati perutean proxy tingkat Node kecuali mereka mewarisi dan mematuhi variabel lingkungan proxy.
- IRC adalah channel TCP/TLS mentah di luar perutean proxy forward yang dikelola operator. Dalam deployment yang mewajibkan semua egress melalui proxy forward tersebut, atur `channels.irc.enabled=false` kecuali egress IRC langsung disetujui secara eksplisit.
- Proxy debug lokal adalah perkakas diagnostik dan penerusan upstream langsungnya untuk permintaan proxy serta tunnel CONNECT dinonaktifkan secara default saat mode proxy terkelola aktif; aktifkan penerusan langsung hanya untuk diagnostik lokal yang disetujui.
- WebUI lokal pengguna dan server model lokal harus dimasukkan dalam allowlist di kebijakan proxy operator bila diperlukan; OpenClaw tidak mengekspos bypass jaringan lokal umum untuk keduanya.
- Bypass proxy control-plane Gateway sengaja dibatasi ke `localhost` dan URL IP loopback literal. Gunakan `ws://127.0.0.1:18789`, `ws://[::1]:18789`, atau `ws://localhost:18789` untuk koneksi control-plane Gateway langsung lokal; hostname lain dirutekan seperti lalu lintas berbasis hostname biasa.
- OpenClaw tidak memeriksa, menguji, atau mensertifikasi kebijakan proxy Anda.
- Perlakukan perubahan kebijakan proxy sebagai perubahan operasional yang sensitif terhadap keamanan.

73
docs/id/tools/loop-detection.md
View File

@ -1,29 +1,29 @@
---
read_when:
- Seorang pengguna melaporkan bahwa agen terjebak mengulang panggilan alat
- Seorang pengguna melaporkan agen tersangkut mengulangi panggilan alat
- Anda perlu menyesuaikan perlindungan panggilan berulang
- Anda sedang mengedit kebijakan alat/runtime agen
summary: Cara mengaktifkan dan menyesuaikan pembatas pengaman yang mendeteksi loop panggilan alat berulang
title: Deteksi perulangan alat
- Anda sedang mengedit kebijakan alat/waktu jalan agen
summary: Cara mengaktifkan dan menyesuaikan pagar pengaman yang mendeteksi loop panggilan alat yang berulang
title: Deteksi loop alat
x-i18n:
generated_at: "2026-05-03T21:38:09Z"
generated_at: "2026-05-05T01:49:26Z"
model: gpt-5.5
provider: openai
source_hash: 1b3976948d5735cf08b7ce854bab048a77a778a07a9f3f66d17c15aed0d42a97
source_hash: b9221e1716d3f4c2814a4705b160253839510cd6d11fe4ccd598c67958851afb
source_path: tools/loop-detection.md
workflow: 16
---
OpenClaw dapat mencegah agen terjebak dalam pola panggilan alat yang berulang.
Pengaman ini **dinonaktifkan secara default**.
Guard ini **dinonaktifkan secara bawaan**.
Aktifkan hanya jika diperlukan, karena pengaturan yang ketat dapat memblokir panggilan berulang yang sah.
## Mengapa ini ada
- Mendeteksi urutan berulang yang tidak menghasilkan kemajuan.
- Mendeteksi loop tanpa hasil berfrekuensi tinggi (alat yang sama, input yang sama, kesalahan berulang).
- Mendeteksi pola panggilan berulang tertentu untuk alat polling yang dikenal.
- Mendeteksi urutan berulang yang tidak menghasilkan progres.
- Mendeteksi loop tanpa hasil berfrekuensi tinggi (alat yang sama, input yang sama, error berulang).
- Mendeteksi pola panggilan berulang tertentu untuk alat polling yang diketahui.
## Blok konfigurasi
@ -69,36 +69,59 @@ Override per agen (opsional):
}
```
### Perilaku field
### Perilaku bidang
- `enabled`: Sakelar utama. `false` berarti tidak ada deteksi loop yang dilakukan.
- `enabled`: Sakelar utama. `false` berarti tidak ada deteksi loop yang dijalankan.
- `historySize`: jumlah panggilan alat terbaru yang disimpan untuk analisis.
- `warningThreshold`: ambang batas sebelum mengklasifikasikan pola sebagai hanya peringatan.
- `criticalThreshold`: ambang batas untuk memblokir pola loop berulang.
- `globalCircuitBreakerThreshold`: ambang pemutus global tanpa kemajuan.
- `detectors.genericRepeat`: mendeteksi pola alat-sama + parameter-sama yang berulang.
- `detectors.knownPollNoProgress`: mendeteksi pola yang mirip polling dan dikenal tanpa perubahan status.
- `warningThreshold`: ambang sebelum mengklasifikasikan pola sebagai peringatan saja.
- `criticalThreshold`: ambang untuk memblokir pola loop berulang.
- `globalCircuitBreakerThreshold`: ambang pemutus global tanpa progres.
- `detectors.genericRepeat`: mendeteksi pola alat yang sama + parameter yang sama secara berulang.
- `detectors.knownPollNoProgress`: mendeteksi pola mirip polling yang diketahui tanpa perubahan status.
- `detectors.pingPong`: mendeteksi pola ping-pong bergantian.
Untuk `exec`, pemeriksaan tanpa kemajuan membandingkan hasil perintah yang stabil dan mengabaikan metadata runtime yang mudah berubah seperti durasi, PID, ID sesi, dan direktori kerja.
Ketika ID run tersedia, riwayat panggilan alat terbaru dievaluasi hanya di dalam run tersebut sehingga siklus Heartbeat terjadwal dan run baru tidak mewarisi hitungan loop usang dari run sebelumnya.
Untuk `exec`, pemeriksaan tanpa progres membandingkan hasil perintah yang stabil dan mengabaikan metadata runtime yang berubah-ubah seperti durasi, PID, ID sesi, dan direktori kerja.
Saat id run tersedia, riwayat panggilan alat terbaru dievaluasi hanya dalam run tersebut sehingga siklus Heartbeat terjadwal dan run baru tidak mewarisi hitungan loop usang dari run sebelumnya.
## Penyiapan yang direkomendasikan
## Penyiapan yang disarankan
- Untuk model yang lebih kecil, mulai dengan `enabled: true`, tanpa mengubah default. Model unggulan jarang memerlukan deteksi loop dan dapat membiarkannya dinonaktifkan.
- Pertahankan urutan ambang batas sebagai `warningThreshold < criticalThreshold < globalCircuitBreakerThreshold`.
- Untuk model yang lebih kecil, mulai dengan `enabled: true`, default tidak diubah. Model unggulan jarang memerlukan deteksi loop dan dapat membiarkannya dinonaktifkan.
- Pertahankan urutan ambang sebagai `warningThreshold < criticalThreshold < globalCircuitBreakerThreshold`.
- Jika terjadi positif palsu:
- naikkan `warningThreshold` dan/atau `criticalThreshold`
- (opsional) naikkan `globalCircuitBreakerThreshold`
- nonaktifkan hanya detektor yang menyebabkan masalah
- kurangi `historySize` untuk konteks historis yang tidak terlalu ketat
## Guard pasca-Compaction
Saat pelaksana menyelesaikan percobaan ulang Compaction otomatis (setelah context-overflow), guard jendela pendek diaktifkan untuk memantau beberapa panggilan alat berikutnya. Jika agen mengeluarkan triple `(toolName, args, result)` yang _sama_ beberapa kali dalam jendela tersebut, guard menyimpulkan bahwa Compaction tidak memutus loop dan membatalkan run dengan error `compaction_loop_persisted`.
Ini adalah jalur kode terpisah dari detektor `tools.loopDetection` global. Ini dapat dikonfigurasi secara independen:
```json5
{
tools: {
loopDetection: {
enabled: true, // existing master switch; set false to disable loop guards
postCompactionGuard: {
windowSize: 3, // default: 3
},
},
},
}
```
- `windowSize`: jumlah panggilan alat pasca-Compaction selama guard tetap aktif _dan_ jumlah triple (alat, argumen, hasil) identik yang memicu pembatalan.
Guard tidak pernah membatalkan saat hasil berubah, hanya saat hasil identik byte demi byte di seluruh jendela. Ini sengaja dibuat sempit: hanya terpicu segera setelah percobaan ulang Compaction.
## Log dan perilaku yang diharapkan
Ketika loop terdeteksi, OpenClaw melaporkan peristiwa loop dan memblokir atau meredam siklus alat berikutnya tergantung tingkat keparahan.
Ini melindungi pengguna dari pengeluaran token yang tak terkendali dan macet, sambil mempertahankan akses alat normal.
Saat loop terdeteksi, OpenClaw melaporkan peristiwa loop dan memblokir atau meredam siklus alat berikutnya bergantung pada tingkat keparahan.
Ini melindungi pengguna dari pemborosan token yang tidak terkendali dan kebuntuan sambil tetap mempertahankan akses alat normal.
- Utamakan peringatan dan supresi sementara terlebih dahulu.
- Utamakan peringatan dan penekanan sementara terlebih dahulu.
- Eskalasikan hanya ketika bukti berulang terkumpul.
## Catatan

138
docs/id/tools/media-overview.md
View File

@ -1,25 +1,25 @@
---
read_when:
- Mencari gambaran umum tentang kemampuan media OpenClaw
- Menentukan penyedia media mana yang akan dikonfigurasi
- Menentukan penyedia media yang akan dikonfigurasi
- Memahami cara kerja pembuatan media asinkron
sidebarTitle: Media overview
summary: Sekilas kemampuan gambar, video, musik, ucapan, dan pemahaman media
summary: Sekilas tentang kemampuan gambar, video, musik, ucapan, dan pemahaman media
title: Ikhtisar media
x-i18n:
generated_at: "2026-04-30T10:16:30Z"
generated_at: "2026-05-05T01:50:07Z"
model: gpt-5.5
provider: openai
source_hash: b9f40e4fb86832438ae99dd2dc42da93c41937541314d95486c97c210dfef508
source_hash: 1bd6b93fd79897001d24f3ba5a5c8cb9bd17281116fad17262a6389214db7059
source_path: tools/media-overview.md
workflow: 16
---
OpenClaw menghasilkan gambar, video, dan musik, memahami media masuk
(gambar, audio, video), dan mengucapkan balasan dengan text-to-speech. Semua
kemampuan media digerakkan oleh alat: agen memutuskan kapan menggunakannya
berdasarkan percakapan, dan setiap alat hanya muncul ketika setidaknya satu
penyedia pendukung telah dikonfigurasi.
(gambar, audio, video), dan mengucapkan balasan dengan lantang menggunakan text-to-speech. Semua
kemampuan media digerakkan oleh alat: agen memutuskan kapan menggunakannya berdasarkan
percakapan, dan setiap alat hanya muncul ketika setidaknya satu penyedia pendukung
dikonfigurasi.
## Kemampuan
@ -30,90 +30,92 @@ penyedia pendukung telah dikonfigurasi.
</Card>
<Card title="Pembuatan video" href="/id/tools/video-generation" icon="video">
Teks-ke-video, gambar-ke-video, dan video-ke-video melalui `video_generate`.
Asinkron — berjalan di latar belakang dan memposting hasilnya saat siap.
Asinkron — berjalan di latar belakang dan memposting hasil ketika siap.
</Card>
<Card title="Pembuatan musik" href="/id/tools/music-generation" icon="music">
Hasilkan musik atau trek audio melalui `music_generate`. Asinkron pada
penyedia bersama; jalur alur kerja ComfyUI berjalan secara sinkron.
Hasilkan musik atau trek audio melalui `music_generate`. Asinkron pada penyedia
bersama; jalur alur kerja ComfyUI berjalan secara sinkron.
</Card>
<Card title="Text-to-speech" href="/id/tools/tts" icon="microphone">
Konversi balasan keluar menjadi audio ucapan melalui alat `tts` ditambah
Konversi balasan keluar menjadi audio ucapan melalui alat `tts` plus
konfigurasi `messages.tts`. Sinkron.
</Card>
<Card title="Pemahaman media" href="/id/nodes/media-understanding" icon="eye">
Ringkas gambar, audio, dan video masuk menggunakan penyedia model
berkemampuan visi dan Plugin pemahaman media khusus.
Ringkas gambar, audio, dan video masuk menggunakan penyedia model yang mendukung
visi dan Plugin khusus pemahaman media.
</Card>
<Card title="Speech-to-text" href="/id/nodes/audio" icon="ear-listen">
Transkripsikan pesan suara masuk melalui penyedia STT batch atau STT
streaming Voice Call.
Transkripsikan pesan suara masuk melalui STT batch atau penyedia STT streaming
Panggilan Suara.
</Card>
</CardGroup>
## Matriks kemampuan penyedia
| Penyedia | Gambar | Video | Musik | TTS | STT | Suara realtime | Pemahaman media |
| ----------- | :----: | :---: | :---: | :-: | :-: | :-------------: | :-------------: |
| Alibaba | | ✓ | | | | | |
| BytePlus | | ✓ | | | | | |
| ComfyUI | ✓ | ✓ | ✓ | | | | |
| DeepInfra | ✓ | ✓ | | ✓ | ✓ | | ✓ |
| Deepgram | | | | | ✓ | ✓ | |
| ElevenLabs | | | | ✓ | ✓ | | |
| fal | ✓ | ✓ | | | | | |
| Google | ✓ | ✓ | ✓ | ✓ | | ✓ | ✓ |
| Gradium | | | | ✓ | | | |
| Local CLI | | | | ✓ | | | |
| Microsoft | | | | ✓ | | | |
| MiniMax | ✓ | ✓ | ✓ | ✓ | | | |
| Mistral | | | | | ✓ | | |
| OpenAI | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ |
| OpenRouter | ✓ | ✓ | | ✓ | | | ✓ |
| Qwen | | ✓ | | | | | |
| Runway | | ✓ | | | | | |
| SenseAudio | | | | | ✓ | | |
| Together | | ✓ | | | | | |
| Vydra | ✓ | ✓ | | ✓ | | | |
| xAI | ✓ | ✓ | | ✓ | ✓ | | ✓ |
| Xiaomi MiMo | ✓ | | | ✓ | | | ✓ |
| ----------- | :----: | :---: | :---: | :-: | :-: | :-------------: | :--------------: |
| Alibaba | | ✓ | | | | | |
| BytePlus | | ✓ | | | | | |
| ComfyUI | ✓ | ✓ | ✓ | | | | |
| DeepInfra | ✓ | ✓ | | ✓ | ✓ | | ✓ |
| Deepgram | | | | | ✓ | ✓ | |
| ElevenLabs | | | | ✓ | ✓ | | |
| fal | ✓ | ✓ | | | | | |
| Google | ✓ | ✓ | ✓ | ✓ | | ✓ | ✓ |
| Gradium | | | | ✓ | | | |
| Local CLI | | | | ✓ | | | |
| Microsoft | | | | ✓ | | | |
| MiniMax | ✓ | ✓ | ✓ | ✓ | | | |
| Mistral | | | | | ✓ | | |
| OpenAI | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ |
| OpenRouter | ✓ | ✓ | | ✓ | | | ✓ |
| Qwen | | ✓ | | | | | |
| Runway | | ✓ | | | | | |
| SenseAudio | | | | | ✓ | | |
| Together | | ✓ | | | | | |
| Vydra | ✓ | ✓ | | ✓ | | | |
| xAI | ✓ | ✓ | | ✓ | ✓ | | ✓ |
| Xiaomi MiMo | ✓ | | | ✓ | | | ✓ |
<Note>
Pemahaman media menggunakan model berkemampuan visi atau berkemampuan audio apa pun yang terdaftar
Pemahaman media menggunakan model apa pun yang mendukung visi atau audio yang terdaftar
dalam konfigurasi penyedia Anda. Matriks di atas mencantumkan penyedia dengan dukungan
pemahaman media khusus; sebagian besar penyedia LLM multimodal (Anthropic, Google,
khusus pemahaman media; sebagian besar penyedia LLM multimodal (Anthropic, Google,
OpenAI, dll.) juga dapat memahami media masuk ketika dikonfigurasi sebagai model
balasan aktif.
</Note>
## Asinkron vs sinkron
| Kemampuan | Mode | Alasan |
| --------------- | --------- | ----------------------------------------------------------------- |
| Gambar | Sinkron | Respons penyedia kembali dalam hitungan detik; selesai sebaris dengan balasan. |
| Text-to-speech | Sinkron | Respons penyedia kembali dalam hitungan detik; dilampirkan ke audio balasan. |
| Video | Asinkron | Pemrosesan penyedia memerlukan 30 dtk hingga beberapa menit. |
| Musik (bersama) | Asinkron | Karakteristik pemrosesan penyedia sama seperti video. |
| Musik (ComfyUI) | Sinkron | Alur kerja lokal berjalan sebaris terhadap server ComfyUI yang dikonfigurasi. |
| Kemampuan | Mode | Alasan |
| --------------- | ---------- | ------------------------------------------------------------------ |
| Gambar | Sinkron | Respons penyedia kembali dalam hitungan detik; selesai sebaris dengan balasan. |
| Text-to-speech | Sinkron | Respons penyedia kembali dalam hitungan detik; dilampirkan ke audio balasan. |
| Video | Asinkron | Pemrosesan penyedia memerlukan 30 d hingga beberapa menit. |
| Musik (bersama) | Asinkron | Karakteristik pemrosesan penyedia sama seperti video. |
| Musik (ComfyUI) | Sinkron | Alur kerja lokal berjalan sebaris terhadap server ComfyUI yang dikonfigurasi. |
Untuk alat asinkron, OpenClaw mengirimkan permintaan ke penyedia, segera mengembalikan
id tugas, dan melacak pekerjaan di ledger tugas. Agen terus merespons pesan lain
selama pekerjaan berjalan. Ketika penyedia selesai, OpenClaw membangunkan agen agar
dapat memposting media yang sudah selesai kembali ke saluran asli.
id tugas, dan melacak pekerjaan di buku besar tugas. Agen terus
merespons pesan lain saat pekerjaan berjalan. Ketika penyedia selesai,
OpenClaw membangunkan agen dengan jalur media yang dihasilkan agar agen dapat memberi tahu
pengguna dan, ketika diwajibkan oleh kebijakan pengiriman sumber, meneruskan hasil melalui
alat pesan.
## Speech-to-text dan Voice Call
## Speech-to-text dan Panggilan Suara
Deepgram, DeepInfra, ElevenLabs, Mistral, OpenAI, SenseAudio, dan xAI semuanya dapat mentranskripsikan
audio masuk melalui jalur batch `tools.media.audio` ketika dikonfigurasi.
Plugin saluran yang melakukan preflight catatan suara untuk gating sebutan atau penguraian
perintah menandai lampiran yang ditranskripsikan pada konteks masuk, sehingga pass
pemahaman media bersama menggunakan kembali transkrip itu alih-alih membuat panggilan
audio masuk melalui jalur batch `tools.media.audio` saat dikonfigurasi.
Plugin kanal yang melakukan prapemeriksaan catatan suara untuk gating penyebutan atau penguraian
perintah menandai lampiran yang ditranskripsikan pada konteks masuk, sehingga proses
pemahaman media bersama menggunakan kembali transkrip tersebut alih-alih membuat panggilan
STT kedua untuk audio yang sama.
Deepgram, ElevenLabs, Mistral, OpenAI, dan xAI juga mendaftarkan penyedia STT
streaming Voice Call, sehingga audio telepon langsung dapat diteruskan ke vendor yang dipilih
tanpa menunggu rekaman selesai.
streaming Panggilan Suara, sehingga audio telepon langsung dapat diteruskan ke vendor
yang dipilih tanpa menunggu rekaman selesai.
## Pemetaan penyedia (cara vendor terbagi di berbagai permukaan)
## Pemetaan penyedia (bagaimana vendor terbagi di berbagai permukaan)
<AccordionGroup>
<Accordion title="Google">
@ -121,20 +123,20 @@ tanpa menunggu rekaman selesai.
pemahaman media.
</Accordion>
<Accordion title="OpenAI">
Permukaan gambar, video, TTS batch, STT batch, STT streaming Voice Call, suara
realtime backend, dan embedding memori.
Permukaan gambar, video, TTS batch, STT batch, STT streaming Panggilan Suara,
suara realtime backend, dan embedding memori.
</Accordion>
<Accordion title="DeepInfra">
Routing chat/model, pembuatan/pengeditan gambar, teks-ke-video, TTS batch,
Chat/perutean model, pembuatan/pengeditan gambar, teks-ke-video, TTS batch,
STT batch, pemahaman media gambar, dan permukaan embedding memori.
Model rerank/klasifikasi/deteksi-objek native DeepInfra tidak
didaftarkan hingga OpenClaw memiliki kontrak penyedia khusus untuk
kategori tersebut.
Model rerank/klasifikasi/deteksi objek native DeepInfra tidak
didaftarkan sampai OpenClaw memiliki kontrak penyedia khusus untuk kategori
tersebut.
</Accordion>
<Accordion title="xAI">
Gambar, video, pencarian, eksekusi kode, TTS batch, STT batch, dan STT streaming Voice
Call. Suara xAI Realtime adalah kemampuan upstream tetapi belum
didaftarkan di OpenClaw hingga kontrak suara realtime bersama dapat
Gambar, video, pencarian, eksekusi kode, TTS batch, STT batch, dan STT streaming
Panggilan Suara. Suara Realtime xAI adalah kemampuan upstream tetapi
tidak didaftarkan di OpenClaw sampai kontrak suara realtime bersama dapat
merepresentasikannya.
</Accordion>
</AccordionGroup>

201
docs/id/tools/music-generation.md
View File

@ -7,40 +7,41 @@ sidebarTitle: Music generation
summary: Hasilkan musik melalui music_generate di berbagai alur kerja Google Lyria, MiniMax, dan ComfyUI
title: Pembuatan musik
x-i18n:
generated_at: "2026-05-02T09:34:54Z"
generated_at: "2026-05-05T01:50:12Z"
model: gpt-5.5
provider: openai
source_hash: 9199afe17b2641efb1a7523c651724af9c312c1415c7e60ca736341699f6bc26
source_hash: 0e14a5a10dd485c2d3dbbd23a0fc2c12de500d9f7bfb7db471c27ed2a99ad650
source_path: tools/music-generation.md
workflow: 16
---
Alat `music_generate` memungkinkan agen membuat musik atau audio melalui
Tool `music_generate` memungkinkan agen membuat musik atau audio melalui
kapabilitas pembuatan musik bersama dengan penyedia yang dikonfigurasi — Google,
MiniMax, dan ComfyUI yang dikonfigurasi alur kerja saat ini.
MiniMax, dan ComfyUI yang dikonfigurasi lewat alur kerja saat ini.
Untuk eksekusi agen yang didukung sesi, OpenClaw memulai pembuatan musik sebagai
Untuk eksekusi agen berbasis sesi, OpenClaw memulai pembuatan musik sebagai
tugas latar belakang, melacaknya di ledger tugas, lalu membangunkan agen lagi
ketika trek siap agar agen dapat memposting audio selesai kembali ke
kanal asli.
saat trek sudah siap agar agen dapat memberi tahu pengguna dan melampirkan
audio yang selesai. Di chat grup/channel yang menggunakan pengiriman terlihat
hanya melalui tool pesan, agen meneruskan hasil melalui tool pesan.
<Note>
Alat bersama bawaan hanya muncul saat setidaknya satu penyedia pembuatan musik
tersedia. Jika Anda tidak melihat `music_generate` di alat agen Anda,
konfigurasikan `agents.defaults.musicGenerationModel` atau siapkan
kunci API penyedia.
Tool bersama bawaan hanya muncul ketika setidaknya satu penyedia pembuatan
musik tersedia. Jika Anda tidak melihat `music_generate` di tool agen Anda,
konfigurasikan `agents.defaults.musicGenerationModel` atau siapkan kunci API
penyedia.
</Note>
## Mulai cepat
<Tabs>
<Tab title="Shared provider-backed">
<Tab title="Didukung penyedia bersama">
<Steps>
<Step title="Configure auth">
<Step title="Konfigurasikan autentikasi">
Tetapkan kunci API untuk setidaknya satu penyedia — misalnya
`GEMINI_API_KEY` atau `MINIMAX_API_KEY`.
</Step>
<Step title="Pick a default model (optional)">
<Step title="Pilih model default (opsional)">
```json5
{
agents: {
@ -53,30 +54,30 @@ kunci API penyedia.
}
```
</Step>
<Step title="Ask the agent">
<Step title="Minta agen">
_"Generate an upbeat synthpop track about a night drive through a
neon city."_
Agen memanggil `music_generate` secara otomatis. Tidak perlu
daftar izin alat.
daftar izin tool.
</Step>
</Steps>
Untuk konteks sinkron langsung tanpa eksekusi agen yang didukung sesi,
alat bawaan tetap kembali ke pembuatan inline dan mengembalikan
jalur media akhir dalam hasil alat.
Untuk konteks sinkron langsung tanpa eksekusi agen berbasis sesi,
tool bawaan tetap menggunakan fallback ke pembuatan inline dan
mengembalikan jalur media akhir dalam hasil tool.
</Tab>
<Tab title="ComfyUI workflow">
<Tab title="Alur kerja ComfyUI">
<Steps>
<Step title="Configure the workflow">
<Step title="Konfigurasikan alur kerja">
Konfigurasikan `plugins.entries.comfy.config.music` dengan JSON
alur kerja dan node prompt/output.
alur kerja serta node prompt/output.
</Step>
<Step title="Cloud auth (optional)">
<Step title="Autentikasi cloud (opsional)">
Untuk Comfy Cloud, tetapkan `COMFY_API_KEY` atau `COMFY_CLOUD_API_KEY`.
</Step>
<Step title="Call the tool">
<Step title="Panggil tool">
```text
/tool music_generate prompt="Warm ambient synth loop with soft tape texture"
```
@ -97,31 +98,31 @@ Generate an energetic chiptune loop about launching a rocket at sunrise.
## Penyedia yang didukung
| Penyedia | Model default | Input referensi | Kontrol yang didukung | Auth |
| -------- | ---------------------- | ---------------- | --------------------------------------------------------- | -------------------------------------- |
| ComfyUI | `workflow` | Hingga 1 gambar | Musik atau audio yang ditentukan alur kerja | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` |
| Google | `lyria-3-clip-preview` | Hingga 10 gambar | `lyrics`, `instrumental`, `format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` |
| MiniMax | `music-2.6` | Tidak ada | `lyrics`, `instrumental`, `durationSeconds`, `format=mp3` | `MINIMAX_API_KEY` atau OAuth MiniMax |
| Penyedia | Model default | Input referensi | Kontrol yang didukung | Autentikasi |
| -------- | ---------------------- | ---------------- | ------------------------------------------------------- | -------------------------------------- |
| ComfyUI | `workflow` | Hingga 1 gambar | Musik atau audio yang ditentukan alur kerja | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` |
| Google | `lyria-3-clip-preview` | Hingga 10 gambar | `lyrics`, `instrumental`, `format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` |
| MiniMax | `music-2.6` | Tidak ada | `lyrics`, `instrumental`, `durationSeconds`, `format=mp3` | `MINIMAX_API_KEY` atau OAuth MiniMax |
### Matriks kapabilitas
Kontrak mode eksplisit yang digunakan oleh `music_generate`, pengujian kontrak, dan
sweep live bersama:
Kontrak mode eksplisit yang digunakan oleh `music_generate`, pengujian
kontrak, dan sweep live bersama:
| Penyedia | `generate` | `edit` | Batas edit | Lane live bersama |
| -------- | :--------: | :----: | ---------- | ------------------------------------------------------------------------- |
| ComfyUI | ✓ | ✓ | 1 gambar | Tidak dalam sweep bersama; dicakup oleh `extensions/comfy/comfy.live.test.ts` |
| Google | ✓ | ✓ | 10 gambar | `generate`, `edit` |
| MiniMax | ✓ | — | Tidak ada | `generate` |
| Penyedia | `generate` | `edit` | Batas edit | Lane live bersama |
| -------- | :--------: | :----: | ---------- | ------------------------------------------------------------------------ |
| ComfyUI | ✓ | ✓ | 1 gambar | Tidak ada dalam sweep bersama; dicakup oleh `extensions/comfy/comfy.live.test.ts` |
| Google | ✓ | ✓ | 10 gambar | `generate`, `edit` |
| MiniMax | ✓ | — | Tidak ada | `generate` |
Gunakan `action: "list"` untuk memeriksa penyedia dan model bersama yang tersedia saat
runtime:
Gunakan `action: "list"` untuk memeriksa penyedia dan model bersama yang
tersedia saat runtime:
```text
/tool music_generate action=list
```
Gunakan `action: "status"` untuk memeriksa tugas musik aktif yang didukung sesi:
Gunakan `action: "status"` untuk memeriksa tugas musik berbasis sesi yang aktif:
```text
/tool music_generate action=status
@ -133,7 +134,7 @@ Contoh pembuatan langsung:
/tool music_generate prompt="Dreamy lo-fi hip hop with vinyl texture and gentle rain" instrumental=true
```
## Parameter alat
## Parameter tool
<ParamField path="prompt" type="string" required>
Prompt pembuatan musik. Wajib untuk `action: "generate"`.
@ -146,65 +147,56 @@ Contoh pembuatan langsung:
`comfy/workflow`).
</ParamField>
<ParamField path="lyrics" type="string">
Lirik opsional saat penyedia mendukung input lirik eksplisit.
Lirik opsional ketika penyedia mendukung input lirik eksplisit.
</ParamField>
<ParamField path="instrumental" type="boolean">
Minta output instrumental saja saat penyedia mendukungnya.
Minta output hanya instrumental ketika penyedia mendukungnya.
</ParamField>
<ParamField path="image" type="string">
Jalur atau URL gambar referensi tunggal.
Satu jalur atau URL gambar referensi.
</ParamField>
<ParamField path="images" type="string[]">
Beberapa gambar referensi (hingga 10 pada penyedia yang mendukung).
</ParamField>
<ParamField path="durationSeconds" type="number">
Durasi target dalam detik saat penyedia mendukung petunjuk durasi.
Durasi target dalam detik ketika penyedia mendukung petunjuk durasi.
</ParamField>
<ParamField path="format" type='"mp3" | "wav"'>
Petunjuk format output saat penyedia mendukungnya.
Petunjuk format output ketika penyedia mendukungnya.
</ParamField>
<ParamField path="filename" type="string">Petunjuk nama file output.</ParamField>
<ParamField path="timeoutMs" type="number">Timeout permintaan penyedia opsional dalam milidetik. Nilai di bawah 10000ms dinaikkan ke 10000ms dan dilaporkan dalam hasil alat.</ParamField>
<ParamField path="timeoutMs" type="number">Timeout permintaan penyedia opsional dalam milidetik. Nilai di bawah 10000ms dinaikkan menjadi 10000ms dan dilaporkan dalam hasil tool.</ParamField>
<Note>
Tidak semua penyedia mendukung semua parameter. OpenClaw tetap memvalidasi batas
keras seperti jumlah input sebelum pengiriman. Saat penyedia mendukung
durasi tetapi menggunakan maksimum yang lebih pendek daripada nilai yang diminta, OpenClaw
membatasi ke durasi terdekat yang didukung. Petunjuk opsional yang benar-benar tidak didukung
diabaikan dengan peringatan saat penyedia atau model terpilih tidak dapat mematuhinya.
Hasil alat melaporkan pengaturan yang diterapkan; `details.normalization`
mencatat pemetaan apa pun dari yang diminta ke yang diterapkan.
Tidak semua penyedia mendukung semua parameter. OpenClaw tetap memvalidasi
batas keras seperti jumlah input sebelum pengiriman. Ketika penyedia mendukung
durasi tetapi menggunakan maksimum yang lebih pendek dari nilai yang diminta,
OpenClaw membatasi ke durasi terdekat yang didukung. Petunjuk opsional yang
benar-benar tidak didukung diabaikan dengan peringatan ketika penyedia atau
model yang dipilih tidak dapat memenuhinya. Hasil tool melaporkan pengaturan
yang diterapkan; `details.normalization` mencatat pemetaan dari yang diminta
ke yang diterapkan.
</Note>
## Perilaku asinkron
Pembuatan musik yang didukung sesi berjalan sebagai tugas latar belakang:
Pembuatan musik berbasis sesi berjalan sebagai tugas latar belakang:
- **Tugas latar belakang:** `music_generate` membuat tugas latar belakang, segera mengembalikan
respons mulai/tugas, dan memposting trek yang selesai nanti dalam
pesan agen lanjutan.
- **Pencegahan duplikat:** saat tugas berstatus `queued` atau `running`, panggilan
`music_generate` berikutnya dalam sesi yang sama mengembalikan status tugas, bukan
memulai pembuatan lain. Gunakan `action: "status"` untuk memeriksa secara eksplisit.
- **Pencarian status:** `openclaw tasks list` atau `openclaw tasks show <taskId>`
memeriksa status antre, berjalan, dan terminal.
- **Bangun saat selesai:** OpenClaw menyuntikkan peristiwa penyelesaian internal kembali
ke sesi yang sama agar model dapat menulis tindak lanjut yang terlihat pengguna
sendiri.
- **Petunjuk prompt:** giliran pengguna/manual berikutnya dalam sesi yang sama mendapatkan petunjuk
runtime kecil saat tugas musik sudah berjalan, sehingga model tidak
memanggil `music_generate` lagi secara membuta.
- **Fallback tanpa sesi:** konteks langsung/lokal tanpa sesi agen nyata
berjalan inline dan mengembalikan hasil audio akhir dalam giliran yang sama.
- **Tugas latar belakang:** `music_generate` membuat tugas latar belakang, segera mengembalikan respons dimulai/tugas, dan memposting trek yang selesai nanti dalam pesan lanjutan agen.
- **Pencegahan duplikat:** saat tugas berstatus `queued` atau `running`, panggilan `music_generate` berikutnya dalam sesi yang sama mengembalikan status tugas alih-alih memulai pembuatan lain. Gunakan `action: "status"` untuk memeriksa secara eksplisit.
- **Pencarian status:** `openclaw tasks list` atau `openclaw tasks show <taskId>` memeriksa status antre, berjalan, dan terminal.
- **Wake penyelesaian:** OpenClaw menyuntikkan event penyelesaian internal kembali ke sesi yang sama sehingga model dapat menulis tindak lanjut yang terlihat oleh pengguna sendiri.
- **Petunjuk prompt:** giliran pengguna/manual berikutnya dalam sesi yang sama mendapatkan petunjuk runtime kecil saat tugas musik sudah berjalan, sehingga model tidak memanggil `music_generate` lagi secara buta.
- **Fallback tanpa sesi:** konteks langsung/lokal tanpa sesi agen nyata berjalan inline dan mengembalikan hasil audio akhir pada giliran yang sama.
### Siklus hidup tugas
| Status | Makna |
| ----------- | ---------------------------------------------------------------------------------------------- |
| `queued` | Tugas dibuat, menunggu penyedia menerimanya. |
| `running` | Penyedia sedang memproses (biasanya 30 detik hingga 3 menit tergantung penyedia dan durasi). |
| `running` | Penyedia sedang memproses (biasanya 30 detik hingga 3 menit tergantung penyedia dan durasi). |
| `succeeded` | Trek siap; agen bangun dan mempostingnya ke percakapan. |
| `failed` | Kesalahan penyedia atau timeout; agen bangun dengan detail kesalahan. |
| `failed` | Kesalahan atau timeout penyedia; agen bangun dengan detail kesalahan. |
Periksa status dari CLI:
@ -235,58 +227,56 @@ openclaw tasks cancel <taskId>
OpenClaw mencoba penyedia dalam urutan ini:
1. Parameter `model` dari panggilan alat (jika agen menentukannya).
1. Parameter `model` dari panggilan tool (jika agen menentukannya).
2. `musicGenerationModel.primary` dari konfigurasi.
3. `musicGenerationModel.fallbacks` sesuai urutan.
4. Deteksi otomatis hanya menggunakan default penyedia yang didukung auth:
3. `musicGenerationModel.fallbacks` secara berurutan.
4. Deteksi otomatis hanya menggunakan default penyedia yang didukung autentikasi:
- penyedia default saat ini terlebih dahulu;
- penyedia pembuatan musik terdaftar yang tersisa dalam urutan id penyedia.
- penyedia pembuatan musik terdaftar lainnya dalam urutan id penyedia.
Jika penyedia gagal, kandidat berikutnya dicoba secara otomatis. Jika semua
gagal, kesalahan menyertakan detail dari setiap percobaan.
gagal, kesalahan mencakup detail dari setiap percobaan.
Tetapkan `agents.defaults.mediaGenerationAutoProviderFallback: false` untuk hanya menggunakan
entri `model`, `primary`, dan `fallbacks` eksplisit.
Tetapkan `agents.defaults.mediaGenerationAutoProviderFallback: false` untuk hanya menggunakan entri `model`, `primary`, dan `fallbacks` eksplisit.
## Catatan penyedia
<AccordionGroup>
<Accordion title="ComfyUI">
Digerakkan alur kerja dan bergantung pada grafik yang dikonfigurasi plus pemetaan node
untuk bidang prompt/output. Plugin `comfy` bawaan terhubung ke
alat `music_generate` bersama melalui registry penyedia pembuatan musik.
Digerakkan oleh alur kerja dan bergantung pada graph yang dikonfigurasi
ditambah pemetaan node untuk field prompt/output. Plugin `comfy` bawaan
terhubung ke tool bersama `music_generate` melalui registry penyedia
pembuatan musik.
</Accordion>
<Accordion title="Google (Lyria 3)">
Menggunakan pembuatan batch Lyria 3. Alur bawaan saat ini mendukung
prompt, teks lirik opsional, dan gambar referensi opsional.
</Accordion>
<Accordion title="MiniMax">
Menggunakan endpoint batch `music_generation`. Mendukung prompt, lirik opsional,
mode instrumental, pengarah durasi, dan output mp3 melalui
auth kunci API `minimax` atau OAuth `minimax-portal`.
Menggunakan endpoint batch `music_generation`. Mendukung prompt, lirik
opsional, mode instrumental, pengarahan durasi, dan output mp3 melalui
autentikasi kunci API `minimax` atau OAuth `minimax-portal`.
</Accordion>
</AccordionGroup>
## Memilih jalur yang tepat
- **Didukung penyedia bersama** saat Anda menginginkan pemilihan model, failover
penyedia, dan alur tugas/status asinkron bawaan.
- **Jalur Plugin (ComfyUI)** saat Anda membutuhkan grafik alur kerja kustom atau
penyedia yang bukan bagian dari kapabilitas musik bawaan bersama.
- **Didukung penyedia bersama** saat Anda menginginkan pemilihan model, failover penyedia, dan alur tugas/status asinkron bawaan.
- **Jalur Plugin (ComfyUI)** saat Anda memerlukan graph alur kerja kustom atau penyedia yang bukan bagian dari kapabilitas musik bawaan bersama.
Jika Anda men-debug perilaku khusus ComfyUI, lihat
[ComfyUI](/id/providers/comfy). Jika Anda men-debug perilaku penyedia bersama,
mulailah dengan [Google (Gemini)](/id/providers/google) atau
Jika Anda sedang men-debug perilaku khusus ComfyUI, lihat
[ComfyUI](/id/providers/comfy). Jika Anda sedang men-debug perilaku penyedia
bersama, mulai dengan [Google (Gemini)](/id/providers/google) atau
[MiniMax](/id/providers/minimax).
## Mode kapabilitas penyedia
Kontrak pembuatan musik bersama mendukung deklarasi mode eksplisit:
- `generate` untuk pembuatan berbasis prompt saja.
- `edit` saat permintaan menyertakan satu atau beberapa gambar referensi.
- `generate` untuk pembuatan hanya prompt.
- `edit` ketika permintaan menyertakan satu atau beberapa gambar referensi.
Implementasi penyedia baru sebaiknya memilih blok mode eksplisit:
Implementasi penyedia baru sebaiknya mengutamakan blok mode eksplisit:
```typescript
capabilities: {
@ -304,11 +294,11 @@ capabilities: {
}
```
Bidang datar lama seperti `maxInputImages`, `supportsLyrics`, dan
Field datar lama seperti `maxInputImages`, `supportsLyrics`, dan
`supportsFormat` **tidak** cukup untuk mengiklankan dukungan edit. Penyedia
harus mendeklarasikan `generate` dan `edit` secara eksplisit agar pengujian live, pengujian kontrak,
dan alat `music_generate` bersama dapat memvalidasi dukungan mode
secara deterministik.
harus mendeklarasikan `generate` dan `edit` secara eksplisit agar pengujian
live, pengujian kontrak, dan tool bersama `music_generate` dapat memvalidasi
dukungan mode secara deterministik.
## Pengujian live
@ -324,10 +314,10 @@ Wrapper repo:
pnpm test:live:media music
```
File live ini memuat variabel env penyedia yang hilang dari `~/.profile`, lebih memilih
kunci API live/env di atas profil auth tersimpan secara default, dan menjalankan cakupan
`generate` serta `edit` yang dideklarasikan saat penyedia mengaktifkan mode edit.
Cakupan saat ini:
File live ini memuat var env penyedia yang hilang dari `~/.profile`, secara
default mengutamakan kunci API live/env sebelum profil autentikasi tersimpan,
dan menjalankan cakupan `generate` serta `edit` yang dideklarasikan saat
penyedia mengaktifkan mode edit. Cakupan saat ini:
- `google`: `generate` plus `edit`
- `minimax`: hanya `generate`
@ -339,11 +329,12 @@ Cakupan live opt-in untuk jalur musik ComfyUI bawaan:
OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts
```
File live Comfy juga mencakup alur kerja gambar dan video comfy ketika bagian-bagian tersebut dikonfigurasi.
File uji langsung Comfy juga mencakup alur kerja gambar dan video comfy ketika
bagian-bagian tersebut dikonfigurasi.
## Terkait
- [Tugas latar belakang](/id/automation/tasks) — pelacakan tugas untuk proses `music_generate` terpisah
- [Tugas latar belakang](/id/automation/tasks) — pelacakan tugas untuk eksekusi `music_generate` yang berjalan terpisah
- [ComfyUI](/id/providers/comfy)
- [Referensi konfigurasi](/id/gateway/config-agents#agent-defaults) — konfigurasi `musicGenerationModel`
- [Google (Gemini)](/id/providers/google)

596
docs/id/tools/plugin.md
View File

@ -4,60 +4,59 @@ read_when:
- Memahami aturan penemuan dan pemuatan Plugin
- Bekerja dengan bundel Plugin yang kompatibel dengan Codex/Claude
sidebarTitle: Install and Configure
summary: Instal, konfigurasi, dan kelola Plugin OpenClaw
summary: Instal, konfigurasikan, dan kelola Plugin OpenClaw
title: Plugin
x-i18n:
generated_at: "2026-05-03T21:38:28Z"
generated_at: "2026-05-05T01:50:37Z"
model: gpt-5.5
provider: openai
source_hash: 30e3cffc15c5c52dd539e21103c207c9e38955f9fd3acd561a52964eefafb8f0
source_hash: 1de640f7766a6b312a2385075ae1abdb19f5c2afcb0e7063eba0d3edde697004
source_path: tools/plugin.md
workflow: 16
---
Plugin memperluas OpenClaw dengan kemampuan baru: channel, penyedia model,
harness agen, alat, Skills, ucapan, transkripsi realtime, suara realtime,
pemahaman media, pembuatan gambar, pembuatan video, pengambilan web, pencarian
web, dan lainnya. Beberapa plugin bersifat **inti** (dikirim bersama OpenClaw),
sementara yang lain bersifat **eksternal**. Sebagian besar plugin eksternal
dipublikasikan dan ditemukan melalui [ClawHub](/id/tools/clawhub). Npm tetap
didukung untuk pemasangan langsung dan untuk kumpulan sementara paket plugin
milik OpenClaw hingga migrasi tersebut selesai.
harness agen, alat, Skills, speech, transkripsi realtime, suara realtime,
pemahaman media, pembuatan gambar, pembuatan video, web fetch, web
search, dan lainnya. Sebagian plugin bersifat **core** (dikirim bersama OpenClaw), sebagian lainnya
bersifat **eksternal**. Sebagian besar plugin eksternal dipublikasikan dan ditemukan melalui
[ClawHub](/id/tools/clawhub). Npm tetap didukung untuk instalasi langsung dan untuk
sekumpulan sementara paket plugin milik OpenClaw selama migrasi tersebut selesai.
## Mulai cepat
Untuk contoh pemasangan, daftar, pencopotan, pembaruan, dan penerbitan yang
dapat disalin-tempel, lihat [Kelola plugin](/id/plugins/manage-plugins).
Untuk contoh instalasi salin-tempel, daftar, hapus instalasi, pembaruan, dan publikasi, lihat
[Kelola plugin](/id/plugins/manage-plugins).
<Steps>
<Step title="Lihat apa yang dimuat">
<Step title="See what is loaded">
```bash
openclaw plugins list
```
</Step>
<Step title="Pasang plugin">
<Step title="Install a plugin">
```bash
# Cari plugin ClawHub
# Search ClawHub plugins
openclaw plugins search "calendar"
# Dari ClawHub
# From ClawHub
openclaw plugins install clawhub:openclaw-codex-app-server
# Dari npm
# From npm
openclaw plugins install npm:@acme/openclaw-plugin
# Dari git
# From git
openclaw plugins install git:github.com/acme/openclaw-plugin@v1.0.0
# Dari direktori atau arsip lokal
# From a local directory or archive
openclaw plugins install ./my-plugin
openclaw plugins install ./my-plugin.tgz
```
</Step>
<Step title="Mulai ulang Gateway">
<Step title="Restart the Gateway">
```bash
openclaw gateway restart
```
@ -66,29 +65,27 @@ dapat disalin-tempel, lihat [Kelola plugin](/id/plugins/manage-plugins).
</Step>
<Step title="Pengelolaan native chat">
<Step title="Chat-native management">
Dalam Gateway yang sedang berjalan, `/plugins enable` dan `/plugins disable`
khusus pemilik memicu pemuat ulang konfigurasi Gateway. Gateway memuat ulang
permukaan runtime plugin dalam proses, dan giliran agen baru membangun ulang
daftar alatnya dari registri yang telah disegarkan. `/plugins install`
mengubah kode sumber plugin, sehingga Gateway meminta mulai ulang alih-alih
berpura-pura bahwa proses saat ini dapat memuat ulang modul yang sudah
diimpor dengan aman.
khusus pemilik memicu pemuat ulang konfigurasi Gateway. Gateway memuat ulang surface runtime
plugin dalam proses, dan turn agen baru membangun ulang daftar alatnya dari
registry yang telah diperbarui. `/plugins install` mengubah kode sumber plugin, sehingga
Gateway meminta restart alih-alih berpura-pura bahwa proses saat ini dapat
memuat ulang modul yang sudah diimpor dengan aman.
</Step>
<Step title="Verifikasi plugin">
<Step title="Verify the plugin">
```bash
openclaw plugins inspect <plugin-id> --runtime --json
# Jika plugin mendaftarkan root CLI, jalankan satu perintah dari root tersebut.
# If the plugin registered a CLI root, run one command from that root.
openclaw <plugin-command> --help
```
Gunakan `--runtime` ketika Anda perlu membuktikan alat, layanan, metode
gateway, hook, atau perintah CLI milik plugin yang terdaftar. `inspect` biasa
adalah pemeriksaan manifes/registri dingin dan sengaja menghindari pengimporan
runtime plugin.
Gunakan `--runtime` ketika Anda perlu membuktikan alat, layanan, metode gateway,
hook, atau perintah CLI milik plugin yang terdaftar. `inspect` biasa adalah pemeriksaan
manifest/registry dingin dan sengaja menghindari impor runtime plugin.
</Step>
</Steps>
@ -101,93 +98,85 @@ Jika Anda lebih memilih kontrol native chat, aktifkan `commands.plugins: true` d
/plugin enable <plugin-id>
```
Jalur pemasangan menggunakan resolver yang sama dengan CLI: path/arsip lokal,
`clawhub:<pkg>` eksplisit, `npm:<pkg>` eksplisit, `git:<repo>` eksplisit, atau
spesifikasi paket polos melalui npm.
Jalur instalasi menggunakan resolver yang sama dengan CLI: path/arsip lokal, eksplisit
`clawhub:<pkg>`, eksplisit `npm:<pkg>`, eksplisit `git:<repo>`, atau spesifikasi paket
polos melalui npm.
Jika konfigurasi tidak valid, pemasangan biasanya gagal tertutup dan mengarahkan
Anda ke `openclaw doctor --fix`. Satu-satunya pengecualian pemulihan adalah jalur
pemasangan ulang plugin bawaan yang sempit untuk plugin yang memilih ikut
Jika konfigurasi tidak valid, instalasi biasanya gagal tertutup dan mengarahkan Anda ke
`openclaw doctor --fix`. Satu-satunya pengecualian pemulihan adalah jalur instalasi ulang
plugin bundel yang sempit untuk plugin yang ikut serta dalam
`openclaw.install.allowInvalidConfigRecovery`.
Selama startup Gateway, konfigurasi plugin yang tidak valid gagal tertutup seperti
konfigurasi tidak valid lainnya. Jalankan `openclaw doctor --fix` untuk
mengarantina konfigurasi plugin yang bermasalah dengan menonaktifkan entri plugin
tersebut dan menghapus payload konfigurasi yang tidak valid; cadangan konfigurasi
Selama startup Gateway, konfigurasi plugin yang tidak valid gagal tertutup seperti konfigurasi
tidak valid lainnya. Jalankan `openclaw doctor --fix` untuk mengarantina konfigurasi plugin yang buruk dengan
menonaktifkan entri plugin tersebut dan menghapus payload konfigurasi tidak validnya; cadangan konfigurasi
normal mempertahankan nilai sebelumnya.
Ketika konfigurasi channel merujuk ke plugin yang tidak lagi dapat ditemukan tetapi
id plugin usang yang sama tetap ada dalam konfigurasi plugin atau catatan
pemasangan, startup Gateway mencatat peringatan dan melewati channel tersebut
alih-alih memblokir semua channel lain.
Jalankan `openclaw doctor --fix` untuk menghapus entri channel/plugin yang usang;
kunci channel yang tidak dikenal tanpa bukti plugin usang tetap gagal divalidasi
agar salah ketik tetap terlihat.
Jika `plugins.enabled: false` disetel, referensi plugin usang diperlakukan sebagai
tidak aktif: startup Gateway melewati pekerjaan penemuan/pemuatan plugin dan
`openclaw doctor` mempertahankan konfigurasi plugin yang dinonaktifkan alih-alih
menghapusnya otomatis. Aktifkan kembali plugin sebelum menjalankan pembersihan
doctor jika Anda ingin id plugin usang dihapus.
Ketika konfigurasi channel merujuk ke plugin yang tidak lagi dapat ditemukan tetapi id plugin
usang yang sama tetap ada dalam konfigurasi plugin atau catatan instalasi, startup Gateway
mencatat peringatan dan melewati channel tersebut alih-alih memblokir semua channel lain.
Jalankan `openclaw doctor --fix` untuk menghapus entri channel/plugin yang usang; key
channel yang tidak dikenal tanpa bukti plugin usang tetap gagal validasi agar typo tetap
terlihat.
Jika `plugins.enabled: false` ditetapkan, referensi plugin usang diperlakukan sebagai inert:
startup Gateway melewati pekerjaan penemuan/pemuatan plugin dan `openclaw doctor` mempertahankan
konfigurasi plugin yang dinonaktifkan alih-alih menghapusnya otomatis. Aktifkan kembali plugin sebelum
menjalankan pembersihan doctor jika Anda ingin id plugin usang dihapus.
Pemasangan dependensi plugin hanya terjadi selama alur pemasangan/pembaruan
eksplisit atau perbaikan doctor. Startup Gateway, pemuatan ulang konfigurasi, dan
inspeksi runtime tidak menjalankan pengelola paket atau memperbaiki pohon
dependensi. Plugin lokal harus sudah memiliki dependensinya terpasang, sementara
plugin npm, git, dan ClawHub dipasang di bawah root plugin terkelola OpenClaw.
Dependensi npm dapat di-hoist dalam root npm terkelola OpenClaw; pemasangan/
pembaruan memindai root terkelola tersebut sebelum mempercayai dan pencopotan
menghapus paket yang dikelola npm melalui npm. Plugin eksternal dan path muat
khusus tetap harus dipasang melalui `openclaw plugins install`.
Gunakan `openclaw plugins list --json` untuk melihat `dependencyStatus` statis
untuk setiap plugin yang terlihat tanpa mengimpor kode runtime atau memperbaiki
dependensi.
Lihat [Resolusi dependensi Plugin](/id/plugins/dependency-resolution) untuk siklus
hidup saat pemasangan.
Instalasi dependensi plugin hanya terjadi selama alur instalasi/pembaruan eksplisit atau
perbaikan doctor. Startup Gateway, pemuatan ulang konfigurasi, dan inspeksi runtime tidak
menjalankan manajer paket atau memperbaiki pohon dependensi. Plugin lokal harus sudah
memiliki dependensinya terinstal, sedangkan plugin npm, git, dan ClawHub
diinstal di bawah root plugin terkelola OpenClaw. Dependensi npm dapat di-hoist
dalam root npm terkelola OpenClaw; instalasi/pembaruan memindai root terkelola tersebut sebelum
trust dan uninstall menghapus paket yang dikelola npm melalui npm. Plugin eksternal
dan path pemuatan kustom tetap harus diinstal melalui `openclaw plugins install`.
Gunakan `openclaw plugins list --json` untuk melihat `dependencyStatus` statis untuk setiap
plugin yang terlihat tanpa mengimpor kode runtime atau memperbaiki dependensi.
Lihat [Resolusi dependensi Plugin](/id/plugins/dependency-resolution) untuk
siklus hidup saat instalasi.
Untuk pemasangan npm, selector yang dapat berubah seperti `latest` atau dist-tag
diresolusi sebelum pemasangan lalu dipinkan ke versi persis yang telah diverifikasi
dalam root npm terkelola OpenClaw. Setelah npm selesai, OpenClaw memverifikasi
bahwa entri `package-lock.json` yang terpasang masih cocok dengan versi dan
integritas yang diresolusi. Jika npm menulis metadata paket yang berbeda,
pemasangan gagal dan paket terkelola di-rollback alih-alih menerima artefak
plugin yang berbeda.
Untuk instalasi npm, selector mutable seperti `latest` atau dist-tag diselesaikan
sebelum instalasi lalu dipin ke versi terverifikasi yang tepat dalam root npm
terkelola OpenClaw. Setelah npm selesai, OpenClaw memverifikasi bahwa entri
`package-lock.json` yang terinstal masih cocok dengan versi dan integritas yang diselesaikan. Jika
npm menulis metadata paket yang berbeda, instalasi gagal dan paket terkelola
di-rollback alih-alih menerima artefak plugin yang berbeda.
Checkout sumber adalah workspace pnpm. Jika Anda mengkloning OpenClaw untuk
mengutak-atik plugin bawaan, jalankan `pnpm install`; OpenClaw kemudian memuat
plugin bawaan dari `extensions/<id>` sehingga perubahan dan dependensi lokal
paket digunakan langsung.
Pemasangan root npm biasa ditujukan untuk OpenClaw terpaket, bukan pengembangan
Checkout sumber adalah workspace pnpm. Jika Anda meng-clone OpenClaw untuk mengutak-atik plugin
bundel, jalankan `pnpm install`; OpenClaw kemudian memuat plugin bundel dari
`extensions/<id>` sehingga edit dan dependensi lokal paket digunakan langsung.
Instalasi root npm biasa ditujukan untuk OpenClaw yang sudah dipaketkan, bukan pengembangan
checkout sumber.
## Jenis plugin
## Jenis Plugin
OpenClaw mengenali dua format plugin:
| Format | Cara kerjanya | Contoh |
| ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ |
| **Native** | `openclaw.plugin.json` + modul runtime; dieksekusi dalam proses | Plugin resmi, paket npm komunitas |
| **Bundle** | Tata letak kompatibel Codex/Claude/Cursor; dipetakan ke fitur OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
| **Native** | `openclaw.plugin.json` + modul runtime; berjalan dalam proses | Plugin resmi, paket npm komunitas |
| **Bundle** | Layout kompatibel Codex/Claude/Cursor; dipetakan ke fitur OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
Keduanya muncul di bawah `openclaw plugins list`. Lihat [Bundle Plugin](/id/plugins/bundles) untuk detail bundle.
Jika Anda menulis plugin native, mulai dengan [Membangun Plugin](/id/plugins/building-plugins)
dan [Ikhtisar SDK Plugin](/id/plugins/sdk-overview).
## Entry point paket
## Entrypoint paket
Paket npm plugin native harus mendeklarasikan `openclaw.extensions` dalam `package.json`.
Setiap entri harus tetap berada di dalam direktori paket dan meresolusi ke file
Setiap entri harus tetap berada di dalam direktori paket dan me-resolve ke file
runtime yang dapat dibaca, atau ke file sumber TypeScript dengan peer JavaScript
terbangun yang diinferensikan seperti `src/index.ts` ke `dist/index.js`.
Pemasangan terpaket harus mengirimkan output runtime JavaScript tersebut. Fallback
sumber TypeScript ditujukan untuk checkout sumber dan path pengembangan lokal,
bukan untuk paket npm yang dipasang ke root plugin terkelola OpenClaw.
terbangun yang disimpulkan seperti `src/index.ts` ke `dist/index.js`.
Instalasi paket harus menyertakan output runtime JavaScript tersebut. Fallback sumber
TypeScript ditujukan untuk checkout sumber dan path pengembangan lokal, bukan untuk
paket npm yang diinstal ke root plugin terkelola OpenClaw.
Gunakan `openclaw.runtimeExtensions` ketika file runtime yang dipublikasikan tidak
berada di path yang sama dengan entri sumber. Saat ada, `runtimeExtensions` harus
berisi tepat satu entri untuk setiap entri `extensions`. Daftar yang tidak cocok
membuat pemasangan dan penemuan plugin gagal alih-alih diam-diam fallback ke path
sumber. Jika Anda juga memublikasikan `openclaw.setupEntry`, gunakan
`openclaw.runtimeSetupEntry` untuk peer JavaScript terbangunnya; file tersebut
wajib ada ketika dideklarasikan.
Gunakan `openclaw.runtimeExtensions` ketika file runtime yang dipublikasikan tidak berada di
path yang sama dengan entri sumber. Jika ada, `runtimeExtensions` harus berisi
tepat satu entri untuk setiap entri `extensions`. Daftar yang tidak cocok menggagalkan instalasi dan
penemuan plugin alih-alih diam-diam fallback ke path sumber. Jika Anda juga
mempublikasikan `openclaw.setupEntry`, gunakan `openclaw.runtimeSetupEntry` untuk peer
JavaScript terbangunnya; file tersebut wajib ada saat dideklarasikan.
```json
{
@ -204,16 +193,14 @@ wajib ada ketika dideklarasikan.
### Paket npm milik OpenClaw selama migrasi
ClawHub adalah jalur distribusi utama untuk sebagian besar plugin. Rilis OpenClaw
terpaket saat ini sudah membundel banyak plugin resmi, sehingga plugin tersebut
tidak memerlukan pemasangan npm terpisah dalam penyiapan normal. Hingga setiap
plugin milik OpenClaw bermigrasi ke ClawHub, OpenClaw masih mengirimkan beberapa
paket plugin `@openclaw/*` di npm untuk pemasangan lama/khusus dan alur kerja npm
langsung.
terpaket saat ini sudah membundel banyak plugin resmi, sehingga plugin tersebut tidak memerlukan
instalasi npm terpisah dalam setup normal. Sampai setiap plugin milik OpenClaw
bermigrasi ke ClawHub, OpenClaw masih mengirimkan beberapa paket plugin `@openclaw/*` di
npm untuk instalasi lama/kustom dan workflow npm langsung.
Jika npm melaporkan paket plugin `@openclaw/*` sebagai deprecated, versi paket
tersebut berasal dari rangkaian paket eksternal yang lebih lama. Gunakan plugin
bawaan dari OpenClaw saat ini atau checkout lokal hingga paket npm yang lebih baru
dipublikasikan.
Jika npm melaporkan paket plugin `@openclaw/*` sebagai deprecated, versi paket tersebut
berasal dari rangkaian paket eksternal yang lebih lama. Gunakan plugin bundel dari
OpenClaw saat ini atau checkout lokal sampai paket npm yang lebih baru dipublikasikan.
| Plugin | Paket | Dokumentasi |
| --------------- | -------------------------- | ------------------------------------------ |
@ -231,10 +218,10 @@ dipublikasikan.
| Zalo | `@openclaw/zalo` | [Zalo](/id/channels/zalo) |
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/id/plugins/zalouser) |
### Inti (dikirim bersama OpenClaw)
### Core (dikirim bersama OpenClaw)
<AccordionGroup>
<Accordion title="Penyedia model (diaktifkan secara default)">
<Accordion title="Model providers (enabled by default)">
`anthropic`, `byteplus`, `cloudflare-ai-gateway`, `github-copilot`, `google`,
`huggingface`, `kilocode`, `kimi-coding`, `minimax`, `mistral`, `qwen`,
`moonshot`, `nvidia`, `openai`, `opencode`, `opencode-go`, `openrouter`,
@ -242,21 +229,21 @@ dipublikasikan.
`vercel-ai-gateway`, `volcengine`, `xiaomi`, `zai`
</Accordion>
<Accordion title="Plugin memori">
- `memory-core` — pencarian memori bawaan (default melalui `plugins.slots.memory`)
- `memory-lancedb` — memori jangka panjang berbasis LanceDB dengan auto-recall/capture (setel `plugins.slots.memory = "memory-lancedb"`)
<Accordion title="Memory plugins">
- `memory-core` — pencarian memori bundel (default melalui `plugins.slots.memory`)
- `memory-lancedb` — memori jangka panjang berbasis LanceDB dengan auto-recall/capture (tetapkan `plugins.slots.memory = "memory-lancedb"`)
Lihat [Memory LanceDB](/id/plugins/memory-lancedb) untuk penyiapan embedding
kompatibel OpenAI, contoh Ollama, batas recall, dan pemecahan masalah.
Lihat [Memory LanceDB](/id/plugins/memory-lancedb) untuk setup embedding
yang kompatibel dengan OpenAI, contoh Ollama, batas recall, dan pemecahan masalah.
</Accordion>
<Accordion title="Penyedia ucapan (diaktifkan secara default)">
<Accordion title="Speech providers (enabled by default)">
`elevenlabs`, `microsoft`
</Accordion>
<Accordion title="Lainnya">
- `browser` — plugin browser bawaan untuk alat browser, CLI `openclaw browser`, metode gateway `browser.request`, runtime browser, dan layanan kontrol browser default (diaktifkan secara default; nonaktifkan sebelum menggantinya)
<Accordion title="Other">
- `browser` — plugin browser bundel untuk alat browser, CLI `openclaw browser`, metode gateway `browser.request`, runtime browser, dan layanan kontrol browser default (diaktifkan secara default; nonaktifkan sebelum menggantinya)
- `copilot-proxy` — bridge VS Code Copilot Proxy (dinonaktifkan secara default)
</Accordion>
@ -280,121 +267,127 @@ Mencari plugin pihak ketiga? Lihat [Plugin Komunitas](/id/plugins/community).
}
```
| Bidang | Deskripsi |
| ---------------- | --------------------------------------------------------- |
| `enabled` | Sakelar utama (default: `true`) |
| `allow` | Daftar izin Plugin (opsional) |
| `deny` | Daftar tolak Plugin (opsional; tolak menang) |
| `load.paths` | File/direktori Plugin tambahan |
| `slots` | Pemilih slot eksklusif (mis. `memory`, `contextEngine`) |
| `entries.\<id\>` | Sakelar per-Plugin + konfigurasi |
| Bidang | Deskripsi |
| ------------------ | --------------------------------------------------------- |
| `enabled` | Toggle utama (default: `true`) |
| `allow` | Daftar allow Plugin (opsional) |
| `bundledDiscovery` | Mode penemuan plugin bawaan (`allowlist` secara default) |
| `deny` | Daftar deny Plugin (opsional; deny menang) |
| `load.paths` | File/direktori plugin tambahan |
| `slots` | Pemilih slot eksklusif (mis. `memory`, `contextEngine`) |
| `entries.\<id\>` | Toggle + konfigurasi per plugin |
`plugins.allow` bersifat eksklusif. Saat tidak kosong, hanya Plugin yang
tercantum yang dapat dimuat atau mengekspos alat, bahkan jika `tools.allow`
berisi `"*"` atau nama alat milik Plugin tertentu. Jika daftar izin alat
mereferensikan alat Plugin, tambahkan id Plugin pemilik ke `plugins.allow` atau
hapus `plugins.allow`; `openclaw doctor` memperingatkan bentuk ini.
`plugins.allow` bersifat eksklusif. Saat tidak kosong, hanya plugin yang tercantum yang dapat dimuat
atau mengekspos alat, meskipun `tools.allow` berisi `"*"` atau nama alat milik plugin tertentu. Jika daftar allow alat merujuk alat plugin, tambahkan id plugin pemilik
ke `plugins.allow` atau hapus `plugins.allow`; `openclaw doctor` memperingatkan tentang
bentuk ini.
Perubahan konfigurasi yang dibuat melalui `/plugins enable` atau
`/plugins disable` memicu pemuatan ulang Plugin Gateway di dalam proses. Giliran
agen baru membangun ulang daftar alatnya dari registri Plugin yang sudah
diperbarui. Operasi yang mengubah sumber seperti install, update, dan uninstall
tetap memulai ulang proses Gateway karena modul Plugin yang sudah diimpor tidak
dapat diganti di tempat dengan aman.
`plugins.bundledDiscovery` default ke `"allowlist"` untuk konfigurasi baru, sehingga inventaris
`plugins.allow` yang restriktif juga memblokir plugin penyedia bawaan yang tidak dicantumkan,
termasuk penemuan penyedia web-search runtime. Doctor menandai konfigurasi allowlist
restriktif lama dengan `"compat"` selama migrasi sehingga peningkatan tetap mempertahankan
perilaku penyedia bawaan lama sampai operator memilih mode yang lebih ketat.
`plugins.allow` yang kosong tetap diperlakukan sebagai tidak disetel/terbuka.
`openclaw plugins list` adalah snapshot registri/konfigurasi Plugin lokal.
Plugin `enabled` di sana berarti registri tersimpan dan konfigurasi saat ini
mengizinkan Plugin ikut berpartisipasi. Itu tidak membuktikan bahwa Gateway
jarak jauh yang sudah berjalan telah dimuat ulang atau dimulai ulang ke kode
Plugin yang sama. Pada penyiapan VPS/container dengan proses pembungkus, kirim
restart atau penulisan yang memicu pemuatan ulang ke proses
`openclaw gateway run` yang sebenarnya, atau gunakan `openclaw gateway restart`
terhadap Gateway yang sedang berjalan saat pemuatan ulang melaporkan kegagalan.
Perubahan konfigurasi yang dibuat melalui `/plugins enable` atau `/plugins disable` memicu
pemuatan ulang plugin Gateway dalam proses. Giliran agen baru membangun ulang daftar alatnya dari
registri plugin yang telah disegarkan. Operasi yang mengubah sumber seperti install,
update, dan uninstall tetap memulai ulang proses Gateway karena modul plugin yang sudah diimpor
tidak dapat diganti di tempat dengan aman.
<Accordion title="Status Plugin: dinonaktifkan vs hilang vs tidak valid">
- **Dinonaktifkan**: Plugin ada tetapi aturan pengaktifan mematikannya. Konfigurasi dipertahankan.
- **Hilang**: konfigurasi mereferensikan id Plugin yang tidak ditemukan oleh discovery.
- **Tidak valid**: Plugin ada tetapi konfigurasinya tidak cocok dengan skema yang dideklarasikan. Startup Gateway hanya melewati Plugin tersebut; `openclaw doctor --fix` dapat mengarantina entri yang tidak valid dengan menonaktifkannya dan menghapus payload konfigurasinya.
`openclaw plugins list` adalah snapshot registri/konfigurasi plugin lokal. Plugin
`enabled` di sana berarti registri tersimpan dan konfigurasi saat ini mengizinkan
plugin untuk berpartisipasi. Itu tidak membuktikan bahwa Gateway jarak jauh yang sudah berjalan
telah dimuat ulang atau dimulai ulang ke kode plugin yang sama. Pada pengaturan VPS/kontainer
dengan proses wrapper, kirim restart atau penulisan pemicu reload ke proses
`openclaw gateway run` yang sebenarnya, atau gunakan `openclaw gateway restart` terhadap
Gateway yang berjalan saat reload melaporkan kegagalan.
<Accordion title="Plugin states: disabled vs missing vs invalid">
- **Dinonaktifkan**: plugin ada tetapi aturan enablement mematikannya. Konfigurasi dipertahankan.
- **Hilang**: konfigurasi merujuk id plugin yang tidak ditemukan oleh penemuan.
- **Tidak valid**: plugin ada tetapi konfigurasinya tidak cocok dengan skema yang dideklarasikan. Startup Gateway hanya melewati plugin tersebut; `openclaw doctor --fix` dapat mengarantina entri yang tidak valid dengan menonaktifkannya dan menghapus payload konfigurasinya.
</Accordion>
## Discovery dan presedensi
## Penemuan dan presedensi
OpenClaw memindai Plugin dalam urutan ini (kecocokan pertama menang):
OpenClaw memindai plugin dalam urutan ini (kecocokan pertama menang):
<Steps>
<Step title="Path konfigurasi">
`plugins.load.paths` — path file atau direktori eksplisit. Path yang
menunjuk kembali ke direktori Plugin bawaan paket OpenClaw sendiri diabaikan;
<Step title="Config paths">
`plugins.load.paths` — path file atau direktori eksplisit. Path yang menunjuk
kembali ke direktori plugin bawaan paket milik OpenClaw sendiri diabaikan;
jalankan `openclaw doctor --fix` untuk menghapus alias usang tersebut.
</Step>
<Step title="Plugin workspace">
<Step title="Workspace plugins">
`\<workspace\>/.openclaw/<plugin-root>/*.ts` dan `\<workspace\>/.openclaw/<plugin-root>/*/index.ts`.
</Step>
<Step title="Plugin global">
<Step title="Global plugins">
`~/.openclaw/<plugin-root>/*.ts` dan `~/.openclaw/<plugin-root>/*/index.ts`.
</Step>
<Step title="Plugin bawaan">
<Step title="Bundled plugins">
Dikirim bersama OpenClaw. Banyak yang diaktifkan secara default (penyedia model, ucapan).
Lainnya memerlukan pengaktifan eksplisit.
Lainnya memerlukan enablement eksplisit.
</Step>
</Steps>
Instalasi paket dan image Docker biasanya me-resolve Plugin bawaan dari pohon
`dist/extensions` terkompilasi. Jika direktori sumber Plugin bawaan di-bind-mount
di atas path sumber paket yang cocok, misalnya `/app/extensions/synology-chat`,
OpenClaw memperlakukan direktori sumber yang di-mount itu sebagai overlay sumber
bawaan dan menemukannya sebelum bundle `/app/dist/extensions/synology-chat`
terpaket. Ini membuat loop container maintainer tetap berjalan tanpa mengalihkan
setiap Plugin bawaan kembali ke sumber TypeScript. Set
`OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1` untuk memaksa bundle dist terpaket
Instalasi paket dan image Docker biasanya menyelesaikan plugin bawaan dari tree
`dist/extensions` yang dikompilasi. Jika direktori sumber plugin bawaan
di-bind-mount di atas path sumber paket yang cocok, misalnya
`/app/extensions/synology-chat`, OpenClaw memperlakukan direktori sumber yang dimount tersebut
sebagai overlay sumber bawaan dan menemukannya sebelum bundle paket
`/app/dist/extensions/synology-chat`. Ini menjaga loop kontainer maintainer
tetap berjalan tanpa mengalihkan setiap plugin bawaan kembali ke sumber TypeScript.
Setel `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1` untuk memaksa bundle dist paket
meskipun mount overlay sumber ada.
### Aturan pengaktifan
### Aturan enablement
- `plugins.enabled: false` menonaktifkan semua Plugin dan melewati pekerjaan discovery/muat Plugin
- `plugins.enabled: false` menonaktifkan semua plugin dan melewati pekerjaan penemuan/pemuatan plugin
- `plugins.deny` selalu menang atas allow
- `plugins.entries.\<id\>.enabled: false` menonaktifkan Plugin tersebut
- `plugins.entries.\<id\>.enabled: false` menonaktifkan plugin tersebut
- Plugin asal workspace **dinonaktifkan secara default** (harus diaktifkan secara eksplisit)
- Plugin bawaan mengikuti set default-aktif bawaan kecuali dioverride
- Slot eksklusif dapat memaksa pengaktifan Plugin yang dipilih untuk slot tersebut
- Beberapa Plugin bawaan opt-in diaktifkan secara otomatis saat konfigurasi menamai
permukaan milik Plugin, seperti referensi model penyedia, konfigurasi channel, atau runtime
- Plugin bawaan mengikuti set default-on bawaan kecuali ditimpa
- Slot eksklusif dapat memaksa pengaktifan plugin yang dipilih untuk slot tersebut
- Beberapa plugin opt-in bawaan diaktifkan secara otomatis saat konfigurasi menamai
permukaan milik plugin, seperti ref model penyedia, konfigurasi channel, atau runtime
harness
- Konfigurasi Plugin usang dipertahankan selama `plugins.enabled: false` aktif;
aktifkan kembali Plugin sebelum menjalankan pembersihan doctor jika Anda ingin id usang dihapus
- Rute Codex keluarga OpenAI menjaga batas Plugin terpisah:
`openai-codex/*` milik Plugin OpenAI, sedangkan Plugin app-server Codex bawaan
dipilih oleh `agentRuntime.id: "codex"` atau referensi model lama `codex/*`
- Konfigurasi plugin usang dipertahankan selama `plugins.enabled: false` aktif;
aktifkan kembali plugin sebelum menjalankan pembersihan doctor jika ingin id usang dihapus
- Rute Codex keluarga OpenAI menjaga batas plugin terpisah:
`openai-codex/*` milik plugin OpenAI, sedangkan plugin app-server Codex
bawaan dipilih oleh `agentRuntime.id: "codex"` atau ref model
`codex/*` lama
## Memecahkan masalah hook runtime
Jika sebuah Plugin muncul di `plugins list` tetapi efek samping atau hook
`register(api)` tidak berjalan di lalu lintas chat live, periksa ini terlebih dahulu:
Jika plugin muncul di `plugins list` tetapi efek samping atau hook `register(api)`
tidak berjalan dalam traffic chat live, periksa ini terlebih dahulu:
- Jalankan `openclaw gateway status --deep --require-rpc` dan pastikan URL
- Jalankan `openclaw gateway status --deep --require-rpc` dan konfirmasi bahwa URL
Gateway aktif, profil, path konfigurasi, dan proses adalah yang sedang Anda edit.
- Mulai ulang Gateway live setelah perubahan install/konfigurasi/kode Plugin. Di container
pembungkus, PID 1 mungkin hanya supervisor; mulai ulang atau beri sinyal ke proses anak
- Mulai ulang Gateway live setelah perubahan install/konfigurasi/kode plugin. Dalam kontainer
wrapper, PID 1 mungkin hanya supervisor; mulai ulang atau beri sinyal proses child
`openclaw gateway run`.
- Gunakan `openclaw plugins inspect <id> --runtime --json` untuk mengonfirmasi registrasi hook dan
- Gunakan `openclaw plugins inspect <id> --runtime --json` untuk mengonfirmasi pendaftaran hook dan
diagnostik. Hook percakapan non-bawaan seperti `llm_input`,
`llm_output`, `before_agent_finalize`, dan `agent_end` memerlukan
`plugins.entries.<id>.hooks.allowConversationAccess=true`.
- Untuk perpindahan model, utamakan `before_model_resolve`. Itu berjalan sebelum
resolusi model untuk giliran agen; `llm_output` hanya berjalan setelah percobaan model
- Untuk pengalihan model, pilih `before_model_resolve`. Hook ini berjalan sebelum resolusi model
untuk giliran agen; `llm_output` hanya berjalan setelah percobaan model
menghasilkan output asisten.
- Untuk bukti model sesi efektif, gunakan `openclaw sessions` atau permukaan
sesi/status Gateway dan, saat men-debug payload penyedia, mulai
Gateway dengan `--raw-stream --raw-stream-path <path>`.
### Penyiapan alat Plugin lambat
### Penyiapan alat plugin yang lambat
Jika giliran agen tampak berhenti saat menyiapkan alat, aktifkan logging trace dan
periksa baris timing factory alat Plugin:
Jika giliran agen tampak tersendat saat menyiapkan alat, aktifkan logging trace dan
periksa baris timing factory alat plugin:
```bash
openclaw config set logging.level trace
@ -407,28 +400,26 @@ Cari:
[trace:plugin-tools] factory timings ...
```
Ringkasan mencantumkan total waktu factory dan factory alat Plugin paling lambat,
termasuk id Plugin, nama alat yang dideklarasikan, bentuk hasil, dan apakah alat
bersifat opsional. Baris lambat dinaikkan menjadi peringatan saat satu factory
memakan waktu setidaknya 1 dtk atau total persiapan factory alat Plugin memakan
waktu setidaknya 5 dtk.
Ringkasan mencantumkan total waktu factory dan factory alat plugin paling lambat,
termasuk id plugin, nama alat yang dideklarasikan, bentuk hasil, dan apakah alat tersebut
opsional. Baris lambat dipromosikan menjadi peringatan saat satu factory memakan waktu
setidaknya 1 detik atau total persiapan factory alat plugin memakan waktu setidaknya 5 detik.
OpenClaw menyimpan cache hasil factory alat Plugin yang berhasil untuk resolusi
berulang dengan konteks permintaan efektif yang sama. Kunci cache mencakup
konfigurasi runtime efektif, workspace, id agen/sesi, kebijakan sandbox,
pengaturan browser, konteks pengiriman, identitas peminta, dan status
kepemilikan, sehingga factory yang bergantung pada field tepercaya tersebut
dijalankan ulang saat konteks berubah.
OpenClaw menyimpan cache hasil factory alat plugin yang berhasil untuk resolusi berulang
dengan konteks permintaan efektif yang sama. Kunci cache mencakup konfigurasi
runtime efektif, workspace, id agen/sesi, kebijakan sandbox, pengaturan browser,
konteks pengiriman, identitas requester, dan status kepemilikan, sehingga factory yang
bergantung pada field tepercaya tersebut dijalankan ulang saat konteks berubah.
Jika satu Plugin mendominasi timing, periksa registrasi runtime-nya:
Jika satu plugin mendominasi timing, periksa pendaftaran runtime-nya:
```bash
openclaw plugins inspect <plugin-id> --runtime --json
```
Lalu update, install ulang, atau nonaktifkan Plugin tersebut. Penulis Plugin
sebaiknya memindahkan pemuatan dependensi yang mahal ke balik jalur eksekusi
alat alih-alih melakukannya di dalam factory alat.
Lalu update, install ulang, atau nonaktifkan plugin tersebut. Penulis plugin sebaiknya memindahkan
pemuatan dependensi yang mahal ke balik path eksekusi alat, bukan melakukannya
di dalam factory alat.
### Kepemilikan channel atau alat duplikat
@ -438,36 +429,35 @@ Gejala:
- `channel setup already registered: <channel-id> (<plugin-id>)`
- `plugin tool name conflict (<plugin-id>): <tool-name>`
Ini berarti lebih dari satu Plugin aktif mencoba memiliki channel, alur
penyiapan, atau nama alat yang sama. Penyebab paling umum adalah Plugin channel
eksternal yang diinstal berdampingan dengan Plugin bawaan yang sekarang
menyediakan id channel yang sama.
Ini berarti lebih dari satu plugin aktif mencoba memiliki channel,
alur penyiapan, atau nama alat yang sama. Penyebab paling umum adalah plugin channel eksternal
yang diinstal berdampingan dengan plugin bawaan yang sekarang menyediakan id channel yang sama.
Langkah debug:
- Jalankan `openclaw plugins list --enabled --verbose` untuk melihat setiap Plugin
yang aktif dan asalnya.
- Jalankan `openclaw plugins inspect <id> --runtime --json` untuk setiap Plugin yang dicurigai dan
- Jalankan `openclaw plugins list --enabled --verbose` untuk melihat setiap plugin aktif
dan asalnya.
- Jalankan `openclaw plugins inspect <id> --runtime --json` untuk setiap plugin yang dicurigai dan
bandingkan `channels`, `channelConfigs`, `tools`, dan diagnostik.
- Jalankan `openclaw plugins registry --refresh` setelah menginstal atau menghapus
paket Plugin agar metadata tersimpan mencerminkan instalasi saat ini.
paket plugin agar metadata tersimpan mencerminkan instalasi saat ini.
- Mulai ulang Gateway setelah perubahan install, registri, atau konfigurasi.
Opsi perbaikan:
- Jika satu Plugin sengaja menggantikan Plugin lain untuk id channel yang sama, Plugin
pilihan sebaiknya mendeklarasikan `channelConfigs.<channel-id>.preferOver` dengan
id Plugin prioritas lebih rendah. Lihat [/plugins/manifest#replacing-another-channel-plugin](/id/plugins/manifest#replacing-another-channel-plugin).
- Jika satu plugin sengaja menggantikan yang lain untuk id channel yang sama, plugin
yang dipilih sebaiknya mendeklarasikan `channelConfigs.<channel-id>.preferOver` dengan
id plugin berprioritas lebih rendah. Lihat [/plugins/manifest#replacing-another-channel-plugin](/id/plugins/manifest#replacing-another-channel-plugin).
- Jika duplikat tidak disengaja, nonaktifkan salah satu sisi dengan
`plugins.entries.<plugin-id>.enabled: false` atau hapus instalasi Plugin
yang usang.
- Jika Anda secara eksplisit mengaktifkan kedua Plugin, OpenClaw mempertahankan permintaan itu dan
melaporkan konflik. Pilih satu pemilik untuk channel atau ganti nama alat milik
Plugin agar permukaan runtime tidak ambigu.
`plugins.entries.<plugin-id>.enabled: false` atau hapus instalasi plugin
usang.
- Jika Anda secara eksplisit mengaktifkan kedua plugin, OpenClaw mempertahankan permintaan tersebut dan
melaporkan konflik. Pilih satu pemilik untuk channel atau ganti nama alat milik plugin
agar permukaan runtime tidak ambigu.
## Slot Plugin (kategori eksklusif)
Beberapa kategori bersifat eksklusif (hanya satu aktif pada satu waktu):
Beberapa kategori bersifat eksklusif (hanya satu yang aktif pada satu waktu):
```json5
{
@ -480,10 +470,10 @@ Beberapa kategori bersifat eksklusif (hanya satu aktif pada satu waktu):
}
```
| Slot | Yang dikendalikan | Default |
| --------------- | --------------------- | ------------------- |
| `memory` | Plugin memori aktif | `memory-core` |
| `contextEngine` | Mesin konteks aktif | `legacy` (bawaan) |
| Slot | Yang dikontrolnya | Default |
| --------------- | -------------------- | ------------------- |
| `memory` | Plugin memori aktif | `memory-core` |
| `contextEngine` | Mesin konteks aktif | `legacy` (bawaan) |
## Referensi CLI
@ -533,82 +523,35 @@ openclaw plugins enable <id>
openclaw plugins disable <id>
```
Plugin bawaan dikirimkan bersama OpenClaw. Banyak yang diaktifkan secara default (misalnya
penyedia model bawaan, penyedia ucapan bawaan, dan Plugin browser bawaan).
Plugin bawaan lainnya tetap memerlukan `openclaw plugins enable <id>`.
Plugin bawaan dikirim bersama OpenClaw. Banyak yang diaktifkan secara default (misalnya penyedia model bawaan, penyedia ucapan bawaan, dan Plugin peramban bawaan). Plugin bawaan lain tetap memerlukan `openclaw plugins enable <id>`.
`--force` menimpa Plugin atau paket hook terpasang yang sudah ada di tempatnya. Gunakan
`openclaw plugins update <id-or-npm-spec>` untuk peningkatan rutin Plugin npm
yang terlacak. Ini tidak didukung bersama `--link`, yang menggunakan ulang jalur sumber alih-alih
menyalin ke target pemasangan terkelola.
`--force` menimpa Plugin terinstal atau paket hook yang sudah ada di tempat. Gunakan `openclaw plugins update <id-or-npm-spec>` untuk pemutakhiran rutin Plugin npm yang dilacak. Ini tidak didukung bersama `--link`, yang menggunakan kembali jalur sumber alih-alih menyalin ke target instal terkelola.
Ketika `plugins.allow` sudah disetel, `openclaw plugins install` menambahkan id
Plugin yang dipasang ke allowlist tersebut sebelum mengaktifkannya. Jika id Plugin yang sama
ada di `plugins.deny`, pemasangan menghapus entri deny yang usang itu sehingga
pemasangan eksplisit dapat langsung dimuat setelah restart.
Saat `plugins.allow` sudah ditetapkan, `openclaw plugins install` menambahkan id Plugin yang diinstal ke allowlist tersebut sebelum mengaktifkannya. Jika id Plugin yang sama ada di `plugins.deny`, instalasi menghapus entri deny usang tersebut sehingga instalasi eksplisit langsung dapat dimuat setelah restart.
OpenClaw menyimpan registri Plugin lokal yang dipersistenkan sebagai model baca dingin untuk
inventaris Plugin, kepemilikan kontribusi, dan perencanaan startup. Alur pemasangan, pembaruan,
pencopotan, pengaktifan, dan penonaktifan menyegarkan registri tersebut setelah mengubah status
Plugin. File `plugins/installs.json` yang sama menyimpan metadata pemasangan yang tahan lama di
`installRecords` tingkat atas dan metadata manifes yang dapat dibangun ulang di `plugins`. Jika
registri hilang, usang, atau tidak valid, `openclaw plugins registry
--refresh` membangun ulang tampilan manifesnya dari catatan pemasangan, kebijakan konfigurasi, dan
metadata manifes/paket tanpa memuat modul runtime Plugin.
`openclaw plugins update <id-or-npm-spec>` berlaku untuk pemasangan terlacak. Memberikan
spesifikasi paket npm dengan dist-tag atau versi persis menyelesaikan nama paket
kembali ke catatan Plugin terlacak dan mencatat spesifikasi baru untuk pembaruan mendatang.
Memberikan nama paket tanpa versi memindahkan pemasangan yang dipin persis kembali ke
jalur rilis default registri. Jika Plugin npm yang terpasang sudah cocok dengan
versi yang diselesaikan dan identitas artefak yang tercatat, OpenClaw melewati pembaruan
tanpa mengunduh, memasang ulang, atau menulis ulang konfigurasi.
Ketika `openclaw update` berjalan di kanal beta, catatan Plugin npm dan ClawHub
jalur default mencoba `@beta` terlebih dahulu dan kembali ke default/latest ketika tidak ada rilis
beta Plugin. Versi persis dan tag eksplisit tetap dipin.
OpenClaw mempertahankan registri Plugin lokal persisten sebagai model baca dingin untuk inventaris Plugin, kepemilikan kontribusi, dan perencanaan startup. Alur instal, pemutakhiran, pencopotan, pengaktifan, dan penonaktifan me-refresh registri tersebut setelah mengubah status Plugin. File `plugins/installs.json` yang sama menyimpan metadata instalasi tahan lama di `installRecords` tingkat atas dan metadata manifes yang dapat dibangun ulang di `plugins`. Jika registri hilang, usang, atau tidak valid, `openclaw plugins registry --refresh` membangun ulang tampilan manifesnya dari rekaman instalasi, kebijakan konfigurasi, dan metadata manifes/paket tanpa memuat modul runtime Plugin.
`openclaw plugins update <id-or-npm-spec>` berlaku untuk instalasi yang dilacak. Memberikan spec paket npm dengan dist-tag atau versi pasti akan menyelesaikan nama paket kembali ke rekaman Plugin yang dilacak dan merekam spec baru untuk pemutakhiran mendatang. Memberikan nama paket tanpa versi memindahkan instalasi berpinned pasti kembali ke jalur rilis default registri. Jika Plugin npm yang terinstal sudah cocok dengan versi yang diselesaikan dan identitas artefak yang direkam, OpenClaw melewati pemutakhiran tanpa mengunduh, menginstal ulang, atau menulis ulang konfigurasi.
Saat `openclaw update` berjalan pada kanal beta, rekaman Plugin npm dan ClawHub jalur default mencoba `@beta` terlebih dahulu dan kembali ke default/latest saat tidak ada rilis beta Plugin. Versi pasti dan tag eksplisit tetap dipinned.
`--pin` hanya untuk npm. Ini tidak didukung bersama `--marketplace`, karena
pemasangan marketplace mempertahankan metadata sumber marketplace alih-alih spesifikasi npm.
`--pin` hanya untuk npm. Ini tidak didukung bersama `--marketplace`, karena instalasi marketplace mempertahankan metadata sumber marketplace alih-alih spec npm.
`--dangerously-force-unsafe-install` adalah override darurat untuk false positive
dari pemindai kode berbahaya bawaan. Ini memungkinkan pemasangan Plugin
dan pembaruan Plugin terus berjalan melewati temuan bawaan `critical`, tetapi tetap
tidak melewati blok kebijakan `before_install` Plugin atau pemblokiran kegagalan pemindaian.
Pemindaian pemasangan mengabaikan file dan direktori pengujian umum seperti `tests/`,
`__tests__/`, `*.test.*`, dan `*.spec.*` untuk menghindari pemblokiran mock pengujian yang dipaketkan;
entrypoint runtime Plugin yang dideklarasikan tetap dipindai meskipun menggunakan salah satu
nama tersebut.
`--dangerously-force-unsafe-install` adalah override darurat untuk positif palsu dari pemindai kode berbahaya bawaan. Ini memungkinkan instalasi Plugin dan pemutakhiran Plugin melanjutkan melewati temuan `critical` bawaan, tetapi tetap tidak melewati blok kebijakan `before_install` Plugin atau pemblokiran kegagalan pemindaian. Pemindaian instalasi mengabaikan file dan direktori pengujian umum seperti `tests/`, `__tests__/`, `*.test.*`, dan `*.spec.*` untuk menghindari pemblokiran mock pengujian yang dipaketkan; entrypoint runtime Plugin yang dideklarasikan tetap dipindai meskipun menggunakan salah satu nama tersebut.
Flag CLI ini hanya berlaku untuk alur pemasangan/pembaruan Plugin. Pemasangan dependensi Skills
yang didukung Gateway menggunakan override permintaan `dangerouslyForceUnsafeInstall`
yang sesuai, sedangkan `openclaw skills install` tetap menjadi alur unduh/pasang skill ClawHub
yang terpisah.
Flag CLI ini hanya berlaku untuk alur instal/pemutakhiran Plugin. Instalasi dependensi skill yang didukung Gateway menggunakan override permintaan `dangerouslyForceUnsafeInstall` yang sesuai, sementara `openclaw skills install` tetap menjadi alur pengunduhan/instalasi skill ClawHub yang terpisah.
Jika Plugin yang Anda terbitkan di ClawHub disembunyikan atau diblokir oleh pemindaian, buka
dasbor ClawHub atau jalankan `clawhub package rescan <name>` untuk meminta ClawHub memeriksanya
lagi. `--dangerously-force-unsafe-install` hanya memengaruhi pemasangan di mesin Anda sendiri;
itu tidak meminta ClawHub memindai ulang Plugin atau membuat rilis yang diblokir menjadi publik.
Jika Plugin yang Anda terbitkan di ClawHub disembunyikan atau diblokir oleh pemindaian, buka dasbor ClawHub atau jalankan `clawhub package rescan <name>` untuk meminta ClawHub memeriksanya lagi. `--dangerously-force-unsafe-install` hanya memengaruhi instalasi di mesin Anda sendiri; ini tidak meminta ClawHub memindai ulang Plugin atau membuat rilis yang diblokir menjadi publik.
Bundle yang kompatibel berpartisipasi dalam alur daftar/inspeksi/aktifkan/nonaktifkan Plugin yang sama.
Dukungan runtime saat ini mencakup bundle Skills, command-skills Claude,
default Claude `settings.json`, default Claude `.lsp.json` dan `lspServers` yang dideklarasikan manifes,
command-skills Cursor, dan direktori hook Codex yang kompatibel.
Bundle yang kompatibel berpartisipasi dalam alur daftar/inspeksi/aktifkan/nonaktifkan Plugin yang sama. Dukungan runtime saat ini mencakup Skills bundle, command-skills Claude, default Claude `settings.json`, default Claude `.lsp.json` dan `lspServers` yang dideklarasikan manifes, command-skills Cursor, serta direktori hook Codex yang kompatibel.
`openclaw plugins inspect <id>` juga melaporkan kapabilitas bundle yang terdeteksi plus
entri server MCP dan LSP yang didukung atau tidak didukung untuk Plugin berbasis bundle.
`openclaw plugins inspect <id>` juga melaporkan kapabilitas bundle yang terdeteksi beserta entri server MCP dan LSP yang didukung atau tidak didukung untuk Plugin yang didukung bundle.
Sumber marketplace dapat berupa nama marketplace Claude yang dikenal dari
`~/.claude/plugins/known_marketplaces.json`, root marketplace lokal atau jalur
`marketplace.json`, singkatan GitHub seperti `owner/repo`, URL repo GitHub, atau URL git. Untuk
marketplace jarak jauh, entri Plugin harus tetap berada di dalam repo marketplace yang dikloning
dan hanya menggunakan sumber jalur relatif.
Sumber marketplace dapat berupa nama marketplace Claude yang dikenal dari `~/.claude/plugins/known_marketplaces.json`, root marketplace lokal atau jalur `marketplace.json`, shorthand GitHub seperti `owner/repo`, URL repo GitHub, atau URL git. Untuk marketplace jarak jauh, entri Plugin harus tetap berada di dalam repo marketplace yang dikloning dan hanya menggunakan sumber jalur relatif.
Lihat [referensi CLI `openclaw plugins`](/id/cli/plugins) untuk detail lengkap.
## Ikhtisar API Plugin
Plugin native mengekspor objek entri yang mengekspos `register(api)`. Plugin lama
mungkin masih menggunakan `activate(api)` sebagai alias legacy, tetapi Plugin baru sebaiknya
menggunakan `register`.
Plugin native mengekspor objek entri yang mengekspos `register(api)`. Plugin lama mungkin masih menggunakan `activate(api)` sebagai alias legacy, tetapi Plugin baru sebaiknya menggunakan `register`.
```typescript
export default definePluginEntry({
@ -628,53 +571,43 @@ export default definePluginEntry({
});
```
OpenClaw memuat objek entri dan memanggil `register(api)` selama aktivasi
Plugin. Loader tetap fallback ke `activate(api)` untuk Plugin lama,
tetapi Plugin bawaan dan Plugin eksternal baru sebaiknya menganggap `register` sebagai
kontrak publik.
OpenClaw memuat objek entri dan memanggil `register(api)` selama aktivasi Plugin. Loader masih fallback ke `activate(api)` untuk Plugin lama, tetapi Plugin bawaan dan Plugin eksternal baru sebaiknya memperlakukan `register` sebagai kontrak publik.
`api.registrationMode` memberi tahu Plugin mengapa entrinya sedang dimuat:
`api.registrationMode` memberi tahu Plugin mengapa entrinya dimuat:
| Mode | Arti |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `full` | Aktivasi runtime. Daftarkan tool, hook, layanan, perintah, route, dan efek samping aktif lainnya. |
| `discovery` | Penemuan kapabilitas hanya-baca. Daftarkan penyedia dan metadata; kode entri Plugin tepercaya dapat dimuat, tetapi lewati efek samping aktif. |
| `setup-only` | Pemuatan metadata penyiapan kanal melalui entri penyiapan ringan. |
| `setup-runtime` | Pemuatan penyiapan kanal yang juga memerlukan entri runtime. |
| `cli-metadata` | Hanya pengumpulan metadata perintah CLI. |
| Mode | Makna |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `full` | Aktivasi runtime. Daftarkan alat, hook, layanan, perintah, rute, dan efek samping live lainnya. |
| `discovery` | Penemuan kapabilitas hanya-baca. Daftarkan penyedia dan metadata; kode entri Plugin tepercaya boleh dimuat, tetapi lewati efek samping live. |
| `setup-only` | Pemuatan metadata penyiapan kanal melalui entri penyiapan ringan. |
| `setup-runtime` | Pemuatan penyiapan kanal yang juga memerlukan entri runtime. |
| `cli-metadata` | Hanya pengumpulan metadata perintah CLI. |
Entri Plugin yang membuka soket, database, worker latar belakang, atau klien berumur panjang
sebaiknya menjaga efek samping tersebut dengan `api.registrationMode === "full"`.
Pemuatan discovery di-cache secara terpisah dari pemuatan aktivasi dan tidak menggantikan
registri Gateway yang sedang berjalan. Discovery bersifat tidak mengaktifkan, bukan bebas impor:
OpenClaw dapat mengevaluasi entri Plugin tepercaya atau modul Plugin kanal untuk membangun
snapshot. Jaga tingkat atas modul tetap ringan dan bebas efek samping, serta pindahkan
klien jaringan, subprocess, listener, pembacaan kredensial, dan startup layanan
ke balik jalur runtime penuh.
Entri Plugin yang membuka soket, basis data, worker latar belakang, atau klien berumur panjang sebaiknya melindungi efek samping tersebut dengan `api.registrationMode === "full"`. Pemuatan discovery dicache secara terpisah dari pemuatan aktivasi dan tidak menggantikan registri Gateway yang sedang berjalan. Discovery bersifat tidak mengaktifkan, bukan bebas impor: OpenClaw dapat mengevaluasi entri Plugin tepercaya atau modul Plugin kanal untuk membangun snapshot. Jaga top level modul tetap ringan dan bebas efek samping, lalu pindahkan klien jaringan, subprocess, listener, pembacaan kredensial, dan startup layanan ke balik jalur full-runtime.
Metode pendaftaran umum:
| Metode | Yang didaftarkan |
| --------------------------------------- | ---------------------------- |
| `registerProvider` | Penyedia model (LLM) |
| `registerChannel` | Kanal chat |
| `registerTool` | Tool agen |
| `registerHook` / `on(...)` | Hook siklus hidup |
| `registerSpeechProvider` | Text-to-speech / STT |
| `registerRealtimeTranscriptionProvider` | STT streaming |
| `registerRealtimeVoiceProvider` | Suara realtime dupleks |
| `registerMediaUnderstandingProvider` | Analisis gambar/audio |
| `registerImageGenerationProvider` | Pembuatan gambar |
| `registerMusicGenerationProvider` | Pembuatan musik |
| `registerVideoGenerationProvider` | Pembuatan video |
| `registerWebFetchProvider` | Penyedia web fetch / scrape |
| `registerWebSearchProvider` | Pencarian web |
| `registerHttpRoute` | Endpoint HTTP |
| `registerCommand` / `registerCli` | Perintah CLI |
| `registerContextEngine` | Mesin konteks |
| `registerService` | Layanan latar belakang |
| Metode | Yang didaftarkan |
| --------------------------------------- | ---------------------------------- |
| `registerProvider` | Penyedia model (LLM) |
| `registerChannel` | Kanal chat |
| `registerTool` | Alat agen |
| `registerHook` / `on(...)` | Hook lifecycle |
| `registerSpeechProvider` | Text-to-speech / STT |
| `registerRealtimeTranscriptionProvider` | Streaming STT |
| `registerRealtimeVoiceProvider` | Suara realtime duplex |
| `registerMediaUnderstandingProvider` | Analisis gambar/audio |
| `registerImageGenerationProvider` | Generasi gambar |
| `registerMusicGenerationProvider` | Generasi musik |
| `registerVideoGenerationProvider` | Generasi video |
| `registerWebFetchProvider` | Penyedia web fetch / scrape |
| `registerWebSearchProvider` | Pencarian web |
| `registerHttpRoute` | Endpoint HTTP |
| `registerCommand` / `registerCli` | Perintah CLI |
| `registerContextEngine` | Mesin konteks |
| `registerService` | Layanan latar belakang |
Perilaku guard hook untuk hook siklus hidup bertipe:
Perilaku guard hook untuk hook lifecycle bertipe:
- `before_tool_call`: `{ block: true }` bersifat terminal; handler berprioritas lebih rendah dilewati.
- `before_tool_call`: `{ block: false }` adalah no-op dan tidak menghapus blok sebelumnya.
@ -683,20 +616,15 @@ Perilaku guard hook untuk hook siklus hidup bertipe:
- `message_sending`: `{ cancel: true }` bersifat terminal; handler berprioritas lebih rendah dilewati.
- `message_sending`: `{ cancel: false }` adalah no-op dan tidak menghapus pembatalan sebelumnya.
App-server Codex native menjembatani event tool Codex-native kembali ke permukaan
hook ini. Plugin dapat memblokir tool Codex native melalui `before_tool_call`,
mengamati hasil melalui `after_tool_call`, dan berpartisipasi dalam persetujuan
`PermissionRequest` Codex. Bridge belum menulis ulang argumen tool Codex-native.
Batas dukungan runtime Codex yang persis berada di
[kontrak dukungan Codex harness v1](/id/plugins/codex-harness#v1-support-contract).
Server aplikasi Codex native menjembatani peristiwa alat Codex-native kembali ke permukaan hook ini. Plugin dapat memblokir alat Codex native melalui `before_tool_call`, mengamati hasil melalui `after_tool_call`, dan berpartisipasi dalam persetujuan Codex `PermissionRequest`. Bridge belum menulis ulang argumen alat Codex-native. Batas dukungan runtime Codex yang tepat berada dalam [kontrak dukungan harness Codex v1](/id/plugins/codex-harness#v1-support-contract).
Untuk perilaku hook bertipe lengkap, lihat [ikhtisar SDK](/id/plugins/sdk-overview#hook-decision-semantics).
## Terkait
- [Membangun Plugin](/id/plugins/building-plugins) — buat Plugin Anda sendiri
- [Membuat Plugin](/id/plugins/building-plugins) — buat Plugin Anda sendiri
- [Bundle Plugin](/id/plugins/bundles) — kompatibilitas bundle Codex/Claude/Cursor
- [Manifes Plugin](/id/plugins/manifest) — skema manifes
- [Mendaftarkan tool](/id/plugins/building-plugins#registering-agent-tools) — tambahkan tool agen dalam Plugin
- [Internal Plugin](/id/plugins/architecture) — model kapabilitas dan pipeline pemuatan
- [Manifest Plugin](/id/plugins/manifest) — skema manifest
- [Mendaftarkan alat](/id/plugins/building-plugins#registering-agent-tools) — tambahkan alat agen dalam Plugin
- [Internal Plugin](/id/plugins/architecture) — model kapabilitas dan alur pemuatan
- [Plugin komunitas](/id/plugins/community) — daftar pihak ketiga

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

@ -1,105 +1,106 @@
---
read_when:
- Menyesuaikan penguraian atau nilai bawaan direktif `thinking`, `fast-mode`, atau `verbose`
- Menyesuaikan penguraian atau nilai default direktif thinking, fast-mode, atau verbose
summary: Sintaks direktif untuk /think, /fast, /verbose, /trace, dan visibilitas penalaran
title: Tingkat berpikir
x-i18n:
generated_at: "2026-05-04T18:24:29Z"
generated_at: "2026-05-05T01:50:21Z"
model: gpt-5.5
provider: openai
source_hash: fcd1cd76ca5d0b08656e0629df656ad8aa037201d8de68093b3e46eb0708f811
source_hash: d2282c9eccda4693680bbfbfc42de508021f4472b00d40a1a8c1bc19a4516012
source_path: tools/thinking.md
workflow: 16
---
## Apa yang dilakukan
## Fungsinya
- Arahan inline dalam isi masuk apa pun: `/t <level>`, `/think:<level>`, atau `/thinking <level>`.
- Direktif sebaris dalam isi masuk apa pun: `/t <level>`, `/think:<level>`, atau `/thinking <level>`.
- Level (alias): `off | minimal | low | medium | high | xhigh | adaptive | max`
- minimal → “berpikir”
- low → “berpikir keras”
- medium → “berpikir lebih keras”
- high → “ultrathink” (anggaran maks)
- high → “ultrathink” (anggaran maksimum)
- xhigh → “ultrathink+” (model GPT-5.2+ dan Codex, ditambah upaya Anthropic Claude Opus 4.7)
- adaptive → pemikiran adaptif yang dikelola penyedia (didukung untuk Claude 4.6 di Anthropic/Bedrock, Anthropic Claude Opus 4.7, dan pemikiran dinamis Google Gemini)
- max → penalaran maks penyedia (Anthropic Claude Opus 4.7; Ollama memetakan ini ke upaya native `think` tertingginya)
- adaptive → berpikir adaptif yang dikelola penyedia (didukung untuk Claude 4.6 di Anthropic/Bedrock, Anthropic Claude Opus 4.7, dan berpikir dinamis Google Gemini)
- max → penalaran maksimum penyedia (Anthropic Claude Opus 4.7; Ollama memetakan ini ke upaya `think` native tertingginya)
- `x-high`, `x_high`, `extra-high`, `extra high`, dan `extra_high` dipetakan ke `xhigh`.
- `highest` dipetakan ke `high`.
- Catatan penyedia:
- Menu dan pemilih pemikiran digerakkan oleh profil penyedia. Plugin penyedia mendeklarasikan set level persis untuk model yang dipilih, termasuk label seperti biner `on`.
- `adaptive`, `xhigh`, dan `max` hanya ditampilkan untuk profil penyedia/model yang mendukungnya. Arahan yang diketik untuk level yang tidak didukung ditolak dengan opsi valid model tersebut.
- Level tidak didukung yang tersimpan sebelumnya dipetakan ulang berdasarkan peringkat profil penyedia. `adaptive` kembali ke `medium` pada model non-adaptif, sedangkan `xhigh` dan `max` kembali ke level non-`off` terbesar yang didukung untuk model yang dipilih.
- Model Anthropic Claude 4.6 default ke `adaptive` saat tidak ada level pemikiran eksplisit yang ditetapkan.
- Anthropic Claude Opus 4.7 tidak default ke pemikiran adaptif. Default upaya API-nya tetap dimiliki penyedia kecuali Anda secara eksplisit menetapkan level pemikiran.
- Anthropic Claude Opus 4.7 memetakan `/think xhigh` ke pemikiran adaptif ditambah `output_config.effort: "xhigh"`, karena `/think` adalah arahan pemikiran dan `xhigh` adalah pengaturan upaya Opus 4.7.
- Anthropic Claude Opus 4.7 juga mengekspos `/think max`; ini dipetakan ke jalur upaya maks yang sama milik penyedia.
- Model DeepSeek V4 mengekspos `/think xhigh|max`; keduanya dipetakan ke DeepSeek `reasoning_effort: "max"` sedangkan level non-`off` yang lebih rendah dipetakan ke `high`.
- Model Ollama yang mampu berpikir mengekspos `/think low|medium|high|max`; `max` dipetakan ke native `think: "high"` karena API native Ollama menerima string upaya `low`, `medium`, dan `high`.
- Model OpenAI GPT memetakan `/think` melalui dukungan upaya Responses API khusus model. `/think off` mengirim `reasoning.effort: "none"` hanya saat model target mendukungnya; jika tidak, OpenClaw menghilangkan payload penalaran yang dinonaktifkan alih-alih mengirim nilai yang tidak didukung.
- Entri katalog kustom yang kompatibel dengan OpenAI dapat ikut memakai `/think xhigh` dengan menetapkan `models.providers.<provider>.models[].compat.supportedReasoningEfforts` agar menyertakan `"xhigh"`. Ini menggunakan metadata kompat yang sama yang memetakan payload upaya penalaran OpenAI keluar, sehingga menu, validasi sesi, CLI agen, dan `llm-task` selaras dengan perilaku transport.
- Ref OpenRouter Hunter Alpha terkonfigurasi yang usang melewati injeksi penalaran proxy karena rute yang sudah dihentikan itu dapat mengembalikan teks jawaban akhir melalui field penalaran.
- Google Gemini memetakan `/think adaptive` ke pemikiran dinamis milik penyedia Gemini. Permintaan Gemini 3 menghilangkan `thinkingLevel` tetap, sedangkan permintaan Gemini 2.5 mengirim `thinkingBudget: -1`; level tetap tetap dipetakan ke `thinkingLevel` atau anggaran Gemini terdekat untuk keluarga model tersebut.
- MiniMax (`minimax/*`) pada jalur streaming yang kompatibel dengan Anthropic default ke `thinking: { type: "disabled" }` kecuali Anda secara eksplisit menetapkan pemikiran di parameter model atau parameter permintaan. Ini menghindari delta `reasoning_content` yang bocor dari format stream Anthropic non-native milik MiniMax.
- Z.AI (`zai/*`) hanya mendukung pemikiran biner (`on`/`off`). Level non-`off` apa pun diperlakukan sebagai `on` (dipetakan ke `low`).
- Moonshot (`moonshot/*`) memetakan `/think off` ke `thinking: { type: "disabled" }` dan level non-`off` apa pun ke `thinking: { type: "enabled" }`. Saat pemikiran diaktifkan, Moonshot hanya menerima `tool_choice` `auto|none`; OpenClaw menormalkan nilai yang tidak kompatibel menjadi `auto`.
- Menu dan pemilih berpikir digerakkan oleh profil penyedia. Plugin penyedia mendeklarasikan set level yang tepat untuk model yang dipilih, termasuk label seperti `on` biner.
- `adaptive`, `xhigh`, dan `max` hanya ditampilkan untuk profil penyedia/model yang mendukungnya. Direktif yang diketik untuk level yang tidak didukung ditolak dengan opsi valid model tersebut.
- Level tersimpan yang sudah ada tetapi tidak didukung dipetakan ulang berdasarkan peringkat profil penyedia. `adaptive` kembali ke `medium` pada model non-adaptif, sementara `xhigh` dan `max` kembali ke level non-off terbesar yang didukung untuk model yang dipilih.
- Model Anthropic Claude 4.6 default ke `adaptive` ketika tidak ada level berpikir eksplisit yang ditetapkan.
- Anthropic Claude Opus 4.7 tidak default ke berpikir adaptif. Default upaya API-nya tetap dimiliki penyedia kecuali Anda menetapkan level berpikir secara eksplisit.
- Anthropic Claude Opus 4.7 memetakan `/think xhigh` ke berpikir adaptif plus `output_config.effort: "xhigh"`, karena `/think` adalah direktif berpikir dan `xhigh` adalah pengaturan upaya Opus 4.7.
- Anthropic Claude Opus 4.7 juga mengekspos `/think max`; ini dipetakan ke jalur upaya maksimum yang sama yang dimiliki penyedia.
- Model Direct DeepSeek V4 mengekspos `/think xhigh|max`; keduanya dipetakan ke DeepSeek `reasoning_effort: "max"` sementara level non-off yang lebih rendah dipetakan ke `high`.
- Model DeepSeek V4 yang dirutekan OpenRouter mengekspos `/think xhigh` dan mengirim nilai `reasoning_effort` yang didukung OpenRouter. Override `max` yang tersimpan kembali ke `xhigh`.
- Model Ollama yang mendukung berpikir mengekspos `/think low|medium|high|max`; `max` dipetakan ke `think: "high"` native karena API native Ollama menerima string upaya `low`, `medium`, dan `high`.
- Model OpenAI GPT memetakan `/think` melalui dukungan upaya Responses API khusus model. `/think off` mengirim `reasoning.effort: "none"` hanya ketika model target mendukungnya; jika tidak, OpenClaw menghilangkan payload penalaran yang dinonaktifkan alih-alih mengirim nilai yang tidak didukung.
- Entri katalog kustom yang kompatibel dengan OpenAI dapat mengaktifkan `/think xhigh` dengan menetapkan `models.providers.<provider>.models[].compat.supportedReasoningEfforts` agar menyertakan `"xhigh"`. Ini menggunakan metadata kompatibilitas yang sama yang memetakan payload upaya penalaran OpenAI keluar, sehingga menu, validasi sesi, CLI agen, dan `llm-task` selaras dengan perilaku transport.
- Referensi OpenRouter Hunter Alpha yang dikonfigurasi usang melewati injeksi penalaran proksi karena rute yang sudah dihentikan itu dapat mengembalikan teks jawaban akhir melalui field penalaran.
- Google Gemini memetakan `/think adaptive` ke berpikir dinamis yang dimiliki penyedia Gemini. Permintaan Gemini 3 menghilangkan `thinkingLevel` tetap, sementara permintaan Gemini 2.5 mengirim `thinkingBudget: -1`; level tetap tetap dipetakan ke `thinkingLevel` atau anggaran Gemini terdekat untuk keluarga model tersebut.
- MiniMax (`minimax/*`) pada jalur streaming yang kompatibel dengan Anthropic default ke `thinking: { type: "disabled" }` kecuali Anda menetapkan berpikir secara eksplisit di parameter model atau parameter permintaan. Ini menghindari kebocoran delta `reasoning_content` dari format stream Anthropic non-native milik MiniMax.
- Z.AI (`zai/*`) hanya mendukung berpikir biner (`on`/`off`). Level non-`off` apa pun diperlakukan sebagai `on` (dipetakan ke `low`).
- Moonshot (`moonshot/*`) memetakan `/think off` ke `thinking: { type: "disabled" }` dan level non-`off` apa pun ke `thinking: { type: "enabled" }`. Ketika berpikir diaktifkan, Moonshot hanya menerima `tool_choice` `auto|none`; OpenClaw menormalkan nilai yang tidak kompatibel ke `auto`.
## Urutan resolusi
1. Arahan inline pada pesan (berlaku hanya untuk pesan itu).
2. Override sesi (ditetapkan dengan mengirim pesan yang hanya berisi arahan).
1. Direktif sebaris pada pesan (hanya berlaku untuk pesan tersebut).
2. Override sesi (ditetapkan dengan mengirim pesan yang hanya berisi direktif).
3. Default per agen (`agents.list[].thinkingDefault` dalam konfigurasi).
4. Default global (`agents.defaults.thinkingDefault` dalam konfigurasi).
5. Fallback: default yang dideklarasikan penyedia saat tersedia; jika tidak, model yang mampu bernalar diselesaikan ke `medium` atau level non-`off` terdekat yang didukung untuk model tersebut, dan model non-penalaran tetap `off`.
5. Fallback: default yang dideklarasikan penyedia ketika tersedia; jika tidak, model yang mendukung penalaran diselesaikan ke `medium` atau level non-`off` terdekat yang didukung untuk model tersebut, dan model non-penalaran tetap `off`.
## Menetapkan default sesi
- Kirim pesan yang **hanya** berisi arahan (spasi kosong diperbolehkan), misalnya `/think:medium` atau `/t high`.
- Itu berlaku untuk sesi saat ini (default per pengirim); dihapus oleh `/think:off` atau reset sesi menganggur.
- Balasan konfirmasi dikirim (`Thinking level set to high.` / `Thinking disabled.`). Jika level tidak valid (misalnya `/thinking big`), perintah ditolak dengan petunjuk dan status sesi dibiarkan tidak berubah.
- Kirim `/think` (atau `/think:`) tanpa argumen untuk melihat level pemikiran saat ini.
- Kirim pesan yang **hanya** berisi direktif (spasi putih diperbolehkan), mis. `/think:medium` atau `/t high`.
- Itu akan melekat untuk sesi saat ini (default per pengirim); dibersihkan oleh `/think:off` atau reset idle sesi.
- Balasan konfirmasi dikirim (`Thinking level set to high.` / `Thinking disabled.`). Jika level tidak valid (mis. `/thinking big`), perintah ditolak dengan petunjuk dan status sesi dibiarkan tidak berubah.
- Kirim `/think` (atau `/think:`) tanpa argumen untuk melihat level berpikir saat ini.
## Penerapan berdasarkan agen
## Penerapan oleh agen
- **Pi tertanam**: level yang diselesaikan diteruskan ke runtime agen Pi dalam proses.
- **Backend Claude CLI**: level non-off diteruskan ke Claude Code sebagai `--effort` saat menggunakan `claude-cli`; lihat [Backend CLI](/id/gateway/cli-backends).
- **Backend CLI Claude**: level non-off diteruskan ke Claude Code sebagai `--effort` ketika menggunakan `claude-cli`; lihat [Backend CLI](/id/gateway/cli-backends).
## Mode cepat (/fast)
- Level: `on|off`.
- Pesan yang hanya berisi arahan mengaktifkan/menonaktifkan override mode cepat sesi dan membalas `Fast mode enabled.` / `Fast mode disabled.`.
- Pesan yang hanya berisi direktif mengalihkan override mode cepat sesi dan membalas `Fast mode enabled.` / `Fast mode disabled.`.
- Kirim `/fast` (atau `/fast status`) tanpa mode untuk melihat status mode cepat efektif saat ini.
- OpenClaw menyelesaikan mode cepat dalam urutan ini:
1. Inline/hanya-arahan `/fast on|off`
1. `/fast on|off` sebaris/hanya-direktif
2. Override sesi
3. Default per agen (`agents.list[].fastModeDefault`)
4. Konfigurasi per model: `agents.defaults.models["<provider>/<model>"].params.fastMode`
5. Fallback: `off`
- Untuk `openai/*`, mode cepat dipetakan ke pemrosesan prioritas OpenAI dengan mengirim `service_tier=priority` pada permintaan Responses yang didukung.
- Untuk `openai-codex/*`, mode cepat mengirim flag `service_tier=priority` yang sama pada Codex Responses. OpenClaw mempertahankan satu toggle `/fast` bersama di kedua jalur autentikasi.
- Untuk permintaan publik langsung `anthropic/*`, termasuk lalu lintas terautentikasi OAuth yang dikirim ke `api.anthropic.com`, mode cepat dipetakan ke tingkat layanan Anthropic: `/fast on` menetapkan `service_tier=auto`, `/fast off` menetapkan `service_tier=standard_only`.
- Untuk `openai-codex/*`, mode cepat mengirim flag `service_tier=priority` yang sama pada Responses Codex. OpenClaw mempertahankan satu toggle `/fast` bersama di kedua jalur auth.
- Untuk permintaan publik langsung `anthropic/*`, termasuk lalu lintas terautentikasi OAuth yang dikirim ke `api.anthropic.com`, mode cepat dipetakan ke tingkatan layanan Anthropic: `/fast on` menetapkan `service_tier=auto`, `/fast off` menetapkan `service_tier=standard_only`.
- Untuk `minimax/*` pada jalur yang kompatibel dengan Anthropic, `/fast on` (atau `params.fastMode: true`) menulis ulang `MiniMax-M2.7` menjadi `MiniMax-M2.7-highspeed`.
- Parameter model Anthropic `serviceTier` / `service_tier` eksplisit meng-override default mode cepat saat keduanya ditetapkan. OpenClaw tetap melewati injeksi tingkat layanan Anthropic untuk URL dasar proxy non-Anthropic.
- `/status` menampilkan `Fast` hanya saat mode cepat diaktifkan.
- Parameter model Anthropic `serviceTier` / `service_tier` eksplisit meng-override default mode cepat ketika keduanya ditetapkan. OpenClaw tetap melewati injeksi tingkatan layanan Anthropic untuk URL basis proksi non-Anthropic.
- `/status` menampilkan `Fast` hanya ketika mode cepat diaktifkan.
## Arahan verbose (/verbose atau /v)
## Direktif verbose (/verbose atau /v)
- Level: `on` (minimal) | `full` | `off` (default).
- Pesan yang hanya berisi arahan mengaktifkan/menonaktifkan verbose sesi dan membalas `Verbose logging enabled.` / `Verbose logging disabled.`; level tidak valid mengembalikan petunjuk tanpa mengubah status.
- Pesan yang hanya berisi direktif mengalihkan verbose sesi dan membalas `Verbose logging enabled.` / `Verbose logging disabled.`; level tidak valid mengembalikan petunjuk tanpa mengubah status.
- `/verbose off` menyimpan override sesi eksplisit; hapus melalui UI Sesi dengan memilih `inherit`.
- Arahan inline hanya memengaruhi pesan itu; default sesi/global berlaku selain itu.
- Direktif sebaris hanya memengaruhi pesan tersebut; default sesi/global berlaku selain itu.
- Kirim `/verbose` (atau `/verbose:`) tanpa argumen untuk melihat level verbose saat ini.
- Saat verbose aktif, agen yang memancarkan hasil alat terstruktur (Pi, agen JSON lain) mengirim setiap panggilan alat kembali sebagai pesan metadata-saja miliknya sendiri, diawali dengan `<emoji> <tool-name>: <arg>` saat tersedia. Ringkasan alat ini dikirim segera saat setiap alat dimulai (bubble terpisah), bukan sebagai delta streaming.
- Ketika verbose aktif, agen yang memancarkan hasil alat terstruktur (Pi, agen JSON lain) mengirim setiap panggilan alat kembali sebagai pesan khusus metadata tersendiri, diawali dengan `<emoji> <tool-name>: <arg>` ketika tersedia. Ringkasan alat ini dikirim segera setelah setiap alat dimulai (gelembung terpisah), bukan sebagai delta streaming.
- Ringkasan kegagalan alat tetap terlihat dalam mode normal, tetapi sufiks detail kesalahan mentah disembunyikan kecuali verbose adalah `on` atau `full`.
- Saat verbose adalah `full`, output alat juga diteruskan setelah selesai (bubble terpisah, dipotong ke panjang aman). Jika Anda mengalihkan `/verbose on|full|off` saat run sedang berjalan, bubble alat berikutnya mengikuti pengaturan baru.
- `agents.defaults.toolProgressDetail` mengontrol bentuk ringkasan alat `/verbose` dan baris alat draft progres. Gunakan `"explain"` (default) untuk label manusia ringkas seperti `🛠️ Exec: checking JS syntax`; gunakan `"raw"` saat Anda juga menginginkan perintah/detail mentah ditambahkan untuk debugging. `agents.list[].toolProgressDetail` per agen meng-override default.
- Ketika verbose adalah `full`, output alat juga diteruskan setelah selesai (gelembung terpisah, dipotong ke panjang aman). Jika Anda mengalihkan `/verbose on|full|off` saat sebuah run sedang berlangsung, gelembung alat berikutnya menghormati pengaturan baru.
- `agents.defaults.toolProgressDetail` mengontrol bentuk ringkasan alat `/verbose` dan baris alat draf progres. Gunakan `"explain"` (default) untuk label manusia ringkas seperti `🛠️ Exec: checking JS syntax`; gunakan `"raw"` ketika Anda juga menginginkan perintah/detail mentah ditambahkan untuk debugging. `agents.list[].toolProgressDetail` per agen meng-override default.
- `explain`: `🛠️ Exec: check JS syntax for /tmp/app.js`
- `raw`: `🛠️ Exec: check JS syntax for /tmp/app.js, node --check /tmp/app.js`
## Arahan trace Plugin (/trace)
## Direktif trace Plugin (/trace)
- Level: `on` | `off` (default).
- Pesan yang hanya berisi arahan mengaktifkan/menonaktifkan output trace Plugin sesi dan membalas `Plugin trace enabled.` / `Plugin trace disabled.`.
- Arahan inline hanya memengaruhi pesan itu; default sesi/global berlaku selain itu.
- Pesan yang hanya berisi direktif mengalihkan output trace Plugin sesi dan membalas `Plugin trace enabled.` / `Plugin trace disabled.`.
- Direktif sebaris hanya memengaruhi pesan tersebut; default sesi/global berlaku selain itu.
- Kirim `/trace` (atau `/trace:`) tanpa argumen untuk melihat level trace saat ini.
- `/trace` lebih sempit daripada `/verbose`: ini hanya mengekspos baris trace/debug milik Plugin seperti ringkasan debug Active Memory.
- Baris trace dapat muncul di `/status` dan sebagai pesan diagnostik lanjutan setelah balasan asisten normal.
@ -107,38 +108,38 @@ x-i18n:
## Visibilitas penalaran (/reasoning)
- Level: `on|off|stream`.
- Pesan yang hanya berisi arahan mengaktifkan/menonaktifkan apakah blok pemikiran ditampilkan dalam balasan.
- Saat diaktifkan, penalaran dikirim sebagai **pesan terpisah** dengan prefiks `Reasoning:`.
- `stream` (khusus Telegram): mengalirkan penalaran ke bubble draft Telegram saat balasan sedang dibuat, lalu mengirim jawaban akhir tanpa penalaran.
- Pesan yang hanya berisi direktif mengalihkan apakah blok berpikir ditampilkan dalam balasan.
- Ketika diaktifkan, penalaran dikirim sebagai **pesan terpisah** yang diawali dengan `Reasoning:`.
- `stream` (hanya Telegram): men-stream penalaran ke gelembung draf Telegram saat balasan sedang dibuat, lalu mengirim jawaban akhir tanpa penalaran.
- Alias: `/reason`.
- Kirim `/reasoning` (atau `/reasoning:`) tanpa argumen untuk melihat level penalaran saat ini.
- Urutan resolusi: arahan inline, lalu override sesi, lalu default per agen (`agents.list[].reasoningDefault`), lalu fallback (`off`).
- Urutan resolusi: direktif sebaris, lalu override sesi, lalu default per agen (`agents.list[].reasoningDefault`), lalu fallback (`off`).
Tag penalaran model lokal yang salah bentuk ditangani secara konservatif. Blok `<think>...</think>` tertutup tetap tersembunyi pada balasan normal, dan penalaran yang tidak tertutup setelah teks yang sudah terlihat juga disembunyikan. Jika balasan sepenuhnya dibungkus dalam satu tag pembuka yang tidak tertutup dan jika tidak akan dikirim sebagai teks kosong, OpenClaw menghapus tag pembuka yang salah bentuk dan mengirim teks yang tersisa.
Tag penalaran model lokal yang salah bentuk ditangani secara konservatif. Blok `<think>...</think>` yang tertutup tetap disembunyikan pada balasan normal, dan penalaran yang tidak tertutup setelah teks yang sudah terlihat juga disembunyikan. Jika sebuah balasan sepenuhnya dibungkus dalam satu tag pembuka yang tidak tertutup dan jika tidak akan terkirim sebagai teks kosong, OpenClaw menghapus tag pembuka yang salah bentuk dan mengirim teks yang tersisa.
## Terkait
- Dokumentasi mode tinggi tersedia di [Mode tinggi](/id/tools/elevated).
- Dokumentasi mode tinggi ada di [Mode tinggi](/id/tools/elevated).
## Heartbeat
- Isi probe Heartbeat adalah prompt heartbeat yang dikonfigurasi (default: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Arahan inline dalam pesan heartbeat berlaku seperti biasa (tetapi hindari mengubah default sesi dari heartbeat).
- Pengiriman Heartbeat default hanya ke payload akhir. Untuk juga mengirim pesan `Reasoning:` terpisah (saat tersedia), tetapkan `agents.defaults.heartbeat.includeReasoning: true` atau per agen `agents.list[].heartbeat.includeReasoning: true`.
- Isi probe Heartbeat adalah prompt Heartbeat yang dikonfigurasi (default: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Direktif sebaris dalam pesan Heartbeat berlaku seperti biasa (tetapi hindari mengubah default sesi dari Heartbeat).
- Pengiriman Heartbeat default hanya ke payload akhir. Untuk juga mengirim pesan `Reasoning:` terpisah (ketika tersedia), tetapkan `agents.defaults.heartbeat.includeReasoning: true` atau `agents.list[].heartbeat.includeReasoning: true` per agen.
## UI chat web
- Pemilih pemikiran chat web mencerminkan level tersimpan sesi dari penyimpanan/konfigurasi sesi masuk saat halaman dimuat.
- Memilih level lain langsung menulis override sesi melalui `sessions.patch`; ini tidak menunggu pengiriman berikutnya dan bukan override sekali pakai `thinkingOnce`.
- Opsi pertama selalu `Default (<resolved level>)`, dengan default terselesaikan berasal dari profil pemikiran penyedia model sesi aktif ditambah logika fallback yang sama yang digunakan `/status` dan `session_status`.
- Pemilih berpikir chat web mencerminkan level tersimpan sesi dari penyimpanan/konfigurasi sesi masuk saat halaman dimuat.
- Memilih level lain langsung menulis override sesi melalui `sessions.patch`; ini tidak menunggu pengiriman berikutnya dan bukan override `thinkingOnce` sekali pakai.
- Opsi pertama selalu `Default (<resolved level>)`, tempat default yang diselesaikan berasal dari profil berpikir penyedia model sesi aktif plus logika fallback yang sama yang digunakan `/status` dan `session_status`.
- Pemilih menggunakan `thinkingLevels` yang dikembalikan oleh baris/default sesi Gateway, dengan `thinkingOptions` dipertahankan sebagai daftar label lama. UI browser tidak menyimpan daftar regex penyedianya sendiri; Plugin memiliki set level khusus model.
- `/think:<level>` tetap berfungsi dan memperbarui level sesi tersimpan yang sama, sehingga arahan chat dan pemilih tetap sinkron.
- `/think:<level>` tetap berfungsi dan memperbarui level sesi tersimpan yang sama, sehingga direktif chat dan pemilih tetap sinkron.
## Profil penyedia
- Plugin penyedia dapat mengekspos `resolveThinkingProfile(ctx)` untuk mendefinisikan tingkat yang didukung model dan bawaannya.
- Plugin penyedia yang memproksikan model Claude sebaiknya menggunakan kembali `resolveClaudeThinkingProfile(modelId)` dari `openclaw/plugin-sdk/provider-model-shared` agar katalog Anthropic langsung dan proksi tetap selaras.
- Setiap tingkat profil memiliki `id` kanonis yang disimpan (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `adaptive`, atau `max`) dan dapat menyertakan `label` tampilan. Penyedia biner menggunakan `{ id: "low", label: "on" }`.
- Plugin alat yang perlu memvalidasi penggantian berpikir eksplisit sebaiknya menggunakan `api.runtime.agent.resolveThinkingPolicy({ provider, model })` plus `api.runtime.agent.normalizeThinkingLevel(...)`; mereka tidak sebaiknya menyimpan daftar tingkat penyedia/model sendiri.
- Plugin alat dengan akses ke metadata model kustom yang dikonfigurasi dapat meneruskan `catalog` ke `resolveThinkingPolicy` agar opt-in `compat.supportedReasoningEfforts` tercermin dalam validasi sisi Plugin.
- Hook lama yang dipublikasikan (`supportsXHighThinking`, `isBinaryThinking`, dan `resolveDefaultThinkingLevel`) tetap ada sebagai adaptor kompatibilitas, tetapi set tingkat kustom baru sebaiknya menggunakan `resolveThinkingProfile`.
- Plugin penyedia dapat mengekspos `resolveThinkingProfile(ctx)` untuk menentukan level yang didukung model dan bawaan.
- Plugin penyedia yang mem-proxy model Claude harus menggunakan kembali `resolveClaudeThinkingProfile(modelId)` dari `openclaw/plugin-sdk/provider-model-shared` agar katalog Anthropic langsung dan proxy tetap selaras.
- Setiap level profil memiliki `id` kanonis yang disimpan (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `adaptive`, atau `max`) dan dapat menyertakan `label` tampilan. Penyedia biner menggunakan `{ id: "low", label: "on" }`.
- Plugin alat yang perlu memvalidasi override thinking eksplisit harus menggunakan `api.runtime.agent.resolveThinkingPolicy({ provider, model })` plus `api.runtime.agent.normalizeThinkingLevel(...)`; mereka tidak boleh mempertahankan daftar level penyedia/model sendiri.
- Plugin alat dengan akses ke metadata model kustom yang dikonfigurasi dapat meneruskan `catalog` ke `resolveThinkingPolicy` sehingga opt-in `compat.supportedReasoningEfforts` tercermin dalam validasi sisi Plugin.
- Hook legacy yang dipublikasikan (`supportsXHighThinking`, `isBinaryThinking`, dan `resolveDefaultThinkingLevel`) tetap menjadi adaptor kompatibilitas, tetapi kumpulan level kustom baru harus menggunakan `resolveThinkingProfile`.
- Baris/bawaan Gateway mengekspos `thinkingLevels`, `thinkingOptions`, dan `thinkingDefault` agar klien ACP/chat merender id dan label profil yang sama dengan yang digunakan validasi runtime.

363
docs/id/tools/video-generation.md
View File

@ -1,46 +1,45 @@
---
read_when:
- Menghasilkan video melalui agen
- Membuat video melalui agen
- Mengonfigurasi penyedia dan model pembuatan video
- Memahami parameter alat video_generate
sidebarTitle: Video generation
summary: Hasilkan video melalui video_generate dari referensi teks, gambar, atau video di 16 backend penyedia
title: Pembuatan video
x-i18n:
generated_at: "2026-04-30T10:17:50Z"
generated_at: "2026-05-05T01:50:39Z"
model: gpt-5.5
provider: openai
source_hash: c91409057210af560d389513c2049d643c3e1602df51aa9825ceb01571626cdf
source_hash: 6edce39c3006b748d512fec935b81566ae1a121c280248e9e9439edd1f052d83
source_path: tools/video-generation.md
workflow: 16
---
Agen OpenClaw dapat menghasilkan video dari prompt teks, gambar referensi, atau
video yang sudah ada. Enam belas backend penyedia didukung, masing-masing dengan
opsi model, mode input, dan rangkaian fitur yang berbeda. Agen memilih
penyedia yang tepat secara otomatis berdasarkan konfigurasi Anda dan API key
yang tersedia.
opsi model, mode input, dan set fitur yang berbeda. Agen memilih penyedia yang
tepat secara otomatis berdasarkan konfigurasi Anda dan kunci API yang tersedia.
<Note>
Alat `video_generate` hanya muncul ketika setidaknya satu penyedia pembuatan
video tersedia. Jika Anda tidak melihatnya di alat agen Anda, tetapkan API key
video tersedia. Jika Anda tidak melihatnya di alat agen Anda, tetapkan kunci API
penyedia atau konfigurasikan `agents.defaults.videoGenerationModel`.
</Note>
OpenClaw memperlakukan pembuatan video sebagai tiga mode runtime:
- `generate` — permintaan teks-ke-video tanpa media referensi.
- `imageToVideo` — permintaan mencakup satu atau beberapa gambar referensi.
- `videoToVideo` — permintaan mencakup satu atau beberapa video referensi.
- `imageToVideo` — permintaan menyertakan satu atau beberapa gambar referensi.
- `videoToVideo` — permintaan menyertakan satu atau beberapa video referensi.
Penyedia dapat mendukung subset apa pun dari mode tersebut. Alat memvalidasi
Penyedia dapat mendukung subset mana pun dari mode tersebut. Alat memvalidasi
mode aktif sebelum pengiriman dan melaporkan mode yang didukung di `action=list`.
## Mulai cepat
<Steps>
<Step title="Konfigurasikan autentikasi">
Tetapkan API key untuk penyedia yang didukung:
Tetapkan kunci API untuk penyedia yang didukung:
```bash
export GEMINI_API_KEY="your-key"
@ -53,10 +52,10 @@ mode aktif sebelum pengiriman dan melaporkan mode yang didukung di `action=list`
```
</Step>
<Step title="Minta agen">
> Buat video sinematik berdurasi 5 detik tentang lobster ramah yang berselancar saat matahari terbenam.
> Buat video sinematik 5 detik tentang lobster ramah yang berselancar saat matahari terbenam.
Agen memanggil `video_generate` secara otomatis. Tidak diperlukan daftar izin
alat.
Agen memanggil `video_generate` secara otomatis. Tidak perlu memasukkan
alat ke daftar izin.
</Step>
</Steps>
@ -64,37 +63,39 @@ mode aktif sebelum pengiriman dan melaporkan mode yang didukung di `action=list`
## Cara kerja pembuatan asinkron
Pembuatan video bersifat asinkron. Ketika agen memanggil `video_generate` dalam
sesi:
sebuah sesi:
1. OpenClaw mengirimkan permintaan ke penyedia dan langsung mengembalikan id tugas.
2. Penyedia memproses pekerjaan di latar belakang (biasanya 30 detik hingga 5 menit tergantung penyedia dan resolusi).
2. Penyedia memproses pekerjaan di latar belakang (biasanya 30 detik hingga 5 menit bergantung pada penyedia dan resolusi).
3. Ketika video siap, OpenClaw membangunkan sesi yang sama dengan peristiwa penyelesaian internal.
4. Agen memposting video yang selesai kembali ke percakapan asli.
4. Agen memberi tahu pengguna dan melampirkan video yang sudah selesai. Dalam obrolan grup/channel
yang menggunakan pengiriman terlihat hanya melalui alat pesan, agen meneruskan
hasil melalui alat pesan, bukan OpenClaw yang mempostingnya secara langsung.
Saat pekerjaan sedang berjalan, panggilan `video_generate` duplikat dalam sesi
yang sama mengembalikan status tugas saat ini alih-alih memulai pembuatan lain.
Gunakan `openclaw tasks list` atau `openclaw tasks show <taskId>` untuk
Saat sebuah pekerjaan sedang berjalan, panggilan `video_generate` duplikat dalam
sesi yang sama mengembalikan status tugas saat ini, bukan memulai pembuatan
lain. Gunakan `openclaw tasks list` atau `openclaw tasks show <taskId>` untuk
memeriksa progres dari CLI.
Di luar eksekusi agen yang didukung sesi (misalnya, pemanggilan alat langsung),
alat kembali ke pembuatan inline dan mengembalikan jalur media akhir dalam
giliran yang sama.
alat kembali ke pembuatan inline dan mengembalikan path media akhir
pada giliran yang sama.
File video yang dihasilkan disimpan di penyimpanan media yang dikelola OpenClaw
ketika penyedia mengembalikan byte. Batas penyimpanan video yang dihasilkan
default mengikuti batas media video, dan `agents.defaults.mediaMaxMb`
File video yang dihasilkan disimpan di bawah penyimpanan media yang dikelola
OpenClaw ketika penyedia mengembalikan byte. Batas penyimpanan video hasil
pembuatan default mengikuti batas media video, dan `agents.defaults.mediaMaxMb`
menaikkannya untuk render yang lebih besar. Ketika penyedia juga mengembalikan
URL output yang di-host, OpenClaw dapat mengirimkan URL tersebut alih-alih
URL keluaran yang dihosting, OpenClaw dapat mengirimkan URL tersebut alih-alih
menggagalkan tugas jika persistensi lokal menolak file yang terlalu besar.
### Siklus hidup tugas
| Status | Makna |
| ----------- | ------------------------------------------------------------------------------------------------ |
| `queued` | Tugas dibuat, menunggu penyedia menerimanya. |
| `running` | Penyedia sedang memproses (biasanya 30 detik hingga 5 menit tergantung penyedia dan resolusi). |
| Status | Arti |
| ----------- | ------------------------------------------------------------------------------------------------- |
| `queued` | Tugas dibuat, menunggu penyedia menerimanya. |
| `running` | Penyedia sedang memproses (biasanya 30 detik hingga 5 menit bergantung pada penyedia dan resolusi). |
| `succeeded` | Video siap; agen bangun dan mempostingnya ke percakapan. |
| `failed` | Kesalahan penyedia atau waktu habis; agen bangun dengan detail kesalahan. |
| `failed` | Kesalahan atau timeout penyedia; agen bangun dengan detail kesalahan. |
Periksa status dari CLI:
@ -105,58 +106,58 @@ openclaw tasks cancel <taskId>
```
Jika tugas video sudah `queued` atau `running` untuk sesi saat ini,
`video_generate` mengembalikan status tugas yang ada alih-alih memulai yang
baru. Gunakan `action: "status"` untuk memeriksa secara eksplisit tanpa memicu
`video_generate` mengembalikan status tugas yang ada, bukan memulai yang baru.
Gunakan `action: "status"` untuk memeriksa secara eksplisit tanpa memicu
pembuatan baru.
## Penyedia yang didukung
| Penyedia | Model default | Teks | Ref gambar | Ref video | Autentikasi |
| --------------------- | ------------------------------- | :--: | ---------------------------------------------------- | ---------------------------------------------- | ---------------------------------------- |
| Alibaba | `wan2.6-t2v` | ✓ | Ya (URL jarak jauh) | Ya (URL jarak jauh) | `MODELSTUDIO_API_KEY` |
| BytePlus (1.0) | `seedance-1-0-pro-250528` | ✓ | Hingga 2 gambar (hanya model I2V; frame pertama + terakhir) | — | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | ✓ | Hingga 2 gambar (frame pertama + terakhir via peran) | — | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | ✓ | Hingga 9 gambar referensi | Hingga 3 video | `BYTEPLUS_API_KEY` |
| ComfyUI | `workflow` | ✓ | 1 gambar | — | `COMFY_API_KEY` atau `COMFY_CLOUD_API_KEY` |
| DeepInfra | `Pixverse/Pixverse-T2V` | ✓ | — | — | `DEEPINFRA_API_KEY` |
| fal | `fal-ai/minimax/video-01-live` | ✓ | 1 gambar; hingga 9 dengan Seedance referensi-ke-video | Hingga 3 video dengan Seedance referensi-ke-video | `FAL_KEY` |
| Google | `veo-3.1-fast-generate-preview` | ✓ | 1 gambar | 1 video | `GEMINI_API_KEY` |
| MiniMax | `MiniMax-Hailuo-2.3` | ✓ | 1 gambar | — | `MINIMAX_API_KEY` atau MiniMax OAuth |
| OpenAI | `sora-2` | ✓ | 1 gambar | 1 video | `OPENAI_API_KEY` |
| OpenRouter | `google/veo-3.1-fast` | ✓ | Hingga 4 gambar (frame pertama/terakhir atau referensi) | — | `OPENROUTER_API_KEY` |
| Qwen | `wan2.6-t2v` | ✓ | Ya (URL jarak jauh) | Ya (URL jarak jauh) | `QWEN_API_KEY` |
| Runway | `gen4.5` | ✓ | 1 gambar | 1 video | `RUNWAYML_API_SECRET` |
| Together | `Wan-AI/Wan2.2-T2V-A14B` | ✓ | 1 gambar | — | `TOGETHER_API_KEY` |
| Vydra | `veo3` | ✓ | 1 gambar (`kling`) | — | `VYDRA_API_KEY` |
| xAI | `grok-imagine-video` | ✓ | 1 gambar frame pertama atau hingga 7 `reference_image` | 1 video | `XAI_API_KEY` |
| Penyedia | Model default | Teks | Referensi gambar | Referensi video | Autentikasi |
| --------------------- | ------------------------------- | :--: | ---------------------------------------------------- | ----------------------------------------------- | ---------------------------------------- |
| Alibaba | `wan2.6-t2v` | ✓ | Ya (URL jarak jauh) | Ya (URL jarak jauh) | `MODELSTUDIO_API_KEY` |
| BytePlus (1.0) | `seedance-1-0-pro-250528` | ✓ | Hingga 2 gambar (hanya model I2V; frame pertama + terakhir) | — | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | ✓ | Hingga 2 gambar (frame pertama + terakhir melalui peran) | — | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | ✓ | Hingga 9 gambar referensi | Hingga 3 video | `BYTEPLUS_API_KEY` |
| ComfyUI | `workflow` | ✓ | 1 gambar | — | `COMFY_API_KEY` atau `COMFY_CLOUD_API_KEY` |
| DeepInfra | `Pixverse/Pixverse-T2V` | ✓ | — | — | `DEEPINFRA_API_KEY` |
| fal | `fal-ai/minimax/video-01-live` | ✓ | 1 gambar; hingga 9 dengan Seedance referensi-ke-video | Hingga 3 video dengan Seedance referensi-ke-video | `FAL_KEY` |
| Google | `veo-3.1-fast-generate-preview` | ✓ | 1 gambar | 1 video | `GEMINI_API_KEY` |
| MiniMax | `MiniMax-Hailuo-2.3` | ✓ | 1 gambar | — | `MINIMAX_API_KEY` atau OAuth MiniMax |
| OpenAI | `sora-2` | ✓ | 1 gambar | 1 video | `OPENAI_API_KEY` |
| OpenRouter | `google/veo-3.1-fast` | ✓ | Hingga 4 gambar (frame pertama/terakhir atau referensi) | — | `OPENROUTER_API_KEY` |
| Qwen | `wan2.6-t2v` | ✓ | Ya (URL jarak jauh) | Ya (URL jarak jauh) | `QWEN_API_KEY` |
| Runway | `gen4.5` | ✓ | 1 gambar | 1 video | `RUNWAYML_API_SECRET` |
| Together | `Wan-AI/Wan2.2-T2V-A14B` | ✓ | 1 gambar | — | `TOGETHER_API_KEY` |
| Vydra | `veo3` | ✓ | 1 gambar (`kling`) | — | `VYDRA_API_KEY` |
| xAI | `grok-imagine-video` | ✓ | 1 gambar frame pertama atau hingga 7 `reference_image` | 1 video | `XAI_API_KEY` |
Beberapa penyedia menerima variabel env API key tambahan atau alternatif. Lihat
[halaman penyedia](#related) masing-masing untuk detail.
Beberapa penyedia menerima variabel lingkungan kunci API tambahan atau alternatif. Lihat
[halaman penyedia](#related) individual untuk detail.
Jalankan `video_generate action=list` untuk memeriksa penyedia, model, dan
mode runtime yang tersedia saat runtime.
### Matriks kapabilitas
Kontrak mode eksplisit yang digunakan oleh `video_generate`, pengujian kontrak,
dan sweep live bersama:
Kontrak mode eksplisit yang digunakan oleh `video_generate`, pengujian kontrak, dan
sapu live bersama:
| Penyedia | `generate` | `imageToVideo` | `videoToVideo` | Lane live bersama saat ini |
| ---------- | :--------: | :------------: | :------------: | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Alibaba | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` dilewati karena penyedia ini memerlukan URL video `http(s)` jarak jauh |
| BytePlus | ✓ | ✓ | — | `generate`, `imageToVideo` |
| ComfyUI | ✓ | ✓ | — | Tidak ada dalam sweep bersama; cakupan khusus workflow berada di pengujian Comfy |
| DeepInfra | ✓ | — | — | `generate`; skema video DeepInfra native adalah teks-ke-video dalam kontrak bawaan |
| fal | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` hanya saat menggunakan Seedance referensi-ke-video |
| Google | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` bersama dilewati karena sweep Gemini/Veo berbasis buffer saat ini tidak menerima input tersebut |
| MiniMax | ✓ | ✓ | — | `generate`, `imageToVideo` |
| OpenAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` bersama dilewati karena jalur org/input ini saat ini memerlukan akses inpaint/remix sisi penyedia |
| OpenRouter | ✓ | ✓ | — | `generate`, `imageToVideo` |
| Qwen | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` dilewati karena penyedia ini memerlukan URL video `http(s)` jarak jauh |
| Runway | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` hanya berjalan ketika model yang dipilih adalah `runway/gen4_aleph` |
| Together | ✓ | ✓ | — | `generate`, `imageToVideo` |
| Vydra | ✓ | ✓ | — | `generate`; `imageToVideo` bersama dilewati karena `veo3` bawaan hanya teks dan `kling` bawaan memerlukan URL gambar jarak jauh |
| xAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` dilewati karena penyedia ini saat ini memerlukan URL MP4 jarak jauh |
| Penyedia | `generate` | `imageToVideo` | `videoToVideo` | Lane live bersama hari ini |
| ---------- | :--------: | :------------: | :------------: | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Alibaba | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` dilewati karena penyedia ini memerlukan URL video `http(s)` jarak jauh |
| BytePlus | ✓ | ✓ | — | `generate`, `imageToVideo` |
| ComfyUI | ✓ | ✓ | — | Tidak termasuk dalam sapu bersama; cakupan khusus workflow berada bersama pengujian Comfy |
| DeepInfra | ✓ | — | — | `generate`; skema video native DeepInfra adalah teks-ke-video dalam kontrak yang dibundel |
| fal | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` hanya saat menggunakan Seedance referensi-ke-video |
| Google | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` bersama dilewati karena sapu Gemini/Veo berbasis buffer saat ini tidak menerima input tersebut |
| MiniMax | ✓ | ✓ | — | `generate`, `imageToVideo` |
| OpenAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` bersama dilewati karena jalur organisasi/input ini saat ini memerlukan akses inpaint/remix sisi penyedia |
| OpenRouter | ✓ | ✓ | — | `generate`, `imageToVideo` |
| Qwen | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` dilewati karena penyedia ini memerlukan URL video `http(s)` jarak jauh |
| Runway | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` berjalan hanya saat model yang dipilih adalah `runway/gen4_aleph` |
| Together | ✓ | ✓ | — | `generate`, `imageToVideo` |
| Vydra | ✓ | ✓ | — | `generate`; `imageToVideo` bersama dilewati karena `veo3` yang dibundel hanya teks dan `kling` yang dibundel memerlukan URL gambar jarak jauh |
| xAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` dilewati karena penyedia ini saat ini memerlukan URL MP4 jarak jauh |
## Parameter alat
@ -168,36 +169,37 @@ dan sweep live bersama:
### Input konten
<ParamField path="image" type="string">Satu gambar referensi (jalur atau URL).</ParamField>
<ParamField path="image" type="string">Gambar referensi tunggal (path atau URL).</ParamField>
<ParamField path="images" type="string[]">Beberapa gambar referensi (hingga 9).</ParamField>
<ParamField path="imageRoles" type="string[]">
Petunjuk peran opsional per posisi yang sejajar dengan daftar gabungan gambar.
Petunjuk peran opsional per posisi yang sejajar dengan daftar gambar gabungan.
Nilai kanonis: `first_frame`, `last_frame`, `reference_image`.
</ParamField>
<ParamField path="video" type="string">Satu video referensi (jalur atau URL).</ParamField>
<ParamField path="video" type="string">Video referensi tunggal (path atau URL).</ParamField>
<ParamField path="videos" type="string[]">Beberapa video referensi (hingga 4).</ParamField>
<ParamField path="videoRoles" type="string[]">
Petunjuk peran opsional per posisi yang sejajar dengan daftar gabungan video.
Petunjuk peran opsional per posisi yang sejajar dengan daftar video gabungan.
Nilai kanonis: `reference_video`.
</ParamField>
<ParamField path="audioRef" type="string">
Satu audio referensi (jalur atau URL). Digunakan untuk musik latar atau
referensi suara saat penyedia mendukung input audio.
Audio referensi tunggal (path atau URL). Digunakan untuk musik latar atau
referensi suara ketika penyedia mendukung input audio.
</ParamField>
<ParamField path="audioRefs" type="string[]">Beberapa audio referensi (hingga 3).</ParamField>
<ParamField path="audioRoles" type="string[]">
Petunjuk peran opsional per posisi yang sejajar dengan daftar gabungan audio.
Petunjuk peran opsional per posisi yang sejajar dengan daftar audio gabungan.
Nilai kanonis: `reference_audio`.
</ParamField>
<Note>
Petunjuk peran diteruskan ke penyedia apa adanya. Nilai kanonis berasal dari
union `VideoGenerationAssetRole` tetapi penyedia dapat menerima string peran
Petunjuk peran diteruskan apa adanya ke penyedia. Nilai kanonis berasal dari
union `VideoGenerationAssetRole`, tetapi penyedia dapat menerima string peran
tambahan. Array `*Roles` tidak boleh memiliki entri lebih banyak daripada
daftar referensi terkait; kesalahan selisih satu gagal dengan error yang jelas.
Gunakan string kosong untuk membiarkan slot tidak diatur. Untuk xAI, atur setiap peran gambar ke
`reference_image` untuk menggunakan mode pembuatan `reference_images`; hilangkan
peran atau gunakan `first_frame` untuk gambar-ke-video dengan satu gambar.
daftar referensi yang sesuai; kesalahan selisih satu akan gagal dengan pesan
galat yang jelas. Gunakan string kosong untuk membiarkan sebuah slot tidak
diatur. Untuk xAI, atur setiap peran gambar ke `reference_image` untuk
menggunakan mode pembuatan `reference_images`; hilangkan peran atau gunakan
`first_frame` untuk gambar-ke-video dengan satu gambar.
</Note>
### Kontrol gaya
@ -209,17 +211,17 @@ peran atau gunakan `first_frame` untuk gambar-ke-video dengan satu gambar.
<ParamField path="durationSeconds" type="number">
Durasi target dalam detik (dibulatkan ke nilai terdekat yang didukung penyedia).
</ParamField>
<ParamField path="size" type="string">Petunjuk ukuran saat penyedia mendukungnya.</ParamField>
<ParamField path="size" type="string">Petunjuk ukuran ketika penyedia mendukungnya.</ParamField>
<ParamField path="audio" type="boolean">
Aktifkan audio yang dihasilkan dalam output saat didukung. Berbeda dari `audioRef*` (input).
Aktifkan audio yang dibuat dalam output ketika didukung. Berbeda dari `audioRef*` (input).
</ParamField>
<ParamField path="watermark" type="boolean">Aktifkan/nonaktifkan watermark penyedia saat didukung.</ParamField>
<ParamField path="watermark" type="boolean">Alihkan watermark penyedia ketika didukung.</ParamField>
`adaptive` adalah sentinel khusus penyedia: nilai ini diteruskan apa adanya ke
penyedia yang menyatakan `adaptive` dalam kapabilitasnya (misalnya BytePlus
penyedia yang mendeklarasikan `adaptive` dalam kapabilitasnya (misalnya BytePlus
Seedance menggunakannya untuk mendeteksi rasio secara otomatis dari dimensi
gambar input). Penyedia yang tidak menyatakannya menampilkan nilai tersebut melalui
`details.ignoredOverrides` dalam hasil alat sehingga pengabaian terlihat.
gambar input). Penyedia yang tidak mendeklarasikannya menampilkan nilai melalui
`details.ignoredOverrides` dalam hasil alat agar pengabaian tersebut terlihat.
### Lanjutan
@ -231,34 +233,34 @@ gambar input). Penyedia yang tidak menyatakannya menampilkan nilai tersebut mela
<ParamField path="timeoutMs" type="number">Timeout permintaan penyedia opsional dalam milidetik.</ParamField>
<ParamField path="providerOptions" type="object">
Opsi khusus penyedia sebagai objek JSON (misalnya `{"seed": 42, "draft": true}`).
Penyedia yang menyatakan skema bertipe memvalidasi kunci dan tipe; kunci
tidak dikenal atau ketidakcocokan melewati kandidat selama fallback. Penyedia tanpa
skema yang dinyatakan menerima opsi apa adanya. Jalankan `video_generate action=list`
untuk melihat apa yang diterima setiap penyedia.
Penyedia yang mendeklarasikan skema bertipe memvalidasi kunci dan tipe; kunci
yang tidak dikenal atau ketidakcocokan akan melewati kandidat selama fallback.
Penyedia tanpa skema yang dideklarasikan menerima opsi apa adanya. Jalankan
`video_generate action=list` untuk melihat apa yang diterima tiap penyedia.
</ParamField>
<Note>
Tidak semua penyedia mendukung semua parameter. OpenClaw menormalkan durasi ke
nilai terdekat yang didukung penyedia, dan memetakan ulang petunjuk geometri
yang diterjemahkan seperti ukuran-ke-rasio-aspek saat penyedia fallback mengekspos
permukaan kontrol yang berbeda. Override yang benar-benar tidak didukung diabaikan
berdasarkan upaya terbaik dan dilaporkan sebagai peringatan dalam hasil alat.
Batas kapabilitas keras (seperti terlalu banyak input referensi) gagal sebelum
pengiriman. Hasil alat melaporkan pengaturan yang diterapkan; `details.normalization`
mencatat setiap terjemahan dari yang diminta ke yang diterapkan.
yang diterjemahkan seperti ukuran-ke-rasio-aspek ketika penyedia fallback
menyediakan permukaan kontrol yang berbeda. Override yang benar-benar tidak
didukung diabaikan dengan upaya terbaik dan dilaporkan sebagai peringatan dalam
hasil alat. Batas kapabilitas keras (seperti terlalu banyak input referensi)
gagal sebelum pengiriman. Hasil alat melaporkan pengaturan yang diterapkan;
`details.normalization` menangkap setiap terjemahan dari diminta-ke-diterapkan.
</Note>
Input referensi memilih mode runtime:
- Tanpa media referensi → `generate`
- Referensi gambar apa pun → `imageToVideo`
- Referensi video apa pun → `videoToVideo`
- Input audio referensi **tidak** mengubah mode yang diselesaikan; input tersebut diterapkan di
atas mode apa pun yang dipilih referensi gambar/video, dan hanya berfungsi
dengan penyedia yang menyatakan `maxInputAudios`.
- Tidak ada media referensi → `generate`
- Ada referensi gambar → `imageToVideo`
- Ada referensi video → `videoToVideo`
- Input audio referensi **tidak** mengubah mode yang diselesaikan; input tersebut
diterapkan di atas mode apa pun yang dipilih referensi gambar/video, dan hanya
berfungsi dengan penyedia yang mendeklarasikan `maxInputAudios`.
Referensi gambar dan video campuran bukan permukaan kapabilitas bersama yang stabil.
Pilih satu jenis referensi per permintaan.
Utamakan satu jenis referensi per permintaan.
#### Fallback dan opsi bertipe
@ -266,30 +268,30 @@ Beberapa pemeriksaan kapabilitas diterapkan pada lapisan fallback, bukan pada
batas alat, sehingga permintaan yang melampaui batas penyedia utama masih dapat
berjalan pada fallback yang mampu:
- Kandidat aktif yang tidak menyatakan `maxInputAudios` (atau `0`) dilewati saat
permintaan berisi referensi audio; kandidat berikutnya dicoba.
- `maxDurationSeconds` kandidat aktif berada di bawah `durationSeconds` yang diminta
tanpa daftar `supportedDurationSeconds` yang dinyatakan → dilewati.
- Kandidat aktif yang tidak mendeklarasikan `maxInputAudios` (atau `0`) dilewati
ketika permintaan berisi referensi audio; kandidat berikutnya dicoba.
- `maxDurationSeconds` kandidat aktif di bawah `durationSeconds` yang diminta
tanpa daftar `supportedDurationSeconds` yang dideklarasikan → dilewati.
- Permintaan berisi `providerOptions` dan kandidat aktif secara eksplisit
menyatakan skema `providerOptions` bertipe → dilewati jika kunci yang diberikan
tidak ada dalam skema atau tipe nilai tidak cocok. Penyedia tanpa
skema yang dinyatakan menerima opsi apa adanya (pass-through
kompatibel mundur). Penyedia dapat memilih keluar dari semua opsi penyedia dengan
menyatakan skema kosong (`capabilities.providerOptions: {}`), yang
menyebabkan dilewati sama seperti ketidakcocokan tipe.
mendeklarasikan skema `providerOptions` bertipe → dilewati jika kunci yang
diberikan tidak ada dalam skema atau tipe nilai tidak cocok. Penyedia tanpa
skema yang dideklarasikan menerima opsi apa adanya (pass-through yang kompatibel
ke belakang). Penyedia dapat memilih keluar dari semua opsi penyedia dengan
mendeklarasikan skema kosong (`capabilities.providerOptions: {}`), yang
menyebabkan pelewatan yang sama seperti ketidakcocokan tipe.
Alasan dilewati pertama dalam permintaan dicatat pada `warn` sehingga operator melihat kapan
penyedia utama mereka dilewati; pelewatan berikutnya dicatat pada `debug` untuk
menjaga rantai fallback panjang tetap tenang. Jika setiap kandidat dilewati, error
teragregasi menyertakan alasan dilewati untuk masing-masing.
Alasan pelewatan pertama dalam sebuah permintaan dicatat pada `warn` agar operator
melihat ketika penyedia utama mereka dilewati; pelewatan berikutnya dicatat pada
`debug` agar rantai fallback panjang tetap tidak bising. Jika setiap kandidat
dilewati, galat gabungan menyertakan alasan pelewatan untuk masing-masing.
## Tindakan
| Tindakan | Apa yang dilakukan |
| ---------- | --------------------------------------------------------------------------------------------------------------- |
| `generate` | Default. Buat video dari prompt yang diberikan dan input referensi opsional. |
| `status` | Periksa status tugas video yang sedang berjalan untuk sesi saat ini tanpa memulai pembuatan lain. |
| `list` | Tampilkan penyedia, model, dan kapabilitas yang tersedia. |
| Tindakan | Yang dilakukan |
| ---------- | ------------------------------------------------------------------------------------------------------------ |
| `generate` | Default. Membuat video dari prompt yang diberikan dan input referensi opsional. |
| `status` | Memeriksa status tugas video yang sedang berjalan untuk sesi saat ini tanpa memulai pembuatan lain. |
| `list` | Menampilkan penyedia, model, dan kapabilitasnya yang tersedia. |
## Pemilihan model
@ -298,15 +300,14 @@ OpenClaw menyelesaikan model dalam urutan ini:
1. **Parameter alat `model`** — jika agen menentukannya dalam panggilan.
2. **`videoGenerationModel.primary`** dari konfigurasi.
3. **`videoGenerationModel.fallbacks`** secara berurutan.
4. **Deteksi otomatis** — penyedia yang memiliki autentikasi valid, dimulai dengan
penyedia default saat ini, lalu penyedia yang tersisa dalam urutan
alfabetis.
4. **Deteksi otomatis** — penyedia yang memiliki autentikasi valid, dimulai dari
penyedia default saat ini, lalu penyedia yang tersisa dalam urutan alfabetis.
Jika penyedia gagal, kandidat berikutnya dicoba secara otomatis. Jika semua
kandidat gagal, error menyertakan detail dari setiap percobaan.
Jika sebuah penyedia gagal, kandidat berikutnya dicoba secara otomatis. Jika semua
kandidat gagal, galat menyertakan detail dari setiap percobaan.
Atur `agents.defaults.mediaGenerationAutoProviderFallback: false` untuk menggunakan
hanya entri `model`, `primary`, dan `fallbacks` eksplisit.
Atur `agents.defaults.mediaGenerationAutoProviderFallback: false` untuk hanya
menggunakan entri `model`, `primary`, dan `fallbacks` eksplisit.
```json5
{
@ -337,31 +338,31 @@ hanya entri `model`, `primary`, dan `fallbacks` eksplisit.
Model T2V (`*-t2v-*`) tidak menerima input gambar; model I2V dan
model umum `*-pro-*` mendukung satu gambar referensi (frame pertama).
Teruskan gambar secara posisional atau atur `role: "first_frame"`.
ID model T2V secara otomatis dialihkan ke varian I2V terkait
saat gambar diberikan.
Berikan gambar secara posisional atau atur `role: "first_frame"`.
ID model T2V secara otomatis dialihkan ke varian I2V yang sesuai
ketika gambar diberikan.
Kunci `providerOptions` yang didukung: `seed` (angka), `draft` (boolean —
Kunci `providerOptions` yang didukung: `seed` (number), `draft` (boolean —
memaksa 480p), `camera_fixed` (boolean).
</Accordion>
<Accordion title="BytePlus Seedance 1.5">
Memerlukan plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark).
Memerlukan Plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark).
ID penyedia: `byteplus-seedance15`. Model:
`seedance-1-5-pro-251215`.
Menggunakan API `content[]` terpadu. Mendukung paling banyak 2 gambar input
(`first_frame` + `last_frame`). Semua input harus berupa URL `https://`
jarak jauh. Atur `role: "first_frame"` / `"last_frame"` pada setiap gambar, atau
teruskan gambar secara posisional.
jarak jauh. Atur `role: "first_frame"` / `"last_frame"` pada setiap gambar,
atau berikan gambar secara posisional.
`aspectRatio: "adaptive"` mendeteksi rasio secara otomatis dari gambar input.
`audio: true` dipetakan ke `generate_audio`. `providerOptions.seed`
(angka) diteruskan.
(number) diteruskan.
</Accordion>
<Accordion title="BytePlus Seedance 2.0">
Memerlukan plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark).
Memerlukan Plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark).
ID penyedia: `byteplus-seedance2`. Model:
`dreamina-seedance-2-0-260128`,
`dreamina-seedance-2-0-fast-260128`.
@ -374,7 +375,7 @@ hanya entri `model`, `primary`, dan `fallbacks` eksplisit.
`aspectRatio: "adaptive"` mendeteksi rasio secara otomatis dari gambar input.
`audio: true` dipetakan ke `generate_audio`. `providerOptions.seed`
(angka) diteruskan.
(number) diteruskan.
</Accordion>
<Accordion title="ComfyUI">
@ -382,13 +383,13 @@ hanya entri `model`, `primary`, dan `fallbacks` eksplisit.
gambar-ke-video melalui graf yang dikonfigurasi.
</Accordion>
<Accordion title="fal">
Menggunakan alur berbasis antrean untuk pekerjaan jangka panjang. Sebagian besar model video fal
menerima satu referensi gambar. Model referensi-ke-video Seedance 2.0
menerima hingga 9 gambar, 3 video, dan 3 referensi audio, dengan
paling banyak total 12 file referensi.
Menggunakan alur berbasis antrean untuk pekerjaan berjalan lama. Sebagian besar
model video fal menerima satu referensi gambar. Model referensi-ke-video
Seedance 2.0 menerima hingga 9 gambar, 3 video, dan 3 referensi audio, dengan
total paling banyak 12 file referensi.
</Accordion>
<Accordion title="Google (Gemini / Veo)">
Mendukung satu referensi gambar atau satu referensi video.
Mendukung satu gambar atau satu referensi video.
</Accordion>
<Accordion title="MiniMax">
Hanya satu referensi gambar.
@ -400,30 +401,31 @@ hanya entri `model`, `primary`, dan `fallbacks` eksplisit.
</Accordion>
<Accordion title="OpenRouter">
Menggunakan API `/videos` asinkron OpenRouter. OpenClaw mengirimkan
pekerjaan, melakukan polling `polling_url`, dan mengunduh `unsigned_urls` atau
endpoint konten pekerjaan yang didokumentasikan. Default `google/veo-3.1-fast` bawaan
mengiklankan durasi 4/6/8 detik, resolusi `720P`/`1080P`, dan
rasio aspek `16:9`/`9:16`.
pekerjaan, melakukan polling `polling_url`, dan mengunduh `unsigned_urls`
atau endpoint konten pekerjaan yang terdokumentasi. Default
`google/veo-3.1-fast` bawaan mengiklankan durasi 4/6/8 detik, resolusi
`720P`/`1080P`, dan rasio aspek `16:9`/`9:16`.
</Accordion>
<Accordion title="Qwen">
Backend DashScope yang sama seperti Alibaba. Input referensi harus berupa URL
`http(s)` jarak jauh; file lokal ditolak sejak awal.
Backend DashScope yang sama seperti Alibaba. Input referensi harus berupa
URL `http(s)` jarak jauh; file lokal ditolak sejak awal.
</Accordion>
<Accordion title="Runway">
Mendukung file lokal melalui URI data. Video-ke-video memerlukan
`runway/gen4_aleph`. Eksekusi teks saja mengekspos rasio aspek `16:9` dan `9:16`.
`runway/gen4_aleph`. Eksekusi hanya-teks menyediakan rasio aspek `16:9`
dan `9:16`.
</Accordion>
<Accordion title="Together">
Hanya satu referensi gambar.
</Accordion>
<Accordion title="Vydra">
Menggunakan `https://www.vydra.ai/api/v1` secara langsung untuk menghindari redirect
yang menghilangkan autentikasi. `veo3` dibundel sebagai teks-ke-video saja; `kling` memerlukan
URL gambar jarak jauh.
Menggunakan `https://www.vydra.ai/api/v1` secara langsung untuk menghindari
redirect yang menghapus autentikasi. `veo3` dibundel hanya sebagai teks-ke-video;
`kling` memerlukan URL gambar jarak jauh.
</Accordion>
<Accordion title="xAI">
Mendukung teks-ke-video, gambar-ke-video frame pertama tunggal, hingga 7
input `reference_image` melalui `reference_images` xAI, dan alur edit/perpanjang
Mendukung teks-ke-video, gambar-ke-video dengan satu frame pertama, hingga 7
input `reference_image` melalui `reference_images` xAI, serta alur edit/perpanjang
video jarak jauh.
</Accordion>
</AccordionGroup>
@ -457,19 +459,21 @@ capabilities: {
}
```
Kolom agregat datar seperti `maxInputImages` dan `maxInputVideos`
**tidak** cukup untuk menyatakan dukungan mode transformasi. Penyedia harus
mendeklarasikan `generate`, `imageToVideo`, dan `videoToVideo` secara eksplisit agar
pengujian live, pengujian kontrak, dan alat bersama `video_generate` dapat memvalidasi
dukungan mode secara deterministik.
Bidang agregat datar seperti `maxInputImages` dan `maxInputVideos`
**tidak** cukup untuk mengiklankan dukungan mode transformasi. Penyedia
sebaiknya mendeklarasikan `generate`, `imageToVideo`, dan `videoToVideo`
secara eksplisit agar pengujian langsung, pengujian kontrak, dan alat
bersama `video_generate` dapat memvalidasi dukungan mode secara
deterministik.
Ketika satu model dalam sebuah penyedia memiliki dukungan input referensi yang lebih luas daripada
yang lain, gunakan `maxInputImagesByModel`, `maxInputVideosByModel`, atau
`maxInputAudiosByModel` alih-alih menaikkan batas untuk seluruh mode.
Ketika satu model dalam suatu penyedia memiliki dukungan input referensi
yang lebih luas daripada yang lain, gunakan `maxInputImagesByModel`,
`maxInputVideosByModel`, atau `maxInputAudiosByModel` alih-alih menaikkan
batas di seluruh mode.
## Pengujian live
## Pengujian langsung
Cakupan live yang diaktifkan secara eksplisit untuk penyedia bawaan bersama:
Cakupan langsung opsional untuk penyedia bundel bersama:
```bash
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts
@ -481,33 +485,34 @@ Wrapper repo:
pnpm test:live:media video
```
File live ini memuat variabel env penyedia yang hilang dari `~/.profile`, secara default
mengutamakan kunci API live/env sebelum profil autentikasi tersimpan, dan menjalankan
smoke yang aman untuk rilis secara default:
Berkas langsung ini memuat variabel env penyedia yang hilang dari
`~/.profile`, secara default mengutamakan kunci API live/env daripada
profil autentikasi yang tersimpan, dan secara default menjalankan smoke
test yang aman untuk rilis:
- `generate` untuk setiap penyedia non-FAL dalam sweep.
- Prompt lobster satu detik.
- Batas operasi per penyedia dari
`OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` secara default).
FAL bersifat opt-in karena latensi antrean sisi penyedia dapat mendominasi waktu
rilis:
FAL bersifat opsional karena latensi antrean di sisi penyedia dapat
mendominasi waktu rilis:
```bash
pnpm test:live:media video --video-providers fal
```
Atur `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` untuk juga menjalankan
mode transformasi yang dideklarasikan dan dapat dijalankan dengan aman oleh sweep bersama
menggunakan media lokal:
mode transformasi yang dideklarasikan yang dapat dijalankan oleh sweep
bersama secara aman dengan media lokal:
- `imageToVideo` ketika `capabilities.imageToVideo.enabled`.
- `videoToVideo` ketika `capabilities.videoToVideo.enabled` dan
penyedia/model menerima input video lokal berbasis buffer dalam sweep
bersama.
Saat ini lane live `videoToVideo` bersama hanya mencakup `runway` ketika Anda
memilih `runway/gen4_aleph`.
Saat ini lane langsung bersama `videoToVideo` hanya mencakup `runway`
ketika Anda memilih `runway/gen4_aleph`.
## Konfigurasi

123
docs/id/web/dashboard.md
View File

@ -1,19 +1,19 @@
---
read_when:
- Mengubah auth dashboard atau mode eksposur
summary: Akses dan auth dashboard Gateway (Control UI)
title: Dashboard
- Mengubah autentikasi dasbor atau mode eksposur
summary: Akses dan autentikasi dasbor Gateway (Control UI)
title: Dasbor
x-i18n:
generated_at: "2026-04-25T13:59:22Z"
model: gpt-5.4
generated_at: "2026-05-05T01:50:46Z"
model: gpt-5.5
provider: openai
source_hash: 5e0e7c8cebe715f96e7f0e967e9fd86c4c6c54f7cc08a4291b02515fc0933a1a
source_hash: 0e2086587fee6303221663748c3047886a5beae29862d66e2edf78e02bfe3da1
source_path: web/dashboard.md
workflow: 15
workflow: 16
---
Dashboard Gateway adalah Control UI browser yang disajikan di `/` secara default
(timpa dengan `gateway.controlUi.basePath`).
Dasbor Gateway adalah UI Kontrol browser yang secara default disajikan di `/`
(ganti dengan `gateway.controlUi.basePath`).
Buka cepat (Gateway lokal):
@ -23,84 +23,91 @@ Buka cepat (Gateway lokal):
Referensi utama:
- [Control UI](/id/web/control-ui) untuk penggunaan dan kemampuan UI.
- [UI Kontrol](/id/web/control-ui) untuk penggunaan dan kemampuan UI.
- [Tailscale](/id/gateway/tailscale) untuk otomatisasi Serve/Funnel.
- [Permukaan web](/id/web) untuk mode bind dan catatan keamanan.
Authentication diberlakukan pada handshake WebSocket melalui jalur auth gateway
Autentikasi diterapkan pada handshake WebSocket melalui jalur auth gateway
yang dikonfigurasi:
- `connect.params.auth.token`
- `connect.params.auth.password`
- Header identitas Tailscale Serve saat `gateway.auth.allowTailscale: true`
- Header identitas trusted-proxy saat `gateway.auth.mode: "trusted-proxy"`
- header identitas Tailscale Serve ketika `gateway.auth.allowTailscale: true`
- header identitas trusted-proxy ketika `gateway.auth.mode: "trusted-proxy"`
Lihat `gateway.auth` di [Konfigurasi Gateway](/id/gateway/configuration).
Catatan keamanan: Control UI adalah **permukaan admin** (chat, config, persetujuan exec).
Jangan mengeksposnya secara publik. UI menyimpan token URL dashboard di sessionStorage
Catatan keamanan: UI Kontrol adalah **permukaan admin** (chat, config, persetujuan exec).
Jangan ekspos secara publik. UI menyimpan token URL dasbor di sessionStorage
untuk sesi tab browser saat ini dan URL gateway yang dipilih, lalu menghapusnya dari URL setelah dimuat.
Utamakan localhost, Tailscale Serve, atau tunnel SSH.
## Jalur cepat (direkomendasikan)
- Setelah onboarding, CLI otomatis membuka dashboard dan mencetak tautan bersih (tanpa token).
- Buka kembali kapan saja: `openclaw dashboard` (menyalin tautan, membuka browser jika memungkinkan, menampilkan petunjuk SSH jika headless).
- Jika UI meminta auth shared-secret, tempel token atau
password yang dikonfigurasi ke pengaturan Control UI.
- Setelah onboarding, CLI otomatis membuka dasbor dan mencetak tautan bersih (tanpa token).
- Buka ulang kapan saja: `openclaw dashboard` (menyalin tautan, membuka browser jika memungkinkan, menampilkan petunjuk SSH jika headless).
- Jika pengiriman melalui clipboard dan browser gagal, `openclaw dashboard` tetap mencetak
URL bersih dan memberi tahu Anda untuk menggunakan token dari `OPENCLAW_GATEWAY_TOKEN` atau
`gateway.auth.token` sebagai kunci fragmen URL `token`; perintah ini tidak mencetak nilai
token di log.
- Jika UI meminta auth rahasia bersama, tempel token atau
kata sandi yang dikonfigurasi ke pengaturan UI Kontrol.
## Dasar auth (lokal vs remote)
## Dasar auth (lokal vs jarak jauh)
- **Localhost**: buka `http://127.0.0.1:18789/`.
- **Gateway TLS**: saat `gateway.tls.enabled: true`, tautan dashboard/status menggunakan
`https://` dan tautan WebSocket Control UI menggunakan `wss://`.
- **Sumber token shared-secret**: `gateway.auth.token` (atau
`OPENCLAW_GATEWAY_TOKEN`); `openclaw dashboard` dapat meneruskannya melalui URL fragment
untuk bootstrap satu kali, dan Control UI menyimpannya di sessionStorage untuk
sesi tab browser saat ini dan URL gateway yang dipilih, bukan localStorage.
- Jika `gateway.auth.token` dikelola oleh SecretRef, `openclaw dashboard`
mencetak/menyalin/membuka URL tanpa token secara desain. Ini menghindari
mengekspos token yang dikelola secara eksternal di log shell, riwayat clipboard, atau argumen peluncuran browser.
- Jika `gateway.auth.token` dikonfigurasi sebagai SecretRef dan belum di-resolve di
shell Anda saat ini, `openclaw dashboard` tetap mencetak URL tanpa token plus
- **TLS Gateway**: ketika `gateway.tls.enabled: true`, tautan dasbor/status menggunakan
`https://` dan tautan WebSocket UI Kontrol menggunakan `wss://`.
- **Sumber token rahasia bersama**: `gateway.auth.token` (atau
`OPENCLAW_GATEWAY_TOKEN`); `openclaw dashboard` dapat meneruskannya melalui fragmen URL
untuk bootstrap satu kali, dan UI Kontrol menyimpannya di sessionStorage untuk
sesi tab browser saat ini dan URL gateway yang dipilih, bukan di localStorage.
- Jika `gateway.auth.token` dikelola SecretRef, `openclaw dashboard`
sengaja mencetak/menyalin/membuka URL tanpa token. Ini menghindari tereksposnya
token yang dikelola secara eksternal di log shell, riwayat clipboard, atau argumen
peluncuran browser.
- Jika `gateway.auth.token` dikonfigurasi sebagai SecretRef dan belum terselesaikan di
shell Anda saat ini, `openclaw dashboard` tetap mencetak URL tanpa token beserta
panduan penyiapan auth yang dapat ditindaklanjuti.
- **Password shared-secret**: gunakan `gateway.auth.password` (atau
`OPENCLAW_GATEWAY_PASSWORD`) yang dikonfigurasi. Dashboard tidak mempertahankan password antar
reload.
- **Mode pembawa identitas**: Tailscale Serve dapat memenuhi auth Control UI/WebSocket
melalui header identitas saat `gateway.auth.allowTailscale: true`, dan
reverse proxy sadar identitas non-loopback dapat memenuhi
`gateway.auth.mode: "trusted-proxy"`. Dalam mode tersebut dashboard tidak
memerlukan shared secret yang ditempel untuk WebSocket.
- **Bukan localhost**: gunakan Tailscale Serve, bind shared-secret non-loopback, reverse proxy sadar identitas non-loopback dengan
- **Kata sandi rahasia bersama**: gunakan `gateway.auth.password` yang dikonfigurasi (atau
`OPENCLAW_GATEWAY_PASSWORD`). Dasbor tidak mempertahankan kata sandi lintas
pemuatan ulang.
- **Mode yang membawa identitas**: Tailscale Serve dapat memenuhi auth UI Kontrol/WebSocket
melalui header identitas ketika `gateway.auth.allowTailscale: true`, dan reverse proxy
non-loopback yang sadar identitas dapat memenuhi
`gateway.auth.mode: "trusted-proxy"`. Dalam mode tersebut, dasbor tidak
memerlukan rahasia bersama yang ditempel untuk WebSocket.
- **Bukan localhost**: gunakan Tailscale Serve, bind rahasia bersama non-loopback,
reverse proxy non-loopback yang sadar identitas dengan
`gateway.auth.mode: "trusted-proxy"`, atau tunnel SSH. API HTTP tetap menggunakan
auth shared-secret kecuali Anda dengan sengaja menjalankan ingress privat
`gateway.auth.mode: "none"` atau auth HTTP trusted-proxy. Lihat
auth rahasia bersama kecuali Anda sengaja menjalankan
`gateway.auth.mode: "none"` untuk ingress privat atau auth HTTP trusted-proxy. Lihat
[Permukaan web](/id/web).
<a id="if-you-see-unauthorized-1008"></a>
## Jika Anda melihat "unauthorized" / 1008
- Pastikan gateway dapat dijangkau (lokal: `openclaw status`; remote: tunnel SSH `ssh -N -L 18789:127.0.0.1:18789 user@host` lalu buka `http://127.0.0.1:18789/`).
- Untuk `AUTH_TOKEN_MISMATCH`, klien dapat melakukan satu retry tepercaya dengan token perangkat yang di-cache saat gateway mengembalikan petunjuk retry. Retry token ter-cache itu menggunakan kembali cakupan yang telah disetujui dari token; pemanggil `deviceToken` eksplisit / `scopes` eksplisit mempertahankan set cakupan yang diminta. Jika auth masih gagal setelah retry itu, selesaikan token drift secara manual.
- Di luar jalur retry itu, prioritas auth koneksi adalah shared token/password eksplisit terlebih dahulu, lalu `deviceToken` eksplisit, lalu token perangkat tersimpan, lalu token bootstrap.
- Pada jalur Control UI Tailscale Serve async, upaya yang gagal untuk
`{scope, ip}` yang sama diserialkan sebelum limiter auth gagal mencatatnya, sehingga retry buruk serentak kedua mungkin sudah menampilkan `retry later`.
- Untuk langkah perbaikan token drift, ikuti [Checklist pemulihan token drift](/id/cli/devices#token-drift-recovery-checklist).
- Ambil atau sediakan shared secret dari host gateway:
- Pastikan gateway dapat dijangkau (lokal: `openclaw status`; jarak jauh: tunnel SSH `ssh -N -L 18789:127.0.0.1:18789 user@host` lalu buka `http://127.0.0.1:18789/`).
- Untuk `AUTH_TOKEN_MISMATCH`, klien dapat melakukan satu percobaan ulang tepercaya dengan token perangkat yang di-cache ketika gateway mengembalikan petunjuk retry. Retry token yang di-cache tersebut menggunakan ulang cakupan yang disetujui dari cache token; pemanggil `deviceToken` eksplisit / `scopes` eksplisit mempertahankan kumpulan cakupan yang diminta. Jika auth masih gagal setelah retry tersebut, selesaikan drift token secara manual.
- Di luar jalur retry tersebut, prioritas auth koneksi adalah token/kata sandi bersama eksplisit terlebih dahulu, lalu `deviceToken` eksplisit, lalu token perangkat tersimpan, lalu token bootstrap.
- Pada jalur UI Kontrol Tailscale Serve asinkron, percobaan gagal untuk
`{scope, ip}` yang sama diserialkan sebelum limiter auth gagal mencatatnya, sehingga
retry buruk kedua yang bersamaan sudah dapat menampilkan `retry later`.
- Untuk langkah perbaikan drift token, ikuti [Daftar periksa pemulihan drift token](/id/cli/devices#token-drift-recovery-checklist).
- Ambil atau berikan rahasia bersama dari host gateway:
- Token: `openclaw config get gateway.auth.token`
- Password: resolve `gateway.auth.password` atau
`OPENCLAW_GATEWAY_PASSWORD` yang dikonfigurasi
- Token yang dikelola SecretRef: resolve penyedia secret eksternal atau export
- Kata sandi: selesaikan `gateway.auth.password` yang dikonfigurasi atau
`OPENCLAW_GATEWAY_PASSWORD`
- Token yang dikelola SecretRef: selesaikan penyedia rahasia eksternal atau ekspor
`OPENCLAW_GATEWAY_TOKEN` di shell ini, lalu jalankan ulang `openclaw dashboard`
- Tidak ada shared secret yang dikonfigurasi: `openclaw doctor --generate-gateway-token`
- Di pengaturan dashboard, tempel token atau password ke field auth,
lalu sambungkan.
- Pemilih bahasa UI ada di **Overview -> Gateway Access -> Language**.
Ini merupakan bagian dari kartu akses, bukan bagian Appearance.
- Tidak ada rahasia bersama yang dikonfigurasi: `openclaw doctor --generate-gateway-token`
- Di pengaturan dasbor, tempel token atau kata sandi ke kolom auth,
lalu hubungkan.
- Pemilih bahasa UI ada di **Ikhtisar -> Akses Gateway -> Bahasa**.
Ini adalah bagian dari kartu akses, bukan bagian Tampilan.
## Terkait
- [Control UI](/id/web/control-ui)
- [UI Kontrol](/id/web/control-ui)
- [WebChat](/id/web/webchat)