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

chore(i18n): refresh id translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-30 16:32:01 +00:00
parent 3508830227
commit a4d36bc343
19 changed files with 2311 additions and 2218 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -7,47 +7,43 @@ 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-04-30T09:32:30Z"
generated_at: "2026-04-30T16:27:58Z"
model: gpt-5.5
provider: openai
source_hash: 4bbf74f3aeea532738b56b83cd2e1a0a3734bfd453da6636b8be985a28ccc027
source_hash: 999653c9360323d5135e33193c76458cba8c288227de46a6217f1ccbed2a6d34
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 [Otomasi dan tugas](/id/automation) untuk memilih mekanisme yang tepat. Halaman ini adalah buku aktivitas untuk pekerjaan latar belakang, bukan penjadwal.
</Note>
Tugas latar belakang melacak pekerjaan yang berjalan **di luar sesi percakapan utama Anda**: eksekusi ACP, spawn subagen, eksekusi tugas cron terisolasi, dan operasi yang dimulai dari CLI.
Tugas latar belakang melacak pekerjaan yang berjalan **di luar sesi percakapan utama Anda**: eksekusi ACP, spawn subagent, eksekusi cron job terisolasi, dan operasi yang dimulai dari CLI.
Tugas **tidak** menggantikan sesi, cron job, atau Heartbeat — tugas adalah **buku besar aktivitas** yang mencatat pekerjaan terlepas apa yang terjadi, kapan, dan apakah berhasil.
Tugas **tidak** menggantikan sesi, cron job, atau Heartbeat — tugas adalah **buku aktivitas** yang mencatat pekerjaan terlepas apa yang terjadi, kapan, dan apakah berhasil.
<Note>
Tidak setiap eksekusi agen membuat tugas. Giliran Heartbeat dan chat interaktif normal tidak. Semua eksekusi Cron, spawn ACP, spawn subagen, dan perintah agen CLI melakukannya.
Tidak setiap eksekusi agen membuat tugas. Giliran Heartbeat dan chat interaktif normal tidak membuatnya. Semua eksekusi cron, spawn ACP, spawn subagent, dan perintah agen CLI membuatnya.
</Note>
## Ringkasan
## Ringkasnya
- Tugas adalah **rekaman**, bukan penjadwal — Cron dan Heartbeat menentukan _kapan_ pekerjaan berjalan, tugas melacak _apa yang terjadi_.
- ACP, subagen, semua cron job, 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, subagent, semua cron job, 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 job 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 oleh push: pekerjaan terlepas dapat memberi tahu secara langsung atau membangunkan
sesi/Heartbeat peminta saat selesai, jadi loop polling status
biasanya bukan bentuk yang tepat.
- Eksekusi Cron terisolasi dan penyelesaian subagen berupaya sebaik mungkin membersihkan tab/proses browser yang dilacak untuk sesi anaknya sebelum pembukuan pembersihan final.
- Pengiriman Cron terisolasi menekan balasan induk sementara yang basi saat pekerjaan subagen turunan masih dikuras, dan lebih memilih output turunan final saat output itu tiba sebelum pengiriman.
- Tugas cron tetap aktif selama runtime cron masih memiliki job tersebut; jika status runtime dalam memori hilang, pemeliharaan tugas terlebih dahulu memeriksa riwayat eksekusi cron yang tahan lama sebelum menandai tugas sebagai lost.
- Penyelesaian digerakkan oleh push: pekerjaan terlepas dapat memberi tahu secara langsung atau membangunkan sesi peminta/Heartbeat ketika selesai, sehingga loop polling status biasanya bukan bentuk yang tepat.
- Eksekusi cron terisolasi dan penyelesaian subagent melakukan upaya terbaik untuk membersihkan tab/proses browser terlacak untuk sesi anaknya sebelum pembukuan pembersihan akhir.
- Pengiriman cron terisolasi menekan balasan induk sementara yang basi saat pekerjaan subagent turunan masih diselesaikan, dan lebih memilih output turunan akhir ketika itu tiba sebelum pengiriman.
- Notifikasi penyelesaian dikirim langsung ke channel atau diantrekan untuk Heartbeat berikutnya.
- `openclaw tasks list` menampilkan semua tugas; `openclaw tasks audit` memunculkan masalah.
- Rekaman terminal disimpan selama 7 hari, lalu otomatis dipangkas.
- Catatan terminal disimpan selama 7 hari, lalu dipangkas secara otomatis.
## Mulai cepat
<Tabs>
<Tab title="List and filter">
<Tab title="Daftar dan filter">
```bash
# List all tasks (newest first)
openclaw tasks list
@ -58,13 +54,13 @@ Tidak setiap eksekusi agen membuat tugas. Giliran Heartbeat dan chat interaktif
```
</Tab>
<Tab title="Inspect">
<Tab title="Inspeksi">
```bash
# Show details for a specific task (by ID, run ID, or session key)
openclaw tasks show <lookup>
```
</Tab>
<Tab title="Cancel and notify">
<Tab title="Batalkan dan beri tahu">
```bash
# Cancel a running task (kills the child session)
openclaw tasks cancel <lookup>
@ -74,7 +70,7 @@ Tidak setiap eksekusi agen membuat tugas. Giliran Heartbeat dan chat interaktif
```
</Tab>
<Tab title="Audit and maintenance">
<Tab title="Audit dan pemeliharaan">
```bash
# Run a health audit
openclaw tasks audit
@ -85,7 +81,7 @@ Tidak setiap eksekusi agen membuat tugas. Giliran Heartbeat dan chat interaktif
```
</Tab>
<Tab title="Task flow">
<Tab title="Alur tugas">
```bash
# Inspect TaskFlow state
openclaw tasks flow list
@ -97,25 +93,25 @@ Tidak setiap eksekusi agen membuat tugas. Giliran Heartbeat dan chat interaktif
## Apa yang membuat tugas
| Sumber | Jenis runtime | Kapan rekaman tugas dibuat | Kebijakan notifikasi default |
| ---------------------- | ------------ | ------------------------------------------------------ | --------------------- |
| Eksekusi latar belakang ACP | `acp` | Saat men-spawn sesi ACP anak | `done_only` |
| Orkestrasi subagen | `subagent` | Saat men-spawn subagen melalui `sessions_spawn` | `done_only` |
| Cron job (semua jenis) | `cron` | Setiap eksekusi Cron (sesi utama dan terisolasi) | `silent` |
| Operasi CLI | `cli` | Perintah `openclaw agent` yang berjalan melalui Gateway | `silent` |
| Job media agen | `cli` | Eksekusi `video_generate` berbasis sesi | `silent` |
| Sumber | Jenis runtime | Kapan catatan tugas dibuat | Kebijakan notifikasi bawaan |
| ---------------------- | ------------ | ------------------------------------------------------ | --------------------------- |
| Eksekusi latar belakang ACP | `acp` | Men-spawn sesi ACP anak | `done_only` |
| Orkestrasi subagent | `subagent` | Men-spawn subagent melalui `sessions_spawn` | `done_only` |
| Cron job (semua jenis) | `cron` | Setiap eksekusi cron (sesi utama dan terisolasi) | `silent` |
| Operasi CLI | `cli` | Perintah `openclaw agent` yang berjalan melalui Gateway | `silent` |
| Job media agen | `cli` | Eksekusi `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 rekaman untuk pelacakan tetapi tidak menghasilkan notifikasi. Tugas Cron terisolasi juga default ke `silent` tetapi lebih terlihat karena berjalan dalam sesinya sendiri.
<Accordion title="Bawaan notifikasi untuk cron dan media">
Tugas cron sesi utama menggunakan kebijakan notifikasi `silent` secara bawaan — tugas tersebut membuat catatan untuk pelacakan tetapi tidak menghasilkan notifikasi. Tugas cron terisolasi juga menggunakan `silent` secara bawaan tetapi lebih terlihat karena berjalan dalam sesinya sendiri.
Eksekusi `video_generate` berbasis sesi juga menggunakan kebijakan notifikasi `silent`. Eksekusi ini tetap membuat rekaman tugas, tetapi penyelesaian dikembalikan ke sesi agen asli sebagai wake internal agar agen dapat menulis pesan lanjutan dan melampirkan video yang selesai sendiri. Jika Anda ikut memakai `tools.media.asyncCompletion.directSend`, penyelesaian `music_generate` dan `video_generate` async akan mencoba pengiriman channel langsung terlebih dahulu sebelum fallback ke jalur wake sesi peminta.
Eksekusi `video_generate` berbasis sesi juga menggunakan kebijakan notifikasi `silent`. Eksekusi tersebut tetap membuat catatan tugas, tetapi penyelesaian dikembalikan ke sesi agen asli sebagai bangun internal agar agen dapat menulis pesan tindak lanjut dan melampirkan video yang selesai sendiri. Jika Anda ikut serta ke `tools.media.asyncCompletion.directSend`, penyelesaian asinkron `music_generate` dan `video_generate` mencoba pengiriman channel langsung terlebih dahulu sebelum fallback ke jalur bangun sesi peminta.
</Accordion>
<Accordion title="Concurrent video_generate guardrail">
Selama tugas `video_generate` berbasis sesi masih aktif, tool tersebut juga bertindak sebagai pembatas: panggilan `video_generate` berulang dalam sesi yang sama mengembalikan status tugas aktif alih-alih memulai generasi serentak kedua. Gunakan `action: "status"` saat Anda menginginkan lookup progres/status eksplisit dari sisi agen.
<Accordion title="Pembatas pengaman video_generate serentak">
Saat tugas `video_generate` berbasis sesi masih aktif, tool tersebut juga bertindak sebagai pembatas pengaman: panggilan `video_generate` berulang dalam sesi yang sama mengembalikan status tugas aktif alih-alih memulai pembuatan kedua secara serentak. Gunakan `action: "status"` saat Anda menginginkan pencarian progres/status eksplisit dari sisi agen.
</Accordion>
<Accordion title="What does not create tasks">
<Accordion title="Apa yang tidak membuat tugas">
- Giliran Heartbeat — sesi utama; lihat [Heartbeat](/id/gateway/heartbeat)
- Giliran chat interaktif normal
- Respons `/command` langsung
@ -138,57 +134,51 @@ stateDiagram-v2
```
| Status | Artinya |
| ----------- | -------------------------------------------------------------------------- |
| ----------- | -------------------------------------------------------------------- |
| `queued` | Dibuat, menunggu agen mulai |
| `running` | Giliran agen sedang aktif dieksekusi |
| `running` | Giliran agen sedang dieksekusi secara aktif |
| `succeeded` | Selesai dengan sukses |
| `failed` | Selesai dengan error |
| `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 otomatis — saat eksekusi agen terkait berakhir, status tugas diperbarui agar sesuai.
Transisi terjadi otomatis — ketika eksekusi agen terkait berakhir, status tugas diperbarui agar cocok.
Penyelesaian eksekusi agen bersifat otoritatif untuk rekaman tugas aktif. Eksekusi terlepas yang berhasil difinalisasi sebagai `succeeded`, error eksekusi biasa difinalisasi sebagai `failed`, dan hasil timeout atau abort difinalisasi 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 berikutnya tidak menurunkan status terminal tersebut.
Penyelesaian eksekusi agen bersifat otoritatif untuk catatan tugas aktif. Eksekusi terlepas yang berhasil difinalisasi sebagai `succeeded`, kesalahan eksekusi biasa difinalisasi sebagai `failed`, dan hasil timeout atau abort difinalisasi 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.
`lost` sadar-runtime:
`lost` sadar runtime:
- Tugas ACP: metadata sesi ACP anak pendukung menghilang.
- Tugas subagen: sesi anak pendukung menghilang dari store agen target.
- Tugas Cron: runtime Cron tidak lagi melacak job sebagai aktif dan riwayat
eksekusi Cron yang tahan lama tidak menampilkan hasil terminal untuk eksekusi itu. 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 eksekusi langsung, sehingga baris sesi
channel/group/direct yang tersisa tidak membuatnya tetap aktif. Eksekusi
`openclaw agent` berbasis Gateway juga difinalisasi dari hasil eksekusinya, sehingga eksekusi yang selesai
tidak tetap aktif sampai sweeper menandainya `lost`.
- Tugas ACP: metadata sesi anak ACP pendukung menghilang.
- Tugas subagent: sesi anak pendukung menghilang dari penyimpanan agen target.
- Tugas cron: runtime cron tidak lagi melacak job sebagai aktif dan riwayat eksekusi cron yang tahan lama tidak menampilkan hasil terminal untuk eksekusi 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; tugas CLI berbasis chat menggunakan konteks eksekusi langsung sebagai gantinya, sehingga baris sesi channel/grup/langsung yang tersisa tidak membuatnya tetap aktif. Eksekusi `openclaw agent` berbasis Gateway juga difinalisasi dari hasil eksekusinya, sehingga eksekusi yang selesai tidak tetap aktif sampai sweeper menandainya `lost`.
## Pengiriman dan notifikasi
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 tersebut (Telegram, Discord, Slack, dll.). Untuk penyelesaian subagen, OpenClaw juga mempertahankan routing 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 langsung** — jika tugas memiliki target channel (`requesterOrigin`), pesan penyelesaian langsung masuk ke channel tersebut (Telegram, Discord, Slack, dll.). Untuk penyelesaian subagent, 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 asal yang ditetapkan, pembaruan diantrekan sebagai event sistem di sesi peminta dan muncul pada Heartbeat berikutnya.
**Pengiriman antrean sesi** — jika pengiriman langsung gagal atau tidak ada origin yang ditetapkan, pembaruan diantrekan sebagai event sistem di 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 bangun Heartbeat langsung agar Anda melihat hasilnya dengan cepat — Anda tidak perlu menunggu tick Heartbeat terjadwal berikutnya.
</Tip>
Itu berarti alur kerja biasa berbasis push: mulai pekerjaan terlepas sekali, lalu biarkan runtime membangunkan atau memberi tahu Anda saat selesai. Poll status tugas hanya saat Anda memerlukan debugging, intervensi, atau audit eksplisit.
Itu berarti workflow biasanya berbasis push: mulai pekerjaan terlepas sekali, lalu biarkan runtime membangunkan atau memberi tahu Anda saat selesai. Poll status tugas hanya saat Anda membutuhkan debugging, intervensi, atau audit eksplisit.
### Kebijakan notifikasi
Kontrol seberapa banyak kabar yang Anda terima tentang setiap tugas:
Kontrol seberapa banyak Anda mendengar tentang setiap tugas:
| Kebijakan | Yang dikirim |
| --------------------- | ----------------------------------------------------------------------- |
| `done_only` (default) | Hanya status terminal (succeeded, failed, dll.) — **ini adalah default** |
| Kebijakan | Yang dikirim |
| --------------------- | ------------------------------------------------------------------ |
| `done_only` (bawaan) | Hanya status terminal (succeeded, failed, dll.) — **ini adalah bawaan** |
| `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
@ -210,7 +200,7 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks show <lookup>
```
Token lookup menerima ID tugas, ID eksekusi, atau kunci sesi. Menampilkan rekaman lengkap termasuk waktu, status pengiriman, error, 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 +208,7 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks cancel <lookup>
```
Untuk tugas ACP dan subagen, ini mematikan sesi anak. Untuk tugas yang dilacak CLI, pembatalan dicatat di registry tugas (tidak ada handle runtime anak terpisah). Status bertransisi ke `cancelled` dan notifikasi pengiriman dikirim jika berlaku.
Untuk tugas ACP dan subagent, ini menghentikan sesi anak. Untuk tugas yang dilacak CLI, pembatalan dicatat dalam registri tugas (tidak ada handle runtime anak terpisah). Status bertransisi ke `cancelled` dan notifikasi pengiriman dikirim jika berlaku.
</Accordion>
<Accordion title="tasks notify">
@ -233,56 +223,57 @@ openclaw tasks notify <lookup> state_changes
Memunculkan masalah operasional. Temuan juga muncul di `openclaw status` saat masalah terdeteksi.
| Temuan | Tingkat Keparahan | Pemicu |
| ------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------ |
| `stale_queued` | warn | Mengantre selama lebih dari 10 menit |
| `stale_running` | error | Berjalan selama 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 stempel waktu pembersihan |
| `inconsistent_timestamps` | warn | Pelanggaran lini masa (misalnya berakhir sebelum dimulai) |
| Temuan | Tingkat keparahan | Pemicu |
| ------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------- |
| `stale_queued` | warn | Mengantre selama lebih dari 10 menit |
| `stale_running` | error | Berjalan selama lebih dari 30 menit |
| `lost` | warn/error | Kepemilikan tugas yang didukung runtime menghilang; tugas hilang yang dipertahankan memunculkan peringatan hingga `cleanupAfter`, lalu menjadi error |
| `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="pemeliharaan tugas">
<Accordion title="pemeliharaan tasks">
```bash
openclaw tasks maintenance [--json]
openclaw tasks maintenance --apply [--json]
```
Gunakan ini untuk mempratinjau atau menerapkan rekonsiliasi, pemberian stempel pembersihan, dan pemangkasan untuk tugas serta status Task Flow.
Gunakan ini untuk meninjau atau menerapkan rekonsiliasi, pemberian stempel pembersihan, dan pemangkasan untuk tugas dan status Task Flow.
Rekonsiliasi sadar runtime:
- Tugas ACP/subagent memeriksa sesi anak pendukungnya.
- Tugas Cron memeriksa apakah runtime cron masih memiliki job tersebut, lalu memulihkan status terminal dari log proses cron/status job yang dipersistensikan sebelum kembali ke `lost`. Hanya proses Gateway yang berwenang atas set job aktif cron dalam memori; audit CLI offline menggunakan riwayat tahan lama tetapi tidak menandai tugas cron sebagai hilang semata-mata karena Set lokal itu kosong.
- Tugas CLI yang didukung chat memeriksa konteks proses langsung pemiliknya, bukan hanya baris sesi chat.
- Tugas ACP/subagent memeriksa sesi turunan pendukungnya.
- Tugas subagent yang sesi turunannya memiliki tombstone pemulihan-restart ditandai hilang, alih-alih diperlakukan sebagai sesi pendukung yang dapat dipulihkan.
- Tugas Cron memeriksa apakah runtime cron masih memiliki job, lalu memulihkan status terminal dari log eksekusi cron/status job yang dipersistensikan sebelum beralih ke `lost`. Hanya proses Gateway yang otoritatif untuk set job 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 eksekusi langsung pemiliknya, bukan hanya baris sesi chat.
Pembersihan penyelesaian juga sadar runtime:
- Penyelesaian subagent dengan upaya terbaik menutup tab/proses browser yang dilacak untuk sesi anak sebelum pembersihan pengumuman berlanjut.
- Penyelesaian cron terisolasi dengan upaya terbaik menutup tab/proses browser yang dilacak untuk sesi cron sebelum proses sepenuhnya dibongkar.
- Pengiriman cron terisolasi menunggu tindak lanjut subagent turunan saat diperlukan dan menekan teks pengakuan induk yang usang alih-alih mengumumkannya.
- Pengiriman penyelesaian subagent memilih teks asisten terlihat terbaru; jika kosong, pengiriman kembali ke teks alat/toolResult terbaru yang telah disanitasi, dan proses pemanggilan alat yang hanya timeout dapat diringkas menjadi ringkasan progres parsial singkat. Proses terminal yang gagal mengumumkan status kegagalan tanpa memutar ulang teks balasan yang ditangkap.
- Kegagalan pembersihan tidak menutupi hasil tugas yang sebenarnya.
- Penyelesaian subagent berupaya sebaik mungkin menutup tab/proses browser terlacak untuk sesi turunan sebelum pembersihan pengumuman berlanjut.
- Penyelesaian cron terisolasi berupaya sebaik mungkin menutup tab/proses browser terlacak untuk sesi cron sebelum eksekusi sepenuhnya dibongkar.
- Pengiriman cron terisolasi menunggu tindak lanjut subagent turunan bila diperlukan dan menekan teks pengakuan induk yang kedaluwarsa alih-alih mengumumkannya.
- Pengiriman penyelesaian subagent memprioritaskan teks asisten terlihat yang terbaru; jika kosong, ia beralih ke teks tool/toolResult terbaru yang sudah disanitasi, dan eksekusi panggilan tool yang hanya timeout dapat diringkas menjadi ringkasan kemajuan parsial singkat. Eksekusi gagal terminal mengumumkan status kegagalan tanpa memutar ulang teks balasan yang ditangkap.
- Kegagalan pembersihan tidak menyamarkan hasil tugas yang sebenarnya.
</Accordion>
<Accordion title="daftar | tampilkan | batalkan alur tugas">
<Accordion title="daftar | tampilkan | batalkan alur tasks">
```bash
openclaw tasks flow list [--status <status>] [--json]
openclaw tasks flow show <lookup> [--json]
openclaw tasks flow cancel <lookup>
```
Gunakan ini ketika Task Flow pengatur adalah hal yang Anda pedulikan, bukan satu rekaman tugas latar belakang individual.
Gunakan ini ketika Task Flow yang mengorkestrasi adalah hal yang Anda pedulikan, bukan satu catatan tugas latar belakang individual.
</Accordion>
</AccordionGroup>
## Papan tugas chat (`/tasks`)
Gunakan `/tasks` dalam sesi chat apa pun untuk melihat tugas latar belakang yang tertaut ke sesi tersebut. Papan menampilkan tugas aktif dan yang baru selesai dengan detail runtime, status, waktu, dan progres atau error.
Gunakan `/tasks` di sesi chat apa pun untuk melihat tugas latar belakang yang ditautkan ke sesi tersebut. Papan menampilkan tugas aktif dan yang baru selesai dengan runtime, status, waktu, serta detail kemajuan atau error.
Ketika sesi saat ini tidak memiliki tugas tertaut yang terlihat, `/tasks` kembali ke jumlah tugas lokal agen sehingga Anda tetap mendapatkan gambaran umum tanpa membocorkan detail sesi lain.
Ketika sesi saat ini tidak memiliki tugas tertaut yang terlihat, `/tasks` beralih ke jumlah tugas lokal agen sehingga Anda tetap mendapatkan gambaran umum tanpa membocorkan detail sesi lain.
Untuk ledger operator lengkap, gunakan CLI: `openclaw tasks list`.
@ -298,23 +289,22 @@ Ringkasan melaporkan:
- **aktif** — jumlah `queued` + `running`
- **kegagalan** — jumlah `failed` + `timed_out` + `lost`
- **berdasarkanRuntime** — rincian berdasarkan `acp`, `subagent`, `cron`, `cli`
- **byRuntime** — rincian berdasarkan `acp`, `subagent`, `cron`, `cli`
Baik `/status` maupun alat `session_status` menggunakan snapshot tugas yang sadar pembersihan: tugas aktif diprioritaskan, baris selesai yang usang 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 tool `session_status` menggunakan snapshot tugas yang sadar pembersihan: tugas aktif diprioritaskan, baris selesai yang kedaluwarsa 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.
## Penyimpanan dan pemeliharaan
### Tempat tugas berada
Rekaman tugas dipersistensikan di SQLite pada:
Catatan tugas dipersistensikan di SQLite pada:
```
$OPENCLAW_STATE_DIR/tasks/runs.sqlite
```
Registry dimuat ke memori saat gateway dimulai dan menyinkronkan penulisan ke SQLite untuk ketahanan di antara 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 restart.
Gateway menjaga log write-ahead SQLite tetap terbatas dengan menggunakan ambang autocheckpoint default SQLite ditambah checkpoint `TRUNCATE` berkala dan saat shutdown.
### Pemeliharaan otomatis
@ -322,56 +312,56 @@ Sweeper berjalan setiap **60 detik** dan menangani empat hal:
<Steps>
<Step title="Rekonsiliasi">
Memeriksa apakah tugas aktif masih memiliki dukungan runtime yang berwenang. Tugas ACP/subagent menggunakan status sesi anak, tugas cron menggunakan kepemilikan job aktif, dan tugas CLI yang didukung chat menggunakan konteks proses pemiliknya. Jika status pendukung itu hilang selama lebih dari 5 menit, tugas ditandai `lost`.
Memeriksa apakah tugas aktif masih memiliki dukungan runtime otoritatif. Tugas ACP/subagent menggunakan status sesi turunan, tugas cron menggunakan kepemilikan job aktif, dan tugas CLI yang didukung chat menggunakan konteks eksekusi pemiliknya. 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 usang atau yatim 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 kedaluwarsa hanya ketika tidak ada binding percakapan aktif yang tersisa.
</Step>
<Step title="Pemberian stempel pembersihan">
Menetapkan stempel waktu `cleanupAfter` pada tugas terminal (endedAt + 7 hari). Selama retensi, tugas hilang tetap muncul dalam audit sebagai peringatan; setelah `cleanupAfter` kedaluwarsa atau ketika metadata pembersihan hilang, tugas tersebut menjadi error.
Menetapkan stempel waktu `cleanupAfter` pada tugas terminal (endedAt + 7 hari). Selama retensi, tugas yang hilang masih muncul dalam audit sebagai peringatan; setelah `cleanupAfter` kedaluwarsa atau ketika metadata pembersihan hilang, tugas tersebut menjadi error.
</Step>
<Step title="Pemangkasan">
Menghapus rekaman yang melewati tanggal `cleanupAfter`.
Menghapus catatan yang melewati tanggal `cleanupAfter`-nya.
</Step>
</Steps>
<Note>
**Retensi:** rekaman tugas terminal disimpan selama **7 hari**, lalu dipangkas secara otomatis. Tidak perlu konfigurasi.
**Retensi:** catatan tugas terminal disimpan selama **7 hari**, lalu dipangkas secara otomatis. Tidak perlu konfigurasi.
</Note>
## Bagaimana tugas terkait dengan sistem lain
## Bagaimana tugas berkaitan 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 rekaman tugas individual dan `openclaw tasks flow` untuk memeriksa alur pengatur.
[Task Flow](/id/automation/taskflow) adalah lapisan orkestrasi alur di atas tugas latar belakang. Satu alur dapat mengoordinasikan beberapa tugas sepanjang 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.
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 di `~/.openclaw/cron/jobs-state.json`. **Setiap** eksekusi cron membuat rekaman tugas — baik sesi utama maupun terisolasi. Tugas cron sesi utama secara default menggunakan kebijakan notifikasi `silent` sehingga tugas terlacak tanpa menghasilkan notifikasi.
**Definisi** job cron berada di `~/.openclaw/cron/jobs.json`; status eksekusi runtime berada di sampingnya di `~/.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 terlacak tanpa menghasilkan notifikasi.
Lihat [Cron Jobs](/id/automation/cron-jobs).
</Accordion>
<Accordion title="Tugas dan Heartbeat">
Proses Heartbeat adalah giliran sesi utama — proses tersebut tidak membuat rekaman tugas. Ketika tugas selesai, tugas dapat memicu bangun Heartbeat sehingga Anda melihat hasilnya dengan segera.
<Accordion title="Tugas dan heartbeat">
Eksekusi Heartbeat adalah giliran sesi utama — eksekusi tersebut tidak membuat catatan tugas. Ketika tugas selesai, tugas dapat memicu bangun heartbeat sehingga Anda segera melihat hasilnya.
Lihat [Heartbeat](/id/gateway/heartbeat).
</Accordion>
<Accordion title="Tugas dan sesi">
Tugas dapat mereferensikan `childSessionKey` (tempat pekerjaan berjalan) dan `requesterSessionKey` (siapa yang memulainya). Sesi adalah konteks percakapan; tugas adalah pelacakan aktivitas di atasnya.
Tugas dapat mereferensikan `childSessionKey` (tempat pekerjaan berjalan) dan `requesterSessionKey` (pihak yang memulainya). Sesi adalah konteks percakapan; tugas adalah pelacakan aktivitas di atasnya.
</Accordion>
<Accordion title="Tugas dan proses agen">
`runId` milik tugas tertaut ke proses agen yang melakukan pekerjaan. Peristiwa siklus hidup agen (mulai, berakhir, error) secara otomatis memperbarui status tugas — Anda tidak perlu mengelola siklus hidup secara manual.
<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.
</Accordion>
</AccordionGroup>
## Terkait
- [Otomatisasi & Tugas](/id/automation) — semua mekanisme otomatisasi secara sekilas
- [CLI: Tugas](/id/cli/tasks) — referensi perintah CLI
- [Automation & Tasks](/id/automation) — semua mekanisme otomatisasi sekilas
- [CLI: Tasks](/id/cli/tasks) — referensi perintah CLI
- [Heartbeat](/id/gateway/heartbeat) — giliran sesi utama berkala
- [Tugas Terjadwal](/id/automation/cron-jobs) — menjadwalkan pekerjaan latar belakang
- [Scheduled Tasks](/id/automation/cron-jobs) — menjadwalkan pekerjaan latar belakang
- [Task Flow](/id/automation/taskflow) — orkestrasi alur di atas tugas

195
docs/id/channels/groups.md
View File

@ -2,41 +2,41 @@
read_when:
- Mengubah perilaku obrolan grup atau pembatasan penyebutan
sidebarTitle: Groups
summary: Perilaku obrolan grup di berbagai permukaan (Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo)
summary: Perilaku obrolan grup di seluruh permukaan (Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo)
title: Grup
x-i18n:
generated_at: "2026-04-30T09:33:32Z"
generated_at: "2026-04-30T16:27:45Z"
model: gpt-5.5
provider: openai
source_hash: 743dc1ce1a0e5dc5c6d66091854cdcbb8d2b8f7e06b5c1d13c272142265fc998
source_hash: ed9cba03cf4546a20d473e8095a54858530869b27f8934f2680e8dbe987dbf5e
source_path: channels/groups.md
workflow: 16
---
OpenClaw memperlakukan obrolan grup secara konsisten di berbagai platform: Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo.
OpenClaw memperlakukan obrolan grup secara konsisten di seluruh permukaan: Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo.
## Pengantar pemula (2 menit)
OpenClaw "hidup" di akun perpesanan milik Anda sendiri. Tidak ada pengguna bot WhatsApp terpisah. Jika **Anda** berada dalam sebuah grup, OpenClaw dapat melihat grup itu dan merespons di sana.
OpenClaw "hidup" di akun perpesanan Anda sendiri. Tidak ada pengguna bot WhatsApp terpisah. Jika **Anda** berada dalam grup, OpenClaw dapat melihat grup tersebut dan merespons di sana.
Perilaku bawaan:
Perilaku default:
- Grup dibatasi (`groupPolicy: "allowlist"`).
- Balasan memerlukan penyebutan kecuali Anda secara eksplisit menonaktifkan pembatasan penyebutan.
- Balasan akhir normal di grup/channel bersifat privat secara bawaan. Output ruang yang terlihat menggunakan alat `message`.
- Balasan memerlukan mention kecuali Anda secara eksplisit menonaktifkan pembatasan mention.
- Balasan akhir normal di grup/channel bersifat privat secara default. Keluaran ruang yang terlihat menggunakan tool `message`.
Artinya: pengirim yang ada di daftar izin dapat memicu OpenClaw dengan menyebutnya.
Artinya: pengirim yang ada dalam daftar izin dapat memicu OpenClaw dengan menyebutnya.
<Note>
**TL;DR**
- **Akses DM** dikendalikan oleh `*.allowFrom`.
- **Akses grup** dikendalikan oleh `*.groupPolicy` + daftar izin (`*.groups`, `*.groupAllowFrom`).
- **Pemicu balasan** dikendalikan oleh pembatasan penyebutan (`requireMention`, `/activation`).
- **Akses DM** dikontrol oleh `*.allowFrom`.
- **Akses grup** dikontrol oleh `*.groupPolicy` + daftar izin (`*.groups`, `*.groupAllowFrom`).
- **Pemicu balasan** dikontrol oleh pembatasan mention (`requireMention`, `/activation`).
</Note>
Alur cepat (yang terjadi pada pesan grup):
Alur cepat (apa yang terjadi pada pesan grup):
```
groupPolicy? disabled -> drop
@ -45,16 +45,16 @@ requireMention? yes -> mentioned? no -> store for context only
otherwise -> reply
```
## Balasan terlihat
## Balasan yang terlihat
Untuk ruang grup/channel, OpenClaw secara bawaan menggunakan `messages.groupChat.visibleReplies: "message_tool"`.
Artinya agen tetap memproses giliran tersebut dan dapat memperbarui status memori/sesi, tetapi jawaban akhir normalnya tidak otomatis diposting kembali ke ruang. Untuk berbicara secara terlihat, agen menggunakan `message(action=send)`.
Untuk ruang grup/channel, OpenClaw secara default menggunakan `messages.groupChat.visibleReplies: "message_tool"`.
Itu berarti agent tetap memproses giliran dan dapat memperbarui status memori/sesi, tetapi jawaban akhir normalnya tidak otomatis diposting kembali ke ruang. Untuk berbicara secara terlihat, agent menggunakan `message(action=send)`.
Untuk obrolan langsung dan giliran dari sumber lainnya, gunakan `messages.visibleReplies: "message_tool"` untuk menerapkan perilaku balasan terlihat yang hanya melalui alat yang sama secara global. `messages.groupChat.visibleReplies` tetap menjadi override yang lebih spesifik untuk ruang grup/channel.
Untuk obrolan langsung dan giliran sumber lainnya, gunakan `messages.visibleReplies: "message_tool"` untuk menerapkan perilaku balasan terlihat yang hanya melalui tool secara global. `messages.groupChat.visibleReplies` tetap menjadi override yang lebih spesifik untuk ruang grup/channel.
Ini menggantikan pola lama yang memaksa model menjawab `NO_REPLY` untuk sebagian besar giliran mode mengintai. Dalam mode hanya alat, tidak melakukan apa pun yang terlihat berarti tidak memanggil alat message.
Ini menggantikan pola lama yang memaksa model menjawab `NO_REPLY` untuk sebagian besar giliran mode intai. Dalam mode hanya tool, tidak melakukan apa pun yang terlihat berarti tidak memanggil tool message.
Indikator pengetikan tetap dikirim saat agen bekerja dalam mode hanya alat. Mode pengetikan grup bawaan ditingkatkan dari "message" menjadi "instant" untuk giliran ini karena mungkin tidak pernah ada teks pesan asisten normal sebelum agen memutuskan apakah akan memanggil alat message. Konfigurasi mode pengetikan eksplisit tetap menang.
Indikator mengetik tetap dikirim saat agent bekerja dalam mode hanya tool. Mode mengetik grup default ditingkatkan dari "message" menjadi "instant" untuk giliran ini karena mungkin tidak pernah ada teks pesan assistant normal sebelum agent memutuskan apakah akan memanggil tool message. Konfigurasi mode mengetik eksplisit tetap berlaku lebih kuat.
Untuk memulihkan balasan akhir otomatis lama untuk ruang grup/channel:
@ -68,7 +68,10 @@ Untuk memulihkan balasan akhir otomatis lama untuk ruang grup/channel:
}
```
Untuk mewajibkan output terlihat melalui alat message untuk setiap obrolan sumber:
Gateway memuat ulang panas konfigurasi `messages` setelah file disimpan. Mulai ulang hanya
ketika pemantauan file atau pemuatan ulang konfigurasi dinonaktifkan dalam deployment.
Untuk mewajibkan keluaran terlihat melewati tool message untuk setiap obrolan sumber:
```json5
{
@ -78,29 +81,29 @@ Untuk mewajibkan output terlihat melalui alat message untuk setiap obrolan sumbe
}
```
Perintah slash native (Discord, Telegram, dan platform lain dengan dukungan perintah native) melewati `visibleReplies: "message_tool"` dan selalu membalas secara terlihat agar UI perintah native channel mendapatkan respons yang diharapkan. Ini hanya berlaku untuk giliran perintah native yang tervalidasi; perintah `/...` yang diketik sebagai teks dan giliran obrolan biasa tetap mengikuti bawaan grup yang dikonfigurasi.
Perintah slash native (Discord, Telegram, dan permukaan lain dengan dukungan perintah native) melewati `visibleReplies: "message_tool"` dan selalu membalas secara terlihat agar UI perintah native channel mendapatkan respons yang diharapkan. Ini hanya berlaku untuk giliran perintah native yang tervalidasi; perintah `/...` yang diketik sebagai teks dan giliran obrolan biasa tetap mengikuti default grup yang dikonfigurasi.
## Visibilitas konteks dan daftar izin
Dua kontrol berbeda terlibat dalam keamanan grup:
- **Otorisasi pemicu**: siapa yang dapat memicu agen (`groupPolicy`, `groups`, `groupAllowFrom`, daftar izin khusus channel).
- **Visibilitas konteks**: konteks tambahan apa yang disuntikkan ke model (teks balasan, kutipan, riwayat utas, metadata terusan).
- **Otorisasi pemicu**: siapa yang dapat memicu agent (`groupPolicy`, `groups`, `groupAllowFrom`, daftar izin khusus channel).
- **Visibilitas konteks**: konteks tambahan apa yang disuntikkan ke model (teks balasan, kutipan, riwayat thread, metadata terusan).
Secara bawaan, OpenClaw memprioritaskan perilaku obrolan normal dan sebagian besar mempertahankan konteks sebagaimana diterima. Artinya daftar izin terutama menentukan siapa yang dapat memicu tindakan, bukan batas redaksi universal untuk setiap cuplikan kutipan atau riwayat.
Secara default, OpenClaw memprioritaskan perilaku obrolan normal dan mempertahankan konteks sebagian besar seperti yang diterima. Ini berarti daftar izin terutama menentukan siapa yang dapat memicu tindakan, bukan batas redaksi universal untuk setiap cuplikan kutipan atau historis.
<AccordionGroup>
<Accordion title="Perilaku saat ini khusus per channel">
- Beberapa channel sudah menerapkan pemfilteran berbasis pengirim untuk konteks tambahan pada jalur tertentu (misalnya penanaman utas Slack, pencarian balasan/utas Matrix).
- Channel lain masih meneruskan konteks kutipan/balasan/terusan sebagaimana diterima.
<Accordion title="Perilaku saat ini spesifik per channel">
- Beberapa channel sudah menerapkan penyaringan berbasis pengirim untuk konteks tambahan di jalur tertentu (misalnya penyemaian thread Slack, pencarian balasan/thread Matrix).
- Channel lain masih meneruskan konteks kutipan/balasan/terusan seperti yang diterima.
</Accordion>
<Accordion title="Arah pengerasan (direncanakan)">
- `contextVisibility: "all"` (bawaan) mempertahankan perilaku saat ini sebagaimana diterima.
- `contextVisibility: "allowlist"` memfilter konteks tambahan ke pengirim yang ada di daftar izin.
<Accordion title="Arah penguatan (direncanakan)">
- `contextVisibility: "all"` (default) mempertahankan perilaku saat ini seperti yang diterima.
- `contextVisibility: "allowlist"` memfilter konteks tambahan ke pengirim yang ada dalam daftar izin.
- `contextVisibility: "allowlist_quote"` adalah `allowlist` ditambah satu pengecualian kutipan/balasan eksplisit.
Sampai model pengerasan ini diterapkan secara konsisten di seluruh channel, perkirakan adanya perbedaan antar-platform.
Sampai model penguatan ini diterapkan secara konsisten di seluruh channel, perkirakan adanya perbedaan berdasarkan permukaan.
</Accordion>
</AccordionGroup>
@ -109,39 +112,39 @@ Secara bawaan, OpenClaw memprioritaskan perilaku obrolan normal dan sebagian bes
Jika Anda ingin...
| Tujuan | Yang perlu diatur |
| -------------------------------------------- | ---------------------------------------------------------- |
| Izinkan semua grup tetapi hanya balas pada penyebutan @ | `groups: { "*": { requireMention: true } }` |
| Nonaktifkan semua balasan grup | `groupPolicy: "disabled"` |
| Hanya grup tertentu | `groups: { "<group-id>": { ... } }` (tanpa kunci `"*"` ) |
| Hanya Anda yang dapat memicu di grup | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` |
| Tujuan | Yang harus diatur |
| ---------------------------------------------- | ---------------------------------------------------------- |
| Izinkan semua grup tetapi hanya balas pada @mentions | `groups: { "*": { requireMention: true } }` |
| Nonaktifkan semua balasan grup | `groupPolicy: "disabled"` |
| Hanya grup tertentu | `groups: { "<group-id>": { ... } }` (tanpa kunci `"*"` ) |
| Hanya Anda yang dapat memicu di grup | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` |
## Kunci sesi
- Sesi grup menggunakan kunci sesi `agent:<agentId>:<channel>:group:<id>` (ruang/channel menggunakan `agent:<agentId>:<channel>:channel:<id>`).
- Topik forum Telegram menambahkan `:topic:<threadId>` ke id grup sehingga setiap topik memiliki sesinya sendiri.
- Topik forum Telegram menambahkan `:topic:<threadId>` ke id grup sehingga setiap topik memiliki sesi sendiri.
- Obrolan langsung menggunakan sesi utama (atau per-pengirim jika dikonfigurasi).
- Heartbeat dilewati untuk sesi grup.
<a id="pattern-personal-dms-public-groups-single-agent"></a>
## Pola: DM pribadi + grup publik (satu agen)
## Pola: DM pribadi + grup publik (satu agent)
Ya — ini bekerja baik jika lalu lintas "pribadi" Anda adalah **DM** dan lalu lintas "publik" Anda adalah **grup**.
Ya — ini bekerja dengan baik jika trafik "pribadi" Anda adalah **DM** dan trafik "publik" Anda adalah **grup**.
Alasannya: dalam mode satu agen, DM biasanya masuk ke kunci sesi **utama** (`agent:main:main`), sedangkan grup selalu menggunakan kunci sesi **non-utama** (`agent:main:<channel>:group:<id>`). Jika Anda mengaktifkan sandboxing dengan `mode: "non-main"`, sesi grup tersebut berjalan di backend sandbox yang dikonfigurasi sementara sesi DM utama Anda tetap berada di host. Docker adalah backend bawaan jika Anda tidak memilih salah satu.
Mengapa: dalam mode satu agent, DM biasanya masuk ke kunci sesi **utama** (`agent:main:main`), sementara grup selalu menggunakan kunci sesi **non-utama** (`agent:main:<channel>:group:<id>`). Jika Anda mengaktifkan sandboxing dengan `mode: "non-main"`, sesi grup tersebut berjalan di backend sandbox yang dikonfigurasi sementara sesi DM utama Anda tetap berada di host. Docker adalah backend default jika Anda tidak memilih salah satu.
Ini memberi Anda satu "otak" agen (workspace + memori bersama), tetapi dua postur eksekusi:
Ini memberi Anda satu "otak" agent (workspace + memori bersama), tetapi dua postur eksekusi:
- **DM**: alat penuh (host)
- **Grup**: sandbox + alat terbatas
- **DM**: tool penuh (host)
- **Grup**: sandbox + tool terbatas
<Note>
Jika Anda membutuhkan workspace/persona yang benar-benar terpisah ("pribadi" dan "publik" tidak boleh pernah bercampur), gunakan agen kedua + binding. Lihat [Perutean Multi-Agen](/id/concepts/multi-agent).
Jika Anda memerlukan workspace/persona yang benar-benar terpisah ("pribadi" dan "publik" tidak boleh pernah bercampur), gunakan agent kedua + binding. Lihat [Routing Multi-Agent](/id/concepts/multi-agent).
</Note>
<Tabs>
<Tab title="DM di host, grup dalam sandbox">
<Tab title="DM di host, grup disandbox">
```json5
{
agents: {
@ -165,8 +168,8 @@ Jika Anda membutuhkan workspace/persona yang benar-benar terpisah ("pribadi" dan
}
```
</Tab>
<Tab title="Grup hanya melihat folder yang ada di daftar izin">
Ingin "grup hanya dapat melihat folder X" alih-alih "tidak ada akses host"? Pertahankan `workspaceAccess: "none"` dan mount hanya path yang ada di daftar izin ke dalam sandbox:
<Tab title="Grup hanya melihat folder yang ada dalam daftar izin">
Ingin "grup hanya dapat melihat folder X" alih-alih "tidak ada akses host"? Pertahankan `workspaceAccess: "none"` dan mount hanya path yang ada dalam daftar izin ke sandbox:
```json5
{
@ -193,9 +196,9 @@ Jika Anda membutuhkan workspace/persona yang benar-benar terpisah ("pribadi" dan
Terkait:
- Kunci konfigurasi dan bawaan: [Konfigurasi Gateway](/id/gateway/config-agents#agentsdefaultssandbox)
- Debugging alasan alat diblokir: [Sandbox vs Kebijakan Alat vs Ditinggikan](/id/gateway/sandbox-vs-tool-policy-vs-elevated)
- Detail mount bind: [Sandboxing](/id/gateway/sandboxing#custom-bind-mounts)
- Kunci konfigurasi dan default: [Konfigurasi Gateway](/id/gateway/config-agents#agentsdefaultssandbox)
- Men-debug mengapa sebuah tool diblokir: [Sandbox vs Kebijakan Tool vs Elevated](/id/gateway/sandbox-vs-tool-policy-vs-elevated)
- Detail bind mount: [Sandboxing](/id/gateway/sandboxing#custom-bind-mounts)
## Label tampilan
@ -251,24 +254,25 @@ Kontrol bagaimana pesan grup/ruang ditangani per channel:
}
```
| Kebijakan | Perilaku |
| Kebijakan | Perilaku |
| ------------- | ------------------------------------------------------------ |
| `"open"` | Grup melewati daftar izin; pembatasan penyebutan tetap berlaku. |
| `"disabled"` | Blokir semua pesan grup sepenuhnya. |
| `"open"` | Grup melewati daftar izin; pembatasan mention tetap berlaku. |
| `"disabled"` | Blokir semua pesan grup sepenuhnya. |
| `"allowlist"` | Hanya izinkan grup/ruang yang cocok dengan daftar izin yang dikonfigurasi. |
<AccordionGroup>
<Accordion title="Catatan per channel">
- `groupPolicy` terpisah dari pembatasan penyebutan (yang memerlukan penyebutan @).
- `groupPolicy` terpisah dari pembatasan mention (yang memerlukan @mentions).
- WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: gunakan `groupAllowFrom` (fallback: `allowFrom` eksplisit).
- Persetujuan pemasangan DM (entri penyimpanan `*-allowFrom`) hanya berlaku untuk akses DM; otorisasi pengirim grup tetap eksplisit ke daftar izin grup.
- Signal: `groupAllowFrom` dapat mencocokkan id grup Signal masuk atau telepon/UUID pengirim.
- Persetujuan pairing DM (entri penyimpanan `*-allowFrom`) hanya berlaku untuk akses DM; otorisasi pengirim grup tetap eksplisit ke daftar izin grup.
- Discord: daftar izin menggunakan `channels.discord.guilds.<id>.channels`.
- Slack: daftar izin menggunakan `channels.slack.channels`.
- Matrix: daftar izin menggunakan `channels.matrix.groups`. Utamakan ID ruang atau alias; pencarian nama ruang yang telah bergabung bersifat upaya terbaik, dan nama yang tidak terselesaikan diabaikan saat runtime. Gunakan `channels.matrix.groupAllowFrom` untuk membatasi pengirim; daftar izin `users` per ruang juga didukung.
- DM grup dikendalikan secara terpisah (`channels.discord.dm.*`, `channels.slack.dm.*`).
- Daftar izin Telegram dapat cocok dengan ID pengguna (`"123456789"`, `"telegram:123456789"`, `"tg:123456789"`) atau nama pengguna (`"@alice"` atau `"alice"`); prefiks tidak peka huruf besar/kecil.
- Bawaannya adalah `groupPolicy: "allowlist"`; jika daftar izin grup Anda kosong, pesan grup diblokir.
- Keamanan runtime: ketika blok penyedia sepenuhnya tidak ada (`channels.<provider>` tidak ada), kebijakan grup jatuh kembali ke mode gagal-tertutup (biasanya `allowlist`) alih-alih mewarisi `channels.defaults.groupPolicy`.
- Matrix: daftar izin menggunakan `channels.matrix.groups`. Utamakan ID ruang atau alias; pencarian nama ruang yang sudah diikuti bersifat upaya terbaik, dan nama yang tidak terselesaikan diabaikan saat runtime. Gunakan `channels.matrix.groupAllowFrom` untuk membatasi pengirim; daftar izin `users` per ruang juga didukung.
- DM grup dikontrol secara terpisah (`channels.discord.dm.*`, `channels.slack.dm.*`).
- Daftar izin Telegram dapat mencocokkan ID pengguna (`"123456789"`, `"telegram:123456789"`, `"tg:123456789"`) atau nama pengguna (`"@alice"` atau `"alice"`); prefiks tidak peka huruf besar-kecil.
- Default adalah `groupPolicy: "allowlist"`; jika daftar izin grup Anda kosong, pesan grup diblokir.
- Keamanan runtime: ketika blok provider sepenuhnya tidak ada (`channels.<provider>` tidak ada), kebijakan grup kembali ke mode gagal-tertutup (biasanya `allowlist`) alih-alih mewarisi `channels.defaults.groupPolicy`.
</Accordion>
</AccordionGroup>
@ -282,14 +286,14 @@ Model mental cepat (urutan evaluasi untuk pesan grup):
<Step title="Daftar izin grup">
Daftar izin grup (`*.groups`, `*.groupAllowFrom`, daftar izin khusus channel).
</Step>
<Step title="Pembatasan penyebutan">
Pembatasan penyebutan (`requireMention`, `/activation`).
<Step title="Pembatasan mention">
Pembatasan mention (`requireMention`, `/activation`).
</Step>
</Steps>
## Pembatasan penyebutan (bawaan)
## Pembatasan mention (default)
Pesan grup memerlukan penyebutan kecuali dioverride per grup. Bawaan berada per subsistem di bawah `*.groups."*"`.
Pesan grup memerlukan mention kecuali dioverride per grup. Default berada per subsistem di bawah `*.groups."*"`.
Membalas pesan bot dihitung sebagai mention implisit saat channel mendukung metadata balasan. Mengutip pesan bot juga dapat dihitung sebagai mention implisit pada channel yang mengekspos metadata kutipan. Kasus bawaan saat ini mencakup Telegram, WhatsApp, Slack, Discord, Microsoft Teams, dan ZaloUser.
@ -330,39 +334,40 @@ Membalas pesan bot dihitung sebagai mention implisit saat channel mendukung meta
```
<AccordionGroup>
<Accordion title="Catatan pembatasan mention">
<Accordion title="Catatan gerbang mention">
- `mentionPatterns` adalah pola regex aman yang tidak peka huruf besar-kecil; pola yang tidak valid dan bentuk pengulangan bersarang yang tidak aman diabaikan.
- Permukaan yang menyediakan mention eksplisit tetap lolos; pola adalah fallback.
- Override per agen: `agents.list[].groupChat.mentionPatterns` (berguna saat beberapa agen berbagi satu grup).
- Pembatasan mention hanya diberlakukan saat deteksi mention memungkinkan (mention native atau `mentionPatterns` dikonfigurasi).
- Konteks prompt obrolan grup membawa instruksi balasan senyap yang sudah diresolusikan di setiap giliran; file workspace tidak boleh menduplikasi mekanisme `NO_REPLY`.
- Grup yang mengizinkan balasan senyap memperlakukan giliran model yang kosong bersih atau hanya berisi reasoning sebagai senyap, setara dengan `NO_REPLY`. Obrolan langsung melakukan hal yang sama hanya saat balasan senyap langsung diizinkan secara eksplisit; jika tidak, balasan kosong tetap dianggap sebagai giliran agen yang gagal.
- Surface yang menyediakan mention eksplisit tetap lolos; pola adalah cadangan.
- Override per agen: `agents.list[].groupChat.mentionPatterns` (berguna saat beberapa agen berbagi sebuah grup).
- Gerbang mention hanya diterapkan saat deteksi mention memungkinkan (mention native atau `mentionPatterns` dikonfigurasi).
- Memasukkan grup atau pengirim ke allowlist tidak menonaktifkan gerbang mention; atur `requireMention` grup tersebut ke `false` saat semua pesan harus memicu.
- Konteks prompt chat grup membawa instruksi balasan diam yang sudah di-resolve setiap giliran; file workspace tidak boleh menduplikasi mekanik `NO_REPLY`.
- Grup yang mengizinkan balasan diam memperlakukan giliran model yang kosong bersih atau hanya berisi penalaran sebagai diam, setara dengan `NO_REPLY`. Chat langsung melakukan hal yang sama hanya saat balasan diam langsung diizinkan secara eksplisit; jika tidak, balasan kosong tetap menjadi giliran agen yang gagal.
- Default Discord berada di `channels.discord.guilds."*"` (dapat dioverride per guild/channel).
- Konteks riwayat grup dibungkus secara seragam di seluruh channel dan **hanya pending** (pesan yang dilewati karena pembatasan mention); gunakan `messages.groupChat.historyLimit` untuk default global dan `channels.<channel>.historyLimit` (atau `channels.<channel>.accounts.*.historyLimit`) untuk override. Atur `0` untuk menonaktifkan.
- Konteks riwayat grup dibungkus secara seragam di seluruh channel dan **hanya pending** (pesan yang dilewati karena gerbang mention); gunakan `messages.groupChat.historyLimit` untuk default global dan `channels.<channel>.historyLimit` (atau `channels.<channel>.accounts.*.historyLimit`) untuk override. Atur `0` untuk menonaktifkan.
</Accordion>
</AccordionGroup>
## Pembatasan tool grup/channel (opsional)
Beberapa konfigurasi channel mendukung pembatasan tool yang tersedia **di dalam grup/ruang/channel tertentu**.
Beberapa konfigurasi channel mendukung pembatasan tool mana yang tersedia **di dalam grup/room/channel tertentu**.
- `tools`: izinkan/tolak tool untuk seluruh grup.
- `toolsBySender`: override per pengirim di dalam grup. Gunakan prefiks kunci eksplisit: `id:<senderId>`, `e164:<phone>`, `username:<handle>`, `name:<displayName>`, dan wildcard `"*"`. Kunci lama tanpa prefiks masih diterima dan hanya dicocokkan sebagai `id:`.
- `toolsBySender`: override per pengirim di dalam grup. Gunakan prefiks kunci eksplisit: `id:<senderId>`, `e164:<phone>`, `username:<handle>`, `name:<displayName>`, dan wildcard `"*"`. Kunci lama tanpa prefiks masih diterima dan dicocokkan sebagai `id:` saja.
Urutan resolusi (yang paling spesifik menang):
<Steps>
<Step title="toolsBySender grup">
<Step title="Group toolsBySender">
Kecocokan `toolsBySender` grup/channel.
</Step>
<Step title="tools grup">
<Step title="Group tools">
`tools` grup/channel.
</Step>
<Step title="toolsBySender default">
<Step title="Default toolsBySender">
Kecocokan `toolsBySender` default (`"*"`).
</Step>
<Step title="tool default">
<Step title="Default tools">
`tools` default (`"*"`).
</Step>
</Steps>
@ -388,15 +393,15 @@ Contoh (Telegram):
```
<Note>
Pembatasan tool grup/channel diterapkan selain kebijakan tool global/agen (deny tetap menang). Beberapa channel menggunakan nesting yang berbeda untuk ruang/channel (misalnya, Discord `guilds.*.channels.*`, Slack `channels.*`, Microsoft Teams `teams.*.channels.*`).
Pembatasan tool grup/channel diterapkan selain kebijakan tool global/agen (penolakan tetap menang). Beberapa channel menggunakan nesting berbeda untuk room/channel (misalnya, Discord `guilds.*.channels.*`, Slack `channels.*`, Microsoft Teams `teams.*.channels.*`).
</Note>
## Allowlist grup
Saat `channels.whatsapp.groups`, `channels.telegram.groups`, atau `channels.imessage.groups` dikonfigurasi, kunci-kuncinya bertindak sebagai allowlist grup. Gunakan `"*"` untuk mengizinkan semua grup sambil tetap menetapkan perilaku mention default.
Saat `channels.whatsapp.groups`, `channels.telegram.groups`, atau `channels.imessage.groups` dikonfigurasi, kunci bertindak sebagai allowlist grup. Gunakan `"*"` untuk mengizinkan semua grup sambil tetap menetapkan perilaku mention default.
<Warning>
Kebingungan umum: persetujuan pairing DM tidak sama dengan otorisasi grup. Untuk channel yang mendukung pairing DM, penyimpanan pairing hanya membuka kunci DM. Perintah grup tetap memerlukan otorisasi pengirim grup eksplisit dari allowlist konfigurasi seperti `groupAllowFrom` atau fallback konfigurasi terdokumentasi untuk channel tersebut.
Kebingungan umum: persetujuan pairing DM tidak sama dengan otorisasi grup. Untuk channel yang mendukung pairing DM, penyimpanan pairing hanya membuka DM. Perintah grup tetap memerlukan otorisasi pengirim grup eksplisit dari allowlist konfigurasi seperti `groupAllowFrom` atau fallback konfigurasi yang terdokumentasi untuk channel tersebut.
</Warning>
Intent umum (salin/tempel):
@ -423,7 +428,7 @@ Intent umum (salin/tempel):
}
```
</Tab>
<Tab title="Izinkan semua grup tetapi wajibkan mention">
<Tab title="Izinkan semua grup tetapi wajib mention">
```json5
{
channels: {
@ -434,7 +439,7 @@ Intent umum (salin/tempel):
}
```
</Tab>
<Tab title="Pemicu khusus owner (WhatsApp)">
<Tab title="Pemicu hanya owner (WhatsApp)">
```json5
{
channels: {
@ -449,42 +454,42 @@ Intent umum (salin/tempel):
</Tab>
</Tabs>
## Aktivasi (khusus owner)
## Aktivasi (hanya owner)
Owner grup dapat mengaktifkan/menonaktifkan aktivasi per grup:
- `/activation mention`
- `/activation always`
Owner ditentukan oleh `channels.whatsapp.allowFrom` (atau E.164 milik bot sendiri saat tidak diatur). Kirim perintah sebagai pesan mandiri. Permukaan lain saat ini mengabaikan `/activation`.
Owner ditentukan oleh `channels.whatsapp.allowFrom` (atau E.164 mandiri bot saat tidak diatur). Kirim perintah sebagai pesan mandiri. Surface lain saat ini mengabaikan `/activation`.
## Kolom konteks
## Field konteks
Payload masuk grup menetapkan:
Payload masuk grup mengatur:
- `ChatType=group`
- `GroupSubject` (jika diketahui)
- `GroupMembers` (jika diketahui)
- `WasMentioned` (hasil pembatasan mention)
- Topik forum Telegram juga menyertakan `MessageThreadId` dan `IsForum`.
- `WasMentioned` (hasil gerbang mention)
- Topik forum Telegram juga mencakup `MessageThreadId` dan `IsForum`.
Catatan khusus channel:
- BlueBubbles dapat secara opsional memperkaya peserta grup macOS tanpa nama dari basis data Contacts lokal sebelum mengisi `GroupMembers`. Ini nonaktif secara default dan hanya berjalan setelah pembatasan grup normal lolos.
- BlueBubbles dapat secara opsional memperkaya peserta grup macOS tanpa nama dari database Contacts lokal sebelum mengisi `GroupMembers`. Ini nonaktif secara default dan hanya berjalan setelah gerbang grup normal lolos.
Prompt sistem agen menyertakan intro grup pada giliran pertama dari sesi grup baru. Ini mengingatkan model untuk merespons seperti manusia, menghindari tabel Markdown, meminimalkan baris kosong dan mengikuti spasi obrolan normal, serta menghindari pengetikan urutan literal `\n`. Nama grup dan label peserta yang bersumber dari channel dirender sebagai metadata tidak tepercaya berpagar, bukan instruksi sistem inline.
Prompt sistem agen menyertakan intro grup pada giliran pertama sesi grup baru. Ini mengingatkan model untuk merespons seperti manusia, menghindari tabel Markdown, meminimalkan baris kosong dan mengikuti spasi chat normal, serta menghindari pengetikan urutan literal `\n`. Nama grup dan label peserta yang bersumber dari channel dirender sebagai metadata tidak tepercaya berpagar, bukan instruksi sistem inline.
## Spesifik iMessage
## Detail khusus iMessage
- Pilih `chat_id:<id>` saat merutekan atau memasukkan ke allowlist.
- Daftar obrolan: `imsg chats --limit 20`.
- Utamakan `chat_id:<id>` saat merutekan atau memasukkan ke allowlist.
- Daftar chat: `imsg chats --limit 20`.
- Balasan grup selalu kembali ke `chat_id` yang sama.
## Prompt sistem WhatsApp
Lihat [WhatsApp](/id/channels/whatsapp#system-prompts) untuk aturan prompt sistem WhatsApp kanonis, termasuk resolusi prompt grup dan langsung, perilaku wildcard, dan semantik override akun.
## Spesifik WhatsApp
## Detail khusus WhatsApp
Lihat [Pesan grup](/id/channels/group-messages) untuk perilaku khusus WhatsApp (injeksi riwayat, detail penanganan mention).

131
docs/id/channels/signal.md
View File

@ -5,31 +5,31 @@ read_when:
summary: Dukungan Signal melalui signal-cli (JSON-RPC + SSE), jalur penyiapan, dan model nomor
title: Signal
x-i18n:
generated_at: "2026-04-30T09:35:49Z"
generated_at: "2026-04-30T16:27:42Z"
model: gpt-5.5
provider: openai
source_hash: d450454550a86cbf0e2b7231bb149f78275a756517db1f20d7a07e3d298febee
source_hash: 111b6ebe3bde4e03c7ed432f52d663f0b471f0fc4a4bf835c1ac1972467e0b96
source_path: channels/signal.md
workflow: 16
---
Status: integrasi CLI eksternal. Gateway berbicara dengan `signal-cli` melalui HTTP JSON-RPC + SSE.
Status: integrasi CLI eksternal. Gateway berkomunikasi dengan `signal-cli` melalui HTTP JSON-RPC + SSE.
## Prasyarat
- OpenClaw terpasang di server Anda (alur Linux di bawah diuji pada Ubuntu 24).
- `signal-cli` tersedia pada host tempat Gateway berjalan.
- OpenClaw terinstal di server Anda (alur Linux di bawah ini diuji pada Ubuntu 24).
- `signal-cli` tersedia di host tempat gateway berjalan.
- Nomor telepon yang dapat menerima satu SMS verifikasi (untuk jalur pendaftaran SMS).
- Akses browser untuk captcha Signal (`signalcaptchas.org`) selama pendaftaran.
## Penyiapan cepat (pemula)
1. Gunakan **nomor Signal terpisah** untuk bot (direkomendasikan).
2. Pasang `signal-cli` (Java diperlukan jika Anda menggunakan build JVM).
2. Instal `signal-cli` (Java diperlukan jika Anda menggunakan build JVM).
3. Pilih satu jalur penyiapan:
- **Jalur A (tautan QR):** `signal-cli link -n "OpenClaw"` dan pindai dengan Signal.
- **Jalur B (daftar SMS):** daftarkan nomor khusus dengan captcha + verifikasi SMS.
4. Konfigurasikan OpenClaw dan mulai ulang Gateway.
- **Jalur A (tautan QR):** `signal-cli link -n "OpenClaw"` lalu pindai dengan Signal.
- **Jalur B (pendaftaran SMS):** daftarkan nomor khusus dengan captcha + verifikasi SMS.
4. Konfigurasikan OpenClaw dan mulai ulang gateway.
5. Kirim DM pertama dan setujui pemasangan (`openclaw pairing approve signal <CODE>`).
Konfigurasi minimal:
@ -48,18 +48,18 @@ Konfigurasi minimal:
}
```
Referensi bidang:
Referensi kolom:
| Bidang | Deskripsi |
| ----------- | ------------------------------------------------- |
| `account` | Nomor telepon bot dalam format E.164 (`+15551234567`) |
| `cliPath` | Jalur ke `signal-cli` (`signal-cli` jika ada di `PATH`) |
| `dmPolicy` | Kebijakan akses DM (`pairing` direkomendasikan) |
| `allowFrom` | Nomor telepon atau nilai `uuid:<id>` yang diizinkan untuk DM |
| Kolom | Deskripsi |
| ----------- | ----------------------------------------------------------- |
| `account` | Nomor telepon bot dalam format E.164 (`+15551234567`) |
| `cliPath` | Jalur ke `signal-cli` (`signal-cli` jika ada di `PATH`) |
| `dmPolicy` | Kebijakan akses DM (`pairing` direkomendasikan) |
| `allowFrom` | Nomor telepon atau nilai `uuid:<id>` yang diizinkan mengirim DM |
## Apa ini
- Kanal Signal melalui `signal-cli` (bukan libsignal tertanam).
- Channel Signal melalui `signal-cli` (bukan libsignal tertanam).
- Perutean deterministik: balasan selalu kembali ke Signal.
- DM berbagi sesi utama agen; grup diisolasi (`agent:<agentId>:signal:group:<groupId>`).
@ -78,15 +78,15 @@ Nonaktifkan dengan:
## Model nomor (penting)
- Gateway terhubung ke **perangkat Signal** (akun `signal-cli`).
- Jika Anda menjalankan bot pada **akun Signal pribadi Anda**, bot akan mengabaikan pesan Anda sendiri (perlindungan loop).
- Jika Anda menjalankan bot di **akun Signal pribadi Anda**, bot akan mengabaikan pesan Anda sendiri (perlindungan loop).
- Untuk "saya mengirim pesan ke bot dan bot membalas," gunakan **nomor bot terpisah**.
## Jalur penyiapan A: tautkan akun Signal yang ada (QR)
1. Pasang `signal-cli` (build JVM atau native).
1. Instal `signal-cli` (build JVM atau native).
2. Tautkan akun bot:
- `signal-cli link -n "OpenClaw"` lalu pindai QR di Signal.
3. Konfigurasikan Signal dan mulai Gateway.
3. Konfigurasikan Signal dan mulai gateway.
Contoh:
@ -108,11 +108,11 @@ Dukungan multi-akun: gunakan `channels.signal.accounts` dengan konfigurasi per a
## Jalur penyiapan B: daftarkan nomor bot khusus (SMS, Linux)
Gunakan ini ketika Anda menginginkan nomor bot khusus alih-alih menautkan akun aplikasi Signal yang ada.
Gunakan ini saat Anda menginginkan nomor bot khusus alih-alih menautkan akun aplikasi Signal yang sudah ada.
1. Dapatkan nomor yang dapat menerima SMS (atau verifikasi suara untuk telepon rumah).
- Gunakan nomor bot khusus untuk menghindari konflik akun/sesi.
2. Pasang `signal-cli` pada host Gateway:
2. Instal `signal-cli` pada host gateway:
```bash
VERSION=$(curl -Ls -o /dev/null -w %{url_effective} https://github.com/AsamK/signal-cli/releases/latest | sed -e 's/^.*\/v//')
@ -122,8 +122,8 @@ sudo ln -sf /opt/signal-cli /usr/local/bin/
signal-cli --version
```
Jika Anda menggunakan build JVM (`signal-cli-${VERSION}.tar.gz`), pasang JRE 25+ terlebih dahulu.
Tetap perbarui `signal-cli`; upstream mencatat bahwa rilis lama dapat rusak ketika API server Signal berubah.
Jika Anda menggunakan build JVM (`signal-cli-${VERSION}.tar.gz`), instal JRE 25+ terlebih dahulu.
Tetap perbarui `signal-cli`; upstream mencatat bahwa rilis lama dapat rusak saat API server Signal berubah.
3. Daftarkan dan verifikasi nomor:
@ -143,13 +143,13 @@ signal-cli -a +<BOT_PHONE_NUMBER> register --captcha '<SIGNALCAPTCHA_URL>'
signal-cli -a +<BOT_PHONE_NUMBER> verify <VERIFICATION_CODE>
```
4. Konfigurasikan OpenClaw, mulai ulang Gateway, verifikasi kanal:
4. Konfigurasikan OpenClaw, mulai ulang gateway, verifikasi channel:
```bash
# If you run the gateway as a user systemd service:
# Jika Anda menjalankan gateway sebagai layanan systemd pengguna:
systemctl --user restart openclaw-gateway.service
# Then verify:
# Lalu verifikasi:
openclaw doctor
openclaw channels status --probe
```
@ -160,7 +160,7 @@ openclaw channels status --probe
- Simpan nomor bot sebagai kontak di ponsel Anda untuk menghindari "Unknown contact".
<Warning>
Mendaftarkan akun nomor telepon dengan `signal-cli` dapat membatalkan autentikasi sesi aplikasi Signal utama untuk nomor tersebut. Sebaiknya gunakan nomor bot khusus, atau gunakan mode tautan QR jika Anda perlu mempertahankan penyiapan aplikasi ponsel yang ada.
Mendaftarkan akun nomor telepon dengan `signal-cli` dapat mencabut otorisasi sesi aplikasi Signal utama untuk nomor tersebut. Lebih baik gunakan nomor bot khusus, atau gunakan mode tautan QR jika Anda perlu mempertahankan penyiapan aplikasi ponsel yang sudah ada.
</Warning>
Referensi upstream:
@ -171,7 +171,7 @@ Referensi upstream:
## Mode daemon eksternal (httpUrl)
Jika Anda ingin mengelola `signal-cli` sendiri (cold start JVM yang lambat, init container, atau CPU bersama), jalankan daemon secara terpisah dan arahkan OpenClaw ke sana:
Jika Anda ingin mengelola `signal-cli` sendiri (cold start JVM yang lambat, init kontainer, atau CPU bersama), jalankan daemon secara terpisah dan arahkan OpenClaw ke sana:
```json5
{
@ -184,14 +184,14 @@ Jika Anda ingin mengelola `signal-cli` sendiri (cold start JVM yang lambat, init
}
```
Ini melewati auto-spawn dan waktu tunggu startup di dalam OpenClaw. Untuk startup lambat saat auto-spawn, atur `channels.signal.startupTimeoutMs`.
Ini melewati auto-spawn dan waktu tunggu startup di dalam OpenClaw. Untuk start lambat saat auto-spawn, atur `channels.signal.startupTimeoutMs`.
## Kontrol akses (DM + grup)
DM:
- Default: `channels.signal.dmPolicy = "pairing"`.
- Pengirim yang tidak dikenal menerima kode pemasangan; pesan diabaikan hingga disetujui (kode kedaluwarsa setelah 1 jam).
- Pengirim tidak dikenal menerima kode pemasangan; pesan diabaikan hingga disetujui (kode kedaluwarsa setelah 1 jam).
- Setujui melalui:
- `openclaw pairing list signal`
- `openclaw pairing approve signal <CODE>`
@ -201,32 +201,33 @@ DM:
Grup:
- `channels.signal.groupPolicy = open | allowlist | disabled`.
- `channels.signal.groupAllowFrom` mengontrol siapa yang dapat memicu di grup ketika `allowlist` diatur.
- `channels.signal.groups["<group-id>" | "*"]` dapat mengganti perilaku grup dengan `requireMention`, `tools`, dan `toolsBySender`.
- Gunakan `channels.signal.accounts.<id>.groups` untuk penggantian per akun dalam penyiapan multi-akun.
- Catatan runtime: jika `channels.signal` sama sekali tidak ada, runtime kembali ke `groupPolicy="allowlist"` untuk pemeriksaan grup (meskipun `channels.defaults.groupPolicy` diatur).
- `channels.signal.groupAllowFrom` mengontrol grup atau pengirim mana yang dapat memicu balasan grup saat `allowlist` disetel; entri dapat berupa ID grup Signal (mentah, `group:<id>`, atau `signal:group:<id>`), nomor telepon pengirim, nilai `uuid:<id>`, atau `*`.
- `channels.signal.groups["<group-id>" | "*"]` dapat menimpa perilaku grup dengan `requireMention`, `tools`, dan `toolsBySender`.
- Gunakan `channels.signal.accounts.<id>.groups` untuk penimpaan per akun dalam penyiapan multi-akun.
- Memasukkan grup Signal ke allowlist melalui `groupAllowFrom` tidak menonaktifkan gating mention dengan sendirinya. Entri `channels.signal.groups["<group-id>"]` yang dikonfigurasi secara spesifik memproses setiap pesan grup kecuali `requireMention=true` disetel.
- Catatan runtime: jika `channels.signal` sepenuhnya tidak ada, runtime kembali ke `groupPolicy="allowlist"` untuk pemeriksaan grup (meskipun `channels.defaults.groupPolicy` disetel).
## Cara kerjanya (perilaku)
- `signal-cli` berjalan sebagai daemon; Gateway membaca peristiwa melalui SSE.
- Pesan masuk dinormalisasi ke dalam envelope kanal bersama.
- `signal-cli` berjalan sebagai daemon; gateway membaca event melalui SSE.
- Pesan masuk dinormalisasi ke dalam envelope channel bersama.
- Balasan selalu dirutekan kembali ke nomor atau grup yang sama.
## Media + batas
- Teks keluar dipecah menjadi potongan hingga `channels.signal.textChunkLimit` (default 4000).
- Pemecahan opsional berdasarkan baris baru: atur `channels.signal.chunkMode="newline"` untuk memecah pada baris kosong (batas paragraf) sebelum pemecahan berdasarkan panjang.
- Teks keluar dipecah menjadi chunk sesuai `channels.signal.textChunkLimit` (default 4000).
- Chunking baris baru opsional: setel `channels.signal.chunkMode="newline"` untuk membagi pada baris kosong (batas paragraf) sebelum chunking panjang.
- Lampiran didukung (base64 diambil dari `signal-cli`).
- Lampiran catatan suara menggunakan nama file `signal-cli` sebagai fallback MIME ketika `contentType` tidak ada, sehingga transkripsi audio tetap dapat mengklasifikasikan memo suara AAC.
- Lampiran catatan suara menggunakan nama file `signal-cli` sebagai fallback MIME saat `contentType` tidak ada, sehingga transkripsi audio masih dapat mengklasifikasikan memo suara AAC.
- Batas media default: `channels.signal.mediaMaxMb` (default 8).
- Gunakan `channels.signal.ignoreAttachments` untuk melewati pengunduhan media.
- Konteks riwayat grup menggunakan `channels.signal.historyLimit` (atau `channels.signal.accounts.*.historyLimit`), dengan fallback ke `messages.groupChat.historyLimit`. Atur `0` untuk menonaktifkan (default 50).
- Konteks riwayat grup menggunakan `channels.signal.historyLimit` (atau `channels.signal.accounts.*.historyLimit`), dengan fallback ke `messages.groupChat.historyLimit`. Setel `0` untuk menonaktifkan (default 50).
## Indikator mengetik + tanda dibaca
## Pengetikan + tanda terima baca
- **Indikator mengetik**: OpenClaw mengirim sinyal mengetik melalui `signal-cli sendTyping` dan menyegarkannya saat balasan sedang berjalan.
- **Tanda dibaca**: ketika `channels.signal.sendReadReceipts` bernilai true, OpenClaw meneruskan tanda dibaca untuk DM yang diizinkan.
- Signal-cli tidak mengekspos tanda dibaca untuk grup.
- **Indikator pengetikan**: OpenClaw mengirim sinyal mengetik melalui `signal-cli sendTyping` dan menyegarkannya saat balasan sedang berjalan.
- **Tanda terima baca**: saat `channels.signal.sendReadReceipts` bernilai true, OpenClaw meneruskan tanda terima baca untuk DM yang diizinkan.
- Signal-cli tidak mengekspos tanda terima baca untuk grup.
## Reaksi (alat pesan)
@ -248,10 +249,10 @@ Konfigurasi:
- `channels.signal.actions.reactions`: aktifkan/nonaktifkan tindakan reaksi (default true).
- `channels.signal.reactionLevel`: `off | ack | minimal | extensive`.
- `off`/`ack` menonaktifkan reaksi agen (alat pesan `react` akan error).
- `minimal`/`extensive` mengaktifkan reaksi agen dan mengatur tingkat panduan.
- Penggantian per akun: `channels.signal.accounts.<id>.actions.reactions`, `channels.signal.accounts.<id>.reactionLevel`.
- `minimal`/`extensive` mengaktifkan reaksi agen dan menetapkan tingkat panduan.
- Penimpaan per akun: `channels.signal.accounts.<id>.actions.reactions`, `channels.signal.accounts.<id>.reactionLevel`.
## Target pengiriman (CLI/cron)
## Target pengiriman (CLI/Cron)
- DM: `signal:+15551234567` (atau E.164 polos).
- DM UUID: `uuid:<id>` (atau UUID polos).
@ -280,9 +281,9 @@ Kegagalan umum:
- Daemon dapat dijangkau tetapi tidak ada balasan: verifikasi pengaturan akun/daemon (`httpUrl`, `account`) dan mode penerimaan.
- DM diabaikan: pengirim menunggu persetujuan pemasangan.
- Pesan grup diabaikan: pembatasan pengirim/mention grup memblokir pengiriman.
- Pesan grup diabaikan: gating pengirim/mention grup memblokir pengiriman.
- Error validasi konfigurasi setelah pengeditan: jalankan `openclaw doctor --fix`.
- Signal tidak ada dari diagnostik: konfirmasi `channels.signal.enabled: true`.
- Signal hilang dari diagnostik: konfirmasi `channels.signal.enabled: true`.
Pemeriksaan tambahan:
@ -307,27 +308,27 @@ Konfigurasi lengkap: [Konfigurasi](/id/gateway/configuration)
Opsi penyedia:
- `channels.signal.enabled`: aktifkan/nonaktifkan startup saluran.
- `channels.signal.enabled`: aktifkan/nonaktifkan startup channel.
- `channels.signal.account`: E.164 untuk akun bot.
- `channels.signal.cliPath`: jalur ke `signal-cli`.
- `channels.signal.httpUrl`: URL daemon lengkap (menimpa host/port).
- `channels.signal.cliPath`: path ke `signal-cli`.
- `channels.signal.httpUrl`: URL daemon lengkap (mengganti host/port).
- `channels.signal.httpHost`, `channels.signal.httpPort`: bind daemon (default 127.0.0.1:8080).
- `channels.signal.autoStart`: jalankan daemon otomatis (default true jika `httpUrl` tidak diatur).
- `channels.signal.autoStart`: jalankan daemon otomatis (default true jika `httpUrl` tidak disetel).
- `channels.signal.startupTimeoutMs`: batas waktu tunggu startup dalam ms (batas 120000).
- `channels.signal.receiveMode`: `on-start | manual`.
- `channels.signal.ignoreAttachments`: lewati pengunduhan lampiran.
- `channels.signal.ignoreStories`: abaikan cerita dari daemon.
- `channels.signal.ignoreAttachments`: lewati unduhan lampiran.
- `channels.signal.ignoreStories`: abaikan stories dari daemon.
- `channels.signal.sendReadReceipts`: teruskan tanda terima baca.
- `channels.signal.dmPolicy`: `pairing | allowlist | open | disabled` (default: pairing).
- `channels.signal.allowFrom`: daftar izin DM (E.164 atau `uuid:<id>`). `open` memerlukan `"*"`. Signal tidak memiliki nama pengguna; gunakan id telepon/UUID.
- `channels.signal.allowFrom`: daftar izin DM (E.164 atau `uuid:<id>`). `open` memerlukan `"*"`. Signal tidak memiliki nama pengguna; gunakan ID telepon/UUID.
- `channels.signal.groupPolicy`: `open | allowlist | disabled` (default: allowlist).
- `channels.signal.groupAllowFrom`: daftar izin pengirim grup.
- `channels.signal.groups`: penimpaan per grup yang dikunci oleh id grup Signal (atau `"*"`). Bidang yang didukung: `requireMention`, `tools`, `toolsBySender`.
- `channels.signal.groupAllowFrom`: daftar izin grup; menerima ID grup Signal (mentah, `group:<id>`, atau `signal:group:<id>`), nomor E.164 pengirim, atau nilai `uuid:<id>`.
- `channels.signal.groups`: override per grup dengan kunci ID grup Signal (atau `"*"`). Kolom yang didukung: `requireMention`, `tools`, `toolsBySender`.
- `channels.signal.accounts.<id>.groups`: versi per akun dari `channels.signal.groups` untuk penyiapan multi-akun.
- `channels.signal.historyLimit`: jumlah maksimum pesan grup yang disertakan sebagai konteks (0 menonaktifkan).
- `channels.signal.dmHistoryLimit`: batas riwayat DM dalam giliran pengguna. Penimpaan per pengguna: `channels.signal.dms["<phone_or_uuid>"].historyLimit`.
- `channels.signal.dmHistoryLimit`: batas riwayat DM dalam giliran pengguna. Override per pengguna: `channels.signal.dms["<phone_or_uuid>"].historyLimit`.
- `channels.signal.textChunkLimit`: ukuran potongan keluar (karakter).
- `channels.signal.chunkMode`: `length` (default) atau `newline` untuk memecah pada baris kosong (batas paragraf) sebelum pemotongan berdasarkan panjang.
- `channels.signal.chunkMode`: `length` (default) atau `newline` untuk memisahkan pada baris kosong (batas paragraf) sebelum pemotongan berdasarkan panjang.
- `channels.signal.mediaMaxMb`: batas media masuk/keluar (MB).
Opsi global terkait:
@ -338,8 +339,8 @@ Opsi global terkait:
## Terkait
- [Ikhtisar Saluran](/id/channels) — semua saluran yang didukung
- [Pairing](/id/channels/pairing) — autentikasi DM dan alur pairing
- [Ikhtisar Channel](/id/channels) — semua channel yang didukung
- [Penyandingan](/id/channels/pairing) — autentikasi DM dan alur penyandingan
- [Grup](/id/channels/groups) — perilaku chat grup dan gating mention
- [Perutean Saluran](/id/channels/channel-routing) — perutean sesi untuk pesan
- [Keamanan](/id/gateway/security) — model akses dan pengerasan
- [Perutean Channel](/id/channels/channel-routing) — perutean sesi untuk pesan
- [Keamanan](/id/gateway/security) — model akses dan hardening

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

@ -1,43 +1,43 @@
---
read_when:
- Menyiapkan Slack atau men-debug mode socket/HTTP Slack
summary: Penyiapan Slack dan perilaku runtime (Socket Mode + URL Permintaan HTTP)
- Menyiapkan Slack atau memecahkan masalah mode soket/HTTP Slack
summary: Penyiapan Slack dan perilaku runtime (Mode Socket + URL Permintaan HTTP)
title: Slack
x-i18n:
generated_at: "2026-04-30T09:35:53Z"
generated_at: "2026-04-30T16:27:45Z"
model: gpt-5.5
provider: openai
source_hash: 08024bd947ddeb00a1ab3aaa3864cf31817303bbc0523902acdc539fc662e127
source_hash: 55beddb43a6b91c6853dcf053eab713322de4da5beced7c107d73e1c066fded6
source_path: channels/slack.md
workflow: 16
---
Siap produksi untuk DM dan channel melalui integrasi aplikasi Slack. Mode default adalah Socket Mode; HTTP Request URLs juga didukung.
Siap produksi untuk DM dan saluran melalui integrasi aplikasi Slack. Mode bawaan adalah Mode Socket; URL Permintaan HTTP juga didukung.
<CardGroup cols={3}>
<Card title="Penyandingan" icon="link" href="/id/channels/pairing">
DM Slack menggunakan mode penyandingan secara default.
<Card title="Pemasangan" icon="link" href="/id/channels/pairing">
DM Slack secara bawaan menggunakan mode pemasangan.
</Card>
<Card title="Perintah slash" icon="terminal" href="/id/tools/slash-commands">
Perilaku perintah native dan katalog perintah.
</Card>
<Card title="Pemecahan masalah channel" icon="wrench" href="/id/channels/troubleshooting">
Diagnostik lintas-channel dan playbook perbaikan.
<Card title="Pemecahan masalah saluran" icon="wrench" href="/id/channels/troubleshooting">
Diagnostik lintas saluran dan playbook perbaikan.
</Card>
</CardGroup>
## Penyiapan cepat
<Tabs>
<Tab title="Socket Mode (default)">
<Tab title="Mode Socket (bawaan)">
<Steps>
<Step title="Buat aplikasi Slack baru">
Di pengaturan aplikasi Slack, tekan tombol **[Create New App](https://api.slack.com/apps/new)**:
Di pengaturan aplikasi Slack, tekan tombol **[Buat Aplikasi Baru](https://api.slack.com/apps/new)**:
- pilih **from a manifest** dan pilih workspace untuk aplikasi Anda
- tempel [contoh manifest](#manifest-and-scope-checklist) dari bawah ini dan lanjutkan untuk membuat
- buat **App-Level Token** (`xapp-...`) dengan `connections:write`
- instal aplikasi dan salin **Bot Token** (`xoxb-...`) yang ditampilkan
- pilih **dari manifest** dan pilih workspace untuk aplikasi Anda
- tempel [contoh manifest](#manifest-and-scope-checklist) dari bawah dan lanjutkan untuk membuat
- buat **Token Tingkat Aplikasi** (`xapp-...`) dengan `connections:write`
- instal aplikasi dan salin **Token Bot** (`xoxb-...`) yang ditampilkan
</Step>
@ -64,7 +64,7 @@ openclaw config patch --file ./slack.socket.patch.json5 --dry-run
openclaw config patch --file ./slack.socket.patch.json5
```
Fallback env (hanya akun default):
Fallback env (hanya akun bawaan):
```bash
SLACK_APP_TOKEN=xapp-...
@ -84,15 +84,15 @@ openclaw gateway
</Tab>
<Tab title="HTTP Request URLs">
<Tab title="URL Permintaan HTTP">
<Steps>
<Step title="Buat aplikasi Slack baru">
Di pengaturan aplikasi Slack, tekan tombol **[Create New App](https://api.slack.com/apps/new)**:
Di pengaturan aplikasi Slack, tekan tombol **[Buat Aplikasi Baru](https://api.slack.com/apps/new)**:
- pilih **from a manifest** dan pilih workspace untuk aplikasi Anda
- pilih **dari manifest** dan pilih workspace untuk aplikasi Anda
- tempel [contoh manifest](#manifest-and-scope-checklist) dan perbarui URL sebelum membuat
- simpan **Signing Secret** untuk verifikasi permintaan
- instal aplikasi dan salin **Bot Token** (`xoxb-...`) yang ditampilkan
- simpan **Rahasia Penandatanganan** untuk verifikasi permintaan
- instal aplikasi dan salin **Token Bot** (`xoxb-...`) yang ditampilkan
</Step>
@ -121,9 +121,9 @@ openclaw config patch --file ./slack.http.patch.json5
```
<Note>
Gunakan path Webhook yang unik untuk HTTP multi-akun
Gunakan jalur Webhook unik untuk HTTP multi-akun
Berikan setiap akun `webhookPath` yang berbeda (default `/slack/events`) agar pendaftaran tidak bertabrakan.
Berikan setiap akun `webhookPath` yang berbeda (bawaan `/slack/events`) agar pendaftaran tidak bertabrakan.
</Note>
</Step>
@ -140,9 +140,9 @@ openclaw gateway
</Tab>
</Tabs>
## Penyesuaian transport Socket Mode
## Penalaan transport Mode Socket
OpenClaw menetapkan timeout pong klien Slack SDK ke 15 detik secara default untuk Socket Mode. Timpa pengaturan transport hanya ketika Anda memerlukan penyesuaian khusus workspace atau host:
OpenClaw menetapkan batas waktu pong klien SDK Slack ke 15 detik secara bawaan untuk Mode Socket. Timpa pengaturan transport hanya saat Anda membutuhkan penalaan khusus workspace atau host:
```json5
{
@ -159,13 +159,13 @@ OpenClaw menetapkan timeout pong klien Slack SDK ke 15 detik secara default untu
}
```
Gunakan ini hanya untuk workspace Socket Mode yang mencatat timeout pong websocket Slack/server-ping, atau berjalan di host dengan starvation event-loop yang diketahui. `clientPingTimeout` adalah waktu tunggu pong setelah SDK mengirim client ping; `serverPingTimeout` adalah waktu tunggu untuk ping server Slack. Pesan dan peristiwa aplikasi tetap merupakan status aplikasi, bukan sinyal keaktifan transport.
Gunakan ini hanya untuk workspace Mode Socket yang mencatat batas waktu pong websocket/ping server Slack atau berjalan pada host dengan kelaparan event loop yang diketahui. `clientPingTimeout` adalah waktu tunggu pong setelah SDK mengirim ping klien; `serverPingTimeout` adalah waktu tunggu untuk ping server Slack. Pesan dan kejadian aplikasi tetap menjadi status aplikasi, bukan sinyal keaktifan transport.
## Checklist manifest dan scope
## Daftar periksa manifest dan cakupan
Manifest dasar aplikasi Slack sama untuk Socket Mode dan HTTP Request URLs. Hanya blok `settings` (dan `url` perintah slash) yang berbeda.
Manifest dasar aplikasi Slack sama untuk Mode Socket dan URL Permintaan HTTP. Hanya blok `settings` (dan `url` perintah slash) yang berbeda.
Manifest dasar (default Socket Mode):
Manifest dasar (Mode Socket bawaan):
```json
{
@ -237,7 +237,7 @@ Manifest dasar (default Socket Mode):
}
```
Untuk mode **HTTP Request URLs**, ganti `settings` dengan varian HTTP dan tambahkan `url` ke setiap perintah slash. URL publik diperlukan:
Untuk **mode URL Permintaan HTTP**, ganti `settings` dengan varian HTTP dan tambahkan `url` ke setiap perintah slash. URL publik diperlukan:
```json
{
@ -269,20 +269,20 @@ Untuk mode **HTTP Request URLs**, ganti `settings` dengan varian HTTP dan tambah
### Pengaturan manifest tambahan
Tampilkan fitur berbeda yang memperluas default di atas.
Munculkan fitur berbeda yang memperluas bawaan di atas.
<AccordionGroup>
<Accordion title="Perintah slash native opsional">
Beberapa [perintah slash native](#commands-and-slash-behavior) dapat digunakan sebagai pengganti satu perintah terkonfigurasi dengan nuansa:
- Gunakan `/agentstatus` alih-alih `/status` karena perintah `/status` dicadangkan.
- Gunakan `/agentstatus` sebagai pengganti `/status` karena perintah `/status` dicadangkan.
- Tidak lebih dari 25 perintah slash dapat tersedia sekaligus.
Ganti bagian `features.slash_commands` yang ada dengan subset dari [perintah yang tersedia](/id/tools/slash-commands#command-list):
Ganti bagian `features.slash_commands` yang sudah ada dengan subset [perintah yang tersedia](/id/tools/slash-commands#command-list):
<Tabs>
<Tab title="Socket Mode (default)">
<Tab title="Mode Socket (bawaan)">
```json
"slash_commands": [
@ -398,8 +398,8 @@ Tampilkan fitur berbeda yang memperluas default di atas.
```
</Tab>
<Tab title="HTTP Request URLs">
Gunakan daftar `slash_commands` yang sama seperti Socket Mode di atas, dan tambahkan `"url": "https://gateway-host.example.com/slack/events"` ke setiap entri. Contoh:
<Tab title="URL Permintaan HTTP">
Gunakan daftar `slash_commands` yang sama seperti Mode Socket di atas, dan tambahkan `"url": "https://gateway-host.example.com/slack/events"` ke setiap entri. Contoh:
```json
"slash_commands": [
@ -422,14 +422,14 @@ Tampilkan fitur berbeda yang memperluas default di atas.
</Tabs>
</Accordion>
<Accordion title="Scope atribusi opsional (operasi tulis)">
Tambahkan scope bot `chat:write.customize` jika Anda ingin pesan keluar menggunakan identitas agen aktif (nama pengguna dan ikon kustom), bukan identitas aplikasi Slack default.
<Accordion title="Cakupan kepengarangan opsional (operasi tulis)">
Tambahkan cakupan bot `chat:write.customize` jika Anda ingin pesan keluar menggunakan identitas agen aktif (nama pengguna dan ikon kustom) alih-alih identitas aplikasi Slack bawaan.
Jika Anda menggunakan ikon emoji, Slack mengharapkan sintaks `:emoji_name:`.
</Accordion>
<Accordion title="Scope token pengguna opsional (operasi baca)">
Jika Anda mengonfigurasi `channels.slack.userToken`, scope baca yang umum adalah:
<Accordion title="Cakupan token pengguna opsional (operasi baca)">
Jika Anda mengonfigurasi `channels.slack.userToken`, cakupan baca yang umum adalah:
- `channels:history`, `groups:history`, `im:history`, `mpim:history`
- `channels:read`, `groups:read`, `im:read`, `mpim:read`
@ -444,24 +444,24 @@ Tampilkan fitur berbeda yang memperluas default di atas.
## Model token
- `botToken` + `appToken` wajib untuk Socket Mode.
- `botToken` + `appToken` diperlukan untuk Socket Mode.
- Mode HTTP memerlukan `botToken` + `signingSecret`.
- `botToken`, `appToken`, `signingSecret`, dan `userToken` menerima string
plaintext atau objek SecretRef.
- Token konfigurasi menimpa fallback env.
- `botToken`, `appToken`, `signingSecret`, dan `userToken` menerima string teks biasa
atau objek SecretRef.
- Token konfigurasi mengesampingkan fallback env.
- Fallback env `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` hanya berlaku untuk akun default.
- `userToken` (`xoxp-...`) hanya melalui konfigurasi (tanpa fallback env) dan default ke perilaku baca-saja (`userTokenReadOnly: true`).
- `userToken` (`xoxp-...`) hanya melalui konfigurasi (tanpa fallback env) dan default-nya adalah perilaku hanya-baca (`userTokenReadOnly: true`).
Perilaku snapshot status:
- Pemeriksaan akun Slack melacak field `*Source` dan `*Status`
- Inspeksi akun Slack melacak kolom `*Source` dan `*Status`
per kredensial (`botToken`, `appToken`, `signingSecret`, `userToken`).
- Status adalah `available`, `configured_unavailable`, atau `missing`.
- `configured_unavailable` berarti akun dikonfigurasi melalui SecretRef
atau sumber secret non-inline lainnya, tetapi jalur perintah/runtime saat ini
tidak dapat me-resolve nilai aktualnya.
atau sumber rahasia non-inline lain, tetapi jalur perintah/runtime saat ini
tidak dapat menyelesaikan nilai sebenarnya.
- Dalam mode HTTP, `signingSecretStatus` disertakan; dalam Socket Mode,
pasangan wajibnya adalah `botTokenStatus` + `appTokenStatus`.
pasangan yang diperlukan adalah `botTokenStatus` + `appTokenStatus`.
<Tip>
Untuk tindakan/pembacaan direktori, token pengguna dapat diprioritaskan saat dikonfigurasi. Untuk penulisan, token bot tetap diprioritaskan; penulisan dengan token pengguna hanya diizinkan saat `userTokenReadOnly: false` dan token bot tidak tersedia.
@ -471,7 +471,7 @@ Untuk tindakan/pembacaan direktori, token pengguna dapat diprioritaskan saat dik
Tindakan Slack dikontrol oleh `channels.slack.actions.*`.
Grup tindakan yang tersedia dalam tooling Slack saat ini:
Grup tindakan yang tersedia di tooling Slack saat ini:
| Grup | Default |
| ---------- | ------- |
@ -481,13 +481,13 @@ Grup tindakan yang tersedia dalam tooling Slack saat ini:
| memberInfo | aktif |
| emojiList | aktif |
Tindakan pesan Slack saat ini mencakup `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info`, dan `emoji-list`. `download-file` menerima ID file Slack yang ditampilkan dalam placeholder file masuk dan mengembalikan pratinjau gambar untuk gambar atau metadata file lokal untuk tipe file lain.
Tindakan pesan Slack saat ini mencakup `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info`, dan `emoji-list`. `download-file` menerima ID file Slack yang ditampilkan dalam placeholder file masuk dan mengembalikan pratinjau gambar untuk gambar atau metadata file lokal untuk jenis file lain.
## Kontrol akses dan perutean
<Tabs>
<Tab title="Kebijakan DM">
`channels.slack.dmPolicy` mengontrol akses DM. `channels.slack.allowFrom` adalah allowlist DM kanonis.
<Tab title="DM policy">
`channels.slack.dmPolicy` mengontrol akses DM. `channels.slack.allowFrom` adalah daftar izin DM kanonis.
- `pairing` (default)
- `allowlist`
@ -498,41 +498,41 @@ Tindakan pesan Slack saat ini mencakup `send`, `upload-file`, `download-file`, `
- `dm.enabled` (default true)
- `channels.slack.allowFrom`
- `dm.allowFrom` (legacy)
- `dm.allowFrom` (lama)
- `dm.groupEnabled` (DM grup default false)
- `dm.groupChannels` (allowlist MPIM opsional)
- `dm.groupChannels` (daftar izin MPIM opsional)
Prioritas multi-akun:
- `channels.slack.accounts.default.allowFrom` hanya berlaku untuk akun `default`.
- Akun bernama mewarisi `channels.slack.allowFrom` saat `allowFrom` miliknya sendiri tidak disetel.
- Akun bernama mewarisi `channels.slack.allowFrom` saat `allowFrom` miliknya sendiri belum diatur.
- Akun bernama tidak mewarisi `channels.slack.accounts.default.allowFrom`.
`channels.slack.dm.policy` dan `channels.slack.dm.allowFrom` legacy masih dibaca untuk kompatibilitas. `openclaw doctor --fix` memigrasikannya ke `dmPolicy` dan `allowFrom` saat dapat melakukannya tanpa mengubah akses.
`channels.slack.dm.policy` dan `channels.slack.dm.allowFrom` lama masih dibaca untuk kompatibilitas. `openclaw doctor --fix` memigrasikannya ke `dmPolicy` dan `allowFrom` saat dapat melakukannya tanpa mengubah akses.
Pairing dalam DM menggunakan `openclaw pairing approve slack <code>`.
Pairing di DM menggunakan `openclaw pairing approve slack <code>`.
</Tab>
<Tab title="Kebijakan channel">
<Tab title="Channel policy">
`channels.slack.groupPolicy` mengontrol penanganan channel:
- `open`
- `allowlist`
- `disabled`
Allowlist channel berada di bawah `channels.slack.channels` dan **harus menggunakan ID channel Slack yang stabil** (misalnya `C12345678`) sebagai kunci konfigurasi.
Daftar izin channel berada di bawah `channels.slack.channels` dan **harus menggunakan ID channel Slack yang stabil** (misalnya `C12345678`) sebagai kunci konfigurasi.
Catatan runtime: jika `channels.slack` benar-benar tidak ada (setup hanya env), runtime fallback ke `groupPolicy="allowlist"` dan mencatat peringatan (meskipun `channels.defaults.groupPolicy` disetel).
Catatan runtime: jika `channels.slack` sepenuhnya tidak ada (penyiapan hanya env), runtime fallback ke `groupPolicy="allowlist"` dan mencatat peringatan (meskipun `channels.defaults.groupPolicy` diatur).
Resolusi nama/ID:
- entri allowlist channel dan entri allowlist DM di-resolve saat startup ketika akses token mengizinkan
- entri nama channel yang tidak ter-resolve dipertahankan sesuai konfigurasi tetapi diabaikan untuk perutean secara default
- otorisasi masuk dan perutean channel mengutamakan ID secara default; pencocokan nama pengguna/slug langsung memerlukan `channels.slack.dangerouslyAllowNameMatching: true`
- entri daftar izin channel dan entri daftar izin DM diselesaikan saat startup ketika akses token memungkinkan
- entri nama channel yang tidak terselesaikan dipertahankan sesuai konfigurasi tetapi diabaikan untuk perutean secara default
- otorisasi masuk dan perutean channel mengutamakan ID secara default; pencocokan username/slug langsung memerlukan `channels.slack.dangerouslyAllowNameMatching: true`
<Warning>
Kunci berbasis nama (`#channel-name` atau `channel-name`) **tidak** cocok dalam `groupPolicy: "allowlist"`. Lookup channel mengutamakan ID secara default, sehingga kunci berbasis nama tidak akan pernah berhasil dirutekan dan semua pesan di channel tersebut akan diblokir diam-diam. Ini berbeda dari `groupPolicy: "open"`, ketika kunci channel tidak diperlukan untuk perutean dan kunci berbasis nama tampak berfungsi.
Kunci berbasis nama (`#channel-name` atau `channel-name`) **tidak** cocok di bawah `groupPolicy: "allowlist"`. Pencarian channel mengutamakan ID secara default, sehingga kunci berbasis nama tidak akan pernah berhasil dirutekan dan semua pesan di channel tersebut akan diblokir secara diam-diam. Ini berbeda dari `groupPolicy: "open"`, ketika kunci channel tidak diperlukan untuk perutean dan kunci berbasis nama tampak berfungsi.
Selalu gunakan ID channel Slack sebagai kunci. Untuk menemukannya: klik kanan channel di Slack → **Copy link** — ID (`C...`) muncul di akhir URL.
@ -551,7 +551,7 @@ Tindakan pesan Slack saat ini mencakup `send`, `upload-file`, `download-file`, `
}
```
Salah (diblokir diam-diam dalam `groupPolicy: "allowlist"`):
Salah (diblokir diam-diam di bawah `groupPolicy: "allowlist"`):
```json5
{
@ -569,25 +569,27 @@ Tindakan pesan Slack saat ini mencakup `send`, `upload-file`, `download-file`, `
</Tab>
<Tab title="Mention dan pengguna channel">
Pesan channel digate oleh mention secara default.
<Tab title="Mentions and channel users">
Pesan channel dibatasi mention secara default.
Sumber mention:
- mention aplikasi eksplisit (`<@botId>`)
- pola regex mention (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`)
- perilaku thread balasan-ke-bot implisit (dinonaktifkan saat `thread.requireExplicitMention` adalah `true`)
- perilaku thread balasan-ke-bot implisit (dinonaktifkan saat `thread.requireExplicitMention` bernilai `true`)
Kontrol per-channel (`channels.slack.channels.<id>`; nama hanya melalui resolusi startup atau `dangerouslyAllowNameMatching`):
Kontrol per channel (`channels.slack.channels.<id>`; nama hanya melalui resolusi startup atau `dangerouslyAllowNameMatching`):
- `requireMention`
- `users` (allowlist)
- `users` (daftar izin)
- `allowBots`
- `skills`
- `systemPrompt`
- `tools`, `toolsBySender`
- format kunci `toolsBySender`: wildcard `id:`, `e164:`, `username:`, `name:`, atau `"*"`
(kunci legacy tanpa prefiks tetap hanya dipetakan ke `id:`)
- format kunci `toolsBySender`: `id:`, `e164:`, `username:`, `name:`, atau wildcard `"*"`
(kunci lama tanpa prefiks masih hanya dipetakan ke `id:`)
`allowBots` bersifat konservatif untuk channel dan channel privat: pesan room yang ditulis bot diterima hanya saat bot pengirim secara eksplisit tercantum dalam daftar izin `users` milik room tersebut, atau saat setidaknya satu ID pemilik Slack eksplisit dari `channels.slack.allowFrom` saat ini adalah anggota room. Wildcard dan entri pemilik berbasis nama tampilan tidak memenuhi keberadaan pemilik. Keberadaan pemilik menggunakan `conversations.members` Slack; pastikan aplikasi memiliki scope baca yang sesuai untuk jenis room (`channels:read` untuk channel publik, `groups:read` untuk channel privat). Jika pencarian anggota gagal, OpenClaw membuang pesan room yang ditulis bot.
</Tab>
</Tabs>
@ -599,14 +601,14 @@ Tindakan pesan Slack saat ini mencakup `send`, `upload-file`, `download-file`, `
- Sesi channel: `agent:<agentId>:slack:channel:<channelId>`.
- Balasan thread dapat membuat sufiks sesi thread (`:thread:<threadTs>`) saat berlaku.
- Default `channels.slack.thread.historyScope` adalah `thread`; default `thread.inheritParent` adalah `false`.
- `channels.slack.thread.initialHistoryLimit` mengontrol berapa banyak pesan thread yang sudah ada diambil saat sesi thread baru dimulai (default `20`; setel `0` untuk menonaktifkan).
- `channels.slack.thread.requireExplicitMention` (default `false`): saat `true`, menekan mention thread implisit sehingga bot hanya merespons mention `@bot` eksplisit di dalam thread, meskipun bot sudah berpartisipasi dalam thread. Tanpa ini, balasan dalam thread yang diikuti bot melewati gating `requireMention`.
- `channels.slack.thread.initialHistoryLimit` mengontrol berapa banyak pesan thread yang sudah ada diambil saat sesi thread baru dimulai (default `20`; atur `0` untuk menonaktifkan).
- `channels.slack.thread.requireExplicitMention` (default `false`): saat `true`, menekan mention thread implisit sehingga bot hanya merespons mention `@bot` eksplisit di dalam thread, meskipun bot sudah berpartisipasi dalam thread. Tanpa ini, balasan dalam thread yang diikuti bot melewati gate `requireMention`.
Kontrol threading balasan:
Kontrol thread balasan:
- `channels.slack.replyToMode`: `off|first|all|batched` (default `off`)
- `channels.slack.replyToModeByChatType`: per `direct|group|channel`
- fallback legacy untuk chat langsung: `channels.slack.dm.replyToMode`
- fallback lama untuk chat langsung: `channels.slack.dm.replyToMode`
Tag balasan manual didukung:
@ -614,12 +616,12 @@ Tag balasan manual didukung:
- `[[reply_to:<id>]]`
<Note>
`replyToMode="off"` menonaktifkan **semua** threading balasan di Slack, termasuk tag `[[reply_to_*]]` eksplisit. Ini berbeda dari Telegram, ketika tag eksplisit tetap dihormati dalam mode `"off"`. Thread Slack menyembunyikan pesan dari channel sementara balasan Telegram tetap terlihat inline.
`replyToMode="off"` menonaktifkan **semua** thread balasan di Slack, termasuk tag `[[reply_to_*]]` eksplisit. Ini berbeda dari Telegram, tempat tag eksplisit masih dihormati dalam mode `"off"`. Thread Slack menyembunyikan pesan dari channel, sedangkan balasan Telegram tetap terlihat inline.
</Note>
## Reaksi konfirmasi
## Reaksi ack
`ackReaction` mengirim emoji konfirmasi saat OpenClaw memproses pesan masuk.
`ackReaction` mengirim emoji pengakuan saat OpenClaw memproses pesan masuk.
Urutan resolusi:
@ -631,26 +633,26 @@ Urutan resolusi:
Catatan:
- Slack mengharapkan shortcode (misalnya `"eyes"`).
- Gunakan `""` untuk menonaktifkan reaksi bagi akun Slack atau secara global.
- Gunakan `""` untuk menonaktifkan reaksi untuk akun Slack atau secara global.
## Streaming teks
`channels.slack.streaming` mengontrol perilaku pratinjau live:
`channels.slack.streaming` mengontrol perilaku pratinjau langsung:
- `off`: nonaktifkan streaming pratinjau live.
- `off`: nonaktifkan streaming pratinjau langsung.
- `partial` (default): ganti teks pratinjau dengan output parsial terbaru.
- `block`: tambahkan pembaruan pratinjau terpotong.
- `progress`: tampilkan teks status progres saat menghasilkan, lalu kirim teks akhir.
- `streaming.preview.toolProgress`: saat pratinjau draf aktif, rutekan pembaruan tool/progres ke pesan pratinjau yang diedit yang sama (default: `true`). Setel `false` untuk mempertahankan pesan tool/progres terpisah.
- `block`: tambahkan pembaruan pratinjau dalam chunk.
- `progress`: tampilkan teks status progres saat menghasilkan, lalu kirim teks final.
- `streaming.preview.toolProgress`: saat pratinjau draf aktif, rutekan pembaruan alat/progres ke pesan pratinjau editan yang sama (default: `true`). Atur `false` untuk mempertahankan pesan alat/progres terpisah.
`channels.slack.streaming.nativeTransport` mengontrol streaming teks native Slack saat `channels.slack.streaming.mode` adalah `partial` (default: `true`).
- Thread balasan harus tersedia agar streaming teks native dan status thread asisten Slack muncul. Pemilihan thread tetap mengikuti `replyToMode`.
- Root channel dan chat grup tetap dapat menggunakan pratinjau draf normal saat streaming native tidak tersedia.
- DM Slack tingkat atas tetap di luar thread secara default, sehingga tidak menampilkan pratinjau bergaya thread; gunakan balasan thread atau `typingReaction` jika Anda menginginkan progres terlihat di sana.
- Media dan payload non-teks fallback ke pengiriman normal.
- Final media/error membatalkan edit pratinjau tertunda; final teks/blok yang memenuhi syarat hanya di-flush saat dapat mengedit pratinjau di tempat.
- Jika streaming gagal di tengah balasan, OpenClaw fallback ke pengiriman normal untuk payload tersisa.
- Root channel dan chat grup masih dapat menggunakan pratinjau draf normal saat streaming native tidak tersedia.
- DM Slack tingkat atas tetap berada di luar thread secara default, sehingga tidak menampilkan pratinjau bergaya thread; gunakan balasan thread atau `typingReaction` jika Anda menginginkan progres yang terlihat di sana.
- Payload media dan non-teks fallback ke pengiriman normal.
- Final media/error membatalkan edit pratinjau yang tertunda; final teks/blok yang memenuhi syarat hanya di-flush saat dapat mengedit pratinjau di tempat.
- Jika streaming gagal di tengah balasan, OpenClaw fallback ke pengiriman normal untuk payload yang tersisa.
Gunakan pratinjau draf alih-alih streaming teks native Slack:
@ -667,13 +669,13 @@ Gunakan pratinjau draf alih-alih streaming teks native Slack:
}
```
Kunci legacy:
Kunci lama:
- `channels.slack.streamMode` (`replace | status_final | append`) dimigrasikan otomatis ke `channels.slack.streaming.mode`.
- boolean `channels.slack.streaming` dimigrasikan otomatis ke `channels.slack.streaming.mode` dan `channels.slack.streaming.nativeTransport`.
- `channels.slack.nativeStreaming` legacy dimigrasikan otomatis ke `channels.slack.streaming.nativeTransport`.
- `channels.slack.nativeStreaming` lama dimigrasikan otomatis ke `channels.slack.streaming.nativeTransport`.
## Fallback reaksi pengetikan
## Fallback reaksi mengetik
`typingReaction` menambahkan reaksi sementara ke pesan Slack masuk saat OpenClaw memproses balasan, lalu menghapusnya saat run selesai. Ini paling berguna di luar balasan thread, yang menggunakan indikator status default "is typing...".
@ -685,42 +687,42 @@ Urutan resolusi:
Catatan:
- Slack mengharapkan shortcode (misalnya `"hourglass_flowing_sand"`).
- Reaksi bersifat upaya terbaik dan pembersihan dicoba otomatis setelah jalur balasan atau kegagalan selesai.
- Reaksi bersifat upaya terbaik dan pembersihan dicoba secara otomatis setelah jalur balasan atau kegagalan selesai.
## Media, pemotongan, dan pengiriman
## Media, chunking, dan pengiriman
<AccordionGroup>
<Accordion title="Lampiran masuk">
Lampiran file Slack diunduh dari URL privat yang dihosting Slack (alur permintaan terautentikasi token) dan ditulis ke media store saat fetch berhasil dan batas ukuran mengizinkan. Placeholder file menyertakan `fileId` Slack sehingga agen dapat mengambil file asli dengan `download-file`.
<Accordion title="Inbound attachments">
Lampiran file Slack diunduh dari URL privat yang di-host Slack (alur permintaan terautentikasi token) dan ditulis ke penyimpanan media saat fetch berhasil dan batas ukuran mengizinkan. Placeholder file menyertakan `fileId` Slack sehingga agen dapat mengambil file asli dengan `download-file`.
Unduhan menggunakan timeout idle dan total yang dibatasi. Jika pengambilan file Slack macet atau gagal, OpenClaw tetap memproses pesan dan fallback ke placeholder file.
Batas ukuran masuk runtime default ke `20MB` kecuali ditimpa oleh `channels.slack.mediaMaxMb`.
Batas ukuran runtime masuk default adalah `20MB` kecuali ditimpa oleh `channels.slack.mediaMaxMb`.
</Accordion>
<Accordion title="Teks dan file keluar">
<Accordion title="Teks keluar dan file">
- potongan teks menggunakan `channels.slack.textChunkLimit` (default 4000)
- `channels.slack.chunkMode="newline"` mengaktifkan pemisahan dengan paragraf diprioritaskan
- pengiriman file menggunakan API unggah Slack dan dapat menyertakan balasan thread (`thread_ts`)
- batas media keluar mengikuti `channels.slack.mediaMaxMb` saat dikonfigurasi; jika tidak, pengiriman channel menggunakan default jenis MIME dari pipeline media
- `channels.slack.chunkMode="newline"` mengaktifkan pemisahan yang memprioritaskan paragraf
- pengiriman file menggunakan API unggah Slack dan dapat menyertakan balasan utas (`thread_ts`)
- batas media keluar mengikuti `channels.slack.mediaMaxMb` saat dikonfigurasi; jika tidak, pengiriman kanal menggunakan default jenis MIME dari pipeline media
</Accordion>
<Accordion title="Target pengiriman">
Target eksplisit yang diprioritaskan:
Target eksplisit yang disarankan:
- `user:<id>` untuk DM
- `channel:<id>` untuk channel
- `channel:<id>` untuk kanal
DM Slack dibuka melalui API conversation Slack saat mengirim ke target pengguna.
DM Slack dibuka melalui API percakapan Slack saat mengirim ke target pengguna.
</Accordion>
</AccordionGroup>
## Perintah dan perilaku slash
Perintah slash muncul di Slack sebagai satu perintah terkonfigurasi atau beberapa perintah native. Konfigurasi `channels.slack.slashCommand` untuk mengubah default perintah:
Perintah slash muncul di Slack sebagai satu perintah yang dikonfigurasi atau beberapa perintah native. Konfigurasikan `channels.slack.slashCommand` untuk mengubah default perintah:
- `enabled: false`
- `name: "openclaw"`
@ -731,7 +733,7 @@ Perintah slash muncul di Slack sebagai satu perintah terkonfigurasi atau beberap
/openclaw /help
```
Perintah native memerlukan [pengaturan manifes tambahan](#additional-manifest-settings) di aplikasi Slack Anda dan sebagai gantinya diaktifkan dengan `channels.slack.commands.native: true` atau `commands.native: true` dalam konfigurasi global.
Perintah native memerlukan [pengaturan manifes tambahan](#additional-manifest-settings) di aplikasi Slack Anda dan diaktifkan dengan `channels.slack.commands.native: true` atau `commands.native: true` di konfigurasi global sebagai gantinya.
- Mode otomatis perintah native **nonaktif** untuk Slack sehingga `commands.native: "auto"` tidak mengaktifkan perintah native Slack.
@ -743,8 +745,8 @@ Menu argumen native menggunakan strategi rendering adaptif yang menampilkan moda
- hingga 5 opsi: blok tombol
- 6-100 opsi: menu pilih statis
- lebih dari 100 opsi: pilih eksternal dengan pemfilteran opsi asinkron saat handler opsi interaktivitas tersedia
- melebihi batas Slack: nilai opsi yang dienkode fallback ke tombol
- lebih dari 100 opsi: pilihan eksternal dengan pemfilteran opsi asinkron saat handler opsi interaktivitas tersedia
- melewati batas Slack: nilai opsi yang dienkode beralih kembali ke tombol
```txt
/think
@ -754,7 +756,7 @@ Sesi slash menggunakan kunci terisolasi seperti `agent:<agentId>:slack:slash:<us
## Balasan interaktif
Slack dapat merender kontrol balasan interaktif yang ditulis agen, tetapi fitur ini dinonaktifkan secara default.
Slack dapat merender kontrol balasan interaktif yang dibuat agen, tetapi fitur ini dinonaktifkan secara default.
Aktifkan secara global:
@ -793,39 +795,39 @@ Saat diaktifkan, agen dapat mengeluarkan direktif balasan khusus Slack:
- `[[slack_buttons: Approve:approve, Reject:reject]]`
- `[[slack_select: Choose a target | Canary:canary, Production:production]]`
Direktif ini dikompilasi menjadi Slack Block Kit dan merutekan klik atau pilihan kembali melalui jalur peristiwa interaksi Slack yang sudah ada.
Direktif ini dikompilasi menjadi Slack Block Kit dan merutekan klik atau pilihan kembali melalui jalur event interaksi Slack yang sudah ada.
Catatan:
- Ini adalah UI khusus Slack. Channel lain tidak menerjemahkan direktif Slack Block Kit ke sistem tombol mereka sendiri.
- Nilai callback interaktif adalah token buram yang dibuat OpenClaw, bukan nilai mentah yang ditulis agen.
- Jika blok interaktif yang dihasilkan akan melebihi batas Slack Block Kit, OpenClaw fallback ke balasan teks asli alih-alih mengirim payload blok yang tidak valid.
- Ini adalah UI khusus Slack. Kanal lain tidak menerjemahkan direktif Slack Block Kit ke sistem tombol mereka sendiri.
- Nilai callback interaktif adalah token buram yang dihasilkan OpenClaw, bukan nilai mentah yang dibuat agen.
- Jika blok interaktif yang dihasilkan akan melewati batas Slack Block Kit, OpenClaw beralih kembali ke balasan teks asli, bukan mengirim payload blok yang tidak valid.
## Persetujuan exec di Slack
Slack dapat bertindak sebagai klien persetujuan native dengan tombol dan interaksi interaktif, alih-alih fallback ke UI Web atau terminal.
Slack dapat bertindak sebagai klien persetujuan native dengan tombol dan interaksi interaktif, alih-alih beralih kembali ke UI Web atau terminal.
- Persetujuan exec menggunakan `channels.slack.execApprovals.*` untuk perutean DM/channel native.
- Persetujuan exec menggunakan `channels.slack.execApprovals.*` untuk perutean DM/kanal native.
- Persetujuan Plugin masih dapat diselesaikan melalui permukaan tombol native Slack yang sama saat permintaan sudah masuk ke Slack dan jenis id persetujuannya adalah `plugin:`.
- Otorisasi pemberi persetujuan tetap diberlakukan: hanya pengguna yang diidentifikasi sebagai pemberi persetujuan yang dapat menyetujui atau menolak permintaan melalui Slack.
Ini menggunakan permukaan tombol persetujuan bersama yang sama seperti channel lain. Saat `interactivity` diaktifkan di pengaturan aplikasi Slack Anda, prompt persetujuan dirender sebagai tombol Block Kit langsung di percakapan.
Saat tombol tersebut ada, tombol itu menjadi UX persetujuan utama; OpenClaw
hanya boleh menyertakan perintah manual `/approve` saat hasil alat mengatakan persetujuan chat
Ini menggunakan permukaan tombol persetujuan bersama yang sama seperti kanal lain. Saat `interactivity` diaktifkan di pengaturan aplikasi Slack Anda, prompt persetujuan dirender sebagai tombol Block Kit langsung di percakapan.
Saat tombol tersebut ada, tombol tersebut adalah UX persetujuan utama; OpenClaw
hanya boleh menyertakan perintah manual `/approve` saat hasil alat mengatakan bahwa persetujuan chat
tidak tersedia atau persetujuan manual adalah satu-satunya jalur.
Jalur konfigurasi:
Jalur config:
- `channels.slack.execApprovals.enabled`
- `channels.slack.execApprovals.approvers` (opsional; fallback ke `commands.ownerAllowFrom` jika memungkinkan)
- `channels.slack.execApprovals.approvers` (opsional; beralih kembali ke `commands.ownerAllowFrom` jika memungkinkan)
- `channels.slack.execApprovals.target` (`dm` | `channel` | `both`, default: `dm`)
- `agentFilter`, `sessionFilter`
Slack otomatis mengaktifkan persetujuan exec native saat `enabled` tidak disetel atau `"auto"` dan setidaknya satu
pemberi persetujuan terselesaikan. Setel `enabled: false` untuk menonaktifkan Slack sebagai klien persetujuan native secara eksplisit.
Setel `enabled: true` untuk memaksa persetujuan native aktif saat pemberi persetujuan terselesaikan.
pemberi persetujuan berhasil ditemukan. Setel `enabled: false` untuk menonaktifkan Slack sebagai klien persetujuan native secara eksplisit.
Setel `enabled: true` untuk memaksa persetujuan native aktif saat pemberi persetujuan berhasil ditemukan.
Perilaku default tanpa konfigurasi persetujuan exec Slack eksplisit:
Perilaku default tanpa config persetujuan exec Slack eksplisit:
```json5
{
@ -835,8 +837,8 @@ Perilaku default tanpa konfigurasi persetujuan exec Slack eksplisit:
}
```
Konfigurasi native Slack eksplisit hanya diperlukan saat Anda ingin menimpa pemberi persetujuan, menambahkan filter, atau
ikut menggunakan pengiriman chat asal:
Config native Slack eksplisit hanya diperlukan saat Anda ingin mengganti pemberi persetujuan, menambahkan filter, atau
memilih pengiriman chat asal:
```json5
{
@ -853,35 +855,35 @@ ikut menggunakan pengiriman chat asal:
```
Penerusan `approvals.exec` bersama terpisah. Gunakan hanya saat prompt persetujuan exec juga harus
dirutekan ke chat lain atau target out-of-band eksplisit. Penerusan `approvals.plugin` bersama juga
terpisah; tombol native Slack masih dapat menyelesaikan persetujuan plugin saat permintaan tersebut sudah masuk
dirutekan ke chat lain atau target eksplisit di luar jalur utama. Penerusan `approvals.plugin` bersama juga
terpisah; tombol native Slack masih dapat menyelesaikan persetujuan Plugin saat permintaan tersebut sudah masuk
ke Slack.
`/approve` dalam chat yang sama juga berfungsi di channel Slack dan DM yang sudah mendukung perintah. Lihat [Persetujuan exec](/id/tools/exec-approvals) untuk model penerusan persetujuan lengkap.
`/approve` dalam chat yang sama juga berfungsi di kanal Slack dan DM yang sudah mendukung perintah. Lihat [Persetujuan exec](/id/tools/exec-approvals) untuk model penerusan persetujuan lengkap.
## Peristiwa dan perilaku operasional
## Event dan perilaku operasional
- Edit/hapus pesan dipetakan menjadi peristiwa sistem.
- Siaran thread (balasan thread "Also send to channel") diproses sebagai pesan pengguna normal.
- Peristiwa tambah/hapus reaksi dipetakan menjadi peristiwa sistem.
- Peristiwa anggota bergabung/keluar, channel dibuat/diubah namanya, dan pin tambah/hapus dipetakan menjadi peristiwa sistem.
- `channel_id_changed` dapat memigrasikan kunci konfigurasi channel saat `configWrites` diaktifkan.
- Metadata topik/tujuan channel diperlakukan sebagai konteks tidak tepercaya dan dapat disuntikkan ke konteks perutean.
- Penyemaian konteks pembuka thread dan riwayat thread awal difilter oleh allowlist pengirim yang dikonfigurasi jika berlaku.
- Tindakan blok dan interaksi modal memancarkan peristiwa sistem `Slack interaction: ...` terstruktur dengan kolom payload kaya:
- Edit/hapus pesan dipetakan menjadi event sistem.
- Siaran utas (balasan utas "Also send to channel") diproses sebagai pesan pengguna normal.
- Event tambah/hapus reaksi dipetakan menjadi event sistem.
- Event anggota bergabung/keluar, kanal dibuat/diubah namanya, dan pin tambah/hapus dipetakan menjadi event sistem.
- `channel_id_changed` dapat memigrasikan kunci config kanal saat `configWrites` diaktifkan.
- Metadata topik/tujuan kanal diperlakukan sebagai konteks tidak tepercaya dan dapat disuntikkan ke konteks perutean.
- Penyemaian konteks pembuka utas dan riwayat utas awal difilter oleh allowlist pengirim yang dikonfigurasi jika berlaku.
- Tindakan blok dan interaksi modal memancarkan event sistem `Slack interaction: ...` terstruktur dengan field payload yang kaya:
- tindakan blok: nilai yang dipilih, label, nilai picker, dan metadata `workflow_*`
- peristiwa modal `view_submission` dan `view_closed` dengan metadata channel yang dirutekan dan input formulir
- event modal `view_submission` dan `view_closed` dengan metadata kanal yang dirutekan dan input formulir
## Referensi konfigurasi
Referensi utama: [Referensi konfigurasi - Slack](/id/gateway/config-channels#slack).
<Accordion title="Kolom Slack bersinyal tinggi">
<Accordion title="Field Slack bersinyal tinggi">
- mode/auth: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*`
- akses DM: `dm.enabled`, `dmPolicy`, `allowFrom` (legacy: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels`
- toggle kompatibilitas: `dangerouslyAllowNameMatching` (break-glass; tetap nonaktif kecuali diperlukan)
- akses channel: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention`
- akses kanal: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention`
- threading/riwayat: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
- pengiriman: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport`, `streaming.preview.toolProgress`
- ops/fitur: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly`
@ -891,15 +893,15 @@ Referensi utama: [Referensi konfigurasi - Slack](/id/gateway/config-channels#sla
## Pemecahan masalah
<AccordionGroup>
<Accordion title="Tidak ada balasan di channel">
<Accordion title="Tidak ada balasan di kanal">
Periksa, secara berurutan:
- `groupPolicy`
- allowlist channel (`channels.slack.channels`) — **kunci harus berupa ID channel** (`C12345678`), bukan nama (`#channel-name`). Kunci berbasis nama gagal secara senyap di bawah `groupPolicy: "allowlist"` karena perutean channel mengutamakan ID secara default. Untuk menemukan ID: klik kanan channel di Slack → **Copy link** — nilai `C...` di akhir URL adalah ID channel.
- allowlist kanal (`channels.slack.channels`) — **kunci harus berupa ID kanal** (`C12345678`), bukan nama (`#channel-name`). Kunci berbasis nama gagal secara diam-diam di bawah `groupPolicy: "allowlist"` karena perutean kanal memprioritaskan ID secara default. Untuk menemukan ID: klik kanan kanal di Slack → **Copy link** — nilai `C...` di akhir URL adalah ID kanal.
- `requireMention`
- allowlist `users` per channel
- allowlist `users` per kanal
Perintah berguna:
Perintah yang berguna:
```bash
openclaw channels status --probe
@ -915,9 +917,9 @@ openclaw doctor
- `channels.slack.dm.enabled`
- `channels.slack.dmPolicy` (atau legacy `channels.slack.dm.policy`)
- persetujuan pairing / entri allowlist
- Peristiwa DM Slack Assistant: log verbose yang menyebut `drop message_changed`
biasanya berarti Slack mengirim peristiwa thread Assistant yang diedit tanpa
pengirim manusia yang dapat dipulihkan dalam metadata pesan
- event DM Slack Assistant: log verbose yang menyebutkan `drop message_changed`
biasanya berarti Slack mengirim event utas Assistant yang diedit tanpa
pengirim manusia yang dapat dipulihkan di metadata pesan
```bash
openclaw pairing list slack
@ -925,110 +927,111 @@ openclaw pairing list slack
</Accordion>
<Accordion title="Mode socket tidak tersambung">
Validasi token bot + app dan pengaktifan Socket Mode di pengaturan aplikasi Slack.
<Accordion title="Socket mode tidak tersambung">
Validasi token bot + aplikasi dan pengaktifan Socket Mode di pengaturan aplikasi Slack.
Jika `openclaw channels status --probe --json` menampilkan `botTokenStatus` atau
`appTokenStatus: "configured_unavailable"`, akun Slack sudah
dikonfigurasi tetapi runtime saat ini tidak dapat menyelesaikan nilai yang didukung SecretRef.
`appTokenStatus: "configured_unavailable"`, akun Slack
sudah dikonfigurasi tetapi runtime saat ini tidak dapat menemukan nilai
berbasis SecretRef.
</Accordion>
<Accordion title="Mode HTTP tidak menerima peristiwa">
<Accordion title="Mode HTTP tidak menerima event">
Validasi:
- signing secret
- jalur Webhook
- URL Permintaan Slack (Events + Interactivity + Slash Commands)
- URL Permintaan Slack (Event + Interaktivitas + Perintah Slash)
- `webhookPath` unik per akun HTTP
Jika `signingSecretStatus: "configured_unavailable"` muncul di snapshot akun,
akun HTTP sudah dikonfigurasi tetapi runtime saat ini tidak dapat
menyelesaikan signing secret yang didukung SecretRef.
menemukan signing secret berbasis SecretRef.
</Accordion>
<Accordion title="Perintah native/slash tidak berjalan">
Verifikasi apakah yang Anda maksud:
Verifikasi apakah yang Anda maksud adalah:
- mode perintah native (`channels.slack.commands.native: true`) dengan perintah slash yang sesuai terdaftar di Slack
- atau mode perintah slash tunggal (`channels.slack.slashCommand.enabled: true`)
- mode perintah native (`channels.slack.commands.native: true`) dengan perintah slash yang cocok terdaftar di Slack
- atau mode satu perintah slash (`channels.slack.slashCommand.enabled: true`)
Periksa juga `commands.useAccessGroups` dan allowlist channel/pengguna.
Periksa juga `commands.useAccessGroups` dan allowlist kanal/pengguna.
</Accordion>
</AccordionGroup>
## Referensi visi lampiran
## Referensi vision lampiran
Slack dapat melampirkan media yang diunduh ke giliran agen saat unduhan file Slack berhasil dan batas ukuran mengizinkan. File gambar dapat diteruskan melalui jalur pemahaman media atau langsung ke model balasan berkemampuan visi; file lain dipertahankan sebagai konteks file yang dapat diunduh alih-alih diperlakukan sebagai input gambar.
Slack dapat melampirkan media yang diunduh ke giliran agen saat unduhan file Slack berhasil dan batas ukuran mengizinkan. File gambar dapat diteruskan melalui jalur pemahaman media atau langsung ke model balasan berkemampuan vision; file lain dipertahankan sebagai konteks file yang dapat diunduh, bukan diperlakukan sebagai input gambar.
### Jenis media yang didukung
| Jenis media | Sumber | Perilaku saat ini | Catatan |
| Jenis media | Sumber | Perilaku saat ini | Catatan |
| ------------------------------ | -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Gambar JPEG / PNG / GIF / WebP | URL file Slack | Diunduh dan dilampirkan ke giliran untuk penanganan berkemampuan visi | Batas per file: `channels.slack.mediaMaxMb` (default 20 MB) |
| Gambar JPEG / PNG / GIF / WebP | URL file Slack | Diunduh dan dilampirkan ke giliran untuk penanganan berkemampuan vision | Batas per file: `channels.slack.mediaMaxMb` (default 20 MB) |
| File PDF | URL file Slack | Diunduh dan diekspos sebagai konteks file untuk alat seperti `download-file` atau `pdf` | Inbound Slack tidak mengonversi PDF menjadi input image-vision secara otomatis |
| File lain | URL file Slack | Diunduh jika memungkinkan dan diekspos sebagai konteks file | File biner tidak diperlakukan sebagai input gambar |
| Balasan thread | File pembuka thread | File pesan root dapat dihidrasi sebagai konteks saat balasan tidak memiliki media langsung | Pembuka yang hanya berisi file menggunakan placeholder lampiran |
| Pesan multi-gambar | Beberapa file Slack | Setiap file dievaluasi secara independen | Pemrosesan Slack dibatasi hingga delapan file per pesan |
| File lain | URL file Slack | Diunduh jika memungkinkan dan diekspos sebagai konteks file | File biner tidak diperlakukan sebagai input gambar |
| Balasan utas | File pembuka utas | File pesan root dapat dihidrasi sebagai konteks saat balasan tidak memiliki media langsung | Pembuka yang hanya berisi file menggunakan placeholder lampiran |
| Pesan multi-gambar | Beberapa file Slack | Setiap file dievaluasi secara independen | Pemrosesan Slack dibatasi hingga delapan file per pesan |
### Pipeline inbound
Saat pesan Slack dengan lampiran file tiba:
1. OpenClaw mengunduh file dari URL privat Slack menggunakan token bot (`xoxb-...`).
2. File ditulis ke media store jika berhasil.
3. Jalur media yang diunduh dan jenis konten ditambahkan ke konteks inbound.
4. Jalur model/alat berkemampuan gambar dapat menggunakan lampiran gambar dari konteks tersebut.
2. File ditulis ke penyimpanan media jika berhasil.
3. Jalur media yang diunduh dan jenis konten ditambahkan ke konteks masuk.
4. Jalur model/alat yang mendukung gambar dapat menggunakan lampiran gambar dari konteks tersebut.
5. File non-gambar tetap tersedia sebagai metadata file atau referensi media untuk alat yang dapat menanganinya.
### Pewarisan lampiran root thread
### Pewarisan lampiran root utas
Saat pesan tiba dalam thread (memiliki induk `thread_ts`):
Ketika pesan masuk dalam sebuah utas (memiliki induk `thread_ts`):
- Jika balasan itu sendiri tidak memiliki media langsung dan pesan root yang disertakan memiliki file, Slack dapat menghidrasi file root sebagai konteks pembuka thread.
- Lampiran balasan langsung lebih diutamakan daripada lampiran pesan root.
- Pesan root yang hanya memiliki file dan tanpa teks direpresentasikan dengan placeholder lampiran sehingga fallback masih dapat menyertakan filenya.
- Jika balasan itu sendiri tidak memiliki media langsung dan pesan root yang disertakan memiliki file, Slack dapat menghidrasi file root sebagai konteks pembuka utas.
- Lampiran balasan langsung diprioritaskan daripada lampiran pesan root.
- Pesan root yang hanya memiliki file dan tanpa teks direpresentasikan dengan placeholder lampiran agar fallback tetap dapat menyertakan file-file tersebut.
### Penanganan multi-lampiran
Saat satu pesan Slack berisi beberapa lampiran file:
Ketika satu pesan Slack berisi beberapa lampiran file:
- Setiap lampiran diproses secara independen melalui pipeline media.
- Referensi media yang diunduh diagregasikan ke dalam konteks pesan.
- Referensi media yang diunduh digabungkan ke dalam konteks pesan.
- Urutan pemrosesan mengikuti urutan file Slack dalam payload peristiwa.
- Kegagalan dalam unduhan satu lampiran tidak memblokir lampiran lain.
- Kegagalan pengunduhan pada satu lampiran tidak memblokir lampiran lainnya.
### Ukuran, unduhan, dan batas model
### Batas ukuran, unduhan, dan model
- **Batas ukuran**: Default 20 MB per file. Dapat dikonfigurasi melalui `channels.slack.mediaMaxMb`.
- **Kegagalan unduhan**: File yang tidak dapat disajikan oleh Slack, URL kedaluwarsa, file yang tidak dapat diakses, file terlalu besar, dan respons HTML auth/login Slack dilewati alih-alih dilaporkan sebagai format yang tidak didukung.
- **Model vision**: Analisis gambar menggunakan model balasan aktif saat mendukung vision, atau model gambar yang dikonfigurasi di `agents.defaults.imageModel`.
- **Model penglihatan**: Analisis gambar menggunakan model balasan aktif ketika model tersebut mendukung penglihatan, atau model gambar yang dikonfigurasi di `agents.defaults.imageModel`.
### Batas yang diketahui
| Skenario | Perilaku saat ini | Solusi sementara |
| ------------------------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| URL file Slack kedaluwarsa | File dilewati; tidak ada error yang ditampilkan | Unggah ulang file di Slack |
| Model vision tidak dikonfigurasi | Lampiran gambar disimpan sebagai referensi media, tetapi tidak dianalisis sebagai gambar | Konfigurasikan `agents.defaults.imageModel` atau gunakan model balasan yang mendukung vision |
| Gambar sangat besar (> 20 MB secara default) | Dilewati sesuai batas ukuran | Tingkatkan `channels.slack.mediaMaxMb` jika Slack mengizinkan |
| Lampiran yang diteruskan/dibagikan | Teks dan media gambar/file yang dihosting Slack dilakukan secara best-effort | Bagikan ulang langsung di thread OpenClaw |
| Lampiran PDF | Disimpan sebagai konteks file/media, tidak otomatis dirutekan melalui vision gambar | Gunakan `download-file` untuk metadata file atau tool `pdf` untuk analisis PDF |
| Skenario | Perilaku saat ini | Solusi alternatif |
| -------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| URL file Slack kedaluwarsa | File dilewati; tidak ada error yang ditampilkan | Unggah ulang file di Slack |
| Model penglihatan tidak dikonfigurasi | Lampiran gambar disimpan sebagai referensi media, tetapi tidak dianalisis sebagai gambar | Konfigurasikan `agents.defaults.imageModel` atau gunakan model balasan yang mendukung penglihatan |
| Gambar sangat besar (> 20 MB secara default) | Dilewati sesuai batas ukuran | Tingkatkan `channels.slack.mediaMaxMb` jika Slack mengizinkan |
| Lampiran yang diteruskan/dibagikan | Teks dan media gambar/file yang dihosting Slack bersifat upaya terbaik | Bagikan ulang langsung di utas OpenClaw |
| Lampiran PDF | Disimpan sebagai konteks file/media, tidak otomatis dirutekan melalui penglihatan gambar | Gunakan `download-file` untuk metadata file atau alat `pdf` untuk analisis PDF |
### Dokumentasi terkait
- [Pipeline pemahaman media](/id/nodes/media-understanding)
- [Tool PDF](/id/tools/pdf)
- Epic: [#51349](https://github.com/openclaw/openclaw/issues/51349) — Pengaktifan vision lampiran Slack
- Uji regresi: [#51353](https://github.com/openclaw/openclaw/issues/51353)
- Verifikasi live: [#51354](https://github.com/openclaw/openclaw/issues/51354)
- [Alat PDF](/id/tools/pdf)
- Epik: [#51349](https://github.com/openclaw/openclaw/issues/51349) — pengaktifan penglihatan lampiran Slack
- Pengujian regresi: [#51353](https://github.com/openclaw/openclaw/issues/51353)
- Verifikasi langsung: [#51354](https://github.com/openclaw/openclaw/issues/51354)
## Terkait
<CardGroup cols={2}>
<Card title="Pairing" icon="link" href="/id/channels/pairing">
Pasangkan pengguna Slack ke Gateway.
Pasangkan pengguna Slack ke gateway.
</Card>
<Card title="Groups" icon="users" href="/id/channels/groups">
Perilaku channel dan DM grup.
@ -1037,12 +1040,12 @@ Saat satu pesan Slack berisi beberapa lampiran file:
Rutekan pesan masuk ke agen.
</Card>
<Card title="Security" icon="shield" href="/id/gateway/security">
Model ancaman dan hardening.
Model ancaman dan pengerasan.
</Card>
<Card title="Configuration" icon="sliders" href="/id/gateway/configuration">
Tata letak config dan presedensi.
Tata letak konfigurasi dan presedensi.
</Card>
<Card title="Slash commands" icon="terminal" href="/id/tools/slash-commands">
Katalog dan perilaku command.
Katalog dan perilaku perintah.
</Card>
</CardGroup>

397
docs/id/channels/telegram.md
View File

@ -1,42 +1,42 @@
---
read_when:
- Mengerjakan fitur Telegram atau Webhook
summary: Status dukungan bot Telegram, kapabilitas, dan konfigurasi
summary: Status dukungan, kemampuan, dan konfigurasi bot Telegram
title: Telegram
x-i18n:
generated_at: "2026-04-30T09:36:14Z"
generated_at: "2026-04-30T16:27:42Z"
model: gpt-5.5
provider: openai
source_hash: 1ffc0c1a6bb94fbab81ede0f08b0e3a165f06c599d4d06d4b9e70c8ba41121f7
source_hash: d18ca6c7ab39d7d34848c562857661501d8364329f6e5a266213aa23846047dd
source_path: channels/telegram.md
workflow: 16
---
Siap produksi untuk DM bot dan grup melalui grammY. Long polling adalah mode default; mode webhook bersifat opsional.
Siap produksi untuk DM dan grup bot melalui grammY. Long polling adalah mode default; mode Webhook bersifat opsional.
<CardGroup cols={3}>
<Card title="Pemasangan" icon="link" href="/id/channels/pairing">
Kebijakan DM default untuk Telegram adalah pemasangan.
<Card title="Pairing" icon="link" href="/id/channels/pairing">
Kebijakan DM default untuk Telegram adalah pairing.
</Card>
<Card title="Pemecahan masalah kanal" icon="wrench" href="/id/channels/troubleshooting">
Diagnostik lintas kanal dan panduan perbaikan.
<Card title="Channel troubleshooting" icon="wrench" href="/id/channels/troubleshooting">
Diagnostik lintas saluran dan playbook perbaikan.
</Card>
<Card title="Konfigurasi Gateway" icon="settings" href="/id/gateway/configuration">
Pola dan contoh konfigurasi kanal lengkap.
<Card title="Gateway configuration" icon="settings" href="/id/gateway/configuration">
Pola dan contoh konfigurasi saluran lengkap.
</Card>
</CardGroup>
## Penyiapan cepat
<Steps>
<Step title="Buat token bot di BotFather">
Buka Telegram dan chat dengan **@BotFather** (pastikan handle persis `@BotFather`).
<Step title="Create the bot token in BotFather">
Buka Telegram dan chat dengan **@BotFather** (pastikan handle tepat `@BotFather`).
Jalankan `/newbot`, ikuti prompt, dan simpan token.
</Step>
<Step title="Konfigurasikan token dan kebijakan DM">
<Step title="Configure token and DM policy">
```json5
{
@ -56,7 +56,7 @@ Siap produksi untuk DM bot dan grup melalui grammY. Long polling adalah mode def
</Step>
<Step title="Mulai gateway dan setujui DM pertama">
<Step title="Start gateway and approve first DM">
```bash
openclaw gateway
@ -64,44 +64,44 @@ openclaw pairing list telegram
openclaw pairing approve telegram <CODE>
```
Kode pemasangan kedaluwarsa setelah 1 jam.
Kode pairing kedaluwarsa setelah 1 jam.
</Step>
<Step title="Tambahkan bot ke grup">
<Step title="Add the bot to a group">
Tambahkan bot ke grup Anda, lalu atur `channels.telegram.groups` dan `groupPolicy` agar sesuai dengan model akses Anda.
</Step>
</Steps>
<Note>
Urutan resolusi token sadar akun. Dalam praktiknya, nilai config mengalahkan fallback env, dan `TELEGRAM_BOT_TOKEN` hanya berlaku untuk akun default.
Urutan resolusi token sadar akun. Dalam praktiknya, nilai config mengungguli fallback env, dan `TELEGRAM_BOT_TOKEN` hanya berlaku untuk akun default.
</Note>
## Pengaturan sisi Telegram
<AccordionGroup>
<Accordion title="Mode privasi dan visibilitas grup">
Bot Telegram default ke **Mode Privasi**, yang membatasi pesan grup yang mereka terima.
<Accordion title="Privacy mode and group visibility">
Bot Telegram secara default menggunakan **Privacy Mode**, yang membatasi pesan grup yang diterimanya.
Jika bot harus melihat semua pesan grup, lakukan salah satu dari berikut:
Jika bot harus melihat semua pesan grup, lakukan salah satu:
- nonaktifkan mode privasi melalui `/setprivacy`, atau
- jadikan bot admin grup.
- jadikan bot sebagai admin grup.
Saat mengubah mode privasi, hapus + tambahkan ulang bot di setiap grup agar Telegram menerapkan perubahan.
Saat mengubah mode privasi, hapus + tambahkan kembali bot di setiap grup agar Telegram menerapkan perubahan.
</Accordion>
<Accordion title="Izin grup">
Status admin dikontrol di pengaturan grup Telegram.
<Accordion title="Group permissions">
Status admin dikendalikan di pengaturan grup Telegram.
Bot admin menerima semua pesan grup, yang berguna untuk perilaku grup yang selalu aktif.
</Accordion>
<Accordion title="Toggle BotFather yang berguna">
<Accordion title="Helpful BotFather toggles">
- `/setjoingroups` untuk mengizinkan/menolak penambahan grup
- `/setjoingroups` untuk mengizinkan/menolak penambahan ke grup
- `/setprivacy` untuk perilaku visibilitas grup
</Accordion>
@ -110,7 +110,7 @@ Urutan resolusi token sadar akun. Dalam praktiknya, nilai config mengalahkan fal
## Kontrol akses dan aktivasi
<Tabs>
<Tab title="Kebijakan DM">
<Tab title="DM policy">
`channels.telegram.dmPolicy` mengontrol akses pesan langsung:
- `pairing` (default)
@ -118,21 +118,21 @@ Urutan resolusi token sadar akun. Dalam praktiknya, nilai config mengalahkan fal
- `open` (memerlukan `allowFrom` menyertakan `"*"`)
- `disabled`
`dmPolicy: "open"` dengan `allowFrom: ["*"]` memungkinkan akun Telegram apa pun yang menemukan atau menebak nama pengguna bot untuk memberi perintah ke bot. Gunakan hanya untuk bot yang memang bersifat publik dengan alat yang sangat dibatasi; bot satu pemilik sebaiknya menggunakan `allowlist` dengan ID pengguna numerik.
`dmPolicy: "open"` dengan `allowFrom: ["*"]` memungkinkan akun Telegram apa pun yang menemukan atau menebak nama pengguna bot untuk memerintah bot. Gunakan hanya untuk bot yang sengaja dibuat publik dengan tool yang sangat dibatasi; bot satu pemilik sebaiknya menggunakan `allowlist` dengan ID pengguna numerik.
`channels.telegram.allowFrom` menerima ID pengguna Telegram numerik. Prefiks `telegram:` / `tg:` diterima dan dinormalisasi.
Dalam config multi-akun, `channels.telegram.allowFrom` tingkat atas yang restriktif diperlakukan sebagai batas keamanan: entri `allowFrom: ["*"]` tingkat akun tidak menjadikan akun tersebut publik kecuali allowlist akun efektif masih berisi wildcard eksplisit setelah penggabungan.
Dalam config multi-akun, `channels.telegram.allowFrom` tingkat atas yang restriktif diperlakukan sebagai batas keamanan: entri tingkat akun `allowFrom: ["*"]` tidak membuat akun tersebut publik kecuali allowlist akun efektif masih berisi wildcard eksplisit setelah penggabungan.
`dmPolicy: "allowlist"` dengan `allowFrom` kosong memblokir semua DM dan ditolak oleh validasi config.
Penyiapan hanya meminta ID pengguna numerik.
Jika Anda melakukan upgrade dan config Anda berisi entri allowlist `@username`, jalankan `openclaw doctor --fix` untuk menyelesaikannya (upaya terbaik; memerlukan token bot Telegram).
Jika sebelumnya Anda mengandalkan file allowlist penyimpanan pemasangan, `openclaw doctor --fix` dapat memulihkan entri ke `channels.telegram.allowFrom` dalam alur allowlist (misalnya saat `dmPolicy: "allowlist"` belum memiliki ID eksplisit).
Jika sebelumnya Anda mengandalkan file allowlist pairing-store, `openclaw doctor --fix` dapat memulihkan entri ke `channels.telegram.allowFrom` dalam alur allowlist (misalnya saat `dmPolicy: "allowlist"` belum memiliki ID eksplisit).
Untuk bot satu pemilik, pilih `dmPolicy: "allowlist"` dengan ID `allowFrom` numerik eksplisit agar kebijakan akses bertahan di config (bukan bergantung pada persetujuan pemasangan sebelumnya).
Untuk bot satu pemilik, pilih `dmPolicy: "allowlist"` dengan ID numerik `allowFrom` eksplisit agar kebijakan akses tahan lama dalam config (alih-alih bergantung pada persetujuan pairing sebelumnya).
Kebingungan umum: persetujuan pemasangan DM tidak berarti "pengirim ini diotorisasi di semua tempat".
Pemasangan memberikan akses DM. Jika belum ada pemilik perintah, pemasangan pertama yang disetujui juga mengatur `commands.ownerAllowFrom` sehingga perintah khusus pemilik dan persetujuan exec memiliki akun operator eksplisit.
Kebingungan umum: persetujuan pairing DM tidak berarti "pengirim ini diotorisasi di mana saja".
Pairing memberikan akses DM. Jika belum ada pemilik perintah, pairing pertama yang disetujui juga menetapkan `commands.ownerAllowFrom` sehingga perintah khusus pemilik dan persetujuan exec memiliki akun operator eksplisit.
Otorisasi pengirim grup tetap berasal dari allowlist config eksplisit.
Jika Anda ingin "saya diotorisasi sekali dan DM serta perintah grup berfungsi", masukkan ID pengguna Telegram numerik Anda di `channels.telegram.allowFrom`; untuk perintah khusus pemilik, pastikan `commands.ownerAllowFrom` berisi `telegram:<your user id>`.
Jika Anda ingin "Saya diotorisasi sekali dan DM serta perintah grup sama-sama berfungsi", masukkan ID pengguna Telegram numerik Anda di `channels.telegram.allowFrom`; untuk perintah khusus pemilik, pastikan `commands.ownerAllowFrom` berisi `telegram:<your user id>`.
### Menemukan ID pengguna Telegram Anda
@ -152,29 +152,29 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
</Tab>
<Tab title="Kebijakan grup dan allowlist">
<Tab title="Group policy and allowlists">
Dua kontrol berlaku bersama:
1. **Grup mana yang diizinkan** (`channels.telegram.groups`)
- tanpa config `groups`:
- dengan `groupPolicy: "open"`: grup mana pun dapat lolos pemeriksaan ID grup
- dengan `groupPolicy: "open"`: grup apa pun dapat lolos pemeriksaan ID grup
- dengan `groupPolicy: "allowlist"` (default): grup diblokir sampai Anda menambahkan entri `groups` (atau `"*"`)
- `groups` dikonfigurasi: bertindak sebagai allowlist (ID eksplisit atau `"*"`)
2. **Pengirim mana yang diizinkan di grup** (`channels.telegram.groupPolicy`)
2. **Pengirim mana yang diizinkan dalam grup** (`channels.telegram.groupPolicy`)
- `open`
- `allowlist` (default)
- `disabled`
`groupAllowFrom` digunakan untuk pemfilteran pengirim grup. Jika tidak diatur, Telegram fallback ke `allowFrom`.
Entri `groupAllowFrom` harus berupa ID pengguna Telegram numerik (prefiks `telegram:` / `tg:` dinormalisasi).
`groupAllowFrom` digunakan untuk pemfilteran pengirim grup. Jika tidak disetel, Telegram kembali ke `allowFrom`.
Entri `groupAllowFrom` sebaiknya berupa ID pengguna Telegram numerik (prefiks `telegram:` / `tg:` dinormalisasi).
Jangan masukkan ID chat grup atau supergrup Telegram di `groupAllowFrom`. ID chat negatif berada di bawah `channels.telegram.groups`.
Entri non-numerik diabaikan untuk otorisasi pengirim.
Batas keamanan (`2026.2.25+`): auth pengirim grup **tidak** mewarisi persetujuan penyimpanan pemasangan DM.
Pemasangan tetap khusus DM. Untuk grup, atur `groupAllowFrom` atau `allowFrom` per grup/per topik.
Jika `groupAllowFrom` tidak diatur, Telegram fallback ke config `allowFrom`, bukan penyimpanan pemasangan.
Pola praktis untuk bot satu pemilik: atur ID pengguna Anda di `channels.telegram.allowFrom`, biarkan `groupAllowFrom` tidak diatur, dan izinkan grup target di bawah `channels.telegram.groups`.
Catatan runtime: jika `channels.telegram` sepenuhnya hilang, runtime default ke fail-closed `groupPolicy="allowlist"` kecuali `channels.defaults.groupPolicy` diatur secara eksplisit.
Batas keamanan (`2026.2.25+`): auth pengirim grup **tidak** mewarisi persetujuan pairing-store DM.
Pairing tetap khusus DM. Untuk grup, setel `groupAllowFrom` atau `allowFrom` per grup/per topik.
Jika `groupAllowFrom` tidak disetel, Telegram kembali ke config `allowFrom`, bukan pairing store.
Pola praktis untuk bot satu pemilik: setel ID pengguna Anda di `channels.telegram.allowFrom`, biarkan `groupAllowFrom` tidak disetel, dan izinkan grup target di bawah `channels.telegram.groups`.
Catatan runtime: jika `channels.telegram` sepenuhnya tidak ada, runtime default ke fail-closed `groupPolicy="allowlist"` kecuali `channels.defaults.groupPolicy` disetel secara eksplisit.
Contoh: izinkan anggota mana pun di satu grup tertentu:
@ -214,20 +214,20 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
Kesalahan umum: `groupAllowFrom` bukan allowlist grup Telegram.
- Letakkan ID chat grup atau supergrup Telegram negatif seperti `-1001234567890` di bawah `channels.telegram.groups`.
- Letakkan ID pengguna Telegram seperti `8734062810` di bawah `groupAllowFrom` saat Anda ingin membatasi orang mana di dalam grup yang diizinkan dapat memicu bot.
- Letakkan ID pengguna Telegram seperti `8734062810` di bawah `groupAllowFrom` saat Anda ingin membatasi orang di dalam grup yang diizinkan yang dapat memicu bot.
- Gunakan `groupAllowFrom: ["*"]` hanya saat Anda ingin anggota mana pun dari grup yang diizinkan dapat berbicara dengan bot.
</Warning>
</Tab>
<Tab title="Perilaku penyebutan">
Balasan grup secara default memerlukan penyebutan.
<Tab title="Mention behavior">
Balasan grup memerlukan mention secara default.
Penyebutan dapat berasal dari:
Mention dapat berasal dari:
- penyebutan native `@botusername`, atau
- pola penyebutan di:
- mention native `@botusername`, atau
- pola mention di:
- `agents.list[].groupChat.mentionPatterns`
- `messages.groupChat.mentionPatterns`
@ -264,20 +264,20 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
## Perilaku runtime
- Telegram dimiliki oleh proses gateway.
- Routing bersifat deterministik: pesan masuk Telegram dibalas kembali ke Telegram (model tidak memilih kanal).
- Pesan masuk dinormalisasi ke envelope kanal bersama dengan metadata balasan dan placeholder media.
- Routing deterministik: inbound Telegram membalas kembali ke Telegram (model tidak memilih saluran).
- Pesan inbound dinormalisasi ke dalam envelope saluran bersama dengan metadata balasan dan placeholder media.
- Sesi grup diisolasi berdasarkan ID grup. Topik forum menambahkan `:topic:<threadId>` agar topik tetap terisolasi.
- Pesan DM dapat membawa `message_thread_id`; OpenClaw merutekannya dengan kunci sesi sadar thread dan mempertahankan ID thread untuk balasan.
- Long polling menggunakan runner grammY dengan pengurutan per chat/per thread. Konkurensi sink runner keseluruhan menggunakan `agents.defaults.maxConcurrent`.
- Long polling dijaga di dalam setiap proses gateway sehingga hanya satu poller aktif yang dapat menggunakan token bot pada satu waktu. Jika Anda masih melihat konflik `getUpdates` 409, kemungkinan gateway OpenClaw lain, skrip, atau poller eksternal menggunakan token yang sama.
- Restart watchdog long-polling dipicu setelah 120 detik tanpa liveness `getUpdates` yang selesai secara default. Tingkatkan `channels.telegram.pollingStallThresholdMs` hanya jika deployment Anda masih melihat restart polling-stall palsu selama pekerjaan berjalan lama. Nilainya dalam milidetik dan diizinkan dari `30000` hingga `600000`; override per akun didukung.
- Pesan DM dapat membawa `message_thread_id`; OpenClaw merutekannya dengan kunci sesi yang sadar thread dan mempertahankan ID thread untuk balasan.
- Long polling menggunakan grammY runner dengan pengurutan per chat/per thread. Konkurensi sink runner keseluruhan menggunakan `agents.defaults.maxConcurrent`.
- Long polling dijaga di dalam setiap proses gateway sehingga hanya satu poller aktif yang dapat menggunakan token bot pada satu waktu. Jika Anda masih melihat konflik `getUpdates` 409, kemungkinan gateway OpenClaw lain, skrip, atau poller eksternal sedang menggunakan token yang sama.
- Restart watchdog long-polling terpicu setelah 120 detik tanpa liveness `getUpdates` yang selesai secara default. Tingkatkan `channels.telegram.pollingStallThresholdMs` hanya jika deployment Anda masih melihat restart polling-stall palsu selama pekerjaan yang berjalan lama. Nilainya dalam milidetik dan diizinkan dari `30000` hingga `600000`; override per akun didukung.
- Telegram Bot API tidak memiliki dukungan tanda baca (`sendReadReceipts` tidak berlaku).
## Referensi fitur
<AccordionGroup>
<Accordion title="Pratinjau live stream (edit pesan)">
OpenClaw dapat melakukan stream balasan parsial secara real time:
<Accordion title="Live stream preview (message edits)">
OpenClaw dapat melakukan streaming balasan parsial secara real time:
- chat langsung: pesan pratinjau + `editMessageText`
- grup/topik: pesan pratinjau + `editMessageText`
@ -285,11 +285,11 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
Persyaratan:
- `channels.telegram.streaming` adalah `off | partial | block | progress` (default: `partial`)
- `progress` dipetakan ke `partial` di Telegram (kompat dengan penamaan lintas kanal)
- `streaming.preview.toolProgress` mengontrol apakah pembaruan alat/progres menggunakan kembali pesan pratinjau yang sama yang diedit (default: `true` saat streaming pratinjau aktif)
- `channels.telegram.streamMode` legacy dan nilai boolean `streaming` terdeteksi; jalankan `openclaw doctor --fix` untuk memigrasikannya ke `channels.telegram.streaming.mode`
- `progress` dipetakan ke `partial` di Telegram (kompat dengan penamaan lintas saluran)
- `streaming.preview.toolProgress` mengontrol apakah pembaruan tool/progress menggunakan kembali pesan pratinjau edit yang sama (default: `true` saat streaming pratinjau aktif)
- `channels.telegram.streamMode` lama dan nilai boolean `streaming` terdeteksi; jalankan `openclaw doctor --fix` untuk memigrasikannya ke `channels.telegram.streaming.mode`
Pembaruan pratinjau progres alat adalah baris pendek "Working..." yang ditampilkan saat alat berjalan, misalnya eksekusi perintah, pembacaan file, pembaruan perencanaan, atau ringkasan patch. Telegram mengaktifkan ini secara default agar sesuai dengan perilaku OpenClaw yang dirilis dari `v2026.4.22` dan setelahnya. Untuk mempertahankan pratinjau yang diedit untuk teks jawaban tetapi menyembunyikan baris progres alat, atur:
Pembaruan pratinjau progres tool adalah baris pendek "Working..." yang ditampilkan saat tool berjalan, misalnya eksekusi perintah, pembacaan file, pembaruan perencanaan, atau ringkasan patch. Telegram mengaktifkannya secara default agar sesuai dengan perilaku OpenClaw yang dirilis dari `v2026.4.22` dan setelahnya. Untuk mempertahankan pratinjau edit untuk teks jawaban tetapi menyembunyikan baris progres tool, setel:
```json
{
@ -306,38 +306,36 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
}
```
Gunakan `streaming.mode: "off"` hanya saat Anda menginginkan pengiriman final saja: edit pratinjau Telegram dinonaktifkan dan obrolan alat/progres generik ditekan alih-alih dikirim sebagai pesan "Working..." mandiri. Prompt persetujuan, payload media, dan error tetap dirutekan melalui pengiriman final normal. Gunakan `streaming.preview.toolProgress: false` saat Anda hanya ingin mempertahankan edit pratinjau jawaban sambil menyembunyikan baris status progres alat.
Gunakan `streaming.mode: "off"` hanya saat Anda menginginkan pengiriman final saja: edit pratinjau Telegram dinonaktifkan dan percakapan umum tool/progress ditekan alih-alih dikirim sebagai pesan mandiri "Working...". Prompt persetujuan, payload media, dan error tetap dirutekan melalui pengiriman final normal. Gunakan `streaming.preview.toolProgress: false` saat Anda hanya ingin mempertahankan edit pratinjau jawaban sambil menyembunyikan baris status progres tool.
Untuk balasan hanya teks:
Untuk balasan teks saja:
- pratinjau DM/grup/topik singkat: OpenClaw mempertahankan pesan pratinjau yang sama dan melakukan edit final di tempat
- pratinjau yang lebih lama dari sekitar satu menit: OpenClaw mengirim balasan lengkap sebagai pesan final baru lalu membersihkan pratinjau, sehingga stempel waktu yang terlihat di Telegram mencerminkan waktu penyelesaian, bukan waktu pembuatan pratinjau
- pratinjau DM/grup/topik singkat: OpenClaw mempertahankan pesan pratinjau yang sama dan melakukan pengeditan final di tempat
- pratinjau yang lebih lama dari sekitar satu menit: OpenClaw mengirim balasan selesai sebagai pesan final baru lalu membersihkan pratinjau, sehingga stempel waktu yang terlihat di Telegram mencerminkan waktu penyelesaian, bukan waktu pembuatan pratinjau
Untuk balasan kompleks (misalnya payload media), OpenClaw kembali ke pengiriman final normal lalu membersihkan pesan pratinjau.
Streaming pratinjau terpisah dari streaming blok. Saat streaming blok diaktifkan secara eksplisit untuk Telegram, OpenClaw melewati stream pratinjau untuk menghindari streaming ganda.
Streaming pratinjau terpisah dari streaming blok. Saat streaming blok diaktifkan secara eksplisit untuk Telegram, OpenClaw melewati streaming pratinjau untuk menghindari streaming ganda.
Jika transport draf native tidak tersedia/ditolak, OpenClaw otomatis kembali ke `sendMessage` + `editMessageText`.
Stream penalaran khusus Telegram:
Streaming penalaran khusus Telegram:
- `/reasoning stream` mengirim penalaran ke pratinjau langsung saat menghasilkan
- jawaban final dikirim tanpa teks penalaran
</Accordion>
<Accordion title="Formatting and HTML fallback">
<Accordion title="Pemformatan dan fallback HTML">
Teks keluar menggunakan Telegram `parse_mode: "HTML"`.
- Teks mirip Markdown dirender menjadi HTML yang aman untuk Telegram.
- HTML model mentah di-escape untuk mengurangi kegagalan parsing Telegram.
- Jika Telegram menolak HTML yang diparsing, OpenClaw mencoba lagi sebagai teks biasa.
- HTML mentah dari model di-escape untuk mengurangi kegagalan parsing Telegram.
- Jika Telegram menolak HTML yang diparsing, OpenClaw mencoba ulang sebagai teks biasa.
Pratinjau tautan diaktifkan secara default dan dapat dinonaktifkan dengan `channels.telegram.linkPreview: false`.
</Accordion>
<Accordion title="Native commands and custom commands">
<Accordion title="Perintah native dan perintah kustom">
Pendaftaran menu perintah Telegram ditangani saat startup dengan `setMyCommands`.
Default perintah native:
@ -361,47 +359,47 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
Aturan:
- nama dinormalisasi (hapus `/` di awal, huruf kecil)
- nama dinormalisasi (menghapus `/` di awal, huruf kecil)
- pola valid: `a-z`, `0-9`, `_`, panjang `1..32`
- perintah kustom tidak dapat menimpa perintah native
- konflik/duplikat dilewati dan dicatat di log
- konflik/duplikat dilewati dan dicatat
Catatan:
- perintah kustom hanya entri menu; perintah tersebut tidak otomatis mengimplementasikan perilaku
- perintah plugin/skill tetap dapat berfungsi saat diketik meskipun tidak ditampilkan di menu Telegram
- perintah kustom hanya entri menu; perintah tersebut tidak mengimplementasikan perilaku secara otomatis
- perintah plugin/skill masih dapat bekerja saat diketik meskipun tidak ditampilkan di menu Telegram
Jika perintah native dinonaktifkan, bawaan akan dihapus. Perintah kustom/plugin mungkin tetap didaftarkan jika dikonfigurasi.
Jika perintah native dinonaktifkan, bawaan akan dihapus. Perintah kustom/plugin mungkin tetap terdaftar jika dikonfigurasi.
Kegagalan penyiapan umum:
- `setMyCommands failed` dengan `BOT_COMMANDS_TOO_MUCH` berarti menu Telegram masih melebihi batas setelah pemangkasan; kurangi perintah plugin/skill/kustom atau nonaktifkan `channels.telegram.commands.native`.
- `deleteWebhook`, `deleteMyCommands`, atau `setMyCommands` gagal dengan `404: Not Found` sementara perintah curl Bot API langsung berfungsi dapat berarti `channels.telegram.apiRoot` disetel ke endpoint lengkap `/bot<TOKEN>`. `apiRoot` harus hanya root Bot API, dan `openclaw doctor --fix` menghapus akhiran `/bot<TOKEN>` yang tidak sengaja.
- `getMe returned 401` berarti Telegram menolak token bot yang dikonfigurasi. Perbarui `botToken`, `tokenFile`, atau `TELEGRAM_BOT_TOKEN` dengan token BotFather saat ini; OpenClaw berhenti sebelum polling sehingga ini tidak dilaporkan sebagai kegagalan pembersihan webhook.
- `setMyCommands failed` dengan `BOT_COMMANDS_TOO_MUCH` berarti menu Telegram masih meluap setelah pemangkasan; kurangi perintah plugin/skill/kustom atau nonaktifkan `channels.telegram.commands.native`.
- `deleteWebhook`, `deleteMyCommands`, atau `setMyCommands` gagal dengan `404: Not Found` sementara perintah curl Bot API langsung berfungsi dapat berarti `channels.telegram.apiRoot` diatur ke endpoint lengkap `/bot<TOKEN>`. `apiRoot` harus hanya root Bot API, dan `openclaw doctor --fix` menghapus akhiran `/bot<TOKEN>` yang tidak sengaja.
- `getMe returned 401` berarti Telegram menolak token bot yang dikonfigurasi. Perbarui `botToken`, `tokenFile`, atau `TELEGRAM_BOT_TOKEN` dengan token BotFather saat ini; OpenClaw berhenti sebelum polling sehingga ini tidak dilaporkan sebagai kegagalan pembersihan Webhook.
- `setMyCommands failed` dengan error jaringan/fetch biasanya berarti DNS/HTTPS keluar ke `api.telegram.org` diblokir.
### Perintah pemasangan perangkat (Plugin `device-pair`)
Saat Plugin `device-pair` diinstal:
Saat Plugin `device-pair` dipasang:
1. `/pair` menghasilkan kode penyiapan
2. tempel kode di aplikasi iOS
3. `/pair pending` mencantumkan permintaan yang tertunda (termasuk peran/cakupan)
3. `/pair pending` mencantumkan permintaan tertunda (termasuk peran/scopes)
4. setujui permintaan:
- `/pair approve <requestId>` untuk persetujuan eksplisit
- `/pair approve` saat hanya ada satu permintaan tertunda
- `/pair approve latest` untuk yang paling baru
- `/pair approve latest` untuk yang terbaru
Kode penyiapan membawa token bootstrap berumur pendek. Serah terima bootstrap bawaan mempertahankan token node utama di `scopes: []`; token operator yang diserahterimakan tetap dibatasi pada `operator.approvals`, `operator.read`, `operator.talk.secrets`, dan `operator.write`. Pemeriksaan cakupan bootstrap diberi prefiks peran, sehingga allowlist operator tersebut hanya memenuhi permintaan operator; peran non-operator tetap membutuhkan cakupan di bawah prefiks perannya sendiri.
Kode penyiapan membawa token bootstrap berumur pendek. Handoff bootstrap bawaan mempertahankan token node utama pada `scopes: []`; token operator yang diserahkan tetap dibatasi ke `operator.approvals`, `operator.read`, `operator.talk.secrets`, dan `operator.write`. Pemeriksaan scope bootstrap diberi prefiks peran, sehingga allowlist operator tersebut hanya memenuhi permintaan operator; peran non-operator tetap membutuhkan scope di bawah prefiks perannya sendiri.
Jika perangkat mencoba lagi dengan detail auth yang berubah (misalnya peran/cakupan/kunci publik), permintaan tertunda sebelumnya digantikan dan permintaan baru menggunakan `requestId` yang berbeda. Jalankan ulang `/pair pending` sebelum menyetujui.
Jika perangkat mencoba ulang dengan detail auth yang berubah (misalnya peran/scopes/kunci publik), permintaan tertunda sebelumnya digantikan dan permintaan baru menggunakan `requestId` yang berbeda. Jalankan ulang `/pair pending` sebelum menyetujui.
Detail selengkapnya: [Pemasangan](/id/channels/pairing#pair-via-telegram-recommended-for-ios).
</Accordion>
<Accordion title="Inline buttons">
Konfigurasikan cakupan keyboard inline:
<Accordion title="Tombol inline">
Konfigurasikan scope keyboard inline:
```json5
{
@ -433,7 +431,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
}
```
Cakupan:
Scope:
- `off`
- `dm`
@ -441,9 +439,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- `all`
- `allowlist` (default)
`capabilities: ["inlineButtons"]` legacy dipetakan ke `inlineButtons: "all"`.
Legacy `capabilities: ["inlineButtons"]` dipetakan ke `inlineButtons: "all"`.
Contoh tindakan pesan:
Contoh aksi pesan:
```json5
{
@ -466,16 +464,16 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
</Accordion>
<Accordion title="Telegram message actions for agents and automation">
Tindakan tool Telegram mencakup:
<Accordion title="Aksi pesan Telegram untuk agen dan otomatisasi">
Aksi tool Telegram mencakup:
- `sendMessage` (`to`, `content`, `mediaUrl` opsional, `replyToMessageId`, `messageThreadId`)
- `sendMessage` (`to`, `content`, opsional `mediaUrl`, `replyToMessageId`, `messageThreadId`)
- `react` (`chatId`, `messageId`, `emoji`)
- `deleteMessage` (`chatId`, `messageId`)
- `editMessage` (`chatId`, `messageId`, `content`)
- `createForumTopic` (`chatId`, `name`, `iconColor` opsional, `iconCustomEmojiId`)
- `createForumTopic` (`chatId`, `name`, opsional `iconColor`, `iconCustomEmojiId`)
Tindakan pesan channel mengekspos alias ergonomis (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).
Aksi pesan channel mengekspos alias ergonomis (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).
Kontrol gating:
@ -485,13 +483,13 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- `channels.telegram.actions.sticker` (default: dinonaktifkan)
Catatan: `edit` dan `topic-create` saat ini diaktifkan secara default dan tidak memiliki toggle `channels.telegram.actions.*` terpisah.
Pengiriman runtime menggunakan snapshot konfigurasi/secrets aktif (startup/reload), sehingga jalur tindakan tidak melakukan resolusi ulang SecretRef ad-hoc per pengiriman.
Pengiriman runtime menggunakan snapshot konfigurasi/rahasia aktif (startup/reload), sehingga jalur aksi tidak melakukan resolusi ulang SecretRef ad hoc per pengiriman.
Semantik penghapusan reaksi: [/tools/reactions](/id/tools/reactions)
</Accordion>
<Accordion title="Reply threading tags">
<Accordion title="Tag threading balasan">
Telegram mendukung tag threading balasan eksplisit dalam output yang dihasilkan:
- `[[reply_to_current]]` membalas pesan pemicu
@ -503,13 +501,13 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- `first`
- `all`
Saat threading balasan diaktifkan dan teks atau keterangan Telegram asli tersedia, OpenClaw otomatis menyertakan kutipan native Telegram. Telegram membatasi teks kutipan native pada 1024 unit kode UTF-16, sehingga pesan yang lebih panjang dikutip dari awal dan kembali ke balasan biasa jika Telegram menolak kutipan.
Saat threading balasan diaktifkan dan teks atau caption Telegram asli tersedia, OpenClaw otomatis menyertakan kutipan native Telegram. Telegram membatasi teks kutipan native pada 1024 unit kode UTF-16, sehingga pesan yang lebih panjang dikutip dari awal dan fallback ke balasan biasa jika Telegram menolak kutipan tersebut.
Catatan: `off` menonaktifkan threading balasan implisit. Tag eksplisit `[[reply_to_*]]` tetap dipatuhi.
Catatan: `off` menonaktifkan threading balasan implisit. Tag `[[reply_to_*]]` eksplisit tetap dihormati.
</Accordion>
<Accordion title="Forum topics and thread behavior">
<Accordion title="Topik forum dan perilaku thread">
Supergrup forum:
- kunci sesi topik menambahkan `:topic:<threadId>`
@ -517,15 +515,15 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- jalur konfigurasi topik:
`channels.telegram.groups.<chatId>.topics.<threadId>`
Kasus khusus topik umum (`threadId=1`):
Kasus khusus topik General (`threadId=1`):
- pengiriman pesan menghilangkan `message_thread_id` (Telegram menolak `sendMessage(...thread_id=1)`)
- tindakan pengetikan tetap menyertakan `message_thread_id`
- aksi pengetikan tetap menyertakan `message_thread_id`
Pewarisan topik: entri topik mewarisi pengaturan grup kecuali dioverride (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
`agentId` hanya untuk topik dan tidak mewarisi dari default grup.
Pewarisan topik: entri topik mewarisi pengaturan grup kecuali ditimpa (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
`agentId` hanya untuk topik dan tidak diwarisi dari default grup.
**Perutean agen per topik**: Setiap topik dapat dirutekan ke agen berbeda dengan menyetel `agentId` di konfigurasi topik. Ini memberi setiap topik workspace, memori, dan sesi terisolasi sendiri. Contoh:
**Routing agen per topik**: Setiap topik dapat dirutekan ke agen berbeda dengan mengatur `agentId` dalam konfigurasi topik. Ini memberi setiap topik workspace, memori, dan sesi terisolasi miliknya sendiri. Contoh:
```json5
{
@ -545,26 +543,26 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
}
```
Setiap topik kemudian memiliki kunci sesi sendiri: `agent:zu:telegram:group:-1001234567890:topic:3`
Setiap topik kemudian memiliki kunci sesinya sendiri: `agent:zu:telegram:group:-1001234567890:topic:3`
**Pengikatan topik ACP persisten**: Topik forum dapat mem-pin sesi harness ACP melalui pengikatan ACP bertipe tingkat atas (`bindings[]` dengan `type: "acp"` dan `match.channel: "telegram"`, `peer.kind: "group"`, serta id berkualifikasi topik seperti `-1001234567890:topic:42`). Saat ini dicakup untuk topik forum di grup/supergrup. Lihat [Agen ACP](/id/tools/acp-agents).
**Binding topik ACP persisten**: Topik forum dapat mem-pin sesi harness ACP melalui binding ACP bertipe tingkat atas (`bindings[]` dengan `type: "acp"` dan `match.channel: "telegram"`, `peer.kind: "group"`, serta id berkualifikasi topik seperti `-1001234567890:topic:42`). Saat ini dibatasi untuk topik forum dalam grup/supergrup. Lihat [Agen ACP](/id/tools/acp-agents).
**Spawn ACP terikat thread dari chat**: `/acp spawn <agent> --thread here|auto` mengikat topik saat ini ke sesi ACP baru; tindak lanjut dirutekan langsung ke sana. OpenClaw mem-pin konfirmasi spawn di dalam topik. Memerlukan `channels.telegram.threadBindings.spawnAcpSessions=true`.
Konteks template mengekspos `MessageThreadId` dan `IsForum`. Chat DM dengan `message_thread_id` mempertahankan perutean DM tetapi menggunakan kunci sesi yang sadar thread.
Konteks template mengekspos `MessageThreadId` dan `IsForum`. Chat DM dengan `message_thread_id` mempertahankan routing DM tetapi menggunakan kunci sesi yang sadar thread.
</Accordion>
<Accordion title="Audio, video, and stickers">
<Accordion title="Audio, video, dan stiker">
### Pesan audio
Telegram membedakan catatan suara vs file audio.
Telegram membedakan voice note dan file audio.
- default: perilaku file audio
- tag `[[audio_as_voice]]` dalam balasan agen untuk memaksa pengiriman catatan suara
- transkrip catatan suara masuk dibingkai sebagai teks yang dihasilkan mesin dan tidak tepercaya dalam konteks agen; deteksi mention tetap menggunakan transkrip mentah sehingga pesan suara yang dibatasi mention tetap berfungsi.
- tag `[[audio_as_voice]]` dalam balasan agen untuk memaksa pengiriman voice note
- transkrip voice note masuk dibingkai sebagai teks buatan mesin yang tidak tepercaya dalam konteks agen; deteksi mention tetap menggunakan transkrip mentah sehingga pesan suara yang dibatasi mention tetap berfungsi.
Contoh tindakan pesan:
Contoh aksi pesan:
```json5
{
@ -578,9 +576,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
### Pesan video
Telegram membedakan file video vs catatan video.
Telegram membedakan file video dan video note.
Contoh tindakan pesan:
Contoh aksi pesan:
```json5
{
@ -592,7 +590,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
}
```
Catatan video tidak mendukung keterangan; teks pesan yang diberikan dikirim terpisah.
Video note tidak mendukung caption; teks pesan yang diberikan dikirim secara terpisah.
### Stiker
@ -602,7 +600,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- TGS animasi: dilewati
- WEBM video: dilewati
Kolom konteks stiker:
Field konteks stiker:
- `Sticker.emoji`
- `Sticker.setName`
@ -614,9 +612,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- `~/.openclaw/telegram/sticker-cache.json`
Stiker dideskripsikan sekali (jika memungkinkan) dan disimpan dalam cache untuk mengurangi panggilan vision berulang.
Stiker dideskripsikan sekali (jika memungkinkan) dan di-cache untuk mengurangi panggilan vision berulang.
Aktifkan tindakan stiker:
Aktifkan aksi stiker:
```json5
{
@ -630,7 +628,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
}
```
Tindakan kirim stiker:
Aksi kirim stiker:
```json5
{
@ -654,27 +652,27 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
</Accordion>
<Accordion title="Reaction notifications">
Reaksi Telegram datang sebagai pembaruan `message_reaction` (terpisah dari payload pesan).
<Accordion title="Notifikasi reaksi">
Reaksi Telegram hadir sebagai pembaruan `message_reaction` (terpisah dari payload pesan).
Saat diaktifkan, OpenClaw mengantrekan peristiwa sistem seperti:
Saat diaktifkan, OpenClaw mengantrekan event sistem seperti:
- `Telegram reaction added: 👍 by Alice (@alice) on msg 42`
Konfigurasi:
- `channels.telegram.reactionNotifications`: `off | own | all` (bawaan: `own`)
- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (bawaan: `minimal`)
- `channels.telegram.reactionNotifications`: `off | own | all` (default: `own`)
- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (default: `minimal`)
Catatan:
- `own` berarti reaksi pengguna hanya pada pesan yang dikirim bot (upaya terbaik melalui cache pesan terkirim).
- Peristiwa reaksi tetap mematuhi kontrol akses Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); pengirim yang tidak berwenang akan dibuang.
- `own` berarti hanya reaksi pengguna terhadap pesan yang dikirim bot (upaya terbaik melalui cache pesan terkirim).
- Peristiwa reaksi tetap mematuhi kontrol akses Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); pengirim yang tidak berwenang dibuang.
- Telegram tidak menyediakan ID utas dalam pembaruan reaksi.
- grup non-forum diarahkan ke sesi chat grup
- grup non-forum diarahkan ke sesi obrolan grup
- grup forum diarahkan ke sesi topik umum grup (`:topic:1`), bukan topik asal yang persis
`allowed_updates` untuk polling/webhook menyertakan `message_reaction` secara otomatis.
`allowed_updates` untuk polling/webhook otomatis mencakup `message_reaction`.
</Accordion>
@ -691,12 +689,12 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
Catatan:
- Telegram mengharapkan emoji unicode (misalnya "👀").
- Gunakan `""` untuk menonaktifkan reaksi bagi kanal atau akun.
- Gunakan `""` untuk menonaktifkan reaksi bagi channel atau akun.
</Accordion>
<Accordion title="Penulisan konfigurasi dari peristiwa dan perintah Telegram">
Penulisan konfigurasi kanal diaktifkan secara bawaan (`configWrites !== false`).
Penulisan konfigurasi channel diaktifkan secara default (`configWrites !== false`).
Penulisan yang dipicu Telegram mencakup:
@ -718,30 +716,30 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
</Accordion>
<Accordion title="Long polling vs webhook">
Bawaan adalah long polling. Untuk mode webhook, atur `channels.telegram.webhookUrl` dan `channels.telegram.webhookSecret`; opsional `webhookPath`, `webhookHost`, `webhookPort` (bawaan `/telegram-webhook`, `127.0.0.1`, `8787`).
Default-nya adalah long polling. Untuk mode webhook, atur `channels.telegram.webhookUrl` dan `channels.telegram.webhookSecret`; opsional `webhookPath`, `webhookHost`, `webhookPort` (default `/telegram-webhook`, `127.0.0.1`, `8787`).
Listener lokal mengikat ke `127.0.0.1:8787`. Untuk ingress publik, letakkan reverse proxy di depan port lokal atau atur `webhookHost: "0.0.0.0"` secara sengaja.
Listener lokal bind ke `127.0.0.1:8787`. Untuk ingress publik, pasang reverse proxy di depan port lokal atau atur `webhookHost: "0.0.0.0"` secara sengaja.
Mode webhook memvalidasi guard permintaan, token rahasia Telegram, dan isi JSON sebelum mengembalikan `200` ke Telegram.
OpenClaw kemudian memproses pembaruan secara asinkron melalui lane bot per-chat/per-topik yang sama dengan yang digunakan long polling, sehingga giliran agen yang lambat tidak menahan ACK pengiriman Telegram.
Mode webhook memvalidasi penjaga permintaan, token rahasia Telegram, dan body JSON sebelum mengembalikan `200` ke Telegram.
OpenClaw kemudian memproses pembaruan secara asinkron melalui lane bot per-obrolan/per-topik yang sama seperti long polling, sehingga giliran agen yang lambat tidak menahan ACK pengiriman Telegram.
</Accordion>
<Accordion title="Batas, percobaan ulang, dan target CLI">
- Bawaan `channels.telegram.textChunkLimit` adalah 4000.
- `channels.telegram.chunkMode="newline"` lebih memilih batas paragraf (baris kosong) sebelum pemisahan berdasarkan panjang.
- `channels.telegram.mediaMaxMb` (bawaan 100) membatasi ukuran media Telegram masuk dan keluar.
- `channels.telegram.timeoutSeconds` menimpa timeout klien API Telegram (jika tidak diatur, bawaan grammY berlaku).
- `channels.telegram.pollingStallThresholdMs` bawaan ke `120000`; sesuaikan antara `30000` dan `600000` hanya untuk restart polling-stall positif palsu.
- riwayat konteks grup menggunakan `channels.telegram.historyLimit` atau `messages.groupChat.historyLimit` (bawaan 50); `0` menonaktifkan.
- Default `channels.telegram.textChunkLimit` adalah 4000.
- `channels.telegram.chunkMode="newline"` memprioritaskan batas paragraf (baris kosong) sebelum pemisahan panjang.
- `channels.telegram.mediaMaxMb` (default 100) membatasi ukuran media Telegram masuk dan keluar.
- `channels.telegram.timeoutSeconds` menimpa timeout klien API Telegram (jika tidak diatur, default grammY berlaku). Klien bot long-polling menjepit nilai terkonfigurasi di bawah penjaga permintaan `getUpdates` 45 detik agar polling idle tidak dibatalkan sebelum jendela polling 30 detik selesai.
- Default `channels.telegram.pollingStallThresholdMs` adalah `120000`; sesuaikan antara `30000` dan `600000` hanya untuk restart polling-stall positif palsu.
- riwayat konteks grup menggunakan `channels.telegram.historyLimit` atau `messages.groupChat.historyLimit` (default 50); `0` menonaktifkan.
- konteks tambahan balasan/kutipan/terusan saat ini diteruskan sebagaimana diterima.
- allowlist Telegram terutama membatasi siapa yang dapat memicu agen, bukan batas redaksi konteks tambahan penuh.
- Allowlist Telegram terutama mengatur siapa yang dapat memicu agen, bukan batas redaksi konteks tambahan penuh.
- Kontrol riwayat DM:
- `channels.telegram.dmHistoryLimit`
- `channels.telegram.dms["<user_id>"].historyLimit`
- Konfigurasi `channels.telegram.retry` berlaku untuk helper pengiriman Telegram (CLI/tools/actions) untuk galat API keluar yang dapat dipulihkan. Pengiriman balasan akhir masuk juga menggunakan percobaan ulang safe-send terbatas untuk kegagalan pra-koneksi Telegram, tetapi tidak mencoba ulang amplop jaringan pasca-kirim yang ambigu yang dapat menggandakan pesan yang terlihat.
- Konfigurasi `channels.telegram.retry` berlaku untuk helper kirim Telegram (CLI/tools/actions) untuk error API keluar yang dapat dipulihkan. Pengiriman balasan akhir masuk juga menggunakan percobaan ulang safe-send terbatas untuk kegagalan pra-koneksi Telegram, tetapi tidak mencoba ulang amplop jaringan pasca-kirim yang ambigu yang dapat menduplikasi pesan terlihat.
Target pengiriman CLI dapat berupa ID chat numerik atau username:
Target kirim CLI dapat berupa ID obrolan numerik atau username:
```bash
openclaw message send --channel telegram --target 123456789 --message "hi"
@ -765,13 +763,13 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
- `--poll-public`
- `--thread-id` untuk topik forum (atau gunakan target `:topic:`)
Pengiriman Telegram juga mendukung:
Kirim Telegram juga mendukung:
- `--presentation` dengan blok `buttons` untuk keyboard inline saat `channels.telegram.capabilities.inlineButtons` mengizinkannya
- `--pin` atau `--delivery '{"pin":true}'` untuk meminta pengiriman yang disematkan saat bot dapat menyematkan di chat tersebut
- `--pin` atau `--delivery '{"pin":true}'` untuk meminta pengiriman yang dipin saat bot dapat memin di obrolan tersebut
- `--force-document` untuk mengirim gambar dan GIF keluar sebagai dokumen, bukan unggahan foto terkompresi atau media animasi
Gating tindakan:
Pembatasan tindakan:
- `channels.telegram.actions.sendMessage=false` menonaktifkan pesan Telegram keluar, termasuk poll
- `channels.telegram.actions.poll=false` menonaktifkan pembuatan poll Telegram sambil tetap mengaktifkan pengiriman reguler
@ -779,34 +777,34 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
</Accordion>
<Accordion title="Persetujuan exec di Telegram">
Telegram mendukung persetujuan exec di DM pemberi persetujuan dan secara opsional dapat memposting prompt di chat atau topik asal. Pemberi persetujuan harus berupa ID pengguna Telegram numerik.
Telegram mendukung persetujuan exec di DM pemberi persetujuan dan secara opsional dapat memposting prompt di obrolan atau topik asal. Pemberi persetujuan harus berupa ID pengguna Telegram numerik.
Path konfigurasi:
Jalur konfigurasi:
- `channels.telegram.execApprovals.enabled` (aktif otomatis saat setidaknya satu pemberi persetujuan dapat di-resolve)
- `channels.telegram.execApprovals.approvers` (fallback ke ID pemilik numerik dari `commands.ownerAllowFrom`)
- `channels.telegram.execApprovals.target`: `dm` (bawaan) | `channel` | `both`
- `channels.telegram.execApprovals.enabled` (aktif otomatis ketika setidaknya satu pemberi persetujuan dapat diresolusikan)
- `channels.telegram.execApprovals.approvers` (fallback ke ID owner numerik dari `commands.ownerAllowFrom`)
- `channels.telegram.execApprovals.target`: `dm` (default) | `channel` | `both`
- `agentFilter`, `sessionFilter`
`channels.telegram.allowFrom`, `groupAllowFrom`, dan `defaultTo` mengontrol siapa yang dapat berbicara dengan bot dan ke mana bot mengirim balasan normal. Kunci tersebut tidak menjadikan seseorang sebagai pemberi persetujuan exec. Pemasangan DM pertama yang disetujui melakukan bootstrap `commands.ownerAllowFrom` saat belum ada pemilik perintah, sehingga setup satu pemilik tetap berfungsi tanpa menduplikasi ID di bawah `execApprovals.approvers`.
`channels.telegram.allowFrom`, `groupAllowFrom`, dan `defaultTo` mengontrol siapa yang dapat berbicara dengan bot dan ke mana bot mengirim balasan normal. Itu tidak menjadikan seseorang pemberi persetujuan exec. Pemasangan DM yang disetujui pertama melakukan bootstrap `commands.ownerAllowFrom` ketika belum ada owner perintah, sehingga penyiapan satu-owner tetap bekerja tanpa menduplikasi ID di bawah `execApprovals.approvers`.
Pengiriman kanal menampilkan teks perintah di chat; hanya aktifkan `channel` atau `both` di grup/topik tepercaya. Saat prompt masuk ke topik forum, OpenClaw mempertahankan topik untuk prompt persetujuan dan tindak lanjut. Persetujuan exec kedaluwarsa setelah 30 menit secara bawaan.
Pengiriman channel menampilkan teks perintah di obrolan; aktifkan `channel` atau `both` hanya di grup/topik tepercaya. Ketika prompt masuk ke topik forum, OpenClaw mempertahankan topik untuk prompt persetujuan dan tindak lanjut. Persetujuan exec kedaluwarsa setelah 30 menit secara default.
Tombol persetujuan inline juga memerlukan `channels.telegram.capabilities.inlineButtons` untuk mengizinkan permukaan target (`dm`, `group`, atau `all`). ID persetujuan yang diawali `plugin:` di-resolve melalui persetujuan plugin; yang lain di-resolve melalui persetujuan exec terlebih dahulu.
Tombol persetujuan inline juga memerlukan `channels.telegram.capabilities.inlineButtons` agar mengizinkan permukaan target (`dm`, `group`, atau `all`). ID persetujuan dengan prefiks `plugin:` diresolusikan melalui persetujuan Plugin; yang lain diresolusikan melalui persetujuan exec terlebih dahulu.
Lihat [Persetujuan exec](/id/tools/exec-approvals).
</Accordion>
</AccordionGroup>
## Kontrol balasan galat
## Kontrol balasan error
Saat agen mengalami galat pengiriman atau penyedia, Telegram dapat membalas dengan teks galat atau menyembunyikannya. Dua kunci konfigurasi mengontrol perilaku ini:
Ketika agen mengalami error pengiriman atau provider, Telegram dapat membalas dengan teks error atau menyembunyikannya. Dua kunci konfigurasi mengontrol perilaku ini:
| Kunci | Nilai | Bawaan | Deskripsi |
| ----------------------------------- | ----------------- | ------- | ------------------------------------------------------------------------------------------------ |
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` mengirim pesan galat yang ramah ke chat. `silent` menyembunyikan balasan galat sepenuhnya. |
| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Waktu minimum antar balasan galat ke chat yang sama. Mencegah spam galat selama gangguan. |
| Kunci | Nilai | Default | Deskripsi |
| ----------------------------------- | ----------------- | ------- | ------------------------------------------------------------------------------------------------------ |
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` mengirim pesan error yang ramah ke obrolan. `silent` menyembunyikan balasan error sepenuhnya. |
| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Waktu minimum antar balasan error ke obrolan yang sama. Mencegah spam error selama gangguan. |
Override per-akun, per-grup, dan per-topik didukung (pewarisan yang sama seperti kunci konfigurasi Telegram lainnya).
@ -834,7 +832,7 @@ Override per-akun, per-grup, dan per-topik didukung (pewarisan yang sama seperti
- Jika `requireMention=false`, mode privasi Telegram harus mengizinkan visibilitas penuh.
- BotFather: `/setprivacy` -> Disable
- lalu hapus + tambahkan ulang bot ke grup
- `openclaw channels status` memperingatkan saat konfigurasi mengharapkan pesan grup tanpa mention.
- `openclaw channels status` memperingatkan ketika konfigurasi mengharapkan pesan grup tanpa mention.
- `openclaw channels status --probe` dapat memeriksa ID grup numerik eksplisit; wildcard `"*"` tidak dapat diperiksa keanggotaannya.
- uji sesi cepat: `/activation always`.
@ -842,7 +840,7 @@ Override per-akun, per-grup, dan per-topik didukung (pewarisan yang sama seperti
<Accordion title="Bot sama sekali tidak melihat pesan grup">
- saat `channels.telegram.groups` ada, grup harus dicantumkan (atau menyertakan `"*"`)
- ketika `channels.telegram.groups` ada, grup harus dicantumkan (atau menyertakan `"*"`)
- verifikasi keanggotaan bot di grup
- tinjau log: `openclaw logs --follow` untuk alasan skip
@ -850,30 +848,31 @@ Override per-akun, per-grup, dan per-topik didukung (pewarisan yang sama seperti
<Accordion title="Perintah berfungsi sebagian atau tidak sama sekali">
- beri otorisasi identitas pengirim Anda (pemasangan dan/atau `allowFrom` numerik)
- otorisasi identitas pengirim Anda (pemasangan dan/atau `allowFrom` numerik)
- otorisasi perintah tetap berlaku bahkan ketika kebijakan grup adalah `open`
- `setMyCommands failed` dengan `BOT_COMMANDS_TOO_MUCH` berarti menu native memiliki terlalu banyak entri; kurangi perintah plugin/skill/kustom atau nonaktifkan menu native
- Panggilan startup `deleteMyCommands` / `setMyCommands` dibatasi dan dicoba ulang sekali melalui fallback transport Telegram pada timeout permintaan. Galat jaringan/fetch persisten biasanya menunjukkan masalah keterjangkauan DNS/HTTPS ke `api.telegram.org`
- `setMyCommands failed` dengan `BOT_COMMANDS_TOO_MUCH` berarti menu native memiliki terlalu banyak entri; kurangi perintah Plugin/skill/kustom atau nonaktifkan menu native
- Panggilan startup `deleteMyCommands` / `setMyCommands` dibatasi dan dicoba ulang sekali melalui fallback transport Telegram saat request timeout. Error jaringan/fetch yang persisten biasanya menunjukkan masalah keterjangkauan DNS/HTTPS ke `api.telegram.org`
</Accordion>
<Accordion title="Startup melaporkan token tidak sah">
<Accordion title="Startup melaporkan token tidak berwenang">
- `getMe returned 401` adalah kegagalan autentikasi Telegram untuk token bot yang dikonfigurasi.
- Salin ulang atau buat ulang token bot di BotFather, lalu perbarui `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts.<id>.botToken`, atau `TELEGRAM_BOT_TOKEN` untuk akun bawaan.
- `deleteWebhook 401 Unauthorized` selama startup juga merupakan kegagalan autentikasi; memperlakukannya sebagai "tidak ada webhook" hanya akan menunda kegagalan token buruk yang sama ke panggilan API berikutnya.
- Jika `deleteWebhook` gagal dengan galat jaringan sementara selama startup polling, OpenClaw memeriksa `getWebhookInfo`; saat Telegram melaporkan URL webhook kosong, polling berlanjut karena pembersihan sudah terpenuhi.
- Salin ulang atau buat ulang token bot di BotFather, lalu perbarui `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts.<id>.botToken`, atau `TELEGRAM_BOT_TOKEN` untuk akun default.
- `deleteWebhook 401 Unauthorized` selama startup juga merupakan kegagalan auth; memperlakukannya sebagai "tidak ada webhook" hanya akan menunda kegagalan token buruk yang sama ke panggilan API berikutnya.
- Jika `deleteWebhook` gagal dengan error jaringan sementara selama startup polling, OpenClaw memeriksa `getWebhookInfo`; ketika Telegram melaporkan URL webhook kosong, polling berlanjut karena pembersihan sudah terpenuhi.
</Accordion>
<Accordion title="Ketidakstabilan polling atau jaringan">
- Node 22+ + fetch/proxy kustom dapat memicu perilaku pembatalan langsung jika tipe AbortSignal tidak cocok.
- Sebagian host me-resolve `api.telegram.org` ke IPv6 lebih dulu; egress IPv6 yang rusak dapat menyebabkan kegagalan API Telegram yang intermiten.
- Jika log menyertakan `TypeError: fetch failed` atau `Network request for 'getUpdates' failed!`, OpenClaw kini mencoba ulang ini sebagai galat jaringan yang dapat dipulihkan.
- Node 22+ + fetch/proxy kustom dapat memicu perilaku abort langsung jika tipe AbortSignal tidak cocok.
- Beberapa host menyelesaikan `api.telegram.org` ke IPv6 terlebih dahulu; egress IPv6 yang rusak dapat menyebabkan kegagalan API Telegram secara berkala.
- Jika log menyertakan `TypeError: fetch failed` atau `Network request for 'getUpdates' failed!`, OpenClaw sekarang mencoba ulang ini sebagai kesalahan jaringan yang dapat dipulihkan.
- Jika socket Telegram didaur ulang dalam irama tetap yang singkat, periksa apakah `channels.telegram.timeoutSeconds` rendah; klien bot long-polling membatasi nilai yang dikonfigurasi di bawah pengaman permintaan `getUpdates`, tetapi rilis lama dapat membatalkan setiap poll ketika ini diatur di bawah timeout long-poll.
- Jika log menyertakan `Polling stall detected`, OpenClaw memulai ulang polling dan membangun ulang transport Telegram setelah 120 detik tanpa liveness long-poll yang selesai secara default.
- `openclaw channels status --probe` dan `openclaw doctor` memberi peringatan saat akun polling yang berjalan belum menyelesaikan `getUpdates` setelah masa tenggang startup, saat akun webhook yang berjalan belum menyelesaikan `setWebhook` setelah masa tenggang startup, atau saat aktivitas transport polling terakhir yang berhasil sudah usang.
- Tingkatkan `channels.telegram.pollingStallThresholdMs` hanya ketika panggilan `getUpdates` yang berjalan lama sehat tetapi host Anda masih melaporkan restart polling-stall palsu. Stall persisten biasanya mengarah ke masalah proxy, DNS, IPv6, atau egress TLS antara host dan `api.telegram.org`.
- `openclaw channels status --probe` dan `openclaw doctor` memperingatkan ketika akun polling yang sedang berjalan belum menyelesaikan `getUpdates` setelah masa tenggang startup, ketika akun webhook yang sedang berjalan belum menyelesaikan `setWebhook` setelah masa tenggang startup, atau ketika aktivitas transport polling terakhir yang berhasil sudah basi.
- Tingkatkan `channels.telegram.pollingStallThresholdMs` hanya ketika panggilan `getUpdates` yang berjalan lama sehat tetapi host Anda masih melaporkan mulai ulang polling-stall palsu. Stall yang persisten biasanya menunjuk ke masalah proxy, DNS, IPv6, atau egress TLS antara host dan `api.telegram.org`.
- Telegram juga menghormati env proxy proses untuk transport Bot API, termasuk `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, dan varian huruf kecilnya. `NO_PROXY` / `no_proxy` masih dapat melewati `api.telegram.org`.
- Jika proxy terkelola OpenClaw dikonfigurasi melalui `OPENCLAW_PROXY_URL` untuk lingkungan layanan dan tidak ada env proxy standar, Telegram juga menggunakan URL tersebut untuk transport Bot API.
- Pada host VPS dengan egress/TLS langsung yang tidak stabil, rutekan panggilan API Telegram melalui `channels.telegram.proxy`:
@ -885,7 +884,7 @@ channels:
```
- Node 22+ default ke `autoSelectFamily=true` (kecuali WSL2) dan `dnsResultOrder=ipv4first`.
- Jika host Anda adalah WSL2 atau secara eksplisit bekerja lebih baik dengan perilaku khusus IPv4, paksa pemilihan family:
- Jika host Anda adalah WSL2 atau secara eksplisit bekerja lebih baik dengan perilaku hanya IPv4, paksa pemilihan family:
```yaml
channels:
@ -897,8 +896,8 @@ channels:
- Jawaban rentang benchmark RFC 2544 (`198.18.0.0/15`) sudah diizinkan
untuk unduhan media Telegram secara default. Jika fake-IP tepercaya atau
proxy transparan menulis ulang `api.telegram.org` ke alamat
privat/internal/special-use lain saat unduhan media, Anda dapat ikut serta
dalam bypass khusus Telegram:
privat/internal/penggunaan-khusus lain selama unduhan media, Anda dapat opt in
ke bypass khusus Telegram:
```yaml
channels:
@ -909,15 +908,15 @@ channels:
- Opt-in yang sama tersedia per akun di
`channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork`.
- Jika proxy Anda me-resolve host media Telegram ke `198.18.x.x`, biarkan
- Jika proxy Anda menyelesaikan host media Telegram ke `198.18.x.x`, biarkan
flag berbahaya tetap nonaktif terlebih dahulu. Media Telegram sudah mengizinkan rentang
benchmark RFC 2544 secara default.
<Warning>
`channels.telegram.network.dangerouslyAllowPrivateNetwork` melemahkan perlindungan SSRF media
Telegram. Gunakan hanya untuk lingkungan proxy tepercaya yang dikendalikan operator
seperti perutean fake-IP Clash, Mihomo, atau Surge ketika mereka
mensintesis jawaban privat atau special-use di luar rentang benchmark
`channels.telegram.network.dangerouslyAllowPrivateNetwork` melemahkan perlindungan SSRF
media Telegram. Gunakan hanya untuk lingkungan proxy tepercaya yang dikendalikan operator
seperti routing fake-IP Clash, Mihomo, atau Surge ketika mereka
mensintesis jawaban privat atau penggunaan-khusus di luar rentang benchmark
RFC 2544. Biarkan nonaktif untuk akses Telegram internet publik normal.
</Warning>
@ -941,13 +940,13 @@ Bantuan lainnya: [Pemecahan masalah channel](/id/channels/troubleshooting).
Referensi utama: [Referensi konfigurasi - Telegram](/id/gateway/config-channels#telegram).
<Accordion title="High-signal Telegram fields">
<Accordion title="Field Telegram bersinyal tinggi">
- startup/autentikasi: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` harus menunjuk ke file reguler; symlink ditolak)
- startup/auth: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` harus menunjuk ke file reguler; symlink ditolak)
- kontrol akses: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` tingkat teratas (`type: "acp"`)
- persetujuan eksekusi: `execApprovals`, `accounts.*.execApprovals`
- persetujuan exec: `execApprovals`, `accounts.*.execApprovals`
- perintah/menu: `commands.native`, `commands.nativeSkills`, `customCommands`
- thread/balasan: `replyToMode`
- threading/balasan: `replyToMode`
- streaming: `streaming` (pratinjau), `streaming.preview.toolProgress`, `blockStreaming`
- pemformatan/pengiriman: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix`
- media/jaringan: `mediaMaxMb`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy`
@ -955,34 +954,34 @@ Referensi utama: [Referensi konfigurasi - Telegram](/id/gateway/config-channels#
- webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
- tindakan/kapabilitas: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
- reaksi: `reactionNotifications`, `reactionLevel`
- galat: `errorPolicy`, `errorCooldownMs`
- kesalahan: `errorPolicy`, `errorCooldownMs`
- penulisan/riwayat: `configWrites`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
</Accordion>
<Note>
Prioritas multi-akun: ketika dua atau lebih ID akun dikonfigurasi, atur `channels.telegram.defaultAccount` (atau sertakan `channels.telegram.accounts.default`) untuk membuat perutean default eksplisit. Jika tidak, OpenClaw kembali ke ID akun ternormalisasi pertama dan `openclaw doctor` memberi peringatan. Akun bernama mewarisi `channels.telegram.allowFrom` / `groupAllowFrom`, tetapi tidak nilai `accounts.default.*`.
Presedensi multi-akun: ketika dua atau lebih ID akun dikonfigurasi, atur `channels.telegram.defaultAccount` (atau sertakan `channels.telegram.accounts.default`) untuk membuat routing default eksplisit. Jika tidak, OpenClaw kembali ke ID akun ternormalisasi pertama dan `openclaw doctor` memperingatkan. Akun bernama mewarisi nilai `channels.telegram.allowFrom` / `groupAllowFrom`, tetapi bukan nilai `accounts.default.*`.
</Note>
## Terkait
<CardGroup cols={2}>
<Card title="Pairing" icon="link" href="/id/channels/pairing">
<Card title="Pemasangan" icon="link" href="/id/channels/pairing">
Pasangkan pengguna Telegram ke gateway.
</Card>
<Card title="Groups" icon="users" href="/id/channels/groups">
Perilaku daftar izin grup dan topik.
<Card title="Grup" icon="users" href="/id/channels/groups">
Perilaku allowlist grup dan topik.
</Card>
<Card title="Channel routing" icon="route" href="/id/channels/channel-routing">
<Card title="Routing channel" icon="route" href="/id/channels/channel-routing">
Rutekan pesan masuk ke agen.
</Card>
<Card title="Security" icon="shield" href="/id/gateway/security">
Model ancaman dan pengerasan.
<Card title="Keamanan" icon="shield" href="/id/gateway/security">
Model ancaman dan hardening.
</Card>
<Card title="Multi-agent routing" icon="sitemap" href="/id/concepts/multi-agent">
<Card title="Routing multi-agen" icon="sitemap" href="/id/concepts/multi-agent">
Petakan grup dan topik ke agen.
</Card>
<Card title="Troubleshooting" icon="wrench" href="/id/channels/troubleshooting">
<Card title="Pemecahan masalah" icon="wrench" href="/id/channels/troubleshooting">
Diagnostik lintas-channel.
</Card>
</CardGroup>

87
docs/id/concepts/memory-search.md
View File

@ -1,28 +1,28 @@
---
read_when:
- Anda ingin memahami cara kerja memory_search
- Anda ingin memilih penyedia embedding
- Anda ingin memilih penyedia sematan
- Anda ingin menyesuaikan kualitas pencarian
summary: Cara pencarian memori menemukan catatan relevan menggunakan penyematan dan pengambilan hibrida
summary: Cara pencarian memori menemukan catatan relevan menggunakan sematan dan pengambilan hibrida
title: Pencarian memori
x-i18n:
generated_at: "2026-04-30T09:43:50Z"
generated_at: "2026-04-30T16:28:00Z"
model: gpt-5.5
provider: openai
source_hash: 3e6c44d90f49a797bda01b9a575928c128a334f89ae14fc3620e65562a866aa9
source_hash: 7f40bbe32453a28070ffc67f19a4c06e2fe59a24237a2aef353f4b9b8260bcf2
source_path: concepts/memory-search.md
workflow: 16
---
`memory_search` menemukan catatan yang relevan dari file memori Anda, meskipun
susunan katanya berbeda dari teks asli. Cara kerjanya adalah mengindeks memori menjadi
potongan kecil dan mencarinya menggunakan embedding, kata kunci, atau keduanya.
`memory_search` menemukan catatan yang relevan dari file memori Anda, bahkan ketika
susunannya berbeda dari teks aslinya. Ini bekerja dengan mengindeks memori menjadi
potongan-potongan kecil dan mencarinya menggunakan embedding, kata kunci, atau keduanya.
## Mulai cepat
Jika Anda memiliki langganan GitHub Copilot, atau kunci API OpenAI, Gemini,
Voyage, atau Mistral yang dikonfigurasi, pencarian memori bekerja secara
otomatis. Untuk menetapkan penyedia secara eksplisit:
Jika Anda memiliki langganan GitHub Copilot, kunci API OpenAI, Gemini, Voyage, atau Mistral
yang dikonfigurasi, pencarian memori berfungsi otomatis. Untuk mengatur penyedia
secara eksplisit:
```json5
{
@ -38,29 +38,29 @@ otomatis. Untuk menetapkan penyedia secara eksplisit:
Untuk penyiapan multi-endpoint, `provider` juga dapat berupa entri kustom
`models.providers.<id>`, seperti `ollama-5080`, ketika penyedia tersebut menetapkan
`api: "ollama"` atau pemilik adaptor embedding lain.
`api: "ollama"` atau pemilik adapter embedding lainnya.
Untuk embedding lokal tanpa kunci API, instal paket runtime opsional
`node-llama-cpp` di samping OpenClaw dan gunakan `provider: "local"`.
Untuk embedding lokal tanpa kunci API, atur `provider: "local"`. Instalasi paket
mempertahankan runtime `node-llama-cpp` native di pohon runtime-deps plugin terkelola
OpenClaw; jalankan `openclaw doctor --fix` jika pohon tersebut perlu diperbaiki.
Beberapa endpoint embedding yang kompatibel dengan OpenAI memerlukan label
asimetris seperti `input_type: "query"` untuk pencarian dan
`input_type: "document"` atau `"passage"` untuk potongan yang diindeks.
Konfigurasikan dengan `memorySearch.queryInputType` dan
`memorySearch.documentInputType`; lihat [Referensi konfigurasi memori](/id/reference/memory-config#provider-specific-config).
Beberapa endpoint embedding yang kompatibel dengan OpenAI memerlukan label asimetris seperti
`input_type: "query"` untuk pencarian dan `input_type: "document"` atau `"passage"`
untuk potongan yang diindeks. Konfigurasikan itu dengan `memorySearch.queryInputType` dan
`memorySearch.documentInputType`; lihat [referensi konfigurasi memori](/id/reference/memory-config#provider-specific-config).
## Penyedia yang didukung
| Penyedia | ID | Perlu kunci API | Catatan |
| -------------- | ---------------- | --------------- | ------------------------------------------------------- |
| Bedrock | `bedrock` | Tidak | Terdeteksi otomatis saat rantai kredensial AWS berhasil |
| Gemini | `gemini` | Ya | Mendukung pengindeksan gambar/audio |
| GitHub Copilot | `github-copilot` | Tidak | Terdeteksi otomatis, menggunakan langganan Copilot |
| Lokal | `local` | Tidak | Model GGUF, unduhan ~0,6 GB |
| Mistral | `mistral` | Ya | Terdeteksi otomatis |
| Ollama | `ollama` | Tidak | Lokal, harus ditetapkan secara eksplisit |
| OpenAI | `openai` | Ya | Terdeteksi otomatis, cepat |
| Voyage | `voyage` | Ya | Terdeteksi otomatis |
| Penyedia | ID | Memerlukan kunci API | Catatan |
| -------------- | ---------------- | -------------------- | ------------------------------------------------------ |
| Bedrock | `bedrock` | Tidak | Terdeteksi otomatis ketika rantai kredensial AWS berhasil |
| Gemini | `gemini` | Ya | Mendukung pengindeksan gambar/audio |
| GitHub Copilot | `github-copilot` | Tidak | Terdeteksi otomatis, menggunakan langganan Copilot |
| Local | `local` | Tidak | Model GGUF, unduhan ~0,6 GB |
| Mistral | `mistral` | Ya | Terdeteksi otomatis |
| Ollama | `ollama` | Tidak | Lokal, harus diatur secara eksplisit |
| OpenAI | `openai` | Ya | Terdeteksi otomatis, cepat |
| Voyage | `voyage` | Ya | Terdeteksi otomatis |
## Cara kerja pencarian
@ -77,14 +77,14 @@ flowchart LR
M --> R["Top Results"]
```
- **Pencarian vektor** menemukan catatan dengan makna serupa ("gateway host" cocok
dengan "mesin yang menjalankan OpenClaw").
- **Pencarian kata kunci BM25** menemukan kecocokan persis (ID, string error, kunci
- **Pencarian vektor** menemukan catatan dengan makna serupa ("gateway host" cocok dengan
"mesin yang menjalankan OpenClaw").
- **Pencarian kata kunci BM25** menemukan kecocokan persis (ID, string galat, kunci
konfigurasi).
Jika hanya satu jalur yang tersedia (tanpa embedding atau tanpa FTS), jalur lain berjalan sendiri.
Jika hanya satu jalur yang tersedia (tanpa embedding atau tanpa FTS), jalur lainnya berjalan sendiri.
Ketika embedding tidak tersedia, OpenClaw tetap menggunakan pemeringkatan leksikal atas hasil FTS alih-alih hanya kembali ke pengurutan kecocokan persis mentah. Mode terdegradasi itu meningkatkan potongan dengan cakupan istilah kueri yang lebih kuat dan jalur file yang relevan, sehingga recall tetap berguna bahkan tanpa `sqlite-vec` atau penyedia embedding.
Ketika embedding tidak tersedia, OpenClaw tetap menggunakan pemeringkatan leksikal atas hasil FTS alih-alih hanya kembali ke urutan kecocokan persis mentah. Mode terdegradasi tersebut meningkatkan potongan dengan cakupan istilah kueri yang lebih kuat dan jalur file yang relevan, sehingga recall tetap berguna bahkan tanpa `sqlite-vec` atau penyedia embedding.
## Meningkatkan kualitas pencarian
@ -93,21 +93,20 @@ Dua fitur opsional membantu ketika Anda memiliki riwayat catatan yang besar:
### Peluruhan temporal
Catatan lama secara bertahap kehilangan bobot peringkat sehingga informasi terbaru muncul lebih dulu.
Dengan half-life bawaan 30 hari, catatan dari bulan lalu mendapat skor 50% dari
bobot aslinya. File evergreen seperti `MEMORY.md` tidak pernah diluruhkan.
Dengan half-life default 30 hari, catatan dari bulan lalu mendapat skor 50% dari
bobot aslinya. File yang selalu relevan seperti `MEMORY.md` tidak pernah diluruhkan.
<Tip>
Aktifkan peluruhan temporal jika agen Anda memiliki catatan harian selama berbulan-bulan dan
informasi usang terus mengungguli konteks terbaru.
Aktifkan peluruhan temporal jika agen Anda memiliki catatan harian selama berbulan-bulan dan informasi usang terus mengungguli konteks terbaru.
</Tip>
### MMR (keberagaman)
Mengurangi hasil yang berulang. Jika lima catatan semuanya menyebut konfigurasi router yang sama, MMR
memastikan hasil teratas mencakup topik berbeda alih-alih mengulang.
memastikan hasil teratas mencakup topik berbeda alih-alih berulang.
<Tip>
Aktifkan MMR jika `memory_search` terus mengembalikan cuplikan yang hampir duplikat dari
Aktifkan MMR jika `memory_search` terus mengembalikan snippet yang hampir duplikat dari
catatan harian yang berbeda.
</Tip>
@ -132,9 +131,9 @@ catatan harian yang berbeda.
## Memori multimodal
Dengan Gemini Embedding 2, Anda dapat mengindeks file gambar dan audio bersama
Markdown. Kueri pencarian tetap berupa teks, tetapi dicocokkan dengan konten visual dan
audio. Lihat [Referensi konfigurasi memori](/id/reference/memory-config) untuk
Dengan Gemini Embedding 2, Anda dapat mengindeks gambar dan file audio bersama
Markdown. Kueri pencarian tetap berupa teks, tetapi cocok dengan konten visual dan audio.
Lihat [referensi konfigurasi memori](/id/reference/memory-config) untuk
penyiapan.
## Pencarian memori sesi
@ -152,7 +151,7 @@ percakapan sebelumnya. Ini bersifat opt-in melalui
**Hanya kecocokan kata kunci?** Penyedia embedding Anda mungkin belum dikonfigurasi. Periksa
`openclaw memory status --deep`.
**Embedding lokal mengalami timeout?** `ollama`, `lmstudio`, dan `local` menggunakan timeout batch inline yang lebih panjang secara bawaan. Jika host memang lambat, tetapkan
**Embedding lokal mengalami timeout?** `ollama`, `lmstudio`, dan `local` menggunakan timeout batch inline yang lebih panjang secara default. Jika host memang lambat, atur
`agents.defaults.memorySearch.sync.embeddingBatchTimeoutSeconds` dan jalankan ulang
`openclaw memory index --force`.
@ -168,5 +167,5 @@ percakapan sebelumnya. Ini bersifat opt-in melalui
## Terkait
- [Ikhtisar memori](/id/concepts/memory)
- [Active memory](/id/concepts/active-memory)
- [Active Memory](/id/concepts/active-memory)
- [Mesin memori bawaan](/id/concepts/memory-builtin)

132
docs/id/concepts/messages.md
View File

@ -1,20 +1,20 @@
---
read_when:
- Menjelaskan bagaimana pesan masuk menjadi balasan
- Mengklarifikasi sesi, mode antrean, atau perilaku streaming
- Menjelaskan cara pesan masuk menjadi balasan
- Memperjelas sesi, mode antrean, atau perilaku streaming
- Mendokumentasikan visibilitas penalaran dan implikasi penggunaan
summary: Alur pesan, sesi, pengantrean, dan visibilitas penalaran
title: Pesan
x-i18n:
generated_at: "2026-04-30T09:44:07Z"
generated_at: "2026-04-30T16:27:59Z"
model: gpt-5.5
provider: openai
source_hash: dcfcc995995516b627993755b255a779c681b4976d2d724c0c11e87875e37b1e
source_hash: fdeee014d92767a725501691fbe0c4ee6b631acc9a2ab5cbbcf321bfee9679b9
source_path: concepts/messages.md
workflow: 16
---
OpenClaw menangani pesan masuk melalui pipeline resolusi sesi, antrean, streaming, eksekusi alat, dan visibilitas penalaran. Halaman ini memetakan alur dari pesan masuk hingga balasan.
OpenClaw menangani pesan masuk melalui pipeline yang mencakup resolusi sesi, antrean, streaming, eksekusi tool, dan visibilitas penalaran. Halaman ini memetakan alur dari pesan masuk hingga balasan.
## Alur pesan (tingkat tinggi)
@ -26,21 +26,25 @@ Inbound message
-> outbound replies (channel limits + chunking)
```
Knob utama berada di konfigurasi:
Pengaturan utama berada dalam konfigurasi:
- `messages.*` untuk prefiks, antrean, dan perilaku grup.
- `agents.defaults.*` untuk default streaming blok dan pemotongan.
- `agents.defaults.*` untuk default streaming blok dan chunking.
- Override saluran (`channels.whatsapp.*`, `channels.telegram.*`, dll.) untuk batas dan toggle streaming.
Lihat [Konfigurasi](/id/gateway/configuration) untuk skema lengkap.
## Deduplikasi masuk
Saluran dapat mengirim ulang pesan yang sama setelah koneksi ulang. OpenClaw menyimpan cache berumur pendek yang dikunci berdasarkan saluran/akun/peer/sesi/id pesan agar pengiriman duplikat tidak memicu run agen lain.
Saluran dapat mengirim ulang pesan yang sama setelah koneksi ulang. OpenClaw menyimpan
cache berumur pendek yang dikunci berdasarkan saluran/akun/peer/sesi/id pesan sehingga
pengiriman duplikat tidak memicu agent run lain.
## Debouncing masuk
Pesan beruntun yang cepat dari **pengirim yang sama** dapat digabungkan menjadi satu giliran agen melalui `messages.inbound`. Debouncing dibatasi per saluran + percakapan dan menggunakan pesan terbaru untuk threading/ID balasan.
Pesan berurutan yang cepat dari **pengirim yang sama** dapat digabungkan menjadi satu
giliran agent melalui `messages.inbound`. Debouncing dibatasi per saluran + percakapan
dan menggunakan pesan terbaru untuk threading/ID balasan.
Konfigurasi (default global + override per saluran):
@ -61,67 +65,96 @@ Konfigurasi (default global + override per saluran):
Catatan:
- Debounce berlaku untuk pesan **hanya teks**; media/lampiran langsung dikirim.
- Perintah kontrol melewati debouncing agar tetap berdiri sendiri — **kecuali** ketika saluran secara eksplisit memilih ikut penggabungan DM dari pengirim yang sama (mis. [BlueBubbles `coalesceSameSenderDms`](/id/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition)), tempat perintah DM menunggu di dalam jendela debounce agar payload kirim-terpisah dapat bergabung ke giliran agen yang sama.
- Debounce berlaku untuk pesan **hanya teks**; media/lampiran langsung di-flush.
- Perintah kontrol melewati debouncing agar tetap berdiri sendiri — **kecuali** ketika suatu saluran secara eksplisit ikut serta dalam penggabungan DM dari pengirim yang sama (mis. [BlueBubbles `coalesceSameSenderDms`](/id/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition)), di mana perintah DM menunggu di dalam jendela debounce sehingga payload split-send dapat bergabung dalam giliran agent yang sama.
## Sesi dan perangkat
Sesi dimiliki oleh Gateway, bukan oleh klien.
- Chat langsung digabungkan ke kunci sesi utama agen.
- Grup/saluran mendapatkan kunci sesi sendiri.
- Chat langsung dilebur ke dalam kunci sesi utama agent.
- Grup/saluran mendapatkan kunci sesinya sendiri.
- Penyimpanan sesi dan transkrip berada di host Gateway.
Beberapa perangkat/saluran dapat dipetakan ke sesi yang sama, tetapi riwayat tidak disinkronkan penuh kembali ke setiap klien. Rekomendasi: gunakan satu perangkat utama untuk percakapan panjang guna menghindari konteks yang menyimpang. Control UI dan TUI selalu menampilkan transkrip sesi yang didukung Gateway, sehingga keduanya menjadi sumber kebenaran.
Beberapa perangkat/saluran dapat dipetakan ke sesi yang sama, tetapi riwayat tidak sepenuhnya
disinkronkan kembali ke setiap klien. Rekomendasi: gunakan satu perangkat utama untuk
percakapan panjang agar konteks tidak bercabang. Control UI dan TUI selalu menampilkan
transkrip sesi yang didukung Gateway, sehingga keduanya adalah sumber kebenaran.
Detail: [Manajemen sesi](/id/concepts/session).
## Metadata hasil alat
## Metadata hasil tool
`content` hasil alat adalah hasil yang terlihat oleh model. `details` hasil alat adalah metadata runtime untuk rendering UI, diagnostik, pengiriman media, dan plugin.
`content` hasil tool adalah hasil yang terlihat oleh model. `details` hasil tool adalah
metadata runtime untuk rendering UI, diagnostik, pengiriman media, dan Plugin.
OpenClaw menjaga batas tersebut tetap eksplisit:
- `toolResult.details` dihapus sebelum replay penyedia dan input Compaction.
- Transkrip sesi yang dipersistenkan hanya menyimpan `details` yang dibatasi; metadata yang terlalu besar diganti dengan ringkasan ringkas bertanda `persistedDetailsTruncated: true`.
- Plugin dan alat harus menaruh teks yang wajib dibaca model di `content`, bukan hanya di `details`.
- `toolResult.details` dihapus sebelum replay provider dan input compaction.
- Transkrip sesi yang dipersistenkan hanya menyimpan `details` yang dibatasi; metadata yang terlalu besar
diganti dengan ringkasan ringkas yang ditandai `persistedDetailsTruncated: true`.
- Plugin dan tool harus menaruh teks yang harus dibaca model di `content`, bukan hanya
di `details`.
## Isi masuk dan konteks riwayat
OpenClaw memisahkan **isi prompt** dari **isi perintah**:
- `Body`: teks prompt yang dikirim ke agen. Ini dapat mencakup envelope saluran dan wrapper riwayat opsional.
- `CommandBody`: teks mentah pengguna untuk parsing direktif/perintah.
- `BodyForAgent`: teks utama yang menghadap model untuk pesan saat ini. Plugin saluran
harus menjaga ini tetap terfokus pada teks pembawa prompt saat ini dari pengirim.
- `Body`: fallback prompt lama. Ini dapat mencakup envelope saluran dan
wrapper riwayat opsional, tetapi saluran saat ini tidak boleh mengandalkannya sebagai
input model utama ketika `BodyForAgent` tersedia.
- `CommandBody`: teks pengguna mentah untuk parsing direktif/perintah.
- `RawBody`: alias lama untuk `CommandBody` (dipertahankan untuk kompatibilitas).
Ketika saluran menyediakan riwayat, saluran menggunakan wrapper bersama:
Ketika saluran menyediakan riwayat, saluran tersebut menggunakan wrapper bersama:
- `[Chat messages since your last reply - for context]`
- `[Current message - respond to this]`
Untuk **chat non-langsung** (grup/saluran/ruang), **isi pesan saat ini** diberi prefiks dengan label pengirim (gaya yang sama digunakan untuk entri riwayat). Ini menjaga pesan real-time dan antrean/riwayat tetap konsisten dalam prompt agen.
Untuk **chat tidak langsung** (grup/saluran/ruang), **isi pesan saat ini** diawali dengan
label pengirim (gaya yang sama dengan entri riwayat). Ini menjaga pesan real-time dan pesan
antrean/riwayat tetap konsisten dalam prompt agent.
Buffer riwayat bersifat **hanya-tertunda**: buffer ini mencakup pesan grup yang _tidak_ memicu run (misalnya, pesan yang dibatasi mention) dan **mengecualikan** pesan yang sudah ada dalam transkrip sesi.
Buffer riwayat bersifat **hanya tertunda**: mencakup pesan grup yang _tidak_
memicu run (misalnya, pesan yang dibatasi oleh mention) dan **mengecualikan** pesan
yang sudah ada dalam transkrip sesi.
Penghapusan direktif hanya berlaku pada bagian **pesan saat ini** sehingga riwayat tetap utuh. Saluran yang membungkus riwayat harus menetapkan `CommandBody` (atau `RawBody`) ke teks pesan asli dan menjaga `Body` sebagai prompt gabungan. Buffer riwayat dapat dikonfigurasi melalui `messages.groupChat.historyLimit` (default global) dan override per saluran seperti `channels.slack.historyLimit` atau `channels.telegram.accounts.<id>.historyLimit` (atur `0` untuk menonaktifkan).
Penghapusan direktif hanya berlaku pada bagian **pesan saat ini** sehingga riwayat
tetap utuh. Saluran yang membungkus riwayat harus mengatur `CommandBody` (atau
`RawBody`) ke teks pesan asli dan menjaga `Body` sebagai prompt gabungan.
Riwayat terstruktur, balasan, pesan yang diteruskan, dan metadata saluran dirender sebagai
blok konteks tidak tepercaya dengan peran pengguna saat perakitan prompt.
Buffer riwayat dapat dikonfigurasi melalui `messages.groupChat.historyLimit` (default
global) dan override per saluran seperti `channels.slack.historyLimit` atau
`channels.telegram.accounts.<id>.historyLimit` (atur `0` untuk menonaktifkan).
## Antrean dan tindak lanjut
Jika run sudah aktif, pesan masuk dapat diantrekan, diarahkan ke run saat ini, atau dikumpulkan untuk giliran tindak lanjut.
Jika suatu run sudah aktif, pesan masuk dapat dimasukkan ke antrean, diarahkan ke
run saat ini, atau dikumpulkan untuk giliran tindak lanjut.
- Konfigurasikan melalui `messages.queue` (dan `messages.queue.byChannel`).
- Mode default adalah `steer`, dengan debounce tindak lanjut 500 md ketika pengarahan fallback ke pengiriman tindak lanjut yang diantrekan.
- Mode: `steer`, `followup`, `collect`, `steer-backlog`, `interrupt`, dan mode lama satu-per-satu `queue`.
- Mode default adalah `steer`, dengan debounce tindak lanjut 500 ms ketika pengarahan
kembali ke pengiriman tindak lanjut yang diantrekan.
- Mode: `steer`, `followup`, `collect`, `steer-backlog`, `interrupt`, dan mode lama
`queue` satu per satu.
Detail: [Antrean perintah](/id/concepts/queue) dan [Antrean pengarahan](/id/concepts/queue-steering).
## Kepemilikan run saluran
Plugin saluran dapat mempertahankan urutan, men-debounce input, dan menerapkan backpressure transport sebelum pesan masuk ke antrean sesi. Plugin tersebut tidak boleh memberlakukan timeout terpisah di sekitar giliran agen itu sendiri. Setelah pesan dirutekan ke sebuah sesi, pekerjaan yang berjalan lama diatur oleh siklus hidup sesi, alat, dan runtime sehingga semua saluran melaporkan serta pulih dari giliran lambat secara konsisten.
Plugin saluran dapat mempertahankan urutan, melakukan debounce input, dan menerapkan
backpressure transport sebelum pesan masuk ke antrean sesi. Plugin tidak boleh memaksakan
timeout terpisah di sekitar giliran agent itu sendiri. Setelah pesan dirutekan ke suatu
sesi, pekerjaan berdurasi panjang diatur oleh siklus hidup sesi, tool, dan runtime
agar semua saluran melaporkan dan pulih dari giliran lambat secara konsisten.
## Streaming, pemotongan, dan batching
## Streaming, chunking, dan batching
Streaming blok mengirim balasan parsial saat model menghasilkan blok teks. Pemotongan mematuhi batas teks saluran dan menghindari pemisahan kode berpagar.
Streaming blok mengirim balasan parsial saat model menghasilkan blok teks.
Chunking menghormati batas teks saluran dan menghindari pemecahan kode berpagar.
Pengaturan utama:
@ -129,18 +162,18 @@ Pengaturan utama:
- `agents.defaults.blockStreamingBreak` (`text_end|message_end`)
- `agents.defaults.blockStreamingChunk` (`minChars|maxChars|breakPreference`)
- `agents.defaults.blockStreamingCoalesce` (batching berbasis idle)
- `agents.defaults.humanDelay` (jeda seperti manusia antar balasan blok)
- `agents.defaults.humanDelay` (jeda seperti manusia antarbalasan blok)
- Override saluran: `*.blockStreaming` dan `*.blockStreamingCoalesce` (saluran non-Telegram memerlukan `*.blockStreaming: true` eksplisit)
Detail: [Streaming + pemotongan](/id/concepts/streaming).
Detail: [Streaming + chunking](/id/concepts/streaming).
## Visibilitas penalaran dan token
OpenClaw dapat mengekspos atau menyembunyikan penalaran model:
- `/reasoning on|off|stream` mengontrol visibilitas.
- Konten penalaran tetap dihitung dalam penggunaan token ketika dihasilkan oleh model.
- Telegram mendukung stream penalaran ke bubble draf.
- Konten penalaran tetap dihitung dalam penggunaan token ketika diproduksi oleh model.
- Telegram mendukung stream penalaran ke dalam gelembung draf.
Detail: [Direktif berpikir + penalaran](/id/tools/thinking) dan [Penggunaan token](/id/reference/token-use).
@ -148,7 +181,7 @@ Detail: [Direktif berpikir + penalaran](/id/tools/thinking) dan [Penggunaan toke
Pemformatan pesan keluar dipusatkan di `messages`:
- `messages.responsePrefix`, `channels.<channel>.responsePrefix`, dan `channels.<channel>.accounts.<id>.responsePrefix` (cascade prefiks keluar), ditambah `channels.whatsapp.messagePrefix` (prefiks masuk WhatsApp)
- `messages.responsePrefix`, `channels.<channel>.responsePrefix`, dan `channels.<channel>.accounts.<id>.responsePrefix` (kaskade prefiks keluar), plus `channels.whatsapp.messagePrefix` (prefiks masuk WhatsApp)
- Threading balasan melalui `replyToMode` dan default per saluran
Detail: [Konfigurasi](/id/gateway/config-agents#messages) dan dokumentasi saluran.
@ -156,22 +189,31 @@ Detail: [Konfigurasi](/id/gateway/config-agents#messages) dan dokumentasi salura
## Balasan senyap
Token senyap persis `NO_REPLY` / `no_reply` berarti “jangan kirim balasan yang terlihat pengguna”.
Ketika sebuah giliran juga memiliki media alat yang tertunda, seperti audio TTS yang dihasilkan, OpenClaw menghapus teks senyap tetapi tetap mengirim lampiran media.
Ketika suatu giliran juga memiliki media tool yang tertunda, seperti audio TTS yang dihasilkan, OpenClaw
menghapus teks senyap tetapi tetap mengirim lampiran media.
OpenClaw menyelesaikan perilaku tersebut berdasarkan jenis percakapan:
- Percakapan langsung tidak mengizinkan kesenyapan secara default dan menulis ulang balasan senyap polos menjadi fallback pendek yang terlihat.
- Grup/saluran mengizinkan kesenyapan secara default.
- Orkestrasi internal mengizinkan kesenyapan secara default.
- Percakapan langsung tidak mengizinkan senyap secara default dan menulis ulang balasan
senyap polos menjadi fallback singkat yang terlihat.
- Grup/saluran mengizinkan senyap secara default.
- Orkestrasi internal mengizinkan senyap secara default.
OpenClaw juga menggunakan balasan senyap untuk kegagalan runner internal yang terjadi sebelum balasan asisten apa pun dalam chat non-langsung, sehingga grup/saluran tidak melihat boilerplate kesalahan Gateway. Chat langsung menampilkan salinan kegagalan ringkas secara default; detail runner mentah hanya ditampilkan ketika `/verbose` bernilai `on` atau `full`.
OpenClaw juga menggunakan balasan senyap untuk kegagalan runner internal yang terjadi
sebelum balasan asisten apa pun dalam chat tidak langsung, sehingga grup/saluran tidak melihat
boilerplate error Gateway. Chat langsung menampilkan salinan kegagalan yang ringkas secara default;
detail runner mentah hanya ditampilkan ketika `/verbose` adalah `on` atau `full`.
Default berada di bawah `agents.defaults.silentReply` dan `agents.defaults.silentReplyRewrite`; `surfaces.<id>.silentReply` dan `surfaces.<id>.silentReplyRewrite` dapat meng-override-nya per surface.
Default berada di bawah `agents.defaults.silentReply` dan
`agents.defaults.silentReplyRewrite`; `surfaces.<id>.silentReply` dan
`surfaces.<id>.silentReplyRewrite` dapat meng-override-nya per surface.
Ketika sesi induk memiliki satu atau beberapa run subagen hasil spawn yang tertunda, balasan senyap polos dihapus pada semua surface alih-alih ditulis ulang, sehingga induk tetap diam sampai event penyelesaian anak mengirim balasan sebenarnya.
Ketika sesi induk memiliki satu atau lebih spawned subagent run yang tertunda, balasan
senyap polos dibuang di semua surface alih-alih ditulis ulang, sehingga induk
tetap diam sampai event penyelesaian anak mengirim balasan sebenarnya.
## Terkait
- [Streaming](/id/concepts/streaming) — pengiriman pesan real-time
- [Coba lagi](/id/concepts/retry) — perilaku coba lagi pengiriman pesan
- [Coba ulang](/id/concepts/retry) — perilaku coba ulang pengiriman pesan
- [Antrean](/id/concepts/queue) — antrean pemrosesan pesan
- [Saluran](/id/channels) — integrasi platform perpesanan
- [Saluran](/id/channels) — integrasi platform pesan

446
docs/id/gateway/config-agents.md
View File

@ -1,15 +1,15 @@
---
read_when:
- Menyesuaikan pengaturan bawaan agen (model, pemikiran, ruang kerja, Heartbeat, media, Skills)
- Menyesuaikan default agen (model, penalaran, ruang kerja, Heartbeat, media, Skills)
- Mengonfigurasi perutean dan pengikatan multi-agen
- Menyesuaikan perilaku sesi, pengiriman pesan, dan mode bicara
summary: Default agen, perutean multi-agen, sesi, pesan, dan konfigurasi percakapan
title: Konfigurasi — agen
x-i18n:
generated_at: "2026-04-30T09:47:05Z"
generated_at: "2026-04-30T16:28:04Z"
model: gpt-5.5
provider: openai
source_hash: 61f2d33ae1d3f4ce07636ae4584b9e344fd14e8e08a2612bb1f39ed71c99c25a
source_hash: e6a38f42c35c6c6e46d6d00ad710c6c80d78703e0b7e3388f5631cf91eb17084
source_path: gateway/config-agents.md
workflow: 16
---
@ -18,7 +18,7 @@ Kunci konfigurasi bercakupan agen di bawah `agents.*`, `multiAgent.*`, `session.
`messages.*`, dan `talk.*`. Untuk channel, alat, runtime Gateway, dan kunci
tingkat atas lainnya, lihat [Referensi konfigurasi](/id/gateway/configuration-reference).
## Default Agen
## Default agen
### `agents.defaults.workspace`
@ -32,7 +32,7 @@ Bawaan: `~/.openclaw/workspace`.
### `agents.defaults.repoRoot`
Root repositori opsional yang ditampilkan di baris Runtime prompt sistem. Jika tidak diatur, OpenClaw mendeteksi otomatis dengan menelusuri ke atas dari workspace.
Root repositori opsional yang ditampilkan di baris Runtime pada prompt sistem. Jika tidak diatur, OpenClaw mendeteksi otomatis dengan menelusuri ke atas dari workspace.
```json5
{
@ -42,7 +42,7 @@ Root repositori opsional yang ditampilkan di baris Runtime prompt sistem. Jika t
### `agents.defaults.skills`
Allowlist Skills default opsional untuk agen yang tidak mengatur
Allowlist skill default opsional untuk agen yang tidak menetapkan
`agents.list[].skills`.
```json5
@ -58,10 +58,10 @@ Allowlist Skills default opsional untuk agen yang tidak mengatur
}
```
- Hilangkan `agents.defaults.skills` untuk Skills tanpa pembatasan secara default.
- Hilangkan `agents.list[].skills` untuk mewarisi default.
- Abaikan `agents.defaults.skills` agar Skills tidak dibatasi secara default.
- Abaikan `agents.list[].skills` untuk mewarisi default.
- Atur `agents.list[].skills: []` untuk tanpa Skills.
- Daftar `agents.list[].skills` yang tidak kosong adalah himpunan final untuk agen tersebut; daftar itu
- Daftar `agents.list[].skills` yang tidak kosong adalah kumpulan final untuk agen tersebut; daftar itu
tidak digabungkan dengan default.
### `agents.defaults.skipBootstrap`
@ -78,8 +78,8 @@ Menonaktifkan pembuatan otomatis file bootstrap workspace (`AGENTS.md`, `SOUL.md
Mengontrol kapan file bootstrap workspace disuntikkan ke prompt sistem. Bawaan: `"always"`.
- `"continuation-skip"`: giliran kelanjutan yang aman (setelah respons asisten selesai) melewati penyuntikan ulang bootstrap workspace, sehingga mengurangi ukuran prompt. Proses Heartbeat dan percobaan ulang pasca-Compaction tetap membangun ulang konteks.
- `"never"`: nonaktifkan bootstrap workspace dan penyuntikan file konteks pada setiap giliran. Gunakan ini hanya untuk agen yang sepenuhnya memiliki siklus hidup prompt mereka (mesin konteks kustom, runtime native yang membangun konteksnya sendiri, atau workflow khusus tanpa bootstrap). Giliran Heartbeat dan pemulihan Compaction juga melewati penyuntikan.
- `"continuation-skip"`: giliran lanjutan yang aman (setelah respons asisten selesai) melewati penyuntikan ulang bootstrap workspace, sehingga mengurangi ukuran prompt. Jalankan Heartbeat dan percobaan ulang pasca-Compaction tetap membangun ulang konteks.
- `"never"`: nonaktifkan bootstrap workspace dan penyuntikan file konteks pada setiap giliran. Gunakan ini hanya untuk agen yang sepenuhnya mengelola siklus hidup prompt mereka sendiri (mesin konteks kustom, runtime native yang membangun konteksnya sendiri, atau workflow khusus tanpa bootstrap). Giliran Heartbeat dan pemulihan Compaction juga melewati penyuntikan.
```json5
{
@ -89,7 +89,7 @@ Mengontrol kapan file bootstrap workspace disuntikkan ke prompt sistem. Bawaan:
### `agents.defaults.bootstrapMaxChars`
Karakter maksimum per file bootstrap workspace sebelum dipotong. Bawaan: `12000`.
Karakter maksimum per file bootstrap workspace sebelum pemotongan. Bawaan: `12000`.
```json5
{
@ -122,27 +122,27 @@ Bawaan: `"once"`.
}
```
### Peta Kepemilikan Anggaran Konteks
### Peta kepemilikan anggaran konteks
OpenClaw memiliki beberapa anggaran prompt/konteks bervolume tinggi, dan anggaran tersebut
secara sengaja dipisah menurut subsistem, bukan semuanya mengalir melalui satu
pengaturan generik.
sengaja dipisahkan menurut subsistem, bukan semuanya mengalir melalui satu
knob generik.
- `agents.defaults.bootstrapMaxChars` /
`agents.defaults.bootstrapTotalMaxChars`:
penyuntikan bootstrap workspace normal.
- `agents.defaults.startupContext.*`:
prelude satu kali untuk proses model reset/startup, termasuk file
`memory/*.md` harian terbaru. Perintah chat polos `/new` dan `/reset`
prelude satu kali untuk reset/startup model-run, termasuk file
`memory/*.md` harian terbaru. Perintah chat murni `/new` dan `/reset`
diakui tanpa memanggil model.
- `skills.limits.*`:
daftar Skills ringkas yang disuntikkan ke prompt sistem.
- `agents.defaults.contextLimits.*`:
kutipan runtime terbatas dan blok milik runtime yang disuntikkan.
kutipan runtime berbatas dan blok milik runtime yang disuntikkan.
- `memory.qmd.limits.*`:
cuplikan pencarian memori terindeks dan ukuran penyuntikan.
ukuran snippet pencarian memori terindeks dan penyuntikan.
Gunakan override per agen yang sesuai hanya ketika satu agen membutuhkan
Gunakan override per agen yang sesuai hanya saat satu agen membutuhkan
anggaran berbeda:
- `agents.list[].skillsLimits.maxSkillsPromptChars`
@ -150,9 +150,9 @@ anggaran berbeda:
#### `agents.defaults.startupContext`
Mengontrol prelude startup giliran pertama yang disuntikkan pada proses model reset/startup.
Perintah chat polos `/new` dan `/reset` mengakui reset tanpa memanggil
model, sehingga perintah tersebut tidak memuat prelude ini.
Mengontrol prelude startup giliran pertama yang disuntikkan pada model run reset/startup.
Perintah chat murni `/new` dan `/reset` mengakui reset tanpa memanggil
model, sehingga tidak memuat prelude ini.
```json5
{
@ -173,7 +173,7 @@ model, sehingga perintah tersebut tidak memuat prelude ini.
#### `agents.defaults.contextLimits`
Default bersama untuk permukaan konteks runtime terbatas.
Default bersama untuk permukaan konteks runtime berbatas.
```json5
{
@ -191,17 +191,17 @@ Default bersama untuk permukaan konteks runtime terbatas.
```
- `memoryGetMaxChars`: batas kutipan `memory_get` default sebelum metadata
pemotongan dan pemberitahuan kelanjutan ditambahkan.
- `memoryGetDefaultLines`: jendela baris `memory_get` default ketika `lines`
dihilangkan.
- `toolResultMaxChars`: batas hasil alat langsung yang digunakan untuk hasil tersimpan dan
pemotongan dan pemberitahuan lanjutan ditambahkan.
- `memoryGetDefaultLines`: jendela baris `memory_get` default saat `lines`
diabaikan.
- `toolResultMaxChars`: batas hasil alat live yang digunakan untuk hasil persisten dan
pemulihan luapan.
- `postCompactionMaxChars`: batas kutipan AGENTS.md yang digunakan selama penyuntikan
penyegaran pasca-Compaction.
refresh pasca-Compaction.
#### `agents.list[].contextLimits`
Override per agen untuk pengaturan `contextLimits` bersama. Field yang dihilangkan mewarisi
Override per agen untuk knob `contextLimits` bersama. Bidang yang diabaikan mewarisi
dari `agents.defaults.contextLimits`.
```json5
@ -229,7 +229,7 @@ dari `agents.defaults.contextLimits`.
#### `skills.limits.maxSkillsPromptChars`
Batas global untuk daftar Skills ringkas yang disuntikkan ke prompt sistem. Ini
tidak memengaruhi pembacaan file `SKILL.md` sesuai permintaan.
tidak memengaruhi pembacaan file `SKILL.md` sesuai kebutuhan.
```json5
{
@ -262,10 +262,10 @@ Override per agen untuk anggaran prompt Skills.
### `agents.defaults.imageMaxDimensionPx`
Ukuran piksel maksimum untuk sisi gambar terpanjang dalam blok gambar transcript/alat sebelum panggilan provider.
Ukuran piksel maksimum untuk sisi gambar terpanjang dalam blok gambar transkrip/alat sebelum panggilan penyedia.
Bawaan: `1200`.
Nilai yang lebih rendah biasanya mengurangi penggunaan token visi dan ukuran payload permintaan untuk proses yang banyak memakai tangkapan layar.
Nilai yang lebih rendah biasanya mengurangi penggunaan token visi dan ukuran payload permintaan untuk proses yang banyak memakai screenshot.
Nilai yang lebih tinggi mempertahankan lebih banyak detail visual.
```json5
@ -276,7 +276,7 @@ Nilai yang lebih tinggi mempertahankan lebih banyak detail visual.
### `agents.defaults.userTimezone`
Zona waktu untuk konteks prompt sistem (bukan timestamp pesan). Fallback ke zona waktu host.
Zona waktu untuk konteks prompt sistem (bukan timestamp pesan). Kembali ke zona waktu host sebagai fallback.
```json5
{
@ -346,57 +346,57 @@ Format waktu dalam prompt sistem. Bawaan: `auto` (preferensi OS).
- `model`: menerima string (`"provider/model"`) atau objek (`{ primary, fallbacks }`).
- Bentuk string hanya menetapkan model utama.
- Bentuk objek menetapkan model utama beserta model failover berurutan.
- Bentuk objek menetapkan model utama plus model failover berurutan.
- `imageModel`: menerima string (`"provider/model"`) atau objek (`{ primary, fallbacks }`).
- Digunakan oleh jalur alat `image` sebagai konfigurasi model vision-nya.
- Juga digunakan sebagai perutean fallback ketika model yang dipilih/default tidak dapat menerima input gambar.
- Utamakan referensi `provider/model` eksplisit. ID polos diterima untuk kompatibilitas; jika ID polos cocok secara unik dengan entri berkemampuan gambar yang dikonfigurasi di `models.providers.*.models`, OpenClaw melengkapinya ke penyedia tersebut. Kecocokan terkonfigurasi yang ambigu memerlukan prefiks penyedia eksplisit.
- Utamakan referensi `provider/model` eksplisit. ID polos diterima untuk kompatibilitas; jika ID polos cocok secara unik dengan entri berkemampuan gambar yang dikonfigurasi di `models.providers.*.models`, OpenClaw melengkapinya ke provider tersebut. Kecocokan terkonfigurasi yang ambigu memerlukan prefiks provider eksplisit.
- `imageGenerationModel`: menerima string (`"provider/model"`) atau objek (`{ primary, fallbacks }`).
- Digunakan oleh kapabilitas pembuatan gambar bersama dan permukaan alat/Plugin mendatang apa pun yang menghasilkan gambar.
- Nilai umum: `google/gemini-3.1-flash-image-preview` untuk pembuatan gambar native Gemini, `fal/fal-ai/flux/dev` untuk fal, `openai/gpt-image-2` untuk OpenAI Images, atau `openai/gpt-image-1.5` untuk output PNG/WebP OpenAI dengan latar belakang transparan.
- Jika Anda memilih penyedia/model secara langsung, konfigurasikan juga autentikasi penyedia yang sesuai (misalnya `GEMINI_API_KEY` atau `GOOGLE_API_KEY` untuk `google/*`, `OPENAI_API_KEY` atau OpenAI Codex OAuth untuk `openai/gpt-image-2` / `openai/gpt-image-1.5`, `FAL_KEY` untuk `fal/*`).
- Jika dihilangkan, `image_generate` masih dapat menyimpulkan default penyedia yang didukung autentikasi. Ia mencoba penyedia default saat ini terlebih dahulu, lalu penyedia pembuatan gambar terdaftar yang tersisa dalam urutan ID penyedia.
- Digunakan oleh kapabilitas pembuatan gambar bersama dan surface alat/plugin apa pun di masa mendatang yang menghasilkan gambar.
- Nilai umum: `google/gemini-3.1-flash-image-preview` untuk pembuatan gambar native Gemini, `fal/fal-ai/flux/dev` untuk fal, `openai/gpt-image-2` untuk OpenAI Images, atau `openai/gpt-image-1.5` untuk output PNG/WebP OpenAI berlatar belakang transparan.
- Jika Anda memilih provider/model secara langsung, konfigurasikan juga auth provider yang cocok (misalnya `GEMINI_API_KEY` atau `GOOGLE_API_KEY` untuk `google/*`, `OPENAI_API_KEY` atau OpenAI Codex OAuth untuk `openai/gpt-image-2` / `openai/gpt-image-1.5`, `FAL_KEY` untuk `fal/*`).
- Jika dihilangkan, `image_generate` masih dapat menyimpulkan default provider yang didukung auth. Ini mencoba provider default saat ini terlebih dahulu, lalu provider pembuatan gambar terdaftar lainnya dalam urutan ID provider.
- `musicGenerationModel`: menerima string (`"provider/model"`) atau objek (`{ primary, fallbacks }`).
- Digunakan oleh kapabilitas pembuatan musik bersama dan alat bawaan `music_generate`.
- Nilai umum: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview`, atau `minimax/music-2.6`.
- Jika dihilangkan, `music_generate` masih dapat menyimpulkan default penyedia yang didukung autentikasi. Ia mencoba penyedia default saat ini terlebih dahulu, lalu penyedia pembuatan musik terdaftar yang tersisa dalam urutan ID penyedia.
- Jika Anda memilih penyedia/model secara langsung, konfigurasikan juga autentikasi/kunci API penyedia yang sesuai.
- Jika dihilangkan, `music_generate` masih dapat menyimpulkan default provider yang didukung auth. Ini mencoba provider default saat ini terlebih dahulu, lalu provider pembuatan musik terdaftar lainnya dalam urutan ID provider.
- Jika Anda memilih provider/model secara langsung, konfigurasikan juga auth/kunci API provider yang cocok.
- `videoGenerationModel`: menerima string (`"provider/model"`) atau objek (`{ primary, fallbacks }`).
- Digunakan oleh kapabilitas pembuatan video bersama dan alat bawaan `video_generate`.
- Nilai umum: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash`, atau `qwen/wan2.7-r2v`.
- Jika dihilangkan, `video_generate` masih dapat menyimpulkan default penyedia yang didukung autentikasi. Ia mencoba penyedia default saat ini terlebih dahulu, lalu penyedia pembuatan video terdaftar yang tersisa dalam urutan ID penyedia.
- Jika Anda memilih penyedia/model secara langsung, konfigurasikan juga autentikasi/kunci API penyedia yang sesuai.
- Penyedia pembuatan video Qwen bawaan mendukung hingga 1 video output, 1 gambar input, 4 video input, durasi 10 detik, serta opsi tingkat penyedia `size`, `aspectRatio`, `resolution`, `audio`, dan `watermark`.
- Jika dihilangkan, `video_generate` masih dapat menyimpulkan default provider yang didukung auth. Ini mencoba provider default saat ini terlebih dahulu, lalu provider pembuatan video terdaftar lainnya dalam urutan ID provider.
- Jika Anda memilih provider/model secara langsung, konfigurasikan juga auth/kunci API provider yang cocok.
- Provider pembuatan video Qwen yang dibundel mendukung hingga 1 video output, 1 gambar input, 4 video input, durasi 10 detik, serta opsi tingkat provider `size`, `aspectRatio`, `resolution`, `audio`, dan `watermark`.
- `pdfModel`: menerima string (`"provider/model"`) atau objek (`{ primary, fallbacks }`).
- Digunakan oleh alat `pdf` untuk perutean model.
- Jika dihilangkan, alat PDF fallback ke `imageModel`, lalu ke model sesi/default yang sudah diselesaikan.
- Jika dihilangkan, alat PDF fallback ke `imageModel`, lalu ke model sesi/default yang di-resolve.
- `pdfMaxBytesMb`: batas ukuran PDF default untuk alat `pdf` ketika `maxBytesMb` tidak diteruskan saat pemanggilan.
- `pdfMaxPages`: jumlah halaman maksimum default yang dipertimbangkan oleh mode fallback ekstraksi di alat `pdf`.
- `verboseDefault`: tingkat verbose default untuk agen. Nilai: `"off"`, `"on"`, `"full"`. Default: `"off"`.
- `reasoningDefault`: visibilitas penalaran default untuk agen. Nilai: `"off"`, `"on"`, `"stream"`. `agents.list[].reasoningDefault` per agen menimpa default ini. Default penalaran yang dikonfigurasi hanya diterapkan untuk pemilik, pengirim terotorisasi, atau konteks Gateway operator-admin ketika tidak ada override penalaran per pesan atau sesi yang ditetapkan.
- `reasoningDefault`: visibilitas reasoning default untuk agen. Nilai: `"off"`, `"on"`, `"stream"`. `agents.list[].reasoningDefault` per agen mengganti default ini. Default reasoning yang dikonfigurasi hanya diterapkan untuk owner, pengirim yang diotorisasi, atau konteks Gateway operator-admin ketika tidak ada override reasoning per pesan atau sesi yang ditetapkan.
- `elevatedDefault`: tingkat output elevated default untuk agen. Nilai: `"off"`, `"on"`, `"ask"`, `"full"`. Default: `"on"`.
- `model.primary`: format `provider/model` (misalnya `openai/gpt-5.5` untuk akses kunci API atau `openai-codex/gpt-5.5` untuk Codex OAuth). Jika Anda menghilangkan penyedia, OpenClaw mencoba alias terlebih dahulu, lalu kecocokan penyedia terkonfigurasi yang unik untuk ID model persis tersebut, dan baru setelah itu fallback ke penyedia default yang dikonfigurasi (perilaku kompatibilitas yang sudah deprecated, jadi utamakan `provider/model` eksplisit). Jika penyedia tersebut tidak lagi mengekspos model default yang dikonfigurasi, OpenClaw fallback ke penyedia/model terkonfigurasi pertama, bukan memunculkan default penyedia lama yang sudah dihapus.
- `models`: katalog model terkonfigurasi dan allowlist untuk `/model`. Setiap entri dapat menyertakan `alias` (pintasan) dan `params` (khusus penyedia, misalnya `temperature`, `maxTokens`, `cacheRetention`, `context1m`, `responsesServerCompaction`, `responsesCompactThreshold`, `chat_template_kwargs`, `extra_body`/`extraBody`).
- Edit aman: gunakan `openclaw config set agents.defaults.models '<json>' --strict-json --merge` untuk menambahkan entri. `config set` menolak penggantian yang akan menghapus entri allowlist yang ada kecuali Anda meneruskan `--replace`.
- Alur konfigurasi/onboarding berskup penyedia menggabungkan model penyedia yang dipilih ke dalam peta ini dan mempertahankan penyedia tidak terkait yang sudah dikonfigurasi.
- Untuk model OpenAI Responses langsung, Compaction sisi server diaktifkan secara otomatis. Gunakan `params.responsesServerCompaction: false` untuk berhenti menyisipkan `context_management`, atau `params.responsesCompactThreshold` untuk menimpa ambang batas. Lihat [Compaction sisi server OpenAI](/id/providers/openai#server-side-compaction-responses-api).
- `params`: parameter penyedia default global yang diterapkan ke semua model. Tetapkan di `agents.defaults.params` (misalnya `{ cacheRetention: "long" }`).
- Prioritas penggabungan `params` (konfigurasi): `agents.defaults.params` (basis global) ditimpa oleh `agents.defaults.models["provider/model"].params` (per model), lalu `agents.list[].params` (ID agen yang cocok) menimpa berdasarkan kunci. Lihat [Prompt Caching](/id/reference/prompt-caching) untuk detail.
- `params.extra_body`/`params.extraBody`: JSON pass-through lanjutan yang digabungkan ke badan permintaan `api: "openai-completions"` untuk proxy yang kompatibel dengan OpenAI. Jika bertabrakan dengan kunci permintaan yang dihasilkan, badan ekstra menang; rute completions non-native tetap menghapus `store` khusus OpenAI setelahnya.
- `params.chat_template_kwargs`: argumen chat-template yang kompatibel dengan vLLM/OpenAI yang digabungkan ke badan permintaan tingkat atas `api: "openai-completions"`. Untuk `vllm/nemotron-3-*` dengan thinking nonaktif, Plugin vLLM bawaan otomatis mengirim `enable_thinking: false` dan `force_nonempty_content: true`; `chat_template_kwargs` eksplisit menimpa default yang dihasilkan, dan `extra_body.chat_template_kwargs` tetap memiliki prioritas akhir. Untuk kontrol thinking Qwen vLLM, tetapkan `params.qwenThinkingFormat` ke `"chat-template"` atau `"top-level"` pada entri model tersebut.
- `compat.supportedReasoningEfforts`: daftar upaya penalaran per model yang kompatibel dengan OpenAI. Sertakan `"xhigh"` untuk endpoint kustom yang benar-benar menerimanya; OpenClaw kemudian mengekspos `/think xhigh` di menu perintah, baris sesi Gateway, validasi patch sesi, validasi CLI agen, dan validasi `llm-task` untuk penyedia/model terkonfigurasi tersebut. Gunakan `compat.reasoningEffortMap` ketika backend menginginkan nilai khusus penyedia untuk level kanonis.
- `params.preserveThinking`: opt-in khusus Z.AI untuk thinking yang dipertahankan. Saat diaktifkan dan thinking aktif, OpenClaw mengirim `thinking.clear_thinking: false` dan memutar ulang `reasoning_content` sebelumnya; lihat [thinking Z.AI dan thinking yang dipertahankan](/id/providers/zai#thinking-and-preserved-thinking).
- `agentRuntime`: kebijakan runtime agen tingkat rendah default. ID yang dihilangkan default ke OpenClaw Pi. Gunakan `id: "pi"` untuk memaksa harness PI bawaan, `id: "auto"` agar harness Plugin terdaftar dapat mengklaim model yang didukung, ID harness terdaftar seperti `id: "codex"`, atau alias backend CLI yang didukung seperti `id: "claude-cli"`. Tetapkan `fallback: "none"` untuk menonaktifkan fallback PI otomatis. Runtime Plugin eksplisit seperti `codex` gagal tertutup secara default kecuali Anda menetapkan `fallback: "pi"` dalam cakupan override yang sama. Pertahankan referensi model kanonis sebagai `provider/model`; pilih Codex, Claude CLI, Gemini CLI, dan backend eksekusi lainnya melalui konfigurasi runtime, bukan prefiks penyedia runtime lama. Lihat [Runtime agen](/id/concepts/agent-runtimes) untuk perbedaannya dengan pemilihan penyedia/model.
- Penulis konfigurasi yang memutasi bidang-bidang ini (misalnya `/models set`, `/models set-image`, dan perintah tambah/hapus fallback) menyimpan bentuk objek kanonis dan mempertahankan daftar fallback yang ada jika memungkinkan.
- `maxConcurrent`: jumlah maksimum run agen paralel di seluruh sesi (setiap sesi tetap diserialkan). Default: 4.
- `model.primary`: format `provider/model` (mis. `openai/gpt-5.5` untuk akses kunci API atau `openai-codex/gpt-5.5` untuk Codex OAuth). Jika Anda menghilangkan provider, OpenClaw mencoba alias terlebih dahulu, lalu kecocokan provider terkonfigurasi yang unik untuk ID model persis tersebut, dan baru setelah itu fallback ke provider default yang dikonfigurasi (perilaku kompatibilitas usang, jadi utamakan `provider/model` eksplisit). Jika provider tersebut tidak lagi mengekspos model default yang dikonfigurasi, OpenClaw fallback ke provider/model terkonfigurasi pertama alih-alih menampilkan default provider yang sudah usang dan dihapus.
- `models`: katalog model dan allowlist yang dikonfigurasi untuk `/model`. Setiap entri dapat menyertakan `alias` (pintasan) dan `params` (khusus provider, misalnya `temperature`, `maxTokens`, `cacheRetention`, `context1m`, `responsesServerCompaction`, `responsesCompactThreshold`, `chat_template_kwargs`, `extra_body`/`extraBody`).
- Edit aman: gunakan `openclaw config set agents.defaults.models '<json>' --strict-json --merge` untuk menambahkan entri. `config set` menolak penggantian yang akan menghapus entri allowlist yang sudah ada kecuali Anda meneruskan `--replace`.
- Alur konfigurasi/onboarding bercakupan provider menggabungkan model provider yang dipilih ke dalam map ini dan mempertahankan provider tidak terkait yang sudah dikonfigurasi.
- Untuk model OpenAI Responses langsung, Compaction sisi server diaktifkan otomatis. Gunakan `params.responsesServerCompaction: false` untuk berhenti menyuntikkan `context_management`, atau `params.responsesCompactThreshold` untuk mengganti ambang batas. Lihat [Compaction sisi server OpenAI](/id/providers/openai#server-side-compaction-responses-api).
- `params`: parameter provider default global yang diterapkan ke semua model. Tetapkan di `agents.defaults.params` (mis. `{ cacheRetention: "long" }`).
- Presedensi penggabungan `params` (konfigurasi): `agents.defaults.params` (basis global) diganti oleh `agents.defaults.models["provider/model"].params` (per model), lalu `agents.list[].params` (ID agen yang cocok) mengganti berdasarkan kunci. Lihat [Caching Prompt](/id/reference/prompt-caching) untuk detail.
- `params.extra_body`/`params.extraBody`: JSON pass-through lanjutan yang digabungkan ke body permintaan `api: "openai-completions"` untuk proxy kompatibel OpenAI. Jika bertabrakan dengan kunci permintaan yang dihasilkan, body tambahan menang; rute completions non-native masih menghapus `store` khusus OpenAI setelahnya.
- `params.chat_template_kwargs`: argumen chat-template kompatibel vLLM/OpenAI yang digabungkan ke body permintaan tingkat atas `api: "openai-completions"`. Untuk `vllm/nemotron-3-*` dengan thinking nonaktif, Plugin vLLM yang dibundel otomatis mengirim `enable_thinking: false` dan `force_nonempty_content: true`; `chat_template_kwargs` eksplisit mengganti default yang dihasilkan, dan `extra_body.chat_template_kwargs` tetap memiliki presedensi akhir. Untuk kontrol thinking Qwen vLLM, tetapkan `params.qwenThinkingFormat` ke `"chat-template"` atau `"top-level"` pada entri model tersebut.
- `compat.supportedReasoningEfforts`: daftar upaya reasoning kompatibel OpenAI per model. Sertakan `"xhigh"` untuk endpoint kustom yang benar-benar menerimanya; OpenClaw kemudian mengekspos `/think xhigh` di menu perintah, baris sesi Gateway, validasi patch sesi, validasi CLI agen, dan validasi `llm-task` untuk provider/model terkonfigurasi tersebut. Gunakan `compat.reasoningEffortMap` ketika backend menginginkan nilai khusus provider untuk tingkat kanonis.
- `params.preserveThinking`: opt-in khusus Z.AI untuk thinking yang dipertahankan. Ketika diaktifkan dan thinking aktif, OpenClaw mengirim `thinking.clear_thinking: false` dan memutar ulang `reasoning_content` sebelumnya; lihat [thinking Z.AI dan thinking yang dipertahankan](/id/providers/zai#thinking-and-preserved-thinking).
- `agentRuntime`: kebijakan runtime agen tingkat rendah default. ID yang dihilangkan default ke OpenClaw Pi. Gunakan `id: "pi"` untuk memaksa harness PI bawaan, `id: "auto"` untuk membiarkan harness Plugin terdaftar mengklaim model yang didukung, ID harness terdaftar seperti `id: "codex"`, atau alias backend CLI yang didukung seperti `id: "claude-cli"`. Tetapkan `fallback: "none"` untuk menonaktifkan fallback PI otomatis. Runtime Plugin eksplisit seperti `codex` gagal secara tertutup secara default kecuali Anda menetapkan `fallback: "pi"` dalam scope override yang sama. Pertahankan referensi model kanonis sebagai `provider/model`; pilih Codex, Claude CLI, Gemini CLI, dan backend eksekusi lain melalui konfigurasi runtime, bukan prefiks provider runtime legacy. Lihat [Runtime agen](/id/concepts/agent-runtimes) untuk memahami perbedaannya dari pemilihan provider/model.
- Penulis konfigurasi yang memutasi field ini (misalnya `/models set`, `/models set-image`, dan perintah tambah/hapus fallback) menyimpan bentuk objek kanonis dan mempertahankan daftar fallback yang ada jika memungkinkan.
- `maxConcurrent`: jumlah maksimum run agen paralel lintas sesi (setiap sesi tetap diserialkan). Default: 4.
### `agents.defaults.agentRuntime`
`agentRuntime` mengontrol eksekutor tingkat rendah mana yang menjalankan giliran agen. Sebagian besar
deployment sebaiknya mempertahankan runtime OpenClaw Pi default. Gunakan ini ketika Plugin tepercaya
menyediakan harness native, seperti harness app-server Codex bawaan,
atau ketika Anda menginginkan backend CLI yang didukung seperti Claude CLI. Untuk model mentalnya,
lihat [Runtime agen](/id/concepts/agent-runtimes).
`agentRuntime` mengontrol executor tingkat rendah mana yang menjalankan turn agen. Sebagian besar
deployment sebaiknya tetap menggunakan runtime default OpenClaw Pi. Gunakan ini ketika Plugin
tepercaya menyediakan harness native, seperti harness app-server Codex yang dibundel,
atau ketika Anda menginginkan backend CLI yang didukung seperti Claude CLI. Untuk model
mental, lihat [Runtime agen](/id/concepts/agent-runtimes).
```json5
{
@ -412,14 +412,14 @@ lihat [Runtime agen](/id/concepts/agent-runtimes).
}
```
- `id`: `"auto"`, `"pi"`, ID harness Plugin terdaftar, atau alias backend CLI yang didukung. Plugin Codex bawaan mendaftarkan `codex`; Plugin Anthropic bawaan menyediakan backend CLI `claude-cli`.
- `fallback`: `"pi"` atau `"none"`. Dalam `id: "auto"`, fallback yang dihilangkan default ke `"pi"` agar konfigurasi lama dapat terus menggunakan PI ketika tidak ada harness Plugin yang mengklaim sebuah run. Dalam mode runtime Plugin eksplisit, seperti `id: "codex"`, fallback yang dihilangkan default ke `"none"` agar harness yang hilang gagal, bukan diam-diam menggunakan PI. Override runtime tidak mewarisi fallback dari cakupan yang lebih luas; tetapkan `fallback: "pi"` bersama runtime eksplisit ketika Anda sengaja menginginkan fallback kompatibilitas tersebut. Kegagalan harness Plugin yang dipilih selalu dimunculkan secara langsung.
- Override lingkungan: `OPENCLAW_AGENT_RUNTIME=<id|auto|pi>` menimpa `id`; `OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` menimpa fallback untuk proses tersebut.
- `id`: `"auto"`, `"pi"`, ID harness Plugin terdaftar, atau alias backend CLI yang didukung. Plugin Codex yang dibundel mendaftarkan `codex`; Plugin Anthropic yang dibundel menyediakan backend CLI `claude-cli`.
- `fallback`: `"pi"` atau `"none"`. Dalam `id: "auto"`, fallback yang dihilangkan default ke `"pi"` agar konfigurasi lama dapat tetap menggunakan PI ketika tidak ada harness Plugin yang mengklaim run. Dalam mode runtime Plugin eksplisit, seperti `id: "codex"`, fallback yang dihilangkan default ke `"none"` agar harness yang hilang gagal alih-alih diam-diam menggunakan PI. Override runtime tidak mewarisi fallback dari scope yang lebih luas; tetapkan `fallback: "pi"` bersama runtime eksplisit ketika Anda sengaja menginginkan fallback kompatibilitas tersebut. Kegagalan harness Plugin yang dipilih selalu ditampilkan langsung.
- Override lingkungan: `OPENCLAW_AGENT_RUNTIME=<id|auto|pi>` mengganti `id`; `OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` mengganti fallback untuk proses tersebut.
- Untuk deployment khusus Codex, tetapkan `model: "openai/gpt-5.5"` dan `agentRuntime.id: "codex"`. Anda juga dapat menetapkan `agentRuntime.fallback: "none"` secara eksplisit agar lebih mudah dibaca; itu adalah default untuk runtime Plugin eksplisit.
- Untuk deployment Claude CLI, utamakan `model: "anthropic/claude-opus-4-7"` plus `agentRuntime.id: "claude-cli"`. Referensi model lama `claude-cli/claude-opus-4-7` masih berfungsi untuk kompatibilitas, tetapi konfigurasi baru sebaiknya mempertahankan pemilihan penyedia/model secara kanonis dan meletakkan backend eksekusi di `agentRuntime.id`.
- Kunci kebijakan runtime lama ditulis ulang ke `agentRuntime` oleh `openclaw doctor --fix`.
- Pilihan harness dipasangkan per ID sesi setelah run embedded pertama. Perubahan konfigurasi/env memengaruhi sesi baru atau yang direset, bukan transkrip yang sudah ada. Sesi lama dengan riwayat transkrip tetapi tanpa pin terekam diperlakukan sebagai ter-pin ke PI. `/status` melaporkan runtime efektif, misalnya `Runtime: OpenClaw Pi Default` atau `Runtime: OpenAI Codex`.
- Ini hanya mengontrol eksekusi giliran agen teks. Pembuatan media, vision, PDF, musik, video, dan TTS tetap menggunakan pengaturan penyedia/model masing-masing.
- Untuk deployment Claude CLI, utamakan `model: "anthropic/claude-opus-4-7"` plus `agentRuntime.id: "claude-cli"`. Referensi model legacy `claude-cli/claude-opus-4-7` masih berfungsi untuk kompatibilitas, tetapi konfigurasi baru sebaiknya menjaga pemilihan provider/model tetap kanonis dan menempatkan backend eksekusi di `agentRuntime.id`.
- Kunci kebijakan runtime lama ditulis ulang menjadi `agentRuntime` oleh `openclaw doctor --fix`.
- Pilihan harness dipin per ID sesi setelah run tertanam pertama. Perubahan konfigurasi/env memengaruhi sesi baru atau yang direset, bukan transcript yang sudah ada. Sesi legacy dengan riwayat transcript tetapi tanpa pin yang tercatat diperlakukan sebagai dipin ke PI. `/status` melaporkan runtime efektif, misalnya `Runtime: OpenClaw Pi Default` atau `Runtime: OpenAI Codex`.
- Ini hanya mengontrol eksekusi turn agen teks. Pembuatan media, vision, PDF, musik, video, dan TTS tetap menggunakan pengaturan provider/model masing-masing.
**Singkatan alias bawaan** (hanya berlaku ketika model ada di `agents.defaults.models`):
@ -427,22 +427,22 @@ lihat [Runtime agen](/id/concepts/agent-runtimes).
| ------------------- | ------------------------------------------ |
| `opus` | `anthropic/claude-opus-4-6` |
| `sonnet` | `anthropic/claude-sonnet-4-6` |
| `gpt` | `openai/gpt-5.5` or `openai-codex/gpt-5.5` |
| `gpt` | `openai/gpt-5.5` atau `openai-codex/gpt-5.5` |
| `gpt-mini` | `openai/gpt-5.4-mini` |
| `gpt-nano` | `openai/gpt-5.4-nano` |
| `gemini` | `google/gemini-3.1-pro-preview` |
| `gemini-flash` | `google/gemini-3-flash-preview` |
| `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` |
Alias yang Anda konfigurasi selalu mengalahkan bawaan.
Alias yang Anda konfigurasi selalu mengungguli default.
Model Z.AI GLM-4.x otomatis mengaktifkan mode berpikir kecuali Anda menetapkan `--thinking off` atau mendefinisikan `agents.defaults.models["zai/<model>"].params.thinking` sendiri.
Model Z.AI mengaktifkan `tool_stream` secara bawaan untuk streaming panggilan alat. Tetapkan `agents.defaults.models["zai/<model>"].params.tool_stream` ke `false` untuk menonaktifkannya.
Model Anthropic Claude 4.6 secara bawaan menggunakan berpikir `adaptive` ketika tidak ada tingkat berpikir eksplisit yang ditetapkan.
Model Z.AI GLM-4.x otomatis mengaktifkan mode berpikir kecuali Anda menetapkan `--thinking off` atau mendefinisikan sendiri `agents.defaults.models["zai/<model>"].params.thinking`.
Model Z.AI mengaktifkan `tool_stream` secara default untuk streaming panggilan alat. Tetapkan `agents.defaults.models["zai/<model>"].params.tool_stream` ke `false` untuk menonaktifkannya.
Model Anthropic Claude 4.6 menggunakan berpikir `adaptive` secara default ketika tidak ada tingkat berpikir eksplisit yang ditetapkan.
### `agents.defaults.cliBackends`
Backend CLI opsional untuk eksekusi fallback hanya teks (tanpa panggilan alat). Berguna sebagai cadangan ketika penyedia API gagal.
Backend CLI opsional untuk eksekusi fallback khusus teks (tanpa panggilan alat). Berguna sebagai cadangan ketika penyedia API gagal.
```json5
{
@ -471,13 +471,13 @@ Backend CLI opsional untuk eksekusi fallback hanya teks (tanpa panggilan alat).
}
```
- Backend CLI mengutamakan teks; alat selalu dinonaktifkan.
- Backend CLI berorientasi teks terlebih dahulu; alat selalu dinonaktifkan.
- Sesi didukung ketika `sessionArg` ditetapkan.
- Penerusan gambar didukung ketika `imageArg` menerima jalur file.
### `agents.defaults.systemPromptOverride`
Ganti seluruh prompt sistem yang dirakit OpenClaw dengan string tetap. Tetapkan di tingkat default (`agents.defaults.systemPromptOverride`) atau per agen (`agents.list[].systemPromptOverride`). Nilai per agen didahulukan; nilai kosong atau hanya spasi diabaikan. Berguna untuk eksperimen prompt terkontrol.
Ganti seluruh prompt sistem yang dirakit OpenClaw dengan string tetap. Tetapkan di tingkat default (`agents.defaults.systemPromptOverride`) atau per agen (`agents.list[].systemPromptOverride`). Nilai per agen lebih diutamakan; nilai kosong atau hanya spasi diabaikan. Berguna untuk eksperimen prompt yang terkontrol.
```json5
{
@ -491,7 +491,7 @@ Ganti seluruh prompt sistem yang dirakit OpenClaw dengan string tetap. Tetapkan
### `agents.defaults.promptOverlays`
Overlay prompt yang tidak bergantung pada penyedia, diterapkan berdasarkan keluarga model. ID model keluarga GPT-5 menerima kontrak perilaku bersama di seluruh penyedia; `personality` hanya mengontrol lapisan gaya interaksi yang ramah.
Overlay prompt yang tidak bergantung pada penyedia, diterapkan berdasarkan keluarga model. ID model keluarga GPT-5 menerima kontrak perilaku bersama di seluruh penyedia; `personality` hanya mengontrol lapisan gaya interaksi ramah.
```json5
{
@ -507,9 +507,9 @@ Overlay prompt yang tidak bergantung pada penyedia, diterapkan berdasarkan kelua
}
```
- `"friendly"` (bawaan) dan `"on"` mengaktifkan lapisan gaya interaksi yang ramah.
- `"off"` hanya menonaktifkan lapisan ramah; kontrak perilaku GPT-5 yang diberi tag tetap aktif.
- `plugins.entries.openai.config.personality` lama masih dibaca ketika pengaturan bersama ini belum ditetapkan.
- `"friendly"` (default) dan `"on"` mengaktifkan lapisan gaya interaksi ramah.
- `"off"` hanya menonaktifkan lapisan ramah; kontrak perilaku GPT-5 bertanda tetap diaktifkan.
- `plugins.entries.openai.config.personality` lama tetap dibaca ketika pengaturan bersama ini belum ditetapkan.
### `agents.defaults.heartbeat`
@ -541,15 +541,15 @@ Eksekusi Heartbeat berkala.
}
```
- `every`: string durasi (ms/s/m/h). Bawaan: `30m` (autentikasi kunci API) atau `1h` (autentikasi OAuth). Tetapkan ke `0m` untuk menonaktifkan.
- `includeSystemPromptSection`: ketika false, menghilangkan bagian Heartbeat dari prompt sistem dan melewati injeksi `HEARTBEAT.md` ke dalam konteks bootstrap. Bawaan: `true`.
- `suppressToolErrorWarnings`: ketika true, menekan payload peringatan kesalahan alat selama eksekusi Heartbeat.
- `timeoutSeconds`: waktu maksimum dalam detik yang diizinkan untuk satu giliran agen Heartbeat sebelum dibatalkan. Biarkan tidak ditetapkan untuk menggunakan `agents.defaults.timeoutSeconds`.
- `directPolicy`: kebijakan pengiriman langsung/DM. `allow` (bawaan) mengizinkan pengiriman ke target langsung. `block` menekan pengiriman ke target langsung dan memancarkan `reason=dm-blocked`.
- `lightContext`: ketika true, eksekusi Heartbeat menggunakan konteks bootstrap ringan dan hanya mempertahankan `HEARTBEAT.md` dari file bootstrap ruang kerja.
- `isolatedSession`: ketika true, setiap Heartbeat berjalan dalam sesi baru tanpa riwayat percakapan sebelumnya. Pola isolasi yang sama dengan cron `sessionTarget: "isolated"`. Mengurangi biaya token per Heartbeat dari ~100K menjadi ~2-5K token.
- `skipWhenBusy`: ketika true, eksekusi Heartbeat ditunda pada jalur sibuk tambahan: pekerjaan subagen atau perintah bertingkat. Jalur Cron selalu menunda Heartbeat, bahkan tanpa flag ini.
- Per agen: tetapkan `agents.list[].heartbeat`. Ketika agen mana pun mendefinisikan `heartbeat`, **hanya agen tersebut** yang menjalankan Heartbeat.
- `every`: string durasi (ms/s/m/h). Default: `30m` (autentikasi kunci API) atau `1h` (autentikasi OAuth). Tetapkan ke `0m` untuk menonaktifkan.
- `includeSystemPromptSection`: ketika false, menghilangkan bagian Heartbeat dari prompt sistem dan melewati injeksi `HEARTBEAT.md` ke dalam konteks bootstrap. Default: `true`.
- `suppressToolErrorWarnings`: ketika true, menekan payload peringatan galat alat selama eksekusi heartbeat.
- `timeoutSeconds`: waktu maksimum dalam detik yang diizinkan untuk giliran agen heartbeat sebelum dibatalkan. Biarkan tidak ditetapkan untuk menggunakan `agents.defaults.timeoutSeconds`.
- `directPolicy`: kebijakan pengiriman langsung/DM. `allow` (default) mengizinkan pengiriman target langsung. `block` menekan pengiriman target langsung dan mengeluarkan `reason=dm-blocked`.
- `lightContext`: ketika true, eksekusi heartbeat menggunakan konteks bootstrap ringan dan hanya mempertahankan `HEARTBEAT.md` dari file bootstrap ruang kerja.
- `isolatedSession`: ketika true, setiap heartbeat berjalan dalam sesi baru tanpa riwayat percakapan sebelumnya. Pola isolasi yang sama seperti cron `sessionTarget: "isolated"`. Mengurangi biaya token per heartbeat dari ~100K menjadi ~2-5K token.
- `skipWhenBusy`: ketika true, eksekusi heartbeat ditunda pada jalur sibuk tambahan: pekerjaan subagen atau perintah bersarang. Jalur Cron selalu menunda heartbeat, bahkan tanpa flag ini.
- Per agen: tetapkan `agents.list[].heartbeat`. Ketika agen mana pun mendefinisikan `heartbeat`, **hanya agen tersebut** yang menjalankan heartbeat.
- Heartbeat menjalankan giliran agen penuh — interval yang lebih pendek menghabiskan lebih banyak token.
### `agents.defaults.compaction`
@ -567,6 +567,7 @@ Eksekusi Heartbeat berkala.
identifierPolicy: "strict", // strict | off | custom
identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom
qualityGuard: { enabled: true, maxRetries: 1 },
midTurnPrecheck: { enabled: false }, // optional Pi tool-loop pressure check
postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection
model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override
truncateAfterCompaction: true, // rotate to a smaller successor JSONL after compaction
@ -585,22 +586,23 @@ Eksekusi Heartbeat berkala.
}
```
- `mode`: `default` atau `safeguard` (perangkuman berbongkah untuk riwayat panjang). Lihat [Compaction](/id/concepts/compaction).
- `provider`: id Plugin penyedia Compaction terdaftar. Ketika ditetapkan, `summarize()` milik penyedia dipanggil alih-alih perangkuman LLM bawaan. Kembali ke bawaan jika gagal. Menetapkan penyedia memaksa `mode: "safeguard"`. Lihat [Compaction](/id/concepts/compaction).
- `timeoutSeconds`: detik maksimum yang diizinkan untuk satu operasi Compaction sebelum OpenClaw membatalkannya. Bawaan: `900`.
- `keepRecentTokens`: anggaran titik potong Pi untuk mempertahankan ekor transkrip terbaru apa adanya. `/compact` manual menghormati ini ketika ditetapkan secara eksplisit; jika tidak, Compaction manual adalah checkpoint keras.
- `identifierPolicy`: `strict` (bawaan), `off`, atau `custom`. `strict` menambahkan panduan retensi pengenal buram bawaan di awal selama perangkuman Compaction.
- `identifierInstructions`: teks kustom opsional untuk mempertahankan pengenal, digunakan ketika `identifierPolicy=custom`.
- `qualityGuard`: pemeriksaan coba ulang pada keluaran yang salah bentuk untuk ringkasan safeguard. Diaktifkan secara bawaan dalam mode safeguard; tetapkan `enabled: false` untuk melewati audit.
- `postCompactionSections`: nama bagian H2/H3 AGENTS.md opsional untuk diinjeksi ulang setelah Compaction. Bawaan ke `["Session Startup", "Red Lines"]`; tetapkan `[]` untuk menonaktifkan injeksi ulang. Ketika tidak ditetapkan atau secara eksplisit ditetapkan ke pasangan bawaan tersebut, heading lama `Every Session`/`Safety` juga diterima sebagai fallback warisan.
- `model`: penggantian `provider/model-id` opsional hanya untuk perangkuman Compaction. Gunakan ini ketika sesi utama harus mempertahankan satu model tetapi ringkasan Compaction harus berjalan pada model lain; ketika tidak ditetapkan, Compaction menggunakan model utama sesi.
- `maxActiveTranscriptBytes`: ambang byte opsional (`number` atau string seperti `"20mb"`) yang memicu Compaction lokal normal sebelum eksekusi ketika JSONL aktif melampaui ambang. Memerlukan `truncateAfterCompaction` agar Compaction yang berhasil dapat merotasi ke transkrip penerus yang lebih kecil. Dinonaktifkan ketika tidak ditetapkan atau `0`.
- `notifyUser`: ketika `true`, mengirim pemberitahuan singkat kepada pengguna ketika Compaction dimulai dan ketika selesai (misalnya, "Memadatkan konteks..." dan "Compaction selesai"). Dinonaktifkan secara bawaan agar Compaction tetap senyap.
- `memoryFlush`: giliran agen senyap sebelum Compaction otomatis untuk menyimpan memori tahan lama. Tetapkan `model` ke penyedia/model yang persis seperti `ollama/qwen3:8b` ketika giliran housekeeping ini harus tetap pada model lokal; penggantian tidak mewarisi rantai fallback sesi aktif. Dilewati ketika ruang kerja bersifat hanya baca.
- `mode`: `default` atau `safeguard` (perangkuman berpotongan untuk riwayat panjang). Lihat [Compaction](/id/concepts/compaction).
- `provider`: id Plugin penyedia compaction terdaftar. Ketika ditetapkan, `summarize()` milik penyedia dipanggil alih-alih perangkuman LLM bawaan. Kembali ke bawaan saat gagal. Menetapkan penyedia memaksa `mode: "safeguard"`. Lihat [Compaction](/id/concepts/compaction).
- `timeoutSeconds`: detik maksimum yang diizinkan untuk satu operasi compaction sebelum OpenClaw membatalkannya. Default: `900`.
- `keepRecentTokens`: anggaran titik potong Pi untuk mempertahankan ekor transkrip terbaru secara verbatim. `/compact` manual menghormati ini ketika ditetapkan secara eksplisit; jika tidak, compaction manual adalah checkpoint keras.
- `identifierPolicy`: `strict` (default), `off`, atau `custom`. `strict` menambahkan panduan bawaan untuk mempertahankan identifier buram di awal selama perangkuman compaction.
- `identifierInstructions`: teks kustom opsional untuk mempertahankan identifier yang digunakan ketika `identifierPolicy=custom`.
- `qualityGuard`: pemeriksaan coba ulang pada keluaran cacat untuk ringkasan safeguard. Diaktifkan secara default dalam mode safeguard; tetapkan `enabled: false` untuk melewati audit.
- `midTurnPrecheck`: pemeriksaan tekanan tool-loop Pi opsional. Ketika `enabled: true`, OpenClaw memeriksa tekanan konteks setelah hasil alat ditambahkan dan sebelum panggilan model berikutnya. Jika konteks tidak lagi muat, OpenClaw membatalkan upaya saat ini sebelum mengirimkan prompt dan menggunakan kembali jalur pemulihan precheck yang ada untuk memangkas hasil alat atau melakukan compaction lalu mencoba lagi. Berfungsi dengan mode compaction `default` dan `safeguard`. Default: dinonaktifkan.
- `postCompactionSections`: nama bagian H2/H3 AGENTS.md opsional untuk diinjeksi ulang setelah compaction. Default ke `["Session Startup", "Red Lines"]`; tetapkan `[]` untuk menonaktifkan injeksi ulang. Ketika tidak ditetapkan atau ditetapkan secara eksplisit ke pasangan default tersebut, heading lama `Every Session`/`Safety` juga diterima sebagai fallback warisan.
- `model`: override `provider/model-id` opsional khusus untuk perangkuman compaction. Gunakan ini ketika sesi utama harus tetap memakai satu model tetapi ringkasan compaction harus berjalan pada model lain; ketika tidak ditetapkan, compaction menggunakan model utama sesi.
- `maxActiveTranscriptBytes`: ambang byte opsional (`number` atau string seperti `"20mb"`) yang memicu compaction lokal normal sebelum eksekusi ketika JSONL aktif tumbuh melewati ambang. Memerlukan `truncateAfterCompaction` agar compaction yang berhasil dapat berotasi ke transkrip penerus yang lebih kecil. Dinonaktifkan ketika tidak ditetapkan atau `0`.
- `notifyUser`: ketika `true`, mengirim pemberitahuan singkat kepada pengguna ketika compaction dimulai dan ketika selesai (misalnya, "Compacting context..." dan "Compaction complete"). Dinonaktifkan secara default agar compaction tetap senyap.
- `memoryFlush`: giliran agentic senyap sebelum compaction otomatis untuk menyimpan memori tahan lama. Tetapkan `model` ke penyedia/model yang tepat seperti `ollama/qwen3:8b` ketika giliran housekeeping ini harus tetap pada model lokal; override tidak mewarisi rantai fallback sesi aktif. Dilewati ketika ruang kerja hanya-baca.
### `agents.defaults.contextPruning`
Memangkas **hasil alat lama** dari konteks dalam memori sebelum dikirim ke LLM. Ini **tidak** mengubah riwayat sesi di disk.
Memangkas **hasil alat lama** dari konteks dalam memori sebelum dikirim ke LLM. **Tidak** mengubah riwayat sesi di disk.
```json5
{
@ -622,21 +624,21 @@ Memangkas **hasil alat lama** dari konteks dalam memori sebelum dikirim ke LLM.
}
```
<Accordion title="perilaku mode cache-ttl">
<Accordion title="cache-ttl mode behavior">
- `mode: "cache-ttl"` mengaktifkan lintasan pemangkasan.
- `ttl` mengontrol seberapa sering pemangkasan dapat berjalan lagi (setelah sentuhan cache terakhir).
- Pemangkasan pertama-tama memangkas lunak hasil alat yang terlalu besar, lalu menghapus keras hasil alat yang lebih lama jika diperlukan.
- Pemangkasan melakukan soft-trim pada hasil alat yang terlalu besar terlebih dahulu, lalu hard-clear pada hasil alat yang lebih lama jika diperlukan.
**Pemangkasan lunak** mempertahankan awal + akhir dan menyisipkan `...` di tengah.
**Soft-trim** mempertahankan awal + akhir dan menyisipkan `...` di tengah.
**Penghapusan keras** mengganti seluruh hasil alat dengan placeholder.
**Hard-clear** mengganti seluruh hasil alat dengan placeholder.
Catatan:
- Blok gambar tidak pernah dipangkas/dihapus.
- Blok gambar tidak pernah dipangkas/dibersihkan.
- Rasio berbasis karakter (perkiraan), bukan jumlah token persis.
- Jika terdapat kurang dari `keepLastAssistants` pesan asisten, pemangkasan dilewati.
- Jika pesan asisten lebih sedikit daripada `keepLastAssistants`, pemangkasan dilewati.
</Accordion>
@ -658,13 +660,13 @@ Lihat [Pemangkasan Sesi](/id/concepts/session-pruning) untuk detail perilaku.
}
```
- Kanal non-Telegram memerlukan `*.blockStreaming: true` eksplisit untuk mengaktifkan balasan blok.
- Penggantian kanal: `channels.<channel>.blockStreamingCoalesce` (dan varian per akun). Signal/Slack/Discord/Google Chat secara bawaan menggunakan `minChars: 1500`.
- Saluran non-Telegram memerlukan `*.blockStreaming: true` eksplisit untuk mengaktifkan balasan blok.
- Penggantian saluran: `channels.<channel>.blockStreamingCoalesce` (dan varian per akun). Signal/Slack/Discord/Google Chat default `minChars: 1500`.
- `humanDelay`: jeda acak di antara balasan blok. `natural` = 800–2500ms. Penggantian per agen: `agents.list[].humanDelay`.
Lihat [Streaming](/id/concepts/streaming) untuk detail perilaku + pembongkahan.
Lihat [Streaming](/id/concepts/streaming) untuk detail perilaku + pemotongan.
### Indikator pengetikan
### Indikator mengetik
```json5
{
@ -678,9 +680,9 @@ Lihat [Streaming](/id/concepts/streaming) untuk detail perilaku + pembongkahan.
```
- Default: `instant` untuk chat langsung/mention, `message` untuk chat grup tanpa mention.
- Override per sesi: `session.typingMode`, `session.typingIntervalSeconds`.
- Penggantian per sesi: `session.typingMode`, `session.typingIntervalSeconds`.
Lihat [Indikator Pengetikan](/id/concepts/typing-indicators).
Lihat [Indikator Mengetik](/id/concepts/typing-indicators).
<a id="agentsdefaultssandbox"></a>
@ -797,21 +799,21 @@ Saat `backend: "openshell"` dipilih, pengaturan khusus runtime berpindah ke
- `target`: target SSH dalam bentuk `user@host[:port]`
- `command`: perintah klien SSH (default: `ssh`)
- `workspaceRoot`: root jarak jauh absolut yang digunakan untuk workspace per cakupan
- `identityFile` / `certificateFile` / `knownHostsFile`: file lokal yang ada yang diteruskan ke OpenSSH
- `identityFile` / `certificateFile` / `knownHostsFile`: file lokal yang sudah ada yang diteruskan ke OpenSSH
- `identityData` / `certificateData` / `knownHostsData`: konten inline atau SecretRefs yang diwujudkan OpenClaw menjadi file sementara saat runtime
- `strictHostKeyChecking` / `updateHostKeys`: pengaturan kebijakan host-key OpenSSH
- `strictHostKeyChecking` / `updateHostKeys`: kontrol kebijakan host-key OpenSSH
**Presedensi autentikasi SSH:**
- `identityData` mengungguli `identityFile`
- `certificateData` mengungguli `certificateFile`
- `knownHostsData` mengungguli `knownHostsFile`
- `identityData` mengalahkan `identityFile`
- `certificateData` mengalahkan `certificateFile`
- `knownHostsData` mengalahkan `knownHostsFile`
- Nilai `*Data` berbasis SecretRef diselesaikan dari snapshot runtime rahasia aktif sebelum sesi sandbox dimulai
**Perilaku backend SSH:**
- menyiapkan workspace jarak jauh satu kali setelah dibuat atau dibuat ulang
- lalu menjaga workspace SSH jarak jauh sebagai kanonis
- melakukan seed workspace jarak jauh satu kali setelah dibuat atau dibuat ulang
- lalu menjaga workspace SSH jarak jauh tetap kanonis
- merutekan `exec`, alat file, dan jalur media melalui SSH
- tidak menyinkronkan perubahan jarak jauh kembali ke host secara otomatis
- tidak mendukung kontainer browser sandbox
@ -819,8 +821,8 @@ Saat `backend: "openshell"` dipilih, pengaturan khusus runtime berpindah ke
**Akses workspace:**
- `none`: workspace sandbox per cakupan di bawah `~/.openclaw/sandboxes`
- `ro`: workspace sandbox di `/workspace`, workspace agen di-mount baca-saja di `/agent`
- `rw`: workspace agen di-mount baca/tulis di `/workspace`
- `ro`: workspace sandbox di `/workspace`, workspace agen dipasang hanya-baca di `/agent`
- `rw`: workspace agen dipasang baca/tulis di `/workspace`
**Cakupan:**
@ -856,30 +858,30 @@ Saat `backend: "openshell"` dipilih, pengaturan khusus runtime berpindah ke
**Mode OpenShell:**
- `mirror`: siapkan jarak jauh dari lokal sebelum exec, sinkronkan kembali setelah exec; workspace lokal tetap kanonis
- `remote`: siapkan jarak jauh satu kali saat sandbox dibuat, lalu jaga workspace jarak jauh sebagai kanonis
- `mirror`: seed jarak jauh dari lokal sebelum exec, sinkronkan kembali setelah exec; workspace lokal tetap kanonis
- `remote`: seed jarak jauh satu kali saat sandbox dibuat, lalu jaga workspace jarak jauh tetap kanonis
Dalam mode `remote`, edit lokal host yang dibuat di luar OpenClaw tidak disinkronkan ke sandbox secara otomatis setelah langkah penyiapan.
Dalam mode `remote`, edit host-lokal yang dibuat di luar OpenClaw tidak disinkronkan ke sandbox secara otomatis setelah langkah seed.
Transport adalah SSH ke sandbox OpenShell, tetapi Plugin memiliki siklus hidup sandbox dan sinkronisasi mirror opsional.
**`setupCommand`** berjalan satu kali setelah pembuatan kontainer (melalui `sh -lc`). Membutuhkan egress jaringan, root yang dapat ditulis, pengguna root.
**`setupCommand`** berjalan satu kali setelah pembuatan kontainer (melalui `sh -lc`). Memerlukan egress jaringan, root yang dapat ditulis, pengguna root.
**Kontainer menggunakan default `network: "none"`** — atur ke `"bridge"` (atau jaringan bridge kustom) jika agen membutuhkan akses keluar.
`"host"` diblokir. `"container:<id>"` diblokir secara default kecuali Anda secara eksplisit mengatur
**Kontainer default ke `network: "none"`** — atur ke `"bridge"` (atau jaringan bridge kustom) jika agen memerlukan akses keluar.
`"host"` diblokir. `"container:<id>"` diblokir secara default kecuali Anda secara eksplisit menetapkan
`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (break-glass).
**Lampiran masuk** ditempatkan ke `media/inbound/*` di workspace aktif.
**Lampiran masuk** di-stage ke `media/inbound/*` di workspace aktif.
**`docker.binds`** me-mount direktori host tambahan; bind global dan per agen digabungkan.
**`docker.binds`** memasang direktori host tambahan; bind global dan per agen digabungkan.
**Browser sandbox** (`sandbox.browser.enabled`): Chromium + CDP dalam kontainer. URL noVNC disuntikkan ke prompt sistem. Tidak memerlukan `browser.enabled` di `openclaw.json`.
Akses pengamat noVNC menggunakan autentikasi VNC secara default dan OpenClaw memancarkan URL token berumur pendek (alih-alih mengekspos kata sandi di URL bersama).
Akses pengamat noVNC menggunakan autentikasi VNC secara default dan OpenClaw memancarkan URL token berumur pendek (alih-alih mengekspos kata sandi dalam URL bersama).
- `allowHostControl: false` (default) memblokir sesi sandbox agar tidak menargetkan browser host.
- `network` default ke `openclaw-sandbox-browser` (jaringan bridge khusus). Atur ke `bridge` hanya saat Anda secara eksplisit menginginkan konektivitas bridge global.
- `cdpSourceRange` secara opsional membatasi ingress CDP di tepi kontainer ke rentang CIDR (misalnya `172.21.0.1/32`).
- `sandbox.browser.binds` me-mount direktori host tambahan hanya ke dalam kontainer browser sandbox. Saat diatur (termasuk `[]`), nilai ini menggantikan `docker.binds` untuk kontainer browser.
- Default peluncuran didefinisikan di `scripts/sandbox-browser-entrypoint.sh` dan disetel untuk host kontainer:
- `sandbox.browser.binds` memasang direktori host tambahan ke kontainer browser sandbox saja. Saat ditetapkan (termasuk `[]`), ini menggantikan `docker.binds` untuk kontainer browser.
- Default peluncuran didefinisikan dalam `scripts/sandbox-browser-entrypoint.sh` dan disetel untuk host kontainer:
- `--remote-debugging-address=127.0.0.1`
- `--remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>`
- `--user-data-dir=${HOME}/.chrome`
@ -896,15 +898,15 @@ Akses pengamat noVNC menggunakan autentikasi VNC secara default dan OpenClaw mem
- `--renderer-process-limit=2`
- `--no-zygote`
- `--metrics-recording-only`
- `--disable-extensions` (aktif secara default)
- `--disable-extensions` (default diaktifkan)
- `--disable-3d-apis`, `--disable-software-rasterizer`, dan `--disable-gpu`
diaktifkan secara default dan dapat dinonaktifkan dengan
`OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` jika penggunaan WebGL/3D membutuhkannya.
- `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` mengaktifkan kembali ekstensi jika workflow Anda
`OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` jika penggunaan WebGL/3D memerlukannya.
- `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` mengaktifkan kembali ekstensi jika alur kerja Anda
bergantung padanya.
- `--renderer-process-limit=2` dapat diubah dengan
`OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>`; atur `0` untuk menggunakan batas proses
default Chromium.
`OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>`; atur `0` untuk menggunakan
batas proses default Chromium.
- ditambah `--no-sandbox` saat `noSandbox` diaktifkan.
- Default adalah baseline image kontainer; gunakan image browser kustom dengan
entrypoint kustom untuk mengubah default kontainer.
@ -920,14 +922,14 @@ scripts/sandbox-setup.sh # main sandbox image
scripts/sandbox-browser-setup.sh # optional browser image
```
### `agents.list` (override per agen)
### `agents.list` (penggantian per agen)
Gunakan `agents.list[].tts` untuk memberi agen penyedia TTS, suara, model,
gaya, atau mode TTS otomatisnya sendiri. Blok agen digabungkan secara mendalam di atas
`messages.tts` global, sehingga kredensial bersama dapat tetap di satu tempat sementara masing-masing
agen hanya meng-override bidang suara atau penyedia yang mereka butuhkan. Override agen aktif
gaya, atau mode TTS otomatisnya sendiri. Blok agen melakukan deep-merge atas
`messages.tts` global, sehingga kredensial bersama dapat tetap berada di satu tempat sementara agen individual
hanya mengganti bidang suara atau penyedia yang mereka perlukan. Penggantian agen aktif
berlaku untuk balasan lisan otomatis, `/tts audio`, `/tts status`, dan
alat agen `tts`. Lihat [Teks ke suara](/id/tools/tts#per-agent-voice-overrides)
alat agen `tts`. Lihat [Teks-ke-ucapan](/id/tools/tts#per-agent-voice-overrides)
untuk contoh penyedia dan presedensi.
```json5
@ -983,21 +985,21 @@ untuk contoh penyedia dan presedensi.
```
- `id`: id agen stabil (wajib).
- `default`: ketika beberapa disetel, yang pertama menang (peringatan dicatat). Jika tidak ada yang disetel, entri daftar pertama menjadi default.
- `model`: bentuk string menetapkan model primer per agen yang ketat tanpa fallback model; bentuk objek `{ primary }` juga ketat kecuali Anda menambahkan `fallbacks`. Gunakan `{ primary, fallbacks: [...] }` untuk mengikutsertakan agen tersebut ke fallback, atau `{ primary, fallbacks: [] }` untuk membuat perilaku ketat menjadi eksplisit. Pekerjaan Cron yang hanya menimpa `primary` tetap mewarisi fallback default kecuali Anda menetapkan `fallbacks: []`.
- `params`: parameter stream per agen yang digabungkan di atas entri model yang dipilih di `agents.defaults.models`. Gunakan ini untuk penggantian khusus agen seperti `cacheRetention`, `temperature`, atau `maxTokens` tanpa menggandakan seluruh katalog model.
- `tts`: penggantian text-to-speech opsional per agen. Blok ini digabungkan secara mendalam di atas `messages.tts`, jadi simpan kredensial penyedia bersama dan kebijakan fallback di `messages.tts`, lalu tetapkan hanya nilai khusus persona seperti penyedia, suara, model, gaya, atau mode otomatis di sini.
- `skills`: allowlist Skills opsional per agen. Jika dihilangkan, agen mewarisi `agents.defaults.skills` saat disetel; daftar eksplisit menggantikan default alih-alih menggabungkan, dan `[]` berarti tanpa Skills.
- `thinkingDefault`: level berpikir default opsional per agen (`off | minimal | low | medium | high | xhigh | adaptive | max`). Menimpa `agents.defaults.thinkingDefault` untuk agen ini ketika tidak ada penggantian per pesan atau sesi yang disetel. Profil penyedia/model yang dipilih mengontrol nilai mana yang valid; untuk Google Gemini, `adaptive` mempertahankan pemikiran dinamis milik penyedia (`thinkingLevel` dihilangkan pada Gemini 3/3.1, `thinkingBudget: -1` pada Gemini 2.5).
- `reasoningDefault`: visibilitas penalaran default opsional per agen (`on | off | stream`). Menimpa `agents.defaults.reasoningDefault` untuk agen ini ketika tidak ada penggantian penalaran per pesan atau sesi yang disetel.
- `fastModeDefault`: default opsional per agen untuk mode cepat (`true | false`). Berlaku ketika tidak ada penggantian mode cepat per pesan atau sesi yang disetel.
- `agentRuntime`: penggantian kebijakan runtime tingkat rendah opsional per agen. Gunakan `{ id: "codex" }` untuk membuat satu agen hanya Codex sementara agen lain mempertahankan fallback PI default dalam mode `auto`.
- `runtime`: deskriptor runtime opsional per agen. Gunakan `type: "acp"` dengan default `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) ketika agen harus secara default memakai sesi harness ACP.
- `default`: saat beberapa disetel, yang pertama menang (peringatan dicatat). Jika tidak ada yang disetel, entri daftar pertama menjadi default.
- `model`: bentuk string menetapkan primary per agen yang ketat tanpa fallback model; bentuk objek `{ primary }` juga ketat kecuali Anda menambahkan `fallbacks`. Gunakan `{ primary, fallbacks: [...] }` untuk mengikutkan agen tersebut ke fallback, atau `{ primary, fallbacks: [] }` untuk membuat perilaku ketat menjadi eksplisit. Tugas Cron yang hanya mengganti `primary` tetap mewarisi fallback default kecuali Anda menyetel `fallbacks: []`.
- `params`: parameter stream per agen yang digabungkan di atas entri model yang dipilih di `agents.defaults.models`. Gunakan ini untuk override khusus agen seperti `cacheRetention`, `temperature`, atau `maxTokens` tanpa menduplikasi seluruh katalog model.
- `tts`: override text-to-speech per agen opsional. Blok ini melakukan deep-merge di atas `messages.tts`, jadi simpan kredensial penyedia bersama dan kebijakan fallback di `messages.tts` dan setel hanya nilai khusus persona seperti penyedia, suara, model, gaya, atau mode otomatis di sini.
- `skills`: allowlist skill per agen opsional. Jika dihilangkan, agen mewarisi `agents.defaults.skills` saat disetel; daftar eksplisit menggantikan default alih-alih menggabungkannya, dan `[]` berarti tanpa skill.
- `thinkingDefault`: level berpikir default per agen opsional (`off | minimal | low | medium | high | xhigh | adaptive | max`). Mengganti `agents.defaults.thinkingDefault` untuk agen ini saat tidak ada override per pesan atau sesi yang disetel. Profil penyedia/model yang dipilih mengontrol nilai mana yang valid; untuk Google Gemini, `adaptive` mempertahankan pemikiran dinamis milik penyedia (`thinkingLevel` dihilangkan pada Gemini 3/3.1, `thinkingBudget: -1` pada Gemini 2.5).
- `reasoningDefault`: visibilitas penalaran default per agen opsional (`on | off | stream`). Mengganti `agents.defaults.reasoningDefault` untuk agen ini saat tidak ada override penalaran per pesan atau sesi yang disetel.
- `fastModeDefault`: default per agen opsional untuk mode cepat (`true | false`). Berlaku saat tidak ada override mode cepat per pesan atau sesi yang disetel.
- `agentRuntime`: override kebijakan runtime level rendah per agen opsional. Gunakan `{ id: "codex" }` untuk membuat satu agen khusus Codex sementara agen lain tetap menggunakan fallback PI default dalam mode `auto`.
- `runtime`: deskriptor runtime per agen opsional. Gunakan `type: "acp"` dengan default `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) saat agen harus secara default menggunakan sesi harness ACP.
- `identity.avatar`: path relatif workspace, URL `http(s)`, atau URI `data:`.
- `identity` menurunkan default: `ackReaction` dari `emoji`, `mentionPatterns` dari `name`/`emoji`.
- `subagents.allowAgents`: allowlist id agen untuk target `sessions_spawn.agentId` eksplisit (`["*"]` = apa pun; default: hanya agen yang sama). Sertakan id peminta ketika panggilan `agentId` yang menargetkan diri sendiri harus diizinkan.
- Pelindung pewarisan sandbox: jika sesi peminta berada dalam sandbox, `sessions_spawn` menolak target yang akan berjalan tanpa sandbox.
- `subagents.requireAgentId`: ketika true, blokir panggilan `sessions_spawn` yang menghilangkan `agentId` (memaksa pemilihan profil eksplisit; default: false).
- `subagents.allowAgents`: allowlist id agen untuk target eksplisit `sessions_spawn.agentId` (`["*"]` = apa pun; default: hanya agen yang sama). Sertakan id peminta saat panggilan `agentId` yang menargetkan diri sendiri harus diizinkan.
- Penjaga pewarisan sandbox: jika sesi peminta berada dalam sandbox, `sessions_spawn` menolak target yang akan berjalan tanpa sandbox.
- `subagents.requireAgentId`: saat true, blokir panggilan `sessions_spawn` yang menghilangkan `agentId` (memaksa pemilihan profil eksplisit; default: false).
---
@ -1022,7 +1024,7 @@ Jalankan beberapa agen terisolasi di dalam satu Gateway. Lihat [Multi-Agen](/id/
### Kolom pencocokan binding
- `type` (opsional): `route` untuk perutean normal (tipe yang hilang default ke route), `acp` untuk binding percakapan ACP persisten.
- `type` (opsional): `route` untuk perutean normal (type yang hilang default ke route), `acp` untuk binding percakapan ACP persisten.
- `match.channel` (wajib)
- `match.accountId` (opsional; `*` = akun apa pun; dihilangkan = akun default)
- `match.peer` (opsional; `{ kind: direct|group|channel, id }`)
@ -1038,13 +1040,13 @@ Jalankan beberapa agen terisolasi di dalam satu Gateway. Lihat [Multi-Agen](/id/
5. `match.accountId: "*"` (seluruh channel)
6. Agen default
Di dalam setiap tingkat, entri `bindings` pertama yang cocok menang.
Dalam setiap tingkat, entri `bindings` pertama yang cocok menang.
Untuk entri `type: "acp"`, OpenClaw menyelesaikan berdasarkan identitas percakapan persis (`match.channel` + akun + `match.peer.id`) dan tidak menggunakan urutan tingkat binding route di atas.
Untuk entri `type: "acp"`, OpenClaw menyelesaikan berdasarkan identitas percakapan persis (`match.channel` + akun + `match.peer.id`) dan tidak menggunakan urutan tingkat binding rute di atas.
### Profil akses per agen
<Accordion title="Full access (no sandbox)">
<Accordion title="Akses penuh (tanpa sandbox)">
```json5
{
@ -1062,7 +1064,7 @@ Untuk entri `type: "acp"`, OpenClaw menyelesaikan berdasarkan identitas percakap
</Accordion>
<Accordion title="Read-only tools + workspace">
<Accordion title="Alat hanya-baca + workspace">
```json5
{
@ -1091,7 +1093,7 @@ Untuk entri `type: "acp"`, OpenClaw menyelesaikan berdasarkan identitas percakap
</Accordion>
<Accordion title="No filesystem access (messaging only)">
<Accordion title="Tanpa akses sistem berkas (hanya pesan)">
```json5
{
@ -1187,37 +1189,37 @@ Lihat [Sandbox & Alat Multi-Agen](/id/tools/multi-agent-sandbox-tools) untuk det
}
```
<Accordion title="Session field details">
<Accordion title="Detail kolom sesi">
- **`scope`**: strategi pengelompokan sesi dasar untuk konteks chat grup.
- **`scope`**: strategi pengelompokan sesi dasar untuk konteks obrolan grup.
- `per-sender` (default): setiap pengirim mendapatkan sesi terisolasi dalam konteks channel.
- `global`: semua peserta dalam konteks channel berbagi satu sesi (gunakan hanya ketika konteks bersama memang dimaksudkan).
- `global`: semua peserta dalam konteks channel berbagi satu sesi (gunakan hanya saat konteks bersama memang dimaksudkan).
- **`dmScope`**: cara DM dikelompokkan.
- `main`: semua DM berbagi sesi utama.
- `per-peer`: isolasi berdasarkan id pengirim lintas channel.
- `per-channel-peer`: isolasi per channel + pengirim (direkomendasikan untuk inbox multi-pengguna).
- `per-channel-peer`: isolasi per channel + pengirim (direkomendasikan untuk kotak masuk multi-pengguna).
- `per-account-channel-peer`: isolasi per akun + channel + pengirim (direkomendasikan untuk multi-akun).
- **`identityLinks`**: memetakan id kanonis ke peer berprefiks penyedia untuk berbagi sesi lintas channel. Perintah dock seperti `/dock_discord` menggunakan peta yang sama untuk mengalihkan route balasan sesi aktif ke peer channel tertaut lain; lihat [Docking channel](/id/concepts/channel-docking).
- **`reset`**: kebijakan reset primer. `daily` mereset pada waktu lokal `atHour`; `idle` mereset setelah `idleMinutes`. Ketika keduanya dikonfigurasi, yang kedaluwarsa lebih dulu menang. Kesegaran reset harian menggunakan `sessionStartedAt` dari baris sesi; kesegaran reset idle menggunakan `lastInteractionAt`. Penulisan latar belakang/peristiwa sistem seperti Heartbeat, bangun Cron, notifikasi exec, dan pembukuan Gateway dapat memperbarui `updatedAt`, tetapi itu tidak menjaga sesi daily/idle tetap segar.
- **`resetByType`**: penggantian per tipe (`direct`, `group`, `thread`). `dm` lama diterima sebagai alias untuk `direct`.
- **`parentForkMaxTokens`**: maksimum `totalTokens` sesi induk yang diizinkan saat membuat sesi thread bercabang (default `100000`).
- **`identityLinks`**: memetakan id kanonis ke peer berprefiks penyedia untuk berbagi sesi lintas channel. Perintah dock seperti `/dock_discord` menggunakan peta yang sama untuk mengalihkan rute balasan sesi aktif ke peer channel tertaut lainnya; lihat [Docking channel](/id/concepts/channel-docking).
- **`reset`**: kebijakan reset utama. `daily` mereset pada waktu lokal `atHour`; `idle` mereset setelah `idleMinutes`. Jika keduanya dikonfigurasi, yang kedaluwarsa lebih dulu yang berlaku. Kesegaran reset harian menggunakan `sessionStartedAt` pada baris sesi; kesegaran reset idle menggunakan `lastInteractionAt`. Penulisan latar belakang/peristiwa sistem seperti heartbeat, cron wakeup, notifikasi eksekusi, dan pembukuan Gateway dapat memperbarui `updatedAt`, tetapi tidak menjaga sesi harian/idle tetap segar.
- **`resetByType`**: override per tipe (`direct`, `group`, `thread`). `dm` lama diterima sebagai alias untuk `direct`.
- **`parentForkMaxTokens`**: `totalTokens` sesi induk maksimum yang diizinkan saat membuat sesi thread bercabang (default `100000`).
- Jika `totalTokens` induk berada di atas nilai ini, OpenClaw memulai sesi thread baru alih-alih mewarisi riwayat transkrip induk.
- Tetapkan `0` untuk menonaktifkan pelindung ini dan selalu mengizinkan pencabangan induk.
- **`mainKey`**: kolom lama. Runtime selalu menggunakan `"main"` untuk bucket chat langsung utama.
- **`agentToAgent.maxPingPongTurns`**: jumlah maksimum giliran balasan bolak-balik antar agen selama pertukaran agen-ke-agen (bilangan bulat, rentang: `0`–`5`). `0` menonaktifkan perangkaian ping-pong.
- **`sendPolicy`**: cocokkan berdasarkan `channel`, `chatType` (`direct|group|channel`, dengan alias lama `dm`), `keyPrefix`, atau `rawKeyPrefix`. Penolakan pertama menang.
- Tetapkan `0` untuk menonaktifkan penjaga ini dan selalu mengizinkan percabangan induk.
- **`mainKey`**: field lama. Runtime selalu menggunakan `"main"` untuk bucket obrolan langsung utama.
- **`agentToAgent.maxPingPongTurns`**: jumlah maksimum giliran balasan balik antar agen selama pertukaran agen-ke-agen (bilangan bulat, rentang: `0`–`5`). `0` menonaktifkan perangkaian ping-pong.
- **`sendPolicy`**: cocokkan berdasarkan `channel`, `chatType` (`direct|group|channel`, dengan alias lama `dm`), `keyPrefix`, atau `rawKeyPrefix`. Penolakan pertama yang berlaku menang.
- **`maintenance`**: kontrol pembersihan + retensi penyimpanan sesi.
- `mode`: `warn` hanya memancarkan peringatan; `enforce` menerapkan pembersihan.
- `mode`: `warn` hanya memunculkan peringatan; `enforce` menerapkan pembersihan.
- `pruneAfter`: batas usia untuk entri usang (default `30d`).
- `maxEntries`: jumlah maksimum entri dalam `sessions.json` (default `500`). Runtime menulis pembersihan batch dengan buffer high-water kecil untuk batas berukuran produksi; `openclaw sessions cleanup --enforce` menerapkan batas segera.
- `rotateBytes`: usang dan diabaikan; `openclaw doctor --fix` menghapusnya dari config lama.
- `maxEntries`: jumlah maksimum entri dalam `sessions.json` (default `500`). Runtime menulis pembersihan batch dengan buffer batas atas kecil untuk batas berukuran produksi; `openclaw sessions cleanup --enforce` menerapkan batas tersebut langsung.
- `rotateBytes`: tidak digunakan lagi dan diabaikan; `openclaw doctor --fix` menghapusnya dari konfigurasi lama.
- `resetArchiveRetention`: retensi untuk arsip transkrip `*.reset.<timestamp>`. Default ke `pruneAfter`; tetapkan `false` untuk menonaktifkan.
- `maxDiskBytes`: anggaran disk direktori sesi opsional. Dalam mode `warn`, ini mencatat peringatan; dalam mode `enforce`, ini menghapus artefak/sesi tertua terlebih dahulu.
- `highWaterBytes`: target opsional setelah pembersihan anggaran. Default ke `80%` dari `maxDiskBytes`.
- **`threadBindings`**: default global untuk fitur sesi yang terikat thread.
- `enabled`: sakelar default utama (penyedia dapat menimpa; Discord menggunakan `channels.discord.threadBindings.enabled`)
- `idleHours`: auto-unfocus default karena tidak aktif dalam jam (`0` menonaktifkan; penyedia dapat menimpa)
- `maxAgeHours`: usia maksimum keras default dalam jam (`0` menonaktifkan; penyedia dapat menimpa)
- **`threadBindings`**: default global untuk fitur sesi terikat thread.
- `enabled`: sakelar default utama (penyedia dapat melakukan override; Discord menggunakan `channels.discord.threadBindings.enabled`)
- `idleHours`: auto-unfocus default karena tidak aktif dalam jam (`0` menonaktifkan; penyedia dapat melakukan override)
- `maxAgeHours`: usia maksimum keras default dalam jam (`0` menonaktifkan; penyedia dapat melakukan override)
</Accordion>
@ -1255,38 +1257,38 @@ Lihat [Sandbox & Alat Multi-Agen](/id/tools/multi-agent-sandbox-tools) untuk det
### Prefiks respons
Penimpaan per kanal/akun: `channels.<channel>.responsePrefix`, `channels.<channel>.accounts.<id>.responsePrefix`.
Override per channel/akun: `channels.<channel>.responsePrefix`, `channels.<channel>.accounts.<id>.responsePrefix`.
Resolusi (yang paling spesifik menang): akun → kanal → global. `""` menonaktifkan dan menghentikan kaskade. `"auto"` menghasilkan `[{identity.name}]`.
Resolusi (yang paling spesifik menang): akun → channel → global. `""` menonaktifkan dan menghentikan kaskade. `"auto"` diturunkan dari `[{identity.name}]`.
**Variabel templat:**
| Variabel | Deskripsi | Contoh |
| ----------------- | --------------------------- | --------------------------- |
| `{model}` | Nama model singkat | `claude-opus-4-6` |
| `{modelFull}` | Pengidentifikasi model penuh | `anthropic/claude-opus-4-6` |
| `{provider}` | Nama penyedia | `anthropic` |
| `{thinkingLevel}` | Tingkat berpikir saat ini | `high`, `low`, `off` |
| `{identity.name}` | Nama identitas agen | (sama seperti `"auto"`) |
| Variabel | Deskripsi | Contoh |
| ----------------- | ---------------------- | --------------------------- |
| `{model}` | Nama model pendek | `claude-opus-4-6` |
| `{modelFull}` | Pengidentifikasi model lengkap | `anthropic/claude-opus-4-6` |
| `{provider}` | Nama penyedia | `anthropic` |
| `{thinkingLevel}` | Level berpikir saat ini | `high`, `low`, `off` |
| `{identity.name}` | Nama identitas agen | (sama seperti `"auto"`) |
Variabel tidak peka huruf besar/kecil. `{think}` adalah alias untuk `{thinkingLevel}`.
### Reaksi ack
### Reaksi konfirmasi
- Default ke `identity.emoji` agen aktif, jika tidak ada menggunakan `"👀"`. Atur `""` untuk menonaktifkan.
- Penimpaan per kanal: `channels.<channel>.ackReaction`, `channels.<channel>.accounts.<id>.ackReaction`.
- Urutan resolusi: akun → kanal → `messages.ackReaction` → fallback identitas.
- Default ke `identity.emoji` agen aktif, jika tidak ada maka `"👀"`. Tetapkan `""` untuk menonaktifkan.
- Override per channel: `channels.<channel>.ackReaction`, `channels.<channel>.accounts.<id>.ackReaction`.
- Urutan resolusi: akun → channel → `messages.ackReaction` → fallback identitas.
- Cakupan: `group-mentions` (default), `group-all`, `direct`, `all`.
- `removeAckAfterReply`: menghapus ack setelah balasan pada kanal yang mendukung reaksi seperti Slack, Discord, Telegram, WhatsApp, dan BlueBubbles.
- `removeAckAfterReply`: menghapus reaksi konfirmasi setelah balasan pada channel yang mendukung reaksi seperti Slack, Discord, Telegram, WhatsApp, dan BlueBubbles.
- `messages.statusReactions.enabled`: mengaktifkan reaksi status siklus hidup di Slack, Discord, dan Telegram.
Di Slack dan Discord, nilai yang tidak diatur mempertahankan reaksi status tetap aktif saat reaksi ack aktif.
Di Telegram, atur secara eksplisit ke `true` untuk mengaktifkan reaksi status siklus hidup.
Di Slack dan Discord, nilai yang tidak ditetapkan mempertahankan reaksi status aktif saat reaksi konfirmasi aktif.
Di Telegram, tetapkan secara eksplisit ke `true` untuk mengaktifkan reaksi status siklus hidup.
### Debounce masuk
Mengelompokkan pesan cepat yang hanya berisi teks dari pengirim yang sama ke dalam satu giliran agen. Media/lampiran langsung di-flush. Perintah kontrol melewati debounce.
Mengelompokkan pesan khusus teks yang cepat dari pengirim yang sama menjadi satu giliran agen. Media/lampiran langsung mengosongkan antrean. Perintah kontrol melewati debouncing.
### TTS (teks-ke-suara)
### TTS (teks-ke-ucapan)
```json5
{
@ -1334,19 +1336,19 @@ Mengelompokkan pesan cepat yang hanya berisi teks dari pengirim yang sama ke dal
}
```
- `auto` mengontrol mode auto-TTS default: `off`, `always`, `inbound`, atau `tagged`. `/tts on|off` dapat menimpa preferensi lokal, dan `/tts status` menampilkan status efektif.
- `summaryModel` menimpa `agents.defaults.model.primary` untuk ringkasan otomatis.
- `modelOverrides` diaktifkan secara default; `modelOverrides.allowProvider` default ke `false` (ikut serta).
- Kunci API melakukan fallback ke `ELEVENLABS_API_KEY`/`XI_API_KEY` dan `OPENAI_API_KEY`.
- Penyedia ucapan bawaan dimiliki oleh Plugin. Jika `plugins.allow` diatur, sertakan setiap Plugin penyedia TTS yang ingin Anda gunakan, misalnya `microsoft` untuk Edge TTS. Id penyedia lama `edge` diterima sebagai alias untuk `microsoft`.
- `providers.openai.baseUrl` menimpa endpoint TTS OpenAI. Urutan resolusinya adalah konfigurasi, lalu `OPENAI_TTS_BASE_URL`, lalu `https://api.openai.com/v1`.
- Ketika `providers.openai.baseUrl` mengarah ke endpoint non-OpenAI, OpenClaw memperlakukannya sebagai server TTS yang kompatibel dengan OpenAI dan melonggarkan validasi model/suara.
- `auto` mengontrol mode auto-TTS default: `off`, `always`, `inbound`, atau `tagged`. `/tts on|off` dapat melakukan override preferensi lokal, dan `/tts status` menampilkan status efektif.
- `summaryModel` melakukan override `agents.defaults.model.primary` untuk ringkasan otomatis.
- `modelOverrides` diaktifkan secara default; `modelOverrides.allowProvider` default ke `false` (ikut serta eksplisit).
- Kunci API fallback ke `ELEVENLABS_API_KEY`/`XI_API_KEY` dan `OPENAI_API_KEY`.
- Penyedia ucapan bawaan dimiliki Plugin. Jika `plugins.allow` ditetapkan, sertakan setiap Plugin penyedia TTS yang ingin Anda gunakan, misalnya `microsoft` untuk Edge TTS. Id penyedia lama `edge` diterima sebagai alias untuk `microsoft`.
- `providers.openai.baseUrl` melakukan override endpoint TTS OpenAI. Urutan resolusi adalah konfigurasi, lalu `OPENAI_TTS_BASE_URL`, lalu `https://api.openai.com/v1`.
- Saat `providers.openai.baseUrl` menunjuk ke endpoint non-OpenAI, OpenClaw memperlakukannya sebagai server TTS yang kompatibel dengan OpenAI dan melonggarkan validasi model/suara.
---
## Bicara
## Talk
Default untuk mode Bicara (macOS/iOS/Android).
Default untuk mode Talk (macOS/iOS/Android).
```json5
{
@ -1375,16 +1377,16 @@ Default untuk mode Bicara (macOS/iOS/Android).
}
```
- `talk.provider` harus cocok dengan kunci di `talk.providers` ketika beberapa penyedia Bicara dikonfigurasi.
- Kunci Bicara datar lama (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) hanya untuk kompatibilitas dan dimigrasikan otomatis ke `talk.providers.<provider>`.
- ID suara melakukan fallback ke `ELEVENLABS_VOICE_ID` atau `SAG_VOICE_ID`.
- `talk.provider` harus cocok dengan kunci dalam `talk.providers` saat beberapa penyedia Talk dikonfigurasi.
- Kunci Talk datar lama (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) hanya untuk kompatibilitas dan dimigrasikan otomatis ke `talk.providers.<provider>`.
- ID suara fallback ke `ELEVENLABS_VOICE_ID` atau `SAG_VOICE_ID`.
- `providers.*.apiKey` menerima string teks biasa atau objek SecretRef.
- Fallback `ELEVENLABS_API_KEY` hanya berlaku ketika tidak ada kunci API Bicara yang dikonfigurasi.
- `providers.*.voiceAliases` memungkinkan direktif Bicara menggunakan nama yang mudah dikenali.
- Fallback `ELEVENLABS_API_KEY` hanya berlaku saat tidak ada kunci API Talk yang dikonfigurasi.
- `providers.*.voiceAliases` memungkinkan direktif Talk menggunakan nama yang mudah dikenali.
- `providers.mlx.modelId` memilih repo Hugging Face yang digunakan oleh helper MLX lokal macOS. Jika dihilangkan, macOS menggunakan `mlx-community/Soprano-80M-bf16`.
- Pemutaran MLX macOS berjalan melalui helper `openclaw-mlx-tts` bawaan jika ada, atau executable di `PATH`; `OPENCLAW_MLX_TTS_BIN` menimpa jalur helper untuk pengembangan.
- `speechLocale` mengatur id locale BCP 47 yang digunakan oleh pengenalan ucapan Bicara iOS/macOS. Biarkan tidak diatur untuk menggunakan default perangkat.
- `silenceTimeoutMs` mengontrol berapa lama mode Bicara menunggu setelah pengguna diam sebelum mengirim transkrip. Nilai yang tidak diatur mempertahankan jendela jeda default platform (`700 ms on macOS and Android, 900 ms on iOS`).
- Pemutaran MLX macOS berjalan melalui helper `openclaw-mlx-tts` bawaan jika ada, atau executable di `PATH`; `OPENCLAW_MLX_TTS_BIN` melakukan override jalur helper untuk pengembangan.
- `speechLocale` menetapkan id lokal BCP 47 yang digunakan oleh pengenalan ucapan Talk iOS/macOS. Biarkan tidak ditetapkan untuk menggunakan default perangkat.
- `silenceTimeoutMs` mengontrol berapa lama mode Talk menunggu setelah pengguna diam sebelum mengirim transkrip. Nilai yang tidak ditetapkan mempertahankan jendela jeda default platform (`700 ms on macOS and Android, 900 ms on iOS`).
---

294
docs/id/gateway/config-channels.md
View File

@ -3,22 +3,22 @@ read_when:
- Mengonfigurasi Plugin saluran (autentikasi, kontrol akses, multi-akun)
- Pemecahan masalah kunci konfigurasi per saluran
- Mengaudit kebijakan pesan langsung, kebijakan grup, atau pembatasan penyebutan
summary: 'Konfigurasi channel: kontrol akses, penyandingan, kunci per-channel di Slack, Discord, Telegram, WhatsApp, Matrix, iMessage, dan lainnya'
summary: 'Konfigurasi saluran: kontrol akses, penyandingan, kunci per saluran di Slack, Discord, Telegram, WhatsApp, Matrix, iMessage, dan lainnya'
title: Konfigurasi — saluran
x-i18n:
generated_at: "2026-04-30T09:47:29Z"
generated_at: "2026-04-30T16:29:03Z"
model: gpt-5.5
provider: openai
source_hash: e16ab50020711aac8e06cd234739ac7b566420cf7ce8621c0aca12c22484f07f
source_hash: aba14cb43e1fe914cc7c03f41bed1b5915cc6b2ad8e0f1d47f58b7e98c1b3915
source_path: gateway/config-channels.md
workflow: 16
---
Kunci konfigurasi per kanal di bawah `channels.*`. Mencakup akses DM dan grup,
penyiapan multi-akun, pembatasan mention, serta kunci per kanal untuk Slack, Discord,
Telegram, WhatsApp, Matrix, iMessage, dan Plugin kanal bawaan lainnya.
penyiapan multi-akun, gerbang mention, serta kunci per kanal untuk Slack, Discord,
Telegram, WhatsApp, Matrix, iMessage, dan plugin kanal bawaan lainnya.
Untuk agen, alat, runtime Gateway, dan kunci tingkat atas lainnya, lihat
Untuk agen, alat, runtime gateway, dan kunci tingkat atas lainnya, lihat
[Referensi konfigurasi](/id/gateway/configuration-reference).
## Kanal
@ -31,26 +31,26 @@ Semua kanal mendukung kebijakan DM dan kebijakan grup:
| Kebijakan DM | Perilaku |
| ------------------- | --------------------------------------------------------------- |
| `pairing` (default) | Pengirim tidak dikenal menerima kode pairing sekali pakai; pemilik harus menyetujui |
| `allowlist` | Hanya pengirim dalam `allowFrom` (atau penyimpanan izin yang sudah dipairing) |
| `pairing` (default) | Pengirim tidak dikenal mendapat kode pairing satu kali; pemilik harus menyetujui |
| `allowlist` | Hanya pengirim dalam `allowFrom` (atau penyimpanan izin yang sudah dipasangkan) |
| `open` | Izinkan semua DM masuk (memerlukan `allowFrom: ["*"]`) |
| `disabled` | Abaikan semua DM masuk |
| Kebijakan grup | Perilaku |
| --------------------- | ------------------------------------------------------ |
| `allowlist` (default) | Hanya grup yang cocok dengan allowlist yang dikonfigurasi |
| `open` | Lewati allowlist grup (pembatasan mention tetap berlaku) |
| `open` | Lewati allowlist grup (gerbang mention tetap berlaku) |
| `disabled` | Blokir semua pesan grup/ruang |
<Note>
`channels.defaults.groupPolicy` menetapkan default saat `groupPolicy` milik penyedia belum diatur.
Kode pairing kedaluwarsa setelah 1 jam. Permintaan pairing DM yang tertunda dibatasi hingga **3 per kanal**.
Jika blok penyedia sepenuhnya tidak ada (`channels.<provider>` tidak ada), kebijakan grup runtime kembali ke `allowlist` (fail-closed) dengan peringatan saat startup.
Jika blok penyedia sepenuhnya hilang (`channels.<provider>` tidak ada), kebijakan grup runtime kembali ke `allowlist` (fail-closed) dengan peringatan saat startup.
</Note>
### Override model kanal
### Penggantian model kanal
Gunakan `channels.modelByChannel` untuk menetapkan ID kanal tertentu ke sebuah model. Nilai menerima `provider/model` atau alias model yang dikonfigurasi. Pemetaan kanal diterapkan saat sebuah sesi belum memiliki override model (misalnya, yang diatur melalui `/model`).
Gunakan `channels.modelByChannel` untuk menyematkan ID kanal tertentu ke suatu model. Nilai menerima `provider/model` atau alias model yang dikonfigurasi. Pemetaan kanal berlaku saat sesi belum memiliki penggantian model (misalnya, diatur melalui `/model`).
```json5
{
@ -73,7 +73,7 @@ Gunakan `channels.modelByChannel` untuk menetapkan ID kanal tertentu ke sebuah m
### Default kanal dan Heartbeat
Gunakan `channels.defaults` untuk perilaku kebijakan grup dan Heartbeat bersama lintas penyedia:
Gunakan `channels.defaults` untuk perilaku kebijakan grup dan Heartbeat bersama di seluruh penyedia:
```json5
{
@ -91,15 +91,15 @@ Gunakan `channels.defaults` untuk perilaku kebijakan grup dan Heartbeat bersama
}
```
- `channels.defaults.groupPolicy`: kebijakan grup fallback saat `groupPolicy` tingkat penyedia belum diatur.
- `channels.defaults.contextVisibility`: mode visibilitas konteks tambahan default untuk semua kanal. Nilai: `all` (default, sertakan semua konteks kutipan/thread/riwayat), `allowlist` (hanya sertakan konteks dari pengirim yang diizinkan), `allowlist_quote` (sama seperti allowlist tetapi tetap simpan konteks kutipan/balasan eksplisit). Override per kanal: `channels.<channel>.contextVisibility`.
- `channels.defaults.heartbeat.showOk`: sertakan status kanal sehat dalam output Heartbeat.
- `channels.defaults.groupPolicy`: kebijakan grup cadangan saat `groupPolicy` tingkat penyedia belum diatur.
- `channels.defaults.contextVisibility`: mode visibilitas konteks tambahan default untuk semua kanal. Nilai: `all` (default, sertakan semua konteks kutipan/thread/riwayat), `allowlist` (hanya sertakan konteks dari pengirim yang ada di allowlist), `allowlist_quote` (sama seperti allowlist tetapi tetap pertahankan konteks kutipan/balasan eksplisit). Penggantian per kanal: `channels.<channel>.contextVisibility`.
- `channels.defaults.heartbeat.showOk`: sertakan status kanal yang sehat dalam output Heartbeat.
- `channels.defaults.heartbeat.showAlerts`: sertakan status terdegradasi/error dalam output Heartbeat.
- `channels.defaults.heartbeat.useIndicator`: render output Heartbeat ringkas bergaya indikator.
### WhatsApp
WhatsApp berjalan melalui kanal web Gateway (Baileys Web). Kanal ini dimulai otomatis saat sesi tertaut ada.
WhatsApp berjalan melalui kanal web Gateway (Baileys Web). Ini dimulai otomatis saat sesi tertaut ada.
```json5
{
@ -139,7 +139,7 @@ WhatsApp berjalan melalui kanal web Gateway (Baileys Web). Kanal ini dimulai oto
}
```
<Accordion title="WhatsApp Multi-akun">
<Accordion title="WhatsApp multi-akun">
```json5
{
@ -158,9 +158,9 @@ WhatsApp berjalan melalui kanal web Gateway (Baileys Web). Kanal ini dimulai oto
```
- Perintah keluar menggunakan akun `default` secara default jika ada; jika tidak, ID akun pertama yang dikonfigurasi (diurutkan).
- `channels.whatsapp.defaultAccount` opsional meng-override pemilihan akun default fallback tersebut saat cocok dengan ID akun yang dikonfigurasi.
- `channels.whatsapp.defaultAccount` opsional mengganti pemilihan akun default cadangan itu saat cocok dengan ID akun yang dikonfigurasi.
- Direktori auth Baileys satu-akun lama dimigrasikan oleh `openclaw doctor` ke `whatsapp/default`.
- Override per akun: `channels.whatsapp.accounts.<id>.sendReadReceipts`, `channels.whatsapp.accounts.<id>.dmPolicy`, `channels.whatsapp.accounts.<id>.allowFrom`.
- Penggantian per akun: `channels.whatsapp.accounts.<id>.sendReadReceipts`, `channels.whatsapp.accounts.<id>.dmPolicy`, `channels.whatsapp.accounts.<id>.allowFrom`.
</Accordion>
@ -219,14 +219,14 @@ WhatsApp berjalan melalui kanal web Gateway (Baileys Web). Kanal ini dimulai oto
}
```
- Token bot: `channels.telegram.botToken` atau `channels.telegram.tokenFile` (hanya berkas reguler; symlink ditolak), dengan `TELEGRAM_BOT_TOKEN` sebagai fallback untuk akun default.
- `apiRoot` hanya root Telegram Bot API. Gunakan `https://api.telegram.org` atau root self-hosted/proxy Anda, bukan `https://api.telegram.org/bot<TOKEN>`; `openclaw doctor --fix` menghapus sufiks `/bot<TOKEN>` tidak sengaja yang tertinggal.
- `channels.telegram.defaultAccount` opsional meng-override pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi.
- Dalam penyiapan multi-akun (2+ ID akun), tetapkan default eksplisit (`channels.telegram.defaultAccount` atau `channels.telegram.accounts.default`) untuk menghindari routing fallback; `openclaw doctor` memperingatkan saat ini hilang atau tidak valid.
- Token bot: `channels.telegram.botToken` atau `channels.telegram.tokenFile` (hanya file biasa; symlink ditolak), dengan `TELEGRAM_BOT_TOKEN` sebagai cadangan untuk akun default.
- `apiRoot` hanya root Telegram Bot API. Gunakan `https://api.telegram.org` atau root self-hosted/proxy Anda, bukan `https://api.telegram.org/bot<TOKEN>`; `openclaw doctor --fix` menghapus sufiks `/bot<TOKEN>` yang tidak sengaja tertinggal.
- `channels.telegram.defaultAccount` opsional mengganti pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi.
- Dalam penyiapan multi-akun (2+ ID akun), tetapkan default eksplisit (`channels.telegram.defaultAccount` atau `channels.telegram.accounts.default`) untuk menghindari perutean cadangan; `openclaw doctor` memperingatkan saat ini hilang atau tidak valid.
- `configWrites: false` memblokir penulisan konfigurasi yang dimulai dari Telegram (migrasi ID supergroup, `/config set|unset`).
- Entri `bindings[]` tingkat atas dengan `type: "acp"` mengonfigurasi binding ACP persisten untuk topik forum (gunakan `chatId:topic:topicId` kanonis dalam `match.peer.id`). Semantik field dibagikan di [Agen ACP](/id/tools/acp-agents#channel-specific-settings).
- Entri `bindings[]` tingkat atas dengan `type: "acp"` mengonfigurasi binding ACP persisten untuk topik forum (gunakan `chatId:topic:topicId` kanonis di `match.peer.id`). Semantik bidang dibagikan di [Agen ACP](/id/tools/acp-agents#channel-specific-settings).
- Pratinjau stream Telegram menggunakan `sendMessage` + `editMessageText` (berfungsi di chat langsung dan grup).
- Kebijakan percobaan ulang: lihat [Kebijakan percobaan ulang](/id/concepts/retry).
- Kebijakan coba ulang: lihat [Kebijakan coba ulang](/id/concepts/retry).
### Discord
@ -330,33 +330,33 @@ WhatsApp berjalan melalui kanal web Gateway (Baileys Web). Kanal ini dimulai oto
- Token: `channels.discord.token`, dengan `DISCORD_BOT_TOKEN` sebagai fallback untuk akun default.
- Panggilan keluar langsung yang menyediakan Discord `token` eksplisit menggunakan token tersebut untuk panggilan; pengaturan percobaan ulang/kebijakan akun tetap berasal dari akun yang dipilih dalam snapshot runtime aktif.
- `channels.discord.defaultAccount` opsional mengganti pemilihan akun default saat cocok dengan id akun yang dikonfigurasi.
- `channels.discord.defaultAccount` opsional menimpa pemilihan akun default ketika cocok dengan id akun yang dikonfigurasi.
- Gunakan `user:<id>` (DM) atau `channel:<id>` (kanal guild) untuk target pengiriman; ID numerik polos ditolak.
- Slug guild memakai huruf kecil dengan spasi diganti `-`; kunci kanal menggunakan nama yang sudah dibuat slug (tanpa `#`). Sebaiknya gunakan ID guild.
- Slug guild menggunakan huruf kecil dengan spasi diganti `-`; kunci kanal menggunakan nama yang sudah menjadi slug (tanpa `#`). Lebih disarankan memakai ID guild.
- Pesan yang dibuat bot diabaikan secara default. `allowBots: true` mengaktifkannya; gunakan `allowBots: "mentions"` untuk hanya menerima pesan bot yang menyebut bot (pesan sendiri tetap difilter).
- `channels.discord.guilds.<id>.ignoreOtherMentions` (dan override kanal) membuang pesan yang menyebut pengguna atau peran lain tetapi bukan bot (tidak termasuk @everyone/@here).
- `maxLinesPerMessage` (default 17) memecah pesan tinggi meskipun di bawah 2000 karakter.
- `channels.discord.threadBindings` mengontrol perutean Discord yang terikat thread:
- `enabled`: override Discord untuk fitur sesi yang terikat thread (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, serta pengiriman/perutean terikat)
- `idleHours`: override Discord untuk auto-unfocus akibat tidak aktif dalam jam (`0` menonaktifkan)
- `maxAgeHours`: override Discord untuk usia maksimum keras dalam jam (`0` menonaktifkan)
- `spawnSubagentSessions`: sakelar opt-in untuk pembuatan/pengikatan thread otomatis `sessions_spawn({ thread: true })`
- Entri `bindings[]` level atas dengan `type: "acp"` mengonfigurasi pengikatan ACP persisten untuk kanal dan thread (gunakan id kanal/thread di `match.peer.id`). Semantik field dibagikan di [Agen ACP](/id/tools/acp-agents#channel-specific-settings).
- `channels.discord.guilds.<id>.ignoreOtherMentions` (dan penimpaan kanal) membuang pesan yang menyebut pengguna atau peran lain tetapi bukan bot (tidak termasuk @everyone/@here).
- `maxLinesPerMessage` (default 17) membagi pesan tinggi bahkan ketika di bawah 2000 karakter.
- `channels.discord.threadBindings` mengontrol routing berbasis thread Discord:
- `enabled`: penimpaan Discord untuk fitur sesi berbasis thread (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, dan pengiriman/routing terikat)
- `idleHours`: penimpaan Discord untuk auto-unfocus karena tidak aktif dalam jam (`0` menonaktifkan)
- `maxAgeHours`: penimpaan Discord untuk usia maksimum keras dalam jam (`0` menonaktifkan)
- `spawnSubagentSessions`: sakelar ikut-serta untuk pembuatan/pengikatan thread otomatis `sessions_spawn({ thread: true })`
- Entri `bindings[]` tingkat atas dengan `type: "acp"` mengonfigurasi pengikatan ACP persisten untuk kanal dan thread (gunakan id kanal/thread di `match.peer.id`). Semantik kolom dibagikan di [Agen ACP](/id/tools/acp-agents#channel-specific-settings).
- `channels.discord.ui.components.accentColor` mengatur warna aksen untuk kontainer komponen Discord v2.
- `channels.discord.voice` mengaktifkan percakapan kanal suara Discord dan override auto-join + LLM + TTS opsional.
- `channels.discord.voice.model` secara opsional mengganti model LLM yang digunakan untuk respons kanal suara Discord.
- `channels.discord.voice` mengaktifkan percakapan kanal suara Discord dan penimpaan auto-join + LLM + TTS opsional.
- `channels.discord.voice.model` secara opsional menimpa model LLM yang digunakan untuk respons kanal suara Discord.
- `channels.discord.voice.daveEncryption` dan `channels.discord.voice.decryptionFailureTolerance` diteruskan ke opsi DAVE `@discordjs/voice` (`true` dan `24` secara default).
- OpenClaw juga mencoba pemulihan penerimaan suara dengan keluar/bergabung ulang ke sesi suara setelah kegagalan dekripsi berulang.
- `channels.discord.streaming` adalah kunci mode stream kanonis. Nilai legacy `streamMode` dan boolean `streaming` dimigrasikan otomatis.
- `channels.discord.autoPresence` memetakan ketersediaan runtime ke presence bot (healthy => online, degraded => idle, exhausted => dnd) dan mengizinkan override teks status opsional.
- `channels.discord.dangerouslyAllowNameMatching` mengaktifkan kembali pencocokan nama/tag yang dapat berubah (mode kompatibilitas break-glass).
- `channels.discord.autoPresence` memetakan ketersediaan runtime ke kehadiran bot (sehat => online, menurun => idle, habis => dnd) dan mengizinkan penimpaan teks status opsional.
- `channels.discord.dangerouslyAllowNameMatching` mengaktifkan ulang pencocokan nama/tag yang dapat berubah (mode kompatibilitas darurat).
- `channels.discord.execApprovals`: pengiriman persetujuan exec native Discord dan otorisasi pemberi persetujuan.
- `enabled`: `true`, `false`, atau `"auto"` (default). Dalam mode auto, persetujuan exec aktif saat pemberi persetujuan dapat diselesaikan dari `approvers` atau `commands.ownerAllowFrom`.
- `approvers`: ID pengguna Discord yang diizinkan menyetujui permintaan exec. Fallback ke `commands.ownerAllowFrom` saat dihilangkan.
- `enabled`: `true`, `false`, atau `"auto"` (default). Dalam mode otomatis, persetujuan exec aktif ketika pemberi persetujuan dapat di-resolve dari `approvers` atau `commands.ownerAllowFrom`.
- `approvers`: ID pengguna Discord yang diizinkan menyetujui permintaan exec. Fallback ke `commands.ownerAllowFrom` ketika dihilangkan.
- `agentFilter`: allowlist ID agen opsional. Hilangkan untuk meneruskan persetujuan bagi semua agen.
- `sessionFilter`: pola kunci sesi opsional (substring atau regex).
- `target`: tempat mengirim prompt persetujuan. `"dm"` (default) mengirim ke DM pemberi persetujuan, `"channel"` mengirim ke kanal asal, `"both"` mengirim ke keduanya. Saat target menyertakan `"channel"`, tombol hanya dapat digunakan oleh pemberi persetujuan yang berhasil diselesaikan.
- `cleanupAfterResolve`: saat `true`, menghapus DM persetujuan setelah persetujuan, penolakan, atau timeout.
- `target`: tempat mengirim prompt persetujuan. `"dm"` (default) mengirim ke DM pemberi persetujuan, `"channel"` mengirim ke kanal asal, `"both"` mengirim ke keduanya. Ketika target mencakup `"channel"`, tombol hanya dapat digunakan oleh pemberi persetujuan yang di-resolve.
- `cleanupAfterResolve`: ketika `true`, menghapus DM persetujuan setelah persetujuan, penolakan, atau timeout.
**Mode notifikasi reaksi:** `off` (tidak ada), `own` (pesan bot, default), `all` (semua pesan), `allowlist` (dari `guilds.<id>.users` pada semua pesan).
@ -393,7 +393,7 @@ WhatsApp berjalan melalui kanal web Gateway (Baileys Web). Kanal ini dimulai oto
- SecretRef akun layanan juga didukung (`serviceAccountRef`).
- Fallback env: `GOOGLE_CHAT_SERVICE_ACCOUNT` atau `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`.
- Gunakan `spaces/<spaceId>` atau `users/<userId>` untuk target pengiriman.
- `channels.googlechat.dangerouslyAllowNameMatching` mengaktifkan kembali pencocokan principal email yang dapat berubah (mode kompatibilitas break-glass).
- `channels.googlechat.dangerouslyAllowNameMatching` mengaktifkan ulang pencocokan prinsipal email yang dapat berubah (mode kompatibilitas darurat).
### Slack
@ -465,18 +465,18 @@ WhatsApp berjalan melalui kanal web Gateway (Baileys Web). Kanal ini dimulai oto
}
```
- **Mode socket** memerlukan `botToken` dan `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` untuk fallback env akun default).
- **Mode HTTP** memerlukan `botToken` ditambah `signingSecret` (di root atau per akun).
- `socketMode` meneruskan penyesuaian transport Socket Mode Slack SDK ke API receiver Bolt publik. Gunakan hanya saat menyelidiki timeout ping/pong atau perilaku websocket usang.
- **Mode soket** memerlukan `botToken` dan `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` untuk fallback env akun default).
- **Mode HTTP** memerlukan `botToken` plus `signingSecret` (di root atau per akun).
- `socketMode` meneruskan penyetelan transport Slack SDK Socket Mode ke API receiver Bolt publik. Gunakan hanya saat menyelidiki timeout ping/pong atau perilaku websocket usang.
- `botToken`, `appToken`, `signingSecret`, dan `userToken` menerima string plaintext
atau objek SecretRef.
- Snapshot akun Slack mengekspos field sumber/status per kredensial seperti
- Snapshot akun Slack mengekspos kolom sumber/status per kredensial seperti
`botTokenSource`, `botTokenStatus`, `appTokenStatus`, dan, dalam mode HTTP,
`signingSecretStatus`. `configured_unavailable` berarti akun
dikonfigurasi melalui SecretRef tetapi jalur perintah/runtime saat ini tidak dapat
menyelesaikan nilai secret.
- `configWrites: false` memblokir penulisan konfigurasi yang dimulai Slack.
- `channels.slack.defaultAccount` opsional mengganti pemilihan akun default saat cocok dengan id akun yang dikonfigurasi.
me-resolve nilai secret.
- `configWrites: false` memblokir penulisan konfigurasi yang diprakarsai Slack.
- `channels.slack.defaultAccount` opsional menimpa pemilihan akun default ketika cocok dengan id akun yang dikonfigurasi.
- `channels.slack.streaming.mode` adalah kunci mode stream Slack kanonis. `channels.slack.streaming.nativeTransport` mengontrol transport streaming native Slack. Nilai legacy `streamMode`, boolean `streaming`, dan `nativeStreaming` dimigrasikan otomatis.
- Gunakan `user:<id>` (DM) atau `channel:<id>` untuk target pengiriman.
@ -484,24 +484,24 @@ WhatsApp berjalan melalui kanal web Gateway (Baileys Web). Kanal ini dimulai oto
**Isolasi sesi thread:** `thread.historyScope` bersifat per-thread (default) atau dibagikan di seluruh kanal. `thread.inheritParent` menyalin transkrip kanal induk ke thread baru.
- Streaming native Slack ditambah status thread gaya asisten Slack "is typing..." memerlukan target thread balasan. DM level atas tetap di luar thread secara default, sehingga menggunakan `typingReaction` atau pengiriman normal alih-alih pratinjau gaya thread.
- `typingReaction` menambahkan reaksi sementara ke pesan Slack masuk saat balasan berjalan, lalu menghapusnya setelah selesai. Gunakan shortcode emoji Slack seperti `"hourglass_flowing_sand"`.
- `channels.slack.execApprovals`: pengiriman persetujuan exec native Slack dan otorisasi pemberi persetujuan. Skema sama seperti Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ID pengguna Slack), `agentFilter`, `sessionFilter`, dan `target` (`"dm"`, `"channel"`, atau `"both"`).
- Streaming native Slack plus status thread gaya asisten Slack "is typing..." memerlukan target thread balasan. DM tingkat atas tetap di luar thread secara default, sehingga menggunakan `typingReaction` atau pengiriman normal alih-alih pratinjau gaya thread.
- `typingReaction` menambahkan reaksi sementara ke pesan Slack masuk saat balasan berjalan, lalu menghapusnya saat selesai. Gunakan shortcode emoji Slack seperti `"hourglass_flowing_sand"`.
- `channels.slack.execApprovals`: pengiriman persetujuan exec native Slack dan otorisasi pemberi persetujuan. Skema yang sama seperti Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ID pengguna Slack), `agentFilter`, `sessionFilter`, dan `target` (`"dm"`, `"channel"`, atau `"both"`).
| Grup tindakan | Default | Catatan |
| ------------- | ------- | ---------------------- |
| reactions | aktif | React + daftar reaksi |
| messages | aktif | Baca/kirim/edit/hapus |
| pins | aktif | Pin/unpin/daftar |
| memberInfo | aktif | Info anggota |
| emojiList | aktif | Daftar emoji kustom |
| Grup tindakan | Default | Catatan |
| ------------ | ------- | ---------------------- |
| reactions | aktif | Bereaksi + daftar reaksi |
| messages | aktif | Baca/kirim/edit/hapus |
| pins | aktif | Sematkan/lepas sematan/daftar |
| memberInfo | aktif | Info anggota |
| emojiList | aktif | Daftar emoji kustom |
### Mattermost
Mattermost dikirim sebagai Plugin bawaan dalam rilis OpenClaw saat ini. Build lama atau
Mattermost dikirim sebagai Plugin bundel dalam rilis OpenClaw saat ini. Build lama atau
kustom dapat menginstal paket npm saat ini dengan
`openclaw plugins install @openclaw/mattermost`; jika npm melaporkan paket
milik OpenClaw sebagai deprecated, gunakan Plugin bawaan atau checkout lokal
milik OpenClaw sebagai deprecated, gunakan Plugin bundel atau checkout lokal
hingga paket npm yang lebih baru dipublikasikan.
```json5
@ -534,21 +534,21 @@ hingga paket npm yang lebih baru dipublikasikan.
Mode chat: `oncall` (merespons pada @-mention, default), `onmessage` (setiap pesan), `onchar` (pesan yang dimulai dengan prefiks pemicu).
Saat perintah native Mattermost diaktifkan:
Ketika perintah native Mattermost diaktifkan:
- `commands.callbackPath` harus berupa path (misalnya `/api/channels/mattermost/command`), bukan URL lengkap.
- `commands.callbackUrl` harus mengarah ke endpoint Gateway OpenClaw dan dapat dijangkau dari server Mattermost.
- `commands.callbackPath` harus berupa path (misalnya `/api/channels/mattermost/command`), bukan URL penuh.
- `commands.callbackUrl` harus me-resolve ke endpoint Gateway OpenClaw dan dapat dijangkau dari server Mattermost.
- Callback slash native diautentikasi dengan token per perintah yang dikembalikan
oleh Mattermost selama pendaftaran slash command. Jika pendaftaran gagal atau tidak ada
perintah yang diaktifkan, OpenClaw menolak callback dengan
`Unauthorized: invalid command token.`
- Untuk host callback privat/tailnet/internal, Mattermost mungkin memerlukan
`ServiceSettings.AllowedUntrustedInternalConnections` untuk menyertakan host/domain callback.
Gunakan nilai host/domain, bukan URL lengkap.
- `channels.mattermost.configWrites`: izinkan atau tolak penulisan konfigurasi yang dimulai Mattermost.
- Untuk host callback privat/tailnet/internal, Mattermost mungkin mengharuskan
`ServiceSettings.AllowedUntrustedInternalConnections` menyertakan host/domain callback.
Gunakan nilai host/domain, bukan URL penuh.
- `channels.mattermost.configWrites`: izinkan atau tolak penulisan konfigurasi yang diprakarsai Mattermost.
- `channels.mattermost.requireMention`: wajibkan `@mention` sebelum membalas di kanal.
- `channels.mattermost.groups.<channelId>.requireMention`: override gating mention per kanal (`"*"` untuk default).
- `channels.mattermost.defaultAccount` opsional mengganti pemilihan akun default saat cocok dengan id akun yang dikonfigurasi.
- `channels.mattermost.groups.<channelId>.requireMention`: penimpaan gating mention per kanal (`"*"` untuk default).
- `channels.mattermost.defaultAccount` opsional menimpa pemilihan akun default ketika cocok dengan id akun yang dikonfigurasi.
### Signal
@ -569,11 +569,11 @@ Saat perintah native Mattermost diaktifkan:
}
```
**Mode notifikasi reaksi:** `off`, `own` (bawaan), `all`, `allowlist` (dari `reactionAllowlist`).
**Mode notifikasi reaksi:** `off`, `own` (default), `all`, `allowlist` (dari `reactionAllowlist`).
- `channels.signal.account`: sematkan startup channel ke identitas akun Signal tertentu.
- `channels.signal.configWrites`: izinkan atau tolak penulisan konfigurasi yang dimulai oleh Signal.
- `channels.signal.defaultAccount` opsional menggantikan pemilihan akun bawaan ketika cocok dengan id akun yang dikonfigurasi.
- `channels.signal.account`: kaitkan startup saluran ke identitas akun Signal tertentu.
- `channels.signal.configWrites`: izinkan atau tolak penulisan konfigurasi yang dimulai dari Signal.
- `channels.signal.defaultAccount` opsional menimpa pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi.
### BlueBubbles
@ -592,10 +592,10 @@ BlueBubbles adalah jalur iMessage yang direkomendasikan (didukung Plugin, dikonf
}
```
- Jalur kunci inti yang dicakup di sini: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`.
- `channels.bluebubbles.defaultAccount` opsional menggantikan pemilihan akun bawaan ketika cocok dengan id akun yang dikonfigurasi.
- Entri `bindings[]` tingkat atas dengan `type: "acp"` dapat mengikat percakapan BlueBubbles ke sesi ACP persisten. Gunakan handle BlueBubbles atau string target (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) di `match.peer.id`. Semantik bidang bersama: [Agen ACP](/id/tools/acp-agents#channel-specific-settings).
- Konfigurasi channel BlueBubbles lengkap didokumentasikan di [BlueBubbles](/id/channels/bluebubbles).
- Jalur kunci inti yang dibahas di sini: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`.
- `channels.bluebubbles.defaultAccount` opsional menimpa pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi.
- Entri `bindings[]` tingkat atas dengan `type: "acp"` dapat mengikat percakapan BlueBubbles ke sesi ACP persisten. Gunakan handle BlueBubbles atau string target (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) di `match.peer.id`. Semantik field bersama: [Agen ACP](/id/tools/acp-agents#channel-specific-settings).
- Konfigurasi saluran BlueBubbles lengkap didokumentasikan di [BlueBubbles](/id/channels/bluebubbles).
### iMessage
@ -623,17 +623,17 @@ OpenClaw menjalankan `imsg rpc` (JSON-RPC melalui stdio). Tidak memerlukan daemo
}
```
- `channels.imessage.defaultAccount` opsional menggantikan pemilihan akun bawaan ketika cocok dengan id akun yang dikonfigurasi.
- `channels.imessage.defaultAccount` opsional menimpa pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi.
- Memerlukan Full Disk Access ke DB Messages.
- Utamakan target `chat_id:<id>`. Gunakan `imsg chats --limit 20` untuk mencantumkan chat.
- `cliPath` dapat mengarah ke wrapper SSH; atur `remoteHost` (`host` atau `user@host`) untuk pengambilan lampiran melalui SCP.
- `attachmentRoots` dan `remoteAttachmentRoots` membatasi jalur lampiran masuk (bawaan: `/Users/*/Library/Messages/Attachments`).
- SCP menggunakan pemeriksaan host-key yang ketat, jadi pastikan host key relay sudah ada di `~/.ssh/known_hosts`.
- `channels.imessage.configWrites`: izinkan atau tolak penulisan konfigurasi yang dimulai oleh iMessage.
- Entri `bindings[]` tingkat atas dengan `type: "acp"` dapat mengikat percakapan iMessage ke sesi ACP persisten. Gunakan handle yang dinormalisasi atau target chat eksplisit (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) di `match.peer.id`. Semantik bidang bersama: [Agen ACP](/id/tools/acp-agents#channel-specific-settings).
- Utamakan target `chat_id:<id>`. Gunakan `imsg chats --limit 20` untuk mencantumkan obrolan.
- `cliPath` dapat menunjuk ke wrapper SSH; tetapkan `remoteHost` (`host` atau `user@host`) untuk pengambilan lampiran SCP.
- `attachmentRoots` dan `remoteAttachmentRoots` membatasi jalur lampiran masuk (default: `/Users/*/Library/Messages/Attachments`).
- SCP menggunakan pemeriksaan host-key ketat, jadi pastikan host key relay sudah ada di `~/.ssh/known_hosts`.
- `channels.imessage.configWrites`: izinkan atau tolak penulisan konfigurasi yang dimulai dari iMessage.
- Entri `bindings[]` tingkat atas dengan `type: "acp"` dapat mengikat percakapan iMessage ke sesi ACP persisten. Gunakan handle yang dinormalisasi atau target obrolan eksplisit (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) di `match.peer.id`. Semantik field bersama: [Agen ACP](/id/tools/acp-agents#channel-specific-settings).
<Accordion title="contoh wrapper SSH iMessage">
<Accordion title="iMessage SSH wrapper example">
```bash
#!/usr/bin/env bash
@ -675,20 +675,20 @@ Matrix didukung Plugin dan dikonfigurasi di bawah `channels.matrix`.
```
- Autentikasi token menggunakan `accessToken`; autentikasi kata sandi menggunakan `userId` + `password`.
- `channels.matrix.proxy` merutekan lalu lintas HTTP Matrix melalui proksi HTTP(S) eksplisit. Akun bernama dapat menggantikannya dengan `channels.matrix.accounts.<id>.proxy`.
- `channels.matrix.network.dangerouslyAllowPrivateNetwork` mengizinkan homeserver privat/internal. `proxy` dan opt-in jaringan ini adalah kontrol independen.
- `channels.matrix.defaultAccount` memilih akun pilihan dalam setup multi-akun.
- `channels.matrix.autoJoin` secara bawaan adalah `off`, sehingga room undangan dan undangan baru bergaya DM diabaikan hingga Anda mengatur `autoJoin: "allowlist"` dengan `autoJoinAllowlist` atau `autoJoin: "always"`.
- `channels.matrix.proxy` merutekan trafik HTTP Matrix melalui proxy HTTP(S) eksplisit. Akun bernama dapat menimpanya dengan `channels.matrix.accounts.<id>.proxy`.
- `channels.matrix.network.dangerouslyAllowPrivateNetwork` mengizinkan homeserver privat/internal. `proxy` dan opt-in jaringan ini adalah kontrol terpisah.
- `channels.matrix.defaultAccount` memilih akun yang diprioritaskan dalam penyiapan multi-akun.
- `channels.matrix.autoJoin` default ke `off`, sehingga room undangan dan undangan baru bergaya DM diabaikan sampai Anda menetapkan `autoJoin: "allowlist"` dengan `autoJoinAllowlist` atau `autoJoin: "always"`.
- `channels.matrix.execApprovals`: pengiriman persetujuan exec native Matrix dan otorisasi pemberi persetujuan.
- `enabled`: `true`, `false`, atau `"auto"` (bawaan). Dalam mode auto, persetujuan exec aktif ketika pemberi persetujuan dapat di-resolve dari `approvers` atau `commands.ownerAllowFrom`.
- `approvers`: ID pengguna Matrix (misalnya `@owner:example.org`) yang diizinkan menyetujui permintaan exec.
- `agentFilter`: allowlist ID agen opsional. Abaikan untuk meneruskan persetujuan bagi semua agen.
- `enabled`: `true`, `false`, atau `"auto"` (default). Dalam mode otomatis, persetujuan exec aktif saat pemberi persetujuan dapat diselesaikan dari `approvers` atau `commands.ownerAllowFrom`.
- `approvers`: ID pengguna Matrix (mis. `@owner:example.org`) yang diizinkan menyetujui permintaan exec.
- `agentFilter`: allowlist ID agen opsional. Hilangkan untuk meneruskan persetujuan bagi semua agen.
- `sessionFilter`: pola kunci sesi opsional (substring atau regex).
- `target`: tempat mengirim prompt persetujuan. `"dm"` (bawaan), `"channel"` (room asal), atau `"both"`.
- Override per akun: `channels.matrix.accounts.<id>.execApprovals`.
- `channels.matrix.dm.sessionScope` mengontrol bagaimana DM Matrix dikelompokkan ke dalam sesi: `per-user` (bawaan) berbagi berdasarkan peer yang dirutekan, sedangkan `per-room` mengisolasi setiap room DM.
- Probe status Matrix dan lookup direktori live menggunakan kebijakan proksi yang sama dengan lalu lintas runtime.
- Konfigurasi Matrix lengkap, aturan penargetan, dan contoh setup didokumentasikan di [Matrix](/id/channels/matrix).
- `target`: tempat mengirim prompt persetujuan. `"dm"` (default), `"channel"` (room asal), atau `"both"`.
- Penimpaan per akun: `channels.matrix.accounts.<id>.execApprovals`.
- `channels.matrix.dm.sessionScope` mengontrol cara DM Matrix dikelompokkan ke dalam sesi: `per-user` (default) berbagi berdasarkan peer yang dirutekan, sedangkan `per-room` mengisolasi tiap room DM.
- Probe status Matrix dan pencarian direktori live menggunakan kebijakan proxy yang sama dengan trafik runtime.
- Konfigurasi Matrix lengkap, aturan penargetan, dan contoh penyiapan didokumentasikan di [Matrix](/id/channels/matrix).
### Microsoft Teams
@ -707,8 +707,8 @@ Microsoft Teams didukung Plugin dan dikonfigurasi di bawah `channels.msteams`.
}
```
- Jalur kunci inti yang dicakup di sini: `channels.msteams`, `channels.msteams.configWrites`.
- Konfigurasi Teams lengkap (kredensial, Webhook, kebijakan DM/grup, override per tim/per channel) didokumentasikan di [Microsoft Teams](/id/channels/msteams).
- Jalur kunci inti yang dibahas di sini: `channels.msteams`, `channels.msteams.configWrites`.
- Konfigurasi Teams lengkap (kredensial, Webhook, kebijakan DM/grup, penimpaan per tim/per saluran) didokumentasikan di [Microsoft Teams](/id/channels/msteams).
### IRC
@ -733,13 +733,13 @@ IRC didukung Plugin dan dikonfigurasi di bawah `channels.irc`.
}
```
- Jalur kunci inti yang dicakup di sini: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`.
- `channels.irc.defaultAccount` opsional menggantikan pemilihan akun bawaan ketika cocok dengan id akun yang dikonfigurasi.
- Konfigurasi channel IRC lengkap (host/port/TLS/channel/allowlist/gating mention) didokumentasikan di [IRC](/id/channels/irc).
- Jalur kunci inti yang dibahas di sini: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`.
- `channels.irc.defaultAccount` opsional menimpa pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi.
- Konfigurasi saluran IRC lengkap (host/port/TLS/saluran/allowlist/pembatasan mention) didokumentasikan di [IRC](/id/channels/irc).
### Multi-akun (semua channel)
### Multi-akun (semua saluran)
Jalankan beberapa akun per channel (masing-masing dengan `accountId` sendiri):
Jalankan beberapa akun per saluran (masing-masing dengan `accountId` sendiri):
```json5
{
@ -760,30 +760,32 @@ Jalankan beberapa akun per channel (masing-masing dengan `accountId` sendiri):
}
```
- `default` digunakan ketika `accountId` dihilangkan (CLI + routing).
- `default` digunakan saat `accountId` dihilangkan (CLI + perutean).
- Token env hanya berlaku untuk akun **default**.
- Pengaturan channel dasar berlaku untuk semua akun kecuali diganti per akun.
- Gunakan `bindings[].match.accountId` untuk merutekan setiap akun ke agen yang berbeda.
- Jika Anda menambahkan akun non-default melalui `openclaw channels add` (atau onboarding channel) saat masih menggunakan konfigurasi channel tingkat atas akun tunggal, OpenClaw terlebih dahulu mempromosikan nilai akun tunggal tingkat atas yang berlingkup akun ke dalam peta akun channel agar akun asli tetap berfungsi. Sebagian besar channel memindahkannya ke `channels.<channel>.accounts.default`; Matrix dapat mempertahankan target bernama/default yang cocok yang sudah ada.
- Binding khusus channel yang ada (tanpa `accountId`) tetap cocok dengan akun default; binding berlingkup akun tetap opsional.
- `openclaw doctor --fix` juga memperbaiki bentuk campuran dengan memindahkan nilai akun tunggal tingkat atas yang berlingkup akun ke akun yang dipromosikan yang dipilih untuk channel tersebut. Sebagian besar channel menggunakan `accounts.default`; Matrix dapat mempertahankan target bernama/default yang cocok yang sudah ada.
- Pengaturan saluran dasar berlaku untuk semua akun kecuali ditimpa per akun.
- Gunakan `bindings[].match.accountId` untuk merutekan tiap akun ke agen yang berbeda.
- Jika Anda menambahkan akun non-default melalui `openclaw channels add` (atau onboarding saluran) saat masih menggunakan konfigurasi saluran tingkat atas akun tunggal, OpenClaw terlebih dahulu mempromosikan nilai akun tunggal tingkat atas yang berlingkup akun ke peta akun saluran agar akun asli tetap berfungsi. Sebagian besar saluran memindahkannya ke `channels.<channel>.accounts.default`; Matrix dapat mempertahankan target bernama/default yang cocok jika sudah ada.
- Binding khusus saluran yang sudah ada (tanpa `accountId`) tetap mencocokkan akun default; binding berlingkup akun tetap opsional.
- `openclaw doctor --fix` juga memperbaiki bentuk campuran dengan memindahkan nilai akun tunggal tingkat atas yang berlingkup akun ke akun yang dipromosikan yang dipilih untuk saluran tersebut. Sebagian besar saluran menggunakan `accounts.default`; Matrix dapat mempertahankan target bernama/default yang cocok jika sudah ada.
### Channel Plugin lainnya
### Saluran Plugin lainnya
Banyak channel Plugin dikonfigurasi sebagai `channels.<id>` dan didokumentasikan di halaman channel khususnya (misalnya Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat, dan Twitch).
Lihat indeks channel lengkap: [Channel](/id/channels).
Banyak saluran Plugin dikonfigurasi sebagai `channels.<id>` dan didokumentasikan di halaman saluran khususnya (misalnya Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat, dan Twitch).
Lihat indeks saluran lengkap: [Saluran](/id/channels).
### Gating mention chat grup
### Pembatasan mention obrolan grup
Pesan grup secara bawaan **memerlukan mention** (mention metadata atau pola regex aman). Berlaku untuk chat grup WhatsApp, Telegram, Discord, Google Chat, dan iMessage.
Pesan grup default ke **wajib mention** (mention metadata atau pola regex aman). Berlaku untuk obrolan grup WhatsApp, Telegram, Discord, Google Chat, dan iMessage.
Balasan terlihat dikontrol secara terpisah. Room grup/channel secara bawaan menggunakan `messages.groupChat.visibleReplies: "message_tool"`: OpenClaw tetap memproses giliran, tetapi balasan final normal tetap privat dan output room yang terlihat memerlukan `message(action=send)`. Atur `"automatic"` hanya ketika Anda menginginkan perilaku lama ketika balasan normal diposting kembali ke room. Untuk menerapkan perilaku balasan terlihat khusus alat yang sama ke chat langsung juga, atur `messages.visibleReplies: "message_tool"`.
Balasan yang terlihat dikontrol secara terpisah. Room grup/saluran default ke `messages.groupChat.visibleReplies: "message_tool"`: OpenClaw tetap memproses giliran, tetapi balasan akhir normal tetap privat dan output room yang terlihat memerlukan `message(action=send)`. Tetapkan `"automatic"` hanya saat Anda menginginkan perilaku legacy di mana balasan normal diposting kembali ke room. Untuk menerapkan perilaku balasan terlihat khusus-tool yang sama ke obrolan langsung juga, tetapkan `messages.visibleReplies: "message_tool"`.
Gateway memuat ulang panas konfigurasi `messages` setelah file disimpan. Mulai ulang hanya saat pemantauan file atau pemuatan ulang konfigurasi dinonaktifkan dalam deployment.
**Jenis mention:**
- **Mention metadata**: @-mention native platform. Diabaikan dalam mode self-chat WhatsApp.
- **Pola teks**: Pola regex aman di `agents.list[].groupChat.mentionPatterns`. Pola tidak valid dan pengulangan bertingkat yang tidak aman diabaikan.
- Gating mention hanya diberlakukan ketika deteksi memungkinkan (mention native atau setidaknya satu pola).
- **Mention metadata**: @-mention platform native. Diabaikan dalam mode obrolan mandiri WhatsApp.
- **Pola teks**: Pola regex aman di `agents.list[].groupChat.mentionPatterns`. Pola tidak valid dan repetisi bersarang yang tidak aman diabaikan.
- Pembatasan mention diterapkan hanya saat deteksi memungkinkan (mention native atau setidaknya satu pola).
```json5
{
@ -800,9 +802,9 @@ Balasan terlihat dikontrol secara terpisah. Room grup/channel secara bawaan meng
}
```
`messages.groupChat.historyLimit` menetapkan bawaan global. Channel dapat menggantikannya dengan `channels.<channel>.historyLimit` (atau per akun). Atur `0` untuk menonaktifkan.
`messages.groupChat.historyLimit` menetapkan default global. Saluran dapat menimpa dengan `channels.<channel>.historyLimit` (atau per akun). Tetapkan `0` untuk menonaktifkan.
`messages.visibleReplies` adalah bawaan giliran sumber global; `messages.groupChat.visibleReplies` menggantikannya untuk giliran sumber grup/channel. Allowlist channel dan gating mention tetap menentukan apakah suatu giliran diproses.
`messages.visibleReplies` adalah default giliran sumber global; `messages.groupChat.visibleReplies` menimpanya untuk giliran sumber grup/saluran. Allowlist saluran dan pembatasan mention tetap menentukan apakah suatu giliran diproses.
#### Batas riwayat DM
@ -819,13 +821,13 @@ Balasan terlihat dikontrol secara terpisah. Room grup/channel secara bawaan meng
}
```
Resolusi: override per DM → bawaan provider → tanpa batas (semua dipertahankan).
Resolusi: penimpaan per-DM → default provider → tanpa batas (semua dipertahankan).
Didukung: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`.
#### Mode self-chat
#### Mode obrolan mandiri
Sertakan nomor Anda sendiri di `allowFrom` untuk mengaktifkan mode self-chat (mengabaikan @-mention native, hanya merespons pola teks):
Sertakan nomor Anda sendiri di `allowFrom` untuk mengaktifkan mode obrolan mandiri (mengabaikan @-mention native, hanya merespons pola teks):
```json5
{
@ -873,30 +875,30 @@ Sertakan nomor Anda sendiri di `allowFrom` untuk mengaktifkan mode self-chat (me
}
```
<Accordion title="Detail perintah">
<Accordion title="Command details">
- Blok ini mengonfigurasi permukaan perintah. Untuk katalog perintah bawaan + bundel saat ini, lihat [Perintah Slash](/id/tools/slash-commands).
- Halaman ini adalah **referensi kunci konfigurasi**, bukan katalog perintah lengkap. Perintah milik kanal/Plugin seperti QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone`, dan Talk `/voice` didokumentasikan di halaman kanal/Plugin masing-masing serta [Perintah Slash](/id/tools/slash-commands).
- Blok ini mengonfigurasi permukaan perintah. Untuk katalog perintah bawaan saat ini + yang dibundel, lihat [Perintah Slash](/id/tools/slash-commands).
- Halaman ini adalah **referensi kunci konfigurasi**, bukan katalog perintah lengkap. Perintah milik channel/Plugin seperti QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, pemasangan perangkat `/pair`, memori `/dreaming`, kontrol ponsel `/phone`, dan Talk `/voice` didokumentasikan di halaman channel/Plugin masing-masing serta [Perintah Slash](/id/tools/slash-commands).
- Perintah teks harus berupa pesan **mandiri** dengan awalan `/`.
- `native: "auto"` mengaktifkan perintah native untuk Discord/Telegram, membiarkan Slack nonaktif.
- `nativeSkills: "auto"` mengaktifkan perintah Skills native untuk Discord/Telegram, membiarkan Slack nonaktif.
- Timpa per kanal: `channels.discord.commands.native` (bool atau `"auto"`). `false` menghapus perintah yang sebelumnya terdaftar.
- Timpa pendaftaran Skills native per kanal dengan `channels.<provider>.commands.nativeSkills`.
- `nativeSkills: "auto"` mengaktifkan perintah native Skills untuk Discord/Telegram, membiarkan Slack nonaktif.
- Timpa per channel: `channels.discord.commands.native` (bool atau `"auto"`). `false` menghapus perintah yang sebelumnya terdaftar.
- Timpa pendaftaran Skills native per channel dengan `channels.<provider>.commands.nativeSkills`.
- `channels.telegram.customCommands` menambahkan entri menu bot Telegram tambahan.
- `bash: true` mengaktifkan `! <cmd>` untuk shell host. Memerlukan `tools.elevated.enabled` dan pengirim di `tools.elevated.allowFrom.<channel>`.
- `config: true` mengaktifkan `/config` (membaca/menulis `openclaw.json`). Untuk klien Gateway `chat.send`, penulisan persisten `/config set|unset` juga memerlukan `operator.admin`; `/config show` yang hanya baca tetap tersedia untuk klien operator normal dengan cakupan tulis.
- `config: true` mengaktifkan `/config` (membaca/menulis `openclaw.json`). Untuk klien `chat.send` Gateway, penulisan persisten `/config set|unset` juga memerlukan `operator.admin`; `/config show` hanya-baca tetap tersedia untuk klien operator normal dengan cakupan tulis.
- `mcp: true` mengaktifkan `/mcp` untuk konfigurasi server MCP yang dikelola OpenClaw di bawah `mcp.servers`.
- `plugins: true` mengaktifkan `/plugins` untuk penemuan Plugin, pemasangan, dan kontrol aktif/nonaktif.
- `channels.<provider>.configWrites` membatasi mutasi konfigurasi per kanal (default: true).
- Untuk kanal multi-akun, `channels.<provider>.accounts.<id>.configWrites` juga membatasi penulisan yang menargetkan akun tersebut (misalnya `/allowlist --config --account <id>` atau `/config set channels.<provider>.accounts.<id>...`).
- `restart: false` menonaktifkan `/restart` dan tindakan alat mulai ulang Gateway. Default: `true`.
- `ownerAllowFrom` adalah daftar izin pemilik eksplisit untuk perintah/alat khusus pemilik. Ini terpisah dari `allowFrom`.
- `ownerDisplay: "hash"` melakukan hash pada ID pemilik di prompt sistem. Atur `ownerDisplaySecret` untuk mengontrol hashing.
- `allowFrom` berlaku per penyedia. Jika diatur, ini menjadi **satu-satunya** sumber otorisasi (daftar izin/pemasangan kanal dan `useAccessGroups` diabaikan).
- `useAccessGroups: false` mengizinkan perintah melewati kebijakan grup akses saat `allowFrom` tidak diatur.
- `plugins: true` mengaktifkan `/plugins` untuk penemuan, instalasi, dan kontrol aktif/nonaktif Plugin.
- `channels.<provider>.configWrites` membatasi mutasi konfigurasi per channel (default: true).
- Untuk channel multi-akun, `channels.<provider>.accounts.<id>.configWrites` juga membatasi penulisan yang menargetkan akun tersebut (misalnya `/allowlist --config --account <id>` atau `/config set channels.<provider>.accounts.<id>...`).
- `restart: false` menonaktifkan `/restart` dan tindakan alat restart Gateway. Default: `true`.
- `ownerAllowFrom` adalah allowlist pemilik eksplisit untuk perintah/alat khusus pemilik. Ini terpisah dari `allowFrom`.
- `ownerDisplay: "hash"` melakukan hash id pemilik di prompt sistem. Tetapkan `ownerDisplaySecret` untuk mengontrol hashing.
- `allowFrom` berlaku per provider. Jika ditetapkan, ini adalah **satu-satunya** sumber otorisasi (allowlist/pemasangan channel dan `useAccessGroups` diabaikan).
- `useAccessGroups: false` mengizinkan perintah melewati kebijakan grup akses saat `allowFrom` tidak ditetapkan.
- Peta dokumentasi perintah:
- katalog bawaan + bundel: [Perintah Slash](/id/tools/slash-commands)
- permukaan perintah khusus kanal: [Kanal](/id/channels)
- katalog bawaan + yang dibundel: [Perintah Slash](/id/tools/slash-commands)
- permukaan perintah khusus channel: [Channel](/id/channels)
- perintah QQ Bot: [QQ Bot](/id/channels/qqbot)
- perintah pemasangan: [Pemasangan](/id/channels/pairing)
- perintah kartu LINE: [LINE](/id/channels/line)
@ -910,4 +912,4 @@ Sertakan nomor Anda sendiri di `allowFrom` untuk mengaktifkan mode self-chat (me
- [Referensi konfigurasi](/id/gateway/configuration-reference) — kunci tingkat atas
- [Konfigurasi — agen](/id/gateway/config-agents)
- [Ikhtisar kanal](/id/channels)
- [Ikhtisar channel](/id/channels)

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

@ -1,20 +1,20 @@
---
read_when:
- Menambahkan atau memodifikasi migrasi doctor
- Menambahkan atau mengubah migrasi doctor
- Memperkenalkan perubahan konfigurasi yang tidak kompatibel
sidebarTitle: Doctor
summary: 'Perintah doctor: pemeriksaan kesehatan, migrasi konfigurasi, dan langkah perbaikan'
title: Diagnostik
title: Dokter
x-i18n:
generated_at: "2026-04-30T09:48:44Z"
generated_at: "2026-04-30T16:29:00Z"
model: gpt-5.5
provider: openai
source_hash: c27b8e85eb0a577e676f0e6e205262775ff37303453e64fc1bc2adaf8b51147c
source_hash: 89150fe2b2848f1f168b42ca6b240bc0e6a0edee4f1bcad7f79d297face9c95e
source_path: gateway/doctor.md
workflow: 16
---
`openclaw doctor` adalah alat perbaikan + migrasi untuk OpenClaw. Alat ini memperbaiki konfigurasi/status yang usang, memeriksa kesehatan, dan menyediakan langkah perbaikan yang dapat ditindaklanjuti.
`openclaw doctor` adalah alat perbaikan + migrasi untuk OpenClaw. Alat ini memperbaiki config/status yang usang, memeriksa kesehatan, dan menyediakan langkah perbaikan yang dapat ditindaklanjuti.
## Mulai cepat
@ -30,7 +30,7 @@ openclaw doctor
openclaw doctor --yes
```
Terima default tanpa prompt (termasuk langkah perbaikan restart/layanan/sandbox jika berlaku).
Terima default tanpa meminta konfirmasi (termasuk langkah restart/service/perbaikan 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 khusus).
Terapkan juga perbaikan agresif (menimpa config supervisor kustom).
</Tab>
<Tab title="--non-interactive">
@ -54,7 +54,7 @@ openclaw doctor
openclaw doctor --non-interactive
```
Jalankan tanpa prompt dan hanya terapkan migrasi 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 config + pemindahan status di disk). Melewati tindakan restart/service/sandbox yang memerlukan konfirmasi manusia. Migrasi status legacy berjalan otomatis saat terdeteksi.
</Tab>
<Tab title="--deep">
@ -62,125 +62,126 @@ 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>
Jika Anda ingin meninjau perubahan sebelum menulis, buka file konfigurasi terlebih dahulu:
Jika Anda ingin meninjau perubahan sebelum menulis, buka file config terlebih dahulu:
```bash
cat ~/.openclaw/openclaw.json
```
## Apa yang dilakukan (ringkasan)
## Yang dilakukannya (ringkasan)
<AccordionGroup>
<Accordion title="Kesehatan, UI, dan pembaruan">
<Accordion title="Health, UI, and updates">
- Pembaruan pre-flight opsional untuk instalasi git (hanya interaktif).
- Pemeriksaan kesegaran protokol UI (membangun ulang UI Kontrol saat skema protokol lebih baru).
- Pemeriksaan kesegaran protokol UI (membangun ulang Control UI ketika 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 field datar lama `talk.*` ke `talk.provider` + `talk.providers.<provider>`.
- Pemeriksaan migrasi browser untuk konfigurasi ekstensi Chrome lama dan kesiapan Chrome MCP.
<Accordion title="Config and migrations">
- Normalisasi config untuk nilai legacy.
- Migrasi config Talk dari field datar legacy `talk.*` ke dalam `talk.provider` + `talk.providers.<provider>`.
- Pemeriksaan migrasi browser untuk config ekstensi Chrome legacy 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 OAuth TLS untuk profil OAuth OpenAI Codex.
- 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`, field delivery/payload tingkat atas, payload `provider`, job fallback webhook `notify: true` sederhana).
- Migrasi runtime-policy 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.
- Pemeriksaan prasyarat OAuth TLS untuk profil OpenAI Codex OAuth.
- Migrasi status legacy di disk (sessions/direktori agent/auth WhatsApp).
- Migrasi kunci kontrak manifes plugin legacy (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
- Migrasi penyimpanan cron legacy (`jobId`, `schedule.cron`, field delivery/payload tingkat atas, payload `provider`, pekerjaan fallback Webhook sederhana `notify: true`).
- Migrasi runtime-policy agent legacy ke `agents.defaults.agentRuntime` dan `agents.list[].agentRuntime`.
- Pembersihan config plugin usang saat plugin diaktifkan; ketika `plugins.enabled=false`, referensi plugin usang diperlakukan sebagai config containment inert dan dipertahankan.
</Accordion>
<Accordion title="Status dan integritas">
- 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.
- 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.
<Accordion title="State and integrity">
- Inspeksi file lock session dan pembersihan lock usang.
- Perbaikan transkrip session untuk cabang prompt-rewrite duplikat yang dibuat oleh build 2026.4.24 yang terdampak.
- Deteksi tombstone restart-recovery subagent yang macet, dengan dukungan `--fix` untuk membersihkan flag pemulihan aborted yang usang agar startup tidak terus memperlakukan child sebagai restart-aborted.
- Pemeriksaan integritas status dan izin (sessions, transkrip, direktori status).
- Pemeriksaan izin file config (chmod 600) saat berjalan lokal.
- Kesehatan auth model: memeriksa kedaluwarsa OAuth, dapat menyegarkan token yang hampir kedaluwarsa, dan melaporkan status cooldown/dinonaktifkan auth-profile.
- Deteksi direktori workspace tambahan (`~/openclaw`).
</Accordion>
<Accordion title="Gateway, layanan, dan supervisor">
<Accordion title="Gateway, services, and supervisors">
- Perbaikan image sandbox saat sandboxing diaktifkan.
- Migrasi layanan 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).
- Audit konfigurasi supervisor (launchd/systemd/schtasks) dengan perbaikan opsional.
- Pembersihan lingkungan proxy tersemat untuk layanan Gateway yang menangkap nilai shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` selama instalasi atau pembaruan.
- Migrasi service legacy dan deteksi Gateway tambahan.
- Migrasi status legacy channel Matrix (dalam mode `--fix` / `--repair`).
- Pemeriksaan runtime Gateway (service terpasang tetapi tidak berjalan; label launchd yang di-cache).
- Peringatan status channel (diprobe dari Gateway yang sedang berjalan).
- Audit config supervisor (launchd/systemd/schtasks) dengan perbaikan opsional.
- Pembersihan environment proxy tertanam untuk service Gateway yang menangkap nilai shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` saat instalasi atau pembaruan.
- Pemeriksaan praktik terbaik runtime Gateway (Node vs Bun, path version-manager).
- Diagnostik benturan port Gateway (default `18789`).
- Diagnostik tabrakan port Gateway (default `18789`).
</Accordion>
<Accordion title="Autentikasi, keamanan, dan pairing">
<Accordion title="Auth, security, and 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 token SecretRef).
- Deteksi masalah pairing perangkat (permintaan pairing pertama kali yang tertunda, peningkatan peran/cakupan yang tertunda, drift cache device-token lokal yang usang, dan drift autentikasi catatan paired).
- Pemeriksaan auth Gateway untuk mode token lokal (menawarkan pembuatan token saat tidak ada sumber token; tidak menimpa config token SecretRef).
- Deteksi masalah pairing perangkat (permintaan pair pertama kali yang tertunda, peningkatan role/scope yang tertunda, drift cache device-token lokal usang, dan drift auth catatan paired).
</Accordion>
<Accordion title="Workspace dan shell">
- Pemeriksaan systemd linger di Linux.
- Pemeriksaan ukuran file bootstrap workspace (peringatan terpotong/hampir batas untuk file konteks).
- Pemeriksaan status shell completion dan instalasi/peningkatan otomatis.
- Pemeriksaan kesiapan penyedia embedding pencarian memori (model lokal, kunci API jarak jauh, atau biner QMD).
- Pemeriksaan instalasi sumber (ketidaksesuaian workspace pnpm, aset UI hilang, biner tsx hilang).
- Menulis konfigurasi yang diperbarui + metadata wizard.
<Accordion title="Workspace and shell">
- Pemeriksaan linger systemd di Linux.
- Pemeriksaan ukuran file bootstrap workspace (peringatan pemotongan/hampir batas untuk file konteks).
- Pemeriksaan status shell completion dan instalasi/upgrade otomatis.
- Pemeriksaan kesiapan penyedia embedding pencarian memory (model lokal, kunci API remote, atau biner QMD).
- Pemeriksaan instalasi source (ketidakcocokan workspace pnpm, aset UI hilang, biner tsx hilang).
- Menulis config yang diperbarui + metadata wizard.
</Accordion>
</AccordionGroup>
## Backfill dan reset UI Dreams
Adegan Dreams UI Kontrol menyertakan tindakan **Backfill**, **Reset**, dan **Bersihkan Grounded** untuk alur kerja dreaming berbasis grounding. Tindakan ini menggunakan metode RPC bergaya Gateway doctor, tetapi tindakan ini **bukan** bagian dari perbaikan/migrasi CLI `openclaw doctor`.
Scene Dreams Control UI menyertakan 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`.
Yang dilakukan:
- **Backfill** memindai file historis `memory/YYYY-MM-DD.md` di workspace aktif, menjalankan pass diary REM berbasis grounding, dan menulis entri backfill yang dapat dibalik ke `DREAMS.md`.
- **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 bertanda tersebut dari `DREAMS.md`.
- **Bersihkan Grounded** hanya menghapus entri jangka pendek khusus grounded yang sudah di-stage, yang berasal dari replay historis dan belum mengakumulasi recall live atau dukungan harian.
- **Clear Grounded** hanya menghapus entri jangka pendek staged khusus grounded yang berasal dari replay historis dan belum mengumpulkan recall live atau dukungan harian.
Yang **tidak** dilakukan dengan sendirinya:
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 menjalankan jalur CLI staging secara eksplisit terlebih dahulu
- tindakan ini tidak mengedit `MEMORY.md`
- tindakan ini tidak menjalankan migrasi doctor penuh
- tindakan ini tidak otomatis men-stage kandidat grounded ke penyimpanan promosi jangka pendek live kecuali Anda secara eksplisit menjalankan path CLI staged terlebih dahulu
Jika Anda ingin replay historis berbasis grounding memengaruhi lane promosi mendalam normal, gunakan alur CLI sebagai gantinya:
Jika Anda ingin replay historis grounded memengaruhi jalur promosi deep normal, gunakan alur CLI sebagai gantinya:
```bash
openclaw memory rem-backfill --path ./memory --stage-short-term
```
Itu men-stage kandidat durable berbasis grounding ke penyimpanan dreaming jangka pendek sambil tetap menjadikan `DREAMS.md` sebagai permukaan peninjauan.
Itu men-stage kandidat durable grounded ke penyimpanan dreaming jangka pendek sambil mempertahankan `DREAMS.md` sebagai permukaan peninjauan.
## Perilaku detail dan alasan
## Perilaku dan alasan terperinci
<AccordionGroup>
<Accordion title="0. Pembaruan opsional (instalasi git)">
Jika ini adalah git checkout dan doctor berjalan secara interaktif, doctor menawarkan pembaruan (fetch/rebase/build) sebelum menjalankan doctor.
<Accordion title="0. Optional update (git installs)">
Jika ini adalah checkout git dan doctor berjalan secara interaktif, ia 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 menormalisasinya ke skema saat ini.
<Accordion title="1. Config normalization">
Jika config berisi bentuk nilai legacy (misalnya `messages.ackReaction` tanpa override khusus channel), doctor menormalisasikannya ke skema saat ini.
Itu mencakup field 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 peta penyedia.
Itu mencakup field datar Talk legacy. Config 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.
</Accordion>
<Accordion title="2. Migrasi kunci konfigurasi lama">
Saat konfigurasi berisi kunci yang sudah tidak digunakan, perintah lain menolak berjalan dan meminta Anda menjalankan `openclaw doctor`.
<Accordion title="2. Legacy config key migrations">
Ketika config berisi kunci yang sudah tidak digunakan, perintah lain menolak berjalan dan meminta Anda menjalankan `openclaw doctor`.
Doctor akan:
- Menjelaskan kunci lama mana yang ditemukan.
- Menjelaskan kunci legacy mana yang ditemukan.
- 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 job Cron ditangani oleh `openclaw doctor --fix`.
Gateway juga menjalankan otomatis migrasi doctor saat startup ketika mendeteksi format config legacy, sehingga config usang diperbaiki tanpa intervensi manual. Migrasi penyimpanan pekerjaan Cron ditangani oleh `openclaw doctor --fix`.
Migrasi saat ini:
@ -191,7 +192,7 @@ Itu men-stage kandidat durable berbasis grounding ke penyimpanan dreaming jangka
- `routing.queue` → `messages.queue`
- `routing.bindings` → `bindings` tingkat atas
- `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default`
- `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` lama → `talk.provider` + `talk.providers.<provider>`
- legacy `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.<provider>`
- `routing.agentToAgent` → `tools.agentToAgent`
- `routing.transcribeAudio` → `tools.media.audio.models`
- `messages.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `messages.tts.providers.<provider>`
@ -205,247 +206,247 @@ Itu men-stage kandidat durable berbasis grounding ke penyimpanan dreaming jangka
- `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 yang tertinggal, pindahkan nilai bercakupan akun tersebut ke akun yang dipromosikan dan dipilih untuk channel itu (`accounts.default` untuk sebagian besar channel; Matrix dapat mempertahankan target bernama/default yang cocok jika sudah ada)
- Untuk channel dengan `accounts` bernama tetapi masih memiliki nilai channel tingkat atas akun tunggal yang tertinggal, pindahkan nilai berlingkup akun tersebut ke akun promoted yang dipilih untuk channel itu (`accounts.default` untuk sebagian besar channel; Matrix dapat mempertahankan target bernama/default yang cocok yang sudah ada)
- `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 timeout penyedia/model yang lambat
- hapus `agents.defaults.llm`; gunakan `models.providers.<id>.timeoutSeconds` untuk timeout penyedia/model lambat
- `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
- `browser.profiles.*.driver: "extension"` → `"existing-session"`
- hapus `browser.relayBindHost` (pengaturan relay ekstensi lama)
- `models.providers.*.api: "openai"` lama → `"openai-completions"` (startup Gateway juga melewati penyedia yang `api`-nya disetel ke nilai enum masa depan atau tidak dikenal, bukan gagal tertutup)
- hapus `browser.relayBindHost` (pengaturan relay ekstensi legacy)
- legacy `models.providers.*.api: "openai"` → `"openai-completions"` (startup Gateway juga melewati penyedia yang `api`-nya disetel ke nilai enum masa depan atau tidak dikenal, alih-alih gagal tertutup)
Peringatan doctor juga mencakup panduan default akun untuk channel multi-akun:
- Jika dua atau lebih entri `channels.<channel>.accounts` dikonfigurasi tanpa `channels.<channel>.defaultAccount` atau `accounts.default`, doctor memperingatkan bahwa routing 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.
- Jika `channels.<channel>.defaultAccount` diatur ke ID akun yang tidak dikenal, doctor memperingatkan dan mencantumkan ID akun yang dikonfigurasi.
</Accordion>
<Accordion title="2b. Penimpaan penyedia OpenCode">
Jika Anda menambahkan `models.providers.opencode`, `opencode-zen`, atau `opencode-go` secara manual, itu menimpa katalog OpenCode bawaan dari `@mariozechner/pi-ai`. Itu dapat memaksa model ke API yang salah atau mengosongkan biaya. Doctor memperingatkan agar Anda dapat menghapus penimpaan dan memulihkan perutean API per model + biaya.
<Accordion title="2b. Penggantian penyedia 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 ke API yang salah atau menihilkan biaya. Doctor memperingatkan agar Anda dapat menghapus penggantian tersebut dan memulihkan routing API + biaya per model.
</Accordion>
<Accordion title="2c. Migrasi peramban dan kesiapan Chrome MCP">
Jika konfigurasi peramban Anda masih mengarah ke jalur ekstensi Chrome yang telah dihapus, doctor menormalkannya ke model lampiran Chrome MCP host-lokal saat ini:
<Accordion title="2c. Migrasi browser dan kesiapan Chrome MCP">
Jika konfigurasi browser Anda masih menunjuk ke jalur ekstensi Chrome yang telah 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 host-lokal saat Anda menggunakan `defaultProfile: "user"` atau profil `existing-session` yang dikonfigurasi:
- memeriksa apakah Google Chrome terpasang di host yang sama untuk profil koneksi otomatis default
- memeriksa versi Chrome yang terdeteksi dan memperingatkan jika versinya di bawah Chrome 144
- mengingatkan Anda untuk mengaktifkan debugging jarak jauh di halaman inspeksi peramban (misalnya `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`, atau `edge://inspect/#remote-debugging`)
- memeriksa apakah Google Chrome terinstal di host yang sama untuk profil auto-connect default
- memeriksa versi Chrome yang terdeteksi dan memperingatkan saat 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 host-lokal masih memerlukan:
Doctor tidak dapat mengaktifkan pengaturan sisi Chrome untuk Anda. Chrome MCP host-lokal tetap memerlukan:
- peramban berbasis Chromium 144+ pada host gateway/node
- peramban berjalan secara lokal
- debugging jarak jauh diaktifkan di peramban tersebut
- menyetujui prompt persetujuan lampiran pertama di peramban
- browser berbasis Chromium 144+ pada host gateway/node
- browser berjalan secara lokal
- debugging jarak jauh diaktifkan di browser tersebut
- menyetujui prompt persetujuan attach pertama di browser
Kesiapan di sini hanya tentang prasyarat lampiran lokal. Existing-session mempertahankan batas rute Chrome MCP saat ini; rute lanjutan seperti `responsebody`, ekspor PDF, intersepsi unduhan, dan tindakan batch masih memerlukan peramban 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 tetap memerlukan browser terkelola atau profil CDP mentah.
Pemeriksaan ini **tidak** berlaku untuk Docker, sandbox, remote-browser, atau alur headless lainnya. Semua itu tetap menggunakan CDP mentah.
</Accordion>
<Accordion title="2d. Prasyarat OAuth TLS">
<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 yang ditandatangani sendiri), doctor mencetak panduan perbaikan khusus platform. Di macOS dengan Node dari Homebrew, perbaikannya biasanya `brew postinstall ca-certificates`. Dengan `--deep`, pemeriksaan berjalan meskipun gateway sehat.
</Accordion>
<Accordion title="2e. Penimpaan penyedia OAuth Codex">
Jika sebelumnya Anda menambahkan pengaturan transport OpenAI lama di bawah `models.providers.openai-codex`, pengaturan tersebut dapat menutupi jalur penyedia OAuth Codex bawaan yang digunakan rilis yang lebih baru secara otomatis. Doctor memperingatkan saat melihat pengaturan transport lama tersebut bersama OAuth Codex agar Anda dapat menghapus atau menulis ulang penimpaan transport yang usang dan mendapatkan kembali perilaku perutean/fallback bawaan. Proxy kustom dan penimpaan khusus header tetap didukung dan tidak memicu peringatan ini.
<Accordion title="2e. Penggantian penyedia OAuth Codex">
Jika sebelumnya Anda menambahkan pengaturan transport OpenAI lama di bawah `models.providers.openai-codex`, pengaturan itu dapat menutupi jalur penyedia 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 penggantian transport yang usang dan mendapatkan kembali perilaku routing/fallback bawaan. Proxy kustom dan penggantian hanya-header tetap didukung dan tidak memicu peringatan ini.
</Accordion>
<Accordion title="2f. Peringatan rute Plugin Codex">
Saat Plugin Codex bawaan diaktifkan, doctor juga memeriksa apakah ref 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 server aplikasi Codex native. Doctor memperingatkan dan menunjuk ke bentuk server aplikasi 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 primer `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`.
Doctor tidak memperbaiki ini secara otomatis karena kedua rute valid:
- `openai-codex/*` + PI berarti "gunakan autentikasi OAuth/langganan Codex melalui runner OpenClaw normal."
- `openai/*` + `runtime: "codex"` berarti "jalankan giliran tersemat melalui server aplikasi Codex native."
- `/codex ...` berarti "kendalikan atau ikat percakapan Codex native dari chat."
- `openai/*` + `runtime: "codex"` berarti "jalankan turn tertanam melalui app-server Codex native."
- `/codex ...` berarti "kontrol atau ikat percakapan Codex native dari chat."
- `/acp ...` atau `runtime: "acp"` berarti "gunakan adaptor ACP/acpx eksternal."
Jika peringatan muncul, pilih rute yang Anda maksud dan edit konfigurasi secara manual. Biarkan peringatan apa adanya saat OAuth Codex PI memang disengaja.
Jika peringatan muncul, pilih rute yang Anda maksud dan edit konfigurasi secara manual. Biarkan peringatan apa adanya saat PI Codex OAuth memang disengaja.
</Accordion>
<Accordion title="3. Migrasi status lama (tata letak disk)">
<Accordion title="3. Migrasi state lama (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 agen:
- dari `~/.openclaw/agent/` ke `~/.openclaw/agents/<agentId>/agent/`
- Status autentikasi WhatsApp (Baileys):
- State autentikasi WhatsApp (Baileys):
- dari `~/.openclaw/credentials/*.json` lama (kecuali `oauth.json`)
- ke `~/.openclaw/credentials/whatsapp/<accountId>/...` (id akun default: `default`)
Migrasi ini bersifat upaya terbaik dan idempoten; doctor akan memunculkan peringatan saat meninggalkan folder lama apa pun sebagai cadangan. Gateway/CLI juga memigrasikan otomatis sesi lama + direktori agen saat startup sehingga riwayat/autentikasi/model masuk ke jalur per agen tanpa menjalankan doctor secara manual. Autentikasi WhatsApp sengaja hanya dimigrasikan melalui `openclaw doctor`. Normalisasi talk provider/provider-map kini membandingkan berdasarkan kesetaraan struktural, sehingga diff yang hanya berupa urutan kunci tidak lagi memicu perubahan `doctor --fix` tanpa operasi secara berulang.
Migrasi ini bersifat best-effort dan idempoten; doctor akan memunculkan peringatan saat meninggalkan folder lama sebagai cadangan. Gateway/CLI juga melakukan auto-migrasi sesi lama + 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 talk/provider-map kini membandingkan berdasarkan kesetaraan struktural, sehingga perbedaan yang hanya berupa urutan kunci tidak lagi memicu perubahan no-op `doctor --fix` berulang.
</Accordion>
<Accordion title="3a. Migrasi manifes Plugin lama">
Doctor memindai semua manifes Plugin terpasang untuk mencari kunci capability tingkat atas yang tidak digunakan lagi (`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 lama dihapus tanpa menduplikasi data.
<Accordion title="3a. Migrasi manifes plugin lama">
Doctor memindai semua manifes plugin yang terinstal untuk kunci capability tingkat atas yang sudah tidak digunakan (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Saat 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 lama dihapus tanpa menduplikasi data.
</Accordion>
<Accordion title="3b. Migrasi penyimpanan cron lama">
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.
Doctor juga memeriksa penyimpanan job cron (`~/.openclaw/cron/jobs.json` secara default, atau `cron.store` saat diganti) untuk bentuk job lama yang masih diterima scheduler demi kompatibilitas.
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`
- field delivery tingkat atas (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
- alias delivery payload `provider` → `delivery.channel` eksplisit
- job fallback webhook `notify: true` lama sederhana → `delivery.mode="webhook"` eksplisit dengan `delivery.to=cron.webhook`
Doctor hanya memigrasikan otomatis job `notify: true` saat dapat melakukannya tanpa mengubah perilaku. Jika sebuah job menggabungkan fallback notify lama dengan mode pengiriman non-webhook yang sudah ada, doctor memperingatkan dan membiarkan job tersebut untuk ditinjau manual.
Doctor hanya melakukan auto-migrasi job `notify: true` saat dapat melakukannya tanpa mengubah perilaku. Jika sebuah job menggabungkan fallback notify lama dengan mode delivery non-webhook yang sudah ada, doctor memperingatkan dan membiarkan job tersebut untuk ditinjau manual.
</Accordion>
<Accordion title="3c. Pembersihan kunci sesi">
Doctor memindai setiap direktori sesi agen untuk file write-lock 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 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`.
<Accordion title="3c. Pembersihan lock sesi">
Doctor memindai setiap direktori sesi agen untuk file write-lock usang — file yang tertinggal saat sesi keluar secara abnormal. Untuk setiap file lock yang ditemukan, doctor melaporkan: jalur, PID, apakah PID masih hidup, usia lock, dan apakah dianggap usang (PID mati atau lebih lama dari 30 menit). Dalam mode `--fix` / `--repair`, doctor menghapus file lock usang secara otomatis; jika tidak, doctor mencetak catatan dan menginstruksikan Anda untuk menjalankan ulang dengan `--fix`.
</Accordion>
<Accordion title="3d. Perbaikan cabang transkrip sesi">
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 plus sibling aktif yang berisi prompt pengguna terlihat yang sama. Dalam mode `--fix` / `--repair`, doctor mencadangkan setiap file terdampak di sebelah aslinya dan menulis ulang transkrip ke cabang aktif sehingga pembaca riwayat dan memori gateway tidak lagi melihat giliran duplikat.
Doctor memindai file JSONL sesi agen untuk bentuk cabang terduplikasi yang dibuat oleh bug penulisan ulang transkrip prompt 2026.4.24: turn pengguna yang ditinggalkan dengan konteks runtime internal OpenClaw plus sibling 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 turn duplikat.
</Accordion>
<Accordion title="4. Pemeriksaan integritas status (persistensi sesi, perutean, dan keselamatan)">
Direktori status adalah batang otak operasional. Jika hilang, Anda kehilangan sesi, kredensial, log, dan konfigurasi (kecuali Anda memiliki cadangan di tempat lain).
<Accordion title="4. Pemeriksaan integritas state (persistensi sesi, routing, dan keamanan)">
Direktori state adalah pusat 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 untuk memperbaiki izin (dan memunculkan petunjuk `chown` saat ketidakcocokan pemilik/grup terdeteksi).
- **Direktori status tersinkron cloud macOS**: memperingatkan saat status diselesaikan 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 saat status diselesaikan 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 state hilang**: memperingatkan tentang kehilangan state yang katastrofik, meminta untuk membuat ulang direktori, dan mengingatkan Anda bahwa data yang hilang tidak dapat dipulihkan.
- **Izin direktori state**: memverifikasi kemampuan tulis; menawarkan untuk memperbaiki izin (dan memunculkan petunjuk `chown` saat ketidakcocokan owner/group terdeteksi).
- **Direktori state tersinkron cloud macOS**: memperingatkan saat state berada 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 lock/sinkronisasi.
- **Direktori state SD atau eMMC Linux**: memperingatkan saat state mengarah 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 kehilangan file transkrip.
- **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 terpisah 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 grup/dunia dan menawarkan untuk memperketat ke `600`.
- **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 state**: memperingatkan saat beberapa folder `~/.openclaw` ada di beberapa 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 (state berada di sana).
- **Izin file konfigurasi**: memperingatkan jika `~/.openclaw/openclaw.json` dapat dibaca oleh group/world 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.
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 perlu dijalankan.
Saat penyegaran OAuth gagal permanen (misalnya `refresh_token_reused`, `invalid_grant`, atau penyedia memberi tahu Anda untuk masuk lagi), doctor melaporkan bahwa autentikasi ulang diperlukan dan mencetak perintah persis `openclaw models auth login --provider ...` yang harus dijalankan.
Doctor juga melaporkan profil autentikasi yang sementara tidak dapat digunakan karena:
- cooldown singkat (batas laju/timeout/kegagalan autentikasi)
- penonaktifan yang lebih lama (kegagalan penagihan/kredit)
- penonaktifan lebih lama (kegagalan penagihan/kredit)
</Accordion>
<Accordion title="6. Validasi model hooks">
Jika `hooks.gmail.model` disetel, doctor memvalidasi referensi model terhadap katalog dan allowlist serta memperingatkan saat tidak dapat diselesaikan atau tidak diizinkan.
Jika `hooks.gmail.model` disetel, doctor memvalidasi referensi model terhadap katalog dan allowlist serta memperingatkan ketika referensi tersebut tidak dapat di-resolve 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.
Saat sandboxing diaktifkan, doctor memeriksa image Docker dan menawarkan untuk membangun atau beralih ke nama lama jika image saat ini tidak ada.
</Accordion>
<Accordion title="7b. Dependensi runtime Plugin bawaan">
Doctor memverifikasi dependensi runtime hanya untuk Plugin bawaan yang aktif dalam konfigurasi saat ini atau diaktifkan oleh default manifes bawaannya, misalnya `plugins.entries.discord.enabled: true`, `channels.discord.enabled: true` lama, `models.providers.*` / ref model agen yang dikonfigurasi, atau Plugin bawaan yang diaktifkan default tanpa kepemilikan penyedia. Jika ada yang hilang, doctor melaporkan paket dan memasangnya dalam mode `openclaw doctor --fix` / `openclaw doctor --repair`. Plugin eksternal tetap menggunakan `openclaw plugins install` / `openclaw plugins update`; doctor tidak memasang dependensi untuk jalur Plugin arbitrer.
Doctor memverifikasi dependensi runtime hanya untuk Plugin bawaan yang aktif dalam config saat ini atau diaktifkan oleh default manifest bawaannya, misalnya `plugins.entries.discord.enabled: true`, legacy `channels.discord.enabled: true`, `models.providers.*` / referensi model agen yang dikonfigurasi, atau Plugin bawaan yang default-nya aktif tanpa kepemilikan provider. Jika ada yang hilang, doctor melaporkan paketnya dan menginstalnya dalam mode `openclaw doctor --fix` / `openclaw doctor --repair`. Plugin eksternal tetap menggunakan `openclaw plugins install` / `openclaw plugins update`; doctor tidak menginstal dependensi untuk path Plugin arbitrer.
Selama perbaikan doctor, pemasangan npm dependensi runtime bawaan melaporkan progres spinner dalam sesi TTY dan progres baris berkala dalam keluaran berpipa/headless. Gateway dan CLI lokal juga dapat memperbaiki dependensi runtime Plugin bawaan yang aktif sesuai permintaan sebelum mengimpor Plugin bawaan. Pemasangan ini dibatasi ke root pemasangan runtime Plugin, berjalan dengan skrip dinonaktifkan, tidak menulis package lock, dan dilindungi oleh kunci root pemasangan agar proses mulai CLI atau Gateway yang bersamaan tidak memutasi pohon `node_modules` yang sama pada saat yang sama.
Selama perbaikan doctor, instalasi npm dependensi runtime bawaan melaporkan progres spinner dalam sesi TTY dan progres baris berkala dalam output piped/headless. Gateway dan CLI lokal juga dapat memperbaiki dependensi runtime Plugin bawaan yang aktif sesuai permintaan sebelum mengimpor Plugin bawaan. Instalasi ini dibatasi pada root instal runtime Plugin, dijalankan dengan skrip dinonaktifkan, tidak menulis package lock, dan dijaga oleh lock root instal sehingga start CLI atau Gateway bersamaan tidak memutasi tree `node_modules` yang sama pada waktu yang sama.
</Accordion>
<Accordion title="8. Migrasi layanan Gateway dan petunjuk pembersihan">
Doctor mendeteksi layanan gateway lama (launchd/systemd/schtasks) dan menawarkan untuk menghapusnya serta memasang layanan OpenClaw menggunakan port gateway saat ini. Doctor juga dapat memindai layanan tambahan yang mirip gateway dan mencetak petunjuk pembersihan. Layanan gateway OpenClaw yang diberi nama profil dianggap kelas utama dan tidak ditandai sebagai "ekstra."
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 mirip gateway tambahan dan mencetak petunjuk pembersihan. Layanan gateway OpenClaw bernama profil dianggap kelas utama dan tidak ditandai sebagai "tambahan."
Di Linux, jika layanan gateway tingkat pengguna tidak ada tetapi layanan gateway OpenClaw tingkat sistem ada, doctor tidak memasang layanan tingkat pengguna kedua secara otomatis. Periksa dengan `openclaw gateway status --deep` atau `openclaw doctor --deep`, lalu hapus duplikatnya atau tetapkan `OPENCLAW_SERVICE_REPAIR_POLICY=external` ketika supervisor sistem memiliki lifecycle gateway.
Di Linux, jika layanan gateway tingkat pengguna tidak ada tetapi layanan gateway OpenClaw tingkat sistem ada, doctor tidak otomatis menginstal layanan tingkat pengguna kedua. Periksa dengan `openclaw gateway status --deep` atau `openclaw doctor --deep`, lalu hapus duplikatnya atau setel `OPENCLAW_SERVICE_REPAIR_POLICY=external` saat supervisor sistem memiliki siklus hidup gateway.
</Accordion>
<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 best-effort: 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.
Saat akun channel Matrix memiliki migrasi status lama yang tertunda atau dapat ditindaklanjuti, doctor (dalam mode `--fix` / `--repair`) membuat snapshot pra-migrasi lalu menjalankan langkah migrasi best-effort: migrasi status Matrix lama dan persiapan status terenkripsi lama. Kedua langkah bersifat non-fatal; error dicatat dan startup berlanjut. Dalam mode read-only (`openclaw doctor` tanpa `--fix`) pemeriksaan ini dilewati sepenuhnya.
</Accordion>
<Accordion title="8c. Penyandingan perangkat dan pergeseran auth">
Doctor kini memeriksa status penyandingan perangkat sebagai bagian dari pemeriksaan kesehatan normal.
<Accordion title="8c. Pairing perangkat dan drift autentikasi">
Doctor sekarang memeriksa status pairing perangkat sebagai bagian dari health pass normal.
Yang dilaporkan:
- permintaan penyandingan pertama kali yang tertunda
- peningkatan peran yang tertunda untuk perangkat yang sudah tersanding
- peningkatan cakupan yang tertunda untuk perangkat yang sudah tersanding
- perbaikan ketidakcocokan kunci publik ketika id perangkat masih cocok tetapi identitas perangkat tidak lagi cocok dengan catatan yang disetujui
- catatan tersanding yang tidak memiliki token aktif untuk peran yang disetujui
- token tersanding yang cakupannya bergeser di luar baseline penyandingan yang disetujui
- entri token perangkat cache lokal untuk mesin saat ini yang lebih lama dari rotasi token sisi gateway atau membawa metadata cakupan yang usang
- permintaan pairing pertama kali yang tertunda
- upgrade peran tertunda untuk perangkat yang sudah dipairing
- upgrade scope tertunda untuk perangkat yang sudah dipairing
- perbaikan ketidakcocokan kunci publik ketika id perangkat masih cocok tetapi identitas perangkat tidak lagi cocok dengan record yang disetujui
- record pairing yang tidak memiliki token aktif untuk peran yang disetujui
- token pairing yang scope-nya bergeser keluar dari baseline pairing yang disetujui
- entri token perangkat cache lokal untuk mesin saat ini yang mendahului rotasi token sisi gateway atau membawa metadata scope usang
Doctor tidak menyetujui otomatis permintaan penyandingan atau merotasi otomatis token perangkat. Doctor mencetak langkah berikutnya yang tepat sebagai gantinya:
Doctor tidak menyetujui otomatis permintaan pairing atau merotasi otomatis token perangkat. Doctor 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>`
- hapus dan setujui ulang record usang dengan `openclaw devices remove <deviceId>`
Ini menutup celah umum "sudah tersanding tetapi masih mendapat pairing required": doctor kini membedakan penyandingan pertama kali dari peningkatan peran/cakupan yang tertunda dan dari pergeseran token/identitas perangkat yang usang.
Ini menutup celah umum "sudah dipairing tetapi masih mendapatkan pairing required": doctor sekarang membedakan pairing pertama kali dari upgrade peran/scope tertunda dan dari drift token/identitas perangkat yang usang.
</Accordion>
<Accordion title="9. Peringatan keamanan">
Doctor mengeluarkan peringatan ketika penyedia terbuka untuk DM tanpa allowlist, atau ketika kebijakan dikonfigurasi dengan cara yang berbahaya.
Doctor memunculkan peringatan saat provider terbuka untuk DM tanpa allowlist, atau saat 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 hidup setelah logout.
</Accordion>
<Accordion title="11. Status workspace (skills, plugin, dan direktori lama)">
<Accordion title="11. Status workspace (skills, Plugin, dan direktori legacy)">
Doctor mencetak ringkasan status workspace untuk agen default:
- **Status Skills**: menghitung skills yang memenuhi syarat, persyaratannya hilang, dan diblokir allowlist.
- **Direktori workspace lama**: memperingatkan ketika `~/openclaw` atau direktori workspace lama lainnya ada berdampingan dengan workspace saat ini.
- **Status Plugin**: menghitung plugin yang diaktifkan/dinonaktifkan/bermasalah; mencantumkan ID plugin untuk kesalahan apa pun; melaporkan kapabilitas plugin bundel.
- **Peringatan kompatibilitas Plugin**: menandai plugin yang memiliki masalah kompatibilitas dengan runtime saat ini.
- **Diagnostik Plugin**: menampilkan peringatan atau kesalahan waktu muat apa pun yang dikeluarkan oleh registry plugin.
- **Status Skills**: menghitung skill yang eligible, missing-requirements, dan diblokir allowlist.
- **Direktori workspace legacy**: memperingatkan saat `~/openclaw` atau direktori workspace legacy lain ada berdampingan dengan workspace saat ini.
- **Status Plugin**: menghitung Plugin yang diaktifkan/dinonaktifkan/error; mencantumkan ID Plugin untuk setiap error; melaporkan kapabilitas Plugin bundle.
- **Peringatan kompatibilitas Plugin**: menandai Plugin yang memiliki masalah kompatibilitas dengan runtime saat ini.
- **Diagnostik Plugin**: menampilkan peringatan atau error waktu muat apa pun yang dipancarkan oleh registry Plugin.
</Accordion>
<Accordion title="11b. Ukuran file bootstrap">
Doctor memeriksa apakah file bootstrap workspace (misalnya `AGENTS.md`, `CLAUDE.md`, atau file konteks tersuntik lainnya) mendekati atau melebihi anggaran karakter yang dikonfigurasi. Doctor melaporkan jumlah karakter mentah vs. tersuntik per file, persentase pemotongan, penyebab pemotongan (`max/file` atau `max/total`), dan total karakter tersuntik sebagai fraksi dari total anggaran. Ketika file dipotong atau mendekati batas, doctor mencetak tips untuk menyetel `agents.defaults.bootstrapMaxChars` dan `agents.defaults.bootstrapTotalMaxChars`.
Doctor memeriksa apakah file bootstrap workspace (misalnya `AGENTS.md`, `CLAUDE.md`, atau file konteks terinjeksi lainnya) mendekati atau melebihi anggaran karakter yang dikonfigurasi. Doctor melaporkan jumlah karakter mentah vs. terinjeksi per file, persentase pemotongan, penyebab pemotongan (`max/file` atau `max/total`), dan total karakter terinjeksi sebagai fraksi dari total anggaran. Saat file dipotong atau mendekati batas, doctor mencetak tips untuk menyesuaikan `agents.defaults.bootstrapMaxChars` dan `agents.defaults.bootstrapTotalMaxChars`.
</Accordion>
<Accordion title="11d. Pembersihan plugin kanal usang">
Ketika `openclaw doctor --fix` menghapus plugin kanal yang hilang, doctor juga menghapus konfigurasi bercakupan kanal yang menggantung yang merujuk plugin tersebut: entri `channels.<id>`, target heartbeat yang menamai kanal, dan override `agents.*.models["<channel>/*"]`. Ini mencegah loop boot Gateway ketika runtime kanal sudah hilang tetapi konfigurasi masih meminta gateway untuk mengikat ke sana.
<Accordion title="11d. Pembersihan Plugin channel usang">
Saat `openclaw doctor --fix` menghapus Plugin channel yang hilang, perintah ini juga menghapus config berscope channel yang menggantung dan mereferensikan Plugin tersebut: entri `channels.<id>`, target heartbeat yang menamai channel, dan override `agents.*.models["<channel>/*"]`. Ini mencegah boot loop Gateway ketika runtime channel sudah hilang tetapi config masih meminta gateway untuk bind ke runtime tersebut.
</Accordion>
<Accordion title="11c. Pelengkapan shell">
Doctor memeriksa apakah pelengkapan tab terpasang untuk shell saat ini (zsh, bash, fish, atau PowerShell):
<Accordion title="11c. Completion shell">
Doctor memeriksa apakah tab completion sudah diinstal 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 meregenerasi 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 completion dinamis yang lambat (`source <(openclaw completion ...)`), doctor meng-upgrade-nya ke varian file cache yang lebih cepat.
- Jika completion dikonfigurasi dalam profil tetapi file cache hilang, doctor meregenerasi cache secara otomatis.
- Jika tidak ada completion yang dikonfigurasi sama sekali, doctor meminta untuk menginstalnya (hanya mode interaktif; dilewati dengan `--non-interactive`).
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.
- `openclaw doctor --generate-gateway-token` memaksa pembuatan hanya saat tidak ada SecretRef token yang dikonfigurasi.
</Accordion>
<Accordion title="12b. Perbaikan sadar SecretRef yang hanya baca">
<Accordion title="12b. Perbaikan read-only yang sadar SecretRef">
Beberapa alur perbaikan perlu memeriksa kredensial yang dikonfigurasi tanpa melemahkan perilaku runtime fail-fast.
- `openclaw doctor --fix` kini menggunakan model ringkasan SecretRef hanya baca yang sama seperti perintah keluarga status untuk perbaikan konfigurasi bertarget.
- 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` sekarang 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 saat tersedia.
- Jika token bot Telegram dikonfigurasi melalui SecretRef tetapi tidak tersedia dalam path perintah saat ini, doctor melaporkan bahwa kredensial dikonfigurasi-tetapi-tidak-tersedia dan melewati resolusi otomatis alih-alih crash atau salah melaporkan token sebagai hilang.
</Accordion>
<Accordion title="13. Pemeriksaan kesehatan Gateway + restart">
Doctor menjalankan pemeriksaan kesehatan dan menawarkan untuk me-restart gateway ketika terlihat tidak sehat.
<Accordion title="13. Health check Gateway + restart">
Doctor menjalankan health check dan menawarkan untuk me-restart gateway saat 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:
Doctor memeriksa apakah provider embedding pencarian memori yang dikonfigurasi siap untuk agen default. Perilakunya bergantung pada backend dan provider yang dikonfigurasi:
- **Backend QMD**: memeriksa apakah biner `qmd` tersedia dan dapat dimulai. 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 hilang, menyarankan beralih ke penyedia jarak jauh.
- **Penyedia jarak jauh eksplisit** (`openai`, `voyage`, dll.): memverifikasi bahwa kunci API ada di environment 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.
- **Backend QMD**: memeriksa apakah binary `qmd` tersedia dan dapat dijalankan. Jika tidak, mencetak panduan perbaikan termasuk paket npm dan opsi path binary manual.
- **Provider lokal eksplisit**: memeriksa file model lokal atau URL model jarak jauh/dapat diunduh yang dikenali. Jika hilang, menyarankan beralih ke provider jarak jauh.
- **Provider jarak jauh eksplisit** (`openai`, `voyage`, dll.): memverifikasi bahwa API key ada di environment atau auth store. Mencetak petunjuk perbaikan yang dapat ditindaklanjuti jika hilang.
- **Provider otomatis**: memeriksa ketersediaan model lokal terlebih dahulu, lalu mencoba setiap provider jarak jauh dalam urutan pemilihan otomatis.
Ketika hasil probe gateway cache tersedia (gateway sehat pada saat pemeriksaan), doctor mencocokkan silang 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 ketika Anda menginginkan pemeriksaan penyedia langsung.
Saat hasil probe gateway cache tersedia (gateway sehat pada saat pemeriksaan), doctor mencocokkan silang hasilnya dengan config yang terlihat oleh CLI dan mencatat setiap ketidaksesuaian. Doctor tidak memulai ping embedding baru pada path default; gunakan perintah status memori deep saat Anda menginginkan pemeriksaan provider live.
Gunakan `openclaw memory status --deep` untuk memverifikasi kesiapan embedding saat runtime.
</Accordion>
<Accordion title="14. Peringatan status kanal">
Jika gateway sehat, doctor menjalankan probe status kanal dan melaporkan peringatan dengan perbaikan yang disarankan.
<Accordion title="14. Peringatan status channel">
Jika gateway sehat, doctor menjalankan probe status channel 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 kedaluwarsa (misalnya dependensi systemd network-online dan jeda restart). Ketika menemukan ketidakcocokan, doctor merekomendasikan pembaruan dan dapat menulis ulang file layanan/tugas ke default saat ini.
<Accordion title="15. Audit + perbaikan config supervisor">
Doctor memeriksa config supervisor yang terinstal (launchd/systemd/schtasks) untuk default yang hilang atau usang (misalnya, dependensi systemd network-online dan jeda restart). Saat menemukan ketidaksesuaian, doctor merekomendasikan pembaruan dan dapat menulis ulang file layanan/task ke default saat ini.
Catatan:
@ -453,34 +454,34 @@ Itu men-stage kandidat durable berbasis grounding ke penyimpanan dreaming jangka
- `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 lifecycle layanan gateway. Doctor tetap melaporkan kesehatan layanan dan menjalankan perbaikan non-layanan, tetapi melewati pemasangan/mulai/restart/bootstrap layanan, penulisan ulang konfigurasi supervisor, dan pembersihan layanan lama karena supervisor eksternal memiliki lifecycle tersebut.
- Di Linux, doctor tidak menulis ulang metadata perintah/entrypoint ketika unit gateway systemd yang cocok aktif. Doctor juga mengabaikan unit ekstra mirip gateway non-legacy yang tidak aktif selama pemindaian layanan duplikat agar file layanan pendamping tidak menimbulkan noise pembersihan.
- Jika auth token membutuhkan token dan `gateway.auth.token` dikelola SecretRef, pemasangan/perbaikan layanan doctor memvalidasi SecretRef tetapi tidak menyimpan nilai token plaintext yang terselesaikan ke metadata environment layanan supervisor.
- Doctor mendeteksi nilai environment layanan yang dikelola `.env`/didukung SecretRef yang disematkan inline oleh pemasangan 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 ketika perintah layanan masih mengunci `--port` lama setelah `gateway.port` berubah dan menulis ulang metadata layanan ke port saat ini.
- Jika auth token membutuhkan token dan SecretRef token yang dikonfigurasi tidak 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` tidak disetel, doctor memblokir pemasangan/perbaikan sampai mode disetel secara eksplisit.
- Untuk unit user-systemd Linux, pemeriksaan pergeseran token doctor kini mencakup sumber `Environment=` dan `EnvironmentFile=` saat membandingkan metadata auth layanan.
- Perbaikan layanan doctor menolak menulis ulang, menghentikan, atau me-restart 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).
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` menjaga doctor tetap hanya-baca untuk siklus hidup layanan Gateway. Ini tetap melaporkan kesehatan layanan dan menjalankan perbaikan non-layanan, tetapi melewati pemasangan/memulai/memulai 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 sedang aktif. Ini juga mengabaikan unit tambahan mirip Gateway non-legacy yang tidak aktif selama pemindaian layanan duplikat sehingga file layanan pendamping tidak menimbulkan gangguan 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 terselesaikan ke metadata lingkungan layanan supervisor.
- Doctor mendeteksi nilai lingkungan layanan terkelola berbasis `.env`/SecretRef yang tertanam inline pada pemasangan LaunchAgent, systemd, atau Windows Scheduled Task lama dan menulis ulang metadata layanan agar nilai tersebut dimuat dari sumber runtime alih-alih 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 tidak 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 diatur, doctor memblokir pemasangan/perbaikan hingga mode diatur 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 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. Runtime Gateway + diagnostik port">
Doctor memeriksa runtime layanan (PID, status keluar terakhir) dan memperingatkan ketika layanan terinstal 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 + port Gateway">
Doctor memeriksa runtime layanan (PID, status keluar terakhir) dan memperingatkan saat layanan terpasang tetapi sebenarnya tidak berjalan. Ini 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 ketika 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 ketika tersedia (Homebrew/apt/choco).
Doctor memperingatkan saat layanan Gateway berjalan di Bun atau path Node yang dikelola versi (`nvm`, `fnm`, `volta`, `asdf`, dll.). Kanal WhatsApp + Telegram memerlukan Node, dan path pengelola versi dapat rusak setelah peningkatan karena layanan tidak memuat inisialisasi shell Anda. Doctor menawarkan migrasi ke pemasangan Node sistem saat tersedia (Homebrew/apt/choco).
Layanan yang baru diinstal atau diperbaiki 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 ketika direktori tersebut ada di disk. Ini menjaga PATH supervisor yang dihasilkan tetap selaras dengan audit minimal-PATH yang dijalankan doctor nanti.
Layanan yang baru dipasang atau diperbaiki 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. Ini menjaga PATH supervisor yang dihasilkan tetap selaras dengan audit PATH minimal yang sama yang dijalankan doctor kemudian.
</Accordion>
<Accordion title="18. Penulisan config + metadata wizard">
Doctor menyimpan setiap perubahan config dan memberi cap metadata wizard untuk mencatat eksekusi doctor.
<Accordion title="18. Penulisan konfigurasi + metadata wizard">
Doctor menyimpan perubahan konfigurasi apa pun dan membubuhkan metadata wizard untuk mencatat eksekusi doctor.
</Accordion>
<Accordion title="19. Tips workspace (backup + sistem memori)">
Doctor menyarankan sistem memori workspace ketika belum ada dan mencetak tips backup jika workspace belum berada di bawah git.
<Accordion title="19. Kiat workspace (cadangan + sistem memori)">
Doctor menyarankan sistem memori workspace saat belum ada dan mencetak kiat pencadangan jika workspace belum berada di bawah git.
Lihat [/concepts/agent-workspace](/id/concepts/agent-workspace) untuk panduan lengkap tentang struktur workspace dan backup git (disarankan GitHub atau GitLab privat).
Lihat [/concepts/agent-workspace](/id/concepts/agent-workspace) untuk panduan lengkap struktur workspace dan pencadangan git (disarankan GitHub atau GitLab privat).
</Accordion>
</AccordionGroup>

36
docs/id/gateway/gateway-lock.md
View File

@ -2,41 +2,41 @@
read_when:
- Menjalankan atau men-debug proses Gateway
- Menyelidiki penegakan instans tunggal
summary: Pengaman singleton Gateway menggunakan pengikatan pendengar WebSocket
title: Kunci Gateway
summary: Pengaman instans tunggal Gateway menggunakan pengikatan pendengar WebSocket
title: Penguncian Gateway
x-i18n:
generated_at: "2026-04-30T09:48:44Z"
generated_at: "2026-04-30T16:29:02Z"
model: gpt-5.5
provider: openai
source_hash: fe61ff81106554e98de1ca04c213b76d230265cdf3e81b70897d2de00f6a0179
source_hash: 85a1cb55f08d47d36fde25900e4247ef01c9a6800bf017fbff44a337f299ce13
source_path: gateway/gateway-lock.md
workflow: 16
---
## Mengapa
- Pastikan hanya satu instance Gateway berjalan per port dasar pada host yang sama; Gateway tambahan harus menggunakan profil terisolasi dan port unik.
- Tetap pulih dari crash/SIGKILL tanpa meninggalkan file kunci usang.
- Gagal cepat dengan kesalahan yang jelas ketika port kontrol sudah ditempati.
- Memastikan hanya satu instance Gateway berjalan per port dasar pada host yang sama; Gateway tambahan harus menggunakan profil terisolasi dan port unik.
- Tetap pulih dari crash/SIGKILL tanpa meninggalkan berkas kunci yang basi.
- Gagal cepat dengan error yang jelas ketika port kontrol sudah dipakai.
## Mekanisme
- Gateway pertama-tama memperoleh file kunci per konfigurasi di bawah direktori kunci status dan memeriksa port yang dikonfigurasi untuk pendengar yang sudah ada.
- Jika pemilik kunci yang tercatat sudah tidak ada, port bebas, atau kunci sudah usang, startup mengambil alih kunci dan melanjutkan.
- Gateway kemudian mengikat pendengar HTTP/WebSocket (default `ws://127.0.0.1:18789`) menggunakan pendengar TCP eksklusif.
- Jika pengikatan gagal dengan `EADDRINUSE`, startup melempar `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`.
- Saat shutdown, Gateway menutup server HTTP/WebSocket dan menghapus file kunci.
- Gateway terlebih dahulu memperoleh berkas kunci per-konfigurasi di bawah direktori kunci status dan memeriksa port yang dikonfigurasi untuk listener yang sudah ada.
- Jika pemilik kunci yang tercatat sudah tidak ada, port kosong, atau kunci basi, startup mengambil alih kembali kunci dan melanjutkan.
- Gateway kemudian mengikat listener HTTP/WebSocket (default `ws://127.0.0.1:18789`) menggunakan listener TCP eksklusif.
- Jika bind gagal dengan `EADDRINUSE`, startup melempar `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`.
- Saat shutdown, Gateway menutup server HTTP/WebSocket dan menghapus berkas kunci.
## Permukaan kesalahan
## Permukaan error
- Jika proses lain memegang port tersebut, startup melempar `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`.
- Kegagalan pengikatan lainnya muncul sebagai `GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: …")`.
- Jika proses lain memegang port, startup melempar `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`.
- Kegagalan bind lainnya muncul sebagai `GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: …")`.
## Catatan operasional
- Jika port ditempati oleh proses _lain_, kesalahannya sama; bebaskan port atau pilih port lain dengan `openclaw gateway --port <port>`.
- Di bawah supervisor layanan, proses Gateway baru yang melihat perespons `/healthz` sehat yang sudah ada akan keluar dengan sukses dan membiarkan proses tersebut memegang kendali. Jika proses yang ada tidak pernah menjadi sehat, percobaan ulang dibatasi dan startup gagal dengan kesalahan kunci yang jelas alih-alih berulang selamanya.
- Aplikasi macOS masih mempertahankan penjaga PID ringannya sendiri sebelum memunculkan Gateway; kunci saat runtime diberlakukan oleh file kunci plus pengikatan HTTP/WebSocket.
- Jika port ditempati oleh proses _lain_, error-nya sama; kosongkan port atau pilih yang lain dengan `openclaw gateway --port <port>`.
- Di bawah supervisor layanan, proses Gateway baru yang melihat responder `/healthz` sehat yang sudah ada membiarkan proses tersebut tetap memegang kontrol. Pada systemd, starter duplikat keluar dengan kode 78 sehingga default `RestartPreventExitStatus=78` menghentikan `Restart=always` agar tidak berulang karena konflik kunci atau `EADDRINUSE`. Jika proses yang sudah ada tidak pernah menjadi sehat, percobaan ulang dibatasi dan startup gagal dengan error kunci yang jelas alih-alih berulang selamanya.
- Aplikasi macOS tetap mempertahankan guard PID ringan miliknya sendiri sebelum menelurkan Gateway; kunci runtime diterapkan oleh berkas kunci plus bind HTTP/WebSocket.
## Terkait

124
docs/id/platforms/mac/remote.md
View File

@ -1,108 +1,108 @@
---
read_when:
- Menyiapkan atau men-debug kontrol mac remote
summary: Alur aplikasi macOS untuk mengendalikan gateway OpenClaw remote melalui SSH
title: Kontrol remote
- Menyiapkan atau men-debug kontrol Mac jarak jauh
summary: Alur aplikasi macOS untuk mengontrol Gateway OpenClaw jarak jauh melalui SSH
title: Kendali jarak jauh
x-i18n:
generated_at: "2026-04-26T11:34:01Z"
model: gpt-5.4
generated_at: "2026-04-30T16:28:59Z"
model: gpt-5.5
provider: openai
source_hash: 4de4980fe378fc9b685cf7732d21a80c640088191308b8ef1d3df9f468cb5be2
source_hash: 2c63f752c3636a253220310c7c8e57a28549704b74b2f0370bac432bae28a7d3
source_path: platforms/mac/remote.md
workflow: 15
workflow: 16
---
# OpenClaw remote (macOS ⇄ host remote)
# OpenClaw Jarak Jauh (macOS ⇄ host jarak jauh)
Alur ini memungkinkan aplikasi macOS bertindak sebagai kontrol remote penuh untuk gateway OpenClaw yang berjalan di host lain (desktop/server). Ini adalah fitur aplikasi **Remote over SSH** (eksekusi remote). Semua fitur—pemeriksaan kesehatan, penerusan Voice Wake, dan Web Chat—menggunakan config SSH remote yang sama dari _Settings → General_.
Alur ini memungkinkan aplikasi macOS bertindak sebagai kendali jarak jauh penuh untuk Gateway OpenClaw yang berjalan di host lain (desktop/server). Ini adalah fitur **Jarak Jauh melalui SSH** (jalan jarak jauh) aplikasi. Semua fitur—pemeriksaan kesehatan, penerusan Voice Wake, dan Obrolan Web—menggunakan ulang konfigurasi SSH jarak jauh yang sama dari _Pengaturan → Umum_.
## Mode
- **Local (Mac ini)**: Semua berjalan di laptop. Tidak ada SSH yang terlibat.
- **Remote over SSH (default)**: Perintah OpenClaw dijalankan di host remote. Aplikasi mac membuka koneksi SSH dengan `-o BatchMode` ditambah identitas/key pilihan Anda dan local port-forward.
- **Remote direct (ws/wss)**: Tanpa tunnel SSH. Aplikasi mac terhubung langsung ke URL gateway (misalnya, melalui Tailscale Serve atau reverse proxy HTTPS publik).
- **Lokal (Mac ini)**: Semuanya berjalan di laptop. Tidak ada SSH yang terlibat.
- **Jarak Jauh melalui SSH (default)**: Perintah OpenClaw dijalankan di host jarak jauh. Aplikasi mac membuka koneksi SSH dengan `-o BatchMode` ditambah identitas/kunci pilihan Anda dan penerusan port lokal.
- **Jarak jauh langsung (ws/wss)**: Tanpa tunnel SSH. Aplikasi mac terhubung langsung ke URL Gateway (misalnya, melalui Tailscale Serve atau reverse proxy HTTPS publik).
## Transport remote
## Transport jarak jauh
Mode remote mendukung dua transport:
Mode jarak jauh mendukung dua transport:
- **Tunnel SSH** (default): Menggunakan `ssh -N -L ...` untuk meneruskan port gateway ke localhost. Gateway akan melihat IP node sebagai `127.0.0.1` karena tunnel bersifat loopback.
- **Direct (ws/wss)**: Terhubung langsung ke URL gateway. Gateway melihat IP klien yang sebenarnya.
- **Tunnel SSH** (default): Menggunakan `ssh -N -L ...` untuk meneruskan port Gateway ke localhost. Gateway akan melihat IP node sebagai `127.0.0.1` karena tunnel adalah loopback.
- **Langsung (ws/wss)**: Terhubung langsung ke URL Gateway. Gateway melihat IP klien yang sebenarnya.
Dalam mode tunnel SSH, hostname LAN/tailnet yang ditemukan disimpan sebagai
`gateway.remote.sshTarget`. Aplikasi mempertahankan `gateway.remote.url` pada
endpoint tunnel lokal, misalnya `ws://127.0.0.1:18789`, sehingga CLI, Web Chat, dan
service host-node lokal semuanya menggunakan transport loopback aman yang sama.
Dalam mode tunnel SSH, nama host LAN/tailnet yang ditemukan disimpan sebagai
`gateway.remote.sshTarget`. Aplikasi mempertahankan `gateway.remote.url` pada endpoint
tunnel lokal, misalnya `ws://127.0.0.1:18789`, sehingga CLI, Obrolan Web, dan
layanan host node lokal semuanya menggunakan transport loopback aman yang sama.
Otomasi browser dalam mode remote dimiliki oleh host node CLI, bukan oleh node aplikasi macOS native.
Aplikasi memulai service host node yang terinstal bila memungkinkan; jika Anda memerlukan
kontrol browser dari Mac tersebut, instal/mulai dengan
Otomatisasi browser dalam mode jarak jauh dimiliki oleh host node CLI, bukan oleh
node aplikasi macOS native. Aplikasi memulai layanan host node yang terpasang bila
memungkinkan; jika Anda memerlukan kontrol browser dari Mac tersebut, pasang/mulai dengan
`openclaw node install ...` dan `openclaw node start` (atau jalankan
`openclaw node run ...` di foreground), lalu targetkan node dengan kapabilitas
browser tersebut.
`openclaw node run ...` di foreground), lalu targetkan node yang mampu menjalankan browser tersebut.
## Prasyarat pada host remote
## Prasyarat pada host jarak jauh
1. Instal Node + pnpm dan build/instal CLI OpenClaw (`pnpm install && pnpm build && pnpm link --global`).
2. Pastikan `openclaw` ada di PATH untuk shell non-interaktif (buat symlink ke `/usr/local/bin` atau `/opt/homebrew/bin` jika perlu).
3. Buka SSH dengan auth berbasis key. Kami menyarankan IP **Tailscale** untuk keterjangkauan stabil di luar LAN.
1. Pasang Node + pnpm dan bangun/pasang CLI OpenClaw (`pnpm install && pnpm build && pnpm link --global`).
2. Pastikan `openclaw` ada di PATH untuk shell non-interaktif (buat symlink ke `/usr/local/bin` atau `/opt/homebrew/bin` jika diperlukan).
3. Buka SSH dengan autentikasi kunci. Kami merekomendasikan IP **Tailscale** untuk keterjangkauan stabil di luar LAN.
## Penyiapan aplikasi macOS
1. Buka _Settings → General_.
2. Di bawah **OpenClaw runs**, pilih **Remote over SSH** dan atur:
- **Transport**: **SSH tunnel** atau **Direct (ws/wss)**.
- **SSH target**: `user@host` (`:port` opsional).
- Jika gateway berada di LAN yang sama dan mengiklankan Bonjour, pilih dari daftar yang ditemukan untuk mengisi field ini secara otomatis.
- **Gateway URL** (hanya Direct): `wss://gateway.example.ts.net` (atau `ws://...` untuk lokal/LAN).
- **Identity file** (lanjutan): path ke key Anda.
- **Project root** (lanjutan): path checkout remote yang digunakan untuk perintah.
- **CLI path** (lanjutan): path opsional ke entrypoint/binary `openclaw` yang dapat dijalankan (diisi otomatis saat diiklankan).
3. Tekan **Test remote**. Keberhasilan menandakan `openclaw status --json` remote berjalan dengan benar. Kegagalan biasanya berarti masalah PATH/CLI; exit 127 berarti CLI tidak ditemukan di remote.
4. Pemeriksaan kesehatan dan Web Chat sekarang akan berjalan melalui tunnel SSH ini secara otomatis.
1. Buka _Pengaturan → Umum_.
2. Di bawah **OpenClaw berjalan**, pilih **Jarak Jauh melalui SSH** dan atur:
- **Transport**: **Tunnel SSH** atau **Langsung (ws/wss)**.
- **Target SSH**: `user@host` (opsional `:port`).
- Jika Gateway berada di LAN yang sama dan mengiklankan Bonjour, pilih dari daftar yang ditemukan untuk mengisi bidang ini secara otomatis.
- **URL Gateway** (hanya Langsung): `wss://gateway.example.ts.net` (atau `ws://...` untuk lokal/LAN).
- **Berkas identitas** (lanjutan): path ke kunci Anda.
- **Root proyek** (lanjutan): path checkout jarak jauh yang digunakan untuk perintah.
- **Path CLI** (lanjutan): path opsional ke entrypoint/biner `openclaw` yang dapat dijalankan (diisi otomatis saat diiklankan).
3. Tekan **Uji jarak jauh**. Keberhasilan menunjukkan `openclaw status --json` jarak jauh berjalan dengan benar. Kegagalan biasanya berarti masalah PATH/CLI; exit 127 berarti CLI tidak ditemukan secara jarak jauh.
4. Pemeriksaan kesehatan dan Obrolan Web sekarang akan berjalan melalui tunnel SSH ini secara otomatis.
## Web Chat
## Obrolan Web
- **Tunnel SSH**: Web Chat terhubung ke gateway melalui port kontrol WebSocket yang diteruskan (default 18789).
- **Direct (ws/wss)**: Web Chat terhubung langsung ke URL gateway yang dikonfigurasi.
- Tidak ada lagi server HTTP WebChat terpisah.
- **Tunnel SSH**: Obrolan Web terhubung ke Gateway melalui port kontrol WebSocket yang diteruskan (default 18789).
- **Langsung (ws/wss)**: Obrolan Web terhubung langsung ke URL Gateway yang dikonfigurasi.
- Tidak ada server HTTP WebChat terpisah lagi.
## Izin
- Host remote memerlukan persetujuan TCC yang sama seperti lokal (Automation, Accessibility, Screen Recording, Microphone, Speech Recognition, Notifications). Jalankan onboarding di mesin tersebut untuk memberikannya sekali.
- Node mengiklankan status izinnya melalui `node.list` / `node.describe` agar agen mengetahui apa yang tersedia.
- Host jarak jauh memerlukan persetujuan TCC yang sama seperti lokal (Automation, Accessibility, Screen Recording, Microphone, Speech Recognition, Notifications). Jalankan onboarding di mesin tersebut untuk memberikannya sekali.
- Node mengiklankan status izinnya melalui `node.list` / `node.describe` sehingga agen mengetahui apa yang tersedia.
## Catatan keamanan
- Utamakan bind loopback pada host remote dan hubungkan melalui SSH atau Tailscale.
- SSH tunneling menggunakan pemeriksaan host-key yang ketat; percayai host key terlebih dahulu agar ada di `~/.ssh/known_hosts`.
- Jika Anda me-bind Gateway ke interface non-loopback, wajibkan auth Gateway yang valid: token, password, atau reverse proxy yang sadar identitas dengan `gateway.auth.mode: "trusted-proxy"`.
- Lihat [Security](/id/gateway/security) dan [Tailscale](/id/gateway/tailscale).
- Pilih bind loopback pada host jarak jauh dan hubungkan melalui SSH atau Tailscale.
- Tunnel SSH menggunakan pemeriksaan host-key yang ketat; percayai kunci host terlebih dahulu agar ada di `~/.ssh/known_hosts`.
- Jika Anda mengikat Gateway ke antarmuka non-loopback, wajibkan autentikasi Gateway yang valid: token, kata sandi, atau reverse proxy sadar-identitas dengan `gateway.auth.mode: "trusted-proxy"`.
- Lihat [Keamanan](/id/gateway/security) dan [Tailscale](/id/gateway/tailscale).
## Alur login WhatsApp (remote)
## Alur login WhatsApp (jarak jauh)
- Jalankan `openclaw channels login --verbose` **di host remote**. Pindai QR dengan WhatsApp di ponsel Anda.
- Jalankan ulang login di host tersebut jika auth kedaluwarsa. Pemeriksaan kesehatan akan menampilkan masalah tautan.
- Jalankan `openclaw channels login --verbose` **di host jarak jauh**. Pindai QR dengan WhatsApp di ponsel Anda.
- Jalankan ulang login di host tersebut jika autentikasi kedaluwarsa. Pemeriksaan kesehatan akan memunculkan masalah tautan.
## Pemecahan masalah
- **exit 127 / not found**: `openclaw` tidak ada di PATH untuk shell non-login. Tambahkan ke `/etc/paths`, rc shell Anda, atau buat symlink ke `/usr/local/bin`/`/opt/homebrew/bin`.
- **Health probe failed**: periksa keterjangkauan SSH, PATH, dan bahwa Baileys sudah login (`openclaw status --json`).
- **Web Chat stuck**: pastikan gateway berjalan di host remote dan port yang diteruskan cocok dengan port WS gateway; UI memerlukan koneksi WS yang sehat.
- **IP node menunjukkan 127.0.0.1**: ini diharapkan dengan tunnel SSH. Ubah **Transport** ke **Direct (ws/wss)** jika Anda ingin gateway melihat IP klien yang sebenarnya.
- **Voice Wake**: frasa pemicu diteruskan secara otomatis dalam mode remote; tidak diperlukan forwarder terpisah.
- **exit 127 / tidak ditemukan**: `openclaw` tidak ada di PATH untuk shell non-login. Tambahkan ke `/etc/paths`, rc shell Anda, atau buat symlink ke `/usr/local/bin`/`/opt/homebrew/bin`.
- **Probe kesehatan gagal**: periksa keterjangkauan SSH, PATH, dan bahwa Baileys sudah login (`openclaw status --json`).
- **Obrolan Web macet**: konfirmasikan Gateway berjalan di host jarak jauh dan port yang diteruskan cocok dengan port WS Gateway; UI memerlukan koneksi WS yang sehat.
- **IP node menampilkan 127.0.0.1**: ini diharapkan dengan tunnel SSH. Ubah **Transport** ke **Langsung (ws/wss)** jika Anda ingin Gateway melihat IP klien yang sebenarnya.
- **Dashboard berfungsi tetapi kapabilitas Mac offline**: ini berarti koneksi operator/kontrol aplikasi sehat, tetapi koneksi node pendamping tidak terhubung atau kehilangan permukaan perintahnya. Buka bagian perangkat bilah menu dan periksa apakah Mac adalah `paired · disconnected`. Untuk endpoint Tailscale Serve `wss://*.ts.net`, aplikasi mendeteksi pin leaf TLS lama yang usang setelah rotasi sertifikat, menghapus pin usang saat macOS memercayai sertifikat baru, dan mencoba ulang secara otomatis. Jika sertifikat tidak dipercaya sistem atau host bukan nama Tailscale Serve, tinjau sertifikat atau beralih ke **Jarak Jauh melalui SSH**.
- **Voice Wake**: frasa pemicu diteruskan secara otomatis dalam mode jarak jauh; tidak diperlukan penerus terpisah.
## Suara notifikasi
Pilih suara per notifikasi dari script dengan `openclaw` dan `node.invoke`, misalnya:
Pilih suara per notifikasi dari skrip dengan `openclaw` dan `node.invoke`, misalnya:
```bash
openclaw nodes notify --node <id> --title "Ping" --body "Remote gateway ready" --sound Glass
```
Tidak ada lagi toggle “default sound” global di aplikasi; pemanggil memilih suara (atau tidak ada) per permintaan.
Tidak ada lagi toggle “suara default” global di aplikasi; pemanggil memilih suara (atau tanpa suara) per permintaan.
## Terkait
- [Aplikasi macOS](/id/platforms/macos)
- [Akses remote](/id/gateway/remote)
- [aplikasi macOS](/id/platforms/macos)
- [Akses jarak jauh](/id/gateway/remote)

78
docs/id/providers/deepseek.md
View File

@ -1,26 +1,26 @@
---
read_when:
- Anda ingin menggunakan DeepSeek dengan OpenClaw
- Anda memerlukan variabel lingkungan untuk kunci API atau pilihan autentikasi CLI
- Anda memerlukan variabel lingkungan kunci API atau pilihan autentikasi CLI
summary: Penyiapan DeepSeek (autentikasi + pemilihan model)
title: DeepSeek
x-i18n:
generated_at: "2026-04-30T10:06:43Z"
generated_at: "2026-04-30T16:29:21Z"
model: gpt-5.5
provider: openai
source_hash: e84d989a7cba8d259779ac02293718050ce51efe6ce2bdbfacb9e22bbfd294ef
source_hash: 6fbc7bd4de14000eaa5c42b17eb8c9312321ed02ac1667e60774ead3f1749eb4
source_path: providers/deepseek.md
workflow: 16
---
[DeepSeek](https://www.deepseek.com) menyediakan model AI yang kuat dengan API yang kompatibel dengan OpenAI.
| Properti | Nilai |
| --------- | -------------------------- |
| Penyedia | `deepseek` |
| Autentikasi | `DEEPSEEK_API_KEY` |
| API | Kompatibel dengan OpenAI |
| URL dasar | `https://api.deepseek.com` |
| Properti | Nilai |
| -------- | -------------------------- |
| Penyedia | `deepseek` |
| Autentikasi | `DEEPSEEK_API_KEY` |
| API | Kompatibel dengan OpenAI |
| URL Dasar | `https://api.deepseek.com` |
## Memulai
@ -33,7 +33,7 @@ x-i18n:
openclaw onboard --auth-choice deepseek-api-key
```
Ini akan meminta kunci API Anda dan mengatur `deepseek/deepseek-v4-flash` sebagai model default.
Ini akan meminta kunci API Anda dan menetapkan `deepseek/deepseek-v4-flash` sebagai model default.
</Step>
<Step title="Verifikasi model tersedia">
@ -52,8 +52,8 @@ x-i18n:
</Steps>
<AccordionGroup>
<Accordion title="Penyiapan noninteraktif">
Untuk instalasi berskrip atau tanpa antarmuka, teruskan semua flag secara langsung:
<Accordion title="Penyiapan non-interaktif">
Untuk instalasi terskrip atau headless, teruskan semua flag secara langsung:
```bash
openclaw onboard --non-interactive \
@ -75,46 +75,48 @@ tersedia untuk proses tersebut (misalnya, di `~/.openclaw/.env` atau melalui
## Katalog bawaan
| Ref model | Nama | Input | Konteks | Output maks | Catatan |
| ---------------------------- | ----------------- | ----- | --------- | ----------- | -------------------------------------------- |
| `deepseek/deepseek-v4-flash` | DeepSeek V4 Flash | teks | 1,000,000 | 384,000 | Model default; permukaan V4 yang mendukung berpikir |
| `deepseek/deepseek-v4-pro` | DeepSeek V4 Pro | teks | 1,000,000 | 384,000 | Permukaan V4 yang mendukung berpikir |
| `deepseek/deepseek-chat` | DeepSeek Chat | teks | 131,072 | 8,192 | Permukaan DeepSeek V3.2 tanpa berpikir |
| `deepseek/deepseek-reasoner` | DeepSeek Reasoner | teks | 131,072 | 65,536 | Permukaan V3.2 dengan penalaran diaktifkan |
| Ref model | Nama | Masukan | Konteks | Output maks | Catatan |
| ---------------------------- | ----------------- | ----- | --------- | ---------- | ------------------------------------------ |
| `deepseek/deepseek-v4-flash` | DeepSeek V4 Flash | teks | 1,000,000 | 384,000 | Model default; permukaan V4 yang mendukung thinking |
| `deepseek/deepseek-v4-pro` | DeepSeek V4 Pro | teks | 1,000,000 | 384,000 | Permukaan V4 yang mendukung thinking |
| `deepseek/deepseek-chat` | DeepSeek Chat | teks | 131,072 | 8,192 | Permukaan DeepSeek V3.2 non-thinking |
| `deepseek/deepseek-reasoner` | DeepSeek Reasoner | teks | 131,072 | 65,536 | Permukaan V3.2 dengan penalaran diaktifkan |
<Tip>
Model V4 mendukung kontrol `thinking` DeepSeek. OpenClaw juga memutar ulang
`reasoning_content` DeepSeek pada giliran lanjutan sehingga sesi berpikir dengan pemanggilan tool
dapat berlanjut.
`reasoning_content` DeepSeek pada giliran lanjutan sehingga sesi thinking dengan
panggilan alat dapat berlanjut.
Gunakan `/think xhigh` atau `/think max` dengan model DeepSeek V4 untuk meminta
`reasoning_effort` maksimum DeepSeek.
</Tip>
## Berpikir dan tool
## Thinking dan alat
Sesi berpikir DeepSeek V4 memiliki kontrak pemutaran ulang yang lebih ketat daripada sebagian besar
penyedia yang kompatibel dengan OpenAI: setelah giliran dengan berpikir diaktifkan menggunakan tool, DeepSeek
mengharapkan pesan assistant yang diputar ulang dari giliran tersebut menyertakan
Sesi thinking DeepSeek V4 memiliki kontrak pemutaran ulang yang lebih ketat daripada sebagian besar
penyedia yang kompatibel dengan OpenAI: setelah giliran dengan thinking diaktifkan menggunakan alat, DeepSeek
mengharapkan pesan asisten yang diputar ulang dari giliran tersebut menyertakan
`reasoning_content` pada permintaan lanjutan. OpenClaw menangani ini di dalam
Plugin DeepSeek, sehingga penggunaan tool multi-giliran normal berfungsi dengan
Plugin DeepSeek, sehingga penggunaan alat multi-giliran normal berfungsi dengan
`deepseek/deepseek-v4-flash` dan `deepseek/deepseek-v4-pro`.
Jika Anda mengalihkan sesi yang ada dari penyedia lain yang kompatibel dengan OpenAI ke
model DeepSeek V4, giliran pemanggilan tool assistant yang lebih lama mungkin tidak memiliki
`reasoning_content` DeepSeek asli. OpenClaw mengisi bidang yang hilang itu pada pesan
assistant yang diputar ulang untuk permintaan berpikir DeepSeek V4 sehingga penyedia dapat menerima
model DeepSeek V4, giliran panggilan alat asisten lama mungkin tidak memiliki
`reasoning_content` DeepSeek asli. OpenClaw mengisi field yang hilang tersebut pada pesan
asisten yang diputar ulang untuk permintaan thinking DeepSeek V4 sehingga penyedia dapat menerima
riwayat tanpa memerlukan `/new`.
Ketika berpikir dinonaktifkan di OpenClaw (termasuk pilihan UI **None**),
OpenClaw mengirim `thinking: { type: "disabled" }` DeepSeek dan menghapus
`reasoning_content` yang diputar ulang dari riwayat keluar. Ini menjaga sesi dengan berpikir dinonaktifkan
tetap berada pada jalur DeepSeek tanpa berpikir.
Ketika thinking dinonaktifkan di OpenClaw (termasuk pilihan UI **None**),
OpenClaw mengirimkan `thinking: { type: "disabled" }` DeepSeek dan menghapus
`reasoning_content` yang diputar ulang dari riwayat keluar. Ini menjaga sesi
dengan thinking dinonaktifkan tetap berada di jalur DeepSeek non-thinking.
Gunakan `deepseek/deepseek-v4-flash` untuk jalur cepat default. Gunakan
`deepseek/deepseek-v4-pro` saat Anda menginginkan model V4 yang lebih kuat dan dapat menerima
`deepseek/deepseek-v4-pro` ketika Anda menginginkan model V4 yang lebih kuat dan dapat menerima
biaya atau latensi yang lebih tinggi.
## Pengujian langsung
## Pengujian live
Suite model langsung langsung mencakup DeepSeek V4 dalam kumpulan model modern. Untuk
Rangkaian model live langsung mencakup DeepSeek V4 dalam set model modern. Untuk
menjalankan hanya pemeriksaan model langsung DeepSeek V4:
```bash
@ -123,8 +125,8 @@ OPENCLAW_LIVE_MODELS="deepseek/deepseek-v4-flash,deepseek/deepseek-v4-pro" \
pnpm test:live src/agents/models.profiles.live.test.ts
```
Pemeriksaan langsung tersebut memverifikasi bahwa kedua model V4 dapat menyelesaikan tugas dan bahwa giliran lanjutan berpikir/tool
mempertahankan payload pemutaran ulang yang diperlukan DeepSeek.
Pemeriksaan live tersebut memverifikasi bahwa kedua model V4 dapat menyelesaikan permintaan dan bahwa giliran lanjutan
thinking/alat mempertahankan payload pemutaran ulang yang diperlukan DeepSeek.
## Contoh konfigurasi
@ -146,6 +148,6 @@ mempertahankan payload pemutaran ulang yang diperlukan DeepSeek.
Memilih penyedia, ref 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>

381
docs/id/providers/openai.md
View File

@ -1,68 +1,68 @@
---
read_when:
- Anda ingin menggunakan model OpenAI di OpenClaw
- Anda menginginkan autentikasi langganan Codex alih-alih kunci API
- Anda menginginkan autentikasi langganan Codex, bukan kunci API
- Anda memerlukan perilaku eksekusi agen GPT-5 yang lebih ketat
summary: Gunakan OpenAI melalui kunci API atau langganan Codex di OpenClaw
title: OpenAI
x-i18n:
generated_at: "2026-04-30T10:08:19Z"
generated_at: "2026-04-30T16:29:45Z"
model: gpt-5.5
provider: openai
source_hash: be0e2cd14990a53533c800cd8d305c9c50b0fa7131f6638e7b9d8dd9f2942fe8
source_hash: 7e113f2418f82a8859f208f85efb55114bda7bc17beeb28f012b19e861609dad
source_path: providers/openai.md
workflow: 16
---
OpenAI menyediakan API pengembang untuk model GPT, dan Codex juga tersedia sebagai agen coding
paket ChatGPT melalui klien Codex dari OpenAI. OpenClaw menjaga permukaan tersebut
tetap terpisah agar konfigurasi tetap dapat diprediksi.
OpenAI menyediakan API pengembang untuk model GPT, dan Codex juga tersedia sebagai
agen coding paket ChatGPT melalui klien Codex milik OpenAI. OpenClaw menjaga
permukaan tersebut tetap terpisah agar konfigurasi tetap dapat diprediksi.
OpenClaw mendukung tiga rute keluarga OpenAI. Prefiks model memilih rute
penyedia/autentikasi; pengaturan runtime terpisah memilih siapa yang menjalankan
loop agen tertanam:
- **API key** — akses langsung OpenAI Platform dengan penagihan berbasis pemakaian (model `openai/*`)
- **Kunci API** — akses langsung OpenAI Platform dengan penagihan berbasis penggunaan (model `openai/*`)
- **Langganan Codex melalui PI** — masuk ChatGPT/Codex dengan akses langganan (model `openai-codex/*`)
- **Harness app-server Codex** — eksekusi app-server Codex native (model `openai/*` plus `agents.defaults.agentRuntime.id: "codex"`)
OpenAI secara eksplisit mendukung penggunaan OAuth langganan di alat dan alur kerja eksternal seperti OpenClaw.
Penyedia, model, runtime, dan channel adalah lapisan terpisah. Jika label-label itu
Penyedia, model, runtime, dan saluran adalah lapisan terpisah. Jika label-label itu
mulai tercampur, baca [Runtime agen](/id/concepts/agent-runtimes) sebelum
mengubah konfigurasi.
## Pilihan cepat
| Tujuan | Gunakan | Catatan |
| Tujuan | Gunakan | Catatan |
| --------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------- |
| Penagihan API-key langsung | `openai/gpt-5.5` | Atur `OPENAI_API_KEY` atau jalankan onboarding API-key OpenAI. |
| Penagihan kunci API langsung | `openai/gpt-5.5` | Atur `OPENAI_API_KEY` atau jalankan onboarding kunci API OpenAI. |
| GPT-5.5 dengan autentikasi langganan ChatGPT/Codex | `openai-codex/gpt-5.5` | Rute PI default untuk OAuth Codex. Pilihan awal terbaik untuk setup langganan. |
| GPT-5.5 dengan perilaku app-server Codex native | `openai/gpt-5.5` plus `agentRuntime.id: "codex"` | Memaksa harness app-server Codex untuk referensi model tersebut. |
| Pembuatan atau pengeditan gambar | `openai/gpt-image-2` | Berfungsi dengan `OPENAI_API_KEY` atau OAuth OpenAI Codex. |
| Gambar dengan latar belakang transparan | `openai/gpt-image-1.5` | Gunakan `outputFormat=png` atau `webp` dan `openai.background=transparent`. |
| GPT-5.5 dengan perilaku app-server Codex native | `openai/gpt-5.5` plus `agentRuntime.id: "codex"` | Memaksa harness app-server Codex untuk referensi model itu. |
| Pembuatan atau penyuntingan gambar | `openai/gpt-image-2` | Berfungsi dengan `OPENAI_API_KEY` atau OAuth OpenAI Codex. |
| Gambar dengan latar belakang transparan | `openai/gpt-image-1.5` | Gunakan `outputFormat=png` atau `webp` dan `openai.background=transparent`. |
## Peta penamaan
Nama-namanya mirip tetapi tidak dapat dipertukarkan:
Nama-namanya mirip tetapi tidak dapat saling dipertukarkan:
| Nama yang Anda lihat | Lapisan | Makna |
| Nama yang Anda lihat | Lapisan | Arti |
| ---------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------- |
| `openai` | Prefiks penyedia | Rute API OpenAI Platform langsung. |
| `openai` | Prefiks penyedia | Rute API OpenAI Platform langsung. |
| `openai-codex` | Prefiks penyedia | Rute OAuth/langganan OpenAI Codex melalui runner PI OpenClaw normal. |
| Plugin `codex` | Plugin | Plugin bawaan OpenClaw yang menyediakan runtime app-server Codex native dan kontrol chat `/codex`. |
| Plugin `codex` | Plugin | Plugin OpenClaw bawaan yang menyediakan runtime app-server Codex native dan kontrol chat `/codex`. |
| `agentRuntime.id: codex` | Runtime agen | Paksa harness app-server Codex native untuk giliran tertanam. |
| `/codex ...` | Kumpulan perintah chat | Ikat/kontrol thread app-server Codex dari percakapan. |
| `/codex ...` | Kumpulan perintah chat | Ikat/kontrol thread app-server Codex dari percakapan. |
| `runtime: "acp", agentId: "codex"` | Rute sesi ACP | Jalur fallback eksplisit yang menjalankan Codex melalui ACP/acpx. |
Ini berarti konfigurasi dapat dengan sengaja berisi `openai-codex/*` dan Plugin
`codex`. Itu valid ketika Anda menginginkan OAuth Codex melalui PI dan juga ingin
Ini berarti konfigurasi dapat sengaja memuat `openai-codex/*` dan Plugin
`codex` sekaligus. Itu valid ketika Anda ingin OAuth Codex melalui PI dan juga ingin
kontrol chat `/codex` native tersedia. `openclaw doctor` memperingatkan tentang
kombinasi itu agar Anda dapat memastikan bahwa hal tersebut disengaja; perintah itu tidak menulis ulangnya.
kombinasi itu agar Anda dapat memastikan bahwa itu disengaja; perintah tersebut tidak menulis ulangnya.
<Note>
GPT-5.5 tersedia melalui akses API-key OpenAI Platform langsung dan rute
langganan/OAuth. Gunakan `openai/gpt-5.5` untuk traffic `OPENAI_API_KEY`
GPT-5.5 tersedia melalui akses kunci API OpenAI Platform langsung dan
rute langganan/OAuth. Gunakan `openai/gpt-5.5` untuk traffic `OPENAI_API_KEY`
langsung, `openai-codex/gpt-5.5` untuk OAuth Codex melalui PI, atau
`openai/gpt-5.5` dengan `agentRuntime.id: "codex"` untuk harness app-server
Codex native.
@ -72,24 +72,24 @@ Codex native.
Mengaktifkan Plugin OpenAI, atau memilih model `openai-codex/*`, tidak
mengaktifkan Plugin app-server Codex bawaan. OpenClaw mengaktifkan Plugin itu hanya
ketika Anda secara eksplisit memilih harness Codex native dengan
`agentRuntime.id: "codex"` atau menggunakan referensi model lama `codex/*`.
Jika Plugin `codex` bawaan diaktifkan tetapi `openai-codex/*` masih di-resolve
`agentRuntime.id: "codex"` atau menggunakan referensi model `codex/*` lama.
Jika Plugin `codex` bawaan diaktifkan tetapi `openai-codex/*` masih diselesaikan
melalui PI, `openclaw doctor` memperingatkan dan membiarkan rute tetap tidak berubah.
</Note>
## Cakupan fitur OpenClaw
| Kapabilitas OpenAI | Permukaan OpenClaw | Status |
| Kemampuan OpenAI | Permukaan OpenClaw | Status |
| ------------------------- | ---------------------------------------------------------- | ------------------------------------------------------ |
| Chat / Responses | Penyedia model `openai/<model>` | Ya |
| Model langganan Codex | `openai-codex/<model>` dengan OAuth `openai-codex` | Ya |
| Harness app-server Codex | `openai/<model>` dengan `agentRuntime.id: codex` | Ya |
| Chat / Responses | penyedia model `openai/<model>` | Ya |
| Model langganan Codex | `openai-codex/<model>` dengan OAuth `openai-codex` | Ya |
| Harness app-server Codex | `openai/<model>` dengan `agentRuntime.id: codex` | Ya |
| Pencarian web sisi server | Alat OpenAI Responses native | Ya, ketika pencarian web diaktifkan dan tidak ada penyedia yang dipin |
| Gambar | `image_generate` | Ya |
| Video | `video_generate` | Ya |
| Text-to-speech | `messages.tts.provider: "openai"` / `tts` | Ya |
| Speech-to-text batch | `tools.media.audio` / pemahaman media | Ya |
| Speech-to-text streaming | Voice Call `streaming.provider: "openai"` | Ya |
| Teks ke ucapan | `messages.tts.provider: "openai"` / `tts` | Ya |
| Ucapan ke teks batch | `tools.media.audio` / pemahaman media | Ya |
| Ucapan ke teks streaming | Voice Call `streaming.provider: "openai"` | Ya |
| Suara realtime | Voice Call `realtime.provider: "openai"` / Control UI Talk | Ya |
| Embedding | penyedia embedding memori | Ya |
@ -111,7 +111,7 @@ pengindeksan `memory_search` dan embedding kueri:
}
```
Untuk endpoint kompatibel OpenAI yang memerlukan label embedding asimetris, atur
Untuk endpoint yang kompatibel dengan OpenAI yang memerlukan label embedding asimetris, atur
`queryInputType` dan `documentInputType` di bawah `memorySearch`. OpenClaw meneruskan
keduanya sebagai field permintaan `input_type` khusus penyedia: embedding kueri menggunakan
`queryInputType`; potongan memori yang diindeks dan pengindeksan batch menggunakan
@ -119,28 +119,28 @@ keduanya sebagai field permintaan `input_type` khusus penyedia: embedding kueri
## Memulai
Pilih metode autentikasi pilihan Anda dan ikuti langkah-langkah setup.
Pilih metode autentikasi yang Anda inginkan dan ikuti langkah-langkah setup.
<Tabs>
<Tab title="API key (OpenAI Platform)">
**Terbaik untuk:** akses API langsung dan penagihan berbasis pemakaian.
<Tab title="Kunci API (OpenAI Platform)">
**Terbaik untuk:** akses API langsung dan penagihan berbasis penggunaan.
<Steps>
<Step title="Dapatkan API key Anda">
Buat atau salin API key dari [dasbor OpenAI Platform](https://platform.openai.com/api-keys).
<Step title="Dapatkan kunci API Anda">
Buat atau salin kunci API dari [dasbor OpenAI Platform](https://platform.openai.com/api-keys).
</Step>
<Step title="Jalankan onboarding">
```bash
openclaw onboard --auth-choice openai-api-key
```
Atau berikan key secara langsung:
Atau berikan kuncinya secara langsung:
```bash
openclaw onboard --openai-api-key "$OPENAI_API_KEY"
```
</Step>
<Step title="Verifikasi bahwa model tersedia">
<Step title="Verifikasi model tersedia">
```bash
openclaw models list --provider openai
```
@ -149,14 +149,14 @@ Pilih metode autentikasi pilihan Anda dan ikuti langkah-langkah setup.
### Ringkasan rute
| Referensi model | Konfigurasi runtime | Rute | Autentikasi |
| Referensi model | Konfigurasi runtime | Rute | Autentikasi |
| ---------------------- | -------------------------- | --------------------------- | ---------------- |
| `openai/gpt-5.5` | dihilangkan / `agentRuntime.id: "pi"` | API OpenAI Platform langsung | `OPENAI_API_KEY` |
| `openai/gpt-5.4-mini` | dihilangkan / `agentRuntime.id: "pi"` | API OpenAI Platform langsung | `OPENAI_API_KEY` |
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Harness app-server Codex | App-server Codex |
<Note>
`openai/*` adalah rute API-key OpenAI langsung kecuali Anda secara eksplisit memaksa
`openai/*` adalah rute kunci API OpenAI langsung kecuali Anda secara eksplisit memaksa
harness app-server Codex. Gunakan `openai-codex/*` untuk OAuth Codex melalui
runner PI default, atau gunakan `openai/gpt-5.5` dengan
`agentRuntime.id: "codex"` untuk eksekusi app-server Codex native.
@ -172,13 +172,13 @@ Pilih metode autentikasi pilihan Anda dan ikuti langkah-langkah setup.
```
<Warning>
OpenClaw **tidak** mengekspos `openai/gpt-5.3-codex-spark`. Permintaan API OpenAI live menolak model tersebut, dan katalog Codex saat ini juga tidak mengeksposnya.
OpenClaw **tidak** mengekspos `openai/gpt-5.3-codex-spark`. Permintaan API OpenAI live menolak model itu, dan katalog Codex saat ini juga tidak mengeksposnya.
</Warning>
</Tab>
<Tab title="Langganan Codex">
**Terbaik untuk:** menggunakan langganan ChatGPT/Codex Anda alih-alih API key terpisah. Cloud Codex memerlukan masuk ChatGPT.
**Terbaik untuk:** menggunakan langganan ChatGPT/Codex Anda alih-alih kunci API terpisah. Cloud Codex memerlukan masuk ChatGPT.
<Steps>
<Step title="Jalankan OAuth Codex">
@ -192,7 +192,7 @@ Pilih metode autentikasi pilihan Anda dan ikuti langkah-langkah setup.
openclaw models auth login --provider openai-codex
```
Untuk setup headless atau yang tidak cocok dengan callback, tambahkan `--device-code` untuk masuk dengan alur device-code ChatGPT alih-alih callback browser localhost:
Untuk setup headless atau yang tidak cocok dengan callback, tambahkan `--device-code` untuk masuk dengan alur kode perangkat ChatGPT alih-alih callback browser localhost:
```bash
openclaw models auth login --provider openai-codex --device-code
@ -203,7 +203,7 @@ Pilih metode autentikasi pilihan Anda dan ikuti langkah-langkah setup.
openclaw config set agents.defaults.model.primary openai-codex/gpt-5.5
```
</Step>
<Step title="Verifikasi bahwa model tersedia">
<Step title="Verifikasi model tersedia">
```bash
openclaw models list --provider openai-codex
```
@ -215,6 +215,7 @@ Pilih metode autentikasi pilihan Anda dan ikuti langkah-langkah setup.
| Referensi model | Konfigurasi runtime | Rute | Autentikasi |
|-----------|----------------|-------|------|
| `openai-codex/gpt-5.5` | dihilangkan / `runtime: "pi"` | OAuth ChatGPT/Codex melalui PI | Masuk Codex |
| `openai-codex/gpt-5.4-mini` | dihilangkan / `runtime: "pi"` | OAuth ChatGPT/Codex melalui PI | Masuk Codex |
| `openai-codex/gpt-5.5` | `runtime: "auto"` | Tetap PI kecuali sebuah Plugin secara eksplisit mengklaim `openai-codex` | Masuk Codex |
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Harness app-server Codex | Autentikasi app-server Codex |
@ -224,12 +225,6 @@ Pilih metode autentikasi pilihan Anda dan ikuti langkah-langkah setup.
Itu tidak memilih atau mengaktifkan otomatis harness app-server Codex bawaan.
</Note>
<Warning>
`openai-codex/gpt-5.4-mini` bukan rute OAuth Codex yang didukung. Gunakan
`openai/gpt-5.4-mini` dengan API key OpenAI, atau gunakan
`openai-codex/gpt-5.5` dengan OAuth Codex.
</Warning>
### Contoh konfigurasi
```json5
@ -239,24 +234,23 @@ Pilih metode autentikasi pilihan Anda dan ikuti langkah-langkah setup.
```
<Note>
Onboarding tidak lagi mengimpor materi OAuth dari `~/.codex`. Masuk dengan OAuth browser (default) atau alur device-code di atas — OpenClaw mengelola kredensial yang dihasilkan di penyimpanan autentikasi agennya sendiri.
Onboarding tidak lagi mengimpor material OAuth dari `~/.codex`. Masuk dengan OAuth browser (default) atau alur kode perangkat di atas — OpenClaw mengelola kredensial yang dihasilkan di penyimpanan autentikasi agennya sendiri.
</Note>
### Indikator status
Chat `/status` menampilkan runtime model mana yang aktif untuk sesi saat ini.
Harness PI default muncul sebagai `Runtime: OpenClaw Pi Default`. Ketika
harness app-server Codex bawaan dipilih, `/status` menampilkan
`Runtime: OpenAI Codex`. Sesi yang sudah ada mempertahankan id harness yang terekam, jadi gunakan
Chat `/status` menunjukkan runtime model mana yang aktif untuk sesi saat ini.
Harness PI default muncul sebagai `Runtime: OpenClaw Pi Default`. Saat harness app-server Codex bawaan dipilih, `/status` menampilkan
`Runtime: OpenAI Codex`. Sesi yang ada mempertahankan id harness yang terekam, jadi gunakan
`/new` atau `/reset` setelah mengubah `agentRuntime` jika Anda ingin `/status`
mencerminkan pilihan PI/Codex baru.
mencerminkan pilihan PI/Codex yang baru.
### Peringatan Doctor
### Peringatan doctor
Jika Plugin `codex` bawaan diaktifkan sementara route
Jika Plugin `codex` bawaan diaktifkan sementara rute
`openai-codex/*` tab ini dipilih, `openclaw doctor` memperingatkan bahwa model
masih di-resolve melalui PI. Biarkan konfigurasi tidak berubah jika itu adalah
route auth langganan yang dimaksud. Beralihlah ke `openai/<model>` plus
masih diselesaikan melalui PI. Biarkan config tidak berubah jika itu adalah rute
autentikasi langganan yang dimaksud. Beralihlah ke `openai/<model>` ditambah
`agentRuntime.id: "codex"` hanya ketika Anda menginginkan eksekusi app-server
Codex native.
@ -264,12 +258,12 @@ Pilih metode autentikasi pilihan Anda dan ikuti langkah-langkah setup.
OpenClaw memperlakukan metadata model dan batas konteks runtime sebagai nilai yang terpisah.
Untuk `openai-codex/gpt-5.5` melalui OAuth Codex:
Untuk `openai-codex/gpt-5.5` melalui Codex OAuth:
- `contextWindow` native: `1000000`
- Batas `contextTokens` runtime default: `272000`
Batas default yang lebih kecil memiliki karakteristik latensi dan kualitas yang lebih baik dalam praktik. Timpa dengan `contextTokens`:
Batas default yang lebih kecil memiliki karakteristik latensi dan kualitas yang lebih baik dalam praktiknya. Override dengan `contextTokens`:
```json5
{
@ -289,50 +283,50 @@ Pilih metode autentikasi pilihan Anda dan ikuti langkah-langkah setup.
### Pemulihan katalog
OpenClaw menggunakan metadata katalog Codex upstream untuk `gpt-5.5` ketika
tersedia. Jika penemuan Codex langsung menghilangkan baris `openai-codex/gpt-5.5` sementara
OpenClaw menggunakan metadata katalog Codex upstream untuk `gpt-5.5` saat metadata itu
ada. Jika penemuan Codex live menghilangkan baris `openai-codex/gpt-5.5` sementara
akun sudah diautentikasi, OpenClaw menyintesis baris model OAuth tersebut agar
cron, sub-agent, dan eksekusi model default yang dikonfigurasi tidak gagal dengan
cron, sub-agent, dan run model default yang dikonfigurasi tidak gagal dengan
`Unknown model`.
</Tab>
</Tabs>
## Auth app-server Codex native
## Autentikasi app-server Codex native
Harness app-server Codex native menggunakan ref model `openai/*` plus
`agentRuntime.id: "codex"`, tetapi auth-nya tetap berbasis akun. OpenClaw
memilih auth dalam urutan ini:
Harness app-server Codex native menggunakan ref model `openai/*` ditambah
`agentRuntime.id: "codex"`, tetapi autentikasinya tetap berbasis akun. OpenClaw
memilih autentikasi dalam urutan ini:
1. Profil auth OpenClaw `openai-codex` eksplisit yang terikat ke agen.
2. Akun app-server yang sudah ada, seperti login ChatGPT Codex CLI lokal.
1. Profil autentikasi OpenClaw `openai-codex` eksplisit yang terikat ke agent.
2. Akun app-server yang sudah ada, seperti sign-in ChatGPT CLI Codex lokal.
3. Hanya untuk peluncuran app-server stdio lokal, `CODEX_API_KEY`, lalu
`OPENAI_API_KEY`, ketika app-server melaporkan tidak ada akun dan masih memerlukan
auth OpenAI.
`OPENAI_API_KEY`, saat app-server melaporkan tidak ada akun dan masih memerlukan
autentikasi OpenAI.
Itu berarti login langganan ChatGPT/Codex lokal tidak diganti hanya
Artinya, sign-in langganan ChatGPT/Codex lokal tidak diganti hanya
karena proses Gateway juga memiliki `OPENAI_API_KEY` untuk model OpenAI langsung
atau embeddings. Fallback kunci API env hanya jalur stdio lokal tanpa akun; fallback itu
tidak dikirim ke koneksi app-server WebSocket. Ketika profil Codex bergaya langganan
dipilih, OpenClaw juga menjaga `CODEX_API_KEY` dan `OPENAI_API_KEY`
tetap keluar dari child app-server stdio yang di-spawn dan mengirim kredensial yang dipilih
atau embeddings. Fallback kunci API env hanya jalur stdio lokal tanpa akun; itu
tidak dikirim ke koneksi app-server WebSocket. Saat profil Codex bergaya langganan
dipilih, OpenClaw juga mencegah `CODEX_API_KEY` dan `OPENAI_API_KEY`
masuk ke child app-server stdio yang dibuat dan mengirim kredensial terpilih
melalui RPC login app-server.
## Pembuatan gambar
Plugin `openai` bawaan mendaftarkan pembuatan gambar melalui alat `image_generate`.
Plugin ini mendukung pembuatan gambar OpenAI berbasis kunci API dan pembuatan gambar
OAuth Codex melalui ref model `openai/gpt-image-2` yang sama.
Plugin `openai` bawaan mendaftarkan pembuatan gambar melalui tool `image_generate`.
Ini mendukung pembuatan gambar kunci API OpenAI dan pembuatan gambar Codex OAuth
melalui ref model `openai/gpt-image-2` yang sama.
| Kapabilitas | Kunci API OpenAI | OAuth Codex |
| ----------------------- | ---------------------------------------- | ------------------------------------ |
| Ref model | `openai/gpt-image-2` | `openai/gpt-image-2` |
| Auth | `OPENAI_API_KEY` | Login OAuth OpenAI Codex |
| Transport | OpenAI Images API | Backend Codex Responses |
| Gambar maks per request | 4 | 4 |
| Mode edit | Diaktifkan (hingga 5 gambar referensi) | Diaktifkan (hingga 5 gambar referensi) |
| Override ukuran | Didukung, termasuk ukuran 2K/4K | Didukung, termasuk ukuran 2K/4K |
| Rasio aspek / resolusi | Tidak diteruskan ke OpenAI Images API | Dipetakan ke ukuran yang didukung jika aman |
| Kapabilitas | Kunci API OpenAI | Codex OAuth |
| ------------------------- | ---------------------------------- | ------------------------------------ |
| Ref model | `openai/gpt-image-2` | `openai/gpt-image-2` |
| Auth | `OPENAI_API_KEY` | Sign-in OpenAI Codex OAuth |
| Transport | OpenAI Images API | Backend Codex Responses |
| Maks gambar per permintaan | 4 | 4 |
| Mode edit | Diaktifkan (hingga 5 gambar referensi) | Diaktifkan (hingga 5 gambar referensi) |
| Override ukuran | Didukung, termasuk ukuran 2K/4K | Didukung, termasuk ukuran 2K/4K |
| Rasio aspek / resolusi | Tidak diteruskan ke OpenAI Images API | Dipetakan ke ukuran yang didukung saat aman |
```json5
{
@ -345,24 +339,24 @@ OAuth Codex melalui ref model `openai/gpt-image-2` yang sama.
```
<Note>
Lihat [Pembuatan Gambar](/id/tools/image-generation) untuk parameter alat bersama, pemilihan penyedia, dan perilaku failover.
Lihat [Pembuatan Gambar](/id/tools/image-generation) untuk parameter tool bersama, pemilihan provider, dan perilaku failover.
</Note>
`gpt-image-2` adalah default untuk pembuatan gambar dari teks OpenAI dan pengeditan gambar.
`gpt-image-2` adalah default untuk pembuatan teks-ke-gambar OpenAI dan pengeditan gambar.
`gpt-image-1.5`, `gpt-image-1`, dan `gpt-image-1-mini` tetap dapat digunakan sebagai
override model eksplisit. Gunakan `openai/gpt-image-1.5` untuk output PNG/WebP
berlatar transparan; API `gpt-image-2` saat ini menolak
berlatar belakang transparan; API `gpt-image-2` saat ini menolak
`background: "transparent"`.
Untuk request latar transparan, agen harus memanggil `image_generate` dengan
Untuk permintaan berlatar belakang transparan, agent harus memanggil `image_generate` dengan
`model: "openai/gpt-image-1.5"`, `outputFormat: "png"` atau `"webp"`, dan
`background: "transparent"`; opsi penyedia `openai.background` yang lebih lama
masih diterima. OpenClaw juga melindungi route OpenAI publik dan
OAuth OpenAI Codex dengan menulis ulang request transparan default `openai/gpt-image-2`
ke `gpt-image-1.5`; endpoint Azure dan kustom yang kompatibel dengan OpenAI mempertahankan
`background: "transparent"`; opsi provider `openai.background` yang lebih lama
tetap diterima. OpenClaw juga melindungi rute OpenAI publik dan
OpenAI Codex OAuth dengan menulis ulang permintaan transparan default `openai/gpt-image-2`
ke `gpt-image-1.5`; endpoint Azure dan endpoint kompatibel OpenAI kustom mempertahankan
nama deployment/model yang dikonfigurasi.
Pengaturan yang sama tersedia untuk eksekusi CLI headless:
Pengaturan yang sama diekspos untuk run CLI headless:
```bash
openclaw infer image generate \
@ -374,19 +368,19 @@ openclaw infer image generate \
```
Gunakan flag `--output-format` dan `--background` yang sama dengan
`openclaw infer image edit` ketika memulai dari file input.
`openclaw infer image edit` saat memulai dari file input.
`--openai-background` tetap tersedia sebagai alias khusus OpenAI.
Untuk instalasi OAuth Codex, pertahankan ref `openai/gpt-image-2` yang sama. Ketika profil
OAuth `openai-codex` dikonfigurasi, OpenClaw me-resolve token akses OAuth yang tersimpan
tersebut dan mengirim request gambar melalui backend Codex Responses. OpenClaw
Untuk instalasi Codex OAuth, pertahankan ref `openai/gpt-image-2` yang sama. Saat profil OAuth
`openai-codex` dikonfigurasi, OpenClaw menyelesaikan token akses OAuth tersimpan tersebut
dan mengirim permintaan gambar melalui backend Codex Responses. OpenClaw
tidak terlebih dahulu mencoba `OPENAI_API_KEY` atau diam-diam fallback ke kunci API untuk
request tersebut. Konfigurasikan `models.providers.openai` secara eksplisit dengan kunci API,
base URL kustom, atau endpoint Azure ketika Anda menginginkan route OpenAI Images API
langsung.
Jika endpoint gambar kustom tersebut berada di alamat LAN/pribadi tepercaya, atur juga
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`; OpenClaw tetap memblokir
endpoint gambar internal/pribadi yang kompatibel dengan OpenAI kecuali opt-in ini
permintaan itu. Konfigurasikan `models.providers.openai` secara eksplisit dengan kunci API,
URL dasar kustom, atau endpoint Azure saat Anda menginginkan rute OpenAI Images API
langsung sebagai gantinya.
Jika endpoint gambar kustom itu berada pada alamat LAN/pribadi tepercaya, tetapkan juga
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`; OpenClaw tetap
memblokir endpoint gambar kompatibel OpenAI privat/internal kecuali opt-in ini
ada.
Buat:
@ -409,15 +403,15 @@ Edit:
## Pembuatan video
Plugin `openai` bawaan mendaftarkan pembuatan video melalui alat `video_generate`.
Plugin `openai` bawaan mendaftarkan pembuatan video melalui tool `video_generate`.
| Kapabilitas | Nilai |
| Kapabilitas | Nilai |
| ---------------- | --------------------------------------------------------------------------------- |
| Model default | `openai/sora-2` |
| Mode | Teks-ke-video, gambar-ke-video, edit video tunggal |
| Input referensi | 1 gambar atau 1 video |
| Override ukuran | Didukung |
| Override lain | `aspectRatio`, `resolution`, `audio`, `watermark` diabaikan dengan peringatan alat |
| Override lain | `aspectRatio`, `resolution`, `audio`, `watermark` diabaikan dengan peringatan tool |
```json5
{
@ -430,25 +424,25 @@ Plugin `openai` bawaan mendaftarkan pembuatan video melalui alat `video_generate
```
<Note>
Lihat [Pembuatan Video](/id/tools/video-generation) untuk parameter alat bersama, pemilihan penyedia, dan perilaku failover.
Lihat [Pembuatan Video](/id/tools/video-generation) untuk parameter tool bersama, pemilihan provider, dan perilaku failover.
</Note>
## Kontribusi prompt GPT-5
OpenClaw menambahkan kontribusi prompt GPT-5 bersama untuk eksekusi keluarga GPT-5 lintas penyedia. Kontribusi ini berlaku berdasarkan id model, jadi `openai-codex/gpt-5.5`, `openai/gpt-5.5`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5`, dan ref GPT-5 kompatibel lainnya menerima overlay yang sama. Model GPT-4.x yang lebih lama tidak.
OpenClaw menambahkan kontribusi prompt GPT-5 bersama untuk run keluarga GPT-5 di seluruh provider. Ini berlaku berdasarkan id model, sehingga `openai-codex/gpt-5.5`, `openai/gpt-5.5`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5`, dan ref GPT-5 kompatibel lainnya menerima overlay yang sama. Model GPT-4.x yang lebih lama tidak.
Harness Codex native bawaan menggunakan perilaku GPT-5 dan overlay Heartbeat yang sama melalui instruksi developer app-server Codex, jadi sesi `openai/gpt-5.x` yang dipaksa melalui `agentRuntime.id: "codex"` mempertahankan panduan tindak lanjut dan Heartbeat proaktif yang sama meskipun Codex memiliki sisa prompt harness.
Harness Codex native bawaan menggunakan perilaku GPT-5 dan overlay Heartbeat yang sama melalui instruksi developer app-server Codex, sehingga sesi `openai/gpt-5.x` yang dipaksa melalui `agentRuntime.id: "codex"` mempertahankan panduan tindak lanjut dan Heartbeat proaktif yang sama meskipun Codex memiliki sisa prompt harness.
Kontribusi GPT-5 menambahkan kontrak perilaku bertag untuk persistensi persona, keamanan eksekusi, disiplin alat, bentuk output, pemeriksaan penyelesaian, dan verifikasi. Perilaku balasan khusus channel dan pesan senyap tetap berada di prompt sistem OpenClaw bersama dan kebijakan pengiriman keluar. Panduan GPT-5 selalu diaktifkan untuk model yang cocok. Lapisan gaya interaksi ramah terpisah dan dapat dikonfigurasi.
Kontribusi GPT-5 menambahkan kontrak perilaku bertag untuk persistensi persona, keselamatan eksekusi, disiplin tool, bentuk output, pemeriksaan penyelesaian, dan verifikasi. Perilaku balasan khusus channel dan pesan senyap tetap berada dalam prompt sistem OpenClaw bersama dan kebijakan pengiriman keluar. Panduan GPT-5 selalu diaktifkan untuk model yang cocok. Lapisan gaya interaksi ramah terpisah dan dapat dikonfigurasi.
| Nilai | Efek |
| ---------------------- | ------------------------------------------ |
| `"friendly"` (default) | Aktifkan lapisan gaya interaksi ramah |
| `"on"` | Alias untuk `"friendly"` |
| Nilai | Efek |
| ---------------------- | ------------------------------------------- |
| `"friendly"` (default) | Aktifkan lapisan gaya interaksi ramah |
| `"on"` | Alias untuk `"friendly"` |
| `"off"` | Nonaktifkan hanya lapisan gaya ramah |
<Tabs>
<Tab title="Konfigurasi">
<Tab title="Config">
```json5
{
agents: {
@ -469,11 +463,11 @@ Kontribusi GPT-5 menambahkan kontrak perilaku bertag untuk persistensi persona,
</Tabs>
<Tip>
Nilai tidak peka huruf besar/kecil saat runtime, jadi `"Off"` dan `"off"` sama-sama menonaktifkan lapisan gaya ramah.
Nilai tidak peka huruf besar-kecil pada runtime, jadi `"Off"` dan `"off"` sama-sama menonaktifkan lapisan gaya ramah.
</Tip>
<Note>
`plugins.entries.openai.config.personality` lama masih dibaca sebagai fallback kompatibilitas ketika pengaturan `agents.defaults.promptOverlays.gpt5.personality` bersama tidak diatur.
`plugins.entries.openai.config.personality` legacy masih dibaca sebagai fallback kompatibilitas saat pengaturan `agents.defaults.promptOverlays.gpt5.personality` bersama belum ditetapkan.
</Note>
## Suara dan ucapan
@ -482,7 +476,7 @@ Nilai tidak peka huruf besar/kecil saat runtime, jadi `"Off"` dan `"off"` sama-s
<Accordion title="Sintesis ucapan (TTS)">
Plugin `openai` bawaan mendaftarkan sintesis ucapan untuk surface `messages.tts`.
| Pengaturan | Path konfigurasi | Default |
| Pengaturan | Jalur config | Default |
|---------|------------|---------|
| Model | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` |
| Suara | `messages.tts.providers.openai.voice` | `coral` |
@ -490,7 +484,7 @@ Nilai tidak peka huruf besar/kecil saat runtime, jadi `"Off"` dan `"off"` sama-s
| Instruksi | `messages.tts.providers.openai.instructions` | (belum diatur, hanya `gpt-4o-mini-tts`) |
| Format | `messages.tts.providers.openai.responseFormat` | `opus` untuk catatan suara, `mp3` untuk file |
| Kunci API | `messages.tts.providers.openai.apiKey` | Fallback ke `OPENAI_API_KEY` |
| Base URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` |
| URL dasar | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` |
Model yang tersedia: `gpt-4o-mini-tts`, `tts-1`, `tts-1-hd`. Suara yang tersedia: `alloy`, `ash`, `ballad`, `cedar`, `coral`, `echo`, `fable`, `juniper`, `marin`, `onyx`, `nova`, `sage`, `shimmer`, `verse`.
@ -507,7 +501,7 @@ Nilai tidak peka huruf besar/kecil saat runtime, jadi `"Off"` dan `"off"` sama-s
```
<Note>
Atur `OPENAI_TTS_BASE_URL` untuk menimpa base URL TTS tanpa memengaruhi endpoint API chat.
Tetapkan `OPENAI_TTS_BASE_URL` untuk meng-override URL dasar TTS tanpa memengaruhi endpoint API chat.
</Note>
</Accordion>
@ -517,13 +511,13 @@ Nilai tidak peka huruf besar/kecil saat runtime, jadi `"Off"` dan `"off"` sama-s
surface transkripsi pemahaman media OpenClaw.
- Model default: `gpt-4o-transcribe`
- Endpoint: REST OpenAI `/v1/audio/transcriptions`
- Path input: upload file audio multipart
- Endpoint: OpenAI REST `/v1/audio/transcriptions`
- Jalur input: upload file audio multipart
- Didukung oleh OpenClaw di mana pun transkripsi audio masuk menggunakan
`tools.media.audio`, termasuk segmen channel suara Discord dan lampiran
audio channel
Untuk memaksa OpenAI bagi transkripsi audio masuk:
Untuk memaksa OpenAI untuk transkripsi audio masuk:
```json5
{
@ -551,7 +545,7 @@ Nilai tidak peka huruf besar/kecil saat runtime, jadi `"Off"` dan `"off"` sama-s
<Accordion title="Transkripsi realtime">
Plugin `openai` bawaan mendaftarkan transkripsi realtime untuk Plugin Voice Call.
| Pengaturan | Jalur konfigurasi | Default |
| Pengaturan | Jalur konfigurasi | Bawaan |
|---------|------------|---------|
| Model | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` |
| Bahasa | `...openai.language` | (belum diatur) |
@ -561,7 +555,7 @@ Nilai tidak peka huruf besar/kecil saat runtime, jadi `"Off"` dan `"off"` sama-s
| Kunci API | `...openai.apiKey` | Menggunakan fallback ke `OPENAI_API_KEY` |
<Note>
Menggunakan koneksi WebSocket ke `wss://api.openai.com/v1/realtime` dengan audio G.711 u-law (`g711_ulaw` / `audio/pcmu`). Penyedia streaming ini ditujukan untuk jalur transkripsi realtime Voice Call; suara Discord saat ini merekam segmen pendek dan menggunakan jalur transkripsi batch `tools.media.audio` sebagai gantinya.
Menggunakan koneksi WebSocket ke `wss://api.openai.com/v1/realtime` dengan audio G.711 u-law (`g711_ulaw` / `audio/pcmu`). Penyedia streaming ini digunakan untuk jalur transkripsi realtime Voice Call; suara Discord saat ini merekam segmen pendek dan menggunakan jalur transkripsi batch `tools.media.audio`.
</Note>
</Accordion>
@ -569,25 +563,25 @@ Nilai tidak peka huruf besar/kecil saat runtime, jadi `"Off"` dan `"off"` sama-s
<Accordion title="Suara realtime">
Plugin `openai` bawaan mendaftarkan suara realtime untuk Plugin Voice Call.
| Pengaturan | Jalur konfigurasi | Default |
| Pengaturan | Jalur konfigurasi | Bawaan |
|---------|------------|---------|
| Model | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime-1.5` |
| Suara | `...openai.voice` | `alloy` |
| Temperature | `...openai.temperature` | `0.8` |
| Suhu | `...openai.temperature` | `0.8` |
| Ambang VAD | `...openai.vadThreshold` | `0.5` |
| Durasi hening | `...openai.silenceDurationMs` | `500` |
| Kunci API | `...openai.apiKey` | Menggunakan fallback ke `OPENAI_API_KEY` |
<Note>
Mendukung Azure OpenAI melalui kunci konfigurasi `azureEndpoint` dan `azureDeployment` untuk bridge realtime backend. Mendukung pemanggilan tool dua arah. Menggunakan format audio G.711 u-law.
Mendukung Azure OpenAI melalui kunci konfigurasi `azureEndpoint` dan `azureDeployment` untuk bridge realtime backend. Mendukung pemanggilan alat dua arah. Menggunakan format audio G.711 u-law.
</Note>
<Note>
Control UI Talk menggunakan sesi realtime browser OpenAI dengan rahasia klien sementara
yang diterbitkan Gateway dan pertukaran SDP WebRTC browser langsung terhadap
OpenAI Realtime API. Verifikasi live maintainer tersedia dengan
yang dibuat oleh Gateway dan pertukaran SDP WebRTC browser langsung terhadap
OpenAI Realtime API. Verifikasi live oleh maintainer tersedia dengan
`OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts`;
leg OpenAI menerbitkan rahasia klien di Node, menghasilkan penawaran SDP browser
leg OpenAI membuat rahasia klien di Node, menghasilkan tawaran SDP browser
dengan media mikrofon palsu, mempostingnya ke OpenAI, dan menerapkan jawaban SDP
tanpa mencatat rahasia.
</Note>
@ -598,22 +592,23 @@ Nilai tidak peka huruf besar/kecil saat runtime, jadi `"Off"` dan `"off"` sama-s
## Endpoint Azure OpenAI
Penyedia `openai` bawaan dapat menargetkan resource Azure OpenAI untuk pembuatan
gambar dengan menimpa URL dasar. Pada jalur pembuatan gambar, OpenClaw
gambar dengan mengganti URL dasar. Pada jalur pembuatan gambar, OpenClaw
mendeteksi hostname Azure pada `models.providers.openai.baseUrl` dan beralih ke
bentuk permintaan Azure secara otomatis.
<Note>
Suara realtime menggunakan jalur konfigurasi terpisah
(`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`)
dan tidak dipengaruhi oleh `models.providers.openai.baseUrl`. Lihat akordeon **Suara
realtime** di bawah [Suara dan ucapan](#voice-and-speech) untuk pengaturan Azure-nya.
dan tidak terpengaruh oleh `models.providers.openai.baseUrl`. Lihat accordion
**Suara realtime** di bawah [Suara dan ucapan](#voice-and-speech) untuk pengaturan
Azure-nya.
</Note>
Gunakan Azure OpenAI saat:
- Anda sudah memiliki langganan, kuota, atau perjanjian perusahaan Azure OpenAI
- Anda membutuhkan residensi data regional atau kontrol kepatuhan yang disediakan Azure
- Anda ingin menjaga traffic tetap di dalam tenancy Azure yang sudah ada
- Anda sudah memiliki langganan Azure OpenAI, kuota, atau perjanjian enterprise
- Anda memerlukan residensi data regional atau kontrol kepatuhan yang disediakan Azure
- Anda ingin menjaga lalu lintas tetap di dalam tenancy Azure yang sudah ada
### Konfigurasi
@ -634,7 +629,7 @@ kunci Azure OpenAI (bukan kunci OpenAI Platform):
}
```
OpenClaw mengenali sufiks host Azure ini untuk rute pembuatan gambar Azure:
OpenClaw mengenali sufiks host Azure berikut untuk rute pembuatan gambar Azure:
- `*.openai.azure.com`
- `*.services.ai.azure.com`
@ -642,39 +637,41 @@ OpenClaw mengenali sufiks host Azure ini untuk rute pembuatan gambar Azure:
Untuk permintaan pembuatan gambar pada host Azure yang dikenali, OpenClaw:
- Mengirim header `api-key` alih-alih `Authorization: Bearer`
- Menggunakan jalur berskup deployment (`/openai/deployments/{deployment}/...`)
- Mengirim header `api-key`, bukan `Authorization: Bearer`
- Menggunakan path berbasis deployment (`/openai/deployments/{deployment}/...`)
- Menambahkan `?api-version=...` ke setiap permintaan
- Menggunakan timeout permintaan default 600 detik untuk panggilan pembuatan gambar Azure.
Nilai `timeoutMs` per panggilan tetap menimpa default ini.
- Menggunakan batas waktu permintaan bawaan 600 detik untuk panggilan pembuatan gambar Azure.
Nilai `timeoutMs` per panggilan tetap mengganti bawaan ini.
URL dasar lain (OpenAI publik, proxy yang kompatibel dengan OpenAI) tetap menggunakan bentuk permintaan gambar OpenAI standar.
URL dasar lainnya (OpenAI publik, proxy kompatibel OpenAI) tetap menggunakan bentuk
permintaan gambar OpenAI standar.
<Note>
Routing Azure untuk jalur pembuatan gambar penyedia `openai` memerlukan
OpenClaw 2026.4.22 atau lebih baru. Versi lebih lama memperlakukan setiap
`openai.baseUrl` kustom seperti endpoint OpenAI publik dan akan gagal terhadap deployment gambar Azure.
OpenClaw 2026.4.22 atau yang lebih baru. Versi lebih lama memperlakukan
`openai.baseUrl` kustom apa pun seperti endpoint OpenAI publik dan akan gagal pada
deployment gambar Azure.
</Note>
### Versi API
Atur `AZURE_OPENAI_API_VERSION` untuk mematok versi pratinjau atau GA Azure tertentu
bagi jalur pembuatan gambar Azure:
Atur `AZURE_OPENAI_API_VERSION` untuk menyematkan versi pratinjau atau GA Azure tertentu
untuk jalur pembuatan gambar Azure:
```bash
export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
```
Default-nya adalah `2024-12-01-preview` saat variabel tidak diatur.
Bawaannya adalah `2024-12-01-preview` saat variabel tidak diatur.
### Nama model adalah nama deployment
Azure OpenAI mengikat model ke deployment. Untuk permintaan pembuatan gambar Azure
yang dirutekan melalui penyedia `openai` bawaan, bidang `model` di OpenClaw
harus berupa **nama deployment Azure** yang Anda konfigurasikan di portal Azure, bukan
yang dirutekan melalui penyedia `openai` bawaan, kolom `model` di OpenClaw
harus berupa **nama deployment Azure** yang Anda konfigurasi di portal Azure, bukan
id model OpenAI publik.
Jika Anda membuat deployment bernama `gpt-image-2-prod` yang menyajikan `gpt-image-2`:
Jika Anda membuat deployment bernama `gpt-image-2-prod` yang melayani `gpt-image-2`:
```
/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1
@ -685,7 +682,7 @@ penyedia `openai` bawaan.
### Ketersediaan regional
Pembuatan gambar Azure saat ini hanya tersedia di subset region
Pembuatan gambar Azure saat ini hanya tersedia di sebagian region
(misalnya `eastus2`, `swedencentral`, `polandcentral`, `westus3`,
`uaenorth`). Periksa daftar region Microsoft terbaru sebelum membuat
deployment, dan pastikan model tertentu ditawarkan di region Anda.
@ -694,22 +691,22 @@ deployment, dan pastikan model tertentu ditawarkan di region Anda.
Azure OpenAI dan OpenAI publik tidak selalu menerima parameter gambar yang sama.
Azure dapat menolak opsi yang diizinkan OpenAI publik (misalnya nilai
`background` tertentu pada `gpt-image-2`) atau hanya mengeksposnya pada versi model
`background` tertentu pada `gpt-image-2`) atau mengeksposnya hanya pada versi model
tertentu. Perbedaan ini berasal dari Azure dan model yang mendasarinya, bukan
OpenClaw. Jika permintaan Azure gagal dengan galat validasi, periksa
kumpulan parameter yang didukung oleh deployment dan versi API spesifik Anda di
OpenClaw. Jika permintaan Azure gagal dengan kesalahan validasi, periksa
set parameter yang didukung oleh deployment dan versi API spesifik Anda di
portal Azure.
<Note>
Azure OpenAI menggunakan transport native dan perilaku kompatibilitas tetapi tidak menerima
header atribusi tersembunyi OpenClaw — lihat akordeon **Rute native vs yang kompatibel dengan OpenAI**
header atribusi tersembunyi OpenClaw — lihat accordion **Rute native vs kompatibel OpenAI**
di bawah [Konfigurasi lanjutan](#advanced-configuration).
Untuk traffic chat atau Responses di Azure (di luar pembuatan gambar), gunakan
Untuk lalu lintas chat atau Responses di Azure (di luar pembuatan gambar), gunakan
alur onboarding atau konfigurasi penyedia Azure khusus — `openai.baseUrl` saja
tidak mengambil bentuk API/auth Azure. Penyedia
tidak memakai bentuk API/auth Azure. Penyedia
`azure-openai-responses/*` terpisah tersedia; lihat
akordeon Compaction sisi server di bawah.
accordion Compaction sisi server di bawah.
</Note>
## Konfigurasi lanjutan
@ -720,13 +717,13 @@ akordeon Compaction sisi server di bawah.
Dalam mode `"auto"`, OpenClaw:
- Mencoba ulang satu kegagalan WebSocket awal sebelum fallback ke SSE
- Setelah kegagalan, menandai WebSocket sebagai terdegradasi selama ~60 detik dan menggunakan SSE selama masa pendinginan
- Melampirkan header identitas sesi dan giliran yang stabil untuk percobaan ulang dan koneksi ulang
- Menormalkan penghitung penggunaan (`input_tokens` / `prompt_tokens`) lintas varian transport
- Setelah kegagalan, menandai WebSocket sebagai terdegradasi selama ~60 detik dan menggunakan SSE selama masa jeda
- Melampirkan header identitas sesi dan turn yang stabil untuk percobaan ulang dan koneksi ulang
- Menormalkan penghitung penggunaan (`input_tokens` / `prompt_tokens`) di seluruh varian transport
| Nilai | Perilaku |
|-------|----------|
| `"auto"` (default) | WebSocket terlebih dahulu, fallback SSE |
| `"auto"` (bawaan) | WebSocket terlebih dahulu, fallback SSE |
| `"sse"` | Paksa hanya SSE |
| `"websocket"` | Paksa hanya WebSocket |
@ -754,7 +751,7 @@ akordeon Compaction sisi server di bawah.
</Accordion>
<Accordion title="Pemanasan WebSocket">
OpenClaw mengaktifkan pemanasan WebSocket secara default untuk `openai/*` dan `openai-codex/*` guna mengurangi latensi giliran pertama.
OpenClaw mengaktifkan pemanasan WebSocket secara bawaan untuk `openai/*` dan `openai-codex/*` guna mengurangi latensi turn pertama.
```json5
// Disable warm-up
@ -794,7 +791,7 @@ akordeon Compaction sisi server di bawah.
```
<Note>
Penimpaan sesi mengalahkan konfigurasi. Menghapus penimpaan sesi di UI Sessions mengembalikan sesi ke default yang dikonfigurasi.
Override sesi mengalahkan konfigurasi. Menghapus override sesi di UI Sessions mengembalikan sesi ke bawaan yang dikonfigurasi.
</Note>
</Accordion>
@ -823,17 +820,17 @@ akordeon Compaction sisi server di bawah.
</Accordion>
<Accordion title="Compaction sisi server (Responses API)">
Untuk model OpenAI Responses langsung (`openai/*` pada `api.openai.com`), wrapper streaming Pi-harness Plugin OpenAI mengaktifkan otomatis Compaction sisi server:
Untuk model OpenAI Responses langsung (`openai/*` pada `api.openai.com`), wrapper stream Pi-harness Plugin OpenAI mengaktifkan otomatis Compaction sisi server:
- Memaksa `store: true` (kecuali kompatibilitas model menetapkan `supportsStore: false`)
- Memaksa `store: true` (kecuali compat model menetapkan `supportsStore: false`)
- Menyisipkan `context_management: [{ type: "compaction", compact_threshold: ... }]`
- `compact_threshold` default: 70% dari `contextWindow` (atau `80000` saat tidak tersedia)
- `compact_threshold` bawaan: 70% dari `contextWindow` (atau `80000` saat tidak tersedia)
Ini berlaku untuk jalur Pi harness bawaan dan hook penyedia OpenAI yang digunakan oleh run tertanam. Harness app-server Codex native mengelola konteksnya sendiri melalui Codex dan dikonfigurasi secara terpisah dengan `agents.defaults.agentRuntime.id`.
<Tabs>
<Tab title="Aktifkan secara eksplisit">
Berguna untuk endpoint yang kompatibel seperti Azure OpenAI Responses:
Berguna untuk endpoint kompatibel seperti Azure OpenAI Responses:
```json5
{
@ -849,7 +846,7 @@ akordeon Compaction sisi server di bawah.
}
```
</Tab>
<Tab title="Ambang batas khusus">
<Tab title="Ambang batas kustom">
```json5
{
agents: {
@ -904,33 +901,33 @@ akordeon Compaction sisi server di bawah.
```
Dengan `strict-agentic`, OpenClaw:
- Tidak lagi memperlakukan giliran yang hanya berisi rencana sebagai progres yang berhasil ketika tindakan tool tersedia
- Mencoba ulang giliran dengan arahan bertindak sekarang
- Mengaktifkan otomatis `update_plan` untuk pekerjaan substansial
- Tidak lagi memperlakukan giliran yang hanya berupa rencana sebagai progres berhasil ketika tindakan alat tersedia
- Mencoba ulang giliran dengan arahan untuk bertindak sekarang
- Mengaktifkan otomatis `update_plan` untuk pekerjaan yang substansial
- Menampilkan status terblokir eksplisit jika model terus merencanakan tanpa bertindak
<Note>
Hanya berlaku untuk proses keluarga GPT-5 OpenAI dan Codex. Penyedia lain dan keluarga model yang lebih lama mempertahankan perilaku bawaan.
Hanya berlaku untuk proses keluarga OpenAI dan Codex GPT-5. Penyedia lain dan keluarga model yang lebih lama tetap memakai perilaku default.
</Note>
</Accordion>
<Accordion title="Rute native vs kompatibel OpenAI">
OpenClaw memperlakukan endpoint OpenAI langsung, Codex, dan Azure OpenAI berbeda dari proxy `/v1` kompatibel OpenAI generik:
OpenClaw memperlakukan endpoint OpenAI langsung, Codex, dan Azure OpenAI secara berbeda dari proxy `/v1` kompatibel OpenAI generik:
**Rute native** (`openai/*`, Azure OpenAI):
- Mempertahankan `reasoning: { effort: "none" }` hanya untuk model yang mendukung effort `none` OpenAI
- Menghilangkan reasoning yang dinonaktifkan untuk model atau proxy yang menolak `reasoning.effort: "none"`
- Menetapkan skema tool bawaan ke mode ketat
- Melampirkan header atribusi tersembunyi hanya pada host native terverifikasi
- Mempertahankan pembentukan request khusus OpenAI (`service_tier`, `store`, reasoning-compat, petunjuk prompt-cache)
- Mempertahankan `reasoning: { effort: "none" }` hanya untuk model yang mendukung upaya `none` OpenAI
- Menghilangkan penalaran yang dinonaktifkan untuk model atau proxy yang menolak `reasoning.effort: "none"`
- Menetapkan skema alat secara default ke mode ketat
- Melampirkan header atribusi tersembunyi hanya pada host native yang terverifikasi
- Mempertahankan pembentukan permintaan khusus OpenAI (`service_tier`, `store`, reasoning-compat, petunjuk prompt-cache)
**Rute proxy/kompatibel:**
- Menggunakan perilaku compat yang lebih longgar
- Menghapus Completions `store` dari payload `openai-completions` non-native
- Menghapus `store` Completions dari payload `openai-completions` non-native
- Menerima JSON pass-through `params.extra_body`/`params.extraBody` lanjutan untuk proxy Completions kompatibel OpenAI
- Menerima `params.chat_template_kwargs` untuk proxy Completions kompatibel OpenAI seperti vLLM
- Tidak memaksakan skema tool ketat atau header khusus native
- Tidak memaksa skema alat ketat atau header khusus native
Azure OpenAI menggunakan transport native dan perilaku compat tetapi tidak menerima header atribusi tersembunyi.
@ -944,10 +941,10 @@ akordeon Compaction sisi server di bawah.
Memilih penyedia, referensi model, dan perilaku failover.
</Card>
<Card title="Pembuatan gambar" href="/id/tools/image-generation" icon="image">
Parameter tool gambar bersama dan pemilihan penyedia.
Parameter alat gambar bersama dan pemilihan penyedia.
</Card>
<Card title="Pembuatan video" href="/id/tools/video-generation" icon="video">
Parameter tool video bersama dan pemilihan penyedia.
Parameter alat video bersama dan pemilihan penyedia.
</Card>
<Card title="OAuth dan auth" href="/id/gateway/authentication" icon="key">
Detail auth dan aturan penggunaan ulang kredensial.

342
docs/id/reference/memory-config.md
View File

@ -1,17 +1,17 @@
---
read_when:
- Anda ingin mengonfigurasi penyedia pencarian memori atau model embedding
- Anda ingin mengonfigurasi penyedia pencarian memori atau model penyematan
- Anda ingin menyiapkan backend QMD
- Anda ingin menyetel pencarian hibrida, MMR, atau peluruhan temporal
- Anda ingin mengaktifkan pengindeksan memori multimodal
sidebarTitle: Memory config
summary: Semua opsi konfigurasi untuk pencarian memori, penyedia penyematan, QMD, pencarian hibrida, dan pengindeksan multimodal
summary: Semua pengaturan konfigurasi untuk pencarian memori, penyedia embedding, QMD, pencarian hibrida, dan pengindeksan multimodal
title: Referensi konfigurasi memori
x-i18n:
generated_at: "2026-04-30T10:10:32Z"
generated_at: "2026-04-30T16:29:59Z"
model: gpt-5.5
provider: openai
source_hash: fbb21d407f7ec9ef76e68c268138892b12568137735b723579703e535d34b195
source_hash: 58b75751a19afb883fd7646cf5f71859f95bac468b2bfd8cc79db12ae892f70f
source_path: reference/memory-config.md
workflow: 16
---
@ -19,57 +19,57 @@ x-i18n:
Halaman ini mencantumkan setiap tombol konfigurasi untuk pencarian memori OpenClaw. Untuk ikhtisar konseptual, lihat:
<CardGroup cols={2}>
<Card title="Ikhtisar memori" href="/id/concepts/memory">
<Card title="Memory overview" href="/id/concepts/memory">
Cara kerja memori.
</Card>
<Card title="Mesin bawaan" href="/id/concepts/memory-builtin">
Backend SQLite bawaan.
<Card title="Builtin engine" href="/id/concepts/memory-builtin">
Backend SQLite default.
</Card>
<Card title="Mesin QMD" href="/id/concepts/memory-qmd">
<Card title="QMD engine" href="/id/concepts/memory-qmd">
Sidecar yang mengutamakan lokal.
</Card>
<Card title="Pencarian memori" href="/id/concepts/memory-search">
Pipeline pencarian dan penyetelan.
<Card title="Memory search" href="/id/concepts/memory-search">
Pipeline pencarian dan penyesuaian.
</Card>
<Card title="Active memory" href="/id/concepts/active-memory">
Sub-agen memori untuk sesi interaktif.
</Card>
</CardGroup>
Semua pengaturan pencarian memori berada di bawah `agents.defaults.memorySearch` dalam `openclaw.json` kecuali dinyatakan lain.
Semua pengaturan pencarian memori berada di bawah `agents.defaults.memorySearch` dalam `openclaw.json` kecuali disebutkan lain.
<Note>
Jika Anda mencari toggle fitur **active memory** dan konfigurasi sub-agennya, itu berada di bawah `plugins.entries.active-memory`, bukan `memorySearch`.
Jika Anda mencari toggle fitur **active memory** dan konfigurasi sub-agen, itu berada di bawah `plugins.entries.active-memory`, bukan `memorySearch`.
Active memory menggunakan model dua gerbang:
1. Plugin harus diaktifkan dan menargetkan id agen saat ini
2. Permintaan harus berupa sesi obrolan persisten interaktif yang memenuhi syarat
1. plugin harus diaktifkan dan menargetkan id agen saat ini
2. permintaan harus merupakan sesi chat persisten interaktif yang memenuhi syarat
Lihat [Active Memory](/id/concepts/active-memory) untuk model aktivasi, konfigurasi milik Plugin, persistensi transkrip, dan pola peluncuran aman.
Lihat [Active Memory](/id/concepts/active-memory) untuk model aktivasi, konfigurasi milik plugin, persistensi transkrip, dan pola peluncuran aman.
</Note>
---
## Pemilihan penyedia
| Kunci | Tipe | Bawaan | Deskripsi |
| ---------- | --------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider` | `string` | terdeteksi otomatis | ID adaptor embedding seperti `bedrock`, `deepinfra`, `gemini`, `github-copilot`, `local`, `mistral`, `ollama`, `openai`, atau `voyage`; juga dapat berupa `models.providers.<id>` yang dikonfigurasi dengan `api` yang mengarah ke salah satu adaptor tersebut |
| `model` | `string` | bawaan penyedia | Nama model embedding |
| `fallback` | `string` | `"none"` | ID adaptor fallback saat yang utama gagal |
| `enabled` | `boolean` | `true` | Aktifkan atau nonaktifkan pencarian memori |
| Kunci | Tipe | Default | Deskripsi |
| ---------- | --------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider` | `string` | terdeteksi otomatis | ID adaptor embedding seperti `bedrock`, `deepinfra`, `gemini`, `github-copilot`, `local`, `mistral`, `ollama`, `openai`, atau `voyage`; juga dapat berupa `models.providers.<id>` yang dikonfigurasi dengan `api` yang mengarah ke salah satu adaptor tersebut |
| `model` | `string` | default penyedia | Nama model embedding |
| `fallback` | `string` | `"none"` | ID adaptor fallback ketika yang utama gagal |
| `enabled` | `boolean` | `true` | Aktifkan atau nonaktifkan pencarian memori |
### Urutan deteksi otomatis
Saat `provider` tidak disetel, OpenClaw memilih yang pertama tersedia:
Ketika `provider` tidak diatur, OpenClaw memilih yang pertama tersedia:
<Steps>
<Step title="local">
Dipilih jika `memorySearch.local.modelPath` dikonfigurasi dan file tersebut ada.
</Step>
<Step title="github-copilot">
Dipilih jika token GitHub Copilot dapat di-resolve (variabel env atau profil auth).
Dipilih jika token GitHub Copilot dapat di-resolve (env var atau profil auth).
</Step>
<Step title="openai">
Dipilih jika kunci OpenAI dapat di-resolve.
@ -87,15 +87,15 @@ Saat `provider` tidak disetel, OpenClaw memilih yang pertama tersedia:
Dipilih jika kunci DeepInfra dapat di-resolve.
</Step>
<Step title="bedrock">
Dipilih jika rantai kredensial AWS SDK berhasil di-resolve (peran instance, kunci akses, profil, SSO, identitas web, atau konfigurasi bersama).
Dipilih jika rantai kredensial AWS SDK berhasil di-resolve (role instans, kunci akses, profil, SSO, identitas web, atau konfigurasi bersama).
</Step>
</Steps>
`ollama` didukung tetapi tidak terdeteksi otomatis (setel secara eksplisit).
`ollama` didukung tetapi tidak terdeteksi otomatis (atur secara eksplisit).
### ID penyedia kustom
`memorySearch.provider` dapat mengarah ke entri `models.providers.<id>` kustom. OpenClaw me-resolve pemilik `api` penyedia tersebut untuk adaptor embedding sambil mempertahankan id penyedia kustom untuk penanganan endpoint, auth, dan prefiks model. Ini memungkinkan setup multi-GPU atau multi-host mendedikasikan embedding memori ke endpoint lokal tertentu:
`memorySearch.provider` dapat menunjuk ke entri `models.providers.<id>` kustom. OpenClaw me-resolve pemilik `api` penyedia tersebut untuk adaptor embedding sambil mempertahankan id penyedia kustom untuk penanganan endpoint, auth, dan prefiks model. Ini memungkinkan setup multi-GPU atau multi-host mendedikasikan embedding memori ke endpoint lokal tertentu:
```json5
{
@ -122,9 +122,9 @@ Saat `provider` tidak disetel, OpenClaw memilih yang pertama tersedia:
### Resolusi kunci API
Embedding jarak jauh memerlukan kunci API. Bedrock menggunakan rantai kredensial bawaan AWS SDK sebagai gantinya (peran instance, SSO, kunci akses).
Embedding jarak jauh memerlukan kunci API. Bedrock menggunakan rantai kredensial default AWS SDK sebagai gantinya (role instans, SSO, kunci akses).
| Penyedia | Variabel env | Kunci konfigurasi |
| Penyedia | Env var | Kunci konfigurasi |
| -------------- | -------------------------------------------------- | ----------------------------------- |
| Bedrock | Rantai kredensial AWS | Tidak perlu kunci API |
| DeepInfra | `DEEPINFRA_API_KEY` | `models.providers.deepinfra.apiKey` |
@ -136,23 +136,23 @@ Embedding jarak jauh memerlukan kunci API. Bedrock menggunakan rantai kredensial
| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` |
<Note>
Codex OAuth hanya mencakup chat/completions dan tidak memenuhi permintaan embedding.
OAuth Codex hanya mencakup chat/completions dan tidak memenuhi permintaan embedding.
</Note>
---
## Konfigurasi endpoint jarak jauh
Untuk endpoint kustom yang kompatibel dengan OpenAI atau mengganti bawaan penyedia:
Untuk endpoint kustom yang kompatibel dengan OpenAI atau menimpa default penyedia:
<ParamField path="remote.baseUrl" type="string">
URL basis API kustom.
URL dasar API kustom.
</ParamField>
<ParamField path="remote.apiKey" type="string">
Ganti kunci API.
Timpa kunci API.
</ParamField>
<ParamField path="remote.headers" type="object">
Header HTTP tambahan (digabung dengan bawaan penyedia).
Header HTTP tambahan (digabung dengan default penyedia).
</ParamField>
```json5
@ -178,24 +178,24 @@ Untuk endpoint kustom yang kompatibel dengan OpenAI atau mengganti bawaan penyed
<AccordionGroup>
<Accordion title="Gemini">
| Kunci | Tipe | Bawaan | Deskripsi |
| Kunci | Tipe | Default | Deskripsi |
| ---------------------- | -------- | ---------------------- | ------------------------------------------ |
| `model` | `string` | `gemini-embedding-001` | Juga mendukung `gemini-embedding-2-preview` |
| `outputDimensionality` | `number` | `3072` | Untuk Embedding 2: 768, 1536, atau 3072 |
<Warning>
Mengubah model atau `outputDimensionality` memicu reindeks penuh otomatis.
Mengubah model atau `outputDimensionality` memicu pengindeksan ulang penuh otomatis.
</Warning>
</Accordion>
<Accordion title="Tipe input yang kompatibel dengan OpenAI">
<Accordion title="OpenAI-compatible input types">
Endpoint embedding yang kompatibel dengan OpenAI dapat ikut menggunakan field permintaan `input_type` khusus penyedia. Ini berguna untuk model embedding asimetris yang memerlukan label berbeda untuk embedding kueri dan dokumen.
| Kunci | Tipe | Bawaan | Deskripsi |
| ------------------- | -------- | ------------- | -------------------------------------------------------- |
| `inputType` | `string` | belum disetel | `input_type` bersama untuk embedding kueri dan dokumen |
| `queryInputType` | `string` | belum disetel | `input_type` saat kueri; mengganti `inputType` |
| `documentInputType` | `string` | belum disetel | `input_type` indeks/dokumen; mengganti `inputType` |
| Kunci | Tipe | Default | Deskripsi |
| ------------------- | -------- | ------------- | ------------------------------------------------------ |
| `inputType` | `string` | tidak diatur | `input_type` bersama untuk embedding kueri dan dokumen |
| `queryInputType` | `string` | tidak diatur | `input_type` saat kueri; menimpa `inputType` |
| `documentInputType` | `string` | tidak diatur | `input_type` indeks/dokumen; menimpa `inputType` |
```json5
{
@ -216,11 +216,11 @@ Untuk endpoint kustom yang kompatibel dengan OpenAI atau mengganti bawaan penyed
}
```
Mengubah nilai-nilai ini memengaruhi identitas cache embedding untuk pengindeksan batch penyedia dan sebaiknya diikuti dengan reindeks memori saat model upstream memperlakukan label-label tersebut secara berbeda.
Mengubah nilai-nilai ini memengaruhi identitas cache embedding untuk pengindeksan batch penyedia dan harus diikuti dengan pengindeksan ulang memori ketika model upstream memperlakukan label tersebut secara berbeda.
</Accordion>
<Accordion title="Bedrock">
Bedrock menggunakan rantai kredensial bawaan AWS SDK — tidak perlu kunci API. Jika OpenClaw berjalan di EC2 dengan peran instance yang mendukung Bedrock, cukup setel penyedia dan model:
Bedrock menggunakan rantai kredensial default AWS SDK — tidak perlu kunci API. Jika OpenClaw berjalan di EC2 dengan role instans yang mengaktifkan Bedrock, cukup atur penyedia dan model:
```json5
{
@ -235,39 +235,39 @@ Untuk endpoint kustom yang kompatibel dengan OpenAI atau mengganti bawaan penyed
}
```
| Kunci | Tipe | Bawaan | Deskripsi |
| ---------------------- | -------- | ----------------------------- | ---------------------------- |
| Kunci | Tipe | Default | Deskripsi |
| ---------------------- | -------- | ------------------------------ | ----------------------------- |
| `model` | `string` | `amazon.titan-embed-text-v2:0` | ID model embedding Bedrock apa pun |
| `outputDimensionality` | `number` | bawaan model | Untuk Titan V2: 256, 512, atau 1024 |
| `outputDimensionality` | `number` | default model | Untuk Titan V2: 256, 512, atau 1024 |
**Model yang didukung** (dengan deteksi family dan bawaan dimensi):
**Model yang didukung** (dengan deteksi keluarga dan default dimensi):
| ID Model | Penyedia | Dim Bawaan | Dim yang Dapat Dikonfigurasi |
| ------------------------------------------ | ---------- | ---------- | ---------------------------- |
| `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256, 512, 1024 |
| `amazon.titan-embed-text-v1` | Amazon | 1536 | -- |
| `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- |
| `amazon.titan-embed-image-v1` | Amazon | 1024 | -- |
| `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256, 384, 1024, 3072 |
| `cohere.embed-english-v3` | Cohere | 1024 | -- |
| `cohere.embed-multilingual-v3` | Cohere | 1024 | -- |
| `cohere.embed-v4:0` | Cohere | 1536 | 256-1536 |
| `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- |
| `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- |
| ID Model | Penyedia | Dim Default | Dim yang Dapat Dikonfigurasi |
| ------------------------------------------ | ---------- | ----------- | ---------------------------- |
| `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256, 512, 1024 |
| `amazon.titan-embed-text-v1` | Amazon | 1536 | -- |
| `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- |
| `amazon.titan-embed-image-v1` | Amazon | 1024 | -- |
| `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256, 384, 1024, 3072 |
| `cohere.embed-english-v3` | Cohere | 1024 | -- |
| `cohere.embed-multilingual-v3` | Cohere | 1024 | -- |
| `cohere.embed-v4:0` | Cohere | 1536 | 256-1536 |
| `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- |
| `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- |
Varian bersufiks throughput (misalnya, `amazon.titan-embed-text-v1:2:8k`) mewarisi konfigurasi model dasar.
**Autentikasi:** Auth Bedrock menggunakan urutan resolusi kredensial AWS SDK standar:
**Autentikasi:** auth Bedrock menggunakan urutan resolusi kredensial AWS SDK standar:
1. Variabel lingkungan (`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`)
2. Cache token SSO
3. Kredensial token identitas web
4. Kredensial bersama dan file konfigurasi
4. File kredensial dan konfigurasi bersama
5. Kredensial metadata ECS atau EC2
Region di-resolve dari `AWS_REGION`, `AWS_DEFAULT_REGION`, `baseUrl` penyedia `amazon-bedrock`, atau default ke `us-east-1`.
**Izin IAM:** peran atau pengguna IAM memerlukan:
**Izin IAM:** role atau pengguna IAM memerlukan:
```json
{
@ -277,30 +277,30 @@ Untuk endpoint kustom yang kompatibel dengan OpenAI atau mengganti bawaan penyed
}
```
Untuk hak akses paling minimal, batasi cakupan `InvokeModel` ke model tertentu:
Untuk hak akses paling terbatas, batasi cakupan `InvokeModel` ke model tertentu:
```
arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
```
</Accordion>
<Accordion title="Lokal (GGUF + node-llama-cpp)">
| Kunci | Tipe | Default | Deskripsi |
| --------------------- | ------------------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `local.modelPath` | `string` | diunduh otomatis | Path ke berkas model GGUF |
| `local.modelCacheDir` | `string` | default node-llama-cpp | Direktori cache untuk model yang diunduh |
| `local.contextSize` | `number \| "auto"` | `4096` | Ukuran jendela konteks untuk konteks embedding. 4096 mencakup chunk umum (128–512 token) sambil membatasi VRAM non-bobot. Turunkan ke 1024–2048 pada host terbatas. `"auto"` menggunakan maksimum terlatih model — tidak disarankan untuk model 8B+ (Qwen3-Embedding-8B: 40 960 token → ~32 GB VRAM vs ~8,8 GB pada 4096). |
<Accordion title="Local (GGUF + node-llama-cpp)">
| Kunci | Tipe | Bawaan | Deskripsi |
| --------------------- | ------------------ | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `local.modelPath` | `string` | diunduh otomatis | Jalur ke berkas model GGUF |
| `local.modelCacheDir` | `string` | bawaan node-llama-cpp | Direktori cache untuk model yang diunduh |
| `local.contextSize` | `number \| "auto"` | `4096` | Ukuran jendela konteks untuk konteks embedding. 4096 mencakup potongan umum (128–512 token) sambil membatasi VRAM non-bobot. Turunkan ke 1024–2048 pada host terbatas. `"auto"` menggunakan maksimum terlatih model — tidak direkomendasikan untuk model 8B+ (Qwen3-Embedding-8B: 40 960 token → ~32 GB VRAM dibanding ~8,8 GB pada 4096). |
Model default: `embeddinggemma-300m-qat-Q8_0.gguf` (~0,6 GB, diunduh otomatis). Memerlukan build native: `pnpm approve-builds` lalu `pnpm rebuild node-llama-cpp`.
Model bawaan: `embeddinggemma-300m-qat-Q8_0.gguf` (~0,6 GB, diunduh otomatis). Instalasi terpaket memperbaiki runtime native `node-llama-cpp` melalui dependensi runtime Plugin terkelola ketika `provider: "local"` dikonfigurasi. Checkout sumber tetap memerlukan persetujuan build native: `pnpm approve-builds` lalu `pnpm rebuild node-llama-cpp`.
Gunakan CLI mandiri untuk memverifikasi path penyedia yang sama dengan yang digunakan Gateway:
Gunakan CLI mandiri untuk memverifikasi jalur penyedia yang sama dengan yang digunakan Gateway:
```bash
openclaw memory status --deep --agent main
openclaw memory index --force --agent main
```
Jika `provider` adalah `auto`, `local` dipilih hanya ketika `local.modelPath` menunjuk ke berkas lokal yang sudah ada. Referensi model `hf:` dan HTTP(S) masih dapat digunakan secara eksplisit dengan `provider: "local"`, tetapi referensi tersebut tidak membuat `auto` memilih lokal sebelum model tersedia di disk.
Jika `provider` adalah `auto`, `local` hanya dipilih ketika `local.modelPath` menunjuk ke berkas lokal yang ada. Referensi model `hf:` dan HTTP(S) tetap dapat digunakan secara eksplisit dengan `provider: "local"`, tetapi referensi tersebut tidak membuat `auto` memilih lokal sebelum model tersedia di disk.
</Accordion>
</AccordionGroup>
@ -308,9 +308,9 @@ Untuk endpoint kustom yang kompatibel dengan OpenAI atau mengganti bawaan penyed
### Timeout embedding inline
<ParamField path="sync.embeddingBatchTimeoutSeconds" type="number">
Timpa timeout untuk batch embedding inline selama pengindeksan memori.
Ganti timeout untuk batch embedding inline selama pengindeksan memori.
Jika tidak diatur, gunakan default penyedia: 600 detik untuk penyedia lokal/self-hosted seperti `local`, `ollama`, dan `lmstudio`, serta 120 detik untuk penyedia hosted. Tingkatkan ini ketika batch embedding lokal yang bergantung pada CPU sehat tetapi lambat.
Jika tidak diatur, nilai bawaan penyedia digunakan: 600 detik untuk penyedia lokal/self-hosted seperti `local`, `ollama`, dan `lmstudio`, serta 120 detik untuk penyedia hosted. Tingkatkan nilai ini ketika batch embedding lokal yang terikat CPU sehat tetapi lambat.
</ParamField>
---
@ -319,27 +319,27 @@ Jika tidak diatur, gunakan default penyedia: 600 detik untuk penyedia lokal/self
Semua berada di bawah `memorySearch.query.hybrid`:
| Kunci | Tipe | Default | Deskripsi |
| --------------------- | --------- | ------- | -------------------------------------------- |
| `enabled` | `boolean` | `true` | Aktifkan pencarian hybrid BM25 + vektor |
| `vectorWeight` | `number` | `0.7` | Bobot untuk skor vektor (0-1) |
| `textWeight` | `number` | `0.3` | Bobot untuk skor BM25 (0-1) |
| `candidateMultiplier` | `number` | `4` | Pengali ukuran kumpulan kandidat |
| Kunci | Tipe | Bawaan | Deskripsi |
| --------------------- | --------- | ------- | ------------------------------------------ |
| `enabled` | `boolean` | `true` | Aktifkan pencarian hybrid BM25 + vektor |
| `vectorWeight` | `number` | `0.7` | Bobot untuk skor vektor (0-1) |
| `textWeight` | `number` | `0.3` | Bobot untuk skor BM25 (0-1) |
| `candidateMultiplier` | `number` | `4` | Pengali ukuran kumpulan kandidat |
<Tabs>
<Tab title="MMR (keragaman)">
| Kunci | Tipe | Default | Deskripsi |
| ------------- | --------- | ------- | --------------------------------------- |
| `mmr.enabled` | `boolean` | `false` | Aktifkan pemeringkatan ulang MMR |
| `mmr.lambda` | `number` | `0.7` | 0 = keragaman maksimum, 1 = relevansi maksimum |
<Tab title="MMR (diversity)">
| Kunci | Tipe | Bawaan | Deskripsi |
| ------------- | --------- | ------- | ---------------------------------------- |
| `mmr.enabled` | `boolean` | `false` | Aktifkan pemeringkatan ulang MMR |
| `mmr.lambda` | `number` | `0.7` | 0 = keragaman maks, 1 = relevansi maks |
</Tab>
<Tab title="Peluruhan temporal (keterbaruan)">
| Kunci | Tipe | Default | Deskripsi |
| ---------------------------- | --------- | ------- | -------------------------------- |
| `temporalDecay.enabled` | `boolean` | `false` | Aktifkan peningkatan keterbaruan |
| `temporalDecay.halfLifeDays` | `number` | `30` | Skor berkurang setengah setiap N hari |
<Tab title="Temporal decay (recency)">
| Kunci | Tipe | Bawaan | Deskripsi |
| ---------------------------- | --------- | ------- | --------------------------------- |
| `temporalDecay.enabled` | `boolean` | `false` | Aktifkan peningkatan kebaruan |
| `temporalDecay.halfLifeDays` | `number` | `30` | Skor berkurang setengah tiap N hari |
Berkas evergreen (`MEMORY.md`, berkas tanpa tanggal di `memory/`) tidak pernah diluruhkan.
Berkas evergreen (`MEMORY.md`, berkas tanpa tanggal di `memory/`) tidak pernah mengalami decay.
</Tab>
</Tabs>
@ -367,10 +367,10 @@ Semua berada di bawah `memorySearch.query.hybrid`:
---
## Path memori tambahan
## Jalur memori tambahan
| Kunci | Tipe | Deskripsi |
| ------------ | ---------- | ------------------------------------------ |
| Kunci | Tipe | Deskripsi |
| ------------ | ---------- | -------------------------------------------- |
| `extraPaths` | `string[]` | Direktori atau berkas tambahan untuk diindeks |
```json5
@ -385,9 +385,9 @@ Semua berada di bawah `memorySearch.query.hybrid`:
}
```
Path dapat bersifat absolut atau relatif terhadap workspace. Direktori dipindai secara rekursif untuk berkas `.md`. Penanganan symlink bergantung pada backend aktif: mesin bawaan mengabaikan symlink, sedangkan QMD mengikuti perilaku pemindai QMD yang mendasarinya.
Jalur dapat bersifat absolut atau relatif terhadap workspace. Direktori dipindai secara rekursif untuk berkas `.md`. Penanganan symlink bergantung pada backend aktif: mesin bawaan mengabaikan symlink, sedangkan QMD mengikuti perilaku pemindai QMD yang mendasarinya.
Untuk pencarian transkrip lintas agen dengan scope agen, gunakan `agents.list[].memorySearch.qmd.extraCollections` alih-alih `memory.qmd.paths`. Koleksi tambahan tersebut mengikuti bentuk `{ path, name, pattern? }` yang sama, tetapi digabungkan per agen dan dapat mempertahankan nama bersama eksplisit ketika path menunjuk ke luar workspace saat ini. Jika path terselesaikan yang sama muncul di `memory.qmd.paths` dan `memorySearch.qmd.extraCollections`, QMD mempertahankan entri pertama dan melewati duplikat.
Untuk pencarian transkrip lintas agen dalam cakupan agen, gunakan `agents.list[].memorySearch.qmd.extraCollections` alih-alih `memory.qmd.paths`. Koleksi tambahan tersebut mengikuti bentuk `{ path, name, pattern? }` yang sama, tetapi digabungkan per agen dan dapat mempertahankan nama bersama eksplisit ketika jalur menunjuk ke luar workspace saat ini. Jika jalur ter-resolve yang sama muncul di `memory.qmd.paths` dan `memorySearch.qmd.extraCollections`, QMD mempertahankan entri pertama dan melewati duplikatnya.
---
@ -395,47 +395,47 @@ Untuk pencarian transkrip lintas agen dengan scope agen, gunakan `agents.list[].
Indeks gambar dan audio bersama Markdown menggunakan Gemini Embedding 2:
| Kunci | Tipe | Default | Deskripsi |
| Kunci | Tipe | Bawaan | Deskripsi |
| ------------------------- | ---------- | ---------- | -------------------------------------- |
| `multimodal.enabled` | `boolean` | `false` | Aktifkan pengindeksan multimodal |
| `multimodal.modalities` | `string[]` | -- | `["image"]`, `["audio"]`, atau `["all"]` |
| `multimodal.maxFileBytes` | `number` | `10000000` | Ukuran berkas maksimum untuk pengindeksan |
| `multimodal.maxFileBytes` | `number` | `10000000` | Ukuran berkas maks untuk pengindeksan |
<Note>
Hanya berlaku untuk file di `extraPaths`. Root memori default tetap hanya Markdown. Memerlukan `gemini-embedding-2-preview`. `fallback` harus berupa `"none"`.
Hanya berlaku untuk berkas di `extraPaths`. Root memori bawaan tetap hanya Markdown. Memerlukan `gemini-embedding-2-preview`. `fallback` harus berupa `"none"`.
</Note>
Format yang didukung: `.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.heic`, `.heif` (gambar); `.mp3`, `.wav`, `.ogg`, `.opus`, `.m4a`, `.aac`, `.flac` (audio).
---
## Cache penyematan
## Cache embedding
| Kunci | Tipe | Default | Deskripsi |
| ------------------ | --------- | ------- | --------------------------------------- |
| `cache.enabled` | `boolean` | `false` | Cache penyematan chunk di SQLite |
| `cache.maxEntries` | `number` | `50000` | Penyematan cache maksimum |
| Kunci | Tipe | Bawaan | Deskripsi |
| ------------------ | --------- | ------- | --------------------------------- |
| `cache.enabled` | `boolean` | `false` | Cache embedding potongan di SQLite |
| `cache.maxEntries` | `number` | `50000` | Embedding cache maks |
Mencegah penyematan ulang teks yang tidak berubah selama pengindeksan ulang atau pembaruan transkrip.
Mencegah embedding ulang teks yang tidak berubah selama reindex atau pembaruan transkrip.
---
## Pengindeksan batch
| Kunci | Tipe | Default | Deskripsi |
| ----------------------------- | --------- | ------- | -------------------------------- |
| `remote.nonBatchConcurrency` | `number` | `4` | Penyematan langsung paralel |
| `remote.batch.enabled` | `boolean` | `false` | Aktifkan API penyematan batch |
| `remote.batch.concurrency` | `number` | `2` | Pekerjaan batch paralel |
| `remote.batch.wait` | `boolean` | `true` | Tunggu penyelesaian batch |
| `remote.batch.pollIntervalMs` | `number` | -- | Interval polling |
| `remote.batch.timeoutMinutes` | `number` | -- | Batas waktu batch |
| Kunci | Tipe | Bawaan | Deskripsi |
| ----------------------------- | --------- | ------- | ------------------------------ |
| `remote.nonBatchConcurrency` | `number` | `4` | Embedding inline paralel |
| `remote.batch.enabled` | `boolean` | `false` | Aktifkan API embedding batch |
| `remote.batch.concurrency` | `number` | `2` | Job batch paralel |
| `remote.batch.wait` | `boolean` | `true` | Tunggu penyelesaian batch |
| `remote.batch.pollIntervalMs` | `number` | -- | Interval polling |
| `remote.batch.timeoutMinutes` | `number` | -- | Timeout batch |
Tersedia untuk `openai`, `gemini`, dan `voyage`. Batch OpenAI biasanya paling cepat dan paling murah untuk backfill besar.
`remote.nonBatchConcurrency` mengontrol panggilan penyematan langsung yang digunakan oleh penyedia lokal/di-host sendiri dan penyedia ter-host saat API batch penyedia tidak aktif. Ollama menggunakan default `1` untuk pengindeksan non-batch agar tidak membebani host lokal yang lebih kecil; tetapkan nilai yang lebih tinggi di mesin yang lebih besar.
`remote.nonBatchConcurrency` mengontrol panggilan embedding inline yang digunakan oleh penyedia lokal/self-hosted dan penyedia hosted ketika API batch penyedia tidak aktif. Ollama menggunakan bawaan `1` untuk pengindeksan non-batch agar tidak membebani host lokal yang lebih kecil secara berlebihan; tetapkan nilai lebih tinggi pada mesin yang lebih besar.
Ini terpisah dari `sync.embeddingBatchTimeoutSeconds`, yang mengontrol batas waktu untuk panggilan penyematan langsung.
Ini terpisah dari `sync.embeddingBatchTimeoutSeconds`, yang mengontrol timeout untuk panggilan embedding inline.
---
@ -443,36 +443,36 @@ Ini terpisah dari `sync.embeddingBatchTimeoutSeconds`, yang mengontrol batas wak
Indeks transkrip sesi dan tampilkan melalui `memory_search`:
| Kunci | Tipe | Default | Deskripsi |
| Kunci | Tipe | Bawaan | Deskripsi |
| ----------------------------- | ---------- | ------------ | ------------------------------------------ |
| `experimental.sessionMemory` | `boolean` | `false` | Aktifkan pengindeksan sesi |
| `sources` | `string[]` | `["memory"]` | Tambahkan `"sessions"` untuk menyertakan transkrip |
| `sync.sessions.deltaBytes` | `number` | `100000` | Ambang byte untuk pengindeksan ulang |
| `sync.sessions.deltaMessages` | `number` | `50` | Ambang pesan untuk pengindeksan ulang |
| `sync.sessions.deltaBytes` | `number` | `100000` | Ambang byte untuk reindex |
| `sync.sessions.deltaMessages` | `number` | `50` | Ambang pesan untuk reindex |
<Warning>
Pengindeksan sesi bersifat opt-in dan berjalan secara asinkron. Hasil dapat sedikit usang. Log sesi berada di disk, jadi perlakukan akses sistem file sebagai batas kepercayaan.
Pengindeksan sesi bersifat opt-in dan berjalan secara asinkron. Hasil dapat sedikit kedaluwarsa. Log sesi berada di disk, jadi perlakukan akses filesystem sebagai batas kepercayaan.
</Warning>
---
## Akselerasi vektor SQLite (sqlite-vec)
| Kunci | Tipe | Default | Deskripsi |
| ---------------------------- | --------- | ------- | ---------------------------------------- |
| `store.vector.enabled` | `boolean` | `true` | Gunakan sqlite-vec untuk kueri vektor |
| `store.vector.extensionPath` | `string` | bundled | Timpa jalur sqlite-vec |
| Kunci | Tipe | Bawaan | Deskripsi |
| ---------------------------- | --------- | ------- | ------------------------------------ |
| `store.vector.enabled` | `boolean` | `true` | Gunakan sqlite-vec untuk kueri vektor |
| `store.vector.extensionPath` | `string` | dibundel | Ganti jalur sqlite-vec |
Saat sqlite-vec tidak tersedia, OpenClaw otomatis beralih ke kemiripan kosinus dalam proses.
Ketika sqlite-vec tidak tersedia, OpenClaw otomatis kembali ke kemiripan kosinus dalam proses.
---
## Penyimpanan indeks
| Kunci | Tipe | Default | Deskripsi |
| --------------------- | -------- | ------------------------------------- | ---------------------------------------------- |
| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | Lokasi indeks (mendukung token `{agentId}`) |
| `store.fts.tokenizer` | `string` | `unicode61` | Tokenizer FTS5 (`unicode61` atau `trigram`) |
| Kunci | Tipe | Bawaan | Deskripsi |
| --------------------- | -------- | ------------------------------------- | ------------------------------------------ |
| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | Lokasi indeks (mendukung token `{agentId}`) |
| `store.fts.tokenizer` | `string` | `unicode61` | Tokenizer FTS5 (`unicode61` atau `trigram`) |
---
@ -480,46 +480,46 @@ Saat sqlite-vec tidak tersedia, OpenClaw otomatis beralih ke kemiripan kosinus d
Tetapkan `memory.backend = "qmd"` untuk mengaktifkan. Semua pengaturan QMD berada di bawah `memory.qmd`:
| Kunci | Tipe | Default | Deskripsi |
| ------------------------ | --------- | -------- | ----------------------------------------------------------------------------------------- |
| `command` | `string` | `qmd` | Jalur executable QMD; tetapkan jalur absolut saat layanan `PATH` berbeda dari shell Anda |
| `searchMode` | `string` | `search` | Perintah pencarian: `search`, `vsearch`, `query` |
| `includeDefaultMemory` | `boolean` | `true` | Indeks otomatis `MEMORY.md` + `memory/**/*.md` |
| `paths[]` | `array` | -- | Jalur tambahan: `{ name, path, pattern? }` |
| `sessions.enabled` | `boolean` | `false` | Indeks transkrip sesi |
| `sessions.retentionDays` | `number` | -- | Retensi transkrip |
| `sessions.exportDir` | `string` | -- | Direktori ekspor |
| Kunci | Tipe | Bawaan | Deskripsi |
| ------------------------ | --------- | -------- | ------------------------------------------------------------------------------------------- |
| `command` | `string` | `qmd` | Jalur executable QMD; tetapkan jalur absolut ketika `PATH` layanan berbeda dari shell Anda |
| `searchMode` | `string` | `search` | Perintah pencarian: `search`, `vsearch`, `query` |
| `includeDefaultMemory` | `boolean` | `true` | Indeks otomatis `MEMORY.md` + `memory/**/*.md` |
| `paths[]` | `array` | -- | Jalur tambahan: `{ name, path, pattern? }` |
| `sessions.enabled` | `boolean` | `false` | Indeks transkrip sesi |
| `sessions.retentionDays` | `number` | -- | Retensi transkrip |
| `sessions.exportDir` | `string` | -- | Direktori ekspor |
`searchMode: "search"` bersifat leksikal/BM25 saja. OpenClaw tidak menjalankan probe kesiapan vektor semantik atau pemeliharaan embedding QMD untuk mode tersebut, termasuk selama `memory status --deep`; `vsearch` dan `query` tetap memerlukan kesiapan vektor QMD dan embedding.
`searchMode: "search"` hanya leksikal/BM25. OpenClaw tidak menjalankan probe kesiapan vektor semantik atau pemeliharaan embedding QMD untuk mode tersebut, termasuk selama `memory status --deep`; `vsearch` dan `query` tetap memerlukan kesiapan vektor QMD dan embedding.
OpenClaw lebih memilih koleksi QMD dan bentuk kueri MCP saat ini, tetapi tetap menjaga rilis QMD lama tetap berfungsi dengan mencoba flag pola koleksi yang kompatibel dan nama alat MCP lama saat diperlukan. Saat QMD mengiklankan dukungan untuk beberapa filter koleksi, koleksi dari sumber yang sama dicari dengan satu proses QMD; build QMD lama tetap menggunakan jalur kompatibilitas per koleksi. Sumber yang sama berarti koleksi memori tahan lama dikelompokkan bersama, sementara koleksi transkrip sesi tetap menjadi grup terpisah sehingga diversifikasi sumber masih memiliki kedua input.
OpenClaw lebih memilih koleksi QMD dan bentuk kueri MCP saat ini, tetapi tetap membuat rilis QMD lama berfungsi dengan mencoba flag pola koleksi yang kompatibel dan nama alat MCP lama bila diperlukan. Ketika QMD mengiklankan dukungan untuk beberapa filter koleksi, koleksi dari sumber yang sama dicari dengan satu proses QMD; build QMD lama tetap memakai jalur kompatibilitas per koleksi. Sumber yang sama berarti koleksi memori tahan lama dikelompokkan bersama, sementara koleksi transkrip sesi tetap menjadi grup terpisah sehingga diversifikasi sumber tetap memiliki kedua input.
<Note>
Override model QMD tetap berada di sisi QMD, bukan konfigurasi OpenClaw. Jika Anda perlu mengesampingkan model QMD secara global, tetapkan variabel lingkungan seperti `QMD_EMBED_MODEL`, `QMD_RERANK_MODEL`, dan `QMD_GENERATE_MODEL` di lingkungan runtime gateway.
Override model QMD tetap berada di sisi QMD, bukan konfigurasi OpenClaw. Jika Anda perlu meng-override model QMD secara global, tetapkan variabel lingkungan seperti `QMD_EMBED_MODEL`, `QMD_RERANK_MODEL`, dan `QMD_GENERATE_MODEL` di lingkungan runtime gateway.
</Note>
<AccordionGroup>
<Accordion title="Jadwal pembaruan">
| Key | Type | Default | Description |
| ------------------------- | --------- | ------- | ------------------------------------- |
| `update.interval` | `string` | `5m` | Interval penyegaran |
| `update.debounceMs` | `number` | `15000` | Debounce perubahan file |
| `update.onBoot` | `boolean` | `true` | Segarkan saat manajer QMD berumur panjang dibuka; juga mengatur penyegaran startup opt-in |
| `update.startup` | `string` | `off` | Penyegaran opsional saat gateway dimulai: `off`, `idle`, atau `immediate` |
| `update.startupDelayMs` | `number` | `120000` | Penundaan sebelum penyegaran `startup: "idle"` berjalan |
| `update.waitForBootSync` | `boolean` | `false` | Blokir pembukaan manajer hingga penyegaran awalnya selesai |
| `update.embedInterval` | `string` | -- | Irama embed terpisah |
| `update.commandTimeoutMs` | `number` | -- | Timeout untuk perintah QMD |
| `update.updateTimeoutMs` | `number` | -- | Timeout untuk operasi pembaruan QMD |
| `update.embedTimeoutMs` | `number` | -- | Timeout untuk operasi embed QMD |
| Kunci | Tipe | Bawaan | Deskripsi |
| ------------------------- | --------- | ------- | ----------------------------------- |
| `update.interval` | `string` | `5m` | Interval refresh |
| `update.debounceMs` | `number` | `15000` | Debounce perubahan file |
| `update.onBoot` | `boolean` | `true` | Refresh ketika manajer QMD jangka panjang dibuka; juga menjadi gerbang refresh startup opt-in |
| `update.startup` | `string` | `off` | Refresh opsional saat gateway dimulai: `off`, `idle`, atau `immediate` |
| `update.startupDelayMs` | `number` | `120000` | Penundaan sebelum refresh `startup: "idle"` berjalan |
| `update.waitForBootSync` | `boolean` | `false` | Blokir pembukaan manajer hingga refresh awalnya selesai |
| `update.embedInterval` | `string` | -- | Irama embed terpisah |
| `update.commandTimeoutMs` | `number` | -- | Timeout untuk perintah QMD |
| `update.updateTimeoutMs` | `number` | -- | Timeout untuk operasi pembaruan QMD |
| `update.embedTimeoutMs` | `number` | -- | Timeout untuk operasi embed QMD |
</Accordion>
<Accordion title="Batas">
| Key | Type | Default | Description |
| ------------------------- | -------- | ------- | -------------------------- |
| `limits.maxResults` | `number` | `6` | Hasil pencarian maksimum |
| `limits.maxSnippetChars` | `number` | -- | Batasi panjang cuplikan |
| Kunci | Tipe | Bawaan | Deskripsi |
| ------------------------- | -------- | ------- | ---------------------------- |
| `limits.maxResults` | `number` | `6` | Hasil pencarian maksimum |
| `limits.maxSnippetChars` | `number` | -- | Batasi panjang cuplikan |
| `limits.maxInjectedChars` | `number` | -- | Batasi total karakter yang diinjeksi |
| `limits.timeoutMs` | `number` | `4000` | Timeout pencarian |
| `limits.timeoutMs` | `number` | `4000` | Timeout pencarian |
</Accordion>
<Accordion title="Cakupan">
Mengontrol sesi mana yang dapat menerima hasil pencarian QMD. Skema yang sama seperti [`session.sendPolicy`](/id/gateway/config-agents#session):
@ -537,24 +537,24 @@ Override model QMD tetap berada di sisi QMD, bukan konfigurasi OpenClaw. Jika An
}
```
Default bawaan mengizinkan sesi langsung dan channel, sambil tetap menolak grup.
Default yang dikirim memungkinkan sesi langsung dan kanal, sambil tetap menolak grup.
Default hanya DM. `match.keyPrefix` mencocokkan kunci sesi yang dinormalisasi; `match.rawKeyPrefix` mencocokkan kunci mentah termasuk `agent:<id>:`.
</Accordion>
<Accordion title="Kutipan">
<Accordion title="Sitasi">
`memory.citations` berlaku untuk semua backend:
| Value | Behavior |
| Nilai | Perilaku |
| ---------------- | --------------------------------------------------- |
| `auto` (default) | Sertakan footer `Source: <path#line>` dalam cuplikan |
| `on` | Selalu sertakan footer |
| `off` | Hilangkan footer (path masih diteruskan ke agent secara internal) |
| `off` | Hilangkan footer (jalur tetap diteruskan ke agent secara internal) |
</Accordion>
</AccordionGroup>
Penyegaran boot QMD menggunakan jalur subprocess sekali jalan selama startup gateway. Manajer QMD berumur panjang tetap memiliki file watcher reguler dan timer interval saat pencarian memori dibuka untuk penggunaan interaktif.
Refresh boot QMD menggunakan jalur subproses sekali jalan selama startup gateway. Manajer QMD jangka panjang tetap memiliki watcher file reguler dan timer interval ketika pencarian memori dibuka untuk penggunaan interaktif.
### Contoh QMD lengkap
@ -583,17 +583,17 @@ Penyegaran boot QMD menggunakan jalur subprocess sekali jalan selama startup gat
Dreaming dikonfigurasi di bawah `plugins.entries.memory-core.config.dreaming`, bukan di bawah `agents.defaults.memorySearch`.
Dreaming berjalan sebagai satu sweep terjadwal dan menggunakan fase internal light/deep/REM sebagai detail implementasi.
Dreaming berjalan sebagai satu sweep terjadwal dan menggunakan fase light/deep/REM internal sebagai detail implementasi.
Untuk perilaku konseptual dan perintah slash, lihat [Dreaming](/id/concepts/dreaming).
### Pengaturan pengguna
| Key | Type | Default | Description |
| ----------- | --------- | ------------- | ------------------------------------------------- |
| `enabled` | `boolean` | `false` | Aktifkan atau nonaktifkan dreaming sepenuhnya |
| `frequency` | `string` | `0 3 * * *` | Irama cron opsional untuk sweep dreaming lengkap |
| `model` | `string` | model default | Override model subagent Dream Diary opsional |
| Kunci | Tipe | Bawaan | Deskripsi |
| ----------- | --------- | ------------- | ---------------------------------------------- |
| `enabled` | `boolean` | `false` | Aktifkan atau nonaktifkan dreaming sepenuhnya |
| `frequency` | `string` | `0 3 * * *` | Irama cron opsional untuk sweep dreaming penuh |
| `model` | `string` | model default | Override model subagent Dream Diary opsional |
### Contoh
@ -622,9 +622,9 @@ Untuk perilaku konseptual dan perintah slash, lihat [Dreaming](/id/concepts/drea
<Note>
- Dreaming menulis status mesin ke `memory/.dreams/`.
- Dreaming menulis keluaran naratif yang dapat dibaca manusia ke `DREAMS.md` (atau `dreams.md` yang sudah ada).
- `dreaming.model` menggunakan gate kepercayaan subagent plugin yang sudah ada; tetapkan `plugins.entries.memory-core.subagent.allowModelOverride: true` sebelum mengaktifkannya.
- Dream Diary mencoba ulang satu kali dengan model default sesi saat model yang dikonfigurasi tidak tersedia. Kegagalan kepercayaan atau allowlist dicatat di log dan tidak dicoba ulang secara diam-diam.
- Kebijakan fase light/deep/REM dan ambang batas adalah perilaku internal, bukan konfigurasi yang terlihat oleh pengguna.
- `dreaming.model` menggunakan gerbang kepercayaan subagent Plugin yang sudah ada; tetapkan `plugins.entries.memory-core.subagent.allowModelOverride: true` sebelum mengaktifkannya.
- Dream Diary mencoba ulang sekali dengan model default sesi ketika model yang dikonfigurasi tidak tersedia. Kegagalan kepercayaan atau allowlist dicatat di log dan tidak dicoba ulang secara diam-diam.
- Kebijakan dan ambang fase light/deep/REM adalah perilaku internal, bukan konfigurasi yang terlihat pengguna.
</Note>

283
docs/id/reference/session-management-compaction.md
View File

@ -1,34 +1,34 @@
---
read_when:
- Anda perlu menelusuri masalah pada ID sesi, JSONL transkrip, atau bidang sessions.json
- Anda mengubah perilaku Compaction otomatis atau menambahkan pemeliharaan “pra-Compaction”
- Anda perlu men-debug ID sesi, transkrip JSONL, atau bidang sessions.json
- Anda mengubah perilaku auto-Compaction atau menambahkan pemeliharaan “pre-Compaction”
- Anda ingin mengimplementasikan pengosongan memori atau giliran sistem senyap
summary: 'Pembahasan mendalam: penyimpanan sesi + transkrip, siklus hidup, dan internal (auto)Compaction'
summary: 'Pembahasan mendalam: penyimpanan sesi + transkrip, siklus hidup, dan internal (otomatis)Compaction'
title: Pendalaman manajemen sesi
x-i18n:
generated_at: "2026-04-30T10:10:59Z"
generated_at: "2026-04-30T16:30:13Z"
model: gpt-5.5
provider: openai
source_hash: 1e9785723ebf9b5411440a8f3b2885a50d659f669811ba749c431a2b3aeed700
source_hash: 5a6a7031cebd90d27784a32a0d0378ea9959249389d209f0745395f90b8a0df9
source_path: reference/session-management-compaction.md
workflow: 16
---
OpenClaw mengelola sesi secara menyeluruh di area-area berikut:
OpenClaw mengelola sesi end-to-end di seluruh area ini:
- **Perutean sesi** (cara pesan masuk dipetakan ke `sessionKey`)
- **Penyimpanan sesi** (`sessions.json`) dan apa yang dilacaknya
- **Persistensi transkrip** (`*.jsonl`) dan strukturnya
- **Kebersihan transkrip** (perbaikan spesifik penyedia sebelum run)
- **Batas konteks** (jendela konteks vs token terlacak)
- **Compaction** (Compaction manual dan otomatis) dan tempat mengaitkan pekerjaan pra-Compaction
- **Pemeliharaan senyap** (penulisan memori yang tidak boleh menghasilkan output yang terlihat pengguna)
- **Kebersihan transkrip** (perbaikan khusus penyedia sebelum run)
- **Batas konteks** (jendela konteks vs token yang dilacak)
- **Compaction** (manual dan auto-compaction) dan tempat mengaitkan pekerjaan pra-compaction
- **Housekeeping senyap** (penulisan memori yang tidak boleh menghasilkan output yang terlihat pengguna)
Jika Anda ingin gambaran tingkat tinggi terlebih dahulu, mulai dari:
Jika Anda ingin ikhtisar tingkat lebih tinggi terlebih dahulu, mulai dengan:
- [Manajemen sesi](/id/concepts/session)
- [Compaction](/id/concepts/compaction)
- [Ringkasan memori](/id/concepts/memory)
- [Ikhtisar memori](/id/concepts/memory)
- [Pencarian memori](/id/concepts/memory-search)
- [Pemangkasan sesi](/id/concepts/session-pruning)
- [Kebersihan transkrip](/id/reference/transcript-hygiene)
@ -37,9 +37,9 @@ Jika Anda ingin gambaran tingkat tinggi terlebih dahulu, mulai dari:
## Sumber kebenaran: Gateway
OpenClaw dirancang di sekitar satu **proses Gateway** yang memiliki status sesi.
OpenClaw dirancang di sekitar satu **proses Gateway** yang memiliki state sesi.
- UI (aplikasi macOS, UI Kontrol web, TUI) harus mengkueri Gateway untuk daftar sesi dan jumlah token.
- UI (aplikasi macOS, Control UI web, TUI) harus mengueri Gateway untuk daftar sesi dan jumlah token.
- Dalam mode jarak jauh, file sesi berada di host jarak jauh; “memeriksa file Mac lokal Anda” tidak akan mencerminkan apa yang digunakan Gateway.
---
@ -49,29 +49,29 @@ OpenClaw dirancang di sekitar satu **proses Gateway** yang memiliki status sesi.
OpenClaw mempertahankan sesi dalam dua lapisan:
1. **Penyimpanan sesi (`sessions.json`)**
- Peta kunci/nilai: `sessionKey -> SessionEntry`
- Peta key/value: `sessionKey -> SessionEntry`
- Kecil, dapat diubah, aman untuk diedit (atau menghapus entri)
- Melacak metadata sesi (id sesi saat ini, aktivitas terakhir, toggle, penghitung token, dll.)
2. **Transkrip (`<sessionId>.jsonl`)**
- Transkrip append-only dengan struktur pohon (entri memiliki `id` + `parentId`)
- Menyimpan percakapan aktual + panggilan alat + ringkasan Compaction
- Menyimpan percakapan aktual + pemanggilan alat + ringkasan compaction
- Digunakan untuk membangun ulang konteks model untuk giliran berikutnya
- Checkpoint debug pra-Compaction yang besar dilewati setelah transkrip
aktif melampaui batas ukuran checkpoint, sehingga menghindari salinan
`.checkpoint.*.jsonl` raksasa kedua.
- Checkpoint debug pra-compaction yang besar dilewati setelah transkrip aktif
melebihi batas ukuran checkpoint, sehingga menghindari salinan `.checkpoint.*.jsonl`
raksasa kedua.
---
## Lokasi di disk
Per agen, di host Gateway:
Per agen, pada host Gateway:
- Penyimpanan: `~/.openclaw/agents/<agentId>/sessions/sessions.json`
- Transkrip: `~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl`
- Sesi topik Telegram: `.../<sessionId>-topic-<threadId>.jsonl`
OpenClaw menyelesaikan lokasi ini melalui `src/config/sessions.ts`.
OpenClaw menyelesaikan ini melalui `src/config/sessions.ts`.
---
@ -80,23 +80,23 @@ OpenClaw menyelesaikan lokasi ini melalui `src/config/sessions.ts`.
Persistensi sesi memiliki kontrol pemeliharaan otomatis (`session.maintenance`) untuk `sessions.json`, artefak transkrip, dan sidecar trajectory:
- `mode`: `warn` (default) atau `enforce`
- `pruneAfter`: batas usia entri usang (default `30d`)
- `maxEntries`: batas entri di `sessions.json` (default `500`)
- `resetArchiveRetention`: retensi untuk arsip transkrip `*.reset.<timestamp>` (default: sama seperti `pruneAfter`; `false` menonaktifkan pembersihan)
- `pruneAfter`: batas usia entri stale (default `30d`)
- `maxEntries`: batas entri dalam `sessions.json` (default `500`)
- `resetArchiveRetention`: retensi untuk arsip transkrip `*.reset.<timestamp>` (default: sama dengan `pruneAfter`; `false` menonaktifkan pembersihan)
- `maxDiskBytes`: anggaran direktori sesi opsional
- `highWaterBytes`: target opsional setelah pembersihan (default `80%` dari `maxDiskBytes`)
Penulisan Gateway normal melakukan batch pembersihan `maxEntries` untuk batas berukuran produksi, sehingga penyimpanan dapat sebentar melampaui batas yang dikonfigurasi sebelum pembersihan high-water berikutnya menulis ulang hingga turun kembali. `openclaw sessions cleanup --enforce` tetap langsung menerapkan batas yang dikonfigurasi.
Penulisan Gateway normal melakukan batch pembersihan `maxEntries` untuk batas berukuran produksi, sehingga penyimpanan mungkin sebentar melebihi batas yang dikonfigurasi sebelum pembersihan high-water berikutnya menulis ulangnya kembali ke bawah. `openclaw sessions cleanup --enforce` tetap menerapkan batas yang dikonfigurasi secara langsung.
OpenClaw tidak lagi membuat cadangan rotasi `sessions.json.bak.*` otomatis selama penulisan Gateway. Kunci lama `session.maintenance.rotateBytes` diabaikan dan `openclaw doctor --fix` menghapusnya dari konfigurasi lama.
OpenClaw tidak lagi membuat backup rotasi `sessions.json.bak.*` otomatis selama penulisan Gateway. Kunci lama `session.maintenance.rotateBytes` diabaikan dan `openclaw doctor --fix` menghapusnya dari konfigurasi lama.
Urutan penegakan untuk pembersihan anggaran disk (`mode: "enforce"`):
1. Hapus artefak arsip tertua, transkrip yatim, atau trajectory yatim terlebih dahulu.
2. Jika masih di atas target, keluarkan entri sesi tertua dan file transkrip/trajectory-nya.
3. Teruskan hingga penggunaan berada pada atau di bawah `highWaterBytes`.
1. Hapus artefak arsip, transkrip yatim, atau trajectory yatim yang paling lama terlebih dahulu.
2. Jika masih di atas target, keluarkan entri sesi tertua beserta file transkrip/trajectory-nya.
3. Lanjutkan hingga penggunaan berada pada atau di bawah `highWaterBytes`.
Dalam `mode: "warn"`, OpenClaw melaporkan potensi pengeluaran tetapi tidak mengubah penyimpanan/file.
Dalam `mode: "warn"`, OpenClaw melaporkan potensi eviction tetapi tidak mengubah penyimpanan/file.
Jalankan pemeliharaan sesuai kebutuhan:
@ -114,19 +114,19 @@ Run cron terisolasi juga membuat entri sesi/transkrip, dan memiliki kontrol rete
- `cron.sessionRetention` (default `24h`) memangkas sesi run cron terisolasi lama dari penyimpanan sesi (`false` menonaktifkan).
- `cron.runLog.maxBytes` + `cron.runLog.keepLines` memangkas file `~/.openclaw/cron/runs/<jobId>.jsonl` (default: `2_000_000` byte dan `2000` baris).
Saat cron memaksa pembuatan sesi run terisolasi baru, cron membersihkan entri
sesi `cron:<jobId>` sebelumnya sebelum menulis baris baru. Cron membawa
preferensi aman seperti pengaturan berpikir/cepat/verbose, label, dan override
model/auth yang dipilih pengguna secara eksplisit. Cron membuang konteks
percakapan ambien seperti perutean channel/grup, kebijakan kirim atau antrean,
elevasi, asal, dan binding runtime ACP sehingga run terisolasi baru tidak dapat
mewarisi pengiriman usang atau otoritas runtime dari run lama.
Ketika cron memaksa pembuatan sesi run terisolasi baru, ia membersihkan entri sesi
`cron:<jobId>` sebelumnya sebelum menulis baris baru. Ia membawa preferensi aman
seperti pengaturan thinking/fast/verbose, label, dan override model/auth yang
dipilih pengguna secara eksplisit. Ia membuang konteks percakapan sekitar seperti
perutean channel/grup, kebijakan kirim atau antrean, elevation, origin, dan binding
runtime ACP sehingga run terisolasi baru tidak dapat mewarisi pengiriman atau
otoritas runtime stale dari run yang lebih lama.
---
## Kunci sesi (`sessionKey`)
`sessionKey` mengidentifikasi _bucket percakapan mana_ yang sedang Anda gunakan (perutean + isolasi).
`sessionKey` mengidentifikasi _bucket percakapan mana_ tempat Anda berada (perutean + isolasi).
Pola umum:
@ -134,7 +134,7 @@ Pola umum:
- Grup: `agent:<agentId>:<channel>:group:<id>`
- Room/channel (Discord/Slack): `agent:<agentId>:<channel>:channel:<id>` atau `...:room:<id>`
- Cron: `cron:<job.id>`
- Webhook: `hook:<uuid>` (kecuali di-override)
- Webhook: `hook:<uuid>` (kecuali dioverride)
Aturan kanonis didokumentasikan di [/concepts/session](/id/concepts/session).
@ -148,9 +148,9 @@ Aturan praktis:
- **Reset** (`/new`, `/reset`) membuat `sessionId` baru untuk `sessionKey` tersebut.
- **Reset harian** (default pukul 4:00 AM waktu lokal pada host gateway) membuat `sessionId` baru pada pesan berikutnya setelah batas reset.
- **Kedaluwarsa idle** (`session.reset.idleMinutes` atau legacy `session.idleMinutes`) membuat `sessionId` baru saat pesan tiba setelah jendela idle. Saat harian + idle sama-sama dikonfigurasi, yang kedaluwarsa lebih dulu menang.
- **Event sistem** (heartbeat, wakeup cron, notifikasi exec, pembukuan gateway) dapat mengubah baris sesi tetapi tidak memperpanjang kesegaran reset harian/idle. Rollover reset membuang pemberitahuan event sistem yang diantrekan untuk sesi sebelumnya sebelum prompt baru dibangun.
- **Pelindung fork parent thread** (`session.parentForkMaxTokens`, default `100000`) melewati forking transkrip parent saat sesi parent sudah terlalu besar; thread baru dimulai segar. Atur `0` untuk menonaktifkan.
- **Kedaluwarsa idle** (`session.reset.idleMinutes` atau legacy `session.idleMinutes`) membuat `sessionId` baru ketika pesan tiba setelah jendela idle. Ketika harian + idle sama-sama dikonfigurasi, yang kedaluwarsa lebih dulu menang.
- **Event sistem** (Heartbeat, wakeup cron, notifikasi exec, bookkeeping gateway) dapat mengubah baris sesi tetapi tidak memperpanjang kesegaran reset harian/idle. Rollover reset membuang pemberitahuan event sistem yang diantrekan untuk sesi sebelumnya sebelum prompt baru dibangun.
- **Pelindung fork parent thread** (`session.parentForkMaxTokens`, default `100000`) melewati forking transkrip parent ketika sesi parent sudah terlalu besar; thread baru dimulai segar. Setel `0` untuk menonaktifkan.
Detail implementasi: keputusan terjadi di `initSessionState()` dalam `src/auto-reply/reply/session.ts`.
@ -160,17 +160,17 @@ Detail implementasi: keputusan terjadi di `initSessionState()` dalam `src/auto-r
Tipe nilai penyimpanan adalah `SessionEntry` dalam `src/config/sessions.ts`.
Field utama (tidak lengkap):
Field kunci (tidak lengkap):
- `sessionId`: id transkrip saat ini (nama file diturunkan dari ini kecuali `sessionFile` diatur)
- `sessionId`: id transkrip saat ini (nama file diturunkan dari ini kecuali `sessionFile` disetel)
- `sessionStartedAt`: timestamp mulai untuk `sessionId` saat ini; kesegaran reset harian
menggunakan ini. Baris legacy dapat menurunkannya dari header sesi JSONL.
- `lastInteractionAt`: timestamp interaksi pengguna/channel nyata terakhir; kesegaran reset
idle menggunakan ini sehingga heartbeat, cron, dan event exec tidak menjaga sesi
idle menggunakan ini sehingga Heartbeat, cron, dan event exec tidak membuat sesi
tetap hidup. Baris legacy tanpa field ini fallback ke waktu mulai sesi yang dipulihkan
untuk kesegaran idle.
- `updatedAt`: timestamp mutasi baris penyimpanan terakhir, digunakan untuk listing, pemangkasan, dan
pembukuan. Ini bukan otoritas untuk kesegaran reset harian/idle.
bookkeeping. Ini bukan otoritas untuk kesegaran reset harian/idle.
- `sessionFile`: override path transkrip eksplisit opsional
- `chatType`: `direct | group | room` (membantu UI dan kebijakan kirim)
- `provider`, `subject`, `room`, `space`, `displayName`: metadata untuk pelabelan grup/channel
@ -181,11 +181,11 @@ Field utama (tidak lengkap):
- `providerOverride`, `modelOverride`, `authProfileOverride`
- Penghitung token (best-effort / bergantung penyedia):
- `inputTokens`, `outputTokens`, `totalTokens`, `contextTokens`
- `compactionCount`: seberapa sering auto-Compaction selesai untuk kunci sesi ini
- `memoryFlushAt`: timestamp untuk flush memori pra-Compaction terakhir
- `memoryFlushCompactionCount`: jumlah Compaction saat flush terakhir berjalan
- `compactionCount`: seberapa sering auto-compaction selesai untuk kunci sesi ini
- `memoryFlushAt`: timestamp untuk flush memori pra-compaction terakhir
- `memoryFlushCompactionCount`: jumlah compaction saat flush terakhir berjalan
Penyimpanan aman untuk diedit, tetapi Gateway adalah otoritasnya: Gateway dapat menulis ulang atau merehidrasi entri saat sesi berjalan.
Penyimpanan aman untuk diedit, tetapi Gateway adalah otoritas: ia dapat menulis ulang atau merehidrasi entri saat sesi berjalan.
---
@ -195,32 +195,32 @@ Transkrip dikelola oleh `SessionManager` milik `@mariozechner/pi-coding-agent`.
File ini adalah JSONL:
- Baris pertama: header sesi (`type: "session"`, mencakup `id`, `cwd`, `timestamp`, opsional `parentSession`)
- Baris pertama: header sesi (`type: "session"`, mencakup `id`, `cwd`, `timestamp`, `parentSession` opsional)
- Lalu: entri sesi dengan `id` + `parentId` (pohon)
Tipe entri penting:
- `message`: pesan pengguna/asisten/toolResult
- `custom_message`: pesan yang diinjeksi ekstensi yang _memang_ masuk ke konteks model (dapat disembunyikan dari UI)
- `custom`: status ekstensi yang _tidak_ masuk ke konteks model
- `compaction`: ringkasan Compaction yang dipersistenkan dengan `firstKeptEntryId` dan `tokensBefore`
- `branch_summary`: ringkasan yang dipersistenkan saat menavigasi cabang pohon
- `custom`: state ekstensi yang _tidak_ masuk ke konteks model
- `compaction`: ringkasan compaction yang dipertahankan dengan `firstKeptEntryId` dan `tokensBefore`
- `branch_summary`: ringkasan yang dipertahankan saat menavigasi cabang pohon
OpenClaw sengaja **tidak** “memperbaiki” transkrip; Gateway menggunakan `SessionManager` untuk membaca/menulisnya.
---
## Jendela konteks vs token terlacak
## Jendela konteks vs token yang dilacak
Dua konsep berbeda penting:
1. **Jendela konteks model**: batas keras per model (token yang terlihat oleh model)
2. **Penghitung penyimpanan sesi**: statistik bergulir yang ditulis ke `sessions.json` (digunakan untuk /status dan dasbor)
2. **Penghitung penyimpanan sesi**: statistik rolling yang ditulis ke `sessions.json` (digunakan untuk /status dan dasbor)
Jika Anda menyesuaikan batas:
Jika Anda menyetel batas:
- Jendela konteks berasal dari katalog model (dan dapat di-override melalui konfigurasi).
- `contextTokens` dalam penyimpanan adalah nilai estimasi/pelaporan runtime; jangan perlakukan sebagai jaminan ketat.
- Jendela konteks berasal dari katalog model (dan dapat dioverride melalui konfigurasi).
- `contextTokens` dalam penyimpanan adalah nilai estimasi/pelaporan runtime; jangan memperlakukannya sebagai jaminan ketat.
Untuk selengkapnya, lihat [/token-use](/id/reference/token-use).
@ -228,40 +228,40 @@ Untuk selengkapnya, lihat [/token-use](/id/reference/token-use).
## Compaction: apa itu
Compaction merangkum percakapan lama ke dalam entri `compaction` yang dipersistenkan di transkrip dan menjaga pesan terbaru tetap utuh.
Compaction merangkum percakapan lama ke dalam entri `compaction` yang dipertahankan dalam transkrip dan menjaga pesan terbaru tetap utuh.
Setelah Compaction, giliran berikutnya melihat:
Setelah compaction, giliran berikutnya melihat:
- Ringkasan Compaction
- Ringkasan compaction
- Pesan setelah `firstKeptEntryId`
Compaction bersifat **persisten** (tidak seperti pemangkasan sesi). Lihat [/concepts/session-pruning](/id/concepts/session-pruning).
## Batas chunk Compaction dan pemasangan alat
## Batas chunk Compaction dan pemasangan tool
Saat OpenClaw membagi transkrip panjang menjadi chunk Compaction, OpenClaw menjaga
panggilan alat asisten tetap berpasangan dengan entri `toolResult` yang sesuai.
Ketika OpenClaw membagi transkrip panjang menjadi chunk compaction, ia menjaga
pemanggilan tool asisten tetap berpasangan dengan entri `toolResult` yang cocok.
- Jika pembagian porsi token jatuh di antara panggilan alat dan hasilnya, OpenClaw
menggeser batas ke pesan panggilan alat asisten alih-alih memisahkan
- Jika split token-share jatuh di antara pemanggilan tool dan hasilnya, OpenClaw
menggeser batas ke pesan pemanggilan tool asisten alih-alih memisahkan
pasangan tersebut.
- Jika blok hasil alat di akhir sebaliknya akan mendorong chunk melewati target,
OpenClaw mempertahankan blok alat tertunda tersebut dan menjaga ekor yang belum diringkas
tetap utuh.
- Blok panggilan alat yang dibatalkan/error tidak menahan pembagian tertunda tetap terbuka.
- Jika blok tool-result trailing seharusnya mendorong chunk melewati target,
OpenClaw mempertahankan blok tool yang tertunda tersebut dan menjaga tail yang
belum diringkas tetap utuh.
- Blok pemanggilan tool yang dibatalkan/error tidak menahan split tertunda tetap terbuka.
---
## Kapan auto-Compaction terjadi (runtime Pi)
## Kapan auto-compaction terjadi (runtime Pi)
Dalam agen Pi tertanam, auto-Compaction dipicu dalam dua kasus:
Dalam agen Pi tersemat, auto-compaction terpicu dalam dua kasus:
1. **Pemulihan overflow**: model mengembalikan error overflow konteks
(`request_too_large`, `context length exceeded`, `input exceeds the maximum
number of tokens`, `input token count exceeds the maximum number of input
tokens`, `input is too long for the model`, `ollama error: context length
exceeded`, dan varian serupa berbentuk penyedia) → compact → coba lagi.
2. **Pemeliharaan ambang**: setelah giliran berhasil, saat:
2. **Pemeliharaan threshold**: setelah giliran berhasil, ketika:
`contextTokens > contextWindow - reserveTokens`
@ -270,14 +270,28 @@ Di mana:
- `contextWindow` adalah jendela konteks model
- `reserveTokens` adalah ruang cadangan yang disisihkan untuk prompt + output model berikutnya
Ini adalah semantik runtime Pi (OpenClaw mengonsumsi event, tetapi Pi memutuskan kapan melakukan Compaction).
Ini adalah semantik runtime Pi (OpenClaw mengonsumsi event, tetapi Pi memutuskan kapan melakukan compaction).
OpenClaw juga dapat memicu Compaction lokal preflight sebelum membuka run berikutnya
saat `agents.defaults.compaction.maxActiveTranscriptBytes` diatur dan file transkrip
aktif mencapai ukuran tersebut. Ini adalah pelindung ukuran file untuk biaya
pembukaan ulang lokal, bukan pengarsipan mentah: OpenClaw tetap menjalankan Compaction
semantik normal, dan memerlukan `truncateAfterCompaction` agar ringkasan yang telah
di-compact dapat menjadi transkrip penerus baru.
OpenClaw juga dapat memicu compaction lokal preflight sebelum membuka run berikutnya
ketika `agents.defaults.compaction.maxActiveTranscriptBytes` disetel dan file
transkrip aktif mencapai ukuran tersebut. Ini adalah pelindung ukuran file untuk
biaya pembukaan ulang lokal, bukan pengarsipan mentah: OpenClaw tetap menjalankan
compaction semantik normal, dan memerlukan `truncateAfterCompaction` agar ringkasan
yang telah dipadatkan dapat menjadi transkrip penerus baru.
Untuk eksekusi Pi tertanam, `agents.defaults.compaction.midTurnPrecheck.enabled: true`
menambahkan guard tool-loop yang bersifat opt-in. Setelah hasil tool ditambahkan dan sebelum
pemanggilan model berikutnya, OpenClaw memperkirakan tekanan prompt menggunakan logika anggaran
preflight yang sama seperti yang digunakan di awal giliran. Jika konteks tidak lagi muat, guard
tidak melakukan Compaction di dalam hook `transformContext` Pi. Guard tersebut memunculkan sinyal
precheck tengah-giliran terstruktur, menghentikan pengiriman prompt saat ini, dan membiarkan
loop eksekusi luar menggunakan jalur pemulihan yang sudah ada: memangkas hasil tool yang terlalu besar
jika itu cukup, atau memicu mode Compaction yang dikonfigurasi dan mencoba lagi. Opsi ini
dinonaktifkan secara default dan bekerja dengan mode Compaction `default` maupun `safeguard`,
termasuk Compaction safeguard yang didukung provider.
Ini independen dari `maxActiveTranscriptBytes`: guard ukuran byte berjalan
sebelum sebuah giliran dibuka, sementara precheck tengah-giliran berjalan kemudian di tool loop Pi tertanam
setelah hasil tool baru ditambahkan.
---
@ -295,47 +309,52 @@ Pengaturan Compaction Pi berada di pengaturan Pi:
}
```
OpenClaw juga memberlakukan batas bawah keamanan untuk proses tertanam:
OpenClaw juga memberlakukan batas bawah keamanan untuk eksekusi tertanam:
- Jika `compaction.reserveTokens < reserveTokensFloor`, OpenClaw menaikkannya.
- Batas bawah default adalah `20000` token.
- Atur `agents.defaults.compaction.reserveTokensFloor: 0` untuk menonaktifkan batas bawah.
- Jika nilainya sudah lebih tinggi, OpenClaw membiarkannya.
- `/compact` manual menghormati `agents.defaults.compaction.keepRecentTokens`
eksplisit dan mempertahankan titik pemotongan ekor terbaru Pi. Tanpa anggaran
simpan eksplisit, compaction manual tetap menjadi checkpoint keras dan konteks
yang dibangun ulang dimulai dari ringkasan baru.
- `/compact` manual menghormati `agents.defaults.compaction.keepRecentTokens` eksplisit
dan mempertahankan titik pemotongan ekor terbaru Pi. Tanpa anggaran simpan eksplisit,
Compaction manual tetap menjadi checkpoint keras dan konteks yang dibangun ulang dimulai dari
ringkasan baru.
- Atur `agents.defaults.compaction.midTurnPrecheck.enabled: true` untuk menjalankan
precheck tool-loop opsional setelah hasil tool baru dan sebelum pemanggilan model berikutnya.
Ini hanya pemicu; pembuatan ringkasan tetap menggunakan jalur Compaction yang dikonfigurasi.
Ini independen dari `maxActiveTranscriptBytes`, yang merupakan guard ukuran byte
transkrip aktif di awal giliran.
- Atur `agents.defaults.compaction.maxActiveTranscriptBytes` ke nilai byte atau
string seperti `"20mb"` untuk menjalankan compaction lokal sebelum giliran saat
transkrip aktif menjadi besar. Pelindung ini hanya aktif saat
`truncateAfterCompaction` juga diaktifkan. Biarkan tidak diatur atau atur ke `0`
untuk menonaktifkan.
- Saat `agents.defaults.compaction.truncateAfterCompaction` diaktifkan,
string seperti `"20mb"` untuk menjalankan Compaction lokal sebelum giliran ketika transkrip aktif
menjadi besar. Guard ini aktif hanya ketika
`truncateAfterCompaction` juga diaktifkan. Biarkan tidak diatur atau atur `0` untuk
menonaktifkan.
- Ketika `agents.defaults.compaction.truncateAfterCompaction` diaktifkan,
OpenClaw merotasi transkrip aktif ke JSONL penerus yang sudah dipadatkan setelah
compaction. Transkrip lengkap lama tetap diarsipkan dan ditautkan dari
checkpoint compaction, bukan ditulis ulang di tempat.
Compaction. Transkrip lengkap lama tetap diarsipkan dan ditautkan dari
checkpoint Compaction alih-alih ditulis ulang di tempat.
Alasan: menyisakan ruang kepala yang cukup untuk “pemeliharaan” beberapa giliran (seperti penulisan memori) sebelum compaction menjadi tidak terhindarkan.
Alasan: menyisakan cukup ruang untuk “housekeeping” multi-giliran (seperti penulisan memori) sebelum Compaction menjadi tidak terhindarkan.
Implementasi: `ensurePiCompactionReserveTokens()` di `src/agents/pi-settings.ts`
(dipanggil dari `src/agents/pi-embedded-runner.ts`).
---
## Penyedia compaction yang dapat dipasang
## Provider Compaction yang dapat dipasang
Plugin dapat mendaftarkan penyedia compaction melalui `registerCompactionProvider()` pada API Plugin. Saat `agents.defaults.compaction.provider` diatur ke id penyedia terdaftar, ekstensi pengaman mendelegasikan peringkasan ke penyedia tersebut, bukan ke pipeline `summarizeInStages` bawaan.
Plugin dapat mendaftarkan provider Compaction melalui `registerCompactionProvider()` pada API plugin. Ketika `agents.defaults.compaction.provider` diatur ke id provider terdaftar, ekstensi safeguard mendelegasikan peringkasan ke provider tersebut alih-alih pipeline bawaan `summarizeInStages`.
- `provider`: id Plugin penyedia compaction terdaftar. Biarkan tidak diatur untuk peringkasan LLM default.
- `provider`: id dari plugin provider Compaction terdaftar. Biarkan tidak diatur untuk peringkasan LLM default.
- Mengatur `provider` memaksa `mode: "safeguard"`.
- Penyedia menerima instruksi compaction dan kebijakan pelestarian pengenal yang sama seperti jalur bawaan.
- Pengaman tetap mempertahankan konteks akhiran giliran terbaru dan giliran terpisah setelah keluaran penyedia.
- Peringkasan pengaman bawaan menyuling ulang ringkasan sebelumnya dengan pesan baru
alih-alih mempertahankan ringkasan sebelumnya secara lengkap apa adanya.
- Mode pengaman mengaktifkan audit kualitas ringkasan secara default; atur
`qualityGuard.enabled: false` untuk melewati perilaku coba ulang saat keluaran salah bentuk.
- Jika penyedia gagal atau mengembalikan hasil kosong, OpenClaw otomatis kembali ke peringkasan LLM bawaan.
- Sinyal abort/timeout dilemparkan kembali (tidak ditelan) untuk menghormati pembatalan pemanggil.
- Provider menerima instruksi Compaction dan kebijakan pelestarian pengenal yang sama seperti jalur bawaan.
- Safeguard tetap mempertahankan konteks akhiran giliran-terbaru dan giliran-terbagi setelah output provider.
- Peringkasan safeguard bawaan menyaring ulang ringkasan sebelumnya dengan pesan baru
alih-alih mempertahankan ringkasan sebelumnya secara verbatim.
- Mode safeguard mengaktifkan audit kualitas ringkasan secara default; atur
`qualityGuard.enabled: false` untuk melewati perilaku coba-ulang-pada-output-cacat.
- Jika provider gagal atau mengembalikan hasil kosong, OpenClaw otomatis kembali ke peringkasan LLM bawaan.
- Sinyal abort/timeout dilempar ulang (tidak ditelan) untuk menghormati pembatalan pemanggil.
Sumber: `src/plugins/compaction-provider.ts`, `src/agents/pi-hooks/compaction-safeguard.ts`.
@ -343,53 +362,53 @@ Sumber: `src/plugins/compaction-provider.ts`, `src/agents/pi-hooks/compaction-sa
## Permukaan yang terlihat pengguna
Anda dapat mengamati compaction dan status sesi melalui:
Anda dapat mengamati Compaction dan status sesi melalui:
- `/status` (di sesi chat mana pun)
- `/status` (di sesi chat apa pun)
- `openclaw status` (CLI)
- `openclaw sessions` / `sessions --json`
- Mode verbose: `🧹 Auto-compaction complete` + jumlah compaction
- Mode verbose: `🧹 Auto-compaction complete` + jumlah Compaction
---
## Pemeliharaan senyap (`NO_REPLY`)
## Housekeeping senyap (`NO_REPLY`)
OpenClaw mendukung giliran “senyap” untuk tugas latar belakang saat pengguna tidak boleh melihat keluaran perantara.
OpenClaw mendukung giliran “senyap” untuk tugas latar belakang ketika pengguna tidak seharusnya melihat output antara.
Konvensi:
- Asisten memulai keluarannya dengan token senyap persis `NO_REPLY` /
- Asisten memulai outputnya dengan token senyap persis `NO_REPLY` /
`no_reply` untuk menunjukkan “jangan kirim balasan kepada pengguna”.
- OpenClaw menghapus/menekan ini di lapisan pengiriman.
- Penekanan token senyap persis tidak peka huruf besar-kecil, sehingga `NO_REPLY` dan
`no_reply` sama-sama dihitung saat seluruh muatan hanya berupa token senyap.
- Ini hanya untuk giliran latar belakang/tanpa pengiriman yang sebenarnya; ini bukan pintasan untuk
permintaan pengguna biasa yang dapat ditindaklanjuti.
- Penekanan token senyap persis tidak peka huruf besar-kecil, jadi `NO_REPLY` dan
`no_reply` keduanya dihitung ketika seluruh payload hanyalah token senyap.
- Ini hanya untuk giliran latar belakang/tanpa-pengiriman sungguhan; ini bukan jalan pintas untuk
permintaan pengguna yang dapat ditindaklanjuti biasa.
Sejak `2026.1.10`, OpenClaw juga menekan **streaming draf/pengetikan** saat
potongan parsial dimulai dengan `NO_REPLY`, sehingga operasi senyap tidak membocorkan keluaran
parsial di tengah giliran.
Sejak `2026.1.10`, OpenClaw juga menekan **streaming draf/pengetikan** ketika
chunk parsial dimulai dengan `NO_REPLY`, sehingga operasi senyap tidak membocorkan output parsial
di tengah giliran.
---
## "Memory flush" pra-compaction (diimplementasikan)
## "Flush memori" pra-Compaction (diimplementasikan)
Tujuan: sebelum auto-compaction terjadi, jalankan giliran agentik senyap yang menulis
status tahan lama ke disk (misalnya `memory/YYYY-MM-DD.md` di workspace agen) sehingga compaction tidak dapat
Tujuan: sebelum Compaction otomatis terjadi, jalankan giliran agentik senyap yang menulis status tahan lama
ke disk (misalnya `memory/YYYY-MM-DD.md` di workspace agen) sehingga Compaction tidak dapat
menghapus konteks penting.
OpenClaw menggunakan pendekatan **flush pra-ambang**:
1. Pantau penggunaan konteks sesi.
2. Saat melewati “ambang lunak” (di bawah ambang compaction Pi), jalankan arahan senyap
“tulis memori sekarang” ke agen.
2. Ketika melewati “ambang lunak” (di bawah ambang Compaction Pi), jalankan direktif senyap
“tulis memori sekarang” kepada agen.
3. Gunakan token senyap persis `NO_REPLY` / `no_reply` sehingga pengguna tidak melihat
apa pun.
Konfigurasi (`agents.defaults.compaction.memoryFlush`):
- `enabled` (default: `true`)
- `model` (opsional override penyedia/model persis untuk giliran flush, misalnya `ollama/qwen3:8b`)
- `model` (override provider/model persis opsional untuk giliran flush, misalnya `ollama/qwen3:8b`)
- `softThresholdTokens` (default: `4000`)
- `prompt` (pesan pengguna untuk giliran flush)
- `systemPrompt` (prompt sistem tambahan yang ditambahkan untuk giliran flush)
@ -398,12 +417,12 @@ Catatan:
- Prompt/prompt sistem default menyertakan petunjuk `NO_REPLY` untuk menekan
pengiriman.
- Saat `model` diatur, giliran flush menggunakan model tersebut tanpa mewarisi rantai fallback
sesi aktif, sehingga pemeliharaan khusus lokal tidak diam-diam
- Ketika `model` diatur, giliran flush menggunakan model tersebut tanpa mewarisi
rantai fallback sesi aktif, sehingga housekeeping khusus lokal tidak diam-diam
fallback ke model percakapan berbayar.
- Flush berjalan sekali per siklus compaction (dilacak di `sessions.json`).
- Flush berjalan sekali per siklus Compaction (dilacak di `sessions.json`).
- Flush hanya berjalan untuk sesi Pi tertanam (backend CLI melewatinya).
- Flush dilewati saat workspace sesi bersifat hanya baca (`workspaceAccess: "ro"` atau `"none"`).
- Flush dilewati ketika workspace sesi bersifat hanya-baca (`workspaceAccess: "ro"` atau `"none"`).
- Lihat [Memori](/id/concepts/memory) untuk tata letak file workspace dan pola penulisan.
Pi juga mengekspos hook `session_before_compact` di API ekstensi, tetapi logika
@ -411,14 +430,14 @@ flush OpenClaw saat ini berada di sisi Gateway.
---
## Checklist pemecahan masalah
## Daftar periksa pemecahan masalah
- Kunci sesi salah? Mulai dengan [/concepts/session](/id/concepts/session) dan konfirmasi `sessionKey` di `/status`.
- Ketidakcocokan store vs transkrip? Konfirmasi host Gateway dan jalur store dari `openclaw status`.
- Spam compaction? Periksa:
- Spam Compaction? Periksa:
- jendela konteks model (terlalu kecil)
- pengaturan compaction (`reserveTokens` terlalu tinggi untuk jendela model dapat menyebabkan compaction lebih awal)
- pembengkakan hasil alat: aktifkan/sesuaikan pemangkasan sesi
- pengaturan Compaction (`reserveTokens` terlalu tinggi untuk jendela model dapat menyebabkan Compaction lebih awal)
- pembengkakan hasil tool: aktifkan/sesuaikan pemangkasan sesi
- Giliran senyap bocor? Konfirmasi balasan dimulai dengan `NO_REPLY` (token persis tidak peka huruf besar-kecil) dan Anda menggunakan build yang menyertakan perbaikan penekanan streaming.
## Terkait

150
docs/id/tools/index.md
View File

@ -3,13 +3,13 @@ read_when:
- Anda ingin memahami alat apa saja yang disediakan OpenClaw
- Anda perlu mengonfigurasi, mengizinkan, atau menolak alat
- Anda sedang memilih antara alat bawaan, Skills, dan Plugin
summary: 'Gambaran umum alat dan Plugin OpenClaw: apa yang dapat dilakukan agen dan cara memperluasnya'
summary: 'Ikhtisar alat dan plugin OpenClaw: apa yang dapat dilakukan agen dan cara memperluasnya'
title: Alat dan Plugin
x-i18n:
generated_at: "2026-04-30T10:15:42Z"
generated_at: "2026-04-30T16:30:15Z"
model: gpt-5.5
provider: openai
source_hash: 62cde740188c224af03b4425c7f6dfca9a12f95603066db5925724fc6a07dcf0
source_hash: 7acfac11669b6f9696a368c08afada8d33e30ac2f452d507f5d1bc36bae367eb
source_path: tools/index.md
workflow: 16
---
@ -18,38 +18,38 @@ Semua yang dilakukan agen selain menghasilkan teks terjadi melalui **alat**.
Alat adalah cara agen membaca berkas, menjalankan perintah, menjelajahi web, mengirim
pesan, dan berinteraksi dengan perangkat.
## Alat, Skills, dan plugin
## Alat, Skills, dan Plugin
OpenClaw memiliki tiga lapisan yang bekerja bersama:
<Steps>
<Step title="Alat adalah yang dipanggil agen">
Alat adalah fungsi bertipe yang dapat dipanggil agen (mis. `exec`, `browser`,
`web_search`, `message`). OpenClaw menyediakan serangkaian **alat bawaan** dan
`web_search`, `message`). OpenClaw menyertakan sekumpulan **alat bawaan** dan
plugin dapat mendaftarkan alat tambahan.
Agen melihat alat sebagai definisi fungsi terstruktur yang dikirim ke API model.
</Step>
<Step title="Skills mengajari agen kapan dan bagaimana">
<Step title="Skills mengajarkan agen kapan dan bagaimana">
Skill adalah berkas markdown (`SKILL.md`) yang disisipkan ke prompt sistem.
Skills memberi agen konteks, batasan, dan panduan langkah demi langkah untuk
menggunakan alat secara efektif. Skills berada di workspace Anda, di folder bersama,
menggunakan alat secara efektif. Skills berada di ruang kerja Anda, di folder bersama,
atau disertakan di dalam plugin.
[Referensi Skills](/id/tools/skills) | [Membuat Skills](/id/tools/creating-skills)
</Step>
<Step title="Plugin mengemas semuanya menjadi satu">
<Step title="Plugin mengemas semuanya bersama">
Plugin adalah paket yang dapat mendaftarkan kombinasi kapabilitas apa pun:
channel, penyedia model, alat, Skills, ucapan, transkripsi realtime,
kanal, penyedia model, alat, Skills, ucapan, transkripsi realtime,
suara realtime, pemahaman media, pembuatan gambar, pembuatan video,
pengambilan web, pencarian web, dan lainnya. Beberapa plugin bersifat **core** (disertakan bersama
OpenClaw), yang lain bersifat **eksternal** (diterbitkan di npm oleh komunitas).
pengambilan web, pencarian web, dan lainnya. Sebagian plugin bersifat **inti** (disertakan bersama
OpenClaw), sedangkan yang lain bersifat **eksternal** (diterbitkan di npm oleh komunitas).
[Instal dan konfigurasikan plugin](/id/tools/plugin) | [Bangun milik Anda sendiri](/id/plugins/building-plugins)
[Instal dan konfigurasi plugin](/id/tools/plugin) | [Bangun milik Anda sendiri](/id/plugins/building-plugins)
</Step>
</Steps>
@ -58,33 +58,33 @@ OpenClaw memiliki tiga lapisan yang bekerja bersama:
Alat ini disertakan bersama OpenClaw dan tersedia tanpa menginstal plugin apa pun:
| Alat | Fungsinya | Halaman |
| ------------------------------------------ | ---------------------------------------------------------------------- | ------------------------------------------------------------ |
| `exec` / `process` | Menjalankan perintah shell, mengelola proses latar belakang | [Exec](/id/tools/exec), [Persetujuan Exec](/id/tools/exec-approvals) |
| `code_execution` | Menjalankan analisis Python jarak jauh dalam sandbox | [Eksekusi Kode](/id/tools/code-execution) |
| `browser` | Mengendalikan browser Chromium (navigasi, klik, tangkapan layar) | [Browser](/id/tools/browser) |
| `web_search` / `x_search` / `web_fetch` | Mencari di web, mencari postingan X, mengambil konten halaman | [Web](/id/tools/web), [Pengambilan Web](/id/tools/web-fetch) |
| `read` / `write` / `edit` | I/O berkas di workspace | |
| `apply_patch` | Patch berkas multi-hunk | [Terapkan Patch](/id/tools/apply-patch) |
| `message` | Mengirim pesan di semua channel | [Kirim Agen](/id/tools/agent-send) |
| `canvas` | Menggerakkan Node Canvas (present, eval, snapshot) | |
| `nodes` | Menemukan dan menargetkan perangkat yang dipasangkan | |
| `cron` / `gateway` | Mengelola job terjadwal; memeriksa, menambal, memulai ulang, atau memperbarui Gateway | |
| `image` / `image_generate` | Menganalisis atau membuat gambar | [Pembuatan Gambar](/id/tools/image-generation) |
| `music_generate` | Membuat trek musik | [Pembuatan Musik](/id/tools/music-generation) |
| `video_generate` | Membuat video | [Pembuatan Video](/id/tools/video-generation) |
| `tts` | Konversi teks ke ucapan sekali jalan | [TTS](/id/tools/tts) |
| `sessions_*` / `subagents` / `agents_list` | Manajemen sesi, status, dan orkestrasi sub-agen | [Sub-agen](/id/tools/subagents) |
| `session_status` | Pembacaan balik ringan bergaya `/status` dan override model sesi | [Alat Sesi](/id/concepts/session-tool) |
| Alat | Fungsinya | Halaman |
| ------------------------------------------ | --------------------------------------------------------------------- | ------------------------------------------------------------ |
| `exec` / `process` | Menjalankan perintah shell, mengelola proses latar belakang | [Exec](/id/tools/exec), [Persetujuan Exec](/id/tools/exec-approvals) |
| `code_execution` | Menjalankan analisis Python jarak jauh dalam sandbox | [Eksekusi Kode](/id/tools/code-execution) |
| `browser` | Mengontrol browser Chromium (navigasi, klik, tangkapan layar) | [Browser](/id/tools/browser) |
| `web_search` / `x_search` / `web_fetch` | Mencari di web, mencari posting X, mengambil konten halaman | [Web](/id/tools/web), [Pengambilan Web](/id/tools/web-fetch) |
| `read` / `write` / `edit` | I/O berkas di ruang kerja | |
| `apply_patch` | Patch berkas multi-hunk | [Terapkan Patch](/id/tools/apply-patch) |
| `message` | Mengirim pesan di semua kanal | [Kirim Agen](/id/tools/agent-send) |
| `canvas` | Mengendalikan node Canvas (presentasi, eval, snapshot) | |
| `nodes` | Menemukan dan menargetkan perangkat yang dipasangkan | |
| `cron` / `gateway` | Mengelola pekerjaan terjadwal; memeriksa, menambal, memulai ulang, atau memperbarui gateway | |
| `image` / `image_generate` | Menganalisis atau menghasilkan gambar | [Pembuatan Gambar](/id/tools/image-generation) |
| `music_generate` | Menghasilkan trek musik | [Pembuatan Musik](/id/tools/music-generation) |
| `video_generate` | Menghasilkan video | [Pembuatan Video](/id/tools/video-generation) |
| `tts` | Konversi teks-ke-ucapan sekali jalan | [TTS](/id/tools/tts) |
| `sessions_*` / `subagents` / `agents_list` | Manajemen sesi, status, dan orkestrasi sub-agen | [Sub-agen](/id/tools/subagents) |
| `session_status` | Pembacaan balik ringan bergaya `/status` dan override model sesi | [Alat Sesi](/id/concepts/session-tool) |
Untuk pekerjaan gambar, gunakan `image` untuk analisis dan `image_generate` untuk pembuatan atau pengeditan. Jika Anda menargetkan `openai/*`, `google/*`, `fal/*`, atau penyedia gambar non-default lain, konfigurasikan auth/kunci API penyedia tersebut terlebih dahulu.
Untuk pekerjaan gambar, gunakan `image` untuk analisis dan `image_generate` untuk pembuatan atau penyuntingan. Jika Anda menargetkan `openai/*`, `google/*`, `fal/*`, atau penyedia gambar non-default lain, konfigurasikan autentikasi/kunci API penyedia tersebut terlebih dahulu.
Untuk pekerjaan musik, gunakan `music_generate`. Jika Anda menargetkan `google/*`, `minimax/*`, atau penyedia musik non-default lain, konfigurasikan auth/kunci API penyedia tersebut terlebih dahulu.
Untuk pekerjaan musik, gunakan `music_generate`. Jika Anda menargetkan `google/*`, `minimax/*`, atau penyedia musik non-default lain, konfigurasikan autentikasi/kunci API penyedia tersebut terlebih dahulu.
Untuk pekerjaan video, gunakan `video_generate`. Jika Anda menargetkan `qwen/*` atau penyedia video non-default lain, konfigurasikan auth/kunci API penyedia tersebut terlebih dahulu.
Untuk pekerjaan video, gunakan `video_generate`. Jika Anda menargetkan `qwen/*` atau penyedia video non-default lain, konfigurasikan autentikasi/kunci API penyedia tersebut terlebih dahulu.
Untuk pembuatan audio berbasis workflow, gunakan `music_generate` ketika plugin seperti
ComfyUI mendaftarkannya. Ini terpisah dari `tts`, yang merupakan teks-ke-ucapan.
Untuk pembuatan audio berbasis alur kerja, gunakan `music_generate` ketika plugin seperti
ComfyUI mendaftarkannya. Ini terpisah dari `tts`, yaitu teks-ke-ucapan.
`session_status` adalah alat status/pembacaan balik ringan dalam grup sesi.
Alat ini menjawab pertanyaan bergaya `/status` tentang sesi saat ini dan dapat
@ -92,38 +92,38 @@ secara opsional menetapkan override model per sesi; `model=default` menghapus
override tersebut. Seperti `/status`, alat ini dapat mengisi balik penghitung token/cache yang jarang dan
label model runtime aktif dari entri penggunaan transkrip terbaru.
`gateway` adalah alat runtime khusus pemilik untuk operasi Gateway:
`gateway` adalah alat runtime khusus pemilik untuk operasi gateway:
- `config.schema.lookup` untuk satu subtree konfigurasi yang dibatasi path sebelum pengeditan
- `config.schema.lookup` untuk satu subtree konfigurasi dengan cakupan path sebelum penyuntingan
- `config.get` untuk snapshot konfigurasi saat ini + hash
- `config.patch` untuk pembaruan konfigurasi parsial dengan mulai ulang
- `config.apply` hanya untuk penggantian konfigurasi penuh
- `update.run` untuk self-update eksplisit + mulai ulang
- `update.run` untuk pembaruan mandiri eksplisit + mulai ulang
Untuk perubahan parsial, utamakan `config.schema.lookup` lalu `config.patch`. Gunakan
`config.apply` hanya ketika Anda sengaja mengganti seluruh konfigurasi.
`config.apply` hanya ketika Anda memang sengaja mengganti seluruh konfigurasi.
Untuk dokumentasi konfigurasi yang lebih luas, baca [Konfigurasi](/id/gateway/configuration) dan
[Referensi konfigurasi](/id/gateway/configuration-reference).
Alat ini juga menolak mengubah `tools.exec.ask` atau `tools.exec.security`;
alias lama `tools.bash.*` dinormalisasi ke path exec terlindungi yang sama.
alias legacy `tools.bash.*` dinormalisasi ke path exec terlindungi yang sama.
### Alat yang disediakan plugin
Plugin dapat mendaftarkan alat tambahan. Beberapa contoh:
- [Diff](/id/tools/diffs) — penampil dan perender diff
- [Tugas LLM](/id/tools/llm-task) — langkah LLM khusus JSON untuk output terstruktur
- [Lobster](/id/tools/lobster) — runtime workflow bertipe dengan persetujuan yang dapat dilanjutkan
- [Pembuatan Musik](/id/tools/music-generation) — alat `music_generate` bersama dengan penyedia berbasis workflow
- [OpenProse](/id/prose) — orkestrasi workflow yang mengutamakan markdown
- [Tugas LLM](/id/tools/llm-task) — langkah LLM khusus JSON untuk keluaran terstruktur
- [Lobster](/id/tools/lobster) — runtime alur kerja bertipe dengan persetujuan yang dapat dilanjutkan
- [Pembuatan Musik](/id/tools/music-generation) — alat `music_generate` bersama dengan penyedia berbasis alur kerja
- [OpenProse](/id/prose) — orkestrasi alur kerja yang mengutamakan markdown
- [Tokenjuice](/id/tools/tokenjuice) — memadatkan hasil alat `exec` dan `bash` yang berisik
## Konfigurasi alat
### Daftar izinkan dan tolak
### Daftar izin dan tolak
Kontrol alat mana yang dapat dipanggil agen melalui `tools.allow` / `tools.deny` di
konfigurasi. Tolak selalu menang atas izinkan.
Kontrol alat mana yang dapat dipanggil agen melalui `tools.allow` / `tools.deny` dalam
konfigurasi. Tolak selalu menang atas izin.
```json5
{
@ -136,42 +136,46 @@ konfigurasi. Tolak selalu menang atas izinkan.
OpenClaw gagal tertutup ketika allowlist eksplisit tidak menghasilkan alat yang dapat dipanggil.
Misalnya, `tools.allow: ["query_db"]` hanya berfungsi jika plugin yang dimuat benar-benar
mendaftarkan `query_db`. Jika tidak ada alat bawaan, plugin, atau alat MCP bundle yang cocok dengan
allowlist, proses berhenti sebelum panggilan model alih-alih berlanjut sebagai
proses hanya teks yang dapat berhalusinasi hasil alat.
mendaftarkan `query_db`. Jika tidak ada alat bawaan, plugin, atau alat MCP bundel yang cocok dengan
allowlist, eksekusi berhenti sebelum panggilan model alih-alih berlanjut sebagai
eksekusi hanya-teks yang dapat menghalusinasi hasil alat.
### Profil alat
`tools.profile` menetapkan allowlist dasar sebelum `allow`/`deny` diterapkan.
Override per agen: `agents.list[].tools.profile`.
Override per-agen: `agents.list[].tools.profile`.
| Profil | Yang disertakan |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `full` | Baseline tanpa batasan untuk akses perintah/kontrol yang lebih luas; sama seperti membiarkan `tools.profile` tidak disetel |
| `full` | Baseline tanpa pembatasan untuk akses perintah/kontrol yang lebih luas; sama seperti membiarkan `tools.profile` tidak disetel |
| `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `music_generate`, `video_generate` |
| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` |
| `minimal` | Hanya `session_status` |
<Note>
`tools.profile: "messaging"` sengaja dibuat sempit untuk agen yang berfokus pada channel.
Profil ini mengecualikan alat perintah/kontrol yang lebih luas seperti filesystem, runtime,
browser, canvas, nodes, Cron, dan kontrol Gateway. Gunakan `tools.profile: "full"`
sebagai baseline tanpa batasan untuk akses perintah/kontrol yang lebih luas, lalu pangkas
akses dengan `tools.allow` / `tools.deny` saat diperlukan.
`tools.profile: "messaging"` sengaja dibuat sempit untuk agen yang berfokus pada kanal.
Profil ini mengecualikan alat perintah/kontrol yang lebih luas seperti sistem berkas, runtime,
browser, canvas, node, Cron, dan kontrol Gateway. Gunakan `tools.profile: "full"`
sebagai baseline tanpa pembatasan untuk akses perintah/kontrol yang lebih luas, lalu pangkas
akses dengan `tools.allow` / `tools.deny` ketika diperlukan.
</Note>
`coding` mencakup alat web ringan (`web_search`, `web_fetch`, `x_search`)
tetapi bukan alat kontrol browser penuh. Otomasi browser dapat menggerakkan
`coding` menyertakan alat web ringan (`web_search`, `web_fetch`, `x_search`)
tetapi bukan alat kontrol browser penuh. Otomasi browser dapat mengendalikan
sesi nyata dan profil yang sudah login, jadi tambahkan secara eksplisit dengan
`tools.alsoAllow: ["browser"]` atau per agen
`tools.alsoAllow: ["browser"]` atau per-agen
`agents.list[].tools.alsoAllow: ["browser"]`.
Profil `coding` dan `messaging` juga mengizinkan alat MCP bundle yang dikonfigurasi
di bawah kunci plugin `bundle-mcp`. Tambahkan `tools.deny: ["bundle-mcp"]` ketika Anda
ingin profil mempertahankan alat bawaan normalnya tetapi menyembunyikan semua alat MCP yang dikonfigurasi.
Profil `minimal` tidak mencakup alat MCP bundle.
<Note>
Mengonfigurasi `tools.exec` atau `tools.fs` di bawah profil restriktif (`messaging`, `minimal`) tidak secara implisit memperluas allowlist profil tersebut. Tambahkan entri `tools.alsoAllow` eksplisit (misalnya `["exec", "process"]` untuk exec, atau `["read", "write", "edit"]` untuk fs) ketika Anda ingin profil restriktif menggunakan bagian yang dikonfigurasi tersebut. OpenClaw mencatat peringatan saat startup ketika bagian konfigurasi ada tanpa grant `alsoAllow` yang cocok.
</Note>
Contoh (permukaan alat terluas secara default):
Profil `coding` dan `messaging` juga mengizinkan alat MCP bundel yang dikonfigurasi
di bawah kunci plugin `bundle-mcp`. Tambahkan `tools.deny: ["bundle-mcp"]` ketika Anda
ingin profil mempertahankan bawaan normalnya tetapi menyembunyikan semua alat MCP yang dikonfigurasi.
Profil `minimal` tidak menyertakan alat MCP bundel.
Contoh (permukaan alat paling luas secara default):
```json5
{
@ -183,7 +187,7 @@ Contoh (permukaan alat terluas secara default):
### Grup alat
Gunakan singkatan `group:*` dalam daftar izinkan/tolak:
Gunakan singkatan `group:*` dalam daftar izin/tolak:
| Grup | Alat |
| ------------------ | --------------------------------------------------------------------------------------------------------- |
@ -198,16 +202,16 @@ Gunakan singkatan `group:*` dalam daftar izinkan/tolak:
| `group:nodes` | nodes |
| `group:agents` | agents_list |
| `group:media` | image, image_generate, music_generate, video_generate, tts |
| `group:openclaw` | Semua alat bawaan OpenClaw (tidak termasuk alat Plugin) |
| `group:openclaw` | Semua alat OpenClaw bawaan (tidak termasuk alat plugin) |
`sessions_history` mengembalikan tampilan ingatan kembali yang dibatasi dan difilter demi keamanan. Ini menghapus
tag pemikiran, kerangka `<relevant-memories>`, muatan XML pemanggilan alat teks biasa
`sessions_history` mengembalikan tampilan ingatan terbatas yang difilter demi keamanan. Ini menghapus
tag pemikiran, kerangka `<relevant-memories>`, payload XML panggilan alat teks biasa
(termasuk `<tool_call>...</tool_call>`,
`<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`,
`<function_calls>...</function_calls>`, dan blok pemanggilan alat yang dipotong),
kerangka pemanggilan alat yang diturunkan, token kontrol model ASCII/lebar-penuh yang bocor,
dan XML pemanggilan alat MiniMax yang tidak valid dari teks asisten, lalu menerapkan
redaksi/pemotongan dan kemungkinan placeholder baris yang terlalu besar alih-alih bertindak
`<function_calls>...</function_calls>`, dan blok panggilan alat yang terpotong),
kerangka panggilan alat yang diturunkan, token kontrol model ASCII/lebar penuh yang bocor,
dan XML panggilan alat MiniMax yang keliru bentuknya dari teks asisten, lalu menerapkan
redaksi/pemotongan dan kemungkinan placeholder baris terlalu besar alih-alih bertindak
sebagai dump transkrip mentah.
### Pembatasan khusus penyedia

342
docs/id/tools/subagents.md
View File

@ -1,38 +1,38 @@
---
read_when:
- Anda ingin pekerjaan di latar belakang atau paralel melalui agen
- Anda ingin menjalankan pekerjaan latar belakang atau paralel melalui agen
- Anda mengubah kebijakan alat sessions_spawn atau sub-agen
- Anda sedang mengimplementasikan atau memecahkan masalah sesi subagen yang terikat pada utas
- Anda sedang mengimplementasikan atau memecahkan masalah sesi subagen yang terikat utas
sidebarTitle: Sub-agents
summary: Buat eksekusi agen latar belakang terisolasi yang mengumumkan hasil kembali ke obrolan peminta
summary: Mulai eksekusi agen latar belakang terisolasi yang mengumumkan hasilnya kembali ke chat peminta
title: Sub-agen
x-i18n:
generated_at: "2026-04-30T10:17:32Z"
generated_at: "2026-04-30T16:30:20Z"
model: gpt-5.5
provider: openai
source_hash: 84386ea706873cf9f2ea03261f916c8fb01304999f2d9fa86e037e734a62bf7e
source_hash: c7c46d2c6d9ddac23653dcbfaf20df0ff5be9619035a1b115a3b49fd48fd8280
source_path: tools/subagents.md
workflow: 16
---
Sub-agen adalah eksekusi agen latar belakang yang dibuat dari eksekusi agen yang sudah ada.
Mereka berjalan dalam sesi sendiri (`agent:<agentId>:subagent:<uuid>`) dan,
setelah selesai, **mengumumkan** hasilnya kembali ke saluran obrolan
Sub-agen adalah eksekusi agen latar belakang yang dimunculkan dari eksekusi agen yang sudah ada.
Sub-agen berjalan dalam sesi sendiri (`agent:<agentId>:subagent:<uuid>`) dan,
setelah selesai, **mengumumkan** hasilnya kembali ke kanal chat
peminta. Setiap eksekusi sub-agen dilacak sebagai
[tugas latar belakang](/id/automation/tasks).
Tujuan utama:
- Memparalelkan pekerjaan "riset / tugas panjang / alat lambat" tanpa memblokir eksekusi utama.
- Menjaga sub-agen tetap terisolasi secara default (pemisahan sesi + sandbox opsional).
- Menjaga permukaan alat sulit disalahgunakan: sub-agen **tidak** mendapatkan alat sesi secara default.
- Mendukung kedalaman nesting yang dapat dikonfigurasi untuk pola orkestrator.
- Menjaga sub-agen tetap terisolasi secara default (pemisahan sesi + sandboxing opsional).
- Menjaga permukaan alat sulit disalahgunakan: sub-agen secara default **tidak** mendapatkan alat sesi.
- Mendukung kedalaman nesting yang dapat dikonfigurasi untuk pola orchestrator.
<Note>
**Catatan biaya:** setiap sub-agen memiliki konteks dan penggunaan tokennya sendiri secara
default. Untuk tugas berat atau repetitif, tetapkan model yang lebih murah untuk sub-agen
**Catatan biaya:** setiap sub-agen memiliki konteks dan penggunaan token sendiri secara
default. Untuk tugas berat atau berulang, tetapkan model yang lebih murah untuk sub-agen
dan pertahankan agen utama Anda pada model berkualitas lebih tinggi. Konfigurasikan melalui
`agents.defaults.subagents.model` atau override per agen. Ketika anak
`agents.defaults.subagents.model` atau override per agen. Ketika child
benar-benar membutuhkan transkrip peminta saat ini, agen dapat meminta
`context: "fork"` pada satu spawn tersebut.
</Note>
@ -53,14 +53,14 @@ saat ini**:
```
`/subagents info` menampilkan metadata eksekusi (status, timestamp, id sesi,
path transkrip, pembersihan). Gunakan `sessions_history` untuk tampilan ingatan
terbatas dan difilter keamanan; periksa path transkrip di disk ketika Anda
jalur transkrip, pembersihan). Gunakan `sessions_history` untuk tampilan ingatan
terbatas dan terfilter demi keamanan; periksa jalur transkrip di disk ketika Anda
membutuhkan transkrip lengkap mentah.
### Kontrol binding thread
### Kontrol pengikatan thread
Perintah ini berfungsi pada saluran yang mendukung binding thread persisten.
Lihat [Saluran yang mendukung thread](#thread-supporting-channels) di bawah.
Perintah ini berfungsi pada kanal yang mendukung pengikatan thread persisten.
Lihat [Kanal pendukung thread](#thread-supporting-channels) di bawah.
```text
/focus <subagent-label|session-key|session-id|session-label>
@ -73,39 +73,39 @@ Lihat [Saluran yang mendukung thread](#thread-supporting-channels) di bawah.
### Perilaku spawn
`/subagents spawn` memulai sub-agen latar belakang sebagai perintah pengguna (bukan
relay internal) dan mengirim satu pembaruan penyelesaian final kembali ke
obrolan peminta saat eksekusi selesai.
relay internal) dan mengirim satu pembaruan penyelesaian akhir kembali ke
chat peminta saat eksekusi selesai.
<AccordionGroup>
<Accordion title="Penyelesaian non-pemblokir berbasis push">
- Perintah spawn bersifat non-pemblokir; ia segera mengembalikan id eksekusi.
- Saat selesai, sub-agen mengumumkan pesan ringkasan/hasil kembali ke saluran obrolan peminta.
- Penyelesaian berbasis push. Setelah dibuat, jangan melakukan polling `/subagents list`, `sessions_list`, atau `sessions_history` dalam loop hanya untuk menunggu selesai; periksa status hanya sesuai kebutuhan untuk debugging atau intervensi.
<Accordion title="Penyelesaian berbasis push dan nonblokir">
- Perintah spawn bersifat nonblokir; perintah ini langsung mengembalikan id eksekusi.
- Saat selesai, sub-agen mengumumkan pesan ringkasan/hasil kembali ke kanal chat peminta.
- Penyelesaian berbasis push. Setelah dimunculkan, jangan melakukan polling `/subagents list`, `sessions_list`, atau `sessions_history` dalam loop hanya untuk menunggu selesai; periksa status hanya sesuai kebutuhan untuk debugging atau intervensi.
- Saat selesai, OpenClaw berupaya sebaik mungkin menutup tab/proses browser terlacak yang dibuka oleh sesi sub-agen tersebut sebelum alur pembersihan pengumuman berlanjut.
</Accordion>
<Accordion title="Ketahanan pengiriman spawn manual">
- OpenClaw mencoba pengiriman langsung `agent` terlebih dahulu dengan kunci idempotensi yang stabil.
- Jika pengiriman langsung gagal, ia fallback ke routing antrean.
- Jika routing antrean masih tidak tersedia, pengumuman dicoba ulang dengan backoff eksponensial singkat sebelum akhirnya menyerah.
- Pengiriman penyelesaian mempertahankan rute peminta yang telah di-resolve: rute penyelesaian terikat thread atau terikat percakapan menang ketika tersedia; jika asal penyelesaian hanya menyediakan saluran, OpenClaw mengisi target/akun yang hilang dari rute sesi peminta yang telah di-resolve (`lastChannel` / `lastTo` / `lastAccountId`) sehingga pengiriman langsung tetap berfungsi.
- OpenClaw mencoba pengiriman `agent` langsung terlebih dahulu dengan kunci idempotensi yang stabil.
- Jika pengiriman langsung gagal, OpenClaw fallback ke perutean antrean.
- Jika perutean antrean masih tidak tersedia, pengumuman dicoba ulang dengan backoff eksponensial singkat sebelum akhirnya menyerah.
- Pengiriman penyelesaian mempertahankan rute peminta yang terselesaikan: rute penyelesaian yang terikat thread atau terikat percakapan menang saat tersedia; jika asal penyelesaian hanya menyediakan kanal, OpenClaw mengisi target/akun yang hilang dari rute terselesaikan sesi peminta (`lastChannel` / `lastTo` / `lastAccountId`) sehingga pengiriman langsung tetap berfungsi.
</Accordion>
<Accordion title="Metadata handoff penyelesaian">
Handoff penyelesaian ke sesi peminta adalah konteks internal yang dibuat runtime
(bukan teks yang ditulis pengguna) dan mencakup:
- `Result` — teks balasan `assistant` terbaru yang terlihat, jika tidak ada maka teks tool/toolResult terbaru yang telah disanitasi. Eksekusi gagal terminal tidak menggunakan ulang teks balasan yang ditangkap.
- `Result` — teks balasan `assistant` terlihat terbaru, atau teks tool/toolResult terbaru yang disanitasi. Eksekusi gagal terminal tidak menggunakan ulang teks balasan yang tertangkap.
- `Status` — `completed successfully` / `failed` / `timed out` / `unknown`.
- Statistik runtime/token ringkas.
- Instruksi pengiriman yang memberi tahu agen peminta untuk menulis ulang dengan suara asisten normal (bukan meneruskan metadata internal mentah).
</Accordion>
<Accordion title="Mode dan runtime ACP">
- `--model` dan `--thinking` mengoverride default untuk eksekusi spesifik tersebut.
- Gunakan `info`/`log` untuk memeriksa detail dan output setelah selesai.
- `--model` dan `--thinking` mengesampingkan default untuk eksekusi spesifik tersebut.
- Gunakan `info`/`log` untuk memeriksa detail dan output setelah penyelesaian.
- `/subagents spawn` adalah mode sekali jalan (`mode: "run"`). Untuk sesi persisten yang terikat thread, gunakan `sessions_spawn` dengan `thread: true` dan `mode: "session"`.
- Untuk sesi harness ACP (Claude Code, Gemini CLI, OpenCode, atau Codex ACP/acpx eksplisit), gunakan `sessions_spawn` dengan `runtime: "acp"` ketika alat mengiklankan runtime tersebut. Lihat [Model pengiriman ACP](/id/tools/acp-agents#delivery-model) saat men-debug penyelesaian atau loop agen-ke-agen. Ketika plugin `codex` diaktifkan, kontrol obrolan/thread Codex sebaiknya memilih `/codex ...` dibanding ACP kecuali pengguna secara eksplisit meminta ACP/acpx.
- Untuk sesi harness ACP (Claude Code, Gemini CLI, OpenCode, atau Codex ACP/acpx eksplisit), gunakan `sessions_spawn` dengan `runtime: "acp"` ketika alat mengiklankan runtime tersebut. Lihat [model pengiriman ACP](/id/tools/acp-agents#delivery-model) saat men-debug penyelesaian atau loop agen-ke-agen. Ketika plugin `codex` diaktifkan, kontrol chat/thread Codex sebaiknya mengutamakan `/codex ...` daripada ACP kecuali pengguna secara eksplisit meminta ACP/acpx.
- OpenClaw menyembunyikan `runtime: "acp"` sampai ACP diaktifkan, peminta tidak berada dalam sandbox, dan plugin backend seperti `acpx` dimuat. `runtime: "acp"` mengharapkan id harness ACP eksternal, atau entri `agents.list[]` dengan `runtime.type="acp"`; gunakan runtime sub-agen default untuk agen konfigurasi OpenClaw normal dari `agents_list`.
</Accordion>
@ -113,28 +113,28 @@ obrolan peminta saat eksekusi selesai.
## Mode konteks
Sub-agen native mulai terisolasi kecuali pemanggil secara eksplisit meminta untuk mem-fork
Sub-agen native mulai terisolasi kecuali pemanggil secara eksplisit meminta untuk melakukan fork
transkrip saat ini.
| Mode | Kapan menggunakannya | Perilaku |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `isolated` | Riset baru, implementasi independen, pekerjaan alat lambat, atau apa pun yang dapat dijelaskan dalam teks tugas | Membuat transkrip anak yang bersih. Ini adalah default dan menjaga penggunaan token lebih rendah. |
| `fork` | Pekerjaan yang bergantung pada percakapan saat ini, hasil alat sebelumnya, atau instruksi bernuansa yang sudah ada dalam transkrip peminta | Mencabangkan transkrip peminta ke sesi anak sebelum anak dimulai. |
| `isolated` | Riset baru, implementasi independen, pekerjaan alat lambat, atau apa pun yang dapat dijelaskan dalam teks tugas | Membuat transkrip child yang bersih. Ini adalah default dan menjaga penggunaan token lebih rendah. |
| `fork` | Pekerjaan yang bergantung pada percakapan saat ini, hasil alat sebelumnya, atau instruksi bernuansa yang sudah ada dalam transkrip peminta | Mencabangkan transkrip peminta ke sesi child sebelum child dimulai. |
Gunakan `fork` seperlunya. Ini untuk delegasi yang peka konteks, bukan
pengganti untuk menulis prompt tugas yang jelas.
Gunakan `fork` secara hemat. Ini untuk delegasi yang peka konteks, bukan
pengganti penulisan prompt tugas yang jelas.
## Alat: `sessions_spawn`
Memulai eksekusi sub-agen dengan `deliver: false` pada lane global `subagent`,
lalu menjalankan langkah pengumuman dan memposting balasan pengumuman ke saluran
obrolan peminta.
Memulai eksekusi sub-agen dengan `deliver: false` pada lane `subagent` global,
lalu menjalankan langkah pengumuman dan memposting balasan pengumuman ke kanal
chat peminta.
Ketersediaan bergantung pada kebijakan alat efektif pemanggil. Profil `coding` dan
Ketersediaan bergantung pada kebijakan alat efektif milik pemanggil. Profil `coding` dan
`full` mengekspos `sessions_spawn` secara default. Profil `messaging`
tidak; tambahkan `tools.alsoAllow: ["sessions_spawn", "sessions_yield",
"subagents"]` atau gunakan `tools.profile: "coding"` untuk agen yang harus mendelegasikan
pekerjaan. Kebijakan izinkan/tolak per saluran/grup, provider, sandbox, dan per agen masih dapat
pekerjaan. Kebijakan allow/deny kanal/grup, penyedia, sandbox, dan per agen masih dapat
menghapus alat setelah tahap profil. Gunakan `/tools` dari sesi yang sama
untuk mengonfirmasi daftar alat efektif.
@ -142,7 +142,7 @@ untuk mengonfirmasi daftar alat efektif.
- **Model:** mewarisi pemanggil kecuali Anda menetapkan `agents.defaults.subagents.model` (atau `agents.list[].subagents.model` per agen); `sessions_spawn.model` eksplisit tetap menang.
- **Thinking:** mewarisi pemanggil kecuali Anda menetapkan `agents.defaults.subagents.thinking` (atau `agents.list[].subagents.thinking` per agen); `sessions_spawn.thinking` eksplisit tetap menang.
- **Timeout eksekusi:** jika `sessions_spawn.runTimeoutSeconds` dihilangkan, OpenClaw menggunakan `agents.defaults.subagents.runTimeoutSeconds` ketika disetel; jika tidak, fallback ke `0` (tanpa timeout).
- **Timeout eksekusi:** jika `sessions_spawn.runTimeoutSeconds` dihilangkan, OpenClaw menggunakan `agents.defaults.subagents.runTimeoutSeconds` saat ditetapkan; jika tidak, fallback ke `0` (tanpa timeout).
### Parameter alat
@ -150,10 +150,10 @@ untuk mengonfirmasi daftar alat efektif.
Deskripsi tugas untuk sub-agen.
</ParamField>
<ParamField path="label" type="string">
Label opsional yang mudah dibaca manusia.
Label opsional yang dapat dibaca manusia.
</ParamField>
<ParamField path="agentId" type="string">
Spawn di bawah id agen lain ketika diizinkan oleh `subagents.allowAgents`.
Spawn di bawah id agen lain saat diizinkan oleh `subagents.allowAgents`.
</ParamField>
<ParamField path="runtime" type='"subagent" | "acp"' default="subagent">
`acp` hanya untuk harness ACP eksternal (`claude`, `droid`, `gemini`, `opencode`, atau Codex ACP/acpx yang diminta secara eksplisit) dan untuk entri `agents.list[]` yang `runtime.type`-nya adalah `acp`.
@ -162,19 +162,19 @@ untuk mengonfirmasi daftar alat efektif.
Khusus ACP. Melanjutkan sesi harness ACP yang sudah ada ketika `runtime: "acp"`; diabaikan untuk spawn sub-agen native.
</ParamField>
<ParamField path="streamTo" type='"parent"'>
Khusus ACP. Mengalirkan output eksekusi ACP ke sesi induk ketika `runtime: "acp"`; hilangkan untuk spawn sub-agen native.
Khusus ACP. Melakukan stream output eksekusi ACP ke sesi parent ketika `runtime: "acp"`; hilangkan untuk spawn sub-agen native.
</ParamField>
<ParamField path="model" type="string">
Override model sub-agen. Nilai tidak valid dilewati dan sub-agen berjalan pada model default dengan peringatan dalam hasil alat.
Override model sub-agen. Nilai yang tidak valid dilewati dan sub-agen berjalan pada model default dengan peringatan dalam hasil alat.
</ParamField>
<ParamField path="thinking" type="string">
Override tingkat thinking untuk eksekusi sub-agen.
</ParamField>
<ParamField path="runTimeoutSeconds" type="number">
Default ke `agents.defaults.subagents.runTimeoutSeconds` ketika disetel, jika tidak `0`. Ketika disetel, eksekusi sub-agen dibatalkan setelah N detik.
Default ke `agents.defaults.subagents.runTimeoutSeconds` saat ditetapkan, jika tidak `0`. Saat ditetapkan, eksekusi sub-agen dibatalkan setelah N detik.
</ParamField>
<ParamField path="thread" type="boolean" default="false">
Ketika `true`, meminta binding thread saluran untuk sesi sub-agen ini.
Ketika `true`, meminta pengikatan thread kanal untuk sesi sub-agen ini.
</ParamField>
<ParamField path="mode" type='"run" | "session"' default="run">
Jika `thread: true` dan `mode` dihilangkan, default menjadi `session`. `mode: "session"` memerlukan `thread: true`.
@ -183,28 +183,28 @@ untuk mengonfirmasi daftar alat efektif.
`"delete"` langsung mengarsipkan setelah pengumuman (tetap menyimpan transkrip melalui rename).
</ParamField>
<ParamField path="sandbox" type='"inherit" | "require"' default="inherit">
`require` menolak spawn kecuali runtime anak target berada dalam sandbox.
`require` menolak spawn kecuali runtime child target berada dalam sandbox.
</ParamField>
<ParamField path="context" type='"isolated" | "fork"' default="isolated">
`fork` mencabangkan transkrip peminta saat ini ke sesi anak. Hanya sub-agen native. Gunakan `fork` hanya ketika anak membutuhkan transkrip saat ini.
`fork` mencabangkan transkrip saat ini milik peminta ke sesi child. Hanya sub-agen native. Gunakan `fork` hanya ketika child membutuhkan transkrip saat ini.
</ParamField>
<Warning>
`sessions_spawn` **tidak** menerima parameter pengiriman saluran (`target`,
`sessions_spawn` **tidak** menerima parameter pengiriman kanal (`target`,
`channel`, `to`, `threadId`, `replyTo`, `transport`). Untuk pengiriman, gunakan
`message`/`sessions_send` dari eksekusi yang dibuat.
`message`/`sessions_send` dari eksekusi yang dimunculkan.
</Warning>
## Sesi terikat thread
Ketika binding thread diaktifkan untuk suatu saluran, sub-agen dapat tetap terikat
ke sebuah thread sehingga pesan pengguna lanjutan di thread tersebut tetap dirutekan ke
Ketika pengikatan thread diaktifkan untuk sebuah kanal, sub-agen dapat tetap terikat
ke thread sehingga pesan pengguna lanjutan di thread tersebut tetap dirutekan ke
sesi sub-agen yang sama.
### Saluran yang mendukung thread
### Kanal pendukung thread
**Discord** saat ini adalah satu-satunya saluran yang didukung. Ia mendukung
sesi sub-agen terikat thread persisten (`sessions_spawn` dengan
**Discord** saat ini adalah satu-satunya kanal yang didukung. Kanal ini mendukung
sesi sub-agen persisten yang terikat thread (`sessions_spawn` dengan
`thread: true`), kontrol thread manual (`/focus`, `/unfocus`, `/agents`,
`/session idle`, `/session max-age`), dan kunci adapter
`channels.discord.threadBindings.enabled`,
@ -216,37 +216,37 @@ sesi sub-agen terikat thread persisten (`sessions_spawn` dengan
<Steps>
<Step title="Spawn">
`sessions_spawn` dengan `thread: true` (dan opsional `mode: "session"`).
`sessions_spawn` dengan `thread: true` (dan secara opsional `mode: "session"`).
</Step>
<Step title="Bind">
OpenClaw membuat atau mengikat thread ke target sesi tersebut di saluran aktif.
<Step title="Ikat">
OpenClaw membuat atau mengikat thread ke target sesi tersebut di kanal aktif.
</Step>
<Step title="Rutekan tindak lanjut">
Balasan dan pesan lanjutan di thread tersebut dirutekan ke sesi terikat.
</Step>
<Step title="Periksa timeout">
Gunakan `/session idle` untuk memeriksa/memperbarui auto-unfocus karena tidak aktif dan
Gunakan `/session idle` untuk memeriksa/memperbarui auto-unfocus ketidakaktifan dan
`/session max-age` untuk mengontrol batas keras.
</Step>
<Step title="Lepaskan">
<Step title="Lepas">
Gunakan `/unfocus` untuk melepas secara manual.
</Step>
</Steps>
### Kontrol manual
| Perintah | Efek |
| ----------------- | --------------------------------------------------------------------- |
| `/focus <target>` | Ikat thread saat ini (atau buat yang baru) ke target sub-agen/sesi |
| `/unfocus` | Hapus ikatan untuk thread terikat saat ini |
| `/agents` | Cantumkan run aktif dan status ikatan (`thread:<id>` atau `unbound`) |
| `/session idle` | Periksa/perbarui auto-unfocus saat idle (hanya thread terikat fokus) |
| `/session max-age` | Periksa/perbarui batas keras (hanya thread terikat fokus) |
| Perintah | Efek |
| ------------------ | --------------------------------------------------------------------- |
| `/focus <target>` | Ikat utas saat ini (atau buat satu) ke target sub-agen/sesi |
| `/unfocus` | Hapus pengikatan untuk utas terikat saat ini |
| `/agents` | Cantumkan run aktif dan status pengikatan (`thread:<id>` atau `unbound`) |
| `/session idle` | Periksa/perbarui auto-unfocus saat idle (hanya utas terikat yang difokuskan) |
| `/session max-age` | Periksa/perbarui batas keras (hanya utas terikat yang difokuskan) |
### Sakelar konfigurasi
- **Default global:** `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`.
- **Override channel dan kunci spawn auto-bind** bersifat khusus adapter. Lihat [Channel pendukung thread](#thread-supporting-channels) di atas.
- **Override channel dan kunci spawn auto-bind** bersifat spesifik adapter. Lihat [Channel pendukung utas](#thread-supporting-channels) di atas.
Lihat [Referensi konfigurasi](/id/gateway/configuration-reference) dan
[Perintah slash](/id/tools/slash-commands) untuk detail adapter saat ini.
@ -254,10 +254,10 @@ Lihat [Referensi konfigurasi](/id/gateway/configuration-reference) dan
### Daftar izin
<ParamField path="agents.list[].subagents.allowAgents" type="string[]">
Daftar id agen yang dapat ditargetkan melalui `agentId` eksplisit (`["*"]` mengizinkan apa pun). Default: hanya agen peminta. Jika Anda menetapkan daftar dan tetap ingin peminta men-spawn dirinya sendiri dengan `agentId`, sertakan id peminta dalam daftar.
Daftar id agen yang dapat ditargetkan melalui `agentId` eksplisit (`["*"]` mengizinkan apa pun). Default: hanya agen peminta. Jika Anda menetapkan daftar dan masih ingin peminta melakukan spawn terhadap dirinya sendiri dengan `agentId`, sertakan id peminta dalam daftar.
</ParamField>
<ParamField path="agents.defaults.subagents.allowAgents" type="string[]">
Daftar izin agen target default yang digunakan saat agen peminta tidak menetapkan `subagents.allowAgents` miliknya sendiri.
Daftar izin agen target default yang digunakan ketika agen peminta tidak menetapkan `subagents.allowAgents` miliknya sendiri.
</ParamField>
<ParamField path="agents.defaults.subagents.requireAgentId" type="boolean" default="false">
Blokir panggilan `sessions_spawn` yang menghilangkan `agentId` (memaksa pemilihan profil eksplisit). Override per agen: `agents.list[].subagents.requireAgentId`.
@ -270,24 +270,24 @@ yang akan berjalan tanpa sandbox.
Gunakan `agents_list` untuk melihat id agen mana yang saat ini diizinkan untuk
`sessions_spawn`. Respons menyertakan model efektif setiap agen yang tercantum
dan metadata runtime tertanam agar pemanggil dapat membedakan PI, server aplikasi Codex,
dan runtime native terkonfigurasi lainnya.
dan metadata runtime tertanam sehingga pemanggil dapat membedakan PI, Codex
app-server, dan runtime native lain yang dikonfigurasi.
### Arsip otomatis
- Sesi sub-agen diarsipkan secara otomatis setelah `agents.defaults.subagents.archiveAfterMinutes` (default `60`).
- Arsip menggunakan `sessions.delete` dan mengganti nama transkrip menjadi `*.deleted.<timestamp>` (folder yang sama).
- `cleanup: "delete"` langsung mengarsipkan setelah announce (tetap menyimpan transkrip melalui penggantian nama).
- Arsip otomatis bersifat best-effort; timer tertunda hilang jika gateway dimulai ulang.
- `cleanup: "delete"` mengarsipkan segera setelah announce (transkrip tetap disimpan melalui penggantian nama).
- Arsip otomatis bersifat upaya terbaik; timer tertunda hilang jika Gateway dimulai ulang.
- `runTimeoutSeconds` **tidak** mengarsipkan otomatis; itu hanya menghentikan run. Sesi tetap ada sampai arsip otomatis.
- Arsip otomatis berlaku sama untuk sesi kedalaman-1 dan kedalaman-2.
- Pembersihan browser terpisah dari pembersihan arsip: tab/proses browser yang dilacak ditutup secara best-effort saat run selesai, meskipun catatan transkrip/sesi tetap disimpan.
- Arsip otomatis berlaku sama untuk sesi depth-1 dan depth-2.
- Pembersihan browser terpisah dari pembersihan arsip: tab/proses browser yang dilacak ditutup dengan upaya terbaik ketika run selesai, meskipun catatan transkrip/sesi disimpan.
## Sub-agen bersarang
## Sub-agen bertingkat
Secara default, sub-agen tidak dapat men-spawn sub-agennya sendiri
Secara default, sub-agen tidak dapat melakukan spawn terhadap sub-agennya sendiri
(`maxSpawnDepth: 1`). Tetapkan `maxSpawnDepth: 2` untuk mengaktifkan satu tingkat
penyarangan — **pola orkestrator**: utama → sub-agen orkestrator →
nesting — **pola orkestrator**: utama → sub-agen orkestrator →
sub-sub-agen pekerja.
```json5
@ -305,67 +305,66 @@ sub-sub-agen pekerja.
}
```
### Tingkat kedalaman
### Tingkat depth
| Kedalaman | Bentuk kunci sesi | Peran | Dapat men-spawn? |
| --------- | -------------------------------------------- | ------------------------------------------------- | ---------------------------- |
| 0 | `agent:<id>:main` | Agen utama | Selalu |
| 1 | `agent:<id>:subagent:<uuid>` | Sub-agen (orkestrator saat kedalaman 2 diizinkan) | Hanya jika `maxSpawnDepth >= 2` |
| 2 | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | Sub-sub-agen (pekerja leaf) | Tidak pernah |
| Depth | Bentuk kunci sesi | Peran | Dapat spawn? |
| ----- | -------------------------------------------- | --------------------------------------------- | ---------------------------- |
| 0 | `agent:<id>:main` | Agen utama | Selalu |
| 1 | `agent:<id>:subagent:<uuid>` | Sub-agen (orkestrator ketika depth 2 diizinkan) | Hanya jika `maxSpawnDepth >= 2` |
| 2 | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | Sub-sub-agen (pekerja daun) | Tidak pernah |
### Rantai announce
Hasil mengalir kembali ke atas rantai:
1. Pekerja kedalaman-2 selesai → mengumumkan ke induknya (orkestrator kedalaman-1).
2. Orkestrator kedalaman-1 menerima announce, menyintesis hasil, selesai → mengumumkan ke utama.
1. Pekerja depth-2 selesai → mengirim announce ke induknya (orkestrator depth-1).
2. Orkestrator depth-1 menerima announce, menyintesis hasil, selesai → mengirim announce ke utama.
3. Agen utama menerima announce dan mengirimkannya kepada pengguna.
Setiap tingkat hanya melihat announce dari anak langsungnya.
<Note>
**Panduan operasional:** mulai pekerjaan anak sekali dan tunggu event penyelesaian
alih-alih membuat loop polling di sekitar `sessions_list`,
**Panduan operasional:** mulai pekerjaan anak satu kali dan tunggu event penyelesaian
alih-alih membangun loop polling di sekitar `sessions_list`,
`sessions_history`, `/subagents list`, atau perintah sleep `exec`.
`sessions_list` dan `/subagents list` menjaga hubungan sesi anak
`sessions_list` dan `/subagents list` menjaga hubungan sesi-anak
tetap berfokus pada pekerjaan live — anak live tetap terlampir, anak yang berakhir tetap
terlihat selama jendela terbaru yang singkat, dan tautan anak lama yang hanya ada di store
terlihat untuk jendela terbaru yang singkat, dan tautan anak hanya-store yang basi
diabaikan setelah jendela kesegarannya. Ini mencegah metadata `spawnedBy` /
`parentSessionKey` lama membangkitkan anak hantu setelah
`parentSessionKey` lama menghidupkan kembali anak bayangan setelah
restart. Jika event penyelesaian anak tiba setelah Anda sudah mengirim
jawaban final, tindak lanjut yang benar adalah token senyap persis
jawaban akhir, tindak lanjut yang benar adalah token senyap persis
`NO_REPLY` / `no_reply`.
</Note>
### Kebijakan alat berdasarkan kedalaman
### Kebijakan alat menurut depth
- Peran dan cakupan kontrol ditulis ke metadata sesi saat spawn. Itu mencegah kunci sesi datar atau yang dipulihkan mendapatkan kembali hak istimewa orkestrator secara tidak sengaja.
- **Kedalaman 1 (orkestrator, saat `maxSpawnDepth >= 2`):** mendapatkan `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history` agar dapat mengelola anaknya. Alat sesi/sistem lainnya tetap ditolak.
- **Kedalaman 1 (leaf, saat `maxSpawnDepth == 1`):** tidak ada alat sesi (perilaku default saat ini).
- **Kedalaman 2 (pekerja leaf):** tidak ada alat sesi — `sessions_spawn` selalu ditolak pada kedalaman 2. Tidak dapat men-spawn anak lebih lanjut.
- Peran dan cakupan kontrol ditulis ke metadata sesi pada waktu spawn. Itu mencegah kunci sesi datar atau dipulihkan mendapatkan kembali hak istimewa orkestrator secara tidak sengaja.
- **Depth 1 (orkestrator, ketika `maxSpawnDepth >= 2`):** mendapat `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history` agar dapat mengelola anaknya. Alat sesi/sistem lain tetap ditolak.
- **Depth 1 (daun, ketika `maxSpawnDepth == 1`):** tidak ada alat sesi (perilaku default saat ini).
- **Depth 2 (pekerja daun):** tidak ada alat sesi — `sessions_spawn` selalu ditolak pada depth 2. Tidak dapat melakukan spawn anak lebih lanjut.
### Batas spawn per agen
Setiap sesi agen (pada kedalaman apa pun) dapat memiliki paling banyak `maxChildrenPerAgent`
(default `5`) anak aktif sekaligus. Ini mencegah fan-out tak terkendali
Setiap sesi agen (pada depth apa pun) dapat memiliki paling banyak `maxChildrenPerAgent`
(default `5`) anak aktif pada satu waktu. Ini mencegah fan-out tak terkendali
dari satu orkestrator.
### Henti kaskade
### Penghentian berantai
Menghentikan orkestrator kedalaman-1 secara otomatis menghentikan semua anak kedalaman-2
miliknya:
Menghentikan orkestrator depth-1 secara otomatis menghentikan semua anak depth-2-nya:
- `/stop` di chat utama menghentikan semua agen kedalaman-1 dan melakukan kaskade ke anak kedalaman-2 mereka.
- `/subagents kill <id>` menghentikan sub-agen tertentu dan melakukan kaskade ke anaknya.
- `/subagents kill all` menghentikan semua sub-agen untuk peminta dan melakukan kaskade.
- `/stop` di chat utama menghentikan semua agen depth-1 dan berantai ke anak depth-2 mereka.
- `/subagents kill <id>` menghentikan sub-agen tertentu dan berantai ke anaknya.
- `/subagents kill all` menghentikan semua sub-agen untuk peminta dan berantai.
## Autentikasi
Auth sub-agen diselesaikan berdasarkan **id agen**, bukan berdasarkan tipe sesi:
Auth sub-agen diselesaikan berdasarkan **id agen**, bukan berdasarkan jenis sesi:
- Kunci sesi sub-agen adalah `agent:<agentId>:subagent:<uuid>`.
- Store auth dimuat dari `agentDir` agen tersebut.
- Profil auth agen utama digabungkan sebagai **fallback**; profil agen menimpa profil utama jika ada konflik.
- Profil auth agen utama digabungkan sebagai **fallback**; profil agen menimpa profil utama saat terjadi konflik.
Penggabungan bersifat aditif, sehingga profil utama selalu tersedia sebagai
fallback. Auth yang sepenuhnya terisolasi per agen belum didukung.
@ -378,22 +377,22 @@ Sub-agen melapor kembali melalui langkah announce:
- Jika sub-agen membalas persis `ANNOUNCE_SKIP`, tidak ada yang diposting.
- Jika teks asisten terbaru adalah token senyap persis `NO_REPLY` / `no_reply`, output announce ditekan meskipun progres terlihat sebelumnya ada.
Pengiriman bergantung pada kedalaman peminta:
Pengiriman bergantung pada depth peminta:
- Sesi peminta tingkat atas menggunakan panggilan `agent` tindak lanjut dengan pengiriman eksternal (`deliver=true`).
- Sesi subagen peminta bersarang menerima injeksi tindak lanjut internal (`deliver=false`) agar orkestrator dapat menyintesis hasil anak di dalam sesi.
- Jika sesi subagen peminta bersarang sudah hilang, OpenClaw fallback ke peminta sesi tersebut jika tersedia.
- Sesi subagen peminta bertingkat menerima injeksi tindak lanjut internal (`deliver=false`) sehingga orkestrator dapat menyintesis hasil anak di dalam sesi.
- Jika sesi subagen peminta bertingkat hilang, OpenClaw fallback ke peminta sesi tersebut bila tersedia.
Untuk sesi peminta tingkat atas, pengiriman langsung mode penyelesaian terlebih dahulu
menyelesaikan rute percakapan/thread terikat dan override hook apa pun, lalu mengisi
Untuk sesi peminta tingkat atas, pengiriman langsung mode penyelesaian pertama-tama
menyelesaikan rute percakapan/utas terikat apa pun dan override hook, lalu mengisi
field target-channel yang hilang dari rute tersimpan sesi peminta.
Itu menjaga penyelesaian tetap berada di chat/topik yang benar meskipun asal penyelesaian
Itu menjaga penyelesaian tetap di chat/topik yang tepat meskipun asal penyelesaian
hanya mengidentifikasi channel.
Agregasi penyelesaian anak dicakup ke run peminta saat ini ketika
membangun temuan penyelesaian bersarang, mencegah output anak dari run sebelumnya yang usang
membangun temuan penyelesaian bertingkat, mencegah output anak dari prior-run basi
bocor ke announce saat ini. Balasan announce mempertahankan
perutean thread/topik saat tersedia pada adapter channel.
routing utas/topik bila tersedia pada adapter channel.
### Konteks announce
@ -401,47 +400,47 @@ Konteks announce dinormalisasi menjadi blok event internal yang stabil:
| Field | Sumber |
| -------------- | ------------------------------------------------------------------------------------------------------------- |
| Source | `subagent` atau `cron` |
| Session ids | Kunci/id sesi anak |
| Type | Tipe announce + label tugas |
| Sumber | `subagent` atau `cron` |
| Id sesi | Kunci/id sesi anak |
| Jenis | Jenis announce + label tugas |
| Status | Diturunkan dari hasil runtime (`success`, `error`, `timeout`, atau `unknown`) — **bukan** disimpulkan dari teks model |
| Result content | Teks asisten terlihat terbaru, jika tidak ada maka teks tool/toolResult terbaru yang disanitasi |
| Follow-up | Instruksi yang menjelaskan kapan harus membalas vs tetap senyap |
| Konten hasil | Teks asisten terlihat terbaru, jika tidak ada teks alat/toolResult terbaru yang disanitasi |
| Tindak lanjut | Instruksi yang menjelaskan kapan membalas vs tetap senyap |
Run terminal yang gagal melaporkan status kegagalan tanpa memutar ulang teks
balasan yang ditangkap. Saat timeout, jika anak hanya berhasil menjalankan panggilan alat,
announce dapat meringkas riwayat itu menjadi ringkasan progres parsial singkat alih-alih
memutar ulang output alat mentah.
Run terminal yang gagal melaporkan status kegagalan tanpa memutar ulang
teks balasan yang ditangkap. Saat timeout, jika anak hanya sempat melalui panggilan alat,
announce dapat meruntuhkan riwayat tersebut menjadi ringkasan progres parsial singkat
alih-alih memutar ulang output alat mentah.
### Baris statistik
### Baris stats
Payload announce menyertakan baris statistik di akhir (bahkan saat dibungkus):
Payload announce menyertakan baris stats di akhir (bahkan saat dibungkus):
- Runtime (mis. `runtime 5m12s`).
- Penggunaan token (input/output/total).
- Estimasi biaya saat harga model dikonfigurasi (`models.providers.*.models[].cost`).
- `sessionKey`, `sessionId`, dan path transkrip agar agen utama dapat mengambil riwayat melalui `sessions_history` atau memeriksa file di disk.
- Perkiraan biaya ketika harga model dikonfigurasi (`models.providers.*.models[].cost`).
- `sessionKey`, `sessionId`, dan jalur transkrip sehingga agen utama dapat mengambil riwayat melalui `sessions_history` atau memeriksa file di disk.
Metadata internal hanya dimaksudkan untuk orkestrasi; balasan yang menghadap pengguna
Metadata internal ditujukan hanya untuk orkestrasi; balasan yang menghadap pengguna
harus ditulis ulang dengan suara asisten normal.
### Mengapa lebih memilih `sessions_history`
`sessions_history` adalah jalur orkestrasi yang lebih aman:
- Recall asisten dinormalisasi terlebih dahulu: tag thinking dihapus; scaffolding `<relevant-memories>` / `<relevant_memories>` dihapus; blok payload XML panggilan alat teks biasa (`<tool_call>`, `<function_call>`, `<tool_calls>`, `<function_calls>`) dihapus, termasuk payload terpotong yang tidak pernah tertutup bersih; scaffolding panggilan/hasil alat yang diturunkan dan penanda konteks historis dihapus; token kontrol model yang bocor (`<|assistant|>`, ASCII lain `<|...|>`, lebar penuh `<｜...｜>`) dihapus; XML panggilan alat MiniMax yang cacat dihapus.
- Teks mirip kredensial/token disunting.
- Ingatan asisten dinormalisasi terlebih dahulu: tag thinking dihapus; kerangka `<relevant-memories>` / `<relevant_memories>` dihapus; blok payload XML panggilan alat teks biasa (`<tool_call>`, `<function_call>`, `<tool_calls>`, `<function_calls>`) dihapus, termasuk payload terpotong yang tidak pernah tertutup bersih; kerangka panggilan/hasil alat yang diturunkan dan marker konteks historis dihapus; token kontrol model yang bocor (`<|assistant|>`, ASCII `<|...|>` lain, full-width `<｜...｜>`) dihapus; XML panggilan alat MiniMax yang malformed dihapus.
- Teks yang menyerupai kredensial/token direduksi.
- Blok panjang dapat dipotong.
- Riwayat yang sangat besar dapat menghapus baris yang lebih lama atau mengganti baris yang terlalu besar dengan `[sessions_history omitted: message too large]`.
- Pemeriksaan transkrip mentah di disk adalah fallback saat Anda membutuhkan transkrip lengkap byte demi byte.
- Riwayat yang sangat besar dapat membuang baris lama atau mengganti baris berukuran terlalu besar dengan `[sessions_history omitted: message too large]`.
- Pemeriksaan transkrip mentah di disk adalah fallback ketika Anda membutuhkan transkrip penuh byte-for-byte.
## Kebijakan alat
Sub-agen menggunakan profil dan pipeline kebijakan alat yang sama seperti induk atau
Sub-agen menggunakan pipeline profil dan kebijakan alat yang sama seperti induk atau
agen target terlebih dahulu. Setelah itu, OpenClaw menerapkan lapisan pembatasan
sub-agen.
Tanpa `tools.profile` yang restriktif, sub-agen mendapatkan **semua alat kecuali
Tanpa `tools.profile` yang restriktif, sub-agen mendapat **semua alat kecuali
alat sesi** dan alat sistem:
- `sessions_list`
@ -449,12 +448,12 @@ alat sesi** dan alat sistem:
- `sessions_send`
- `sessions_spawn`
`sessions_history` tetap berupa tampilan recall terbatas dan tersanitasi di sini juga — itu
`sessions_history` tetap menjadi tampilan recall yang terbatas dan disanitasi di sini juga — itu
bukan dump transkrip mentah.
Saat `maxSpawnDepth >= 2`, sub-agen orkestrator kedalaman-1 juga
Ketika `maxSpawnDepth >= 2`, sub-agen orkestrator depth-1 juga
menerima `sessions_spawn`, `subagents`, `sessions_list`, dan
`sessions_history` agar dapat mengelola anaknya.
`sessions_history` sehingga mereka dapat mengelola anaknya.
### Override melalui konfigurasi
@ -480,7 +479,12 @@ menerima `sessions_spawn`, `subagents`, `sessions_list`, dan
}
```
`tools.subagents.tools.allow` adalah filter final khusus allow. Filter ini dapat mempersempit kumpulan tool yang sudah diselesaikan, tetapi tidak dapat **menambahkan kembali** tool yang dihapus oleh `tools.profile`. Misalnya, `tools.profile: "coding"` menyertakan `web_search`/`web_fetch` tetapi tidak menyertakan tool `browser`. Agar sub-agen profil coding dapat menggunakan otomatisasi browser, tambahkan browser pada tahap profil:
`tools.subagents.tools.allow` adalah filter akhir hanya-izinkan. Filter ini dapat mempersempit
kumpulan alat yang sudah diresolusikan, tetapi tidak dapat **menambahkan kembali** alat yang dihapus
oleh `tools.profile`. Misalnya, `tools.profile: "coding"` menyertakan
`web_search`/`web_fetch` tetapi bukan alat `browser`. Untuk mengizinkan
sub-agen profil coding menggunakan otomasi browser, tambahkan browser pada tahap
profil:
```json5
{
@ -491,42 +495,64 @@ menerima `sessions_spawn`, `subagents`, `sessions_list`, dan
}
```
Gunakan `agents.list[].tools.alsoAllow: ["browser"]` per agen ketika hanya satu agen yang perlu mendapatkan otomatisasi browser.
Gunakan `agents.list[].tools.alsoAllow: ["browser"]` per agen ketika hanya satu
agen yang harus mendapatkan otomasi browser.
## Konkurensi
Sub-agen menggunakan jalur antrean khusus dalam proses:
Sub-agen menggunakan jalur antrean dalam proses khusus:
- **Nama jalur:** `subagent`
- **Konkurensi:** `agents.defaults.subagents.maxConcurrent` (default `8`)
## Liveness dan pemulihan
## Keaktifan dan pemulihan
OpenClaw tidak memperlakukan ketiadaan `endedAt` sebagai bukti permanen bahwa sebuah sub-agen masih hidup. Run yang belum berakhir dan lebih lama dari jendela run basi berhenti dihitung sebagai aktif/tertunda di `/subagents list`, ringkasan status, gating penyelesaian turunan, dan pemeriksaan konkurensi per sesi.
OpenClaw tidak memperlakukan ketiadaan `endedAt` sebagai bukti permanen bahwa
sub-agen masih hidup. Proses yang belum berakhir dan lebih lama dari jendela proses usang
berhenti dihitung sebagai aktif/tertunda di `/subagents list`, ringkasan status,
gating penyelesaian turunan, dan pemeriksaan konkurensi per sesi.
Setelah Gateway dimulai ulang, run pulihan basi yang belum berakhir dipangkas kecuali sesi anaknya ditandai `abortedLastRun: true`. Sesi anak yang dibatalkan oleh restart tersebut tetap dapat dipulihkan melalui alur pemulihan yatim sub-agen, yang mengirim pesan resume sintetis sebelum menghapus penanda dibatalkan.
Setelah Gateway dimulai ulang, proses pulihan usang yang belum berakhir akan dipangkas kecuali
sesi anaknya ditandai `abortedLastRun: true`. Sesi anak yang dibatalkan karena
restart tersebut tetap dapat dipulihkan melalui alur pemulihan orphan sub-agen,
yang mengirim pesan resume sintetis sebelum menghapus penanda dibatalkan.
Pemulihan restart otomatis dibatasi per sesi anak. Jika anak sub-agen yang sama
diterima untuk pemulihan orphan berulang kali di dalam jendela re-wedge cepat,
OpenClaw menyimpan tombstone pemulihan pada sesi tersebut dan berhenti melanjutkannya
secara otomatis pada restart berikutnya. Jalankan
`openclaw tasks maintenance --apply` untuk merekonsiliasi catatan tugas, atau
`openclaw doctor --fix` untuk menghapus flag pemulihan dibatalkan yang usang pada
sesi yang ditombstone.
<Note>
Jika spawn sub-agen gagal dengan Gateway `PAIRING_REQUIRED` / `scope-upgrade`, periksa pemanggil RPC sebelum mengedit status pairing. Koordinasi internal `sessions_spawn` harus terhubung sebagai `client.id: "gateway-client"` dengan `client.mode: "backend"` melalui autentikasi shared-token/password loopback langsung; jalur itu tidak bergantung pada baseline cakupan perangkat yang dipairing milik CLI. Pemanggil jarak jauh, `deviceIdentity` eksplisit, jalur token perangkat eksplisit, serta klien browser/node tetap memerlukan persetujuan perangkat normal untuk peningkatan cakupan.
Jika spawn sub-agen gagal dengan Gateway `PAIRING_REQUIRED` /
`scope-upgrade`, periksa pemanggil RPC sebelum mengedit status pairing.
Koordinasi internal `sessions_spawn` harus terhubung sebagai
`client.id: "gateway-client"` dengan `client.mode: "backend"` melalui auth
local loopback token bersama/kata sandi langsung; jalur tersebut tidak bergantung pada
baseline cakupan perangkat terpasangkan CLI. Pemanggil jarak jauh, `deviceIdentity`
eksplisit, jalur token perangkat eksplisit, serta klien browser/node tetap
memerlukan persetujuan perangkat normal untuk peningkatan cakupan.
</Note>
## Menghentikan
- Mengirim `/stop` di chat peminta membatalkan sesi peminta dan menghentikan run sub-agen aktif yang di-spawn darinya, lalu mengalir ke anak bertingkat.
- `/subagents kill <id>` menghentikan sub-agen tertentu dan mengalir ke anak-anaknya.
- Mengirim `/stop` di chat peminta membatalkan sesi peminta dan menghentikan semua proses sub-agen aktif yang dibuat darinya, berantai ke anak bertingkat.
- `/subagents kill <id>` menghentikan sub-agen tertentu dan berantai ke anak-anaknya.
## Batasan
- Pengumuman sub-agen bersifat **upaya terbaik**. Jika gateway dimulai ulang, pekerjaan "announce back" yang tertunda akan hilang.
- Sub-agen tetap berbagi sumber daya proses gateway yang sama; perlakukan `maxConcurrent` sebagai katup pengaman.
- `sessions_spawn` selalu non-blocking: ini langsung mengembalikan `{ status: "accepted", runId, childSessionKey }`.
- Pengumuman sub-agen bersifat **upaya terbaik**. Jika Gateway dimulai ulang, pekerjaan "announce back" yang tertunda akan hilang.
- Sub-agen masih berbagi sumber daya proses Gateway yang sama; perlakukan `maxConcurrent` sebagai katup pengaman.
- `sessions_spawn` selalu non-blocking: perintah ini langsung mengembalikan `{ status: "accepted", runId, childSessionKey }`.
- Konteks sub-agen hanya menyuntikkan `AGENTS.md` + `TOOLS.md` (tanpa `SOUL.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, atau `BOOTSTRAP.md`).
- Kedalaman bersarang maksimum adalah 5 (rentang `maxSpawnDepth`: 1–5). Kedalaman 2 direkomendasikan untuk sebagian besar kasus penggunaan.
- Kedalaman nesting maksimum adalah 5 (rentang `maxSpawnDepth`: 1–5). Kedalaman 2 direkomendasikan untuk sebagian besar kasus penggunaan.
- `maxChildrenPerAgent` membatasi anak aktif per sesi (default `5`, rentang `1–20`).
## Terkait
- [Agen ACP](/id/tools/acp-agents)
- [Pengiriman agen](/id/tools/agent-send)
- [Kirim agen](/id/tools/agent-send)
- [Tugas latar belakang](/id/automation/tasks)
- [Tool sandbox multi-agen](/id/tools/multi-agent-sandbox-tools)
- [Alat sandbox multi-agen](/id/tools/multi-agent-sandbox-tools)

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

@ -1,100 +1,101 @@
---
read_when:
- Menyesuaikan penguraian atau nilai bawaan direktif thinking, fast-mode, atau verbose
- Menyesuaikan penguraian atau default untuk 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-04-30T10:17:21Z"
generated_at: "2026-04-30T16:31:09Z"
model: gpt-5.5
provider: openai
source_hash: e9fabead8d2f58fc5bce3bf8b281ad9d52da2cd02ba2777bc1597359537b7705
source_hash: f9adf065e46cb64e4c2149b95ecd69ed887a17e2eff5a5569894defa3e7217b7
source_path: tools/thinking.md
workflow: 16
---
## Apa fungsinya
- Direktif inline dalam isi pesan masuk apa pun: `/t <level>`, `/think:<level>`, atau `/thinking <level>`.
- Direktif inline dalam body masuk apa pun: `/t <level>`, `/think:<level>`, atau `/thinking <level>`.
- Level (alias): `off | minimal | low | medium | high | xhigh | adaptive | max`
- minimal → “think”
- low → “think hard”
- medium → “think harder”
- high → “ultrathink” (anggaran maksimum)
- xhigh → “ultrathink+” (model GPT-5.2+ dan Codex, ditambah upaya Anthropic Claude Opus 4.7)
- xhigh → “ultrathink+” (model GPT-5.2+ dan Codex, ditambah effort 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 maksimum penyedia (Anthropic Claude Opus 4.7; Ollama memetakan ini ke upaya `think` native tertingginya)
- max → penalaran maksimum penyedia (Anthropic Claude Opus 4.7; Ollama memetakannya ke effort `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 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 tidak didukung yang tersimpan sebelumnya 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 secara default menggunakan `adaptive` ketika tidak ada level pemikiran eksplisit yang ditetapkan.
- Anthropic Claude Opus 4.7 tidak secara default menggunakan 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 direktif pemikiran 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 dan dimiliki penyedia.
- Model Ollama yang mendukung pemikiran 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 kompatibel OpenAI kustom dapat ikut menggunakan `/think xhigh` dengan mengatur `models.providers.<provider>.models[].compat.supportedReasoningEfforts` agar menyertakan `"xhigh"`. Ini menggunakan metadata compat 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 terkonfigurasi yang usang melewati injeksi penalaran proxy karena rute yang sudah dipensiunkan itu dapat mengembalikan teks jawaban akhir melalui bidang penalaran.
- Google Gemini memetakan `/think adaptive` ke pemikiran dinamis milik 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 kompatibel Anthropic secara default menggunakan `thinking: { type: "disabled" }` kecuali Anda secara eksplisit menetapkan pemikiran 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 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" }`. Ketika 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 kumpulan level persis untuk model yang dipilih, termasuk label seperti `on` biner.
- `adaptive`, `xhigh`, dan `max` hanya diiklankan untuk profil penyedia/model yang mendukungnya. Direktif yang diketik untuk level yang tidak didukung ditolak dengan opsi valid model tersebut.
- Level tidak didukung tersimpan yang ada 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 secara default menggunakan `adaptive` ketika tidak ada level berpikir eksplisit yang ditetapkan.
- Anthropic Claude Opus 4.7 tidak secara default menggunakan pemikiran adaptif. Default effort API-nya tetap dimiliki penyedia kecuali Anda menetapkan level berpikir secara eksplisit.
- Anthropic Claude Opus 4.7 memetakan `/think xhigh` ke pemikiran adaptif ditambah `output_config.effort: "xhigh"`, karena `/think` adalah direktif berpikir dan `xhigh` adalah pengaturan effort Opus 4.7.
- Anthropic Claude Opus 4.7 juga mengekspos `/think max`; ini dipetakan ke jalur effort maksimum milik penyedia yang sama.
- Model DeepSeek V4 mengekspos `/think xhigh|max`; keduanya dipetakan ke DeepSeek `reasoning_effort: "max"` sementara level non-`off` yang lebih rendah dipetakan ke `high`.
- Model Ollama yang mendukung berpikir mengekspos `/think low|medium|high|max`; `max` dipetakan ke native `think: "high"` karena API native Ollama menerima string effort `low`, `medium`, dan `high`.
- Model GPT OpenAI memetakan `/think` melalui dukungan effort 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 mengatur `models.providers.<provider>.models[].compat.supportedReasoningEfforts` agar menyertakan `"xhigh"`. Ini menggunakan metadata compat yang sama yang memetakan payload effort 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 secara default menggunakan `thinking: { type: "disabled" }` kecuali Anda menetapkan berpikir secara eksplisit dalam parameter model atau parameter permintaan. Ini menghindari delta `reasoning_content` yang bocor dari format stream Anthropic non-native 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" }`. Saat berpikir diaktifkan, Moonshot hanya menerima `tool_choice` `auto|none`; OpenClaw menormalkan nilai yang tidak kompatibel ke `auto`.
## Urutan resolusi
1. Direktif inline 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 config).
4. Default global (`agents.defaults.thinkingDefault` dalam config).
5. Fallback: default yang dideklarasikan penyedia ketika tersedia; jika tidak, model yang mendukung penalaran beresolusi ke `medium` atau level non-`off` terdekat yang didukung untuk model tersebut, dan model non-penalaran tetap `off`.
2. Override sesi (diatur 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 mendukung penalaran diselesaikan ke `medium` atau level non-`off` terdekat yang didukung untuk model tersebut, dan model non-penalaran tetap `off`.
## Menetapkan default sesi
## Mengatur default sesi
- Kirim pesan yang **hanya** berisi direktif (spasi diperbolehkan), misalnya `/think:medium` atau `/t high`.
- Itu berlaku untuk sesi saat ini (secara default per pengirim); dihapus oleh `/think:off` atau reset idle sesi.
- Balasan konfirmasi dikirim (`Thinking level set to high.` / `Thinking disabled.`). Jika level tidak valid (misalnya `/thinking big`), perintah ditolak dengan petunjuk dan status sesi tidak diubah.
- Kirim `/think` (atau `/think:`) tanpa argumen untuk melihat level pemikiran saat ini.
- Kirim pesan yang **hanya** berisi direktif (spasi kosong diperbolehkan), misalnya `/think:medium` atau `/t high`.
- Itu bertahan untuk sesi saat ini (secara 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 (misalnya `/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 oleh agen
- **Pi tertanam**: level yang diresolusi diteruskan ke runtime agen Pi dalam proses.
- **Pi tertanam**: level yang diselesaikan diteruskan ke runtime agen Pi dalam proses.
## Mode cepat (/fast)
- Level: `on|off`.
- Pesan yang hanya berisi direktif 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 meresolusi mode cepat dalam urutan ini:
1. Inline/hanya direktif `/fast on|off`
- OpenClaw menyelesaikan mode cepat dalam urutan ini:
1. Inline/hanya-direktif `/fast on|off`
2. Override sesi
3. Default per agen (`agents.list[].fastModeDefault`)
4. Config per model: `agents.defaults.models["<provider>/<model>"].params.fastMode`
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 traffic berautentikasi 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 `minimax/*` pada jalur kompatibel Anthropic, `/fast on` (atau `params.fastMode: true`) menulis ulang `MiniMax-M2.7` menjadi `MiniMax-M2.7-highspeed`.
- Parameter model Anthropic `serviceTier` / `service_tier` eksplisit mengesampingkan default mode cepat ketika keduanya ditetapkan. OpenClaw tetap melewati injeksi tingkat layanan Anthropic untuk URL basis proxy non-Anthropic.
- Untuk `openai-codex/*`, mode cepat mengirim flag `service_tier=priority` yang sama pada Codex Responses. OpenClaw mempertahankan satu toggle `/fast` bersama di kedua jalur auth.
- Untuk permintaan publik langsung `anthropic/*`, termasuk traffic terautentikasi OAuth yang dikirim ke `api.anthropic.com`, mode cepat dipetakan ke tier 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 mengoverride default mode cepat ketika keduanya ditetapkan. OpenClaw tetap melewati injeksi tier layanan Anthropic untuk URL basis proxy non-Anthropic.
- `/status` menampilkan `Fast` hanya ketika mode cepat diaktifkan.
## Direktif verbose (/verbose atau /v)
- Level: `on` (minimal) | `full` | `off` (default).
- Pesan yang hanya berisi direktif mengaktifkan/menonaktifkan 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 Sessions dengan memilih `inherit`.
- Direktif inline hanya memengaruhi pesan tersebut; default sesi/global berlaku jika tidak.
- 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; bersihkan melalui UI Sessions dengan memilih `inherit`.
- Direktif inline hanya memengaruhi pesan tersebut; default sesi/global berlaku selain itu.
- Kirim `/verbose` (atau `/verbose:`) tanpa argumen untuk melihat level verbose saat ini.
- Ketika verbose aktif, agen yang memancarkan hasil alat terstruktur (Pi, agen JSON lain) mengirim setiap panggilan alat kembali sebagai pesannya sendiri yang hanya berisi metadata, diawali dengan `<emoji> <tool-name>: <arg>` ketika tersedia (path/perintah). Ringkasan alat ini dikirim segera setelah setiap alat dimulai (bubble terpisah), bukan sebagai delta streaming.
- Ringkasan kegagalan alat tetap terlihat dalam mode normal, tetapi sufiks detail error mentah disembunyikan kecuali verbose adalah `on` atau `full`.
- Ketika verbose adalah `full`, output alat juga diteruskan setelah selesai (bubble terpisah, dipotong ke panjang yang aman). Jika Anda mengubah `/verbose on|full|off` saat run sedang berjalan, bubble alat berikutnya mengikuti pengaturan baru.
- Saat verbose aktif, agen yang memancarkan hasil tool terstruktur (Pi, agen JSON lain) mengirim setiap panggilan tool kembali sebagai pesan khusus metadata tersendiri, diawali dengan `<emoji> <tool-name>: <arg>` jika tersedia (path/command). Ringkasan tool ini dikirim segera ketika setiap tool dimulai (bubble terpisah), bukan sebagai delta streaming.
- Ringkasan kegagalan tool tetap terlihat dalam mode normal, tetapi sufiks detail error mentah disembunyikan kecuali verbose adalah `on` atau `full`.
- Saat verbose adalah `full`, output tool juga diteruskan setelah selesai (bubble terpisah, dipotong ke panjang aman). Jika Anda mengalihkan `/verbose on|full|off` saat run sedang berjalan, bubble tool berikutnya mengikuti pengaturan baru.
## Direktif trace Plugin (/trace)
- Level: `on` | `off` (default).
- Pesan yang hanya berisi direktif mengaktifkan/menonaktifkan output trace Plugin sesi dan membalas `Plugin trace enabled.` / `Plugin trace disabled.`.
- Direktif inline hanya memengaruhi pesan tersebut; default sesi/global berlaku jika tidak.
- Pesan yang hanya berisi direktif mengalihkan output trace Plugin sesi dan membalas `Plugin trace enabled.` / `Plugin trace disabled.`.
- Direktif inline 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.
@ -102,14 +103,14 @@ x-i18n:
## Visibilitas penalaran (/reasoning)
- Level: `on|off|stream`.
- Pesan yang hanya berisi direktif mengaktifkan/menonaktifkan apakah blok pemikiran ditampilkan dalam balasan.
- Ketika diaktifkan, penalaran dikirim sebagai **pesan terpisah** yang diawali dengan `Reasoning:`.
- `stream` (hanya Telegram): men-stream penalaran ke bubble draf Telegram saat balasan sedang dibuat, lalu mengirim jawaban akhir tanpa penalaran.
- Pesan yang hanya berisi direktif mengalihkan apakah blok berpikir ditampilkan dalam balasan.
- Saat diaktifkan, penalaran dikirim sebagai **pesan terpisah** yang diawali dengan `Reasoning:`.
- `stream` (hanya Telegram): melakukan streaming penalaran ke bubble 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: direktif inline, 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>` yang tertutup tetap disembunyikan 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 sisanya.
Tag penalaran model lokal yang malformasi ditangani secara konservatif. Blok `<think>...</think>` tertutup tetap disembunyikan 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 terkirim sebagai teks kosong, OpenClaw menghapus tag pembuka yang malformasi dan mengirim teks yang tersisa.
## Terkait
@ -117,23 +118,23 @@ Tag penalaran model lokal yang salah bentuk ditangani secara konservatif. Blok `
## 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.`). Direktif inline dalam pesan heartbeat berlaku seperti biasa (tetapi hindari mengubah default sesi dari heartbeat).
- Pengiriman Heartbeat secara default hanya mengirim payload akhir. Untuk juga mengirim pesan `Reasoning:` terpisah (ketika tersedia), tetapkan `agents.defaults.heartbeat.includeReasoning: true` atau per agen `agents.list[].heartbeat.includeReasoning: true`.
- Body probe Heartbeat adalah prompt Heartbeat yang dikonfigurasi (default: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Direktif inline dalam pesan Heartbeat berlaku seperti biasa (tetapi hindari mengubah default sesi dari Heartbeat).
- Pengiriman Heartbeat secara default hanya menggunakan payload final. Untuk juga mengirim pesan `Reasoning:` terpisah (jika tersedia), tetapkan `agents.defaults.heartbeat.includeReasoning: true` atau per agen `agents.list[].heartbeat.includeReasoning: true`.
## UI chat web
- Pemilih pemikiran chat web mencerminkan level tersimpan sesi dari penyimpanan/config sesi masuk saat halaman dimuat.
- Memilih level lain langsung menulis override sesi melalui `sessions.patch`; itu tidak menunggu pengiriman berikutnya dan bukan override sekali pakai `thinkingOnce`.
- Opsi pertama selalu `Default (<resolved level>)`, dengan default yang diresolusi berasal dari profil pemikiran penyedia model sesi aktif ditambah 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 penyedia sendiri; Plugin memiliki set level khusus model.
- Pemilih berpikir chat web mencerminkan level tersimpan sesi dari penyimpanan sesi masuk/konfigurasi saat halaman dimuat.
- Memilih level lain langsung menulis override sesi melalui `sessions.patch`; ini tidak menunggu pengiriman berikutnya dan bukan override satu kali `thinkingOnce`.
- Opsi pertama selalu `Default (<resolved level>)`, dengan default yang diselesaikan berasal dari profil berpikir penyedia model sesi aktif ditambah 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 legacy. UI browser tidak menyimpan daftar regex penyedia sendiri; Plugin memiliki kumpulan level khusus model.
- `/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 menentukan level yang didukung model dan nilai bawaannya.
- Plugin penyedia yang melakukan 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 penyedia dapat mengekspos `resolveThinkingProfile(ctx)` untuk menentukan level yang didukung model dan default-nya.
- 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 tersimpan (`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 menyimpan daftar level 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 di sisi Plugin.
- Hook lama yang dipublikasikan (`supportsXHighThinking`, `isBinaryThinking`, dan `resolveDefaultThinkingLevel`) tetap ada sebagai adaptor kompatibilitas, tetapi kumpulan level kustom baru harus menggunakan `resolveThinkingProfile`.
- Baris/nilai bawaan Gateway mengekspos `thinkingLevels`, `thinkingOptions`, dan `thinkingDefault` agar klien ACP/obrolan merender id dan label profil yang sama dengan yang digunakan validasi runtime.
- 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 warisan yang dipublikasikan (`supportsXHighThinking`, `isBinaryThinking`, dan `resolveDefaultThinkingLevel`) tetap ada sebagai adaptor kompatibilitas, tetapi kumpulan level kustom baru harus menggunakan `resolveThinkingProfile`.
- Baris/default Gateway mengekspos `thinkingLevels`, `thinkingOptions`, dan `thinkingDefault` agar klien ACP/chat merender id dan label profil yang sama dengan yang digunakan validasi runtime.