​

Session Management & Compaction (Deep Dive)

• 工作階段路由（傳入訊息如何對應到一個 sessionKey）
• 工作階段儲存庫（sessions.json）及其追蹤內容
• Transcript persistence (*.jsonl) and its structure
• 逐字稿衛生（在執行前的提供者特定修正）
• 上下文限制（上下文視窗 vs 追蹤的權杖）
• Compaction (manual + auto-compaction) and where to hook pre-compaction work
• 無聲例行整理（例如不應產生使用者可見輸出的記憶體寫入）

• /concepts/session
• /concepts/compaction
• /concepts/session-pruning
• /reference/transcript-hygiene

​

Source of truth: the Gateway

• UI（macOS app、Web Control UI、TUI）應向 Gateway 閘道器查詢工作階段清單與權杖計數。
• 在遠端模式下，工作階段檔案位於遠端主機；「檢查你本機 Mac 的檔案」不會反映 Gateway 閘道器實際使用的內容。

​

兩層持久化

1. 工作階段儲存庫（sessions.json）
   • 鍵／值對映：sessionKey -> SessionEntry
   • 小型、可變更、可安全編輯（或刪除項目）
   • Tracks session metadata (current session id, last activity, toggles, token counters, etc.)
2. 逐字稿（<sessionId>.jsonl）
   • 具有樹狀結構的附加寫入逐字稿（項目具有 id + parentId）
   • 儲存實際對話 + 工具呼叫 + 壓縮摘要
   • 用於重建未來回合的模型上下文

​

磁碟上的位置

• 儲存庫：~/.openclaw/agents/<agentId>/sessions/sessions.json
• 逐字稿：~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl
  • Telegram 主題工作階段：.../<sessionId>-topic-<threadId>.jsonl

​

工作階段金鑰（sessionKey）

• 主要／直接聊天（每個代理程式）：agent:<agentId>:<mainKey>（預設 main）
• 群組：agent:<agentId>:<channel>:group:<id>
• 房間／頻道（Discord／Slack）：agent:<agentId>:<channel>:channel:<id> 或 ...:room:<id>
• Cron：cron:<job.id>
• Webhook：hook:<uuid>（除非被覆寫）

​

工作階段 ID（sessionId）

• 重設（/new、/reset）會為該 sessionKey 建立新的 sessionId。
• 每日重設（預設為 Gateway 閘道器主機的當地時間凌晨 4:00）會在重設邊界後的下一則訊息建立新的 sessionId。
• 閒置到期（session.reset.idleMinutes 或舊版 session.idleMinutes）在超過閒置視窗後收到訊息時建立新的 sessionId。若同時設定每日 + 閒置，以先到期者為準。 When daily + idle are both configured, whichever expires first wins. When daily + idle are both configured, whichever expires first wins.

​

Session store schema (sessions.json)

• sessionId：目前逐字稿 ID（除非設定 sessionFile，否則檔名由此衍生）
• updatedAt：最後活動時間戳
• sessionFile：可選的逐字稿路徑覆寫
• chatType：direct | group | room（協助 UI 與傳送政策）
• provider、subject、room、space、displayName：群組／頻道標示的中繼資料
• 切換開關：
  • thinkingLevel、verboseLevel、reasoningLevel、elevatedLevel
  • sendPolicy（每個工作階段的覆寫）
• 模型選擇：
  • providerOverride、modelOverride、authProfileOverride
• 權杖計數器（盡力而為／依提供者而異）：
  • inputTokens、outputTokens、totalTokens、contextTokens
• compactionCount：此工作階段金鑰完成自動壓縮的次數
• memoryFlushAt：上一次壓縮前記憶體寫入的時間戳
• memoryFlushCompactionCount：上一次寫入執行時的壓縮計數

​

Transcript structure (*.jsonl)

• 第一行：工作階段標頭（type: "session"，包含 id、cwd、timestamp，以及可選的 parentSession）
• 接著：具有 id + parentId（樹狀）的工作階段項目

• message：使用者／助理／toolResult 訊息
• custom_message：由擴充注入、會進入模型上下文的訊息（可在 UI 中隱藏）
• custom：不會進入模型上下文的擴充狀態
• compaction：具有 firstKeptEntryId 與 tokensBefore 的持久化壓縮摘要
• branch_summary：在樹分支導覽時的持久化摘要

​

上下文視窗 vs 追蹤的權杖

1. 模型上下文視窗：每個模型的硬性上限（模型可見的權杖）
2. 工作階段儲存庫計數器：寫入 sessions.json 的滾動統計（用於 /status 與儀表板）

• 上下文視窗來自模型目錄（並且可透過設定覆寫）。
• 儲存庫中的 contextTokens 是執行時估計／回報值；不要把它當成嚴格保證。

​

壓縮：它是什麼

• 壓縮摘要
• firstKeptEntryId 之後的訊息

​

When auto-compaction happens (Pi runtime)

1. 溢位復原：模型回傳上下文溢位錯誤 → 壓縮 → 重試。
2. 閾值維護：成功完成一個回合後，當：

• contextWindow 是模型的上下文視窗
• reserveTokens 是為提示詞 + 下一次模型輸出保留的餘裕

​

壓縮設定（reserveTokens、keepRecentTokens）

{
  compaction: {
    enabled: true,
    reserveTokens: 16384,
    keepRecentTokens: 20000,
  },
}

• 若 compaction.reserveTokens < reserveTokensFloor，OpenClaw 會提高它。
• Default floor is 20000 tokens.
• 設定 agents.defaults.compaction.reserveTokensFloor: 0 可停用下限。
• 若原本已更高，OpenClaw 會維持不變。

​

使用者可見的介面

• /status（任何聊天工作階段中）
• openclaw status（CLI）
• openclaw sessions / sessions --json
• 詳細模式：🧹 Auto-compaction complete + 壓縮次數

​

Silent housekeeping (NO_REPLY)

• 助理以 NO_REPLY 開頭輸出，表示「不要將回覆傳遞給使用者」。
• OpenClaw strips/suppresses this in the delivery layer.

​

Pre-compaction “memory flush” (implemented)

1. 監控工作階段上下文使用量。
2. 當超過「軟性閾值」（低於 Pi 的壓縮閾值）時，對代理程式執行一次無聲的 「立即寫入記憶體」指令。
3. 使用 NO_REPLY，讓使用者看不到任何輸出。

• enabled（預設：true）
• softThresholdTokens（預設：4000）
• prompt（寫入回合的使用者訊息）
• systemPrompt（附加於寫入回合的額外系統提示）

• 預設的提示／系統提示包含 NO_REPLY 提示以抑制傳遞。
• 清空操作在每個壓縮週期中只會執行一次（記錄於 sessions.json）。
• 僅對內嵌 Pi 工作階段執行（CLI 後端會略過）。
• The flush is skipped when the session workspace is read-only (workspaceAccess: "ro" or "none").
• See Memory for the workspace file layout and write patterns.

​

疑難排解檢查清單

• 11. 工作階段金鑰錯誤？ 工作階段金鑰錯誤？先從 /concepts/session 開始，並確認 /status 中的 sessionKey。
• 儲存區與逐字稿不一致？ 儲存區與逐字稿不一致？ Confirm the Gateway host and the store path from openclaw status.
• Compaction spam? 檢查：
  • 模型上下文視窗（是否過小）
  • 壓縮設定（reserveTokens 對模型視窗而言過高，可能導致提早壓縮）
  • 工具結果膨脹：啟用／調整工作階段修剪
• Silent turns leaking? 確認回覆以 NO_REPLY（完全相同的權杖）開頭，且你正在使用包含串流抑制修復的版本。