Skip to main content

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 (unless enabled: 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

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

Use channels.defaults for shared group-policy and heartbeat behavior across providers:
  • channels.defaults.groupPolicy: fallback group policy when a provider-level groupPolicy is 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.

WhatsApp

WhatsApp runs through the gateway’s web channel (Baileys Web). It starts automatically when a linked session exists. The config key remains 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.
  • Outbound commands default to account default if present; otherwise the first configured account id (sorted).
  • Optional channels.whatsapp.defaultAccount overrides that fallback default account selection when it matches a configured account id.
  • Legacy single-account Baileys auth dir is migrated by wednesdayai doctor into whatsapp/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.botToken or channels.telegram.tokenFile, with TELEGRAM_BOT_TOKEN as fallback for the default account.
  • Multi-bot fleet: define channels.telegram.accounts.<id> with account-level botToken or tokenFile values. 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 as conflicted.
  • 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.defaultAccount overrides default account selection when it matches a configured account id.
  • configWrites: false blocks 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, with DISCORD_BOT_TOKEN as fallback for the default account.
  • Optional channels.discord.defaultAccount overrides default account selection when it matches a configured account id.
  • Use user:<id> (DM) or channel:<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: true enables them (own messages still filtered).
  • maxLinesPerMessage (default 17) splits tall messages even when under 2000 chars.
  • channels.discord.threadBindings controls 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 (0 disables)
    • maxAgeHours: Discord override for hard max age in hours (0 disables)
    • spawnSubagentSessions: opt-in switch for sessions_spawn({ thread: true }) auto thread creation/binding
  • channels.discord.ui.components.accentColor sets the accent color for Discord components v2 containers.
  • channels.discord.voice enables Discord voice channel conversations and optional auto-join + TTS overrides.
  • channels.discord.voice.daveEncryption and channels.discord.voice.decryptionFailureTolerance pass through to @discordjs/voice DAVE options (true and 24 by default).
  • WednesdayAI additionally attempts voice receive recovery by leaving/rejoining a voice session after repeated decrypt failures.
  • channels.discord.streaming is the canonical stream mode key. Legacy streamMode and boolean streaming values are auto-migrated.
  • channels.discord.dangerouslyAllowNameMatching re-enables mutable name/tag matching (break-glass compatibility mode).
Reaction notification modes: 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_ACCOUNT or GOOGLE_CHAT_SERVICE_ACCOUNT_FILE.
  • Use spaces/<spaceId> or users/<userId> for delivery targets.
  • channels.googlechat.dangerouslyAllowNameMatching re-enables mutable email principal matching (break-glass compatibility mode).

Slack

  • Socket mode requires both botToken and appToken (SLACK_BOT_TOKEN + SLACK_APP_TOKEN for default account env fallback).
  • HTTP mode requires botToken plus signingSecret (at root or per-account).
  • configWrites: false blocks Slack-initiated config writes.
  • Optional channels.slack.defaultAccount overrides default account selection when it matches a configured account id.
  • channels.slack.streaming is the canonical stream mode key. Legacy streamMode and boolean streaming values are auto-migrated.
  • Use user:<id> (DM) or channel:<id> for delivery targets.
Reaction notification modes: 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).
Chat modes: 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 @mention before replying in channels.
  • Optional channels.mattermost.defaultAccount overrides default account selection when it matches a configured account id.

Signal

Reaction notification modes: 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.defaultAccount overrides default account selection when it matches a configured account id.

BlueBubbles

BlueBubbles is the recommended iMessage path (plugin-backed, configured under channels.bluebubbles).
  • Core key paths covered here: channels.bluebubbles, channels.bluebubbles.dmPolicy.
  • Optional channels.bluebubbles.defaultAccount overrides default account selection when it matches a configured account id.
  • Full BlueBubbles channel configuration is documented in BlueBubbles.

iMessage

WednesdayAI spawns imsg rpc (JSON-RPC over stdio). No daemon or port required.
  • Optional channels.imessage.defaultAccount overrides default account selection when it matches a configured account id.
  • Requires Full Disk Access to the Messages DB.
  • Prefer chat_id:<id> targets. Use imsg chats --limit 20 to list chats.
  • cliPath can point to an SSH wrapper; set remoteHost (host or user@host) for SCP attachment fetching.
  • attachmentRoots and remoteAttachmentRoots restrict 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.

Microsoft Teams

