Per-plugin settings keyed by plugin ID including enablement and plugin-specific runtime configuration payloads. Use this for scoped plugin tuning without changing global loader policy.


Plugin-defined configuration payload interpreted by that plugin's own schema and validation rules. Use only documented fields from the plugin to prevent ignored or invalid settings.


Per-plugin enablement override for a specific entry, applied on top of global plugin policy (restart required). Use this to stage plugin rollout gradually across environments.


Per-plugin typed hook policy controls for core-enforced safety gates. Use this to constrain high-impact hook categories without disabling the entire plugin.


Controls whether this plugin may mutate prompts through typed hooks. Set false to block `before_prompt_build` and ignore prompt-mutating fields from legacy `before_agent_start`, while preserving legacy `modelOverride` and `providerOverride` behavior.


Per-plugin subagent runtime controls for model override trust and allowlists. Keep this unset unless a plugin must explicitly steer subagent model selection.


Allowed override targets for trusted plugin subagent runs as canonical "provider/model" refs. Use "*" only when you intentionally allow any model.


Explicitly allows this plugin to request provider/model overrides in background subagent runs. Keep false unless the plugin is trusted to steer model selection.


ACP runtime backend powered by acpx with configurable command path and version policy. (plugin: acpx)


Optional path/command override for acpx (for example /home/user/repos/acpx/dist/cli.js). Leave unset to use plugin-local bundled acpx.


Default cwd for ACP session operations when not set per session.


Exact version to enforce (for example 0.1.16) or "any" to skip strict version matching.


Named MCP server definitions to inject into ACPX-backed session bootstrap. Each entry needs a command and can include args and env.


acpx policy when interactive permission prompts are unavailable.


Default acpx permission policy for runtime prompts.


Idle queue-owner TTL for acpx prompt turns. Keep this short in OpenClaw to avoid delayed completion after each turn.


Enabled by default. On Windows, reject unresolved .cmd/.bat wrappers instead of shell fallback. Disable only for compatibility with non-standard wrappers.


Optional acpx timeout for each runtime turn.


OpenClaw Amazon Bedrock provider plugin (plugin: amazon-bedrock)


Plugin-defined config payload for amazon-bedrock.


Per-plugin typed hook policy controls for core-enforced safety gates. Use this to constrain high-impact hook categories without disabling the entire plugin.


Controls whether this plugin may mutate prompts through typed hooks. Set false to block `before_prompt_build` and ignore prompt-mutating fields from legacy `before_agent_start`, while preserving legacy `modelOverride` and `providerOverride` behavior.


Per-plugin subagent runtime controls for model override trust and allowlists. Keep this unset unless a plugin must explicitly steer subagent model selection.


Allowed override targets for trusted plugin subagent runs as canonical "provider/model" refs. Use "*" only when you intentionally allow any model.


Explicitly allows this plugin to request provider/model overrides in background subagent runs. Keep false unless the plugin is trusted to steer model selection.


OpenClaw Anthropic provider plugin (plugin: anthropic)


Plugin-defined config payload for anthropic.


OpenClaw BlueBubbles channel plugin (plugin: bluebubbles)


Plugin-defined config payload for bluebubbles.


Plugin-defined config payload for brave.


Brave Search API key (fallback: BRAVE_API_KEY env var).


OpenClaw BytePlus provider plugin (plugin: byteplus)


Plugin-defined config payload for byteplus.


OpenClaw Chutes.ai provider plugin (plugin: chutes)


Plugin-defined config payload for chutes.


OpenClaw Cloudflare AI Gateway provider plugin (plugin: cloudflare-ai-gateway)


Plugin-defined config payload for cloudflare-ai-gateway.


Per-plugin typed hook policy controls for core-enforced safety gates. Use this to constrain high-impact hook categories without disabling the entire plugin.


Controls whether this plugin may mutate prompts through typed hooks. Set false to block `before_prompt_build` and ignore prompt-mutating fields from legacy `before_agent_start`, while preserving legacy `modelOverride` and `providerOverride` behavior.


Per-plugin subagent runtime controls for model override trust and allowlists. Keep this unset unless a plugin must explicitly steer subagent model selection.


Allowed override targets for trusted plugin subagent runs as canonical "provider/model" refs. Use "*" only when you intentionally allow any model.


Explicitly allows this plugin to request provider/model overrides in background subagent runs. Keep false unless the plugin is trusted to steer model selection.


OpenClaw Copilot Proxy provider plugin (plugin: copilot-proxy)


Plugin-defined config payload for copilot-proxy.


Generate setup codes and approve device pairing requests. (plugin: device-pair)


Plugin-defined config payload for device-pair.


Public WebSocket URL used for /pair setup codes (ws/wss or http/https).


OpenClaw diagnostics OpenTelemetry exporter (plugin: diagnostics-otel)


Plugin-defined config payload for diagnostics-otel.


Read-only diff viewer and file renderer for agents. (plugin: diffs)


Plugin-defined config payload for diffs.


Show added/removed background highlights by default.


Rendered file format for file mode (PNG or PDF).


Maximum file render width in CSS pixels.


Device scale factor used while rendering file artifacts.


Preferred font family name for diff content and headers.


Initial diff layout shown in the viewer.


Line-height multiplier applied to diff rows.


Tool default when mode is omitted. Use view for canvas/gateway viewer, file for PNG/PDF, or both.


Allow non-loopback access to diff viewer URLs when the token path is known.


Per-plugin typed hook policy controls for core-enforced safety gates. Use this to constrain high-impact hook categories without disabling the entire plugin.


Controls whether this plugin may mutate prompts through typed hooks. Set false to block `before_prompt_build` and ignore prompt-mutating fields from legacy `before_agent_start`, while preserving legacy `modelOverride` and `providerOverride` behavior.


Per-plugin subagent runtime controls for model override trust and allowlists. Keep this unset unless a plugin must explicitly steer subagent model selection.


