> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration Reference

> Complete field-by-field reference for ~/.openclaw/openclaw.json

# Configuration Reference

Every field available in `~/.openclaw/openclaw.json`. For a task-oriented overview, see [Configuration](https://docs.wednesdayai.dev/next/admin/gateway/configuration.md).

Config format is **JSON5** (comments + trailing commas allowed). All fields are optional — WednesdayAI uses safe defaults when omitted.

***

## Channels

Each channel starts automatically when its config section exists (unless `enabled: false`).

### DM and group access

All channels support DM policies and group policies:

| DM policy | Behavior |
| - | - |
| `pairing` (default) | Unknown senders get a one-time pairing code; owner must approve |
| `allowlist` | Only senders in `allowFrom` (or paired allow store) |
| `open` | Allow all inbound DMs (requires `allowFrom: ["*"]`) |
| `disabled` | Ignore all inbound DMs |

| Group policy | Behavior |
| - | - |
| `allowlist` (default) | Only groups matching the configured allowlist |
| `open` | Bypass group allowlists (mention-gating still applies) |
| `disabled` | Block all group/room messages |

> [!NOTE]
>
> `channels.defaults.groupPolicy` sets the default when a provider's `groupPolicy` is unset.
> Pairing codes expire after 1 hour. Pending DM pairing requests are capped at **3 per channel**.
> If a provider block is missing entirely (`channels.<provider>` absent), runtime group policy falls back to `allowlist` (fail-closed) with a startup warning.

### Channel model overrides

Use `channels.modelByChannel` to pin specific channel IDs to a model. Values accept `provider/model` or configured model aliases. The channel mapping applies when a session does not already have a model override (for example, set via `/model`).

```json5 theme={"dark"}
{
  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",
      },
    },
  },
}
```

### Channel defaults and heartbeat

Use `channels.defaults` for shared group-policy and heartbeat behavior across providers:

```json5 theme={"dark"}
{
  channels: {
    defaults: {
      groupPolicy: "allowlist", // open | allowlist | disabled
      heartbeat: {
        showOk: false,
        showAlerts: true,
        useIndicator: true,
      },
    },
  },
}
```

* `channels.defaults.groupPolicy`: fallback group policy when a provider-level `groupPolicy` is unset.
* `channels.defaults.heartbeat.showOk`: include healthy channel statuses in heartbeat output.
* `channels.defaults.heartbeat.showAlerts`: include degraded/error statuses in heartbeat output.
* `channels.defaults.heartbeat.useIndicator`: render compact indicator-style heartbeat output.

### WhatsApp

WhatsApp runs through the gateway's web channel (Baileys Web). It starts automatically when a linked session exists.
The config key remains `channels.whatsapp` even though WhatsApp is supplied by a bundled channel plugin;
gateway validation resolves compatibility channel ids before reporting unknown channel keys, so this block is
valid in both packaged installs and source checkouts.

```json5 theme={"dark"}
{
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000,
      chunkMode: "length", // length | newline | paragraph
      chunkNewlinePacking: true, // deprecated; only applies with chunkMode "newline" (false then ≡ paragraph)
      mediaMaxMb: 50,
      sendReadReceipts: true, // blue ticks (false in self-chat mode)
      syncFullHistory: false, // request full history at the next QR re-link
      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,
    },
  },
}
```

> [accordion] Multi-account WhatsApp
>
> ```json5 theme={"dark"}
> {
>   channels: {
>     whatsapp: {
>       accounts: {
>         default: {},
>         personal: {},
>         biz: {
>           // authDir: "~/.openclaw/credentials/whatsapp/biz",
>         },
>       },
>     },
>   },
> }
> ```
>
> * Outbound commands default to account `default` if present; otherwise the first configured account id (sorted).
> * Optional `channels.whatsapp.defaultAccount` overrides that fallback default account selection when it matches a configured account id.
> * Legacy single-account Baileys auth dir is migrated by `wednesdayai doctor` into `whatsapp/default`.
> * Per-account overrides: `channels.whatsapp.accounts.<id>.sendReadReceipts`, `channels.whatsapp.accounts.<id>.syncFullHistory`, `channels.whatsapp.accounts.<id>.dmPolicy`, `channels.whatsapp.accounts.<id>.allowFrom`.

### Telegram

```json5 theme={"dark"}
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing",
      allowFrom: ["tg:123456789"],
      groups: {
        "*": { requireMention: true },
        "-1001234567890": {
          allowFrom: ["987654321"],
          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
      linkPreview: true,
      streaming: "partial", // off | partial | block | progress (default: partial)
      actions: { reactions: true, sendMessage: true },
      reactionNotifications: "own", // off | own | all
      mediaMaxMb: 5,
      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",
    },
  },
}
```

* Bot token: `channels.telegram.botToken` or `channels.telegram.tokenFile`, with `TELEGRAM_BOT_TOKEN` as fallback for the default account.
* Multi-bot fleet: define `channels.telegram.accounts.<id>` with account-level `botToken` or `tokenFile` values. Accounts inherit base access controls unless overridden. Avoid letting two enabled accounts resolve to the same token; the Telegram fleet supervisor marks duplicate local owners as `conflicted`.
* Webhook fields (`webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`, `webhookPort`) can be set per account. One bot token should have one intake owner and one intake mode: polling or webhook.
* Optional `channels.telegram.defaultAccount` overrides default account selection when it matches a configured account id.
* `configWrites: false` blocks Telegram-initiated config writes (supergroup ID migrations, `/config set|unset`).
* Telegram stream previews use `sendMessage` + `editMessageText` (works in direct and group chats).
* Retry policy: see [Retry policy](https://docs.wednesdayai.dev/next/developers/concepts/retry.md).
* Full fleet operations guide: [Telegram multi-bot fleet](https://docs.wednesdayai.dev/next/admin/channels/telegram.md#multi-bot-fleet).

### Discord

```json5 theme={"dark"}
{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      mediaMaxMb: 8,
      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
      dmPolicy: "pairing",
      allowFrom: ["1234567890", "123456789012345678"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["openclaw-dm"] },
      guilds: {
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          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 | paragraph
      chunkNewlinePacking: true, // deprecated; only applies with chunkMode "newline" (false then ≡ paragraph)
      streaming: "off", // off | partial | block | progress (progress maps to partial on Discord)
      maxLinesPerMessage: 17,
      ui: {
        components: {
          accentColor: "#5865F2",
        },
      },
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSubagentSessions: false, // opt-in for sessions_spawn({ thread: true })
      },
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        tts: {
          provider: "openai",
          openai: { voice: "alloy" },
        },
      },
      retry: {
        attempts: 3,
        minDelayMs: 500,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
    },
  },
}
```

* Token: `channels.discord.token`, with `DISCORD_BOT_TOKEN` as fallback for the default account.
* Optional `channels.discord.defaultAccount` overrides default account selection when it matches a configured account id.
* Use `user:<id>` (DM) or `channel:<id>` (guild channel) for delivery targets; bare numeric IDs are rejected.
* Guild slugs are lowercase with spaces replaced by `-`; channel keys use the slugged name (no `#`). Prefer guild IDs.
* Bot-authored messages are ignored by default. `allowBots: true` enables them (own messages still filtered).
* `maxLinesPerMessage` (default 17) splits tall messages even when under 2000 chars.
* `channels.discord.threadBindings` controls Discord thread-bound routing:
  * `enabled`: Discord override for thread-bound session features (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, and bound delivery/routing)
  * `idleHours`: Discord override for inactivity auto-unfocus in hours (`0` disables)
  * `maxAgeHours`: Discord override for hard max age in hours (`0` disables)
  * `spawnSubagentSessions`: opt-in switch for `sessions_spawn({ thread: true })` auto thread creation/binding
* `channels.discord.ui.components.accentColor` sets the accent color for Discord components v2 containers.
* `channels.discord.voice` enables Discord voice channel conversations and optional auto-join + TTS overrides.
* `channels.discord.voice.daveEncryption` and `channels.discord.voice.decryptionFailureTolerance` pass through to `@discordjs/voice` DAVE options (`true` and `24` by default).
* WednesdayAI additionally attempts voice receive recovery by leaving/rejoining a voice session after repeated decrypt failures.
* `channels.discord.streaming` is the canonical stream mode key. Legacy `streamMode` and boolean `streaming` values are auto-migrated.
* `channels.discord.dangerouslyAllowNameMatching` re-enables mutable name/tag matching (break-glass compatibility mode).

**Reaction notification modes:** `off` (none), `own` (bot's messages, default), `all` (all messages), `allowlist` (from `guilds.<id>.users` on all messages).

### Google Chat

```json5 theme={"dark"}
{
  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,
    },
  },
}
```

* Service account JSON: inline (`serviceAccount`) or file-based (`serviceAccountFile`).
* Service account SecretRef is also supported (`serviceAccountRef`).
* Env fallbacks: `GOOGLE_CHAT_SERVICE_ACCOUNT` or `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`.
* Use `spaces/<spaceId>` or `users/<userId>` for delivery targets.
* `channels.googlechat.dangerouslyAllowNameMatching` re-enables mutable email principal matching (break-glass compatibility mode).

### Slack

```json5 theme={"dark"}
{
  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
      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", // length | newline | paragraph
      chunkNewlinePacking: true, // deprecated; only applies with chunkMode "newline" (false then ≡ paragraph)
      streaming: "partial", // off | partial | block | progress (preview mode)
      nativeStreaming: true, // use Slack native streaming API when streaming=partial
      mediaMaxMb: 20,
    },
  },
}
```

* **Socket mode** requires both `botToken` and `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` for default account env fallback).
* **HTTP mode** requires `botToken` plus `signingSecret` (at root or per-account).
* `configWrites: false` blocks Slack-initiated config writes.
* Optional `channels.slack.defaultAccount` overrides default account selection when it matches a configured account id.
* `channels.slack.streaming` is the canonical stream mode key. Legacy `streamMode` and boolean `streaming` values are auto-migrated.
* Use `user:<id>` (DM) or `channel:<id>` for delivery targets.

**Reaction notification modes:** `off`, `own` (default), `all`, `allowlist` (from `reactionAllowlist`).

**Thread session isolation:** `thread.historyScope` is per-thread (default) or shared across channel. `thread.inheritParent` copies parent channel transcript to new threads.

| Action group | Default | Notes |
| - | - | - |
| reactions | enabled | React + list reactions |
| messages | enabled | Read/send/edit/delete |
| pins | enabled | Pin/unpin/list |
| memberInfo | enabled | Member info |
| emojiList | enabled | Custom emoji list |

### Mattermost

Mattermost ships as a bundled plugin: `wednesdayai plugins install mattermost` (the legacy `@openclaw/mattermost` spec resolves to the same bundled copy).

```json5 theme={"dark"}
{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
      chatmode: "oncall", // oncall | onmessage | onchar
      oncharPrefixes: [">", "!"],
      textChunkLimit: 4000,
      chunkMode: "length", // length | newline | paragraph
      chunkNewlinePacking: true, // deprecated; only applies with chunkMode "newline" (false then ≡ paragraph)
    },
  },
}
```

Chat modes: `oncall` (respond on @-mention, default), `onmessage` (every message), `onchar` (messages starting with trigger prefix).

* `channels.mattermost.configWrites`: allow or deny Mattermost-initiated config writes.
* `channels.mattermost.requireMention`: require `@mention` before replying in channels.
* Optional `channels.mattermost.defaultAccount` overrides default account selection when it matches a configured account id.

### Signal

```json5 theme={"dark"}
{
  channels: {
    signal: {
      enabled: true,
      account: "+15555550123", // optional account binding
      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,
    },
  },
}
```

**Reaction notification modes:** `off`, `own` (default), `all`, `allowlist` (from `reactionAllowlist`).

* `channels.signal.account`: pin channel startup to a specific Signal account identity.
* `channels.signal.configWrites`: allow or deny Signal-initiated config writes.
* Optional `channels.signal.defaultAccount` overrides default account selection when it matches a configured account id.

### BlueBubbles

BlueBubbles is the recommended iMessage path (plugin-backed, configured under `channels.bluebubbles`).

```json5 theme={"dark"}
{
  channels: {
    bluebubbles: {
      enabled: true,
      dmPolicy: "pairing",
      // serverUrl, password, webhookPath, group controls, and advanced actions:
      // see /channels/bluebubbles
    },
  },
}
```

* Core key paths covered here: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`.
* Optional `channels.bluebubbles.defaultAccount` overrides default account selection when it matches a configured account id.
* Full BlueBubbles channel configuration is documented in [BlueBubbles](https://docs.wednesdayai.dev/next/admin/channels/bluebubbles.md).

### iMessage

WednesdayAI spawns `imsg rpc` (JSON-RPC over stdio). No daemon or port required.

```json5 theme={"dark"}
{
  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",
    },
  },
}
```

* Optional `channels.imessage.defaultAccount` overrides default account selection when it matches a configured account id.

* Requires Full Disk Access to the Messages DB.

* Prefer `chat_id:<id>` targets. Use `imsg chats --limit 20` to list chats.

* `cliPath` can point to an SSH wrapper; set `remoteHost` (`host` or `user@host`) for SCP attachment fetching.

* `attachmentRoots` and `remoteAttachmentRoots` restrict inbound attachment paths (default: `/Users/*/Library/Messages/Attachments`).

* SCP uses strict host-key checking, so ensure the relay host key already exists in `~/.ssh/known_hosts`.

* `channels.imessage.configWrites`: allow or deny iMessage-initiated config writes.

> [accordion] iMessage SSH wrapper example
>
> ```bash theme={"dark"}
> #!/usr/bin/env bash
> exec ssh -T gateway-host imsg "$@"
> ```

### Microsoft Teams

Microsoft Teams is extension-backed and configured under `channels.msteams`.

```json5 theme={"dark"}
{
  channels: {
    msteams: {
      enabled: true,
      configWrites: true,
      // appId, appPassword, tenantId, webhook, team/channel policies:
      // see /channels/msteams
    },
  },
}
```

* Core key paths covered here: `channels.msteams`, `channels.msteams.configWrites`.
* Full Teams config (credentials, webhook, DM/group policy, per-team/per-channel overrides) is documented in [Microsoft Teams](https://docs.wednesdayai.dev/next/admin/channels/msteams.md).

### IRC

IRC is extension-backed and configured under `channels.irc`.

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

* Core key paths covered here: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`.
* Optional `channels.irc.defaultAccount` overrides default account selection when it matches a configured account id.
* Full IRC channel configuration (host/port/TLS/channels/allowlists/mention gating) is documented in [IRC](https://docs.wednesdayai.dev/next/admin/channels/irc.md).

### Multi-account (all channels)

Run multiple accounts per channel (each with its own `accountId`):

```json5 theme={"dark"}
{
  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.
* Base channel settings apply to all accounts unless overridden per account.
* Use `bindings[].match.accountId` to route each account to a different agent.
* For Telegram, each enabled account should resolve to a distinct bot token; duplicate local token owners surface as `conflicted` in the Channels UI.
* If you add a non-default account via `wednesdayai channels add` (or channel onboarding) while still on a single-account top-level channel config, WednesdayAI moves account-scoped top-level single-account values into `channels.<channel>.accounts.default` first so the original account keeps working.
* Existing channel-only bindings (no `accountId`) keep matching the default account; account-scoped bindings remain optional.
* `wednesdayai doctor --fix` also repairs mixed shapes by moving account-scoped top-level single-account values into `accounts.default` when named accounts exist but `default` is missing.

### Other extension channels

Many extension channels are configured as `channels.<id>` and documented in their dedicated channel pages (for example A2A, Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat, and Twitch).
See the full channel index: [Channels](https://docs.wednesdayai.dev/next/admin/channels.md).

### Group chat mention gating

Group messages default to **require mention** (metadata mention or regex patterns). Applies to WhatsApp, Telegram, Discord, Google Chat, and iMessage group chats.

**Mention types:**

* **Metadata mentions**: Native platform @-mentions. Ignored in WhatsApp self-chat mode.
* **Text patterns**: Regex patterns in `agents.list[].groupChat.mentionPatterns`. Always checked.
* Mention gating is enforced only when detection is possible (native mentions or at least one pattern).

```json5 theme={"dark"}
{
  messages: {
    groupChat: { historyLimit: 50 },
  },
  agents: {
    list: [{ id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"] } }],
  },
}
```

`messages.groupChat.historyLimit` sets the global default. Channels can override with `channels.<channel>.historyLimit` (or per-account). Set `0` to disable.

#### DM history limits

```json5 theme={"dark"}
{
  channels: {
    telegram: {
      dmHistoryLimit: 30,
      dms: {
        "123456789": { historyLimit: 50 },
      },
    },
  },
}
```

Resolution: per-DM override → provider default → no limit (all retained). The DM's channel and
peer id come from the session's stored identity, not the session key text: a session with no
stored identity gets no limit (all retained), and a per-DM override never matches it.

Supported: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`.

#### Self-chat mode

Include your own number in `allowFrom` to enable self-chat mode (ignores native @-mentions, only responds to text patterns):

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

### Commands (chat command handling)

```json5 theme={"dark"}
{
  commands: {
    native: "auto", // register native commands when supported
    text: true, // parse /commands in chat messages
    bash: false, // allow ! (alias: /bash)
    bashForegroundMs: 2000,
    config: false, // allow /config
    debug: false, // allow /debug
    restart: false, // allow /restart + gateway restart tool
    allowFrom: {
      "*": ["user1"],
      discord: ["user:123"],
    },
    useAccessGroups: true,
  },
}
```

> [accordion] Command details
>
> * Text commands must be **standalone** messages with leading `/`.
> * `native: "auto"` turns on native commands for Discord/Telegram, leaves Slack off.
> * Override per channel: `channels.discord.commands.native` (bool or `"auto"`). `false` clears previously registered commands.
> * `channels.telegram.customCommands` adds extra Telegram bot menu entries.
> * `bash: true` enables `! <cmd>` for host shell. Requires `tools.elevated.enabled` and sender in `tools.elevated.allowFrom.<channel>`.
> * `config: true` enables `/config` (reads/writes `openclaw.json`).
> * `channels.<provider>.configWrites` gates config mutations per channel (default: true).
> * `allowFrom` is per-provider. When set, it is the **only** authorization source (channel allowlists/pairing and `useAccessGroups` are ignored).
> * `useAccessGroups: false` allows commands to bypass access-group policies when `allowFrom` is not set.

***

## Agent defaults

### `agents.defaults.workspace`

Default: `~/.openclaw/workspace`.

```json5 theme={"dark"}
{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
}
```

### `agents.defaults.repoRoot`

Optional repository root shown in the system prompt's Runtime line. If unset, WednesdayAI auto-detects by walking upward from the workspace.

```json5 theme={"dark"}
{
  agents: { defaults: { repoRoot: "~/Projects/openclaw" } },
}
```

### `agents.defaults.skipBootstrap`

Disables automatic creation of workspace bootstrap files (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`).

```json5 theme={"dark"}
{
  agents: { defaults: { skipBootstrap: true } },
}
```

### `agents.defaults.bootstrapMaxChars`

Max characters per workspace bootstrap file before truncation. Default: `20000`.

```json5 theme={"dark"}
{
  agents: { defaults: { bootstrapMaxChars: 20000 } },
}
```

### `agents.defaults.bootstrapTotalMaxChars`

Max total characters injected across all workspace bootstrap files. Default: `150000`.

```json5 theme={"dark"}
{
  agents: { defaults: { bootstrapTotalMaxChars: 150000 } },
}
```

### `agents.defaults.systemPrompt`

Controls the system prompt shape for all agents. Per-agent overrides go in `agents.list[].systemPrompt` and merge over this baseline by section key. See [System Prompt](https://docs.wednesdayai.dev/next/developers/concepts/system-prompt) for full behavior details.

```json5 theme={"dark"}
{
  agents: {
    defaults: {
      systemPrompt: {
        preset: "lean", // default | lean | minimal
        cache: {
          boundary: "auto", // auto | off
        },
        sections: {
          // Regular section — prepend/append/replace built-in content
          safety: {
            mode: "append", // default | off | prepend | append | replace
            content: [
              { text: "Prefer reversible actions during experiments." },
              { file: "prompt/safety.md", optional: true, maxChars: 4000 },
            ],
          },
          // Generated section — controls rendering density
          tooling: {
            mode: "compact", // default | compact | names | off
            progressive: false,
          },
          // Project Context — controls file injection list
          projectContext: {
            mode: "default", // default | lean | off
            content: [{ text: "Internal tooling docs are at ~/wiki." }],
            files: [
              { path: "AGENTS.md", mode: "inline" },
              { path: "SOUL.md", mode: "inline" },
              { path: "USER.md", mode: "manifest" },
              { path: "HEARTBEAT.md", mode: "runKind" },
            ],
          },
          // Runtime section
          runtime: {
            mode: "minimal", // default | minimal | off
          },
        },
      },
    },
  },
}
```

**`preset`** choices:

| Preset | Effect |
| - | - |
| `default` | Full legacy prompt shape. |
| `lean` | Compact tool/skill listings, reduced documentation, manifest-mode for large context files. |
| `minimal` | Essentials only: identity, tooling (names), safety, workspace, sandbox, time, runtime. |

**`cache.boundary`**: `auto` (default) places the cache boundary between stable and volatile sections for provider prompt caching. `off` renders one continuous prompt.

**Section types and modes:**

| Section key | Type | Modes |
| - | - | - |
| `identity` | Regular | `default` / `off` / `prepend` / `append` / `replace` |
| `tooling` | Generated | `default` / `compact` / `names` / `off` + `progressive?` |
| `team` | Regular | `default` / `off` / `prepend` / `append` / `replace` |
| `toolCallStyle` | Regular | `default` / `off` / `prepend` / `append` / `replace` |
| `safety` | Regular | `default` / `off` / `prepend` / `append` / `replace` |
| `cliQuickReference` | Regular | `default` / `off` / `prepend` / `append` / `replace` |
| `skills` | Generated | `default` / `compact` / `names` / `off` + `progressive?` |
| `memory` | Regular | `default` / `off` / `prepend` / `append` / `replace` |
| `selfUpdate` | Regular | `default` / `off` / `prepend` / `append` / `replace` |
| `modelAliases` | Generated | `default` / `compact` / `names` / `off` + `progressive?` |
| `workspace` | Regular | `default` / `off` / `prepend` / `append` / `replace` |
| `documentation` | Regular | `default` / `off` / `prepend` / `append` / `replace` |
| `sandbox` | Regular | `default` / `off` / `prepend` / `append` / `replace` |
| `authorizedSenders` | Regular | `default` / `off` / `prepend` / `append` / `replace` |
| `time` | Regular | `default` / `off` / `prepend` / `append` / `replace` |
| `workspaceFilesNotice` | Regular | `default` / `off` / `prepend` / `append` / `replace` |
| `replyTags` | Regular | `default` / `off` / `prepend` / `append` / `replace` |
| `messaging` | Regular | `default` / `off` / `prepend` / `append` / `replace` |
| `voice` | Regular | `default` / `off` / `prepend` / `append` / `replace` |
| `groupContext` | Regular | `default` / `off` / `prepend` / `append` / `replace` |
| `reactions` | Regular | `default` / `off` / `prepend` / `append` / `replace` |
| `silentReplies` | Regular | `default` / `off` / `prepend` / `append` / `replace` |
| `heartbeats` | Regular | `default` / `off` / `prepend` / `append` / `replace` |
| `reasoningFormat` | Regular | `default` / `off` / `prepend` / `append` / `replace` |
| `projectContext` | Project Context | `default` / `lean` / `off` + `content[]` + `files[]` |
| `runtime` | Runtime | `default` / `minimal` / `off` |

**`sections.<key>.content`** — inline or file-backed text added to the section. Each entry is one of:

* `{ text: "..." }` — inline text.
* `{ file: "path/to/file.md", optional?: true, maxChars?: 4000 }` — file content, resolved relative to the agent workspace (absolute and `~`-prefixed paths also accepted).

**`sections.projectContext.files`** — ordered list that replaces the default bootstrap file list. Each entry:

* `path` — workspace-relative, absolute, or `~`-prefixed path.
* `mode` — `inline` (inject content), `manifest` (inject pointer), `off` (skip), or `runKind` (include only on matching run kinds such as heartbeat).
* `optional` — omit missing files instead of injecting a missing-file marker.
* `maxChars` — per-file character cap.

### `agents.defaults.imageMaxDimensionPx`

Max pixel size for the longest image side in transcript/tool image blocks before provider calls.
Default: `1200`.

Lower values usually reduce vision-token usage and request payload size for screenshot-heavy runs.
Higher values preserve more visual detail.

```json5 theme={"dark"}
{
  agents: { defaults: { imageMaxDimensionPx: 1200 } },
}
```

### `agents.defaults.envelopeTimestamp`

Timestamp handling for messages. Default: `"on"`.

When `"off"`, absolute timestamps are removed from inbound envelope headers, user turns are not
stamped at the model boundary, and the timestamp prevention line is dropped from the system
prompt.

```json5 theme={"dark"}
{
  agents: { defaults: { envelopeTimestamp: "on" } }, // "on" | "off"
}
```

### `agents.defaults.runtimeEvents` / `agents.defaults.untrustedContext`

Control whether core renders two blocks around the current user turn (#2107):

* `runtimeEvents` — the runtime-events block (gateway-generated events drained for the turn).
* `untrustedContext` — the untrusted-context trailer (session metadata such as channel context
  and link previews; data, never instructions).

Each takes `{ render: "core" | "off" }`. Default: `"core"` — core renders the block, and
`"core"` output is unchanged except the header wording. `"off"` means core omits the block.
A `message-render` context owner receives the underlying data via `context.project`
`turnInputs` regardless and renders it itself. `runtimeEvents.render: "off"` also drops
agent/plugin-authored untrusted nudges, and drained events are consumed, not re-queued.

Both can be overridden per `agents.list[]` entry.

```json5 theme={"dark"}
{
  agents: {
    defaults: {
      runtimeEvents: { render: "core" }, // "core" (default) | "off"
      untrustedContext: { render: "core" }, // "core" (default) | "off"
    },
  },
}
```

### `agents.defaults.userTimezone`

Timezone for system prompt context and for the `[Ddd YYYY-MM-DD HH:MM GMT±H]` stamp rendered on
every user turn. Falls back to the host timezone.

```json5 theme={"dark"}
{
  agents: { defaults: { userTimezone: "America/Chicago" } },
}
```

### `agents.defaults.timeFormat`

Time format in system prompt. Default: `auto` (OS preference).

```json5 theme={"dark"}
{
  agents: { defaults: { timeFormat: "auto" } }, // auto | 12 | 24
}
```

### `agents.defaults.model`

```json5 theme={"dark"}
{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "minimax/MiniMax-M2.5": { alias: "minimax" },
      },
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["minimax/MiniMax-M2.5"],
      },
      imageModel: {
        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
        fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],
      },
      pdfModel: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5-mini"],
      },
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      contextTokens: 200000,
      maxConcurrent: 3,
      nested: {
        maxConcurrent: 2,
      },
      subagents: {
        maxConcurrent: 6,
      },
    },
  },
}
```

* `model`: accepts either a string (`"provider/model"`) or an object (`{ primary, fallbacks }`).
  * String form sets only the primary model.
  * Object form sets primary plus ordered failover models.
* `imageModel`: accepts either a string (`"provider/model"`) or an object (`{ primary, fallbacks }`).
  * Used by the `image` tool path as its vision-model config.
  * Routes media understanding when the turn's model is known text-only; when the active model is
    vision-capable or unknown to the catalog, the active model is tried first and this pin stays a
    later fallback. Full order: [Media Understanding](https://docs.wednesdayai.dev/next/users/nodes/media-understanding.md#describing-media-when-the-primary-model-is-text-only).
* `pdfModel`: accepts either a string (`"provider/model"`) or an object (`{ primary, fallbacks }`).
  * Used by the `pdf` tool for model routing.
  * If omitted, the PDF tool falls back to `imageModel`, then to best-effort provider defaults.
* `pdfMaxBytesMb`: default PDF size limit for the `pdf` tool when `maxBytesMb` is not passed at call time.
* `pdfMaxPages`: default maximum pages considered by extraction fallback mode in the `pdf` tool.
* `model.primary`: format `provider/model` (e.g. `anthropic/claude-opus-4-6`). If you omit the provider, WednesdayAI assumes `anthropic` (deprecated).
* `models`: the configured model catalog and allowlist for `/model`. Each entry can include `alias` (shortcut) and `params` (provider-specific, for example `temperature`, `maxTokens`, `cacheRetention`, `context1m`).
* `params` merge precedence (config): `agents.defaults.models["provider/model"].params` is the base, then `agents.list[].params` (matching agent id) overrides by key.
* Config writers that mutate these fields (for example `/models set`, `/models set-image`, and fallback add/remove commands) save canonical object form and preserve existing fallback lists when possible.
* `maxConcurrent`: max parallel main-lane agent runs across sessions (each session still serialized). Default: 4.
* `nested.maxConcurrent`: max parallel nested coordination runs for agent-to-agent and nested subagent orchestration. Default: 2.
* `subagents.maxConcurrent`: max parallel spawned sub-agent runs on the subagent lane. Default: 8.
* `subagents.maxSpawnDepth`: max nesting depth for `sessions_spawn` chains (default: 1, range 1–5). Depth 2 enables the orchestrator pattern (main → orchestrator → workers).
* `subagents.maxChildrenPerAgent`: max active children per requester session (default: 5, range 1–20).
* `subagents.archiveAfterMinutes`: auto-archive finished sub-agent sessions after N minutes (default: 60).
* `subagents.model`: default model selection for spawned sub-agents (string or `{ primary, fallbacks }`). Overridden per-agent by `agents.list[].subagents.model`.
* `subagents.thinking`: default thinking level for spawned sub-agents (e.g. `"off"`, `"low"`, `"medium"`, `"high"`). Overridden per-agent by `agents.list[].subagents.thinking`.
* `subagents.runTimeoutSeconds`: default run timeout for spawned sub-agents in seconds (0 = no timeout). Does not auto-archive; only stops the run.
* `subagents.announceTimeoutMs`: gateway timeout for sub-agent announce delivery calls (default: 60000).
* `subagents.completionDelivery`: default delivery mode for top-level sub-agent completions: `"parent"` (default; the completion is passed to the parent as an internal event and the parent authors the user-facing reply on a durable agent turn) or `"direct"` (legacy verbatim send to the requester channel, suppressed while sibling runs are pending). Cron routes, and bound-session or hook routes on session-mode spawns, always deliver directly, regardless of this setting. Overridden per-agent by `agents.list[].subagents.completionDelivery` and per-spawn by the `sessions_spawn` `completionDelivery` parameter. See [Completion delivery](https://docs.wednesdayai.dev/next/users/tools/subagents.md#completion-delivery).
* `subagents.announceFanInCoalesce`: deprecated, no effect. Accepted for backward compatibility; sibling completion fan-in is always coalesced into one parent turn on the durable agent-turn announce path.

**Built-in alias shorthands** (only apply when the model is in `agents.defaults.models`):

| Alias | Model |
| - | - |
| `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` |

Your configured aliases always win over defaults.

Z.AI GLM-4.x models automatically enable thinking mode unless you set `--thinking off` or define `agents.defaults.models["zai/<model>"].params.thinking` yourself.
Z.AI models enable `tool_stream` by default for tool call streaming. Set `agents.defaults.models["zai/<model>"].params.tool_stream` to `false` to disable it.
Anthropic Claude 4.6 models default to `adaptive` thinking when no explicit thinking level is set.

### `agents.defaults.cliBackends`

Optional CLI backends for text-only fallback runs (no tool calls). Useful as a backup when API providers fail.

```json5 theme={"dark"}
{
  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",
        },
      },
    },
  },
}
```

* CLI backends are text-first; tools are always disabled.
* Sessions supported when `sessionArg` is set.
* Image pass-through supported when `imageArg` accepts file paths.

### `agents.defaults.heartbeat`

Periodic heartbeat runs.

```json5 theme={"dark"}
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 0m disables
        model: "openai/gpt-5.2-mini",
        includeReasoning: false,
        session: "main",
        to: "+15555550123",
        directPolicy: "allow", // allow (default) | block
        target: "none", // default: none | options: last | webchat | whatsapp | telegram | discord | ...
        prompt: "Read HEARTBEAT.md if it exists...",
        ackMaxChars: 300,
        suppressToolErrorWarnings: false,
        skipWhenBusy: false,
        isolatedSession: false,
        // wakeGate: { kind: "command", command: "..." } — see Heartbeat
        // activeHours: { start: "08:00", end: "22:00", timezone: "..." }
        lightContext: false,
      },
    },
  },
}
```

* `every`: duration string (ms/s/m/h). Default: `30m`. A blank or non-positive value (e.g. `0m`) disables the heartbeat instead of falling back to the default.
* `skipWhenBusy`: when true, heartbeat ticks that find the main lane busy are skipped instead of enqueued.
* `isolatedSession`: when true, each heartbeat enqueues an `agent.turn` (`kind` heartbeat) that runs in a fresh `:heartbeat` sibling session with no prior transcript; a positive `wakeGate` also nudges the main session (`kind` nudge). See [Heartbeat](https://docs.wednesdayai.dev/next/admin/gateway/heartbeat.md).
* `wakeGate`: optional command/model gate checked before the heartbeat turn; on a positive gate the isolated heartbeat turn is enqueued and the main session is additionally nudged (`kind` nudge). Default `timeoutMs` is 30000. Gates the heartbeat producer only.
* `activeHours`: optional window (`start`/`end`/`timezone`) — heartbeat ticks outside the window are skipped.
* `lightContext`: when true, runs the heartbeat turn with a reduced context payload (isolated `:heartbeat` sessions only — shared-session heartbeats keep the session's full bootstrap) and swaps the default heartbeat prompt for the light variant; a configured `prompt` always wins.
* `toolsAllow`: exact tool names an isolated heartbeat may use (`[]` = no tools; matching is case- and alias-insensitive; when set the skills list is also omitted and skill-declared environment overrides are not applied; only with `isolatedSession: true` — ignored with a warn on a shared-session heartbeat; can only narrow the tool surface, policy `tools.allow` still applies; an entry matching no tool logs a `toolsAllow names matched no tool` warn; unset keeps the full tool surface).
* `suppressToolErrorWarnings`: when true, suppresses tool error warning payloads during heartbeat runs.
* `directPolicy`: direct/DM delivery policy. `allow` (default) permits direct-target delivery. `block` suppresses direct-target delivery and emits `reason=dm-blocked`.
* `to`: optional recipient override (channel-specific id, e.g. E.164 for WhatsApp or a Telegram chat id; Telegram topics use `<chatId>:topic:<threadId>`).
* `accountId`: optional account id for multi-account channels; see [Heartbeat](https://docs.wednesdayai.dev/next/admin/gateway/heartbeat.md) for `target` interactions.
* `identity`: optional `session.identityLinks` key (matched case-insensitively). On match, heartbeat runs carry that canonical identity as the requester identity (`identitySource: "job-config"`); unmatched values leave runs unattributed. Honoured per-agent via `agents.list[].heartbeat.identity`.
* Per-agent: set `agents.list[].heartbeat`. When any agent defines `heartbeat`, **only those agents** run heartbeats; the block merges key-by-key over `agents.defaults.heartbeat`, so a partial block inherits the rest.
* Heartbeats run full agent turns — shorter intervals burn more tokens.

### `agents.defaults.compaction`

```json5 theme={"dark"}
{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
        reserveTokensFloor: 24000,
        summaryTimeoutMs: 300000, // per summarization call; raise for slow local models
        identifierPolicy: "strict", // strict | off | custom
        identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom
        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.",
        },
      },
    },
  },
}
```

* `mode`: `default` or `safeguard` (chunked summarization for long histories). See [Compaction](https://docs.wednesdayai.dev/next/developers/concepts/compaction.md).
* `identifierPolicy`: `strict` (default), `off`, or `custom`. `strict` prepends built-in opaque identifier retention guidance during compaction summarization.
* `identifierInstructions`: optional custom identifier-preservation text used when `identifierPolicy=custom`.
* `memoryFlush`: silent agentic turn before auto-compaction to store durable memories. Skipped when workspace is read-only.

### `agents.defaults.contextPruning`

Prunes **old tool results** from in-memory context before sending to the LLM. Does **not** modify session history on disk.

```json5 theme={"dark"}
{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl", // off | cache-ttl
        ttl: "1h", // duration (ms/s/m/h), default unit: minutes
        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"] },
      },
    },
  },
}
```

> [accordion] cache-ttl mode behavior
>
> * `mode: "cache-ttl"` enables pruning passes.
> * `ttl` controls when the next pruning round becomes due (after the last cache touch).
> * Pruning soft-trims oversized tool results first, then hard-clears older tool results if needed.
> * Pruning rounds are **sticky per session**: each round's decisions are recorded in a per-session
>   prompt ledger and stay applied. The trimmed view does not revert between calls, and a gateway
>   restart replays the same trimmed view from the recorded ledger.
>
> **Soft-trim** keeps beginning + end and inserts `...` in the middle.
>
> **Hard-clear** replaces the entire tool result with the placeholder.
>
> Notes:
>
> * Tool results containing image blocks are skipped by pruning (never trimmed/cleared).
> * Ratios are character-based (approximate), not exact token counts.
> * If fewer than `keepLastAssistants` assistant messages exist, pruning is skipped.
> * Separately from pruning, any single tool result is capped at `400,000` text chars in memory at
>   the tool seam and on DB hydration; the cap truncates text and keeps images. When a result is
>   trimmed to fit the context window, its images keep at most half the trimmed budget (over-budget
>   images are replaced by an `[N image(s) omitted from context]` note). The raw bytes
>   are stored out-of-band when DB write-through is on. This cap applies regardless of
>   `contextPruning`.

See [Session Pruning](https://docs.wednesdayai.dev/next/developers/concepts/session-pruning.md) for behavior details.

### Block streaming

```json5 theme={"dark"}
{
  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 (use minMs/maxMs)
    },
  },
}
```

* Non-Telegram channels require explicit `*.blockStreaming: true` to enable block replies.
* Channel overrides: `channels.<channel>.blockStreamingCoalesce` (and per-account variants). Signal/Slack/Discord/Google Chat default `minChars: 1500`.
* `humanDelay`: randomized pause between block replies. `natural` = 800–2500ms. Per-agent override: `agents.list[].humanDelay`.

See [Streaming](https://docs.wednesdayai.dev/next/developers/concepts/streaming.md) for behavior + chunking details.

### Typing indicators

```json5 theme={"dark"}
{
  agents: {
    defaults: {
      typingMode: "instant", // never | instant | thinking | message
      typingIntervalSeconds: 6,
    },
  },
}
```

* Defaults: `instant` for direct chats/mentions, `message` for unmentioned group chats.
* Per-session overrides: `session.typingMode`, `session.typingIntervalSeconds`.

See [Typing Indicators](https://docs.wednesdayai.dev/next/developers/concepts/typing-indicators.md).

### `agents.defaults.sandbox`

Optional **Docker sandboxing** for the embedded agent. See [Sandboxing](https://docs.wednesdayai.dev/next/admin/gateway/sandboxing.md) for the full guide.

```json5 theme={"dark"}
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        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"],
        },
        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",
          "delete",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status",
        ],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
      },
    },
  },
}
```

> [accordion] Sandbox details
>
> **Workspace access:**
>
> * `none`: per-scope sandbox workspace under `~/.openclaw/sandboxes`
> * `ro`: sandbox workspace at `/workspace`, agent workspace mounted read-only at `/agent`
> * `rw`: agent workspace mounted read/write at `/workspace`
>
> **Scope:**
>
> * `session`: per-session container + workspace
> * `agent`: one container + workspace per agent (default)
> * `shared`: shared container and workspace (no cross-session isolation)
>
> **`setupCommand`** runs once after container creation (via `sh -lc`). Needs network egress, writable root, root user.
>
> **Containers default to `network: "none"`** — set to `"bridge"` (or a custom bridge network) if the agent needs outbound access.
> `"host"` is blocked. `"container:<id>"` is blocked by default unless you explicitly set
> `sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (break-glass).
>
> **Inbound attachments** are staged into `media/inbound/*` in the active workspace.
>
> **`docker.binds`** mounts additional host directories; global and per-agent binds are merged.
>
> **Sandboxed browser** (`sandbox.browser.enabled`): Chromium + CDP in a container. noVNC URL injected into system prompt. Does not require `browser.enabled` in `openclaw.json`.
> noVNC observer access uses VNC auth by default and WednesdayAI emits a short-lived token URL (instead of exposing the password in the shared URL).
>
> * `allowHostControl: false` (default) blocks sandboxed sessions from targeting the host browser.
> * `network` defaults to `openclaw-sandbox-browser` (dedicated bridge network). Set to `bridge` only when you explicitly want global bridge connectivity.
> * `cdpSourceRange` optionally restricts CDP ingress at the container edge to a CIDR range (for example `172.21.0.1/32`).
> * `sandbox.browser.binds` mounts additional host directories into the sandbox browser container only. When set (including `[]`), it replaces `docker.binds` for the browser container.
> * `autoStart` (default: true) — when true, sandboxed browser control will try to start/reattach to the sandbox browser container when a tool call needs it.
> * `autoStartTimeoutMs` — max time to wait for CDP to become reachable after auto-start (ms).
> * Launch defaults are defined in `scripts/sandbox-browser-entrypoint.sh` and tuned for container hosts:
>   * `--remote-debugging-address=127.0.0.1`
>   * `--remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>`
>   * `--user-data-dir=${HOME}/.chrome`
>   * `--no-first-run`
>   * `--no-default-browser-check`
>   * `--disable-3d-apis`
>   * `--disable-gpu`
>   * `--disable-software-rasterizer`
>   * `--disable-dev-shm-usage`
>   * `--disable-background-networking`
>   * `--disable-features=TranslateUI`
>   * `--disable-breakpad`
>   * `--disable-crash-reporter`
>   * `--renderer-process-limit=2`
>   * `--no-zygote`
>   * `--metrics-recording-only`
>   * `--disable-extensions` (default enabled)
>   * `--disable-3d-apis`, `--disable-software-rasterizer`, and `--disable-gpu` are
>     enabled by default and can be disabled with
>     `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` if WebGL/3D usage requires it.
>   * `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` re-enables extensions if your workflow
>     depends on them.
>   * `--renderer-process-limit=2` can be changed with
>     `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>`; set `0` to use Chromium's
>     default process limit.
>   * plus `--no-sandbox` and `--disable-setuid-sandbox` when `noSandbox` is enabled.
>   * Defaults are the container image baseline; use a custom browser image with a custom
>     entrypoint to change container defaults.

Build images:

```bash theme={"dark"}
scripts/sandbox-setup.sh           # main sandbox image
scripts/sandbox-browser-setup.sh   # optional browser image
```

### `agents.list` (per-agent overrides)

```json5 theme={"dark"}
{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        name: "Main Agent",
        workspace: "~/.openclaw/workspace",
        agentDir: "~/.openclaw/agents/main/agent",
        workspaceLanes: {
          enabled: true,
          strategy: "hybrid",
          laneKey: "canonical-identity",
          rootTemplate: "~/.openclaw/agents/{agentId}/lanes/{laneId}/workspace",
          sharedFiles: ["AGENTS.md", "SOUL.md", "IDENTITY.md", "TOOLS.md", "HEARTBEAT.md"],
          copiedOnCreate: ["USER.md", "BOOTSTRAP.md"],
          laneFiles: ["USER.md", "BOOTSTRAP.md", "MEMORY.md", "memory.md"],
          skills: "shared",
          create: "on-first-message",
        },
        model: "anthropic/claude-opus-4-6", // or { primary, fallbacks }
        runtimeEvents: { render: "off" }, // overrides agents.defaults.runtimeEvents
        params: { cacheRetention: "none" }, // overrides matching defaults.models params by key
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
          emoji: "🦥",
          avatar: "avatars/samantha.png",
          color: "lime", // optional; web client assistant colour, see agents.list[].identity.color
        },
        groupChat: { mentionPatterns: ["@openclaw"] },
        sandbox: { mode: "off" },
        subagents: { allowAgents: ["*"] },
        tools: {
          profile: "coding",
          allow: ["browser"],
          deny: ["canvas"],
          elevated: { enabled: true },
        },
        systemPrompt: {
          preset: "lean",
          cache: { boundary: "auto" },
          sections: {
            safety: {
              mode: "append",
              content: [{ text: "Scope all writes to the project directory." }],
            },
            projectContext: {
              files: [
                { path: "AGENTS.md", mode: "inline" },
                { path: "SOUL.md", mode: "inline" },
                { path: "USER.md", mode: "manifest" },
              ],
            },
          },
        },
      },
    ],
  },
}
```

* `id`: stable agent id (required). Ids are compared after normalization (lowercased, invalid characters collapsed to `-`); two entries that normalize to the same id fail config validation.
* `default`: when multiple are set, first wins (warning logged). If none set, first list entry is default.
* `description`: one-line summary of what the agent is for (max 500 characters). Team leads see it in their `## Team` prompt section, `agents_list` returns it, and the Control UI shows it.
* `userFacing`: whether people can reach the agent directly (default `true`). Set `false` for internal specialists. Config validation rejects an internal agent as the default agent, a `bindings[]` target, or a `broadcast` target, and rejects any internal agent when `session.scope` is `"global"` (all agents share one session there). User clients (web client) do not see it or its sessions and runs in `agents.list`, `sessions.direct`, `sessions.list`, or `sessions.runs.list`, do not receive events for its sessions, get it omitted from `health` and `status` agent summaries, and any user-client request that names it, one of its sessions, or one of its runs (`chat.send`, `chat.history`, `sessions.create`, `sessions.steer`, `sessions.runs.get`, `sessions.resolve`, ...) fails with the same error as an unknown agent. `sessions_spawn` with `thread: true`, `/subagents spawn`, `/tell`, `/steer`, `/focus`, and `/acp` cannot target it, `/acp sessions` hides it, and an existing channel thread binding to one of its sessions stops routing once the flag is set. Other agents, cron, hooks, and operator clients keep full access.
* `inheritRequesterIdentity`: when another agent invokes this agent (`sessions_spawn`, `sessions_send`), accept the requesting person's canonical identity, validated against `session.identityLinks`, so identity-scoped workspace lanes, memory, and plugins resolve for that person (default `true`). Set `false` to run delegated turns on this agent without a person identity. This also applies to sub-agent completion announces delivered to this agent, so do not turn it off on a lead that relies on identity-scoped workspace lanes.
* `workspaceLanes`: optional per-agent workspace lanes for personas that may serve multiple users. See [Workspace Lanes](https://docs.wednesdayai.dev/next/developers/concepts/workspace-lanes.md).
* `model`: string form overrides `primary` only; object form `{ primary, fallbacks }` overrides both (`[]` disables global fallbacks). Cron jobs that only override `primary` still inherit default fallbacks unless you set `fallbacks: []`.
* `params`: per-agent stream params merged over the selected model entry in `agents.defaults.models`. Use this for agent-specific overrides like `cacheRetention`, `temperature`, or `maxTokens` without duplicating the whole model catalog.
* `identity.avatar`: workspace-relative path, `http(s)` URL, or `data:` URI.
* `identity.color`: optional web client assistant colour. See
  [`agents.list[].identity.color`](#agentslistidentitycolor) below.
* `identity` derives defaults: `ackReaction` from `emoji`, `mentionPatterns` from `name`/`emoji`.
* `subagents.allowAgents`: per-agent allowlist of agent ids for `sessions_spawn`'s `agentId` parameter (`["*"]` = any; default: same agent only). Allowlist-only — no deny-list for target agent IDs. See [Sub-agent access control](https://docs.wednesdayai.dev/next/users/tools/subagents.md#sub-agent-access-control-which-agents-which-tools).
* `subagents.model`: per-agent default model for spawned sub-agents (overrides `agents.defaults.subagents.model`).
* `subagents.thinking`: per-agent default thinking level for spawned sub-agents (overrides `agents.defaults.subagents.thinking`).
* `subagents.completionDelivery`: per-agent delivery mode for top-level sub-agent completions (`"parent"` or `"direct"`; overrides `agents.defaults.subagents.completionDelivery`). See [Completion delivery](https://docs.wednesdayai.dev/next/users/tools/subagents.md#completion-delivery).
* `tts`: per-agent override of `messages.tts` (voice, provider, model, `readAloud`, ...), deep-merged over the global config. Applies to read aloud, auto voice replies, `/tts` and the `tts` tool for this agent. A provider pinned with `/tts provider` still wins. See [Per-agent TTS](https://docs.wednesdayai.dev/next/users/tts.md#per-agent-tts-agentslisttts).
* `systemPrompt`: per-agent prompt shape override. Merges over `agents.defaults.systemPrompt` by section key. When `projectContext.files` is set, that list replaces the default entirely (not merged). See [`agents.defaults.systemPrompt`](#agentsdefaultssystemprompt) for the full field reference.
* Sandbox inheritance guard: if the requester session is sandboxed, `sessions_spawn` rejects targets that would run unsandboxed.

### `agents.list[].identity.color`

```json5 theme={"dark"}
{
  agents: {
    list: [{ id: "main", identity: { color: "lime" } }],
    defaults: { models: { "anthropic/claude-opus-4-6": {} } }, // bounds the web client's model switcher, see below
  },
}
```

* One of a closed palette: `indigo`, `violet`, `pink`, `rose`, `amber`, `lime`, `teal`, `sky`. Any
  other value fails config validation with the allowed values listed in the error. Optional; an
  assistant with no configured colour still gets a stable colour in the web client, hashed from its
  agent id (`packages/brand-tokens` guarantees 3:1 contrast against the background and 4.5:1 on the
  foreground for every colour in dark, light and high-contrast themes).
* Set it here only: `IDENTITY.md` does not carry a colour.
* Also carried on `agents.list` (the gateway RPC method) as `identity.color`, so a colour set here
  is what the [web client](https://docs.wednesdayai.dev/next/admin/web/user-client.md) shows for this assistant - the assistant picker, the
  sidebar, the top bar and each of its replies.
* **If you expose the web client**, also set `agents.defaults.models` to a real, bounded catalog.
  The model menu (`models.list`) lists the catalog entries named there, and `sessions.patch` and
  `sessions.create`'s optional `model` field (client-chat-v3 P2, ADR 0083/0084) accept those plus
  the agent's own default model. `agents.list[].model` fallbacks do not widen or narrow either.
  Leaving `agents.defaults.models` empty lists the whole model catalog and admits any
  `provider/model` reference that parses, not just the ones you intend end users to pick from.

### `agents.list[].workspaceLanes`

Opt-in per-agent workspace lanes. Leave unset or set `enabled: false` for the existing
single-workspace behavior.

```json5 theme={"dark"}
{
  agents: {
    list: [
      {
        id: "support",
        workspaceLanes: {
          enabled: true,
          strategy: "hybrid",
          laneKey: "canonical-identity",
          rootTemplate: "~/.openclaw/agents/{agentId}/lanes/{laneId}/workspace",
          create: "on-first-message",
        },
      },
    ],
  },
}
```

| Key | Values | Notes |
| - | - | - |
| `enabled` | boolean | Turns lanes on for this agent only. |
| `strategy` | `hybrid`, `copy-template`, `overlay`, `extension` | The schema accepts all four. Runtime support in this slice is `hybrid`; other values are denied until implemented. |
| `laneKey` | `canonical-identity`, `account-channel-peer`, `channel-peer` | Selects the actor identity used to compute the deterministic lane id. |
| `rootTemplate` | string | May use `{agentId}` and required `{laneId}`. Traversal, unsupported placeholders, malformed braces, templates without `{laneId}`, and existing non-directory lane paths are denied. |
| `sharedFiles` | string array | Persona-level files read from the shared agent workspace. |
| `copiedOnCreate` | string array | Files copied from the persona workspace into a newly created lane. Existing lane files are not overwritten, and files removed from an existing lane are not restored. |
| `laneFiles` | string array | Files or directories treated as lane-local user state. |
| `skills` | `shared`, `lane`, `both` | `shared` loads skills from the persona workspace. `lane` loads them from the lane workspace. `both` is reserved and currently behaves like `shared`. |
| `create` | `on-first-message`, `manual` | `on-first-message` creates the lane directory when a lane is first resolved. `manual` requires a pre-provisioned directory and skips missing or non-directory lane replies. |

Defaults for enabled agents:

* `strategy: "hybrid"`
* `laneKey: "canonical-identity"`
* `rootTemplate: "~/.openclaw/agents/{agentId}/lanes/{laneId}/workspace"`
* `sharedFiles: ["AGENTS.md", "SOUL.md", "IDENTITY.md", "TOOLS.md", "HEARTBEAT.md"]`
* `copiedOnCreate: ["USER.md", "BOOTSTRAP.md"]`
* `laneFiles: ["USER.md", "BOOTSTRAP.md", "MEMORY.md", "memory.md"]`
* `skills: "shared"` (`"lane"` is implemented for lane-local skill roots; `"both"` is reserved and currently behaves like `"shared"`)
* `create: "on-first-message"`

### `agents.teams`

Named groups of agents with one lead. Set `userFacing: false` on members that people should only
reach through the lead.

```json5 theme={"dark"}
{
  agents: {
    list: [
      { id: "main", default: true },
      { id: "researcher", userFacing: false, description: "Finds and summarises sources." },
      { id: "writer", userFacing: false, description: "Drafts long-form text." },
    ],
    teams: [{ id: "research", name: "Research", lead: "main", members: ["researcher", "writer"] }],
  },
}
```

* `id`: stable, unique team id: 1–64 characters, starting with a lowercase letter or digit, then lowercase letters, digits, `-` or `_`.
* `name`: optional display name for the Control UI and the lead's prompt.
* `lead`: agent id of the team lead; must be in `agents.list`.
* `members`: agent ids of the members (at least one); must be in `agents.list` and must not include the lead.
* Each agent belongs to at most one team, as lead or member; teams do not nest. Config validation rejects unknown ids and repeated agents.
* The lead can `sessions_spawn` every member in addition to its own `subagents.allowAgents`, and `agents_list` includes them. Members get no new rights.
* When the lead has the `sessions_spawn` tool, its system prompt gets a `## Team` section listing each member's id, name, and description. Control it with the `team` key in [`systemPrompt.sections`](#agentsdefaultssystemprompt).
* Teams do not change `tools.agentToAgent` (`sessions_send`) or ACP targets.

***

## Multi-agent routing

Run multiple isolated agents inside one Gateway. See [Multi-Agent](https://docs.wednesdayai.dev/next/developers/concepts/multi-agent.md).

```json5 theme={"dark"}
{
  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" } },
  ],
}
```

### Binding match fields

* `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)

**Deterministic match order:**

1. `match.peer`
2. `match.guildId`
3. `match.teamId`
4. `match.accountId` (exact, no peer/guild/team)
5. `match.accountId: "*"` (channel-wide)
6. Default agent

Within each tier, the first matching `bindings` entry wins.

### Per-agent access profiles

> [accordion] Full access (no sandbox)
>
> ```json5 theme={"dark"}
> {
>   agents: {
>     list: [
>       {
>         id: "personal",
>         workspace: "~/.openclaw/workspace-personal",
>         sandbox: { mode: "off" },
>       },
>     ],
>   },
> }
> ```

> [accordion] Read-only tools + workspace
>
> ```json5 theme={"dark"}
> {
>   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", "delete", "apply_patch", "exec", "process", "browser"],
>         },
>       },
>     ],
>   },
> }
> ```

> [accordion] No filesystem access (messaging only)
>
> ```json5 theme={"dark"}
> {
>   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",
>             "delete",
>             "apply_patch",
>             "exec",
>             "process",
>             "browser",
>             "canvas",
>             "nodes",
>             "cron",
>             "gateway",
>             "image",
>           ],
>         },
>       },
>     ],
>   },
> }
> ```

See [Multi-Agent Sandbox & Tools](https://docs.wednesdayai.dev/next/users/tools/multi-agent-sandbox-tools) for precedence details.

***

## Session

```json5 theme={"dark"}
{
  session: {
    scope: "per-sender",
    dmScope: "main", // main | per-peer | per-channel-peer | per-account-channel-peer
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678", "device:6abfaeda…"],
    },
    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, // skip parent-thread fork above this token count (0 disables)
    maintenance: {
      mode: "warn", // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
    },
    threadBindings: {
      enabled: true,
      idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables)
      maxAgeHours: 0, // default hard max age in hours (`0` disables)
    },
    mainKey: "main", // legacy (runtime always uses "main")
    agentToAgent: { maxPingPongTurns: 5 },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}
```

> [accordion] Session field details
>
> * **`dmScope`**: how DMs are grouped.
>   * `main`: all DMs share the main session.
>   * `per-peer`: isolate by sender id across channels.
>   * `per-channel-peer`: isolate per channel + sender (recommended for multi-user inboxes).
>   * `per-account-channel-peer`: isolate per account + channel + sender (recommended for multi-account).
> * **`identityLinks`**: map canonical ids to provider-prefixed peers for cross-channel session sharing. The keys are also the value space for cron-job and heartbeat `identity` attribution (matched case-insensitively; the run carries the stored key casing as its canonical identity). Keys starting with `raw~` are rejected at config validation — that prefix is reserved for contained unlinked-sender session buckets (see [Sessions](https://docs.wednesdayai.dev/next/developers/concepts/session.md)). Gateway clients (web client, Control UI) send their turns as `device:<deviceId>`; link each device to a person with `wednesdayai devices link <deviceId> --identity <key>`, or pair it already linked with `wednesdayai identity link <key> --qr` (see [Identities](https://docs.wednesdayai.dev/next/admin/gateway/identity)). Get ids from `wednesdayai devices list --json` (`deviceId` on each `paired` entry). Agents with [workspace lanes](https://docs.wednesdayai.dev/next/developers/concepts/workspace-lanes.md) deny unlinked devices.
> * **`reset`**: primary reset policy. `daily` resets at `atHour` local time; `idle` resets after `idleMinutes`. When both configured, whichever expires first wins.
> * **`resetByType`**: per-type overrides (`direct`, `group`, `thread`). Legacy `dm` accepted as alias for `direct`.
> * **`parentForkMaxTokens`**: max parent-session `totalTokens` allowed when creating a forked thread session (default `100000`).
>   * If parent `totalTokens` is above this value, WednesdayAI starts a fresh thread session instead of inheriting parent transcript history.
>   * Set `0` to disable this guard and always allow parent forking.
> * **`mainKey`**: legacy field. Runtime now always uses `"main"` for the main direct-chat bucket.
> * **`sendPolicy`**: match by `channel`, `chatType` (`direct|group|channel`, with legacy `dm` alias), `keyPrefix`, or `rawKeyPrefix`. First deny wins. `channel` and `chatType` compare against the session's stored identity (the channel and peer kind recorded when the conversation arrived, or the session's recorded channel), never the session key text; `keyPrefix` and `rawKeyPrefix` match the key itself. A `channel` named in an `agent` request is never policy input: it cannot satisfy an allow rule the stored session does not match. The Gateway decides the policy on the session row it holds the store lock for, so a concurrent reset or a cleared `sendPolicy` is seen. If the row was deleted while the request was in flight, the Gateway falls back to the stored `sendPolicy`, channel, peer kind, and actor it read before taking the lock, so a deny the session carried still applies. A denied request writes nothing to the session store. A contained `raw~` bucket is a distinct key: a `keyPrefix` written for a linked person's canonical key does not match their unlinked `raw~<peer>` bucket — add a rule for each bucket (see [Sessions](https://docs.wednesdayai.dev/next/developers/concepts/session.md)).
> * **`store`**: per-agent session store identity (supports the `{agentId}` template); also where
>   legacy JSON session files are found for the one-time import. See
>   [Sessions](https://docs.wednesdayai.dev/next/developers/concepts/session.md#upgrading-from-json-session-files).
> * **`maintenance`**: session index cleanup + retention controls. Conversation history is never
>   deleted by maintenance: it only retires idle or over-cap sessions from the session index
>   (tombstones), and there is no automatic space reclamation (ADR 0098).
>   * `mode`: `warn` emits warnings only (default); `enforce` applies cleanup.
>   * `pruneAfter`: index entries whose `updatedAt` is older than this are retired (tombstoned) in
>     enforce mode (default `30d`).
>   * `maxEntries`: maximum number of session index rows to keep; the oldest are tombstoned beyond
>     the cap (default `500`).
>   * The file-only controls `rotateBytes`, `resetArchiveRetention`, `maxDiskBytes`, and
>     `highWaterBytes` are retired (they applied to JSONL transcript files) and are removed from
>     config automatically on load.
> * **`threadBindings`**: global defaults for thread-bound session features.
>   * `enabled`: master default switch (providers can override; Discord uses `channels.discord.threadBindings.enabled`)
>   * `idleHours`: default inactivity auto-unfocus in hours (`0` disables; providers can override)
>   * `maxAgeHours`: default hard max age in hours (`0` disables; providers can override)
> * **`consumerClaims`**: session-consumer claim ledger settings.
>   See [Session Consumer Claims](https://docs.wednesdayai.dev/next/admin/gateway/session-consumer-claims.md) for full details.
>   * `sweepCadenceMs`: reconciler sweep interval (default `60000` = 1min).
>   * `maxAttempts`: DLQ threshold (default `5`).
>   * `leaseMs`: claim lease duration (default `30000` = 30s).
>   * `retryBaseMs`: exponential backoff base (default `1000`).

***

## Storage

Where runtime data in each config domain is stored. Every config domain (`identity`, `pairing`,
`approvals`, `agents`, `channel-accounts`, `credentials`, `preferences`) has a backend; in this
release every domain is JSON-only, so SQL backends live in the session database. Inspect the
resolved placement with `wednesdayai storage status` ([CLI reference](https://docs.wednesdayai.dev/next/users/cli/storage)).

```json5 theme={"dark"}
{
  storage: {
    backend: "json", // json | sqlite | postgres
    domains: {
      preferences: { backend: "json" },
    },
  },
}
```

> [accordion] Storage field details
>
> * **`backend`**: default backend (`json`, `sqlite` or `postgres`) for every config domain that
>   ships it; domains that do not ship the selected backend stay on `json`. A `sqlite` or
>   `postgres` value must match `session.storage.backend` and the gateway fails to start with
>   `storage.backend is "<backend>" but session storage is "<session>"; config domains live in the
>   session database` when they disagree. In this release no domain ships a SQL backend, so the
>   gateway logs `storage.backend "<backend>" leaves config domains without a <backend> backend on
>   json: <ids>` for every domain.
> * **`domains.<id>.backend`**: per-domain override. `<id>` must be a config domain id (`identity`,
>   `pairing`, `approvals`, `agents`, `channel-accounts`, `credentials`, `preferences`); any other
>   key fails config validation with `storage.domains.<id>: unknown config domain; expected one of
>   identity, pairing, approvals, agents, channel-accounts, credentials, preferences`. The backend
>   must be one the domain ships: `storage domain "<id>" has no <backend> backend in this release`
>   otherwise. A SQL override must equal `session.storage.backend`; a mismatch fails with
>   `storage domain "<id>" is "<backend>" but session storage is "<session>"; config domains live
>   in the session database`.

Changes under `storage` require a gateway restart
(see [What hot-applies vs what needs a restart](https://docs.wednesdayai.dev/next/admin/gateway/configuration.md#what-hot-applies-vs-what-needs-a-restart)).

***

## Messages

```json5 theme={"dark"}
{
  messages: {
    responsePrefix: "🦞", // or "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 disables
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
      },
    },
  },
}
```

### Response prefix

Per-channel/account overrides: `channels.<channel>.responsePrefix`, `channels.<channel>.accounts.<id>.responsePrefix`.

Resolution (most specific wins): account → channel → global. `""` disables and stops cascade. `"auto"` derives `[{identity.name}]`.

**Template variables:**

| Variable | Description | Example |
| - | - | - |
| `{model}` | Short model name | `claude-opus-4-6` |
| `{modelFull}` | Full model identifier | `anthropic/claude-opus-4-6` |
| `{provider}` | Provider name | `anthropic` |
| `{thinkingLevel}` | Current thinking level | `high`, `low`, `off` |
| `{identity.name}` | Agent identity name | (same as `"auto"`) |

Variables are case-insensitive. `{think}` is an alias for `{thinkingLevel}`.

### Ack reaction

* Defaults to active agent's `identity.emoji`, otherwise `"👀"`. Set `""` to disable.
* Per-channel overrides: `channels.<channel>.ackReaction`, `channels.<channel>.accounts.<id>.ackReaction`.
* Resolution order: account → channel → `messages.ackReaction` → identity fallback.
* Scope: `group-mentions` (default), `group-all`, `direct`, `all`.
* `removeAckAfterReply`: removes ack after reply (Slack/Discord/Telegram/Google Chat only).

### Inbound debounce

Batches rapid text-only messages from the same sender into a single agent turn. Media/attachments flush immediately. Control commands bypass debouncing.

### TTS (text-to-speech)

```json5 theme={"dark"}
{
  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",
      readAloud: { enabled: true }, // gate for chat clients' Read aloud button
      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", // OpenAI-compatible endpoint; replaces the deprecated OPENAI_TTS_BASE_URL env var
        model: "gpt-4o-mini-tts",
        voice: "alloy",
      },
      providers: {
        kokoro: { voice: "af_heart", model: "kokoro" }, // plugin-registered speech providers only
      },
    },
  },
}
```

* `auto` controls auto-TTS. `/tts off|always|inbound|tagged` overrides per session.
* `summaryModel` overrides `agents.defaults.model.primary` for auto-summary.
* `modelOverrides` is enabled by default; `modelOverrides.allowProvider` defaults to `false` (opt-in).
* `openai.baseUrl`: OpenAI-compatible endpoint for OpenAI TTS (default `https://api.openai.com/v1`),
  overridable per agent with `agents.list[].tts.openai.baseUrl`. The `OPENAI_TTS_BASE_URL` env var
  is deprecated and is only used when no config value is set. A non-default endpoint relaxes the
  OpenAI model and voice validators. See [Text-to-speech](https://docs.wednesdayai.dev/next/users/tts.md).
* `providers`: per-provider settings for plugin-registered speech providers (such as the bundled
  Kokoro plugin), keyed by provider id. Built-in ids (`openai`, `elevenlabs`, `edge`) are rejected
  here. Plugin providers join the fallback order after the built-ins and are never auto-selected as
  primary. See [Custom and local providers](https://docs.wednesdayai.dev/next/users/tts.md#custom-and-local-providers).
* `readAloud.enabled`: gate for chat clients reading replies aloud on demand through the
  `tts.speak` gateway RPC (default `true`). Turn it off to stop on-demand synthesis spend; auto-TTS
  and `/tts` are unaffected. Overridden per agent by `agents.list[].tts.readAloud.enabled`. See
  [Read aloud for chat clients](https://docs.wednesdayai.dev/next/users/tts.md#read-aloud-for-chat-clients).
* Per-agent override: an agent's `agents.list[].tts` block (same fields as `messages.tts`) merges
  over the global config, so voice, provider, model and the read-aloud gate can differ per agent.
  See [Per-agent TTS](https://docs.wednesdayai.dev/next/users/tts.md#per-agent-tts-agentslisttts).
* API keys fall back to `ELEVENLABS_API_KEY`/`XI_API_KEY` and `OPENAI_API_KEY`.

***

## Talk

Defaults for Talk mode (macOS/iOS/Android).

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

* Voice IDs fall back to `ELEVENLABS_VOICE_ID` or `SAG_VOICE_ID`.
* `apiKey` and `providers.*.apiKey` accept plaintext strings or SecretRef objects. Both are best-effort: an unresolvable ref warns (`SECRETS_REF_OPTIONAL_UNRESOLVED`) and does not fail gateway startup. `talk.catalog` then reports that provider unavailable with `diagnostic: "secret-ref-unresolved"`. A CLI command that falls back to local secret resolution still hydrates a resolvable Talk ref instead of treating it as absent.
* `ELEVENLABS_API_KEY` fallback applies only when no Talk API key is configured.
* `voiceAliases` lets Talk directives use friendly names.
* Cascaded Voice mode reuses `talk.providers.<id>.modelId` when set. When it is unset, Voice mode falls back to `eleven_flash_v2_5`, not the legacy Talk-command default `eleven_v3` shown above.

### `talk.conversation`

Settings for the voice conversation behind the `/v2/client` web client's Dictate and Voice mode
controls. `engine` selects how Voice runs: the cascaded `stt-tts` loop or the session-bound
`realtime` speech-to-speech engine. See
[Voice conversation sessions](https://docs.wednesdayai.dev/next/users/talk/realtime-voice-conversation) for the full behavior;
cascaded text-to-speech output reuses `talk.provider`/`talk.providers.<id>` above, so this block
configures the STT seam, the engine choice, turn-taking thresholds, session limits, and
filler/acknowledgement phrases. The `realtime` engine uses the realtime provider's own voice:
neither `messages.tts` nor the `talk.provider`/`talk.providers.<id>` TTS settings apply to it.

```json5 theme={"dark"}
{
  talk: {
    conversation: {
      enabled: false,
      sttProvider: "elevenlabs",
      sttModel: "scribe_v2_realtime",
      endOfTurnSilenceMs: 500,
      recallDeadlineMs: 250,
      fillersEnabled: false,
      fillerAfterMs: 1200,
      falseInterruptionMs: 700,
      locale: "en",
      backchannels: {
        en: ["mm-hmm", "uh-huh", "yeah", "right", "okay", "ok", "sure", "got it", "i see"],
      },
      fillerPhrases: { en: ["One moment.", "Let me check.", "Just a sec."] },
      ackPhrases: { en: ["Working on that.", "Looking that up.", "On it."] },
      maxSessionMinutes: 30,
      maxTurnSeconds: 60,
      engine: "stt-tts",
    },
  },
}
```

| Field | Default | Meaning |
| - | - | - |
| `enabled` | `false` | Master gate. `talk.session.create` refuses every voice session (`stt-tts`, streaming-`transcription`, `realtime`) while this is `false`. |
| `sttProvider` | `"elevenlabs"` | Streaming speech-to-text provider id; must match a row in `talk.catalog`'s `streamingTranscription` section. |
| `sttModel` | `"scribe_v2_realtime"` | STT model id, passed through to the provider. |
| `endOfTurnSilenceMs` | `500` | Silence window used to estimate end-of-turn when the provider reports no `speechEndedAt` timestamp. |
| `recallDeadlineMs` | `250` | Deadline a voice turn's `context.collect` memory-recall hook races against. Typed chat turns never use this deadline. |
| `fillersEnabled` | `false` | Plays `fillerPhrases` and `ackPhrases` while the assistant prepares its reply. Off by default: on speakers the mic can hear the filler. The phrase lists keep their defaults. |
| `fillerAfterMs` | `1200` | Delay after end-of-turn before the cached filler phrase plays, if no assistant speech has started. |
| `falseInterruptionMs` | `700` | Window a qualifying STT word has, after a client-reported barge-in, to confirm the interruption before it resumes. |
| `backchannels` | built-in `"en"` list | Per-locale short phrases (keyed by lowercase BCP-47 tag) that never confirm a barge-in. |
| `fillerPhrases` | built-in `"en"` list | Per-locale phrases played when no speech output has started within `fillerAfterMs`. |
| `ackPhrases` | built-in `"en"` list | Per-locale phrases played when a tool call starts during a turn. |
| `locale` | `"en"` | BCP-47 locale selecting `backchannels`/`fillerPhrases`/`ackPhrases` for a session. An unrecognised locale falls back to `"en"`. |
| `maxSessionMinutes` | `30` | Hard session duration ceiling. A cascaded `stt-tts` session closes with `session.closed { reason: "session-minutes-exceeded" }`; the `realtime` engine uses the value as the relay session TTL and closes as a normal close when reached. |
| `maxTurnSeconds` | `60` | Hard ceiling on one turn's continuous user speech. Closes with `session.closed { reason: "turn-seconds-exceeded" }`. |
| `engine` | `"stt-tts"` | Voice mode engine. `"realtime"` runs speech-to-speech through the active talk realtime provider, bound to the chat session. |

Numeric fields (`endOfTurnSilenceMs`, `recallDeadlineMs`, `fillerAfterMs`, `falseInterruptionMs`, `maxSessionMinutes`, `maxTurnSeconds`) must be positive integers. `0`, negatives, and non-integers fail config validation.

Voice mode injects `commitStrategy: "vad"` and this block's `endOfTurnSilenceMs` into the STT provider config. An explicit `talk.providers.<id>.commitStrategy` (`"vad"` or `"manual"`) or `talk.providers.<id>.endOfTurnSilenceMs` wins, because those provider keys are spread last. Dictate does not receive that injection and commits only when the user stops.

Changes under `talk.conversation.*` apply without a gateway restart to new sessions; existing
sessions keep the configuration resolved when they started.

***

## Tools

### Tool profiles

`tools.profile` sets a base allowlist before `tools.allow`/`tools.deny`:

Local onboarding defaults new local configs to `tools.profile: "messaging"` when unset (existing explicit profiles are preserved). When onboarding applies that default profile, it also adds `tools.alsoAllow: ["group:fs"]` (skipped when `tools.allow` is already set) and `tools.fs.workspaceOnly: true`, so a fresh install has workspace-contained filesystem tools including `delete`. Existing configs are not modified; opt in with `tools.alsoAllow: ["group:fs"]` plus `tools.fs.workspaceOnly: true`.

| Profile | Includes |
| - | - |
| `minimal` | `session_status` only |
| `coding` | `group:fs`, `group:runtime`, `group:sessions`, `group:memory`, `image` |
| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `agents_nudge`, `session_status` |
| `full` | No restriction (same as unset) |

### Tool groups

| Group | Tools |
| - | - |
| `group:runtime` | `exec`, `process` (`bash` is accepted as an alias for `exec`) |
| `group:fs` | `read`, `write`, `edit`, `delete`, `apply_patch` |
| `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `agents_nudge`, `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:device` | Device tools (`node_<id>_<command>`) of the run's linked nodes; see [Device tools](https://docs.wednesdayai.dev/next/users/tools.md#device-tools) |
| `group:openclaw` | All built-in tools (excludes provider plugins) |

`tools.fs.workspaceOnly: true` restricts `read`/`write`/`edit`/`apply_patch` paths to the agent
workspace. `delete` is always workspace-contained: it deletes one file at a time, refuses
directories, the workspace root and paths outside the workspace (or the lane directory when
workspace lanes are on), and ignores `tools.fs.workspaceOnly`. `apply_patch` stays workspace-only
unless `tools.exec.applyPatch.workspaceOnly` is also set to `false`.

### `tools.allow` / `tools.deny`

Global tool allow/deny policy (deny wins). Case-insensitive, supports `*` wildcards. Applied even when Docker sandbox is off.

The `gateway` tool also accepts action tokens (`gateway.config_apply`, `gateway.config_patch`, `gateway.config_get`, `gateway.config_schema`, `gateway.restart`, `gateway.update_run`). For non-sandbox agents, `gateway.config_apply` is denied by default. Re-enable with `tools.allow`, `tools.alsoAllow`, or `agents.list[].tools.alsoAllow` (see [Config writes](https://docs.wednesdayai.dev/next/admin/gateway/config-writes.md)). Bare `*` does not waive that default-deny.

```json5 theme={"dark"}
{
  tools: { deny: ["browser", "canvas"] },
}
```

### `tools.byProvider`

Further restrict tools for specific providers or models. Order: base profile → provider profile → allow/deny.

```json5 theme={"dark"}
{
  tools: {
    profile: "coding",
    byProvider: {
      "google-antigravity": { profile: "minimal" },
      "openai/gpt-5.2": { allow: ["group:fs", "sessions_list"] },
    },
  },
}
```

### `tools.elevated`

Controls elevated (host) exec access:

```json5 theme={"dark"}
{
  tools: {
    elevated: {
      enabled: true,
      allowFrom: {
        whatsapp: ["+15555550123"],
        discord: ["1234567890123", "987654321098765432"],
      },
    },
  },
}
```

* Per-agent override (`agents.list[].tools.elevated`) can only further restrict.
* `/elevated on|off|ask|full` stores state per session; inline directives apply to single message.
* Elevated `exec` runs on the host, bypasses sandboxing.

### `tools.exec`

```json5 theme={"dark"}
{
  tools: {
    exec: {
      backgroundMs: 10000,
      timeoutSec: 1800,
      cleanupMs: 1800000,
      notifyOnExit: true,
      notifyOnExitEmptySuccess: false,
      applyPatch: {
        enabled: false,
        allowModels: ["gpt-5.2"],
      },
    },
  },
}
```

### `tools.loopDetection`

Tool-loop safety checks are **disabled by default**, except `detectors.sameErrorRepeat`, which runs unless you set it to `false` or set `enabled: false`. Set `enabled: true` to activate the other detectors.
Settings can be defined globally in `tools.loopDetection` and overridden per-agent at `agents.list[].tools.loopDetection`.

```json5 theme={"dark"}
{
  tools: {
    loopDetection: {
      enabled: true,
      historySize: 30,
      warningThreshold: 10,
      criticalThreshold: 20,
      globalCircuitBreakerThreshold: 30,
      detectors: {
        genericRepeat: true,
        knownPollNoProgress: true,
        pingPong: true,
        sameErrorRepeat: true,
      },
    },
  },
}
```

* `historySize`: max tool-call history retained for loop analysis.
* `warningThreshold`: repeating no-progress pattern threshold for warnings.
* `criticalThreshold`: higher repeating threshold for blocking critical loops.
* `globalCircuitBreakerThreshold`: hard stop threshold for any no-progress run.
* `detectors.genericRepeat`: warn on repeated same-tool/same-args calls.
* `detectors.knownPollNoProgress`: warn/block on known poll tools (`process.poll`, `command_status`, etc.).
* `detectors.pingPong`: warn/block on alternating no-progress pair patterns.
* `detectors.sameErrorRepeat`: warn, then block, when one tool repeats the same error within the last `historySize` calls of a run, even with changed arguments; the block lifts when those failures leave the window or a new run starts.
* If `warningThreshold >= criticalThreshold` or `criticalThreshold >= globalCircuitBreakerThreshold`, validation fails.

### `tools.web`

```json5 theme={"dark"}
{
  tools: {
    web: {
      search: {
        enabled: true,
        apiKey: "brave_api_key", // or BRAVE_API_KEY env
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
      },
      fetch: {
        enabled: true,
        maxChars: 50000,
        maxCharsCap: 50000,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
        userAgent: "custom-ua",
      },
    },
  },
}
```

### `tools.media`

Configures inbound media understanding (image/audio/video). The vendor providers referenced by
`provider` below (openai, google, etc.) ship as plugin extensions and are **disabled by default**
— enable each one with `plugins.entries.<vendor>.enabled: true` (see
[Media Understanding](https://docs.wednesdayai.dev/next/users/nodes/media-understanding.md#provider-extensions)). A config-provided
OpenAI-compatible proxy (`models.providers.<id>` with `api: "openai-completions"` or `"openai-responses"`)
needs no plugin extension, but voice notes are never auto-detected on it — name a speech-to-text model in
`tools.media.audio.models` (see [Config-provided proxy bindings](https://docs.wednesdayai.dev/next/users/nodes/media-understanding.md#config-provided-proxy-bindings-openai-compatible)).

The following example shows a vendor plugin entry (`openai`):

```json5 theme={"dark"}
{
  tools: {
    media: {
      concurrency: 2,
      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" }],
      },
    },
  },
}
```

> [accordion] Media model entry fields
>
> **Provider entry** (`type: "provider"` or omitted):
>
> * `provider`: API provider id (`openai`, `anthropic`, `google`/`gemini`, `groq`, etc.)
> * `model`: model id override
> * `profile` / `preferredProfile`: `auth-profiles.json` profile selection
>
> **CLI entry** (`type: "cli"`):
>
> * `command`: executable to run
> * `args`: templated args (supports `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, etc.)
>
> **Common fields:**
>
> * `capabilities`: optional list (`image`, `audio`, `video`). Defaults: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio.
> * `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: per-entry overrides.
> * Failures fall back to the next entry.
>
> Provider auth follows standard order: `auth-profiles.json` → env vars → `models.providers.*.apiKey`.
> The env var step checks the variable core maps for that provider id, then any variable the provider
> extension declares for itself (`envVars`). A provider whose credential resolves nowhere is skipped
> during auto-detection rather than attempted.

### `tools.agentToAgent`

```json5 theme={"dark"}
{
  tools: {
    agentToAgent: {
      enabled: false,
      allow: ["home", "work"],
    },
  },
}
```

### `tools.sessions`

Controls which sessions can be targeted by the session tools (`sessions_list`, `sessions_history`, `sessions_send`).

Default: `tree` (current session + sessions spawned by it, such as subagents).

```json5 theme={"dark"}
{
  tools: {
    sessions: {
      // "self" | "tree" | "agent" | "all"
      visibility: "tree",
    },
  },
}
```

Notes:

* `self`: only the current session key.
* `tree`: current session + sessions spawned by the current session (subagents).
* `agent`: any session belonging to the current agent id (can include other users if you run per-sender sessions under the same agent id).
* `all`: any session. Cross-agent targeting still requires `tools.agentToAgent`.
* Sandbox clamp: when the current session is sandboxed and `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, visibility is forced to `tree` even if `tools.sessions.visibility="all"`.

### `tools.sessions_spawn`

Controls inline attachment support for `sessions_spawn`.

```json5 theme={"dark"}
{
  tools: {
    sessions_spawn: {
      attachments: {
        enabled: false, // opt-in: set true to allow inline file attachments
        maxTotalBytes: 5242880, // 5 MB total across all files
        maxFiles: 50,
        maxFileBytes: 1048576, // 1 MB per file
        retainOnSessionKeep: false, // keep attachments when cleanup="keep"
      },
    },
  },
}
```

Notes:

* Attachments are only supported for `runtime: "subagent"`. ACP runtime rejects them.
* Files are materialized into the child workspace at `.openclaw/attachments/<uuid>/` with a `.manifest.json`.
* Attachment content is automatically redacted from transcript persistence.
* Base64 inputs are validated with strict alphabet/padding checks and a pre-decode size guard.
* File permissions are `0700` for directories and `0600` for files.
* Cleanup follows the `cleanup` policy: `delete` always removes attachments; `keep` retains them only when `retainOnSessionKeep: true`.

### `tools.subagents`

Tool-policy defaults for spawned sub-agents. Controls which **tools** sub-agents can use — not which agent IDs can be spawned (that's `agents.list[].subagents.allowAgents`).

```json5 theme={"dark"}
{
  tools: {
    subagents: {
      model: "minimax/MiniMax-M2.5", // default model (also settable via agents.defaults.subagents.model)
      tools: {
        allow: ["read", "exec", "process"], // if set, becomes allow-only (deny still wins)
        alsoAllow: ["browser"], // merge into allow / default sub-agent denylist
        deny: ["gateway", "cron"], // deny wins over allow
      },
    },
  },
}
```

* `model`: default model for spawned sub-agents. If omitted, sub-agents inherit the caller's model. Overridden per-agent by `agents.list[].subagents.model` and globally by `agents.defaults.subagents.model`.
* `tools.allow`: if set, becomes allow-only (deny still wins).
* `tools.alsoAllow`: additional allowlist entries merged into allow and/or default sub-agent denylist.
* `tools.deny`: denied tools (deny wins over allow).
* Sub-agents always start with all tools except session tools (`sessions_list`, `sessions_history`, `sessions_send`, `agents_nudge`, `sessions_spawn`) and system tools. At `maxSpawnDepth >= 2`, depth-1 orchestrators additionally receive `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history`.

For runtime tuning (depth, concurrency, timeouts, archive), see `agents.defaults.subagents.*` above.

***

## Custom providers and base URLs

WednesdayAI uses the pi-coding-agent model catalog. Add custom providers via `models.providers` in config or `~/.openclaw/agents/<agentId>/agent/models.json`.

```json5 theme={"dark"}
{
  models: {
    mode: "merge", // merge (default) | replace
    providers: {
      "custom-proxy": {
        baseUrl: "http://localhost:4000/v1",
        apiKey: "LITELLM_KEY",
        api: "openai-completions", // openai-completions | openai-responses | anthropic-messages | google-generative-ai
        models: [
          {
            id: "llama-3.1-8b",
            name: "Llama 3.1 8B",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 32000,
          },
        ],
      },
    },
  },
}
```

* Use `authHeader: true` + `headers` for custom auth needs.
* Override agent config root with `OPENCLAW_AGENT_DIR` (or `PI_CODING_AGENT_DIR`).
* Merge precedence for matching provider IDs:
  * Non-empty agent `models.json` `apiKey`/`baseUrl` win.
  * Empty or missing agent `apiKey`/`baseUrl` fall back to `models.providers` in config.
  * Matching model `contextWindow`/`maxTokens` use the higher value between explicit config and implicit catalog values.
  * Use `models.mode: "replace"` when you want config to fully rewrite `models.json`.

### Provider field details

* `models.mode`: provider catalog behavior (`merge` or `replace`).
* `models.providers`: custom provider map keyed by provider id.
* `models.providers.*.api`: request adapter (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai`, etc).
* `models.providers.*.apiKey`: provider credential (prefer SecretRef/env substitution).
* `models.providers.*.auth`: auth strategy (`api-key`, `token`, `oauth`, `aws-sdk`).
* `models.providers.*.injectNumCtxForOpenAICompat`: for Ollama + `openai-completions`, inject `options.num_ctx` into requests (default: `true`).
* `models.providers.*.authHeader`: force credential transport in the `Authorization` header when required.
* `models.providers.*.baseUrl`: upstream API base URL.
* `models.providers.*.headers`: extra static headers for proxy/tenant routing.
* `models.providers.*.models`: explicit provider model catalog entries.
* `models.providers.*.models.*.compat.supportsDeveloperRole`: optional compatibility hint. For `api: "openai-completions"` with a non-empty non-native `baseUrl` (host not `api.openai.com`), WednesdayAI forces this to `false` at runtime. Empty/omitted `baseUrl` keeps default OpenAI behavior.
* `models.bedrockDiscovery`: Bedrock auto-discovery settings root.
* `models.bedrockDiscovery.enabled`: turn discovery polling on/off.
* `models.bedrockDiscovery.region`: AWS region for discovery.
* `models.bedrockDiscovery.providerFilter`: optional provider-id filter for targeted discovery.
* `models.bedrockDiscovery.refreshInterval`: polling interval for discovery refresh.
* `models.bedrockDiscovery.defaultContextWindow`: fallback context window for discovered models.
* `models.bedrockDiscovery.defaultMaxTokens`: fallback max output tokens for discovered models.

### Provider examples

> [accordion] Cerebras (GLM 4.6 / 4.7)
>
> ```json5 theme={"dark"}
> {
>   env: { CEREBRAS_API_KEY: "sk-..." },
>   agents: {
>     defaults: {
>       model: {
>         primary: "cerebras/zai-glm-4.7",
>         fallbacks: ["cerebras/zai-glm-4.6"],
>       },
>       models: {
>         "cerebras/zai-glm-4.7": { alias: "GLM 4.7 (Cerebras)" },
>         "cerebras/zai-glm-4.6": { alias: "GLM 4.6 (Cerebras)" },
>       },
>     },
>   },
>   models: {
>     mode: "merge",
>     providers: {
>       cerebras: {
>         baseUrl: "https://api.cerebras.ai/v1",
>         apiKey: "${CEREBRAS_API_KEY}",
>         api: "openai-completions",
>         models: [
>           { id: "zai-glm-4.7", name: "GLM 4.7 (Cerebras)" },
>           { id: "zai-glm-4.6", name: "GLM 4.6 (Cerebras)" },
>         ],
>       },
>     },
>   },
> }
> ```
>
> Use `cerebras/zai-glm-4.7` for Cerebras; `zai/glm-4.7` for Z.AI direct.

> [accordion] OpenCode Zen
>
> ```json5 theme={"dark"}
> {
>   agents: {
>     defaults: {
>       model: { primary: "opencode/claude-opus-4-6" },
>       models: { "opencode/claude-opus-4-6": { alias: "Opus" } },
>     },
>   },
> }
> ```
>
> Set `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`). Shortcut: `wednesdayai onboard --auth-choice opencode-zen`.

> [accordion] Z.AI (GLM-4.7)
>
> ```json5 theme={"dark"}
> {
>   agents: {
>     defaults: {
>       model: { primary: "zai/glm-4.7" },
>       models: { "zai/glm-4.7": {} },
>     },
>   },
> }
> ```
>
> Set `ZAI_API_KEY`. `z.ai/*` and `z-ai/*` are accepted aliases. Shortcut: `wednesdayai onboard --auth-choice zai-api-key`.
>
> * General endpoint: `https://api.z.ai/api/paas/v4`
> * Coding endpoint (default): `https://api.z.ai/api/coding/paas/v4`
> * For the general endpoint, define a custom provider with the base URL override.

> [accordion] Moonshot AI (Kimi)
>
> ```json5 theme={"dark"}
> {
>   env: { MOONSHOT_API_KEY: "sk-..." },
>   agents: {
>     defaults: {
>       model: { primary: "moonshot/kimi-k2.5" },
>       models: { "moonshot/kimi-k2.5": { alias: "Kimi K2.5" } },
>     },
>   },
>   models: {
>     mode: "merge",
>     providers: {
>       moonshot: {
>         baseUrl: "https://api.moonshot.ai/v1",
>         apiKey: "${MOONSHOT_API_KEY}",
>         api: "openai-completions",
>         models: [
>           {
>             id: "kimi-k2.5",
>             name: "Kimi K2.5",
>             reasoning: false,
>             input: ["text"],
>             cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
>             contextWindow: 256000,
>             maxTokens: 8192,
>           },
>         ],
>       },
>     },
>   },
> }
> ```
>
> For the China endpoint: `baseUrl: "https://api.moonshot.cn/v1"` or `wednesdayai onboard --auth-choice moonshot-api-key-cn`.

> [accordion] Kimi Coding
>
> ```json5 theme={"dark"}
> {
>   env: { KIMI_API_KEY: "sk-..." },
>   agents: {
>     defaults: {
>       model: { primary: "kimi-coding/k2p5" },
>       models: { "kimi-coding/k2p5": { alias: "Kimi K2.5" } },
>     },
>   },
> }
> ```
>
> Anthropic-compatible, built-in provider. Shortcut: `wednesdayai onboard --auth-choice kimi-code-api-key`.

> [accordion] Synthetic (Anthropic-compatible)
>
> ```json5 theme={"dark"}
> {
>   env: { SYNTHETIC_API_KEY: "sk-..." },
>   agents: {
>     defaults: {
>       model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.5" },
>       models: { "synthetic/hf:MiniMaxAI/MiniMax-M2.5": { alias: "MiniMax M2.5" } },
>     },
>   },
>   models: {
>     mode: "merge",
>     providers: {
>       synthetic: {
>         baseUrl: "https://api.synthetic.new/anthropic",
>         apiKey: "${SYNTHETIC_API_KEY}",
>         api: "anthropic-messages",
>         models: [
>           {
>             id: "hf:MiniMaxAI/MiniMax-M2.5",
>             name: "MiniMax M2.5",
>             reasoning: false,
>             input: ["text"],
>             cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
>             contextWindow: 192000,
>             maxTokens: 65536,
>           },
>         ],
>       },
>     },
>   },
> }
> ```
>
> Base URL should omit `/v1` (Anthropic client appends it). Shortcut: `wednesdayai onboard --auth-choice synthetic-api-key`.

> [accordion] MiniMax M2.5 (direct)
>
> ```json5 theme={"dark"}
> {
>   agents: {
>     defaults: {
>       model: { primary: "minimax/MiniMax-M2.5" },
>       models: {
>         "minimax/MiniMax-M2.5": { alias: "Minimax" },
>       },
>     },
>   },
>   models: {
>     mode: "merge",
>     providers: {
>       minimax: {
>         baseUrl: "https://api.minimax.io/anthropic",
>         apiKey: "${MINIMAX_API_KEY}",
>         api: "anthropic-messages",
>         models: [
>           {
>             id: "MiniMax-M2.5",
>             name: "MiniMax M2.5",
>             reasoning: false,
>             input: ["text"],
>             cost: { input: 15, output: 60, cacheRead: 2, cacheWrite: 10 },
>             contextWindow: 200000,
>             maxTokens: 8192,
>           },
>         ],
>       },
>     },
>   },
> }
> ```
>
> Set `MINIMAX_API_KEY`. Shortcut: `wednesdayai onboard --auth-choice minimax-api`.

> [accordion] Local models (LM Studio)
>
> See [Local Models](https://docs.wednesdayai.dev/next/admin/gateway/local-models.md). TL;DR: run MiniMax M2.5 via LM Studio Responses API on serious hardware; keep hosted models merged for fallback.

***

## Skills

```json5 theme={"dark"}
{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
    },
    install: {
      preferBrew: true,
      nodeManager: "npm", // npm | pnpm | yarn
    },
    entries: {
      "nano-banana-pro": {
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string
        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
    installs: {
      "nano-banana-pro": {
        source: "archive",
        spec: "nano-banana-pro",
        installPath: "~/.openclaw/skills/nano-banana-pro",
        version: "1.2.0",
      },
    },
  },
}
```

* `allowBundled`: optional allowlist for bundled skills only (managed/workspace skills unaffected).
* `entries.<skillKey>.enabled: false` disables a skill even if bundled/installed.
* `entries.<skillKey>.apiKey`: convenience for skills declaring a primary env var (plaintext string or SecretRef object).
* `skills.installs`: CLI-managed install metadata for skills installed from the verified
  skills catalog (`wednesdayai skills install <id>`), used by `wednesdayai skills` commands to
  locate install sources. Mirrors `plugins.installs`:
  * `source` is one of `npm`, `archive`, `path`, or `bundled`; catalog installs use `archive`.
  * `spec` is the catalog id (or the original spec for non-catalog installs).
  * `installPath` is the resolved install directory (usually `~/.openclaw/skills/<id>`).
  * Includes `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`,
    `resolvedVersion`, `resolvedSpec` (the verified download URL), `integrity`
    (`sha256:<hex>` from the catalog), `shasum`, `resolvedAt`, `installedAt`.
  * Treat `skills.installs.*` as managed state; prefer CLI commands (`skills install`,
    `skills uninstall`) over manual edits. See [skills CLI](https://docs.wednesdayai.dev/next/users/cli/skills.md).

***

## Plugins

```json5 theme={"dark"}
{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    deny: [],
    load: {
      paths: ["~/Projects/oss/voice-call-extension"],
    },
    installs: {
      telegram: {
        source: "bundled",
        sourcePath: "/path/to/extensions/telegram",
        version: "0.4.4",
      },
    },
    hookTimeouts: {
      default: 30000,
      "context.collect": 60000,
    },
    analysisConcurrency: {
      maxParallel: 2,
      maxSequential: 0,
      maxParallelPerPlugin: 1,
      // omit maxSequentialPerPlugin to inherit maxSequential
    },
    entries: {
      "voice-call": {
        enabled: true,
        config: { provider: "twilio" },
      },
    },
  },
}
```

* Loaded from `~/.openclaw/extensions`, `<workspace>/.openclaw/extensions`, plus `plugins.load.paths`.
* **Config changes require a gateway restart.**
* `allow`: optional allowlist (only listed plugins load). `deny` wins.
* `plugins.entries.<id>.apiKey`: plugin-level API key convenience field (when supported by the plugin).
* `plugins.entries.<id>.env`: plugin-scoped env var map.
* `plugins.entries.<id>.config`: plugin-defined config object (validated by plugin schema).
* `plugins.entries.<id>.grants.agentTurn.agents`: agent ids (or `"*"`) this plugin may wake
  through `api.runtime.signals.nudge`; default deny. Each wake is a durable `agent.turn` nudge.
  Bundled plugins may ship a manifest-declared default used only when this key is unset (an
  explicit empty list revokes it). See [Agent coordination](https://docs.wednesdayai.dev/next/developers/concepts/agent-coordination).
* `plugins.slots.memory`: pick the active memory plugin id, or `"none"` to disable memory plugins.
* `plugins.slots.contextEngine`: pick the active context-engine plugin id, or `"none"` to disable
  context-engine plugins. Unlike `plugins.slots.memory` there is no default id: unset means the
  first loaded context-engine plugin wins.
* `plugins.hookTimeouts`: per-hook timeout in milliseconds. Keys are hook names or `default`.
  Unset hooks use 30000 ms. Registration `api.on(..., { timeoutMs })` still wins. Restart required.
* `plugins.analysisConcurrency.maxParallel`: concurrent awaited `analysis.run()` slots (default 2). Most-permissive across winning enabled manifests unless the operator sets this field.
* `plugins.analysisConcurrency.maxSequential`: global awaited-overflow queue for calls blocked by either the global or per-plugin active boundary, not only after global parallel slots fill (default 0).
* `plugins.analysisConcurrency.maxParallelPerPlugin`: concurrent awaited slots for one plugin (default 1, clamped to maxParallel). Attaches to plugin identity from the winning enabled manifest. Operator value is a uniform ceiling when set.
* `plugins.analysisConcurrency.maxSequentialPerPlugin`: per-plugin overflow queue (inherits maxSequential when omitted, clamped to maxSequential), including when global active capacity remains. Operator value is a uniform ceiling when set.
* `plugins.contextHookTimeoutMs`: deprecated fallback for `context.*` hooks only, used when
  `hookTimeouts` does not cover that hook. Restart required.
* `plugins.installs`: CLI-managed install metadata used by `wednesdayai plugins update`.
  * `source` is one of `npm`, `archive`, `path`, or `bundled`.
  * `source: "bundled"` means the plugin is loaded from the bundled extension copy that shipped with the current WednesdayAI package. `sourcePath` must match that current bundled source path.
  * Includes `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`.
  * Treat `plugins.installs.*` as managed state; prefer CLI commands over manual edits.

Gateway validation treats missing plugin references in `plugins.entries`, `plugins.allow`,
`plugins.deny`, `plugins.slots.memory`, and `plugins.slots.contextEngine` as warnings rather than
hard errors. A valid
`source: "bundled"` install record suppresses those warnings even when discovery cache state is
stale, and the plugin's config is still validated against the bundled manifest's `configSchema`.
If logs suggest `wednesdayai plugins install <id>` for a bundled plugin that is already loaded,
run `wednesdayai plugins info <id>` and `wednesdayai plugins list --verbose` before editing
config. Bundled install records should not be added to `plugins.load.paths`.

See [Plugins](https://docs.wednesdayai.dev/next/users/tools/plugin.md).

***

## Browser

```json5 theme={"dark"}
{
  browser: {
    enabled: true,
    evaluateEnabled: true,
    defaultProfile: "chrome",
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: true, // default trusted-network mode
      // allowPrivateNetwork: true, // legacy alias
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    profiles: {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      work: { cdpPort: 18801, color: "#0066CC" },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
    color: "#FF4500",
    // headless: false,
    // noSandbox: false,
    // extraArgs: [],
    // executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    // attachOnly: false,
    // snapshotDefaults: { mode: "efficient" },
    // remoteCdpTimeoutMs: 1500,
    // remoteCdpHandshakeTimeoutMs: 3000,
  },
}
```

* `evaluateEnabled: false` disables `act:evaluate` and `wait --fn`.
* `ssrfPolicy.dangerouslyAllowPrivateNetwork` defaults to `true` when unset (trusted-network model).
* Set `ssrfPolicy.dangerouslyAllowPrivateNetwork: false` for strict public-only browser navigation.
* `ssrfPolicy.allowPrivateNetwork` remains supported as a legacy alias.
* In strict mode, use `ssrfPolicy.hostnameAllowlist` and `ssrfPolicy.allowedHostnames` for explicit exceptions.
* `ssrfPolicy.allowedCidrs` allows specific IPv4/IPv6 CIDR ranges for private/internal addresses.
* `ssrfPolicy.allowRfc2544BenchmarkRange` additionally allows the 198.18.0.0/15 benchmark range.
* Remote profiles are attach-only (start/stop/reset disabled).
* Auto-detect order: default browser if Chromium-based → Chrome → Brave → Edge → Chromium → Chrome Canary.
* Control service: loopback only (port derived from `gateway.port`, default `18791`).
* `extraArgs` appends extra launch flags to local Chromium startup (for example
  `--disable-gpu`, window sizing, or debug flags).
* `snapshotDefaults.mode: "efficient"` uses compact role snapshots by default when the caller does not specify a mode.
* `remoteCdpTimeoutMs` (default: 1500) applies to remote (non-loopback) CDP HTTP reachability checks.
* `remoteCdpHandshakeTimeoutMs` (default: max(remoteCdpTimeoutMs \* 2, 2000)) applies to remote CDP WebSocket handshake checks.
* Per-profile options: `cdpPort`, `cdpUrl`, `driver` (`"openclaw"` or `"extension"`), `attachOnly`, `color`.

***

## Network

```json5 theme={"dark"}
{
  network: {
    ssrfPolicy: {
      // Preferred: allow only specific LAN hosts/subnets (deny everything else private).
      allowedCidrs: ["192.168.1.0/24"],
      // allowedHostnames: ["llm.internal.example.com"],
      // hostnameAllowlist: ["llm.internal"],           // legacy alias
      // allowPrivateNetwork: true,                     // legacy alias for dangerouslyAllowPrivateNetwork
      // Or open all private space (broad, audited, logged):
      // dangerouslyAllowPrivateNetwork: true,
      // allowRfc2544BenchmarkRange: true,              // also allows 198.18.0.0/15 benchmark range
    },
  },
}
```

* By default all outbound requests to private/loopback/link-local addresses are blocked (deny-by-default).
* `network.ssrfPolicy.allowedCidrs`: preferred narrow override — list CIDR ranges whose addresses are permitted. All other private space remains blocked.
* `network.ssrfPolicy.allowedHostnames` / `hostnameAllowlist`: allow specific hostnames (both DNS phases checked).
* `network.ssrfPolicy.dangerouslyAllowPrivateNetwork`: blunt override — allows **all** private addresses. Surfaced by `wednesdayai security audit` and logged at startup. Use `allowedCidrs` instead where possible.
* `network.ssrfPolicy.allowPrivateNetwork`: legacy alias for `dangerouslyAllowPrivateNetwork`.
* `network.ssrfPolicy.allowRfc2544BenchmarkRange`: additionally allows the RFC 2544 benchmark range (`198.18.0.0/15`), which is technically not in the standard private IANA ranges but is sometimes used internally.
* All blocked requests emit an actionable log line naming the target and the exact config key to set.
* All permitted-private requests emit an INFO log for monitoring.

See [Network egress policy](https://docs.wednesdayai.dev/next/admin/gateway/security/network-egress-policy.md) for the full security rationale and worked examples.

***

## UI

```json5 theme={"dark"}
{
  ui: {
    seamColor: "#FF4500",
    assistant: {
      name: "WednesdayAI",
      avatar: "CB", // emoji, short text, image URL, or data URI
    },
  },
}
```

* `seamColor`: accent color for native app UI chrome (Talk Mode bubble tint, etc.).
* `assistant`: Control UI identity override. Falls back to active agent identity.

***

## Gateway

```json5 theme={"dark"}
{
  gateway: {
    mode: "local", // local | remote
    port: 18789,
    bind: "loopback",
    auth: {
      mode: "token", // none | token | password | trusted-proxy
      token: "your-token",
      // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD
      // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth
      allowTailscale: true,
      rateLimit: {
        maxAttempts: 10,
        windowMs: 60000,
        lockoutMs: 300000,
        exemptLoopback: true,
      },
    },
    tailscale: {
      mode: "off", // off | serve | funnel
      resetOnExit: false,
    },
    controlUi: {
      // admission and auth policy for the operator console client (openclaw-control-ui);
      // the removed classic hosting keys (enabled, basePath, root) are stripped on config load
      // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI
      // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode
      // allowInsecureAuth: false,
      // dangerouslyDisableDeviceAuth: false,
    },
    webClient: {
      // allowedOrigins: ["https://chat.example.com"], // required for the WednesdayAI web client
      // enabled: false, // serve the web client bundle from this gateway (default off)
      // basePath: "/v2/client", // default; override to remount, must not collide with another SPA mount
      // root: "/srv/wednesdayai-web", // optional; defaults to the packaged dist/web-client
      // accountLinking: true, // default; set false to keep all linking operator-only (no /link codes)
    },
    controlUiV2: {
      // enabled: true, // default; the v2 console owns the gateway root
      // basePath is unset by default: unset means the gateway root, but the console yields to
      // /v2/control when an enabled web client explicitly owns "/" — setting basePath: "/"
      // explicitly in that case is a collision the config load rejects.
      // root: "/srv/wednesdayai-control", // optional; defaults to the packaged dist/control-ui-v2
      // pluginUi: { allow: ["console-ui-probe"] }, // plugin ids allowed to run browser code in the console
    },
    remote: {
      url: "ws://gateway.tailnet:18789",
      transport: "ssh", // ssh | direct
      token: "your-token",
      // password: "your-password",
    },
    trustedProxies: ["10.0.0.1"],
    // Optional. Default false.
    allowRealIpFallback: false,
    tools: {
      // Additional /tools/invoke HTTP denies
      deny: ["browser"],
      // Remove tools from the default HTTP deny list
      allow: ["gateway"],
    },
  },
}
```

> [accordion] Gateway field details
>
> * `mode`: `local` (run gateway) or `remote` (connect to remote gateway). Gateway refuses to start unless `local`.
> * `port`: single multiplexed port for WS + HTTP. Precedence: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`.
> * `bind`: `auto`, `loopback` (default), `lan` (`0.0.0.0`), `tailnet` (Tailscale IP only), or `custom`.
> * **Legacy bind aliases**: use bind mode values in `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), not host aliases (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`).
> * **Docker note**: the default `loopback` bind listens on `127.0.0.1` inside the container. With Docker bridge networking (`-p 18789:18789`), traffic arrives on `eth0`, so the gateway is unreachable. Use `--network host`, or set `bind: "lan"` (or `bind: "custom"` with `customBindHost: "0.0.0.0"`) to listen on all interfaces.
> * **Auth**: required by default. Non-loopback binds require a shared token/password. Onboarding wizard generates a token by default.
> * `gateway.auth.mode: "none"`: explicit no-auth mode. Use only for trusted local loopback setups; this is intentionally not offered by onboarding prompts.
> * `gateway.auth.mode: "trusted-proxy"`: delegate auth to an identity-aware reverse proxy and trust identity headers from `gateway.trustedProxies` (see [Trusted Proxy Auth](https://docs.wednesdayai.dev/next/admin/gateway/trusted-proxy-auth.md)).
> * **Ambient auth still verifies device tokens**: under `none`, `trusted-proxy` or Tailscale identity auth, a connect that presents `auth.deviceToken` gets it verified as under `token` mode; a revoked, unknown or over-scoped token is refused with `AUTH_DEVICE_TOKEN_MISMATCH`. `auth.token` is not treated as a device credential in those modes. See [Protocol](https://docs.wednesdayai.dev/next/admin/gateway/protocol.md#client-identity).
> * The `openclaw-user-client` web client is exempt from every ambient auth mode: under `none`, `trusted-proxy` and Tailscale identity auth it is still refused (`CLIENT_DEVICE_CREDENTIAL_REQUIRED`) unless it presents its bounded device token or redeems its bounded bootstrap token. Hosting it behind a reverse proxy keeps working; the proxy identity just never replaces the device credential. Other client ids are unaffected. See [Protocol](https://docs.wednesdayai.dev/next/admin/gateway/protocol.md) for the full rule.
> * `gateway.auth.allowTailscale`: when `true`, Tailscale Serve identity headers can satisfy Control UI/WebSocket auth (verified via `tailscale whois`); HTTP API endpoints still require token/password auth. This tokenless flow assumes the gateway host is trusted. Defaults to `true` when `tailscale.mode = "serve"`.
> * `gateway.auth.rateLimit`: optional failed-auth limiter. Applies per client IP and per auth scope (shared-secret and device-token are tracked independently). Blocked attempts return `429` + `Retry-After`.
>   * `gateway.auth.rateLimit.exemptLoopback` defaults to `true`; set `false` when you intentionally want localhost traffic rate-limited too (for test setups or strict proxy deployments).
> * Browser-origin WS auth attempts are always throttled with loopback exemption disabled (defense-in-depth against browser-based localhost brute force).
> * `tailscale.mode`: `serve` (tailnet only, loopback bind) or `funnel` (public, requires auth).
> * `controlUi.allowedOrigins`: explicit browser-origin allowlist for Gateway WebSocket connects. Required when browser clients are expected from non-loopback origins: a non-loopback bind with the operator console (`controlUiV2`) enabled is refused at startup without it, unless `dangerouslyAllowHostHeaderOriginFallback` is set. Onboarding and gateway startup seed `http://localhost:<port>` and `http://127.0.0.1:<port>` (plus the custom bind host) when none are configured. `gateway.controlUi` is the admission and auth policy for the `openclaw-control-ui` console client; its removed classic hosting keys (enabled, basePath, root) are stripped by a retirement migration when the config loads.
> * `OPENCLAW_GATEWAY_CONTROL_UI_ALLOWED_ORIGINS` (env): comma-separated origins appended to `controlUi.allowedOrigins` when config loads, for deployments without a config file such as the container image on Cloud Run. Every consumer (startup guard, WebSocket origin check, doctor, audit) sees the merged list; the env origins are never written to `openclaw.json`.
> * `controlUi.dangerouslyAllowHostHeaderOriginFallback`: dangerous mode that enables Host-header origin fallback for deployments that intentionally rely on Host-header origin policy.
> * `webClient.allowedOrigins`: exact browser origins allowed to open a websocket as the `openclaw-user-client` web client. This check always runs for that client id, even when reverse-proxy headers are present, and `controlUi.allowedOrigins` never admits it. Default empty, which admits nothing. See [Protocol](https://docs.wednesdayai.dev/next/admin/gateway/protocol.md) for the client identity rules.
> * `webClient.enabled`: serve the built web client bundle from this gateway, same-origin, at `webClient.basePath`. Default `false`: the client is normally hosted separately (`wednesdayai web serve`, a CDN, or the container image). Enabling it does not admit the client - the origin allowlist above still applies, so add the gateway's own origin. See [Web client hosting](https://docs.wednesdayai.dev/next/admin/web/user-client.md).
> * `webClient.basePath`: public path the gateway-served client is mounted under. Default `/v2/client`. It must be a single-slash path: a `//` prefix, backslashes, whitespace or control characters, `.` or `..` segments, and query or fragment characters are rejected when the config loads. It may not equal, contain, or be contained by another active SPA mount (`gateway.controlUiV2.basePath` when the v2 console is enabled); a collision is rejected when the config loads, naming both keys. Earlier builds defaulted to `/client`; on a deployment that never set `basePath`, an old `/client/` bookmark no longer reaches the client (there is no redirect), and with the Control UI at the gateway root that path is answered by the Control UI. Set `basePath: "/client"` to keep the old address. `gateway.*` changes need a gateway restart. See [Web client hosting](https://docs.wednesdayai.dev/next/admin/web/user-client.md#gateway-route).
> * `webClient.root`: directory holding the built bundle (`index.html` plus `assets/`). Optional: with `webClient.enabled` true and no `root`, the gateway serves the bundle packaged with this install (`dist/web-client`), and answers `503` naming the build command only when that is missing too. An explicit `root` always wins - including when it is broken, which answers `503` with that reason rather than silently falling back.
> * `webClient.imageOrigins`: exact `https://host[:port]` origins that remote markdown images may load from in the gateway-served web client, extended into its CSP `img-src`. Default empty: remote images render as links and never auto-load, so agent output cannot turn them into a tracking or exfiltration channel. Each entry must be an exact https origin with no path, query or fragment. See [Web client hosting](https://docs.wednesdayai.dev/next/admin/web/user-client.md).
> * `webClient.accountLinking`: lets a linked web-client user link their own chat accounts with `/link` codes (web client Account menu → Linked accounts → `identity.link.claim`). Default `true`. Set `false` to keep all linking operator-only: `/link` and the claim RPC both answer `Account linking is turned off on this gateway.` Operator commands (`identity add/link/unlink`, `devices link`, `pairing approve`) are unaffected. See [Identities](https://docs.wednesdayai.dev/next/admin/gateway/identity).
> * `webClient.pluginUi.allow`: plugin ids whose chat UI browser module (manifest `chatUi.entry`) the web client may load. Default **none**: an unlisted plugin contributes no chat panels and its UI assets answer 404. Plugin chat UI calls are dispatched per user (`plugins.chatUi.request` injects the signed-in user's identity); allow only plugins you trust. Take effect when the gateway applies the config, plus a web client reload. See the developer guide [Chat UI plugins](https://docs.wednesdayai.dev/next/developers/plugins/chat-ui).
> * `controlUiV2.enabled`: serve the control UI v2 operator console from this gateway, same-origin, at `controlUiV2.basePath`. Default `true`: the v2 console is the daily console and owns the gateway root. Set it to `false` to serve no operator console. The classic console was removed (ADR 1771), so `gateway.controlUi` is admission-only and `controlUiV2` is the only console mount. The console connects as the `openclaw-control-ui` client, so admission, scopes and auth modes are governed by `controlUi.allowedOrigins` and friends; there is no separate allowlist. A non-loopback bind with the console enabled still requires `controlUi.allowedOrigins` at startup. See [Control UI v2](https://docs.wednesdayai.dev/next/admin/web/control-ui-v2.md).
> * `controlUiV2.basePath`: public path the console is mounted under. Default: the gateway root; the v2 console mounts at `/v2/control` instead when an enabled `webClient` explicitly claims `/` with its `basePath`, so a config that pinned the removed classic console to the root now serves v2 at the root. Must be a single-slash path: it must start with `/`, and a `//` prefix, backslashes, whitespace or control characters, `.` or `..` segments, and query or fragment characters are rejected when the config loads. It may not equal, contain, or be contained by another active SPA mount (`webClient.basePath`); a collision is rejected when the config loads, naming both keys. `gateway.*` changes need a gateway restart.
> * `controlUiV2.root`: directory holding the built console (`index.html` plus `assets/`). Optional: unset, the gateway serves the bundle packaged with this install (`dist/control-ui-v2`) and answers `503` naming `pnpm control:build:packaged` only when that is missing too. An explicit `root` always wins - including when it is broken, which answers `503` with that reason.
> * `controlUiV2.pluginUi.allow`: plugin ids whose browser module (manifest `controlUi.entry`) the console may load. Default **none**: an unlisted plugin contributes no pages or panels and its UI assets answer 404. Plugin UI shares your console session's gateway access; allow only plugins you trust. Take effect when the gateway applies the config, plus a console tab reload. See [Control UI v2](https://docs.wednesdayai.dev/next/admin/web/control-ui-v2.md) and the developer guide [Control UI plugins](https://docs.wednesdayai.dev/next/developers/plugins/control-ui).
> * `remote.transport`: `ssh` (default) or `direct` (ws/wss). For `direct`, `remote.url` must be `ws://` or `wss://`.
> * `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: client-side break-glass override that allows plaintext `ws://` to trusted private-network IPs; default remains loopback-only for plaintext.
> * `gateway.remote.token` / `.password` are remote-client credential fields. They do not configure gateway auth by themselves.
> * Local gateway call paths can use `gateway.remote.*` as fallback when `gateway.auth.*` is unset.
> * `trustedProxies`: reverse proxy IPs that terminate TLS. Only list proxies you control.
> * `allowRealIpFallback`: when `true`, the gateway accepts `X-Real-IP` if `X-Forwarded-For` is missing. Default `false` for fail-closed behavior.
> * `gateway.tools.deny`: extra tool names blocked for HTTP `POST /tools/invoke` (extends default deny list).
> * `gateway.tools.allow`: remove tool names from the default HTTP deny list.
> * `gateway.nodes.browser.mode`: browser routing mode for node-hosted browser proxies. Values: `"auto"` (default, route to browser-capable node if available), `"manual"` (explicit node pinning required), `"off"` (disable node browser proxy).
> * `gateway.nodes.browser.node`: pin browser routing to a specific node id or name (optional).
> * `gateway.devices.staleAfterDays`: days without activity after which a paired device or node is listed as stale by `devices list` and `nodes status`, and may be archived by `devices prune --stale`. Activity is the latest of the record's last-active time, any device token's last use, approval, and first registration. A connected device is never stale. Default `90`.
> * `gateway.devices.neverUsedAfterDays`: days after approval with no recorded activity (no connection, no token use) after which a paired device counts as never used and is offered by `devices prune --never-used` (dry-run until `--yes`; nothing is archived automatically). Default `7`.
> * `gateway.devices.activityIntervalMinutes`: minutes between last-active writes for a connection that stays open. Connect and disconnect always write. Default `5`. Separately, a device token's `lastUsedAtMs` is written at most once every 5 minutes (fixed).

### Session steering defaults

* `gateway.sessions.steer.defaultMode`: mode the `sessions.steer` RPC applies when the caller omits
  `mode`. One of `"inject"` (default), `"interrupt"`, `"queue"`. Deliberately independent of the
  session or channel queue mode: a client asking to steer never inherits collect or followup
  semantics from the channel.
* `gateway.sessions.steer.settleTimeoutMs`: how long `sessions.steer` with `mode: "interrupt"` waits
  for the aborted run to reach a terminal state before failing the call. Integer, `0` or more;
  default `15000`. The replacement turn is never started past this point, so a session cannot end
  up with two concurrent runs.

The web client always sends an explicit `mode` and never `interrupt`, so neither key changes what it
does. While a reply streams, Send adds the message to the current turn (`inject`); with a file
attached it sends `queue` instead, because `inject` refuses attachments. Send after reply sends
`queue`.

See [Gateway protocol](https://docs.wednesdayai.dev/next/admin/gateway/protocol.md) for the full `sessions.steer` request and response shape.

### OpenAI-compatible endpoints

* Chat Completions: disabled by default. Enable with `gateway.http.endpoints.chatCompletions.enabled: true`.
* Responses API: `gateway.http.endpoints.responses.enabled`.
* Responses URL-input hardening:
  * `gateway.http.endpoints.responses.maxUrlParts`
  * `gateway.http.endpoints.responses.files.urlAllowlist`
  * `gateway.http.endpoints.responses.images.urlAllowlist`
* Optional response hardening header:
  * `gateway.http.securityHeaders.strictTransportSecurity` (set only for HTTPS origins you control; see [Trusted Proxy Auth](https://docs.wednesdayai.dev/next/admin/gateway/trusted-proxy-auth.md#tls-termination-and-hsts))

### Multi-instance isolation

Run multiple gateways on one host with unique ports and state dirs:

```bash theme={"dark"}
OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
OPENCLAW_STATE_DIR=~/.openclaw-a \
wednesdayai gateway --port 19001
```

Convenience flags: `--dev` (uses `~/.openclaw-dev` + port `19001`), `--profile <name>` (uses `~/.openclaw-<name>`).

See [Multiple Gateways](https://docs.wednesdayai.dev/next/admin/gateway/multiple-gateways.md).

***

## Node Host Browser Proxy

```json5 theme={"dark"}
{
  nodeHost: {
    browserProxy: {
      enabled: true, // default: true
      // allowProfiles: ["openclaw", "work"],  // optional profile allowlist
    },
  },
}
```

* `enabled` (default: true) — enables the browser proxy on the node host. When a node host runs on a machine with a browser, the gateway can auto-route browser tool calls to that node.
* `allowProfiles` — optional allowlist of profile names exposed via the proxy. When omitted, all profiles are available.

Disable on the node: `nodeHost.browserProxy.enabled=false`.
Disable on the gateway: `gateway.nodes.browser.mode="off"`.

***

## Hooks

```json5 theme={"dark"}
{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    maxBodyBytes: 262144,
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
    allowedAgentIds: ["hooks", "main"],
    presets: ["gmail"],
    transformsDir: "~/.openclaw/hooks/transforms",
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "hooks",
        wakeMode: "now",
        name: "Gmail",
        sessionKey: "hook:gmail:{{messages[0].id}}",
        messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}",
        deliver: true,
        channel: "last",
        model: "openai/gpt-5.2-mini",
      },
    ],
  },
}
```

Auth: `Authorization: Bearer <token>` or `x-openclaw-token: <token>`.

**Endpoints:**

* `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }`
* `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }`
  * `sessionKey` from request payload is accepted only when `hooks.allowRequestSessionKey=true` (default: `false`).
* `POST /hooks/<name>` → resolved via `hooks.mappings`

> [accordion] Mapping details
>
> * `match.path` matches sub-path after `/hooks` (e.g. `/hooks/gmail` → `gmail`).
> * `match.source` matches a payload field for generic paths.
> * Templates like `{{messages[0].subject}}` read from the payload.
> * `transform` can point to a JS/TS module returning a hook action.
>   * `transform.module` must be a relative path and stays within `hooks.transformsDir` (absolute paths and traversal are rejected).
> * `agentId` routes to a specific agent; unknown IDs fall back to default.
> * `allowedAgentIds`: restricts explicit routing (`*` or omitted = allow all, `[]` = deny all).
> * `defaultSessionKey`: optional fixed session key for hook agent runs without explicit `sessionKey`.
> * `allowRequestSessionKey`: allow `/hooks/agent` callers to set `sessionKey` (default: `false`).
> * `allowedSessionKeyPrefixes`: optional prefix allowlist for explicit `sessionKey` values (request + mapping), e.g. `["hook:"]`.
> * `deliver: true` sends final reply to a channel; `channel` defaults to `last`.
> * `model` overrides LLM for this hook run (must be allowed if model catalog is set).

### Gmail integration

```json5 theme={"dark"}
{
  hooks: {
    gmail: {
      account: "openclaw@gmail.com",
      topic: "projects/<project-id>/topics/gog-gmail-watch",
      subscription: "gog-gmail-watch-push",
      pushToken: "shared-push-token",
      hookUrl: "http://127.0.0.1:18789/hooks/gmail",
      includeBody: true,
      maxBytes: 20000,
      renewEveryMinutes: 720,
      serve: { bind: "127.0.0.1", port: 8788, path: "/" },
      tailscale: { mode: "funnel", path: "/gmail-pubsub" },
      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
      thinking: "off",
    },
  },
}
```

* Gateway auto-starts `gog gmail watch serve` on boot when configured. Set `OPENCLAW_SKIP_GMAIL_WATCHER=1` to disable.
* Don't run a separate `gog gmail watch serve` alongside the Gateway.

***

## Canvas host

```json5 theme={"dark"}
{
  canvasHost: {
    root: "~/.openclaw/workspace/canvas",
    liveReload: true,
    // enabled: false, // or OPENCLAW_SKIP_CANVAS_HOST=1
  },
}
```

* Serves agent-editable HTML/CSS/JS and A2UI over HTTP under the Gateway port:
  * `http://<gateway-host>:<gateway.port>/__openclaw__/canvas/`
  * `http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/`
* Local-only: keep `gateway.bind: "loopback"` (default).
* Non-loopback binds: canvas routes require Gateway auth (token/password/trusted-proxy), same as other Gateway HTTP surfaces.
* Node WebViews typically don't send auth headers; after a node is paired and connected, the Gateway advertises node-scoped capability URLs for canvas/A2UI access.
* Capability URLs are bound to the active node WS session and expire quickly. IP-based fallback is not used.
* Injects live-reload client into served HTML.
* Auto-creates starter `index.html` when empty.
* Also serves A2UI at `/__openclaw__/a2ui/`.
* Changes require a gateway restart.
* Disable live reload for large directories or `EMFILE` errors.

***

## Discovery

### mDNS (Bonjour)

```json5 theme={"dark"}
{
  discovery: {
    mdns: {
      mode: "minimal", // minimal | full | off
    },
  },
}
```

* `minimal` (default): omit `cliPath` + `sshPort` from TXT records.
* `full`: include `cliPath` + `sshPort`.
* Hostname defaults to `openclaw`. Override with `OPENCLAW_MDNS_HOSTNAME`.

### Wide-area (DNS-SD)

```json5 theme={"dark"}
{
  discovery: {
    wideArea: { enabled: true },
  },
}
```

Writes a unicast DNS-SD zone under `~/.openclaw/dns/`. For cross-network discovery, pair with a DNS server (CoreDNS recommended) + Tailscale split DNS.

Setup: `wednesdayai dns setup --apply`.

***

## Environment

### `env` (inline env vars)

```json5 theme={"dark"}
{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}
```

* Inline env vars are only applied if the process env is missing the key.
* `.env` files: CWD `.env` + `~/.openclaw/.env` (neither overrides existing vars).
* `shellEnv`: imports missing expected keys from your login shell profile.
* See [Environment](https://docs.wednesdayai.dev/next/users/help/environment.md) for full precedence.

### Env var substitution

Reference env vars in any config string with `${VAR_NAME}`:

```json5 theme={"dark"}
{
  gateway: {
    auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" },
  },
}
```

* Only uppercase names matched: `[A-Z_][A-Z0-9_]*`.
* Missing/empty vars throw an error at config load.
* Escape with `$${VAR}` for a literal `${VAR}`.
* Works with `$include`.

### Plugin and skill catalog variables

These environment variables control the remote catalog feeds behind
`wednesdayai plugins install <id>` and `wednesdayai skills install <id>`. Full list and
precedence: [Environment](https://docs.wednesdayai.dev/next/users/help/environment.md#plugin-and-skill-catalogs).

| Variable | Default | Purpose |
| - | - | - |
| `OPENCLAW_CATALOG_URL` | `https://raw.githubusercontent.com/ExpansionX/WednesdayAI-plugins/main/catalog.json` | Override the remote plugin catalog URL (operator mirror / airgap pinning) |
| `OPENCLAW_CATALOG_TTL_MS` | `3600000` (1 hour) | Remote catalog cache TTL in milliseconds (0 is rejected — falls back to default) |
| `OPENCLAW_CATALOG_REMOTE` | unset (enabled) | Set to `"0"` to disable all remote catalog fetching (airgap / mirror mode) |
| `OPENCLAW_SKILLS_CATALOG_URL` | `https://raw.githubusercontent.com/ExpansionX/WednesdayAI-skills/main/catalog.json` | Override the remote skills catalog URL |

With `OPENCLAW_CATALOG_REMOTE=0`, every feed fails open to the bundled offline snapshot and
bare catalog ids still install, verified against the snapshot pins.

***

## Secrets

Secret refs are additive: plaintext values still work.

### `SecretRef`

Use one object shape:

```json5 theme={"dark"}
{ source: "env" | "file" | "exec", provider: "default", id: "..." }
```

Validation:

* `provider` pattern: `^[a-z][a-z0-9_-]{0,63}$`
* `source: "env"` id pattern: `^[A-Z][A-Z0-9_]{0,127}$`
* `source: "file"` id: absolute JSON pointer (for example `"/providers/openai/apiKey"`)
* `source: "exec"` id pattern: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`

### Supported credential surface

* Canonical matrix: [SecretRef Credential Surface](https://docs.wednesdayai.dev/next/developers/reference/secretref-credential-surface.md)
* `secrets apply` targets supported `openclaw.json` credential paths.
* `auth-profiles.json` refs are included in runtime resolution and audit coverage.

### Secret providers config

```json5 theme={"dark"}
{
  secrets: {
    providers: {
      default: { source: "env" }, // optional explicit env provider
      filemain: {
        source: "file",
        path: "~/.openclaw/secrets.json",
        mode: "json",
        timeoutMs: 5000,
      },
      vault: {
        source: "exec",
        command: "/usr/local/bin/openclaw-vault-resolver",
        passEnv: ["PATH", "VAULT_ADDR"],
      },
    },
    defaults: {
      env: "default",
      file: "filemain",
      exec: "vault",
    },
  },
}
```

Notes:

* `file` provider supports `mode: "json"` and `mode: "singleValue"` (`id` must be `"value"` in singleValue mode).
* `exec` provider requires an absolute `command` path and uses protocol payloads on stdin/stdout.
* By default, symlink command paths are rejected. Set `allowSymlinkCommand: true` to allow symlink paths while validating the resolved target path.
* If `trustedDirs` is configured, the trusted-dir check applies to the resolved target path.
* `exec` child environment is minimal by default; pass required variables explicitly with `passEnv`.
* Secret refs are resolved at activation time into an in-memory snapshot, then request paths read the snapshot only.
* Active-surface filtering applies during activation: unresolved refs on enabled surfaces fail startup/reload, while inactive surfaces are skipped with diagnostics.

***

## Auth storage

```json5 theme={"dark"}
{
  auth: {
    profiles: {
      "anthropic:me@example.com": { provider: "anthropic", mode: "oauth", email: "me@example.com" },
      "anthropic:work": { provider: "anthropic", mode: "api_key" },
    },
    order: {
      anthropic: ["anthropic:me@example.com", "anthropic:work"],
    },
  },
}
```

* Per-agent profiles are stored at `<agentDir>/auth-profiles.json`.
* `auth-profiles.json` supports value-level refs (`keyRef` for `api_key`, `tokenRef` for `token`).
* Static runtime credentials come from in-memory resolved snapshots; legacy static `auth.json` entries are scrubbed when discovered.
* Legacy OAuth imports from `~/.openclaw/credentials/oauth.json`.
* See [OAuth](https://docs.wednesdayai.dev/next/developers/concepts/oauth.md).
* Secrets runtime behavior and `audit/configure/apply` tooling: [Secrets Management](https://docs.wednesdayai.dev/next/admin/gateway/secrets.md).

***

## Logging

```json5 theme={"dark"}
{
  logging: {
    level: "info", // silent | fatal | error | warn | info | debug | trace
    file: "/tmp/openclaw/openclaw.log",
    maxFileBytes: 10485760,
    maxBackups: 5,
    fileLogs: {
      defaults: {
        maxFileBytes: 10485760,
        maxBackups: 5,
        compress: "gzip", // gzip | false
        maxQueuedBytes: 1048576,
        mode: "jsonl", // jsonl | text
      },
      profiles: {
        "agents.rawStream": {
          maxFileBytes: 1048576,
          maxBackups: 2,
        },
        "extensions.voiceCall.calls": {
          compress: false,
        },
      },
    },
    consoleLevel: "info",
    consoleStyle: "pretty", // pretty | compact | json
    redactSensitive: "tools", // off | tools
    redactPatterns: ["\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1"],
  },
}
```

* Default log file: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`.
* Set `logging.file` for a stable path.
* `logging.maxFileBytes` and `logging.maxBackups` remain aliases for the `primary` file-log profile.
* `logging.fileLogs.defaults` applies shared file-log defaults for durable diagnostic and audit logs.
* `logging.fileLogs.profiles.<profileId>` overrides one named log. Supported built-in profiles:
  * `primary`: main `openclaw-YYYY-MM-DD.log` runtime log.
  * `cron.run`: cron run JSONL logs under `cron/runs/<jobId>.jsonl`.
  * `config.audit`: config write audit log at `logs/config-audit.jsonl`.
  * `hooks.command`: bundled command logger output at `logs/commands.log`.
  * `agents.rawStream`: PI raw stream diagnostic JSONL.
  * `extensions.learningCore`: learning-core active JSONL log.
  * `extensions.voiceCall.calls`: voice-call legacy `calls.jsonl` store.
* File-log profile fields: `file`, `maxFileBytes`, `maxBackups`, `compress`, `maxQueuedBytes`, `keepLines`, and `mode`.
* Default profile values are `maxFileBytes: 10485760`, `maxBackups: 5`, `compress: "gzip"`, `maxQueuedBytes: 1048576`, and `mode: "jsonl"`.
* `maxFileBytes` and `maxQueuedBytes` must be positive integers. `maxBackups` must be a non-negative integer; `0` means rotate by truncating without retaining backups.
* `compress: false` keeps plaintext numbered backups such as `.1`; `compress: "gzip"` writes `.1.gz` backups.
* Profile merge order is built-in defaults, `logging.fileLogs.defaults`, call-site defaults, primary legacy aliases for the `primary` profile, then `logging.fileLogs.profiles.<profileId>`.
* Path-indexed state logs keep their canonical file path so their readers and recovery paths stay coherent. For `cron.run`, `extensions.learningCore`, and `extensions.voiceCall.calls`, use profile fields such as `maxFileBytes`, `maxBackups`, `compress`, and `maxQueuedBytes`; `file` is intentionally ignored.
* `maxQueuedBytes` bounds queued in-memory writes per file-log writer. Non-strict writers drop new writes when the queue is full; strict writers reject so durability-sensitive callers can report the failure.
* Sessions and conversations are excluded from `logging.fileLogs`; transcript/session storage uses its own retention controls.
* `consoleLevel` bumps to `debug` when `--verbose`.

***

## CLI

```json5 theme={"dark"}
{
  cli: {
    banner: {
      taglineMode: "off", // random | default | off
    },
  },
}
```

* `cli.banner.taglineMode` controls banner tagline style:
  * `"random"` (default): rotating funny/seasonal taglines.
  * `"default"`: fixed neutral tagline (`All your chats, one WednesdayAI.`).
  * `"off"`: no tagline text (banner title/version still shown).
* To hide the entire banner (not just taglines), set env `OPENCLAW_HIDE_BANNER=1`.

***

## Wizard

Metadata written by CLI wizards (`onboard`, `configure`, `doctor`):

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

***

## Identity

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

Written by the macOS onboarding assistant. Derives defaults:

* `messages.ackReaction` from `identity.emoji` (falls back to 👀)
* `mentionPatterns` from `identity.name`/`identity.emoji`
* `avatar` accepts: workspace-relative path, `http(s)` URL, or `data:` URI
* `color` is optional and only affects the [web client](https://docs.wednesdayai.dev/next/admin/web/user-client.md); see
  [`agents.list[].identity.color`](#agentslistidentitycolor) for the palette and the
  `agents.defaults.models` advice

***

## Bridge (legacy, removed)

Current builds no longer include the TCP bridge. Nodes connect over the Gateway WebSocket. `bridge.*` keys are no longer part of the config schema (validation fails until removed; `wednesdayai doctor --fix` can strip unknown keys).

> [accordion] Legacy bridge config (historical reference)
>
> ```json theme={"dark"}
> {
>   "bridge": {
>     "enabled": true,
>     "port": 18790,
>     "bind": "tailnet",
>     "tls": {
>       "enabled": true,
>       "autoGenerate": true
>     }
>   }
> }
> ```

***

## Tasks

The background task pipeline (`tasks.*`: `enabled`, `dispatchConcurrency`,
`preemptionCeiling`, `budget`, `restartLoop`, `idle`, `schedule`) is documented with defaults
on [Task operations](https://docs.wednesdayai.dev/next/admin/gateway/tasks.md). The `tasks.idle` and `tasks.schedule` keys drive the
idle monitor consumed by plugins such as [Dream Cycle](https://docs.wednesdayai.dev/next/developers/plugins/dream-cycle).

***

## Cron

```json5 theme={"dark"}
{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs
    webhookToken: "replace-with-dedicated-token", // optional bearer token for outbound webhook auth
    sessionRetention: "24h", // duration string or false
    runLog: {
      maxBytes: "2mb", // default 2_000_000 bytes
      keepLines: 2000, // default 2000
    },
  },
}
```

* `sessionRetention`: how long to keep completed isolated cron run sessions before their index rows are tombstoned from the session store. Default: `24h`; set `false` to disable.
* `runLog.maxBytes`: max size per run log file (`cron/runs/<jobId>.jsonl`) before pruning. Default: `2_000_000` bytes.
* `runLog.keepLines`: newest lines retained when run-log pruning is triggered. Default: `2000`.
* `webhookToken`: bearer token used for cron webhook POST delivery (`delivery.mode = "webhook"`), if omitted no auth header is sent.
* `webhook`: deprecated legacy fallback webhook URL (http/https) used only for stored jobs that still have `notify: true`.

See [Cron Jobs](https://docs.wednesdayai.dev/next/users/automation/cron-jobs.md).

***

## Media model template variables

Template placeholders expanded in `tools.media.models[].args`:

| Variable | Description |
| - | - |
| `{{Body}}` | Full inbound message body |
| `{{RawBody}}` | Raw body (no history/sender wrappers) |
| `{{BodyStripped}}` | Body with group mentions stripped |
| `{{From}}` | Sender identifier |
| `{{To}}` | Destination identifier |
| `{{MessageSid}}` | Channel message id |
| `{{SessionId}}` | Current session UUID |
| `{{IsNewSession}}` | `"true"` when new session created |
| `{{MediaUrl}}` | Inbound media pseudo-URL |
| `{{MediaPath}}` | Local media path |
| `{{MediaType}}` | Media type (image/audio/document/…) |
| `{{Transcript}}` | Audio transcript |
| `{{Prompt}}` | Resolved media prompt for CLI entries |
| `{{MaxChars}}` | Resolved max output chars for CLI entries |
| `{{ChatType}}` | `"direct"` or `"group"` |
| `{{GroupSubject}}` | Group subject (best effort) |
| `{{GroupMembers}}` | Group members preview (best effort) |
| `{{SenderName}}` | Sender display name (best effort) |
| `{{SenderE164}}` | Sender phone number (best effort) |
| `{{Provider}}` | Provider hint (whatsapp, telegram, discord, etc.) |

***

## Config includes (`$include`)

Split config into multiple files:

```json5 theme={"dark"}
// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/mueller.json5", "./clients/schmidt.json5"],
  },
}
```

**Merge behavior:**

* Single file: replaces the containing object.
* Array of files: deep-merged in order (later overrides earlier).
* Sibling keys: merged after includes (override included values).
* Nested includes: up to 10 levels deep.
* Paths: resolved relative to the including file, but must stay inside the top-level config directory (`dirname` of `openclaw.json`). Absolute/`../` forms are allowed only when they still resolve inside that boundary.
* Errors: clear messages for missing files, parse errors, and circular includes.

***

*Related: [Configuration](https://docs.wednesdayai.dev/next/admin/gateway/configuration.md) · [Configuration Examples](https://docs.wednesdayai.dev/next/admin/gateway/configuration-examples.md) · [Doctor](https://docs.wednesdayai.dev/next/admin/gateway/doctor.md)*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.