session-logs

session-logs

搜尋儲存在對話 JSONL 檔案中的完整對話歷史。當使用者提及較舊/上層對話或詢問之前說過什麼時使用此技能。

觸發時機

當使用者詢問先前的聊天、上層對話或不在記憶檔案中的歷史脈絡時，使用此技能。

位置

對話記錄位於作用中狀態目錄下：
$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/（預設：~/.openclaw/agents/<agentId>/sessions/）。
使用系統提示 Runtime 行中的 agent=<id> 值。

• sessions.json - 索引，將對話金鑰對應到對話 ID
• <session-id>.jsonl - 每個對話的完整對話記錄
• <session-id>.jsonl.reset.<timestamp>Z - 由 /new 或 /reset 歸檔的記錄
• <session-id>.jsonl.deleted.<timestamp>Z - 對話刪除時歸檔的記錄

搜尋歷史時，也請包含已歸檔的變體（.reset.*、.deleted.*）——它們
仍然包含真實的對話內容。下方的純 glob 範例只會抓到作用中的
*.jsonl 檔案；當你需要完整回憶時，請使用「包含已歸檔記錄」的程式碼片段。

結構

每個 .jsonl 檔案包含帶有以下欄位的訊息：

• type："session"（中繼資料）或 "message"
• timestamp：ISO 時間戳
• message.role："user"、"assistant" 或 "toolResult"
• message.content[]：文字、思考過程或工具呼叫（過濾 type=="text" 以取得人類可讀內容）
• message.usage.cost.total：每次回應的成本

常見查詢

包含已歸檔記錄（.reset.*、.deleted.*）

# Bash 輔助函式，輸出每個可搜尋的記錄路徑——包含作用中與已歸檔。
# 在區域內儲存並還原 `nullglob`，以免影響呼叫者的 shell 選項。
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"
}

如果你需要包含已歸檔的對話，請在下方顯示純 *.jsonl glob 的地方使用
list_session_transcripts（或等效的 find 呼叫）：

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

依日期與大小列出所有對話

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

提示： 當你也想在清單中包含已歸檔的 .reset / .deleted 檔案時，
將 for f in ... 行替換為對 list_session_transcripts 的 while-read 迴圈
（請見上方程式碼片段）。while-read 模式對於包含空格或其他 IFS 字元的路徑是安全的：

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

尋找特定日期的對話

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

從對話中擷取使用者訊息

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

在助理回應中搜尋關鍵字

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

取得對話的總成本

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

每日成本摘要

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

計算對話中的訊息數與 token 數

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

工具使用分析

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

在所有對話中搜尋某個詞組

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

# 僅作用中對話：
rg -l "phrase" "$SESSION_DIR"/*.jsonl

# 作用中 + 已歸檔（`.reset.*`、`.deleted.*`）——在檢查可能已被壓縮/重設/刪除的內容時使用：
rg -l "phrase" "$SESSION_DIR"/*.jsonl \
               "$SESSION_DIR"/*.jsonl.reset.*Z \
               "$SESSION_DIR"/*.jsonl.deleted.*Z 2>/dev/null

提示

• 對話是附加唯讀的 JSONL（每行一個 JSON 物件）
• 大型對話可能達數 MB——使用 head/tail 進行取樣
• sessions.json 索引將聊天提供者（discord、whatsapp 等）對應到對話 ID
• 重設/壓縮的對話 帶有 .jsonl.reset.<timestamp>Z 後綴——仍然包含
  完整記錄且可搜尋。
• 已刪除的對話 帶有 .jsonl.deleted.<timestamp>Z 後綴——也仍然可搜尋。
• 純 *.jsonl glob 會 遺漏 這兩種歸檔形式。當你需要完整歷史時，
  請明確包含它們（請見上方的「包含已歸檔記錄」程式碼片段）。

快速純文字提示（低雜訊）

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 'keyword'