Configuration reference

Core config reference for

. For a task-oriented overview, see Configuration.

Covers the main OpenClaw config surfaces and links out when a subsystem has its own deeper reference. Channel- and plugin-owned command catalogs and deep memory/QMD knobs live on their own pages rather than on this one.

Code truth:

• text

  Copy

  openclaw config schema
  prints the live JSON Schema used for validation and Control UI, with bundled/plugin/channel metadata merged in when available
• text

  Copy

  config.schema.lookup
  returns one path-scoped schema node for drill-down tooling
• text

  Copy

  pnpm config:docs:check
  /
  text

  Copy

  pnpm config:docs:gen
  validate the config-doc baseline hash against the current schema surface

Agent lookup path: use the

tool action for exact field-level docs and constraints before edits. Use Configuration for task-oriented guidance and this page for the broader field map, defaults, and links to subsystem references.

Dedicated deep references:

• Memory configuration reference for
  text

  Copy

  agents.defaults.memorySearch.*
  ,
  text

  Copy

  memory.qmd.*
  ,
  text

  Copy

  memory.citations
  , and dreaming config under
  text

  Copy

  plugins.entries.memory-core.config.dreaming
• Slash commands for the current built-in + bundled command catalog
• owning channel/plugin pages for channel-specific command surfaces

Config format is JSON5 (comments + trailing commas allowed). All fields are optional — OpenClaw uses safe defaults when omitted.

---

Channels

Per-channel config keys moved to a dedicated page — see Configuration — channels for

, including Slack, Discord, Telegram, WhatsApp, Matrix, iMessage, and other bundled channels (auth, access control, multi-account, mention gating).

Agent defaults, multi-agent, sessions, and messages

Moved to a dedicated page — see Configuration — agents for:

• text

  Copy

  agents.defaults.*
  (workspace, model, thinking, heartbeat, memory, media, skills, sandbox)
• text

  Copy

  multiAgent.*
  (multi-agent routing and bindings)
• text

  Copy

  session.*
  (session lifecycle, compaction, pruning)
• text

  Copy

  messages.*
  (message delivery, TTS, markdown rendering)
• text

  Copy

  talk.*
  (Talk mode)
  • text

    Copy

    talk.speechLocale
    : optional BCP 47 locale id for Talk speech recognition on iOS/macOS
  • text

    Copy

    talk.silenceTimeoutMs
    : when unset, Talk keeps the platform default pause window before sending the transcript (
    text

    Copy

    700 ms on macOS and Android, 900 ms on iOS
    )

Tools and custom providers

Tool policy, experimental toggles, provider-backed tool config, and custom provider / base-URL setup moved to a dedicated page — see Configuration — tools and custom providers.

Models

Provider definitions, model allowlists, and custom provider setup live in Configuration — tools and custom providers. The

root also owns global model-catalog behavior.

json5
Copy
{
  models: {
    // Optional. Default: true. Requires a Gateway restart when changed.
    pricing: { enabled: false },
  },
}

• text

  Copy

  models.mode
  : provider catalog behavior (
  text

  Copy

  merge
  or
  text

  Copy

  replace
  ).
• text

  Copy

  models.providers
  : custom provider map keyed by provider id.
• text

  Copy

  models.pricing.enabled
  : controls the background pricing bootstrap. When
  text

  Copy

  false
  , Gateway startup skips OpenRouter and LiteLLM pricing-catalog fetches; configured
  text

  Copy

  models.providers.*.models[].cost
  values still work for local cost estimates.

MCP

OpenClaw-managed MCP server definitions live under

and are consumed by embedded Pi and other runtime adapters. The , , , and commands manage this block without connecting to the target server during config edits.

json5
Copy
{
  mcp: {
    // Optional. Default: 600000 ms (10 minutes). Set 0 to disable idle eviction.
    sessionIdleTtlMs: 600000,
    servers: {
      docs: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-fetch"],
      },
      remote: {
        url: "https://example.com/mcp",
        transport: "streamable-http", // streamable-http | sse
        headers: {
          Authorization: "Bearer ${MCP_REMOTE_TOKEN}",
        },
      },
    },
  },
}

• text

  Copy

  mcp.servers
  : named stdio or remote MCP server definitions for runtimes that expose configured MCP tools. Remote entries use
  text

  Copy

  transport: "streamable-http"
  or
  text

  Copy

  transport: "sse"
  ;
  text

  Copy

  type: "http"
  is a CLI-native alias that
  text

  Copy

  openclaw mcp set
  and
  text

  Copy

  openclaw doctor --fix
  normalize into the canonical
  text

  Copy

  transport
  field.
• text

  Copy

  mcp.sessionIdleTtlMs
  : idle TTL for session-scoped bundled MCP runtimes. One-shot embedded runs request run-end cleanup; this TTL is the backstop for long-lived sessions and future callers.
• Changes under
  text

  Copy

  mcp.*
  hot-apply by disposing cached session MCP runtimes. The next tool discovery/use recreates them from the new config, so removed
  text

  Copy

  mcp.servers
  entries are reaped immediately instead of waiting for idle TTL.

See MCP and CLI backends for runtime behavior.

Skills

