Tìm hiểu chuyên sâu về quản lý phiên

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• Định tuyến phiên (cách thông điệp đến được ánh xạ tới sessionKey)
• Kho phiên (sessions.json) và những gì nó theo dõi
• Lưu bền vững 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 từng provider 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 hook công việc trước Compaction
• Dọn dẹp im lặng (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

• UI (ứng dụng macOS, Control UI trên web, TUI) nên truy vấn Gateway để lấy danh sách phiên và số 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 Mac cục bộ của bạn” sẽ không phản ánh những gì Gateway đang dùng.

​

Hai lớp lưu bền vững

1. Kho phiên (sessions.json)
   • Bản đồ 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 công tắc, bộ đếm token, v.v.)
2. Bản ghi hội thoại (<sessionId>.jsonl)
   • Bản ghi hội thoại chỉ ghi nối thêm với cấu trúc cây (các mục có id + parentId)
   • Lưu cuộc hội thoại thực tế + lời gọi công cụ + tóm tắt Compaction
   • Dùng để dựng lại ngữ cảnh mô hình cho các lượt sau
   • Các checkpoint gỡ lỗi lớn trước Compaction được bỏ qua khi bản ghi hội thoại đang hoạt động vượt quá giới hạn kích thước checkpoint, tránh tạo thêm một bản sao .checkpoint.*.jsonl khổng lồ 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: warn (mặc định) hoặc enforce
• pruneAfter: ngưỡng tuổi mục cũ (mặc định 30d)
• maxEntries: giới hạn số mục trong sessions.json (mặc định 500)
• resetArchiveRetention: thời gian lưu trữ cho archive 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 khi dọn dẹp (mặc định 80% của maxDiskBytes)

1. Trước tiên xóa các artifact archive, bản ghi hội thoại mồ côi, hoặc trajectory mồ côi cũ nhất.
2. Nếu vẫn vượt mục tiêu, loại bỏ các mục phiên cũ nhất và tệp bản ghi hội thoại/trajectory 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 biệt lập cũ khỏi kho phiên (false tắt).
• cron.runLog.maxBytes + cron.runLog.keepLines cắt tỉa 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 (theo agent): agent:<agentId>:<mainKey> (mặc định main)
• Nhóm: agent:<agentId>:<channel>:group:<id>
• Phòng/channel (Discord/Slack): agent:<agentId>:<channel>:channel:<id> hoặc ...:room:<id>
• Cron: cron:<job.id>
• Webhook: hook:<uuid> (trừ khi được 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 ở thông điệp tiếp theo sau ranh giới reset.
• Hết hạn do không hoạt động (session.reset.idleMinutes hoặc session.idleMinutes cũ) tạo một sessionId mới khi có thông điệp đến sau cửa sổ không hoạt động. Khi cả hằng ngày + không hoạt động đều được cấu hình, cái nào hết hạn trước sẽ thắng.
• 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 của reset hằng ngày/không hoạt động. Rollover reset loại bỏ các thông báo sự kiện hệ thống đã 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 PI khi tạo luồng hoặc fork subagent. Nếu nhánh đó quá lớn, OpenClaw khởi động con với ngữ cảnh biệt 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 session.parentForkMaxTokens cũ bị openclaw doctor --fix xóa.

​

Schema 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 sessionFile được đặt)
• sessionStartedAt: timestamp bắt đầu cho sessionId hiện tại; độ mới của reset hằng ngày dùng trường này. Các hàng cũ có thể suy ra nó từ header phiên JSONL.
• lastInteractionAt: timestamp tương tác người dùng/channel thực gần nhất; độ mới của reset không hoạt động dùng trường 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 fallback về thời gian bắt đầu phiên đã khôi phục cho độ mới không hoạt động.
• updatedAt: timestamp thay đổi hàng kho gần nhất, dùng cho liệt kê, cắt tỉa, và ghi sổ. Nó không phải nguồn thẩm quyền cho độ mới của reset hằng ngày/không hoạt động.
• sessionFile: ghi đè đường dẫn bản ghi hội thoại 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 group/channel
• Công tắc:
  • thinkingLevel, verboseLevel, reasoningLevel, elevatedLevel
  • sendPolicy (ghi đè theo phiên)
• Chọn mô hình:
  • providerOverride, modelOverride, authProfileOverride
• Bộ đếm token (best-effort / phụ thuộc provider):
  • inputTokens, outputTokens, totalTokens, contextTokens
• compactionCount: số lần auto-compaction hoàn tất cho khóa phiên này
• memoryFlushAt: timestamp cho lần flush bộ nhớ trước Compaction gần nhất
• memoryFlushCompactionCount: số Compaction khi lần flush gần nhất chạy

​

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

• Dòng đầu tiên: header 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: thông điệp user/assistant/toolResult
• custom_message: thông điệp do extension chèn vào có đi vào ngữ cảnh mô hình (có thể bị ẩ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 Compaction đã lưu bền vững với firstKeptEntryId và tokensBefore
• branch_summary: tóm tắt đã lưu bền vững 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ị cho 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à dashboard)

