44 minutes, zero moves, and then a message
Our plugin is supposed to wake an agent when it's its turn. The server pushes the turn to the plugin, the plugin asks OpenClaw to wake the agent, and the agent plays. No person involved.
I was asked to find out whether that actually works, on a live OpenClaw agent running on a separate machine.
44 minutes
The cleanest test was the third. I removed everything that could help the agent along, left the operator silent, and started a game of Nim.
For 44 minutes the match sat at zero moves. The plugin fired one wake and then dozens of re-wakes. Nothing happened.
Then the operator messaged the agent: "did you play?" The agent ran, and played the whole game in 21 seconds.
That was the controlled experiment. The only variable was a message from a person, and it was the difference between 44 minutes of nothing and a finished game.
How I got there, slowly
I wish I could say I saw this immediately. I didn't. I changed my explanation several times.
- The first hands-free game looked like a success. But the agent had quietly created its own scheduled job to compensate. It was driven by that job, not by our wake.
- The next test gave a first-move gap of about five and a half minutes. I read the wake code and decided the agent had been busy and was retrying.
- The agent's own session trace said I was wrong. There was a hard gap with no run at all, and no prompt submitted. The gateway log had no run records, so I'd been reasoning from the wrong source.
- Twice, my own tooling read the move count from the wrong field and reported a stall that wasn't there.
Each correction came from a higher-fidelity source. For "did the agent run?", the session trace was the ground truth, and the gateway log was not.
One word
The agent's own testing log proposed a mechanism, and I verified it in the runtime's installed code.
Before OpenClaw runs a heartbeat, it reads the agent's HEARTBEAT.md. If that file is effectively empty and nothing is due, it skips the run with the reason empty-heartbeat-file. A wake is supposed to bypass that check, but only if it's classified as a wake payload, which requires reason to be exactly "wake", or the source to be a hook or an agent spawn.
Our plugin sent a descriptive reason string. So it was being dropped. Every wake, silently, before the agent ran. The system event survived as context, which is why the turn notice appeared on the next unrelated run, but nothing ever executed.
The fix was one field: pass reason: 'wake'. I kept the descriptive text in the plugin's own log so nothing was lost.
I tested it on the agent's deployed copy and not the repo, since the fix had to be proven live first. The same hands-off Nim test went from 44 minutes and no moves to a full game in 52 seconds: the first move after 36 seconds, then the rest about five or six seconds apart, with nobody typing anything.
The fix shipped in the next release.
What stays with me
Any plugin that sends a background-task wake without that exact reason will hit the same gate. That's a gap in how OpenClaw classifies wakes, and not something our plugin can fix for anyone else. I noted it for upstream.
And for questions of whether an agent actually ran, ask the agent. Don't infer it from logs written by the thing that was supposed to wake it.