json5
Copy
{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
    },
    install: {
      preferBrew: true,
      nodeManager: "npm", // npm | pnpm | yarn | bun
    },
    entries: {
      "image-lab": {
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string
        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

• text

  Copy

  allowBundled
  : optional allowlist for bundled skills only (managed/workspace skills unaffected).
• text

  Copy

  load.extraDirs
  : extra shared skill roots (lowest precedence).
• text

  Copy

  install.preferBrew
  : when true, prefer Homebrew installers when
  text

  Copy

  brew
  is available before falling back to other installer kinds.
• text

  Copy

  install.nodeManager
  : node installer preference for
  text

  Copy

  metadata.openclaw.install
  specs (
  text

  Copy

  npm
  |
  text

  Copy

  pnpm
  |
  text

  Copy

  yarn
  |
  text

  Copy

  bun
  ).
• text

  Copy

  entries.<skillKey>.enabled: false
  disables a skill even if bundled/installed.
• text

  Copy

  entries.<skillKey>.apiKey
  : convenience for skills declaring a primary env var (plaintext string or SecretRef object).

---

Plugins

json5
Copy
{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    deny: [],
    load: {
      paths: ["~/Projects/oss/voice-call-plugin"],
    },
    entries: {
      "voice-call": {
        enabled: true,
        hooks: {
          allowPromptInjection: false,
        },
        config: { provider: "twilio" },
      },
    },
  },
}

• Loaded from
  text

  Copy

  ~/.openclaw/extensions
  ,
  text

  Copy

  <workspace>/.openclaw/extensions
  , plus
  text

  Copy

  plugins.load.paths
  .
• Discovery accepts native OpenClaw plugins plus compatible Codex bundles and Claude bundles, including manifestless Claude default-layout bundles.
• Config changes require a gateway restart.
• text

  Copy

  allow
  : optional allowlist (only listed plugins load).
  text

  Copy

  deny
  wins.
• text

  Copy

  plugins.entries.<id>.apiKey
  : plugin-level API key convenience field (when supported by the plugin).
• text

  Copy

  plugins.entries.<id>.env
  : plugin-scoped env var map.
• text

  Copy

  plugins.entries.<id>.hooks.allowPromptInjection
  : when
  text

  Copy

  false
  , core blocks
  text

  Copy

  before_prompt_build
  and ignores prompt-mutating fields from legacy
  text

  Copy

  before_agent_start
  , while preserving legacy
  text

  Copy

  modelOverride
  and
  text

  Copy

  providerOverride
  . Applies to native plugin hooks and supported bundle-provided hook directories.
• text

  Copy

  plugins.entries.<id>.hooks.allowConversationAccess
  : when
  text

  Copy

  true
  , trusted non-bundled plugins may read raw conversation content from typed hooks such as
  text

  Copy

  llm_input
  ,
  text

  Copy

  llm_output
  ,
  text

  Copy

  before_agent_finalize
  , and
  text

  Copy

  agent_end
  .
• text

  Copy

  plugins.entries.<id>.subagent.allowModelOverride
  : explicitly trust this plugin to request per-run
  text

  Copy

  provider
  and
  text

  Copy

  model
  overrides for background subagent runs.
• text

  Copy

  plugins.entries.<id>.subagent.allowedModels
  : optional allowlist of canonical
  text

  Copy

  provider/model
  targets for trusted subagent overrides. Use
  text

  Copy

  "*"
  only when you intentionally want to allow any model.
• text

  Copy

  plugins.entries.<id>.config
  : plugin-defined config object (validated by native OpenClaw plugin schema when available).
• Channel plugin account/runtime settings live under
  text

  Copy

  channels.<id>
  and should be described by the owning plugin's manifest
  text

  Copy

  channelConfigs
  metadata, not by a central OpenClaw option registry.
• text

  Copy

  plugins.entries.firecrawl.config.webFetch
  : Firecrawl web-fetch provider settings.
  • text

    Copy

    apiKey
    : Firecrawl API key (accepts SecretRef). Falls back to
    text

    Copy

    plugins.entries.firecrawl.config.webSearch.apiKey
    , legacy
    text

    Copy

    tools.web.fetch.firecrawl.apiKey
    , or
    text

    Copy

    FIRECRAWL_API_KEY
    env var.
  • text

    Copy

    baseUrl
    : Firecrawl API base URL (default:
    text

    Copy

    https://api.firecrawl.dev
    ).
  • text

    Copy

    onlyMainContent
    : extract only the main content from pages (default:
    text

    Copy

    true
    ).
  • text

    Copy

    maxAgeMs
    : maximum cache age in milliseconds (default:
    text

    Copy

    172800000
    / 2 days).
  • text

    Copy

    timeoutSeconds
    : scrape request timeout in seconds (default:
    text

    Copy

    60
    ).
• text

  Copy

  plugins.entries.xai.config.xSearch
  : xAI X Search (Grok web search) settings.
  • text

    Copy

    enabled
    : enable the X Search provider.
  • text

    Copy

    model
    : Grok model to use for search (e.g.
    text

    Copy

    "grok-4-1-fast"
    ).
• text

  Copy

  plugins.entries.memory-core.config.dreaming
  : memory dreaming settings. See Dreaming for phases and thresholds.
  • text

    Copy

    enabled
    : master dreaming switch (default
    text

    Copy

    false
    ).
  • text

    Copy

    frequency
    : cron cadence for each full dreaming sweep (
    text

    Copy

    "0 3 * * *"
    by default).
  • text

    Copy

    model
    : optional Dream Diary subagent model override. Requires
    text

    Copy

    plugins.entries.memory-core.subagent.allowModelOverride: true
    ; pair with
    text

    Copy

    allowedModels
    to restrict targets. Model-unavailable errors retry once with the session default model; trust or allowlist failures do not fall back silently.
  • phase policy and thresholds are implementation details (not user-facing config keys).
• Full memory config lives in Memory configuration reference:
  • text

    Copy

    agents.defaults.memorySearch.*
  • text

    Copy

    memory.backend
  • text

    Copy

    memory.citations
  • text

    Copy

    memory.qmd.*
  • text

    Copy

    plugins.entries.memory-core.config.dreaming
• Enabled Claude bundle plugins can also contribute embedded Pi defaults from
  text

  Copy

  settings.json
  ; OpenClaw applies those as sanitized agent settings, not as raw OpenClaw config patches.
• text

  Copy

  plugins.slots.memory
  : pick the active memory plugin id, or
  text

  Copy

  "none"
  to disable memory plugins.
• text

  Copy

  plugins.slots.contextEngine
  : pick the active context engine plugin id; defaults to
  text

  Copy

  "legacy"
  unless you install and select another engine.

See Plugins.

---

Browser

json5
Copy
{
  browser: {
    enabled: true,
    evaluateEnabled: true,
    defaultProfile: "user",
    ssrfPolicy: {
      // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access
      // allowPrivateNetwork: true, // legacy alias
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    tabCleanup: {
      enabled: true,
      idleMinutes: 120,
      maxTabsPerSession: 8,
      sweepMinutes: 5,
    },
    profiles: {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      work: {
        cdpPort: 18801,
        color: "#0066CC",
        executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
      },
      user: { driver: "existing-session", attachOnly: true, color: "#00AA00" },
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
    color: "#FF4500",
    // headless: false,
    // noSandbox: false,
    // extraArgs: [],
    // executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    // attachOnly: false,
  },
}

• text

  Copy

  evaluateEnabled: false
  disables
  text

  Copy

  act:evaluate
  and
  text

  Copy

  wait --fn
  .
• text

  Copy

  tabCleanup
  reclaims tracked primary-agent tabs after idle time or when a session exceeds its cap. Set
  text

  Copy

  idleMinutes: 0
  or
  text

  Copy

  maxTabsPerSession: 0
  to disable those individual cleanup modes.
• text

  Copy

  ssrfPolicy.dangerouslyAllowPrivateNetwork
  is disabled when unset, so browser navigation stays strict by default.
• Set
  text

  Copy

  ssrfPolicy.dangerouslyAllowPrivateNetwork: true
  only when you intentionally trust private-network browser navigation.
• In strict mode, remote CDP profile endpoints (
  text

  Copy

  profiles.*.cdpUrl
  ) are subject to the same private-network blocking during reachability/discovery checks.
• text

  Copy

  ssrfPolicy.allowPrivateNetwork
  remains supported as a legacy alias.
• In strict mode, use
  text

  Copy

  ssrfPolicy.hostnameAllowlist
  and
  text

  Copy

  ssrfPolicy.allowedHostnames
  for explicit exceptions.
• Remote profiles are attach-only (start/stop/reset disabled).
• text

  Copy

  profiles.*.cdpUrl
  accepts
  text

  Copy

  http://
  ,
  text

  Copy

  https://
  ,
  text

  Copy

  ws://
  , and
  text

  Copy

  wss://
  . Use HTTP(S) when you want OpenClaw to discover
  text

  Copy

  /json/version
  ; use WS(S) when your provider gives you a direct DevTools WebSocket URL.
• text

  Copy

  remoteCdpTimeoutMs
  and
  text

  Copy

  remoteCdpHandshakeTimeoutMs
  apply to remote and
  text

  Copy

  attachOnly
  CDP reachability plus tab-opening requests. Managed loopback profiles keep local CDP defaults.
• If an externally managed CDP service is reachable through loopback, set that profile's
  text

  Copy

  attachOnly: true
  ; otherwise OpenClaw treats the loopback port as a local managed browser profile and may report local port ownership errors.
• text

  Copy

  existing-session
  profiles use Chrome MCP instead of CDP and can attach on the selected host or through a connected browser node.
• text

  Copy

  existing-session
  profiles can set
  text

  Copy

  userDataDir
  to target a specific Chromium-based browser profile such as Brave or Edge.
• text

  Copy

  existing-session
  profiles keep the current Chrome MCP route limits: snapshot/ref-driven actions instead of CSS-selector targeting, one-file upload hooks, no dialog timeout overrides, no
  text

  Copy

  wait --load networkidle
  , and no
  text

  Copy

  responsebody
  , PDF export, download interception, or batch actions.
• Local managed
  text

  Copy

  openclaw
  profiles auto-assign
  text

  Copy

  cdpPort
  and
  text

  Copy

  cdpUrl
  ; only set
  text

  Copy

  cdpUrl
  explicitly for remote CDP.
• Local managed profiles can set
  text

  Copy

  executablePath
  to override the global
  text

  Copy

  browser.executablePath
  for that profile. Use this to run one profile in Chrome and another in Brave.
• Local managed profiles use
  text

  Copy

  browser.localLaunchTimeoutMs
  for Chrome CDP HTTP discovery after process start and
  text

  Copy

  browser.localCdpReadyTimeoutMs
  for post-launch CDP websocket readiness. Raise them on slower hosts where Chrome starts successfully but readiness checks race startup. Both values must be positive integers up to
  text

  Copy

  120000
  ms; invalid config values are rejected.
• Auto-detect order: default browser if Chromium-based → Chrome → Brave → Edge → Chromium → Chrome Canary.
• text

  Copy

  browser.executablePath
  and
  text

  Copy

  browser.profiles.<name>.executablePath
  both accept
  text

  Copy

  ~
  and
  text

  Copy

  ~/...
  for your OS home directory before Chromium launch. Per-profile
  text

  Copy

  userDataDir
  on
  text

  Copy

  existing-session
  profiles is also tilde-expanded.
• Control service: loopback only (port derived from
  text

  Copy

  gateway.port
  , default
  text

  Copy

  18791
  ).
• text

  Copy

  extraArgs
  appends extra launch flags to local Chromium startup (for example
  text

  Copy

  --disable-gpu
  , window sizing, or debug flags).

---

UI

json5
Copy
{
  ui: {
    seamColor: "#FF4500",
    assistant: {
      name: "OpenClaw",
      avatar: "CB", // emoji, short text, image URL, or data URI
    },
  },
}

• text

  Copy

  seamColor
  : accent color for native app UI chrome (Talk Mode bubble tint, etc.).
• text

  Copy

  assistant
  : Control UI identity override. Falls back to active agent identity.

---

Gateway

json5
Copy
{
  gateway: {
    mode: "local", // local | remote
    port: 18789,
    bind: "loopback",
    auth: {
      mode: "token", // none | token | password | trusted-proxy
      token: "your-token",
      // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD
      // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth
      allowTailscale: true,
      rateLimit: {
        maxAttempts: 10,
        windowMs: 60000,
        lockoutMs: 300000,
        exemptLoopback: true,
      },
    },
    tailscale: {
      mode: "off", // off | serve | funnel
      resetOnExit: false,
    },
    controlUi: {
      enabled: true,
      basePath: "/openclaw",
      // root: "dist/control-ui",
      // embedSandbox: "scripts", // strict | scripts | trusted
      // allowExternalEmbedUrls: false, // dangerous: allow absolute external http(s) embed URLs
      // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI
      // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode
      // allowInsecureAuth: false,
      // dangerouslyDisableDeviceAuth: false,
    },
    remote: {
      url: "ws://gateway.tailnet:18789",
      transport: "ssh", // ssh | direct
      token: "your-token",
      // password: "your-password",
    },
    trustedProxies: ["10.0.0.1"],
    // Optional. Default false.
    allowRealIpFallback: false,
    nodes: {
      pairing: {
        // Optional. Default unset/disabled.
        autoApproveCidrs: ["192.168.1.0/24", "fd00:1234:5678::/64"],
      },
      allowCommands: ["canvas.navigate"],
      denyCommands: ["system.run"],
    },
    tools: {
      // Additional /tools/invoke HTTP denies
      deny: ["browser"],
      // Remove tools from the default HTTP deny list
      allow: ["gateway"],
    },
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          timeoutMs: 10000,
        },
      },
    },
  },
}

