Configuration Reference
Every field available in~/.openclaw/openclaw.json. For a task-oriented overview, see Configuration.
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 (unlessenabled: false).
DM and group access
All channels support DM policies and group policies: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
Usechannels.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).
Channel defaults and heartbeat
Usechannels.defaults for shared group-policy and heartbeat behavior across providers:
channels.defaults.groupPolicy: fallback group policy when a provider-levelgroupPolicyis 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.
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.
Multi-account WhatsApp
Multi-account WhatsApp
- Outbound commands default to account
defaultif present; otherwise the first configured account id (sorted). - Optional
channels.whatsapp.defaultAccountoverrides that fallback default account selection when it matches a configured account id. - Legacy single-account Baileys auth dir is migrated by
wednesdayai doctorintowhatsapp/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
- Bot token:
channels.telegram.botTokenorchannels.telegram.tokenFile, withTELEGRAM_BOT_TOKENas fallback for the default account. - Multi-bot fleet: define
channels.telegram.accounts.<id>with account-levelbotTokenortokenFilevalues. 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 asconflicted. - 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.defaultAccountoverrides default account selection when it matches a configured account id. configWrites: falseblocks 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.
- Full fleet operations guide: Telegram multi-bot fleet.
Discord
- Token:
channels.discord.token, withDISCORD_BOT_TOKENas fallback for the default account. - Optional
channels.discord.defaultAccountoverrides default account selection when it matches a configured account id. - Use
user:<id>(DM) orchannel:<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: trueenables them (own messages still filtered). maxLinesPerMessage(default 17) splits tall messages even when under 2000 chars.channels.discord.threadBindingscontrols 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 (0disables)maxAgeHours: Discord override for hard max age in hours (0disables)spawnSubagentSessions: opt-in switch forsessions_spawn({ thread: true })auto thread creation/binding
channels.discord.ui.components.accentColorsets the accent color for Discord components v2 containers.channels.discord.voiceenables Discord voice channel conversations and optional auto-join + TTS overrides.channels.discord.voice.daveEncryptionandchannels.discord.voice.decryptionFailureTolerancepass through to@discordjs/voiceDAVE options (trueand24by default).- WednesdayAI additionally attempts voice receive recovery by leaving/rejoining a voice session after repeated decrypt failures.
channels.discord.streamingis the canonical stream mode key. LegacystreamModeand booleanstreamingvalues are auto-migrated.channels.discord.dangerouslyAllowNameMatchingre-enables mutable name/tag matching (break-glass compatibility mode).
off (none), own (bot’s messages, default), all (all messages), allowlist (from guilds.<id>.users on all messages).
Google Chat
- Service account JSON: inline (
serviceAccount) or file-based (serviceAccountFile). - Service account SecretRef is also supported (
serviceAccountRef). - Env fallbacks:
GOOGLE_CHAT_SERVICE_ACCOUNTorGOOGLE_CHAT_SERVICE_ACCOUNT_FILE. - Use
spaces/<spaceId>orusers/<userId>for delivery targets. channels.googlechat.dangerouslyAllowNameMatchingre-enables mutable email principal matching (break-glass compatibility mode).
Slack
- Socket mode requires both
botTokenandappToken(SLACK_BOT_TOKEN+SLACK_APP_TOKENfor default account env fallback). - HTTP mode requires
botTokenplussigningSecret(at root or per-account). configWrites: falseblocks Slack-initiated config writes.- Optional
channels.slack.defaultAccountoverrides default account selection when it matches a configured account id. channels.slack.streamingis the canonical stream mode key. LegacystreamModeand booleanstreamingvalues are auto-migrated.- Use
user:<id>(DM) orchannel:<id>for delivery targets.
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.
Mattermost
Mattermost ships as a bundled plugin:wednesdayai plugins install mattermost (the legacy @openclaw/mattermost spec resolves to the same bundled copy).
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@mentionbefore replying in channels.- Optional
channels.mattermost.defaultAccountoverrides default account selection when it matches a configured account id.
Signal
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.defaultAccountoverrides default account selection when it matches a configured account id.
BlueBubbles
BlueBubbles is the recommended iMessage path (plugin-backed, configured underchannels.bluebubbles).
- Core key paths covered here:
channels.bluebubbles,channels.bluebubbles.dmPolicy. - Optional
channels.bluebubbles.defaultAccountoverrides default account selection when it matches a configured account id. - Full BlueBubbles channel configuration is documented in BlueBubbles.
iMessage
WednesdayAI spawnsimsg rpc (JSON-RPC over stdio). No daemon or port required.
-
Optional
channels.imessage.defaultAccountoverrides default account selection when it matches a configured account id. - Requires Full Disk Access to the Messages DB.
-
Prefer
chat_id:<id>targets. Useimsg chats --limit 20to list chats. -
cliPathcan point to an SSH wrapper; setremoteHost(hostoruser@host) for SCP attachment fetching. -
attachmentRootsandremoteAttachmentRootsrestrict 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.
iMessage SSH wrapper example
iMessage SSH wrapper example
Microsoft Teams
Microsoft Teams is extension-backed and configured underchannels.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.
IRC
IRC is extension-backed and configured underchannels.irc.
- Core key paths covered here:
channels.irc,channels.irc.dmPolicy,channels.irc.configWrites,channels.irc.nickserv.*. - Optional
channels.irc.defaultAccountoverrides 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.
Multi-account (all channels)
Run multiple accounts per channel (each with its ownaccountId):
defaultis used whenaccountIdis 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.accountIdto 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
conflictedin 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 intochannels.<channel>.accounts.defaultfirst so the original account keeps working. - Existing channel-only bindings (no
accountId) keep matching the default account; account-scoped bindings remain optional. wednesdayai doctor --fixalso repairs mixed shapes by moving account-scoped top-level single-account values intoaccounts.defaultwhen named accounts exist butdefaultis missing.
Other extension channels
Many extension channels are configured aschannels.<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.
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).
messages.groupChat.historyLimit sets the global default. Channels can override with channels.<channel>.historyLimit (or per-account). Set 0 to disable.
DM history limits
telegram, whatsapp, discord, slack, signal, imessage, msteams.
Self-chat mode
Include your own number inallowFrom to enable self-chat mode (ignores native @-mentions, only responds to text patterns):
Commands (chat command handling)
Command details
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").falseclears previously registered commands. channels.telegram.customCommandsadds extra Telegram bot menu entries.bash: trueenables! <cmd>for host shell. Requirestools.elevated.enabledand sender intools.elevated.allowFrom.<channel>.config: trueenables/config(reads/writesopenclaw.json).channels.<provider>.configWritesgates config mutations per channel (default: true).allowFromis per-provider. When set, it is the only authorization source (channel allowlists/pairing anduseAccessGroupsare ignored).useAccessGroups: falseallows commands to bypass access-group policies whenallowFromis not set.
Agent defaults
agents.defaults.workspace
Default: ~/.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.
agents.defaults.skipBootstrap
Disables automatic creation of workspace bootstrap files (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md).
agents.defaults.bootstrapMaxChars
Max characters per workspace bootstrap file before truncation. Default: 20000.
agents.defaults.bootstrapTotalMaxChars
Max total characters injected across all workspace bootstrap files. Default: 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 for full behavior details.
preset choices:
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:
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), orrunKind(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.
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.
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).
{ 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.
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.
agents.defaults.timeFormat
Time format in system prompt. Default: auto (OS preference).
agents.defaults.model
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
imagetool 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.
- Used by the
pdfModel: accepts either a string ("provider/model") or an object ({ primary, fallbacks }).- Used by the
pdftool for model routing. - If omitted, the PDF tool falls back to
imageModel, then to best-effort provider defaults.
- Used by the
pdfMaxBytesMb: default PDF size limit for thepdftool whenmaxBytesMbis not passed at call time.pdfMaxPages: default maximum pages considered by extraction fallback mode in thepdftool.model.primary: formatprovider/model(e.g.anthropic/claude-opus-4-6). If you omit the provider, WednesdayAI assumesanthropic(deprecated).models: the configured model catalog and allowlist for/model. Each entry can includealias(shortcut) andparams(provider-specific, for exampletemperature,maxTokens,cacheRetention,context1m).paramsmerge precedence (config):agents.defaults.models["provider/model"].paramsis the base, thenagents.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 forsessions_spawnchains (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 byagents.list[].subagents.model.subagents.thinking: default thinking level for spawned sub-agents (e.g."off","low","medium","high"). Overridden per-agent byagents.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 byagents.list[].subagents.completionDeliveryand per-spawn by thesessions_spawncompletionDeliveryparameter. See 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.
agents.defaults.models):
--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.
- CLI backends are text-first; tools are always disabled.
- Sessions supported when
sessionArgis set. - Image pass-through supported when
imageArgaccepts file paths.
agents.defaults.heartbeat
Periodic heartbeat runs.
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 anagent.turn(kindheartbeat) that runs in a fresh:heartbeatsibling session with no prior transcript; a positivewakeGatealso nudges the main session (kindnudge). See Heartbeat.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 (kindnudge). DefaulttimeoutMsis 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:heartbeatsessions only — shared-session heartbeats keep the session’s full bootstrap) and swaps the default heartbeat prompt for the light variant; a configuredpromptalways 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 withisolatedSession: true— ignored with a warn on a shared-session heartbeat; can only narrow the tool surface, policytools.allowstill applies; an entry matching no tool logs atoolsAllow names matched no toolwarn; 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.blocksuppresses direct-target delivery and emitsreason=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 fortargetinteractions.identity: optionalsession.identityLinkskey (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 viaagents.list[].heartbeat.identity.- Per-agent: set
agents.list[].heartbeat. When any agent definesheartbeat, only those agents run heartbeats; the block merges key-by-key overagents.defaults.heartbeat, so a partial block inherits the rest. - Heartbeats run full agent turns — shorter intervals burn more tokens.
agents.defaults.compaction
mode:defaultorsafeguard(chunked summarization for long histories). See Compaction.identifierPolicy:strict(default),off, orcustom.strictprepends built-in opaque identifier retention guidance during compaction summarization.identifierInstructions: optional custom identifier-preservation text used whenidentifierPolicy=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.
cache-ttl mode behavior
cache-ttl mode behavior
mode: "cache-ttl"enables pruning passes.ttlcontrols 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.
... 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
keepLastAssistantsassistant messages exist, pruning is skipped. - Separately from pruning, any single tool result is capped at
400,000text 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 ofcontextPruning.
Block streaming
- Non-Telegram channels require explicit
*.blockStreaming: trueto enable block replies. - Channel overrides:
channels.<channel>.blockStreamingCoalesce(and per-account variants). Signal/Slack/Discord/Google Chat defaultminChars: 1500. humanDelay: randomized pause between block replies.natural= 800–2500ms. Per-agent override:agents.list[].humanDelay.
Typing indicators
- Defaults:
instantfor direct chats/mentions,messagefor unmentioned group chats. - Per-session overrides:
session.typingMode,session.typingIntervalSeconds.
agents.defaults.sandbox
Optional Docker sandboxing for the embedded agent. See Sandboxing for the full guide.
Sandbox details
Sandbox details
none: per-scope sandbox workspace under~/.openclaw/sandboxesro: sandbox workspace at/workspace, agent workspace mounted read-only at/agentrw: agent workspace mounted read/write at/workspace
session: per-session container + workspaceagent: 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.networkdefaults toopenclaw-sandbox-browser(dedicated bridge network). Set tobridgeonly when you explicitly want global bridge connectivity.cdpSourceRangeoptionally restricts CDP ingress at the container edge to a CIDR range (for example172.21.0.1/32).sandbox.browser.bindsmounts additional host directories into the sandbox browser container only. When set (including[]), it replacesdocker.bindsfor 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.shand 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-gpuare enabled by default and can be disabled withOPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0if WebGL/3D usage requires it.OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0re-enables extensions if your workflow depends on them.--renderer-process-limit=2can be changed withOPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>; set0to use Chromium’s default process limit.- plus
--no-sandboxand--disable-setuid-sandboxwhennoSandboxis enabled. - Defaults are the container image baseline; use a custom browser image with a custom entrypoint to change container defaults.
agents.list (per-agent overrides)
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## Teamprompt section,agents_listreturns it, and the Control UI shows it.userFacing: whether people can reach the agent directly (defaulttrue). Setfalsefor internal specialists. Config validation rejects an internal agent as the default agent, abindings[]target, or abroadcasttarget, and rejects any internal agent whensession.scopeis"global"(all agents share one session there). User clients (web client) do not see it or its sessions and runs inagents.list,sessions.direct,sessions.list, orsessions.runs.list, do not receive events for its sessions, get it omitted fromhealthandstatusagent 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_spawnwiththread: true,/subagents spawn,/tell,/steer,/focus, and/acpcannot target it,/acp sessionshides 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 againstsession.identityLinks, so identity-scoped workspace lanes, memory, and plugins resolve for that person (defaulttrue). Setfalseto 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.model: string form overridesprimaryonly; object form{ primary, fallbacks }overrides both ([]disables global fallbacks). Cron jobs that only overrideprimarystill inherit default fallbacks unless you setfallbacks: [].params: per-agent stream params merged over the selected model entry inagents.defaults.models. Use this for agent-specific overrides likecacheRetention,temperature, ormaxTokenswithout duplicating the whole model catalog.identity.avatar: workspace-relative path,http(s)URL, ordata:URI.identity.color: optional web client assistant colour. Seeagents.list[].identity.colorbelow.identityderives defaults:ackReactionfromemoji,mentionPatternsfromname/emoji.subagents.allowAgents: per-agent allowlist of agent ids forsessions_spawn’sagentIdparameter (["*"]= any; default: same agent only). Allowlist-only — no deny-list for target agent IDs. See Sub-agent access control.subagents.model: per-agent default model for spawned sub-agents (overridesagents.defaults.subagents.model).subagents.thinking: per-agent default thinking level for spawned sub-agents (overridesagents.defaults.subagents.thinking).subagents.completionDelivery: per-agent delivery mode for top-level sub-agent completions ("parent"or"direct"; overridesagents.defaults.subagents.completionDelivery). See Completion delivery.tts: per-agent override ofmessages.tts(voice, provider, model,readAloud, …), deep-merged over the global config. Applies to read aloud, auto voice replies,/ttsand thettstool for this agent. A provider pinned with/tts providerstill wins. See Per-agent TTS.systemPrompt: per-agent prompt shape override. Merges overagents.defaults.systemPromptby section key. WhenprojectContext.filesis set, that list replaces the default entirely (not merged). Seeagents.defaults.systemPromptfor the full field reference.- Sandbox inheritance guard: if the requester session is sandboxed,
sessions_spawnrejects targets that would run unsandboxed.
agents.list[].identity.color
- 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-tokensguarantees 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.mddoes not carry a colour. - Also carried on
agents.list(the gateway RPC method) asidentity.color, so a colour set here is what the web client 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.modelsto a real, bounded catalog. The model menu (models.list) lists the catalog entries named there, andsessions.patchandsessions.create’s optionalmodelfield (client-chat-v3 P2, ADR 0083/0084) accept those plus the agent’s own default model.agents.list[].modelfallbacks do not widen or narrow either. Leavingagents.defaults.modelsempty lists the whole model catalog and admits anyprovider/modelreference 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.
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.
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 inagents.list.members: agent ids of the members (at least one); must be inagents.listand 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_spawnevery member in addition to its ownsubagents.allowAgents, andagents_listincludes them. Members get no new rights. - When the lead has the
sessions_spawntool, its system prompt gets a## Teamsection listing each member’s id, name, and description. Control it with theteamkey insystemPrompt.sections. - Teams do not change
tools.agentToAgent(sessions_send) or ACP targets.
Multi-agent routing
Run multiple isolated agents inside one Gateway. See Multi-Agent.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)
match.peermatch.guildIdmatch.teamIdmatch.accountId(exact, no peer/guild/team)match.accountId: "*"(channel-wide)- Default agent
bindings entry wins.
Per-agent access profiles
Full access (no sandbox)
Full access (no sandbox)
Read-only tools + workspace
Read-only tools + workspace
No filesystem access (messaging only)
No filesystem access (messaging only)
Session
Session field details
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 heartbeatidentityattribution (matched case-insensitively; the run carries the stored key casing as its canonical identity). Keys starting withraw~are rejected at config validation — that prefix is reserved for contained unlinked-sender session buckets (see Sessions). Gateway clients (web client, Control UI) send their turns asdevice:<deviceId>; link each device to a person withwednesdayai devices link <deviceId> --identity <key>, or pair it already linked withwednesdayai identity link <key> --qr(see Identities). Get ids fromwednesdayai devices list --json(deviceIdon eachpairedentry). Agents with workspace lanes deny unlinked devices.reset: primary reset policy.dailyresets atatHourlocal time;idleresets afteridleMinutes. When both configured, whichever expires first wins.resetByType: per-type overrides (direct,group,thread). Legacydmaccepted as alias fordirect.parentForkMaxTokens: max parent-sessiontotalTokensallowed when creating a forked thread session (default100000).- If parent
totalTokensis above this value, WednesdayAI starts a fresh thread session instead of inheriting parent transcript history. - Set
0to disable this guard and always allow parent forking.
- If parent
mainKey: legacy field. Runtime now always uses"main"for the main direct-chat bucket.sendPolicy: match bychannel,chatType(direct|group|channel, with legacydmalias),keyPrefix, orrawKeyPrefix. First deny wins.channelandchatTypecompare 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;keyPrefixandrawKeyPrefixmatch the key itself. Achannelnamed in anagentrequest 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 clearedsendPolicyis seen. If the row was deleted while the request was in flight, the Gateway falls back to the storedsendPolicy, 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 containedraw~bucket is a distinct key: akeyPrefixwritten for a linked person’s canonical key does not match their unlinkedraw~<peer>bucket — add a rule for each bucket (see Sessions).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.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:warnemits warnings only (default);enforceapplies cleanup.pruneAfter: index entries whoseupdatedAtis older than this are retired (tombstoned) in enforce mode (default30d).maxEntries: maximum number of session index rows to keep; the oldest are tombstoned beyond the cap (default500).- The file-only controls
rotateBytes,resetArchiveRetention,maxDiskBytes, andhighWaterBytesare 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 useschannels.discord.threadBindings.enabled)idleHours: default inactivity auto-unfocus in hours (0disables; providers can override)maxAgeHours: default hard max age in hours (0disables; providers can override)
consumerClaims: session-consumer claim ledger settings. See Session Consumer Claims for full details.sweepCadenceMs: reconciler sweep interval (default60000= 1min).maxAttempts: DLQ threshold (default5).leaseMs: claim lease duration (default30000= 30s).retryBaseMs: exponential backoff base (default1000).
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).
Storage field details
Storage field details
backend: default backend (json,sqliteorpostgres) for every config domain that ships it; domains that do not ship the selected backend stay onjson. Asqliteorpostgresvalue must matchsession.storage.backendand the gateway fails to start withstorage.backend is "<backend>" but session storage is "<session>"; config domains live in the session databasewhen they disagree. In this release no domain ships a SQL backend, so the gateway logsstorage.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 withstorage.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 releaseotherwise. A SQL override must equalsession.storage.backend; a mismatch fails withstorage domain "<id>" is "<backend>" but session storage is "<session>"; config domains live in the session database.
storage require a gateway restart
(see What hot-applies vs what needs a restart).
Messages
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:
{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)
autocontrols auto-TTS./tts off|always|inbound|taggedoverrides per session.summaryModeloverridesagents.defaults.model.primaryfor auto-summary.modelOverridesis enabled by default;modelOverrides.allowProviderdefaults tofalse(opt-in).openai.baseUrl: OpenAI-compatible endpoint for OpenAI TTS (defaulthttps://api.openai.com/v1), overridable per agent withagents.list[].tts.openai.baseUrl. TheOPENAI_TTS_BASE_URLenv 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.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.readAloud.enabled: gate for chat clients reading replies aloud on demand through thetts.speakgateway RPC (defaulttrue). Turn it off to stop on-demand synthesis spend; auto-TTS and/ttsare unaffected. Overridden per agent byagents.list[].tts.readAloud.enabled. See Read aloud for chat clients.- Per-agent override: an agent’s
agents.list[].ttsblock (same fields asmessages.tts) merges over the global config, so voice, provider, model and the read-aloud gate can differ per agent. See Per-agent TTS. - API keys fall back to
ELEVENLABS_API_KEY/XI_API_KEYandOPENAI_API_KEY.
Talk
Defaults for Talk mode (macOS/iOS/Android).- Voice IDs fall back to
ELEVENLABS_VOICE_IDorSAG_VOICE_ID. apiKeyandproviders.*.apiKeyaccept plaintext strings or SecretRef objects. Both are best-effort: an unresolvable ref warns (SECRETS_REF_OPTIONAL_UNRESOLVED) and does not fail gateway startup.talk.catalogthen reports that provider unavailable withdiagnostic: "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_KEYfallback applies only when no Talk API key is configured.voiceAliaseslets Talk directives use friendly names.- Cascaded Voice mode reuses
talk.providers.<id>.modelIdwhen set. When it is unset, Voice mode falls back toeleven_flash_v2_5, not the legacy Talk-command defaulteleven_v3shown 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 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.
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.
Tool groups
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). Bare * does not waive that default-deny.
tools.byProvider
Further restrict tools for specific providers or models. Order: base profile → provider profile → allow/deny.
tools.elevated
Controls elevated (host) exec access:
- Per-agent override (
agents.list[].tools.elevated) can only further restrict. /elevated on|off|ask|fullstores state per session; inline directives apply to single message.- Elevated
execruns on the host, bypasses sandboxing.
tools.exec
tools.loopDetection
Tool-loop safety checks are disabled by default. Set enabled: true to activate detection.
Settings can be defined globally in tools.loopDetection and overridden per-agent at agents.list[].tools.loopDetection.
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.- If
warningThreshold >= criticalThresholdorcriticalThreshold >= globalCircuitBreakerThreshold, validation fails.
tools.web
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). 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).
The following example shows a vendor plugin entry (openai):
Media model entry fields
Media model entry fields
type: "provider" or omitted):provider: API provider id (openai,anthropic,google/gemini,groq, etc.)model: model id overrideprofile/preferredProfile:auth-profiles.jsonprofile selection
type: "cli"):command: executable to runargs: templated args (supports{{MediaPath}},{{Prompt}},{{MaxChars}}, etc.)
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.
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
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).
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 requirestools.agentToAgent.- Sandbox clamp: when the current session is sandboxed and
agents.defaults.sandbox.sessionToolsVisibility="spawned", visibility is forced totreeeven iftools.sessions.visibility="all".
tools.sessions_spawn
Controls inline attachment support for sessions_spawn.
- 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
0700for directories and0600for files. - Cleanup follows the
cleanuppolicy:deletealways removes attachments;keepretains them only whenretainOnSessionKeep: 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).
model: default model for spawned sub-agents. If omitted, sub-agents inherit the caller’s model. Overridden per-agent byagents.list[].subagents.modeland globally byagents.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. AtmaxSpawnDepth >= 2, depth-1 orchestrators additionally receivesessions_spawn,subagents,sessions_list,sessions_history.
agents.defaults.subagents.* above.
Custom providers and base URLs
WednesdayAI uses the pi-coding-agent model catalog. Add custom providers viamodels.providers in config or ~/.openclaw/agents/<agentId>/agent/models.json.
- Use
authHeader: true+headersfor custom auth needs. - Override agent config root with
OPENCLAW_AGENT_DIR(orPI_CODING_AGENT_DIR). - Merge precedence for matching provider IDs:
- Non-empty agent
models.jsonapiKey/baseUrlwin. - Empty or missing agent
apiKey/baseUrlfall back tomodels.providersin config. - Matching model
contextWindow/maxTokensuse the higher value between explicit config and implicit catalog values. - Use
models.mode: "replace"when you want config to fully rewritemodels.json.
- Non-empty agent
Provider field details
models.mode: provider catalog behavior (mergeorreplace).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, injectoptions.num_ctxinto requests (default:true).models.providers.*.authHeader: force credential transport in theAuthorizationheader 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. Forapi: "openai-completions"with a non-empty non-nativebaseUrl(host notapi.openai.com), WednesdayAI forces this tofalseat runtime. Empty/omittedbaseUrlkeeps 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
Cerebras (GLM 4.6 / 4.7)
Cerebras (GLM 4.6 / 4.7)
cerebras/zai-glm-4.7 for Cerebras; zai/glm-4.7 for Z.AI direct.OpenCode Zen
OpenCode Zen
OPENCODE_API_KEY (or OPENCODE_ZEN_API_KEY). Shortcut: wednesdayai onboard --auth-choice opencode-zen.Z.AI (GLM-4.7)
Z.AI (GLM-4.7)
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.
Moonshot AI (Kimi)
Moonshot AI (Kimi)
baseUrl: "https://api.moonshot.cn/v1" or wednesdayai onboard --auth-choice moonshot-api-key-cn.Kimi Coding
Kimi Coding
wednesdayai onboard --auth-choice kimi-code-api-key.Synthetic (Anthropic-compatible)
Synthetic (Anthropic-compatible)
/v1 (Anthropic client appends it). Shortcut: wednesdayai onboard --auth-choice synthetic-api-key.MiniMax M2.5 (direct)
MiniMax M2.5 (direct)
MINIMAX_API_KEY. Shortcut: wednesdayai onboard --auth-choice minimax-api.Local models (LM Studio)
Local models (LM Studio)
Skills
allowBundled: optional allowlist for bundled skills only (managed/workspace skills unaffected).entries.<skillKey>.enabled: falsedisables 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 bywednesdayai skillscommands to locate install sources. Mirrorsplugins.installs:sourceis one ofnpm,archive,path, orbundled; catalog installs usearchive.specis the catalog id (or the original spec for non-catalog installs).installPathis 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.
Plugins
- Loaded from
~/.openclaw/extensions,<workspace>/.openclaw/extensions, plusplugins.load.paths. - Config changes require a gateway restart.
allow: optional allowlist (only listed plugins load).denywins.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 throughapi.runtime.signals.nudge; default deny. Each wake is a durableagent.turnnudge. Bundled plugins may ship a manifest-declared default used only when this key is unset (an explicit empty list revokes it). See 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. Unlikeplugins.slots.memorythere is no default id: unset means the first loaded context-engine plugin wins.plugins.hookTimeouts: per-hook timeout in milliseconds. Keys are hook names ordefault. Unset hooks use 30000 ms. Registrationapi.on(..., { timeoutMs })still wins. Restart required.plugins.analysisConcurrency.maxParallel: concurrent awaitedanalysis.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 forcontext.*hooks only, used whenhookTimeoutsdoes not cover that hook. Restart required.plugins.installs: CLI-managed install metadata used bywednesdayai plugins update.sourceis one ofnpm,archive,path, orbundled.source: "bundled"means the plugin is loaded from the bundled extension copy that shipped with the current WednesdayAI package.sourcePathmust 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.
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.
Browser
evaluateEnabled: falsedisablesact:evaluateandwait --fn.ssrfPolicy.dangerouslyAllowPrivateNetworkdefaults totruewhen unset (trusted-network model).- Set
ssrfPolicy.dangerouslyAllowPrivateNetwork: falsefor strict public-only browser navigation. ssrfPolicy.allowPrivateNetworkremains supported as a legacy alias.- In strict mode, use
ssrfPolicy.hostnameAllowlistandssrfPolicy.allowedHostnamesfor explicit exceptions. ssrfPolicy.allowedCidrsallows specific IPv4/IPv6 CIDR ranges for private/internal addresses.ssrfPolicy.allowRfc2544BenchmarkRangeadditionally 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, default18791). extraArgsappends 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
- 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 bywednesdayai security auditand logged at startup. UseallowedCidrsinstead where possible.network.ssrfPolicy.allowPrivateNetwork: legacy alias fordangerouslyAllowPrivateNetwork.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.
UI
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
Gateway field details
Gateway field details
mode:local(run gateway) orremote(connect to remote gateway). Gateway refuses to start unlesslocal.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), orcustom.- 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
loopbackbind listens on127.0.0.1inside the container. With Docker bridge networking (-p 18789:18789), traffic arrives oneth0, so the gateway is unreachable. Use--network host, or setbind: "lan"(orbind: "custom"withcustomBindHost: "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 fromgateway.trustedProxies(see Trusted Proxy Auth).- Ambient auth still verifies device tokens: under
none,trusted-proxyor Tailscale identity auth, a connect that presentsauth.deviceTokengets it verified as undertokenmode; a revoked, unknown or over-scoped token is refused withAUTH_DEVICE_TOKEN_MISMATCH.auth.tokenis not treated as a device credential in those modes. See Protocol. - The
openclaw-user-clientweb client is exempt from every ambient auth mode: undernone,trusted-proxyand 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 for the full rule. gateway.auth.allowTailscale: whentrue, Tailscale Serve identity headers can satisfy Control UI/WebSocket auth (verified viatailscale whois); HTTP API endpoints still require token/password auth. This tokenless flow assumes the gateway host is trusted. Defaults totruewhentailscale.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 return429+Retry-After.gateway.auth.rateLimit.exemptLoopbackdefaults totrue; setfalsewhen 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) orfunnel(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, unlessdangerouslyAllowHostHeaderOriginFallbackis set. Onboarding and gateway startup seedhttp://localhost:<port>andhttp://127.0.0.1:<port>(plus the custom bind host) when none are configured.gateway.controlUiis the admission and auth policy for theopenclaw-control-uiconsole 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 tocontrolUi.allowedOriginswhen 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 toopenclaw.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 theopenclaw-user-clientweb client. This check always runs for that client id, even when reverse-proxy headers are present, andcontrolUi.allowedOriginsnever admits it. Default empty, which admits nothing. See Protocol for the client identity rules.webClient.enabled: serve the built web client bundle from this gateway, same-origin, atwebClient.basePath. Defaultfalse: 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.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.basePathwhen 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 setbasePath, 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. SetbasePath: "/client"to keep the old address.gateway.*changes need a gateway restart. See Web client hosting.webClient.root: directory holding the built bundle (index.htmlplusassets/). Optional: withwebClient.enabledtrue and noroot, the gateway serves the bundle packaged with this install (dist/web-client), and answers503naming the build command only when that is missing too. An explicitrootalways wins - including when it is broken, which answers503with that reason rather than silently falling back.webClient.imageOrigins: exacthttps://host[:port]origins that remote markdown images may load from in the gateway-served web client, extended into its CSPimg-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.webClient.accountLinking: lets a linked web-client user link their own chat accounts with/linkcodes (web client Account menu → Linked accounts →identity.link.claim). Defaulttrue. Setfalseto keep all linking operator-only:/linkand the claim RPC both answerAccount linking is turned off on this gateway.Operator commands (identity add/link/unlink,devices link,pairing approve) are unaffected. See Identities.webClient.pluginUi.allow: plugin ids whose chat UI browser module (manifestchatUi.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.requestinjects 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.controlUiV2.enabled: serve the control UI v2 operator console from this gateway, same-origin, atcontrolUiV2.basePath. Defaulttrue: the v2 console is the daily console and owns the gateway root. Set it tofalseto serve no operator console. The classic console was removed (ADR 1771), sogateway.controlUiis admission-only andcontrolUiV2is the only console mount. The console connects as theopenclaw-control-uiclient, so admission, scopes and auth modes are governed bycontrolUi.allowedOriginsand friends; there is no separate allowlist. A non-loopback bind with the console enabled still requirescontrolUi.allowedOriginsat startup. See Control UI v2.controlUiV2.basePath: public path the console is mounted under. Default: the gateway root; the v2 console mounts at/v2/controlinstead when an enabledwebClientexplicitly claims/with itsbasePath, 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.htmlplusassets/). Optional: unset, the gateway serves the bundle packaged with this install (dist/control-ui-v2) and answers503namingpnpm control:build:packagedonly when that is missing too. An explicitrootalways wins - including when it is broken, which answers503with that reason.controlUiV2.pluginUi.allow: plugin ids whose browser module (manifestcontrolUi.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 and the developer guide Control UI plugins.remote.transport:ssh(default) ordirect(ws/wss). Fordirect,remote.urlmust bews://orwss://.OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1: client-side break-glass override that allows plaintextws://to trusted private-network IPs; default remains loopback-only for plaintext.gateway.remote.token/.passwordare remote-client credential fields. They do not configure gateway auth by themselves.- Local gateway call paths can use
gateway.remote.*as fallback whengateway.auth.*is unset. trustedProxies: reverse proxy IPs that terminate TLS. Only list proxies you control.allowRealIpFallback: whentrue, the gateway acceptsX-Real-IPifX-Forwarded-Foris missing. Defaultfalsefor fail-closed behavior.gateway.tools.deny: extra tool names blocked for HTTPPOST /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 bydevices listandnodes status, and may be archived bydevices 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. Default90.gateway.devices.activityIntervalMinutes: minutes between last-active writes for a connection that stays open. Connect and disconnect always write. Default5. Separately, a device token’slastUsedAtMsis written at most once every 5 minutes (fixed).
Session steering defaults
gateway.sessions.steer.defaultMode: mode thesessions.steerRPC applies when the caller omitsmode. 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 longsessions.steerwithmode: "interrupt"waits for the aborted run to reach a terminal state before failing the call. Integer,0or more; default15000. The replacement turn is never started past this point, so a session cannot end up with two concurrent runs.
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 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.maxUrlPartsgateway.http.endpoints.responses.files.urlAllowlistgateway.http.endpoints.responses.images.urlAllowlist
- Optional response hardening header:
gateway.http.securityHeaders.strictTransportSecurity(set only for HTTPS origins you control; see Trusted Proxy Auth)
Multi-instance isolation
Run multiple gateways on one host with unique ports and state dirs:--dev (uses ~/.openclaw-dev + port 19001), --profile <name> (uses ~/.openclaw-<name>).
See Multiple Gateways.
Node Host Browser Proxy
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.
nodeHost.browserProxy.enabled=false.
Disable on the gateway: gateway.nodes.browser.mode="off".
Hooks
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? }sessionKeyfrom request payload is accepted only whenhooks.allowRequestSessionKey=true(default:false).
POST /hooks/<name>→ resolved viahooks.mappings
Mapping details
Mapping details
match.pathmatches sub-path after/hooks(e.g./hooks/gmail→gmail).match.sourcematches a payload field for generic paths.- Templates like
{{messages[0].subject}}read from the payload. transformcan point to a JS/TS module returning a hook action.transform.modulemust be a relative path and stays withinhooks.transformsDir(absolute paths and traversal are rejected).
agentIdroutes 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 explicitsessionKey.allowRequestSessionKey: allow/hooks/agentcallers to setsessionKey(default:false).allowedSessionKeyPrefixes: optional prefix allowlist for explicitsessionKeyvalues (request + mapping), e.g.["hook:"].deliver: truesends final reply to a channel;channeldefaults tolast.modeloverrides LLM for this hook run (must be allowed if model catalog is set).
Gmail integration
- Gateway auto-starts
gog gmail watch serveon boot when configured. SetOPENCLAW_SKIP_GMAIL_WATCHER=1to disable. - Don’t run a separate
gog gmail watch servealongside the Gateway.
Canvas host
- 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.htmlwhen empty. - Also serves A2UI at
/__openclaw__/a2ui/. - Changes require a gateway restart.
- Disable live reload for large directories or
EMFILEerrors.
Discovery
mDNS (Bonjour)
minimal(default): omitcliPath+sshPortfrom TXT records.full: includecliPath+sshPort.- Hostname defaults to
openclaw. Override withOPENCLAW_MDNS_HOSTNAME.
Wide-area (DNS-SD)
~/.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)
- Inline env vars are only applied if the process env is missing the key.
.envfiles: CWD.env+~/.openclaw/.env(neither overrides existing vars).shellEnv: imports missing expected keys from your login shell profile.- See Environment for full precedence.
Env var substitution
Reference env vars in any config string with${VAR_NAME}:
- 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 behindwednesdayai plugins install <id> and wednesdayai skills install <id>. Full list and
precedence: Environment.
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:
providerpattern:^[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
secrets applytargets supportedopenclaw.jsoncredential paths.auth-profiles.jsonrefs are included in runtime resolution and audit coverage.
Secret providers config
fileprovider supportsmode: "json"andmode: "singleValue"(idmust be"value"in singleValue mode).execprovider requires an absolutecommandpath and uses protocol payloads on stdin/stdout.- By default, symlink command paths are rejected. Set
allowSymlinkCommand: trueto allow symlink paths while validating the resolved target path. - If
trustedDirsis configured, the trusted-dir check applies to the resolved target path. execchild environment is minimal by default; pass required variables explicitly withpassEnv.- 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
- Per-agent profiles are stored at
<agentDir>/auth-profiles.json. auth-profiles.jsonsupports value-level refs (keyRefforapi_key,tokenReffortoken).- Static runtime credentials come from in-memory resolved snapshots; legacy static
auth.jsonentries are scrubbed when discovered. - Legacy OAuth imports from
~/.openclaw/credentials/oauth.json. - See OAuth.
- Secrets runtime behavior and
audit/configure/applytooling: Secrets Management.
Logging
- Default log file:
/tmp/openclaw/openclaw-YYYY-MM-DD.log. - Set
logging.filefor a stable path. logging.maxFileBytesandlogging.maxBackupsremain aliases for theprimaryfile-log profile.logging.fileLogs.defaultsapplies shared file-log defaults for durable diagnostic and audit logs.logging.fileLogs.profiles.<profileId>overrides one named log. Supported built-in profiles:primary: mainopenclaw-YYYY-MM-DD.logruntime log.cron.run: cron run JSONL logs undercron/runs/<jobId>.jsonl.config.audit: config write audit log atlogs/config-audit.jsonl.hooks.command: bundled command logger output atlogs/commands.log.agents.rawStream: PI raw stream diagnostic JSONL.extensions.learningCore: learning-core active JSONL log.extensions.voiceCall.calls: voice-call legacycalls.jsonlstore.
- File-log profile fields:
file,maxFileBytes,maxBackups,compress,maxQueuedBytes,keepLines, andmode. - Default profile values are
maxFileBytes: 10485760,maxBackups: 5,compress: "gzip",maxQueuedBytes: 1048576, andmode: "jsonl". maxFileBytesandmaxQueuedBytesmust be positive integers.maxBackupsmust be a non-negative integer;0means rotate by truncating without retaining backups.compress: falsekeeps plaintext numbered backups such as.1;compress: "gzip"writes.1.gzbackups.- Profile merge order is built-in defaults,
logging.fileLogs.defaults, call-site defaults, primary legacy aliases for theprimaryprofile, thenlogging.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, andextensions.voiceCall.calls, use profile fields such asmaxFileBytes,maxBackups,compress, andmaxQueuedBytes;fileis intentionally ignored. maxQueuedBytesbounds 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. consoleLevelbumps todebugwhen--verbose.
CLI
cli.banner.taglineModecontrols 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):
Identity
messages.ackReactionfromidentity.emoji(falls back to 👀)mentionPatternsfromidentity.name/identity.emojiavataraccepts: workspace-relative path,http(s)URL, ordata:URIcoloris optional and only affects the web client; seeagents.list[].identity.colorfor the palette and theagents.defaults.modelsadvice
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).
Legacy bridge config (historical reference)
Legacy bridge config (historical reference)
Tasks
The background task pipeline (tasks.*: enabled, dispatchConcurrency,
preemptionCeiling, budget, restartLoop, idle, schedule) is documented with defaults
on Task operations. The tasks.idle and tasks.schedule keys drive the
idle monitor consumed by plugins such as Dream Cycle.
Cron
sessionRetention: how long to keep completed isolated cron run sessions before their index rows are tombstoned from the session store. Default:24h; setfalseto disable.runLog.maxBytes: max size per run log file (cron/runs/<jobId>.jsonl) before pruning. Default:2_000_000bytes.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 havenotify: true.
Media model template variables
Template placeholders expanded intools.media.models[].args:
Config includes ($include)
Split config into multiple files:
- 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 (
dirnameofopenclaw.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 · Configuration Examples · Doctor