• Cửa sổ ngữ cảnh đến từ catalog 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 runtime; đừng xem nó là bảo đảm nghiêm ngặt.

​

Compaction: là gì

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

​

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

• Nếu điểm chia 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ề thông điệp 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 không sẽ khiến khối vượt quá mục tiêu, OpenClaw giữ nguyên khối công cụ đang chờ đó và giữ phần đuôi chưa được tóm tắt nguyên vẹn.
• Các khối lệnh gọi công cụ bị hủy/lỗi không giữ một điểm chia đang chờ mở.

​

Khi tự động Compaction xảy ra (runtime Pi)

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 dạng nhà cung cấp) → 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à khoảng trống dự phòng dành cho prompt + đầu ra mô hình tiếp theo

​

Thiết lập Compaction (reserveTokens, keepRecentTokens)

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

• Nếu compaction.reserveTokens < reserveTokensFloor, OpenClaw tăng giá trị đó.
• 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 Pi. Khi không có ngân sách giữ lại rõ ràng, Compaction thủ công vẫn là một điểm kiểm tra cứng và ngữ cảnh được 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 các kết quả công cụ mới và trước lệnh gọi mô hình tiếp theo. Đây chỉ là một trigger; việc tạo tóm tắt vẫn dùng đường Compaction đã cấu hình. Nó độc lập với maxActiveTranscriptBytes, vốn là chốt chặn kích thước byte bản ghi đang hoạt động lúc bắt đầ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. Chốt chặn 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 vòng bản ghi đang hoạt động sang một JSONL kế nhiệm đã nén sau Compaction. Bản ghi đầy đủ cũ vẫn được lưu trữ và liên kết từ điểm kiểm tra Compaction thay vì bị ghi lại tại chỗ.

​

Nhà cung cấp Compaction có thể cắm vào

• provider: id của Plugin nhà cung cấp Compaction đã đăng ký. Để trống để dùng tóm tắt LLM mặc định.
• Đặt provider buộc mode: "safeguard".
• Nhà cung cấp nhận cùng các chỉ dẫn Compaction và chính sách bảo toàn định danh như đường tích hợp sẵn.
• Bảo vệ vẫn giữ ngữ cảnh hậu tố của lượt gần đây và lượt bị chia sau đầu ra của nhà cung cấp.
• Tóm tắt bảo vệ tích hợp sẵn chưng cất lại các bản tóm tắt trước đó với thông điệp mới thay vì giữ nguyên văn toàn bộ bản tóm tắt trước đó.
• Chế độ bảo vệ bật kiểm tra chất lượng tóm tắt theo mặc định; đặt qualityGuard.enabled: false để bỏ qua hành vi thử lại khi đầu ra sai đị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 sẵn.
• Tín hiệu hủy/hết thời gian chờ đượ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 người dùng thấy được

• /status (trong bất kỳ phiên trò chuyện 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ố lần Compaction

​

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

• Assistant bắt đầu đầu ra bằng token im lặng chính xác NO_REPLY / no_reply để biểu thị “không gửi phản hồi tới người dùng”.
• OpenClaw loại bỏ/ẩn điều này ở lớp phân phối.
• Việc ẩn token im lặng chính xác không phân biệt chữ hoa chữ thường, nên NO_REPLY và no_reply đều được tính khi toàn bộ payload chỉ là token im lặng.
• Điều này chỉ dành cho các lượt nền/không phân phối thực sự; nó không phải 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 phiên.
2. Khi nó vượt qua một “ngưỡng mềm” (dưới ngưỡng Compaction của Pi), chạy chỉ thị “ghi bộ nhớ ngay” im lặng cho tác nhân.
3. Dùng token 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 đè nhà cung cấp/mô hình 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 (prompt hệ thống bổ sung được thêm vào cho lượt xả)

• Prompt/prompt hệ thống mặc định bao gồm gợi ý NO_REPLY để ẩn phân phối.
• Khi model được đặt, lượt xả dùng mô hình đó mà không kế thừa chuỗi fallback của phiên đang hoạt động, nên việc dọn dẹp chỉ cục bộ không âm thầm quay về mô hình trò chuyện 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 Pi nhúng (backend CLI bỏ qua).
• Lượt xả bị bỏ qua khi workspace phiên ở chế độ 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 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.
• Kho lưu trữ và bản ghi không khớp? Xác nhận máy chủ Gateway và đường dẫn kho lưu trữ từ openclaw status.
• Compaction lặp quá nhiều? Kiểm tra:
  • cửa sổ ngữ cảnh mô hình (quá nhỏ)
  • thiết lập Compaction (reserveTokens quá cao so với cửa sổ mô hình có thể gây Compaction sớm hơn)
  • kết quả công cụ 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 (token chính xác không phân biệt chữ hoa chữ thường) và bạn đang dùng bản dựng có bao gồm bản sửa ẩn streaming.

​

Liên quan

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