​

Quản lý phiên & Nén (Chuyên sâu)

• Định tuyến phiên (cách thông điệp đến được ánh xạ tới một sessionKey)
• Kho phiên (sessions.json) và những gì nó theo dõi
• Lưu trữ bản ghi hội thoại (*.jsonl) và cấu trúc của nó
• Vệ sinh bản ghi hội thoại (các chỉnh sửa 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 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ớ không nên tạo đầu ra hiển thị cho người dùng)

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

​

Nguồn sự thật: Gateway

• Các UI (ứng dụng macOS, Control UI 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 Mac cục bộ” sẽ không phản ánh những gì Gateway đang dùng.

​

Hai lớp lưu trữ

1. Kho phiên (sessions.json)
   • Ánh xạ khóa/giá trị: sessionKey -> SessionEntry
   • Nhỏ, có thể thay đổi, an toàn để chỉnh sửa (hoặc xóa mục)
   • Theo dõi metadata của phiên (session id hiện tại, hoạt động gần nhất, các toggle, bộ đếm token, v.v.)
2. Bản ghi hội thoại (<sessionId>.jsonl)
   • Bản ghi chỉ-ghi-nối 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ế + lời gọi công cụ + tóm tắt nén
   • Dùng để tái dựng ngữ cảnh mô hình cho các lượt sau

​

Vị trí trên đĩa

• Kho: ~/.openclaw/agents/<agentId>/sessions/sessions.json
• Bản ghi hội thoại: ~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl
  • Phiên theo chủ đề Telegram: .../<sessionId>-topic-<threadId>.jsonl

​

Khóa phiên (sessionKey)

• Chat chính/trực tiếp (theo từng tác tử): 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 đè)

​

Session id (sessionId)

• Reset (/new, /reset) tạo một sessionId mới cho sessionKey đó.
• Reset hằng ngày (mặc định 4:00 sáng theo giờ địa phương trên máy chủ gateway) tạo một sessionId mới ở thông điệp kế tiếp sau mốc reset.
• Hết hạn khi nhàn rỗi (session.reset.idleMinutes hoặc legacy session.idleMinutes) tạo một sessionId mới khi một tin nhắn đến sau cửa sổ nhàn rỗi. Khi cả daily + idle đều được cấu hình, cái nào hết hạn trước sẽ được ưu tiên.

​

Lược đồ kho phiên (sessions.json)

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

​

Cấu trúc bản ghi hội thoại (*.jsonl)

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

• message: thông điệp user/assistant/toolResult
• custom_message: thông điệp do extension chèn có đi vào ngữ cảnh mô hình (có thể ẩn khỏi UI)
• custom: trạng thái extension không đi vào ngữ cảnh mô hình
• compaction: tóm tắt nén được lưu với firstKeptEntryId và tokensBefore
• branch_summary: tóm tắt được lưu khi điều hướng một nhánh cây

​

Cửa sổ ngữ cảnh vs token được theo dõi

1. Cửa sổ ngữ cảnh của mô hình: giới hạn cứng theo từng mô hình (token nhìn thấy bởi mô hình)
2. Bộ đếm trong kho phiên: thống kê cuộn được ghi vào sessions.json (dùng cho /status và dashboard)

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

​

Nén: là gì

• Tóm tắt nén
• Các thông điệp sau firstKeptEntryId

32. Khóa phiên sai? 33. Bắt đầu với /concepts/session và xác nhận sessionKey trong /status.

​

Khi nào tự động nén diễn ra (runtime Pi)

1. Khôi phục tràn: mô hình trả lỗi tràn ngữ cảnh → nén → thử lại.
2. Bảo trì theo 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à phần đệm dành cho prompt + đầu ra mô hình kế tiếp

​

Thiết lập nén (reserveTokens, keepRecentTokens)

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

• Nếu compaction.reserveTokens < reserveTokensFloor, OpenClaw sẽ nâng lên.
• Mức sàn mặc định là 20000 token.
• Đặt agents.defaults.compaction.reserveTokensFloor: 0 để tắt mức sàn.
• Nếu đã cao hơn, OpenClaw giữ nguyên.

​

Bề mặt hiển thị cho người dùng

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

​

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

• Assistant bắt đầu đầu ra bằng NO_REPLY để báo “không gửi phản hồi cho người dùng”.
• OpenClaw loại bỏ/ẩn điều này ở lớp phân phối.

​

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

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

• enabled (mặc định: true)
• softThresholdTokens (mặc định: 4000)
• prompt (thông điệp người dùng cho lượt xả)
• systemPrompt (system prompt bổ sung được nối cho lượt xả)

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

​

Danh sách kiểm tra xử lý sự cố

• Session key sai? Bắt đầu với /concepts/session và xác nhận sessionKey trong /status.
• Lệch giữa store và transcript? 37. Kiểm tra:
• Spam nén? 39. Xác nhận phản hồi bắt đầu bằng NO_REPLY (token chính xác) và bạn đang dùng bản build có bao gồm bản sửa ức chế streaming.
  • cửa sổ ngữ cảnh mô hình (quá nhỏ)
  • thiết lập nén (reserveTokens quá cao so với cửa sổ mô hình có thể gây nén sớm)
  • phình to tool-result: bật/điều chỉnh cắt tỉa phiên
• 40. “Xin chào, C-3PO! Xác nhận phản hồi bắt đầu bằng NO_REPLY (token chính xác) và bạn đang ở bản build bao gồm bản sửa lỗi chặn streaming.