OpenAI-compatible endpoints

• Chat Completions: disabled by default. Enable with
  text

  Copy

  gateway.http.endpoints.chatCompletions.enabled: true
  .
• Responses API:
  text

  Copy

  gateway.http.endpoints.responses.enabled
  .
• Responses URL-input hardening:
  • text

    Copy

    gateway.http.endpoints.responses.maxUrlParts
  • text

    Copy

    gateway.http.endpoints.responses.files.urlAllowlist
  • text

    Copy

    gateway.http.endpoints.responses.images.urlAllowlist
    Empty allowlists are treated as unset; use
    text

    Copy

    gateway.http.endpoints.responses.files.allowUrl=false
    and/or
    text

    Copy

    gateway.http.endpoints.responses.images.allowUrl=false
    to disable URL fetching.
• Optional response hardening header:
  • text

    Copy

    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:

bash
Copy
OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
OPENCLAW_STATE_DIR=~/.openclaw-a \
openclaw gateway --port 19001

Convenience flags:

(uses + port ), (uses ).

See Multiple Gateways.

text

Copy

gateway.tls

json5
Copy
{
  gateway: {
    tls: {
      enabled: false,
      autoGenerate: false,
      certPath: "/etc/openclaw/tls/server.crt",
      keyPath: "/etc/openclaw/tls/server.key",
      caPath: "/etc/openclaw/tls/ca-bundle.crt",
    },
  },
}

