chore(i18n): refresh id translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
3f5000005f
commit
91b4e5a5cc
@ -1,40 +1,40 @@
|
||||
---
|
||||
read_when:
|
||||
- Menyiapkan kontrol akses DM
|
||||
- Melakukan pairing node iOS/Android baru
|
||||
- Mem-pairing node iOS/Android baru
|
||||
- Meninjau postur keamanan OpenClaw
|
||||
summary: 'Ikhtisar pairing: setujui siapa yang dapat mengirimi Anda DM + node mana yang dapat bergabung'
|
||||
summary: 'Ringkasan pairing: setujui siapa yang dapat mengirimi Anda DM + node mana yang dapat bergabung'
|
||||
title: Pairing
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T13:43:46Z"
|
||||
generated_at: "2026-04-20T09:27:37Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 2bd99240b3530def23c05a26915d07cf8b730565c2822c6338437f8fb3f285c9
|
||||
source_hash: 4161629ead02dc0bdcd283cc125fe6579a579e03740127f4feb22dfe344bd028
|
||||
source_path: channels/pairing.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Pairing
|
||||
|
||||
“Pairing” adalah langkah **persetujuan pemilik** eksplisit OpenClaw.
|
||||
“Pairing” adalah langkah **persetujuan pemilik** yang eksplisit di OpenClaw.
|
||||
Ini digunakan di dua tempat:
|
||||
|
||||
1. **Pairing DM** (siapa yang diizinkan berbicara dengan bot)
|
||||
2. **Pairing node** (perangkat/node mana yang diizinkan bergabung ke jaringan gateway)
|
||||
1. **DM pairing** (siapa yang diizinkan berbicara dengan bot)
|
||||
2. **Node pairing** (perangkat/node mana yang diizinkan bergabung ke jaringan Gateway)
|
||||
|
||||
Konteks keamanan: [Keamanan](/gateway/security)
|
||||
Konteks keamanan: [Security](/id/gateway/security)
|
||||
|
||||
## 1) Pairing DM (akses chat masuk)
|
||||
## 1) DM pairing (akses chat masuk)
|
||||
|
||||
Saat sebuah channel dikonfigurasi dengan kebijakan DM `pairing`, pengirim yang tidak dikenal akan mendapatkan kode singkat dan pesan mereka **tidak diproses** sampai Anda menyetujuinya.
|
||||
Saat sebuah channel dikonfigurasi dengan kebijakan DM `pairing`, pengirim yang tidak dikenal akan mendapatkan kode singkat dan pesannya **tidak diproses** sampai Anda menyetujuinya.
|
||||
|
||||
Kebijakan DM default didokumentasikan di: [Keamanan](/gateway/security)
|
||||
Kebijakan DM default didokumentasikan di: [Security](/id/gateway/security)
|
||||
|
||||
Kode pairing:
|
||||
|
||||
- 8 karakter, huruf besar, tanpa karakter ambigu (`0O1I`).
|
||||
- 8 karakter, huruf besar, tanpa karakter yang ambigu (`0O1I`).
|
||||
- **Kedaluwarsa setelah 1 jam**. Bot hanya mengirim pesan pairing saat permintaan baru dibuat (kurang lebih sekali per jam per pengirim).
|
||||
- Permintaan pairing DM yang tertunda dibatasi maksimal **3 per channel** secara default; permintaan tambahan diabaikan sampai salah satunya kedaluwarsa atau disetujui.
|
||||
- Permintaan DM pairing yang tertunda dibatasi hingga **3 per channel** secara default; permintaan tambahan diabaikan sampai salah satunya kedaluwarsa atau disetujui.
|
||||
|
||||
### Menyetujui pengirim
|
||||
|
||||
@ -45,7 +45,7 @@ openclaw pairing approve telegram <CODE>
|
||||
|
||||
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`.
|
||||
|
||||
### Tempat status disimpan
|
||||
### Lokasi penyimpanan status
|
||||
|
||||
Disimpan di bawah `~/.openclaw/credentials/`:
|
||||
|
||||
@ -56,46 +56,46 @@ Disimpan di bawah `~/.openclaw/credentials/`:
|
||||
|
||||
Perilaku cakupan akun:
|
||||
|
||||
- Akun non-default hanya membaca/menulis file allowlist dalam cakupannya.
|
||||
- Akun default menggunakan file allowlist tanpa cakupan yang dicakup per channel.
|
||||
- Akun non-default hanya membaca/menulis file allowlist dengan cakupan akunnya.
|
||||
- Akun default menggunakan file allowlist tanpa cakupan yang khusus untuk channel tersebut.
|
||||
|
||||
Anggap ini sensitif (karena menentukan akses ke asisten Anda).
|
||||
Anggap ini sensitif (karena mengendalikan akses ke asisten Anda).
|
||||
|
||||
Penting: penyimpanan ini untuk akses DM. Otorisasi grup terpisah.
|
||||
Menyetujui kode pairing DM tidak secara otomatis mengizinkan pengirim tersebut menjalankan perintah grup atau mengontrol bot di grup. Untuk akses grup, konfigurasikan allowlist grup eksplisit milik channel tersebut (misalnya `groupAllowFrom`, `groups`, atau override per grup/per topik tergantung channel).
|
||||
Penting: penyimpanan ini untuk akses DM. Otorisasi grup bersifat terpisah.
|
||||
Menyetujui kode DM pairing tidak secara otomatis mengizinkan pengirim tersebut menjalankan perintah grup atau mengendalikan bot di grup. Untuk akses grup, konfigurasikan allowlist grup eksplisit milik channel tersebut (misalnya `groupAllowFrom`, `groups`, atau override per grup/per topik tergantung pada channel).
|
||||
|
||||
## 2) Pairing 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 pairing perangkat yang harus disetujui.
|
||||
|
||||
### Pair melalui Telegram (direkomendasikan untuk iOS)
|
||||
### Pair via Telegram (disarankan untuk iOS)
|
||||
|
||||
Jika Anda menggunakan plugin `device-pair`, Anda dapat melakukan pairing 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 untuk disalin/ditempel di Telegram).
|
||||
2. Bot membalas dengan dua pesan: pesan instruksi dan pesan **kode penyiapan** terpisah (mudah disalin/ditempel di Telegram).
|
||||
3. Di ponsel Anda, buka aplikasi OpenClaw iOS → Settings → Gateway.
|
||||
4. Tempel kode penyiapan lalu sambungkan.
|
||||
4. Tempel kode penyiapan dan hubungkan.
|
||||
5. Kembali ke Telegram: `/pair pending` (tinjau ID permintaan, role, dan scope), lalu setujui.
|
||||
|
||||
Kode penyiapan adalah payload JSON terenkripsi base64 yang berisi:
|
||||
Kode penyiapan adalah payload JSON berkode base64 yang berisi:
|
||||
|
||||
- `url`: URL WebSocket Gateway (`ws://...` atau `wss://...`)
|
||||
- `bootstrapToken`: token bootstrap satu perangkat yang berumur pendek dan digunakan untuk handshake pairing awal
|
||||
- `bootstrapToken`: token bootstrap satu perangkat berumur singkat yang digunakan untuk handshake pairing awal
|
||||
|
||||
Token bootstrap tersebut membawa profil bootstrap pairing bawaan:
|
||||
|
||||
- token `node` utama yang diserahkan tetap `scopes: []`
|
||||
- token `operator` yang diserahkan tetap dibatasi ke allowlist bootstrap:
|
||||
- token `operator` yang diserahkan tetap dibatasi ke bootstrap allowlist:
|
||||
`operator.approvals`, `operator.read`, `operator.talk.secrets`, `operator.write`
|
||||
- pemeriksaan scope bootstrap diberi awalan role, bukan satu kumpulan scope datar:
|
||||
- pemeriksaan scope bootstrap menggunakan prefiks role, bukan satu kumpulan scope datar:
|
||||
entri scope operator hanya memenuhi permintaan operator, dan role non-operator
|
||||
tetap harus meminta scope di bawah awalan role mereka sendiri
|
||||
tetap harus meminta scope di bawah prefiks role mereka sendiri
|
||||
|
||||
Perlakukan kode penyiapan seperti kata sandi selama masih berlaku.
|
||||
|
||||
### Menyetujui perangkat node
|
||||
### Menyetujui perangkat Node
|
||||
|
||||
```bash
|
||||
openclaw devices list
|
||||
@ -103,34 +103,40 @@ openclaw devices approve <requestId>
|
||||
openclaw devices reject <requestId>
|
||||
```
|
||||
|
||||
Jika perangkat yang sama mencoba lagi dengan detail autentikasi berbeda (misalnya
|
||||
Jika perangkat yang sama mencoba lagi dengan detail autentikasi yang berbeda (misalnya
|
||||
role/scope/public key yang berbeda), permintaan tertunda sebelumnya akan digantikan dan
|
||||
`requestId` baru akan dibuat.
|
||||
|
||||
### Penyimpanan status pairing node
|
||||
Penting: perangkat yang sudah di-pairing tidak akan diam-diam mendapatkan akses yang lebih luas. Jika perangkat itu
|
||||
terhubung kembali dengan meminta scope lebih banyak atau role yang lebih luas, OpenClaw mempertahankan
|
||||
persetujuan yang ada sebagaimana adanya dan membuat permintaan upgrade tertunda yang baru. Gunakan
|
||||
`openclaw devices list` untuk membandingkan akses yang saat ini disetujui dengan akses yang baru
|
||||
diminta sebelum Anda menyetujuinya.
|
||||
|
||||
### Penyimpanan status Node pairing
|
||||
|
||||
Disimpan di bawah `~/.openclaw/devices/`:
|
||||
|
||||
- `pending.json` (berumur pendek; permintaan tertunda akan kedaluwarsa)
|
||||
- `paired.json` (perangkat yang sudah dipairing + token)
|
||||
- `pending.json` (berumur singkat; permintaan tertunda akan kedaluwarsa)
|
||||
- `paired.json` (perangkat yang sudah di-pairing + token)
|
||||
|
||||
### Catatan
|
||||
|
||||
- API `node.pair.*` lama (CLI: `openclaw nodes pending|approve|reject|rename`) adalah
|
||||
penyimpanan pairing terpisah milik gateway. Node WS tetap memerlukan pairing perangkat.
|
||||
- Rekaman pairing adalah sumber kebenaran tahan lama untuk role yang disetujui. Token
|
||||
perangkat aktif tetap dibatasi ke kumpulan role yang disetujui tersebut; entri token
|
||||
liar di luar role yang disetujui tidak menciptakan akses baru.
|
||||
penyimpanan pairing terpisah yang dimiliki Gateway. Node WS tetap memerlukan pairing perangkat.
|
||||
- Catatan pairing adalah sumber kebenaran yang tahan lama untuk role yang disetujui. Token perangkat yang aktif
|
||||
tetap dibatasi pada kumpulan role yang disetujui tersebut; entri token liar
|
||||
di luar role yang disetujui tidak menciptakan akses baru.
|
||||
|
||||
## Dokumen terkait
|
||||
## Dokumentasi terkait
|
||||
|
||||
- Model keamanan + prompt injection: [Keamanan](/gateway/security)
|
||||
- Memperbarui dengan aman (jalankan doctor): [Memperbarui](/install/updating)
|
||||
- Model keamanan + prompt injection: [Security](/id/gateway/security)
|
||||
- Memperbarui dengan aman (jalankan doctor): [Updating](/id/install/updating)
|
||||
- Konfigurasi channel:
|
||||
- Telegram: [Telegram](/channels/telegram)
|
||||
- WhatsApp: [WhatsApp](/channels/whatsapp)
|
||||
- Signal: [Signal](/channels/signal)
|
||||
- BlueBubbles (iMessage): [BlueBubbles](/channels/bluebubbles)
|
||||
- iMessage (lama): [iMessage](/channels/imessage)
|
||||
- Discord: [Discord](/channels/discord)
|
||||
- Slack: [Slack](/channels/slack)
|
||||
- Telegram: [Telegram](/id/channels/telegram)
|
||||
- WhatsApp: [WhatsApp](/id/channels/whatsapp)
|
||||
- Signal: [Signal](/id/channels/signal)
|
||||
- BlueBubbles (iMessage): [BlueBubbles](/id/channels/bluebubbles)
|
||||
- iMessage (legacy): [iMessage](/id/channels/imessage)
|
||||
- Discord: [Discord](/id/channels/discord)
|
||||
- Slack: [Slack](/id/channels/slack)
|
||||
|
||||
@ -1,13 +1,13 @@
|
||||
---
|
||||
read_when:
|
||||
- Sedang mengerjakan fitur Telegram atau webhook
|
||||
- Mengerjakan fitur Telegram atau Webhook
|
||||
summary: Status dukungan bot Telegram, kemampuan, dan konfigurasi
|
||||
title: Telegram
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T13:52:08Z"
|
||||
generated_at: "2026-04-20T09:27:34Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 39fbf328375fbc5d08ec2e3eed58b19ee0afa102010ecbc02e074a310ced157e
|
||||
source_hash: b9903fae98bca0c345aa86d5c29015539c375442524a34d26bd28181470b8477
|
||||
source_path: channels/telegram.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -17,13 +17,13 @@ x-i18n:
|
||||
Status: siap produksi untuk DM bot + grup melalui grammY. Long polling adalah mode default; mode webhook bersifat opsional.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Pairing" icon="link" href="/id/channels/pairing">
|
||||
Kebijakan DM default untuk Telegram adalah pairing.
|
||||
<Card title="Pemasangan" icon="link" href="/id/channels/pairing">
|
||||
Kebijakan DM default untuk Telegram adalah pemasangan.
|
||||
</Card>
|
||||
<Card title="Pemecahan masalah channel" icon="wrench" href="/id/channels/troubleshooting">
|
||||
Diagnostik lintas-channel dan panduan perbaikan.
|
||||
Diagnostik lintas channel dan playbook perbaikan.
|
||||
</Card>
|
||||
<Card title="Konfigurasi gateway" icon="settings" href="/gateway/configuration">
|
||||
<Card title="Konfigurasi Gateway" icon="settings" href="/id/gateway/configuration">
|
||||
Pola dan contoh konfigurasi channel lengkap.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@ -32,9 +32,9 @@ Status: siap produksi untuk DM bot + grup melalui grammY. Long polling adalah mo
|
||||
|
||||
<Steps>
|
||||
<Step title="Buat token bot di BotFather">
|
||||
Buka Telegram dan chat dengan **@BotFather** (pastikan handle-nya persis `@BotFather`).
|
||||
Buka Telegram dan chat dengan **@BotFather** (pastikan handle-nya tepat `@BotFather`).
|
||||
|
||||
Jalankan `/newbot`, ikuti petunjuknya, lalu simpan token-nya.
|
||||
Jalankan `/newbot`, ikuti petunjuk, lalu simpan tokennya.
|
||||
|
||||
</Step>
|
||||
|
||||
@ -54,11 +54,11 @@ Status: siap produksi untuk DM bot + grup melalui grammY. Long polling adalah mo
|
||||
```
|
||||
|
||||
Fallback env: `TELEGRAM_BOT_TOKEN=...` (hanya akun default).
|
||||
Telegram **tidak** menggunakan `openclaw channels login telegram`; konfigurasikan token di config/env, lalu mulai gateway.
|
||||
Telegram **tidak** menggunakan `openclaw channels login telegram`; konfigurasikan token di config/env, lalu jalankan gateway.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Mulai gateway dan setujui DM pertama">
|
||||
<Step title="Jalankan gateway dan setujui DM pertama">
|
||||
|
||||
```bash
|
||||
openclaw gateway
|
||||
@ -66,7 +66,7 @@ openclaw pairing list telegram
|
||||
openclaw pairing approve telegram <CODE>
|
||||
```
|
||||
|
||||
Kode pairing kedaluwarsa setelah 1 jam.
|
||||
Kode pemasangan kedaluwarsa setelah 1 jam.
|
||||
|
||||
</Step>
|
||||
|
||||
@ -76,26 +76,26 @@ openclaw pairing approve telegram <CODE>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
Urutan resolusi token memperhitungkan akun. Dalam praktiknya, nilai config lebih diutamakan daripada fallback env, dan `TELEGRAM_BOT_TOKEN` hanya berlaku untuk akun default.
|
||||
Urutan resolusi token bersifat sadar-akun. Dalam praktiknya, nilai config mengalahkan fallback env, dan `TELEGRAM_BOT_TOKEN` hanya berlaku untuk akun default.
|
||||
</Note>
|
||||
|
||||
## Pengaturan di sisi Telegram
|
||||
## Pengaturan sisi Telegram
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Mode privasi dan visibilitas grup">
|
||||
Bot Telegram secara default menggunakan **Privacy Mode**, yang membatasi pesan grup yang mereka terima.
|
||||
|
||||
Jika bot harus dapat melihat semua pesan grup, lakukan salah satu dari berikut ini:
|
||||
Jika bot harus melihat semua pesan grup, lakukan salah satu dari berikut:
|
||||
|
||||
- nonaktifkan privacy mode melalui `/setprivacy`, atau
|
||||
- nonaktifkan mode privasi melalui `/setprivacy`, atau
|
||||
- jadikan bot sebagai admin grup.
|
||||
|
||||
Saat mengubah privacy mode, keluarkan lalu tambahkan kembali bot di setiap grup agar Telegram menerapkan perubahan tersebut.
|
||||
Saat mengubah mode privasi, hapus lalu tambahkan kembali bot di setiap grup agar Telegram menerapkan perubahan tersebut.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Izin grup">
|
||||
Status admin dikendalikan dalam pengaturan grup Telegram.
|
||||
Status admin dikendalikan di pengaturan grup Telegram.
|
||||
|
||||
Bot admin menerima semua pesan grup, yang berguna untuk perilaku grup yang selalu aktif.
|
||||
|
||||
@ -117,20 +117,20 @@ Urutan resolusi token memperhitungkan akun. Dalam praktiknya, nilai config lebih
|
||||
|
||||
- `pairing` (default)
|
||||
- `allowlist` (memerlukan setidaknya satu ID pengirim di `allowFrom`)
|
||||
- `open` (mengharuskan `allowFrom` menyertakan `"*"`)
|
||||
- `open` (memerlukan `allowFrom` untuk menyertakan `"*"`)
|
||||
- `disabled`
|
||||
|
||||
`channels.telegram.allowFrom` menerima ID pengguna Telegram numerik. Prefiks `telegram:` / `tg:` diterima dan dinormalisasi.
|
||||
`channels.telegram.allowFrom` menerima ID pengguna Telegram numerik. Awalan `telegram:` / `tg:` diterima dan dinormalisasi.
|
||||
`dmPolicy: "allowlist"` dengan `allowFrom` kosong memblokir semua DM dan ditolak oleh validasi config.
|
||||
Onboarding menerima input `@username` dan meresolusikannya ke ID numerik.
|
||||
Jika Anda melakukan upgrade dan config Anda berisi entri allowlist `@username`, jalankan `openclaw doctor --fix` untuk meresolusikannya (best-effort; memerlukan token bot Telegram).
|
||||
Penyiapan meminta hanya ID pengguna numerik.
|
||||
Jika Anda melakukan upgrade dan config Anda berisi entri allowlist `@username`, jalankan `openclaw doctor --fix` untuk menyelesaikannya (upaya terbaik; memerlukan token bot Telegram).
|
||||
Jika sebelumnya Anda mengandalkan file allowlist pairing-store, `openclaw doctor --fix` dapat memulihkan entri ke `channels.telegram.allowFrom` dalam alur allowlist (misalnya saat `dmPolicy: "allowlist"` belum memiliki ID eksplisit).
|
||||
|
||||
Untuk bot dengan satu pemilik, gunakan `dmPolicy: "allowlist"` dengan ID `allowFrom` numerik yang eksplisit agar kebijakan akses tetap tahan lama di config (alih-alih bergantung pada persetujuan pairing sebelumnya).
|
||||
Untuk bot dengan satu pemilik, gunakan `dmPolicy: "allowlist"` dengan ID `allowFrom` numerik yang eksplisit agar kebijakan akses tetap bertahan di config (alih-alih bergantung pada persetujuan pemasangan sebelumnya).
|
||||
|
||||
Kebingungan umum: persetujuan pairing DM tidak berarti "pengirim ini diotorisasi di mana saja".
|
||||
Pairing hanya memberikan akses DM. Otorisasi pengirim grup tetap berasal dari allowlist config yang eksplisit.
|
||||
Jika Anda ingin "saya diotorisasi sekali lalu baik DM maupun perintah grup berfungsi", masukkan ID pengguna Telegram numerik Anda ke `channels.telegram.allowFrom`.
|
||||
Kebingungan yang umum: persetujuan pemasangan DM tidak berarti "pengirim ini diotorisasi di mana saja".
|
||||
Pemasangan hanya memberikan akses DM. Otorisasi pengirim grup tetap berasal dari allowlist config yang eksplisit.
|
||||
Jika Anda ingin "saya diotorisasi sekali dan DM maupun perintah grup sama-sama berfungsi", masukkan ID pengguna Telegram numerik Anda ke `channels.telegram.allowFrom`.
|
||||
|
||||
### Menemukan ID pengguna Telegram Anda
|
||||
|
||||
@ -151,7 +151,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
</Tab>
|
||||
|
||||
<Tab title="Kebijakan grup dan allowlist">
|
||||
Dua kontrol diterapkan bersamaan:
|
||||
Dua kontrol berlaku bersamaan:
|
||||
|
||||
1. **Grup mana yang diizinkan** (`channels.telegram.groups`)
|
||||
- tanpa config `groups`:
|
||||
@ -159,20 +159,20 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- dengan `groupPolicy: "allowlist"` (default): grup diblokir sampai Anda menambahkan entri `groups` (atau `"*"`)
|
||||
- `groups` dikonfigurasi: bertindak sebagai allowlist (ID eksplisit atau `"*"`)
|
||||
|
||||
2. **Pengirim mana yang diizinkan di grup** (`channels.telegram.groupPolicy`)
|
||||
2. **Pengirim mana yang diizinkan dalam grup** (`channels.telegram.groupPolicy`)
|
||||
- `open`
|
||||
- `allowlist` (default)
|
||||
- `disabled`
|
||||
|
||||
`groupAllowFrom` digunakan untuk pemfilteran pengirim grup. Jika tidak diatur, Telegram akan fallback ke `allowFrom`.
|
||||
Entri `groupAllowFrom` harus berupa ID pengguna Telegram numerik (prefiks `telegram:` / `tg:` dinormalisasi).
|
||||
Jangan masukkan ID chat grup atau supergroup Telegram ke dalam `groupAllowFrom`. ID chat negatif harus ditempatkan di bawah `channels.telegram.groups`.
|
||||
`groupAllowFrom` digunakan untuk pemfilteran pengirim grup. Jika tidak diatur, Telegram akan menggunakan fallback ke `allowFrom`.
|
||||
Entri `groupAllowFrom` harus berupa ID pengguna Telegram numerik (awalan `telegram:` / `tg:` dinormalisasi).
|
||||
Jangan letakkan ID chat grup atau supergrup Telegram di `groupAllowFrom`. ID chat negatif harus ditempatkan di bawah `channels.telegram.groups`.
|
||||
Entri non-numerik diabaikan untuk otorisasi pengirim.
|
||||
Batas keamanan (`2026.2.25+`): auth pengirim grup **tidak** mewarisi persetujuan pairing-store DM.
|
||||
Pairing tetap hanya untuk DM. Untuk grup, atur `groupAllowFrom` atau `allowFrom` per-grup/per-topik.
|
||||
Jika `groupAllowFrom` tidak diatur, Telegram fallback ke config `allowFrom`, bukan pairing store.
|
||||
Pola praktis untuk bot satu pemilik: atur ID pengguna Anda di `channels.telegram.allowFrom`, biarkan `groupAllowFrom` tidak diatur, dan izinkan grup target di bawah `channels.telegram.groups`.
|
||||
Catatan runtime: jika `channels.telegram` sama sekali tidak ada, default runtime adalah fail-closed `groupPolicy="allowlist"` kecuali `channels.defaults.groupPolicy` diatur secara eksplisit.
|
||||
Batas keamanan (`2026.2.25+`): autentikasi pengirim grup **tidak** mewarisi persetujuan pairing-store DM.
|
||||
Pemasangan tetap hanya untuk DM. Untuk grup, atur `groupAllowFrom` atau `allowFrom` per grup/per topik.
|
||||
Jika `groupAllowFrom` tidak diatur, Telegram akan menggunakan fallback ke config `allowFrom`, bukan pairing store.
|
||||
Pola praktis untuk bot dengan satu pemilik: atur ID pengguna Anda di `channels.telegram.allowFrom`, biarkan `groupAllowFrom` tidak diatur, dan izinkan grup target di `channels.telegram.groups`.
|
||||
Catatan runtime: jika `channels.telegram` benar-benar tidak ada, default runtime adalah fail-closed `groupPolicy="allowlist"` kecuali `channels.defaults.groupPolicy` diatur secara eksplisit.
|
||||
|
||||
Contoh: izinkan anggota mana pun di satu grup tertentu:
|
||||
|
||||
@ -211,9 +211,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
<Warning>
|
||||
Kesalahan umum: `groupAllowFrom` bukan allowlist grup Telegram.
|
||||
|
||||
- Tempatkan ID chat grup atau supergroup Telegram negatif seperti `-1001234567890` di bawah `channels.telegram.groups`.
|
||||
- Tempatkan ID pengguna Telegram seperti `8734062810` di bawah `groupAllowFrom` saat Anda ingin membatasi orang mana di dalam grup yang diizinkan dapat memicu bot.
|
||||
- Gunakan `groupAllowFrom: ["*"]` hanya ketika Anda ingin anggota mana pun dari grup yang diizinkan dapat berbicara dengan bot.
|
||||
- Letakkan ID grup atau supergrup Telegram negatif seperti `-1001234567890` di bawah `channels.telegram.groups`.
|
||||
- Letakkan ID pengguna Telegram seperti `8734062810` di bawah `groupAllowFrom` saat Anda ingin membatasi orang mana di dalam grup yang diizinkan yang dapat memicu bot.
|
||||
- Gunakan `groupAllowFrom: ["*"]` hanya jika Anda ingin anggota mana pun dari grup yang diizinkan dapat berbicara dengan bot.
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
@ -233,7 +233,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `/activation always`
|
||||
- `/activation mention`
|
||||
|
||||
Ini hanya memperbarui state sesi. Gunakan config untuk persistensi.
|
||||
Ini hanya memperbarui status sesi. Gunakan config untuk persistensi.
|
||||
|
||||
Contoh config persisten:
|
||||
|
||||
@ -253,7 +253,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- teruskan pesan grup ke `@userinfobot` / `@getidsbot`
|
||||
- atau baca `chat.id` dari `openclaw logs --follow`
|
||||
- atau periksa `getUpdates` Bot API
|
||||
- atau periksa Bot API `getUpdates`
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
@ -261,59 +261,59 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
## Perilaku runtime
|
||||
|
||||
- Telegram dimiliki oleh proses gateway.
|
||||
- Routing bersifat deterministik: balasan inbound Telegram kembali ke Telegram (model tidak memilih channel).
|
||||
- Pesan inbound dinormalisasi ke envelope channel bersama dengan metadata balasan dan placeholder media.
|
||||
- Routing bersifat deterministik: balasan masuk dari Telegram akan dibalas kembali ke Telegram (model tidak memilih channel).
|
||||
- Pesan masuk dinormalisasi ke shared channel envelope dengan metadata balasan dan placeholder media.
|
||||
- Sesi grup diisolasi berdasarkan ID grup. Topik forum menambahkan `:topic:<threadId>` agar topik tetap terisolasi.
|
||||
- Pesan DM dapat membawa `message_thread_id`; OpenClaw merutekannya dengan kunci sesi yang sadar thread dan mempertahankan ID thread untuk balasan.
|
||||
- Long polling menggunakan grammY runner dengan pengurutan per-chat/per-thread. Sink runner secara keseluruhan menggunakan konkurensi `agents.defaults.maxConcurrent`.
|
||||
- Pesan DM dapat membawa `message_thread_id`; OpenClaw merutekannya dengan kunci sesi yang sadar-thread dan mempertahankan ID thread untuk balasan.
|
||||
- Long polling menggunakan grammY runner dengan pengurutan per-chat/per-thread. Konkurensi sink runner secara keseluruhan menggunakan `agents.defaults.maxConcurrent`.
|
||||
- Telegram Bot API tidak memiliki dukungan tanda terima baca (`sendReadReceipts` tidak berlaku).
|
||||
|
||||
## Referensi fitur
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Pratinjau live stream (edit pesan)">
|
||||
<Accordion title="Pratinjau stream langsung (edit pesan)">
|
||||
OpenClaw dapat melakukan streaming balasan parsial secara real time:
|
||||
|
||||
- chat langsung: pesan pratinjau + `editMessageText`
|
||||
- grup/topik: pesan pratinjau + `editMessageText`
|
||||
|
||||
Syarat:
|
||||
Persyaratan:
|
||||
|
||||
- `channels.telegram.streaming` adalah `off | partial | block | progress` (default: `partial`)
|
||||
- `progress` dipetakan ke `partial` di Telegram (kompatibel dengan penamaan lintas-channel)
|
||||
- nilai lama `channels.telegram.streamMode` dan nilai boolean `streaming` dipetakan otomatis
|
||||
- `progress` dipetakan ke `partial` di Telegram (kompatibel dengan penamaan lintas channel)
|
||||
- nilai legacy `channels.telegram.streamMode` dan boolean `streaming` dipetakan secara otomatis
|
||||
|
||||
Untuk balasan teks saja:
|
||||
Untuk balasan hanya teks:
|
||||
|
||||
- DM: OpenClaw mempertahankan pesan pratinjau yang sama dan melakukan edit final di tempatnya (tanpa pesan kedua)
|
||||
- grup/topik: OpenClaw mempertahankan pesan pratinjau yang sama dan melakukan edit final di tempatnya (tanpa pesan kedua)
|
||||
- DM: OpenClaw mempertahankan pesan pratinjau yang sama dan melakukan edit final di tempat (tanpa pesan kedua)
|
||||
- grup/topik: OpenClaw mempertahankan pesan pratinjau yang sama dan melakukan edit final di tempat (tanpa pesan kedua)
|
||||
|
||||
Untuk balasan kompleks (misalnya payload media), OpenClaw fallback ke pengiriman final normal lalu membersihkan pesan pratinjau.
|
||||
Untuk balasan kompleks (misalnya payload media), OpenClaw menggunakan fallback ke pengiriman final normal lalu membersihkan pesan pratinjau.
|
||||
|
||||
Preview streaming terpisah dari block streaming. Saat block streaming diaktifkan secara eksplisit untuk Telegram, OpenClaw melewati preview stream untuk menghindari double-streaming.
|
||||
Streaming pratinjau terpisah dari block streaming. Saat block streaming diaktifkan secara eksplisit untuk Telegram, OpenClaw melewati stream pratinjau untuk menghindari streaming ganda.
|
||||
|
||||
Jika transport draf native tidak tersedia/ditolak, OpenClaw otomatis fallback ke `sendMessage` + `editMessageText`.
|
||||
Jika transport draf native tidak tersedia/ditolak, OpenClaw secara otomatis menggunakan fallback ke `sendMessage` + `editMessageText`.
|
||||
|
||||
Streaming reasoning khusus Telegram:
|
||||
Stream reasoning khusus Telegram:
|
||||
|
||||
- `/reasoning stream` mengirim reasoning ke pratinjau live saat sedang menghasilkan
|
||||
- `/reasoning stream` mengirim reasoning ke pratinjau langsung selama proses generasi
|
||||
- jawaban final dikirim tanpa teks reasoning
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Pemformatan dan fallback HTML">
|
||||
Teks outbound menggunakan Telegram `parse_mode: "HTML"`.
|
||||
Teks keluar menggunakan Telegram `parse_mode: "HTML"`.
|
||||
|
||||
- Teks bergaya Markdown dirender menjadi HTML aman untuk Telegram.
|
||||
- HTML model mentah di-escape untuk mengurangi kegagalan parse Telegram.
|
||||
- Jika Telegram menolak HTML yang telah diparse, OpenClaw mencoba ulang sebagai teks biasa.
|
||||
- HTML mentah dari model di-escape untuk mengurangi kegagalan parse Telegram.
|
||||
- Jika Telegram menolak HTML yang di-parse, OpenClaw mencoba lagi sebagai teks biasa.
|
||||
|
||||
Pratinjau tautan aktif secara default dan dapat dinonaktifkan dengan `channels.telegram.linkPreview: false`.
|
||||
Pratinjau tautan diaktifkan secara default dan dapat dinonaktifkan dengan `channels.telegram.linkPreview: false`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Perintah native dan perintah kustom">
|
||||
Registrasi menu perintah Telegram ditangani saat startup dengan `setMyCommands`.
|
||||
Pendaftaran menu perintah Telegram ditangani saat startup dengan `setMyCommands`.
|
||||
|
||||
Default perintah native:
|
||||
|
||||
@ -326,8 +326,8 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
channels: {
|
||||
telegram: {
|
||||
customCommands: [
|
||||
{ command: "backup", description: "Git backup" },
|
||||
{ command: "generate", description: "Create an image" },
|
||||
{ command: "backup", description: "Cadangan Git" },
|
||||
{ command: "generate", description: "Buat gambar" },
|
||||
],
|
||||
},
|
||||
},
|
||||
@ -339,42 +339,42 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- nama dinormalisasi (hapus `/` di depan, huruf kecil)
|
||||
- pola valid: `a-z`, `0-9`, `_`, panjang `1..32`
|
||||
- perintah kustom tidak dapat menimpa perintah native
|
||||
- konflik/duplikasi dilewati dan dicatat di log
|
||||
- konflik/duplikat dilewati dan dicatat ke log
|
||||
|
||||
Catatan:
|
||||
|
||||
- perintah kustom hanya entri menu; tidak otomatis mengimplementasikan perilaku
|
||||
- perintah plugin/skill tetap dapat berfungsi saat diketik meskipun tidak ditampilkan di menu Telegram
|
||||
- perintah kustom hanyalah entri menu; mereka tidak otomatis mengimplementasikan perilaku
|
||||
- perintah plugin/Skills tetap dapat berfungsi saat diketik meskipun tidak ditampilkan di menu Telegram
|
||||
|
||||
Jika perintah native dinonaktifkan, built-in akan dihapus. Perintah kustom/plugin mungkin tetap terdaftar jika dikonfigurasi.
|
||||
|
||||
Kegagalan penyiapan umum:
|
||||
Kegagalan penyiapan yang umum:
|
||||
|
||||
- `setMyCommands failed` dengan `BOT_COMMANDS_TOO_MUCH` berarti menu Telegram masih meluap setelah dipangkas; kurangi perintah plugin/skill/kustom atau nonaktifkan `channels.telegram.commands.native`.
|
||||
- `setMyCommands failed` dengan kesalahan jaringan/fetch biasanya berarti DNS/HTTPS outbound ke `api.telegram.org` diblokir.
|
||||
- `setMyCommands failed` dengan `BOT_COMMANDS_TOO_MUCH` berarti menu Telegram tetap meluap setelah dipangkas; kurangi perintah plugin/Skills/kustom atau nonaktifkan `channels.telegram.commands.native`.
|
||||
- `setMyCommands failed` dengan error jaringan/fetch biasanya berarti DNS/HTTPS keluar ke `api.telegram.org` diblokir.
|
||||
|
||||
### Perintah pairing perangkat (plugin `device-pair`)
|
||||
### Perintah pemasangan perangkat (plugin `device-pair`)
|
||||
|
||||
Saat plugin `device-pair` terpasang:
|
||||
|
||||
1. `/pair` menghasilkan kode penyiapan
|
||||
2. tempelkan kode di aplikasi iOS
|
||||
3. `/pair pending` mencantumkan permintaan yang tertunda (termasuk role/scopes)
|
||||
4. setujui permintaannya:
|
||||
2. tempel kode di aplikasi iOS
|
||||
3. `/pair pending` menampilkan permintaan yang tertunda (termasuk peran/scope)
|
||||
4. setujui permintaan:
|
||||
- `/pair approve <requestId>` untuk persetujuan eksplisit
|
||||
- `/pair approve` saat hanya ada satu permintaan tertunda
|
||||
- `/pair approve` saat hanya ada satu permintaan yang tertunda
|
||||
- `/pair approve latest` untuk yang paling baru
|
||||
|
||||
Kode penyiapan membawa token bootstrap berumur pendek. Built-in bootstrap handoff menjaga token node utama pada `scopes: []`; token operator apa pun yang diserahkan tetap dibatasi pada `operator.approvals`, `operator.read`, `operator.talk.secrets`, dan `operator.write`. Pemeriksaan scope bootstrap berawalan role, sehingga allowlist operator tersebut hanya memenuhi permintaan operator; role non-operator tetap memerlukan scope di bawah prefiks role mereka sendiri.
|
||||
Kode penyiapan membawa token bootstrap berumur pendek. Built-in bootstrap handoff menjaga token Node utama tetap pada `scopes: []`; token operator yang diserahkan tetap dibatasi pada `operator.approvals`, `operator.read`, `operator.talk.secrets`, dan `operator.write`. Pemeriksaan scope bootstrap menggunakan awalan peran, sehingga allowlist operator tersebut hanya memenuhi permintaan operator; peran non-operator tetap memerlukan scope di bawah awalan perannya sendiri.
|
||||
|
||||
Jika perangkat mencoba lagi dengan detail auth yang berubah (misalnya role/scopes/public key), permintaan tertunda sebelumnya akan digantikan dan permintaan baru menggunakan `requestId` yang berbeda. Jalankan kembali `/pair pending` sebelum menyetujui.
|
||||
Jika sebuah perangkat mencoba lagi dengan detail auth yang berubah (misalnya peran/scope/kunci publik), permintaan tertunda sebelumnya akan digantikan dan permintaan baru menggunakan `requestId` yang berbeda. Jalankan kembali `/pair pending` sebelum menyetujui.
|
||||
|
||||
Detail selengkapnya: [Pairing](/id/channels/pairing#pair-via-telegram-recommended-for-ios).
|
||||
Detail lebih lanjut: [Pemasangan](/id/channels/pairing#pair-via-telegram-recommended-for-ios).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Tombol inline">
|
||||
Konfigurasikan cakupan keyboard inline:
|
||||
Konfigurasikan scope keyboard inline:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -406,7 +406,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Cakupan:
|
||||
Scope:
|
||||
|
||||
- `off`
|
||||
- `dm`
|
||||
@ -414,7 +414,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `all`
|
||||
- `allowlist` (default)
|
||||
|
||||
`capabilities: ["inlineButtons"]` lama dipetakan ke `inlineButtons: "all"`.
|
||||
Legacy `capabilities: ["inlineButtons"]` dipetakan ke `inlineButtons: "all"`.
|
||||
|
||||
Contoh aksi pesan:
|
||||
|
||||
@ -423,23 +423,23 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
action: "send",
|
||||
channel: "telegram",
|
||||
to: "123456789",
|
||||
message: "Choose an option:",
|
||||
message: "Pilih satu opsi:",
|
||||
buttons: [
|
||||
[
|
||||
{ text: "Yes", callback_data: "yes" },
|
||||
{ text: "No", callback_data: "no" },
|
||||
{ text: "Ya", callback_data: "yes" },
|
||||
{ text: "Tidak", callback_data: "no" },
|
||||
],
|
||||
[{ text: "Cancel", callback_data: "cancel" }],
|
||||
[{ text: "Batal", callback_data: "cancel" }],
|
||||
],
|
||||
}
|
||||
```
|
||||
|
||||
Klik callback diteruskan ke agent sebagai teks:
|
||||
Klik callback diteruskan ke agen sebagai teks:
|
||||
`callback_data: <value>`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Aksi pesan Telegram untuk agent dan otomatisasi">
|
||||
<Accordion title="Aksi pesan Telegram untuk agen dan otomasi">
|
||||
Aksi tool Telegram meliputi:
|
||||
|
||||
- `sendMessage` (`to`, `content`, opsional `mediaUrl`, `replyToMessageId`, `messageThreadId`)
|
||||
@ -448,44 +448,44 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `editMessage` (`chatId`, `messageId`, `content`)
|
||||
- `createForumTopic` (`chatId`, `name`, opsional `iconColor`, `iconCustomEmojiId`)
|
||||
|
||||
Aksi pesan channel menyediakan alias ergonomis (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).
|
||||
Aksi pesan channel menyediakan alias yang ergonomis (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).
|
||||
|
||||
Kontrol gating:
|
||||
|
||||
- `channels.telegram.actions.sendMessage`
|
||||
- `channels.telegram.actions.deleteMessage`
|
||||
- `channels.telegram.actions.reactions`
|
||||
- `channels.telegram.actions.sticker` (default: dinonaktifkan)
|
||||
- `channels.telegram.actions.sticker` (default: disabled)
|
||||
|
||||
Catatan: `edit` dan `topic-create` saat ini diaktifkan secara default dan tidak memiliki toggle `channels.telegram.actions.*` terpisah.
|
||||
Pengiriman runtime menggunakan snapshot config/secret yang aktif (startup/reload), sehingga jalur aksi tidak melakukan resolusi ulang SecretRef ad-hoc untuk setiap pengiriman.
|
||||
Pengiriman runtime menggunakan snapshot config/secret yang aktif (startup/reload), sehingga jalur aksi tidak melakukan resolusi ulang SecretRef ad-hoc per pengiriman.
|
||||
|
||||
Semantik penghapusan reaction: [/tools/reactions](/tools/reactions)
|
||||
Semantik penghapusan reaction: [/tools/reactions](/id/tools/reactions)
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Tag reply threading">
|
||||
Telegram mendukung tag reply threading eksplisit dalam output yang dihasilkan:
|
||||
<Accordion title="Tag threading balasan">
|
||||
Telegram mendukung tag threading balasan eksplisit dalam output yang dihasilkan:
|
||||
|
||||
- `[[reply_to_current]]` membalas pesan yang memicu
|
||||
- `[[reply_to:<id>]]` membalas ID pesan Telegram tertentu
|
||||
|
||||
`channels.telegram.replyToMode` mengontrol penanganannya:
|
||||
`channels.telegram.replyToMode` mengontrol penanganan:
|
||||
|
||||
- `off` (default)
|
||||
- `first`
|
||||
- `all`
|
||||
|
||||
Catatan: `off` menonaktifkan reply threading implisit. Tag `[[reply_to_*]]` eksplisit tetap dihormati.
|
||||
Catatan: `off` menonaktifkan threading balasan implisit. Tag `[[reply_to_*]]` yang eksplisit tetap dipatuhi.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Topik forum dan perilaku thread">
|
||||
Supergroup forum:
|
||||
Supergrup forum:
|
||||
|
||||
- kunci sesi topik menambahkan `:topic:<threadId>`
|
||||
- balasan dan typing menargetkan thread topik
|
||||
- jalur config topik:
|
||||
- balasan dan indikator mengetik menargetkan thread topik
|
||||
- path config topik:
|
||||
`channels.telegram.groups.<chatId>.topics.<threadId>`
|
||||
|
||||
Kasus khusus topik umum (`threadId=1`):
|
||||
@ -494,9 +494,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- aksi mengetik tetap menyertakan `message_thread_id`
|
||||
|
||||
Pewarisan topik: entri topik mewarisi pengaturan grup kecuali dioverride (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
|
||||
`agentId` hanya untuk topik dan tidak mewarisi dari default grup.
|
||||
`agentId` khusus topik dan tidak mewarisi dari default grup.
|
||||
|
||||
**Routing agent per-topik**: Setiap topik dapat dirutekan ke agent yang berbeda dengan menetapkan `agentId` di config topik. Ini memberi setiap topik workspace, memori, dan sesi terisolasi sendiri. Contoh:
|
||||
**Routing agen per topik**: Setiap topik dapat merutekan ke agen yang berbeda dengan mengatur `agentId` di config topik. Ini memberi setiap topik workspace, memori, dan sesi terisolasi sendiri. Contoh:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -505,9 +505,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
groups: {
|
||||
"-1001234567890": {
|
||||
topics: {
|
||||
"1": { agentId: "main" }, // Topik umum → agent utama
|
||||
"3": { agentId: "zu" }, // Topik dev → agent zu
|
||||
"5": { agentId: "coder" } // Review kode → agent coder
|
||||
"1": { agentId: "main" }, // Topik umum → agen utama
|
||||
"3": { agentId: "zu" }, // Topik dev → agen zu
|
||||
"5": { agentId: "coder" } // Tinjauan kode → agen coder
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -516,7 +516,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Setiap topik kemudian memiliki kunci sesi sendiri: `agent:zu:telegram:group:-1001234567890:topic:3`
|
||||
Setiap topik lalu memiliki kunci sesinya sendiri: `agent:zu:telegram:group:-1001234567890:topic:3`
|
||||
|
||||
**Binding topik ACP persisten**: Topik forum dapat menyematkan sesi harness ACP melalui binding ACP bertipe tingkat atas:
|
||||
|
||||
@ -569,33 +569,33 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Ini saat ini dibatasi untuk topik forum di grup dan supergroup.
|
||||
Ini saat ini dibatasi pada topik forum di grup dan supergrup.
|
||||
|
||||
**Spawn ACP terikat thread dari chat**:
|
||||
**Spawn ACP yang terikat thread dari chat**:
|
||||
|
||||
- `/acp spawn <agent> --thread here|auto` dapat membinding topik Telegram saat ini ke sesi ACP baru.
|
||||
- `/acp spawn <agent> --thread here|auto` dapat mengikat topik Telegram saat ini ke sesi ACP baru.
|
||||
- Pesan topik lanjutan dirutekan langsung ke sesi ACP yang terikat (tidak perlu `/acp steer`).
|
||||
- OpenClaw menyematkan pesan konfirmasi spawn di dalam topik setelah binding berhasil.
|
||||
- Memerlukan `channels.telegram.threadBindings.spawnAcpSessions=true`.
|
||||
|
||||
Konteks template meliputi:
|
||||
Konteks template mencakup:
|
||||
|
||||
- `MessageThreadId`
|
||||
- `IsForum`
|
||||
|
||||
Perilaku thread DM:
|
||||
|
||||
- chat privat dengan `message_thread_id` tetap menggunakan routing DM tetapi memakai kunci sesi/target balasan yang sadar thread.
|
||||
- chat privat dengan `message_thread_id` tetap menggunakan routing DM tetapi memakai kunci sesi/target balasan yang sadar-thread.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Audio, video, dan stiker">
|
||||
### Pesan audio
|
||||
|
||||
Telegram membedakan voice note dan file audio.
|
||||
Telegram membedakan catatan suara dan file audio.
|
||||
|
||||
- default: perilaku file audio
|
||||
- tag `[[audio_as_voice]]` di balasan agent untuk memaksa pengiriman sebagai voice note
|
||||
- tag `[[audio_as_voice]]` dalam balasan agen untuk memaksa pengiriman sebagai catatan suara
|
||||
|
||||
Contoh aksi pesan:
|
||||
|
||||
@ -625,11 +625,11 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Video note tidak mendukung caption; teks pesan yang diberikan dikirim secara terpisah.
|
||||
Video note tidak mendukung caption; teks pesan yang diberikan dikirim terpisah.
|
||||
|
||||
### Stiker
|
||||
|
||||
Penanganan stiker inbound:
|
||||
Penanganan stiker masuk:
|
||||
|
||||
- WEBP statis: diunduh dan diproses (placeholder `<media:sticker>`)
|
||||
- TGS animasi: dilewati
|
||||
@ -647,7 +647,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- `~/.openclaw/telegram/sticker-cache.json`
|
||||
|
||||
Stiker dideskripsikan sekali (jika memungkinkan) dan di-cache untuk mengurangi panggilan vision berulang.
|
||||
Stiker dideskripsikan sekali (saat memungkinkan) dan di-cache untuk mengurangi panggilan vision berulang.
|
||||
|
||||
Aktifkan aksi stiker:
|
||||
|
||||
@ -680,7 +680,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
{
|
||||
action: "sticker-search",
|
||||
channel: "telegram",
|
||||
query: "cat waving",
|
||||
query: "kucing melambai",
|
||||
limit: 5,
|
||||
}
|
||||
```
|
||||
@ -690,7 +690,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
<Accordion title="Notifikasi reaction">
|
||||
Reaction Telegram datang sebagai update `message_reaction` (terpisah dari payload pesan).
|
||||
|
||||
Saat diaktifkan, OpenClaw mengantrikan event sistem seperti:
|
||||
Saat diaktifkan, OpenClaw memasukkan event sistem seperti:
|
||||
|
||||
- `Telegram reaction added: 👍 by Alice (@alice) on msg 42`
|
||||
|
||||
@ -701,30 +701,30 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Catatan:
|
||||
|
||||
- `own` berarti hanya reaction pengguna terhadap pesan yang dikirim bot (best-effort melalui cache pesan terkirim).
|
||||
- Event reaction tetap mematuhi kontrol akses Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); pengirim yang tidak diotorisasi dibuang.
|
||||
- `own` berarti hanya reaction pengguna pada pesan yang dikirim bot (best-effort melalui cache pesan terkirim).
|
||||
- Event reaction tetap mematuhi kontrol akses Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); pengirim yang tidak berwenang akan dibuang.
|
||||
- Telegram tidak menyediakan ID thread dalam update reaction.
|
||||
- grup non-forum dirutekan ke sesi chat grup
|
||||
- grup forum dirutekan ke sesi topik umum grup (`:topic:1`), bukan ke topik asal yang tepat
|
||||
|
||||
`allowed_updates` untuk polling/webhook otomatis menyertakan `message_reaction`.
|
||||
`allowed_updates` untuk polling/webhook otomatis mencakup `message_reaction`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Reaction ack">
|
||||
`ackReaction` mengirim emoji pengakuan saat OpenClaw sedang memproses pesan inbound.
|
||||
`ackReaction` mengirim emoji pengakuan saat OpenClaw sedang memproses pesan masuk.
|
||||
|
||||
Urutan resolusi:
|
||||
|
||||
- `channels.telegram.accounts.<accountId>.ackReaction`
|
||||
- `channels.telegram.ackReaction`
|
||||
- `messages.ackReaction`
|
||||
- fallback emoji identitas agent (`agents.list[].identity.emoji`, jika tidak "👀")
|
||||
- fallback emoji identitas agen (`agents.list[].identity.emoji`, atau "👀")
|
||||
|
||||
Catatan:
|
||||
|
||||
- Telegram mengharapkan emoji unicode (misalnya "👀").
|
||||
- Gunakan `""` untuk menonaktifkan reaction bagi suatu channel atau akun.
|
||||
- Gunakan `""` untuk menonaktifkan reaction untuk sebuah channel atau akun.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -734,7 +734,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
Penulisan yang dipicu Telegram meliputi:
|
||||
|
||||
- event migrasi grup (`migrate_to_chat_id`) untuk memperbarui `channels.telegram.groups`
|
||||
- `/config set` dan `/config unset` (memerlukan enablement perintah)
|
||||
- `/config set` dan `/config unset` (memerlukan pengaktifan perintah)
|
||||
|
||||
Nonaktifkan:
|
||||
|
||||
@ -756,32 +756,32 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
Mode webhook:
|
||||
|
||||
- atur `channels.telegram.webhookUrl`
|
||||
- atur `channels.telegram.webhookSecret` (wajib saat webhook URL diatur)
|
||||
- atur `channels.telegram.webhookSecret` (wajib saat URL webhook diatur)
|
||||
- opsional `channels.telegram.webhookPath` (default `/telegram-webhook`)
|
||||
- opsional `channels.telegram.webhookHost` (default `127.0.0.1`)
|
||||
- opsional `channels.telegram.webhookPort` (default `8787`)
|
||||
|
||||
Listener lokal default untuk mode webhook bind ke `127.0.0.1:8787`.
|
||||
Listener lokal default untuk mode webhook melakukan bind ke `127.0.0.1:8787`.
|
||||
|
||||
Jika endpoint publik Anda berbeda, tempatkan reverse proxy di depan dan arahkan `webhookUrl` ke URL publik.
|
||||
Atur `webhookHost` (misalnya `0.0.0.0`) saat Anda memang membutuhkan ingress eksternal.
|
||||
Jika endpoint publik Anda berbeda, tempatkan reverse proxy di depannya dan arahkan `webhookUrl` ke URL publik tersebut.
|
||||
Atur `webhookHost` (misalnya `0.0.0.0`) saat Anda memang memerlukan ingress eksternal.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Batas, retry, dan target CLI">
|
||||
- default `channels.telegram.textChunkLimit` adalah 4000.
|
||||
- `channels.telegram.chunkMode="newline"` lebih memilih batas paragraf (baris kosong) sebelum pemisahan berdasarkan panjang.
|
||||
- `channels.telegram.mediaMaxMb` (default 100) membatasi ukuran media Telegram inbound dan outbound.
|
||||
- `channels.telegram.chunkMode="newline"` mengutamakan batas paragraf (baris kosong) sebelum pemotongan berdasarkan panjang.
|
||||
- `channels.telegram.mediaMaxMb` (default 100) membatasi ukuran media Telegram masuk dan keluar.
|
||||
- `channels.telegram.timeoutSeconds` menimpa timeout klien API Telegram (jika tidak diatur, default grammY berlaku).
|
||||
- riwayat konteks grup menggunakan `channels.telegram.historyLimit` atau `messages.groupChat.historyLimit` (default 50); `0` menonaktifkan.
|
||||
- konteks tambahan reply/quote/forward saat ini diteruskan sebagaimana diterima.
|
||||
- allowlist Telegram terutama membatasi siapa yang dapat memicu agent, bukan batas penyuntingan penuh untuk konteks tambahan.
|
||||
- allowlist Telegram terutama membatasi siapa yang dapat memicu agen, bukan batas redaksi konteks tambahan yang sepenuhnya.
|
||||
- kontrol riwayat DM:
|
||||
- `channels.telegram.dmHistoryLimit`
|
||||
- `channels.telegram.dms["<user_id>"].historyLimit`
|
||||
- config `channels.telegram.retry` berlaku untuk helper pengiriman Telegram (CLI/tools/actions) pada kesalahan API outbound yang dapat dipulihkan.
|
||||
- config `channels.telegram.retry` berlaku untuk helper pengiriman Telegram (CLI/tools/actions) untuk error API keluar yang dapat dipulihkan.
|
||||
|
||||
Target pengiriman CLI dapat berupa ID chat numerik atau username:
|
||||
Target kirim CLI dapat berupa ID chat numerik atau username:
|
||||
|
||||
```bash
|
||||
openclaw message send --channel telegram --target 123456789 --message "hi"
|
||||
@ -808,69 +808,69 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
Pengiriman Telegram juga mendukung:
|
||||
|
||||
- `--buttons` untuk keyboard inline saat `channels.telegram.capabilities.inlineButtons` mengizinkannya
|
||||
- `--force-document` untuk mengirim gambar dan GIF outbound sebagai dokumen alih-alih unggahan foto terkompresi atau media animasi
|
||||
- `--force-document` untuk mengirim gambar dan GIF keluar sebagai dokumen alih-alih unggahan foto terkompresi atau media animasi
|
||||
|
||||
Gating aksi:
|
||||
|
||||
- `channels.telegram.actions.sendMessage=false` menonaktifkan pesan Telegram outbound, termasuk poll
|
||||
- `channels.telegram.actions.poll=false` menonaktifkan pembuatan poll Telegram sambil tetap membiarkan pengiriman reguler aktif
|
||||
- `channels.telegram.actions.sendMessage=false` menonaktifkan pesan Telegram keluar, termasuk poll
|
||||
- `channels.telegram.actions.poll=false` menonaktifkan pembuatan poll Telegram sambil tetap membiarkan pengiriman biasa aktif
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Persetujuan exec di Telegram">
|
||||
Telegram mendukung persetujuan exec di DM approver dan secara opsional dapat memposting prompt persetujuan di chat atau topik asal.
|
||||
|
||||
Jalur config:
|
||||
Path config:
|
||||
|
||||
- `channels.telegram.execApprovals.enabled`
|
||||
- `channels.telegram.execApprovals.approvers` (opsional; fallback ke ID pemilik numerik yang diinferensikan dari `allowFrom` dan `defaultTo` langsung jika memungkinkan)
|
||||
- `channels.telegram.execApprovals.approvers` (opsional; menggunakan fallback ke ID pemilik numerik yang disimpulkan dari `allowFrom` dan `defaultTo` pesan langsung bila memungkinkan)
|
||||
- `channels.telegram.execApprovals.target` (`dm` | `channel` | `both`, default: `dm`)
|
||||
- `agentFilter`, `sessionFilter`
|
||||
|
||||
Approver harus berupa ID pengguna Telegram numerik. Telegram otomatis mengaktifkan persetujuan exec native ketika `enabled` tidak diatur atau `"auto"` dan setidaknya satu approver dapat diresolusikan, baik dari `execApprovals.approvers` maupun dari config pemilik numerik akun (`allowFrom` dan `defaultTo` direct-message). Atur `enabled: false` untuk menonaktifkan Telegram sebagai klien persetujuan native secara eksplisit. Jika tidak, permintaan persetujuan akan fallback ke rute persetujuan terkonfigurasi lainnya atau kebijakan fallback persetujuan exec.
|
||||
Approver harus berupa ID pengguna Telegram numerik. Telegram secara otomatis mengaktifkan persetujuan exec native saat `enabled` tidak diatur atau `"auto"` dan setidaknya satu approver dapat di-resolve, baik dari `execApprovals.approvers` maupun dari config pemilik numerik akun (`allowFrom` dan `defaultTo` pesan langsung). Atur `enabled: false` untuk menonaktifkan Telegram sebagai klien persetujuan native secara eksplisit. Jika tidak, permintaan persetujuan akan menggunakan fallback ke rute persetujuan lain yang dikonfigurasi atau kebijakan fallback persetujuan exec.
|
||||
|
||||
Telegram juga merender tombol persetujuan bersama yang digunakan oleh channel chat lain. Adapter Telegram native terutama menambahkan routing DM approver, fanout channel/topik, dan petunjuk mengetik sebelum pengiriman.
|
||||
Saat tombol tersebut ada, itulah UX persetujuan utama; OpenClaw
|
||||
seharusnya hanya menyertakan perintah `/approve` manual ketika hasil tool menyatakan
|
||||
hanya boleh menyertakan perintah manual `/approve` saat hasil tool menyatakan
|
||||
persetujuan chat tidak tersedia atau persetujuan manual adalah satu-satunya jalur.
|
||||
|
||||
Aturan pengiriman:
|
||||
|
||||
- `target: "dm"` hanya mengirim prompt persetujuan ke DM approver yang teresolusikan
|
||||
- `target: "dm"` mengirim prompt persetujuan hanya ke DM approver yang di-resolve
|
||||
- `target: "channel"` mengirim prompt kembali ke chat/topik Telegram asal
|
||||
- `target: "both"` mengirim ke DM approver dan chat/topik asal
|
||||
|
||||
Hanya approver yang teresolusikan yang dapat menyetujui atau menolak. Non-approver tidak dapat menggunakan `/approve` dan tidak dapat menggunakan tombol persetujuan Telegram.
|
||||
Hanya approver yang di-resolve yang dapat menyetujui atau menolak. Non-approver tidak dapat menggunakan `/approve` dan tidak dapat menggunakan tombol persetujuan Telegram.
|
||||
|
||||
Perilaku resolusi persetujuan:
|
||||
|
||||
- ID berprefiks `plugin:` selalu diresolusikan melalui persetujuan plugin.
|
||||
- ID persetujuan lainnya mencoba `exec.approval.resolve` terlebih dahulu.
|
||||
- Jika Telegram juga diotorisasi untuk persetujuan plugin dan gateway mengatakan
|
||||
persetujuan exec tidak dikenal/kedaluwarsa, Telegram mencoba ulang satu kali melalui
|
||||
- ID dengan awalan `plugin:` selalu di-resolve melalui persetujuan plugin.
|
||||
- ID persetujuan lain mencoba `exec.approval.resolve` terlebih dahulu.
|
||||
- Jika Telegram juga diotorisasi untuk persetujuan plugin dan gateway menyatakan
|
||||
persetujuan exec tidak dikenal/kedaluwarsa, Telegram mencoba lagi sekali melalui
|
||||
`plugin.approval.resolve`.
|
||||
- Penolakan/kesalahan persetujuan exec yang nyata tidak diam-diam diteruskan ke resolusi
|
||||
- Penolakan/error persetujuan exec yang nyata tidak diam-diam dialihkan ke resolusi
|
||||
persetujuan plugin.
|
||||
|
||||
Pengiriman channel menampilkan teks perintah di chat, jadi aktifkan `channel` atau `both` hanya di grup/topik tepercaya. Saat prompt mendarat di topik forum, OpenClaw mempertahankan topik tersebut baik untuk prompt persetujuan maupun tindak lanjut pasca-persetujuan. Persetujuan exec kedaluwarsa setelah 30 menit secara default.
|
||||
Pengiriman ke channel menampilkan teks perintah di chat, jadi aktifkan `channel` atau `both` hanya di grup/topik tepercaya. Saat prompt masuk ke topik forum, OpenClaw mempertahankan topik tersebut baik untuk prompt persetujuan maupun tindak lanjut pasca-persetujuan. Persetujuan exec kedaluwarsa setelah 30 menit secara default.
|
||||
|
||||
Tombol persetujuan inline juga bergantung pada `channels.telegram.capabilities.inlineButtons` yang mengizinkan permukaan target (`dm`, `group`, atau `all`).
|
||||
|
||||
Dokumentasi terkait: [Persetujuan exec](/tools/exec-approvals)
|
||||
Dokumen terkait: [Persetujuan exec](/id/tools/exec-approvals)
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Kontrol balasan error
|
||||
|
||||
Saat agent mengalami error pengiriman atau provider, Telegram dapat membalas dengan teks error tersebut atau menekannya. Dua kunci config mengontrol perilaku ini:
|
||||
Saat agen mengalami error pengiriman atau provider, Telegram dapat membalas dengan teks error atau menekannya. Dua kunci config mengontrol perilaku ini:
|
||||
|
||||
| Key | Values | Default | Description |
|
||||
| ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- |
|
||||
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` mengirim pesan error yang ramah ke chat. `silent` sepenuhnya menekan balasan error. |
|
||||
| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Waktu minimum antar balasan error ke chat yang sama. Mencegah spam error selama gangguan. |
|
||||
| Key | Nilai | Default | Deskripsi |
|
||||
| ----------------------------------- | ----------------- | ------- | ------------------------------------------------------------------------------------------------ |
|
||||
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` mengirim pesan error yang ramah ke chat. `silent` menekan balasan error sepenuhnya. |
|
||||
| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Waktu minimum antar balasan error ke chat yang sama. Mencegah spam error saat terjadi gangguan. |
|
||||
|
||||
Override per-akun, per-grup, dan per-topik didukung (pewarisan yang sama seperti kunci config Telegram lainnya).
|
||||
Override per akun, per grup, dan per topik didukung (pewarisan yang sama seperti key config Telegram lainnya).
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -894,37 +894,37 @@ Override per-akun, per-grup, dan per-topik didukung (pewarisan yang sama seperti
|
||||
<Accordion title="Bot tidak merespons pesan grup tanpa mention">
|
||||
|
||||
- Jika `requireMention=false`, mode privasi Telegram harus mengizinkan visibilitas penuh.
|
||||
- BotFather: `/setprivacy` -> Disable
|
||||
- lalu keluarkan + tambahkan kembali bot ke grup
|
||||
- BotFather: `/setprivacy` -> Nonaktifkan
|
||||
- lalu hapus + tambahkan kembali bot ke grup
|
||||
- `openclaw channels status` memberi peringatan saat config mengharapkan pesan grup tanpa mention.
|
||||
- `openclaw channels status --probe` dapat memeriksa ID grup numerik eksplisit; wildcard `"*"` tidak dapat diperiksa keanggotaannya.
|
||||
- tes sesi cepat: `/activation always`.
|
||||
- uji sesi cepat: `/activation always`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Bot sama sekali tidak melihat pesan grup">
|
||||
|
||||
- saat `channels.telegram.groups` ada, grup harus tercantum (atau menyertakan `"*"`)
|
||||
- saat `channels.telegram.groups` ada, grup harus terdaftar (atau menyertakan `"*"`)
|
||||
- verifikasi keanggotaan bot di grup
|
||||
- tinjau log: `openclaw logs --follow` untuk alasan dilewati
|
||||
- tinjau log: `openclaw logs --follow` untuk alasan skip
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Perintah hanya sebagian berfungsi atau tidak berfungsi sama sekali">
|
||||
<Accordion title="Perintah bekerja sebagian atau tidak sama sekali">
|
||||
|
||||
- otorisasi identitas pengirim Anda (pairing dan/atau `allowFrom` numerik)
|
||||
- otorisasi perintah tetap berlaku meskipun kebijakan grup adalah `open`
|
||||
- `setMyCommands failed` dengan `BOT_COMMANDS_TOO_MUCH` berarti menu native memiliki terlalu banyak entri; kurangi perintah plugin/skill/kustom atau nonaktifkan menu native
|
||||
- `setMyCommands failed` dengan kesalahan jaringan/fetch biasanya menunjukkan masalah keterjangkauan DNS/HTTPS ke `api.telegram.org`
|
||||
- `setMyCommands failed` dengan `BOT_COMMANDS_TOO_MUCH` berarti menu native memiliki terlalu banyak entri; kurangi perintah plugin/Skills/kustom atau nonaktifkan menu native
|
||||
- `setMyCommands failed` dengan error jaringan/fetch biasanya menunjukkan masalah keterjangkauan DNS/HTTPS ke `api.telegram.org`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Polling atau ketidakstabilan jaringan">
|
||||
|
||||
- Node 22+ + fetch/proxy kustom dapat memicu perilaku abort langsung jika tipe AbortSignal tidak cocok.
|
||||
- Beberapa host meresolusikan `api.telegram.org` ke IPv6 terlebih dahulu; egress IPv6 yang rusak dapat menyebabkan kegagalan API Telegram yang intermiten.
|
||||
- Jika log menyertakan `TypeError: fetch failed` atau `Network request for 'getUpdates' failed!`, OpenClaw kini mencoba ulang ini sebagai kesalahan jaringan yang dapat dipulihkan.
|
||||
- Pada host VPS dengan egress/TLS langsung yang tidak stabil, rute panggilan API Telegram melalui `channels.telegram.proxy`:
|
||||
- Beberapa host me-resolve `api.telegram.org` ke IPv6 terlebih dahulu; egress IPv6 yang rusak dapat menyebabkan kegagalan API Telegram yang intermiten.
|
||||
- Jika log menyertakan `TypeError: fetch failed` atau `Network request for 'getUpdates' failed!`, OpenClaw kini mencoba ulang error ini sebagai error jaringan yang dapat dipulihkan.
|
||||
- Pada host VPS dengan egress/TLS langsung yang tidak stabil, arahkan panggilan API Telegram melalui `channels.telegram.proxy`:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -932,8 +932,8 @@ channels:
|
||||
proxy: socks5://<user>:<password>@proxy-host:1080
|
||||
```
|
||||
|
||||
- Default Node 22+ adalah `autoSelectFamily=true` (kecuali WSL2) dan `dnsResultOrder=ipv4first`.
|
||||
- Jika host Anda adalah WSL2 atau memang bekerja lebih baik dengan perilaku hanya-IPv4, paksa pemilihan family:
|
||||
- Node 22+ default ke `autoSelectFamily=true` (kecuali WSL2) dan `dnsResultOrder=ipv4first`.
|
||||
- Jika host Anda adalah WSL2 atau secara eksplisit bekerja lebih baik dengan perilaku khusus IPv4, paksa pemilihan family:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -943,10 +943,10 @@ channels:
|
||||
```
|
||||
|
||||
- Jawaban rentang benchmark RFC 2544 (`198.18.0.0/15`) sudah diizinkan
|
||||
untuk unduhan media Telegram secara default. Jika proxy IP palsu atau
|
||||
transparan tepercaya menulis ulang `api.telegram.org` ke alamat
|
||||
private/internal/special-use lain saat unduhan media, Anda dapat memilih
|
||||
bypass khusus Telegram berikut:
|
||||
untuk unduhan media Telegram secara default. Jika fake-IP tepercaya atau
|
||||
proxy transparan menulis ulang `api.telegram.org` ke alamat
|
||||
private/internal/special-use lain selama unduhan media, Anda dapat memilih
|
||||
bypass khusus Telegram ini:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -955,14 +955,14 @@ channels:
|
||||
dangerouslyAllowPrivateNetwork: true
|
||||
```
|
||||
|
||||
- Opsi ikut serta yang sama juga tersedia per akun di
|
||||
- Opsi yang sama juga tersedia per akun di
|
||||
`channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork`.
|
||||
- Jika proxy Anda meresolusikan host media Telegram ke `198.18.x.x`, biarkan
|
||||
flag berbahaya itu nonaktif terlebih dahulu. Media Telegram sudah mengizinkan rentang benchmark RFC 2544
|
||||
- Jika proxy Anda me-resolve host media Telegram ke `198.18.x.x`, biarkan
|
||||
flag dangerous tetap nonaktif terlebih dahulu. Media Telegram sudah mengizinkan rentang benchmark RFC 2544
|
||||
secara default.
|
||||
|
||||
<Warning>
|
||||
`channels.telegram.network.dangerouslyAllowPrivateNetwork` melemahkan perlindungan SSRF media Telegram. Gunakan hanya untuk lingkungan proxy tepercaya yang dikendalikan operator seperti routing fake-IP Clash, Mihomo, atau Surge ketika mereka mensintesis jawaban private atau special-use di luar rentang benchmark RFC 2544 default. Biarkan tetap nonaktif untuk akses Telegram internet publik normal.
|
||||
`channels.telegram.network.dangerouslyAllowPrivateNetwork` melemahkan perlindungan SSRF media Telegram. Gunakan hanya untuk lingkungan proxy tepercaya yang dikendalikan operator seperti Clash, Mihomo, atau routing fake-IP Surge saat mereka mensintesis jawaban private atau special-use di luar rentang benchmark RFC 2544. Biarkan nonaktif untuk akses Telegram internet publik normal.
|
||||
</Warning>
|
||||
|
||||
- Override environment (sementara):
|
||||
@ -987,71 +987,71 @@ Referensi utama:
|
||||
|
||||
- `channels.telegram.enabled`: aktifkan/nonaktifkan startup channel.
|
||||
- `channels.telegram.botToken`: token bot (BotFather).
|
||||
- `channels.telegram.tokenFile`: baca token dari path file reguler. Symlink ditolak.
|
||||
- `channels.telegram.tokenFile`: baca token dari path file biasa. Symlink ditolak.
|
||||
- `channels.telegram.dmPolicy`: `pairing | allowlist | open | disabled` (default: pairing).
|
||||
- `channels.telegram.allowFrom`: allowlist DM (ID pengguna Telegram numerik). `allowlist` memerlukan setidaknya satu ID pengirim. `open` mengharuskan `"*"`. `openclaw doctor --fix` dapat meresolusikan entri `@username` lama ke ID dan dapat memulihkan entri allowlist dari file pairing-store dalam alur migrasi allowlist.
|
||||
- `channels.telegram.actions.poll`: aktifkan atau nonaktifkan pembuatan poll Telegram (default: aktif; tetap memerlukan `sendMessage`).
|
||||
- `channels.telegram.defaultTo`: target Telegram default yang digunakan CLI `--deliver` ketika tidak ada `--reply-to` eksplisit.
|
||||
- `channels.telegram.allowFrom`: allowlist DM (ID pengguna Telegram numerik). `allowlist` memerlukan setidaknya satu ID pengirim. `open` memerlukan `"*"`. `openclaw doctor --fix` dapat me-resolve entri legacy `@username` ke ID dan dapat memulihkan entri allowlist dari file pairing-store dalam alur migrasi allowlist.
|
||||
- `channels.telegram.actions.poll`: aktifkan atau nonaktifkan pembuatan poll Telegram (default: enabled; tetap memerlukan `sendMessage`).
|
||||
- `channels.telegram.defaultTo`: target Telegram default yang digunakan oleh CLI `--deliver` saat tidak ada `--reply-to` eksplisit.
|
||||
- `channels.telegram.groupPolicy`: `open | allowlist | disabled` (default: allowlist).
|
||||
- `channels.telegram.groupAllowFrom`: allowlist pengirim grup (ID pengguna Telegram numerik). `openclaw doctor --fix` dapat meresolusikan entri `@username` lama ke ID. Entri non-numerik diabaikan saat auth. Auth grup tidak menggunakan fallback pairing-store DM (`2026.2.25+`).
|
||||
- `channels.telegram.groupAllowFrom`: allowlist pengirim grup (ID pengguna Telegram numerik). `openclaw doctor --fix` dapat me-resolve entri legacy `@username` ke ID. Entri non-numerik diabaikan saat auth. Auth grup tidak menggunakan fallback pairing-store DM (`2026.2.25+`).
|
||||
- Prioritas multi-akun:
|
||||
- Saat dua atau lebih ID akun dikonfigurasi, atur `channels.telegram.defaultAccount` (atau sertakan `channels.telegram.accounts.default`) untuk membuat routing default menjadi eksplisit.
|
||||
- Jika keduanya tidak diatur, OpenClaw fallback ke ID akun pertama yang dinormalisasi dan `openclaw doctor` memberi peringatan.
|
||||
- Saat dua atau lebih ID akun dikonfigurasi, atur `channels.telegram.defaultAccount` (atau sertakan `channels.telegram.accounts.default`) agar routing default eksplisit.
|
||||
- Jika keduanya tidak diatur, OpenClaw menggunakan fallback ke ID akun pertama yang dinormalisasi dan `openclaw doctor` akan memberi peringatan.
|
||||
- `channels.telegram.accounts.default.allowFrom` dan `channels.telegram.accounts.default.groupAllowFrom` hanya berlaku untuk akun `default`.
|
||||
- Akun bernama mewarisi `channels.telegram.allowFrom` dan `channels.telegram.groupAllowFrom` saat nilai tingkat akun tidak diatur.
|
||||
- Akun bernama tidak mewarisi `channels.telegram.accounts.default.allowFrom` / `groupAllowFrom`.
|
||||
- `channels.telegram.groups`: default per-grup + allowlist (gunakan `"*"` untuk default global).
|
||||
- `channels.telegram.groups.<id>.groupPolicy`: override per-grup untuk groupPolicy (`open | allowlist | disabled`).
|
||||
- `channels.telegram.groups`: default per grup + allowlist (gunakan `"*"` untuk default global).
|
||||
- `channels.telegram.groups.<id>.groupPolicy`: override per grup untuk groupPolicy (`open | allowlist | disabled`).
|
||||
- `channels.telegram.groups.<id>.requireMention`: default gating mention.
|
||||
- `channels.telegram.groups.<id>.skills`: filter skill (hilangkan = semua skill, kosong = tidak ada).
|
||||
- `channels.telegram.groups.<id>.allowFrom`: override allowlist pengirim per-grup.
|
||||
- `channels.telegram.groups.<id>.skills`: filter Skills (hilangkan = semua Skills, kosong = tidak ada).
|
||||
- `channels.telegram.groups.<id>.allowFrom`: override allowlist pengirim per grup.
|
||||
- `channels.telegram.groups.<id>.systemPrompt`: system prompt tambahan untuk grup.
|
||||
- `channels.telegram.groups.<id>.enabled`: nonaktifkan grup saat `false`.
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.*`: override per-topik (field grup + `agentId` khusus topik).
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.agentId`: rute topik ini ke agent tertentu (menimpa routing tingkat grup dan binding).
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.groupPolicy`: override per-topik untuk groupPolicy (`open | allowlist | disabled`).
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.requireMention`: override gating mention per-topik.
|
||||
- `bindings[]` tingkat atas dengan `type: "acp"` dan ID topik kanonis `chatId:topic:topicId` di `match.peer.id`: field binding topik ACP persisten (lihat [ACP Agents](/tools/acp-agents#channel-specific-settings)).
|
||||
- `channels.telegram.direct.<id>.topics.<threadId>.agentId`: rute topik DM ke agent tertentu (perilaku sama seperti topik forum).
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.*`: override per topik (field grup + `agentId` khusus topik).
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.agentId`: rutekan topik ini ke agen tertentu (mengoverride routing tingkat grup dan binding).
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.groupPolicy`: override per topik untuk groupPolicy (`open | allowlist | disabled`).
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.requireMention`: override gating mention per topik.
|
||||
- `bindings[]` tingkat atas dengan `type: "acp"` dan ID topik kanonis `chatId:topic:topicId` di `match.peer.id`: field binding topik ACP persisten (lihat [ACP Agents](/id/tools/acp-agents#channel-specific-settings)).
|
||||
- `channels.telegram.direct.<id>.topics.<threadId>.agentId`: rutekan topik DM ke agen tertentu (perilaku sama seperti topik forum).
|
||||
- `channels.telegram.execApprovals.enabled`: aktifkan Telegram sebagai klien persetujuan exec berbasis chat untuk akun ini.
|
||||
- `channels.telegram.execApprovals.approvers`: ID pengguna Telegram yang diizinkan untuk menyetujui atau menolak permintaan exec. Opsional saat `channels.telegram.allowFrom` atau `channels.telegram.defaultTo` langsung sudah mengidentifikasi pemilik.
|
||||
- `channels.telegram.execApprovals.target`: `dm | channel | both` (default: `dm`). `channel` dan `both` mempertahankan topik Telegram asal jika ada.
|
||||
- `channels.telegram.execApprovals.agentFilter`: filter ID agent opsional untuk prompt persetujuan yang diteruskan.
|
||||
- `channels.telegram.execApprovals.target`: `dm | channel | both` (default: `dm`). `channel` dan `both` mempertahankan topik Telegram asal saat ada.
|
||||
- `channels.telegram.execApprovals.agentFilter`: filter ID agen opsional untuk prompt persetujuan yang diteruskan.
|
||||
- `channels.telegram.execApprovals.sessionFilter`: filter kunci sesi opsional (substring atau regex) untuk prompt persetujuan yang diteruskan.
|
||||
- `channels.telegram.accounts.<account>.execApprovals`: override per-akun untuk routing persetujuan exec Telegram dan otorisasi approver.
|
||||
- `channels.telegram.accounts.<account>.execApprovals`: override per akun untuk routing persetujuan exec Telegram dan otorisasi approver.
|
||||
- `channels.telegram.capabilities.inlineButtons`: `off | dm | group | all | allowlist` (default: allowlist).
|
||||
- `channels.telegram.accounts.<account>.capabilities.inlineButtons`: override per-akun.
|
||||
- `channels.telegram.commands.nativeSkills`: aktifkan/nonaktifkan perintah native skills Telegram.
|
||||
- `channels.telegram.accounts.<account>.capabilities.inlineButtons`: override per akun.
|
||||
- `channels.telegram.commands.nativeSkills`: aktifkan/nonaktifkan perintah Skills native Telegram.
|
||||
- `channels.telegram.replyToMode`: `off | first | all` (default: `off`).
|
||||
- `channels.telegram.textChunkLimit`: ukuran potongan outbound (karakter).
|
||||
- `channels.telegram.chunkMode`: `length` (default) atau `newline` untuk memisah pada baris kosong (batas paragraf) sebelum pemotongan berdasarkan panjang.
|
||||
- `channels.telegram.linkPreview`: toggle pratinjau tautan untuk pesan outbound (default: true).
|
||||
- `channels.telegram.streaming`: `off | partial | block | progress` (pratinjau live stream; default: `partial`; `progress` dipetakan ke `partial`; `block` adalah kompatibilitas mode pratinjau lama). Preview streaming Telegram menggunakan satu pesan pratinjau yang diedit di tempat.
|
||||
- `channels.telegram.mediaMaxMb`: batas media Telegram inbound/outbound (MB, default: 100).
|
||||
- `channels.telegram.retry`: kebijakan retry untuk helper pengiriman Telegram (CLI/tools/actions) pada kesalahan API outbound yang dapat dipulihkan (attempts, minDelayMs, maxDelayMs, jitter).
|
||||
- `channels.telegram.network.autoSelectFamily`: timpa autoSelectFamily Node (true=aktifkan, false=nonaktifkan). Default aktif di Node 22+, dengan WSL2 default nonaktif.
|
||||
- `channels.telegram.network.dnsResultOrder`: timpa urutan hasil DNS (`ipv4first` atau `verbatim`). Default `ipv4first` di Node 22+.
|
||||
- `channels.telegram.network.dangerouslyAllowPrivateNetwork`: opsi berbahaya untuk lingkungan fake-IP atau proxy transparan tepercaya di mana unduhan media Telegram meresolusikan `api.telegram.org` ke alamat private/internal/special-use di luar izin rentang benchmark RFC 2544 default.
|
||||
- `channels.telegram.textChunkLimit`: ukuran chunk keluar (karakter).
|
||||
- `channels.telegram.chunkMode`: `length` (default) atau `newline` untuk membagi pada baris kosong (batas paragraf) sebelum chunking berdasarkan panjang.
|
||||
- `channels.telegram.linkPreview`: toggle pratinjau tautan untuk pesan keluar (default: true).
|
||||
- `channels.telegram.streaming`: `off | partial | block | progress` (pratinjau stream langsung; default: `partial`; `progress` dipetakan ke `partial`; `block` adalah kompatibilitas mode pratinjau legacy). Streaming pratinjau Telegram menggunakan satu pesan pratinjau yang diedit di tempat.
|
||||
- `channels.telegram.mediaMaxMb`: batas media Telegram masuk/keluar (MB, default: 100).
|
||||
- `channels.telegram.retry`: kebijakan retry untuk helper pengiriman Telegram (CLI/tools/actions) pada error API keluar yang dapat dipulihkan (attempts, minDelayMs, maxDelayMs, jitter).
|
||||
- `channels.telegram.network.autoSelectFamily`: override Node autoSelectFamily (true=aktifkan, false=nonaktifkan). Default aktif pada Node 22+, dengan default nonaktif pada WSL2.
|
||||
- `channels.telegram.network.dnsResultOrder`: override urutan hasil DNS (`ipv4first` atau `verbatim`). Default ke `ipv4first` pada Node 22+.
|
||||
- `channels.telegram.network.dangerouslyAllowPrivateNetwork`: opt-in berbahaya untuk lingkungan fake-IP atau proxy transparan tepercaya saat unduhan media Telegram me-resolve `api.telegram.org` ke alamat private/internal/special-use di luar rentang benchmark RFC 2544 default yang diizinkan.
|
||||
- `channels.telegram.proxy`: URL proxy untuk panggilan Bot API (SOCKS/HTTP).
|
||||
- `channels.telegram.webhookUrl`: aktifkan mode webhook (memerlukan `channels.telegram.webhookSecret`).
|
||||
- `channels.telegram.webhookSecret`: secret webhook (wajib saat webhookUrl diatur).
|
||||
- `channels.telegram.webhookPath`: path webhook lokal (default `/telegram-webhook`).
|
||||
- `channels.telegram.webhookHost`: host bind webhook lokal (default `127.0.0.1`).
|
||||
- `channels.telegram.webhookPort`: port bind webhook lokal (default `8787`).
|
||||
- `channels.telegram.webhookUrl`: aktifkan mode Webhook (memerlukan `channels.telegram.webhookSecret`).
|
||||
- `channels.telegram.webhookSecret`: secret Webhook (wajib saat webhookUrl diatur).
|
||||
- `channels.telegram.webhookPath`: path Webhook lokal (default `/telegram-webhook`).
|
||||
- `channels.telegram.webhookHost`: host bind Webhook lokal (default `127.0.0.1`).
|
||||
- `channels.telegram.webhookPort`: port bind Webhook lokal (default `8787`).
|
||||
- `channels.telegram.actions.reactions`: gate reaction tool Telegram.
|
||||
- `channels.telegram.actions.sendMessage`: gate pengiriman pesan tool Telegram.
|
||||
- `channels.telegram.actions.deleteMessage`: gate penghapusan pesan tool Telegram.
|
||||
- `channels.telegram.actions.sticker`: gate aksi stiker Telegram — kirim dan cari (default: false).
|
||||
- `channels.telegram.reactionNotifications`: `off | own | all` — kontrol reaction mana yang memicu event sistem (default: `own` saat tidak diatur).
|
||||
- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` — kontrol kemampuan reaction agent (default: `minimal` saat tidak diatur).
|
||||
- `channels.telegram.errorPolicy`: `reply | silent` — kontrol perilaku balasan error (default: `reply`). Override per-akun/grup/topik didukung.
|
||||
- `channels.telegram.errorCooldownMs`: minimum ms antar balasan error ke chat yang sama (default: `60000`). Mencegah spam error selama gangguan.
|
||||
- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` — kontrol kemampuan reaction agen (default: `minimal` saat tidak diatur).
|
||||
- `channels.telegram.errorPolicy`: `reply | silent` — kontrol perilaku balasan error (default: `reply`). Override per akun/grup/topik didukung.
|
||||
- `channels.telegram.errorCooldownMs`: ms minimum antar balasan error ke chat yang sama (default: `60000`). Mencegah spam error saat terjadi gangguan.
|
||||
|
||||
- [Referensi konfigurasi - Telegram](/gateway/configuration-reference#telegram)
|
||||
- [Referensi konfigurasi - Telegram](/id/gateway/configuration-reference#telegram)
|
||||
|
||||
Field Telegram khusus dengan sinyal tinggi:
|
||||
Field sinyal tinggi khusus Telegram:
|
||||
|
||||
- startup/auth: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` harus menunjuk ke file reguler; symlink ditolak)
|
||||
- startup/auth: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` harus menunjuk ke file biasa; symlink ditolak)
|
||||
- kontrol akses: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` tingkat atas (`type: "acp"`)
|
||||
- persetujuan exec: `execApprovals`, `accounts.*.execApprovals`
|
||||
- perintah/menu: `commands.native`, `commands.nativeSkills`, `customCommands`
|
||||
@ -1060,16 +1060,16 @@ Field Telegram khusus dengan sinyal tinggi:
|
||||
- pemformatan/pengiriman: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix`
|
||||
- media/jaringan: `mediaMaxMb`, `timeoutSeconds`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy`
|
||||
- webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
|
||||
- aksi/kapabilitas: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
|
||||
- actions/capabilities: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
|
||||
- reaction: `reactionNotifications`, `reactionLevel`
|
||||
- error: `errorPolicy`, `errorCooldownMs`
|
||||
- penulisan/riwayat: `configWrites`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
|
||||
|
||||
## Terkait
|
||||
|
||||
- [Pairing](/id/channels/pairing)
|
||||
- [Pemasangan](/id/channels/pairing)
|
||||
- [Grup](/id/channels/groups)
|
||||
- [Keamanan](/gateway/security)
|
||||
- [Keamanan](/id/gateway/security)
|
||||
- [Routing channel](/id/channels/channel-routing)
|
||||
- [Routing multi-agent](/concepts/multi-agent)
|
||||
- [Routing multi-agent](/id/concepts/multi-agent)
|
||||
- [Pemecahan masalah](/id/channels/troubleshooting)
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- Transport channel menunjukkan terhubung tetapi balasan gagal
|
||||
- Anda memerlukan pemeriksaan khusus channel sebelum dokumentasi provider yang lebih mendalam
|
||||
summary: Pemecahan masalah level channel dengan cepat menggunakan signature kegagalan dan perbaikan per channel
|
||||
title: Channel Troubleshooting
|
||||
- Anda memerlukan pemeriksaan khusus channel sebelum masuk ke dokumentasi provider yang mendalam
|
||||
summary: Pemecahan masalah tingkat channel yang cepat dengan tanda kegagalan per channel dan perbaikannya
|
||||
title: Pemecahan Masalah Channel
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T13:44:43Z"
|
||||
generated_at: "2026-04-20T09:27:34Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: d45d8220505ea420d970b20bc66e65216c2d7024b5736db1936421ffc0676e1f
|
||||
source_hash: 0aef31742cd5cc4af3fa3d3ea1acba51875ad4a1423c0e8c87372c3df31b0528
|
||||
source_path: channels/troubleshooting.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -19,7 +19,7 @@ Gunakan halaman ini saat sebuah channel terhubung tetapi perilakunya salah.
|
||||
|
||||
## Urutan perintah
|
||||
|
||||
Jalankan ini terlebih dahulu secara berurutan:
|
||||
Jalankan ini secara berurutan terlebih dahulu:
|
||||
|
||||
```bash
|
||||
openclaw status
|
||||
@ -29,112 +29,113 @@ openclaw doctor
|
||||
openclaw channels status --probe
|
||||
```
|
||||
|
||||
Baseline sehat:
|
||||
Baseline yang sehat:
|
||||
|
||||
- `Runtime: running`
|
||||
- `RPC probe: ok`
|
||||
- `Connectivity probe: ok`
|
||||
- `Capability: read-only`, `write-capable`, atau `admin-capable`
|
||||
- Probe channel menunjukkan transport terhubung dan, jika didukung, `works` atau `audit ok`
|
||||
|
||||
## WhatsApp
|
||||
|
||||
### Signature kegagalan WhatsApp
|
||||
### Tanda kegagalan WhatsApp
|
||||
|
||||
| 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 konfigurasi | Mention bot atau longgarkan kebijakan mention untuk grup itu. |
|
||||
| Putus sambung acak/loop login ulang | `openclaw channels status --probe` + log | Login ulang dan verifikasi direktori kredensial sehat. |
|
||||
| Gejala | Pemeriksaan tercepat | Perbaikan |
|
||||
| ------------------------------- | -------------------------------------------------- | -------------------------------------------------------- |
|
||||
| Terhubung tetapi tidak ada balasan DM | `openclaw pairing list whatsapp` | Setujui pengirim atau ubah kebijakan DM/allowlist. |
|
||||
| Pesan grup diabaikan | Periksa `requireMention` + pola mention di config | Mention bot atau longgarkan kebijakan mention untuk grup tersebut. |
|
||||
| Putus sambung acak/perulangan login ulang | `openclaw channels status --probe` + log | Login ulang dan verifikasi direktori kredensial dalam kondisi sehat. |
|
||||
|
||||
Pemecahan masalah lengkap: [/channels/whatsapp#troubleshooting](/channels/whatsapp#troubleshooting)
|
||||
Pemecahan masalah lengkap: [/channels/whatsapp#troubleshooting](/id/channels/whatsapp#troubleshooting)
|
||||
|
||||
## Telegram
|
||||
|
||||
### Signature kegagalan Telegram
|
||||
### 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. |
|
||||
| `/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 kirim dengan kesalahan jaringan | Periksa log untuk kegagalan panggilan Telegram API | Perbaiki routing DNS/IPv6/proxy ke `api.telegram.org`. |
|
||||
| `setMyCommands` ditolak saat startup | Periksa log untuk `BOT_COMMANDS_TOO_MUCH` | Kurangi perintah Telegram plugin/Skills/kustom atau nonaktifkan menu native. |
|
||||
| Sudah upgrade dan allowlist memblokir Anda | `openclaw security audit` dan allowlist konfigurasi | Jalankan `openclaw doctor --fix` atau ganti `@username` dengan ID pengirim numerik. |
|
||||
| Kegagalan pengiriman dengan error jaringan | Periksa log untuk kegagalan panggilan API Telegram | Perbaiki routing DNS/IPv6/proxy ke `api.telegram.org`. |
|
||||
| `setMyCommands` ditolak saat startup | Periksa log untuk `BOT_COMMANDS_TOO_MUCH` | Kurangi perintah Telegram 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. |
|
||||
|
||||
Pemecahan masalah lengkap: [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting)
|
||||
Pemecahan masalah lengkap: [/channels/telegram#troubleshooting](/id/channels/telegram#troubleshooting)
|
||||
|
||||
## Discord
|
||||
|
||||
### Signature kegagalan Discord
|
||||
### Tanda kegagalan Discord
|
||||
|
||||
| Gejala | Pemeriksaan tercepat | Perbaikan |
|
||||
| ----------------------------- | --------------------------------- | --------------------------------------------------------- |
|
||||
| Bot online tetapi tidak ada balasan guild | `openclaw channels status --probe` | Izinkan guild/channel dan verifikasi message content intent. |
|
||||
| Pesan grup diabaikan | Periksa log untuk drop mention gating | Mention bot atau setel guild/channel `requireMention: false`. |
|
||||
| Balasan DM tidak ada | `openclaw pairing list discord` | Setujui pairing DM atau sesuaikan kebijakan DM. |
|
||||
| Gejala | Pemeriksaan tercepat | Perbaikan |
|
||||
| ------------------------------- | --------------------------------- | --------------------------------------------------------- |
|
||||
| Bot online tetapi tidak ada balasan guild | `openclaw channels status --probe` | Izinkan guild/channel dan verifikasi message content intent. |
|
||||
| Pesan grup diabaikan | Periksa log untuk drop gating mention | Mention bot atau setel `requireMention: false` untuk guild/channel. |
|
||||
| Balasan DM tidak ada | `openclaw pairing list discord` | Setujui pairing DM atau sesuaikan kebijakan DM. |
|
||||
|
||||
Pemecahan masalah lengkap: [/channels/discord#troubleshooting](/channels/discord#troubleshooting)
|
||||
Pemecahan masalah lengkap: [/channels/discord#troubleshooting](/id/channels/discord#troubleshooting)
|
||||
|
||||
## Slack
|
||||
|
||||
### Signature kegagalan Slack
|
||||
### Tanda kegagalan Slack
|
||||
|
||||
| Gejala | Pemeriksaan tercepat | Perbaikan |
|
||||
| -------------------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Socket mode terhubung tetapi tidak ada respons | `openclaw channels status --probe` | Verifikasi app token + bot token dan scope yang diperlukan; perhatikan `botTokenStatus` / `appTokenStatus = configured_unavailable` pada penyiapan berbasis SecretRef. |
|
||||
| DM diblokir | `openclaw pairing list slack` | Setujui pairing atau longgarkan kebijakan DM. |
|
||||
| Socket mode terhubung tetapi tidak ada respons | `openclaw channels status --probe` | Verifikasi app token + bot token dan scope yang diperlukan; perhatikan `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 menjadi `open`. |
|
||||
|
||||
Pemecahan masalah lengkap: [/channels/slack#troubleshooting](/channels/slack#troubleshooting)
|
||||
Pemecahan masalah lengkap: [/channels/slack#troubleshooting](/id/channels/slack#troubleshooting)
|
||||
|
||||
## iMessage dan BlueBubbles
|
||||
|
||||
### Signature kegagalan iMessage dan BlueBubbles
|
||||
### Tanda kegagalan iMessage dan BlueBubbles
|
||||
|
||||
| Gejala | Pemeriksaan tercepat | Perbaikan |
|
||||
| ------------------------------ | ------------------------------------------------------------------------- | ----------------------------------------------------- |
|
||||
| Tidak ada event masuk | Verifikasi keterjangkauan webhook/server dan izin aplikasi | Perbaiki URL webhook atau status server BlueBubbles. |
|
||||
| Bisa mengirim tetapi tidak menerima di macOS | Periksa izin privasi macOS untuk otomasi 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 event masuk | Verifikasi keterjangkauan webhook/server dan izin aplikasi | Perbaiki URL webhook atau status server BlueBubbles. |
|
||||
| Bisa mengirim tetapi tidak bisa menerima di macOS | Periksa izin privasi macOS untuk otomasi Messages | Berikan ulang izin TCC dan mulai ulang proses channel. |
|
||||
| Pengirim DM diblokir | `openclaw pairing list imessage` atau `openclaw pairing list bluebubbles` | Setujui pairing atau perbarui allowlist. |
|
||||
|
||||
Pemecahan masalah lengkap:
|
||||
|
||||
- [/channels/imessage#troubleshooting](/channels/imessage#troubleshooting)
|
||||
- [/channels/bluebubbles#troubleshooting](/channels/bluebubbles#troubleshooting)
|
||||
- [/channels/imessage#troubleshooting](/id/channels/imessage#troubleshooting)
|
||||
- [/channels/bluebubbles#troubleshooting](/id/channels/bluebubbles#troubleshooting)
|
||||
|
||||
## Signal
|
||||
|
||||
### Signature kegagalan Signal
|
||||
### 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 receive. |
|
||||
| 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/account daemon `signal-cli` dan mode receive. |
|
||||
| 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. |
|
||||
|
||||
Pemecahan masalah lengkap: [/channels/signal#troubleshooting](/channels/signal#troubleshooting)
|
||||
Pemecahan masalah lengkap: [/channels/signal#troubleshooting](/id/channels/signal#troubleshooting)
|
||||
|
||||
## QQ Bot
|
||||
|
||||
### Signature kegagalan QQ Bot
|
||||
### Tanda kegagalan QQ Bot
|
||||
|
||||
| Gejala | Pemeriksaan tercepat | Perbaikan |
|
||||
| ----------------------------- | ------------------------------------------------- | ---------------------------------------------------------------- |
|
||||
| Bot membalas "gone to Mars" | Verifikasi `appId` dan `clientSecret` di konfigurasi | Setel kredensial atau restart gateway. |
|
||||
| Tidak ada pesan masuk | `openclaw channels status --probe` | Verifikasi kredensial di QQ Open Platform. |
|
||||
| Suara tidak ditranskripsikan | Periksa konfigurasi provider STT | Konfigurasikan `channels.qqbot.stt` atau `tools.media.audio`. |
|
||||
| Pesan proaktif tidak sampai | Periksa persyaratan interaksi platform QQ | QQ mungkin memblokir pesan yang diprakarsai bot tanpa interaksi baru-baru ini. |
|
||||
| Gejala | Pemeriksaan tercepat | Perbaikan |
|
||||
| ------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------- |
|
||||
| Bot membalas "gone to Mars" | Verifikasi `appId` dan `clientSecret` di config | Setel kredensial atau mulai ulang gateway. |
|
||||
| Tidak ada pesan masuk | `openclaw channels status --probe` | Verifikasi kredensial di QQ Open Platform. |
|
||||
| Suara tidak ditranskripsikan | Periksa config provider STT | Konfigurasikan `channels.qqbot.stt` atau `tools.media.audio`. |
|
||||
| Pesan proaktif tidak sampai | Periksa persyaratan interaksi platform QQ | QQ dapat memblokir pesan yang diinisiasi bot tanpa interaksi terbaru. |
|
||||
|
||||
Pemecahan masalah lengkap: [/channels/qqbot#troubleshooting](/channels/qqbot#troubleshooting)
|
||||
Pemecahan masalah lengkap: [/channels/qqbot#troubleshooting](/id/channels/qqbot#troubleshooting)
|
||||
|
||||
## Matrix
|
||||
|
||||
### Signature kegagalan Matrix
|
||||
### Tanda kegagalan Matrix
|
||||
|
||||
| Gejala | Pemeriksaan tercepat | Perbaikan |
|
||||
| ----------------------------------- | ------------------------------------- | ------------------------------------------------------------------------- |
|
||||
| Sudah login tetapi mengabaikan pesan room | `openclaw channels status --probe` | Periksa `groupPolicy`, allowlist room, dan mention gating. |
|
||||
| DM tidak diproses | `openclaw pairing list matrix` | Setujui pengirim atau sesuaikan kebijakan DM. |
|
||||
| Room terenkripsi gagal | `openclaw matrix verify status` | Verifikasi ulang device, lalu periksa `openclaw matrix verify backup status`. |
|
||||
| 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`. |
|
||||
| Pemulihan backup tertunda/rusak | `openclaw matrix verify backup status` | Jalankan `openclaw matrix verify backup restore` atau jalankan ulang dengan recovery key. |
|
||||
| Cross-signing/bootstrap tampak salah | `openclaw matrix verify bootstrap` | Perbaiki status secret storage, cross-signing, dan backup dalam satu langkah. |
|
||||
| Cross-signing/bootstrap terlihat salah | `openclaw matrix verify bootstrap` | Perbaiki secret storage, cross-signing, dan status backup dalam satu langkah. |
|
||||
|
||||
Penyiapan dan konfigurasi lengkap: [Matrix](/channels/matrix)
|
||||
Setup dan config lengkap: [Matrix](/id/channels/matrix)
|
||||
|
||||
@ -1,33 +1,37 @@
|
||||
---
|
||||
read_when:
|
||||
- Memperluas qa-lab atau qa-channel
|
||||
- Menambahkan skenario QA berbasis repo
|
||||
- Menambahkan skenario QA yang didukung repo
|
||||
- Membangun otomasi QA dengan realisme lebih tinggi di sekitar dasbor Gateway
|
||||
summary: Bentuk otomasi QA privat untuk qa-lab, qa-channel, skenario seed, dan laporan protokol
|
||||
title: Otomasi QA E2E
|
||||
summary: Bentuk otomasi QA privat untuk qa-lab, qa-channel, skenario yang di-seed, dan laporan protokol
|
||||
title: Otomasi E2E QA
|
||||
x-i18n:
|
||||
generated_at: "2026-04-18T09:05:48Z"
|
||||
generated_at: "2026-04-20T09:27:34Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: adf8c5f74e8fabdc8e9fd7ecd41afce8b60354c7dd24d92ac926d3c527927cd4
|
||||
source_hash: 34245ce871356caeab0d9e0eeeaa9fb4e408920a4a97ad27567fa365d8db17c7
|
||||
source_path: concepts/qa-e2e-automation.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Otomasi QA E2E
|
||||
# Otomasi E2E QA
|
||||
|
||||
Stack QA privat dimaksudkan untuk menguji OpenClaw dengan cara yang lebih realistis dan berbentuk seperti channel dibandingkan yang dapat dilakukan oleh satu unit test.
|
||||
Stack QA privat dimaksudkan untuk menguji OpenClaw dengan cara yang lebih realistis,
|
||||
berbentuk kanal, dibandingkan yang bisa dilakukan oleh satu unit test.
|
||||
|
||||
Bagian saat ini:
|
||||
Komponen saat ini:
|
||||
|
||||
- `extensions/qa-channel`: channel pesan sintetis dengan permukaan DM, channel, thread, reaction, edit, dan delete.
|
||||
- `extensions/qa-lab`: UI debugger dan bus QA untuk mengamati transkrip, menyuntikkan pesan masuk, dan mengekspor laporan Markdown.
|
||||
- `qa/`: aset seed berbasis repo untuk tugas kickoff dan skenario QA baseline.
|
||||
- `extensions/qa-channel`: kanal pesan sintetis dengan permukaan DM, kanal, thread,
|
||||
reaksi, edit, dan hapus.
|
||||
- `extensions/qa-lab`: UI debugger dan bus QA untuk mengamati transkrip,
|
||||
menyuntikkan pesan masuk, dan mengekspor laporan Markdown.
|
||||
- `qa/`: aset seed yang didukung repo untuk tugas kickoff dan skenario QA
|
||||
dasar.
|
||||
|
||||
Alur operator QA saat ini adalah situs QA dua panel:
|
||||
|
||||
- Kiri: dasbor Gateway (Control UI) dengan agen.
|
||||
- Kanan: QA Lab, yang menampilkan transkrip bergaya Slack dan rencana skenario.
|
||||
- Kanan: QA Lab, menampilkan transkrip bergaya Slack dan rencana skenario.
|
||||
|
||||
Jalankan dengan:
|
||||
|
||||
@ -35,9 +39,13 @@ Jalankan dengan:
|
||||
pnpm qa:lab:up
|
||||
```
|
||||
|
||||
Perintah itu membangun situs QA, memulai lane gateway berbasis Docker, dan mengekspos halaman QA Lab tempat operator atau loop otomasi dapat memberi agen misi QA, mengamati perilaku channel nyata, dan mencatat apa yang berhasil, gagal, atau tetap terblokir.
|
||||
Perintah itu membangun situs QA, memulai lane gateway berbasis Docker, dan membuka
|
||||
halaman QA Lab tempat operator atau loop otomasi dapat memberi agen
|
||||
misi QA, mengamati perilaku kanal nyata, dan mencatat apa yang berhasil, gagal, atau
|
||||
tetap terblokir.
|
||||
|
||||
Untuk iterasi UI QA Lab yang lebih cepat tanpa membangun ulang image Docker setiap kali, mulai stack dengan bundle QA Lab yang di-bind-mount:
|
||||
Untuk iterasi UI QA Lab yang lebih cepat tanpa membangun ulang image Docker setiap kali,
|
||||
mulai stack dengan bundle QA Lab yang di-bind-mount:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa docker-build-image
|
||||
@ -46,7 +54,9 @@ pnpm qa:lab:up:fast
|
||||
pnpm qa:lab:watch
|
||||
```
|
||||
|
||||
`qa:lab:up:fast` menjaga layanan Docker tetap berjalan pada image yang sudah dibangun sebelumnya dan melakukan bind-mount `extensions/qa-lab/web/dist` ke dalam container `qa-lab`. `qa:lab:watch` membangun ulang bundle tersebut saat ada perubahan, dan browser memuat ulang secara otomatis saat hash aset QA Lab berubah.
|
||||
`qa:lab:up:fast` menjaga layanan Docker tetap berjalan pada image yang sudah dibangun dan melakukan bind-mount
|
||||
`extensions/qa-lab/web/dist` ke dalam container `qa-lab`. `qa:lab:watch`
|
||||
membangun ulang bundle tersebut saat ada perubahan, dan browser akan memuat ulang otomatis ketika hash aset QA Lab berubah.
|
||||
|
||||
Untuk lane smoke Matrix dengan transport nyata, jalankan:
|
||||
|
||||
@ -54,7 +64,14 @@ Untuk lane smoke Matrix dengan transport nyata, jalankan:
|
||||
pnpm openclaw qa matrix
|
||||
```
|
||||
|
||||
Lane itu menyediakan homeserver Tuwunel sekali pakai di Docker, mendaftarkan pengguna driver, SUT, dan observer sementara, membuat satu room privat, lalu menjalankan plugin Matrix nyata di dalam child Gateway QA. Lane transport live menjaga konfigurasi child tetap dibatasi pada transport yang sedang diuji, sehingga Matrix berjalan tanpa `qa-channel` di konfigurasi child. Lane ini menulis artefak laporan terstruktur dan log stdout/stderr gabungan ke direktori output QA Matrix yang dipilih. Untuk juga menangkap output build/launcher luar dari `scripts/run-node.mjs`, set `OPENCLAW_RUN_NODE_OUTPUT_LOG=<path>` ke file log lokal repo.
|
||||
Lane itu memprovisikan homeserver Tuwunel sekali pakai di Docker, mendaftarkan
|
||||
pengguna driver, SUT, dan observer sementara, membuat satu room privat, lalu menjalankan
|
||||
Plugin Matrix nyata di dalam child gateway QA. Lane transport live menjaga config child
|
||||
tetap terbatas pada transport yang sedang diuji, sehingga Matrix berjalan tanpa
|
||||
`qa-channel` di config child. Lane ini menulis artefak laporan terstruktur dan
|
||||
log gabungan stdout/stderr ke direktori output Matrix QA yang dipilih. Untuk
|
||||
menangkap output build/launcher luar `scripts/run-node.mjs` juga, set
|
||||
`OPENCLAW_RUN_NODE_OUTPUT_LOG=<path>` ke file log lokal repo.
|
||||
|
||||
Untuk lane smoke Telegram dengan transport nyata, jalankan:
|
||||
|
||||
@ -62,87 +79,121 @@ Untuk lane smoke Telegram dengan transport nyata, jalankan:
|
||||
pnpm openclaw qa telegram
|
||||
```
|
||||
|
||||
Lane itu menargetkan satu grup Telegram privat nyata alih-alih menyediakan server sekali pakai. Lane ini memerlukan `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`, dan `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, serta dua bot berbeda dalam grup privat yang sama. Bot SUT harus memiliki username Telegram, dan observasi bot-ke-bot bekerja paling baik saat kedua bot mengaktifkan Bot-to-Bot Communication Mode di `@BotFather`.
|
||||
Lane itu menargetkan satu grup Telegram privat nyata alih-alih memprovisikan server
|
||||
sekali pakai. Lane ini memerlukan `OPENCLAW_QA_TELEGRAM_GROUP_ID`,
|
||||
`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`, dan
|
||||
`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, ditambah dua bot berbeda di grup
|
||||
privat yang sama. Bot SUT harus memiliki username Telegram, dan observasi bot-ke-bot
|
||||
bekerja paling baik saat kedua bot mengaktifkan Bot-to-Bot Communication Mode
|
||||
di `@BotFather`.
|
||||
Perintah akan keluar dengan status non-zero ketika ada skenario yang gagal. Gunakan `--allow-failures` ketika
|
||||
Anda menginginkan artefak tanpa exit code gagal.
|
||||
|
||||
Lane transport live sekarang berbagi satu kontrak yang lebih kecil alih-alih masing-masing menciptakan bentuk daftar skenario sendiri:
|
||||
Lane transport live sekarang berbagi satu kontrak yang lebih kecil alih-alih masing-masing
|
||||
menciptakan bentuk daftar skenario sendiri:
|
||||
|
||||
`qa-channel` tetap menjadi suite perilaku produk sintetis yang luas dan bukan bagian dari matriks cakupan transport live.
|
||||
`qa-channel` tetap menjadi suite perilaku produk sintetis yang luas dan tidak termasuk
|
||||
dalam matriks cakupan transport live.
|
||||
|
||||
| Lane | Canary | Gating mention | Blokir allowlist | Balasan tingkat atas | Lanjut setelah restart | Tindak lanjut thread | Isolasi thread | Observasi reaction | Perintah help |
|
||||
| -------- | ------ | -------------- | ---------------- | -------------------- | ---------------------- | -------------------- | -------------- | ------------------ | ------------- |
|
||||
| Matrix | x | x | x | x | x | x | x | x | |
|
||||
| Telegram | x | | | | | | | | x |
|
||||
| Lane | Canary | Penyaringan mention | Blok allowlist | Balasan tingkat atas | Lanjut setelah restart | Tindak lanjut thread | Isolasi thread | Observasi reaksi | Perintah help |
|
||||
| -------- | ------ | ------------------- | -------------- | -------------------- | ---------------------- | -------------------- | -------------- | ---------------- | ------------- |
|
||||
| Matrix | x | x | x | x | x | x | x | x | |
|
||||
| Telegram | x | | | | | | | | x |
|
||||
|
||||
Ini menjaga `qa-channel` sebagai suite perilaku produk yang luas, sementara Matrix, Telegram, dan transport live di masa mendatang berbagi satu daftar periksa kontrak transport yang eksplisit.
|
||||
Ini menjaga `qa-channel` tetap sebagai suite perilaku produk yang luas sementara Matrix,
|
||||
Telegram, dan transport live di masa depan berbagi satu daftar pemeriksaan kontrak transport yang eksplisit.
|
||||
|
||||
Untuk lane VM Linux sekali pakai tanpa membawa Docker ke jalur QA, jalankan:
|
||||
Untuk lane VM Linux sekali pakai tanpa membawa Docker ke dalam jalur QA, jalankan:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
|
||||
```
|
||||
|
||||
Ini menyalakan guest Multipass baru, memasang dependensi, membangun OpenClaw di dalam guest, menjalankan `qa suite`, lalu menyalin kembali laporan dan ringkasan QA normal ke `.artifacts/qa-e2e/...` di host.
|
||||
Lane ini menggunakan kembali perilaku pemilihan skenario yang sama seperti `qa suite` di host.
|
||||
Eksekusi suite di host dan Multipass menjalankan beberapa skenario terpilih secara paralel dengan worker Gateway terisolasi secara default, hingga 64 worker atau sebanyak jumlah skenario yang dipilih. Gunakan `--concurrency <count>` untuk menyesuaikan jumlah worker, atau `--concurrency 1` untuk eksekusi serial.
|
||||
Eksekusi live meneruskan input auth QA yang didukung dan praktis untuk guest: key provider berbasis env, path konfigurasi provider live QA, dan `CODEX_HOME` jika ada. Pertahankan `--output-dir` di bawah root repo agar guest dapat menulis kembali melalui workspace yang di-mount.
|
||||
Ini mem-boot guest Multipass baru, menginstal dependensi, membangun OpenClaw
|
||||
di dalam guest, menjalankan `qa suite`, lalu menyalin kembali laporan dan
|
||||
ringkasan QA normal ke `.artifacts/qa-e2e/...` di host.
|
||||
Perintah ini menggunakan kembali perilaku pemilihan skenario yang sama seperti `qa suite` di host.
|
||||
Eksekusi suite host dan Multipass menjalankan beberapa skenario terpilih secara paralel
|
||||
dengan worker gateway terisolasi secara default. `qa-channel` default ke concurrency
|
||||
4, dibatasi oleh jumlah skenario yang dipilih. Gunakan `--concurrency <count>` untuk menyesuaikan
|
||||
jumlah worker, atau `--concurrency 1` untuk eksekusi serial.
|
||||
Perintah akan keluar dengan status non-zero ketika ada skenario yang gagal. Gunakan `--allow-failures` ketika
|
||||
Anda menginginkan artefak tanpa exit code gagal.
|
||||
Eksekusi live meneruskan input auth QA yang didukung dan praktis untuk
|
||||
guest: key provider berbasis env, path config provider live QA, dan
|
||||
`CODEX_HOME` bila ada. Pertahankan `--output-dir` di bawah root repo agar guest
|
||||
dapat menulis kembali melalui workspace yang di-mount.
|
||||
|
||||
## Seed berbasis repo
|
||||
## Seed yang didukung repo
|
||||
|
||||
Aset seed berada di `qa/`:
|
||||
|
||||
- `qa/scenarios/index.md`
|
||||
- `qa/scenarios/<theme>/*.md`
|
||||
|
||||
Ini sengaja disimpan di git agar rencana QA terlihat baik oleh manusia maupun agen.
|
||||
Ini sengaja disimpan di git agar rencana QA terlihat oleh manusia maupun
|
||||
agen.
|
||||
|
||||
`qa-lab` harus tetap menjadi runner markdown generik. Setiap file markdown skenario adalah sumber kebenaran untuk satu eksekusi pengujian dan harus mendefinisikan:
|
||||
`qa-lab` harus tetap menjadi runner markdown generik. Setiap file markdown skenario adalah
|
||||
sumber kebenaran untuk satu eksekusi pengujian dan harus mendefinisikan:
|
||||
|
||||
- metadata skenario
|
||||
- metadata kategori, capability, lane, dan risk opsional
|
||||
- referensi docs dan code
|
||||
- metadata kategori, kapabilitas, lane, dan risiko opsional
|
||||
- referensi docs dan kode
|
||||
- persyaratan Plugin opsional
|
||||
- patch konfigurasi Gateway opsional
|
||||
- patch config gateway opsional
|
||||
- `qa-flow` yang dapat dieksekusi
|
||||
|
||||
Permukaan runtime yang dapat digunakan ulang dan mendukung `qa-flow` boleh tetap generik dan lintas area. Misalnya, skenario markdown dapat menggabungkan helper sisi transport dengan helper sisi browser yang mengendalikan Control UI tersemat melalui seam Gateway `browser.request` tanpa menambahkan runner kasus khusus.
|
||||
Permukaan runtime yang dapat digunakan ulang yang mendukung `qa-flow` boleh tetap generik
|
||||
dan lintas bidang. Sebagai contoh, skenario markdown dapat menggabungkan helper sisi transport
|
||||
dengan helper sisi browser yang menggerakkan Control UI tersemat melalui
|
||||
seam Gateway `browser.request` tanpa menambahkan runner kasus khusus.
|
||||
|
||||
File skenario harus dikelompokkan berdasarkan capability produk, bukan folder pohon sumber. Pertahankan ID skenario tetap stabil saat file dipindahkan; gunakan `docsRefs` dan `codeRefs` untuk keterlacakan implementasi.
|
||||
File skenario harus dikelompokkan berdasarkan kapabilitas produk, bukan folder
|
||||
pohon sumber. Jaga ID skenario tetap stabil saat file dipindahkan; gunakan `docsRefs` dan `codeRefs`
|
||||
untuk keterlacakan implementasi.
|
||||
|
||||
Daftar baseline harus tetap cukup luas untuk mencakup:
|
||||
Daftar dasar harus tetap cukup luas untuk mencakup:
|
||||
|
||||
- chat DM dan channel
|
||||
- DM dan chat kanal
|
||||
- perilaku thread
|
||||
- siklus hidup aksi pesan
|
||||
- callback Cron
|
||||
- penarikan memori
|
||||
- perpindahan model
|
||||
- pemanggilan kembali memori
|
||||
- pergantian model
|
||||
- handoff subagen
|
||||
- membaca repo dan docs
|
||||
- pembacaan repo dan pembacaan docs
|
||||
- satu tugas build kecil seperti Lobster Invaders
|
||||
|
||||
## Lane mock provider
|
||||
|
||||
`qa suite` memiliki dua lane mock provider lokal:
|
||||
|
||||
- `mock-openai` adalah mock OpenClaw yang sadar skenario. Ini tetap menjadi lane mock deterministik default untuk QA berbasis repo dan gate paritas.
|
||||
- `aimock` memulai server provider berbasis AIMock untuk cakupan protokol, fixture, record/replay, dan chaos yang eksperimental. Ini bersifat tambahan dan tidak menggantikan dispatcher skenario `mock-openai`.
|
||||
- `mock-openai` adalah mock OpenClaw yang sadar skenario. Ini tetap menjadi
|
||||
lane mock deterministik default untuk QA yang didukung repo dan gate paritas.
|
||||
- `aimock` memulai server provider berbasis AIMock untuk cakupan protokol,
|
||||
fixture, record/replay, dan chaos eksperimental. Ini bersifat tambahan dan tidak menggantikan dispatcher skenario `mock-openai`.
|
||||
|
||||
Implementasi lane provider berada di `extensions/qa-lab/src/providers/`.
|
||||
Setiap provider memiliki default, startup server lokal, konfigurasi model Gateway, kebutuhan staging auth-profile, dan flag capability live/mock masing-masing. Kode suite dan gateway bersama harus merutekan melalui registry provider alih-alih bercabang berdasarkan nama provider.
|
||||
Setiap provider memiliki default, startup server lokal, config model gateway,
|
||||
kebutuhan staging auth-profile, dan flag kapabilitas live/mock sendiri. Kode suite dan gateway
|
||||
bersama harus merutekan melalui registry provider alih-alih bercabang berdasarkan
|
||||
nama provider.
|
||||
|
||||
## Adapter transport
|
||||
## Adaptor transport
|
||||
|
||||
`qa-lab` memiliki seam transport generik untuk skenario QA markdown.
|
||||
`qa-channel` adalah adapter pertama pada seam itu, tetapi target desainnya lebih luas:
|
||||
channel nyata atau sintetis di masa mendatang harus dapat dipasang ke runner suite yang sama alih-alih menambahkan runner QA khusus transport.
|
||||
`qa-channel` adalah adaptor pertama pada seam tersebut, tetapi target desainnya lebih luas:
|
||||
kanal nyata atau sintetis di masa depan harus dapat dipasang ke runner suite yang sama
|
||||
alih-alih menambahkan runner QA khusus transport.
|
||||
|
||||
Pada tingkat arsitektur, pembagiannya adalah:
|
||||
|
||||
- `qa-lab` memiliki eksekusi skenario generik, konkurensi worker, penulisan artefak, dan pelaporan.
|
||||
- adapter transport memiliki konfigurasi Gateway, kesiapan, observasi inbound dan outbound, aksi transport, dan status transport yang dinormalisasi.
|
||||
- file skenario markdown di bawah `qa/scenarios/` mendefinisikan eksekusi pengujian; `qa-lab` menyediakan permukaan runtime yang dapat digunakan ulang yang mengeksekusinya.
|
||||
- `qa-lab` memiliki eksekusi skenario generik, concurrency worker, penulisan artefak, dan pelaporan.
|
||||
- adaptor transport memiliki config gateway, kesiapan, observasi masuk dan keluar, aksi transport, dan state transport yang dinormalisasi.
|
||||
- file skenario markdown di bawah `qa/scenarios/` mendefinisikan eksekusi pengujian; `qa-lab` menyediakan permukaan runtime yang dapat digunakan ulang untuk mengeksekusinya.
|
||||
|
||||
Panduan adopsi untuk maintainer terkait adapter channel baru tersedia di
|
||||
Panduan adopsi untuk adaptor kanal baru yang ditujukan bagi maintainer berada di
|
||||
[Testing](/id/help/testing#adding-a-channel-to-qa).
|
||||
|
||||
## Pelaporan
|
||||
@ -155,7 +206,8 @@ Laporan tersebut harus menjawab:
|
||||
- Apa yang tetap terblokir
|
||||
- Skenario tindak lanjut apa yang layak ditambahkan
|
||||
|
||||
Untuk pemeriksaan karakter dan gaya, jalankan skenario yang sama di beberapa ref model live dan tulis laporan Markdown yang dinilai:
|
||||
Untuk pemeriksaan karakter dan gaya, jalankan skenario yang sama di beberapa ref model live
|
||||
dan tulis laporan Markdown yang dinilai:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa character-eval \
|
||||
@ -174,24 +226,41 @@ pnpm openclaw qa character-eval \
|
||||
--judge-concurrency 16
|
||||
```
|
||||
|
||||
Perintah tersebut menjalankan child process gateway QA lokal, bukan Docker. Skenario evaluasi karakter harus menetapkan persona melalui `SOUL.md`, lalu menjalankan giliran pengguna biasa seperti chat, bantuan workspace, dan tugas file kecil. Model kandidat tidak boleh diberi tahu bahwa model itu sedang dievaluasi. Perintah ini mempertahankan setiap transkrip lengkap, mencatat statistik dasar eksekusi, lalu meminta model juri dalam mode cepat dengan penalaran `xhigh` untuk memberi peringkat eksekusi berdasarkan naturalness, vibe, dan humor.
|
||||
Gunakan `--blind-judge-models` saat membandingkan provider: prompt juri tetap mendapatkan setiap transkrip dan status eksekusi, tetapi ref kandidat diganti dengan label netral seperti `candidate-01`; laporan memetakan peringkat kembali ke ref nyata setelah parsing.
|
||||
Eksekusi kandidat default menggunakan thinking `high`, dengan `xhigh` untuk model OpenAI yang mendukungnya. Override kandidat tertentu secara inline dengan
|
||||
`--model provider/model,thinking=<level>`. `--thinking <level>` tetap menetapkan fallback global, dan bentuk lama `--model-thinking <provider/model=level>` dipertahankan untuk kompatibilitas.
|
||||
Ref kandidat OpenAI default ke mode cepat sehingga pemrosesan prioritas digunakan saat provider mendukungnya. Tambahkan `,fast`, `,no-fast`, atau `,fast=false` secara inline saat satu kandidat atau juri memerlukan override. Berikan `--fast` hanya jika Anda ingin memaksa mode cepat aktif untuk setiap model kandidat. Durasi kandidat dan juri dicatat dalam laporan untuk analisis benchmark, tetapi prompt juri secara eksplisit mengatakan untuk tidak memberi peringkat berdasarkan kecepatan.
|
||||
Eksekusi model kandidat dan juri sama-sama default ke konkurensi 16. Turunkan
|
||||
`--concurrency` atau `--judge-concurrency` saat batas provider atau tekanan gateway lokal membuat eksekusi terlalu bising.
|
||||
Perintah ini menjalankan proses child gateway QA lokal, bukan Docker. Skenario evaluasi karakter
|
||||
harus menetapkan persona melalui `SOUL.md`, lalu menjalankan giliran pengguna biasa
|
||||
seperti chat, bantuan workspace, dan tugas file kecil. Model kandidat
|
||||
tidak boleh diberi tahu bahwa model tersebut sedang dievaluasi. Perintah ini mempertahankan setiap
|
||||
transkrip lengkap, mencatat statistik dasar eksekusi, lalu meminta model penilai dalam mode fast dengan
|
||||
penalaran `xhigh` untuk memberi peringkat eksekusi berdasarkan kealamian, vibe, dan humor.
|
||||
Gunakan `--blind-judge-models` saat membandingkan provider:
|
||||
prompt penilai tetap mendapatkan setiap transkrip dan status eksekusi, tetapi ref kandidat diganti
|
||||
dengan label netral seperti `candidate-01`; laporan memetakan kembali peringkat ke ref nyata setelah
|
||||
parsing.
|
||||
Eksekusi kandidat default ke thinking `high`, dengan `xhigh` untuk model OpenAI yang
|
||||
mendukungnya. Override kandidat tertentu secara inline dengan
|
||||
`--model provider/model,thinking=<level>`. `--thinking <level>` tetap menetapkan
|
||||
fallback global, dan bentuk lama `--model-thinking <provider/model=level>` tetap
|
||||
dipertahankan untuk kompatibilitas.
|
||||
Ref kandidat OpenAI default ke mode fast sehingga pemrosesan prioritas digunakan jika
|
||||
provider mendukungnya. Tambahkan `,fast`, `,no-fast`, atau `,fast=false` secara inline ketika satu
|
||||
kandidat atau penilai memerlukan override. Berikan `--fast` hanya jika Anda ingin
|
||||
memaksa mode fast aktif untuk setiap model kandidat. Durasi kandidat dan penilai
|
||||
dicatat dalam laporan untuk analisis benchmark, tetapi prompt penilai secara eksplisit mengatakan
|
||||
untuk tidak memberi peringkat berdasarkan kecepatan.
|
||||
Eksekusi model kandidat dan penilai keduanya default ke concurrency 16. Turunkan
|
||||
`--concurrency` atau `--judge-concurrency` saat batas provider atau tekanan gateway lokal
|
||||
membuat eksekusi terlalu bising.
|
||||
Saat tidak ada kandidat `--model` yang diberikan, evaluasi karakter akan default ke
|
||||
`openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`,
|
||||
`anthropic/claude-sonnet-4-6`, `zai/glm-5.1`,
|
||||
`moonshot/kimi-k2.5`, dan
|
||||
`google/gemini-3.1-pro-preview` saat tidak ada `--model` yang diberikan.
|
||||
Saat tidak ada `--judge-model` yang diberikan, juri akan default ke
|
||||
Saat tidak ada `--judge-model` yang diberikan, penilai akan default ke
|
||||
`openai/gpt-5.4,thinking=xhigh,fast` dan
|
||||
`anthropic/claude-opus-4-6,thinking=high`.
|
||||
|
||||
## Dokumen terkait
|
||||
## Docs terkait
|
||||
|
||||
- [Testing](/id/help/testing)
|
||||
- [QA Channel](/id/channels/qa-channel)
|
||||
- [Dashboard](/web/dashboard)
|
||||
- [Dasbor](/web/dashboard)
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- Menambahkan atau mengubah migrasi doctor
|
||||
- Memperkenalkan perubahan konfigurasi yang breaking
|
||||
summary: 'Perintah Doctor: pemeriksaan kesehatan, migrasi konfigurasi, dan langkah perbaikan'
|
||||
- Memperkenalkan perubahan konfigurasi yang merusak
|
||||
summary: 'Perintah doctor: pemeriksaan kesehatan, migrasi konfigurasi, dan langkah perbaikan'
|
||||
title: Doctor
|
||||
x-i18n:
|
||||
generated_at: "2026-04-09T01:28:58Z"
|
||||
generated_at: "2026-04-20T09:27:33Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 75d321bd1ad0e16c29f2382e249c51edfc3a8d33b55bdceea39e7dbcd4901fce
|
||||
source_hash: 61a5e01a306058c49be6095f7c8082d779a55d63cf3b5f4c4096173943faf51b
|
||||
source_path: gateway/doctor.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -16,8 +16,7 @@ x-i18n:
|
||||
# Doctor
|
||||
|
||||
`openclaw doctor` adalah alat perbaikan + migrasi untuk OpenClaw. Alat ini memperbaiki
|
||||
konfigurasi/status yang usang, memeriksa kesehatan, dan menyediakan langkah
|
||||
perbaikan yang dapat ditindaklanjuti.
|
||||
konfigurasi/status yang usang, memeriksa kesehatan, dan menyediakan langkah perbaikan yang dapat ditindaklanjuti.
|
||||
|
||||
## Mulai cepat
|
||||
|
||||
@ -31,13 +30,13 @@ openclaw doctor
|
||||
openclaw doctor --yes
|
||||
```
|
||||
|
||||
Terima default tanpa prompt (termasuk langkah perbaikan restart/layanan/sandbox bila berlaku).
|
||||
Terima nilai default tanpa prompt (termasuk langkah perbaikan restart/layanan/sandbox jika berlaku).
|
||||
|
||||
```bash
|
||||
openclaw doctor --repair
|
||||
```
|
||||
|
||||
Terapkan perbaikan yang direkomendasikan tanpa prompt (perbaikan + restart bila aman).
|
||||
Terapkan perbaikan yang direkomendasikan tanpa prompt (perbaikan + restart jika aman).
|
||||
|
||||
```bash
|
||||
openclaw doctor --repair --force
|
||||
@ -49,7 +48,7 @@ Terapkan juga perbaikan agresif (menimpa konfigurasi supervisor kustom).
|
||||
openclaw doctor --non-interactive
|
||||
```
|
||||
|
||||
Jalankan tanpa prompt dan hanya terapkan migrasi yang aman (normalisasi konfigurasi + pemindahan status di disk). Melewati tindakan restart/layanan/sandbox yang memerlukan konfirmasi manusia.
|
||||
Jalankan tanpa prompt dan hanya terapkan migrasi aman (normalisasi konfigurasi + pemindahan status di disk). Melewati tindakan restart/layanan/sandbox yang memerlukan konfirmasi manusia.
|
||||
Migrasi status lama berjalan otomatis saat terdeteksi.
|
||||
|
||||
```bash
|
||||
@ -64,89 +63,88 @@ Jika Anda ingin meninjau perubahan sebelum menulis, buka file konfigurasi terleb
|
||||
cat ~/.openclaw/openclaw.json
|
||||
```
|
||||
|
||||
## Apa yang dilakukan (ringkasan)
|
||||
## Apa yang dilakukannya (ringkasan)
|
||||
|
||||
- Pembaruan pre-flight opsional untuk instalasi git (hanya interaktif).
|
||||
- Pemeriksaan kesegaran protokol UI (membangun ulang Control UI bila skema protokol lebih baru).
|
||||
- Pembaruan pra-penerbangan opsional untuk instalasi git (hanya interaktif).
|
||||
- Pemeriksaan kebaruan protokol UI (membangun ulang Control UI saat skema protokol lebih baru).
|
||||
- Pemeriksaan kesehatan + prompt restart.
|
||||
- Ringkasan status Skills (eligible/missing/blocked) dan status plugin.
|
||||
- Ringkasan status Skills (memenuhi syarat/tidak ada/terblokir) dan status plugin.
|
||||
- Normalisasi konfigurasi untuk nilai lama.
|
||||
- Migrasi konfigurasi Talk dari field datar lama `talk.*` ke `talk.provider` + `talk.providers.<provider>`.
|
||||
- Migrasi konfigurasi Talk dari field datar `talk.*` lama ke `talk.provider` + `talk.providers.<provider>`.
|
||||
- Pemeriksaan migrasi browser untuk konfigurasi ekstensi Chrome lama dan kesiapan Chrome MCP.
|
||||
- Peringatan override provider OpenCode (`models.providers.opencode` / `models.providers.opencode-go`).
|
||||
- Peringatan shadowing Codex OAuth (`models.providers.openai-codex`).
|
||||
- Pemeriksaan prasyarat OAuth TLS untuk profil OpenAI Codex OAuth.
|
||||
- Migrasi status lama di disk (sesi/dir agen/auth WhatsApp).
|
||||
- Peringatan shadowing OAuth Codex (`models.providers.openai-codex`).
|
||||
- Pemeriksaan prasyarat TLS OAuth untuk profil OAuth OpenAI Codex.
|
||||
- Migrasi status lama di disk (sesi/direktori agent/autentikasi WhatsApp).
|
||||
- Migrasi kunci kontrak manifest plugin lama (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
|
||||
- Migrasi penyimpanan cron lama (`jobId`, `schedule.cron`, field delivery/payload tingkat atas, payload `provider`, pekerjaan fallback webhook `notify: true` sederhana).
|
||||
- Inspeksi file lock sesi dan pembersihan lock usang.
|
||||
- Pemeriksaan integritas dan izin status (sessions, transcripts, state dir).
|
||||
- Pemeriksaan izin file konfigurasi (chmod 600) saat berjalan secara lokal.
|
||||
- Kesehatan auth model: memeriksa kedaluwarsa OAuth, dapat me-refresh token yang akan kedaluwarsa, dan melaporkan status cooldown/nonaktif profil auth.
|
||||
- Deteksi dir workspace tambahan (`~/openclaw`).
|
||||
- Migrasi penyimpanan Cron lama (`jobId`, `schedule.cron`, field delivery/payload tingkat atas, payload `provider`, pekerjaan fallback Webhook sederhana `notify: true`).
|
||||
- Inspeksi file kunci sesi dan pembersihan kunci usang.
|
||||
- Pemeriksaan integritas dan izin status (sesi, transkrip, direktori status).
|
||||
- Pemeriksaan izin file konfigurasi (`chmod 600`) saat berjalan secara lokal.
|
||||
- Kesehatan autentikasi model: memeriksa kedaluwarsa OAuth, dapat menyegarkan token yang akan kedaluwarsa, dan melaporkan status cooldown/nonaktif profil autentikasi.
|
||||
- Deteksi direktori workspace tambahan (`~/openclaw`).
|
||||
- Perbaikan image sandbox saat sandboxing diaktifkan.
|
||||
- Migrasi layanan lama dan deteksi gateway tambahan.
|
||||
- Migrasi status lama kanal Matrix (dalam mode `--fix` / `--repair`).
|
||||
- Pemeriksaan runtime gateway (layanan terpasang tetapi tidak berjalan; label launchd yang di-cache).
|
||||
- Peringatan status kanal (diprobe dari gateway yang berjalan).
|
||||
- Migrasi status lama channel Matrix (dalam mode `--fix` / `--repair`).
|
||||
- Pemeriksaan runtime Gateway (layanan terpasang tetapi tidak berjalan; label launchd yang di-cache).
|
||||
- Peringatan status channel (diprobe dari gateway yang sedang berjalan).
|
||||
- Audit konfigurasi supervisor (launchd/systemd/schtasks) dengan perbaikan opsional.
|
||||
- Pemeriksaan best practice runtime gateway (Node vs Bun, path version manager).
|
||||
- Diagnostik benturan port gateway (default `18789`).
|
||||
- Pemeriksaan praktik terbaik runtime Gateway (Node vs Bun, path version manager).
|
||||
- Diagnostik benturan port Gateway (default `18789`).
|
||||
- Peringatan keamanan untuk kebijakan DM terbuka.
|
||||
- Pemeriksaan auth gateway untuk mode token lokal (menawarkan pembuatan token saat tidak ada sumber token; tidak menimpa konfigurasi token SecretRef).
|
||||
- Pemeriksaan autentikasi Gateway untuk mode token lokal (menawarkan pembuatan token saat tidak ada sumber token; tidak menimpa konfigurasi token SecretRef).
|
||||
- Deteksi masalah pairing perangkat (permintaan pair pertama kali yang tertunda, peningkatan role/scope yang tertunda, drift cache token perangkat lokal yang usang, dan drift autentikasi paired-record).
|
||||
- Pemeriksaan linger systemd di Linux.
|
||||
- Pemeriksaan ukuran file bootstrap workspace (peringatan pemotongan/hampir batas untuk file konteks).
|
||||
- Pemeriksaan status shell completion dan auto-install/upgrade.
|
||||
- Pemeriksaan kesiapan provider embedding memory search (model lokal, kunci API jarak jauh, atau biner QMD).
|
||||
- Pemeriksaan instalasi sumber (ketidakcocokan workspace pnpm, aset UI hilang, biner tsx hilang).
|
||||
- Menulis konfigurasi yang diperbarui + metadata wizard.
|
||||
- Pemeriksaan ukuran file bootstrap workspace (peringatan pemotongan/mendekati batas untuk file konteks).
|
||||
- Pemeriksaan status shell completion serta instalasi/peningkatan otomatis.
|
||||
- Pemeriksaan kesiapan provider embedding pencarian memori (model lokal, kunci API jarak jauh, atau biner QMD).
|
||||
- Pemeriksaan instalasi source (ketidakcocokan workspace pnpm, aset UI yang hilang, biner tsx yang hilang).
|
||||
- Menulis konfigurasi + metadata wizard yang diperbarui.
|
||||
|
||||
## Backfill dan reset UI Dreams
|
||||
|
||||
Scene Dreams di Control UI mencakup tindakan **Backfill**, **Reset**, dan **Clear Grounded**
|
||||
untuk alur grounded dreaming. Tindakan ini menggunakan metode RPC
|
||||
bergaya gateway doctor, tetapi **bukan** bagian dari perbaikan/migrasi CLI
|
||||
`openclaw doctor`.
|
||||
bergaya doctor gateway, tetapi tindakan ini **bukan** bagian dari perbaikan/migrasi CLI `openclaw doctor`.
|
||||
|
||||
Yang dilakukan:
|
||||
|
||||
- **Backfill** memindai file `memory/YYYY-MM-DD.md` historis di
|
||||
workspace aktif, menjalankan pass diary REM grounded, dan menulis entri
|
||||
backfill yang dapat dibalik ke `DREAMS.md`.
|
||||
- **Reset** hanya menghapus entri diary backfill bertanda tersebut dari `DREAMS.md`.
|
||||
- **Clear Grounded** hanya menghapus entri jangka pendek staged khusus grounded yang
|
||||
berasal dari replay historis dan belum mengakumulasi recall live atau dukungan
|
||||
harian.
|
||||
- **Backfill** memindai file `memory/YYYY-MM-DD.md` historis di workspace
|
||||
aktif, menjalankan proses diary REM grounded, dan menulis entri backfill yang dapat dibalik ke `DREAMS.md`.
|
||||
- **Reset** hanya menghapus entri diary backfill yang ditandai tersebut dari `DREAMS.md`.
|
||||
- **Clear Grounded** hanya menghapus entri jangka pendek khusus grounded yang ditahap
|
||||
yang berasal dari replay historis dan belum mengumpulkan recall langsung atau
|
||||
dukungan harian.
|
||||
|
||||
Yang **tidak** dilakukan dengan sendirinya:
|
||||
Yang **tidak** dilakukan sendiri oleh tindakan ini:
|
||||
|
||||
- tindakan tersebut tidak mengedit `MEMORY.md`
|
||||
- tindakan tersebut tidak menjalankan migrasi doctor penuh
|
||||
- tindakan tersebut tidak otomatis men-stage kandidat grounded ke dalam penyimpanan
|
||||
promosi jangka pendek live kecuali Anda secara eksplisit menjalankan path CLI staged terlebih dahulu
|
||||
- tindakan ini tidak mengedit `MEMORY.md`
|
||||
- tindakan ini tidak menjalankan migrasi doctor penuh
|
||||
- tindakan ini tidak otomatis menahapkan kandidat grounded ke penyimpanan promosi jangka pendek langsung
|
||||
kecuali Anda secara eksplisit menjalankan jalur CLI yang ditahap terlebih dahulu
|
||||
|
||||
Jika Anda ingin replay historis grounded memengaruhi lane deep promotion
|
||||
normal, gunakan alur CLI berikut:
|
||||
Jika Anda ingin replay historis grounded memengaruhi jalur promosi mendalam normal,
|
||||
gunakan alur CLI sebagai gantinya:
|
||||
|
||||
```bash
|
||||
openclaw memory rem-backfill --path ./memory --stage-short-term
|
||||
```
|
||||
|
||||
Perintah itu men-stage kandidat durable grounded ke penyimpanan dreaming jangka pendek sambil
|
||||
tetap menjadikan `DREAMS.md` sebagai permukaan peninjauan.
|
||||
Itu menahapkan kandidat durable grounded ke penyimpanan dreaming jangka pendek sambil
|
||||
menjaga `DREAMS.md` sebagai permukaan tinjauan.
|
||||
|
||||
## Perilaku dan alasan terperinci
|
||||
|
||||
### 0) Pembaruan opsional (instalasi git)
|
||||
|
||||
Jika ini adalah checkout git dan doctor berjalan secara interaktif, doctor menawarkan untuk
|
||||
Jika ini adalah checkout git dan doctor berjalan secara interaktif, doctor akan menawarkan untuk
|
||||
memperbarui (fetch/rebase/build) sebelum menjalankan doctor.
|
||||
|
||||
### 1) Normalisasi konfigurasi
|
||||
|
||||
Jika konfigurasi berisi bentuk nilai lama (misalnya `messages.ackReaction`
|
||||
tanpa override spesifik kanal), doctor menormalisasikannya ke dalam skema
|
||||
saat ini.
|
||||
tanpa override khusus channel), doctor menormalkannya ke
|
||||
skema saat ini.
|
||||
|
||||
Itu termasuk field datar Talk lama. Konfigurasi Talk publik saat ini adalah
|
||||
`talk.provider` + `talk.providers.<provider>`. Doctor menulis ulang bentuk lama
|
||||
@ -155,18 +153,18 @@ Itu termasuk field datar Talk lama. Konfigurasi Talk publik saat ini adalah
|
||||
|
||||
### 2) Migrasi kunci konfigurasi lama
|
||||
|
||||
Saat konfigurasi berisi kunci yang sudah deprecated, perintah lain menolak berjalan dan meminta
|
||||
Saat konfigurasi berisi kunci yang sudah usang, perintah lain akan menolak berjalan dan meminta
|
||||
Anda menjalankan `openclaw doctor`.
|
||||
|
||||
Doctor akan:
|
||||
|
||||
- Menjelaskan kunci lama mana yang ditemukan.
|
||||
- Menampilkan migrasi yang diterapkannya.
|
||||
- Menampilkan migrasi yang diterapkan.
|
||||
- Menulis ulang `~/.openclaw/openclaw.json` dengan skema yang diperbarui.
|
||||
|
||||
Gateway juga otomatis menjalankan migrasi doctor saat startup ketika mendeteksi
|
||||
format konfigurasi lama, sehingga konfigurasi usang diperbaiki tanpa intervensi manual.
|
||||
Migrasi penyimpanan pekerjaan cron ditangani oleh `openclaw doctor --fix`.
|
||||
Migrasi penyimpanan pekerjaan Cron ditangani oleh `openclaw doctor --fix`.
|
||||
|
||||
Migrasi saat ini:
|
||||
|
||||
@ -190,7 +188,7 @@ Migrasi saat ini:
|
||||
- `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold`
|
||||
→ `plugins.entries.voice-call.config.streaming.providers.openai.*`
|
||||
- `bindings[].match.accountID` → `bindings[].match.accountId`
|
||||
- Untuk kanal dengan `accounts` bernama tetapi masih memiliki nilai kanal tingkat atas akun tunggal, pindahkan nilai yang dicakup akun tersebut ke akun yang dipromosikan dan dipilih untuk kanal itu (`accounts.default` untuk sebagian besar kanal; Matrix dapat mempertahankan target bernama/default yang sudah cocok)
|
||||
- Untuk channel dengan `accounts` bernama tetapi masih memiliki nilai channel tingkat atas akun tunggal, pindahkan nilai yang dicakup akun tersebut ke akun yang dipromosikan yang dipilih untuk channel tersebut (`accounts.default` untuk sebagian besar channel; Matrix dapat mempertahankan target bernama/default yang cocok yang sudah ada)
|
||||
- `identity` → `agents.list[].identity`
|
||||
- `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents)
|
||||
- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks`
|
||||
@ -199,32 +197,31 @@ Migrasi saat ini:
|
||||
- `browser.profiles.*.driver: "extension"` → `"existing-session"`
|
||||
- hapus `browser.relayBindHost` (pengaturan relay ekstensi lama)
|
||||
|
||||
Peringatan doctor juga mencakup panduan account-default untuk kanal multi-akun:
|
||||
Peringatan doctor juga mencakup panduan default akun untuk channel multi-akun:
|
||||
|
||||
- Jika dua atau lebih entri `channels.<channel>.accounts` dikonfigurasi tanpa `channels.<channel>.defaultAccount` atau `accounts.default`, doctor memperingatkan bahwa fallback routing dapat memilih akun yang tidak terduga.
|
||||
- Jika dua atau lebih entri `channels.<channel>.accounts` dikonfigurasi tanpa `channels.<channel>.defaultAccount` atau `accounts.default`, doctor memperingatkan bahwa routing fallback dapat memilih akun yang tidak diharapkan.
|
||||
- Jika `channels.<channel>.defaultAccount` diatur ke ID akun yang tidak dikenal, doctor memperingatkan dan mencantumkan ID akun yang dikonfigurasi.
|
||||
|
||||
### 2b) Override provider OpenCode
|
||||
|
||||
Jika Anda menambahkan `models.providers.opencode`, `opencode-zen`, atau `opencode-go`
|
||||
secara manual, itu akan menimpa katalog OpenCode bawaan dari `@mariozechner/pi-ai`.
|
||||
Hal itu dapat memaksa model ke API yang salah atau men-nol-kan biaya. Doctor memperingatkan agar Anda
|
||||
dapat menghapus override dan memulihkan perutean API + biaya per model.
|
||||
secara manual, itu akan meng-override katalog OpenCode bawaan dari `@mariozechner/pi-ai`.
|
||||
Ini dapat memaksa model ke API yang salah atau membuat biaya menjadi nol. Doctor memperingatkan agar Anda
|
||||
dapat menghapus override tersebut dan memulihkan routing API per-model + biaya.
|
||||
|
||||
### 2c) Migrasi browser dan kesiapan Chrome MCP
|
||||
|
||||
Jika konfigurasi browser Anda masih menunjuk ke path ekstensi Chrome yang sudah dihapus, doctor
|
||||
menormalisasikannya ke model attach Chrome MCP host-lokal saat ini:
|
||||
Jika konfigurasi browser Anda masih menunjuk ke jalur ekstensi Chrome yang telah dihapus, doctor
|
||||
menormalkannya ke model attach Chrome MCP host-lokal saat ini:
|
||||
|
||||
- `browser.profiles.*.driver: "extension"` menjadi `"existing-session"`
|
||||
- `browser.relayBindHost` dihapus
|
||||
|
||||
Doctor juga mengaudit path Chrome MCP host-lokal saat Anda menggunakan `defaultProfile:
|
||||
Doctor juga mengaudit jalur Chrome MCP host-lokal saat Anda menggunakan `defaultProfile:
|
||||
"user"` atau profil `existing-session` yang dikonfigurasi:
|
||||
|
||||
- memeriksa apakah Google Chrome terinstal pada host yang sama untuk profil
|
||||
auto-connect default
|
||||
- memeriksa versi Chrome yang terdeteksi dan memperingatkan bila di bawah Chrome 144
|
||||
- memeriksa apakah Google Chrome terpasang pada host yang sama untuk profil auto-connect default
|
||||
- memeriksa versi Chrome yang terdeteksi dan memperingatkan jika di bawah Chrome 144
|
||||
- mengingatkan Anda untuk mengaktifkan remote debugging di halaman inspect browser (misalnya
|
||||
`chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`,
|
||||
atau `edge://inspect/#remote-debugging`)
|
||||
@ -237,91 +234,90 @@ tetap memerlukan:
|
||||
- remote debugging diaktifkan di browser tersebut
|
||||
- menyetujui prompt persetujuan attach pertama di browser
|
||||
|
||||
Kesiapan di sini hanya tentang prasyarat attach lokal. Existing-session mempertahankan
|
||||
batas route Chrome MCP saat ini; route lanjutan seperti `responsebody`, ekspor PDF,
|
||||
intersepsi unduhan, dan tindakan batch tetap memerlukan browser yang dikelola
|
||||
Kesiapan di sini hanya terkait prasyarat attach lokal. Existing-session mempertahankan
|
||||
batas rute Chrome MCP saat ini; rute lanjutan seperti `responsebody`, ekspor PDF,
|
||||
intersepsi unduhan, dan tindakan batch tetap memerlukan browser terkelola
|
||||
atau profil CDP mentah.
|
||||
|
||||
Pemeriksaan ini **tidak** berlaku untuk Docker, sandbox, remote-browser, atau alur
|
||||
headless lainnya. Semua itu tetap menggunakan CDP mentah.
|
||||
Pemeriksaan ini **tidak** berlaku untuk Docker, sandbox, remote-browser, atau alur headless lainnya. Alur tersebut tetap menggunakan CDP mentah.
|
||||
|
||||
### 2d) Prasyarat OAuth TLS
|
||||
### 2d) Prasyarat TLS OAuth
|
||||
|
||||
Saat profil OpenAI Codex OAuth dikonfigurasi, doctor mem-probe endpoint
|
||||
otorisasi OpenAI untuk memverifikasi bahwa stack TLS Node/OpenSSL lokal dapat
|
||||
memvalidasi rantai sertifikat. Jika probe gagal dengan kesalahan sertifikat (misalnya
|
||||
`UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, sertifikat kedaluwarsa, atau self-signed cert),
|
||||
doctor mencetak panduan perbaikan spesifik platform. Di macOS dengan Homebrew Node,
|
||||
perbaikannya biasanya `brew postinstall ca-certificates`. Dengan `--deep`, probe berjalan
|
||||
Saat profil OAuth OpenAI Codex dikonfigurasi, doctor memeriksa endpoint otorisasi OpenAI
|
||||
untuk memverifikasi bahwa stack TLS Node/OpenSSL lokal dapat
|
||||
memvalidasi rantai sertifikat. Jika pemeriksaan gagal dengan kesalahan sertifikat (misalnya
|
||||
`UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, sertifikat kedaluwarsa, atau sertifikat self-signed),
|
||||
doctor mencetak panduan perbaikan khusus platform. Di macOS dengan Node Homebrew,
|
||||
perbaikannya biasanya `brew postinstall ca-certificates`. Dengan `--deep`, pemeriksaan berjalan
|
||||
bahkan jika gateway sehat.
|
||||
|
||||
### 2c) Override provider Codex OAuth
|
||||
### 2c) Override provider OAuth Codex
|
||||
|
||||
Jika sebelumnya Anda menambahkan pengaturan transport OpenAI lama di bawah
|
||||
`models.providers.openai-codex`, pengaturan itu dapat membayangi path provider Codex OAuth
|
||||
bawaan yang digunakan otomatis oleh rilis yang lebih baru. Doctor memperingatkan saat melihat
|
||||
pengaturan transport lama tersebut bersama Codex OAuth agar Anda dapat menghapus atau menulis ulang
|
||||
override transport usang dan mendapatkan kembali perilaku routing/fallback bawaan.
|
||||
Proxy kustom dan override hanya-header tetap didukung dan tidak
|
||||
Jika Anda sebelumnya menambahkan pengaturan transport OpenAI lama di bawah
|
||||
`models.providers.openai-codex`, pengaturan tersebut dapat membayangi jalur provider
|
||||
OAuth Codex bawaan yang digunakan otomatis oleh rilis yang lebih baru. Doctor memperingatkan saat melihat
|
||||
pengaturan transport lama tersebut bersamaan dengan OAuth Codex agar Anda dapat menghapus atau menulis ulang
|
||||
override transport usang tersebut dan mendapatkan kembali perilaku routing/fallback
|
||||
bawaan. Proxy kustom dan override khusus header tetap didukung dan tidak
|
||||
memicu peringatan ini.
|
||||
|
||||
### 3) Migrasi status lama (layout disk)
|
||||
### 3) Migrasi status lama (tata letak disk)
|
||||
|
||||
Doctor dapat memigrasikan layout lama di disk ke struktur saat ini:
|
||||
Doctor dapat memigrasikan tata letak lama di disk ke struktur saat ini:
|
||||
|
||||
- Penyimpanan sesi + transkrip:
|
||||
- dari `~/.openclaw/sessions/` ke `~/.openclaw/agents/<agentId>/sessions/`
|
||||
- Dir agen:
|
||||
- Direktori agent:
|
||||
- dari `~/.openclaw/agent/` ke `~/.openclaw/agents/<agentId>/agent/`
|
||||
- Status auth WhatsApp (Baileys):
|
||||
- Status autentikasi WhatsApp (Baileys):
|
||||
- dari `~/.openclaw/credentials/*.json` lama (kecuali `oauth.json`)
|
||||
- ke `~/.openclaw/credentials/whatsapp/<accountId>/...` (ID akun default: `default`)
|
||||
|
||||
Migrasi ini bersifat best-effort dan idempoten; doctor akan mengeluarkan peringatan saat
|
||||
meninggalkan folder lama sebagai cadangan. Gateway/CLI juga memigrasikan otomatis
|
||||
sesi lama + dir agen saat startup sehingga riwayat/auth/model berada di
|
||||
path per-agen tanpa perlu menjalankan doctor secara manual. Auth WhatsApp sengaja hanya
|
||||
dimigrasikan melalui `openclaw doctor`. Normalisasi provider/peta provider Talk kini
|
||||
membandingkan berdasarkan kesetaraan struktural, sehingga perbedaan urutan kunci saja tidak lagi
|
||||
memicu perubahan no-op `doctor --fix` yang berulang.
|
||||
meninggalkan folder lama sebagai cadangan. Gateway/CLI juga otomatis memigrasikan
|
||||
sesi lama + direktori agent saat startup sehingga riwayat/autentikasi/model masuk ke
|
||||
path per-agent tanpa perlu menjalankan doctor secara manual. Autentikasi WhatsApp sengaja hanya
|
||||
dimigrasikan melalui `openclaw doctor`. Normalisasi provider/peta provider Talk sekarang
|
||||
membandingkan berdasarkan kesetaraan struktural, sehingga perbedaan urutan kunci saja tidak lagi memicu
|
||||
perubahan no-op `doctor --fix` berulang.
|
||||
|
||||
### 3a) Migrasi manifest plugin lama
|
||||
|
||||
Doctor memindai semua manifest plugin yang terinstal untuk kunci kapabilitas tingkat atas
|
||||
yang sudah deprecated (`speechProviders`, `realtimeTranscriptionProviders`,
|
||||
Doctor memindai semua manifest plugin yang terinstal untuk mencari capability tingkat atas yang sudah usang
|
||||
(`speechProviders`, `realtimeTranscriptionProviders`,
|
||||
`realtimeVoiceProviders`, `mediaUnderstandingProviders`,
|
||||
`imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`,
|
||||
`webSearchProviders`). Saat ditemukan, doctor menawarkan untuk memindahkannya ke objek `contracts`
|
||||
dan menulis ulang file manifest di tempat. Migrasi ini idempoten;
|
||||
jika kunci `contracts` sudah memiliki nilai yang sama, kunci lama dihapus
|
||||
jika kunci `contracts` sudah memiliki nilai yang sama, kunci lama akan dihapus
|
||||
tanpa menduplikasi data.
|
||||
|
||||
### 3b) Migrasi penyimpanan cron lama
|
||||
### 3b) Migrasi penyimpanan Cron lama
|
||||
|
||||
Doctor juga memeriksa penyimpanan pekerjaan cron (`~/.openclaw/cron/jobs.json` secara default,
|
||||
atau `cron.store` jika di-override) untuk bentuk pekerjaan lama yang masih diterima
|
||||
scheduler demi kompatibilitas.
|
||||
Doctor juga memeriksa penyimpanan pekerjaan Cron (`~/.openclaw/cron/jobs.json` secara default,
|
||||
atau `cron.store` jika dioverride) untuk bentuk pekerjaan lama yang masih
|
||||
diterima scheduler demi kompatibilitas.
|
||||
|
||||
Pembersihan cron saat ini mencakup:
|
||||
Pembersihan Cron saat ini mencakup:
|
||||
|
||||
- `jobId` → `id`
|
||||
- `schedule.cron` → `schedule.expr`
|
||||
- field payload tingkat atas (`message`, `model`, `thinking`, ...) → `payload`
|
||||
- field delivery tingkat atas (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
|
||||
- alias delivery `provider` pada payload → `delivery.channel` eksplisit
|
||||
- pekerjaan fallback webhook lama `notify: true` sederhana → `delivery.mode="webhook"` eksplisit dengan `delivery.to=cron.webhook`
|
||||
- pekerjaan fallback Webhook `notify: true` lama yang sederhana → `delivery.mode="webhook"` eksplisit dengan `delivery.to=cron.webhook`
|
||||
|
||||
Doctor hanya otomatis memigrasikan pekerjaan `notify: true` bila hal itu dapat dilakukan tanpa
|
||||
mengubah perilaku. Jika suatu pekerjaan menggabungkan fallback notify lama dengan mode
|
||||
delivery non-webhook yang sudah ada, doctor memperingatkan dan membiarkan pekerjaan tersebut untuk ditinjau manual.
|
||||
Doctor hanya memigrasikan otomatis pekerjaan `notify: true` saat dapat melakukannya tanpa
|
||||
mengubah perilaku. Jika sebuah pekerjaan menggabungkan fallback notify lama dengan mode delivery
|
||||
non-webhook yang sudah ada, doctor akan memperingatkan dan membiarkan pekerjaan tersebut untuk ditinjau secara manual.
|
||||
|
||||
### 3c) Pembersihan lock sesi
|
||||
### 3c) Pembersihan kunci sesi
|
||||
|
||||
Doctor memindai setiap direktori sesi agen untuk file write-lock usang — file yang tertinggal
|
||||
saat suatu sesi keluar secara abnormal. Untuk setiap file lock yang ditemukan, doctor melaporkan:
|
||||
path, PID, apakah PID masih hidup, usia lock, dan apakah lock tersebut
|
||||
dianggap usang (PID mati atau lebih tua dari 30 menit). Dalam mode `--fix` / `--repair`
|
||||
doctor menghapus file lock usang secara otomatis; jika tidak, doctor mencetak catatan dan
|
||||
Doctor memindai setiap direktori sesi agent untuk file kunci tulis usang — file yang tertinggal
|
||||
saat sebuah sesi keluar secara tidak normal. Untuk setiap file kunci yang ditemukan, doctor melaporkan:
|
||||
path, PID, apakah PID masih hidup, usia kunci, dan apakah kunci tersebut
|
||||
dianggap usang (PID mati atau lebih lama dari 30 menit). Dalam mode `--fix` / `--repair`,
|
||||
doctor menghapus file kunci usang secara otomatis; jika tidak, doctor mencetak catatan dan
|
||||
menginstruksikan Anda untuk menjalankan ulang dengan `--fix`.
|
||||
|
||||
### 4) Pemeriksaan integritas status (persistensi sesi, routing, dan keamanan)
|
||||
@ -331,116 +327,144 @@ sesi, kredensial, log, dan konfigurasi (kecuali Anda memiliki cadangan di tempat
|
||||
|
||||
Doctor memeriksa:
|
||||
|
||||
- **State dir hilang**: memperingatkan kehilangan status yang katastrofik, meminta untuk membuat ulang
|
||||
- **Direktori status hilang**: memperingatkan tentang kehilangan status yang katastrofik, meminta untuk membuat ulang
|
||||
direktori, dan mengingatkan bahwa doctor tidak dapat memulihkan data yang hilang.
|
||||
- **Izin state dir**: memverifikasi dapat ditulis; menawarkan untuk memperbaiki izin
|
||||
- **Izin direktori status**: memverifikasi bahwa direktori dapat ditulis; menawarkan perbaikan izin
|
||||
(dan mengeluarkan petunjuk `chown` saat terdeteksi ketidakcocokan owner/group).
|
||||
- **State dir tersinkron cloud di macOS**: memperingatkan saat status ter-resolve di bawah iCloud Drive
|
||||
- **Direktori status macOS yang disinkronkan cloud**: memperingatkan saat status berada di bawah iCloud Drive
|
||||
(`~/Library/Mobile Documents/com~apple~CloudDocs/...`) atau
|
||||
`~/Library/CloudStorage/...` karena path yang didukung sinkronisasi dapat menyebabkan I/O lebih lambat
|
||||
dan race lock/sinkronisasi.
|
||||
- **State dir Linux di SD atau eMMC**: memperingatkan saat status ter-resolve ke sumber mount `mmcblk*`,
|
||||
karena random I/O yang didukung SD atau eMMC bisa lebih lambat dan lebih cepat aus
|
||||
di bawah penulisan sesi dan kredensial.
|
||||
- **Dir sesi hilang**: `sessions/` dan direktori penyimpanan sesi
|
||||
`~/Library/CloudStorage/...` karena path yang didukung sinkronisasi dapat menyebabkan I/O
|
||||
lebih lambat dan race lock/sinkronisasi.
|
||||
- **Direktori status Linux pada SD atau eMMC**: memperingatkan saat status berada pada sumber mount `mmcblk*`,
|
||||
karena I/O acak yang didukung SD atau eMMC bisa lebih lambat dan lebih cepat aus
|
||||
saat penulisan sesi dan kredensial.
|
||||
- **Direktori sesi hilang**: `sessions/` dan direktori penyimpanan sesi
|
||||
diperlukan untuk mempertahankan riwayat dan menghindari crash `ENOENT`.
|
||||
- **Ketidakcocokan transkrip**: memperingatkan saat entri sesi terbaru memiliki file
|
||||
transkrip yang hilang.
|
||||
- **Sesi utama “1-line JSONL”**: menandai saat transkrip utama hanya memiliki satu
|
||||
- **Sesi utama “JSONL 1 baris”**: menandai saat transkrip utama hanya memiliki satu
|
||||
baris (riwayat tidak terakumulasi).
|
||||
- **Beberapa state dir**: memperingatkan saat beberapa folder `~/.openclaw` ada di berbagai
|
||||
- **Beberapa direktori status**: memperingatkan saat ada beberapa folder `~/.openclaw` di berbagai
|
||||
direktori home atau saat `OPENCLAW_STATE_DIR` menunjuk ke tempat lain (riwayat dapat
|
||||
terpecah antar instalasi).
|
||||
terpecah di beberapa instalasi).
|
||||
- **Pengingat mode remote**: jika `gateway.mode=remote`, doctor mengingatkan Anda untuk menjalankannya
|
||||
di host remote (status berada di sana).
|
||||
- **Izin file konfigurasi**: memperingatkan jika `~/.openclaw/openclaw.json` dapat
|
||||
dibaca group/world dan menawarkan untuk memperketat ke `600`.
|
||||
- **Izin file konfigurasi**: memperingatkan jika `~/.openclaw/openclaw.json` dapat dibaca
|
||||
oleh group/dunia dan menawarkan untuk memperketatnya menjadi `600`.
|
||||
|
||||
### 5) Kesehatan auth model (kedaluwarsa OAuth)
|
||||
### 5) Kesehatan autentikasi model (kedaluwarsa OAuth)
|
||||
|
||||
Doctor memeriksa profil OAuth di penyimpanan auth, memperingatkan saat token akan
|
||||
kedaluwarsa/sudah kedaluwarsa, dan dapat me-refresh token saat aman. Jika profil
|
||||
OAuth/token Anthropic usang, doctor menyarankan Anthropic API key atau path
|
||||
setup-token Anthropic.
|
||||
Prompt refresh hanya muncul saat berjalan secara interaktif (TTY); `--non-interactive`
|
||||
melewati upaya refresh.
|
||||
Doctor memeriksa profil OAuth di penyimpanan autentikasi, memperingatkan saat token
|
||||
akan kedaluwarsa/sudah kedaluwarsa, dan dapat menyegarkannya jika aman. Jika profil
|
||||
OAuth/token Anthropic usang, doctor menyarankan API key Anthropic atau
|
||||
jalur setup-token Anthropic.
|
||||
Prompt penyegaran hanya muncul saat berjalan secara interaktif (TTY); `--non-interactive`
|
||||
melewati upaya penyegaran.
|
||||
|
||||
Saat refresh OAuth gagal permanen (misalnya `refresh_token_reused`,
|
||||
`invalid_grant`, atau provider memberi tahu Anda untuk sign in lagi), doctor melaporkan
|
||||
bahwa re-auth diperlukan dan mencetak perintah `openclaw models auth login --provider ...`
|
||||
Saat penyegaran OAuth gagal secara permanen (misalnya `refresh_token_reused`,
|
||||
`invalid_grant`, atau provider memberi tahu Anda untuk masuk lagi), doctor melaporkan
|
||||
bahwa autentikasi ulang diperlukan dan mencetak perintah `openclaw models auth login --provider ...`
|
||||
yang tepat untuk dijalankan.
|
||||
|
||||
Doctor juga melaporkan profil auth yang sementara tidak dapat digunakan karena:
|
||||
Doctor juga melaporkan profil autentikasi yang sementara tidak dapat digunakan karena:
|
||||
|
||||
- cooldown singkat (rate limit/timeout/kegagalan auth)
|
||||
- penonaktifan lebih lama (kegagalan billing/kredit)
|
||||
- cooldown singkat (batas laju/timeout/kegagalan autentikasi)
|
||||
- penonaktifan yang lebih lama (kegagalan billing/kredit)
|
||||
|
||||
### 6) Validasi model hooks
|
||||
|
||||
Jika `hooks.gmail.model` diatur, doctor memvalidasi referensi model terhadap
|
||||
katalog dan allowlist serta memperingatkan saat referensi itu tidak akan ter-resolve atau tidak diizinkan.
|
||||
katalog dan allowlist serta memperingatkan jika referensi tersebut tidak akan ter-resolve atau tidak diizinkan.
|
||||
|
||||
### 7) Perbaikan image sandbox
|
||||
|
||||
Saat sandboxing diaktifkan, doctor memeriksa image Docker dan menawarkan untuk membangun atau
|
||||
beralih ke nama lama jika image saat ini hilang.
|
||||
beralih ke nama lama jika image saat ini tidak ada.
|
||||
|
||||
### 7b) Dependensi runtime plugin bawaan
|
||||
|
||||
Doctor memverifikasi bahwa dependensi runtime plugin bawaan (misalnya paket
|
||||
runtime plugin Discord) ada di root instalasi OpenClaw.
|
||||
Doctor memverifikasi bahwa dependensi runtime plugin bawaan (misalnya paket runtime plugin
|
||||
Discord) ada di root instalasi OpenClaw.
|
||||
Jika ada yang hilang, doctor melaporkan paket tersebut dan menginstalnya dalam
|
||||
mode `openclaw doctor --fix` / `openclaw doctor --repair`.
|
||||
|
||||
### 8) Migrasi layanan gateway dan petunjuk pembersihan
|
||||
### 8) Migrasi layanan Gateway dan petunjuk pembersihan
|
||||
|
||||
Doctor mendeteksi layanan gateway lama (launchd/systemd/schtasks) dan
|
||||
menawarkan untuk menghapusnya serta memasang layanan OpenClaw menggunakan port gateway
|
||||
saat ini. Doctor juga dapat memindai layanan mirip gateway tambahan dan mencetak petunjuk pembersihan.
|
||||
Layanan gateway OpenClaw bernama profil dianggap first-class dan tidak
|
||||
menawarkan untuk menghapusnya serta menginstal layanan OpenClaw menggunakan port gateway
|
||||
saat ini. Doctor juga dapat memindai layanan tambahan yang menyerupai gateway dan mencetak petunjuk pembersihan.
|
||||
Layanan gateway OpenClaw bernama profil dianggap sebagai kelas utama dan tidak
|
||||
ditandai sebagai "tambahan".
|
||||
|
||||
### 8b) Migrasi startup Matrix
|
||||
### 8b) Migrasi Matrix saat startup
|
||||
|
||||
Saat akun kanal Matrix memiliki migrasi status lama yang tertunda atau dapat ditindaklanjuti,
|
||||
Saat akun channel Matrix memiliki migrasi status lama yang tertunda atau dapat ditindaklanjuti,
|
||||
doctor (dalam mode `--fix` / `--repair`) membuat snapshot pra-migrasi lalu
|
||||
menjalankan langkah migrasi best-effort: migrasi status Matrix lama dan persiapan
|
||||
status terenkripsi lama. Kedua langkah bersifat non-fatal; kesalahan dicatat dan
|
||||
startup berlanjut. Dalam mode baca-saja (`openclaw doctor` tanpa `--fix`) pemeriksaan ini
|
||||
status terenkripsi lama. Kedua langkah tidak fatal; kesalahan dicatat dalam log dan
|
||||
startup tetap berlanjut. Dalam mode hanya-baca (`openclaw doctor` tanpa `--fix`) pemeriksaan ini
|
||||
dilewati sepenuhnya.
|
||||
|
||||
### 8c) Pairing perangkat dan drift autentikasi
|
||||
|
||||
Doctor sekarang memeriksa status pairing perangkat sebagai bagian dari pemeriksaan kesehatan normal.
|
||||
|
||||
Yang dilaporkan:
|
||||
|
||||
- permintaan pairing pertama kali yang tertunda
|
||||
- peningkatan role yang tertunda untuk perangkat yang sudah dipair
|
||||
- peningkatan scope yang tertunda untuk perangkat yang sudah dipair
|
||||
- perbaikan ketidakcocokan kunci publik saat ID perangkat masih cocok tetapi identitas
|
||||
perangkat tidak lagi cocok dengan catatan yang disetujui
|
||||
- catatan pairing yang tidak memiliki token aktif untuk role yang disetujui
|
||||
- token pairing yang scopenya menyimpang di luar baseline pairing yang disetujui
|
||||
- entri token perangkat cache lokal untuk mesin saat ini yang lebih lama dari
|
||||
rotasi token sisi gateway atau membawa metadata scope yang usang
|
||||
|
||||
Doctor tidak otomatis menyetujui permintaan pairing atau otomatis merotasi token perangkat. Doctor
|
||||
mencetak langkah berikutnya yang tepat:
|
||||
|
||||
- periksa permintaan yang tertunda dengan `openclaw devices list`
|
||||
- setujui permintaan yang tepat dengan `openclaw devices approve <requestId>`
|
||||
- rotasi token baru dengan `openclaw devices rotate --device <deviceId> --role <role>`
|
||||
- hapus dan setujui ulang catatan usang dengan `openclaw devices remove <deviceId>`
|
||||
|
||||
Ini menutup celah umum "sudah dipair tetapi masih mendapat pairing required":
|
||||
doctor kini membedakan pairing pertama kali dari peningkatan role/scope yang tertunda
|
||||
dan dari drift token/identitas perangkat yang usang.
|
||||
|
||||
### 9) Peringatan keamanan
|
||||
|
||||
Doctor mengeluarkan peringatan saat suatu provider terbuka untuk DM tanpa allowlist, atau
|
||||
saat suatu kebijakan dikonfigurasi dengan cara yang berbahaya.
|
||||
Doctor mengeluarkan peringatan saat sebuah provider terbuka untuk DM tanpa allowlist, atau
|
||||
saat sebuah kebijakan dikonfigurasi dengan cara yang berbahaya.
|
||||
|
||||
### 10) systemd linger (Linux)
|
||||
### 10) Linger systemd (Linux)
|
||||
|
||||
Jika berjalan sebagai layanan pengguna systemd, doctor memastikan lingering diaktifkan agar
|
||||
gateway tetap hidup setelah logout.
|
||||
|
||||
### 11) Status workspace (Skills, plugin, dan dir lama)
|
||||
### 11) Status workspace (Skills, plugin, dan direktori lama)
|
||||
|
||||
Doctor mencetak ringkasan status workspace untuk agen default:
|
||||
Doctor mencetak ringkasan status workspace untuk agent default:
|
||||
|
||||
- **Status Skills**: menghitung Skills yang eligible, missing-requirements, dan allowlist-blocked.
|
||||
- **Dir workspace lama**: memperingatkan saat `~/openclaw` atau direktori workspace lama lain
|
||||
- **Status Skills**: menghitung Skills yang memenuhi syarat, tidak memiliki persyaratan, dan diblokir oleh allowlist.
|
||||
- **Direktori workspace lama**: memperingatkan saat `~/openclaw` atau direktori workspace lama lainnya
|
||||
ada bersama workspace saat ini.
|
||||
- **Status plugin**: menghitung plugin loaded/disabled/errored; mencantumkan ID plugin untuk
|
||||
error apa pun; melaporkan kapabilitas bundle plugin.
|
||||
- **Status plugin**: menghitung plugin yang dimuat/dinonaktifkan/error; mencantumkan ID plugin untuk setiap
|
||||
error; melaporkan capability plugin bundel.
|
||||
- **Peringatan kompatibilitas plugin**: menandai plugin yang memiliki masalah kompatibilitas dengan
|
||||
runtime saat ini.
|
||||
- **Diagnostik plugin**: menampilkan peringatan atau error saat load yang dikeluarkan oleh
|
||||
registry plugin.
|
||||
- **Diagnostik plugin**: menampilkan peringatan atau error waktu muat yang dikeluarkan oleh
|
||||
registri plugin.
|
||||
|
||||
### 11b) Ukuran file bootstrap
|
||||
|
||||
Doctor memeriksa apakah file bootstrap workspace (misalnya `AGENTS.md`,
|
||||
`CLAUDE.md`, atau file konteks injeksi lainnya) mendekati atau melebihi budget karakter
|
||||
yang dikonfigurasi. Doctor melaporkan jumlah karakter mentah vs. yang diinjeksi per file, persentase
|
||||
pemotongan, penyebab pemotongan (`max/file` atau `max/total`), dan total karakter
|
||||
yang diinjeksi sebagai fraksi dari total budget. Saat file dipotong atau mendekati
|
||||
batas, doctor mencetak tips untuk menyetel `agents.defaults.bootstrapMaxChars`
|
||||
`CLAUDE.md`, atau file konteks lain yang diinjeksi) mendekati atau melebihi
|
||||
anggaran karakter yang dikonfigurasi. Doctor melaporkan jumlah karakter mentah vs. yang diinjeksi per file, persentase
|
||||
pemotongan, penyebab pemotongan (`max/file` atau `max/total`), dan total karakter yang diinjeksi
|
||||
sebagai fraksi dari total anggaran. Saat file dipotong atau mendekati
|
||||
batas, doctor mencetak tips untuk menyesuaikan `agents.defaults.bootstrapMaxChars`
|
||||
dan `agents.defaults.bootstrapTotalMaxChars`.
|
||||
|
||||
### 11c) Shell completion
|
||||
@ -448,68 +472,68 @@ dan `agents.defaults.bootstrapTotalMaxChars`.
|
||||
Doctor memeriksa apakah tab completion terinstal untuk shell saat ini
|
||||
(zsh, bash, fish, atau PowerShell):
|
||||
|
||||
- Jika profil shell menggunakan pola dynamic completion yang lambat
|
||||
- Jika profil shell menggunakan pola completion dinamis yang lambat
|
||||
(`source <(openclaw completion ...)`), doctor meningkatkannya ke varian file cache
|
||||
yang lebih cepat.
|
||||
- Jika completion dikonfigurasi di profil tetapi file cache hilang,
|
||||
doctor meregenerasi cache secara otomatis.
|
||||
- Jika tidak ada completion yang dikonfigurasi sama sekali, doctor meminta untuk menginstalnya
|
||||
- Jika completion sama sekali tidak dikonfigurasi, doctor meminta untuk menginstalnya
|
||||
(hanya mode interaktif; dilewati dengan `--non-interactive`).
|
||||
|
||||
Jalankan `openclaw completion --write-state` untuk meregenerasi cache secara manual.
|
||||
|
||||
### 12) Pemeriksaan auth gateway (token lokal)
|
||||
### 12) Pemeriksaan autentikasi Gateway (token lokal)
|
||||
|
||||
Doctor memeriksa kesiapan auth token gateway lokal.
|
||||
Doctor memeriksa kesiapan autentikasi token gateway lokal.
|
||||
|
||||
- Jika mode token memerlukan token dan tidak ada sumber token, doctor menawarkan untuk membuatnya.
|
||||
- Jika `gateway.auth.token` dikelola SecretRef tetapi tidak tersedia, doctor memperingatkan dan tidak menimpanya dengan plaintext.
|
||||
- `openclaw doctor --generate-gateway-token` memaksa pembuatan hanya saat tidak ada token SecretRef yang dikonfigurasi.
|
||||
- Jika `gateway.auth.token` dikelola oleh SecretRef tetapi tidak tersedia, doctor memperingatkan dan tidak menimpanya dengan teks biasa.
|
||||
- `openclaw doctor --generate-gateway-token` memaksa pembuatan hanya jika tidak ada SecretRef token yang dikonfigurasi.
|
||||
|
||||
### 12b) Perbaikan sadar-SecretRef baca-saja
|
||||
### 12b) Perbaikan hanya-baca yang sadar SecretRef
|
||||
|
||||
Beberapa alur perbaikan perlu memeriksa kredensial yang dikonfigurasi tanpa melemahkan perilaku fail-fast saat runtime.
|
||||
Beberapa alur perbaikan perlu memeriksa kredensial yang dikonfigurasi tanpa melemahkan perilaku fail-fast runtime.
|
||||
|
||||
- `openclaw doctor --fix` sekarang menggunakan model ringkasan SecretRef baca-saja yang sama seperti keluarga perintah status untuk perbaikan konfigurasi yang terarah.
|
||||
- Contoh: perbaikan Telegram `allowFrom` / `groupAllowFrom` `@username` mencoba menggunakan kredensial bot yang dikonfigurasi bila tersedia.
|
||||
- Jika token bot Telegram dikonfigurasi melalui SecretRef tetapi tidak tersedia dalam path perintah saat ini, doctor melaporkan bahwa kredensial tersebut dikonfigurasi-tetapi-tidak-tersedia dan melewati auto-resolution alih-alih crash atau salah melaporkan token sebagai hilang.
|
||||
- `openclaw doctor --fix` sekarang menggunakan model ringkasan SecretRef hanya-baca yang sama seperti perintah keluarga status untuk perbaikan konfigurasi yang ditargetkan.
|
||||
- Contoh: perbaikan Telegram `allowFrom` / `groupAllowFrom` `@username` mencoba menggunakan kredensial bot yang dikonfigurasi jika tersedia.
|
||||
- Jika token bot Telegram dikonfigurasi melalui SecretRef tetapi tidak tersedia pada jalur perintah saat ini, doctor melaporkan bahwa kredensial tersebut dikonfigurasi-tetapi-tidak-tersedia dan melewati resolusi otomatis alih-alih crash atau salah melaporkan token sebagai hilang.
|
||||
|
||||
### 13) Pemeriksaan kesehatan gateway + restart
|
||||
### 13) Pemeriksaan kesehatan Gateway + restart
|
||||
|
||||
Doctor menjalankan pemeriksaan kesehatan dan menawarkan untuk merestart gateway saat terlihat
|
||||
tidak sehat.
|
||||
Doctor menjalankan pemeriksaan kesehatan dan menawarkan untuk me-restart gateway saat
|
||||
terlihat tidak sehat.
|
||||
|
||||
### 13b) Kesiapan memory search
|
||||
### 13b) Kesiapan pencarian memori
|
||||
|
||||
Doctor memeriksa apakah provider embedding memory search yang dikonfigurasi siap
|
||||
untuk agen default. Perilakunya bergantung pada backend dan provider yang dikonfigurasi:
|
||||
Doctor memeriksa apakah provider embedding pencarian memori yang dikonfigurasi siap
|
||||
untuk agent default. Perilakunya bergantung pada backend dan provider yang dikonfigurasi:
|
||||
|
||||
- **Backend QMD**: mem-probe apakah biner `qmd` tersedia dan dapat dijalankan.
|
||||
- **Backend QMD**: memeriksa apakah biner `qmd` tersedia dan dapat dijalankan.
|
||||
Jika tidak, doctor mencetak panduan perbaikan termasuk paket npm dan opsi path biner manual.
|
||||
- **Provider lokal eksplisit**: memeriksa file model lokal atau URL model
|
||||
remote/dapat-diunduh yang dikenali. Jika hilang, doctor menyarankan beralih ke provider remote.
|
||||
- **Provider lokal eksplisit**: memeriksa file model lokal atau URL model remote/yang dapat diunduh
|
||||
yang dikenali. Jika tidak ada, doctor menyarankan beralih ke provider remote.
|
||||
- **Provider remote eksplisit** (`openai`, `voyage`, dll.): memverifikasi bahwa API key
|
||||
ada di environment atau penyimpanan auth. Mencetak petunjuk perbaikan yang dapat ditindaklanjuti jika hilang.
|
||||
- **Provider auto**: memeriksa ketersediaan model lokal terlebih dahulu, lalu mencoba setiap
|
||||
provider remote dalam urutan auto-selection.
|
||||
ada di environment atau penyimpanan autentikasi. Mencetak petunjuk perbaikan yang dapat ditindaklanjuti jika tidak ada.
|
||||
- **Provider otomatis**: memeriksa ketersediaan model lokal terlebih dahulu, lalu mencoba setiap provider remote
|
||||
sesuai urutan auto-selection.
|
||||
|
||||
Saat hasil probe gateway tersedia (gateway sehat pada saat
|
||||
pemeriksaan), doctor melakukan cross-reference hasilnya dengan konfigurasi yang terlihat oleh CLI dan mencatat
|
||||
pemeriksaan), doctor mencocokkan hasilnya dengan konfigurasi yang terlihat oleh CLI dan mencatat
|
||||
setiap ketidaksesuaian.
|
||||
|
||||
Gunakan `openclaw memory status --deep` untuk memverifikasi kesiapan embedding saat runtime.
|
||||
|
||||
### 14) Peringatan status kanal
|
||||
### 14) Peringatan status channel
|
||||
|
||||
Jika gateway sehat, doctor menjalankan probe status kanal dan melaporkan
|
||||
Jika gateway sehat, doctor menjalankan probe status channel dan melaporkan
|
||||
peringatan dengan perbaikan yang disarankan.
|
||||
|
||||
### 15) Audit konfigurasi supervisor + perbaikan
|
||||
|
||||
Doctor memeriksa konfigurasi supervisor yang terpasang (launchd/systemd/schtasks) untuk
|
||||
default yang hilang atau usang (misalnya dependensi systemd network-online dan
|
||||
restart delay). Saat menemukan ketidakcocokan, doctor merekomendasikan pembaruan dan dapat
|
||||
menulis ulang file/task layanan ke default saat ini.
|
||||
Doctor memeriksa konfigurasi supervisor terinstal (launchd/systemd/schtasks) untuk
|
||||
default yang hilang atau usang (misalnya dependensi network-online systemd dan
|
||||
delay restart). Saat menemukan ketidaksesuaian, doctor merekomendasikan pembaruan dan dapat
|
||||
menulis ulang file layanan/tugas ke default saat ini.
|
||||
|
||||
Catatan:
|
||||
|
||||
@ -517,36 +541,36 @@ Catatan:
|
||||
- `openclaw doctor --yes` menerima prompt perbaikan default.
|
||||
- `openclaw doctor --repair` menerapkan perbaikan yang direkomendasikan tanpa prompt.
|
||||
- `openclaw doctor --repair --force` menimpa konfigurasi supervisor kustom.
|
||||
- Jika auth token memerlukan token dan `gateway.auth.token` dikelola SecretRef, install/perbaikan layanan doctor memvalidasi SecretRef tetapi tidak menyimpan nilai token plaintext yang telah di-resolve ke metadata environment layanan supervisor.
|
||||
- Jika auth token memerlukan token dan token SecretRef yang dikonfigurasi tidak ter-resolve, doctor memblokir path install/perbaikan dengan panduan yang dapat ditindaklanjuti.
|
||||
- Jika `gateway.auth.token` dan `gateway.auth.password` sama-sama dikonfigurasi dan `gateway.auth.mode` tidak diatur, doctor memblokir install/perbaikan sampai mode diatur secara eksplisit.
|
||||
- Untuk unit user-systemd Linux, pemeriksaan drift token doctor kini mencakup sumber `Environment=` dan `EnvironmentFile=` saat membandingkan metadata auth layanan.
|
||||
- Jika autentikasi token memerlukan token dan `gateway.auth.token` dikelola oleh SecretRef, jalur instalasi/perbaikan layanan doctor memvalidasi SecretRef tetapi tidak menyimpan nilai token teks biasa yang telah di-resolve ke metadata environment layanan supervisor.
|
||||
- Jika autentikasi token memerlukan token dan SecretRef token yang dikonfigurasi tidak ter-resolve, doctor memblokir jalur instalasi/perbaikan dengan panduan yang dapat ditindaklanjuti.
|
||||
- Jika `gateway.auth.token` dan `gateway.auth.password` sama-sama dikonfigurasi dan `gateway.auth.mode` tidak diatur, doctor memblokir instalasi/perbaikan sampai mode diatur secara eksplisit.
|
||||
- Untuk unit user-systemd Linux, pemeriksaan drift token doctor sekarang mencakup sumber `Environment=` dan `EnvironmentFile=` saat membandingkan metadata autentikasi layanan.
|
||||
- Anda selalu dapat memaksa penulisan ulang penuh melalui `openclaw gateway install --force`.
|
||||
|
||||
### 16) Diagnostik runtime + port gateway
|
||||
### 16) Diagnostik runtime + port Gateway
|
||||
|
||||
Doctor memeriksa runtime layanan (PID, status exit terakhir) dan memperingatkan saat
|
||||
layanan terpasang tetapi sebenarnya tidak berjalan. Doctor juga memeriksa benturan port
|
||||
Doctor memeriksa runtime layanan (PID, status keluar terakhir) dan memperingatkan saat
|
||||
layanan terinstal tetapi sebenarnya tidak berjalan. Doctor juga memeriksa benturan port
|
||||
pada port gateway (default `18789`) dan melaporkan kemungkinan penyebabnya (gateway sudah
|
||||
berjalan, tunnel SSH).
|
||||
|
||||
### 17) Best practice runtime gateway
|
||||
### 17) Praktik terbaik runtime Gateway
|
||||
|
||||
Doctor memperingatkan saat layanan gateway berjalan di Bun atau path Node yang dikelola version manager
|
||||
(`nvm`, `fnm`, `volta`, `asdf`, dll.). Kanal WhatsApp + Telegram memerlukan Node,
|
||||
Doctor memperingatkan saat layanan gateway berjalan di Bun atau pada path Node yang dikelola version manager
|
||||
(`nvm`, `fnm`, `volta`, `asdf`, dll.). Channel WhatsApp + Telegram memerlukan Node,
|
||||
dan path version manager dapat rusak setelah upgrade karena layanan tidak
|
||||
memuat init shell Anda. Doctor menawarkan untuk memigrasikan ke instalasi Node sistem bila
|
||||
memuat init shell Anda. Doctor menawarkan untuk memigrasikan ke instalasi Node sistem jika
|
||||
tersedia (Homebrew/apt/choco).
|
||||
|
||||
### 18) Penulisan konfigurasi + metadata wizard
|
||||
|
||||
Doctor menyimpan setiap perubahan konfigurasi dan memberi cap metadata wizard untuk mencatat
|
||||
run doctor.
|
||||
Doctor menyimpan semua perubahan konfigurasi dan memberi cap metadata wizard untuk mencatat
|
||||
jalannya doctor.
|
||||
|
||||
### 19) Tips workspace (cadangan + sistem memori)
|
||||
|
||||
Doctor menyarankan sistem memori workspace jika belum ada dan mencetak tip cadangan
|
||||
Doctor menyarankan sistem memori workspace jika belum ada dan mencetak tip pencadangan
|
||||
jika workspace belum berada di bawah git.
|
||||
|
||||
Lihat [/concepts/agent-workspace](/id/concepts/agent-workspace) untuk panduan lengkap tentang
|
||||
struktur workspace dan cadangan git (disarankan GitHub atau GitLab privat).
|
||||
struktur workspace dan pencadangan git (disarankan GitHub atau GitLab privat).
|
||||
|
||||
@ -1,33 +1,33 @@
|
||||
---
|
||||
read_when:
|
||||
- Menjalankan atau melakukan debug proses gateway
|
||||
summary: Runbook untuk layanan Gateway, siklus hidup, dan operasional
|
||||
- Menjalankan atau men-debug proses gateway
|
||||
summary: Runbook untuk layanan Gateway, siklus hidup, dan operasi
|
||||
title: Runbook Gateway
|
||||
x-i18n:
|
||||
generated_at: "2026-04-07T09:14:29Z"
|
||||
generated_at: "2026-04-20T09:27:31Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: fd2c21036e88612861ef2195b8ff7205aca31386bb11558614ade8d1a54fdebd
|
||||
source_hash: e1004cdd43b1db6794f3ca83da38dbdb231a1976329d9d6d851e2b02405278d8
|
||||
source_path: gateway/index.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Runbook Gateway
|
||||
|
||||
Gunakan halaman ini untuk startup hari pertama dan operasional hari kedua dari layanan Gateway.
|
||||
Gunakan halaman ini untuk startup hari pertama dan operasi hari kedua dari layanan Gateway.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Pemecahan masalah mendalam" icon="siren" href="/id/gateway/troubleshooting">
|
||||
Diagnostik berbasis gejala dengan urutan perintah yang tepat dan signature log.
|
||||
</Card>
|
||||
<Card title="Konfigurasi" icon="sliders" href="/id/gateway/configuration">
|
||||
Panduan penyiapan berbasis tugas + referensi konfigurasi lengkap.
|
||||
Panduan penyiapan berorientasi tugas + referensi konfigurasi lengkap.
|
||||
</Card>
|
||||
<Card title="Manajemen secret" icon="key-round" href="/id/gateway/secrets">
|
||||
Kontrak SecretRef, perilaku snapshot runtime, serta operasi migrasi/muat ulang.
|
||||
Kontrak SecretRef, perilaku snapshot runtime, dan operasi migrasi/muat ulang.
|
||||
</Card>
|
||||
<Card title="Kontrak rencana secret" icon="shield-check" href="/id/gateway/secrets-plan-contract">
|
||||
Aturan target/path `secrets apply` yang tepat dan perilaku profil auth hanya-ref.
|
||||
Aturan target/path `secrets apply` yang tepat dan perilaku auth-profile hanya-ref.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -40,7 +40,7 @@ Gunakan halaman ini untuk startup hari pertama dan operasional hari kedua dari l
|
||||
openclaw gateway --port 18789
|
||||
# debug/trace dicerminkan ke stdio
|
||||
openclaw gateway --port 18789 --verbose
|
||||
# paksa mematikan listener pada port yang dipilih, lalu mulai
|
||||
# paksa matikan listener pada port yang dipilih, lalu mulai
|
||||
openclaw gateway --force
|
||||
```
|
||||
|
||||
@ -54,36 +54,36 @@ openclaw status
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
Baseline sehat: `Runtime: running` dan `RPC probe: ok`.
|
||||
Baseline sehat: `Runtime: running`, `Connectivity probe: ok`, dan `Capability: ...` yang sesuai dengan yang Anda harapkan. Gunakan `openclaw gateway status --require-rpc` saat Anda memerlukan bukti RPC cakupan baca, bukan sekadar keterjangkauan.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Validasikan kesiapan channel">
|
||||
<Step title="Validasi kesiapan channel">
|
||||
|
||||
```bash
|
||||
openclaw channels status --probe
|
||||
```
|
||||
|
||||
Dengan gateway yang dapat dijangkau, ini menjalankan probe channel per akun secara live dan audit opsional.
|
||||
Jika gateway tidak dapat dijangkau, CLI akan fallback ke ringkasan channel berbasis konfigurasi saja
|
||||
Dengan gateway yang dapat dijangkau, ini menjalankan probe channel per-akun secara live dan audit opsional.
|
||||
Jika gateway tidak dapat dijangkau, CLI akan kembali ke ringkasan channel berbasis konfigurasi saja
|
||||
alih-alih output probe live.
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
Muat ulang konfigurasi Gateway memantau path file konfigurasi aktif (diselesaikan dari default profile/state, atau `OPENCLAW_CONFIG_PATH` saat disetel).
|
||||
Reload konfigurasi Gateway memantau path file konfigurasi aktif (di-resolve dari default profile/state, atau `OPENCLAW_CONFIG_PATH` jika disetel).
|
||||
Mode default adalah `gateway.reload.mode="hybrid"`.
|
||||
Setelah pemuatan pertama berhasil, proses yang berjalan melayani snapshot konfigurasi dalam memori yang aktif; muat ulang yang berhasil menukar snapshot tersebut secara atomik.
|
||||
Setelah pemuatan berhasil pertama, proses yang berjalan menyajikan snapshot konfigurasi aktif di memori; reload yang berhasil menukar snapshot tersebut secara atomik.
|
||||
</Note>
|
||||
|
||||
## Model runtime
|
||||
|
||||
- Satu proses selalu aktif untuk perutean, control plane, dan koneksi channel.
|
||||
- Satu proses yang selalu aktif untuk routing, control plane, dan koneksi channel.
|
||||
- Satu port termultipleks untuk:
|
||||
- control/RPC WebSocket
|
||||
- API HTTP, kompatibel dengan OpenAI (`/v1/models`, `/v1/embeddings`, `/v1/chat/completions`, `/v1/responses`, `/tools/invoke`)
|
||||
- Control UI dan hooks
|
||||
- WebSocket control/RPC
|
||||
- HTTP API, kompatibel OpenAI (`/v1/models`, `/v1/embeddings`, `/v1/chat/completions`, `/v1/responses`, `/tools/invoke`)
|
||||
- Control UI dan hook
|
||||
- Mode bind default: `loopback`.
|
||||
- Auth diwajibkan secara default. Penyiapan shared-secret menggunakan
|
||||
`gateway.auth.token` / `gateway.auth.password` (atau
|
||||
@ -92,7 +92,7 @@ Setelah pemuatan pertama berhasil, proses yang berjalan melayani snapshot konfig
|
||||
|
||||
## Endpoint kompatibel OpenAI
|
||||
|
||||
Permukaan kompatibilitas OpenClaw dengan leverage tertinggi sekarang adalah:
|
||||
Surface kompatibilitas dengan leverage tertinggi OpenClaw saat ini adalah:
|
||||
|
||||
- `GET /v1/models`
|
||||
- `GET /v1/models/{id}`
|
||||
@ -100,37 +100,37 @@ Permukaan kompatibilitas OpenClaw dengan leverage tertinggi sekarang adalah:
|
||||
- `POST /v1/chat/completions`
|
||||
- `POST /v1/responses`
|
||||
|
||||
Mengapa kumpulan ini penting:
|
||||
Mengapa set ini penting:
|
||||
|
||||
- Sebagian besar integrasi Open WebUI, LobeChat, dan LibreChat memprobe `/v1/models` terlebih dahulu.
|
||||
- Sebagian besar integrasi Open WebUI, LobeChat, dan LibreChat melakukan probe ke `/v1/models` terlebih dahulu.
|
||||
- Banyak pipeline RAG dan memori mengharapkan `/v1/embeddings`.
|
||||
- Klien native agent semakin memilih `/v1/responses`.
|
||||
|
||||
Catatan perencanaan:
|
||||
|
||||
- `/v1/models` bersifat agent-first: endpoint ini mengembalikan `openclaw`, `openclaw/default`, dan `openclaw/<agentId>`.
|
||||
- `openclaw/default` adalah alias stabil yang selalu memetakan ke agent default yang dikonfigurasi.
|
||||
- Gunakan `x-openclaw-model` saat Anda menginginkan override provider/model backend; jika tidak, penyiapan model dan embedding normal dari agent yang dipilih tetap mengendalikan.
|
||||
- `openclaw/default` adalah alias stabil yang selalu dipetakan ke agent default yang dikonfigurasi.
|
||||
- Gunakan `x-openclaw-model` saat Anda menginginkan override provider/model backend; jika tidak, pengaturan model dan embedding normal milik agent yang dipilih tetap mengendalikan.
|
||||
|
||||
Semua ini berjalan pada port Gateway utama dan menggunakan batas auth operator tepercaya yang sama seperti sisa API HTTP Gateway.
|
||||
Semua ini berjalan pada port utama Gateway dan menggunakan batas auth operator tepercaya yang sama seperti bagian lain dari HTTP API Gateway.
|
||||
|
||||
### Prioritas port dan bind
|
||||
|
||||
| Pengaturan | Urutan resolusi |
|
||||
| ------------ | ------------------------------------------------------------ |
|
||||
| Setting | Urutan resolusi |
|
||||
| ------------ | ------------------------------------------------------------- |
|
||||
| Port Gateway | `--port` → `OPENCLAW_GATEWAY_PORT` → `gateway.port` → `18789` |
|
||||
| Mode bind | CLI/override → `gateway.bind` → `loopback` |
|
||||
| Mode bind | CLI/override → `gateway.bind` → `loopback` |
|
||||
|
||||
### Mode hot reload
|
||||
|
||||
| `gateway.reload.mode` | Perilaku |
|
||||
| --------------------- | ----------------------------------------- |
|
||||
| `off` | Tidak ada muat ulang konfigurasi |
|
||||
| `hot` | Terapkan hanya perubahan yang aman untuk hot |
|
||||
| `restart` | Mulai ulang pada perubahan yang memerlukan reload |
|
||||
| `hybrid` (default) | Terapkan hot saat aman, mulai ulang saat diperlukan |
|
||||
| `off` | Tidak ada reload konfigurasi |
|
||||
| `hot` | Terapkan hanya perubahan yang aman-hot |
|
||||
| `restart` | Restart pada perubahan yang memerlukan reload |
|
||||
| `hybrid` (default) | Terapkan secara hot saat aman, restart saat diperlukan |
|
||||
|
||||
## Kumpulan perintah operator
|
||||
## Set perintah operator
|
||||
|
||||
```bash
|
||||
openclaw gateway status
|
||||
@ -144,14 +144,15 @@ openclaw logs --follow
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
`gateway status --deep` ditujukan untuk penemuan layanan tambahan (LaunchDaemons/unit sistem systemd/schtasks), bukan probe kesehatan RPC yang lebih mendalam.
|
||||
`gateway status --deep` digunakan untuk penemuan layanan tambahan (unit
|
||||
LaunchDaemons/systemd system/schtasks), bukan probe kesehatan RPC yang lebih mendalam.
|
||||
|
||||
## Beberapa gateway (host yang sama)
|
||||
|
||||
Sebagian besar instalasi sebaiknya menjalankan satu gateway per mesin. Satu gateway dapat menampung beberapa
|
||||
agent dan channel.
|
||||
|
||||
Anda hanya memerlukan beberapa gateway saat Anda sengaja menginginkan isolasi atau bot penyelamat.
|
||||
Anda hanya memerlukan beberapa gateway saat Anda sengaja menginginkan isolasi atau rescue bot.
|
||||
|
||||
Pemeriksaan yang berguna:
|
||||
|
||||
@ -160,20 +161,20 @@ openclaw gateway status --deep
|
||||
openclaw gateway probe
|
||||
```
|
||||
|
||||
Yang perlu diharapkan:
|
||||
Yang diharapkan:
|
||||
|
||||
- `gateway status --deep` dapat melaporkan `Other gateway-like services detected (best effort)`
|
||||
dan mencetak petunjuk pembersihan ketika instalasi launchd/systemd/schtasks lama masih ada.
|
||||
dan menampilkan petunjuk pembersihan saat instalasi launchd/systemd/schtasks lama masih ada.
|
||||
- `gateway probe` dapat memperingatkan tentang `multiple reachable gateways` saat lebih dari satu target
|
||||
merespons.
|
||||
- Jika itu disengaja, isolasikan port, config/state, dan root workspace per gateway.
|
||||
- Jika itu memang disengaja, isolasikan root port, config/state, dan workspace untuk tiap gateway.
|
||||
|
||||
Penyiapan terperinci: [/gateway/multiple-gateways](/id/gateway/multiple-gateways).
|
||||
|
||||
## Akses jarak jauh
|
||||
|
||||
Disarankan: Tailscale/VPN.
|
||||
Fallback: tunnel SSH.
|
||||
Yang disarankan: Tailscale/VPN.
|
||||
Cadangan: tunnel SSH.
|
||||
|
||||
```bash
|
||||
ssh -N -L 18789:127.0.0.1:18789 user@host
|
||||
@ -191,7 +192,7 @@ Lihat: [Gateway Jarak Jauh](/id/gateway/remote), [Autentikasi](/id/gateway/authe
|
||||
|
||||
## Supervisi dan siklus hidup layanan
|
||||
|
||||
Gunakan run yang disupervisi untuk keandalan setingkat produksi.
|
||||
Gunakan proses yang disupervisi untuk keandalan yang menyerupai produksi.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="macOS (launchd)">
|
||||
@ -215,13 +216,13 @@ systemctl --user enable --now openclaw-gateway[-<profile>].service
|
||||
openclaw gateway status
|
||||
```
|
||||
|
||||
Untuk persistensi setelah logout, aktifkan lingering:
|
||||
Agar tetap berjalan setelah logout, aktifkan lingering:
|
||||
|
||||
```bash
|
||||
sudo loginctl enable-linger <user>
|
||||
```
|
||||
|
||||
Contoh unit pengguna manual saat Anda memerlukan path instalasi kustom:
|
||||
Contoh user-unit manual saat Anda memerlukan path instalasi kustom:
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
@ -255,7 +256,7 @@ openclaw gateway stop
|
||||
|
||||
Startup terkelola Windows native menggunakan Scheduled Task bernama `OpenClaw Gateway`
|
||||
(atau `OpenClaw Gateway (<profile>)` untuk profile bernama). Jika pembuatan Scheduled Task
|
||||
ditolak, OpenClaw melakukan fallback ke launcher folder Startup per pengguna
|
||||
ditolak, OpenClaw akan beralih ke launcher Startup-folder per-pengguna
|
||||
yang menunjuk ke `gateway.cmd` di dalam direktori state.
|
||||
|
||||
</Tab>
|
||||
@ -269,7 +270,7 @@ sudo systemctl daemon-reload
|
||||
sudo systemctl enable --now openclaw-gateway[-<profile>].service
|
||||
```
|
||||
|
||||
Gunakan isi layanan yang sama seperti unit pengguna, tetapi instal di bawah
|
||||
Gunakan body layanan yang sama seperti user unit, tetapi instal di bawah
|
||||
`/etc/systemd/system/openclaw-gateway[-<profile>].service` dan sesuaikan
|
||||
`ExecStart=` jika biner `openclaw` Anda berada di lokasi lain.
|
||||
|
||||
@ -279,7 +280,7 @@ Gunakan isi layanan yang sama seperti unit pengguna, tetapi instal di bawah
|
||||
## Beberapa gateway pada satu host
|
||||
|
||||
Sebagian besar penyiapan sebaiknya menjalankan **satu** Gateway.
|
||||
Gunakan beberapa hanya untuk isolasi/redundansi yang ketat (misalnya profile penyelamat).
|
||||
Gunakan beberapa hanya untuk isolasi/redundansi ketat (misalnya profile rescue).
|
||||
|
||||
Checklist per instance:
|
||||
|
||||
@ -305,25 +306,25 @@ openclaw --dev gateway --allow-unconfigured
|
||||
openclaw --dev status
|
||||
```
|
||||
|
||||
Default mencakup state/config terisolasi dan port gateway dasar `19001`.
|
||||
Default mencakup state/config yang terisolasi dan port dasar gateway `19001`.
|
||||
|
||||
## Referensi cepat protokol (sudut pandang operator)
|
||||
## Referensi cepat protokol (tampilan operator)
|
||||
|
||||
- Frame klien pertama harus `connect`.
|
||||
- Frame klien pertama harus berupa `connect`.
|
||||
- Gateway mengembalikan snapshot `hello-ok` (`presence`, `health`, `stateVersion`, `uptimeMs`, limits/policy).
|
||||
- `hello-ok.features.methods` / `events` adalah daftar penemuan konservatif, bukan
|
||||
dump yang dihasilkan dari setiap rute helper yang dapat dipanggil.
|
||||
- Permintaan: `req(method, params)` → `res(ok/payload|error)`.
|
||||
- `hello-ok.features.methods` / `events` adalah daftar discovery konservatif, bukan
|
||||
dump yang dihasilkan dari setiap helper route yang dapat dipanggil.
|
||||
- Request: `req(method, params)` → `res(ok/payload|error)`.
|
||||
- Event umum mencakup `connect.challenge`, `agent`, `chat`,
|
||||
`session.message`, `session.tool`, `sessions.changed`, `presence`, `tick`,
|
||||
`health`, `heartbeat`, event siklus hidup pairing/approval, dan `shutdown`.
|
||||
|
||||
Run agent terdiri dari dua tahap:
|
||||
|
||||
1. Ack accepted langsung (`status:"accepted"`)
|
||||
2. Respons penyelesaian final (`status:"ok"|"error"`), dengan event `agent` yang di-stream di antaranya.
|
||||
1. Ack penerimaan langsung (`status:"accepted"`)
|
||||
2. Respons penyelesaian akhir (`status:"ok"|"error"`), dengan event `agent` yang di-stream di antaranya.
|
||||
|
||||
Lihat dokumen protokol lengkap: [Protokol Gateway](/id/gateway/protocol).
|
||||
Lihat dokumentasi protokol lengkap: [Protokol Gateway](/id/gateway/protocol).
|
||||
|
||||
## Pemeriksaan operasional
|
||||
|
||||
@ -342,24 +343,24 @@ openclaw health
|
||||
|
||||
### Pemulihan gap
|
||||
|
||||
Event tidak diputar ulang. Pada gap urutan, segarkan state (`health`, `system-presence`) sebelum melanjutkan.
|
||||
Event tidak diputar ulang. Pada gap sequence, segarkan state (`health`, `system-presence`) sebelum melanjutkan.
|
||||
|
||||
## Signature kegagalan umum
|
||||
|
||||
| Signature | Masalah yang mungkin |
|
||||
| -------------------------------------------------------------- | -------------------------------------------------------------------------------- |
|
||||
| `refusing to bind gateway ... without auth` | Bind non-loopback tanpa jalur auth gateway yang valid |
|
||||
| `another gateway instance is already listening` / `EADDRINUSE` | Konflik port |
|
||||
| `Gateway start blocked: set gateway.mode=local` | Konfigurasi disetel ke mode remote, atau cap mode lokal hilang dari konfigurasi yang rusak |
|
||||
| `unauthorized` during connect | Ketidakcocokan auth antara klien dan gateway |
|
||||
| Signature | Kemungkinan masalah |
|
||||
| -------------------------------------------------------------- | --------------------------------------------------------------------------------- |
|
||||
| `refusing to bind gateway ... without auth` | Bind non-loopback tanpa jalur auth gateway yang valid |
|
||||
| `another gateway instance is already listening` / `EADDRINUSE` | Konflik port |
|
||||
| `Gateway start blocked: set gateway.mode=local` | Konfigurasi disetel ke mode remote, atau stamp mode lokal hilang dari konfigurasi yang rusak |
|
||||
| `unauthorized` during connect | Ketidakcocokan auth antara klien dan gateway |
|
||||
|
||||
Untuk urutan diagnosis lengkap, gunakan [Pemecahan Masalah Gateway](/id/gateway/troubleshooting).
|
||||
|
||||
## Jaminan keamanan
|
||||
|
||||
- Klien protokol Gateway gagal cepat ketika Gateway tidak tersedia (tanpa fallback channel langsung implisit).
|
||||
- Klien protokol Gateway gagal cepat saat Gateway tidak tersedia (tanpa fallback direct-channel implisit).
|
||||
- Frame pertama yang tidak valid/bukan-connect ditolak dan koneksi ditutup.
|
||||
- Shutdown yang graceful memancarkan event `shutdown` sebelum socket ditutup.
|
||||
- Shutdown graceful mengirim event `shutdown` sebelum socket ditutup.
|
||||
|
||||
---
|
||||
|
||||
@ -368,6 +369,6 @@ Terkait:
|
||||
- [Pemecahan Masalah](/id/gateway/troubleshooting)
|
||||
- [Proses Latar Belakang](/id/gateway/background-process)
|
||||
- [Konfigurasi](/id/gateway/configuration)
|
||||
- [Kesehatan](/id/gateway/health)
|
||||
- [Health](/id/gateway/health)
|
||||
- [Doctor](/id/gateway/doctor)
|
||||
- [Autentikasi](/id/gateway/authentication)
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- Hub pemecahan masalah mengarahkan Anda ke sini untuk diagnosis yang lebih mendalam
|
||||
- Pusat pemecahan masalah mengarahkan Anda ke sini untuk diagnosis yang lebih mendalam
|
||||
- Anda memerlukan bagian runbook berbasis gejala yang stabil dengan perintah yang tepat
|
||||
summary: Runbook pemecahan masalah mendalam untuk gateway, channel, otomasi, node, dan browser
|
||||
summary: Runbook pemecahan masalah mendalam untuk gateway, channel, otomatisasi, node, dan browser
|
||||
title: Pemecahan masalah
|
||||
x-i18n:
|
||||
generated_at: "2026-04-11T02:45:10Z"
|
||||
generated_at: "2026-04-20T09:27:35Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 7ef2faccba26ede307861504043a6415bc1f12dc64407771106f63ddc5b107f5
|
||||
source_hash: d93a82407dbb1314b91a809ff9433114e1e9a3b56d46547ef53a8196bac06260
|
||||
source_path: gateway/troubleshooting.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -18,7 +18,7 @@ x-i18n:
|
||||
Halaman ini adalah runbook mendalam.
|
||||
Mulai dari [/help/troubleshooting](/id/help/troubleshooting) jika Anda ingin alur triase cepat terlebih dahulu.
|
||||
|
||||
## Tingkatan perintah
|
||||
## Tangga perintah
|
||||
|
||||
Jalankan ini terlebih dahulu, dalam urutan berikut:
|
||||
|
||||
@ -32,12 +32,12 @@ openclaw channels status --probe
|
||||
|
||||
Sinyal sehat yang diharapkan:
|
||||
|
||||
- `openclaw gateway status` menampilkan `Runtime: running` dan `RPC probe: ok`.
|
||||
- `openclaw doctor` melaporkan tidak ada masalah config/layanan yang memblokir.
|
||||
- `openclaw gateway status` menampilkan `Runtime: running`, `Connectivity probe: ok`, dan baris `Capability: ...`.
|
||||
- `openclaw doctor` melaporkan tidak ada masalah konfigurasi/layanan yang memblokir.
|
||||
- `openclaw channels status --probe` menampilkan status transport per akun secara live dan,
|
||||
jika didukung, hasil probe/audit seperti `works` atau `audit ok`.
|
||||
|
||||
## Anthropic 429 extra usage required for long context
|
||||
## Anthropic 429 memerlukan penggunaan tambahan untuk konteks panjang
|
||||
|
||||
Gunakan ini saat log/error mencakup:
|
||||
`HTTP 429: rate_limit_error: Extra usage is required for long context requests`.
|
||||
@ -48,17 +48,17 @@ openclaw models status
|
||||
openclaw config get agents.defaults.models
|
||||
```
|
||||
|
||||
Perhatikan:
|
||||
Periksa:
|
||||
|
||||
- Model Anthropic Opus/Sonnet yang dipilih memiliki `params.context1m: true`.
|
||||
- Kredensial Anthropic saat ini tidak memenuhi syarat untuk penggunaan konteks panjang.
|
||||
- Permintaan gagal hanya pada sesi panjang/eksekusi model yang memerlukan jalur beta 1M.
|
||||
- Permintaan gagal hanya pada sesi panjang/jalankan model yang memerlukan jalur beta 1M.
|
||||
|
||||
Opsi perbaikan:
|
||||
|
||||
1. Nonaktifkan `context1m` untuk model tersebut agar kembali ke jendela konteks normal.
|
||||
2. Gunakan kredensial Anthropic yang memenuhi syarat untuk permintaan konteks panjang, atau beralih ke Anthropic API key.
|
||||
3. Konfigurasikan model fallback agar eksekusi tetap berlanjut saat permintaan konteks panjang Anthropic ditolak.
|
||||
3. Konfigurasikan model fallback agar proses tetap berjalan saat permintaan konteks panjang Anthropic ditolak.
|
||||
|
||||
Terkait:
|
||||
|
||||
@ -66,13 +66,13 @@ Terkait:
|
||||
- [/reference/token-use](/id/reference/token-use)
|
||||
- [/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic](/id/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic)
|
||||
|
||||
## Backend lokal yang kompatibel dengan OpenAI lolos probe langsung tetapi eksekusi agen gagal
|
||||
## Backend lokal yang kompatibel dengan OpenAI lolos probe langsung tetapi jalankan agent gagal
|
||||
|
||||
Gunakan ini saat:
|
||||
|
||||
- `curl ... /v1/models` berfungsi
|
||||
- pemanggilan langsung kecil ke `/v1/chat/completions` berfungsi
|
||||
- eksekusi model OpenClaw gagal hanya pada giliran agen normal
|
||||
- panggilan `/v1/chat/completions` langsung yang kecil berfungsi
|
||||
- jalankan model OpenClaw gagal hanya pada giliran agent normal
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:1234/v1/models
|
||||
@ -83,33 +83,34 @@ openclaw infer model run --model <provider/model> --prompt "hi" --json
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
Perhatikan:
|
||||
Periksa:
|
||||
|
||||
- pemanggilan langsung kecil berhasil, tetapi eksekusi OpenClaw gagal hanya pada prompt yang lebih besar
|
||||
- panggilan langsung kecil berhasil, tetapi jalankan OpenClaw gagal hanya pada prompt yang lebih besar
|
||||
- error backend tentang `messages[].content` yang mengharapkan string
|
||||
- crash backend yang hanya muncul pada jumlah token prompt yang lebih besar atau prompt runtime agen penuh
|
||||
- crash backend yang hanya muncul dengan jumlah token prompt yang lebih besar atau prompt runtime agent penuh
|
||||
|
||||
Tanda umum:
|
||||
Ciri umum:
|
||||
|
||||
- `messages[...].content: invalid type: sequence, expected a string` → backend
|
||||
menolak bagian konten Chat Completions terstruktur. Perbaikan: atur
|
||||
menolak bagian konten Chat Completions yang terstruktur. Perbaikan: tetapkan
|
||||
`models.providers.<provider>.models[].compat.requiresStringContent: true`.
|
||||
- permintaan langsung kecil berhasil, tetapi eksekusi agen OpenClaw gagal dengan crash backend/model
|
||||
(misalnya Gemma pada beberapa build `inferrs`) → transport OpenClaw
|
||||
kemungkinan sudah benar; backend gagal pada bentuk prompt runtime agen yang lebih besar.
|
||||
- kegagalan berkurang setelah tools dinonaktifkan tetapi tidak hilang → schema tool memang
|
||||
menjadi bagian dari tekanan, tetapi masalah yang tersisa tetap merupakan keterbatasan model/server upstream
|
||||
atau bug backend.
|
||||
- permintaan langsung kecil berhasil, tetapi jalankan agent OpenClaw gagal dengan crash
|
||||
backend/model (misalnya Gemma pada beberapa build `inferrs`) → transport OpenClaw
|
||||
kemungkinan sudah benar; backend gagal pada bentuk prompt runtime agent yang lebih besar.
|
||||
- kegagalan berkurang setelah menonaktifkan tools tetapi tidak hilang → skema tool
|
||||
merupakan bagian dari tekanan, tetapi masalah yang tersisa tetap kapasitas model/server
|
||||
upstream atau bug backend.
|
||||
|
||||
Opsi perbaikan:
|
||||
|
||||
1. Atur `compat.requiresStringContent: true` untuk backend Chat Completions yang hanya menerima string.
|
||||
2. Atur `compat.supportsTools: false` untuk model/backend yang tidak dapat menangani
|
||||
permukaan schema tool OpenClaw secara andal.
|
||||
3. Kurangi tekanan prompt bila memungkinkan: bootstrap workspace yang lebih kecil, riwayat
|
||||
sesi yang lebih pendek, model lokal yang lebih ringan, atau backend dengan dukungan konteks panjang yang lebih kuat.
|
||||
4. Jika permintaan langsung kecil terus berhasil sementara giliran agen OpenClaw masih crash
|
||||
di dalam backend, anggap ini sebagai keterbatasan server/model upstream dan ajukan
|
||||
1. Tetapkan `compat.requiresStringContent: true` untuk backend Chat Completions yang hanya mendukung string.
|
||||
2. Tetapkan `compat.supportsTools: false` untuk model/backend yang tidak dapat menangani
|
||||
permukaan skema tool OpenClaw secara andal.
|
||||
3. Kurangi tekanan prompt jika memungkinkan: bootstrap workspace yang lebih kecil, riwayat
|
||||
sesi yang lebih pendek, model lokal yang lebih ringan, atau backend dengan dukungan
|
||||
konteks panjang yang lebih kuat.
|
||||
4. Jika permintaan langsung kecil terus lolos sementara giliran agent OpenClaw tetap crash
|
||||
di dalam backend, anggap ini sebagai keterbatasan server/model upstream dan buat
|
||||
repro di sana dengan bentuk payload yang diterima.
|
||||
|
||||
Terkait:
|
||||
@ -120,7 +121,7 @@ Terkait:
|
||||
|
||||
## Tidak ada balasan
|
||||
|
||||
Jika channel aktif tetapi tidak ada yang membalas, periksa routing dan kebijakan sebelum menyambungkan ulang apa pun.
|
||||
Jika channel aktif tetapi tidak ada yang menjawab, periksa routing dan kebijakan sebelum menyambungkan ulang apa pun.
|
||||
|
||||
```bash
|
||||
openclaw status
|
||||
@ -130,16 +131,16 @@ openclaw config get channels
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
Perhatikan:
|
||||
Periksa:
|
||||
|
||||
- Pairing tertunda untuk pengirim DM.
|
||||
- Pengaturan mention grup (`requireMention`, `mentionPatterns`).
|
||||
- Pembatasan mention grup (`requireMention`, `mentionPatterns`).
|
||||
- Ketidakcocokan allowlist channel/grup.
|
||||
|
||||
Tanda umum:
|
||||
Ciri umum:
|
||||
|
||||
- `drop guild message (mention required` → pesan grup diabaikan sampai ada mention.
|
||||
- `pairing request` → pengirim memerlukan persetujuan.
|
||||
- `pairing request` → pengirim perlu persetujuan.
|
||||
- `blocked` / `allowlist` → pengirim/channel difilter oleh kebijakan.
|
||||
|
||||
Terkait:
|
||||
@ -148,9 +149,9 @@ Terkait:
|
||||
- [/channels/pairing](/id/channels/pairing)
|
||||
- [/channels/groups](/id/channels/groups)
|
||||
|
||||
## Konektivitas dashboard control ui
|
||||
## Konektivitas control UI dashboard
|
||||
|
||||
Saat dashboard/control UI tidak dapat terhubung, validasi URL, mode auth, dan asumsi secure context.
|
||||
Saat dashboard/control UI tidak dapat terhubung, validasi URL, mode auth, dan asumsi konteks aman.
|
||||
|
||||
```bash
|
||||
openclaw gateway status
|
||||
@ -160,13 +161,13 @@ openclaw doctor
|
||||
openclaw gateway status --json
|
||||
```
|
||||
|
||||
Perhatikan:
|
||||
Periksa:
|
||||
|
||||
- URL probe dan URL dashboard sudah benar.
|
||||
- Ketidakcocokan mode auth/token antara klien dan gateway.
|
||||
- Penggunaan HTTP saat identitas perangkat diperlukan.
|
||||
- Penggunaan HTTP ketika identitas perangkat diperlukan.
|
||||
|
||||
Tanda umum:
|
||||
Ciri umum:
|
||||
|
||||
- `device identity required` → konteks tidak aman atau auth perangkat tidak ada.
|
||||
- `origin not allowed` → `Origin` browser tidak ada di `gateway.controlUi.allowedOrigins`
|
||||
@ -174,33 +175,35 @@ Tanda umum:
|
||||
allowlist eksplisit).
|
||||
- `device nonce required` / `device nonce mismatch` → klien tidak menyelesaikan
|
||||
alur auth perangkat berbasis challenge (`connect.challenge` + `device.nonce`).
|
||||
- `device signature invalid` / `device signature expired` → klien menandatangani payload yang salah
|
||||
(atau timestamp basi) untuk handshake saat ini.
|
||||
- `device signature invalid` / `device signature expired` → klien menandatangani payload
|
||||
yang salah (atau timestamp lama) untuk handshake saat ini.
|
||||
- `AUTH_TOKEN_MISMATCH` dengan `canRetryWithDeviceToken=true` → klien dapat melakukan satu kali retry tepercaya dengan token perangkat yang di-cache.
|
||||
- Retry token cache itu menggunakan kembali kumpulan scope yang di-cache dan disimpan bersama
|
||||
token perangkat yang telah dipasangkan. Pemanggil `deviceToken` eksplisit / `scopes` eksplisit mempertahankan
|
||||
- Retry token yang di-cache tersebut menggunakan kembali kumpulan scope yang di-cache dan disimpan bersama
|
||||
token perangkat yang telah dipasangkan. Pemanggil `deviceToken` eksplisit / `scopes` eksplisit tetap mempertahankan
|
||||
kumpulan scope yang diminta.
|
||||
- Di luar jalur retry itu, prioritas auth connect bersifat eksplisit:
|
||||
shared token/password terlebih dahulu, lalu `deviceToken` eksplisit, lalu token perangkat tersimpan,
|
||||
lalu bootstrap token.
|
||||
- Di luar jalur retry itu, prioritas auth connect adalah shared
|
||||
token/password eksplisit terlebih dahulu, lalu `deviceToken` eksplisit, lalu token perangkat tersimpan,
|
||||
lalu token bootstrap.
|
||||
- Pada jalur async Tailscale Serve Control UI, upaya gagal untuk
|
||||
`{scope, ip}` yang sama diserialkan sebelum limiter mencatat kegagalan. Oleh karena itu, dua retry bersamaan yang buruk dari klien yang sama dapat menampilkan `retry later`
|
||||
pada percobaan kedua alih-alih dua ketidakcocokan biasa.
|
||||
- `too many failed authentication attempts (retry later)` dari klien loopback browser-origin
|
||||
→ kegagalan berulang dari `Origin` ternormalisasi yang sama dikunci sementara; origin localhost lain menggunakan bucket terpisah.
|
||||
- `unauthorized` berulang setelah retry tersebut → shared token/device token berubah; segarkan config token dan setujui ulang/rotasi token perangkat bila perlu.
|
||||
`{scope, ip}` yang sama diserialkan sebelum limiter mencatat kegagalan. Karena itu, dua retry buruk yang
|
||||
bersamaan dari klien yang sama dapat memunculkan `retry later`
|
||||
pada percobaan kedua, bukan dua mismatch biasa.
|
||||
- `too many failed authentication attempts (retry later)` dari klien loopback
|
||||
origin browser → kegagalan berulang dari `Origin` yang sama yang telah dinormalisasi akan
|
||||
diblokir sementara; origin localhost lain menggunakan bucket terpisah.
|
||||
- `unauthorized` berulang setelah retry itu → shared token/token perangkat drift; segarkan konfigurasi token dan setujui ulang/putar token perangkat jika diperlukan.
|
||||
- `gateway connect failed:` → target host/port/url salah.
|
||||
|
||||
### Peta cepat kode detail auth
|
||||
|
||||
Gunakan `error.details.code` dari respons `connect` yang gagal untuk memilih tindakan berikutnya:
|
||||
|
||||
| Kode detail | Arti | Tindakan yang direkomendasikan |
|
||||
| ---------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `AUTH_TOKEN_MISSING` | Klien tidak mengirim shared token yang diperlukan. | Tempel/atur token di klien lalu coba lagi. Untuk jalur dashboard: `openclaw config get gateway.auth.token` lalu tempel ke pengaturan Control UI. |
|
||||
| `AUTH_TOKEN_MISMATCH` | Shared token tidak cocok dengan token auth gateway. | Jika `canRetryWithDeviceToken=true`, izinkan satu retry tepercaya. Retry token cache menggunakan kembali scope yang disetujui dan disimpan; pemanggil `deviceToken` / `scopes` eksplisit mempertahankan scope yang diminta. Jika masih gagal, jalankan [daftar periksa pemulihan token drift](/cli/devices#token-drift-recovery-checklist). |
|
||||
| `AUTH_DEVICE_TOKEN_MISMATCH` | Token per-perangkat yang di-cache sudah basi atau dicabut. | Putar/setujui ulang token perangkat menggunakan [devices CLI](/cli/devices), lalu sambungkan kembali. |
|
||||
| `PAIRING_REQUIRED` | Identitas perangkat diketahui tetapi belum disetujui untuk peran ini. | Setujui permintaan tertunda: `openclaw devices list` lalu `openclaw devices approve <requestId>`. |
|
||||
| Kode detail | Arti | Tindakan yang direkomendasikan |
|
||||
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `AUTH_TOKEN_MISSING` | Klien tidak mengirim shared token yang diwajibkan. | Tempel/tetapkan token di klien lalu coba lagi. Untuk jalur dashboard: `openclaw config get gateway.auth.token` lalu tempel ke pengaturan Control UI. |
|
||||
| `AUTH_TOKEN_MISMATCH` | Shared token tidak cocok dengan token auth gateway. | Jika `canRetryWithDeviceToken=true`, izinkan satu retry tepercaya. Retry token yang di-cache menggunakan kembali scope yang disetujui dan disimpan; pemanggil `deviceToken` / `scopes` eksplisit mempertahankan scope yang diminta. Jika masih gagal, jalankan [checklist pemulihan drift token](/cli/devices#token-drift-recovery-checklist). |
|
||||
| `AUTH_DEVICE_TOKEN_MISMATCH` | Token per-perangkat yang di-cache sudah usang atau dicabut. | Putar/setujui ulang token perangkat menggunakan [devices CLI](/cli/devices), lalu sambungkan kembali. |
|
||||
| `PAIRING_REQUIRED` | Identitas perangkat memerlukan persetujuan. Periksa `error.details.reason` untuk `not-paired`, `scope-upgrade`, `role-upgrade`, atau `metadata-upgrade`, dan gunakan `requestId` / `remediationHint` jika ada. | Setujui permintaan tertunda: `openclaw devices list` lalu `openclaw devices approve <requestId>`. Peningkatan scope/peran menggunakan alur yang sama setelah Anda meninjau akses yang diminta. |
|
||||
|
||||
Pemeriksaan migrasi auth perangkat v2:
|
||||
|
||||
@ -213,12 +216,12 @@ openclaw gateway status
|
||||
Jika log menampilkan error nonce/signature, perbarui klien yang terhubung dan verifikasi bahwa klien:
|
||||
|
||||
1. menunggu `connect.challenge`
|
||||
2. menandatangani payload yang terikat pada challenge
|
||||
2. menandatangani payload yang terikat ke challenge
|
||||
3. mengirim `connect.params.device.nonce` dengan nonce challenge yang sama
|
||||
|
||||
Jika `openclaw devices rotate` / `revoke` / `remove` ditolak secara tak terduga:
|
||||
Jika `openclaw devices rotate` / `revoke` / `remove` ditolak secara tidak terduga:
|
||||
|
||||
- sesi token paired-device hanya dapat mengelola **perangkatnya sendiri** kecuali
|
||||
- sesi token paired-device hanya dapat mengelola **perangkat mereka sendiri** kecuali
|
||||
pemanggil juga memiliki `operator.admin`
|
||||
- `openclaw devices rotate --scope ...` hanya dapat meminta scope operator yang
|
||||
sudah dimiliki oleh sesi pemanggil
|
||||
@ -233,7 +236,7 @@ Terkait:
|
||||
|
||||
## Layanan gateway tidak berjalan
|
||||
|
||||
Gunakan ini saat layanan sudah terinstal tetapi proses tidak tetap berjalan.
|
||||
Gunakan ini saat layanan terpasang tetapi proses tidak tetap berjalan.
|
||||
|
||||
```bash
|
||||
openclaw gateway status
|
||||
@ -243,20 +246,20 @@ openclaw doctor
|
||||
openclaw gateway status --deep # juga memindai layanan tingkat sistem
|
||||
```
|
||||
|
||||
Perhatikan:
|
||||
Periksa:
|
||||
|
||||
- `Runtime: stopped` dengan petunjuk exit.
|
||||
- Ketidakcocokan config layanan (`Config (cli)` vs `Config (service)`).
|
||||
- Ketidakcocokan konfigurasi layanan (`Config (cli)` vs `Config (service)`).
|
||||
- Konflik port/listener.
|
||||
- Instalasi launchd/systemd/schtasks tambahan saat `--deep` digunakan.
|
||||
- Petunjuk pembersihan `Other gateway-like services detected (best effort)`.
|
||||
|
||||
Tanda umum:
|
||||
Ciri umum:
|
||||
|
||||
- `Gateway start blocked: set gateway.mode=local` atau `existing config is missing gateway.mode` → mode gateway lokal tidak diaktifkan, atau file config tertimpa dan kehilangan `gateway.mode`. Perbaikan: atur `gateway.mode="local"` dalam config Anda, atau jalankan ulang `openclaw onboard --mode local` / `openclaw setup` untuk menulis ulang config mode lokal yang diharapkan. Jika Anda menjalankan OpenClaw melalui Podman, jalur config default adalah `~/.openclaw/openclaw.json`.
|
||||
- `Gateway start blocked: set gateway.mode=local` atau `existing config is missing gateway.mode` → mode gateway lokal tidak diaktifkan, atau file konfigurasi tertimpa dan kehilangan `gateway.mode`. Perbaikan: tetapkan `gateway.mode="local"` di konfigurasi Anda, atau jalankan kembali `openclaw onboard --mode local` / `openclaw setup` untuk menerapkan ulang konfigurasi mode lokal yang diharapkan. Jika Anda menjalankan OpenClaw melalui Podman, path konfigurasi default adalah `~/.openclaw/openclaw.json`.
|
||||
- `refusing to bind gateway ... without auth` → bind non-loopback tanpa jalur auth gateway yang valid (token/password, atau trusted-proxy jika dikonfigurasi).
|
||||
- `another gateway instance is already listening` / `EADDRINUSE` → konflik port.
|
||||
- `Other gateway-like services detected (best effort)` → unit launchd/systemd/schtasks yang basi atau paralel masih ada. Sebagian besar setup sebaiknya mempertahankan satu gateway per mesin; jika Anda memang memerlukan lebih dari satu, isolasikan port + config/status/workspace. Lihat [/gateway#multiple-gateways-same-host](/id/gateway#multiple-gateways-same-host).
|
||||
- `Other gateway-like services detected (best effort)` → unit launchd/systemd/schtasks yang usang atau paralel masih ada. Sebagian besar setup sebaiknya mempertahankan satu gateway per mesin; jika Anda memang memerlukan lebih dari satu, pisahkan port + konfigurasi/state/workspace. Lihat [/gateway#multiple-gateways-same-host](/id/gateway#multiple-gateways-same-host).
|
||||
|
||||
Terkait:
|
||||
|
||||
@ -264,9 +267,9 @@ Terkait:
|
||||
- [/gateway/configuration](/id/gateway/configuration)
|
||||
- [/gateway/doctor](/id/gateway/doctor)
|
||||
|
||||
## Peringatan probe Gateway
|
||||
## Peringatan probe gateway
|
||||
|
||||
Gunakan ini saat `openclaw gateway probe` mencapai sesuatu, tetapi tetap menampilkan blok peringatan.
|
||||
Gunakan ini saat `openclaw gateway probe` menjangkau sesuatu, tetapi masih menampilkan blok peringatan.
|
||||
|
||||
```bash
|
||||
openclaw gateway probe
|
||||
@ -274,16 +277,17 @@ openclaw gateway probe --json
|
||||
openclaw gateway probe --ssh user@gateway-host
|
||||
```
|
||||
|
||||
Perhatikan:
|
||||
Periksa:
|
||||
|
||||
- `warnings[].code` dan `primaryTargetId` dalam output JSON.
|
||||
- Apakah peringatannya tentang fallback SSH, beberapa gateway, scope yang hilang, atau auth ref yang tidak terselesaikan.
|
||||
- Apakah peringatannya tentang fallback SSH, beberapa gateway, scope yang hilang, atau referensi auth yang tidak terselesaikan.
|
||||
|
||||
Tanda umum:
|
||||
Ciri umum:
|
||||
|
||||
- `SSH tunnel failed to start; falling back to direct probes.` → penyiapan SSH gagal, tetapi perintah tetap mencoba target langsung yang dikonfigurasi/loopback.
|
||||
- `multiple reachable gateways detected` → lebih dari satu target merespons. Biasanya ini berarti setup multi-gateway yang disengaja atau listener yang basi/duplikat.
|
||||
- `Probe diagnostics are limited by gateway scopes (missing operator.read)` → connect berhasil, tetapi detail RPC dibatasi oleh scope; pasangkan identitas perangkat atau gunakan kredensial dengan `operator.read`.
|
||||
- `SSH tunnel failed to start; falling back to direct probes.` → setup SSH gagal, tetapi perintah tetap mencoba target langsung yang dikonfigurasi/loopback.
|
||||
- `multiple reachable gateways detected` → lebih dari satu target merespons. Biasanya ini berarti setup multi-gateway yang disengaja atau listener yang usang/duplikat.
|
||||
- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → koneksi berhasil, tetapi detail RPC dibatasi oleh scope; pasangkan identitas perangkat atau gunakan kredensial dengan `operator.read`.
|
||||
- `Capability: pairing-pending` atau `gateway closed (1008): pairing required` → gateway merespons, tetapi klien ini masih memerlukan pairing/persetujuan sebelum akses operator normal.
|
||||
- teks peringatan SecretRef `gateway.auth.*` / `gateway.remote.*` yang tidak terselesaikan → materi auth tidak tersedia di jalur perintah ini untuk target yang gagal.
|
||||
|
||||
Terkait:
|
||||
@ -292,9 +296,9 @@ Terkait:
|
||||
- [/gateway#multiple-gateways-same-host](/id/gateway#multiple-gateways-same-host)
|
||||
- [/gateway/remote](/id/gateway/remote)
|
||||
|
||||
## Pesan channel terhubung tetapi tidak mengalir
|
||||
## Channel terhubung tetapi pesan tidak mengalir
|
||||
|
||||
Jika status channel terhubung tetapi aliran pesan mati, fokuslah pada kebijakan, izin, dan aturan pengiriman spesifik channel.
|
||||
Jika status channel terhubung tetapi aliran pesan mati, fokus pada kebijakan, izin, dan aturan pengiriman khusus channel.
|
||||
|
||||
```bash
|
||||
openclaw channels status --probe
|
||||
@ -304,13 +308,13 @@ openclaw logs --follow
|
||||
openclaw config get channels
|
||||
```
|
||||
|
||||
Perhatikan:
|
||||
Periksa:
|
||||
|
||||
- Kebijakan DM (`pairing`, `allowlist`, `open`, `disabled`).
|
||||
- Allowlist grup dan persyaratan mention.
|
||||
- Izin/scope API channel yang hilang.
|
||||
|
||||
Tanda umum:
|
||||
Ciri umum:
|
||||
|
||||
- `mention required` → pesan diabaikan oleh kebijakan mention grup.
|
||||
- jejak `pairing` / persetujuan tertunda → pengirim belum disetujui.
|
||||
@ -323,9 +327,9 @@ Terkait:
|
||||
- [/channels/telegram](/id/channels/telegram)
|
||||
- [/channels/discord](/id/channels/discord)
|
||||
|
||||
## Pengiriman cron dan heartbeat
|
||||
## Pengiriman Cron dan Heartbeat
|
||||
|
||||
Jika cron atau heartbeat tidak berjalan atau tidak terkirim, verifikasi status scheduler terlebih dahulu, lalu target pengirimannya.
|
||||
Jika Cron atau Heartbeat tidak berjalan atau tidak terkirim, verifikasi status scheduler terlebih dahulu, lalu target pengiriman.
|
||||
|
||||
```bash
|
||||
openclaw cron status
|
||||
@ -335,21 +339,21 @@ openclaw system heartbeat last
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
Perhatikan:
|
||||
Periksa:
|
||||
|
||||
- Cron diaktifkan dan waktu bangun berikutnya ada.
|
||||
- Cron diaktifkan dan waktu bangun berikutnya tersedia.
|
||||
- Status riwayat eksekusi job (`ok`, `skipped`, `error`).
|
||||
- Alasan heartbeat dilewati (`quiet-hours`, `requests-in-flight`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`).
|
||||
- Alasan Heartbeat dilewati (`quiet-hours`, `requests-in-flight`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`).
|
||||
|
||||
Tanda umum:
|
||||
Ciri umum:
|
||||
|
||||
- `cron: scheduler disabled; jobs will not run automatically` → cron dinonaktifkan.
|
||||
- `cron: timer tick failed` → tick scheduler gagal; periksa file/log/error runtime.
|
||||
- `cron: scheduler disabled; jobs will not run automatically` → Cron dinonaktifkan.
|
||||
- `cron: timer tick failed` → tick scheduler gagal; periksa error file/log/runtime.
|
||||
- `heartbeat skipped` dengan `reason=quiet-hours` → di luar jendela jam aktif.
|
||||
- `heartbeat skipped` dengan `reason=empty-heartbeat-file` → `HEARTBEAT.md` ada tetapi hanya berisi baris kosong / heading markdown, sehingga OpenClaw melewati pemanggilan model.
|
||||
- `heartbeat skipped` dengan `reason=no-tasks-due` → `HEARTBEAT.md` berisi blok `tasks:`, tetapi tidak ada tugas yang jatuh tempo pada tick ini.
|
||||
- `heartbeat: unknown accountId` → account id tidak valid untuk target pengiriman heartbeat.
|
||||
- `heartbeat skipped` dengan `reason=dm-blocked` → target heartbeat terselesaikan ke tujuan bergaya DM sementara `agents.defaults.heartbeat.directPolicy` (atau override per agen) diatur ke `block`.
|
||||
- `heartbeat skipped` dengan `reason=empty-heartbeat-file` → `HEARTBEAT.md` ada tetapi hanya berisi baris kosong / heading markdown, sehingga OpenClaw melewati panggilan model.
|
||||
- `heartbeat skipped` dengan `reason=no-tasks-due` → `HEARTBEAT.md` berisi blok `tasks:`, tetapi tidak ada task yang jatuh tempo pada tick ini.
|
||||
- `heartbeat: unknown accountId` → account id tidak valid untuk target pengiriman Heartbeat.
|
||||
- `heartbeat skipped` dengan `reason=dm-blocked` → target Heartbeat terurai menjadi tujuan bergaya DM sementara `agents.defaults.heartbeat.directPolicy` (atau override per-agent) disetel ke `block`.
|
||||
|
||||
Terkait:
|
||||
|
||||
@ -359,7 +363,7 @@ Terkait:
|
||||
|
||||
## Tool node berpasangan gagal
|
||||
|
||||
Jika sebuah node sudah dipasangkan tetapi tool gagal, isolasi status foreground, izin, dan persetujuan.
|
||||
Jika sebuah node sudah dipasangkan tetapi tools gagal, pisahkan kondisi foreground, izin, dan persetujuan.
|
||||
|
||||
```bash
|
||||
openclaw nodes status
|
||||
@ -369,16 +373,16 @@ openclaw logs --follow
|
||||
openclaw status
|
||||
```
|
||||
|
||||
Perhatikan:
|
||||
Periksa:
|
||||
|
||||
- Node online dengan kapabilitas yang diharapkan.
|
||||
- Node online dengan capability yang diharapkan.
|
||||
- Pemberian izin OS untuk kamera/mikrofon/lokasi/layar.
|
||||
- Persetujuan exec dan status allowlist.
|
||||
- Status persetujuan exec dan allowlist.
|
||||
|
||||
Tanda umum:
|
||||
Ciri umum:
|
||||
|
||||
- `NODE_BACKGROUND_UNAVAILABLE` → aplikasi node harus berada di foreground.
|
||||
- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → izin OS tidak ada.
|
||||
- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → izin OS belum diberikan.
|
||||
- `SYSTEM_RUN_DENIED: approval required` → persetujuan exec tertunda.
|
||||
- `SYSTEM_RUN_DENIED: allowlist miss` → perintah diblokir oleh allowlist.
|
||||
|
||||
@ -390,7 +394,7 @@ Terkait:
|
||||
|
||||
## Tool browser gagal
|
||||
|
||||
Gunakan ini saat aksi tool browser gagal meskipun gateway sendiri sehat.
|
||||
Gunakan ini saat aksi tool browser gagal meskipun gateway itu sendiri sehat.
|
||||
|
||||
```bash
|
||||
openclaw browser status
|
||||
@ -400,29 +404,29 @@ openclaw logs --follow
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
Perhatikan:
|
||||
Periksa:
|
||||
|
||||
- Apakah `plugins.allow` diatur dan menyertakan `browser`.
|
||||
- Jalur executable browser valid.
|
||||
- Apakah `plugins.allow` disetel dan menyertakan `browser`.
|
||||
- Path executable browser valid.
|
||||
- Keterjangkauan profil CDP.
|
||||
- Ketersediaan Chrome lokal untuk profil `existing-session` / `user`.
|
||||
|
||||
Tanda umum:
|
||||
Ciri umum:
|
||||
|
||||
- `unknown command "browser"` atau `unknown command 'browser'` → plugin browser bawaan dikecualikan oleh `plugins.allow`.
|
||||
- tool browser hilang / tidak tersedia saat `browser.enabled=true` → `plugins.allow` mengecualikan `browser`, sehingga plugin tidak pernah dimuat.
|
||||
- `Failed to start Chrome CDP on port` → proses browser gagal dijalankan.
|
||||
- `browser.executablePath not found` → jalur yang dikonfigurasi tidak valid.
|
||||
- `unknown command "browser"` atau `unknown command 'browser'` → Plugin browser bawaan dikecualikan oleh `plugins.allow`.
|
||||
- tool browser hilang / tidak tersedia saat `browser.enabled=true` → `plugins.allow` mengecualikan `browser`, sehingga Plugin tidak pernah dimuat.
|
||||
- `Failed to start Chrome CDP on port` → proses browser gagal diluncurkan.
|
||||
- `browser.executablePath not found` → path yang dikonfigurasi tidak valid.
|
||||
- `browser.cdpUrl must be http(s) or ws(s)` → URL CDP yang dikonfigurasi menggunakan skema yang tidak didukung seperti `file:` atau `ftp:`.
|
||||
- `browser.cdpUrl has invalid port` → URL CDP yang dikonfigurasi memiliki port yang buruk atau di luar rentang.
|
||||
- `No Chrome tabs found for profile="user"` → profil attach Chrome MCP tidak memiliki tab Chrome lokal yang terbuka.
|
||||
- `No Chrome tabs found for profile="user"` → profil lampiran Chrome MCP tidak memiliki tab Chrome lokal yang terbuka.
|
||||
- `Remote CDP for profile "<name>" is not reachable` → endpoint CDP remote yang dikonfigurasi tidak dapat dijangkau dari host gateway.
|
||||
- `Browser attachOnly is enabled ... not reachable` atau `Browser attachOnly is enabled and CDP websocket ... is not reachable` → profil attach-only tidak memiliki target yang dapat dijangkau, atau endpoint HTTP merespons tetapi WebSocket CDP tetap tidak dapat dibuka.
|
||||
- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → instalasi gateway saat ini tidak memiliki paket Playwright lengkap; snapshot ARIA dan screenshot halaman dasar masih dapat berfungsi, tetapi navigasi, snapshot AI, screenshot elemen pemilih CSS, dan ekspor PDF tetap tidak tersedia.
|
||||
- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → instalasi gateway saat ini tidak memiliki paket Playwright penuh; snapshot ARIA dan screenshot halaman dasar masih dapat berfungsi, tetapi navigasi, snapshot AI, screenshot elemen dengan selektor CSS, dan ekspor PDF tetap tidak tersedia.
|
||||
- `fullPage is not supported for element screenshots` → permintaan screenshot mencampurkan `--full-page` dengan `--ref` atau `--element`.
|
||||
- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → pemanggilan screenshot Chrome MCP / `existing-session` harus menggunakan pengambilan halaman atau `--ref` dari snapshot, bukan CSS `--element`.
|
||||
- `existing-session file uploads do not support element selectors; use ref/inputRef.` → hook upload Chrome MCP memerlukan ref snapshot, bukan selector CSS.
|
||||
- `existing-session file uploads currently support one file at a time.` → kirim satu upload per pemanggilan pada profil Chrome MCP.
|
||||
- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → panggilan screenshot Chrome MCP / `existing-session` harus menggunakan page capture atau `--ref` dari snapshot, bukan CSS `--element`.
|
||||
- `existing-session file uploads do not support element selectors; use ref/inputRef.` → hook unggah Chrome MCP memerlukan ref snapshot, bukan selektor CSS.
|
||||
- `existing-session file uploads currently support one file at a time.` → kirim satu unggahan per panggilan pada profil Chrome MCP.
|
||||
- `existing-session dialog handling does not support timeoutMs.` → hook dialog pada profil Chrome MCP tidak mendukung override timeout.
|
||||
- `response body is not supported for existing-session profiles yet.` → `responsebody` masih memerlukan browser terkelola atau profil CDP mentah.
|
||||
- override viewport / dark-mode / locale / offline yang basi pada profil attach-only atau CDP remote → jalankan `openclaw browser stop --browser-profile <name>` untuk menutup sesi kontrol aktif dan melepaskan status emulasi Playwright/CDP tanpa me-restart seluruh gateway.
|
||||
@ -434,7 +438,7 @@ Terkait:
|
||||
|
||||
## Jika Anda melakukan upgrade dan sesuatu tiba-tiba rusak
|
||||
|
||||
Sebagian besar kerusakan setelah upgrade adalah config drift atau default yang lebih ketat yang sekarang diberlakukan.
|
||||
Sebagian besar kerusakan setelah upgrade disebabkan oleh drift konfigurasi atau default yang lebih ketat yang kini diberlakukan.
|
||||
|
||||
### 1) Perilaku override auth dan URL berubah
|
||||
|
||||
@ -445,12 +449,12 @@ openclaw config get gateway.remote.url
|
||||
openclaw config get gateway.auth.mode
|
||||
```
|
||||
|
||||
Yang perlu diperiksa:
|
||||
Yang harus diperiksa:
|
||||
|
||||
- Jika `gateway.mode=remote`, pemanggilan CLI mungkin menargetkan remote sementara layanan lokal Anda baik-baik saja.
|
||||
- Pemanggilan `--url` eksplisit tidak melakukan fallback ke kredensial yang tersimpan.
|
||||
- Jika `gateway.mode=remote`, panggilan CLI mungkin menargetkan remote sementara layanan lokal Anda baik-baik saja.
|
||||
- Panggilan `--url` eksplisit tidak melakukan fallback ke kredensial yang tersimpan.
|
||||
|
||||
Tanda umum:
|
||||
Ciri umum:
|
||||
|
||||
- `gateway connect failed:` → target URL salah.
|
||||
- `unauthorized` → endpoint dapat dijangkau tetapi auth salah.
|
||||
@ -465,15 +469,15 @@ openclaw gateway status
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
Yang perlu diperiksa:
|
||||
Yang harus diperiksa:
|
||||
|
||||
- Bind non-loopback (`lan`, `tailnet`, `custom`) memerlukan jalur auth gateway yang valid: auth shared token/password, atau deployment `trusted-proxy` non-loopback yang dikonfigurasi dengan benar.
|
||||
- Kunci lama seperti `gateway.token` tidak menggantikan `gateway.auth.token`.
|
||||
|
||||
Tanda umum:
|
||||
Ciri umum:
|
||||
|
||||
- `refusing to bind gateway ... without auth` → bind non-loopback tanpa jalur auth gateway yang valid.
|
||||
- `RPC probe: failed` saat runtime berjalan → gateway hidup tetapi tidak dapat diakses dengan auth/url saat ini.
|
||||
- `Connectivity probe: failed` saat runtime berjalan → gateway hidup tetapi tidak dapat diakses dengan auth/url saat ini.
|
||||
|
||||
### 3) Status pairing dan identitas perangkat berubah
|
||||
|
||||
@ -484,17 +488,17 @@ openclaw logs --follow
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
Yang perlu diperiksa:
|
||||
Yang harus diperiksa:
|
||||
|
||||
- Persetujuan perangkat tertunda untuk dashboard/node.
|
||||
- Persetujuan perangkat tertunda untuk dashboard/nodes.
|
||||
- Persetujuan pairing DM tertunda setelah perubahan kebijakan atau identitas.
|
||||
|
||||
Tanda umum:
|
||||
Ciri umum:
|
||||
|
||||
- `device identity required` → auth perangkat tidak terpenuhi.
|
||||
- `device identity required` → auth perangkat belum terpenuhi.
|
||||
- `pairing required` → pengirim/perangkat harus disetujui.
|
||||
|
||||
Jika config layanan dan runtime masih tidak cocok setelah pemeriksaan, instal ulang metadata layanan dari direktori profil/status yang sama:
|
||||
Jika konfigurasi layanan dan runtime masih tidak sesuai setelah pemeriksaan, instal ulang metadata layanan dari profil/direktori state yang sama:
|
||||
|
||||
```bash
|
||||
openclaw gateway install --force
|
||||
|
||||
1560
docs/id/help/faq.md
1560
docs/id/help/faq.md
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- OpenClaw tidak berfungsi dan Anda memerlukan jalur tercepat menuju perbaikan
|
||||
- Anda ingin alur triase sebelum mendalami runbook yang lebih mendalam
|
||||
summary: Pusat pemecahan masalah berbasis gejala terlebih dahulu untuk OpenClaw
|
||||
- OpenClaw tidak berfungsi dan Anda membutuhkan jalur tercepat menuju perbaikan
|
||||
- Anda menginginkan alur triase sebelum masuk ke runbook mendalam
|
||||
summary: Hub pemecahan masalah berbasis gejala untuk OpenClaw
|
||||
title: Pemecahan Masalah Umum
|
||||
x-i18n:
|
||||
generated_at: "2026-04-11T02:45:14Z"
|
||||
generated_at: "2026-04-20T09:28:16Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 16b38920dbfdc8d4a79bbb5d6fab2c67c9f218a97c36bb4695310d7db9c4614a
|
||||
source_hash: cc5d8c9f804084985c672c5a003ce866e8142ab99fe81abb7a0d38e22aea4b88
|
||||
source_path: help/troubleshooting.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -33,47 +33,47 @@ openclaw logs --follow
|
||||
|
||||
Output yang baik dalam satu baris:
|
||||
|
||||
- `openclaw status` → menampilkan saluran yang dikonfigurasi dan tidak ada error auth yang jelas.
|
||||
- `openclaw status` → menampilkan channel yang dikonfigurasi dan tidak ada error auth yang jelas.
|
||||
- `openclaw status --all` → laporan lengkap tersedia dan dapat dibagikan.
|
||||
- `openclaw gateway probe` → target gateway yang diharapkan dapat dijangkau (`Reachable: yes`). `RPC: limited - missing scope: operator.read` adalah diagnostik yang terdegradasi, bukan kegagalan koneksi.
|
||||
- `openclaw gateway status` → `Runtime: running` dan `RPC probe: ok`.
|
||||
- `openclaw doctor` → tidak ada error config/layanan yang memblokir.
|
||||
- `openclaw gateway probe` → target gateway yang diharapkan dapat dijangkau (`Reachable: yes`). `Capability: ...` memberi tahu tingkat auth apa yang dapat dibuktikan probe, dan `Read probe: limited - missing scope: operator.read` adalah diagnostik yang menurun, bukan kegagalan koneksi.
|
||||
- `openclaw gateway status` → `Runtime: running`, `Connectivity probe: ok`, dan baris `Capability: ...` yang masuk akal. Gunakan `--require-rpc` jika Anda juga memerlukan bukti RPC cakupan baca.
|
||||
- `openclaw doctor` → tidak ada error konfigurasi/layanan yang memblokir.
|
||||
- `openclaw channels status --probe` → gateway yang dapat dijangkau mengembalikan
|
||||
status transport live per akun plus hasil probe/audit seperti `works` atau `audit ok`; jika
|
||||
gateway tidak dapat dijangkau, perintah akan fallback ke ringkasan berbasis config saja.
|
||||
- `openclaw logs --follow` → aktivitas stabil, tidak ada error fatal yang berulang.
|
||||
status transport per-akun secara live beserta hasil probe/audit seperti `works` atau `audit ok`; jika
|
||||
gateway tidak dapat dijangkau, perintah kembali ke ringkasan berbasis konfigurasi saja.
|
||||
- `openclaw logs --follow` → aktivitas stabil, tanpa error fatal yang berulang.
|
||||
|
||||
## 429 konteks panjang Anthropic
|
||||
## Anthropic long context 429
|
||||
|
||||
Jika Anda melihat:
|
||||
`HTTP 429: rate_limit_error: Extra usage is required for long context requests`,
|
||||
buka [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/id/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context).
|
||||
|
||||
## Backend lokal yang kompatibel dengan OpenAI bekerja langsung tetapi gagal di OpenClaw
|
||||
## Backend lokal yang kompatibel OpenAI bekerja secara langsung tetapi gagal di OpenClaw
|
||||
|
||||
Jika backend `/v1` lokal atau self-hosted Anda merespons probe langsung
|
||||
`/v1/chat/completions` yang kecil tetapi gagal pada `openclaw infer model run` atau giliran
|
||||
agen normal:
|
||||
`/v1/chat/completions` kecil tetapi gagal pada `openclaw infer model run` atau turn
|
||||
agent normal:
|
||||
|
||||
1. Jika error menyebut `messages[].content` mengharapkan string, setel
|
||||
`models.providers.<provider>.models[].compat.requiresStringContent: true`.
|
||||
2. Jika backend masih gagal hanya pada giliran agen OpenClaw, setel
|
||||
2. Jika backend masih gagal hanya pada turn agent OpenClaw, setel
|
||||
`models.providers.<provider>.models[].compat.supportsTools: false` lalu coba lagi.
|
||||
3. Jika panggilan langsung kecil masih berfungsi tetapi prompt OpenClaw yang lebih besar membuat
|
||||
backend crash, anggap sisa masalah sebagai keterbatasan model/server upstream dan
|
||||
3. Jika panggilan langsung yang kecil tetap bekerja tetapi prompt OpenClaw yang lebih besar membuat
|
||||
backend crash, anggap masalah yang tersisa sebagai keterbatasan model/server upstream dan
|
||||
lanjutkan ke runbook mendalam:
|
||||
[/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail](/id/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail)
|
||||
|
||||
## Instal plugin gagal karena ekstensi openclaw tidak ada
|
||||
## Instalasi Plugin gagal dengan ekstensi openclaw yang hilang
|
||||
|
||||
Jika instalasi gagal dengan `package.json missing openclaw.extensions`, paket plugin
|
||||
menggunakan bentuk lama yang tidak lagi diterima OpenClaw.
|
||||
Jika instalasi gagal dengan `package.json missing openclaw.extensions`, paket Plugin
|
||||
menggunakan bentuk lama yang tidak lagi diterima oleh OpenClaw.
|
||||
|
||||
Perbaiki di paket plugin:
|
||||
Perbaiki di paket Plugin:
|
||||
|
||||
1. Tambahkan `openclaw.extensions` ke `package.json`.
|
||||
2. Arahkan entri ke file runtime hasil build (biasanya `./dist/index.js`).
|
||||
3. Publikasikan ulang plugin lalu jalankan `openclaw plugins install <package>` lagi.
|
||||
3. Publikasikan ulang Plugin lalu jalankan `openclaw plugins install <package>` lagi.
|
||||
|
||||
Contoh:
|
||||
|
||||
@ -87,7 +87,7 @@ Contoh:
|
||||
}
|
||||
```
|
||||
|
||||
Referensi: [Arsitektur plugin](/id/plugins/architecture)
|
||||
Referensi: [Arsitektur Plugin](/id/plugins/architecture)
|
||||
|
||||
## Pohon keputusan
|
||||
|
||||
@ -95,19 +95,19 @@ Referensi: [Arsitektur plugin](/id/plugins/architecture)
|
||||
flowchart TD
|
||||
A[OpenClaw tidak berfungsi] --> B{Apa yang pertama kali rusak}
|
||||
B --> C[Tidak ada balasan]
|
||||
B --> D[Dashboard atau UI Kontrol tidak dapat terhubung]
|
||||
B --> E[Gateway tidak dapat dimulai atau layanan tidak berjalan]
|
||||
B --> F[Saluran terhubung tetapi pesan tidak mengalir]
|
||||
B --> G[Cron atau heartbeat tidak berjalan atau tidak terkirim]
|
||||
B --> H[Node sudah dipasangkan tetapi exec layar kanvas kamera gagal]
|
||||
B --> I[Alat browser gagal]
|
||||
B --> D[Dashboard atau Control UI tidak dapat terhubung]
|
||||
B --> E[Gateway tidak dapat mulai atau layanan tidak berjalan]
|
||||
B --> F[Channel terhubung tetapi pesan tidak mengalir]
|
||||
B --> G[Cron atau Heartbeat tidak berjalan atau tidak terkirim]
|
||||
B --> H[Node sudah dipasangkan tetapi exec layar canvas kamera gagal]
|
||||
B --> I[Tool browser gagal]
|
||||
|
||||
C --> C1[/Bagian tidak ada balasan/]
|
||||
D --> D1[/Bagian UI Kontrol/]
|
||||
D --> D1[/Bagian Control UI/]
|
||||
E --> E1[/Bagian Gateway/]
|
||||
F --> F1[/Bagian alur saluran/]
|
||||
G --> G1[/Bagian otomasi/]
|
||||
H --> H1[/Bagian alat node/]
|
||||
F --> F1[/Bagian alur channel/]
|
||||
G --> G1[/Bagian otomatisasi/]
|
||||
H --> H1[/Bagian tool Node/]
|
||||
I --> I1[/Bagian browser/]
|
||||
```
|
||||
|
||||
@ -121,18 +121,19 @@ flowchart TD
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
Output yang baik terlihat seperti ini:
|
||||
Output yang baik terlihat seperti:
|
||||
|
||||
- `Runtime: running`
|
||||
- `RPC probe: ok`
|
||||
- Saluran Anda menunjukkan transport terhubung dan, jika didukung, `works` atau `audit ok` di `channels status --probe`
|
||||
- Pengirim tampak disetujui (atau kebijakan DM terbuka/allowlist)
|
||||
- `Connectivity probe: ok`
|
||||
- `Capability: read-only`, `write-capable`, atau `admin-capable`
|
||||
- Channel Anda menunjukkan transport terhubung dan, jika didukung, `works` atau `audit ok` di `channels status --probe`
|
||||
- Pengirim terlihat disetujui (atau kebijakan DM terbuka/allowlist)
|
||||
|
||||
Tanda log yang umum:
|
||||
Signature log umum:
|
||||
|
||||
- `drop guild message (mention required` → gerbang mention memblokir pesan di Discord.
|
||||
- `pairing request` → pengirim belum disetujui dan menunggu persetujuan pairing DM.
|
||||
- `blocked` / `allowlist` di log saluran → pengirim, room, atau grup difilter.
|
||||
- `drop guild message (mention required` → gating mention memblokir pesan di Discord.
|
||||
- `pairing request` → pengirim belum disetujui dan sedang menunggu persetujuan pairing DM.
|
||||
- `blocked` / `allowlist` di log channel → pengirim, room, atau grup difilter.
|
||||
|
||||
Halaman mendalam:
|
||||
|
||||
@ -142,7 +143,7 @@ flowchart TD
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Dashboard atau UI Kontrol tidak dapat terhubung">
|
||||
<Accordion title="Dashboard atau Control UI tidak dapat terhubung">
|
||||
```bash
|
||||
openclaw status
|
||||
openclaw gateway status
|
||||
@ -151,24 +152,28 @@ flowchart TD
|
||||
openclaw channels status --probe
|
||||
```
|
||||
|
||||
Output yang baik terlihat seperti ini:
|
||||
Output yang baik terlihat seperti:
|
||||
|
||||
- `Dashboard: http://...` ditampilkan di `openclaw gateway status`
|
||||
- `RPC probe: ok`
|
||||
- `Connectivity probe: ok`
|
||||
- `Capability: read-only`, `write-capable`, atau `admin-capable`
|
||||
- Tidak ada loop auth di log
|
||||
|
||||
Tanda log yang umum:
|
||||
Signature log umum:
|
||||
|
||||
- `device identity required` → konteks HTTP/non-aman tidak dapat menyelesaikan auth perangkat.
|
||||
- `origin not allowed` → `Origin` browser tidak diizinkan untuk
|
||||
target gateway UI Kontrol.
|
||||
- `AUTH_TOKEN_MISMATCH` dengan petunjuk percobaan ulang (`canRetryWithDeviceToken=true`) → satu percobaan ulang token perangkat tepercaya dapat terjadi secara otomatis.
|
||||
- Percobaan ulang token cache itu menggunakan kembali set scope cache yang disimpan bersama token perangkat yang dipasangkan. Pemanggil `deviceToken` eksplisit / `scopes` eksplisit tetap memakai set scope yang diminta.
|
||||
- Pada jalur UI Kontrol Tailscale Serve async, upaya gagal untuk
|
||||
- `device identity required` → HTTP/konteks non-aman tidak dapat menyelesaikan auth perangkat.
|
||||
- `origin not allowed` → browser `Origin` tidak diizinkan untuk target gateway
|
||||
Control UI.
|
||||
- `AUTH_TOKEN_MISMATCH` dengan petunjuk retry (`canRetryWithDeviceToken=true`) → satu retry device-token tepercaya dapat terjadi secara otomatis.
|
||||
- Retry token cache itu menggunakan kembali kumpulan scope cache yang disimpan bersama
|
||||
token perangkat yang dipasangkan. Pemanggil `deviceToken` eksplisit / `scopes` eksplisit mempertahankan
|
||||
kumpulan scope yang mereka minta.
|
||||
- Pada jalur async Tailscale Serve Control UI, upaya gagal untuk
|
||||
`{scope, ip}` yang sama diserialkan sebelum limiter mencatat kegagalan, sehingga
|
||||
percobaan ulang buruk kedua yang bersamaan sudah bisa menampilkan `retry later`.
|
||||
- `too many failed authentication attempts (retry later)` dari origin browser localhost → kegagalan berulang dari `Origin` yang sama untuk sementara dikunci; origin localhost lain memakai bucket terpisah.
|
||||
- `repeated unauthorized` setelah percobaan ulang itu → token/password salah, mode auth tidak cocok, atau token perangkat pasangan yang sudah usang.
|
||||
retry buruk kedua yang bersamaan sudah bisa menampilkan `retry later`.
|
||||
- `too many failed authentication attempts (retry later)` dari origin browser localhost
|
||||
→ kegagalan berulang dari `Origin` yang sama dikunci sementara; origin localhost lain menggunakan bucket terpisah.
|
||||
- `unauthorized` berulang setelah retry itu → token/password salah, mode auth tidak cocok, atau token perangkat yang dipasangkan sudah usang.
|
||||
- `gateway connect failed:` → UI menargetkan URL/port yang salah atau gateway tidak dapat dijangkau.
|
||||
|
||||
Halaman mendalam:
|
||||
@ -179,7 +184,7 @@ flowchart TD
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Gateway tidak dapat dimulai atau layanan terinstal tetapi tidak berjalan">
|
||||
<Accordion title="Gateway tidak dapat mulai atau layanan terpasang tetapi tidak berjalan">
|
||||
```bash
|
||||
openclaw status
|
||||
openclaw gateway status
|
||||
@ -188,17 +193,18 @@ flowchart TD
|
||||
openclaw channels status --probe
|
||||
```
|
||||
|
||||
Output yang baik terlihat seperti ini:
|
||||
Output yang baik terlihat seperti:
|
||||
|
||||
- `Service: ... (loaded)`
|
||||
- `Runtime: running`
|
||||
- `RPC probe: ok`
|
||||
- `Connectivity probe: ok`
|
||||
- `Capability: read-only`, `write-capable`, atau `admin-capable`
|
||||
|
||||
Tanda log yang umum:
|
||||
Signature log umum:
|
||||
|
||||
- `Gateway start blocked: set gateway.mode=local` atau `existing config is missing gateway.mode` → mode gateway adalah remote, atau file config tidak memiliki penanda local-mode dan harus diperbaiki.
|
||||
- `Gateway start blocked: set gateway.mode=local` atau `existing config is missing gateway.mode` → mode gateway adalah remote, atau file konfigurasi tidak memiliki stamp mode lokal dan harus diperbaiki.
|
||||
- `refusing to bind gateway ... without auth` → bind non-loopback tanpa jalur auth gateway yang valid (token/password, atau trusted-proxy jika dikonfigurasi).
|
||||
- `another gateway instance is already listening` atau `EADDRINUSE` → port sudah dipakai.
|
||||
- `another gateway instance is already listening` atau `EADDRINUSE` → port sudah digunakan.
|
||||
|
||||
Halaman mendalam:
|
||||
|
||||
@ -208,7 +214,7 @@ flowchart TD
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Saluran terhubung tetapi pesan tidak mengalir">
|
||||
<Accordion title="Channel terhubung tetapi pesan tidak mengalir">
|
||||
```bash
|
||||
openclaw status
|
||||
openclaw gateway status
|
||||
@ -217,17 +223,17 @@ flowchart TD
|
||||
openclaw channels status --probe
|
||||
```
|
||||
|
||||
Output yang baik terlihat seperti ini:
|
||||
Output yang baik terlihat seperti:
|
||||
|
||||
- Transport saluran terhubung.
|
||||
- Transport channel terhubung.
|
||||
- Pemeriksaan pairing/allowlist lolos.
|
||||
- Mention terdeteksi jika diwajibkan.
|
||||
|
||||
Tanda log yang umum:
|
||||
Signature log umum:
|
||||
|
||||
- `mention required` → gerbang mention memblokir pemrosesan grup.
|
||||
- `mention required` → gating mention grup memblokir pemrosesan.
|
||||
- `pairing` / `pending` → pengirim DM belum disetujui.
|
||||
- `not_in_channel`, `missing_scope`, `Forbidden`, `401/403` → masalah token izin saluran.
|
||||
- `not_in_channel`, `missing_scope`, `Forbidden`, `401/403` → masalah token izin channel.
|
||||
|
||||
Halaman mendalam:
|
||||
|
||||
@ -236,7 +242,7 @@ flowchart TD
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Cron atau heartbeat tidak berjalan atau tidak terkirim">
|
||||
<Accordion title="Cron atau Heartbeat tidak berjalan atau tidak terkirim">
|
||||
```bash
|
||||
openclaw status
|
||||
openclaw gateway status
|
||||
@ -246,21 +252,21 @@ flowchart TD
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
Output yang baik terlihat seperti ini:
|
||||
Output yang baik terlihat seperti:
|
||||
|
||||
- `cron.status` menunjukkan aktif dengan wake berikutnya.
|
||||
- `cron runs` menunjukkan entri `ok` terbaru.
|
||||
- Heartbeat aktif dan tidak berada di luar jam aktif.
|
||||
|
||||
Tanda log yang umum:
|
||||
Signature log umum:
|
||||
|
||||
- `cron: scheduler disabled; jobs will not run automatically` → cron dinonaktifkan.
|
||||
- `cron: scheduler disabled; jobs will not run automatically` → Cron dinonaktifkan.
|
||||
- `heartbeat skipped` dengan `reason=quiet-hours` → di luar jam aktif yang dikonfigurasi.
|
||||
- `heartbeat skipped` dengan `reason=empty-heartbeat-file` → `HEARTBEAT.md` ada tetapi hanya berisi scaffold kosong/header saja.
|
||||
- `heartbeat skipped` dengan `reason=empty-heartbeat-file` → `HEARTBEAT.md` ada tetapi hanya berisi scaffolding kosong/header-only.
|
||||
- `heartbeat skipped` dengan `reason=no-tasks-due` → mode tugas `HEARTBEAT.md` aktif tetapi belum ada interval tugas yang jatuh tempo.
|
||||
- `heartbeat skipped` dengan `reason=alerts-disabled` → semua visibilitas heartbeat dinonaktifkan (`showOk`, `showAlerts`, dan `useIndicator` semuanya mati).
|
||||
- `requests-in-flight` → lajur utama sibuk; wake heartbeat ditunda.
|
||||
- `unknown accountId` → account target pengiriman heartbeat tidak ada.
|
||||
- `requests-in-flight` → lane utama sibuk; wake heartbeat ditunda.
|
||||
- `unknown accountId` → target pengiriman heartbeat account tidak ada.
|
||||
|
||||
Halaman mendalam:
|
||||
|
||||
@ -270,7 +276,7 @@ flowchart TD
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Node sudah dipasangkan tetapi alat gagal pada exec layar kanvas kamera">
|
||||
<Accordion title="Node sudah dipasangkan tetapi tool gagal pada camera canvas screen exec">
|
||||
```bash
|
||||
openclaw status
|
||||
openclaw gateway status
|
||||
@ -279,17 +285,17 @@ flowchart TD
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
Output yang baik terlihat seperti ini:
|
||||
Output yang baik terlihat seperti:
|
||||
|
||||
- Node tercantum sebagai terhubung dan sudah dipasangkan untuk peran `node`.
|
||||
- Kapabilitas tersedia untuk perintah yang Anda panggil.
|
||||
- Status izin diberikan untuk alat tersebut.
|
||||
- Node terdaftar sebagai terhubung dan dipasangkan untuk peran `node`.
|
||||
- Capability ada untuk perintah yang Anda jalankan.
|
||||
- Status izin diberikan untuk tool tersebut.
|
||||
|
||||
Tanda log yang umum:
|
||||
Signature log umum:
|
||||
|
||||
- `NODE_BACKGROUND_UNAVAILABLE` → bawa aplikasi node ke foreground.
|
||||
- `*_PERMISSION_REQUIRED` → izin OS ditolak/tidak ada.
|
||||
- `SYSTEM_RUN_DENIED: approval required` → persetujuan exec sedang menunggu.
|
||||
- `SYSTEM_RUN_DENIED: approval required` → persetujuan exec masih tertunda.
|
||||
- `SYSTEM_RUN_DENIED: allowlist miss` → perintah tidak ada di allowlist exec.
|
||||
|
||||
Halaman mendalam:
|
||||
@ -308,14 +314,14 @@ flowchart TD
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
Yang berubah:
|
||||
Apa yang berubah:
|
||||
|
||||
- Jika `tools.exec.host` tidak disetel, default-nya adalah `auto`.
|
||||
- `host=auto` di-resolve menjadi `sandbox` saat runtime sandbox aktif, dan `gateway` jika tidak.
|
||||
- `host=auto` hanya untuk perutean; perilaku tanpa prompt "YOLO" berasal dari `security=full` plus `ask=off` pada gateway/node.
|
||||
- Pada `gateway` dan `node`, `tools.exec.security` yang tidak disetel default-nya `full`.
|
||||
- `tools.exec.ask` yang tidak disetel default-nya `off`.
|
||||
- Hasilnya: jika Anda melihat persetujuan, beberapa kebijakan lokal-host atau per-sesi telah memperketat exec dari default saat ini.
|
||||
- `host=auto` akan di-resolve ke `sandbox` saat runtime sandbox aktif, dan ke `gateway` jika tidak.
|
||||
- `host=auto` hanya untuk routing; perilaku "YOLO" tanpa prompt berasal dari `security=full` plus `ask=off` pada gateway/node.
|
||||
- Pada `gateway` dan `node`, `tools.exec.security` yang tidak disetel default-nya adalah `full`.
|
||||
- `tools.exec.ask` yang tidak disetel default-nya adalah `off`.
|
||||
- Hasilnya: jika Anda melihat permintaan persetujuan, ada kebijakan lokal-host atau per-sesi yang memperketat exec dari default saat ini.
|
||||
|
||||
Pulihkan perilaku tanpa persetujuan sesuai default saat ini:
|
||||
|
||||
@ -328,14 +334,14 @@ flowchart TD
|
||||
|
||||
Alternatif yang lebih aman:
|
||||
|
||||
- Setel hanya `tools.exec.host=gateway` jika Anda hanya ingin perutean host yang stabil.
|
||||
- Gunakan `security=allowlist` dengan `ask=on-miss` jika Anda ingin exec host tetapi tetap ingin peninjauan saat ada miss pada allowlist.
|
||||
- Aktifkan mode sandbox jika Anda ingin `host=auto` di-resolve kembali ke `sandbox`.
|
||||
- Setel hanya `tools.exec.host=gateway` jika Anda hanya menginginkan routing host yang stabil.
|
||||
- Gunakan `security=allowlist` dengan `ask=on-miss` jika Anda menginginkan host exec tetapi tetap ingin peninjauan saat terjadi miss pada allowlist.
|
||||
- Aktifkan mode sandbox jika Anda ingin `host=auto` kembali di-resolve ke `sandbox`.
|
||||
|
||||
Tanda log yang umum:
|
||||
Signature log umum:
|
||||
|
||||
- `Approval required.` → perintah sedang menunggu `/approve ...`.
|
||||
- `SYSTEM_RUN_DENIED: approval required` → persetujuan exec host-node sedang menunggu.
|
||||
- `SYSTEM_RUN_DENIED: approval required` → persetujuan exec host-node masih tertunda.
|
||||
- `exec host=sandbox requires a sandbox runtime for this session` → pemilihan sandbox implisit/eksplisit tetapi mode sandbox nonaktif.
|
||||
|
||||
Halaman mendalam:
|
||||
@ -346,7 +352,7 @@ flowchart TD
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Alat browser gagal">
|
||||
<Accordion title="Tool browser gagal">
|
||||
```bash
|
||||
openclaw status
|
||||
openclaw gateway status
|
||||
@ -355,22 +361,22 @@ flowchart TD
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
Output yang baik terlihat seperti ini:
|
||||
Output yang baik terlihat seperti:
|
||||
|
||||
- Status browser menunjukkan `running: true` dan browser/profile yang dipilih.
|
||||
- `openclaw` dimulai, atau `user` dapat melihat tab Chrome lokal.
|
||||
- `openclaw` berhasil mulai, atau `user` dapat melihat tab Chrome lokal.
|
||||
|
||||
Tanda log yang umum:
|
||||
Signature log umum:
|
||||
|
||||
- `unknown command "browser"` atau `unknown command 'browser'` → `plugins.allow` disetel dan tidak menyertakan `browser`.
|
||||
- `unknown command "browser"` atau `unknown command 'browser'` → `plugins.allow` disetel dan tidak mencakup `browser`.
|
||||
- `Failed to start Chrome CDP on port` → peluncuran browser lokal gagal.
|
||||
- `browser.executablePath not found` → path biner yang dikonfigurasi salah.
|
||||
- `browser.cdpUrl must be http(s) or ws(s)` → URL CDP yang dikonfigurasi menggunakan skema yang tidak didukung.
|
||||
- `browser.cdpUrl has invalid port` → URL CDP yang dikonfigurasi memiliki port yang buruk atau di luar rentang.
|
||||
- `No Chrome tabs found for profile="user"` → profile lampiran Chrome MCP tidak memiliki tab Chrome lokal yang terbuka.
|
||||
- `Remote CDP for profile "<name>" is not reachable` → endpoint CDP jarak jauh yang dikonfigurasi tidak dapat dijangkau dari host ini.
|
||||
- `No Chrome tabs found for profile="user"` → profile attach Chrome MCP tidak memiliki tab Chrome lokal yang terbuka.
|
||||
- `Remote CDP for profile "<name>" is not reachable` → endpoint CDP remote yang dikonfigurasi tidak dapat dijangkau dari host ini.
|
||||
- `Browser attachOnly is enabled ... not reachable` atau `Browser attachOnly is enabled and CDP websocket ... is not reachable` → profile attach-only tidak memiliki target CDP live.
|
||||
- override viewport / mode gelap / locale / offline yang usang pada profile attach-only atau CDP jarak jauh → jalankan `openclaw browser stop --browser-profile <name>` untuk menutup sesi kontrol aktif dan melepaskan state emulasi tanpa memulai ulang gateway.
|
||||
- override viewport / dark-mode / locale / offline yang stale pada profile attach-only atau remote CDP → jalankan `openclaw browser stop --browser-profile <name>` untuk menutup sesi kontrol aktif dan melepaskan state emulasi tanpa me-restart gateway.
|
||||
|
||||
Halaman mendalam:
|
||||
|
||||
@ -388,5 +394,5 @@ flowchart TD
|
||||
- [FAQ](/id/help/faq) — pertanyaan yang sering diajukan
|
||||
- [Pemecahan Masalah Gateway](/id/gateway/troubleshooting) — masalah khusus gateway
|
||||
- [Doctor](/id/gateway/doctor) — pemeriksaan kesehatan dan perbaikan otomatis
|
||||
- [Pemecahan Masalah Saluran](/id/channels/troubleshooting) — masalah konektivitas saluran
|
||||
- [Pemecahan Masalah Otomasi](/id/automation/cron-jobs#troubleshooting) — masalah cron dan heartbeat
|
||||
- [Pemecahan Masalah Channel](/id/channels/troubleshooting) — masalah konektivitas channel
|
||||
- [Pemecahan Masalah Otomatisasi](/id/automation/cron-jobs#troubleshooting) — masalah Cron dan Heartbeat
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue
Block a user