Phân tích chuyên sâu về quản lý phiên

• Định tuyến phiên (cách tin nhắn đến ánh xạ tới một sessionKey)
• Kho phiên (sessions.json) và những gì nó theo dõi
• Lưu bền 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 riêng 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)
• Compaction (Compaction thủ công và tự động) và nơi gắn công việc trước Compaction
• Dọn dẹp âm thầm (các lần ghi bộ nhớ không nên tạo đầu ra hiển thị cho người dùng)

• Quản lý phiên
• Compaction
• Tổng quan bộ nhớ
• Tìm kiếm bộ nhớ
• Cắt tỉa phiên
• Vệ sinh bản ghi hội thoại

​

Nguồn chân lý: Gateway

• Các giao diện người dùng (ứ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 cục bộ trên Mac của bạn” sẽ không phản ánh những gì Gateway đang sử dụng.

​

Hai lớp lưu bền

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 siêu dữ liệu phiên (id phiên hiện tại, hoạt động gần nhất, các nút bật/tắt, bộ đếm token, v.v.)
2. Bản ghi hội thoại (<sessionId>.jsonl)
   • Bản ghi hội thoại chỉ thêm vào với cấu trúc cây (các mục có id + parentId)
   • Lưu cuộc trò chuyện thực tế + lệnh gọi công cụ + tóm tắt Compaction
   • Được dùng để dựng lại ngữ cảnh mô hình cho các lượt trong tương lai
   • Các điểm kiểm tra Compaction là siêu dữ liệu trên bản ghi hội thoại kế nhiệm đã được thu gọn. Các lần Compaction mới không ghi thêm một bản sao .checkpoint.*.jsonl thứ hai.

​

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 chủ đề Telegram: .../<sessionId>-topic-<threadId>.jsonl

​

Bảo trì kho và kiểm soát đĩa

• mode: enforce (mặc định) hoặc warn
• pruneAfter: ngưỡng tuổi của mục đã cũ (mặc định 30d)
• maxEntries: giới hạn mục trong sessions.json (mặc định 500)
• Thời gian giữ lại probe chạy mô hình Gateway ngắn hạn được cố định ở 24h, nhưng có cổng áp lực: nó chỉ xóa các hàng probe nghiêm ngặt đã cũ khi đạt đến áp lực bảo trì/giới hạn mục phiên. Điều này chỉ áp dụng cho các khóa probe rõ ràng nghiêm ngặt khớp với agent:*:explicit:model-run-<uuid> và chạy trước quá trình dọn dẹp/giới hạn mục cũ toàn cục khi nó chạy.
• resetArchiveRetention: thời gian giữ lại cho kho lưu trữ bản ghi hội thoại *.reset.<timestamp> (mặc định: giống pruneAfter; false tắt dọn dẹp)
• maxDiskBytes: ngân sách thư mục phiên tùy chọn
• highWaterBytes: mục tiêu tùy chọn sau dọn dẹp (mặc định 80% của maxDiskBytes)

1. Xóa các tạo tác đã lưu trữ cũ nhất, bản ghi hội thoại mồ côi hoặc quỹ đạo mồ côi 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 hội thoại/quỹ đạo của chúng.
3. Tiếp tục cho đến khi mức sử dụng bằng hoặc thấp hơn 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) cắt tỉa các phiên chạy cron cô lập cũ khỏi kho phiên (false tắt).
• cron.runLog.keepLines cắt tỉa các hàng lịch sử chạy SQLite được giữ lại theo từng công việc cron (mặc định: 2000). cron.runLog.maxBytes vẫn được chấp nhận cho nhật ký chạy dựa trên tệp cũ hơn.

​

Khóa phiên (sessionKey)

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

​

ID phiên (sessionId)