• text

  Copy

  enabled
  : enables TLS termination at the gateway listener (HTTPS/WSS) (default:
  text

  Copy

  false
  ).
• text

  Copy

  autoGenerate
  : auto-generates a local self-signed cert/key pair when explicit files are not configured; for local/dev use only.
• text

  Copy

  certPath
  : filesystem path to the TLS certificate file.
• text

  Copy

  keyPath
  : filesystem path to the TLS private key file; keep permission-restricted.
• text

  Copy

  caPath
  : optional CA bundle path for client verification or custom trust chains.

text

Copy

gateway.reload

json5
Copy
{
  gateway: {
    reload: {
      mode: "hybrid", // off | restart | hot | hybrid
      debounceMs: 500,
      deferralTimeoutMs: 300000,
    },
  },
}

• text

  Copy

  mode
  : controls how config edits are applied at runtime.
  • text

    Copy

    "off"
    : ignore live edits; changes require an explicit restart.
  • text

    Copy

    "restart"
    : always restart the gateway process on config change.
  • text

    Copy

    "hot"
    : apply changes in-process without restarting.
  • text

    Copy

    "hybrid"
    (default): try hot reload first; fall back to restart if required.
• text

  Copy

  debounceMs
  : debounce window in ms before config changes are applied (non-negative integer).
• text

  Copy

  deferralTimeoutMs
  : optional maximum time in ms to wait for in-flight operations before forcing a restart. Omit it to use the default bounded wait (
  text

  Copy

  300000
  ); set
  text

  Copy

  0
  to wait indefinitely and log periodic still-pending warnings.

---

Hooks

json5
Copy
{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    maxBodyBytes: 262144,
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: true,
    allowedSessionKeyPrefixes: ["hook:", "hook:gmail:"],
    allowedAgentIds: ["hooks", "main"],
    presets: ["gmail"],
    transformsDir: "~/.openclaw/hooks/transforms",
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "hooks",
        wakeMode: "now",
        name: "Gmail",
        sessionKey: "hook:gmail:{{messages[0].id}}",
        messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}",
        deliver: true,
        channel: "last",
        model: "openai/gpt-5.4-mini",
      },
    ],
  },
}

Auth:

or . Query-string hook tokens are rejected.

Validation and safety notes:

• text

  Copy

  hooks.enabled=true
  requires a non-empty
  text

  Copy

  hooks.token
  .
• text

  Copy

  hooks.token
  must be distinct from
  text

  Copy

  gateway.auth.token
  ; reusing the Gateway token is rejected.
• text

  Copy

  hooks.path
  cannot be
  text

  Copy

  /
  ; use a dedicated subpath such as
  text

  Copy

  /hooks
  .
• If
  text

  Copy

  hooks.allowRequestSessionKey=true
  , constrain
  text

  Copy

  hooks.allowedSessionKeyPrefixes
  (for example
  text

  Copy

  ["hook:"]
  ).
• If a mapping or preset uses a templated
  text

  Copy

  sessionKey
  , set
  text

  Copy

  hooks.allowedSessionKeyPrefixes
  and
  text

  Copy

  hooks.allowRequestSessionKey=true
  . Static mapping keys do not require that opt-in.

Endpoints:

• text

  Copy

  POST /hooks/wake
  →
  text

  Copy

  { text, mode?: "now"|"next-heartbeat" }
• text

  Copy

  POST /hooks/agent
  →
  text

  Copy

  { message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }
  • text

    Copy

    sessionKey
    from request payload is accepted only when
    text

    Copy

    hooks.allowRequestSessionKey=true
    (default:
    text

    Copy

    false
    ).
• text

  Copy

  POST /hooks/<name>
  → resolved via
  text

  Copy

  hooks.mappings
  • Template-rendered mapping
    text

    Copy

    sessionKey
    values are treated as externally supplied and also require
    text

    Copy

    hooks.allowRequestSessionKey=true
    .

Gmail integration

• The built-in Gmail preset uses
  text

  Copy

  sessionKey: "hook:gmail:{{messages[0].id}}"
  .
• If you keep that per-message routing, set
  text

  Copy

  hooks.allowRequestSessionKey: true
  and constrain
  text

  Copy

  hooks.allowedSessionKeyPrefixes
  to match the Gmail namespace, for example
  text

  Copy

  ["hook:", "hook:gmail:"]
  .
• If you need
  text

  Copy

  hooks.allowRequestSessionKey: false
  , override the preset with a static
  text

  Copy

  sessionKey
  instead of the templated default.

json5
Copy
{
  hooks: {
    gmail: {
      account: "openclaw@gmail.com",
      topic: "projects/<project-id>/topics/gog-gmail-watch",
      subscription: "gog-gmail-watch-push",
      pushToken: "shared-push-token",
      hookUrl: "http://127.0.0.1:18789/hooks/gmail",
      includeBody: true,
      maxBytes: 20000,
      renewEveryMinutes: 720,
      serve: { bind: "127.0.0.1", port: 8788, path: "/" },
      tailscale: { mode: "funnel", path: "/gmail-pubsub" },
      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
      thinking: "off",
    },
  },
}

• Gateway auto-starts
  text

  Copy

  gog gmail watch serve
  on boot when configured. Set
  text

  Copy

  OPENCLAW_SKIP_GMAIL_WATCHER=1
  to disable.
• Don't run a separate
  text

  Copy

  gog gmail watch serve
  alongside the Gateway.

---

Canvas host

json5
Copy
{
  canvasHost: {
    root: "~/.openclaw/workspace/canvas",
    liveReload: true,
    // enabled: false, // or OPENCLAW_SKIP_CANVAS_HOST=1
  },
}