Microsoft Teams is extension-backed and configured under channels.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 under channels.irc.
  • Core key paths covered here: channels.irc, channels.irc.dmPolicy, channels.irc.configWrites, channels.irc.nickserv.*.
  • Optional channels.irc.defaultAccount overrides 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 own accountId):
  • default is used when accountId is 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.accountId to 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 conflicted in 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 into channels.<channel>.accounts.default first so the original account keeps working.
  • Existing channel-only bindings (no accountId) keep matching the default account; account-scoped bindings remain optional.
  • wednesdayai doctor --fix also repairs mixed shapes by moving account-scoped top-level single-account values into accounts.default when named accounts exist but default is missing.

Other extension channels

Many extension channels are configured as channels.<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

Resolution: per-DM override → provider default → no limit (all retained). The DM’s channel and peer id come from the session’s stored identity, not the session key text: a session with no stored identity gets no limit (all retained), and a per-DM override never matches it. Supported: telegram, whatsapp, discord, slack, signal, imessage, msteams.

Self-chat mode

Include your own number in allowFrom to enable self-chat mode (ignores native @-mentions, only responds to text patterns):

Commands (chat command handling)

  • 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"). false clears previously registered commands.
  • channels.telegram.customCommands adds extra Telegram bot menu entries.
  • bash: true enables ! <cmd> for host shell. Requires tools.elevated.enabled and sender in tools.elevated.allowFrom.<channel>.
  • config: true enables /config (reads/writes openclaw.json).
  • channels.<provider>.configWrites gates config mutations per channel (default: true).
  • allowFrom is per-provider. When set, it is the only authorization source (channel allowlists/pairing and useAccessGroups are ignored).
  • useAccessGroups: false allows commands to bypass access-group policies when allowFrom is 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), or runKind (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).
