​

Referensi Konfigurasi

• openclaw config schema mencetak JSON Schema aktif yang digunakan untuk validasi dan Control UI, dengan metadata bundled/plugin/channel digabungkan bila tersedia
• config.schema.lookup mengembalikan satu node skema yang dicakup jalur untuk alat penelusuran mendalam
• pnpm config:docs:check / pnpm config:docs:gen memvalidasi hash baseline dokumen konfigurasi terhadap permukaan skema saat ini

• Referensi konfigurasi memori untuk agents.defaults.memorySearch.*, memory.qmd.*, memory.citations, dan konfigurasi dreaming di bawah plugins.entries.memory-core.config.dreaming
• Slash Commands untuk katalog perintah bawaan + bundled saat ini
• halaman channel/plugin pemilik untuk permukaan perintah khusus channel

​

Channels

​

Akses DM dan grup

​

Override model channel

{
  channels: {
    modelByChannel: {
      discord: {
        "123456789012345678": "anthropic/claude-opus-4-6",
      },
      slack: {
        C1234567890: "openai/gpt-4.1",
      },
      telegram: {
        "-1001234567890": "openai/gpt-4.1-mini",
        "-1001234567890:topic:99": "anthropic/claude-sonnet-4-6",
      },
    },
  },
}

​

Default channel dan heartbeat

{
  channels: {
    defaults: {
      groupPolicy: "allowlist", // open | allowlist | disabled
      contextVisibility: "all", // all | allowlist | allowlist_quote
      heartbeat: {
        showOk: false,
        showAlerts: true,
        useIndicator: true,
      },
    },
  },
}

• channels.defaults.groupPolicy: kebijakan grup fallback saat groupPolicy tingkat provider tidak diatur.
• channels.defaults.contextVisibility: mode visibilitas konteks tambahan default untuk semua channel. Nilai: all (default, sertakan semua konteks kutipan/thread/riwayat), allowlist (hanya sertakan konteks dari pengirim yang diizinkan), allowlist_quote (sama seperti allowlist tetapi pertahankan konteks kutipan/balasan eksplisit). Override per channel: channels.<channel>.contextVisibility.
• channels.defaults.heartbeat.showOk: sertakan status channel yang sehat dalam output heartbeat.
• channels.defaults.heartbeat.showAlerts: sertakan status menurun/error dalam output heartbeat.
• channels.defaults.heartbeat.useIndicator: tampilkan output heartbeat bergaya indikator yang ringkas.

​

WhatsApp

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000,
      chunkMode: "length", // length | newline
      mediaMaxMb: 50,
      sendReadReceipts: true, // centang biru (false dalam mode chat ke diri sendiri)
      groups: {
        "*": { requireMention: true },
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
  web: {
    enabled: true,
    heartbeatSeconds: 60,
    reconnect: {
      initialMs: 2000,
      maxMs: 120000,
      factor: 1.4,
      jitter: 0.2,
      maxAttempts: 0,
    },
  },
}

{
  channels: {
    whatsapp: {
      accounts: {
        default: {},
        personal: {},
        biz: {
          // authDir: "~/.openclaw/credentials/whatsapp/biz",
        },
      },
    },
  },
}

​

Telegram

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing",
      allowFrom: ["tg:123456789"],
      groups: {
        "*": { requireMention: true },
        "-1001234567890": {
          allowFrom: ["@admin"],
          systemPrompt: "Keep answers brief.",
          topics: {
            "99": {
              requireMention: false,
              skills: ["search"],
              systemPrompt: "Stay on topic.",
            },
          },
        },
      },
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
      historyLimit: 50,
      replyToMode: "first", // off | first | all | batched
      linkPreview: true,
      streaming: "partial", // off | partial | block | progress (default: off; aktifkan secara eksplisit untuk menghindari batas laju edit pratinjau)
      actions: { reactions: true, sendMessage: true },
      reactionNotifications: "own", // off | own | all
      mediaMaxMb: 100,
      retry: {
        attempts: 3,
        minDelayMs: 400,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
      network: {
        autoSelectFamily: true,
        dnsResultOrder: "ipv4first",
      },
      proxy: "socks5://localhost:9050",
      webhookUrl: "https://example.com/telegram-webhook",
      webhookSecret: "secret",
      webhookPath: "/telegram-webhook",
    },
  },
}

• Token bot: channels.telegram.botToken atau channels.telegram.tokenFile (hanya file biasa; symlink ditolak), dengan TELEGRAM_BOT_TOKEN sebagai fallback untuk akun default.
• channels.telegram.defaultAccount opsional menggantikan pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi.
• Dalam penyiapan multi-akun (2+ ID akun), tetapkan default eksplisit (channels.telegram.defaultAccount atau channels.telegram.accounts.default) untuk menghindari perutean fallback; openclaw doctor memberi peringatan saat ini tidak ada atau tidak valid.
• configWrites: false memblokir penulisan konfigurasi yang dipicu Telegram (migrasi ID supergroup, /config set|unset).
• Entri bindings[] tingkat atas dengan type: "acp" mengonfigurasi binding ACP persisten untuk topik forum (gunakan chatId:topic:topicId kanonis di match.peer.id). Semantik bidang dibagikan di ACP Agents.
• Pratinjau stream Telegram menggunakan sendMessage + editMessageText (berfungsi di chat langsung dan grup).
• Kebijakan retry: lihat Kebijakan retry.

​

Discord

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      mediaMaxMb: 100,
      allowBots: false,
      actions: {
        reactions: true,
        stickers: true,
        polls: true,
        permissions: true,
        messages: true,
        threads: true,
        pins: true,
        search: true,
        memberInfo: true,
        roleInfo: true,
        roles: false,
        channelInfo: true,
        voiceStatus: true,
        events: true,
        moderation: false,
      },
      replyToMode: "off", // off | first | all | batched
      dmPolicy: "pairing",
      allowFrom: ["1234567890", "123456789012345678"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["openclaw-dm"] },
      guilds: {
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          ignoreOtherMentions: true,
          reactionNotifications: "own",
          users: ["987654321098765432"],
          channels: {
            general: { allow: true },
            help: {
              allow: true,
              requireMention: true,
              users: ["987654321098765432"],
              skills: ["docs"],
              systemPrompt: "Short answers only.",
            },
          },
        },
      },
      historyLimit: 20,
      textChunkLimit: 2000,
      chunkMode: "length", // length | newline
      streaming: "off", // off | partial | block | progress (progress dipetakan ke partial di Discord)
      maxLinesPerMessage: 17,
      ui: {
        components: {
          accentColor: "#5865F2",
        },
      },
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSubagentSessions: false, // opt-in untuk sessions_spawn({ thread: true })
      },
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        tts: {
          provider: "openai",
          openai: { voice: "alloy" },
        },
      },
      execApprovals: {
        enabled: "auto", // true | false | "auto"
        approvers: ["987654321098765432"],
        agentFilter: ["default"],
        sessionFilter: ["discord:"],
        target: "dm", // dm | channel | both
        cleanupAfterResolve: false,
      },
      retry: {
        attempts: 3,
        minDelayMs: 500,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
    },
  },
}

