企业官网建设流程全解析

• 人工智能
• 大模型
• LLM 网关
• AI Agent
• 即时通讯

本指南完整讲解 OpenClaw 的openclaw sessions命令族：如何列出已存储的会话记录、按 Agent / 时间窗口 / 存储文件多维度筛选、以 JSON 形式输出供脚本消费，以及通过openclaw sessions cleanup手动触发session.maintenance维护清理。阅读完成后，你将掌握会话存储的定位方式、每条会话的字段含义、dry-run 预演与 enforce 强制执行的正确用法，并能结合配置对sessions.json做磁盘与条目数量层面的日常养护。

命令概览：一个命令，两个职责

openclaw sessions在 OpenClaw 中承担两类职责：

1. 列表查看：列出当前状态目录下存储的会话（session）记录，包括会话 key、最近更新时间、使用的模型、Token 占用、会话 ID 与各种运行标记（如think、verbose、aborted等）。
2. 维护清理：通过子命令openclaw sessions cleanup手动触发会话存储的保留与清理策略，功能与配置节session.maintenance完全对应。

在 CLI 注册层（cli/program/register.status-health-sessions.ts）可以看到，sessions命令与health命令同属一个注册模块，并支持--json、--verbose、--store、--agent、--all-agents等父级选项；子命令cleanup则额外提供--dry-run、--enforce、--fix-missing、--active-key等维护专用选项。

列出会话：openclaw sessions基础用法

最基础的用法不带任何参数，直接列出默认 Agent 会话存储中的全部会话：

openclaw sessions

输出为表格形式，包含以下列（字段定义可参见 commands/sessions.ts 与 commands/sessions-table.ts）：

表格按updatedAt降序排列，最新更新的会话排在最前。终端支持彩色输出时（isRich()判断），不同Kind会使用不同的主题色渲染，方便快速识别群聊与全局会话。

提示：命令帮助中还说明，Token 占用需要 Agent 上报后才会显示；可通过配置agents.defaults.contextTokens设置上下文窗口大小，从而在表格中呈现占用百分比。

作用域选择：默认、指定 Agent、全部 Agent 与显式存储路径

会话存储按 Agent 隔离，因此sessions与sessions cleanup都支持四种作用域选择方式：

openclaw sessions openclaw sessions --agent work openclaw sessions --all-agents openclaw sessions --store ./tmp/sessions.json

其中--active <minutes>参数可以只展示最近 N 分钟内更新过的会话，例如只显示最近 2 小时内的活动会话：

openclaw sessions --active 120

在源码实现（config/sessions/targets.ts）中可以确认这些作用域规则：

• --agent与--all-agents同时使用会直接报错；
• --store与--agent/--all-agents组合也会报错；
• --agent指定的 id 必须是配置中已存在的 Agent（listAgentIds(cfg)），否则提示"Unknown agent id"，并建议使用openclaw agents list查看已配置 Agent；
• --all-agents会对每个 Agent 解析其存储路径，再按路径去重；
• --store传入的路径支持~主目录前缀与{agentId}占位符（见 config/sessions/paths.ts 的resolveStorePath），例如配置中的默认写法~/.openclaw/agents/{agentId}/sessions/sessions.json。

JSON 输出：让脚本与 Agent 程序可消费

--json让结果以结构化 JSON 输出，适合接入 shell 脚本、CI 流水线或其他程序。多 Agent 聚合时输出形如：

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, "activeMinutes": null, "sessions": [ { "agentId": "main", "key": "agent:main:main", "model": "gpt-5" }, { "agentId": "work", "key": "agent:work:main", "model": "claude-opus-4-5" } ] }

JSON 顶层字段说明：

会话 key 遵循agent:<agentId>:<会话键>的结构，由 routing/session-key.ts 的parseAgentSessionKey解析，可据此推断会话归属的 Agent。

会话存储到底在哪里

默认情况下，每个 Agent 的会话存储位于：

<state-root>/agents/<agentId>/sessions/sessions.json

其中<state-root>默认为~/.openclaw（受环境与主目录解析影响，见 infra/home-dir.ts），因此典型路径是：

/home/user/.openclaw/agents/main/sessions/sessions.json

除了sessions.json索引文件，同一目录下还有按会话 ID 存放的转录（transcript）文件<sessionId>.jsonl（带话题时为<sessionId>-topic-<topicId>.jsonl），以及维护轮转产生的sessions.json.bak.<timestamp>备份。路径解析逻辑集中在 config/sessions/paths.ts，包括：

• resolveDefaultSessionStorePath(agentId)：计算默认sessions.json路径；
• resolveSessionTranscriptPath(sessionId, agentId, topicId)：计算转录文件路径，会话 ID 会经过SAFE_SESSION_ID_RE合法性校验（/^[a-z0-9][a-z0-9._-]{0,127}$/i）；
• 所有会话文件必须位于对应sessions/目录内，超出目录的路径会被拒绝（防止越界访问）。

cleanup 维护清理：手动触发保留策略

会话存储会随使用持续增长，因此 OpenClaw 内置了维护机制，默认在写入周期中自动运行。如果你不想等待下一次写入触发，可以手动执行openclaw sessions cleanup：

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:dm:123" openclaw sessions cleanup --json

cleanup使用配置中的session.maintenance设置。作用域与sessions列表命令一致（--agent/--all-agents/--store）。

重要边界：openclaw sessions cleanup只维护会话存储（sessions.json）与会话转录文件，不会清理 cron 运行日志（cron/runs/<jobId>.jsonl）。cron 日志由cron.runLog.maxBytes与cron.runLog.keepLines管理，相关配置见 Cron 配置，维护策略见 Cron 维护。

