--- summary: "Configuration overview: common tasks, quick setup, and links to the full reference" read_when: - Setting up OpenClaw for the first time - Looking for common configuration patterns - Navigating to specific config sections title: "Configuration" --- OpenClaw reads an optional **JSON5** config from `~/.openclaw/openclaw.json`. If the file is missing, OpenClaw uses safe defaults. The active config path must be a regular file. OpenClaw-owned writes replace it atomically (rename onto the path), so a symlinked `openclaw.json` gets its target replaced rather than written through - avoid symlinked config layouts. If you keep config outside the default state directory, point `OPENCLAW_CONFIG_PATH` directly at the real file. Common reasons to add a config: - Connect channels and control who can message the bot - Set models, tools, sandboxing, or automation (cron, hooks) - Tune sessions, media, networking, or UI See the [full reference](/gateway/configuration-reference) for every available field. Configuration follows a two-bucket rule: root siblings hold infrastructure and cross-agent defaults, while `agents.defaults` holds agent-loop behavior. Entries under `agents.entries` may override either bucket where the schema supports a per-agent override. Agents and automation should use `config.schema.lookup` for exact field-level docs before editing config. Use this page for task-oriented guidance and [Configuration reference](/gateway/configuration-reference) for the broader field map and defaults. **New to configuration?** Start with `openclaw onboard` for interactive setup, or check out the [Configuration Examples](/gateway/configuration-examples) guide for complete copy-paste configs. ## Minimal config ```json5 // ~/.openclaw/openclaw.json { agents: { defaults: { workspace: "~/.openclaw/workspace" } }, channels: { whatsapp: { allowFrom: ["+15555550123"] } }, } ``` ## Editing config ```bash openclaw onboard # full onboarding flow openclaw configure # config wizard ``` ```bash openclaw config get agents.defaults.workspace openclaw config set agents.defaults.heartbeat.every "2h" openclaw config unset plugins.entries.brave.config.webSearch.apiKey ``` Open [http://127.0.0.1:18789](http://127.0.0.1:18789) and use the **Config** tab. The Control UI renders a form from the live config schema, including field `title` / `description` docs metadata plus plugin and channel schemas when available, with a **Raw JSON** editor as an escape hatch. For drill-down UIs and other tooling, the gateway also exposes `config.schema.lookup` to fetch one path-scoped schema node plus immediate child summaries. Settings show common fields first. Each section keeps its advanced fields in a collapsed **Advanced (N)** group; use **Show advanced** to expand all groups. Settings search always includes both tiers and opens the matching advanced group when needed. Per-channel settings under **Settings -> Channels** use the same split and share the **Show advanced** preference, with **Hide advanced** on the divider to collapse them again. Edit `~/.openclaw/openclaw.json` directly. The Gateway watches the file and applies changes automatically (see [hot reload](#config-hot-reload)). ## Strict validation OpenClaw only accepts configurations that fully match the schema. Gateway startup first applies safe legacy-key migrations to eligible single-file configs. Unknown keys, malformed types, or invalid values that remain cause the Gateway to **refuse to start**. The only root-level exception is `$schema` (string), so editors can attach JSON Schema metadata. `openclaw config schema` prints the canonical JSON Schema used by Control UI and validation. `config.schema.lookup` fetches a single path-scoped node plus child summaries for drill-down tooling. Field `title`/`description` docs metadata carries through nested objects, wildcard (`*`), array-item (`[]`), and `anyOf`/ `oneOf`/`allOf` branches. Runtime plugin and channel schemas merge in when the manifest registry is loaded. Every config leaf has a common or advanced presentation tier in `uiHints`. `advanced: false` marks common settings and `advanced: true` marks advanced settings. A leaf inherits the nearest ancestor tier when it has no direct hint; paths with no declared ancestor default to advanced. This affects presentation only, not validation, defaults, reload behavior, or whether the key can be set. Startup migration uses the same deterministic, prompt-free transforms as `openclaw doctor --fix` and writes only when the entire migrated config validates, including plugins. The previous config stays in the `.bak` ring. Configs using `$include`, Nix-managed configs, and configs written by a newer OpenClaw version are not automatically migrated. See [Legacy config key migrations](/gateway/doctor#detailed-behavior-and-rationale) for the conditions and fallback. When validation still fails: - The Gateway does not boot - Only diagnostic commands work (`openclaw doctor`, `openclaw logs`, `openclaw health`, `openclaw status`) - Run `openclaw doctor` to see exact issues - Run `openclaw doctor --fix` (`--repair` is the same flag; `--yes` skips prompts) to apply repairs The Gateway keeps a trusted last-known-good copy after each successful startup, but startup and hot reload do not restore it automatically - only `openclaw doctor --fix` does. If `openclaw.json` remains invalid after eligible startup migrations (including plugin-local validation), Gateway startup fails. An invalid hot reload is skipped and the current runtime keeps the last accepted config. A rejected write is also saved as `.rejected.` for inspection. The Gateway blocks writes that look like accidental clobbers - dropping the effective `gateway.mode` or shrinking the file by more than half - unless the write explicitly allows destructive changes. Mode checks resolve `$include` and environment references first. Missing `meta` is recorded as a write anomaly. Promotion to last-known-good is skipped when a candidate contains a redacted secret placeholder such as `***` or `[redacted]`. ## Common tasks Each channel has its own config section under `channels.`. See the dedicated channel page for setup steps: - [Discord](/channels/discord) - `channels.discord` - [Feishu](/channels/feishu) - `channels.feishu` - [Google Chat](/channels/googlechat) - `channels.googlechat` - [iMessage](/channels/imessage) - `channels.imessage` - [Mattermost](/channels/mattermost) - `channels.mattermost` - [Microsoft Teams](/channels/msteams) - `channels.msteams` - [Signal](/channels/signal) - `channels.signal` - [Slack](/channels/slack) - `channels.slack` - [Telegram](/channels/telegram) - `channels.telegram` - [WhatsApp](/channels/whatsapp) - `channels.whatsapp` All channels share the same DM policy pattern: ```json5 { channels: { telegram: { enabled: true, botToken: "123:abc", dmPolicy: "pairing", // pairing | allowlist | open | disabled allowFrom: ["tg:123"], // only for allowlist/open }, }, } ``` Set the primary model and optional fallbacks: ```json5 { agents: { defaults: { model: { primary: "anthropic/claude-sonnet-4-6", fallbacks: ["openai/gpt-5.4"], }, models: { "anthropic/claude-sonnet-4-6": { alias: "Sonnet" }, "openai/gpt-5.4": { alias: "GPT" }, }, }, }, } ``` - `agents.defaults.models` stores aliases and per-model settings; adding an entry never restricts `/model` or `--model` overrides. - `agents.defaults.modelPolicy.allow` is the explicit allowlist for overrides and model pickers. It accepts exact refs and `provider/*` wildcards; omit it or use `[]` to allow any model. - Model refs use `provider/model` format (e.g. `anthropic/claude-opus-4-6`). - `agents.defaults.imageMaxDimensionPx` controls transcript/tool image downscaling (default `1200`); lower values usually reduce vision-token usage on screenshot-heavy runs. - See [Models CLI](/concepts/models) for switching models in chat and [Model Failover](/concepts/model-failover) for auth rotation and fallback behavior. - For custom/self-hosted providers, see [Custom providers](/gateway/config-tools#custom-providers-and-base-urls) in the reference. DM access is controlled per channel via `dmPolicy` (default `"pairing"`): - `"pairing"`: unknown senders get a one-time pairing code to approve - `"allowlist"`: only senders in `allowFrom` (or the paired allow store) - `"open"`: allow all inbound DMs (requires `allowFrom: ["*"]`) - `"disabled"`: ignore all DMs For groups, use `groupPolicy` (`"allowlist" | "open" | "disabled"`) plus `groupAllowFrom` or channel-specific allowlists. See the [full reference](/gateway/config-channels#dm-and-group-access) for per-channel details. Group messages default to **require mention**. Configure trigger patterns per agent. Normal group/channel replies post automatically; opt into the message-tool path for shared rooms where the agent should decide when to speak: ```json5 { messages: { visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere groupChat: { visibleReplies: "message_tool", // opt-in; visible output requires message(action=send) unmentionedInbound: "room_event", // unmentioned always-on group chatter is quiet context }, }, agents: { entries: { main: { default: true, groupChat: { mentionPatterns: ["@openclaw", "openclaw"], }, }, }, }, channels: { whatsapp: { groups: { "*": { requireMention: true } }, }, }, } ``` - **Metadata mentions**: native @-mentions (WhatsApp tap-to-mention, Telegram @bot, etc.) - **Text patterns**: safe regex patterns in `mentionPatterns` - **Visible replies**: `messages.visibleReplies` can require message-tool sends globally; `messages.groupChat.visibleReplies` overrides that for groups/channels. - See [full reference](/gateway/config-channels#group-chat-mention-gating) for visible reply modes, per-channel overrides, and self-chat mode. Use `agents.defaults.skills` for a shared baseline, then override specific agents with `agents.entries.*.skills`: ```json5 { agents: { defaults: { skills: ["github", "weather"], }, entries: { writer: { default: true }, // inherits github, weather docs: { skills: ["docs-search"] }, // replaces defaults "locked-down": { skills: [] }, // no skills }, }, } ``` - Omit `agents.defaults.skills` for unrestricted skills by default. - Omit `agents.entries.*.skills` to inherit the defaults. - Set `agents.entries.*.skills: []` for no skills. - See [Skills](/tools/skills), [Skills config](/tools/skills-config), and the [Configuration Reference](/gateway/config-agents#agents-defaults-skills). Disable or enable automatic health restarts for a channel or account: ```json5 { channels: { telegram: { healthMonitor: { enabled: false }, accounts: { alerts: { healthMonitor: { enabled: true }, }, }, }, }, } ``` - Use `channels..healthMonitor.enabled` or `channels..accounts..healthMonitor.enabled` to control auto-restarts for one channel or account. - See [Health Checks](/gateway/health) for operational debugging and the [full reference](/gateway/configuration-reference#gateway) for all fields. Sessions control conversation continuity and isolation: ```json5 { session: { dmScope: "per-channel-peer", // recommended for multi-user threadBindings: { enabled: true, idleHours: 24, maxAgeHours: 0, }, reset: { mode: "daily", atHour: 4, idleMinutes: 120, }, }, } ``` - `dmScope`: `main` (shared) | `per-peer` | `per-channel-peer` | `per-account-channel-peer` - `threadBindings`: global defaults for thread-bound session routing. Spawn with `sessions_spawn({ thread: true })` or `/acp spawn --thread auto`. Use `/session unbind`, `/agents`, `/session idle`, and `/session max-age` to detach, list, and tune bindings (Discord binds threads, Telegram binds topics/conversations). - See [Session Management](/concepts/session) for scoping, identity links, and send policy. - See [full reference](/gateway/config-agents#session) for all fields. Run agent sessions in isolated sandbox runtimes: ```json5 { agents: { defaults: { sandbox: { mode: "non-main", // off | non-main | all scope: "agent", // session | agent | shared }, }, }, } ``` Build the image first - from a source checkout run `scripts/sandbox-setup.sh`, or from an npm install see the inline `docker build` command in [Sandboxing § Images and setup](/gateway/sandboxing#images-and-setup). See [Sandboxing](/gateway/sandboxing) for the full guide and [full reference](/gateway/config-agents#agentsdefaultssandbox) for all options. Relay-backed push for public App Store builds uses the hosted OpenClaw relay: `https://ios-push-relay.openclaw.ai`. Custom relay deployments require a deliberately separate iOS build/deployment path whose relay URL matches the gateway relay URL. If you are using a custom relay build, set this in gateway config: ```json5 { gateway: { push: { apns: { relay: { baseUrl: "https://relay.example.com", // Optional. Default: 10000 timeoutMs: 10000, }, }, }, }, } ``` CLI equivalent: ```bash openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com ``` What this does: - Lets the gateway send `push.test`, wake nudges, and reconnect wakes through the external relay. - Uses a registration-scoped send grant forwarded by the paired iOS app. The gateway does not need a deployment-wide relay token. - Binds each relay-backed registration to the gateway identity that the iOS app paired with, so another gateway cannot reuse the stored registration. - Keeps local/manual iOS builds on direct APNs. Relay-backed sends apply only to official distributed builds that registered through the relay. - Must match the relay base URL baked into the iOS build, so registration and send traffic reach the same relay deployment. End-to-end flow: 1. Install the official iOS app. 2. Optional: configure `gateway.push.apns.relay.baseUrl` on the gateway only when using a deliberately separate custom relay build. 3. Pair the iOS app to the gateway and let both node and operator sessions connect. 4. The iOS app fetches the gateway identity, registers with the relay using App Attest plus the app receipt, and then publishes the relay-backed `push.apns.register` payload to the paired gateway. 5. The gateway stores the relay handle and send grant, then uses them for `push.test`, wake nudges, and reconnect wakes. Operational notes: - If you switch the iOS app to a different gateway, reconnect the app so it can publish a new relay registration bound to that gateway. - If you ship a new iOS build that points at a different relay deployment, the app refreshes its cached relay registration instead of reusing the old relay origin. Compatibility note: - `OPENCLAW_APNS_RELAY_BASE_URL` and `OPENCLAW_APNS_RELAY_TIMEOUT_MS` still work as temporary env overrides. - Custom gateway relay URLs must match the relay base URL baked into the iOS build; the public App Store release lane rejects custom iOS relay URL overrides. - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` remains a loopback-only development escape hatch; do not persist HTTP relay URLs in config. See [iOS App](/platforms/ios#relay-backed-push-for-official-builds) for the end-to-end flow and [Authentication and trust flow](/platforms/ios#authentication-and-trust-flow) for the relay security model. ```json5 { agents: { defaults: { heartbeat: { every: "30m", target: "owner", }, }, }, } ``` - `every`: duration string (`30m`, `2h`). Set `0m` to disable recurring cadence; targeted event-driven wakes can still run one agent turn. Default: `30m`. - `target`: `owner` (default operator DM) | `last` (latest conversation, including groups) | `none` (internal only) | `` - `directPolicy`: `allow` (default) or `block` for DM-style heartbeat targets - See [Heartbeat](/gateway/heartbeat) for the full guide. ```json5 { cron: { enabled: true, sessionRetention: "24h", }, } ``` - `sessionRetention`: prune completed isolated run sessions from SQLite session rows (default `24h`; set `false` or a zero duration such as `"0h"` to disable). - Terminal run history is retained for 7 days (`lost` rows for 24 hours), with the newest 2000 rows per job and history class enforced as an additional ceiling. - See [Cron jobs](/automation/cron-jobs) for feature overview and CLI examples. Enable HTTP webhook endpoints on the Gateway: ```json5 { hooks: { enabled: true, token: "shared-secret", path: "/hooks", defaultSessionKey: "hook:ingress", allowRequestSessionKey: false, allowedSessionKeyPrefixes: ["hook:"], mappings: [ { match: { path: "gmail" }, action: "agent", agentId: "main", sessionKey: "hook:gmail", sessionMode: "persistent", deliver: true, }, ], }, } ``` Security note: - Treat all hook/webhook payload content as untrusted input. - Use a dedicated `hooks.token`; do not reuse active Gateway auth secrets (`gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` or `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`). - Hook auth is header-only (`Authorization: Bearer ...` or `x-openclaw-token`); query-string tokens are rejected. - `hooks.path` cannot be `/`; keep webhook ingress on a dedicated subpath such as `/hooks`. - Keep unsafe-content bypass flags disabled (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`) unless doing tightly scoped debugging. - If you enable `hooks.allowRequestSessionKey`, also set `hooks.allowedSessionKeyPrefixes` to bound caller-selected session keys. - Keep hook sessions isolated unless durable context is intentional. Direct persistent hooks require an explicit, prefix-bounded request `sessionKey`; mapped persistent hooks require a stable mapping key or `hooks.defaultSessionKey`. - For hook-driven agents, prefer strong modern model tiers and strict tool policy (for example messaging-only plus sandboxing where possible). See [full reference](/gateway/configuration-reference#hooks) for all mapping options and Gmail integration. Run multiple isolated agents with separate workspaces and sessions: ```json5 { agents: { entries: { home: { default: true, workspace: "~/.openclaw/workspace-home" }, work: { workspace: "~/.openclaw/workspace-work" }, }, }, bindings: [ { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } }, { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } }, ], } ``` See [Multi-Agent](/concepts/multi-agent) and [full reference](/gateway/config-agents#multi-agent-routing) for binding rules and per-agent access profiles. Use `$include` to organize large configs: ```json5 // ~/.openclaw/openclaw.json { gateway: { port: 18789 }, agents: { $include: "./agents.json5" }, broadcast: { $include: ["./clients/a.json5", "./clients/b.json5"], }, } ``` - **Single file**: replaces the containing object - **Array of files**: deep-merged in order (later wins), up to 10 nested levels deep - **Sibling keys**: merged after includes (override included values) - **Relative paths**: resolved relative to the including file - **Path format**: include paths must not contain null bytes and must be strictly shorter than 4096 characters before and after resolution - **OpenClaw-owned writes**: when a write changes only one top-level section backed by a single-file include such as `plugins: { $include: "./plugins.json5" }`, OpenClaw updates that included file and leaves `openclaw.json` intact - **Unsupported write-through**: root includes, include arrays, and includes with sibling overrides fail closed for OpenClaw-owned writes instead of flattening the config - **Confinement**: `$include` paths must resolve under the directory holding `openclaw.json`. To share a tree across machines or users, set `OPENCLAW_INCLUDE_ROOTS` to a path-list (`:` on POSIX, `;` on Windows) of additional directories that includes may reference. Symlinks are resolved and re-checked, so a path that lexically lives in a config dir but whose real target escapes every allowed root is still rejected. - **Error handling**: clear errors for missing files, parse errors, circular includes, invalid path format, and excessive length ## Config hot reload The Gateway watches `~/.openclaw/openclaw.json` and applies changes automatically - no manual restart needed for most settings. Direct file edits are treated as untrusted until they validate. The watcher waits for editor temp-write/rename churn to settle, reads the final file, and rejects invalid external edits without rewriting `openclaw.json`. OpenClaw-owned config writes use the same schema gate before writing (see [Strict validation](#strict-validation) for the clobber/rollback rules that apply to every write). If you see `config reload skipped (invalid config)` or startup reports `Invalid config`, inspect the config, run `openclaw config validate`, then run `openclaw doctor --fix` for repair. See [Gateway troubleshooting](/gateway/troubleshooting#gateway-rejected-invalid-config) for the checklist. A live change that selects a workspace with retired setup state is also rejected, with an `openclaw doctor --fix` hint. The Gateway keeps its last-good runtime. Gateway-managed writes, including `config.set`, reject the candidate before persistence; hand edits and writes from a separate CLI process can remain on disk even though the watcher refuses to activate them. Stop the Gateway and, if the write was rejected before persistence, save the intended workspace path while it is stopped. Then run [`openclaw doctor --fix`](/cli/doctor) and restart. Reload never migrates workspace state. ### Reload modes | Mode | Behavior | | ---------------------- | ----------------------------------------------------------------------- | | **`hybrid`** (default) | Applies hot-reloadable settings. Automatically restarts when required. | | **`off`** | Disables file watching. Changes take effect on the next manual restart. | ```json5 { gateway: { reload: { mode: "hybrid" }, }, } ``` The earlier `hot` and `restart` modes are retired; [`openclaw doctor --fix`](/cli/doctor) maps both to `hybrid`. Reload debounce is no longer configurable and runs behind a built-in default. ### What hot-applies vs what needs a restart Most fields hot-apply without downtime; some hot-applied sections restart just that subsystem (channel, cron, heartbeat) rather than the whole Gateway. In `hybrid` mode, Gateway-restart-required changes are handled automatically. By default, changing `agents.defaults.mediaMaxMb` restarts channel runtimes so their inherited attachment limits take effect together. Automatic reloads preserve manually stopped accounts; use an explicit channel start to resume those accounts. Model runtime selection keeps your authored settings separate from catalog defaults. Hot reload and secrets reload preserve that distinction: catalog compatibility metadata does not become a custom request override that switches a native runtime back to OpenClaw. | Category | Fields | Gateway restart needed? | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- | | Channels | `channels.*`, `web` (WhatsApp) - all built-in and plugin channels | No (restarts that channel) | | Agent & models | `agents`, `models`, `auth.order`, `auth.profiles`, `broadcast`, `worktreeRoot`, `cloudWorkers.projectProfiles` | No | | Automation | `hooks`, `cron`, `agents.defaults.heartbeat` | No (reloads the owning subsystem) | | Sessions & messages | `session`, `messages` | No | | Tools & media | `tools`, `skills`, `mcp` except Apps listener settings, `audio`, `talk`, `tts`, `memory.citations`, `attachments.ttlHours` | No | | Plugin config | `plugins.entries.*`, `plugins.allow`, `plugins.deny`, `plugins.enabled` | No (reloads plugin runtime) | | UI & misc | `ui`, `logging`, `identity`, `bindings`, `surfaces` | No | | Approval & install policy | `approvals.exec`, `approvals.plugin`, `security.installPolicy`, `security.audit.suppressions` | No (subsequent operations) | | Diagnostics & ACP | `diagnostics.flags`, `diagnostics.cacheTrace.enabled`, `acp.stream`, `acp.runtime.installCommand` | No (subsequent operations) | | Updates & telemetry | `update.checkOnStart`, `update.channel`, `update.auto.enabled`, `telemetry.enabled`, `telemetry.consentedAt` | No (next check) | | Hosted URLs | `gateway.publicOrigin`, `mcp.apps.sandboxOrigin` | No (new URLs and hosted apps) | | Gateway HTTP APIs | `gateway.http.endpoints`, `gateway.http.securityHeaders.strictTransportSecurity` | No (next request) | | Gateway tools & nodes | `gateway.tools`, `gateway.nodes.browser`, `gateway.nodes.pairing`, `gateway.nodes.commands`, `gateway.nodes.pluginTools.enabled`, `gateway.nodes.allowSkills` | No | | Gateway client features | `gateway.cliAgents`, selected `gateway.controlUi` settings below | No | | Gateway push | `gateway.push.apns.relay` | No (next push) | | Gateway terminal | `gateway.terminal` | No | | Gateway credentials | `gateway.auth.token`, `gateway.auth.password`, with the same effective auth mode | No (old shared-auth clients reconnect) | | Gateway auth limits | `gateway.auth.rateLimit` | No (retains limiter state) | | Discovery visibility | `discovery.mdns.mode` | No (replaces discovery advertisements) | | Browser defaults | `browser.profiles`, `browser.defaultProfile`, `browser.headless`, `browser.executablePath`, `browser.attachOnly`, `browser.cdpUrl`, `browser.noSandbox`, `browser.extraArgs`, `browser.snapshotDefaults`, `browser.tabCleanup`, `browser.allowSystemProfileImport` | No | | Gateway server | Other `gateway.*` settings (port, bind, auth mode, roles, tailscale, TLS) | **Yes** | | Infrastructure | Other `discovery` and `browser` settings, MCP Apps listener settings, `secrets.egressProxy`, `plugins.load`, `plugins.installs` | **Yes** | Changes to `channels.defaults`, `channels.modelByChannel`, `commands`, `accessGroups`, `tts`, `surfaces`, `acp.stream`, and `diagnostics.flags` refresh loaded channel runtimes that capture those policies. Manually stopped accounts stay stopped, and the Gateway keeps running. [Inbound debounce settings](/concepts/messages#inbound-debouncing) apply at the next inbound admission without reconnecting supported channels. `messages.ackReactionScope` applies to subsequent turns without reconnecting Discord, Matrix, Signal, Slack, Telegram, or WhatsApp. Other channel plugins refresh unless they declare that they read the policy live. Per-channel and per-account overrides still take precedence; admitted turns retain their policy. `diagnostics.enabled` updates diagnostic dispatch and heartbeat ownership live. With `diagnostics-otel` loaded, `diagnostics.otel` restarts only its exporter service, flushing the old generation before starting the new one. Externally preloaded OpenTelemetry providers retain their transport and shutdown ownership. Operation settings apply at their next use; they do not restart in-flight runs or recreate provisioned workers. Approval expiry changes affect newly issued grants. Attachment retention changes apply on the next cleanup sweep, including files already older than the new limit. Update and telemetry settings apply at the next scheduled check. A pending automatic-update countdown rechecks enablement and channel selection before starting; an update already applying keeps its admitted target. Changing these settings does not force an update. Telemetry consent is read again before the next update-check request. Internal-hook changes prepare a complete replacement before publishing it. A load failure keeps the previous handlers; events already running finish with their original handlers. Workspace changes reload directory hooks from the newly selected workspace. Reload does not replay `gateway:startup`. Under `gateway.controlUi`, the `enabled`, `environment`, `github`, `sessionObserver`, `embedSandbox`, `allowExternalEmbedUrls`, and `automaticallyFetchFavicons` settings hot-apply. Reload open Control UI pages to pick up the environment label, CLI agent picker, embed preferences, and favicon display preference; the Gateway process keeps running. `allowedOrigins` and `dangerouslyAllowHostHeaderOriginFallback` also hot-apply: pending handshakes recheck the new policy, and browser connections it no longer allows close. Disabling the Control UI stops serving dashboard pages and assets and cancels pending asset preparation. Existing Gateway connections and agent runs continue. Re-enabling prepares missing dashboard assets in the background; requests return `503` until they are ready. Control UI serving paths still require a Gateway restart. Node command policy updates connected nodes immediately. Disabling node-published tools or skills withdraws them; re-enabling restores the last publication within the node's existing pairing approval. Reload never grants an unapproved command. Revoking a command cancels its active invocations and rejects later input and results. Revoking desktop streaming also closes its observer transports. Browser node routing applies to subsequent operations. Node pairing policy (`gateway.nodes.pairing`) also hot-applies: pending automatic approvals recheck the current policy before granting access, including after SSH probes. Existing paired devices remain paired. Terminal shell changes apply to newly opened terminals; active terminals keep their original shell. Detached-session timeout changes recalculate deadlines from each terminal's original disconnect time. Already-expired sessions close immediately; attached terminals keep running. Terminal enablement also hot-applies. Disabling terminals closes attached, detached, and conversation-owned sessions and cancels pending opens. Re-enabling allows fresh sessions; closed sessions do not return. Reload open Control UI pages to pick up the terminal's content security policy. An unrelated deferred restart does not delay a committed terminal enable or shell change. A pending restart can still keep earlier terminal or sandbox restrictions in force until that restart completes or its rejected changes are reverted. Browser default-profile changes apply on the next request. Launch-setting changes replace affected managed browser processes when next used; externally attached browsers stay running. Browser enablement, evaluation, SSRF policy, and extension relay remain restart-owned. Snapshot defaults apply to the next snapshot, and tab-cleanup settings apply on the next sweep. Authentication rate-limit changes retain recorded failures, earned lockout deadlines, and pending loopback delays. New limits and loopback exemptions apply to subsequent attempts; tightening the attempt limit can lock a client based on its retained failures. Removing `gateway.auth.rateLimit` restores the defaults. Browser-origin and node-reapproval budgets remain nonexempt. Discovery mode changes replace the current advertisements without interrupting Gateway connections. Switching from `full` to `minimal` removes extra TXT hints from LAN advertisements and any configured wide-area DNS-SD zone. `off` stops LAN advertisements while configured wide-area discovery remains enabled. The Bonjour plugin must already be enabled, and environment overrides still apply. Token and password rotation hot-applies only when the effective auth mode stays the same. Existing clients using the old shared credential must reconnect with the new credential; independently paired device-token clients remain connected. Browser device tokens derived from the old shared credential are revoked too. For SecretRef credentials, set `gateway.auth.mode` explicitly to make rotation eligible for hot reload. Auth-mode changes still restart the Gateway. Changing `gateway.reload` or `gateway.remote` also does **not** trigger a restart. Individual plugins can declare their own restart-triggering config prefixes. Canvas enablement uses plugin hot reload. Current-protocol nodes whose hosted capabilities change reconnect to receive fresh capability URLs; other current-protocol nodes and operator connections stay open. Legacy nodes reconnect when hosted surface descriptors change so their protocol limits are recalculated. Pending node handshakes also recheck those capabilities before admission. Plugin hot reload uses the package metadata discovered at Gateway startup. Enablement, plugin config, and account changes do not rescan plugin files. Install, update, uninstall, and explicit plugin metadata refresh require a Gateway restart; `hybrid` schedules that restart, while `off` leaves it to you. Changing an agent's workspace also does not discover plugins in the new directory until restart. See [Plugin metadata snapshots](/plugins/architecture#plugin-metadata-snapshot-and-lookup-table). During channel or plugin hot reload, Gateway-hosted channel webhook routes return `503` with `Retry-After: 1` until replacement ingress registers. Senders must honor retry responses; this does not acknowledge delivery. Disabled or removed accounts, manual stops, and cancelled replacement lifetimes release those temporary routes. When replacement ingress reports ready, old paths it did not reclaim are removed. ### Reload planning When you edit a source file that is referenced through `$include`, OpenClaw plans the reload from the source-authored layout, not the flattened in-memory view. That keeps hot-reload decisions (hot-apply vs restart) predictable even when a single top-level section lives in its own included file such as `plugins: { $include: "./plugins.json5" }`. Reload planning fails closed if the source layout is ambiguous. ## Config RPC (programmatic updates) For tooling that writes config over the gateway API, prefer this flow: - `config.schema.lookup` to inspect one subtree (shallow schema node + child summaries) - `config.get` to fetch the current snapshot plus `hash` - `config.patch` for partial updates (JSON merge patch: objects merge, `null` deletes, arrays replace when explicitly confirmed with `replacePaths` if entries would be removed) - `config.apply` only when you intend to replace the entire config - `update.run` for explicit self-update plus restart; include `continuationMessage` when the post-restart session should run one follow-up turn - `update.status` to inspect the latest update restart sentinel and verify the running version after a restart Agents should treat `config.schema.lookup` as the first stop for exact field-level docs and constraints. Use [Configuration reference](/gateway/configuration-reference) when they need the broader config map, defaults, or links to dedicated subsystem references. Control-plane writes (`config.apply`, `config.patch`, `update.run`) are rate-limited to 30 requests per 60 seconds, per method, per `deviceId+clientIp`; see [Rate limiting](/gateway/security/rate-limiting). Restart requests coalesce and then enforce a 30-second cooldown between restart cycles. `update.status` is read-only but admin-scoped because the restart sentinel can include update step summaries and command output tails. Example partial patch: ```bash openclaw gateway call config.get --params '{}' # capture payload.hash openclaw gateway call config.patch --params '{ "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }", "baseHash": "" }' ``` Both `config.apply` and `config.patch` accept `raw`, `baseHash`, `sessionKey`, `note`, and `restartDelayMs`. `baseHash` is required for both methods once a config file already exists (a first write with no existing config skips the check). For hot-applied changes, these RPCs wait until the active Gateway applies the exact write. Channel or plugin reloads may defer for unrelated active work. If the file watcher takes over the same unapplied write during that wait, the RPC stays pending through replay; persistence alone is not an application acknowledgment. Shutdown, supersession by different content, or failed application returns `UNAVAILABLE` with recovery guidance. `config.set` acknowledges persistence only. Once a reload has committed, it finishes its model and channel work before a newer config is applied. If that work needs restart recovery, the RPC returns `UNAVAILABLE`; wait for the Gateway to restart, then use `config.get` to verify the active revision. `config.patch` also accepts `replacePaths`, an array of config paths whose array replacement or deletion is intentional. If a patch removes existing array entries or deletes an array, the Gateway rejects the write unless that exact array path appears in `replacePaths`. Deleting a containing object requires its contained array paths, including empty arrays. Deleting a whole array requires only its own path, not paths to arrays nested inside its entries. Use exact record keys, such as `agents.entries.main.skills`. For ID-merged entry updates, nested array paths use `[]`, such as `models.providers.custom.models[].input`. Parent paths and `*` wildcards do not authorize descendant arrays. This prevents truncated `config.get` snapshots from silently clobbering routing or allowlist arrays. Use `config.apply` when you intend to replace the full config. Arrays of objects with stable `id` fields merge by ID unless their path appears in `replacePaths`. These updates preserve authored fields in untouched entries; runtime defaults, such as model catalog compatibility and context budgets, are not saved into sibling entries. Explicitly configured values remain authoritative. ## Environment variables OpenClaw reads env vars from the parent process plus: - `.env` from the current working directory (if present) - `~/.openclaw/.env` (global fallback) Neither file overrides existing env vars. You can also set inline env vars in config: ```json5 { env: { vars: { OPENROUTER_API_KEY: "sk-or-...", GROQ_API_KEY: "gsk-...", }, }, } ``` If enabled and expected keys aren't set, OpenClaw runs your login shell and imports only the missing keys: ```json5 { env: { shellEnv: { enabled: true, timeoutMs: 15000 }, }, } ``` Env var equivalent: `OPENCLAW_LOAD_SHELL_ENV=1`. Default `timeoutMs`: `15000`. Reference env vars in any config string value with `${VAR_NAME}`: ```json5 { gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } }, models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } }, } ``` Rules: - Only uppercase names matched: `[A-Z_][A-Z0-9_]*` - Missing/empty vars stay visibly unresolved, emit a warning, and are unavailable to consumers that require the value - Escape with `$${VAR}` to produce a literal `${VAR}` value - Works inside `$include` files - Inline substitution: `"${BASE}/v1"` → `"https://api.example.com/v1"` For fields that support SecretRef objects, you can use: ```json5 { models: { providers: { openai: { apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" } }, }, }, skills: { entries: { "image-lab": { apiKey: { source: "file", provider: "filemain", id: "/skills/entries/image-lab/apiKey", }, }, }, }, channels: { googlechat: { serviceAccount: { source: "exec", provider: "vault", id: "channels/googlechat/serviceAccount", }, }, }, } ``` The `env` ref above uses the built-in `default` provider and needs no `secrets.providers.default` entry unless `secrets.defaults.env` selects another alias. The same rule applies to `store` refs and `secrets.defaults.store`. See [Secrets Management](/gateway/secrets#secretref-contract) for provider precedence and the required `file`/`exec` provider configuration. Supported credential paths are listed in [SecretRef Credential Surface](/reference/secretref-credential-surface). See [Environment](/help/environment) for full precedence and sources. ## Full reference For the complete field-by-field reference, see **[Configuration Reference](/gateway/configuration-reference)**. --- _Related: [Configuration Examples](/gateway/configuration-examples) · [Configuration Reference](/gateway/configuration-reference) · [Doctor](/gateway/doctor)_ ## Related - [Configuration reference](/gateway/configuration-reference) - [Configuration examples](/gateway/configuration-examples) - [Gateway runbook](/gateway)