Skill: lucal6/claw-insights-install (version 1.0.0)

--- name: claw-insights-install description: 'Install and run Claw Insights, a read-only observability dashboard that monitors your OpenClaw agent with zero intrusion — no code changes, no cloud dependency, data never leaves your machine. Full session transcript replay, per-turn token and tool tracking, and shareable PNG/SVG status cards. One command to install, auto-discovers your running gateway, lightweight SQLite storage. Use when setting up claw-insights for the first time, upgrading versions, configuring auth or port, managing the service, or troubleshooting startup failures.' --- # Install Claw Insights **Announce at start:** "I'm setting up Claw Insights — a read-only observability dashboard for your OpenClaw agent." ## What is Claw Insights? A read-only observability dashboard for OpenClaw agents. One command installs it, auto-connects to your running gateway — no configuration needed. - **Zero intrusion** — pure sidecar that reads logs and CLI output only; no code changes, no cloud calls, data stays on your machine - **Full session replay** — complete transcript timeline with role separation, tool calls, and per-turn token tracking - **Shareable snapshots** — generate PNG/SVG status cards with themes, languages, and detail levels via REST API Runs locally with SQLite. Requires Node.js ≥ 22.5 and a running OpenClaw gateway. ## Install ```bash # One-line install (recommended) curl -fsSL https://claw-insights.com/install.sh | sh # Or via npm npm install -g claw-insights ``` ## Run ```bash claw-insights start # Default port 41041, opens browser claw-insights start --port 8080 # Custom port claw-insights start --no-auth # Disable authentication claw-insights stop # Stop the service claw-insights restart # Restart ``` ## Verify ```bash curl http://127.0.0.1:41041/health # → {"status":"ok",...} ``` ## Upgrade ```bash npm update -g claw-insights # Or re-run the install script curl -fsSL https://claw-insights.com/install.sh | sh ``` ## Quick Config | Variable | Default | Description | | ---------------------------------- | ----------------------------- | --------------------------- | | `CLAW_INSIGHTS_SERVER_PORT` | `41041` | Server port | | `CLAW_INSIGHTS_API_TOKEN` | _(auto)_ | Auth token (min 32 chars) | | `CLAW_INSIGHTS_NO_AUTH` | `false` | Disable auth entirely | | `CLAW_INSIGHTS_DB` | `~/.claw-insights/metrics.db` | SQLite database path | | [REDACTED_SECRET] | `7` | Raw metric retention (days) | Full configuration reference: See [references/configuration.md](references/configuration.md) ## Troubleshooting | Symptom | Cause | Fix | | --------------------------- | ---------------------------- | -------------------------------------------------- | | `EADDRINUSE` | Port already in use | `claw-insights stop` then retry, or use `--port` | | `Cannot connect to gateway` | OpenClaw gateway not running | Start gateway: `openclaw gateway start` | | `401 Unauthorized` | Token mismatch | Check `CLAW_INSIGHTS_API_TOKEN` or use `--no-auth` | | `Node.js version error` | Node.js < 22.5 | Upgrade Node.js to ≥ 22.5 | More troubleshooting: See [references/troubleshooting.md](references/troubleshooting.md) ## Next Step Use the `claw-insights-snapshot` skill to generate and share visual status cards via REST API.

path: references/configuration.md
content: # Configuration Reference

> This is a quick reference covering the most common settings. For the full configuration reference (including logging, NODE_ENV defaults, and advanced tuning), see [docs/configuration.md](../../../configuration.md).

All variables use the `CLAW_INSIGHTS_` prefix. For backward compatibility, `OPENCLAW_` prefix is also accepted (lower priority).

## Core

| Variable                    | Default            | Description                                                                      |
| --------------------------- | ------------------ | -------------------------------------------------------------------------------- |
| `CLAW_INSIGHTS_SERVER_PORT` | `41041`            | GraphQL API + web server port                                                    |
| `CLAW_INSIGHTS_WEB_PORT`    | `41042`            | Vite dev server port (development only)                                          |
| `CLAW_INSIGHTS_API_TOKEN`   | _(auto-generated)_ | Fixed Bearer token (minimum 32 characters). Empty = auto-generate on fresh start |
| `CLAW_INSIGHTS_NO_AUTH`     | `false`            | Disable authentication entirely (`true` or `1`)                                  |
| `CLAW_INSIGHTS_SERVER_ONLY` | `false`            | Run API server without serving web UI                                            |

## Session Rotation

| Variable                                         | Default    | Description                              |
| ------------------------------------------------ | ---------- | ---------------------------------------- |
| `CLAW_INSIGHTS_TOKEN_ROTATION_ENABLED`           | `true`     | Enable rotating session-cookie key-ring  |
| [REDACTED_SECRET]       | `86400000` | Rotation interval (24h)                  |
| `CLAW_INSIGHTS_TOKEN_GRACE_MS`                   | `43200000` | Previous-key grace window (12h)          |
| [REDACTED_SECRET] | `300000`   | Background rotation check cadence (5min) |
| [REDACTED_SECRET]               | `2`        | Max retained previous keys in key-ring   |

## Data Sources

| Variable                      | Default                                          | Description                   |
| ----------------------------- | ------------------------------------------------ | ----------------------------- |
| `CLAW_INSIGHTS_DB`            | `~/.claw-insights/metrics.db`                    | SQLite database path          |
| `CLAW_INSIGHTS_SESSIONS_PATH` | `~/.openclaw/agents/main/sessions/sessions.json` | OpenClaw sessions file        |
| `CLAW_INSIGHTS_LOG_DIR`       | `/tmp/openclaw/`                                 | OpenClaw log directory        |
| `CLAW_INSIGHTS_CRON_PATH`     | `~/.openclaw/cron/jobs.json`                     | OpenClaw cron jobs file       |
| `CLAW_INSIGHTS_DIR`           | `~/.openclaw`                                    | OpenClaw base directory       |
| `CLAW_INSIGHTS_CLI`           | _(auto-detected)_                                | Path to `openclaw` CLI binary |

