OpenClaw configuration: which settings apply without a restart?
OpenClaw configuration now applies many changes while the Gateway is running, but that does not make every edit safe to treat as live. The practical rule is simple: make the smallest supported change, confirm whether that setting hot-applies, then observe the owning service before you move on. In v2026.9.2, more agent, model, tool, channel, browser, node, access, and terminal settings apply through their running owners; the configuration reference still marks the settings that need a Gateway restart.
This matters for a self-hosted agent because configuration controls real behavior: who can message it, which models it may use, which tools have access, and how work reaches channels. A faster edit loop is useful only when it also preserves a clear recovery path.
Contents
- What OpenClaw configuration hot reload means
- Use a safe configuration workflow
- Changes that deserve extra care
- How to verify a live configuration change
- FAQ
What OpenClaw configuration hot reload means
OpenClaw reads its optional JSON5 configuration from ~/.openclaw/openclaw.json by default. You can change it through the Control UI, openclaw configure, or focused CLI commands such as openclaw config set. The Gateway watches the file and applies supported changes automatically.
Hot reload means the running owner of a setting can adopt a valid new value without a full Gateway stop and start. It does not mean every subsystem can safely rebuild in place, nor does it promise that an already-running agent turn will change behavior halfway through. Treat active work as its own unit of state.
| Question | Safe interpretation |
|---|---|
| Does the config file change? | Use a supported writer when possible so the full post-change config is validated before it is committed. |
| Does the Gateway accept it? | A valid hot reload keeps the current runtime on the last accepted configuration if the new candidate is rejected. |
| Does every setting apply live? | No. Check the configuration reference for the individual field’s restart behavior. |
| Does an active agent turn change immediately? | Do not assume so. Verify new behavior with a small, disposable test after the change is accepted. |
The distinction is worth keeping. A config edit can be valid on disk yet require a restart before a particular owner reconstructs itself. Conversely, a hot-applied channel or model setting can take effect for the next relevant action without interrupting unrelated conversations.
For the broader architecture, see how OpenClaw works. The Gateway is the runtime that owns configuration, sessions, channels, and tool execution, so configuration safety belongs at that boundary rather than in a random chat prompt.
Use a safe OpenClaw configuration workflow
A short, repeatable sequence is better than hand-editing a large file and hoping a restart fixes the result.
- Identify the exact field and its owner. Start with the configuration reference or
config.schema.lookuprather than guessing a JSON path. The docs separate infrastructure and cross-agent defaults at the root from agent-loop behavior underagents.defaults; per-agent entries can override supported fields. - Choose a supported write path. For narrow changes, use
openclaw config set <path> <value>. For several related choices, useopenclaw configureor the Control UI. Direct editing can be appropriate for reviewed configuration, but it skips the guardrails of a purpose-built writer. - Validate before you broaden scope. OpenClaw-owned writers validate the full resulting configuration before committing it. If a hot reload is invalid, the running Gateway keeps its last accepted configuration instead of adopting a partial candidate.
- Check whether the setting hot-applies. The v2026.9.2 release expanded live application across several owner types, but the documentation is the source of truth for a specific field. Plan a Gateway restart when the reference says one is required.
- Test one observable behavior. After changing a channel policy, test a non-privileged message path. After changing model selection, start a small new chat. After changing tool access, run a harmless tool call. Do not use a production automation as the first test.
- Record the change and recovery step. In a shared installation, leave a short note with the field, previous value, expected effect, and whether a restart was performed. That saves time when a later issue turns out to be configuration drift.
This sequence is intentionally conservative. The goal is not to avoid live changes; it is to make them reversible and easy to diagnose.
Changes that deserve extra care
Some settings carry a larger blast radius than others. Before changing these, decide how you will verify them and how you will roll them back.
Access, session visibility, and shared Gateways
v2026.9.2 changed the default session-tool visibility to all sessions and enabled ordinary agent-to-agent access. If agents on a shared Gateway should not read or search one another’s conversations, set tools.sessions.visibility to agent or self and review the surrounding session-tool policy. The release notes are explicit that mutually untrusted users need separate Gateways.
That is an ownership decision, not a tuning tweak. Read what OpenClaw is and the OpenClaw 2.0 migration guide before treating a multi-user Gateway as a casual shared workspace.
Model and provider changes
Changing a primary model, fallback list, account, or provider capability can affect cost, tool calling, and the behavior of new sessions. v2026.9.2 adds GPT-6 Astra for eligible OpenAI API-key profiles and supported ChatGPT/Codex accounts, including text and image input. Availability still depends on successful account discovery and the account’s access.
Make a small new-session test after a model change. Do not infer that an existing session has switched simply because the global default changed.
Channels, browser access, nodes, and terminal settings
These settings can alter delivery paths or expand what the agent can reach. Prefer a narrow test account, a loopback browser target, or a non-production node when you are changing a policy. If a field needs a restart, schedule it rather than repeatedly editing the same config while the system is in an uncertain state.
For the mechanics of safe writes and rejected candidates, see OpenClaw configuration write reliability.
How to verify a live configuration change
Use evidence from the runtime, not only the file timestamp.
| Change type | Small verification | Escalate when |
|---|---|---|
| Agent or model default | Start a new low-risk chat and inspect the selected model or behavior | New sessions ignore the documented default |
| Channel access policy | Send a controlled message from an allowed and a disallowed identity | Delivery, pairing, or authorization is ambiguous |
| Tool or terminal policy | Run a harmless read-only action | The scope is broader than intended or the tool is unavailable |
| Browser or node setting | Connect only to an approved local target | The setting changes remote reachability or approval requirements |
| Restart-required field | Restart in a maintenance window and check Gateway health | The service does not return cleanly or reports migration errors |
If a configuration change fails validation, avoid the instinct to make a larger edit. Run openclaw doctor to see the specific problem. The configuration guide notes that openclaw doctor --fix can apply eligible repairs, while an invalid startup configuration leaves diagnostic commands available. Keep a known-good copy and change one variable at a time.
Recent community discussion shows why this discipline pays off. A late-August r/openclaw update thread described an installation becoming difficult to use after an update and a failed doctor --fix attempt. That anecdote does not prove a product-wide fault, but it is a familiar operations lesson: updates and configuration are easier to recover when the prior state, intended change, and validation evidence are visible.
A useful operating stance
Live configuration is a speed feature, not a license to treat the Gateway as disposable. Use supported writers, verify the specific field’s reload behavior, test the smallest affected workflow, and keep access controls especially deliberate on a shared Gateway.
OpenClaw v2026.9.2 makes more of that workflow possible without disconnecting unaffected conversations. The operator still owns the boundary: a clear change record and a small verification step beat a large, unreviewed config rewrite every time.
FAQ
Does every OpenClaw configuration change apply without a restart?
No. The Gateway watches the config file and automatically applies supported changes, but some fields still require a Gateway restart. Check the field’s entry in the configuration reference before assuming an edit is live.
Is direct editing of openclaw.json safe?
It can be, provided you understand the JSON5 structure and validate the result. OpenClaw-owned writers such as openclaw config set validate the full post-change configuration before committing it, which makes them the safer default for focused edits.
What happens when a hot reload is invalid?
OpenClaw skips the invalid hot reload and keeps the current runtime on the last accepted configuration. Inspect the validation error, correct the narrowest cause, and retry instead of restarting blindly.
Should teams share one OpenClaw Gateway?
Only when the session and access boundaries match the trust model. In v2026.9.2, omitted session-tool settings can permit broad session visibility. Set narrower visibility where appropriate, and use separate Gateways for mutually untrusted users.