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 berbagi 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.
• Gunakan openclaw config set agents.defaults.models '<json>' --strict-json --merge untuk menambahkan entri allowlist tanpa menghapus model yang sudah ada. Penggantian biasa yang akan menghapus entri ditolak kecuali Anda meneruskan --replace.
• Referensi model menggunakan format provider/model (misalnya anthropic/claude-opus-4-6).
• agents.defaults.imageMaxDimensionPx mengontrol downscaling gambar transkrip/tool (default 1200); nilai yang lebih rendah biasanya mengurangi penggunaan vision-token pada run yang banyak screenshot.
• Lihat CLI Model untuk mengganti model dalam chat dan Failover Model untuk rotasi auth dan perilaku fallback.
• Untuk penyedia kustom/self-hosted, lihat Penyedia kustom di referensi.

Akses DM dikontrol per saluran melalui dmPolicy:

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

Untuk grup, gunakan groupPolicy + groupAllowFrom atau daftar izin khusus saluran.

Lihat referensi lengkap untuk detail per saluran.

Pesan grup secara default memerlukan penyebutan. Konfigurasikan pola pemicu per agen, dan pertahankan balasan ruang yang terlihat pada jalur message-tool default kecuali Anda memang menginginkan balasan akhir otomatis lama:

{
  messages: {
    visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere
    groupChat: {
      visibleReplies: "message_tool", // default; use "automatic" for legacy room replies
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}

• Penyebutan metadata: @-mention native (WhatsApp tap-to-mention, Telegram @bot, 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/saluran.
• Lihat referensi lengkap untuk mode balasan terlihat, penimpaan per saluran, dan mode obrolan mandiri.

Gunakan agents.defaults.skills sebagai baseline bersama, lalu timpa agen 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 untuk Skills yang tidak dibatasi secara default.
• Hilangkan agents.list[].skills untuk mewarisi default.
• Tetapkan agents.list[].skills: [] untuk tanpa Skills.
• Lihat Skills, konfigurasi Skills, dan Referensi Konfigurasi.

Kontrol seberapa agresif Gateway memulai ulang saluran yang tampak stale:

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

• Tetapkan gateway.channelHealthCheckMinutes: 0 untuk menonaktifkan restart pemantauan kesehatan 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 bagi satu saluran atau akun tanpa menonaktifkan pemantau global.
• Lihat Pemeriksaan Kesehatan untuk debugging operasional dan referensi lengkap untuk semua bidang.

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

{
  gateway: {
    handshakeTimeoutMs: 30000,
  },
}

• Default-nya adalah 15000 milidetik.
• OPENCLAW_HANDSHAKE_TIMEOUT_MS tetap diprioritaskan untuk penimpaan layanan atau shell sekali jalan.
• Utamakan memperbaiki stall startup/event-loop terlebih dahulu; knob ini untuk host yang sehat tetapi lambat selama 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 berbasis 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 terisolasi:

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

Build 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 dikonfigurasi di openclaw.json.

Atur ini di 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, dorongan bangun, dan bangun sambung ulang melalui relay eksternal.
• Menggunakan izin kirim berskala 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 tersimpan.
• Mempertahankan build iOS lokal/manual pada APNs langsung. Pengiriman berbasis relay hanya berlaku untuk build terdistribusi resmi yang mendaftar melalui relay.
• Harus cocok dengan URL dasar relay yang disematkan ke build iOS resmi/TestFlight, sehingga lalu lintas registrasi dan pengiriman mencapai deployment relay yang sama.

Alur end-to-end:

1. Instal build iOS resmi/TestFlight yang dikompilasi dengan URL dasar relay yang sama.
2. Konfigurasikan gateway.push.apns.relay.baseUrl pada gateway.
3. Pasangkan aplikasi iOS ke gateway dan biarkan sesi node dan operator terhubung.
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 izin kirim, lalu menggunakannya untuk push.test, dorongan 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 mengarah ke deployment relay berbeda, aplikasi menyegarkan registrasi relay yang di-cache alih-alih menggunakan ulang asal relay lama.

Catatan kompatibilitas:

• OPENCLAW_APNS_RELAY_BASE_URL dan OPENCLAW_APNS_RELAY_TIMEOUT_MS masih berfungsi sebagai override env sementara.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true tetap menjadi jalan keluar pengembangan khusus loopback; jangan simpan URL relay HTTP di konfigurasi.

Lihat Aplikasi iOS untuk alur end-to-end 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: 2, // cron dispatch + isolated cron agent-turn execution
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}

• sessionRetention: pangkas sesi eksekusi terisolasi yang selesai dari sessions.json (default 24h; atur false untuk menonaktifkan).
• runLog: pangkas cron/runs/<jobId>.jsonl berdasarkan ukuran dan baris yang dipertahankan.
• Lihat Tugas 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 tidak tepercaya.
• Gunakan hooks.token khusus; jangan gunakan ulang token Gateway bersama.
• Autentikasi hook hanya melalui header (Authorization: Bearer ... atau x-openclaw-token); token query-string ditolak.
• hooks.path tidak boleh berupa /; tempatkan ingress Webhook pada subpath khusus seperti /hooks.
• Biarkan flag bypass konten tidak aman tetap nonaktif (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent) kecuali saat melakukan debugging dengan cakupan ketat.
• Jika Anda mengaktifkan hooks.allowRequestSessionKey, atur juga hooks.allowedSessionKeyPrefixes untuk membatasi kunci sesi yang dipilih pemanggil.
• Untuk agen yang digerakkan hook, pilih tingkat model modern yang kuat dan kebijakan alat yang ketat (misalnya hanya messaging plus sandboxing jika memungkinkan).

Lihat referensi lengkap untuk semua opsi mapping 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: mengganti objek yang memuatnya
• Array file: digabung mendalam secara berurutan (yang terakhir menang)
• Kunci sejajar: digabung setelah include (menimpa nilai yang di-include)
• Include bersarang: didukung hingga 10 level
• Path relatif: diselesaikan relatif terhadap file yang melakukan include
• Penulisan milik OpenClaw: ketika penulisan hanya mengubah satu bagian tingkat atas 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 tidak didukung: include root, array include, dan include dengan override kunci sejajar gagal tertutup untuk penulisan milik OpenClaw alih-alih meratakan konfigurasi
• Pembatasan: path $include harus diselesaikan di bawah direktori yang memuat openclaw.json. Untuk berbagi tree lintas mesin atau pengguna, atur OPENCLAW_INCLUDE_ROOTS ke daftar path (: di POSIX, ; di Windows) dari direktori tambahan yang dapat dirujuk oleh include. Symlink diselesaikan dan diperiksa ulang, sehingga path yang secara leksikal berada di dir konfigurasi tetapi target nyatanya keluar dari setiap root yang diizinkan tetap ditolak.
• Penanganan error: error yang jelas untuk file hilang, error parse, dan include melingkar