Each takes { 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 image tool 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.
  • pdfModel: accepts either a string ("provider/model") or an object ({ primary, fallbacks }).
    • Used by the pdf tool for model routing.
    • If omitted, the PDF tool falls back to imageModel, then to best-effort provider defaults.
  • pdfMaxBytesMb: default PDF size limit for the pdf tool when maxBytesMb is not passed at call time.
  • pdfMaxPages: default maximum pages considered by extraction fallback mode in the pdf tool.
  • model.primary: format provider/model (e.g. anthropic/claude-opus-4-6). If you omit the provider, WednesdayAI assumes anthropic (deprecated).
  • models: the configured model catalog and allowlist for /model. Each entry can include alias (shortcut) and params (provider-specific, for example temperature, maxTokens, cacheRetention, context1m).
  • params merge precedence (config): agents.defaults.models["provider/model"].params is the base, then agents.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 for sessions_spawn chains (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 by agents.list[].subagents.model.
  • subagents.thinking: default thinking level for spawned sub-agents (e.g. "off", "low", "medium", "high"). Overridden per-agent by agents.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 by agents.list[].subagents.completionDelivery and per-spawn by the sessions_spawn completionDelivery parameter. 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.
Built-in alias shorthands (only apply when the model is in agents.defaults.models): Your configured aliases always win over defaults. Z.AI GLM-4.x models automatically enable thinking mode unless you set --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 sessionArg is set.
  • Image pass-through supported when imageArg accepts 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 an agent.turn (kind heartbeat) that runs in a fresh :heartbeat sibling session with no prior transcript; a positive wakeGate also nudges the main session (kind nudge). 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 (kind nudge). Default timeoutMs is 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 :heartbeat sessions only — shared-session heartbeats keep the session’s full bootstrap) and swaps the default heartbeat prompt for the light variant; a configured prompt always 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 with isolatedSession: true — ignored with a warn on a shared-session heartbeat; can only narrow the tool surface, policy tools.allow still applies; an entry matching no tool logs a toolsAllow names matched no tool warn; 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. block suppresses direct-target delivery and emits reason=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 for target interactions.
  • identity: optional session.identityLinks key (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 via agents.list[].heartbeat.identity.
  • Per-agent: set agents.list[].heartbeat. When any agent defines heartbeat, only those agents run heartbeats; the block merges key-by-key over agents.defaults.heartbeat, so a partial block inherits the rest.
  • Heartbeats run full agent turns — shorter intervals burn more tokens.

agents.defaults.compaction

  • mode: default or safeguard (chunked summarization for long histories). See Compaction.
  • identifierPolicy: strict (default), off, or custom. strict prepends built-in opaque identifier retention guidance during compaction summarization.
  • identifierInstructions: optional custom identifier-preservation text used when identifierPolicy=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.
  • mode: "cache-ttl" enables pruning passes.
  • ttl controls 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.
Soft-trim keeps beginning + end and inserts ... 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 keepLastAssistants assistant messages exist, pruning is skipped.
  • Separately from pruning, any single tool result is capped at 400,000 text 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 of contextPruning.
See Session Pruning for behavior details.

Block streaming

  • Non-Telegram channels require explicit *.blockStreaming: true to enable block replies.
  • Channel overrides: channels.<channel>.blockStreamingCoalesce (and per-account variants). Signal/Slack/Discord/Google Chat default minChars: 1500.
  • humanDelay: randomized pause between block replies. natural = 800–2500ms. Per-agent override: agents.list[].humanDelay.
See Streaming for behavior + chunking details.

Typing indicators

  • Defaults: instant for direct chats/mentions, message for unmentioned group chats.
  • Per-session overrides: session.typingMode, session.typingIntervalSeconds.
See Typing Indicators.

agents.defaults.sandbox

Optional Docker sandboxing for the embedded agent. See Sandboxing for the full guide.
Workspace access:
  • none: per-scope sandbox workspace under ~/.openclaw/sandboxes
  • ro: sandbox workspace at /workspace, agent workspace mounted read-only at /agent
  • rw: agent workspace mounted read/write at /workspace
Scope:
  • session: per-session container + workspace
  • agent: 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.
  • network defaults to openclaw-sandbox-browser (dedicated bridge network). Set to bridge only when you explicitly want global bridge connectivity.
  • cdpSourceRange optionally restricts CDP ingress at the container edge to a CIDR range (for example 172.21.0.1/32).
  • sandbox.browser.binds mounts additional host directories into the sandbox browser container only. When set (including []), it replaces docker.binds for 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.sh and 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-gpu are enabled by default and can be disabled with OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 if WebGL/3D usage requires it.
    • OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 re-enables extensions if your workflow depends on them.
    • --renderer-process-limit=2 can be changed with OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>; set 0 to use Chromium’s default process limit.
    • plus --no-sandbox and --disable-setuid-sandbox when noSandbox is enabled.
    • Defaults are the container image baseline; use a custom browser image with a custom entrypoint to change container defaults.
Build images:

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 ## Team prompt section, agents_list returns it, and the Control UI shows it.
  • userFacing: whether people can reach the agent directly (default true). Set false for internal specialists. Config validation rejects an internal agent as the default agent, a bindings[] target, or a broadcast target, and rejects any internal agent when session.scope is "global" (all agents share one session there). User clients (web client) do not see it or its sessions and runs in agents.list, sessions.direct, sessions.list, or sessions.runs.list, do not receive events for its sessions, get it omitted from health and status agent 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_spawn with thread: true, /subagents spawn, /tell, /steer, /focus, and /acp cannot target it, /acp sessions hides 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 against session.identityLinks, so identity-scoped workspace lanes, memory, and plugins resolve for that person (default true). Set false to 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 overrides primary only; object form { primary, fallbacks } overrides both ([] disables global fallbacks). Cron jobs that only override primary still inherit default fallbacks unless you set fallbacks: [].
  • params: per-agent stream params merged over the selected model entry in agents.defaults.models. Use this for agent-specific overrides like cacheRetention, temperature, or maxTokens without duplicating the whole model catalog.
  • identity.avatar: workspace-relative path, http(s) URL, or data: URI.
  • identity.color: optional web client assistant colour. See agents.list[].identity.color below.
  • identity derives defaults: ackReaction from emoji, mentionPatterns from name/emoji.
  • subagents.allowAgents: per-agent allowlist of agent ids for sessions_spawn’s agentId parameter (["*"] = 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 (overrides agents.defaults.subagents.model).
  • subagents.thinking: per-agent default thinking level for spawned sub-agents (overrides agents.defaults.subagents.thinking).
  • subagents.completionDelivery: per-agent delivery mode for top-level sub-agent completions ("parent" or "direct"; overrides agents.defaults.subagents.completionDelivery). See Completion delivery.
  • tts: per-agent override of messages.tts (voice, provider, model, readAloud, …), deep-merged over the global config. Applies to read aloud, auto voice replies, /tts and the tts tool for this agent. A provider pinned with /tts provider still wins. See Per-agent TTS.
  • systemPrompt: per-agent prompt shape override. Merges over agents.defaults.systemPrompt by section key. When projectContext.files is set, that list replaces the default entirely (not merged). See agents.defaults.systemPrompt for the full field reference.
  • Sandbox inheritance guard: if the requester session is sandboxed, sessions_spawn rejects 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-tokens guarantees 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.md does not carry a colour.
  • Also carried on agents.list (the gateway RPC method) as identity.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.models to a real, bounded catalog. The model menu (models.list) lists the catalog entries named there, and sessions.patch and sessions.create’s optional model field (client-chat-v3 P2, ADR 0083/0084) accept those plus the agent’s own default model. agents.list[].model fallbacks do not widen or narrow either. Leaving agents.defaults.models empty lists the whole model catalog and admits any provider/model reference 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.
Defaults for enabled agents:
  • 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 in agents.list.
  • members: agent ids of the members (at least one); must be in agents.list and 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_spawn every member in addition to its own subagents.allowAgents, and agents_list includes them. Members get no new rights.
  • When the lead has the sessions_spawn tool, its system prompt gets a ## Team section listing each member’s id, name, and description. Control it with the team key in systemPrompt.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)
Deterministic match order:
  1. match.peer
  2. match.guildId
  3. match.teamId
  4. match.accountId (exact, no peer/guild/team)
  5. match.accountId: "*" (channel-wide)
  6. Default agent
Within each tier, the first matching bindings entry wins.

Per-agent access profiles

See Multi-Agent Sandbox & Tools for precedence details.

Session

  • 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 heartbeat identity attribution (matched case-insensitively; the run carries the stored key casing as its canonical identity). Keys starting with raw~ 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 as device:<deviceId>; link each device to a person with wednesdayai devices link <deviceId> --identity <key>, or pair it already linked with wednesdayai identity link <key> --qr (see Identities). Get ids from wednesdayai devices list --json (deviceId on each paired entry). Agents with workspace lanes deny unlinked devices.
  • reset: primary reset policy. daily resets at atHour local time; idle resets after idleMinutes. When both configured, whichever expires first wins.
  • resetByType: per-type overrides (direct, group, thread). Legacy dm accepted as alias for direct.
  • parentForkMaxTokens: max parent-session totalTokens allowed when creating a forked thread session (default 100000).
    • If parent totalTokens is above this value, WednesdayAI starts a fresh thread session instead of inheriting parent transcript history.
    • Set 0 to disable this guard and always allow parent forking.
  • mainKey: legacy field. Runtime now always uses "main" for the main direct-chat bucket.
  • sendPolicy: match by channel, chatType (direct|group|channel, with legacy dm alias), keyPrefix, or rawKeyPrefix. First deny wins. channel and chatType compare 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; keyPrefix and rawKeyPrefix match the key itself. A channel named in an agent request 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 cleared sendPolicy is seen. If the row was deleted while the request was in flight, the Gateway falls back to the stored sendPolicy, 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 contained raw~ bucket is a distinct key: a keyPrefix written for a linked person’s canonical key does not match their unlinked raw~<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: warn emits warnings only (default); enforce applies cleanup.
    • pruneAfter: index entries whose updatedAt is older than this are retired (tombstoned) in enforce mode (default 30d).
    • maxEntries: maximum number of session index rows to keep; the oldest are tombstoned beyond the cap (default 500).
    • The file-only controls rotateBytes, resetArchiveRetention, maxDiskBytes, and highWaterBytes are 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 uses channels.discord.threadBindings.enabled)
    • idleHours: default inactivity auto-unfocus in hours (0 disables; providers can override)
    • maxAgeHours: default hard max age in hours (0 disables; providers can override)
  • consumerClaims: session-consumer claim ledger settings. See Session Consumer Claims for full details.
    • sweepCadenceMs: reconciler sweep interval (default 60000 = 1min).
    • maxAttempts: DLQ threshold (default 5).
    • leaseMs: claim lease duration (default 30000 = 30s).
    • retryBaseMs: exponential backoff base (default 1000).

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).
  • backend: default backend (json, sqlite or postgres) for every config domain that ships it; domains that do not ship the selected backend stay on json. A sqlite or postgres value must match session.storage.backend and the gateway fails to start with storage.backend is "<backend>" but session storage is "<session>"; config domains live in the session database when they disagree. In this release no domain ships a SQL backend, so the gateway logs storage.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 with storage.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 release otherwise. A SQL override must equal session.storage.backend; a mismatch fails with storage domain "<id>" is "<backend>" but session storage is "<session>"; config domains live in the session database.
Changes under 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: Variables are case-insensitive. {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)

  • auto controls auto-TTS. /tts off|always|inbound|tagged overrides per session.
  • summaryModel overrides agents.defaults.model.primary for auto-summary.
  • modelOverrides is enabled by default; modelOverrides.allowProvider defaults to false (opt-in).
  • openai.baseUrl: OpenAI-compatible endpoint for OpenAI TTS (default https://api.openai.com/v1), overridable per agent with agents.list[].tts.openai.baseUrl. The OPENAI_TTS_BASE_URL env 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 the tts.speak gateway RPC (default true). Turn it off to stop on-demand synthesis spend; auto-TTS and /tts are unaffected. Overridden per agent by agents.list[].tts.readAloud.enabled. See Read aloud for chat clients.
  • Per-agent override: an agent’s agents.list[].tts block (same fields as messages.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_KEY and OPENAI_API_KEY.

Talk

Defaults for Talk mode (macOS/iOS/Android).
  • Voice IDs fall back to ELEVENLABS_VOICE_ID or SAG_VOICE_ID.
  • apiKey and providers.*.apiKey accept plaintext strings or SecretRef objects. Both are best-effort: an unresolvable ref warns (SECRETS_REF_OPTIONAL_UNRESOLVED) and does not fail gateway startup. talk.catalog then reports that provider unavailable with diagnostic: "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_KEY fallback applies only when no Talk API key is configured.
  • voiceAliases lets Talk directives use friendly names.
  • Cascaded Voice mode reuses talk.providers.<id>.modelId when set. When it is unset, Voice mode falls back to eleven_flash_v2_5, not the legacy Talk-command default eleven_v3 shown 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.
Numeric fields (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|full stores state per session; inline directives apply to single message.
  • Elevated exec runs 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 >= criticalThreshold or criticalThreshold >= 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):
Provider entry (type: "provider" or omitted):
  • provider: API provider id (openai, anthropic, google/gemini, groq, etc.)
  • model: model id override
  • profile / preferredProfile: auth-profiles.json profile selection
CLI entry (type: "cli"):
  • command: executable to run
  • args: templated args (supports {{MediaPath}}, {{Prompt}}, {{MaxChars}}, etc.)
Common fields:
  • 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.
Provider auth follows standard order: 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).
Notes:
  • 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 requires tools.agentToAgent.
  • Sandbox clamp: when the current session is sandboxed and agents.defaults.sandbox.sessionToolsVisibility="spawned", visibility is forced to tree even if tools.sessions.visibility="all".

tools.sessions_spawn

Controls inline attachment support for sessions_spawn.
Notes:
  • 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 0700 for directories and 0600 for files.
  • Cleanup follows the cleanup policy: delete always removes attachments; keep retains them only when retainOnSessionKeep: 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 by agents.list[].subagents.model and globally by agents.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. At maxSpawnDepth >= 2, depth-1 orchestrators additionally receive sessions_spawn, subagents, sessions_list, sessions_history.
For runtime tuning (depth, concurrency, timeouts, archive), see agents.defaults.subagents.* above.

Custom providers and base URLs

WednesdayAI uses the pi-coding-agent model catalog. Add custom providers via models.providers in config or ~/.openclaw/agents/<agentId>/agent/models.json.
  • Use authHeader: true + headers for custom auth needs.
  • Override agent config root with OPENCLAW_AGENT_DIR (or PI_CODING_AGENT_DIR).
  • Merge precedence for matching provider IDs:
    • Non-empty agent models.json apiKey/baseUrl win.
    • Empty or missing agent apiKey/baseUrl fall back to models.providers in config.
    • Matching model contextWindow/maxTokens use the higher value between explicit config and implicit catalog values.
    • Use models.mode: "replace" when you want config to fully rewrite models.json.

Provider field details

  • models.mode: provider catalog behavior (merge or replace).
  • 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, inject options.num_ctx into requests (default: true).
  • models.providers.*.authHeader: force credential transport in the Authorization header 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. For api: "openai-completions" with a non-empty non-native baseUrl (host not api.openai.com), WednesdayAI forces this to false at runtime. Empty/omitted baseUrl keeps 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

Use cerebras/zai-glm-4.7 for Cerebras; zai/glm-4.7 for Z.AI direct.
Set OPENCODE_API_KEY (or OPENCODE_ZEN_API_KEY). Shortcut: wednesdayai onboard --auth-choice opencode-zen.
Set 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.
For the China endpoint: baseUrl: "https://api.moonshot.cn/v1" or wednesdayai onboard --auth-choice moonshot-api-key-cn.
Anthropic-compatible, built-in provider. Shortcut: wednesdayai onboard --auth-choice kimi-code-api-key.
Base URL should omit /v1 (Anthropic client appends it). Shortcut: wednesdayai onboard --auth-choice synthetic-api-key.
Set MINIMAX_API_KEY. Shortcut: wednesdayai onboard --auth-choice minimax-api.
See Local Models. TL;DR: run MiniMax M2.5 via LM Studio Responses API on serious hardware; keep hosted models merged for fallback.

Skills

  • allowBundled: optional allowlist for bundled skills only (managed/workspace skills unaffected).
  • entries.<skillKey>.enabled: false disables 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 by wednesdayai skills commands to locate install sources. Mirrors plugins.installs:
    • source is one of npm, archive, path, or bundled; catalog installs use archive.
    • spec is the catalog id (or the original spec for non-catalog installs).
    • installPath is 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, plus plugins.load.paths.
  • Config changes require a gateway restart.
  • allow: optional allowlist (only listed plugins load). deny wins.
  • 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 through api.runtime.signals.nudge; default deny. Each wake is a durable agent.turn nudge. 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. Unlike plugins.slots.memory there is no default id: unset means the first loaded context-engine plugin wins.
  • plugins.hookTimeouts: per-hook timeout in milliseconds. Keys are hook names or default. Unset hooks use 30000 ms. Registration api.on(..., { timeoutMs }) still wins. Restart required.
  • plugins.analysisConcurrency.maxParallel: concurrent awaited analysis.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 for context.* hooks only, used when hookTimeouts does not cover that hook. Restart required.
  • plugins.installs: CLI-managed install metadata used by wednesdayai plugins update.
    • source is one of npm, archive, path, or bundled.
    • source: "bundled" means the plugin is loaded from the bundled extension copy that shipped with the current WednesdayAI package. sourcePath must 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.
Gateway validation treats missing plugin references in 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: false disables act:evaluate and wait --fn.
  • ssrfPolicy.dangerouslyAllowPrivateNetwork defaults to true when unset (trusted-network model).
  • Set ssrfPolicy.dangerouslyAllowPrivateNetwork: false for strict public-only browser navigation.
  • ssrfPolicy.allowPrivateNetwork remains supported as a legacy alias.
  • In strict mode, use ssrfPolicy.hostnameAllowlist and ssrfPolicy.allowedHostnames for explicit exceptions.
  • ssrfPolicy.allowedCidrs allows specific IPv4/IPv6 CIDR ranges for private/internal addresses.
  • ssrfPolicy.allowRfc2544BenchmarkRange additionally 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, default 18791).
  • extraArgs appends 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 by wednesdayai security audit and logged at startup. Use allowedCidrs instead where possible.
  • network.ssrfPolicy.allowPrivateNetwork: legacy alias for dangerouslyAllowPrivateNetwork.
  • 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.
See Network egress policy for the full security rationale and worked examples.

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

  • mode: local (run gateway) or remote (connect to remote gateway). Gateway refuses to start unless local.
  • 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), or custom.
  • 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 loopback bind listens on 127.0.0.1 inside the container. With Docker bridge networking (-p 18789:18789), traffic arrives on eth0, so the gateway is unreachable. Use --network host, or set bind: "lan" (or bind: "custom" with customBindHost: "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 from gateway.trustedProxies (see Trusted Proxy Auth).
  • Ambient auth still verifies device tokens: under none, trusted-proxy or Tailscale identity auth, a connect that presents auth.deviceToken gets it verified as under token mode; a revoked, unknown or over-scoped token is refused with AUTH_DEVICE_TOKEN_MISMATCH. auth.token is not treated as a device credential in those modes. See Protocol.
  • The openclaw-user-client web client is exempt from every ambient auth mode: under none, trusted-proxy and 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: when true, Tailscale Serve identity headers can satisfy Control UI/WebSocket auth (verified via tailscale whois); HTTP API endpoints still require token/password auth. This tokenless flow assumes the gateway host is trusted. Defaults to true when tailscale.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 return 429 + Retry-After.
    • gateway.auth.rateLimit.exemptLoopback defaults to true; set false when 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) or funnel (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, unless dangerouslyAllowHostHeaderOriginFallback is set. Onboarding and gateway startup seed http://localhost:<port> and http://127.0.0.1:<port> (plus the custom bind host) when none are configured. gateway.controlUi is the admission and auth policy for the openclaw-control-ui console 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 to controlUi.allowedOrigins when 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 to openclaw.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 the openclaw-user-client web client. This check always runs for that client id, even when reverse-proxy headers are present, and controlUi.allowedOrigins never 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, at webClient.basePath. Default false: 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.basePath when 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 set basePath, 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. Set basePath: "/client" to keep the old address. gateway.* changes need a gateway restart. See Web client hosting.
  • webClient.root: directory holding the built bundle (index.html plus assets/). Optional: with webClient.enabled true and no root, the gateway serves the bundle packaged with this install (dist/web-client), and answers 503 naming the build command only when that is missing too. An explicit root always wins - including when it is broken, which answers 503 with that reason rather than silently falling back.
  • webClient.imageOrigins: exact https://host[:port] origins that remote markdown images may load from in the gateway-served web client, extended into its CSP img-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 /link codes (web client Account menu → Linked accounts → identity.link.claim). Default true. Set false to keep all linking operator-only: /link and the claim RPC both answer Account 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 (manifest chatUi.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.request injects 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, at controlUiV2.basePath. Default true: the v2 console is the daily console and owns the gateway root. Set it to false to serve no operator console. The classic console was removed (ADR 1771), so gateway.controlUi is admission-only and controlUiV2 is the only console mount. The console connects as the openclaw-control-ui client, so admission, scopes and auth modes are governed by controlUi.allowedOrigins and friends; there is no separate allowlist. A non-loopback bind with the console enabled still requires controlUi.allowedOrigins at startup. See Control UI v2.
  • controlUiV2.basePath: public path the console is mounted under. Default: the gateway root; the v2 console mounts at /v2/control instead when an enabled webClient explicitly claims / with its basePath, 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.html plus assets/). Optional: unset, the gateway serves the bundle packaged with this install (dist/control-ui-v2) and answers 503 naming pnpm control:build:packaged only when that is missing too. An explicit root always wins - including when it is broken, which answers 503 with that reason.
  • controlUiV2.pluginUi.allow: plugin ids whose browser module (manifest controlUi.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) or direct (ws/wss). For direct, remote.url must be ws:// or wss://.
  • OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1: client-side break-glass override that allows plaintext ws:// to trusted private-network IPs; default remains loopback-only for plaintext.
  • gateway.remote.token / .password are remote-client credential fields. They do not configure gateway auth by themselves.
  • Local gateway call paths can use gateway.remote.* as fallback when gateway.auth.* is unset.
  • trustedProxies: reverse proxy IPs that terminate TLS. Only list proxies you control.
  • allowRealIpFallback: when true, the gateway accepts X-Real-IP if X-Forwarded-For is missing. Default false for fail-closed behavior.
  • gateway.tools.deny: extra tool names blocked for HTTP POST /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 by devices list and nodes status, and may be archived by devices 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. Default 90.
  • gateway.devices.activityIntervalMinutes: minutes between last-active writes for a connection that stays open. Connect and disconnect always write. Default 5. Separately, a device token’s lastUsedAtMs is written at most once every 5 minutes (fixed).

