เจาะลึกการจัดการเซสชัน

Documentation Index

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

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

• การกำหนดเส้นทางเซสชัน (วิธีที่ข้อความขาเข้าถูกแมปไปยัง sessionKey)
• ที่เก็บเซสชัน (sessions.json) และสิ่งที่ติดตาม
• การคงอยู่ของทรานสคริปต์ (*.jsonl) และโครงสร้างของมัน
• สุขอนามัยของทรานสคริปต์ (การปรับแก้เฉพาะผู้ให้บริการก่อนการรัน)
• ขีดจำกัดบริบท (หน้าต่างบริบทเทียบกับโทเค็นที่ติดตาม)
• Compaction (การ Compaction แบบแมนนวลและอัตโนมัติ) และตำแหน่งที่จะ hook งานก่อน Compaction
• การดูแลระบบแบบเงียบ (การเขียนหน่วยความจำที่ไม่ควรสร้างเอาต์พุตที่ผู้ใช้มองเห็น)

• การจัดการเซสชัน
• Compaction
• ภาพรวมหน่วยความจำ
• การค้นหาหน่วยความจำ
• การตัดแต่งเซสชัน
• สุขอนามัยของทรานสคริปต์

​

แหล่งข้อมูลจริง: Gateway

• ส่วนติดต่อผู้ใช้ (แอป macOS, UI ควบคุมบนเว็บ, TUI) ควรสอบถาม Gateway เพื่อรับรายการเซสชันและจำนวนโทเค็น
• ในโหมดรีโมต ไฟล์เซสชันอยู่บนโฮสต์รีโมต; “การตรวจสอบไฟล์ใน Mac เครื่องคุณ” จะไม่สะท้อนสิ่งที่ Gateway ใช้งานอยู่

​

ชั้นการคงอยู่สองชั้น

1. ที่เก็บเซสชัน (sessions.json)
   • แผนที่คีย์/ค่า: sessionKey -> SessionEntry
   • ขนาดเล็ก เปลี่ยนแปลงได้ แก้ไขได้อย่างปลอดภัย (หรือลบรายการได้)
   • ติดตามเมทาดาทาของเซสชัน (รหัสเซสชันปัจจุบัน กิจกรรมล่าสุด toggle ตัวนับโทเค็น ฯลฯ)
2. ทรานสคริปต์ (<sessionId>.jsonl)
   • ทรานสคริปต์แบบ append-only พร้อมโครงสร้างต้นไม้ (รายการมี id + parentId)
   • เก็บบทสนทนาจริง + การเรียกเครื่องมือ + สรุป Compaction
   • ใช้สร้างบริบทโมเดลใหม่สำหรับเทิร์นในอนาคต
   • checkpoint ดีบักขนาดใหญ่ก่อน Compaction จะถูกข้ามเมื่อทรานสคริปต์ที่ active เกินเพดานขนาด checkpoint เพื่อหลีกเลี่ยงสำเนา .checkpoint.*.jsonl ขนาดยักษ์ชุดที่สอง

​

ตำแหน่งบนดิสก์

• ที่เก็บ: ~/.openclaw/agents/<agentId>/sessions/sessions.json
• ทรานสคริปต์: ~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl
  • เซสชันหัวข้อ Telegram: .../<sessionId>-topic-<threadId>.jsonl

​

การบำรุงรักษาที่เก็บและการควบคุมดิสก์

• mode: warn (ค่าเริ่มต้น) หรือ enforce
• pruneAfter: cutoff อายุของรายการที่ค้างเก่า (ค่าเริ่มต้น 30d)
• maxEntries: จำกัดจำนวนรายการใน sessions.json (ค่าเริ่มต้น 500)
• resetArchiveRetention: ระยะเวลาเก็บรักษา archive ทรานสคริปต์ *.reset.<timestamp> (ค่าเริ่มต้น: เหมือน pruneAfter; false ปิดการ cleanup)
• maxDiskBytes: งบประมาณไดเรกทอรีเซสชันแบบไม่บังคับ
• highWaterBytes: เป้าหมายแบบไม่บังคับหลัง cleanup (ค่าเริ่มต้น 80% ของ maxDiskBytes)

1. ลบ artifact ที่ archive ไว้เก่าสุด ทรานสคริปต์กำพร้า หรือ trajectory กำพร้าก่อน
2. หากยังเกินเป้าหมาย ให้ขับรายการเซสชันเก่าสุดและไฟล์ทรานสคริปต์/trajectory ของรายการเหล่านั้นออก
3. ทำต่อไปจนกว่าการใช้งานจะอยู่ที่หรือต่ำกว่า highWaterBytes

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

