​

Quản Lý Phiên & Nén (Khám Phá Sâu)

• Định tuyến phiên (cách các tin nhắn đến được ánh xạ tới sessionKey)
• Lưu trữ phiên (sessions.json) và những gì nó theo dõi
• Lưu trữ bản ghi (*.jsonl) và cấu trúc của nó
• Vệ sinh bản ghi (sửa chữa cụ thể theo nhà cung cấp trước khi chạy)
• Giới hạn ngữ cảnh (cửa sổ ngữ cảnh so với các token được theo dõi)
• Nén (nén thủ công + tự động) và nơi để gắn công việc trước khi nén
• Dọn dẹp im lặng (ví dụ: ghi bộ nhớ mà không tạo ra đầu ra thấy được cho người dùng)

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

​

Nguồn sự thật: Gateway

• Các giao diện người dùng (ứng dụng macOS, giao diện điều khiển web, TUI) nên truy vấn Gateway để lấy danh sách phiên và số lượng token.
• Ở chế độ từ xa, các tệp phiên nằm trên máy chủ từ xa; “kiểm tra các tệp trên máy Mac của bạn” sẽ không phản ánh những gì Gateway đang sử dụng.

​

Hai lớp lưu trữ

1. Lưu trữ phiên (sessions.json)
   • Bản đồ khóa/giá trị: sessionKey -> SessionEntry
   • Nhỏ, có thể chỉnh sửa, an toàn để chỉnh sửa (hoặc xóa các mục)
   • Theo dõi siêu dữ liệu phiên (id phiên hiện tại, hoạt động cuối cùng, chuyển đổi, bộ đếm token, v.v.)
2. Bản ghi (<sessionId>.jsonl)
   • Bản ghi chỉ thêm với cấu trúc cây (các mục có id + parentId)
   • Lưu trữ cuộc trò chuyện thực tế + các cuộc gọi công cụ + tóm tắt nén
   • Dùng để tái tạo ngữ cảnh mô hình cho các lượt tiếp theo

​

Vị trí trên đĩa

• Lưu trữ: ~/.openclaw/agents/<agentId>/sessions/sessions.json
• Bản ghi: ~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl
  • Phiên chủ đề Telegram: .../<sessionId>-topic-<threadId>.jsonl

​

Bảo trì lưu trữ và kiểm soát đĩa

• mode: warn (mặc định) hoặc enforce
• pruneAfter: ngưỡng tuổi mục không hoạt động (mặc định 30d)
• maxEntries: giới hạn số mục trong sessions.json (mặc định 500)
• rotateBytes: xoay sessions.json khi quá kích thước (mặc định 10mb)
• resetArchiveRetention: thời gian lưu trữ cho các bản ghi *.reset.<timestamp> (mặc định: giống pruneAfter; false vô hiệu hóa dọn dẹp)
• maxDiskBytes: ngân sách tùy chọn cho thư mục phiên
• highWaterBytes: mục tiêu tùy chọn sau khi dọn dẹp (mặc định 80% của maxDiskBytes)

1. Xóa các bản ghi lưu trữ hoặc mồ côi cũ nhất trước.
2. Nếu vẫn trên mục tiêu, loại bỏ các mục phiên cũ nhất và các tệp bản ghi của chúng.
3. Tiếp tục cho đến khi sử dụng đạt hoặc dưới highWaterBytes.

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

​

Phiên cron và nhật ký chạy

• cron.sessionRetention (mặc định 24h) loại bỏ các phiên chạy cron cô lập cũ khỏi lưu trữ phiên (false vô hiệu hóa).
• cron.runLog.maxBytes + cron.runLog.keepLines loại bỏ các tệp ~/.openclaw/cron/runs/<jobId>.jsonl (mặc định: 2_000_000 byte và 2000 dòng).

​

Khóa phiên (sessionKey)

• Chat chính/trực tiếp (mỗi agent): agent:<agentId>:<mainKey> (mặc định main)
• Nhóm: agent:<agentId>:<channel>:group:<id>
• Phòng/kênh (Discord/Slack): agent:<agentId>:<channel>:channel:<id> hoặc ...:room:<id>
• Cron: cron:<job.id>
• Webhook: hook:<uuid> (trừ khi bị ghi đè)

​

Id phiên (sessionId)

• Reset (/new, /reset) tạo một sessionId mới cho sessionKey đó.
• Reset hàng ngày (mặc định 4:00 AM giờ địa phương trên máy chủ gateway) tạo một sessionId mới vào tin nhắn tiếp theo sau ranh giới reset.
• Hết hạn không hoạt động (session.reset.idleMinutes hoặc session.idleMinutes cũ) tạo một sessionId mới khi một tin nhắn đến sau cửa sổ không hoạt động. Khi cả hai cấu hình hàng ngày + không hoạt động, cái nào hết hạn trước sẽ thắng.
• Bảo vệ fork cha luồng (session.parentForkMaxTokens, mặc định 100000) bỏ qua fork bản ghi cha khi phiên cha đã quá lớn; luồng mới bắt đầu từ đầu. Đặt 0 để vô hiệu hóa.

​

Schema lưu trữ phiên (sessions.json)

• sessionId: id bản ghi hiện tại (tên tệp được suy ra từ đây trừ khi sessionFile được đặt)
• updatedAt: dấu thời gian hoạt động cuối cùng
• sessionFile: đường dẫn bản ghi rõ ràng tùy chọn
• chatType: direct | group | room (giúp các giao diện người dùng và chính sách gửi)
• provider, subject, room, space, displayName: siêu dữ liệu cho nhãn nhóm/kênh
• Chuyển đổi:
  • thinkingLevel, verboseLevel, reasoningLevel, elevatedLevel
  • sendPolicy (ghi đè theo phiên)