• Serves agent-editable HTML/CSS/JS and A2UI over HTTP under the Gateway port:
  • text

    Copy

    http://<gateway-host>:<gateway.port>/__openclaw__/canvas/
  • text

    Copy

    http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/
• Local-only: keep
  text

  Copy

  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
  text

  Copy

  index.html
  when empty.
• Also serves A2UI at
  text

  Copy

  /__openclaw__/a2ui/
  .
• Changes require a gateway restart.
• Disable live reload for large directories or
  text

  Copy

  EMFILE
  errors.

---

Discovery

mDNS (Bonjour)

json5
Copy
{
  discovery: {
    mdns: {
      mode: "minimal", // minimal | full | off
    },
  },
}

• text

  Copy

  minimal
  (default): omit
  text

  Copy

  cliPath
  +
  text

  Copy

  sshPort
  from TXT records.
• text

  Copy

  full
  : include
  text

  Copy

  cliPath
  +
  text

  Copy

  sshPort
  .
• Hostname defaults to the system hostname when it is a valid DNS label, falling back to
  text

  Copy

  openclaw
  . Override with
  text

  Copy

  OPENCLAW_MDNS_HOSTNAME
  .

Wide-area (DNS-SD)

json5
Copy
{
  discovery: {
    wideArea: { enabled: true },
  },
}

Writes a unicast DNS-SD zone under

. For cross-network discovery, pair with a DNS server (CoreDNS recommended) + Tailscale split DNS.

Setup:

.

---

Environment

text

Copy

env

(inline env vars)

