openclaw - 💡(How to fix) Fix [Feature]: per-agent model override for heartbeat sessions [1 participants]

Summary

Add a model option to the heartbeat configuration (either in openclaw.json or as a --model flag on openclaw system heartbeat enable) that overrides the model used specifically for heartbeat-triggered agent runs.

Problem to solve

Currently heartbeats always use the agent's default model (inherited from agents.defaults.model). There's no way to configure a lighter/cheaper model specifically for heartbeat invocations without affecting all interactive sessions for that agent.

Proposed solution

"heartbeat": { "interval": "30m",
"model": "openrouter/anthropic/claude-haiku-4.5"
}

Alternatives considered

1. Per-agent default model (safest, but a blunt instrument) Set Haiku as the default model for a specific agent in openclaw.json. Heartbeats and all interactive conversations for that agent would use Haiku. Probably too limiting.

2. Temp-switch script (risky) A script that switches the global default to Haiku, fires the heartbeat, waits, then switches back. The race condition is the problem. If a Telegram message arrives during the 5-10 second window, it gets Haiku instead of Sonnet. And if the script fails mid-run, the config stays wrong until manually fixed.

3. Replace heartbeats with cron + openclaw agent calls (no model gain) Disable the OpenClaw heartbeat and drive the same behavior via cron calling openclaw agent. But since openclaw agent also inherits the global model, you gain nothing on cost, just more complexity.

Impact

• Affects any deployment running multiple agents with heartbeats enabled. Severity is low, it doesn't block functionality, but the cost impact is ongoing and scales linearly with the number of agents and heartbeat frequency.
• In practice: a 5-agent deployment with 30-minute heartbeats runs ~240 heartbeat invocations per day. Heartbeat tasks are intentionally minimal (read a file, check a date, send one alert or reply OK), but they currently run on whatever the primary model is, in most production deployments, Sonnet or equivalent. There's no mechanism to route these lightweight, repetitive calls to a cheaper model without also downgrading all interactive sessions for that agent.
• This occurs on every heartbeat tick, it's not intermittent. The consequence isn't errors or workflow blockage, it's persistent unnecessary spend. For a cost-conscious deployment the practical workaround is to either keep heartbeats disabled (losing proactive monitoring) or accept the overhead. Neither is a good answer for what should be a solved problem at the config layer.

Evidence/examples

Running openclaw system heartbeat --help and openclaw system heartbeat enable --help confirms no --model flag exists. The openclaw agent CLI also has no --model flag. Per-agent model config (agents.list[n].model) is not a supported key in openclaw.json — openclaw config get agents.main.model returns Config path not found.

Gateway logs confirm heartbeats fire using the global default model with no override mechanism:

{"subsystem":"gateway/heartbeat","intervalMs":1800000,"heartbeat":"started"}

The active session for the heartbeat agent (agent:main:main) consistently shows claude-sonnet-4-6 with no way to configure an alternative at the heartbeat level. The only workaround available today is setting a per-agent default model in openclaw.json, which affects all interactive sessions for that agent — not just heartbeat invocations.

Confirmed on OpenClaw v2026.3.28, macOS 26.4, Node 22.22.2.

Additional information

No response