From 9878bfc8e505f9bbc87905b67488248e51546eaf Mon Sep 17 00:00:00 2001
From: Koduri Mahesh Bhushan Chowdary
<128616744+MaheshBhushan@users.noreply.github.com>
Date: Sat, 1 Aug 2026 00:35:16 +0200
Subject: [PATCH] docs: drop retired gateway.reload keys and modes from config
docs (#116975)
The gateway.reload documentation advertised four settings the shipped
build rejects. gateway.reload is a strictObject accepting only `mode`,
and `mode` is a union of "off" | "hybrid", so a config written from the
docs fails validation and the gateway fails closed on the unknown keys.
Retired but still documented:
- `debounceMs` and `deferralTimeoutMs` (RETIRED_TUNING_PATHS; stripped by
`openclaw doctor --fix` via stripRetiredTuningKnobs)
- `mode: "restart"` and `mode: "hot"` (mapped to "hybrid" by
`openclaw doctor --fix`)
Correct all four docs pages that still describe them, and say what
replaced them: debounce and active-work deferral now run behind built-in
defaults rather than config keys.
Refs #116973
---
docs/gateway/configuration-reference.md | 14 ++++++--------
docs/gateway/configuration.md | 14 +++++++-------
docs/gateway/index.md | 4 ++--
docs/help/faq.md | 2 +-
4 files changed, 16 insertions(+), 18 deletions(-)
diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md
index 6692586dc8b0..dd8615a05148 100644
--- a/docs/gateway/configuration-reference.md
+++ b/docs/gateway/configuration-reference.md
@@ -761,9 +761,7 @@ See [Multiple Gateways](/gateway/multiple-gateways).
{
gateway: {
reload: {
- mode: "hybrid", // off | restart | hot | hybrid
- debounceMs: 500,
- deferralTimeoutMs: 300000,
+ mode: "hybrid", // off | hybrid
},
},
}
@@ -771,11 +769,11 @@ See [Multiple Gateways](/gateway/multiple-gateways).
- `mode`: controls how config edits are applied at runtime.
- `"off"`: ignore live edits; changes require an explicit restart.
- - `"restart"`: always restart the gateway process on config change.
- - `"hot"`: apply changes in-process without restarting.
- - `"hybrid"` (default): try hot reload first; fall back to restart if required.
-- `debounceMs`: debounce window in ms before config changes are applied (non-negative integer; default: `300`).
-- `deferralTimeoutMs`: optional maximum time in ms to wait for in-flight operations before forcing a restart or channel hot reload. Omit it to use the default bounded wait (`300000`); set `0` to wait indefinitely and log periodic still-pending warnings.
+ - `"hybrid"` (default): apply hot-safe changes in-process, then restart when a change requires it.
+
+The earlier `"restart"` and `"hot"` values are retired; [`openclaw doctor --fix`](/cli/doctor) maps both to `"hybrid"`.
+
+Reload debounce and in-flight operation deferral are no longer configurable and run behind built-in defaults. [`openclaw doctor --fix`](/cli/doctor) removes the retired `debounceMs` and `deferralTimeoutMs` keys from older config files.
---
diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md
index ebe3e03f301d..d594a712d7f2 100644
--- a/docs/gateway/configuration.md
+++ b/docs/gateway/configuration.md
@@ -535,21 +535,21 @@ for the checklist.
### Reload modes
-| Mode | Behavior |
-| ---------------------- | --------------------------------------------------------------------------------------- |
-| **`hybrid`** (default) | Hot-applies safe changes instantly. Automatically restarts for critical ones. |
-| **`hot`** | Hot-applies safe changes only. Logs a warning when a restart is needed - you handle it. |
-| **`restart`** | Restarts the Gateway on any config change, safe or not. |
-| **`off`** | Disables file watching. Changes take effect on the next manual restart. |
+| Mode | Behavior |
+| ---------------------- | ----------------------------------------------------------------------------- |
+| **`hybrid`** (default) | Hot-applies safe changes instantly. Automatically restarts for critical ones. |
+| **`off`** | Disables file watching. Changes take effect on the next manual restart. |
```json5
{
gateway: {
- reload: { mode: "hybrid", debounceMs: 300 },
+ 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
diff --git a/docs/gateway/index.md b/docs/gateway/index.md
index 7ba812a95382..2662c999d614 100644
--- a/docs/gateway/index.md
+++ b/docs/gateway/index.md
@@ -113,10 +113,10 @@ Gateway startup uses the same effective port and bind when it seeds local Contro
| `gateway.reload.mode` | Behavior |
| --------------------- | ------------------------------------------ |
| `off` | No config reload |
-| `hot` | Apply only hot-safe changes |
-| `restart` | Restart on reload-required changes |
| `hybrid` (default) | Hot-apply when safe, restart when required |
+The earlier `hot` and `restart` modes are retired; [`openclaw doctor --fix`](/cli/doctor) maps both to `hybrid`.
+
## Operator command set
```bash
diff --git a/docs/help/faq.md b/docs/help/faq.md
index a0561dec8a6e..e1dbec379309 100644
--- a/docs/help/faq.md
+++ b/docs/help/faq.md
@@ -592,7 +592,7 @@ First-run Q&A - install, onboard, auth routes, subscriptions, initial failures -
- The Gateway watches the config and supports hot-reload: `gateway.reload.mode: "hybrid"` (default) hot-applies safe changes and restarts for critical ones. `hot`, `restart`, and `off` are also supported. Most `tools.*`, `agents.*` policy, `session.*`, and `messages.*` changes apply immediately with no reload action at all; `gateway.*` binding/port changes require a restart.
+ The Gateway watches the config and supports hot-reload: `gateway.reload.mode: "hybrid"` (default) hot-applies safe changes and restarts for critical ones. `off` disables config reload; the earlier `hot` and `restart` modes are retired. Most `tools.*`, `agents.*` policy, `session.*`, and `messages.*` changes apply immediately with no reload action at all; `gateway.*` binding/port changes require a restart.