​

เซสชัน Cron และ run log

• cron.sessionRetention (ค่าเริ่มต้น 24h) prune เซสชันการรัน cron แบบแยกส่วนเก่าจากที่เก็บเซสชัน (false ปิดใช้งาน)
• cron.runLog.maxBytes + cron.runLog.keepLines prune ไฟล์ ~/.openclaw/cron/runs/<jobId>.jsonl (ค่าเริ่มต้น: 2_000_000 ไบต์ และ 2000 บรรทัด)

​

คีย์เซสชัน (sessionKey)

• แชตหลัก/โดยตรง (ต่อ agent): agent:<agentId>:<mainKey> (ค่าเริ่มต้น main)
• กลุ่ม: agent:<agentId>:<channel>:group:<id>
• ห้อง/channel (Discord/Slack): agent:<agentId>:<channel>:channel:<id> หรือ ...:room:<id>
• Cron: cron:<job.id>
• Webhook: hook:<uuid> (เว้นแต่ถูก override)

​

รหัสเซสชัน (sessionId)

• Reset (/new, /reset) สร้าง sessionId ใหม่สำหรับ sessionKey นั้น
• Daily reset (ค่าเริ่มต้น 4:00 AM ตามเวลาท้องถิ่นบนโฮสต์ Gateway) สร้าง sessionId ใหม่เมื่อมีข้อความถัดไปหลังขอบเขต reset
• Idle expiry (session.reset.idleMinutes หรือ legacy session.idleMinutes) สร้าง sessionId ใหม่เมื่อมีข้อความมาถึงหลังช่วง idle เมื่อกำหนดทั้ง daily + idle ไว้ ตัวที่หมดอายุก่อนจะชนะ
• System events (Heartbeat, การปลุก cron, การแจ้งเตือน exec, งานบัญชีของ gateway) อาจ mutate แถวเซสชัน แต่ไม่ขยายความสดใหม่ของ daily/idle reset การ rollover ของ reset จะทิ้งประกาศ system-event ที่เข้าคิวไว้สำหรับเซสชันก่อนหน้า ก่อนสร้าง prompt ใหม่
• Parent fork policy ใช้ branch ที่ active ของ PI เมื่อสร้างเธรดหรือ fork subagent หาก branch นั้นใหญ่เกินไป OpenClaw จะเริ่ม child ด้วยบริบทแบบแยกส่วนแทนการล้มเหลวหรือสืบทอดประวัติที่ใช้งานไม่ได้ นโยบาย sizing เป็นอัตโนมัติ; config เดิม session.parentForkMaxTokens จะถูกลบโดย openclaw doctor --fix

​

สคีมาที่เก็บเซสชัน (sessions.json)

• sessionId: รหัสทรานสคริปต์ปัจจุบัน (filename derive จากค่านี้ เว้นแต่ตั้ง sessionFile)
• sessionStartedAt: timestamp เริ่มต้นสำหรับ sessionId ปัจจุบัน; ความสดใหม่ของ daily reset ใช้ค่านี้ แถว legacy อาจ derive จาก session header ของ JSONL
• lastInteractionAt: timestamp ของ interaction จริงล่าสุดจากผู้ใช้/channel; ความสดใหม่ของ idle reset ใช้ค่านี้เพื่อให้ Heartbeat, cron และ exec events ไม่ทำให้เซสชัน มีชีวิตต่อ แถว legacy ที่ไม่มีฟิลด์นี้ fallback ไปยังเวลาเริ่มต้นเซสชันที่กู้คืนมา สำหรับความสดใหม่ของ idle
• updatedAt: timestamp ของ mutation แถวที่เก็บล่าสุด ใช้สำหรับการแสดงรายการ การ prune และ งานบัญชี ไม่ใช่ authority สำหรับความสดใหม่ของ daily/idle reset
• sessionFile: override path ทรานสคริปต์แบบชัดเจนที่ไม่บังคับ
• chatType: direct | group | room (ช่วย UI และนโยบายส่ง)
• provider, subject, room, space, displayName: เมทาดาทาสำหรับการตั้ง label ของกลุ่ม/channel
• Toggle:
  • thinkingLevel, verboseLevel, reasoningLevel, elevatedLevel
  • sendPolicy (override ต่อเซสชัน)
