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

chore(i18n): add it tr id pl translations

Browse Source
This commit is contained in:
Peter Steinberger 2026-04-05 15:54:45 +01:00
parent b0b4652d1d
commit aaca615b6b
No known key found for this signature in database
1608 changed files with 360417 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/.i18n/id.tm.jsonl
View File

@ -1 +0,0 @@

1
docs/.i18n/it.tm.jsonl
View File

@ -1 +0,0 @@

1
docs/.i18n/pl.tm.jsonl
View File

@ -1 +0,0 @@

1
docs/.i18n/tr.tm.jsonl
View File

@ -1 +0,0 @@

81
docs/id/.i18n/README.md Normal file
View File

@ -0,0 +1,81 @@
---
x-i18n:
generated_at: "2026-04-05T13:42:11Z"
model: gpt-5.4
provider: openai
source_hash: f07671afbba2efa77f5fb43ebed242d0fdca835f7810fdd60998e537b73d1efc
source_path: .i18n/README.md
workflow: 15
---
# Aset i18n dokumen OpenClaw
Folder ini menyimpan konfigurasi terjemahan untuk repo dokumen sumber.
Pohon lokal yang dihasilkan dan memori terjemahan langsung kini berada di repo publikasi:
- repo: `openclaw/docs`
- checkout lokal: `~/Projects/openclaw-docs`
## Sumber kebenaran
- Dokumen bahasa Inggris ditulis di `openclaw/openclaw`.
- Pohon dokumen sumber berada di bawah `docs/`.
- Repo sumber tidak lagi menyimpan pohon lokal yang dihasilkan dan dikomit seperti `docs/zh-CN/**`, `docs/ja-JP/**`, `docs/es/**`, `docs/pt-BR/**`, `docs/ko/**`, `docs/de/**`, `docs/fr/**`, `docs/ar/**`, `docs/it/**`, `docs/tr/**`, `docs/id/**`, atau `docs/pl/**`.
## Alur end-to-end
1. Edit dokumen bahasa Inggris di `openclaw/openclaw`.
2. Push ke `main`.
3. `openclaw/openclaw/.github/workflows/docs-sync-publish.yml` mencerminkan pohon dokumen ke `openclaw/docs`.
4. Skrip sinkronisasi menulis ulang `docs/docs.json` publikasi agar blok pemilih lokal yang dihasilkan ada di sana meskipun tidak lagi dikomit di repo sumber.
5. `openclaw/docs/.github/workflows/translate-zh-cn.yml` menyegarkan `docs/zh-CN/**` sekali sehari, sesuai permintaan, dan setelah dispatch rilis repo sumber.
6. `openclaw/docs/.github/workflows/translate-ja-jp.yml` melakukan hal yang sama untuk `docs/ja-JP/**`.
7. `openclaw/docs/.github/workflows/translate-es.yml`, `translate-pt-br.yml`, `translate-ko.yml`, `translate-de.yml`, `translate-fr.yml`, `translate-ar.yml`, `translate-it.yml`, `translate-tr.yml`, `translate-id.yml`, dan `translate-pl.yml` melakukan hal yang sama untuk `docs/es/**`, `docs/pt-BR/**`, `docs/ko/**`, `docs/de/**`, `docs/fr/**`, `docs/ar/**`, `docs/it/**`, `docs/tr/**`, `docs/id/**`, dan `docs/pl/**`.
## Mengapa pemisahan ini ada
- Menjaga output lokal yang dihasilkan tetap berada di luar repo produk utama.
- Menjaga Mintlify tetap pada satu pohon dokumen yang dipublikasikan.
- Mempertahankan pengalih bahasa bawaan dengan membiarkan repo publikasi memiliki pohon lokal yang dihasilkan.
## File di folder ini
- `glossary.<lang>.json` — pemetaan istilah pilihan yang digunakan sebagai panduan prompt.
- `ar-navigation.json`, `de-navigation.json`, `es-navigation.json`, `fr-navigation.json`, `id-navigation.json`, `it-navigation.json`, `ja-navigation.json`, `ko-navigation.json`, `pl-navigation.json`, `pt-BR-navigation.json`, `tr-navigation.json`, `zh-Hans-navigation.json` — blok pemilih lokal Mintlify yang disisipkan kembali ke repo publikasi selama sinkronisasi.
- `<lang>.tm.jsonl` — memori terjemahan yang dikunci oleh workflow + model + hash teks.
Di repo ini, file TM lokal yang dihasilkan seperti `docs/.i18n/zh-CN.tm.jsonl`, `docs/.i18n/ja-JP.tm.jsonl`, `docs/.i18n/es.tm.jsonl`, `docs/.i18n/pt-BR.tm.jsonl`, `docs/.i18n/ko.tm.jsonl`, `docs/.i18n/de.tm.jsonl`, `docs/.i18n/fr.tm.jsonl`, `docs/.i18n/ar.tm.jsonl`, `docs/.i18n/it.tm.jsonl`, `docs/.i18n/tr.tm.jsonl`, `docs/.i18n/id.tm.jsonl`, dan `docs/.i18n/pl.tm.jsonl` memang sengaja tidak lagi dikomit.
## Format glosarium
`glossary.<lang>.json` adalah array entri:
```json
{
"source": "troubleshooting",
"target": "故障排除"
}
```
Kolom:
- `source`: frasa bahasa Inggris (atau sumber) yang diprioritaskan.
- `target`: output terjemahan pilihan.
## Mekanisme terjemahan
- `scripts/docs-i18n` masih memiliki tanggung jawab atas pembuatan terjemahan.
- Mode dokumen menulis `x-i18n.source_hash` ke setiap halaman yang diterjemahkan.
- Setiap workflow publikasi menghitung lebih dulu daftar file tertunda dengan membandingkan hash sumber bahasa Inggris saat ini dengan `x-i18n.source_hash` lokal yang tersimpan.
- Jika jumlah tertunda adalah `0`, langkah terjemahan yang mahal dilewati sepenuhnya.
- Jika ada file tertunda, workflow hanya menerjemahkan file-file tersebut.
- Workflow publikasi mencoba ulang kegagalan format model yang bersifat sementara, tetapi file yang tidak berubah tetap dilewati karena pemeriksaan hash yang sama dijalankan pada setiap percobaan ulang.
- Repo sumber juga melakukan dispatch penyegaran zh-CN, ja-JP, es, pt-BR, ko, de, fr, ar, it, tr, id, dan pl setelah rilis GitHub dipublikasikan agar dokumen rilis dapat menyusul tanpa menunggu cron harian.
## Catatan operasional
- Metadata sinkronisasi ditulis ke `.openclaw-sync/source.json` di repo publikasi.
- Secret repo sumber: `OPENCLAW_DOCS_SYNC_TOKEN`
- Secret repo publikasi: `OPENCLAW_DOCS_I18N_OPENAI_API_KEY`
- Jika output lokal terlihat usang, periksa workflow `Translate <locale>` yang sesuai di `openclaw/docs` terlebih dahulu.

87
docs/id/auth-credential-semantics.md Normal file
View File

@ -0,0 +1,87 @@
---
read_when:
- Saat mengerjakan resolusi profil auth atau perutean kredensial
- Saat men-debug kegagalan auth model atau urutan profil
summary: Semantik kanonis kelayakan kredensial dan resolusi untuk profil auth
title: Semantik Kredensial Auth
x-i18n:
generated_at: "2026-04-05T13:42:07Z"
model: gpt-5.4
provider: openai
source_hash: a4cd3e16cd25eb22c5e707311d06a19df1a59747ee3261c2d32c534a245fd7fb
source_path: auth-credential-semantics.md
workflow: 15
---
# Semantik Kredensial Auth
Dokumen ini mendefinisikan semantik kanonis kelayakan kredensial dan resolusi yang digunakan di seluruh:
- `resolveAuthProfileOrder`
- `resolveApiKeyForProfile`
- `models status --probe`
- `doctor-auth`
Tujuannya adalah menjaga perilaku saat pemilihan dan saat runtime tetap selaras.
## Kode Alasan Probe yang Stabil
- `ok`
- `excluded_by_auth_order`
- `missing_credential`
- `invalid_expires`
- `expired`
- `unresolved_ref`
- `no_model`
## Kredensial Token
Kredensial token (`type: "token"`) mendukung `token` inline dan/atau `tokenRef`.
### Aturan kelayakan
1. Profil token tidak memenuhi syarat ketika `token` dan `tokenRef` sama-sama tidak ada.
2. `expires` bersifat opsional.
3. Jika `expires` ada, nilainya harus berupa angka hingga yang lebih besar dari `0`.
4. Jika `expires` tidak valid (`NaN`, `0`, negatif, tidak hingga, atau tipe yang salah), profil tidak memenuhi syarat dengan `invalid_expires`.
5. Jika `expires` berada di masa lalu, profil tidak memenuhi syarat dengan `expired`.
6. `tokenRef` tidak melewati validasi `expires`.
### Aturan resolusi
1. Semantik resolver cocok dengan semantik kelayakan untuk `expires`.
2. Untuk profil yang memenuhi syarat, materi token dapat diresolusikan dari nilai inline atau `tokenRef`.
3. Ref yang tidak dapat diresolusikan menghasilkan `unresolved_ref` dalam output `models status --probe`.
## Pemfilteran Urutan Auth Eksplisit
- Ketika `auth.order.<provider>` atau override urutan auth-store ditetapkan untuk suatu
provider, `models status --probe` hanya mem-probe id profil yang tetap berada dalam
urutan auth yang telah diresolusikan untuk provider tersebut.
- Profil tersimpan untuk provider tersebut yang dihilangkan dari urutan eksplisit
tidak akan dicoba secara diam-diam nanti. Output probe melaporkannya dengan
`reasonCode: excluded_by_auth_order` dan detail
`Dikecualikan oleh auth.order untuk provider ini.`
## Resolusi Target Probe
- Target probe dapat berasal dari profil auth, kredensial environment, atau
`models.json`.
- Jika suatu provider memiliki kredensial tetapi OpenClaw tidak dapat meresolusikan kandidat
model yang dapat di-probe untuknya, `models status --probe` melaporkan `status: no_model` dengan
`reasonCode: no_model`.
## Guard Kebijakan OAuth SecretRef
- Input SecretRef hanya untuk kredensial statis.
- Jika kredensial profil adalah `type: "oauth"`, objek SecretRef tidak didukung untuk materi kredensial profil tersebut.
- Jika `auth.profiles.<id>.mode` adalah `"oauth"`, input `keyRef`/`tokenRef` berbasis SecretRef untuk profil tersebut ditolak.
- Pelanggaran merupakan kegagalan keras dalam jalur resolusi auth saat startup/reload.
## Pesan yang Kompatibel dengan Versi Lama
Untuk kompatibilitas skrip, error probe mempertahankan baris pertama ini tanpa perubahan:
`Auth profile credentials are missing or expired.`
Detail yang ramah bagi manusia dan kode alasan yang stabil dapat ditambahkan pada baris berikutnya.

15
docs/id/automation/auth-monitoring.md Normal file
View File

@ -0,0 +1,15 @@
---
summary: Alihkan ke /gateway/authentication
title: Pemantauan Auth
x-i18n:
generated_at: "2026-04-05T13:41:58Z"
model: gpt-5.4
provider: openai
source_hash: 42aa1b4aa76201b20e07d8ad77231607855e7e7421fa032830055144ccd8819a
source_path: automation/auth-monitoring.md
workflow: 15
---
# Pemantauan Auth
Halaman ini dipindahkan ke [Authentication](/gateway/authentication). Lihat [Authentication](/gateway/authentication) untuk dokumentasi pemantauan auth.

15
docs/id/automation/clawflow.md Normal file
View File

@ -0,0 +1,15 @@
---
summary: Alihkan ke Task Flow
title: ClawFlow
x-i18n:
generated_at: "2026-04-05T13:41:58Z"
model: gpt-5.4
provider: openai
source_hash: e644237e0812f25b46a06ff125c8858dbc69a499aa43cfd73cf7cb37572e78e6
source_path: automation/clawflow.md
workflow: 15
---
# ClawFlow
ClawFlow diubah namanya menjadi [Task Flow](/automation/taskflow). Lihat [Task Flow](/automation/taskflow) untuk dokumentasi terbaru.

414
docs/id/automation/cron-jobs.md Normal file
View File

@ -0,0 +1,414 @@
---
read_when:
- Menjadwalkan pekerjaan latar belakang atau wakeup
- Menghubungkan pemicu eksternal (webhook, Gmail) ke OpenClaw
- Memutuskan antara heartbeat dan cron untuk tugas terjadwal
summary: Pekerjaan terjadwal, webhook, dan pemicu Gmail PubSub untuk scheduler Gateway
title: Tugas Terjadwal
x-i18n:
generated_at: "2026-04-05T13:42:42Z"
model: gpt-5.4
provider: openai
source_hash: 43b906914461aba9af327e7e8c22aa856f65802ec2da37ed0c4f872d229cfde6
source_path: automation/cron-jobs.md
workflow: 15
---
# Tugas Terjadwal (Cron)
Cron adalah scheduler bawaan Gateway. Ini menyimpan pekerjaan, membangunkan agen pada waktu yang tepat, dan dapat mengirimkan output kembali ke channel chat atau endpoint webhook.
## Mulai cepat
```bash
# Tambahkan pengingat sekali jalan
openclaw cron add \
--name "Reminder" \
--at "2026-02-01T16:00:00Z" \
--session main \
--system-event "Reminder: check the cron docs draft" \
--wake now \
--delete-after-run
# Periksa pekerjaan Anda
openclaw cron list
# Lihat riwayat eksekusi
openclaw cron runs --id <job-id>
```
## Cara kerja cron
- Cron berjalan **di dalam** proses Gateway (bukan di dalam model).
- Pekerjaan disimpan di `~/.openclaw/cron/jobs.json` sehingga restart tidak menghilangkan jadwal.
- Semua eksekusi cron membuat catatan [tugas latar belakang](/automation/tasks).
- Pekerjaan sekali jalan (`--at`) otomatis dihapus setelah berhasil secara default.
- Eksekusi cron terisolasi akan menutup tab/proses browser yang terlacak untuk sesi `cron:<jobId>` mereka secara best-effort saat eksekusi selesai, sehingga otomasi browser yang terlepas tidak meninggalkan proses yatim.
- Eksekusi cron terisolasi juga melindungi dari balasan pengakuan yang kedaluwarsa. Jika
hasil pertama hanya berupa pembaruan status sementara (`on it`, `pulling everything
together`, dan petunjuk serupa) dan tidak ada eksekusi subagen turunan yang masih
bertanggung jawab atas jawaban akhir, OpenClaw akan meminta ulang sekali untuk hasil yang sebenarnya
sebelum pengiriman.
Rekonsiliasi tugas untuk cron dimiliki oleh runtime: tugas cron aktif tetap hidup selama
runtime cron masih melacak pekerjaan tersebut sebagai sedang berjalan, meskipun baris sesi anak lama masih ada.
Setelah runtime berhenti memiliki pekerjaan itu dan jendela tenggang 5 menit berakhir, maintenance dapat
menandai tugas sebagai `lost`.
## Jenis jadwal
| Jenis | Flag CLI | Deskripsi |
| ------- | --------- | ------------------------------------------------------------- |
| `at` | `--at` | Stempel waktu sekali jalan (ISO 8601 atau relatif seperti `20m`) |
| `every` | `--every` | Interval tetap |
| `cron` | `--cron` | Ekspresi cron 5-field atau 6-field dengan `--tz` opsional |
Stempel waktu tanpa zona waktu diperlakukan sebagai UTC. Tambahkan `--tz America/New_York` untuk penjadwalan waktu lokal.
Ekspresi rekuren tepat di awal jam otomatis di-stagger hingga 5 menit untuk mengurangi lonjakan beban. Gunakan `--exact` untuk memaksa waktu yang presisi atau `--stagger 30s` untuk jendela eksplisit.
## Gaya eksekusi
| Gaya | Nilai `--session` | Berjalan di | Paling cocok untuk |
| --------------- | ------------------- | ------------------------- | --------------------------------- |
| Sesi utama | `main` | Giliran heartbeat berikutnya | Pengingat, peristiwa sistem |
| Terisolasi | `isolated` | `cron:<jobId>` khusus | Laporan, pekerjaan latar belakang |
| Sesi saat ini | `current` | Terikat saat pembuatan | Pekerjaan rekuren yang sadar konteks |
| Sesi kustom | `session:custom-id` | Sesi bernama persisten | Workflow yang dibangun di atas riwayat |
Pekerjaan **sesi utama** mengantrikan peristiwa sistem dan secara opsional membangunkan heartbeat (`--wake now` atau `--wake next-heartbeat`). Pekerjaan **terisolasi** menjalankan giliran agen khusus dengan sesi baru. **Sesi kustom** (`session:xxx`) mempertahankan konteks antar eksekusi, memungkinkan workflow seperti standup harian yang dibangun dari ringkasan sebelumnya.
Untuk pekerjaan terisolasi, teardown runtime sekarang mencakup pembersihan browser secara best-effort untuk sesi cron tersebut. Kegagalan pembersihan diabaikan sehingga hasil cron yang sebenarnya tetap menjadi prioritas.
Saat eksekusi cron terisolasi mengorkestrasi subagen, pengiriman juga lebih mengutamakan
output turunan akhir daripada teks sementara induk yang sudah kedaluwarsa. Jika turunan masih
berjalan, OpenClaw menekan pembaruan induk parsial tersebut alih-alih mengumumkannya.
### Opsi payload untuk pekerjaan terisolasi
- `--message`: teks prompt (wajib untuk terisolasi)
- `--model` / `--thinking`: override model dan tingkat pemikiran
- `--light-context`: lewati injeksi file bootstrap workspace
- `--tools exec,read`: batasi alat mana yang dapat digunakan pekerjaan
`--model` menggunakan model yang dipilih dan diizinkan untuk pekerjaan tersebut. Jika model yang diminta
tidak diizinkan, cron mencatat peringatan dan kembali ke pemilihan model agen/default
untuk pekerjaan itu. Rantai fallback yang dikonfigurasi tetap berlaku, tetapi override model biasa
tanpa daftar fallback per pekerjaan yang eksplisit tidak lagi menambahkan model utama agen sebagai target retry tambahan yang tersembunyi.
Urutan prioritas pemilihan model untuk pekerjaan terisolasi adalah:
1. Override model hook Gmail (saat eksekusi berasal dari Gmail dan override itu diizinkan)
2. `model` payload per pekerjaan
3. Override model sesi cron yang tersimpan
4. Pemilihan model agen/default
Mode cepat juga mengikuti pemilihan live yang telah diselesaikan. Jika konfigurasi model terpilih
memiliki `params.fastMode`, cron terisolasi akan menggunakannya secara default. Override `fastMode`
sesi yang tersimpan tetap lebih diutamakan daripada config dalam kedua arah.
Jika eksekusi terisolasi mencapai handoff perpindahan model live, cron akan mencoba ulang dengan
penyedia/model yang telah dialihkan dan menyimpan pemilihan live tersebut sebelum mencoba ulang. Saat
perpindahan itu juga membawa profil auth baru, cron juga menyimpan override profil auth
tersebut. Retry dibatasi: setelah percobaan awal ditambah 2 retry perpindahan
, cron akan membatalkan alih-alih berulang tanpa akhir.
## Pengiriman dan output
| Mode | Yang terjadi |
| --------- | ---------------------------------------------------------- |
| `announce` | Kirim ringkasan ke channel target (default untuk terisolasi) |
| `webhook` | POST payload peristiwa selesai ke URL |
| `none` | Internal saja, tanpa pengiriman |
Gunakan `--announce --channel telegram --to "-1001234567890"` untuk pengiriman ke channel. Untuk topik forum Telegram, gunakan `-1001234567890:topic:123`. Target Slack/Discord/Mattermost harus menggunakan prefiks eksplisit (`channel:<id>`, `user:<id>`).
Untuk pekerjaan terisolasi yang dimiliki cron, runner memiliki jalur pengiriman akhir. Agen
diprompt untuk mengembalikan ringkasan teks biasa, lalu ringkasan itu dikirim
melalui `announce`, `webhook`, atau tetap internal untuk `none`. `--no-deliver`
tidak mengembalikan pengiriman ke agen; ini membuat eksekusi tetap internal.
Jika tugas asli secara eksplisit mengatakan untuk mengirim pesan ke penerima eksternal tertentu, agen
harus mencatat kepada siapa/ke mana pesan itu harus dikirim dalam outputnya alih-alih
mencoba mengirimkannya langsung.
Notifikasi kegagalan mengikuti jalur tujuan terpisah:
- `cron.failureDestination` menetapkan default global untuk notifikasi kegagalan.
- `job.delivery.failureDestination` menimpa itu per pekerjaan.
- Jika keduanya tidak disetel dan pekerjaan sudah mengirim melalui `announce`, notifikasi kegagalan kini akan fallback ke target announce utama tersebut.
- `delivery.failureDestination` hanya didukung pada pekerjaan `sessionTarget="isolated"` kecuali mode pengiriman utama adalah `webhook`.
## Contoh CLI
Pengingat sekali jalan (sesi utama):
```bash
openclaw cron add \
--name "Calendar check" \
--at "20m" \
--session main \
--system-event "Next heartbeat: check calendar." \
--wake now
```
Pekerjaan terisolasi rekuren dengan pengiriman:
```bash
openclaw cron add \
--name "Morning brief" \
--cron "0 7 * * *" \
--tz "America/Los_Angeles" \
--session isolated \
--message "Summarize overnight updates." \
--announce \
--channel slack \
--to "channel:C1234567890"
```
Pekerjaan terisolasi dengan override model dan thinking:
```bash
openclaw cron add \
--name "Deep analysis" \
--cron "0 6 * * 1" \
--tz "America/Los_Angeles" \
--session isolated \
--message "Weekly deep analysis of project progress." \
--model "opus" \
--thinking high \
--announce
```
## Webhook
Gateway dapat mengekspos endpoint webhook HTTP untuk pemicu eksternal. Aktifkan di config:
```json5
{
hooks: {
enabled: true,
token: "shared-secret",
path: "/hooks",
},
}
```
### Autentikasi
Setiap permintaan harus menyertakan token hook melalui header:
- `Authorization: Bearer <token>` (disarankan)
- `x-openclaw-token: <token>`
Token query-string ditolak.
### POST /hooks/wake
Antrikan peristiwa sistem untuk sesi utama:
```bash
curl -X POST http://127.0.0.1:18789/hooks/wake \
-H 'Authorization: Bearer SECRET' \
-H 'Content-Type: application/json' \
-d '{"text":"New email received","mode":"now"}'
```
- `text` (wajib): deskripsi peristiwa
- `mode` (opsional): `now` (default) atau `next-heartbeat`
### POST /hooks/agent
Jalankan giliran agen terisolasi:
```bash
curl -X POST http://127.0.0.1:18789/hooks/agent \
-H 'Authorization: Bearer SECRET' \
-H 'Content-Type: application/json' \
-d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.4-mini"}'
```
Field: `message` (wajib), `name`, `agentId`, `wakeMode`, `deliver`, `channel`, `to`, `model`, `thinking`, `timeoutSeconds`.
### Hook yang dipetakan (POST /hooks/\<name\>)
Nama hook kustom diselesaikan melalui `hooks.mappings` di config. Mapping dapat mentransformasi payload arbitrer menjadi aksi `wake` atau `agent` dengan template atau transformasi kode.
### Keamanan
- Simpan endpoint hook di balik loopback, tailnet, atau reverse proxy tepercaya.
- Gunakan token hook khusus; jangan gunakan ulang token auth gateway.
- Simpan `hooks.path` pada subpath khusus; `/` ditolak.
- Set `hooks.allowedAgentIds` untuk membatasi routing `agentId` eksplisit.
- Biarkan `hooks.allowRequestSessionKey=false` kecuali Anda memerlukan sesi yang dipilih pemanggil.
- Jika Anda mengaktifkan `hooks.allowRequestSessionKey`, set juga `hooks.allowedSessionKeyPrefixes` untuk membatasi bentuk session key yang diizinkan.
- Payload hook dibungkus dengan batas keamanan secara default.
## Integrasi Gmail PubSub
Hubungkan pemicu inbox Gmail ke OpenClaw melalui Google PubSub.
**Prasyarat**: `gcloud` CLI, `gog` (gogcli), hook OpenClaw diaktifkan, Tailscale untuk endpoint HTTPS publik.
### Setup wizard (disarankan)
```bash
openclaw webhooks gmail setup --account openclaw@gmail.com
```
Ini menulis config `hooks.gmail`, mengaktifkan preset Gmail, dan menggunakan Tailscale Funnel untuk endpoint push.
### Gateway auto-start
Saat `hooks.enabled=true` dan `hooks.gmail.account` disetel, Gateway memulai `gog gmail watch serve` saat boot dan memperbarui watch secara otomatis. Set `OPENCLAW_SKIP_GMAIL_WATCHER=1` untuk menonaktifkannya.
### Setup manual sekali saja
1. Pilih project GCP yang memiliki klien OAuth yang digunakan oleh `gog`:
```bash
gcloud auth login
gcloud config set project <project-id>
gcloud services enable gmail.googleapis.com pubsub.googleapis.com
```
2. Buat topic dan berikan akses push Gmail:
```bash
gcloud pubsub topics create gog-gmail-watch
gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
--member=serviceAccount:gmail-api-push@system.gserviceaccount.com \
--role=roles/pubsub.publisher
```
3. Mulai watch:
```bash
gog gmail watch start \
--account openclaw@gmail.com \
--label INBOX \
--topic projects/<project-id>/topics/gog-gmail-watch
```
### Override model Gmail
```json5
{
hooks: {
gmail: {
model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
thinking: "off",
},
},
}
```
## Mengelola pekerjaan
```bash
# Daftar semua pekerjaan
openclaw cron list
# Edit pekerjaan
openclaw cron edit <jobId> --message "Updated prompt" --model "opus"
# Paksa jalankan pekerjaan sekarang
openclaw cron run <jobId>
# Jalankan hanya jika sudah jatuh tempo
openclaw cron run <jobId> --due
# Lihat riwayat eksekusi
openclaw cron runs --id <jobId> --limit 50
# Hapus pekerjaan
openclaw cron remove <jobId>
# Pemilihan agen (setup multi-agen)
openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops
openclaw cron edit <jobId> --clear-agent
```
Catatan override model:
- `openclaw cron add|edit --model ...` mengubah model yang dipilih untuk pekerjaan.
- Jika model diizinkan, penyedia/model yang tepat itu akan mencapai eksekusi agen terisolasi.
- Jika tidak diizinkan, cron memberi peringatan dan kembali ke pemilihan model agen/default pekerjaan tersebut.
- Rantai fallback yang dikonfigurasi tetap berlaku, tetapi override `--model` biasa
tanpa daftar fallback per pekerjaan yang eksplisit tidak lagi diteruskan ke model utama agen
sebagai target retry tambahan diam-diam.
## Konfigurasi
```json5
{
cron: {
enabled: true,
store: "~/.openclaw/cron/jobs.json",
maxConcurrentRuns: 1,
retry: {
maxAttempts: 3,
backoffMs: [60000, 120000, 300000],
retryOn: ["rate_limit", "overloaded", "network", "server_error"],
},
webhookToken: "replace-with-dedicated-webhook-token",
sessionRetention: "24h",
runLog: { maxBytes: "2mb", keepLines: 2000 },
},
}
```
Nonaktifkan cron: `cron.enabled: false` atau `OPENCLAW_SKIP_CRON=1`.
**Retry sekali jalan**: error sementara (rate limit, overload, network, server error) akan dicoba ulang hingga 3 kali dengan exponential backoff. Error permanen langsung dinonaktifkan.
**Retry rekuren**: exponential backoff (30 detik hingga 60 menit) di antara retry. Backoff direset setelah eksekusi berhasil berikutnya.
**Maintenance**: `cron.sessionRetention` (default `24h`) memangkas entri sesi eksekusi terisolasi. `cron.runLog.maxBytes` / `cron.runLog.keepLines` memangkas file log eksekusi secara otomatis.
## Pemecahan masalah
### Urutan perintah
```bash
openclaw status
openclaw gateway status
openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow
openclaw doctor
```
### Cron tidak berjalan
- Periksa `cron.enabled` dan variabel env `OPENCLAW_SKIP_CRON`.
- Pastikan Gateway berjalan terus-menerus.
- Untuk jadwal `cron`, verifikasi zona waktu (`--tz`) dibandingkan zona waktu host.
- `reason: not-due` di output eksekusi berarti eksekusi manual diperiksa dengan `openclaw cron run <jobId> --due` dan pekerjaan belum jatuh tempo.
### Cron berjalan tetapi tidak ada pengiriman
- Mode pengiriman `none` berarti tidak ada pesan eksternal yang diharapkan.
- Target pengiriman hilang/tidak valid (`channel`/`to`) berarti pengiriman keluar dilewati.
- Error auth channel (`unauthorized`, `Forbidden`) berarti pengiriman diblokir oleh kredensial.
- Jika eksekusi terisolasi hanya mengembalikan token senyap (`NO_REPLY` / `no_reply`),
OpenClaw menekan pengiriman keluar langsung dan juga menekan jalur fallback
ringkasan antrean, sehingga tidak ada yang diposting kembali ke chat.
- Untuk pekerjaan terisolasi yang dimiliki cron, jangan mengharapkan agen menggunakan message tool
sebagai fallback. Runner memiliki pengiriman akhir; `--no-deliver` membuatnya
tetap internal alih-alih mengizinkan pengiriman langsung.
### Jebakan zona waktu
- Cron tanpa `--tz` menggunakan zona waktu host gateway.
- Jadwal `at` tanpa zona waktu diperlakukan sebagai UTC.
- `activeHours` heartbeat menggunakan resolusi zona waktu yang dikonfigurasi.
## Terkait
- [Otomasi & Tugas](/automation) — semua mekanisme otomasi secara ringkas
- [Tugas Latar Belakang](/automation/tasks) — ledger tugas untuk eksekusi cron
- [Heartbeat](/gateway/heartbeat) — giliran sesi utama periodik
- [Zona Waktu](/concepts/timezone) — konfigurasi zona waktu

15
docs/id/automation/cron-vs-heartbeat.md Normal file
View File

@ -0,0 +1,15 @@
---
summary: Alihkan ke /automation
title: Cron vs Heartbeat
x-i18n:
generated_at: "2026-04-05T13:41:58Z"
model: gpt-5.4
provider: openai
source_hash: 579c6618108ad7e2a71f53d5d6aa6550956fa0fdb2fe64ecdb7e8a0ce1366e33
source_path: automation/cron-vs-heartbeat.md
workflow: 15
---
# Cron vs Heartbeat
Halaman ini telah dipindahkan ke [Automation & Tasks](/automation). Lihat [Automation & Tasks](/automation) untuk panduan keputusan yang membandingkan cron dan heartbeat.

15
docs/id/automation/gmail-pubsub.md Normal file
View File

@ -0,0 +1,15 @@
---
summary: Alihkan ke /automation/cron-jobs
title: Gmail PubSub
x-i18n:
generated_at: "2026-04-05T13:41:58Z"
model: gpt-5.4
provider: openai
source_hash: c2e17fdc8c09d52b6dc9fb6c44053446f07d02c65a0ab725d4ea038bd035d889
source_path: automation/gmail-pubsub.md
workflow: 15
---
# Gmail PubSub
Halaman ini dipindahkan ke [Tugas Terjadwal](/automation/cron-jobs#gmail-pubsub-integration). Lihat [Tugas Terjadwal](/automation/cron-jobs#gmail-pubsub-integration) untuk dokumentasi Gmail PubSub.

310
docs/id/automation/hooks.md Normal file
View File

@ -0,0 +1,310 @@
---
read_when:
- Anda ingin otomatisasi berbasis peristiwa untuk /new, /reset, /stop, dan peristiwa siklus hidup agen
- Anda ingin membangun, menginstal, atau men-debug hook
summary: 'Hooks: otomatisasi berbasis peristiwa untuk perintah dan peristiwa siklus hidup'
title: Hooks
x-i18n:
generated_at: "2026-04-05T13:42:29Z"
model: gpt-5.4
provider: openai
source_hash: 66eb75bb2b3b2ad229bf3da24fdb0fe021ed08f812fd1d13c69b3bd9df0218e5
source_path: automation/hooks.md
workflow: 15
---
# Hooks
Hooks adalah skrip kecil yang berjalan saat sesuatu terjadi di dalam Gateway. Hooks ditemukan secara otomatis dari direktori dan dapat diperiksa dengan `openclaw hooks`.
Ada dua jenis hook di OpenClaw:
- **Hook internal** (halaman ini): berjalan di dalam Gateway saat peristiwa agen dipicu, seperti `/new`, `/reset`, `/stop`, atau peristiwa siklus hidup.
- **Webhook**: endpoint HTTP eksternal yang memungkinkan sistem lain memicu pekerjaan di OpenClaw. Lihat [Webhooks](/automation/cron-jobs#webhooks).
Hooks juga dapat dibundel di dalam plugin. `openclaw hooks list` menampilkan hook mandiri dan hook yang dikelola plugin.
## Mulai cepat
```bash
# Daftar hook yang tersedia
openclaw hooks list
# Aktifkan hook
openclaw hooks enable session-memory
# Periksa status hook
openclaw hooks check
# Dapatkan informasi terperinci
openclaw hooks info session-memory
```
## Jenis peristiwa
| Peristiwa | Kapan dipicu |
| ----------------------- | ------------------------------------------------ |
| `command:new` | Perintah `/new` dijalankan |
| `command:reset` | Perintah `/reset` dijalankan |
| `command:stop` | Perintah `/stop` dijalankan |
| `command` | Peristiwa perintah apa pun (listener umum) |
| `session:compact:before`| Sebelum pemadatan merangkum riwayat |
| `session:compact:after` | Setelah pemadatan selesai |
| `session:patch` | Saat properti sesi diubah |
| `agent:bootstrap` | Sebelum file bootstrap workspace disisipkan |
| `gateway:startup` | Setelah channel dimulai dan hook dimuat |
| `message:received` | Pesan masuk dari channel mana pun |
| `message:transcribed` | Setelah transkripsi audio selesai |
| `message:preprocessed` | Setelah semua pemahaman media dan tautan selesai |
| `message:sent` | Pesan keluar terkirim |
## Menulis hook
### Struktur hook
Setiap hook adalah direktori yang berisi dua file:
```
my-hook/
├── HOOK.md # Metadata + dokumentasi
└── handler.ts # Implementasi handler
```
### Format HOOK.md
```markdown
---
name: my-hook
description: "Deskripsi singkat tentang apa yang dilakukan hook ini"
metadata:
{ "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }
---
# My Hook
Dokumentasi terperinci ada di sini.
```
**Bidang metadata** (`metadata.openclaw`):
| Bidang | Deskripsi |
| --------- | ---------------------------------------------------- |
| `emoji` | Emoji tampilan untuk CLI |
| `events` | Array peristiwa yang akan didengarkan |
| `export` | Named export yang akan digunakan (default `"default"`) |
| `os` | Platform yang diperlukan (misalnya `["darwin", "linux"]`) |
| `requires`| `bins`, `anyBins`, `env`, atau jalur `config` yang diperlukan |
| `always` | Lewati pemeriksaan kelayakan (boolean) |
| `install` | Metode instalasi |
### Implementasi handler
```typescript
const handler = async (event) => {
if (event.type !== "command" || event.action !== "new") {
return;
}
console.log(`[my-hook] New command triggered`);
// Your logic here
// Optionally send message to user
event.messages.push("Hook executed!");
};
export default handler;
```
Setiap peristiwa mencakup: `type`, `action`, `sessionKey`, `timestamp`, `messages` (push untuk mengirim ke pengguna), dan `context` (data spesifik peristiwa).
### Sorotan konteks peristiwa
**Peristiwa perintah** (`command:new`, `command:reset`): `context.sessionEntry`, `context.previousSessionEntry`, `context.commandSource`, `context.workspaceDir`, `context.cfg`.
**Peristiwa pesan** (`message:received`): `context.from`, `context.content`, `context.channelId`, `context.metadata` (data spesifik provider termasuk `senderId`, `senderName`, `guildId`).
**Peristiwa pesan** (`message:sent`): `context.to`, `context.content`, `context.success`, `context.channelId`.
**Peristiwa pesan** (`message:transcribed`): `context.transcript`, `context.from`, `context.channelId`, `context.mediaPath`.
**Peristiwa pesan** (`message:preprocessed`): `context.bodyForAgent` (isi akhir yang telah diperkaya), `context.from`, `context.channelId`.
**Peristiwa bootstrap** (`agent:bootstrap`): `context.bootstrapFiles` (array yang dapat diubah), `context.agentId`.
**Peristiwa patch sesi** (`session:patch`): `context.sessionEntry`, `context.patch` (hanya bidang yang berubah), `context.cfg`. Hanya klien dengan hak istimewa yang dapat memicu peristiwa patch.
**Peristiwa pemadatan**: `session:compact:before` mencakup `messageCount`, `tokenCount`. `session:compact:after` menambahkan `compactedCount`, `summaryLength`, `tokensBefore`, `tokensAfter`.
## Penemuan hook
Hooks ditemukan dari direktori berikut, dalam urutan prioritas override yang meningkat:
1. **Hook bawaan**: dikirim bersama OpenClaw
2. **Hook plugin**: hook yang dibundel di dalam plugin yang terinstal
3. **Hook terkelola**: `~/.openclaw/hooks/` (diinstal pengguna, dibagikan di seluruh workspace). Direktori tambahan dari `hooks.internal.load.extraDirs` berbagi prioritas ini.
4. **Hook workspace**: `<workspace>/hooks/` (per agen, dinonaktifkan secara default sampai diaktifkan secara eksplisit)
Hook workspace dapat menambahkan nama hook baru tetapi tidak dapat mengganti hook bawaan, terkelola, atau yang disediakan plugin dengan nama yang sama.
### Paket hook
Paket hook adalah paket npm yang mengekspor hook melalui `openclaw.hooks` di `package.json`. Instal dengan:
```bash
openclaw plugins install <path-or-spec>
```
Spesifikasi npm hanya untuk registry (nama paket + versi tepat opsional atau dist-tag). Spesifikasi Git/URL/file dan rentang semver ditolak.
## Hook bawaan
| Hook | Peristiwa | Fungsinya |
| --------------------- | ------------------------------ | ----------------------------------------------------- |
| session-memory | `command:new`, `command:reset` | Menyimpan konteks sesi ke `<workspace>/memory/` |
| bootstrap-extra-files | `agent:bootstrap` | Menyisipkan file bootstrap tambahan dari pola glob |
| command-logger | `command` | Mencatat semua perintah ke `~/.openclaw/logs/commands.log` |
| boot-md | `gateway:startup` | Menjalankan `BOOT.md` saat gateway dimulai |
Aktifkan hook bawaan apa pun:
```bash
openclaw hooks enable <hook-name>
```
### Detail session-memory
Mengekstrak 15 pesan pengguna/asisten terakhir, menghasilkan slug nama file deskriptif melalui LLM, dan menyimpannya ke `<workspace>/memory/YYYY-MM-DD-slug.md`. Memerlukan `workspace.dir` dikonfigurasi.
### Konfigurasi bootstrap-extra-files
```json
{
"hooks": {
"internal": {
"entries": {
"bootstrap-extra-files": {
"enabled": true,
"paths": ["packages/*/AGENTS.md", "packages/*/TOOLS.md"]
}
}
}
}
}
```
Path diselesaikan relatif terhadap workspace. Hanya basename bootstrap yang dikenali yang dimuat (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, `MEMORY.md`).
## Hook plugin
Plugin dapat mendaftarkan hook melalui Plugin SDK untuk integrasi yang lebih dalam: mencegat panggilan alat, memodifikasi prompt, mengontrol alur pesan, dan banyak lagi. Plugin SDK menyediakan 28 hook yang mencakup resolusi model, siklus hidup agen, alur pesan, eksekusi alat, koordinasi subagen, dan siklus hidup gateway.
Untuk referensi hook plugin lengkap termasuk `before_tool_call`, `before_agent_reply`, `before_install`, dan semua hook plugin lainnya, lihat [Plugin Architecture](/plugins/architecture#provider-runtime-hooks).
## Konfigurasi
```json
{
"hooks": {
"internal": {
"enabled": true,
"entries": {
"session-memory": { "enabled": true },
"command-logger": { "enabled": false }
}
}
}
}
```
Variabel lingkungan per hook:
```json
{
"hooks": {
"internal": {
"entries": {
"my-hook": {
"enabled": true,
"env": { "MY_CUSTOM_VAR": "value" }
}
}
}
}
}
```
Direktori hook tambahan:
```json
{
"hooks": {
"internal": {
"load": {
"extraDirs": ["/path/to/more/hooks"]
}
}
}
}
```
<Note>
Format konfigurasi array legacy `hooks.internal.handlers` masih didukung untuk kompatibilitas mundur, tetapi hook baru sebaiknya menggunakan sistem berbasis penemuan.
</Note>
## Referensi CLI
```bash
# Daftar semua hook (tambahkan --eligible, --verbose, atau --json)
openclaw hooks list
# Tampilkan info terperinci tentang sebuah hook
openclaw hooks info <hook-name>
# Tampilkan ringkasan kelayakan
openclaw hooks check
# Aktifkan/nonaktifkan
openclaw hooks enable <hook-name>
openclaw hooks disable <hook-name>
```
## Praktik terbaik
- **Jaga handler tetap cepat.** Hooks berjalan selama pemrosesan perintah. Jalankan pekerjaan berat secara fire-and-forget dengan `void processInBackground(event)`.
- **Tangani error dengan baik.** Bungkus operasi berisiko dalam try/catch; jangan throw agar handler lain tetap dapat berjalan.
- **Filter peristiwa lebih awal.** Segera return jika tipe/aksi peristiwa tidak relevan.
- **Gunakan kunci peristiwa spesifik.** Pilih `"events": ["command:new"]` daripada `"events": ["command"]` untuk mengurangi overhead.
## Pemecahan masalah
### Hook tidak ditemukan
```bash
# Verifikasi struktur direktori
ls -la ~/.openclaw/hooks/my-hook/
# Seharusnya menampilkan: HOOK.md, handler.ts
# Daftar semua hook yang ditemukan
openclaw hooks list
```
### Hook tidak memenuhi syarat
```bash
openclaw hooks info my-hook
```
Periksa biner yang hilang (PATH), variabel lingkungan, nilai konfigurasi, atau kompatibilitas OS.
### Hook tidak berjalan
1. Verifikasi hook diaktifkan: `openclaw hooks list`
2. Mulai ulang proses gateway Anda agar hook dimuat ulang.
3. Periksa log gateway: `./scripts/clawlog.sh | grep hook`
## Terkait
- [Referensi CLI: hooks](/cli/hooks)
- [Webhooks](/automation/cron-jobs#webhooks)
- [Plugin Architecture](/plugins/architecture#provider-runtime-hooks) — referensi hook plugin lengkap
- [Configuration](/gateway/configuration-reference#hooks)

122
docs/id/automation/index.md Normal file
View File

@ -0,0 +1,122 @@
---
read_when:
- Menentukan cara mengotomatisasi pekerjaan dengan OpenClaw
- Memilih antara heartbeat, cron, hooks, dan standing orders
- Mencari titik masuk otomatisasi yang tepat
summary: 'Gambaran umum mekanisme otomatisasi: tugas, cron, hooks, standing orders, dan Task Flow'
title: Otomatisasi & Tugas
x-i18n:
generated_at: "2026-04-05T13:42:19Z"
model: gpt-5.4
provider: openai
source_hash: 13cd05dcd2f38737f7bb19243ad1136978bfd727006fd65226daa3590f823afe
source_path: automation/index.md
workflow: 15
---
# Otomatisasi & Tugas
OpenClaw menjalankan pekerjaan di latar belakang melalui tugas, pekerjaan terjadwal, event hook, dan instruksi tetap. Halaman ini membantu Anda memilih mekanisme yang tepat dan memahami bagaimana semuanya saling terkait.
## Panduan keputusan cepat
```mermaid
flowchart TD
START([Apa yang Anda butuhkan?]) --> Q1{Menjadwalkan pekerjaan?}
START --> Q2{Melacak pekerjaan yang dilepas?}
START --> Q3{Mengorkestrasi alur multi-langkah?}
START --> Q4{Bereaksi terhadap peristiwa siklus hidup?}
START --> Q5{Memberi agen instruksi persisten?}
Q1 -->|Ya| Q1a{Waktu tepat atau fleksibel?}
Q1a -->|Tepat| CRON["Tugas Terjadwal (Cron)"]
Q1a -->|Fleksibel| HEARTBEAT[Heartbeat]
Q2 -->|Ya| TASKS[Tugas Latar Belakang]
Q3 -->|Ya| FLOW[Task Flow]
Q4 -->|Ya| HOOKS[Hooks]
Q5 -->|Ya| SO[Standing Orders]
```
| Kasus penggunaan | Rekomendasi | Alasan |
| --------------------------------------- | --------------------- | ----------------------------------------------- |
| Kirim laporan harian tepat pukul 9 pagi | Tugas Terjadwal (Cron) | Waktu tepat, eksekusi terisolasi |
| Ingatkan saya dalam 20 menit | Tugas Terjadwal (Cron) | Sekali jalan dengan waktu yang presisi (`--at`) |
| Jalankan analisis mendalam mingguan | Tugas Terjadwal (Cron) | Tugas mandiri, dapat menggunakan model berbeda |
| Periksa inbox setiap 30 menit | Heartbeat | Digabungkan dengan pemeriksaan lain, sadar konteks |
| Pantau kalender untuk acara mendatang | Heartbeat | Cocok secara alami untuk kesadaran berkala |
| Periksa status subagent atau eksekusi ACP | Tugas Latar Belakang | Buku besar tugas melacak semua pekerjaan yang dilepas |
| Audit apa yang dijalankan dan kapan | Tugas Latar Belakang | `openclaw tasks list` dan `openclaw tasks audit` |
| Riset multi-langkah lalu rangkum | Task Flow | Orkestrasi tahan lama dengan pelacakan revisi |
| Jalankan skrip saat reset sesi | Hooks | Berbasis peristiwa, dipicu pada peristiwa siklus hidup |
| Jalankan kode pada setiap pemanggilan tool | Hooks | Hooks dapat memfilter berdasarkan jenis peristiwa |
| Selalu periksa kepatuhan sebelum membalas | Standing Orders | Disuntikkan ke setiap sesi secara otomatis |
### Tugas Terjadwal (Cron) vs Heartbeat
| Dimensi | Tugas Terjadwal (Cron) | Heartbeat |
| --------------- | ----------------------------------- | ------------------------------------ |
| Waktu | Tepat (ekspresi cron, sekali jalan) | Perkiraan (default setiap 30 menit) |
| Konteks sesi | Baru (terisolasi) atau bersama | Konteks sesi utama penuh |
| Catatan tugas | Selalu dibuat | Tidak pernah dibuat |
| Penyampaian | Channel, webhook, atau senyap | Inline di sesi utama |
| Paling cocok untuk | Laporan, pengingat, pekerjaan latar belakang | Pemeriksaan inbox, kalender, notifikasi |
Gunakan Tugas Terjadwal (Cron) saat Anda membutuhkan waktu yang presisi atau eksekusi terisolasi. Gunakan Heartbeat saat pekerjaan mendapat manfaat dari konteks sesi penuh dan waktu perkiraan sudah memadai.
## Konsep inti
### Tugas terjadwal (cron)
Cron adalah penjadwal bawaan Gateway untuk waktu yang presisi. Cron menyimpan pekerjaan, membangunkan agen pada waktu yang tepat, dan dapat mengirimkan output ke channel obrolan atau endpoint webhook. Mendukung pengingat sekali jalan, ekspresi berulang, dan pemicu webhook masuk.
Lihat [Tugas Terjadwal](/automation/cron-jobs).
### Tugas
Buku besar tugas latar belakang melacak semua pekerjaan yang dilepas: eksekusi ACP, spawn subagent, eksekusi cron terisolasi, dan operasi CLI. Tugas adalah catatan, bukan penjadwal. Gunakan `openclaw tasks list` dan `openclaw tasks audit` untuk memeriksanya.
Lihat [Tugas Latar Belakang](/automation/tasks).
### Task Flow
Task Flow adalah substrat orkestrasi alur di atas tugas latar belakang. Task Flow mengelola alur multi-langkah yang tahan lama dengan mode sinkronisasi terkelola dan tercermin, pelacakan revisi, serta `openclaw tasks flow list|show|cancel` untuk inspeksi.
Lihat [Task Flow](/automation/taskflow).
### Standing orders
Standing orders memberi agen wewenang operasional permanen untuk program yang ditentukan. Standing orders disimpan dalam file workspace (biasanya `AGENTS.md`) dan disuntikkan ke setiap sesi. Gabungkan dengan cron untuk penegakan berbasis waktu.
Lihat [Standing Orders](/automation/standing-orders).
### Hooks
Hooks adalah skrip berbasis peristiwa yang dipicu oleh peristiwa siklus hidup agen (`/new`, `/reset`, `/stop`), pemadatan sesi, startup gateway, alur pesan, dan pemanggilan tool. Hooks ditemukan secara otomatis dari direktori dan dapat dikelola dengan `openclaw hooks`.
Lihat [Hooks](/automation/hooks).
### Heartbeat
Heartbeat adalah giliran sesi utama berkala (default setiap 30 menit). Heartbeat menggabungkan beberapa pemeriksaan (inbox, kalender, notifikasi) dalam satu giliran agen dengan konteks sesi penuh. Giliran heartbeat tidak membuat catatan tugas. Gunakan `HEARTBEAT.md` untuk daftar periksa kecil, atau blok `tasks:` saat Anda menginginkan pemeriksaan berkala hanya-saat-jatuh-tempo di dalam heartbeat itu sendiri. File heartbeat kosong dilewati sebagai `empty-heartbeat-file`; mode tugas hanya-saat-jatuh-tempo dilewati sebagai `no-tasks-due`.
Lihat [Heartbeat](/gateway/heartbeat).
## Cara kerjanya bersama-sama
- **Cron** menangani jadwal presisi (laporan harian, tinjauan mingguan) dan pengingat sekali jalan. Semua eksekusi cron membuat catatan tugas.
- **Heartbeat** menangani pemantauan rutin (inbox, kalender, notifikasi) dalam satu giliran gabungan setiap 30 menit.
- **Hooks** bereaksi terhadap peristiwa tertentu (pemanggilan tool, reset sesi, pemadatan) dengan skrip kustom.
- **Standing orders** memberi agen konteks persisten dan batas wewenang.
- **Task Flow** mengoordinasikan alur multi-langkah di atas tugas individual.
- **Tugas** secara otomatis melacak semua pekerjaan yang dilepas sehingga Anda dapat memeriksa dan mengauditnya.
## Terkait
- [Tugas Terjadwal](/automation/cron-jobs) — penjadwalan presisi dan pengingat sekali jalan
- [Tugas Latar Belakang](/automation/tasks) — buku besar tugas untuk semua pekerjaan yang dilepas
- [Task Flow](/automation/taskflow) — orkestrasi alur multi-langkah yang tahan lama
- [Hooks](/automation/hooks) — skrip siklus hidup berbasis peristiwa
- [Standing Orders](/automation/standing-orders) — instruksi agen persisten
- [Heartbeat](/gateway/heartbeat) — giliran sesi utama berkala
- [Referensi Konfigurasi](/gateway/configuration-reference) — semua kunci konfigurasi

15
docs/id/automation/poll.md Normal file
View File

@ -0,0 +1,15 @@
---
summary: Alihkan ke /tools/message
title: Polling
x-i18n:
generated_at: "2026-04-05T13:42:01Z"
model: gpt-5.4
provider: openai
source_hash: 8d69432ad8ba5fd80b59f8df779a1105ce0a2ff767d7dd5dc9d8e3ac1cb1ff1f
source_path: automation/poll.md
workflow: 15
---
# Polling
Halaman ini telah dipindahkan ke [alat Message](/cli/message). Lihat [alat Message](/cli/message) untuk dokumentasi polling.

261
docs/id/automation/standing-orders.md Normal file
View File

@ -0,0 +1,261 @@
---
read_when:
- Menyiapkan alur kerja agen otonom yang berjalan tanpa prompt per tugas
- Menentukan apa yang dapat dilakukan agen secara mandiri vs. apa yang memerlukan persetujuan manusia
- Menyusun agen multi-program dengan batasan yang jelas dan aturan eskalasi
summary: Tentukan otoritas operasional permanen untuk program agen otonom
title: Standing Orders
x-i18n:
generated_at: "2026-04-05T13:42:29Z"
model: gpt-5.4
provider: openai
source_hash: 81347d7a51a6ce20e6493277afee92073770f69a91a2e6b3bf87b99bb586d038
source_path: automation/standing-orders.md
workflow: 15
---
# Standing Orders
Standing orders memberi agen Anda **otoritas operasional permanen** untuk program yang ditentukan. Alih-alih memberikan instruksi tugas satu per satu setiap kali, Anda menentukan program dengan cakupan, pemicu, dan aturan eskalasi yang jelas — lalu agen mengeksekusi secara otonom di dalam batasan tersebut.
Inilah perbedaan antara memberi tahu asisten Anda "kirim laporan mingguan" setiap hari Jumat vs. memberikan otoritas tetap: "Anda bertanggung jawab atas laporan mingguan. Susun setiap hari Jumat, kirim, dan eskalasikan hanya jika ada sesuatu yang terlihat salah."
## Mengapa Standing Orders?
**Tanpa standing orders:**
- Anda harus memicu agen untuk setiap tugas
- Agen diam tidak aktif di antara permintaan
- Pekerjaan rutin terlupakan atau tertunda
- Anda menjadi bottleneck
**Dengan standing orders:**
- Agen mengeksekusi secara otonom dalam batasan yang ditentukan
- Pekerjaan rutin berjalan sesuai jadwal tanpa prompt
- Anda hanya terlibat untuk pengecualian dan persetujuan
- Agen mengisi waktu senggang secara produktif
## Cara Kerjanya
Standing orders ditentukan dalam file [agent workspace](/concepts/agent-workspace) Anda. Pendekatan yang direkomendasikan adalah menyertakannya langsung di `AGENTS.md` (yang otomatis disuntikkan di setiap sesi) agar agen selalu memilikinya dalam konteks. Untuk konfigurasi yang lebih besar, Anda juga dapat menaruhnya di file khusus seperti `standing-orders.md` dan mereferensikannya dari `AGENTS.md`.
Setiap program menentukan:
1. **Cakupan** — apa yang berwenang dilakukan agen
2. **Pemicu** — kapan harus mengeksekusi (jadwal, peristiwa, atau kondisi)
3. **Gerbang persetujuan** — apa yang memerlukan persetujuan manusia sebelum bertindak
4. **Aturan eskalasi** — kapan harus berhenti dan meminta bantuan
Agen memuat instruksi ini di setiap sesi melalui file bootstrap workspace (lihat [Agent Workspace](/concepts/agent-workspace) untuk daftar lengkap file yang disuntikkan otomatis) dan mengeksekusi berdasarkan instruksi tersebut, dikombinasikan dengan [cron jobs](/automation/cron-jobs) untuk penegakan berbasis waktu.
<Tip>
Letakkan standing orders di `AGENTS.md` untuk memastikan semuanya dimuat di setiap sesi. Bootstrap workspace otomatis menyuntikkan `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, dan `MEMORY.md` — tetapi tidak file sembarang di subdirektori.
</Tip>
## Anatomi Standing Order
```markdown
## Program: Weekly Status Report
**Authority:** Compile data, generate report, deliver to stakeholders
**Trigger:** Every Friday at 4 PM (enforced via cron job)
**Approval gate:** None for standard reports. Flag anomalies for human review.
**Escalation:** If data source is unavailable or metrics look unusual (>2σ from norm)
### Execution Steps
1. Pull metrics from configured sources
2. Compare to prior week and targets
3. Generate report in Reports/weekly/YYYY-MM-DD.md
4. Deliver summary via configured channel
5. Log completion to Agent/Logs/
### What NOT to Do
- Do not send reports to external parties
- Do not modify source data
- Do not skip delivery if metrics look bad — report accurately
```
## Standing Orders + Cron Jobs
Standing orders menentukan **apa** yang berwenang dilakukan agen. [Cron jobs](/automation/cron-jobs) menentukan **kapan** hal itu terjadi. Keduanya bekerja bersama:
```
Standing Order: "Anda bertanggung jawab atas triase inbox harian"
↓
Cron Job (setiap hari pukul 8 pagi): "Jalankan triase inbox sesuai standing orders"
↓
Agen: Membaca standing orders → mengeksekusi langkah-langkah → melaporkan hasil
```
Prompt cron job seharusnya mereferensikan standing order, bukan menduplikasinya:
```bash
openclaw cron add \
--name daily-inbox-triage \
--cron "0 8 * * 1-5" \
--tz America/New_York \
--timeout-seconds 300 \
--announce \
--channel bluebubbles \
--to "+1XXXXXXXXXX" \
--message "Execute daily inbox triage per standing orders. Check mail for new alerts. Parse, categorize, and persist each item. Report summary to owner. Escalate unknowns."
```
## Contoh
### Contoh 1: Konten & Media Sosial (Siklus Mingguan)
```markdown
## Program: Content & Social Media
**Authority:** Draft content, schedule posts, compile engagement reports
**Approval gate:** All posts require owner review for first 30 days, then standing approval
**Trigger:** Weekly cycle (Monday review → mid-week drafts → Friday brief)
### Weekly Cycle
- **Monday:** Review platform metrics and audience engagement
- **Tuesday–Thursday:** Draft social posts, create blog content
- **Friday:** Compile weekly marketing brief → deliver to owner
### Content Rules
- Voice must match the brand (see SOUL.md or brand voice guide)
- Never identify as AI in public-facing content
- Include metrics when available
- Focus on value to audience, not self-promotion
```
### Contoh 2: Operasi Keuangan (Dipicu Peristiwa)
```markdown
## Program: Financial Processing
**Authority:** Process transaction data, generate reports, send summaries
**Approval gate:** None for analysis. Recommendations require owner approval.
**Trigger:** New data file detected OR scheduled monthly cycle
### When New Data Arrives
1. Detect new file in designated input directory
2. Parse and categorize all transactions
3. Compare against budget targets
4. Flag: unusual items, threshold breaches, new recurring charges
5. Generate report in designated output directory
6. Deliver summary to owner via configured channel
### Escalation Rules
- Single item > $500: immediate alert
- Category > budget by 20%: flag in report
- Unrecognizable transaction: ask owner for categorization
- Failed processing after 2 retries: report failure, do not guess
```
### Contoh 3: Pemantauan & Peringatan (Berkelanjutan)
```markdown
## Program: System Monitoring
**Authority:** Check system health, restart services, send alerts
**Approval gate:** Restart services automatically. Escalate if restart fails twice.
**Trigger:** Every heartbeat cycle
### Checks
- Service health endpoints responding
- Disk space above threshold
- Pending tasks not stale (>24 hours)
- Delivery channels operational
### Response Matrix
| Condition | Action | Escalate? |
| ---------------- | ------------------------ | ------------------------ |
| Service down | Restart automatically | Only if restart fails 2x |
| Disk space < 10% | Alert owner | Yes |
| Stale task > 24h | Remind owner | No |
| Channel offline | Log and retry next cycle | If offline > 2 hours |
```
## Pola Execute-Verify-Report
Standing orders bekerja paling baik jika digabungkan dengan disiplin eksekusi yang ketat. Setiap tugas dalam standing order harus mengikuti loop ini:
1. **Execute** — Lakukan pekerjaan yang sebenarnya (jangan hanya mengakui instruksinya)
2. **Verify** — Konfirmasi bahwa hasilnya benar (file ada, pesan terkirim, data berhasil diparse)
3. **Report** — Beri tahu pemilik apa yang telah dilakukan dan apa yang telah diverifikasi
```markdown
### Execution Rules
- Every task follows Execute-Verify-Report. No exceptions.
- "I'll do that" is not execution. Do it, then report.
- "Done" without verification is not acceptable. Prove it.
- If execution fails: retry once with adjusted approach.
- If still fails: report failure with diagnosis. Never silently fail.
- Never retry indefinitely — 3 attempts max, then escalate.
```
Pola ini mencegah mode kegagalan agen yang paling umum: mengakui sebuah tugas tanpa menyelesaikannya.
## Arsitektur Multi-Program
Untuk agen yang mengelola banyak area, susun standing orders sebagai program terpisah dengan batasan yang jelas:
```markdown
# Standing Orders
## Program 1: [Domain A] (Weekly)
...
## Program 2: [Domain B] (Monthly + On-Demand)
...
## Program 3: [Domain C] (As-Needed)
...
## Escalation Rules (All Programs)
- [Common escalation criteria]
- [Approval gates that apply across programs]
```
Setiap program seharusnya memiliki:
- **Kadensi pemicu** sendiri (mingguan, bulanan, berbasis peristiwa, berkelanjutan)
- **Gerbang persetujuan** sendiri (beberapa program memerlukan pengawasan lebih banyak daripada yang lain)
- **Batasan** yang jelas (agen harus mengetahui di mana satu program berakhir dan program lain dimulai)
## Praktik Terbaik
### Lakukan
- Mulailah dengan otoritas yang sempit dan perluas seiring tumbuhnya kepercayaan
- Tentukan gerbang persetujuan yang eksplisit untuk tindakan berisiko tinggi
- Sertakan bagian "Apa yang TIDAK boleh dilakukan" — batasan sama pentingnya dengan izin
- Gabungkan dengan cron jobs untuk eksekusi berbasis waktu yang andal
- Tinjau log agen setiap minggu untuk memverifikasi bahwa standing orders diikuti
- Perbarui standing orders seiring kebutuhan Anda berkembang — ini adalah dokumen hidup
### Hindari
- Memberikan otoritas yang luas sejak hari pertama ("lakukan apa pun yang menurut Anda terbaik")
- Melewatkan aturan eskalasi — setiap program membutuhkan klausul "kapan harus berhenti dan bertanya"
- Menganggap agen akan mengingat instruksi lisan — tuliskan semuanya di file
- Mencampur banyak area dalam satu program — program terpisah untuk domain yang terpisah
- Lupa menegakkan dengan cron jobs — standing orders tanpa pemicu akan menjadi saran saja
## Terkait
- [Automation & Tasks](/automation) — semua mekanisme otomasi secara ringkas
- [Cron Jobs](/automation/cron-jobs) — penegakan jadwal untuk standing orders
- [Hooks](/automation/hooks) — skrip berbasis peristiwa untuk peristiwa siklus hidup agen
- [Webhooks](/automation/cron-jobs#webhooks) — pemicu peristiwa HTTP masuk
- [Agent Workspace](/concepts/agent-workspace) — tempat standing orders berada, termasuk daftar lengkap file bootstrap yang disuntikkan otomatis (AGENTS.md, SOUL.md, dll.)

89
docs/id/automation/taskflow.md Normal file
View File

@ -0,0 +1,89 @@
---
read_when:
- Anda ingin memahami bagaimana Task Flow berhubungan dengan background tasks
- Anda menemukan Task Flow atau openclaw tasks flow di catatan rilis atau dokumentasi
- Anda ingin memeriksa atau mengelola status flow yang tahan lama
summary: Lapisan orkestrasi flow Task Flow di atas background tasks
title: Task Flow
x-i18n:
generated_at: "2026-04-05T13:42:14Z"
model: gpt-5.4
provider: openai
source_hash: 172871206b839845db807d9c627015890f7733b862e276853d5dbfbe29e03883
source_path: automation/taskflow.md
workflow: 15
---
# Task Flow
Task Flow adalah substrat orkestrasi flow yang berada di atas [background tasks](/automation/tasks). Fitur ini mengelola flow multi-langkah yang tahan lama dengan status, pelacakan revisi, dan semantik sinkronisasinya sendiri, sementara task individual tetap menjadi unit kerja terlepas.
## Kapan menggunakan Task Flow
Gunakan Task Flow saat pekerjaan mencakup beberapa langkah berurutan atau bercabang dan Anda memerlukan pelacakan progres yang tahan lama di seluruh restart gateway. Untuk operasi latar belakang tunggal, [task](/automation/tasks) biasa sudah memadai.
| Skenario | Penggunaan |
| ------------------------------------ | --------------------- |
| Job latar belakang tunggal | Task biasa |
| Pipeline multi-langkah (A lalu B lalu C) | Task Flow (dikelola) |
| Mengamati task yang dibuat secara eksternal | Task Flow (dicerminkan) |
| Pengingat sekali jalan | Cron job |
## Mode sinkronisasi
### Mode dikelola
Task Flow memiliki siklus hidup end-to-end. Fitur ini membuat task sebagai langkah flow, menjalankannya hingga selesai, dan memajukan status flow secara otomatis.
Contoh: flow laporan mingguan yang (1) mengumpulkan data, (2) membuat laporan, dan (3) mengirimkannya. Task Flow membuat setiap langkah sebagai background task, menunggu hingga selesai, lalu berpindah ke langkah berikutnya.
```
Flow: weekly-report
Step 1: gather-data → task created → succeeded
Step 2: generate-report → task created → succeeded
Step 3: deliver → task created → running
```
### Mode dicerminkan
Task Flow mengamati task yang dibuat secara eksternal dan menjaga agar status flow tetap sinkron tanpa mengambil alih kepemilikan pembuatan task. Ini berguna ketika task berasal dari cron job, perintah CLI, atau sumber lain dan Anda menginginkan tampilan progresnya yang terpadu sebagai sebuah flow.
Contoh: tiga cron job independen yang bersama-sama membentuk rutinitas "operasi pagi". Flow yang dicerminkan melacak progres kolektifnya tanpa mengendalikan kapan atau bagaimana pekerjaan tersebut berjalan.
## Status tahan lama dan pelacakan revisi
Setiap flow menyimpan statusnya sendiri dan melacak revisi sehingga progres tetap bertahan setelah gateway direstart. Pelacakan revisi memungkinkan deteksi konflik saat beberapa sumber mencoba memajukan flow yang sama secara bersamaan.
## Perilaku pembatalan
`openclaw tasks flow cancel` menetapkan intent pembatalan lekat pada flow. Task aktif di dalam flow dibatalkan, dan tidak ada langkah baru yang dimulai. Intent pembatalan tetap bertahan setelah restart, sehingga flow yang dibatalkan tetap dibatalkan meskipun gateway direstart sebelum semua task turunan dihentikan.
## Perintah CLI
```bash
# List active and recent flows
openclaw tasks flow list
# Show details for a specific flow
openclaw tasks flow show <lookup>
# Cancel a running flow and its active tasks
openclaw tasks flow cancel <lookup>
```
| Perintah | Deskripsi |
| -------------------------------- | ------------------------------------------------- |
| `openclaw tasks flow list` | Menampilkan flow yang dilacak beserta status dan mode sinkronisasi |
| `openclaw tasks flow show <id>` | Periksa satu flow berdasarkan id flow atau kunci lookup |
| `openclaw tasks flow cancel <id>` | Batalkan flow yang sedang berjalan dan task aktifnya |
## Bagaimana flow berhubungan dengan task
Flow mengoordinasikan task, bukan menggantikannya. Satu flow dapat menjalankan beberapa background task selama masa berlakunya. Gunakan `openclaw tasks` untuk memeriksa catatan task individual dan `openclaw tasks flow` untuk memeriksa flow yang mengatur orkestrasi.
## Terkait
- [Background Tasks](/automation/tasks) — ledger pekerjaan terlepas yang dikoordinasikan oleh flow
- [CLI: tasks](/cli/index#tasks) — referensi perintah CLI untuk `openclaw tasks flow`
- [Ikhtisar Otomasi](/automation) — semua mekanisme otomasi secara sekilas
- [Cron Jobs](/automation/cron-jobs) — job terjadwal yang dapat menjadi masukan ke flow

317
docs/id/automation/tasks.md Normal file
View File

@ -0,0 +1,317 @@
---
read_when:
- Memeriksa pekerjaan latar belakang yang sedang berlangsung atau baru saja selesai
- Men-debug kegagalan pengiriman untuk proses agen terlepas
- Memahami bagaimana proses latar belakang berkaitan dengan sesi, cron, dan heartbeat
summary: Pelacakan tugas latar belakang untuk proses ACP, subagen, job cron terisolasi, dan operasi CLI
title: Tugas Latar Belakang
x-i18n:
generated_at: "2026-04-05T13:42:46Z"
model: gpt-5.4
provider: openai
source_hash: 6c95ccf4388d07e60a7bb68746b161793f4bb5ff2ba3d5ce9e51f2225dab2c4d
source_path: automation/tasks.md
workflow: 15
---
# Tugas Latar Belakang
> **Mencari penjadwalan?** Lihat [Otomasi & Tugas](/automation) untuk memilih mekanisme yang tepat. Halaman ini membahas **pelacakan** pekerjaan latar belakang, bukan penjadwalannya.
Tugas latar belakang melacak pekerjaan yang berjalan **di luar sesi percakapan utama Anda**:
proses ACP, pemunculan subagen, eksekusi job cron terisolasi, dan operasi yang dimulai dari CLI.
Tugas **tidak** menggantikan sesi, job cron, atau heartbeat — tugas adalah **buku besar aktivitas** yang mencatat pekerjaan terlepas apa yang terjadi, kapan terjadi, dan apakah berhasil.
<Note>
Tidak setiap proses agen membuat tugas. Giliran heartbeat dan chat interaktif normal tidak membuat tugas. Semua eksekusi cron, pemunculan ACP, pemunculan subagen, dan perintah agen CLI membuat tugas.
</Note>
## Ringkasan
- Tugas adalah **catatan**, bukan penjadwal — cron dan heartbeat menentukan _kapan_ pekerjaan berjalan, tugas melacak _apa yang terjadi_.
- ACP, subagen, semua job cron, dan operasi CLI membuat tugas. Giliran heartbeat tidak membuat tugas.
- Setiap tugas berpindah melalui `queued → running → terminal` (`succeeded`, `failed`, `timed_out`, `cancelled`, atau `lost`).
- Tugas cron tetap aktif selama runtime cron masih memiliki job tersebut; tugas CLI berbasis chat tetap aktif hanya selama konteks proses pemiliknya masih aktif.
- Penyelesaian didorong oleh push: pekerjaan terlepas dapat memberi tahu secara langsung atau membangunkan sesi/heartbeat peminta saat selesai, jadi loop polling status biasanya bukan pola yang tepat.
- Proses cron terisolasi dan penyelesaian subagen sebisa mungkin membersihkan tab/proses browser yang dilacak untuk sesi anaknya sebelum pembukuan pembersihan akhir.
- Pengiriman cron terisolasi menekan balasan perantara induk yang sudah usang saat pekerjaan subagen turunan masih dikuras, dan memprioritaskan output akhir turunan jika output itu tiba sebelum pengiriman.
- Notifikasi penyelesaian dikirim langsung ke channel atau diantrikan untuk heartbeat berikutnya.
- `openclaw tasks list` menampilkan semua tugas; `openclaw tasks audit` menampilkan masalah.
- Rekaman terminal disimpan selama 7 hari, lalu dipangkas secara otomatis.
## Mulai cepat
```bash
# Daftar semua tugas (terbaru terlebih dahulu)
openclaw tasks list
# Filter berdasarkan runtime atau status
openclaw tasks list --runtime acp
openclaw tasks list --status running
# Tampilkan detail untuk tugas tertentu (berdasarkan ID, ID proses, atau kunci sesi)
openclaw tasks show <lookup>
# Batalkan tugas yang sedang berjalan (menghentikan sesi anak)
openclaw tasks cancel <lookup>
# Ubah kebijakan notifikasi untuk suatu tugas
openclaw tasks notify <lookup> state_changes
# Jalankan audit kesehatan
openclaw tasks audit
# Pratinjau atau terapkan pemeliharaan
openclaw tasks maintenance
openclaw tasks maintenance --apply
# Periksa status Task Flow
openclaw tasks flow list
openclaw tasks flow show <lookup>
openclaw tasks flow cancel <lookup>
```
## Apa yang membuat tugas
| Sumber | Jenis runtime | Kapan rekaman tugas dibuat | Kebijakan notifikasi default |
| ---------------------- | ------------- | ---------------------------------------------------- | ---------------------------- |
| Proses latar belakang ACP | `acp` | Memunculkan sesi anak ACP | `done_only` |
| Orkestrasi subagen | `subagent` | Memunculkan subagen melalui `sessions_spawn` | `done_only` |
| Job cron (semua jenis) | `cron` | Setiap eksekusi cron (sesi utama dan terisolasi) | `silent` |
| Operasi CLI | `cli` | Perintah `openclaw agent` yang berjalan melalui gateway | `silent` |
Tugas cron sesi utama menggunakan kebijakan notifikasi `silent` secara default — tugas ini membuat rekaman untuk pelacakan tetapi tidak menghasilkan notifikasi. Tugas cron terisolasi juga default ke `silent` tetapi lebih terlihat karena berjalan dalam sesinya sendiri.
**Yang tidak membuat tugas:**
- Giliran heartbeat — sesi utama; lihat [Heartbeat](/gateway/heartbeat)
- Giliran chat interaktif normal
- Respons `/command` langsung
## Siklus hidup tugas
```mermaid
stateDiagram-v2
[*] --> queued
queued --> running : agent starts
running --> succeeded : completes ok
running --> failed : error
running --> timed_out : timeout exceeded
running --> cancelled : operator cancels
queued --> lost : session gone > 5 min
running --> lost : session gone > 5 min
```
| Status | Artinya |
| ----------- | ---------------------------------------------------------------------------- |
| `queued` | Dibuat, menunggu agen memulai |
| `running` | Giliran agen sedang dieksekusi secara aktif |
| `succeeded` | Selesai dengan sukses |
| `failed` | Selesai dengan error |
| `timed_out` | Melebihi batas waktu yang dikonfigurasi |
| `cancelled` | Dihentikan oleh operator melalui `openclaw tasks cancel` |
| `lost` | Runtime kehilangan status dukungan yang otoritatif setelah masa tenggang 5 menit |
Transisi terjadi secara otomatis — saat proses agen terkait berakhir, status tugas diperbarui agar sesuai.
`lost` bergantung pada runtime:
- Tugas ACP: metadata sesi anak ACP pendukung menghilang.
- Tugas subagen: sesi anak pendukung menghilang dari penyimpanan agen target.
- Tugas cron: runtime cron tidak lagi melacak job tersebut sebagai aktif.
- Tugas CLI: tugas sesi anak terisolasi menggunakan sesi anak; tugas CLI berbasis chat menggunakan konteks proses langsung, sehingga baris sesi channel/grup/langsung yang tersisa tidak membuatnya tetap aktif.
## Pengiriman dan notifikasi
Saat sebuah tugas mencapai status terminal, OpenClaw memberi tahu Anda. Ada dua jalur pengiriman:
**Pengiriman langsung** — jika tugas memiliki target channel (`requesterOrigin`), pesan penyelesaian langsung dikirim ke channel tersebut (Telegram, Discord, Slack, dll.). Untuk penyelesaian subagen, OpenClaw juga mempertahankan perutean thread/topik yang terikat saat tersedia dan dapat mengisi `to` / akun yang hilang dari rute tersimpan sesi peminta (`lastChannel` / `lastTo` / `lastAccountId`) sebelum menyerah pada pengiriman langsung.
**Pengiriman melalui antrean sesi** — jika pengiriman langsung gagal atau tidak ada origin yang ditetapkan, pembaruan diantrikan sebagai peristiwa sistem dalam sesi peminta dan akan muncul pada heartbeat berikutnya.
<Tip>
Penyelesaian tugas memicu kebangkitan heartbeat segera sehingga Anda dapat melihat hasilnya dengan cepat — Anda tidak perlu menunggu tick heartbeat terjadwal berikutnya.
</Tip>
Artinya, alur kerja yang umum bersifat berbasis push: mulai pekerjaan terlepas sekali, lalu biarkan runtime membangunkan atau memberi tahu Anda saat selesai. Poll status tugas hanya saat Anda memerlukan debugging, intervensi, atau audit eksplisit.
### Kebijakan notifikasi
Kendalikan seberapa banyak Anda menerima kabar tentang setiap tugas:
| Kebijakan | Yang dikirim |
| ---------------------- | ---------------------------------------------------------------------- |
| `done_only` (default) | Hanya status terminal (`succeeded`, `failed`, dll.) — **ini adalah default** |
| `state_changes` | Setiap transisi status dan pembaruan progres |
| `silent` | Tidak ada sama sekali |
Ubah kebijakan saat tugas sedang berjalan:
```bash
openclaw tasks notify <lookup> state_changes
```
## Referensi CLI
### `tasks list`
```bash
openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--json]
```
Kolom output: ID Tugas, Jenis, Status, Pengiriman, ID Proses, Sesi Anak, Ringkasan.
### `tasks show`
```bash
openclaw tasks show <lookup>
```
Token lookup menerima ID tugas, ID proses, atau kunci sesi. Menampilkan rekaman lengkap termasuk waktu, status pengiriman, error, dan ringkasan terminal.
### `tasks cancel`
```bash
openclaw tasks cancel <lookup>
```
Untuk tugas ACP dan subagen, ini menghentikan sesi anak. Status bertransisi ke `cancelled` dan notifikasi pengiriman dikirim.
### `tasks notify`
```bash
openclaw tasks notify <lookup> <done_only|state_changes|silent>
```
### `tasks audit`
```bash
openclaw tasks audit [--json]
```
Menampilkan masalah operasional. Temuan juga muncul di `openclaw status` saat masalah terdeteksi.
| Temuan | Tingkat keparahan | Pemicu |
| ------------------------- | ----------------- | ----------------------------------------------------- |
| `stale_queued` | peringatan | Berada di antrean lebih dari 10 menit |
| `stale_running` | error | Berjalan lebih dari 30 menit |
| `lost` | error | Kepemilikan tugas berbasis runtime menghilang |
| `delivery_failed` | peringatan | Pengiriman gagal dan kebijakan notifikasi bukan `silent` |
| `missing_cleanup` | peringatan | Tugas terminal tanpa stempel waktu pembersihan |
| `inconsistent_timestamps` | peringatan | Pelanggaran linimasa (misalnya berakhir sebelum dimulai) |
### `tasks maintenance`
```bash
openclaw tasks maintenance [--json]
openclaw tasks maintenance --apply [--json]
```
Gunakan ini untuk mempratinjau atau menerapkan rekonsiliasi, penandaan pembersihan, dan pemangkasan untuk tugas dan status Task Flow.
Rekonsiliasi bergantung pada runtime:
- Tugas ACP/subagen memeriksa sesi anak pendukungnya.
- Tugas cron memeriksa apakah runtime cron masih memiliki job tersebut.
- Tugas CLI berbasis chat memeriksa konteks proses langsung milik pemiliknya, bukan hanya baris sesi chat.
Pembersihan penyelesaian juga bergantung pada runtime:
- Penyelesaian subagen sebisa mungkin menutup tab/proses browser yang dilacak untuk sesi anak sebelum pembersihan pengumuman dilanjutkan.
- Penyelesaian cron terisolasi sebisa mungkin menutup tab/proses browser yang dilacak untuk sesi cron sebelum proses sepenuhnya dibongkar.
- Pengiriman cron terisolasi menunggu tindak lanjut subagen turunan bila perlu dan menekan teks pengakuan induk yang sudah usang alih-alih mengumumkannya.
- Pengiriman penyelesaian subagen memprioritaskan teks asisten terbaru yang terlihat; jika kosong, pengiriman akan menggunakan cadangan berupa teks tool/toolResult terbaru yang telah disanitasi, dan proses panggilan tool yang hanya timeout dapat diringkas menjadi ringkasan progres parsial yang singkat.
- Kegagalan pembersihan tidak menutupi hasil tugas yang sebenarnya.
### `tasks flow list|show|cancel`
```bash
openclaw tasks flow list [--status <status>] [--json]
openclaw tasks flow show <lookup> [--json]
openclaw tasks flow cancel <lookup>
```
Gunakan ini saat Task Flow pengorkestrasi adalah hal yang Anda pedulikan, bukan satu rekaman tugas latar belakang individual.
## Papan tugas chat (`/tasks`)
Gunakan `/tasks` di sesi chat mana pun untuk melihat tugas latar belakang yang ditautkan ke sesi tersebut. Papan ini menampilkan tugas aktif dan yang baru saja selesai beserta runtime, status, waktu, dan detail progres atau error.
Saat sesi saat ini tidak memiliki tugas tertaut yang terlihat, `/tasks` akan menggunakan cadangan berupa jumlah tugas lokal agen sehingga Anda tetap mendapatkan gambaran umum tanpa membocorkan detail sesi lain.
Untuk buku besar operator lengkap, gunakan CLI: `openclaw tasks list`.
## Integrasi status (tekanan tugas)
`openclaw status` menyertakan ringkasan tugas sekilas:
```
Tasks: 3 queued · 2 running · 1 issues
```
Ringkasan ini melaporkan:
- **active** — jumlah `queued` + `running`
- **failures** — jumlah `failed` + `timed_out` + `lost`
- **byRuntime** — perincian berdasarkan `acp`, `subagent`, `cron`, `cli`
Baik `/status` maupun tool `session_status` menggunakan snapshot tugas yang sadar pembersihan: tugas aktif diprioritaskan, baris selesai yang basi disembunyikan, dan kegagalan terbaru hanya muncul saat tidak ada pekerjaan aktif yang tersisa. Ini menjaga kartu status tetap fokus pada hal yang penting saat ini.
## Penyimpanan dan pemeliharaan
### Tempat tugas disimpan
Rekaman tugas disimpan secara persisten di SQLite pada:
```
$OPENCLAW_STATE_DIR/tasks/runs.sqlite
```
Registri dimuat ke memori saat gateway dimulai dan menyinkronkan penulisan ke SQLite untuk ketahanan di seluruh restart.
### Pemeliharaan otomatis
Sebuah sweeper berjalan setiap **60 detik** dan menangani tiga hal:
1. **Rekonsiliasi** — memeriksa apakah tugas aktif masih memiliki dukungan runtime otoritatif. Tugas ACP/subagen menggunakan status sesi anak, tugas cron menggunakan kepemilikan job aktif, dan tugas CLI berbasis chat menggunakan konteks proses milik pemiliknya. Jika status dukungan itu hilang selama lebih dari 5 menit, tugas ditandai sebagai `lost`.
2. **Penandaan pembersihan** — menetapkan stempel waktu `cleanupAfter` pada tugas terminal (`endedAt + 7 days`).
3. **Pemangkasan** — menghapus rekaman yang telah melewati tanggal `cleanupAfter`.
**Retensi**: rekaman tugas terminal disimpan selama **7 hari**, lalu dipangkas secara otomatis. Tidak perlu konfigurasi.
## Bagaimana tugas terkait dengan sistem lain
### Tugas dan Task Flow
[Task Flow](/automation/taskflow) adalah lapisan orkestrasi alur di atas tugas latar belakang. Satu alur dapat mengoordinasikan beberapa tugas selama masa hidupnya menggunakan mode sinkronisasi terkelola atau tercermin. Gunakan `openclaw tasks` untuk memeriksa rekaman tugas individual dan `openclaw tasks flow` untuk memeriksa alur pengorkestrasi.
Lihat [Task Flow](/automation/taskflow) untuk detailnya.
### Tugas dan cron
Sebuah **definisi** job cron disimpan di `~/.openclaw/cron/jobs.json`. **Setiap** eksekusi cron membuat rekaman tugas — baik sesi utama maupun terisolasi. Tugas cron sesi utama default ke kebijakan notifikasi `silent` sehingga tetap terlacak tanpa menghasilkan notifikasi.
Lihat [Job Cron](/automation/cron-jobs).
### Tugas dan heartbeat
Proses heartbeat adalah giliran sesi utama — proses ini tidak membuat rekaman tugas. Saat sebuah tugas selesai, tugas itu dapat memicu kebangkitan heartbeat agar Anda segera melihat hasilnya.
Lihat [Heartbeat](/gateway/heartbeat).
### Tugas dan sesi
Sebuah tugas dapat merujuk ke `childSessionKey` (tempat pekerjaan berjalan) dan `requesterSessionKey` (siapa yang memulainya). Sesi adalah konteks percakapan; tugas adalah pelacakan aktivitas di atas konteks itu.
### Tugas dan proses agen
`runId` sebuah tugas terhubung ke proses agen yang melakukan pekerjaan. Peristiwa siklus hidup agen (mulai, selesai, error) secara otomatis memperbarui status tugas — Anda tidak perlu mengelola siklus hidupnya secara manual.
## Terkait
- [Otomasi & Tugas](/automation) — semua mekanisme otomasi secara sekilas
- [Task Flow](/automation/taskflow) — orkestrasi alur di atas tugas
- [Tugas Terjadwal](/automation/cron-jobs) — penjadwalan pekerjaan latar belakang
- [Heartbeat](/gateway/heartbeat) — giliran sesi utama berkala
- [CLI: Tasks](/cli/index#tasks) — referensi perintah CLI

15
docs/id/automation/troubleshooting.md Normal file
View File

@ -0,0 +1,15 @@
---
summary: Alihkan ke /automation/cron-jobs
title: Pemecahan Masalah Otomasi
x-i18n:
generated_at: "2026-04-05T13:42:09Z"
model: gpt-5.4
provider: openai
source_hash: 6621342754fb56234b89e71167f73bad6c070273ff0b8d12dbb20854e32e7980
source_path: automation/troubleshooting.md
workflow: 15
---
# Pemecahan Masalah Otomasi
Halaman ini dipindahkan ke [Tugas Terjadwal](/automation/cron-jobs#troubleshooting). Lihat [Tugas Terjadwal](/automation/cron-jobs#troubleshooting) untuk dokumentasi pemecahan masalah.

15
docs/id/automation/webhook.md Normal file
View File

@ -0,0 +1,15 @@
---
summary: Alihkan ke /automation/cron-jobs
title: Webhooks
x-i18n:
generated_at: "2026-04-05T13:42:11Z"
model: gpt-5.4
provider: openai
source_hash: 7511f6bc28e7f13ee1d9313bb5551825afb5706019068079603a44668c4dda34
source_path: automation/webhook.md
workflow: 15
---
# Webhooks
Halaman ini dipindahkan ke [Tugas Terjadwal](/automation/cron-jobs#webhooks). Lihat [Tugas Terjadwal](/automation/cron-jobs#webhooks) untuk dokumentasi webhook.

110
docs/id/brave-search.md Normal file
View File

@ -0,0 +1,110 @@
---
read_when:
- Anda ingin menggunakan Brave Search untuk web_search
- Anda memerlukan BRAVE_API_KEY atau detail paket
summary: Penyiapan Brave Search API untuk web_search
title: Brave Search (jalur lama)
x-i18n:
generated_at: "2026-04-05T13:42:25Z"
model: gpt-5.4
provider: openai
source_hash: 7788e4cee7dc460819e55095c87df8cea29ba3a8bd3cef4c0e98ac601b45b651
source_path: brave-search.md
workflow: 15
---
# Brave Search API
OpenClaw mendukung Brave Search API sebagai penyedia `web_search`.
## Dapatkan kunci API
1. Buat akun Brave Search API di [https://brave.com/search/api/](https://brave.com/search/api/)
2. Di dasbor, pilih paket **Search** dan buat kunci API.
3. Simpan kunci tersebut di konfigurasi atau tetapkan `BRAVE_API_KEY` di environment Gateway.
## Contoh konfigurasi
```json5
{
plugins: {
entries: {
brave: {
config: {
webSearch: {
apiKey: "BRAVE_API_KEY_HERE",
mode: "web", // or "llm-context"
},
},
},
},
},
tools: {
web: {
search: {
provider: "brave",
maxResults: 5,
timeoutSeconds: 30,
},
},
},
}
```
Pengaturan pencarian Brave yang khusus penyedia kini berada di bawah `plugins.entries.brave.config.webSearch.*`.
`tools.web.search.apiKey` lama masih dimuat melalui shim kompatibilitas, tetapi itu bukan lagi jalur konfigurasi kanonis.
`webSearch.mode` mengontrol transport Brave:
- `web` (default): pencarian web Brave normal dengan judul, URL, dan cuplikan
- `llm-context`: Brave LLM Context API dengan potongan teks dan sumber yang sudah diekstrak sebelumnya untuk grounding
## Parameter alat
| Parameter | Deskripsi |
| ------------- | ------------------------------------------------------------------- |
| `query` | Kueri pencarian (wajib) |
| `count` | Jumlah hasil yang dikembalikan (1-10, default: 5) |
| `country` | Kode negara ISO 2 huruf (misalnya, "US", "DE") |
| `language` | Kode bahasa ISO 639-1 untuk hasil pencarian (misalnya, "en", "de", "fr") |
| `search_lang` | Kode bahasa pencarian Brave (misalnya, `en`, `en-gb`, `zh-hans`) |
| `ui_lang` | Kode bahasa ISO untuk elemen UI |
| `freshness` | Filter waktu: `day` (24 jam), `week`, `month`, atau `year` |
| `date_after` | Hanya hasil yang dipublikasikan setelah tanggal ini (YYYY-MM-DD) |
| `date_before` | Hanya hasil yang dipublikasikan sebelum tanggal ini (YYYY-MM-DD) |
**Contoh:**
```javascript
// Country and language-specific search
await web_search({
query: "renewable energy",
country: "DE",
language: "de",
});
// Recent results (past week)
await web_search({
query: "AI news",
freshness: "week",
});
// Date range search
await web_search({
query: "AI developments",
date_after: "2024-01-01",
date_before: "2024-06-30",
});
```
## Catatan
- OpenClaw menggunakan paket Brave **Search**. Jika Anda memiliki langganan lama (misalnya paket Free asli dengan 2.000 kueri/bulan), langganan itu tetap valid tetapi tidak mencakup fitur yang lebih baru seperti LLM Context atau batas laju yang lebih tinggi.
- Setiap paket Brave menyertakan **\$5/bulan dalam kredit gratis** (diperbarui). Paket Search berbiaya \$5 per 1.000 permintaan, jadi kredit tersebut mencakup 1.000 kueri/bulan. Tetapkan batas penggunaan Anda di dasbor Brave untuk menghindari biaya tak terduga. Lihat [portal Brave API](https://brave.com/search/api/) untuk paket saat ini.
- Paket Search mencakup endpoint LLM Context dan hak inferensi AI. Menyimpan hasil untuk melatih atau menyetel model memerlukan paket dengan hak penyimpanan eksplisit. Lihat Brave [Ketentuan Layanan](https://api-dashboard.search.brave.com/terms-of-service).
- Mode `llm-context` mengembalikan entri sumber yang digrounded alih-alih bentuk cuplikan pencarian web normal.
- Mode `llm-context` tidak mendukung `ui_lang`, `freshness`, `date_after`, atau `date_before`.
- `ui_lang` harus menyertakan subtag wilayah seperti `en-US`.
- Hasil di-cache selama 15 menit secara default (dapat dikonfigurasi melalui `cacheTtlMinutes`).
Lihat [Alat web](/tools/web) untuk konfigurasi lengkap `web_search`.

442
docs/id/channels/bluebubbles.md Normal file
View File

@ -0,0 +1,442 @@
---
read_when:
- Menyiapkan channel BlueBubbles
- Memecahkan masalah pairing webhook
- Mengonfigurasi iMessage di macOS
summary: iMessage melalui server macOS BlueBubbles (REST kirim/terima, mengetik, reaksi, pairing, tindakan lanjutan).
title: BlueBubbles
x-i18n:
generated_at: "2026-04-05T13:43:04Z"
model: gpt-5.4
provider: openai
source_hash: ed8e59a165bdfb8fd794ee2ad6e4dacd44aa02d512312c5f2fd7d15f863380bb
source_path: channels/bluebubbles.md
workflow: 15
---
# BlueBubbles (REST macOS)
Status: plugin bawaan yang berkomunikasi dengan server macOS BlueBubbles melalui HTTP. **Direkomendasikan untuk integrasi iMessage** karena API-nya lebih kaya dan penyiapannya lebih mudah dibandingkan channel imsg lama.
## Plugin bawaan
Rilis OpenClaw saat ini menyertakan BlueBubbles, jadi build paket normal tidak
memerlukan langkah `openclaw plugins install` terpisah.
## Gambaran umum
- Berjalan di macOS melalui aplikasi helper BlueBubbles ([bluebubbles.app](https://bluebubbles.app)).
- Direkomendasikan/teruji: macOS Sequoia (15). macOS Tahoe (26) berfungsi; edit saat ini rusak di Tahoe, dan pembaruan ikon grup dapat dilaporkan berhasil tetapi tidak tersinkron.
- OpenClaw berkomunikasi dengannya melalui API REST-nya (`GET /api/v1/ping`, `POST /message/text`, `POST /chat/:id/*`).
- Pesan masuk tiba melalui webhook; balasan keluar, indikator mengetik, tanda baca, dan tapback adalah panggilan REST.
- Lampiran dan stiker diingest sebagai media masuk (dan ditampilkan ke agen jika memungkinkan).
- Pairing/allowlist berfungsi sama seperti channel lain (`/channels/pairing` dan seterusnya) dengan `channels.bluebubbles.allowFrom` + kode pairing.
- Reaksi ditampilkan sebagai event sistem seperti Slack/Telegram sehingga agen dapat "menyebutkannya" sebelum membalas.
- Fitur lanjutan: edit, batalkan kirim, utas balasan, efek pesan, manajemen grup.
## Mulai cepat
1. Instal server BlueBubbles di Mac Anda (ikuti petunjuk di [bluebubbles.app/install](https://bluebubbles.app/install)).
2. Di konfigurasi BlueBubbles, aktifkan web API dan tetapkan kata sandi.
3. Jalankan `openclaw onboard` dan pilih BlueBubbles, atau konfigurasi secara manual:
```json5
{
channels: {
bluebubbles: {
enabled: true,
serverUrl: "http://192.168.1.100:1234",
password: "example-password",
webhookPath: "/bluebubbles-webhook",
},
},
}
```
4. Arahkan webhook BlueBubbles ke gateway Anda (contoh: `https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`).
5. Mulai gateway; gateway akan mendaftarkan handler webhook dan memulai pairing.
Catatan keamanan:
- Selalu tetapkan kata sandi webhook.
- Autentikasi webhook selalu wajib. OpenClaw menolak permintaan webhook BlueBubbles kecuali permintaan tersebut menyertakan password/guid yang cocok dengan `channels.bluebubbles.password` (misalnya `?password=<password>` atau `x-password`), terlepas dari topologi loopback/proxy.
- Autentikasi kata sandi diperiksa sebelum membaca/mengurai body webhook secara penuh.
## Menjaga Messages.app tetap aktif (VM / penyiapan headless)
Beberapa penyiapan VM macOS / selalu aktif dapat membuat Messages.app menjadi “idle” (event masuk berhenti sampai aplikasi dibuka/dijadikan foreground). Solusi sederhananya adalah **menyentuh Messages setiap 5 menit** menggunakan AppleScript + LaunchAgent.
### 1) Simpan AppleScript
Simpan sebagai:
- `~/Scripts/poke-messages.scpt`
Contoh skrip (non-interaktif; tidak mencuri fokus):
```applescript
try
tell application "Messages"
if not running then
launch
end if
-- Touch the scripting interface to keep the process responsive.
set _chatCount to (count of chats)
end tell
on error
-- Ignore transient failures (first-run prompts, locked session, etc).
end try
```
### 2) Instal LaunchAgent
Simpan sebagai:
- `~/Library/LaunchAgents/com.user.poke-messages.plist`
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.user.poke-messages</string>
<key>ProgramArguments</key>
<array>
<string>/bin/bash</string>
<string>-lc</string>
<string>/usr/bin/osascript &quot;$HOME/Scripts/poke-messages.scpt&quot;</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>StartInterval</key>
<integer>300</integer>
<key>StandardOutPath</key>
<string>/tmp/poke-messages.log</string>
<key>StandardErrorPath</key>
<string>/tmp/poke-messages.err</string>
</dict>
</plist>
```
Catatan:
- Ini berjalan **setiap 300 detik** dan **saat login**.
- Proses pertama kali berjalan dapat memicu prompt macOS **Automation** (`osascript` → Messages). Setujui prompt tersebut di sesi pengguna yang sama yang menjalankan LaunchAgent.
Muat:
```bash
launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true
launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist
```
## Onboarding
BlueBubbles tersedia dalam onboarding interaktif:
```
openclaw onboard
```
Wizard akan meminta:
- **URL Server** (wajib): alamat server BlueBubbles (misalnya, `http://192.168.1.100:1234`)
- **Password** (wajib): kata sandi API dari pengaturan BlueBubbles Server
- **Path webhook** (opsional): default ke `/bluebubbles-webhook`
- **Kebijakan DM**: pairing, allowlist, open, atau disabled
- **Daftar izinkan**: nomor telepon, email, atau target chat
Anda juga dapat menambahkan BlueBubbles melalui CLI:
```
openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password <password>
```
## Kontrol akses (DM + grup)
DM:
- Default: `channels.bluebubbles.dmPolicy = "pairing"`.
- Pengirim yang tidak dikenal menerima kode pairing; pesan diabaikan sampai disetujui (kode kedaluwarsa setelah 1 jam).
- Setujui melalui:
- `openclaw pairing list bluebubbles`
- `openclaw pairing approve bluebubbles <CODE>`
- Pairing adalah pertukaran token default. Detail: [Pairing](/channels/pairing)
Grup:
- `channels.bluebubbles.groupPolicy = open | allowlist | disabled` (default: `allowlist`).
- `channels.bluebubbles.groupAllowFrom` mengontrol siapa yang dapat memicu di grup ketika `allowlist` ditetapkan.
### Pengayaan nama kontak (macOS, opsional)
Webhook grup BlueBubbles sering kali hanya menyertakan alamat peserta mentah. Jika Anda ingin konteks `GroupMembers` menampilkan nama kontak lokal sebagai gantinya, Anda dapat memilih pengayaan Contacts lokal di macOS:
- `channels.bluebubbles.enrichGroupParticipantsFromContacts = true` mengaktifkan lookup. Default: `false`.
- Lookup hanya dijalankan setelah akses grup, otorisasi perintah, dan penggatingan mention mengizinkan pesan lolos.
- Hanya peserta telepon tanpa nama yang diperkaya.
- Nomor telepon mentah tetap menjadi fallback saat tidak ditemukan kecocokan lokal.
```json5
{
channels: {
bluebubbles: {
enrichGroupParticipantsFromContacts: true,
},
},
}
```
### Penggatingan mention (grup)
BlueBubbles mendukung penggatingan mention untuk chat grup, selaras dengan perilaku iMessage/WhatsApp:
- Menggunakan `agents.list[].groupChat.mentionPatterns` (atau `messages.groupChat.mentionPatterns`) untuk mendeteksi mention.
- Ketika `requireMention` diaktifkan untuk sebuah grup, agen hanya merespons saat disebut.
- Perintah kontrol dari pengirim yang berwenang melewati penggatingan mention.
Konfigurasi per grup:
```json5
{
channels: {
bluebubbles: {
groupPolicy: "allowlist",
groupAllowFrom: ["+15555550123"],
groups: {
"*": { requireMention: true }, // default untuk semua grup
"iMessage;-;chat123": { requireMention: false }, // override untuk grup tertentu
},
},
},
}
```
### Penggatingan perintah
- Perintah kontrol (misalnya, `/config`, `/model`) memerlukan otorisasi.
- Menggunakan `allowFrom` dan `groupAllowFrom` untuk menentukan otorisasi perintah.
- Pengirim yang berwenang dapat menjalankan perintah kontrol bahkan tanpa mention di grup.
## Binding percakapan ACP
Chat BlueBubbles dapat diubah menjadi workspace ACP yang persisten tanpa mengubah lapisan transport.
Alur operator cepat:
- Jalankan `/acp spawn codex --bind here` di dalam DM atau chat grup yang diizinkan.
- Pesan berikutnya dalam percakapan BlueBubbles yang sama akan dirutekan ke sesi ACP yang telah di-spawn.
- `/new` dan `/reset` mereset sesi ACP terikat yang sama di tempat.
- `/acp close` menutup sesi ACP dan menghapus binding.
Binding persisten yang dikonfigurasi juga didukung melalui entri `bindings[]` tingkat atas dengan `type: "acp"` dan `match.channel: "bluebubbles"`.
`match.peer.id` dapat menggunakan bentuk target BlueBubbles yang didukung:
- handle DM yang dinormalisasi seperti `+15555550123` atau `user@example.com`
- `chat_id:<id>`
- `chat_guid:<guid>`
- `chat_identifier:<identifier>`
Untuk binding grup yang stabil, utamakan `chat_id:*` atau `chat_identifier:*`.
Contoh:
```json5
{
agents: {
list: [
{
id: "codex",
runtime: {
type: "acp",
acp: { agent: "codex", backend: "acpx", mode: "persistent" },
},
},
],
},
bindings: [
{
type: "acp",
agentId: "codex",
match: {
channel: "bluebubbles",
accountId: "default",
peer: { kind: "dm", id: "+15555550123" },
},
acp: { label: "codex-imessage" },
},
],
}
```
Lihat [Agen ACP](/tools/acp-agents) untuk perilaku binding ACP bersama.
## Mengetik + tanda baca
- **Indikator mengetik**: Dikirim secara otomatis sebelum dan selama pembuatan respons.
- **Tanda baca**: Dikontrol oleh `channels.bluebubbles.sendReadReceipts` (default: `true`).
- **Indikator mengetik**: OpenClaw mengirim event mulai mengetik; BlueBubbles menghapus status mengetik secara otomatis saat mengirim atau saat timeout (penghentian manual via DELETE tidak andal).
```json5
{
channels: {
bluebubbles: {
sendReadReceipts: false, // nonaktifkan tanda baca
},
},
}
```
## Tindakan lanjutan
BlueBubbles mendukung tindakan pesan lanjutan saat diaktifkan di konfigurasi:
```json5
{
channels: {
bluebubbles: {
actions: {
reactions: true, // tapback (default: true)
edit: true, // edit pesan terkirim (macOS 13+, rusak di macOS 26 Tahoe)
unsend: true, // batalkan kirim pesan (macOS 13+)
reply: true, // utas balasan berdasarkan GUID pesan
sendWithEffect: true, // efek pesan (slam, loud, dll.)
renameGroup: true, // ganti nama chat grup
setGroupIcon: true, // setel ikon/foto chat grup (tidak stabil di macOS 26 Tahoe)
addParticipant: true, // tambahkan peserta ke grup
removeParticipant: true, // hapus peserta dari grup
leaveGroup: true, // keluar dari chat grup
sendAttachment: true, // kirim lampiran/media
},
},
},
}
```
Tindakan yang tersedia:
- **react**: Tambahkan/hapus reaksi tapback (`messageId`, `emoji`, `remove`)
- **edit**: Edit pesan yang telah dikirim (`messageId`, `text`)
- **unsend**: Batalkan kirim pesan (`messageId`)
- **reply**: Balas pesan tertentu (`messageId`, `text`, `to`)
- **sendWithEffect**: Kirim dengan efek iMessage (`text`, `to`, `effectId`)
- **renameGroup**: Ganti nama chat grup (`chatGuid`, `displayName`)
- **setGroupIcon**: Setel ikon/foto chat grup (`chatGuid`, `media`) — tidak stabil di macOS 26 Tahoe (API mungkin mengembalikan sukses tetapi ikon tidak tersinkron).
- **addParticipant**: Tambahkan seseorang ke grup (`chatGuid`, `address`)
- **removeParticipant**: Hapus seseorang dari grup (`chatGuid`, `address`)
- **leaveGroup**: Keluar dari chat grup (`chatGuid`)
- **upload-file**: Kirim media/file (`to`, `buffer`, `filename`, `asVoice`)
- Memo suara: setel `asVoice: true` dengan audio **MP3** atau **CAF** untuk mengirim sebagai pesan suara iMessage. BlueBubbles mengonversi MP3 → CAF saat mengirim memo suara.
- Alias lama: `sendAttachment` masih berfungsi, tetapi `upload-file` adalah nama tindakan kanonis.
### ID pesan (singkat vs penuh)
OpenClaw dapat menampilkan ID pesan _singkat_ (misalnya, `1`, `2`) untuk menghemat token.
- `MessageSid` / `ReplyToId` dapat berupa ID singkat.
- `MessageSidFull` / `ReplyToIdFull` berisi ID penuh provider.
- ID singkat berada di memori; ID ini dapat kedaluwarsa saat restart atau pengusiran cache.
- Tindakan menerima `messageId` singkat atau penuh, tetapi ID singkat akan menghasilkan error jika sudah tidak tersedia.
Gunakan ID penuh untuk otomasi dan penyimpanan yang persisten:
- Template: `{{MessageSidFull}}`, `{{ReplyToIdFull}}`
- Konteks: `MessageSidFull` / `ReplyToIdFull` di payload masuk
Lihat [Konfigurasi](/gateway/configuration) untuk variabel template.
## Streaming blok
Kontrol apakah respons dikirim sebagai satu pesan atau di-stream dalam blok:
```json5
{
channels: {
bluebubbles: {
blockStreaming: true, // aktifkan streaming blok (nonaktif secara default)
},
},
}
```
## Media + batasan
- Lampiran masuk diunduh dan disimpan di cache media.
- Batas media melalui `channels.bluebubbles.mediaMaxMb` untuk media masuk dan keluar (default: 8 MB).
- Teks keluar dipecah menjadi `channels.bluebubbles.textChunkLimit` (default: 4000 karakter).
## Referensi konfigurasi
Konfigurasi lengkap: [Konfigurasi](/gateway/configuration)
Opsi provider:
- `channels.bluebubbles.enabled`: Aktifkan/nonaktifkan channel.
- `channels.bluebubbles.serverUrl`: URL dasar API REST BlueBubbles.
- `channels.bluebubbles.password`: Kata sandi API.
- `channels.bluebubbles.webhookPath`: Path endpoint webhook (default: `/bluebubbles-webhook`).
- `channels.bluebubbles.dmPolicy`: `pairing | allowlist | open | disabled` (default: `pairing`).
- `channels.bluebubbles.allowFrom`: allowlist DM (handle, email, nomor E.164, `chat_id:*`, `chat_guid:*`).
- `channels.bluebubbles.groupPolicy`: `open | allowlist | disabled` (default: `allowlist`).
- `channels.bluebubbles.groupAllowFrom`: allowlist pengirim grup.
- `channels.bluebubbles.enrichGroupParticipantsFromContacts`: Di macOS, secara opsional memperkaya peserta grup tanpa nama dari Contacts lokal setelah gating lolos. Default: `false`.
- `channels.bluebubbles.groups`: Konfigurasi per grup (`requireMention`, dll.).
- `channels.bluebubbles.sendReadReceipts`: Kirim tanda baca (default: `true`).
- `channels.bluebubbles.blockStreaming`: Aktifkan streaming blok (default: `false`; diperlukan untuk balasan streaming).
- `channels.bluebubbles.textChunkLimit`: Ukuran potongan keluar dalam karakter (default: 4000).
- `channels.bluebubbles.chunkMode`: `length` (default) membagi hanya saat melebihi `textChunkLimit`; `newline` membagi pada baris kosong (batas paragraf) sebelum pemotongan berdasarkan panjang.
- `channels.bluebubbles.mediaMaxMb`: Batas media masuk/keluar dalam MB (default: 8).
- `channels.bluebubbles.mediaLocalRoots`: allowlist eksplisit direktori lokal absolut yang diizinkan untuk path media lokal keluar. Pengiriman path lokal ditolak secara default kecuali ini dikonfigurasi. Override per akun: `channels.bluebubbles.accounts.<accountId>.mediaLocalRoots`.
- `channels.bluebubbles.historyLimit`: Maks pesan grup untuk konteks (0 menonaktifkan).
- `channels.bluebubbles.dmHistoryLimit`: Batas riwayat DM.
- `channels.bluebubbles.actions`: Aktifkan/nonaktifkan tindakan tertentu.
- `channels.bluebubbles.accounts`: Konfigurasi multi-akun.
Opsi global terkait:
- `agents.list[].groupChat.mentionPatterns` (atau `messages.groupChat.mentionPatterns`).
- `messages.responsePrefix`.
## Pengalamatan / target pengiriman
Utamakan `chat_guid` untuk perutean yang stabil:
- `chat_guid:iMessage;-;+15555550123` (disarankan untuk grup)
- `chat_id:123`
- `chat_identifier:...`
- Handle langsung: `+15555550123`, `user@example.com`
- Jika handle langsung tidak memiliki chat DM yang sudah ada, OpenClaw akan membuatnya melalui `POST /api/v1/chat/new`. Ini mengharuskan BlueBubbles Private API diaktifkan.
## Keamanan
- Permintaan webhook diautentikasi dengan membandingkan parameter query atau header `guid`/`password` dengan `channels.bluebubbles.password`.
- Jaga kerahasiaan kata sandi API dan endpoint webhook (perlakukan keduanya seperti kredensial).
- Tidak ada bypass localhost untuk autentikasi webhook BlueBubbles. Jika Anda mem-proxy lalu lintas webhook, pertahankan kata sandi BlueBubbles pada permintaan secara end-to-end. `gateway.trustedProxies` tidak menggantikan `channels.bluebubbles.password` di sini. Lihat [Keamanan gateway](/gateway/security#reverse-proxy-configuration).
- Aktifkan HTTPS + aturan firewall pada server BlueBubbles jika diekspos di luar LAN Anda.
## Pemecahan masalah
- Jika event mengetik/baca berhenti berfungsi, periksa log webhook BlueBubbles dan verifikasi path gateway cocok dengan `channels.bluebubbles.webhookPath`.
- Kode pairing kedaluwarsa setelah satu jam; gunakan `openclaw pairing list bluebubbles` dan `openclaw pairing approve bluebubbles <code>`.
- Reaksi memerlukan BlueBubbles private API (`POST /api/v1/message/react`); pastikan versi server mengeksposnya.
- Edit/batalkan kirim memerlukan macOS 13+ dan versi server BlueBubbles yang kompatibel. Di macOS 26 (Tahoe), edit saat ini rusak karena perubahan private API.
- Pembaruan ikon grup bisa tidak stabil di macOS 26 (Tahoe): API mungkin mengembalikan sukses tetapi ikon baru tidak tersinkron.
- OpenClaw secara otomatis menyembunyikan tindakan yang diketahui rusak berdasarkan versi macOS server BlueBubbles. Jika edit masih muncul di macOS 26 (Tahoe), nonaktifkan secara manual dengan `channels.bluebubbles.actions.edit=false`.
- Untuk info status/kesehatan: `openclaw status --all` atau `openclaw status --deep`.
Untuk referensi alur kerja channel umum, lihat [Channels](/channels) dan panduan [Plugins](/tools/plugin).
## Terkait
- [Ikhtisar Channels](/channels) — semua channel yang didukung
- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing
- [Groups](/channels/groups) — perilaku chat grup dan penggatingan mention
- [Perutean Channel](/channels/channel-routing) — perutean sesi untuk pesan
- [Keamanan](/gateway/security) — model akses dan hardening

449
docs/id/channels/broadcast-groups.md Normal file
View File

@ -0,0 +1,449 @@
---
read_when:
- Mengonfigurasi broadcast groups
- Men-debug balasan multi-agent di WhatsApp
status: experimental
summary: Siarkan pesan WhatsApp ke beberapa agent
title: Broadcast Groups
x-i18n:
generated_at: "2026-04-05T13:42:50Z"
model: gpt-5.4
provider: openai
source_hash: 1d117ae65ec3b63c2bd4b3c215d96f32d7eafa0f99a9cd7378e502c15e56ca56
source_path: channels/broadcast-groups.md
workflow: 15
---
# Broadcast Groups
**Status:** Eksperimental
**Versi:** Ditambahkan pada 2026.1.9
## Ikhtisar
Broadcast Groups memungkinkan beberapa agent memproses dan merespons pesan yang sama secara bersamaan. Ini memungkinkan Anda membuat tim agent khusus yang bekerja bersama dalam satu grup atau DM WhatsApp — semuanya menggunakan satu nomor telepon.
Cakupan saat ini: **WhatsApp saja** (channel web).
Broadcast groups dievaluasi setelah allowlist channel dan aturan aktivasi grup. Di grup WhatsApp, ini berarti siaran terjadi saat OpenClaw biasanya akan membalas (misalnya: saat disebut, tergantung pada pengaturan grup Anda).
## Kasus Penggunaan
### 1. Tim Agent Khusus
Terapkan beberapa agent dengan tanggung jawab atomik dan terfokus:
```
Group: "Development Team"
Agents:
- CodeReviewer (reviews code snippets)
- DocumentationBot (generates docs)
- SecurityAuditor (checks for vulnerabilities)
- TestGenerator (suggests test cases)
```
Setiap agent memproses pesan yang sama dan memberikan perspektif khususnya.
### 2. Dukungan Multi-Bahasa
```
Group: "International Support"
Agents:
- Agent_EN (responds in English)
- Agent_DE (responds in German)
- Agent_ES (responds in Spanish)
```
### 3. Alur Kerja Jaminan Kualitas
```
Group: "Customer Support"
Agents:
- SupportAgent (provides answer)
- QAAgent (reviews quality, only responds if issues found)
```
### 4. Otomatisasi Tugas
```
Group: "Project Management"
Agents:
- TaskTracker (updates task database)
- TimeLogger (logs time spent)
- ReportGenerator (creates summaries)
```
## Konfigurasi
### Pengaturan Dasar
Tambahkan bagian `broadcast` tingkat atas (di samping `bindings`). Kuncinya adalah ID peer WhatsApp:
- obrolan grup: JID grup (misalnya `120363403215116621@g.us`)
- DM: nomor telepon E.164 (misalnya `+15551234567`)
```json
{
"broadcast": {
"120363403215116621@g.us": ["alfred", "baerbel", "assistant3"]
}
}
```
**Hasil:** Saat OpenClaw akan membalas di obrolan ini, OpenClaw akan menjalankan ketiga agent tersebut.
### Strategi Pemrosesan
Kontrol bagaimana agent memproses pesan:
#### Paralel (Default)
Semua agent memproses secara bersamaan:
```json
{
"broadcast": {
"strategy": "parallel",
"120363403215116621@g.us": ["alfred", "baerbel"]
}
}
```
#### Berurutan
Agent memproses secara berurutan (satu menunggu yang sebelumnya selesai):
```json
{
"broadcast": {
"strategy": "sequential",
"120363403215116621@g.us": ["alfred", "baerbel"]
}
}
```
### Contoh Lengkap
```json
{
"agents": {
"list": [
{
"id": "code-reviewer",
"name": "Code Reviewer",
"workspace": "/path/to/code-reviewer",
"sandbox": { "mode": "all" }
},
{
"id": "security-auditor",
"name": "Security Auditor",
"workspace": "/path/to/security-auditor",
"sandbox": { "mode": "all" }
},
{
"id": "docs-generator",
"name": "Documentation Generator",
"workspace": "/path/to/docs-generator",
"sandbox": { "mode": "all" }
}
]
},
"broadcast": {
"strategy": "parallel",
"120363403215116621@g.us": ["code-reviewer", "security-auditor", "docs-generator"],
"120363424282127706@g.us": ["support-en", "support-de"],
"+15555550123": ["assistant", "logger"]
}
}
```
## Cara Kerjanya
### Alur Pesan
1. **Pesan masuk** tiba di grup WhatsApp
2. **Pemeriksaan broadcast**: Sistem memeriksa apakah ID peer ada di `broadcast`
3. **Jika ada dalam daftar broadcast**:
- Semua agent yang tercantum memproses pesan
- Setiap agent memiliki kunci sesi sendiri dan konteks yang terisolasi
- Agent memproses secara paralel (default) atau berurutan
4. **Jika tidak ada dalam daftar broadcast**:
- Routing normal berlaku (binding pertama yang cocok)
Catatan: broadcast groups tidak mem-bypass allowlist channel atau aturan aktivasi grup (mention/perintah/dll). Fitur ini hanya mengubah _agent mana yang dijalankan_ saat sebuah pesan memenuhi syarat untuk diproses.
### Isolasi Sesi
Setiap agent dalam broadcast group mempertahankan hal-hal berikut secara sepenuhnya terpisah:
- **Kunci sesi** (`agent:alfred:whatsapp:group:120363...` vs `agent:baerbel:whatsapp:group:120363...`)
- **Riwayat percakapan** (agent tidak melihat pesan agent lain)
- **Workspace** (sandbox terpisah jika dikonfigurasi)
- **Akses tool** (daftar allow/deny yang berbeda)
- **Memori/konteks** (`IDENTITY.md`, `SOUL.md`, dll. yang terpisah)
- **Buffer konteks grup** (pesan grup terbaru yang digunakan untuk konteks) dibagikan per peer, jadi semua agent broadcast melihat konteks yang sama saat dipicu
Ini memungkinkan setiap agent memiliki:
- Kepribadian yang berbeda
- Akses tool yang berbeda (misalnya, read-only vs. read-write)
- Model yang berbeda (misalnya, opus vs. sonnet)
- Skills berbeda yang terinstal
### Contoh: Sesi Terisolasi
Di grup `120363403215116621@g.us` dengan agent `["alfred", "baerbel"]`:
**Konteks Alfred:**
```
Session: agent:alfred:whatsapp:group:120363403215116621@g.us
History: [user message, alfred's previous responses]
Workspace: /Users/user/openclaw-alfred/
Tools: read, write, exec
```
**Konteks Bärbel:**
```
Session: agent:baerbel:whatsapp:group:120363403215116621@g.us
History: [user message, baerbel's previous responses]
Workspace: /Users/user/openclaw-baerbel/
Tools: read only
```
## Praktik Terbaik
### 1. Pertahankan Agent Tetap Terfokus
Rancang setiap agent dengan satu tanggung jawab yang jelas:
```json
{
"broadcast": {
"DEV_GROUP": ["formatter", "linter", "tester"]
}
}
```
✅ **Baik:** Setiap agent memiliki satu tugas
❌ **Buruk:** Satu agent "dev-helper" generik
### 2. Gunakan Nama yang Deskriptif
Buat jelas apa yang dilakukan setiap agent:
```json
{
"agents": {
"security-scanner": { "name": "Security Scanner" },
"code-formatter": { "name": "Code Formatter" },
"test-generator": { "name": "Test Generator" }
}
}
```
### 3. Konfigurasikan Akses Tool yang Berbeda
Berikan agent hanya tool yang mereka perlukan:
```json
{
"agents": {
"reviewer": {
"tools": { "allow": ["read", "exec"] } // Read-only
},
"fixer": {
"tools": { "allow": ["read", "write", "edit", "exec"] } // Read-write
}
}
}
```
### 4. Pantau Performa
Dengan banyak agent, pertimbangkan:
- Menggunakan `"strategy": "parallel"` (default) untuk kecepatan
- Membatasi broadcast groups menjadi 5-10 agent
- Menggunakan model yang lebih cepat untuk agent yang lebih sederhana
### 5. Tangani Kegagalan dengan Baik
Agent gagal secara independen. Kesalahan pada satu agent tidak memblokir yang lain:
```
Message → [Agent A ✓, Agent B ✗ error, Agent C ✓]
Result: Agent A and C respond, Agent B logs error
```
## Kompatibilitas
### Provider
Broadcast groups saat ini berfungsi dengan:
- ✅ WhatsApp (sudah diimplementasikan)
- 🚧 Telegram (direncanakan)
- 🚧 Discord (direncanakan)
- 🚧 Slack (direncanakan)
### Routing
Broadcast groups berfungsi bersama routing yang sudah ada:
```json
{
"bindings": [
{
"match": { "channel": "whatsapp", "peer": { "kind": "group", "id": "GROUP_A" } },
"agentId": "alfred"
}
],
"broadcast": {
"GROUP_B": ["agent1", "agent2"]
}
}
```
- `GROUP_A`: Hanya alfred yang merespons (routing normal)
- `GROUP_B`: agent1 DAN agent2 merespons (broadcast)
**Prioritas:** `broadcast` memiliki prioritas lebih tinggi daripada `bindings`.
## Pemecahan Masalah
### Agent Tidak Merespons
**Periksa:**
1. ID agent ada di `agents.list`
2. Format ID peer benar (misalnya, `120363403215116621@g.us`)
3. Agent tidak ada dalam deny list
**Debug:**
```bash
tail -f ~/.openclaw/logs/gateway.log | grep broadcast
```
### Hanya Satu Agent yang Merespons
**Penyebab:** ID peer mungkin ada di `bindings` tetapi tidak ada di `broadcast`.
**Perbaikan:** Tambahkan ke konfigurasi broadcast atau hapus dari bindings.
### Masalah Performa
**Jika lambat dengan banyak agent:**
- Kurangi jumlah agent per grup
- Gunakan model yang lebih ringan (sonnet alih-alih opus)
- Periksa waktu startup sandbox
## Contoh
### Contoh 1: Tim Review Kode
```json
{
"broadcast": {
"strategy": "parallel",
"120363403215116621@g.us": [
"code-formatter",
"security-scanner",
"test-coverage",
"docs-checker"
]
},
"agents": {
"list": [
{
"id": "code-formatter",
"workspace": "~/agents/formatter",
"tools": { "allow": ["read", "write"] }
},
{
"id": "security-scanner",
"workspace": "~/agents/security",
"tools": { "allow": ["read", "exec"] }
},
{
"id": "test-coverage",
"workspace": "~/agents/testing",
"tools": { "allow": ["read", "exec"] }
},
{ "id": "docs-checker", "workspace": "~/agents/docs", "tools": { "allow": ["read"] } }
]
}
}
```
**Pengguna mengirim:** Potongan kode
**Respons:**
- code-formatter: "Memperbaiki indentasi dan menambahkan type hint"
- security-scanner: "⚠️ Kerentanan SQL injection pada baris 12"
- test-coverage: "Cakupan 45%, tes untuk kasus kesalahan masih kurang"
- docs-checker: "Docstring untuk fungsi `process_data` tidak ada"
### Contoh 2: Dukungan Multi-Bahasa
```json
{
"broadcast": {
"strategy": "sequential",
"+15555550123": ["detect-language", "translator-en", "translator-de"]
},
"agents": {
"list": [
{ "id": "detect-language", "workspace": "~/agents/lang-detect" },
{ "id": "translator-en", "workspace": "~/agents/translate-en" },
{ "id": "translator-de", "workspace": "~/agents/translate-de" }
]
}
}
```
## Referensi API
### Skema Konfigurasi
```typescript
interface OpenClawConfig {
broadcast?: {
strategy?: "parallel" | "sequential";
[peerId: string]: string[];
};
}
```
### Field
- `strategy` (opsional): Cara memproses agent
- `"parallel"` (default): Semua agent memproses secara bersamaan
- `"sequential"`: Agent memproses sesuai urutan array
- `[peerId]`: JID grup WhatsApp, nomor E.164, atau ID peer lainnya
- Nilai: Array ID agent yang harus memproses pesan
## Keterbatasan
1. **Maks agent:** Tidak ada batas keras, tetapi 10+ agent mungkin lambat
2. **Konteks bersama:** Agent tidak melihat respons satu sama lain (sesuai desain)
3. **Urutan pesan:** Respons paralel dapat tiba dalam urutan apa pun
4. **Batas laju:** Semua agent dihitung terhadap batas laju WhatsApp
## Peningkatan di Masa Depan
Fitur yang direncanakan:
- [ ] Mode konteks bersama (agent melihat respons satu sama lain)
- [ ] Koordinasi agent (agent dapat saling memberi sinyal)
- [ ] Pemilihan agent dinamis (pilih agent berdasarkan isi pesan)
- [ ] Prioritas agent (beberapa agent merespons sebelum yang lain)
## Lihat Juga
- [Konfigurasi Multi-Agent](/tools/multi-agent-sandbox-tools)
- [Konfigurasi Routing](/channels/channel-routing)
- [Manajemen Sesi](/concepts/session)

136
docs/id/channels/channel-routing.md Normal file
View File

@ -0,0 +1,136 @@
---
read_when:
- Mengubah perutean channel atau perilaku inbox
summary: Aturan perutean per channel (WhatsApp, Telegram, Discord, Slack) dan konteks bersama
title: Perutean Channel
x-i18n:
generated_at: "2026-04-05T13:42:36Z"
model: gpt-5.4
provider: openai
source_hash: 63916c4dd0af5fc9bbd12581a9eb15fea14a380c5ade09323ca0c237db61e537
source_path: channels/channel-routing.md
workflow: 15
---
# Channel & perutean
OpenClaw merutekan balasan **kembali ke channel asal pesan**. Model tidak memilih channel; perutean bersifat deterministik dan dikendalikan oleh konfigurasi host.
## Istilah utama
- **Channel**: `telegram`, `whatsapp`, `discord`, `irc`, `googlechat`, `slack`, `signal`, `imessage`, `line`, ditambah extension channel. `webchat` adalah channel UI WebChat internal dan bukan channel outbound yang dapat dikonfigurasi.
- **AccountId**: instance akun per channel (jika didukung).
- Akun default channel opsional: `channels.<channel>.defaultAccount` memilih akun mana yang digunakan saat jalur outbound tidak menentukan `accountId`.
- Dalam pengaturan multi-akun, tetapkan default eksplisit (`defaultAccount` atau `accounts.default`) saat dua atau lebih akun dikonfigurasi. Tanpanya, perutean fallback dapat memilih ID akun ternormalisasi pertama.
- **AgentId**: penyimpanan workspace + sesi yang terisolasi (“otak”).
- **SessionKey**: kunci bucket yang digunakan untuk menyimpan konteks dan mengendalikan konkurensi.
## Bentuk kunci sesi (contoh)
Pesan langsung disatukan ke sesi **utama** agen:
- `agent:<agentId>:<mainKey>` (default: `agent:main:main`)
Grup dan channel tetap terisolasi per channel:
- Grup: `agent:<agentId>:<channel>:group:<id>`
- Channel/room: `agent:<agentId>:<channel>:channel:<id>`
Thread:
- Thread Slack/Discord menambahkan `:thread:<threadId>` ke kunci dasar.
- Topik forum Telegram menyematkan `:topic:<topicId>` dalam kunci grup.
Contoh:
- `agent:main:telegram:group:-1001234567890:topic:42`
- `agent:main:discord:channel:123456:thread:987654`
## Penyematan rute DM utama
Saat `session.dmScope` adalah `main`, pesan langsung dapat berbagi satu sesi utama.
Untuk mencegah `lastRoute` sesi ditimpa oleh DM non-pemilik, OpenClaw menyimpulkan pemilik yang disematkan dari `allowFrom` jika semua kondisi berikut benar:
- `allowFrom` memiliki tepat satu entri non-wildcard.
- Entri tersebut dapat dinormalisasi menjadi ID pengirim konkret untuk channel itu.
- Pengirim DM masuk tidak cocok dengan pemilik yang disematkan itu.
Dalam kasus ketidakcocokan tersebut, OpenClaw tetap merekam metadata sesi masuk, tetapi melewati pembaruan `lastRoute` sesi utama.
## Aturan perutean (cara agen dipilih)
Perutean memilih **satu agen** untuk setiap pesan masuk:
1. **Kecocokan peer persis** (`bindings` dengan `peer.kind` + `peer.id`).
2. **Kecocokan peer induk** (pewarisan thread).
3. **Kecocokan guild + roles** (Discord) melalui `guildId` + `roles`.
4. **Kecocokan guild** (Discord) melalui `guildId`.
5. **Kecocokan team** (Slack) melalui `teamId`.
6. **Kecocokan akun** (`accountId` pada channel).
7. **Kecocokan channel** (akun apa pun pada channel tersebut, `accountId: "*"`).
8. **Agen default** (`agents.list[].default`, jika tidak maka entri daftar pertama, fallback ke `main`).
Saat sebuah binding menyertakan beberapa field kecocokan (`peer`, `guildId`, `teamId`, `roles`), **semua field yang disediakan harus cocok** agar binding tersebut berlaku.
Agen yang cocok menentukan workspace dan penyimpanan sesi mana yang digunakan.
## Grup broadcast (menjalankan beberapa agen)
Grup broadcast memungkinkan Anda menjalankan **beberapa agen** untuk peer yang sama **saat OpenClaw biasanya akan membalas** (misalnya: di grup WhatsApp, setelah penyebutan/activation gating).
Konfigurasi:
```json5
{
broadcast: {
strategy: "parallel",
"120363403215116621@g.us": ["alfred", "baerbel"],
"+15555550123": ["support", "logger"],
},
}
```
Lihat: [Grup Broadcast](/channels/broadcast-groups).
## Gambaran umum konfigurasi
- `agents.list`: definisi agen bernama (workspace, model, dll.).
- `bindings`: memetakan channel/akun/peer masuk ke agen.
Contoh:
```json5
{
agents: {
list: [{ id: "support", name: "Support", workspace: "~/.openclaw/workspace-support" }],
},
bindings: [
{ match: { channel: "slack", teamId: "T123" }, agentId: "support" },
{ match: { channel: "telegram", peer: { kind: "group", id: "-100123" } }, agentId: "support" },
],
}
```
## Penyimpanan sesi
Penyimpanan sesi berada di bawah direktori state (default `~/.openclaw`):
- `~/.openclaw/agents/<agentId>/sessions/sessions.json`
- Transkrip JSONL berada di lokasi yang sama dengan penyimpanan
Anda dapat menimpa jalur penyimpanan melalui `session.store` dan templating `{agentId}`.
Penemuan sesi Gateway dan ACP juga memindai penyimpanan agen berbasis disk di bawah root `agents/` default dan di bawah root `session.store` bertemplat. Penyimpanan yang ditemukan harus tetap berada di dalam root agen yang telah di-resolve tersebut dan menggunakan file `sessions.json` biasa. Symlink dan jalur di luar root diabaikan.
## Perilaku WebChat
WebChat terpasang ke **agen yang dipilih** dan default ke sesi utama agen. Karena itu, WebChat memungkinkan Anda melihat konteks lintas-channel untuk agen tersebut di satu tempat.
## Konteks balasan
Balasan masuk mencakup:
- `ReplyToId`, `ReplyToBody`, dan `ReplyToSender` jika tersedia.
- Konteks kutipan ditambahkan ke `Body` sebagai blok `[Replying to ...]`.
Ini konsisten di semua channel.

1261
docs/id/channels/discord.md Normal file
View File

File diff suppressed because it is too large Load Diff

800
docs/id/channels/feishu.md Normal file
View File

@ -0,0 +1,800 @@
---
read_when:
- Anda ingin menghubungkan bot Feishu/Lark
- Anda sedang mengonfigurasi channel Feishu
summary: Ikhtisar, fitur, dan konfigurasi bot Feishu
title: Feishu
x-i18n:
generated_at: "2026-04-05T13:43:35Z"
model: gpt-5.4
provider: openai
source_hash: 4e39b6dfe3a3aa4ebbdb992975e570e4f1b5e79f3b400a555fc373a0d1889952
source_path: channels/feishu.md
workflow: 15
---
# Bot Feishu
Feishu (Lark) adalah platform obrolan tim yang digunakan perusahaan untuk perpesanan dan kolaborasi. Plugin ini menghubungkan OpenClaw ke bot Feishu/Lark menggunakan langganan peristiwa WebSocket milik platform, sehingga pesan dapat diterima tanpa mengekspos URL webhook publik.
---
## Plugin bawaan
Feishu sudah disertakan secara bawaan dalam rilis OpenClaw saat ini, sehingga tidak
memerlukan instalasi plugin terpisah.
Jika Anda menggunakan build lama atau instalasi kustom yang tidak menyertakan bundel
Feishu, instal secara manual:
```bash
openclaw plugins install @openclaw/feishu
```
---
## Mulai cepat
Ada dua cara untuk menambahkan channel Feishu:
### Metode 1: onboarding (direkomendasikan)
Jika Anda baru saja menginstal OpenClaw, jalankan onboarding:
```bash
openclaw onboard
```
Wizard akan memandu Anda melalui:
1. Membuat aplikasi Feishu dan mengumpulkan kredensial
2. Mengonfigurasi kredensial aplikasi di OpenClaw
3. Menjalankan gateway
✅ **Setelah konfigurasi**, periksa status gateway:
- `openclaw gateway status`
- `openclaw logs --follow`
### Metode 2: penyiapan CLI
Jika Anda sudah menyelesaikan instalasi awal, tambahkan channel melalui CLI:
```bash
openclaw channels add
```
Pilih **Feishu**, lalu masukkan App ID dan App Secret.
✅ **Setelah konfigurasi**, kelola gateway:
- `openclaw gateway status`
- `openclaw gateway restart`
- `openclaw logs --follow`
---
## Langkah 1: Buat aplikasi Feishu
### 1. Buka Feishu Open Platform
Kunjungi [Feishu Open Platform](https://open.feishu.cn/app) dan masuk.
Tenant Lark (global) harus menggunakan [https://open.larksuite.com/app](https://open.larksuite.com/app) dan menetapkan `domain: "lark"` di konfigurasi Feishu.
### 2. Buat aplikasi
1. Klik **Create enterprise app**
2. Isi nama + deskripsi aplikasi
3. Pilih ikon aplikasi
![Create enterprise app](/images/feishu-step2-create-app.png)
### 3. Salin kredensial
Dari **Credentials & Basic Info**, salin:
- **App ID** (format: `cli_xxx`)
- **App Secret**
❗ **Penting:** jaga kerahasiaan App Secret.
![Get credentials](/images/feishu-step3-credentials.png)
### 4. Konfigurasikan izin
Pada **Permissions**, klik **Batch import** dan tempel:
```json
{
"scopes": {
"tenant": [
"aily:file:read",
"aily:file:write",
"application:application.app_message_stats.overview:readonly",
"application:application:self_manage",
"application:bot.menu:write",
"cardkit:card:read",
"cardkit:card:write",
"contact:user.employee_id:readonly",
"corehr:file:download",
"event:ip_list",
"im:chat.access_event.bot_p2p_chat:read",
"im:chat.members:bot_access",
"im:message",
"im:message.group_at_msg:readonly",
"im:message.p2p_msg:readonly",
"im:message:readonly",
"im:message:send_as_bot",
"im:resource"
],
"user": ["aily:file:read", "aily:file:write", "im:chat.access_event.bot_p2p_chat:read"]
}
}
```
![Configure permissions](/images/feishu-step4-permissions.png)
### 5. Aktifkan kemampuan bot
Di **App Capability** > **Bot**:
1. Aktifkan kemampuan bot
2. Tetapkan nama bot
![Enable bot capability](/images/feishu-step5-bot-capability.png)
### 6. Konfigurasikan langganan peristiwa
⚠️ **Penting:** sebelum menetapkan langganan peristiwa, pastikan:
1. Anda sudah menjalankan `openclaw channels add` untuk Feishu
2. Gateway sedang berjalan (`openclaw gateway status`)
Di **Event Subscription**:
1. Pilih **Use long connection to receive events** (WebSocket)
2. Tambahkan peristiwa: `im.message.receive_v1`
3. (Opsional) Untuk alur kerja komentar Drive, tambahkan juga: `drive.notice.comment_add_v1`
⚠️ Jika gateway tidak berjalan, penyiapan long-connection mungkin gagal disimpan.
![Configure event subscription](/images/feishu-step6-event-subscription.png)
### 7. Publikasikan aplikasi
1. Buat versi di **Version Management & Release**
2. Kirim untuk peninjauan dan publikasikan
3. Tunggu persetujuan admin (aplikasi enterprise biasanya disetujui otomatis)
---
## Langkah 2: Konfigurasikan OpenClaw
### Konfigurasikan dengan wizard (direkomendasikan)
```bash
openclaw channels add
```
Pilih **Feishu** dan tempelkan App ID + App Secret Anda.
### Konfigurasikan melalui file konfigurasi
Edit `~/.openclaw/openclaw.json`:
```json5
{
channels: {
feishu: {
enabled: true,
dmPolicy: "pairing",
accounts: {
main: {
appId: "cli_xxx",
appSecret: "xxx",
name: "My AI assistant",
},
},
},
},
}
```
Jika Anda menggunakan `connectionMode: "webhook"`, tetapkan `verificationToken` dan `encryptKey`. Server webhook Feishu melakukan bind ke `127.0.0.1` secara default; tetapkan `webhookHost` hanya jika Anda memang sengaja memerlukan alamat bind yang berbeda.
#### Verification Token dan Encrypt Key (mode webhook)
Saat menggunakan mode webhook, tetapkan `channels.feishu.verificationToken` dan `channels.feishu.encryptKey` di konfigurasi Anda. Untuk mendapatkan nilainya:
1. Di Feishu Open Platform, buka aplikasi Anda
2. Buka **Development** → **Events & Callbacks** (开发配置 → 事件与回调)
3. Buka tab **Encryption** (加密策略)
4. Salin **Verification Token** dan **Encrypt Key**
Tangkapan layar di bawah ini menunjukkan tempat menemukan **Verification Token**. **Encrypt Key** tercantum di bagian **Encryption** yang sama.
![Verification Token location](/images/feishu-verification-token.png)
### Konfigurasikan melalui variabel lingkungan
```bash
export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="xxx"
```
### Domain Lark (global)
Jika tenant Anda berada di Lark (internasional), tetapkan domain ke `lark` (atau string domain lengkap). Anda dapat menetapkannya di `channels.feishu.domain` atau per akun (`channels.feishu.accounts.<id>.domain`).
```json5
{
channels: {
feishu: {
domain: "lark",
accounts: {
main: {
appId: "cli_xxx",
appSecret: "xxx",
},
},
},
},
}
```
### Flag optimasi kuota
Anda dapat mengurangi penggunaan API Feishu dengan dua flag opsional:
- `typingIndicator` (default `true`): saat `false`, lewati panggilan reaksi mengetik.
- `resolveSenderNames` (default `true`): saat `false`, lewati panggilan pencarian profil pengirim.
Tetapkan di level teratas atau per akun:
```json5
{
channels: {
feishu: {
typingIndicator: false,
resolveSenderNames: false,
accounts: {
main: {
appId: "cli_xxx",
appSecret: "xxx",
typingIndicator: true,
resolveSenderNames: false,
},
},
},
},
}
```
---
## Langkah 3: Jalankan + uji
### 1. Jalankan gateway
```bash
openclaw gateway
```
### 2. Kirim pesan uji
Di Feishu, temukan bot Anda dan kirim pesan.
### 3. Setujui pairing
Secara default, bot membalas dengan kode pairing. Setujui:
```bash
openclaw pairing approve feishu <CODE>
```
Setelah disetujui, Anda dapat mengobrol seperti biasa.
---
## Ikhtisar
- **Channel bot Feishu**: bot Feishu yang dikelola oleh gateway
- **Routing deterministik**: balasan selalu kembali ke Feishu
- **Isolasi sesi**: DM berbagi satu sesi utama; grup diisolasi
- **Koneksi WebSocket**: long connection melalui SDK Feishu, tidak memerlukan URL publik
---
## Kontrol akses
### Pesan langsung
- **Default**: `dmPolicy: "pairing"` (pengguna yang tidak dikenal mendapatkan kode pairing)
- **Setujui pairing**:
```bash
openclaw pairing list feishu
openclaw pairing approve feishu <CODE>
```
- **Mode allowlist**: tetapkan `channels.feishu.allowFrom` dengan Open ID yang diizinkan
### Obrolan grup
**1. Kebijakan grup** (`channels.feishu.groupPolicy`):
- `"open"` = izinkan semua orang di grup
- `"allowlist"` = hanya izinkan `groupAllowFrom`
- `"disabled"` = nonaktifkan pesan grup
Default: `allowlist`
**2. Persyaratan mention** (`channels.feishu.requireMention`, dapat dioverride melalui `channels.feishu.groups.<chat_id>.requireMention`):
- `true` eksplisit = memerlukan @mention
- `false` eksplisit = merespons tanpa mention
- jika tidak ditetapkan dan `groupPolicy: "open"` = default ke `false`
- jika tidak ditetapkan dan `groupPolicy` bukan `"open"` = default ke `true`
---
## Contoh konfigurasi grup
### Izinkan semua grup, tanpa @mention wajib (default untuk grup terbuka)
```json5
{
channels: {
feishu: {
groupPolicy: "open",
},
},
}
```
### Izinkan semua grup, tetapi tetap memerlukan @mention
```json5
{
channels: {
feishu: {
groupPolicy: "open",
requireMention: true,
},
},
}
```
### Hanya izinkan grup tertentu
```json5
{
channels: {
feishu: {
groupPolicy: "allowlist",
// Feishu group IDs (chat_id) look like: oc_xxx
groupAllowFrom: ["oc_xxx", "oc_yyy"],
},
},
}
```
### Batasi pengirim mana yang dapat mengirim pesan dalam grup (allowlist pengirim)
Selain mengizinkan grup itu sendiri, **semua pesan** dalam grup tersebut dibatasi oleh sender `open_id`: hanya pengguna yang tercantum di `groups.<chat_id>.allowFrom` yang pesannya diproses; pesan dari anggota lain diabaikan (ini adalah pembatasan penuh di level pengirim, bukan hanya untuk perintah kontrol seperti /reset atau /new).
```json5
{
channels: {
feishu: {
groupPolicy: "allowlist",
groupAllowFrom: ["oc_xxx"],
groups: {
oc_xxx: {
// Feishu user IDs (open_id) look like: ou_xxx
allowFrom: ["ou_user1", "ou_user2"],
},
},
},
},
}
```
---
<a id="get-groupuser-ids"></a>
## Dapatkan ID grup/pengguna
### ID grup (chat_id)
ID grup terlihat seperti `oc_xxx`.
**Metode 1 (direkomendasikan)**
1. Jalankan gateway dan lakukan @mention pada bot di grup
2. Jalankan `openclaw logs --follow` dan cari `chat_id`
**Metode 2**
Gunakan debugger API Feishu untuk mencantumkan obrolan grup.
### ID pengguna (open_id)
ID pengguna terlihat seperti `ou_xxx`.
**Metode 1 (direkomendasikan)**
1. Jalankan gateway dan kirim DM ke bot
2. Jalankan `openclaw logs --follow` dan cari `open_id`
**Metode 2**
Periksa permintaan pairing untuk Open ID pengguna:
```bash
openclaw pairing list feishu
```
---
## Perintah umum
| Perintah | Deskripsi |
| --------- | ---------------------- |
| `/status` | Tampilkan status bot |
| `/reset` | Reset sesi |
| `/model` | Tampilkan/ganti model |
> Catatan: Feishu belum mendukung menu perintah native, jadi perintah harus dikirim sebagai teks.
## Perintah manajemen gateway
| Perintah | Deskripsi |
| -------------------------- | ----------------------------- |
| `openclaw gateway status` | Tampilkan status gateway |
| `openclaw gateway install` | Instal/jalankan layanan gateway |
| `openclaw gateway stop` | Hentikan layanan gateway |
| `openclaw gateway restart` | Mulai ulang gateway |
| `openclaw logs --follow` | Ikuti log gateway |
---
## Pemecahan masalah
### Bot tidak merespons di obrolan grup
1. Pastikan bot sudah ditambahkan ke grup
2. Pastikan Anda melakukan @mention pada bot (perilaku default)
3. Periksa `groupPolicy` tidak disetel ke `"disabled"`
4. Periksa log: `openclaw logs --follow`
### Bot tidak menerima pesan
1. Pastikan aplikasi sudah dipublikasikan dan disetujui
2. Pastikan langganan peristiwa menyertakan `im.message.receive_v1`
3. Pastikan **long connection** diaktifkan
4. Pastikan izin aplikasi sudah lengkap
5. Pastikan gateway sedang berjalan: `openclaw gateway status`
6. Periksa log: `openclaw logs --follow`
### Kebocoran App Secret
1. Reset App Secret di Feishu Open Platform
2. Perbarui App Secret di konfigurasi Anda
3. Mulai ulang gateway
### Kegagalan pengiriman pesan
1. Pastikan aplikasi memiliki izin `im:message:send_as_bot`
2. Pastikan aplikasi sudah dipublikasikan
3. Periksa log untuk error yang lebih rinci
---
## Konfigurasi lanjutan
### Banyak akun
```json5
{
channels: {
feishu: {
defaultAccount: "main",
accounts: {
main: {
appId: "cli_xxx",
appSecret: "xxx",
name: "Primary bot",
},
backup: {
appId: "cli_yyy",
appSecret: "yyy",
name: "Backup bot",
enabled: false,
},
},
},
},
}
```
`defaultAccount` mengontrol akun Feishu mana yang digunakan ketika API outbound tidak menentukan `accountId` secara eksplisit.
### Batas pesan
- `textChunkLimit`: ukuran potongan teks outbound (default: 2000 karakter)
- `mediaMaxMb`: batas upload/download media (default: 30MB)
### Streaming
Feishu mendukung balasan streaming melalui kartu interaktif. Saat diaktifkan, bot memperbarui kartu ketika menghasilkan teks.
```json5
{
channels: {
feishu: {
streaming: true, // enable streaming card output (default true)
blockStreaming: true, // enable block-level streaming (default true)
},
},
}
```
Tetapkan `streaming: false` untuk menunggu balasan lengkap sebelum mengirim.
### Sesi ACP
Feishu mendukung ACP untuk:
- DM
- percakapan topik grup
ACP Feishu dikendalikan oleh perintah teks. Tidak ada menu slash-command native, jadi gunakan pesan `/acp ...` langsung di percakapan.
#### Binding ACP persisten
Gunakan binding ACP bertipe di level teratas untuk menautkan DM atau percakapan topik Feishu ke sesi ACP persisten.
```json5
{
agents: {
list: [
{
id: "codex",
runtime: {
type: "acp",
acp: {
agent: "codex",
backend: "acpx",
mode: "persistent",
cwd: "/workspace/openclaw",
},
},
},
],
},
bindings: [
{
type: "acp",
agentId: "codex",
match: {
channel: "feishu",
accountId: "default",
peer: { kind: "direct", id: "ou_1234567890" },
},
},
{
type: "acp",
agentId: "codex",
match: {
channel: "feishu",
accountId: "default",
peer: { kind: "group", id: "oc_group_chat:topic:om_topic_root" },
},
acp: { label: "codex-feishu-topic" },
},
],
}
```
#### Spawn ACP terikat thread dari obrolan
Di DM atau percakapan topik Feishu, Anda dapat membuat dan menautkan sesi ACP langsung di tempat:
```text
/acp spawn codex --thread here
```
Catatan:
- `--thread here` berfungsi untuk DM dan topik Feishu.
- Pesan lanjutan dalam DM/topik yang terikat dirutekan langsung ke sesi ACP tersebut.
- v1 tidak menargetkan obrolan grup umum tanpa topik.
### Routing multi-agent
Gunakan `bindings` untuk merutekan DM atau grup Feishu ke agen yang berbeda.
```json5
{
agents: {
list: [
{ id: "main" },
{
id: "clawd-fan",
workspace: "/home/user/clawd-fan",
agentDir: "/home/user/.openclaw/agents/clawd-fan/agent",
},
{
id: "clawd-xi",
workspace: "/home/user/clawd-xi",
agentDir: "/home/user/.openclaw/agents/clawd-xi/agent",
},
],
},
bindings: [
{
agentId: "main",
match: {
channel: "feishu",
peer: { kind: "direct", id: "ou_xxx" },
},
},
{
agentId: "clawd-fan",
match: {
channel: "feishu",
peer: { kind: "direct", id: "ou_yyy" },
},
},
{
agentId: "clawd-xi",
match: {
channel: "feishu",
peer: { kind: "group", id: "oc_zzz" },
},
},
],
}
```
Field routing:
- `match.channel`: `"feishu"`
- `match.peer.kind`: `"direct"` atau `"group"`
- `match.peer.id`: Open ID pengguna (`ou_xxx`) atau ID grup (`oc_xxx`)
Lihat [Dapatkan ID grup/pengguna](#get-groupuser-ids) untuk tips pencarian.
---
## Referensi konfigurasi
Konfigurasi lengkap: [Gateway configuration](/gateway/configuration)
Opsi utama:
| Pengaturan | Deskripsi | Default |
| ------------------------------------------------- | --------------------------------------- | ---------------- |
| `channels.feishu.enabled` | Aktifkan/nonaktifkan channel | `true` |
| `channels.feishu.domain` | Domain API (`feishu` atau `lark`) | `feishu` |
| `channels.feishu.connectionMode` | Mode transport peristiwa | `websocket` |
| `channels.feishu.defaultAccount` | ID akun default untuk routing outbound | `default` |
| `channels.feishu.verificationToken` | Wajib untuk mode webhook | - |
| `channels.feishu.encryptKey` | Wajib untuk mode webhook | - |
| `channels.feishu.webhookPath` | Path rute webhook | `/feishu/events` |
| `channels.feishu.webhookHost` | Host bind webhook | `127.0.0.1` |
| `channels.feishu.webhookPort` | Port bind webhook | `3000` |
| `channels.feishu.accounts.<id>.appId` | App ID | - |
| `channels.feishu.accounts.<id>.appSecret` | App Secret | - |
| `channels.feishu.accounts.<id>.domain` | Override domain API per akun | `feishu` |
| `channels.feishu.dmPolicy` | Kebijakan DM | `pairing` |
| `channels.feishu.allowFrom` | Allowlist DM (daftar `open_id`) | - |
| `channels.feishu.groupPolicy` | Kebijakan grup | `allowlist` |
| `channels.feishu.groupAllowFrom` | Allowlist grup | - |
| `channels.feishu.requireMention` | Persyaratan @mention default | conditional |
| `channels.feishu.groups.<chat_id>.requireMention` | Override @mention wajib per grup | inherited |
| `channels.feishu.groups.<chat_id>.enabled` | Aktifkan grup | `true` |
| `channels.feishu.textChunkLimit` | Ukuran potongan pesan | `2000` |
| `channels.feishu.mediaMaxMb` | Batas ukuran media | `30` |
| `channels.feishu.streaming` | Aktifkan output kartu streaming | `true` |
| `channels.feishu.blockStreaming` | Aktifkan streaming per blok | `true` |
---
## Referensi dmPolicy
| Nilai | Perilaku |
| ------------- | --------------------------------------------------------------- |
| `"pairing"` | **Default.** Pengguna tak dikenal mendapatkan kode pairing; harus disetujui |
| `"allowlist"` | Hanya pengguna di `allowFrom` yang dapat mengobrol |
| `"open"` | Izinkan semua pengguna (memerlukan `"*"` di `allowFrom`) |
| `"disabled"` | Nonaktifkan DM |
---
## Jenis pesan yang didukung
### Menerima
- ✅ Teks
- ✅ Rich text (post)
- ✅ Gambar
- ✅ File
- ✅ Audio
- ✅ Video/media
- ✅ Stiker
### Mengirim
- ✅ Teks
- ✅ Gambar
- ✅ File
- ✅ Audio
- ✅ Video/media
- ✅ Kartu interaktif
- ⚠️ Rich text (pemformatan gaya post dan kartu, bukan fitur authoring Feishu yang sewenang-wenang)
### Thread dan balasan
- ✅ Balasan inline
- ✅ Balasan topic-thread saat Feishu mengekspos `reply_in_thread`
- ✅ Balasan media tetap sadar thread saat membalas pesan thread/topik
## Komentar Drive
Feishu dapat memicu agen ketika seseorang menambahkan komentar pada dokumen Feishu Drive (Docs, Sheets,
dan lain-lain). Agen menerima teks komentar, konteks dokumen, dan thread komentar sehingga dapat
merespons di dalam thread atau melakukan edit dokumen.
Persyaratan:
- Berlangganan ke `drive.notice.comment_add_v1` di pengaturan langganan peristiwa aplikasi Feishu Anda
(bersama `im.message.receive_v1` yang sudah ada)
- Tool Drive aktif secara default; nonaktifkan dengan `channels.feishu.tools.drive: false`
Tool `feishu_drive` mengekspos tindakan komentar berikut:
| Tindakan | Deskripsi |
| ---------------------- | -------------------------------------- |
| `list_comments` | Daftarkan komentar pada dokumen |
| `list_comment_replies` | Daftarkan balasan dalam thread komentar |
| `add_comment` | Tambahkan komentar tingkat atas baru |
| `reply_comment` | Balas thread komentar yang ada |
Saat agen menangani peristiwa komentar Drive, agen menerima:
- teks komentar dan pengirim
- metadata dokumen (judul, jenis, URL)
- konteks thread komentar untuk balasan dalam thread
Setelah melakukan edit dokumen, agen diarahkan untuk menggunakan `feishu_drive.reply_comment` guna memberi tahu
pemberi komentar lalu mengeluarkan token senyap yang persis `NO_REPLY` / `no_reply` untuk
menghindari pengiriman duplikat.
## Permukaan tindakan runtime
Feishu saat ini mengekspos tindakan runtime berikut:
- `send`
- `read`
- `edit`
- `thread-reply`
- `pin`
- `list-pins`
- `unpin`
- `member-info`
- `channel-info`
- `channel-list`
- `react` dan `reactions` saat reaksi diaktifkan dalam konfigurasi
- tindakan komentar `feishu_drive`: `list_comments`, `list_comment_replies`, `add_comment`, `reply_comment`
## Terkait
- [Channels Overview](/channels) — semua channel yang didukung
- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing
- [Groups](/channels/groups) — perilaku obrolan grup dan pembatasan mention
- [Channel Routing](/channels/channel-routing) — routing sesi untuk pesan
- [Security](/gateway/security) — model akses dan penguatan

277
docs/id/channels/googlechat.md Normal file
View File

@ -0,0 +1,277 @@
---
read_when:
- Sedang mengerjakan fitur channel Google Chat
summary: Status dukungan aplikasi Google Chat, kapabilitas, dan konfigurasi
title: Google Chat
x-i18n:
generated_at: "2026-04-05T13:42:59Z"
model: gpt-5.4
provider: openai
source_hash: 570894ed798dd0b9ba42806b050927216379a1228fcd2f96de565bc8a4ac7c2c
source_path: channels/googlechat.md
workflow: 15
---
# Google Chat (Chat API)
Status: siap untuk DM + space melalui webhook Google Chat API (hanya HTTP).
## Penyiapan cepat (pemula)
1. Buat project Google Cloud dan aktifkan **Google Chat API**.
- Buka: [Google Chat API Credentials](https://console.cloud.google.com/apis/api/chat.googleapis.com/credentials)
- Aktifkan API jika belum diaktifkan.
2. Buat **Service Account**:
- Tekan **Create Credentials** > **Service Account**.
- Beri nama sesuai keinginan Anda (misalnya, `openclaw-chat`).
- Biarkan izin kosong (tekan **Continue**).
- Biarkan principal dengan akses tetap kosong (tekan **Done**).
3. Buat dan unduh **JSON Key**:
- Dalam daftar service account, klik yang baru saja Anda buat.
- Buka tab **Keys**.
- Klik **Add Key** > **Create new key**.
- Pilih **JSON** dan tekan **Create**.
4. Simpan file JSON yang diunduh di host gateway Anda (misalnya, `~/.openclaw/googlechat-service-account.json`).
5. Buat aplikasi Google Chat di [Google Cloud Console Chat Configuration](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat):
- Isi **Application info**:
- **App name**: (misalnya `OpenClaw`)
- **Avatar URL**: (misalnya `https://openclaw.ai/logo.png`)
- **Description**: (misalnya `Personal AI Assistant`)
- Aktifkan **Interactive features**.
- Di bawah **Functionality**, centang **Join spaces and group conversations**.
- Di bawah **Connection settings**, pilih **HTTP endpoint URL**.
- Di bawah **Triggers**, pilih **Use a common HTTP endpoint URL for all triggers** dan atur ke URL publik gateway Anda diikuti dengan `/googlechat`.
- _Tip: Jalankan `openclaw status` untuk menemukan URL publik gateway Anda._
- Di bawah **Visibility**, centang **Make this Chat app available to specific people and groups in &lt;Your Domain&gt;**.
- Masukkan alamat email Anda (misalnya `user@example.com`) ke dalam kotak teks.
- Klik **Save** di bagian bawah.
6. **Aktifkan status aplikasi**:
- Setelah menyimpan, **muat ulang halaman**.
- Cari bagian **App status** (biasanya di dekat atas atau bawah setelah menyimpan).
- Ubah status menjadi **Live - available to users**.
- Klik **Save** lagi.
7. Konfigurasikan OpenClaw dengan path service account + audience webhook:
- Env: `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json`
- Atau config: `channels.googlechat.serviceAccountFile: "/path/to/service-account.json"`.
8. Atur jenis + nilai audience webhook (sesuai dengan config aplikasi Chat Anda).
9. Mulai gateway. Google Chat akan mengirim POST ke path webhook Anda.
## Tambahkan ke Google Chat
Setelah gateway berjalan dan email Anda ditambahkan ke daftar visibilitas:
1. Buka [Google Chat](https://chat.google.com/).
2. Klik ikon **+** (plus) di samping **Direct Messages**.
3. Di bilah pencarian (tempat Anda biasanya menambahkan orang), ketik **App name** yang Anda konfigurasi di Google Cloud Console.
- **Catatan**: Bot _tidak_ akan muncul dalam daftar penelusuran "Marketplace" karena ini adalah aplikasi privat. Anda harus mencarinya berdasarkan nama.
4. Pilih bot Anda dari hasil pencarian.
5. Klik **Add** atau **Chat** untuk memulai percakapan 1:1.
6. Kirim "Hello" untuk memicu asisten!
## URL publik (khusus webhook)
Webhook Google Chat memerlukan endpoint HTTPS publik. Demi keamanan, **hanya ekspos path `/googlechat`** ke internet. Simpan dashboard OpenClaw dan endpoint sensitif lainnya di jaringan privat Anda.
### Opsi A: Tailscale Funnel (Direkomendasikan)
Gunakan Tailscale Serve untuk dashboard privat dan Funnel untuk path webhook publik. Ini menjaga `/` tetap privat sambil hanya mengekspos `/googlechat`.
1. **Periksa alamat tempat gateway Anda terikat:**
```bash
ss -tlnp | grep 18789
```
Catat alamat IP (misalnya `127.0.0.1`, `0.0.0.0`, atau IP Tailscale Anda seperti `100.x.x.x`).
2. **Ekspos dashboard hanya ke tailnet (port 8443):**
```bash
# Jika terikat ke localhost (127.0.0.1 atau 0.0.0.0):
tailscale serve --bg --https 8443 http://127.0.0.1:18789
# Jika terikat hanya ke IP Tailscale (misalnya, 100.106.161.80):
tailscale serve --bg --https 8443 http://100.106.161.80:18789
```
3. **Ekspos hanya path webhook secara publik:**
```bash
# Jika terikat ke localhost (127.0.0.1 atau 0.0.0.0):
tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat
# Jika terikat hanya ke IP Tailscale (misalnya, 100.106.161.80):
tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat
```
4. **Otorisasi node untuk akses Funnel:**
Jika diminta, kunjungi URL otorisasi yang ditampilkan dalam output untuk mengaktifkan Funnel bagi node ini dalam kebijakan tailnet Anda.
5. **Verifikasi konfigurasi:**
```bash
tailscale serve status
tailscale funnel status
```
URL webhook publik Anda akan menjadi:
`https://<node-name>.<tailnet>.ts.net/googlechat`
Dashboard privat Anda tetap hanya untuk tailnet:
`https://<node-name>.<tailnet>.ts.net:8443/`
Gunakan URL publik (tanpa `:8443`) dalam config aplikasi Google Chat.
> Catatan: Konfigurasi ini tetap ada setelah reboot. Untuk menghapusnya nanti, jalankan `tailscale funnel reset` dan `tailscale serve reset`.
### Opsi B: Reverse Proxy (Caddy)
Jika Anda menggunakan reverse proxy seperti Caddy, proksikan hanya path spesifik:
```caddy
your-domain.com {
reverse_proxy /googlechat* localhost:18789
}
```
Dengan config ini, setiap permintaan ke `your-domain.com/` akan diabaikan atau mengembalikan 404, sedangkan `your-domain.com/googlechat` akan dirutekan dengan aman ke OpenClaw.
### Opsi C: Cloudflare Tunnel
Konfigurasikan aturan ingress tunnel Anda agar hanya merutekan path webhook:
- **Path**: `/googlechat` -> `http://localhost:18789/googlechat`
- **Default Rule**: HTTP 404 (Not Found)
## Cara kerjanya
1. Google Chat mengirim webhook POST ke gateway. Setiap permintaan menyertakan header `Authorization: Bearer <token>`.
- OpenClaw memverifikasi autentikasi bearer sebelum membaca/mem-parse body webhook penuh saat header tersebut ada.
- Permintaan Google Workspace Add-on yang membawa `authorizationEventObject.systemIdToken` di dalam body didukung melalui anggaran body pra-autentikasi yang lebih ketat.
2. OpenClaw memverifikasi token terhadap `audienceType` + `audience` yang dikonfigurasi:
- `audienceType: "app-url"` → audience adalah URL webhook HTTPS Anda.
- `audienceType: "project-number"` → audience adalah nomor project Cloud.
3. Pesan dirutekan berdasarkan space:
- DM menggunakan kunci sesi `agent:<agentId>:googlechat:direct:<spaceId>`.
- Space menggunakan kunci sesi `agent:<agentId>:googlechat:group:<spaceId>`.
4. Akses DM menggunakan pairing secara default. Pengirim yang tidak dikenal menerima kode pairing; setujui dengan:
- `openclaw pairing approve googlechat <code>`
5. Space grup memerlukan @-mention secara default. Gunakan `botUser` jika deteksi mention memerlukan nama pengguna aplikasi.
## Target
Gunakan identifier ini untuk pengiriman dan allowlist:
- Direct messages: `users/<userId>` (direkomendasikan).
- Email mentah `name@example.com` dapat berubah dan hanya digunakan untuk pencocokan allowlist direct saat `channels.googlechat.dangerouslyAllowNameMatching: true`.
- Deprecated: `users/<email>` diperlakukan sebagai user id, bukan allowlist email.
- Spaces: `spaces/<spaceId>`.
## Sorotan config
```json5
{
channels: {
googlechat: {
enabled: true,
serviceAccountFile: "/path/to/service-account.json",
// atau serviceAccountRef: { source: "file", provider: "filemain", id: "/channels/googlechat/serviceAccount" }
audienceType: "app-url",
audience: "https://gateway.example.com/googlechat",
webhookPath: "/googlechat",
botUser: "users/1234567890", // opsional; membantu deteksi mention
dm: {
policy: "pairing",
allowFrom: ["users/1234567890"],
},
groupPolicy: "allowlist",
groups: {
"spaces/AAAA": {
allow: true,
requireMention: true,
users: ["users/1234567890"],
systemPrompt: "Short answers only.",
},
},
actions: { reactions: true },
typingIndicator: "message",
mediaMaxMb: 20,
},
},
}
```
Catatan:
- Kredensial service account juga dapat diberikan secara inline dengan `serviceAccount` (string JSON).
- `serviceAccountRef` juga didukung (SecretRef env/file), termasuk ref per akun di bawah `channels.googlechat.accounts.<id>.serviceAccountRef`.
- Path webhook default adalah `/googlechat` jika `webhookPath` tidak diatur.
- `dangerouslyAllowNameMatching` mengaktifkan kembali pencocokan principal email yang dapat berubah untuk allowlist (mode kompatibilitas break-glass).
- Reactions tersedia melalui alat `reactions` dan `channels action` saat `actions.reactions` diaktifkan.
- Message actions mengekspos `send` untuk teks dan `upload-file` untuk pengiriman lampiran eksplisit. `upload-file` menerima `media` / `filePath` / `path` ditambah `message`, `filename`, dan penargetan thread opsional.
- `typingIndicator` mendukung `none`, `message` (default), dan `reaction` (reaction memerlukan OAuth pengguna).
- Lampiran diunduh melalui Chat API dan disimpan di pipeline media (ukuran dibatasi oleh `mediaMaxMb`).
Detail referensi rahasia: [Secrets Management](/gateway/secrets).
## Pemecahan masalah
### 405 Method Not Allowed
Jika Google Cloud Logs Explorer menampilkan error seperti:
```
status code: 405, reason phrase: HTTP error response: HTTP/1.1 405 Method Not Allowed
```
Ini berarti handler webhook tidak terdaftar. Penyebab umum:
1. **Channel tidak dikonfigurasi**: Bagian `channels.googlechat` tidak ada dari config Anda. Verifikasi dengan:
```bash
openclaw config get channels.googlechat
```
Jika mengembalikan "Config path not found", tambahkan konfigurasi tersebut (lihat [Sorotan config](#config-highlights)).
2. **Plugin tidak diaktifkan**: Periksa status plugin:
```bash
openclaw plugins list | grep googlechat
```
Jika menampilkan "disabled", tambahkan `plugins.entries.googlechat.enabled: true` ke config Anda.
3. **Gateway belum dimulai ulang**: Setelah menambahkan config, mulai ulang gateway:
```bash
openclaw gateway restart
```
Verifikasi bahwa channel berjalan:
```bash
openclaw channels status
# Harus menampilkan: Google Chat default: enabled, configured, ...
```
### Masalah lain
- Periksa `openclaw channels status --probe` untuk error autentikasi atau config audience yang hilang.
- Jika tidak ada pesan yang masuk, konfirmasikan URL webhook + langganan peristiwa aplikasi Chat.
- Jika pembatasan mention memblokir balasan, atur `botUser` ke nama resource pengguna aplikasi dan verifikasi `requireMention`.
- Gunakan `openclaw logs --follow` saat mengirim pesan uji untuk melihat apakah permintaan mencapai gateway.
Dokumen terkait:
- [Konfigurasi gateway](/gateway/configuration)
- [Keamanan](/gateway/security)
- [Reactions](/tools/reactions)
## Terkait
- [Ikhtisar Channels](/channels) — semua channel yang didukung
- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing
- [Groups](/channels/groups) — perilaku obrolan grup dan pembatasan mention
- [Channel Routing](/channels/channel-routing) — perutean sesi untuk pesan
- [Keamanan](/gateway/security) — model akses dan penguatan

91
docs/id/channels/group-messages.md Normal file
View File

@ -0,0 +1,91 @@
---
read_when:
- Mengubah aturan pesan grup atau mention
summary: Perilaku dan konfigurasi untuk penanganan pesan grup WhatsApp (mentionPatterns dibagikan di seluruh surface)
title: Pesan Grup
x-i18n:
generated_at: "2026-04-05T13:42:55Z"
model: gpt-5.4
provider: openai
source_hash: 2543be5bc4c6f188f955df580a6fef585ecbfc1be36ade5d34b1a9157e021bc5
source_path: channels/group-messages.md
workflow: 15
---
# Pesan grup (channel web WhatsApp)
Tujuan: membiarkan Clawd berada di grup WhatsApp, aktif hanya saat dipanggil, dan menjaga thread itu tetap terpisah dari sesi DM pribadi.
Catatan: `agents.list[].groupChat.mentionPatterns` sekarang juga digunakan oleh Telegram/Discord/Slack/iMessage; dokumen ini berfokus pada perilaku khusus WhatsApp. Untuk pengaturan multi-agen, tetapkan `agents.list[].groupChat.mentionPatterns` per agen (atau gunakan `messages.groupChat.mentionPatterns` sebagai fallback global).
## Implementasi saat ini (2025-12-03)
- Mode aktivasi: `mention` (default) atau `always`. `mention` memerlukan panggilan (mention WhatsApp @ yang nyata melalui `mentionedJids`, pola regex aman, atau E.164 bot di mana pun dalam teks). `always` membangunkan agen pada setiap pesan tetapi agen seharusnya hanya membalas saat dapat memberi nilai yang bermakna; jika tidak, agen mengembalikan token senyap yang persis `NO_REPLY` / `no_reply`. Default dapat ditetapkan di config (`channels.whatsapp.groups`) dan dioverride per grup melalui `/activation`. Saat `channels.whatsapp.groups` ditetapkan, itu juga bertindak sebagai allowlist grup (sertakan `"*"` untuk mengizinkan semua).
- Kebijakan grup: `channels.whatsapp.groupPolicy` mengontrol apakah pesan grup diterima (`open|disabled|allowlist`). `allowlist` menggunakan `channels.whatsapp.groupAllowFrom` (fallback: `channels.whatsapp.allowFrom` yang eksplisit). Default adalah `allowlist` (diblokir sampai Anda menambahkan pengirim).
- Sesi per grup: kunci sesi berbentuk `agent:<agentId>:whatsapp:group:<jid>` sehingga perintah seperti `/verbose on` atau `/think high` (dikirim sebagai pesan mandiri) dibatasi ke grup tersebut; status DM pribadi tidak tersentuh. Heartbeat dilewati untuk thread grup.
- Injeksi konteks: pesan grup **pending-only** (default 50) yang _tidak_ memicu eksekusi diawali di bawah `[Chat messages since your last reply - for context]`, dengan baris pemicu di bawah `[Current message - respond to this]`. Pesan yang sudah ada di sesi tidak diinjeksi ulang.
- Penampilan pengirim: setiap batch grup sekarang diakhiri dengan `[from: Sender Name (+E164)]` sehingga Pi tahu siapa yang sedang berbicara.
- Ephemeral/view-once: kami membuka bungkusnya sebelum mengekstrak teks/mention, sehingga panggilan di dalamnya tetap memicu.
- Prompt sistem grup: pada giliran pertama sesi grup (dan setiap kali `/activation` mengubah mode) kami menyuntikkan uraian singkat ke prompt sistem seperti `You are replying inside the WhatsApp group "<subject>". Group members: Alice (+44...), Bob (+43...), … Activation: trigger-only … Address the specific sender noted in the message context.` Jika metadata tidak tersedia, kami tetap memberi tahu agen bahwa ini adalah obrolan grup.
## Contoh config (WhatsApp)
Tambahkan blok `groupChat` ke `~/.openclaw/openclaw.json` agar panggilan nama tampilan berfungsi bahkan saat WhatsApp menghapus `@` visual dari isi teks:
```json5
{
channels: {
whatsapp: {
groups: {
"*": { requireMention: true },
},
},
},
agents: {
list: [
{
id: "main",
groupChat: {
historyLimit: 50,
mentionPatterns: ["@?openclaw", "\\+?15555550123"],
},
},
],
},
}
```
Catatan:
- Regex ini tidak peka huruf besar/kecil dan menggunakan guardrail safe-regex yang sama seperti surface regex config lainnya; pola yang tidak valid dan nested repetition yang tidak aman diabaikan.
- WhatsApp tetap mengirim mention kanonis melalui `mentionedJids` saat seseorang mengetuk kontak, jadi fallback nomor jarang diperlukan tetapi berguna sebagai jaring pengaman.
### Perintah aktivasi (khusus pemilik)
Gunakan perintah obrolan grup:
- `/activation mention`
- `/activation always`
Hanya nomor pemilik (dari `channels.whatsapp.allowFrom`, atau E.164 bot itu sendiri jika tidak disetel) yang dapat mengubah ini. Kirim `/status` sebagai pesan mandiri di grup untuk melihat mode aktivasi saat ini.
## Cara menggunakan
1. Tambahkan akun WhatsApp Anda (yang menjalankan OpenClaw) ke grup.
2. Ucapkan `@openclaw …` (atau sertakan nomornya). Hanya pengirim di allowlist yang dapat memicunya kecuali Anda menetapkan `groupPolicy: "open"`.
3. Prompt agen akan menyertakan konteks grup terbaru plus penanda `[from: …]` di bagian akhir sehingga agen dapat menyapa orang yang tepat.
4. Direktif tingkat sesi (`/verbose on`, `/think high`, `/new` atau `/reset`, `/compact`) hanya berlaku untuk sesi grup itu; kirim sebagai pesan mandiri agar terdaftar. Sesi DM pribadi Anda tetap independen.
## Pengujian / verifikasi
- Smoke manual:
- Kirim panggilan `@openclaw` di grup dan konfirmasikan ada balasan yang merujuk nama pengirim.
- Kirim panggilan kedua dan verifikasi blok riwayat disertakan lalu dibersihkan pada giliran berikutnya.
- Periksa log gateway (jalankan dengan `--verbose`) untuk melihat entri `inbound web message` yang menampilkan `from: <groupJid>` dan sufiks `[from: …]`.
## Hal-hal yang perlu diperhatikan
- Heartbeat sengaja dilewati untuk grup agar tidak menimbulkan broadcast yang berisik.
- Penekanan echo menggunakan string batch gabungan; jika Anda mengirim teks identik dua kali tanpa mention, hanya yang pertama akan mendapat respons.
- Entri penyimpanan sesi akan muncul sebagai `agent:<agentId>:whatsapp:group:<jid>` di penyimpanan sesi (default `~/.openclaw/agents/<agentId>/sessions/sessions.json`); entri yang hilang hanya berarti grup tersebut belum memicu eksekusi.
- Indikator mengetik di grup mengikuti `agents.defaults.typingMode` (default: `message` saat tidak di-mention).

417
docs/id/channels/groups.md Normal file
View File

@ -0,0 +1,417 @@
---
read_when:
- Mengubah perilaku obrolan grup atau gating mention
summary: Perilaku obrolan grup di berbagai surface (Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo)
title: Grup
x-i18n:
generated_at: "2026-04-05T13:43:23Z"
model: gpt-5.4
provider: openai
source_hash: 39d066e0542b468c6f8b384b463e2316590ea09a00ecb2065053e1e2ce55bd5f
source_path: channels/groups.md
workflow: 15
---
# Grup
OpenClaw memperlakukan obrolan grup secara konsisten di berbagai surface: Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo.
## Pengantar untuk pemula (2 menit)
OpenClaw “hidup” di akun pesan Anda sendiri. Tidak ada pengguna bot WhatsApp terpisah.
Jika **Anda** berada di dalam grup, OpenClaw dapat melihat grup tersebut dan merespons di sana.
Perilaku default:
- Grup dibatasi (`groupPolicy: "allowlist"`).
- Balasan memerlukan mention kecuali Anda secara eksplisit menonaktifkan gating mention.
Artinya: pengirim yang ada dalam allowlist dapat memicu OpenClaw dengan menyebutnya.
> TL;DR
>
> - **Akses DM** dikendalikan oleh `*.allowFrom`.
> - **Akses grup** dikendalikan oleh `*.groupPolicy` + allowlist (`*.groups`, `*.groupAllowFrom`).
> - **Pemicu balasan** dikendalikan oleh gating mention (`requireMention`, `/activation`).
Alur singkat (apa yang terjadi pada pesan grup):
```
groupPolicy? disabled -> drop
groupPolicy? allowlist -> group allowed? no -> drop
requireMention? yes -> mentioned? no -> store for context only
otherwise -> reply
```
## Visibilitas konteks dan allowlist
Dua kontrol yang berbeda terlibat dalam keamanan grup:
- **Otorisasi pemicu**: siapa yang dapat memicu agen (`groupPolicy`, `groups`, `groupAllowFrom`, allowlist khusus channel).
- **Visibilitas konteks**: konteks tambahan apa yang disuntikkan ke model (teks balasan, kutipan, riwayat thread, metadata forward).
Secara default, OpenClaw memprioritaskan perilaku chat normal dan menjaga konteks sebagian besar tetap seperti diterima. Artinya, allowlist terutama menentukan siapa yang dapat memicu tindakan, bukan batas redaksi universal untuk setiap kutipan atau potongan riwayat.
Perilaku saat ini bersifat spesifik per channel:
- Beberapa channel sudah menerapkan pemfilteran berbasis pengirim untuk konteks tambahan pada jalur tertentu (misalnya seeding thread Slack, lookup balasan/thread Matrix).
- Channel lain masih meneruskan konteks kutipan/balasan/forward sebagaimana diterima.
Arah hardening (direncanakan):
- `contextVisibility: "all"` (default) mempertahankan perilaku saat ini sebagaimana diterima.
- `contextVisibility: "allowlist"` memfilter konteks tambahan ke pengirim yang ada dalam allowlist.
- `contextVisibility: "allowlist_quote"` adalah `allowlist` ditambah satu pengecualian kutipan/balasan yang eksplisit.
Sampai model hardening ini diimplementasikan secara konsisten di seluruh channel, perkirakan akan ada perbedaan antar surface.
![Alur pesan grup](/images/groups-flow.svg)
Jika Anda ingin...
| Tujuan | Yang harus disetel |
| ------------------------------------------- | ----------------------------------------------------------- |
| Izinkan semua grup tetapi hanya balas pada @mention | `groups: { "*": { requireMention: true } }` |
| Nonaktifkan semua balasan grup | `groupPolicy: "disabled"` |
| Hanya grup tertentu | `groups: { "<group-id>": { ... } }` (tanpa key `"*"` ) |
| Hanya Anda yang dapat memicu di grup | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` |
## Session key
- Sesi grup menggunakan session key `agent:<agentId>:<channel>:group:<id>` (room/channel menggunakan `agent:<agentId>:<channel>:channel:<id>`).
- Topik forum Telegram menambahkan `:topic:<threadId>` ke id grup sehingga setiap topik memiliki sesinya sendiri.
- Obrolan langsung menggunakan sesi utama (atau per pengirim jika dikonfigurasi).
- Heartbeat dilewati untuk sesi grup.
<a id="pattern-personal-dms-public-groups-single-agent"></a>
## Pola: DM pribadi + grup publik (agen tunggal)
Ya — ini bekerja dengan baik jika trafik “pribadi” Anda adalah **DM** dan trafik “publik” Anda adalah **grup**.
Alasannya: dalam mode agen tunggal, DM biasanya masuk ke session key **utama** (`agent:main:main`), sementara grup selalu menggunakan session key **non-utama** (`agent:main:<channel>:group:<id>`). Jika Anda mengaktifkan sandboxing dengan `mode: "non-main"`, sesi grup tersebut berjalan di Docker sementara sesi DM utama Anda tetap berjalan di host.
Ini memberi Anda satu “otak” agen (workspace + memori bersama), tetapi dua postur eksekusi:
- **DM**: alat penuh (host)
- **Grup**: sandbox + alat terbatas (Docker)
> Jika Anda memerlukan workspace/persona yang benar-benar terpisah (“pribadi” dan “publik” sama sekali tidak boleh bercampur), gunakan agen kedua + binding. Lihat [Multi-Agent Routing](/concepts/multi-agent).
Contoh (DM di host, grup di-sandbox + alat khusus messaging):
```json5
{
agents: {
defaults: {
sandbox: {
mode: "non-main", // groups/channels are non-main -> sandboxed
scope: "session", // strongest isolation (one container per group/channel)
workspaceAccess: "none",
},
},
},
tools: {
sandbox: {
tools: {
// If allow is non-empty, everything else is blocked (deny still wins).
allow: ["group:messaging", "group:sessions"],
deny: ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"],
},
},
},
}
```
Ingin “grup hanya bisa melihat folder X” alih-alih “tidak ada akses host”? Pertahankan `workspaceAccess: "none"` dan mount hanya path yang ada dalam allowlist ke sandbox:
```json5
{
agents: {
defaults: {
sandbox: {
mode: "non-main",
scope: "session",
workspaceAccess: "none",
docker: {
binds: [
// hostPath:containerPath:mode
"/home/user/FriendsShared:/data:ro",
],
},
},
},
},
}
```
Terkait:
- Key konfigurasi dan default: [Konfigurasi Gateway](/gateway/configuration-reference#agentsdefaultssandbox)
- Men-debug mengapa suatu alat diblokir: [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated)
- Detail bind mount: [Sandboxing](/gateway/sandboxing#custom-bind-mounts)
## Label tampilan
- Label UI menggunakan `displayName` bila tersedia, diformat sebagai `<channel>:<token>`.
- `#room` dicadangkan untuk room/channel; obrolan grup menggunakan `g-<slug>` (huruf kecil, spasi -> `-`, pertahankan `#@+._-`).
## Kebijakan grup
Kendalikan cara pesan grup/room ditangani per channel:
```json5
{
channels: {
whatsapp: {
groupPolicy: "disabled", // "open" | "disabled" | "allowlist"
groupAllowFrom: ["+15551234567"],
},
telegram: {
groupPolicy: "disabled",
groupAllowFrom: ["123456789"], // numeric Telegram user id (wizard can resolve @username)
},
signal: {
groupPolicy: "disabled",
groupAllowFrom: ["+15551234567"],
},
imessage: {
groupPolicy: "disabled",
groupAllowFrom: ["chat_id:123"],
},
msteams: {
groupPolicy: "disabled",
groupAllowFrom: ["user@org.com"],
},
discord: {
groupPolicy: "allowlist",
guilds: {
GUILD_ID: { channels: { help: { allow: true } } },
},
},
slack: {
groupPolicy: "allowlist",
channels: { "#general": { allow: true } },
},
matrix: {
groupPolicy: "allowlist",
groupAllowFrom: ["@owner:example.org"],
groups: {
"!roomId:example.org": { allow: true },
"#alias:example.org": { allow: true },
},
},
},
}
```
| Kebijakan | Perilaku |
| ------------- | ------------------------------------------------------------ |
| `"open"` | Grup melewati allowlist; gating mention tetap berlaku. |
| `"disabled"` | Blokir semua pesan grup sepenuhnya. |
| `"allowlist"` | Hanya izinkan grup/room yang cocok dengan allowlist yang dikonfigurasi. |
Catatan:
- `groupPolicy` terpisah dari gating mention (yang memerlukan @mention).
- WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: gunakan `groupAllowFrom` (fallback: `allowFrom` eksplisit).
- Persetujuan pairing DM (entri penyimpanan `*-allowFrom`) hanya berlaku untuk akses DM; otorisasi pengirim grup tetap eksplisit ke allowlist grup.
- Discord: allowlist menggunakan `channels.discord.guilds.<id>.channels`.
- Slack: allowlist menggunakan `channels.slack.channels`.
- Matrix: allowlist menggunakan `channels.matrix.groups`. Pilih room ID atau alias; lookup nama joined-room bersifat best-effort, dan nama yang tidak dapat diselesaikan diabaikan saat runtime. Gunakan `channels.matrix.groupAllowFrom` untuk membatasi pengirim; allowlist `users` per room juga didukung.
- Group DM dikendalikan secara terpisah (`channels.discord.dm.*`, `channels.slack.dm.*`).
- Allowlist Telegram dapat mencocokkan user ID (`"123456789"`, `"telegram:123456789"`, `"tg:123456789"`) atau username (`"@alice"` atau `"alice"`); prefiks tidak peka huruf besar/kecil.
- Default adalah `groupPolicy: "allowlist"`; jika allowlist grup Anda kosong, pesan grup diblokir.
- Keamanan runtime: saat blok provider sama sekali tidak ada (`channels.<provider>` tidak ada), kebijakan grup fallback ke mode fail-closed (biasanya `allowlist`) alih-alih mewarisi `channels.defaults.groupPolicy`.
Model mental singkat (urutan evaluasi untuk pesan grup):
1. `groupPolicy` (open/disabled/allowlist)
2. allowlist grup (`*.groups`, `*.groupAllowFrom`, allowlist khusus channel)
3. gating mention (`requireMention`, `/activation`)
## Gating mention (default)
Pesan grup memerlukan mention kecuali ditimpa per grup. Default berada per subsistem di bawah `*.groups."*"`.
Membalas pesan bot dihitung sebagai mention implisit (saat channel mendukung metadata balasan). Ini berlaku untuk Telegram, WhatsApp, Slack, Discord, dan Microsoft Teams.
```json5
{
channels: {
whatsapp: {
groups: {
"*": { requireMention: true },
"123@g.us": { requireMention: false },
},
},
telegram: {
groups: {
"*": { requireMention: true },
"123456789": { requireMention: false },
},
},
imessage: {
groups: {
"*": { requireMention: true },
"123": { requireMention: false },
},
},
},
agents: {
list: [
{
id: "main",
groupChat: {
mentionPatterns: ["@openclaw", "openclaw", "\\+15555550123"],
historyLimit: 50,
},
},
],
},
}
```
Catatan:
- `mentionPatterns` adalah pola regex aman yang tidak peka huruf besar/kecil; pola yang tidak valid dan bentuk nested-repetition yang tidak aman akan diabaikan.
- Surface yang menyediakan mention eksplisit tetap lolos; pola hanyalah fallback.
- Override per agen: `agents.list[].groupChat.mentionPatterns` (berguna saat beberapa agen berbagi satu grup).
- Gating mention hanya diterapkan ketika deteksi mention memungkinkan (mention native atau `mentionPatterns` dikonfigurasi).
- Default Discord berada di `channels.discord.guilds."*"` (dapat ditimpa per guild/channel).
- Konteks riwayat grup dibungkus secara seragam di seluruh channel dan hanya **pending-only** (pesan yang dilewati karena gating mention); gunakan `messages.groupChat.historyLimit` untuk default global dan `channels.<channel>.historyLimit` (atau `channels.<channel>.accounts.*.historyLimit`) untuk override. Set `0` untuk menonaktifkan.
## Pembatasan alat grup/channel (opsional)
Beberapa config channel mendukung pembatasan alat mana yang tersedia **di dalam grup/room/channel tertentu**.
- `tools`: izinkan/tolak alat untuk seluruh grup.
- `toolsBySender`: override per pengirim di dalam grup.
Gunakan prefiks key eksplisit:
`id:<senderId>`, `e164:<phone>`, `username:<handle>`, `name:<displayName>`, dan wildcard `"*"`.
Key lama tanpa prefiks masih diterima dan hanya dicocokkan sebagai `id:`.
Urutan resolusi (yang paling spesifik menang):
1. kecocokan `toolsBySender` grup/channel
2. `tools` grup/channel
3. kecocokan `toolsBySender` default (`"*"`)
4. `tools` default (`"*"`)
Contoh (Telegram):
```json5
{
channels: {
telegram: {
groups: {
"*": { tools: { deny: ["exec"] } },
"-1001234567890": {
tools: { deny: ["exec", "read", "write"] },
toolsBySender: {
"id:123456789": { alsoAllow: ["exec"] },
},
},
},
},
},
}
```
Catatan:
- Pembatasan alat grup/channel diterapkan sebagai tambahan terhadap kebijakan alat global/agen (deny tetap menang).
- Beberapa channel menggunakan nesting yang berbeda untuk room/channel (misalnya Discord `guilds.*.channels.*`, Slack `channels.*`, Microsoft Teams `teams.*.channels.*`).
## Allowlist grup
Saat `channels.whatsapp.groups`, `channels.telegram.groups`, atau `channels.imessage.groups` dikonfigurasi, key-nya bertindak sebagai allowlist grup. Gunakan `"*"` untuk mengizinkan semua grup sambil tetap mengatur perilaku mention default.
Kebingungan umum: persetujuan pairing DM tidak sama dengan otorisasi grup.
Untuk channel yang mendukung pairing DM, penyimpanan pairing hanya membuka DM. Perintah grup tetap memerlukan otorisasi pengirim grup yang eksplisit dari allowlist config seperti `groupAllowFrom` atau fallback config terdokumentasi untuk channel tersebut.
Maksud umum (salin/tempel):
1. Nonaktifkan semua balasan grup
```json5
{
channels: { whatsapp: { groupPolicy: "disabled" } },
}
```
2. Izinkan hanya grup tertentu (WhatsApp)
```json5
{
channels: {
whatsapp: {
groups: {
"123@g.us": { requireMention: true },
"456@g.us": { requireMention: false },
},
},
},
}
```
3. Izinkan semua grup tetapi wajib mention (eksplisit)
```json5
{
channels: {
whatsapp: {
groups: { "*": { requireMention: true } },
},
},
}
```
4. Hanya pemilik yang dapat memicu di grup (WhatsApp)
```json5
{
channels: {
whatsapp: {
groupPolicy: "allowlist",
groupAllowFrom: ["+15551234567"],
groups: { "*": { requireMention: true } },
},
},
}
```
## Aktivasi (khusus pemilik)
Pemilik grup dapat mengubah aktivasi per grup:
- `/activation mention`
- `/activation always`
Pemilik ditentukan oleh `channels.whatsapp.allowFrom` (atau E.164 milik bot sendiri jika tidak disetel). Kirim perintah sebagai pesan mandiri. Surface lain saat ini mengabaikan `/activation`.
## Field konteks
Payload masuk grup menetapkan:
- `ChatType=group`
- `GroupSubject` (jika diketahui)
- `GroupMembers` (jika diketahui)
- `WasMentioned` (hasil gating mention)
- Topik forum Telegram juga menyertakan `MessageThreadId` dan `IsForum`.
Catatan khusus channel:
- BlueBubbles secara opsional dapat memperkaya peserta grup macOS tanpa nama dari database Kontak lokal sebelum mengisi `GroupMembers`. Ini nonaktif secara default dan hanya berjalan setelah gating grup normal lolos.
System prompt agen menyertakan pengantar grup pada giliran pertama dari sesi grup baru. Ini mengingatkan model agar merespons seperti manusia, menghindari tabel Markdown, dan menghindari mengetik urutan literal `\n`.
## Hal spesifik iMessage
- Pilih `chat_id:<id>` saat routing atau membuat allowlist.
- Daftar obrolan: `imsg chats --limit 20`.
- Balasan grup selalu kembali ke `chat_id` yang sama.
## Hal spesifik WhatsApp
Lihat [Pesan grup](/channels/group-messages) untuk perilaku khusus WhatsApp (injeksi riwayat, detail penanganan mention).

434
docs/id/channels/imessage.md Normal file
View File

@ -0,0 +1,434 @@
---
read_when:
- Menyiapkan dukungan iMessage
- Men-debug kirim/terima iMessage
summary: Dukungan iMessage lama melalui imsg (JSON-RPC melalui stdio). Penyiapan baru sebaiknya menggunakan BlueBubbles.
title: iMessage
x-i18n:
generated_at: "2026-04-05T13:43:28Z"
model: gpt-5.4
provider: openai
source_hash: 086d85bead49f75d12ae6b14ac917af52375b6afd28f6af1a0dcbbc7fcb628a0
source_path: channels/imessage.md
workflow: 15
---
# iMessage (lama: imsg)
<Warning>
Untuk deployment iMessage baru, gunakan <a href="/channels/bluebubbles">BlueBubbles</a>.
Integrasi `imsg` adalah versi lama dan mungkin akan dihapus pada rilis mendatang.
</Warning>
Status: integrasi CLI eksternal versi lama. Gateway memunculkan `imsg rpc` dan berkomunikasi melalui JSON-RPC di stdio (tanpa daemon/port terpisah).
<CardGroup cols={3}>
<Card title="BlueBubbles (direkomendasikan)" icon="message-circle" href="/channels/bluebubbles">
Jalur iMessage yang diprioritaskan untuk penyiapan baru.
</Card>
<Card title="Pairing" icon="link" href="/channels/pairing">
DM iMessage secara default menggunakan mode pairing.
</Card>
<Card title="Referensi konfigurasi" icon="settings" href="/gateway/configuration-reference#imessage">
Referensi lengkap field iMessage.
</Card>
</CardGroup>
## Penyiapan cepat
<Tabs>
<Tab title="Mac lokal (jalur cepat)">
<Steps>
<Step title="Instal dan verifikasi imsg">
```bash
brew install steipete/tap/imsg
imsg rpc --help
```
</Step>
<Step title="Konfigurasikan OpenClaw">
```json5
{
channels: {
imessage: {
enabled: true,
cliPath: "/usr/local/bin/imsg",
dbPath: "/Users/<you>/Library/Messages/chat.db",
},
},
}
```
</Step>
<Step title="Mulai gateway">
```bash
openclaw gateway
```
</Step>
<Step title="Setujui pairing DM pertama (dmPolicy default)">
```bash
openclaw pairing list imessage
openclaw pairing approve imessage <CODE>
```
Permintaan pairing kedaluwarsa setelah 1 jam.
</Step>
</Steps>
</Tab>
<Tab title="Mac jarak jauh melalui SSH">
OpenClaw hanya memerlukan `cliPath` yang kompatibel dengan stdio, jadi Anda dapat mengarahkan `cliPath` ke skrip pembungkus yang melakukan SSH ke Mac jarak jauh dan menjalankan `imsg`.
```bash
#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"
```
Konfigurasi yang direkomendasikan saat lampiran diaktifkan:
```json5
{
channels: {
imessage: {
enabled: true,
cliPath: "~/.openclaw/scripts/imsg-ssh",
remoteHost: "user@gateway-host", // digunakan untuk pengambilan lampiran melalui SCP
includeAttachments: true,
// Opsional: timpa root lampiran yang diizinkan.
// Default mencakup /Users/*/Library/Messages/Attachments
attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
},
},
}
```
Jika `remoteHost` tidak diatur, OpenClaw mencoba mendeteksinya secara otomatis dengan mem-parsing skrip pembungkus SSH.
`remoteHost` harus berupa `host` atau `user@host` (tanpa spasi atau opsi SSH).
OpenClaw menggunakan pemeriksaan host-key ketat untuk SCP, jadi host key relay harus sudah ada di `~/.ssh/known_hosts`.
Path lampiran divalidasi terhadap root yang diizinkan (`attachmentRoots` / `remoteAttachmentRoots`).
</Tab>
</Tabs>
## Persyaratan dan izin (macOS)
- Messages harus sudah login di Mac yang menjalankan `imsg`.
- Full Disk Access diperlukan untuk konteks proses yang menjalankan OpenClaw/`imsg` (akses DB Messages).
- Izin Automation diperlukan untuk mengirim pesan melalui Messages.app.
<Tip>
Izin diberikan per konteks proses. Jika gateway berjalan headless (LaunchAgent/SSH), jalankan satu perintah interaktif sekali dalam konteks yang sama untuk memicu prompt:
```bash
imsg chats --limit 1
# atau
imsg send <handle> "test"
```
</Tip>
## Kontrol akses dan perutean
<Tabs>
<Tab title="Kebijakan DM">
`channels.imessage.dmPolicy` mengontrol pesan langsung:
- `pairing` (default)
- `allowlist`
- `open` (mengharuskan `allowFrom` menyertakan `"*"`)
- `disabled`
Field allowlist: `channels.imessage.allowFrom`.
Entri allowlist dapat berupa handle atau target chat (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`).
</Tab>
<Tab title="Kebijakan grup + mention">
`channels.imessage.groupPolicy` mengontrol penanganan grup:
- `allowlist` (default saat dikonfigurasi)
- `open`
- `disabled`
Allowlist pengirim grup: `channels.imessage.groupAllowFrom`.
Fallback runtime: jika `groupAllowFrom` tidak diatur, pemeriksaan pengirim grup iMessage akan fallback ke `allowFrom` jika tersedia.
Catatan runtime: jika `channels.imessage` sama sekali tidak ada, runtime fallback ke `groupPolicy="allowlist"` dan mencatat peringatan (bahkan jika `channels.defaults.groupPolicy` diatur).
Penyaringan mention untuk grup:
- iMessage tidak memiliki metadata mention bawaan
- deteksi mention menggunakan pola regex (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`)
- tanpa pola yang dikonfigurasi, penyaringan mention tidak dapat diberlakukan
Perintah kontrol dari pengirim yang diotorisasi dapat melewati penyaringan mention di grup.
</Tab>
<Tab title="Sesi dan balasan deterministik">
- DM menggunakan perutean langsung; grup menggunakan perutean grup.
- Dengan default `session.dmScope=main`, DM iMessage digabungkan ke sesi utama agen.
- Sesi grup diisolasi (`agent:<agentId>:imessage:group:<chat_id>`).
- Balasan dirutekan kembali ke iMessage menggunakan metadata channel/target asal.
Perilaku thread mirip grup:
Beberapa thread iMessage multi-peserta dapat datang dengan `is_group=false`.
Jika `chat_id` tersebut dikonfigurasi secara eksplisit di bawah `channels.imessage.groups`, OpenClaw memperlakukannya sebagai lalu lintas grup (penyaringan grup + isolasi sesi grup).
</Tab>
</Tabs>
## Binding percakapan ACP
Chat iMessage versi lama juga dapat diikat ke sesi ACP.
Alur operator cepat:
- Jalankan `/acp spawn codex --bind here` di dalam DM atau chat grup yang diizinkan.
- Pesan berikutnya di percakapan iMessage yang sama akan dirutekan ke sesi ACP yang dimunculkan.
- `/new` dan `/reset` mengatur ulang sesi ACP terikat yang sama di tempat.
- `/acp close` menutup sesi ACP dan menghapus binding.
Binding persisten yang dikonfigurasi didukung melalui entri `bindings[]` tingkat atas dengan `type: "acp"` dan `match.channel: "imessage"`.
`match.peer.id` dapat menggunakan:
- handle DM yang dinormalisasi seperti `+15555550123` atau `user@example.com`
- `chat_id:<id>` (direkomendasikan untuk binding grup yang stabil)
- `chat_guid:<guid>`
- `chat_identifier:<identifier>`
Contoh:
```json5
{
agents: {
list: [
{
id: "codex",
runtime: {
type: "acp",
acp: { agent: "codex", backend: "acpx", mode: "persistent" },
},
},
],
},
bindings: [
{
type: "acp",
agentId: "codex",
match: {
channel: "imessage",
accountId: "default",
peer: { kind: "group", id: "chat_id:123" },
},
acp: { label: "codex-group" },
},
],
}
```
Lihat [ACP Agents](/tools/acp-agents) untuk perilaku binding ACP bersama.
## Pola deployment
<AccordionGroup>
<Accordion title="Pengguna bot macOS khusus (identitas iMessage terpisah)">
Gunakan Apple ID dan pengguna macOS khusus agar lalu lintas bot terisolasi dari profil Messages pribadi Anda.
Alur umum:
1. Buat/login pengguna macOS khusus.
2. Login ke Messages dengan Apple ID bot pada pengguna tersebut.
3. Instal `imsg` pada pengguna tersebut.
4. Buat pembungkus SSH agar OpenClaw dapat menjalankan `imsg` dalam konteks pengguna tersebut.
5. Arahkan `channels.imessage.accounts.<id>.cliPath` dan `.dbPath` ke profil pengguna tersebut.
Eksekusi pertama mungkin memerlukan persetujuan GUI (Automation + Full Disk Access) pada sesi pengguna bot tersebut.
</Accordion>
<Accordion title="Mac jarak jauh melalui Tailscale (contoh)">
Topologi umum:
- gateway berjalan di Linux/VM
- iMessage + `imsg` berjalan di Mac dalam tailnet Anda
- pembungkus `cliPath` menggunakan SSH untuk menjalankan `imsg`
- `remoteHost` mengaktifkan pengambilan lampiran melalui SCP
Contoh:
```json5
{
channels: {
imessage: {
enabled: true,
cliPath: "~/.openclaw/scripts/imsg-ssh",
remoteHost: "bot@mac-mini.tailnet-1234.ts.net",
includeAttachments: true,
dbPath: "/Users/bot/Library/Messages/chat.db",
},
},
}
```
```bash
#!/usr/bin/env bash
exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"
```
Gunakan SSH key agar SSH dan SCP sama-sama non-interaktif.
Pastikan host key sudah dipercaya terlebih dahulu (misalnya `ssh bot@mac-mini.tailnet-1234.ts.net`) agar `known_hosts` terisi.
</Accordion>
<Accordion title="Pola multi-akun">
iMessage mendukung konfigurasi per akun di bawah `channels.imessage.accounts`.
Setiap akun dapat menimpa field seperti `cliPath`, `dbPath`, `allowFrom`, `groupPolicy`, `mediaMaxMb`, pengaturan riwayat, dan allowlist root lampiran.
</Accordion>
</AccordionGroup>
## Media, pemotongan, dan target pengiriman
<AccordionGroup>
<Accordion title="Lampiran dan media">
- ingest lampiran masuk bersifat opsional: `channels.imessage.includeAttachments`
- path lampiran jarak jauh dapat diambil melalui SCP saat `remoteHost` diatur
- path lampiran harus cocok dengan root yang diizinkan:
- `channels.imessage.attachmentRoots` (lokal)
- `channels.imessage.remoteAttachmentRoots` (mode SCP jarak jauh)
- pola root default: `/Users/*/Library/Messages/Attachments`
- SCP menggunakan pemeriksaan host-key ketat (`StrictHostKeyChecking=yes`)
- ukuran media keluar menggunakan `channels.imessage.mediaMaxMb` (default 16 MB)
</Accordion>
<Accordion title="Pemotongan keluar">
- batas potongan teks: `channels.imessage.textChunkLimit` (default 4000)
- mode potongan: `channels.imessage.chunkMode`
- `length` (default)
- `newline` (pemisahan dengan paragraf terlebih dahulu)
</Accordion>
<Accordion title="Format pengalamatan">
Target eksplisit yang direkomendasikan:
- `chat_id:123` (direkomendasikan untuk perutean yang stabil)
- `chat_guid:...`
- `chat_identifier:...`
Target handle juga didukung:
- `imessage:+1555...`
- `sms:+1555...`
- `user@example.com`
```bash
imsg chats --limit 20
```
</Accordion>
</AccordionGroup>
## Penulisan konfigurasi
iMessage mengizinkan penulisan konfigurasi yang dimulai dari channel secara default (untuk `/config set|unset` saat `commands.config: true`).
Nonaktifkan:
```json5
{
channels: {
imessage: {
configWrites: false,
},
},
}
```
## Pemecahan masalah
<AccordionGroup>
<Accordion title="imsg tidak ditemukan atau RPC tidak didukung">
Validasi biner dan dukungan RPC:
```bash
imsg rpc --help
openclaw channels status --probe
```
Jika probe melaporkan RPC tidak didukung, perbarui `imsg`.
</Accordion>
<Accordion title="DM diabaikan">
Periksa:
- `channels.imessage.dmPolicy`
- `channels.imessage.allowFrom`
- persetujuan pairing (`openclaw pairing list imessage`)
</Accordion>
<Accordion title="Pesan grup diabaikan">
Periksa:
- `channels.imessage.groupPolicy`
- `channels.imessage.groupAllowFrom`
- perilaku allowlist `channels.imessage.groups`
- konfigurasi pola mention (`agents.list[].groupChat.mentionPatterns`)
</Accordion>
<Accordion title="Lampiran jarak jauh gagal">
Periksa:
- `channels.imessage.remoteHost`
- `channels.imessage.remoteAttachmentRoots`
- autentikasi key SSH/SCP dari host gateway
- host key ada di `~/.ssh/known_hosts` pada host gateway
- keterbacaan path jarak jauh pada Mac yang menjalankan Messages
</Accordion>
<Accordion title="Prompt izin macOS terlewat">
Jalankan ulang di terminal GUI interaktif dalam konteks pengguna/sesi yang sama dan setujui prompt:
```bash
imsg chats --limit 1
imsg send <handle> "test"
```
Pastikan Full Disk Access + Automation telah diberikan untuk konteks proses yang menjalankan OpenClaw/`imsg`.
</Accordion>
</AccordionGroup>
## Penunjuk referensi konfigurasi
- [Referensi konfigurasi - iMessage](/gateway/configuration-reference#imessage)
- [Konfigurasi gateway](/gateway/configuration)
- [Pairing](/channels/pairing)
- [BlueBubbles](/channels/bluebubbles)
## Terkait
- [Ikhtisar Channel](/channels) — semua channel yang didukung
- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing
- [Grup](/channels/groups) — perilaku chat grup dan penyaringan mention
- [Perutean Channel](/channels/channel-routing) — perutean sesi untuk pesan
- [Keamanan](/gateway/security) — model akses dan hardening

57
docs/id/channels/index.md Normal file
View File

@ -0,0 +1,57 @@
---
read_when:
- Anda ingin memilih chat channel untuk OpenClaw
- Anda memerlukan ikhtisar singkat tentang platform perpesanan yang didukung
summary: Platform perpesanan yang dapat dihubungkan dengan OpenClaw
title: Chat Channels
x-i18n:
generated_at: "2026-04-05T13:43:03Z"
model: gpt-5.4
provider: openai
source_hash: 246ee6f16aebe751241f00102bb435978ed21f6158385aff5d8e222e30567416
source_path: channels/index.md
workflow: 15
---
# Chat Channels
OpenClaw dapat berbicara dengan Anda di aplikasi chat apa pun yang sudah Anda gunakan. Setiap channel terhubung melalui Gateway.
Teks didukung di semua tempat; media dan reaksi berbeda-beda menurut channel.
## Channel yang didukung
- [BlueBubbles](/channels/bluebubbles) — **Direkomendasikan untuk iMessage**; menggunakan REST API server macOS BlueBubbles dengan dukungan fitur penuh (plugin bawaan; edit, unsend, efek, reaksi, manajemen grup — edit saat ini rusak di macOS 26 Tahoe).
- [Discord](/channels/discord) — Discord Bot API + Gateway; mendukung server, channel, dan DM.
- [Feishu](/channels/feishu) — Bot Feishu/Lark melalui WebSocket (plugin bawaan).
- [Google Chat](/channels/googlechat) — Aplikasi Google Chat API melalui webhook HTTP.
- [iMessage (lama)](/channels/imessage) — Integrasi macOS lama melalui CLI imsg (tidak digunakan lagi, gunakan BlueBubbles untuk penyiapan baru).
- [IRC](/channels/irc) — Server IRC klasik; channel + DM dengan kontrol pairing/allowlist.
- [LINE](/channels/line) — Bot LINE Messaging API (plugin bawaan).
- [Matrix](/channels/matrix) — Protokol Matrix (plugin bawaan).
- [Mattermost](/channels/mattermost) — Bot API + WebSocket; channel, grup, DM (plugin bawaan).
- [Microsoft Teams](/channels/msteams) — Bot Framework; dukungan enterprise (plugin bawaan).
- [Nextcloud Talk](/channels/nextcloud-talk) — Chat self-hosted melalui Nextcloud Talk (plugin bawaan).
- [Nostr](/channels/nostr) — DM terdesentralisasi melalui NIP-04 (plugin bawaan).
- [QQ Bot](/channels/qqbot) — QQ Bot API; chat privat, chat grup, dan media kaya (plugin bawaan).
- [Signal](/channels/signal) — signal-cli; berfokus pada privasi.
- [Slack](/channels/slack) — Bolt SDK; aplikasi workspace.
- [Synology Chat](/channels/synology-chat) — Chat Synology NAS melalui webhook keluar+masuk (plugin bawaan).
- [Telegram](/channels/telegram) — Bot API melalui grammY; mendukung grup.
- [Tlon](/channels/tlon) — Messenger berbasis Urbit (plugin bawaan).
- [Twitch](/channels/twitch) — Chat Twitch melalui koneksi IRC (plugin bawaan).
- [Voice Call](/plugins/voice-call) — Telepon melalui Plivo atau Twilio (plugin, dipasang secara terpisah).
- [WebChat](/web/webchat) — UI Gateway WebChat melalui WebSocket.
- [WeChat](https://www.npmjs.com/package/@tencent-weixin/openclaw-weixin) — Plugin Tencent iLink Bot melalui login QR; hanya chat privat.
- [WhatsApp](/channels/whatsapp) — Paling populer; menggunakan Baileys dan memerlukan pairing QR.
- [Zalo](/channels/zalo) — Zalo Bot API; messenger populer di Vietnam (plugin bawaan).
- [Zalo Personal](/channels/zalouser) — Akun pribadi Zalo melalui login QR (plugin bawaan).
## Catatan
- Channel dapat berjalan secara bersamaan; konfigurasikan beberapa channel dan OpenClaw akan melakukan routing per chat.
- Penyiapan tercepat biasanya **Telegram** (token bot sederhana). WhatsApp memerlukan pairing QR dan
menyimpan lebih banyak status di disk.
- Perilaku grup berbeda-beda menurut channel; lihat [Groups](/channels/groups).
- Pairing DM dan allowlist diterapkan demi keamanan; lihat [Security](/gateway/security).
- Pemecahan masalah: [Pemecahan masalah channel](/channels/troubleshooting).
- Provider model didokumentasikan secara terpisah; lihat [Model Providers](/providers/models).

259
docs/id/channels/irc.md Normal file
View File

@ -0,0 +1,259 @@
---
read_when:
- Anda ingin menghubungkan OpenClaw ke channel IRC atau DM
- Anda sedang mengonfigurasi allowlist IRC, kebijakan grup, atau gating mention
summary: Penyiapan plugin IRC, kontrol akses, dan pemecahan masalah
title: IRC
x-i18n:
generated_at: "2026-04-05T13:43:16Z"
model: gpt-5.4
provider: openai
source_hash: fceab2979db72116689c6c774d6736a8a2eee3559e3f3cf8969e673d317edd94
source_path: channels/irc.md
workflow: 15
---
# IRC
Gunakan IRC saat Anda ingin OpenClaw berada di channel klasik (`#room`) dan direct message.
IRC dikirim sebagai extension plugin, tetapi dikonfigurasi di config utama di bawah `channels.irc`.
## Mulai cepat
1. Aktifkan config IRC di `~/.openclaw/openclaw.json`.
2. Setidaknya atur:
```json5
{
channels: {
irc: {
enabled: true,
host: "irc.example.com",
port: 6697,
tls: true,
nick: "openclaw-bot",
channels: ["#openclaw"],
},
},
}
```
Utamakan server IRC privat untuk koordinasi bot. Jika Anda sengaja menggunakan jaringan IRC publik, pilihan umum mencakup Libera.Chat, OFTC, dan Snoonet. Hindari channel publik yang mudah ditebak untuk lalu lintas backchannel bot atau swarm.
3. Mulai/restart gateway:
```bash
openclaw gateway run
```
## Default keamanan
- `channels.irc.dmPolicy` default ke `"pairing"`.
- `channels.irc.groupPolicy` default ke `"allowlist"`.
- Dengan `groupPolicy="allowlist"`, atur `channels.irc.groups` untuk menentukan channel yang diizinkan.
- Gunakan TLS (`channels.irc.tls=true`) kecuali Anda memang sengaja menerima transport plaintext.
## Kontrol akses
Ada dua “gate” terpisah untuk channel IRC:
1. **Akses channel** (`groupPolicy` + `groups`): apakah bot menerima pesan dari suatu channel sama sekali.
2. **Akses pengirim** (`groupAllowFrom` / per-channel `groups["#channel"].allowFrom`): siapa yang diizinkan memicu bot di dalam channel tersebut.
Kunci config:
- Allowlist DM (akses pengirim DM): `channels.irc.allowFrom`
- Allowlist pengirim grup (akses pengirim channel): `channels.irc.groupAllowFrom`
- Kontrol per-channel (channel + pengirim + aturan mention): `channels.irc.groups["#channel"]`
- `channels.irc.groupPolicy="open"` mengizinkan channel yang tidak dikonfigurasi (**tetap di-gate oleh mention secara default**)
Entri allowlist sebaiknya menggunakan identitas pengirim yang stabil (`nick!user@host`).
Pencocokan nick polos dapat berubah-ubah dan hanya diaktifkan saat `channels.irc.dangerouslyAllowNameMatching: true`.
### Jebakan umum: `allowFrom` untuk DM, bukan channel
Jika Anda melihat log seperti:
- `irc: drop group sender alice!ident@host (policy=allowlist)`
...artinya pengirim tidak diizinkan untuk pesan **grup/channel**. Perbaiki dengan salah satu cara berikut:
- mengatur `channels.irc.groupAllowFrom` (global untuk semua channel), atau
- mengatur allowlist pengirim per-channel: `channels.irc.groups["#channel"].allowFrom`
Contoh (izinkan siapa pun di `#tuirc-dev` berbicara dengan bot):
```json5
{
channels: {
irc: {
groupPolicy: "allowlist",
groups: {
"#tuirc-dev": { allowFrom: ["*"] },
},
},
},
}
```
## Pemicu balasan (mention)
Walaupun suatu channel diizinkan (melalui `groupPolicy` + `groups`) dan pengirim diizinkan, OpenClaw secara default menggunakan **gating mention** dalam konteks grup.
Artinya Anda mungkin melihat log seperti `drop channel … (missing-mention)` kecuali pesan menyertakan pola mention yang cocok dengan bot.
Untuk membuat bot membalas di channel IRC **tanpa memerlukan mention**, nonaktifkan gating mention untuk channel tersebut:
```json5
{
channels: {
irc: {
groupPolicy: "allowlist",
groups: {
"#tuirc-dev": {
requireMention: false,
allowFrom: ["*"],
},
},
},
},
}
```
Atau untuk mengizinkan **semua** channel IRC (tanpa allowlist per-channel) dan tetap membalas tanpa mention:
```json5
{
channels: {
irc: {
groupPolicy: "open",
groups: {
"*": { requireMention: false, allowFrom: ["*"] },
},
},
},
}
```
## Catatan keamanan (disarankan untuk channel publik)
Jika Anda mengizinkan `allowFrom: ["*"]` di channel publik, siapa pun dapat memberi prompt ke bot.
Untuk mengurangi risiko, batasi tools untuk channel tersebut.
### Tools yang sama untuk semua orang di channel
```json5
{
channels: {
irc: {
groups: {
"#tuirc-dev": {
allowFrom: ["*"],
tools: {
deny: ["group:runtime", "group:fs", "gateway", "nodes", "cron", "browser"],
},
},
},
},
},
}
```
### Tools berbeda per pengirim (pemilik mendapat lebih banyak kuasa)
Gunakan `toolsBySender` untuk menerapkan kebijakan yang lebih ketat ke `"*"` dan yang lebih longgar ke nick Anda:
```json5
{
channels: {
irc: {
groups: {
"#tuirc-dev": {
allowFrom: ["*"],
toolsBySender: {
"*": {
deny: ["group:runtime", "group:fs", "gateway", "nodes", "cron", "browser"],
},
"id:eigen": {
deny: ["gateway", "nodes", "cron"],
},
},
},
},
},
},
}
```
Catatan:
- Kunci `toolsBySender` sebaiknya menggunakan `id:` untuk nilai identitas pengirim IRC:
`id:eigen` atau `id:eigen!~eigen@174.127.248.171` untuk pencocokan yang lebih kuat.
- Kunci lama tanpa prefiks masih diterima dan hanya dicocokkan sebagai `id:`.
- Kebijakan pengirim pertama yang cocok akan menang; `"*"` adalah fallback wildcard.
Untuk informasi lebih lanjut tentang akses grup vs gating mention (dan bagaimana keduanya berinteraksi), lihat: [/channels/groups](/channels/groups).
## NickServ
Untuk mengidentifikasi diri ke NickServ setelah terhubung:
```json5
{
channels: {
irc: {
nickserv: {
enabled: true,
service: "NickServ",
password: "your-nickserv-password",
},
},
},
}
```
Registrasi satu kali opsional saat terhubung:
```json5
{
channels: {
irc: {
nickserv: {
register: true,
registerEmail: "bot@example.com",
},
},
},
}
```
Nonaktifkan `register` setelah nick terdaftar agar tidak terjadi percobaan REGISTER berulang.
## Variabel lingkungan
Akun default mendukung:
- `IRC_HOST`
- `IRC_PORT`
- `IRC_TLS`
- `IRC_NICK`
- `IRC_USERNAME`
- `IRC_REALNAME`
- `IRC_PASSWORD`
- `IRC_CHANNELS` (dipisahkan dengan koma)
- `IRC_NICKSERV_PASSWORD`
- `IRC_NICKSERV_REGISTER_EMAIL`
## Pemecahan masalah
- Jika bot terhubung tetapi tidak pernah membalas di channel, verifikasi `channels.irc.groups` **dan** apakah gating mention membuang pesan (`missing-mention`). Jika Anda ingin bot membalas tanpa ping, set `requireMention:false` untuk channel tersebut.
- Jika login gagal, verifikasi ketersediaan nick dan kata sandi server.
- Jika TLS gagal pada jaringan kustom, verifikasi host/port dan penyiapan sertifikat.
## Terkait
- [Ringkasan Channel](/channels) — semua channel yang didukung
- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing
- [Groups](/channels/groups) — perilaku obrolan grup dan gating mention
- [Channel Routing](/channels/channel-routing) — perutean sesi untuk pesan
- [Keamanan](/gateway/security) — model akses dan hardening

232
docs/id/channels/line.md Normal file
View File

@ -0,0 +1,232 @@
---
read_when:
- Anda ingin menghubungkan OpenClaw ke LINE
- Anda memerlukan penyiapan webhook + kredensial LINE
- Anda menginginkan opsi pesan khusus LINE
summary: Penyiapan, config, dan penggunaan plugin LINE Messaging API
title: LINE
x-i18n:
generated_at: "2026-04-05T13:43:23Z"
model: gpt-5.4
provider: openai
source_hash: b4782b2aa3e8654505d7f1fd6fc112adf125b5010fc84d655d033688ded37414
source_path: channels/line.md
workflow: 15
---
# LINE
LINE terhubung ke OpenClaw melalui LINE Messaging API. Plugin berjalan sebagai
penerima webhook di gateway dan menggunakan token akses channel + rahasia channel Anda untuk
autentikasi.
Status: plugin bawaan. Direct message, obrolan grup, media, lokasi, pesan Flex,
pesan template, dan quick reply didukung. Reactions dan thread
tidak didukung.
## Plugin bawaan
LINE dikirim sebagai plugin bawaan dalam rilis OpenClaw saat ini, jadi build
terpaket normal tidak memerlukan instalasi terpisah.
Jika Anda menggunakan build lama atau instalasi kustom yang tidak menyertakan LINE, instal
secara manual:
```bash
openclaw plugins install @openclaw/line
```
Checkout lokal (saat berjalan dari repo git):
```bash
openclaw plugins install ./path/to/local/line-plugin
```
## Penyiapan
1. Buat akun LINE Developers dan buka Console:
[https://developers.line.biz/console/](https://developers.line.biz/console/)
2. Buat (atau pilih) Provider dan tambahkan channel **Messaging API**.
3. Salin **Channel access token** dan **Channel secret** dari pengaturan channel.
4. Aktifkan **Use webhook** di pengaturan Messaging API.
5. Atur URL webhook ke endpoint gateway Anda (HTTPS wajib):
```
https://gateway-host/line/webhook
```
Gateway merespons verifikasi webhook LINE (GET) dan peristiwa masuk (POST).
Jika Anda memerlukan path kustom, atur `channels.line.webhookPath` atau
`channels.line.accounts.<id>.webhookPath` dan perbarui URL sesuai kebutuhan.
Catatan keamanan:
- Verifikasi signature LINE bergantung pada body (HMAC atas body mentah), jadi OpenClaw menerapkan batas body pra-autentikasi yang ketat dan timeout sebelum verifikasi.
- OpenClaw memproses peristiwa webhook dari byte permintaan mentah yang telah diverifikasi. Nilai `req.body` yang diubah oleh middleware upstream diabaikan demi keamanan integritas signature.
## Konfigurasi
Config minimal:
```json5
{
channels: {
line: {
enabled: true,
channelAccessToken: "LINE_CHANNEL_ACCESS_TOKEN",
channelSecret: "LINE_CHANNEL_SECRET",
dmPolicy: "pairing",
},
},
}
```
Variabel env (hanya akun default):
- `LINE_CHANNEL_ACCESS_TOKEN`
- `LINE_CHANNEL_SECRET`
File token/secret:
```json5
{
channels: {
line: {
tokenFile: "/path/to/line-token.txt",
secretFile: "/path/to/line-secret.txt",
},
},
}
```
`tokenFile` dan `secretFile` harus menunjuk ke file reguler. Symlink ditolak.
Beberapa akun:
```json5
{
channels: {
line: {
accounts: {
marketing: {
channelAccessToken: "...",
channelSecret: "...",
webhookPath: "/line/marketing",
},
},
},
},
}
```
## Kontrol akses
Direct message secara default menggunakan pairing. Pengirim yang tidak dikenal akan mendapatkan kode pairing dan
pesannya diabaikan sampai disetujui.
```bash
openclaw pairing list line
openclaw pairing approve line <CODE>
```
Allowlist dan kebijakan:
- `channels.line.dmPolicy`: `pairing | allowlist | open | disabled`
- `channels.line.allowFrom`: ID pengguna LINE yang masuk allowlist untuk DM
- `channels.line.groupPolicy`: `allowlist | open | disabled`
- `channels.line.groupAllowFrom`: ID pengguna LINE yang masuk allowlist untuk grup
- Override per grup: `channels.line.groups.<groupId>.allowFrom`
- Catatan runtime: jika `channels.line` tidak ada sama sekali, runtime akan fallback ke `groupPolicy="allowlist"` untuk pemeriksaan grup (bahkan jika `channels.defaults.groupPolicy` diatur).
ID LINE peka huruf besar/kecil. ID yang valid terlihat seperti:
- Pengguna: `U` + 32 karakter hex
- Grup: `C` + 32 karakter hex
- Room: `R` + 32 karakter hex
## Perilaku pesan
- Teks dipotong per 5000 karakter.
- Format Markdown dihapus; blok kode dan tabel dikonversi menjadi kartu Flex
jika memungkinkan.
- Respons streaming dibuffer; LINE menerima potongan penuh dengan animasi
loading saat agen bekerja.
- Unduhan media dibatasi oleh `channels.line.mediaMaxMb` (default 10).
## Data channel (pesan kaya)
Gunakan `channelData.line` untuk mengirim quick reply, lokasi, kartu Flex, atau pesan
template.
```json5
{
text: "Here you go",
channelData: {
line: {
quickReplies: ["Status", "Help"],
location: {
title: "Office",
address: "123 Main St",
latitude: 35.681236,
longitude: 139.767125,
},
flexMessage: {
altText: "Status card",
contents: {
/* Flex payload */
},
},
templateMessage: {
type: "confirm",
text: "Proceed?",
confirmLabel: "Yes",
confirmData: "yes",
cancelLabel: "No",
cancelData: "no",
},
},
},
}
```
Plugin LINE juga menyertakan perintah `/card` untuk preset pesan Flex:
```
/card info "Welcome" "Thanks for joining!"
```
## Dukungan ACP
LINE mendukung binding percakapan ACP (Agent Communication Protocol):
- `/acp spawn <agent> --bind here` mengikat obrolan LINE saat ini ke sesi ACP tanpa membuat child thread.
- Binding ACP yang dikonfigurasi dan sesi ACP aktif yang terikat percakapan bekerja di LINE seperti di channel percakapan lainnya.
Lihat [ACP agents](/tools/acp-agents) untuk detail.
## Media keluar
Plugin LINE mendukung pengiriman file gambar, video, dan audio melalui alat pesan agen. Media dikirim melalui jalur pengiriman khusus LINE dengan penanganan pratinjau dan pelacakan yang sesuai:
- **Gambar**: dikirim sebagai pesan gambar LINE dengan pembuatan pratinjau otomatis.
- **Video**: dikirim dengan pratinjau eksplisit dan penanganan content-type.
- **Audio**: dikirim sebagai pesan audio LINE.
Pengiriman media generik akan fallback ke rute khusus gambar yang sudah ada saat jalur khusus LINE tidak tersedia.
## Pemecahan masalah
- **Verifikasi webhook gagal:** pastikan URL webhook menggunakan HTTPS dan
`channelSecret` cocok dengan console LINE.
- **Tidak ada peristiwa masuk:** pastikan path webhook cocok dengan `channels.line.webhookPath`
dan gateway dapat dijangkau dari LINE.
- **Error unduhan media:** tingkatkan `channels.line.mediaMaxMb` jika media melebihi
batas default.
## Terkait
- [Ikhtisar Channels](/channels) — semua channel yang didukung
- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing
- [Groups](/channels/groups) — perilaku obrolan grup dan pembatasan mention
- [Channel Routing](/channels/channel-routing) — perutean sesi untuk pesan
- [Security](/gateway/security) — model akses dan penguatan

63
docs/id/channels/location.md Normal file
View File

@ -0,0 +1,63 @@
---
read_when:
- Menambahkan atau memodifikasi penguraian lokasi channel
- Menggunakan field konteks lokasi dalam prompt agent atau tool
summary: Penguraian lokasi channel masuk (Telegram/WhatsApp/Matrix) dan field konteks
title: Channel Location Parsing
x-i18n:
generated_at: "2026-04-05T13:43:13Z"
model: gpt-5.4
provider: openai
source_hash: 10061f0c109240a9e0bcab649b17f03b674e8bdf410debf3669b7b6da8189d96
source_path: channels/location.md
workflow: 15
---
# Penguraian lokasi channel
OpenClaw menormalkan lokasi bersama dari chat channel menjadi:
- teks yang dapat dibaca manusia yang ditambahkan ke body masuk, dan
- field terstruktur dalam payload konteks balasan otomatis.
Saat ini didukung:
- **Telegram** (pin lokasi + venue + lokasi live)
- **WhatsApp** (`locationMessage` + `liveLocationMessage`)
- **Matrix** (`m.location` dengan `geo_uri`)
## Pemformatan teks
Lokasi dirender sebagai baris yang ramah tanpa tanda kurung:
- Pin:
- `📍 48.858844, 2.294351 ±12m`
- Tempat bernama:
- `📍 Eiffel Tower — Champ de Mars, Paris (48.858844, 2.294351 ±12m)`
- Berbagi live:
- `🛰 Lokasi live: 48.858844, 2.294351 ±12m`
Jika channel menyertakan caption/komentar, itu ditambahkan pada baris berikutnya:
```
📍 48.858844, 2.294351 ±12m
Temui di sini
```
## Field konteks
Saat lokasi ada, field ini ditambahkan ke `ctx`:
- `LocationLat` (angka)
- `LocationLon` (angka)
- `LocationAccuracy` (angka, meter; opsional)
- `LocationName` (string; opsional)
- `LocationAddress` (string; opsional)
- `LocationSource` (`pin | place | live`)
- `LocationIsLive` (boolean)
## Catatan channel
- **Telegram**: venue dipetakan ke `LocationName/LocationAddress`; lokasi live menggunakan `live_period`.
- **WhatsApp**: `locationMessage.comment` dan `liveLocationMessage.caption` ditambahkan sebagai baris caption.
- **Matrix**: `geo_uri` diurai sebagai lokasi pin; ketinggian diabaikan dan `LocationIsLive` selalu false.

870
docs/id/channels/matrix.md Normal file
View File

@ -0,0 +1,870 @@
---
read_when:
- Menyiapkan Matrix di OpenClaw
- Mengonfigurasi Matrix E2EE dan verifikasi
summary: Status dukungan, penyiapan, dan contoh konfigurasi Matrix
title: Matrix
x-i18n:
generated_at: "2026-04-05T13:44:56Z"
model: gpt-5.4
provider: openai
source_hash: ba5c49ad2125d97adf66b5517f8409567eff8b86e20224a32fcb940a02cb0659
source_path: channels/matrix.md
workflow: 15
---
# Matrix
Matrix adalah plugin channel bawaan Matrix untuk OpenClaw.
Plugin ini menggunakan `matrix-js-sdk` resmi dan mendukung DM, room, thread, media, reaksi, polling, lokasi, dan E2EE.
## Plugin bawaan
Matrix dikirim sebagai plugin bawaan dalam rilis OpenClaw saat ini, jadi build
paket normal tidak memerlukan instalasi terpisah.
Jika Anda menggunakan build yang lebih lama atau instalasi kustom yang tidak menyertakan Matrix, instal
secara manual:
Instal dari npm:
```bash
openclaw plugins install @openclaw/matrix
```
Instal dari checkout lokal:
```bash
openclaw plugins install ./path/to/local/matrix-plugin
```
Lihat [Plugins](/tools/plugin) untuk perilaku plugin dan aturan instalasi.
## Penyiapan
1. Pastikan plugin Matrix tersedia.
- Rilis OpenClaw dalam paket saat ini sudah menyertakannya.
- Instalasi lama/kustom dapat menambahkannya secara manual dengan perintah di atas.
2. Buat akun Matrix di homeserver Anda.
3. Konfigurasikan `channels.matrix` dengan salah satu dari:
- `homeserver` + `accessToken`, atau
- `homeserver` + `userId` + `password`.
4. Mulai ulang gateway.
5. Mulai DM dengan bot atau undang bot ke room.
Jalur penyiapan interaktif:
```bash
openclaw channels add
openclaw configure --section channels
```
Yang benar-benar ditanyakan wizard Matrix:
- URL homeserver
- metode auth: access token atau password
- ID pengguna hanya saat Anda memilih auth password
- nama perangkat opsional
- apakah akan mengaktifkan E2EE
- apakah akan mengonfigurasi akses room Matrix sekarang
Perilaku wizard yang penting:
- Jika env var auth Matrix sudah ada untuk akun yang dipilih, dan akun tersebut belum memiliki auth yang tersimpan di config, wizard menawarkan pintasan env dan hanya menulis `enabled: true` untuk akun tersebut.
- Saat Anda menambahkan akun Matrix lain secara interaktif, nama akun yang dimasukkan dinormalisasi menjadi ID akun yang digunakan di config dan env vars. Misalnya, `Ops Bot` menjadi `ops-bot`.
- Prompt allowlist DM langsung menerima nilai `@user:server` penuh. Nama tampilan hanya berfungsi saat lookup direktori langsung menemukan satu kecocokan yang tepat; jika tidak, wizard meminta Anda mencoba lagi dengan ID Matrix penuh.
- Prompt allowlist room menerima ID room dan alias secara langsung. Prompt ini juga dapat meresolusikan nama room yang sudah diikuti secara live, tetapi nama yang tidak teresolusikan hanya dipertahankan sebagaimana diketik saat penyiapan dan diabaikan nanti oleh resolusi allowlist saat runtime. Utamakan `!room:server` atau `#alias:server`.
- Identitas room/sesi saat runtime menggunakan ID room Matrix yang stabil. Alias yang dideklarasikan room hanya digunakan sebagai input lookup, bukan sebagai kunci sesi jangka panjang atau identitas grup yang stabil.
- Untuk meresolusikan nama room sebelum menyimpannya, gunakan `openclaw channels resolve --channel matrix "Project Room"`.
Penyiapan minimal berbasis token:
```json5
{
channels: {
matrix: {
enabled: true,
homeserver: "https://matrix.example.org",
accessToken: "syt_xxx",
dm: { policy: "pairing" },
},
},
}
```
Penyiapan berbasis password (token di-cache setelah login):
```json5
{
channels: {
matrix: {
enabled: true,
homeserver: "https://matrix.example.org",
userId: "@bot:example.org",
password: "replace-me", // pragma: allowlist secret
deviceName: "OpenClaw Gateway",
},
},
}
```
Matrix menyimpan kredensial cache di `~/.openclaw/credentials/matrix/`.
Akun default menggunakan `credentials.json`; akun bernama menggunakan `credentials-<account>.json`.
Padanan variabel environment (digunakan saat kunci config tidak ditetapkan):
- `MATRIX_HOMESERVER`
- `MATRIX_ACCESS_TOKEN`
- `MATRIX_USER_ID`
- `MATRIX_PASSWORD`
- `MATRIX_DEVICE_ID`
- `MATRIX_DEVICE_NAME`
Untuk akun non-default, gunakan env vars dengan cakupan akun:
- `MATRIX_<ACCOUNT_ID>_HOMESERVER`
- `MATRIX_<ACCOUNT_ID>_ACCESS_TOKEN`
- `MATRIX_<ACCOUNT_ID>_USER_ID`
- `MATRIX_<ACCOUNT_ID>_PASSWORD`
- `MATRIX_<ACCOUNT_ID>_DEVICE_ID`
- `MATRIX_<ACCOUNT_ID>_DEVICE_NAME`
Contoh untuk akun `ops`:
- `MATRIX_OPS_HOMESERVER`
- `MATRIX_OPS_ACCESS_TOKEN`
Untuk ID akun yang dinormalisasi `ops-bot`, gunakan:
- `MATRIX_OPS_X2D_BOT_HOMESERVER`
- `MATRIX_OPS_X2D_BOT_ACCESS_TOKEN`
Matrix meng-escape tanda baca dalam ID akun agar env vars bercakupan tetap bebas tabrakan.
Misalnya, `-` menjadi `_X2D_`, sehingga `ops-prod` dipetakan ke `MATRIX_OPS_X2D_PROD_*`.
Wizard interaktif hanya menawarkan pintasan env-var saat env vars auth tersebut sudah ada dan akun yang dipilih belum memiliki auth Matrix yang tersimpan di config.
## Contoh konfigurasi
Ini adalah config baseline praktis dengan pairing DM, allowlist room, dan E2EE diaktifkan:
```json5
{
channels: {
matrix: {
enabled: true,
homeserver: "https://matrix.example.org",
accessToken: "syt_xxx",
encryption: true,
dm: {
policy: "pairing",
threadReplies: "off",
},
groupPolicy: "allowlist",
groupAllowFrom: ["@admin:example.org"],
groups: {
"!roomid:example.org": {
requireMention: true,
},
},
autoJoin: "allowlist",
autoJoinAllowlist: ["!roomid:example.org"],
threadReplies: "inbound",
replyToMode: "off",
streaming: "partial",
},
},
}
```
## Pratinjau streaming
Streaming balasan Matrix bersifat opt-in.
Tetapkan `channels.matrix.streaming` ke `"partial"` saat Anda ingin OpenClaw mengirim satu balasan draf,
mengedit draf tersebut di tempat saat model sedang menghasilkan teks, lalu memfinalkannya ketika balasan
selesai:
```json5
{
channels: {
matrix: {
streaming: "partial",
},
},
}
```
- `streaming: "off"` adalah default. OpenClaw menunggu balasan final dan mengirimnya sekali.
- `streaming: "partial"` membuat satu pesan pratinjau yang dapat diedit untuk blok asisten saat ini alih-alih mengirim beberapa pesan parsial.
- `blockStreaming: true` mengaktifkan pesan progres Matrix terpisah. Dengan `streaming: "partial"`, Matrix mempertahankan draf live untuk blok saat ini dan mempertahankan blok yang sudah selesai sebagai pesan terpisah.
- Saat `streaming: "partial"` dan `blockStreaming` nonaktif, Matrix hanya mengedit draf live dan mengirim balasan lengkap setelah blok atau giliran tersebut selesai.
- Jika pratinjau tidak lagi muat dalam satu event Matrix, OpenClaw menghentikan streaming pratinjau dan kembali ke pengiriman final normal.
- Balasan media tetap mengirim lampiran secara normal. Jika pratinjau lama tidak lagi dapat digunakan kembali dengan aman, OpenClaw meredaksinya sebelum mengirim balasan media final.
- Edit pratinjau memerlukan panggilan API Matrix tambahan. Biarkan streaming nonaktif jika Anda menginginkan perilaku rate-limit yang paling konservatif.
`blockStreaming` tidak dengan sendirinya mengaktifkan pratinjau draf.
Gunakan `streaming: "partial"` untuk edit pratinjau; lalu tambahkan `blockStreaming: true` hanya jika Anda juga ingin blok asisten yang selesai tetap terlihat sebagai pesan progres terpisah.
## Enkripsi dan verifikasi
Di room terenkripsi (E2EE), event gambar keluar menggunakan `thumbnail_file` sehingga pratinjau gambar terenkripsi bersama lampiran penuh. Room yang tidak terenkripsi tetap menggunakan `thumbnail_url` biasa. Tidak diperlukan konfigurasi — plugin mendeteksi status E2EE secara otomatis.
### Room bot ke bot
Secara default, pesan Matrix dari akun Matrix OpenClaw lain yang dikonfigurasi akan diabaikan.
Gunakan `allowBots` saat Anda memang ingin lalu lintas Matrix antar-agen:
```json5
{
channels: {
matrix: {
allowBots: "mentions", // true | "mentions"
groups: {
"!roomid:example.org": {
requireMention: true,
},
},
},
},
}
```
- `allowBots: true` menerima pesan dari akun bot Matrix lain yang dikonfigurasi di room dan DM yang diizinkan.
- `allowBots: "mentions"` menerima pesan tersebut hanya saat pesan secara terlihat me-mention bot ini di room. DM tetap diizinkan.
- `groups.<room>.allowBots` menimpa setelan tingkat akun untuk satu room.
- OpenClaw tetap mengabaikan pesan dari ID pengguna Matrix yang sama untuk menghindari loop balas-diri.
- Matrix tidak mengekspos flag bot native di sini; OpenClaw menganggap "dibuat oleh bot" sebagai "dikirim oleh akun Matrix lain yang dikonfigurasi pada gateway OpenClaw ini".
Gunakan allowlist room yang ketat dan persyaratan mention saat mengaktifkan lalu lintas bot-ke-bot di room bersama.
Aktifkan enkripsi:
```json5
{
channels: {
matrix: {
enabled: true,
homeserver: "https://matrix.example.org",
accessToken: "syt_xxx",
encryption: true,
dm: { policy: "pairing" },
},
},
}
```
Periksa status verifikasi:
```bash
openclaw matrix verify status
```
Status verbose (diagnostik lengkap):
```bash
openclaw matrix verify status --verbose
```
Sertakan recovery key yang tersimpan dalam output yang dapat dibaca mesin:
```bash
openclaw matrix verify status --include-recovery-key --json
```
Bootstrap status cross-signing dan verifikasi:
```bash
openclaw matrix verify bootstrap
```
Dukungan multi-akun: gunakan `channels.matrix.accounts` dengan kredensial per akun dan `name` opsional. Lihat [Referensi konfigurasi](/gateway/configuration-reference#multi-account-all-channels) untuk pola bersama.
Diagnostik bootstrap verbose:
```bash
openclaw matrix verify bootstrap --verbose
```
Paksa reset identitas cross-signing baru sebelum bootstrap:
```bash
openclaw matrix verify bootstrap --force-reset-cross-signing
```
Verifikasi perangkat ini dengan recovery key:
```bash
openclaw matrix verify device "<your-recovery-key>"
```
Detail verifikasi perangkat verbose:
```bash
openclaw matrix verify device "<your-recovery-key>" --verbose
```
Periksa kesehatan backup room-key:
```bash
openclaw matrix verify backup status
```
Diagnostik kesehatan backup verbose:
```bash
openclaw matrix verify backup status --verbose
```
Pulihkan room key dari backup server:
```bash
openclaw matrix verify backup restore
```
Diagnostik pemulihan verbose:
```bash
openclaw matrix verify backup restore --verbose
```
Hapus backup server saat ini dan buat baseline backup baru. Jika backup key yang tersimpan
tidak dapat dimuat dengan bersih, reset ini juga dapat membuat ulang secret storage sehingga
cold start berikutnya dapat memuat backup key yang baru:
```bash
openclaw matrix verify backup reset --yes
```
Semua perintah `verify` ringkas secara default (termasuk logging SDK internal yang sunyi) dan hanya menampilkan diagnostik terperinci dengan `--verbose`.
Gunakan `--json` untuk output lengkap yang dapat dibaca mesin saat scripting.
Dalam penyiapan multi-akun, perintah CLI Matrix menggunakan akun default Matrix implisit kecuali Anda meneruskan `--account <id>`.
Jika Anda mengonfigurasi beberapa akun bernama, tetapkan `channels.matrix.defaultAccount` terlebih dahulu atau operasi CLI implisit tersebut akan berhenti dan meminta Anda memilih akun secara eksplisit.
Gunakan `--account` setiap kali Anda ingin operasi verifikasi atau perangkat menargetkan akun bernama secara eksplisit:
```bash
openclaw matrix verify status --account assistant
openclaw matrix verify backup restore --account assistant
openclaw matrix devices list --account assistant
```
Saat enkripsi dinonaktifkan atau tidak tersedia untuk akun bernama, peringatan Matrix dan error verifikasi menunjuk ke kunci config akun tersebut, misalnya `channels.matrix.accounts.assistant.encryption`.
### Arti "terverifikasi"
OpenClaw menganggap perangkat Matrix ini terverifikasi hanya jika perangkat tersebut diverifikasi oleh identitas cross-signing Anda sendiri.
Dalam praktiknya, `openclaw matrix verify status --verbose` mengekspos tiga sinyal kepercayaan:
- `Locally trusted`: perangkat ini dipercaya hanya oleh klien saat ini
- `Cross-signing verified`: SDK melaporkan perangkat sebagai terverifikasi melalui cross-signing
- `Signed by owner`: perangkat ditandatangani oleh self-signing key milik Anda sendiri
`Verified by owner` menjadi `yes` hanya saat verifikasi cross-signing atau owner-signing ada.
Kepercayaan lokal saja tidak cukup bagi OpenClaw untuk menganggap perangkat sepenuhnya terverifikasi.
### Fungsi bootstrap
`openclaw matrix verify bootstrap` adalah perintah perbaikan dan penyiapan untuk akun Matrix terenkripsi.
Perintah ini melakukan semua hal berikut secara berurutan:
- mem-bootstrap secret storage, menggunakan kembali recovery key yang sudah ada bila memungkinkan
- mem-bootstrap cross-signing dan mengunggah public cross-signing keys yang hilang
- mencoba menandai dan me-cross-sign perangkat saat ini
- membuat backup room-key sisi server baru jika belum ada
Jika homeserver memerlukan auth interaktif untuk mengunggah cross-signing keys, OpenClaw mencoba unggahan tanpa auth terlebih dahulu, lalu dengan `m.login.dummy`, lalu dengan `m.login.password` saat `channels.matrix.password` dikonfigurasi.
Gunakan `--force-reset-cross-signing` hanya saat Anda memang ingin membuang identitas cross-signing saat ini dan membuat yang baru.
Jika Anda memang ingin membuang backup room-key saat ini dan memulai baseline backup
baru untuk pesan mendatang, gunakan `openclaw matrix verify backup reset --yes`.
Lakukan ini hanya jika Anda menerima bahwa riwayat terenkripsi lama yang tidak dapat dipulihkan akan tetap
tidak tersedia dan bahwa OpenClaw dapat membuat ulang secret storage jika secret backup saat ini
tidak dapat dimuat dengan aman.
### Baseline backup baru
Jika Anda ingin menjaga agar pesan terenkripsi di masa depan tetap berfungsi dan menerima kehilangan riwayat lama yang tidak dapat dipulihkan, jalankan perintah ini secara berurutan:
```bash
openclaw matrix verify backup reset --yes
openclaw matrix verify backup status --verbose
openclaw matrix verify status
```
Tambahkan `--account <id>` ke setiap perintah saat Anda ingin secara eksplisit menargetkan akun Matrix bernama.
### Perilaku startup
Saat `encryption: true`, Matrix secara default menetapkan `startupVerification` ke `"if-unverified"`.
Saat startup, jika perangkat ini masih belum terverifikasi, Matrix akan meminta self-verification di klien Matrix lain,
melewati permintaan duplikat saat sudah ada satu yang tertunda, dan menerapkan cooldown lokal sebelum mencoba lagi setelah restart.
Upaya permintaan yang gagal akan mencoba ulang lebih cepat daripada pembuatan permintaan yang berhasil secara default.
Tetapkan `startupVerification: "off"` untuk menonaktifkan permintaan startup otomatis, atau atur `startupVerificationCooldownHours`
jika Anda menginginkan jendela coba ulang yang lebih pendek atau lebih panjang.
Startup juga melakukan pass bootstrap crypto yang konservatif secara otomatis.
Pass tersebut mencoba menggunakan kembali secret storage dan identitas cross-signing saat ini terlebih dahulu, dan menghindari reset cross-signing kecuali Anda menjalankan alur perbaikan bootstrap eksplisit.
Jika startup menemukan status bootstrap yang rusak dan `channels.matrix.password` dikonfigurasi, OpenClaw dapat mencoba jalur perbaikan yang lebih ketat.
Jika perangkat saat ini sudah owner-signed, OpenClaw mempertahankan identitas tersebut alih-alih meresetnya secara otomatis.
Upgrade dari plugin Matrix publik sebelumnya:
- OpenClaw secara otomatis menggunakan kembali akun Matrix, access token, dan identitas perangkat yang sama bila memungkinkan.
- Sebelum perubahan migrasi Matrix yang dapat ditindaklanjuti dijalankan, OpenClaw membuat atau menggunakan kembali snapshot pemulihan di `~/Backups/openclaw-migrations/`.
- Jika Anda menggunakan beberapa akun Matrix, tetapkan `channels.matrix.defaultAccount` sebelum upgrade dari tata letak flat-store lama agar OpenClaw tahu akun mana yang harus menerima status lama bersama tersebut.
- Jika plugin sebelumnya menyimpan decryption key backup room-key Matrix secara lokal, startup atau `openclaw doctor --fix` akan mengimpornya secara otomatis ke alur recovery-key baru.
- Jika access token Matrix berubah setelah migrasi disiapkan, startup sekarang memindai root penyimpanan hash token saudara untuk status restore lama yang tertunda sebelum menyerah pada restore backup otomatis.
- Jika access token Matrix berubah kemudian untuk akun, homeserver, dan pengguna yang sama, OpenClaw sekarang mengutamakan penggunaan kembali root hash token yang paling lengkap alih-alih memulai dari direktori status Matrix kosong.
- Pada startup gateway berikutnya, room key yang telah dibackup dipulihkan secara otomatis ke crypto store baru.
- Jika plugin lama memiliki room key hanya-lokal yang tidak pernah dibackup, OpenClaw akan memberi peringatan dengan jelas. Kunci tersebut tidak dapat diekspor secara otomatis dari rust crypto store sebelumnya, sehingga beberapa riwayat terenkripsi lama mungkin tetap tidak tersedia sampai dipulihkan secara manual.
- Lihat [Migrasi Matrix](/install/migrating-matrix) untuk alur upgrade lengkap, batasan, perintah pemulihan, dan pesan migrasi umum.
Status runtime terenkripsi diatur di bawah root hash token per akun, per pengguna dalam
`~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/`.
Direktori tersebut berisi sync store (`bot-storage.json`), crypto store (`crypto/`),
file recovery key (`recovery-key.json`), snapshot IndexedDB (`crypto-idb-snapshot.json`),
thread bindings (`thread-bindings.json`), dan status verifikasi startup (`startup-verification.json`)
saat fitur-fitur tersebut digunakan.
Ketika token berubah tetapi identitas akun tetap sama, OpenClaw menggunakan kembali root
terbaik yang ada untuk tuple akun/homeserver/pengguna tersebut sehingga status sinkronisasi sebelumnya, status crypto, thread bindings,
dan status verifikasi startup tetap terlihat.
### Model crypto store Node
Matrix E2EE di plugin ini menggunakan jalur Rust crypto `matrix-js-sdk` resmi di Node.
Jalur tersebut mengharapkan persistensi berbasis IndexedDB saat Anda ingin status crypto tetap bertahan setelah restart.
Saat ini OpenClaw menyediakannya di Node dengan cara:
- menggunakan `fake-indexeddb` sebagai shim API IndexedDB yang diharapkan SDK
- memulihkan isi IndexedDB Rust crypto dari `crypto-idb-snapshot.json` sebelum `initRustCrypto`
- mempertahankan isi IndexedDB yang diperbarui kembali ke `crypto-idb-snapshot.json` setelah init dan selama runtime
- menserialisasikan pemulihan dan persist snapshot terhadap `crypto-idb-snapshot.json` dengan advisory file lock agar persistensi runtime gateway dan pemeliharaan CLI tidak saling balapan pada file snapshot yang sama
Ini adalah plumbing kompatibilitas/penyimpanan, bukan implementasi crypto kustom.
File snapshot adalah status runtime sensitif dan disimpan dengan izin file yang ketat.
Dalam model keamanan OpenClaw, host gateway dan direktori status OpenClaw lokal sudah berada di dalam batas operator tepercaya, jadi ini terutama merupakan persoalan durabilitas operasional, bukan batas kepercayaan jarak jauh yang terpisah.
Peningkatan yang direncanakan:
- menambahkan dukungan SecretRef untuk materi key Matrix persisten sehingga recovery key dan secret enkripsi store terkait dapat bersumber dari penyedia secret OpenClaw, bukan hanya file lokal
## Manajemen profil
Perbarui self-profile Matrix untuk akun yang dipilih dengan:
```bash
openclaw matrix profile set --name "OpenClaw Assistant"
openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png
```
Tambahkan `--account <id>` saat Anda ingin secara eksplisit menargetkan akun Matrix bernama.
Matrix menerima URL avatar `mxc://` secara langsung. Saat Anda meneruskan URL avatar `http://` atau `https://`, OpenClaw akan mengunggahnya ke Matrix terlebih dahulu dan menyimpan kembali URL `mxc://` yang sudah diresolusikan ke `channels.matrix.avatarUrl` (atau override akun yang dipilih).
## Pemberitahuan verifikasi otomatis
Matrix sekarang memposting pemberitahuan siklus hidup verifikasi langsung ke room verifikasi DM ketat sebagai pesan `m.notice`.
Ini mencakup:
- pemberitahuan permintaan verifikasi
- pemberitahuan verifikasi siap (dengan panduan eksplisit "Verify by emoji")
- pemberitahuan mulai dan selesai verifikasi
- detail SAS (emoji dan desimal) bila tersedia
Permintaan verifikasi masuk dari klien Matrix lain dilacak dan diterima otomatis oleh OpenClaw.
Untuk alur self-verification, OpenClaw juga memulai alur SAS secara otomatis saat verifikasi emoji tersedia dan mengonfirmasi sisinya sendiri.
Untuk permintaan verifikasi dari pengguna/perangkat Matrix lain, OpenClaw menerima permintaan secara otomatis lalu menunggu alur SAS berjalan secara normal.
Anda tetap perlu membandingkan emoji atau SAS desimal di klien Matrix Anda dan mengonfirmasi "They match" di sana untuk menyelesaikan verifikasi.
OpenClaw tidak menerima otomatis alur duplikat yang dimulai sendiri secara membabi buta. Startup melewati pembuatan permintaan baru saat permintaan self-verification sudah tertunda.
Pemberitahuan protokol/sistem verifikasi tidak diteruskan ke pipeline chat agen, sehingga tidak menghasilkan `NO_REPLY`.
### Kebersihan perangkat
Perangkat Matrix yang dikelola OpenClaw lama dapat menumpuk di akun dan membuat kepercayaan room terenkripsi lebih sulit dipahami.
Daftarkan perangkat tersebut dengan:
```bash
openclaw matrix devices list
```
Hapus perangkat OpenClaw terkelola yang usang dengan:
```bash
openclaw matrix devices prune-stale
```
### Perbaikan Direct Room
Jika status direct-message tidak sinkron, OpenClaw dapat berakhir dengan pemetaan `m.direct` usang yang menunjuk ke room solo lama, bukan DM aktif. Periksa pemetaan saat ini untuk peer dengan:
```bash
openclaw matrix direct inspect --user-id @alice:example.org
```
Perbaiki dengan:
```bash
openclaw matrix direct repair --user-id @alice:example.org
```
Perbaikan menjaga logika khusus Matrix tetap berada di dalam plugin:
- plugin mengutamakan DM 1:1 ketat yang sudah dipetakan di `m.direct`
- jika tidak, plugin kembali ke DM 1:1 ketat mana pun yang saat ini sudah diikuti dengan pengguna tersebut
- jika tidak ada DM sehat, plugin membuat direct room baru dan menulis ulang `m.direct` agar menunjuk ke room tersebut
Alur perbaikan tidak menghapus room lama secara otomatis. Alur ini hanya memilih DM yang sehat dan memperbarui pemetaan agar pengiriman Matrix baru, pemberitahuan verifikasi, dan alur direct-message lainnya kembali menargetkan room yang benar.
## Thread
Matrix mendukung thread Matrix native untuk balasan otomatis dan pengiriman alat pesan.
- `threadReplies: "off"` menjaga balasan tetap di tingkat atas dan menjaga pesan ber-thread masuk tetap pada sesi induk.
- `threadReplies: "inbound"` membalas di dalam thread hanya saat pesan masuk sudah berada di thread tersebut.
- `threadReplies: "always"` menjaga balasan room tetap di thread yang berakar pada pesan pemicu dan merutekan percakapan tersebut melalui sesi bercakupan thread yang cocok dari pesan pemicu pertama.
- `dm.threadReplies` menimpa setelan tingkat atas hanya untuk DM. Misalnya, Anda dapat menjaga thread room tetap terisolasi sambil menjaga DM tetap datar.
- Pesan ber-thread masuk menyertakan pesan akar thread sebagai konteks agen tambahan.
- Pengiriman alat pesan kini otomatis mewarisi thread Matrix saat ini ketika targetnya adalah room yang sama, atau target pengguna DM yang sama, kecuali jika `threadId` eksplisit diberikan.
- Thread bindings saat runtime didukung untuk Matrix. `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, dan `/acp spawn` terikat thread kini berfungsi di room dan DM Matrix.
- `/focus` room/DM Matrix tingkat atas membuat thread Matrix baru dan mengikatnya ke sesi target saat `threadBindings.spawnSubagentSessions=true`.
- Menjalankan `/focus` atau `/acp spawn --thread here` di dalam thread Matrix yang sudah ada akan mengikat thread saat ini sebagai gantinya.
## Binding percakapan ACP
Room, DM, dan thread Matrix yang sudah ada dapat diubah menjadi workspace ACP yang persisten tanpa mengubah permukaan chat.
Alur operator cepat:
- Jalankan `/acp spawn codex --bind here` di dalam DM Matrix, room, atau thread yang sudah ada yang ingin terus Anda gunakan.
- Di DM atau room Matrix tingkat atas, DM/room saat ini tetap menjadi permukaan chat dan pesan berikutnya dirutekan ke sesi ACP yang telah di-spawn.
- Di dalam thread Matrix yang sudah ada, `--bind here` mengikat thread saat ini di tempat.
- `/new` dan `/reset` mereset sesi ACP terikat yang sama di tempat.
- `/acp close` menutup sesi ACP dan menghapus binding.
Catatan:
- `--bind here` tidak membuat thread Matrix turunan.
- `threadBindings.spawnAcpSessions` hanya diperlukan untuk `/acp spawn --thread auto|here`, saat OpenClaw perlu membuat atau mengikat thread Matrix turunan.
### Konfigurasi Thread Binding
Matrix mewarisi default global dari `session.threadBindings`, dan juga mendukung override per channel:
- `threadBindings.enabled`
- `threadBindings.idleHours`
- `threadBindings.maxAgeHours`
- `threadBindings.spawnSubagentSessions`
- `threadBindings.spawnAcpSessions`
Flag spawn terikat thread Matrix bersifat opt-in:
- Tetapkan `threadBindings.spawnSubagentSessions: true` untuk mengizinkan `/focus` tingkat atas membuat dan mengikat thread Matrix baru.
- Tetapkan `threadBindings.spawnAcpSessions: true` untuk mengizinkan `/acp spawn --thread auto|here` mengikat sesi ACP ke thread Matrix.
## Reaksi
Matrix mendukung tindakan reaksi keluar, notifikasi reaksi masuk, dan reaksi ack masuk.
- Tooling reaksi keluar digate oleh `channels["matrix"].actions.reactions`.
- `react` menambahkan reaksi ke event Matrix tertentu.
- `reactions` mencantumkan ringkasan reaksi saat ini untuk event Matrix tertentu.
- `emoji=""` menghapus reaksi milik akun bot sendiri pada event tersebut.
- `remove: true` hanya menghapus reaksi emoji yang ditentukan dari akun bot.
Cakupan reaksi ack diresolusikan dalam urutan standar OpenClaw:
- `channels["matrix"].accounts.<accountId>.ackReaction`
- `channels["matrix"].ackReaction`
- `messages.ackReaction`
- fallback emoji identitas agen
Cakupan reaksi ack diresolusikan dalam urutan ini:
- `channels["matrix"].accounts.<accountId>.ackReactionScope`
- `channels["matrix"].ackReactionScope`
- `messages.ackReactionScope`
Mode notifikasi reaksi diresolusikan dalam urutan ini:
- `channels["matrix"].accounts.<accountId>.reactionNotifications`
- `channels["matrix"].reactionNotifications`
- default: `own`
Perilaku saat ini:
- `reactionNotifications: "own"` meneruskan event `m.reaction` yang ditambahkan saat event tersebut menargetkan pesan Matrix buatan bot.
- `reactionNotifications: "off"` menonaktifkan event sistem reaksi.
- Penghapusan reaksi masih belum disintesis menjadi event sistem karena Matrix menampilkannya sebagai redaksi, bukan sebagai penghapusan `m.reaction` mandiri.
## Konteks riwayat
- `channels.matrix.historyLimit` mengontrol berapa banyak pesan room terbaru yang disertakan sebagai `InboundHistory` saat pesan room Matrix memicu agen.
- Ini kembali ke `messages.groupChat.historyLimit`. Tetapkan `0` untuk menonaktifkan.
- Riwayat room Matrix hanya untuk room. DM tetap menggunakan riwayat sesi normal.
- Riwayat room Matrix bersifat pending-only: OpenClaw men-buffer pesan room yang belum memicu balasan, lalu mengambil snapshot jendela tersebut saat mention atau pemicu lain tiba.
- Pesan pemicu saat ini tidak disertakan dalam `InboundHistory`; pesan tersebut tetap berada di body masuk utama untuk giliran itu.
- Percobaan ulang event Matrix yang sama menggunakan kembali snapshot riwayat asli alih-alih bergeser maju ke pesan room yang lebih baru.
## Visibilitas konteks
Matrix mendukung kontrol `contextVisibility` bersama untuk konteks room tambahan seperti teks balasan yang diambil, akar thread, dan riwayat tertunda.
- `contextVisibility: "all"` adalah default. Konteks tambahan dipertahankan sebagaimana diterima.
- `contextVisibility: "allowlist"` memfilter konteks tambahan ke pengirim yang diizinkan oleh pemeriksaan allowlist room/pengguna aktif.
- `contextVisibility: "allowlist_quote"` berperilaku seperti `allowlist`, tetapi tetap menyimpan satu balasan kutipan eksplisit.
Setelan ini memengaruhi visibilitas konteks tambahan, bukan apakah pesan masuk itu sendiri dapat memicu balasan.
Otorisasi pemicu tetap berasal dari setelan `groupPolicy`, `groups`, `groupAllowFrom`, dan kebijakan DM.
## Contoh kebijakan DM dan room
```json5
{
channels: {
matrix: {
dm: {
policy: "allowlist",
allowFrom: ["@admin:example.org"],
threadReplies: "off",
},
groupPolicy: "allowlist",
groupAllowFrom: ["@admin:example.org"],
groups: {
"!roomid:example.org": {
requireMention: true,
},
},
},
},
}
```
Lihat [Groups](/channels/groups) untuk perilaku penggatingan mention dan allowlist.
Contoh pairing untuk DM Matrix:
```bash
openclaw pairing list matrix
openclaw pairing approve matrix <CODE>
```
Jika pengguna Matrix yang belum disetujui terus mengirim pesan kepada Anda sebelum persetujuan, OpenClaw menggunakan kembali kode pairing tertunda yang sama dan dapat mengirim balasan pengingat lagi setelah cooldown singkat alih-alih mencetak kode baru.
Lihat [Pairing](/channels/pairing) untuk alur pairing DM dan tata letak penyimpanan bersama.
## Persetujuan exec
Matrix dapat bertindak sebagai klien persetujuan exec untuk akun Matrix.
- `channels.matrix.execApprovals.enabled`
- `channels.matrix.execApprovals.approvers` (opsional; kembali ke `channels.matrix.dm.allowFrom`)
- `channels.matrix.execApprovals.target` (`dm` | `channel` | `both`, default: `dm`)
- `channels.matrix.execApprovals.agentFilter`
- `channels.matrix.execApprovals.sessionFilter`
Approver harus berupa ID pengguna Matrix seperti `@owner:example.org`. Matrix otomatis mengaktifkan persetujuan exec native saat `enabled` tidak ditetapkan atau `"auto"` dan setidaknya satu approver dapat diresolusikan, baik dari `execApprovals.approvers` atau dari `channels.matrix.dm.allowFrom`. Tetapkan `enabled: false` untuk menonaktifkan Matrix sebagai klien persetujuan native secara eksplisit. Jika tidak, permintaan persetujuan kembali ke rute persetujuan lain yang dikonfigurasi atau ke kebijakan fallback persetujuan exec.
Perutean native Matrix saat ini hanya untuk exec:
- `channels.matrix.execApprovals.*` mengontrol perutean DM/channel native hanya untuk persetujuan exec.
- Persetujuan plugin tetap menggunakan `/approve` di chat yang sama bersama dengan forwarding `approvals.plugin` yang dikonfigurasi.
- Matrix tetap dapat menggunakan kembali `channels.matrix.dm.allowFrom` untuk otorisasi persetujuan plugin saat Matrix dapat menyimpulkan approver dengan aman, tetapi Matrix tidak mengekspos jalur fanout DM/channel persetujuan plugin native yang terpisah.
Aturan pengiriman:
- `target: "dm"` mengirim prompt persetujuan ke DM approver
- `target: "channel"` mengirim prompt kembali ke room atau DM Matrix asal
- `target: "both"` mengirim ke DM approver dan room atau DM Matrix asal
Saat ini Matrix menggunakan prompt persetujuan berbasis teks. Approver menyelesaikannya dengan `/approve <id> allow-once`, `/approve <id> allow-always`, atau `/approve <id> deny`.
Hanya approver yang teresolusikan yang dapat menyetujui atau menolak. Pengiriman ke channel menyertakan teks perintah, jadi aktifkan `channel` atau `both` hanya di room tepercaya.
Prompt persetujuan Matrix menggunakan kembali planner persetujuan inti bersama. Permukaan native khusus Matrix hanyalah transport untuk persetujuan exec: perutean room/DM dan perilaku kirim/perbarui/hapus pesan.
Override per akun:
- `channels.matrix.accounts.<account>.execApprovals`
Dokumentasi terkait: [Persetujuan exec](/tools/exec-approvals)
## Contoh multi-akun
```json5
{
channels: {
matrix: {
enabled: true,
defaultAccount: "assistant",
dm: { policy: "pairing" },
accounts: {
assistant: {
homeserver: "https://matrix.example.org",
accessToken: "syt_assistant_xxx",
encryption: true,
},
alerts: {
homeserver: "https://matrix.example.org",
accessToken: "syt_alerts_xxx",
dm: {
policy: "allowlist",
allowFrom: ["@ops:example.org"],
threadReplies: "off",
},
},
},
},
},
}
```
Nilai `channels.matrix` tingkat atas bertindak sebagai default untuk akun bernama kecuali jika sebuah akun menimpanya.
Anda dapat mencakup entri room turunan ke satu akun Matrix dengan `groups.<room>.account` (atau `rooms.<room>.account` lama).
Entri tanpa `account` tetap dibagikan di semua akun Matrix, dan entri dengan `account: "default"` tetap berfungsi saat akun default dikonfigurasi langsung di `channels.matrix.*` tingkat atas.
Default auth bersama parsial tidak dengan sendirinya membuat akun default implisit terpisah. OpenClaw hanya mensintesis akun tingkat atas `default` saat default tersebut memiliki auth yang baru (`homeserver` plus `accessToken`, atau `homeserver` plus `userId` dan `password`); akun bernama tetap dapat ditemukan dari `homeserver` plus `userId` saat kredensial cache memenuhi auth nanti.
Jika Matrix sudah memiliki tepat satu akun bernama, atau `defaultAccount` menunjuk ke kunci akun bernama yang sudah ada, promosi perbaikan/penyiapan dari akun tunggal ke multi-akun mempertahankan akun tersebut alih-alih membuat entri `accounts.default` baru. Hanya kunci auth/bootstrap Matrix yang dipindahkan ke akun yang dipromosikan itu; kunci kebijakan pengiriman bersama tetap di tingkat atas.
Tetapkan `defaultAccount` saat Anda ingin OpenClaw mengutamakan satu akun Matrix bernama untuk perutean implisit, probing, dan operasi CLI.
Jika Anda mengonfigurasi beberapa akun bernama, tetapkan `defaultAccount` atau teruskan `--account <id>` untuk perintah CLI yang bergantung pada pemilihan akun implisit.
Teruskan `--account <id>` ke `openclaw matrix verify ...` dan `openclaw matrix devices ...` saat Anda ingin menimpa pemilihan implisit tersebut untuk satu perintah.
## Homeserver privat/LAN
Secara default, OpenClaw memblokir homeserver Matrix privat/internal untuk perlindungan SSRF kecuali Anda
secara eksplisit melakukan opt-in per akun.
Jika homeserver Anda berjalan di localhost, IP LAN/Tailscale, atau hostname internal, aktifkan
`allowPrivateNetwork` untuk akun Matrix tersebut:
```json5
{
channels: {
matrix: {
homeserver: "http://matrix-synapse:8008",
allowPrivateNetwork: true,
accessToken: "syt_internal_xxx",
},
},
}
```
Contoh penyiapan CLI:
```bash
openclaw matrix account add \
--account ops \
--homeserver http://matrix-synapse:8008 \
--allow-private-network \
--access-token syt_ops_xxx
```
Opt-in ini hanya mengizinkan target privat/internal tepercaya. Homeserver cleartext publik seperti
`http://matrix.example.org:8008` tetap diblokir. Utamakan `https://` bila memungkinkan.
## Mem-proxy lalu lintas Matrix
Jika deployment Matrix Anda memerlukan proxy HTTP(S) keluar eksplisit, tetapkan `channels.matrix.proxy`:
```json5
{
channels: {
matrix: {
homeserver: "https://matrix.example.org",
accessToken: "syt_bot_xxx",
proxy: "http://127.0.0.1:7890",
},
},
}
```
Akun bernama dapat menimpa default tingkat atas dengan `channels.matrix.accounts.<id>.proxy` miliknya sendiri.
OpenClaw menggunakan setelan proxy yang sama untuk lalu lintas Matrix saat runtime dan probe status akun.
## Resolusi target
Matrix menerima bentuk target ini di mana pun OpenClaw meminta target room atau pengguna:
- Pengguna: `@user:server`, `user:@user:server`, atau `matrix:user:@user:server`
- Room: `!room:server`, `room:!room:server`, atau `matrix:room:!room:server`
- Alias: `#alias:server`, `channel:#alias:server`, atau `matrix:channel:#alias:server`
Lookup direktori live menggunakan akun Matrix yang sudah login:
- Lookup pengguna mengueri direktori pengguna Matrix di homeserver tersebut.
- Lookup room menerima ID room dan alias eksplisit secara langsung, lalu kembali ke pencarian nama room yang sudah diikuti untuk akun tersebut.
- Lookup nama room yang sudah diikuti bersifat best-effort. Jika nama room tidak dapat diresolusikan menjadi ID atau alias, nama tersebut diabaikan oleh resolusi allowlist saat runtime.
## Referensi konfigurasi
- `enabled`: aktifkan atau nonaktifkan channel.
- `name`: label opsional untuk akun.
- `defaultAccount`: ID akun pilihan saat beberapa akun Matrix dikonfigurasi.
- `homeserver`: URL homeserver, misalnya `https://matrix.example.org`.
- `allowPrivateNetwork`: izinkan akun Matrix ini terhubung ke homeserver privat/internal. Aktifkan ini saat homeserver diresolusikan ke `localhost`, IP LAN/Tailscale, atau host internal seperti `matrix-synapse`.
- `proxy`: URL proxy HTTP(S) opsional untuk lalu lintas Matrix. Akun bernama dapat menimpa default tingkat atas dengan `proxy` miliknya sendiri.
- `userId`: ID pengguna Matrix penuh, misalnya `@bot:example.org`.
- `accessToken`: access token untuk auth berbasis token. Nilai plaintext dan SecretRef didukung untuk `channels.matrix.accessToken` dan `channels.matrix.accounts.<id>.accessToken` di seluruh penyedia env/file/exec. Lihat [Secrets Management](/gateway/secrets).
- `password`: password untuk login berbasis password. Nilai plaintext dan SecretRef didukung.
- `deviceId`: ID perangkat Matrix eksplisit.
- `deviceName`: nama tampilan perangkat untuk login password.
- `avatarUrl`: URL avatar diri yang tersimpan untuk sinkronisasi profil dan pembaruan `set-profile`.
- `initialSyncLimit`: batas event sinkronisasi saat startup.
- `encryption`: aktifkan E2EE.
- `allowlistOnly`: paksa perilaku hanya-allowlist untuk DM dan room.
- `allowBots`: izinkan pesan dari akun Matrix OpenClaw lain yang dikonfigurasi (`true` atau `"mentions"`).
- `groupPolicy`: `open`, `allowlist`, atau `disabled`.
- `contextVisibility`: mode visibilitas konteks room tambahan (`all`, `allowlist`, `allowlist_quote`).
- `groupAllowFrom`: allowlist ID pengguna untuk lalu lintas room.
- Entri `groupAllowFrom` harus berupa ID pengguna Matrix penuh. Nama yang tidak teresolusikan diabaikan saat runtime.
- `historyLimit`: jumlah maksimum pesan room yang disertakan sebagai konteks riwayat grup. Kembali ke `messages.groupChat.historyLimit`. Tetapkan `0` untuk menonaktifkan.
- `replyToMode`: `off`, `first`, atau `all`.
- `markdown`: konfigurasi rendering Markdown opsional untuk teks Matrix keluar.
- `streaming`: `off` (default), `partial`, `true`, atau `false`. `partial` dan `true` mengaktifkan pratinjau draf satu pesan dengan pembaruan edit-di-tempat.
- `blockStreaming`: `true` mengaktifkan pesan progres terpisah untuk blok asisten yang selesai saat streaming pratinjau draf aktif.
- `threadReplies`: `off`, `inbound`, atau `always`.
- `threadBindings`: override per channel untuk perutean sesi terikat thread dan siklus hidupnya.
- `startupVerification`: mode permintaan self-verification otomatis saat startup (`if-unverified`, `off`).
- `startupVerificationCooldownHours`: cooldown sebelum mencoba ulang permintaan verifikasi startup otomatis.
- `textChunkLimit`: ukuran chunk pesan keluar.
- `chunkMode`: `length` atau `newline`.
- `responsePrefix`: prefiks pesan opsional untuk balasan keluar.
- `ackReaction`: override reaksi ack opsional untuk channel/akun ini.
- `ackReactionScope`: override cakupan reaksi ack opsional (`group-mentions`, `group-all`, `direct`, `all`, `none`, `off`).
- `reactionNotifications`: mode notifikasi reaksi masuk (`own`, `off`).
- `mediaMaxMb`: batas ukuran media dalam MB untuk penanganan media Matrix. Berlaku untuk pengiriman keluar dan pemrosesan media masuk.
- `autoJoin`: kebijakan auto-join undangan (`always`, `allowlist`, `off`). Default: `off`.
- `autoJoinAllowlist`: room/alias yang diizinkan saat `autoJoin` adalah `allowlist`. Entri alias diresolusikan menjadi ID room selama penanganan undangan; OpenClaw tidak mempercayai status alias yang diklaim oleh room yang mengundang.
- `dm`: blok kebijakan DM (`enabled`, `policy`, `allowFrom`, `threadReplies`).
- Entri `dm.allowFrom` harus berupa ID pengguna Matrix penuh kecuali Anda sudah meresolusikannya melalui lookup direktori live.
- `dm.threadReplies`: override kebijakan thread khusus DM (`off`, `inbound`, `always`). Menimpa setelan `threadReplies` tingkat atas untuk penempatan balasan dan isolasi sesi di DM.
- `execApprovals`: pengiriman persetujuan exec native Matrix (`enabled`, `approvers`, `target`, `agentFilter`, `sessionFilter`).
- `execApprovals.approvers`: ID pengguna Matrix yang diizinkan menyetujui permintaan exec. Opsional jika `dm.allowFrom` sudah mengidentifikasi approver.
- `execApprovals.target`: `dm | channel | both` (default: `dm`).
- `accounts`: override bernama per akun. Nilai `channels.matrix` tingkat atas bertindak sebagai default untuk entri ini.
- `groups`: peta kebijakan per room. Utamakan ID room atau alias; nama room yang tidak teresolusikan diabaikan saat runtime. Identitas sesi/grup menggunakan ID room stabil setelah resolusi, sementara label yang dapat dibaca manusia tetap berasal dari nama room.
- `groups.<room>.account`: batasi satu entri room turunan ke akun Matrix tertentu dalam penyiapan multi-akun.
- `groups.<room>.allowBots`: override tingkat room untuk pengirim bot yang dikonfigurasi (`true` atau `"mentions"`).
- `groups.<room>.users`: allowlist pengirim per room.
- `groups.<room>.tools`: override izinkan/tolak alat per room.
- `groups.<room>.autoReply`: override penggatingan mention tingkat room. `true` menonaktifkan persyaratan mention untuk room tersebut; `false` memaksanya aktif kembali.
- `groups.<room>.skills`: filter skill tingkat room opsional.
- `groups.<room>.systemPrompt`: cuplikan system prompt tingkat room opsional.
- `rooms`: alias lama untuk `groups`.
- `actions`: gating alat per tindakan (`messages`, `reactions`, `pins`, `profile`, `memberInfo`, `channelInfo`, `verification`).
## Terkait
- [Ikhtisar Channels](/channels) — semua channel yang didukung
- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing
- [Groups](/channels/groups) — perilaku chat grup dan penggatingan mention
- [Perutean Channel](/channels/channel-routing) — perutean sesi untuk pesan
- [Keamanan](/gateway/security) — model akses dan hardening

479
docs/id/channels/mattermost.md Normal file
View File

@ -0,0 +1,479 @@
---
read_when:
- Menyiapkan Mattermost
- Men-debug routing Mattermost
summary: Penyiapan bot Mattermost dan konfigurasi OpenClaw
title: Mattermost
x-i18n:
generated_at: "2026-04-05T13:44:13Z"
model: gpt-5.4
provider: openai
source_hash: f21dc7543176fda0b38b00fab60f0daae38dffcf68fa1cf7930a9f14ec57cb5a
source_path: channels/mattermost.md
workflow: 15
---
# Mattermost
Status: plugin bawaan (token bot + event WebSocket). Channel, grup, dan DM didukung.
Mattermost adalah platform perpesanan tim yang dapat di-host sendiri; lihat situs resmi di
[mattermost.com](https://mattermost.com) untuk detail produk dan unduhan.
## Plugin bawaan
Mattermost dikirim sebagai plugin bawaan dalam rilis OpenClaw saat ini, jadi build
paket normal tidak memerlukan instalasi terpisah.
Jika Anda menggunakan build lama atau instalasi kustom yang tidak menyertakan Mattermost,
instal secara manual:
Instal melalui CLI (registry npm):
```bash
openclaw plugins install @openclaw/mattermost
```
Checkout lokal (saat berjalan dari repo git):
```bash
openclaw plugins install ./path/to/local/mattermost-plugin
```
Detail: [Plugins](/tools/plugin)
## Penyiapan cepat
1. Pastikan plugin Mattermost tersedia.
- Rilis OpenClaw terpaket saat ini sudah menyertakannya.
- Instalasi lama/kustom dapat menambahkannya secara manual dengan perintah di atas.
2. Buat akun bot Mattermost dan salin **token bot**.
3. Salin **URL dasar** Mattermost (misalnya `https://chat.example.com`).
4. Konfigurasikan OpenClaw dan jalankan gateway.
Konfigurasi minimal:
```json5
{
channels: {
mattermost: {
enabled: true,
botToken: "mm-token",
baseUrl: "https://chat.example.com",
dmPolicy: "pairing",
},
},
}
```
## Native slash commands
Native slash commands bersifat opt-in. Saat diaktifkan, OpenClaw mendaftarkan slash command `oc_*` melalui
Mattermost API dan menerima POST callback pada server HTTP gateway.
```json5
{
channels: {
mattermost: {
commands: {
native: true,
nativeSkills: true,
callbackPath: "/api/channels/mattermost/command",
// Gunakan saat Mattermost tidak dapat menjangkau gateway secara langsung (reverse proxy/URL publik).
callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
},
},
},
}
```
Catatan:
- `native: "auto"` secara default dinonaktifkan untuk Mattermost. Setel `native: true` untuk mengaktifkannya.
- Jika `callbackUrl` dihilangkan, OpenClaw akan menurunkannya dari host/port gateway + `callbackPath`.
- Untuk penyiapan multi-akun, `commands` dapat disetel di tingkat atas atau di bawah
`channels.mattermost.accounts.<id>.commands` (nilai akun menimpa field tingkat atas).
- Callback perintah divalidasi dengan token per perintah yang dikembalikan oleh
Mattermost saat OpenClaw mendaftarkan perintah `oc_*`.
- Callback slash gagal secara tertutup saat pendaftaran gagal, startup parsial, atau
token callback tidak cocok dengan salah satu perintah yang terdaftar.
- Persyaratan keterjangkauan: endpoint callback harus dapat dijangkau dari server Mattermost.
- Jangan setel `callbackUrl` ke `localhost` kecuali Mattermost berjalan pada host/network namespace yang sama dengan OpenClaw.
- Jangan setel `callbackUrl` ke URL dasar Mattermost Anda kecuali URL tersebut melakukan reverse-proxy `/api/channels/mattermost/command` ke OpenClaw.
- Pemeriksaan cepat: `curl https://<gateway-host>/api/channels/mattermost/command`; GET harus mengembalikan `405 Method Not Allowed` dari OpenClaw, bukan `404`.
- Persyaratan allowlist egress Mattermost:
- Jika callback Anda menargetkan alamat privat/tailnet/internal, setel Mattermost
`ServiceSettings.AllowedUntrustedInternalConnections` agar menyertakan host/domain callback.
- Gunakan entri host/domain, bukan URL lengkap.
- Baik: `gateway.tailnet-name.ts.net`
- Buruk: `https://gateway.tailnet-name.ts.net`
## Variabel lingkungan (akun default)
Setel ini pada host gateway jika Anda lebih memilih env var:
- `MATTERMOST_BOT_TOKEN=...`
- `MATTERMOST_URL=https://chat.example.com`
Env var hanya berlaku untuk akun **default** (`default`). Akun lain harus menggunakan nilai konfigurasi.
## Mode chat
Mattermost merespons DM secara otomatis. Perilaku channel dikendalikan oleh `chatmode`:
- `oncall` (default): hanya merespons saat di-@mention di channel.
- `onmessage`: merespons setiap pesan channel.
- `onchar`: merespons saat pesan dimulai dengan prefiks pemicu.
Contoh konfigurasi:
```json5
{
channels: {
mattermost: {
chatmode: "onchar",
oncharPrefixes: [">", "!"],
},
},
}
```
Catatan:
- `onchar` tetap merespons @mention eksplisit.
- `channels.mattermost.requireMention` dihormati untuk konfigurasi lama, tetapi `chatmode` lebih disukai.
## Threading dan sesi
Gunakan `channels.mattermost.replyToMode` untuk mengontrol apakah balasan channel dan grup tetap berada di
channel utama atau memulai thread di bawah post pemicu.
- `off` (default): hanya membalas dalam thread saat post masuk memang sudah berada di thread.
- `first`: untuk post channel/grup tingkat atas, mulai thread di bawah post tersebut dan rutekan
percakapan ke sesi dengan cakupan thread.
- `all`: perilakunya sama dengan `first` untuk Mattermost saat ini.
- Pesan langsung mengabaikan pengaturan ini dan tetap non-threaded.
Contoh konfigurasi:
```json5
{
channels: {
mattermost: {
replyToMode: "all",
},
},
}
```
Catatan:
- Sesi dengan cakupan thread menggunakan id post pemicu sebagai akar thread.
- `first` dan `all` saat ini setara karena setelah Mattermost memiliki akar thread,
chunk lanjutan dan media akan tetap berada di thread yang sama.
## Kontrol akses (DM)
- Default: `channels.mattermost.dmPolicy = "pairing"` (pengirim yang tidak dikenal mendapatkan kode pairing).
- Setujui melalui:
- `openclaw pairing list mattermost`
- `openclaw pairing approve mattermost <CODE>`
- DM publik: `channels.mattermost.dmPolicy="open"` plus `channels.mattermost.allowFrom=["*"]`.
## Channel (grup)
- Default: `channels.mattermost.groupPolicy = "allowlist"` (dibatasi mention).
- Allowlist pengirim dengan `channels.mattermost.groupAllowFrom` (ID pengguna direkomendasikan).
- Override mention per channel ada di bawah `channels.mattermost.groups.<channelId>.requireMention`
atau `channels.mattermost.groups["*"].requireMention` sebagai default.
- Pencocokan `@username` bersifat dapat berubah dan hanya diaktifkan saat `channels.mattermost.dangerouslyAllowNameMatching: true`.
- Channel terbuka: `channels.mattermost.groupPolicy="open"` (dibatasi mention).
- Catatan runtime: jika `channels.mattermost` sama sekali tidak ada, runtime akan fallback ke `groupPolicy="allowlist"` untuk pemeriksaan grup (bahkan jika `channels.defaults.groupPolicy` disetel).
Contoh:
```json5
{
channels: {
mattermost: {
groupPolicy: "open",
groups: {
"*": { requireMention: true },
"team-channel-id": { requireMention: false },
},
},
},
}
```
## Target untuk pengiriman keluar
Gunakan format target ini dengan `openclaw message send` atau cron/webhook:
- `channel:<id>` untuk channel
- `user:<id>` untuk DM
- `@username` untuk DM (di-resolve melalui Mattermost API)
ID opak biasa (seperti `64ifufp...`) **ambigu** di Mattermost (ID pengguna vs ID channel).
OpenClaw me-resolve-nya dengan prioritas **pengguna terlebih dahulu**:
- Jika ID ada sebagai pengguna (`GET /api/v4/users/<id>` berhasil), OpenClaw mengirim **DM** dengan me-resolve channel langsung melalui `/api/v4/channels/direct`.
- Jika tidak, ID diperlakukan sebagai **ID channel**.
Jika Anda membutuhkan perilaku deterministik, selalu gunakan prefiks eksplisit (`user:<id>` / `channel:<id>`).
## Percobaan ulang channel DM
Saat OpenClaw mengirim ke target DM Mattermost dan perlu me-resolve channel langsung terlebih dahulu, OpenClaw
secara default mencoba ulang kegagalan sementara pada pembuatan channel langsung.
Gunakan `channels.mattermost.dmChannelRetry` untuk menyetel perilaku itu secara global untuk plugin Mattermost,
atau `channels.mattermost.accounts.<id>.dmChannelRetry` untuk satu akun.
```json5
{
channels: {
mattermost: {
dmChannelRetry: {
maxRetries: 3,
initialDelayMs: 1000,
maxDelayMs: 10000,
timeoutMs: 30000,
},
},
},
}
```
Catatan:
- Ini hanya berlaku untuk pembuatan channel DM (`/api/v4/channels/direct`), bukan setiap panggilan Mattermost API.
- Percobaan ulang berlaku untuk kegagalan sementara seperti rate limit, respons 5xx, dan kesalahan jaringan atau timeout.
- Kesalahan klien 4xx selain `429` diperlakukan sebagai permanen dan tidak dicoba ulang.
## Reaksi (message tool)
- Gunakan `message action=react` dengan `channel=mattermost`.
- `messageId` adalah id post Mattermost.
- `emoji` menerima nama seperti `thumbsup` atau `:+1:` (titik dua opsional).
- Setel `remove=true` (boolean) untuk menghapus reaksi.
- Event tambah/hapus reaksi diteruskan sebagai event sistem ke sesi agent yang dirutekan.
Contoh:
```
message action=react channel=mattermost target=channel:<channelId> messageId=<postId> emoji=thumbsup
message action=react channel=mattermost target=channel:<channelId> messageId=<postId> emoji=thumbsup remove=true
```
Konfigurasi:
- `channels.mattermost.actions.reactions`: aktifkan/nonaktifkan tindakan reaksi (default true).
- Override per akun: `channels.mattermost.accounts.<id>.actions.reactions`.
## Tombol interaktif (message tool)
Kirim pesan dengan tombol yang dapat diklik. Saat pengguna mengklik tombol, agent menerima
pilihan tersebut dan dapat merespons.
Aktifkan tombol dengan menambahkan `inlineButtons` ke capability channel:
```json5
{
channels: {
mattermost: {
capabilities: ["inlineButtons"],
},
},
}
```
Gunakan `message action=send` dengan parameter `buttons`. Tombol adalah array 2D (baris tombol):
```
message action=send channel=mattermost target=channel:<channelId> buttons=[[{"text":"Yes","callback_data":"yes"},{"text":"No","callback_data":"no"}]]
```
Field tombol:
- `text` (wajib): label tampilan.
- `callback_data` (wajib): nilai yang dikirim kembali saat diklik (digunakan sebagai action ID).
- `style` (opsional): `"default"`, `"primary"`, atau `"danger"`.
Saat pengguna mengklik tombol:
1. Semua tombol diganti dengan baris konfirmasi (misalnya, "✓ **Yes** selected by @user").
2. Agent menerima pilihan sebagai pesan masuk dan merespons.
Catatan:
- Callback tombol menggunakan verifikasi HMAC-SHA256 (otomatis, tidak perlu konfigurasi).
- Mattermost menghapus callback data dari respons API-nya (fitur keamanan), sehingga semua tombol
dihapus saat diklik — penghapusan sebagian tidak dimungkinkan.
- Action ID yang berisi tanda hubung atau garis bawah disanitasi secara otomatis
(keterbatasan routing Mattermost).
Konfigurasi:
- `channels.mattermost.capabilities`: array string capability. Tambahkan `"inlineButtons"` untuk
mengaktifkan deskripsi tool tombol dalam prompt sistem agent.
- `channels.mattermost.interactions.callbackBaseUrl`: URL dasar eksternal opsional untuk callback
tombol (misalnya `https://gateway.example.com`). Gunakan ini saat Mattermost tidak dapat
menjangkau gateway pada bind host-nya secara langsung.
- Dalam penyiapan multi-akun, Anda juga dapat menyetel field yang sama di bawah
`channels.mattermost.accounts.<id>.interactions.callbackBaseUrl`.
- Jika `interactions.callbackBaseUrl` dihilangkan, OpenClaw menurunkan URL callback dari
`gateway.customBindHost` + `gateway.port`, lalu fallback ke `http://localhost:<port>`.
- Aturan keterjangkauan: URL callback tombol harus dapat dijangkau dari server Mattermost.
`localhost` hanya berfungsi jika Mattermost dan OpenClaw berjalan pada host/network namespace yang sama.
- Jika target callback Anda bersifat privat/tailnet/internal, tambahkan host/domain-nya ke Mattermost
`ServiceSettings.AllowedUntrustedInternalConnections`.
### Integrasi API langsung (skrip eksternal)
Skrip eksternal dan webhook dapat mem-posting tombol langsung melalui Mattermost REST API
alih-alih melalui `message` tool milik agent. Gunakan `buildButtonAttachments()` dari
ekstensi bila memungkinkan; jika mem-posting JSON mentah, ikuti aturan ini:
**Struktur payload:**
```json5
{
channel_id: "<channelId>",
message: "Choose an option:",
props: {
attachments: [
{
actions: [
{
id: "mybutton01", // alfanumerik saja — lihat di bawah
type: "button", // wajib, atau klik akan diabaikan secara diam-diam
name: "Approve", // label tampilan
style: "primary", // opsional: "default", "primary", "danger"
integration: {
url: "https://gateway.example.com/mattermost/interactions/default",
context: {
action_id: "mybutton01", // harus cocok dengan id tombol (untuk lookup nama)
action: "approve",
// ... field kustom apa pun ...
_token: "<hmac>", // lihat bagian HMAC di bawah
},
},
},
],
},
],
},
}
```
**Aturan penting:**
1. Attachment ditempatkan di `props.attachments`, bukan `attachments` tingkat atas (kalau tidak akan diabaikan secara diam-diam).
2. Setiap action memerlukan `type: "button"` — tanpa itu, klik akan tertelan secara diam-diam.
3. Setiap action memerlukan field `id` — Mattermost mengabaikan action tanpa ID.
4. `id` action harus **hanya alfanumerik** (`[a-zA-Z0-9]`). Tanda hubung dan garis bawah merusak
routing action sisi server Mattermost (mengembalikan 404). Hapus karakter tersebut sebelum digunakan.
5. `context.action_id` harus cocok dengan `id` tombol agar pesan konfirmasi menampilkan
nama tombol (misalnya, "Approve"), bukan ID mentah.
6. `context.action_id` wajib — handler interaksi mengembalikan 400 tanpanya.
**Pembuatan token HMAC:**
Gateway memverifikasi klik tombol dengan HMAC-SHA256. Skrip eksternal harus membuat token
yang cocok dengan logika verifikasi gateway:
1. Turunkan secret dari token bot:
`HMAC-SHA256(key="openclaw-mattermost-interactions", data=botToken)`
2. Bangun objek context dengan semua field **kecuali** `_token`.
3. Serialisasikan dengan **kunci yang diurutkan** dan **tanpa spasi** (gateway menggunakan `JSON.stringify`
dengan kunci yang diurutkan, yang menghasilkan output ringkas).
4. Tanda tangani: `HMAC-SHA256(key=secret, data=serializedContext)`
5. Tambahkan hex digest yang dihasilkan sebagai `_token` dalam context.
Contoh Python:
```python
import hmac, hashlib, json
secret = hmac.new(
b"openclaw-mattermost-interactions",
bot_token.encode(), hashlib.sha256
).hexdigest()
ctx = {"action_id": "mybutton01", "action": "approve"}
payload = json.dumps(ctx, sort_keys=True, separators=(",", ":"))
token = hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest()
context = {**ctx, "_token": token}
```
Jebakan umum HMAC:
- `json.dumps` Python secara default menambahkan spasi (`{"key": "val"}`). Gunakan
`separators=(",", ":")` agar cocok dengan output ringkas JavaScript (`{"key":"val"}`).
- Selalu tanda tangani **semua** field context (tanpa `_token`). Gateway menghapus `_token` lalu
menandatangani semua yang tersisa. Menandatangani subset akan menyebabkan kegagalan verifikasi diam-diam.
- Gunakan `sort_keys=True` — gateway mengurutkan kunci sebelum penandatanganan, dan Mattermost dapat
mengubah urutan field context saat menyimpan payload.
- Turunkan secret dari token bot (deterministik), bukan byte acak. Secret
harus sama di seluruh proses yang membuat tombol dan gateway yang memverifikasi.
## Adapter direktori
Plugin Mattermost menyertakan adapter direktori yang me-resolve nama channel dan pengguna
melalui Mattermost API. Ini memungkinkan target `#channel-name` dan `@username` dalam
`openclaw message send` dan pengiriman cron/webhook.
Tidak diperlukan konfigurasi — adapter menggunakan token bot dari konfigurasi akun.
## Multi-akun
Mattermost mendukung beberapa akun di bawah `channels.mattermost.accounts`:
```json5
{
channels: {
mattermost: {
accounts: {
default: { name: "Primary", botToken: "mm-token", baseUrl: "https://chat.example.com" },
alerts: { name: "Alerts", botToken: "mm-token-2", baseUrl: "https://alerts.example.com" },
},
},
},
}
```
## Pemecahan masalah
- Tidak ada balasan di channel: pastikan bot ada di channel dan sebut bot tersebut (oncall), gunakan prefiks pemicu (onchar), atau setel `chatmode: "onmessage"`.
- Kesalahan autentikasi: periksa token bot, URL dasar, dan apakah akun diaktifkan.
- Masalah multi-akun: env var hanya berlaku untuk akun `default`.
- Native slash commands mengembalikan `Unauthorized: invalid command token.`: OpenClaw
tidak menerima token callback. Penyebab umum:
- pendaftaran slash command gagal atau hanya selesai sebagian saat startup
- callback mengenai gateway/akun yang salah
- Mattermost masih memiliki perintah lama yang menunjuk ke target callback sebelumnya
- gateway direstart tanpa mengaktifkan kembali slash commands
- Jika native slash commands berhenti berfungsi, periksa log untuk
`mattermost: failed to register slash commands` atau
`mattermost: native slash commands enabled but no commands could be registered`.
- Jika `callbackUrl` dihilangkan dan log memperingatkan bahwa callback di-resolve ke
`http://127.0.0.1:18789/...`, URL tersebut kemungkinan hanya dapat dijangkau saat
Mattermost berjalan pada host/network namespace yang sama dengan OpenClaw. Setel
`commands.callbackUrl` eksplisit yang dapat dijangkau dari luar.
- Tombol muncul sebagai kotak putih: agent mungkin mengirim data tombol yang tidak valid. Pastikan setiap tombol memiliki field `text` dan `callback_data`.
- Tombol dirender tetapi klik tidak melakukan apa-apa: verifikasi `AllowedUntrustedInternalConnections` pada konfigurasi server Mattermost menyertakan `127.0.0.1 localhost`, dan `EnablePostActionIntegration` bernilai `true` di ServiceSettings.
- Tombol mengembalikan 404 saat diklik: `id` tombol kemungkinan berisi tanda hubung atau garis bawah. Router action Mattermost rusak pada ID non-alfanumerik. Gunakan hanya `[a-zA-Z0-9]`.
- Log gateway `invalid _token`: HMAC tidak cocok. Periksa bahwa Anda menandatangani semua field context (bukan subset), menggunakan kunci yang diurutkan, dan JSON ringkas (tanpa spasi). Lihat bagian HMAC di atas.
- Log gateway `missing _token in context`: field `_token` tidak ada dalam context tombol. Pastikan field tersebut disertakan saat membangun payload integrasi.
- Konfirmasi menampilkan ID mentah alih-alih nama tombol: `context.action_id` tidak cocok dengan `id` tombol. Setel keduanya ke nilai tersanitasi yang sama.
- Agent tidak mengetahui tombol: tambahkan `capabilities: ["inlineButtons"]` ke konfigurasi channel Mattermost.
## Terkait
- [Ikhtisar Channels](/channels) — semua channel yang didukung
- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing
- [Groups](/channels/groups) — perilaku obrolan grup dan pembatasan mention
- [Channel Routing](/channels/channel-routing) — routing sesi untuk pesan
- [Security](/gateway/security) — model akses dan hardening

810
docs/id/channels/msteams.md Normal file
View File

@ -0,0 +1,810 @@
---
read_when:
- Mengerjakan fitur channel Microsoft Teams
summary: Status dukungan bot Microsoft Teams, kapabilitas, dan konfigurasi
title: Microsoft Teams
x-i18n:
generated_at: "2026-04-05T13:44:53Z"
model: gpt-5.4
provider: openai
source_hash: 99fc6e136893ec65dc85d3bc0c0d92134069a2f3b8cb4fcf66c14674399b3eaf
source_path: channels/msteams.md
workflow: 15
---
# Microsoft Teams
> "Tinggalkan semua harapan, hai kalian yang masuk ke sini."
Diperbarui: 2026-01-21
Status: teks + lampiran DM didukung; pengiriman file channel/grup memerlukan `sharePointSiteId` + izin Graph (lihat [Mengirim file di obrolan grup](#sending-files-in-group-chats)). Poll dikirim melalui Adaptive Cards. Aksi pesan mengekspos `upload-file` secara eksplisit untuk pengiriman yang mengutamakan file.
## Plugin bawaan
Microsoft Teams dikirim sebagai plugin bawaan dalam rilis OpenClaw saat ini, jadi tidak diperlukan instalasi terpisah dalam build paket normal.
Jika Anda menggunakan build lama atau instalasi kustom yang tidak menyertakan Teams bawaan, instal secara manual:
```bash
openclaw plugins install @openclaw/msteams
```
Checkout lokal (saat berjalan dari repo git):
```bash
openclaw plugins install ./path/to/local/msteams-plugin
```
Detail: [Plugins](/tools/plugin)
## Penyiapan cepat (pemula)
1. Pastikan plugin Microsoft Teams tersedia.
- Rilis OpenClaw paket saat ini sudah menyertakannya.
- Instalasi lama/kustom dapat menambahkannya secara manual dengan perintah di atas.
2. Buat **Azure Bot** (App ID + client secret + tenant ID).
3. Konfigurasikan OpenClaw dengan kredensial tersebut.
4. Ekspos `/api/messages` (default port 3978) melalui URL publik atau tunnel.
5. Instal paket aplikasi Teams dan jalankan gateway.
Config minimal:
```json5
{
channels: {
msteams: {
enabled: true,
appId: "<APP_ID>",
appPassword: "<APP_PASSWORD>",
tenantId: "<TENANT_ID>",
webhook: { port: 3978, path: "/api/messages" },
},
},
}
```
Catatan: obrolan grup diblokir secara default (`channels.msteams.groupPolicy: "allowlist"`). Untuk mengizinkan balasan grup, atur `channels.msteams.groupAllowFrom` (atau gunakan `groupPolicy: "open"` untuk mengizinkan anggota mana pun, dengan gating mention).
## Tujuan
- Berbicara dengan OpenClaw melalui DM, obrolan grup, atau channel Teams.
- Menjaga perutean tetap deterministik: balasan selalu kembali ke channel asal kedatangannya.
- Default ke perilaku channel yang aman (mention diwajibkan kecuali dikonfigurasi lain).
## Penulisan config
Secara default, Microsoft Teams diizinkan menulis pembaruan config yang dipicu oleh `/config set|unset` (memerlukan `commands.config: true`).
Nonaktifkan dengan:
```json5
{
channels: { msteams: { configWrites: false } },
}
```
## Kontrol akses (DM + grup)
**Akses DM**
- Default: `channels.msteams.dmPolicy = "pairing"`. Pengirim yang tidak dikenal diabaikan sampai disetujui.
- `channels.msteams.allowFrom` sebaiknya menggunakan AAD object ID yang stabil.
- UPN/nama tampilan dapat berubah; pencocokan langsung dinonaktifkan secara default dan hanya diaktifkan dengan `channels.msteams.dangerouslyAllowNameMatching: true`.
- Wizard dapat me-resolve nama ke ID melalui Microsoft Graph jika kredensial mengizinkan.
**Akses grup**
- Default: `channels.msteams.groupPolicy = "allowlist"` (diblokir kecuali Anda menambahkan `groupAllowFrom`). Gunakan `channels.defaults.groupPolicy` untuk menimpa default saat tidak disetel.
- `channels.msteams.groupAllowFrom` mengontrol pengirim mana yang dapat memicu di obrolan grup/channel (fallback ke `channels.msteams.allowFrom`).
- Set `groupPolicy: "open"` untuk mengizinkan anggota mana pun (tetap di-gate oleh mention secara default).
- Untuk mengizinkan **tanpa channel apa pun**, set `channels.msteams.groupPolicy: "disabled"`.
Contoh:
```json5
{
channels: {
msteams: {
groupPolicy: "allowlist",
groupAllowFrom: ["user@org.com"],
},
},
}
```
**Teams + allowlist channel**
- Lingkupi balasan grup/channel dengan mendaftarkan team dan channel di bawah `channels.msteams.teams`.
- Kunci sebaiknya menggunakan team ID yang stabil dan channel conversation ID.
- Saat `groupPolicy="allowlist"` dan allowlist teams tersedia, hanya team/channel yang terdaftar yang diterima (dengan gating mention).
- Wizard konfigurasi menerima entri `Team/Channel` dan menyimpannya untuk Anda.
- Saat startup, OpenClaw me-resolve nama team/channel dan nama allowlist pengguna ke ID (saat izin Graph mengizinkan)
dan mencatat pemetaannya; nama team/channel yang tidak ter-resolve tetap disimpan seperti diketik tetapi diabaikan untuk perutean secara default kecuali `channels.msteams.dangerouslyAllowNameMatching: true` diaktifkan.
Contoh:
```json5
{
channels: {
msteams: {
groupPolicy: "allowlist",
teams: {
"My Team": {
channels: {
General: { requireMention: true },
},
},
},
},
},
}
```
## Cara kerjanya
1. Pastikan plugin Microsoft Teams tersedia.
- Rilis OpenClaw paket saat ini sudah menyertakannya.
- Instalasi lama/kustom dapat menambahkannya secara manual dengan perintah di atas.
2. Buat **Azure Bot** (App ID + secret + tenant ID).
3. Bangun **paket aplikasi Teams** yang merujuk ke bot dan menyertakan izin RSC di bawah ini.
4. Unggah/instal aplikasi Teams ke dalam team (atau cakupan personal untuk DM).
5. Konfigurasikan `msteams` di `~/.openclaw/openclaw.json` (atau env vars) dan jalankan gateway.
6. Gateway mendengarkan traffic webhook Bot Framework di `/api/messages` secara default.
## Penyiapan Azure Bot (Prasyarat)
Sebelum mengonfigurasi OpenClaw, Anda perlu membuat resource Azure Bot.
### Langkah 1: Buat Azure Bot
1. Buka [Create Azure Bot](https://portal.azure.com/#create/Microsoft.AzureBot)
2. Isi tab **Basics**:
| Field | Value |
| ------------------ | -------------------------------------------------------- |
| **Bot handle** | Nama bot Anda, mis. `openclaw-msteams` (harus unik) |
| **Subscription** | Pilih subscription Azure Anda |
| **Resource group** | Buat baru atau gunakan yang sudah ada |
| **Pricing tier** | **Free** untuk dev/testing |
| **Type of App** | **Single Tenant** (disarankan - lihat catatan di bawah) |
| **Creation type** | **Create new Microsoft App ID** |
> **Pemberitahuan deprecation:** Pembuatan bot multi-tenant baru tidak lagi didukung setelah 2025-07-31. Gunakan **Single Tenant** untuk bot baru.
3. Klik **Review + create** → **Create** (tunggu ~1-2 menit)
### Langkah 2: Dapatkan Kredensial
1. Buka resource Azure Bot Anda → **Configuration**
2. Salin **Microsoft App ID** → ini adalah `appId` Anda
3. Klik **Manage Password** → buka App Registration
4. Di bawah **Certificates & secrets** → **New client secret** → salin **Value** → ini adalah `appPassword` Anda
5. Buka **Overview** → salin **Directory (tenant) ID** → ini adalah `tenantId` Anda
### Langkah 3: Konfigurasikan Messaging Endpoint
1. Di Azure Bot → **Configuration**
2. Set **Messaging endpoint** ke URL webhook Anda:
- Produksi: `https://your-domain.com/api/messages`
- Dev lokal: gunakan tunnel (lihat [Pengembangan Lokal](#local-development-tunneling) di bawah)
### Langkah 4: Aktifkan Channel Teams
1. Di Azure Bot → **Channels**
2. Klik **Microsoft Teams** → Configure → Save
3. Terima Terms of Service
## Pengembangan Lokal (Tunneling)
Teams tidak dapat menjangkau `localhost`. Gunakan tunnel untuk pengembangan lokal:
**Opsi A: ngrok**
```bash
ngrok http 3978
# Salin URL https, mis. https://abc123.ngrok.io
# Set messaging endpoint ke: https://abc123.ngrok.io/api/messages
```
**Opsi B: Tailscale Funnel**
```bash
tailscale funnel 3978
# Gunakan URL Tailscale funnel Anda sebagai messaging endpoint
```
## Teams Developer Portal (Alternatif)
Alih-alih membuat ZIP manifest secara manual, Anda dapat menggunakan [Teams Developer Portal](https://dev.teams.microsoft.com/apps):
1. Klik **+ New app**
2. Isi info dasar (nama, deskripsi, info developer)
3. Buka **App features** → **Bot**
4. Pilih **Enter a bot ID manually** dan tempel Azure Bot App ID Anda
5. Centang scope: **Personal**, **Team**, **Group Chat**
6. Klik **Distribute** → **Download app package**
7. Di Teams: **Apps** → **Manage your apps** → **Upload a custom app** → pilih ZIP
Ini sering lebih mudah daripada mengedit manifest JSON secara manual.
## Menguji Bot
**Opsi A: Azure Web Chat (verifikasi webhook terlebih dahulu)**
1. Di Azure Portal → resource Azure Bot Anda → **Test in Web Chat**
2. Kirim pesan - Anda seharusnya melihat respons
3. Ini mengonfirmasi bahwa endpoint webhook Anda berfungsi sebelum penyiapan Teams
**Opsi B: Teams (setelah aplikasi diinstal)**
1. Instal aplikasi Teams (sideload atau katalog organisasi)
2. Temukan bot di Teams dan kirim DM
3. Periksa log gateway untuk aktivitas masuk
## Penyiapan (minimal hanya teks)
1. **Pastikan plugin Microsoft Teams tersedia**
- Rilis OpenClaw paket saat ini sudah menyertakannya.
- Instalasi lama/kustom dapat menambahkannya secara manual:
- Dari npm: `openclaw plugins install @openclaw/msteams`
- Dari checkout lokal: `openclaw plugins install ./path/to/local/msteams-plugin`
2. **Registrasi bot**
- Buat Azure Bot (lihat di atas) dan catat:
- App ID
- Client secret (App password)
- Tenant ID (single-tenant)
3. **Manifest aplikasi Teams**
- Sertakan entri `bot` dengan `botId = <App ID>`.
- Scope: `personal`, `team`, `groupChat`.
- `supportsFiles: true` (diperlukan untuk penanganan file dalam scope personal).
- Tambahkan izin RSC (di bawah).
- Buat ikon: `outline.png` (32x32) dan `color.png` (192x192).
- Zip ketiga file menjadi satu: `manifest.json`, `outline.png`, `color.png`.
4. **Konfigurasikan OpenClaw**
```json5
{
channels: {
msteams: {
enabled: true,
appId: "<APP_ID>",
appPassword: "<APP_PASSWORD>",
tenantId: "<TENANT_ID>",
webhook: { port: 3978, path: "/api/messages" },
},
},
}
```
Anda juga dapat menggunakan variabel lingkungan alih-alih kunci config:
- `MSTEAMS_APP_ID`
- `MSTEAMS_APP_PASSWORD`
- `MSTEAMS_TENANT_ID`
5. **Endpoint bot**
- Set Azure Bot Messaging Endpoint ke:
- `https://<host>:3978/api/messages` (atau path/port pilihan Anda).
6. **Jalankan gateway**
- Channel Teams dimulai secara otomatis saat plugin bawaan atau plugin yang diinstal manual tersedia dan config `msteams` ada beserta kredensialnya.
## Aksi info anggota
OpenClaw mengekspos aksi `member-info` berbasis Graph untuk Microsoft Teams sehingga agen dan otomatisasi dapat me-resolve detail anggota channel (nama tampilan, email, peran) langsung dari Microsoft Graph.
Persyaratan:
- Izin RSC `Member.Read.Group` (sudah ada dalam manifest yang direkomendasikan)
- Untuk lookup lintas-team: izin Graph Application `User.Read.All` dengan admin consent
Aksi ini di-gate oleh `channels.msteams.actions.memberInfo` (default: aktif saat kredensial Graph tersedia).
## Konteks riwayat
- `channels.msteams.historyLimit` mengontrol berapa banyak pesan channel/grup terbaru yang dibungkus ke dalam prompt.
- Fallback ke `messages.groupChat.historyLimit`. Set `0` untuk menonaktifkan (default 50).
- Riwayat thread yang diambil difilter oleh allowlist pengirim (`allowFrom` / `groupAllowFrom`), sehingga penanaman konteks thread hanya menyertakan pesan dari pengirim yang diizinkan.
- Konteks lampiran kutipan (`ReplyTo*` yang diturunkan dari HTML balasan Teams) saat ini diteruskan apa adanya.
- Dengan kata lain, allowlist mengatur siapa yang dapat memicu agen; hanya jalur konteks tambahan tertentu yang difilter saat ini.
- Riwayat DM dapat dibatasi dengan `channels.msteams.dmHistoryLimit` (giliran pengguna). Override per pengguna: `channels.msteams.dms["<user_id>"].historyLimit`.
## Izin RSC Teams saat ini (Manifest)
Berikut adalah **resourceSpecific permissions** yang sudah ada di manifest aplikasi Teams kami. Izin ini hanya berlaku di dalam team/chat tempat aplikasi diinstal.
**Untuk channel (scope team):**
- `ChannelMessage.Read.Group` (Application) - menerima semua teks pesan channel tanpa @mention
- `ChannelMessage.Send.Group` (Application)
- `Member.Read.Group` (Application)
- `Owner.Read.Group` (Application)
- `ChannelSettings.Read.Group` (Application)
- `TeamMember.Read.Group` (Application)
- `TeamSettings.Read.Group` (Application)
**Untuk obrolan grup:**
- `ChatMessage.Read.Chat` (Application) - menerima semua pesan obrolan grup tanpa @mention
## Contoh Manifest Teams (disamarkan)
Contoh minimal yang valid dengan field yang diperlukan. Ganti ID dan URL.
```json5
{
$schema: "https://developer.microsoft.com/en-us/json-schemas/teams/v1.23/MicrosoftTeams.schema.json",
manifestVersion: "1.23",
version: "1.0.0",
id: "00000000-0000-0000-0000-000000000000",
name: { short: "OpenClaw" },
developer: {
name: "Your Org",
websiteUrl: "https://example.com",
privacyUrl: "https://example.com/privacy",
termsOfUseUrl: "https://example.com/terms",
},
description: { short: "OpenClaw in Teams", full: "OpenClaw in Teams" },
icons: { outline: "outline.png", color: "color.png" },
accentColor: "#5B6DEF",
bots: [
{
botId: "11111111-1111-1111-1111-111111111111",
scopes: ["personal", "team", "groupChat"],
isNotificationOnly: false,
supportsCalling: false,
supportsVideo: false,
supportsFiles: true,
},
],
webApplicationInfo: {
id: "11111111-1111-1111-1111-111111111111",
},
authorization: {
permissions: {
resourceSpecific: [
{ name: "ChannelMessage.Read.Group", type: "Application" },
{ name: "ChannelMessage.Send.Group", type: "Application" },
{ name: "Member.Read.Group", type: "Application" },
{ name: "Owner.Read.Group", type: "Application" },
{ name: "ChannelSettings.Read.Group", type: "Application" },
{ name: "TeamMember.Read.Group", type: "Application" },
{ name: "TeamSettings.Read.Group", type: "Application" },
{ name: "ChatMessage.Read.Chat", type: "Application" },
],
},
},
}
```
### Catatan penting manifest (field wajib)
- `bots[].botId` **harus** cocok dengan Azure Bot App ID.
- `webApplicationInfo.id` **harus** cocok dengan Azure Bot App ID.
- `bots[].scopes` harus menyertakan surface yang ingin Anda gunakan (`personal`, `team`, `groupChat`).
- `bots[].supportsFiles: true` diperlukan untuk penanganan file dalam scope personal.
- `authorization.permissions.resourceSpecific` harus menyertakan izin baca/kirim channel jika Anda ingin traffic channel.
### Memperbarui aplikasi yang sudah ada
Untuk memperbarui aplikasi Teams yang sudah terinstal (misalnya untuk menambahkan izin RSC):
1. Perbarui `manifest.json` Anda dengan setelan baru
2. **Naikkan field `version`** (mis. `1.0.0` → `1.1.0`)
3. **Zip ulang** manifest dengan ikon (`manifest.json`, `outline.png`, `color.png`)
4. Unggah ZIP baru:
- **Opsi A (Teams Admin Center):** Teams Admin Center → Teams apps → Manage apps → temukan aplikasi Anda → Upload new version
- **Opsi B (Sideload):** Di Teams → Apps → Manage your apps → Upload a custom app
5. **Untuk channel team:** instal ulang aplikasi di setiap team agar izin baru berlaku
6. **Keluar sepenuhnya lalu jalankan ulang Teams** (bukan hanya menutup jendela) untuk membersihkan metadata aplikasi yang di-cache
## Kapabilitas: hanya RSC vs Graph
### Dengan **hanya Teams RSC** (aplikasi terinstal, tanpa izin Microsoft Graph API)
Berfungsi:
- Membaca konten **teks** pesan channel.
- Mengirim konten **teks** pesan channel.
- Menerima lampiran file **personal (DM)**.
Tidak berfungsi:
- **Konten gambar atau file** channel/grup (payload hanya menyertakan stub HTML).
- Mengunduh lampiran yang disimpan di SharePoint/OneDrive.
- Membaca riwayat pesan (di luar event webhook langsung).
### Dengan **Teams RSC + izin Microsoft Graph Application**
Menambahkan:
- Mengunduh hosted content (gambar yang ditempel ke pesan).
- Mengunduh lampiran file yang disimpan di SharePoint/OneDrive.
- Membaca riwayat pesan channel/chat melalui Graph.
### RSC vs Graph API
| Kapabilitas | Izin RSC | Graph API |
| ----------------------- | --------------------- | ------------------------------------ |
| **Pesan real-time** | Ya (melalui webhook) | Tidak (hanya polling) |
| **Pesan historis** | Tidak | Ya (dapat mengambil riwayat) |
| **Kompleksitas setup** | Hanya manifest aplikasi | Memerlukan admin consent + alur token |
| **Berfungsi offline** | Tidak (harus berjalan) | Ya (dapat melakukan query kapan saja) |
**Intinya:** RSC untuk mendengarkan secara real-time; Graph API untuk akses historis. Untuk mengejar pesan yang terlewat saat offline, Anda memerlukan Graph API dengan `ChannelMessage.Read.All` (memerlukan admin consent).
## Media + riwayat dengan Graph (diperlukan untuk channel)
Jika Anda memerlukan gambar/file di **channel** atau ingin mengambil **riwayat pesan**, Anda harus mengaktifkan izin Microsoft Graph dan memberikan admin consent.
1. Di Entra ID (Azure AD) **App Registration**, tambahkan Microsoft Graph **Application permissions**:
- `ChannelMessage.Read.All` (lampiran channel + riwayat)
- `Chat.Read.All` atau `ChatMessage.Read.All` (obrolan grup)
2. **Berikan admin consent** untuk tenant.
3. Naikkan **versi manifest** aplikasi Teams, unggah ulang, dan **instal ulang aplikasi di Teams**.
4. **Keluar sepenuhnya lalu jalankan ulang Teams** untuk membersihkan metadata aplikasi yang di-cache.
**Izin tambahan untuk mention pengguna:** Mention @pengguna berfungsi langsung untuk pengguna dalam percakapan. Namun, jika Anda ingin mencari dan me-mention pengguna secara dinamis yang **tidak berada dalam percakapan saat ini**, tambahkan izin `User.Read.All` (Application) dan berikan admin consent.
## Keterbatasan yang diketahui
### Timeout webhook
Teams mengirim pesan melalui webhook HTTP. Jika pemrosesan terlalu lama (misalnya respons LLM lambat), Anda mungkin melihat:
- Timeout gateway
- Teams mencoba ulang pesan (menyebabkan duplikasi)
- Balasan yang terlewat
OpenClaw menanganinya dengan mengembalikan respons dengan cepat dan mengirim balasan secara proaktif, tetapi respons yang sangat lambat masih dapat menyebabkan masalah.
### Pemformatan
Markdown Teams lebih terbatas daripada Slack atau Discord:
- Pemformatan dasar berfungsi: **tebal**, _miring_, `code`, tautan
- Markdown kompleks (tabel, daftar bertingkat) mungkin tidak dirender dengan benar
- Adaptive Cards didukung untuk poll dan pengiriman card arbitrer (lihat di bawah)
## Konfigurasi
Setelan utama (lihat `/gateway/configuration` untuk pola channel bersama):
- `channels.msteams.enabled`: aktifkan/nonaktifkan channel.
- `channels.msteams.appId`, `channels.msteams.appPassword`, `channels.msteams.tenantId`: kredensial bot.
- `channels.msteams.webhook.port` (default `3978`)
- `channels.msteams.webhook.path` (default `/api/messages`)
- `channels.msteams.dmPolicy`: `pairing | allowlist | open | disabled` (default: pairing)
- `channels.msteams.allowFrom`: allowlist DM (AAD object ID direkomendasikan). Wizard me-resolve nama ke ID selama setup saat akses Graph tersedia.
- `channels.msteams.dangerouslyAllowNameMatching`: toggle break-glass untuk mengaktifkan kembali pencocokan UPN/nama tampilan yang bisa berubah dan perutean langsung nama team/channel.
- `channels.msteams.textChunkLimit`: ukuran chunk teks outbound.
- `channels.msteams.chunkMode`: `length` (default) atau `newline` untuk memisah berdasarkan baris kosong (batas paragraf) sebelum chunking berdasarkan panjang.
- `channels.msteams.mediaAllowHosts`: allowlist untuk host lampiran masuk (default ke domain Microsoft/Teams).
- `channels.msteams.mediaAuthAllowHosts`: allowlist untuk melampirkan header Authorization pada percobaan ulang media (default ke host Graph + Bot Framework).
- `channels.msteams.requireMention`: wajibkan @mention di channel/grup (default true).
- `channels.msteams.replyStyle`: `thread | top-level` (lihat [Gaya Balasan](#reply-style-threads-vs-posts)).
- `channels.msteams.teams.<teamId>.replyStyle`: override per-team.
- `channels.msteams.teams.<teamId>.requireMention`: override per-team.
- `channels.msteams.teams.<teamId>.tools`: override kebijakan tool default per-team (`allow`/`deny`/`alsoAllow`) yang digunakan saat override channel tidak ada.
- `channels.msteams.teams.<teamId>.toolsBySender`: override kebijakan tool per-pengirim default per-team (`"*"` wildcard didukung).
- `channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle`: override per-channel.
- `channels.msteams.teams.<teamId>.channels.<conversationId>.requireMention`: override per-channel.
- `channels.msteams.teams.<teamId>.channels.<conversationId>.tools`: override kebijakan tool per-channel (`allow`/`deny`/`alsoAllow`).
- `channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender`: override kebijakan tool per-pengirim per-channel (`"*"` wildcard didukung).
- Kunci `toolsBySender` sebaiknya menggunakan prefiks eksplisit:
`id:`, `e164:`, `username:`, `name:` (kunci lama tanpa prefiks masih dipetakan hanya ke `id:`).
- `channels.msteams.actions.memberInfo`: aktifkan atau nonaktifkan aksi info anggota berbasis Graph (default: aktif saat kredensial Graph tersedia).
- `channels.msteams.sharePointSiteId`: SharePoint site ID untuk upload file di obrolan grup/channel (lihat [Mengirim file di obrolan grup](#sending-files-in-group-chats)).
## Perutean & Sesi
- Kunci sesi mengikuti format agen standar (lihat [/concepts/session](/concepts/session)):
- Direct message berbagi sesi utama (`agent:<agentId>:<mainKey>`).
- Pesan channel/grup menggunakan ID percakapan:
- `agent:<agentId>:msteams:channel:<conversationId>`
- `agent:<agentId>:msteams:group:<conversationId>`
## Gaya Balasan: Threads vs Posts
Teams baru-baru ini memperkenalkan dua gaya UI channel di atas model data dasar yang sama:
| Gaya | Deskripsi | `replyStyle` yang direkomendasikan |
| ----------------------- | ------------------------------------------------------ | ---------------------------------- |
| **Posts** (klasik) | Pesan muncul sebagai kartu dengan balasan ber-thread di bawahnya | `thread` (default) |
| **Threads** (mirip Slack) | Pesan mengalir secara linear, lebih mirip Slack | `top-level` |
**Masalahnya:** API Teams tidak mengekspos gaya UI channel yang digunakan. Jika Anda menggunakan `replyStyle` yang salah:
- `thread` di channel bergaya Threads → balasan muncul bertingkat secara janggal
- `top-level` di channel bergaya Posts → balasan muncul sebagai post top-level terpisah, bukan di dalam thread
**Solusi:** Konfigurasikan `replyStyle` per-channel berdasarkan cara channel disiapkan:
```json5
{
channels: {
msteams: {
replyStyle: "thread",
teams: {
"19:abc...@thread.tacv2": {
channels: {
"19:xyz...@thread.tacv2": {
replyStyle: "top-level",
},
},
},
},
},
},
}
```
## Lampiran & Gambar
**Keterbatasan saat ini:**
- **DM:** Gambar dan lampiran file berfungsi melalui API file bot Teams.
- **Channel/grup:** Lampiran berada di penyimpanan M365 (SharePoint/OneDrive). Payload webhook hanya menyertakan stub HTML, bukan byte file yang sebenarnya. **Izin Graph API diperlukan** untuk mengunduh lampiran channel.
- Untuk pengiriman eksplisit yang mengutamakan file, gunakan `action=upload-file` dengan `media` / `filePath` / `path`; `message` opsional menjadi teks/komentar pendamping, dan `filename` menimpa nama yang diunggah.
Tanpa izin Graph, pesan channel dengan gambar akan diterima sebagai teks saja (konten gambar tidak dapat diakses bot).
Secara default, OpenClaw hanya mengunduh media dari hostname Microsoft/Teams. Timpa dengan `channels.msteams.mediaAllowHosts` (gunakan `["*"]` untuk mengizinkan host mana pun).
Header Authorization hanya dilampirkan untuk host dalam `channels.msteams.mediaAuthAllowHosts` (default ke host Graph + Bot Framework). Jaga daftar ini tetap ketat (hindari suffix multi-tenant).
## Mengirim file di obrolan grup
Bot dapat mengirim file di DM menggunakan alur FileConsentCard (bawaan). Namun, **mengirim file di obrolan grup/channel** memerlukan setup tambahan:
| Konteks | Cara file dikirim | Setup yang diperlukan |
| ------------------------ | -------------------------------------------- | -------------------------------------------------- |
| **DM** | FileConsentCard → pengguna menerima → bot mengunggah | Langsung berfungsi |
| **Obrolan grup/channel** | Unggah ke SharePoint → bagikan tautan | Memerlukan `sharePointSiteId` + izin Graph |
| **Gambar (konteks apa pun)** | Inline berkode Base64 | Langsung berfungsi |
### Mengapa obrolan grup memerlukan SharePoint
Bot tidak memiliki drive OneDrive personal (endpoint Graph API `/me/drive` tidak berfungsi untuk identitas aplikasi). Untuk mengirim file di obrolan grup/channel, bot mengunggah ke **situs SharePoint** dan membuat tautan berbagi.
### Setup
1. **Tambahkan izin Graph API** di Entra ID (Azure AD) → App Registration:
- `Sites.ReadWrite.All` (Application) - unggah file ke SharePoint
- `Chat.Read.All` (Application) - opsional, mengaktifkan tautan berbagi per-pengguna
2. **Berikan admin consent** untuk tenant.
3. **Dapatkan ID situs SharePoint Anda:**
```bash
# Via Graph Explorer atau curl dengan token yang valid:
curl -H "Authorization: Bearer $TOKEN" \
"https://graph.microsoft.com/v1.0/sites/{hostname}:/{site-path}"
# Contoh: untuk situs di "contoso.sharepoint.com/sites/BotFiles"
curl -H "Authorization: Bearer $TOKEN" \
"https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/sites/BotFiles"
# Respons mencakup: "id": "contoso.sharepoint.com,guid1,guid2"
```
4. **Konfigurasikan OpenClaw:**
```json5
{
channels: {
msteams: {
// ... config lain ...
sharePointSiteId: "contoso.sharepoint.com,guid1,guid2",
},
},
}
```
### Perilaku berbagi
| Izin | Perilaku berbagi |
| --------------------------------------- | --------------------------------------------------------- |
| `Sites.ReadWrite.All` saja | Tautan berbagi ke seluruh organisasi (siapa pun di org dapat mengakses) |
| `Sites.ReadWrite.All` + `Chat.Read.All` | Tautan berbagi per-pengguna (hanya anggota chat yang dapat mengakses) |
Berbagi per-pengguna lebih aman karena hanya peserta chat yang dapat mengakses file. Jika izin `Chat.Read.All` tidak ada, bot fallback ke berbagi seluruh organisasi.
### Perilaku fallback
| Skenario | Hasil |
| ------------------------------------------------- | -------------------------------------------------- |
| Obrolan grup + file + `sharePointSiteId` dikonfigurasi | Unggah ke SharePoint, kirim tautan berbagi |
| Obrolan grup + file + tanpa `sharePointSiteId` | Coba unggah ke OneDrive (mungkin gagal), kirim teks saja |
| Obrolan personal + file | Alur FileConsentCard (berfungsi tanpa SharePoint) |
| Konteks apa pun + gambar | Inline berkode Base64 (berfungsi tanpa SharePoint) |
### Lokasi penyimpanan file
File yang diunggah disimpan di folder `/OpenClawShared/` di pustaka dokumen default situs SharePoint yang dikonfigurasi.
## Poll (Adaptive Cards)
OpenClaw mengirim poll Teams sebagai Adaptive Cards (tidak ada API poll Teams bawaan).
- CLI: `openclaw message poll --channel msteams --target conversation:<id> ...`
- Suara dicatat oleh gateway di `~/.openclaw/msteams-polls.json`.
- Gateway harus tetap online untuk mencatat suara.
- Poll belum otomatis mem-posting ringkasan hasil (periksa file penyimpanan jika perlu).
## Adaptive Cards (arbitrer)
Kirim JSON Adaptive Card apa pun ke pengguna atau percakapan Teams menggunakan tool `message` atau CLI.
Parameter `card` menerima objek JSON Adaptive Card. Saat `card` disediakan, teks pesan bersifat opsional.
**Tool agen:**
```json5
{
action: "send",
channel: "msteams",
target: "user:<id>",
card: {
type: "AdaptiveCard",
version: "1.5",
body: [{ type: "TextBlock", text: "Hello!" }],
},
}
```
**CLI:**
```bash
openclaw message send --channel msteams \
--target "conversation:19:abc...@thread.tacv2" \
--card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Hello!"}]}'
```
Lihat [dokumentasi Adaptive Cards](https://adaptivecards.io/) untuk skema card dan contoh. Untuk detail format target, lihat [Format target](#target-formats) di bawah.
## Format target
Target MSTeams menggunakan prefiks untuk membedakan pengguna dan percakapan:
| Jenis target | Format | Contoh |
| -------------------- | -------------------------------- | --------------------------------------------------- |
| Pengguna (berdasarkan ID) | `user:<aad-object-id>` | `user:40a1a0ed-4ff2-4164-a219-55518990c197` |
| Pengguna (berdasarkan nama) | `user:<display-name>` | `user:John Smith` (memerlukan Graph API) |
| Grup/channel | `conversation:<conversation-id>` | `conversation:19:abc123...@thread.tacv2` |
| Grup/channel (mentah) | `<conversation-id>` | `19:abc123...@thread.tacv2` (jika mengandung `@thread`) |
**Contoh CLI:**
```bash
# Kirim ke pengguna berdasarkan ID
openclaw message send --channel msteams --target "user:40a1a0ed-..." --message "Hello"
# Kirim ke pengguna berdasarkan nama tampilan (memicu lookup Graph API)
openclaw message send --channel msteams --target "user:John Smith" --message "Hello"
# Kirim ke obrolan grup atau channel
openclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" --message "Hello"
# Kirim Adaptive Card ke percakapan
openclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" \
--card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Hello"}]}'
```
**Contoh tool agen:**
```json5
{
action: "send",
channel: "msteams",
target: "user:John Smith",
message: "Hello!",
}
```
```json5
{
action: "send",
channel: "msteams",
target: "conversation:19:abc...@thread.tacv2",
card: {
type: "AdaptiveCard",
version: "1.5",
body: [{ type: "TextBlock", text: "Hello" }],
},
}
```
Catatan: Tanpa prefiks `user:`, nama secara default di-resolve sebagai grup/team. Selalu gunakan `user:` saat menargetkan orang berdasarkan nama tampilan.
## Pesan proaktif
- Pesan proaktif hanya dimungkinkan **setelah** pengguna berinteraksi, karena saat itulah kami menyimpan referensi percakapan.
- Lihat `/gateway/configuration` untuk gating `dmPolicy` dan allowlist.
## ID Team dan Channel (Jebakan Umum)
Parameter kueri `groupId` di URL Teams **BUKAN** team ID yang digunakan untuk konfigurasi. Ekstrak ID dari path URL sebagai gantinya:
**URL Team:**
```
https://teams.microsoft.com/l/team/19%3ABk4j...%40thread.tacv2/conversations?groupId=...
└────────────────────────────┘
Team ID (URL-decode ini)
```
**URL Channel:**
```
https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?groupId=...
└─────────────────────────┘
Channel ID (URL-decode ini)
```
**Untuk config:**
- Team ID = segmen path setelah `/team/` (URL-decoded, mis. `19:Bk4j...@thread.tacv2`)
- Channel ID = segmen path setelah `/channel/` (URL-decoded)
- **Abaikan** parameter kueri `groupId`
## Channel Privat
Bot memiliki dukungan terbatas di channel privat:
| Fitur | Channel Standar | Channel Privat |
| ---------------------------- | --------------- | --------------------- |
| Instalasi bot | Ya | Terbatas |
| Pesan real-time (webhook) | Ya | Mungkin tidak berfungsi |
| Izin RSC | Ya | Dapat berperilaku berbeda |
| @mentions | Ya | Jika bot dapat diakses |
| Riwayat Graph API | Ya | Ya (dengan izin) |
**Solusi sementara jika channel privat tidak berfungsi:**
1. Gunakan channel standar untuk interaksi bot
2. Gunakan DM - pengguna selalu dapat mengirim pesan langsung ke bot
3. Gunakan Graph API untuk akses historis (memerlukan `ChannelMessage.Read.All`)
## Pemecahan masalah
### Masalah umum
- **Gambar tidak muncul di channel:** izin Graph atau admin consent belum ada. Instal ulang aplikasi Teams dan keluar/buka kembali Teams sepenuhnya.
- **Tidak ada respons di channel:** mention diwajibkan secara default; set `channels.msteams.requireMention=false` atau konfigurasikan per team/channel.
- **Ketidakcocokan versi (Teams masih menampilkan manifest lama):** hapus + tambahkan kembali aplikasi dan keluar sepenuhnya dari Teams untuk refresh.
- **401 Unauthorized dari webhook:** Wajar saat menguji manual tanpa Azure JWT - artinya endpoint dapat dijangkau tetapi autentikasi gagal. Gunakan Azure Web Chat untuk menguji dengan benar.
### Error upload manifest
- **"Icon file cannot be empty":** Manifest merujuk file ikon yang berukuran 0 byte. Buat ikon PNG yang valid (32x32 untuk `outline.png`, 192x192 untuk `color.png`).
- **"webApplicationInfo.Id already in use":** Aplikasi masih terinstal di team/chat lain. Temukan dan uninstall terlebih dahulu, atau tunggu 5-10 menit untuk propagasi.
- **"Something went wrong" saat upload:** Unggah melalui [https://admin.teams.microsoft.com](https://admin.teams.microsoft.com), lalu buka browser DevTools (F12) → tab Network, dan periksa body respons untuk error sebenarnya.
- **Sideload gagal:** Coba "Upload an app to your org's app catalog" alih-alih "Upload a custom app" - ini sering melewati pembatasan sideload.
### Izin RSC tidak berfungsi
1. Verifikasi `webApplicationInfo.id` cocok persis dengan App ID bot Anda
2. Unggah ulang aplikasi dan instal ulang di team/chat
3. Periksa apakah admin organisasi Anda memblokir izin RSC
4. Pastikan Anda menggunakan scope yang benar: `ChannelMessage.Read.Group` untuk teams, `ChatMessage.Read.Chat` untuk obrolan grup
## Referensi
- [Create Azure Bot](https://learn.microsoft.com/en-us/azure/bot-service/bot-service-quickstart-registration) - panduan setup Azure Bot
- [Teams Developer Portal](https://dev.teams.microsoft.com/apps) - membuat/mengelola aplikasi Teams
- [Skema manifest aplikasi Teams](https://learn.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema)
- [Menerima pesan channel dengan RSC](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/channel-messages-with-rsc)
- [Referensi izin RSC](https://learn.microsoft.com/en-us/microsoftteams/platform/graph-api/rsc/resource-specific-consent)
- [Penanganan file bot Teams](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/bots-filesv4) (channel/grup memerlukan Graph)
- [Pesan proaktif](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/send-proactive-messages)
## Terkait
- [Ringkasan Channel](/channels) — semua channel yang didukung
- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing
- [Groups](/channels/groups) — perilaku obrolan grup dan gating mention
- [Channel Routing](/channels/channel-routing) — perutean sesi untuk pesan
- [Keamanan](/gateway/security) — model akses dan hardening

156
docs/id/channels/nextcloud-talk.md Normal file
View File

@ -0,0 +1,156 @@
---
read_when:
- Sedang mengerjakan fitur channel Nextcloud Talk
summary: Status dukungan, kapabilitas, dan konfigurasi Nextcloud Talk
title: Nextcloud Talk
x-i18n:
generated_at: "2026-04-05T13:43:40Z"
model: gpt-5.4
provider: openai
source_hash: 900402afe67cf3ce96103d55158eb28cffb29c9845b77248e70d7653b12ae810
source_path: channels/nextcloud-talk.md
workflow: 15
---
# Nextcloud Talk
Status: plugin bawaan (bot webhook). Direct message, room, reactions, dan pesan markdown didukung.
## Plugin bawaan
Nextcloud Talk dikirim sebagai plugin bawaan dalam rilis OpenClaw saat ini, jadi
build terpaket normal tidak memerlukan instalasi terpisah.
Jika Anda menggunakan build lama atau instalasi kustom yang tidak menyertakan Nextcloud Talk,
instal secara manual:
Instal melalui CLI (registry npm):
```bash
openclaw plugins install @openclaw/nextcloud-talk
```
Checkout lokal (saat berjalan dari repo git):
```bash
openclaw plugins install ./path/to/local/nextcloud-talk-plugin
```
Detail: [Plugins](/tools/plugin)
## Penyiapan cepat (pemula)
1. Pastikan plugin Nextcloud Talk tersedia.
- Rilis OpenClaw terpaket saat ini sudah menyertakannya.
- Instalasi lama/kustom dapat menambahkannya secara manual dengan perintah di atas.
2. Di server Nextcloud Anda, buat bot:
```bash
./occ talk:bot:install "OpenClaw" "<shared-secret>" "<webhook-url>" --feature reaction
```
3. Aktifkan bot di pengaturan room target.
4. Konfigurasikan OpenClaw:
- Config: `channels.nextcloud-talk.baseUrl` + `channels.nextcloud-talk.botSecret`
- Atau env: `NEXTCLOUD_TALK_BOT_SECRET` (hanya akun default)
5. Mulai ulang gateway (atau selesaikan penyiapan).
Config minimal:
```json5
{
channels: {
"nextcloud-talk": {
enabled: true,
baseUrl: "https://cloud.example.com",
botSecret: "shared-secret",
dmPolicy: "pairing",
},
},
}
```
## Catatan
- Bot tidak dapat memulai DM. Pengguna harus mengirim pesan ke bot terlebih dahulu.
- URL webhook harus dapat dijangkau oleh Gateway; atur `webhookPublicUrl` jika berada di balik proxy.
- Unggahan media tidak didukung oleh API bot; media dikirim sebagai URL.
- Payload webhook tidak membedakan DM vs room; atur `apiUser` + `apiPassword` untuk mengaktifkan lookup tipe room (jika tidak, DM diperlakukan sebagai room).
## Kontrol akses (DM)
- Default: `channels.nextcloud-talk.dmPolicy = "pairing"`. Pengirim yang tidak dikenal mendapatkan kode pairing.
- Setujui melalui:
- `openclaw pairing list nextcloud-talk`
- `openclaw pairing approve nextcloud-talk <CODE>`
- DM publik: `channels.nextcloud-talk.dmPolicy="open"` ditambah `channels.nextcloud-talk.allowFrom=["*"]`.
- `allowFrom` hanya cocok dengan ID pengguna Nextcloud; nama tampilan diabaikan.
## Room (grup)
- Default: `channels.nextcloud-talk.groupPolicy = "allowlist"` (dibatasi mention).
- Masukkan room ke allowlist dengan `channels.nextcloud-talk.rooms`:
```json5
{
channels: {
"nextcloud-talk": {
rooms: {
"room-token": { requireMention: true },
},
},
},
}
```
- Untuk tidak mengizinkan room apa pun, biarkan allowlist kosong atau atur `channels.nextcloud-talk.groupPolicy="disabled"`.
## Kapabilitas
| Fitur | Status |
| --------------- | ----------------- |
| Direct message | Didukung |
| Room | Didukung |
| Thread | Tidak didukung |
| Media | Hanya URL |
| Reactions | Didukung |
| Perintah native | Tidak didukung |
## Referensi konfigurasi (Nextcloud Talk)
Konfigurasi lengkap: [Configuration](/gateway/configuration)
Opsi provider:
- `channels.nextcloud-talk.enabled`: aktifkan/nonaktifkan startup channel.
- `channels.nextcloud-talk.baseUrl`: URL instance Nextcloud.
- `channels.nextcloud-talk.botSecret`: rahasia bersama bot.
- `channels.nextcloud-talk.botSecretFile`: path rahasia file reguler. Symlink ditolak.
- `channels.nextcloud-talk.apiUser`: pengguna API untuk lookup room (deteksi DM).
- `channels.nextcloud-talk.apiPassword`: kata sandi API/aplikasi untuk lookup room.
- `channels.nextcloud-talk.apiPasswordFile`: path file kata sandi API.
- `channels.nextcloud-talk.webhookPort`: port listener webhook (default: 8788).
- `channels.nextcloud-talk.webhookHost`: host webhook (default: 0.0.0.0).
- `channels.nextcloud-talk.webhookPath`: path webhook (default: /nextcloud-talk-webhook).
- `channels.nextcloud-talk.webhookPublicUrl`: URL webhook yang dapat dijangkau secara eksternal.
- `channels.nextcloud-talk.dmPolicy`: `pairing | allowlist | open | disabled`.
- `channels.nextcloud-talk.allowFrom`: allowlist DM (ID pengguna). `open` memerlukan `"*"`.
- `channels.nextcloud-talk.groupPolicy`: `allowlist | open | disabled`.
- `channels.nextcloud-talk.groupAllowFrom`: allowlist grup (ID pengguna).
- `channels.nextcloud-talk.rooms`: pengaturan per-room dan allowlist.
- `channels.nextcloud-talk.historyLimit`: batas riwayat grup (0 menonaktifkan).
- `channels.nextcloud-talk.dmHistoryLimit`: batas riwayat DM (0 menonaktifkan).
- `channels.nextcloud-talk.dms`: override per-DM (`historyLimit`).
- `channels.nextcloud-talk.textChunkLimit`: ukuran potongan teks keluar (karakter).
- `channels.nextcloud-talk.chunkMode`: `length` (default) atau `newline` untuk membagi pada baris kosong (batas paragraf) sebelum pemotongan berdasarkan panjang.
- `channels.nextcloud-talk.blockStreaming`: nonaktifkan block streaming untuk channel ini.
- `channels.nextcloud-talk.blockStreamingCoalesce`: tuning penggabungan block streaming.
- `channels.nextcloud-talk.mediaMaxMb`: batas media masuk (MB).
## Terkait
- [Ikhtisar Channels](/channels) — semua channel yang didukung
- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing
- [Groups](/channels/groups) — perilaku obrolan grup dan pembatasan mention
- [Channel Routing](/channels/channel-routing) — perutean sesi untuk pesan
- [Security](/gateway/security) — model akses dan penguatan

259
docs/id/channels/nostr.md Normal file
View File

@ -0,0 +1,259 @@
---
read_when:
- Anda ingin OpenClaw menerima DM melalui Nostr
- Anda sedang menyiapkan pesan terdesentralisasi
summary: Channel DM Nostr melalui pesan terenkripsi NIP-04
title: Nostr
x-i18n:
generated_at: "2026-04-05T13:43:44Z"
model: gpt-5.4
provider: openai
source_hash: f82829ee66fbeb3367007af343797140049ea49f2e842a695fa56acea0c80728
source_path: channels/nostr.md
workflow: 15
---
# Nostr
**Status:** Plugin bawaan opsional (dinonaktifkan secara default sampai dikonfigurasi).
Nostr adalah protokol terdesentralisasi untuk jejaring sosial. Channel ini memungkinkan OpenClaw menerima dan merespons pesan langsung terenkripsi (DM) melalui NIP-04.
## Plugin bawaan
Rilis OpenClaw saat ini mengirimkan Nostr sebagai plugin bawaan, jadi build paket normal
tidak memerlukan instalasi terpisah.
### Instalasi lama/kustom
- Onboarding (`openclaw onboard`) dan `openclaw channels add` tetap menampilkan
Nostr dari katalog channel bersama.
- Jika build Anda tidak menyertakan Nostr bawaan, instal secara manual.
```bash
openclaw plugins install @openclaw/nostr
```
Gunakan checkout lokal (workflow dev):
```bash
openclaw plugins install --link <path-to-local-nostr-plugin>
```
Restart Gateway setelah menginstal atau mengaktifkan plugin.
### Setup non-interaktif
```bash
openclaw channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY"
openclaw channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY" --relay-urls "wss://relay.damus.io,wss://relay.primal.net"
```
Gunakan `--use-env` agar `NOSTR_PRIVATE_KEY` tetap berada di environment alih-alih menyimpan key di config.
## Setup cepat
1. Buat keypair Nostr (jika perlu):
```bash
# Using nak
nak key generate
```
2. Tambahkan ke config:
```json5
{
channels: {
nostr: {
privateKey: "${NOSTR_PRIVATE_KEY}",
},
},
}
```
3. Ekspor key:
```bash
export NOSTR_PRIVATE_KEY="nsec1..."
```
4. Restart Gateway.
## Referensi konfigurasi
| Key | Tipe | Default | Deskripsi |
| ------------ | -------- | ------------------------------------------- | ------------------------------------ |
| `privateKey` | string | wajib | Private key dalam format `nsec` atau hex |
| `relays` | string[] | `['wss://relay.damus.io', 'wss://nos.lol']` | URL relay (WebSocket) |
| `dmPolicy` | string | `pairing` | Kebijakan akses DM |
| `allowFrom` | string[] | `[]` | Pubkey pengirim yang diizinkan |
| `enabled` | boolean | `true` | Aktifkan/nonaktifkan channel |
| `name` | string | - | Nama tampilan |
| `profile` | object | - | Metadata profil NIP-01 |
## Metadata profil
Data profil dipublikasikan sebagai peristiwa NIP-01 `kind:0`. Anda dapat mengelolanya dari UI Control (Channels -> Nostr -> Profile) atau menyetelnya langsung di config.
Contoh:
```json5
{
channels: {
nostr: {
privateKey: "${NOSTR_PRIVATE_KEY}",
profile: {
name: "openclaw",
displayName: "OpenClaw",
about: "Personal assistant DM bot",
picture: "https://example.com/avatar.png",
banner: "https://example.com/banner.png",
website: "https://example.com",
nip05: "openclaw@example.com",
lud16: "openclaw@example.com",
},
},
},
}
```
Catatan:
- URL profil harus menggunakan `https://`.
- Mengimpor dari relay akan menggabungkan field dan mempertahankan override lokal.
## Kontrol akses
### Kebijakan DM
- **pairing** (default): pengirim yang tidak dikenal mendapatkan kode pairing.
- **allowlist**: hanya pubkey dalam `allowFrom` yang dapat mengirim DM.
- **open**: DM masuk publik (memerlukan `allowFrom: ["*"]`).
- **disabled**: abaikan DM masuk.
Catatan penegakan:
- Tanda tangan peristiwa masuk diverifikasi sebelum kebijakan pengirim dan dekripsi NIP-04, sehingga peristiwa palsu ditolak lebih awal.
- Balasan pairing dikirim tanpa memproses isi DM asli.
- DM masuk dibatasi lajunya dan payload yang terlalu besar dibuang sebelum dekripsi.
### Contoh allowlist
```json5
{
channels: {
nostr: {
privateKey: "${NOSTR_PRIVATE_KEY}",
dmPolicy: "allowlist",
allowFrom: ["npub1abc...", "npub1xyz..."],
},
},
}
```
## Format key
Format yang diterima:
- **Private key:** `nsec...` atau hex 64 karakter
- **Pubkey (`allowFrom`):** `npub...` atau hex
## Relay
Default: `relay.damus.io` dan `nos.lol`.
```json5
{
channels: {
nostr: {
privateKey: "${NOSTR_PRIVATE_KEY}",
relays: ["wss://relay.damus.io", "wss://relay.primal.net", "wss://nostr.wine"],
},
},
}
```
Tips:
- Gunakan 2-3 relay untuk redundansi.
- Hindari terlalu banyak relay (latensi, duplikasi).
- Relay berbayar dapat meningkatkan keandalan.
- Relay lokal cocok untuk pengujian (`ws://localhost:7777`).
## Dukungan protokol
| NIP | Status | Deskripsi |
| ------ | ------------ | ----------------------------------- |
| NIP-01 | Didukung | Format peristiwa dasar + metadata profil |
| NIP-04 | Didukung | DM terenkripsi (`kind:4`) |
| NIP-17 | Direncanakan | DM gift-wrapped |
| NIP-44 | Direncanakan | Enkripsi berversi |
## Pengujian
### Relay lokal
```bash
# Start strfry
docker run -p 7777:7777 ghcr.io/hoytech/strfry
```
```json5
{
channels: {
nostr: {
privateKey: "${NOSTR_PRIVATE_KEY}",
relays: ["ws://localhost:7777"],
},
},
}
```
### Pengujian manual
1. Catat pubkey bot (npub) dari log.
2. Buka klien Nostr (Damus, Amethyst, dll.).
3. Kirim DM ke pubkey bot.
4. Verifikasi responsnya.
## Pemecahan masalah
### Tidak menerima pesan
- Verifikasi bahwa private key valid.
- Pastikan URL relay dapat dijangkau dan menggunakan `wss://` (atau `ws://` untuk lokal).
- Konfirmasi `enabled` bukan `false`.
- Periksa log Gateway untuk error koneksi relay.
### Tidak mengirim respons
- Periksa apakah relay menerima penulisan.
- Verifikasi konektivitas keluar.
- Perhatikan rate limit relay.
### Respons duplikat
- Ini normal saat menggunakan beberapa relay.
- Pesan dideduplikasi berdasarkan ID peristiwa; hanya pengiriman pertama yang memicu respons.
## Keamanan
- Jangan pernah meng-commit private key.
- Gunakan variabel environment untuk key.
- Pertimbangkan `allowlist` untuk bot produksi.
- Tanda tangan diverifikasi sebelum kebijakan pengirim, dan kebijakan pengirim diberlakukan sebelum dekripsi, sehingga peristiwa palsu ditolak lebih awal dan pengirim yang tidak dikenal tidak dapat memaksa kerja kripto penuh.
## Keterbatasan (MVP)
- Hanya pesan langsung (tanpa obrolan grup).
- Tidak ada lampiran media.
- Hanya NIP-04 (gift-wrap NIP-17 direncanakan).
## Terkait
- [Ikhtisar Channels](/channels) — semua channel yang didukung
- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing
- [Grup](/channels/groups) — perilaku obrolan grup dan gating mention
- [Channel Routing](/channels/channel-routing) — routing sesi untuk pesan
- [Keamanan](/gateway/security) — model akses dan hardening

136
docs/id/channels/pairing.md Normal file
View File

@ -0,0 +1,136 @@
---
read_when:
- Menyiapkan kontrol akses DM
- Melakukan pairing node iOS/Android baru
- Meninjau postur keamanan OpenClaw
summary: 'Ikhtisar pairing: setujui siapa yang dapat mengirimi Anda DM + node mana yang dapat bergabung'
title: Pairing
x-i18n:
generated_at: "2026-04-05T13:43:46Z"
model: gpt-5.4
provider: openai
source_hash: 2bd99240b3530def23c05a26915d07cf8b730565c2822c6338437f8fb3f285c9
source_path: channels/pairing.md
workflow: 15
---
# Pairing
“Pairing” adalah langkah **persetujuan pemilik** eksplisit 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)
Konteks keamanan: [Keamanan](/gateway/security)
## 1) Pairing DM (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.
Kebijakan DM default didokumentasikan di: [Keamanan](/gateway/security)
Kode pairing:
- 8 karakter, huruf besar, tanpa karakter 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.
### Menyetujui pengirim
```bash
openclaw pairing list telegram
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
Disimpan di bawah `~/.openclaw/credentials/`:
- Permintaan tertunda: `<channel>-pairing.json`
- Penyimpanan allowlist yang disetujui:
- Akun default: `<channel>-allowFrom.json`
- Akun non-default: `<channel>-<accountId>-allowFrom.json`
Perilaku cakupan akun:
- Akun non-default hanya membaca/menulis file allowlist dalam cakupannya.
- Akun default menggunakan file allowlist tanpa cakupan yang dicakup per channel.
Anggap ini sensitif (karena menentukan 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).
## 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)
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).
3. Di ponsel Anda, buka aplikasi OpenClaw iOS → Settings → Gateway.
4. Tempel kode penyiapan lalu sambungkan.
5. Kembali ke Telegram: `/pair pending` (tinjau ID permintaan, role, dan scope), lalu setujui.
Kode penyiapan adalah payload JSON terenkripsi base64 yang berisi:
- `url`: URL WebSocket Gateway (`ws://...` atau `wss://...`)
- `bootstrapToken`: token bootstrap satu perangkat yang berumur pendek dan 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:
`operator.approvals`, `operator.read`, `operator.talk.secrets`, `operator.write`
- pemeriksaan scope bootstrap diberi awalan 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
Perlakukan kode penyiapan seperti kata sandi selama masih berlaku.
### Menyetujui perangkat node
```bash
openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>
```
Jika perangkat yang sama mencoba lagi dengan detail autentikasi berbeda (misalnya
role/scope/public key yang berbeda), permintaan tertunda sebelumnya akan digantikan dan
`requestId` baru akan dibuat.
### Penyimpanan status pairing node
Disimpan di bawah `~/.openclaw/devices/`:
- `pending.json` (berumur pendek; permintaan tertunda akan kedaluwarsa)
- `paired.json` (perangkat yang sudah dipairing + 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.
## Dokumen terkait
- Model keamanan + prompt injection: [Keamanan](/gateway/security)
- Memperbarui dengan aman (jalankan doctor): [Memperbarui](/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)

200
docs/id/channels/qqbot.md Normal file
View File

@ -0,0 +1,200 @@
---
read_when:
- Anda ingin menghubungkan OpenClaw ke QQ
- Anda memerlukan penyiapan kredensial QQ Bot
- Anda ingin dukungan grup atau obrolan pribadi QQ Bot
summary: Penyiapan, konfigurasi, dan penggunaan QQ Bot
title: QQ Bot
x-i18n:
generated_at: "2026-04-05T13:43:54Z"
model: gpt-5.4
provider: openai
source_hash: 0e58fb7b07c59ecbf80a1276368c4a007b45d84e296ed40cffe9845e0953696c
source_path: channels/qqbot.md
workflow: 15
---
# QQ Bot
QQ Bot terhubung ke OpenClaw melalui API resmi QQ Bot (gateway WebSocket). Plugin
ini mendukung obrolan pribadi C2C, @message grup, dan pesan channel guild dengan
media kaya (gambar, suara, video, file).
Status: plugin bawaan. Pesan langsung, obrolan grup, channel guild, dan
media didukung. Reaksi dan thread tidak didukung.
## Plugin bawaan
Rilis OpenClaw saat ini menyertakan QQ Bot, jadi build paket normal tidak memerlukan
langkah `openclaw plugins install` terpisah.
## Penyiapan
1. Buka [QQ Open Platform](https://q.qq.com/) dan pindai kode QR dengan
QQ di ponsel Anda untuk mendaftar / masuk.
2. Klik **Create Bot** untuk membuat bot QQ baru.
3. Temukan **AppID** dan **AppSecret** di halaman pengaturan bot dan salin.
> AppSecret tidak disimpan dalam plaintext — jika Anda meninggalkan halaman tanpa menyimpannya,
> Anda harus membuat ulang yang baru.
4. Tambahkan channel:
```bash
openclaw channels add --channel qqbot --token "AppID:AppSecret"
```
5. Mulai ulang Gateway.
Path penyiapan interaktif:
```bash
openclaw channels add
openclaw configure --section channels
```
## Konfigurasi
Konfigurasi minimal:
```json5
{
channels: {
qqbot: {
enabled: true,
appId: "YOUR_APP_ID",
clientSecret: "YOUR_APP_SECRET",
},
},
}
```
Variabel lingkungan akun default:
- `QQBOT_APP_ID`
- `QQBOT_CLIENT_SECRET`
AppSecret berbasis file:
```json5
{
channels: {
qqbot: {
enabled: true,
appId: "YOUR_APP_ID",
clientSecretFile: "/path/to/qqbot-secret.txt",
},
},
}
```
Catatan:
- Fallback env hanya berlaku untuk akun default QQ Bot.
- `openclaw channels add --channel qqbot --token-file ...` hanya menyediakan
AppSecret; AppID harus sudah ditetapkan di konfigurasi atau `QQBOT_APP_ID`.
- `clientSecret` juga menerima input SecretRef, bukan hanya string plaintext.
### Penyiapan multi-akun
Jalankan beberapa bot QQ dalam satu instance OpenClaw:
```json5
{
channels: {
qqbot: {
enabled: true,
appId: "111111111",
clientSecret: "secret-of-bot-1",
accounts: {
bot2: {
enabled: true,
appId: "222222222",
clientSecret: "secret-of-bot-2",
},
},
},
},
}
```
Setiap akun meluncurkan koneksi WebSocket-nya sendiri dan mempertahankan cache
token yang independen (diisolasi berdasarkan `appId`).
Tambahkan bot kedua melalui CLI:
```bash
openclaw channels add --channel qqbot --account bot2 --token "222222222:secret-of-bot-2"
```
### Suara (STT / TTS)
Dukungan STT dan TTS menggunakan konfigurasi dua tingkat dengan fallback prioritas:
| Pengaturan | Khusus plugin | Fallback framework |
| ---------- | --------------------- | ----------------------------- |
| STT | `channels.qqbot.stt` | `tools.media.audio.models[0]` |
| TTS | `channels.qqbot.tts` | `messages.tts` |
```json5
{
channels: {
qqbot: {
stt: {
provider: "your-provider",
model: "your-stt-model",
},
tts: {
provider: "your-provider",
model: "your-tts-model",
voice: "your-voice",
},
},
},
}
```
Tetapkan `enabled: false` pada salah satu untuk menonaktifkannya.
Perilaku upload/transcode audio outbound juga dapat disetel dengan
`channels.qqbot.audioFormatPolicy`:
- `sttDirectFormats`
- `uploadDirectFormats`
- `transcodeEnabled`
## Format target
| Format | Deskripsi |
| -------------------------- | ------------------- |
| `qqbot:c2c:OPENID` | Obrolan pribadi (C2C) |
| `qqbot:group:GROUP_OPENID` | Obrolan grup |
| `qqbot:channel:CHANNEL_ID` | Channel guild |
> Setiap bot memiliki kumpulan OpenID penggunanya sendiri. OpenID yang diterima oleh Bot A **tidak dapat**
> digunakan untuk mengirim pesan melalui Bot B.
## Slash command
Perintah bawaan yang dicegat sebelum antrean AI:
| Perintah | Deskripsi |
| -------------- | -------------------------------------- |
| `/bot-ping` | Uji latensi |
| `/bot-version` | Tampilkan versi framework OpenClaw |
| `/bot-help` | Daftarkan semua perintah |
| `/bot-upgrade` | Tampilkan tautan panduan upgrade QQBot |
| `/bot-logs` | Ekspor log gateway terbaru sebagai file |
Tambahkan `?` ke perintah apa pun untuk bantuan penggunaan (misalnya `/bot-upgrade ?`).
## Pemecahan masalah
- **Bot membalas "gone to Mars":** kredensial belum dikonfigurasi atau Gateway belum dijalankan.
- **Tidak ada pesan masuk:** verifikasi bahwa `appId` dan `clientSecret` benar, dan
bot diaktifkan di QQ Open Platform.
- **Penyiapan dengan `--token-file` masih menunjukkan belum dikonfigurasi:** `--token-file` hanya menetapkan
AppSecret. Anda tetap memerlukan `appId` di konfigurasi atau `QQBOT_APP_ID`.
- **Pesan proaktif tidak sampai:** QQ dapat mencegat pesan yang diprakarsai bot jika
pengguna belum berinteraksi baru-baru ini.
- **Suara tidak ditranskripsikan:** pastikan STT sudah dikonfigurasi dan provider dapat dijangkau.

344
docs/id/channels/signal.md Normal file
View File

@ -0,0 +1,344 @@
---
read_when:
- Menyiapkan dukungan Signal
- Men-debug kirim/terima Signal
summary: Dukungan Signal melalui signal-cli (JSON-RPC + SSE), jalur penyiapan, dan model nomor
title: Signal
x-i18n:
generated_at: "2026-04-05T13:44:20Z"
model: gpt-5.4
provider: openai
source_hash: cdd855eb353aca6a1c2b04d14af0e3da079349297b54fa8243562c52b29118d9
source_path: channels/signal.md
workflow: 15
---
# Signal (signal-cli)
Status: integrasi CLI eksternal. Gateway berkomunikasi dengan `signal-cli` melalui HTTP JSON-RPC + SSE.
## Prasyarat
- OpenClaw terinstal di server Anda (alur Linux di bawah telah diuji pada Ubuntu 24).
- `signal-cli` tersedia di host tempat gateway berjalan.
- Nomor telepon yang dapat menerima satu SMS verifikasi (untuk jalur pendaftaran SMS).
- Akses browser untuk captcha Signal (`signalcaptchas.org`) selama pendaftaran.
## Penyiapan cepat (pemula)
1. Gunakan **nomor Signal terpisah** untuk bot (direkomendasikan).
2. Instal `signal-cli` (Java diperlukan jika Anda menggunakan build JVM).
3. Pilih salah satu jalur penyiapan:
- **Jalur A (tautan QR):** `signal-cli link -n "OpenClaw"` lalu pindai dengan Signal.
- **Jalur B (daftar SMS):** daftarkan nomor khusus dengan captcha + verifikasi SMS.
4. Konfigurasikan OpenClaw dan mulai ulang gateway.
5. Kirim DM pertama dan setujui pairing (`openclaw pairing approve signal <CODE>`).
Config minimal:
```json5
{
channels: {
signal: {
enabled: true,
account: "+15551234567",
cliPath: "signal-cli",
dmPolicy: "pairing",
allowFrom: ["+15557654321"],
},
},
}
```
Referensi bidang:
| Bidang | Deskripsi |
| ----------- | -------------------------------------------------- |
| `account` | Nomor telepon bot dalam format E.164 (`+15551234567`) |
| `cliPath` | Path ke `signal-cli` (`signal-cli` jika ada di `PATH`) |
| `dmPolicy` | Kebijakan akses DM (`pairing` direkomendasikan) |
| `allowFrom` | Nomor telepon atau nilai `uuid:<id>` yang diizinkan untuk DM |
## Apa itu
- Channel Signal melalui `signal-cli` (bukan libsignal tertanam).
- Perutean deterministik: balasan selalu kembali ke Signal.
- DM berbagi sesi utama agen; grup diisolasi (`agent:<agentId>:signal:group:<groupId>`).
## Penulisan config
Secara default, Signal diizinkan menulis pembaruan config yang dipicu oleh `/config set|unset` (memerlukan `commands.config: true`).
Nonaktifkan dengan:
```json5
{
channels: { signal: { configWrites: false } },
}
```
## Model nomor (penting)
- Gateway terhubung ke **perangkat Signal** (akun `signal-cli`).
- Jika Anda menjalankan bot pada **akun Signal pribadi Anda**, bot akan mengabaikan pesan Anda sendiri (perlindungan loop).
- Untuk "saya mengirim pesan ke bot dan bot membalas," gunakan **nomor bot terpisah**.
## Jalur penyiapan A: tautkan akun Signal yang ada (QR)
1. Instal `signal-cli` (build JVM atau native).
2. Tautkan akun bot:
- `signal-cli link -n "OpenClaw"` lalu pindai QR di Signal.
3. Konfigurasikan Signal dan mulai gateway.
Contoh:
```json5
{
channels: {
signal: {
enabled: true,
account: "+15551234567",
cliPath: "signal-cli",
dmPolicy: "pairing",
allowFrom: ["+15557654321"],
},
},
}
```
Dukungan multi-akun: gunakan `channels.signal.accounts` dengan config per akun dan `name` opsional. Lihat [`gateway/configuration`](/gateway/configuration-reference#multi-account-all-channels) untuk pola bersama.
## Jalur penyiapan B: daftarkan nomor bot khusus (SMS, Linux)
Gunakan ini jika Anda ingin nomor bot khusus alih-alih menautkan akun aplikasi Signal yang sudah ada.
1. Dapatkan nomor yang dapat menerima SMS (atau verifikasi suara untuk telepon rumah).
- Gunakan nomor bot khusus untuk menghindari konflik akun/sesi.
2. Instal `signal-cli` di host gateway:
```bash
VERSION=$(curl -Ls -o /dev/null -w %{url_effective} https://github.com/AsamK/signal-cli/releases/latest | sed -e 's/^.*\/v//')
curl -L -O "https://github.com/AsamK/signal-cli/releases/download/v${VERSION}/signal-cli-${VERSION}-Linux-native.tar.gz"
sudo tar xf "signal-cli-${VERSION}-Linux-native.tar.gz" -C /opt
sudo ln -sf /opt/signal-cli /usr/local/bin/
signal-cli --version
```
Jika Anda menggunakan build JVM (`signal-cli-${VERSION}.tar.gz`), instal JRE 25+ terlebih dahulu.
Pastikan `signal-cli` tetap diperbarui; upstream mencatat bahwa rilis lama dapat rusak saat API server Signal berubah.
3. Daftarkan dan verifikasi nomor:
```bash
signal-cli -a +<BOT_PHONE_NUMBER> register
```
Jika captcha diperlukan:
1. Buka `https://signalcaptchas.org/registration/generate.html`.
2. Selesaikan captcha, salin target tautan `signalcaptcha://...` dari "Open Signal".
3. Jalankan dari IP eksternal yang sama dengan sesi browser jika memungkinkan.
4. Jalankan pendaftaran lagi segera (token captcha cepat kedaluwarsa):
```bash
signal-cli -a +<BOT_PHONE_NUMBER> register --captcha '<SIGNALCAPTCHA_URL>'
signal-cli -a +<BOT_PHONE_NUMBER> verify <VERIFICATION_CODE>
```
4. Konfigurasikan OpenClaw, mulai ulang gateway, verifikasi channel:
```bash
# Jika Anda menjalankan gateway sebagai layanan systemd pengguna:
systemctl --user restart openclaw-gateway.service
# Lalu verifikasi:
openclaw doctor
openclaw channels status --probe
```
5. Pair pengirim DM Anda:
- Kirim pesan apa pun ke nomor bot.
- Setujui kode di server: `openclaw pairing approve signal <PAIRING_CODE>`.
- Simpan nomor bot sebagai kontak di ponsel Anda untuk menghindari "Unknown contact".
Penting: mendaftarkan akun nomor telepon dengan `signal-cli` dapat menghapus autentikasi sesi aplikasi Signal utama untuk nomor tersebut. Sebaiknya gunakan nomor bot khusus, atau gunakan mode tautan QR jika Anda perlu mempertahankan penyiapan aplikasi ponsel yang ada.
Referensi upstream:
- README `signal-cli`: `https://github.com/AsamK/signal-cli`
- Alur captcha: `https://github.com/AsamK/signal-cli/wiki/Registration-with-captcha`
- Alur penautan: `https://github.com/AsamK/signal-cli/wiki/Linking-other-devices-(Provisioning)`
## Mode daemon eksternal (httpUrl)
Jika Anda ingin mengelola `signal-cli` sendiri (cold start JVM lambat, inisialisasi container, atau CPU bersama), jalankan daemon secara terpisah dan arahkan OpenClaw ke sana:
```json5
{
channels: {
signal: {
httpUrl: "http://127.0.0.1:8080",
autoStart: false,
},
},
}
```
Ini melewati auto-spawn dan waktu tunggu startup di dalam OpenClaw. Untuk startup lambat saat auto-spawn, atur `channels.signal.startupTimeoutMs`.
## Kontrol akses (DM + grup)
DM:
- Default: `channels.signal.dmPolicy = "pairing"`.
- Pengirim yang tidak dikenal menerima kode pairing; pesan diabaikan sampai disetujui (kode kedaluwarsa setelah 1 jam).
- Setujui melalui:
- `openclaw pairing list signal`
- `openclaw pairing approve signal <CODE>`
- Pairing adalah pertukaran token default untuk DM Signal. Detail: [Pairing](/channels/pairing)
- Pengirim khusus UUID (dari `sourceUuid`) disimpan sebagai `uuid:<id>` di `channels.signal.allowFrom`.
Grup:
- `channels.signal.groupPolicy = open | allowlist | disabled`.
- `channels.signal.groupAllowFrom` mengontrol siapa yang dapat memicu di grup saat `allowlist` diatur.
- `channels.signal.groups["<group-id>" | "*"]` dapat mengganti perilaku grup dengan `requireMention`, `tools`, dan `toolsBySender`.
- Gunakan `channels.signal.accounts.<id>.groups` untuk override per akun dalam penyiapan multi-akun.
- Catatan runtime: jika `channels.signal` tidak ada sama sekali, runtime akan fallback ke `groupPolicy="allowlist"` untuk pemeriksaan grup (bahkan jika `channels.defaults.groupPolicy` diatur).
## Cara kerjanya (perilaku)
- `signal-cli` berjalan sebagai daemon; gateway membaca peristiwa melalui SSE.
- Pesan masuk dinormalisasi ke dalam envelope channel bersama.
- Balasan selalu dirutekan kembali ke nomor atau grup yang sama.
## Media + batas
- Teks keluar dipotong menurut `channels.signal.textChunkLimit` (default 4000).
- Pemotongan newline opsional: atur `channels.signal.chunkMode="newline"` untuk membagi pada baris kosong (batas paragraf) sebelum pemotongan berdasarkan panjang.
- Lampiran didukung (base64 diambil dari `signal-cli`).
- Batas media default: `channels.signal.mediaMaxMb` (default 8).
- Gunakan `channels.signal.ignoreAttachments` untuk melewati unduhan media.
- Konteks riwayat grup menggunakan `channels.signal.historyLimit` (atau `channels.signal.accounts.*.historyLimit`), fallback ke `messages.groupChat.historyLimit`. Atur `0` untuk menonaktifkan (default 50).
## Tanda mengetik + tanda baca
- **Indikator mengetik**: OpenClaw mengirim sinyal mengetik melalui `signal-cli sendTyping` dan menyegarkannya saat balasan sedang berlangsung.
- **Tanda baca**: saat `channels.signal.sendReadReceipts` bernilai true, OpenClaw meneruskan tanda baca untuk DM yang diizinkan.
- Signal-cli tidak mengekspos tanda baca untuk grup.
## Reactions (alat pesan)
- Gunakan `message action=react` dengan `channel=signal`.
- Target: pengirim E.164 atau UUID (gunakan `uuid:<id>` dari output pairing; UUID polos juga berfungsi).
- `messageId` adalah timestamp Signal untuk pesan yang Anda beri reaction.
- Reaction grup memerlukan `targetAuthor` atau `targetAuthorUuid`.
Contoh:
```
message action=react channel=signal target=uuid:123e4567-e89b-12d3-a456-426614174000 messageId=1737630212345 emoji=🔥
message action=react channel=signal target=+15551234567 messageId=1737630212345 emoji=🔥 remove=true
message action=react channel=signal target=signal:group:<groupId> targetAuthor=uuid:<sender-uuid> messageId=1737630212345 emoji=✅
```
Config:
- `channels.signal.actions.reactions`: aktifkan/nonaktifkan action reaction (default true).
- `channels.signal.reactionLevel`: `off | ack | minimal | extensive`.
- `off`/`ack` menonaktifkan reaction agen (alat pesan `react` akan menghasilkan error).
- `minimal`/`extensive` mengaktifkan reaction agen dan menetapkan tingkat panduan.
- Override per akun: `channels.signal.accounts.<id>.actions.reactions`, `channels.signal.accounts.<id>.reactionLevel`.
## Target pengiriman (CLI/cron)
- DM: `signal:+15551234567` (atau E.164 polos).
- DM UUID: `uuid:<id>` (atau UUID polos).
- Grup: `signal:group:<groupId>`.
- Nama pengguna: `username:<name>` (jika didukung oleh akun Signal Anda).
## Pemecahan masalah
Jalankan langkah ini terlebih dahulu:
```bash
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
```
Lalu konfirmasi status pairing DM jika diperlukan:
```bash
openclaw pairing list signal
```
Kegagalan umum:
- Daemon dapat dijangkau tetapi tidak ada balasan: verifikasi pengaturan akun/daemon (`httpUrl`, `account`) dan mode penerimaan.
- DM diabaikan: pengirim masih menunggu persetujuan pairing.
- Pesan grup diabaikan: pembatasan pengirim/mention grup memblokir pengiriman.
- Error validasi config setelah pengeditan: jalankan `openclaw doctor --fix`.
- Signal tidak muncul dalam diagnostik: pastikan `channels.signal.enabled: true`.
Pemeriksaan tambahan:
```bash
openclaw pairing list signal
pgrep -af signal-cli
grep -i "signal" "/tmp/openclaw/openclaw-$(date +%Y-%m-%d).log" | tail -20
```
Untuk alur triase: [/channels/troubleshooting](/channels/troubleshooting).
## Catatan keamanan
- `signal-cli` menyimpan kunci akun secara lokal (biasanya `~/.local/share/signal-cli/data/`).
- Cadangkan status akun Signal sebelum migrasi atau rebuild server.
- Pertahankan `channels.signal.dmPolicy: "pairing"` kecuali Anda memang ingin akses DM yang lebih luas.
- Verifikasi SMS hanya diperlukan untuk alur pendaftaran atau pemulihan, tetapi kehilangan kendali atas nomor/akun dapat mempersulit pendaftaran ulang.
## Referensi konfigurasi (Signal)
Konfigurasi lengkap: [Configuration](/gateway/configuration)
Opsi provider:
- `channels.signal.enabled`: aktifkan/nonaktifkan startup channel.
- `channels.signal.account`: E.164 untuk akun bot.
- `channels.signal.cliPath`: path ke `signal-cli`.
- `channels.signal.httpUrl`: URL daemon lengkap (menggantikan host/port).
- `channels.signal.httpHost`, `channels.signal.httpPort`: bind daemon (default 127.0.0.1:8080).
- `channels.signal.autoStart`: auto-spawn daemon (default true jika `httpUrl` tidak diatur).
- `channels.signal.startupTimeoutMs`: batas waktu tunggu startup dalam ms (maksimum 120000).
- `channels.signal.receiveMode`: `on-start | manual`.
- `channels.signal.ignoreAttachments`: lewati unduhan lampiran.
- `channels.signal.ignoreStories`: abaikan story dari daemon.
- `channels.signal.sendReadReceipts`: teruskan tanda baca.
- `channels.signal.dmPolicy`: `pairing | allowlist | open | disabled` (default: pairing).
- `channels.signal.allowFrom`: allowlist DM (E.164 atau `uuid:<id>`). `open` memerlukan `"*"`. Signal tidak memiliki username; gunakan ID telepon/UUID.
- `channels.signal.groupPolicy`: `open | allowlist | disabled` (default: allowlist).
- `channels.signal.groupAllowFrom`: allowlist pengirim grup.
- `channels.signal.groups`: override per grup yang dikunci dengan id grup Signal (atau `"*"`). Bidang yang didukung: `requireMention`, `tools`, `toolsBySender`.
- `channels.signal.accounts.<id>.groups`: versi per akun dari `channels.signal.groups` untuk penyiapan multi-akun.
- `channels.signal.historyLimit`: jumlah maksimum pesan grup yang disertakan sebagai konteks (0 menonaktifkan).
- `channels.signal.dmHistoryLimit`: batas riwayat DM dalam giliran pengguna. Override per pengguna: `channels.signal.dms["<phone_or_uuid>"].historyLimit`.
- `channels.signal.textChunkLimit`: ukuran potongan keluar (karakter).
- `channels.signal.chunkMode`: `length` (default) atau `newline` untuk membagi pada baris kosong (batas paragraf) sebelum pemotongan berdasarkan panjang.
- `channels.signal.mediaMaxMb`: batas media masuk/keluar (MB).
Opsi global terkait:
- `agents.list[].groupChat.mentionPatterns` (Signal tidak mendukung mention native).
- `messages.groupChat.mentionPatterns` (fallback global).
- `messages.responsePrefix`.
## Terkait
- [Ikhtisar Channels](/channels) — semua channel yang didukung
- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing
- [Groups](/channels/groups) — perilaku obrolan grup dan pembatasan mention
- [Channel Routing](/channels/channel-routing) — perutean sesi untuk pesan
- [Security](/gateway/security) — model akses dan penguatan

688
docs/id/channels/slack.md Normal file
View File

@ -0,0 +1,688 @@
---
read_when:
- Menyiapkan Slack atau men-debug mode socket/HTTP Slack
summary: Setup Slack dan perilaku runtime (Socket Mode + HTTP Events API)
title: Slack
x-i18n:
generated_at: "2026-04-05T13:44:44Z"
model: gpt-5.4
provider: openai
source_hash: efb37e1f04e1ac8ac3786c36ffc20013dacdc654bfa61e7f6e8df89c4902d2ab
source_path: channels/slack.md
workflow: 15
---
# Slack
Status: siap produksi untuk DM + channel melalui integrasi aplikasi Slack. Mode default adalah Socket Mode; mode HTTP Events API juga didukung.
<CardGroup cols={3}>
<Card title="Pairing" icon="link" href="/channels/pairing">
DM Slack secara default menggunakan mode pairing.
</Card>
<Card title="Slash commands" icon="terminal" href="/tools/slash-commands">
Perilaku perintah native dan katalog perintah.
</Card>
<Card title="Channel troubleshooting" icon="wrench" href="/channels/troubleshooting">
Diagnostik lintas channel dan playbook perbaikan.
</Card>
</CardGroup>
## Setup cepat
<Tabs>
<Tab title="Socket Mode (default)">
<Steps>
<Step title="Create Slack app and tokens">
Di pengaturan aplikasi Slack:
- aktifkan **Socket Mode**
- buat **App Token** (`xapp-...`) dengan `connections:write`
- instal aplikasi dan salin **Bot Token** (`xoxb-...`)
</Step>
<Step title="Configure OpenClaw">
```json5
{
channels: {
slack: {
enabled: true,
mode: "socket",
appToken: "xapp-...",
botToken: "xoxb-...",
},
},
}
```
Fallback env (hanya akun default):
```bash
SLACK_APP_TOKEN=xapp-...
SLACK_BOT_TOKEN=xoxb-...
```
</Step>
<Step title="Subscribe app events">
Subscribe event bot untuk:
- `app_mention`
- `message.channels`, `message.groups`, `message.im`, `message.mpim`
- `reaction_added`, `reaction_removed`
- `member_joined_channel`, `member_left_channel`
- `channel_rename`
- `pin_added`, `pin_removed`
Aktifkan juga App Home **Messages Tab** untuk DM.
</Step>
<Step title="Start gateway">
```bash
openclaw gateway
```
</Step>
</Steps>
</Tab>
<Tab title="HTTP Events API mode">
<Steps>
<Step title="Configure Slack app for HTTP">
- setel mode ke HTTP (`channels.slack.mode="http"`)
- salin Slack **Signing Secret**
- setel Request URL untuk Event Subscriptions + Interactivity + Slash command ke path webhook yang sama (default `/slack/events`)
</Step>
<Step title="Configure OpenClaw HTTP mode">
```json5
{
channels: {
slack: {
enabled: true,
mode: "http",
botToken: "xoxb-...",
signingSecret: "your-signing-secret",
webhookPath: "/slack/events",
},
},
}
```
</Step>
<Step title="Use unique webhook paths for multi-account HTTP">
Mode HTTP per akun didukung.
Berikan `webhookPath` yang berbeda untuk setiap akun agar pendaftaran tidak saling bertabrakan.
</Step>
</Steps>
</Tab>
</Tabs>
## Checklist manifest dan scope
<AccordionGroup>
<Accordion title="Slack app manifest example" defaultOpen>
```json
{
"display_information": {
"name": "OpenClaw",
"description": "Slack connector for OpenClaw"
},
"features": {
"bot_user": {
"display_name": "OpenClaw",
"always_online": true
},
"app_home": {
"messages_tab_enabled": true,
"messages_tab_read_only_enabled": false
},
"slash_commands": [
{
"command": "/openclaw",
"description": "Send a message to OpenClaw",
"should_escape": false
}
]
},
"oauth_config": {
"scopes": {
"bot": [
"app_mentions:read",
"assistant:write",
"channels:history",
"channels:read",
"chat:write",
"commands",
"emoji:read",
"files:read",
"files:write",
"groups:history",
"groups:read",
"im:history",
"im:read",
"im:write",
"mpim:history",
"mpim:read",
"mpim:write",
"pins:read",
"pins:write",
"reactions:read",
"reactions:write",
"users:read"
]
}
},
"settings": {
"socket_mode_enabled": true,
"event_subscriptions": {
"bot_events": [
"app_mention",
"channel_rename",
"member_joined_channel",
"member_left_channel",
"message.channels",
"message.groups",
"message.im",
"message.mpim",
"pin_added",
"pin_removed",
"reaction_added",
"reaction_removed"
]
}
}
}
```
</Accordion>
<Accordion title="Optional user-token scopes (read operations)">
Jika Anda mengonfigurasi `channels.slack.userToken`, scope baca yang umum adalah:
- `channels:history`, `groups:history`, `im:history`, `mpim:history`
- `channels:read`, `groups:read`, `im:read`, `mpim:read`
- `users:read`
- `reactions:read`
- `pins:read`
- `emoji:read`
- `search:read` (jika Anda bergantung pada pembacaan pencarian Slack)
</Accordion>
</AccordionGroup>
## Model token
- `botToken` + `appToken` wajib untuk Socket Mode.
- Mode HTTP memerlukan `botToken` + `signingSecret`.
- `botToken`, `appToken`, `signingSecret`, dan `userToken` menerima
string plaintext atau objek SecretRef.
- Token config menimpa fallback env.
- Fallback env `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` hanya berlaku untuk akun default.
- `userToken` (`xoxp-...`) hanya config-only (tanpa fallback env) dan default ke perilaku read-only (`userTokenReadOnly: true`).
- Opsional: tambahkan `chat:write.customize` jika Anda ingin pesan keluar menggunakan identitas agen aktif (`username` dan ikon kustom). `icon_emoji` menggunakan sintaks `:emoji_name:`.
Perilaku snapshot status:
- Inspeksi akun Slack melacak field `*Source` dan `*Status`
per kredensial (`botToken`, `appToken`, `signingSecret`, `userToken`).
- Status bernilai `available`, `configured_unavailable`, atau `missing`.
- `configured_unavailable` berarti akun dikonfigurasi melalui SecretRef
atau sumber secret non-inline lain, tetapi jalur perintah/runtime saat ini
tidak dapat menyelesaikan nilai sebenarnya.
- Dalam mode HTTP, `signingSecretStatus` disertakan; dalam Socket Mode,
pasangan yang wajib adalah `botTokenStatus` + `appTokenStatus`.
<Tip>
Untuk tindakan/pembacaan direktori, user token dapat diprioritaskan jika dikonfigurasi. Untuk penulisan, bot token tetap diprioritaskan; penulisan dengan user token hanya diizinkan saat `userTokenReadOnly: false` dan bot token tidak tersedia.
</Tip>
## Tindakan dan gate
Tindakan Slack dikendalikan oleh `channels.slack.actions.*`.
Grup tindakan yang tersedia dalam tooling Slack saat ini:
| Grup | Default |
| ---------- | ------- |
| messages | enabled |
| reactions | enabled |
| pins | enabled |
| memberInfo | enabled |
| emojiList | enabled |
Tindakan pesan Slack saat ini mencakup `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info`, dan `emoji-list`.
## Kontrol akses dan routing
<Tabs>
<Tab title="DM policy">
`channels.slack.dmPolicy` mengendalikan akses DM (legacy: `channels.slack.dm.policy`):
- `pairing` (default)
- `allowlist`
- `open` (memerlukan `channels.slack.allowFrom` mencakup `"*"`; legacy: `channels.slack.dm.allowFrom`)
- `disabled`
Flag DM:
- `dm.enabled` (default true)
- `channels.slack.allowFrom` (disarankan)
- `dm.allowFrom` (legacy)
- `dm.groupEnabled` (group DM default false)
- `dm.groupChannels` (allowlist MPIM opsional)
Prioritas multi-akun:
- `channels.slack.accounts.default.allowFrom` hanya berlaku untuk akun `default`.
- Akun bernama mewarisi `channels.slack.allowFrom` saat `allowFrom` miliknya sendiri tidak disetel.
- Akun bernama tidak mewarisi `channels.slack.accounts.default.allowFrom`.
Pairing di DM menggunakan `openclaw pairing approve slack <code>`.
</Tab>
<Tab title="Channel policy">
`channels.slack.groupPolicy` mengendalikan penanganan channel:
- `open`
- `allowlist`
- `disabled`
Allowlist channel berada di bawah `channels.slack.channels` dan sebaiknya menggunakan ID channel yang stabil.
Catatan runtime: jika `channels.slack` sama sekali tidak ada (setup hanya env), runtime akan fallback ke `groupPolicy="allowlist"` dan mencatat peringatan (bahkan jika `channels.defaults.groupPolicy` disetel).
Resolusi nama/ID:
- entri allowlist channel dan entri allowlist DM diselesaikan saat startup jika akses token memungkinkan
- entri nama channel yang tidak dapat diselesaikan tetap disimpan seperti dikonfigurasi tetapi diabaikan untuk routing secara default
- otorisasi masuk dan routing channel secara default berbasis ID; pencocokan langsung username/slug memerlukan `channels.slack.dangerouslyAllowNameMatching: true`
</Tab>
<Tab title="Mentions and channel users">
Pesan channel secara default di-gate oleh mention.
Sumber mention:
- mention aplikasi eksplisit (`<@botId>`)
- pola regex mention (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`)
- perilaku thread reply-to-bot implisit
Kontrol per channel (`channels.slack.channels.<id>`; nama hanya melalui resolusi startup atau `dangerouslyAllowNameMatching`):
- `requireMention`
- `users` (allowlist)
- `allowBots`
- `skills`
- `systemPrompt`
- `tools`, `toolsBySender`
- format key `toolsBySender`: `id:`, `e164:`, `username:`, `name:`, atau wildcard `"*"`
(key legacy tanpa prefiks masih dipetakan hanya ke `id:`)
</Tab>
</Tabs>
## Threading, sesi, dan tag balasan
- DM dirutekan sebagai `direct`; channel sebagai `channel`; MPIM sebagai `group`.
- Dengan default `session.dmScope=main`, DM Slack digabungkan ke sesi utama agen.
- Sesi channel: `agent:<agentId>:slack:channel:<channelId>`.
- Balasan thread dapat membuat sufiks sesi thread (`:thread:<threadTs>`) jika berlaku.
- Default `channels.slack.thread.historyScope` adalah `thread`; default `thread.inheritParent` adalah `false`.
- `channels.slack.thread.initialHistoryLimit` mengendalikan berapa banyak pesan thread yang sudah ada diambil saat sesi thread baru dimulai (default `20`; set `0` untuk menonaktifkan).
Kontrol reply threading:
- `channels.slack.replyToMode`: `off|first|all` (default `off`)
- `channels.slack.replyToModeByChatType`: per `direct|group|channel`
- fallback legacy untuk obrolan langsung: `channels.slack.dm.replyToMode`
Tag balasan manual didukung:
- `[[reply_to_current]]`
- `[[reply_to:<id>]]`
Catatan: `replyToMode="off"` menonaktifkan **semua** reply threading di Slack, termasuk tag `[[reply_to_*]]` yang eksplisit. Ini berbeda dari Telegram, di mana tag eksplisit tetap dihormati dalam mode `"off"`. Perbedaan ini mencerminkan model threading platform: thread Slack menyembunyikan pesan dari channel, sedangkan balasan Telegram tetap terlihat di alur chat utama.
## Reaksi ack
`ackReaction` mengirim emoji tanda terima saat OpenClaw sedang memproses pesan masuk.
Urutan resolusi:
- `channels.slack.accounts.<accountId>.ackReaction`
- `channels.slack.ackReaction`
- `messages.ackReaction`
- fallback emoji identitas agen (`agents.list[].identity.emoji`, jika tidak ada gunakan "👀")
Catatan:
- Slack mengharapkan shortcode (misalnya `"eyes"`).
- Gunakan `""` untuk menonaktifkan reaksi untuk akun Slack atau secara global.
## Streaming teks
`channels.slack.streaming` mengendalikan perilaku pratinjau live:
- `off`: nonaktifkan streaming pratinjau live.
- `partial` (default): ganti teks pratinjau dengan output parsial terbaru.
- `block`: tambahkan pembaruan pratinjau bertahap.
- `progress`: tampilkan teks status progres saat menghasilkan, lalu kirim teks akhir.
`channels.slack.nativeStreaming` mengendalikan streaming teks native Slack saat `streaming` adalah `partial` (default: `true`).
- Thread balasan harus tersedia agar streaming teks native muncul. Pemilihan thread tetap mengikuti `replyToMode`. Tanpanya, pratinjau draf normal akan digunakan.
- Media dan payload non-teks akan fallback ke pengiriman normal.
- Jika streaming gagal di tengah balasan, OpenClaw akan fallback ke pengiriman normal untuk payload yang tersisa.
Gunakan pratinjau draf alih-alih streaming teks native Slack:
```json5
{
channels: {
slack: {
streaming: "partial",
nativeStreaming: false,
},
},
}
```
Key legacy:
- `channels.slack.streamMode` (`replace | status_final | append`) dimigrasikan otomatis ke `channels.slack.streaming`.
- boolean `channels.slack.streaming` dimigrasikan otomatis ke `channels.slack.nativeStreaming`.
## Fallback reaksi mengetik
`typingReaction` menambahkan reaksi sementara ke pesan Slack masuk saat OpenClaw sedang memproses balasan, lalu menghapusnya saat eksekusi selesai. Ini paling berguna di luar balasan thread, yang menggunakan indikator status default "is typing...".
Urutan resolusi:
- `channels.slack.accounts.<accountId>.typingReaction`
- `channels.slack.typingReaction`
Catatan:
- Slack mengharapkan shortcode (misalnya `"hourglass_flowing_sand"`).
- Reaksi ini bersifat best-effort dan pembersihannya dicoba secara otomatis setelah jalur balasan atau kegagalan selesai.
## Media, chunking, dan pengiriman
<AccordionGroup>
<Accordion title="Inbound attachments">
Lampiran file Slack diunduh dari URL privat yang di-host Slack (alur permintaan terautentikasi token) dan ditulis ke penyimpanan media saat pengambilan berhasil dan batas ukuran mengizinkan.
Batas ukuran masuk runtime default adalah `20MB` kecuali ditimpa oleh `channels.slack.mediaMaxMb`.
</Accordion>
<Accordion title="Outbound text and files">
- potongan teks menggunakan `channels.slack.textChunkLimit` (default 4000)
- `channels.slack.chunkMode="newline"` mengaktifkan pemisahan dengan prioritas paragraf
- pengiriman file menggunakan API upload Slack dan dapat menyertakan balasan thread (`thread_ts`)
- batas media keluar mengikuti `channels.slack.mediaMaxMb` saat dikonfigurasi; jika tidak, pengiriman channel menggunakan default jenis MIME dari pipeline media
</Accordion>
<Accordion title="Delivery targets">
Target eksplisit yang disarankan:
- `user:<id>` untuk DM
- `channel:<id>` untuk channel
DM Slack dibuka melalui API percakapan Slack saat mengirim ke target pengguna.
</Accordion>
</AccordionGroup>
## Perintah dan perilaku slash
- Auto-mode perintah native adalah **off** untuk Slack (`commands.native: "auto"` tidak mengaktifkan perintah native Slack).
- Aktifkan handler perintah Slack native dengan `channels.slack.commands.native: true` (atau global `commands.native: true`).
- Saat perintah native diaktifkan, daftarkan slash command yang sesuai di Slack (nama `/<command>`), dengan satu pengecualian:
- daftarkan `/agentstatus` untuk perintah status (Slack mencadangkan `/status`)
- Jika perintah native tidak diaktifkan, Anda dapat menjalankan satu slash command yang dikonfigurasi melalui `channels.slack.slashCommand`.
- Menu argumen native kini menyesuaikan strategi rendering-nya:
- hingga 5 opsi: blok tombol
- 6-100 opsi: menu select statis
- lebih dari 100 opsi: external select dengan penyaringan opsi async saat handler opsi interaktivitas tersedia
- jika nilai opsi yang dikodekan melebihi batas Slack, alur akan fallback ke tombol
- Untuk payload opsi yang panjang, menu argumen Slash command menggunakan dialog konfirmasi sebelum mengirim nilai yang dipilih.
Pengaturan default slash command:
- `enabled: false`
- `name: "openclaw"`
- `sessionPrefix: "slack:slash"`
- `ephemeral: true`
Sesi slash menggunakan key terisolasi:
- `agent:<agentId>:slack:slash:<userId>`
dan tetap merutekan eksekusi perintah terhadap sesi percakapan target (`CommandTargetSessionKey`).
## Balasan interaktif
Slack dapat merender kontrol balasan interaktif yang ditulis agen, tetapi fitur ini dinonaktifkan secara default.
Aktifkan secara global:
```json5
{
channels: {
slack: {
capabilities: {
interactiveReplies: true,
},
},
},
}
```
Atau aktifkan hanya untuk satu akun Slack:
```json5
{
channels: {
slack: {
accounts: {
ops: {
capabilities: {
interactiveReplies: true,
},
},
},
},
},
}
```
Saat diaktifkan, agen dapat mengeluarkan directive balasan khusus Slack:
- `[[slack_buttons: Approve:approve, Reject:reject]]`
- `[[slack_select: Choose a target | Canary:canary, Production:production]]`
Directive ini dikompilasi menjadi Slack Block Kit dan merutekan klik atau pilihan kembali melalui jalur event interaksi Slack yang ada.
Catatan:
- Ini adalah UI khusus Slack. Channel lain tidak menerjemahkan directive Slack Block Kit ke sistem tombol mereka sendiri.
- Nilai callback interaktif adalah token opak yang dibuat OpenClaw, bukan nilai mentah yang ditulis agen.
- Jika blok interaktif yang dihasilkan melebihi batas Slack Block Kit, OpenClaw akan fallback ke balasan teks asli alih-alih mengirim payload blocks yang tidak valid.
## Persetujuan exec di Slack
Slack dapat bertindak sebagai klien persetujuan native dengan tombol interaktif dan interaksi, alih-alih fallback ke UI Web atau terminal.
- Persetujuan exec menggunakan `channels.slack.execApprovals.*` untuk routing DM/channel native.
- Persetujuan plugin tetap dapat diselesaikan melalui surface tombol native Slack yang sama saat permintaan sudah sampai di Slack dan jenis approval id adalah `plugin:`.
- Otorisasi approver tetap diberlakukan: hanya pengguna yang diidentifikasi sebagai approver yang dapat menyetujui atau menolak permintaan melalui Slack.
Ini menggunakan surface tombol persetujuan bersama yang sama seperti channel lain. Saat `interactivity` diaktifkan di pengaturan aplikasi Slack Anda, prompt persetujuan dirender sebagai tombol Block Kit langsung di percakapan.
Saat tombol tersebut ada, itu menjadi UX persetujuan utama; OpenClaw
hanya boleh menyertakan perintah manual `/approve` saat hasil tool menyatakan persetujuan chat
tidak tersedia atau persetujuan manual adalah satu-satunya jalur.
Path config:
- `channels.slack.execApprovals.enabled`
- `channels.slack.execApprovals.approvers` (opsional; fallback ke `commands.ownerAllowFrom` jika memungkinkan)
- `channels.slack.execApprovals.target` (`dm` | `channel` | `both`, default: `dm`)
- `agentFilter`, `sessionFilter`
Slack otomatis mengaktifkan persetujuan exec native saat `enabled` tidak disetel atau `"auto"` dan setidaknya satu
approver berhasil diselesaikan. Set `enabled: false` untuk menonaktifkan Slack sebagai klien persetujuan native secara eksplisit.
Set `enabled: true` untuk memaksa persetujuan native aktif saat approver berhasil diselesaikan.
Perilaku default tanpa config persetujuan exec Slack eksplisit:
```json5
{
commands: {
ownerAllowFrom: ["slack:U12345678"],
},
}
```
Config native Slack eksplisit hanya diperlukan saat Anda ingin menimpa approver, menambahkan filter, atau
memilih pengiriman ke chat asal:
```json5
{
channels: {
slack: {
execApprovals: {
enabled: true,
approvers: ["U12345678"],
target: "both",
},
},
},
}
```
Forwarding bersama `approvals.exec` bersifat terpisah. Gunakan hanya saat prompt persetujuan exec juga harus
dirutekan ke chat lain atau target out-of-band eksplisit. Forwarding bersama `approvals.plugin` juga
terpisah; tombol native Slack tetap dapat menyelesaikan persetujuan plugin saat permintaan tersebut sudah sampai
di Slack.
`/approve` pada chat yang sama juga berfungsi di channel dan DM Slack yang sudah mendukung perintah. Lihat [Exec approvals](/tools/exec-approvals) untuk model forwarding persetujuan lengkap.
## Event dan perilaku operasional
- Edit/hapus pesan/thread broadcast dipetakan ke peristiwa sistem.
- Event tambah/hapus reaksi dipetakan ke peristiwa sistem.
- Event anggota masuk/keluar, channel dibuat/diubah namanya, dan tambah/hapus pin dipetakan ke peristiwa sistem.
- `channel_id_changed` dapat memigrasikan key config channel saat `configWrites` diaktifkan.
- Metadata topik/tujuan channel diperlakukan sebagai konteks yang tidak tepercaya dan dapat disuntikkan ke konteks routing.
- Konteks awal thread starter dan riwayat thread awal difilter oleh allowlist pengirim yang dikonfigurasi jika berlaku.
- Tindakan blok dan interaksi modal menghasilkan peristiwa sistem terstruktur `Slack interaction: ...` dengan field payload kaya:
- block actions: nilai terpilih, label, nilai picker, dan metadata `workflow_*`
- event modal `view_submission` dan `view_closed` dengan metadata channel yang dirutekan dan input formulir
## Petunjuk referensi konfigurasi
Referensi utama:
- [Referensi konfigurasi - Slack](/gateway/configuration-reference#slack)
Field Slack dengan sinyal tinggi:
- mode/auth: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*`
- akses DM: `dm.enabled`, `dmPolicy`, `allowFrom` (legacy: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels`
- toggle kompatibilitas: `dangerouslyAllowNameMatching` (break-glass; biarkan off kecuali diperlukan)
- akses channel: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention`
- threading/history: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
- pengiriman: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `nativeStreaming`
- ops/fitur: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly`
## Pemecahan masalah
<AccordionGroup>
<Accordion title="No replies in channels">
Periksa, secara berurutan:
- `groupPolicy`
- allowlist channel (`channels.slack.channels`)
- `requireMention`
- allowlist `users` per channel
Perintah yang berguna:
```bash
openclaw channels status --probe
openclaw logs --follow
openclaw doctor
```
</Accordion>
<Accordion title="DM messages ignored">
Periksa:
- `channels.slack.dm.enabled`
- `channels.slack.dmPolicy` (atau legacy `channels.slack.dm.policy`)
- persetujuan pairing / entri allowlist
```bash
openclaw pairing list slack
```
</Accordion>
<Accordion title="Socket mode not connecting">
Validasi token bot + aplikasi dan pengaktifan Socket Mode di pengaturan aplikasi Slack.
Jika `openclaw channels status --probe --json` menampilkan `botTokenStatus` atau
`appTokenStatus: "configured_unavailable"`, akun Slack
telah dikonfigurasi tetapi runtime saat ini tidak dapat menyelesaikan nilai
yang didukung SecretRef.
</Accordion>
<Accordion title="HTTP mode not receiving events">
Validasi:
- signing secret
- path webhook
- Slack Request URL (Events + Interactivity + Slash Commands)
- `webhookPath` unik per akun HTTP
Jika `signingSecretStatus: "configured_unavailable"` muncul di snapshot akun,
akun HTTP telah dikonfigurasi tetapi runtime saat ini tidak dapat
menyelesaikan signing secret yang didukung SecretRef.
</Accordion>
<Accordion title="Native/slash commands not firing">
Verifikasi apakah yang Anda maksud adalah:
- mode perintah native (`channels.slack.commands.native: true`) dengan slash command yang sesuai terdaftar di Slack
- atau mode single slash command (`channels.slack.slashCommand.enabled: true`)
Periksa juga `commands.useAccessGroups` dan allowlist channel/pengguna.
</Accordion>
</AccordionGroup>
## Terkait
- [Pairing](/channels/pairing)
- [Grup](/channels/groups)
- [Keamanan](/gateway/security)
- [Channel routing](/channels/channel-routing)
- [Pemecahan masalah](/channels/troubleshooting)
- [Konfigurasi](/gateway/configuration)
- [Slash commands](/tools/slash-commands)

192
docs/id/channels/synology-chat.md Normal file
View File

@ -0,0 +1,192 @@
---
read_when:
- Menyiapkan Synology Chat dengan OpenClaw
- Men-debug perutean webhook Synology Chat
summary: Penyiapan webhook Synology Chat dan konfigurasi OpenClaw
title: Synology Chat
x-i18n:
generated_at: "2026-04-05T13:44:08Z"
model: gpt-5.4
provider: openai
source_hash: ddb25fc6b53f896f15f43b4936d69ea071a29a91838a5b662819377271e89d81
source_path: channels/synology-chat.md
workflow: 15
---
# Synology Chat
Status: channel pesan langsung plugin bawaan yang menggunakan webhook Synology Chat.
Plugin ini menerima pesan masuk dari webhook keluar Synology Chat dan mengirim balasan
melalui webhook masuk Synology Chat.
## Plugin bawaan
Synology Chat tersedia sebagai plugin bawaan dalam rilis OpenClaw saat ini, jadi build
paket normal tidak memerlukan instalasi terpisah.
Jika Anda menggunakan build lama atau instalasi kustom yang tidak menyertakan Synology Chat,
instal secara manual:
Instal dari checkout lokal:
```bash
openclaw plugins install ./path/to/local/synology-chat-plugin
```
Detail: [Plugins](/tools/plugin)
## Penyiapan cepat
1. Pastikan plugin Synology Chat tersedia.
- Rilis OpenClaw paket saat ini sudah menyertakan plugin ini.
- Instalasi lama/kustom dapat menambahkannya secara manual dari checkout sumber dengan perintah di atas.
- `openclaw onboard` sekarang menampilkan Synology Chat dalam daftar penyiapan channel yang sama seperti `openclaw channels add`.
- Penyiapan non-interaktif: `openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>`
2. Di integrasi Synology Chat:
- Buat webhook masuk dan salin URL-nya.
- Buat webhook keluar dengan token rahasia Anda.
3. Arahkan URL webhook keluar ke gateway OpenClaw Anda:
- `https://gateway-host/webhook/synology` secara default.
- Atau `channels.synology-chat.webhookPath` kustom Anda.
4. Selesaikan penyiapan di OpenClaw.
- Terpandu: `openclaw onboard`
- Langsung: `openclaw channels add --channel synology-chat --token <token> --url <incoming-webhook-url>`
5. Mulai ulang gateway dan kirim DM ke bot Synology Chat.
Detail autentikasi webhook:
- OpenClaw menerima token webhook keluar dari `body.token`, lalu
`?token=...`, lalu header.
- Bentuk header yang diterima:
- `x-synology-token`
- `x-webhook-token`
- `x-openclaw-token`
- `Authorization: Bearer <token>`
- Token yang kosong atau tidak ada akan gagal secara fail-closed.
Konfigurasi minimal:
```json5
{
channels: {
"synology-chat": {
enabled: true,
token: "synology-outgoing-token",
incomingUrl: "https://nas.example.com/webapi/entry.cgi?api=SYNO.Chat.External&method=incoming&version=2&token=...",
webhookPath: "/webhook/synology",
dmPolicy: "allowlist",
allowedUserIds: ["123456"],
rateLimitPerMinute: 30,
allowInsecureSsl: false,
},
},
}
```
## Variabel lingkungan
Untuk akun default, Anda dapat menggunakan variabel lingkungan:
- `SYNOLOGY_CHAT_TOKEN`
- `SYNOLOGY_CHAT_INCOMING_URL`
- `SYNOLOGY_NAS_HOST`
- `SYNOLOGY_ALLOWED_USER_IDS` (dipisahkan koma)
- `SYNOLOGY_RATE_LIMIT`
- `OPENCLAW_BOT_NAME`
Nilai konfigurasi menimpa variabel lingkungan.
## Kebijakan DM dan kontrol akses
- `dmPolicy: "allowlist"` adalah default yang direkomendasikan.
- `allowedUserIds` menerima daftar (atau string yang dipisahkan koma) ID pengguna Synology.
- Dalam mode `allowlist`, daftar `allowedUserIds` yang kosong dianggap sebagai salah konfigurasi dan rute webhook tidak akan dimulai (gunakan `dmPolicy: "open"` untuk mengizinkan semua).
- `dmPolicy: "open"` mengizinkan pengirim mana pun.
- `dmPolicy: "disabled"` memblokir DM.
- Binding penerima balasan tetap menggunakan `user_id` numerik yang stabil secara default. `channels.synology-chat.dangerouslyAllowNameMatching: true` adalah mode kompatibilitas darurat yang mengaktifkan kembali pencocokan username/nickname yang dapat berubah untuk pengiriman balasan.
- Persetujuan pairing berfungsi dengan:
- `openclaw pairing list synology-chat`
- `openclaw pairing approve synology-chat <CODE>`
## Pengiriman keluar
Gunakan ID pengguna Synology Chat numerik sebagai target.
Contoh:
```bash
openclaw message send --channel synology-chat --target 123456 --text "Hello from OpenClaw"
openclaw message send --channel synology-chat --target synology-chat:123456 --text "Hello again"
```
Pengiriman media didukung melalui pengiriman file berbasis URL.
## Multi-akun
Beberapa akun Synology Chat didukung di bawah `channels.synology-chat.accounts`.
Setiap akun dapat menimpa token, URL masuk, path webhook, kebijakan DM, dan batasan.
Sesi pesan langsung diisolasi per akun dan pengguna, sehingga `user_id` numerik yang sama
pada dua akun Synology yang berbeda tidak berbagi status transkrip.
Berikan setiap akun aktif `webhookPath` yang berbeda. OpenClaw sekarang menolak path persis yang duplikat
dan menolak memulai akun bernama yang hanya mewarisi satu path webhook bersama dalam penyiapan multi-akun.
Jika Anda sengaja memerlukan pewarisan lama untuk akun bernama, atur
`dangerouslyAllowInheritedWebhookPath: true` pada akun tersebut atau di `channels.synology-chat`,
tetapi path persis yang duplikat tetap ditolak secara fail-closed. Lebih baik gunakan path eksplisit per akun.
```json5
{
channels: {
"synology-chat": {
enabled: true,
accounts: {
default: {
token: "token-a",
incomingUrl: "https://nas-a.example.com/...token=...",
},
alerts: {
token: "token-b",
incomingUrl: "https://nas-b.example.com/...token=...",
webhookPath: "/webhook/synology-alerts",
dmPolicy: "allowlist",
allowedUserIds: ["987654"],
},
},
},
},
}
```
## Catatan keamanan
- Jaga kerahasiaan `token` dan rotasi jika bocor.
- Pertahankan `allowInsecureSsl: false` kecuali Anda secara eksplisit memercayai sertifikat NAS lokal self-signed.
- Permintaan webhook masuk diverifikasi token dan dibatasi lajunya per pengirim.
- Pemeriksaan token tidak valid menggunakan perbandingan rahasia waktu konstan dan fail-closed.
- Gunakan `dmPolicy: "allowlist"` untuk produksi.
- Biarkan `dangerouslyAllowNameMatching` nonaktif kecuali Anda benar-benar memerlukan pengiriman balasan berbasis username lama.
- Biarkan `dangerouslyAllowInheritedWebhookPath` nonaktif kecuali Anda secara eksplisit menerima risiko perutean path bersama dalam penyiapan multi-akun.
## Pemecahan masalah
- `Missing required fields (token, user_id, text)`:
- payload webhook keluar tidak memiliki salah satu field wajib
- jika Synology mengirim token di header, pastikan gateway/proxy mempertahankan header tersebut
- `Invalid token`:
- rahasia webhook keluar tidak cocok dengan `channels.synology-chat.token`
- permintaan mengenai akun/path webhook yang salah
- reverse proxy menghapus header token sebelum permintaan mencapai OpenClaw
- `Rate limit exceeded`:
- terlalu banyak percobaan token tidak valid dari sumber yang sama dapat mengunci sementara sumber tersebut
- pengirim yang terautentikasi juga memiliki batas laju pesan terpisah per pengguna
- `Allowlist is empty. Configure allowedUserIds or use dmPolicy=open.`:
- `dmPolicy="allowlist"` aktif tetapi tidak ada pengguna yang dikonfigurasi
- `User not authorized`:
- `user_id` numerik pengirim tidak ada dalam `allowedUserIds`
## Terkait
- [Ikhtisar Channel](/channels) — semua channel yang didukung
- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing
- [Grup](/channels/groups) — perilaku chat grup dan penyaringan mention
- [Perutean Channel](/channels/channel-routing) — perutean sesi untuk pesan
- [Keamanan](/gateway/security) — model akses dan hardening

1075
docs/id/channels/telegram.md Normal file
View File

File diff suppressed because it is too large Load Diff

297
docs/id/channels/tlon.md Normal file
View File

@ -0,0 +1,297 @@
---
read_when:
- Mengerjakan fitur channel Tlon/Urbit
summary: Status dukungan Tlon/Urbit, kemampuan, dan konfigurasi
title: Tlon
x-i18n:
generated_at: "2026-04-05T13:44:35Z"
model: gpt-5.4
provider: openai
source_hash: 289cffb3c1b2d450a5f41e0d67117dfb5c192cec956d82039caac9df9f07496d
source_path: channels/tlon.md
workflow: 15
---
# Tlon
Tlon adalah messenger terdesentralisasi yang dibangun di atas Urbit. OpenClaw terhubung ke ship Urbit Anda dan dapat
merespons DM serta pesan chat grup. Balasan grup secara default memerlukan mention @ dan dapat
dibatasi lebih lanjut melalui allowlist.
Status: plugin bawaan. DM, mention grup, balasan thread, pemformatan rich text, dan
unggahan gambar didukung. Reaksi dan polling belum didukung.
## Plugin bawaan
Tlon tersedia sebagai plugin bawaan dalam rilis OpenClaw saat ini, jadi build paket
normal tidak memerlukan instalasi terpisah.
Jika Anda menggunakan build lama atau instalasi kustom yang tidak menyertakan Tlon, instal secara
manual:
Instal melalui CLI (registri npm):
```bash
openclaw plugins install @openclaw/tlon
```
Checkout lokal (saat berjalan dari repositori git):
```bash
openclaw plugins install ./path/to/local/tlon-plugin
```
Detail: [Plugins](/tools/plugin)
## Penyiapan
1. Pastikan plugin Tlon tersedia.
- Rilis OpenClaw paket saat ini sudah menyertakan plugin ini.
- Instalasi lama/kustom dapat menambahkannya secara manual dengan perintah di atas.
2. Siapkan URL ship dan kode login Anda.
3. Konfigurasikan `channels.tlon`.
4. Mulai ulang gateway.
5. Kirim DM ke bot atau mention bot di channel grup.
Konfigurasi minimal (akun tunggal):
```json5
{
channels: {
tlon: {
enabled: true,
ship: "~sampel-palnet",
url: "https://your-ship-host",
code: "lidlut-tabwed-pillex-ridrup",
ownerShip: "~your-main-ship", // direkomendasikan: ship Anda, selalu diizinkan
},
},
}
```
## Ship privat/LAN
Secara default, OpenClaw memblokir hostname dan rentang IP privat/internal untuk perlindungan SSRF.
Jika ship Anda berjalan di jaringan privat (localhost, IP LAN, atau hostname internal),
Anda harus mengaktifkannya secara eksplisit:
```json5
{
channels: {
tlon: {
url: "http://localhost:8080",
allowPrivateNetwork: true,
},
},
}
```
Ini berlaku untuk URL seperti:
- `http://localhost:8080`
- `http://192.168.x.x:8080`
- `http://my-ship.local:8080`
⚠️ Aktifkan ini hanya jika Anda memercayai jaringan lokal Anda. Pengaturan ini menonaktifkan perlindungan SSRF
untuk permintaan ke URL ship Anda.
## Channel grup
Penemuan otomatis diaktifkan secara default. Anda juga dapat menyematkan channel secara manual:
```json5
{
channels: {
tlon: {
groupChannels: ["chat/~host-ship/general", "chat/~host-ship/support"],
},
},
}
```
Nonaktifkan penemuan otomatis:
```json5
{
channels: {
tlon: {
autoDiscoverChannels: false,
},
},
}
```
## Kontrol akses
Allowlist DM (kosong = tidak ada DM yang diizinkan, gunakan `ownerShip` untuk alur persetujuan):
```json5
{
channels: {
tlon: {
dmAllowlist: ["~zod", "~nec"],
},
},
}
```
Otorisasi grup (dibatasi secara default):
```json5
{
channels: {
tlon: {
defaultAuthorizedShips: ["~zod"],
authorization: {
channelRules: {
"chat/~host-ship/general": {
mode: "restricted",
allowedShips: ["~zod", "~nec"],
},
"chat/~host-ship/announcements": {
mode: "open",
},
},
},
},
},
}
```
## Sistem owner dan persetujuan
Atur ship owner untuk menerima permintaan persetujuan saat pengguna yang tidak diotorisasi mencoba berinteraksi:
```json5
{
channels: {
tlon: {
ownerShip: "~your-main-ship",
},
},
}
```
Ship owner **secara otomatis diotorisasi di mana saja** — undangan DM diterima otomatis dan
pesan channel selalu diizinkan. Anda tidak perlu menambahkan owner ke `dmAllowlist` atau
`defaultAuthorizedShips`.
Saat diatur, owner menerima notifikasi DM untuk:
- permintaan DM dari ship yang tidak ada di allowlist
- mention di channel tanpa otorisasi
- permintaan undangan grup
## Pengaturan terima otomatis
Terima otomatis undangan DM (untuk ship di `dmAllowlist`):
```json5
{
channels: {
tlon: {
autoAcceptDmInvites: true,
},
},
}
```
Terima otomatis undangan grup:
```json5
{
channels: {
tlon: {
autoAcceptGroupInvites: true,
},
},
}
```
## Target pengiriman (CLI/cron)
Gunakan ini dengan `openclaw message send` atau pengiriman cron:
- DM: `~sampel-palnet` atau `dm/~sampel-palnet`
- Grup: `chat/~host-ship/channel` atau `group:~host-ship/channel`
## Skill bawaan
Plugin Tlon menyertakan skill bawaan ([`@tloncorp/tlon-skill`](https://github.com/tloncorp/tlon-skill))
yang menyediakan akses CLI ke operasi Tlon:
- **Kontak**: dapatkan/perbarui profil, daftar kontak
- **Channel**: daftar, buat, kirim pesan, ambil riwayat
- **Grup**: daftar, buat, kelola anggota
- **DM**: kirim pesan, beri reaksi pada pesan
- **Reaksi**: tambahkan/hapus reaksi emoji ke post dan DM
- **Pengaturan**: kelola izin plugin melalui perintah slash
Skill ini otomatis tersedia saat plugin diinstal.
## Kemampuan
| Fitur | Status |
| --------------- | --------------------------------------- |
| Pesan langsung | ✅ Didukung |
| Grup/channel | ✅ Didukung (secara default dibatasi mention) |
| Thread | ✅ Didukung (balasan otomatis di thread) |
| Rich text | ✅ Markdown dikonversi ke format Tlon |
| Gambar | ✅ Diunggah ke penyimpanan Tlon |
| Reaksi | ✅ Melalui [skill bawaan](#skill-bawaan) |
| Polling | ❌ Belum didukung |
| Perintah native | ✅ Didukung (secara default hanya owner) |
## Pemecahan masalah
Jalankan urutan ini terlebih dahulu:
```bash
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
```
Kegagalan umum:
- **DM diabaikan**: pengirim tidak ada di `dmAllowlist` dan tidak ada `ownerShip` yang dikonfigurasi untuk alur persetujuan.
- **Pesan grup diabaikan**: channel tidak ditemukan atau pengirim tidak diotorisasi.
- **Error koneksi**: periksa apakah URL ship dapat dijangkau; aktifkan `allowPrivateNetwork` untuk ship lokal.
- **Error autentikasi**: pastikan kode login masih berlaku (kode berotasi).
## Referensi konfigurasi
Konfigurasi lengkap: [Konfigurasi](/gateway/configuration)
Opsi provider:
- `channels.tlon.enabled`: aktifkan/nonaktifkan startup channel.
- `channels.tlon.ship`: nama ship Urbit bot (mis. `~sampel-palnet`).
- `channels.tlon.url`: URL ship (mis. `https://sampel-palnet.tlon.network`).
- `channels.tlon.code`: kode login ship.
- `channels.tlon.allowPrivateNetwork`: izinkan URL localhost/LAN (melewati SSRF).
- `channels.tlon.ownerShip`: ship owner untuk sistem persetujuan (selalu diotorisasi).
- `channels.tlon.dmAllowlist`: ship yang diizinkan mengirim DM (kosong = tidak ada).
- `channels.tlon.autoAcceptDmInvites`: terima otomatis DM dari ship yang ada di allowlist.
- `channels.tlon.autoAcceptGroupInvites`: terima otomatis semua undangan grup.
- `channels.tlon.autoDiscoverChannels`: temukan channel grup secara otomatis (default: true).
- `channels.tlon.groupChannels`: nest channel yang disematkan secara manual.
- `channels.tlon.defaultAuthorizedShips`: ship yang diotorisasi untuk semua channel.
- `channels.tlon.authorization.channelRules`: aturan otorisasi per channel.
- `channels.tlon.showModelSignature`: tambahkan nama model ke pesan.
## Catatan
- Balasan grup memerlukan mention (mis. `~your-bot-ship`) agar merespons.
- Balasan thread: jika pesan masuk berada di thread, OpenClaw akan membalas di thread.
- Rich text: pemformatan Markdown (tebal, miring, kode, header, daftar) dikonversi ke format native Tlon.
- Gambar: URL diunggah ke penyimpanan Tlon dan disematkan sebagai blok gambar.
## Terkait
- [Ikhtisar Channel](/channels) — semua channel yang didukung
- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing
- [Grup](/channels/groups) — perilaku chat grup dan penyaringan mention
- [Perutean Channel](/channels/channel-routing) — perutean sesi untuk pesan
- [Keamanan](/gateway/security) — model akses dan hardening

140
docs/id/channels/troubleshooting.md Normal file
View File

@ -0,0 +1,140 @@
---
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
x-i18n:
generated_at: "2026-04-05T13:44:43Z"
model: gpt-5.4
provider: openai
source_hash: d45d8220505ea420d970b20bc66e65216c2d7024b5736db1936421ffc0676e1f
source_path: channels/troubleshooting.md
workflow: 15
---
# Pemecahan masalah channel
Gunakan halaman ini saat sebuah channel terhubung tetapi perilakunya salah.
## Urutan perintah
Jalankan ini terlebih dahulu secara berurutan:
```bash
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
```
Baseline sehat:
- `Runtime: running`
- `RPC probe: ok`
- Probe channel menunjukkan transport terhubung dan, jika didukung, `works` atau `audit ok`
## WhatsApp
### Signature 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. |
Pemecahan masalah lengkap: [/channels/whatsapp#troubleshooting](/channels/whatsapp#troubleshooting)
## Telegram
### Signature kegagalan Telegram
| Gejala | Pemeriksaan tercepat | Perbaikan |
| ----------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------- |
| `/start` tetapi tidak ada alur balasan yang dapat digunakan | `openclaw pairing list telegram` | Setujui pairing atau ubah kebijakan DM. |
| Bot online tetapi grup tetap diam | Verifikasi persyaratan mention dan mode privasi bot | Nonaktifkan mode privasi untuk visibilitas grup atau mention bot. |
| Kegagalan 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. |
Pemecahan masalah lengkap: [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting)
## Discord
### Signature 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. |
Pemecahan masalah lengkap: [/channels/discord#troubleshooting](/channels/discord#troubleshooting)
## Slack
### Signature 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. |
| Pesan channel diabaikan | Periksa `groupPolicy` dan allowlist channel | Izinkan channel atau ubah kebijakan menjadi `open`. |
Pemecahan masalah lengkap: [/channels/slack#troubleshooting](/channels/slack#troubleshooting)
## iMessage dan BlueBubbles
### Signature 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. |
Pemecahan masalah lengkap:
- [/channels/imessage#troubleshooting](/channels/imessage#troubleshooting)
- [/channels/bluebubbles#troubleshooting](/channels/bluebubbles#troubleshooting)
## Signal
### Signature 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. |
Pemecahan masalah lengkap: [/channels/signal#troubleshooting](/channels/signal#troubleshooting)
## QQ Bot
### Signature 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. |
Pemecahan masalah lengkap: [/channels/qqbot#troubleshooting](/channels/qqbot#troubleshooting)
## Matrix
### Signature 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`. |
| 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. |
Penyiapan dan konfigurasi lengkap: [Matrix](/channels/matrix)

401
docs/id/channels/twitch.md Normal file
View File

@ -0,0 +1,401 @@
---
read_when:
- Menyiapkan integrasi chat Twitch untuk OpenClaw
summary: Konfigurasi dan penyiapan bot chat Twitch
title: Twitch
x-i18n:
generated_at: "2026-04-05T13:44:54Z"
model: gpt-5.4
provider: openai
source_hash: 47af9fb6edb1f462c5919850ee9d05e500a1914ddd0d64a41608fbe960e77cd6
source_path: channels/twitch.md
workflow: 15
---
# Twitch
Dukungan chat Twitch melalui koneksi IRC. OpenClaw terhubung sebagai pengguna Twitch (akun bot) untuk menerima dan mengirim pesan di channel.
## Plugin bawaan
Twitch dikirim sebagai plugin bawaan di rilis OpenClaw saat ini, jadi build
paket normal tidak memerlukan instalasi terpisah.
Jika Anda menggunakan build lama atau instalasi kustom yang tidak menyertakan Twitch, instal
secara manual:
Instal melalui CLI (registry npm):
```bash
openclaw plugins install @openclaw/twitch
```
Checkout lokal (saat berjalan dari repo git):
```bash
openclaw plugins install ./path/to/local/twitch-plugin
```
Detail: [Plugins](/tools/plugin)
## Penyiapan cepat (pemula)
1. Pastikan plugin Twitch tersedia.
- Rilis OpenClaw terpaket saat ini sudah menyertakannya.
- Instalasi lama/kustom dapat menambahkannya secara manual dengan perintah di atas.
2. Buat akun Twitch khusus untuk bot (atau gunakan akun yang sudah ada).
3. Buat kredensial: [Twitch Token Generator](https://twitchtokengenerator.com/)
- Pilih **Bot Token**
- Pastikan scope `chat:read` dan `chat:write` dipilih
- Salin **Client ID** dan **Access Token**
4. Temukan ID pengguna Twitch Anda: [https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/](https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/)
5. Konfigurasikan token:
- Env: `OPENCLAW_TWITCH_ACCESS_TOKEN=...` (hanya akun default)
- Atau config: `channels.twitch.accessToken`
- Jika keduanya ditetapkan, config lebih diutamakan (fallback env hanya untuk akun default).
6. Mulai gateway.
**⚠️ Penting:** Tambahkan kontrol akses (`allowFrom` atau `allowedRoles`) untuk mencegah pengguna yang tidak berwenang memicu bot. `requireMention` default ke `true`.
Config minimal:
```json5
{
channels: {
twitch: {
enabled: true,
username: "openclaw", // Akun Twitch bot
accessToken: "oauth:abc123...", // OAuth Access Token (atau gunakan env var OPENCLAW_TWITCH_ACCESS_TOKEN)
clientId: "xyz789...", // Client ID dari Token Generator
channel: "vevisk", // Chat channel Twitch yang akan diikuti (wajib)
allowFrom: ["123456789"], // (disarankan) Hanya ID pengguna Twitch Anda - dapatkan dari https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
},
},
}
```
## Apa ini
- Channel Twitch yang dimiliki oleh Gateway.
- Routing deterministik: balasan selalu kembali ke Twitch.
- Setiap akun dipetakan ke kunci sesi terisolasi `agent:<agentId>:twitch:<accountName>`.
- `username` adalah akun bot (yang melakukan autentikasi), `channel` adalah ruang chat yang akan diikuti.
## Penyiapan (detail)
### Buat kredensial
Gunakan [Twitch Token Generator](https://twitchtokengenerator.com/):
- Pilih **Bot Token**
- Pastikan scope `chat:read` dan `chat:write` dipilih
- Salin **Client ID** dan **Access Token**
Tidak perlu pendaftaran aplikasi manual. Token kedaluwarsa setelah beberapa jam.
### Konfigurasikan bot
**Env var (hanya akun default):**
```bash
OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...
```
**Atau config:**
```json5
{
channels: {
twitch: {
enabled: true,
username: "openclaw",
accessToken: "oauth:abc123...",
clientId: "xyz789...",
channel: "vevisk",
},
},
}
```
Jika env dan config sama-sama ditetapkan, config lebih diutamakan.
### Kontrol akses (disarankan)
```json5
{
channels: {
twitch: {
allowFrom: ["123456789"], // (disarankan) Hanya ID pengguna Twitch Anda
},
},
}
```
Utamakan `allowFrom` untuk allowlist yang ketat. Gunakan `allowedRoles` jika Anda menginginkan akses berbasis peran.
**Peran yang tersedia:** `"moderator"`, `"owner"`, `"vip"`, `"subscriber"`, `"all"`.
**Mengapa ID pengguna?** Nama pengguna dapat berubah, sehingga memungkinkan penyamaran. ID pengguna bersifat permanen.
Temukan ID pengguna Twitch Anda: [https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/](https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/) (Konversi nama pengguna Twitch Anda ke ID)
## Penyegaran token (opsional)
Token dari [Twitch Token Generator](https://twitchtokengenerator.com/) tidak dapat disegarkan secara otomatis - buat ulang saat kedaluwarsa.
Untuk penyegaran token otomatis, buat aplikasi Twitch Anda sendiri di [Twitch Developer Console](https://dev.twitch.tv/console) lalu tambahkan ke config:
```json5
{
channels: {
twitch: {
clientSecret: "your_client_secret",
refreshToken: "your_refresh_token",
},
},
}
```
Bot secara otomatis menyegarkan token sebelum kedaluwarsa dan mencatat event penyegaran.
## Dukungan multi-akun
Gunakan `channels.twitch.accounts` dengan token per akun. Lihat [`gateway/configuration`](/gateway/configuration) untuk pola bersama.
Contoh (satu akun bot di dua channel):
```json5
{
channels: {
twitch: {
accounts: {
channel1: {
username: "openclaw",
accessToken: "oauth:abc123...",
clientId: "xyz789...",
channel: "vevisk",
},
channel2: {
username: "openclaw",
accessToken: "oauth:def456...",
clientId: "uvw012...",
channel: "secondchannel",
},
},
},
},
}
```
**Catatan:** Setiap akun memerlukan tokennya sendiri (satu token per channel).
## Kontrol akses
### Pembatasan berbasis peran
```json5
{
channels: {
twitch: {
accounts: {
default: {
allowedRoles: ["moderator", "vip"],
},
},
},
},
}
```
### Allowlist berdasarkan ID Pengguna (paling aman)
```json5
{
channels: {
twitch: {
accounts: {
default: {
allowFrom: ["123456789", "987654321"],
},
},
},
},
}
```
### Akses berbasis peran (alternatif)
`allowFrom` adalah allowlist yang ketat. Jika ditetapkan, hanya ID pengguna tersebut yang diizinkan.
Jika Anda menginginkan akses berbasis peran, biarkan `allowFrom` tidak ditetapkan dan konfigurasi `allowedRoles` sebagai gantinya:
```json5
{
channels: {
twitch: {
accounts: {
default: {
allowedRoles: ["moderator"],
},
},
},
},
}
```
### Nonaktifkan persyaratan @mention
Secara default, `requireMention` adalah `true`. Untuk menonaktifkannya dan merespons semua pesan:
```json5
{
channels: {
twitch: {
accounts: {
default: {
requireMention: false,
},
},
},
},
}
```
## Troubleshooting
Pertama, jalankan perintah diagnostik:
```bash
openclaw doctor
openclaw channels status --probe
```
### Bot tidak merespons pesan
**Periksa kontrol akses:** Pastikan ID pengguna Anda ada di `allowFrom`, atau hapus sementara
`allowFrom` dan tetapkan `allowedRoles: ["all"]` untuk pengujian.
**Periksa apakah bot ada di channel:** Bot harus bergabung ke channel yang ditentukan di `channel`.
### Masalah token
**"Failed to connect" atau error autentikasi:**
- Pastikan `accessToken` adalah nilai token akses OAuth (biasanya diawali prefiks `oauth:`)
- Pastikan token memiliki scope `chat:read` dan `chat:write`
- Jika menggunakan penyegaran token, pastikan `clientSecret` dan `refreshToken` ditetapkan
### Penyegaran token tidak berfungsi
**Periksa log untuk event penyegaran:**
```
Using env token source for mybot
Access token refreshed for user 123456 (expires in 14400s)
```
Jika Anda melihat "token refresh disabled (no refresh token)":
- Pastikan `clientSecret` disediakan
- Pastikan `refreshToken` disediakan
## Config
**Config akun:**
- `username` - Nama pengguna bot
- `accessToken` - Token akses OAuth dengan `chat:read` dan `chat:write`
- `clientId` - Twitch Client ID (dari Token Generator atau aplikasi Anda)
- `channel` - Channel yang akan diikuti (wajib)
- `enabled` - Aktifkan akun ini (default: `true`)
- `clientSecret` - Opsional: Untuk penyegaran token otomatis
- `refreshToken` - Opsional: Untuk penyegaran token otomatis
- `expiresIn` - Masa berlaku token dalam detik
- `obtainmentTimestamp` - Stempel waktu saat token diperoleh
- `allowFrom` - Allowlist ID pengguna
- `allowedRoles` - Kontrol akses berbasis peran (`"moderator" | "owner" | "vip" | "subscriber" | "all"`)
- `requireMention` - Wajibkan @mention (default: `true`)
**Opsi penyedia:**
- `channels.twitch.enabled` - Aktifkan/nonaktifkan startup channel
- `channels.twitch.username` - Nama pengguna bot (config satu akun yang disederhanakan)
- `channels.twitch.accessToken` - Token akses OAuth (config satu akun yang disederhanakan)
- `channels.twitch.clientId` - Twitch Client ID (config satu akun yang disederhanakan)
- `channels.twitch.channel` - Channel yang akan diikuti (config satu akun yang disederhanakan)
- `channels.twitch.accounts.<accountName>` - Config multi-akun (semua field akun di atas)
Contoh lengkap:
```json5
{
channels: {
twitch: {
enabled: true,
username: "openclaw",
accessToken: "oauth:abc123...",
clientId: "xyz789...",
channel: "vevisk",
clientSecret: "secret123...",
refreshToken: "refresh456...",
allowFrom: ["123456789"],
allowedRoles: ["moderator", "vip"],
accounts: {
default: {
username: "mybot",
accessToken: "oauth:abc123...",
clientId: "xyz789...",
channel: "your_channel",
enabled: true,
clientSecret: "secret123...",
refreshToken: "refresh456...",
expiresIn: 14400,
obtainmentTimestamp: 1706092800000,
allowFrom: ["123456789", "987654321"],
allowedRoles: ["moderator"],
},
},
},
},
}
```
## Aksi tool
Agen dapat memanggil `twitch` dengan aksi:
- `send` - Mengirim pesan ke channel
Contoh:
```json5
{
action: "twitch",
params: {
message: "Hello Twitch!",
to: "#mychannel",
},
}
```
## Keamanan & operasi
- **Perlakukan token seperti kata sandi** - Jangan pernah mengomit token ke git
- **Gunakan penyegaran token otomatis** untuk bot yang berjalan lama
- **Gunakan allowlist ID pengguna** alih-alih nama pengguna untuk kontrol akses
- **Pantau log** untuk event penyegaran token dan status koneksi
- **Batasi scope token seminimal mungkin** - Hanya minta `chat:read` dan `chat:write`
- **Jika buntu**: Mulai ulang gateway setelah memastikan tidak ada proses lain yang memiliki sesi
## Batasan
- **500 karakter** per pesan (dipotong otomatis di batas kata)
- Markdown dihapus sebelum pemotongan
- Tidak ada pembatasan laju (menggunakan batas laju bawaan Twitch)
## Terkait
- [Channels Overview](/channels) — semua channel yang didukung
- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing
- [Groups](/channels/groups) — perilaku group chat dan pembatasan mention
- [Channel Routing](/channels/channel-routing) — routing sesi untuk pesan
- [Security](/gateway/security) — model akses dan hardening

495
docs/id/channels/whatsapp.md Normal file
View File

@ -0,0 +1,495 @@
---
read_when:
- Sedang mengerjakan perilaku channel WhatsApp/web atau perutean inbox
summary: Dukungan channel WhatsApp, kontrol akses, perilaku pengiriman, dan operasi
title: WhatsApp
x-i18n:
generated_at: "2026-04-05T13:45:01Z"
model: gpt-5.4
provider: openai
source_hash: c16a468b3f47fdf7e4fc3fd745b5c49c7ccebb7af0e8c87c632b78b04c583e49
source_path: channels/whatsapp.md
workflow: 15
---
# WhatsApp (Web channel)
Status: siap produksi melalui WhatsApp Web (Baileys). Gateway memiliki sesi tertaut.
## Instal (sesuai kebutuhan)
- Onboarding (`openclaw onboard`) dan `openclaw channels add --channel whatsapp`
akan meminta Anda menginstal plugin WhatsApp saat pertama kali memilihnya.
- `openclaw channels login --channel whatsapp` juga menawarkan alur instalasi saat
plugin belum tersedia.
- Dev channel + checkout git: default ke path plugin lokal.
- Stable/Beta: default ke paket npm `@openclaw/whatsapp`.
Instalasi manual tetap tersedia:
```bash
openclaw plugins install @openclaw/whatsapp
```
<CardGroup cols={3}>
<Card title="Pairing" icon="link" href="/channels/pairing">
Kebijakan DM default adalah pairing untuk pengirim yang tidak dikenal.
</Card>
<Card title="Channel troubleshooting" icon="wrench" href="/channels/troubleshooting">
Diagnostik lintas channel dan panduan perbaikan.
</Card>
<Card title="Gateway configuration" icon="settings" href="/gateway/configuration">
Pola dan contoh config channel lengkap.
</Card>
</CardGroup>
## Penyiapan cepat
<Steps>
<Step title="Konfigurasikan kebijakan akses WhatsApp">
```json5
{
channels: {
whatsapp: {
dmPolicy: "pairing",
allowFrom: ["+15551234567"],
groupPolicy: "allowlist",
groupAllowFrom: ["+15551234567"],
},
},
}
```
</Step>
<Step title="Tautkan WhatsApp (QR)">
```bash
openclaw channels login --channel whatsapp
```
Untuk akun tertentu:
```bash
openclaw channels login --channel whatsapp --account work
```
</Step>
<Step title="Mulai gateway">
```bash
openclaw gateway
```
</Step>
<Step title="Setujui permintaan pairing pertama (jika menggunakan mode pairing)">
```bash
openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>
```
Permintaan pairing kedaluwarsa setelah 1 jam. Permintaan tertunda dibatasi hingga 3 per channel.
</Step>
</Steps>
<Note>
OpenClaw merekomendasikan menjalankan WhatsApp pada nomor terpisah jika memungkinkan. (Metadata channel dan alur penyiapan dioptimalkan untuk penyiapan tersebut, tetapi penyiapan nomor pribadi juga didukung.)
</Note>
## Pola deployment
<AccordionGroup>
<Accordion title="Nomor khusus (direkomendasikan)">
Ini adalah mode operasional yang paling bersih:
- identitas WhatsApp terpisah untuk OpenClaw
- allowlist DM dan batas perutean yang lebih jelas
- kemungkinan kebingungan obrolan sendiri yang lebih rendah
Pola kebijakan minimal:
```json5
{
channels: {
whatsapp: {
dmPolicy: "allowlist",
allowFrom: ["+15551234567"],
},
},
}
```
</Accordion>
<Accordion title="Fallback nomor pribadi">
Onboarding mendukung mode nomor pribadi dan menulis baseline yang ramah obrolan sendiri:
- `dmPolicy: "allowlist"`
- `allowFrom` mencakup nomor pribadi Anda
- `selfChatMode: true`
Dalam runtime, perlindungan obrolan sendiri bergantung pada nomor diri tertaut dan `allowFrom`.
</Accordion>
<Accordion title="Cakupan channel khusus WhatsApp Web">
Channel platform pesan berbasis WhatsApp Web (`Baileys`) dalam arsitektur channel OpenClaw saat ini.
Tidak ada channel pesan Twilio WhatsApp terpisah dalam registry channel obrolan bawaan.
</Accordion>
</AccordionGroup>
## Model runtime
- Gateway memiliki socket WhatsApp dan loop reconnect.
- Pengiriman keluar memerlukan listener WhatsApp aktif untuk akun target.
- Obrolan status dan siaran diabaikan (`@status`, `@broadcast`).
- Obrolan langsung menggunakan aturan sesi DM (`session.dmScope`; default `main` menggabungkan DM ke sesi utama agen).
- Sesi grup diisolasi (`agent:<agentId>:whatsapp:group:<jid>`).
## Kontrol akses dan aktivasi
<Tabs>
<Tab title="Kebijakan DM">
`channels.whatsapp.dmPolicy` mengontrol akses obrolan langsung:
- `pairing` (default)
- `allowlist`
- `open` (memerlukan `allowFrom` untuk menyertakan `"*"`)
- `disabled`
`allowFrom` menerima nomor bergaya E.164 (dinormalisasi secara internal).
Override multi-akun: `channels.whatsapp.accounts.<id>.dmPolicy` (dan `allowFrom`) lebih diprioritaskan daripada default tingkat channel untuk akun tersebut.
Detail perilaku runtime:
- pairing disimpan di allow-store channel dan digabungkan dengan `allowFrom` yang dikonfigurasi
- jika tidak ada allowlist yang dikonfigurasi, nomor diri tertaut diizinkan secara default
- DM keluar `fromMe` tidak pernah dipair otomatis
</Tab>
<Tab title="Kebijakan grup + allowlist">
Akses grup memiliki dua lapisan:
1. **Allowlist keanggotaan grup** (`channels.whatsapp.groups`)
- jika `groups` dihilangkan, semua grup memenuhi syarat
- jika `groups` ada, itu bertindak sebagai allowlist grup (`"*"` diperbolehkan)
2. **Kebijakan pengirim grup** (`channels.whatsapp.groupPolicy` + `groupAllowFrom`)
- `open`: allowlist pengirim dilewati
- `allowlist`: pengirim harus cocok dengan `groupAllowFrom` (atau `*`)
- `disabled`: blokir semua grup masuk
Fallback allowlist pengirim:
- jika `groupAllowFrom` tidak diatur, runtime fallback ke `allowFrom` jika tersedia
- allowlist pengirim dievaluasi sebelum aktivasi mention/balasan
Catatan: jika tidak ada blok `channels.whatsapp` sama sekali, fallback kebijakan grup runtime adalah `allowlist` (dengan log peringatan), bahkan jika `channels.defaults.groupPolicy` diatur.
</Tab>
<Tab title="Mention + /activation">
Balasan grup memerlukan mention secara default.
Deteksi mention mencakup:
- mention WhatsApp eksplisit dari identitas bot
- pola regex mention yang dikonfigurasi (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`)
- deteksi reply-to-bot implisit (pengirim balasan cocok dengan identitas bot)
Catatan keamanan:
- kutip/balas hanya memenuhi pembatasan mention; itu **tidak** memberikan otorisasi pengirim
- dengan `groupPolicy: "allowlist"`, pengirim yang tidak ada di allowlist tetap diblokir meskipun mereka membalas pesan pengguna yang ada di allowlist
Perintah aktivasi tingkat sesi:
- `/activation mention`
- `/activation always`
`activation` memperbarui status sesi (bukan config global). Ini dibatasi untuk owner.
</Tab>
</Tabs>
## Perilaku nomor pribadi dan obrolan sendiri
Saat nomor diri tertaut juga ada di `allowFrom`, perlindungan obrolan sendiri WhatsApp aktif:
- lewati tanda baca untuk giliran obrolan sendiri
- abaikan perilaku pemicu otomatis mention-JID yang sebaliknya akan meming diri Anda sendiri
- jika `messages.responsePrefix` tidak diatur, balasan obrolan sendiri default ke `[{identity.name}]` atau `[openclaw]`
## Normalisasi pesan dan konteks
<AccordionGroup>
<Accordion title="Envelope masuk + konteks balasan">
Pesan WhatsApp masuk dibungkus dalam envelope masuk bersama.
Jika ada balasan kutipan, konteks ditambahkan dalam bentuk ini:
```text
[Replying to <sender> id:<stanzaId>]
<quoted body or media placeholder>
[/Replying]
```
Bidang metadata balasan juga diisi jika tersedia (`ReplyToId`, `ReplyToBody`, `ReplyToSender`, sender JID/E.164).
</Accordion>
<Accordion title="Placeholder media dan ekstraksi lokasi/kontak">
Pesan masuk yang hanya berisi media dinormalisasi dengan placeholder seperti:
- `<media:image>`
- `<media:video>`
- `<media:audio>`
- `<media:document>`
- `<media:sticker>`
Payload lokasi dan kontak dinormalisasi menjadi konteks tekstual sebelum perutean.
</Accordion>
<Accordion title="Injeksi riwayat grup tertunda">
Untuk grup, pesan yang belum diproses dapat dibuffer dan disisipkan sebagai konteks saat bot akhirnya dipicu.
- batas default: `50`
- config: `channels.whatsapp.historyLimit`
- fallback: `messages.groupChat.historyLimit`
- `0` menonaktifkan
Penanda injeksi:
- `[Chat messages since your last reply - for context]`
- `[Current message - respond to this]`
</Accordion>
<Accordion title="Tanda baca">
Tanda baca diaktifkan secara default untuk pesan WhatsApp masuk yang diterima.
Nonaktifkan secara global:
```json5
{
channels: {
whatsapp: {
sendReadReceipts: false,
},
},
}
```
Override per akun:
```json5
{
channels: {
whatsapp: {
accounts: {
work: {
sendReadReceipts: false,
},
},
},
},
}
```
Giliran obrolan sendiri melewati tanda baca bahkan saat diaktifkan secara global.
</Accordion>
</AccordionGroup>
## Pengiriman, pemotongan, dan media
<AccordionGroup>
<Accordion title="Pemotongan teks">
- batas potongan default: `channels.whatsapp.textChunkLimit = 4000`
- `channels.whatsapp.chunkMode = "length" | "newline"`
- mode `newline` mengutamakan batas paragraf (baris kosong), lalu fallback ke pemotongan aman berdasarkan panjang
</Accordion>
<Accordion title="Perilaku media keluar">
- mendukung payload gambar, video, audio (PTT voice-note), dan dokumen
- `audio/ogg` ditulis ulang menjadi `audio/ogg; codecs=opus` untuk kompatibilitas voice-note
- pemutaran GIF animasi didukung melalui `gifPlayback: true` pada pengiriman video
- caption diterapkan pada item media pertama saat mengirim payload balasan multi-media
- sumber media dapat berupa HTTP(S), `file://`, atau path lokal
</Accordion>
<Accordion title="Batas ukuran media dan perilaku fallback">
- batas penyimpanan media masuk: `channels.whatsapp.mediaMaxMb` (default `50`)
- batas pengiriman media keluar: `channels.whatsapp.mediaMaxMb` (default `50`)
- override per akun menggunakan `channels.whatsapp.accounts.<accountId>.mediaMaxMb`
- gambar dioptimalkan otomatis (resize/quality sweep) agar sesuai dengan batas
- saat pengiriman media gagal, fallback item pertama mengirim peringatan teks alih-alih diam-diam membuang respons
</Accordion>
</AccordionGroup>
## Tingkat reaction
`channels.whatsapp.reactionLevel` mengontrol seberapa luas agen menggunakan reaction emoji di WhatsApp:
| Level | Reaction ack | Reaction yang dimulai agen | Deskripsi |
| ------------- | ------------ | -------------------------- | ------------------------------------------------- |
| `"off"` | Tidak | Tidak | Tidak ada reaction sama sekali |
| `"ack"` | Ya | Tidak | Hanya reaction ack (tanda terima pra-balasan) |
| `"minimal"` | Ya | Ya (konservatif) | Ack + reaction agen dengan panduan konservatif |
| `"extensive"` | Ya | Ya (didorong) | Ack + reaction agen dengan panduan yang didorong |
Default: `"minimal"`.
Override per akun menggunakan `channels.whatsapp.accounts.<id>.reactionLevel`.
```json5
{
channels: {
whatsapp: {
reactionLevel: "ack",
},
},
}
```
## Reaction acknowledgment
WhatsApp mendukung reaction ack segera saat penerimaan masuk melalui `channels.whatsapp.ackReaction`.
Reaction ack dibatasi oleh `reactionLevel` — reaction ini ditekan saat `reactionLevel` adalah `"off"`.
```json5
{
channels: {
whatsapp: {
ackReaction: {
emoji: "👀",
direct: true,
group: "mentions", // always | mentions | never
},
},
},
}
```
Catatan perilaku:
- dikirim segera setelah pesan masuk diterima (pra-balasan)
- kegagalan dicatat dalam log tetapi tidak memblokir pengiriman balasan normal
- mode grup `mentions` bereaksi pada giliran yang dipicu mention; aktivasi grup `always` bertindak sebagai bypass untuk pemeriksaan ini
- WhatsApp menggunakan `channels.whatsapp.ackReaction` (`messages.ackReaction` legacy tidak digunakan di sini)
## Multi-akun dan kredensial
<AccordionGroup>
<Accordion title="Pemilihan akun dan default">
- id akun berasal dari `channels.whatsapp.accounts`
- pemilihan akun default: `default` jika ada, jika tidak id akun pertama yang dikonfigurasi (diurutkan)
- id akun dinormalisasi secara internal untuk lookup
</Accordion>
<Accordion title="Path kredensial dan kompatibilitas legacy">
- path autentikasi saat ini: `~/.openclaw/credentials/whatsapp/<accountId>/creds.json`
- file cadangan: `creds.json.bak`
- autentikasi default legacy di `~/.openclaw/credentials/` masih dikenali/dimigrasikan untuk alur akun default
</Accordion>
<Accordion title="Perilaku logout">
`openclaw channels logout --channel whatsapp [--account <id>]` menghapus status autentikasi WhatsApp untuk akun tersebut.
Dalam direktori autentikasi legacy, `oauth.json` dipertahankan sementara file autentikasi Baileys dihapus.
</Accordion>
</AccordionGroup>
## Alat, action, dan penulisan config
- Dukungan alat agen mencakup action reaction WhatsApp (`react`).
- Pembatasan action:
- `channels.whatsapp.actions.reactions`
- `channels.whatsapp.actions.polls`
- Penulisan config yang dimulai channel diaktifkan secara default (nonaktifkan melalui `channels.whatsapp.configWrites=false`).
## Pemecahan masalah
<AccordionGroup>
<Accordion title="Belum tertaut (QR diperlukan)">
Gejala: status channel melaporkan belum tertaut.
Perbaikan:
```bash
openclaw channels login --channel whatsapp
openclaw channels status
```
</Accordion>
<Accordion title="Tertaut tetapi terputus / loop reconnect">
Gejala: akun tertaut dengan disconnect berulang atau upaya reconnect.
Perbaikan:
```bash
openclaw doctor
openclaw logs --follow
```
Jika perlu, tautkan ulang dengan `channels login`.
</Accordion>
<Accordion title="Tidak ada listener aktif saat mengirim">
Pengiriman keluar gagal cepat saat tidak ada listener gateway aktif untuk akun target.
Pastikan gateway berjalan dan akun tertaut.
</Accordion>
<Accordion title="Pesan grup tiba-tiba diabaikan">
Periksa dalam urutan ini:
- `groupPolicy`
- `groupAllowFrom` / `allowFrom`
- entri allowlist `groups`
- pembatasan mention (`requireMention` + pola mention)
- kunci duplikat di `openclaw.json` (JSON5): entri terakhir menggantikan entri sebelumnya, jadi gunakan satu `groupPolicy` per cakupan
</Accordion>
<Accordion title="Peringatan runtime Bun">
Runtime gateway WhatsApp seharusnya menggunakan Node. Bun ditandai tidak kompatibel untuk operasi gateway WhatsApp/Telegram yang stabil.
</Accordion>
</AccordionGroup>
## Penunjuk referensi konfigurasi
Referensi utama:
- [Referensi konfigurasi - WhatsApp](/gateway/configuration-reference#whatsapp)
Bidang WhatsApp dengan sinyal tinggi:
- akses: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`
- pengiriman: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `sendReadReceipts`, `ackReaction`, `reactionLevel`
- multi-akun: `accounts.<id>.enabled`, `accounts.<id>.authDir`, override tingkat akun
- operasi: `configWrites`, `debounceMs`, `web.enabled`, `web.heartbeatSeconds`, `web.reconnect.*`
- perilaku sesi: `session.dmScope`, `historyLimit`, `dmHistoryLimit`, `dms.<id>.historyLimit`
## Terkait
- [Pairing](/channels/pairing)
- [Groups](/channels/groups)
- [Security](/gateway/security)
- [Channel routing](/channels/channel-routing)
- [Multi-agent routing](/concepts/multi-agent)
- [Troubleshooting](/channels/troubleshooting)

261
docs/id/channels/zalo.md Normal file
View File

@ -0,0 +1,261 @@
---
read_when:
- Mengerjakan fitur atau webhook Zalo
summary: Status dukungan bot Zalo, kemampuan, dan konfigurasi
title: Zalo
x-i18n:
generated_at: "2026-04-05T13:45:10Z"
model: gpt-5.4
provider: openai
source_hash: ab94642ba28e79605b67586af8f71c18bc10e0af60343a7df508e6823b6f4119
source_path: channels/zalo.md
workflow: 15
---
# Zalo (Bot API)
Status: eksperimental. DM didukung. Bagian [Kemampuan](#capabilities) di bawah mencerminkan perilaku bot Marketplace saat ini.
## Plugin bawaan
Zalo tersedia sebagai plugin bawaan dalam rilis OpenClaw saat ini, jadi build paket
normal tidak memerlukan instalasi terpisah.
Jika Anda menggunakan build lama atau instalasi kustom yang tidak menyertakan Zalo, instal secara
manual:
- Instal melalui CLI: `openclaw plugins install @openclaw/zalo`
- Atau dari checkout sumber: `openclaw plugins install ./path/to/local/zalo-plugin`
- Detail: [Plugins](/tools/plugin)
## Penyiapan cepat (pemula)
1. Pastikan plugin Zalo tersedia.
- Rilis OpenClaw paket saat ini sudah menyertakan plugin ini.
- Instalasi lama/kustom dapat menambahkannya secara manual dengan perintah di atas.
2. Atur token:
- Env: `ZALO_BOT_TOKEN=...`
- Atau konfigurasi: `channels.zalo.accounts.default.botToken: "..."`.
3. Mulai ulang gateway (atau selesaikan penyiapan).
4. Akses DM secara default menggunakan pairing; setujui kode pairing saat kontak pertama.
Konfigurasi minimal:
```json5
{
channels: {
zalo: {
enabled: true,
accounts: {
default: {
botToken: "12345689:abc-xyz",
dmPolicy: "pairing",
},
},
},
},
}
```
## Apa itu
Zalo adalah aplikasi pesan yang berfokus pada Vietnam; Bot API-nya memungkinkan Gateway menjalankan bot untuk percakapan 1:1.
Ini cocok untuk dukungan atau notifikasi saat Anda menginginkan perutean deterministik kembali ke Zalo.
Halaman ini mencerminkan perilaku OpenClaw saat ini untuk **bot Zalo Bot Creator / Marketplace**.
**Bot Zalo Official Account (OA)** adalah permukaan produk Zalo yang berbeda dan dapat berperilaku berbeda.
- Channel Zalo Bot API yang dimiliki oleh Gateway.
- Perutean deterministik: balasan kembali ke Zalo; model tidak pernah memilih channel.
- DM berbagi sesi utama agen.
- Bagian [Kemampuan](#capabilities) di bawah menunjukkan dukungan bot Marketplace saat ini.
## Penyiapan (jalur cepat)
### 1) Buat token bot (Zalo Bot Platform)
1. Buka [https://bot.zaloplatforms.com](https://bot.zaloplatforms.com) dan masuk.
2. Buat bot baru dan konfigurasikan pengaturannya.
3. Salin token bot lengkap (biasanya `numeric_id:secret`). Untuk bot Marketplace, token runtime yang dapat digunakan mungkin muncul dalam pesan sambutan bot setelah pembuatan.
### 2) Konfigurasikan token (env atau config)
Contoh:
```json5
{
channels: {
zalo: {
enabled: true,
accounts: {
default: {
botToken: "12345689:abc-xyz",
dmPolicy: "pairing",
},
},
},
},
}
```
Jika nantinya Anda berpindah ke permukaan bot Zalo tempat grup tersedia, Anda dapat menambahkan konfigurasi khusus grup seperti `groupPolicy` dan `groupAllowFrom` secara eksplisit. Untuk perilaku bot Marketplace saat ini, lihat [Kemampuan](#capabilities).
Opsi env: `ZALO_BOT_TOKEN=...` (hanya berfungsi untuk akun default).
Dukungan multi-akun: gunakan `channels.zalo.accounts` dengan token per akun dan `name` opsional.
3. Mulai ulang gateway. Zalo dimulai saat token berhasil di-resolve (env atau config).
4. Akses DM secara default menggunakan pairing. Setujui kode saat bot pertama kali dihubungi.
## Cara kerjanya (perilaku)
- Pesan masuk dinormalisasi ke envelope channel bersama dengan placeholder media.
- Balasan selalu dirutekan kembali ke chat Zalo yang sama.
- Long-polling secara default; mode webhook tersedia dengan `channels.zalo.webhookUrl`.
## Batasan
- Teks keluar dipotong menjadi 2000 karakter (batas API Zalo).
- Unduhan/unggahan media dibatasi oleh `channels.zalo.mediaMaxMb` (default 5).
- Streaming diblokir secara default karena batas 2000 karakter membuat streaming kurang berguna.
## Kontrol akses (DM)
### Akses DM
- Default: `channels.zalo.dmPolicy = "pairing"`. Pengirim yang tidak dikenal menerima kode pairing; pesan diabaikan sampai disetujui (kode kedaluwarsa setelah 1 jam).
- Setujui melalui:
- `openclaw pairing list zalo`
- `openclaw pairing approve zalo <CODE>`
- Pairing adalah pertukaran token default. Detail: [Pairing](/channels/pairing)
- `channels.zalo.allowFrom` menerima ID pengguna numerik (tidak ada pencarian username yang tersedia).
## Kontrol akses (Grup)
Untuk **bot Zalo Bot Creator / Marketplace**, dukungan grup secara praktik tidak tersedia karena bot sama sekali tidak dapat ditambahkan ke grup.
Artinya key konfigurasi terkait grup di bawah ini ada dalam schema, tetapi tidak dapat digunakan untuk bot Marketplace:
- `channels.zalo.groupPolicy` mengontrol penanganan masuk grup: `open | allowlist | disabled`.
- `channels.zalo.groupAllowFrom` membatasi ID pengirim mana yang dapat memicu bot di grup.
- Jika `groupAllowFrom` tidak diatur, Zalo menggunakan fallback ke `allowFrom` untuk pemeriksaan pengirim.
- Catatan runtime: jika `channels.zalo` sama sekali tidak ada, runtime tetap menggunakan fallback ke `groupPolicy="allowlist"` demi keamanan.
Nilai kebijakan grup (saat akses grup tersedia pada permukaan bot Anda) adalah:
- `groupPolicy: "disabled"` — memblokir semua pesan grup.
- `groupPolicy: "open"` — mengizinkan anggota grup mana pun (dibatasi mention).
- `groupPolicy: "allowlist"` — default fail-closed; hanya pengirim yang diizinkan yang diterima.
Jika Anda menggunakan permukaan produk bot Zalo yang berbeda dan telah memverifikasi perilaku grup yang berfungsi, dokumentasikan itu secara terpisah daripada mengasumsikan bahwa perilakunya sama dengan alur bot Marketplace.
## Long-polling vs webhook
- Default: long-polling (tidak memerlukan URL publik).
- Mode webhook: atur `channels.zalo.webhookUrl` dan `channels.zalo.webhookSecret`.
- Rahasia webhook harus 8-256 karakter.
- URL webhook harus menggunakan HTTPS.
- Zalo mengirim peristiwa dengan header `X-Bot-Api-Secret-Token` untuk verifikasi.
- HTTP Gateway menangani permintaan webhook di `channels.zalo.webhookPath` (default ke path URL webhook).
- Permintaan harus menggunakan `Content-Type: application/json` (atau tipe media `+json`).
- Peristiwa duplikat (`event_name + message_id`) diabaikan selama jendela replay singkat.
- Lonjakan trafik dibatasi lajunya per path/sumber dan dapat mengembalikan HTTP 429.
**Catatan:** getUpdates (polling) dan webhook saling eksklusif menurut dokumentasi API Zalo.
## Jenis pesan yang didukung
Untuk ringkasan dukungan cepat, lihat [Kemampuan](#capabilities). Catatan di bawah menambahkan detail saat perilaku memerlukan konteks tambahan.
- **Pesan teks**: Dukungan penuh dengan pemotongan 2000 karakter.
- **URL polos dalam teks**: Berperilaku seperti input teks normal.
- **Pratinjau tautan / kartu tautan rich**: Lihat status bot Marketplace di [Kemampuan](#capabilities); fitur ini tidak secara andal memicu balasan.
- **Pesan gambar**: Lihat status bot Marketplace di [Kemampuan](#capabilities); penanganan gambar masuk tidak andal (indikator mengetik tanpa balasan akhir).
- **Stiker**: Lihat status bot Marketplace di [Kemampuan](#capabilities).
- **Catatan suara / file audio / video / lampiran file umum**: Lihat status bot Marketplace di [Kemampuan](#capabilities).
- **Jenis yang tidak didukung**: Dicatat di log (misalnya, pesan dari pengguna yang dilindungi).
## Kemampuan
Tabel ini merangkum perilaku OpenClaw saat ini untuk **bot Zalo Bot Creator / Marketplace**.
| Fitur | Status |
| --------------------------- | --------------------------------------- |
| Pesan langsung | ✅ Didukung |
| Grup | ❌ Tidak tersedia untuk bot Marketplace |
| Media (gambar masuk) | ⚠️ Terbatas / verifikasi di lingkungan Anda |
| Media (gambar keluar) | ⚠️ Belum diuji ulang untuk bot Marketplace |
| URL polos dalam teks | ✅ Didukung |
| Pratinjau tautan | ⚠️ Tidak andal untuk bot Marketplace |
| Reaksi | ❌ Tidak didukung |
| Stiker | ⚠️ Tidak ada balasan agen untuk bot Marketplace |
| Catatan suara / audio / video | ⚠️ Tidak ada balasan agen untuk bot Marketplace |
| Lampiran file | ⚠️ Tidak ada balasan agen untuk bot Marketplace |
| Thread | ❌ Tidak didukung |
| Polling | ❌ Tidak didukung |
| Perintah native | ❌ Tidak didukung |
| Streaming | ⚠️ Diblokir (batas 2000 karakter) |
## Target pengiriman (CLI/cron)
- Gunakan chat id sebagai target.
- Contoh: `openclaw message send --channel zalo --target 123456789 --message "hi"`.
## Pemecahan masalah
**Bot tidak merespons:**
- Periksa apakah token valid: `openclaw channels status --probe`
- Pastikan pengirim telah disetujui (pairing atau allowFrom)
- Periksa log gateway: `openclaw logs --follow`
**Webhook tidak menerima peristiwa:**
- Pastikan URL webhook menggunakan HTTPS
- Pastikan token rahasia 8-256 karakter
- Konfirmasikan endpoint HTTP gateway dapat dijangkau pada path yang dikonfigurasi
- Periksa bahwa polling getUpdates tidak sedang berjalan (keduanya saling eksklusif)
## Referensi konfigurasi (Zalo)
Konfigurasi lengkap: [Konfigurasi](/gateway/configuration)
Key datar tingkat atas (`channels.zalo.botToken`, `channels.zalo.dmPolicy`, dan yang serupa) adalah singkatan lama untuk akun tunggal. Gunakan `channels.zalo.accounts.<id>.*` untuk konfigurasi baru. Kedua bentuk masih didokumentasikan di sini karena keduanya ada dalam schema.
Opsi provider:
- `channels.zalo.enabled`: aktifkan/nonaktifkan startup channel.
- `channels.zalo.botToken`: token bot dari Zalo Bot Platform.
- `channels.zalo.tokenFile`: baca token dari path file reguler. Symlink ditolak.
- `channels.zalo.dmPolicy`: `pairing | allowlist | open | disabled` (default: pairing).
- `channels.zalo.allowFrom`: allowlist DM (ID pengguna). `open` mengharuskan `"*"`. Wizard akan meminta ID numerik.
- `channels.zalo.groupPolicy`: `open | allowlist | disabled` (default: allowlist). Ada dalam config; lihat [Kemampuan](#capabilities) dan [Kontrol akses (Grup)](#access-control-groups) untuk perilaku bot Marketplace saat ini.
- `channels.zalo.groupAllowFrom`: allowlist pengirim grup (ID pengguna). Menggunakan fallback ke `allowFrom` saat tidak diatur.
- `channels.zalo.mediaMaxMb`: batas media masuk/keluar (MB, default 5).
- `channels.zalo.webhookUrl`: aktifkan mode webhook (HTTPS wajib).
- `channels.zalo.webhookSecret`: rahasia webhook (8-256 karakter).
- `channels.zalo.webhookPath`: path webhook pada server HTTP gateway.
- `channels.zalo.proxy`: URL proxy untuk permintaan API.
Opsi multi-akun:
- `channels.zalo.accounts.<id>.botToken`: token per akun.
- `channels.zalo.accounts.<id>.tokenFile`: file token reguler per akun. Symlink ditolak.
- `channels.zalo.accounts.<id>.name`: nama tampilan.
- `channels.zalo.accounts.<id>.enabled`: aktifkan/nonaktifkan akun.
- `channels.zalo.accounts.<id>.dmPolicy`: kebijakan DM per akun.
- `channels.zalo.accounts.<id>.allowFrom`: allowlist per akun.
- `channels.zalo.accounts.<id>.groupPolicy`: kebijakan grup per akun. Ada dalam config; lihat [Kemampuan](#capabilities) dan [Kontrol akses (Grup)](#access-control-groups) untuk perilaku bot Marketplace saat ini.
- `channels.zalo.accounts.<id>.groupAllowFrom`: allowlist pengirim grup per akun.
- `channels.zalo.accounts.<id>.webhookUrl`: URL webhook per akun.
- `channels.zalo.accounts.<id>.webhookSecret`: rahasia webhook per akun.
- `channels.zalo.accounts.<id>.webhookPath`: path webhook per akun.
- `channels.zalo.accounts.<id>.proxy`: URL proxy per akun.
## Terkait
- [Ikhtisar Channel](/channels) — semua channel yang didukung
- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing
- [Grup](/channels/groups) — perilaku chat grup dan penyaringan mention
- [Perutean Channel](/channels/channel-routing) — perutean sesi untuk pesan
- [Keamanan](/gateway/security) — model akses dan hardening

202
docs/id/channels/zalouser.md Normal file
View File

@ -0,0 +1,202 @@
---
read_when:
- Menyiapkan Zalo Personal untuk OpenClaw
- Men-debug login atau alur pesan Zalo Personal
summary: Dukungan akun pribadi Zalo melalui zca-js native (login QR), capability, dan konfigurasi
title: Zalo Personal
x-i18n:
generated_at: "2026-04-05T13:45:09Z"
model: gpt-5.4
provider: openai
source_hash: 331b95041463185472d242cb0a944972f0a8e99df8120bda6350eca86ad5963f
source_path: channels/zalouser.md
workflow: 15
---
# Zalo Personal (tidak resmi)
Status: eksperimental. Integrasi ini mengotomatisasi **akun pribadi Zalo** melalui `zca-js` native di dalam OpenClaw.
> **Peringatan:** Ini adalah integrasi tidak resmi dan dapat mengakibatkan akun ditangguhkan/diblokir. Gunakan dengan risiko Anda sendiri.
## Plugin bawaan
Zalo Personal dikirim sebagai plugin bawaan dalam rilis OpenClaw saat ini, jadi build
paket normal tidak memerlukan instalasi terpisah.
Jika Anda menggunakan build lama atau instalasi kustom yang tidak menyertakan Zalo Personal,
instal secara manual:
- Instal melalui CLI: `openclaw plugins install @openclaw/zalouser`
- Atau dari source checkout: `openclaw plugins install ./path/to/local/zalouser-plugin`
- Detail: [Plugins](/tools/plugin)
Tidak diperlukan binary CLI `zca`/`openzca` eksternal.
## Penyiapan cepat (pemula)
1. Pastikan plugin Zalo Personal tersedia.
- Rilis OpenClaw terpaket saat ini sudah menyertakannya.
- Instalasi lama/kustom dapat menambahkannya secara manual dengan perintah di atas.
2. Login (QR, di mesin Gateway):
- `openclaw channels login --channel zalouser`
- Pindai kode QR dengan aplikasi seluler Zalo.
3. Aktifkan channel:
```json5
{
channels: {
zalouser: {
enabled: true,
dmPolicy: "pairing",
},
},
}
```
4. Restart Gateway (atau selesaikan penyiapan).
5. Akses DM secara default menggunakan pairing; setujui kode pairing saat kontak pertama.
## Apa itu
- Berjalan sepenuhnya in-process melalui `zca-js`.
- Menggunakan event listener native untuk menerima pesan masuk.
- Mengirim balasan langsung melalui JS API (teks/media/tautan).
- Dirancang untuk kasus penggunaan “akun pribadi” saat Zalo Bot API tidak tersedia.
## Penamaan
ID channel adalah `zalouser` untuk menegaskan bahwa ini mengotomatisasi **akun pengguna pribadi Zalo** (tidak resmi). Kami mempertahankan `zalo` untuk potensi integrasi resmi Zalo API di masa depan.
## Menemukan ID (direktori)
Gunakan CLI direktori untuk menemukan peer/grup dan ID-nya:
```bash
openclaw directory self --channel zalouser
openclaw directory peers list --channel zalouser --query "name"
openclaw directory groups list --channel zalouser --query "work"
```
## Batasan
- Teks keluar dipecah menjadi ~2000 karakter (batas klien Zalo).
- Streaming diblokir secara default.
## Kontrol akses (DM)
`channels.zalouser.dmPolicy` mendukung: `pairing | allowlist | open | disabled` (default: `pairing`).
`channels.zalouser.allowFrom` menerima ID pengguna atau nama. Saat penyiapan, nama di-resolve menjadi ID menggunakan lookup kontak in-process milik plugin.
Setujui melalui:
- `openclaw pairing list zalouser`
- `openclaw pairing approve zalouser <code>`
## Akses grup (opsional)
- Default: `channels.zalouser.groupPolicy = "open"` (grup diizinkan). Gunakan `channels.defaults.groupPolicy` untuk menimpa default saat tidak disetel.
- Batasi ke allowlist dengan:
- `channels.zalouser.groupPolicy = "allowlist"`
- `channels.zalouser.groups` (kunci sebaiknya berupa ID grup stabil; nama di-resolve menjadi ID saat startup jika memungkinkan)
- `channels.zalouser.groupAllowFrom` (mengontrol pengirim mana di grup yang diizinkan yang dapat memicu bot)
- Blokir semua grup: `channels.zalouser.groupPolicy = "disabled"`.
- Wizard konfigurasi dapat meminta allowlist grup.
- Saat startup, OpenClaw me-resolve nama grup/pengguna dalam allowlist menjadi ID dan mencatat pemetaannya.
- Pencocokan allowlist grup secara default hanya berdasarkan ID. Nama yang tidak ter-resolve diabaikan untuk autentikasi kecuali `channels.zalouser.dangerouslyAllowNameMatching: true` diaktifkan.
- `channels.zalouser.dangerouslyAllowNameMatching: true` adalah mode kompatibilitas break-glass yang mengaktifkan kembali pencocokan nama grup yang dapat berubah.
- Jika `groupAllowFrom` tidak disetel, runtime akan fallback ke `allowFrom` untuk pemeriksaan pengirim grup.
- Pemeriksaan pengirim berlaku untuk pesan grup normal maupun perintah kontrol (misalnya `/new`, `/reset`).
Contoh:
```json5
{
channels: {
zalouser: {
groupPolicy: "allowlist",
groupAllowFrom: ["1471383327500481391"],
groups: {
"123456789": { allow: true },
"Work Chat": { allow: true },
},
},
},
}
```
### Pembatasan mention grup
- `channels.zalouser.groups.<group>.requireMention` mengontrol apakah balasan grup memerlukan mention.
- Urutan resolusi: ID/nama grup persis -> slug grup ternormalisasi -> `*` -> default (`true`).
- Ini berlaku baik untuk grup yang di-allowlist maupun mode grup terbuka.
- Perintah kontrol yang diotorisasi (misalnya `/new`) dapat mem-bypass pembatasan mention.
- Saat pesan grup dilewati karena mention diperlukan, OpenClaw menyimpannya sebagai riwayat grup tertunda dan menyertakannya pada pesan grup berikutnya yang diproses.
- Batas riwayat grup secara default adalah `messages.groupChat.historyLimit` (fallback `50`). Anda dapat menimpanya per akun dengan `channels.zalouser.historyLimit`.
Contoh:
```json5
{
channels: {
zalouser: {
groupPolicy: "allowlist",
groups: {
"*": { allow: true, requireMention: true },
"Work Chat": { allow: true, requireMention: false },
},
},
},
}
```
## Multi-akun
Akun dipetakan ke profil `zalouser` dalam status OpenClaw. Contoh:
```json5
{
channels: {
zalouser: {
enabled: true,
defaultAccount: "default",
accounts: {
work: { enabled: true, profile: "work" },
},
},
},
}
```
## Typing, reaksi, dan pengakuan pengiriman
- OpenClaw mengirim event typing sebelum mengirim balasan (best-effort).
- Tindakan reaksi pesan `react` didukung untuk `zalouser` dalam tindakan channel.
- Gunakan `remove: true` untuk menghapus emoji reaksi tertentu dari pesan.
- Semantik reaksi: [Reactions](/tools/reactions)
- Untuk pesan masuk yang menyertakan metadata event, OpenClaw mengirim pengakuan delivered + seen (best-effort).
## Pemecahan masalah
**Login tidak tersimpan:**
- `openclaw channels status --probe`
- Login ulang: `openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser`
**Allowlist/nama grup tidak ter-resolve:**
- Gunakan ID numerik di `allowFrom`/`groupAllowFrom`/`groups`, atau nama teman/grup yang persis.
**Upgrade dari penyiapan lama berbasis CLI:**
- Hapus asumsi proses `zca` eksternal lama.
- Channel sekarang berjalan sepenuhnya di OpenClaw tanpa binary CLI eksternal.
## Terkait
- [Ikhtisar Channels](/channels) — semua channel yang didukung
- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing
- [Groups](/channels/groups) — perilaku obrolan grup dan pembatasan mention
- [Channel Routing](/channels/channel-routing) — routing sesi untuk pesan
- [Security](/gateway/security) — model akses dan hardening

73
docs/id/ci.md Normal file
View File

@ -0,0 +1,73 @@
---
read_when:
- Anda perlu memahami mengapa suatu job CI berjalan atau tidak berjalan
- Anda sedang men-debug pemeriksaan GitHub Actions yang gagal
summary: Graf job CI, gate scope, dan padanan perintah lokal
title: Pipeline CI
x-i18n:
generated_at: "2026-04-05T13:44:58Z"
model: gpt-5.4
provider: openai
source_hash: 5a95b6e584b4309bc249866ea436b4dfe30e0298ab8916eadbc344edae3d1194
source_path: ci.md
workflow: 15
---
# Pipeline CI
CI berjalan pada setiap push ke `main` dan setiap pull request. Ini menggunakan scoping cerdas untuk melewati job mahal ketika hanya area yang tidak terkait yang berubah.
## Ikhtisar Job
| Job | Tujuan | Kapan dijalankan |
| ------------------------ | ---------------------------------------------------------------------------------------- | ----------------------------------- |
| `preflight` | Mendeteksi perubahan khusus docs, scope yang berubah, extension yang berubah, dan membangun manifest CI | Selalu pada push dan PR non-draft |
| `security-fast` | Deteksi private key, audit workflow melalui `zizmor`, audit dependensi produksi | Selalu pada push dan PR non-draft |
| `build-artifacts` | Membangun `dist/` dan UI Control sekali, mengunggah artifact yang dapat digunakan ulang untuk job downstream | Perubahan yang relevan dengan Node |
| `checks-fast-core` | Lane korektness Linux cepat seperti pemeriksaan bundled/plugin-contract/protocol | Perubahan yang relevan dengan Node |
| `checks-fast-extensions` | Mengagregasi lane shard extension setelah `checks-fast-extensions-shard` selesai | Perubahan yang relevan dengan Node |
| `extension-fast` | Pengujian terfokus hanya untuk bundled plugin yang berubah | Saat perubahan extension terdeteksi |
| `check` | Gate lokal utama di CI: `pnpm check` plus `pnpm build:strict-smoke` | Perubahan yang relevan dengan Node |
| `check-additional` | Guard arsitektur dan boundary plus harness regresi gateway watch | Perubahan yang relevan dengan Node |
| `build-smoke` | Pengujian smoke CLI hasil build dan smoke memori saat startup | Perubahan yang relevan dengan Node |
| `checks` | Lane Node Linux yang lebih berat: pengujian penuh, pengujian channel, dan kompatibilitas Node 22 khusus push | Perubahan yang relevan dengan Node |
| `check-docs` | Pemeriksaan format docs, lint, dan tautan rusak | Docs berubah |
| `skills-python` | Ruff + pytest untuk Skills berbasis Python | Perubahan yang relevan dengan Skills Python |
| `checks-windows` | Lane pengujian khusus Windows | Perubahan yang relevan dengan Windows |
| `macos-node` | Lane pengujian TypeScript macOS menggunakan artifact build bersama | Perubahan yang relevan dengan macOS |
| `macos-swift` | Lint, build, dan pengujian Swift untuk aplikasi macOS | Perubahan yang relevan dengan macOS |
| `android` | Matriks build dan pengujian Android | Perubahan yang relevan dengan Android |
## Urutan Fail-Fast
Job diurutkan sehingga pemeriksaan murah gagal sebelum job mahal berjalan:
1. `preflight` menentukan lane mana yang ada sama sekali. Logika `docs-scope` dan `changed-scope` adalah step di dalam job ini, bukan job terpisah.
2. `security-fast`, `check`, `check-additional`, `check-docs`, dan `skills-python` gagal cepat tanpa menunggu artifact yang lebih berat dan job matriks platform.
3. `build-artifacts` berjalan tumpang tindih dengan lane Linux cepat sehingga konsumen downstream dapat mulai segera setelah build bersama siap.
4. Setelah itu, lane platform dan runtime yang lebih berat menyebar: `checks-fast-core`, `checks-fast-extensions`, `extension-fast`, `checks`, `checks-windows`, `macos-node`, `macos-swift`, dan `android`.
Logika scope berada di `scripts/ci-changed-scope.mjs` dan dicakup oleh unit test di `src/scripts/ci-changed-scope.test.ts`.
Workflow `install-smoke` yang terpisah menggunakan ulang skrip scope yang sama melalui job `preflight` miliknya sendiri. Workflow ini menghitung `run_install_smoke` dari sinyal changed-smoke yang lebih sempit, sehingga smoke Docker/install hanya berjalan untuk perubahan yang relevan dengan install, packaging, dan container.
Pada push, matriks `checks` menambahkan lane `compat-node22` khusus push. Pada pull request, lane tersebut dilewati dan matriks tetap fokus pada lane pengujian/channel normal.
## Runner
| Runner | Job |
| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `blacksmith-16vcpu-ubuntu-2404` | `preflight`, `security-fast`, `build-artifacts`, pemeriksaan Linux, pemeriksaan docs, Skills Python, `android` |
| `blacksmith-32vcpu-windows-2025` | `checks-windows` |
| `macos-latest` | `macos-node`, `macos-swift` |
## Padanan Lokal
```bash
pnpm check # types + lint + format
pnpm build:strict-smoke
pnpm test:gateway:watch-regression
pnpm test # vitest tests
pnpm test:channels
pnpm check:docs # docs format + lint + broken links
pnpm build # build dist when CI artifact/build-smoke lanes matter
```

293
docs/id/cli/acp.md Normal file
View File

@ -0,0 +1,293 @@
---
read_when:
- Menyiapkan integrasi IDE berbasis ACP
- Men-debug perutean sesi ACP ke Gateway
summary: Jalankan bridge ACP untuk integrasi IDE
title: acp
x-i18n:
generated_at: "2026-04-05T13:45:37Z"
model: gpt-5.4
provider: openai
source_hash: 2461b181e4a97dd84580581e9436ca1947a224decce8044132dbcf7fb2b7502c
source_path: cli/acp.md
workflow: 15
---
# acp
Jalankan bridge [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) yang berbicara dengan OpenClaw Gateway.
Perintah ini berbicara ACP melalui stdio untuk IDE dan meneruskan prompt ke Gateway melalui WebSocket. Perintah ini menjaga sesi ACP tetap dipetakan ke kunci sesi Gateway.
`openclaw acp` adalah bridge ACP yang didukung Gateway, bukan runtime editor native ACP penuh. Fokusnya adalah perutean sesi, pengiriman prompt, dan pembaruan streaming dasar.
Jika Anda ingin klien MCP eksternal berbicara langsung dengan percakapan channel OpenClaw alih-alih meng-host sesi harness ACP, gunakan
[`openclaw mcp serve`](/cli/mcp).
## Ini bukan apa
Halaman ini sering disalahartikan sebagai sesi harness ACP.
`openclaw acp` berarti:
- OpenClaw bertindak sebagai server ACP
- IDE atau klien ACP terhubung ke OpenClaw
- OpenClaw meneruskan pekerjaan itu ke sesi Gateway
Ini berbeda dari [ACP Agents](/tools/acp-agents), di mana OpenClaw menjalankan harness eksternal seperti Codex atau Claude Code melalui `acpx`.
Aturan cepat:
- editor/klien ingin berbicara ACP ke OpenClaw: gunakan `openclaw acp`
- OpenClaw harus meluncurkan Codex/Claude/Gemini sebagai harness ACP: gunakan `/acp spawn` dan [ACP Agents](/tools/acp-agents)
## Matriks Kompatibilitas
| Area ACP | Status | Catatan |
| --------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `initialize`, `newSession`, `prompt`, `cancel` | Diimplementasikan | Alur bridge inti melalui stdio ke chat/send Gateway + abort. |
| `listSessions`, slash commands | Diimplementasikan | Daftar sesi bekerja terhadap status sesi Gateway; perintah diiklankan melalui `available_commands_update`. |
| `loadSession` | Parsial | Mengikat ulang sesi ACP ke kunci sesi Gateway dan memutar ulang riwayat teks pengguna/asisten yang tersimpan. Riwayat tool/sistem belum direkonstruksi. |
| Konten prompt (`text`, `resource` tersemat, gambar) | Parsial | Teks/resource diratakan ke input chat; gambar menjadi lampiran Gateway. |
| Mode sesi | Parsial | `session/set_mode` didukung dan bridge mengekspos kontrol sesi awal yang didukung Gateway untuk tingkat pemikiran, verbositas tool, penalaran, detail penggunaan, dan elevated actions. Surface mode/config native ACP yang lebih luas masih di luar cakupan. |
| Info sesi dan pembaruan penggunaan | Parsial | Bridge memancarkan notifikasi `session_info_update` dan `usage_update` best-effort dari snapshot sesi Gateway yang di-cache. Penggunaan bersifat perkiraan dan hanya dikirim saat total token Gateway ditandai fresh. |
| Streaming tool | Parsial | Event `tool_call` / `tool_call_update` mencakup I/O mentah, konten teks, dan lokasi file best-effort saat argumen/hasil tool Gateway mengeksposnya. Terminal tersemat dan output native diff yang lebih kaya masih belum diekspos. |
| Server MCP per sesi (`mcpServers`) | Tidak didukung | Mode bridge menolak permintaan server MCP per sesi. Konfigurasikan MCP di gateway atau agen OpenClaw. |
| Metode filesystem klien (`fs/read_text_file`, `fs/write_text_file`) | Tidak didukung | Bridge tidak memanggil metode filesystem klien ACP. |
| Metode terminal klien (`terminal/*`) | Tidak didukung | Bridge tidak membuat terminal klien ACP atau men-stream id terminal melalui pemanggilan tool. |
| Rencana sesi / streaming pemikiran | Tidak didukung | Bridge saat ini memancarkan teks output dan status tool, bukan pembaruan rencana atau pemikiran ACP. |
## Keterbatasan yang Diketahui
- `loadSession` memutar ulang riwayat teks pengguna dan asisten yang tersimpan, tetapi tidak merekonstruksi pemanggilan tool historis, pemberitahuan sistem, atau jenis event native ACP yang lebih kaya.
- Jika beberapa klien ACP berbagi kunci sesi Gateway yang sama, perutean event dan cancel bersifat best-effort, bukan benar-benar terisolasi per klien. Gunakan sesi `acp:<uuid>` terisolasi default saat Anda memerlukan giliran lokal editor yang bersih.
- Status berhenti Gateway diterjemahkan ke alasan berhenti ACP, tetapi pemetaan itu kurang ekspresif dibanding runtime native ACP penuh.
- Kontrol sesi awal saat ini hanya mengekspos subset terfokus dari knob Gateway: tingkat pemikiran, verbositas tool, penalaran, detail penggunaan, dan elevated actions. Pemilihan model serta kontrol exec-host belum diekspos sebagai opsi config ACP.
- `session_info_update` dan `usage_update` diturunkan dari snapshot sesi Gateway, bukan akuntansi runtime native ACP langsung. Penggunaan bersifat perkiraan, tidak membawa data biaya, dan hanya dipancarkan saat Gateway menandai data total token sebagai fresh.
- Data follow-along tool bersifat best-effort. Bridge dapat menampilkan jalur file yang muncul dalam argumen/hasil tool yang dikenal, tetapi belum memancarkan terminal ACP atau diff file terstruktur.
## Penggunaan
```bash
openclaw acp
# Gateway jarak jauh
openclaw acp --url wss://gateway-host:18789 --token <token>
# Gateway jarak jauh (token dari file)
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token
# Lampirkan ke kunci sesi yang sudah ada
openclaw acp --session agent:main:main
# Lampirkan berdasarkan label (harus sudah ada)
openclaw acp --session-label "support inbox"
# Reset kunci sesi sebelum prompt pertama
openclaw acp --session agent:main:main --reset-session
```
## Klien ACP (debug)
Gunakan klien ACP bawaan untuk sanity-check bridge tanpa IDE.
Perintah ini menjalankan bridge ACP dan memungkinkan Anda mengetik prompt secara interaktif.
```bash
openclaw acp client
# Arahkan bridge yang dijalankan ke Gateway jarak jauh
openclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token
# Override perintah server (default: openclaw)
openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001
```
Model izin (mode debug klien):
- Persetujuan otomatis berbasis allowlist dan hanya berlaku untuk ID tool inti tepercaya.
- Persetujuan otomatis `read` dibatasi ke direktori kerja saat ini (`--cwd` jika disetel).
- ACP hanya menyetujui otomatis kelas readonly yang sempit: pemanggilan `read` yang dibatasi di bawah cwd aktif plus tool pencarian readonly (`search`, `web_search`, `memory_search`). Tool yang tidak dikenal/non-inti, pembacaan di luar cakupan, tool yang mampu exec, tool control-plane, tool yang memodifikasi, dan alur interaktif selalu memerlukan persetujuan prompt eksplisit.
- `toolCall.kind` yang disediakan server diperlakukan sebagai metadata yang tidak tepercaya (bukan sumber otorisasi).
- Kebijakan bridge ACP ini terpisah dari izin harness ACPX. Jika Anda menjalankan OpenClaw melalui backend `acpx`, `plugins.entries.acpx.config.permissionMode=approve-all` adalah sakelar break-glass “yolo” untuk sesi harness tersebut.
## Cara menggunakan ini
Gunakan ACP saat IDE (atau klien lain) berbicara Agent Client Protocol dan Anda ingin IDE itu mengendalikan sesi OpenClaw Gateway.
1. Pastikan Gateway sedang berjalan (lokal atau jarak jauh).
2. Konfigurasikan target Gateway (config atau flag).
3. Arahkan IDE Anda untuk menjalankan `openclaw acp` melalui stdio.
Contoh config (persisten):
```bash
openclaw config set gateway.remote.url wss://gateway-host:18789
openclaw config set gateway.remote.token <token>
```
Contoh menjalankan langsung (tanpa menulis config):
```bash
openclaw acp --url wss://gateway-host:18789 --token <token>
# disarankan untuk keamanan proses lokal
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token
```
## Memilih agen
ACP tidak memilih agen secara langsung. ACP merutekan berdasarkan kunci sesi Gateway.
Gunakan kunci sesi yang dicakup agen untuk menargetkan agen tertentu:
```bash
openclaw acp --session agent:main:main
openclaw acp --session agent:design:main
openclaw acp --session agent:qa:bug-123
```
Setiap sesi ACP dipetakan ke satu kunci sesi Gateway. Satu agen dapat memiliki banyak sesi; ACP default ke sesi `acp:<uuid>` terisolasi kecuali Anda menimpa kunci atau labelnya.
`mcpServers` per sesi tidak didukung dalam mode bridge. Jika klien ACP mengirimkannya selama `newSession` atau `loadSession`, bridge akan mengembalikan error yang jelas alih-alih mengabaikannya secara diam-diam.
Jika Anda ingin sesi yang didukung ACPX melihat plugin tools OpenClaw, aktifkan bridge plugin ACPX di sisi gateway alih-alih mencoba meneruskan `mcpServers` per sesi. Lihat [ACP Agents](/tools/acp-agents#plugin-tools-mcp-bridge).
## Gunakan dari `acpx` (Codex, Claude, klien ACP lainnya)
Jika Anda ingin agen coding seperti Codex atau Claude Code berbicara dengan bot OpenClaw Anda melalui ACP, gunakan `acpx` dengan target `openclaw` bawaannya.
Alur umum:
1. Jalankan Gateway dan pastikan bridge ACP dapat menjangkaunya.
2. Arahkan `acpx openclaw` ke `openclaw acp`.
3. Targetkan kunci sesi OpenClaw yang ingin digunakan agen coding tersebut.
Contoh:
```bash
# Permintaan sekali jalan ke sesi ACP OpenClaw default Anda
acpx openclaw exec "Ringkas status sesi OpenClaw aktif."
# Sesi bernama persisten untuk giliran lanjutan
acpx openclaw sessions ensure --name codex-bridge
acpx openclaw -s codex-bridge --cwd /path/to/repo \
"Tanyakan ke agen kerja OpenClaw saya konteks terbaru yang relevan untuk repo ini."
```
Jika Anda ingin `acpx openclaw` selalu menargetkan Gateway dan kunci sesi tertentu, timpa perintah agen `openclaw` di `~/.acpx/config.json`:
```json
{
"agents": {
"openclaw": {
"command": "env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 openclaw acp --url ws://127.0.0.1:18789 --token-file ~/.openclaw/gateway.token --session agent:main:main"
}
}
}
```
Untuk checkout OpenClaw lokal berbasis repo, gunakan entrypoint CLI langsung alih-alih dev runner agar stream ACP tetap bersih. Contohnya:
```bash
env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ...
```
Ini adalah cara termudah untuk membiarkan Codex, Claude Code, atau klien lain yang mendukung ACP menarik informasi kontekstual dari agen OpenClaw tanpa mengikis terminal.
## Setup editor Zed
Tambahkan agen ACP kustom di `~/.config/zed/settings.json` (atau gunakan UI Settings Zed):
```json
{
"agent_servers": {
"OpenClaw ACP": {
"type": "custom",
"command": "openclaw",
"args": ["acp"],
"env": {}
}
}
}
```
Untuk menargetkan Gateway atau agen tertentu:
```json
{
"agent_servers": {
"OpenClaw ACP": {
"type": "custom",
"command": "openclaw",
"args": [
"acp",
"--url",
"wss://gateway-host:18789",
"--token",
"<token>",
"--session",
"agent:design:main"
],
"env": {}
}
}
}
```
Di Zed, buka panel Agent dan pilih “OpenClaw ACP” untuk memulai thread.
## Pemetaan sesi
Secara default, sesi ACP mendapatkan kunci sesi Gateway terisolasi dengan prefiks `acp:`.
Untuk menggunakan ulang sesi yang diketahui, berikan kunci sesi atau label:
- `--session <key>`: gunakan kunci sesi Gateway tertentu.
- `--session-label <label>`: resolve sesi yang sudah ada berdasarkan label.
- `--reset-session`: buat id sesi baru untuk kunci itu (kunci sama, transkrip baru).
Jika klien ACP Anda mendukung metadata, Anda dapat menimpa per sesi:
```json
{
"_meta": {
"sessionKey": "agent:main:main",
"sessionLabel": "support inbox",
"resetSession": true
}
}
```
Pelajari lebih lanjut tentang kunci sesi di [/concepts/session](/concepts/session).
## Opsi
- `--url <url>`: URL WebSocket Gateway (default ke `gateway.remote.url` jika dikonfigurasi).
- `--token <token>`: token autentikasi Gateway.
- `--token-file <path>`: baca token autentikasi Gateway dari file.
- `--password <password>`: kata sandi autentikasi Gateway.
- `--password-file <path>`: baca kata sandi autentikasi Gateway dari file.
- `--session <key>`: kunci sesi default.
- `--session-label <label>`: label sesi default untuk di-resolve.
- `--require-existing`: gagal jika kunci/label sesi tidak ada.
- `--reset-session`: reset kunci sesi sebelum penggunaan pertama.
- `--no-prefix-cwd`: jangan awali prompt dengan direktori kerja.
- `--provenance <off|meta|meta+receipt>`: sertakan metadata atau receipt provenance ACP.
- `--verbose, -v`: logging verbose ke stderr.
Catatan keamanan:
- `--token` dan `--password` dapat terlihat di daftar proses lokal pada beberapa sistem.
- Gunakan `--token-file`/`--password-file` atau variabel lingkungan (`OPENCLAW_GATEWAY_TOKEN`, `OPENCLAW_GATEWAY_PASSWORD`).
- Resolusi autentikasi Gateway mengikuti kontrak bersama yang digunakan oleh klien Gateway lain:
- mode lokal: env (`OPENCLAW_GATEWAY_*`) -> `gateway.auth.*` -> fallback `gateway.remote.*` hanya saat `gateway.auth.*` tidak disetel (SecretRef lokal yang dikonfigurasi tetapi tidak dapat di-resolve gagal tertutup)
- mode jarak jauh: `gateway.remote.*` dengan fallback env/config sesuai aturan prioritas remote
- `--url` aman untuk override dan tidak menggunakan ulang kredensial env/config implisit; berikan `--token`/`--password` eksplisit (atau varian file)
- Proses child backend runtime ACP menerima `OPENCLAW_SHELL=acp`, yang dapat digunakan untuk aturan shell/profile spesifik konteks.
- `openclaw acp client` menyetel `OPENCLAW_SHELL=acp-client` pada proses bridge yang dijalankan.
### Opsi `acp client`
- `--cwd <dir>`: direktori kerja untuk sesi ACP.
- `--server <command>`: perintah server ACP (default: `openclaw`).
- `--server-args <args...>`: argumen tambahan yang diteruskan ke server ACP.
- `--server-verbose`: aktifkan logging verbose pada server ACP.
- `--verbose, -v`: logging verbose klien.

64
docs/id/cli/agent.md Normal file
View File

@ -0,0 +1,64 @@
---
read_when:
- Anda ingin menjalankan satu giliran agen dari skrip (opsional kirim balasan)
summary: Referensi CLI untuk `openclaw agent` (kirim satu giliran agen melalui Gateway)
title: agent
x-i18n:
generated_at: "2026-04-05T13:45:04Z"
model: gpt-5.4
provider: openai
source_hash: 0627f943bc7f3556318008f76dc6150788cf06927dccdc7d2681acb98f257d56
source_path: cli/agent.md
workflow: 15
---
# `openclaw agent`
Jalankan satu giliran agen melalui Gateway (gunakan `--local` untuk mode tersemat).
Gunakan `--agent <id>` untuk langsung menargetkan agen yang dikonfigurasi.
Berikan setidaknya satu pemilih sesi:
- `--to <dest>`
- `--session-id <id>`
- `--agent <id>`
Terkait:
- Tool pengiriman agen: [Agent send](/tools/agent-send)
## Opsi
- `-m, --message <text>`: isi pesan wajib
- `-t, --to <dest>`: penerima yang digunakan untuk menurunkan kunci sesi
- `--session-id <id>`: id sesi eksplisit
- `--agent <id>`: id agen; menggantikan binding routing
- `--thinking <off|minimal|low|medium|high|xhigh>`: level thinking agen
- `--verbose <on|off>`: simpan level verbose untuk sesi
- `--channel <channel>`: channel pengiriman; hilangkan untuk menggunakan channel sesi utama
- `--reply-to <target>`: override target pengiriman
- `--reply-channel <channel>`: override channel pengiriman
- `--reply-account <id>`: override akun pengiriman
- `--local`: jalankan agen tersemat secara langsung (setelah preload registry plugin)
- `--deliver`: kirim balasan kembali ke channel/target yang dipilih
- `--timeout <seconds>`: override timeout agen (default 600 atau nilai config)
- `--json`: keluarkan JSON
## Contoh
```bash
openclaw agent --to +15555550123 --message "status update" --deliver
openclaw agent --agent ops --message "Summarize logs"
openclaw agent --session-id 1234 --message "Summarize inbox" --thinking medium
openclaw agent --to +15555550123 --message "Trace logs" --verbose on --json
openclaw agent --agent ops --message "Generate report" --deliver --reply-channel slack --reply-to "#reports"
openclaw agent --agent ops --message "Run locally" --local
```
## Catatan
- Mode Gateway fallback ke agen tersemat saat permintaan Gateway gagal. Gunakan `--local` untuk memaksa eksekusi tersemat sejak awal.
- `--local` tetap melakukan preload registry plugin terlebih dahulu, sehingga provider, tool, dan channel yang disediakan plugin tetap tersedia selama eksekusi tersemat.
- `--channel`, `--reply-channel`, dan `--reply-account` memengaruhi pengiriman balasan, bukan routing sesi.
- Saat perintah ini memicu regenerasi `models.json`, kredensial provider yang dikelola SecretRef disimpan sebagai penanda non-rahasia (misalnya nama env var, `secretref-env:ENV_VAR_NAME`, atau `secretref-managed`), bukan plaintext rahasia yang sudah di-resolve.
- Penulisan penanda bersifat source-authoritative: OpenClaw menyimpan penanda dari snapshot config sumber aktif, bukan dari nilai rahasia runtime yang sudah di-resolve.

227
docs/id/cli/agents.md Normal file
View File

@ -0,0 +1,227 @@
---
read_when:
- Anda menginginkan beberapa agen terisolasi (workspace + perutean + auth)
summary: Referensi CLI untuk `openclaw agents` (list/add/delete/bindings/bind/unbind/set identity)
title: agents
x-i18n:
generated_at: "2026-04-05T13:45:14Z"
model: gpt-5.4
provider: openai
source_hash: 90b90c4915993bd8af322c0590d4cb59baabb8940598ce741315f8f95ef43179
source_path: cli/agents.md
workflow: 15
---
# `openclaw agents`
Kelola agen terisolasi (workspace + auth + perutean).
Terkait:
- Perutean multi-agen: [Perutean Multi-Agen](/concepts/multi-agent)
- Workspace agen: [Workspace agen](/concepts/agent-workspace)
- Konfigurasi visibilitas skill: [Konfigurasi Skills](/tools/skills-config)
## Contoh
```bash
openclaw agents list
openclaw agents list --bindings
openclaw agents add work --workspace ~/.openclaw/workspace-work
openclaw agents add ops --workspace ~/.openclaw/workspace-ops --bind telegram:ops --non-interactive
openclaw agents bindings
openclaw agents bind --agent work --bind telegram:ops
openclaw agents unbind --agent work --bind telegram:ops
openclaw agents set-identity --workspace ~/.openclaw/workspace --from-identity
openclaw agents set-identity --agent main --avatar avatars/openclaw.png
openclaw agents delete work
```
## Binding perutean
Gunakan binding perutean untuk menyematkan lalu lintas channel masuk ke agen tertentu.
Jika Anda juga menginginkan Skills yang terlihat berbeda per agen, konfigurasikan
`agents.defaults.skills` dan `agents.list[].skills` di `openclaw.json`. Lihat
[Konfigurasi Skills](/tools/skills-config) dan
[Referensi Konfigurasi](/gateway/configuration-reference#agentsdefaultsskills).
Daftar binding:
```bash
openclaw agents bindings
openclaw agents bindings --agent work
openclaw agents bindings --json
```
Tambahkan binding:
```bash
openclaw agents bind --agent work --bind telegram:ops --bind discord:guild-a
```
Jika Anda menghilangkan `accountId` (`--bind <channel>`), OpenClaw meresolusikannya dari default channel dan hook penyiapan plugin bila tersedia.
Jika Anda menghilangkan `--agent` untuk `bind` atau `unbind`, OpenClaw menargetkan agen default saat ini.
### Perilaku cakupan binding
- Binding tanpa `accountId` hanya cocok dengan akun default channel.
- `accountId: "*"` adalah fallback seluruh channel (semua akun) dan kurang spesifik dibanding binding akun eksplisit.
- Jika agen yang sama sudah memiliki binding channel yang cocok tanpa `accountId`, lalu Anda mengikat dengan `accountId` eksplisit atau yang telah diresolusikan, OpenClaw meningkatkan binding yang sudah ada tersebut di tempat alih-alih menambahkan duplikat.
Contoh:
```bash
# binding awal hanya channel
openclaw agents bind --agent work --bind telegram
# kemudian tingkatkan ke binding bercakupan akun
openclaw agents bind --agent work --bind telegram:ops
```
Setelah peningkatan, perutean untuk binding tersebut dicakup ke `telegram:ops`. Jika Anda juga menginginkan perutean akun default, tambahkan secara eksplisit (misalnya `--bind telegram:default`).
Hapus binding:
```bash
openclaw agents unbind --agent work --bind telegram:ops
openclaw agents unbind --agent work --all
```
`unbind` menerima `--all` atau satu atau beberapa nilai `--bind`, tidak keduanya.
## Permukaan perintah
### `agents`
Menjalankan `openclaw agents` tanpa subperintah setara dengan `openclaw agents list`.
### `agents list`
Opsi:
- `--json`
- `--bindings`: sertakan aturan perutean lengkap, bukan hanya jumlah/ringkasan per agen
### `agents add [name]`
Opsi:
- `--workspace <dir>`
- `--model <id>`
- `--agent-dir <dir>`
- `--bind <channel[:accountId]>` (dapat diulang)
- `--non-interactive`
- `--json`
Catatan:
- Meneruskan flag add eksplisit apa pun mengalihkan perintah ke jalur non-interaktif.
- Mode non-interaktif memerlukan nama agen dan `--workspace`.
- `main` dicadangkan dan tidak dapat digunakan sebagai id agen baru.
### `agents bindings`
Opsi:
- `--agent <id>`
- `--json`
### `agents bind`
Opsi:
- `--agent <id>` (default ke agen default saat ini)
- `--bind <channel[:accountId]>` (dapat diulang)
- `--json`
### `agents unbind`
Opsi:
- `--agent <id>` (default ke agen default saat ini)
- `--bind <channel[:accountId]>` (dapat diulang)
- `--all`
- `--json`
### `agents delete <id>`
Opsi:
- `--force`
- `--json`
Catatan:
- `main` tidak dapat dihapus.
- Tanpa `--force`, konfirmasi interaktif diperlukan.
- Workspace, status agen, dan direktori transkrip sesi dipindahkan ke Trash, bukan dihapus permanen.
## File identitas
Setiap workspace agen dapat menyertakan `IDENTITY.md` di root workspace:
- Contoh path: `~/.openclaw/workspace/IDENTITY.md`
- `set-identity --from-identity` membaca dari root workspace (atau `--identity-file` eksplisit)
Path avatar diresolusikan relatif terhadap root workspace.
## Set identity
`set-identity` menulis field ke `agents.list[].identity`:
- `name`
- `theme`
- `emoji`
- `avatar` (path relatif workspace, URL http(s), atau URI data)
Opsi:
- `--agent <id>`
- `--workspace <dir>`
- `--identity-file <path>`
- `--from-identity`
- `--name <name>`
- `--theme <theme>`
- `--emoji <emoji>`
- `--avatar <value>`
- `--json`
Catatan:
- `--agent` atau `--workspace` dapat digunakan untuk memilih agen target.
- Jika Anda mengandalkan `--workspace` dan beberapa agen berbagi workspace tersebut, perintah gagal dan meminta Anda meneruskan `--agent`.
- Saat tidak ada field identitas eksplisit yang diberikan, perintah membaca data identitas dari `IDENTITY.md`.
Muat dari `IDENTITY.md`:
```bash
openclaw agents set-identity --workspace ~/.openclaw/workspace --from-identity
```
Timpa field secara eksplisit:
```bash
openclaw agents set-identity --agent main --name "OpenClaw" --emoji "🦞" --avatar avatars/openclaw.png
```
Contoh config:
```json5
{
agents: {
list: [
{
id: "main",
identity: {
name: "OpenClaw",
theme: "space lobster",
emoji: "🦞",
avatar: "avatars/openclaw.png",
},
},
],
},
}
```

143
docs/id/cli/approvals.md Normal file
View File

@ -0,0 +1,143 @@
---
read_when:
- Anda ingin mengedit persetujuan exec dari CLI
- Anda perlu mengelola allowlist pada host gateway atau node
summary: Referensi CLI untuk `openclaw approvals` (persetujuan exec untuk gateway atau host node)
title: approvals
x-i18n:
generated_at: "2026-04-05T13:45:10Z"
model: gpt-5.4
provider: openai
source_hash: 7b2532bfd3e6e6ce43c96a2807df2dd00cb7b4320b77a7dfd09bee0531da610e
source_path: cli/approvals.md
workflow: 15
---
# `openclaw approvals`
Kelola persetujuan exec untuk **host lokal**, **host gateway**, atau **host node**.
Secara default, perintah menargetkan file persetujuan lokal di disk. Gunakan `--gateway` untuk menargetkan gateway, atau `--node` untuk menargetkan node tertentu.
Alias: `openclaw exec-approvals`
Terkait:
- Persetujuan exec: [Exec approvals](/tools/exec-approvals)
- Node: [Nodes](/nodes)
## Perintah umum
```bash
openclaw approvals get
openclaw approvals get --node <id|name|ip>
openclaw approvals get --gateway
```
`openclaw approvals get` sekarang menampilkan kebijakan exec efektif untuk target lokal, gateway, dan node:
- kebijakan `tools.exec` yang diminta
- kebijakan file persetujuan host
- hasil efektif setelah aturan prioritas diterapkan
Prioritas ini disengaja:
- file persetujuan host adalah sumber kebenaran yang dapat diberlakukan
- kebijakan `tools.exec` yang diminta dapat mempersempit atau memperluas maksud, tetapi hasil efektif tetap diturunkan dari aturan host
- `--node` menggabungkan file persetujuan host node dengan kebijakan gateway `tools.exec`, karena keduanya tetap berlaku saat runtime
- jika config gateway tidak tersedia, CLI akan fallback ke snapshot persetujuan node dan mencatat bahwa kebijakan runtime akhir tidak dapat dihitung
## Ganti persetujuan dari file
```bash
openclaw approvals set --file ./exec-approvals.json
openclaw approvals set --stdin <<'EOF'
{ version: 1, defaults: { security: "full", ask: "off" } }
EOF
openclaw approvals set --node <id|name|ip> --file ./exec-approvals.json
openclaw approvals set --gateway --file ./exec-approvals.json
```
`set` menerima JSON5, bukan hanya JSON ketat. Gunakan `--file` atau `--stdin`, jangan keduanya.
## Contoh "Never prompt" / YOLO
Untuk host yang seharusnya tidak pernah berhenti pada persetujuan exec, setel default persetujuan host ke `full` + `off`:
```bash
openclaw approvals set --stdin <<'EOF'
{
version: 1,
defaults: {
security: "full",
ask: "off",
askFallback: "full"
}
}
EOF
```
Varian node:
```bash
openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
{
version: 1,
defaults: {
security: "full",
ask: "off",
askFallback: "full"
}
}
EOF
```
Ini hanya mengubah **file persetujuan host**. Untuk menjaga kebijakan OpenClaw yang diminta tetap selaras, setel juga:
```bash
openclaw config set tools.exec.host gateway
openclaw config set tools.exec.security full
openclaw config set tools.exec.ask off
```
Mengapa `tools.exec.host=gateway` pada contoh ini:
- `host=auto` tetap berarti "sandbox jika tersedia, jika tidak gateway".
- YOLO berkaitan dengan persetujuan, bukan routing.
- Jika Anda menginginkan exec host bahkan ketika sandbox dikonfigurasi, buat pilihan host menjadi eksplisit dengan `gateway` atau `/exec host=gateway`.
Ini sesuai dengan perilaku default host YOLO saat ini. Perketat jika Anda menginginkan persetujuan.
## Helper allowlist
```bash
openclaw approvals allowlist add "~/Projects/**/bin/rg"
openclaw approvals allowlist add --agent main --node <id|name|ip> "/usr/bin/uptime"
openclaw approvals allowlist add --agent "*" "/usr/bin/uname"
openclaw approvals allowlist remove "~/Projects/**/bin/rg"
```
## Opsi umum
`get`, `set`, dan `allowlist add|remove` semuanya mendukung:
- `--node <id|name|ip>`
- `--gateway`
- opsi RPC node bersama: `--url`, `--token`, `--timeout`, `--json`
Catatan penargetan:
- tanpa flag target berarti file persetujuan lokal di disk
- `--gateway` menargetkan file persetujuan host gateway
- `--node` menargetkan satu host node setelah menyelesaikan id, nama, IP, atau prefiks id
`allowlist add|remove` juga mendukung:
- `--agent <id>` (default ke `*`)
## Catatan
- `--node` menggunakan resolver yang sama seperti `openclaw nodes` (id, nama, ip, atau prefiks id).
- `--agent` default ke `"*"`, yang berlaku untuk semua agen.
- Host node harus mengiklankan `system.execApprovals.get/set` (aplikasi macOS atau host node headless).
- File persetujuan disimpan per host di `~/.openclaw/exec-approvals.json`.

91
docs/id/cli/backup.md Normal file
View File

@ -0,0 +1,91 @@
---
read_when:
- Anda menginginkan arsip cadangan kelas satu untuk status OpenClaw lokal
- Anda ingin melihat pratinjau path mana yang akan disertakan sebelum reset atau uninstall
summary: Referensi CLI untuk `openclaw backup` (membuat arsip cadangan lokal)
title: backup
x-i18n:
generated_at: "2026-04-05T13:45:17Z"
model: gpt-5.4
provider: openai
source_hash: 700eda8f9eac1cc93a854fa579f128e5e97d4e6dfc0da75b437c0fb2a898a37d
source_path: cli/backup.md
workflow: 15
---
# `openclaw backup`
Buat arsip cadangan lokal untuk status, config, profil autentikasi, kredensial channel/provider, sesi, dan secara opsional workspace OpenClaw.
```bash
openclaw backup create
openclaw backup create --output ~/Backups
openclaw backup create --dry-run --json
openclaw backup create --verify
openclaw backup create --no-include-workspace
openclaw backup create --only-config
openclaw backup verify ./2026-03-09T00-00-00.000Z-openclaw-backup.tar.gz
```
## Catatan
- Arsip menyertakan file `manifest.json` dengan path sumber yang telah di-resolve dan tata letak arsip.
- Output default adalah arsip `.tar.gz` bertimestamp di direktori kerja saat ini.
- Jika direktori kerja saat ini berada di dalam tree sumber yang dicadangkan, OpenClaw akan fallback ke direktori home Anda untuk lokasi arsip default.
- File arsip yang sudah ada tidak pernah ditimpa.
- Path output di dalam tree status/workspace sumber ditolak untuk menghindari penyertaan diri sendiri.
- `openclaw backup verify <archive>` memvalidasi bahwa arsip berisi tepat satu manifest root, menolak path arsip bergaya traversal, dan memeriksa bahwa setiap payload yang dideklarasikan manifest ada di dalam tarball.
- `openclaw backup create --verify` menjalankan validasi tersebut segera setelah arsip ditulis.
- `openclaw backup create --only-config` hanya mencadangkan file config JSON aktif.
## Apa yang dicadangkan
`openclaw backup create` merencanakan sumber cadangan dari instalasi OpenClaw lokal Anda:
- Direktori status yang dikembalikan oleh resolver status lokal OpenClaw, biasanya `~/.openclaw`
- Path file config aktif
- Direktori `credentials/` yang telah di-resolve jika berada di luar direktori status
- Direktori workspace yang ditemukan dari config saat ini, kecuali jika Anda meneruskan `--no-include-workspace`
Profil autentikasi model sudah menjadi bagian dari direktori status di bawah
`agents/<agentId>/agent/auth-profiles.json`, sehingga biasanya sudah tercakup oleh entri cadangan
status.
Jika Anda menggunakan `--only-config`, OpenClaw melewati penemuan status, direktori kredensial, dan workspace, lalu hanya mengarsipkan path file config aktif.
OpenClaw mengkanonisasi path sebelum membangun arsip. Jika config, direktori
kredensial, atau workspace sudah berada di dalam direktori status,
mereka tidak diduplikasi sebagai sumber cadangan tingkat atas yang terpisah. Path yang hilang akan
dilewati.
Payload arsip menyimpan isi file dari tree sumber tersebut, dan `manifest.json` yang tersemat mencatat path sumber absolut yang telah di-resolve beserta tata letak arsip yang digunakan untuk setiap aset.
## Perilaku config tidak valid
`openclaw backup` sengaja melewati preflight config normal agar tetap dapat membantu selama pemulihan. Karena penemuan workspace bergantung pada config yang valid, `openclaw backup create` sekarang gagal cepat saat file config ada tetapi tidak valid dan pencadangan workspace masih diaktifkan.
Jika Anda tetap menginginkan cadangan parsial dalam situasi tersebut, jalankan ulang:
```bash
openclaw backup create --no-include-workspace
```
Itu akan tetap mencakup status, config, dan direktori kredensial eksternal sambil
melewati penemuan workspace sepenuhnya.
Jika Anda hanya memerlukan salinan file config itu sendiri, `--only-config` juga berfungsi saat config bermasalah karena tidak bergantung pada parsing config untuk penemuan workspace.
## Ukuran dan performa
OpenClaw tidak menerapkan ukuran cadangan maksimum bawaan atau batas ukuran per file.
Batas praktis berasal dari mesin lokal dan filesystem tujuan:
- Ruang yang tersedia untuk penulisan arsip sementara ditambah arsip akhir
- Waktu untuk menelusuri tree workspace besar dan mengompresnya ke dalam `.tar.gz`
- Waktu untuk memindai ulang arsip jika Anda menggunakan `openclaw backup create --verify` atau menjalankan `openclaw backup verify`
- Perilaku filesystem pada path tujuan. OpenClaw lebih memilih langkah publish hard-link tanpa overwrite dan fallback ke penyalinan eksklusif saat hard link tidak didukung
Workspace besar biasanya menjadi faktor utama ukuran arsip. Jika Anda menginginkan cadangan yang lebih kecil atau lebih cepat, gunakan `--no-include-workspace`.
Untuk arsip terkecil, gunakan `--only-config`.

240
docs/id/cli/browser.md Normal file
View File

@ -0,0 +1,240 @@
---
read_when:
- Anda menggunakan `openclaw browser` dan ingin contoh untuk tugas umum
- Anda ingin mengontrol browser yang berjalan di mesin lain melalui host node
- Anda ingin menempel ke Chrome lokal yang sudah login melalui Chrome MCP
summary: Referensi CLI untuk `openclaw browser` (siklus hidup, profil, tab, aksi, status, dan debugging)
title: browser
x-i18n:
generated_at: "2026-04-05T13:45:27Z"
model: gpt-5.4
provider: openai
source_hash: c89a7483dd733863dd8ebd47a14fbb411808ad07daaed515c1270978de9157e7
source_path: cli/browser.md
workflow: 15
---
# `openclaw browser`
Kelola permukaan kontrol browser OpenClaw dan jalankan aksi browser (siklus hidup, profil, tab, snapshot, tangkapan layar, navigasi, input, emulasi status, dan debugging).
Terkait:
- Tool + API browser: [Browser tool](/tools/browser)
## Flag umum
- `--url <gatewayWsUrl>`: URL WebSocket Gateway (default dari config).
- `--token <token>`: token Gateway (jika diperlukan).
- `--timeout <ms>`: timeout permintaan (ms).
- `--expect-final`: tunggu respons Gateway final.
- `--browser-profile <name>`: pilih profil browser (default dari config).
- `--json`: output yang dapat dibaca mesin (jika didukung).
## Mulai cepat (lokal)
```bash
openclaw browser profiles
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot
```
## Siklus hidup
```bash
openclaw browser status
openclaw browser start
openclaw browser stop
openclaw browser --browser-profile openclaw reset-profile
```
Catatan:
- Untuk profil `attachOnly` dan CDP jarak jauh, `openclaw browser stop` menutup
sesi kontrol aktif dan menghapus override emulasi sementara meskipun
OpenClaw tidak meluncurkan proses browser itu sendiri.
- Untuk profil terkelola lokal, `openclaw browser stop` menghentikan proses
browser yang diluncurkan.
## Jika perintah tidak ada
Jika `openclaw browser` adalah perintah yang tidak dikenal, periksa `plugins.allow` di
`~/.openclaw/openclaw.json`.
Saat `plugins.allow` ada, plugin browser bawaan harus dicantumkan
secara eksplisit:
```json5
{
plugins: {
allow: ["telegram", "browser"],
},
}
```
`browser.enabled=true` tidak memulihkan subperintah CLI saat
allowlist plugin mengecualikan `browser`.
Terkait: [Browser tool](/tools/browser#missing-browser-command-or-tool)
## Profil
Profil adalah config routing browser bernama. Dalam praktiknya:
- `openclaw`: meluncurkan atau menempel ke instance Chrome khusus yang dikelola OpenClaw (direktori data pengguna terisolasi).
- `user`: mengontrol sesi Chrome Anda yang sudah login melalui Chrome DevTools MCP.
- profil CDP kustom: mengarah ke endpoint CDP lokal atau jarak jauh.
```bash
openclaw browser profiles
openclaw browser create-profile --name work --color "#FF5A36"
openclaw browser create-profile --name chrome-live --driver existing-session
openclaw browser create-profile --name remote --cdp-url https://browser-host.example.com
openclaw browser delete-profile --name work
```
Gunakan profil tertentu:
```bash
openclaw browser --browser-profile work tabs
```
## Tab
```bash
openclaw browser tabs
openclaw browser tab new
openclaw browser tab select 2
openclaw browser tab close 2
openclaw browser open https://docs.openclaw.ai
openclaw browser focus <targetId>
openclaw browser close <targetId>
```
## Snapshot / tangkapan layar / aksi
Snapshot:
```bash
openclaw browser snapshot
```
Tangkapan layar:
```bash
openclaw browser screenshot
openclaw browser screenshot --full-page
openclaw browser screenshot --ref e12
```
Catatan:
- `--full-page` hanya untuk pengambilan halaman; tidak dapat digabungkan dengan `--ref`
atau `--element`.
- Profil `existing-session` / `user` mendukung tangkapan layar halaman dan tangkapan layar `--ref`
dari output snapshot, tetapi tidak mendukung tangkapan layar CSS `--element`.
Navigasi/klik/ketik (otomasi UI berbasis ref):
```bash
openclaw browser navigate https://example.com
openclaw browser click <ref>
openclaw browser type <ref> "hello"
openclaw browser press Enter
openclaw browser hover <ref>
openclaw browser scrollintoview <ref>
openclaw browser drag <startRef> <endRef>
openclaw browser select <ref> OptionA OptionB
openclaw browser fill --fields '[{"ref":"1","value":"Ada"}]'
openclaw browser wait --text "Done"
openclaw browser evaluate --fn '(el) => el.textContent' --ref <ref>
```
Helper file + dialog:
```bash
openclaw browser upload /tmp/openclaw/uploads/file.pdf --ref <ref>
openclaw browser waitfordownload
openclaw browser download <ref> report.pdf
openclaw browser dialog --accept
```
## Status dan penyimpanan
Viewport + emulasi:
```bash
openclaw browser resize 1280 720
openclaw browser set viewport 1280 720
openclaw browser set offline on
openclaw browser set media dark
openclaw browser set timezone Europe/London
openclaw browser set locale en-GB
openclaw browser set geo 51.5074 -0.1278 --accuracy 25
openclaw browser set device "iPhone 14"
openclaw browser set headers '{"x-test":"1"}'
openclaw browser set credentials myuser mypass
```
Cookie + penyimpanan:
```bash
openclaw browser cookies
openclaw browser cookies set session abc123 --url https://example.com
openclaw browser cookies clear
openclaw browser storage local get
openclaw browser storage local set token abc123
openclaw browser storage session clear
```
## Debugging
```bash
openclaw browser console --level error
openclaw browser pdf
openclaw browser responsebody "**/api"
openclaw browser highlight <ref>
openclaw browser errors --clear
openclaw browser requests --filter api
openclaw browser trace start
openclaw browser trace stop --out trace.zip
```
## Chrome yang ada melalui MCP
Gunakan profil bawaan `user`, atau buat profil `existing-session` Anda sendiri:
```bash
openclaw browser --browser-profile user tabs
openclaw browser create-profile --name chrome-live --driver existing-session
openclaw browser create-profile --name brave-live --driver existing-session --user-data-dir "~/Library/Application Support/BraveSoftware/Brave-Browser"
openclaw browser --browser-profile chrome-live tabs
```
Jalur ini hanya untuk host. Untuk Docker, server headless, Browserless, atau penyiapan jarak jauh lainnya, gunakan profil CDP.
Batas `existing-session` saat ini:
- aksi yang didorong snapshot menggunakan ref, bukan selektor CSS
- `click` hanya mendukung klik kiri
- `type` tidak mendukung `slowly=true`
- `press` tidak mendukung `delayMs`
- `hover`, `scrollintoview`, `drag`, `select`, `fill`, dan `evaluate` menolak
override timeout per panggilan
- `select` hanya mendukung satu nilai
- `wait --load networkidle` tidak didukung
- upload file memerlukan `--ref` / `--input-ref`, tidak mendukung CSS
`--element`, dan saat ini mendukung satu file sekali waktu
- hook dialog tidak mendukung `--timeout`
- tangkapan layar mendukung pengambilan halaman dan `--ref`, tetapi tidak CSS `--element`
- `responsebody`, intersepsi unduhan, ekspor PDF, dan aksi batch masih
memerlukan browser terkelola atau profil CDP mentah
## Kontrol browser jarak jauh (proxy host node)
Jika Gateway berjalan di mesin yang berbeda dari browser, jalankan **host node** di mesin yang memiliki Chrome/Brave/Edge/Chromium. Gateway akan mem-proxy aksi browser ke node tersebut (tidak memerlukan server kontrol browser terpisah).
Gunakan `gateway.nodes.browser.mode` untuk mengontrol auto-routing dan `gateway.nodes.browser.node` untuk menetapkan node tertentu jika beberapa node terhubung.
Keamanan + penyiapan jarak jauh: [Browser tool](/tools/browser), [Remote access](/gateway/remote), [Tailscale](/gateway/tailscale), [Security](/gateway/security)

138
docs/id/cli/channels.md Normal file
View File

@ -0,0 +1,138 @@
---
read_when:
- Anda ingin menambah/menghapus akun channel (WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (plugin)/Signal/iMessage/Matrix)
- Anda ingin memeriksa status channel atau mengikuti log channel
summary: Referensi CLI untuk `openclaw channels` (akun, status, login/logout, log)
title: channels
x-i18n:
generated_at: "2026-04-05T13:45:29Z"
model: gpt-5.4
provider: openai
source_hash: d0f558fdb5f6ec54e7fdb7a88e5c24c9d2567174341bd3ea87848bce4cba5d29
source_path: cli/channels.md
workflow: 15
---
# `openclaw channels`
Kelola akun chat channel dan status runtime-nya di Gateway.
Dokumentasi terkait:
- Panduan channel: [Channels](/channels/index)
- Konfigurasi Gateway: [Configuration](/gateway/configuration)
## Perintah umum
```bash
openclaw channels list
openclaw channels status
openclaw channels capabilities
openclaw channels capabilities --channel discord --target channel:123
openclaw channels resolve --channel slack "#general" "@jane"
openclaw channels logs --channel all
```
## Status / capabilities / resolve / log
- `channels status`: `--probe`, `--timeout <ms>`, `--json`
- `channels capabilities`: `--channel <name>`, `--account <id>` (hanya dengan `--channel`), `--target <dest>`, `--timeout <ms>`, `--json`
- `channels resolve`: `<entries...>`, `--channel <name>`, `--account <id>`, `--kind <auto|user|group>`, `--json`
- `channels logs`: `--channel <name|all>`, `--lines <n>`, `--json`
`channels status --probe` adalah jalur live: pada gateway yang dapat dijangkau, perintah ini menjalankan
pemeriksaan `probeAccount` per akun dan pemeriksaan `auditAccount` opsional, sehingga output dapat mencakup
status transport ditambah hasil probe seperti `works`, `probe failed`, `audit ok`, atau `audit failed`.
Jika gateway tidak dapat dijangkau, `channels status` akan fallback ke ringkasan berbasis konfigurasi
alih-alih output probe live.
## Menambah / menghapus akun
```bash
openclaw channels add --channel telegram --token <bot-token>
openclaw channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY"
openclaw channels remove --channel telegram --delete
```
Tips: `openclaw channels add --help` menampilkan flag per channel (token, private key, app token, path signal-cli, dll.).
Surface penambahan non-interaktif umum meliputi:
- channel berbasis bot token: `--token`, `--bot-token`, `--app-token`, `--token-file`
- field transport Signal/iMessage: `--signal-number`, `--cli-path`, `--http-url`, `--http-host`, `--http-port`, `--db-path`, `--service`, `--region`
- field Google Chat: `--webhook-path`, `--webhook-url`, `--audience-type`, `--audience`
- field Matrix: `--homeserver`, `--user-id`, `--access-token`, `--password`, `--device-name`, `--initial-sync-limit`
- field Nostr: `--private-key`, `--relay-urls`
- field Tlon: `--ship`, `--url`, `--code`, `--group-channels`, `--dm-allowlist`, `--auto-discover-channels`
- `--use-env` untuk autentikasi akun default berbasis env jika didukung
Saat Anda menjalankan `openclaw channels add` tanpa flag, wizard interaktif dapat meminta:
- ID akun per channel yang dipilih
- nama tampilan opsional untuk akun tersebut
- `Bind configured channel accounts to agents now?`
Jika Anda mengonfirmasi bind sekarang, wizard akan menanyakan agent mana yang harus memiliki setiap akun channel yang dikonfigurasi dan menulis binding routing dengan cakupan akun.
Anda juga dapat mengelola aturan routing yang sama nanti dengan `openclaw agents bindings`, `openclaw agents bind`, dan `openclaw agents unbind` (lihat [agents](/cli/agents)).
Saat Anda menambahkan akun non-default ke channel yang masih menggunakan pengaturan tingkat atas akun tunggal, OpenClaw mempromosikan nilai tingkat atas dengan cakupan akun ke dalam peta akun channel tersebut sebelum menulis akun baru. Sebagian besar channel menempatkan nilai tersebut di `channels.<channel>.accounts.default`, tetapi channel bawaan dapat mempertahankan akun hasil promosi yang cocok yang sudah ada. Matrix adalah contoh saat ini: jika satu akun bernama sudah ada, atau `defaultAccount` menunjuk ke akun bernama yang sudah ada, proses promosi mempertahankan akun tersebut alih-alih membuat `accounts.default` baru.
Perilaku routing tetap konsisten:
- Binding khusus channel yang sudah ada (tanpa `accountId`) tetap cocok dengan akun default.
- `channels add` tidak otomatis membuat atau menulis ulang binding dalam mode non-interaktif.
- Penyiapan interaktif dapat secara opsional menambahkan binding dengan cakupan akun.
Jika konfigurasi Anda sudah berada dalam status campuran (akun bernama ada dan nilai akun tunggal tingkat atas masih disetel), jalankan `openclaw doctor --fix` untuk memindahkan nilai dengan cakupan akun ke akun hasil promosi yang dipilih untuk channel itu. Sebagian besar channel dipromosikan ke `accounts.default`; Matrix dapat mempertahankan target bernama/default yang sudah ada.
## Login / logout (interaktif)
```bash
openclaw channels login --channel whatsapp
openclaw channels logout --channel whatsapp
```
Catatan:
- `channels login` mendukung `--verbose`.
- `channels login` / `logout` dapat menyimpulkan channel saat hanya satu target login yang didukung yang dikonfigurasi.
## Pemecahan masalah
- Jalankan `openclaw status --deep` untuk probe yang luas.
- Gunakan `openclaw doctor` untuk perbaikan terpandu.
- `openclaw channels list` mencetak `Claude: HTTP 403 ... user:profile` → snapshot penggunaan memerlukan scope `user:profile`. Gunakan `--no-usage`, atau sediakan kunci sesi claude.ai (`CLAUDE_WEB_SESSION_KEY` / `CLAUDE_WEB_COOKIE`), atau autentikasi ulang melalui Claude CLI.
- `openclaw channels status` akan fallback ke ringkasan berbasis konfigurasi saat gateway tidak dapat dijangkau. Jika kredensial channel yang didukung dikonfigurasi melalui SecretRef tetapi tidak tersedia dalam jalur perintah saat ini, perintah akan melaporkan akun tersebut sebagai configured dengan catatan degraded alih-alih menampilkannya sebagai tidak dikonfigurasi.
## Probe capabilities
Ambil petunjuk capability provider (intent/scope jika tersedia) ditambah dukungan fitur statis:
```bash
openclaw channels capabilities
openclaw channels capabilities --channel discord --target channel:123
```
Catatan:
- `--channel` bersifat opsional; hilangkan untuk mencantumkan setiap channel (termasuk ekstensi).
- `--account` hanya valid dengan `--channel`.
- `--target` menerima `channel:<id>` atau ID channel numerik mentah dan hanya berlaku untuk Discord.
- Probe bersifat spesifik provider: intent Discord + izin channel opsional; scope bot + pengguna Slack; flag bot Telegram + webhook; versi daemon Signal; token aplikasi Microsoft Teams + peran/scope Graph (diberi anotasi jika diketahui). Channel tanpa probe melaporkan `Probe: unavailable`.
## Resolve nama menjadi ID
Resolve nama channel/pengguna menjadi ID menggunakan direktori provider:
```bash
openclaw channels resolve --channel slack "#general" "@jane"
openclaw channels resolve --channel discord "My Server/#support" "@someone"
openclaw channels resolve --channel matrix "Project Room"
```
Catatan:
- Gunakan `--kind user|group|auto` untuk memaksa jenis target.
- Resolve lebih mengutamakan kecocokan aktif saat beberapa entri memiliki nama yang sama.
- `channels resolve` bersifat read-only. Jika akun yang dipilih dikonfigurasi melalui SecretRef tetapi kredensial tersebut tidak tersedia dalam jalur perintah saat ini, perintah mengembalikan hasil unresolved degraded dengan catatan alih-alih membatalkan seluruh proses.

28
docs/id/cli/clawbot.md Normal file
View File

@ -0,0 +1,28 @@
---
read_when:
- Anda memelihara skrip lama yang menggunakan `openclaw clawbot ...`
- Anda memerlukan panduan migrasi ke perintah saat ini
summary: Referensi CLI untuk `openclaw clawbot` (namespace alias lama)
title: clawbot
x-i18n:
generated_at: "2026-04-05T13:45:13Z"
model: gpt-5.4
provider: openai
source_hash: 1db82065ecb0107d1ab1a2c6ddaee9df1dd02b983ca1f759974c9d73f0ee3bde
source_path: cli/clawbot.md
workflow: 15
---
# `openclaw clawbot`
Namespace alias lama yang dipertahankan untuk kompatibilitas mundur.
Alias yang saat ini didukung:
- `openclaw clawbot qr` (perilaku sama dengan [`openclaw qr`](/cli/qr))
## Migrasi
Sebaiknya gunakan langsung perintah tingkat atas modern:
- `openclaw clawbot qr` -> `openclaw qr`

42
docs/id/cli/completion.md Normal file
View File

@ -0,0 +1,42 @@
---
read_when:
- Anda menginginkan completion shell untuk zsh/bash/fish/PowerShell
- Anda perlu menyimpan cache skrip completion di bawah state OpenClaw
summary: Referensi CLI untuk `openclaw completion` (menghasilkan/menginstal skrip completion shell)
title: completion
x-i18n:
generated_at: "2026-04-05T13:45:16Z"
model: gpt-5.4
provider: openai
source_hash: 7bbf140a880bafdb7140149f85465d66d0d46e5a3da6a1e41fb78be2fd2bd4d0
source_path: cli/completion.md
workflow: 15
---
# `openclaw completion`
Hasilkan skrip completion shell dan secara opsional instal ke profil shell Anda.
## Penggunaan
```bash
openclaw completion
openclaw completion --shell zsh
openclaw completion --install
openclaw completion --shell fish --install
openclaw completion --write-state
openclaw completion --shell bash --write-state
```
## Opsi
- `-s, --shell <shell>`: target shell (`zsh`, `bash`, `powershell`, `fish`; default: `zsh`)
- `-i, --install`: instal completion dengan menambahkan baris source ke profil shell Anda
- `--write-state`: tulis skrip completion ke `$OPENCLAW_STATE_DIR/completions` tanpa mencetak ke stdout
- `-y, --yes`: lewati prompt konfirmasi instalasi
## Catatan
- `--install` menulis blok kecil "OpenClaw Completion" ke profil shell Anda dan mengarahkannya ke skrip yang di-cache.
- Tanpa `--install` atau `--write-state`, perintah akan mencetak skrip ke stdout.
- Pembuatan completion memuat tree perintah secara eager sehingga subperintah bertingkat ikut disertakan.

360
docs/id/cli/config.md Normal file
View File

@ -0,0 +1,360 @@
---
read_when:
- Anda ingin membaca atau mengedit konfigurasi secara non-interaktif
summary: Referensi CLI untuk `openclaw config` (get/set/unset/file/schema/validate)
title: config
x-i18n:
generated_at: "2026-04-05T13:45:44Z"
model: gpt-5.4
provider: openai
source_hash: e4de30f41e15297019151ad1a5b306cb331fd5c2beefd5ce5b98fcc51e95f0de
source_path: cli/config.md
workflow: 15
---
# `openclaw config`
Helper konfigurasi untuk pengeditan non-interaktif di `openclaw.json`: get/set/unset/file/schema/validate
nilai berdasarkan path dan mencetak file konfigurasi aktif. Jalankan tanpa subperintah untuk
membuka wizard konfigurasi (sama seperti `openclaw configure`).
Opsi root:
- `--section <section>`: filter bagian penyiapan terpandu yang dapat diulang saat Anda menjalankan `openclaw config` tanpa subperintah
Bagian terpandu yang didukung:
- `workspace`
- `model`
- `web`
- `gateway`
- `daemon`
- `channels`
- `plugins`
- `skills`
- `health`
## Contoh
```bash
openclaw config file
openclaw config --section model
openclaw config --section gateway --section daemon
openclaw config schema
openclaw config get browser.executablePath
openclaw config set browser.executablePath "/usr/bin/google-chrome"
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN
openclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/openclaw/secrets.json --provider-mode json
openclaw config unset plugins.entries.brave.config.webSearch.apiKey
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run
openclaw config validate
openclaw config validate --json
```
### `config schema`
Cetak JSON schema yang dihasilkan untuk `openclaw.json` ke stdout sebagai JSON.
Yang disertakan:
- Root schema konfigurasi saat ini, plus field string root `$schema` untuk tooling editor
- Metadata dokumen `title` dan `description` field yang digunakan oleh UI Control
- Node objek bertingkat, wildcard (`*`), dan item array (`[]`) mewarisi metadata `title` / `description` yang sama saat dokumentasi field yang cocok ada
- Cabang `anyOf` / `oneOf` / `allOf` juga mewarisi metadata dokumen yang sama saat dokumentasi field yang cocok ada
- Metadata schema plugin + channel live secara best-effort saat manifest runtime dapat dimuat
- Schema fallback yang bersih bahkan saat konfigurasi saat ini tidak valid
Runtime RPC terkait:
- `config.schema.lookup` mengembalikan satu path konfigurasi yang dinormalisasi dengan node
schema dangkal (`title`, `description`, `type`, `enum`, `const`, batas umum),
metadata petunjuk UI yang cocok, dan ringkasan anak langsung. Gunakan ini untuk
penelusuran berbasis path di UI Control atau klien kustom.
```bash
openclaw config schema
```
Pipe ke file saat Anda ingin memeriksa atau memvalidasinya dengan tool lain:
```bash
openclaw config schema > openclaw.schema.json
```
### Path
Path menggunakan notasi titik atau kurung:
```bash
openclaw config get agents.defaults.workspace
openclaw config get agents.list[0].id
```
Gunakan indeks daftar agen untuk menargetkan agen tertentu:
```bash
openclaw config get agents.list
openclaw config set agents.list[1].tools.exec.node "node-id-or-name"
```
## Nilai
Nilai diparse sebagai JSON5 jika memungkinkan; jika tidak, nilainya diperlakukan sebagai string.
Gunakan `--strict-json` untuk mewajibkan parsing JSON5. `--json` tetap didukung sebagai alias lama.
```bash
openclaw config set agents.defaults.heartbeat.every "0m"
openclaw config set gateway.port 19001 --strict-json
openclaw config set channels.whatsapp.groups '["*"]' --strict-json
```
`config get <path> --json` mencetak nilai mentah sebagai JSON alih-alih teks berformat terminal.
## Mode `config set`
`openclaw config set` mendukung empat gaya penetapan:
1. Mode nilai: `openclaw config set <path> <value>`
2. Mode pembuat SecretRef:
```bash
openclaw config set channels.discord.token \
--ref-provider default \
--ref-source env \
--ref-id DISCORD_BOT_TOKEN
```
3. Mode pembuat provider (khusus path `secrets.providers.<alias>`):
```bash
openclaw config set secrets.providers.vault \
--provider-source exec \
--provider-command /usr/local/bin/openclaw-vault \
--provider-arg read \
--provider-arg openai/api-key \
--provider-timeout-ms 5000
```
4. Mode batch (`--batch-json` atau `--batch-file`):
```bash
openclaw config set --batch-json '[
{
"path": "secrets.providers.default",
"provider": { "source": "env" }
},
{
"path": "channels.discord.token",
"ref": { "source": "env", "provider": "default", "id": "DISCORD_BOT_TOKEN" }
}
]'
```
```bash
openclaw config set --batch-file ./config-set.batch.json --dry-run
```
Catatan kebijakan:
- Penetapan SecretRef ditolak pada surface yang tidak mendukung mutasi runtime (misalnya `hooks.token`, `commands.ownerDisplaySecret`, token webhook thread-binding Discord, dan JSON kredensial WhatsApp). Lihat [SecretRef Credential Surface](/reference/secretref-credential-surface).
Parsing batch selalu menggunakan payload batch (`--batch-json`/`--batch-file`) sebagai sumber kebenaran.
`--strict-json` / `--json` tidak mengubah perilaku parsing batch.
Mode path/nilai JSON tetap didukung untuk SecretRefs maupun provider:
```bash
openclaw config set channels.discord.token \
'{"source":"env","provider":"default","id":"DISCORD_BOT_TOKEN"}' \
--strict-json
openclaw config set secrets.providers.vaultfile \
'{"source":"file","path":"/etc/openclaw/secrets.json","mode":"json"}' \
--strict-json
```
## Flag Pembuat Provider
Target pembuat provider harus menggunakan `secrets.providers.<alias>` sebagai path.
Flag umum:
- `--provider-source <env|file|exec>`
- `--provider-timeout-ms <ms>` (`file`, `exec`)
Provider env (`--provider-source env`):
- `--provider-allowlist <ENV_VAR>` (dapat diulang)
Provider file (`--provider-source file`):
- `--provider-path <path>` (wajib)
- `--provider-mode <singleValue|json>`
- `--provider-max-bytes <bytes>`
Provider exec (`--provider-source exec`):
- `--provider-command <path>` (wajib)
- `--provider-arg <arg>` (dapat diulang)
- `--provider-no-output-timeout-ms <ms>`
- `--provider-max-output-bytes <bytes>`
- `--provider-json-only`
- `--provider-env <KEY=VALUE>` (dapat diulang)
- `--provider-pass-env <ENV_VAR>` (dapat diulang)
- `--provider-trusted-dir <path>` (dapat diulang)
- `--provider-allow-insecure-path`
- `--provider-allow-symlink-command`
Contoh provider exec yang diperkeras:
```bash
openclaw config set secrets.providers.vault \
--provider-source exec \
--provider-command /usr/local/bin/openclaw-vault \
--provider-arg read \
--provider-arg openai/api-key \
--provider-json-only \
--provider-pass-env VAULT_TOKEN \
--provider-trusted-dir /usr/local/bin \
--provider-timeout-ms 5000
```
## Dry run
Gunakan `--dry-run` untuk memvalidasi perubahan tanpa menulis ke `openclaw.json`.
```bash
openclaw config set channels.discord.token \
--ref-provider default \
--ref-source env \
--ref-id DISCORD_BOT_TOKEN \
--dry-run
openclaw config set channels.discord.token \
--ref-provider default \
--ref-source env \
--ref-id DISCORD_BOT_TOKEN \
--dry-run \
--json
openclaw config set channels.discord.token \
--ref-provider vault \
--ref-source exec \
--ref-id discord/token \
--dry-run \
--allow-exec
```
Perilaku dry-run:
- Mode builder: menjalankan pemeriksaan resolvabilitas SecretRef untuk ref/provider yang berubah.
- Mode JSON (`--strict-json`, `--json`, atau mode batch): menjalankan validasi schema plus pemeriksaan resolvabilitas SecretRef.
- Validasi kebijakan juga dijalankan untuk surface target SecretRef yang diketahui tidak didukung.
- Pemeriksaan kebijakan mengevaluasi keseluruhan konfigurasi pasca-perubahan, sehingga penulisan objek induk (misalnya mengatur `hooks` sebagai objek) tidak dapat melewati validasi surface yang tidak didukung.
- Pemeriksaan SecretRef exec dilewati secara default selama dry-run untuk menghindari efek samping perintah.
- Gunakan `--allow-exec` bersama `--dry-run` untuk ikut serta dalam pemeriksaan SecretRef exec (ini dapat mengeksekusi perintah provider).
- `--allow-exec` hanya untuk dry-run dan menghasilkan error jika digunakan tanpa `--dry-run`.
`--dry-run --json` mencetak laporan yang dapat dibaca mesin:
- `ok`: apakah dry-run lulus
- `operations`: jumlah penetapan yang dievaluasi
- `checks`: apakah pemeriksaan schema/resolvabilitas dijalankan
- `checks.resolvabilityComplete`: apakah pemeriksaan resolvabilitas berjalan hingga selesai (false saat ref exec dilewati)
- `refsChecked`: jumlah ref yang benar-benar di-resolve selama dry-run
- `skippedExecRefs`: jumlah ref exec yang dilewati karena `--allow-exec` tidak diatur
- `errors`: kegagalan schema/resolvabilitas terstruktur saat `ok=false`
### Bentuk Output JSON
```json5
{
ok: boolean,
operations: number,
configPath: string,
inputModes: ["value" | "json" | "builder", ...],
checks: {
schema: boolean,
resolvability: boolean,
resolvabilityComplete: boolean,
},
refsChecked: number,
skippedExecRefs: number,
errors?: [
{
kind: "schema" | "resolvability",
message: string,
ref?: string, // ada untuk error resolvabilitas
},
],
}
```
Contoh sukses:
```json
{
"ok": true,
"operations": 1,
"configPath": "~/.openclaw/openclaw.json",
"inputModes": ["builder"],
"checks": {
"schema": false,
"resolvability": true,
"resolvabilityComplete": true
},
"refsChecked": 1,
"skippedExecRefs": 0
}
```
Contoh gagal:
```json
{
"ok": false,
"operations": 1,
"configPath": "~/.openclaw/openclaw.json",
"inputModes": ["builder"],
"checks": {
"schema": false,
"resolvability": true,
"resolvabilityComplete": true
},
"refsChecked": 1,
"skippedExecRefs": 0,
"errors": [
{
"kind": "resolvability",
"message": "Error: Environment variable \"MISSING_TEST_SECRET\" is not set.",
"ref": "env:default:MISSING_TEST_SECRET"
}
]
}
```
Jika dry-run gagal:
- `config schema validation failed`: bentuk konfigurasi pasca-perubahan Anda tidak valid; perbaiki path/nilai atau bentuk objek provider/ref.
- `Config policy validation failed: unsupported SecretRef usage`: pindahkan kredensial itu kembali ke input plaintext/string dan pertahankan SecretRef hanya pada surface yang didukung.
- `SecretRef assignment(s) could not be resolved`: provider/ref yang dirujuk saat ini tidak dapat di-resolve (variabel env hilang, pointer file tidak valid, kegagalan provider exec, atau ketidakcocokan provider/source).
- `Dry run note: skipped <n> exec SecretRef resolvability check(s)`: dry-run melewati ref exec; jalankan lagi dengan `--allow-exec` jika Anda memerlukan validasi resolvabilitas exec.
- Untuk mode batch, perbaiki entri yang gagal lalu jalankan ulang `--dry-run` sebelum menulis.
## Subperintah
- `config file`: Cetak path file konfigurasi aktif (di-resolve dari `OPENCLAW_CONFIG_PATH` atau lokasi default).
Mulai ulang gateway setelah pengeditan.
## Validasi
Validasi konfigurasi saat ini terhadap schema aktif tanpa memulai
gateway.
```bash
openclaw config validate
openclaw config validate --json
```

75
docs/id/cli/configure.md Normal file
View File

@ -0,0 +1,75 @@
---
read_when:
- Anda ingin menyesuaikan kredensial, perangkat, atau default agen secara interaktif
summary: Referensi CLI untuk `openclaw configure` (prompt konfigurasi interaktif)
title: configure
x-i18n:
generated_at: "2026-04-05T13:45:24Z"
model: gpt-5.4
provider: openai
source_hash: 989569fdb8e1b31ce3438756b3ed9bf18e0c8baf611c5981643ba5925459c98f
source_path: cli/configure.md
workflow: 15
---
# `openclaw configure`
Prompt interaktif untuk menyiapkan kredensial, perangkat, dan default agen.
Catatan: Bagian **Model** sekarang menyertakan multi-select untuk allowlist
`agents.defaults.models` (apa yang muncul di `/model` dan pemilih model).
Saat configure dimulai dari pilihan auth provider, pemilih model default dan
allowlist otomatis mengutamakan provider tersebut. Untuk provider berpasangan seperti
Volcengine/BytePlus, preferensi yang sama juga cocok dengan varian coding-plan
mereka (`volcengine-plan/*`, `byteplus-plan/*`). Jika filter preferred-provider
akan menghasilkan daftar kosong, configure akan kembali ke katalog tanpa filter alih-alih menampilkan pemilih kosong.
Tip: `openclaw config` tanpa subperintah membuka wizard yang sama. Gunakan
`openclaw config get|set|unset` untuk pengeditan non-interaktif.
Untuk pencarian web, `openclaw configure --section web` memungkinkan Anda memilih provider
dan mengonfigurasi kredensialnya. Beberapa provider juga menampilkan prompt tindak lanjut khusus provider:
- **Grok** dapat menawarkan penyiapan `x_search` opsional dengan `XAI_API_KEY` yang sama dan
memungkinkan Anda memilih model `x_search`.
- **Kimi** dapat menanyakan region API Moonshot (`api.moonshot.ai` vs
`api.moonshot.cn`) dan model pencarian web Kimi default.
Terkait:
- Referensi konfigurasi gateway: [Konfigurasi](/gateway/configuration)
- CLI config: [Config](/cli/config)
## Opsi
- `--section <section>`: filter section yang dapat diulang
Section yang tersedia:
- `workspace`
- `model`
- `web`
- `gateway`
- `daemon`
- `channels`
- `plugins`
- `skills`
- `health`
Catatan:
- Memilih tempat Gateway berjalan selalu memperbarui `gateway.mode`. Anda dapat memilih "Continue" tanpa section lain jika hanya itu yang Anda perlukan.
- Layanan yang berorientasi channel (Slack/Discord/Matrix/Microsoft Teams) meminta allowlist channel/room selama penyiapan. Anda dapat memasukkan nama atau ID; wizard meresolusikan nama menjadi ID jika memungkinkan.
- Jika Anda menjalankan langkah instalasi daemon, auth token memerlukan token, dan `gateway.auth.token` dikelola oleh SecretRef, configure memvalidasi SecretRef tetapi tidak menyimpan nilai token plaintext yang telah diresolusikan ke metadata environment layanan supervisor.
- Jika auth token memerlukan token dan SecretRef token yang dikonfigurasi tidak teresolusikan, configure memblokir instalasi daemon dengan panduan perbaikan yang dapat ditindaklanjuti.
- Jika `gateway.auth.token` dan `gateway.auth.password` sama-sama dikonfigurasi dan `gateway.auth.mode` tidak ditetapkan, configure memblokir instalasi daemon sampai mode ditetapkan secara eksplisit.
## Contoh
```bash
openclaw configure
openclaw configure --section web
openclaw configure --section model --section channels
openclaw configure --section gateway --section daemon
```

174
docs/id/cli/cron.md Normal file
View File

@ -0,0 +1,174 @@
---
read_when:
- Anda menginginkan pekerjaan dan wakeup terjadwal
- Anda sedang men-debug eksekusi dan log cron
summary: Referensi CLI untuk `openclaw cron` (menjadwalkan dan menjalankan pekerjaan latar belakang)
title: cron
x-i18n:
generated_at: "2026-04-05T13:45:35Z"
model: gpt-5.4
provider: openai
source_hash: f74ec8847835f24b3970f1b260feeb69c7ab6c6ec7e41615cbb73f37f14a8112
source_path: cli/cron.md
workflow: 15
---
# `openclaw cron`
Kelola pekerjaan cron untuk scheduler Gateway.
Terkait:
- Pekerjaan cron: [Pekerjaan cron](/automation/cron-jobs)
Tip: jalankan `openclaw cron --help` untuk permukaan perintah lengkap.
Catatan: pekerjaan `cron add` terisolasi secara default menggunakan pengiriman `--announce`. Gunakan `--no-deliver` agar
output tetap internal. `--deliver` tetap tersedia sebagai alias usang untuk `--announce`.
Catatan: eksekusi terisolasi yang dimiliki cron mengharapkan ringkasan teks biasa dan runner memiliki
jalur pengiriman akhir. `--no-deliver` menjaga eksekusi tetap internal; ini tidak
mengembalikan pengiriman ke message tool milik agen.
Catatan: pekerjaan sekali jalan (`--at`) dihapus setelah berhasil secara default. Gunakan `--keep-after-run` untuk menyimpannya.
Catatan: `--session` mendukung `main`, `isolated`, `current`, dan `session:<id>`.
Gunakan `current` untuk mengikat ke sesi aktif pada saat pembuatan, atau `session:<id>` untuk
session key persisten yang eksplisit.
Catatan: untuk pekerjaan CLI sekali jalan, datetime `--at` tanpa offset diperlakukan sebagai UTC kecuali Anda juga meneruskan
`--tz <iana>`, yang akan menafsirkan waktu lokal wall-clock tersebut dalam timezone yang diberikan.
Catatan: pekerjaan rekuren sekarang menggunakan retry backoff eksponensial setelah error berturut-turut (30d → 1m → 5m → 15m → 60m), lalu kembali ke jadwal normal setelah eksekusi berhasil berikutnya.
Catatan: `openclaw cron run` sekarang kembali segera setelah eksekusi manual dimasukkan ke antrean untuk dijalankan. Respons yang berhasil mencakup `{ ok: true, enqueued: true, runId }`; gunakan `openclaw cron runs --id <job-id>` untuk mengikuti hasil akhirnya.
Catatan: `openclaw cron run <job-id>` secara default memaksa eksekusi. Gunakan `--due` untuk mempertahankan
perilaku lama "hanya jalankan jika sudah jatuh tempo".
Catatan: giliran cron terisolasi menekan balasan usang yang hanya berupa tanda terima. Jika
hasil pertama hanya berupa pembaruan status sementara dan tidak ada eksekusi subagen turunan yang
bertanggung jawab atas jawaban akhirnya, cron akan meminta ulang sekali untuk hasil sebenarnya
sebelum pengiriman.
Catatan: jika eksekusi cron terisolasi hanya mengembalikan token senyap (`NO_REPLY` /
`no_reply`), cron menekan pengiriman keluar langsung dan juga jalur fallback
ringkasan antrean, sehingga tidak ada yang dikirim kembali ke chat.
Catatan: `cron add|edit --model ...` menggunakan model yang dipilih dan diizinkan untuk pekerjaan tersebut.
Jika model tidak diizinkan, cron memberi peringatan dan kembali ke pemilihan model agen/default
pekerjaan tersebut. Rantai fallback yang dikonfigurasi tetap berlaku, tetapi override model biasa
tanpa daftar fallback per pekerjaan yang eksplisit tidak lagi menambahkan model utama agen
sebagai target retry tambahan yang tersembunyi.
Catatan: prioritas model cron terisolasi adalah override hook Gmail terlebih dahulu, lalu `--model`
per pekerjaan, lalu override model cron-session tersimpan, lalu pemilihan
agen/default normal.
Catatan: mode cepat cron terisolasi mengikuti pemilihan model live yang sudah diselesaikan. Konfigurasi model
`params.fastMode` berlaku secara default, tetapi override `fastMode` sesi yang tersimpan
tetap lebih diutamakan daripada config.
Catatan: jika eksekusi terisolasi melempar `LiveSessionModelSwitchError`, cron menyimpan
penyedia/model yang dialihkan (dan override profil auth yang dialihkan jika ada) sebelum
mencoba ulang. Loop retry luar dibatasi hingga 2 retry perpindahan setelah percobaan
awal, lalu dibatalkan alih-alih berulang tanpa akhir.
Catatan: notifikasi kegagalan menggunakan `delivery.failureDestination` terlebih dahulu, lalu
`cron.failureDestination` global, dan terakhir fallback ke target
announce utama pekerjaan saat tidak ada tujuan kegagalan eksplisit yang dikonfigurasi.
Catatan: retensi/pemangkasan dikendalikan di config:
- `cron.sessionRetention` (default `24h`) memangkas sesi eksekusi terisolasi yang sudah selesai.
- `cron.runLog.maxBytes` + `cron.runLog.keepLines` memangkas `~/.openclaw/cron/runs/<jobId>.jsonl`.
Catatan upgrade: jika Anda memiliki pekerjaan cron lama dari sebelum format delivery/store saat ini, jalankan
`openclaw doctor --fix`. Doctor sekarang menormalkan field cron lama (`jobId`, `schedule.cron`,
field delivery level atas termasuk `threadId` lama, alias delivery `provider` pada payload) dan memigrasikan pekerjaan fallback webhook sederhana
`notify: true` ke delivery webhook eksplisit saat `cron.webhook` telah
dikonfigurasi.
## Edit umum
Perbarui pengaturan delivery tanpa mengubah pesan:
```bash
openclaw cron edit <job-id> --announce --channel telegram --to "123456789"
```
Nonaktifkan delivery untuk pekerjaan terisolasi:
```bash
openclaw cron edit <job-id> --no-deliver
```
Aktifkan konteks bootstrap ringan untuk pekerjaan terisolasi:
```bash
openclaw cron edit <job-id> --light-context
```
Umumkan ke channel tertentu:
```bash
openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
```
Buat pekerjaan terisolasi dengan konteks bootstrap ringan:
```bash
openclaw cron add \
--name "Lightweight morning brief" \
--cron "0 7 * * *" \
--session isolated \
--message "Summarize overnight updates." \
--light-context \
--no-deliver
```
`--light-context` hanya berlaku untuk pekerjaan giliran agen terisolasi. Untuk eksekusi cron, mode ringan menjaga konteks bootstrap tetap kosong alih-alih menyuntikkan set bootstrap workspace lengkap.
Catatan kepemilikan delivery:
- Pekerjaan terisolasi yang dimiliki cron selalu merutekan delivery akhir yang terlihat pengguna melalui
runner cron (`announce`, `webhook`, atau hanya internal `none`).
- Jika tugas menyebut pengiriman pesan ke penerima eksternal tertentu, agen harus
menjelaskan tujuan yang dimaksud dalam hasilnya alih-alih mencoba mengirimnya
langsung.
## Perintah admin umum
Eksekusi manual:
```bash
openclaw cron run <job-id>
openclaw cron run <job-id> --due
openclaw cron runs --id <job-id> --limit 50
```
Pengalihan agen/sesi:
```bash
openclaw cron edit <job-id> --agent ops
openclaw cron edit <job-id> --clear-agent
openclaw cron edit <job-id> --session current
openclaw cron edit <job-id> --session "session:daily-brief"
```
Penyesuaian delivery:
```bash
openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
openclaw cron edit <job-id> --best-effort-deliver
openclaw cron edit <job-id> --no-best-effort-deliver
openclaw cron edit <job-id> --no-deliver
```
Catatan delivery kegagalan:
- `delivery.failureDestination` didukung untuk pekerjaan terisolasi.
- Pekerjaan sesi utama hanya dapat menggunakan `delivery.failureDestination` saat mode
delivery utama adalah `webhook`.
- Jika Anda tidak menetapkan tujuan kegagalan apa pun dan pekerjaan sudah mengumumkan ke
channel, notifikasi kegagalan akan menggunakan kembali target announce yang sama.

64
docs/id/cli/daemon.md Normal file
View File

@ -0,0 +1,64 @@
---
read_when:
- Anda masih menggunakan `openclaw daemon ...` dalam skrip
- Anda memerlukan perintah siklus hidup layanan (install/start/stop/restart/status)
summary: Referensi CLI untuk `openclaw daemon` (alias legacy untuk pengelolaan layanan gateway)
title: daemon
x-i18n:
generated_at: "2026-04-05T13:45:27Z"
model: gpt-5.4
provider: openai
source_hash: 91fdaf3c4f3e7dd4dff86f9b74a653dcba2674573698cf51efc4890077994169
source_path: cli/daemon.md
workflow: 15
---
# `openclaw daemon`
Alias legacy untuk perintah pengelolaan layanan Gateway.
`openclaw daemon ...` dipetakan ke surface kontrol layanan yang sama seperti perintah layanan `openclaw gateway ...`.
## Penggunaan
```bash
openclaw daemon status
openclaw daemon install
openclaw daemon start
openclaw daemon stop
openclaw daemon restart
openclaw daemon uninstall
```
## Subperintah
- `status`: tampilkan status instalasi layanan dan probe kesehatan Gateway
- `install`: instal layanan (`launchd`/`systemd`/`schtasks`)
- `uninstall`: hapus layanan
- `start`: mulai layanan
- `stop`: hentikan layanan
- `restart`: mulai ulang layanan
## Opsi umum
- `status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json`
- `install`: `--port`, `--runtime <node|bun>`, `--token`, `--force`, `--json`
- siklus hidup (`uninstall|start|stop|restart`): `--json`
Catatan:
- `status` me-resolve SecretRef autentikasi yang dikonfigurasi untuk autentikasi probe bila memungkinkan.
- Jika SecretRef autentikasi yang diperlukan tidak dapat di-resolve dalam jalur perintah ini, `daemon status --json` melaporkan `rpc.authWarning` saat konektivitas/autentikasi probe gagal; berikan `--token`/`--password` secara eksplisit atau resolve sumber secret terlebih dahulu.
- Jika probe berhasil, peringatan auth-ref yang tidak ter-resolve ditekan untuk menghindari positif palsu.
- `status --deep` menambahkan pemindaian layanan tingkat sistem dengan upaya terbaik. Saat menemukan layanan lain yang mirip gateway, output untuk manusia akan mencetak petunjuk pembersihan dan memperingatkan bahwa satu gateway per mesin tetap merupakan rekomendasi normal.
- Pada instalasi Linux systemd, pemeriksaan token drift `status` mencakup sumber unit `Environment=` dan `EnvironmentFile=`.
- Pemeriksaan drift me-resolve SecretRef `gateway.auth.token` menggunakan env runtime gabungan (env perintah layanan terlebih dahulu, lalu fallback env proses).
- Jika autentikasi token tidak aktif secara efektif (mode `gateway.auth.mode` eksplisit `password`/`none`/`trusted-proxy`, atau mode tidak diatur sehingga password dapat menang dan tidak ada kandidat token yang dapat menang), pemeriksaan token drift melewati resolusi token config.
- Saat autentikasi token memerlukan token dan `gateway.auth.token` dikelola SecretRef, `install` memvalidasi bahwa SecretRef dapat di-resolve tetapi tidak menyimpan token yang telah di-resolve ke metadata env layanan.
- Jika autentikasi token memerlukan token dan SecretRef token yang dikonfigurasi tidak dapat di-resolve, instalasi gagal secara tertutup.
- Jika `gateway.auth.token` dan `gateway.auth.password` keduanya dikonfigurasi dan `gateway.auth.mode` tidak diatur, instalasi diblokir sampai mode diatur secara eksplisit.
- Jika Anda sengaja menjalankan beberapa gateway pada satu host, isolasikan port, config/status, dan workspace; lihat [/gateway#multiple-gateways-same-host](/gateway#multiple-gateways-same-host).
## Disarankan
Gunakan [`openclaw gateway`](/cli/gateway) untuk dokumentasi dan contoh terbaru.

29
docs/id/cli/dashboard.md Normal file
View File

@ -0,0 +1,29 @@
---
read_when:
- Anda ingin membuka UI Control dengan token saat ini
- Anda ingin mencetak URL tanpa meluncurkan browser
summary: Referensi CLI untuk `openclaw dashboard` (membuka UI Control)
title: dashboard
x-i18n:
generated_at: "2026-04-05T13:45:28Z"
model: gpt-5.4
provider: openai
source_hash: a34cd109a3803e2910fcb4d32f2588aa205a4933819829ef5598f0780f586c94
source_path: cli/dashboard.md
workflow: 15
---
# `openclaw dashboard`
Buka UI Control menggunakan auth Anda saat ini.
```bash
openclaw dashboard
openclaw dashboard --no-open
```
Catatan:
- `dashboard` meresolusikan SecretRef `gateway.auth.token` yang dikonfigurasi bila memungkinkan.
- Untuk token yang dikelola SecretRef (teresolusikan atau tidak teresolusikan), `dashboard` mencetak/menyalin/membuka URL tanpa token untuk menghindari tereksposnya secret eksternal dalam output terminal, riwayat clipboard, atau argumen peluncuran browser.
- Jika `gateway.auth.token` dikelola SecretRef tetapi tidak teresolusikan dalam jalur perintah ini, perintah mencetak URL tanpa token dan panduan perbaikan yang eksplisit alih-alih menyematkan placeholder token yang tidak valid.

178
docs/id/cli/devices.md Normal file
View File

@ -0,0 +1,178 @@
---
read_when:
- Anda sedang menyetujui permintaan pairing perangkat
- Anda perlu merotasi atau mencabut token perangkat
summary: Referensi CLI untuk `openclaw devices` (pairing perangkat + rotasi/pencabutan token)
title: devices
x-i18n:
generated_at: "2026-04-05T13:45:45Z"
model: gpt-5.4
provider: openai
source_hash: e2f9fcb8e3508a703590f87caaafd953a5d3557e11c958cbb2be1d67bb8720f4
source_path: cli/devices.md
workflow: 15
---
# `openclaw devices`
Kelola permintaan pairing perangkat dan token yang dibatasi untuk perangkat.
## Perintah
### `openclaw devices list`
Tampilkan daftar permintaan pairing yang tertunda dan perangkat yang sudah dipasangkan.
```
openclaw devices list
openclaw devices list --json
```
Output permintaan tertunda mencakup role dan scope yang diminta sehingga persetujuan
dapat ditinjau sebelum Anda menyetujuinya.
### `openclaw devices remove <deviceId>`
Hapus satu entri perangkat yang sudah dipasangkan.
Saat Anda diautentikasi dengan token perangkat yang sudah dipasangkan, pemanggil non-admin hanya dapat
menghapus entri perangkat **milik mereka sendiri**. Menghapus perangkat lain memerlukan
`operator.admin`.
```
openclaw devices remove <deviceId>
openclaw devices remove <deviceId> --json
```
### `openclaw devices clear --yes [--pending]`
Hapus perangkat yang sudah dipasangkan secara massal.
```
openclaw devices clear --yes
openclaw devices clear --yes --pending
openclaw devices clear --yes --pending --json
```
### `openclaw devices approve [requestId] [--latest]`
Setujui permintaan pairing perangkat yang tertunda. Jika `requestId` dihilangkan, OpenClaw
secara otomatis menyetujui permintaan tertunda yang paling baru.
Catatan: jika sebuah perangkat mencoba pairing ulang dengan detail autentikasi yang berubah (role/scope/public
key), OpenClaw menggantikan entri tertunda sebelumnya dan menerbitkan
`requestId` baru. Jalankan `openclaw devices list` tepat sebelum persetujuan untuk menggunakan
ID saat ini.
```
openclaw devices approve
openclaw devices approve <requestId>
openclaw devices approve --latest
```
### `openclaw devices reject <requestId>`
Tolak permintaan pairing perangkat yang tertunda.
```
openclaw devices reject <requestId>
```
### `openclaw devices rotate --device <id> --role <role> [--scope <scope...>]`
Rotasikan token perangkat untuk role tertentu (opsional sambil memperbarui scope).
Role target harus sudah ada dalam kontrak pairing yang disetujui untuk perangkat tersebut;
rotasi tidak dapat menerbitkan role baru yang belum disetujui.
Jika Anda menghilangkan `--scope`, koneksi ulang berikutnya dengan token hasil rotasi yang tersimpan akan menggunakan kembali
scope yang disetujui dan di-cache dari token tersebut. Jika Anda memberikan nilai `--scope` secara eksplisit, nilai tersebut
menjadi kumpulan scope tersimpan untuk koneksi ulang token-cache di masa mendatang.
Pemanggil perangkat berpasangan non-admin hanya dapat merotasi token perangkat **milik mereka sendiri**.
Selain itu, setiap nilai `--scope` eksplisit harus tetap berada dalam scope operator milik sesi pemanggil sendiri;
rotasi tidak dapat menerbitkan token operator yang lebih luas daripada yang
sudah dimiliki pemanggil.
```
openclaw devices rotate --device <deviceId> --role operator --scope operator.read --scope operator.write
```
Mengembalikan payload token baru sebagai JSON.
### `openclaw devices revoke --device <id> --role <role>`
Cabut token perangkat untuk role tertentu.
Pemanggil perangkat berpasangan non-admin hanya dapat mencabut token perangkat **milik mereka sendiri**.
Mencabut token perangkat lain memerlukan `operator.admin`.
```
openclaw devices revoke --device <deviceId> --role node
```
Mengembalikan hasil pencabutan sebagai JSON.
## Opsi umum
- `--url <url>`: URL WebSocket Gateway (default ke `gateway.remote.url` jika dikonfigurasi).
- `--token <token>`: token Gateway (jika diperlukan).
- `--password <password>`: kata sandi Gateway (autentikasi kata sandi).
- `--timeout <ms>`: timeout RPC.
- `--json`: output JSON (disarankan untuk scripting).
Catatan: saat Anda menetapkan `--url`, CLI tidak melakukan fallback ke kredensial config atau environment.
Berikan `--token` atau `--password` secara eksplisit. Kredensial eksplisit yang tidak ada adalah error.
## Catatan
- Rotasi token mengembalikan token baru (sensitif). Perlakukan seperti rahasia.
- Perintah ini memerlukan scope `operator.pairing` (atau `operator.admin`).
- Rotasi token tetap berada dalam kumpulan role pairing yang disetujui dan baseline scope yang disetujui
untuk perangkat tersebut. Entri token cache yang menyimpang tidak memberikan target
rotasi baru.
- Untuk sesi token perangkat berpasangan, pengelolaan lintas perangkat hanya untuk admin:
`remove`, `rotate`, dan `revoke` hanya berlaku untuk diri sendiri kecuali pemanggil memiliki
`operator.admin`.
- `devices clear` sengaja dibatasi oleh `--yes`.
- Jika scope pairing tidak tersedia di local loopback (dan tidak ada `--url` eksplisit yang diberikan), list/approve dapat menggunakan fallback pairing lokal.
- `devices approve` secara otomatis memilih permintaan tertunda terbaru saat Anda menghilangkan `requestId` atau memberikan `--latest`.
## Checklist pemulihan drift token
Gunakan ini saat Control UI atau klien lain terus gagal dengan `AUTH_TOKEN_MISMATCH` atau `AUTH_DEVICE_TOKEN_MISMATCH`.
1. Konfirmasikan sumber token gateway saat ini:
```bash
openclaw config get gateway.auth.token
```
2. Tampilkan perangkat yang sudah dipasangkan dan identifikasi id perangkat yang terdampak:
```bash
openclaw devices list
```
3. Rotasikan token operator untuk perangkat yang terdampak:
```bash
openclaw devices rotate --device <deviceId> --role operator
```
4. Jika rotasi tidak cukup, hapus pairing yang usang dan setujui lagi:
```bash
openclaw devices remove <deviceId>
openclaw devices list
openclaw devices approve <requestId>
```
5. Coba lagi koneksi klien dengan token/kata sandi bersama saat ini.
Catatan:
- Prioritas autentikasi koneksi ulang normal adalah token/kata sandi bersama eksplisit terlebih dahulu, lalu `deviceToken` eksplisit, lalu token perangkat tersimpan, lalu token bootstrap.
- Pemulihan tepercaya `AUTH_TOKEN_MISMATCH` dapat sementara mengirim baik token bersama maupun token perangkat tersimpan secara bersamaan untuk satu percobaan ulang yang dibatasi.
Terkait:
- [Pemecahan masalah autentikasi Dashboard](/web/dashboard#if-you-see-unauthorized-1008)
- [Pemecahan masalah Gateway](/gateway/troubleshooting#dashboard-control-ui-connectivity)

69
docs/id/cli/directory.md Normal file
View File

@ -0,0 +1,69 @@
---
read_when:
- Anda ingin mencari ID kontak/grup/diri sendiri untuk sebuah channel
- Anda sedang mengembangkan adapter direktori channel
summary: Referensi CLI untuk `openclaw directory` (diri sendiri, peer, grup)
title: directory
x-i18n:
generated_at: "2026-04-05T13:45:34Z"
model: gpt-5.4
provider: openai
source_hash: 6a81a037e0a33f77c24b1adabbc4be16ed4d03c419873f3cbdd63f2ce84a1064
source_path: cli/directory.md
workflow: 15
---
# `openclaw directory`
Lookup direktori untuk channel yang mendukungnya (kontak/peer, grup, dan “saya”).
## Flag umum
- `--channel <name>`: id/alias channel (wajib saat beberapa channel dikonfigurasi; otomatis saat hanya satu yang dikonfigurasi)
- `--account <id>`: id akun (default: channel default)
- `--json`: output JSON
## Catatan
- `directory` dimaksudkan untuk membantu Anda menemukan ID yang dapat ditempel ke perintah lain (terutama `openclaw message send --target ...`).
- Untuk banyak channel, hasil didukung config (allowlist / grup yang dikonfigurasi) alih-alih direktori provider langsung.
- Output default adalah `id` (dan kadang `name`) yang dipisahkan oleh tab; gunakan `--json` untuk skrip.
## Menggunakan hasil dengan `message send`
```bash
openclaw directory peers list --channel slack --query "U0"
openclaw message send --channel slack --target user:U012ABCDEF --message "hello"
```
## Format ID (berdasarkan channel)
- WhatsApp: `+15551234567` (DM), `1234567890-1234567890@g.us` (grup)
- Telegram: `@username` atau id chat numerik; grup adalah id numerik
- Discord: `user:<id>` dan `channel:<id>`
- Matrix (plugin): `user:@user:server`, `room:!roomId:server`, atau `#alias:server`
- Microsoft Teams (plugin): `user:<id>` dan `conversation:<id>`
- Zalo (plugin): id pengguna (Bot API)
- Zalo Personal / `zalouser` (plugin): id thread (DM/grup) dari `zca` (`me`, `friend list`, `group list`)
## Diri sendiri ("me")
```bash
openclaw directory self --channel zalouser
```
## Peer (kontak/pengguna)
```bash
openclaw directory peers list --channel zalouser
openclaw directory peers list --channel zalouser --query "name"
openclaw directory peers list --channel zalouser --limit 50
```
## Grup
```bash
openclaw directory groups list --channel zalouser
openclaw directory groups list --channel zalouser --query "work"
openclaw directory groups members --channel zalouser --group-id <id>
```

55
docs/id/cli/dns.md Normal file
View File

@ -0,0 +1,55 @@
---
read_when:
- Anda menginginkan discovery area luas (DNS-SD) melalui Tailscale + CoreDNS
- You’re setting up split DNS for a custom discovery domain (example: openclaw.internal)
summary: Referensi CLI untuk `openclaw dns` (helper discovery area luas)
title: dns
x-i18n:
generated_at: "2026-04-05T13:45:35Z"
model: gpt-5.4
provider: openai
source_hash: 4831fbb7791adfed5195bc4ba36bb248d2bc8830958334211d3c96f824617927
source_path: cli/dns.md
workflow: 15
---
# `openclaw dns`
Helper DNS untuk discovery area luas (Tailscale + CoreDNS). Saat ini berfokus pada macOS + Homebrew CoreDNS.
Terkait:
- Discovery gateway: [Discovery](/gateway/discovery)
- Konfigurasi discovery area luas: [Konfigurasi](/gateway/configuration)
## Penyiapan
```bash
openclaw dns setup
openclaw dns setup --domain openclaw.internal
openclaw dns setup --apply
```
## `dns setup`
Rencanakan atau terapkan penyiapan CoreDNS untuk discovery DNS-SD unicast.
Opsi:
- `--domain <domain>`: domain discovery area luas (misalnya `openclaw.internal`)
- `--apply`: instal atau perbarui config CoreDNS dan mulai ulang layanan (memerlukan sudo; hanya macOS)
Yang ditampilkan:
- domain discovery yang telah diresolusikan
- path file zone
- IP tailnet saat ini
- config discovery `openclaw.json` yang direkomendasikan
- nilai nameserver/domain Tailscale Split DNS yang perlu ditetapkan
Catatan:
- Tanpa `--apply`, perintah ini hanya merupakan helper perencanaan dan mencetak penyiapan yang direkomendasikan.
- Jika `--domain` dihilangkan, OpenClaw menggunakan `discovery.wideArea.domain` dari config.
- `--apply` saat ini hanya mendukung macOS dan mengharapkan Homebrew CoreDNS.
- `--apply` melakukan bootstrap file zone jika diperlukan, memastikan stanza import CoreDNS ada, dan memulai ulang layanan brew `coredns`.

35
docs/id/cli/docs.md Normal file
View File

@ -0,0 +1,35 @@
---
read_when:
- Anda ingin mencari dokumentasi OpenClaw live dari terminal
summary: Referensi CLI untuk `openclaw docs` (mencari indeks dokumentasi live)
title: docs
x-i18n:
generated_at: "2026-04-05T13:45:32Z"
model: gpt-5.4
provider: openai
source_hash: cfcceed872d7509b9843af3fae733a136bc5e26ded55c2ac47a16489a1636989
source_path: cli/docs.md
workflow: 15
---
# `openclaw docs`
Cari indeks dokumentasi live.
Argumen:
- `[query...]`: istilah pencarian yang akan dikirim ke indeks dokumentasi live
Contoh:
```bash
openclaw docs
openclaw docs browser existing-session
openclaw docs sandbox allowHostControl
openclaw docs gateway token secretref
```
Catatan:
- Tanpa kueri, `openclaw docs` membuka entrypoint pencarian dokumentasi live.
- Kueri multi-kata diteruskan sebagai satu permintaan pencarian.

70
docs/id/cli/doctor.md Normal file
View File

@ -0,0 +1,70 @@
---
read_when:
- Anda mengalami masalah konektivitas/autentikasi dan menginginkan perbaikan terpandu
- Anda baru melakukan pembaruan dan menginginkan pemeriksaan kewarasan
summary: Referensi CLI untuk `openclaw doctor` (pemeriksaan kesehatan + perbaikan terpandu)
title: doctor
x-i18n:
generated_at: "2026-04-05T13:45:46Z"
model: gpt-5.4
provider: openai
source_hash: d257a9e2797b4b0b50c1020165c8a1cd6a2342381bf9c351645ca37494c881e1
source_path: cli/doctor.md
workflow: 15
---
# `openclaw doctor`
Pemeriksaan kesehatan + perbaikan cepat untuk gateway dan channel.
Terkait:
- Pemecahan masalah: [Troubleshooting](/gateway/troubleshooting)
- Audit keamanan: [Security](/gateway/security)
## Contoh
```bash
openclaw doctor
openclaw doctor --repair
openclaw doctor --deep
openclaw doctor --repair --non-interactive
openclaw doctor --generate-gateway-token
```
## Opsi
- `--no-workspace-suggestions`: nonaktifkan saran memori/pencarian workspace
- `--yes`: terima default tanpa prompt
- `--repair`: terapkan perbaikan yang direkomendasikan tanpa prompt
- `--fix`: alias untuk `--repair`
- `--force`: terapkan perbaikan agresif, termasuk menimpa konfigurasi layanan kustom bila diperlukan
- `--non-interactive`: jalankan tanpa prompt; hanya migrasi aman
- `--generate-gateway-token`: hasilkan dan konfigurasikan token gateway
- `--deep`: pindai layanan sistem untuk instalasi gateway tambahan
Catatan:
- Prompt interaktif (seperti perbaikan keychain/OAuth) hanya berjalan saat stdin adalah TTY dan `--non-interactive` **tidak** disetel. Eksekusi headless (cron, Telegram, tanpa terminal) akan melewati prompt.
- `--fix` (alias untuk `--repair`) menulis cadangan ke `~/.openclaw/openclaw.json.bak` dan menghapus kunci konfigurasi yang tidak dikenal, sambil mencantumkan setiap penghapusan.
- Pemeriksaan integritas status kini mendeteksi file transkrip yatim di direktori sesi dan dapat mengarsipkannya sebagai `.deleted.<timestamp>` untuk merebut kembali ruang dengan aman.
- Doctor juga memindai `~/.openclaw/cron/jobs.json` (atau `cron.store`) untuk bentuk cron job lama dan dapat menulis ulangnya di tempat sebelum scheduler harus menormalkannya otomatis saat runtime.
- Doctor memigrasikan konfigurasi Talk datar lama (`talk.voiceId`, `talk.modelId`, dan sejenisnya) secara otomatis ke `talk.provider` + `talk.providers.<provider>`.
- Eksekusi berulang `doctor --fix` tidak lagi melaporkan/menerapkan normalisasi Talk saat satu-satunya perbedaan hanyalah urutan kunci objek.
- Doctor menyertakan pemeriksaan kesiapan memory-search dan dapat merekomendasikan `openclaw configure --section model` saat kredensial embedding tidak ada.
- Jika mode sandbox diaktifkan tetapi Docker tidak tersedia, doctor melaporkan peringatan bernilai sinyal tinggi dengan remediasi (`install Docker` atau `openclaw config set agents.defaults.sandbox.mode off`).
- Jika `gateway.auth.token`/`gateway.auth.password` dikelola SecretRef dan tidak tersedia dalam jalur perintah saat ini, doctor melaporkan peringatan read-only dan tidak menulis kredensial fallback plaintext.
- Jika inspeksi SecretRef channel gagal dalam jalur perbaikan, doctor tetap melanjutkan dan melaporkan peringatan alih-alih keluar lebih awal.
- Resolusi otomatis username `allowFrom` Telegram (`doctor --fix`) memerlukan token Telegram yang dapat di-resolve dalam jalur perintah saat ini. Jika inspeksi token tidak tersedia, doctor melaporkan peringatan dan melewati resolusi otomatis untuk eksekusi tersebut.
## macOS: override env `launchctl`
Jika Anda sebelumnya menjalankan `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (atau `...PASSWORD`), nilai tersebut akan menimpa file konfigurasi Anda dan dapat menyebabkan kesalahan “unauthorized” yang persisten.
```bash
launchctl getenv OPENCLAW_GATEWAY_TOKEN
launchctl getenv OPENCLAW_GATEWAY_PASSWORD
launchctl unsetenv OPENCLAW_GATEWAY_TOKEN
launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD
```

25
docs/id/cli/flows.md Normal file
View File

@ -0,0 +1,25 @@
---
read_when:
- Anda menemukan openclaw flows di dokumentasi lama atau catatan rilis
summary: 'Redirect: perintah flow berada di bawah `openclaw tasks flow`'
title: flows (redirect)
x-i18n:
generated_at: "2026-04-05T13:45:37Z"
model: gpt-5.4
provider: openai
source_hash: f4b9acefdb4e8dedde08d96986fe9b1ca7f91293281850b68ff9fa28f0516a61
source_path: cli/flows.md
workflow: 15
---
# `openclaw tasks flow`
Perintah flow adalah subperintah dari `openclaw tasks`, bukan perintah `flows` mandiri.
```bash
openclaw tasks flow list [--json]
openclaw tasks flow show <lookup>
openclaw tasks flow cancel <lookup>
```
Untuk dokumentasi lengkap, lihat [Task Flow](/automation/taskflow) dan [referensi CLI tasks](/cli/index#tasks).

314
docs/id/cli/gateway.md Normal file
View File

@ -0,0 +1,314 @@
---
read_when:
- Menjalankan Gateway dari CLI (dev atau server)
- Men-debug autentikasi Gateway, mode bind, dan konektivitas
- Menemukan gateway melalui Bonjour (DNS-SD lokal + area luas)
summary: CLI Gateway OpenClaw (`openclaw gateway`) — jalankan, kueri, dan temukan gateway
title: gateway
x-i18n:
generated_at: "2026-04-05T13:49:35Z"
model: gpt-5.4
provider: openai
source_hash: e311ded0dbad84b8212f0968f3563998d49c5e0eb292a0dc4b3bd3c22d4fa7f2
source_path: cli/gateway.md
workflow: 15
---
# CLI Gateway
Gateway adalah server WebSocket OpenClaw (channel, node, sesi, hook).
Subperintah di halaman ini berada di bawah `openclaw gateway …`.
Dokumentasi terkait:
- [/gateway/bonjour](/gateway/bonjour)
- [/gateway/discovery](/gateway/discovery)
- [/gateway/configuration](/gateway/configuration)
## Menjalankan Gateway
Jalankan proses Gateway lokal:
```bash
openclaw gateway
```
Alias latar depan:
```bash
openclaw gateway run
```
Catatan:
- Secara default, Gateway menolak untuk memulai kecuali `gateway.mode=local` disetel di `~/.openclaw/openclaw.json`. Gunakan `--allow-unconfigured` untuk proses ad-hoc/dev.
- `openclaw onboard --mode local` dan `openclaw setup` diharapkan menulis `gateway.mode=local`. Jika file ada tetapi `gateway.mode` tidak ada, perlakukan itu sebagai konfigurasi yang rusak atau tertimpa dan perbaiki alih-alih mengasumsikan mode lokal secara implisit.
- Jika file ada dan `gateway.mode` tidak ada, Gateway memperlakukannya sebagai kerusakan konfigurasi yang mencurigakan dan menolak untuk “menebak mode lokal” untuk Anda.
- Bind di luar loopback tanpa autentikasi diblokir (guardrail keamanan).
- `SIGUSR1` memicu restart dalam proses jika diizinkan (`commands.restart` aktif secara default; setel `commands.restart: false` untuk memblokir restart manual, sementara penerapan/pembaruan tool/konfigurasi gateway tetap diizinkan).
- Handler `SIGINT`/`SIGTERM` menghentikan proses gateway, tetapi tidak memulihkan status terminal kustom apa pun. Jika Anda membungkus CLI dengan TUI atau input mode mentah, pulihkan terminal sebelum keluar.
### Opsi
- `--port <port>`: port WebSocket (default berasal dari config/env; biasanya `18789`).
- `--bind <loopback|lan|tailnet|auto|custom>`: mode bind listener.
- `--auth <token|password>`: override mode autentikasi.
- `--token <token>`: override token (juga menetapkan `OPENCLAW_GATEWAY_TOKEN` untuk proses).
- `--password <password>`: override kata sandi. Peringatan: kata sandi inline dapat terlihat di daftar proses lokal.
- `--password-file <path>`: baca kata sandi gateway dari file.
- `--tailscale <off|serve|funnel>`: ekspos Gateway melalui Tailscale.
- `--tailscale-reset-on-exit`: reset konfigurasi Tailscale serve/funnel saat shutdown.
- `--allow-unconfigured`: izinkan gateway mulai tanpa `gateway.mode=local` di config. Ini melewati guard startup hanya untuk bootstrap ad-hoc/dev; ini tidak menulis atau memperbaiki file config.
- `--dev`: buat config + workspace dev jika belum ada (melewati BOOTSTRAP.md).
- `--reset`: reset config + kredensial + sesi + workspace dev (memerlukan `--dev`).
- `--force`: matikan listener yang ada pada port yang dipilih sebelum memulai.
- `--verbose`: log verbose.
- `--cli-backend-logs`: hanya tampilkan log backend CLI di konsol (dan aktifkan stdout/stderr).
- `--claude-cli-logs`: alias usang untuk `--cli-backend-logs`.
- `--ws-log <auto|full|compact>`: gaya log websocket (default `auto`).
- `--compact`: alias untuk `--ws-log compact`.
- `--raw-stream`: log event stream model mentah ke jsonl.
- `--raw-stream-path <path>`: path jsonl stream mentah.
## Mengueri Gateway yang sedang berjalan
Semua perintah kueri menggunakan RPC WebSocket.
Mode output:
- Default: dapat dibaca manusia (berwarna di TTY).
- `--json`: JSON yang dapat dibaca mesin (tanpa styling/spinner).
- `--no-color` (atau `NO_COLOR=1`): nonaktifkan ANSI sambil tetap mempertahankan tata letak untuk manusia.
Opsi bersama (jika didukung):
- `--url <url>`: URL WebSocket Gateway.
- `--token <token>`: token Gateway.
- `--password <password>`: kata sandi Gateway.
- `--timeout <ms>`: timeout/anggaran waktu (bervariasi per perintah).
- `--expect-final`: tunggu respons “final” (panggilan agen).
Catatan: saat Anda menetapkan `--url`, CLI tidak kembali menggunakan kredensial config atau environment.
Berikan `--token` atau `--password` secara eksplisit. Kredensial eksplisit yang tidak ada akan menghasilkan error.
### `gateway health`
```bash
openclaw gateway health --url ws://127.0.0.1:18789
```
### `gateway usage-cost`
Ambil ringkasan biaya penggunaan dari log sesi.
```bash
openclaw gateway usage-cost
openclaw gateway usage-cost --days 7
openclaw gateway usage-cost --json
```
Opsi:
- `--days <days>`: jumlah hari yang disertakan (default `30`).
### `gateway status`
`gateway status` menampilkan layanan Gateway (launchd/systemd/schtasks) beserta probe RPC opsional.
```bash
openclaw gateway status
openclaw gateway status --json
openclaw gateway status --require-rpc
```
Opsi:
- `--url <url>`: tambahkan target probe eksplisit. Remote yang dikonfigurasi + localhost tetap diprobe.
- `--token <token>`: autentikasi token untuk probe.
- `--password <password>`: autentikasi kata sandi untuk probe.
- `--timeout <ms>`: timeout probe (default `10000`).
- `--no-probe`: lewati probe RPC (tampilan layanan saja).
- `--deep`: pindai juga layanan tingkat sistem.
- `--require-rpc`: keluar dengan status non-zero saat probe RPC gagal. Tidak dapat digabungkan dengan `--no-probe`.
Catatan:
- `gateway status` tetap tersedia untuk diagnostik meskipun config CLI lokal tidak ada atau tidak valid.
- `gateway status` menyelesaikan SecretRef autentikasi yang dikonfigurasi untuk autentikasi probe jika memungkinkan.
- Jika SecretRef autentikasi yang diperlukan tidak terselesaikan di jalur perintah ini, `gateway status --json` melaporkan `rpc.authWarning` saat konektivitas/autentikasi probe gagal; berikan `--token`/`--password` secara eksplisit atau selesaikan sumber secret terlebih dahulu.
- Jika probe berhasil, peringatan auth-ref yang tidak terselesaikan disembunyikan untuk menghindari positif palsu.
- Gunakan `--require-rpc` dalam skrip dan otomatisasi saat layanan yang mendengarkan saja tidak cukup dan Anda memerlukan RPC Gateway itu sendiri dalam keadaan sehat.
- `--deep` menambahkan pemindaian best-effort untuk instalasi launchd/systemd/schtasks tambahan. Ketika beberapa layanan mirip gateway terdeteksi, output untuk manusia mencetak petunjuk pembersihan dan memperingatkan bahwa sebagian besar setup seharusnya menjalankan satu gateway per mesin.
- Output untuk manusia mencakup path log file yang telah diselesaikan beserta snapshot path/validitas config CLI-vs-service untuk membantu mendiagnosis drift profil atau state-dir.
- Pada instalasi systemd Linux, pemeriksaan drift autentikasi layanan membaca nilai `Environment=` dan `EnvironmentFile=` dari unit (termasuk `%h`, path dalam tanda kutip, beberapa file, dan file opsional `-`).
- Pemeriksaan drift menyelesaikan SecretRef `gateway.auth.token` menggunakan env runtime gabungan (env perintah layanan terlebih dahulu, lalu fallback env proses).
- Jika autentikasi token tidak aktif secara efektif (nilai eksplisit `gateway.auth.mode` adalah `password`/`none`/`trusted-proxy`, atau mode tidak disetel sehingga password bisa menang dan tidak ada kandidat token yang bisa menang), pemeriksaan drift token melewati resolusi token config.
### `gateway probe`
`gateway probe` adalah perintah “debug semuanya”. Perintah ini selalu memprobe:
- gateway remote yang dikonfigurasi (jika ada), dan
- localhost (loopback) **bahkan jika remote dikonfigurasi**.
Jika Anda memberikan `--url`, target eksplisit tersebut ditambahkan di depan keduanya. Output untuk manusia memberi label pada
target sebagai:
- `URL (eksplisit)`
- `Remote (dikonfigurasi)` atau `Remote (dikonfigurasi, tidak aktif)`
- `Local loopback`
Jika beberapa gateway dapat dijangkau, perintah ini mencetak semuanya. Beberapa gateway didukung saat Anda menggunakan profil/port terisolasi (misalnya, rescue bot), tetapi sebagian besar instalasi tetap menjalankan satu gateway.
```bash
openclaw gateway probe
openclaw gateway probe --json
```
Interpretasi:
- `Reachable: yes` berarti setidaknya satu target menerima koneksi WebSocket.
- `RPC: ok` berarti panggilan RPC detail (`health`/`status`/`system-presence`/`config.get`) juga berhasil.
- `RPC: limited - missing scope: operator.read` berarti koneksi berhasil tetapi RPC detail dibatasi oleh scope. Ini dilaporkan sebagai keterjangkauan **terdegradasi**, bukan kegagalan penuh.
- Kode keluar non-zero hanya ketika tidak ada target yang diprobe yang dapat dijangkau.
Catatan JSON (`--json`):
- Level atas:
- `ok`: setidaknya satu target dapat dijangkau.
- `degraded`: setidaknya satu target memiliki RPC detail yang dibatasi scope.
- `primaryTargetId`: target terbaik untuk diperlakukan sebagai pemenang aktif dalam urutan ini: URL eksplisit, tunnel SSH, remote yang dikonfigurasi, lalu local loopback.
- `warnings[]`: catatan peringatan best-effort dengan `code`, `message`, dan `targetIds` opsional.
- `network`: petunjuk URL local loopback/tailnet yang diturunkan dari config saat ini dan jaringan host.
- `discovery.timeoutMs` dan `discovery.count`: anggaran penemuan/jumlah hasil aktual yang digunakan untuk pass probe ini.
- Per target (`targets[].connect`):
- `ok`: keterjangkauan setelah koneksi + klasifikasi terdegradasi.
- `rpcOk`: keberhasilan penuh RPC detail.
- `scopeLimited`: RPC detail gagal karena scope operator tidak ada.
Kode peringatan umum:
- `ssh_tunnel_failed`: setup tunnel SSH gagal; perintah kembali menggunakan probe langsung.
- `multiple_gateways`: lebih dari satu target dapat dijangkau; ini tidak biasa kecuali Anda sengaja menjalankan profil terisolasi, seperti rescue bot.
- `auth_secretref_unresolved`: SecretRef autentikasi yang dikonfigurasi tidak dapat diselesaikan untuk target yang gagal.
- `probe_scope_limited`: koneksi WebSocket berhasil, tetapi RPC detail dibatasi karena `operator.read` tidak ada.
#### Remote melalui SSH (paritas app Mac)
Mode “Remote over SSH” pada app macOS menggunakan port-forward lokal sehingga gateway remote (yang mungkin hanya di-bind ke loopback) menjadi dapat dijangkau di `ws://127.0.0.1:<port>`.
Padanan CLI:
```bash
openclaw gateway probe --ssh user@gateway-host
```
Opsi:
- `--ssh <target>`: `user@host` atau `user@host:port` (port default `22`).
- `--ssh-identity <path>`: file identitas.
- `--ssh-auto`: pilih host gateway pertama yang ditemukan sebagai target SSH dari endpoint
discovery yang telah diselesaikan (`local.` ditambah domain area luas yang dikonfigurasi, jika ada). Petunjuk TXT saja
diabaikan.
Config (opsional, digunakan sebagai default):
- `gateway.remote.sshTarget`
- `gateway.remote.sshIdentity`
### `gateway call <method>`
Helper RPC level rendah.
```bash
openclaw gateway call status
openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
```
Opsi:
- `--params <json>`: string objek JSON untuk parameter (default `{}`)
- `--url <url>`
- `--token <token>`
- `--password <password>`
- `--timeout <ms>`
- `--expect-final`
- `--json`
Catatan:
- `--params` harus berupa JSON yang valid.
- `--expect-final` terutama untuk RPC gaya agen yang mengalirkan event perantara sebelum payload final.
## Mengelola layanan Gateway
```bash
openclaw gateway install
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway uninstall
```
Opsi perintah:
- `gateway status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json`
- `gateway install`: `--port`, `--runtime <node|bun>`, `--token`, `--force`, `--json`
- `gateway uninstall|start|stop|restart`: `--json`
Catatan:
- `gateway install` mendukung `--port`, `--runtime`, `--token`, `--force`, `--json`.
- Ketika autentikasi token memerlukan token dan `gateway.auth.token` dikelola oleh SecretRef, `gateway install` memvalidasi bahwa SecretRef dapat diselesaikan tetapi tidak menyimpan token yang telah diselesaikan ke metadata environment layanan.
- Jika autentikasi token memerlukan token dan SecretRef token yang dikonfigurasi tidak terselesaikan, instalasi gagal secara tertutup alih-alih menyimpan fallback plaintext.
- Untuk autentikasi kata sandi pada `gateway run`, pilih `OPENCLAW_GATEWAY_PASSWORD`, `--password-file`, atau `gateway.auth.password` berbasis SecretRef daripada `--password` inline.
- Dalam mode autentikasi tersimpulkan, `OPENCLAW_GATEWAY_PASSWORD` yang hanya ada di shell tidak melonggarkan persyaratan token instalasi; gunakan konfigurasi yang persisten (`gateway.auth.password` atau `env` config) saat menginstal layanan terkelola.
- Jika `gateway.auth.token` dan `gateway.auth.password` sama-sama dikonfigurasi dan `gateway.auth.mode` tidak disetel, instalasi diblokir sampai mode disetel secara eksplisit.
- Perintah siklus hidup menerima `--json` untuk scripting.
## Menemukan gateway (Bonjour)
`gateway discover` memindai beacon Gateway (`_openclaw-gw._tcp`).
- Multicast DNS-SD: `local.`
- Unicast DNS-SD (Wide-Area Bonjour): pilih domain (contoh: `openclaw.internal.`) dan siapkan split DNS + server DNS; lihat [/gateway/bonjour](/gateway/bonjour)
Hanya gateway dengan discovery Bonjour yang diaktifkan (default) yang mengiklankan beacon.
Rekaman discovery Wide-Area menyertakan (TXT):
- `role` (petunjuk peran gateway)
- `transport` (petunjuk transport, misalnya `gateway`)
- `gatewayPort` (port WebSocket, biasanya `18789`)
- `sshPort` (opsional; klien menggunakan target SSH default `22` ketika ini tidak ada)
- `tailnetDns` (hostname MagicDNS, jika tersedia)
- `gatewayTls` / `gatewayTlsSha256` (TLS diaktifkan + sidik jari sertifikat)
- `cliPath` (petunjuk instalasi remote yang ditulis ke zona area luas)
### `gateway discover`
```bash
openclaw gateway discover
```
Opsi:
- `--timeout <ms>`: timeout per perintah (browse/resolve); default `2000`.
- `--json`: output yang dapat dibaca mesin (juga menonaktifkan styling/spinner).
Contoh:
```bash
openclaw gateway discover --timeout 4000
openclaw gateway discover --json | jq '.beacons[].wsUrl'
```
Catatan:
- CLI memindai `local.` ditambah domain area luas yang dikonfigurasi saat ada yang diaktifkan.
- `wsUrl` dalam output JSON diturunkan dari endpoint layanan yang telah diselesaikan, bukan dari petunjuk
TXT saja seperti `lanHost` atau `tailnetDns`.
- Pada mDNS `local.`, `sshPort` dan `cliPath` hanya disiarkan ketika
`discovery.mdns.mode` adalah `full`. Wide-area DNS-SD tetap menulis `cliPath`; `sshPort`
tetap opsional di sana juga.

43
docs/id/cli/health.md Normal file
View File

@ -0,0 +1,43 @@
---
read_when:
- Anda ingin cepat memeriksa kesehatan Gateway yang sedang berjalan
summary: Referensi CLI untuk `openclaw health` (snapshot kesehatan gateway melalui RPC)
title: health
x-i18n:
generated_at: "2026-04-05T13:45:40Z"
model: gpt-5.4
provider: openai
source_hash: 4ed2b9ceefee6159cabaae9172d2d88174626456e7503d5d2bcd142634188ff0
source_path: cli/health.md
workflow: 15
---
# `openclaw health`
Ambil status kesehatan dari Gateway yang sedang berjalan.
Opsi:
- `--json`: output yang dapat dibaca mesin
- `--timeout <ms>`: timeout koneksi dalam milidetik (default `10000`)
- `--verbose`: logging verbose
- `--debug`: alias untuk `--verbose`
Contoh:
```bash
openclaw health
openclaw health --json
openclaw health --timeout 2500
openclaw health --verbose
openclaw health --debug
```
Catatan:
- `openclaw health` default meminta snapshot kesehatan dari gateway yang sedang berjalan. Saat
gateway sudah memiliki snapshot cache yang masih baru, gateway dapat mengembalikan payload cache tersebut dan
melakukan refresh di latar belakang.
- `--verbose` memaksa probe live, mencetak detail koneksi gateway, dan memperluas
output yang dapat dibaca manusia ke semua akun dan agen yang dikonfigurasi.
- Output menyertakan penyimpanan sesi per agen saat beberapa agen dikonfigurasi.

344
docs/id/cli/hooks.md Normal file
View File

@ -0,0 +1,344 @@
---
read_when:
- Anda ingin mengelola hook agen
- Anda ingin memeriksa ketersediaan hook atau mengaktifkan hook workspace
summary: Referensi CLI untuk `openclaw hooks` (hook agen)
title: hook
x-i18n:
generated_at: "2026-04-05T13:49:18Z"
model: gpt-5.4
provider: openai
source_hash: 8dc9144e9844e9c3cdef2514098eb170543746fcc55ca5a1cc746c12d80209e7
source_path: cli/hooks.md
workflow: 15
---
# `openclaw hooks`
Kelola hook agen (otomatisasi berbasis peristiwa untuk perintah seperti `/new`, `/reset`, dan startup gateway).
Menjalankan `openclaw hooks` tanpa subperintah setara dengan `openclaw hooks list`.
Terkait:
- Hook: [Hooks](/id/automation/hooks)
- Hook plugin: [Plugin hooks](/plugins/architecture#provider-runtime-hooks)
## Daftar Semua Hook
```bash
openclaw hooks list
```
Daftarkan semua hook yang ditemukan dari direktori workspace, managed, extra, dan bundled.
**Opsi:**
- `--eligible`: Tampilkan hanya hook yang memenuhi syarat
- `--json`: Keluarkan sebagai JSON
- `-v, --verbose`: Tampilkan informasi terperinci termasuk persyaratan yang belum terpenuhi
**Contoh output:**
```
Hooks (4/4 ready)
Ready:
🚀 boot-md ✓ - Jalankan BOOT.md saat startup gateway
📎 bootstrap-extra-files ✓ - Sisipkan file bootstrap workspace tambahan selama bootstrap agen
📝 command-logger ✓ - Catat semua peristiwa perintah ke file audit terpusat
💾 session-memory ✓ - Simpan konteks sesi ke memori saat perintah /new atau /reset dijalankan
```
**Contoh (verbose):**
```bash
openclaw hooks list --verbose
```
Menampilkan persyaratan yang belum terpenuhi untuk hook yang tidak memenuhi syarat.
**Contoh (JSON):**
```bash
openclaw hooks list --json
```
Mengembalikan JSON terstruktur untuk penggunaan terprogram.
## Dapatkan Informasi Hook
```bash
openclaw hooks info <name>
```
Tampilkan informasi terperinci tentang hook tertentu.
**Argumen:**
- `<name>`: Nama hook atau kunci hook (misalnya, `session-memory`)
**Opsi:**
- `--json`: Keluarkan sebagai JSON
**Contoh:**
```bash
openclaw hooks info session-memory
```
**Output:**
```
💾 session-memory ✓ Siap
Simpan konteks sesi ke memori saat perintah /new atau /reset dijalankan
Detail:
Source: openclaw-bundled
Path: /path/to/openclaw/hooks/bundled/session-memory/HOOK.md
Handler: /path/to/openclaw/hooks/bundled/session-memory/handler.ts
Homepage: https://docs.openclaw.ai/automation/hooks#session-memory
Events: command:new, command:reset
Requirements:
Config: ✓ workspace.dir
```
## Periksa Kelayakan Hook
```bash
openclaw hooks check
```
Tampilkan ringkasan status kelayakan hook (berapa banyak yang siap vs. tidak siap).
**Opsi:**
- `--json`: Keluarkan sebagai JSON
**Contoh output:**
```
Hooks Status
Total hooks: 4
Ready: 4
Not ready: 0
```
## Aktifkan Hook
```bash
openclaw hooks enable <name>
```
Aktifkan hook tertentu dengan menambahkannya ke konfigurasi Anda (`~/.openclaw/openclaw.json` secara default).
**Catatan:** Hook workspace dinonaktifkan secara default sampai diaktifkan di sini atau di konfigurasi. Hook yang dikelola oleh plugin menampilkan `plugin:<id>` di `openclaw hooks list` dan tidak dapat diaktifkan/dinonaktifkan di sini. Aktifkan/nonaktifkan plugin sebagai gantinya.
**Argumen:**
- `<name>`: Nama hook (misalnya, `session-memory`)
**Contoh:**
```bash
openclaw hooks enable session-memory
```
**Output:**
```
✓ Hook diaktifkan: 💾 session-memory
```
**Yang dilakukan:**
- Memeriksa apakah hook ada dan memenuhi syarat
- Memperbarui `hooks.internal.entries.<name>.enabled = true` di konfigurasi Anda
- Menyimpan konfigurasi ke disk
Jika hook berasal dari `<workspace>/hooks/`, langkah opt-in ini wajib dilakukan sebelum
Gateway akan memuatnya.
**Setelah diaktifkan:**
- Mulai ulang gateway agar hook dimuat ulang (mulai ulang app bilah menu di macOS, atau mulai ulang proses gateway Anda dalam dev).
## Nonaktifkan Hook
```bash
openclaw hooks disable <name>
```
Nonaktifkan hook tertentu dengan memperbarui konfigurasi Anda.
**Argumen:**
- `<name>`: Nama hook (misalnya, `command-logger`)
**Contoh:**
```bash
openclaw hooks disable command-logger
```
**Output:**
```
⏸ Hook dinonaktifkan: 📝 command-logger
```
**Setelah dinonaktifkan:**
- Mulai ulang gateway agar hook dimuat ulang
## Catatan
- `openclaw hooks list --json`, `info --json`, dan `check --json` menulis JSON terstruktur langsung ke stdout.
- Hook yang dikelola plugin tidak dapat diaktifkan atau dinonaktifkan di sini; aktifkan atau nonaktifkan plugin pemiliknya sebagai gantinya.
## Instal Paket Hook
```bash
openclaw plugins install <package> # ClawHub terlebih dahulu, lalu npm
openclaw plugins install <package> --pin # sematkan versi
openclaw plugins install <path> # path lokal
```
Instal paket hook melalui penginstal plugin terpadu.
`openclaw hooks install` masih berfungsi sebagai alias kompatibilitas, tetapi menampilkan
peringatan deprecation dan meneruskan ke `openclaw plugins install`.
Spesifikasi npm bersifat **khusus registri** (nama paket + **versi exact** opsional atau
**dist-tag**). Spesifikasi Git/URL/file dan rentang semver ditolak. Penginstalan
dependensi dijalankan dengan `--ignore-scripts` demi keamanan.
Spesifikasi polos dan `@latest` tetap berada di jalur stabil. Jika npm menyelesaikan salah satu dari
itu ke versi prerelease, OpenClaw berhenti dan meminta Anda untuk melakukan opt-in secara eksplisit dengan
tag prerelease seperti `@beta`/`@rc` atau versi prerelease exact.
**Yang dilakukan:**
- Menyalin paket hook ke `~/.openclaw/hooks/<id>`
- Mengaktifkan hook yang diinstal di `hooks.internal.entries.*`
- Mencatat penginstalan di `hooks.internal.installs`
**Opsi:**
- `-l, --link`: Tautkan direktori lokal alih-alih menyalin (menambahkannya ke `hooks.internal.load.extraDirs`)
- `--pin`: Catat penginstalan npm sebagai `name@version` exact yang telah diselesaikan di `hooks.internal.installs`
**Arsip yang didukung:** `.zip`, `.tgz`, `.tar.gz`, `.tar`
**Contoh:**
```bash
# Direktori lokal
openclaw plugins install ./my-hook-pack
# Arsip lokal
openclaw plugins install ./my-hook-pack.zip
# Paket NPM
openclaw plugins install @openclaw/my-hook-pack
# Tautkan direktori lokal tanpa menyalin
openclaw plugins install -l ./my-hook-pack
```
Paket hook yang ditautkan diperlakukan sebagai hook managed dari
direktori yang dikonfigurasi operator, bukan sebagai hook workspace.
## Perbarui Paket Hook
```bash
openclaw plugins update <id>
openclaw plugins update --all
```
Perbarui paket hook berbasis npm yang dilacak melalui pembaru plugin terpadu.
`openclaw hooks update` masih berfungsi sebagai alias kompatibilitas, tetapi menampilkan
peringatan deprecation dan meneruskan ke `openclaw plugins update`.
**Opsi:**
- `--all`: Perbarui semua paket hook yang dilacak
- `--dry-run`: Tampilkan apa yang akan berubah tanpa menulis
Ketika hash integritas tersimpan ada dan hash artefak yang diambil berubah,
OpenClaw menampilkan peringatan dan meminta konfirmasi sebelum melanjutkan. Gunakan
`--yes` global untuk melewati prompt dalam menjalankan CI/non-interaktif.
## Hook Bundled
### session-memory
Menyimpan konteks sesi ke memori saat Anda menjalankan `/new` atau `/reset`.
**Aktifkan:**
```bash
openclaw hooks enable session-memory
```
**Output:** `~/.openclaw/workspace/memory/YYYY-MM-DD-slug.md`
**Lihat:** [dokumentasi session-memory](/id/automation/hooks#session-memory)
### bootstrap-extra-files
Menyisipkan file bootstrap tambahan (misalnya `AGENTS.md` / `TOOLS.md` lokal monorepo) selama `agent:bootstrap`.
**Aktifkan:**
```bash
openclaw hooks enable bootstrap-extra-files
```
**Lihat:** [dokumentasi bootstrap-extra-files](/id/automation/hooks#bootstrap-extra-files)
### command-logger
Mencatat semua peristiwa perintah ke file audit terpusat.
**Aktifkan:**
```bash
openclaw hooks enable command-logger
```
**Output:** `~/.openclaw/logs/commands.log`
**Lihat log:**
```bash
# Perintah terbaru
tail -n 20 ~/.openclaw/logs/commands.log
# Cetak rapi
cat ~/.openclaw/logs/commands.log | jq .
# Filter berdasarkan aksi
grep '"action":"new"' ~/.openclaw/logs/commands.log | jq .
```
**Lihat:** [dokumentasi command-logger](/id/automation/hooks#command-logger)
### boot-md
Menjalankan `BOOT.md` saat gateway dimulai (setelah channel dimulai).
**Peristiwa**: `gateway:startup`
**Aktifkan**:
```bash
openclaw hooks enable boot-md
```
**Lihat:** [dokumentasi boot-md](/id/automation/hooks#boot-md)

1828
docs/id/cli/index.md Normal file
View File

File diff suppressed because it is too large Load Diff

66
docs/id/cli/logs.md Normal file
View File

@ -0,0 +1,66 @@
---
read_when:
- Anda perlu melakukan tail log Gateway dari jarak jauh (tanpa SSH)
- Anda menginginkan baris log JSON untuk tooling
summary: Referensi CLI untuk `openclaw logs` (tail log gateway melalui RPC)
title: logs
x-i18n:
generated_at: "2026-04-05T13:45:46Z"
model: gpt-5.4
provider: openai
source_hash: 238a52e31a9a332cab513ced049e92d032b03c50376895ce57dffa2ee7d1e4b4
source_path: cli/logs.md
workflow: 15
---
# `openclaw logs`
Lakukan tail log file Gateway melalui RPC (berfungsi dalam mode jarak jauh).
Terkait:
- Ikhtisar logging: [Logging](/logging)
- CLI Gateway: [gateway](/cli/gateway)
## Opsi
- `--limit <n>`: jumlah maksimum baris log yang dikembalikan (default `200`)
- `--max-bytes <n>`: jumlah byte maksimum yang dibaca dari file log (default `250000`)
- `--follow`: ikuti stream log
- `--interval <ms>`: interval polling saat mengikuti (default `1000`)
- `--json`: keluarkan event JSON dengan pemisah baris
- `--plain`: output teks biasa tanpa format bergaya
- `--no-color`: nonaktifkan warna ANSI
- `--local-time`: render stempel waktu dalam zona waktu lokal Anda
## Opsi RPC Gateway bersama
`openclaw logs` juga menerima flag klien Gateway standar:
- `--url <url>`: URL WebSocket Gateway
- `--token <token>`: token Gateway
- `--timeout <ms>`: timeout dalam ms (default `30000`)
- `--expect-final`: tunggu respons final saat pemanggilan Gateway didukung agen
Saat Anda meneruskan `--url`, CLI tidak otomatis menerapkan kredensial config atau environment. Sertakan `--token` secara eksplisit jika Gateway target memerlukan auth.
## Contoh
```bash
openclaw logs
openclaw logs --follow
openclaw logs --follow --interval 2000
openclaw logs --limit 500 --max-bytes 500000
openclaw logs --json
openclaw logs --plain
openclaw logs --no-color
openclaw logs --limit 500
openclaw logs --local-time
openclaw logs --follow --local-time
openclaw logs --url ws://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"
```
## Catatan
- Gunakan `--local-time` untuk merender stempel waktu dalam zona waktu lokal Anda.
- Jika Gateway local loopback meminta pairing, `openclaw logs` akan otomatis fallback ke file log lokal yang dikonfigurasi. Target `--url` eksplisit tidak menggunakan fallback ini.

523
docs/id/cli/mcp.md Normal file
View File

@ -0,0 +1,523 @@
---
read_when:
- Menghubungkan Codex, Claude Code, atau klien MCP lain ke saluran yang didukung OpenClaw
- Menjalankan `openclaw mcp serve`
- Mengelola definisi server MCP tersimpan milik OpenClaw
summary: Mengekspos percakapan saluran OpenClaw melalui MCP dan mengelola definisi server MCP tersimpan
title: mcp
x-i18n:
generated_at: "2026-04-05T13:49:31Z"
model: gpt-5.4
provider: openai
source_hash: b35de9e14f96666eeca2f93c06cb214e691152f911d45ee778efe9cf5bf96cc2
source_path: cli/mcp.md
workflow: 15
---
# mcp
`openclaw mcp` memiliki dua tugas:
- menjalankan OpenClaw sebagai server MCP dengan `openclaw mcp serve`
- mengelola definisi server MCP keluar milik OpenClaw dengan `list`, `show`,
`set`, dan `unset`
Dengan kata lain:
- `serve` adalah OpenClaw yang bertindak sebagai server MCP
- `list` / `show` / `set` / `unset` adalah OpenClaw yang bertindak sebagai
registri sisi klien MCP untuk server MCP lain yang mungkin digunakan oleh
runtime-nya nanti
Gunakan [`openclaw acp`](/cli/acp) saat OpenClaw harus meng-host sesi harness
pengodean itu sendiri dan merutekan runtime tersebut melalui ACP.
## OpenClaw sebagai server MCP
Ini adalah jalur `openclaw mcp serve`.
## Kapan menggunakan `serve`
Gunakan `openclaw mcp serve` saat:
- Codex, Claude Code, atau klien MCP lain harus berbicara langsung dengan
percakapan saluran yang didukung OpenClaw
- Anda sudah memiliki Gateway OpenClaw lokal atau jarak jauh dengan sesi yang
telah dirutekan
- Anda menginginkan satu server MCP yang berfungsi di seluruh backend saluran
OpenClaw alih-alih menjalankan bridge terpisah per saluran
Gunakan [`openclaw acp`](/cli/acp) sebagai gantinya saat OpenClaw harus
meng-host runtime pengodean itu sendiri dan menjaga sesi agen tetap berada di
dalam OpenClaw.
## Cara kerjanya
`openclaw mcp serve` memulai server MCP stdio. Klien MCP memiliki proses
tersebut. Selama klien mempertahankan sesi stdio tetap terbuka, bridge akan
terhubung ke Gateway OpenClaw lokal atau jarak jauh melalui WebSocket dan
mengekspos percakapan saluran yang telah dirutekan melalui MCP.
Siklus hidup:
1. klien MCP memunculkan `openclaw mcp serve`
2. bridge terhubung ke Gateway
3. sesi yang telah dirutekan menjadi percakapan MCP serta alat transkrip/riwayat
4. peristiwa langsung diantrikan di memori selama bridge terhubung
5. jika mode saluran Claude diaktifkan, sesi yang sama juga dapat menerima
notifikasi push khusus Claude
Perilaku penting:
- status antrean langsung dimulai saat bridge terhubung
- riwayat transkrip lama dibaca dengan `messages_read`
- notifikasi push Claude hanya ada selama sesi MCP masih aktif
- saat klien terputus, bridge berhenti dan antrean langsung hilang
## Pilih mode klien
Gunakan bridge yang sama dengan dua cara berbeda:
- Klien MCP generik: hanya alat MCP standar. Gunakan `conversations_list`,
`messages_read`, `events_poll`, `events_wait`, `messages_send`, dan alat
persetujuan.
- Claude Code: alat MCP standar ditambah adaptor saluran khusus Claude.
Aktifkan `--claude-channel-mode on` atau biarkan default `auto`.
Saat ini, `auto` berperilaku sama dengan `on`. Belum ada deteksi kemampuan
klien.
## Yang diekspos oleh `serve`
Bridge menggunakan metadata rute sesi Gateway yang sudah ada untuk mengekspos
percakapan berbasis saluran. Sebuah percakapan muncul saat OpenClaw sudah
memiliki status sesi dengan rute yang diketahui seperti:
- `channel`
- metadata penerima atau tujuan
- `accountId` opsional
- `threadId` opsional
Ini memberi klien MCP satu tempat untuk:
- mencantumkan percakapan yang baru dirutekan
- membaca riwayat transkrip terbaru
- menunggu peristiwa masuk baru
- mengirim balasan kembali melalui rute yang sama
- melihat permintaan persetujuan yang tiba saat bridge terhubung
## Penggunaan
```bash
# Gateway lokal
openclaw mcp serve
# Gateway jarak jauh
openclaw mcp serve --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token
# Gateway jarak jauh dengan autentikasi kata sandi
openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password
# Aktifkan log bridge verbose
openclaw mcp serve --verbose
# Nonaktifkan notifikasi push khusus Claude
openclaw mcp serve --claude-channel-mode off
```
## Alat bridge
Bridge saat ini mengekspos alat MCP berikut:
- `conversations_list`
- `conversation_get`
- `messages_read`
- `attachments_fetch`
- `events_poll`
- `events_wait`
- `messages_send`
- `permissions_list_open`
- `permissions_respond`
### `conversations_list`
Mencantumkan percakapan terbaru berbasis sesi yang sudah memiliki metadata rute
dalam status sesi Gateway.
Filter yang berguna:
- `limit`
- `search`
- `channel`
- `includeDerivedTitles`
- `includeLastMessage`
### `conversation_get`
Mengembalikan satu percakapan berdasarkan `session_key`.
### `messages_read`
Membaca pesan transkrip terbaru untuk satu percakapan berbasis sesi.
### `attachments_fetch`
Mengekstrak blok konten pesan non-teks dari satu pesan transkrip. Ini adalah
tampilan metadata atas konten transkrip, bukan penyimpanan blob lampiran tahan
lama yang berdiri sendiri.
### `events_poll`
Membaca peristiwa langsung yang diantrikan sejak kursor numerik.
### `events_wait`
Melakukan long-polling hingga peristiwa antrean berikutnya yang cocok tiba atau
batas waktu habis.
Gunakan ini saat klien MCP generik membutuhkan pengiriman hampir real-time
tanpa protokol push khusus Claude.
### `messages_send`
Mengirim teks kembali melalui rute yang sama yang sudah tercatat pada sesi.
Perilaku saat ini:
- memerlukan rute percakapan yang sudah ada
- menggunakan channel, penerima, id akun, dan id thread milik sesi
- hanya mengirim teks
### `permissions_list_open`
Mencantumkan permintaan persetujuan exec/plugin tertunda yang telah diamati oleh
bridge sejak terhubung ke Gateway.
### `permissions_respond`
Menyelesaikan satu permintaan persetujuan exec/plugin tertunda dengan:
- `allow-once`
- `allow-always`
- `deny`
## Model peristiwa
Bridge menyimpan antrean peristiwa di memori selama terhubung.
Jenis peristiwa saat ini:
- `message`
- `exec_approval_requested`
- `exec_approval_resolved`
- `plugin_approval_requested`
- `plugin_approval_resolved`
- `claude_permission_request`
Batasan penting:
- antrean bersifat live-only; antrean dimulai saat bridge MCP dimulai
- `events_poll` dan `events_wait` tidak memutar ulang riwayat Gateway yang
lebih lama dengan sendirinya
- backlog tahan lama harus dibaca dengan `messages_read`
## Notifikasi saluran Claude
Bridge juga dapat mengekspos notifikasi saluran khusus Claude. Ini adalah
padanan OpenClaw untuk adaptor saluran Claude Code: alat MCP standar tetap
tersedia, tetapi pesan masuk langsung juga dapat tiba sebagai notifikasi MCP
khusus Claude.
Flag:
- `--claude-channel-mode off`: hanya alat MCP standar
- `--claude-channel-mode on`: aktifkan notifikasi saluran Claude
- `--claude-channel-mode auto`: default saat ini; perilaku bridge sama seperti `on`
Saat mode saluran Claude diaktifkan, server mengiklankan kemampuan eksperimental
Claude dan dapat memancarkan:
- `notifications/claude/channel`
- `notifications/claude/channel/permission`
Perilaku bridge saat ini:
- pesan transkrip masuk `user` diteruskan sebagai
`notifications/claude/channel`
- permintaan persetujuan Claude yang diterima melalui MCP dilacak di memori
- jika percakapan terkait kemudian mengirim `yes abcde` atau `no abcde`, bridge
mengubahnya menjadi `notifications/claude/channel/permission`
- notifikasi ini hanya berlaku untuk sesi langsung; jika klien MCP terputus,
tidak ada target push
Ini memang khusus klien. Klien MCP generik harus mengandalkan alat polling
standar.
## Konfigurasi klien MCP
Contoh konfigurasi klien stdio:
```json
{
"mcpServers": {
"openclaw": {
"command": "openclaw",
"args": [
"mcp",
"serve",
"--url",
"wss://gateway-host:18789",
"--token-file",
"/path/to/gateway.token"
]
}
}
}
```
Untuk sebagian besar klien MCP generik, mulai dengan permukaan alat standar dan
abaikan mode Claude. Aktifkan mode Claude hanya untuk klien yang benar-benar
memahami metode notifikasi khusus Claude.
## Opsi
`openclaw mcp serve` mendukung:
- `--url <url>`: URL WebSocket Gateway
- `--token <token>`: token Gateway
- `--token-file <path>`: baca token dari file
- `--password <password>`: kata sandi Gateway
- `--password-file <path>`: baca kata sandi dari file
- `--claude-channel-mode <auto|on|off>`: mode notifikasi Claude
- `-v`, `--verbose`: log verbose di stderr
Sebaiknya gunakan `--token-file` atau `--password-file` daripada secret inline
jika memungkinkan.
## Keamanan dan batas kepercayaan
Bridge tidak menciptakan perutean. Bridge hanya mengekspos percakapan yang
sudah diketahui Gateway cara merutekannya.
Artinya:
- daftar izin pengirim, pairing, dan trust tingkat saluran tetap menjadi bagian
dari konfigurasi saluran OpenClaw yang mendasarinya
- `messages_send` hanya dapat membalas melalui rute tersimpan yang sudah ada
- status persetujuan hanya bersifat langsung/di memori untuk sesi bridge saat
ini
- autentikasi bridge harus menggunakan kontrol token atau kata sandi Gateway
yang sama seperti yang Anda percayai untuk klien Gateway jarak jauh lainnya
Jika sebuah percakapan hilang dari `conversations_list`, penyebab umumnya bukan
konfigurasi MCP. Penyebabnya adalah metadata rute yang hilang atau tidak lengkap
dalam sesi Gateway yang mendasarinya.
## Pengujian
OpenClaw menyediakan smoke Docker yang deterministik untuk bridge ini:
```bash
pnpm test:docker:mcp-channels
```
Smoke tersebut:
- memulai container Gateway yang telah di-seed
- memulai container kedua yang memunculkan `openclaw mcp serve`
- memverifikasi penemuan percakapan, pembacaan transkrip, pembacaan metadata
lampiran, perilaku antrean peristiwa langsung, dan perutean pengiriman keluar
- memvalidasi notifikasi saluran dan persetujuan bergaya Claude melalui bridge
stdio MCP yang nyata
Ini adalah cara tercepat untuk membuktikan bahwa bridge berfungsi tanpa harus
menghubungkan akun Telegram, Discord, atau iMessage nyata ke dalam proses uji.
Untuk konteks pengujian yang lebih luas, lihat [Testing](/help/testing).
## Pemecahan masalah
### Tidak ada percakapan yang dikembalikan
Biasanya berarti sesi Gateway belum dapat dirutekan. Pastikan bahwa sesi yang
mendasarinya memiliki metadata rute channel/provider, penerima, serta
account/thread opsional yang tersimpan.
### `events_poll` atau `events_wait` melewatkan pesan lama
Memang begitu. Antrean langsung dimulai saat bridge terhubung. Baca riwayat
transkrip yang lebih lama dengan `messages_read`.
### Notifikasi Claude tidak muncul
Periksa semua hal berikut:
- klien mempertahankan sesi stdio MCP tetap terbuka
- `--claude-channel-mode` bernilai `on` atau `auto`
- klien benar-benar memahami metode notifikasi khusus Claude
- pesan masuk terjadi setelah bridge terhubung
### Persetujuan hilang
`permissions_list_open` hanya menampilkan permintaan persetujuan yang diamati
saat bridge terhubung. Ini bukan API riwayat persetujuan yang tahan lama.
## OpenClaw sebagai registri klien MCP
Ini adalah jalur `openclaw mcp list`, `show`, `set`, dan `unset`.
Perintah-perintah ini tidak mengekspos OpenClaw melalui MCP. Perintah-perintah
ini mengelola definisi server MCP milik OpenClaw di bawah `mcp.servers` dalam
konfigurasi OpenClaw.
Definisi yang disimpan tersebut ditujukan untuk runtime yang nanti diluncurkan
atau dikonfigurasi oleh OpenClaw, seperti Pi tertanam dan adaptor runtime
lainnya. OpenClaw menyimpan definisi secara terpusat agar runtime tersebut tidak
perlu menyimpan daftar server MCP duplikat mereka sendiri.
Perilaku penting:
- perintah-perintah ini hanya membaca atau menulis konfigurasi OpenClaw
- perintah-perintah ini tidak terhubung ke server MCP target
- perintah-perintah ini tidak memvalidasi apakah perintah, URL, atau transport
jarak jauh dapat dijangkau saat ini
- adaptor runtime memutuskan bentuk transport mana yang benar-benar didukung
pada waktu eksekusi
## Definisi server MCP tersimpan
OpenClaw juga menyimpan registri server MCP ringan dalam konfigurasi untuk
permukaan yang menginginkan definisi MCP yang dikelola OpenClaw.
Perintah:
- `openclaw mcp list`
- `openclaw mcp show [name]`
- `openclaw mcp set <name> <json>`
- `openclaw mcp unset <name>`
Catatan:
- `list` mengurutkan nama server.
- `show` tanpa nama mencetak objek server MCP terkonfigurasi lengkap.
- `set` mengharapkan satu nilai objek JSON pada command line.
- `unset` gagal jika server bernama tersebut tidak ada.
Contoh:
```bash
openclaw mcp list
openclaw mcp show context7 --json
openclaw mcp set context7 '{"command":"uvx","args":["context7-mcp"]}'
openclaw mcp set docs '{"url":"https://mcp.example.com"}'
openclaw mcp unset context7
```
Contoh bentuk konfigurasi:
```json
{
"mcp": {
"servers": {
"context7": {
"command": "uvx",
"args": ["context7-mcp"]
},
"docs": {
"url": "https://mcp.example.com"
}
}
}
}
```
### Transport stdio
Meluncurkan proses child lokal dan berkomunikasi melalui stdin/stdout.
| Field | Deskripsi |
| -------------------------- | ----------------------------------- |
| `command` | Executable yang akan dimunculkan (wajib) |
| `args` | Array argumen command line |
| `env` | Variabel lingkungan tambahan |
| `cwd` / `workingDirectory` | Direktori kerja untuk proses |
### Transport SSE / HTTP
Terhubung ke server MCP jarak jauh melalui HTTP Server-Sent Events.
| Field | Deskripsi |
| --------------------- | ------------------------------------------------------------------- |
| `url` | URL HTTP atau HTTPS server jarak jauh (wajib) |
| `headers` | Peta key-value header HTTP opsional (misalnya token auth) |
| `connectionTimeoutMs` | Batas waktu koneksi per server dalam ms (opsional) |
Contoh:
```json
{
"mcp": {
"servers": {
"remote-tools": {
"url": "https://mcp.example.com",
"headers": {
"Authorization": "Bearer <token>"
}
}
}
}
}
```
Nilai sensitif di `url` (userinfo) dan `headers` disamarkan dalam log dan
output status.
### Transport Streamable HTTP
`streamable-http` adalah opsi transport tambahan di samping `sse` dan `stdio`.
Transport ini menggunakan streaming HTTP untuk komunikasi dua arah dengan server
MCP jarak jauh.
| Field | Deskripsi |
| --------------------- | ------------------------------------------------------------------------------------- |
| `url` | URL HTTP atau HTTPS server jarak jauh (wajib) |
| `transport` | Setel ke `"streamable-http"` untuk memilih transport ini; jika dihilangkan, OpenClaw menggunakan `sse` |
| `headers` | Peta key-value header HTTP opsional (misalnya token auth) |
| `connectionTimeoutMs` | Batas waktu koneksi per server dalam ms (opsional) |
Contoh:
```json
{
"mcp": {
"servers": {
"streaming-tools": {
"url": "https://mcp.example.com/stream",
"transport": "streamable-http",
"connectionTimeoutMs": 10000,
"headers": {
"Authorization": "Bearer <token>"
}
}
}
}
}
```
Perintah-perintah ini hanya mengelola konfigurasi yang disimpan. Perintah-
perintah ini tidak memulai bridge saluran, membuka sesi klien MCP langsung, atau
membuktikan bahwa server target dapat dijangkau.
## Batasan saat ini
Halaman ini mendokumentasikan bridge sebagaimana dikirim saat ini.
Batasan saat ini:
- penemuan percakapan bergantung pada metadata rute sesi Gateway yang sudah ada
- belum ada protokol push generik selain adaptor khusus Claude
- belum ada alat edit pesan atau react
- transport HTTP/SSE/streamable-http terhubung ke satu server jarak jauh; belum
ada upstream multipleks
- `permissions_list_open` hanya mencakup persetujuan yang diamati saat bridge
terhubung

142
docs/id/cli/memory.md Normal file
View File

@ -0,0 +1,142 @@
---
read_when:
- Anda ingin mengindeks atau menelusuri memori semantik
- Anda sedang men-debug ketersediaan memori atau pengindeksan
- Anda ingin mempromosikan memori jangka pendek yang dipanggil kembali ke `MEMORY.md`
summary: Referensi CLI untuk `openclaw memory` (status/index/search/promote)
title: memory
x-i18n:
generated_at: "2026-04-05T13:49:06Z"
model: gpt-5.4
provider: openai
source_hash: a89e3a819737bb63521128ae63d9e25b5cd9db35c3ea4606d087a8ad48b41eab
source_path: cli/memory.md
workflow: 15
---
# `openclaw memory`
Kelola pengindeksan dan penelusuran memori semantik.
Disediakan oleh plugin memori aktif (default: `memory-core`; setel `plugins.slots.memory = "none"` untuk menonaktifkan).
Terkait:
- Konsep Memory: [Memory](/concepts/memory)
- Plugins: [Plugins](/tools/plugin)
## Contoh
```bash
openclaw memory status
openclaw memory status --deep
openclaw memory status --fix
openclaw memory index --force
openclaw memory search "meeting notes"
openclaw memory search --query "deployment" --max-results 20
openclaw memory promote --limit 10 --min-score 0.75
openclaw memory promote --apply
openclaw memory promote --json --min-recall-count 0 --min-unique-queries 0
openclaw memory status --json
openclaw memory status --deep --index
openclaw memory status --deep --index --verbose
openclaw memory status --agent main
openclaw memory index --agent main --verbose
```
## Opsi
`memory status` dan `memory index`:
- `--agent <id>`: cakup ke satu agen. Tanpanya, perintah ini berjalan untuk setiap agen yang dikonfigurasi; jika tidak ada daftar agen yang dikonfigurasi, perintah ini kembali ke agen default.
- `--verbose`: keluarkan log terperinci selama probe dan pengindeksan.
`memory status`:
- `--deep`: periksa ketersediaan vector + embedding.
- `--index`: jalankan pengindeksan ulang jika penyimpanan kotor (mengimplikasikan `--deep`).
- `--fix`: perbaiki kunci recall yang usang dan normalkan metadata promosi.
- `--json`: cetak output JSON.
`memory index`:
- `--force`: paksa pengindeksan ulang penuh.
`memory search`:
- Input kueri: berikan `[query]` posisional atau `--query <text>`.
- Jika keduanya diberikan, `--query` akan digunakan.
- Jika tidak satu pun diberikan, perintah keluar dengan error.
- `--agent <id>`: cakup ke satu agen (default: agen default).
- `--max-results <n>`: batasi jumlah hasil yang dikembalikan.
- `--min-score <n>`: saring kecocokan dengan skor rendah.
- `--json`: cetak hasil JSON.
`memory promote`:
Pratinjau dan terapkan promosi memori jangka pendek.
```bash
openclaw memory promote [--apply] [--limit <n>] [--include-promoted]
```
- `--apply` -- tulis promosi ke `MEMORY.md` (default: pratinjau saja).
- `--limit <n>` -- batasi jumlah kandidat yang ditampilkan.
- `--include-promoted` -- sertakan entri yang sudah dipromosikan pada siklus sebelumnya.
Opsi lengkap:
- Memberi peringkat kandidat jangka pendek dari `memory/YYYY-MM-DD.md` menggunakan sinyal recall berbobot (`frequency`, `relevance`, `query diversity`, `recency`).
- Menggunakan peristiwa recall yang ditangkap saat `memory_search` mengembalikan hit memori harian.
- Mode auto-dreaming opsional: saat `plugins.entries.memory-core.config.dreaming.mode` adalah `core`, `deep`, atau `rem`, `memory-core` mengelola otomatis sebuah cron job yang memicu promosi di latar belakang (tidak perlu `openclaw cron add` manual).
- `--agent <id>`: cakup ke satu agen (default: agen default).
- `--limit <n>`: jumlah maksimum kandidat yang dikembalikan/diterapkan.
- `--min-score <n>`: skor promosi berbobot minimum.
- `--min-recall-count <n>`: jumlah recall minimum yang diperlukan untuk kandidat.
- `--min-unique-queries <n>`: jumlah kueri berbeda minimum yang diperlukan untuk kandidat.
- `--apply`: tambahkan kandidat yang dipilih ke `MEMORY.md` dan tandai sebagai sudah dipromosikan.
- `--include-promoted`: sertakan kandidat yang sudah dipromosikan dalam output.
- `--json`: cetak output JSON.
## Dreaming (eksperimental)
Dreaming adalah proses refleksi semalam untuk memory. Disebut "dreaming" karena sistem meninjau kembali apa yang dipanggil kembali sepanjang hari dan memutuskan apa yang layak disimpan untuk jangka panjang.
- Ini bersifat opt-in dan dinonaktifkan secara default.
- Aktifkan dengan `plugins.entries.memory-core.config.dreaming.mode`.
- Anda dapat mengganti mode dari chat dengan `/dreaming off|core|rem|deep`. Jalankan `/dreaming` (atau `/dreaming options`) untuk melihat fungsi masing-masing mode.
- Saat diaktifkan, `memory-core` secara otomatis membuat dan memelihara cron job terkelola.
- Setel `dreaming.limit` ke `0` jika Anda ingin dreaming diaktifkan tetapi promosi otomatis secara efektif dijeda.
- Pemeringkatan menggunakan sinyal berbobot: frekuensi recall, relevansi pengambilan, keragaman kueri, dan recency temporal (recall terbaru meluruh seiring waktu).
- Promosi ke `MEMORY.md` hanya terjadi saat ambang kualitas terpenuhi, sehingga memori jangka panjang tetap bernilai tinggi alih-alih mengumpulkan detail sekali pakai.
Preset mode default:
- `core`: setiap hari pada `0 3 * * *`, `minScore=0.75`, `minRecallCount=3`, `minUniqueQueries=2`
- `deep`: setiap 12 jam (`0 */12 * * *`), `minScore=0.8`, `minRecallCount=3`, `minUniqueQueries=3`
- `rem`: setiap 6 jam (`0 */6 * * *`), `minScore=0.85`, `minRecallCount=4`, `minUniqueQueries=3`
Contoh:
```json
{
"plugins": {
"entries": {
"memory-core": {
"config": {
"dreaming": {
"mode": "core"
}
}
}
}
}
}
```
Catatan:
- `memory index --verbose` mencetak detail per fase (provider, model, sumber, aktivitas batch).
- `memory status` menyertakan jalur tambahan apa pun yang dikonfigurasi melalui `memorySearch.extraPaths`.
- Jika field kunci API jarak jauh memory yang aktif secara efektif dikonfigurasi sebagai SecretRef, perintah akan menyelesaikan nilai tersebut dari snapshot gateway aktif. Jika gateway tidak tersedia, perintah gagal dengan cepat.
- Catatan ketidaksesuaian versi gateway: jalur perintah ini memerlukan gateway yang mendukung `secrets.resolve`; gateway yang lebih lama mengembalikan error unknown-method.
- Cadence dreaming secara default mengikuti jadwal preset tiap mode. Ganti cadence dengan `plugins.entries.memory-core.config.dreaming.frequency` sebagai ekspresi cron (misalnya `0 3 * * *`) dan sesuaikan lebih lanjut dengan `timezone`, `limit`, `minScore`, `minRecallCount`, dan `minUniqueQueries`.

307
docs/id/cli/message.md Normal file
View File

@ -0,0 +1,307 @@
---
read_when:
- Menambahkan atau mengubah aksi CLI message
- Mengubah perilaku saluran keluar
summary: Referensi CLI untuk `openclaw message` (kirim + aksi saluran)
title: message
x-i18n:
generated_at: "2026-04-05T13:49:23Z"
model: gpt-5.4
provider: openai
source_hash: b70f36189d028d59db25cd8b39d7c67883eaea71bea2358ee6314eec6cd2fa51
source_path: cli/message.md
workflow: 15
---
# `openclaw message`
Perintah keluar tunggal untuk mengirim pesan dan aksi saluran
(Discord/Google Chat/iMessage/Matrix/Mattermost (plugin)/Microsoft Teams/Signal/Slack/Telegram/WhatsApp).
## Penggunaan
```
openclaw message <subcommand> [flags]
```
Pemilihan saluran:
- `--channel` wajib jika lebih dari satu saluran dikonfigurasi.
- Jika tepat satu saluran dikonfigurasi, saluran itu menjadi default.
- Nilai: `discord|googlechat|imessage|matrix|mattermost|msteams|signal|slack|telegram|whatsapp` (Mattermost memerlukan plugin)
Format target (`--target`):
- WhatsApp: E.164 atau JID grup
- Telegram: id chat atau `@username`
- Discord: `channel:<id>` atau `user:<id>` (atau mention `<@id>`; id numerik mentah diperlakukan sebagai saluran)
- Google Chat: `spaces/<spaceId>` atau `users/<userId>`
- Slack: `channel:<id>` atau `user:<id>` (id saluran mentah diterima)
- Mattermost (plugin): `channel:<id>`, `user:<id>`, atau `@username` (id polos diperlakukan sebagai saluran)
- Signal: `+E.164`, `group:<id>`, `signal:+E.164`, `signal:group:<id>`, atau `username:<name>`/`u:<name>`
- iMessage: handle, `chat_id:<id>`, `chat_guid:<guid>`, atau `chat_identifier:<id>`
- Matrix: `@user:server`, `!room:server`, atau `#alias:server`
- Microsoft Teams: id percakapan (`19:...@thread.tacv2`) atau `conversation:<id>` atau `user:<aad-object-id>`
Pencarian nama:
- Untuk provider yang didukung (Discord/Slack/dll), nama saluran seperti `Help` atau `#help` diselesaikan melalui cache direktori.
- Saat cache miss, OpenClaw akan mencoba pencarian direktori langsung jika provider mendukungnya.
## Flag umum
- `--channel <name>`
- `--account <id>`
- `--target <dest>` (saluran target atau pengguna untuk kirim/poll/baca/dll)
- `--targets <name>` (ulangi; hanya siaran)
- `--json`
- `--dry-run`
- `--verbose`
## Perilaku SecretRef
- `openclaw message` menyelesaikan SecretRef saluran yang didukung sebelum menjalankan aksi yang dipilih.
- Penyelesaian dibatasi ke target aksi aktif bila memungkinkan:
- cakupan saluran saat `--channel` diatur (atau disimpulkan dari target berawalan seperti `discord:...`)
- cakupan akun saat `--account` diatur (global saluran + permukaan akun yang dipilih)
- saat `--account` dihilangkan, OpenClaw tidak memaksakan cakupan SecretRef akun `default`
- SecretRef yang tidak terselesaikan pada saluran yang tidak terkait tidak memblokir aksi message yang ditargetkan.
- Jika SecretRef saluran/akun yang dipilih tidak terselesaikan, perintah gagal tertutup untuk aksi tersebut.
## Aksi
### Inti
- `send`
- Saluran: WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (plugin)/Signal/iMessage/Matrix/Microsoft Teams
- Wajib: `--target`, ditambah `--message` atau `--media`
- Opsional: `--media`, `--interactive`, `--buttons`, `--components`, `--card`, `--reply-to`, `--thread-id`, `--gif-playback`, `--force-document`, `--silent`
- Payload interaktif bersama: `--interactive` mengirim payload JSON interaktif native saluran jika didukung
- Khusus Telegram: `--buttons` (memerlukan `channels.telegram.capabilities.inlineButtons` agar mengizinkannya)
- Khusus Telegram: `--force-document` (kirim gambar dan GIF sebagai dokumen untuk menghindari kompresi Telegram)
- Khusus Telegram: `--thread-id` (id topik forum)
- Khusus Slack: `--thread-id` (timestamp thread; `--reply-to` menggunakan field yang sama)
- Khusus Discord: payload JSON `--components`
- Saluran Adaptive Card: payload JSON `--card` jika didukung
- Telegram + Discord: `--silent`
- Khusus WhatsApp: `--gif-playback`
- `poll`
- Saluran: WhatsApp/Telegram/Discord/Matrix/Microsoft Teams
- Wajib: `--target`, `--poll-question`, `--poll-option` (ulangi)
- Opsional: `--poll-multi`
- Khusus Discord: `--poll-duration-hours`, `--silent`, `--message`
- Khusus Telegram: `--poll-duration-seconds` (5-600), `--silent`, `--poll-anonymous` / `--poll-public`, `--thread-id`
- `react`
- Saluran: Discord/Google Chat/Slack/Telegram/WhatsApp/Signal/Matrix
- Wajib: `--message-id`, `--target`
- Opsional: `--emoji`, `--remove`, `--participant`, `--from-me`, `--target-author`, `--target-author-uuid`
- Catatan: `--remove` memerlukan `--emoji` (hilangkan `--emoji` untuk menghapus reaksi sendiri jika didukung; lihat /tools/reactions)
- Khusus WhatsApp: `--participant`, `--from-me`
- Reaksi grup Signal: `--target-author` atau `--target-author-uuid` wajib
- `reactions`
- Saluran: Discord/Google Chat/Slack/Matrix
- Wajib: `--message-id`, `--target`
- Opsional: `--limit`
- `read`
- Saluran: Discord/Slack/Matrix
- Wajib: `--target`
- Opsional: `--limit`, `--before`, `--after`
- Khusus Discord: `--around`
- `edit`
- Saluran: Discord/Slack/Matrix
- Wajib: `--message-id`, `--message`, `--target`
- `delete`
- Saluran: Discord/Slack/Telegram/Matrix
- Wajib: `--message-id`, `--target`
- `pin` / `unpin`
- Saluran: Discord/Slack/Matrix
- Wajib: `--message-id`, `--target`
- `pins` (daftar)
- Saluran: Discord/Slack/Matrix
- Wajib: `--target`
- `permissions`
- Saluran: Discord/Matrix
- Wajib: `--target`
- Khusus Matrix: tersedia saat enkripsi Matrix diaktifkan dan aksi verifikasi diizinkan
- `search`
- Saluran: Discord
- Wajib: `--guild-id`, `--query`
- Opsional: `--channel-id`, `--channel-ids` (ulangi), `--author-id`, `--author-ids` (ulangi), `--limit`
### Thread
- `thread create`
- Saluran: Discord
- Wajib: `--thread-name`, `--target` (id saluran)
- Opsional: `--message-id`, `--message`, `--auto-archive-min`
- `thread list`
- Saluran: Discord
- Wajib: `--guild-id`
- Opsional: `--channel-id`, `--include-archived`, `--before`, `--limit`
- `thread reply`
- Saluran: Discord
- Wajib: `--target` (id thread), `--message`
- Opsional: `--media`, `--reply-to`
### Emoji
- `emoji list`
- Discord: `--guild-id`
- Slack: tidak ada flag tambahan
- `emoji upload`
- Saluran: Discord
- Wajib: `--guild-id`, `--emoji-name`, `--media`
- Opsional: `--role-ids` (ulangi)
### Stiker
- `sticker send`
- Saluran: Discord
- Wajib: `--target`, `--sticker-id` (ulangi)
- Opsional: `--message`
- `sticker upload`
- Saluran: Discord
- Wajib: `--guild-id`, `--sticker-name`, `--sticker-desc`, `--sticker-tags`, `--media`
### Role / Saluran / Anggota / Suara
- `role info` (Discord): `--guild-id`
- `role add` / `role remove` (Discord): `--guild-id`, `--user-id`, `--role-id`
- `channel info` (Discord): `--target`
- `channel list` (Discord): `--guild-id`
- `member info` (Discord/Slack): `--user-id` (+ `--guild-id` untuk Discord)
- `voice status` (Discord): `--guild-id`, `--user-id`
### Event
- `event list` (Discord): `--guild-id`
- `event create` (Discord): `--guild-id`, `--event-name`, `--start-time`
- Opsional: `--end-time`, `--desc`, `--channel-id`, `--location`, `--event-type`
### Moderasi (Discord)
- `timeout`: `--guild-id`, `--user-id` (opsional `--duration-min` atau `--until`; hilangkan keduanya untuk menghapus timeout)
- `kick`: `--guild-id`, `--user-id` (+ `--reason`)
- `ban`: `--guild-id`, `--user-id` (+ `--delete-days`, `--reason`)
- `timeout` juga mendukung `--reason`
### Siaran
- `broadcast`
- Saluran: saluran terkonfigurasi apa pun; gunakan `--channel all` untuk menargetkan semua provider
- Wajib: `--targets <target...>`
- Opsional: `--message`, `--media`, `--dry-run`
## Contoh
Kirim balasan Discord:
```
openclaw message send --channel discord \
--target channel:123 --message "hi" --reply-to 456
```
Kirim pesan Discord dengan komponen:
```
openclaw message send --channel discord \
--target channel:123 --message "Choose:" \
--components '{"text":"Choose a path","blocks":[{"type":"actions","buttons":[{"label":"Approve","style":"success"},{"label":"Decline","style":"danger"}]}]}'
```
Lihat [Komponen Discord](/id/channels/discord#interactive-components) untuk skema lengkapnya.
Kirim payload interaktif bersama:
```bash
openclaw message send --channel googlechat --target spaces/AAA... \
--message "Choose:" \
--interactive '{"text":"Choose a path","blocks":[{"type":"actions","buttons":[{"label":"Approve"},{"label":"Decline"}]}]}'
```
Buat poll Discord:
```
openclaw message poll --channel discord \
--target channel:123 \
--poll-question "Snack?" \
--poll-option Pizza --poll-option Sushi \
--poll-multi --poll-duration-hours 48
```
Buat poll Telegram (tutup otomatis dalam 2 menit):
```
openclaw message poll --channel telegram \
--target @mychat \
--poll-question "Lunch?" \
--poll-option Pizza --poll-option Sushi \
--poll-duration-seconds 120 --silent
```
Kirim pesan proaktif Teams:
```
openclaw message send --channel msteams \
--target conversation:19:abc@thread.tacv2 --message "hi"
```
Buat poll Teams:
```
openclaw message poll --channel msteams \
--target conversation:19:abc@thread.tacv2 \
--poll-question "Lunch?" \
--poll-option Pizza --poll-option Sushi
```
Beri reaksi di Slack:
```
openclaw message react --channel slack \
--target C123 --message-id 456 --emoji "✅"
```
Beri reaksi di grup Signal:
```
openclaw message react --channel signal \
--target signal:group:abc123 --message-id 1737630212345 \
--emoji "✅" --target-author-uuid 123e4567-e89b-12d3-a456-426614174000
```
Kirim tombol inline Telegram:
```
openclaw message send --channel telegram --target @mychat --message "Choose:" \
--buttons '[ [{"text":"Yes","callback_data":"cmd:yes"}], [{"text":"No","callback_data":"cmd:no"}] ]'
```
Kirim Adaptive Card Teams:
```bash
openclaw message send --channel msteams \
--target conversation:19:abc@thread.tacv2 \
--card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Status update"}]}'
```
Kirim gambar Telegram sebagai dokumen untuk menghindari kompresi:
```bash
openclaw message send --channel telegram --target @mychat \
--media ./diagram.png --force-document
```

142
docs/id/cli/models.md Normal file
View File

@ -0,0 +1,142 @@
---
read_when:
- Anda ingin mengubah model default atau melihat status auth penyedia
- Anda ingin memindai model/penyedia yang tersedia dan men-debug profil auth
summary: Referensi CLI untuk `openclaw models` (status/list/set/scan, alias, fallback, auth)
title: models
x-i18n:
generated_at: "2026-04-05T13:49:08Z"
model: gpt-5.4
provider: openai
source_hash: 04ba33181d49b6bbf3b5d5fa413aa6b388c9f29fb9d4952055d68c79f7bcfea0
source_path: cli/models.md
workflow: 15
---
# `openclaw models`
Penemuan model, pemindaian, dan konfigurasi (model default, fallback, profil auth).
Terkait:
- Penyedia + model: [Models](/providers/models)
- Penyiapan auth penyedia: [Memulai](/start/getting-started)
## Perintah umum
```bash
openclaw models status
openclaw models list
openclaw models set <model-or-alias>
openclaw models scan
```
`openclaw models status` menampilkan default/fallback yang terselesaikan beserta ringkasan auth.
Saat snapshot penggunaan penyedia tersedia, bagian status OAuth/API-key mencakup
jendela penggunaan penyedia dan snapshot kuota.
Penyedia jendela penggunaan saat ini: Anthropic, GitHub Copilot, Gemini CLI, OpenAI
Codex, MiniMax, Xiaomi, dan z.ai. Auth penggunaan berasal dari hook khusus penyedia
saat tersedia; jika tidak, OpenClaw menggunakan fallback dengan mencocokkan
kredensial OAuth/API-key dari profil auth, env, atau config.
Tambahkan `--probe` untuk menjalankan probe auth langsung terhadap setiap profil penyedia yang dikonfigurasi.
Probe adalah permintaan nyata (dapat mengonsumsi token dan memicu batas laju).
Gunakan `--agent <id>` untuk memeriksa status model/auth agen yang dikonfigurasi. Jika dihilangkan,
perintah menggunakan `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR` jika disetel, jika tidak maka
agen default yang dikonfigurasi akan digunakan.
Baris probe dapat berasal dari profil auth, kredensial env, atau `models.json`.
Catatan:
- `models set <model-or-alias>` menerima `provider/model` atau alias.
- Ref model diurai dengan memisahkan pada `/` **pertama**. Jika ID model menyertakan `/` (gaya OpenRouter), sertakan awalan penyedia (contoh: `openrouter/moonshotai/kimi-k2`).
- Jika Anda menghilangkan penyedia, OpenClaw terlebih dahulu menyelesaikan input sebagai alias, lalu
sebagai kecocokan penyedia-terkonfigurasi unik untuk ID model yang persis itu, dan hanya setelah itu
menggunakan fallback ke penyedia default yang dikonfigurasi dengan peringatan deprecation.
Jika penyedia tersebut tidak lagi mengekspos model default yang dikonfigurasi, OpenClaw
menggunakan fallback ke penyedia/model terkonfigurasi pertama alih-alih menampilkan
default penyedia-terhapus lama.
- `models status` dapat menampilkan `marker(<value>)` dalam output auth untuk placeholder non-rahasia (misalnya `OPENAI_API_KEY`, `secretref-managed`, `minimax-oauth`, `oauth:chutes`, `ollama-local`) alih-alih menyamarkannya sebagai rahasia.
### `models status`
Opsi:
- `--json`
- `--plain`
- `--check` (keluar 1=kedaluwarsa/hilang, 2=akan kedaluwarsa)
- `--probe` (probe langsung dari profil auth yang dikonfigurasi)
- `--probe-provider <name>` (probe satu penyedia)
- `--probe-profile <id>` (ID profil berulang atau dipisahkan koma)
- `--probe-timeout <ms>`
- `--probe-concurrency <n>`
- `--probe-max-tokens <n>`
- `--agent <id>` (ID agen yang dikonfigurasi; menggantikan `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`)
Kelompok status probe:
- `ok`
- `auth`
- `rate_limit`
- `billing`
- `timeout`
- `format`
- `unknown`
- `no_model`
Kasus detail/kode alasan probe yang perlu diharapkan:
- `excluded_by_auth_order`: profil tersimpan ada, tetapi
`auth.order.<provider>` yang eksplisit mengabaikannya, sehingga probe melaporkan pengecualian itu alih-alih
mencobanya.
- `missing_credential`, `invalid_expires`, `expired`, `unresolved_ref`:
profil ada tetapi tidak memenuhi syarat/tidak dapat diselesaikan.
- `no_model`: auth penyedia ada, tetapi OpenClaw tidak dapat menyelesaikan
kandidat model yang dapat diprobe untuk penyedia tersebut.
## Alias + fallback
```bash
openclaw models aliases list
openclaw models fallbacks list
```
## Profil auth
```bash
openclaw models auth add
openclaw models auth login --provider <id>
openclaw models auth setup-token --provider <id>
openclaw models auth paste-token
```
`models auth add` adalah pembantu auth interaktif. Perintah ini dapat meluncurkan alur auth penyedia
(OAuth/API key) atau memandu Anda ke penempelan token manual, tergantung pada
penyedia yang Anda pilih.
`models auth login` menjalankan alur auth plugin penyedia (OAuth/API key). Gunakan
`openclaw plugins list` untuk melihat penyedia mana yang terpasang.
Contoh:
```bash
openclaw models auth login --provider anthropic --method cli --set-default
openclaw models auth login --provider openai-codex --set-default
```
Catatan:
- `login --provider anthropic --method cli --set-default` menggunakan kembali login Claude
CLI lokal dan menulis ulang jalur model default Anthropic utama ke ref
`claude-cli/claude-*` kanonis.
- `setup-token` dan `paste-token` tetap menjadi perintah token generik untuk penyedia
yang mengekspos metode auth token.
- `setup-token` memerlukan TTY interaktif dan menjalankan metode auth-token penyedia
(secara default menggunakan metode `setup-token` penyedia tersebut saat tersedia).
- `paste-token` menerima string token yang dihasilkan di tempat lain atau dari otomatisasi.
- `paste-token` memerlukan `--provider`, meminta nilai token, dan menulisnya
ke ID profil default `<provider>:manual` kecuali Anda memberikan
`--profile-id`.
- `paste-token --expires-in <duration>` menyimpan masa kedaluwarsa token absolut dari
durasi relatif seperti `365d` atau `12h`.
- Catatan billing Anthropic: Kami meyakini fallback Claude Code CLI kemungkinan diizinkan untuk otomatisasi lokal yang dikelola pengguna berdasarkan dokumentasi CLI publik Anthropic. Meski demikian, kebijakan harness pihak ketiga Anthropic menimbulkan ambiguitas yang cukup besar terkait penggunaan berbasis langganan dalam produk eksternal sehingga kami tidak merekomendasikannya untuk produksi. Anthropic juga memberi tahu pengguna OpenClaw pada **4 April 2026 pukul 12:00 PM PT / 8:00 PM BST** bahwa jalur login Claude milik **OpenClaw** dihitung sebagai penggunaan harness pihak ketiga dan memerlukan **Extra Usage** yang ditagihkan terpisah dari langganan.
- Anthropic `setup-token` / `paste-token` kini tersedia lagi sebagai jalur OpenClaw lama/manual. Gunakan dengan pemahaman bahwa Anthropic memberi tahu pengguna OpenClaw bahwa jalur ini memerlukan **Extra Usage**.

144
docs/id/cli/node.md Normal file
View File

@ -0,0 +1,144 @@
---
read_when:
- Menjalankan host node headless
- Memasangkan node non-macOS untuk system.run
summary: Referensi CLI untuk `openclaw node` (host node headless)
title: node
x-i18n:
generated_at: "2026-04-05T13:49:20Z"
model: gpt-5.4
provider: openai
source_hash: 6123b33ec46f2b85f2c815947435ac91bbe84456165ff0e504453356da55b46d
source_path: cli/node.md
workflow: 15
---
# `openclaw node`
Jalankan **host node headless** yang terhubung ke Gateway WebSocket dan mengekspos
`system.run` / `system.which` di mesin ini.
## Mengapa menggunakan host node?
Gunakan host node ketika Anda ingin agen **menjalankan perintah di mesin lain** dalam
jaringan Anda tanpa memasang aplikasi pendamping macOS lengkap di sana.
Kasus penggunaan umum:
- Menjalankan perintah di mesin Linux/Windows jarak jauh (server build, mesin lab, NAS).
- Menjaga exec tetap **dalam sandbox** di gateway, tetapi mendelegasikan eksekusi yang disetujui ke host lain.
- Menyediakan target eksekusi yang ringan dan headless untuk otomasi atau node CI.
Eksekusi tetap dijaga oleh **persetujuan exec** dan allowlist per agen pada
host node, sehingga Anda dapat menjaga akses perintah tetap terbatas dan eksplisit.
## Browser proxy (konfigurasi nol)
Host node secara otomatis mengiklankan browser proxy jika `browser.enabled` tidak
dinonaktifkan pada node. Ini memungkinkan agen menggunakan otomasi browser pada node tersebut
tanpa konfigurasi tambahan.
Secara default, proxy mengekspos permukaan profil browser normal milik node. Jika Anda
menyetel `nodeHost.browserProxy.allowProfiles`, proxy menjadi restriktif:
penargetan profil yang tidak ada dalam allowlist akan ditolak, dan rute
pembuatan/penghapusan profil persisten diblokir melalui proxy.
Nonaktifkan pada node jika diperlukan:
```json5
{
nodeHost: {
browserProxy: {
enabled: false,
},
},
}
```
## Jalankan (foreground)
```bash
openclaw node run --host <gateway-host> --port 18789
```
Opsi:
- `--host <host>`: host Gateway WebSocket (default: `127.0.0.1`)
- `--port <port>`: port Gateway WebSocket (default: `18789`)
- `--tls`: gunakan TLS untuk koneksi gateway
- `--tls-fingerprint <sha256>`: fingerprint sertifikat TLS yang diharapkan (sha256)
- `--node-id <id>`: timpa id node (menghapus pairing token)
- `--display-name <name>`: timpa nama tampilan node
## Auth gateway untuk host node
`openclaw node run` dan `openclaw node install` menyelesaikan auth gateway dari config/env (tanpa flag `--token`/`--password` pada perintah node):
- `OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD` diperiksa terlebih dahulu.
- Lalu fallback config lokal: `gateway.auth.token` / `gateway.auth.password`.
- Dalam mode lokal, host node secara sengaja tidak mewarisi `gateway.remote.token` / `gateway.remote.password`.
- Jika `gateway.auth.token` / `gateway.auth.password` secara eksplisit dikonfigurasi melalui SecretRef dan tidak terselesaikan, resolusi auth node gagal secara tertutup (tanpa fallback jarak jauh yang menutupi masalah).
- Dalam `gateway.mode=remote`, field klien jarak jauh (`gateway.remote.token` / `gateway.remote.password`) juga memenuhi syarat sesuai aturan prioritas remote.
- Resolusi auth host node hanya menghormati env var `OPENCLAW_GATEWAY_*`.
## Layanan (background)
Pasang host node headless sebagai layanan pengguna.
```bash
openclaw node install --host <gateway-host> --port 18789
```
Opsi:
- `--host <host>`: host Gateway WebSocket (default: `127.0.0.1`)
- `--port <port>`: port Gateway WebSocket (default: `18789`)
- `--tls`: gunakan TLS untuk koneksi gateway
- `--tls-fingerprint <sha256>`: fingerprint sertifikat TLS yang diharapkan (sha256)
- `--node-id <id>`: timpa id node (menghapus pairing token)
- `--display-name <name>`: timpa nama tampilan node
- `--runtime <runtime>`: runtime layanan (`node` atau `bun`)
- `--force`: pasang ulang/timpa jika sudah terpasang
Kelola layanan:
```bash
openclaw node status
openclaw node stop
openclaw node restart
openclaw node uninstall
```
Gunakan `openclaw node run` untuk host node foreground (tanpa layanan).
Perintah layanan menerima `--json` untuk output yang dapat dibaca mesin.
## Pairing
Koneksi pertama membuat permintaan pairing perangkat tertunda (`role: node`) pada Gateway.
Setujui melalui:
```bash
openclaw devices list
openclaw devices approve <requestId>
```
Jika node mencoba pairing ulang dengan detail auth yang berubah (role/scope/public key),
permintaan tertunda sebelumnya digantikan dan `requestId` baru dibuat.
Jalankan `openclaw devices list` lagi sebelum menyetujui.
Host node menyimpan id node, token, nama tampilan, dan info koneksi gateway di
`~/.openclaw/node.json`.
## Persetujuan exec
`system.run` dikendalikan oleh persetujuan exec lokal:
- `~/.openclaw/exec-approvals.json`
- [Persetujuan exec](/tools/exec-approvals)
- `openclaw approvals --node <id|name|ip>` (edit dari Gateway)
Untuk exec node async yang disetujui, OpenClaw menyiapkan `systemRunPlan` kanonis
sebelum meminta persetujuan. Forward `system.run` yang kemudian disetujui menggunakan kembali
rencana tersimpan tersebut, sehingga edit pada field command/cwd/session setelah permintaan persetujuan
dibuat akan ditolak alih-alih mengubah apa yang dieksekusi node.

73
docs/id/cli/nodes.md Normal file
View File

@ -0,0 +1,73 @@
---
read_when:
- Anda sedang mengelola node berpasangan (kamera, layar, canvas)
- Anda perlu menyetujui permintaan atau memanggil perintah node
summary: Referensi CLI untuk `openclaw nodes` (status, pairing, invoke, kamera/canvas/layar)
title: nodes
x-i18n:
generated_at: "2026-04-05T13:49:16Z"
model: gpt-5.4
provider: openai
source_hash: 1ce3095591c4623ad18e3eca8d8083e5c10266fbf94afea2d025f0ba8093a175
source_path: cli/nodes.md
workflow: 15
---
# `openclaw nodes`
Kelola node (perangkat) yang berpasangan dan panggil kapabilitas node.
Terkait:
- Gambaran umum node: [Nodes](/nodes)
- Kamera: [Camera nodes](/nodes/camera)
- Gambar: [Image nodes](/nodes/images)
Opsi umum:
- `--url`, `--token`, `--timeout`, `--json`
## Perintah umum
```bash
openclaw nodes list
openclaw nodes list --connected
openclaw nodes list --last-connected 24h
openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes reject <requestId>
openclaw nodes rename --node <id|name|ip> --name <displayName>
openclaw nodes status
openclaw nodes status --connected
openclaw nodes status --last-connected 24h
```
`nodes list` mencetak tabel tertunda/berpasangan. Baris berpasangan menyertakan usia koneksi terbaru (Last Connect).
Gunakan `--connected` untuk hanya menampilkan node yang sedang terhubung. Gunakan `--last-connected <duration>` untuk
memfilter node yang terhubung dalam suatu durasi (misalnya `24h`, `7d`).
Catatan persetujuan:
- `openclaw nodes pending` hanya memerlukan cakupan pairing.
- `openclaw nodes approve <requestId>` mewarisi persyaratan cakupan tambahan dari
permintaan tertunda:
- permintaan tanpa perintah: hanya pairing
- perintah node non-exec: pairing + write
- `system.run` / `system.run.prepare` / `system.which`: pairing + admin
## Invoke
```bash
openclaw nodes invoke --node <id|name|ip> --command <command> --params <json>
```
Flag invoke:
- `--params <json>`: string objek JSON (default `{}`).
- `--invoke-timeout <ms>`: batas waktu invoke node (default `15000`).
- `--idempotency-key <key>`: kunci idempotensi opsional.
- `system.run` dan `system.run.prepare` diblokir di sini; gunakan tool `exec` dengan `host=node` untuk eksekusi shell.
Untuk eksekusi shell pada node, gunakan tool `exec` dengan `host=node` alih-alih `openclaw nodes run`.
CLI `nodes` sekarang berfokus pada kapabilitas: RPC langsung melalui `nodes invoke`, ditambah pairing, kamera,
layar, lokasi, canvas, dan notifikasi.

178
docs/id/cli/onboard.md Normal file
View File

@ -0,0 +1,178 @@
---
read_when:
- Anda ingin penyiapan terpandu untuk gateway, workspace, auth, channel, dan Skills
summary: Referensi CLI untuk `openclaw onboard` (onboarding interaktif)
title: onboard
x-i18n:
generated_at: "2026-04-05T13:49:37Z"
model: gpt-5.4
provider: openai
source_hash: 6db61c8002c9e82e48ff44f72e176b58ad85fad5cb8434687455ed40add8cc2a
source_path: cli/onboard.md
workflow: 15
---
# `openclaw onboard`
Onboarding interaktif untuk penyiapan Gateway lokal atau jarak jauh.
## Panduan terkait
- Pusat onboarding CLI: [Onboarding (CLI)](/start/wizard)
- Gambaran umum onboarding: [Onboarding Overview](/start/onboarding-overview)
- Referensi onboarding CLI: [CLI Setup Reference](/start/wizard-cli-reference)
- Otomatisasi CLI: [CLI Automation](/start/wizard-cli-automation)
- Onboarding macOS: [Onboarding (macOS App)](/start/onboarding)
## Contoh
```bash
openclaw onboard
openclaw onboard --flow quickstart
openclaw onboard --flow manual
openclaw onboard --mode remote --remote-url wss://gateway-host:18789
```
Untuk target `ws://` jaringan privat plaintext (hanya jaringan tepercaya), setel
`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` dalam environment proses onboarding.
Penyedia kustom non-interaktif:
```bash
openclaw onboard --non-interactive \
--auth-choice custom-api-key \
--custom-base-url "https://llm.example.com/v1" \
--custom-model-id "foo-large" \
--custom-api-key "$CUSTOM_API_KEY" \
--secret-input-mode plaintext \
--custom-compatibility openai
```
`--custom-api-key` bersifat opsional dalam mode non-interaktif. Jika dihilangkan, onboarding memeriksa `CUSTOM_API_KEY`.
Ollama non-interaktif:
```bash
openclaw onboard --non-interactive \
--auth-choice ollama \
--custom-base-url "http://ollama-host:11434" \
--custom-model-id "qwen3.5:27b" \
--accept-risk
```
`--custom-base-url` default ke `http://127.0.0.1:11434`. `--custom-model-id` bersifat opsional; jika dihilangkan, onboarding menggunakan default yang disarankan Ollama. ID model cloud seperti `kimi-k2.5:cloud` juga berfungsi di sini.
Simpan key penyedia sebagai ref alih-alih plaintext:
```bash
openclaw onboard --non-interactive \
--auth-choice openai-api-key \
--secret-input-mode ref \
--accept-risk
```
Dengan `--secret-input-mode ref`, onboarding menulis ref berbasis env alih-alih nilai key plaintext.
Untuk penyedia berbasis auth-profile, ini menulis entri `keyRef`; untuk penyedia kustom, ini menulis `models.providers.<id>.apiKey` sebagai env ref (misalnya `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`).
Kontrak mode `ref` non-interaktif:
- Setel env var penyedia dalam environment proses onboarding (misalnya `OPENAI_API_KEY`).
- Jangan berikan flag key inline (misalnya `--openai-api-key`) kecuali env var tersebut juga disetel.
- Jika flag key inline diberikan tanpa env var yang diwajibkan, onboarding gagal cepat dengan panduan.
Opsi token gateway dalam mode non-interaktif:
- `--gateway-auth token --gateway-token <token>` menyimpan token plaintext.
- `--gateway-auth token --gateway-token-ref-env <name>` menyimpan `gateway.auth.token` sebagai env SecretRef.
- `--gateway-token` dan `--gateway-token-ref-env` saling eksklusif.
- `--gateway-token-ref-env` memerlukan env var yang tidak kosong dalam environment proses onboarding.
- Dengan `--install-daemon`, saat auth token memerlukan token, token gateway yang dikelola SecretRef divalidasi tetapi tidak dipersistenkan sebagai plaintext yang telah diselesaikan dalam metadata environment layanan supervisor.
- Dengan `--install-daemon`, jika mode token memerlukan token dan token SecretRef yang dikonfigurasi tidak terselesaikan, onboarding gagal tertutup dengan panduan remediasi.
- Dengan `--install-daemon`, jika `gateway.auth.token` dan `gateway.auth.password` keduanya dikonfigurasi dan `gateway.auth.mode` tidak disetel, onboarding memblokir instalasi sampai mode disetel secara eksplisit.
- Onboarding lokal menulis `gateway.mode="local"` ke dalam config. Jika file config berikutnya tidak memiliki `gateway.mode`, anggap itu sebagai kerusakan config atau edit manual yang tidak lengkap, bukan sebagai pintasan mode lokal yang valid.
- `--allow-unconfigured` adalah escape hatch runtime gateway yang terpisah. Ini tidak berarti onboarding boleh menghilangkan `gateway.mode`.
Contoh:
```bash
export OPENCLAW_GATEWAY_TOKEN="your-token"
openclaw onboard --non-interactive \
--mode local \
--auth-choice skip \
--gateway-auth token \
--gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN \
--accept-risk
```
Kesehatan gateway lokal non-interaktif:
- Kecuali Anda memberikan `--skip-health`, onboarding menunggu gateway lokal yang dapat dijangkau sebelum keluar dengan sukses.
- `--install-daemon` memulai jalur instalasi gateway terkelola terlebih dahulu. Tanpanya, Anda harus sudah memiliki gateway lokal yang berjalan, misalnya `openclaw gateway run`.
- Jika Anda hanya ingin penulisan config/workspace/bootstrap dalam otomatisasi, gunakan `--skip-health`.
- Di Windows native, `--install-daemon` mencoba Scheduled Tasks terlebih dahulu dan menggunakan fallback item login folder Startup per pengguna jika pembuatan task ditolak.
Perilaku onboarding interaktif dengan mode referensi:
- Pilih **Use secret reference** saat diminta.
- Lalu pilih salah satu:
- Environment variable
- Penyedia secret yang dikonfigurasi (`file` atau `exec`)
- Onboarding melakukan validasi preflight cepat sebelum menyimpan ref.
- Jika validasi gagal, onboarding menampilkan error dan memungkinkan Anda mencoba lagi.
Pilihan endpoint Z.AI non-interaktif:
Catatan: `--auth-choice zai-api-key` sekarang mendeteksi otomatis endpoint Z.AI terbaik untuk key Anda (lebih memilih API umum dengan `zai/glm-5`).
Jika Anda secara khusus menginginkan endpoint GLM Coding Plan, pilih `zai-coding-global` atau `zai-coding-cn`.
```bash
# Pemilihan endpoint tanpa prompt
openclaw onboard --non-interactive \
--auth-choice zai-coding-global \
--zai-api-key "$ZAI_API_KEY"
# Pilihan endpoint Z.AI lainnya:
# --auth-choice zai-coding-cn
# --auth-choice zai-global
# --auth-choice zai-cn
```
Contoh Mistral non-interaktif:
```bash
openclaw onboard --non-interactive \
--auth-choice mistral-api-key \
--mistral-api-key "$MISTRAL_API_KEY"
```
Catatan alur:
- `quickstart`: prompt minimal, otomatis membuat token gateway.
- `manual`: prompt lengkap untuk port/bind/auth (alias dari `advanced`).
- Saat pilihan auth menyiratkan penyedia yang diprioritaskan, onboarding memprefilter
pemilih model default dan allowlist ke penyedia tersebut. Untuk Volcengine dan
BytePlus, ini juga cocok dengan varian coding-plan
(`volcengine-plan/*`, `byteplus-plan/*`).
- Jika filter penyedia yang diprioritaskan belum menghasilkan model yang dimuat, onboarding
menggunakan fallback ke katalog tanpa filter alih-alih membiarkan pemilih kosong.
- Dalam langkah pencarian web, beberapa penyedia dapat memicu
prompt lanjutan khusus penyedia:
- **Grok** dapat menawarkan penyiapan `x_search` opsional dengan `XAI_API_KEY`
yang sama dan pilihan model `x_search`.
- **Kimi** dapat menanyakan region API Moonshot (`api.moonshot.ai` vs
`api.moonshot.cn`) dan model pencarian web Kimi default.
- Perilaku cakupan DM onboarding lokal: [CLI Setup Reference](/start/wizard-cli-reference#outputs-and-internals).
- Chat pertama tercepat: `openclaw dashboard` (UI Kontrol, tanpa penyiapan channel).
- Penyedia Kustom: sambungkan endpoint apa pun yang kompatibel dengan OpenAI atau Anthropic,
termasuk penyedia yang di-host yang tidak tercantum. Gunakan Unknown untuk deteksi otomatis.
## Perintah tindak lanjut umum
```bash
openclaw configure
openclaw agents add <name>
```
<Note>
`--json` tidak menyiratkan mode non-interaktif. Gunakan `--non-interactive` untuk skrip.
</Note>

72
docs/id/cli/pairing.md Normal file
View File

@ -0,0 +1,72 @@
---
read_when:
- Anda menggunakan DM mode pairing dan perlu menyetujui pengirim
summary: Referensi CLI untuk `openclaw pairing` (menyetujui/mendaftarkan permintaan pairing)
title: pairing
x-i18n:
generated_at: "2026-04-05T13:49:25Z"
model: gpt-5.4
provider: openai
source_hash: 122a608ef83ec2b1011fdfd1b59b94950a4dcc8b598335b0956e2eedece4958f
source_path: cli/pairing.md
workflow: 15
---
# `openclaw pairing`
Setujui atau periksa permintaan pairing DM (untuk channel yang mendukung pairing).
Terkait:
- Alur pairing: [Pairing](/id/channels/pairing)
## Perintah
```bash
openclaw pairing list telegram
openclaw pairing list --channel telegram --account work
openclaw pairing list telegram --json
openclaw pairing approve <code>
openclaw pairing approve telegram <code>
openclaw pairing approve --channel telegram --account work <code> --notify
```
## `pairing list`
Daftarkan permintaan pairing tertunda untuk satu channel.
Opsi:
- `[channel]`: ID channel posisional
- `--channel <channel>`: ID channel eksplisit
- `--account <accountId>`: ID akun untuk channel multi-akun
- `--json`: output yang dapat dibaca mesin
Catatan:
- Jika beberapa channel yang mendukung pairing dikonfigurasi, Anda harus memberikan channel baik secara posisional maupun dengan `--channel`.
- Channel plugin diizinkan selama ID channel valid.
## `pairing approve`
Setujui kode pairing yang tertunda dan izinkan pengirim tersebut.
Penggunaan:
- `openclaw pairing approve <channel> <code>`
- `openclaw pairing approve --channel <channel> <code>`
- `openclaw pairing approve <code>` ketika tepat satu channel yang mendukung pairing dikonfigurasi
Opsi:
- `--channel <channel>`: ID channel eksplisit
- `--account <accountId>`: ID akun untuk channel multi-akun
- `--notify`: kirim konfirmasi kembali ke peminta di channel yang sama
## Catatan
- Input channel: berikan secara posisional (`pairing list telegram`) atau dengan `--channel <channel>`.
- `pairing list` mendukung `--account <accountId>` untuk channel multi-akun.
- `pairing approve` mendukung `--account <accountId>` dan `--notify`.
- Jika hanya satu channel yang mendukung pairing dikonfigurasi, `pairing approve <code>` diperbolehkan.

304
docs/id/cli/plugins.md Normal file
View File

@ -0,0 +1,304 @@
---
read_when:
- Anda ingin menginstal atau mengelola plugin Gateway atau bundle yang kompatibel
- Anda ingin men-debug kegagalan pemuatan plugin
summary: Referensi CLI untuk `openclaw plugins` (list, install, marketplace, uninstall, enable/disable, doctor)
title: plugins
x-i18n:
generated_at: "2026-04-05T13:49:53Z"
model: gpt-5.4
provider: openai
source_hash: 8c35ccf68cd7be1af5fee175bd1ce7de88b81c625a05a23887e5780e790df925
source_path: cli/plugins.md
workflow: 15
---
# `openclaw plugins`
Kelola plugin/ekstensi Gateway, hook pack, dan bundle yang kompatibel.
Terkait:
- Sistem plugin: [Plugins](/tools/plugin)
- Kompatibilitas bundle: [Plugin bundles](/plugins/bundles)
- Manifest plugin + schema: [Plugin manifest](/plugins/manifest)
- Penguatan keamanan: [Security](/gateway/security)
## Perintah
```bash
openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
openclaw plugins install <path-or-spec>
openclaw plugins inspect <id>
openclaw plugins inspect <id> --json
openclaw plugins inspect --all
openclaw plugins info <id>
openclaw plugins enable <id>
openclaw plugins disable <id>
openclaw plugins uninstall <id>
openclaw plugins doctor
openclaw plugins update <id>
openclaw plugins update --all
openclaw plugins marketplace list <marketplace>
openclaw plugins marketplace list <marketplace> --json
```
Plugin bawaan dikirim bersama OpenClaw. Beberapa diaktifkan secara default (misalnya
provider model bawaan, provider speech bawaan, dan plugin browser
bawaan); yang lain memerlukan `plugins enable`.
Plugin OpenClaw native harus menyertakan `openclaw.plugin.json` dengan JSON
Schema inline (`configSchema`, meskipun kosong). Bundle yang kompatibel menggunakan
manifest bundle mereka sendiri.
`plugins list` menampilkan `Format: openclaw` atau `Format: bundle`. Output
verbose list/info juga menampilkan subtipe bundle (`codex`, `claude`, atau `cursor`) serta kemampuan bundle
yang terdeteksi.
### Instal
```bash
openclaw plugins install <package> # ClawHub terlebih dahulu, lalu npm
openclaw plugins install clawhub:<package> # hanya ClawHub
openclaw plugins install <package> --force # timpa instalasi yang ada
openclaw plugins install <package> --pin # pin versi
openclaw plugins install <package> --dangerously-force-unsafe-install
openclaw plugins install <path> # path lokal
openclaw plugins install <plugin>@<marketplace> # marketplace
openclaw plugins install <plugin> --marketplace <name> # marketplace (eksplisit)
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
```
Nama package polos diperiksa ke ClawHub terlebih dahulu, lalu npm. Catatan keamanan:
anggap instalasi plugin seperti menjalankan kode. Sebaiknya gunakan versi yang dipin.
Jika config tidak valid, `plugins install` biasanya gagal secara tertutup dan memberi tahu Anda untuk
menjalankan `openclaw doctor --fix` terlebih dahulu. Satu-satunya pengecualian yang terdokumentasi adalah jalur pemulihan plugin bawaan yang sempit
untuk plugin yang secara eksplisit memilih
`openclaw.install.allowInvalidConfigRecovery`.
`--force` menggunakan ulang target instalasi yang ada dan menimpa plugin atau hook pack
yang sudah terinstal di tempat. Gunakan saat Anda sengaja menginstal ulang
id yang sama dari path lokal baru, arsip, package ClawHub, atau artefak npm.
`--pin` hanya berlaku untuk instalasi npm. Ini tidak didukung dengan `--marketplace`,
karena instalasi marketplace menyimpan metadata sumber marketplace, bukan
spec npm.
`--dangerously-force-unsafe-install` adalah opsi darurat untuk false positive
dalam pemindai kode berbahaya bawaan. Ini memungkinkan instalasi tetap berlanjut bahkan
saat pemindai bawaan melaporkan temuan `critical`, tetapi **tidak**
melewati blok kebijakan hook plugin `before_install` dan **tidak** melewati
kegagalan pemindaian.
Flag CLI ini berlaku untuk alur instal/update plugin. Instalasi dependensi skill
berbasis Gateway menggunakan override permintaan `dangerouslyForceUnsafeInstall` yang sesuai, sedangkan `openclaw skills install` tetap merupakan alur
unduh/instal skill ClawHub yang terpisah.
`plugins install` juga merupakan permukaan instalasi untuk hook pack yang mengekspos
`openclaw.hooks` di `package.json`. Gunakan `openclaw hooks` untuk visibilitas hook
yang difilter dan pengaktifan per hook, bukan instalasi package.
Spec npm hanya **khusus registry** (nama package + **versi exact** opsional atau
**dist-tag**). Spec git/URL/file dan rentang semver ditolak. Instalasi dependensi
berjalan dengan `--ignore-scripts` demi keamanan.
Spec polos dan `@latest` tetap berada di jalur stabil. Jika npm menyelesaikan salah satu
dari itu ke prerelease, OpenClaw akan berhenti dan meminta Anda memilihnya secara eksplisit dengan
tag prerelease seperti `@beta`/`@rc` atau versi prerelease exact seperti
`@1.2.3-beta.4`.
Jika spec instalasi polos cocok dengan id plugin bawaan (misalnya `diffs`), OpenClaw
menginstal plugin bawaan secara langsung. Untuk menginstal package npm dengan nama yang sama,
gunakan spec berscope yang eksplisit (misalnya `@scope/diffs`).
Arsip yang didukung: `.zip`, `.tgz`, `.tar.gz`, `.tar`.
Instalasi marketplace Claude juga didukung.
Instalasi ClawHub menggunakan locator `clawhub:<package>` yang eksplisit:
```bash
openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
```
OpenClaw kini juga memprioritaskan ClawHub untuk spec plugin polos yang aman untuk npm. OpenClaw hanya
fallback ke npm jika ClawHub tidak memiliki package atau versi tersebut:
```bash
openclaw plugins install openclaw-codex-app-server
```
OpenClaw mengunduh arsip package dari ClawHub, memeriksa kompatibilitas
API plugin / gateway minimum yang diiklankan, lalu menginstalnya melalui jalur
arsip normal. Instalasi yang dicatat mempertahankan metadata sumber ClawHub untuk update berikutnya.
Gunakan singkatan `plugin@marketplace` saat nama marketplace ada di cache registry
lokal Claude di `~/.claude/plugins/known_marketplaces.json`:
```bash
openclaw plugins marketplace list <marketplace-name>
openclaw plugins install <plugin-name>@<marketplace-name>
```
Gunakan `--marketplace` saat Anda ingin memberikan sumber marketplace secara eksplisit:
```bash
openclaw plugins install <plugin-name> --marketplace <marketplace-name>
openclaw plugins install <plugin-name> --marketplace <owner/repo>
openclaw plugins install <plugin-name> --marketplace https://github.com/<owner>/<repo>
openclaw plugins install <plugin-name> --marketplace ./my-marketplace
```
Sumber marketplace dapat berupa:
- nama known-marketplace Claude dari `~/.claude/plugins/known_marketplaces.json`
- root marketplace lokal atau path `marketplace.json`
- singkatan repo GitHub seperti `owner/repo`
- URL repo GitHub seperti `https://github.com/owner/repo`
- URL git
Untuk marketplace remote yang dimuat dari GitHub atau git, entri plugin harus tetap
berada di dalam repo marketplace yang di-clone. OpenClaw menerima sumber path relatif dari
repo itu dan menolak sumber plugin HTTP(S), absolute-path, git, GitHub, dan sumber non-path lain dari manifest remote.
Untuk path lokal dan arsip, OpenClaw mendeteksi otomatis:
- plugin OpenClaw native (`openclaw.plugin.json`)
- bundle yang kompatibel dengan Codex (`.codex-plugin/plugin.json`)
- bundle yang kompatibel dengan Claude (`.claude-plugin/plugin.json` atau tata letak komponen Claude default)
- bundle yang kompatibel dengan Cursor (`.cursor-plugin/plugin.json`)
Bundle yang kompatibel diinstal ke root ekstensi normal dan berpartisipasi dalam alur yang sama untuk list/info/enable/disable. Saat ini, skill bundle, Claude
command-skills, default Claude `settings.json`, default Claude `.lsp.json` /
`lspServers` default yang dideklarasikan manifest, Cursor command-skills, dan direktori hook Codex yang kompatibel didukung; kemampuan bundle lain yang terdeteksi
ditampilkan dalam diagnostik/info tetapi belum terhubung ke eksekusi runtime.
### Daftar
```bash
openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
```
Gunakan `--enabled` untuk hanya menampilkan plugin yang dimuat. Gunakan `--verbose` untuk beralih dari
tampilan tabel ke baris detail per plugin dengan metadata sumber/asal/versi/aktivasi.
Gunakan `--json` untuk inventaris yang dapat dibaca mesin plus
diagnostik registry.
Gunakan `--link` untuk menghindari penyalinan direktori lokal (menambahkan ke `plugins.load.paths`):
```bash
openclaw plugins install -l ./my-plugin
```
`--force` tidak didukung dengan `--link` karena instalasi tertaut menggunakan ulang
path sumber alih-alih menyalin ke target instalasi terkelola.
Gunakan `--pin` pada instalasi npm untuk menyimpan spec exact yang diselesaikan (`name@version`) di
`plugins.installs` sambil mempertahankan perilaku default tanpa pin.
### Uninstal
```bash
openclaw plugins uninstall <id>
openclaw plugins uninstall <id> --dry-run
openclaw plugins uninstall <id> --keep-files
```
`uninstall` menghapus catatan plugin dari `plugins.entries`, `plugins.installs`,
allowlist plugin, dan entri `plugins.load.paths` yang tertaut jika berlaku.
Untuk plugin memori aktif, slot memory di-reset ke `memory-core`.
Secara default, uninstall juga menghapus direktori instalasi plugin di bawah
root plugin state-dir yang aktif. Gunakan
`--keep-files` untuk mempertahankan file di disk.
`--keep-config` didukung sebagai alias usang untuk `--keep-files`.
### Update
```bash
openclaw plugins update <id-or-npm-spec>
openclaw plugins update --all
openclaw plugins update <id-or-npm-spec> --dry-run
openclaw plugins update @openclaw/voice-call@beta
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install
```
Update berlaku untuk instalasi terlacak di `plugins.installs` dan instalasi
hook-pack terlacak di `hooks.internal.installs`.
Saat Anda memberikan id plugin, OpenClaw menggunakan ulang spec instalasi yang tercatat untuk
plugin tersebut. Artinya dist-tag yang sebelumnya disimpan seperti `@beta` dan versi exact yang dipin
tetap digunakan pada eksekusi `update <id>` berikutnya.
Untuk instalasi npm, Anda juga dapat memberikan spec package npm yang eksplisit dengan dist-tag
atau versi exact. OpenClaw menyelesaikan nama package itu kembali ke catatan plugin yang terlacak,
meng-update plugin yang terinstal tersebut, dan mencatat spec npm baru untuk update berbasis id di masa mendatang.
Saat hash integritas yang tersimpan ada dan hash artefak yang diambil berubah,
OpenClaw mencetak peringatan dan meminta konfirmasi sebelum melanjutkan. Gunakan
global `--yes` untuk melewati prompt dalam eksekusi CI/non-interaktif.
`--dangerously-force-unsafe-install` juga tersedia pada `plugins update` sebagai
override darurat untuk false positive pemindaian kode berbahaya bawaan selama
update plugin. Ini tetap tidak melewati blok kebijakan plugin `before_install`
atau pemblokiran kegagalan pemindaian, dan hanya berlaku untuk update plugin, bukan update hook-pack.
### Inspect
```bash
openclaw plugins inspect <id>
openclaw plugins inspect <id> --json
```
Introspeksi mendalam untuk satu plugin. Menampilkan identitas, status muat, sumber,
kemampuan yang terdaftar, hook, tool, perintah, layanan, metode gateway,
rute HTTP, flag kebijakan, diagnostik, metadata instalasi, kemampuan bundle,
serta dukungan MCP atau server LSP yang terdeteksi.
Setiap plugin diklasifikasikan berdasarkan apa yang benar-benar didaftarkannya saat runtime:
- **plain-capability** — satu jenis kemampuan (misalnya plugin khusus provider)
- **hybrid-capability** — beberapa jenis kemampuan (misalnya teks + speech + gambar)
- **hook-only** — hanya hook, tanpa kemampuan atau permukaan
- **non-capability** — tools/perintah/layanan tetapi tanpa kemampuan
Lihat [Plugin shapes](/plugins/architecture#plugin-shapes) untuk informasi lebih lanjut tentang model kemampuan.
Flag `--json` menghasilkan laporan yang dapat dibaca mesin dan cocok untuk scripting serta
audit.
`inspect --all` merender tabel seluruh armada dengan kolom shape, jenis kemampuan,
pemberitahuan kompatibilitas, kemampuan bundle, dan ringkasan hook.
`info` adalah alias untuk `inspect`.
### Doctor
```bash
openclaw plugins doctor
```
`doctor` melaporkan error pemuatan plugin, diagnostik manifest/discovery, dan
pemberitahuan kompatibilitas. Jika semuanya bersih, perintah ini mencetak `No plugin issues
detected.`
### Marketplace
```bash
openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
```
Daftar marketplace menerima path marketplace lokal, path `marketplace.json`, singkatan
GitHub seperti `owner/repo`, URL repo GitHub, atau URL git. `--json`
mencetak label sumber yang diselesaikan beserta manifest marketplace yang diurai dan
entri plugin.

59
docs/id/cli/qr.md Normal file
View File

@ -0,0 +1,59 @@
---
read_when:
- Anda ingin memasangkan aplikasi node seluler dengan gateway dengan cepat
- Anda memerlukan output kode penyiapan untuk dibagikan secara jarak jauh/manual
summary: Referensi CLI untuk `openclaw qr` (membuat QR pairing seluler + kode penyiapan)
title: qr
x-i18n:
generated_at: "2026-04-05T13:49:35Z"
model: gpt-5.4
provider: openai
source_hash: ee6469334ad09037318f938c7ac609b7d5e3385c0988562501bb02a1bfa411ff
source_path: cli/qr.md
workflow: 15
---
# `openclaw qr`
Buat QR pairing seluler dan kode penyiapan dari konfigurasi Gateway Anda saat ini.
## Penggunaan
```bash
openclaw qr
openclaw qr --setup-code-only
openclaw qr --json
openclaw qr --remote
openclaw qr --url wss://gateway.example/ws
```
## Opsi
- `--remote`: utamakan `gateway.remote.url`; jika tidak disetel, `gateway.tailscale.mode=serve|funnel` masih dapat menyediakan URL publik jarak jauh
- `--url <url>`: timpa URL gateway yang digunakan dalam payload
- `--public-url <url>`: timpa URL publik yang digunakan dalam payload
- `--token <token>`: timpa token gateway mana yang diautentikasi oleh alur bootstrap
- `--password <password>`: timpa kata sandi gateway mana yang diautentikasi oleh alur bootstrap
- `--setup-code-only`: cetak hanya kode penyiapan
- `--no-ascii`: lewati rendering QR ASCII
- `--json`: keluarkan JSON (`setupCode`, `gatewayUrl`, `auth`, `urlSource`)
## Catatan
- `--token` dan `--password` bersifat saling eksklusif.
- Kode penyiapan itu sendiri sekarang membawa `bootstrapToken` opak berumur pendek, bukan token/kata sandi gateway bersama.
- Dalam alur bootstrap node/operator bawaan, token node utama tetap berakhir dengan `scopes: []`.
- Jika serah terima bootstrap juga menerbitkan token operator, token itu tetap dibatasi ke allowlist bootstrap: `operator.approvals`, `operator.read`, `operator.talk.secrets`, `operator.write`.
- Pemeriksaan cakupan bootstrap berawalan peran. Allowlist operator itu hanya memenuhi permintaan operator; peran non-operator tetap memerlukan cakupan di bawah awalan peran mereka sendiri.
- Pairing seluler gagal tertutup untuk URL gateway Tailscale/publik `ws://`. `ws://` LAN privat tetap didukung, tetapi rute seluler Tailscale/publik harus menggunakan Tailscale Serve/Funnel atau URL gateway `wss://`.
- Dengan `--remote`, OpenClaw memerlukan `gateway.remote.url` atau
`gateway.tailscale.mode=serve|funnel`.
- Dengan `--remote`, jika kredensial jarak jauh aktif yang efektif dikonfigurasi sebagai SecretRef dan Anda tidak memberikan `--token` atau `--password`, perintah akan menyelesaikannya dari snapshot gateway aktif. Jika gateway tidak tersedia, perintah gagal cepat.
- Tanpa `--remote`, SecretRef autentikasi gateway lokal diselesaikan saat tidak ada override autentikasi CLI yang diberikan:
- `gateway.auth.token` diselesaikan saat autentikasi token dapat menang (eksplisit `gateway.auth.mode="token"` atau mode tersimpulkan saat tidak ada sumber kata sandi yang menang).
- `gateway.auth.password` diselesaikan saat autentikasi kata sandi dapat menang (eksplisit `gateway.auth.mode="password"` atau mode tersimpulkan tanpa token pemenang dari auth/env).
- Jika `gateway.auth.token` dan `gateway.auth.password` keduanya dikonfigurasi (termasuk SecretRef) dan `gateway.auth.mode` tidak disetel, penyelesaian kode penyiapan gagal sampai mode disetel secara eksplisit.
- Catatan ketidaksesuaian versi gateway: jalur perintah ini memerlukan gateway yang mendukung `secrets.resolve`; gateway yang lebih lama mengembalikan error unknown-method.
- Setelah dipindai, setujui pairing perangkat dengan:
- `openclaw devices list`
- `openclaw devices approve <requestId>`

42
docs/id/cli/reset.md Normal file
View File

@ -0,0 +1,42 @@
---
read_when:
- Anda ingin menghapus status lokal sambil tetap mempertahankan CLI terinstal
- Anda ingin melihat dry-run dari apa saja yang akan dihapus
summary: Referensi CLI untuk `openclaw reset` (mengatur ulang status/konfigurasi lokal)
title: reset
x-i18n:
generated_at: "2026-04-05T13:49:31Z"
model: gpt-5.4
provider: openai
source_hash: ad464700f948bebe741ec309f25150714f0b280834084d4f531327418a42c79b
source_path: cli/reset.md
workflow: 15
---
# `openclaw reset`
Atur ulang konfigurasi/status lokal (tetap mempertahankan CLI terinstal).
Opsi:
- `--scope <scope>`: `config`, `config+creds+sessions`, atau `full`
- `--yes`: lewati prompt konfirmasi
- `--non-interactive`: nonaktifkan prompt; memerlukan `--scope` dan `--yes`
- `--dry-run`: cetak tindakan tanpa menghapus file
Contoh:
```bash
openclaw backup create
openclaw reset
openclaw reset --dry-run
openclaw reset --scope config --yes --non-interactive
openclaw reset --scope config+creds+sessions --yes --non-interactive
openclaw reset --scope full --yes --non-interactive
```
Catatan:
- Jalankan `openclaw backup create` terlebih dahulu jika Anda menginginkan snapshot yang dapat dipulihkan sebelum menghapus status lokal.
- Jika Anda tidak menyertakan `--scope`, `openclaw reset` menggunakan prompt interaktif untuk memilih apa yang akan dihapus.
- `--non-interactive` hanya valid jika `--scope` dan `--yes` sama-sama ditetapkan.

204
docs/id/cli/sandbox.md Normal file
View File

@ -0,0 +1,204 @@
---
read_when: You are managing sandbox runtimes or debugging sandbox/tool-policy behavior.
status: active
summary: Kelola runtime sandbox dan periksa kebijakan sandbox efektif
title: CLI Sandbox
x-i18n:
generated_at: "2026-04-05T13:49:50Z"
model: gpt-5.4
provider: openai
source_hash: fa2783037da2901316108d35e04bb319d5d57963c2764b9146786b3c6474b48a
source_path: cli/sandbox.md
workflow: 15
---
# CLI Sandbox
Kelola runtime sandbox untuk eksekusi agen yang terisolasi.
## Gambaran umum
OpenClaw dapat menjalankan agen dalam runtime sandbox yang terisolasi untuk keamanan. Perintah `sandbox` membantu Anda memeriksa dan membuat ulang runtime tersebut setelah pembaruan atau perubahan konfigurasi.
Saat ini, biasanya ini berarti:
- Kontainer sandbox Docker
- Runtime sandbox SSH saat `agents.defaults.sandbox.backend = "ssh"`
- Runtime sandbox OpenShell saat `agents.defaults.sandbox.backend = "openshell"`
Untuk `ssh` dan OpenShell `remote`, pembuatan ulang lebih penting dibandingkan dengan Docker:
- workspace remote menjadi kanonis setelah seed awal
- `openclaw sandbox recreate` menghapus workspace remote kanonis tersebut untuk cakupan yang dipilih
- penggunaan berikutnya melakukan seed ulang dari workspace lokal saat ini
## Perintah
### `openclaw sandbox explain`
Periksa mode/cakupan/akses workspace sandbox yang **efektif**, kebijakan alat sandbox, dan gerbang elevasi (dengan path kunci konfigurasi fix-it).
```bash
openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json
```
### `openclaw sandbox list`
Daftarkan semua runtime sandbox beserta status dan konfigurasinya.
```bash
openclaw sandbox list
openclaw sandbox list --browser # Daftarkan hanya kontainer browser
openclaw sandbox list --json # Output JSON
```
**Output mencakup:**
- Nama runtime dan status
- Backend (`docker`, `openshell`, dll.)
- Label konfigurasi dan apakah cocok dengan konfigurasi saat ini
- Usia (waktu sejak dibuat)
- Waktu idle (waktu sejak terakhir digunakan)
- Sesi/agen terkait
### `openclaw sandbox recreate`
Hapus runtime sandbox untuk memaksa pembuatan ulang dengan konfigurasi yang diperbarui.
```bash
openclaw sandbox recreate --all # Buat ulang semua kontainer
openclaw sandbox recreate --session main # Sesi tertentu
openclaw sandbox recreate --agent mybot # Agen tertentu
openclaw sandbox recreate --browser # Hanya kontainer browser
openclaw sandbox recreate --all --force # Lewati konfirmasi
```
**Opsi:**
- `--all`: Buat ulang semua kontainer sandbox
- `--session <key>`: Buat ulang kontainer untuk sesi tertentu
- `--agent <id>`: Buat ulang kontainer untuk agen tertentu
- `--browser`: Buat ulang hanya kontainer browser
- `--force`: Lewati prompt konfirmasi
**Penting:** Runtime dibuat ulang secara otomatis saat agen berikutnya digunakan.
## Kasus penggunaan
### Setelah memperbarui image Docker
```bash
# Tarik image baru
docker pull openclaw-sandbox:latest
docker tag openclaw-sandbox:latest openclaw-sandbox:bookworm-slim
# Perbarui konfigurasi untuk menggunakan image baru
# Edit konfigurasi: agents.defaults.sandbox.docker.image (atau agents.list[].sandbox.docker.image)
# Buat ulang kontainer
openclaw sandbox recreate --all
```
### Setelah mengubah konfigurasi sandbox
```bash
# Edit konfigurasi: agents.defaults.sandbox.* (atau agents.list[].sandbox.*)
# Buat ulang untuk menerapkan konfigurasi baru
openclaw sandbox recreate --all
```
### Setelah mengubah target SSH atau materi autentikasi SSH
```bash
# Edit konfigurasi:
# - agents.defaults.sandbox.backend
# - agents.defaults.sandbox.ssh.target
# - agents.defaults.sandbox.ssh.workspaceRoot
# - agents.defaults.sandbox.ssh.identityFile / certificateFile / knownHostsFile
# - agents.defaults.sandbox.ssh.identityData / certificateData / knownHostsData
openclaw sandbox recreate --all
```
Untuk backend inti `ssh`, pembuatan ulang menghapus root workspace remote per cakupan
pada target SSH. Eksekusi berikutnya akan melakukan seed ulang dari workspace lokal.
### Setelah mengubah sumber, kebijakan, atau mode OpenShell
```bash
# Edit konfigurasi:
# - agents.defaults.sandbox.backend
# - plugins.entries.openshell.config.from
# - plugins.entries.openshell.config.mode
# - plugins.entries.openshell.config.policy
openclaw sandbox recreate --all
```
Untuk mode OpenShell `remote`, pembuatan ulang menghapus workspace remote kanonis
untuk cakupan tersebut. Eksekusi berikutnya akan melakukan seed ulang dari workspace lokal.
### Setelah mengubah setupCommand
```bash
openclaw sandbox recreate --all
# atau hanya satu agen:
openclaw sandbox recreate --agent family
```
### Hanya untuk agen tertentu
```bash
# Perbarui kontainer hanya untuk satu agen
openclaw sandbox recreate --agent alfred
```
## Mengapa ini diperlukan?
**Masalah:** Saat Anda memperbarui konfigurasi sandbox:
- Runtime yang ada terus berjalan dengan pengaturan lama
- Runtime hanya dipangkas setelah 24 jam tidak aktif
- Agen yang digunakan secara rutin membuat runtime lama tetap hidup tanpa batas waktu
**Solusi:** Gunakan `openclaw sandbox recreate` untuk memaksa penghapusan runtime lama. Runtime tersebut akan dibuat ulang secara otomatis dengan pengaturan saat ini ketika berikutnya diperlukan.
Tips: lebih baik gunakan `openclaw sandbox recreate` daripada pembersihan manual yang khusus backend.
Perintah ini menggunakan registri runtime Gateway dan menghindari ketidakcocokan saat kunci cakupan/sesi berubah.
## Konfigurasi
Pengaturan sandbox berada di `~/.openclaw/openclaw.json` di bawah `agents.defaults.sandbox` (override per agen berada di `agents.list[].sandbox`):
```jsonc
{
"agents": {
"defaults": {
"sandbox": {
"mode": "all", // off, non-main, all
"backend": "docker", // docker, ssh, openshell
"scope": "agent", // session, agent, shared
"docker": {
"image": "openclaw-sandbox:bookworm-slim",
"containerPrefix": "openclaw-sbx-",
// ... lebih banyak opsi Docker
},
"prune": {
"idleHours": 24, // Pangkas otomatis setelah idle 24 jam
"maxAgeDays": 7, // Pangkas otomatis setelah 7 hari
},
},
},
},
}
```
## Lihat juga
- [Dokumentasi Sandbox](/gateway/sandboxing)
- [Konfigurasi Agen](/concepts/agent-workspace)
- [Perintah Doctor](/gateway/doctor) - Periksa penyiapan sandbox

204
docs/id/cli/secrets.md Normal file
View File

@ -0,0 +1,204 @@
---
read_when:
- Menyelesaikan ulang referensi secret saat runtime
- Mengaudit residu plaintext dan referensi yang belum terselesaikan
- Mengonfigurasi SecretRefs dan menerapkan perubahan scrub satu arah
summary: Referensi CLI untuk `openclaw secrets` (reload, audit, configure, apply)
title: secrets
x-i18n:
generated_at: "2026-04-05T13:49:54Z"
model: gpt-5.4
provider: openai
source_hash: f436ba089d752edb766c0a3ce746ee6bca1097b22c9b30e3d9715cb0bb50bf47
source_path: cli/secrets.md
workflow: 15
---
# `openclaw secrets`
Gunakan `openclaw secrets` untuk mengelola SecretRefs dan menjaga snapshot runtime aktif tetap sehat.
Peran perintah:
- `reload`: gateway RPC (`secrets.reload`) yang menyelesaikan ulang referensi dan menukar snapshot runtime hanya jika seluruh proses berhasil (tanpa penulisan konfigurasi).
- `audit`: pemindaian baca-saja atas penyimpanan configuration/auth/generated-model dan residu lama untuk plaintext, referensi yang belum terselesaikan, dan drift precedence (referensi exec dilewati kecuali `--allow-exec` diatur).
- `configure`: perencana interaktif untuk penyiapan provider, pemetaan target, dan preflight (memerlukan TTY).
- `apply`: menjalankan rencana yang disimpan (`--dry-run` hanya untuk validasi; dry-run melewati pemeriksaan exec secara default, dan mode tulis menolak rencana yang berisi exec kecuali `--allow-exec` diatur), lalu melakukan scrub pada residu plaintext yang ditargetkan.
Loop operator yang direkomendasikan:
```bash
openclaw secrets audit --check
openclaw secrets configure
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets audit --check
openclaw secrets reload
```
Jika rencana Anda mencakup `exec` SecretRefs/providers, berikan `--allow-exec` pada perintah apply dry-run dan mode tulis.
Catatan exit code untuk CI/gate:
- `audit --check` mengembalikan `1` jika ada temuan.
- referensi yang belum terselesaikan mengembalikan `2`.
Terkait:
- Panduan secrets: [Secrets Management](/gateway/secrets)
- Permukaan kredensial: [SecretRef Credential Surface](/reference/secretref-credential-surface)
- Panduan keamanan: [Security](/gateway/security)
## Reload snapshot runtime
Selesaikan ulang referensi secret dan tukar snapshot runtime secara atomik.
```bash
openclaw secrets reload
openclaw secrets reload --json
openclaw secrets reload --url ws://127.0.0.1:18789 --token <token>
```
Catatan:
- Menggunakan metode gateway RPC `secrets.reload`.
- Jika penyelesaian gagal, gateway mempertahankan snapshot baik-terakhir-yang-diketahui dan mengembalikan error (tanpa aktivasi parsial).
- Respons JSON mencakup `warningCount`.
Opsi:
- `--url <url>`
- `--token <token>`
- `--timeout <ms>`
- `--json`
## Audit
Pindai status OpenClaw untuk:
- penyimpanan secret plaintext
- referensi yang belum terselesaikan
- drift precedence (kredensial `auth-profiles.json` yang membayangi referensi `openclaw.json`)
- residu `agents/*/agent/models.json` yang dihasilkan (nilai `apiKey` provider dan header provider sensitif)
- residu lama (entri penyimpanan auth lama, pengingat OAuth)
Catatan residu header:
- Deteksi header provider sensitif didasarkan pada heuristik nama (nama dan fragmen header auth/kredensial yang umum seperti `authorization`, `x-api-key`, `token`, `secret`, `password`, dan `credential`).
```bash
openclaw secrets audit
openclaw secrets audit --check
openclaw secrets audit --json
openclaw secrets audit --allow-exec
```
Perilaku keluar:
- `--check` keluar dengan kode non-zero jika ada temuan.
- referensi yang belum terselesaikan keluar dengan kode non-zero prioritas lebih tinggi.
Sorotan bentuk laporan:
- `status`: `clean | findings | unresolved`
- `resolution`: `refsChecked`, `skippedExecRefs`, `resolvabilityComplete`
- `summary`: `plaintextCount`, `unresolvedRefCount`, `shadowedRefCount`, `legacyResidueCount`
- kode temuan:
- `PLAINTEXT_FOUND`
- `REF_UNRESOLVED`
- `REF_SHADOWED`
- `LEGACY_RESIDUE`
## Configure (helper interaktif)
Bangun perubahan provider dan SecretRef secara interaktif, jalankan preflight, dan secara opsional terapkan:
```bash
openclaw secrets configure
openclaw secrets configure --plan-out /tmp/openclaw-secrets-plan.json
openclaw secrets configure --apply --yes
openclaw secrets configure --providers-only
openclaw secrets configure --skip-provider-setup
openclaw secrets configure --agent ops
openclaw secrets configure --json
```
Alur:
- Penyiapan provider terlebih dahulu (`add/edit/remove` untuk alias `secrets.providers`).
- Pemetaan kredensial berikutnya (pilih field dan tetapkan referensi `{source, provider, id}`).
- Preflight dan apply opsional terakhir.
Flag:
- `--providers-only`: konfigurasikan hanya `secrets.providers`, lewati pemetaan kredensial.
- `--skip-provider-setup`: lewati penyiapan provider dan petakan kredensial ke provider yang ada.
- `--agent <id>`: cakup penemuan target `auth-profiles.json` dan penulisan ke satu penyimpanan agen.
- `--allow-exec`: izinkan pemeriksaan exec SecretRef selama preflight/apply (dapat mengeksekusi perintah provider).
Catatan:
- Memerlukan TTY interaktif.
- Anda tidak dapat menggabungkan `--providers-only` dengan `--skip-provider-setup`.
- `configure` menargetkan field yang mengandung secret di `openclaw.json` serta `auth-profiles.json` untuk cakupan agen yang dipilih.
- `configure` mendukung pembuatan pemetaan `auth-profiles.json` baru langsung di alur picker.
- Permukaan yang didukung secara kanonis: [SecretRef Credential Surface](/reference/secretref-credential-surface).
- Perintah ini melakukan penyelesaian preflight sebelum apply.
- Jika preflight/apply mencakup referensi exec, tetap atur `--allow-exec` untuk kedua langkah.
- Rencana yang dihasilkan secara default menggunakan opsi scrub (`scrubEnv`, `scrubAuthProfilesForProviderTargets`, `scrubLegacyAuthJson` semuanya diaktifkan).
- Jalur apply bersifat satu arah untuk nilai plaintext yang telah di-scrub.
- Tanpa `--apply`, CLI tetap menampilkan prompt `Apply this plan now?` setelah preflight.
- Dengan `--apply` (dan tanpa `--yes`), CLI menampilkan prompt konfirmasi tambahan yang tidak dapat dibatalkan.
- `--json` mencetak rencana + laporan preflight, tetapi perintah ini tetap memerlukan TTY interaktif.
Catatan keamanan provider exec:
- Instalasi Homebrew sering mengekspos binary bertautan simbolik di bawah `/opt/homebrew/bin/*`.
- Atur `allowSymlinkCommand: true` hanya bila diperlukan untuk path package manager tepercaya, dan pasangkan dengan `trustedDirs` (misalnya `["/opt/homebrew"]`).
- Di Windows, jika verifikasi ACL tidak tersedia untuk path provider, OpenClaw gagal secara tertutup. Hanya untuk path tepercaya, atur `allowInsecurePath: true` pada provider tersebut untuk melewati pemeriksaan keamanan path.
## Terapkan rencana yang disimpan
Terapkan atau lakukan preflight pada rencana yang dibuat sebelumnya:
```bash
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --json
```
Perilaku exec:
- `--dry-run` memvalidasi preflight tanpa menulis file.
- pemeriksaan exec SecretRef dilewati secara default dalam dry-run.
- mode tulis menolak rencana yang mengandung exec SecretRefs/providers kecuali `--allow-exec` diatur.
- Gunakan `--allow-exec` untuk memilih ikut serta dalam pemeriksaan/eksekusi provider exec di kedua mode.
Detail kontrak rencana (path target yang diizinkan, aturan validasi, dan semantik kegagalan):
- [Secrets Apply Plan Contract](/gateway/secrets-plan-contract)
Yang dapat diperbarui oleh `apply`:
- `openclaw.json` (target SecretRef + upsert/delete provider)
- `auth-profiles.json` (scrub target provider)
- residu `auth.json` lama
- `~/.openclaw/.env` untuk kunci secret yang dikenal yang nilainya telah dimigrasikan
## Mengapa tidak ada backup rollback
`secrets apply` sengaja tidak menulis backup rollback yang berisi nilai plaintext lama.
Keamanan berasal dari preflight yang ketat + apply yang nyaris atomik dengan pemulihan dalam memori upaya-terbaik saat terjadi kegagalan.
## Contoh
```bash
openclaw secrets audit --check
openclaw secrets configure
openclaw secrets audit --check
```
Jika `audit --check` masih melaporkan temuan plaintext, perbarui path target yang tersisa yang dilaporkan lalu jalankan ulang audit.

93
docs/id/cli/security.md Normal file
View File

@ -0,0 +1,93 @@
---
read_when:
- Anda ingin menjalankan audit keamanan cepat pada config/state
- Anda ingin menerapkan saran “fix” yang aman (izin, memperketat default)
summary: Referensi CLI untuk `openclaw security` (audit dan perbaiki footgun keamanan umum)
title: security
x-i18n:
generated_at: "2026-04-05T13:49:54Z"
model: gpt-5.4
provider: openai
source_hash: e5a3e4ab8e0dfb6c10763097cb4483be2431985f16de877523eb53e2122239ae
source_path: cli/security.md
workflow: 15
---
# `openclaw security`
Tool keamanan (audit + perbaikan opsional).
Terkait:
- Panduan keamanan: [Security](/gateway/security)
## Audit
```bash
openclaw security audit
openclaw security audit --deep
openclaw security audit --deep --password <password>
openclaw security audit --deep --token <token>
openclaw security audit --fix
openclaw security audit --json
```
Audit memperingatkan ketika beberapa pengirim DM berbagi sesi utama dan merekomendasikan **mode DM aman**: `session.dmScope="per-channel-peer"` (atau `per-account-channel-peer` untuk channel multi-akun) untuk kotak masuk bersama.
Ini ditujukan untuk penguatan kotak masuk kooperatif/bersama. Satu Gateway yang dibagikan oleh operator yang saling tidak dipercaya/bersifat adversarial bukanlah setup yang direkomendasikan; pisahkan batas kepercayaan dengan gateway terpisah (atau pengguna OS/host terpisah).
Audit juga menghasilkan `security.trust_model.multi_user_heuristic` ketika config menunjukkan ingress pengguna bersama yang mungkin terjadi (misalnya kebijakan DM/grup terbuka, target grup yang dikonfigurasi, atau aturan pengirim wildcard), dan mengingatkan Anda bahwa model kepercayaan OpenClaw secara default adalah asisten pribadi.
Untuk setup pengguna bersama yang disengaja, panduan audit adalah menjalankan sandbox untuk semua sesi, menjaga akses filesystem tetap dibatasi ke workspace, serta tidak menempatkan identitas atau kredensial pribadi/pribadi sensitif pada runtime tersebut.
Audit juga memperingatkan ketika model kecil (`<=300B`) digunakan tanpa sandboxing dan dengan tool web/browser diaktifkan.
Untuk ingress webhook, audit memperingatkan ketika `hooks.token` menggunakan ulang token Gateway, ketika `hooks.token` pendek, ketika `hooks.path="/"`, ketika `hooks.defaultSessionKey` tidak disetel, ketika `hooks.allowedAgentIds` tidak dibatasi, ketika override `sessionKey` permintaan diaktifkan, dan ketika override diaktifkan tanpa `hooks.allowedSessionKeyPrefixes`.
Audit juga memperingatkan ketika pengaturan Docker sandbox dikonfigurasi sementara mode sandbox nonaktif, ketika `gateway.nodes.denyCommands` menggunakan entri mirip pola/tidak dikenal yang tidak efektif (hanya pencocokan nama perintah node yang persis, bukan pemfilteran teks shell), ketika `gateway.nodes.allowCommands` secara eksplisit mengaktifkan perintah node berbahaya, ketika `tools.profile="minimal"` global dioverride oleh profil tool agen, ketika grup terbuka mengekspos tool runtime/filesystem tanpa pelindung sandbox/workspace, dan ketika tool plugin ekstensi yang terinstal mungkin dapat dijangkau di bawah kebijakan tool yang permisif.
Audit juga menandai `gateway.allowRealIpFallback=true` (risiko spoofing header jika proxy salah konfigurasi) dan `discovery.mdns.mode="full"` (kebocoran metadata melalui rekaman TXT mDNS).
Audit juga memperingatkan ketika browser sandbox menggunakan jaringan Docker `bridge` tanpa `sandbox.browser.cdpSourceRange`.
Audit juga menandai mode jaringan Docker sandbox yang berbahaya (termasuk `host` dan penggabungan namespace `container:*`).
Audit juga memperingatkan ketika container Docker browser sandbox yang ada memiliki label hash yang hilang/usang (misalnya container pra-migrasi yang tidak memiliki `openclaw.browserConfigEpoch`) dan merekomendasikan `openclaw sandbox recreate --browser --all`.
Audit juga memperingatkan ketika catatan instalasi plugin/hook berbasis npm tidak dipin, tidak memiliki metadata integritas, atau mengalami drift dari versi paket yang saat ini terinstal.
Audit memperingatkan ketika daftar izin channel mengandalkan nama/email/tag yang dapat berubah alih-alih ID stabil (Discord, Slack, Google Chat, Microsoft Teams, Mattermost, cakupan IRC jika berlaku).
Audit memperingatkan ketika `gateway.auth.mode="none"` membuat API HTTP Gateway dapat dijangkau tanpa secret bersama (`/tools/invoke` ditambah endpoint `/v1/*` apa pun yang diaktifkan).
Pengaturan yang diawali dengan `dangerous`/`dangerously` adalah override operator break-glass yang eksplisit; mengaktifkan salah satunya bukan, dengan sendirinya, laporan kerentanan keamanan.
Untuk inventaris lengkap parameter berbahaya, lihat bagian "Insecure or dangerous flags summary" di [Security](/gateway/security).
Perilaku SecretRef:
- `security audit` menyelesaikan SecretRef yang didukung dalam mode baca-saja untuk path yang ditargetkan.
- Jika SecretRef tidak tersedia di jalur perintah saat ini, audit tetap berlanjut dan melaporkan `secretDiagnostics` (bukan crash).
- `--token` dan `--password` hanya mengoverride autentikasi deep-probe untuk pemanggilan perintah tersebut; keduanya tidak menulis ulang config atau pemetaan SecretRef.
## Output JSON
Gunakan `--json` untuk pemeriksaan CI/kebijakan:
```bash
openclaw security audit --json | jq '.summary'
openclaw security audit --deep --json | jq '.findings[] | select(.severity=="critical") | .checkId'
```
Jika `--fix` dan `--json` digabungkan, output mencakup tindakan perbaikan dan laporan akhir:
```bash
openclaw security audit --fix --json | jq '{fix: .fix.ok, summary: .report.summary}'
```
## Apa yang diubah oleh `--fix`
`--fix` menerapkan remediasi yang aman dan deterministik:
- mengubah `groupPolicy="open"` yang umum menjadi `groupPolicy="allowlist"` (termasuk varian akun di channel yang didukung)
- ketika kebijakan grup WhatsApp diubah menjadi `allowlist`, mengisi `groupAllowFrom` dari
file `allowFrom` yang tersimpan saat daftar itu ada dan config belum
mendefinisikan `allowFrom`
- menetapkan `logging.redactSensitive` dari `"off"` menjadi `"tools"`
- memperketat izin untuk state/config dan file sensitif umum
(`credentials/*.json`, `auth-profiles.json`, `sessions.json`, sesi
`*.jsonl`)
- juga memperketat file include config yang dirujuk dari `openclaw.json`
- menggunakan `chmod` pada host POSIX dan reset `icacls` di Windows
`--fix` **tidak**:
- merotasi token/kata sandi/API key
- menonaktifkan tool (`gateway`, `cron`, `exec`, dll.)
- mengubah pilihan bind/auth/eksposur jaringan gateway
- menghapus atau menulis ulang plugin/Skills

120
docs/id/cli/sessions.md Normal file
View File

@ -0,0 +1,120 @@
---
read_when:
- Anda ingin mencantumkan sesi tersimpan dan melihat aktivitas terbaru
summary: Referensi CLI untuk `openclaw sessions` (daftar sesi tersimpan + penggunaan)
title: sessions
x-i18n:
generated_at: "2026-04-05T13:49:49Z"
model: gpt-5.4
provider: openai
source_hash: 47eb55d90bd0681676283310cfa50dcacc95dff7d9a39bf2bb188788c6e5e5ba
source_path: cli/sessions.md
workflow: 15
---
# `openclaw sessions`
Mencantumkan sesi percakapan yang tersimpan.
```bash
openclaw sessions
openclaw sessions --agent work
openclaw sessions --all-agents
openclaw sessions --active 120
openclaw sessions --verbose
openclaw sessions --json
```
Pemilihan cakupan:
- default: penyimpanan agen default yang dikonfigurasi
- `--verbose`: logging verbose
- `--agent <id>`: satu penyimpanan agen yang dikonfigurasi
- `--all-agents`: gabungkan semua penyimpanan agen yang dikonfigurasi
- `--store <path>`: jalur penyimpanan eksplisit (tidak dapat digabungkan dengan `--agent` atau `--all-agents`)
`openclaw sessions --all-agents` membaca penyimpanan agen yang dikonfigurasi. Gateway dan ACP
discovery sesi lebih luas: keduanya juga menyertakan penyimpanan hanya-di-disk yang ditemukan di bawah
root default `agents/` atau root `session.store` bertemplat. Penyimpanan yang
ditemukan ini harus di-resolve menjadi file `sessions.json` biasa di dalam
root agen; symlink dan jalur di luar root dilewati.
Contoh JSON:
`openclaw sessions --all-agents --json`:
```json
{
"path": null,
"stores": [
{ "agentId": "main", "path": "/home/user/.openclaw/agents/main/sessions/sessions.json" },
{ "agentId": "work", "path": "/home/user/.openclaw/agents/work/sessions/sessions.json" }
],
"allAgents": true,
"count": 2,
"activeMinutes": null,
"sessions": [
{ "agentId": "main", "key": "agent:main:main", "model": "gpt-5" },
{ "agentId": "work", "key": "agent:work:main", "model": "claude-opus-4-6" }
]
}
```
## Pemeliharaan pembersihan
Jalankan pemeliharaan sekarang (alih-alih menunggu siklus penulisan berikutnya):
```bash
openclaw sessions cleanup --dry-run
openclaw sessions cleanup --agent work --dry-run
openclaw sessions cleanup --all-agents --dry-run
openclaw sessions cleanup --enforce
openclaw sessions cleanup --enforce --active-key "agent:main:telegram:direct:123"
openclaw sessions cleanup --json
```
`openclaw sessions cleanup` menggunakan pengaturan `session.maintenance` dari config:
- Catatan cakupan: `openclaw sessions cleanup` hanya memelihara penyimpanan/transkrip sesi. Perintah ini tidak memangkas log eksekusi cron (`cron/runs/<jobId>.jsonl`), yang dikelola oleh `cron.runLog.maxBytes` dan `cron.runLog.keepLines` di [Konfigurasi Cron](/id/automation/cron-jobs#configuration) dan dijelaskan dalam [Pemeliharaan Cron](/id/automation/cron-jobs#maintenance).
- `--dry-run`: pratinjau berapa banyak entri yang akan dipangkas/dibatasi tanpa menulis.
- Dalam mode teks, dry-run mencetak tabel aksi per sesi (`Action`, `Key`, `Age`, `Model`, `Flags`) sehingga Anda dapat melihat mana yang akan dipertahankan vs dihapus.
- `--enforce`: terapkan pemeliharaan meskipun `session.maintenance.mode` adalah `warn`.
- `--fix-missing`: hapus entri yang file transkripnya hilang, meskipun entri tersebut biasanya belum melewati batas usia/jumlah.
- `--active-key <key>`: lindungi active key tertentu dari pengusiran karena anggaran disk.
- `--agent <id>`: jalankan pembersihan untuk satu penyimpanan agen yang dikonfigurasi.
- `--all-agents`: jalankan pembersihan untuk semua penyimpanan agen yang dikonfigurasi.
- `--store <path>`: jalankan terhadap file `sessions.json` tertentu.
- `--json`: cetak ringkasan JSON. Dengan `--all-agents`, output mencakup satu ringkasan per penyimpanan.
`openclaw sessions cleanup --all-agents --dry-run --json`:
```json
{
"allAgents": true,
"mode": "warn",
"dryRun": true,
"stores": [
{
"agentId": "main",
"storePath": "/home/user/.openclaw/agents/main/sessions/sessions.json",
"beforeCount": 120,
"afterCount": 80,
"pruned": 40,
"capped": 0
},
{
"agentId": "work",
"storePath": "/home/user/.openclaw/agents/work/sessions/sessions.json",
"beforeCount": 18,
"afterCount": 18,
"pruned": 0,
"capped": 0
}
]
}
```
Terkait:
- Config sesi: [Referensi konfigurasi](/gateway/configuration-reference#session)

52
docs/id/cli/setup.md Normal file
View File

@ -0,0 +1,52 @@
---
read_when:
- Anda sedang melakukan penyiapan pertama tanpa onboarding CLI penuh
- Anda ingin menetapkan path workspace default
summary: Referensi CLI untuk `openclaw setup` (inisialisasi config + workspace)
title: setup
x-i18n:
generated_at: "2026-04-05T13:49:43Z"
model: gpt-5.4
provider: openai
source_hash: f538aac341c749043ad959e35f2ed99c844ab8c3500ff59aa159d940bd301792
source_path: cli/setup.md
workflow: 15
---
# `openclaw setup`
Inisialisasi `~/.openclaw/openclaw.json` dan workspace agen.
Terkait:
- Memulai: [Getting started](/start/getting-started)
- Onboarding CLI: [Onboarding (CLI)](/start/wizard)
## Contoh
```bash
openclaw setup
openclaw setup --workspace ~/.openclaw/workspace
openclaw setup --wizard
openclaw setup --non-interactive --mode remote --remote-url wss://gateway-host:18789 --remote-token <token>
```
## Opsi
- `--workspace <dir>`: direktori workspace agen (disimpan sebagai `agents.defaults.workspace`)
- `--wizard`: jalankan onboarding
- `--non-interactive`: jalankan onboarding tanpa prompt
- `--mode <local|remote>`: mode onboarding
- `--remote-url <url>`: URL WebSocket Gateway jarak jauh
- `--remote-token <token>`: token Gateway jarak jauh
Untuk menjalankan onboarding melalui setup:
```bash
openclaw setup --wizard
```
Catatan:
- `openclaw setup` biasa menginisialisasi config + workspace tanpa alur onboarding penuh.
- Onboarding dijalankan otomatis saat ada flag onboarding (`--wizard`, `--non-interactive`, `--mode`, `--remote-url`, `--remote-token`).

66
docs/id/cli/skills.md Normal file
View File

@ -0,0 +1,66 @@
---
read_when:
- Anda ingin melihat Skills mana yang tersedia dan siap dijalankan
- Anda ingin mencari, menginstal, atau memperbarui Skills dari ClawHub
- Anda ingin men-debug binary/env/config yang hilang untuk Skills
summary: Referensi CLI untuk `openclaw skills` (search/install/update/list/info/check)
title: skills
x-i18n:
generated_at: "2026-04-05T13:49:51Z"
model: gpt-5.4
provider: openai
source_hash: 11af59b1b6bff19cc043acd8d67bdd4303201d3f75f23c948b83bf14882c7bb1
source_path: cli/skills.md
workflow: 15
---
# `openclaw skills`
Periksa Skills lokal dan instal/perbarui Skills dari ClawHub.
Terkait:
- Sistem Skills: [Skills](/tools/skills)
- Config Skills: [Skills config](/tools/skills-config)
- Instalasi ClawHub: [ClawHub](/tools/clawhub)
## Perintah
```bash
openclaw skills search "calendar"
openclaw skills search --limit 20 --json
openclaw skills install <slug>
openclaw skills install <slug> --version <version>
openclaw skills install <slug> --force
openclaw skills update <slug>
openclaw skills update --all
openclaw skills list
openclaw skills list --eligible
openclaw skills list --json
openclaw skills list --verbose
openclaw skills info <name>
openclaw skills info <name> --json
openclaw skills check
openclaw skills check --json
```
`search`/`install`/`update` menggunakan ClawHub secara langsung dan menginstal ke direktori
workspace aktif `skills/`. `list`/`info`/`check` tetap memeriksa Skills lokal
yang terlihat oleh workspace dan config saat ini.
Perintah CLI `install` ini mengunduh folder skill dari ClawHub. Instalasi dependensi skill
berbasis Gateway yang dipicu dari onboarding atau pengaturan Skills menggunakan
jalur permintaan `skills.install` yang terpisah.
Catatan:
- `search [query...]` menerima kueri opsional; hilangkan untuk menelusuri feed pencarian default
ClawHub.
- `search --limit <n>` membatasi jumlah hasil yang dikembalikan.
- `install --force` menimpa folder skill workspace yang sudah ada untuk
slug yang sama.
- `update --all` hanya memperbarui instalasi ClawHub yang dilacak di workspace aktif.
- `list` adalah tindakan default saat tidak ada subperintah yang diberikan.
- `list`, `info`, dan `check` menulis output yang sudah dirender ke stdout. Dengan
`--json`, artinya payload yang dapat dibaca mesin tetap berada di stdout untuk pipe
dan skrip.

42
docs/id/cli/status.md Normal file
View File

@ -0,0 +1,42 @@
---
read_when:
- Anda ingin diagnosis cepat tentang kesehatan saluran + penerima sesi terbaru
- Anda menginginkan status “all” yang bisa ditempel untuk debugging
summary: Referensi CLI untuk `openclaw status` (diagnostik, probe, snapshot penggunaan)
title: status
x-i18n:
generated_at: "2026-04-05T13:49:59Z"
model: gpt-5.4
provider: openai
source_hash: fbe9d94fbe9938cd946ee6f293b5bd3b464b75e1ade2eacdd851788c3bffe94e
source_path: cli/status.md
workflow: 15
---
# `openclaw status`
Diagnostik untuk saluran + sesi.
```bash
openclaw status
openclaw status --all
openclaw status --deep
openclaw status --usage
```
Catatan:
- `--deep` menjalankan probe langsung (WhatsApp Web + Telegram + Discord + Slack + Signal).
- `--usage` mencetak jendela penggunaan provider yang dinormalisasi sebagai `X% left`.
- Field mentah `usage_percent` / `usagePercent` milik MiniMax adalah kuota tersisa, jadi OpenClaw membalikkannya sebelum ditampilkan; field berbasis hitungan diprioritaskan saat tersedia. Respons `model_remains` memprioritaskan entri model chat, menurunkan label jendela dari timestamp saat diperlukan, dan menyertakan nama model dalam label paket.
- Saat snapshot sesi saat ini jarang terisi, `/status` dapat mengisi balik penghitung token dan cache dari log penggunaan transkrip terbaru. Nilai langsung nonzero yang sudah ada tetap diprioritaskan dibanding nilai fallback transkrip.
- Fallback transkrip juga dapat memulihkan label model runtime aktif saat entri sesi langsung tidak memilikinya. Jika model transkrip tersebut berbeda dari model yang dipilih, status menyelesaikan context window terhadap model runtime yang dipulihkan, bukan model yang dipilih.
- Untuk perhitungan ukuran prompt, fallback transkrip memprioritaskan total berorientasi prompt yang lebih besar saat metadata sesi tidak ada atau lebih kecil, sehingga sesi custom-provider tidak turun menjadi tampilan token `0`.
- Output mencakup penyimpanan sesi per agen saat beberapa agen dikonfigurasi.
- Ringkasan mencakup status instalasi/runtime layanan host Gateway + node saat tersedia.
- Ringkasan mencakup saluran pembaruan + git SHA (untuk checkout source).
- Info pembaruan muncul di Ringkasan; jika pembaruan tersedia, status mencetak petunjuk untuk menjalankan `openclaw update` (lihat [Memperbarui](/install/updating)).
- Permukaan status read-only (`status`, `status --json`, `status --all`) menyelesaikan SecretRef yang didukung untuk jalur config targetnya bila memungkinkan.
- Jika SecretRef saluran yang didukung dikonfigurasi tetapi tidak tersedia dalam jalur perintah saat ini, status tetap read-only dan melaporkan output terdegradasi alih-alih crash. Output untuk manusia menampilkan peringatan seperti “configured token unavailable in this command path”, dan output JSON mencakup `secretDiagnostics`.
- Saat penyelesaian SecretRef lokal-perintah berhasil, status memprioritaskan snapshot yang telah diselesaikan dan menghapus penanda saluran “secret unavailable” sementara dari output akhir.
- `status --all` mencakup baris ringkasan Secrets dan bagian diagnosis yang merangkum diagnostik secret (dipotong agar mudah dibaca) tanpa menghentikan pembuatan laporan.

78
docs/id/cli/system.md Normal file
View File

@ -0,0 +1,78 @@
---
read_when:
- Anda ingin mengantrekan peristiwa sistem tanpa membuat tugas cron
- Anda perlu mengaktifkan atau menonaktifkan heartbeat
- Anda ingin memeriksa entri presence sistem
summary: Referensi CLI untuk `openclaw system` (peristiwa sistem, heartbeat, presence)
title: system
x-i18n:
generated_at: "2026-04-05T13:50:26Z"
model: gpt-5.4
provider: openai
source_hash: a7d19afde9d9cde8a79b0bb8cec6e5673466f4cb9b575fb40111fc32f4eee5d7
source_path: cli/system.md
workflow: 15
---
# `openclaw system`
Helper tingkat sistem untuk Gateway: mengantrekan peristiwa sistem, mengontrol heartbeat,
dan melihat presence.
Semua subperintah `system` menggunakan RPC Gateway dan menerima flag klien bersama:
- `--url <url>`
- `--token <token>`
- `--timeout <ms>`
- `--expect-final`
## Perintah umum
```bash
openclaw system event --text "Check for urgent follow-ups" --mode now
openclaw system event --text "Check for urgent follow-ups" --url ws://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"
openclaw system heartbeat enable
openclaw system heartbeat last
openclaw system presence
```
## `system event`
Antrekan peristiwa sistem pada sesi **utama**. Heartbeat berikutnya akan menyisipkannya
sebagai baris `System:` di prompt. Gunakan `--mode now` untuk memicu heartbeat
segera; `next-heartbeat` menunggu tick terjadwal berikutnya.
Flag:
- `--text <text>`: teks peristiwa sistem yang wajib diisi.
- `--mode <mode>`: `now` atau `next-heartbeat` (default).
- `--json`: output yang dapat dibaca mesin.
- `--url`, `--token`, `--timeout`, `--expect-final`: flag RPC Gateway bersama.
## `system heartbeat last|enable|disable`
Kontrol heartbeat:
- `last`: tampilkan peristiwa heartbeat terakhir.
- `enable`: aktifkan kembali heartbeat (gunakan ini jika sebelumnya dinonaktifkan).
- `disable`: jeda heartbeat.
Flag:
- `--json`: output yang dapat dibaca mesin.
- `--url`, `--token`, `--timeout`, `--expect-final`: flag RPC Gateway bersama.
## `system presence`
Daftarkan entri presence sistem saat ini yang diketahui Gateway (node,
instance, dan baris status serupa).
Flag:
- `--json`: output yang dapat dibaca mesin.
- `--url`, `--token`, `--timeout`, `--expect-final`: flag RPC Gateway bersama.
## Catatan
- Memerlukan Gateway yang sedang berjalan dan dapat dijangkau oleh konfigurasi Anda saat ini (lokal atau jarak jauh).
- Peristiwa sistem bersifat sementara dan tidak disimpan setelah restart.

37
docs/id/cli/tui.md Normal file
View File

@ -0,0 +1,37 @@
---
read_when:
- Anda ingin UI terminal untuk Gateway (ramah untuk penggunaan jarak jauh)
- Anda ingin meneruskan url/token/session dari skrip
summary: Referensi CLI untuk `openclaw tui` (UI terminal yang terhubung ke Gateway)
title: tui
x-i18n:
generated_at: "2026-04-05T13:49:56Z"
model: gpt-5.4
provider: openai
source_hash: 60e35062c0551f85ce0da604a915b3e1ca2514d00d840afe3b94c529304c2c1a
source_path: cli/tui.md
workflow: 15
---
# `openclaw tui`
Buka UI terminal yang terhubung ke Gateway.
Terkait:
- Panduan TUI: [TUI](/web/tui)
Catatan:
- `tui` menyelesaikan SecretRef auth gateway yang dikonfigurasi untuk auth token/password bila memungkinkan (penyedia `env`/`file`/`exec`).
- Saat diluncurkan dari dalam direktori workspace agen yang dikonfigurasi, TUI otomatis memilih agen tersebut untuk default kunci sesi (kecuali `--session` secara eksplisit adalah `agent:<id>:...`).
## Contoh
```bash
openclaw tui
openclaw tui --url ws://127.0.0.1:18789 --token <token>
openclaw tui --session main --deliver
# when run inside an agent workspace, infers that agent automatically
openclaw tui --session bugfix
```

46
docs/id/cli/uninstall.md Normal file
View File

@ -0,0 +1,46 @@
---
read_when:
- Anda ingin menghapus layanan gateway dan/atau state lokal
- Anda ingin melakukan dry-run terlebih dahulu
summary: Referensi CLI untuk `openclaw uninstall` (hapus layanan gateway + data lokal)
title: uninstall
x-i18n:
generated_at: "2026-04-05T13:49:58Z"
model: gpt-5.4
provider: openai
source_hash: 2123a4f9c7a070ef7e13c60dafc189053ef61ce189fa4f29449dd50987c1894c
source_path: cli/uninstall.md
workflow: 15
---
# `openclaw uninstall`
Copot layanan gateway + data lokal (CLI tetap ada).
Opsi:
- `--service`: hapus layanan gateway
- `--state`: hapus state dan config
- `--workspace`: hapus direktori workspace
- `--app`: hapus app macOS
- `--all`: hapus layanan, state, workspace, dan app
- `--yes`: lewati prompt konfirmasi
- `--non-interactive`: nonaktifkan prompt; memerlukan `--yes`
- `--dry-run`: tampilkan tindakan tanpa menghapus file
Contoh:
```bash
openclaw backup create
openclaw uninstall
openclaw uninstall --service --yes --non-interactive
openclaw uninstall --state --workspace --yes --non-interactive
openclaw uninstall --all --yes
openclaw uninstall --dry-run
```
Catatan:
- Jalankan `openclaw backup create` terlebih dahulu jika Anda ingin snapshot yang dapat dipulihkan sebelum menghapus state atau workspace.
- `--all` adalah singkatan untuk menghapus layanan, state, workspace, dan app sekaligus.
- `--non-interactive` memerlukan `--yes`.

120
docs/id/cli/update.md Normal file
View File

@ -0,0 +1,120 @@
---
read_when:
- Anda ingin memperbarui checkout sumber dengan aman
- Anda perlu memahami perilaku singkatan `--update`
summary: Referensi CLI untuk `openclaw update` (pembaruan sumber yang cukup aman + mulai ulang gateway otomatis)
title: update
x-i18n:
generated_at: "2026-04-05T13:50:34Z"
model: gpt-5.4
provider: openai
source_hash: 12c8098654b644c3666981d379f6c018e84fde56a5420f295d78052f9001bdad
source_path: cli/update.md
workflow: 15
---
# `openclaw update`
Perbarui OpenClaw dengan aman dan beralih antara channel stable/beta/dev.
Jika Anda menginstal melalui **npm/pnpm/bun** (instalasi global, tanpa metadata git),
pembaruan dilakukan melalui alur package manager di [Memperbarui](/install/updating).
## Penggunaan
```bash
openclaw update
openclaw update status
openclaw update wizard
openclaw update --channel beta
openclaw update --channel dev
openclaw update --tag beta
openclaw update --tag main
openclaw update --dry-run
openclaw update --no-restart
openclaw update --yes
openclaw update --json
openclaw --update
```
## Opsi
- `--no-restart`: lewati memulai ulang layanan Gateway setelah pembaruan berhasil.
- `--channel <stable|beta|dev>`: atur channel pembaruan (git + npm; disimpan dalam config).
- `--tag <dist-tag|version|spec>`: timpa target paket hanya untuk pembaruan ini. Untuk instalasi paket, `main` dipetakan ke `github:openclaw/openclaw#main`.
- `--dry-run`: pratinjau tindakan pembaruan yang direncanakan (alur channel/tag/target/restart) tanpa menulis config, menginstal, menyinkronkan plugin, atau memulai ulang.
- `--json`: cetak JSON `UpdateRunResult` yang dapat dibaca mesin.
- `--timeout <seconds>`: batas waktu per langkah (default adalah 1200d).
- `--yes`: lewati prompt konfirmasi (misalnya konfirmasi downgrade)
Catatan: downgrade memerlukan konfirmasi karena versi yang lebih lama dapat merusak konfigurasi.
## `update status`
Tampilkan channel pembaruan aktif + tag/branch/SHA git (untuk checkout sumber), beserta ketersediaan pembaruan.
```bash
openclaw update status
openclaw update status --json
openclaw update status --timeout 10
```
Opsi:
- `--json`: cetak JSON status yang dapat dibaca mesin.
- `--timeout <seconds>`: batas waktu untuk pemeriksaan (default adalah 3d).
## `update wizard`
Alur interaktif untuk memilih channel pembaruan dan mengonfirmasi apakah Gateway
perlu dimulai ulang setelah pembaruan (default-nya adalah dimulai ulang). Jika Anda memilih `dev` tanpa checkout git, perintah ini
menawarkan untuk membuatnya.
Opsi:
- `--timeout <seconds>`: batas waktu untuk setiap langkah pembaruan (default `1200`)
## Yang dilakukan
Saat Anda beralih channel secara eksplisit (`--channel ...`), OpenClaw juga menjaga agar
metode instalasi tetap selaras:
- `dev` → memastikan ada checkout git (default: `~/openclaw`, timpa dengan `OPENCLAW_GIT_DIR`),
memperbaruinya, dan menginstal CLI global dari checkout tersebut.
- `stable` → menginstal dari npm menggunakan `latest`.
- `beta` → lebih memilih dist-tag npm `beta`, tetapi kembali ke `latest` saat beta
tidak ada atau lebih lama daripada rilis stable saat ini.
Pembaruan otomatis inti Gateway (saat diaktifkan melalui config) menggunakan kembali jalur pembaruan yang sama ini.
## Alur checkout git
Channel:
- `stable`: checkout tag non-beta terbaru, lalu build + doctor.
- `beta`: lebih memilih tag `-beta` terbaru, tetapi kembali ke tag stable terbaru
saat beta tidak ada atau lebih lama.
- `dev`: checkout `main`, lalu fetch + rebase.
Tingkat tinggi:
1. Memerlukan worktree yang bersih (tidak ada perubahan yang belum di-commit).
2. Beralih ke channel yang dipilih (tag atau branch).
3. Mengambil dari upstream (hanya dev).
4. Hanya dev: lint prapenerbangan + build TypeScript dalam worktree sementara; jika tip gagal, mundur hingga 10 commit untuk menemukan build bersih terbaru.
5. Rebase ke commit yang dipilih (hanya dev).
6. Menginstal dependensi (lebih memilih pnpm; npm sebagai fallback; bun tetap tersedia sebagai fallback kompatibilitas sekunder).
7. Build + build Control UI.
8. Menjalankan `openclaw doctor` sebagai pemeriksaan akhir “pembaruan aman”.
9. Menyinkronkan plugin ke channel aktif (dev menggunakan extension bawaan; stable/beta menggunakan npm) dan memperbarui plugin yang diinstal melalui npm.
## Singkatan `--update`
`openclaw --update` ditulis ulang menjadi `openclaw update` (berguna untuk shell dan skrip launcher).
## Lihat juga
- `openclaw doctor` (menawarkan untuk menjalankan pembaruan terlebih dahulu pada checkout git)
- [Channel pengembangan](/install/development-channels)
- [Memperbarui](/install/updating)
- [Referensi CLI](/cli)

41
docs/id/cli/voicecall.md Normal file
View File

@ -0,0 +1,41 @@
---
read_when:
- Anda menggunakan plugin panggilan suara dan menginginkan entry point CLI-nya
- Anda menginginkan contoh cepat untuk `voicecall call|continue|status|tail|expose`
summary: Referensi CLI untuk `openclaw voicecall` (permukaan perintah plugin panggilan suara)
title: voicecall
x-i18n:
generated_at: "2026-04-05T13:49:58Z"
model: gpt-5.4
provider: openai
source_hash: 2c99e7a3d256e1c74a0f07faba9675cc5a88b1eb2fc6e22993caf3874d4f340a
source_path: cli/voicecall.md
workflow: 15
---
# `openclaw voicecall`
`voicecall` adalah perintah yang disediakan plugin. Perintah ini hanya muncul jika plugin panggilan suara terpasang dan diaktifkan.
Dokumen utama:
- Plugin panggilan suara: [Voice Call](/plugins/voice-call)
## Perintah umum
```bash
openclaw voicecall status --call-id <id>
openclaw voicecall call --to "+15555550123" --message "Hello" --mode notify
openclaw voicecall continue --call-id <id> --message "Any questions?"
openclaw voicecall end --call-id <id>
```
## Mengekspos webhook (Tailscale)
```bash
openclaw voicecall expose --mode serve
openclaw voicecall expose --mode funnel
openclaw voicecall expose --mode off
```
Catatan keamanan: hanya ekspos endpoint webhook ke jaringan yang Anda percayai. Sebaiknya gunakan Tailscale Serve daripada Funnel jika memungkinkan.

98
docs/id/cli/webhooks.md Normal file
View File

@ -0,0 +1,98 @@
---
read_when:
- Anda ingin menghubungkan event Gmail Pub/Sub ke OpenClaw
- Anda ingin perintah helper webhook
summary: Referensi CLI untuk `openclaw webhooks` (helper webhook + Gmail Pub/Sub)
title: webhooks
x-i18n:
generated_at: "2026-04-05T13:50:26Z"
model: gpt-5.4
provider: openai
source_hash: 2b22ce879c3a94557be57919b4d2b3e92ff4d41fbae7bc88d2ab07cd4bbeac83
source_path: cli/webhooks.md
workflow: 15
---
# `openclaw webhooks`
Helper webhook dan integrasi (Gmail Pub/Sub, helper webhook).
Terkait:
- Webhooks: [Webhooks](/id/automation/cron-jobs#webhooks)
- Gmail Pub/Sub: [Gmail Pub/Sub](/id/automation/cron-jobs#gmail-pubsub-integration)
## Gmail
```bash
openclaw webhooks gmail setup --account you@example.com
openclaw webhooks gmail run
```
### `webhooks gmail setup`
Konfigurasikan Gmail watch, Pub/Sub, dan pengiriman webhook OpenClaw.
Diperlukan:
- `--account <email>`
Opsi:
- `--project <id>`
- `--topic <name>`
- `--subscription <name>`
- `--label <label>`
- `--hook-url <url>`
- `--hook-token <token>`
- `--push-token <token>`
- `--bind <host>`
- `--port <port>`
- `--path <path>`
- `--include-body`
- `--max-bytes <n>`
- `--renew-minutes <n>`
- `--tailscale <funnel|serve|off>`
- `--tailscale-path <path>`
- `--tailscale-target <target>`
- `--push-endpoint <url>`
- `--json`
Contoh:
```bash
openclaw webhooks gmail setup --account you@example.com
openclaw webhooks gmail setup --account you@example.com --project my-gcp-project --json
openclaw webhooks gmail setup --account you@example.com --hook-url https://gateway.example.com/hooks/gmail
```
### `webhooks gmail run`
Jalankan `gog watch serve` beserta loop perpanjangan otomatis watch.
Opsi:
- `--account <email>`
- `--topic <topic>`
- `--subscription <name>`
- `--label <label>`
- `--hook-url <url>`
- `--hook-token <token>`
- `--push-token <token>`
- `--bind <host>`
- `--port <port>`
- `--path <path>`
- `--include-body`
- `--max-bytes <n>`
- `--renew-minutes <n>`
- `--tailscale <funnel|serve|off>`
- `--tailscale-path <path>`
- `--tailscale-target <target>`
Contoh:
```bash
openclaw webhooks gmail run --account you@example.com
```
Lihat [dokumentasi Gmail Pub/Sub](/id/automation/cron-jobs#gmail-pubsub-integration) untuk alur penyiapan end-to-end dan detail operasional.

Some files were not shown because too many files have changed in this diff Show More