ocdiag

OpenClaw diagnostics CLI — analyze sessions, debug crons, check health.

Install

npm install -g @twelvehart/ocdiag

Or run without installing:

npx @twelvehart/ocdiag --help

From source

git clone <repo-url>
cd ocdiag
npm install
npm run build
npm link  # makes `ocdiag` available globally

Session Directory

ocdiag auto-detects your OpenClaw session directory:

1. $OPENCLAW_HOME_DIR/agents/main/sessions (if set)
2. ~/.openclaw/agents/main/sessions (default)

Override per-command by passing a directory argument: ocdiag sessions list /path/to/sessions.

Commands

ocdiag sessions list [dir]

List session logs with summary stats (message count, errors, duration).

ocdiag sessions list              # last 20 sessions
ocdiag sessions list -n 5         # last 5

| Option | Default | Description | |--------|---------|-------------| | -n, --limit <n> | 20 | Max sessions to show |

ocdiag sessions analyze <file>

Deep-dive into a single session log file. Shows message counts by role, token usage, tool call frequency, errors, most expensive messages, and response timing.

ocdiag sessions analyze ~/.openclaw/agents/main/sessions/2026-02-12_abc123.jsonl

ocdiag sessions errors [pathOrDir]

Scan JSONL logs for error entries. Groups by tool name and shows recent errors.

ocdiag sessions errors                        # scan default dir
ocdiag sessions errors ./my-session.jsonl     # scan single file

ocdiag sessions timeline [dir]

Visualize session activity over time.

ocdiag sessions timeline                          # last 24h
ocdiag sessions timeline -d 7                     # last 7 days
ocdiag sessions timeline --type isolated          # filter by type
ocdiag sessions timeline --label compound --json  # JSON output

| Option | Default | Description | |--------|---------|-------------| | -d, --days <n> | 1 | Days to include | | --min-messages <n> | 2 | Minimum messages per session | | --type <type> | — | Filter by session type (comma-separated) | | --label <pattern> | — | Filter by label substring | | --json | — | Output as JSON |

ocdiag insights [dir]

Summarize cost, errors, anomalies, and model usage across sessions.

ocdiag insights                  # default session dir
ocdiag insights --json           # machine-readable output
ocdiag insights /path/to/dir     # custom dir

| Option | Default | Description | |--------|---------|-------------| | --json | — | Output as JSON |

ocdiag cron test <expression>

Test a cron expression — shows the next N scheduled run times.

$ ocdiag cron test "*/15 * * * *" -n 3
Cron: */15 * * * *
Next 3 runs:

   1. Wed, Feb 12 at 11:00 PM  in 1 min
   2. Wed, Feb 12 at 11:15 PM  in 16 min
   3. Wed, Feb 12 at 11:30 PM  in 31 min

| Option | Default | Description | |--------|---------|-------------| | -n, --count <n> | 10 | Number of runs to show | | -t, --timezone <tz> | system | Timezone (e.g., America/New_York) |

ocdiag cron validate [configPath]

Validate gateway cron configuration. Checks schedules and payload requirements; reports errors and warnings.

ocdiag cron validate                              # auto-detect config
ocdiag cron validate ~/.openclaw/openclaw.json    # explicit path

ocdiag health

Overall health report: cron job status, recent session stats, error rates.

$ ocdiag health
🩺 OpenClaw Health Report
   Status: ● Healthy

Cron Jobs
  No cron jobs configured

Sessions (last 24h)
  Active: 97  Messages: 1472  Errors: 3  Error rate: 0.2%

  Total sessions on disk: 894

Development

npm run build       # compile to dist/
npm run dev         # watch mode
npm run test        # run tests
npm run test:watch  # watch tests

Publishing

# 1. Bump version
npm version patch  # or minor / major

# 2. Build
npm run build

# 3. Run tests
npm test

# 4. Publish
npm publish

# 5. Push tag
git push origin main --tags

License

MIT © Ahmad Ragab