session-logs

Sitzungsprotokolle

Durchsuche deinen vollständigen Konversationsverlauf, der in Sitzungs-JSONL-Dateien gespeichert ist. Verwende diese Fähigkeit, wenn ein Benutzer sich auf ältere/übergeordnete Konversationen bezieht oder fragt, was zuvor gesagt wurde.

Auslöser

Verwende diese Fähigkeit, wenn der Benutzer nach früheren Chats, übergeordneten Konversationen oder historischem Kontext fragt, der nicht in Speicherdateien vorhanden ist.

Speicherort

Sitzungsprotokolle befinden sich im aktiven Zustandsverzeichnis: $OPENCLAW_STATE_DIR/agents/<agentId>/sessions/ (Standard: ~/.openclaw/agents/<agentId>/sessions/). Verwende den Wert agent=<id> aus der Runtime-Zeile des System-Prompts.

• sessions.json – Index, der Sitzungsschlüssel auf Sitzungs-IDs abbildet
• <session-id>.jsonl – Vollständiges Gesprächstranskript pro Sitzung
• <session-id>.jsonl.reset.<timestamp>Z – Transkript, das durch /new oder /reset archiviert wurde
• <session-id>.jsonl.deleted.<timestamp>Z – Transkript, das archiviert wurde, als eine Sitzung gelöscht wurde

Wenn du im Verlauf suchst, beziehe auch die archivierten Varianten (.reset.*, .deleted.*) mit ein – sie enthalten immer noch echten Gesprächsinhalt. Die unten gezeigten einfachen Glob-Beispiele erfassen nur die aktiven *.jsonl-Dateien; verwende das Code-Snippet „Archivierte Transkripte einbeziehen“, wenn du eine vollständige Rückverfolgung benötigst.

Struktur

Jede .jsonl-Datei enthält Nachrichten mit:

• type: „session“ (Metadaten) oder „message“
• timestamp: ISO-Zeitstempel
• message.role: „user“, „assistant“ oder „toolResult“
• message.content[]: Text, Gedanken oder Tool-Aufrufe (filtere type=="text" für menschenlesbaren Inhalt)
• message.usage.cost.total: Kosten pro Antwort

Häufige Abfragen

Archivierte Transkripte einbeziehen (.reset.*, .deleted.*)