• Đặt lại (/new, /reset) tạo một sessionId mới cho sessionKey đó.
• Đặt lại hằng ngày (mặc định 4:00 sáng giờ địa phương trên máy chủ gateway) tạo một sessionId mới ở tin nhắn tiếp theo sau ranh giới đặt lại.
• Hết hạn do nhàn rỗi (session.reset.idleMinutes hoặc session.idleMinutes cũ) tạo một sessionId mới khi tin nhắn đến sau cửa sổ nhàn rỗi. Khi cả hằng ngày + nhàn rỗi đều được cấu hình, cái nào hết hạn trước sẽ thắng.
• Tiếp tục sau khi Control UI kết nối lại có thể giữ phiên hiện đang hiển thị cho một lần gửi sau kết nối lại khi Gateway nhận sessionId khớp từ một client giao diện người vận hành. Các lần gửi cũ thông thường vẫn tạo một sessionId mới.
• Sự kiện hệ thống (heartbeat, đánh thức cron, thông báo exec, ghi sổ Gateway) có thể thay đổi hàng phiên nhưng không kéo dài độ mới đặt lại hằng ngày/nhàn rỗi. Chuyển phiên đặt lại loại bỏ các thông báo sự kiện hệ thống đang xếp hàng cho phiên trước trước khi prompt mới được dựng.
• Chính sách fork cha dùng nhánh đang hoạt động của OpenClaw khi tạo một luồng hoặc fork tác tử con. Nếu nhánh đó quá lớn, OpenClaw bắt đầu tác tử con với ngữ cảnh cô lập thay vì thất bại hoặc kế thừa lịch sử không dùng được. Chính sách định cỡ là tự động; cấu hình cũ session.parentForkMaxTokens được openclaw doctor --fix xóa.

​

Sơ đồ kho phiên (sessions.json)

• sessionId: id bản ghi hiện tại (tên tệp được suy ra từ giá trị này trừ khi đặt sessionFile)
• sessionStartedAt: dấu thời gian bắt đầu cho sessionId hiện tại; độ mới khi đặt lại hằng ngày dùng giá trị này. Các hàng cũ có thể suy ra giá trị này từ phần đầu phiên JSONL.
• lastInteractionAt: dấu thời gian tương tác thực gần nhất của người dùng/kênh; độ mới khi đặt lại do nhàn rỗi dùng giá trị này để Heartbeat, Cron và sự kiện exec không giữ phiên còn sống. Các hàng cũ không có trường này sẽ dùng thời điểm bắt đầu phiên đã khôi phục làm dự phòng cho độ mới khi nhàn rỗi.
• updatedAt: dấu thời gian đột biến hàng lưu trữ gần nhất, dùng cho liệt kê, cắt tỉa và sổ sách. Đây không phải là nguồn thẩm quyền cho độ mới đặt lại hằng ngày/nhàn rỗi.
• archivedAt: dấu thời gian lưu trữ tùy chọn. Các phiên đã lưu trữ vẫn ở trong kho với bản ghi nguyên vẹn và bị loại khỏi danh sách hoạt động thông thường.
• pinnedAt: dấu thời gian ghim tùy chọn. Các phiên đang hoạt động đã ghim được sắp xếp trước các phiên chưa ghim; lưu trữ một phiên sẽ xóa ghim của phiên đó.
• Tương tác liên thông luồng Codex: cả hai trường đều theo hình dạng quản lý luồng Codex — các boolean archived/pinned trên dây luôn được suy ra từ dấu thời gian và được đóng dấu phía máy chủ, khớp với ngữ nghĩa Codex threads.archived_at và tuần tự hóa camelCase. Dấu thời gian OpenClaw là mili giây epoch còn Codex dùng giây epoch, vì vậy các cầu nối chuyển đổi tại ranh giới plugin codex. Codex chưa có API ghim (thread/archive/thread/unarchive בלבד); trạng thái đã ghim vẫn ở phía OpenClaw cho đến khi có API đó, lúc đó hình dạng khớp sẽ cho phép các phiên đã liên kết khứ hồi trạng thái ghim một cách cơ học.
• sessionFile: ghi đè đường dẫn bản ghi rõ ràng tùy chọn
• chatType: direct | group | room (giúp UI và chính sách gửi)
• provider, subject, room, space, displayName: siêu dữ liệu để gắn nhãn nhóm/kênh
• Công tắc:
  • thinkingLevel, verboseLevel, reasoningLevel, elevatedLevel
  • sendPolicy (ghi đè theo từng phiên)
• Chọn mô hình:
  • providerOverride, modelOverride, authProfileOverride
• Bộ đếm token (nỗ lực tối đa / phụ thuộc nhà cung cấp):
  • inputTokens, outputTokens, totalTokens, contextTokens
• compactionCount: số lần auto-compaction hoàn tất cho khóa phiên này
• memoryFlushAt: dấu thời gian cho lần xả bộ nhớ trước Compaction gần nhất
• memoryFlushCompactionCount: số đếm Compaction khi lần xả gần nhất chạy

​

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

