GitHub Issue Draft

Repository: openclaw/openclaw
Created: 2026-03-12
Status: Ready to submit

Title

Heartbeat config written to invalid gateway.heartbeat location instead of agents.defaults.heartbeat

Labels

bug, config, regression

Summary

When configuring heartbeat settings, OpenClaw writes the configuration to gateway.heartbeat which is not a valid schema key. This causes the gateway to abort on startup with a schema validation error. Running openclaw doctor --fix removes the invalid key, but the issue recurs when heartbeat settings are modified again.

Steps to Reproduce

1. Start OpenClaw gateway
2. Modify heartbeat configuration (e.g., change lightContext, model, or activeHours)
3. Restart the gateway
4. Gateway fails to start with error:

   Config invalid
   gateway: Unrecognized key: "heartbeat"
   Gateway aborted: config is invalid.
   

Expected Behavior

Heartbeat configuration should be written to agents.defaults.heartbeat which is the valid location in the schema.

Actual Behavior

Heartbeat configuration is incorrectly written to gateway.heartbeat, causing schema validation failure and gateway abort.

Evidence

Backup file (.bak.2) shows invalid location:

{
  "gateway": {
    "auth": { ... },
    "bind": "loopback",
    "heartbeat": {
      "lightContext": true,
      "model": "google/gemini-3.1-flash-lite-preview",
      "activeHours": {
        "start": "08:00",
        "end": "23:00"
      }
    },
    "mode": "local",
    ...
  }
}

After doctor --fix, the key is removed but not migrated:

{
  "gateway": {
    // heartbeat removed (correct - schema doesn't allow it)
  },
  "agents": {
    "defaults": {
      "heartbeat": null
    }
  }
}

Log excerpts showing the failure:

2026-03-12T01:25:58.378-04:00 config reload skipped (invalid config): gateway: Unrecognized key: "heartbeat"
2026-03-12T01:26:47.730-04:00 Gateway aborted: config is invalid.
2026-03-12T01:26:47.730-04:00 gateway: Unrecognized key: "heartbeat"
2026-03-12T01:26:47.730-04:00 Fix the config and retry, or run "openclaw doctor" to repair.

Workaround

Run openclaw doctor --fix to remove the invalid key. However, this is only temporary - any subsequent modification to heartbeat settings will reintroduce the issue.

Environment

• OpenClaw Version: 2026.3.8
• Node Version: 22.22.0
• Platform: macOS (Darwin 25.3.0 arm64)
• Config file: ~/.openclaw/openclaw.json

Additional Context

The issue appears to be in the config write/migration logic that persists heartbeat settings. The valid schema path is agents.defaults.heartbeat but the code writes to gateway.heartbeat.

The doctor --fix command correctly identifies and removes the invalid key but does not migrate the configuration to the correct location.

Suggested Fix

1. Audit all config write paths that set heartbeat settings
2. Ensure writes go to agents.defaults.heartbeat not gateway.heartbeat
3. Consider adding migration logic in doctor --fix to move existing gateway.heartbeat configs to agents.defaults.heartbeat