7. Session Management

Mục tiêu: Hiểu cách OpenClaw quản lý ngữ cảnh hội thoại và lifecycle của session.

Session là gì?

Session là một chuỗi hội thoại liên tục giữa một người dùng và AI. Mỗi session:

• Lưu trữ lịch sử chat (context)
• Có session ID riêng biệt
• Được cô lập giữa các người dùng (không chia sẻ)
• Có thể reset khi cần bắt đầu mới

┌─────────────────────────────────────────┐
│           OpenClaw Gateway              │
├─────────────────────────────────────────┤
│  Session A (User 1)                     │
│  - "Phân tích báo cáo Q1"               │
│  - "Viết email cho khách hàng"          │
│  Context: business tasks                │
├─────────────────────────────────────────┤
│  Session B (User 2)                     │
│  - "Debug lỗi Python"                   │
│  - "Review code này"                    │
│  Context: coding tasks                  │
└─────────────────────────────────────────┘

Vòng đời (Lifecycle) của Session

1. Tạo (Creation)

Khi nào tạo mới:

• Người dùng gửi tin nhắn lần đầu
• Sau khi reset (/new, /reset)
• Khi session cũ hết hạn

Session ID:

<channel>:<user-id>
Ví dụ: telegram:123456789
       whatsapp:+84123456789

2. Duy trì (Maintenance)

Mặc định:

• Session được tái sử dụng cho đến khi hết hạn
• AI nhớ context của cuộc trò chuyện
• File lưu tại: ~/.openclaw/agents/<agentId>/sessions/

Cấu trúc file:

~/.openclaw/agents/main/sessions/
├── sessions.json           # Metadata các session
├── telegram-123.jsonl     # Transcript Telegram user 123
├── whatsapp-456.jsonl     # Transcript WhatsApp user 456
├── main.jsonl             # Main session
└── *.deleted.<timestamp>    # Archive sau khi xóa

3. Hết hạn (Expiry)

Chính sách reset mặc định:

• Daily reset: 4:00 AM (giờ local của gateway host)
• Session "stale" khi last update < thời điểm reset gần nhất

Tùy chọn cấu hình:

{
  session: {
    // Reset hàng ngày lúc 4h sáng
    reset: {
      mode: "daily",
      atHour: 4,
    },
    // HOẶC reset sau idle 120 phút
    reset: {
      mode: "idle",
      idleMinutes: 120,
    },
    // HOẶC kết hợp: cái nào đến trước thì reset
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120, // Reset nếu idle 2 giờ
    },
  },
}

Theo loại chat:

{
  session: {
    resetByType: {
      direct: {
        // DM: idle 4 giờ
        mode: "idle",
        idleMinutes: 240,
      },
      group: {
        // Group: idle 2 giờ
        mode: "idle",
        idleMinutes: 120,
      },
      thread: {
        // Thread: daily reset
        mode: "daily",
        atHour: 4,
      },
    },
  },
}

4. Reset (Manual)

Cách reset:

/new              # Reset và bắt đầu session mới
/reset            # Tương tự /new
/new claude-sonnet # Reset + đổi model

Khi reset:

• Tạo session ID mới
• Context cũ bị xóa
• AI gửi "hello" greeting để xác nhận

Maintenance & Cleanup

Tại sao cần maintenance?

Không giới hạn session = Disk đầy, performance giảm.

Cấu hình maintenance

{
  session: {
    maintenance: {
      mode: "enforce", // "warn" | "enforce"
      pruneAfter: "30d", // Xóa session sau 30 ngày
      maxEntries: 500, // Giới hạn 500 session
      rotateBytes: "10mb", // Rotate file khi > 10MB
      maxDiskBytes: "1gb", // Giới hạn disk 1GB
      highWaterBytes: "800mb", // Bắt đầu cleanup ở 800MB
    },
  },
}

Các chế độ maintenance

Mode	Mô tả	Khi dùng
warn	Chỉ báo cáo, không xóa	Development
enforce	Tự động xóa theo policy	Production

Quy trình cleanup (enforce)

1. Prune stale entries (> pruneAfter)
2. Cap entry count (xóa oldest first)
3. Archive transcript files
4. Purge old deleted/reset archives
5. Rotate sessions.json (> rotateBytes)
6. Enforce disk budget (nếu maxDiskBytes set)

Commands maintenance

# Xem trạng thái session
openclaw sessions list

# Cleanup (dry-run - chỉ xem)
openclaw sessions cleanup --dry-run

# Cleanup thực tế
openclaw sessions cleanup

# Cleanup với JSON output
openclaw sessions cleanup --dry-run --json

# Cleanup specific session
openclaw sessions cleanup --active-key telegram:123456

Session Storage

Cấu trúc thư mục

~/.openclaw/
├── agents/
│   └── main/
│       └── sessions/
│           ├── sessions.json          # Index tất cả sessions
│           ├── telegram-123.jsonl    # Transcript user 123
│           ├── telegram-123.reset.2024-01-15T10-30-00.jsonl
│           └── whatsapp-456.deleted.2024-01-10T08-15-00.jsonl

Định dạng sessions.json

{
  "telegram:123456": {
    id: "telegram:123456",
    createdAt: "2024-01-15T08:00:00Z",
    updatedAt: "2024-01-15T10:30:00Z",
    messageCount: 42,
    lastModel: "anthropic/claude-3-5-sonnet",
  },
}

Identity Links (Nâng cao)

Vấn đề: Cùng một người dùng trên nhiều kênh khác nhau.

Giải pháp: Liên kết identity để chia sẻ context.

{
  session: {
    identityLinks: {
      alice: [
        "telegram:123456789",
        "discord:987654321012345678",
        "whatsapp:+84123456789",
      ],
    },
  },
}

Kết quả:

• Alice chat Telegram → Context lưu
• Alice chuyển Discord → AI nhớ context từ Telegram

Best Practices

1. Production: Dùng enforce mode

{
  session: {
    maintenance: {
      mode: "enforce",
      pruneAfter: "30d",
      maxEntries: 500,
      maxDiskBytes: "1gb",
    },
  },
}

2. Set cả time và count limits

• pruneAfter: Giới hạn thời gian
• maxEntries: Giới hạn số lượng
• maxDiskBytes: Giới hạn disk

3. Backup định kỳ

# Backup session data
cp -r ~/.openclaw/agents/main/sessions ~/backup/sessions-$(date +%Y%m%d)

4. Monitor session count

# Kiểm tra số lượng session
openclaw sessions list | wc -l

# Kiểm tra disk usage
du -sh ~/.openclaw/agents/main/sessions/

Commands tham khảo

Command	Mục đích
openclaw sessions list	Liệt kê tất cả sessions
openclaw sessions cleanup	Chạy maintenance
openclaw sessions cleanup --dry-run	Xem trước kết quả
/new	Reset session hiện tại
/compact	Nén ngữ cảnh (giảm token)

Tiếp theo?

• Bài 8: Cron Jobs - Tác vụ tự động theo lịch
• Bài 9: Multi-Instance - Chạy nhiều Gateway