工作階段管理深入解析

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• 工作階段路由（傳入訊息如何對應到 sessionKey）
• 工作階段儲存區（sessions.json）以及其追蹤內容
• 轉錄紀錄持久化（*.jsonl）及其結構
• 轉錄紀錄衛生（執行前的供應商特定修正）
• 情境限制（情境視窗與已追蹤權杖）
• Compaction（手動與自動 Compaction）以及要在哪裡掛接 Compaction 前工作
• 靜默內務處理（不應產生使用者可見輸出的記憶寫入）

• 工作階段管理
• Compaction
• 記憶概觀
• 記憶搜尋
• 工作階段修剪
• 轉錄紀錄衛生

​

真實來源：Gateway

• UI（macOS 應用程式、網頁 Control UI、TUI）應向 Gateway 查詢工作階段清單和權杖數。
• 在遠端模式中，工作階段檔案位於遠端主機；「檢查你的本機 Mac 檔案」不會反映 Gateway 正在使用的內容。

​

兩個持久化層

1. 工作階段儲存區（sessions.json）
   • 鍵/值映射：sessionKey -> SessionEntry
   • 小型、可變、可安全編輯（或刪除項目）
   • 追蹤工作階段中繼資料（目前工作階段 ID、最後活動、切換設定、權杖計數器等）
2. 轉錄紀錄（<sessionId>.jsonl）
   • 具有樹狀結構的僅附加轉錄紀錄（項目有 id + parentId）
   • 儲存實際對話 + 工具呼叫 + Compaction 摘要
   • 用於重建未來回合的模型情境
   • 一旦作用中轉錄紀錄超過檢查點大小上限，就會略過大型 Compaction 前除錯檢查點，避免再產生第二個巨大的 .checkpoint.*.jsonl 副本。

​

磁碟位置

• 儲存區：~/.openclaw/agents/<agentId>/sessions/sessions.json
• 轉錄紀錄：~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl
  • Telegram 主題工作階段：.../<sessionId>-topic-<threadId>.jsonl

​

儲存區維護和磁碟控制

• mode：warn（預設）或 enforce
• pruneAfter：過期項目年齡截止值（預設 30d）
• maxEntries：sessions.json 中的項目上限（預設 500）
• resetArchiveRetention：*.reset.<timestamp> 轉錄紀錄封存的保留期限（預設：與 pruneAfter 相同；false 會停用清理）
• maxDiskBytes：選用的工作階段目錄預算
• highWaterBytes：清理後的選用目標（預設為 maxDiskBytes 的 80%）

1. 先移除最舊的已封存、孤立轉錄紀錄或孤立軌跡成品。
2. 如果仍高於目標，逐出最舊的工作階段項目及其轉錄紀錄/軌跡檔案。
3. 持續進行，直到用量等於或低於 highWaterBytes。

openclaw sessions cleanup --dry-run
openclaw sessions cleanup --enforce

​

Cron 工作階段和執行記錄

• cron.sessionRetention（預設 24h）會從工作階段儲存區修剪舊的隔離 Cron 執行工作階段（false 會停用）。
• cron.runLog.maxBytes + cron.runLog.keepLines 會修剪 ~/.openclaw/cron/runs/<jobId>.jsonl 檔案（預設：2_000_000 位元組和 2000 行）。

​

工作階段鍵（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。當每日和閒置兩者都已設定時，先到期者生效。
• 系統事件（Heartbeat、Cron 喚醒、exec 通知、Gateway 簿記）可能會變更工作階段列，但不會延長每日/閒置重設新鮮度。重設輪替會在建立全新提示前，捨棄上一個工作階段的已佇列系統事件通知。
• 父分支分叉政策在建立執行緒或子代理程式分叉時使用 Pi 的作用中分支。如果該分支過大，OpenClaw 會以隔離情境啟動子項，而不是失敗或繼承無法使用的歷史。大小政策是自動的；舊版 session.parentForkMaxTokens 設定會由 openclaw doctor --fix 移除。