# Bash-Helfer, der jeden durchsuchbaren Transkriptpfad ausgibt – aktiv und archiviert.
# Speichert und stellt `nullglob` lokal wieder her, damit die Shell-Optionen des Aufrufers nicht beeinträchtigt werden.
AGENT_ID="<agentId>"
SESSION_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/agents/$AGENT_ID/sessions"
list_session_transcripts() {
  local _nullglob_state
  _nullglob_state=$(shopt -p nullglob 2>/dev/null)
  shopt -s nullglob
  for f in "$SESSION_DIR"/*.jsonl \
           "$SESSION_DIR"/*.jsonl.reset.*Z \
           "$SESSION_DIR"/*.jsonl.deleted.*Z; do
    [ -f "$f" ] && printf '%s\n' "$f"
  done
  eval "$_nullglob_state"
}

Verwende list_session_transcripts (oder einen entsprechenden find-Aufruf) anstelle des einfachen *.jsonl-Globs, der unten gezeigt wird, wenn du archivierte Sitzungen einbeziehen möchtest:

find "$SESSION_DIR" -maxdepth 1 -type f \
  \( -name '*.jsonl' -o -name '*.jsonl.reset.*Z' -o -name '*.jsonl.deleted.*Z' \) -print

Alle Sitzungen nach Datum und Größe auflisten

AGENT_ID="<agentId>"
SESSION_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/agents/$AGENT_ID/sessions"
for f in "$SESSION_DIR"/*.jsonl; do
  date=$(head -1 "$f" | jq -r '.timestamp' | cut -dT -f1)
  size=$(ls -lh "$f" | awk '{print $5}')
  echo "$date $size $(basename $f)"
done | sort -r

Tipp: Ersetze die for f in ...-Zeile durch eine while-read-Schleife über list_session_transcripts (siehe Code-Snippet oben), wenn du auch archivierte .reset- / .deleted-Dateien in der Auflistung haben möchtest. Das while-read-Muster ist sicher für Pfade mit Leerzeichen oder anderen IFS-Zeichen:

while IFS= read -r f; do
  date=$(head -1 "$f" | jq -r '.timestamp' | cut -dT -f1)
  size=$(ls -lh "$f" | awk '{print $5}')
  echo "$date $size $(basename "$f")"
done < <(list_session_transcripts) | sort -r

Sitzungen von einem bestimmten Tag finden

AGENT_ID="<agentId>"
SESSION_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/agents/$AGENT_ID/sessions"
for f in "$SESSION_DIR"/*.jsonl; do
  head -1 "$f" | jq -r '.timestamp' | grep -q "2026-01-06" && echo "$f"
done

Benutzernachrichten aus einer Sitzung extrahieren

jq -r 'select(.message.role == "user") | .message.content[]? | select(.type == "text") | .text' <sitzung>.jsonl

Nach Schlüsselwort in Assistentenantworten suchen

jq -r 'select(.message.role == "assistant") | .message.content[]? | select(.type == "text") | .text' <sitzung>.jsonl | rg -i "schlüsselwort"

Gesamtkosten für eine Sitzung abrufen

jq -s '[.[] | .message.usage.cost.total // 0] | add' <sitzung>.jsonl

Tägliche Kostenübersicht

AGENT_ID="<agentId>"
SESSION_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/agents/$AGENT_ID/sessions"
for f in "$SESSION_DIR"/*.jsonl; do
  date=$(head -1 "$f" | jq -r '.timestamp' | cut -dT -f1)
  cost=$(jq -s '[.[] | .message.usage.cost.total // 0] | add' "$f")
  echo "$date $cost"
done | awk '{a[$1]+=$2} END {for(d in a) print d, "$"a[d]}' | sort -r

Nachrichten und Token in einer Sitzung zählen

jq -s '{
  messages: length,
  user: [.[] | select(.message.role == "user")] | length,
  assistant: [.[] | select(.message.role == "assistant")] | length,
  first: .[0].timestamp,
  last: .[-1].timestamp
}' <sitzung>.jsonl

Aufschlüsselung der Tool-Nutzung

jq -r '.message.content[]? | select(.type == "toolCall") | .name' <sitzung>.jsonl | sort | uniq -c | sort -rn

Suche in ALLEN Sitzungen nach einem Begriff

AGENT_ID="<agentId>"
SESSION_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/agents/$AGENT_ID/sessions"

# Nur aktive Sitzungen:
rg -l "begriff" "$SESSION_DIR"/*.jsonl

# Aktive + archivierte (`.reset.*`, `.deleted.*`) – verwende dies, wenn du nach
# Inhalten suchst, die möglicherweise komprimiert/zurückgesetzt/gelöscht wurden:
rg -l "begriff" "$SESSION_DIR"/*.jsonl \
               "$SESSION_DIR"/*.jsonl.reset.*Z \
               "$SESSION_DIR"/*.jsonl.deleted.*Z 2>/dev/null

Tipps

• Sitzungen sind Append-Only-JSONL (ein JSON-Objekt pro Zeile)
• Große Sitzungen können mehrere MB groß sein – verwende head/tail zum Stichprobenziehen
• Der Index sessions.json bildet Chat-Anbieter (discord, whatsapp usw.) auf Sitzungs-IDs ab
• Zurückgesetzte/komprimierte Sitzungen haben das Suffix .jsonl.reset.<timestamp>Z – enthalten immer noch vollständige Transkripte und sind durchsuchbar.
• Gelöschte Sitzungen haben das Suffix .jsonl.deleted.<timestamp>Z – ebenfalls noch durchsuchbar.
• Ein einfacher *.jsonl-Glob übersieht beide archivierten Formen. Beziehe sie explizit ein (siehe Code-Snippet „Archivierte Transkripte einbeziehen“ oben), wenn du die vollständige Historie benötigst.

Schneller Text-only-Hinweis (weniger Rauschen)

AGENT_ID="<agentId>"
SESSION_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/agents/$AGENT_ID/sessions"
jq -r 'select(.type=="message") | .message.content[]? | select(.type=="text") | .text' "$SESSION_DIR"/<id>.jsonl | rg 'schlüsselwort'