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
Minimal config
Editing config
- Interactive wizard
- CLI (one-liners)
- Control UI
- Direct edit
Strict validation
When validation fails:- The Gateway does not boot
- Only diagnostic commands work (
wednesdayai doctor,wednesdayai logs,wednesdayai health,wednesdayai status) - Run
wednesdayai doctorto see exact issues - Run
wednesdayai doctor --fix(or--yes) to apply repairs
Common tasks
Set up a channel (WhatsApp, Telegram, Discord, etc.)
Set up a channel (WhatsApp, Telegram, Discord, etc.)
channels.<provider>. See the dedicated channel page for setup steps:- WhatsApp —
channels.whatsapp - Telegram —
channels.telegram - Discord —
channels.discord - Slack —
channels.slack - Signal —
channels.signal - iMessage —
channels.imessage - Google Chat —
channels.googlechat - Mattermost —
channels.mattermost - MS Teams —
channels.msteams
Choose and configure models
Choose and configure models
agents.defaults.modelsdefines the model catalog and acts as the allowlist for/model.- Model refs use
provider/modelformat (e.g.anthropic/claude-opus-4-6). agents.defaults.imageMaxDimensionPxcontrols transcript/tool image downscaling (default1200); 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.
Control who can message the bot
Control who can message the bot
dmPolicy:"pairing"(default): unknown senders get a one-time pairing code to approve"allowlist": only senders inallowFrom(or the paired allow store)"open": allow all inbound DMs (requiresallowFrom: ["*"])"disabled": ignore all DMs
groupPolicy + groupAllowFrom or channel-specific allowlists.See the full reference for per-channel details.Set up group chat mention gating
Set up group chat mention gating
- 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.
Configure sessions and resets
Configure sessions and resets
dmScope:main(shared) |per-peer|per-channel-peer|per-account-channel-peerthreadBindings: 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.
Configure session storage backend
Configure session storage backend
<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: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: whentrue, 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 emitsALTER TABLE ... ADD COLUMN IF NOT EXISTS, while SQLite checksPRAGMA table_infoand issues a plainALTER TABLE ... ADD COLUMNwhen 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(default600s) 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.
Enable sandboxing
Enable sandboxing
scripts/sandbox-setup.shSee Sandboxing for the full guide and full reference for all options.Set up heartbeat (periodic check-ins)
Set up heartbeat (periodic check-ins)
every: duration string (30m,2h). Set0mto disable.target:last|whatsapp|telegram|discord|webchat|nonedirectPolicy:allow(default) orblockfor DM-style heartbeat targets- See Heartbeat for the full guide.
Configure cron jobs
Configure cron jobs
sessionRetention: tombstone completed isolated run session index rows from the session store (default24h; setfalseto disable).runLog: prunecron/runs/<jobId>.jsonlby size and retained lines.- See Cron jobs for feature overview and CLI examples.
Set up webhooks (hooks)
Set up webhooks (hooks)
- 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).
Configure multi-agent routing
Configure multi-agent routing
Split config into multiple files ($include)
Split config into multiple files ($include)
$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. Inhybrid 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.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.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)
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.config.apply (full replace)
config.apply (full replace)
raw(string) — JSON5 payload for the entire configbaseHash(optional) — config hash fromconfig.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 pingnote(optional) — note for the restart sentinelrestartDelayMs(optional) — delay before restart (default 2000)
config.patch (partial update)
config.patch (partial update)
- Objects merge recursively
nulldeletes a key- Arrays replace
raw(string) — JSON5 with just the keys to changebaseHash(required) — config hash fromconfig.getallowTopLevelKeyRemoval(optional string[]) — same asconfig.apply; required only if the patch removes a top-level key (for examplenullat the top level)sessionKey,note,restartDelayMs— same asconfig.apply
config.apply: coalesced pending restarts plus a 30-second cooldown between restart cycles.Environment variables
WednesdayAI reads env vars from the parent process plus:.envfrom the current working directory (if present)~/.openclaw/.env(global fallback)
Shell env import (optional)
Shell env import (optional)
OPENCLAW_LOAD_SHELL_ENV=1Env var substitution in config values
Env var substitution in config values
${VAR_NAME}:- 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
$includefiles - Inline substitution:
"${BASE}/v1"→"https://api.example.com/v1"
Secret refs (env, file, exec)
Secret refs (env, file, exec)
secrets.providers for env/file/exec) are in Secrets Management.
Supported credential paths are listed in SecretRef Credential Surface.Full reference
For the complete field-by-field reference, see Configuration Reference.Related: Configuration Examples · Configuration Reference · Config writes · Doctor