openclaw sessions 用于列出 OpenClaw 网关中存储的对话 Session。它不检测信道连通性——想确认通道是否在线的要用 openclaw channels status --probe 或 openclaw health --verbose。默认只返回最新的 100 条 Session；想调整用 --limit <n> 或 --limit all。清理过期记录用 sessions cleanup，先加 --dry-run 预览再 --enforce 真正执行。

openclaw sessions

列出已存储的对话 Session。

openclaw sessions
openclaw sessions --agent work
openclaw sessions --all-agents
openclaw sessions --active 120
openclaw sessions --limit 25
openclaw sessions --verbose
openclaw sessions --json

Session 列表不是信道/提供商的存活检测。它只显示持久化的会话记录。一个安静的 Discord、Slack、Telegram 或其他通道可以在没有新消息时成功重连，而不会创建新 Session 行——直到有消息被处理才会产生。需要实时信道连通性时，用 openclaw channels status --probe、openclaw status --deep 或 openclaw health --verbose。

openclaw sessions 和 Gateway sessions.list 响应默认有上限，防止大数据量的存储垄断 CLI 或 Gateway 事件循环。CLI 默认返回最新的 100 条 Session；用 --limit <n> 设置更小或更大的窗口，或 --limit all 获取全部。JSON 响应中包含 totalCount、limitApplied 和 hasMore，用于告诉调用者还有更多行。

RPC 客户端可以传 configuredAgentsOnly: true，保持广泛的组合发现源，但只返回当前配置中存在的智能体的行。Control UI 默认使用该模式，所以已删除或仅磁盘上的智能体存储不会在 Sessions 视图中再次出现。

范围选择：

• 默认：已配置的默认智能体存储
• --verbose：详细日志
• --agent <id>：单个已配置的智能体存储
• --all-agents：聚合所有已配置的智能体存储
• --store <path>：显式指定存储路径（不能与 --agent 或 --all-agents 组合）
• --limit <n|all>：最多输出多少行（默认 100；all 恢复全部）

导出轨迹包：

openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --workspace .
openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --output bug-123 --json

这是 /export-trajectory 斜杠命令在所有者批准执行请求后使用的命令路径。输出目录始终解析到所选工作区的 .openclaw/trajectory-exports/ 下。

openclaw sessions --all-agents 读取已配置的智能体存储。Gateway 和 ACP Session 发现范围更广：它们还包括默认 agents/ 根目录或模板化 session.store 根目录下的纯磁盘存储。发现的存储必须解析到智能体根目录内的常规 sessions.json 文件；符号链接和根目录外的路径会被跳过。

JSON 示例：

openclaw sessions --all-agents --json：

{
  "path": null,
  "stores": [
    { "agentId": "main", "path": "/home/user/.openclaw/agents/main/sessions/sessions.json" },
    { "agentId": "work", "path": "/home/user/.openclaw/agents/work/sessions/sessions.json" }
  ],
  "allAgents": true,
  "count": 2,
  "totalCount": 2,
  "limitApplied": 100,
  "hasMore": false,
  "activeMinutes": null,
  "sessions": [
    { "agentId": "main", "key": "agent:main:main", "model": "gpt-5" },
    { "agentId": "work", "key": "agent:work:main", "model": "claude-opus-4-6" }
  ]
}

清理维护

立即运行维护（而不是等待下一个写入周期）：

openclaw sessions cleanup --dry-run
openclaw sessions cleanup --agent work --dry-run
openclaw sessions cleanup --all-agents --dry-run
openclaw sessions cleanup --enforce
openclaw sessions cleanup --enforce --active-key "agent:main:telegram:direct:123"
openclaw sessions cleanup --dry-run --fix-dm-scope
openclaw sessions cleanup --json

openclaw sessions cleanup 使用配置中的 session.maintenance 设置：

• 范围说明：openclaw sessions cleanup 维护 Session 存储、记录文件和轨迹侧车。它不清理 Cron 运行日志（cron/runs/<jobId>.jsonl）——这些由 Cron 配置 中的 cron.runLog.maxBytes 和 cron.runLog.keepLines 管理，详见 Cron 维护。

• Cleanup 还会修剪未被引用的原始记录、压缩检查点以及早于 session.maintenance.pruneAfter 的轨迹侧车；但仍在 sessions.json 中引用的文件会被保留。

• --dry-run：预览将被修剪/截断的条目数，但不写入。文本模式下，会打印每个 Session 的操作表（Action、Key、Age、Model、Flags），让你看到哪些会被保留、哪些会被删除。

• --enforce：即使 session.maintenance.mode 为 warn，也强制应用维护。

• --fix-missing：移除那些记录文件已缺失的条目，即使它们还没到正常淘汰时间。

• --fix-dm-scope：当 session.dmScope 为 main 时，清理由较早的 per-peer、per-channel-peer 或 per-account-channel-peer 路由留下的过期 peer-key 直连 DM 行。先用 --dry-run；应用清理会从 sessions.json 中移除这些行，并将其记录保存为已删除归档。

• --active-key <key>：保护特定活跃键不被磁盘预算驱逐。持久的对话指针（如群组会话和线程作用域的聊天会话）也会被年龄/计数/磁盘预算维护保留。

• --agent <id>：对单个已配置的智能体存储运行清理。

• --all-agents：对所有已配置的智能体存储运行清理。

• --store <path>：针对指定的 sessions.json 文件运行（离线修复时可用）。

• --json：打印 JSON 摘要。使用 --all-agents 时，输出包含每个存储的摘要。

当 Gateway 可达时，对已配置智能体存储的非干运行清理会通过 Gateway 发送，以与运行时流量共享同一个 Session 存储写入器。使用 --store <path> 进行显式的离线修复。

openclaw sessions cleanup --all-agents --dry-run --json：

{
  "allAgents": true,
  "mode": "warn",
  "dryRun": true,
  "stores": [
    {
      "agentId": "main",
      "storePath": "/home/user/.openclaw/agents/main/sessions/sessions.json",
      "beforeCount": 120,
      "afterCount": 80,
      "missing": 0,
      "dmScopeRetired": 0,
      "pruned": 40,
      "capped": 0
    },
    {
      "agentId": "work",
      "storePath": "/home/user/.openclaw/agents/work/sessions/sessions.json",
      "beforeCount": 18,
      "afterCount": 18,
      "missing": 0,
      "dmScopeRetired": 0,
      "pruned": 0,
      "capped": 0
    }
  ]
}

常见问题

Session 列表显示数量与预期不符，怎么确认是否被 limit 截断了？

加 --json 查看输出中的 totalCount 和 hasMore。如果 hasMore 为 true，说明还有更多行，可以用 --limit all 或更大的 --limit 值获取全部。默认 limit 是 100。

cleanup 的 --dry-run 和 --enforce 有什么区别？

--dry-run 只预览会删除多少条、哪些会被保留，不会真正修改存储。--enforce 是实际执行清理，即使配置的维护模式是 warn 也会强制执行。建议先 --dry-run 确认效果，再 --enforce。

清理 Session 后，为什么某些对话记录还在但无法访问？

可能是记录文件（transcript）已缺失，但 Session 行还没被清理。此时可以用 --fix-missing 选项，它会删除那些记录文件已不存在的条目。先用 --dry-run --fix-missing 预览会删哪些。

相关文档：

• Session 配置：配置参考
• CLI 参考
• Session 管理概念