OpenClaw Session Reset 机制

Session reset 是 OpenClaw 创建新 sessionId 的行为，会导致对话上下文清零。理解触发条件对于避免长任务”失忆”至关重要。

触发条件分类

1. 自动触发（默认行为）

触发条件	默认值	配置项
每日定时重置（Daily Reset）	每天凌晨 4:00（Gateway 本地时间）	session.reset.mode = "daily"
空闲超时重置（Idle Reset）	未启用，需手动配置	session.reset.mode = "idle"

关键细节：

• Reset 是惰性触发，不是定时任务。下一条消息到来时检测是否跨过边界，才执行 reset
• Daily 模式的 freshness 基于 sessionStartedAt（session 创建时间），不是最后写入时间
• Idle 模式的 freshness 基于 lastInteractionAt（最后一次真实用户交互）
• heartbeat、cron、exec 等系统事件不会延长 idle 计时
• 两种模式同时配置时，哪个先到期哪个生效

2. 手动触发

• 聊天中输入 /new 或 /reset
• CLI：openclaw reset（可选范围：config / config+creds+sessions / full）

3. 磁盘/维护触发（需 mode: "enforce"）

默认 mode: "warn" 只报警不执行，需显式设为 enforce 才会自动清理：

• pruneAfter：超龄 session 被清理（默认 30 天）
• maxEntries：超出条目上限后按旧到新淘汰（默认 500）
• maxDiskBytes：超出磁盘预算后驱逐旧 session

Reset 具体做了什么

1. 为当前 sessionKey 分配全新 sessionId（UUID）
2. 旧 .jsonl 重命名为 .jsonl.reset.<timestamp> 归档（数据不丢失）
3. 新建空的 .jsonl，写入新 session header
4. 更新 sessions.json：同一 sessionKey 的 sessionId 指向新文件
5. 丢弃旧 session 排队的系统事件（heartbeat、cron、exec 通知）
6. 注入 startupContext（如配置）：第一轮注入最近几天的 memory/*.md

本质：干净的”换文件”操作，上下文清零是设计如此，不是 bug。

完整配置结构

{
  "session": {
    "reset": {
      "mode": "daily",      // daily | idle
      "atHour": 4,          // 仅 daily 模式，默认 4（凌晨 4 点，Gateway 本地时间）
      "idleMinutes": 60     // 仅 idle 模式，空闲多少分钟后重置
    },
    "resetByType": {
      "thread": { "mode": "daily", "atHour": 4 },
      "direct": { "mode": "idle", "idleMinutes": 240 },
      "group":  { "mode": "idle", "idleMinutes": 120 }
    },
    "resetTriggers": ["/new", "/reset"],
    "maintenance": {
      "mode": "warn",                    // warn | enforce
      "pruneAfter": "30d",
      "maxEntries": 500,
      "resetArchiveRetention": "30d",    // duration 或 false（禁用清理）
      "maxDiskBytes": "500mb",
      "highWaterBytes": "400mb"
    }
  }
}

字段说明

字段	默认值	说明
reset.mode	"daily"	重置模式：daily 或 idle
reset.atHour	4	daily 模式每天几点重置（Gateway 本地时间）
reset.idleMinutes	60	idle 模式空闲多少分钟后重置
resetByType.direct	—	覆盖 DM 会话的重置策略
resetByType.group	—	覆盖群组会话的重置策略
resetByType.thread	—	覆盖 thread 会话的重置策略
resetTriggers	["/new", "/reset"]	用户可手动触发 reset 的命令
maintenance.mode	"warn"	warn 只报警，enforce 自动清理
maintenance.resetArchiveRetention	同 pruneAfter	.reset.timestamp 归档文件保留时长

典型案例：Daily Reset 导致长任务失忆

现象：周六布置评测任务，周一问进度，Agent 完全不记得。

根因时间线：

时间（北京）	事件
周六 10:54	session cd0e434d 创建，开始评测任务
周六 23:49	评测完成，最后一条消息
周日 04:00	Daily Reset 边界到达（Gateway 时区 UTC+8）
周一 09:45	用户发消息 → 触发 reset，旧 session 归档，新 session d42894fe 创建

诊断方法：

# 确认是否有 session.reset 配置
openclaw config get session.reset
# 返回 "Config path not found" = 使用默认 daily 模式
 
# 查看 session 文件，确认 reset 归档
ls ~/.openclaw/agents/main/sessions/*.reset.*
 
# 确认 compactionCount（排除 compaction 触发）
openclaw sessions --json | jq '.[] | {sessionId, compactionCount}'

与 compaction 的区别：

• compaction：compactionCount > 0，transcript 文件不变，只是内容被压缩摘要
• reset：compactionCount = 0，旧 transcript 被归档，新建空文件

解决方案

方案一：改为 idle 模式（治标）

{
  "session": {
    "reset": {
      "mode": "idle",
      "idleMinutes": 10080
    }
  }
}

7 天不活跃才 reset，跨天长任务不会被打断。

方案二：长任务完成后写 memory（治本）

让 Agent 在完成长任务后主动将结果摘要写入 memory/ 目录。即使 reset 后，startupContext 会在第一轮注入最近的 memory 文件，恢复关键上下文。

# memory/agent-evaluation-2026-05-09.md
## Agent 评测任务（2026-05-09）
- 状态：已完成
- 结果：59 个 Agent，58 个成功，1 个失败
- 报告路径：/root/.openclaw/workspace/agent_evaluation/reports/

方案三：两者结合（推荐）

1. 配置合理的 idle reset 时间（避免无意义的每日清零）
2. 要求 Agent 在关键节点主动写 memory（防止任何形式的 reset 导致失忆）

相关

• openclaw — OpenClaw 主页
• openclaw-sessions-tools — sessions_spawn / sessions_send / sessions_yield 工具
• openclaw-multi-agent-timeout — 多 Agent 超时与挂起问题