关键选项

dry-run 预演输出示例

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, "pruned": 40, "capped": 0 }, { "agentId": "work", "storePath": "/home/user/.openclaw/agents/work/sessions/sessions.json", "beforeCount": 18, "afterCount": 18, "pruned": 0, "capped": 0 } ] }

文本模式下，dry-run 会先打印摘要（存储路径、维护模式、条目数变化、将删除的缺失转录数 / 过期数 / 溢出截断数 / 磁盘预算清理数），随后打印"Planned session actions"动作表。动作取值在源码 commands/sessions-cleanup.ts 中定义：

enforce 实际执行

不带--dry-run时命令会真正写盘。执行流程（commands/sessions-cleanup.ts）：

1. 解析目标存储列表（resolveSessionStoreTargetsOrExit）；
2. 先对每个目标做一次预演计算（预览结果同时用于最终摘要）；
3. 通过updateSessionStore原子地应用维护：依次执行缺失转录清理（若开启--fix-missing）、过期条目清理、条目数截断与磁盘预算清理；
4. 输出每个存储的"Applied maintenance"结果。

维护模式为warn时，写入循环会先检查"活跃会话是否会被逐出"（getActiveSessionMaintenanceWarning，见 config/sessions/store-maintenance.ts），若活跃会话面临被清理的风险则跳过强制执行并输出警告；--enforce正是为了绕过这种warn限制。--active-key则用于在磁盘预算逐出中显式保护某个活跃 key（见 config/sessions/disk-budget.ts）。

维护策略的配置参考：session.maintenance

cleanup的行为完全由配置节session.maintenance驱动，完整字段与默认值可参见 Gateway 配置参考的 Session 小节：

{ session: { maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", maxEntries: 500, rotateBytes: "10mb", resetArchiveRetention: "30d", // duration 或 false maxDiskBytes: "500mb", // 可选硬盘硬预算 highWaterBytes: "400mb", // 可选清理目标水位 }, }, }

这些字段的解析与校验在 config/zod-schema.session.ts 中完成：pruneAfter/rotateBytes/resetArchiveRetention/maxDiskBytes/highWaterBytes在配置加载时即经过parseDurationMs/parseByteSize校验，格式非法会直接给出配置校验错误；底层默认值则集中在 config/sessions/store-maintenance.ts：

• pruneAfter默认 30 天（30 * 24 * 60 * 60 * 1000ms）；
• maxEntries默认 500；
• rotateBytes默认 10 MB（10_485_760字节）；
• mode默认warn；
• 磁盘高水位比率默认0.8（即highWaterBytes未配置时取maxDiskBytes的 80%）。

底层维护逻辑拆解：prune、cap 与 rotate

了解了配置之后，可以深入源码看维护到底做了什么。核心实现位于 config/sessions/store-maintenance.ts：

1. 过期条目清理（prune）

pruneStaleEntries计算cutoffMs = Date.now() - pruneAfterMs，遍历存储中每条记录，凡是updatedAt早于阈值的条目一律删除；没有updatedAt的条目会保留（无法判断其新旧程度）。函数直接原地修改存储对象并返回被删除的条数。

2. 条目数截断（cap）

capEntryCount在条目数超过maxEntries时，按updatedAt降序排序（无updatedAt的排最后、最先被删），删除超出上限的最旧条目，返回被截断的条数。

3. 文件轮转（rotate）

rotateSessionFile检查sessions.json当前文件大小，若超过rotateBytes，则将当前文件重命名为sessions.json.bak.<timestamp>，并清理旧备份、只保留最近 3 个.bak.*文件。轮转失败（如文件恰好消失）会被安全吞掉，不影响后续写入。

4. 磁盘预算（disk budget）

当配置了maxDiskBytes时，enforceSessionDiskBudget（见 config/sessions/disk-budget.ts）会统计会话目录总占用（totalBytesBefore），超过预算后按最旧优先策略删除转录文件与会话条目（removedFiles/removedEntries），直到降到highWaterBytes目标水位；--active-key指定的 key 会被跳过，避免误伤正在活跃的会话。

维护触发时机与 warn 模式行为

除了手动执行cleanup，维护还会在会话存储的常规写入流程中自动发生（updateSessionStore，见 config/sessions/store.ts）。mode: "warn"时：

• 若活跃会话将因过期或截断被移除，会发出session maintenance would evict active session; skipping enforcement警告并跳过强制清理（对应源码 config/sessions/store.ts 中shouldWarnOnly分支与getActiveSessionMaintenanceWarning）；
• 磁盘预算以warnOnly模式只记录警告，不实际删除。

这也是为什么文档建议定期用--dry-run预演：它能在不写盘的情况下告诉你"当前配置下哪些会话会被清理"，避免某次强制执行误删重要会话。而--enforce则是你在确认预演结果后，把维护从"告警"升级为"执行"的开关。

相关资源

• 会话配置完整字段与取值：Gateway 配置参考 · Session
• 会话存储路径解析：config/sessions/paths.ts
• 维护策略实现：config/sessions/store-maintenance.ts
• 磁盘预算实现：config/sessions/disk-budget.ts
• 列表命令实现：commands/sessions.ts、表格渲染：commands/sessions-table.ts
• 清理命令实现：commands/sessions-cleanup.ts
• CLI 注册与选项定义：cli/program/register.status-health-sessions.ts

• 人工智能
• 大模型
• LLM 网关
• AI Agent
• 即时通讯