collect-session

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)
• INLINECODE3 — append-only table of all collected sessions
• INLINECODE4 — machine-readable record for analytics

Prerequisites

• - LiteLLM running locally — required for cost derivation and LLM enrichment. Verify with: INLINECODE5
• 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:

CODEBLOCK0

Step 2 — Configure the script

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

CODEBLOCK1

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:

CODEBLOCK2

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

CODEBLOCK3

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

CODEBLOCK4

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:
CODEBLOCK5

Output path

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

• - Environment variable: INLINECODE21
• CLI flag: INLINECODE22
• Edit OUTPUT_DIR_DEFAULT in the script CONFIG block

Backfill sweep

To collect all existing uncollected sessions:

CODEBLOCK6

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

CLI reference

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.