codeburn/docs/providers/openclaw.md

OpenClaw

OpenClaw, plus the older Clawdbot / Moltbot / Moldbot lineage.

• Source: src/providers/openclaw.ts
• Loading: eager (src/providers/index.ts:8)
• Test: tests/providers/openclaw.test.ts

Where it reads from

Four directories, all checked on every run (openclaw.ts):

• ~/.openclaw/agents
• ~/.clawdbot/agents
• ~/.moltbot/agents
• ~/.moldbot/agents

The legacy directories are kept for users who upgraded from older builds.

Storage format

Two eras, discovered side by side under each <agents>/<agent>/ directory:

• SQLite (since the 2026-09-01 migration, 2026.8.1; #1259). agent/openclaw-agent.sqlite, table transcript_events(session_id, seq, event_json, created_at). Each row's event_json is the verbatim JSONL envelope, so both eras run the same event reducer; agent-schema 23 additionally allows a row to carry its event as a event_zstd BLOB instead (one zstd frame, decoded when node:zlib has zstd — Node 22.15+ — and skipped with a notice otherwise). Sessions are listed with a GROUP BY session_id and each parses in keyset batches of 2000 rows so a gigabyte store never loads whole.
• JSONL (pre-migration, still read when present). sessions/sessions.json index plus per-session .jsonl files, with a directory-scan fallback when the index is missing or stale. Post-migration the migration tool moves these to session-sqlite-import-archive/ or renames them *.jsonl.deleted.<ts>, which the .jsonl filter naturally ignores.

The SQLite source path carries the session id after the database path (<db>:<sessionId>, the forge.ts convention), so each session parses — and dedups — on its own.

Caching

None.

Deduplication

Per <sessionId>:<dedupId>, identical keys across both storage eras because the migrated envelopes keep their original session and event ids. An envelope without an event id hashes its payload instead of falling back to its parse position, so the same id-less event hashes identically in either era while distinct ones never collide on an array index.

Store authority

When a session id exists both as a legacy .jsonl file and in the store (a partial migration or a restored backup), discovery keeps only the store's source. Keeping both live would let the legacy file's cached turns suppress the store's first parse — the suppressed (empty) result becomes the store's session-cache entry, and once the legacy file is archived and its entry evicted, the imported history would be gone from every report until the store changed.

Quirks

• Cost is preferred from the provider when reported. OpenClaw emits costUSD in message.usage; the parser uses it directly when present and only computes from tokens when it is missing.
• Tokens are reported across input, output, cacheRead, and cacheWrite. Anthropic semantics throughout, no normalization needed.
• Timestamp fallback chain (SQLite): envelope timestamp → row created_at (ms) → the store file's mtime. The retry on created_at also covers a present-but-unparseable envelope timestamp, which must not land the call on the store's mtime ("now" on a live gateway). The JSONL era uses envelope → file mtime, as before.

When fixing a bug here

1. If the bug is "session not found", check the four legacy dirs first. A user might have a stray ~/.moltbot/ that the parser is reading instead of the real ~/.openclaw/.
2. If the bug is "wrong cost", confirm whether costUSD is present in the source data; the parser trusts it over its own calculation.
3. The sessions.json index can drift when the user crashes mid-session. Make sure the directory-scan fallback triggers in those cases.
4. If a migrated install reports empty, confirm agent/openclaw-agent.sqlite exists and has a transcript_events table; a DB without that table is skipped silently (it is not an agent-schema store).
5. A live OpenClaw gateway keeps writing to the store; the parser opens it read-only per session and closes it when done, and the sqlite wrapper handles -wal sidecars.