---
read_when:
    - การวินิจฉัยข้อผิดพลาดจากสคีมาฐานข้อมูลที่ใหม่กว่า
    - การตรวจสอบความเข้ากันได้ของฐานข้อมูลก่อนอัปเดตหรือดาวน์เกรด
    - การกู้คืนฐานข้อมูลสำหรับ OpenClaw รุ่นเก่า
summary: ตำแหน่งฐานข้อมูล SQLite, เวอร์ชันสคีมา, การตรวจสอบความสมบูรณ์ และการกู้คืนหลังดาวน์เกรดของ OpenClaw
title: สคีมาฐานข้อมูล
x-i18n:
    generated_at: "2026-07-19T07:34:16Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 73993e2c593ba460784108aedef70bbfb499e525c709d6d6bdd956ccf93e0ddc
    source_path: reference/database-schemas.md
    workflow: 16
---

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

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

| ขอบเขต                | พาธเริ่มต้น                                               | เนื้อหา                                                                                              |
| -------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| ระนาบควบคุมส่วนกลาง | `~/.openclaw/state/openclaw.sqlite`                        | สถานะการกำหนดค่าที่ใช้ร่วมกัน รีจิสทรี การอนุมัติ สถานะ Plugin และสถานะรันไทม์ที่ใช้ร่วมกัน             |
| ระนาบข้อมูลต่อเอเจนต์ | `~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite` | เซสชัน บันทึกบทสนทนา ดัชนีหน่วยความจำ สถานะการยืนยันตัวตน สถานะการสนทนา และสถานะรันไทม์ที่มีขอบเขตเฉพาะเอเจนต์ |

ฟีเจอร์บางรายการที่มีปริมาณข้อมูลสูงหรือมีวงจรชีวิตเฉพาะใช้ที่เก็บ 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 จะข้ามกลไกป้องกันของตัวอัปเดต แต่การตรวจสอบขณะเปิดฐานข้อมูลยังคงปฏิเสธบิลด์ที่เข้ากันไม่ได้

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

| เวอร์ชัน | การเปลี่ยนแปลง                                                                                                                                                                                                                                                         | รุ่นที่เผยแพร่ครั้งแรก                                   |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| 1       | ที่เก็บต่อเอเจนต์เริ่มต้น ([#88349](https://github.com/openclaw/openclaw/pull/88349))                                                                                                                                                                            | `v2026.5.30-beta.1`, เสถียรจนถึง `v2026.7.1` |
| 2       | ข้อมูลระบุตัวตนของดัชนีหน่วยความจำ ([#104449](https://github.com/openclaw/openclaw/pull/104449))                                                                                                                                                                            | `v2026.7.2-beta.1`                              |
| 4       | ย้ายเซสชันและบันทึกบทสนทนาไปยัง SQLite ([#98236](https://github.com/openclaw/openclaw/pull/98236))                                                                                                                                                         | `v2026.7.2-beta.1`                              |
| 5-6     | ความใหม่ของสถานะปลายทางและวงจรชีวิตของสถานะ ([#104859](https://github.com/openclaw/openclaw/pull/104859))                                                                                                                                                           | `v2026.7.2-beta.1`                              |
| 7       | การฉายสถานะวงจรชีวิตต่อรายการ ([#106151](https://github.com/openclaw/openclaw/pull/106151))                                                                                                                                                            | `v2026.7.2-beta.1`                              |
| 8       | ที่มาของเซสชันต่อบันทึกบทสนทนา ([#106766](https://github.com/openclaw/openclaw/pull/106766))                                                                                                                                                                | `v2026.7.2-beta.2`                              |
| 9       | ตาราง `STRICT` ([#108663](https://github.com/openclaw/openclaw/pull/108663))                                                                                                                                                                                  | `v2026.7.2-beta.2`                              |
| 10      | พาธบันทึกบทสนทนาที่ใช้งานอยู่ซึ่งสร้างเป็นรูปธรรม ([#108851](https://github.com/openclaw/openclaw/pull/108851))                                                                                                                                                             | ยังไม่เผยแพร่                                      |
| 11      | สัญญาเช่า การส่งมอบแบบคงทน ที่อยู่การสนทนา และผลลัพธ์ Heartbeat ([#109636](https://github.com/openclaw/openclaw/pull/109636), [#95838](https://github.com/openclaw/openclaw/pull/95838), [#109999](https://github.com/openclaw/openclaw/pull/109999)) | ยังไม่เผยแพร่                                      |

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

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

| เวอร์ชัน | การเปลี่ยนแปลง                                                                                                   | รุ่นที่เผยแพร่ครั้งแรก       |
| ------- | -------------------------------------------------------------------------------------------------------- | ------------------- |
| 1       | ฐานข้อมูลสถานะที่ใช้ร่วมกันเริ่มต้น                                                                            | `v2026.5.30-beta.1` |
| 2       | เหตุการณ์ตรวจสอบข้อความที่มีเฉพาะข้อมูลเมตา ([#103903](https://github.com/openclaw/openclaw/pull/103903))         | `v2026.7.2-beta.1`  |
| 3       | ตาราง `STRICT` และการเสริมความแข็งแกร่งต่อความคลาดเคลื่อนของสคีมา ([#108663](https://github.com/openclaw/openclaw/pull/108663)) | `v2026.7.2-beta.2`  |
| 4       | ที่มาของการเฝ้าดูเซสชันแทนที่แถวค่าเซนทิเนลที่เข้ารหัส                                                  | ยังไม่เผยแพร่          |

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

| เวลา                                        | การตรวจสอบ                                                           |
| ------------------------------------------- | --------------------------------------------------------------- |
| ทุกครั้งที่เปิด                                  | ตรวจสอบตาราง `schema_meta` และแถวข้อมูลเมตาหลัก       |
| ก่อนการย้ายที่รอดำเนินการ                  | เรียกใช้การสแกนความสมบูรณ์ คีย์ต่างประเทศ บทบาท สคีมา และดัชนีแบบเต็ม |
| ตัวตรวจสอบเบื้องหลังของ Gateway                 | เรียกใช้การสแกนแบบเต็มประมาณวันละครั้งและบันทึกผล              |
| Doctor การตรวจสอบข้อมูลสำรอง และ Compaction | เรียกใช้การสแกนแบบเต็มก่อนยอมรับหรือเขียนฐานข้อมูลใหม่    |

การตรวจสอบล่วงหน้าของ 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. กู้คืนข้อมูลสำรองที่สร้างไว้ก่อนอัปเดต [สร้างและตรวจสอบข้อมูลสำรอง](/th/cli/backup) ก่อนการอัปเดตครั้งใหญ่
2. เรียกใช้บิลด์รุ่นเก่ากับไดเรกทอรีสถานะแยกต่างหาก (`OPENCLAW_STATE_DIR`) โดยจะเริ่มต้นใหม่ ส่วนข้อมูลที่ย้ายแล้วจะไม่ถูกแตะต้องและพร้อมใช้งานเมื่อกลับไปใช้บิลด์รุ่นใหม่กว่า
3. ทำตามขั้นตอนการดาวน์เกรดด้วยตนเองด้านล่าง วิธีนี้ไม่ได้รับการรองรับและเสี่ยงต่อการสูญเสียข้อมูลหากไม่มีข้อมูลสำรองที่ผ่านการตรวจสอบ

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

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

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

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

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

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

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

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

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

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

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

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

```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_meta
SET schema_version = 9,
    updated_at = unixepoch('now') * 1000
WHERE meta_key = 'primary';

COMMIT;
```

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