• Dòng đầu tiên: phần đầ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/assistant/toolResult
• custom_message: tin nhắn do tiện ích mở rộng chèn vào và có đi vào ngữ cảnh mô hình (có thể ẩn khỏi UI)
• custom: trạng thái tiện ích mở rộng không đi vào ngữ cảnh mô hình
• compaction: bản tóm tắt Compaction đã lưu với firstKeptEntryId và tokensBefore
• branch_summary: bản tóm tắt đã lưu khi điều hướng một nhánh cây

​

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

1. Cửa sổ ngữ cảnh mô hình: giới hạn cứng theo từng mô hình (token hiển thị với mô hình)
2. Bộ đếm kho 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 kho là giá trị ước tính/báo cáo lúc chạy; đừng xem nó như một bảo đảm nghiêm ngặt.

​

Compaction: nó là gì

• Bản tóm tắt Compaction
• Tin nhắn sau firstKeptEntryId

​

Ranh giới khúc Compaction và ghép cặp công cụ

• Nếu điểm tách theo tỷ lệ token rơi vào giữa một lệnh gọi công cụ và kết quả của nó, OpenClaw dịch ranh giới về tin nhắn lệnh gọi công cụ của assistant thay vì tách cặp đó.
• Nếu một khối kết quả công cụ ở cuối nếu giữ nguyên sẽ đẩy khúc vượt quá mục tiêu, OpenClaw bảo toàn khối công cụ đang chờ đó và giữ nguyên phần đuôi chưa tóm tắt.
• Các khối lệnh gọi công cụ bị hủy/lỗi không giữ mở một điểm tách đang chờ.

​

Khi auto-compaction xảy ra (runtime OpenClaw)

1. Khôi phục tràn: mô hình trả về lỗi tràn ngữ cảnh (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, và các biến thể tương tự theo hình dạng nhà cung cấp) → compact → thử lại. Khi nhà cung cấp báo số token đã thử, OpenClaw chuyển tiếp số lượng quan sát được đó vào Compaction khôi phục tràn. Nếu nhà cung cấp xác nhận tràn nhưng không hiển thị số lượng có thể phân tích cú pháp, OpenClaw truyền một số lượng tổng hợp tối thiểu vượt ngân sách cho các engine Compaction và chẩn đoán. Nếu khôi phục tràn vẫn thất bại, OpenClaw hiển thị hướng dẫn rõ ràng cho người dùng và giữ nguyên ánh xạ phiên hiện tại thay vì âm thầm xoay khóa phiên sang một id phiên mới. Bước tiếp theo do người vận hành kiểm soát: thử lại tin nhắn, chạy /compact, hoặc chạy /new khi muốn một phiên mớ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 dự phòng dành cho prompt + đầu ra mô hình tiếp theo

​

Cài đặt Compaction (reserveTokens, keepRecentTokens)

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

• Nếu compaction.reserveTokens < reserveTokensFloor, OpenClaw nâng giá trị đó 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 giá trị đã cao hơn, OpenClaw giữ nguyên.
• /compact thủ công tôn trọng agents.defaults.compaction.keepRecentTokens rõ ràng và giữ điểm cắt phần đuôi gần đây của runtime OpenClaw. Nếu không có ngân sách giữ lại rõ ràng, Compaction thủ công vẫn là một checkpoint cứng và ngữ cảnh dựng lại bắt đầu từ bản tóm tắt mới.
• Đặt agents.defaults.compaction.midTurnPrecheck.enabled: true để chạy kiểm tra trước vòng lặp công cụ tùy chọn sau kết quả công cụ mới và trước lệnh gọi mô hình tiếp theo. Đây chỉ là bộ kích hoạt; việc tạo bản tóm tắt vẫn dùng đường dẫn Compaction đã cấu hình. Nó độc lập với maxActiveTranscriptBytes, vốn là cơ chế bảo vệ kích thước byte của bản ghi đang hoạt động ở đầu lượt.
• Đặt agents.defaults.compaction.maxActiveTranscriptBytes thành một giá trị byte hoặc chuỗi như "20mb" để chạy Compaction cục bộ trước một lượt khi bản ghi đang hoạt động trở nên lớn. Cơ chế bảo vệ này chỉ hoạt động khi truncateAfterCompaction cũng được bật. Để trống hoặc đặt 0 để tắt.
• Khi agents.defaults.compaction.truncateAfterCompaction được bật, OpenClaw xoay bản ghi đang hoạt động sang một JSONL kế nhiệm đã compact sau Compaction. Các hành động checkpoint nhánh/khôi phục dùng kế nhiệm đã compact đó; các tệp checkpoint cũ trước Compaction vẫn đọc được khi còn được tham chiếu.