json5
Copy
{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

• Inline env vars are only applied if the process env is missing the key.
• text

  Copy

  .env
  files: CWD
  text

  Copy

  .env
  +
  text

  Copy

  ~/.openclaw/.env
  (neither overrides existing vars).
• text

  Copy

  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

:

json5
Copy
{
  gateway: {
    auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" },
  },
}

• Only uppercase names matched:
  text

  Copy

  [A-Z_][A-Z0-9_]*
  .
• Missing/empty vars throw an error at config load.
• Escape with
  text

  Copy

  $${VAR}
  for a literal
  text

  Copy

  ${VAR}
  .
• Works with
  text

  Copy

  $include
  .

---

Secrets

Secret refs are additive: plaintext values still work.

text

Copy

SecretRef

Use one object shape:

json5
Copy
{ source: "env" | "file" | "exec", provider: "default", id: "..." }

Validation:

• text

  Copy

  provider
  pattern:
  text

  Copy

  ^[a-z][a-z0-9_-]{0,63}$
• text

  Copy

  source: "env"
  id pattern:
  text

  Copy

  ^[A-Z][A-Z0-9_]{0,127}$
• text

  Copy

  source: "file"
  id: absolute JSON pointer (for example
  text

  Copy

  "/providers/openai/apiKey"
  )
• text

  Copy

  source: "exec"
  id pattern:
  text

  Copy

  ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$
• text

  Copy

  source: "exec"
  ids must not contain
  text

  Copy

  .
  or
  text

  Copy

  ..
  slash-delimited path segments (for example
  text

  Copy

  a/../b
  is rejected)

Supported credential surface

• Canonical matrix: SecretRef Credential Surface
• text

  Copy

  secrets apply
  targets supported
  text

  Copy

  openclaw.json
  credential paths.
• text

  Copy

  auth-profiles.json
  refs are included in runtime resolution and audit coverage.

Secret providers config

json5
Copy
{
  secrets: {
    providers: {
      default: { source: "env" }, // optional explicit env provider
      filemain: {
        source: "file",
        path: "~/.openclaw/secrets.json",
        mode: "json",
        timeoutMs: 5000,
      },
      vault: {
        source: "exec",
        command: "/usr/local/bin/openclaw-vault-resolver",
        passEnv: ["PATH", "VAULT_ADDR"],
      },
    },
    defaults: {
      env: "default",
      file: "filemain",
      exec: "vault",
    },
  },
}

Notes:

• text

  Copy

  file
  provider supports
  text

  Copy

  mode: "json"
  and
  text

  Copy

  mode: "singleValue"
  (
  text

  Copy

  id
  must be
  text

  Copy

  "value"
  in singleValue mode).
• File and exec provider paths fail closed when Windows ACL verification is unavailable. Set
  text

  Copy

  allowInsecurePath: true
  only for trusted paths that cannot be verified.
• text

  Copy

  exec
  provider requires an absolute
  text

  Copy

  command
  path and uses protocol payloads on stdin/stdout.
• By default, symlink command paths are rejected. Set
  text

  Copy

  allowSymlinkCommand: true
  to allow symlink paths while validating the resolved target path.
• If
  text

  Copy

  trustedDirs
  is configured, the trusted-dir check applies to the resolved target path.
• text

  Copy

  exec
  child environment is minimal by default; pass required variables explicitly with
  text

  Copy

  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

json5
Copy
{
  auth: {
    profiles: {
      "anthropic:default": { provider: "anthropic", mode: "api_key" },
      "anthropic:work": { provider: "anthropic", mode: "api_key" },
      "openai-codex:personal": { provider: "openai-codex", mode: "oauth" },
    },
    order: {
      anthropic: ["anthropic:default", "anthropic:work"],
      "openai-codex": ["openai-codex:personal"],
    },
  },
}

• Per-agent profiles are stored at
  text

  Copy

  <agentDir>/auth-profiles.json
  .
• text

  Copy

  auth-profiles.json
  supports value-level refs (
  text

  Copy

  keyRef
  for
  text

  Copy

  api_key
  ,
  text

  Copy

  tokenRef
  for
  text

  Copy

  token
  ) for static credential modes.
• Legacy flat
  text

  Copy

  auth-profiles.json
  maps such as
  text

  Copy

  { "provider": { "apiKey": "..." } }
  are not a runtime format;
  text

  Copy

  openclaw doctor --fix
  rewrites them to canonical
  text

  Copy

  provider:default
  API-key profiles with a
  text

  Copy

  .legacy-flat.*.bak
  backup.
• OAuth-mode profiles (
  text

  Copy

  auth.profiles.<id>.mode = "oauth"
  ) do not support SecretRef-backed auth-profile credentials.
• Static runtime credentials come from in-memory resolved snapshots; legacy static
  text

  Copy

  auth.json
  entries are scrubbed when discovered.
• Legacy OAuth imports from
  text

  Copy

  ~/.openclaw/credentials/oauth.json
  .
• See OAuth.
• Secrets runtime behavior and
  text

  Copy

  audit/configure/apply
  tooling: Secrets Management.

text

Copy

auth.cooldowns

json5
Copy
{
  auth: {
    cooldowns: {
      billingBackoffHours: 5,
      billingBackoffHoursByProvider: { anthropic: 3, openai: 8 },
      billingMaxHours: 24,
      authPermanentBackoffMinutes: 10,
      authPermanentMaxMinutes: 60,
      failureWindowHours: 24,
      overloadedProfileRotations: 1,
      overloadedBackoffMs: 0,
      rateLimitedProfileRotations: 1,
    },
  },
}

• text

  Copy

  billingBackoffHours
  : base backoff in hours when a profile fails due to true billing/insufficient-credit errors (default:
  text

  Copy

  5
  ). Explicit billing text can still land here even on
  text

  Copy

  401
  /
  text

  Copy

  403
  responses, but provider-specific text matchers stay scoped to the provider that owns them (for example OpenRouter
  text

  Copy

  Key limit exceeded
  ). Retryable HTTP
  text

  Copy

  402
  usage-window or organization/workspace spend-limit messages stay in the
  text

  Copy

  rate_limit
  path instead.
• text

  Copy

  billingBackoffHoursByProvider
  : optional per-provider overrides for billing backoff hours.
• text

  Copy

  billingMaxHours
  : cap in hours for billing backoff exponential growth (default:
  text

  Copy

  24
  ).
• text

  Copy

  authPermanentBackoffMinutes
  : base backoff in minutes for high-confidence
  text

  Copy

  auth_permanent
  failures (default:
  text

  Copy

  10
  ).
• text

  Copy

  authPermanentMaxMinutes
  : cap in minutes for
  text

  Copy

  auth_permanent
  backoff growth (default:
  text

  Copy

  60
  ).
• text

  Copy

  failureWindowHours
  : rolling window in hours used for backoff counters (default:
  text

  Copy

  24
  ).
• text

  Copy

  overloadedProfileRotations
  : maximum same-provider auth-profile rotations for overloaded errors before switching to model fallback (default:
  text

  Copy

  1
  ). Provider-busy shapes such as
  text

  Copy

  ModelNotReadyException
  land here.
• text

  Copy

  overloadedBackoffMs
  : fixed delay before retrying an overloaded provider/profile rotation (default:
  text

  Copy

  0
  ).
• text

  Copy

  rateLimitedProfileRotations
  : maximum same-provider auth-profile rotations for rate-limit errors before switching to model fallback (default:
  text

  Copy

  1
  ). That rate-limit bucket includes provider-shaped text such as
  text

  Copy

  Too many concurrent requests
  ,
  text

  Copy

  ThrottlingException
  ,
  text

  Copy

  concurrency limit reached
  ,
  text

  Copy

  workers_ai ... quota limit exceeded
  , and
  text

  Copy

  resource exhausted
  .

---

Logging

json5
Copy
{
  logging: {
    level: "info",
    file: "/tmp/openclaw/openclaw.log",
    consoleLevel: "info",
    consoleStyle: "pretty", // pretty | compact | json
    redactSensitive: "tools", // off | tools
    redactPatterns: ["\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1"],
  },
}

• Default log file:
  text

  Copy

  /tmp/openclaw/openclaw-YYYY-MM-DD.log
  .
• Set
  text

  Copy

  logging.file
  for a stable path.
• text

  Copy

  consoleLevel
  bumps to
  text

  Copy

  debug
  when
  text

  Copy

  --verbose
  .
• text

  Copy

  maxFileBytes
  : maximum active log file size in bytes before rotation (positive integer; default:
  text

  Copy

  104857600
  = 100 MB). OpenClaw keeps up to five numbered archives beside the active file.
• text

  Copy

  redactSensitive
  /
  text

  Copy

  redactPatterns
  : best-effort masking for console output, file logs, OTLP log records, and persisted session transcript text.
  text

  Copy

  redactSensitive: "off"
  only disables this general log/transcript policy; UI/tool/diagnostic safety surfaces still redact secrets before emission.

---

Diagnostics

json5
Copy
{
  diagnostics: {
    enabled: true,
    flags: ["telegram.*"],
    stuckSessionWarnMs: 30000,

    otel: {
      enabled: false,
      endpoint: "https://otel-collector.example.com:4318",
      tracesEndpoint: "https://traces.example.com/v1/traces",
      metricsEndpoint: "https://metrics.example.com/v1/metrics",
      logsEndpoint: "https://logs.example.com/v1/logs",
      protocol: "http/protobuf", // http/protobuf | grpc
      headers: { "x-tenant-id": "my-org" },
      serviceName: "openclaw-gateway",
      traces: true,
      metrics: true,
      logs: false,
      sampleRate: 1.0,
      flushIntervalMs: 5000,
      captureContent: {
        enabled: false,
        inputMessages: false,
        outputMessages: false,
        toolInputs: false,
        toolOutputs: false,
        systemPrompt: false,
      },
    },

    cacheTrace: {
      enabled: false,
      filePath: "~/.openclaw/logs/cache-trace.jsonl",
      includeMessages: true,
      includePrompt: true,
      includeSystem: true,
    },
  },
}

• text

  Copy

  enabled
  : master toggle for instrumentation output (default:
  text

  Copy

  true
  ).
• text

  Copy

  flags
  : array of flag strings enabling targeted log output (supports wildcards like
  text

  Copy

  "telegram.*"
  or
  text

  Copy

  "*"
  ).
• text

  Copy

  stuckSessionWarnMs
  : age threshold in ms for emitting stuck-session warnings while a session remains in processing state.
• text

  Copy

  otel.enabled
  : enables the OpenTelemetry export pipeline (default:
  text

  Copy

  false
  ). For the full configuration, signal catalog, and privacy model, see OpenTelemetry export.
• text

  Copy

  otel.endpoint
  : collector URL for OTel export.
• text

  Copy

  otel.tracesEndpoint
  /
  text

  Copy

  otel.metricsEndpoint
  /
  text

  Copy

  otel.logsEndpoint
  : optional signal-specific OTLP endpoints. When set, they override
  text

  Copy

  otel.endpoint
  for that signal only.
• text

  Copy

  otel.protocol
  :
  text

  Copy

  "http/protobuf"
  (default) or
  text

  Copy

  "grpc"
  .
• text

  Copy

  otel.headers
  : extra HTTP/gRPC metadata headers sent with OTel export requests.
• text

  Copy

  otel.serviceName
  : service name for resource attributes.
• text

  Copy

  otel.traces
  /
  text

  Copy

  otel.metrics
  /
  text

  Copy

  otel.logs
  : enable trace, metrics, or log export.
• text

  Copy

  otel.sampleRate
  : trace sampling rate
  text

  Copy

  0
  –
  text

  Copy

  1
  .
• text

  Copy

  otel.flushIntervalMs
  : periodic telemetry flush interval in ms.
• text

  Copy

  otel.captureContent
  : opt-in raw content capture for OTEL span attributes. Defaults to off. Boolean
  text

  Copy

  true
  captures non-system message/tool content; the object form lets you enable
  text

  Copy

  inputMessages
  ,
  text

  Copy

  outputMessages
  ,
  text

  Copy

  toolInputs
  ,
  text

  Copy

  toolOutputs
  , and
  text

  Copy

  systemPrompt
  explicitly.
• text

  Copy

  OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental
  : environment toggle for latest experimental GenAI span provider attributes. By default spans keep the legacy
  text

  Copy

  gen_ai.system
  attribute for compatibility; GenAI metrics use bounded semantic attributes.
• text

  Copy

  OPENCLAW_OTEL_PRELOADED=1
  : environment toggle for hosts that already registered a global OpenTelemetry SDK. OpenClaw then skips plugin-owned SDK startup/shutdown while keeping diagnostic listeners active.
• text

  Copy

  OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
  ,
  text

  Copy

  OTEL_EXPORTER_OTLP_METRICS_ENDPOINT
  , and
  text

  Copy

  OTEL_EXPORTER_OTLP_LOGS_ENDPOINT
  : signal-specific endpoint env vars used when the matching config key is unset.
• text

  Copy

  cacheTrace.enabled
  : log cache trace snapshots for embedded runs (default:
  text

  Copy

  false
  ).
• text

  Copy

  cacheTrace.filePath
  : output path for cache trace JSONL (default:
  text

  Copy

  $OPENCLAW_STATE_DIR/logs/cache-trace.jsonl
  ).
• text

  Copy

  cacheTrace.includeMessages
  /
  text

  Copy

  includePrompt
  /
  text

  Copy

  includeSystem
  : control what is included in cache trace output (all default:
  text

  Copy

  true
  ).

---

Update

json5
Copy
{
  update: {
    channel: "stable", // stable | beta | dev
    checkOnStart: true,

    auto: {
      enabled: false,
      stableDelayHours: 6,
      stableJitterHours: 12,
      betaCheckIntervalHours: 1,
    },
  },
}

• text

  Copy

  channel
  : release channel for npm/git installs —
  text

  Copy

  "stable"
  ,
  text

  Copy

  "beta"
  , or
  text

  Copy

  "dev"
  .
• text

  Copy

  checkOnStart
  : check for npm updates when the gateway starts (default:
  text

  Copy

  true
  ).
• text

  Copy

  auto.enabled
  : enable background auto-update for package installs (default:
  text

  Copy

  false
  ).
• text

  Copy

  auto.stableDelayHours
  : minimum delay in hours before stable-channel auto-apply (default:
  text

  Copy

  6
  ; max:
  text

  Copy

  168
  ).
• text

  Copy

  auto.stableJitterHours
  : extra stable-channel rollout spread window in hours (default:
  text

  Copy

  12
  ; max:
  text

  Copy

  168
  ).
• text

  Copy

  auto.betaCheckIntervalHours
  : how often beta-channel checks run in hours (default:
  text

  Copy

  1
  ; max:
  text

  Copy

  24
  ).

---

ACP

json5
Copy
{
  acp: {
    enabled: true,
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "main",
    allowedAgents: ["main", "ops"],
    maxConcurrentSessions: 10,

    stream: {
      coalesceIdleMs: 50,
      maxChunkChars: 1000,
      repeatSuppression: true,
      deliveryMode: "live", // live | final_only
      hiddenBoundarySeparator: "paragraph", // none | space | newline | paragraph
      maxOutputChars: 50000,
      maxSessionUpdateChars: 500,
    },

    runtime: {
      ttlMinutes: 30,
    },
  },
}

• text

  Copy

  enabled
  : global ACP feature gate (default:
  text

  Copy

  true
  ; set
  text

  Copy

  false
  to hide ACP dispatch and spawn affordances).
• text

  Copy

  dispatch.enabled
  : independent gate for ACP session turn dispatch (default:
  text

  Copy

  true
  ). Set
  text

  Copy

  false
  to keep ACP commands available while blocking execution.
• text

  Copy

  backend
  : default ACP runtime backend id (must match a registered ACP runtime plugin). If
  text

  Copy

  plugins.allow
  is set, include the backend plugin id (for example
  text

  Copy

  acpx
  ) or the bundled default plugin will not load.
• text

  Copy

  defaultAgent
  : fallback ACP target agent id when spawns do not specify an explicit target.
• text

  Copy

  allowedAgents
  : allowlist of agent ids permitted for ACP runtime sessions; empty means no additional restriction.
• text

  Copy

  maxConcurrentSessions
  : maximum concurrently active ACP sessions.
• text

  Copy

  stream.coalesceIdleMs
  : idle flush window in ms for streamed text.
• text

  Copy

  stream.maxChunkChars
  : maximum chunk size before splitting streamed block projection.
• text

  Copy

  stream.repeatSuppression
  : suppress repeated status/tool lines per turn (default:
  text

  Copy

  true
  ).
• text

  Copy

  stream.deliveryMode
  :
  text

  Copy

  "live"
  streams incrementally;
  text

  Copy

  "final_only"
  buffers until turn terminal events.
• text

  Copy

  stream.hiddenBoundarySeparator
  : separator before visible text after hidden tool events (default:
  text

  Copy

  "paragraph"
  ).
• text

  Copy

  stream.maxOutputChars
  : maximum assistant output characters projected per ACP turn.
• text

  Copy

  stream.maxSessionUpdateChars
  : maximum characters for projected ACP status/update lines.
• text

  Copy

  stream.tagVisibility
  : record of tag names to boolean visibility overrides for streamed events.
• text

  Copy

  runtime.ttlMinutes
  : idle TTL in minutes for ACP session workers before eligible cleanup.
• text

  Copy

  runtime.installCommand
  : optional install command to run when bootstrapping an ACP runtime environment.

---

CLI

json5
Copy
{
  cli: {
    banner: {
      taglineMode: "off", // random | default | off
    },
  },
}

• text

  Copy

  cli.banner.taglineMode
  controls banner tagline style:
  • text

    Copy

    "random"
    (default): rotating funny/seasonal taglines.
  • text

    Copy

    "default"
    : fixed neutral tagline (
    text

    Copy

    All your chats, one OpenClaw.
    ).
  • text

    Copy

    "off"
    : no tagline text (banner title/version still shown).
• To hide the entire banner (not just taglines), set env
  text

  Copy

  OPENCLAW_HIDE_BANNER=1
  .

---

Wizard

Metadata written by CLI guided setup flows (

, , ):

json5
Copy
{
  wizard: {
    lastRunAt: "2026-01-01T00:00:00.000Z",
    lastRunVersion: "2026.1.4",
    lastRunCommit: "abc1234",
    lastRunCommand: "configure",
    lastRunMode: "local",
  },
}

---

Identity

See

identity fields under Agent defaults.

---

Bridge (legacy, removed)

Current builds no longer include the TCP bridge. Nodes connect over the Gateway WebSocket.

keys are no longer part of the config schema (validation fails until removed; can strip unknown keys).

---

Cron

json5
Copy
{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2, // cron dispatch + isolated cron agent-turn execution
    webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs
    webhookToken: "replace-with-dedicated-token", // optional bearer token for outbound webhook auth
    sessionRetention: "24h", // duration string or false
    runLog: {
      maxBytes: "2mb", // default 2_000_000 bytes
      keepLines: 2000, // default 2000
    },
  },
}