• การเลือกโมเดล:
  • providerOverride, modelOverride, authProfileOverride
• ตัวนับโทเค็น (best-effort / ขึ้นกับผู้ให้บริการ):
  • inputTokens, outputTokens, totalTokens, contextTokens
• compactionCount: ความถี่ที่ auto-compaction เสร็จสมบูรณ์สำหรับคีย์เซสชันนี้
• memoryFlushAt: timestamp สำหรับการ flush หน่วยความจำก่อน Compaction ครั้งล่าสุด
• memoryFlushCompactionCount: จำนวน Compaction เมื่อ flush ล่าสุดรัน

​

โครงสร้างทรานสคริปต์ (*.jsonl)

• บรรทัดแรก: session header (type: "session", รวม id, cwd, timestamp, parentSession แบบไม่บังคับ)
• จากนั้น: รายการเซสชันที่มี id + parentId (ต้นไม้)

• message: ข้อความ user/assistant/toolResult
• custom_message: ข้อความที่ extension inject เข้ามาซึ่ง เข้า บริบทโมเดล (ซ่อนจาก UI ได้)
• custom: สถานะ extension ที่ ไม่เข้า บริบทโมเดล
• compaction: สรุป Compaction ที่คงอยู่พร้อม firstKeptEntryId และ tokensBefore
• branch_summary: สรุปที่คงอยู่เมื่อนำทาง branch ของต้นไม้

​

หน้าต่างบริบทเทียบกับโทเค็นที่ติดตาม

1. หน้าต่างบริบทของโมเดล: hard cap ต่อโมเดล (โทเค็นที่โมเดลมองเห็นได้)
2. ตัวนับที่เก็บเซสชัน: สถิติ rolling ที่เขียนลง sessions.json (ใช้สำหรับ /status และ dashboard)

• หน้าต่างบริบทมาจาก catalog โมเดล (และ override ผ่าน config ได้)
• contextTokens ในที่เก็บเป็นค่าประมาณ/ค่ารายงานขณะ runtime; อย่าถือว่าเป็นการรับประกันแบบเข้มงวด

​

Compaction: คืออะไร

• สรุป Compaction
• ข้อความหลัง firstKeptEntryId

​

ขอบเขตชังก์ของ Compaction และการจับคู่เครื่องมือ

• หากการแบ่งตามสัดส่วนโทเคนตกอยู่ระหว่างการเรียกเครื่องมือกับผลลัพธ์ OpenClaw จะเลื่อนขอบเขตไปที่ข้อความการเรียกเครื่องมือของผู้ช่วยแทนการแยกคู่นั้นออกจากกัน
• หากบล็อกผลลัพธ์เครื่องมือท้ายสุดจะทำให้ชังก์เกินเป้าหมายในกรณีปกติ OpenClaw จะรักษาบล็อกเครื่องมือที่ค้างอยู่นั้นไว้ และคงส่วนท้ายที่ยังไม่ได้สรุปไว้ครบถ้วน
• บล็อกการเรียกเครื่องมือที่ถูกยกเลิก/เกิดข้อผิดพลาดจะไม่ทำให้การแบ่งที่ค้างอยู่เปิดต่อไป

​

เมื่อใดที่ auto-compaction เกิดขึ้น (รันไทม์ Pi)

1. การกู้คืนจากการล้น: โมเดลส่งคืนข้อผิดพลาดบริบทล้น (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 และรูปแบบคล้ายกันตามผู้ให้บริการ) → compact → ลองใหม่
2. การดูแลรักษาตามเกณฑ์: หลังจากเทิร์นสำเร็จ เมื่อ:

• contextWindow คือหน้าต่างบริบทของโมเดล
• reserveTokens คือพื้นที่เผื่อที่สงวนไว้สำหรับพรอมป์ + เอาต์พุตโมเดลถัดไป

​

การตั้งค่า Compaction (reserveTokens, keepRecentTokens)

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

