Skip to main content

Configuration

WednesdayAI reads an optional 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 for every available field.
New to configuration? Start with wednesdayai onboard for interactive setup, or check out the Configuration Examples guide for complete copy-paste configs.

Minimal config

Editing config

Strict validation

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

Each channel has its own config section under channels.<provider>. See the dedicated channel page for setup steps:All channels share the same DM policy pattern:
Set the primary model and optional fallbacks:
  • 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 for switching models in chat and Model Failover for auth rotation and fallback behavior.
  • For custom/self-hosted providers, see Custom providers in the reference.
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 for per-channel details.
Group messages default to require mention. Configure patterns per agent:
  • Metadata mentions: native @-mentions (WhatsApp tap-to-mention, Telegram @bot, etc.)
  • Text patterns: regex patterns in mentionPatterns
  • See full reference for per-channel overrides and self-chat mode.
Sessions control conversation continuity and isolation:
  • 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 for scoping, identity links, and send policy.
  • See full reference for all fields.
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:
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).
  • 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 for ownership, backups, and the legacy upgrade path.
Run agent sessions in isolated Docker containers:
Build the image first: scripts/sandbox-setup.shSee Sandboxing for the full guide and full reference for all options.
  • 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 for the full guide.
  • 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 for feature overview and CLI examples.
Enable HTTP webhook endpoints on the Gateway:
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 for all mapping options and Gmail integration.
Run multiple isolated agents with separate workspaces and sessions:
See Multi-Agent and full reference for binding rules and per-agent access profiles.
Use $include to organize large configs:
  • 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

What hot-applies vs what needs a restart

Most fields hot-apply without downtime. In hybrid mode, restart-required changes are handled automatically.
gateway.reload and gateway.remote are exceptions — changing them does not trigger a restart.
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.
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.
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)

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.
Validates + writes the full config and restarts the Gateway in one step.
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.
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.
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.

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:
If enabled and expected keys aren’t set, WednesdayAI runs your login shell and imports only the missing keys:
Env var equivalent: OPENCLAW_LOAD_SHELL_ENV=1
Reference env vars in any config string value with ${VAR_NAME}:
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"
For fields that support SecretRef objects, you can use:
SecretRef details (including secrets.providers for env/file/exec) are in Secrets Management. Supported credential paths are listed in SecretRef Credential Surface.
See Environment for full precedence and sources.

Full reference

For the complete field-by-field reference, see Configuration Reference.
Related: Configuration Examples · Configuration Reference · Config writes · Doctor