Konfigurasi

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

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

Semua channel menggunakan pola kebijakan DM yang sama:

{  channels: {    telegram: {      enabled: true,      botToken: "123:abc",      dmPolicy: "pairing",   // pemasangan | daftar izin | terbuka | dinonaktifkan      allowFrom: ["tg:123"], // hanya untuk daftar izin/terbuka    },  },}

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 menyimpan alias dan pengaturan per model; menambahkan entri tidak pernah membatasi penggantian /model atau --model.
• agents.defaults.modelPolicy.allow adalah daftar izin eksplisit untuk penggantian dan pemilih model. Ini menerima referensi persis dan wildcard provider/*; hilangkan atau gunakan [] untuk mengizinkan model apa pun.
• Referensi model menggunakan format provider/model (misalnya anthropic/claude-opus-4-6).
• agents.defaults.imageMaxDimensionPx mengontrol penurunan skala gambar transkrip/alat (default 1200); nilai yang lebih rendah biasanya mengurangi penggunaan token visi pada proses yang sarat tangkapan layar.
• Lihat CLI Model untuk mengganti model dalam obrolan dan Failover Model untuk rotasi autentikasi dan perilaku fallback.
• Untuk penyedia khusus/yang dihosting sendiri, lihat Penyedia khusus dalam referensi.

Akses DM dikendalikan per channel melalui dmPolicy (default "pairing"):

• "pairing": pengirim tidak dikenal mendapatkan kode pemasangan sekali pakai untuk disetujui
• "allowlist": hanya pengirim dalam allowFrom (atau penyimpanan izin yang telah dipasangkan)
• "open": izinkan semua DM masuk (memerlukan allowFrom: ["*"])
• "disabled": abaikan semua DM

Untuk grup, gunakan groupPolicy ("allowlist" | "open" | "disabled") bersama groupAllowFrom atau daftar izin khusus channel.

Lihat referensi lengkap untuk detail per channel.

Pesan grup secara default memerlukan penyebutan. Konfigurasikan pola pemicu per agen. Balasan grup/channel normal dikirim secara otomatis; aktifkan jalur alat pesan untuk ruang bersama tempat agen harus memutuskan kapan akan berbicara:

{  messages: {    visibleReplies: "automatic", // atur "message_tool" agar pengiriman alat pesan diwajibkan di mana saja    groupChat: {      visibleReplies: "message_tool", // ikut serta; keluaran terlihat memerlukan message(action=send)      unmentionedInbound: "room_event", // percakapan grup selalu aktif tanpa penyebutan menjadi konteks senyap    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@openclaw", "openclaw"],        },      },    ],  },  channels: {    whatsapp: {      groups: { "*": { requireMention: true } },    },  },}

• Penyebutan metadata: @-mention native (ketuk untuk menyebut di WhatsApp, @bot di Telegram, dll.)
• Pola teks: pola regex aman dalam mentionPatterns
• Balasan terlihat: messages.visibleReplies dapat mewajibkan pengiriman alat pesan secara global; messages.groupChat.visibleReplies menggantikannya untuk grup/channel.
• Lihat referensi lengkap untuk mode balasan terlihat, penggantian per channel, dan mode obrolan dengan diri sendiri.

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

{  agents: {    defaults: {      skills: ["github", "weather"],    },    list: [      { id: "writer" }, // mewarisi github, weather      { id: "docs", skills: ["docs-search"] }, // menggantikan nilai default      { id: "locked-down", skills: [] }, // tanpa skills    ],  },}

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

Nonaktifkan atau aktifkan mulai ulang kesehatan otomatis untuk channel atau akun:

{  channels: {    telegram: {      healthMonitor: { enabled: false },      accounts: {        alerts: {          healthMonitor: { enabled: true },        },      },    },  },}

• Gunakan channels.<provider>.healthMonitor.enabled atau channels.<provider>.accounts.<id>.healthMonitor.enabled untuk mengontrol mulai ulang otomatis bagi satu channel atau akun.
• Lihat Pemeriksaan Kesehatan untuk debugging operasional dan referensi lengkap untuk semua bidang.

Sesi mengontrol kesinambungan dan isolasi percakapan:

{  session: {    dmScope: "per-channel-peer",  // direkomendasikan untuk banyak pengguna    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: nilai default global untuk perutean sesi yang terikat ke utas. /focus, /unfocus, /agents, /session idle, dan /session max-age mengikat, melepas ikatan, mencantumkan, dan menyesuaikan ini per sesi (Discord mengikat utas, Telegram mengikat topik/percakapan).
• 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",  // nonaktif | non-main | semua        scope: "agent",    // sesi | agen | bersama      },    },  },}

Buat 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 dihosting: 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",          // Opsional. Default: 10000          timeoutMs: 10000,        },      },    },  },}

Padanan CLI:

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

Fungsinya:

• Memungkinkan gateway mengirim push.test, dorongan untuk membangunkan, dan pembangkitan koneksi ulang melalui relay eksternal.
• Menggunakan izin pengiriman dengan cakupan pendaftaran yang diteruskan oleh aplikasi iOS yang dipasangkan. Gateway tidak memerlukan token relay untuk seluruh deployment.
• Mengikat setiap pendaftaran berbasis relay ke identitas gateway yang dipasangkan dengan aplikasi iOS, sehingga gateway lain tidak dapat menggunakan kembali pendaftaran yang tersimpan.
• Mempertahankan penggunaan APNs langsung untuk build iOS lokal/manual. Pengiriman berbasis relay hanya berlaku untuk build resmi yang didistribusikan dan didaftarkan melalui relay.
• Harus cocok dengan URL dasar relay yang disematkan dalam build iOS agar lalu lintas pendaftaran dan pengiriman mencapai deployment relay yang sama.

Alur menyeluruh:

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 dengan gateway dan biarkan sesi node maupun operator terhubung.
4. Aplikasi iOS mengambil identitas gateway, mendaftar ke relay menggunakan App Attest beserta tanda terima aplikasi, lalu memublikasikan payload push.apns.register berbasis relay ke gateway yang dipasangkan.
5. Gateway menyimpan handle relay dan izin pengiriman, lalu menggunakannya untuk push.test, dorongan untuk membangunkan, dan pembangkitan koneksi ulang.

Catatan operasional:

• Jika Anda mengalihkan aplikasi iOS ke gateway lain, hubungkan kembali aplikasi agar dapat memublikasikan pendaftaran relay baru yang terikat ke gateway tersebut.
• Jika Anda merilis build iOS baru yang mengarah ke deployment relay lain, aplikasi memperbarui pendaftaran relay yang di-cache alih-alih menggunakan kembali asal relay lama.

Catatan kompatibilitas:

• OPENCLAW_APNS_RELAY_BASE_URL dan OPENCLAW_APNS_RELAY_TIMEOUT_MS tetap berfungsi sebagai penggantian sementara melalui variabel lingkungan.
• URL relay gateway khusus harus cocok dengan URL dasar relay yang disematkan dalam build iOS; jalur rilis App Store publik menolak penggantian URL relay iOS khusus.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true tetap menjadi jalur darurat pengembangan khusus loopback; jangan simpan URL relay HTTP dalam konfigurasi.

Lihat Aplikasi iOS untuk alur menyeluruh 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. Default: 30m.
• 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,    sessionRetention: "24h",  },}

• sessionRetention: pangkas sesi eksekusi terisolasi yang telah selesai dari baris sesi SQLite (default 24h; atur false untuk menonaktifkan).
• Riwayat eksekusi secara otomatis menyimpan 2000 baris terminal terbaru per tugas; baris yang hilang tetap mempertahankan jangka waktu pembersihan 24 jam.
• Lihat Tugas Cron untuk ikhtisar 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 kembali rahasia autentikasi Gateway yang aktif (gateway.auth.token / OPENCLAW_GATEWAY_TOKEN atau gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD).
• Autentikasi hook hanya melalui header (Authorization: Bearer ... atau x-openclaw-token); token string kueri ditolak.
• hooks.path tidak boleh berupa /; pertahankan ingress Webhook pada subjalur khusus seperti /hooks.
• Biarkan flag pengabaian konten tidak aman tetap dinonaktifkan (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent), kecuali saat melakukan debugging dengan cakupan yang sangat ketat.
• Jika Anda mengaktifkan hooks.allowRequestSessionKey, atur juga hooks.allowedSessionKeyPrefixes untuk membatasi kunci sesi yang dipilih pemanggil.
• Untuk agen yang digerakkan oleh hook, utamakan tingkat model modern yang kuat dan kebijakan alat yang ketat (misalnya hanya olah pesan ditambah sandboxing jika memungkinkan).

Lihat referensi lengkap untuk semua opsi pemetaan dan integrasi Gmail.

Jalankan beberapa agen terisolasi dengan ruang kerja 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 Multiagen dan referensi lengkap untuk aturan pengikatan 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"],  },}

• Satu file: menggantikan objek yang memuatnya
• Array file: digabungkan secara mendalam sesuai urutan (yang lebih akhir menang), hingga kedalaman 10 tingkat bertingkat
• Kunci sejajar: digabungkan setelah penyertaan (menimpa nilai yang disertakan)
• Jalur relatif: diresolusikan relatif terhadap file yang menyertakan
• Format jalur: jalur penyertaan tidak boleh berisi byte null dan panjangnya harus benar-benar kurang dari 4096 karakter sebelum maupun sesudah resolusi
• Penulisan milik OpenClaw: ketika suatu penulisan hanya mengubah satu bagian tingkat teratas yang didukung oleh penyertaan satu file seperti plugins: { $include: "./plugins.json5" }, OpenClaw memperbarui file yang disertakan tersebut dan membiarkan openclaw.json tetap utuh
• Penulisan tembus yang tidak didukung: penyertaan root, array penyertaan, dan penyertaan dengan penggantian sejajar akan gagal secara tertutup untuk penulisan milik OpenClaw, alih-alih meratakan konfigurasi
• Pembatasan: jalur $include harus diresolusikan di bawah direktori yang menyimpan openclaw.json. Untuk berbagi struktur direktori antar mesin atau pengguna, atur OPENCLAW_INCLUDE_ROOTS ke daftar jalur (: di POSIX, ; di Windows) berisi direktori tambahan yang boleh dirujuk oleh penyertaan. Symlink diresolusikan dan diperiksa kembali, sehingga jalur yang secara leksikal berada dalam direktori konfigurasi tetapi target sebenarnya keluar dari setiap root yang diizinkan tetap ditolak.
• Penanganan kesalahan: kesalahan yang jelas untuk file yang tidak ditemukan, kesalahan penguraian, penyertaan melingkar, format jalur tidak valid, dan panjang berlebihan