Allowed override targets for trusted plugin subagent runs as canonical "provider/model" refs. Use "*" only when you intentionally allow any model.


Explicitly allows this plugin to request provider/model overrides in background subagent runs. Keep false unless the plugin is trusted to steer model selection.


OpenClaw Discord channel plugin (plugin: discord)


Plugin-defined config payload for discord.


OpenClaw ElevenLabs speech plugin (plugin: elevenlabs)


Plugin-defined config payload for elevenlabs.


OpenClaw fal provider plugin (plugin: fal)


OpenClaw Feishu/Lark channel plugin (community maintained by @m1heng) (plugin: feishu)


Plugin-defined config payload for feishu.


OpenClaw Firecrawl plugin (plugin: firecrawl)


Plugin-defined config payload for firecrawl.


Firecrawl API key for web search (fallback: FIRECRAWL_API_KEY env var).


OpenClaw GitHub Copilot provider plugin (plugin: github-copilot)


Plugin-defined config payload for github-copilot.


Per-plugin typed hook policy controls for core-enforced safety gates. Use this to constrain high-impact hook categories without disabling the entire plugin.


Controls whether this plugin may mutate prompts through typed hooks. Set false to block `before_prompt_build` and ignore prompt-mutating fields from legacy `before_agent_start`, while preserving legacy `modelOverride` and `providerOverride` behavior.


Per-plugin subagent runtime controls for model override trust and allowlists. Keep this unset unless a plugin must explicitly steer subagent model selection.


Allowed override targets for trusted plugin subagent runs as canonical "provider/model" refs. Use "*" only when you intentionally allow any model.


Explicitly allows this plugin to request provider/model overrides in background subagent runs. Keep false unless the plugin is trusted to steer model selection.


Plugin-defined config payload for google.


Gemini API key for Google Search grounding (fallback: GEMINI_API_KEY env var).


Gemini model override for web search grounding.


OpenClaw Google Chat channel plugin (plugin: googlechat)


Plugin-defined config payload for googlechat.


OpenClaw Hugging Face provider plugin (plugin: huggingface)


Plugin-defined config payload for huggingface.


OpenClaw iMessage channel plugin (plugin: imessage)


Plugin-defined config payload for imessage.


OpenClaw IRC channel plugin (plugin: irc)


OpenClaw Kilo Gateway provider plugin (plugin: kilocode)


Plugin-defined config payload for kilocode.


Per-plugin typed hook policy controls for core-enforced safety gates. Use this to constrain high-impact hook categories without disabling the entire plugin.


Controls whether this plugin may mutate prompts through typed hooks. Set false to block `before_prompt_build` and ignore prompt-mutating fields from legacy `before_agent_start`, while preserving legacy `modelOverride` and `providerOverride` behavior.


Per-plugin subagent runtime controls for model override trust and allowlists. Keep this unset unless a plugin must explicitly steer subagent model selection.


Allowed override targets for trusted plugin subagent runs as canonical "provider/model" refs. Use "*" only when you intentionally allow any model.


Explicitly allows this plugin to request provider/model overrides in background subagent runs. Keep false unless the plugin is trusted to steer model selection.


OpenClaw Kimi provider plugin (plugin: kimi)


OpenClaw LINE channel plugin (plugin: line)


Generic JSON-only LLM tool for structured tasks callable from workflows. (plugin: llm-task)


Plugin-defined config payload for llm-task.


Typed workflow tool with resumable approvals. (plugin: lobster)


Plugin-defined config payload for lobster.


OpenClaw Matrix channel plugin (plugin: matrix)


Plugin-defined config payload for matrix.


OpenClaw Mattermost channel plugin (plugin: mattermost)


Plugin-defined config payload for mattermost.


OpenClaw core memory search plugin (plugin: memory-core)


Plugin-defined config payload for memory-core.


Per-plugin typed hook policy controls for core-enforced safety gates. Use this to constrain high-impact hook categories without disabling the entire plugin.


Controls whether this plugin may mutate prompts through typed hooks. Set false to block `before_prompt_build` and ignore prompt-mutating fields from legacy `before_agent_start`, while preserving legacy `modelOverride` and `providerOverride` behavior.


Per-plugin subagent runtime controls for model override trust and allowlists. Keep this unset unless a plugin must explicitly steer subagent model selection.


Allowed override targets for trusted plugin subagent runs as canonical "provider/model" refs. Use "*" only when you intentionally allow any model.


Explicitly allows this plugin to request provider/model overrides in background subagent runs. Keep false unless the plugin is trusted to steer model selection.


OpenClaw LanceDB-backed long-term memory plugin with auto-recall/capture (plugin: memory-lancedb)


Plugin-defined config payload for memory-lancedb.


Automatically capture important information from conversations


Automatically inject relevant memories into context


Maximum message length eligible for auto-capture


API key for OpenAI embeddings (or use ${OPENAI_API_KEY})