​

Nhà cung cấp Compaction có thể cắm được

• provider: id của một Plugin nhà cung cấp Compaction đã đăng ký. Để trống để dùng tóm tắt LLM mặc định.
• Đặt provider sẽ buộc mode: "safeguard".
• Nhà cung cấp nhận cùng chỉ dẫn Compaction và chính sách bảo toàn định danh như đường dẫn tích hợp.
• Safeguard vẫn bảo toàn ngữ cảnh hậu tố lượt gần đây và lượt bị tách sau đầu ra của nhà cung cấp.
• Tóm tắt safeguard tích hợp tái chưng cất các bản tóm tắt trước đó với tin nhắn mới thay vì giữ nguyên văn toàn bộ bản tóm tắt trước đó.
• Chế độ safeguard bật kiểm toán chất lượng bản tóm tắt theo mặc định; đặt qualityGuard.enabled: false để bỏ qua hành vi thử lại khi đầu ra không đúng định dạng.
• Nếu nhà cung cấp thất bại hoặc trả về kết quả rỗng, OpenClaw tự động quay về tóm tắt LLM tích hợp.
• Tín hiệu hủy/hết thời gian được ném lại (không bị nuốt) để tôn trọng việc hủy của bên gọi.

​

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

• /status (trong bất kỳ phiên chat nào)
• openclaw status (CLI)
• openclaw sessions / sessions --json
• Nhật ký Gateway (pnpm gateway:watch hoặc openclaw logs --follow): embedded run auto-compaction start + complete
• Chế độ chi tiết: 🧹 Auto-compaction complete + số đếm Compaction

​

Dọn dẹp âm thầm (NO_REPLY)

• Trợ lý bắt đầu đầu ra bằng mã thông báo im lặng chính xác NO_REPLY / no_reply để biểu thị “không gửi phản hồi cho người dùng”.
• OpenClaw loại bỏ/chặn mã này ở lớp phân phối.
• Việc chặn mã thông báo im lặng chính xác không phân biệt chữ hoa/thường, nên NO_REPLY và no_reply đều được tính khi toàn bộ payload chỉ là mã thông báo im lặng.
• Cơ chế này chỉ dành cho các lượt chạy nền/thực sự không phân phối; đây không phải là lối tắt cho các yêu cầu người dùng thông thường có thể hành động.

​

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

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

• enabled (mặc định: true)
• model (ghi đè provider/model chính xác tùy chọn cho lượt xả, ví dụ ollama/qwen3:8b)
• 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 thêm cho lượt xả)

• Prompt/system prompt mặc định bao gồm gợi ý NO_REPLY để chặn phân phối.
• Khi đặt model, lượt xả sử dụng model đó mà không kế thừa chuỗi fallback của phiên đang hoạt động, để các tác vụ dọn dẹp chỉ chạy cục bộ không âm thầm fallback sang model hội thoại trả phí.
• Lượt xả chạy một lần cho mỗi chu kỳ Compaction (được theo dõi trong sessions.json).
• Lượt xả chỉ chạy cho các phiên OpenClaw nhúng (các backend CLI bỏ qua).
• Lượt xả bị bỏ qua khi workspace của phiên ở chế độ chỉ đọc (workspaceAccess: "ro" hoặc "none").
• Xem Bộ nhớ để biết bố cục tệp workspace 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.
• Store và transcript không khớp? Xác nhận host Gateway và đường dẫn store từ openclaw status.
• Compaction spam? Kiểm tra:
  • cửa sổ ngữ cảnh của model (quá nhỏ)
  • cài đặt Compaction (reserveTokens quá cao so với cửa sổ model có thể gây Compaction sớm hơn)
  • tool-result phình to: bật/tinh chỉnh cắt tỉa phiên
• Lượt im lặng bị rò rỉ? Xác nhận phản hồi bắt đầu bằng NO_REPLY (mã chính xác không phân biệt chữ hoa/thường) và bạn đang dùng bản build có bản sửa chặn streaming.

​

Liên quan

• Quản lý phiên
• Cắt tỉa phiên
• Công cụ ngữ cảnh