Konfigurasi

Setiap channel memiliki bagian konfigurasinya sendiri di bawah channels.<provider>. Lihat halaman channel khusus untuk langkah penyiapan:

• WhatsApp - channels.whatsapp
• Telegram - channels.telegram
• Discord - channels.discord
• Feishu - channels.feishu
• Google Chat - channels.googlechat
• Microsoft Teams - channels.msteams
• Slack - channels.slack
• Signal - channels.signal
• iMessage - channels.imessage
• Mattermost - channels.mattermost

Semua channel menggunakan pola kebijakan DM yang sama:

{  channels: {    telegram: {      enabled: true,      botToken: "123:abc",      dmPolicy: "pairing",   // pairing | allowlist | open | disabled      allowFrom: ["tg:123"], // only for allowlist/open    },  },}

Atur model utama dan fallback opsional:

{  agents: {    defaults: {      model: {        primary: "anthropic/claude-sonnet-4-6",        fallbacks: ["openai/gpt-5.4"],      },      models: {        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },        "openai/gpt-5.4": { alias: "GPT" },      },    },  },}

• agents.defaults.models mendefinisikan katalog model dan bertindak sebagai allowlist untuk /model; entri provider/* memfilter /model, /models, dan pemilih model ke provider yang dipilih sambil tetap menggunakan penemuan model dinamis.
• Gunakan openclaw config set agents.defaults.models '<json>' --strict-json --merge untuk menambahkan entri allowlist tanpa menghapus model yang ada. Penggantian biasa yang akan menghapus entri ditolak kecuali Anda meneruskan --replace.
• Referensi model menggunakan format provider/model (mis. anthropic/claude-opus-4-6).
• agents.defaults.imageMaxDimensionPx mengontrol downscaling gambar transkrip/alat (default 1200); nilai yang lebih rendah biasanya mengurangi penggunaan token vision pada run yang banyak screenshot.
• Lihat CLI Model untuk mengganti model di chat dan Failover Model untuk rotasi autentikasi dan perilaku fallback.
• Untuk provider kustom/self-hosted, lihat Provider kustom di referensi.

Akses DM dikontrol per channel melalui dmPolicy:

• "pairing" (default): pengirim tidak dikenal mendapatkan kode pairing satu kali untuk disetujui
• "allowlist": hanya pengirim di allowFrom (atau penyimpanan allow yang sudah dipasangkan)
• "open": izinkan semua DM masuk (memerlukan allowFrom: ["*"])
• "disabled": abaikan semua DM

Untuk grup, gunakan groupPolicy + groupAllowFrom atau allowlist khusus channel.

Lihat referensi lengkap untuk detail per channel.

Pesan grup secara default memerlukan mention. Konfigurasikan pola pemicu per agent. Balasan grup/channel normal diposting secara otomatis; pilih path message-tool untuk room bersama tempat agent harus memutuskan kapan berbicara:

{  messages: {    visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere    groupChat: {      visibleReplies: "message_tool", // opt-in; visible output requires message(action=send)      unmentionedInbound: "room_event", // unmentioned always-on group chatter is quiet context    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@openclaw", "openclaw"],        },      },    ],  },  channels: {    whatsapp: {      groups: { "*": { requireMention: true } },    },  },}

• Mention metadata: @-mention native (tap-to-mention WhatsApp, @bot Telegram, dll.)
• Pola teks: pola regex aman di mentionPatterns
• Balasan terlihat: messages.visibleReplies dapat mewajibkan pengiriman message-tool secara global; messages.groupChat.visibleReplies menimpanya untuk grup/channel.
• Lihat referensi lengkap untuk mode balasan terlihat, override per channel, dan mode self-chat.

Gunakan agents.defaults.skills untuk baseline bersama, lalu override agent tertentu dengan agents.list[].skills:

{  agents: {    defaults: {      skills: ["github", "weather"],    },    list: [      { id: "writer" }, // inherits github, weather      { id: "docs", skills: ["docs-search"] }, // replaces defaults      { id: "locked-down", skills: [] }, // no skills    ],  },}

• Hilangkan agents.defaults.skills agar Skills tidak dibatasi secara default.
• Hilangkan agents.list[].skills untuk mewarisi default.
• Atur agents.list[].skills: [] agar tidak ada Skills.
• Lihat Skills, Konfigurasi Skills, dan Referensi Konfigurasi.

Kontrol seberapa agresif Gateway memulai ulang channel yang terlihat stale:

{  gateway: {    channelHealthCheckMinutes: 5,    channelStaleEventThresholdMinutes: 30,    channelMaxRestartsPerHour: 10,  },  channels: {    telegram: {      healthMonitor: { enabled: false },      accounts: {        alerts: {          healthMonitor: { enabled: true },        },      },    },  },}

• Atur gateway.channelHealthCheckMinutes: 0 untuk menonaktifkan restart health-monitor secara global.
• channelStaleEventThresholdMinutes harus lebih besar dari atau sama dengan interval pemeriksaan.
• Gunakan channels.<provider>.healthMonitor.enabled atau channels.<provider>.accounts.<id>.healthMonitor.enabled untuk menonaktifkan restart otomatis untuk satu channel atau akun tanpa menonaktifkan monitor global.
• Lihat Health Check untuk debugging operasional dan referensi lengkap untuk semua field.

Beri client lokal lebih banyak waktu untuk menyelesaikan handshake WebSocket pra-auth pada host yang terbebani atau berdaya rendah:

{  gateway: {    handshakeTimeoutMs: 30000,  },}

• Default-nya adalah 15000 milidetik.
• OPENCLAW_HANDSHAKE_TIMEOUT_MS tetap didahulukan untuk override service atau shell satu kali.
• Lebih baik perbaiki stall startup/event-loop terlebih dahulu; knob ini untuk host yang sehat tetapi lambat saat warmup.

Sesi mengontrol kontinuitas dan isolasi percakapan:

{  session: {    dmScope: "per-channel-peer",  // recommended for multi-user    threadBindings: {      enabled: true,      idleHours: 24,      maxAgeHours: 0,    },    reset: {      mode: "daily",      atHour: 4,      idleMinutes: 120,    },  },}

• dmScope: main (bersama) | per-peer | per-channel-peer | per-account-channel-peer
• threadBindings: default global untuk perutean sesi yang terikat thread (Discord mendukung /focus, /unfocus, /agents, /session idle, dan /session max-age).
• Lihat Manajemen Sesi untuk cakupan, tautan identitas, dan kebijakan pengiriman.
• Lihat referensi lengkap untuk semua bidang.

Jalankan sesi agen dalam runtime sandbox yang terisolasi:

{  agents: {    defaults: {      sandbox: {        mode: "non-main",  // off | non-main | all        scope: "agent",    // session | agent | shared      },    },  },}

Bangun image terlebih dahulu - dari checkout sumber jalankan scripts/sandbox-setup.sh, atau dari instalasi npm lihat perintah inline docker build di Sandboxing § Image dan penyiapan.

Lihat Sandboxing untuk panduan lengkap dan referensi lengkap untuk semua opsi.

Push berbasis relay untuk build App Store publik menggunakan relay OpenClaw yang di-host: https://ios-push-relay.openclaw.ai.

Deployment relay khusus memerlukan jalur build/deployment iOS yang sengaja dipisahkan, dengan URL relay yang cocok dengan URL relay gateway. Jika Anda menggunakan build relay khusus, atur ini dalam konfigurasi gateway:

{  gateway: {    push: {      apns: {        relay: {          baseUrl: "https://relay.example.com",          // Optional. Default: 10000          timeoutMs: 10000,        },      },    },  },}

Padanan CLI:

openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com

Yang dilakukan ini:

• Memungkinkan gateway mengirim push.test, sinyal bangun, dan bangun sambung ulang melalui relay eksternal.
• Menggunakan grant pengiriman bercakupan registrasi yang diteruskan oleh aplikasi iOS yang dipasangkan. Gateway tidak memerlukan token relay untuk seluruh deployment.
• Mengikat setiap registrasi berbasis relay ke identitas gateway yang dipasangkan dengan aplikasi iOS, sehingga gateway lain tidak dapat menggunakan ulang registrasi yang tersimpan.
• Mempertahankan build iOS lokal/manual pada APNs langsung. Pengiriman berbasis relay hanya berlaku untuk build resmi terdistribusi yang terdaftar melalui relay.
• Harus cocok dengan URL dasar relay yang dibenamkan ke dalam build iOS, agar lalu lintas registrasi dan pengiriman mencapai deployment relay yang sama.

Alur ujung ke ujung:

1. Instal aplikasi iOS resmi.
2. Opsional: konfigurasikan gateway.push.apns.relay.baseUrl pada gateway hanya saat menggunakan build relay khusus yang sengaja dipisahkan.
3. Pasangkan aplikasi iOS ke gateway dan biarkan sesi node serta operator tersambung.
4. Aplikasi iOS mengambil identitas gateway, mendaftar ke relay menggunakan App Attest plus tanda terima aplikasi, lalu menerbitkan payload push.apns.register berbasis relay ke gateway yang dipasangkan.
5. Gateway menyimpan handle relay dan grant pengiriman, lalu menggunakannya untuk push.test, sinyal bangun, dan bangun sambung ulang.

Catatan operasional:

• Jika Anda mengalihkan aplikasi iOS ke gateway lain, sambungkan ulang aplikasi agar dapat menerbitkan registrasi relay baru yang terikat ke gateway tersebut.
• Jika Anda mengirim build iOS baru yang menunjuk ke deployment relay lain, aplikasi menyegarkan registrasi relay yang di-cache, bukan menggunakan ulang asal relay lama.

Catatan kompatibilitas:

• OPENCLAW_APNS_RELAY_BASE_URL dan OPENCLAW_APNS_RELAY_TIMEOUT_MS masih berfungsi sebagai override env sementara.
• URL relay gateway khusus harus cocok dengan URL dasar relay yang dibenamkan ke dalam build iOS. Jalur rilis App Store publik menolak override URL relay iOS khusus.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true tetap menjadi celah pengembangan khusus loopback; jangan simpan URL relay HTTP dalam konfigurasi.

Lihat Aplikasi iOS untuk alur ujung ke ujung dan Alur autentikasi dan kepercayaan untuk model keamanan relay.

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last",      },    },  },}

• every: string durasi (30m, 2h). Atur 0m untuk menonaktifkan.
• target: last | none | <channel-id> (misalnya discord, matrix, telegram, atau whatsapp)
• directPolicy: allow (default) atau block untuk target Heartbeat bergaya DM
• Lihat Heartbeat untuk panduan lengkap.

{  cron: {    enabled: true,    maxConcurrentRuns: 8, // default; cron dispatch + isolated cron agent-turn execution    sessionRetention: "24h",    runLog: {      maxBytes: "2mb",      keepLines: 2000,    },  },}

• sessionRetention: pangkas sesi run terisolasi yang telah selesai dari sessions.json (default 24h; atur false untuk menonaktifkan).
• runLog: pangkas baris riwayat run Cron yang dipertahankan per pekerjaan. maxBytes tetap diterima untuk log run lama berbasis file.
• Lihat Pekerjaan cron untuk ringkasan fitur dan contoh CLI.

Aktifkan endpoint Webhook HTTP pada Gateway:

{  hooks: {    enabled: true,    token: "shared-secret",    path: "/hooks",    defaultSessionKey: "hook:ingress",    allowRequestSessionKey: false,    allowedSessionKeyPrefixes: ["hook:"],    mappings: [      {        match: { path: "gmail" },        action: "agent",        agentId: "main",        deliver: true,      },    ],  },}

Catatan keamanan:

• Perlakukan semua konten payload hook/webhook sebagai input yang tidak tepercaya.
• Gunakan hooks.token khusus; jangan gunakan ulang rahasia auth Gateway aktif (gateway.auth.token / OPENCLAW_GATEWAY_TOKEN atau gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD).
• Auth hook hanya melalui header (Authorization: Bearer ... atau x-openclaw-token); token query-string ditolak.
• hooks.path tidak boleh /; pertahankan ingress Webhook pada subpath khusus seperti /hooks.
• Biarkan flag bypass konten tidak aman tetap dinonaktifkan (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent) kecuali untuk debugging yang cakupannya sangat ketat.
• Jika Anda mengaktifkan hooks.allowRequestSessionKey, atur juga hooks.allowedSessionKeyPrefixes untuk membatasi kunci sesi yang dipilih pemanggil.
• Untuk agen yang digerakkan hook, pilih tier model modern yang kuat dan kebijakan tool yang ketat (misalnya hanya perpesanan plus sandboxing jika memungkinkan).

Lihat referensi lengkap untuk semua opsi pemetaan dan integrasi Gmail.

Jalankan beberapa agen terisolasi dengan workspace dan sesi terpisah:

{  agents: {    list: [      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },      { id: "work", workspace: "~/.openclaw/workspace-work" },    ],  },  bindings: [    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },  ],}

Lihat Multi-Agen dan referensi lengkap untuk aturan binding dan profil akses per agen.

Gunakan $include untuk mengatur konfigurasi besar:

// ~/.openclaw/openclaw.json{  gateway: { port: 18789 },  agents: { $include: "./agents.json5" },  broadcast: {    $include: ["./clients/a.json5", "./clients/b.json5"],  },}

• File tunggal: menggantikan objek yang memuatnya
• Array file: di-deep-merge secara berurutan (yang belakangan menang)
• Kunci saudara: digabung setelah include (menimpa nilai yang di-include)
• Include bertingkat: didukung hingga kedalaman 10 level
• Path relatif: diselesaikan relatif terhadap file yang menyertakan
• Format path: path include tidak boleh berisi byte null dan harus benar-benar lebih pendek dari 4096 karakter sebelum dan sesudah resolusi
• Penulisan milik OpenClaw: saat penulisan hanya mengubah satu bagian top-level yang didukung oleh include file tunggal seperti plugins: { $include: "./plugins.json5" }, OpenClaw memperbarui file yang di-include tersebut dan membiarkan openclaw.json tetap utuh
• Write-through yang tidak didukung: include root, array include, dan include dengan override saudara gagal tertutup untuk penulisan milik OpenClaw, alih-alih meratakan konfigurasi
• Pembatasan: path $include harus terselesaikan di bawah direktori yang berisi openclaw.json. Untuk berbagi tree lintas mesin atau pengguna, atur OPENCLAW_INCLUDE_ROOTS ke daftar path (: pada POSIX, ; pada Windows) dari direktori tambahan yang dapat dirujuk oleh include. Symlink diselesaikan dan diperiksa ulang, sehingga path yang secara leksikal berada dalam dir konfigurasi tetapi target nyatanya keluar dari setiap root yang diizinkan tetap ditolak.
• Penanganan error: error yang jelas untuk file yang hilang, error parse, include melingkar, format path tidak valid, dan panjang berlebihan