Session steering defaults

  • gateway.sessions.steer.defaultMode: mode the sessions.steer RPC applies when the caller omits mode. 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 long sessions.steer with mode: "interrupt" waits for the aborted run to reach a terminal state before failing the call. Integer, 0 or more; default 15000. The replacement turn is never started past this point, so a session cannot end up with two concurrent runs.
The web client always sends an explicit 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.maxUrlParts
    • gateway.http.endpoints.responses.files.urlAllowlist
    • gateway.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:
Convenience flags: --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.
Disable on the node: nodeHost.browserProxy.enabled=false. Disable on the gateway: gateway.nodes.browser.mode="off".

Hooks

Auth: 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? }
    • sessionKey from request payload is accepted only when hooks.allowRequestSessionKey=true (default: false).
  • POST /hooks/<name> → resolved via hooks.mappings
  • match.path matches sub-path after /hooks (e.g. /hooks/gmail → gmail).
  • match.source matches a payload field for generic paths.
  • Templates like {{messages[0].subject}} read from the payload.
  • transform can point to a JS/TS module returning a hook action.
    • transform.module must be a relative path and stays within hooks.transformsDir (absolute paths and traversal are rejected).
  • agentId routes 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 explicit sessionKey.
  • allowRequestSessionKey: allow /hooks/agent callers to set sessionKey (default: false).
  • allowedSessionKeyPrefixes: optional prefix allowlist for explicit sessionKey values (request + mapping), e.g. ["hook:"].
  • deliver: true sends final reply to a channel; channel defaults to last.
  • model overrides LLM for this hook run (must be allowed if model catalog is set).