• หาก compaction.reserveTokens < reserveTokensFloor OpenClaw จะเพิ่มค่าให้
• ค่าพื้นเริ่มต้นคือ 20000 โทเคน
• ตั้งค่า agents.defaults.compaction.reserveTokensFloor: 0 เพื่อปิดใช้ค่าพื้น
• หากค่าสูงกว่าอยู่แล้ว OpenClaw จะปล่อยไว้ตามเดิม
• /compact แบบแมนนวลจะเคารพ agents.defaults.compaction.keepRecentTokens ที่ระบุชัดเจน และเก็บจุดตัดส่วนท้ายล่าสุดของ Pi ไว้ หากไม่มีงบประมาณการเก็บที่ระบุชัดเจน Compaction แบบแมนนวลจะยังคงเป็นเช็กพอยต์แบบแข็ง และบริบทที่สร้างใหม่จะเริ่มจาก สรุปใหม่
• ตั้งค่า agents.defaults.compaction.midTurnPrecheck.enabled: true เพื่อรัน precheck ของลูปเครื่องมือที่เป็นตัวเลือก หลังจากมีผลลัพธ์เครื่องมือใหม่และก่อนการเรียกโมเดล ถัดไป นี่เป็นเพียงทริกเกอร์เท่านั้น; การสร้างสรุปยังคงใช้เส้นทาง Compaction ที่กำหนดค่าไว้ สิ่งนี้เป็นอิสระจาก maxActiveTranscriptBytes ซึ่งเป็นตัวป้องกัน ตามขนาดไบต์ของทรานสคริปต์ที่ใช้งานอยู่ตอนเริ่มเทิร์น
• ตั้งค่า agents.defaults.compaction.maxActiveTranscriptBytes เป็นค่าไบต์หรือ สตริง เช่น "20mb" เพื่อรัน Compaction ภายในเครื่องก่อนเทิร์นเมื่อทรานสคริปต์ ที่ใช้งานอยู่มีขนาดใหญ่ ตัวป้องกันนี้จะทำงานเฉพาะเมื่อเปิดใช้ truncateAfterCompaction ด้วย ปล่อยไว้ไม่ตั้งค่าหรือตั้ง 0 เพื่อปิดใช้
• เมื่อเปิดใช้ agents.defaults.compaction.truncateAfterCompaction OpenClaw จะหมุนทรานสคริปต์ที่ใช้งานอยู่ไปเป็น JSONL ตัวสืบทอดที่ถูก compact แล้ว หลัง Compaction ทรานสคริปต์เต็มเดิมยังคงถูกเก็บถาวรและลิงก์จากเช็กพอยต์ Compaction แทนการเขียนทับในที่เดิม

​

ผู้ให้บริการ Compaction แบบเสียบเปลี่ยนได้

• provider: id ของ Plugin ผู้ให้บริการ Compaction ที่ลงทะเบียนไว้ ปล่อยว่างไว้เพื่อใช้การสรุปด้วย LLM เริ่มต้น
• การตั้งค่า provider จะบังคับ mode: "safeguard"
• ผู้ให้บริการจะได้รับคำสั่ง Compaction และนโยบายการรักษาตัวระบุแบบเดียวกับเส้นทางในตัว
• safeguard ยังคงรักษาบริบทส่วนต่อท้ายของเทิร์นล่าสุดและเทิร์นที่ถูกแบ่งไว้หลังเอาต์พุตของผู้ให้บริการ
• การสรุป safeguard ในตัวจะกลั่นสรุปก่อนหน้าซ้ำร่วมกับข้อความใหม่ แทนการรักษาสรุปก่อนหน้าแบบเต็มไว้ตามตัวอักษร
• โหมด safeguard เปิดใช้การตรวจสอบคุณภาพสรุปโดยค่าเริ่มต้น; ตั้งค่า qualityGuard.enabled: false เพื่อข้ามพฤติกรรมลองใหม่เมื่อเอาต์พุตมีรูปแบบผิด
• หากผู้ให้บริการล้มเหลวหรือส่งคืนผลลัพธ์ว่าง OpenClaw จะย้อนกลับไปใช้การสรุปด้วย LLM ในตัวโดยอัตโนมัติ
• สัญญาณยกเลิก/หมดเวลาจะถูกโยนซ้ำ (ไม่ถูกกลืน) เพื่อเคารพการยกเลิกของผู้เรียก

​

พื้นผิวที่ผู้ใช้มองเห็น

• /status (ในเซสชันแชตใดก็ได้)
• openclaw status (CLI)
• openclaw sessions / sessions --json
• ล็อก Gateway (pnpm gateway:watch หรือ openclaw logs --follow): embedded run auto-compaction start + complete
• โหมดละเอียด: 🧹 Auto-compaction complete + จำนวน Compaction

​

งานดูแลระบบแบบเงียบ (NO_REPLY)

