English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Sessions and memory

工作階段管理

OpenClaw 會將對話組織成工作階段。每則訊息都會根據來源路由到某個工作階段 -- 私訊、群組聊天、cron 工作等。

訊息如何路由

來源 行為
直接訊息 預設共用工作階段
群組聊天 依群組隔離
房間/頻道 依房間隔離
Cron 工作 每次執行使用新的工作階段
Webhook 依 hook 隔離

DM 隔離

預設情況下，所有 DM 會共用一個工作階段以保持連續性。這適合單一使用者設定。

修正方式：

{
  session: {
    dmScope: "per-channel-peer", // isolate by channel + sender
  },
}

其他選項：

  • main（預設）-- 所有 DM 共用一個工作階段。
  • per-peer -- 依傳送者隔離（跨頻道）。
  • per-channel-peer -- 依頻道 + 傳送者隔離（建議）。
  • per-account-channel-peer -- 依帳號 + 頻道 + 傳送者隔離。

停駐已連結頻道

Dock 命令可讓使用者將目前直接聊天工作階段的回覆路由移至另一個已連結頻道，而不必開始新的工作階段。請參閱頻道停駐以取得範例、設定與疑難排解。

使用 openclaw security audit 驗證你的設定。

工作階段生命週期

工作階段會重複使用，直到過期：

  • 每日重設（預設）-- Gateway 主機本機時間凌晨 4:00 建立新的工作階段。每日新鮮度以目前 sessionId 開始的時間為準，而不是之後的中繼資料寫入時間。
  • 閒置重設（選用）-- 在一段時間未活動後建立新的工作階段。設定 session.reset.idleMinutes。閒置新鮮度以最後一次真實的使用者/頻道互動為準，因此 Heartbeat、cron 和 exec 系統事件不會讓工作階段保持存活。
  • 手動重設 -- 在聊天中輸入 /new 或 /reset。/new <model> 也會切換模型。

同時設定每日與閒置重設時，先過期者生效。Heartbeat、cron、exec 和其他系統事件回合可能會寫入工作階段中繼資料，但這些寫入不會延長每日或閒置重設的新鮮度。當重設切換工作階段時，舊工作階段中佇列的系統事件通知會被捨棄，避免過期的背景更新被前置到新工作階段的第一個提示。

具有作用中供應商擁有之 CLI 工作階段的工作階段，不會被隱含的每日預設切斷。當這些工作階段應依計時器過期時，請使用 /reset 或明確設定 session.reset。

狀態存放位置

所有工作階段狀態都由 Gateway 擁有。UI 用戶端會查詢 Gateway 以取得工作階段資料。

  • 儲存區： ~/.openclaw/agents/<agentId>/sessions/sessions.json
  • 逐字稿： ~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl

sessions.json 會保留不同的生命週期時間戳記：

  • sessionStartedAt：目前 sessionId 開始的時間；每日重設使用此值。
  • lastInteractionAt：最後一次會延長閒置存續時間的使用者/頻道互動。
  • updatedAt：最後一次儲存區資料列變更；對列出和修剪很有用，但不是每日/閒置重設新鮮度的權威依據。

沒有 sessionStartedAt 的舊資料列，會在可用時從逐字稿 JSONL 工作階段標頭解析。如果舊資料列也缺少 lastInteractionAt，閒置新鮮度會回退到該工作階段開始時間，而不是之後的簿記寫入時間。

工作階段維護

OpenClaw 會隨時間自動限制工作階段儲存空間。預設會以 warn 模式執行（回報哪些內容會被清理）。將 session.maintenance.mode 設為 "enforce" 以進行自動清理：

{
  session: {
    maintenance: {
      mode: "enforce",
      pruneAfter: "30d",
      maxEntries: 500,
    },
  },
}

對於生產規模的 maxEntries 限制，Gateway 執行階段寫入會使用小型高水位緩衝區，並分批清理回設定的上限。工作階段儲存區讀取不會在 Gateway 啟動期間修剪或限制項目數。這可避免每次啟動或隔離的 cron 工作階段都執行完整儲存區清理。openclaw sessions cleanup --enforce 會立即套用上限。

維護作業會保留持久的外部對話指標，包括群組工作階段和執行緒範圍的聊天工作階段，同時仍允許合成的 cron、hook、heartbeat、ACP 和子代理項目逐漸過期。

如果你先前使用過直接訊息隔離，後來又將 session.dmScope 改回 main，可使用 openclaw sessions cleanup --dry-run --fix-dm-scope 預覽過時的依 peer 設鍵 DM 資料列。套用相同旗標會淘汰這些舊的直接 DM 資料列，並將其逐字稿保留為已刪除封存。

使用 openclaw sessions cleanup --dry-run 預覽。

檢查工作階段

  • openclaw status -- 工作階段儲存區路徑與近期活動。
  • openclaw sessions --json -- 所有工作階段（使用 --active <minutes> 篩選）。
  • 聊天中的 /status -- 脈絡使用量、模型與切換項。
  • /context list -- 系統提示中的內容。

延伸閱讀

相關