Gmail integration

  • Gateway auto-starts gog gmail watch serve on boot when configured. Set OPENCLAW_SKIP_GMAIL_WATCHER=1 to disable.
  • Don’t run a separate gog gmail watch serve alongside 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.html when empty.
  • Also serves A2UI at /__openclaw__/a2ui/.
  • Changes require a gateway restart.
  • Disable live reload for large directories or EMFILE errors.

Discovery

mDNS (Bonjour)

  • minimal (default): omit cliPath + sshPort from TXT records.
  • full: include cliPath + sshPort.
  • Hostname defaults to openclaw. Override with OPENCLAW_MDNS_HOSTNAME.

Wide-area (DNS-SD)

Writes a unicast DNS-SD zone under ~/.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.
  • .env files: 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 behind wednesdayai plugins install <id> and wednesdayai skills install <id>. Full list and precedence: Environment. With 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:
Validation:
  • provider pattern: ^[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 apply targets supported openclaw.json credential paths.
  • auth-profiles.json refs are included in runtime resolution and audit coverage.

Secret providers config

Notes:
  • file provider supports mode: "json" and mode: "singleValue" (id must be "value" in singleValue mode).
  • exec provider requires an absolute command path and uses protocol payloads on stdin/stdout.
  • By default, symlink command paths are rejected. Set allowSymlinkCommand: true to allow symlink paths while validating the resolved target path.
  • If trustedDirs is configured, the trusted-dir check applies to the resolved target path.
  • exec child environment is minimal by default; pass required variables explicitly with passEnv.
  • 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.json supports value-level refs (keyRef for api_key, tokenRef for token).
  • Static runtime credentials come from in-memory resolved snapshots; legacy static auth.json entries are scrubbed when discovered.
  • Legacy OAuth imports from ~/.openclaw/credentials/oauth.json.
  • See OAuth.
  • Secrets runtime behavior and audit/configure/apply tooling: Secrets Management.

Logging

  • Default log file: /tmp/openclaw/openclaw-YYYY-MM-DD.log.
  • Set logging.file for a stable path.
  • logging.maxFileBytes and logging.maxBackups remain aliases for the primary file-log profile.
  • logging.fileLogs.defaults applies shared file-log defaults for durable diagnostic and audit logs.
  • logging.fileLogs.profiles.<profileId> overrides one named log. Supported built-in profiles:
    • primary: main openclaw-YYYY-MM-DD.log runtime log.
    • cron.run: cron run JSONL logs under cron/runs/<jobId>.jsonl.
    • config.audit: config write audit log at logs/config-audit.jsonl.
    • hooks.command: bundled command logger output at logs/commands.log.
    • agents.rawStream: PI raw stream diagnostic JSONL.
    • extensions.learningCore: learning-core active JSONL log.
    • extensions.voiceCall.calls: voice-call legacy calls.jsonl store.
  • File-log profile fields: file, maxFileBytes, maxBackups, compress, maxQueuedBytes, keepLines, and mode.
  • Default profile values are maxFileBytes: 10485760, maxBackups: 5, compress: "gzip", maxQueuedBytes: 1048576, and mode: "jsonl".
  • maxFileBytes and maxQueuedBytes must be positive integers. maxBackups must be a non-negative integer; 0 means rotate by truncating without retaining backups.
  • compress: false keeps plaintext numbered backups such as .1; compress: "gzip" writes .1.gz backups.
  • Profile merge order is built-in defaults, logging.fileLogs.defaults, call-site defaults, primary legacy aliases for the primary profile, then logging.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, and extensions.voiceCall.calls, use profile fields such as maxFileBytes, maxBackups, compress, and maxQueuedBytes; file is intentionally ignored.
  • maxQueuedBytes bounds 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.
  • consoleLevel bumps to debug when --verbose.

CLI

  • cli.banner.taglineMode controls 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

Written by the macOS onboarding assistant. Derives defaults:
  • messages.ackReaction from identity.emoji (falls back to 👀)
  • mentionPatterns from identity.name/identity.emoji
  • avatar accepts: workspace-relative path, http(s) URL, or data: URI
  • color is optional and only affects the web client; see agents.list[].identity.color for the palette and the agents.defaults.models advice

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

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; set false to disable.
  • runLog.maxBytes: max size per run log file (cron/runs/<jobId>.jsonl) before pruning. Default: 2_000_000 bytes.
  • 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 have notify: true.
See Cron Jobs.

Media model template variables

Template placeholders expanded in tools.media.models[].args:

Config includes ($include)

Split config into multiple files:
Merge behavior:
  • 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 (dirname of openclaw.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