工作階段管理深入解析

Documentation Index

Fetch the complete documentation index at: https://docs.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 應用程式、網頁控制 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 喚醒、執行通知、Gateway 簿記）可能會變更工作階段列，但不會延長每日/閒置重設的新鮮度。重設輪替會在建立新提示前捨棄前一個工作階段的佇列中系統事件通知。
• 執行緒父項分叉保護（session.parentForkMaxTokens，預設 100000）會在父工作階段已經過大時略過父逐字稿分叉；新執行緒會重新開始。設定為 0 可停用。

​

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

• sessionId：目前逐字稿 ID（除非設定了 sessionFile，否則檔名會由此衍生）
• sessionStartedAt：目前 sessionId 的開始時間戳；每日重設新鮮度使用此欄位。舊版列可能會從 JSONL 工作階段標頭衍生它。
• lastInteractionAt：最後一次真實使用者/頻道互動時間戳；閒置重設新鮮度使用此欄位，因此 Heartbeat、Cron 和執行事件不會讓工作階段保持存活。沒有此欄位的舊版列會退回使用復原的工作階段開始時間作為閒置新鮮度。
• 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：使用者/助理/工具結果訊息
• custom_message：由擴充注入且_會_進入模型上下文的訊息（可在 UI 中隱藏）
• custom：_不會_進入模型上下文的擴充狀態
• compaction：持久化的 Compaction 摘要，帶有 firstKeptEntryId 和 tokensBefore
• branch_summary：瀏覽樹狀分支時持久化的摘要

​

上下文視窗與已追蹤權杖

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

• 上下文視窗來自模型目錄（且可透過設定覆寫）。
• 儲存區中的 contextTokens 是執行階段估算/報告值；不要把它視為嚴格保證。

​

Compaction：它是什麼

• Compaction 摘要
• firstKeptEntryId 之後的訊息

​

Compaction 區塊邊界和工具配對

• 如果權杖占比拆分落在工具呼叫與其結果之間，OpenClaw 會將邊界移到助理工具呼叫訊息，而不是分開該配對。
• 如果尾端工具結果區塊原本會讓區塊超過目標，OpenClaw 會保留該待處理工具區塊，並保持未摘要尾端完整。
• 已中止/錯誤的工具呼叫區塊不會讓待處理拆分保持開啟。

​

自動 Compaction 發生時機（Pi 執行階段）

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，以及類似的提供者形式變體）→ 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.maxActiveTranscriptBytes 設為位元組值或 字串，例如 "20mb"，即可在作用中的逐字稿變大時於回合前執行本機 Compaction。 這個防護只有在也啟用 truncateAfterCompaction 時才會生效。保持未設定或設為 0 即可 停用。
• 啟用 agents.defaults.compaction.truncateAfterCompaction 時， OpenClaw 會在 Compaction 後將作用中的逐字稿輪替為壓縮後的後續 JSONL。 舊的完整逐字稿會保留封存，並從 Compaction 檢查點連結，而不是就地重寫。

​

可插拔的 Compaction 提供者

• provider：已註冊 Compaction 提供者 Plugin 的 ID。保持未設定即可使用預設 LLM 摘要。
• 設定 provider 會強制 mode: "safeguard"。
• 提供者會收到與內建路徑相同的 Compaction 指示與識別碼保留政策。
• 防護在提供者輸出後仍會保留近期回合與分割回合的後綴上下文。
• 內建防護摘要會使用新訊息重新萃取既有摘要， 而不是逐字保留完整的先前摘要。
• 防護模式預設會啟用摘要品質稽核；設定 qualityGuard.enabled: false 可略過輸出格式錯誤時重試的行為。
• 如果提供者失敗或傳回空結果，OpenClaw 會自動退回使用內建 LLM 摘要。
• Abort/timeout 訊號會被重新擲出（不會被吞掉），以尊重呼叫端取消。

​

使用者可見介面

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

​

靜默內務處理（NO_REPLY）

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

​

Compaction 前「記憶清空」（已實作）

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

• enabled（預設：true）
• model（可選的精確提供者/模型覆寫，用於清空回合，例如 ollama/qwen3:8b）
• softThresholdTokens（預設：4000）
• prompt（清空回合的使用者訊息）
• systemPrompt（附加到清空回合的額外系統提示）

• 預設提示/系統提示包含 NO_REPLY 提示，以抑制 遞送。
• 設定 model 時，清空回合會使用該模型，而不繼承 作用中工作階段的後備鏈，因此僅限本機的內務處理不會靜默地 退回使用付費對話模型。
• 每個 Compaction 週期只會執行一次清空（追蹤於 sessions.json）。
• 清空只會針對嵌入式 Pi 工作階段執行（CLI 後端會略過）。
• 當工作階段工作區是唯讀時（workspaceAccess: "ro" 或 "none"），會略過清空。
• 請參閱 Memory 了解工作區檔案配置與寫入模式。

​

疑難排解檢查清單

• 工作階段金鑰錯誤？從 /concepts/session 開始，並確認 /status 中的 sessionKey。
• 儲存區與逐字稿不相符？從 openclaw status 確認 Gateway 主機與儲存區路徑。
• Compaction 垃圾訊息過多？檢查：
  • 模型上下文視窗（太小）
  • Compaction 設定（reserveTokens 對模型視窗而言過高，可能導致更早 Compaction）
  • 工具結果膨脹：啟用/調整工作階段修剪
• 靜默回合外洩？確認回覆以 NO_REPLY 開頭（不區分大小寫的精確 token），並且你使用的建置包含串流抑制修正。

​

相關

• 工作階段管理
• 工作階段修剪
• 上下文引擎