## Data Retention

| Variable                           | Default     | Description                                                |
| ---------------------------------- | ----------- | ---------------------------------------------------------- |
| [REDACTED_SECRET] | `7`         | Days to keep raw metric data                               |
| `CLAW_INSIGHTS_HOURLY_RETENTION`   | `permanent` | Hourly aggregate retention (`permanent` or number of days) |

## Config File

Path: `~/.claw-insights/config.json`

Supports a subset of configuration keys in camelCase (without the `CLAW_INSIGHTS_` prefix). Environment variables take precedence over config file values. Unknown keys are logged as warnings and ignored.

Supported keys: `serverPort`, `webPort`, `apiToken`, `noAuth`, `dbPath`, `logLevel`, `serverOnly`, `tokenRotationEnabled`, `tokenRotationIntervalMs`, `tokenGraceMs`, `tokenMaxPrevious`, `rawRetentionDays`, `hourlyRetention`, `transcriptsDir`, `deviceJsonPath`, `sessionHierarchyMode`, and logging/pressure-related keys. See `knownKeys` in `config.ts` for the complete list.

Example:

```json
{
  "serverPort": 41041,
  "noAuth": false,
  "rawRetentionDays": 7
}
```


path: references/troubleshooting.md
content: # Troubleshooting

> Paths below use default locations. If you customized `CLAW_INSIGHTS_DIR`, `CLAW_INSIGHTS_DB`, or other path variables, substitute accordingly.

## Port Conflict — `EADDRINUSE`

**Symptom:** `Error: listen EADDRINUSE: address already in use :::41041`

**Diagnosis:**

```bash
lsof -i :41041
# or
claw-insights stop
```

**Fix:**

- Stop existing instance: `claw-insights stop`
- Or use a different port: `claw-insights start --port 8080`

---

## Gateway Connection Failed

**Symptom:** Dashboard shows "Gateway: disconnected" or data panels are empty.

**Diagnosis:**

```bash
# Check if OpenClaw gateway is running
openclaw gateway status

# Check if sessions file exists
ls ~/.openclaw/agents/main/sessions/sessions.json
```

**Fix:**

- Start gateway: `openclaw gateway start`
- If sessions file missing: ensure OpenClaw is configured and has run at least once
- Check `CLAW_INSIGHTS_DIR` points to the correct OpenClaw directory

---

## Authentication Issues

### 401 Unauthorized

**Symptom:** API calls return `401` status.

**Diagnosis:**

```bash
# Check configured token
echo "$CLAW_INSIGHTS_API_TOKEN"
# Or check auth-secret file
cat ~/.claw-insights/auth-secret 2>/dev/null

# Test token against an authenticated endpoint
[REDACTED_SECRET] ~/.claw-insights/auth-secret 2>/dev/null)}"
curl -s -o /dev/null -w "%{http_code}" \
  -X POST http://127.0.0.1:41041/api/snapshot \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{}'
# → 200 = token valid, 401 = token invalid
```

> Note: `/health` does not require auth and cannot be used to verify tokens.

**Fix:**

- Ensure Bearer token matches `CLAW_INSIGHTS_API_TOKEN` or the value in `~/.claw-insights/auth-secret`
- Token must be ≥ 32 characters
- Or disable auth: `claw-insights start --no-auth`

### Cookie / Session Expired

**Symptom:** Web UI suddenly asks for re-authentication.

**Fix:** This is normal — session cookies rotate every 24h by default. Re-enter the token. To extend: increase `CLAW_INSIGHTS_TOKEN_ROTATION_INTERVAL_MS`.

---

## Database Issues

### Permission Denied

**Symptom:** `SQLITE_CANTOPEN` or permission errors on startup.

**Diagnosis:**

```bash
ls -la ~/.claw-insights/metrics.db
```

**Fix:**

- Ensure the user running claw-insights has read/write access
- Or set a custom path: `CLAW_INSIGHTS_DB=/path/to/writable/metrics.db`

### Database Corruption

**Symptom:** Queries fail with `SQLITE_CORRUPT` errors.

**Fix:**

```bash
# Stop the service
claw-insights stop

# Back up corrupted file
mv ~/.claw-insights/metrics.db ~/.claw-insights/metrics.db.bak

# Restart — a fresh database will be created
claw-insights start
```

Historical data will be lost, but new data collection starts immediately.

---

## Node.js Version Incompatibility

**Symptom:** `SyntaxError: Unexpected token` or import errors on startup.

**Diagnosis:**

```bash
node --version
# Must be ≥ 22.5
```

**Fix:**

- Upgrade Node.js: `nvm install 22` or download from https://nodejs.org
- Claw Insights uses Node.js native features (ESM, fetch, etc.) that require ≥ 22.5

---

## Remote Access

**Symptom:** Cannot access dashboard from another machine on the network.

**Diagnosis:**

```bash
# Check if listening on all interfaces
curl http://YOUR_IP:41041/health
```

**Fix:**

- By default, claw-insights binds to `127.0.0.1` (localhost only)
- For LAN access, use a reverse proxy (nginx, caddy) or SSH tunnel:
  ```bash
  ssh -L 41041:127.0.0.1:41041 user@remote-host
  ```
- **Security note:** Do not expose claw-insights directly to the internet without authentication enabled


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)