> ## 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

# Configuration

WednesdayAI reads an optional **JSON5** (JSON5 supports comments and trailing commas) config from `~/.openclaw/openclaw.json`.

If the file is missing, WednesdayAI uses safe defaults. Common reasons to add a config:

* Connect channels and control who can message the bot
* Set models, tools, sandboxing, or automation (cron, hooks)
* Tune sessions, media, networking, or UI

See the [full reference](https://docs.wednesdayai.dev/next/admin/gateway/configuration-reference.md) for every available field.

> [!TIP]
>
> **New to configuration?** Start with `wednesdayai onboard` for interactive setup, or check out the [Configuration Examples](https://docs.wednesdayai.dev/next/admin/gateway/configuration-examples.md) guide for complete copy-paste configs.

## Minimal config

```json5 theme={"dark"}
// ~/.openclaw/openclaw.json
{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}
```

## Editing config

> [tab] Interactive wizard
>
> ```bash theme={"dark"}
> wednesdayai onboard       # full setup wizard
> wednesdayai configure     # config wizard
> ```

> [tab] CLI (one-liners)
>
> ```bash theme={"dark"}
> wednesdayai config get agents.defaults.workspace
> wednesdayai config set agents.defaults.heartbeat.every "2h"
> wednesdayai config unset tools.web.search.apiKey
> ```

> [tab] Control UI
>
> Open [http://127.0.0.1:18789](http://127.0.0.1:18789) and use the **Settings** screen (**Configure → Settings**).
> The console renders a form from the config schema, with a **Raw JSON5** editor as an escape hatch.

> [tab] Direct edit
>
> Edit `~/.openclaw/openclaw.json` directly. The Gateway watches the file and applies changes automatically (see [hot reload](#config-hot-reload)).

## Strict validation

> [!WARNING]
>
> WednesdayAI only accepts configurations that fully match the schema. Unknown keys, malformed types, or invalid values cause the Gateway to **refuse to start**. The only root-level exception is `$schema` (string), so editors can attach JSON Schema metadata.

When validation fails:

* The Gateway does not boot
* Only diagnostic commands work (`wednesdayai doctor`, `wednesdayai logs`, `wednesdayai health`, `wednesdayai status`)
* Run `wednesdayai doctor` to see exact issues
* Run `wednesdayai doctor --fix` (or `--yes`) to apply repairs

## Common tasks

> [accordion] Set up a channel (WhatsApp, Telegram, Discord, etc.)
>
> Each channel has its own config section under `channels.<provider>`. See the dedicated channel page for setup steps:
>
> * [WhatsApp](https://docs.wednesdayai.dev/next/admin/channels/whatsapp.md) — `channels.whatsapp`
> * [Telegram](https://docs.wednesdayai.dev/next/admin/channels/telegram.md) — `channels.telegram`
> * [Discord](https://docs.wednesdayai.dev/next/admin/channels/discord.md) — `channels.discord`
> * [Slack](https://docs.wednesdayai.dev/next/admin/channels/slack.md) — `channels.slack`
> * [Signal](https://docs.wednesdayai.dev/next/admin/channels/signal.md) — `channels.signal`
> * [iMessage](https://docs.wednesdayai.dev/next/admin/channels/imessage.md) — `channels.imessage`
> * [Google Chat](https://docs.wednesdayai.dev/next/admin/channels/googlechat.md) — `channels.googlechat`
> * [Mattermost](https://docs.wednesdayai.dev/next/admin/channels/mattermost.md) — `channels.mattermost`
> * [MS Teams](https://docs.wednesdayai.dev/next/admin/channels/msteams.md) — `channels.msteams`
>
> All channels share the same DM policy pattern:
>
> ```json5 theme={"dark"}
> {
>   channels: {
>     telegram: {
>       enabled: true,
>       botToken: "123:abc",
>       dmPolicy: "pairing",   // pairing | allowlist | open | disabled
>       allowFrom: ["tg:123"], // only for allowlist/open
>     },
>   },
> }
> ```

> [accordion] Choose and configure models
>
> Set the primary model and optional fallbacks:
>
> ```json5 theme={"dark"}
> {
>   agents: {
>     defaults: {
>       model: {
>         primary: "anthropic/claude-sonnet-4-5",
>         fallbacks: ["openai/gpt-5.2"],
>       },
>       models: {
>         "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
>         "openai/gpt-5.2": { alias: "GPT" },
>       },
>     },
>   },
> }
> ```
>
> * `agents.defaults.models` defines the model catalog and acts as the allowlist for `/model`.
> * Model refs use `provider/model` format (e.g. `anthropic/claude-opus-4-6`).
> * `agents.defaults.imageMaxDimensionPx` controls transcript/tool image downscaling (default `1200`); lower values usually reduce vision-token usage on screenshot-heavy runs.
> * See [Models CLI](https://docs.wednesdayai.dev/next/developers/concepts/models.md) for switching models in chat and [Model Failover](https://docs.wednesdayai.dev/next/developers/concepts/model-failover.md) for auth rotation and fallback behavior.
> * For custom/self-hosted providers, see [Custom providers](https://docs.wednesdayai.dev/next/admin/gateway/configuration-reference.md#custom-providers-and-base-urls) in the reference.

> [accordion] Control who can message the bot
>
> DM access is controlled per channel via `dmPolicy`:
>
> * `"pairing"` (default): unknown senders get a one-time pairing code to approve
> * `"allowlist"`: only senders in `allowFrom` (or the paired allow store)
> * `"open"`: allow all inbound DMs (requires `allowFrom: ["*"]`)
> * `"disabled"`: ignore all DMs
>
> For groups, use `groupPolicy` + `groupAllowFrom` or channel-specific allowlists.
>
> See the [full reference](https://docs.wednesdayai.dev/next/admin/gateway/configuration-reference.md#dm-and-group-access) for per-channel details.

> [accordion] Set up group chat mention gating
>
> Group messages default to **require mention**. Configure patterns per agent:
>
> ```json5 theme={"dark"}
> {
>   agents: {
>     list: [
>       {
>         id: "main",
>         groupChat: {
>           mentionPatterns: ["@openclaw", "openclaw"],
>         },
>       },
>     ],
>   },
>   channels: {
>     whatsapp: {
>       groups: { "*": { requireMention: true } },
>     },
>   },
> }
> ```
>
> * **Metadata mentions**: native @-mentions (WhatsApp tap-to-mention, Telegram @bot, etc.)
> * **Text patterns**: regex patterns in `mentionPatterns`
> * See [full reference](https://docs.wednesdayai.dev/next/admin/gateway/configuration-reference.md#group-chat-mention-gating) for per-channel overrides and self-chat mode.

> [accordion] Configure sessions and resets
>
> Sessions control conversation continuity and isolation:
>
> ```json5 theme={"dark"}
> {
>   session: {
>     dmScope: "per-channel-peer",  // recommended for multi-user
>     threadBindings: {
>       enabled: true,
>       idleHours: 24,
>       maxAgeHours: 0,
>     },
>     reset: {
>       mode: "daily",
>       atHour: 4,
>       idleMinutes: 120,
>     },
>   },
> }
> ```
>
> * `dmScope`: `main` (shared) | `per-peer` | `per-channel-peer` | `per-account-channel-peer`
> * `threadBindings`: global defaults for thread-bound session routing (Discord supports `/focus`, `/unfocus`, `/agents`, `/session idle`, and `/session max-age`).
> * See [Session Management](https://docs.wednesdayai.dev/next/developers/concepts/session.md) for scoping, identity links, and send policy.
> * See [full reference](https://docs.wednesdayai.dev/next/admin/gateway/configuration-reference.md#session) for all fields.

> [accordion] Configure session storage backend
>
> By default, sessions and conversation history are stored in a local SQLite database at
> `<state-dir>/sessions.db` (normally `~/.openclaw/sessions.db`). SQL session storage is the only
> session storage: `backend` selects SQLite (default) or Postgres, and there is no JSONL backend
> or file fallback. Override the SQLite path or switch to Postgres:
>
> ```json5 theme={"dark"}
> {
>   session: {
>     storage: {
>       backend: "sqlite", // sqlite (default) | postgres
>       sqlitePath: "/var/lib/openclaw/sessions.db", // optional override; defaults to <state-dir>/sessions.db
>       migration: { validateOnStart: true },
>     },
>   },
> }
> ```
>
> ```json5 theme={"dark"}
> {
>   session: {
>     storage: {
>       backend: "postgres",
>       databaseUrl: "${SESSION_DATABASE_URL}",
>       cache: "redis",
>       redisUrl: "${REDIS_URL}",
>       migration: { validateOnStart: true },
>     },
>   },
> }
> ```
>
> Key behaviors:
>
> * `backend: "sqlite"` (default) stores everything in one SQLite database with WAL durability;
>   `backend: "postgres"` stores it in Postgres. `cache: "redis"` (Postgres only) adds a
>   write-through hot cache that is never authoritative — the database always wins.
> * Legacy file-backend keys (`session.storage.backend: "fs-jsonl"`, `session.storage.mode`,
>   `session.storage.fallbackToJsonlOnError`) are retired: configs that still set them are
>   migrated automatically on load and the gateway logs the change at start. Existing JSONL
>   history is imported automatically (see
>   [Session Management / Upgrading from JSON session files](https://docs.wednesdayai.dev/next/developers/concepts/session.md#upgrading-from-json-session-files)).
> * `migration.validateOnStart`: when `true`, the gateway validates schema and data integrity at
>   startup before serving.
> * The gateway converges the database schema on every startup: tables and indexes are created
>   with `IF NOT EXISTS`, and columns added in newer versions are added idempotently — PostgreSQL
>   emits `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`, while SQLite checks `PRAGMA table_info` and
>   issues a plain `ALTER TABLE ... ADD COLUMN` when the column is missing. Convergence is
>   additive only; existing columns and data are never dropped, renamed, or re-typed, and no
>   manual SQL is required.
> * SQLite options under `storage.sqlite`: `wal`, `busyTimeoutMs`, `walAutocheckpointPages`.
> * Redis options under `storage.redis`: `keyPrefix`, `ttlSeconds`.
> * Postgres options under `storage.postgres`: `connectionTimeoutMs` (default 10000; 0 = no limit).
> * `session.storage.recovery.startupProbeTimeoutMs` (default `600s`) bounds how long the gateway
>   waits for session storage to open at startup before exiting. A failed or timed-out start is
>   fatal (the process exits with the cause and the service manager restarts it); the gateway
>   never serves a degraded file view.
> * Exactly one process owns the database at a time (the gateway, or one CLI command when no
>   gateway runs). CLI storage commands go over the gateway RPC while it runs.
>
> See [Session Management / Session storage](https://docs.wednesdayai.dev/next/developers/concepts/session.md#session-storage) for ownership,
> backups, and the legacy upgrade path.

> [accordion] Enable sandboxing
>
> Run agent sessions in isolated Docker containers:
>
> ```json5 theme={"dark"}
> {
>   agents: {
>     defaults: {
>       sandbox: {
>         mode: "non-main",  // off | non-main | all
>         scope: "agent",    // session | agent | shared
>       },
>     },
>   },
> }
> ```
>
> Build the image first: `scripts/sandbox-setup.sh`
>
> See [Sandboxing](https://docs.wednesdayai.dev/next/admin/gateway/sandboxing.md) for the full guide and [full reference](https://docs.wednesdayai.dev/next/admin/gateway/configuration-reference.md#sandbox) for all options.

> [accordion] Set up heartbeat (periodic check-ins)
>
> ```json5 theme={"dark"}
> {
>   agents: {
>     defaults: {
>       heartbeat: {
>         every: "30m",
>         target: "last",
>       },
>     },
>   },
> }
> ```
>
> * `every`: duration string (`30m`, `2h`). Set `0m` to disable.
> * `target`: `last` | `whatsapp` | `telegram` | `discord` | `webchat` | `none`
> * `directPolicy`: `allow` (default) or `block` for DM-style heartbeat targets
> * See [Heartbeat](https://docs.wednesdayai.dev/next/admin/gateway/heartbeat.md) for the full guide.

> [accordion] Configure cron jobs
>
> ```json5 theme={"dark"}
> {
>   cron: {
>     enabled: true,
>     maxConcurrentRuns: 2,
>     sessionRetention: "24h",
>     runLog: {
>       maxBytes: "2mb",
>       keepLines: 2000,
>     },
>   },
> }
> ```
>
> * `sessionRetention`: tombstone completed isolated run session index rows from the session store (default `24h`; set `false` to disable).
> * `runLog`: prune `cron/runs/<jobId>.jsonl` by size and retained lines.
> * See [Cron jobs](https://docs.wednesdayai.dev/next/users/automation/cron-jobs.md) for feature overview and CLI examples.

> [accordion] Set up webhooks (hooks)
>
> Enable HTTP webhook endpoints on the Gateway:
>
> ```json5 theme={"dark"}
> {
>   hooks: {
>     enabled: true,
>     token: "shared-secret",
>     path: "/hooks",
>     defaultSessionKey: "hook:ingress",
>     allowRequestSessionKey: false,
>     allowedSessionKeyPrefixes: ["hook:"],
>     mappings: [
>       {
>         match: { path: "gmail" },
>         action: "agent",
>         agentId: "main",
>         deliver: true,
>       },
>     ],
>   },
> }
> ```
>
> Security note:
>
> * Treat all hook/webhook payload content as untrusted input.
> * Keep unsafe-content bypass flags disabled (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`) unless doing tightly scoped debugging.
> * For hook-driven agents, prefer strong modern model tiers and strict tool policy (for example messaging-only plus sandboxing where possible).
>
> See [full reference](https://docs.wednesdayai.dev/next/admin/gateway/configuration-reference.md#hooks) for all mapping options and Gmail integration.

> [accordion] Configure multi-agent routing
>
> Run multiple isolated agents with separate workspaces and sessions:
>
> ```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" } },
>   ],
> }
> ```
>
> See [Multi-Agent](https://docs.wednesdayai.dev/next/developers/concepts/multi-agent.md) and [full reference](https://docs.wednesdayai.dev/next/admin/gateway/configuration-reference.md#multi-agent-routing) for binding rules and per-agent access profiles.

> [accordion] Split config into multiple files (\$include)
>
> Use `$include` to organize large configs:
>
> ```json5 theme={"dark"}
> // ~/.openclaw/openclaw.json
> {
>   gateway: { port: 18789 },
>   agents: { $include: "./agents.json5" },
>   broadcast: {
>     $include: ["./clients/a.json5", "./clients/b.json5"],
>   },
> }
> ```
>
> * **Single file**: replaces the containing object
> * **Array of files**: deep-merged in order (later wins)
> * **Sibling keys**: merged after includes (override included values)
> * **Nested includes**: supported up to 10 levels deep
> * **Relative paths**: resolved relative to the including file
> * **Error handling**: clear errors for missing files, parse errors, and circular includes

## Config hot reload

The Gateway watches `~/.openclaw/openclaw.json` and applies changes automatically — no manual restart needed for most settings.

### Reload modes

| Mode | Behavior |
| - | - |
| **`hybrid`** (default) | Hot-applies safe changes instantly. Automatically restarts for critical ones. |
| **`hot`** | Hot-applies safe changes only. Logs a warning when a restart is needed — you handle it. |
| **`restart`** | Restarts the Gateway on any config change, safe or not. |
| **`off`** | Disables file watching. Changes take effect on the next manual restart. |

```json5 theme={"dark"}
{
  gateway: {
    reload: { mode: "hybrid", debounceMs: 300 },
  },
}
```

### What hot-applies vs what needs a restart

Most fields hot-apply without downtime. In `hybrid` mode, restart-required changes are handled automatically.

| Category | Fields | Restart needed? |
| - | - | - |
| Channels | `channels.*`, `web` (WhatsApp) — all built-in and extension channels | No |
| Agent & models | `agent`, `agents`, `models`, `routing` | No |
| Automation | `hooks`, `cron`, `agent.heartbeat` | No |
| Sessions & messages | `session`, `messages` | No |
| Tools & media | `tools`, `browser`, `skills`, `audio`, `talk` | No |
| UI & misc | `ui`, `logging`, `identity`, `bindings` | No |
| Inbox | `inbox.owners` (account ↔ person bindings) | No |
| Gateway server | `gateway.*` (port, bind, auth, tailscale, TLS, HTTP) | **Yes** |
| Infrastructure | `discovery`, `canvasHost`, `plugins` | **Yes** |
| Storage | `storage` (config domain backends) | **Yes** |

> [!NOTE]
>
> `gateway.reload` and `gateway.remote` are exceptions — changing them does **not** trigger a restart.

> [!NOTE]
>
> **`inbox.owners` is a no-op reload, not a hot-apply.** Changing it never restarts the gateway,
> but the running gateway keeps the bindings it loaded at startup: bind accounts with
> `wednesdayai inbox owners bind` (the authoritative row applies immediately and the config seed
> is kept in sync); a hand edit of `openclaw.json` applies at the next gateway start.

> [!NOTE]
>
> **Plugin install records restart once per batch.** Installing or updating plugins rewrites
> `plugins.installs.<id>` once per plugin. In `hybrid` and `restart` mode the gateway waits until
> no install record has changed for 60 seconds, then restarts once to load all the new plugin code.
> Any other restart-required change restarts the gateway immediately and loads the pending
> installs with it.

> [!NOTE]
>
> **Per-agent entries are an exception to the `agents` row.** `agents.defaults.heartbeat` and
> `agents.defaults.model` are applied in process (they trigger a `restart-heartbeat` action), but
> edits under `agents.list[]` — including `agents.list[].heartbeat.*` — collapse to the single
> `agents.list` path, which is treated as a no-op. They are neither applied in process nor flagged
> as needing a restart, so the heartbeat runner keeps its startup snapshot. Restart the gateway
> after editing a per-agent heartbeat.

## Config RPC (programmatic updates)

> [!NOTE]
>
> Control-plane write RPCs (`config.apply`, `config.patch`, `update.run`) are rate-limited to **3 requests per 60 seconds** per `deviceId+clientIp`. When limited, the RPC returns `UNAVAILABLE` with `retryAfterMs`.

> [accordion] config.apply (full replace)
>
> Validates + writes the full config and restarts the Gateway in one step.
>
> > [!WARNING]
> >
> > `config.apply` replaces the **entire config**. Use `config.patch` for partial updates, or `wednesdayai config set` for single keys. A document that drops top-level keys without listing them in `allowTopLevelKeyRemoval` is refused (`INVALID_REQUEST`, `details.code: CONFIG_WRITE_REFUSED`) and the on-disk file is left unchanged. Agents cannot call `config.apply` unless you opt in. See [Config writes](https://docs.wednesdayai.dev/next/admin/gateway/config-writes.md).
>
> Params:
>
> * `raw` (string) — JSON5 payload for the entire config
> * `baseHash` (optional) — config hash from `config.get` (required when config exists)
> * `allowTopLevelKeyRemoval` (optional string\[]) — top-level keys this write may delete; omitted means none. Payload diffs do not grant removals.
> * `sessionKey` (optional) — session key for the post-restart wake-up ping
> * `note` (optional) — note for the restart sentinel
> * `restartDelayMs` (optional) — delay before restart (default 2000)
>
> Restart requests are coalesced while one is already pending/in-flight, and a 30-second cooldown applies between restart cycles.
>
> ```bash theme={"dark"}
> wednesdayai gateway call config.get --params '{}'  # capture payload.hash
> wednesdayai gateway call config.apply --params '{
>   "raw": "{ agents: { defaults: { workspace: \"~/.openclaw/workspace\" } } }",
>   "baseHash": "<hash>",
>   "sessionKey": "agent:main:whatsapp:dm:+15555550123"
> }'
> ```

> [accordion] config.patch (partial update)
>
> Merges a partial update into the existing config (JSON merge patch semantics):
>
> * Objects merge recursively
> * `null` deletes a key
> * Arrays replace
>
> Params:
>
> * `raw` (string) — JSON5 with just the keys to change
> * `baseHash` (required) — config hash from `config.get`
> * `allowTopLevelKeyRemoval` (optional string\[]) — same as `config.apply`; required only if the patch removes a top-level key (for example `null` at the top level)
> * `sessionKey`, `note`, `restartDelayMs` — same as `config.apply`
>
> Restart behavior matches `config.apply`: coalesced pending restarts plus a 30-second cooldown between restart cycles.
>
> ```bash theme={"dark"}
> wednesdayai gateway call config.patch --params '{
>   "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
>   "baseHash": "<hash>"
> }'
> ```

## Environment variables

WednesdayAI reads env vars from the parent process plus:

* `.env` from the current working directory (if present)
* `~/.openclaw/.env` (global fallback)

Neither file overrides existing env vars. You can also set inline env vars in config:

```json5 theme={"dark"}
{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}
```

> [accordion] Shell env import (optional)
>
> If enabled and expected keys aren't set, WednesdayAI runs your login shell and imports only the missing keys:
>
> ```json5 theme={"dark"}
> {
>   env: {
>     shellEnv: { enabled: true, timeoutMs: 15000 },
>   },
> }
> ```
>
> Env var equivalent: `OPENCLAW_LOAD_SHELL_ENV=1`

> [accordion] Env var substitution in config values
>
> Reference env vars in any config string value with `${VAR_NAME}`:
>
> ```json5 theme={"dark"}
> {
>   gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
>   models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
> }
> ```
>
> Rules:
>
> * Only uppercase names matched: `[A-Z_][A-Z0-9_]*`
> * Missing/empty vars throw an error at load time
> * Escape with `$${VAR}` for literal output
> * Works inside `$include` files
> * Inline substitution: `"${BASE}/v1"` → `"https://api.example.com/v1"`

> [accordion] Secret refs (env, file, exec)
>
> For fields that support SecretRef objects, you can use:
>
> ```json5 theme={"dark"}
> {
>   models: {
>     providers: {
>       openai: { apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" } },
>     },
>   },
>   skills: {
>     entries: {
>       "nano-banana-pro": {
>         apiKey: {
>           source: "file",
>           provider: "filemain",
>           id: "/skills/entries/nano-banana-pro/apiKey",
>         },
>       },
>     },
>   },
>   channels: {
>     googlechat: {
>       serviceAccountRef: {
>         source: "exec",
>         provider: "vault",
>         id: "channels/googlechat/serviceAccount",
>       },
>     },
>   },
> }
> ```
>
> SecretRef details (including `secrets.providers` for `env`/`file`/`exec`) are in [Secrets Management](https://docs.wednesdayai.dev/next/admin/gateway/secrets.md).
> Supported credential paths are listed in [SecretRef Credential Surface](https://docs.wednesdayai.dev/next/developers/reference/secretref-credential-surface.md).

See [Environment](https://docs.wednesdayai.dev/next/users/help/environment.md) for full precedence and sources.

## Full reference

For the complete field-by-field reference, see **[Configuration Reference](https://docs.wednesdayai.dev/next/admin/gateway/configuration-reference.md)**.

***

*Related: [Configuration Examples](https://docs.wednesdayai.dev/next/admin/gateway/configuration-examples.md) · [Configuration Reference](https://docs.wednesdayai.dev/next/admin/gateway/configuration-reference.md) · [Config writes](https://docs.wednesdayai.dev/next/admin/gateway/config-writes.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.