Collect Session

Installs and configures a hook to capture and save detailed Markdown session summaries with telemetry and cost data on /new or /reset commands.

Security Scan

The skill mostly does what it claims (collects and summarizes session files), but there are mismatches in declared requirements vs instructions and an explicit channel that can transmit whole session contents to an LLM endpoint — the metadata omission and potential data exfiltration risk merit caution.

Purpose & Capability

The name/description match the code: the hook and script read OpenClaw session JSONL files, compute telemetry, optionally call an LLM for naming/summarization, and write Markdown/JSONL outputs. However, registry metadata listed no required env vars or config, while SKILL.md and the scripts clearly require Node, a workspace.dir, a sessions directory, and optionally a LITELLM_API_KEY and LITELLM_BASE_URL — that mismatch is an incoherence.

Instruction Scope

SKILL.md and the hook instruct the agent to read session files (~/.openclaw/agents/main/sessions) and write to the workspace memory directory; this is expected for session collection. The script also performs network calls to a LiteLLM endpoint (default http://localhost:4000) to enrich summaries. That behavior is within the stated purpose but means full session content is transmitted to whatever LITELLM_BASE is configured to (local or remote). The docs encourage retrieving a virtual key from a secrets manager — the key is optional but used if provided.

Install Mechanism

Instruction-only skill with no remote downloads or package installers. The install steps are manual file copies into the workspace and hooks directory; nothing is fetched from arbitrary URLs and no archive extraction occurs.

Credentials

The script reads environment variables (COLLECT_SESSION_OUTPUT_DIR, LITELLM_API_KEY, LITELLM_BASE_URL, COLLECT_SESSION_LLM_MODEL) and expects OpenClaw config values (workspace.dir). Registry metadata did not declare these env vars, creating a transparency gap. Requesting an LLM key is proportional for enrichment, but it enables transmitting session contents to an LLM provider — a sensitive privilege that the metadata failed to surface.

Persistence & Privilege

Skill is not always-enabled and does not request permanent/privileged platform presence. The hook runs on command:new and command:reset and invokes a local node script; it does not modify other skills' configs or system-wide settings beyond enabling itself in openclaw.json as the user instructs.

What to consider before installing

This skill appears to perform the described session collection, but take these precautions before installing: (1) review the included scripts yourself — they read full session JSONL files and will write them to your chosen output directory; (2) be aware that if you set LITELLM_BASE_URL to anything other than localhost or provide a LITELLM_API_KEY, the script will send session contents (including user messages and tool usage) to that endpoint — only use a trusted local or provider endpoint you control; (3) update the OUTPUT_DIR_DEFAULT and SESSIONS_DIR to safe locations you expect, or run with --no-llm to avoid network enrichment; (4) fix the metadata gap: the skill registry entry should declare required env vars (workspace.dir, optional LITELLM_API_KEY) — demand that from the publisher or avoid installing until it's corrected; (5) test in an isolated workspace or non-production account first so you can inspect outputs and logs (gateway logs may receive the script's stdout/stderr). If you want to proceed, prefer running the collector with --no-llm or point LITELLM_BASE_URL to a local-only instance you control.

Captures every session when /new or /reset is issued and writes a rich Markdown summary to disk. Useful for session findability, cost tracking, and building a searchable history of agent work.

What it produces

For each session:

• <output-dir>/sessions/YYYY-MM-DD-<slug>.md — full session report (turns, tool calls, model usage, cost, LLM-generated name + summary)
• <output-dir>/SESSION-INDEX.md — append-only table of all collected sessions
• <output-dir>/session-log.jsonl — machine-readable record for analytics

Prerequisites

• LiteLLM running locally — required for cost derivation and LLM enrichment. Verify with: curl http://localhost:4000/health
• Node.js — node must be in PATH
• OpenClaw workspace.dir — must be set in openclaw.json so the hook can find the script

Installation

Step 1 — Copy the script

Copy scripts/collect-session.mjs to your workspace scripts directory:

cp collect-session.mjs <workspace-dir>/scripts/collect-session.mjs
chmod +x <workspace-dir>/scripts/collect-session.mjs

Step 2 — Configure the script

Edit the CONFIG block at the top of collect-session.mjs. Three values must be set:

// Agent: set to your workspace memory directory
const OUTPUT_DIR_DEFAULT = process.env.COLLECT_SESSION_OUTPUT_DIR
  || path.join(os.homedir(), 'workspace', 'memory');

// Agent: verify this matches your LiteLLM port (default 4000)
const LITELLM_BASE = process.env.LITELLM_BASE_URL || 'http://localhost:4000';

// Agent: find your LiteLLM virtual key.
// Check your LiteLLM dashboard at http://localhost:4000/ui, or retrieve from 1Password/secrets manager.
// Prefer a low-cost key (cron/batch budget) — enrichment costs ~$0.0001/session with Gemini Flash.
const LITELLM_KEY = process.env.LITELLM_API_KEY || 'YOUR_LITELLM_VIRTUAL_KEY';

Alternatively, set environment variables: COLLECT_SESSION_OUTPUT_DIR, LITELLM_API_KEY, LITELLM_BASE_URL.

Step 3 — Install the hook

Copy scripts/hook-handler.ts to your OpenClaw hooks directory and register it:

mkdir -p ~/.openclaw/hooks/collect-session
cp hook-handler.ts ~/.openclaw/hooks/collect-session/handler.ts

Create ~/.openclaw/hooks/collect-session/HOOK.md:

---
name: collect-session
description: "Collect and persist the current session to memory/sessions/ when /new or /reset is issued"
metadata:
  { "openclaw": { "emoji": "📦", "events": ["command:new", "command:reset"], "requires": { "bins": ["node"], "config": ["workspace.dir"] } } }
---

Then enable it in openclaw.json under hooks.internal.entries:

"collect-session": {
  "enabled": true
}

Restart the gateway after making config changes.

Step 4 — Verify

Issue /new in any session. You should see [collect-session] ✅ Session collected in gateway logs.

To check manually:

node <workspace-dir>/scripts/collect-session.mjs --no-llm

Output path

Default output is ~/workspace/memory/. Override with:

• Environment variable: COLLECT_SESSION_OUTPUT_DIR=/path/to/dir
• CLI flag: node collect-session.mjs --output-dir /path/to/dir
• Edit OUTPUT_DIR_DEFAULT in the script CONFIG block

Backfill sweep

To collect all existing uncollected sessions:

node <workspace-dir>/scripts/collect-session.mjs --sweep

Add --no-llm to skip LLM enrichment (faster, uses heuristic names).

CLI reference

Flag	Description
(no args)	Collect most recent completed session
<session-id>	Collect specific session by ID or path
--current	Collect the currently active session (hook use)
--sweep	Collect all uncollected sessions
--no-llm	Skip LLM enrichment, use heuristic title
--force	Re-collect even if already in session-log.jsonl
--output-dir <path>	Override output directory

Troubleshooting

Hook not firing on /new: Check that collect-session is enabled in openclaw.json and the gateway was restarted. Look for [collect-session] lines in gateway logs.

LITELLM_API_KEY not configured warning: Set LITELLM_API_KEY env var or edit the CONFIG block. The script will fall back to heuristic titles but still write session files.

Sessions directory not found: The default sessions path is ~/.openclaw/agents/main/sessions. If you use a custom agent name, update SESSIONS_DIR in the CONFIG block.

Cost shows $0.0000: LiteLLM returns zero cost for some providers. The script derives cost from token counts using a built-in pricing table. Add missing models to MODEL_PRICING in the CONFIG block.