​

工作階段儲存區結構描述（sessions.json）

• sessionId：目前的轉錄紀錄 ID（除非已設定 sessionFile，否則檔名由此衍生）
• sessionStartedAt：目前 sessionId 的開始時間戳；每日重設新鮮度使用此欄位。舊版列可能會從 JSONL 工作階段標頭衍生它。
• lastInteractionAt：最後一次真實使用者/頻道互動時間戳；閒置重設新鮮度使用此欄位，因此 Heartbeat、Cron 和 exec 事件不會讓工作階段保持存活。沒有此欄位的舊版列會回退到復原的工作階段開始時間，以用於閒置新鮮度。
• 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：此工作階段鍵的自動 Compaction 完成次數
• memoryFlushAt：上次 Compaction 前記憶排清的時間戳
• memoryFlushCompactionCount：上次排清執行時的 Compaction 計數

​

轉錄紀錄結構（*.jsonl）

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

• message：使用者/助理/toolResult 訊息
• custom_message：由擴充功能注入、_會_進入模型情境的訊息（可從 UI 隱藏）
• custom：_不會_進入模型情境的擴充功能狀態
• compaction：持久化的 Compaction 摘要，含 firstKeptEntryId 和 tokensBefore
• branch_summary：瀏覽樹狀分支時持久化的摘要

​

情境視窗與已追蹤權杖

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

• 情境視窗來自模型目錄（並可透過設定覆寫）。
• 儲存區中的 contextTokens 是執行階段估計/回報值；不要將其視為嚴格保證。

​

Compaction：它是什麼

• Compaction 摘要
• firstKeptEntryId 之後的訊息

​

Compaction 區塊邊界與工具配對

• 如果依 token 比例切分的落點位於工具呼叫與其結果之間，OpenClaw 會將邊界移到 assistant 工具呼叫訊息，而不是拆開這一對。
• 如果尾端的工具結果區塊原本會讓區塊超出目標大小，OpenClaw 會保留該待處理工具區塊，並讓未摘要的尾端保持完整。
• 已中止/錯誤的工具呼叫區塊不會讓待處理切分保持開啟。

​

自動 Compaction 何時發生（Pi runtime）

1. 溢位復原：模型傳回脈絡溢位錯誤 (request_too_large, context length exceeded, input exceeds the maximum number of tokens, input token count exceeds the maximum number of input tokens, input is too long for the model, ollama error: context length exceeded，以及類似的 provider 形式變體) → compact → retry。
2. 閾值維護：在成功完成一輪之後，當：

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

​

Compaction 設定（reserveTokens, keepRecentTokens）

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

• 如果 compaction.reserveTokens < reserveTokensFloor，OpenClaw 會將它提高。
• 預設下限為 20000 token。
• 設定 agents.defaults.compaction.reserveTokensFloor: 0 可停用下限。
• 如果它已經更高，OpenClaw 會保持不變。
• 手動 /compact 會遵守明確的 agents.defaults.compaction.keepRecentTokens 並保留 Pi 的近期尾端切點。若沒有明確的保留預算， 手動 Compaction 仍會是硬性檢查點，重建後的脈絡會從 新摘要開始。
• 設定 agents.defaults.compaction.midTurnPrecheck.enabled: true，可在新工具結果之後、 下一次模型呼叫之前執行選用的工具迴圈預檢。這只是觸發器； 摘要產生仍會使用已設定的 Compaction 路徑。它與 maxActiveTranscriptBytes 無關， 後者是輪次開始時的作用中對話記錄位元組大小防護。
• 將 agents.defaults.compaction.maxActiveTranscriptBytes 設為位元組值或 字串，例如 "20mb"，即可在作用中對話記錄變大時，於輪次開始前執行本機 Compaction。 這個防護只有在也啟用 truncateAfterCompaction 時才會生效。 不設定或設為 0 可停用。
• 啟用 agents.defaults.compaction.truncateAfterCompaction 時， OpenClaw 會在 Compaction 後，將作用中對話記錄輪替為壓縮後的後繼 JSONL。 舊的完整對話記錄會保留封存，並從 Compaction 檢查點連結， 而不是就地重寫。

