chore(i18n): refresh id translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
6983853b45
commit
3a4fd5f6b7
@ -4,45 +4,45 @@ read_when:
|
||||
- Pemecahan masalah penyandingan Webhook
|
||||
- Mengonfigurasi iMessage di macOS
|
||||
sidebarTitle: BlueBubbles
|
||||
summary: iMessage melalui server macOS BlueBubbles (pengiriman/penerimaan REST, status mengetik, reaksi, pemasangan, tindakan lanjutan).
|
||||
summary: iMessage melalui server macOS BlueBubbles (pengiriman/penerimaan REST, indikator mengetik, reaksi, pemasangan, tindakan lanjutan).
|
||||
title: BlueBubbles
|
||||
x-i18n:
|
||||
generated_at: "2026-05-01T09:22:14Z"
|
||||
generated_at: "2026-05-04T02:21:41Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 499cc2a46db6e0eddfb897e96ec4b3e4a39ba9f2f6da8e7485c1c46562de4145
|
||||
source_hash: 78a054da0c7c32b161997acd05914896259dd1a050e736a4c9e438a452ab6a51
|
||||
source_path: channels/bluebubbles.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Status: Plugin bawaan yang berkomunikasi dengan server macOS BlueBubbles melalui HTTP. **Direkomendasikan untuk integrasi iMessage** karena API-nya lebih kaya dan penyiapannya lebih mudah dibandingkan channel imsg lama.
|
||||
Status: Plugin bawaan yang berkomunikasi dengan server macOS BlueBubbles melalui HTTP. **Direkomendasikan untuk integrasi iMessage** karena API-nya lebih kaya dan penyiapannya lebih mudah dibandingkan saluran imsg lama.
|
||||
|
||||
<Note>
|
||||
Rilis OpenClaw saat ini menyertakan BlueBubbles, jadi build paket normal tidak memerlukan langkah `openclaw plugins install` terpisah.
|
||||
Rilis OpenClaw saat ini sudah menyertakan BlueBubbles, sehingga build paket normal tidak memerlukan langkah `openclaw plugins install` terpisah.
|
||||
</Note>
|
||||
|
||||
## Gambaran umum
|
||||
|
||||
- Berjalan di macOS melalui aplikasi pembantu BlueBubbles ([bluebubbles.app](https://bluebubbles.app)).
|
||||
- Direkomendasikan/diuji: macOS Sequoia (15). macOS Tahoe (26) berfungsi; pengeditan saat ini rusak di Tahoe, dan pembaruan ikon grup mungkin melaporkan berhasil tetapi tidak tersinkron.
|
||||
- Direkomendasikan/diuji: macOS Sequoia (15). macOS Tahoe (26) berfungsi; fitur edit saat ini rusak di Tahoe, dan pembaruan ikon grup mungkin melaporkan berhasil tetapi tidak tersinkron.
|
||||
- OpenClaw berkomunikasi dengannya melalui REST API (`GET /api/v1/ping`, `POST /message/text`, `POST /chat/:id/*`).
|
||||
- Pesan masuk tiba melalui Webhook; balasan keluar, indikator mengetik, tanda terima telah dibaca, dan tapback adalah panggilan REST.
|
||||
- Lampiran dan stiker dicerna sebagai media masuk (dan ditampilkan ke agen jika memungkinkan).
|
||||
- Pesan masuk tiba melalui webhooks; balasan keluar, indikator mengetik, tanda dibaca, dan tapback adalah panggilan REST.
|
||||
- Lampiran dan stiker diserap sebagai media masuk (dan ditampilkan ke agen bila memungkinkan).
|
||||
- Balasan Auto-TTS yang menyintesis audio MP3 atau CAF dikirim sebagai gelembung memo suara iMessage, bukan lampiran file biasa.
|
||||
- Pairing/daftar izin bekerja dengan cara yang sama seperti channel lain (`/channels/pairing` dll.) dengan `channels.bluebubbles.allowFrom` + kode pairing.
|
||||
- Reaksi ditampilkan sebagai peristiwa sistem seperti Slack/Telegram sehingga agen dapat "menyebutkan" reaksi tersebut sebelum membalas.
|
||||
- Fitur lanjutan: edit, batalkan kirim, threading balasan, efek pesan, manajemen grup.
|
||||
- Penyandingan/allowlist bekerja dengan cara yang sama seperti saluran lain (`/channels/pairing` dll) dengan `channels.bluebubbles.allowFrom` + kode penyandingan.
|
||||
- Reaksi ditampilkan sebagai peristiwa sistem seperti Slack/Telegram sehingga agen dapat "menyebut" reaksi tersebut sebelum membalas.
|
||||
- Fitur lanjutan: edit, batal kirim, thread balasan, efek pesan, manajemen grup.
|
||||
|
||||
## Mulai cepat
|
||||
|
||||
<Steps>
|
||||
<Step title="Instal BlueBubbles">
|
||||
<Step title="Install BlueBubbles">
|
||||
Instal server BlueBubbles di Mac Anda (ikuti instruksi di [bluebubbles.app/install](https://bluebubbles.app/install)).
|
||||
</Step>
|
||||
<Step title="Aktifkan API web">
|
||||
Di konfigurasi BlueBubbles, aktifkan API web dan tetapkan kata sandi.
|
||||
<Step title="Enable the web API">
|
||||
Di konfigurasi BlueBubbles, aktifkan web API dan tetapkan kata sandi.
|
||||
</Step>
|
||||
<Step title="Konfigurasikan OpenClaw">
|
||||
<Step title="Configure OpenClaw">
|
||||
Jalankan `openclaw onboard` dan pilih BlueBubbles, atau konfigurasikan secara manual:
|
||||
|
||||
```json5
|
||||
@ -59,29 +59,29 @@ Rilis OpenClaw saat ini menyertakan BlueBubbles, jadi build paket normal tidak m
|
||||
```
|
||||
|
||||
</Step>
|
||||
<Step title="Arahkan Webhook ke Gateway">
|
||||
Arahkan Webhook BlueBubbles ke Gateway Anda (contoh: `https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`).
|
||||
<Step title="Point webhooks at the gateway">
|
||||
Arahkan webhooks BlueBubbles ke gateway Anda (contoh: `https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`).
|
||||
</Step>
|
||||
<Step title="Mulai Gateway">
|
||||
Mulai Gateway; Gateway akan mendaftarkan handler Webhook dan memulai pairing.
|
||||
<Step title="Start the gateway">
|
||||
Mulai gateway; gateway akan mendaftarkan handler webhook dan mulai penyandingan.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Warning>
|
||||
**Keamanan**
|
||||
|
||||
- Selalu tetapkan kata sandi Webhook.
|
||||
- Autentikasi Webhook selalu wajib. OpenClaw menolak permintaan Webhook BlueBubbles kecuali permintaan tersebut menyertakan kata sandi/guid yang cocok dengan `channels.bluebubbles.password` (misalnya `?password=<password>` atau `x-password`), terlepas dari topologi loopback/proksi.
|
||||
- Autentikasi kata sandi diperiksa sebelum membaca/mengurai isi Webhook lengkap.
|
||||
- Selalu tetapkan kata sandi webhook.
|
||||
- Autentikasi webhook selalu wajib. OpenClaw menolak permintaan webhook BlueBubbles kecuali permintaan tersebut menyertakan kata sandi/guid yang cocok dengan `channels.bluebubbles.password` (misalnya `?password=<password>` atau `x-password`), apa pun topologi loopback/proxy-nya.
|
||||
- Autentikasi kata sandi diperiksa sebelum membaca/mem-parse body webhook lengkap.
|
||||
|
||||
</Warning>
|
||||
|
||||
## Menjaga Messages.app tetap hidup (penyiapan VM / headless)
|
||||
## Menjaga Messages.app tetap aktif (penyiapan VM / headless)
|
||||
|
||||
Beberapa penyiapan VM macOS / selalu aktif dapat membuat Messages.app menjadi "idle" (peristiwa masuk berhenti sampai aplikasi dibuka/dibawa ke depan). Solusi sederhana adalah **menyentuh Messages setiap 5 menit** menggunakan AppleScript + LaunchAgent.
|
||||
|
||||
<Steps>
|
||||
<Step title="Simpan AppleScript">
|
||||
<Step title="Save the AppleScript">
|
||||
Simpan ini sebagai `~/Scripts/poke-messages.scpt`:
|
||||
|
||||
```applescript
|
||||
@ -100,7 +100,7 @@ Beberapa penyiapan VM macOS / selalu aktif dapat membuat Messages.app menjadi "i
|
||||
```
|
||||
|
||||
</Step>
|
||||
<Step title="Instal LaunchAgent">
|
||||
<Step title="Install a LaunchAgent">
|
||||
Simpan ini sebagai `~/Library/LaunchAgents/com.user.poke-messages.plist`:
|
||||
|
||||
```xml
|
||||
@ -135,7 +135,7 @@ Beberapa penyiapan VM macOS / selalu aktif dapat membuat Messages.app menjadi "i
|
||||
Ini berjalan **setiap 300 detik** dan **saat login**. Eksekusi pertama mungkin memicu prompt **Automation** macOS (`osascript` → Messages). Setujui prompt tersebut dalam sesi pengguna yang sama dengan yang menjalankan LaunchAgent.
|
||||
|
||||
</Step>
|
||||
<Step title="Muat">
|
||||
<Step title="Load it">
|
||||
```bash
|
||||
launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true
|
||||
launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist
|
||||
@ -157,16 +157,16 @@ Wizard meminta:
|
||||
Alamat server BlueBubbles (misalnya, `http://192.168.1.100:1234`).
|
||||
</ParamField>
|
||||
<ParamField path="Password" type="string" required>
|
||||
Kata sandi API dari pengaturan Server BlueBubbles.
|
||||
Kata sandi API dari pengaturan BlueBubbles Server.
|
||||
</ParamField>
|
||||
<ParamField path="Webhook path" type="string" default="/bluebubbles-webhook">
|
||||
Path endpoint Webhook.
|
||||
Jalur endpoint Webhook.
|
||||
</ParamField>
|
||||
<ParamField path="DM policy" type="string">
|
||||
`pairing`, `allowlist`, `open`, atau `disabled`.
|
||||
</ParamField>
|
||||
<ParamField path="Allow list" type="string[]">
|
||||
Nomor telepon, email, atau target chat.
|
||||
Nomor telepon, email, atau target obrolan.
|
||||
</ParamField>
|
||||
|
||||
Anda juga dapat menambahkan BlueBubbles melalui CLI:
|
||||
@ -178,18 +178,18 @@ openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --passwor
|
||||
## Kontrol akses (DM + grup)
|
||||
|
||||
<Tabs>
|
||||
<Tab title="DM">
|
||||
<Tab title="DMs">
|
||||
- Default: `channels.bluebubbles.dmPolicy = "pairing"`.
|
||||
- Pengirim tidak dikenal menerima kode pairing; pesan diabaikan sampai disetujui (kode kedaluwarsa setelah 1 jam).
|
||||
- Pengirim tidak dikenal menerima kode penyandingan; pesan diabaikan sampai disetujui (kode kedaluwarsa setelah 1 jam).
|
||||
- Setujui melalui:
|
||||
- `openclaw pairing list bluebubbles`
|
||||
- `openclaw pairing approve bluebubbles <CODE>`
|
||||
- Pairing adalah pertukaran token default. Detail: [Pairing](/id/channels/pairing)
|
||||
- Penyandingan adalah pertukaran token default. Detail: [Penyandingan](/id/channels/pairing)
|
||||
|
||||
</Tab>
|
||||
<Tab title="Grup">
|
||||
<Tab title="Groups">
|
||||
- `channels.bluebubbles.groupPolicy = open | allowlist | disabled` (default: `allowlist`).
|
||||
- `channels.bluebubbles.groupAllowFrom` mengontrol siapa yang dapat memicu di grup saat `allowlist` ditetapkan.
|
||||
- `channels.bluebubbles.groupAllowFrom` mengontrol siapa yang dapat memicu dalam grup saat `allowlist` ditetapkan.
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
@ -198,10 +198,10 @@ openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --passwor
|
||||
|
||||
Webhook grup BlueBubbles sering kali hanya menyertakan alamat peserta mentah. Jika Anda ingin konteks `GroupMembers` menampilkan nama kontak lokal sebagai gantinya, Anda dapat ikut serta dalam pengayaan Contacts lokal di macOS:
|
||||
|
||||
- `channels.bluebubbles.enrichGroupParticipantsFromContacts = true` mengaktifkan lookup. Default: `false`.
|
||||
- Lookup hanya berjalan setelah akses grup, otorisasi perintah, dan gating penyebutan mengizinkan pesan lewat.
|
||||
- `channels.bluebubbles.enrichGroupParticipantsFromContacts = true` mengaktifkan pencarian. Default: `false`.
|
||||
- Pencarian hanya berjalan setelah akses grup, otorisasi perintah, dan gating sebutan mengizinkan pesan lewat.
|
||||
- Hanya peserta telepon tanpa nama yang diperkaya.
|
||||
- Nomor telepon mentah tetap menjadi fallback saat tidak ditemukan kecocokan lokal.
|
||||
- Nomor telepon mentah tetap menjadi fallback saat tidak ada kecocokan lokal yang ditemukan.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -213,13 +213,13 @@ Webhook grup BlueBubbles sering kali hanya menyertakan alamat peserta mentah. Ji
|
||||
}
|
||||
```
|
||||
|
||||
### Gating penyebutan (grup)
|
||||
### Gating sebutan (grup)
|
||||
|
||||
BlueBubbles mendukung gating penyebutan untuk chat grup, sesuai perilaku iMessage/WhatsApp:
|
||||
BlueBubbles mendukung gating sebutan untuk obrolan grup, sesuai perilaku iMessage/WhatsApp:
|
||||
|
||||
- Menggunakan `agents.list[].groupChat.mentionPatterns` (atau `messages.groupChat.mentionPatterns`) untuk mendeteksi penyebutan.
|
||||
- Saat `requireMention` diaktifkan untuk suatu grup, agen hanya merespons saat disebutkan.
|
||||
- Perintah kontrol dari pengirim yang diotorisasi melewati gating penyebutan.
|
||||
- Menggunakan `agents.list[].groupChat.mentionPatterns` (atau `messages.groupChat.mentionPatterns`) untuk mendeteksi sebutan.
|
||||
- Saat `requireMention` diaktifkan untuk grup, agen hanya merespons saat disebut.
|
||||
- Perintah kontrol dari pengirim yang berwenang melewati gating sebutan.
|
||||
|
||||
Konfigurasi per grup:
|
||||
|
||||
@ -242,11 +242,11 @@ Konfigurasi per grup:
|
||||
|
||||
- Perintah kontrol (misalnya, `/config`, `/model`) memerlukan otorisasi.
|
||||
- Menggunakan `allowFrom` dan `groupAllowFrom` untuk menentukan otorisasi perintah.
|
||||
- Pengirim yang diotorisasi dapat menjalankan perintah kontrol bahkan tanpa menyebut di grup.
|
||||
- Pengirim yang berwenang dapat menjalankan perintah kontrol meski tanpa menyebut di grup.
|
||||
|
||||
### Prompt sistem per grup
|
||||
|
||||
Setiap entri di bawah `channels.bluebubbles.groups.*` menerima string `systemPrompt` opsional. Nilainya disuntikkan ke prompt sistem agen pada setiap giliran yang menangani pesan di grup tersebut, sehingga Anda dapat menetapkan persona atau aturan perilaku per grup tanpa mengedit prompt agen:
|
||||
Setiap entri di bawah `channels.bluebubbles.groups.*` menerima string `systemPrompt` opsional. Nilai ini disuntikkan ke prompt sistem agen pada setiap giliran yang menangani pesan di grup tersebut, sehingga Anda dapat menetapkan persona atau aturan perilaku per grup tanpa mengedit prompt agen:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -264,9 +264,9 @@ Setiap entri di bawah `channels.bluebubbles.groups.*` menerima string `systemPro
|
||||
|
||||
Kunci cocok dengan apa pun yang dilaporkan BlueBubbles sebagai `chatGuid` / `chatIdentifier` / `chatId` numerik untuk grup, dan entri wildcard `"*"` menyediakan default untuk setiap grup tanpa kecocokan persis (pola yang sama digunakan oleh `requireMention` dan kebijakan alat per grup). Kecocokan persis selalu mengalahkan wildcard. DM mengabaikan bidang ini; gunakan kustomisasi prompt tingkat agen atau tingkat akun sebagai gantinya.
|
||||
|
||||
#### Contoh lengkap: balasan berutas dan reaksi tapback (API Privat)
|
||||
#### Contoh lengkap: balasan ber-thread dan reaksi tapback (Private API)
|
||||
|
||||
Dengan API Privat BlueBubbles diaktifkan, pesan masuk tiba dengan ID pesan pendek (misalnya `[[reply_to:5]]`) dan agen dapat memanggil `action=reply` untuk membuat utas ke pesan tertentu atau `action=react` untuk menjatuhkan tapback. `systemPrompt` per grup adalah cara yang andal untuk menjaga agen memilih alat yang tepat:
|
||||
Dengan BlueBubbles Private API diaktifkan, pesan masuk tiba dengan ID pesan pendek (misalnya `[[reply_to:5]]`) dan agen dapat memanggil `action=reply` untuk masuk ke thread pesan tertentu atau `action=react` untuk memberikan tapback. `systemPrompt` per grup adalah cara yang andal untuk menjaga agen memilih alat yang tepat:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -274,15 +274,7 @@ Dengan API Privat BlueBubbles diaktifkan, pesan masuk tiba dengan ID pesan pende
|
||||
bluebubbles: {
|
||||
groups: {
|
||||
"iMessage;+;chat-family": {
|
||||
systemPrompt: [
|
||||
"When replying in this group, always call action=reply with the",
|
||||
"[[reply_to:N]] messageId from context so your response threads",
|
||||
"under the triggering message. Never send a new unlinked message.",
|
||||
"",
|
||||
"For short acknowledgements ('ok', 'got it', 'on it'), use",
|
||||
"action=react with an appropriate tapback emoji (❤️, 👍, 😂, ‼️, ❓)",
|
||||
"instead of sending a text reply.",
|
||||
].join(" "),
|
||||
systemPrompt: "When replying in this group, always call action=reply with the [[reply_to:N]] messageId from context so your response threads under the triggering message. Never send a new unlinked message. For short acknowledgements ('ok', 'got it', 'on it'), use action=react with an appropriate tapback emoji (❤️, 👍, 😂, ‼️, ❓) instead of sending a text reply.",
|
||||
},
|
||||
},
|
||||
},
|
||||
@ -290,20 +282,20 @@ Dengan API Privat BlueBubbles diaktifkan, pesan masuk tiba dengan ID pesan pende
|
||||
}
|
||||
```
|
||||
|
||||
Reaksi tapback dan balasan berutas sama-sama memerlukan API Privat BlueBubbles; lihat [Tindakan lanjutan](#advanced-actions) dan [ID pesan](#message-ids-short-vs-full) untuk mekanisme dasarnya.
|
||||
Reaksi tapback dan balasan ber-thread sama-sama memerlukan BlueBubbles Private API; lihat [Tindakan lanjutan](#advanced-actions) dan [ID pesan](#message-ids-short-vs-full) untuk mekanisme dasarnya.
|
||||
|
||||
## Pengikatan percakapan ACP
|
||||
## Binding percakapan ACP
|
||||
|
||||
Chat BlueBubbles dapat diubah menjadi workspace ACP yang tahan lama tanpa mengubah lapisan transport.
|
||||
Obrolan BlueBubbles dapat diubah menjadi workspace ACP yang tahan lama tanpa mengubah lapisan transport.
|
||||
|
||||
Alur operator cepat:
|
||||
|
||||
- Jalankan `/acp spawn codex --bind here` di dalam DM atau chat grup yang diizinkan.
|
||||
- Pesan berikutnya dalam percakapan BlueBubbles yang sama dirutekan ke sesi ACP yang dibuat.
|
||||
- Jalankan `/acp spawn codex --bind here` di dalam DM atau obrolan grup yang diizinkan.
|
||||
- Pesan berikutnya dalam percakapan BlueBubbles yang sama akan dirutekan ke sesi ACP yang dibuat.
|
||||
- `/new` dan `/reset` mereset sesi ACP terikat yang sama di tempat.
|
||||
- `/acp close` menutup sesi ACP dan menghapus pengikatan.
|
||||
- `/acp close` menutup sesi ACP dan menghapus binding.
|
||||
|
||||
Pengikatan persisten yang dikonfigurasi juga didukung melalui entri `bindings[]` tingkat atas dengan `type: "acp"` dan `match.channel: "bluebubbles"`.
|
||||
Binding persisten terkonfigurasi juga didukung melalui entri `bindings[]` tingkat atas dengan `type: "acp"` dan `match.channel: "bluebubbles"`.
|
||||
|
||||
`match.peer.id` dapat menggunakan bentuk target BlueBubbles apa pun yang didukung:
|
||||
|
||||
@ -312,7 +304,7 @@ Pengikatan persisten yang dikonfigurasi juga didukung melalui entri `bindings[]`
|
||||
- `chat_guid:<guid>`
|
||||
- `chat_identifier:<identifier>`
|
||||
|
||||
Untuk pengikatan grup yang stabil, pilih `chat_id:*` atau `chat_identifier:*`.
|
||||
Untuk binding grup yang stabil, utamakan `chat_id:*` atau `chat_identifier:*`.
|
||||
|
||||
Contoh:
|
||||
|
||||
@ -344,13 +336,13 @@ Contoh:
|
||||
}
|
||||
```
|
||||
|
||||
Lihat [Agen ACP](/id/tools/acp-agents) untuk perilaku pengikatan ACP bersama.
|
||||
Lihat [Agen ACP](/id/tools/acp-agents) untuk perilaku binding ACP bersama.
|
||||
|
||||
## Mengetik + tanda terima telah dibaca
|
||||
## Indikator mengetik + tanda dibaca
|
||||
|
||||
- **Indikator mengetik**: Dikirim otomatis sebelum dan selama pembuatan respons.
|
||||
- **Tanda sudah dibaca**: Dikontrol oleh `channels.bluebubbles.sendReadReceipts` (bawaan: `true`).
|
||||
- **Indikator mengetik**: OpenClaw mengirim event mulai mengetik; BlueBubbles menghapus status mengetik secara otomatis saat mengirim atau timeout (penghentian manual melalui DELETE tidak andal).
|
||||
- **Tanda dibaca**: Dikontrol oleh `channels.bluebubbles.sendReadReceipts` (default: `true`).
|
||||
- **Indikator mengetik**: OpenClaw mengirim peristiwa mulai mengetik; BlueBubbles menghapus status mengetik secara otomatis saat mengirim atau timeout (penghentian manual melalui DELETE tidak andal).
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -390,33 +382,33 @@ BlueBubbles mendukung tindakan pesan lanjutan saat diaktifkan dalam konfigurasi:
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Tindakan yang tersedia">
|
||||
- **react**: Menambahkan/menghapus reaksi tapback (`messageId`, `emoji`, `remove`). Set tapback bawaan iMessage adalah `love`, `like`, `dislike`, `laugh`, `emphasize`, dan `question`. Saat agent memilih emoji di luar set tersebut (misalnya `👀`), alat reaksi akan fallback ke `love` sehingga tapback tetap dirender, bukan menggagalkan seluruh permintaan. Reaksi ack yang dikonfigurasi tetap divalidasi secara ketat dan menghasilkan error pada nilai yang tidak dikenal.
|
||||
- **edit**: Mengedit pesan terkirim (`messageId`, `text`).
|
||||
- **unsend**: Membatalkan pengiriman pesan (`messageId`).
|
||||
- **reply**: Membalas pesan tertentu (`messageId`, `text`, `to`).
|
||||
- **sendWithEffect**: Mengirim dengan efek iMessage (`text`, `to`, `effectId`).
|
||||
- **renameGroup**: Mengganti nama chat grup (`chatGuid`, `displayName`).
|
||||
- **setGroupIcon**: Mengatur ikon/foto chat grup (`chatGuid`, `media`) — tidak stabil di macOS 26 Tahoe (API dapat mengembalikan sukses tetapi ikon tidak tersinkron).
|
||||
- **addParticipant**: Menambahkan seseorang ke grup (`chatGuid`, `address`).
|
||||
- **removeParticipant**: Menghapus seseorang dari grup (`chatGuid`, `address`).
|
||||
- **leaveGroup**: Meninggalkan chat grup (`chatGuid`).
|
||||
- **upload-file**: Mengirim media/file (`to`, `buffer`, `filename`, `asVoice`).
|
||||
- Memo suara: atur `asVoice: true` dengan audio **MP3** atau **CAF** untuk mengirim sebagai pesan suara iMessage. BlueBubbles mengonversi MP3 → CAF saat mengirim memo suara.
|
||||
- **react**: Tambahkan/hapus reaksi tapback (`messageId`, `emoji`, `remove`). Set tapback native iMessage adalah `love`, `like`, `dislike`, `laugh`, `emphasize`, dan `question`. Saat agen memilih emoji di luar set tersebut (misalnya `👀`), alat reaksi kembali menggunakan `love` agar tapback tetap dirender alih-alih menggagalkan seluruh permintaan. Reaksi ack yang dikonfigurasi tetap divalidasi secara ketat dan menghasilkan error pada nilai yang tidak dikenal.
|
||||
- **edit**: Edit pesan terkirim (`messageId`, `text`).
|
||||
- **unsend**: Batalkan pengiriman pesan (`messageId`).
|
||||
- **reply**: Balas pesan tertentu (`messageId`, `text`, `to`).
|
||||
- **sendWithEffect**: Kirim dengan efek iMessage (`text`, `to`, `effectId`).
|
||||
- **renameGroup**: Ganti nama obrolan grup (`chatGuid`, `displayName`).
|
||||
- **setGroupIcon**: Tetapkan ikon/foto obrolan grup (`chatGuid`, `media`) — tidak stabil di macOS 26 Tahoe (API dapat mengembalikan sukses tetapi ikon tidak disinkronkan).
|
||||
- **addParticipant**: Tambahkan seseorang ke grup (`chatGuid`, `address`).
|
||||
- **removeParticipant**: Hapus seseorang dari grup (`chatGuid`, `address`).
|
||||
- **leaveGroup**: Tinggalkan obrolan grup (`chatGuid`).
|
||||
- **upload-file**: Kirim media/file (`to`, `buffer`, `filename`, `asVoice`).
|
||||
- Memo suara: tetapkan `asVoice: true` dengan audio **MP3** atau **CAF** untuk mengirim sebagai pesan suara iMessage. BlueBubbles mengonversi MP3 → CAF saat mengirim memo suara.
|
||||
- Alias lama: `sendAttachment` masih berfungsi, tetapi `upload-file` adalah nama tindakan kanonis.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### ID Pesan (pendek vs lengkap)
|
||||
### ID pesan (pendek vs lengkap)
|
||||
|
||||
OpenClaw dapat menampilkan ID pesan _pendek_ (misalnya, `1`, `2`) untuk menghemat token.
|
||||
|
||||
- `MessageSid` / `ReplyToId` dapat berupa ID pendek.
|
||||
- `MessageSidFull` / `ReplyToIdFull` berisi ID lengkap provider.
|
||||
- ID pendek berada di memori; ID ini dapat kedaluwarsa saat restart atau cache eviction.
|
||||
- ID pendek disimpan dalam memori; ID tersebut dapat kedaluwarsa saat restart atau cache dikeluarkan.
|
||||
- Tindakan menerima `messageId` pendek atau lengkap, tetapi ID pendek akan menghasilkan error jika tidak lagi tersedia.
|
||||
|
||||
Gunakan ID lengkap untuk otomasi dan penyimpanan yang tahan lama:
|
||||
Gunakan ID lengkap untuk automasi dan penyimpanan yang tahan lama:
|
||||
|
||||
- Templat: `{{MessageSidFull}}`, `{{ReplyToIdFull}}`
|
||||
- Konteks: `MessageSidFull` / `ReplyToIdFull` dalam payload masuk
|
||||
@ -427,27 +419,27 @@ Lihat [Konfigurasi](/id/gateway/configuration) untuk variabel templat.
|
||||
|
||||
## Menggabungkan DM split-send (perintah + URL dalam satu komposisi)
|
||||
|
||||
Saat pengguna mengetik perintah dan URL bersama-sama di iMessage — misalnya `Dump https://example.com/article` — Apple memecah pengiriman menjadi **dua pengiriman Webhook terpisah**:
|
||||
Saat pengguna mengetik perintah dan URL bersama-sama di iMessage — misalnya `Dump https://example.com/article` — Apple membagi pengiriman menjadi **dua pengiriman webhook terpisah**:
|
||||
|
||||
1. Pesan teks (`"Dump"`).
|
||||
2. Balon pratinjau URL (`"https://..."`) dengan gambar pratinjau OG sebagai lampiran.
|
||||
|
||||
Kedua Webhook tiba di OpenClaw dengan selisih ~0,8-2,0 dtk pada sebagian besar setup. Tanpa penggabungan, agent menerima perintah saja pada turn 1, membalas (sering kali "kirimkan URL-nya"), dan baru melihat URL pada turn 2 — saat konteks perintah sudah hilang.
|
||||
Kedua webhook tiba di OpenClaw dengan selisih sekitar 0,8-2,0 d pada sebagian besar penyiapan. Tanpa penggabungan, agen menerima perintah saja pada giliran 1, membalas (sering kali "kirimkan URL-nya"), dan baru melihat URL pada giliran 2 — saat konteks perintah sudah hilang.
|
||||
|
||||
`channels.bluebubbles.coalesceSameSenderDms` memilih sebuah DM untuk menggabungkan Webhook berturut-turut dari pengirim yang sama menjadi satu turn agent. Chat grup tetap menggunakan kunci per pesan sehingga struktur turn multi-pengguna tetap dipertahankan.
|
||||
`channels.bluebubbles.coalesceSameSenderDms` mengikutsertakan DM untuk menggabungkan webhook berurutan dari pengirim yang sama menjadi satu giliran agen. Obrolan grup tetap menggunakan kunci per pesan sehingga struktur giliran multi-pengguna dipertahankan.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Kapan mengaktifkan">
|
||||
Aktifkan saat:
|
||||
|
||||
- Anda mengirimkan Skills yang mengharapkan `command + payload` dalam satu pesan (dump, paste, save, queue, dll.).
|
||||
- Anda mengirimkan skills yang mengharapkan `command + payload` dalam satu pesan (dump, paste, save, queue, dll.).
|
||||
- Pengguna Anda menempelkan URL, gambar, atau konten panjang bersama perintah.
|
||||
- Anda dapat menerima latensi turn DM tambahan (lihat di bawah).
|
||||
- Anda dapat menerima latensi giliran DM tambahan (lihat di bawah).
|
||||
|
||||
Biarkan dinonaktifkan saat:
|
||||
Biarkan nonaktif saat:
|
||||
|
||||
- Anda membutuhkan latensi perintah minimum untuk pemicu DM satu kata.
|
||||
- Semua flow Anda adalah perintah sekali jalan tanpa payload lanjutan.
|
||||
- Semua alur Anda adalah perintah sekali jalan tanpa tindak lanjut payload.
|
||||
|
||||
</Tab>
|
||||
<Tab title="Mengaktifkan">
|
||||
@ -461,9 +453,9 @@ Kedua Webhook tiba di OpenClaw dengan selisih ~0,8-2,0 dtk pada sebagian besar s
|
||||
}
|
||||
```
|
||||
|
||||
Dengan flag aktif dan tanpa `messages.inbound.byChannel.bluebubbles` eksplisit, jendela debounce melebar menjadi **2500 md** (bawaan untuk non-penggabungan adalah 500 md). Jendela yang lebih lebar diperlukan — ritme split-send Apple sebesar 0,8-2,0 dtk tidak muat dalam bawaan yang lebih ketat.
|
||||
Dengan flag aktif dan tanpa `messages.inbound.byChannel.bluebubbles` eksplisit, jendela debounce melebar menjadi **2500 md** (default untuk non-penggabungan adalah 500 md). Jendela yang lebih lebar diperlukan — irama split-send Apple 0,8-2,0 d tidak muat dalam default yang lebih sempit.
|
||||
|
||||
Untuk menyetel jendela sendiri:
|
||||
Untuk menyesuaikan jendela sendiri:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -480,28 +472,28 @@ Kedua Webhook tiba di OpenClaw dengan selisih ~0,8-2,0 dtk pada sebagian besar s
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab title="Trade-off">
|
||||
- **Latensi tambahan untuk perintah kontrol DM.** Dengan flag aktif, pesan perintah kontrol DM (seperti `Dump`, `Save`, dll.) sekarang menunggu hingga jendela debounce sebelum dikirim, untuk berjaga-jaga jika Webhook payload akan datang. Perintah chat grup tetap dikirim seketika.
|
||||
- **Output tergabung dibatasi** — teks tergabung dibatasi 4000 karakter dengan penanda `…[truncated]` eksplisit; lampiran dibatasi 20; entri sumber dibatasi 10 (pertama-plus-terbaru dipertahankan setelah itu). Setiap `messageId` sumber tetap mencapai dedupe masuk sehingga pemutaran ulang MessagePoller berikutnya dari event individual apa pun dikenali sebagai duplikat.
|
||||
- **Opt-in, per channel.** Channel lain (Telegram, WhatsApp, Slack, …) tidak terpengaruh.
|
||||
<Tab title="Konsekuensi">
|
||||
- **Latensi tambahan untuk perintah kontrol DM.** Dengan flag aktif, pesan perintah kontrol DM (seperti `Dump`, `Save`, dll.) kini menunggu hingga jendela debounce sebelum dikirim, untuk berjaga-jaga jika webhook payload akan datang. Perintah obrolan grup tetap dikirim seketika.
|
||||
- **Output gabungan dibatasi** — teks gabungan dibatasi hingga 4000 karakter dengan penanda `…[truncated]` eksplisit; lampiran dibatasi hingga 20; entri sumber dibatasi hingga 10 (pertama-plus-terbaru dipertahankan setelah itu). Setiap `messageId` sumber tetap mencapai dedupe masuk sehingga pemutaran ulang MessagePoller berikutnya dari peristiwa individual apa pun dikenali sebagai duplikat.
|
||||
- **Opt-in, per saluran.** Saluran lain (Telegram, WhatsApp, Slack, …) tidak terpengaruh.
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### Skenario dan apa yang dilihat agent
|
||||
### Skenario dan apa yang dilihat agen
|
||||
|
||||
| Pengguna menyusun | Apple mengirimkan | Flag nonaktif (bawaan) | Flag aktif + jendela 2500 md |
|
||||
| ------------------------------------------------------------------- | ------------------------- | -------------------------------------- | ------------------------------------------------------------------------ |
|
||||
| `Dump https://example.com` (satu pengiriman) | 2 Webhook berjarak ~1 dtk | Dua turn agent: "Dump" saja, lalu URL | Satu turn: teks tergabung `Dump https://example.com` |
|
||||
| `Save this 📎image.jpg caption` (lampiran + teks) | 2 Webhook | Dua turn | Satu turn: teks + gambar |
|
||||
| `/status` (perintah mandiri) | 1 Webhook | Pengiriman seketika | **Menunggu hingga jendela, lalu mengirim** |
|
||||
| URL ditempelkan saja | 1 Webhook | Pengiriman seketika | Pengiriman seketika (hanya satu entri dalam bucket) |
|
||||
| Teks + URL dikirim sebagai dua pesan terpisah yang disengaja, berjeda menit | 2 Webhook di luar jendela | Dua turn | Dua turn (jendela kedaluwarsa di antara keduanya) |
|
||||
| Flood cepat (>10 DM kecil di dalam jendela) | N Webhook | N turn | Satu turn, output dibatasi (pertama + terbaru, batas teks/lampiran diterapkan) |
|
||||
| Yang disusun pengguna | Yang dikirim Apple | Flag nonaktif (default) | Flag aktif + jendela 2500 md |
|
||||
| ------------------------------------------------------------------ | ------------------------- | --------------------------------------- | ----------------------------------------------------------------------- |
|
||||
| `Dump https://example.com` (satu pengiriman) | 2 webhook berselisih ~1 d | Dua giliran agen: "Dump" saja, lalu URL | Satu giliran: teks gabungan `Dump https://example.com` |
|
||||
| `Save this 📎image.jpg caption` (lampiran + teks) | 2 webhook | Dua giliran | Satu giliran: teks + gambar |
|
||||
| `/status` (perintah mandiri) | 1 webhook | Pengiriman seketika | **Tunggu hingga jendela, lalu kirim** |
|
||||
| URL ditempelkan sendiri | 1 webhook | Pengiriman seketika | Pengiriman seketika (hanya satu entri dalam bucket) |
|
||||
| Teks + URL dikirim sebagai dua pesan terpisah yang disengaja, berjeda menit | 2 webhook di luar jendela | Dua giliran | Dua giliran (jendela kedaluwarsa di antaranya) |
|
||||
| Banjir cepat (>10 DM kecil di dalam jendela) | N webhook | N giliran | Satu giliran, output dibatasi (pertama + terbaru, batas teks/lampiran diterapkan) |
|
||||
|
||||
### Pemecahan masalah penggabungan split-send
|
||||
|
||||
Jika flag aktif dan split-send masih tiba sebagai dua turn, periksa setiap lapisan:
|
||||
Jika flag aktif dan split-send masih tiba sebagai dua giliran, periksa tiap lapisan:
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Konfigurasi benar-benar dimuat">
|
||||
@ -512,24 +504,24 @@ Jika flag aktif dan split-send masih tiba sebagai dua turn, periksa setiap lapis
|
||||
Lalu `openclaw gateway restart` — flag dibaca saat pembuatan debouncer-registry.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Jendela debounce cukup lebar untuk setup Anda">
|
||||
<Accordion title="Jendela debounce cukup lebar untuk penyiapan Anda">
|
||||
Lihat log server BlueBubbles di bawah `~/Library/Logs/bluebubbles-server/main.log`:
|
||||
|
||||
```
|
||||
grep -E "Dispatching event to webhook" main.log | tail -20
|
||||
```
|
||||
|
||||
Ukur jarak antara pengiriman teks gaya `"Dump"` dan pengiriman `"https://..."; Attachments:` yang mengikutinya. Naikkan `messages.inbound.byChannel.bluebubbles` agar cukup mencakup jarak tersebut.
|
||||
Ukur jeda antara pengiriman teks bergaya `"Dump"` dan pengiriman `"https://..."; Attachments:` yang mengikutinya. Naikkan `messages.inbound.byChannel.bluebubbles` agar nyaman mencakup jeda tersebut.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Timestamp JSONL sesi ≠ kedatangan Webhook">
|
||||
Timestamp event sesi (`~/.openclaw/agents/<id>/sessions/*.jsonl`) mencerminkan saat Gateway menyerahkan pesan ke agent, **bukan** saat Webhook tiba. Pesan kedua yang diantrekan dengan tag `[Queued messages while agent was busy]` berarti turn pertama masih berjalan saat Webhook kedua tiba — bucket penggabungan sudah dikosongkan. Setel jendela berdasarkan log server BB, bukan log sesi.
|
||||
<Accordion title="Timestamp JSONL sesi ≠ kedatangan webhook">
|
||||
Timestamp peristiwa sesi (`~/.openclaw/agents/<id>/sessions/*.jsonl`) mencerminkan kapan Gateway menyerahkan pesan kepada agen, **bukan** kapan webhook tiba. Pesan kedua dalam antrean yang ditandai `[Queued messages while agent was busy]` berarti giliran pertama masih berjalan saat webhook kedua tiba — bucket penggabungan sudah di-flush. Sesuaikan jendela terhadap log server BB, bukan log sesi.
|
||||
</Accordion>
|
||||
<Accordion title="Tekanan memori memperlambat pengiriman balasan">
|
||||
Pada mesin yang lebih kecil (8 GB), turn agent dapat berlangsung cukup lama sehingga bucket penggabungan dikosongkan sebelum balasan selesai, dan URL masuk sebagai turn kedua yang diantrekan. Periksa `memory_pressure` dan `ps -o rss -p $(pgrep openclaw-gateway)`; jika Gateway berada di atas ~500 MB RSS dan kompresor aktif, tutup proses berat lain atau pindahkan ke host yang lebih besar.
|
||||
Pada mesin yang lebih kecil (8 GB), giliran agen dapat memakan waktu cukup lama sehingga bucket penggabungan di-flush sebelum balasan selesai, dan URL masuk sebagai giliran kedua yang diantrekan. Periksa `memory_pressure` dan `ps -o rss -p $(pgrep openclaw-gateway)`; jika Gateway melebihi ~500 MB RSS dan kompresor aktif, tutup proses berat lainnya atau pindah ke host yang lebih besar.
|
||||
</Accordion>
|
||||
<Accordion title="Pengiriman kutipan balasan adalah jalur berbeda">
|
||||
Jika pengguna mengetuk `Dump` sebagai **balasan** ke balon URL yang sudah ada (iMessage menampilkan badge "1 Reply" pada balon Dump), URL berada di `replyToBody`, bukan di Webhook kedua. Penggabungan tidak berlaku — itu adalah urusan skill/prompt, bukan urusan debouncer.
|
||||
Jika pengguna mengetuk `Dump` sebagai **balasan** ke balon URL yang sudah ada (iMessage menampilkan lencana "1 Reply" pada balon Dump), URL berada di `replyToBody`, bukan dalam webhook kedua. Penggabungan tidak berlaku — itu adalah urusan skill/prompt, bukan urusan debouncer.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -550,45 +542,45 @@ Kontrol apakah respons dikirim sebagai satu pesan atau di-stream dalam blok:
|
||||
## Media + batas
|
||||
|
||||
- Lampiran masuk diunduh dan disimpan dalam cache media.
|
||||
- Batas media melalui `channels.bluebubbles.mediaMaxMb` untuk media masuk dan keluar (bawaan: 8 MB).
|
||||
- Teks keluar dipotong menjadi chunk sesuai `channels.bluebubbles.textChunkLimit` (bawaan: 4000 karakter).
|
||||
- Batas media melalui `channels.bluebubbles.mediaMaxMb` untuk media masuk dan keluar (default: 8 MB).
|
||||
- Teks keluar dipecah menjadi bagian-bagian sesuai `channels.bluebubbles.textChunkLimit` (default: 4000 karakter).
|
||||
|
||||
## Referensi konfigurasi
|
||||
|
||||
Konfigurasi lengkap: [Konfigurasi](/id/gateway/configuration)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Koneksi dan Webhook">
|
||||
- `channels.bluebubbles.enabled`: Mengaktifkan/menonaktifkan channel.
|
||||
<Accordion title="Koneksi dan webhook">
|
||||
- `channels.bluebubbles.enabled`: Aktifkan/nonaktifkan saluran.
|
||||
- `channels.bluebubbles.serverUrl`: URL dasar API REST BlueBubbles.
|
||||
- `channels.bluebubbles.password`: Kata sandi API.
|
||||
- `channels.bluebubbles.webhookPath`: Path endpoint Webhook (bawaan: `/bluebubbles-webhook`).
|
||||
- `channels.bluebubbles.webhookPath`: Path endpoint Webhook (default: `/bluebubbles-webhook`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Kebijakan akses">
|
||||
- `channels.bluebubbles.dmPolicy`: `pairing | allowlist | open | disabled` (bawaan: `pairing`).
|
||||
- `channels.bluebubbles.dmPolicy`: `pairing | allowlist | open | disabled` (default: `pairing`).
|
||||
- `channels.bluebubbles.allowFrom`: Allowlist DM (handle, email, nomor E.164, `chat_id:*`, `chat_guid:*`).
|
||||
- `channels.bluebubbles.groupPolicy`: `open | allowlist | disabled` (bawaan: `allowlist`).
|
||||
- `channels.bluebubbles.groupPolicy`: `open | allowlist | disabled` (default: `allowlist`).
|
||||
- `channels.bluebubbles.groupAllowFrom`: Allowlist pengirim grup.
|
||||
- `channels.bluebubbles.enrichGroupParticipantsFromContacts`: Di macOS, secara opsional memperkaya peserta grup tanpa nama dari Kontak lokal setelah gating lulus. Bawaan: `false`.
|
||||
- `channels.bluebubbles.enrichGroupParticipantsFromContacts`: Di macOS, secara opsional perkaya peserta grup tanpa nama dari Kontak lokal setelah gating lolos. Default: `false`.
|
||||
- `channels.bluebubbles.groups`: Konfigurasi per grup (`requireMention`, dll.).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Pengiriman dan pemotongan">
|
||||
- `channels.bluebubbles.sendReadReceipts`: Kirim tanda sudah dibaca (default: `true`).
|
||||
- `channels.bluebubbles.sendReadReceipts`: Kirim tanda baca (default: `true`).
|
||||
- `channels.bluebubbles.blockStreaming`: Aktifkan streaming blok (default: `false`; diperlukan untuk balasan streaming).
|
||||
- `channels.bluebubbles.textChunkLimit`: Ukuran potongan keluar dalam karakter (default: 4000).
|
||||
- `channels.bluebubbles.sendTimeoutMs`: Timeout per permintaan dalam ms untuk pengiriman teks keluar melalui `/api/v1/message/text` (default: 30000). Naikkan pada penyiapan macOS 26 saat pengiriman iMessage Private API dapat tertahan selama 60+ detik di dalam framework iMessage; misalnya `45000` atau `60000`. Probe, pencarian chat, reaksi, edit, dan pemeriksaan kesehatan saat ini tetap memakai default 10 detik yang lebih pendek; perluasan cakupan ke reaksi dan edit direncanakan sebagai tindak lanjut. Override per akun: `channels.bluebubbles.accounts.<accountId>.sendTimeoutMs`.
|
||||
- `channels.bluebubbles.chunkMode`: `length` (default) membagi hanya saat melebihi `textChunkLimit`; `newline` membagi pada baris kosong (batas paragraf) sebelum pemotongan berdasarkan panjang.
|
||||
- `channels.bluebubbles.sendTimeoutMs`: Timeout per permintaan dalam ms untuk pengiriman teks keluar melalui `/api/v1/message/text` (default: 30000). Tingkatkan pada penyiapan macOS 26 ketika pengiriman iMessage Private API dapat tersendat selama 60+ detik di dalam framework iMessage; misalnya `45000` atau `60000`. Probe, pencarian chat, reaksi, edit, dan pemeriksaan kesehatan saat ini tetap memakai default 10 dtk yang lebih pendek; perluasan cakupan ke reaksi dan edit direncanakan sebagai tindak lanjut. Override per akun: `channels.bluebubbles.accounts.<accountId>.sendTimeoutMs`.
|
||||
- `channels.bluebubbles.chunkMode`: `length` (default) hanya memisahkan saat melebihi `textChunkLimit`; `newline` memisahkan pada baris kosong (batas paragraf) sebelum pemotongan berdasarkan panjang.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Media dan riwayat">
|
||||
- `channels.bluebubbles.mediaMaxMb`: Batas media masuk/keluar dalam MB (default: 8).
|
||||
- `channels.bluebubbles.mediaLocalRoots`: Allowlist eksplisit direktori lokal absolut yang diizinkan untuk jalur media lokal keluar. Pengiriman jalur lokal ditolak secara default kecuali ini dikonfigurasi. Override per akun: `channels.bluebubbles.accounts.<accountId>.mediaLocalRoots`.
|
||||
- `channels.bluebubbles.coalesceSameSenderDms`: Gabungkan Webhook DM berturut-turut dari pengirim yang sama menjadi satu giliran agen sehingga pengiriman terpisah teks+URL Apple tiba sebagai satu pesan (default: `false`). Lihat [Menggabungkan DM pengiriman terpisah](#coalescing-split-send-dms-command--url-in-one-composition) untuk skenario, penyesuaian jendela, dan trade-off. Memperlebar jendela debounce masuk default dari 500 ms menjadi 2500 ms saat diaktifkan tanpa `messages.inbound.byChannel.bluebubbles` eksplisit.
|
||||
- `channels.bluebubbles.mediaLocalRoots`: Daftar izin eksplisit direktori lokal absolut yang diizinkan untuk jalur media lokal keluar. Pengiriman jalur lokal ditolak secara default kecuali ini dikonfigurasi. Override per akun: `channels.bluebubbles.accounts.<accountId>.mediaLocalRoots`.
|
||||
- `channels.bluebubbles.coalesceSameSenderDms`: Gabungkan Webhook DM berturut-turut dari pengirim yang sama menjadi satu giliran agen sehingga pengiriman terpisah teks+URL dari Apple tiba sebagai satu pesan (default: `false`). Lihat [Menggabungkan DM pengiriman terpisah](#coalescing-split-send-dms-command--url-in-one-composition) untuk skenario, penyetelan jendela, dan komprominya. Memperlebar jendela debounce masuk default dari 500 md menjadi 2500 md saat diaktifkan tanpa `messages.inbound.byChannel.bluebubbles` eksplisit.
|
||||
- `channels.bluebubbles.historyLimit`: Pesan grup maksimum untuk konteks (0 menonaktifkan).
|
||||
- `channels.bluebubbles.dmHistoryLimit`: Batas riwayat DM.
|
||||
- `channels.bluebubbles.replyContextApiFallback`: Saat balasan masuk tiba tanpa `replyToBody`/`replyToSender` dan cache konteks balasan dalam memori tidak menemukan data, ambil pesan asli dari BlueBubbles HTTP API sebagai fallback upaya terbaik (default: `false`). Berguna untuk deployment multi-instans yang berbagi satu akun BlueBubbles, setelah proses dimulai ulang, atau setelah pengusiran cache TTL/LRU yang berumur panjang. Pengambilan dilindungi SSRF oleh kebijakan yang sama seperti setiap permintaan klien BlueBubbles lainnya, tidak pernah melempar error, dan mengisi cache sehingga balasan berikutnya teramortisasi. Override per akun: `channels.bluebubbles.accounts.<accountId>.replyContextApiFallback`. Pengaturan tingkat channel diterapkan ke akun yang tidak menyertakan flag tersebut.
|
||||
- `channels.bluebubbles.replyContextApiFallback`: Saat balasan masuk tiba tanpa `replyToBody`/`replyToSender` dan cache konteks balasan dalam memori tidak ditemukan, ambil pesan asli dari API HTTP BlueBubbles sebagai fallback upaya-terbaik (default: `false`). Berguna untuk deployment multi-instans yang berbagi satu akun BlueBubbles, setelah proses dimulai ulang, atau setelah pengusiran cache TTL/LRU berumur panjang. Pengambilan dilindungi SSRF oleh kebijakan yang sama seperti setiap permintaan klien BlueBubbles lainnya, tidak pernah melempar error, dan mengisi cache sehingga balasan berikutnya teramortisasi. Override per akun: `channels.bluebubbles.accounts.<accountId>.replyContextApiFallback`. Pengaturan tingkat channel diteruskan ke akun yang tidak menetapkan flag tersebut.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Tindakan dan akun">
|
||||
@ -603,9 +595,9 @@ Opsi global terkait:
|
||||
- `agents.list[].groupChat.mentionPatterns` (atau `messages.groupChat.mentionPatterns`).
|
||||
- `messages.responsePrefix`.
|
||||
|
||||
## Alamat / target pengiriman
|
||||
## Target alamat / pengiriman
|
||||
|
||||
Utamakan `chat_guid` untuk routing yang stabil:
|
||||
Utamakan `chat_guid` untuk perutean stabil:
|
||||
|
||||
- `chat_guid:iMessage;-;+15555550123` (disarankan untuk grup)
|
||||
- `chat_id:123`
|
||||
@ -613,34 +605,34 @@ Utamakan `chat_guid` untuk routing yang stabil:
|
||||
- Handle langsung: `+15555550123`, `user@example.com`
|
||||
- Jika handle langsung tidak memiliki chat DM yang sudah ada, OpenClaw akan membuatnya melalui `POST /api/v1/chat/new`. Ini mengharuskan BlueBubbles Private API diaktifkan.
|
||||
|
||||
### Routing iMessage vs SMS
|
||||
### Perutean iMessage vs SMS
|
||||
|
||||
Saat handle yang sama memiliki chat iMessage dan SMS di Mac (misalnya nomor telepon yang terdaftar di iMessage tetapi juga pernah menerima fallback gelembung hijau), OpenClaw mengutamakan chat iMessage dan tidak pernah diam-diam menurunkan ke SMS. Untuk memaksa chat SMS, gunakan awalan target `sms:` eksplisit (misalnya `sms:+15555550123`). Handle tanpa chat iMessage yang cocok tetap mengirim melalui chat apa pun yang dilaporkan BlueBubbles.
|
||||
Saat handle yang sama memiliki chat iMessage dan SMS di Mac (misalnya nomor telepon yang terdaftar di iMessage tetapi juga pernah menerima fallback gelembung hijau), OpenClaw mengutamakan chat iMessage dan tidak pernah diam-diam menurunkan ke SMS. Untuk memaksa chat SMS, gunakan prefiks target `sms:` eksplisit (misalnya `sms:+15555550123`). Handle tanpa chat iMessage yang cocok tetap dikirim melalui chat apa pun yang dilaporkan BlueBubbles.
|
||||
|
||||
## Keamanan
|
||||
|
||||
- Permintaan Webhook diautentikasi dengan membandingkan param kueri atau header `guid`/`password` dengan `channels.bluebubbles.password`.
|
||||
- Jaga kerahasiaan kata sandi API dan endpoint Webhook (perlakukan seperti kredensial).
|
||||
- Tidak ada bypass localhost untuk autentikasi Webhook BlueBubbles. Jika Anda mem-proxy traffic Webhook, pertahankan kata sandi BlueBubbles pada permintaan dari awal sampai akhir. `gateway.trustedProxies` tidak menggantikan `channels.bluebubbles.password` di sini. Lihat [Keamanan Gateway](/id/gateway/security#reverse-proxy-configuration).
|
||||
- Aktifkan HTTPS + aturan firewall pada server BlueBubbles jika mengeksposnya di luar LAN Anda.
|
||||
- Tidak ada bypass localhost untuk autentikasi Webhook BlueBubbles. Jika Anda mem-proxy traffic Webhook, pertahankan kata sandi BlueBubbles pada permintaan dari ujung ke ujung. `gateway.trustedProxies` tidak menggantikan `channels.bluebubbles.password` di sini. Lihat [Keamanan Gateway](/id/gateway/security#reverse-proxy-configuration).
|
||||
- Aktifkan aturan HTTPS + firewall pada server BlueBubbles jika mengeksposnya di luar LAN Anda.
|
||||
|
||||
## Pemecahan masalah
|
||||
|
||||
- Jika event mengetik/sudah dibaca berhenti berfungsi, periksa log Webhook BlueBubbles dan verifikasi jalur gateway cocok dengan `channels.bluebubbles.webhookPath`.
|
||||
- Kode pairing kedaluwarsa setelah satu jam; gunakan `openclaw pairing list bluebubbles` dan `openclaw pairing approve bluebubbles <code>`.
|
||||
- Reaksi memerlukan private API BlueBubbles (`POST /api/v1/message/react`); pastikan versi server mengeksposnya.
|
||||
- Edit/batal kirim memerlukan macOS 13+ dan versi server BlueBubbles yang kompatibel. Di macOS 26 (Tahoe), edit saat ini rusak karena perubahan private API.
|
||||
- Pembaruan ikon grup dapat tidak stabil di macOS 26 (Tahoe): API mungkin mengembalikan sukses tetapi ikon baru tidak tersinkron.
|
||||
- OpenClaw otomatis menyembunyikan tindakan yang diketahui rusak berdasarkan versi macOS server BlueBubbles. Jika edit masih muncul di macOS 26 (Tahoe), nonaktifkan secara manual dengan `channels.bluebubbles.actions.edit=false`.
|
||||
- `coalesceSameSenderDms` diaktifkan tetapi pengiriman terpisah (misalnya `Dump` + URL) masih tiba sebagai dua giliran: lihat daftar periksa [pemecahan masalah penggabungan pengiriman terpisah](#split-send-coalescing-troubleshooting) — penyebab umum adalah jendela debounce yang terlalu ketat, timestamp log sesi yang keliru dibaca sebagai kedatangan Webhook, atau pengiriman kutipan balasan (yang memakai `replyToBody`, bukan Webhook kedua).
|
||||
- Jika event mengetik/membaca berhenti berfungsi, periksa log Webhook BlueBubbles dan pastikan jalur Gateway cocok dengan `channels.bluebubbles.webhookPath`.
|
||||
- Kode pemasangan kedaluwarsa setelah satu jam; gunakan `openclaw pairing list bluebubbles` dan `openclaw pairing approve bluebubbles <code>`.
|
||||
- Reaksi memerlukan API privat BlueBubbles (`POST /api/v1/message/react`); pastikan versi server mengeksposnya.
|
||||
- Edit/batalkan kirim memerlukan macOS 13+ dan versi server BlueBubbles yang kompatibel. Pada macOS 26 (Tahoe), edit saat ini rusak karena perubahan API privat.
|
||||
- Pembaruan ikon grup dapat tidak stabil pada macOS 26 (Tahoe): API mungkin mengembalikan sukses tetapi ikon baru tidak tersinkron.
|
||||
- OpenClaw otomatis menyembunyikan tindakan yang diketahui rusak berdasarkan versi macOS server BlueBubbles. Jika edit masih muncul pada macOS 26 (Tahoe), nonaktifkan secara manual dengan `channels.bluebubbles.actions.edit=false`.
|
||||
- `coalesceSameSenderDms` diaktifkan tetapi pengiriman terpisah (mis. `Dump` + URL) masih tiba sebagai dua giliran: lihat checklist [pemecahan masalah penggabungan pengiriman terpisah](#split-send-coalescing-troubleshooting) — penyebab umum adalah jendela debounce terlalu ketat, timestamp log sesi keliru dibaca sebagai kedatangan Webhook, atau pengiriman kutipan balasan (yang memakai `replyToBody`, bukan Webhook kedua).
|
||||
- Untuk info status/kesehatan: `openclaw status --all` atau `openclaw status --deep`.
|
||||
|
||||
Untuk referensi alur kerja channel umum, lihat [Channel](/id/channels) dan panduan [Plugins](/id/tools/plugin).
|
||||
|
||||
## Terkait
|
||||
|
||||
- [Routing Channel](/id/channels/channel-routing) — routing sesi untuk pesan
|
||||
- [Perutean Channel](/id/channels/channel-routing) — perutean sesi untuk pesan
|
||||
- [Ikhtisar Channel](/id/channels) — semua channel yang didukung
|
||||
- [Grup](/id/channels/groups) — perilaku chat grup dan gating mention
|
||||
- [Pairing](/id/channels/pairing) — autentikasi DM dan alur pairing
|
||||
- [Grup](/id/channels/groups) — perilaku chat grup dan gating sebutan
|
||||
- [Pemasangan](/id/channels/pairing) — autentikasi DM dan alur pemasangan
|
||||
- [Keamanan](/id/gateway/security) — model akses dan hardening
|
||||
|
||||
@ -1,16 +1,16 @@
|
||||
---
|
||||
read_when:
|
||||
- Mengonfigurasi grup siaran
|
||||
- Pemecahan masalah balasan multi-agen di WhatsApp
|
||||
- Men-debug balasan multi-agen di WhatsApp
|
||||
sidebarTitle: Broadcast groups
|
||||
status: experimental
|
||||
summary: Siarkan pesan WhatsApp ke beberapa agen
|
||||
title: Grup siaran
|
||||
x-i18n:
|
||||
generated_at: "2026-04-30T09:32:44Z"
|
||||
generated_at: "2026-05-04T02:21:36Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: b0de4ccc85bf79e2ceb1dddd60db067309b15b7f876c92e7d591ff0b4b4315ec
|
||||
source_hash: eab43d3c3ffddb360340469433d74a380fbab98e662b2463a54f62eafc375b55
|
||||
source_path: channels/broadcast-groups.md
|
||||
workflow: 16
|
||||
---
|
||||
@ -19,19 +19,19 @@ x-i18n:
|
||||
**Status:** Eksperimental. Ditambahkan pada 2026.1.9.
|
||||
</Note>
|
||||
|
||||
## Ikhtisar
|
||||
## Gambaran umum
|
||||
|
||||
Grup broadcast memungkinkan beberapa agen memproses dan merespons pesan yang sama secara bersamaan. Ini memungkinkan Anda membuat tim agen khusus yang bekerja bersama dalam satu grup WhatsApp atau DM — semuanya menggunakan satu nomor telepon.
|
||||
Grup Broadcast memungkinkan beberapa agen memproses dan merespons pesan yang sama secara bersamaan. Ini memungkinkan Anda membuat tim agen terspesialisasi yang bekerja bersama dalam satu grup WhatsApp atau DM — semuanya menggunakan satu nomor telepon.
|
||||
|
||||
Cakupan saat ini: **hanya WhatsApp** (kanal web).
|
||||
|
||||
Grup broadcast dievaluasi setelah daftar izin kanal dan aturan aktivasi grup. Di grup WhatsApp, ini berarti broadcast terjadi ketika OpenClaw biasanya akan membalas (misalnya: saat disebut, tergantung pengaturan grup Anda).
|
||||
Grup broadcast dievaluasi setelah daftar izin kanal dan aturan aktivasi grup. Di grup WhatsApp, ini berarti broadcast terjadi ketika OpenClaw biasanya akan membalas (misalnya: saat disebut, bergantung pada pengaturan grup Anda).
|
||||
|
||||
## Kasus penggunaan
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="1. Tim agen khusus">
|
||||
Jalankan beberapa agen dengan tanggung jawab yang atomik dan terfokus:
|
||||
<Accordion title="1. Tim agen terspesialisasi">
|
||||
Terapkan beberapa agen dengan tanggung jawab yang atomik dan terfokus:
|
||||
|
||||
```
|
||||
Group: "Development Team"
|
||||
@ -42,7 +42,7 @@ Grup broadcast dievaluasi setelah daftar izin kanal dan aturan aktivasi grup. Di
|
||||
- TestGenerator (suggests test cases)
|
||||
```
|
||||
|
||||
Setiap agen memproses pesan yang sama dan memberikan perspektif khususnya.
|
||||
Setiap agen memproses pesan yang sama dan memberikan perspektif terspesialisasinya.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2. Dukungan multi-bahasa">
|
||||
@ -77,7 +77,7 @@ Grup broadcast dievaluasi setelah daftar izin kanal dan aturan aktivasi grup. Di
|
||||
|
||||
### Penyiapan dasar
|
||||
|
||||
Tambahkan bagian `broadcast` tingkat atas (di samping `bindings`). Kunci adalah ID peer WhatsApp:
|
||||
Tambahkan bagian `broadcast` tingkat atas (di sebelah `bindings`). Kunci adalah ID peer WhatsApp:
|
||||
|
||||
- chat grup: JID grup (mis. `120363403215116621@g.us`)
|
||||
- DM: nomor telepon E.164 (mis. `+15551234567`)
|
||||
@ -97,7 +97,7 @@ Tambahkan bagian `broadcast` tingkat atas (di samping `bindings`). Kunci adalah
|
||||
Kontrol cara agen memproses pesan:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="paralel (default)">
|
||||
<Tab title="parallel (default)">
|
||||
Semua agen memproses secara bersamaan:
|
||||
|
||||
```json
|
||||
@ -110,8 +110,8 @@ Kontrol cara agen memproses pesan:
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab title="berurutan">
|
||||
Agen memproses sesuai urutan (satu agen menunggu agen sebelumnya selesai):
|
||||
<Tab title="sequential">
|
||||
Agen memproses secara berurutan (satu menunggu yang sebelumnya selesai):
|
||||
|
||||
```json
|
||||
{
|
||||
@ -183,12 +183,12 @@ Kontrol cara agen memproses pesan:
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
Grup broadcast tidak melewati daftar izin kanal atau aturan aktivasi grup (sebutan/perintah/dll.). Grup broadcast hanya mengubah _agen mana yang berjalan_ ketika sebuah pesan memenuhi syarat untuk diproses.
|
||||
Grup broadcast tidak melewati daftar izin kanal atau aturan aktivasi grup (sebutan/perintah/dll). Grup broadcast hanya mengubah _agen mana yang berjalan_ ketika sebuah pesan memenuhi syarat untuk diproses.
|
||||
</Note>
|
||||
|
||||
### Isolasi sesi
|
||||
|
||||
Setiap agen dalam grup broadcast mempertahankan hal berikut secara sepenuhnya terpisah:
|
||||
Setiap agen dalam grup broadcast mempertahankan hal-hal yang sepenuhnya terpisah:
|
||||
|
||||
- **Kunci sesi** (`agent:alfred:whatsapp:group:120363...` vs `agent:baerbel:whatsapp:group:120363...`)
|
||||
- **Riwayat percakapan** (agen tidak melihat pesan agen lain)
|
||||
@ -200,9 +200,9 @@ Setiap agen dalam grup broadcast mempertahankan hal berikut secara sepenuhnya te
|
||||
Ini memungkinkan setiap agen memiliki:
|
||||
|
||||
- Kepribadian berbeda
|
||||
- Akses alat berbeda (mis., hanya baca vs. baca-tulis)
|
||||
- Akses alat berbeda (mis., hanya-baca vs. baca-tulis)
|
||||
- Model berbeda (mis., opus vs. sonnet)
|
||||
- Skills berbeda yang terpasang
|
||||
- Skills berbeda yang terinstal
|
||||
|
||||
### Contoh: sesi terisolasi
|
||||
|
||||
@ -241,11 +241,11 @@ Di grup `120363403215116621@g.us` dengan agen `["alfred", "baerbel"]`:
|
||||
}
|
||||
```
|
||||
|
||||
✅ **Baik:** Setiap agen memiliki satu pekerjaan. ❌ **Buruk:** Satu agen "dev-helper" generik.
|
||||
✅ **Baik:** Setiap agen memiliki satu tugas. ❌ **Buruk:** Satu agen generik "dev-helper".
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2. Gunakan nama deskriptif">
|
||||
Buat agar jelas apa yang dilakukan setiap agen:
|
||||
<Accordion title="2. Gunakan nama yang deskriptif">
|
||||
Buat jelas apa yang dilakukan setiap agen:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -259,27 +259,29 @@ Di grup `120363403215116621@g.us` dengan agen `["alfred", "baerbel"]`:
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="3. Konfigurasikan akses alat yang berbeda">
|
||||
Berikan agen hanya alat yang mereka butuhkan:
|
||||
Berikan agen hanya alat yang mereka perlukan:
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"reviewer": {
|
||||
"tools": { "allow": ["read", "exec"] } // Read-only
|
||||
"tools": { "allow": ["read", "exec"] }
|
||||
},
|
||||
"fixer": {
|
||||
"tools": { "allow": ["read", "write", "edit", "exec"] } // Read-write
|
||||
"tools": { "allow": ["read", "write", "edit", "exec"] }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`reviewer` bersifat hanya-baca. `fixer` dapat membaca dan menulis.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="4. Pantau performa">
|
||||
Dengan banyak agen, pertimbangkan:
|
||||
|
||||
- Menggunakan `"strategy": "parallel"` (default) untuk kecepatan
|
||||
- Membatasi grup broadcast menjadi 5-10 agen
|
||||
- Membatasi grup broadcast hingga 5-10 agen
|
||||
- Menggunakan model yang lebih cepat untuk agen yang lebih sederhana
|
||||
|
||||
</Accordion>
|
||||
@ -307,7 +309,7 @@ Grup broadcast saat ini berfungsi dengan:
|
||||
|
||||
### Perutean
|
||||
|
||||
Grup broadcast bekerja berdampingan dengan perutean yang sudah ada:
|
||||
Grup broadcast bekerja bersama perutean yang sudah ada:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -327,7 +329,7 @@ Grup broadcast bekerja berdampingan dengan perutean yang sudah ada:
|
||||
- `GROUP_B`: agent1 DAN agent2 merespons (broadcast).
|
||||
|
||||
<Note>
|
||||
**Presedensi:** `broadcast` memiliki prioritas atas `bindings`.
|
||||
**Prioritas:** `broadcast` memiliki prioritas lebih tinggi daripada `bindings`.
|
||||
</Note>
|
||||
|
||||
## Pemecahan masalah
|
||||
@ -408,7 +410,7 @@ Grup broadcast bekerja berdampingan dengan perutean yang sudah ada:
|
||||
- code-formatter: "Memperbaiki indentasi dan menambahkan petunjuk tipe"
|
||||
- security-scanner: "⚠️ Kerentanan injeksi SQL di baris 12"
|
||||
- test-coverage: "Cakupan 45%, kurang pengujian untuk kasus kesalahan"
|
||||
- docs-checker: "Docstring tidak ada untuk fungsi `process_data`"
|
||||
- docs-checker: "Docstring hilang untuk fungsi `process_data`"
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Contoh 2: Dukungan multi-bahasa">
|
||||
@ -459,19 +461,19 @@ interface OpenClawConfig {
|
||||
3. **Urutan pesan:** Respons paralel dapat tiba dalam urutan apa pun.
|
||||
4. **Batas laju:** Semua agen dihitung terhadap batas laju WhatsApp.
|
||||
|
||||
## Penyempurnaan mendatang
|
||||
## Peningkatan mendatang
|
||||
|
||||
Fitur yang direncanakan:
|
||||
|
||||
- [ ] Mode konteks bersama (agen melihat respons satu sama lain)
|
||||
- [ ] Koordinasi agen (agen dapat saling memberi sinyal)
|
||||
- [ ] Koordinasi agen (agen dapat memberi sinyal satu sama lain)
|
||||
- [ ] Pemilihan agen dinamis (memilih agen berdasarkan konten pesan)
|
||||
- [ ] Prioritas agen (sebagian agen merespons sebelum yang lain)
|
||||
- [ ] Prioritas agen (beberapa agen merespons sebelum yang lain)
|
||||
|
||||
## Terkait
|
||||
|
||||
- [Perutean saluran](/id/channels/channel-routing)
|
||||
- [Grup](/id/channels/groups)
|
||||
- [Alat sandbox multi-agen](/id/tools/multi-agent-sandbox-tools)
|
||||
- [Pemasangan](/id/channels/pairing)
|
||||
- [Penyandingan](/id/channels/pairing)
|
||||
- [Manajemen sesi](/id/concepts/session)
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -4,25 +4,25 @@ read_when:
|
||||
summary: Status dukungan, kemampuan, dan konfigurasi aplikasi Google Chat
|
||||
title: Google Chat
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T09:12:37Z"
|
||||
generated_at: "2026-05-04T02:21:26Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: fdb8dcf651602e92801d7107646d853871ea6cef188a8733a831695a1243740e
|
||||
source_hash: afa2ca4d9673396aa24a55ca5855a34ad26a4640c3a1f6928dbf7246e403cb04
|
||||
source_path: channels/googlechat.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Status: Plugin yang dapat diunduh untuk DM + ruang melalui Webhook Google Chat API (hanya HTTP).
|
||||
|
||||
## Instalasi
|
||||
## Instal
|
||||
|
||||
Instal Google Chat sebelum mengonfigurasi channel:
|
||||
Instal Google Chat sebelum mengonfigurasi saluran:
|
||||
|
||||
```bash
|
||||
openclaw plugins install @openclaw/googlechat
|
||||
```
|
||||
|
||||
Checkout lokal (saat dijalankan dari repo git):
|
||||
Checkout lokal (saat menjalankan dari repo git):
|
||||
|
||||
```bash
|
||||
openclaw plugins install ./path/to/local/googlechat-plugin
|
||||
@ -35,11 +35,11 @@ openclaw plugins install ./path/to/local/googlechat-plugin
|
||||
- Aktifkan API jika belum aktif.
|
||||
2. Buat **Service Account**:
|
||||
- Tekan **Create Credentials** > **Service Account**.
|
||||
- Beri nama sesuai keinginan Anda (misalnya, `openclaw-chat`).
|
||||
- Beri nama apa pun yang Anda inginkan (misalnya, `openclaw-chat`).
|
||||
- Biarkan izin kosong (tekan **Continue**).
|
||||
- Biarkan principal dengan akses kosong (tekan **Done**).
|
||||
- Biarkan prinsipal dengan akses kosong (tekan **Done**).
|
||||
3. Buat dan unduh **JSON Key**:
|
||||
- Di daftar service account, klik akun yang baru Anda buat.
|
||||
- Dalam daftar service account, klik yang baru saja Anda buat.
|
||||
- Buka tab **Keys**.
|
||||
- Klik **Add Key** > **Create new key**.
|
||||
- Pilih **JSON** dan tekan **Create**.
|
||||
@ -53,7 +53,7 @@ openclaw plugins install ./path/to/local/googlechat-plugin
|
||||
- Di bawah **Functionality**, centang **Join spaces and group conversations**.
|
||||
- Di bawah **Connection settings**, pilih **HTTP endpoint URL**.
|
||||
- Di bawah **Triggers**, pilih **Use a common HTTP endpoint URL for all triggers** dan atur ke URL publik Gateway Anda diikuti dengan `/googlechat`.
|
||||
- _Kiat: Jalankan `openclaw status` untuk menemukan URL publik Gateway Anda._
|
||||
- _Tips: Jalankan `openclaw status` untuk menemukan URL publik Gateway Anda._
|
||||
- Di bawah **Visibility**, centang **Make this Chat app available to specific people and groups in `<Your Domain>`**.
|
||||
- Masukkan alamat email Anda (misalnya `user@example.com`) di kotak teks.
|
||||
- Klik **Save** di bagian bawah.
|
||||
@ -62,33 +62,33 @@ openclaw plugins install ./path/to/local/googlechat-plugin
|
||||
- Cari bagian **App status** (biasanya di dekat bagian atas atau bawah setelah menyimpan).
|
||||
- Ubah status menjadi **Live - available to users**.
|
||||
- Klik **Save** lagi.
|
||||
7. Konfigurasi OpenClaw dengan path service account + audiens Webhook:
|
||||
7. Konfigurasikan OpenClaw dengan jalur service account + audiens Webhook:
|
||||
- Env: `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json`
|
||||
- Atau config: `channels.googlechat.serviceAccountFile: "/path/to/service-account.json"`.
|
||||
8. Atur jenis + nilai audiens Webhook (sesuai dengan config aplikasi Chat Anda).
|
||||
9. Mulai Gateway. Google Chat akan melakukan POST ke path Webhook Anda.
|
||||
- Atau konfigurasi: `channels.googlechat.serviceAccountFile: "/path/to/service-account.json"`.
|
||||
8. Atur jenis + nilai audiens Webhook (sesuai dengan konfigurasi aplikasi Chat Anda).
|
||||
9. Mulai Gateway. Google Chat akan melakukan POST ke jalur Webhook Anda.
|
||||
|
||||
## Tambahkan ke Google Chat
|
||||
|
||||
Setelah Gateway berjalan dan email Anda ditambahkan ke daftar visibilitas:
|
||||
|
||||
1. Buka [Google Chat](https://chat.google.com/).
|
||||
2. Klik ikon **+** (plus) di sebelah **Direct Messages**.
|
||||
3. Di bilah pencarian (tempat Anda biasanya menambahkan orang), ketik **App name** yang Anda konfigurasi di Google Cloud Console.
|
||||
- **Catatan**: Bot _tidak_ akan muncul di daftar jelajah "Marketplace" karena ini adalah aplikasi privat. Anda harus mencarinya berdasarkan nama.
|
||||
2. Klik ikon **+** (plus) di samping **Direct Messages**.
|
||||
3. Di bilah pencarian (tempat Anda biasanya menambahkan orang), ketik **App name** yang Anda konfigurasikan di Google Cloud Console.
|
||||
- **Catatan**: Bot _tidak_ akan muncul dalam daftar jelajah "Marketplace" karena ini adalah aplikasi pribadi. Anda harus mencarinya berdasarkan nama.
|
||||
4. Pilih bot Anda dari hasil.
|
||||
5. Klik **Add** atau **Chat** untuk memulai percakapan 1:1.
|
||||
6. Kirim "Halo" untuk memicu asisten!
|
||||
6. Kirim "Hello" untuk memicu asisten!
|
||||
|
||||
## URL Publik (khusus Webhook)
|
||||
## URL publik (khusus Webhook)
|
||||
|
||||
Webhook Google Chat memerlukan endpoint HTTPS publik. Untuk keamanan, **hanya ekspos path `/googlechat`** ke internet. Biarkan dasbor OpenClaw dan endpoint sensitif lainnya tetap berada di jaringan privat Anda.
|
||||
Webhook Google Chat memerlukan endpoint HTTPS publik. Untuk keamanan, **hanya ekspos jalur `/googlechat`** ke internet. Pertahankan dasbor OpenClaw dan endpoint sensitif lainnya di jaringan pribadi Anda.
|
||||
|
||||
### Opsi A: Tailscale Funnel (Direkomendasikan)
|
||||
|
||||
Gunakan Tailscale Serve untuk dasbor privat dan Funnel untuk path Webhook publik. Ini membuat `/` tetap privat sambil hanya mengekspos `/googlechat`.
|
||||
Gunakan Tailscale Serve untuk dasbor pribadi dan Funnel untuk jalur Webhook publik. Ini menjaga `/` tetap pribadi sambil hanya mengekspos `/googlechat`.
|
||||
|
||||
1. **Periksa alamat tempat Gateway Anda terikat:**
|
||||
1. **Periksa alamat apa yang digunakan Gateway Anda untuk bind:**
|
||||
|
||||
```bash
|
||||
ss -tlnp | grep 18789
|
||||
@ -106,7 +106,7 @@ Gunakan Tailscale Serve untuk dasbor privat dan Funnel untuk path Webhook publik
|
||||
tailscale serve --bg --https 8443 http://100.106.161.80:18789
|
||||
```
|
||||
|
||||
3. **Ekspos hanya path Webhook secara publik:**
|
||||
3. **Ekspos hanya jalur Webhook secara publik:**
|
||||
|
||||
```bash
|
||||
# If bound to localhost (127.0.0.1 or 0.0.0.0):
|
||||
@ -116,8 +116,8 @@ Gunakan Tailscale Serve untuk dasbor privat dan Funnel untuk path Webhook publik
|
||||
tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat
|
||||
```
|
||||
|
||||
4. **Otorisasi node untuk akses Funnel:**
|
||||
Jika diminta, kunjungi URL otorisasi yang ditampilkan di output untuk mengaktifkan Funnel bagi node ini dalam kebijakan tailnet Anda.
|
||||
4. **Otorisasi Node untuk akses Funnel:**
|
||||
Jika diminta, kunjungi URL otorisasi yang ditampilkan dalam output untuk mengaktifkan Funnel bagi Node ini dalam kebijakan tailnet Anda.
|
||||
|
||||
5. **Verifikasi konfigurasi:**
|
||||
|
||||
@ -129,16 +129,16 @@ Gunakan Tailscale Serve untuk dasbor privat dan Funnel untuk path Webhook publik
|
||||
URL Webhook publik Anda adalah:
|
||||
`https://<node-name>.<tailnet>.ts.net/googlechat`
|
||||
|
||||
Dasbor privat Anda tetap hanya untuk tailnet:
|
||||
Dasbor pribadi Anda tetap hanya untuk tailnet:
|
||||
`https://<node-name>.<tailnet>.ts.net:8443/`
|
||||
|
||||
Gunakan URL publik (tanpa `:8443`) dalam config aplikasi Google Chat.
|
||||
Gunakan URL publik (tanpa `:8443`) dalam konfigurasi aplikasi Google Chat.
|
||||
|
||||
> Catatan: Konfigurasi ini bertahan setelah reboot. Untuk menghapusnya nanti, jalankan `tailscale funnel reset` dan `tailscale serve reset`.
|
||||
> Catatan: Konfigurasi ini tetap ada setelah reboot. Untuk menghapusnya nanti, jalankan `tailscale funnel reset` dan `tailscale serve reset`.
|
||||
|
||||
### Opsi B: Reverse Proxy (Caddy)
|
||||
### Opsi B: Proxy balik (Caddy)
|
||||
|
||||
Jika Anda menggunakan reverse proxy seperti Caddy, proxy hanya path tertentu:
|
||||
Jika Anda menggunakan proxy balik seperti Caddy, hanya proksikan jalur tertentu:
|
||||
|
||||
```caddy
|
||||
your-domain.com {
|
||||
@ -146,27 +146,27 @@ your-domain.com {
|
||||
}
|
||||
```
|
||||
|
||||
Dengan config ini, permintaan apa pun ke `your-domain.com/` akan diabaikan atau dikembalikan sebagai 404, sementara `your-domain.com/googlechat` diarahkan dengan aman ke OpenClaw.
|
||||
Dengan konfigurasi ini, setiap permintaan ke `your-domain.com/` akan diabaikan atau dikembalikan sebagai 404, sementara `your-domain.com/googlechat` dirutekan dengan aman ke OpenClaw.
|
||||
|
||||
### Opsi C: Cloudflare Tunnel
|
||||
|
||||
Konfigurasikan aturan ingress tunnel Anda untuk hanya merutekan path Webhook:
|
||||
Konfigurasikan aturan ingress tunnel Anda untuk hanya merutekan jalur Webhook:
|
||||
|
||||
- **Path**: `/googlechat` -> `http://localhost:18789/googlechat`
|
||||
- **Default Rule**: HTTP 404 (Not Found)
|
||||
- **Jalur**: `/googlechat` -> `http://localhost:18789/googlechat`
|
||||
- **Aturan Default**: HTTP 404 (Tidak Ditemukan)
|
||||
|
||||
## Cara kerjanya
|
||||
|
||||
1. Google Chat mengirim POST Webhook ke Gateway. Setiap permintaan menyertakan header `Authorization: Bearer <token>`.
|
||||
- OpenClaw memverifikasi autentikasi bearer sebelum membaca/mengurai body Webhook penuh saat header ada.
|
||||
- Permintaan Google Workspace Add-on yang membawa `authorizationEventObject.systemIdToken` dalam body didukung melalui anggaran body pra-autentikasi yang lebih ketat.
|
||||
- OpenClaw memverifikasi autentikasi bearer sebelum membaca/mem-parse seluruh isi Webhook saat header ada.
|
||||
- Permintaan Google Workspace Add-on yang membawa `authorizationEventObject.systemIdToken` dalam body didukung melalui anggaran body praautentikasi yang lebih ketat.
|
||||
2. OpenClaw memverifikasi token terhadap `audienceType` + `audience` yang dikonfigurasi:
|
||||
- `audienceType: "app-url"` → audiens adalah URL Webhook HTTPS Anda.
|
||||
- `audienceType: "project-number"` → audiens adalah nomor proyek Cloud.
|
||||
3. Pesan dirutekan berdasarkan ruang:
|
||||
- DM menggunakan kunci sesi `agent:<agentId>:googlechat:direct:<spaceId>`.
|
||||
- Ruang menggunakan kunci sesi `agent:<agentId>:googlechat:group:<spaceId>`.
|
||||
4. Akses DM menggunakan pairing secara default. Pengirim yang tidak dikenal menerima kode pairing; setujui dengan:
|
||||
4. Akses DM secara default menggunakan pairing. Pengirim yang tidak dikenal menerima kode pairing; setujui dengan:
|
||||
- `openclaw pairing approve googlechat <code>`
|
||||
5. Ruang grup memerlukan @-mention secara default. Gunakan `botUser` jika deteksi mention memerlukan nama pengguna aplikasi.
|
||||
|
||||
@ -176,10 +176,10 @@ Gunakan pengenal ini untuk pengiriman dan allowlist:
|
||||
|
||||
- Pesan langsung: `users/<userId>` (direkomendasikan).
|
||||
- Email mentah `name@example.com` dapat berubah dan hanya digunakan untuk pencocokan allowlist langsung saat `channels.googlechat.dangerouslyAllowNameMatching: true`.
|
||||
- Tidak digunakan lagi: `users/<email>` diperlakukan sebagai id pengguna, bukan allowlist email.
|
||||
- Usang: `users/<email>` diperlakukan sebagai id pengguna, bukan allowlist email.
|
||||
- Ruang: `spaces/<spaceId>`.
|
||||
|
||||
## Sorotan config
|
||||
## Sorotan konfigurasi
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -199,7 +199,7 @@ Gunakan pengenal ini untuk pengiriman dan allowlist:
|
||||
groupPolicy: "allowlist",
|
||||
groups: {
|
||||
"spaces/AAAA": {
|
||||
allow: true,
|
||||
enabled: true,
|
||||
requireMention: true,
|
||||
users: ["users/1234567890"],
|
||||
systemPrompt: "Short answers only.",
|
||||
@ -217,20 +217,20 @@ Catatan:
|
||||
|
||||
- Kredensial service account juga dapat diteruskan secara inline dengan `serviceAccount` (string JSON).
|
||||
- `serviceAccountRef` juga didukung (env/file SecretRef), termasuk ref per akun di bawah `channels.googlechat.accounts.<id>.serviceAccountRef`.
|
||||
- Path Webhook default adalah `/googlechat` jika `webhookPath` tidak diatur.
|
||||
- `dangerouslyAllowNameMatching` mengaktifkan kembali pencocokan principal email yang dapat berubah untuk allowlist (mode kompatibilitas break-glass).
|
||||
- Jalur Webhook default adalah `/googlechat` jika `webhookPath` tidak diatur.
|
||||
- `dangerouslyAllowNameMatching` mengaktifkan kembali pencocokan prinsipal email yang dapat berubah untuk allowlist (mode kompatibilitas break-glass).
|
||||
- Reaksi tersedia melalui tool `reactions` dan `channels action` saat `actions.reactions` diaktifkan.
|
||||
- Aksi pesan mengekspos `send` untuk teks dan `upload-file` untuk pengiriman lampiran eksplisit. `upload-file` menerima `media` / `filePath` / `path` plus `message`, `filename`, dan target thread opsional.
|
||||
- `typingIndicator` mendukung `none`, `message` (default), dan `reaction` (reaksi memerlukan OAuth pengguna).
|
||||
- Aksi pesan mengekspos `send` untuk teks dan `upload-file` untuk pengiriman lampiran eksplisit. `upload-file` menerima `media` / `filePath` / `path` ditambah `message`, `filename`, dan penargetan thread opsional.
|
||||
- `typingIndicator` mendukung `none`, `message` (default), dan `reaction` (`reaction` memerlukan OAuth pengguna).
|
||||
- Lampiran diunduh melalui Chat API dan disimpan dalam pipeline media (ukuran dibatasi oleh `mediaMaxMb`).
|
||||
|
||||
Detail referensi rahasia: [Manajemen Rahasia](/id/gateway/secrets).
|
||||
|
||||
## Pemecahan masalah
|
||||
|
||||
### 405 Method Not Allowed
|
||||
### 405 Metode Tidak Diizinkan
|
||||
|
||||
Jika Google Cloud Logs Explorer menampilkan error seperti:
|
||||
Jika Google Cloud Logs Explorer menampilkan kesalahan seperti:
|
||||
|
||||
```
|
||||
status code: 405, reason phrase: HTTP error response: HTTP/1.1 405 Method Not Allowed
|
||||
@ -238,29 +238,29 @@ status code: 405, reason phrase: HTTP error response: HTTP/1.1 405 Method Not Al
|
||||
|
||||
Ini berarti handler Webhook tidak terdaftar. Penyebab umum:
|
||||
|
||||
1. **Channel tidak dikonfigurasi**: Bagian `channels.googlechat` hilang dari config Anda. Verifikasi dengan:
|
||||
1. **Saluran belum dikonfigurasi**: Bagian `channels.googlechat` hilang dari konfigurasi Anda. Verifikasi dengan:
|
||||
|
||||
```bash
|
||||
openclaw config get channels.googlechat
|
||||
```
|
||||
|
||||
Jika mengembalikan "Config path not found", tambahkan konfigurasi (lihat [Sorotan config](#config-highlights)).
|
||||
Jika mengembalikan "Config path not found", tambahkan konfigurasi (lihat [Sorotan konfigurasi](#config-highlights)).
|
||||
|
||||
2. **Plugin tidak diaktifkan**: Periksa status Plugin:
|
||||
2. **Plugin belum diaktifkan**: Periksa status Plugin:
|
||||
|
||||
```bash
|
||||
openclaw plugins list | grep googlechat
|
||||
```
|
||||
|
||||
Jika menampilkan "disabled", tambahkan `plugins.entries.googlechat.enabled: true` ke config Anda.
|
||||
Jika menampilkan "disabled", tambahkan `plugins.entries.googlechat.enabled: true` ke konfigurasi Anda.
|
||||
|
||||
3. **Gateway belum dimulai ulang**: Setelah menambahkan config, mulai ulang Gateway:
|
||||
3. **Gateway belum dimulai ulang**: Setelah menambahkan konfigurasi, mulai ulang Gateway:
|
||||
|
||||
```bash
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
Verifikasi bahwa channel berjalan:
|
||||
Verifikasi saluran berjalan:
|
||||
|
||||
```bash
|
||||
openclaw channels status
|
||||
@ -269,12 +269,12 @@ openclaw channels status
|
||||
|
||||
### Masalah lain
|
||||
|
||||
- Periksa `openclaw channels status --probe` untuk error autentikasi atau config audiens yang hilang.
|
||||
- Jika tidak ada pesan yang masuk, konfirmasikan URL Webhook aplikasi Chat + langganan peristiwa.
|
||||
- Jika gating mention memblokir balasan, atur `botUser` ke nama resource pengguna aplikasi dan verifikasi `requireMention`.
|
||||
- Periksa `openclaw channels status --probe` untuk kesalahan autentikasi atau konfigurasi audiens yang hilang.
|
||||
- Jika tidak ada pesan masuk, konfirmasi URL Webhook aplikasi Chat + langganan peristiwa.
|
||||
- Jika pembatasan mention memblokir balasan, atur `botUser` ke nama resource pengguna aplikasi dan verifikasi `requireMention`.
|
||||
- Gunakan `openclaw logs --follow` saat mengirim pesan uji untuk melihat apakah permintaan mencapai Gateway.
|
||||
|
||||
Dokumen terkait:
|
||||
Dokumentasi terkait:
|
||||
|
||||
- [Konfigurasi Gateway](/id/gateway/configuration)
|
||||
- [Keamanan](/id/gateway/security)
|
||||
@ -282,8 +282,8 @@ Dokumen terkait:
|
||||
|
||||
## Terkait
|
||||
|
||||
- [Ringkasan Channel](/id/channels) — semua channel yang didukung
|
||||
- [Ringkasan Saluran](/id/channels) — semua saluran yang didukung
|
||||
- [Pairing](/id/channels/pairing) — autentikasi DM dan alur pairing
|
||||
- [Grup](/id/channels/groups) — perilaku chat grup dan gating mention
|
||||
- [Perutean Channel](/id/channels/channel-routing) — perutean sesi untuk pesan
|
||||
- [Keamanan](/id/gateway/security) — model akses dan pengerasan
|
||||
- [Grup](/id/channels/groups) — perilaku chat grup dan pembatasan mention
|
||||
- [Perutean Saluran](/id/channels/channel-routing) — perutean sesi untuk pesan
|
||||
- [Keamanan](/id/gateway/security) — model akses dan hardening
|
||||
|
||||
@ -2,18 +2,18 @@
|
||||
read_when:
|
||||
- Mengubah perilaku obrolan grup atau pembatasan penyebutan
|
||||
sidebarTitle: Groups
|
||||
summary: Perilaku obrolan grup pada berbagai antarmuka (Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo)
|
||||
summary: Perilaku obrolan grup di berbagai antarmuka (Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo)
|
||||
title: Grup
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:27:22Z"
|
||||
generated_at: "2026-05-04T02:21:37Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 6fd4fcaa8335f1dc4b4b1a719d6654ab0c10530f74284269ed6205dd5f87c116
|
||||
source_hash: dea506c011a5d8f6155b2f56aacb236482cb8c5b7457001cb2171fd45932443d
|
||||
source_path: channels/groups.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw memperlakukan obrolan grup secara konsisten di semua permukaan: Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo.
|
||||
OpenClaw memperlakukan obrolan grup secara konsisten di berbagai surface: Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo.
|
||||
|
||||
## Pengantar pemula (2 menit)
|
||||
|
||||
@ -22,21 +22,21 @@ OpenClaw "hidup" di akun perpesanan Anda sendiri. Tidak ada pengguna bot WhatsAp
|
||||
Perilaku default:
|
||||
|
||||
- Grup dibatasi (`groupPolicy: "allowlist"`).
|
||||
- Balasan memerlukan penyebutan kecuali Anda secara eksplisit menonaktifkan pembatasan penyebutan.
|
||||
- Balasan akhir normal di grup/kanal bersifat privat secara default. Output ruang yang terlihat menggunakan alat `message`.
|
||||
- Balasan memerlukan mention kecuali Anda secara eksplisit menonaktifkan gerbang mention.
|
||||
- Balasan final normal di grup/channel bersifat privat secara default. Output ruang yang terlihat menggunakan alat `message`.
|
||||
|
||||
Artinya: pengirim yang ada dalam daftar izin dapat memicu OpenClaw dengan menyebutnya.
|
||||
Terjemahan: pengirim yang masuk allowlist dapat memicu OpenClaw dengan menyebutkannya.
|
||||
|
||||
<Note>
|
||||
**Ringkasnya**
|
||||
**TL;DR**
|
||||
|
||||
- **Akses DM** dikontrol oleh `*.allowFrom`.
|
||||
- **Akses grup** dikontrol oleh `*.groupPolicy` + daftar izin (`*.groups`, `*.groupAllowFrom`).
|
||||
- **Pemicu balasan** dikontrol oleh pembatasan penyebutan (`requireMention`, `/activation`).
|
||||
- **Akses grup** dikontrol oleh `*.groupPolicy` + allowlist (`*.groups`, `*.groupAllowFrom`).
|
||||
- **Pemicu balasan** dikontrol oleh gerbang mention (`requireMention`, `/activation`).
|
||||
|
||||
</Note>
|
||||
|
||||
Alur cepat (yang terjadi pada pesan grup):
|
||||
Alur cepat (apa yang terjadi pada pesan grup):
|
||||
|
||||
```
|
||||
groupPolicy? disabled -> drop
|
||||
@ -47,21 +47,29 @@ otherwise -> reply
|
||||
|
||||
## Balasan terlihat
|
||||
|
||||
Untuk ruang grup/kanal, OpenClaw secara default menggunakan `messages.groupChat.visibleReplies: "message_tool"`.
|
||||
`openclaw doctor --fix` menuliskan default ini ke konfigurasi kanal yang dikonfigurasi tetapi belum memilikinya.
|
||||
Ini berarti agen tetap memproses giliran 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"`.
|
||||
`openclaw doctor --fix` menulis default ini ke konfigurasi channel yang telah dikonfigurasi yang belum memilikinya.
|
||||
Artinya agen tetap memproses giliran tersebut dan dapat memperbarui status memori/sesi, tetapi jawaban final normalnya tidak otomatis diposting kembali ke ruang. Untuk berbicara secara terlihat, agen menggunakan `message(action=send)`.
|
||||
|
||||
Jika alat pesan tidak tersedia menurut kebijakan alat yang aktif, OpenClaw beralih
|
||||
kembali ke balasan terlihat otomatis alih-alih menekan respons secara diam-diam.
|
||||
`openclaw doctor` memperingatkan ketidakcocokan ini.
|
||||
Default ini bergantung pada model/runtime yang andal memanggil alat. Jika log menampilkan
|
||||
teks asisten tetapi `didSendViaMessagingTool: false`, model menjawab
|
||||
secara privat alih-alih memanggil alat message. Itu bukan kegagalan pengiriman
|
||||
Discord/Slack/Telegram. Gunakan model yang andal dalam pemanggilan alat untuk
|
||||
sesi grup/channel, atau atur
|
||||
`messages.groupChat.visibleReplies: "automatic"` untuk memulihkan balasan final
|
||||
terlihat gaya lama.
|
||||
|
||||
Untuk obrolan langsung dan giliran sumber lainnya, gunakan `messages.visibleReplies: "message_tool"` untuk menerapkan perilaku balasan terlihat khusus alat yang sama secara global. Harness juga dapat memilih ini sebagai default saat belum diatur; harness Codex melakukan ini untuk obrolan langsung mode Codex. `messages.groupChat.visibleReplies` tetap menjadi override yang lebih spesifik untuk ruang grup/kanal.
|
||||
Jika alat message tidak tersedia di bawah kebijakan alat aktif, OpenClaw kembali
|
||||
ke balasan terlihat otomatis alih-alih menekan respons secara diam-diam.
|
||||
`openclaw doctor` memperingatkan tentang ketidakcocokan ini.
|
||||
|
||||
Ini menggantikan pola lama yang memaksa model menjawab `NO_REPLY` untuk sebagian besar giliran mode memantau. Dalam mode khusus alat, tidak melakukan apa pun yang terlihat berarti tidak memanggil alat pesan.
|
||||
Untuk obrolan langsung dan giliran sumber lainnya, gunakan `messages.visibleReplies: "message_tool"` untuk menerapkan perilaku balasan terlihat hanya melalui alat yang sama secara global. Harness juga dapat memilih ini sebagai default saat belum diatur; harness Codex melakukan ini untuk obrolan langsung mode Codex. `messages.groupChat.visibleReplies` tetap menjadi override yang lebih spesifik untuk ruang grup/channel.
|
||||
|
||||
Indikator mengetik tetap dikirim saat agen bekerja dalam mode khusus alat. Mode mengetik grup default ditingkatkan dari "message" ke "instant" untuk giliran ini karena mungkin tidak pernah ada teks pesan asisten normal sebelum agen memutuskan apakah akan memanggil alat pesan. Konfigurasi mode mengetik eksplisit tetap diutamakan.
|
||||
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.
|
||||
|
||||
Untuk memulihkan balasan akhir otomatis lama bagi ruang grup/kanal:
|
||||
Indikator mengetik tetap dikirim saat agen bekerja dalam mode hanya alat. Mode mengetik grup default ditingkatkan dari "message" ke "instant" untuk giliran ini karena mungkin tidak pernah ada teks pesan asisten normal sebelum agen memutuskan apakah akan memanggil alat message. Konfigurasi mode mengetik eksplisit tetap menang.
|
||||
|
||||
Untuk memulihkan balasan final otomatis gaya lama untuk ruang grup/channel:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -73,10 +81,10 @@ Untuk memulihkan balasan akhir otomatis lama bagi ruang grup/kanal:
|
||||
}
|
||||
```
|
||||
|
||||
Gateway memuat ulang konfigurasi `messages` secara langsung setelah berkas disimpan. Mulai ulang hanya
|
||||
ketika pemantauan berkas atau pemuatan ulang konfigurasi dinonaktifkan dalam deployment.
|
||||
Gateway memuat ulang konfigurasi `messages` secara hot-reload setelah file disimpan. Mulai ulang hanya
|
||||
ketika pemantauan file atau pemuatan ulang konfigurasi dinonaktifkan dalam deployment.
|
||||
|
||||
Untuk mewajibkan output terlihat melewati alat pesan untuk setiap obrolan sumber:
|
||||
Untuk mewajibkan output terlihat melewati alat message untuk setiap obrolan sumber:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -86,29 +94,29 @@ Untuk mewajibkan output terlihat melewati alat pesan untuk setiap obrolan sumber
|
||||
}
|
||||
```
|
||||
|
||||
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 kanal mendapatkan respons yang diharapkannya. Ini hanya berlaku untuk giliran perintah native yang tervalidasi; perintah `/...` yang diketik sebagai teks dan giliran obrolan biasa tetap mengikuti default grup yang dikonfigurasi.
|
||||
Perintah slash native (Discord, Telegram, dan surface lain dengan dukungan perintah native) melewati `visibleReplies: "message_tool"` dan selalu membalas secara terlihat agar UI perintah native channel mendapatkan respons yang diharapkannya. 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
|
||||
## Visibilitas konteks dan allowlist
|
||||
|
||||
Dua kontrol berbeda terlibat dalam keamanan grup:
|
||||
|
||||
- **Otorisasi pemicu**: siapa yang dapat memicu agen (`groupPolicy`, `groups`, `groupAllowFrom`, daftar izin khusus kanal).
|
||||
- **Visibilitas konteks**: konteks tambahan apa yang disuntikkan ke model (teks balasan, kutipan, riwayat utas, metadata terusan).
|
||||
- **Otorisasi pemicu**: siapa yang dapat memicu agen (`groupPolicy`, `groups`, `groupAllowFrom`, allowlist khusus channel).
|
||||
- **Visibilitas konteks**: konteks tambahan apa yang disuntikkan ke model (teks balasan, kutipan, riwayat thread, metadata terusan).
|
||||
|
||||
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 yang dikutip atau historis.
|
||||
Secara default, OpenClaw memprioritaskan perilaku obrolan normal dan menjaga konteks sebagian besar sebagaimana diterima. Artinya allowlist terutama menentukan siapa yang dapat memicu tindakan, bukan batas redaksi universal untuk setiap cuplikan kutipan atau historis.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Perilaku saat ini bergantung pada kanal">
|
||||
- Beberapa kanal sudah menerapkan pemfilteran berbasis pengirim untuk konteks tambahan di jalur tertentu (misalnya penyemaian utas Slack, pencarian balasan/utas Matrix).
|
||||
- Kanal lain masih meneruskan konteks kutipan/balasan/terusan sebagaimana diterima.
|
||||
<Accordion title="Perilaku saat ini khusus per channel">
|
||||
- Beberapa channel sudah menerapkan pemfilteran berbasis pengirim untuk konteks tambahan di jalur tertentu (misalnya penyiapan thread Slack, pencarian balasan/thread Matrix).
|
||||
- Channel lain masih meneruskan konteks kutipan/balasan/terusan sebagaimana diterima.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Arah penguatan (direncanakan)">
|
||||
<Accordion title="Arah hardening (direncanakan)">
|
||||
- `contextVisibility: "all"` (default) mempertahankan perilaku saat ini sebagaimana diterima.
|
||||
- `contextVisibility: "allowlist"` memfilter konteks tambahan ke pengirim yang ada dalam daftar izin.
|
||||
- `contextVisibility: "allowlist"` memfilter konteks tambahan ke pengirim yang masuk allowlist.
|
||||
- `contextVisibility: "allowlist_quote"` adalah `allowlist` ditambah satu pengecualian kutipan/balasan eksplisit.
|
||||
|
||||
Hingga model penguatan ini diterapkan secara konsisten di seluruh kanal, harapkan perbedaan berdasarkan permukaan.
|
||||
Hingga model hardening ini diterapkan secara konsisten di seluruh channel, harapkan perbedaan berdasarkan surface.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -117,19 +125,19 @@ Secara default, OpenClaw memprioritaskan perilaku obrolan normal dan mempertahan
|
||||
|
||||
Jika Anda ingin...
|
||||
|
||||
| Tujuan | Yang perlu diatur |
|
||||
| Tujuan | Yang harus diatur |
|
||||
| -------------------------------------------- | ---------------------------------------------------------- |
|
||||
| Izinkan semua grup tetapi hanya balas pada @penyebutan | `groups: { "*": { requireMention: true } }` |
|
||||
| Izinkan semua grup tetapi hanya balas saat @mention | `groups: { "*": { requireMention: true } }` |
|
||||
| Nonaktifkan semua balasan grup | `groupPolicy: "disabled"` |
|
||||
| Hanya grup tertentu | `groups: { "<group-id>": { ... } }` (tanpa kunci `"*"` key) |
|
||||
| Hanya grup tertentu | `groups: { "<group-id>": { ... } }` (tanpa kunci `"*"` ) |
|
||||
| Hanya Anda yang dapat memicu di grup | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` |
|
||||
| Gunakan ulang satu set pengirim tepercaya di seluruh kanal | `groupAllowFrom: ["accessGroup:operators"]` |
|
||||
| Gunakan ulang satu set pengirim tepercaya di seluruh channel | `groupAllowFrom: ["accessGroup:operators"]` |
|
||||
|
||||
Untuk daftar izin pengirim yang dapat digunakan ulang, lihat [Grup akses](/id/channels/access-groups).
|
||||
Untuk allowlist pengirim yang dapat digunakan ulang, lihat [Grup akses](/id/channels/access-groups).
|
||||
|
||||
## Kunci sesi
|
||||
|
||||
- Sesi grup menggunakan kunci sesi `agent:<agentId>:<channel>:group:<id>` (ruang/kanal menggunakan `agent:<agentId>:<channel>:channel:<id>`).
|
||||
- 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 sesi sendiri.
|
||||
- Obrolan langsung menggunakan sesi utama (atau per pengirim jika dikonfigurasi).
|
||||
- Heartbeat dilewati untuk sesi grup.
|
||||
@ -138,9 +146,9 @@ Untuk daftar izin pengirim yang dapat digunakan ulang, lihat [Grup akses](/id/ch
|
||||
|
||||
## Pola: DM pribadi + grup publik (satu agen)
|
||||
|
||||
Ya — ini berjalan baik jika lalu lintas "pribadi" Anda adalah **DM** dan lalu lintas "publik" Anda adalah **grup**.
|
||||
Ya — ini bekerja dengan baik jika lalu lintas "pribadi" Anda adalah **DM** dan lalu lintas "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 di host. Docker adalah backend default jika Anda tidak memilih salah satunya.
|
||||
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 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:
|
||||
|
||||
@ -148,11 +156,11 @@ Ini memberi Anda satu "otak" agen (workspace + memori bersama), tetapi dua postu
|
||||
- **Grup**: sandbox + alat 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 agen kedua + binding. Lihat [Routing Multi-Agen](/id/concepts/multi-agent).
|
||||
</Note>
|
||||
|
||||
<Tabs>
|
||||
<Tab title="DM di host, grup dalam sandbox">
|
||||
<Tab title="DM di host, grup di-sandbox">
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
@ -176,8 +184,8 @@ Jika Anda membutuhkan workspace/persona yang benar-benar terpisah ("pribadi" dan
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Grup hanya melihat folder dalam daftar izin">
|
||||
Ingin "grup hanya dapat melihat folder X" alih-alih "tanpa akses host"? Pertahankan `workspaceAccess: "none"` dan mount hanya path yang ada dalam daftar izin ke dalam sandbox:
|
||||
<Tab title="Grup hanya melihat folder yang masuk allowlist">
|
||||
Ingin "grup hanya dapat melihat folder X" alih-alih "tanpa akses host"? Pertahankan `workspaceAccess: "none"` dan mount hanya path yang masuk allowlist ke dalam sandbox:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -211,11 +219,11 @@ Terkait:
|
||||
## Label tampilan
|
||||
|
||||
- Label UI menggunakan `displayName` jika tersedia, diformat sebagai `<channel>:<token>`.
|
||||
- `#room` dicadangkan untuk ruang/kanal; obrolan grup menggunakan `g-<slug>` (huruf kecil, spasi -> `-`, pertahankan `#@+._-`).
|
||||
- `#room` dicadangkan untuk ruang/channel; obrolan grup menggunakan `g-<slug>` (huruf kecil, spasi -> `-`, pertahankan `#@+._-`).
|
||||
|
||||
## Kebijakan grup
|
||||
|
||||
Kontrol bagaimana pesan grup/ruang ditangani per kanal:
|
||||
Kontrol bagaimana pesan grup/ruang ditangani per channel:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -262,25 +270,25 @@ Kontrol bagaimana pesan grup/ruang ditangani per kanal:
|
||||
}
|
||||
```
|
||||
|
||||
| Kebijakan | Perilaku |
|
||||
| Kebijakan | Perilaku |
|
||||
| ------------- | ------------------------------------------------------------ |
|
||||
| `"open"` | Grup melewati daftar izin; pembatasan penyebutan tetap berlaku. |
|
||||
| `"disabled"` | Blokir semua pesan grup sepenuhnya. |
|
||||
| `"allowlist"` | Hanya izinkan grup/ruang yang cocok dengan daftar izin yang dikonfigurasi. |
|
||||
| `"open"` | Grup melewati allowlist; gerbang mention tetap berlaku. |
|
||||
| `"disabled"` | Blokir semua pesan grup sepenuhnya. |
|
||||
| `"allowlist"` | Hanya izinkan grup/ruang yang cocok dengan allowlist yang dikonfigurasi. |
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Catatan per kanal">
|
||||
- `groupPolicy` terpisah dari pembatasan penyebutan (yang memerlukan @penyebutan).
|
||||
<Accordion title="Catatan per saluran">
|
||||
- `groupPolicy` terpisah dari pembatasan berdasarkan mention (yang memerlukan @mention).
|
||||
- WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: gunakan `groupAllowFrom` (fallback: `allowFrom` eksplisit).
|
||||
- Signal: `groupAllowFrom` dapat cocok dengan id grup Signal masuk atau nomor telepon/UUID pengirim.
|
||||
- Persetujuan pemasangan DM (entri penyimpanan `*-allowFrom`) hanya berlaku untuk akses DM; otorisasi pengirim grup tetap eksplisit pada daftar izin grup.
|
||||
- Signal: `groupAllowFrom` dapat cocok dengan id grup Signal masuk atau telepon/UUID pengirim.
|
||||
- Persetujuan pemasangan 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 sudah dimasuki 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.
|
||||
- Matrix: daftar izin menggunakan `channels.matrix.groups`. Utamakan ID ruangan atau alias; pencarian nama ruangan yang telah diikuti bersifat best-effort, dan nama yang tidak terselesaikan diabaikan saat runtime. Gunakan `channels.matrix.groupAllowFrom` untuk membatasi pengirim; daftar izin `users` per ruangan juga didukung.
|
||||
- DM grup dikontrol 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.
|
||||
- Default 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 beralih ke mode gagal-tertutup (biasanya `allowlist`) alih-alih mewarisi `channels.defaults.groupPolicy`.
|
||||
- Daftar izin Telegram dapat cocok dengan ID pengguna (`"123456789"`, `"telegram:123456789"`, `"tg:123456789"`) atau username (`"@alice"` atau `"alice"`); prefiks tidak peka huruf besar/kecil.
|
||||
- Default-nya 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 fallback ke mode fail-closed (biasanya `allowlist`) alih-alih mewarisi `channels.defaults.groupPolicy`.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -289,21 +297,21 @@ Model mental cepat (urutan evaluasi untuk pesan grup):
|
||||
|
||||
<Steps>
|
||||
<Step title="groupPolicy">
|
||||
`groupPolicy` (terbuka/dinonaktifkan/allowlist).
|
||||
`groupPolicy` (open/disabled/allowlist).
|
||||
</Step>
|
||||
<Step title="Group allowlists">
|
||||
Allowlist grup (`*.groups`, `*.groupAllowFrom`, allowlist khusus kanal).
|
||||
<Step title="Daftar izin grup">
|
||||
Daftar izin grup (`*.groups`, `*.groupAllowFrom`, daftar izin khusus saluran).
|
||||
</Step>
|
||||
<Step title="Mention gating">
|
||||
Gating sebutan (`requireMention`, `/activation`).
|
||||
<Step title="Pembatasan mention">
|
||||
Pembatasan mention (`requireMention`, `/activation`).
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Gating sebutan (bawaan)
|
||||
## Pembatasan mention (default)
|
||||
|
||||
Pesan grup memerlukan sebutan kecuali ditimpa per grup. Default berada per subsistem di bawah `*.groups."*"`.
|
||||
Pesan grup memerlukan mention kecuali ditimpa per grup. Default berada per subsistem di bawah `*.groups."*"`.
|
||||
|
||||
Membalas pesan bot dihitung sebagai sebutan implisit ketika kanal mendukung metadata balasan. Mengutip pesan bot juga dapat dihitung sebagai sebutan implisit pada kanal yang mengekspos metadata kutipan. Kasus bawaan saat ini mencakup Telegram, WhatsApp, Slack, Discord, Microsoft Teams, dan ZaloUser.
|
||||
Membalas pesan bot dihitung sebagai mention implisit ketika saluran mendukung metadata balasan. Mengutip pesan bot juga dapat dihitung sebagai mention implisit pada saluran yang mengekspos metadata kutipan. Kasus bawaan saat ini mencakup Telegram, WhatsApp, Slack, Discord, Microsoft Teams, dan ZaloUser.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -342,40 +350,40 @@ Membalas pesan bot dihitung sebagai sebutan implisit ketika kanal mendukung meta
|
||||
```
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Catatan gating sebutan">
|
||||
- `mentionPatterns` adalah pola regex aman yang tidak peka huruf besar-kecil; pola tidak valid dan bentuk pengulangan bersarang yang tidak aman diabaikan.
|
||||
- Permukaan yang menyediakan sebutan eksplisit tetap lolos; pola adalah fallback.
|
||||
- Timpa per agen: `agents.list[].groupChat.mentionPatterns` (berguna ketika beberapa agen berbagi satu grup).
|
||||
- Gating sebutan hanya diberlakukan ketika deteksi sebutan memungkinkan (sebutan native atau `mentionPatterns` dikonfigurasi).
|
||||
- Memasukkan grup atau pengirim ke allowlist tidak menonaktifkan gating sebutan; setel `requireMention` grup tersebut ke `false` ketika semua pesan harus memicu.
|
||||
- Konteks prompt obrolan grup membawa instruksi balasan senyap yang sudah diselesaikan di setiap giliran; file ruang kerja tidak boleh menggandakan mekanisme `NO_REPLY`.
|
||||
- Grup yang mengizinkan balasan senyap memperlakukan giliran model yang kosong bersih atau hanya penalaran sebagai senyap, setara dengan `NO_REPLY`. Obrolan langsung melakukan hal yang sama hanya ketika balasan senyap langsung diizinkan secara eksplisit; jika tidak, balasan kosong tetap menjadi giliran agen yang gagal.
|
||||
- Default Discord berada di `channels.discord.guilds."*"` (dapat ditimpa per guild/kanal).
|
||||
- Konteks riwayat grup dibungkus secara seragam lintas kanal dan bersifat **hanya tertunda** (pesan yang dilewati karena gating sebutan); gunakan `messages.groupChat.historyLimit` untuk default global dan `channels.<channel>.historyLimit` (atau `channels.<channel>.accounts.*.historyLimit`) untuk penimpaan. Setel `0` untuk menonaktifkan.
|
||||
<Accordion title="Catatan pembatasan 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.
|
||||
- Timpa per agen: `agents.list[].groupChat.mentionPatterns` (berguna ketika beberapa agen berbagi grup).
|
||||
- Pembatasan mention hanya diberlakukan ketika deteksi mention memungkinkan (mention native atau `mentionPatterns` dikonfigurasi).
|
||||
- Memasukkan grup atau pengirim ke daftar izin tidak menonaktifkan pembatasan mention; atur `requireMention` grup tersebut ke `false` ketika semua pesan harus memicu.
|
||||
- Konteks prompt obrolan grup membawa instruksi balasan diam yang telah diselesaikan pada setiap giliran; file workspace tidak boleh menduplikasi mekanisme `NO_REPLY`.
|
||||
- Grup tempat balasan diam diizinkan memperlakukan giliran model yang benar-benar kosong atau hanya reasoning sebagai diam, setara dengan `NO_REPLY`. Obrolan langsung melakukan hal yang sama hanya ketika balasan diam langsung diizinkan secara eksplisit; jika tidak, balasan kosong tetap menjadi giliran agen yang gagal.
|
||||
- Default Discord berada di `channels.discord.guilds."*"` (dapat ditimpa per guild/saluran).
|
||||
- Konteks riwayat grup dibungkus secara seragam di seluruh saluran dan bersifat **pending-only** (pesan yang dilewati karena pembatasan mention); gunakan `messages.groupChat.historyLimit` untuk default global dan `channels.<channel>.historyLimit` (atau `channels.<channel>.accounts.*.historyLimit`) untuk penimpaan. Atur `0` untuk menonaktifkan.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Pembatasan alat grup/kanal (opsional)
|
||||
## Pembatasan tool grup/saluran (opsional)
|
||||
|
||||
Beberapa konfigurasi kanal mendukung pembatasan alat mana yang tersedia **di dalam grup/ruang/kanal tertentu**.
|
||||
Beberapa konfigurasi saluran mendukung pembatasan tool mana yang tersedia **di dalam grup/ruangan/saluran tertentu**.
|
||||
|
||||
- `tools`: izinkan/tolak alat untuk seluruh grup.
|
||||
- `toolsBySender`: penimpaan 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.
|
||||
- `tools`: izinkan/tolak tool untuk seluruh grup.
|
||||
- `toolsBySender`: penimpaan per pengirim dalam grup. Gunakan prefiks kunci eksplisit: `id:<senderId>`, `e164:<phone>`, `username:<handle>`, `name:<displayName>`, dan wildcard `"*"`. Kunci lama tanpa prefiks masih diterima dan dicocokkan hanya sebagai `id:`.
|
||||
|
||||
Urutan resolusi (yang paling spesifik menang):
|
||||
|
||||
<Steps>
|
||||
<Step title="Group toolsBySender">
|
||||
Kecocokan `toolsBySender` grup/kanal.
|
||||
<Step title="toolsBySender grup">
|
||||
Kecocokan `toolsBySender` grup/saluran.
|
||||
</Step>
|
||||
<Step title="Group tools">
|
||||
`tools` grup/kanal.
|
||||
<Step title="tools grup">
|
||||
`tools` grup/saluran.
|
||||
</Step>
|
||||
<Step title="Default toolsBySender">
|
||||
<Step title="toolsBySender default">
|
||||
Kecocokan `toolsBySender` default (`"*"`).
|
||||
</Step>
|
||||
<Step title="Default tools">
|
||||
<Step title="tools default">
|
||||
`tools` default (`"*"`).
|
||||
</Step>
|
||||
</Steps>
|
||||
@ -401,18 +409,18 @@ Contoh (Telegram):
|
||||
```
|
||||
|
||||
<Note>
|
||||
Pembatasan alat grup/kanal diterapkan sebagai tambahan terhadap kebijakan alat global/agen (penolakan tetap menang). Beberapa kanal menggunakan penyarangan berbeda untuk ruang/kanal (misalnya, Discord `guilds.*.channels.*`, Slack `channels.*`, Microsoft Teams `teams.*.channels.*`).
|
||||
Pembatasan tool grup/saluran diterapkan selain kebijakan tool global/agen (deny tetap menang). Beberapa saluran menggunakan nesting yang berbeda untuk ruangan/saluran (misalnya, Discord `guilds.*.channels.*`, Slack `channels.*`, Microsoft Teams `teams.*.channels.*`).
|
||||
</Note>
|
||||
|
||||
## Allowlist grup
|
||||
## Daftar izin grup
|
||||
|
||||
Ketika `channels.whatsapp.groups`, `channels.telegram.groups`, atau `channels.imessage.groups` dikonfigurasi, kuncinya bertindak sebagai allowlist grup. Gunakan `"*"` untuk mengizinkan semua grup sambil tetap menetapkan perilaku sebutan default.
|
||||
Ketika `channels.whatsapp.groups`, `channels.telegram.groups`, atau `channels.imessage.groups` dikonfigurasi, kuncinya berfungsi sebagai daftar izin grup. Gunakan `"*"` untuk mengizinkan semua grup sambil tetap menetapkan perilaku mention default.
|
||||
|
||||
<Warning>
|
||||
Kebingungan umum: persetujuan pemasangan DM tidak sama dengan otorisasi grup. Untuk kanal yang mendukung pemasangan DM, penyimpanan pemasangan hanya membuka DM. Perintah grup tetap memerlukan otorisasi pengirim grup eksplisit dari allowlist konfigurasi seperti `groupAllowFrom` atau fallback konfigurasi terdokumentasi untuk kanal tersebut.
|
||||
Kebingungan umum: persetujuan pemasangan DM tidak sama dengan otorisasi grup. Untuk saluran yang mendukung pemasangan DM, penyimpanan pemasangan hanya membuka DM. Perintah grup tetap memerlukan otorisasi pengirim grup eksplisit dari daftar izin konfigurasi seperti `groupAllowFrom` atau fallback konfigurasi yang terdokumentasi untuk saluran tersebut.
|
||||
</Warning>
|
||||
|
||||
Niat umum (salin/tempel):
|
||||
Maksud umum (salin/tempel):
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Nonaktifkan semua balasan grup">
|
||||
@ -436,7 +444,7 @@ Niat umum (salin/tempel):
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Izinkan semua grup tetapi wajibkan sebutan">
|
||||
<Tab title="Izinkan semua grup tetapi wajibkan mention">
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
@ -447,7 +455,7 @@ Niat umum (salin/tempel):
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Pemicu hanya pemilik (WhatsApp)">
|
||||
<Tab title="Pemicu khusus pemilik (WhatsApp)">
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
@ -462,34 +470,34 @@ Niat umum (salin/tempel):
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Aktivasi (hanya pemilik)
|
||||
## Aktivasi (khusus pemilik)
|
||||
|
||||
Pemilik grup dapat mengalihkan aktivasi per grup:
|
||||
Pemilik grup dapat mengaktifkan/menonaktifkan aktivasi per grup:
|
||||
|
||||
- `/activation mention`
|
||||
- `/activation always`
|
||||
|
||||
Pemilik ditentukan oleh `channels.whatsapp.allowFrom` (atau E.164 milik bot sendiri ketika tidak disetel). Kirim perintah sebagai pesan mandiri. Permukaan lain saat ini mengabaikan `/activation`.
|
||||
Pemilik ditentukan oleh `channels.whatsapp.allowFrom` (atau E.164 mandiri bot saat tidak diatur). Kirim perintah sebagai pesan mandiri. Permukaan lain saat ini mengabaikan `/activation`.
|
||||
|
||||
## Bidang konteks
|
||||
## Kolom konteks
|
||||
|
||||
Payload masuk grup menetapkan:
|
||||
Payload masuk grup mengatur:
|
||||
|
||||
- `ChatType=group`
|
||||
- `GroupSubject` (jika diketahui)
|
||||
- `GroupMembers` (jika diketahui)
|
||||
- `WasMentioned` (hasil gating sebutan)
|
||||
- `WasMentioned` (hasil pembatasan mention)
|
||||
- Topik forum Telegram juga menyertakan `MessageThreadId` dan `IsForum`.
|
||||
|
||||
Catatan khusus kanal:
|
||||
Catatan khusus saluran:
|
||||
|
||||
- BlueBubbles dapat secara opsional memperkaya peserta grup macOS yang tidak bernama dari basis data Kontak lokal sebelum mengisi `GroupMembers`. Ini nonaktif secara default dan hanya berjalan setelah gating grup normal lolos.
|
||||
- BlueBubbles secara opsional dapat memperkaya peserta grup macOS tanpa nama dari database Contacts lokal sebelum mengisi `GroupMembers`. Ini nonaktif secara default dan hanya berjalan setelah pembatasan grup normal lolos.
|
||||
|
||||
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 obrolan normal, serta menghindari pengetikan urutan literal `\n`. Nama grup dan label peserta yang bersumber dari kanal 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 obrolan normal, serta menghindari mengetik urutan literal `\n`. Nama grup dan label peserta yang bersumber dari saluran dirender sebagai metadata tidak tepercaya berpagar, bukan instruksi sistem inline.
|
||||
|
||||
## Kekhususan iMessage
|
||||
|
||||
- Utamakan `chat_id:<id>` saat merutekan atau memasukkan ke allowlist.
|
||||
- Utamakan `chat_id:<id>` saat merutekan atau memasukkan ke daftar izin.
|
||||
- Daftar obrolan: `imsg chats --limit 20`.
|
||||
- Balasan grup selalu kembali ke `chat_id` yang sama.
|
||||
|
||||
@ -499,11 +507,11 @@ Lihat [WhatsApp](/id/channels/whatsapp#system-prompts) untuk aturan prompt siste
|
||||
|
||||
## Kekhususan WhatsApp
|
||||
|
||||
Lihat [Pesan grup](/id/channels/group-messages) untuk perilaku khusus WhatsApp (injeksi riwayat, detail penanganan sebutan).
|
||||
Lihat [Pesan grup](/id/channels/group-messages) untuk perilaku khusus WhatsApp (injeksi riwayat, detail penanganan mention).
|
||||
|
||||
## Terkait
|
||||
|
||||
- [Grup siaran](/id/channels/broadcast-groups)
|
||||
- [Perutean kanal](/id/channels/channel-routing)
|
||||
- [Grup broadcast](/id/channels/broadcast-groups)
|
||||
- [Perutean saluran](/id/channels/channel-routing)
|
||||
- [Pesan grup](/id/channels/group-messages)
|
||||
- [Pemasangan](/id/channels/pairing)
|
||||
|
||||
@ -1,26 +1,25 @@
|
||||
---
|
||||
read_when:
|
||||
- Anda ingin menghubungkan OpenClaw ke channel atau DM IRC
|
||||
- Anda sedang mengonfigurasi allowlist IRC, kebijakan grup, atau gating mention
|
||||
summary: Penyiapan plugin IRC, kontrol akses, dan pemecahan masalah
|
||||
- Anda ingin menghubungkan OpenClaw ke kanal IRC atau pesan langsung
|
||||
- Anda sedang mengonfigurasi daftar izin IRC, kebijakan grup, atau pembatasan penyebutan
|
||||
summary: Penyiapan Plugin IRC, kontrol akses, dan pemecahan masalah
|
||||
title: IRC
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T08:58:19Z"
|
||||
model: gpt-5.4
|
||||
generated_at: "2026-05-04T02:21:38Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 76f316c0f026d0387a97dc5dcb6d8967f6e4841d94b95b36e42f6f6284882a69
|
||||
source_hash: 43c3098fe49a5e7405443df73e1bf752a579460dc0b2070c3d07f43b512bb555
|
||||
source_path: channels/irc.md
|
||||
workflow: 15
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Gunakan IRC saat Anda menginginkan OpenClaw di channel klasik (`#room`) dan pesan langsung.
|
||||
|
||||
IRC dikirim sebagai plugin bawaan, tetapi dikonfigurasi di config utama pada `channels.irc`.
|
||||
Gunakan IRC saat Anda menginginkan OpenClaw di saluran klasik (`#room`) dan pesan langsung.
|
||||
IRC disertakan sebagai Plugin bawaan, tetapi dikonfigurasi di konfigurasi utama di bawah `channels.irc`.
|
||||
|
||||
## Mulai cepat
|
||||
|
||||
1. Aktifkan config IRC di `~/.openclaw/openclaw.json`.
|
||||
2. Atur setidaknya:
|
||||
1. Aktifkan konfigurasi IRC di `~/.openclaw/openclaw.json`.
|
||||
2. Tetapkan setidaknya:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -37,9 +36,9 @@ IRC dikirim sebagai plugin bawaan, tetapi dikonfigurasi di config utama pada `ch
|
||||
}
|
||||
```
|
||||
|
||||
Utamakan server IRC privat untuk koordinasi bot. Jika Anda sengaja menggunakan jaringan IRC publik, pilihan umum mencakup Libera.Chat, OFTC, dan Snoonet. Hindari channel publik yang mudah ditebak untuk lalu lintas bot atau backchannel swarm.
|
||||
Utamakan server IRC privat untuk koordinasi bot. Jika Anda sengaja menggunakan jaringan IRC publik, pilihan umum mencakup Libera.Chat, OFTC, dan Snoonet. Hindari saluran publik yang mudah ditebak untuk lalu lintas backchannel bot atau swarm.
|
||||
|
||||
3. Mulai/mulai ulang gateway:
|
||||
3. Mulai/jalankan ulang Gateway:
|
||||
|
||||
```bash
|
||||
openclaw gateway run
|
||||
@ -47,40 +46,41 @@ openclaw gateway run
|
||||
|
||||
## Default keamanan
|
||||
|
||||
- IRC menggunakan soket TCP/TLS mentah di luar perutean forward proxy yang dikelola operator OpenClaw. Dalam deployment yang mewajibkan semua egress melalui forward proxy tersebut, tetapkan `channels.irc.enabled=false` kecuali egress IRC langsung disetujui secara eksplisit.
|
||||
- `channels.irc.dmPolicy` default ke `"pairing"`.
|
||||
- `channels.irc.groupPolicy` default ke `"allowlist"`.
|
||||
- Dengan `groupPolicy="allowlist"`, atur `channels.irc.groups` untuk menentukan channel yang diizinkan.
|
||||
- Gunakan TLS (`channels.irc.tls=true`) kecuali Anda memang sengaja menerima transport plaintext.
|
||||
- Dengan `groupPolicy="allowlist"`, tetapkan `channels.irc.groups` untuk menentukan saluran yang diizinkan.
|
||||
- Gunakan TLS (`channels.irc.tls=true`) kecuali Anda sengaja menerima transport plaintext.
|
||||
|
||||
## Kontrol akses
|
||||
|
||||
Ada dua “gerbang” terpisah untuk channel IRC:
|
||||
Ada dua “gerbang” terpisah untuk saluran IRC:
|
||||
|
||||
1. **Akses channel** (`groupPolicy` + `groups`): apakah bot menerima pesan dari suatu channel sama sekali.
|
||||
2. **Akses pengirim** (`groupAllowFrom` / per-channel `groups["#channel"].allowFrom`): siapa yang diizinkan memicu bot di dalam channel tersebut.
|
||||
1. **Akses saluran** (`groupPolicy` + `groups`): apakah bot menerima pesan dari suatu saluran sama sekali.
|
||||
2. **Akses pengirim** (`groupAllowFrom` / per-saluran `groups["#channel"].allowFrom`): siapa yang diizinkan memicu bot di dalam saluran tersebut.
|
||||
|
||||
Kunci config:
|
||||
Kunci konfigurasi:
|
||||
|
||||
- Allowlist DM (akses pengirim DM): `channels.irc.allowFrom`
|
||||
- Allowlist pengirim grup (akses pengirim channel): `channels.irc.groupAllowFrom`
|
||||
- Kontrol per channel (aturan channel + pengirim + mention): `channels.irc.groups["#channel"]`
|
||||
- `channels.irc.groupPolicy="open"` mengizinkan channel yang tidak dikonfigurasi (**tetap menggunakan gating mention secara default**)
|
||||
- Allowlist pengirim grup (akses pengirim saluran): `channels.irc.groupAllowFrom`
|
||||
- Kontrol per-saluran (aturan saluran + pengirim + mention): `channels.irc.groups["#channel"]`
|
||||
- `channels.irc.groupPolicy="open"` mengizinkan saluran yang belum dikonfigurasi (**tetap dibatasi mention secara default**)
|
||||
|
||||
Entri allowlist sebaiknya menggunakan identitas pengirim yang stabil (`nick!user@host`).
|
||||
Pencocokan nick tanpa tambahan bersifat dapat berubah dan hanya diaktifkan saat `channels.irc.dangerouslyAllowNameMatching: true`.
|
||||
Pencocokan nick polos dapat berubah dan hanya diaktifkan saat `channels.irc.dangerouslyAllowNameMatching: true`.
|
||||
|
||||
### Hal yang sering menjebak: `allowFrom` untuk DM, bukan channel
|
||||
### Kekeliruan umum: `allowFrom` untuk DM, bukan saluran
|
||||
|
||||
Jika Anda melihat log seperti:
|
||||
|
||||
- `irc: drop group sender alice!ident@host (policy=allowlist)`
|
||||
|
||||
...artinya pengirim tidak diizinkan untuk pesan **grup/channel**. Perbaiki dengan salah satu cara berikut:
|
||||
…itu berarti pengirim tidak diizinkan untuk pesan **grup/saluran**. Perbaiki dengan salah satu cara berikut:
|
||||
|
||||
- mengatur `channels.irc.groupAllowFrom` (global untuk semua channel), atau
|
||||
- mengatur allowlist pengirim per channel: `channels.irc.groups["#channel"].allowFrom`
|
||||
- menetapkan `channels.irc.groupAllowFrom` (global untuk semua saluran), atau
|
||||
- menetapkan allowlist pengirim per-saluran: `channels.irc.groups["#channel"].allowFrom`
|
||||
|
||||
Contoh (izinkan siapa pun di `#tuirc-dev` berbicara ke bot):
|
||||
Contoh (izinkan siapa pun di `#tuirc-dev` berbicara dengan bot):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -97,11 +97,11 @@ Contoh (izinkan siapa pun di `#tuirc-dev` berbicara ke bot):
|
||||
|
||||
## Pemicu balasan (mention)
|
||||
|
||||
Meskipun sebuah channel diizinkan (melalui `groupPolicy` + `groups`) dan pengirim diizinkan, OpenClaw secara default menggunakan **gating mention** dalam konteks grup.
|
||||
Meskipun saluran diizinkan (melalui `groupPolicy` + `groups`) dan pengirim diizinkan, OpenClaw secara default menggunakan **pembatasan mention** dalam konteks grup.
|
||||
|
||||
Itu berarti Anda mungkin melihat log seperti `drop channel … (missing-mention)` kecuali pesan menyertakan pola mention yang cocok dengan bot.
|
||||
Artinya, Anda mungkin melihat log seperti `drop channel … (missing-mention)` kecuali pesan menyertakan pola mention yang cocok dengan bot.
|
||||
|
||||
Agar bot membalas di channel IRC **tanpa perlu mention**, nonaktifkan gating mention untuk channel tersebut:
|
||||
Agar bot membalas di saluran IRC **tanpa memerlukan mention**, nonaktifkan pembatasan mention untuk saluran tersebut:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -119,7 +119,7 @@ Agar bot membalas di channel IRC **tanpa perlu mention**, nonaktifkan gating men
|
||||
}
|
||||
```
|
||||
|
||||
Atau untuk mengizinkan **semua** channel IRC (tanpa allowlist per channel) dan tetap membalas tanpa mention:
|
||||
Atau untuk mengizinkan **semua** saluran IRC (tanpa allowlist per-saluran) dan tetap membalas tanpa mention:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -134,12 +134,12 @@ Atau untuk mengizinkan **semua** channel IRC (tanpa allowlist per channel) dan t
|
||||
}
|
||||
```
|
||||
|
||||
## Catatan keamanan (disarankan untuk channel publik)
|
||||
## Catatan keamanan (disarankan untuk saluran publik)
|
||||
|
||||
Jika Anda mengizinkan `allowFrom: ["*"]` di channel publik, siapa pun dapat memberi prompt ke bot.
|
||||
Untuk mengurangi risiko, batasi alat untuk channel tersebut.
|
||||
Jika Anda mengizinkan `allowFrom: ["*"]` di saluran publik, siapa pun dapat memberi prompt ke bot.
|
||||
Untuk mengurangi risiko, batasi alat untuk saluran tersebut.
|
||||
|
||||
### Alat yang sama untuk semua orang di channel
|
||||
### Alat yang sama untuk semua orang di saluran
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -158,9 +158,9 @@ Untuk mengurangi risiko, batasi alat untuk channel tersebut.
|
||||
}
|
||||
```
|
||||
|
||||
### Alat berbeda per pengirim (owner mendapat lebih banyak kuasa)
|
||||
### Alat berbeda per pengirim (pemilik mendapat lebih banyak kuasa)
|
||||
|
||||
Gunakan `toolsBySender` untuk menerapkan kebijakan yang lebih ketat ke `"*"` dan kebijakan yang lebih longgar ke nick Anda:
|
||||
Gunakan `toolsBySender` untuk menerapkan kebijakan yang lebih ketat ke `"*"` dan yang lebih longgar ke nick Anda:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -188,14 +188,14 @@ Catatan:
|
||||
|
||||
- Kunci `toolsBySender` sebaiknya menggunakan `id:` untuk nilai identitas pengirim IRC:
|
||||
`id:eigen` atau `id:eigen!~eigen@174.127.248.171` untuk pencocokan yang lebih kuat.
|
||||
- Kunci lama tanpa prefiks masih diterima dan hanya dicocokkan sebagai `id:`.
|
||||
- Kebijakan pengirim pertama yang cocok akan digunakan; `"*"` adalah fallback wildcard.
|
||||
- Kunci lama tanpa prefiks masih diterima dan dicocokkan hanya sebagai `id:`.
|
||||
- Kebijakan pengirim pertama yang cocok akan berlaku; `"*"` adalah fallback wildcard.
|
||||
|
||||
Untuk info lebih lanjut tentang akses grup vs gating mention (dan cara keduanya berinteraksi), lihat: [/channels/groups](/id/channels/groups).
|
||||
Untuk informasi lebih lanjut tentang akses grup vs pembatasan mention (dan bagaimana keduanya berinteraksi), lihat: [/channels/groups](/id/channels/groups).
|
||||
|
||||
## NickServ
|
||||
|
||||
Untuk mengidentifikasi dengan NickServ setelah tersambung:
|
||||
Untuk mengidentifikasi diri dengan NickServ setelah terhubung:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -211,7 +211,7 @@ Untuk mengidentifikasi dengan NickServ setelah tersambung:
|
||||
}
|
||||
```
|
||||
|
||||
Pendaftaran satu kali opsional saat tersambung:
|
||||
Pendaftaran satu kali opsional saat terhubung:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -243,18 +243,18 @@ Akun default mendukung:
|
||||
- `IRC_NICKSERV_PASSWORD`
|
||||
- `IRC_NICKSERV_REGISTER_EMAIL`
|
||||
|
||||
`IRC_HOST` tidak dapat diatur dari workspace `.env`; lihat [File `.env` workspace](/id/gateway/security).
|
||||
`IRC_HOST` tidak dapat ditetapkan dari `.env` workspace; lihat [File `.env` workspace](/id/gateway/security).
|
||||
|
||||
## Pemecahan masalah
|
||||
|
||||
- Jika bot tersambung tetapi tidak pernah membalas di channel, verifikasi `channels.irc.groups` **dan** apakah gating mention membuang pesan (`missing-mention`). Jika Anda ingin bot membalas tanpa ping, atur `requireMention:false` untuk channel tersebut.
|
||||
- Jika bot terhubung tetapi tidak pernah membalas di saluran, verifikasi `channels.irc.groups` **dan** apakah pembatasan mention menggugurkan pesan (`missing-mention`). Jika Anda ingin bot membalas tanpa ping, tetapkan `requireMention:false` untuk saluran tersebut.
|
||||
- Jika login gagal, verifikasi ketersediaan nick dan kata sandi server.
|
||||
- Jika TLS gagal di jaringan kustom, verifikasi pengaturan host/port dan sertifikat.
|
||||
- Jika TLS gagal pada jaringan kustom, verifikasi host/port dan penyiapan sertifikat.
|
||||
|
||||
## Terkait
|
||||
|
||||
- [Ikhtisar Channels](/id/channels) — semua channel yang didukung
|
||||
- [Ikhtisar Saluran](/id/channels) — semua saluran yang didukung
|
||||
- [Pairing](/id/channels/pairing) — autentikasi DM dan alur pairing
|
||||
- [Grup](/id/channels/groups) — perilaku chat grup dan gating mention
|
||||
- [Perutean Channel](/id/channels/channel-routing) — perutean sesi untuk pesan
|
||||
- [Grup](/id/channels/groups) — perilaku chat grup dan pembatasan mention
|
||||
- [Perutean Saluran](/id/channels/channel-routing) — perutean sesi untuk pesan
|
||||
- [Keamanan](/id/gateway/security) — model akses dan hardening
|
||||
|
||||
@ -3,39 +3,39 @@ read_when:
|
||||
- Menyiapkan kontrol akses DM
|
||||
- Memasangkan Node iOS/Android baru
|
||||
- Meninjau postur keamanan OpenClaw
|
||||
summary: 'Ikhtisar penyandingan: setujui siapa yang dapat mengirim pesan langsung kepada Anda + node mana yang dapat bergabung'
|
||||
summary: 'Ikhtisar penyandingan: setujui siapa yang dapat mengirim pesan langsung kepada Anda + Node mana yang dapat bergabung'
|
||||
title: Penyandingan
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T09:13:43Z"
|
||||
generated_at: "2026-05-04T02:21:46Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: bb68d87c0e1dfe7c9a6a6d9415f4c63625755fb43a2e22a1d1374ff0a63e49c4
|
||||
source_hash: 4fb27840f7c9ef55e7270cc29f813e6db90b240aa2180f30952eb9485f0f8874
|
||||
source_path: channels/pairing.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
“Pemasangan” adalah langkah persetujuan akses eksplisit OpenClaw.
|
||||
“Pairing” adalah langkah persetujuan akses eksplisit OpenClaw.
|
||||
Ini digunakan di dua tempat:
|
||||
|
||||
1. **Pemasangan DM** (siapa yang diizinkan berbicara dengan bot)
|
||||
2. **Pemasangan Node** (perangkat/node mana yang diizinkan bergabung ke jaringan Gateway)
|
||||
1. **Pairing DM** (siapa yang diizinkan berbicara dengan bot)
|
||||
2. **Pairing Node** (perangkat/Node mana yang diizinkan bergabung ke jaringan Gateway)
|
||||
|
||||
Konteks keamanan: [Keamanan](/id/gateway/security)
|
||||
|
||||
## 1) Pemasangan DM (akses chat masuk)
|
||||
## 1) Pairing DM (akses chat masuk)
|
||||
|
||||
Ketika channel dikonfigurasi dengan kebijakan DM `pairing`, pengirim yang tidak dikenal akan menerima kode singkat dan pesan mereka **tidak diproses** sampai Anda menyetujuinya.
|
||||
Ketika sebuah kanal dikonfigurasi dengan kebijakan DM `pairing`, pengirim yang tidak dikenal akan mendapatkan kode singkat dan pesan mereka **tidak diproses** sampai Anda menyetujuinya.
|
||||
|
||||
Kebijakan DM bawaan didokumentasikan di: [Keamanan](/id/gateway/security)
|
||||
Kebijakan DM default didokumentasikan di: [Keamanan](/id/gateway/security)
|
||||
|
||||
`dmPolicy: "open"` bersifat publik hanya ketika daftar izin DM efektif menyertakan `"*"`.
|
||||
Penyiapan dan validasi memerlukan wildcard tersebut untuk konfigurasi publik-terbuka. Jika state yang ada berisi `open` dengan entri `allowFrom` konkret, runtime tetap hanya menerima pengirim tersebut, dan persetujuan di penyimpanan pemasangan tidak memperluas akses `open`.
|
||||
`dmPolicy: "open"` bersifat publik hanya ketika allowlist DM efektif menyertakan `"*"`.
|
||||
Penyiapan dan validasi memerlukan wildcard tersebut untuk konfigurasi publik-terbuka. Jika state yang ada berisi `open` dengan entri `allowFrom` konkret, runtime tetap hanya mengizinkan pengirim tersebut, dan persetujuan pairing-store tidak memperluas akses `open`.
|
||||
|
||||
Kode pemasangan:
|
||||
Kode pairing:
|
||||
|
||||
- 8 karakter, huruf besar, tanpa karakter ambigu (`0O1I`).
|
||||
- **Kedaluwarsa setelah 1 jam**. Bot hanya mengirim pesan pemasangan ketika permintaan baru dibuat (kurang lebih sekali per jam per pengirim).
|
||||
- Permintaan pemasangan DM yang tertunda dibatasi secara bawaan menjadi **3 per channel**; permintaan tambahan diabaikan sampai salah satunya kedaluwarsa atau disetujui.
|
||||
- **Kedaluwarsa setelah 1 jam**. Bot hanya mengirim pesan pairing ketika permintaan baru dibuat (kira-kira sekali per jam per pengirim).
|
||||
- Permintaan pairing DM yang tertunda dibatasi hingga **3 per kanal** secara default; permintaan tambahan diabaikan sampai salah satunya kedaluwarsa atau disetujui.
|
||||
|
||||
### Setujui pengirim
|
||||
|
||||
@ -44,16 +44,16 @@ openclaw pairing list telegram
|
||||
openclaw pairing approve telegram <CODE>
|
||||
```
|
||||
|
||||
Jika belum ada pemilik perintah yang dikonfigurasi, menyetujui kode pemasangan DM juga akan melakukan bootstrap `commands.ownerAllowFrom` ke pengirim yang disetujui, seperti `telegram:123456789`.
|
||||
Ini memberi penyiapan pertama kali pemilik eksplisit untuk perintah istimewa dan prompt persetujuan exec. Setelah pemilik ada, persetujuan pemasangan berikutnya hanya memberikan akses DM; persetujuan itu tidak menambahkan pemilik lagi.
|
||||
Jika belum ada pemilik perintah yang dikonfigurasi, menyetujui kode pairing DM juga akan melakukan bootstrap `commands.ownerAllowFrom` ke pengirim yang disetujui, seperti `telegram:123456789`.
|
||||
Ini memberi penyiapan pertama kali pemilik eksplisit untuk perintah istimewa dan prompt persetujuan exec. Setelah pemilik ada, persetujuan pairing berikutnya hanya memberikan akses DM; persetujuan tersebut tidak menambahkan pemilik lagi.
|
||||
|
||||
Channel yang didukung: `bluebubbles`, `discord`, `feishu`, `googlechat`, `imessage`, `irc`, `line`, `matrix`, `mattermost`, `msteams`, `nextcloud-talk`, `nostr`, `openclaw-weixin`, `signal`, `slack`, `synology-chat`, `telegram`, `twitch`, `whatsapp`, `zalo`, `zalouser`.
|
||||
Kanal yang didukung: `bluebubbles`, `discord`, `feishu`, `googlechat`, `imessage`, `irc`, `line`, `matrix`, `mattermost`, `msteams`, `nextcloud-talk`, `nostr`, `openclaw-weixin`, `signal`, `slack`, `synology-chat`, `telegram`, `twitch`, `whatsapp`, `zalo`, `zalouser`.
|
||||
|
||||
### Grup pengirim yang dapat digunakan ulang
|
||||
|
||||
Gunakan `accessGroups` tingkat atas ketika kumpulan pengirim tepercaya yang sama harus diterapkan ke beberapa channel pesan atau ke daftar izin DM sekaligus grup.
|
||||
Gunakan `accessGroups` tingkat atas ketika kumpulan pengirim tepercaya yang sama harus berlaku untuk beberapa kanal pesan atau untuk allowlist DM dan grup.
|
||||
|
||||
Grup statis menggunakan `type: "message.senders"` dan dirujuk dengan `accessGroup:<name>` dari daftar izin channel:
|
||||
Grup statis menggunakan `type: "message.senders"` dan dirujuk dengan `accessGroup:<name>` dari allowlist kanal:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -76,54 +76,54 @@ Grup statis menggunakan `type: "message.senders"` dan dirujuk dengan `accessGrou
|
||||
|
||||
Grup akses didokumentasikan secara detail di sini: [Grup akses](/id/channels/access-groups)
|
||||
|
||||
### Tempat state disimpan
|
||||
### Lokasi state disimpan
|
||||
|
||||
Disimpan di bawah `~/.openclaw/credentials/`:
|
||||
|
||||
- Permintaan tertunda: `<channel>-pairing.json`
|
||||
- Penyimpanan daftar izin yang disetujui:
|
||||
- Penyimpanan allowlist yang disetujui:
|
||||
- Akun default: `<channel>-allowFrom.json`
|
||||
- Akun non-default: `<channel>-<accountId>-allowFrom.json`
|
||||
|
||||
Perilaku cakupan akun:
|
||||
|
||||
- Akun non-default hanya membaca/menulis file daftar izin bercakupan miliknya.
|
||||
- Akun default menggunakan file daftar izin tanpa cakupan yang bercakupan channel.
|
||||
- Akun non-default hanya membaca/menulis file allowlist bercakup miliknya.
|
||||
- Akun default menggunakan file allowlist tanpa cakupan yang bercakup kanal.
|
||||
|
||||
Perlakukan ini sebagai data sensitif (ini mengatur akses ke asisten Anda).
|
||||
Perlakukan ini sebagai sensitif (ini mengatur akses ke asisten Anda).
|
||||
|
||||
<Note>
|
||||
Penyimpanan daftar izin pemasangan adalah untuk akses DM. Otorisasi grup terpisah.
|
||||
Menyetujui kode pemasangan DM tidak otomatis mengizinkan pengirim tersebut menjalankan perintah grup atau mengontrol bot di grup. Bootstrap pemilik pertama adalah state konfigurasi terpisah di `commands.ownerAllowFrom`, dan pengiriman chat grup tetap mengikuti daftar izin grup channel tersebut (misalnya `groupAllowFrom`, `groups`, atau override per-grup atau per-topik tergantung channel).
|
||||
Penyimpanan allowlist pairing ditujukan untuk akses DM. Otorisasi grup terpisah.
|
||||
Menyetujui kode pairing DM tidak otomatis mengizinkan pengirim tersebut menjalankan perintah grup atau mengontrol bot di grup. Bootstrap pemilik pertama adalah state konfigurasi terpisah di `commands.ownerAllowFrom`, dan pengiriman chat grup tetap mengikuti allowlist grup kanal tersebut (misalnya `groupAllowFrom`, `groups`, atau override per-grup atau per-topik tergantung kanalnya).
|
||||
</Note>
|
||||
|
||||
## 2) Pemasangan perangkat Node (node iOS/Android/macOS/headless)
|
||||
## 2) Pairing perangkat Node (Node iOS/Android/macOS/headless)
|
||||
|
||||
Node terhubung ke Gateway sebagai **perangkat** dengan `role: node`. Gateway membuat permintaan pemasangan perangkat yang harus disetujui.
|
||||
Node terhubung ke Gateway sebagai **perangkat** dengan `role: node`. Gateway membuat permintaan pairing perangkat yang harus disetujui.
|
||||
|
||||
### Pasangkan melalui Telegram (direkomendasikan untuk iOS)
|
||||
### Pairing melalui Telegram (direkomendasikan untuk iOS)
|
||||
|
||||
Jika Anda menggunakan Plugin `device-pair`, Anda dapat melakukan pemasangan perangkat pertama kali sepenuhnya dari Telegram:
|
||||
Jika Anda menggunakan Plugin `device-pair`, Anda dapat melakukan pairing perangkat pertama kali sepenuhnya dari Telegram:
|
||||
|
||||
1. Di Telegram, kirim pesan ke bot Anda: `/pair`
|
||||
2. Bot membalas dengan dua pesan: pesan instruksi dan pesan **kode penyiapan** terpisah (mudah disalin/ditempel di Telegram).
|
||||
3. Di ponsel Anda, buka aplikasi iOS OpenClaw → Settings → Gateway.
|
||||
3. Di ponsel Anda, buka aplikasi OpenClaw iOS → Settings → Gateway.
|
||||
4. Tempel kode penyiapan dan hubungkan.
|
||||
5. Kembali di Telegram: `/pair pending` (tinjau ID permintaan, peran, dan cakupan), lalu setujui.
|
||||
|
||||
Kode penyiapan adalah payload JSON berkode base64 yang berisi:
|
||||
Kode penyiapan adalah payload JSON yang dikodekan base64 yang berisi:
|
||||
|
||||
- `url`: URL WebSocket Gateway (`ws://...` atau `wss://...`)
|
||||
- `bootstrapToken`: token bootstrap satu-perangkat berumur pendek yang digunakan untuk handshake pemasangan awal
|
||||
- `bootstrapToken`: token bootstrap perangkat tunggal berumur pendek yang digunakan untuk handshake pairing awal
|
||||
|
||||
Token bootstrap tersebut membawa profil bootstrap pemasangan bawaan:
|
||||
Token bootstrap tersebut membawa profil bootstrap pairing bawaan:
|
||||
|
||||
- token `node` yang diserahkan utama tetap `scopes: []`
|
||||
- token `operator` apa pun yang diserahkan tetap dibatasi ke daftar izin bootstrap:
|
||||
- token `node` yang diserahterimakan secara utama tetap `scopes: []`
|
||||
- token `operator` apa pun yang diserahterimakan tetap dibatasi pada allowlist bootstrap:
|
||||
`operator.approvals`, `operator.read`, `operator.talk.secrets`, `operator.write`
|
||||
- pemeriksaan cakupan bootstrap diberi prefiks peran, bukan satu kumpulan cakupan datar:
|
||||
entri cakupan operator hanya memenuhi permintaan operator, dan peran non-operator tetap harus meminta cakupan di bawah prefiks peran mereka sendiri
|
||||
- rotasi/pencabutan token berikutnya tetap dibatasi oleh kontrak peran yang disetujui untuk perangkat sekaligus cakupan operator sesi pemanggil
|
||||
entri cakupan operator hanya memenuhi permintaan operator, dan peran non-operator tetap harus meminta cakupan di bawah prefiks perannya sendiri
|
||||
- rotasi/pencabutan token berikutnya tetap dibatasi oleh kontrak peran perangkat yang disetujui dan cakupan operator sesi pemanggil
|
||||
|
||||
Perlakukan kode penyiapan seperti kata sandi selama masih valid.
|
||||
|
||||
@ -135,15 +135,17 @@ openclaw devices approve <requestId>
|
||||
openclaw devices reject <requestId>
|
||||
```
|
||||
|
||||
Jika perangkat yang sama mencoba lagi dengan detail autentikasi berbeda (misalnya peran/cakupan/kunci publik yang berbeda), permintaan tertunda sebelumnya digantikan dan `requestId` baru dibuat.
|
||||
Ketika persetujuan eksplisit ditolak karena sesi perangkat-paired yang menyetujui dibuka dengan cakupan hanya-pairing, CLI mencoba ulang permintaan yang sama dengan `operator.admin`. Ini memungkinkan perangkat paired yang sudah ada dan berkemampuan admin memulihkan pairing Control UI/browser baru tanpa mengedit `devices/paired.json` secara manual. Gateway tetap memvalidasi koneksi yang dicoba ulang; token yang tidak dapat mengautentikasi dengan `operator.admin` tetap diblokir.
|
||||
|
||||
Jika perangkat yang sama mencoba ulang dengan detail auth berbeda (misalnya peran/cakupan/kunci publik yang berbeda), permintaan tertunda sebelumnya digantikan dan `requestId` baru dibuat.
|
||||
|
||||
<Note>
|
||||
Perangkat yang sudah dipasangkan tidak mendapatkan akses yang lebih luas secara diam-diam. Jika perangkat terhubung ulang dan meminta cakupan lebih banyak atau peran yang lebih luas, OpenClaw mempertahankan persetujuan yang ada apa adanya dan membuat permintaan peningkatan baru yang tertunda. Gunakan `openclaw devices list` untuk membandingkan akses yang saat ini disetujui dengan akses yang baru diminta sebelum Anda menyetujui.
|
||||
Perangkat yang sudah paired tidak mendapatkan akses lebih luas secara diam-diam. Jika perangkat itu terhubung kembali sambil meminta lebih banyak cakupan atau peran yang lebih luas, OpenClaw mempertahankan persetujuan yang ada apa adanya dan membuat permintaan upgrade tertunda yang baru. Gunakan `openclaw devices list` untuk membandingkan akses yang saat ini disetujui dengan akses baru yang diminta sebelum Anda menyetujui.
|
||||
</Note>
|
||||
|
||||
### Persetujuan otomatis Node CIDR tepercaya opsional
|
||||
### Persetujuan otomatis Node trusted-CIDR opsional
|
||||
|
||||
Pemasangan perangkat tetap manual secara bawaan. Untuk jaringan node yang dikontrol ketat, Anda dapat memilih untuk mengaktifkan persetujuan otomatis Node pertama kali dengan CIDR eksplisit atau IP persis:
|
||||
Pairing perangkat tetap manual secara default. Untuk jaringan Node yang dikontrol ketat, Anda dapat memilih persetujuan otomatis Node pertama kali dengan CIDR eksplisit atau IP persis:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -157,25 +159,25 @@ Pemasangan perangkat tetap manual secara bawaan. Untuk jaringan node yang dikont
|
||||
}
|
||||
```
|
||||
|
||||
Ini hanya berlaku untuk permintaan pemasangan baru `role: node` tanpa cakupan yang diminta. Klien operator, browser, Control UI, dan WebChat tetap memerlukan persetujuan manual. Perubahan peran, cakupan, metadata, dan kunci publik tetap memerlukan persetujuan manual.
|
||||
Ini hanya berlaku untuk permintaan pairing `role: node` baru tanpa cakupan yang diminta. Klien operator, browser, Control UI, dan WebChat tetap memerlukan persetujuan manual. Perubahan peran, cakupan, metadata, dan kunci publik tetap memerlukan persetujuan manual.
|
||||
|
||||
### Penyimpanan state pemasangan Node
|
||||
### Penyimpanan state pairing Node
|
||||
|
||||
Disimpan di bawah `~/.openclaw/devices/`:
|
||||
|
||||
- `pending.json` (berumur pendek; permintaan tertunda kedaluwarsa)
|
||||
- `paired.json` (perangkat yang dipasangkan + token)
|
||||
- `paired.json` (perangkat paired + token)
|
||||
|
||||
### Catatan
|
||||
|
||||
- API legacy `node.pair.*` (CLI: `openclaw nodes pending|approve|reject|remove|rename`) adalah penyimpanan pemasangan terpisah milik gateway. Node WS tetap memerlukan pemasangan perangkat.
|
||||
- Rekaman pemasangan adalah sumber kebenaran tahan lama untuk peran yang disetujui. Token perangkat aktif tetap dibatasi ke kumpulan peran yang disetujui tersebut; entri token menyimpang di luar peran yang disetujui tidak membuat akses baru.
|
||||
- API legacy `node.pair.*` (CLI: `openclaw nodes pending|approve|reject|remove|rename`) adalah penyimpanan pairing terpisah milik gateway. Node WS tetap memerlukan pairing perangkat.
|
||||
- Catatan pairing adalah sumber kebenaran yang tahan lama untuk peran yang disetujui. Token perangkat aktif tetap dibatasi pada kumpulan peran yang disetujui tersebut; entri token tersasar di luar peran yang disetujui tidak membuat akses baru.
|
||||
|
||||
## Dokumen terkait
|
||||
|
||||
- Model keamanan + injeksi prompt: [Keamanan](/id/gateway/security)
|
||||
- Memperbarui dengan aman (jalankan doctor): [Memperbarui](/id/install/updating)
|
||||
- Konfigurasi channel:
|
||||
- Konfigurasi kanal:
|
||||
- Telegram: [Telegram](/id/channels/telegram)
|
||||
- WhatsApp: [WhatsApp](/id/channels/whatsapp)
|
||||
- Signal: [Signal](/id/channels/signal)
|
||||
|
||||
@ -2,21 +2,21 @@
|
||||
read_when:
|
||||
- Anda ingin menghubungkan OpenClaw ke QQ
|
||||
- Anda perlu menyiapkan kredensial QQ Bot
|
||||
- Anda ingin dukungan QQ Bot untuk obrolan grup atau obrolan pribadi
|
||||
- Anda menginginkan dukungan obrolan grup atau pribadi untuk QQ Bot
|
||||
summary: Penyiapan, konfigurasi, dan penggunaan QQ Bot
|
||||
title: Bot QQ
|
||||
title: bot QQ
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:27:32Z"
|
||||
generated_at: "2026-05-04T02:21:39Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 471c24110bf0ab8896d22f5bb5932ac4e03ff5169560c99ba6b9d1ca4025d9a8
|
||||
source_hash: e17fa0da2f6939ed28cac5f13b3e37e6c63b87a10250ff213f7a86685a6141d6
|
||||
source_path: channels/qqbot.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
QQ Bot terhubung ke OpenClaw melalui API QQ Bot resmi (Gateway WebSocket). Plugin ini mendukung chat privat C2C, @pesan grup, dan pesan saluran guild dengan media kaya (gambar, suara, video, file).
|
||||
QQ Bot terhubung ke OpenClaw melalui QQ Bot API resmi (Gateway WebSocket). Plugin ini mendukung obrolan privat C2C, @pesan grup, dan pesan saluran guild dengan media kaya (gambar, suara, video, file).
|
||||
|
||||
Status: Plugin yang dapat diunduh. Pesan langsung, chat grup, saluran guild, dan media didukung. Reaksi dan thread tidak didukung.
|
||||
Status: Plugin yang dapat diunduh. Pesan langsung, obrolan grup, saluran guild, dan media didukung. Reaksi dan utas tidak didukung.
|
||||
|
||||
## Instal
|
||||
|
||||
@ -28,11 +28,12 @@ openclaw plugins install @openclaw/qqbot
|
||||
|
||||
## Penyiapan
|
||||
|
||||
1. Buka [QQ Open Platform](https://q.qq.com/) dan pindai kode QR dengan QQ di ponsel Anda untuk mendaftar / masuk.
|
||||
1. Buka [QQ Open Platform](https://q.qq.com/) dan pindai kode QR dengan QQ di
|
||||
ponsel Anda untuk mendaftar / masuk.
|
||||
2. Klik **Create Bot** untuk membuat bot QQ baru.
|
||||
3. Temukan **AppID** dan **AppSecret** di halaman pengaturan bot, lalu salin.
|
||||
3. Temukan **AppID** dan **AppSecret** di halaman pengaturan bot lalu salin.
|
||||
|
||||
> AppSecret tidak disimpan sebagai teks biasa — jika Anda meninggalkan halaman tanpa menyimpannya,
|
||||
> AppSecret tidak disimpan sebagai teks polos — jika Anda meninggalkan halaman tanpa menyimpannya,
|
||||
> Anda harus membuat ulang yang baru.
|
||||
|
||||
4. Tambahkan saluran:
|
||||
@ -66,7 +67,7 @@ Konfigurasi minimal:
|
||||
}
|
||||
```
|
||||
|
||||
Variabel env akun default:
|
||||
Variabel lingkungan akun bawaan:
|
||||
|
||||
- `QQBOT_APP_ID`
|
||||
- `QQBOT_CLIENT_SECRET`
|
||||
@ -85,7 +86,7 @@ AppSecret berbasis file:
|
||||
}
|
||||
```
|
||||
|
||||
AppSecret SecretRef env:
|
||||
AppSecret SecretRef lingkungan:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -101,16 +102,16 @@ AppSecret SecretRef env:
|
||||
|
||||
Catatan:
|
||||
|
||||
- Fallback env hanya berlaku untuk akun QQ Bot default.
|
||||
- Fallback lingkungan hanya berlaku untuk akun QQ Bot bawaan.
|
||||
- `openclaw channels add --channel qqbot --token-file ...` hanya menyediakan
|
||||
AppSecret; AppID harus sudah diatur di konfigurasi atau `QQBOT_APP_ID`.
|
||||
- `clientSecret` juga menerima input SecretRef, bukan hanya string teks biasa.
|
||||
- `clientSecret` juga menerima masukan SecretRef, bukan hanya string teks polos.
|
||||
- String penanda lama `secretref:/...` bukan nilai `clientSecret` yang valid;
|
||||
gunakan objek SecretRef terstruktur seperti contoh di atas.
|
||||
|
||||
### Penyiapan multi-akun
|
||||
|
||||
Jalankan beberapa bot QQ dalam satu instance OpenClaw:
|
||||
Jalankan beberapa QQ bot dalam satu instance OpenClaw:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -131,7 +132,8 @@ Jalankan beberapa bot QQ dalam satu instance OpenClaw:
|
||||
}
|
||||
```
|
||||
|
||||
Setiap akun meluncurkan koneksi WebSocket sendiri dan mempertahankan cache token independen (diisolasi oleh `appId`).
|
||||
Setiap akun meluncurkan koneksi WebSocket-nya sendiri dan memelihara cache token
|
||||
independen (diisolasi berdasarkan `appId`).
|
||||
|
||||
Tambahkan bot kedua melalui CLI:
|
||||
|
||||
@ -139,9 +141,10 @@ Tambahkan bot kedua melalui CLI:
|
||||
openclaw channels add --channel qqbot --account bot2 --token "222222222:secret-of-bot-2"
|
||||
```
|
||||
|
||||
### Chat grup
|
||||
### Obrolan grup
|
||||
|
||||
Dukungan chat grup QQ Bot menggunakan OpenID grup QQ, bukan nama tampilan. Tambahkan bot ke grup, lalu sebut bot tersebut atau konfigurasikan grup agar berjalan tanpa mention.
|
||||
Dukungan obrolan grup QQ Bot menggunakan OpenID grup QQ, bukan nama tampilan. Tambahkan bot
|
||||
ke grup, lalu sebut bot tersebut atau konfigurasikan grup agar berjalan tanpa sebutan.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -168,24 +171,30 @@ Dukungan chat grup QQ Bot menggunakan OpenID grup QQ, bukan nama tampilan. Tamba
|
||||
}
|
||||
```
|
||||
|
||||
`groups["*"]` menetapkan default untuk setiap grup, dan entri konkret `groups.GROUP_OPENID` menimpa default tersebut untuk satu grup. Pengaturan grup mencakup:
|
||||
`groups["*"]` menetapkan bawaan untuk setiap grup, dan entri konkret
|
||||
`groups.GROUP_OPENID` menimpa bawaan tersebut untuk satu grup. Pengaturan grup
|
||||
mencakup:
|
||||
|
||||
- `requireMention`: mewajibkan @mention sebelum bot membalas. Default: `true`.
|
||||
- `ignoreOtherMentions`: membuang pesan yang menyebut orang lain tetapi tidak menyebut bot.
|
||||
- `historyLimit`: menyimpan pesan grup non-mention terbaru sebagai konteks untuk giliran berikutnya yang menyebut bot. Atur `0` untuk menonaktifkan.
|
||||
- `toolPolicy`: `full`, `restricted`, atau `none` untuk alat yang dicakup grup.
|
||||
- `requireMention`: mewajibkan @mention sebelum bot membalas. Bawaan: `true`.
|
||||
- `ignoreOtherMentions`: buang pesan yang menyebut orang lain tetapi bukan bot.
|
||||
- `historyLimit`: simpan pesan grup non-sebutan terbaru sebagai konteks untuk giliran berikutnya yang menyebut bot. Atur `0` untuk menonaktifkan.
|
||||
- `toolPolicy`: `full`, `restricted`, atau `none` untuk alat bercakupan grup.
|
||||
- `name`: label ramah yang digunakan dalam log dan konteks grup.
|
||||
- `prompt`: prompt perilaku per grup yang ditambahkan ke konteks agen.
|
||||
|
||||
Mode aktivasi adalah `mention` dan `always`. `requireMention: true` dipetakan ke `mention`; `requireMention: false` dipetakan ke `always`. Override aktivasi tingkat sesi, jika ada, mengalahkan konfigurasi.
|
||||
Mode aktivasi adalah `mention` dan `always`. `requireMention: true` dipetakan ke
|
||||
`mention`; `requireMention: false` dipetakan ke `always`. Penggantian aktivasi
|
||||
tingkat sesi, jika ada, mengalahkan konfigurasi.
|
||||
|
||||
Antrean masuk bersifat per peer. Peer grup mendapatkan batas antrean yang lebih besar, memprioritaskan pesan manusia di atas percakapan buatan bot saat penuh, dan menggabungkan lonjakan pesan grup normal menjadi satu giliran beratribusi. Perintah slash tetap berjalan satu per satu.
|
||||
Antrean masuk bersifat per rekan. Rekan grup mendapat batas antrean yang lebih besar, menjaga pesan
|
||||
manusia tetap di depan percakapan buatan bot saat penuh, dan menggabungkan ledakan pesan grup
|
||||
normal menjadi satu giliran dengan atribusi. Perintah slash tetap berjalan satu per satu.
|
||||
|
||||
### Suara (STT / TTS)
|
||||
|
||||
Dukungan STT dan TTS menggunakan konfigurasi dua tingkat dengan fallback prioritas:
|
||||
|
||||
| Pengaturan | Khusus Plugin | Fallback framework |
|
||||
| Pengaturan | Khusus Plugin | Fallback kerangka kerja |
|
||||
| ------- | -------------------------------------------------------- | ----------------------------- |
|
||||
| STT | `channels.qqbot.stt` | `tools.media.audio.models[0]` |
|
||||
| TTS | `channels.qqbot.tts`, `channels.qqbot.accounts.<id>.tts` | `messages.tts` |
|
||||
@ -204,7 +213,7 @@ Dukungan STT dan TTS menggunakan konfigurasi dua tingkat dengan fallback priorit
|
||||
voice: "your-voice",
|
||||
},
|
||||
accounts: {
|
||||
qq-main: {
|
||||
"qq-main": {
|
||||
tts: {
|
||||
providers: {
|
||||
openai: { voice: "shimmer" },
|
||||
@ -218,11 +227,16 @@ Dukungan STT dan TTS menggunakan konfigurasi dua tingkat dengan fallback priorit
|
||||
```
|
||||
|
||||
Atur `enabled: false` pada salah satunya untuk menonaktifkan.
|
||||
Override TTS tingkat akun menggunakan bentuk yang sama seperti `messages.tts` dan deep-merge di atas konfigurasi TTS saluran/global.
|
||||
Penggantian TTS tingkat akun menggunakan bentuk yang sama seperti `messages.tts` dan melakukan deep-merge
|
||||
di atas konfigurasi TTS saluran/global.
|
||||
|
||||
Lampiran suara QQ masuk diekspos ke agen sebagai metadata media audio sambil menjaga file suara mentah tetap di luar `MediaPaths` generik. Balasan teks biasa `[[audio_as_voice]]` menyintesis TTS dan mengirim pesan suara QQ native saat TTS dikonfigurasi.
|
||||
Lampiran suara QQ yang masuk diekspos ke agen sebagai metadata media audio sambil
|
||||
menjaga file suara mentah tetap berada di luar `MediaPaths` generik. Balasan teks polos
|
||||
`[[audio_as_voice]]` menyintesis TTS dan mengirim pesan suara QQ asli ketika TTS
|
||||
dikonfigurasi.
|
||||
|
||||
Perilaku unggah/transkode audio keluar juga dapat disetel dengan `channels.qqbot.audioFormatPolicy`:
|
||||
Perilaku unggah/transkode audio keluar juga dapat disesuaikan dengan
|
||||
`channels.qqbot.audioFormatPolicy`:
|
||||
|
||||
- `sttDirectFormats`
|
||||
- `uploadDirectFormats`
|
||||
@ -232,8 +246,8 @@ Perilaku unggah/transkode audio keluar juga dapat disetel dengan `channels.qqbot
|
||||
|
||||
| Format | Deskripsi |
|
||||
| -------------------------- | ------------------ |
|
||||
| `qqbot:c2c:OPENID` | Chat privat (C2C) |
|
||||
| `qqbot:group:GROUP_OPENID` | Chat grup |
|
||||
| `qqbot:c2c:OPENID` | Obrolan privat (C2C) |
|
||||
| `qqbot:group:GROUP_OPENID` | Obrolan grup |
|
||||
| `qqbot:channel:CHANNEL_ID` | Saluran guild |
|
||||
|
||||
> Setiap bot memiliki kumpulan OpenID pengguna sendiri. OpenID yang diterima oleh Bot A **tidak dapat**
|
||||
@ -243,57 +257,57 @@ Perilaku unggah/transkode audio keluar juga dapat disetel dengan `channels.qqbot
|
||||
|
||||
Perintah bawaan yang dicegat sebelum antrean AI:
|
||||
|
||||
| Perintah | Deskripsi |
|
||||
| Perintah | Deskripsi |
|
||||
| -------------- | -------------------------------------------------------------------------------------------------------- |
|
||||
| `/bot-ping` | Uji latensi |
|
||||
| `/bot-version` | Tampilkan versi framework OpenClaw |
|
||||
| `/bot-help` | Cantumkan semua perintah |
|
||||
| `/bot-me` | Tampilkan ID pengguna QQ pengirim (openid) untuk penyiapan `allowFrom`/`groupAllowFrom` |
|
||||
| `/bot-upgrade` | Tampilkan tautan panduan upgrade QQBot |
|
||||
| `/bot-logs` | Ekspor log Gateway terbaru sebagai file |
|
||||
| `/bot-approve` | Setujui tindakan QQ Bot yang tertunda (misalnya, mengonfirmasi unggahan C2C atau grup) melalui alur native. |
|
||||
| `/bot-ping` | Uji latensi |
|
||||
| `/bot-version` | Tampilkan versi kerangka kerja OpenClaw |
|
||||
| `/bot-help` | Cantumkan semua perintah |
|
||||
| `/bot-me` | Tampilkan ID pengguna QQ pengirim (openid) untuk penyiapan `allowFrom`/`groupAllowFrom` |
|
||||
| `/bot-upgrade` | Tampilkan tautan panduan peningkatan QQBot |
|
||||
| `/bot-logs` | Ekspor log Gateway terbaru sebagai file |
|
||||
| `/bot-approve` | Setujui tindakan QQ Bot yang tertunda (misalnya, mengonfirmasi unggahan C2C atau grup) melalui alur asli. |
|
||||
|
||||
Tambahkan `?` ke perintah apa pun untuk bantuan penggunaan (misalnya `/bot-upgrade ?`).
|
||||
|
||||
Perintah admin (`/bot-me`, `/bot-upgrade`, `/bot-logs`, `/bot-clear-storage`, `/bot-streaming`, `/bot-approve`) hanya untuk pesan langsung dan memerlukan openid pengirim dalam daftar `allowFrom` eksplisit non-wildcard. Wildcard `allowFrom: ["*"]` mengizinkan chat tetapi tidak memberikan akses perintah admin. Pesan grup dicocokkan terhadap `groupAllowFrom` terlebih dahulu dan fallback ke `allowFrom`. Menjalankan perintah admin di grup mengembalikan petunjuk alih-alih dibuang diam-diam.
|
||||
Perintah admin (`/bot-me`, `/bot-upgrade`, `/bot-logs`, `/bot-clear-storage`, `/bot-streaming`, `/bot-approve`) hanya untuk pesan langsung dan mengharuskan openid pengirim berada dalam daftar `allowFrom` eksplisit non-wildcard. Wildcard `allowFrom: ["*"]` mengizinkan obrolan tetapi tidak memberikan akses perintah admin. Pesan grup dicocokkan terhadap `groupAllowFrom` terlebih dahulu dan fallback ke `allowFrom`. Menjalankan perintah admin di grup mengembalikan petunjuk, bukan mengabaikannya diam-diam.
|
||||
|
||||
## Arsitektur mesin
|
||||
|
||||
QQ Bot dikirim sebagai mesin mandiri di dalam Plugin:
|
||||
|
||||
- Setiap akun memiliki stack sumber daya terisolasi (koneksi WebSocket, klien API, cache token, root penyimpanan media) yang dikunci oleh `appId`. Akun tidak pernah berbagi status masuk/keluar.
|
||||
- Logger multi-akun menandai baris log dengan akun pemilik sehingga diagnostik tetap dapat dipisahkan saat Anda menjalankan beberapa bot dalam satu Gateway.
|
||||
- Jalur inbound, outbound, dan bridge Gateway berbagi satu root payload media di bawah `~/.openclaw/media`, sehingga unggahan, unduhan, dan cache transkode berada di bawah satu direktori yang dijaga, bukan pohon per subsistem.
|
||||
- Pengiriman media kaya melewati satu jalur `sendMedia` untuk target C2C dan grup. File lokal dan buffer di atas ambang file besar menggunakan endpoint unggahan chunked QQ, sedangkan payload yang lebih kecil menggunakan API media sekali jalan.
|
||||
- Kredensial dapat dicadangkan dan dipulihkan sebagai bagian dari snapshot kredensial OpenClaw standar; mesin memasang ulang stack sumber daya setiap akun saat pemulihan tanpa memerlukan pasangan kode QR baru.
|
||||
- Setiap akun memiliki stack sumber daya terisolasi (koneksi WebSocket, klien API, cache token, root penyimpanan media) yang dikunci berdasarkan `appId`. Akun tidak pernah berbagi status masuk/keluar.
|
||||
- Pencatat multi-akun memberi tag baris log dengan akun pemilik agar diagnostik tetap dapat dipisahkan saat Anda menjalankan beberapa bot dalam satu Gateway.
|
||||
- Jalur masuk, keluar, dan jembatan Gateway berbagi satu root payload media di bawah `~/.openclaw/media`, sehingga unggahan, unduhan, dan cache transkode berada di bawah satu direktori terlindungi, bukan pohon per subsistem.
|
||||
- Pengiriman media kaya melewati satu jalur `sendMedia` untuk target C2C dan grup. File lokal dan buffer di atas ambang file besar menggunakan endpoint unggah bertahap QQ, sedangkan payload yang lebih kecil menggunakan API media sekali jalan.
|
||||
- Kredensial dapat dicadangkan dan dipulihkan sebagai bagian dari snapshot kredensial OpenClaw standar; mesin memasang kembali stack sumber daya setiap akun saat pemulihan tanpa memerlukan pasangan kode QR baru.
|
||||
|
||||
## Onboarding kode QR
|
||||
|
||||
Sebagai alternatif untuk menempelkan `AppID:AppSecret` secara manual, mesin mendukung alur onboarding kode QR untuk menautkan QQ Bot ke OpenClaw:
|
||||
|
||||
1. Jalankan jalur penyiapan QQ Bot (misalnya `openclaw channels add --channel qqbot`) dan pilih alur kode QR saat diminta.
|
||||
2. Pindai kode QR yang dihasilkan dengan aplikasi ponsel yang terhubung ke QQ Bot target.
|
||||
3. Setujui pairing di ponsel. OpenClaw menyimpan kredensial yang dikembalikan ke `credentials/` di bawah cakupan akun yang tepat.
|
||||
2. Pindai kode QR yang dihasilkan dengan aplikasi ponsel yang terikat ke QQ Bot target.
|
||||
3. Setujui pemasangan di ponsel. OpenClaw menyimpan kredensial yang dikembalikan ke `credentials/` di bawah cakupan akun yang benar.
|
||||
|
||||
Prompt persetujuan yang dihasilkan oleh bot itu sendiri (misalnya, alur "izinkan tindakan ini?" yang diekspos oleh API QQ Bot) muncul sebagai prompt native OpenClaw yang dapat Anda terima dengan `/bot-approve` alih-alih membalas melalui klien QQ mentah.
|
||||
Prompt persetujuan yang dibuat oleh bot itu sendiri (misalnya, alur "izinkan tindakan ini?" yang diekspos oleh QQ Bot API) muncul sebagai prompt OpenClaw asli yang dapat Anda terima dengan `/bot-approve`, bukan membalas melalui klien QQ mentah.
|
||||
|
||||
## Pemecahan masalah
|
||||
|
||||
- **Bot membalas "gone to Mars":** kredensial tidak dikonfigurasi atau Gateway belum dimulai.
|
||||
- **Bot membalas "gone to Mars":** kredensial belum dikonfigurasi atau Gateway belum dimulai.
|
||||
- **Tidak ada pesan masuk:** verifikasi `appId` dan `clientSecret` sudah benar, dan
|
||||
bot diaktifkan di QQ Open Platform.
|
||||
- **Balasan mandiri berulang:** OpenClaw mencatat indeks ref keluar QQ sebagai
|
||||
buatan bot dan mengabaikan event masuk yang `msgIdx` saat ini cocok dengan
|
||||
akun bot yang sama. Ini mencegah loop echo platform sambil tetap mengizinkan pengguna
|
||||
- **Balasan diri berulang:** OpenClaw mencatat indeks referensi keluar QQ sebagai
|
||||
buatan bot dan mengabaikan peristiwa masuk yang `msgIdx` saat ini cocok dengan
|
||||
akun bot yang sama. Ini mencegah loop gema platform sambil tetap memungkinkan pengguna
|
||||
mengutip atau membalas pesan bot sebelumnya.
|
||||
- **Penyiapan dengan `--token-file` masih menunjukkan belum dikonfigurasi:** `--token-file` hanya mengatur
|
||||
AppSecret. Anda masih memerlukan `appId` dalam konfigurasi atau `QQBOT_APP_ID`.
|
||||
- **Penyiapan dengan `--token-file` masih menampilkan belum dikonfigurasi:** `--token-file` hanya mengatur
|
||||
AppSecret. Anda tetap memerlukan `appId` di konfigurasi atau `QQBOT_APP_ID`.
|
||||
- **Pesan proaktif tidak tiba:** QQ dapat mencegat pesan yang dimulai bot jika
|
||||
pengguna belum berinteraksi baru-baru ini.
|
||||
- **Suara tidak ditranskripsi:** pastikan STT dikonfigurasi dan provider dapat dijangkau.
|
||||
- **Suara tidak ditranskripsikan:** pastikan STT dikonfigurasi dan penyedia dapat dijangkau.
|
||||
|
||||
## Terkait
|
||||
|
||||
- [Pairing](/id/channels/pairing)
|
||||
- [Pemasangan](/id/channels/pairing)
|
||||
- [Grup](/id/channels/groups)
|
||||
- [Pemecahan masalah saluran](/id/channels/troubleshooting)
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,40 +1,40 @@
|
||||
---
|
||||
read_when:
|
||||
- Mengerjakan fitur kanal Tlon/Urbit
|
||||
- Mengerjakan fitur saluran Tlon/Urbit
|
||||
summary: Status dukungan, kemampuan, dan konfigurasi Tlon/Urbit
|
||||
title: Tlon
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T22:16:40Z"
|
||||
generated_at: "2026-05-04T02:22:14Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 30915170786fc1ee8b84fb8be2ea42280262923064cfa9ca7107036096a13add
|
||||
source_hash: 1718044541b431ff2437508e7e6659c14206f4aa84ab8b207e0d791dea2a48c5
|
||||
source_path: channels/tlon.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Tlon adalah messenger terdesentralisasi yang dibangun di atas Urbit. OpenClaw terhubung ke ship Urbit Anda dan dapat
|
||||
merespons DM serta pesan chat grup. Balasan grup secara default memerlukan mention @ dan dapat
|
||||
dibatasi lebih lanjut melalui allowlist.
|
||||
menanggapi DM dan pesan obrolan grup. Balasan grup memerlukan sebutan @ secara default dan dapat
|
||||
dibatasi lebih lanjut melalui daftar izin.
|
||||
|
||||
Status: plugin bawaan. DM, mention grup, balasan thread, pemformatan rich text, dan
|
||||
unggahan gambar didukung. Reaksi dan polling belum didukung.
|
||||
Status: Plugin terbundel. DM, sebutan grup, balasan utas, pemformatan teks kaya, dan
|
||||
unggahan gambar didukung. Reaksi dan jajak pendapat belum didukung.
|
||||
|
||||
## Plugin bawaan
|
||||
## Plugin terbundel
|
||||
|
||||
Tlon dikirim sebagai plugin bawaan dalam rilis OpenClaw saat ini, sehingga build
|
||||
paket normal tidak memerlukan instalasi terpisah.
|
||||
Tlon dikirim sebagai Plugin terbundel dalam rilis OpenClaw saat ini, sehingga build paket
|
||||
normal tidak memerlukan instalasi terpisah.
|
||||
|
||||
Jika Anda menggunakan build lama atau instalasi kustom yang mengecualikan Tlon, instal
|
||||
paket npm saat ini:
|
||||
|
||||
Instal melalui CLI (registry npm):
|
||||
Instal melalui CLI (registri npm):
|
||||
|
||||
```bash
|
||||
openclaw plugins install @openclaw/tlon
|
||||
```
|
||||
|
||||
Gunakan paket polos untuk mengikuti tag rilis resmi saat ini. Sematkan versi yang tepat
|
||||
hanya saat Anda memerlukan instalasi yang dapat direproduksi.
|
||||
Gunakan paket polos untuk mengikuti tag rilis resmi saat ini. Sematkan versi
|
||||
persis hanya ketika Anda membutuhkan instalasi yang dapat direproduksi.
|
||||
|
||||
Checkout lokal (saat menjalankan dari repo git):
|
||||
|
||||
@ -46,13 +46,13 @@ Detail: [Plugin](/id/tools/plugin)
|
||||
|
||||
## Penyiapan
|
||||
|
||||
1. Pastikan plugin Tlon tersedia.
|
||||
- Rilis OpenClaw paket saat ini sudah menyertakannya.
|
||||
1. Pastikan Plugin Tlon tersedia.
|
||||
- Rilis paket OpenClaw saat ini sudah membundelnya.
|
||||
- Instalasi lama/kustom dapat menambahkannya secara manual dengan perintah di atas.
|
||||
2. Kumpulkan URL ship dan kode login Anda.
|
||||
3. Konfigurasikan `channels.tlon`.
|
||||
4. Mulai ulang gateway.
|
||||
5. Kirim DM ke bot atau mention bot di channel grup.
|
||||
4. Mulai ulang Gateway.
|
||||
5. Kirim DM ke bot atau sebut bot di channel grup.
|
||||
|
||||
Konfigurasi minimal (satu akun):
|
||||
|
||||
@ -74,7 +74,7 @@ Konfigurasi minimal (satu akun):
|
||||
|
||||
Secara default, OpenClaw memblokir hostname dan rentang IP privat/internal untuk perlindungan SSRF.
|
||||
Jika ship Anda berjalan di jaringan privat (localhost, IP LAN, atau hostname internal),
|
||||
Anda harus ikut serta secara eksplisit:
|
||||
Anda harus memilih ikut serta secara eksplisit:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -124,7 +124,7 @@ Nonaktifkan penemuan otomatis:
|
||||
|
||||
## Kontrol akses
|
||||
|
||||
Allowlist DM (kosong = DM tidak diizinkan, gunakan `ownerShip` untuk alur persetujuan):
|
||||
Daftar izin DM (kosong = tidak ada DM yang diizinkan, gunakan `ownerShip` untuk alur persetujuan):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -159,9 +159,9 @@ Otorisasi grup (dibatasi secara default):
|
||||
}
|
||||
```
|
||||
|
||||
## Sistem pemilik dan persetujuan
|
||||
## Pemilik dan sistem persetujuan
|
||||
|
||||
Tetapkan ship pemilik untuk menerima permintaan persetujuan saat pengguna tanpa otorisasi mencoba berinteraksi:
|
||||
Atur ship pemilik untuk menerima permintaan persetujuan ketika pengguna yang tidak berwenang mencoba berinteraksi:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -177,10 +177,10 @@ Ship pemilik **secara otomatis diotorisasi di mana saja** — undangan DM diteri
|
||||
pesan channel selalu diizinkan. Anda tidak perlu menambahkan pemilik ke `dmAllowlist` atau
|
||||
`defaultAuthorizedShips`.
|
||||
|
||||
Saat ditetapkan, pemilik menerima notifikasi DM untuk:
|
||||
Ketika diatur, pemilik menerima notifikasi DM untuk:
|
||||
|
||||
- Permintaan DM dari ship yang tidak ada dalam allowlist
|
||||
- Mention di channel tanpa otorisasi
|
||||
- Permintaan DM dari ship yang tidak ada dalam daftar izin
|
||||
- Sebutan di channel tanpa otorisasi
|
||||
- Permintaan undangan grup
|
||||
|
||||
## Pengaturan terima otomatis
|
||||
@ -197,55 +197,59 @@ Terima otomatis undangan DM (untuk ship dalam dmAllowlist):
|
||||
}
|
||||
```
|
||||
|
||||
Terima otomatis undangan grup:
|
||||
Terima otomatis undangan grup dari ship tepercaya:
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
tlon: {
|
||||
autoAcceptGroupInvites: true,
|
||||
groupInviteAllowlist: ["~zod"],
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## Target pengiriman (CLI/cron)
|
||||
`autoAcceptGroupInvites` gagal tertutup ketika `groupInviteAllowlist` kosong. Atur
|
||||
daftar izin ke ship yang undangan grupnya harus diterima secara otomatis.
|
||||
|
||||
Gunakan ini dengan `openclaw message send` atau pengiriman cron:
|
||||
## Target pengiriman (CLI/Cron)
|
||||
|
||||
Gunakan ini dengan `openclaw message send` atau pengiriman Cron:
|
||||
|
||||
- DM: `~sampel-palnet` atau `dm/~sampel-palnet`
|
||||
- Grup: `chat/~host-ship/channel` atau `group:~host-ship/channel`
|
||||
|
||||
## Skill bawaan
|
||||
## Skill terbundel
|
||||
|
||||
Plugin Tlon menyertakan skill bawaan ([`@tloncorp/tlon-skill`](https://github.com/tloncorp/tlon-skill))
|
||||
Plugin Tlon menyertakan skill terbundel ([`@tloncorp/tlon-skill`](https://github.com/tloncorp/tlon-skill))
|
||||
yang menyediakan akses CLI ke operasi Tlon:
|
||||
|
||||
- **Kontak**: dapatkan/perbarui profil, tampilkan daftar kontak
|
||||
- **Channel**: tampilkan daftar, buat, posting pesan, ambil riwayat
|
||||
- **Grup**: tampilkan daftar, buat, kelola anggota
|
||||
- **DM**: kirim pesan, beri reaksi pada pesan
|
||||
- **Reaksi**: tambah/hapus reaksi emoji pada posting dan DM
|
||||
- **Pengaturan**: kelola izin plugin melalui perintah slash
|
||||
- **Kontak**: dapatkan/perbarui profil, cantumkan kontak
|
||||
- **Channel**: cantumkan, buat, kirim pesan, ambil riwayat
|
||||
- **Grup**: cantumkan, buat, kelola anggota
|
||||
- **DM**: kirim pesan, beri reaksi ke pesan
|
||||
- **Reaksi**: tambah/hapus reaksi emoji ke postingan dan DM
|
||||
- **Pengaturan**: kelola izin Plugin melalui perintah slash
|
||||
|
||||
Skill tersedia secara otomatis saat plugin diinstal.
|
||||
Skill tersedia secara otomatis ketika Plugin diinstal.
|
||||
|
||||
## Kapabilitas
|
||||
|
||||
| Fitur | Status |
|
||||
| --------------- | --------------------------------------- |
|
||||
| Pesan langsung | ✅ Didukung |
|
||||
| Grup/channel | ✅ Didukung (berbasis mention secara default) |
|
||||
| Thread | ✅ Didukung (balasan otomatis dalam thread) |
|
||||
| Rich text | ✅ Markdown dikonversi ke format Tlon |
|
||||
| Gambar | ✅ Diunggah ke penyimpanan Tlon |
|
||||
| Reaksi | ✅ Melalui [skill bawaan](#bundled-skill) |
|
||||
| Polling | ❌ Belum didukung |
|
||||
| Perintah native | ✅ Didukung (khusus pemilik secara default) |
|
||||
| Fitur | Status |
|
||||
| --------------- | ------------------------------------------ |
|
||||
| Pesan langsung | ✅ Didukung |
|
||||
| Grup/channel | ✅ Didukung (dibatasi sebutan secara default) |
|
||||
| Utas | ✅ Didukung (balasan otomatis dalam utas) |
|
||||
| Teks kaya | ✅ Markdown dikonversi ke format Tlon |
|
||||
| Gambar | ✅ Diunggah ke penyimpanan Tlon |
|
||||
| Reaksi | ✅ Melalui [skill terbundel](#bundled-skill) |
|
||||
| Jajak pendapat | ❌ Belum didukung |
|
||||
| Perintah native | ✅ Didukung (hanya pemilik secara default) |
|
||||
|
||||
## Pemecahan masalah
|
||||
|
||||
Jalankan urutan ini terlebih dahulu:
|
||||
Jalankan tangga ini terlebih dahulu:
|
||||
|
||||
```bash
|
||||
openclaw status
|
||||
@ -258,8 +262,8 @@ Kegagalan umum:
|
||||
|
||||
- **DM diabaikan**: pengirim tidak ada di `dmAllowlist` dan tidak ada `ownerShip` yang dikonfigurasi untuk alur persetujuan.
|
||||
- **Pesan grup diabaikan**: channel tidak ditemukan atau pengirim tidak diotorisasi.
|
||||
- **Kesalahan koneksi**: periksa apakah URL ship dapat dijangkau; aktifkan `allowPrivateNetwork` untuk ship lokal.
|
||||
- **Kesalahan autentikasi**: verifikasi kode login masih berlaku (kode berotasi).
|
||||
- **Kesalahan koneksi**: periksa URL ship dapat dijangkau; aktifkan `allowPrivateNetwork` untuk ship lokal.
|
||||
- **Kesalahan auth**: verifikasi kode login masih berlaku (kode berotasi).
|
||||
|
||||
## Referensi konfigurasi
|
||||
|
||||
@ -274,25 +278,26 @@ Opsi penyedia:
|
||||
- `channels.tlon.allowPrivateNetwork`: izinkan URL localhost/LAN (bypass SSRF).
|
||||
- `channels.tlon.ownerShip`: ship pemilik untuk sistem persetujuan (selalu diotorisasi).
|
||||
- `channels.tlon.dmAllowlist`: ship yang diizinkan mengirim DM (kosong = tidak ada).
|
||||
- `channels.tlon.autoAcceptDmInvites`: terima otomatis DM dari ship dalam allowlist.
|
||||
- `channels.tlon.autoAcceptGroupInvites`: terima otomatis semua undangan grup.
|
||||
- `channels.tlon.autoAcceptDmInvites`: terima otomatis DM dari ship yang ada di daftar izin.
|
||||
- `channels.tlon.autoAcceptGroupInvites`: terima otomatis undangan grup dari ship yang ada di daftar izin.
|
||||
- `channels.tlon.groupInviteAllowlist`: ship yang undangan grupnya boleh diterima otomatis.
|
||||
- `channels.tlon.autoDiscoverChannels`: temukan channel grup secara otomatis (default: true).
|
||||
- `channels.tlon.groupChannels`: nest channel yang disematkan secara manual.
|
||||
- `channels.tlon.defaultAuthorizedShips`: ship yang diotorisasi untuk semua channel.
|
||||
- `channels.tlon.authorization.channelRules`: aturan autentikasi per channel.
|
||||
- `channels.tlon.authorization.channelRules`: aturan auth per channel.
|
||||
- `channels.tlon.showModelSignature`: tambahkan nama model ke pesan.
|
||||
|
||||
## Catatan
|
||||
|
||||
- Balasan grup memerlukan mention (mis. `~your-bot-ship`) untuk merespons.
|
||||
- Balasan thread: jika pesan masuk berada dalam thread, OpenClaw membalas di dalam thread.
|
||||
- Rich text: pemformatan Markdown (tebal, miring, kode, header, daftar) dikonversi ke format native Tlon.
|
||||
- Balasan grup memerlukan sebutan (mis. `~your-bot-ship`) untuk menanggapi.
|
||||
- Balasan utas: jika pesan masuk berada dalam utas, OpenClaw membalas di dalam utas.
|
||||
- Teks kaya: pemformatan Markdown (tebal, miring, kode, header, daftar) dikonversi ke format native Tlon.
|
||||
- Gambar: URL diunggah ke penyimpanan Tlon dan disematkan sebagai blok gambar.
|
||||
|
||||
## Terkait
|
||||
|
||||
- [Ikhtisar Channel](/id/channels) — semua channel yang didukung
|
||||
- [Pairing](/id/channels/pairing) — autentikasi DM dan alur pairing
|
||||
- [Grup](/id/channels/groups) — perilaku chat grup dan gating mention
|
||||
- [Pemasangan](/id/channels/pairing) — autentikasi DM dan alur pemasangan
|
||||
- [Grup](/id/channels/groups) — perilaku obrolan grup dan pembatasan sebutan
|
||||
- [Perutean Channel](/id/channels/channel-routing) — perutean sesi untuk pesan
|
||||
- [Keamanan](/id/gateway/security) — model akses dan hardening
|
||||
- [Keamanan](/id/gateway/security) — model akses dan pengerasan
|
||||
|
||||
@ -2,20 +2,20 @@
|
||||
read_when:
|
||||
- Transport kanal menunjukkan terhubung tetapi balasan gagal
|
||||
- Anda memerlukan pemeriksaan khusus saluran sebelum dokumentasi penyedia yang mendalam
|
||||
summary: Pemecahan masalah cepat di tingkat saluran dengan ciri kegagalan dan perbaikan per saluran
|
||||
summary: Pemecahan masalah tingkat saluran secara cepat dengan pola kegagalan dan perbaikan per saluran
|
||||
title: Pemecahan masalah saluran
|
||||
x-i18n:
|
||||
generated_at: "2026-04-30T09:36:59Z"
|
||||
generated_at: "2026-05-04T02:22:36Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 6024f2ae0a058b2296758c237c912a5cd8ea6bbafea33cc201690cc081efcbee
|
||||
source_hash: a3a0737156ae83897c44d18505e0355a5d8e5700106b984496d94874c270deb2
|
||||
source_path: channels/troubleshooting.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Gunakan halaman ini ketika channel terhubung tetapi perilakunya salah.
|
||||
Gunakan halaman ini saat saluran terhubung tetapi perilakunya salah.
|
||||
|
||||
## Tangga perintah
|
||||
## Urutan perintah
|
||||
|
||||
Jalankan ini secara berurutan terlebih dahulu:
|
||||
|
||||
@ -27,23 +27,23 @@ openclaw doctor
|
||||
openclaw channels status --probe
|
||||
```
|
||||
|
||||
Baseline sehat:
|
||||
Dasar acuan yang sehat:
|
||||
|
||||
- `Runtime: running`
|
||||
- `Connectivity probe: ok`
|
||||
- `Capability: read-only`, `write-capable`, atau `admin-capable`
|
||||
- Probe channel menunjukkan transport terhubung dan, jika didukung, `works` atau `audit ok`
|
||||
- Probe saluran menampilkan transport terhubung dan, jika didukung, `works` atau `audit ok`
|
||||
|
||||
## WhatsApp
|
||||
|
||||
### Tanda kegagalan WhatsApp
|
||||
|
||||
| Gejala | Pemeriksaan tercepat | Perbaikan |
|
||||
| Gejala | Pemeriksaan tercepat | Perbaikan |
|
||||
| ------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Terhubung tetapi tidak ada balasan DM | `openclaw pairing list whatsapp` | Setujui pengirim atau ubah kebijakan/allowlist DM. |
|
||||
| Pesan grup diabaikan | Periksa `requireMention` + pola mention di config | Mention bot atau longgarkan kebijakan mention untuk grup tersebut. |
|
||||
| Login QR habis waktu dengan 408 | Periksa env `HTTPS_PROXY` / `HTTP_PROXY` Gateway | Tetapkan proxy yang dapat dijangkau; gunakan `NO_PROXY` hanya untuk bypass. |
|
||||
| Loop disconnect/relogin acak | `openclaw channels status --probe` + log | Reconnect terbaru ditandai meskipun saat ini terhubung; pantau log, restart Gateway, lalu tautkan ulang jika flapping berlanjut. |
|
||||
| Terhubung tetapi tidak ada balasan DM | `openclaw pairing list whatsapp` | Setujui pengirim atau ubah kebijakan/daftar izin DM. |
|
||||
| Pesan grup diabaikan | Periksa `requireMention` + pola mention di konfigurasi | Mention bot atau longgarkan kebijakan mention untuk grup tersebut. |
|
||||
| Login QR habis waktu dengan 408 | Periksa env `HTTPS_PROXY` / `HTTP_PROXY` Gateway | Tetapkan proxy yang dapat dijangkau; gunakan `NO_PROXY` hanya untuk bypass. |
|
||||
| Loop putus sambung/login ulang acak | `openclaw channels status --probe` + log | Rekoneksi terbaru ditandai meskipun saat ini terhubung; pantau log, mulai ulang Gateway, lalu tautkan ulang jika flapping berlanjut. |
|
||||
|
||||
Pemecahan masalah lengkap: [Pemecahan masalah WhatsApp](/id/channels/whatsapp#troubleshooting)
|
||||
|
||||
@ -51,15 +51,15 @@ Pemecahan masalah lengkap: [Pemecahan masalah WhatsApp](/id/channels/whatsapp#tr
|
||||
|
||||
### Tanda kegagalan Telegram
|
||||
|
||||
| Gejala | Pemeriksaan tercepat | Perbaikan |
|
||||
| ------------------------------------ | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `/start` tetapi tidak ada alur balasan yang dapat digunakan | `openclaw pairing list telegram` | Setujui pairing atau ubah kebijakan DM. |
|
||||
| Bot online tetapi grup tetap diam | Verifikasi persyaratan mention dan mode privasi bot | Nonaktifkan mode privasi untuk visibilitas grup atau mention bot. |
|
||||
| Kegagalan pengiriman dengan error jaringan | Periksa log untuk kegagalan panggilan API Telegram | Perbaiki routing DNS/IPv6/proxy ke `api.telegram.org`. |
|
||||
| Startup melaporkan `getMe returned 401` | Periksa sumber token yang dikonfigurasi | Salin ulang atau buat ulang token BotFather dan perbarui `botToken`, `tokenFile`, atau akun default `TELEGRAM_BOT_TOKEN`. |
|
||||
| Polling macet atau reconnect lambat | `openclaw logs --follow` untuk diagnostik polling | Upgrade; jika restart adalah positif palsu, sesuaikan `pollingStallThresholdMs`. Stalled persisten tetap mengarah ke proxy/DNS/IPv6. |
|
||||
| `setMyCommands` ditolak saat startup | Periksa log untuk `BOT_COMMANDS_TOO_MUCH` | Kurangi perintah Telegram dari Plugin/Skills/kustom atau nonaktifkan menu native. |
|
||||
| Setelah upgrade, allowlist memblokir Anda | `openclaw security audit` dan allowlist config | Jalankan `openclaw doctor --fix` atau ganti `@username` dengan ID pengirim numerik. |
|
||||
| Gejala | Pemeriksaan tercepat | Perbaikan |
|
||||
| ------------------------------------ | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `/start` tetapi tidak ada alur balasan yang dapat digunakan | `openclaw pairing list telegram` | Setujui pairing atau ubah kebijakan DM. |
|
||||
| Bot online tetapi grup tetap diam | Verifikasi persyaratan mention dan mode privasi bot | Nonaktifkan mode privasi agar grup terlihat atau mention bot. |
|
||||
| Kegagalan pengiriman dengan kesalahan jaringan | Periksa log untuk kegagalan panggilan API Telegram | Perbaiki perutean DNS/IPv6/proxy ke `api.telegram.org`. |
|
||||
| Startup melaporkan `getMe returned 401` | Periksa sumber token yang dikonfigurasi | Salin ulang atau buat ulang token BotFather dan perbarui `botToken`, `tokenFile`, atau akun bawaan `TELEGRAM_BOT_TOKEN`. |
|
||||
| Polling macet atau lambat terhubung ulang | `openclaw logs --follow` untuk diagnostik polling | Tingkatkan versi; jika restart adalah positif palsu, sesuaikan `pollingStallThresholdMs`. Kemacetan yang persisten tetap mengarah ke proxy/DNS/IPv6. |
|
||||
| `setMyCommands` ditolak saat startup | Periksa log untuk `BOT_COMMANDS_TOO_MUCH` | Kurangi perintah Telegram Plugin/skill/kustom atau nonaktifkan menu native. |
|
||||
| Setelah peningkatan versi daftar izin memblokir Anda | `openclaw security audit` dan daftar izin konfigurasi | Jalankan `openclaw doctor --fix` atau ganti `@username` dengan ID pengirim numerik. |
|
||||
|
||||
Pemecahan masalah lengkap: [Pemecahan masalah Telegram](/id/channels/telegram#troubleshooting)
|
||||
|
||||
@ -67,11 +67,12 @@ Pemecahan masalah lengkap: [Pemecahan masalah Telegram](/id/channels/telegram#tr
|
||||
|
||||
### Tanda kegagalan Discord
|
||||
|
||||
| Gejala | Pemeriksaan tercepat | Perbaikan |
|
||||
| ------------------------------- | ----------------------------------- | ---------------------------------------------------------- |
|
||||
| Bot online tetapi tidak ada balasan guild | `openclaw channels status --probe` | Izinkan guild/channel dan verifikasi intent konten pesan. |
|
||||
| Pesan grup diabaikan | Periksa log untuk drop gating mention | Mention bot atau setel `requireMention: false` guild/channel. |
|
||||
| Balasan DM hilang | `openclaw pairing list discord` | Setujui pairing DM atau sesuaikan kebijakan DM. |
|
||||
| Gejala | Pemeriksaan tercepat | Perbaikan |
|
||||
| ----------------------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Bot online tetapi tidak ada balasan server | `openclaw channels status --probe` | Izinkan server/saluran dan verifikasi intent konten pesan. |
|
||||
| Pesan grup diabaikan | Periksa log untuk drop akibat gating mention | Mention bot atau atur `requireMention: false` untuk server/saluran. |
|
||||
| Ada penggunaan pengetikan/token tetapi tidak ada pesan Discord | Log sesi menampilkan teks asisten dengan `didSendViaMessagingTool: false` | Model menjawab secara privat alih-alih memanggil alat pesan. Gunakan model yang andal untuk pemanggilan alat, atau atur `messages.groupChat.visibleReplies: "automatic"` agar otomatis memposting. |
|
||||
| Balasan DM hilang | `openclaw pairing list discord` | Setujui pairing DM atau sesuaikan kebijakan DM. |
|
||||
|
||||
Pemecahan masalah lengkap: [Pemecahan masalah Discord](/id/channels/discord#troubleshooting)
|
||||
|
||||
@ -79,11 +80,11 @@ Pemecahan masalah lengkap: [Pemecahan masalah Discord](/id/channels/discord#trou
|
||||
|
||||
### Tanda kegagalan Slack
|
||||
|
||||
| Gejala | Pemeriksaan tercepat | Perbaikan |
|
||||
| -------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Socket mode terhubung tetapi tidak ada respons | `openclaw channels status --probe` | Verifikasi token app + token bot dan scope yang diperlukan; pantau `botTokenStatus` / `appTokenStatus = configured_unavailable` pada setup berbasis SecretRef. |
|
||||
| DM diblokir | `openclaw pairing list slack` | Setujui pairing atau longgarkan kebijakan DM. |
|
||||
| Pesan channel diabaikan | Periksa `groupPolicy` dan allowlist channel | Izinkan channel atau ubah kebijakan ke `open`. |
|
||||
| Gejala | Pemeriksaan tercepat | Perbaikan |
|
||||
| -------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| Mode soket terhubung tetapi tidak ada respons | `openclaw channels status --probe` | Verifikasi token aplikasi + token bot dan cakupan yang diperlukan; pantau `botTokenStatus` / `appTokenStatus = configured_unavailable` pada penyiapan berbasis SecretRef. |
|
||||
| DM diblokir | `openclaw pairing list slack` | Setujui pairing atau longgarkan kebijakan DM. |
|
||||
| Pesan saluran diabaikan | Periksa `groupPolicy` dan daftar izin saluran | Izinkan saluran atau ubah kebijakan ke `open`. |
|
||||
|
||||
Pemecahan masalah lengkap: [Pemecahan masalah Slack](/id/channels/slack#troubleshooting)
|
||||
|
||||
@ -91,11 +92,11 @@ Pemecahan masalah lengkap: [Pemecahan masalah Slack](/id/channels/slack#troubles
|
||||
|
||||
### Tanda kegagalan iMessage dan BlueBubbles
|
||||
|
||||
| Gejala | Pemeriksaan tercepat | Perbaikan |
|
||||
| -------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------- |
|
||||
| Tidak ada event masuk | Verifikasi keterjangkauan webhook/server dan izin app | Perbaiki URL Webhook atau status server BlueBubbles. |
|
||||
| Dapat mengirim tetapi tidak menerima di macOS | Periksa izin privasi macOS untuk automasi Messages | Berikan ulang izin TCC dan restart proses channel. |
|
||||
| Pengirim DM diblokir | `openclaw pairing list imessage` atau `openclaw pairing list bluebubbles` | Setujui pairing atau perbarui allowlist. |
|
||||
| Gejala | Pemeriksaan tercepat | Perbaikan |
|
||||
| -------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------- |
|
||||
| Tidak ada peristiwa masuk | Verifikasi keterjangkauan Webhook/server dan izin aplikasi | Perbaiki URL Webhook atau status server BlueBubbles. |
|
||||
| Dapat mengirim tetapi tidak menerima di macOS | Periksa izin privasi macOS untuk otomatisasi Messages | Berikan ulang izin TCC dan mulai ulang proses saluran. |
|
||||
| Pengirim DM diblokir | `openclaw pairing list imessage` atau `openclaw pairing list bluebubbles` | Setujui pairing atau perbarui daftar izin. |
|
||||
|
||||
Pemecahan masalah lengkap:
|
||||
|
||||
@ -106,11 +107,11 @@ Pemecahan masalah lengkap:
|
||||
|
||||
### Tanda kegagalan Signal
|
||||
|
||||
| Gejala | Pemeriksaan tercepat | Perbaikan |
|
||||
| ------------------------------- | ------------------------------------------ | ------------------------------------------------------- |
|
||||
| Daemon dapat dijangkau tetapi bot diam | `openclaw channels status --probe` | Verifikasi URL/akun daemon `signal-cli` dan mode terima. |
|
||||
| DM diblokir | `openclaw pairing list signal` | Setujui pengirim atau sesuaikan kebijakan DM. |
|
||||
| Balasan grup tidak terpicu | Periksa allowlist grup dan pola mention | Tambahkan pengirim/grup atau longgarkan gating. |
|
||||
| Gejala | Pemeriksaan tercepat | Perbaikan |
|
||||
| ------------------------------- | ------------------------------------------ | ------------------------------------------------------------- |
|
||||
| Daemon dapat dijangkau tetapi bot diam | `openclaw channels status --probe` | Verifikasi URL/akun daemon `signal-cli` dan mode penerimaan. |
|
||||
| DM diblokir | `openclaw pairing list signal` | Setujui pengirim atau sesuaikan kebijakan DM. |
|
||||
| Balasan grup tidak terpicu | Periksa daftar izin grup dan pola mention | Tambahkan pengirim/grup atau longgarkan gating. |
|
||||
|
||||
Pemecahan masalah lengkap: [Pemecahan masalah Signal](/id/channels/signal#troubleshooting)
|
||||
|
||||
@ -118,12 +119,12 @@ Pemecahan masalah lengkap: [Pemecahan masalah Signal](/id/channels/signal#troubl
|
||||
|
||||
### Tanda kegagalan QQ Bot
|
||||
|
||||
| Gejala | Pemeriksaan tercepat | Perbaikan |
|
||||
| ------------------------------- | ------------------------------------------- | -------------------------------------------------------------- |
|
||||
| Bot membalas "gone to Mars" | Verifikasi `appId` dan `clientSecret` di config | Tetapkan kredensial atau restart Gateway. |
|
||||
| Tidak ada pesan masuk | `openclaw channels status --probe` | Verifikasi kredensial di QQ Open Platform. |
|
||||
| Suara tidak ditranskripsikan | Periksa config penyedia STT | Konfigurasikan `channels.qqbot.stt` atau `tools.media.audio`. |
|
||||
| Pesan proaktif tidak sampai | Periksa persyaratan interaksi platform QQ | QQ dapat memblokir pesan yang dimulai bot tanpa interaksi terbaru. |
|
||||
| Gejala | Pemeriksaan tercepat | Perbaikan |
|
||||
| ------------------------------- | -------------------------------------------- | ------------------------------------------------------------------ |
|
||||
| Bot membalas "pergi ke Mars" | Verifikasi `appId` dan `clientSecret` di konfigurasi | Tetapkan kredensial atau mulai ulang Gateway. |
|
||||
| Tidak ada pesan masuk | `openclaw channels status --probe` | Verifikasi kredensial di QQ Open Platform. |
|
||||
| Suara tidak ditranskripsi | Periksa konfigurasi penyedia STT | Konfigurasikan `channels.qqbot.stt` atau `tools.media.audio`. |
|
||||
| Pesan proaktif tidak tiba | Periksa persyaratan interaksi platform QQ | QQ dapat memblokir pesan yang dimulai bot tanpa interaksi terbaru. |
|
||||
|
||||
Pemecahan masalah lengkap: [Pemecahan masalah QQ Bot](/id/channels/qqbot#troubleshooting)
|
||||
|
||||
@ -131,18 +132,18 @@ Pemecahan masalah lengkap: [Pemecahan masalah QQ Bot](/id/channels/qqbot#trouble
|
||||
|
||||
### Tanda kegagalan Matrix
|
||||
|
||||
| Gejala | Pemeriksaan tercepat | Perbaikan |
|
||||
| ----------------------------------- | -------------------------------------- | ------------------------------------------------------------------------ |
|
||||
| Sudah login tetapi mengabaikan pesan room | `openclaw channels status --probe` | Periksa `groupPolicy`, allowlist room, dan gating mention. |
|
||||
| DM tidak diproses | `openclaw pairing list matrix` | Setujui pengirim atau sesuaikan kebijakan DM. |
|
||||
| Room terenkripsi gagal | `openclaw matrix verify status` | Verifikasi ulang perangkat, lalu periksa `openclaw matrix verify backup status`. |
|
||||
| Restore backup tertunda/rusak | `openclaw matrix verify backup status` | Jalankan `openclaw matrix verify backup restore` atau jalankan ulang dengan recovery key. |
|
||||
| Cross-signing/bootstrap terlihat salah | `openclaw matrix verify bootstrap` | Perbaiki secret storage, cross-signing, dan status backup dalam satu lintasan. |
|
||||
| Gejala | Pemeriksaan tercepat | Perbaikan |
|
||||
| ------------------------------------ | --------------------------------------- | ----------------------------------------------------------------------------- |
|
||||
| Sudah login tetapi mengabaikan pesan ruang | `openclaw channels status --probe` | Periksa `groupPolicy`, daftar izin ruang, dan gating mention. |
|
||||
| DM tidak diproses | `openclaw pairing list matrix` | Setujui pengirim atau sesuaikan kebijakan DM. |
|
||||
| Ruang terenkripsi gagal | `openclaw matrix verify status` | Verifikasi ulang perangkat, lalu periksa `openclaw matrix verify backup status`. |
|
||||
| Pemulihan cadangan tertunda/rusak | `openclaw matrix verify backup status` | Jalankan `openclaw matrix verify backup restore` atau jalankan ulang dengan kunci pemulihan. |
|
||||
| Cross-signing/bootstrap terlihat salah | `openclaw matrix verify bootstrap` | Perbaiki penyimpanan rahasia, cross-signing, dan status cadangan dalam satu langkah. |
|
||||
|
||||
Setup dan config lengkap: [Matrix](/id/channels/matrix)
|
||||
Penyiapan dan konfigurasi lengkap: [Matrix](/id/channels/matrix)
|
||||
|
||||
## Terkait
|
||||
|
||||
- [Pairing](/id/channels/pairing)
|
||||
- [Routing channel](/id/channels/channel-routing)
|
||||
- [Perutean saluran](/id/channels/channel-routing)
|
||||
- [Pemecahan masalah Gateway](/id/gateway/troubleshooting)
|
||||
|
||||
@ -1,25 +1,25 @@
|
||||
---
|
||||
read_when:
|
||||
- Anda mengalami masalah konektivitas/autentikasi dan menginginkan perbaikan terpandu
|
||||
- Anda telah memperbarui dan ingin melakukan pemeriksaan kewajaran
|
||||
- Anda telah memperbarui dan ingin pemeriksaan kewajaran
|
||||
summary: Referensi CLI untuk `openclaw doctor` (pemeriksaan kesehatan + perbaikan terpandu)
|
||||
title: Dokter
|
||||
title: Diagnostik
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:28:37Z"
|
||||
generated_at: "2026-05-04T02:22:33Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: d4baab5b0cd4d046d12ae5bd14ccf05224115856d45e630a57e77a2be15e5db0
|
||||
source_hash: cd7fb09d373c313e4be45ad9e3b19ceb187a5787ef3e70fcd2b1f1f01b50c905
|
||||
source_path: cli/doctor.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
# `openclaw doctor`
|
||||
|
||||
Pemeriksaan kesehatan + perbaikan cepat untuk Gateway dan kanal.
|
||||
Pemeriksaan kesehatan + perbaikan cepat untuk Gateway dan channel.
|
||||
|
||||
Terkait:
|
||||
|
||||
- Pemecahan masalah: [Pemecahan Masalah](/id/gateway/troubleshooting)
|
||||
- Pemecahan masalah: [Pemecahan masalah](/id/gateway/troubleshooting)
|
||||
- Audit keamanan: [Keamanan](/id/gateway/security)
|
||||
|
||||
## Contoh
|
||||
@ -34,45 +34,45 @@ openclaw doctor --generate-gateway-token
|
||||
|
||||
## Opsi
|
||||
|
||||
- `--no-workspace-suggestions`: menonaktifkan saran memori/pencarian workspace
|
||||
- `--yes`: menerima default tanpa prompt
|
||||
- `--repair`: menerapkan perbaikan non-layanan yang direkomendasikan tanpa prompt; instalasi dan penulisan ulang layanan Gateway tetap memerlukan konfirmasi interaktif atau perintah Gateway eksplisit
|
||||
- `--no-workspace-suggestions`: nonaktifkan saran memori/pencarian workspace
|
||||
- `--yes`: terima nilai default tanpa prompt
|
||||
- `--repair`: terapkan perbaikan non-layanan yang direkomendasikan tanpa prompt; pemasangan dan penulisan ulang layanan Gateway tetap memerlukan konfirmasi interaktif atau perintah Gateway eksplisit
|
||||
- `--fix`: alias untuk `--repair`
|
||||
- `--force`: menerapkan perbaikan agresif, termasuk menimpa konfigurasi layanan kustom bila diperlukan
|
||||
- `--non-interactive`: berjalan tanpa prompt; hanya migrasi aman dan perbaikan non-layanan
|
||||
- `--generate-gateway-token`: membuat dan mengonfigurasi token Gateway
|
||||
- `--deep`: memindai layanan sistem untuk instalasi Gateway tambahan
|
||||
- `--force`: terapkan perbaikan agresif, termasuk menimpa konfigurasi layanan kustom jika diperlukan
|
||||
- `--non-interactive`: jalankan tanpa prompt; hanya migrasi aman dan perbaikan non-layanan
|
||||
- `--generate-gateway-token`: buat dan konfigurasikan token Gateway
|
||||
- `--deep`: pindai layanan sistem untuk pemasangan Gateway tambahan
|
||||
|
||||
Catatan:
|
||||
|
||||
- Prompt interaktif (seperti perbaikan keychain/OAuth) hanya berjalan ketika stdin adalah TTY dan `--non-interactive` **tidak** diatur. Proses tanpa head (cron, Telegram, tanpa terminal) akan melewati prompt.
|
||||
- Performa: proses `doctor` non-interaktif melewati pemuatan plugin secara eager agar pemeriksaan kesehatan tanpa head tetap cepat. Sesi interaktif tetap memuat plugin sepenuhnya ketika sebuah pemeriksaan memerlukan kontribusinya.
|
||||
- Prompt interaktif (seperti perbaikan keychain/OAuth) hanya berjalan ketika stdin adalah TTY dan `--non-interactive` **tidak** disetel. Eksekusi headless (cron, Telegram, tanpa terminal) akan melewati prompt.
|
||||
- Performa: eksekusi `doctor` non-interaktif melewati pemuatan Plugin secara eager agar pemeriksaan kesehatan headless tetap cepat. Sesi interaktif tetap memuat Plugin sepenuhnya ketika pemeriksaan membutuhkan kontribusinya.
|
||||
- `--fix` (alias untuk `--repair`) menulis cadangan ke `~/.openclaw/openclaw.json.bak` dan menghapus kunci konfigurasi yang tidak dikenal, dengan mencantumkan setiap penghapusan.
|
||||
- `doctor --fix --non-interactive` melaporkan definisi layanan Gateway yang hilang atau usang, tetapi tidak menginstal atau menulis ulang di luar mode perbaikan pembaruan. Jalankan `openclaw gateway install` untuk layanan yang hilang, atau `openclaw gateway install --force` ketika Anda memang ingin mengganti launcher.
|
||||
- Pemeriksaan integritas state kini mendeteksi berkas transkrip yatim di direktori sesi. Mengarsipkannya sebagai `.deleted.<timestamp>` memerlukan konfirmasi interaktif; `--fix`, `--yes`, dan proses tanpa head membiarkannya tetap di tempat.
|
||||
- Doctor juga memindai `~/.openclaw/cron/jobs.json` (atau `cron.store`) untuk bentuk job cron legacy dan dapat menulis ulang di tempat sebelum scheduler harus melakukan normalisasi otomatis saat runtime.
|
||||
- Di Linux, doctor memperingatkan ketika crontab pengguna masih menjalankan legacy `~/.openclaw/bin/ensure-whatsapp.sh`; skrip itu tidak lagi dipelihara dan dapat mencatat outage Gateway WhatsApp palsu ketika cron tidak memiliki lingkungan user-bus systemd.
|
||||
- Doctor membersihkan state staging dependensi plugin legacy yang dibuat oleh versi OpenClaw lama. Doctor juga memperbaiki plugin unduhan yang dikonfigurasi tetapi hilang ketika registry dapat me-resolve-nya, dan pass doctor 2026.5.2 secara otomatis menginstal plugin unduhan yang sudah digunakan konfigurasi lama sebelum menandai konfigurasi tersentuh untuk rilis tersebut.
|
||||
- Doctor memperbaiki konfigurasi plugin usang dengan menghapus id plugin yang hilang dari `plugins.allow`/`plugins.entries`, beserta konfigurasi kanal yang menggantung, target Heartbeat, dan override model kanal yang cocok ketika penemuan plugin sehat.
|
||||
- Doctor mengarantina konfigurasi plugin tidak valid dengan menonaktifkan entri `plugins.entries.<id>` yang terpengaruh dan menghapus payload `config`-nya yang tidak valid. Startup Gateway sudah hanya melewati plugin bermasalah tersebut agar plugin dan kanal lain dapat terus berjalan.
|
||||
- Atur `OPENCLAW_SERVICE_REPAIR_POLICY=external` ketika supervisor lain memiliki lifecycle Gateway. Doctor tetap melaporkan kesehatan Gateway/layanan dan menerapkan perbaikan non-layanan, tetapi melewati instalasi/start/restart/bootstrap layanan dan pembersihan layanan legacy.
|
||||
- Di Linux, doctor mengabaikan unit systemd tambahan mirip Gateway yang tidak aktif dan tidak menulis ulang metadata perintah/entrypoint untuk layanan Gateway systemd yang sedang berjalan saat perbaikan. Hentikan layanan terlebih dahulu atau gunakan `openclaw gateway install --force` ketika Anda memang ingin mengganti launcher aktif.
|
||||
- Doctor otomatis memigrasikan konfigurasi Talk datar legacy (`talk.voiceId`, `talk.modelId`, dan sejenisnya) ke `talk.provider` + `talk.providers.<provider>`.
|
||||
- Proses `doctor --fix` berulang tidak lagi melaporkan/menerapkan normalisasi Talk ketika satu-satunya perbedaan adalah urutan kunci objek.
|
||||
- `doctor --fix --non-interactive` melaporkan definisi layanan Gateway yang hilang atau usang tetapi tidak memasang atau menulis ulang definisi tersebut di luar mode perbaikan pembaruan. Jalankan `openclaw gateway install` untuk layanan yang hilang, atau `openclaw gateway install --force` ketika Anda memang ingin mengganti launcher.
|
||||
- Pemeriksaan integritas status kini mendeteksi file transkrip yatim di direktori sesi. Mengarsipkannya sebagai `.deleted.<timestamp>` memerlukan konfirmasi interaktif; `--fix`, `--yes`, dan eksekusi headless membiarkannya tetap di tempat.
|
||||
- Doctor juga memindai `~/.openclaw/cron/jobs.json` (atau `cron.store`) untuk bentuk job cron lama dan dapat menulis ulang secara langsung sebelum scheduler harus melakukan normalisasi otomatis saat runtime.
|
||||
- Di Linux, doctor memperingatkan ketika crontab pengguna masih menjalankan `~/.openclaw/bin/ensure-whatsapp.sh` lama; skrip tersebut tidak lagi dipelihara dan dapat mencatat gangguan Gateway WhatsApp palsu ketika cron tidak memiliki lingkungan user-bus systemd.
|
||||
- Doctor membersihkan status staging dependensi Plugin lama yang dibuat oleh versi OpenClaw yang lebih lama. Doctor juga memperbaiki Plugin unduhan terkonfigurasi yang hilang ketika registry dapat menyelesaikannya, dan proses doctor 2026.5.2 secara otomatis memasang Plugin unduhan yang sudah digunakan konfigurasi lama sebelum menandai konfigurasi tersentuh untuk rilis tersebut. Jika unduhan gagal, doctor melaporkan error pemasangan dan mempertahankan entri Plugin terkonfigurasi untuk upaya perbaikan berikutnya.
|
||||
- Doctor memperbaiki konfigurasi Plugin usang dengan menghapus id Plugin yang hilang dari `plugins.allow`/`plugins.entries`, serta konfigurasi channel yang menggantung, target Heartbeat, dan override model channel yang cocok ketika penemuan Plugin sehat.
|
||||
- Doctor mengarantina konfigurasi Plugin yang tidak valid dengan menonaktifkan entri `plugins.entries.<id>` yang terdampak dan menghapus payload `config` yang tidak valid. Startup Gateway sudah melewati hanya Plugin bermasalah tersebut sehingga Plugin dan channel lain dapat tetap berjalan.
|
||||
- Setel `OPENCLAW_SERVICE_REPAIR_POLICY=external` ketika supervisor lain memiliki siklus hidup Gateway. Doctor tetap melaporkan kesehatan Gateway/layanan dan menerapkan perbaikan non-layanan, tetapi melewati pemasangan/start/restart/bootstrap layanan dan pembersihan layanan lama.
|
||||
- Di Linux, doctor mengabaikan unit systemd tambahan mirip Gateway yang tidak aktif dan tidak menulis ulang metadata command/entrypoint untuk layanan Gateway systemd yang sedang berjalan selama perbaikan. Hentikan layanan terlebih dahulu atau gunakan `openclaw gateway install --force` ketika Anda memang ingin mengganti launcher aktif.
|
||||
- Doctor melakukan migrasi otomatis konfigurasi Talk datar lama (`talk.voiceId`, `talk.modelId`, dan sejenisnya) ke `talk.provider` + `talk.providers.<provider>`.
|
||||
- Eksekusi `doctor --fix` berulang tidak lagi melaporkan/menerapkan normalisasi Talk ketika satu-satunya perbedaan adalah urutan kunci objek.
|
||||
- Doctor menyertakan pemeriksaan kesiapan pencarian memori dan dapat merekomendasikan `openclaw configure --section model` ketika kredensial embedding hilang.
|
||||
- Doctor memperingatkan ketika tidak ada pemilik perintah yang dikonfigurasi. Pemilik perintah adalah akun operator manusia yang diizinkan menjalankan perintah khusus pemilik dan menyetujui tindakan berbahaya. Pairing DM hanya mengizinkan seseorang berbicara dengan bot; jika Anda menyetujui pengirim sebelum bootstrap pemilik pertama tersedia, atur `commands.ownerAllowFrom` secara eksplisit.
|
||||
- Doctor memperingatkan ketika agen mode Codex dikonfigurasi dan aset CLI Codex pribadi ada di home Codex operator. Peluncuran app-server Codex lokal menggunakan home per-agen yang terisolasi, jadi gunakan `openclaw migrate codex --dry-run` untuk menginventarisasi aset yang harus dipromosikan secara sengaja.
|
||||
- Doctor memperingatkan ketika Skills yang diizinkan untuk agen default tidak tersedia di lingkungan runtime saat ini karena bin, env var, konfigurasi, atau persyaratan OS hilang. `doctor --fix` dapat menonaktifkan skill yang tidak tersedia tersebut dengan `skills.entries.<skill>.enabled=false`; instal/konfigurasikan persyaratan yang hilang sebagai gantinya ketika Anda ingin skill tetap aktif.
|
||||
- Doctor memperingatkan ketika tidak ada pemilik command yang dikonfigurasi. Pemilik command adalah akun operator manusia yang diizinkan menjalankan command khusus pemilik dan menyetujui tindakan berbahaya. Pairing DM hanya memungkinkan seseorang berbicara dengan bot; jika Anda menyetujui pengirim sebelum bootstrap pemilik pertama ada, setel `commands.ownerAllowFrom` secara eksplisit.
|
||||
- Doctor memperingatkan ketika agen mode Codex dikonfigurasi dan aset CLI Codex pribadi ada di home Codex operator. Peluncuran server aplikasi Codex lokal menggunakan home per-agen yang terisolasi, jadi gunakan `openclaw migrate codex --dry-run` untuk menginventarisasi aset yang harus dipromosikan secara sengaja.
|
||||
- Doctor memperingatkan ketika Skills yang diizinkan untuk agen default tidak tersedia di lingkungan runtime saat ini karena bin, env vars, konfigurasi, atau persyaratan OS hilang. `doctor --fix` dapat menonaktifkan Skills yang tidak tersedia tersebut dengan `skills.entries.<skill>.enabled=false`; pasang/konfigurasikan persyaratan yang hilang sebagai gantinya ketika Anda ingin mempertahankan skill tetap aktif.
|
||||
- Jika mode sandbox diaktifkan tetapi Docker tidak tersedia, doctor melaporkan peringatan bernilai tinggi dengan remediasi (`install Docker` atau `openclaw config set agents.defaults.sandbox.mode off`).
|
||||
- Jika berkas registry sandbox legacy (`~/.openclaw/sandbox/containers.json` atau `~/.openclaw/sandbox/browsers.json`) ada, doctor melaporkannya; `openclaw doctor --fix` memigrasikan entri valid ke direktori registry tersharding dan mengarantina berkas legacy yang tidak valid.
|
||||
- Jika `gateway.auth.token`/`gateway.auth.password` dikelola SecretRef dan tidak tersedia di path perintah saat ini, doctor melaporkan peringatan baca-saja dan tidak menulis kredensial fallback plaintext.
|
||||
- Jika inspeksi SecretRef kanal gagal di path perbaikan, doctor melanjutkan dan melaporkan peringatan alih-alih keluar lebih awal.
|
||||
- Setelah migrasi direktori state, doctor memperingatkan ketika akun Telegram atau Discord default yang aktif bergantung pada fallback env dan `TELEGRAM_BOT_TOKEN` atau `DISCORD_BOT_TOKEN` tidak tersedia untuk proses doctor.
|
||||
- Auto-resolusi username `allowFrom` Telegram (`doctor --fix`) memerlukan token Telegram yang dapat di-resolve di path perintah saat ini. Jika inspeksi token tidak tersedia, doctor melaporkan peringatan dan melewati auto-resolusi untuk pass tersebut.
|
||||
- Jika file registry sandbox lama (`~/.openclaw/sandbox/containers.json` atau `~/.openclaw/sandbox/browsers.json`) ada, doctor melaporkannya; `openclaw doctor --fix` memigrasikan entri valid ke direktori registry bershard dan mengarantina file lama yang tidak valid.
|
||||
- Jika `gateway.auth.token`/`gateway.auth.password` dikelola SecretRef dan tidak tersedia di jalur command saat ini, doctor melaporkan peringatan hanya-baca dan tidak menulis kredensial fallback plaintext.
|
||||
- Jika inspeksi SecretRef channel gagal di jalur perbaikan, doctor melanjutkan dan melaporkan peringatan alih-alih keluar lebih awal.
|
||||
- Setelah migrasi direktori status, doctor memperingatkan ketika akun Telegram atau Discord default yang diaktifkan bergantung pada fallback env dan `TELEGRAM_BOT_TOKEN` atau `DISCORD_BOT_TOKEN` tidak tersedia untuk proses doctor.
|
||||
- Resolusi otomatis username `allowFrom` Telegram (`doctor --fix`) memerlukan token Telegram yang dapat di-resolve di jalur command saat ini. Jika inspeksi token tidak tersedia, doctor melaporkan peringatan dan melewati resolusi otomatis untuk proses tersebut.
|
||||
|
||||
## macOS: override env `launchctl`
|
||||
|
||||
Jika sebelumnya Anda menjalankan `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (atau `...PASSWORD`), nilai itu menimpa berkas konfigurasi Anda dan dapat menyebabkan galat “tidak terotorisasi” yang persisten.
|
||||
Jika sebelumnya Anda menjalankan `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (atau `...PASSWORD`), nilai tersebut menimpa file konfigurasi Anda dan dapat menyebabkan error “tidak terotorisasi” yang persisten.
|
||||
|
||||
```bash
|
||||
launchctl getenv OPENCLAW_GATEWAY_TOKEN
|
||||
|
||||
@ -1,52 +1,52 @@
|
||||
---
|
||||
read_when:
|
||||
- Mengubah lingkungan eksekusi agen, inisialisasi ruang kerja, atau perilaku sesi
|
||||
summary: Runtime agen, kontrak ruang kerja, dan inisialisasi awal sesi
|
||||
title: Runtime agen
|
||||
summary: Runtime agen, kontrak ruang kerja, dan inisialisasi sesi
|
||||
title: Lingkungan eksekusi agen
|
||||
x-i18n:
|
||||
generated_at: "2026-04-30T09:42:23Z"
|
||||
generated_at: "2026-05-04T02:22:40Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: f4d65ee96cece296251d7d3a0512f12d2dfa900db0e5ffc0f37dcddae7ea55ad
|
||||
source_hash: 89bbbd05a9bf2054d3a1f24aeed005a05b61152a047b593addfb46817baae05a
|
||||
source_path: concepts/agent.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw menjalankan **satu runtime agen tertanam** — satu proses agen per
|
||||
Gateway, dengan workspace, file bootstrap, dan penyimpanan sesinya sendiri. Halaman ini
|
||||
membahas kontrak runtime tersebut: apa yang harus ada dalam workspace, file mana yang
|
||||
disuntikkan, dan bagaimana sesi melakukan bootstrap terhadapnya.
|
||||
mencakup kontrak runtime tersebut: apa yang harus ada di workspace, file mana yang
|
||||
diinjeksikan, dan bagaimana sesi melakukan bootstrap terhadapnya.
|
||||
|
||||
## Workspace (wajib)
|
||||
|
||||
OpenClaw menggunakan satu direktori workspace agen (`agents.defaults.workspace`) sebagai direktori kerja (`cwd`) **satu-satunya** milik agen untuk alat dan konteks.
|
||||
OpenClaw menggunakan satu direktori workspace agen (`agents.defaults.workspace`) sebagai **satu-satunya** direktori kerja (`cwd`) agen untuk alat dan konteks.
|
||||
|
||||
Direkomendasikan: gunakan `openclaw setup` untuk membuat `~/.openclaw/openclaw.json` jika belum ada dan menginisialisasi file workspace.
|
||||
|
||||
Tata letak workspace lengkap + panduan pencadangan: [Workspace agen](/id/concepts/agent-workspace)
|
||||
|
||||
Jika `agents.defaults.sandbox` diaktifkan, sesi non-utama dapat menimpanya dengan
|
||||
Jika `agents.defaults.sandbox` diaktifkan, sesi non-utama dapat menimpa ini dengan
|
||||
workspace per sesi di bawah `agents.defaults.sandbox.workspaceRoot` (lihat
|
||||
[Konfigurasi Gateway](/id/gateway/configuration)).
|
||||
|
||||
## File bootstrap (disuntikkan)
|
||||
## File bootstrap (diinjeksikan)
|
||||
|
||||
Di dalam `agents.defaults.workspace`, OpenClaw mengharapkan file yang dapat diedit pengguna berikut:
|
||||
|
||||
- `AGENTS.md` — instruksi operasional + “memori”
|
||||
- `AGENTS.md` — instruksi operasi + “memori”
|
||||
- `SOUL.md` — persona, batasan, nada
|
||||
- `TOOLS.md` — catatan alat yang dikelola pengguna (mis. `imsg`, `sag`, konvensi)
|
||||
- `BOOTSTRAP.md` — ritual sekali jalan pertama kali (dihapus setelah selesai)
|
||||
- `BOOTSTRAP.md` — ritual pertama kali satu kali (dihapus setelah selesai)
|
||||
- `IDENTITY.md` — nama/vibe/emoji agen
|
||||
- `USER.md` — profil pengguna + sapaan yang disukai
|
||||
- `USER.md` — profil pengguna + sapaan pilihan
|
||||
|
||||
Pada giliran pertama sesi baru, OpenClaw menyuntikkan isi file-file ini langsung ke konteks agen.
|
||||
Pada giliran pertama sesi baru, OpenClaw menginjeksikan isi file-file ini ke dalam Project Context pada prompt sistem.
|
||||
|
||||
File kosong dilewati. File besar dipangkas dan dipotong dengan penanda agar prompt tetap ringkas (baca file untuk isi lengkap).
|
||||
File kosong dilewati. File besar dipangkas dan dipotong dengan penanda agar prompt tetap ramping (baca file untuk konten lengkap).
|
||||
|
||||
Jika sebuah file hilang, OpenClaw menyuntikkan satu baris penanda “file hilang” (dan `openclaw setup` akan membuat templat default yang aman).
|
||||
Jika file tidak ada, OpenClaw menginjeksikan satu baris penanda “file hilang” (dan `openclaw setup` akan membuat templat default yang aman).
|
||||
|
||||
`BOOTSTRAP.md` hanya dibuat untuk **workspace yang benar-benar baru** (tidak ada file bootstrap lain). Jika Anda menghapusnya setelah menyelesaikan ritual, file itu tidak boleh dibuat ulang pada restart berikutnya.
|
||||
`BOOTSTRAP.md` hanya dibuat untuk **workspace yang benar-benar baru** (tidak ada file bootstrap lain). Selagi masih tertunda, OpenClaw mempertahankannya di Project Context dan menambahkan panduan bootstrap prompt sistem untuk ritual awal alih-alih menyalinnya ke pesan pengguna. Jika Anda menghapusnya setelah menyelesaikan ritual, file itu tidak seharusnya dibuat ulang pada restart berikutnya.
|
||||
|
||||
Untuk menonaktifkan pembuatan file bootstrap sepenuhnya (untuk workspace yang sudah diisi sebelumnya), atur:
|
||||
|
||||
@ -57,28 +57,28 @@ Untuk menonaktifkan pembuatan file bootstrap sepenuhnya (untuk workspace yang su
|
||||
## Alat bawaan
|
||||
|
||||
Alat inti (read/exec/edit/write dan alat sistem terkait) selalu tersedia,
|
||||
sesuai kebijakan alat. `apply_patch` bersifat opsional dan dikendalikan oleh
|
||||
tunduk pada kebijakan alat. `apply_patch` bersifat opsional dan dikontrol oleh
|
||||
`tools.exec.applyPatch`. `TOOLS.md` **tidak** mengontrol alat mana yang ada; itu adalah
|
||||
panduan tentang bagaimana _Anda_ ingin alat tersebut digunakan.
|
||||
|
||||
## Skills
|
||||
|
||||
OpenClaw memuat skills dari lokasi berikut (prioritas tertinggi terlebih dahulu):
|
||||
OpenClaw memuat Skills dari lokasi berikut (prioritas tertinggi lebih dulu):
|
||||
|
||||
- Workspace: `<workspace>/skills`
|
||||
- Skill agen proyek: `<workspace>/.agents/skills`
|
||||
- Skill agen pribadi: `~/.agents/skills`
|
||||
- Skills agen proyek: `<workspace>/.agents/skills`
|
||||
- Skills agen pribadi: `~/.agents/skills`
|
||||
- Terkelola/lokal: `~/.openclaw/skills`
|
||||
- Bundel (dikirim bersama instalasi)
|
||||
- Folder skill tambahan: `skills.load.extraDirs`
|
||||
- Terbundel (dikirim bersama instalasi)
|
||||
- Folder Skills tambahan: `skills.load.extraDirs`
|
||||
|
||||
Skills dapat dibatasi oleh config/env (lihat `skills` di [Konfigurasi Gateway](/id/gateway/configuration)).
|
||||
Skills dapat dikontrol oleh config/env (lihat `skills` di [Konfigurasi Gateway](/id/gateway/configuration)).
|
||||
|
||||
## Batas runtime
|
||||
|
||||
Runtime agen tertanam dibangun di atas inti agen Pi (model, alat, dan
|
||||
pipeline prompt). Manajemen sesi, penemuan, pengabelan alat, dan pengiriman
|
||||
channel adalah lapisan milik OpenClaw di atas inti tersebut.
|
||||
pipeline prompt). Manajemen sesi, penemuan, penyambungan alat, dan pengiriman
|
||||
kanal adalah lapisan milik OpenClaw di atas inti tersebut.
|
||||
|
||||
## Sesi
|
||||
|
||||
@ -89,43 +89,43 @@ Transkrip sesi disimpan sebagai JSONL di:
|
||||
ID sesi stabil dan dipilih oleh OpenClaw.
|
||||
Folder sesi lama dari alat lain tidak dibaca.
|
||||
|
||||
## Mengarahkan saat streaming
|
||||
## Pengarahan saat streaming
|
||||
|
||||
Ketika mode antrean adalah `steer`, pesan masuk disuntikkan ke run saat ini.
|
||||
Saat mode antrean adalah `steer`, pesan masuk diinjeksikan ke run saat ini.
|
||||
Pengarahan yang diantrekan dikirim **setelah giliran asisten saat ini selesai
|
||||
mengeksekusi panggilan alatnya**, sebelum panggilan LLM berikutnya. Pi menguras semua pesan
|
||||
pengarahan tertunda sekaligus untuk `steer`; `queue` lama menguras satu pesan per
|
||||
batas model. Pengarahan tidak lagi melewati panggilan alat tersisa dari pesan
|
||||
mengeksekusi tool call-nya**, sebelum panggilan LLM berikutnya. Pi menguras semua pesan
|
||||
pengarahan yang tertunda bersama-sama untuk `steer`; `queue` lama menguras satu pesan per
|
||||
batas model. Pengarahan tidak lagi melewati tool call yang tersisa dari pesan
|
||||
asisten saat ini.
|
||||
|
||||
Ketika mode antrean adalah `followup` atau `collect`, pesan masuk ditahan hingga
|
||||
Saat mode antrean adalah `followup` atau `collect`, pesan masuk ditahan hingga
|
||||
giliran saat ini berakhir, lalu giliran agen baru dimulai dengan payload yang diantrekan. Lihat
|
||||
[Antrean](/id/concepts/queue) dan [Antrean pengarahan](/id/concepts/queue-steering) untuk perilaku mode
|
||||
dan batas.
|
||||
|
||||
Streaming blok mengirim blok asisten yang selesai segera setelah blok tersebut selesai; fitur ini
|
||||
**mati secara default** (`agents.defaults.blockStreamingDefault: "off"`).
|
||||
Streaming blok mengirim blok asisten yang selesai segera setelah selesai; ini
|
||||
**nonaktif secara default** (`agents.defaults.blockStreamingDefault: "off"`).
|
||||
Sesuaikan batas melalui `agents.defaults.blockStreamingBreak` (`text_end` vs `message_end`; default ke text_end).
|
||||
Kontrol pemotongan blok lunak dengan `agents.defaults.blockStreamingChunk` (default ke
|
||||
800–1200 karakter; mengutamakan jeda paragraf, lalu baris baru; kalimat terakhir).
|
||||
Gabungkan potongan yang di-stream dengan `agents.defaults.blockStreamingCoalesce` untuk mengurangi
|
||||
spam satu baris (penggabungan berbasis idle sebelum kirim). Channel non-Telegram memerlukan
|
||||
Gabungkan chunk streaming dengan `agents.defaults.blockStreamingCoalesce` untuk mengurangi
|
||||
spam satu baris (penggabungan berbasis idle sebelum kirim). Kanal non-Telegram memerlukan
|
||||
`*.blockStreaming: true` eksplisit untuk mengaktifkan balasan blok.
|
||||
Ringkasan alat verbose dikeluarkan saat alat dimulai (tanpa debounce); Control UI
|
||||
melakukan stream output alat melalui event agen jika tersedia.
|
||||
Detail selengkapnya: [Streaming + pemotongan](/id/concepts/streaming).
|
||||
Ringkasan alat verbose dipancarkan saat alat dimulai (tanpa debounce); Control UI
|
||||
men-stream output alat melalui event agen jika tersedia.
|
||||
Detail lebih lanjut: [Streaming + pemotongan chunk](/id/concepts/streaming).
|
||||
|
||||
## Referensi model
|
||||
|
||||
Referensi model dalam konfigurasi (misalnya `agents.defaults.model` dan `agents.defaults.models`) diurai dengan memisahkan pada `/` **pertama**.
|
||||
Referensi model dalam config (misalnya `agents.defaults.model` dan `agents.defaults.models`) diurai dengan membagi pada `/` **pertama**.
|
||||
|
||||
- Gunakan `provider/model` saat mengonfigurasi model.
|
||||
- Jika ID model itu sendiri berisi `/` (gaya OpenRouter), sertakan prefiks provider (contoh: `openrouter/moonshotai/kimi-k2`).
|
||||
- Jika Anda menghilangkan provider, OpenClaw mencoba alias terlebih dahulu, lalu kecocokan
|
||||
provider-terkonfigurasi yang unik untuk id model persis tersebut, dan baru kemudian fallback
|
||||
ke provider default yang dikonfigurasi. Jika provider tersebut tidak lagi mengekspos
|
||||
model default yang dikonfigurasi, OpenClaw fallback ke provider/model pertama yang
|
||||
dikonfigurasi alih-alih menampilkan default provider yang sudah dihapus dan usang.
|
||||
- Jika ID model itu sendiri berisi `/` (gaya OpenRouter), sertakan prefiks penyedia (contoh: `openrouter/moonshotai/kimi-k2`).
|
||||
- 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. Jika penyedia tersebut tidak lagi mengekspos
|
||||
model default yang dikonfigurasi, OpenClaw fallback ke
|
||||
penyedia/model terkonfigurasi pertama alih-alih menampilkan default penyedia yang dihapus yang sudah usang.
|
||||
|
||||
## Konfigurasi (minimal)
|
||||
|
||||
@ -141,5 +141,5 @@ _Berikutnya: [Chat Grup](/id/channels/group-messages)_ 🦞
|
||||
## Terkait
|
||||
|
||||
- [Workspace agen](/id/concepts/agent-workspace)
|
||||
- [Perutean multi-agen](/id/concepts/multi-agent)
|
||||
- [Routing multi-agen](/id/concepts/multi-agent)
|
||||
- [Manajemen sesi](/id/concepts/session)
|
||||
|
||||
@ -1,65 +1,87 @@
|
||||
---
|
||||
read_when:
|
||||
- Membangun atau menjalankan QA visual langsung untuk bug OpenClaw
|
||||
- Menambahkan verifikasi sebelum dan sesudah untuk permintaan tarik
|
||||
- Menambahkan skenario transport langsung Discord, Slack, WhatsApp, atau lainnya
|
||||
- Melakukan debug pada eksekusi QA yang membutuhkan tangkapan layar, otomatisasi peramban, atau akses VNC
|
||||
summary: Mantis adalah sistem verifikasi visual ujung-ke-ujung untuk mereproduksi bug OpenClaw pada transport langsung, menangkap bukti sebelum dan sesudah, serta melampirkan artefak ke PR.
|
||||
- Menambahkan verifikasi sebelum dan sesudah pada permintaan pull
|
||||
- Menambahkan Discord, Slack, WhatsApp, atau skenario transport langsung lainnya
|
||||
- Men-debug proses QA yang memerlukan tangkapan layar, otomatisasi peramban, atau akses VNC
|
||||
summary: Mantis adalah sistem verifikasi visual ujung-ke-ujung untuk mereproduksi bug OpenClaw pada transport langsung, menangkap bukti sebelum dan sesudah, dan melampirkan artefak ke PR.
|
||||
title: Belalang sembah
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:30:10Z"
|
||||
generated_at: "2026-05-04T02:23:12Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 3463882b01a7941f6d758c509d6cd70e099aa8352053347fa9c37a80e5b256ce
|
||||
source_hash: 5a86ab4bc876d1c53ada1c30580034165f028194a072f559eb54a898a369211d
|
||||
source_path: concepts/mantis.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Mantis adalah sistem verifikasi end-to-end OpenClaw untuk bug yang membutuhkan runtime nyata, transport nyata, dan bukti yang terlihat. Sistem ini menjalankan skenario terhadap ref bermasalah yang diketahui, menangkap bukti, menjalankan skenario yang sama terhadap ref kandidat, dan menerbitkan perbandingannya sebagai artefak yang dapat diperiksa pengelola dari PR atau dari perintah lokal.
|
||||
Mantis adalah sistem verifikasi end-to-end OpenClaw untuk bug yang membutuhkan
|
||||
runtime nyata, transport nyata, dan bukti yang terlihat. Sistem ini menjalankan
|
||||
skenario terhadap ref yang diketahui bermasalah, menangkap bukti, menjalankan
|
||||
skenario yang sama terhadap ref kandidat, dan memublikasikan perbandingannya
|
||||
sebagai artefak yang dapat diperiksa maintainer dari PR atau dari perintah lokal.
|
||||
|
||||
Mantis dimulai dengan Discord karena Discord memberi kita jalur pertama bernilai tinggi: autentikasi bot nyata, kanal guild nyata, reaksi, utas, perintah native, dan UI peramban tempat manusia dapat mengonfirmasi secara visual apa yang ditampilkan transport.
|
||||
Mantis dimulai dengan Discord karena Discord memberi kita jalur pertama bernilai
|
||||
tinggi: auth bot nyata, channel guild nyata, reaksi, thread, perintah native, dan
|
||||
UI browser tempat manusia dapat mengonfirmasi secara visual apa yang ditampilkan
|
||||
transport.
|
||||
|
||||
## Sasaran
|
||||
## Tujuan
|
||||
|
||||
- Mereproduksi bug dari issue atau PR GitHub dengan bentuk transport yang sama seperti yang dilihat pengguna.
|
||||
- Mereproduksi bug dari issue atau PR GitHub dengan bentuk transport yang sama
|
||||
seperti yang dilihat pengguna.
|
||||
- Menangkap artefak **sebelum** pada ref baseline sebelum menerapkan perbaikan.
|
||||
- Menangkap artefak **sesudah** pada ref kandidat setelah menerapkan perbaikan.
|
||||
- Menggunakan oracle deterministik bila memungkinkan, seperti pembacaan reaksi REST Discord atau pemeriksaan transkrip kanal.
|
||||
- Menangkap tangkapan layar saat bug memiliki permukaan UI yang terlihat.
|
||||
- Berjalan secara lokal dari CLI yang dikendalikan agen dan secara jarak jauh dari GitHub.
|
||||
- Mempertahankan cukup status mesin untuk penyelamatan VNC saat login, otomatisasi peramban, atau autentikasi penyedia macet.
|
||||
- Mengirim status ringkas ke kanal Discord operator saat eksekusi terblokir, memerlukan bantuan VNC manual, atau selesai.
|
||||
- Menggunakan oracle deterministik jika memungkinkan, seperti pembacaan reaksi
|
||||
Discord REST atau pemeriksaan transkrip channel.
|
||||
- Menangkap screenshot saat bug memiliki permukaan UI yang terlihat.
|
||||
- Berjalan secara lokal dari CLI yang dikendalikan agen dan secara remote dari
|
||||
GitHub.
|
||||
- Mempertahankan state mesin yang cukup untuk penyelamatan VNC saat login,
|
||||
otomasi browser, atau auth provider macet.
|
||||
- Mengirim status ringkas ke channel Discord operator saat proses terblokir,
|
||||
memerlukan bantuan VNC manual, atau selesai.
|
||||
|
||||
## Bukan Sasaran
|
||||
## Bukan Tujuan
|
||||
|
||||
- Mantis bukan pengganti pengujian unit. Eksekusi Mantis biasanya harus menjadi pengujian regresi yang lebih kecil setelah perbaikannya dipahami.
|
||||
- Mantis bukan gate CI cepat normal. Sistem ini lebih lambat, menggunakan kredensial live, dan dicadangkan untuk bug yang membutuhkan lingkungan live.
|
||||
- Mantis tidak boleh memerlukan manusia untuk operasi normal. VNC manual adalah jalur penyelamatan, bukan jalur utama.
|
||||
- Mantis tidak menyimpan secret mentah dalam artefak, log, tangkapan layar, laporan Markdown, atau komentar PR.
|
||||
- Mantis bukan pengganti unit test. Proses Mantis biasanya harus menjadi
|
||||
regression test yang lebih kecil setelah perbaikannya dipahami.
|
||||
- Mantis bukan gate CI cepat yang normal. Sistem ini lebih lambat, menggunakan
|
||||
kredensial live, dan dicadangkan untuk bug ketika lingkungan live berpengaruh.
|
||||
- Mantis tidak boleh memerlukan manusia untuk operasi normal. VNC manual adalah
|
||||
jalur penyelamatan, bukan jalur utama.
|
||||
- Mantis tidak menyimpan secret mentah dalam artefak, log, screenshot, laporan
|
||||
Markdown, atau komentar PR.
|
||||
|
||||
## Kepemilikan
|
||||
|
||||
Mantis berada dalam stack QA OpenClaw.
|
||||
Mantis berada di stack QA OpenClaw.
|
||||
|
||||
- OpenClaw memiliki runtime skenario, adaptor transport, skema bukti, dan CLI lokal di bawah `pnpm openclaw qa mantis`.
|
||||
- QA Lab memiliki bagian harness transport live, helper penangkapan peramban, dan penulis artefak.
|
||||
- Crabbox memiliki mesin Linux yang sudah dipanaskan saat VM jarak jauh diperlukan.
|
||||
- GitHub Actions memiliki entrypoint workflow jarak jauh dan retensi artefak.
|
||||
- ClawSweeper memiliki routing komentar GitHub: mengurai perintah pengelola, mendispatch workflow, dan memposting komentar PR akhir.
|
||||
- Agen OpenClaw menggerakkan Mantis melalui Codex saat skenario membutuhkan penyiapan agentic, debugging, atau pelaporan status macet.
|
||||
- OpenClaw memiliki runtime skenario, adapter transport, skema bukti, dan CLI
|
||||
lokal di bawah `pnpm openclaw qa mantis`.
|
||||
- QA Lab memiliki bagian harness transport live, helper capture browser, dan
|
||||
penulis artefak.
|
||||
- Crabbox memiliki mesin Linux yang sudah dipanaskan saat VM remote dibutuhkan.
|
||||
- GitHub Actions memiliki entrypoint workflow remote dan retensi artefak.
|
||||
- ClawSweeper memiliki routing komentar GitHub: mem-parsing perintah maintainer,
|
||||
mengirim workflow, dan mengirim komentar PR akhir.
|
||||
- Agen OpenClaw menjalankan Mantis melalui Codex saat skenario membutuhkan setup
|
||||
agentic, debugging, atau pelaporan state macet.
|
||||
|
||||
Batas ini menjaga pengetahuan transport tetap di OpenClaw, penjadwalan mesin di Crabbox, dan perekat workflow pengelola di ClawSweeper.
|
||||
Batas ini menjaga pengetahuan transport di OpenClaw, penjadwalan mesin di
|
||||
Crabbox, dan perekat workflow maintainer di ClawSweeper.
|
||||
|
||||
## Bentuk Perintah
|
||||
|
||||
Perintah lokal pertama memverifikasi bot Discord, guild, kanal, pengiriman pesan, pengiriman reaksi, dan jalur artefak:
|
||||
Perintah lokal pertama memverifikasi bot Discord, guild, channel, pengiriman
|
||||
pesan, pengiriman reaksi, dan jalur artefak:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa mantis discord-smoke \
|
||||
--output-dir .artifacts/qa-e2e/mantis/discord-smoke
|
||||
```
|
||||
|
||||
Runner sebelum dan sesudah lokal menerima bentuk ini:
|
||||
Runner lokal sebelum dan sesudah menerima bentuk ini:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa mantis run \
|
||||
@ -70,22 +92,62 @@ pnpm openclaw qa mantis run \
|
||||
--output-dir .artifacts/qa-e2e/mantis/local-discord-status-reactions
|
||||
```
|
||||
|
||||
Runner membuat worktree baseline dan kandidat yang detached di bawah direktori output, memasang dependensi, membangun setiap ref, menjalankan skenario dengan `--allow-failures`, lalu menulis `baseline/`, `candidate/`, `comparison.json`, dan `mantis-report.md`. Untuk skenario Discord pertama, verifikasi yang berhasil berarti status baseline adalah `fail` dan status kandidat adalah `pass`.
|
||||
Runner membuat worktree baseline dan kandidat yang detached di bawah direktori
|
||||
output, menginstal dependensi, membangun setiap ref, menjalankan skenario dengan
|
||||
`--allow-failures`, lalu menulis `baseline/`, `candidate/`, `comparison.json`,
|
||||
dan `mantis-report.md`. Untuk skenario Discord pertama, verifikasi yang berhasil
|
||||
berarti status baseline adalah `fail` dan status kandidat adalah `pass`.
|
||||
|
||||
Workflow smoke GitHub adalah `Mantis Discord Smoke`. Workflow GitHub sebelum dan sesudah untuk skenario nyata pertama adalah `Mantis Discord Status Reactions`. Workflow ini menerima:
|
||||
Primitif VM/browser pertama adalah smoke desktop:
|
||||
|
||||
- `baseline_ref`: ref yang diharapkan mereproduksi perilaku hanya-antre.
|
||||
- `candidate_ref`: ref yang diharapkan menunjukkan `queued -> thinking -> done`.
|
||||
```bash
|
||||
pnpm openclaw qa mantis desktop-browser-smoke \
|
||||
--output-dir .artifacts/qa-e2e/mantis/desktop-browser
|
||||
```
|
||||
|
||||
Workflow ini melakukan checkout ref harness workflow, membangun worktree baseline dan kandidat yang terpisah, menjalankan `discord-status-reactions-tool-only` terhadap setiap worktree, dan mengunggah `baseline/`, `candidate/`, `comparison.json`, dan `mantis-report.md` sebagai artefak Actions.
|
||||
Perintah ini menyewa atau menggunakan ulang mesin desktop Crabbox, memulai
|
||||
browser yang terlihat di dalam sesi VNC, menangkap desktop, menarik artefak
|
||||
kembali ke direktori output lokal, dan menulis perintah reconnect ke dalam
|
||||
laporan. Perintah ini secara default memakai provider Hetzner karena merupakan
|
||||
provider pertama dengan cakupan desktop/VNC yang berfungsi di jalur Mantis.
|
||||
Timpa dengan `--provider`, `--crabbox-bin`, atau
|
||||
`OPENCLAW_MANTIS_CRABBOX_PROVIDER` saat menjalankan terhadap fleet Crabbox lain.
|
||||
|
||||
Anda juga dapat memicu eksekusi status-reactions langsung dari komentar PR:
|
||||
Flag smoke desktop yang berguna:
|
||||
|
||||
- `--lease-id <cbx_...>` atau `OPENCLAW_MANTIS_CRABBOX_LEASE_ID` menggunakan ulang desktop yang sudah dipanaskan.
|
||||
- `--browser-url <url>` mengubah halaman yang dibuka di browser yang terlihat.
|
||||
- `--html-file <path>` merender artefak HTML lokal repo di browser yang terlihat. Mantis menggunakannya untuk menangkap timeline reaksi status Discord yang dihasilkan melalui desktop Crabbox nyata.
|
||||
- `--keep-lease` atau `OPENCLAW_MANTIS_KEEP_VM=1` menjaga lease lulus yang baru dibuat tetap terbuka untuk inspeksi VNC. Proses yang gagal mempertahankan lease secara default saat lease dibuat agar operator dapat reconnect.
|
||||
- `--class`, `--idle-timeout`, dan `--ttl` menyesuaikan ukuran mesin dan masa pakai lease.
|
||||
|
||||
Workflow smoke GitHub adalah `Mantis Discord Smoke`. Workflow GitHub sebelum dan
|
||||
sesudah untuk skenario nyata pertama adalah `Mantis Discord Status Reactions`.
|
||||
Workflow ini menerima:
|
||||
|
||||
- `baseline_ref`: ref yang diharapkan mereproduksi perilaku hanya queued.
|
||||
- `candidate_ref`: ref yang diharapkan menampilkan `queued -> thinking -> done`.
|
||||
|
||||
Workflow ini men-checkout ref harness workflow, membangun worktree baseline dan
|
||||
kandidat terpisah, menjalankan `discord-status-reactions-tool-only` terhadap
|
||||
setiap worktree, dan mengunggah `baseline/`, `candidate/`, `comparison.json`,
|
||||
dan `mantis-report.md` sebagai artefak Actions. Workflow ini juga merender HTML
|
||||
timeline tiap jalur di browser desktop Crabbox dan memublikasikan screenshot VNC
|
||||
tersebut di samping PNG timeline deterministik dalam komentar PR. Workflow ini
|
||||
membangun CLI Crabbox dari main `openclaw/crabbox` agar dapat menggunakan flag
|
||||
lease desktop/browser saat ini sebelum rilis biner Crabbox berikutnya dibuat.
|
||||
|
||||
Anda juga dapat memicu proses status-reactions langsung dari komentar PR:
|
||||
|
||||
```text
|
||||
@Mantis discord status reactions
|
||||
```
|
||||
|
||||
Pemicu komentar sengaja dibuat sempit. Pemicu ini hanya berjalan pada komentar pull request dari pengguna dengan akses write, maintain, atau admin, dan hanya mengenali permintaan reaksi status Discord. Secara default pemicu ini menggunakan ref baseline bermasalah yang diketahui dan SHA head PR saat ini sebagai kandidat. Pengelola dapat mengganti salah satu ref:
|
||||
Pemicu komentar sengaja dibuat sempit. Pemicu ini hanya berjalan pada komentar
|
||||
pull request dari pengguna dengan akses write, maintain, atau admin, dan hanya
|
||||
mengenali permintaan reaksi status Discord. Secara default, pemicu ini memakai
|
||||
ref baseline bermasalah yang diketahui dan SHA head PR saat ini sebagai kandidat.
|
||||
Maintainer dapat menimpa salah satu ref:
|
||||
|
||||
```text
|
||||
@Mantis discord status reactions baseline=origin/main candidate=HEAD
|
||||
@ -98,41 +160,48 @@ Contoh perintah ClawSweeper:
|
||||
@clawsweeper verify e2e discord
|
||||
```
|
||||
|
||||
Perintah pertama eksplisit dan berfokus pada skenario. Perintah kedua nantinya dapat memetakan PR atau issue ke skenario Mantis yang direkomendasikan dari label, file yang berubah, dan temuan tinjauan ClawSweeper.
|
||||
Perintah pertama eksplisit dan berfokus pada skenario. Perintah kedua nanti
|
||||
dapat memetakan PR atau issue ke skenario Mantis yang direkomendasikan dari
|
||||
label, file yang berubah, dan temuan review ClawSweeper.
|
||||
|
||||
## Siklus Hidup Eksekusi
|
||||
## Siklus Proses
|
||||
|
||||
1. Mendapatkan kredensial.
|
||||
2. Mengalokasikan atau menggunakan ulang VM.
|
||||
3. Menyiapkan checkout bersih untuk ref baseline.
|
||||
4. Memasang dependensi dan membangun hanya yang dibutuhkan skenario.
|
||||
5. Memulai Gateway OpenClaw anak dengan direktori status yang terisolasi.
|
||||
6. Mengonfigurasi transport live, penyedia, model, dan profil peramban.
|
||||
7. Menjalankan skenario dan menangkap bukti baseline.
|
||||
8. Menghentikan gateway dan mempertahankan log.
|
||||
9. Menyiapkan ref kandidat dalam VM yang sama.
|
||||
10. Menjalankan skenario yang sama dan menangkap bukti kandidat.
|
||||
11. Membandingkan hasil oracle dan bukti visual.
|
||||
12. Menulis Markdown, JSON, log, tangkapan layar, dan artefak trace opsional.
|
||||
13. Mengunggah artefak GitHub Actions.
|
||||
14. Memposting pesan status PR atau Discord yang ringkas.
|
||||
3. Menyiapkan profil desktop/browser saat skenario membutuhkan bukti UI.
|
||||
4. Menyiapkan checkout bersih untuk ref baseline.
|
||||
5. Menginstal dependensi dan membangun hanya yang dibutuhkan skenario.
|
||||
6. Memulai child OpenClaw Gateway dengan direktori state terisolasi.
|
||||
7. Mengonfigurasi transport live, provider, model, dan profil browser.
|
||||
8. Menjalankan skenario dan menangkap bukti baseline.
|
||||
9. Menghentikan gateway dan mempertahankan log.
|
||||
10. Menyiapkan ref kandidat di VM yang sama.
|
||||
11. Menjalankan skenario yang sama dan menangkap bukti kandidat.
|
||||
12. Membandingkan hasil oracle dan bukti visual.
|
||||
13. Menulis Markdown, JSON, log, screenshot, dan artefak trace opsional.
|
||||
14. Mengunggah artefak GitHub Actions.
|
||||
15. Mengirim pesan status PR atau Discord yang ringkas.
|
||||
|
||||
Skenario harus dapat gagal dengan dua cara berbeda:
|
||||
|
||||
- **Bug direproduksi**: baseline gagal dengan cara yang diharapkan.
|
||||
- **Kegagalan harness**: penyiapan lingkungan, kredensial, API Discord, peramban, atau penyedia gagal sebelum oracle bug bermakna.
|
||||
- **Kegagalan harness**: setup lingkungan, kredensial, API Discord, browser, atau
|
||||
provider gagal sebelum oracle bug bermakna.
|
||||
|
||||
Laporan akhir harus memisahkan kasus-kasus ini agar pengelola tidak mengira lingkungan yang flaky sebagai perilaku produk.
|
||||
Laporan akhir harus memisahkan kasus-kasus ini agar maintainer tidak mencampur
|
||||
lingkungan yang flaky dengan perilaku produk.
|
||||
|
||||
## MVP Discord
|
||||
|
||||
Skenario pertama harus menargetkan reaksi status Discord di kanal guild tempat mode pengiriman balasan sumber adalah `message_tool_only`.
|
||||
Skenario pertama harus menargetkan reaksi status Discord di channel guild ketika
|
||||
mode pengiriman balasan sumber adalah `message_tool_only`.
|
||||
|
||||
Mengapa ini seed Mantis yang baik:
|
||||
|
||||
- Ini terlihat di Discord sebagai reaksi pada pesan pemicu.
|
||||
- Ini memiliki oracle REST yang kuat melalui status reaksi pesan Discord.
|
||||
- Ini menguji Gateway OpenClaw nyata, autentikasi bot Discord, dispatch pesan, mode pengiriman balasan sumber, status reaksi status, dan siklus hidup giliran model.
|
||||
- Ini memiliki oracle REST yang kuat melalui state reaksi pesan Discord.
|
||||
- Ini melatih OpenClaw Gateway nyata, auth bot Discord, dispatch pesan,
|
||||
mode pengiriman balasan sumber, state reaksi status, dan siklus hidup giliran model.
|
||||
- Ini cukup sempit untuk menjaga implementasi pertama tetap jujur.
|
||||
|
||||
Bentuk skenario yang diharapkan:
|
||||
@ -166,9 +235,12 @@ evidence:
|
||||
screenshotMessageRow: true
|
||||
```
|
||||
|
||||
Bukti baseline harus menunjukkan reaksi pengakuan queued tetapi tanpa transisi siklus hidup dalam mode tool-only. Bukti kandidat harus menunjukkan reaksi status siklus hidup berjalan saat `messages.statusReactions.enabled` secara eksplisit bernilai true.
|
||||
Bukti baseline harus menampilkan reaksi acknowledgement queued tetapi tanpa
|
||||
transisi lifecycle dalam mode tool-only. Bukti kandidat harus menampilkan reaksi
|
||||
status lifecycle yang berjalan saat `messages.statusReactions.enabled` secara
|
||||
eksplisit `true`.
|
||||
|
||||
Irisan pertama yang dapat dieksekusi adalah skenario QA live Discord yang opt-in:
|
||||
Irisan pertama yang dapat dieksekusi adalah skenario QA live Discord opt-in:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa discord \
|
||||
@ -180,23 +252,35 @@ pnpm openclaw qa discord \
|
||||
--output-dir .artifacts/qa-e2e/mantis/discord-status-reactions-candidate
|
||||
```
|
||||
|
||||
Ini mengonfigurasi SUT dengan penanganan guild yang selalu aktif, `visibleReplies: "message_tool"`, `ackReaction: "👀"`, dan reaksi status eksplisit. Oracle melakukan polling pesan pemicu Discord nyata dan mengharapkan urutan yang diamati `👀 -> 🤔 -> 👍`. Artefak mencakup `discord-qa-reaction-timelines.json`, `discord-status-reactions-tool-only-timeline.html`, dan `discord-status-reactions-tool-only-timeline.png`.
|
||||
Skenario ini mengonfigurasi SUT dengan penanganan guild selalu aktif,
|
||||
`visibleReplies: "message_tool"`, `ackReaction: "👀"`, dan reaksi status
|
||||
eksplisit. Oracle melakukan polling pada pesan pemicu Discord nyata dan
|
||||
mengharapkan urutan yang diamati `👀 -> 🤔 -> 👍`. Artefak mencakup
|
||||
`discord-qa-reaction-timelines.json`,
|
||||
`discord-status-reactions-tool-only-timeline.html`, dan
|
||||
`discord-status-reactions-tool-only-timeline.png`.
|
||||
|
||||
## Bagian QA yang Ada
|
||||
## Komponen QA yang Ada
|
||||
|
||||
Mantis harus dibangun di atas stack QA privat yang sudah ada alih-alih memulai dari nol:
|
||||
Mantis harus dibangun di atas stack QA privat yang sudah ada alih-alih memulai
|
||||
dari nol:
|
||||
|
||||
- `pnpm openclaw qa discord` sudah menjalankan jalur Discord live dengan bot driver dan SUT.
|
||||
- Runner transport live sudah menulis laporan dan artefak pesan yang diamati di bawah `.artifacts/qa-e2e/`.
|
||||
- Lease kredensial Convex sudah menyediakan akses eksklusif ke kredensial transport live bersama.
|
||||
- Layanan kontrol peramban sudah mendukung tangkapan layar, snapshot, profil terkelola headless, dan profil CDP jarak jauh.
|
||||
- `pnpm openclaw qa discord` sudah menjalankan jalur Discord live dengan bot
|
||||
driver dan SUT.
|
||||
- Runner transport live sudah menulis laporan dan artefak pesan yang diamati di
|
||||
bawah `.artifacts/qa-e2e/`.
|
||||
- Lease kredensial Convex sudah menyediakan akses eksklusif ke kredensial
|
||||
transport live bersama.
|
||||
- Layanan kontrol browser sudah mendukung screenshot, snapshot, profil managed
|
||||
headless, dan profil CDP remote.
|
||||
- QA Lab sudah memiliki UI debugger dan bus untuk pengujian berbentuk transport.
|
||||
|
||||
Implementasi Mantis pertama dapat berupa runner sebelum/sesudah yang tipis di atas bagian-bagian ini, ditambah satu lapisan bukti visual.
|
||||
Implementasi Mantis pertama dapat berupa runner sebelum/sesudah tipis di atas
|
||||
komponen-komponen ini, ditambah satu lapisan bukti visual.
|
||||
|
||||
## Model Bukti
|
||||
|
||||
Setiap eksekusi menulis direktori artefak yang stabil:
|
||||
Setiap proses menulis direktori artefak yang stabil:
|
||||
|
||||
```text
|
||||
.artifacts/qa-e2e/mantis/<run-id>/
|
||||
@ -216,65 +300,79 @@ Setiap eksekusi menulis direktori artefak yang stabil:
|
||||
run.log
|
||||
```
|
||||
|
||||
`mantis-summary.json` harus menjadi sumber kebenaran yang dapat dibaca mesin. Laporan Markdown ditujukan untuk komentar PR dan tinjauan manusia.
|
||||
`mantis-summary.json` harus menjadi sumber kebenaran yang dapat dibaca mesin.
|
||||
Laporan Markdown ditujukan untuk komentar PR dan review manusia.
|
||||
|
||||
Ringkasan harus mencakup:
|
||||
|
||||
- ref dan SHA yang diuji
|
||||
- transport dan id skenario
|
||||
- penyedia mesin dan id mesin atau id lease
|
||||
- provider mesin dan id mesin atau id lease
|
||||
- sumber kredensial tanpa nilai secret
|
||||
- hasil baseline
|
||||
- hasil kandidat
|
||||
- apakah bug direproduksi pada baseline
|
||||
- apakah kandidat memperbaikinya
|
||||
- jalur artefak
|
||||
- masalah penyiapan atau pembersihan yang disanitasi
|
||||
- masalah setup atau cleanup yang sudah disanitasi
|
||||
|
||||
Tangkapan layar adalah bukti, bukan secret. Namun tetap membutuhkan disiplin redaksi: nama kanal privat, nama pengguna, atau isi pesan dapat muncul. Untuk PR publik, utamakan tautan artefak GitHub Actions daripada gambar inline sampai cerita redaksinya lebih kuat.
|
||||
Screenshot adalah bukti, bukan secret. Screenshot tetap membutuhkan disiplin
|
||||
redaksi: nama channel privat, nama pengguna, atau isi pesan mungkin muncul.
|
||||
Untuk PR publik, utamakan link artefak GitHub Actions daripada gambar inline
|
||||
hingga cerita redaksi lebih kuat.
|
||||
|
||||
## Peramban dan VNC
|
||||
## Browser dan VNC
|
||||
|
||||
Jalur peramban memiliki dua mode:
|
||||
Jalur browser memiliki dua mode:
|
||||
|
||||
- **Otomatisasi headless**: default untuk CI. Chrome berjalan dengan CDP diaktifkan, dan Playwright atau kontrol peramban OpenClaw menangkap tangkapan layar.
|
||||
- **Penyelamatan VNC**: diaktifkan pada VM yang sama saat login, MFA, anti-otomatisasi Discord, atau debugging visual membutuhkan manusia.
|
||||
- **Otomasi headless**: default untuk CI. Chrome berjalan dengan CDP aktif, dan
|
||||
Playwright atau kontrol browser OpenClaw menangkap screenshot.
|
||||
- **Penyelamatan VNC**: diaktifkan pada VM yang sama saat login, MFA, anti-otomasi
|
||||
Discord, atau debugging visual membutuhkan manusia.
|
||||
|
||||
Profil peramban pengamat Discord harus cukup persisten untuk menghindari login pada setiap eksekusi, tetapi terisolasi dari status peramban pribadi. Profil dimiliki oleh pool mesin Mantis, bukan laptop developer.
|
||||
Profil browser pengamat Discord harus cukup persisten untuk menghindari
|
||||
login pada setiap proses berjalan, tetapi terisolasi dari status browser pribadi. Profil
|
||||
milik kumpulan mesin Mantis, bukan laptop pengembang.
|
||||
|
||||
Saat Mantis macet, sistem ini memposting pesan status Discord dengan:
|
||||
Saat Mantis macet, ia memposting pesan status Discord dengan:
|
||||
|
||||
- id eksekusi
|
||||
- id proses berjalan
|
||||
- id skenario
|
||||
- penyedia mesin
|
||||
- direktori artefak
|
||||
- instruksi koneksi VNC atau noVNC jika tersedia
|
||||
- teks pemblokir singkat
|
||||
|
||||
Deployment privat pertama dapat memposting pesan-pesan ini ke kanal operator yang sudah ada dan berpindah ke kanal Mantis khusus nanti.
|
||||
Deployment privat pertama dapat memposting pesan ini ke kanal operator yang sudah ada
|
||||
dan berpindah ke kanal Mantis khusus nanti.
|
||||
|
||||
## Mesin
|
||||
|
||||
Mantis harus mengutamakan AWS melalui Crabbox untuk implementasi jarak jauh pertama. Crabbox memberi kita mesin yang sudah dipanaskan, pelacakan lease, hidrasi, log, hasil, dan pembersihan. Jika kapasitas AWS terlalu lambat atau tidak tersedia, tambahkan penyedia Hetzner di balik antarmuka mesin yang sama.
|
||||
Mantis sebaiknya memprioritaskan AWS melalui Crabbox untuk implementasi jarak jauh pertama.
|
||||
Crabbox memberi kita mesin yang sudah dipanaskan, pelacakan sewa, hidrasi, log, hasil, dan
|
||||
pembersihan. Jika kapasitas AWS terlalu lambat atau tidak tersedia, tambahkan penyedia Hetzner
|
||||
di balik antarmuka mesin yang sama.
|
||||
|
||||
Persyaratan VM minimum:
|
||||
Persyaratan minimum VM:
|
||||
|
||||
- Linux dengan instalasi Chrome atau Chromium yang mampu desktop
|
||||
- akses CDP untuk otomatisasi peramban
|
||||
- Linux dengan instalasi Chrome atau Chromium yang mendukung desktop
|
||||
- akses CDP untuk otomasi browser
|
||||
- VNC atau noVNC untuk penyelamatan
|
||||
- Node 22 dan pnpm
|
||||
- checkout OpenClaw dan cache dependensi
|
||||
- cache peramban Playwright Chromium saat Playwright digunakan
|
||||
- CPU dan memori yang cukup untuk satu Gateway OpenClaw, satu peramban, dan satu eksekusi model
|
||||
- cache browser Playwright Chromium saat Playwright digunakan
|
||||
- CPU dan memori yang cukup untuk satu OpenClaw Gateway, satu browser, dan satu proses model
|
||||
- akses keluar ke Discord, GitHub, penyedia model, dan broker kredensial
|
||||
|
||||
VM tidak boleh menyimpan secret mentah berumur panjang di luar penyimpanan kredensial atau profil peramban yang diharapkan.
|
||||
VM tidak boleh menyimpan rahasia mentah berumur panjang di luar penyimpanan kredensial atau
|
||||
profil browser yang diharapkan.
|
||||
|
||||
## Secret
|
||||
## Rahasia
|
||||
|
||||
Secret berada di secret organisasi atau repositori GitHub untuk eksekusi jarak jauh, dan di file secret lokal yang dikendalikan operator untuk eksekusi lokal.
|
||||
Rahasia berada di rahasia organisasi atau repositori GitHub untuk proses jarak jauh, dan di
|
||||
file rahasia lokal yang dikendalikan operator untuk proses lokal.
|
||||
|
||||
Nama secret yang direkomendasikan:
|
||||
Nama rahasia yang direkomendasikan:
|
||||
|
||||
- `OPENCLAW_QA_DISCORD_MANTIS_BOT_TOKEN`
|
||||
- `OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN`
|
||||
@ -285,27 +383,47 @@ Nama secret yang direkomendasikan:
|
||||
- `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` untuk unggahan artefak GitHub publik
|
||||
- `OPENCLAW_QA_CONVEX_SITE_URL`
|
||||
- `OPENCLAW_QA_CONVEX_SECRET_CI`
|
||||
- `OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR`
|
||||
- `OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR_TOKEN`
|
||||
|
||||
Dalam jangka panjang, kumpulan kredensial Convex harus tetap menjadi sumber normal untuk kredensial transport langsung. Rahasia GitHub melakukan bootstrap broker dan lane fallback.
|
||||
Dalam jangka panjang, kumpulan kredensial Convex harus tetap menjadi sumber normal untuk kredensial
|
||||
transport langsung. Rahasia GitHub melakukan bootstrap broker dan jalur fallback.
|
||||
Alur kerja reaksi-status Discord memetakan rahasia Mantis Crabbox kembali ke
|
||||
variabel lingkungan `CRABBOX_COORDINATOR` dan `CRABBOX_COORDINATOR_TOKEN`
|
||||
yang diharapkan CLI Crabbox. Nama rahasia GitHub `CRABBOX_*` biasa tetap
|
||||
diterima sebagai fallback kompatibilitas.
|
||||
|
||||
Runner Mantis tidak boleh pernah mencetak:
|
||||
|
||||
- token bot Discord
|
||||
- kunci API penyedia
|
||||
- cookie browser
|
||||
- isi profil auth
|
||||
- isi profil autentikasi
|
||||
- kata sandi VNC
|
||||
- payload kredensial mentah
|
||||
|
||||
Unggahan artefak publik juga harus menyunting metadata target Discord seperti id bot, guild, channel, dan pesan. Alur kerja smoke GitHub mengaktifkan `OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` karena alasan ini.
|
||||
Unggahan artefak publik juga harus menyamarkan metadata target Discord seperti id bot,
|
||||
guild, kanal, dan pesan. Alur kerja smoke GitHub mengaktifkan
|
||||
`OPENCLAW_QA_REDACT_PUBLIC_METADATA=1` karena alasan ini.
|
||||
|
||||
Jika token tidak sengaja ditempelkan ke issue, PR, chat, atau log, rotasikan token tersebut setelah rahasia baru disimpan.
|
||||
Jika token tidak sengaja ditempelkan ke issue, PR, chat, atau log, rotasikan token itu
|
||||
setelah rahasia baru disimpan.
|
||||
|
||||
## Artefak GitHub Dan Komentar PR
|
||||
|
||||
Alur kerja Mantis harus mengunggah bundle bukti lengkap sebagai artefak Actions berumur pendek. Ketika alur kerja dijalankan untuk laporan bug atau PR perbaikan, alur kerja juga harus menerbitkan tangkapan layar PNG yang sudah disunting ke branch `qa-artifacts` dan melakukan upsert komentar pada bug atau PR perbaikan tersebut dengan tangkapan layar sebelum/sesudah inline. Jangan memposting bukti utama hanya pada PR otomatisasi QA generik. Log mentah, pesan yang teramati, dan bukti besar lainnya tetap berada di artefak Actions.
|
||||
Alur kerja Mantis harus mengunggah bundel bukti lengkap sebagai artefak Actions
|
||||
berumur pendek. Saat alur kerja dijalankan untuk laporan bug atau PR perbaikan, alur itu juga
|
||||
harus memublikasikan tangkapan layar PNG yang sudah disamarkan ke cabang `qa-artifacts` dan melakukan upsert
|
||||
komentar pada bug atau PR perbaikan tersebut dengan tangkapan layar sebelum/sesudah inline. Jangan memposting
|
||||
bukti utama hanya pada PR otomasi QA generik. Log mentah, pesan yang diamati,
|
||||
dan bukti besar lainnya tetap berada di artefak Actions.
|
||||
|
||||
Alur kerja produksi harus memposting komentar tersebut dengan GitHub App Mantis, bukan dengan `github-actions[bot]`. Simpan id aplikasi dan kunci privat sebagai rahasia GitHub Actions `MANTIS_GITHUB_APP_ID` dan `MANTIS_GITHUB_APP_PRIVATE_KEY`. Alur kerja menggunakan marker tersembunyi sebagai kunci upsert, memperbarui komentar tersebut ketika token dapat mengeditnya, dan membuat komentar baru milik Mantis ketika marker lama milik bot tidak dapat diedit.
|
||||
Alur kerja produksi harus memposting komentar tersebut dengan Mantis GitHub App, bukan
|
||||
dengan `github-actions[bot]`. Simpan id aplikasi dan kunci privat sebagai rahasia
|
||||
GitHub Actions `MANTIS_GITHUB_APP_ID` dan `MANTIS_GITHUB_APP_PRIVATE_KEY`.
|
||||
Alur kerja menggunakan penanda tersembunyi sebagai kunci upsert, memperbarui
|
||||
komentar itu saat token dapat mengeditnya, dan membuat komentar baru milik Mantis saat
|
||||
penanda lama milik bot tidak dapat diedit.
|
||||
|
||||
Komentar PR harus singkat dan visual:
|
||||
|
||||
@ -327,15 +445,22 @@ candidate showed the expected queued -> thinking -> done sequence.
|
||||
| <inline screenshot> | <inline screenshot> |
|
||||
```
|
||||
|
||||
Ketika run gagal karena harness gagal, komentar harus menyatakan hal itu, bukan menyiratkan kandidat gagal.
|
||||
Saat proses gagal karena harness gagal, komentar harus menyatakan hal itu, bukan
|
||||
menyiratkan bahwa kandidat gagal.
|
||||
|
||||
## Catatan Deployment Privat
|
||||
|
||||
Deployment privat mungkin sudah memiliki aplikasi Discord Mantis. Gunakan ulang aplikasi tersebut alih-alih membuat aplikasi lain ketika aplikasi itu memiliki izin bot yang tepat dan dapat dirotasi dengan aman.
|
||||
Deployment privat mungkin sudah memiliki aplikasi Discord Mantis. Gunakan kembali
|
||||
aplikasi itu alih-alih membuat aplikasi lain saat aplikasi tersebut memiliki izin bot yang tepat
|
||||
dan dapat dirotasi dengan aman.
|
||||
|
||||
Tetapkan channel notifikasi operator awal melalui rahasia atau konfigurasi deployment. Channel tersebut dapat mengarah ke channel maintainer atau operasi yang sudah ada terlebih dahulu, lalu dipindahkan ke channel Mantis khusus setelah tersedia.
|
||||
Tetapkan kanal notifikasi operator awal melalui rahasia atau konfigurasi deployment.
|
||||
Kanal itu dapat mengarah ke kanal maintainer atau operasi yang sudah ada terlebih dahulu,
|
||||
lalu berpindah ke kanal Mantis khusus setelah kanal tersebut ada.
|
||||
|
||||
Jangan menaruh id guild, id channel, token bot, cookie browser, atau kata sandi VNC dalam dokumen ini. Simpan semuanya di rahasia GitHub, broker kredensial, atau penyimpanan rahasia lokal milik operator.
|
||||
Jangan menaruh id guild, id kanal, token bot, cookie browser, atau kata sandi VNC
|
||||
di dokumen ini. Simpan di rahasia GitHub, broker kredensial, atau penyimpanan
|
||||
rahasia lokal operator.
|
||||
|
||||
## Menambahkan Skenario
|
||||
|
||||
@ -352,35 +477,41 @@ Skenario Mantis harus mendeklarasikan:
|
||||
- oracle baseline yang diharapkan
|
||||
- oracle kandidat yang diharapkan
|
||||
- target tangkapan visual
|
||||
- anggaran timeout
|
||||
- anggaran waktu habis
|
||||
- langkah pembersihan
|
||||
|
||||
Skenario harus mengutamakan oracle kecil dan bertipe:
|
||||
Skenario sebaiknya memprioritaskan oracle kecil dan bertipe:
|
||||
|
||||
- status reaksi Discord untuk bug reaksi
|
||||
- referensi pesan Discord untuk bug threading
|
||||
- ts thread Slack dan status API reaksi untuk bug Slack
|
||||
- id pesan email dan header untuk bug email
|
||||
- tangkapan layar browser ketika UI adalah satu-satunya observasi yang andal
|
||||
- tangkapan layar browser saat UI adalah satu-satunya hal teramati yang andal
|
||||
|
||||
Pemeriksaan vision harus bersifat aditif. Jika API platform dapat membuktikan bug, gunakan API sebagai oracle lulus/gagal dan simpan tangkapan layar untuk keyakinan manusia.
|
||||
Pemeriksaan visi harus bersifat tambahan. Jika API platform dapat membuktikan bug, gunakan
|
||||
API sebagai oracle lulus/gagal dan simpan tangkapan layar untuk keyakinan manusia.
|
||||
|
||||
## Ekspansi Penyedia
|
||||
|
||||
Setelah Discord, runner yang sama dapat menambahkan:
|
||||
|
||||
- Slack: reaksi, thread, mention aplikasi, modal, unggahan file.
|
||||
- Email: auth Gmail dan threading pesan menggunakan `gog` ketika connector tidak cukup.
|
||||
- Email: autentikasi Gmail dan threading pesan menggunakan `gog` saat konektor tidak
|
||||
cukup.
|
||||
- WhatsApp: login QR, identifikasi ulang, pengiriman pesan, media, reaksi.
|
||||
- Telegram: gating mention grup, perintah, reaksi jika tersedia.
|
||||
- Matrix: ruang terenkripsi, relasi thread atau balasan, resume restart.
|
||||
- Matrix: ruang terenkripsi, relasi thread atau balasan, resume setelah restart.
|
||||
|
||||
Setiap transport harus memiliki satu skenario smoke murah dan satu atau lebih skenario kelas bug. Skenario visual yang mahal harus tetap opt-in.
|
||||
Setiap transport harus memiliki satu skenario smoke murah dan satu atau lebih skenario
|
||||
kelas bug. Skenario visual yang mahal harus tetap opt-in.
|
||||
|
||||
## Pertanyaan Terbuka
|
||||
|
||||
- Bot Discord mana yang harus menjadi driver, dan mana yang harus menjadi SUT, ketika bot Mantis yang sudah ada digunakan ulang?
|
||||
- Apakah login browser observer harus menggunakan akun Discord manusia, akun uji, atau hanya bukti REST yang dapat dibaca bot untuk fase pertama?
|
||||
- Bot Discord mana yang harus menjadi driver, dan mana yang harus menjadi SUT, saat bot
|
||||
Mantis yang sudah ada digunakan kembali?
|
||||
- Apakah login browser pengamat harus menggunakan akun Discord manusia, akun pengujian,
|
||||
atau hanya bukti REST yang dapat dibaca bot untuk fase pertama?
|
||||
- Berapa lama GitHub harus menyimpan artefak Mantis untuk PR?
|
||||
- Kapan ClawSweeper harus otomatis merekomendasikan Mantis alih-alih menunggu perintah maintainer?
|
||||
- Apakah tangkapan layar harus disunting atau dipotong sebelum diunggah untuk PR publik?
|
||||
- Kapan ClawSweeper harus otomatis merekomendasikan Mantis alih-alih menunggu
|
||||
perintah maintainer?
|
||||
- Apakah tangkapan layar harus disamarkan atau dipotong sebelum diunggah untuk PR publik?
|
||||
|
||||
@ -1,32 +1,32 @@
|
||||
---
|
||||
read_when:
|
||||
- Mengonfigurasi pembaruan progres yang terlihat untuk giliran obrolan yang berjalan lama
|
||||
- Mengonfigurasi pembaruan progres yang terlihat untuk giliran percakapan yang berjalan lama
|
||||
- Memilih antara mode streaming parsial, blok, dan progres
|
||||
- Menjelaskan bagaimana OpenClaw memperbarui satu pesan saluran saat pekerjaan sedang berlangsung
|
||||
- Pemecahan masalah draf progres, pesan progres mandiri, atau mekanisme cadangan finalisasi
|
||||
- Menjelaskan cara OpenClaw memperbarui satu pesan saluran saat pekerjaan sedang berlangsung
|
||||
- Memecahkan masalah draf progres, pesan progres mandiri, atau fallback finalisasi
|
||||
summary: 'Draf progres: satu pesan pekerjaan yang sedang berlangsung yang terlihat dan diperbarui saat agen berjalan'
|
||||
title: Draf progres
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:30:57Z"
|
||||
generated_at: "2026-05-04T02:23:21Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 0fc0dff38232228b49872d66f4498f065675cdd3abf3a0f4003cb34fcbb7de8c
|
||||
source_hash: 8ce19262800f1c3c3e505a3cf1d41ed5c3dffcbca168ad7b7afabdce62eee8fe
|
||||
source_path: concepts/progress-drafts.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Draf progres membuat giliran agen yang berjalan lama terasa hidup dalam chat tanpa mengubah percakapan menjadi tumpukan balasan status sementara.
|
||||
Draf progres membuat giliran agen yang berjalan lama terasa hidup di chat tanpa mengubah percakapan menjadi tumpukan balasan status sementara.
|
||||
|
||||
Saat draf progres diaktifkan, OpenClaw membuat satu pesan pekerjaan-berjalan yang terlihat, memperbaruinya saat agen membaca, merencanakan, memanggil alat, atau menunggu persetujuan, lalu mengubah draf tersebut menjadi jawaban akhir saat channel dapat melakukannya dengan aman.
|
||||
Saat draf progres diaktifkan, OpenClaw membuat satu pesan pekerjaan-yang-sedang-berlangsung yang terlihat hanya setelah giliran terbukti benar-benar bekerja, memperbaruinya saat agen membaca, merencanakan, memanggil alat, atau menunggu persetujuan, lalu mengubah draf itu menjadi jawaban akhir ketika channel dapat melakukannya dengan aman.
|
||||
|
||||
```text
|
||||
Shelling
|
||||
- reading recent channel context
|
||||
- checking matching issues
|
||||
- preparing reply
|
||||
Shelling...
|
||||
📖 Read: from docs/concepts/progress-drafts.md
|
||||
🔎 Web Search: for "discord edit message"
|
||||
🛠️ Exec: run tests
|
||||
```
|
||||
|
||||
Gunakan draf progres saat Anda menginginkan satu pesan status yang rapi selama pekerjaan yang intensif alat dan jawaban akhir saat giliran selesai.
|
||||
Gunakan draf progres ketika Anda menginginkan satu pesan status yang rapi selama pekerjaan yang banyak memakai alat dan jawaban akhir saat giliran selesai.
|
||||
|
||||
## Mulai Cepat
|
||||
|
||||
@ -44,63 +44,64 @@ Aktifkan draf progres per channel dengan `streaming.mode: "progress"`:
|
||||
}
|
||||
```
|
||||
|
||||
Biasanya itu sudah cukup. OpenClaw akan memilih label satu kata otomatis, menambahkan baris progres ringkas saat pekerjaan berguna berlangsung, dan menekan percakapan progres mandiri yang duplikat untuk giliran tersebut.
|
||||
Itu biasanya cukup. OpenClaw akan memilih label satu kata otomatis, menunggu hingga pekerjaan berlangsung setidaknya lima detik atau memancarkan peristiwa kerja kedua, menambahkan baris progres ringkas saat pekerjaan yang berguna terjadi, dan menekan obrolan progres mandiri duplikat untuk giliran tersebut.
|
||||
|
||||
## Yang Dilihat Pengguna
|
||||
|
||||
Draf progres memiliki dua bagian:
|
||||
|
||||
| Bagian | Tujuan |
|
||||
| -------------- | -------------------------------------------------------------------- |
|
||||
| Label | Judul singkat seperti `Thinking` atau `Shelling`. |
|
||||
| Baris progres | Pembaruan eksekusi ringkas seperti panggilan alat, langkah tugas, atau persetujuan. |
|
||||
| Bagian | Tujuan |
|
||||
| -------------- | --------------------------------------------------------------------------- |
|
||||
| Label | Judul singkat seperti `Thinking...` atau `Shelling...`. |
|
||||
| Baris progres | Pembaruan eksekusi ringkas menggunakan label alat dan ikon yang sama seperti keluaran verbose. |
|
||||
|
||||
Label muncul segera saat agen mulai membalas. Baris progres hanya ditambahkan saat agen memancarkan pembaruan pekerjaan yang berguna. Jawaban akhir menggantikan draf jika memungkinkan; jika tidak, OpenClaw mengirim jawaban akhir seperti biasa dan membersihkan atau berhenti memperbarui draf sesuai transport channel.
|
||||
Label muncul setelah agen memulai pekerjaan bermakna dan tetap sibuk selama lima detik atau memancarkan peristiwa kerja kedua. Balasan teks biasa saja tidak menampilkan draf progres. Baris progres ditambahkan hanya ketika agen memancarkan pembaruan kerja yang berguna, misalnya `🛠️ Exec`, `🔎 Web Search`, atau `✍️ Write: to /tmp/file`. Secara default, baris tersebut menggunakan mode penjelasan ringkas yang sama seperti `/verbose`; atur `agents.defaults.toolProgressDetail: "raw"` saat debugging dan Anda juga ingin perintah/detail mentah ditambahkan.
|
||||
Jawaban akhir menggantikan draf bila memungkinkan; jika tidak, OpenClaw mengirim jawaban akhir secara normal dan membersihkan atau berhenti memperbarui draf sesuai transport channel.
|
||||
|
||||
## Pilih Mode
|
||||
|
||||
`channels.<channel>.streaming.mode` mengontrol perilaku pekerjaan-berjalan yang terlihat:
|
||||
`channels.<channel>.streaming.mode` mengontrol perilaku dalam-progres yang terlihat:
|
||||
|
||||
| Mode | Paling cocok untuk | Yang muncul di chat |
|
||||
| ---------- | ------------------------------------------ | -------------------------------------------------------- |
|
||||
| `off` | Channel yang tenang | Hanya jawaban akhir. |
|
||||
| `partial` | Melihat teks jawaban muncul | Satu draf yang diedit dengan teks jawaban terbaru. |
|
||||
| `block` | Potongan pratinjau jawaban yang lebih besar | Satu pratinjau diperbarui atau ditambahkan dalam potongan yang lebih besar. |
|
||||
| `progress` | Giliran yang intensif alat atau berjalan lama | Satu draf status, lalu jawaban akhir. |
|
||||
| Mode | Paling cocok untuk | Yang muncul di chat |
|
||||
| ---------- | --------------------------------- | ------------------------------------------------ |
|
||||
| `off` | Channel yang senyap | Hanya jawaban akhir. |
|
||||
| `partial` | Melihat teks jawaban muncul | Satu draf yang diedit dengan teks jawaban terbaru. |
|
||||
| `block` | Potongan pratinjau jawaban lebih besar | Satu pratinjau yang diperbarui atau ditambahkan dalam potongan lebih besar. |
|
||||
| `progress` | Giliran yang banyak memakai alat atau berjalan lama | Satu draf status, lalu jawaban akhir. |
|
||||
|
||||
Pilih `progress` saat pengguna lebih peduli pada "apa yang sedang terjadi" daripada melihat teks jawaban mengalir token demi token.
|
||||
Pilih `progress` ketika pengguna lebih peduli pada "apa yang sedang terjadi" daripada melihat teks jawaban mengalir token demi token.
|
||||
|
||||
Pilih `partial` saat jawaban itu sendiri adalah sinyal progres.
|
||||
Pilih `partial` ketika jawaban itu sendiri adalah sinyal progres.
|
||||
|
||||
Pilih `block` saat Anda menginginkan pembaruan pratinjau draf dalam potongan teks yang lebih besar. Di Discord dan Telegram, `streaming.mode: "block"` tetap merupakan streaming pratinjau, bukan pengiriman blok normal. Gunakan `streaming.block.enabled` atau `blockStreaming` lama saat Anda menginginkan balasan blok normal.
|
||||
Pilih `block` ketika Anda menginginkan pembaruan pratinjau draf dalam potongan teks yang lebih besar. Di Discord dan Telegram, `streaming.mode: "block"` masih berupa streaming pratinjau, bukan pengiriman blok normal. Gunakan `streaming.block.enabled` atau `blockStreaming` lama ketika Anda menginginkan balasan blok normal.
|
||||
|
||||
## Konfigurasi Label
|
||||
|
||||
Label progres berada di bawah `channels.<channel>.streaming.progress`.
|
||||
|
||||
Label default adalah `auto`, yang memilih dari kumpulan label satu kata bawaan OpenClaw:
|
||||
Label default adalah `auto`, yang memilih dari kumpulan label bawaan OpenClaw berupa satu-kata-dengan-elipsis:
|
||||
|
||||
```text
|
||||
Thinking
|
||||
Shelling
|
||||
Scuttling
|
||||
Clawing
|
||||
Pinching
|
||||
Molting
|
||||
Bubbling
|
||||
Tiding
|
||||
Reefing
|
||||
Cracking
|
||||
Sifting
|
||||
Brining
|
||||
Nautiling
|
||||
Krilling
|
||||
Barnacling
|
||||
Lobstering
|
||||
Tidepooling
|
||||
Pearling
|
||||
Snapping
|
||||
Surfacing
|
||||
Thinking...
|
||||
Shelling...
|
||||
Scuttling...
|
||||
Clawing...
|
||||
Pinching...
|
||||
Molting...
|
||||
Bubbling...
|
||||
Tiding...
|
||||
Reefing...
|
||||
Cracking...
|
||||
Sifting...
|
||||
Brining...
|
||||
Nautiling...
|
||||
Krilling...
|
||||
Barnacling...
|
||||
Lobstering...
|
||||
Tidepooling...
|
||||
Pearling...
|
||||
Snapping...
|
||||
Surfacing...
|
||||
```
|
||||
|
||||
Gunakan label tetap:
|
||||
@ -138,7 +139,7 @@ Gunakan kumpulan label otomatis Anda sendiri:
|
||||
}
|
||||
```
|
||||
|
||||
Sembunyikan label dan hanya tampilkan baris progres:
|
||||
Sembunyikan label dan tampilkan hanya baris progres:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -159,6 +160,27 @@ Sembunyikan label dan hanya tampilkan baris progres:
|
||||
|
||||
Baris progres diaktifkan secara default dalam mode progres. Baris tersebut berasal dari peristiwa eksekusi nyata: awal alat, pembaruan item, rencana tugas, persetujuan, keluaran perintah, ringkasan patch, dan aktivitas agen serupa.
|
||||
|
||||
OpenClaw menggunakan formatter yang sama untuk draf progres dan `/verbose`:
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
toolProgressDetail: "explain", // explain | raw
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
`"explain"` adalah default dan menjaga draf tetap stabil dengan label ringkas seperti `🛠️ Exec: check JS syntax for /tmp/app.js`. `"raw"` menambahkan perintah/detail yang mendasari bila tersedia, yang berguna saat debugging tetapi lebih ramai di chat.
|
||||
|
||||
Misalnya, perintah yang sama muncul berbeda tergantung mode detail:
|
||||
|
||||
| Mode | Baris progres |
|
||||
| --------- | ------------------------------------------------------------------- |
|
||||
| `explain` | `🛠️ Exec: check JS syntax for /tmp/app.js` |
|
||||
| `raw` | `🛠️ Exec: check JS syntax for /tmp/app.js, node --check /tmp/app.js` |
|
||||
|
||||
Batasi jumlah baris yang tetap terlihat:
|
||||
|
||||
```json5
|
||||
@ -193,22 +215,22 @@ Pertahankan satu draf progres tetapi sembunyikan baris alat dan tugas:
|
||||
}
|
||||
```
|
||||
|
||||
Dengan `toolProgress: false`, OpenClaw tetap menekan pesan progres alat mandiri lama untuk giliran tersebut. Channel tetap tenang secara visual hingga jawaban akhir, kecuali label jika ada yang dikonfigurasi.
|
||||
Dengan `toolProgress: false`, OpenClaw tetap menekan pesan progres-alat mandiri yang lebih lama untuk giliran tersebut. Channel tetap tenang secara visual sampai jawaban akhir, kecuali label jika dikonfigurasi.
|
||||
|
||||
## Perilaku Channel
|
||||
|
||||
Setiap channel menggunakan transport paling bersih yang didukungnya:
|
||||
|
||||
| Channel | Transport progres | Catatan |
|
||||
| --------------- | ------------------------------------- | ----------------------------------------------------------------------- |
|
||||
| Discord | Kirim satu pesan, lalu edit pesan itu. | Teks akhir diedit di tempat saat muat dalam satu pesan pratinjau aman. |
|
||||
| Matrix | Kirim satu peristiwa, lalu edit peristiwa itu. | Konfigurasi streaming tingkat akun mengontrol draf tingkat akun. |
|
||||
| Microsoft Teams | Stream Teams native dalam chat personal. | `streaming.mode: "block"` dipetakan ke pengiriman blok Teams. |
|
||||
| Channel | Transport progres | Catatan |
|
||||
| --------------- | -------------------------------------- | --------------------------------------------------------------------- |
|
||||
| Discord | Kirim satu pesan, lalu edit. | Teks akhir diedit di tempat ketika muat dalam satu pesan pratinjau aman. |
|
||||
| Matrix | Kirim satu peristiwa, lalu edit. | Konfigurasi streaming tingkat akun mengontrol draf tingkat akun. |
|
||||
| Microsoft Teams | Stream Teams native dalam chat pribadi. | `streaming.mode: "block"` dipetakan ke pengiriman blok Teams. |
|
||||
| Slack | Stream native atau posting draf yang dapat diedit. | Ketersediaan thread memengaruhi apakah streaming native dapat digunakan. |
|
||||
| Telegram | Kirim satu pesan, lalu edit pesan itu. | Draf lama yang terlihat dapat diganti agar stempel waktu akhir tetap berguna. |
|
||||
| Mattermost | Posting draf yang dapat diedit. | Aktivitas alat digabungkan ke posting bergaya draf yang sama. |
|
||||
| Telegram | Kirim satu pesan, lalu edit. | Draf lama yang terlihat dapat diganti agar timestamp akhir tetap berguna. |
|
||||
| Mattermost | Posting draf yang dapat diedit. | Aktivitas alat digabungkan ke posting bergaya draf yang sama. |
|
||||
|
||||
Channel tanpa dukungan edit yang aman biasanya kembali ke indikator mengetik atau pengiriman hanya-akhir.
|
||||
Channel tanpa dukungan edit aman biasanya fallback ke indikator mengetik atau pengiriman hanya-final.
|
||||
|
||||
## Finalisasi
|
||||
|
||||
@ -216,15 +238,15 @@ Saat jawaban akhir siap, OpenClaw mencoba menjaga chat tetap bersih:
|
||||
|
||||
- Jika draf dapat dengan aman menjadi jawaban akhir, OpenClaw mengeditnya di tempat.
|
||||
- Jika channel menggunakan streaming progres native, OpenClaw memfinalisasi stream tersebut saat transport native menerima teks akhir.
|
||||
- Jika jawaban akhir memiliki media, prompt persetujuan, target balasan eksplisit, terlalu banyak potongan, atau edit/kirim yang gagal, OpenClaw mengirim jawaban akhir melalui jalur pengiriman channel normal.
|
||||
- Jika jawaban akhir memiliki media, prompt persetujuan, target balasan eksplisit, terlalu banyak potongan, atau edit/kirim gagal, OpenClaw mengirim jawaban akhir melalui jalur pengiriman channel normal.
|
||||
|
||||
Jalur fallback ini disengaja. Lebih baik mengirim jawaban akhir baru daripada kehilangan teks, salah menempatkan thread balasan, atau menimpa draf dengan payload yang tidak dapat direpresentasikan channel secara aman.
|
||||
Jalur fallback ini disengaja. Lebih baik mengirim jawaban akhir baru daripada kehilangan teks, salah menempatkan balasan dalam thread, atau menimpa draf dengan payload yang tidak dapat direpresentasikan channel dengan aman.
|
||||
|
||||
## Pemecahan Masalah
|
||||
|
||||
**Saya hanya melihat jawaban akhir.**
|
||||
|
||||
Periksa bahwa `channels.<channel>.streaming.mode` diatur ke `progress` untuk akun atau channel yang menangani pesan. Beberapa jalur grup atau balasan kutipan dapat menonaktifkan pratinjau draf untuk suatu giliran saat channel tidak dapat mengedit pesan yang tepat dengan aman.
|
||||
Periksa bahwa `channels.<channel>.streaming.mode` diatur ke `progress` untuk akun atau channel yang menangani pesan. Beberapa jalur grup atau balasan-kutipan dapat menonaktifkan pratinjau draf untuk satu giliran ketika channel tidak dapat mengedit pesan yang benar dengan aman.
|
||||
|
||||
**Saya melihat label tetapi tidak ada baris alat.**
|
||||
|
||||
@ -232,19 +254,19 @@ Periksa `streaming.progress.toolProgress`. Jika nilainya `false`, OpenClaw mempe
|
||||
|
||||
**Saya melihat pesan akhir baru alih-alih draf yang diedit.**
|
||||
|
||||
Itu adalah fallback keselamatan. Ini dapat terjadi untuk balasan media, jawaban panjang, target balasan eksplisit, draf Telegram lama, target thread Slack yang hilang, pesan pratinjau yang dihapus, atau finalisasi stream native yang gagal.
|
||||
Itu adalah fallback keamanan. Ini dapat terjadi untuk balasan media, jawaban panjang, target balasan eksplisit, draf Telegram lama, target thread Slack yang hilang, pesan pratinjau yang dihapus, atau finalisasi stream native yang gagal.
|
||||
|
||||
**Saya masih melihat pesan progres mandiri.**
|
||||
|
||||
Mode progres menekan pesan progres alat mandiri default saat draf aktif. Jika pesan mandiri masih muncul, verifikasi bahwa giliran tersebut benar-benar menggunakan mode progres dan bukan `streaming.mode: "off"` atau jalur channel yang tidak dapat membuat draf untuk pesan tersebut.
|
||||
Mode progres menekan pesan progres-alat mandiri default saat draf aktif. Jika pesan mandiri masih muncul, verifikasi bahwa giliran tersebut benar-benar menggunakan mode progres dan bukan `streaming.mode: "off"` atau jalur channel yang tidak dapat membuat draf untuk pesan tersebut.
|
||||
|
||||
**Teams berperilaku berbeda dari Discord atau Telegram.**
|
||||
|
||||
Microsoft Teams menggunakan stream native dalam chat personal alih-alih transport pratinjau kirim-dan-edit generik. Teams juga memperlakukan `streaming.mode: "block"` sebagai pengiriman blok Teams karena tidak memiliki mode blok pratinjau draf yang sama seperti yang digunakan Discord dan Telegram.
|
||||
Microsoft Teams menggunakan stream native di chat pribadi alih-alih transport pratinjau kirim-dan-edit generik. Teams juga memperlakukan `streaming.mode: "block"` sebagai pengiriman blok Teams karena tidak memiliki mode blok pratinjau-draf yang sama seperti yang digunakan Discord dan Telegram.
|
||||
|
||||
## Terkait
|
||||
|
||||
- [Streaming dan pemotongan](/id/concepts/streaming)
|
||||
- [Streaming dan chunking](/id/concepts/streaming)
|
||||
- [Pesan](/id/concepts/messages)
|
||||
- [Konfigurasi channel](/id/gateway/config-channels)
|
||||
- [Discord](/id/channels/discord)
|
||||
|
||||
@ -1,97 +1,104 @@
|
||||
---
|
||||
read_when:
|
||||
- Menjelaskan bagaimana steer berperilaku saat agen menggunakan alat
|
||||
- Mengubah perilaku antrean proses aktif atau integrasi pengarahan waktu jalan
|
||||
- Menjelaskan cara pengarahan berperilaku saat agen menggunakan alat
|
||||
- Mengubah perilaku antrean proses aktif atau integrasi pengarahan lingkungan eksekusi
|
||||
- Membandingkan mode steer, queue, collect, dan followup
|
||||
summary: Cara pengarahan run aktif mengantrekan pesan di batas runtime
|
||||
title: Antrean arahan
|
||||
summary: Bagaimana pengarahan proses aktif mengantrekan pesan pada batas runtime
|
||||
title: Antrean pengarahan
|
||||
x-i18n:
|
||||
generated_at: "2026-04-30T09:45:51Z"
|
||||
generated_at: "2026-05-04T02:23:41Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 560390c8c26bcce95e0137f4336ad6e62bc3e2344cb15fd12ca3cfe4a85a8acc
|
||||
source_hash: c8df35b127ae0c1e1b3b684a1f63ce33874eb3d0b7bf9d0df7cb9dfce093090a
|
||||
source_path: concepts/queue-steering.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Ketika sebuah pesan tiba saat run sesi sudah melakukan streaming, OpenClaw dapat
|
||||
mengirim pesan itu ke runtime aktif alih-alih memulai run lain untuk sesi yang
|
||||
sama. Mode publik bersifat netral terhadap runtime; Pi dan harness app-server
|
||||
Codex native mengimplementasikan detail pengirimannya secara berbeda.
|
||||
Saat pesan tiba ketika proses sesi sudah melakukan streaming, OpenClaw dapat
|
||||
mengirim pesan itu ke runtime aktif alih-alih memulai proses lain untuk sesi
|
||||
yang sama. Mode publik bersifat netral terhadap runtime; Pi dan harness app-server
|
||||
Codex native menerapkan detail pengirimannya secara berbeda.
|
||||
|
||||
## Batas Runtime
|
||||
## Batas runtime
|
||||
|
||||
Pengarahan tidak menginterupsi pemanggilan alat yang sudah berjalan. Pi memeriksa
|
||||
pesan pengarahan yang mengantre pada batas model:
|
||||
Steering tidak menghentikan panggilan alat yang sudah berjalan. Pi memeriksa
|
||||
pesan steering yang mengantre pada batas model:
|
||||
|
||||
1. Asisten meminta pemanggilan alat.
|
||||
2. Pi mengeksekusi batch pemanggilan alat pesan asisten saat ini.
|
||||
1. Asisten meminta panggilan alat.
|
||||
2. Pi menjalankan batch panggilan alat dari pesan asisten saat ini.
|
||||
3. Pi memancarkan peristiwa akhir giliran.
|
||||
4. Pi menguras pesan pengarahan yang mengantre.
|
||||
4. Pi menguras pesan steering yang mengantre.
|
||||
5. Pi menambahkan pesan tersebut sebagai pesan pengguna sebelum panggilan LLM berikutnya.
|
||||
|
||||
Ini menjaga hasil alat tetap berpasangan dengan pesan asisten yang memintanya,
|
||||
lalu memungkinkan panggilan model berikutnya melihat input pengguna terbaru.
|
||||
lalu memungkinkan panggilan model berikutnya melihat masukan pengguna terbaru.
|
||||
|
||||
Harness app-server Codex native mengekspos `turn/steer`, bukan antrean
|
||||
pengarahan internal Pi. OpenClaw menyesuaikan mode yang sama di sana:
|
||||
Harness app-server Codex native mengekspos `turn/steer` alih-alih antrean
|
||||
steering internal Pi. OpenClaw mengadaptasi mode yang sama di sana:
|
||||
|
||||
- `steer` membatch pesan yang mengantre selama jendela senyap yang dikonfigurasi, lalu mengirim
|
||||
satu permintaan `turn/steer` dengan semua input pengguna yang dikumpulkan dalam urutan kedatangan.
|
||||
- `queue` mempertahankan bentuk berseri legacy dengan mengirim permintaan `turn/steer`
|
||||
terpisah.
|
||||
- `steer` mengelompokkan pesan yang mengantre selama jendela hening yang
|
||||
dikonfigurasi, lalu mengirim satu permintaan `turn/steer` dengan semua masukan
|
||||
pengguna yang terkumpul sesuai urutan kedatangan.
|
||||
- `queue` mempertahankan bentuk serialisasi lama dengan mengirim permintaan
|
||||
`turn/steer` terpisah.
|
||||
- `followup`, `collect`, `steer-backlog`, dan `interrupt` tetap menjadi perilaku
|
||||
antrean milik OpenClaw di sekitar giliran Codex yang aktif.
|
||||
|
||||
Giliran peninjauan Codex dan Compaction manual menolak pengarahan dalam giliran
|
||||
yang sama. Ketika runtime tidak dapat menerima pengarahan, OpenClaw beralih ke antrean followup jika
|
||||
mode tersebut mengizinkannya.
|
||||
Giliran peninjauan Codex dan compaction manual menolak steering dalam giliran
|
||||
yang sama. Ketika runtime tidak dapat menerima steering, OpenClaw kembali ke
|
||||
antrean tindak lanjut jika mode tersebut mengizinkannya.
|
||||
|
||||
Halaman ini menjelaskan steering mode antrean untuk pesan masuk normal. Untuk
|
||||
perintah eksplisit `/steer <message>`, lihat [Steer](/tools/steer).
|
||||
|
||||
## Mode
|
||||
|
||||
| Mode | Perilaku run aktif | Perilaku followup berikutnya |
|
||||
| --------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
|
||||
| `steer` | Menyuntikkan semua pesan pengarahan yang mengantre bersama-sama pada batas runtime berikutnya. Ini adalah default. | Beralih ke followup hanya ketika pengarahan tidak tersedia. |
|
||||
| `queue` | Pengarahan legacy satu per satu. Pi menyuntikkan satu pesan yang mengantre per batas model; Codex mengirim permintaan `turn/steer` terpisah. | Beralih ke followup hanya ketika pengarahan tidak tersedia. |
|
||||
| `steer-backlog` | Perilaku pengarahan run aktif yang sama seperti `steer`. | Juga mempertahankan pesan yang sama untuk giliran followup nanti. |
|
||||
| `followup` | Tidak mengarahkan run saat ini. | Menjalankan pesan yang mengantre nanti. |
|
||||
| `collect` | Tidak mengarahkan run saat ini. | Menggabungkan pesan yang mengantre dan kompatibel menjadi satu giliran nanti setelah jendela debounce. |
|
||||
| `interrupt` | Membatalkan run aktif, lalu memulai pesan terbaru. | Tidak ada. |
|
||||
| Mode | Perilaku proses aktif | Perilaku tindak lanjut berikutnya |
|
||||
| --------------- | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
|
||||
| `steer` | Menyisipkan semua pesan steering yang mengantre secara bersama-sama pada batas runtime berikutnya. Ini adalah default. | Kembali ke tindak lanjut hanya ketika steering tidak tersedia. |
|
||||
| `queue` | Steering lama satu per satu. Pi menyisipkan satu pesan antrean per batas model; Codex mengirim permintaan `turn/steer` terpisah. | Kembali ke tindak lanjut hanya ketika steering tidak tersedia. |
|
||||
| `steer-backlog` | Perilaku steering proses aktif yang sama seperti `steer`. | Juga mempertahankan pesan yang sama untuk giliran tindak lanjut berikutnya. |
|
||||
| `followup` | Tidak melakukan steering pada proses saat ini. | Menjalankan pesan yang mengantre nanti. |
|
||||
| `collect` | Tidak melakukan steering pada proses saat ini. | Menggabungkan pesan antrean yang kompatibel ke satu giliran berikutnya setelah jendela debounce. |
|
||||
| `interrupt` | Membatalkan proses aktif, lalu memulai pesan terbaru. | Tidak ada. |
|
||||
|
||||
## Contoh Lonjakan
|
||||
## Contoh lonjakan
|
||||
|
||||
Jika empat pengguna mengirim pesan saat agen sedang mengeksekusi pemanggilan alat:
|
||||
Jika empat pengguna mengirim pesan saat agen sedang menjalankan panggilan alat:
|
||||
|
||||
- `steer`: runtime aktif menerima keempat pesan dalam urutan kedatangan sebelum
|
||||
- `steer`: runtime aktif menerima keempat pesan sesuai urutan kedatangan sebelum
|
||||
keputusan model berikutnya. Pi mengurasnya pada batas model berikutnya; Codex
|
||||
menerimanya sebagai satu `turn/steer` yang dibatch.
|
||||
- `queue`: pengarahan berseri legacy. Pi menyuntikkan satu pesan yang mengantre pada satu waktu;
|
||||
Codex menerima permintaan `turn/steer` terpisah.
|
||||
- `collect`: OpenClaw menunggu hingga run aktif berakhir, lalu membuat giliran followup
|
||||
dengan pesan yang mengantre dan kompatibel setelah jendela debounce.
|
||||
- `queue`: steering serialisasi lama. Pi menyisipkan satu pesan antrean dalam
|
||||
satu waktu; Codex menerima permintaan `turn/steer` terpisah.
|
||||
- `collect`: OpenClaw menunggu sampai proses aktif berakhir, lalu membuat giliran
|
||||
tindak lanjut dengan pesan antrean yang kompatibel setelah jendela debounce.
|
||||
|
||||
## Cakupan
|
||||
|
||||
Pengarahan selalu menargetkan run sesi aktif saat ini. Itu tidak membuat sesi
|
||||
baru, mengubah kebijakan alat run aktif, atau memisahkan pesan berdasarkan pengirim. Di
|
||||
kanal multi-pengguna, prompt masuk sudah menyertakan konteks pengirim dan rute, sehingga
|
||||
panggilan model berikutnya dapat melihat siapa yang mengirim setiap pesan.
|
||||
Steering selalu menargetkan proses sesi aktif saat ini. Ini tidak membuat sesi
|
||||
baru, mengubah kebijakan alat proses aktif, atau memisahkan pesan berdasarkan
|
||||
pengirim. Di kanal multipengguna, prompt masuk sudah menyertakan konteks
|
||||
pengirim dan rute, sehingga panggilan model berikutnya dapat melihat siapa yang
|
||||
mengirim setiap pesan.
|
||||
|
||||
Gunakan `collect` ketika Anda ingin OpenClaw membangun giliran followup nanti yang dapat
|
||||
menggabungkan pesan yang kompatibel dan mempertahankan kebijakan penghapusan antrean followup. Gunakan
|
||||
`queue` hanya ketika Anda memerlukan perilaku pengarahan lama satu per satu.
|
||||
Gunakan `collect` saat Anda ingin OpenClaw membuat giliran tindak lanjut nanti
|
||||
yang dapat menggabungkan pesan yang kompatibel dan mempertahankan kebijakan
|
||||
penghapusan antrean tindak lanjut. Gunakan `queue` hanya saat Anda memerlukan
|
||||
perilaku steering lama satu per satu.
|
||||
|
||||
## Debounce
|
||||
|
||||
`messages.queue.debounceMs` berlaku untuk pengiriman followup, termasuk `collect`,
|
||||
`followup`, `steer-backlog`, dan fallback `steer` ketika pengarahan run aktif tidak
|
||||
tersedia. Untuk Pi, `steer` aktif itu sendiri tidak menggunakan timer debounce karena
|
||||
Pi secara alami membatch pesan hingga batas model berikutnya. Untuk harness
|
||||
Codex native, OpenClaw menggunakan nilai debounce yang sama sebagai jendela senyap sebelum
|
||||
mengirim `turn/steer` yang dibatch.
|
||||
`messages.queue.debounceMs` berlaku untuk pengiriman tindak lanjut, termasuk
|
||||
`collect`, `followup`, `steer-backlog`, dan fallback `steer` ketika steering
|
||||
proses aktif tidak tersedia. Untuk Pi, `steer` aktif itu sendiri tidak menggunakan
|
||||
timer debounce karena Pi secara alami membatch pesan sampai batas model
|
||||
berikutnya. Untuk harness Codex native, OpenClaw menggunakan nilai debounce yang
|
||||
sama sebagai jendela hening sebelum mengirim `turn/steer` yang dibatch.
|
||||
|
||||
## Terkait
|
||||
|
||||
- [Antrean perintah](/id/concepts/queue)
|
||||
- [Steer](/tools/steer)
|
||||
- [Pesan](/id/concepts/messages)
|
||||
- [Loop agen](/id/concepts/agent-loop)
|
||||
|
||||
@ -2,35 +2,35 @@
|
||||
read_when:
|
||||
- Mengubah eksekusi atau konkurensi balasan otomatis
|
||||
- Menjelaskan mode /queue atau perilaku pengarahan pesan
|
||||
summary: Mode antrean balasan otomatis, nilai bawaan, dan penggantian per sesi
|
||||
summary: Mode antrean balasan otomatis, default, dan penggantian per sesi
|
||||
title: Antrean perintah
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T09:18:25Z"
|
||||
generated_at: "2026-05-04T02:23:26Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: c59ea6802d8bf526f4005db3b1baa87d96a23d561c916f91520e8e641fbaf74f
|
||||
source_hash: 085aebe7059020f027eb08bb382cce2d253ea117eed0ca77d6ffd208f295acb1
|
||||
source_path: concepts/queue.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Kami menserialisasi eksekusi balasan otomatis masuk (semua kanal) melalui antrean kecil dalam proses untuk mencegah beberapa eksekusi agen bertabrakan, sambil tetap mengizinkan paralelisme yang aman lintas sesi.
|
||||
Kami menserialkan run balasan otomatis masuk (semua saluran) melalui antrean kecil dalam proses untuk mencegah beberapa run agen saling bertabrakan, sambil tetap memungkinkan paralelisme yang aman di seluruh sesi.
|
||||
|
||||
## Mengapa
|
||||
|
||||
- Eksekusi balasan otomatis bisa mahal (panggilan LLM) dan dapat bertabrakan saat beberapa pesan masuk tiba berdekatan.
|
||||
- Serialisasi menghindari perebutan sumber daya bersama (file sesi, log, stdin CLI) dan mengurangi kemungkinan batas laju upstream.
|
||||
- Run balasan otomatis dapat memakan biaya besar (panggilan LLM) dan dapat bertabrakan ketika beberapa pesan masuk tiba berdekatan.
|
||||
- Serialisasi menghindari perebutan sumber daya bersama (file sesi, log, stdin CLI) dan mengurangi kemungkinan terkena batas laju upstream.
|
||||
|
||||
## Cara kerjanya
|
||||
|
||||
- Antrean FIFO yang sadar jalur menguras setiap jalur dengan batas konkurensi yang dapat dikonfigurasi (default 1 untuk jalur yang tidak dikonfigurasi; main default ke 4, subagent ke 8).
|
||||
- `runEmbeddedPiAgent` mengantrekan berdasarkan **kunci sesi** (jalur `session:<key>`) untuk menjamin hanya ada satu eksekusi aktif per sesi.
|
||||
- Setiap eksekusi sesi lalu diantrekan ke **jalur global** (`main` secara default) sehingga paralelisme keseluruhan dibatasi oleh `agents.defaults.maxConcurrent`.
|
||||
- Saat pencatatan log verbose diaktifkan, eksekusi yang mengantre memancarkan pemberitahuan singkat jika menunggu lebih dari ~2 dtk sebelum dimulai.
|
||||
- Indikator mengetik tetap langsung menyala saat masuk antrean (jika didukung oleh kanal) sehingga pengalaman pengguna tidak berubah saat menunggu giliran.
|
||||
- Antrean FIFO sadar-lane menguras setiap lane dengan batas konkurensi yang dapat dikonfigurasi (default 1 untuk lane yang tidak dikonfigurasi; main default ke 4, subagen ke 8).
|
||||
- `runEmbeddedPiAgent` mengantre berdasarkan **kunci sesi** (lane `session:<key>`) untuk menjamin hanya ada satu run aktif per sesi.
|
||||
- Setiap run sesi kemudian diantrekan ke **lane global** (`main` secara default) sehingga paralelisme keseluruhan dibatasi oleh `agents.defaults.maxConcurrent`.
|
||||
- Ketika logging verbose diaktifkan, run yang mengantre memancarkan pemberitahuan singkat jika menunggu lebih dari ~2 dtk sebelum dimulai.
|
||||
- Indikator mengetik tetap langsung aktif saat masuk antrean (jika didukung oleh saluran) sehingga pengalaman pengguna tidak berubah saat menunggu giliran.
|
||||
|
||||
## Nilai bawaan
|
||||
## Default
|
||||
|
||||
Saat tidak disetel, semua permukaan kanal masuk menggunakan:
|
||||
Jika belum diatur, semua permukaan saluran masuk menggunakan:
|
||||
|
||||
- `mode: "steer"`
|
||||
- `debounceMs: 500`
|
||||
@ -38,29 +38,30 @@ Saat tidak disetel, semua permukaan kanal masuk menggunakan:
|
||||
- `drop: "summarize"`
|
||||
|
||||
`steer` adalah default karena menjaga giliran model aktif tetap responsif tanpa
|
||||
memulai eksekusi sesi kedua. Mode ini menguras semua pesan pengarahan yang tiba
|
||||
sebelum batas model berikutnya. Jika eksekusi saat ini tidak dapat menerima pengarahan,
|
||||
memulai run sesi kedua. Mode ini menguras semua pesan pengarah yang tiba
|
||||
sebelum batas model berikutnya. Jika run saat ini tidak dapat menerima pengarahan,
|
||||
OpenClaw kembali ke entri antrean tindak lanjut.
|
||||
|
||||
## Mode antrean
|
||||
|
||||
Pesan masuk dapat mengarahkan eksekusi saat ini, menunggu giliran tindak lanjut, atau melakukan keduanya:
|
||||
Pesan masuk dapat mengarahkan run saat ini, menunggu giliran tindak lanjut, atau melakukan keduanya:
|
||||
|
||||
- `steer`: antrekan pesan pengarahan ke runtime aktif. Pi mengirim semua pesan pengarahan tertunda **setelah giliran asisten saat ini selesai mengeksekusi panggilan alatnya**, sebelum panggilan LLM berikutnya; app-server Codex menerima satu `turn/steer` yang dibundel. Jika eksekusi tidak sedang streaming aktif atau pengarahan tidak tersedia, OpenClaw kembali ke entri antrean tindak lanjut.
|
||||
- `queue` (legacy): pengarahan lama satu per satu. Pi mengirim satu pesan pengarahan yang diantrekan pada setiap batas model; app-server Codex menerima permintaan `turn/steer` terpisah. Pilih `steer` kecuali Anda membutuhkan perilaku terserialisasi sebelumnya.
|
||||
- `followup`: antrekan setiap pesan untuk giliran agen berikutnya setelah eksekusi saat ini berakhir.
|
||||
- `collect`: gabungkan pesan yang diantrekan menjadi **satu** giliran tindak lanjut setelah jendela tenang. Jika pesan menargetkan kanal/thread yang berbeda, pesan dikuras secara individual untuk mempertahankan perutean.
|
||||
- `steer`: mengantrekan pesan pengarah ke runtime aktif. Pi mengirim semua pesan pengarah tertunda **setelah giliran asisten saat ini selesai mengeksekusi panggilan tool**, sebelum panggilan LLM berikutnya; app-server Codex menerima satu `turn/steer` yang dibundel. Jika run tidak sedang aktif streaming atau pengarahan tidak tersedia, OpenClaw kembali ke entri antrean tindak lanjut.
|
||||
- `queue` (legacy): pengarahan lama satu per satu. Pi mengirim satu pesan pengarah yang diantrekan pada setiap batas model; app-server Codex menerima permintaan `turn/steer` terpisah. Utamakan `steer` kecuali Anda membutuhkan perilaku terserialisasi sebelumnya.
|
||||
- `followup`: mengantrekan setiap pesan untuk giliran agen nanti setelah run saat ini berakhir.
|
||||
- `collect`: menggabungkan pesan yang diantrekan menjadi **satu** giliran tindak lanjut setelah jendela hening. Jika pesan menargetkan saluran/thread berbeda, pesan dikuras secara terpisah untuk mempertahankan perutean.
|
||||
- `steer-backlog` (alias `steer+backlog`): arahkan sekarang **dan** pertahankan pesan yang sama untuk giliran tindak lanjut.
|
||||
- `interrupt` (legacy): batalkan eksekusi aktif untuk sesi tersebut, lalu jalankan pesan terbaru.
|
||||
- `interrupt` (legacy): membatalkan run aktif untuk sesi tersebut, lalu menjalankan pesan terbaru.
|
||||
|
||||
Steer-backlog berarti Anda bisa mendapatkan respons tindak lanjut setelah eksekusi yang diarahkan, sehingga
|
||||
permukaan streaming dapat terlihat seperti duplikat. Pilih `collect`/`steer` jika Anda menginginkan
|
||||
Steer-backlog berarti Anda bisa mendapatkan respons tindak lanjut setelah run yang diarahkan, sehingga
|
||||
permukaan streaming dapat terlihat seperti duplikat. Utamakan `collect`/`steer` jika Anda menginginkan
|
||||
satu respons per pesan masuk.
|
||||
|
||||
Untuk pengaturan waktu khusus runtime dan perilaku dependensi, lihat
|
||||
[Antrean pengarahan](/id/concepts/queue-steering).
|
||||
Untuk timing dan perilaku dependensi khusus runtime, lihat
|
||||
[Antrean pengarahan](/id/concepts/queue-steering). Untuk perintah eksplisit `/steer <message>`,
|
||||
lihat [Arahkan](/tools/steer).
|
||||
|
||||
Konfigurasikan secara global atau per kanal melalui `messages.queue`:
|
||||
Konfigurasikan secara global atau per saluran melalui `messages.queue`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -78,53 +79,55 @@ Konfigurasikan secara global atau per kanal melalui `messages.queue`:
|
||||
|
||||
## Opsi antrean
|
||||
|
||||
Opsi berlaku untuk `followup`, `collect`, dan `steer-backlog` (serta untuk `steer` atau `queue` legacy saat pengarahan kembali ke tindak lanjut):
|
||||
Opsi berlaku untuk `followup`, `collect`, dan `steer-backlog` (serta untuk `steer` atau `queue` legacy ketika pengarahan kembali ke tindak lanjut):
|
||||
|
||||
- `debounceMs`: jendela tenang sebelum menguras tindak lanjut yang diantrekan. Angka polos adalah milidetik; unit `ms`, `s`, `m`, `h`, dan `d` diterima oleh opsi `/queue`.
|
||||
- `cap`: pesan maksimum yang diantrekan per sesi. Nilai di bawah `1` diabaikan.
|
||||
- `debounceMs`: jendela hening sebelum menguras tindak lanjut yang diantrekan. Angka polos adalah milidetik; unit `ms`, `s`, `m`, `h`, dan `d` diterima oleh opsi `/queue`.
|
||||
- `cap`: maksimum pesan yang diantrekan per sesi. Nilai di bawah `1` diabaikan.
|
||||
- `drop: "summarize"`: default. Hapus entri antrean tertua sesuai kebutuhan, simpan ringkasan ringkas, dan sisipkan sebagai prompt tindak lanjut sintetis.
|
||||
- `drop: "old"`: hapus entri antrean tertua sesuai kebutuhan, tanpa mempertahankan ringkasan.
|
||||
- `drop: "new"`: tolak pesan terbaru saat antrean sudah penuh.
|
||||
- `drop: "new"`: tolak pesan terbaru ketika antrean sudah penuh.
|
||||
|
||||
Default: `debounceMs: 500`, `cap: 20`, `drop: summarize`.
|
||||
|
||||
## Prioritas
|
||||
## Presedensi
|
||||
|
||||
Untuk pemilihan mode, OpenClaw menyelesaikan:
|
||||
|
||||
1. Penimpaan `/queue` inline atau tersimpan per sesi.
|
||||
1. Override `/queue` per sesi yang inline atau tersimpan.
|
||||
2. `messages.queue.byChannel.<channel>`.
|
||||
3. `messages.queue.mode`.
|
||||
4. Default `steer`.
|
||||
|
||||
Untuk opsi, opsi `/queue` inline atau tersimpan menang atas konfigurasi. Lalu
|
||||
debounce khusus kanal (`messages.queue.debounceMsByChannel`), default debounce plugin,
|
||||
opsi global `messages.queue`, dan default bawaan diterapkan.
|
||||
`cap` dan `drop` adalah opsi global/sesi, bukan kunci konfigurasi per kanal.
|
||||
Untuk opsi, opsi `/queue` inline atau tersimpan mengalahkan konfigurasi. Kemudian
|
||||
debounce khusus saluran (`messages.queue.debounceMsByChannel`), default debounce
|
||||
Plugin, opsi `messages.queue` global, dan default bawaan
|
||||
diterapkan. `cap` dan `drop` adalah opsi global/sesi, bukan kunci konfigurasi
|
||||
per saluran.
|
||||
|
||||
## Penimpaan per sesi
|
||||
## Override per sesi
|
||||
|
||||
- Kirim `/queue <mode>` sebagai perintah mandiri untuk menyimpan mode bagi sesi saat ini.
|
||||
- Opsi dapat digabungkan: `/queue collect debounce:0.5s cap:25 drop:summarize`
|
||||
- `/queue default` atau `/queue reset` menghapus penimpaan sesi.
|
||||
- `/queue default` atau `/queue reset` menghapus override sesi.
|
||||
|
||||
## Cakupan dan jaminan
|
||||
|
||||
- Berlaku untuk eksekusi agen balasan otomatis di semua kanal masuk yang menggunakan pipeline balasan gateway (web WhatsApp, Telegram, Slack, Discord, Signal, iMessage, webchat, dll.).
|
||||
- Jalur default (`main`) berlaku di seluruh proses untuk masuk + heartbeat utama; setel `agents.defaults.maxConcurrent` untuk mengizinkan beberapa sesi berjalan paralel.
|
||||
- Jalur tambahan mungkin ada (mis. `cron`, `cron-nested`, `nested`, `subagent`) sehingga pekerjaan latar belakang dapat berjalan paralel tanpa memblokir balasan masuk. Giliran agen cron terisolasi menahan slot `cron` sementara eksekusi agen bagian dalamnya menggunakan `cron-nested`; keduanya menggunakan `cron.maxConcurrentRuns`. Alur `nested` non-cron bersama mempertahankan perilaku jalurnya sendiri. Eksekusi terlepas ini dilacak sebagai [tugas latar belakang](/id/automation/tasks).
|
||||
- Jalur per sesi menjamin bahwa hanya satu eksekusi agen menyentuh sesi tertentu pada satu waktu.
|
||||
- Tanpa dependensi eksternal atau thread pekerja latar belakang; TypeScript + promise murni.
|
||||
- Berlaku untuk run agen balasan otomatis di semua saluran masuk yang menggunakan pipeline balasan Gateway (web WhatsApp, Telegram, Slack, Discord, Signal, iMessage, webchat, dll.).
|
||||
- Lane default (`main`) berlaku di seluruh proses untuk Heartbeat masuk + utama; atur `agents.defaults.maxConcurrent` untuk mengizinkan beberapa sesi berjalan paralel.
|
||||
- Lane tambahan mungkin ada (mis. `cron`, `cron-nested`, `nested`, `subagent`) sehingga pekerjaan latar belakang dapat berjalan paralel tanpa memblokir balasan masuk. Giliran agen cron terisolasi menahan slot `cron` sementara eksekusi agen dalamnya menggunakan `cron-nested`; keduanya menggunakan `cron.maxConcurrentRuns`. Alur `nested` non-cron bersama mempertahankan perilaku lane masing-masing. Run terlepas ini dilacak sebagai [tugas latar belakang](/id/automation/tasks).
|
||||
- Lane per sesi menjamin hanya satu run agen menyentuh sesi tertentu pada satu waktu.
|
||||
- Tidak ada dependensi eksternal atau thread worker latar belakang; TypeScript murni + promise.
|
||||
|
||||
## Pemecahan masalah
|
||||
|
||||
- Jika perintah tampak macet, aktifkan log verbose dan cari baris “queued for …ms” untuk memastikan antrean sedang dikuras.
|
||||
- Jika Anda membutuhkan kedalaman antrean, aktifkan log verbose dan perhatikan baris waktu antrean.
|
||||
- Eksekusi app-server Codex yang menerima giliran lalu berhenti memancarkan progres diinterupsi oleh adaptor Codex sehingga jalur sesi aktif dapat dilepaskan alih-alih menunggu timeout eksekusi luar.
|
||||
- Saat diagnostik diaktifkan, sesi yang tetap berada di `processing` melewati `diagnostics.stuckSessionWarnMs` tanpa balasan, alat, status, blok, atau progres ACP yang teramati diklasifikasikan berdasarkan aktivitas saat ini. Pekerjaan aktif dicatat sebagai `session.long_running`; pekerjaan aktif tanpa progres terbaru dicatat sebagai `session.stalled`; `session.stuck` disediakan untuk pembukuan sesi basi tanpa pekerjaan aktif, dan hanya jalur itu yang dapat melepaskan jalur sesi yang terdampak agar pekerjaan yang diantrekan terkuras. Diagnostik `session.stuck` berulang melakukan backoff selama sesi tetap tidak berubah.
|
||||
- Jika perintah tampak macet, aktifkan log verbose dan cari baris “queued for …ms” untuk mengonfirmasi antrean sedang dikuras.
|
||||
- Jika Anda membutuhkan kedalaman antrean, aktifkan log verbose dan amati baris timing antrean.
|
||||
- Run app-server Codex yang menerima giliran lalu berhenti memancarkan progres diinterupsi oleh adapter Codex sehingga lane sesi aktif dapat dilepas alih-alih menunggu timeout run luar.
|
||||
- Ketika diagnostik diaktifkan, sesi yang tetap berada dalam `processing` melewati `diagnostics.stuckSessionWarnMs` tanpa balasan, tool, status, blok, atau progres ACP yang teramati diklasifikasikan berdasarkan aktivitas saat ini. Pekerjaan aktif dicatat sebagai `session.long_running`; pekerjaan aktif tanpa progres terbaru dicatat sebagai `session.stalled`; `session.stuck` dicadangkan untuk pembukuan sesi usang tanpa pekerjaan aktif, dan hanya jalur tersebut yang dapat melepas lane sesi terdampak agar pekerjaan yang diantrekan terkuras. Diagnostik `session.stuck` berulang akan mundur sementara sesi tetap tidak berubah.
|
||||
|
||||
## Terkait
|
||||
|
||||
- [Manajemen sesi](/id/concepts/session)
|
||||
- [Antrean pengarahan](/id/concepts/queue-steering)
|
||||
- [Kebijakan percobaan ulang](/id/concepts/retry)
|
||||
- [Arahkan](/tools/steer)
|
||||
- [Kebijakan coba ulang](/id/concepts/retry)
|
||||
|
||||
@ -1,24 +1,24 @@
|
||||
---
|
||||
read_when:
|
||||
- Mengedit teks prompt sistem, daftar alat, atau bagian waktu/Heartbeat
|
||||
- Mengubah perilaku inisialisasi awal ruang kerja atau injeksi Skills
|
||||
summary: Apa isi prompt sistem OpenClaw dan bagaimana prompt itu disusun
|
||||
- Mengubah perilaku bootstrap ruang kerja atau injeksi Skills
|
||||
summary: Apa isi prompt sistem OpenClaw dan bagaimana prompt tersebut disusun
|
||||
title: Prompt sistem
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:30:55Z"
|
||||
generated_at: "2026-05-04T02:23:29Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 93533ac8090897a7b5fd82b80e542a4ad573670408314b3519c5e317d0408ade
|
||||
source_hash: 5e6067e760eccf58106f0a646c2656e902d5951580abd750f342d70b0568b81b
|
||||
source_path: concepts/system-prompt.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw membangun prompt sistem kustom untuk setiap eksekusi agen. Prompt tersebut **dimiliki OpenClaw** dan tidak menggunakan prompt default pi-coding-agent.
|
||||
OpenClaw membuat prompt sistem kustom untuk setiap eksekusi agen. Prompt tersebut **dimiliki OpenClaw** dan tidak menggunakan prompt default pi-coding-agent.
|
||||
|
||||
Prompt disusun oleh OpenClaw dan disuntikkan ke setiap eksekusi agen.
|
||||
Prompt dirakit oleh OpenClaw dan disuntikkan ke setiap eksekusi agen.
|
||||
|
||||
Plugin penyedia dapat menyumbangkan panduan prompt yang sadar cache tanpa menggantikan
|
||||
prompt penuh yang dimiliki OpenClaw. Runtime penyedia dapat:
|
||||
Plugin penyedia dapat menyumbangkan panduan prompt yang sadar-cache tanpa mengganti
|
||||
prompt lengkap milik OpenClaw. Runtime penyedia dapat:
|
||||
|
||||
- mengganti sekumpulan kecil bagian inti bernama (`interaction_style`,
|
||||
`tool_call_style`, `execution_bias`)
|
||||
@ -30,53 +30,53 @@ Gunakan kontribusi milik penyedia untuk penyetelan khusus keluarga model. Pertah
|
||||
bukan perilaku penyedia normal.
|
||||
|
||||
Overlay keluarga OpenAI GPT-5 menjaga aturan eksekusi inti tetap kecil dan menambahkan
|
||||
panduan khusus model untuk penguncian persona, keluaran ringkas, disiplin alat,
|
||||
pencarian paralel, cakupan deliverable, verifikasi, konteks yang kurang, dan
|
||||
kebersihan alat terminal.
|
||||
panduan khusus model untuk penguncian persona, keluaran ringkas, disiplin tool,
|
||||
pencarian paralel, cakupan deliverable, verifikasi, konteks yang hilang, dan
|
||||
kebersihan tool terminal.
|
||||
|
||||
## Struktur
|
||||
|
||||
Prompt sengaja dibuat ringkas dan menggunakan bagian tetap:
|
||||
|
||||
- **Tooling**: pengingat sumber kebenaran alat terstruktur plus panduan penggunaan alat runtime.
|
||||
- **Execution Bias**: panduan tindak lanjut ringkas: bertindak dalam giliran pada
|
||||
permintaan yang dapat ditindaklanjuti, lanjutkan hingga selesai atau terblokir, pulih dari hasil alat yang lemah,
|
||||
periksa status yang dapat berubah secara live, dan verifikasi sebelum memfinalkan.
|
||||
- **Safety**: pengingat guardrail singkat untuk menghindari perilaku mencari kekuasaan atau melewati pengawasan.
|
||||
- **Skills** (jika tersedia): memberi tahu model cara memuat instruksi skill sesuai kebutuhan.
|
||||
- **OpenClaw Self-Update**: cara memeriksa config dengan aman menggunakan
|
||||
`config.schema.lookup`, mem-patch config dengan `config.patch`, mengganti config penuh
|
||||
dengan `config.apply`, dan menjalankan `update.run` hanya atas permintaan pengguna
|
||||
eksplisit. Alat khusus pemilik `gateway` juga menolak menulis ulang
|
||||
- **Tooling**: pengingat sumber kebenaran tool terstruktur plus panduan penggunaan tool runtime.
|
||||
- **Bias Eksekusi**: panduan tindak lanjut ringkas: bertindak dalam giliran pada
|
||||
permintaan yang dapat ditindaklanjuti, lanjut sampai selesai atau terblokir, pulih dari hasil tool
|
||||
yang lemah, periksa status yang dapat berubah secara langsung, dan verifikasi sebelum finalisasi.
|
||||
- **Keamanan**: pengingat guardrail singkat untuk menghindari perilaku mencari kekuasaan atau melewati pengawasan.
|
||||
- **Skills** (bila tersedia): memberi tahu model cara memuat instruksi skill sesuai kebutuhan.
|
||||
- **Pembaruan Mandiri OpenClaw**: cara memeriksa konfigurasi dengan aman menggunakan
|
||||
`config.schema.lookup`, menambal konfigurasi dengan `config.patch`, mengganti konfigurasi lengkap
|
||||
dengan `config.apply`, dan menjalankan `update.run` hanya atas permintaan eksplisit pengguna.
|
||||
Tool khusus pemilik `gateway` juga menolak menulis ulang
|
||||
`tools.exec.ask` / `tools.exec.security`, termasuk alias lama `tools.bash.*`
|
||||
yang dinormalisasi ke path exec terlindungi tersebut.
|
||||
- **Workspace**: direktori kerja (`agents.defaults.workspace`).
|
||||
- **Documentation**: path lokal ke dokumentasi OpenClaw (repo atau paket npm) dan kapan harus membacanya.
|
||||
- **Workspace Files (injected)**: menunjukkan file bootstrap disertakan di bawah.
|
||||
- **Sandbox** (jika diaktifkan): menunjukkan runtime tersandbox, path sandbox, dan apakah exec terelevasi tersedia.
|
||||
- **Current Date & Time**: waktu lokal pengguna, zona waktu, dan format waktu.
|
||||
- **Reply Tags**: sintaks tag balasan opsional untuk penyedia yang didukung.
|
||||
- **Heartbeats**: prompt heartbeat dan perilaku ack, saat heartbeat diaktifkan untuk agen default.
|
||||
- **Runtime**: host, OS, node, model, root repo (jika terdeteksi), level thinking (satu baris).
|
||||
- **Reasoning**: level visibilitas saat ini + petunjuk toggle /reasoning.
|
||||
yang dinormalisasi ke jalur exec yang dilindungi tersebut.
|
||||
- **Ruang Kerja**: direktori kerja (`agents.defaults.workspace`).
|
||||
- **Dokumentasi**: jalur lokal ke dokumentasi OpenClaw (repo atau paket npm) dan kapan membacanya.
|
||||
- **File Ruang Kerja (disuntikkan)**: menunjukkan file bootstrap disertakan di bawah.
|
||||
- **Sandbox** (bila diaktifkan): menunjukkan runtime tersandbox, jalur sandbox, dan apakah exec yang ditinggikan tersedia.
|
||||
- **Tanggal & Waktu Saat Ini**: waktu lokal pengguna, zona waktu, dan format waktu.
|
||||
- **Tag Balasan**: sintaks tag balasan opsional untuk penyedia yang didukung.
|
||||
- **Heartbeat**: prompt heartbeat dan perilaku ack, saat heartbeat diaktifkan untuk agen default.
|
||||
- **Runtime**: host, OS, node, model, root repo (bila terdeteksi), tingkat berpikir (satu baris).
|
||||
- **Penalaran**: tingkat visibilitas saat ini + petunjuk toggle /reasoning.
|
||||
|
||||
OpenClaw menjaga konten stabil besar, termasuk **Project Context**, di atas
|
||||
batas cache prompt internal. Bagian channel/sesi volatil seperti
|
||||
panduan embed Control UI, **Messaging**, **Voice**, **Group Chat Context**,
|
||||
**Reactions**, **Heartbeats**, dan **Runtime** ditambahkan di bawah batas tersebut
|
||||
sehingga backend lokal dengan cache prefiks dapat memakai ulang prefiks workspace yang stabil
|
||||
di seluruh giliran channel. Deskripsi alat juga sebaiknya menghindari penyematan nama
|
||||
channel saat ini ketika skema yang diterima sudah membawa detail runtime tersebut.
|
||||
OpenClaw menjaga konten stabil besar, termasuk **Konteks Proyek**, di atas
|
||||
batas cache prompt internal. Bagian kanal/sesi yang volatil seperti
|
||||
panduan embed UI Kontrol, **Pesan**, **Suara**, **Konteks Chat Grup**,
|
||||
**Reaksi**, **Heartbeat**, dan **Runtime** ditambahkan di bawah batas itu
|
||||
sehingga backend lokal dengan cache prefiks dapat menggunakan ulang prefiks ruang kerja stabil
|
||||
di seluruh giliran kanal. Deskripsi tool juga sebaiknya menghindari penyematan nama
|
||||
kanal saat ini ketika skema yang diterima sudah membawa detail runtime tersebut.
|
||||
|
||||
Bagian Tooling juga mencakup panduan runtime untuk pekerjaan berjalan lama:
|
||||
Bagian Tooling juga menyertakan panduan runtime untuk pekerjaan berdurasi panjang:
|
||||
|
||||
- gunakan cron untuk tindak lanjut di masa depan (`check back later`, pengingat, pekerjaan berulang)
|
||||
alih-alih loop tidur `exec`, trik jeda `yieldMs`, atau polling `process`
|
||||
- gunakan cron untuk tindak lanjut mendatang (`check back later`, pengingat, pekerjaan berulang)
|
||||
alih-alih loop sleep `exec`, trik penundaan `yieldMs`, atau polling `process`
|
||||
berulang
|
||||
- gunakan `exec` / `process` hanya untuk perintah yang dimulai sekarang dan terus berjalan
|
||||
- gunakan `exec` / `process` hanya untuk perintah yang mulai sekarang dan terus berjalan
|
||||
di latar belakang
|
||||
- saat wake penyelesaian otomatis diaktifkan, mulai perintah sekali dan andalkan
|
||||
jalur wake berbasis push ketika menghasilkan output atau gagal
|
||||
- ketika bangun penyelesaian otomatis diaktifkan, mulai perintah sekali dan andalkan
|
||||
jalur bangun berbasis push saat perintah mengeluarkan output atau gagal
|
||||
- gunakan `process` untuk log, status, input, atau intervensi saat Anda perlu
|
||||
memeriksa perintah yang sedang berjalan
|
||||
- jika tugas lebih besar, pilih `sessions_spawn`; penyelesaian sub-agen
|
||||
@ -84,73 +84,72 @@ Bagian Tooling juga mencakup panduan runtime untuk pekerjaan berjalan lama:
|
||||
- jangan melakukan polling `subagents list` / `sessions_list` dalam loop hanya untuk menunggu
|
||||
penyelesaian
|
||||
|
||||
Saat alat eksperimental `update_plan` diaktifkan, Tooling juga memberi tahu
|
||||
model untuk menggunakannya hanya untuk pekerjaan multi-langkah non-sepele, menjaga tepat satu
|
||||
Saat tool eksperimental `update_plan` diaktifkan, Tooling juga memberi tahu
|
||||
model untuk menggunakannya hanya untuk pekerjaan multi-langkah yang tidak sepele, menjaga tepat satu
|
||||
langkah `in_progress`, dan menghindari pengulangan seluruh rencana setelah setiap pembaruan.
|
||||
|
||||
Guardrail keselamatan dalam prompt sistem bersifat anjuran. Guardrail memandu perilaku model tetapi tidak menegakkan kebijakan. Gunakan kebijakan alat, persetujuan exec, sandboxing, dan allowlist channel untuk penegakan keras; operator dapat menonaktifkan ini sesuai desain.
|
||||
Guardrail keamanan dalam prompt sistem bersifat nasihat. Guardrail tersebut memandu perilaku model tetapi tidak menegakkan kebijakan. Gunakan kebijakan tool, persetujuan exec, sandboxing, dan allowlist kanal untuk penegakan keras; operator dapat menonaktifkannya sesuai desain.
|
||||
|
||||
Pada channel dengan kartu/tombol persetujuan native, prompt runtime sekarang memberi tahu
|
||||
agen untuk mengandalkan UI persetujuan native tersebut terlebih dahulu. Agen hanya boleh menyertakan perintah
|
||||
`/approve` manual ketika hasil alat mengatakan persetujuan chat tidak tersedia atau
|
||||
Pada kanal dengan kartu/tombol persetujuan native, prompt runtime kini memberi tahu
|
||||
agen untuk mengandalkan UI persetujuan native tersebut terlebih dahulu. Agen hanya boleh menyertakan perintah manual
|
||||
`/approve` ketika hasil tool mengatakan persetujuan chat tidak tersedia atau
|
||||
persetujuan manual adalah satu-satunya jalur.
|
||||
|
||||
## Mode prompt
|
||||
|
||||
OpenClaw dapat merender prompt sistem yang lebih kecil untuk sub-agen. Runtime menetapkan
|
||||
`promptMode` untuk setiap eksekusi (bukan config yang ditampilkan kepada pengguna):
|
||||
`promptMode` untuk setiap eksekusi (bukan konfigurasi yang terlihat oleh pengguna):
|
||||
|
||||
- `full` (default): mencakup semua bagian di atas.
|
||||
- `minimal`: digunakan untuk sub-agen; menghilangkan **Skills**, **Memory Recall**, **OpenClaw
|
||||
Self-Update**, **Model Aliases**, **User Identity**, **Reply Tags**,
|
||||
**Messaging**, **Silent Replies**, dan **Heartbeats**. Tooling, **Safety**,
|
||||
Workspace, Sandbox, Current Date & Time (jika diketahui), Runtime, dan konteks
|
||||
yang disuntikkan tetap tersedia.
|
||||
- `full` (default): menyertakan semua bagian di atas.
|
||||
- `minimal`: digunakan untuk sub-agen; menghilangkan **Skills**, **Recall Memori**, **Pembaruan Mandiri OpenClaw**,
|
||||
**Alias Model**, **Identitas Pengguna**, **Tag Balasan**,
|
||||
**Pesan**, **Balasan Senyap**, dan **Heartbeat**. Tooling, **Keamanan**,
|
||||
Ruang Kerja, Sandbox, Tanggal & Waktu Saat Ini (bila diketahui), Runtime, dan konteks yang
|
||||
disuntikkan tetap tersedia.
|
||||
- `none`: hanya mengembalikan baris identitas dasar.
|
||||
|
||||
Saat `promptMode=minimal`, prompt tambahan yang disuntikkan diberi label **Subagent
|
||||
Context** alih-alih **Group Chat Context**.
|
||||
Saat `promptMode=minimal`, prompt tambahan yang disuntikkan diberi label **Konteks Subagen**
|
||||
alih-alih **Konteks Chat Grup**.
|
||||
|
||||
Untuk eksekusi auto-reply channel, OpenClaw dapat menghilangkan bagian generik **Silent Replies**
|
||||
ketika konteks chat langsung/grup sudah mencakup perilaku `NO_REPLY`
|
||||
khusus percakapan yang telah diselesaikan. Ini menghindari pengulangan mekanik token
|
||||
di prompt sistem global dan konteks channel sekaligus.
|
||||
Untuk eksekusi balasan otomatis kanal, OpenClaw dapat menghilangkan bagian umum **Balasan Senyap**
|
||||
ketika konteks chat langsung/grup sudah menyertakan perilaku
|
||||
`NO_REPLY` khusus percakapan yang sudah diselesaikan. Ini menghindari pengulangan mekanik token
|
||||
di prompt sistem global dan konteks kanal.
|
||||
|
||||
## Snapshot prompt
|
||||
|
||||
OpenClaw menyimpan snapshot prompt yang sudah dikomit untuk happy path runtime Codex di bawah
|
||||
OpenClaw menyimpan snapshot prompt yang dikomit untuk jalur sukses runtime Codex di
|
||||
`test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/`. Snapshot tersebut merender
|
||||
parameter thread/giliran app-server terpilih plus stack lapisan prompt terikat model yang direkonstruksi
|
||||
untuk giliran langsung Telegram, grup Discord, dan heartbeat. Stack tersebut
|
||||
mencakup fixture prompt model Codex `gpt-5.5` yang dipin dan dihasilkan dari bentuk
|
||||
katalog/cache model Codex, teks developer izin happy-path Codex,
|
||||
instruksi developer OpenClaw, instruksi collaboration-mode dengan cakupan giliran
|
||||
saat OpenClaw menyediakannya, input giliran pengguna, dan referensi ke spesifikasi alat
|
||||
untuk giliran langsung Telegram, grup Discord, dan heartbeat. Stack itu
|
||||
mencakup fixture prompt model Codex `gpt-5.5` yang dipin, dibuat dari bentuk
|
||||
katalog/cache model Codex, teks developer izin jalur sukses Codex,
|
||||
instruksi developer OpenClaw, instruksi mode kolaborasi berskala giliran
|
||||
ketika OpenClaw menyediakannya, input giliran pengguna, dan referensi ke spesifikasi tool
|
||||
dinamis.
|
||||
|
||||
Segarkan fixture prompt model Codex yang dipin dengan
|
||||
`pnpm prompt:snapshots:sync-codex-model`. Secara default, skrip mencari
|
||||
cache runtime Codex di `$CODEX_HOME/models_cache.json`, lalu
|
||||
`~/.codex/models_cache.json`, dan baru kemudian fallback ke konvensi checkout Codex
|
||||
`~/.codex/models_cache.json`, dan baru kemudian kembali ke konvensi checkout Codex
|
||||
maintainer di `~/code/codex/codex-rs/models-manager/models.json`. Jika
|
||||
tidak ada sumber tersebut, perintah keluar tanpa mengubah fixture yang dikomit.
|
||||
Berikan `--catalog <path>` untuk menyegarkan dari file `models_cache.json`
|
||||
atau `models.json` tertentu.
|
||||
|
||||
Snapshot ini masih bukan tangkapan permintaan OpenAI mentah byte demi byte. Codex
|
||||
dapat menambahkan konteks workspace milik runtime seperti `AGENTS.md`, konteks
|
||||
environment, memory, instruksi app/plugin, dan instruksi Default
|
||||
collaboration-mode bawaan di dalam runtime Codex setelah OpenClaw mengirim
|
||||
parameter thread dan giliran.
|
||||
Snapshot ini tetap bukan tangkapan permintaan OpenAI mentah byte-demi-byte. Codex
|
||||
dapat menambahkan konteks ruang kerja milik runtime seperti `AGENTS.md`, konteks
|
||||
lingkungan, memori, instruksi app/plugin, dan instruksi mode kolaborasi Default
|
||||
bawaan di dalam runtime Codex setelah OpenClaw mengirim parameter thread
|
||||
dan giliran.
|
||||
|
||||
Regenerasi dengan `pnpm prompt:snapshots:gen` dan verifikasi drift dengan
|
||||
`pnpm prompt:snapshots:check`. CI menjalankan pemeriksaan drift di shard boundary
|
||||
tambahan sehingga perubahan prompt dan pembaruan snapshot tetap terikat ke PR
|
||||
yang sama.
|
||||
Regenerasikan dengan `pnpm prompt:snapshots:gen` dan verifikasi drift dengan
|
||||
`pnpm prompt:snapshots:check`. CI menjalankan pemeriksaan drift di shard batas
|
||||
tambahan agar perubahan prompt dan pembaruan snapshot tetap melekat pada PR yang sama.
|
||||
|
||||
## Penyuntikan bootstrap workspace
|
||||
## Injeksi bootstrap ruang kerja
|
||||
|
||||
File bootstrap dipangkas dan ditambahkan di bawah **Project Context** sehingga model melihat konteks identitas dan profil tanpa perlu pembacaan eksplisit:
|
||||
File bootstrap dipangkas dan ditambahkan di bawah **Konteks Proyek** sehingga model melihat konteks identitas dan profil tanpa perlu pembacaan eksplisit:
|
||||
|
||||
- `AGENTS.md`
|
||||
- `SOUL.md`
|
||||
@ -158,54 +157,55 @@ File bootstrap dipangkas dan ditambahkan di bawah **Project Context** sehingga m
|
||||
- `IDENTITY.md`
|
||||
- `USER.md`
|
||||
- `HEARTBEAT.md`
|
||||
- `BOOTSTRAP.md` (hanya pada workspace yang benar-benar baru)
|
||||
- `MEMORY.md` jika ada
|
||||
- `BOOTSTRAP.md` (hanya pada ruang kerja yang benar-benar baru)
|
||||
- `MEMORY.md` bila ada
|
||||
|
||||
Semua file ini **disuntikkan ke jendela konteks** pada setiap giliran kecuali
|
||||
gate khusus file berlaku. `HEARTBEAT.md` dihilangkan pada eksekusi normal ketika
|
||||
heartbeat dinonaktifkan untuk agen default atau
|
||||
`agents.defaults.heartbeat.includeSystemPromptSection` bernilai false. Jaga file yang disuntikkan
|
||||
tetap ringkas — terutama `MEMORY.md`, yang dapat bertambah seiring waktu dan menyebabkan
|
||||
penggunaan konteks yang sangat tinggi secara tak terduga dan Compaction yang lebih sering.
|
||||
penggunaan konteks yang sangat tinggi tanpa diduga serta compaction yang lebih sering.
|
||||
|
||||
Saat sesi berjalan pada harness Codex native, Codex memuat `AGENTS.md`
|
||||
melalui discovery dokumen proyeknya sendiri. OpenClaw tetap menyelesaikan file
|
||||
bootstrap yang tersisa dan meneruskannya sebagai instruksi config Codex, sehingga `SOUL.md`,
|
||||
melalui penemuan dokumen proyeknya sendiri. OpenClaw tetap menyelesaikan file
|
||||
bootstrap lainnya dan meneruskannya sebagai instruksi konfigurasi Codex, sehingga `SOUL.md`,
|
||||
`TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, dan
|
||||
`MEMORY.md` mempertahankan peran konteks workspace yang sama tanpa menduplikasi
|
||||
`MEMORY.md` mempertahankan peran konteks ruang kerja yang sama tanpa menduplikasi
|
||||
`AGENTS.md`.
|
||||
|
||||
<Note>
|
||||
File harian `memory/*.md` **bukan** bagian dari Project Context bootstrap normal. Pada giliran biasa, file tersebut diakses sesuai kebutuhan melalui alat `memory_search` dan `memory_get`, sehingga tidak dihitung terhadap jendela konteks kecuali model membacanya secara eksplisit. Giliran `/new` dan `/reset` kosong adalah pengecualian: runtime dapat menambahkan memory harian terbaru di awal sebagai blok konteks startup sekali pakai untuk giliran pertama tersebut.
|
||||
File harian `memory/*.md` **bukan** bagian dari Konteks Proyek bootstrap normal. Pada giliran biasa file tersebut diakses sesuai kebutuhan melalui tool `memory_search` dan `memory_get`, sehingga tidak dihitung terhadap jendela konteks kecuali model membacanya secara eksplisit. Giliran `/new` dan `/reset` polos adalah pengecualian: runtime dapat menambahkan memori harian terbaru di awal sebagai blok konteks startup sekali pakai untuk giliran pertama itu.
|
||||
</Note>
|
||||
|
||||
File besar dipotong dengan penanda. Ukuran maksimum per file dikendalikan oleh
|
||||
`agents.defaults.bootstrapMaxChars` (default: 12000). Total konten bootstrap yang disuntikkan
|
||||
di seluruh file dibatasi oleh `agents.defaults.bootstrapTotalMaxChars`
|
||||
(default: 60000). File yang hilang menyuntikkan penanda singkat file-hilang. Saat pemotongan
|
||||
terjadi, OpenClaw dapat menyuntikkan blok peringatan dalam Project Context; kendalikan ini dengan
|
||||
(default: 60000). File yang hilang menyuntikkan penanda file-hilang singkat. Saat pemotongan
|
||||
terjadi, OpenClaw dapat menyuntikkan pemberitahuan peringatan prompt sistem yang ringkas; kendalikan ini dengan
|
||||
`agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`;
|
||||
default: `once`).
|
||||
default: `once`). Hitungan mentah/disuntikkan yang terperinci tetap berada dalam diagnostik seperti
|
||||
`/context`, `/status`, doctor, dan log.
|
||||
|
||||
Sesi sub-agen hanya menyuntikkan `AGENTS.md` dan `TOOLS.md` (file bootstrap lain
|
||||
Sesi sub-agen hanya menyuntikkan `AGENTS.md` dan `TOOLS.md` (file bootstrap lainnya
|
||||
difilter keluar untuk menjaga konteks sub-agen tetap kecil).
|
||||
|
||||
Hook internal dapat mengintersep langkah ini melalui `agent:bootstrap` untuk mengubah atau mengganti
|
||||
Hook internal dapat mencegat langkah ini melalui `agent:bootstrap` untuk memutasi atau mengganti
|
||||
file bootstrap yang disuntikkan (misalnya menukar `SOUL.md` dengan persona alternatif).
|
||||
|
||||
Jika Anda ingin membuat agen terdengar tidak terlalu generik, mulai dengan
|
||||
[Panduan Kepribadian SOUL.md](/id/concepts/soul).
|
||||
|
||||
Untuk memeriksa seberapa besar kontribusi tiap file yang disuntikkan (mentah vs disuntikkan, pemotongan, plus overhead skema alat), gunakan `/context list` atau `/context detail`. Lihat [Konteks](/id/concepts/context).
|
||||
Untuk memeriksa seberapa besar kontribusi setiap file yang disuntikkan (mentah vs disuntikkan, pemotongan, plus overhead skema tool), gunakan `/context list` atau `/context detail`. Lihat [Konteks](/id/concepts/context).
|
||||
|
||||
## Penanganan waktu
|
||||
|
||||
Prompt sistem mencakup bagian khusus **Current Date & Time** ketika
|
||||
zona waktu pengguna diketahui. Agar cache prompt tetap stabil, kini bagian tersebut hanya mencakup
|
||||
Prompt sistem menyertakan bagian khusus **Tanggal & Waktu Saat Ini** ketika
|
||||
zona waktu pengguna diketahui. Untuk menjaga prompt tetap stabil-cache, kini prompt hanya menyertakan
|
||||
**zona waktu** (tanpa jam dinamis atau format waktu).
|
||||
|
||||
Gunakan `session_status` saat agen membutuhkan waktu saat ini; kartu status
|
||||
mencakup baris timestamp. Alat yang sama dapat secara opsional menetapkan override model per sesi
|
||||
menyertakan baris stempel waktu. Tool yang sama dapat secara opsional menetapkan override model per sesi
|
||||
(`model=default` menghapusnya).
|
||||
|
||||
Konfigurasikan dengan:
|
||||
@ -217,19 +217,19 @@ Lihat [Tanggal & Waktu](/id/date-time) untuk detail perilaku lengkap.
|
||||
|
||||
## Skills
|
||||
|
||||
Saat skill yang memenuhi syarat tersedia, OpenClaw menyuntikkan **daftar Skills yang tersedia**
|
||||
ringkas (`formatSkillsForPrompt`) yang mencakup **path file** untuk setiap skill. Prompt
|
||||
menginstruksikan model untuk menggunakan `read` guna memuat SKILL.md di lokasi
|
||||
tercantum (workspace, terkelola, atau dibundel). Jika tidak ada skill yang memenuhi syarat, bagian
|
||||
Saat skill yang memenuhi syarat ada, OpenClaw menyuntikkan **daftar skills yang tersedia** yang ringkas
|
||||
(`formatSkillsForPrompt`) yang menyertakan **jalur file** untuk setiap skill. Prompt
|
||||
menginstruksikan model untuk menggunakan `read` guna memuat SKILL.md di lokasi yang terdaftar
|
||||
(ruang kerja, terkelola, atau dibundel). Jika tidak ada skill yang memenuhi syarat, bagian
|
||||
Skills dihilangkan.
|
||||
|
||||
Kelayakan mencakup gate metadata skill, pemeriksaan environment/config runtime,
|
||||
dan allowlist skill agen efektif saat `agents.defaults.skills` atau
|
||||
Kelayakan mencakup gate metadata skill, pemeriksaan lingkungan/konfigurasi runtime,
|
||||
dan allowlist skill agen efektif ketika `agents.defaults.skills` atau
|
||||
`agents.list[].skills` dikonfigurasi.
|
||||
|
||||
Skill yang dibundel plugin hanya memenuhi syarat saat plugin pemiliknya diaktifkan.
|
||||
Ini memungkinkan plugin alat mengekspos panduan operasi yang lebih dalam tanpa menyematkan semua
|
||||
panduan tersebut langsung ke setiap deskripsi alat.
|
||||
Skill yang dibundel Plugin hanya memenuhi syarat ketika Plugin pemiliknya diaktifkan.
|
||||
Ini memungkinkan Plugin tool mengekspos panduan operasi yang lebih mendalam tanpa menyematkan semua
|
||||
panduan tersebut langsung ke setiap deskripsi tool.
|
||||
|
||||
```
|
||||
<available_skills>
|
||||
@ -243,23 +243,23 @@ panduan tersebut langsung ke setiap deskripsi alat.
|
||||
|
||||
Ini menjaga prompt dasar tetap kecil sambil tetap memungkinkan penggunaan skill yang ditargetkan.
|
||||
|
||||
Anggaran daftar Skills dimiliki oleh subsistem Skills:
|
||||
Anggaran daftar skills dimiliki oleh subsistem skills:
|
||||
|
||||
- Default global: `skills.limits.maxSkillsPromptChars`
|
||||
- Override per agen: `agents.list[].skillsLimits.maxSkillsPromptChars`
|
||||
|
||||
Kutipan runtime generik berbatas menggunakan permukaan yang berbeda:
|
||||
Kutipan runtime generik berbatas menggunakan antarmuka yang berbeda:
|
||||
|
||||
- `agents.defaults.contextLimits.*`
|
||||
- `agents.list[].contextLimits.*`
|
||||
|
||||
Pemisahan itu menjaga ukuran Skills tetap terpisah dari ukuran baca/injeksi runtime seperti `memory_get`, hasil alat live, dan penyegaran AGENTS.md pasca-Compaction.
|
||||
Pemisahan itu menjaga pengukuran Skills tetap terpisah dari pengukuran baca/injeksi runtime seperti `memory_get`, hasil alat langsung, dan penyegaran AGENTS.md pasca-Compaction.
|
||||
|
||||
## Dokumentasi
|
||||
|
||||
Prompt sistem menyertakan bagian **Dokumentasi**. Ketika dokumentasi lokal tersedia, bagian ini mengarah ke direktori dokumentasi OpenClaw lokal (`docs/` dalam checkout Git atau dokumentasi paket npm yang dibundel). Jika dokumentasi lokal tidak tersedia, bagian ini menggunakan fallback ke [https://docs.openclaw.ai](https://docs.openclaw.ai).
|
||||
Prompt sistem menyertakan bagian **Dokumentasi**. Saat dokumentasi lokal tersedia, bagian ini menunjuk ke direktori dokumentasi OpenClaw lokal (`docs/` dalam checkout Git atau dokumentasi paket npm yang dibundel). Jika dokumentasi lokal tidak tersedia, bagian ini kembali ke [https://docs.openclaw.ai](https://docs.openclaw.ai).
|
||||
|
||||
Bagian yang sama juga menyertakan lokasi sumber OpenClaw. Checkout Git mengekspos root sumber lokal sehingga agen dapat memeriksa kode secara langsung. Instalasi paket menyertakan URL sumber GitHub dan memberi tahu agen untuk meninjau sumber di sana setiap kali dokumentasi tidak lengkap atau usang. Prompt juga mencatat mirror dokumentasi publik, komunitas Discord, dan ClawHub ([https://clawhub.ai](https://clawhub.ai)) untuk penemuan Skills. Prompt memberi tahu model untuk berkonsultasi dengan dokumentasi terlebih dahulu untuk perilaku, perintah, konfigurasi, atau arsitektur OpenClaw, dan untuk menjalankan `openclaw status` sendiri bila memungkinkan (hanya bertanya kepada pengguna ketika tidak memiliki akses). Khusus untuk konfigurasi, prompt mengarahkan agen ke tindakan alat `gateway` `config.schema.lookup` untuk dokumentasi dan batasan tingkat bidang yang tepat, lalu ke `docs/gateway/configuration.md` dan `docs/gateway/configuration-reference.md` untuk panduan yang lebih luas.
|
||||
Bagian yang sama juga menyertakan lokasi sumber OpenClaw. Checkout Git mengekspos root sumber lokal agar agen dapat memeriksa kode secara langsung. Instalasi paket menyertakan URL sumber GitHub dan memberi tahu agen untuk meninjau sumber di sana setiap kali dokumentasi tidak lengkap atau sudah usang. Prompt juga mencatat cermin dokumentasi publik, Discord komunitas, dan ClawHub ([https://clawhub.ai](https://clawhub.ai)) untuk penemuan Skills. Prompt memberi tahu model untuk berkonsultasi dengan dokumentasi terlebih dahulu terkait perilaku, perintah, konfigurasi, atau arsitektur OpenClaw, dan untuk menjalankan `openclaw status` sendiri jika memungkinkan (hanya bertanya kepada pengguna saat tidak memiliki akses). Khusus untuk konfigurasi, prompt mengarahkan agen ke aksi alat `gateway` `config.schema.lookup` untuk dokumentasi dan batasan tingkat bidang yang tepat, lalu ke `docs/gateway/configuration.md` dan `docs/gateway/configuration-reference.md` untuk panduan yang lebih luas.
|
||||
|
||||
## Terkait
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user