Visual diagnostic tool for OpenClaw agent execution traces
See exactly what your AI agent did, step by step — every LLM call, every tool invocation, every token spent.
Quick Start • Features • Architecture • Configuration • Development
When an AI agent handles a task, it goes through an agentic loop — calling the LLM multiple times, invoking tools, reading results, and deciding what to do next. When something goes wrong, you need to answer:
- Which round made the wrong decision?
- Was the prompt too long? What parts are taking up space?
- Why is it slow? Which tool call is the bottleneck?
- How much of the input is hitting the cache vs. being recomputed?
Trace Viewer answers all of these.
Every agent run is displayed as a pipeline of rounds, each representing one complete cycle of the agentic loop:
User Input → Round 1 (LLM → Tools) → Round 2 (LLM → Tools) → ... → Final Reply → End
- Collapsed view: quick overview with duration, tool names, and token counts
- Expanded view: full model output, tool parameters, results, and error details
Breaks down the system prompt into categorized, collapsible sections:
| Category | Color | Examples |
|---|---|---|
| Tooling | Blue | Tool definitions, call style rules |
| Safety | Red | Safety rules, authorized senders |
| Skills | Green | Registered skills and capabilities |
| Messaging | Amber | Reply format, reactions, group chat rules |
| Workspace | Purple | SOUL.md, IDENTITY.md, USER.md, custom files |
| System | Gray | Date/time, runtime config, memory |
A proportion bar shows at a glance how prompt budget is distributed across categories.
Each round shows a detailed breakdown of what was sent to the LLM:
- System Prompt — fixed across rounds, cached after round 1
- History Messages — grows each round as tool results accumulate
- Cache Analysis — shows cache hit ratio with explanation of why content was cached
Round 1: System Prompt [████ new, writes cache] + History [empty]
Round 5: System Prompt [████ cached] + History [██████ cached ██ new tool results]
Cache hit: 94.2% — only new tool results cost full-price tokens
7 built-in diagnostic rules that flag potential issues:
| Rule | Trigger | Severity |
|---|---|---|
| System prompt too large | > 15,000 chars | Warning |
| Too many history messages | > 100 messages | Warning |
| High cache ratio | > 95% | Info |
| Tool call failure | Any failed tool | Error |
| Slow round | > 30 seconds | Warning |
| Too many tool calls | > 20 per run | Info |
| Suspiciously low output | < 10 tokens | Warning |
┌─────────────────────────────────────────────────────────┐
│ OpenClaw Gateway │
│ │
│ Agent Run │
│ ┌─────────┐ ┌──────────┐ ┌───────────┐ │
│ │ LLM Call ├──►│ Tool Call ├──►│ LLM Call │── ... │
│ └────┬─────┘ └────┬─────┘ └────┬──────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────────────────────────────────┐ │
│ │ Collector Plugin (hooks) │ │
│ │ llm_input · llm_output · tool_call · │ │
│ │ before_prompt_build · agent_end │ │
│ └──────────────┬───────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────┐ │
│ │ REST API │ │
│ │ GET /traces │ │
│ │ GET /traces/:id │ │
│ │ GET /health │ │
│ └──────────┬───────────────┘ │
└─────────────┼────────────────────────────────────────────┘
│ HTTP
▼
┌──────────────────────────────────────────────┐
│ Viewer Frontend │
│ │
│ ┌───────────┐ ┌───────────┐ ┌──────────┐ │
│ │ Trace List │ │ Pipeline │ │ Diagnosis│ │
│ │ Page │ │ View │ │ Panel │ │
│ └───────────┘ └───────────┘ └──────────┘ │
│ │
│ React 18 · TypeScript · Tailwind CSS · Zustand│
└──────────────────────────────────────────────┘
The project is a monorepo with two packages:
| Package | Path | Description |
|---|---|---|
@openclaw/trace-viewer |
packages/collector |
OpenClaw plugin that hooks into the agent runtime and collects trace data |
trace-viewer |
packages/viewer |
Web frontend that visualizes collected traces |
# In your OpenClaw gateway config directory
cd ~/.openclaw
# Clone the plugin
git clone https://github.com/Oldcircle/trace-viewer.git plugins/trace-viewer
# Install (no runtime dependencies needed)
cd plugins/trace-viewer/packages/collector
npm install --omit=devEnable the plugin in your OpenClaw configuration:
openclaw config set plugins.trace-viewer.enabled trueRestart the gateway. The collector will automatically begin capturing traces.
cd plugins/trace-viewer/packages/viewer
# Install dependencies
npm install
# Start dev server
npx vite --port 5173Open http://localhost:5173 in your browser.
Go to Settings and set:
- Gateway URL:
http://127.0.0.1:18789(default) - Auth Token: your gateway auth token (if configured)
Click Test Connection to verify.
The collector stores traces in ~/.openclaw/traces/:
~/.openclaw/traces/
├── detail/ # Full trace data (one JSON file per trace)
│ └── tr_1773480030970_159b091c.json
└── index/ # Daily summaries for fast listing
└── 2026-03-14.jsonl
Traces are automatically:
- Created when LLM activity starts
- Finalized when the agent run ends
- Timed out after 2 minutes of inactivity
Settings are persisted to localStorage. Available options:
| Setting | Default | Description |
|---|---|---|
| Gateway URL | http://127.0.0.1:18789 |
OpenClaw gateway address |
| Auth Token | (empty) | Bearer token for authenticated gateways |
The collector plugin exposes these HTTP endpoints under /plugins/trace-viewer:
| Endpoint | Method | Description |
|---|---|---|
/health |
GET | Returns { ok, schemaVersion, activeTraces } |
/traces |
GET | List traces. Query params: date, sessionKey, status, q (search), limit, cursor |
/traces/:traceId |
GET | Full trace detail with all steps |
All responses use schemaVersion: 1 and return JSON.
Each trace consists of ordered steps:
| Step Type | Description | Key Fields |
|---|---|---|
prompt |
User input + prompt construction | prompt, messageCount |
llm_input |
LLM API call parameters | provider, model, systemPrompt, historyMessagesCount |
llm_output |
LLM response | assistantTexts, usage (input/output/cache tokens), durationMs |
tool_call |
Tool invocation + result | toolName, params, resultPreview, success, durationMs |
agent_end |
Run completion | success, durationMs, messagesCount |
error |
Error captured | stage, message |
- Node.js 22+
- An OpenClaw gateway (for real trace data)
cd packages/collector
# Run tests (requires vitest from the OpenClaw workspace)
npx vitest runcd packages/viewer
# Install dependencies
npm install
# Start dev server
npx vite --port 5173
# Type check
npx tsc --noEmit
# Build for production
npx vite buildtrace-viewer/
├── packages/
│ ├── collector/ # OpenClaw plugin
│ │ ├── index.ts # Plugin entry point (hook registration)
│ │ ├── openclaw.plugin.json # Plugin manifest
│ │ └── src/
│ │ ├── collector.ts # Core trace collection logic
│ │ ├── storage.ts # File-based persistence
│ │ ├── api.ts # HTTP route handler
│ │ ├── types.ts # Shared type definitions
│ │ └── truncation.ts # Data preview utilities
│ │
│ └── viewer/ # Web frontend
│ └── src/
│ ├── App.tsx # Root layout + routing
│ ├── pages/ # TraceList, TraceDetail, Settings
│ ├── components/ # Pipeline, Diagnosis, PromptStructure
│ ├── stores/trace.ts # Zustand state management
│ ├── api/client.ts # HTTP client
│ └── types/trace.ts # Type definitions (mirrors collector)
│
├── README.md
└── LICENSE
This plugin requires OpenClaw with per-turn hook support — llm_input and llm_output hooks must fire on every agentic loop round, not just once per run. See openclaw/openclaw#45990 for the upstream PR.
MIT