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