​

Configuration 🔧

• restrict who can trigger the bot (channels.whatsapp.allowFrom, channels.telegram.allowFrom, etc.)
• control group allowlists + mention behavior (channels.whatsapp.groups, channels.telegram.groups, channels.discord.guilds, agents.list[].groupChat)
• customize message prefixes (messages)
• set the agent’s workspace (agents.defaults.workspace or agents.list[].workspace)
• tune the embedded agent defaults (agents.defaults) and session behavior (session)
• set per-agent identity (agents.list[].identity)

New to configuration? Check out the Configuration Examples guide for complete examples with detailed explanations!

​

Strict config validation

• The Gateway does not boot.
• Only diagnostic commands are allowed (for example: openclaw doctor, openclaw logs, openclaw health, openclaw status, openclaw service, openclaw help).
• Run openclaw doctor to see the exact issues.
• Run openclaw doctor --fix (or --yes) to apply migrations/repairs.

​

Schema + UI hints

​

Apply + restart (RPC)

• raw (string) — JSON5 payload for the entire config
• baseHash (optional) — config hash from config.get (required when a config already exists)
• sessionKey (optional) — last active session key for the wake-up ping
• note (optional) — note to include in the restart sentinel
• restartDelayMs (optional) — delay before restart (default 2000)

openclaw gateway call config.get --params '{}' # capture payload.hash
openclaw gateway call config.apply --params '{
  "raw": "{\\n  agents: { defaults: { workspace: \\"~/.openclaw/workspace\\" } }\\n}\\n",
  "baseHash": "<hash-from-config.get>",
  "sessionKey": "agent:main:whatsapp:dm:+15555550123",
  "restartDelayMs": 1000
}'

​

Partial updates (RPC)

• objects merge recursively
• null deletes a key
• arrays replace Like config.apply, it validates, writes the config, stores a restart sentinel, and schedules the Gateway restart (with an optional wake when sessionKey is provided).

• raw (string) — JSON5 payload containing just the keys to change
• baseHash (required) — config hash from config.get
• sessionKey (optional) — last active session key for the wake-up ping
• note (optional) — note to include in the restart sentinel
• restartDelayMs (optional) — delay before restart (default 2000)

openclaw gateway call config.get --params '{}' # capture payload.hash
openclaw gateway call config.patch --params '{
  "raw": "{\\n  channels: { telegram: { groups: { \\"*\\": { requireMention: false } } } }\\n}\\n",
  "baseHash": "<hash-from-config.get>",
  "sessionKey": "agent:main:whatsapp:dm:+15555550123",
  "restartDelayMs": 1000
}'

​

Minimal config (recommended starting point)

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

scripts/sandbox-setup.sh

​

Self-chat mode (recommended for group control)

{
  agents: {
    defaults: { workspace: "~/.openclaw/workspace" },
    list: [
      {
        id: "main",
        groupChat: { mentionPatterns: ["@openclaw", "reisponde"] },
      },
    ],
  },
  channels: {
    whatsapp: {
      // Allowlist is DMs only; including your own number enables self-chat mode.
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
}

​

Config Includes ($include)

• Organizing large configs (e.g., per-client agent definitions)
• Sharing common settings across environments
• Keeping sensitive configs separate

​

Basic usage

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },

  // Include a single file (replaces the key's value)
  agents: { $include: "./agents.json5" },

  // Include multiple files (deep-merged in order)
  broadcast: {
    $include: ["./clients/mueller.json5", "./clients/schmidt.json5"],
  },
}

// ~/.openclaw/agents.json5
{
  defaults: { sandbox: { mode: "all", scope: "session" } },
  list: [{ id: "main", workspace: "~/.openclaw/workspace" }],
}

​

Merge behavior

• Single file: Replaces the object containing $include
• Array of files: Deep-merges files in order (later files override earlier ones)
• With sibling keys: Sibling keys are merged after includes (override included values)
• Sibling keys + arrays/primitives: Not supported (included content must be an object)

// Sibling keys override included values
{
  $include: "./base.json5", // { a: 1, b: 2 }
  b: 99, // Result: { a: 1, b: 99 }
}

​

Nested includes

// clients/mueller.json5
{
  agents: { $include: "./mueller/agents.json5" },
  broadcast: { $include: "./mueller/broadcast.json5" },
}

​

Path resolution

• Relative paths: Resolved relative to the including file
• Absolute paths: Used as-is
• Parent directories: ../ references work as expected

{ "$include": "./sub/config.json5" }      // relative
{ "$include": "/etc/openclaw/base.json5" } // absolute
{ "$include": "../shared/common.json5" }   // parent dir

​

Error handling

• Missing file: Clear error with resolved path
• Parse error: Shows which included file failed
• Circular includes: Detected and reported with include chain

​

Example: Multi-client legal setup

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789, auth: { token: "secret" } },

  // Common agent defaults
  agents: {
    defaults: {
      sandbox: { mode: "all", scope: "session" },
    },
    // Merge agent lists from all clients
    list: { $include: ["./clients/mueller/agents.json5", "./clients/schmidt/agents.json5"] },
  },

  // Merge broadcast configs
  broadcast: {
    $include: ["./clients/mueller/broadcast.json5", "./clients/schmidt/broadcast.json5"],
  },

  channels: { whatsapp: { groupPolicy: "allowlist" } },
}

// ~/.openclaw/clients/mueller/agents.json5
[
  { id: "mueller-transcribe", workspace: "~/clients/mueller/transcribe" },
  { id: "mueller-docs", workspace: "~/clients/mueller/docs" },
]

// ~/.openclaw/clients/mueller/broadcast.json5
{
  "[email protected]": ["mueller-transcribe", "mueller-docs"],
}

​

Common options

​

Env vars + .env

