สคีมาฐานข้อมูล

OpenClaw จัดเก็บสถานะระนาบควบคุมไว้ในฐานข้อมูล SQLite ส่วนกลาง และจัดเก็บข้อมูลเอเจนต์ไว้ในฐานข้อมูล SQLite หนึ่งฐานต่อเอเจนต์ การย้ายสคีมาจะทำงานไปข้างหน้าเมื่อเปิดฐานข้อมูล บิลด์ OpenClaw รุ่นเก่าจะปฏิเสธฐานข้อมูลที่เขียนด้วยสคีมารุ่นใหม่กว่า

โครงสร้างฐานข้อมูล

ฟีเจอร์บางรายการที่มีปริมาณข้อมูลสูงหรือมีวงจรชีวิตเฉพาะใช้ที่เก็บ SQLite แยกต่างหาก รวมถึงรีจิสทรีงานและข้อมูลวิถีการทำงาน

สัญญาการกำหนดเวอร์ชัน

ฐานข้อมูลแต่ละฐานบันทึกสคีมาไว้สองตำแหน่ง:

• PRAGMA user_version คือเวอร์ชันสคีมา SQLite
• แถวหลัก schema_meta บันทึก role, agent_id, schema_version และ app_version โดย app_version คือบิลด์ OpenClaw ล่าสุดที่เขียนข้อมูลเมตาของสคีมา

OpenClaw ใช้การย้ายแบบไปข้างหน้าเท่านั้นเมื่อเปิดฐานข้อมูลรุ่นเก่าที่ยังรองรับ และจะปฏิเสธฐานข้อมูลที่มี user_version ใหม่กว่าบิลด์ที่กำลังทำงาน พร้อมรายงานข้อผิดพลาด newer schema version Gateway จะตรวจสอบฐานข้อมูลที่ลงทะเบียนทั้งหมดก่อนเริ่มทำงาน นอกจากนี้ openclaw update ยังปฏิเสธแพ็กเกจหรือเป้าหมายซอร์สที่ประกาศการรองรับสคีมาเก่ากว่าฐานข้อมูลบนดิสก์อีกด้วย แพ็กเกจเป้าหมายที่เผยแพร่ก่อนเพิ่มข้อมูลเมตาของสคีมาจะไม่สามารถตรวจสอบล่วงหน้าได้

การติดตั้ง OpenClaw ด้วยตนเองผ่าน npm จะข้ามกลไกป้องกันของตัวอัปเดต แต่การตรวจสอบขณะเปิดฐานข้อมูลยังคงปฏิเสธบิลด์ที่เข้ากันไม่ได้

ประวัติสคีมาเอเจนต์

เวอร์ชัน 3 เป็นขั้นตอนการพัฒนาที่ไม่เคยเผยแพร่และถูกรวมไว้ในเวอร์ชัน 4

ประวัติสคีมาสถานะ

การตรวจสอบความสมบูรณ์

การตรวจสอบล่วงหน้าของ Gateway อ่านเฉพาะส่วนหัวของสคีมา ตัวตรวจสอบเบื้องหลังเป็นผู้รับผิดชอบการสแกนแบบเต็มที่ช้ากว่าสำหรับฐานข้อมูลที่ไม่จำเป็นต้องย้าย การตัดสินใจกักกันจะอยู่เฉพาะในที่เก็บ openclaw-quarantine.sqlite โดยเฉพาะ เพื่อให้ยังคงอยู่แม้ฐานข้อมูลที่ถูกกักกันจะเสียหาย ระบบจะบันทึกผลการตรวจสอบไว้

การแก้ไขปัญหา

เหตุใดจึงย้อนกลับไม่ได้หลังจากอัปเดตเป็น 2026.7.2

ทุกรุ่นจนถึง v2026.7.1 ใช้สคีมาเอเจนต์ 1 และสคีมาสถานะ 1 สายการเผยแพร่ 2026.7.2 (เริ่มต้นด้วย v2026.7.2-beta.1) จะย้ายฐานข้อมูลไปข้างหน้าเมื่อเริ่มทำงานครั้งแรก การย้ายนี้เป็นทางเดียว: ข้อมูลจะถูกเขียนใหม่ให้อยู่ในสคีมารุ่นใหม่กว่า และการติดตั้ง OpenClaw รุ่นเก่าหลังจากนั้นจะไม่ย้อนการเปลี่ยนแปลง บิลด์รุ่นเก่าจะปฏิเสธการเริ่มทำงานพร้อมข้อผิดพลาด newer schema version ซึ่งระบุชื่อบิลด์ที่เป็นเจ้าของฐานข้อมูล

การดาวน์เกรดไบนารีจะไม่ดาวน์เกรดข้อมูล หากจำเป็นต้องใช้รุ่นที่เก่ากว่า 2026.7.2 หลังจากอัปเดตแล้ว มีสามตัวเลือก:

1. กู้คืนข้อมูลสำรองที่สร้างไว้ก่อนอัปเดต สร้างและตรวจสอบข้อมูลสำรอง ก่อนการอัปเดตครั้งใหญ่
2. เรียกใช้บิลด์รุ่นเก่ากับไดเรกทอรีสถานะแยกต่างหาก (OPENCLAW_STATE_DIR) โดยจะเริ่มต้นใหม่ ส่วนข้อมูลที่ย้ายแล้วจะไม่ถูกแตะต้องและพร้อมใช้งานเมื่อกลับไปใช้บิลด์รุ่นใหม่กว่า
3. ทำตามขั้นตอนการดาวน์เกรดด้วยตนเองด้านล่าง วิธีนี้ไม่ได้รับการรองรับและเสี่ยงต่อการสูญเสียข้อมูลหากไม่มีข้อมูลสำรองที่ผ่านการตรวจสอบ

