ClawTrace

Trace and debug a single OpenClaw conversation session. Use when you need to analyze openclaw logs, correlate them with the current session context, inspect...

Security Scan

The skill's requirements and runtime instructions are consistent with its stated purpose of parsing OpenClaw session logs and generating a structured trace report.

Purpose & Capability

Name/description match the actions the skill instructs (parse OpenClaw logs + session context -> report). No unrelated credentials, binaries, or install steps are requested.

Instruction Scope

SKILL.md is specific: it instructs using the local 'openclaw logs' CLI and current session context, parses events, computes metrics, and outputs a sanitized Markdown report. It does not ask to read unrelated files, secrets, or transmit data externally.

Install Mechanism

Instruction-only skill with no install spec and no code files — nothing is written to disk or fetched at install time.

Credentials

No environment variables, credentials, or config paths are requested. The only implicit requirement is access to the local 'openclaw' CLI and session context, which is appropriate for the stated task.

Persistence & Privilege

always is false and the skill does not request persistent system-wide changes or other skills' configs. Autonomous invocation is allowed by default but not combined with other elevated privileges.

Assessment

This skill is coherent and appears to do what it says: parse local OpenClaw logs and current session context to produce a report. Before enabling it, ensure the agent environment actually has the 'openclaw' CLI and that you are comfortable granting the agent access to the local logs and session context (logs may contain sensitive data). The skill states it will not include raw log lines in the final report, but parsed fields can still reveal sensitive information — consider running it in a controlled environment or reviewing logs for sensitive tokens before analysis.

ClawTrace analyzes one OpenClaw session at a time. It combines OpenClaw logs and current session context to reconstruct steps, summarize module activity, and generate a Markdown trace report.

When to Use

• Inspect one OpenClaw session end to end
• Explain slow, failed, retried, or noisy runs
• Generate a structured session trace report
• Produce evidence-based optimization suggestions

Core Rules

1. Always analyze one session at a time.
2. Always use both data sources before writing the report:
   • openclaw logs --json --local-time --no-color
   • current session context
3. Never invent missing values. Use Not available, Estimated, or Unknown when needed.
4. Prefer exact identifiers and timestamps over inferred values.
5. Write the report in the user's language unless the user asks for another language.
6. If the user's chat channel supports file sending, prefer delivering the report as a Markdown file; otherwise reply directly in chat using the same report structure.
7. Do not output raw logs, raw JSON, or verbatim log lines in the final report.

Inputs

Logs

Use JSON logs so events can be parsed reliably.

openclaw logs --json --local-time --no-color

• --limit <n> to restrict line count
• --max-bytes <n> to avoid huge tails
• --interval <ms> if polling is needed
• --timeout <ms> if waiting for fresh output
• --expect-final only when the task requires waiting for the final response

Context

Use current session context to identify the target run and recover information not explicit in logs, such as request scope, recent responses, session clues, and context-size indicators.

Analysis Workflow

1: Identify the Target Session

• sessionId
• sessionKey
• runId
• channel
• nearby timestamps
• current-session clues

If multiple runs exist in the same session, prefer the latest completed run unless the user clearly points to a different one.

2: Extract Key Events

Extract session, prompt, agent, tool, lane, context, warning, error, and related gateway events, and capture the key fields needed for analysis such as time, level, module, sessionID, runID, tool, toolCallID, duration, summary, and outcome.

3: Reconstruct Steps

Convert events into ordered steps such as queue, prompt, agent, tool, gateway, context, warn, error, and done.

When possible, pair start and end events to compute duration. If only one side exists, mark duration as Unknown.

4: Compute Metrics

• Session ID
• Session Key
• Run ID
• Start and End Time
• Total Duration
• Step Count
• Tool Count
• Warning Count
• Error Count
• Module Count
• Context Indicators
• Token Indicators

Use exact values when present. Otherwise mark them as Estimated or Not available.

5: Produce Optimization Suggestions

Only give evidence-based suggestions, such as duplicate tool calls, oversized context, repeated warnings, long tool durations, queue delays, or excessive gateway noise.

If there is no clear optimization opportunity, say that no evidence-backed optimization was found.

Output Format

If file sending is supported in the user's chat channel, prefer a Markdown file such as clawtrace-run-<runId>.md or clawtrace-report-<timestamp>.md; otherwise return the same structure directly in chat.

Example Markdown output:

# ClawTrace Report

## Overview
Scope: RunId=<runId> or Message=<message>
Start: <start>
End: <end>
Total Tokens Used: <tokens>
Total Duration: <total_duration> (seconds)
Total Steps: <steps_count> 
Tools Used: <tools_list> (separated by comma)
Warnings: <warn_count>
Errors: <error_count>
Generated at: <time>

Suggestions:
- <evidence-based suggestion>
- <evidence-based suggestion>

## Modules

| Module | Success | Warn | Error | Total Steps | Avg Time Cost | Notes |
| --- | ---: | ---: | ---: | ---: | --- | --- |
| <module> | <success> | <warn> | <error> | <total_steps> | <avg_time_cost> | <notes> |

## Steps

| Step | Time | Type | Module | Action | Duration | Result | Notes |
| ---: | --- | --- | --- | --- | --- | --- | --- |
| 1 | <time> | <type> | <module> | <action> | <duration> | <result> | <notes> |
| 2 | <time> | <type> | <module> | <action> | <duration> | <result> | <notes> |

Sort the Steps table strictly by time in ascending order. Use Success, Failed, Warning, or Unknown for Result, and do not include raw logs or raw JSON.

Partial Data

If the logs contain Log tail truncated (increase --max-bytes)., explicitly state that the report is based on partial logs.

Do not fabricate missing steps. Mark uncertain durations and metrics as Unknown, Estimated, or Not available.

Noise Filtering

Ignore unrelated background noise such as cron timers, heartbeats, and unrelated channel traffic unless they materially affect the target session.

Quality Standard

The report should quickly show which session was analyzed, how long it took, what modules and steps were involved, where time went, what warnings or failures happened, and what to optimize next. If evidence is weak, say so clearly.