ocx-tail 0.1.1

OpenClaw CLI companion: tail/analyze/export for agent runs

ocx

A CLI companion for OpenClaw logs.

ocx turns noisy openclaw logs output into a structured, high-signal stream.

It is designed for: - debugging gateway conflicts - tracking agent run lifecycles - spotting provider rate limits & connection failures - reducing log spam during live sessions - exporting normalized events for further analysis

---

Features

• Pretty tail for OpenClaw logs
• Error-only filtering
• Hide websocket noise (gateway/ws)
• Automatic de-duplication of repeated identical errors
• Run-level summary (analyze)
• JSONL export (export)
• Clean internal event model (extensible, rule-based classifier)

---

Installation

Recommended: pipx

sudo apt update
sudo apt install -y pipx
pipx ensurepath
source ~/.profile

# inside this repository:
pipx install .

Verify:

ocx --help

---

Usage

Tail OpenClaw logs

openclaw logs --follow | ocx tail

Or:

ocx tail --follow

Errors only

openclaw logs --follow | ocx tail --errors-only

Disable duplicate collapsing

openclaw logs --follow | ocx tail --no-dedup

---

Analyze a saved log file

ocx analyze /tmp/openclaw/openclaw-2026-02-17.log

---

Export normalized JSONL

openclaw logs --follow | ocx export > events.jsonl

---

Event Model

All log lines are normalized into:

Event(
    ts: Optional[str],
    run_id: Optional[str],
    type: EventType,
    name: str,
    payload: Dict[str, object],
)

High-signal classifications include:

• gateway.conflict
• run.start / run.done / run.timeout
• provider.connection_error
• provider.rate_limit

---

Architecture

The codebase is intentionally structured:

• Parsing (regex + classification)
• IO (stdin, file, openclaw subprocess)
• Presentation (Rich formatting)
• CLI wiring (Typer)

---

License

MIT