• Token: channels.discord.token, dengan DISCORD_BOT_TOKEN sebagai fallback untuk akun default.
• Panggilan keluar langsung yang memberikan token Discord eksplisit menggunakan token tersebut untuk panggilan; pengaturan retry/kebijakan akun tetap berasal dari akun yang dipilih dalam snapshot runtime aktif.
• channels.discord.defaultAccount opsional menggantikan pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi.
• Gunakan user:<id> (DM) atau channel:<id> (channel guild) untuk target pengiriman; ID numerik tanpa awalan ditolak.
• Slug guild menggunakan huruf kecil dengan spasi diganti menjadi -; kunci channel menggunakan nama yang sudah di-slug (tanpa #). Lebih disarankan menggunakan ID guild.
• Pesan yang ditulis bot diabaikan secara default. allowBots: true mengaktifkannya; gunakan allowBots: "mentions" untuk hanya menerima pesan bot yang menyebut bot (pesan sendiri tetap difilter).
• channels.discord.guilds.<id>.ignoreOtherMentions (dan override channel) menghapus pesan yang menyebut pengguna atau role lain tetapi tidak menyebut bot (tidak termasuk @everyone/@here).
• maxLinesPerMessage (default 17) membagi pesan yang tinggi meskipun di bawah 2000 karakter.
• channels.discord.threadBindings mengontrol perutean terikat thread Discord:
  • enabled: override Discord untuk fitur sesi terikat thread (/focus, /unfocus, /agents, /session idle, /session max-age, serta pengiriman/perutean terikat)
  • idleHours: override Discord untuk auto-unfocus karena tidak aktif dalam jam (0 menonaktifkan)
  • maxAgeHours: override Discord untuk usia maksimum keras dalam jam (0 menonaktifkan)
  • spawnSubagentSessions: sakelar opt-in untuk pembuatan/pengikatan thread otomatis sessions_spawn({ thread: true })
• Entri bindings[] tingkat atas dengan type: "acp" mengonfigurasi binding ACP persisten untuk channel dan thread (gunakan ID channel/thread di match.peer.id). Semantik bidang dibagikan di ACP Agents.
• channels.discord.ui.components.accentColor menetapkan warna aksen untuk kontainer komponen Discord v2.
• channels.discord.voice mengaktifkan percakapan channel suara Discord dan override auto-join + TTS opsional.
• channels.discord.voice.daveEncryption dan channels.discord.voice.decryptionFailureTolerance diteruskan ke opsi DAVE @discordjs/voice (true dan 24 secara default).
• OpenClaw juga mencoba pemulihan penerimaan suara dengan keluar/bergabung ulang ke sesi suara setelah kegagalan dekripsi berulang.
• channels.discord.streaming adalah kunci mode stream kanonis. Nilai boolean streamMode dan streaming lama dimigrasikan secara otomatis.
• channels.discord.autoPresence memetakan ketersediaan runtime ke presence bot (healthy => online, degraded => idle, exhausted => dnd) dan mengizinkan override teks status opsional.
• channels.discord.dangerouslyAllowNameMatching mengaktifkan kembali pencocokan nama/tag yang dapat berubah (mode kompatibilitas break-glass).
• channels.discord.execApprovals: pengiriman persetujuan exec native Discord dan otorisasi pemberi persetujuan.
  • enabled: true, false, atau "auto" (default). Dalam mode auto, persetujuan exec aktif saat pemberi persetujuan dapat di-resolve dari approvers atau commands.ownerAllowFrom.
  • approvers: ID pengguna Discord yang diizinkan untuk menyetujui permintaan exec. Fallback ke commands.ownerAllowFrom saat dihilangkan.
  • agentFilter: allowlist ID agen opsional. Hilangkan untuk meneruskan persetujuan bagi semua agen.
  • sessionFilter: pola kunci sesi opsional (substring atau regex).
  • target: tempat mengirim prompt persetujuan. "dm" (default) mengirim ke DM pemberi persetujuan, "channel" mengirim ke channel asal, "both" mengirim ke keduanya. Saat target mencakup "channel", tombol hanya dapat digunakan oleh pemberi persetujuan yang berhasil di-resolve.
  • cleanupAfterResolve: saat true, menghapus DM persetujuan setelah persetujuan, penolakan, atau timeout.

​

Google Chat

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      audienceType: "app-url", // app-url | project-number
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890",
      dm: {
        enabled: true,
        policy: "pairing",
        allowFrom: ["users/1234567890"],
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": { allow: true, requireMention: true },
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}

• JSON akun layanan: inline (serviceAccount) atau berbasis file (serviceAccountFile).
• SecretRef akun layanan juga didukung (serviceAccountRef).
• Fallback env: GOOGLE_CHAT_SERVICE_ACCOUNT atau GOOGLE_CHAT_SERVICE_ACCOUNT_FILE.
• Gunakan spaces/<spaceId> atau users/<userId> untuk target pengiriman.
• channels.googlechat.dangerouslyAllowNameMatching mengaktifkan kembali pencocokan principal email yang dapat berubah (mode kompatibilitas break-glass).

​

Slack

{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      appToken: "xapp-...",
      dmPolicy: "pairing",
      allowFrom: ["U123", "U456", "*"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["G123"] },
      channels: {
        C123: { allow: true, requireMention: true, allowBots: false },
        "#general": {
          allow: true,
          requireMention: true,
          allowBots: false,
          users: ["U123"],
          skills: ["docs"],
          systemPrompt: "Short answers only.",
        },
      },
      historyLimit: 50,
      allowBots: false,
      reactionNotifications: "own",
      reactionAllowlist: ["U123"],
      replyToMode: "off", // off | first | all | batched
      thread: {
        historyScope: "thread", // thread | channel
        inheritParent: false,
      },
      actions: {
        reactions: true,
        messages: true,
        pins: true,
        memberInfo: true,
        emojiList: true,
      },
      slashCommand: {
        enabled: true,
        name: "openclaw",
        sessionPrefix: "slack:slash",
        ephemeral: true,
      },
      typingReaction: "hourglass_flowing_sand",
      textChunkLimit: 4000,
      chunkMode: "length",
      streaming: {
        mode: "partial", // off | partial | block | progress
        nativeTransport: true, // gunakan API streaming native Slack saat mode=partial
      },
      mediaMaxMb: 20,
      execApprovals: {
        enabled: "auto", // true | false | "auto"
        approvers: ["U123"],
        agentFilter: ["default"],
        sessionFilter: ["slack:"],
        target: "dm", // dm | channel | both
      },
    },
  },
}

