OpenClaw Session 管理完全指南：Context 压缩、重置与持久化

OpenClaw Session 管理完全指南：Context 压缩、重置与持久化

用过 OpenClaw 的人都会遇到一个问题：聊着聊着，AI 的回复开始变得迟钝、前言不搭后语，甚至报错"context too large"。这背后是大模型固有的 context window 限制在作怪。

OpenClaw 为此设计了一套完整的 Session 管理机制。理解它，能让你的 AI Agent 长期稳定运行。

一、什么是 Session

OpenClaw 把每一个对话维度都映射成一个 Session：

• 与某人的私聊 → 一个 Session
• 某个群组 → 一个 Session
• Discord/Slack 某个 Thread → 一个 Session
• Cron 定时任务 → 每次运行独立生成新 Session

Session 的核心标识是 sessionKey（比如 agent:main:feishu:direct:ou_xxx），状态保存在：

~/.openclaw/agents/<agentId>/sessions/sessions.json       # Session 索引
~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl   # 完整对话历史

二、Context Window 与压缩机制

为什么需要压缩

每个大模型都有 context window 上限（比如 Claude Sonnet 是 200k tokens）。一个长对话会不断往 context 里塞入：

• 用户消息和 AI 回复
• Tool call 的输入和输出
• 系统提示和工作区文件

积累到一定程度，不是报错，就是模型开始"忘事"。

自动压缩（Auto-compaction）

OpenClaw 默认开启自动压缩。当 Session 接近 context window 上限时，自动触发：

1. 把旧的对话历史总结成一段 summary
2. 保留最近的消息不动
3. 把压缩结果持久化到 JSONL 文件

之后的对话会看到：

• summary（旧对话的摘要）
• 最近的消息

在 verbose 模式下你会看到 Auto-compaction complete，/status 也会显示压缩次数。

手动压缩

不用等自动触发，随时可以手动压缩：

/compact

还可以带指令，引导 AI 怎么总结：

/compact 重点保留所有技术决策和代码变更，忽略闲聊

什么时候手动压缩比较好？

• 切换话题前（把旧话题压缩掉，避免干扰）
• 感觉 AI 开始"混乱"时
• 即将开始一个重要的长任务前

压缩 vs 裁剪（Pruning）

这两个概念容易混淆：

配置裁剪策略：

{
  "agents": {
    "defaults": {
      "contextPruning": true
    }
  }
}

三、/new 与 /reset：开启全新对话

当你想彻底抛开旧的上下文、重新开始时：

/new
/reset

两个命令效果几乎相同：生成一个新的 Session ID，旧的 JSONL 文件保留存档（不会删除）。

唯一区别：/new 支持同时切换模型：

/new kimi
/new claude-opus

一条命令，重置 session + 切换模型，非常方便。

/compact 与 /new 的选择

四、Session 存储结构

sessions.json

Session 索引文件，记录每个 sessionKey 的元数据：

{
  "agent:main:feishu:direct:ou_xxx": {
    "sessionId": "abc123",
    "updatedAt": "2026-03-03T06:00:00Z",
    "inputTokens": 45000,
    "outputTokens": 12000,
    "totalTokens": 57000
  }
}

JSONL 历史文件

每条消息、每次 tool call 都记录在 .jsonl 文件里，按行存储 JSON。这是 OpenClaw 的"单一真相来源"，gateway 重启后从这里恢复状态。

五、DM Session 的多用户隔离

默认情况下，所有私聊共享同一个 Session（dmScope: "main"）。如果你的 Agent 会被多人使用，必须开启隔离，否则用户之间的上下文会互相泄漏！

// ~/.openclaw/openclaw.json
{
  "session": {
    "dmScope": "per-channel-peer"
  }
}

dmScope 选项：

六、Session 维护与清理

长期运行的 Agent，sessions.json 会不断增长。OpenClaw 内置了自动维护策略：

默认配置：

{
  "session": {
    "maintenance": {
      "mode": "warn",          // warn=只报告，enforce=真正清理
      "pruneAfter": "30d",     // 30天未活跃的 Session 归档
      "maxEntries": 500,        // 最多保留 500 个 Session 条目
      "rotateBytes": "10mb"    // sessions.json 超过 10MB 时轮转
    }
  }
}

建议生产环境开启 enforce 模式：

{
  "session": {
    "maintenance": {
      "mode": "enforce",
      "pruneAfter": "14d",
      "maxEntries": 200
    }
  }
}

手动触发清理：

openclaw sessions cleanup
openclaw sessions cleanup --dry-run  # 先预览，不真正删除

七、实用命令速查

# 查看当前 Session 状态（token 使用量、压缩次数）
/status

# 查看 context 组成（哪些东西占了多少 token）
/context list
/context detail

# 压缩对话历史
/compact
/compact 保留技术决策，忽略闲聊

# 开新 Session
/new
/new kimi          # 同时切换到 kimi 模型

# 查看所有 Session
openclaw sessions --json

# 清理过期 Session
openclaw sessions cleanup

八、总结

OpenClaw 的 Session 管理是一个设计精良的系统：

• 自动压缩保证了长对话的连续性，不用担心 context 爆掉
• 手动 /compact 让你在切换话题时保持清晰
• /new 重置 适合需要全新上下文的场景，还能顺便换模型
• 多用户隔离 是部署给多人使用时的安全必选项
• 维护策略 保证磁盘不会无限增长

理解这套机制，你的 OpenClaw Agent 就能在长时间、高强度使用下保持稳定和高效。