ตั้งแต่ 2026.7.2 เป็นต้นมา openclaw update จะปฏิเสธการติดตั้งรุ่นที่ไม่สามารถเปิดฐานข้อมูลปัจจุบันได้ ดังนั้นตัวอัปเดตจะไม่ทำให้เกิดสถานการณ์นี้ การติดตั้งรุ่นเก่าด้วยตนเองผ่าน npm จะข้ามกลไกป้องกันดังกล่าว ฐานข้อมูลยังคงปฏิเสธไบนารีรุ่นเก่า แต่จะเกิดขึ้นหลังจากติดตั้งแล้วเท่านั้น

Gateway ปฏิเสธการเริ่มทำงานโดยแจ้งข้อผิดพลาดเวอร์ชันสคีมาที่ใหม่กว่า

บิลด์ OpenClaw รุ่นใหม่กว่าเป็นผู้เขียนฐานข้อมูล แต่บิลด์ที่กำลังทำงานเป็นรุ่นเก่ากว่า ข้อผิดพลาดและบันทึกการเริ่มทำงานของ Gateway จะระบุชื่อบิลด์ที่เป็นเจ้าของฐานข้อมูล (app_version) ให้ติดตั้งเวอร์ชันนั้นหรือใหม่กว่า หรือใช้หนึ่งในตัวเลือกข้างต้น ห้ามแก้ไขฐานข้อมูลเพื่อระงับข้อผิดพลาด

ฐานข้อมูลถูกกักกันหลังการตรวจสอบความสมบูรณ์ล้มเหลว

ตัวตรวจสอบเบื้องหลังพิสูจน์แล้วว่าไฟล์เสียหาย และทุกครั้งที่เปิดจะล้มเหลวทันทีแทนการสแกนซ้ำ กู้คืนฐานข้อมูลจากข้อมูลสำรองหรือซ่อมแซม จากนั้นเรียกใช้ openclaw doctor --fix เพื่อล้างระเบียนการกักกัน Doctor จะรายงานข้อผิดพลาดอย่างชัดเจนหากไม่สามารถล้างระเบียนการกักกันได้ ให้เรียกใช้อีกครั้งจนกว่าจะรายงานว่าสะอาด

ไม่รองรับการดาวน์เกรด

การดาวน์เกรดสคีมาด้วยตนเองมีไว้สำหรับเอเจนต์และผู้ปฏิบัติงานที่ยอมรับความเสี่ยง สร้างและตรวจสอบข้อมูลสำรอง ก่อนแก้ไขฐานข้อมูลใดๆ หยุด Gateway และทุกกระบวนการที่สามารถเปิดฐานข้อมูลได้

ขั้นตอนทั่วไปมีดังนี้:

1. อ่านสคีมาและการย้ายของรุ่นเป้าหมาย
2. ภายในธุรกรรมเดียว ให้ลบทุกตาราง ดัชนี ทริกเกอร์ และคอลัมน์ที่เพิ่มหลังเวอร์ชันเป้าหมาย
3. ตั้งค่า PRAGMA user_version และ schema_meta.schema_version เป็นเวอร์ชันเป้าหมาย
4. เรียกใช้การตรวจสอบฐานข้อมูลแบบเต็มของรุ่นเป้าหมายก่อนเริ่ม Gateway

ตัวอย่าง: สคีมาเอเจนต์ 11 เป็น 9

สคีมา 10 เพิ่มการฉายบันทึกบทสนทนาที่ใช้งานอยู่ สคีมา 11 เพิ่มสัญญาเช่า การส่งมอบแบบคงทน สถานะที่อยู่การสนทนา และผลลัพธ์ Heartbeat การประสานงาน QMD ใช้แถวใน state_leases โดยไม่มีตาราง QMD แยกต่างหากที่ต้องเก็บรักษา

เรียกใช้ SQL ที่เทียบเท่ากันกับฐานข้อมูลต่อเอเจนต์แต่ละฐานที่ได้รับผลกระทบ หลังจากตรวจสอบสคีมาที่เขียนฐานข้อมูลนั้นอย่างถูกต้องแล้ว:

BEGIN IMMEDIATE; DROP TABLE IF EXISTS heartbeat_outcomes;DROP TABLE IF EXISTS conversation_deliveries;DROP TABLE IF EXISTS state_leases;DROP TABLE IF EXISTS session_transcript_active_events; ALTER TABLE session_transcript_index_state DROP COLUMN active_event_count;ALTER TABLE session_transcript_index_state DROP COLUMN active_message_count;ALTER TABLE conversations DROP COLUMN delivery_target; PRAGMA user_version = 9;UPDATE schema_metaSET schema_version = 9,    updated_at = unixepoch('now') * 1000WHERE meta_key = 'primary'; COMMIT;

การดำเนินการนี้จะทิ้งสถานะของเวอร์ชัน 10-11 รวมถึงการดำเนินการส่งมอบที่กำลังดำเนินอยู่ สัญญาเช่า ผลลัพธ์ Heartbeat และการฉายบันทึกบทสนทนาที่ใช้งานอยู่ซึ่งได้มาจากข้อมูล หากดาวน์เกรดผิดพลาด ให้กู้คืนจากข้อมูลสำรองที่ผ่านการตรวจสอบแล้ว