• .env from the current working directory (if present)
• a global fallback .env from ~/.openclaw/.env (aka $OPENCLAW_STATE_DIR/.env)

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
  },
}

​

env.shellEnv (optional)

{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

• OPENCLAW_LOAD_SHELL_ENV=1
• OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

​

Env var substitution in config

{
  models: {
    providers: {
      "vercel-gateway": {
        apiKey: "${VERCEL_GATEWAY_API_KEY}",
      },
    },
  },
  gateway: {
    auth: {
      token: "${OPENCLAW_GATEWAY_TOKEN}",
    },
  },
}

• Only uppercase env var names are matched: [A-Z_][A-Z0-9_]*
• Missing or empty env vars throw an error at config load
• Escape with $${VAR} to output a literal ${VAR}
• Works with $include (included files also get substitution)

{
  models: {
    providers: {
      custom: {
        baseUrl: "${CUSTOM_API_BASE}/v1", // → "https://api.example.com/v1"
      },
    },
  },
}

​

Auth storage (OAuth + API keys)

• <agentDir>/auth-profiles.json (default: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json)

• ~/.openclaw/credentials/oauth.json (or $OPENCLAW_STATE_DIR/credentials/oauth.json)

• <agentDir>/auth.json (managed automatically; don’t edit manually)

• ~/.openclaw/agent/* (migrated by openclaw doctor into ~/.openclaw/agents/<defaultAgentId>/agent/*)

• OAuth dir (legacy import only): OPENCLAW_OAUTH_DIR
• Agent dir (default agent root override): OPENCLAW_AGENT_DIR (preferred), PI_CODING_AGENT_DIR (legacy)

​

auth

{
  auth: {
    profiles: {
      "anthropic:[email protected]": { provider: "anthropic", mode: "oauth", email: "[email protected]" },
      "anthropic:work": { provider: "anthropic", mode: "api_key" },
    },
    order: {
      anthropic: ["anthropic:[email protected]", "anthropic:work"],
    },
  },
}

​

agents.list[].identity

• messages.ackReaction from the active agent’s identity.emoji (falls back to 👀)
• agents.list[].groupChat.mentionPatterns from the agent’s identity.name/identity.emoji (so “@Samantha” works in groups across Telegram/Slack/Discord/Google Chat/iMessage/WhatsApp)
• identity.avatar chấp nhận đường dẫn ảnh tương đối với workspace hoặc URL từ xa/data URL. Các tệp cục bộ phải nằm trong workspace của agent.

• Workspace-relative path (must stay within the agent workspace)
• http(s) URL
• data: URI

{
  agents: {
    list: [
      {
        id: "main",
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
          emoji: "🦥",
          avatar: "avatars/samantha.png",
        },
      },
    ],
  },
}

​

wizard

{
  wizard: {
    lastRunAt: "2026-01-01T00:00:00.000Z",
    lastRunVersion: "2026.1.4",
    lastRunCommit: "abc1234",
    lastRunCommand: "configure",
    lastRunMode: "local",
  },
}

​

logging

• Default log file: /tmp/openclaw/openclaw-YYYY-MM-DD.log
• If you want a stable path, set logging.file to /tmp/openclaw/openclaw.log.
• Console output can be tuned separately via:
  • logging.consoleLevel (defaults to info, bumps to debug when --verbose)
  • logging.consoleStyle (pretty | compact | json)
• Tool summaries can be redacted to avoid leaking secrets:
  • logging.redactSensitive (off | tools, default: tools)
  • logging.redactPatterns (array of regex strings; overrides defaults)

{
  logging: {
    level: "info",
    file: "/tmp/openclaw/openclaw.log",
    consoleLevel: "info",
    consoleStyle: "pretty",
    redactSensitive: "tools",
    redactPatterns: [
      // Example: override defaults with your own rules.
      "\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1",
      "/\\bsk-[A-Za-z0-9_-]{8,}\\b/gi",
    ],
  },
}

​

channels.whatsapp.dmPolicy

• "pairing" (default): unknown senders get a pairing code; owner must approve
• "allowlist": only allow senders in channels.whatsapp.allowFrom (or paired allow store)
• "open": allow all inbound DMs (requires channels.whatsapp.allowFrom to include "*")
• "disabled": ignore all inbound DMs

• openclaw pairing list whatsapp
• openclaw pairing approve whatsapp <code>

​

channels.whatsapp.allowFrom

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000, // optional outbound chunk size (chars)
      chunkMode: "length", // optional chunking mode (length | newline)
      mediaMaxMb: 50, // optional inbound media cap (MB)
    },
  },
}

​

channels.whatsapp.sendReadReceipts

{
  channels: {
    whatsapp: { sendReadReceipts: false },
  },
}

​

channels.whatsapp.accounts (multi-account)

{
  channels: {
    whatsapp: {
      accounts: {
        default: {}, // optional; keeps the default id stable
        personal: {},
        biz: {
          // Optional override. Default: ~/.openclaw/credentials/whatsapp/biz
          // authDir: "~/.openclaw/credentials/whatsapp/biz",
        },
      },
    },
  },
}

• Outbound commands default to account default if present; otherwise the first configured account id (sorted).
• The legacy single-account Baileys auth dir is migrated by openclaw doctor into whatsapp/default.

​

channels.telegram.accounts / channels.discord.accounts / channels.googlechat.accounts / channels.slack.accounts / channels.mattermost.accounts / channels.signal.accounts / channels.imessage.accounts

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

• default is used when accountId is omitted (CLI + routing).
• Env tokens only apply to the default account.
• Cài đặt kênh cơ sở (chính sách nhóm, kiểm soát đề cập, v.v.) apply to all accounts unless overridden per account.
• Use bindings[].match.accountId to route each account to a different agents.defaults.

​

Group chat mention gating (agents.list[].groupChat + messages.groupChat)

• Metadata mentions: Native platform @-mentions (e.g., WhatsApp tap-to-mention). Bị bỏ qua trong chế độ tự chat WhatsApp (xem channels.whatsapp.allowFrom).
• Text patterns: Regex patterns defined in agents.list[].groupChat.mentionPatterns. Luôn được kiểm tra bất kể chế độ self-chat.
• Mention gating is enforced only when mention detection is possible (native mentions or at least one mentionPattern).

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

​

DM history limits

{
  channels: {
    telegram: {
      dmHistoryLimit: 30, // limit DM sessions to 30 user turns
      dms: {
        "123456789": { historyLimit: 50 }, // per-user override (user ID)
      },
    },
  },
}

1. Per-DM override: channels.<provider>.dms[userId].historyLimit
2. Provider default: channels.<provider>.dmHistoryLimit
3. No limit (all history retained)

{
  agents: {
    list: [
      { id: "work", groupChat: { mentionPatterns: ["@workbot", "\\+15555550123"] } },
      { id: "personal", groupChat: { mentionPatterns: ["@homebot", "\\+15555550999"] } },
    ],
  },
}

{
  channels: {
    whatsapp: {
      // Include your own number to enable self-chat mode (ignore native @-mentions).
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          // Only these text patterns will trigger responses
          mentionPatterns: ["reisponde", "@openclaw"],
        },
      },
    ],
  },
}

​

Group policy (per channel)

{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
    telegram: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["tg:123456789", "@alice"],
    },
    signal: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["chat_id:123"],
    },
    msteams: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["[email protected]"],
    },
    discord: {
      groupPolicy: "allowlist",
      guilds: {
        GUILD_ID: {
          channels: { help: { allow: true } },
        },
      },
    },
    slack: {
      groupPolicy: "allowlist",
      channels: { "#general": { allow: true } },
    },
  },
}

• "open": groups bypass allowlists; mention-gating still applies.
• "disabled": block all group/room messages.
• "allowlist": only allow groups/rooms that match the configured allowlist.
• channels.defaults.groupPolicy sets the default when a provider’s groupPolicy is unset.
• WhatsApp/Telegram/Signal/iMessage/Microsoft Teams use groupAllowFrom (fallback: explicit allowFrom).
• Discord/Slack use channel allowlists (channels.discord.guilds.*.channels, channels.slack.channels).
• Group DMs (Discord/Slack) are still controlled by dm.groupEnabled + dm.groupChannels.
• Default is groupPolicy: "allowlist" (unless overridden by channels.defaults.groupPolicy); if no allowlist is configured, group messages are blocked.

​

Multi-agent routing (agents.list + bindings)

• agents.list[]: per-agent overrides.
  • id: stable agent id (required).
  • default: optional; when multiple are set, the first wins and a warning is logged. If none are set, the first entry in the list is the default agent.
  • name: display name for the agent.
  • workspace: default ~/.openclaw/workspace-<agentId> (for main, falls back to agents.defaults.workspace).
  • agentDir: default ~/.openclaw/agents/<agentId>/agent.
  • model: per-agent default model, overrides agents.defaults.model for that agent.
    • string form: "provider/model", overrides only agents.defaults.model.primary
    • object form: { primary, fallbacks } (fallbacks override agents.defaults.model.fallbacks; [] disables global fallbacks for that agent)
  • identity: per-agent name/theme/emoji (used for mention patterns + ack reactions).
  • groupChat: per-agent mention-gating (mentionPatterns).
  • sandbox: per-agent sandbox config (overrides agents.defaults.sandbox).
    • mode: "off" | "non-main" | "all"
    • workspaceAccess: "none" | "ro" | "rw"
    • scope: "session" | "agent" | "shared"
    • workspaceRoot: custom sandbox workspace root
    • docker: per-agent docker overrides (e.g. image, network, env, setupCommand, limits; ignored when scope: "shared")
    • browser: per-agent sandboxed browser overrides (ignored when scope: "shared")
    • prune: per-agent sandbox pruning overrides (ignored when scope: "shared")
  • subagents: per-agent sub-agent defaults.
    • allowAgents: allowlist of agent ids for sessions_spawn from this agent (["*"] = allow any; default: only same agent)
  • tools: per-agent tool restrictions (applied before sandbox tool policy).
    • profile: base tool profile (applied before allow/deny)
    • allow: array of allowed tool names
    • deny: array of denied tool names (deny wins)
• agents.defaults: shared agent defaults (model, workspace, sandbox, etc.).
• bindings[]: routes inbound messages to an agentId.
  • match.channel (required)
  • match.accountId (optional; * = any account; omitted = default account)
  • match.peer (optional; { kind: direct|group|channel, id })
  • match.guildId / match.teamId (optional; channel-specific)

1. match.peer
2. match.guildId
3. match.teamId
4. match.accountId (exact, no peer/guild/team)
5. match.accountId: "*" (channel-wide, no peer/guild/team)
6. default agent (agents.list[].default, else first list entry, else "main")

​

Per-agent access profiles (multi-agent)

• Full access (personal agent)
• Read-only tools + workspace
• No filesystem access (messaging/session tools only)

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

{
  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" } },
  ],
  channels: {
    whatsapp: {
      accounts: {
        personal: {},
        biz: {},
      },
    },
  },
}

​

tools.agentToAgent (optional)

{
  tools: {
    agentToAgent: {
      enabled: false,
      allow: ["home", "work"],
    },
  },
}

​

messages.queue

{
  messages: {
    queue: {
      mode: "collect", // steer | followup | collect | steer-backlog (steer+backlog ok) | interrupt (queue=steer legacy)
      debounceMs: 1000,
      cap: 20,
      drop: "summarize", // old | new | summarize
      byChannel: {
        whatsapp: "collect",
        telegram: "collect",
        discord: "collect",
        imessage: "collect",
        webchat: "collect",
      },
    },
  },
}

​

messages.inbound

{
  messages: {
    inbound: {
      debounceMs: 2000, // 0 disables
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
        discord: 1500,
      },
    },
  },
}

• Debounce batches text-only messages; media/attachments flush immediately.
• Control commands (e.g. /queue, /new) bypass debouncing so they stay standalone.

​

commands (chat command handling)

{
  commands: {
    native: "auto", // register native commands when supported (auto)
    text: true, // parse slash commands in chat messages
    bash: false, // allow ! (alias: /bash) (host-only; requires tools.elevated allowlists)
    bashForegroundMs: 2000, // bash foreground window (0 backgrounds immediately)
    config: false, // allow /config (writes to disk)
    debug: false, // allow /debug (runtime-only overrides)
    restart: false, // allow /restart + gateway restart tool
    useAccessGroups: true, // enforce access-group allowlists/policies for commands
  },
}

• Text commands must be sent as a standalone message and use the leading / (no plain-text aliases).
• commands.text: false disables parsing chat messages for commands.
• commands.native: "auto" (default) turns on native commands for Discord/Telegram and leaves Slack off; unsupported channels stay text-only.
• Đặt commands.native: true|false để ép cho tất cả, hoặc ghi đè theo kênh với channels.discord.commands.native, channels.telegram.commands.native, channels.slack.commands.native (bool hoặc "auto"). false sẽ xóa các lệnh đã đăng ký trước đó trên Discord/Telegram khi khởi động; lệnh Slack được quản lý trong ứng dụng Slack.
• channels.telegram.customCommands adds extra Telegram bot menu entries. Names are normalized; conflicts with native commands are ignored.
• commands.bash: true enables ! <cmd> to run host shell commands (/bash <cmd> also works as an alias). Requires tools.elevated.enabled and allowlisting the sender in tools.elevated.allowFrom.<channel>.
• commands.bashForegroundMs controls how long bash waits before backgrounding. While a bash job is running, new ! <cmd> requests are rejected (one at a time).
• commands.config: true enables /config (reads/writes openclaw.json).
• channels.<provider>WhatsApp chạy thông qua kênh web của gateway (Baileys Web). This applies to /config set|unset` plus provider-specific auto-migrations (Telegram supergroup ID changes, Slack channel ID changes).
• commands.debug: true enables /debug (runtime-only overrides).
• commands.restart: true enables /restart and the gateway tool restart action.
• commands.useAccessGroups: false allows commands to bypass access-group allowlists/policies.
• Slash commands and directives are only honored for authorized senders. Authorization is derived from channel allowlists/pairing plus commands.useAccessGroups.

​

web (WhatsApp web channel runtime)

{
  web: {
    enabled: true,
    heartbeatSeconds: 60,
    reconnect: {
      initialMs: 2000,
      maxMs: 120000,
      factor: 1.4,
      jitter: 0.2,
      maxAttempts: 0,
    },
  },
}

​

channels.telegram (bot transport)

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["tg:123456789"], // optional; "open" requires ["*"]
      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, // include last N group messages as context (0 disables)
      replyToMode: "first", // off | first | all
      linkPreview: true, // toggle outbound link previews
      streamMode: "partial", // off | partial | block (draft streaming; separate from block streaming)
      draftChunk: {
        // optional; only for streamMode=block
        minChars: 200,
        maxChars: 800,
        breakPreference: "paragraph", // paragraph | newline | sentence
      },
      actions: { reactions: true, sendMessage: true }, // tool action gates (false disables)
      reactionNotifications: "own", // off | own | all
      mediaMaxMb: 5,
      retry: {
        // outbound retry policy
        attempts: 3,
        minDelayMs: 400,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
      network: {
        // transport overrides
        autoSelectFamily: false,
      },
      proxy: "socks5://localhost:9050",
      webhookUrl: "https://example.com/telegram-webhook", // requires webhookSecret
      webhookSecret: "secret",
      webhookPath: "/telegram-webhook",
    },
  },
}

• Uses Telegram sendMessageDraft (draft bubble, not a real message).
• Requires private chat topics (message_thread_id in DMs; bot has topics enabled).
• /reasoning stream streams reasoning into the draft, then sends the final answer. Retry policy defaults and behavior are documented in Retry policy.

​

channels.discord (bot transport)

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      mediaMaxMb: 8, // clamp inbound media size
      allowBots: false, // allow bot-authored messages
      actions: {
        // tool action gates (false disables)
        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
      dm: {
        enabled: true, // disable all DMs when false
        policy: "pairing", // pairing | allowlist | open | disabled
        allowFrom: ["1234567890", "steipete"], // optional DM allowlist ("open" requires ["*"])
        groupEnabled: false, // enable group DMs
        groupChannels: ["openclaw-dm"], // optional group DM allowlist
      },
      guilds: {
        "123456789012345678": {
          // guild id (preferred) or slug
          slug: "friends-of-openclaw",
          requireMention: false, // per-guild default
          reactionNotifications: "own", // off | own | all | allowlist
          users: ["987654321098765432"], // optional per-guild user allowlist
          channels: {
            general: { allow: true },
            help: {
              allow: true,
              requireMention: true,
              users: ["987654321098765432"],
              skills: ["docs"],
              systemPrompt: "Short answers only.",
            },
          },
        },
      },
      historyLimit: 20, // include last N guild messages as context
      textChunkLimit: 2000, // optional outbound text chunk size (chars)
      chunkMode: "length", // optional chunking mode (length | newline)
      maxLinesPerMessage: 17, // soft max lines per message (Discord UI clipping)
      retry: {
        // outbound retry policy
        attempts: 3,
        minDelayMs: 500,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
    },
  },
}

• off: no reaction events.
• own: reactions on the bot’s own messages (default).
• all: all reactions on all messages.
• allowlist: reactions from guilds.<id>.users on all messages (empty list disables). Outbound text is chunked by channels.discord.textChunkLimit (default 2000). Set channels.discord.chunkMode="newline" to split on blank lines (paragraph boundaries) before length chunking. Discord clients can clip very tall messages, so channels.discord.maxLinesPerMessage (default 17) splits long multi-line replies even when under 2000 chars. Retry policy defaults and behavior are documented in Retry policy.

​

channels.googlechat (Chat API webhook)

{
  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", // optional; improves mention detection
      dm: {
        enabled: true,
        policy: "pairing", // pairing | allowlist | open | disabled
        allowFrom: ["users/1234567890"], // optional; "open" requires ["*"]
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": { allow: true, requireMention: true },
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}

• Service account JSON can be inline (serviceAccount) or file-based (serviceAccountFile).
• Env fallbacks for the default account: GOOGLE_CHAT_SERVICE_ACCOUNT or GOOGLE_CHAT_SERVICE_ACCOUNT_FILE.
• audienceType + audience must match the Chat app’s webhook auth config.
• Use spaces/<spaceId> or users/<userId|email> when setting delivery targets.

​

channels.slack (socket mode)

{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      appToken: "xapp-...",
      dm: {
        enabled: true,
        policy: "pairing", // pairing | allowlist | open | disabled
        allowFrom: ["U123", "U456", "*"], // optional; "open" requires ["*"]
        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, // include last N channel/group messages as context (0 disables)
      allowBots: false,
      reactionNotifications: "own", // off | own | all | allowlist
      reactionAllowlist: ["U123"],
      replyToMode: "off", // off | first | all
      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,
      },
      textChunkLimit: 4000,
      chunkMode: "length",
      mediaMaxMb: 20,
    },
  },
}

• off: no reaction events.
• own: reactions on the bot’s own messages (default).
• all: all reactions on all messages.
• allowlist: reactions from channels.slack.reactionAllowlist on all messages (empty list disables).

• channels.slack.thread.historyScope controls whether thread history is per-thread (thread, default) or shared across the channel (channel).
• channels.slack.thread.inheritParent controls whether new thread sessions inherit the parent channel transcript (default: false).

​

channels.mattermost (bot token)

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
      chatmode: "oncall", // oncall | onmessage | onchar
      oncharPrefixes: [">", "!"],
      textChunkLimit: 4000,
      chunkMode: "length",
    },
  },
}

• oncall (default): respond to channel messages only when @mentioned.
• onmessage: respond to every channel message.
• onchar: respond when a message starts with a trigger prefix (channels.mattermost.oncharPrefixes, default [">", "!"]).

• Default DMs: channels.mattermost.dmPolicy="pairing" (unknown senders get a pairing code).
• Public DMs: channels.mattermost.dmPolicy="open" plus channels.mattermost.allowFrom=["*"].
• Groups: channels.mattermost.groupPolicy="allowlist" by default (mention-gated). Use channels.mattermost.groupAllowFrom to restrict senders.

​

channels.signal (signal-cli)

{
  channels: {
    signal: {
      reactionNotifications: "own", // off | own | all | allowlist
      reactionAllowlist: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      historyLimit: 50, // include last N group messages as context (0 disables)
    },
  },
}

• off: no reaction events.
• own: reactions on the bot’s own messages (default).
• all: all reactions on all messages.
• allowlist: reactions from channels.signal.reactionAllowlist on all messages (empty list disables).

​

channels.imessage (imsg CLI)

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "imsg",
      dbPath: "~/Library/Messages/chat.db",
      remoteHost: "user@gateway-host", // SCP for remote attachments when using SSH wrapper
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "[email protected]", "chat_id:123"],
      historyLimit: 50, // include last N group messages as context (0 disables)
      includeAttachments: false,
      mediaMaxMb: 16,
      service: "auto",
      region: "US",
    },
  },
}

• Requires Full Disk Access to the Messages DB.
• The first send will prompt for Messages automation permission.
• Ưu tiên các mục tiêu chat_id:<id>. Use imsg chats --limit 20 to list chats.
• channels.imessage.cliPath can point to a wrapper script (e.g. ssh to another Mac that runs imsg rpc); use SSH keys to avoid password prompts.
• For remote SSH wrappers, set channels.imessage.remoteHost to fetch attachments via SCP when includeAttachments is enabled.

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

​

agents.defaults.workspace

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

​

agents.defaults.repoRoot

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

​

agents.defaults.skipBootstrap

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

​

agents.defaults.bootstrapMaxChars

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

​

agents.defaults.userTimezone

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

​

agents.defaults.timeFormat

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

​

messages

{
  messages: {
    responsePrefix: "🦞", // or "auto"
    ackReaction: "👀",
    ackReactionScope: "group-mentions",
    removeAckAfterReply: false,
  },
}

• channels.<channel>.responsePrefix`
• channels.<channel>.accounts.<id>.responsePrefix

1. channels.<channel>.accounts.<id>.responsePrefix`
2. channels.<channel>.responsePrefix
3. messages.responsePrefix

• undefined falls through to the next level.
• "" explicitly disables the prefix and stops the cascade.
• "auto" derives [{identity.name}] for the routed agent.

​

Template variables

{
  messages: {
    responsePrefix: "[{model} | think:{thinkingLevel}]",
  },
}

• group-mentions (default): only when a group/room requires mentions and the bot was mentioned
• group-all: all group/room messages
• direct: direct messages only
• all: all messages

2. removeAckAfterReply sẽ xóa phản ứng xác nhận (ack) của bot sau khi gửi xong phản hồi (Slack/Discord/Telegram/Google Chat בלבד). 3. Mặc định: false.

​

messages.tts

{
  messages: {
    tts: {
      auto: "always", // off | always | inbound | tagged
      mode: "final", // final | all (include tool/block replies)
      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",
        model: "gpt-4o-mini-tts",
        voice: "alloy",
      },
    },
  },
}

• messages.tts.auto controls auto‑TTS (off, always, inbound, tagged).
• /tts off|always|inbound|tagged sets the per‑session auto mode (overrides config).
• messages.tts.enabled is legacy; doctor migrates it to messages.tts.auto.
• prefsPath stores local overrides (provider/limit/summarize).
• maxTextLength is a hard cap for TTS input; summaries are truncated to fit.
• summaryModel overrides agents.defaults.model.primary for auto-summary.
  • Accepts provider/model or an alias from agents.defaults.models.
• modelOverrides enables model-driven overrides like [[tts:...]] tags (on by default).
• /tts limit and /tts summary control per-user summarization settings.
• apiKey values fall back to ELEVENLABS_API_KEY/XI_API_KEY and OPENAI_API_KEY.
• elevenlabs.baseUrl overrides the ElevenLabs API base URL.
• elevenlabs.voiceSettings supports stability/similarityBoost/style (0..1), useSpeakerBoost, and speed (0.5..2.0).

​

talk

{
  talk: {
    voiceId: "elevenlabs_voice_id",
    voiceAliases: {
      Clawd: "EXAVITQu4vr4xnSDxMaL",
      Roger: "CwhRBWXzGAHq8TQ4Fs17",
    },
    modelId: "eleven_v3",
    outputFormat: "mp3_44100_128",
    apiKey: "elevenlabs_api_key",
    interruptOnSpeech: true,
  },
}

​

agents.defaults

• alias (optional model shortcut, e.g. /opus).
• params (optional provider-specific API params passed through to the model request).

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-sonnet-4-5-20250929": {
          params: { temperature: 0.6 },
        },
        "openai/gpt-5.2": {
          params: { maxTokens: 8192 },
        },
      },
    },
  },
}

• set --thinking off, or
• define agents.defaults.models["zai/<model>"].params.thinking yourself.

• opus -> anthropic/claude-opus-4-6
• sonnet -> anthropic/claude-sonnet-4-5
• gpt -> openai/gpt-5.2
• gpt-mini -> openai/gpt-5-mini
• gemini -> google/gemini-3-pro-preview
• gemini-flash -> google/gemini-3-flash-preview

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "minimax/MiniMax-M2.1": { alias: "minimax" },
      },
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["minimax/MiniMax-M2.1"],
      },
    },
  },
}

​

agents.defaults.cliBackends (CLI fallback)

• CLI backends are text-first; tools are always disabled.
• Sessions are supported when sessionArg is set; session ids are persisted per backend.
• For claude-cli, defaults are wired in. Override the command path if PATH is minimal (launchd/systemd).

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

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": { alias: "Opus" },
        "anthropic/claude-sonnet-4-1": { alias: "Sonnet" },
        "openrouter/deepseek/deepseek-r1:free": {},
        "zai/glm-4.7": {
          alias: "GLM",
          params: {
            thinking: {
              type: "enabled",
              clear_thinking: false,
            },
          },
        },
      },
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: [
          "openrouter/deepseek/deepseek-r1:free",
          "openrouter/meta-llama/llama-3.3-70b-instruct:free",
        ],
      },
      imageModel: {
        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
        fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],
      },
      thinkingDefault: "low",
      verboseDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      heartbeat: {
        every: "30m",
        target: "last",
      },
      maxConcurrent: 3,
      subagents: {
        model: "minimax/MiniMax-M2.1",
        maxConcurrent: 1,
        archiveAfterMinutes: 60,
      },
      exec: {
        backgroundMs: 10000,
        timeoutSec: 1800,
        cleanupMs: 1800000,
      },
      contextTokens: 200000,
    },
  },
}

​

agents.defaults.contextPruning (tool-result pruning)

• Never touches user/assistant messages.
• Protects the last keepLastAssistants assistant messages (no tool results after that point are pruned).
• Protects the bootstrap prefix (nothing before the first user message is pruned).
• Modes:
  • adaptive: soft-trims oversized tool results (keep head/tail) when the estimated context ratio crosses softTrimRatio. Then hard-clears the oldest eligible tool results when the estimated context ratio crosses hardClearRatio and there’s enough prunable tool-result bulk (minPrunableToolChars).
  • aggressive: always replaces eligible tool results before the cutoff with the hardClear.placeholder (no ratio checks).

• Soft-trim: only for oversized tool results. Keeps the beginning + end and inserts ... in the middle.
  • Before: toolResult("…very long output…")
  • After: toolResult("HEAD…\n...\n…TAIL\n\n[Tool result trimmed: …]")
• Hard-clear: replaces the entire tool result with the placeholder.
  • Before: toolResult("…very long output…")
  • After: toolResult("[Old tool result content cleared]")

• Tool results containing image blocks are skipped (never trimmed/cleared) right now.
• The estimated “context ratio” is based on characters (approximate), not exact tokens.
• If the session doesn’t contain at least keepLastAssistants assistant messages yet, pruning is skipped.
• In aggressive mode, hardClear.enabled is ignored (eligible tool results are always replaced with hardClear.placeholder).

{
  agents: { defaults: { contextPruning: { mode: "adaptive" } } },
}

{
  agents: { defaults: { contextPruning: { mode: "off" } } },
}

• keepLastAssistants: 3
• softTrimRatio: 0.3 (adaptive only)
• hardClearRatio: 0.5 (adaptive only)
• minPrunableToolChars: 50000 (adaptive only)
• softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 } (adaptive only)
• hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" }

{
  agents: { defaults: { contextPruning: { mode: "aggressive" } } },
}

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "adaptive",
        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]" },
        // Optional: restrict pruning to specific tools (deny wins; supports "*" wildcards)
        tools: { deny: ["browser", "canvas"] },
      },
    },
  },
}

​

agents.defaults.compaction (reserve headroom + memory flush)

• memoryFlush.enabled: true
• memoryFlush.softThresholdTokens: 4000
• memoryFlush.prompt / memoryFlush.systemPrompt: built-in defaults with NO_REPLY
• Note: memory flush is skipped when the session workspace is read-only (agents.defaults.sandbox.workspaceAccess: "ro" or "none").

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard",
        reserveTokensFloor: 24000,
        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 NO_REPLY if nothing to store.",
        },
      },
    },
  },
}

• agents.defaults.blockStreamingDefault: "on"/"off" (default off).
• Ghi đè theo kênh: *.blockStreaming (và các biến thể theo tài khoản) để buộc bật/tắt block streaming. Các kênh không phải Telegram yêu cầu thiết lập rõ ràng *.blockStreaming: true để bật trả lời theo khối.
• agents.defaults.blockStreamingBreak: "text_end" or "message_end" (default: text_end).
• agents.defaults.blockStreamingChunk: soft chunking for streamed blocks. Defaults to 800–1200 chars, prefers paragraph breaks (\n\n), then newlines, then sentences. Example:
  {
    agents: { defaults: { blockStreamingChunk: { minChars: 800, maxChars: 1200 } } },
  }
  
• agents.defaults.blockStreamingCoalesce: gộp các block được stream trước khi gửi. Defaults to { idleMs: 1000 } and inherits minChars from blockStreamingChunk with maxChars capped to the channel text limit. Signal/Slack/Discord/Google Chat mặc định là minChars: 1500 trừ khi được ghi đè. Channel overrides: channels.whatsapp.blockStreamingCoalesce, channels.telegram.blockStreamingCoalesce, channels.discord.blockStreamingCoalesce, channels.slack.blockStreamingCoalesce, channels.mattermost.blockStreamingCoalesce, channels.signal.blockStreamingCoalesce, channels.imessage.blockStreamingCoalesce, channels.msteams.blockStreamingCoalesce, channels.googlechat.blockStreamingCoalesce (and per-account variants).
• agents.defaults.humanDelay: randomized pause between block replies after the first. Modes: off (default), natural (800–2500ms), custom (use minMs/maxMs). Per-agent override: agents.list[].humanDelay. Example:
  {
    agents: { defaults: { humanDelay: { mode: "natural" } } },
  }
  
  See /concepts/streaming for behavior + chunking details.

• agents.defaults.typingMode: "never" | "instant" | "thinking" | "message". Defaults to instant for direct chats / mentions and message for unmentioned group chats.
• session.typingMode: per-session override for the mode.
• agents.defaults.typingIntervalSeconds: how often the typing signal is refreshed (default: 6s).
• session.typingIntervalSeconds: per-session override for the refresh interval. See /concepts/typing-indicators for behavior details.

• every: duration string (ms, s, m, h); default unit minutes. Default: 30m. Set 0m to disable.
• model: optional override model for heartbeat runs (provider/model).
• includeReasoning: when true, heartbeats will also deliver the separate Reasoning: message when available (same shape as /reasoning on). Default: false.
• session: optional session key to control which session the heartbeat runs in. Default: main.
• to: optional recipient override (channel-specific id, e.g. E.164 for WhatsApp, chat id for Telegram).
• target: optional delivery channel (last, whatsapp, telegram, discord, slack, msteams, signal, imessage, none). Default: last.
• prompt: optional override for the heartbeat body (default: Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.). Overrides are sent verbatim; include a Read HEARTBEAT.md line if you still want the file read.
• ackMaxChars: max chars allowed after HEARTBEAT_OK before delivery (default: 300).

• Set agents.list[].heartbeat to enable or override heartbeat settings for a specific agent.
• If any agent entry defines heartbeat, only those agents run heartbeats; defaults become the shared baseline for those agents.

• backgroundMs: time before auto-background (ms, default 10000)
• timeoutSec: auto-kill after this runtime (seconds, default 1800)
• cleanupMs: how long to keep finished sessions in memory (ms, default 1800000)
• notifyOnExit: enqueue a system event + request heartbeat when backgrounded exec exits (default true)
• applyPatch.enabled: enable experimental apply_patch (OpenAI/OpenAI Codex only; default false)
• applyPatch.allowModels: optional allowlist of model ids (e.g. gpt-5.2 or openai/gpt-5.2) Note: applyPatch is only under tools.exec.

• tools.web.search.enabled (default: true when key is present)
• tools.web.search.apiKey (recommended: set via openclaw configure --section web, or use BRAVE_API_KEY env var)
• tools.web.search.maxResults (1–10, default 5)
• tools.web.search.timeoutSeconds (default 30)
• tools.web.search.cacheTtlMinutes (default 15)
• tools.web.fetch.enabled (default true)
• tools.web.fetch.maxChars (default 50000)
• tools.web.fetch.maxCharsCap (default 50000; clamps maxChars from config/tool calls)
• tools.web.fetch.timeoutSeconds (default 30)
• tools.web.fetch.cacheTtlMinutes (default 15)
• tools.web.fetch.userAgent (optional override)
• tools.web.fetch.readability (default true; disable to use basic HTML cleanup only)
• tools.web.fetch.firecrawl.enabled (default true when an API key is set)
• tools.web.fetch.firecrawl.apiKey (optional; defaults to FIRECRAWL_API_KEY)
• tools.web.fetch.firecrawl.baseUrl (default https://api.firecrawl.dev)
• tools.web.fetch.firecrawl.onlyMainContent (default true)
• tools.web.fetch.firecrawl.maxAgeMs (optional)
• tools.web.fetch.firecrawl.timeoutSeconds (optional)

• tools.media.models: shared model list (capability-tagged; used after per-cap lists).
• tools.media.concurrency: max concurrent capability runs (default 2).
• tools.media.image / tools.media.audio / tools.media.video:
  • enabled: opt-out switch (default true when models are configured).
  • prompt: optional prompt override (image/video append a maxChars hint automatically).
  • maxChars: max output characters (default 500 for image/video; unset for audio).
  • maxBytes: max media size to send (defaults: image 10MB, audio 20MB, video 50MB).
  • timeoutSeconds: request timeout (defaults: image 60s, audio 60s, video 120s).
  • language: optional audio hint.
  • attachments: attachment policy (mode, maxAttachments, prefer).
  • scope: optional gating (first match wins) with match.channel, match.chatType, or match.keyPrefix.
  • models: ordered list of model entries; failures or oversize media fall back to the next entry.
• Each models[] entry:
  • Provider entry (type: "provider" or omitted):
    • provider: API provider id (openai, anthropic, google/gemini, groq, etc).
    • model: model id override (required for image; defaults to gpt-4o-mini-transcribe/whisper-large-v3-turbo for audio providers, and gemini-3-flash-preview for video).
    • profile / preferredProfile: auth profile selection.
  • CLI entry (type: "cli"):
    • command: executable to run.
    • args: templated args (supports {{MediaPath}}, {{Prompt}}, {{MaxChars}}, etc).
  • capabilities: optional list (image, audio, video) to gate a shared entry. Defaults when omitted: openai/anthropic/minimax → image, google → image+audio+video, groq → audio.
  • prompt, maxChars, maxBytes, timeoutSeconds, language can be overridden per entry.

{
  tools: {
    media: {
      audio: {
        enabled: true,
        maxBytes: 20971520,
        scope: {
          default: "deny",
          rules: [{ action: "allow", match: { chatType: "direct" } }],
        },
        models: [
          { provider: "openai", model: "gpt-4o-mini-transcribe" },
          { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] },
        ],
      },
      video: {
        enabled: true,
        maxBytes: 52428800,
        models: [{ provider: "google", model: "gemini-3-flash-preview" }],
      },
    },
  },
}

• model: default model for spawned sub-agents (string or { primary, fallbacks }). If omitted, sub-agents inherit the caller’s model unless overridden per agent or per call.
• maxConcurrent: max concurrent sub-agent runs (default 1)
• archiveAfterMinutes: auto-archive sub-agent sessions after N minutes (default 60; set 0 to disable)
• Per-subagent tool policy: tools.subagents.tools.allow / tools.subagents.tools.deny (deny wins)

• minimal: session_status only
• coding: group:fs, group:runtime, group:sessions, group:memory, image
• messaging: group:messaging, sessions_list, sessions_history, sessions_send, session_status
• full: no restriction (same as unset)

{
  tools: {
    profile: "messaging",
    allow: ["slack", "discord"],
  },
}

{
  tools: {
    profile: "coding",
    deny: ["group:runtime"],
  },
}

{
  tools: {
    profile: "coding",
    byProvider: {
      "google-antigravity": { profile: "minimal" },
    },
  },
}

{
  tools: {
    allow: ["group:fs", "group:runtime", "sessions_list"],
    byProvider: {
      "openai/gpt-5.2": { allow: ["group:fs", "sessions_list"] },
    },
  },
}

{
  tools: { deny: ["browser", "canvas"] },
}

• group:runtime: exec, bash, process
• group:fs: read, write, edit, apply_patch
• group:sessions: sessions_list, sessions_history, sessions_send, sessions_spawn, session_status
• group:memory: memory_search, memory_get
• group:web: web_search, web_fetch
• group:ui: browser, canvas
• group:automation: cron, gateway
• group:messaging: message
• group:nodes: nodes
• group:openclaw: all built-in OpenClaw tools (excludes provider plugins)

• enabled: allow elevated mode (default true)
• allowFrom: per-channel allowlists (empty = disabled)
  • whatsapp: E.164 numbers
  • telegram: chat ids or usernames
  • discord: user ids or usernames (falls back to channels.discord.dm.allowFrom if omitted)
  • signal: E.164 numbers
  • imessage: handles/chat ids
  • webchat: session ids or usernames

{
  tools: {
    elevated: {
      enabled: true,
      allowFrom: {
        whatsapp: ["+15555550123"],
        discord: ["steipete", "1234567890123"],
      },
    },
  },
}

{
  agents: {
    list: [
      {
        id: "family",
        tools: {
          elevated: { enabled: false },
        },
      },
    ],
  },
}

• tools.elevated is the global baseline. agents.list[].tools.elevated can only further restrict (both must allow).
• /elevated on|off|ask|full stores state per session key; inline directives apply to a single message.
• Elevated exec runs on the host and bypasses sandboxing.
• Tool policy still applies; if exec is denied, elevated cannot be used.

​

agents.defaults.sandbox

• scope: "agent" (one container + workspace per agent)
• Debian bookworm-slim based image
• agent workspace access: workspaceAccess: "none" (default)
  • "none": use a per-scope sandbox workspace under ~/.openclaw/sandboxes
• "ro": keep the sandbox workspace at /workspace, and mount the agent workspace read-only at /agent (disables write/edit/apply_patch)
  • "rw": mount the agent workspace read/write at /workspace
• auto-prune: idle > 24h OR age > 7d
• tool policy: allow only exec, process, read, write, edit, apply_patch, sessions_list, sessions_history, sessions_send, sessions_spawn, session_status (deny wins)
  • configure via tools.sandbox.tools, override per-agent via agents.list[].tools.sandbox.tools
  • tool group shorthands supported in sandbox policy: group:runtime, group:fs, group:sessions, group:memory (see Sandbox vs Tool Policy vs Elevated)
• optional sandboxed browser (Chromium + CDP, noVNC observer)
• hardening knobs: network, user, pidsLimit, memory, cpus, ulimits, seccompProfile, apparmorProfile