​

可插拔 Compaction provider

• provider：已註冊 Compaction provider plugin 的 id。不設定則使用預設 LLM 摘要。
• 設定 provider 會強制 mode: "safeguard"。
• Provider 會收到與內建路徑相同的 Compaction 指令與識別碼保留政策。
• safeguard 仍會在 provider 輸出後保留近期輪次與分割輪次的後綴脈絡。
• 內建 safeguard 摘要會以新訊息重新萃煉先前摘要， 而不是逐字保留完整的先前摘要。
• Safeguard 模式預設啟用摘要品質稽核；設定 qualityGuard.enabled: false 可略過輸出格式不正確時重試的行為。
• 如果 provider 失敗或傳回空結果，OpenClaw 會自動退回使用內建 LLM 摘要。
• 中止/逾時訊號會重新拋出（不會吞掉），以尊重呼叫端取消。

​

使用者可見介面

• /status（在任何聊天工作階段中）
• openclaw status (CLI)
• openclaw sessions / sessions --json
• Gateway 記錄（pnpm gateway:watch 或 openclaw logs --follow）：embedded run auto-compaction start + complete
• 詳細模式：🧹 Auto-compaction complete + Compaction 次數

​

靜默內務處理（NO_REPLY）

• assistant 會以精確的靜默 token NO_REPLY / no_reply 開始其輸出，用來表示「不要向使用者傳遞回覆」。
• OpenClaw 會在傳遞層移除/抑制這個內容。
• 精確靜默 token 抑制不區分大小寫，因此當整個 payload 只有該靜默 token 時， NO_REPLY 和 no_reply 都算。
• 這僅適用於真正的背景/不傳遞輪次；它不是一般可執行使用者請求的捷徑。

​

Compaction 前的「記憶體 flush」（已實作）

1. 監控工作階段脈絡用量。
2. 當它跨過「軟閾值」（低於 Pi 的 Compaction 閾值）時，向 agent 執行靜默的 「立即寫入記憶體」指令。
3. 使用精確的靜默 token NO_REPLY / no_reply，讓使用者看不到 任何內容。

• enabled（預設：true）
• model（選用的精確 provider/model 覆寫，用於 flush 輪次，例如 ollama/qwen3:8b）
• softThresholdTokens（預設：4000）
• prompt（flush 輪次的使用者訊息）
• systemPrompt（為 flush 輪次附加的額外 system prompt）

• 預設 prompt/system prompt 包含 NO_REPLY 提示，以抑制 傳遞。
• 設定 model 時，flush 輪次會使用該模型，而不繼承 作用中工作階段 fallback chain，因此本機專用內務處理不會靜默 fallback 到付費對話模型。
• flush 每個 Compaction 週期執行一次（追蹤於 sessions.json）。
• flush 只會針對嵌入式 Pi 工作階段執行（CLI backend 會略過）。
• 當工作階段工作區為唯讀時（workspaceAccess: "ro" 或 "none"），會略過 flush。
• 請參閱 Memory，了解工作區檔案配置與寫入模式。

​

疑難排解檢查清單

• 工作階段 key 錯誤？從 /concepts/session 開始，並確認 /status 中的 sessionKey。
• Store 與對話記錄不一致？從 openclaw status 確認 Gateway host 與 store path。
• Compaction 過於頻繁？檢查：
  • 模型脈絡視窗（太小）
  • Compaction 設定（reserveTokens 對模型視窗而言太高，可能導致更早 Compaction）
  • 工具結果膨脹：啟用/調整工作階段修剪
• 靜默輪次外洩？確認回覆以 NO_REPLY 開頭（不區分大小寫的精確 token），且你使用的是包含串流抑制修正的建置版本。

​

相關

• 工作階段管理
• 工作階段修剪
• 脈絡引擎