• Mode socket memerlukan botToken dan appToken (SLACK_BOT_TOKEN + SLACK_APP_TOKEN untuk fallback env akun default).
• Mode HTTP memerlukan botToken ditambah signingSecret (di root atau per akun).
• botToken, appToken, signingSecret, dan userToken menerima string plaintext atau objek SecretRef.
• Snapshot akun Slack mengekspos bidang sumber/status per kredensial seperti botTokenSource, botTokenStatus, appTokenStatus, dan, dalam mode HTTP, signingSecretStatus. configured_unavailable berarti akun dikonfigurasi melalui SecretRef tetapi jalur perintah/runtime saat ini tidak dapat me-resolve nilai secret.
• configWrites: false memblokir penulisan konfigurasi yang dipicu Slack.
• channels.slack.defaultAccount opsional menggantikan pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi.
• channels.slack.streaming.mode adalah kunci mode stream Slack kanonis. channels.slack.streaming.nativeTransport mengontrol transport streaming native Slack. Nilai lama streamMode, boolean streaming, dan nativeStreaming dimigrasikan secara otomatis.
• Gunakan user:<id> (DM) atau channel:<id> untuk target pengiriman.

• Streaming native Slack ditambah status thread bergaya asisten Slack “is typing…” memerlukan target thread balasan. DM tingkat atas tetap off-thread secara default, sehingga menggunakan typingReaction atau pengiriman normal sebagai ganti pratinjau bergaya thread.
• typingReaction menambahkan reaksi sementara ke pesan Slack masuk saat balasan sedang berjalan, lalu menghapusnya saat selesai. Gunakan shortcode emoji Slack seperti "hourglass_flowing_sand".
• channels.slack.execApprovals: pengiriman persetujuan exec native Slack dan otorisasi pemberi persetujuan. Skema sama seperti Discord: enabled (true/false/"auto"), approvers (ID pengguna Slack), agentFilter, sessionFilter, dan target ("dm", "channel", atau "both").

​

Mattermost

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
      chatmode: "oncall", // oncall | onmessage | onchar
      oncharPrefixes: [">", "!"],
      groups: {
        "*": { requireMention: true },
        "team-channel-id": { requireMention: false },
      },
      commands: {
        native: true, // opt-in
        nativeSkills: true,
        callbackPath: "/api/channels/mattermost/command",
        // URL eksplisit opsional untuk deployment reverse-proxy/publik
        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
      },
      textChunkLimit: 4000,
      chunkMode: "length",
    },
  },
}

• commands.callbackPath harus berupa path (misalnya /api/channels/mattermost/command), bukan URL penuh.
• commands.callbackUrl harus mengarah ke endpoint gateway OpenClaw dan dapat dijangkau dari server Mattermost.
• Callback slash native diautentikasi dengan token per perintah yang dikembalikan oleh Mattermost selama pendaftaran slash command. Jika pendaftaran gagal atau tidak ada perintah yang diaktifkan, OpenClaw menolak callback dengan Unauthorized: invalid command token.
• Untuk host callback private/tailnet/internal, Mattermost mungkin memerlukan ServiceSettings.AllowedUntrustedInternalConnections untuk mencakup host/domain callback. Gunakan nilai host/domain, bukan URL penuh.
• channels.mattermost.configWrites: izinkan atau tolak penulisan konfigurasi yang dipicu Mattermost.
• channels.mattermost.requireMention: mewajibkan @mention sebelum membalas di channel.
• channels.mattermost.groups.<channelId>.requireMention: override pembatasan mention per channel ("*" untuk default).
• channels.mattermost.defaultAccount opsional menggantikan pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi.

​

Signal

{
  channels: {
    signal: {
      enabled: true,
      account: "+15555550123", // binding akun opsional
      dmPolicy: "pairing",
      allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      configWrites: true,
      reactionNotifications: "own", // off | own | all | allowlist
      reactionAllowlist: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      historyLimit: 50,
    },
  },
}

• channels.signal.account: sematkan startup channel ke identitas akun Signal tertentu.
• channels.signal.configWrites: izinkan atau tolak penulisan konfigurasi yang dipicu Signal.
• channels.signal.defaultAccount opsional menggantikan pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi.

​

BlueBubbles

{
  channels: {
    bluebubbles: {
      enabled: true,
      dmPolicy: "pairing",
      // serverUrl, password, webhookPath, kontrol grup, dan aksi lanjutan:
      // lihat /channels/bluebubbles
    },
  },
}

• Jalur kunci inti yang dicakup di sini: channels.bluebubbles, channels.bluebubbles.dmPolicy.
• channels.bluebubbles.defaultAccount opsional menggantikan pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi.
• Entri bindings[] tingkat atas dengan type: "acp" dapat mengikat percakapan BlueBubbles ke sesi ACP persisten. Gunakan handle BlueBubbles atau string target (chat_id:*, chat_guid:*, chat_identifier:*) di match.peer.id. Semantik bidang bersama: ACP Agents.
• Konfigurasi channel BlueBubbles lengkap didokumentasikan di BlueBubbles.

​

iMessage

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "imsg",
      dbPath: "~/Library/Messages/chat.db",
      remoteHost: "user@gateway-host",
      dmPolicy: "pairing",
      allowFrom: ["+15555550123", "user@example.com", "chat_id:123"],
      historyLimit: 50,
      includeAttachments: false,
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      mediaMaxMb: 16,
      service: "auto",
      region: "US",
    },
  },
}

