Summary

The runtime config schema (runtime-schema-OL6hE5dN.js) does not expose whether changing a given config path triggers a hot reload, requires a gateway restart, or is a no-op. This information exists internally (config-reload-plan-CT3ozyNA.js's BASE_RELOAD_RULES + matchRule()), but is not surfaced via openclaw config schema, gateway.config.schema.lookup, or any requiresRestart/reloadKind field hint.

As a result, agents and humans must change a config field, watch the gateway log, and observe [reload] config change requires gateway restart (...) to learn the field's reload policy — which is essentially trial-and-error.

Repro

1. Change any field that the schema describes neutrally (e.g. gateway.handshakeTimeoutMs):

   echo '{"gateway":{"handshakeTimeoutMs":30000}}' | openclaw config patch --stdin

2. The CLI prints "Restart the gateway to apply." and the log shows:

   [reload] config change requires gateway restart (gateway.handshakeTimeoutMs) — deferring until ...
   

3. Inspect the schema for the same field via gateway.config.schema.lookup action or openclaw config schema:

   {
     "label": "Gateway Handshake Timeout",
     "help": "Pre-auth Gateway WebSocket handshake timeout in milliseconds...",
     "tags": ["network", "performance"]
   }

   No indication that this field requires a restart.

Examples of fields hit during 5-13 troubleshooting (one operator, one day)

We see this pattern at least 5 times per LRN-066 in our internal log (memory-config-default-restart recurrence).

Root cause (from dist source reading)

config-reload-plan-CT3ozyNA.js line ~344:

for (const path of changedPaths) {
  const rule = matchRule(path);
  if (!rule) {
    plan.restartGateway = true;       // default: any unmatched path triggers restart
    plan.restartReasons.push(path);
    continue;
  }
  if (rule.kind === "restart") { /* explicit restart */ }
  else if (rule.kind === "none") { /* no-op */ }
  else { /* hot reload via actions */ }
}

So the reload policy is essentially:

• Explicit rule (restart / hot / none / restart-channel:X) for paths matched by BASE_RELOAD_RULES + plugin-contributed prefixes
• Default = restart for everything else

This information would be valuable to surface in schema metadata.

Proposed solutions (pick one or combine)

1. Add reloadKind to schema field hints (most aligned with current schema structure):

{
  "label": "Gateway Handshake Timeout",
  "help": "...",
  "tags": ["network", "performance"],
  "reloadKind": "restart"  // or "hot" / "none"
}

2. Expose the reload-rules table separately via a new CLI/RPC, e.g. openclaw config reload-rules that prints the matched policy for each known prefix.

3. Document the "default = restart" rule in docs/gateway/configuration.md so users know unmatched fields require restart by convention.

Why this matters

For automated agents (the primary consumer of the schema), the absence of this metadata means we have to:

• Encode field-by-field restart knowledge in our own runbooks (LRN-066-style learning entries)
• Trigger a deferred restart for every config patch, then observe logs
• Keep "default to restart" as a hard-coded fallback policy

Surfacing reload behavior would let agents reason about restart impact before applying the patch, schedule restarts more thoughtfully, and reduce log-grep noise.

Environment

• OpenClaw version: 2026.5.7 (eeef486)
• Node: v24.14.1
• Platform: Darwin 25.3.0 (arm64)