• text

  Copy

  sessionRetention
  : how long to keep completed isolated cron run sessions before pruning from
  text

  Copy

  sessions.json
  . Also controls cleanup of archived deleted cron transcripts. Default:
  text

  Copy

  24h
  ; set
  text

  Copy

  false
  to disable.
• text

  Copy

  runLog.maxBytes
  : max size per run log file (
  text

  Copy

  cron/runs/<jobId>.jsonl
  ) before pruning. Default:
  text

  Copy

  2_000_000
  bytes.
• text

  Copy

  runLog.keepLines
  : newest lines retained when run-log pruning is triggered. Default:
  text

  Copy

  2000
  .
• text

  Copy

  webhookToken
  : bearer token used for cron webhook POST delivery (
  text

  Copy

  delivery.mode = "webhook"
  ), if omitted no auth header is sent.
• text

  Copy

  webhook
  : deprecated legacy fallback webhook URL (http/https) used only for stored jobs that still have
  text

  Copy

  notify: true
  .

text

Copy

cron.retry

json5
Copy
{
  cron: {
    retry: {
      maxAttempts: 3,
      backoffMs: [30000, 60000, 300000],
      retryOn: ["rate_limit", "overloaded", "network", "timeout", "server_error"],
    },
  },
}

• text

  Copy

  maxAttempts
  : maximum retries for one-shot jobs on transient errors (default:
  text

  Copy

  3
  ; range:
  text

  Copy

  0
  –
  text

  Copy

  10
  ).