• ผู้ช่วยเริ่มเอาต์พุตด้วยโทเคนเงียบที่ตรงเป๊ะ NO_REPLY / no_reply เพื่อระบุว่า “ไม่ต้องส่งคำตอบให้ผู้ใช้”
• OpenClaw จะตัด/ระงับสิ่งนี้ในชั้นการส่งมอบ
• การระงับด้วยโทเคนเงียบที่ตรงเป๊ะไม่สนใจตัวพิมพ์เล็กใหญ่ ดังนั้น NO_REPLY และ no_reply จะนับทั้งคู่เมื่อเพย์โหลดทั้งหมดมีเพียงโทเคนเงียบ
• สิ่งนี้มีไว้สำหรับเทิร์นเบื้องหลัง/ไม่ส่งมอบจริงเท่านั้น; ไม่ใช่ทางลัดสำหรับ คำขอผู้ใช้ทั่วไปที่ต้องดำเนินการได้

​

”การล้างหน่วยความจำ” ก่อน Compaction (ใช้งานแล้ว)

1. ตรวจสอบการใช้งานบริบทของเซสชัน
2. เมื่อข้าม “เกณฑ์อ่อน” (ต่ำกว่าเกณฑ์ Compaction ของ Pi) ให้รันคำสั่งเงียบ “เขียนหน่วยความจำตอนนี้” ไปยังเอเจนต์
3. ใช้โทเคนเงียบที่ตรงเป๊ะ NO_REPLY / no_reply เพื่อให้ผู้ใช้ไม่เห็น อะไรเลย

• enabled (ค่าเริ่มต้น: true)
• model (ตัวเลือกการแทนที่ผู้ให้บริการ/โมเดลแบบตรงเป๊ะที่เป็นทางเลือกสำหรับเทิร์นล้าง เช่น ollama/qwen3:8b)
• softThresholdTokens (ค่าเริ่มต้น: 4000)
• prompt (ข้อความผู้ใช้สำหรับเทิร์นล้าง)
• systemPrompt (พรอมป์ระบบเพิ่มเติมที่ต่อท้ายสำหรับเทิร์นล้าง)

• พรอมป์/พรอมป์ระบบเริ่มต้นมีคำใบ้ NO_REPLY เพื่อระงับ การส่งมอบ
• เมื่อตั้งค่า model เทิร์นล้างจะใช้โมเดลนั้นโดยไม่สืบทอด เชน fallback ของเซสชันที่ใช้งานอยู่ ดังนั้นงานดูแลระบบเฉพาะเครื่องจะไม่ fallback ไปยังโมเดลสนทนาแบบเสียเงินอย่างเงียบ ๆ
• การล้างจะรันหนึ่งครั้งต่อรอบ Compaction (ติดตามใน sessions.json)
• การล้างจะรันเฉพาะสำหรับเซสชัน Pi แบบฝังตัว (แบ็กเอนด์ CLI จะข้าม)
• การล้างจะถูกข้ามเมื่อเวิร์กสเปซเซสชันเป็นแบบอ่านอย่างเดียว (workspaceAccess: "ro" หรือ "none")
• ดู หน่วยความจำ สำหรับเลย์เอาต์ไฟล์เวิร์กสเปซและรูปแบบการเขียน

​

เช็กลิสต์การแก้ปัญหา

• คีย์เซสชันผิดหรือไม่? เริ่มจาก /concepts/session และยืนยัน sessionKey ใน /status
• ที่เก็บกับทรานสคริปต์ไม่ตรงกันหรือไม่? ยืนยันโฮสต์ Gateway และเส้นทางที่เก็บจาก openclaw status
• Compaction ถี่เกินไปหรือไม่? ตรวจสอบ:
  • หน้าต่างบริบทของโมเดล (เล็กเกินไป)
  • การตั้งค่า Compaction (reserveTokens สูงเกินไปสำหรับหน้าต่างโมเดลอาจทำให้ Compaction เกิดเร็วขึ้น)
  • ผลลัพธ์เครื่องมือบวม: เปิดใช้/ปรับแต่งการตัดแต่งเซสชัน
• เทิร์นเงียบรั่วหรือไม่? ยืนยันว่าคำตอบเริ่มด้วย NO_REPLY (โทเคนตรงเป๊ะแบบไม่สนใจตัวพิมพ์เล็กใหญ่) และคุณอยู่บนบิลด์ที่มีการแก้ไขการระงับสตรีมมิงแล้ว

​

ที่เกี่ยวข้อง

• การจัดการเซสชัน
• การตัดแต่งเซสชัน
• เอนจินบริบท