Mastering Agent Observability: Logs, Status, and Diagnostics

Building an autonomous agent is one thing; understanding what it's doing—and why—is another. Unlike traditional software, agents exhibit non-deterministic behavior. They "think," they decide, and sometimes, they get stuck.

To run reliable agents in production, you need visibility. OpenClaw provides a suite of observability tools designed specifically for this purpose. In this guide, we'll explore how to use the CLI, logs, and the advanced diagnostics system to keep your digital workforce running smoothly.

1. The Pulse of Your Agent: openclaw status

Your first line of defense is the status command. It gives you an immediate snapshot of the Gateway's health.

openclaw gateway status

This command communicates with the running daemon and returns key metrics:

• Version: Ensure you're running the latest release.
• Uptime: How long has the agent been alive?
• Memory Usage: Critical for identifying leaks in long-running sessions.
• Active Sessions: Who is talking to your agent right now?

If your agent feels unresponsive, status will tell you if the process is even running or if it has crashed.

2. Tailing Logs Like a Pro

When status shows green but behavior is off, it's time to dive into the logs. OpenClaw writes structured logs that track every decision, tool call, and error.

The easiest way to view them is via the CLI:

openclaw logs --follow

This commands tails the active log file (typically located at ~/.openclaw/logs/openclaw-YYYY-MM-DD.log).

Understanding the Output

OpenClaw's CLI formats these logs for readability:

• Info (Blue/Green): Routine operations like message receipt or tool completion.
• Warn (Yellow): Non-critical issues, such as a retry on a model call.
• Error (Red): Failures that require attention (e.g., API outages, permission denied).

For machine processing, you can view the raw JSON lines:

openclaw logs --follow --json

3. Advanced Telemetry: Diagnostics & OpenTelemetry

For production deployments, reading text logs isn't enough. You need metrics and traces to spot trends over time. This is where OpenClaw's Diagnostics system comes in.

Diagnostics are structured, machine-readable events emitted by the core runtime. They cover:

• Model Usage: Token counts, cost, and latency per provider.
• Message Flow: Webhook ingress, queue depth, and processing time.
• Session State: Transitions between "idle", "thinking", and "stuck".

Enabling OpenTelemetry (OTel)

OpenClaw has native support for OpenTelemetry (OTLP/HTTP). You can export these diagnostics to platforms like Grafana, Jaeger, or Honeycomb.

Add this to your openclaw.json to enable export:

{
  "diagnostics": {
    "enabled": true,
    "otel": {
      "enabled": true,
      "endpoint": "http://otel-collector:4318",
      "serviceName": "openclaw-gateway",
      "traces": true,
      "metrics": true
    }
  }
}

Once enabled, you'll start seeing rich traces of your agent's "thought process"—from the initial webhook event, through the model's reasoning, down to the final tool execution.

4. Debugging in Real-Time

Sometimes you need to inspect the raw stream of data coming from the LLM, especially when fine-tuning prompts or debugging "reasoning" models that output thinking blocks.

You can enable Raw Stream Logging to catch the unparsed output:

OPENCLAW_RAW_STREAM=1 openclaw gateway start

This writes a separate log file (raw-stream.jsonl) capturing every token exactly as it arrives from the provider, before OpenClaw parses it into text or tool calls. This is invaluable for debugging parsing errors or hallucinated JSON.

Conclusion

Observability is not an afterthought—it is the foundation of reliable agent engineering. By mastering openclaw status, becoming comfortable with the logs, and leveraging OpenTelemetry, you transform your agent from a "black box" into a transparent, manageable system.

Start by running openclaw logs --follow in a separate terminal window today. You might be surprised by what you see.