• text

  Copy

  backoffMs
  : array of backoff delays in ms for each retry attempt (default:
  text

  Copy

  [30000, 60000, 300000]
  ; 1–10 entries).
• text

  Copy

  retryOn
  : error types that trigger retries —
  text

  Copy

  "rate_limit"
  ,
  text

  Copy

  "overloaded"
  ,
  text

  Copy

  "network"
  ,
  text

  Copy

  "timeout"
  ,
  text

  Copy

  "server_error"
  . Omit to retry all transient types.

Applies only to one-shot cron jobs. Recurring jobs use separate failure handling.

text

Copy

cron.failureAlert

json5
Copy
{
  cron: {
    failureAlert: {
      enabled: false,
      after: 3,
      cooldownMs: 3600000,
      includeSkipped: false,
      mode: "announce",
      accountId: "main",
    },
  },
}

• text

  Copy

  enabled
  : enable failure alerts for cron jobs (default:
  text

  Copy

  false
  ).
• text

  Copy

  after
  : consecutive failures before an alert fires (positive integer, min:
  text

  Copy

  1
  ).
• text

  Copy

  cooldownMs
  : minimum milliseconds between repeated alerts for the same job (non-negative integer).
• text

  Copy

  includeSkipped
  : count consecutive skipped runs toward the alert threshold (default:
  text

  Copy

  false
  ). Skipped runs are tracked separately and do not affect execution-error backoff.
• text

  Copy

  mode
  : delivery mode —
  text

  Copy

  "announce"
  sends via a channel message;
  text

  Copy

  "webhook"
  posts to the configured webhook.
• text

  Copy

  accountId
  : optional account or channel id to scope alert delivery.

text

Copy

cron.failureDestination

json5
Copy
{
  cron: {
    failureDestination: {
      mode: "announce",
      channel: "last",
      to: "channel:C1234567890",
      accountId: "main",
    },
  },
}

• Default destination for cron failure notifications across all jobs.
• text

  Copy

  mode
  :
  text

  Copy

  "announce"
  or
  text

  Copy

  "webhook"
  ; defaults to
  text

  Copy

  "announce"
  when enough target data exists.
• text

  Copy

  channel
  : channel override for announce delivery.
  text

  Copy

  "last"
  reuses the last known delivery channel.
• text

  Copy

  to
  : explicit announce target or webhook URL. Required for webhook mode.
• text

  Copy

  accountId
  : optional account override for delivery.
• Per-job
  text

  Copy

  delivery.failureDestination
  overrides this global default.
• When neither global nor per-job failure destination is set, jobs that already deliver via
  text

  Copy

  announce
  fall back to that primary announce target on failure.
• text

  Copy

  delivery.failureDestination
  is only supported for
  text

  Copy

  sessionTarget="isolated"
  jobs unless the job's primary
  text

  Copy

  delivery.mode
  is
  text

  Copy

  "webhook"
  .

See Cron Jobs. Isolated cron executions are tracked as background tasks.

---

Media model template variables

Template placeholders expanded in

:

---

Config includes (

text

Copy

$include

)

Split config into multiple files:

json5
Copy
// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/mueller.json5", "./clients/schmidt.json5"],
  },
}

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 (
  text

  Copy

  dirname
  of
  text

  Copy

  openclaw.json
  ). Absolute/
  text

  Copy

  ../
  forms are allowed only when they still resolve inside that boundary.
• OpenClaw-owned writes that change only one top-level section backed by a single-file include write through to that included file. For example,
  text

  Copy

  plugins install
  updates
  text

  Copy

  plugins: { $include: "./plugins.json5" }
  in
  text

  Copy

  plugins.json5
  and leaves
  text

  Copy

  openclaw.json
  intact.
• Root includes, include arrays, and includes with sibling overrides are read-only for OpenClaw-owned writes; those writes fail closed instead of flattening the config.
• Errors: clear messages for missing files, parse errors, and circular includes.

---

Related: Configuration · Configuration Examples · Doctor

Related

• Configuration
• Configuration examples