Agent health checks and auth repair
Learn what the built-in health check looks at and when to use auth repair, re-check auth, or a manual heartbeat run.
Agent health checks help you tell whether a problem lives in the runtime, the OpenClaw agent, or the ClawControl connection layer.
What the health check looks at
ClawControl groups the check into three areas so problems are easier to locate.
Runtime checks
Runtime checks focus on whether the host is in a usable state.
They typically verify things such as:
- backend and OpenClaw gateway connectivity
- whether the Mission Control plugin config is visible on the runtime
- whether the runtime is healthy, degraded, or effectively offline
Agent checks
Agent checks focus on whether the OpenClaw agent can actually execute work.
They typically verify things such as:
- whether the agent still exists in OpenClaw
- whether provider auth is ready
- whether the Mission Control plugin is enabled for that agent
- whether the Mission Control refresh token exists
- whether the heartbeat cron job exists, is enabled, and has run successfully
ClawControl link checks
Link checks focus on whether the agent can still talk back to ClawControl.
They verify things such as:
- whether the plugin has the expected backend URL
- whether the refresh token can be exchanged successfully
- whether the agent can still reach the Mission Control API
What the overall statuses mean
| Status | Meaning |
|---|---|
| Healthy | the runtime, agent execution, and ClawControl link all look usable |
| Degraded | the agent may still work, but something needs attention |
| Broken | a hard failure is preventing normal work |
| Blocked | the runtime is offline or checks cannot complete yet |
The most useful actions in the agent UI
| Action | When to use it |
|---|---|
| Health Check | Run the full diagnostic when an agent looks unhealthy or work is failing unexpectedly |
| Re-check Auth | Refresh the visible auth state after changing provider credentials on the OpenClaw side |
| Run Heartbeat Now | Trigger a quick execution check when the agent should be able to run normally |
| Repair Auth | Re-seed Mission Control plugin auth when the ClawControl link is broken or stale |
When Repair Auth is the right move
Use Repair Auth when the agent still exists and the plugin is present, but the Mission Control connection layer looks broken.
Common examples include:
- the refresh token is missing or stale
- token exchange fails
- the agent shows a link-level auth issue even though local provider auth is fine
Repair Auth is not the first fix for every problem. If the runtime is offline or provider auth is missing, resolve those issues first.
Good troubleshooting order
1. Run Health Check
Start with the built-in check so you know whether the issue is runtime, execution, or ClawControl linkage.
2. Fix provider auth if needed
If the check shows missing or broken provider auth, correct that on the OpenClaw side and then use Re-check Auth.
3. Use Repair Auth for link-level token problems
If the plugin is present but the Mission Control link is failing, repair the agent auth instead of redoing the whole runtime setup immediately.
4. Run Heartbeat Now to confirm recovery
A manual heartbeat run is a fast way to confirm the agent can execute again.