Description

OpenClaw persists per-session agent state — per-turn reasoning, tool calls, tool results, token usage, and cost — as JSONL at stable, predictable paths inside the sandbox, but these paths aren't surfaced anywhere in the public docs. They appear only in the codebase (src/lib/skill-install.ts, test/e2e/*.sh, Dockerfile.base):

The obvious CLI path doesn't expose them: nemoclaw <name> logs streams /tmp/gateway.log (infrastructure lifecycle events), not the agent's reasoning or tool calls. So the discovery path today is: run logs, see only [gateway]/[sandbox] events, then grep the sandbox filesystem for *.jsonl and reverse-engineer the layout — roughly 30–60 minutes of confusion that one docs section eliminates.

This matters specifically for NemoClaw's audit/compliance positioning: an audit dashboard or compliance review surface needs the structured session log to show anything beyond "the agent ran a tool," and replay/visualization tooling needs the trajectory file.

Affected Page

No existing page covers it. Closest existing agent-path docs: docs/inference/set-up-sub-agent.mdx (documents auth-profiles.json only) and docs/security/best-practices.mdx (lists .openclaw/agents/ as a memory-path category). A new short section under docs/inference/ or docs/security/ would be the natural home.

Issue Type

Missing documentation

Suggested Fix

One short docs section listing the paths above with a high-level schema sketch and which file to consume for which job — e.g.:

Agent session state. Each session writes to /sandbox/.openclaw/agents/main/sessions/:

• <session-id>.jsonl — one JSON record per event. Use for audit trails / compliance dashboards. Each message record with role: "assistant" carries the thinking block, toolCall blocks, and usage (tokens + cost).
• <session-id>.trajectory.jsonl — lower-level per-token state; large (10s of MB). Needed for fine-grained replay, not for audit narratives.
• sessions.json — index mapping session keys to files.

A nemoclaw <name> session export helper would make this ergonomic — filed separately as a feature request in #3979.