Summary

Describe the problem and fix in 2–5 bullets:

• Problem: config.schema.lookup exposed field schema and UI hints, but not whether changing the field can hot-reload or requires a Gateway restart.
• Why it matters: users and tools could not tell from schema lookup whether config changes like gateway.handshakeTimeoutMs are hot-reloadable or restart-required.
• What changed: lookup results and immediate child summaries now include optional reloadKind metadata (restart, hot, or none) resolved through the existing config reload rule matcher.
• What did NOT change (scope boundary): this does not alter config patch behavior, reload planning semantics, the full generated JSON schema, or add a second reload rule table.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes Schema doesn't expose hot-reload vs restart-required behavior for config fields #81409
• Related #
• This PR fixes a bug or regression

Real behavior proof (required for external PRs)

• Behavior or issue addressed: config.schema.lookup now reports the reload behavior for a looked-up config path and its immediate children.
• Real environment tested: local OpenClaw checkout, isolated dev Gateway using HOME=/tmp/oc81409-pr-home, port 19809, built from this branch.
• Exact steps or command run after this patch:

pnpm build:strict-smoke
HOME=/tmp/oc81409-pr-home node openclaw.mjs gateway run --dev --auth none --port 19809 --tailscale off --allow-unconfigured
TOKEN=$(node -e "console.log(require('/tmp/oc81409-pr-home/.openclaw/openclaw.json').gateway.auth.token)")
HOME=/tmp/oc81409-pr-home node openclaw.mjs gateway call --url ws://127.0.0.1:19809 --token "$TOKEN" --json --params '{"path":"gateway.handshakeTimeoutMs"}' config.schema.lookup
HOME=/tmp/oc81409-pr-home node openclaw.mjs gateway call --url ws://127.0.0.1:19809 --token "$TOKEN" --json --params '{"path":"gateway"}' config.schema.lookup

• Evidence after fix (screenshot, recording, terminal capture, console output, redacted runtime log, linked artifact, or copied live output):

{
  "path": "gateway.handshakeTimeoutMs",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 9007199254740991,
    "title": "Gateway Handshake Timeout",
    "description": "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."
  },
  "reloadKind": "restart",
  "hint": {
    "label": "Gateway Handshake Timeout",
    "help": "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.",
    "tags": ["network", "performance"]
  },
  "hintPath": "gateway.handshakeTimeoutMs",
  "children": []
}

{
  "path": "gateway",
  "reloadKind": "restart",
  "children": [
    {
      "path": "gateway.handshakeTimeoutMs",
      "reloadKind": "restart"
    },
    {
      "path": "gateway.channelHealthCheckMinutes",
      "reloadKind": "hot"
    }
  ]
}

• Observed result after fix: restart-required and hot-reloadable fields are distinguishable through config.schema.lookup.
• What was not tested: plugin-provided reload metadata beyond existing config-reload unit coverage.
• Before evidence (optional but encouraged): issue Schema doesn't expose hot-reload vs restart-required behavior for config fields #81409 documents that the same lookup output did not expose hot-reload vs restart-required behavior.

Root Cause (if applicable)

• Root cause: schema lookup and config reload planning were implemented as separate paths. lookupConfigSchema() returned schema/UI hint metadata only, while restart/hot/no-op decisions lived in config-reload-plan.ts.
• Missing detection / guardrail: no lookup-level test asserted that reload planning metadata was surfaced to schema consumers.
• Contributing context (if known): config patch planning already had this information, but schema lookup had no resolver hook to reuse it.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/config/schema.test.ts
• Scenario the test should lock in: when a reload metadata resolver is provided, lookupConfigSchema() includes reloadKind on the looked-up path and child summaries.
• Why this is the smallest reliable guardrail: it validates the schema lookup behavior without requiring a live Gateway or duplicating reload plan tests.
• Existing test that already covers this (if any): src/gateway/config-reload.test.ts covers the reload rule semantics themselves.
• If no new test is added, why not: N/A; a test was added.

User-visible / Behavior Changes

config.schema.lookup responses now include optional reloadKind metadata for the requested path and immediate children.

Diagram (if applicable)

Before:
config.schema.lookup -> schema + UI hints

After:
config.schema.lookup -> schema + UI hints + reloadKind from existing reload rules

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: Linux 6.8.0-111-generic x64
• Runtime/container: local Node.js v24.13.0, isolated dev Gateway with HOME=/tmp/oc81409-pr-home
• Model/provider: N/A
• Integration/channel (if any): Gateway RPC / CLI
• Relevant config (redacted): dev config generated under /tmp/oc81409-pr-home/.openclaw/openclaw.json; Gateway token used locally only and not included here.

Steps

1. Build the local checkout with pnpm build:strict-smoke.
2. Start a dev Gateway from this branch with isolated HOME and port 19809.
3. Call config.schema.lookup for gateway.handshakeTimeoutMs.
4. Call config.schema.lookup for gateway and inspect child summaries.

Expected

• gateway.handshakeTimeoutMs reports reloadKind: "restart".
• gateway.channelHealthCheckMinutes appears in child summaries with reloadKind: "hot".

Actual

• Matches expected output shown in the Real behavior proof section.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Targeted checks run locally:

node scripts/run-vitest.mjs run --config test/vitest/vitest.runtime-config.config.ts src/config/schema.test.ts
# 34 passed

node scripts/run-vitest.mjs run --config test/vitest/vitest.gateway.config.ts src/gateway/config-reload.test.ts
# 73 passed

pnpm tsgo:test
# passed

pnpm build:strict-smoke
# passed

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios:
  • gateway.handshakeTimeoutMs lookup now returns reloadKind: "restart".
  • gateway lookup child summaries include both restart-required and hot-reloadable children.
  • Existing reload rule tests still pass.
• Edge cases checked:
  • Resolver is optional, so existing direct schema lookup callers can continue without reload metadata.
  • Metadata is attached only to lookup result/children, avoiding a broader full-schema contract change.
• What you did not verify:
  • Plugin-provided reload rule metadata through a third-party plugin runtime.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: schema lookup consumers may ignore the new optional field.
  • Mitigation: field is additive and optional.
• Risk: reload metadata could diverge if a second rule source were introduced.
  • Mitigation: this PR reuses the existing reload rule matcher instead of duplicating rules.

AI-assisted disclosure

This PR was prepared with AI assistance. I reviewed the change, understand the code path, and ran the local verification listed above.