Base URL for compatible providers (e.g. http://localhost:11434/v1)


Vector dimensions for custom models (required for non-standard models)


OpenClaw Microsoft speech plugin (plugin: microsoft)


Plugin-defined config payload for microsoft.


OpenClaw MiniMax provider and OAuth plugin (plugin: minimax)


Plugin-defined config payload for minimax.


Per-plugin typed hook policy controls for core-enforced safety gates. Use this to constrain high-impact hook categories without disabling the entire plugin.


Controls whether this plugin may mutate prompts through typed hooks. Set false to block `before_prompt_build` and ignore prompt-mutating fields from legacy `before_agent_start`, while preserving legacy `modelOverride` and `providerOverride` behavior.


Per-plugin subagent runtime controls for model override trust and allowlists. Keep this unset unless a plugin must explicitly steer subagent model selection.


Allowed override targets for trusted plugin subagent runs as canonical "provider/model" refs. Use "*" only when you intentionally allow any model.


Explicitly allows this plugin to request provider/model overrides in background subagent runs. Keep false unless the plugin is trusted to steer model selection.


OpenClaw Mistral provider plugin (plugin: mistral)


Plugin-defined config payload for mistral.


OpenClaw Model Studio provider plugin (plugin: modelstudio)


Plugin-defined config payload for modelstudio.


OpenClaw Moonshot provider plugin (plugin: moonshot)


Plugin-defined config payload for moonshot.


Moonshot/Kimi API key (fallback: KIMI_API_KEY or MOONSHOT_API_KEY env var).


OpenClaw Microsoft Teams channel plugin (plugin: msteams)


Plugin-defined config payload for msteams.


OpenClaw Nextcloud Talk channel plugin (plugin: nextcloud-talk)


Plugin-defined config payload for nextcloud-talk.


OpenClaw Nostr channel plugin for NIP-04 encrypted DMs (plugin: nostr)


Plugin-defined config payload for nostr.


Per-plugin typed hook policy controls for core-enforced safety gates. Use this to constrain high-impact hook categories without disabling the entire plugin.


Controls whether this plugin may mutate prompts through typed hooks. Set false to block `before_prompt_build` and ignore prompt-mutating fields from legacy `before_agent_start`, while preserving legacy `modelOverride` and `providerOverride` behavior.


Per-plugin subagent runtime controls for model override trust and allowlists. Keep this unset unless a plugin must explicitly steer subagent model selection.


Allowed override targets for trusted plugin subagent runs as canonical "provider/model" refs. Use "*" only when you intentionally allow any model.


Explicitly allows this plugin to request provider/model overrides in background subagent runs. Keep false unless the plugin is trusted to steer model selection.


OpenClaw NVIDIA provider plugin (plugin: nvidia)


Plugin-defined config payload for nvidia.


OpenClaw Ollama provider plugin (plugin: ollama)


Plugin-defined config payload for ollama.


OpenProse VM skill pack with a /prose slash command. (plugin: open-prose)


Plugin-defined config payload for open-prose.


OpenClaw OpenAI provider plugins (plugin: openai)


Plugin-defined config payload for openai.


OpenClaw OpenCode Zen provider plugin (plugin: opencode)


OpenClaw OpenCode Go provider plugin (plugin: opencode-go)


Plugin-defined config payload for opencode-go.


Plugin-defined config payload for opencode.


Per-plugin typed hook policy controls for core-enforced safety gates. Use this to constrain high-impact hook categories without disabling the entire plugin.


Controls whether this plugin may mutate prompts through typed hooks. Set false to block `before_prompt_build` and ignore prompt-mutating fields from legacy `before_agent_start`, while preserving legacy `modelOverride` and `providerOverride` behavior.


Per-plugin subagent runtime controls for model override trust and allowlists. Keep this unset unless a plugin must explicitly steer subagent model selection.


Allowed override targets for trusted plugin subagent runs as canonical "provider/model" refs. Use "*" only when you intentionally allow any model.


Explicitly allows this plugin to request provider/model overrides in background subagent runs. Keep false unless the plugin is trusted to steer model selection.


OpenClaw OpenRouter provider plugin (plugin: openrouter)


Plugin-defined config payload for openrouter.


Sandbox backend powered by OpenShell with mirrored local workspaces and SSH-based command execution. (plugin: openshell)


Plugin-defined config payload for openshell.


When enabled, pass --auto-providers during sandbox create.


Path or command name for the openshell CLI.


OpenShell sandbox source for first-time create. Defaults to openclaw.


Optional OpenShell gateway name passed as --gateway.


Optional OpenShell gateway endpoint passed as --gateway-endpoint.


Request GPU resources when creating the sandbox.


Optional path to a custom OpenShell sandbox policy YAML.


Provider names to attach when a sandbox is created.


Mirror path for the real agent workspace when workspaceAccess is read-only.


Primary writable workspace inside the OpenShell sandbox.


Timeout for openshell CLI operations such as create/upload/download.


Per-plugin typed hook policy controls for core-enforced safety gates. Use this to constrain high-impact hook categories without disabling the entire plugin.


Controls whether this plugin may mutate prompts through typed hooks. Set false to block `before_prompt_build` and ignore prompt-mutating fields from legacy `before_agent_start`, while preserving legacy `modelOverride` and `providerOverride` behavior.


Per-plugin subagent runtime controls for model override trust and allowlists. Keep this unset unless a plugin must explicitly steer subagent model selection.


Allowed override targets for trusted plugin subagent runs as canonical "provider/model" refs. Use "*" only when you intentionally allow any model.


Explicitly allows this plugin to request provider/model overrides in background subagent runs. Keep false unless the plugin is trusted to steer model selection.


OpenClaw Perplexity plugin (plugin: perplexity)


Plugin-defined config payload for perplexity.


Perplexity or OpenRouter API key for web search.


Optional Perplexity/OpenRouter chat-completions base URL override.


Optional Sonar/OpenRouter model override.


Arm/disarm high-risk phone node commands (camera/screen/writes) with an optional auto-expiry. (plugin: phone-control)


Plugin-defined config payload for phone-control.


OpenClaw Qianfan provider plugin (plugin: qianfan)


Plugin-defined config payload for qianfan.


Plugin-defined config payload for qwen-portal-auth.


OpenClaw SGLang provider plugin (plugin: sglang)


Plugin-defined config payload for sglang.


Per-plugin typed hook policy controls for core-enforced safety gates. Use this to constrain high-impact hook categories without disabling the entire plugin.


Controls whether this plugin may mutate prompts through typed hooks. Set false to block `before_prompt_build` and ignore prompt-mutating fields from legacy `before_agent_start`, while preserving legacy `modelOverride` and `providerOverride` behavior.


Per-plugin subagent runtime controls for model override trust and allowlists. Keep this unset unless a plugin must explicitly steer subagent model selection.


Allowed override targets for trusted plugin subagent runs as canonical "provider/model" refs. Use "*" only when you intentionally allow any model.


Explicitly allows this plugin to request provider/model overrides in background subagent runs. Keep false unless the plugin is trusted to steer model selection.


OpenClaw Signal channel plugin (plugin: signal)


Plugin-defined config payload for signal.


OpenClaw Slack channel plugin (plugin: slack)


Plugin-defined config payload for slack.


Synology Chat channel plugin for OpenClaw (plugin: synology-chat)


Plugin-defined config payload for synology-chat.


OpenClaw Synthetic provider plugin (plugin: synthetic)


Plugin-defined config payload for synthetic.


Manage Talk voice selection (list/set). (plugin: talk-voice)


Plugin-defined config payload for talk-voice.


OpenClaw Telegram channel plugin (plugin: telegram)


Plugin-defined config payload for telegram.


Per-plugin typed hook policy controls for core-enforced safety gates. Use this to constrain high-impact hook categories without disabling the entire plugin.


Controls whether this plugin may mutate prompts through typed hooks. Set false to block `before_prompt_build` and ignore prompt-mutating fields from legacy `before_agent_start`, while preserving legacy `modelOverride` and `providerOverride` behavior.


Per-plugin subagent runtime controls for model override trust and allowlists. Keep this unset unless a plugin must explicitly steer subagent model selection.


Allowed override targets for trusted plugin subagent runs as canonical "provider/model" refs. Use "*" only when you intentionally allow any model.


Explicitly allows this plugin to request provider/model overrides in background subagent runs. Keep false unless the plugin is trusted to steer model selection.


Prevents multiple agents from responding in the same Slack thread. Uses HTTP calls to the slack-forwarder ownership API. (plugin: thread-ownership)


Plugin-defined config payload for thread-ownership.


Slack channel IDs where thread ownership is enforced


Base URL of the slack-forwarder ownership API (default: http://slack-forwarder:8750)


OpenClaw Tlon/Urbit channel plugin (plugin: tlon)


OpenClaw Together provider plugin (plugin: together)


Plugin-defined config payload for together.


OpenClaw Twitch channel plugin (plugin: twitch)


Plugin-defined config payload for twitch.


OpenClaw Venice provider plugin (plugin: venice)


Plugin-defined config payload for venice.


OpenClaw Vercel AI Gateway provider plugin (plugin: vercel-ai-gateway)


Plugin-defined config payload for vercel-ai-gateway.


Per-plugin typed hook policy controls for core-enforced safety gates. Use this to constrain high-impact hook categories without disabling the entire plugin.


Controls whether this plugin may mutate prompts through typed hooks. Set false to block `before_prompt_build` and ignore prompt-mutating fields from legacy `before_agent_start`, while preserving legacy `modelOverride` and `providerOverride` behavior.


Per-plugin subagent runtime controls for model override trust and allowlists. Keep this unset unless a plugin must explicitly steer subagent model selection.


Allowed override targets for trusted plugin subagent runs as canonical "provider/model" refs. Use "*" only when you intentionally allow any model.


Explicitly allows this plugin to request provider/model overrides in background subagent runs. Keep false unless the plugin is trusted to steer model selection.


OpenClaw vLLM provider plugin (plugin: vllm)


OpenClaw voice-call plugin (plugin: voice-call)


Plugin-defined config payload for voice-call.


Use twilio, telnyx, or mock for dev/no-network.


Deep-merges with messages.tts (Microsoft is ignored for calls).


none ngrok tailscale-serve tailscale-funnel


OpenClaw Volcengine provider plugin (plugin: volcengine)


Plugin-defined config payload for volcengine.


OpenClaw WhatsApp channel plugin (plugin: whatsapp)


Plugin-defined config payload for whatsapp.


xAI API key for Grok web search (fallback: XAI_API_KEY env var).


Include inline markdown citations in Grok responses.


OpenClaw Xiaomi provider plugin (plugin: xiaomi)


Plugin-defined config payload for xiaomi.


Per-plugin typed hook policy controls for core-enforced safety gates. Use this to constrain high-impact hook categories without disabling the entire plugin.


Controls whether this plugin may mutate prompts through typed hooks. Set false to block `before_prompt_build` and ignore prompt-mutating fields from legacy `before_agent_start`, while preserving legacy `modelOverride` and `providerOverride` behavior.


Per-plugin subagent runtime controls for model override trust and allowlists. Keep this unset unless a plugin must explicitly steer subagent model selection.


Allowed override targets for trusted plugin subagent runs as canonical "provider/model" refs. Use "*" only when you intentionally allow any model.


Explicitly allows this plugin to request provider/model overrides in background subagent runs. Keep false unless the plugin is trusted to steer model selection.


OpenClaw Z.AI provider plugin (plugin: zai)


OpenClaw Zalo channel plugin (plugin: zalo)


OpenClaw Zalo Personal Account plugin via native zca-js integration (plugin: zalouser)


Plugin-defined config payload for zalouser.


CLI-managed install metadata (used by `openclaw plugins update` to locate install sources).


Resolved install directory (usually ~/.openclaw/extensions/<id>).


Resolved npm dist integrity hash for the fetched artifact (if reported by npm).


Marketplace display name recorded for marketplace-backed plugin installs (if available).


Plugin entry name inside the source marketplace, used for later updates.


Original marketplace source used to resolve the install (for example a repo path or Git URL).


ISO timestamp when npm package metadata was last resolved for this install record.


Resolved npm package name from the fetched artifact.


Resolved exact npm spec (<name>@<version>) from the fetched artifact.


Resolved npm package version from the fetched artifact (useful for non-pinned specs).


Resolved npm dist shasum for the fetched artifact (if reported by npm).


Install source ("npm", "archive", or "path").


Original archive/path used for install (if any).


Original npm spec used for install (if source is npm).


Version recorded at install time (if available).


Plugin loader configuration group for specifying filesystem paths where plugins are discovered. Keep load paths explicit and reviewed to avoid accidental untrusted extension loading.


Additional plugin files or directories scanned by the loader beyond built-in defaults. Use dedicated extension directories and avoid broad paths with unrelated executable content.


Selects which plugins own exclusive runtime slots such as memory so only one plugin provides that capability. Use explicit slot ownership to avoid overlapping providers with conflicting behavior.


Selects the active context engine plugin by id so one plugin provides context orchestration behavior.


Select the active memory plugin by id, or "none" to disable memory plugins.


Global session routing, reset, delivery policy, and maintenance controls for conversation history behavior. Keep defaults unless you need stricter isolation, retention, or delivery constraints.


Groups controls for inter-agent session exchanges, including loop prevention limits on reply chaining. Keep defaults unless you run advanced agent-to-agent automation with strict turn caps.


Max reply-back turns between requester and target agents during agent-to-agent exchanges (0-5). Use lower values to hard-limit chatter loops and preserve predictable run completion.


DM session scoping: "main" keeps continuity, while "per-peer", "per-channel-peer", and "per-account-channel-peer" increase isolation. Use isolated modes for shared inboxes or multi-account deployments.


Maps canonical identities to provider-prefixed peer IDs so equivalent users resolve to one DM thread (example: telegram:123456). Use this when the same human appears across multiple channels or accounts.


Applies a legacy idle reset window in minutes for session reuse behavior across inactivity gaps. Use this only for compatibility and prefer structured reset policies under session.reset/session.resetByType.


Overrides the canonical main session key used for continuity when dmScope or routing logic points to "main". Use a stable value only if you intentionally need custom session anchoring.


Automatic session-store maintenance controls for pruning age, entry caps, and file rotation behavior. Start in warn mode to observe impact, then enforce once thresholds are tuned.


Target size after disk-budget cleanup (high-water mark). Defaults to 80% of maxDiskBytes; set explicitly for tighter reclaim behavior on constrained disks.


Optional per-agent sessions-directory disk budget (for example `500mb`). Use this to cap session storage per agent; when exceeded, warn mode reports pressure and enforce mode performs oldest-first cleanup.


Caps total session entry count retained in the store to prevent unbounded growth over time. Use lower limits for constrained environments, or higher limits when longer history is required.


Determines whether maintenance policies are only reported ("warn") or actively applied ("enforce"). Keep "warn" during rollout and switch to "enforce" after validating safe thresholds.


Removes entries older than this duration (for example `30d` or `12h`) during maintenance passes. Use this as the primary age-retention control and align it with data retention policy.


Deprecated age-retention field kept for compatibility with legacy configs using day counts. Use session.maintenance.pruneAfter instead so duration syntax and behavior are consistent.


Retention for reset transcript archives (`*.reset.<timestamp>`). Accepts a duration (for example `30d`), or `false` to disable cleanup. Defaults to pruneAfter so reset artifacts do not grow forever.


Rotates the session store when file size exceeds a threshold such as `10mb` or `1gb`. Use this to bound single-file growth and keep backup/restore operations manageable.


Maximum parent-session token count allowed for thread/session inheritance forking. If the parent exceeds this, OpenClaw starts a fresh thread session instead of forking; set 0 to disable this protection.


Defines the default reset policy object used when no type-specific or channel-specific override applies. Set this first, then layer resetByType or resetByChannel only where behavior must differ.


Sets local-hour boundary (0-23) for daily reset mode so sessions roll over at predictable times. Use with mode=daily and align to operator timezone expectations for human-readable behavior.


Sets inactivity window before reset for idle mode and can also act as secondary guard with daily mode. Use larger values to preserve continuity or smaller values for fresher short-lived threads.


Selects reset strategy: "daily" resets at a configured hour and "idle" resets after inactivity windows. Keep one clear mode per policy to avoid surprising context turnover patterns.


Provides channel-specific reset overrides keyed by provider/channel id for fine-grained behavior control. Use this only when one channel needs exceptional reset behavior beyond type-level policies.


Overrides reset behavior by chat type (direct, group, thread) when defaults are not sufficient. Use this when group/thread traffic needs different reset cadence than direct messages.


Defines reset policy for direct chats and supersedes the base session.reset configuration for that type. Use this as the canonical direct-message override instead of the legacy dm alias.


Deprecated alias for direct reset behavior kept for backward compatibility with older configs. Use session.resetByType.direct instead so future tooling and validation remain consistent.


Defines reset policy for group chat sessions where continuity and noise patterns differ from DMs. Use shorter idle windows for busy groups if context drift becomes a problem.


Defines reset policy for thread-scoped sessions, including focused channel thread workflows. Use this when thread sessions should expire faster or slower than other chat types.


Lists message triggers that force a session reset when matched in inbound content. Use sparingly for explicit reset phrases so context is not dropped unexpectedly during normal conversation.


Sets base session grouping strategy: "per-sender" isolates by sender and "global" shares one session per channel context. Keep "per-sender" for safer multi-user behavior unless deliberate shared context is required.


Controls cross-session send permissions using allow/deny rules evaluated against channel, chatType, and key prefixes. Use this to fence where session tools can deliver messages in complex environments.


Sets fallback action when no sendPolicy rule matches: "allow" or "deny". Keep "allow" for simpler setups, or choose "deny" when you require explicit allow rules for every destination.


Ordered allow/deny rules evaluated before the default action, for example `{ action: "deny", match: { channel: "discord" } }`. Put most specific rules first so broad rules do not shadow exceptions.


Defines rule decision as "allow" or "deny" when the corresponding match criteria are satisfied. Use deny-first ordering when enforcing strict boundaries with explicit allow exceptions.


Defines optional rule match conditions that can combine channel, chatType, and key-prefix constraints. Keep matches narrow so policy intent stays readable and debugging remains straightforward.


Matches rule application to a specific channel/provider id (for example discord, telegram, slack). Use this when one channel should permit or deny delivery independently of others.


Matches rule application to chat type (direct, group, thread) so behavior varies by conversation form. Use this when DM and group destinations require different safety boundaries.


Matches a normalized session-key prefix after internal key normalization steps in policy consumers. Use this for general prefix controls, and prefer rawKeyPrefix when exact full-key matching is required.


Matches the raw, unnormalized session-key prefix for exact full-key policy targeting. Use this when normalized keyPrefix is too broad and you need agent-prefixed or transport-specific precision.


Sets the session storage file path used to persist session records across restarts. Use an explicit path only when you need custom disk layout, backup routing, or mounted-volume storage.


Shared defaults for thread-bound session routing behavior across providers that support thread focus workflows. Configure global defaults here and override per channel only when behavior differs.


Global master switch for thread-bound session routing features and focused thread delivery behavior. Keep enabled for modern thread workflows unless you need to disable thread binding globally.


Default inactivity window in hours for thread-bound sessions across providers/channels (0 disables idle auto-unfocus). Default: 24.


Optional hard max age in hours for thread-bound sessions across providers/channels (0 disables hard cap). Default: 0.


Controls interval for repeated typing indicators while replies are being prepared in typing-capable channels. Increase to reduce chatty updates or decrease for more active typing feedback.


Controls typing behavior timing: "never", "instant", "thinking", or "message" based emission points. Keep conservative modes in high-volume channels to avoid unnecessary typing noise.


Enable filesystem watching for skill-definition changes so updates can be applied without full process restart. Keep enabled in development workflows and disable in immutable production images.


Debounce window in milliseconds for coalescing rapid skill file changes before reload logic runs. Increase to reduce reload churn on frequent writes, or lower for faster edit feedback.


Talk-mode voice synthesis settings for voice identity, model selection, output format, and interruption behavior. Use this section to tune human-facing voice UX while controlling latency and cost.


Use this legacy ElevenLabs API key for Talk mode only during migration, and keep secrets in env-backed storage. Prefer talk.providers.elevenlabs.apiKey (fallback: ELEVENLABS_API_KEY).


If true (default), stop assistant speech when the user starts speaking in Talk mode. Keep enabled for conversational turn-taking.


Legacy ElevenLabs model ID for Talk mode (default: eleven_v3). Prefer talk.providers.elevenlabs.modelId.


Use this legacy ElevenLabs output format for Talk mode (for example pcm_44100 or mp3_44100_128) only during migration. Prefer talk.providers.elevenlabs.outputFormat.


Active Talk provider id (for example "elevenlabs").


Provider-specific Talk settings keyed by provider id. During migration, prefer this over legacy talk.* keys.


Provider default model ID for Talk mode.


Provider default output format for Talk mode.


Optional provider voice alias map for Talk directives.


Provider default voice ID for Talk mode.


Milliseconds of user silence before Talk mode finalizes and sends the current transcript. Leave unset to keep the platform default pause window (700 ms on macOS and Android, 900 ms on iOS).


Use this legacy ElevenLabs voice alias map (for example {"Clawd":"EXAVITQu4vr4xnSDxMaL"}) only during migration. Prefer talk.providers.elevenlabs.voiceAliases.


Legacy ElevenLabs default voice ID for Talk mode. Prefer talk.providers.elevenlabs.voiceId.


Global tool access policy and capability configuration across web, exec, media, messaging, and elevated surfaces. Use this section to constrain risky capabilities before broad rollout.


Policy for allowing agent-to-agent tool calls and constraining which target agents can be reached. Keep disabled or tightly scoped unless cross-agent orchestration is intentionally enabled.


Allowlist of target agent IDs permitted for agent_to_agent calls when orchestration is enabled. Use explicit allowlists to avoid uncontrolled cross-agent call graphs.


Enables the agent_to_agent tool surface so one agent can invoke another agent at runtime. Keep off in simple deployments and enable only when orchestration value outweighs complexity.


Absolute tool allowlist that replaces profile-derived defaults for strict environments. Use this only when you intentionally run a tightly curated subset of tool capabilities.


Extra tool allowlist entries merged on top of the selected tool profile and default policy. Keep this list small and explicit so audits can quickly identify intentional policy exceptions.


Per-provider tool allow/deny overrides keyed by channel/provider ID to tailor capabilities by surface. Use this when one provider needs stricter controls than global tool policy.


Global tool denylist that blocks listed tools even when profile or provider rules would allow them. Use deny rules for emergency lockouts and long-term defense-in-depth.


Elevated tool access controls for privileged command surfaces that should only be reachable from trusted senders. Keep disabled unless operator workflows explicitly require elevated actions.


Sender allow rules for elevated tools, usually keyed by channel/provider identity formats. Use narrow, explicit identities so elevated commands cannot be triggered by unintended users.


Enables elevated tool execution path when sender and policy checks pass. Keep disabled in public/shared channels and enable only for trusted owner-operated contexts.


Exec-tool policy grouping for shell execution host, security mode, approval behavior, and runtime bindings. Keep conservative defaults in production and tighten elevated execution paths.


Optional allowlist of model ids (e.g. "gpt-5.2" or "openai/gpt-5.2").


Experimental. Enables apply_patch for OpenAI models when allowed by tool policy.


Restrict apply_patch paths to the workspace directory (default: true). Set false to allow writing outside the workspace (dangerous).


Approval strategy for when exec commands require human confirmation before running. Use stricter ask behavior in shared channels and lower-friction settings in private operator contexts.


Selects execution host strategy for shell commands, typically controlling local vs delegated execution environment. Use the safest host mode that still satisfies your automation requirements.


Node binding configuration for exec tooling when command execution is delegated through connected nodes. Use explicit node binding only when multi-node routing is required.


When true (default), backgrounded exec sessions on exit and node exec lifecycle events enqueue a system event and request a heartbeat.


When true, successful backgrounded exec exits with empty output still enqueue a completion system event (default: false).


Directories to prepend to PATH for exec runs (gateway/sandbox).


Optional per-binary safe-bin profiles (positional limits + allowed/denied flags).


Allow stdin-only safe binaries to run without explicit allowlist entries.


Additional explicit directories trusted for safe-bin path checks (PATH entries are never auto-trusted).


Execution security posture selector controlling sandbox/approval expectations for command execution. Keep strict security mode for untrusted prompts and relax only for trusted operator workflows.


Restrict filesystem tools (read/write/edit/apply_patch) to the workspace directory (default: false).


Enable automatic link understanding pre-processing so URLs can be summarized before agent reasoning. Keep enabled for richer context, and disable when strict minimal processing is required.


Maximum number of links expanded per turn during link understanding. Use lower values to control latency/cost in chatty threads and higher values when multi-link context is critical.


Preferred model list for link understanding tasks, evaluated in order as fallbacks when supported. Use lightweight models first for routine summarization and heavier models only when needed.


Controls when link understanding runs relative to conversation context and message type. Keep scope conservative to avoid unnecessary fetches on messages where links are not actionable.


Per-link understanding timeout budget in seconds before unresolved links are skipped. Keep this bounded to avoid long stalls when external sites are slow or unreachable.


Critical threshold for repetitive patterns when detector is enabled (default: 20).


Enable generic repeated same-tool/same-params loop detection (default: true).


Enable known poll tool no-progress loop detection (default: true).


Enable ping-pong loop detection (default: true).


Enable repetitive tool-call loop detection and backoff safety checks (default: false).


Tool-loop Global Circuit Breaker Threshold

Global no-progress breaker threshold (default: 30).


Tool history window size for loop detection (default: 30).


Warning threshold for repetitive patterns when detector is enabled (default: 10).


Attachment policy for audio inputs indicating which uploaded files are eligible for audio processing. Keep restrictive defaults in mixed-content channels to avoid unintended audio workloads.


Format string for the echoed transcript message. Use `{transcript}` as a placeholder for the transcribed text. Default: '📝 "{transcript}"'.


Echo the audio transcript back to the originating chat before agent processing. When enabled, users immediately see what was heard from their voice note, helping them verify transcription accuracy before the agent acts on it. Default: false.


Enable audio understanding so voice notes or audio clips can be transcribed/summarized for agent context. Disable when audio ingestion is outside policy or unnecessary for your workflows.


Preferred language hint for audio understanding/transcription when provider support is available. Set this to improve recognition accuracy for known primary languages.


Maximum accepted audio payload size in bytes before processing is rejected or clipped by policy. Set this based on expected recording length and upstream provider limits.


Maximum characters retained from audio understanding output to prevent oversized transcript injection. Increase for long-form dictation, or lower to keep conversational turns compact.


Ordered model preferences specifically for audio understanding, used before shared media model fallback. Choose models optimized for transcription quality in your primary language/domain.


Instruction template guiding audio understanding output style, such as concise summary versus near-verbatim transcript. Keep wording consistent so downstream automations can rely on output format.


Scope selector for when audio understanding runs across inbound messages and attachments. Keep focused scopes in high-volume channels to reduce cost and avoid accidental transcription.


Timeout in seconds for audio understanding execution before the operation is cancelled. Use longer timeouts for long recordings and tighter ones for interactive chat responsiveness.


Maximum number of concurrent media understanding operations per turn across image, audio, and video tasks. Lower this in resource-constrained deployments to prevent CPU/network saturation.


Attachment handling policy for image inputs, including which message attachments qualify for image analysis. Use restrictive settings in untrusted channels to reduce unexpected processing.


Enable image understanding so attached or referenced images can be interpreted into textual context. Disable if you need text-only operation or want to avoid image-processing cost.


Maximum accepted image payload size in bytes before the item is skipped or truncated by policy. Keep limits realistic for your provider caps and infrastructure bandwidth.


Maximum characters returned from image understanding output after model response normalization. Use tighter limits to reduce prompt bloat and larger limits for detail-heavy OCR tasks.


Ordered model preferences specifically for image understanding when you want to override shared media models. Put the most reliable multimodal model first to reduce fallback attempts.


Instruction template used for image understanding requests to shape extraction style and detail level. Keep prompts deterministic so outputs stay consistent across turns and channels.


Scope selector for when image understanding is attempted (for example only explicit requests versus broader auto-detection). Keep narrow scope in busy channels to control token and API spend.


Timeout in seconds for each image understanding request before it is aborted. Increase for high-resolution analysis and lower it for latency-sensitive operator workflows.


Shared fallback model list used by media understanding tools when modality-specific model lists are not set. Keep this aligned with available multimodal providers to avoid runtime fallback churn.


Attachment eligibility policy for video analysis, defining which message files can trigger video processing. Keep this explicit in shared channels to prevent accidental large media workloads.


Enable video understanding so clips can be summarized into text for downstream reasoning and responses. Disable when processing video is out of policy or too expensive for your deployment.


Maximum accepted video payload size in bytes before policy rejection or trimming occurs. Tune this to provider and infrastructure limits to avoid repeated timeout/failure loops.


Maximum characters retained from video understanding output to control prompt growth. Raise for dense scene descriptions and lower when concise summaries are preferred.


Ordered model preferences specifically for video understanding before shared media fallback applies. Prioritize models with strong multimodal video support to minimize degraded summaries.


Instruction template for video understanding describing desired summary granularity and focus areas. Keep this stable so output quality remains predictable across model/provider fallbacks.


Scope selector controlling when video understanding is attempted across incoming events. Narrow scope in noisy channels, and broaden only where video interpretation is core to workflow.


Timeout in seconds for each video understanding request before cancellation. Use conservative values in interactive channels and longer values for offline or batch-heavy processing.


Legacy override: allow cross-context sends across all providers.


Enable broadcast action (default: true).


Allow sends across different providers (default: false).


Allow sends to other channels within the same provider (default: true).


Add a visible origin marker when sending cross-context (default: true).


Text prefix for cross-context markers (supports "{channel}").


Text suffix for cross-context markers (supports "{channel}").


Global tool profile name used to select a predefined tool policy baseline before applying allow/deny overrides. Use this for consistent environment posture across agents and keep profile names stable.


Tool policy wrapper for sandboxed agent executions so sandbox runs can have distinct capability boundaries. Use this to enforce stronger safety in sandbox contexts.


Allow/deny tool policy applied when agents run in sandboxed execution environments. Keep policies minimal so sandbox tasks cannot escalate into unnecessary external actions.


Controls which sessions can be targeted by sessions_list/sessions_history/sessions_send. ("tree" default = current session + spawned subagent sessions; "self" = only current; "agent" = any session in the current agent id; "all" = any session; cross-agent still requires tools.agentToAgent).


Tool policy wrapper for spawned subagents to restrict or expand tool availability compared to parent defaults. Use this to keep delegated agent capabilities scoped to task intent.


Allow/deny tool policy applied to spawned subagent runtimes for per-subagent hardening. Keep this narrower than parent scope when subagents run semi-autonomous workflows.


Web-tool policy grouping for search/fetch providers, limits, and fallback behavior tuning. Keep enabled settings aligned with API key availability and outbound networking policy.


Cache TTL in minutes for web_fetch results.


Enable the web_fetch tool (lightweight HTTP fetch).


Firecrawl API key (fallback: FIRECRAWL_API_KEY env var).


Firecrawl base URL (e.g. https://api.firecrawl.dev or custom endpoint).


Enable Firecrawl fallback for web_fetch (if configured).


Firecrawl maxAge (ms) for cached results when supported by the API.


When true, Firecrawl returns only the main content (default: true).


Timeout in seconds for Firecrawl requests.


Max characters returned by web_fetch (truncated).


Hard cap for web_fetch maxChars (applies to config and tool calls).


Maximum redirects allowed for web_fetch (default: 3).


Use Readability to extract main content from HTML (fallbacks to basic HTML cleanup).


Timeout in seconds for web_fetch requests.


Override User-Agent header for web_fetch requests.


Cache TTL in minutes for web_search results.


Enable the web_search tool (requires a provider API key).


Search provider id. Auto-detected from available API keys if omitted.


Timeout in seconds for web_search requests.


UI presentation settings for accenting and assistant identity shown in control surfaces. Use this for branding and readability customization without changing runtime behavior.


Assistant display identity settings for name and avatar shown in UI surfaces. Keep these values aligned with your operator-facing persona and support expectations.


Assistant avatar image source used in UI surfaces (URL, path, or data URI depending on runtime support). Use trusted assets and consistent branding dimensions for clean rendering.


Display name shown for the assistant in UI views, chat chrome, and status contexts. Keep this stable so operators can reliably identify which assistant persona is active.


Primary accent color used by UI surfaces for emphasis, badges, and visual identity cues. Use high-contrast values that remain readable across light/dark themes.


Update-channel and startup-check behavior for keeping OpenClaw runtime versions current. Use conservative channels in production and more experimental channels only in controlled environments.


How often beta-channel checks run in hours (default: 1).


Enable background auto-update for package installs (default: false).


Minimum delay before stable-channel auto-apply starts (default: 6).


Extra stable-channel rollout spread window in hours (default: 12).


Update channel for git + npm installs ("stable", "beta", or "dev").


Check for npm updates when the gateway starts (default: true).


Web channel runtime settings for heartbeat and reconnect behavior when operating web-based chat surfaces. Use reconnect values tuned to your network reliability profile and expected uptime needs.


Enables the web channel runtime and related websocket lifecycle behavior. Keep disabled when web chat is unused to reduce active connection management overhead.


Heartbeat interval in seconds for web channel connectivity and liveness maintenance. Use shorter intervals for faster detection, or longer intervals to reduce keepalive chatter.


Reconnect backoff policy for web channel reconnect attempts after transport failure. Keep bounded retries and jitter tuned to avoid thundering-herd reconnect behavior.


Exponential backoff multiplier used between reconnect attempts in web channel retry loops. Keep factor above 1 and tune with jitter for stable large-fleet reconnect behavior.


Initial reconnect delay in milliseconds before the first retry after disconnection. Use modest delays to recover quickly without immediate retry storms.


Randomization factor (0-1) applied to reconnect delays to desynchronize clients after outage events. Keep non-zero jitter in multi-client deployments to reduce synchronized spikes.


Maximum reconnect attempts before giving up for the current failure sequence (0 means no retries). Use finite caps for controlled failure handling in automation-sensitive environments.


Maximum reconnect backoff cap in milliseconds to bound retry delay growth over repeated failures. Use a reasonable cap so recovery remains timely after prolonged outages.


Setup wizard state tracking fields that record the most recent guided setup run details. Keep these fields for observability and troubleshooting of setup flows across upgrades.


ISO timestamp for when the setup wizard most recently completed on this host. Use this to confirm setup recency during support and operational audits.


Command invocation recorded for the latest wizard run to preserve execution context. Use this to reproduce setup steps when verifying setup regressions.


Source commit identifier recorded for the last wizard execution in development builds. Use this to correlate setup behavior with exact source state during debugging.


Wizard execution mode recorded as "local" or "remote" for the most recent setup flow. Use this to understand whether setup targeted direct local runtime or remote gateway topology.


OpenClaw version recorded at the time of the most recent wizard run on this config. Use this when diagnosing behavior differences across version-to-version setup changes.