openclaw-tracking

OpenClaw Activity Tracking Architecture

Overview

SafeClaw tracks OpenClaw AI agent activities using a dual-source approach because the gateway WebSocket does NOT broadcast tool call events.

Event Sources

Source 1: Gateway WebSocket (real-time, limited)

Connects to ws://127.0.0.1:{port} (default 18789) using Ed25519 device auth.

Events received:

• agent with stream=lifecycle — session start/end (phase: start/end/error)
• agent with stream=assistant — LLM text streaming (skipped, not security-relevant)
• chat — final message delivery (WhatsApp, agent responses)
• exec.approval.requested — command approval requests
• tick — keepalive
• presence — online status

Events NOT received:

• agent with stream=tool — tool invocations (file reads, writes, shell commands). These are processed internally by the [agent/embedded] subsystem but never broadcast to WebSocket clients. This was confirmed via gateway log analysis.

Source 2: Session JSONL Files (complete, file-tailed)

OpenClaw stores complete interaction histories at:

~/.openclaw/agents/{agentName}/sessions/{sessionId}.jsonl

Active sessions are listed in:

~/.openclaw/agents/{agentName}/sessions/sessions.json

JSONL entry types:

{"type":"session","id":"...","timestamp":"...","cwd":"..."}
{"type":"model_change","id":"...","modelId":"claude-haiku-4-5"}
{"type":"message","id":"...","parentId":"...","message":{"role":"user","content":[{"type":"text","text":"..."}]}}
{"type":"message","id":"...","parentId":"...","message":{"role":"assistant","content":[{"type":"toolCall","id":"toolu_...","name":"read","arguments":{"file_path":"/path"}}]}}
{"type":"message","id":"...","parentId":"...","message":{"role":"toolResult","toolCallId":"toolu_...","content":[{"type":"text","text":"FULL FILE CONTENT"}]}}

The parentId chain creates a tree structure. Each role: "user" message starts a new interaction run.

Architecture

┌─────────────────┐     ┌──────────────────┐
│ Gateway WS      │     │ Session JSONL     │
│ (chat/lifecycle)│     │ (tool calls+content)│
└────────┬────────┘     └────────┬───────────┘
         │                       │
    OpenClawClient         SessionWatcher
         │                       │
         └───────┬───────────────┘
                 │
         OpenClawMonitor
         ├── analyzeActivityThreat() → classifyActivity()
         │   ├── 10 threat category analyzers (see threat-classification.md)
         │   └── scanForSecrets() (via TC-SEC analyzer)
         ├── DB insert (agent_activities + threat_findings JSON)
         └── Socket.IO emit → React dashboard