How to Monitor OpenClaw Agents: Dashboards, Heartbeats, and Progress Tracking

Running an AI agent in a demo is forgiving. Running one in production is a different game entirely. Without proper monitoring, your OpenClaw agent could silently fail mid-task, burn through your token budget, or stall indefinitely — and you would have no idea until a customer complaint lands in your inbox.

This guide walks through everything you need to monitor OpenClaw agents properly: the five metrics that matter, heartbeat setup, progress tracking patterns, error alerting, cost monitoring, and how to bring it all together in a dashboard.

Why Agent Monitoring Is Non-Negotiable in Production

Unlike a traditional API endpoint that either returns a 200 or fails fast, an AI agent operates over an extended, multi-step reasoning loop. Each step invokes tools, consumes tokens, calls external services, and makes branching decisions. Any one of those can go wrong silently.

The three failure modes that hurt most in production:

1. Silent stalls — the agent is "running" but waiting on a tool call that never returns
2. Runaway costs — no token ceiling means a single agent session can exhaust your monthly budget
3. Invisible errors — an exception is swallowed, the agent halts, and the user sees nothing

Monitoring turns these invisible problems into actionable signals. It also gives you the audit trail you need when a customer asks "why did your agent do that?"

The Five Metrics That Matter

Before building any dashboard, define what you are measuring. For OpenClaw agents in production, these five metrics cover 95% of the observability surface:

1. Liveness (Is the agent still running?)

A heartbeat timestamp updated every N seconds. If it goes stale, the agent has stalled or crashed.

2. Progress (What step is it on?)

Which tool was last invoked, how many steps completed vs. total expected, and what the current intent is.

3. Errors (Did something fail?)

Tool call failures, API errors, unexpected exceptions, and any agent-surfaced error messages. Tracked as a count and a log.

4. Cost (How many tokens consumed?)

Input tokens, output tokens, and total estimated cost per session. Aggregated daily and per-agent.

5. Latency (How long per step?)

Time per tool call and total session duration. Helps identify slow external dependencies before users complain.

OpenClaw's Built-In Logging

OpenClaw exposes structured logs out of the box. Every agent run emits events in JSON format to stdout:

{
  "event": "tool_call",
  "agent_id": "agent_abc123",
  "session_id": "sess_xyz789",
  "tool": "web_search",
  "input": { "query": "Q3 SaaS churn benchmarks" },
  "timestamp": "2026-03-15T09:14:22.341Z",
  "tokens_in": 420,
  "tokens_out": 0,
  "duration_ms": 0
}

What it provides:

• Tool invocation events with input and output
• Per-step token counts
• Session start and end events
• Error events with stack traces

Limitations to know:

• No aggregation — raw event stream only
• No built-in alerting
• Log retention depends on your infrastructure setup
• No cost rollup (you calculate from token counts)

For anything beyond basic debugging, you need to build on top of this stream.

Setting Up Heartbeat Monitoring

A heartbeat is the simplest and most important monitoring primitive. Here is how to implement one for OpenClaw agents.

Step 1 — Emit heartbeats from your agent loop

import { OpenClawAgent } from '@openclaw/sdk';

const agent = new OpenClawAgent({ agentId: 'research-agent' });

agent.on('step', async (step) => {
  await fetch('/api/heartbeat', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      agentId: step.agentId,
      sessionId: step.sessionId,
      stepNumber: step.number,
      timestamp: new Date().toISOString(),
    }),
  });
});

Step 2 — Store heartbeats in PocketBase

// api/heartbeat.ts (Astro SSR route)
export const prerender = false;

export async function POST({ request }) {
  const body = await request.json();
  const pb = new PocketBase(import.meta.env.PUBLIC_POCKETBASE_URL);

  await pb.collection('heartbeats').create({
    agent_id: body.agentId,
    session_id: body.sessionId,
    step_number: body.stepNumber,
    timestamp: body.timestamp,
  });

  return new Response(JSON.stringify({ ok: true }), { status: 200 });
}

Step 3 — Set up a staleness check

const staleThresholdMs = 60_000;
const cutoff = new Date(Date.now() - staleThresholdMs).toISOString();

const stale = await pb.collection('heartbeats').getList(1, 50, {
  filter: `timestamp < "${cutoff}" && status = "running"`,
});

for (const session of stale.items) {
  await alertSlack(`Agent ${session.agent_id} may be stalled. Last heartbeat: ${session.timestamp}`);
}

Task Progress Tracking Patterns

Heartbeats tell you the agent is alive. Progress tracking tells you where it is.

Pattern 1 — Structured step events

agent.on('step', async (step) => {
  await pb.collection('agent_progress').create({
    session_id: step.sessionId,
    step_number: step.number,
    tool_called: step.tool,
    status: 'completed',
    tokens_in: step.usage.inputTokens,
    tokens_out: step.usage.outputTokens,
    duration_ms: step.durationMs,
    timestamp: new Date().toISOString(),
  });
});

Pattern 2 — Intent labeling

const TOOL_INTENT_MAP: Record<string, string> = {
  web_search: 'Searching the web',
  read_file: 'Reading document',
  write_file: 'Saving output',
  send_email: 'Sending notification',
  code_execution: 'Running code',
};

const intent = TOOL_INTENT_MAP[step.tool] ?? `Using ${step.tool}`;

Pattern 3 — Estimated completion

const EXPECTED_STEPS = 8;
const progressPct = Math.min(100, Math.round((step.number / EXPECTED_STEPS) * 100));

Error Alerting Setup

Slack Alerts

export async function alertSlack(message: string, level: 'info' | 'warn' | 'error' = 'info') {
  const emoji = { info: ':robot_face:', warn: ':warning:', error: ':red_circle:' }[level];

  await fetch(process.env.SLACK_WEBHOOK_URL!, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      text: `${emoji} *OpenClaw Agent Alert*\n${message}`,
    }),
  });
}

agent.on('error', async (error) => {
  await alertSlack(
    `Agent ${error.agentId} failed on step ${error.stepNumber}\nTool: ${error.tool}\nError: ${error.message}`,
    'error'
  );
});

Email Alerts

export async function sendDailyDigest(stats: AgentDailyStats) {
  await resend.emails.send({
    from: 'alerts@getclawhosting.com',
    to: process.env.ALERT_EMAIL!,
    subject: `OpenClaw Daily Report — ${stats.date}`,
    html: `<h2>Agent Activity Report</h2>
      <ul>
        <li>Sessions run: ${stats.sessionsCount}</li>
        <li>Errors: ${stats.errorsCount}</li>
        <li>Total tokens used: ${stats.totalTokens.toLocaleString()}</li>
        <li>Estimated cost: $${stats.estimatedCostUsd.toFixed(4)}</li>
      </ul>`,
  });
}