• Lựa chọn mô hình:
  • providerOverride, modelOverride, authProfileOverride
• Bộ đếm token (nỗ lực tốt nhất / phụ thuộc vào nhà cung cấp):
  • inputTokens, outputTokens, totalTokens, contextTokens
• compactionCount: số lần nén tự động hoàn thành cho khóa phiên này
• memoryFlushAt: dấu thời gian cho lần xả bộ nhớ trước khi nén cuối cùng
• memoryFlushCompactionCount: số lần nén khi lần xả cuối cùng chạy

​

Cấu trúc bản ghi (*.jsonl)

• Dòng đầu tiên: tiêu đề phiên (type: "session", bao gồm id, cwd, timestamp, parentSession tùy chọn)
• Sau đó: các mục phiên với id + parentId (cây)

• message: tin nhắn người dùng/trợ lý/kết quả công cụ
• custom_message: tin nhắn được tiêm bởi tiện ích mở rộng mà có vào ngữ cảnh mô hình (có thể bị ẩn khỏi giao diện người dùng)
• custom: trạng thái tiện ích mở rộng mà không vào ngữ cảnh mô hình
• compaction: tóm tắt nén được lưu trữ với firstKeptEntryId và tokensBefore
• branch_summary: tóm tắt được lưu trữ khi điều hướng một nhánh cây

​

Cửa sổ ngữ cảnh so với các token được theo dõi

1. Cửa sổ ngữ cảnh mô hình: giới hạn cứng cho mỗi mô hình (các token thấy được bởi mô hình)
2. Bộ đếm lưu trữ phiên: thống kê cuộn được ghi vào sessions.json (dùng cho /status và bảng điều khiển)

• Cửa sổ ngữ cảnh đến từ danh mục mô hình (và có thể được ghi đè qua cấu hình).
• contextTokens trong lưu trữ là giá trị ước tính/báo cáo thời gian chạy; không coi đó là một đảm bảo nghiêm ngặt.

​

Nén: nó là gì

• Tóm tắt nén
• Tin nhắn sau firstKeptEntryId

​

Khi nào tự động nén xảy ra (Pi runtime)

1. Phục hồi tràn: mô hình trả về lỗi tràn ngữ cảnh → nén → thử lại.
2. Bảo trì ngưỡng: sau một lượt thành công, khi:

• contextWindow là cửa sổ ngữ cảnh của mô hình
• reserveTokens là khoảng trống dành cho các lời nhắc + đầu ra mô hình tiếp theo

​

Cài đặt nén (reserveTokens, keepRecentTokens)

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

• Nếu compaction.reserveTokens < reserveTokensFloor, OpenClaw tăng nó.
• Sàn mặc định là 20000 token.
• Đặt agents.defaults.compaction.reserveTokensFloor: 0 để vô hiệu hóa sàn.
• Nếu nó đã cao hơn, OpenClaw để yên.

​

Bề mặt thấy được cho người dùng

• /status (trong bất kỳ phiên chat nào)
• openclaw status (CLI)
• openclaw sessions / sessions --json
• Chế độ chi tiết: 🧹 Auto-compaction complete + số lần nén

​

Dọn dẹp im lặng (NO_REPLY)

• Trợ lý bắt đầu đầu ra của mình với NO_REPLY để chỉ ra “không gửi trả lời cho người dùng”.
• OpenClaw loại bỏ/ẩn điều này trong lớp phân phối.

​

Xả bộ nhớ trước khi nén (đã triển khai)

1. Giám sát việc sử dụng ngữ cảnh phiên.
2. Khi nó vượt qua một “ngưỡng mềm” (dưới ngưỡng nén của Pi), chạy một chỉ thị “ghi bộ nhớ ngay” im lặng cho agent.
3. Sử dụng NO_REPLY để người dùng không thấy gì.

• enabled (mặc định: true)
• softThresholdTokens (mặc định: 4000)
• prompt (tin nhắn người dùng cho lượt xả)
• systemPrompt (lời nhắc hệ thống bổ sung được thêm vào cho lượt xả)

• Lời nhắc mặc định/lời nhắc hệ thống bao gồm một gợi ý NO_REPLY để ẩn phân phối.
• Xả chạy một lần mỗi chu kỳ nén (được theo dõi trong sessions.json).
• Xả chỉ chạy cho các phiên Pi nhúng (CLI backends bỏ qua nó).
• Xả bị bỏ qua khi không gian làm việc của phiên chỉ đọc (workspaceAccess: "ro" hoặc "none").
• Xem Memory để biết bố cục tệp không gian làm việc và các mẫu ghi.

​

Danh sách kiểm tra khắc phục sự cố

• Khóa phiên sai? Bắt đầu với /concepts/session và xác nhận sessionKey trong /status.
• Lưu trữ so với bản ghi không khớp? Xác nhận máy chủ Gateway và đường dẫn lưu trữ từ openclaw status.
• Nén spam? Kiểm tra:
  • cửa sổ ngữ cảnh mô hình (quá nhỏ)
  • cài đặt nén (reserveTokens quá cao cho cửa sổ mô hình có thể gây ra nén sớm hơn)
  • phình to kết quả công cụ: bật/điều chỉnh cắt tỉa phiên
• Lượt im lặng bị rò rỉ? Xác nhận trả lời bắt đầu với NO_REPLY (token chính xác) và bạn đang ở trên bản dựng bao gồm sửa lỗi ẩn streaming.