• channels.imessage.defaultAccount opsional menggantikan pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi.
• Memerlukan Full Disk Access ke DB Messages.
• Lebih disarankan menggunakan target chat_id:<id>. Gunakan imsg chats --limit 20 untuk mencantumkan chat.
• cliPath dapat mengarah ke wrapper SSH; atur remoteHost (host atau user@host) untuk pengambilan lampiran SCP.
• attachmentRoots dan remoteAttachmentRoots membatasi path lampiran masuk (default: /Users/*/Library/Messages/Attachments).
• SCP menggunakan pemeriksaan host-key ketat, jadi pastikan host key relay sudah ada di ~/.ssh/known_hosts.
• channels.imessage.configWrites: izinkan atau tolak penulisan konfigurasi yang dipicu iMessage.
• Entri bindings[] tingkat atas dengan type: "acp" dapat mengikat percakapan iMessage ke sesi ACP persisten. Gunakan handle yang dinormalisasi atau target chat eksplisit (chat_id:*, chat_guid:*, chat_identifier:*) di match.peer.id. Semantik bidang bersama: ACP Agents.

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

​

Matrix

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_bot_xxx",
      proxy: "http://127.0.0.1:7890",
      encryption: true,
      initialSyncLimit: 20,
      defaultAccount: "ops",
      accounts: {
        ops: {
          name: "Ops",
          userId: "@ops:example.org",
          accessToken: "syt_ops_xxx",
        },
        alerts: {
          userId: "@alerts:example.org",
          password: "secret",
          proxy: "http://127.0.0.1:7891",
        },
      },
    },
  },
}

• Autentikasi token menggunakan accessToken; autentikasi kata sandi menggunakan userId + password.
• channels.matrix.proxy merutekan lalu lintas HTTP Matrix melalui proxy HTTP(S) eksplisit. Akun bernama dapat menggantinya dengan channels.matrix.accounts.<id>.proxy.
• channels.matrix.network.dangerouslyAllowPrivateNetwork mengizinkan homeserver private/internal. proxy dan opt-in jaringan ini adalah kontrol yang independen.
• channels.matrix.defaultAccount memilih akun pilihan dalam penyiapan multi-akun.
• channels.matrix.autoJoin default-nya off, sehingga room undangan dan undangan bergaya DM baru diabaikan sampai Anda menetapkan autoJoin: "allowlist" dengan autoJoinAllowlist atau autoJoin: "always".
• channels.matrix.execApprovals: pengiriman persetujuan exec native Matrix dan otorisasi pemberi persetujuan.
  • enabled: true, false, atau "auto" (default). Dalam mode auto, persetujuan exec aktif saat pemberi persetujuan dapat di-resolve dari approvers atau commands.ownerAllowFrom.
  • approvers: ID pengguna Matrix (mis. @owner:example.org) yang diizinkan untuk menyetujui permintaan exec.
  • agentFilter: allowlist ID agen opsional. Hilangkan untuk meneruskan persetujuan bagi semua agen.
  • sessionFilter: pola kunci sesi opsional (substring atau regex).
  • target: tempat mengirim prompt persetujuan. "dm" (default), "channel" (room asal), atau "both".
  • Override per akun: channels.matrix.accounts.<id>.execApprovals.
• channels.matrix.dm.sessionScope mengontrol cara DM Matrix dikelompokkan ke dalam sesi: per-user (default) berbagi berdasarkan peer yang dirutekan, sedangkan per-room mengisolasi setiap room DM.
• Probe status Matrix dan lookup direktori langsung menggunakan kebijakan proxy yang sama seperti lalu lintas runtime.
• Konfigurasi Matrix lengkap, aturan penargetan, dan contoh penyiapan didokumentasikan di Matrix.

​

Microsoft Teams

{
  channels: {
    msteams: {
      enabled: true,
      configWrites: true,
      // appId, appPassword, tenantId, webhook, kebijakan tim/channel:
      // lihat /channels/msteams
    },
  },
}

• Jalur kunci inti yang dicakup di sini: channels.msteams, channels.msteams.configWrites.
• Konfigurasi Teams lengkap (kredensial, webhook, kebijakan DM/grup, override per tim/per channel) didokumentasikan di Microsoft Teams.

​

IRC

{
  channels: {
    irc: {
      enabled: true,
      dmPolicy: "pairing",
      configWrites: true,
      nickserv: {
        enabled: true,
        service: "NickServ",
        password: "${IRC_NICKSERV_PASSWORD}",
        register: false,
        registerEmail: "bot@example.com",
      },
    },
  },
}

• Jalur kunci inti yang dicakup di sini: channels.irc, channels.irc.dmPolicy, channels.irc.configWrites, channels.irc.nickserv.*.
• channels.irc.defaultAccount opsional menggantikan pemilihan akun default saat cocok dengan ID akun yang dikonfigurasi.
• Konfigurasi channel IRC lengkap (host/port/TLS/channels/allowlists/pembatasan mention) didokumentasikan di IRC.

​

Multi-akun (semua channels)

{
  channels: {
    telegram: {
      accounts: {
        default: {
          name: "Primary bot",
          botToken: "123456:ABC...",
        },
        alerts: {
          name: "Alerts bot",
          botToken: "987654:XYZ...",
        },
      },
    },
  },
}

• default digunakan saat accountId dihilangkan (CLI + perutean).
• Token env hanya berlaku untuk akun default.
• Pengaturan channel dasar berlaku untuk semua akun kecuali dioverride per akun.
• Gunakan bindings[].match.accountId untuk merutekan setiap akun ke agen yang berbeda.
• Jika Anda menambahkan akun non-default melalui openclaw channels add (atau onboarding channel) saat masih menggunakan konfigurasi channel tingkat atas akun tunggal, OpenClaw terlebih dahulu mempromosikan nilai akun tunggal tingkat atas yang dicakup akun ke peta akun channel agar akun asli tetap berfungsi. Sebagian besar channel memindahkannya ke channels.<channel>.accounts.default; Matrix dapat mempertahankan target bernama/default yang sudah cocok.
• Binding khusus channel yang sudah ada (tanpa accountId) tetap cocok dengan akun default; binding yang dicakup akun tetap opsional.
• openclaw doctor --fix juga memperbaiki bentuk campuran dengan memindahkan nilai akun tunggal tingkat atas yang dicakup akun ke akun hasil promosi yang dipilih untuk channel tersebut. Sebagian besar channel menggunakan accounts.default; Matrix dapat mempertahankan target bernama/default yang sudah cocok.

​

Channel extension lainnya

​

Pembatasan mention chat grup

• Mention metadata: @-mention native platform. Diabaikan dalam mode chat ke diri sendiri WhatsApp.
• Pola teks: Pola regex aman di agents.list[].groupChat.mentionPatterns. Pola tidak valid dan repetisi bertingkat yang tidak aman akan diabaikan.
• Pembatasan mention hanya diberlakukan saat deteksi dimungkinkan (mention native atau setidaknya satu pola).

{
  messages: {
    groupChat: { historyLimit: 50 },
  },
  agents: {
    list: [{ id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"] } }],
  },
}

​

Batas riwayat DM

{
  channels: {
    telegram: {
      dmHistoryLimit: 30,
      dms: {
        "123456789": { historyLimit: 50 },
      },
    },
  },
}

​

Mode chat ke diri sendiri

{
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: { mentionPatterns: ["reisponde", "@openclaw"] },
      },
    ],
  },
}

​

Perintah (penanganan perintah chat)

{
  commands: {
    native: "auto", // daftarkan perintah native saat didukung
    nativeSkills: "auto", // daftarkan perintah Skills native saat didukung
    text: true, // parse /commands dalam pesan chat
    bash: false, // izinkan ! (alias: /bash)
    bashForegroundMs: 2000,
    config: false, // izinkan /config
    mcp: false, // izinkan /mcp
    plugins: false, // izinkan /plugins
    debug: false, // izinkan /debug
    restart: true, // izinkan /restart + alat restart gateway
    ownerAllowFrom: ["discord:123456789012345678"],
    ownerDisplay: "raw", // raw | hash
    ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}",
    allowFrom: {
      "*": ["user1"],
      discord: ["user:123"],
    },
    useAccessGroups: true,
  },
}

​

Default agen

​

agents.defaults.workspace

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
}

​

agents.defaults.repoRoot

{
  agents: { defaults: { repoRoot: "~/Projects/openclaw" } },
}

​

agents.defaults.skills

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

• Hilangkan agents.defaults.skills untuk Skills tak dibatasi secara default.
• Hilangkan agents.list[].skills untuk mewarisi default.
• Tetapkan agents.list[].skills: [] untuk tanpa Skills.
• Daftar agents.list[].skills yang tidak kosong adalah set akhir untuk agen tersebut; daftar itu tidak digabungkan dengan default.

​

agents.defaults.skipBootstrap

{
  agents: { defaults: { skipBootstrap: true } },
}

​

agents.defaults.contextInjection

• "continuation-skip": giliran kelanjutan yang aman (setelah respons asisten selesai) melewati penyuntikan ulang bootstrap workspace, sehingga mengurangi ukuran prompt. Eksekusi heartbeat dan percobaan ulang pasca-pemadatan tetap membangun ulang konteks.

{
  agents: { defaults: { contextInjection: "continuation-skip" } },
}

​

agents.defaults.bootstrapMaxChars

{
  agents: { defaults: { bootstrapMaxChars: 20000 } },
}

​

agents.defaults.bootstrapTotalMaxChars

{
  agents: { defaults: { bootstrapTotalMaxChars: 150000 } },
}

​

agents.defaults.bootstrapPromptTruncationWarning

• "off": jangan pernah menyuntikkan teks peringatan ke system prompt.
• "once": suntikkan peringatan sekali per signature pemotongan unik (direkomendasikan).
• "always": suntikkan peringatan pada setiap eksekusi saat pemotongan ada.

{
  agents: { defaults: { bootstrapPromptTruncationWarning: "once" } }, // off | once | always
}

​

agents.defaults.imageMaxDimensionPx

{
  agents: { defaults: { imageMaxDimensionPx: 1200 } },
}

​

agents.defaults.userTimezone

{
  agents: { defaults: { userTimezone: "America/Chicago" } },
}

​

agents.defaults.timeFormat

{
  agents: { defaults: { timeFormat: "auto" } }, // auto | 12 | 24
}

​

agents.defaults.model

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "minimax/MiniMax-M2.7": { alias: "minimax" },
      },
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["minimax/MiniMax-M2.7"],
      },
      imageModel: {
        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
        fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],
      },
      imageGenerationModel: {
        primary: "openai/gpt-image-1",
        fallbacks: ["google/gemini-3.1-flash-image-preview"],
      },
      videoGenerationModel: {
        primary: "qwen/wan2.6-t2v",
        fallbacks: ["qwen/wan2.6-i2v"],
      },
      pdfModel: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5.4-mini"],
      },
      params: { cacheRetention: "long" }, // parameter provider default global
      embeddedHarness: {
        runtime: "auto", // auto | pi | id harness terdaftar, misalnya codex
        fallback: "pi", // pi | none
      },
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      contextTokens: 200000,
      maxConcurrent: 3,
    },
  },
}

• model: menerima string ("provider/model") atau objek ({ primary, fallbacks }).
  • Bentuk string hanya menetapkan model utama.
  • Bentuk objek menetapkan model utama plus model failover berurutan.
• imageModel: menerima string ("provider/model") atau objek ({ primary, fallbacks }).
  • Digunakan oleh jalur alat image sebagai konfigurasi model vision.
  • Juga digunakan sebagai perutean fallback ketika model yang dipilih/default tidak dapat menerima input gambar.
• imageGenerationModel: menerima string ("provider/model") atau objek ({ primary, fallbacks }).
  • Digunakan oleh kapabilitas pembuatan gambar bersama dan permukaan alat/plugin mendatang apa pun yang menghasilkan gambar.
  • Nilai umum: google/gemini-3.1-flash-image-preview untuk pembuatan gambar Gemini native, fal/fal-ai/flux/dev untuk fal, atau openai/gpt-image-1 untuk OpenAI Images.
  • Jika Anda memilih provider/model secara langsung, konfigurasikan juga auth/kunci API provider yang sesuai (misalnya GEMINI_API_KEY atau GOOGLE_API_KEY untuk google/*, OPENAI_API_KEY untuk openai/*, FAL_KEY untuk fal/*).
  • Jika dihilangkan, image_generate masih dapat menyimpulkan default provider berbasis auth. Alat ini mencoba provider default saat ini terlebih dahulu, lalu provider pembuatan gambar terdaftar lainnya menurut urutan provider-id.
• musicGenerationModel: menerima string ("provider/model") atau objek ({ primary, fallbacks }).
  • Digunakan oleh kapabilitas pembuatan musik bersama dan alat bawaan music_generate.
  • Nilai umum: google/lyria-3-clip-preview, google/lyria-3-pro-preview, atau minimax/music-2.5+.
  • Jika dihilangkan, music_generate masih dapat menyimpulkan default provider berbasis auth. Alat ini mencoba provider default saat ini terlebih dahulu, lalu provider pembuatan musik terdaftar lainnya menurut urutan provider-id.
  • Jika Anda memilih provider/model secara langsung, konfigurasikan juga auth/kunci API provider yang sesuai.
• videoGenerationModel: menerima string ("provider/model") atau objek ({ primary, fallbacks }).
  • Digunakan oleh kapabilitas pembuatan video bersama dan alat bawaan video_generate.
  • Nilai umum: qwen/wan2.6-t2v, qwen/wan2.6-i2v, qwen/wan2.6-r2v, qwen/wan2.6-r2v-flash, atau qwen/wan2.7-r2v.
  • Jika dihilangkan, video_generate masih dapat menyimpulkan default provider berbasis auth. Alat ini mencoba provider default saat ini terlebih dahulu, lalu provider pembuatan video terdaftar lainnya menurut urutan provider-id.
  • Jika Anda memilih provider/model secara langsung, konfigurasikan juga auth/kunci API provider yang sesuai.
  • Provider pembuatan video Qwen bawaan mendukung hingga 1 video output, 1 gambar input, 4 video input, durasi 10 detik, dan opsi tingkat provider size, aspectRatio, resolution, audio, dan watermark.
• pdfModel: menerima string ("provider/model") atau objek ({ primary, fallbacks }).
  • Digunakan oleh alat pdf untuk perutean model.
  • Jika dihilangkan, alat PDF fallback ke imageModel, lalu ke model sesi/default yang sudah di-resolve.
• pdfMaxBytesMb: batas ukuran PDF default untuk alat pdf saat maxBytesMb tidak diberikan saat waktu pemanggilan.
• pdfMaxPages: jumlah halaman maksimum default yang dipertimbangkan oleh mode fallback ekstraksi dalam alat pdf.
• verboseDefault: tingkat verbose default untuk agen. Nilai: "off", "on", "full". Default: "off".
• elevatedDefault: tingkat output elevated default untuk agen. Nilai: "off", "on", "ask", "full". Default: "on".
• model.primary: format provider/model (mis. openai/gpt-5.4). Jika Anda menghilangkan provider, OpenClaw mencoba alias terlebih dahulu, lalu kecocokan configured-provider unik untuk ID model yang persis sama, dan baru kemudian fallback ke provider default yang dikonfigurasi (perilaku kompatibilitas lama yang sudah deprecated, jadi lebih baik gunakan provider/model eksplisit). Jika provider tersebut tidak lagi mengekspos model default yang dikonfigurasi, OpenClaw fallback ke provider/model pertama yang dikonfigurasi alih-alih menampilkan default provider usang dari provider yang sudah dihapus.
• models: katalog model dan allowlist yang dikonfigurasi untuk /model. Setiap entri dapat menyertakan alias (shortcut) dan params (khusus provider, misalnya temperature, maxTokens, cacheRetention, context1m).
• params: parameter provider default global yang diterapkan ke semua model. Tetapkan di agents.defaults.params (mis. { cacheRetention: "long" }).
• Urutan prioritas penggabungan params (konfigurasi): agents.defaults.params (dasar global) dioverride oleh agents.defaults.models["provider/model"].params (per-model), lalu agents.list[].params (ID agen yang cocok) mengoverride per kunci. Lihat Prompt Caching untuk detail.
• embeddedHarness: kebijakan runtime agen embedded tingkat rendah default. Gunakan runtime: "auto" agar plugin harness terdaftar dapat mengklaim model yang didukung, runtime: "pi" untuk memaksa harness PI bawaan, atau ID harness terdaftar seperti runtime: "codex". Tetapkan fallback: "none" untuk menonaktifkan fallback PI otomatis.
• Penulis konfigurasi yang memutasi bidang ini (misalnya /models set, /models set-image, dan perintah tambah/hapus fallback) menyimpan bentuk objek kanonis dan mempertahankan daftar fallback yang ada bila memungkinkan.
• maxConcurrent: jumlah maksimum eksekusi agen paralel lintas sesi (setiap sesi tetap diserialisasi). Default: 4.

​

agents.defaults.embeddedHarness

{
  agents: {
    defaults: {
      model: "codex/gpt-5.4",
      embeddedHarness: {
        runtime: "codex",
        fallback: "none",
      },
    },
  },
}

• runtime: "auto", "pi", atau ID harness plugin terdaftar. Plugin Codex bawaan mendaftarkan codex.
• fallback: "pi" atau "none". "pi" mempertahankan harness PI bawaan sebagai fallback kompatibilitas. "none" membuat pemilihan harness plugin yang hilang atau tidak didukung gagal alih-alih diam-diam menggunakan PI.
• Override environment: OPENCLAW_AGENT_RUNTIME=<id|auto|pi> mengoverride runtime; OPENCLAW_AGENT_HARNESS_FALLBACK=none menonaktifkan fallback PI untuk proses tersebut.
• Untuk deployment khusus Codex, tetapkan model: "codex/gpt-5.4", embeddedHarness.runtime: "codex", dan embeddedHarness.fallback: "none".
• Ini hanya mengontrol harness chat embedded. Pembuatan media, vision, PDF, musik, video, dan TTS tetap menggunakan pengaturan provider/model masing-masing.

​

agents.defaults.cliBackends

{
  agents: {
    defaults: {
      cliBackends: {
        "codex-cli": {
          command: "/opt/homebrew/bin/codex",
        },
        "my-cli": {
          command: "my-cli",
          args: ["--json"],
          output: "json",
          modelArg: "--model",
          sessionArg: "--session",
          sessionMode: "existing",
          systemPromptArg: "--system",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
        },
      },
    },
  },
}

• Backend CLI bersifat text-first; alat selalu dinonaktifkan.
• Sesi didukung saat sessionArg diatur.
• Pass-through gambar didukung saat imageArg menerima path file.

​

agents.defaults.systemPromptOverride

{
  agents: {
    defaults: {
      systemPromptOverride: "You are a helpful assistant.",
    },
  },
}

​

agents.defaults.heartbeat

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 0m menonaktifkan
        model: "openai/gpt-5.4-mini",
        includeReasoning: false,
        includeSystemPromptSection: true, // default: true; false menghilangkan bagian Heartbeat dari system prompt
        lightContext: false, // default: false; true hanya mempertahankan HEARTBEAT.md dari file bootstrap workspace
        isolatedSession: false, // default: false; true menjalankan setiap heartbeat dalam sesi baru (tanpa riwayat percakapan)
        session: "main",
        to: "+15555550123",
        directPolicy: "allow", // allow (default) | block
        target: "none", // default: none | opsi: last | whatsapp | telegram | discord | ...
        prompt: "Read HEARTBEAT.md if it exists...",
        ackMaxChars: 300,
        suppressToolErrorWarnings: false,
        timeoutSeconds: 45,
      },
    },
  },
}

• every: string durasi (ms/s/m/h). Default: 30m (auth API-key) atau 1h (auth OAuth). Tetapkan ke 0m untuk menonaktifkan.
• includeSystemPromptSection: saat false, menghilangkan bagian Heartbeat dari system prompt dan melewati penyuntikan HEARTBEAT.md ke konteks bootstrap. Default: true.
• suppressToolErrorWarnings: saat true, menekan payload peringatan error alat selama eksekusi heartbeat.
• timeoutSeconds: waktu maksimum dalam detik yang diizinkan untuk satu giliran agen heartbeat sebelum dibatalkan. Biarkan tidak diatur untuk menggunakan agents.defaults.timeoutSeconds.
• directPolicy: kebijakan pengiriman langsung/DM. allow (default) mengizinkan pengiriman target langsung. block menekan pengiriman target langsung dan memunculkan reason=dm-blocked.
• lightContext: saat true, eksekusi heartbeat menggunakan konteks bootstrap ringan dan hanya mempertahankan HEARTBEAT.md dari file bootstrap workspace.
• isolatedSession: saat true, setiap heartbeat dijalankan dalam sesi baru tanpa riwayat percakapan sebelumnya. Pola isolasi yang sama seperti cron sessionTarget: "isolated". Mengurangi biaya token per heartbeat dari ~100K menjadi ~2-5K token.
• Per agen: tetapkan agents.list[].heartbeat. Saat agen mana pun mendefinisikan heartbeat, hanya agen tersebut yang menjalankan heartbeat.
• Heartbeat menjalankan giliran agen penuh — interval yang lebih pendek membakar lebih banyak token.

​

agents.defaults.compaction

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
        provider: "my-provider", // id dari plugin provider compaction terdaftar (opsional)
        timeoutSeconds: 900,
        reserveTokensFloor: 24000,
        identifierPolicy: "strict", // strict | off | custom
        identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // digunakan saat identifierPolicy=custom
        postCompactionSections: ["Session Startup", "Red Lines"], // [] menonaktifkan penyuntikan ulang
        model: "openrouter/anthropic/claude-sonnet-4-6", // override model khusus compaction opsional
        notifyUser: true, // kirim pemberitahuan singkat saat compaction dimulai (default: false)
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 6000,
          systemPrompt: "Session nearing compaction. Store durable memories now.",
          prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.",
        },
      },
    },
  },
}

• mode: default atau safeguard (peringkasan bertahap untuk riwayat panjang). Lihat Compaction.
• provider: id dari plugin provider compaction terdaftar. Saat diatur, summarize() milik provider dipanggil alih-alih peringkasan LLM bawaan. Fallback ke bawaan jika gagal. Menetapkan provider memaksa mode: "safeguard". Lihat Compaction.
• timeoutSeconds: jumlah detik maksimum yang diizinkan untuk satu operasi compaction sebelum OpenClaw membatalkannya. Default: 900.
• identifierPolicy: strict (default), off, atau custom. strict menambahkan panduan bawaan untuk mempertahankan identifier opak selama peringkasan compaction.
• identifierInstructions: teks kustom opsional untuk mempertahankan identifier yang digunakan saat identifierPolicy=custom.
• postCompactionSections: nama bagian H2/H3 AGENTS.md opsional yang akan disuntikkan ulang setelah compaction. Default ke ["Session Startup", "Red Lines"]; tetapkan [] untuk menonaktifkan penyuntikan ulang. Saat tidak diatur atau secara eksplisit diatur ke pasangan default tersebut, heading lama Every Session/Safety juga diterima sebagai fallback kompatibilitas lama.
• model: override provider/model-id opsional hanya untuk peringkasan compaction. Gunakan ini saat sesi utama harus tetap memakai satu model tetapi ringkasan compaction harus berjalan pada model lain; saat tidak diatur, compaction menggunakan model utama sesi.
• notifyUser: saat true, mengirim pemberitahuan singkat kepada pengguna saat compaction dimulai (misalnya, “Compacting context…”). Dinonaktifkan secara default agar compaction tetap senyap.
• memoryFlush: giliran agentic senyap sebelum auto-compaction untuk menyimpan memori yang tahan lama. Dilewati saat workspace hanya-baca.

​

agents.defaults.contextPruning

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl", // off | cache-ttl
        ttl: "1h", // durasi (ms/s/m/h), unit default: menit
        keepLastAssistants: 3,
        softTrimRatio: 0.3,
        hardClearRatio: 0.5,
        minPrunableToolChars: 50000,
        softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 },
        hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" },
        tools: { deny: ["browser", "canvas"] },
      },
    },
  },
}

​

Streaming blok

{
  agents: {
    defaults: {
      blockStreamingDefault: "off", // on | off
      blockStreamingBreak: "text_end", // text_end | message_end
      blockStreamingChunk: { minChars: 800, maxChars: 1200 },
      blockStreamingCoalesce: { idleMs: 1000 },
      humanDelay: { mode: "natural" }, // off | natural | custom (gunakan minMs/maxMs)
    },
  },
}

• Channel non-Telegram memerlukan *.blockStreaming: true eksplisit untuk mengaktifkan balasan blok.
• Override channel: channels.<channel>.blockStreamingCoalesce (dan varian per akun). Signal/Slack/Discord/Google Chat default minChars: 1500.
• humanDelay: jeda acak antar balasan blok. natural = 800–2500md. Override per agen: agents.list[].humanDelay.

​

Indikator mengetik

{
  agents: {
    defaults: {
      typingMode: "instant", // never | instant | thinking | message
      typingIntervalSeconds: 6,
    },
  },
}

• Default: instant untuk chat langsung/mention, message untuk chat grup tanpa mention.
• Override per sesi: session.typingMode, session.typingIntervalSeconds.

​

agents.defaults.sandbox

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        backend: "docker", // docker | ssh | openshell
        scope: "agent", // session | agent | shared
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          containerPrefix: "openclaw-sbx-",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256,
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "openclaw-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"],
          binds: ["/home/user/source:/source:rw"],
        },
        ssh: {
          target: "user@gateway-host:22",
          command: "ssh",
          workspaceRoot: "/tmp/openclaw-sandboxes",
          strictHostKeyChecking: true,
          updateHostKeys: true,
          identityFile: "~/.ssh/id_ed25519",
          certificateFile: "~/.ssh/id_ed25519-cert.pub",
          knownHostsFile: "~/.ssh/known_hosts",
          // SecretRef / konten inline juga didukung:
          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
        },
        browser: {
          enabled: false,
          image: "openclaw-sandbox-browser:bookworm-slim",
          network: "openclaw-sandbox-browser",
          cdpPort: 9222,
          cdpSourceRange: "172.21.0.1/32",
          vncPort: 5900,
          noVncPort: 6080,
          headless: false,
          enableNoVnc: true,
          allowHostControl: false,
          autoStart: true,
          autoStartTimeoutMs: 12000,
        },
        prune: {
          idleHours: 24,
          maxAgeDays: 7,
        },
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: [
          "exec",
          "process",
          "read",
          "write",
          "edit",
          "apply_patch",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status",
        ],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
      },
    },
  },
}

{
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          mode: "mirror", // mirror | remote
          from: "openclaw",
          remoteWorkspaceDir: "/sandbox",
          remoteAgentWorkspaceDir: "/agent",
          gateway: "lab", // opsional
          gatewayEndpoint: "https://lab.example", // opsional
          policy: "strict", // id kebijakan OpenShell opsional
          providers: ["openai"], // opsional
          autoProviders: true,
          timeoutSeconds: 120,
        },
      },
    },
  },
}

scripts/sandbox-setup.sh           # image sandbox utama
scripts/sandbox-browser-setup.sh   # image browser opsional

​

agents.list (override per agen)

{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        name: "Main Agent",
        workspace: "~/.openclaw/workspace",
        agentDir: "~/.openclaw/agents/main/agent",
        model: "anthropic/claude-opus-4-6", // atau { primary, fallbacks }
        thinkingDefault: "high", // override tingkat thinking per agen
        reasoningDefault: "on", // override visibilitas reasoning per agen
        fastModeDefault: false, // override mode cepat per agen
        embeddedHarness: { runtime: "auto", fallback: "pi" },
        params: { cacheRetention: "none" }, // mengoverride kunci params defaults.models yang cocok per kunci
        skills: ["docs-search"], // menggantikan agents.defaults.skills saat diatur
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
          emoji: "🦥",
          avatar: "avatars/samantha.png",
        },
        groupChat: { mentionPatterns: ["@openclaw"] },
        sandbox: { mode: "off" },
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
        subagents: { allowAgents: ["*"] },
        tools: {
          profile: "coding",
          allow: ["browser"],
          deny: ["canvas"],
          elevated: { enabled: true },
        },
      },
    ],
  },
}

• id: ID agen stabil (wajib).
• default: saat beberapa ditetapkan, yang pertama menang (peringatan dicatat). Jika tidak ada yang ditetapkan, entri daftar pertama menjadi default.
• model: bentuk string hanya mengoverride primary; bentuk objek { primary, fallbacks } mengoverride keduanya ([] menonaktifkan fallback global). Pekerjaan cron yang hanya mengoverride primary tetap mewarisi fallback default kecuali Anda menetapkan fallbacks: [].
• params: params stream per agen yang digabungkan di atas entri model yang dipilih di agents.defaults.models. Gunakan ini untuk override khusus agen seperti cacheRetention, temperature, atau maxTokens tanpa menduplikasi seluruh katalog model.
• skills: allowlist skill per agen opsional. Jika dihilangkan, agen mewarisi agents.defaults.skills bila diatur; daftar eksplisit menggantikan default alih-alih digabungkan, dan [] berarti tanpa skill.
• thinkingDefault: default tingkat thinking per agen opsional (off | minimal | low | medium | high | xhigh | adaptive). Mengoverride agents.defaults.thinkingDefault untuk agen ini saat tidak ada override per pesan atau sesi.
• reasoningDefault: default visibilitas reasoning per agen opsional (on | off | stream). Berlaku saat tidak ada override reasoning per pesan atau sesi.
• fastModeDefault: default mode cepat per agen opsional (true | false). Berlaku saat tidak ada override mode cepat per pesan atau sesi.
• embeddedHarness: override kebijakan harness tingkat rendah per agen opsional. Gunakan { runtime: "codex", fallback: "none" } untuk menjadikan satu agen khusus Codex sementara agen lain tetap menggunakan fallback PI default.
• runtime: deskriptor runtime per agen opsional. Gunakan type: "acp" dengan default runtime.acp (agent, backend, mode, cwd) saat agen harus default ke sesi harness ACP.
• identity.avatar: path relatif workspace, URL http(s), atau URI data:.
• identity menurunkan default: ackReaction dari emoji, mentionPatterns dari name/emoji.
• subagents.allowAgents: allowlist ID agen untuk sessions_spawn (["*"] = apa pun; default: hanya agen yang sama).
• Guard pewarisan sandbox: jika sesi peminta disandbox, sessions_spawn menolak target yang akan berjalan tanpa sandbox.
• subagents.requireAgentId: saat true, blokir panggilan sessions_spawn yang menghilangkan agentId (memaksa pemilihan profil eksplisit; default: false).

​

Perutean multi-agen

{
  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" } },
  ],
}

​

Bidang kecocokan binding

• type (opsional): route untuk perutean normal (type yang hilang default ke route), acp untuk binding percakapan ACP persisten.
• match.channel (wajib)
• match.accountId (opsional; * = akun apa pun; dihilangkan = akun default)
• match.peer (opsional; { kind: direct|group|channel, id })
• match.guildId / match.teamId (opsional; khusus channel)
• acp (opsional; hanya untuk entri type: "acp"): { mode, label, cwd, backend }

1. match.peer
2. match.guildId
3. match.teamId
4. match.accountId (persis, tanpa peer/guild/team)
5. match.accountId: "*" (cakupan seluruh channel)
6. Agen default

​

Profil akses per agen

{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: { mode: "off" },
      },
    ],
  },
}

{
  agents: {
    list: [
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: { mode: "all", scope: "agent", workspaceAccess: "ro" },
        tools: {
          allow: [
            "read",
            "sessions_list",
            "sessions_history",
            "sessions_send",
            "sessions_spawn",
            "session_status",
          ],
          deny: ["write", "edit", "apply_patch", "exec", "process", "browser"],
        },
      },
    ],
  },
}

{
  agents: {
    list: [
      {
        id: "public",
        workspace: "~/.openclaw/workspace-public",
        sandbox: { mode: "all", scope: "agent", workspaceAccess: "none" },
        tools: {
          allow: [
            "sessions_list",
            "sessions_history",
            "sessions_send",
            "sessions_spawn",
            "session_status",
            "whatsapp",
            "telegram",
            "slack",
            "discord",
            "gateway",
          ],
          deny: [
            "read",
            "write",
            "edit",
            "apply_patch",
            "exec",
            "process",
            "browser",
            "canvas",
            "nodes",
            "cron",
            "gateway",
            "image",
          ],
        },
      },
    ],
  },
}

​

Sesi

{
  session: {
    scope: "per-sender",
    dmScope: "main", // main | per-peer | per-channel-peer | per-account-channel-peer
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"],
    },
    reset: {
      mode: "daily", // daily | idle
      atHour: 4,
      idleMinutes: 60,
    },
    resetByType: {
      thread: { mode: "daily", atHour: 4 },
      direct: { mode: "idle", idleMinutes: 240 },
      group: { mode: "idle", idleMinutes: 120 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    parentForkMaxTokens: 100000, // lewati fork thread induk di atas jumlah token ini (0 menonaktifkan)
    maintenance: {
      mode: "warn", // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      rotateBytes: "10mb",
      resetArchiveRetention: "30d", // durasi atau false
      maxDiskBytes: "500mb", // anggaran keras opsional
      highWaterBytes: "400mb", // target pembersihan opsional
    },
    threadBindings: {
      enabled: true,
      idleHours: 24, // default auto-unfocus karena tidak aktif dalam jam (`0` menonaktifkan)
      maxAgeHours: 0, // default usia maksimum keras dalam jam (`0` menonaktifkan)
    },
    mainKey: "main", // lama (runtime selalu menggunakan "main")
    agentToAgent: { maxPingPongTurns: 5 },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}

​

Pesan

{
  messages: {
    responsePrefix: "🦞", // atau "auto"
    ackReaction: "👀",
    ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all
    removeAckAfterReply: false,
    queue: {
      mode: "collect", // steer | followup | collect | steer-backlog | steer+backlog | queue | interrupt
      debounceMs: 1000,
      cap: 20,
      drop: "summarize", // old | new | summarize
      byChannel: {
        whatsapp: "collect",
        telegram: "collect",
      },
    },
    inbound: {
      debounceMs: 2000, // 0 menonaktifkan
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
      },
    },
  },
}

​

Awalan respons

​

Reaksi ack

• Default ke identity.emoji agen aktif, jika tidak "👀". Tetapkan "" untuk menonaktifkan.
• Override per channel: channels.<channel>.ackReaction, channels.<channel>.accounts.<id>.ackReaction.
• Urutan resolusi: akun → channel → messages.ackReaction → fallback identitas.
• Cakupan: group-mentions (default), group-all, direct, all.
• removeAckAfterReply: menghapus ack setelah balasan di Slack, Discord, dan Telegram.
• messages.statusReactions.enabled: mengaktifkan reaksi status siklus hidup di Slack, Discord, dan Telegram. Di Slack dan Discord, jika tidak diatur, reaksi status tetap aktif saat reaksi ack aktif. Di Telegram, tetapkan secara eksplisit ke true untuk mengaktifkan reaksi status siklus hidup.

​

Debounce masuk

​

TTS (text-to-speech)

{
  messages: {
    tts: {
      auto: "always", // off | always | inbound | tagged
      mode: "final", // final | all
      provider: "elevenlabs",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: { enabled: true },
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
      elevenlabs: {
        apiKey: "elevenlabs_api_key",
        baseUrl: "https://api.elevenlabs.io",
        voiceId: "voice_id",
        modelId: "eleven_multilingual_v2",
        seed: 42,
        applyTextNormalization: "auto",
        languageCode: "en",
        voiceSettings: {
          stability: 0.5,
          similarityBoost: 0.75,
          style: 0.0,
          useSpeakerBoost: true,
          speed: 1.0,
        },
      },
      openai: {
        apiKey: "openai_api_key",
        baseUrl: "https://api.openai.com/v1",
        model: "gpt-4o-mini-tts",
        voice: "alloy",
      },
    },
  },
}