// Defines user-facing config field help text for docs and UI surfaces.

import { MEDIA_AUDIO_FIELD_HELP } from "./media-audio-field-metadata.js";

import { describeTalkSilenceTimeoutDefaults } from "./talk-defaults.js";

export const FIELD_HELP: Record<string, string> = {

meta: "Metadata fields automatically maintained by OpenClaw to record write/version history for this config file. Keep these values system-managed and avoid manual edits unless debugging migration history.",

"meta.lastTouchedVersion": "Auto-set when OpenClaw writes the config.",

"meta.lastTouchedAt": "ISO timestamp of the last config write (auto-set).",

marketplaces:

"Marketplace feed and local package source profile settings. Feeds provide package selection and governance metadata, while sources define the local source names that install candidates may reference.",

"marketplaces.feeds":

"Named marketplace feed profiles. The default public profile can be used as shipped, and deployments can add or override profiles to point OpenClaw at their effective feed endpoint.",

"marketplaces.feeds.*.url":

"HTTPS URL for the marketplace feed profile. Remote feed documents cannot introduce new registry domains or credentials; they only reference locally configured sources by name.",

"marketplaces.feeds.*.verification":

"Feed authenticity policy. This slice accepts only unsigned HTTPS feeds; signed verification is added when envelope enforcement is wired.",

"marketplaces.sources":

"Named package source profiles that feed entries can reference using sourceRef. Keep credentials and registry endpoints local so remote feeds cannot bootstrap trust roots.",

"marketplaces.sources.*.type":

"Package source profile type: npm, clawhub, or git. This slice validates sourceRef names only; registry and host endpoints are added when installer resolution can enforce them.",

env: "Environment import and override settings used to supply runtime variables to the gateway process. Use this section to control shell-env loading and explicit variable injection behavior.",

"env.shellEnv":

"Shell environment import controls for loading variables from your login shell during startup. Keep this enabled when you depend on profile-defined secrets or PATH customizations.",

"env.shellEnv.enabled":

"Enables loading environment variables from the user shell profile during startup initialization. Keep enabled for developer machines, or disable in locked-down service environments with explicit env management.",

"env.shellEnv.timeoutMs":

"Maximum time in milliseconds allowed for shell environment resolution before fallback behavior applies. Use tighter timeouts for faster startup, or increase when shell initialization is heavy.",

"env.vars":

"Explicit key/value environment variable overrides merged into runtime process environment for OpenClaw. Use this for deterministic env configuration instead of relying only on shell profile side effects.",

wizard:

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

"wizard.lastRunAt":

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

"wizard.lastRunVersion":

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

"wizard.lastRunCommit":

"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.lastRunCommand":

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

"wizard.lastRunMode":

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

"wizard.securityAcknowledgedAt":

"ISO timestamp for when the setup security acknowledgement was accepted on this config. Setup uses this to avoid repeating the acknowledgement on later wizard runs.",

diagnostics:

"Diagnostics controls for targeted tracing, telemetry export, and cache inspection during debugging. Keep baseline diagnostics minimal in production and enable deeper signals only when investigating issues.",

"diagnostics.memoryPressureSnapshot":

"Whether critical memory pressure automatically captures a redacted stability snapshot. Default: false. Enable only when this host can tolerate the extra file-system scan and snapshot write during critical memory pressure.",

"diagnostics.otel":

"OpenTelemetry export settings for traces, metrics, and logs emitted by gateway components. Use this when integrating with centralized observability backends and distributed tracing pipelines.",

"diagnostics.cacheTrace":

"Cache-trace logging settings for observing cache decisions and payload context in embedded runs. Enable this temporarily for debugging and disable afterward to reduce sensitive log footprint.",

logging:

"Logging behavior controls for severity, output destinations, formatting, and sensitive-data redaction. Keep levels and redaction strict enough for production while preserving useful diagnostics.",

"logging.level":

'Primary log level threshold for runtime logger output: "silent", "fatal", "error", "warn", "info", "debug", or "trace". Keep "info" or "warn" for production, and use debug/trace only during investigation.',

"logging.file":

"Optional file path for persisted log output in addition to or instead of console logging. Use a managed writable path and align retention/rotation with your operational policy.",

"logging.consoleLevel":

'Console-specific log threshold: "silent", "fatal", "error", "warn", "info", "debug", or "trace" for terminal output control. Use this to keep local console quieter while retaining richer file logging if needed.',

"logging.consoleStyle":

'Console output format style: "pretty", "compact", or "json" based on operator and ingestion needs. Use json for machine parsing pipelines and pretty/compact for human-first terminal workflows.',

"logging.redactSensitive":

'Sensitive log/transcript redaction mode: "off" disables general log and transcript masking, while "tools" redacts sensitive tool/config payload fields in those sinks. Safety-boundary UI, tool, and diagnostic payloads may still redact even when this is "off".',

"logging.redactPatterns":

"Additional custom redact regex patterns applied to log output, persisted transcript text, and safety-boundary UI/tool/diagnostic payloads before emission. Use this to mask org-specific tokens and identifiers not covered by built-in redaction rules.",

cli: "CLI presentation controls for local command output behavior such as banner and tagline style. Use this section to keep startup output aligned with operator preference without changing runtime behavior.",

"cli.banner":

"CLI startup banner controls for title/version line and tagline style behavior. Keep banner enabled for fast version/context checks, then tune tagline mode to your preferred noise level.",

"cli.banner.taglineMode":

'Controls tagline style in the CLI startup banner: "random" (default) picks from the rotating tagline pool, "default" always shows the neutral default tagline, and "off" hides tagline text while keeping the banner version line.',

update:

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

"update.channel":

'Update channel for git + npm installs ("stable", "extended-stable", "beta", or "dev"). Extended-stable is package-only: installation is foreground-only, with optional read-only startup hints.',

"update.checkOnStart":

"Check for npm updates when the gateway starts, including read-only extended-stable hints (default: true).",

"update.auto.enabled":

"Enable background auto-update for stable and beta package installs; extended-stable never auto-applies (default: false).",

"update.auto.stableDelayHours":

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

"update.auto.stableJitterHours":

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

"update.auto.betaCheckIntervalHours": "How often beta-channel checks run in hours (default: 1).",

gateway:

"Gateway runtime surface for bind mode, auth, control UI, remote transport, and operational safety controls. Keep conservative defaults unless you intentionally expose the gateway beyond trusted local interfaces.",

"gateway.port":

"TCP port used by the gateway listener for API, control UI, and channel-facing ingress paths. Use a dedicated port and avoid collisions with reverse proxies or local developer services.",

"gateway.mode":

'Gateway operation mode: "local" runs channels and agent runtime on this host, while "remote" connects through remote transport. Keep "local" unless you intentionally run a split remote gateway topology.',

"gateway.bind":

'Network bind profile: "auto", "lan", "loopback", "custom", or "tailnet" to control interface exposure. Keep "loopback" or "auto" for safest local operation unless external clients must connect.',

"gateway.customBindHost":

"Explicit bind host/IP used when gateway.bind is set to custom for manual interface targeting. Use a precise address and avoid wildcard binds unless external exposure is required.",

"gateway.controlUi":

"Control UI hosting settings including enablement, pathing, and browser-origin/auth hardening behavior. Keep UI exposure minimal and pair with strong auth controls before internet-facing deployments.",

"gateway.controlUi.enabled":

"Enables serving the gateway Control UI from the gateway HTTP process when true. Keep enabled for local administration, and disable when an external control surface replaces it.",

"gateway.terminal":

"Operator terminal served to Control UI and mobile clients: a PTY-backed shell on the gateway host, restricted to admin-scope operator sessions. It starts in the target agent's workspace and is refused for fully-sandboxed agents (sandbox.mode 'all') rather than handing back an unconfined host shell.",

"gateway.terminal.enabled":

"Enables the operator terminal for admin-scope clients when true (default: false). This exposes a browser/mobile shell with the gateway process environment, so enable it only for trusted operator deployments. Changing this restarts the gateway so connected clients reload with the correct terminal availability and content-security policy.",

"gateway.terminal.shell":

"Shell executable the operator terminal launches. Leave unset to use the host login shell ($SHELL on Unix, %ComSpec% on Windows), or pin an explicit interpreter for a consistent operator environment.",

"gateway.terminal.detachedSessionTimeoutSeconds":

"Seconds a terminal session survives after its connection drops (laptop sleep, page reload), staying reattachable via terminal.attach with its recent output replayed. Set 0 to kill sessions the moment the connection drops. Default: 300 (5 minutes). Detached sessions keep running their commands, so shorten this on shared or exposed hosts.",

"gateway.auth":

"Authentication policy for gateway HTTP/WebSocket access including mode, credentials, trusted-proxy behavior, and rate limiting. Keep auth enabled for every non-loopback deployment.",

"gateway.auth.mode":

'Gateway auth mode: "none", "token", "password", or "trusted-proxy" depending on your edge architecture. Use token/password for direct exposure, and trusted-proxy only behind hardened identity-aware proxies.',

"gateway.auth.allowTailscale":

"Allows trusted Tailscale identity paths to satisfy gateway auth checks when configured. Use this only when your tailnet identity posture is strong and operator workflows depend on it.",

"gateway.auth.rateLimit":

"Login/auth attempt throttling controls to reduce credential brute-force risk at the gateway boundary. Keep enabled in exposed environments and tune thresholds to your traffic baseline.",

"gateway.auth.trustedProxy":

"Trusted-proxy auth header mapping for upstream identity providers that inject user claims. Use only with known proxy CIDRs and strict header allowlists to prevent spoofed identity headers.",

"gateway.trustedProxies":

"CIDR/IP allowlist of upstream proxies permitted to provide forwarded client identity headers. Keep this list narrow so untrusted hops cannot impersonate users.",

"gateway.allowRealIpFallback":

"Enables x-real-ip fallback when x-forwarded-for is missing in proxy scenarios. Keep disabled unless your ingress stack requires this compatibility behavior.",

"gateway.tools":

"Gateway-level tool exposure allow/deny policy that can restrict runtime tool availability independent of agent/tool profiles. Use this for coarse emergency controls and production hardening.",

"gateway.tools.allow":

"Explicit gateway-level tool allowlist when you want a narrow set of tools available at runtime. Use this for locked-down environments where tool scope must be tightly controlled.",

"gateway.tools.deny":

"Explicit gateway-level tool denylist to block risky tools even if lower-level policies allow them. Use deny rules for emergency response and defense-in-depth hardening.",

"gateway.handshakeTimeoutMs":

"Pre-auth Gateway WebSocket handshake timeout in milliseconds. Use higher values on loaded or low-powered hosts where local clients can connect during startup warmup. OPENCLAW_HANDSHAKE_TIMEOUT_MS still takes precedence.",

"gateway.channelHealthCheckMinutes":

"Interval in minutes for automatic channel health probing and status updates. Use lower intervals for faster detection, or higher intervals to reduce periodic probe noise.",

"gateway.channelStaleEventThresholdMinutes":

"How many minutes a connected channel can go without provider-proven transport activity before the health monitor treats it as a stale socket and triggers a restart. Default: 30.",

"gateway.channelMaxRestartsPerHour":

"Maximum number of health-monitor-initiated channel restarts allowed within a rolling one-hour window. Once hit, further restarts are skipped until the window expires. Default: 10.",

"gateway.tailscale":

"Tailscale integration settings for Serve/Funnel exposure and lifecycle handling on gateway start/exit. Keep off unless your deployment intentionally relies on Tailscale ingress.",

"gateway.tailscale.mode":

'Tailscale publish mode: "off", "serve", or "funnel" for private or public exposure paths. Use "serve" for tailnet-only access and "funnel" only when public internet reachability is required.',

"gateway.tailscale.resetOnExit":

"Resets Tailscale Serve/Funnel state on gateway exit to avoid stale published routes after shutdown. Keep enabled unless another controller manages publish lifecycle outside the gateway.",

"gateway.tailscale.serviceName":

'Optional Tailscale Service name for Serve mode, such as "svc:openclaw". The value must use Tailscale\'s svc:<dns-label> format. When set, OpenClaw passes it to tailscale serve --service and reports the derived Service URL.',

"gateway.tailscale.preserveFunnel":

"When mode='serve' and an externally configured Tailscale Funnel route already covers the gateway port, skip re-applying tailscale serve on startup. Lets operators keep Funnel exposure managed outside OpenClaw without losing it across gateway restarts.",

"gateway.remote":

"Remote gateway connection settings for direct or SSH transport when this instance proxies to another runtime host. Use remote mode only when split-host operation is intentionally configured.",

"gateway.remote.transport":

'Remote connection transport: "direct" uses configured URL connectivity, while "ssh" tunnels through SSH. Use SSH when you need encrypted tunnel semantics without exposing remote ports.',

"gateway.reload":

"Live config-reload policy for how edits are applied and when full restarts are triggered. Keep hybrid behavior for safest operational updates unless debugging reload internals.",

"gateway.tls":

"TLS certificate and key settings for terminating HTTPS directly in the gateway process. Use explicit certificates in production and avoid plaintext exposure on untrusted networks.",

"gateway.tls.enabled":

"Enables TLS termination at the gateway listener so clients connect over HTTPS/WSS directly. Keep enabled for direct internet exposure or any untrusted network boundary.",

"gateway.tls.autoGenerate":

"Auto-generates a local TLS certificate/key pair when explicit files are not configured. Use only for local/dev setups and replace with real certificates for production traffic.",

"gateway.tls.certPath":

"Filesystem path to the TLS certificate file used by the gateway when TLS is enabled. Use managed certificate paths and keep renewal automation aligned with this location.",

"gateway.tls.keyPath":

"Filesystem path to the TLS private key file used by the gateway when TLS is enabled. Keep this key file permission-restricted and rotate per your security policy.",

"gateway.tls.caPath":

"Optional CA bundle path for client verification or custom trust-chain requirements at the gateway edge. Use this when private PKI or custom certificate chains are part of deployment.",

"gateway.http":

"Gateway HTTP API configuration grouping endpoint toggles and transport-facing API exposure controls. Keep only required endpoints enabled to reduce attack surface.",

"gateway.http.endpoints":

"HTTP endpoint feature toggles under the gateway API surface for compatibility routes and optional integrations. Enable endpoints intentionally and monitor access patterns after rollout.",

"gateway.http.securityHeaders":

"Optional HTTP response security headers applied by the gateway process itself. Prefer setting these at your reverse proxy when TLS terminates there.",

"gateway.http.securityHeaders.strictTransportSecurity":

"Value for the Strict-Transport-Security response header. Set only on HTTPS origins that you fully control; use false to explicitly disable.",

"gateway.remote.url": "Remote Gateway WebSocket URL (ws:// or wss://).",

"gateway.remote.token":

"Bearer token used to authenticate this client to a remote gateway in token-auth deployments. Store via secret/env substitution and rotate alongside remote gateway auth changes.",

"gateway.remote.password":

"Password credential used for remote gateway authentication when password mode is enabled. Keep this secret managed externally and avoid plaintext values in committed config.",

"gateway.remote.tlsFingerprint":

"Expected sha256 TLS fingerprint for the remote gateway (pin to avoid MITM).",

"gateway.remote.sshTarget":

"Remote gateway over SSH (tunnels the gateway port to localhost). Format: user@host or user@host:port.",

"gateway.remote.sshIdentity": "Optional SSH identity file path (passed to ssh -i).",

"gateway.remote.sshHostKeyPolicy":

'macOS SSH host-key verification policy. "strict" requires an already trusted host key; "openssh" explicitly delegates to effective OpenSSH configuration.',

"talk.provider": 'Active Talk provider id (for example "acme-speech").',

"talk.providers":

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

"talk.providers.*": "Provider-owned Talk config fields for the matching provider id.",

"talk.providers.*.apiKey": "Provider API key for Talk mode.", // pragma: allowlist secret

"talk.realtime":

"Realtime Talk provider, model, voice, mode, transport, and brain strategy. Keep speech/TTS provider config in talk.provider and talk.providers.",

"talk.realtime.provider": "Active realtime voice provider id, such as openai or google.",

"talk.realtime.providers": "Provider-specific realtime voice settings keyed by provider id.",

"talk.realtime.providers.*": "Provider-owned realtime voice config for the matching provider id.",

"talk.realtime.providers.*.apiKey": "Provider API key for realtime Talk.", // pragma: allowlist secret

"talk.realtime.model":

"Realtime provider model id override for browser or Gateway-owned Talk sessions.",

"talk.realtime.speakerVoice":

"Realtime provider speaker voice name override for browser or Gateway-owned Talk sessions.",

"talk.realtime.speakerVoiceId":

"Realtime provider speaker voice id override for browser or Gateway-owned Talk sessions.",

"talk.realtime.voice":

"Deprecated realtime provider voice override. Use talk.realtime.speakerVoice.",

"talk.realtime.instructions":

"Additional system instructions appended to OpenClaw's built-in realtime Talk prompt. Use this for voice style, tone, and other provider-facing realtime behavior while keeping agent-consult guidance intact.",

"talk.realtime.mode": "Talk execution mode: realtime, stt-tts, or transcription.",

"talk.realtime.transport":

"Talk byte/session transport: webrtc, provider-websocket, gateway-relay, or managed-room.",

"talk.realtime.vadThreshold":

"Realtime voice activity detection threshold from 0 (most sensitive) to 1 (least sensitive).",

"talk.realtime.silenceDurationMs":

"Milliseconds of silence before a realtime Talk user turn is committed.",

"talk.realtime.prefixPaddingMs":

"Milliseconds of audio retained before realtime voice activity is detected.",

"talk.realtime.reasoningEffort":

"Provider-specific reasoning effort for realtime Talk sessions, such as minimal, low, medium, or high.",

"talk.realtime.brain":

"Talk reasoning strategy: agent-consult for Gateway-mediated agent help, direct-tools for local tool calls, or none.",

"talk.realtime.consultRouting":

"Gateway relay fallback for final user transcripts when the realtime provider skips openclaw_agent_consult. provider-direct preserves provider replies; force-agent-consult routes through OpenClaw.",

"talk.consultThinkingLevel":

"Use this to override the thinking level for the regular agent run behind Talk realtime consults.",

"talk.consultFastMode":

"Use this to set true or false fast mode for the regular agent run behind Talk realtime consults.",

"talk.speechLocale":

'BCP 47 locale id for Talk speech recognition on device nodes, for example "ru-RU". Leave unset to use each device default.',

"talk.interruptOnSpeech":

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

"talk.silenceTimeoutMs": `Milliseconds of user silence before Talk mode finalizes and sends the current transcript. Leave unset to keep the platform default pause window (${describeTalkSilenceTimeoutDefaults()}).`,

acp: "ACP runtime controls for enabling dispatch, selecting backends, constraining allowed agent targets, and tuning streamed turn projection behavior.",

"acp.enabled":

"Global ACP feature gate. Keep disabled unless ACP runtime + policy are configured.",

"acp.dispatch.enabled":

"Independent dispatch gate for ACP session turns (default: true). Set false to keep ACP commands available while blocking ACP turn execution.",

"acp.backend":

"Default ACP runtime backend id (for example: acpx). Must match a registered ACP runtime plugin backend.",

"acp.fallbacks":

"Ordered list of fallback ACP backend ids tried when the primary backend fails with UNAVAILABLE (for example: rate-limit / quota exhausted). Each entry must match a registered ACP runtime plugin backend.",

"acp.defaultAgent":

"Fallback ACP target agent id used when ACP spawns do not specify an explicit target.",

"acp.allowedAgents":

"Allowlist of ACP target agent ids permitted for ACP runtime sessions. Empty means no additional allowlist restriction.",

"acp.maxConcurrentSessions":

"Maximum concurrently active ACP sessions across this gateway process.",

"acp.stream":

"ACP streaming projection controls for chunk sizing, metadata visibility, and deduped delivery behavior.",

"acp.stream.coalesceIdleMs":

"Coalescer idle flush window in milliseconds for ACP streamed text before block replies are emitted.",

"acp.stream.maxChunkChars":

"Maximum chunk size for ACP streamed block projection before splitting into multiple block replies.",

"acp.stream.repeatSuppression":

"When true (default), suppress repeated ACP status/tool projection lines in a turn while keeping raw ACP events unchanged.",

"acp.stream.deliveryMode":

"ACP delivery style: live streams projected output incrementally, final_only buffers all projected ACP output until terminal turn events.",

"acp.stream.hiddenBoundarySeparator":

"Separator inserted before next visible assistant text when hidden ACP tool lifecycle events occurred (none|space|newline|paragraph). Default: paragraph.",

"acp.stream.maxOutputChars":

"Maximum assistant output characters projected per ACP turn before truncation notice is emitted.",

"acp.stream.maxSessionUpdateChars":

"Maximum characters for projected ACP session/update lines (tool/status updates).",

"acp.stream.tagVisibility":

"Per-sessionUpdate visibility overrides for ACP projection (for example usage_update, available_commands_update).",

"acp.runtime.ttlMinutes":

"Idle runtime TTL in minutes for ACP session workers before eligible cleanup.",

"acp.runtime.installCommand":

"Optional operator install/setup command shown by `/acp install` and `/acp doctor` when ACP backend wiring is missing.",

commitments:

"Inferred follow-up commitment controls for automatically detecting check-ins from conversation turns and delivering them through heartbeat runs.",

"commitments.enabled":

"Enable hidden LLM extraction, storage, and heartbeat delivery for inferred follow-up commitments. Default: false.",

"commitments.maxPerDay":

"Maximum inferred follow-up commitments delivered per agent session in a rolling day. Default: 3.",

"agents.list.*.skills":

"Optional allowlist of skills for this agent. If omitted, the agent inherits agents.defaults.skills when set; otherwise skills stay unrestricted. Set [] for no skills. An explicit list fully replaces inherited defaults instead of merging with them.",

"agents.list[].skills":

"Optional allowlist of skills for this agent. If omitted, the agent inherits agents.defaults.skills when set; otherwise skills stay unrestricted. Set [] for no skills. An explicit list fully replaces inherited defaults instead of merging with them.",

agents:

"Agent runtime configuration root covering defaults and explicit agent entries used for routing and execution context. Keep this section explicit so model/tool behavior stays predictable across multi-agent workflows.",

"agents.defaults":

"Shared default settings inherited by agents unless overridden per entry in agents.list. Use defaults to enforce consistent baseline behavior and reduce duplicated per-agent configuration.",

"agents.defaults.skills":

"Optional default skill allowlist inherited by agents that omit agents.list[].skills. Omit for unrestricted skills, set [] to give inheriting agents no skills, and remember explicit agents.list[].skills replaces this default instead of merging with it.",

"agents.defaults.subagents.delegationMode":

'Prompt-only sub-agent delegation strength. "suggest" keeps the default guidance; "prefer" strongly instructs the main agent to delegate anything more involved than a direct reply via sessions_spawn.',

"agents.list[].subagents.delegationMode":

"Per-agent override for sub-agent delegation strength. Use this for coordinator agents that should stay responsive and push non-trivial work into spawned sub-agents.",

"agents.list[].contextInjection":

"Per-agent override for when workspace bootstrap files are injected into this agent's system prompt. Omit to inherit agents.defaults.contextInjection.",

"agents.list[].bootstrapMaxChars":

"Per-agent override for max characters of each workspace bootstrap file injected into this agent's system prompt. Omit to inherit agents.defaults.bootstrapMaxChars.",

"agents.list[].bootstrapTotalMaxChars":

"Per-agent override for max total characters across all workspace bootstrap files injected into this agent's system prompt. Omit to inherit agents.defaults.bootstrapTotalMaxChars.",

"agents.list[].experimental":

"Per-agent experimental flags. Omitted fields inherit agents.defaults.experimental.",

"agents.list[].experimental.localModelLean":

"Per-agent override for lean local-model mode. Enable it for one smaller local-model agent without trimming tools from every agent.",

"agents.defaults.contextLimits":

"Focused per-agent-context budget defaults for selected high-volume excerpts and injected prompt blocks. Use this to tune bounded read/injection sizes without reopening any unbounded call paths.",

"agents.defaults.contextLimits.memoryGetMaxChars":

"Default max characters returned by memory_get before truncation metadata and continuation notice are added. Increase to approximate older larger excerpts, but keep it bounded.",

"agents.defaults.contextLimits.memoryGetDefaultLines":

"Default memory_get line window used when requests omit lines. This controls how many source lines are selected before the max-char cap is applied.",

"agents.defaults.contextLimits.toolResultMaxChars":

"Advanced ceiling for a single live tool result before truncation. Leave unset to use the model-context auto cap; explicit values affect both persisted live tool-result writes and overflow-recovery truncation heuristics.",

"agents.defaults.contextLimits.postCompactionMaxChars":

"Default max characters retained from AGENTS.md during post-compaction context refresh injection. Lower this to make compaction recovery cheaper, or raise it for agents that depend on longer startup guidance.",

"agents.list":

"Explicit list of configured agents with IDs and optional overrides for model, tools, identity, and workspace. Keep IDs stable over time so bindings, approvals, and session routing remain deterministic.",

"agents.list[].skillsLimits":

"Optional per-agent overrides for skills subsystem budgets. Use this when an agent needs a different skills prompt budget without introducing a second generic context-limits path.",

"agents.list[].skillsLimits.maxSkillsPromptChars":

"Per-agent override for the skills prompt character budget. This extends the existing skills.limits.maxSkillsPromptChars path instead of routing the same budget through contextLimits.",

"agents.list[].contextLimits":

"Optional per-agent overrides for the focused context budget knobs. Omitted fields inherit agents.defaults.contextLimits.",

"agents.list[].contextLimits.memoryGetMaxChars":

"Per-agent override for the default memory_get max character budget.",

"agents.list[].contextLimits.memoryGetDefaultLines":

"Per-agent override for the default memory_get line window when lines is omitted.",

"agents.list[].contextLimits.toolResultMaxChars":

"Per-agent advanced ceiling for the live tool-result max character budget. Omit to inherit defaults or the model-context auto cap.",

"agents.list[].contextLimits.postCompactionMaxChars":

"Per-agent override for the post-compaction AGENTS.md excerpt budget.",

"agents.list[].thinkingDefault":

"Optional per-agent default thinking level. Overrides agents.defaults.thinkingDefault for this agent when no per-message or session override is set.",

"agents.list[].reasoningDefault":

"Optional per-agent default reasoning visibility (on|off|stream). Applies when no per-message or session reasoning override is set.",

"agents.list[].fastModeDefault":

'Optional per-agent default for fast mode ("auto", true, or false). Applies when no per-message or session fast-mode override is set.',

"agents.list[].runtime":

"Optional runtime descriptor for this agent. Use embedded for default OpenClaw execution or acp for external ACP harness defaults.",

"agents.list[].runtime.type":

'Runtime type for this agent: "embedded" (default OpenClaw runtime) or "acp" (ACP harness defaults).',

"agents.list[].runtime.acp":

"ACP runtime defaults for this agent when runtime.type=acp. Binding-level ACP overrides still take precedence per conversation.",

"agents.list[].runtime.acp.agent":

"Optional ACP harness agent id to use for this OpenClaw agent (for example codex, claude, cursor, gemini, openclaw).",

"agents.list[].runtime.acp.backend":

"Optional ACP backend override for this agent's ACP sessions (falls back to global acp.backend).",

"agents.list[].runtime.acp.mode":

"Optional ACP session mode default for this agent (persistent or oneshot).",

"agents.list[].runtime.acp.cwd":

"Optional default working directory for this agent's ACP sessions.",

"agents.list[].identity.avatar":

"Avatar image path (relative to the agent workspace only) or a remote URL/data URL.",

"agents.defaults.heartbeat.suppressToolErrorWarnings":

"Suppress tool error warning payloads during heartbeat runs.",

"agents.list[].heartbeat.suppressToolErrorWarnings":

"Suppress tool error warning payloads during heartbeat runs.",

"agents.defaults.heartbeat.timeoutSeconds":

"Maximum time in seconds allowed for a heartbeat agent turn before it is aborted. Leave unset to use agents.defaults.timeoutSeconds when set, otherwise the heartbeat cadence capped at 600 seconds.",

"agents.list[].heartbeat.timeoutSeconds":

"Per-agent maximum time in seconds allowed for a heartbeat agent turn before it is aborted. Leave unset to inherit the merged heartbeat timeout, then agents.defaults.timeoutSeconds when set, otherwise the heartbeat cadence capped at 600 seconds.",

"agents.defaults.heartbeat.skipWhenBusy":

"When true, defer heartbeat turns on this agent's extra busy lanes: its own session-keyed subagent or nested command work. Cron lanes always defer heartbeat turns.",

"agents.list[].heartbeat.skipWhenBusy":

"Per-agent override that defers heartbeat turns on that agent's extra busy lanes: its own session-keyed subagent or nested command work. Cron lanes always defer heartbeat turns.",

browser:

"Browser runtime controls for local or remote CDP attachment, profile routing, and screenshot/snapshot behavior. Keep defaults unless your automation workflow requires custom browser transport settings.",

"browser.enabled":

"Enables browser capability wiring in the gateway so browser tools and CDP-driven workflows can run. Disable when browser automation is not needed to reduce surface area and startup work.",

"browser.cdpUrl":

"CDP/DevTools endpoint URL used to attach to an externally managed browser instance. Use this for centralized browser hosts, tunnels, or existing-session attachment, and keep URL access restricted to trusted network paths.",

"browser.actionTimeoutMs":

"Default timeout in milliseconds for browser act requests before the client gives up waiting. Raise this when healthy waits or UI interactions exceed the default request budget.",

"browser.localLaunchTimeoutMs":

"Timeout in milliseconds for locally launched managed Chrome to expose its CDP HTTP endpoint after process start. Raise this on slow single-board computers or older hosts.",

"browser.localCdpReadyTimeoutMs":

"Timeout in milliseconds for a locally launched managed browser to finish CDP websocket readiness after the process is discovered. Raise this when Chrome starts but browser start still reports CDP not reachable.",

"browser.color":

"Default accent color used for browser profile/UI cues where colored identity hints are displayed. Use consistent colors to help operators identify active browser profile context quickly.",

"browser.executablePath":

"Explicit browser executable path when auto-discovery is insufficient for your host environment. Use an absolute stable path, or a path starting with ~ for your OS home directory, so launch behavior stays deterministic across restarts.",

"browser.headless":

"Forces browser launch in headless mode when the local launcher starts browser instances. Keep headless enabled for server environments and disable only when visible UI debugging is required.",

"browser.noSandbox":

"Disables Chromium sandbox isolation flags for environments where sandboxing fails at runtime. Keep this off whenever possible because process isolation protections are reduced.",

"browser.attachOnly":

"Restricts browser mode to attach-only behavior without starting local browser processes. Use this when all browser sessions are externally managed by a remote CDP provider.",

"browser.cdpPortRangeStart":

"Starting local CDP port used for auto-allocated browser profile ports. Increase this when host-level port defaults conflict with other local services.",

"browser.defaultProfile":

"Default browser profile name selected when callers do not explicitly choose a profile. Use a stable low-privilege profile as the default to reduce accidental cross-context state use.",

"browser.profiles":

"Named browser profile connection map used for explicit routing to CDP ports or URLs with optional metadata. Keep profile names consistent and avoid overlapping endpoint definitions.",

"browser.profiles.*.cdpPort":

"Per-profile local CDP port used when connecting to browser instances by port instead of URL. Use unique ports per profile to avoid connection collisions.",

"browser.profiles.*.cdpUrl":

"Per-profile CDP/DevTools endpoint URL used for explicit browser routing by profile name. Use this for remote CDP hosts, tunnels, or existing-session profiles that should attach through a running Chrome DevTools endpoint.",

"browser.profiles.*.userDataDir":

"Per-profile Chromium user data directory for existing-session attachment through Chrome DevTools MCP. Use this for Brave, Edge, Chromium, or non-default Chrome profiles when the built-in auto-connect path would pick the wrong browser data directory on the selected host or browser node. Paths starting with ~ expand to the OS home directory.",

"browser.profiles.*.mcpCommand":

"Per-profile Chrome DevTools MCP command for existing-session attachment. Defaults to npx.",

"browser.profiles.*.mcpArgs":

"Extra per-profile Chrome DevTools MCP arguments for existing-session attachment, such as --no-usage-statistics. Endpoint arguments here override the built-in auto-connect or browser URL selection.",

"browser.profiles.*.driver":

'Per-profile browser driver mode. Use "openclaw" (or legacy "clawd") for CDP-based profiles, or use "existing-session" for Chrome DevTools MCP attachment on the selected host or browser node.',

"browser.profiles.*.executablePath":

"Per-profile browser executable path for locally launched managed browser profiles. Overrides browser.executablePath and accepts paths starting with ~ for the OS home directory.",

"browser.profiles.*.headless":

"Per-profile headless override for locally launched browser instances. Use this when one profile should stay headless without forcing browser.headless for every other profile.",

"browser.profiles.*.attachOnly":

"Per-profile attach-only override that skips local browser launch and only attaches to an existing CDP endpoint. Useful when one profile is externally managed but others are locally launched.",

"browser.profiles.*.color":

"Per-profile accent color for visual differentiation in dashboards and browser-related UI hints. Use distinct colors for high-signal operator recognition of active profiles.",

"browser.evaluateEnabled":

"Enables browser-side evaluate helpers for runtime script evaluation capabilities where supported. Keep disabled unless your workflows require evaluate semantics beyond snapshots/navigation.",

"browser.snapshotDefaults":

"Default snapshot capture configuration used when callers do not provide explicit snapshot options. Tune this for consistent capture behavior across channels and automation paths.",

"browser.snapshotDefaults.mode":

"Default snapshot extraction mode controlling how page content is transformed for agent consumption. Choose the mode that balances readability, fidelity, and token footprint for your workflows.",

"browser.tabCleanup":

"Best-effort cleanup policy for browser tabs opened by primary-agent sessions. Keep enabled to avoid stale sandbox or managed-browser tabs accumulating across long-lived gateways.",

"browser.tabCleanup.enabled":

"Enables cleanup of idle tracked browser tabs for primary-agent sessions. Disable only when external tooling owns tab lifecycle completely.",

"browser.tabCleanup.idleMinutes":

"Minutes of inactivity before a tracked primary-agent browser tab is eligible for closure. Set 0 to disable idle-time cleanup while keeping the per-session tab cap.",

"browser.tabCleanup.maxTabsPerSession":

"Maximum tracked browser tabs kept per primary-agent session. Oldest inactive tabs are closed first. Set 0 to disable the cap.",

"browser.tabCleanup.sweepMinutes":

"Minutes between browser tab cleanup sweeps. Keep this modest so idle tabs are reclaimed without adding frequent background work.",

"browser.ssrfPolicy":

"Server-side request forgery guardrail settings for browser/network fetch paths that could reach internal hosts. Keep restrictive defaults in production and open only explicitly approved targets.",

"browser.ssrfPolicy.dangerouslyAllowPrivateNetwork":

"Allows access to private-network address ranges from browser tooling. Default is disabled when unset; enable only for explicitly trusted private-network destinations.",

"browser.ssrfPolicy.allowedHostnames":

"Explicit hostname allowlist exceptions for SSRF policy checks on browser/network requests. Keep this list minimal and review entries regularly to avoid stale broad access.",

"browser.ssrfPolicy.hostnameAllowlist":

"Legacy/alternate hostname allowlist field used by SSRF policy consumers for explicit host exceptions. Use stable exact hostnames and avoid wildcard-like broad patterns.",

"browser.remoteCdpTimeoutMs":

"Timeout in milliseconds for connecting to a remote CDP endpoint before failing the browser attach attempt. The larger of this value and remoteCdpHandshakeTimeoutMs also bounds persistent remote tab enumeration. Increase for high-latency tunnels, or lower for faster failure detection.",

"browser.remoteCdpHandshakeTimeoutMs":

"Timeout in milliseconds for post-connect CDP handshake readiness checks against remote browser targets. The larger of this value and remoteCdpTimeoutMs also bounds persistent remote tab enumeration. Raise this for slow-start remote browsers and lower to fail fast in automation loops.",

"discovery.mdns.mode":

'mDNS broadcast mode ("minimal" default, "full" includes cliPath/sshPort, "off" disables mDNS).',

discovery:

"Service discovery settings for local mDNS advertisement and optional wide-area presence signaling. Keep discovery scoped to expected networks to avoid leaking service metadata.",

"discovery.wideArea":

"Wide-area discovery configuration group for exposing discovery signals beyond local-link scopes. Enable only in deployments that intentionally aggregate gateway presence across sites.",

"discovery.wideArea.enabled":

"Enables wide-area discovery signaling when your environment needs non-local gateway discovery. Keep disabled unless cross-network discovery is operationally required.",

"discovery.wideArea.domain":

"Optional unicast DNS-SD domain for wide-area discovery, such as openclaw.internal. Use this when you intentionally publish gateway discovery beyond local mDNS scopes.",

"discovery.mdns":

"mDNS discovery configuration group for local network advertisement and discovery behavior tuning. Keep minimal mode for routine LAN discovery unless extra metadata is required.",

tools:

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

"tools.allow":

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

"tools.deny":

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

"tools.web":

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

"tools.exec":

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

"tools.exec.host":

'Selects execution target strategy for shell commands. Use "auto" for runtime-aware behavior (sandbox when available, otherwise gateway), or pin sandbox/gateway/node explicitly when you need a fixed surface.',

"tools.exec.mode":

'Normalized exec policy selector. Use "auto" for classifier-reviewed approval misses, "ask" for human-reviewed misses, "allowlist" for deterministic safe commands only, or "full" for trusted local operation.',

"tools.exec.reviewer":

"Model-backed exec reviewer used by auto mode before human approval fallback. Configure a narrow model override here when you want exec review isolated from the main agent model.",

"tools.exec.reviewer.model":

"Optional provider/model override for the exec reviewer agent. Omit to reuse the current agent model.",

"tools.exec.reviewer.timeoutMs":

"Exec reviewer timeout in milliseconds before falling back to human approval (default: 30000).",

"tools.exec.security":

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

"tools.exec.ask":

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

"tools.exec.node":

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

"tools.agentToAgent":

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

"tools.agentToAgent.enabled":

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

"tools.agentToAgent.allow":

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

"tools.experimental":

"Experimental built-in tool flags. Keep these off by default and enable only when you are intentionally testing a preview surface.",

"tools.experimental.planTool":

"Enable the experimental structured `update_plan` tool for non-trivial multi-step work tracking. Leave this off unless you explicitly want the tool outside strict-agentic embedded OpenClaw runs.",

"tools.toolSearch":

"Compact large OpenClaw, MCP, and client tool catalogs. Set to true for the default code bridge or use the object form to choose structured controls or a compact visible tool directory.",

"tools.toolSearch.enabled":

"Enables Tool Search. When on, OpenClaw hides large tool catalogs behind `tool_search_code` or structured search/describe/call tools during embedded runtime runs.",

"tools.toolSearch.mode":

'Choose the model-facing surface: "code" exposes `tool_search_code`; "tools" exposes structured search/describe/call fallback tools; "directory" keeps a bounded tool directory visible, exposes a bounded set of likely or required schemas, and defers the rest behind search/describe/call.',

"tools.toolSearch.codeTimeoutMs":

"Maximum milliseconds for one `tool_search_code` execution. Runtime clamps values to the supported 1s..60s range.",

"tools.toolSearch.searchDefaultLimit":

"Default number of Tool Search results returned when the model omits a limit. Runtime clamps this to `maxSearchLimit`.",

"tools.toolSearch.maxSearchLimit":

"Maximum number of Tool Search results a model can request. Runtime clamps values to the supported 1..50 range.",

"tools.codeMode":

"Generic OpenClaw code mode. When enabled, agent runs expose only `exec` and `wait` to the model and hide normal tools behind a QuickJS-WASI catalog bridge.",

"tools.codeMode.enabled":

"Enables generic code mode. Default is off. When explicitly enabled, OpenClaw fails closed if the runtime is unavailable instead of exposing the full tool list.",

"tools.codeMode.runtime": 'Guest JavaScript runtime. Only "quickjs-wasi" is supported.',

"tools.codeMode.mode":

'Model-facing surface. Only "only" is supported: expose code-mode `exec` and `wait` and hide normal tools.',

"tools.codeMode.languages":

'Accepted source languages for `exec`. Supported values are "javascript" and "typescript".',

"tools.codeMode.timeoutMs": "Maximum milliseconds for one code-mode `exec` or `wait` call.",

"tools.codeMode.memoryLimitBytes": "QuickJS heap limit for one code-mode VM.",

"tools.codeMode.maxOutputBytes": "Maximum serialized bytes returned through code-mode output.",

"tools.codeMode.maxSnapshotBytes":

"Maximum serialized bytes retained for one suspended QuickJS snapshot.",

"tools.codeMode.maxPendingToolCalls":

"Maximum concurrent nested tool calls a code-mode VM can start before it must resume later.",

"tools.codeMode.snapshotTtlSeconds":

"How long suspended code-mode snapshots can be resumed with `wait` before they expire.",

"tools.codeMode.searchDefaultLimit":

"Default number of hidden catalog search results returned by `tools.search` inside code mode.",

"tools.codeMode.maxSearchLimit":

"Maximum number of hidden catalog search results a code-mode program can request.",

"tools.elevated":

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

"tools.elevated.enabled":

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

"tools.elevated.allowFrom":

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

"tools.subagents":

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

"tools.subagents.tools":

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

"tools.sandbox":

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

"tools.sandbox.tools":

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

web: "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.",

"web.enabled":

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

"web.heartbeatSeconds":

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

"web.reconnect":

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

"web.reconnect.initialMs":

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

"web.reconnect.maxMs":

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

"web.reconnect.factor":

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

"web.reconnect.jitter":

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

"web.reconnect.maxAttempts":

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

"web.whatsapp":

"WhatsApp Web socket timing controls used by Baileys and OpenClaw's local outbound and inbound read-receipt operation bounds. Tune these when network edges, proxies, or NATs are closing otherwise healthy WhatsApp Web sessions.",

"web.whatsapp.keepAliveIntervalMs":

"Baileys WhatsApp Web application ping interval in milliseconds. Lower values detect and refresh idle links sooner; keep this comfortably below your network's idle-flow timeout.",

"web.whatsapp.connectTimeoutMs":

"Maximum time in milliseconds Baileys waits for the WhatsApp WebSocket opening handshake. Use a higher value on slow or lossy networks that report opening handshake 408 timeouts.",

"web.whatsapp.defaultQueryTimeoutMs":

"Default Baileys query timeout and OpenClaw outbound send/presence and inbound read-receipt operation bound in milliseconds for WhatsApp Web requests. Keep aligned with upstream unless a network-specific investigation shows socket operations need longer.",

talk: "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.",

"gateway.auth.token":

"Required by default for gateway access (unless using Tailscale Serve identity); required for non-loopback binds.",

"gateway.auth.password": "Required for Tailscale funnel.",

"agents.defaults.sandbox.browser.network":

"Docker network for sandbox browser containers (default: openclaw-sandbox-browser). Avoid bridge if you need stricter isolation.",

"agents.list[].sandbox.browser.network": "Per-agent override for sandbox browser Docker network.",

"agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin":

"DANGEROUS break-glass override that allows sandbox Docker network mode container:<id>. This joins another container namespace and weakens sandbox isolation.",

"agents.list[].sandbox.docker.dangerouslyAllowContainerNamespaceJoin":

"Per-agent DANGEROUS override for container namespace joins in sandbox Docker network mode.",

"agents.defaults.sandbox.docker.gpus":

'Optional Docker GPU passthrough value passed to --gpus, for example "all" or "device=GPU-uuid". Requires a compatible host runtime such as NVIDIA Container Toolkit.',

"agents.list[].sandbox.docker.gpus":

"Per-agent Docker GPU passthrough override for sandbox containers.",

"agents.defaults.sandbox.browser.cdpSourceRange":

"Optional CIDR allowlist for container-edge CDP ingress (for example 172.21.0.1/32).",

"agents.list[].sandbox.browser.cdpSourceRange":

"Per-agent override for CDP source CIDR allowlist.",

"gateway.controlUi.basePath":

"Optional URL prefix where the Control UI is served (e.g. /openclaw).",

"gateway.controlUi.root":

"Optional filesystem root for Control UI assets (defaults to dist/control-ui).",

"gateway.controlUi.embedSandbox":

'Iframe sandbox policy for hosted Control UI embeds. "strict" disables scripts, "scripts" allows interactive embeds while keeping origin isolation (default), and "trusted" adds `allow-same-origin` for same-site documents that intentionally need stronger privileges.',

"gateway.controlUi.allowExternalEmbedUrls":

"DANGEROUS toggle that allows hosted embeds to load absolute external http(s) URLs. Keep this off unless your Control UI intentionally embeds trusted third-party pages; hosted /__openclaw__/canvas and /__openclaw__/a2ui documents do not need it.",

"gateway.controlUi.chatMessageMaxWidth":

'Optional CSS max-width for grouped Control UI chat messages, for example "960px", "82%", or "min(1280px, 82%)". Values are validated against a constrained width grammar before reaching the browser.',

"gateway.controlUi.allowedOrigins":

'Allowed browser origins for Control UI/WebChat websocket connections (full origins only, e.g. https://control.example.com). Required for non-loopback Control UI deployments unless dangerous Host-header fallback is explicitly enabled. Setting ["*"] means allow any browser origin and should be avoided outside tightly controlled local testing.',

"gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback":

"DANGEROUS toggle that enables Host-header based origin fallback for Control UI/WebChat websocket checks. This mode is supported when your deployment intentionally relies on Host-header origin policy; explicit gateway.controlUi.allowedOrigins remains the recommended hardened default.",

"gateway.controlUi.allowInsecureAuth":

"Loosens strict browser auth checks for Control UI when you must run a non-standard setup. Keep this off unless you trust your network and proxy path, because impersonation risk is higher.",

"gateway.controlUi.dangerouslyDisableDeviceAuth":

"Disables Control UI device identity checks and relies on token/password only. Use only for short-lived debugging on trusted networks, then turn it off immediately.",

"gateway.push":

"Push-delivery settings used by the gateway when it needs to wake or notify paired devices. Configure relay-backed APNs here for official iOS builds; direct APNs auth remains env-based for local/manual builds.",

"gateway.push.apns":

"APNs delivery settings for iOS devices paired to this gateway. Use relay settings for official App Store builds that register through the external push relay.",

"gateway.push.apns.relay":

"External relay settings for relay-backed APNs sends. The gateway uses the hosted OpenClaw relay by default, or this custom relay for push.test, wake nudges, and reconnect wakes after a paired official iOS build publishes a relay-backed registration.",

"gateway.push.apns.relay.baseUrl":

"Optional custom base HTTPS URL for the external APNs relay service used by official App Store iOS builds. Keep this aligned with the relay URL baked into the iOS build so registration and send traffic hit the same deployment.",

"gateway.push.apns.relay.timeoutMs":

"Timeout in milliseconds for relay send requests from the gateway to the APNs relay (default: 10000). Increase for slower relays or networks, or lower to fail wake attempts faster.",

"gateway.http.endpoints.chatCompletions.enabled":

"Enable the OpenAI-compatible `POST /v1/chat/completions` endpoint (default: false).",

"gateway.http.endpoints.chatCompletions.maxBodyBytes":

"Max request body size in bytes for `/v1/chat/completions` (default: 20MB).",

"gateway.http.endpoints.chatCompletions.maxImageParts":

"Max number of `image_url` parts accepted from the latest user message (default: 8).",

"gateway.http.endpoints.chatCompletions.maxTotalImageBytes":

"Max cumulative decoded bytes across all `image_url` parts in one request (default: 20MB).",

"gateway.http.endpoints.chatCompletions.images":

"Image fetch/validation controls for OpenAI-compatible `image_url` parts.",

"gateway.http.endpoints.chatCompletions.images.allowUrl":

"Allow server-side URL fetches for `image_url` parts (default: false; data URIs remain supported). Set this to `false` to disable URL fetching entirely.",

"gateway.http.endpoints.chatCompletions.images.urlAllowlist":

"Optional hostname allowlist for `image_url` URL fetches; supports exact hosts and `*.example.com` wildcards. Empty or omitted lists mean no hostname allowlist restriction.",

"gateway.http.endpoints.chatCompletions.images.allowedMimes":

"Allowed MIME types for `image_url` parts (case-insensitive list).",

"gateway.http.endpoints.chatCompletions.images.maxBytes":

"Max bytes per fetched/decoded `image_url` image (default: 10MB).",

"gateway.http.endpoints.chatCompletions.images.maxRedirects":

"Max HTTP redirects allowed when fetching `image_url` URLs (default: 3).",

"gateway.http.endpoints.chatCompletions.images.timeoutMs":

"Timeout in milliseconds for `image_url` URL fetches (default: 10000).",

"gateway.reload.mode":

'Controls how config edits are applied: "off" ignores live edits, "restart" always restarts, "hot" applies in-process, and "hybrid" tries hot then restarts if required. Keep "hybrid" for safest routine updates.',

"gateway.reload.debounceMs": "Debounce window (ms) before applying config changes.",

"gateway.reload.deferralTimeoutMs":

"Optional maximum time (ms) to wait for in-flight operations before forcing a restart. Omit to use the default bounded wait; set 0 to wait indefinitely with periodic still-pending warnings. Lower positive values risk aborting active subagent LLM calls.",

"gateway.nodes.browser.mode":

'Node browser routing ("auto" = pick single connected browser node, "manual" = require node param, "off" = disable).',

"gateway.nodes.browser.node": "Pin browser routing to a specific node id or name (optional).",

"gateway.nodes.pairing":

"Node pairing policy settings. Defaults keep CIDR auto-approval disabled; enable only with explicit trusted CIDR/IP allowlists you control.",

"gateway.nodes.pairing.autoApproveCidrs":

"Opt-in CIDR/IP allowlist for auto-approving first-time node-role device pairing with no requested scopes. Disabled when unset. Operator, browser, Control UI, and any role, scope, metadata, or public-key upgrade pairing still require manual approval.",

"gateway.nodes.allowCommands":

"Extra node.invoke commands to allow beyond the gateway defaults (array of command strings). Enabling dangerous commands here is a security-sensitive override and is flagged by `openclaw security audit`.",

"gateway.nodes.denyCommands":

"Node command names to block even if present in node claims or default allowlist (exact command-name matching only, e.g. `system.run`; does not inspect shell text inside that command).",

nodeHost:

"Node host controls for features exposed from this gateway node to other nodes or clients. Keep defaults unless you intentionally proxy local capabilities across your node network.",

"nodeHost.browserProxy":

"Groups browser-proxy settings for exposing local browser control through node routing. Enable only when remote node workflows need your local browser profiles.",

"nodeHost.browserProxy.enabled":

"Expose the local browser control server through node proxy routing so remote clients can use this host's browser capabilities. Keep disabled unless remote automation explicitly depends on it.",

"nodeHost.browserProxy.allowProfiles":

"Optional allowlist of browser profile names exposed through node proxy routing. Leave empty to preserve the default full profile surface, including profile create/delete routes. When set, OpenClaw enforces least-privilege profile access and blocks persistent profile create/delete through the proxy.",

media:

"Top-level media behavior shared across providers and tools that handle inbound files. Keep defaults unless you need stable filenames for external processing pipelines or longer-lived inbound media retention.",

"media.preserveFilenames":

"When enabled, uploaded media keeps its original filename instead of a generated temp-safe name. Turn this on when downstream automations depend on stable names, and leave off to reduce accidental filename leakage.",

"media.ttlHours":

"Optional retention window in hours for persisted media cleanup across the full media tree. Leave unset to disable automatic cleanup (media writes never prune), or set values like 24 (1 day) or 168 (7 days) to periodically remove media older than the window.",

audio:

"Global audio ingestion settings used before higher-level tools process speech or media content. Configure this when you need deterministic transcription behavior for voice notes and clips.",

"audio.transcription":

"Command-based transcription settings for converting audio files into text before agent handling. Keep a simple, deterministic command path here so failures are easy to diagnose in logs.",

"audio.transcription.command":

'Executable + args used to transcribe audio (first token must be a safe binary/path), for example `["whisper-cli", "--model", "small", "{{MediaPath}}"]`. Deprecated `{input}` placeholders are migrated to `{{MediaPath}}` by `openclaw doctor --fix`.',

"audio.transcription.timeoutSeconds":

"Maximum time allowed for the transcription command to finish before it is aborted. Increase this for longer recordings, and keep it tight in latency-sensitive deployments.",

bindings:

"Top-level binding rules for routing and persistent ACP conversation ownership. Use type=route for normal routing and type=acp for persistent ACP harness bindings.",

"bindings[].type":

'Binding kind. Use "route" (or omit for legacy route entries) for normal routing, and "acp" for persistent ACP conversation bindings.',

"bindings[].agentId":

"Target agent ID that receives traffic when the corresponding binding match rule is satisfied. Use valid configured agent IDs only so routing does not fail at runtime.",

"bindings[].session":

"Optional route session overrides for conversations matched by this binding. Use this when a narrow route should keep the same agent but isolate session continuity differently.",

"bindings[].session.dmScope":

'Optional DM session scope override for this route binding. For example, keep global session.dmScope="main" while using "per-account-channel-peer" for selected direct peers.',

"bindings[].match":

"Match rule object for deciding when a binding applies, including channel and optional account/peer constraints. Keep rules narrow to avoid accidental agent takeover across contexts.",

"bindings[].match.channel":

"Channel/provider identifier this binding applies to, such as `telegram`, `discord`, or a plugin channel ID. Use the configured channel key exactly so binding evaluation works reliably.",

"bindings[].match.accountId":

"Optional account selector for multi-account channel setups so the binding applies only to one identity. Use this when account scoping is required for the route and leave unset otherwise.",

"bindings[].match.peer":

"Optional peer matcher for specific conversations including peer kind and peer id. Use this when only one direct/group/channel target should be pinned to an agent.",

"bindings[].match.peer.kind":

'Peer conversation type: "direct", "group", "channel", or legacy "dm" (deprecated alias for direct). Prefer "direct" for new configs and keep kind aligned with channel semantics.',

"bindings[].match.peer.id":

"Conversation identifier used with peer matching, such as a chat ID, channel ID, or group ID from the provider. Keep this exact to avoid silent non-matches.",

"bindings[].match.guildId":

"Optional Discord-style guild/server ID constraint for binding evaluation in multi-server deployments. Use this when the same peer identifiers can appear across different guilds.",

"bindings[].match.teamId":

"Optional team/workspace ID constraint used by providers that scope chats under teams. Add this when you need bindings isolated to one workspace context.",

"bindings[].match.roles":

"Optional role-based filter list used by providers that attach roles to chat context. Use this to route privileged or operational role traffic to specialized agents.",

"bindings[].acp":

"Optional per-binding ACP overrides for bindings[].type=acp. This layer overrides agents.list[].runtime.acp defaults for the matched conversation.",

"bindings[].acp.mode": "ACP session mode override for this binding (persistent or oneshot).",

"bindings[].acp.label":

"Human-friendly label for ACP status/diagnostics in this bound conversation.",

"bindings[].acp.cwd": "Working directory override for ACP sessions created from this binding.",

"bindings[].acp.backend":

"ACP backend override for this binding (falls back to agent runtime ACP backend, then global acp.backend).",

broadcast:

"Broadcast routing map for sending the same outbound message to multiple peer IDs per source conversation. Keep this minimal and audited because one source can fan out to many destinations.",

"broadcast.strategy":

'Delivery order for broadcast fan-out: "parallel" sends to all targets concurrently, while "sequential" sends one-by-one. Use "parallel" for speed and "sequential" for stricter ordering/backpressure control.',

"broadcast.*":

"Per-source broadcast destination list where each key is a source peer ID and the value is an array of destination peer IDs. Keep lists intentional to avoid accidental message amplification.",

"diagnostics.flags":

'Enable targeted diagnostics logs by flag (e.g. ["telegram.http"]). Supports wildcards like "telegram.*" or "*".',

"diagnostics.enabled":

"Master toggle for diagnostics instrumentation output in logs and telemetry wiring paths. Defaults to enabled; set false only in tightly constrained environments.",

"diagnostics.stuckSessionWarnMs":

"No-progress age threshold in milliseconds for classifying long processing sessions as long-running, stalled, or stuck. Reply, tool, status, block, and ACP progress reset the timer; repeated stuck diagnostics back off while unchanged.",

"diagnostics.stuckSessionAbortMs":

"No-progress age threshold in milliseconds before eligible stalled active work may be abort-drained for recovery. Defaults to the safer extended embedded-run recovery window.",

"diagnostics.otel.enabled":

"Enables OpenTelemetry export pipeline for traces, metrics, and logs based on configured endpoint/protocol settings. Keep disabled unless your collector endpoint and auth are fully configured.",

"diagnostics.otel.endpoint":

"Collector endpoint URL used for OpenTelemetry export transport, including scheme and port. Use a reachable, trusted collector endpoint and monitor ingestion errors after rollout.",

"diagnostics.otel.tracesEndpoint":

"Signal-specific OTLP/HTTP trace endpoint. When set, this overrides diagnostics.otel.endpoint and OTEL_EXPORTER_OTLP_ENDPOINT for trace export only.",

"diagnostics.otel.metricsEndpoint":

"Signal-specific OTLP/HTTP metrics endpoint. When set, this overrides diagnostics.otel.endpoint and OTEL_EXPORTER_OTLP_ENDPOINT for metrics export only.",

"diagnostics.otel.logsEndpoint":

"Signal-specific OTLP/HTTP logs endpoint. When set, this overrides diagnostics.otel.endpoint and OTEL_EXPORTER_OTLP_ENDPOINT for log export only.",

"diagnostics.otel.protocol":

'OTel transport protocol for telemetry export: "http/protobuf" or "grpc" depending on collector support. Use the protocol your observability backend expects to avoid dropped telemetry payloads.',

"diagnostics.otel.headers":

"Additional HTTP/gRPC metadata headers sent with OpenTelemetry export requests, often used for tenant auth or routing. Keep secrets in env-backed values and avoid unnecessary header sprawl.",

"diagnostics.otel.serviceName":

"Service name reported in telemetry resource attributes to identify this gateway instance in observability backends. Use stable names so dashboards and alerts remain consistent over deployments.",

"diagnostics.otel.traces":

"Enable trace signal export to the configured OpenTelemetry collector endpoint. Keep enabled when latency/debug tracing is needed, and disable if you only want metrics/logs.",

"diagnostics.otel.metrics":

"Enable metrics signal export to the configured OpenTelemetry collector endpoint. Keep enabled for runtime health dashboards, and disable only if metric volume must be minimized.",

"diagnostics.otel.logs":

"Enable log signal export through OpenTelemetry in addition to local logging sinks. Use this when centralized log correlation is required across services and agents.",

"diagnostics.otel.logsExporter":

'Log export sink for diagnostics.otel.logs. Use "otlp" for the configured OTLP logs endpoint, "stdout" for one JSON record per stdout line in container log pipelines, and "both" when both sinks are required.',

"diagnostics.otel.sampleRate":

"Trace sampling rate (0-1) controlling how much trace traffic is exported to observability backends. Lower rates reduce overhead/cost, while higher rates improve debugging fidelity.",

"diagnostics.otel.flushIntervalMs":

"Interval in milliseconds for periodic telemetry flush from buffers to the collector. Increase to reduce export chatter, or lower for faster visibility during active incident response.",

"diagnostics.otel.captureContent":

"Opt-in OTEL span content capture. Defaults to off; boolean true captures non-system message/tool content, while the object form lets you enable specific content classes.",

"diagnostics.otel.captureContent.enabled":

"Master switch for granular OTEL content capture fields. Keep disabled unless your collector is approved for raw prompt, response, or tool content.",

"diagnostics.otel.captureContent.inputMessages":

"Capture model input message text on OTEL spans when content capture is enabled.",

"diagnostics.otel.captureContent.outputMessages":

"Capture model output message text on OTEL spans when content capture is enabled.",

"diagnostics.otel.captureContent.toolInputs":

"Capture tool input text on OTEL spans when content capture is enabled.",

"diagnostics.otel.captureContent.toolOutputs":

"Capture tool output text on OTEL spans when content capture is enabled.",

"diagnostics.otel.captureContent.systemPrompt":

"Capture system prompt text on OTEL spans when content capture is enabled. This remains off unless explicitly enabled.",

"diagnostics.otel.captureContent.toolDefinitions":

"Capture model tool definition schemas on OTEL spans when content capture is enabled.",

"diagnostics.cacheTrace.enabled":

"Log cache trace snapshots for embedded agent runs (default: false).",

"diagnostics.cacheTrace.filePath":

"JSONL output path for cache trace logs (default: $OPENCLAW_STATE_DIR/logs/cache-trace.jsonl).",

"diagnostics.cacheTrace.includeMessages":

"Include full message payloads in trace output (default: true).",

"diagnostics.cacheTrace.includePrompt": "Include prompt text in trace output (default: true).",

"diagnostics.cacheTrace.includeSystem": "Include system prompt in trace output (default: true).",

"tools.exec.applyPatch.enabled":

"Enable or disable apply_patch for OpenAI and OpenAI Codex models when allowed by tool policy (default: true).",

"tools.exec.applyPatch.workspaceOnly":

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

"tools.exec.applyPatch.allowModels":

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

"tools.loopDetection.enabled":

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

"tools.loopDetection.historySize": "Tool history window size for loop detection (default: 30).",

"tools.loopDetection.warningThreshold":

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

"tools.loopDetection.unknownToolThreshold":

"Block repeated calls to the same unavailable tool after this many misses (default: 10).",

"tools.loopDetection.criticalThreshold":

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

"tools.loopDetection.globalCircuitBreakerThreshold":

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

"tools.loopDetection.detectors.genericRepeat":

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

"tools.loopDetection.detectors.knownPollNoProgress":

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

"tools.loopDetection.detectors.pingPong": "Enable ping-pong loop detection (default: true).",

"tools.loopDetection.postCompactionGuard.windowSize":

"Number of post-compaction attempts during which the guard stays armed (default: 3). Lower values are stricter; higher values give the agent more attempts before abort.",

"tools.exec.notifyOnExit":

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

"tools.exec.notifyOnExitEmptySuccess":

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

"tools.exec.pathPrepend": "Directories to prepend to PATH for exec runs (gateway/sandbox).",

"tools.exec.safeBins":

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

"tools.exec.strictInlineEval":

"Require explicit approval for interpreter inline-eval forms such as `python -c`, `node -e`, `ruby -e`, or `osascript -e`. Prevents silent allowlist reuse and downgrades allow-always to ask-each-time for those forms.",

"tools.exec.commandHighlighting":

"Show parser-derived command highlights in exec approval prompts (default: false). Enable this to render highlighted command text without changing exec approval policy.",

"tools.exec.safeBinTrustedDirs":

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

"tools.exec.safeBinProfiles":

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

"tools.profile":

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

"tools.alsoAllow":

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

"tools.byProvider":

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

"agents.list[].tools.profile":

"Per-agent override for tool profile selection when one agent needs a different capability baseline. Use this sparingly so policy differences across agents stay intentional and reviewable.",

"agents.list[].tools.alsoAllow":

"Per-agent additive allowlist for tools on top of global and profile policy. Keep narrow to avoid accidental privilege expansion on specialized agents.",

"agents.list[].tools.codeMode":

"Per-agent code mode override. Use this to test or roll out exec/wait tool-surface mode for one agent without enabling it fleet-wide.",

"agents.list[].tools.byProvider":

"Per-agent provider-specific tool policy overrides for channel-scoped capability control. Use this when a single agent needs tighter restrictions on one provider than others.",

"agents.list[].tools.message.crossContext.allowWithinProvider":

"Per-agent message guard for sending to other conversations on the same provider. Set false for current-conversation-only public agents.",

"agents.list[].tools.message.crossContext.allowAcrossProviders":

"Per-agent message guard for sending across providers. Keep false for public or sandboxed agents.",

"agents.list[].tools.message.actions.allow":

'Per-agent message action allowlist for the message tool. Set to a minimal list such as ["send"] for public sandbox agents so read, edit, delete, reaction, and other provider-specific message actions stay hidden and blocked.',

"tools.exec.approvalRunningNoticeMs":

"Delay in milliseconds before showing an in-progress notice after an exec approval is granted. Increase to reduce flicker for fast commands, or lower for quicker operator feedback.",

"tools.links.enabled":

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

"tools.links.maxLinks":

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

"tools.links.timeoutSeconds":

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

"tools.links.models":

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

"tools.links.scope":

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

"tools.media.models":

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

"tools.media.concurrency":

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

"tools.media.asyncCompletion.directSend":

"Deprecated compatibility flag. Async media generation completions are requester-session mediated so the agent can decide how to tell the user and use the message tool when source delivery requires it.",

"tools.media.image.enabled":

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

"tools.media.image.maxBytes":

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

"tools.media.image.maxChars":

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

"tools.media.image.prompt":

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

"tools.media.image.timeoutSeconds":

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

"tools.media.image.attachments":

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

"tools.media.image.models":

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

"tools.media.image.scope":

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

...MEDIA_AUDIO_FIELD_HELP,

"tools.media.video.enabled":

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

"tools.media.video.maxBytes":

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

"tools.media.video.maxChars":

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

"tools.media.video.prompt":

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

"tools.media.video.timeoutSeconds":

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

"tools.media.video.attachments":

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

"tools.media.video.models":

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

"tools.media.video.scope":

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

"skills.load.extraDirs":

"Additional shared skill roots to scan at lowest precedence. Use this for sibling repos or shared skill packs that should be available without copying them into the OpenClaw workspace.",

"skills.load.allowSymlinkTargets":

"Trusted real target roots that skill symlinks may resolve into when they sit outside their configured source root. Keep this narrow, such as a sibling repo skills directory.",

"skills.load.watch":

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

"skills.load.watchDebounceMs":

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

"skills.workshop.allowSymlinkTargetWrites":

"Allows Skill Workshop apply to write through symlinked workspace skill paths whose real target is already trusted by skills.load.allowSymlinkTargets. Keep disabled unless operators intentionally want generated proposal applies to mutate those shared skill roots.",

approvals:

"Approval routing controls for forwarding exec and plugin approval requests to chat destinations outside the originating session. Keep these disabled unless operators need explicit out-of-band approval visibility.",

"approvals.exec":

"Groups exec-approval forwarding behavior including enablement, routing mode, filters, and explicit targets. Configure here when approval prompts must reach operational channels instead of only the origin thread.",

"approvals.exec.enabled":

"Enables forwarding of exec approval requests to configured delivery destinations (default: false). Keep disabled in low-risk setups and enable only when human approval responders need channel-visible prompts.",

"approvals.exec.mode":

'Controls where approval prompts are sent: "session" uses origin chat, "targets" uses configured targets, and "both" sends to both paths. Use "session" as baseline and expand only when operational workflow requires redundancy.',

"approvals.exec.agentFilter":

'Optional allowlist of agent IDs eligible for forwarded approvals, for example `["primary", "ops-agent"]`. Use this to limit forwarding blast radius and avoid notifying channels for unrelated agents.',

"approvals.exec.sessionFilter":

'Optional session-key filters matched as substring or regex-style patterns, for example `["discord:", "^agent:ops:"]`. Use narrow patterns so only intended approval contexts are forwarded to shared destinations.',

"approvals.exec.targets":

"Explicit delivery targets used when forwarding mode includes targets, each with channel and destination details. Keep target lists least-privilege and validate each destination before enabling broad forwarding.",

"approvals.exec.targets[].channel":

"Channel/provider ID used for forwarded approval delivery, such as discord, slack, or a plugin channel id. Use valid channel IDs only so approvals do not silently fail due to unknown routes.",

"approvals.exec.targets[].to":

"Destination identifier inside the target channel (channel ID, user ID, or thread root depending on provider). Verify semantics per provider because destination format differs across channel integrations.",

"approvals.exec.targets[].accountId":

"Optional account selector for multi-account channel setups when approvals must route through a specific account context. Use this only when the target channel has multiple configured identities.",

"approvals.exec.targets[].threadId":

"Optional thread/topic target for channels that support threaded delivery of forwarded approvals. Use this to keep approval traffic contained in operational threads instead of main channels.",

"approvals.plugin":

"Groups plugin-approval forwarding behavior including enablement, routing mode, filters, and explicit targets. Independent of exec approval forwarding. Configure here when plugin approval prompts must reach operational channels.",

"approvals.plugin.enabled":

"Enables forwarding of plugin approval requests to configured delivery destinations (default: false). Independent of approvals.exec.enabled.",

"approvals.plugin.mode":

'Controls where plugin approval prompts are sent: "session" uses origin chat, "targets" uses configured targets, and "both" sends to both paths.',

"approvals.plugin.agentFilter":

'Optional allowlist of agent IDs eligible for forwarded plugin approvals, for example `["primary", "ops-agent"]`. Use this to limit forwarding blast radius.',

"approvals.plugin.sessionFilter":

'Optional session-key filters matched as substring or regex-style patterns, for example `["discord:", "^agent:ops:"]`. Use narrow patterns so only intended approval contexts are forwarded.',

"approvals.plugin.targets":

"Explicit delivery targets used when plugin approval forwarding mode includes targets, each with channel and destination details.",

"approvals.plugin.targets[].channel":

"Channel/provider ID used for forwarded plugin approval delivery, such as discord, slack, or a plugin channel id.",

"approvals.plugin.targets[].to":

"Destination identifier inside the target channel (channel ID, user ID, or thread root depending on provider).",

"approvals.plugin.targets[].accountId":

"Optional account selector for multi-account channel setups when plugin approvals must route through a specific account context.",

"approvals.plugin.targets[].threadId":

"Optional thread/topic target for channels that support threaded delivery of forwarded plugin approvals.",

"tools.fs.workspaceOnly":

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

"tools.sessions.visibility":

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

"tools.message.allowCrossContextSend":

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

"tools.message.crossContext.allowWithinProvider":

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

"tools.message.crossContext.allowAcrossProviders":

"Allow sends across different providers (default: false).",

"tools.message.crossContext.marker.enabled":

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

"tools.message.crossContext.marker.prefix":

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

"tools.message.crossContext.marker.suffix":

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

"tools.message.broadcast.enabled": "Enable broadcast action (default: true).",

"tools.message.actions.allow":

"Global message action allowlist for the message tool. Use only when the whole runtime should expose and accept a reduced action set; prefer per-agent allowlists for public or sandboxed agents.",

"tools.web.search.enabled":

"Enable managed web_search and optional Codex-native search for eligible models.",

"tools.web.search.provider":

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

"tools.web.search.maxResults": "Number of results to return (1-10).",

"tools.web.search.timeoutSeconds": "Timeout in seconds for web_search requests.",

"tools.web.search.cacheTtlMinutes": "Cache TTL in minutes for web_search results.",

"tools.web.search.openaiCodex.enabled":

"Enable native Codex web search for Codex-capable models.",

"tools.web.search.openaiCodex.mode":

'Native Codex web search preference: "cached" (default; unrestricted Codex turns resolve it to live) or "live".',

"tools.web.search.openaiCodex.allowedDomains":

"Optional domain allowlist passed to the native Codex web_search tool.",

"tools.web.search.openaiCodex.contextSize":

'Native Codex search context size hint: "low", "medium", or "high".',

"tools.web.search.openaiCodex.userLocation.country":

"Approximate country sent to native Codex web search.",

"tools.web.search.openaiCodex.userLocation.region":

"Approximate region/state sent to native Codex web search.",

"tools.web.search.openaiCodex.userLocation.city":

"Approximate city sent to native Codex web search.",

"tools.web.search.openaiCodex.userLocation.timezone":

"Approximate timezone sent to native Codex web search.",

"tools.web.search.brave.mode":

'Brave Search mode: "web" (URL results) or "llm-context" (pre-extracted page content for LLM grounding).',

"tools.web.fetch.enabled": "Enable the web_fetch tool (lightweight HTTP fetch).",

"tools.web.fetch.maxChars": "Max characters returned by web_fetch (truncated).",

"tools.web.fetch.maxCharsCap":

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

"tools.web.fetch.maxResponseBytes": "Max download size before truncation.",

"tools.web.fetch.provider": "Web fetch fallback provider id.",

"tools.web.fetch.timeoutSeconds": "Timeout in seconds for web_fetch requests.",

"tools.web.fetch.cacheTtlMinutes": "Cache TTL in minutes for web_fetch results.",

"tools.web.fetch.maxRedirects": "Maximum redirects allowed for web_fetch (default: 3).",

"tools.web.fetch.userAgent": "Override User-Agent header for web_fetch requests.",

"tools.web.fetch.readability":

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

"tools.web.fetch.useTrustedEnvProxy":

"Route web_fetch through a trusted HTTP(S) env proxy and let the proxy resolve DNS. Enable only when that proxy is operator-controlled and enforces outbound policy after DNS resolution.",

"tools.web.fetch.ssrfPolicy":

"Scoped SSRF policy overrides for web_fetch. Keep this narrow and opt in only for known local-network proxy environments.",

"tools.web.fetch.ssrfPolicy.allowRfc2544BenchmarkRange":

"Allow RFC 2544 benchmark-range IPs (198.18.0.0/15) for fake-IP proxy compatibility such as Clash or Surge.",

"tools.web.fetch.ssrfPolicy.allowIpv6UniqueLocalRange":

"Allow IPv6 Unique Local Addresses (fc00::/7) for trusted fake-IP proxy compatibility such as sing-box, Clash, or Surge.",

models:

"Model catalog root for provider definitions, merge/replace behavior, and optional Bedrock discovery integration. Keep provider definitions explicit and validated before relying on production failover paths.",

"models.mode":

'Controls provider catalog behavior: "merge" keeps built-ins and overlays your custom providers, while "replace" uses only your configured providers. In "merge", matching provider IDs preserve non-empty agent models.json baseUrl values, while apiKey values are preserved only when the provider is not SecretRef-managed in current config/auth-profile context; SecretRef-managed providers refresh apiKey from current source markers, and matching model contextWindow/maxTokens use the higher value between explicit and implicit entries.',

"models.providers":

"Provider map keyed by provider ID containing connection/auth settings and concrete model definitions. Built-in providers may be tuned with provider-level overlays; custom providers must include baseUrl and models. Use stable provider keys so references from agents and tooling remain portable across environments.",

"models.pricing":

"Controls the optional background model-pricing bootstrap that fetches remote per-token cost catalogs.",

"models.pricing.enabled":

"Enable the background model-pricing bootstrap. Set to false to skip OpenRouter and LiteLLM catalog fetches during Gateway startup; changing this value requires a Gateway restart.",

"models.providers.*.baseUrl":

"Base URL for the provider endpoint used to serve model requests for that provider entry. Use HTTPS endpoints and keep URLs environment-specific through config templating where needed.",

"models.providers.*.apiKey":

"Provider credential used for API-key based authentication when the provider requires direct key auth. Use secret/env substitution and avoid storing real keys in committed config files.",

"models.providers.*.auth":