openclaw sessions¶

列出已存储的会话。

会话列表不是通道/提供商的存活检查。它们显示来自会话存储的已持久化会话行。一个安静的 Discord、Slack、Telegram 或其他通道可以在消息被处理之前成功重连，而不会创建新的会话行。当你需要实时通道连接性时，请使用 openclaw channels status --probe、openclaw status --deep 或 openclaw health --verbose。

openclaw sessions
openclaw sessions --agent work
openclaw sessions --all-agents
openclaw sessions --active 120
openclaw sessions --limit 25
openclaw sessions --store ./tmp/sessions.json
openclaw sessions --json

openclaw sessions list 是默认列表操作的显式写法，并接受相同的标志。

人类可读的列表和清理预览使用终端宽度表格。较长的模型名称和标志会换行而不会被截断，Unicode 键保持对齐。较长的键会显示其开头和结尾；要获取完整的会话键，请使用 openclaw sessions --json。

低于 1,000 的 Token 数以整数显示；更大的计数使用紧凑的 k 或 m 标签。JSON 输出保留精确的数值计数。

标志：

--store 接受文档中记载的旧版选择器形式，包括 sessions.json 和无后缀的自定义选择器。OpenClaw 会将该选择器解析为其物理 SQLite 目标，验证目标存在且可用，并报告其实际读取的物理路径。当必须选择拥有该存储的已配置代理时，请将其与 --agent <id> 组合使用。

--agent 和 --store 要求非空值。选择错误会以非零状态退出，并在设置 --json 时使用标准的 CLI JSON 失败信封。

openclaw sessions 和 Gateway 的 sessions.list RPC 默认有边界限制，因此大型长期存储不会独占 CLI 进程或 Gateway 事件循环。CLI 默认返回最新的 100 个会话；如需更小/更大的窗口，请传入 --limit <n>，或在确实需要完整存储时使用 --limit all。当调用方需要显示还存在更多行时，JSON 响应会包含 totalCount、limitApplied 和 hasMore。

当设置了会话颜色时，JSON 会话行会包含 color（例如，"color": "blue"）。未设置颜色的会话以及颜色已被清除的会话会省略该字段。

RPC 客户端可以传入 configuredAgentsOnly: true，以保留广泛的组合发现源，但仅返回当前配置中存在的代理的行。Control UI 默认使用该模式，因此已删除或仅存在于磁盘上的代理存储不会重新出现在“会话”视图中。

--all-agents 读取已配置的代理存储。Gateway 和 ACP 的会话发现范围更广：它们还包括从已配置的代理根或模板化的 session.store 根解析出的 SQLite 存储。旧版选择器路径必须在代理根内解析；符号链接和根外路径会被跳过。

openclaw sessions --all-agents --json：

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

归档会话¶

通过正在运行的 Gateway 归档一个或多个会话：

openclaw sessions archive "agent:main:scratch-1"
openclaw sessions archive "agent:main:scratch-1" "agent:main:scratch-2"
openclaw sessions archive "agent:work:scratch-1" --agent work
openclaw sessions archive "agent:main:scratch-1" --dry-run
openclaw sessions archive "agent:main:scratch-1" --json

归档使用与 Control UI 相同的 sessions.patch 生命周期操作。它会保留转录内容，将会话标记为已归档，并将该会话从默认活动列表中移除。对于具有活动放置的 cloud-worker 会话，Gateway 会先停止 worker，协调其工作区，并回收环境。如果放置仍在过渡中，或失败但没有其环境已消失的证明，则会话保持未归档状态；请等待放置稳定，然后重试。主代理会话仍受保护。已归档的会话是成功的空操作。使用 --dry-run 可验证每个键并预览结果，而不会更改会话状态。

归档原因会自动分配，并在 Control UI 中显示为人类可读文本。显式归档命令会记录 manual；由维护拥有的归档会记录其所属触发器。缺失的原因仍作为旧版状态受保护。基于保留期限的归档在磁盘压力下也保持受保护。只有被 maxEntries 显式归档的会话，才会在更便宜的清理层级耗尽后符合自动删除条件。

删除会话¶

通过正在运行的 Gateway 删除一个或多个会话：

openclaw sessions delete "agent:main:scratch-1"
openclaw sessions delete "agent:main:scratch-1" "agent:main:scratch-2" --yes
openclaw sessions delete "agent:work:scratch-1" --agent work --yes
openclaw sessions delete "agent:main:scratch-1" --dry-run
openclaw sessions delete "agent:main:scratch-1" --yes --json

重复的键只处理一次，按首次出现顺序处理，并在去除周围空白之后进行。这也适用于 sessions archive。

删除使用与控制台 UI 相同的 sessions.delete 生命周期操作，并启用转录清理。Gateway 会移除实时会话行、 转录生成、会话拥有的运行时状态、绑定、boards 以及其他生命周期产物。对于普通会话，它会保留转录，作为 经过验证的 .jsonl.deleted.<timestamp> 归档；隐身转录会被移除且不保留归档。保留的已删除会话归档仍可能 符合记忆搜索条件。要移除已索引的记忆，请在 Gateway 主机或容器上使用该 Gateway 的状态和配置运行 openclaw memory forget --agent <agent-id> --session <id-or-key>。选择拥有该已删除会话的 agent， 包括 global 键。记忆清理在本地运行；通过 --url 或已配置的远程 Gateway 删除时，不会将清理命令转发到 该 Gateway。有关预览和删除详情，请参阅 Memory forget。

如果受管 worktree 无法安全移除，该命令会报告保留的分支和路径，以便手动清理。

两个生命周期命令：

• 接受多个键，并为每个键报告一个有序结果；
• 使用 --agent <id> 选择所属 agent；对于默认 agent 之外的 global 键，这是必需的；
• 支持 --url、--token、--password 和 --timeout <ms> Gateway 连接覆盖；
• 当任何键未知或任何操作失败时返回非零退出码，同时仍处理其他有效键；
• 当设置 --json 时，输出一个稳定的 JSON 信封，包含 ok、operation、dryRun 和 results。

生命周期命令会直接查找每个请求的键，包括从 Gateway 的一般会话列表中隐藏的计划任务运行会话。Dry-run 使用这些 Gateway 事实将受保护的 agent-main 会话报告为失败，即使 CLI 使用不同的本地会话设置。已经 归档的会话仍保持为成功的归档空操作。Dry-run 不会执行所有 Gateway 生命周期检查：global 预览仍可能显示 Gateway 拒绝的归档或删除操作。显式选择的非默认 global 删除仍然受支持。实际的归档或删除请求是权威的。

示例混合结果 JSON：

{
  "ok": false,
  "operation": "archive",
  "dryRun": false,
  "results": [
    { "key": "agent:main:scratch-1", "ok": true, "status": "archived" },
    {
      "key": "agent:main:missing",
      "ok": false,
      "status": "not_found",
      "error": "Session not found. Run openclaw sessions list --json to choose a valid key."
    }
  ]
}

跟踪轨迹进度¶

openclaw sessions tail
openclaw sessions tail --follow
openclaw sessions tail --session-key "agent:main:telegram:direct:123" --tail 25
openclaw sessions --agent work tail --follow
openclaw sessions --all-agents tail --follow

openclaw sessions tail 将最近的运行时轨迹事件渲染为紧凑的进度行。如果没有 --session-key，它会先跟踪正在运行的会话，然后跟踪最新存储的会话。--tail <count> 控制跟随模式之前打印多少现有事件；默认值为 80，0 从当前末尾开始。--follow 会持续监视所选的 SQLite 支持的会话。会话键使用固定宽度的终端列，长键会在完整字素边界处截断，因此 CJK 字符、组合重音符号和组合 emoji 能保持进度行对齐。

完全限定的 --session-key 仅在不存在 --agent、--store 和 --all-agents 时选择其 agent。显式为空或仅包含空格的 --agent 会被拒绝，而不是选择推断出的 agent。

显式 --session-key 如果未匹配任何存储会话，会以非零退出码退出，并提供列出有效键的指导；空或仅包含空格的 --session-key 会被拒绝。如果没有键，空选择会打印 No sessions found. 并成功退出，包括使用 --follow 时。

进度视图有意保守：提示文本、工具参数和工具结果主体不会打印。工具调用显示工具名称和 {...redacted...}；工具结果显示状态，例如 ok、error 或 done；模型完成行显示 provider/model 和终止状态。Provider 故障和未交付的轮次显示 error；取消显示 aborted，超时显示 timeout，成功完成（包括已交付的部分回复）显示 done。

导出轨迹包¶

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

这是在所有者批准 exec 请求后，/export-trajectory 斜杠命令使用的命令路径。输出目录始终解析为所选工作区内的 .openclaw/trajectory-exports/。文本和 JSON 输出中的文件列表仅报告写入 bundle 的产物。

清理维护¶

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

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 维护会话存储、转录、轨迹行和旧版轨迹 sidecar。它不会修剪计划任务运行历史。计划任务保留终端运行历史 7 天（lost 行保留 24 小时），并将每个作业和历史类别的最新 2000 行作为额外上限强制执行（计划任务配置）。
• 清理还会修剪未引用的旧版/归档转录产物、压缩检查点以及早于 session.maintenance.pruneAfter 的轨迹 sidecar；仍被 SQLite 会话行引用的产物会保留。符合条件的空文件在试运行和已应用摘要中都计为已移除产物，即使它们释放的字节数为零。
• 清理会单独报告短生命周期的 Gateway 模型运行探针清理为 modelRunPruned。它仅匹配形如 agent:*:explicit:model-run-<uuid> 的严格显式键。保留期固定为 24h，并受压力门控：只有当会话条目维护/上限压力达到时，才会移除过期的探针行。运行时，模型运行清理发生在全局过期清理和上限处理之前。
• pruneAfter 会就地归档符合条件的持久会话，保留其 ID 和所有转录生成。清理报告 archive-age；存储的 archiveReason 为 age-retention。可丢弃的自动化行仍会删除。
• maxEntries 默认为 5000，并限制未归档会话行数量；已归档行不占用该配额。符合条件的普通溢出会报告为 archive-cap 并归档，而合成运行时溢出仍保持可丢弃。受保护的未归档行会报告为 keep，并且仍占用配额。如果这些受保护行阻止清理达到上限，未归档存储将保持高于上限。--enforce 不会移除该保护；请取消固定、等待活动工作完成，或显式删除你不再希望保留的会话。

可选的冷转录提取拥有自己的后台工作进程，并在 设置 → 代理默认值 → 会话 中提供 立即运行 操作。 它使用 session.maintenance.coldStorage.afterDays，并将非活动转录保存在权威压缩文件中。清理命令的重置/删除归档保留不会删除这些冷文件。

标志：

当 Gateway 可达时，针对已配置代理存储的非演练清理会通过 Gateway 发送，使其与运行时流量共享同一个会话存储写入器。使用 --store <path> 可显式离线修复 SQLite 数据库或遗留存储选择器。

自动离线回退仅适用于在连接之前无法访问已配置的本地 Gateway 的情况。远程 Gateway 连接失败或 OPENCLAW_GATEWAY_URL 覆盖会以错误退出，并保持本地存储不变， 即使所选 URL 使用回环 SSH 隧道也是如此。恢复远程 连接，或使用 --store <path> 显式选择本地存储。

当所选存储的父目录名为 agent 时，转录产物位于同级 sessions 目录中。这也适用于自定义路径： /backup/agent/sessions.json 会选择 /backup/agent/openclaw-agent.sqlite，其 归档位于 /backup/sessions。无论选择遗留路径还是 SQLite 文件，清理都会测量并修剪同一个产物目录。

离线清理会加载受信任且被允许的 harness 插件，以便其会话拥有的资源随删除的行一起回收，即使代理现在使用不同的模型。显式禁用或不受信任的插件不会运行。如果其资源可能仍然保留，清理会在 stderr 上打印警告，而不更改 JSON 结果。演练不会加载 harness 插件。

已应用的产物清理仅统计成功的文件删除。如果无法删除某个文件，它不会贡献已释放字节，并仍计入磁盘使用量。未引用产物清理和遗留磁盘预算执行会继续处理其他符合条件的文件。规范 SQLite 归档修剪在删除错误后停止，以保留其数据库恢复副本。如果使用量仍高于目标，请检查文件系统权限，并在解决删除故障后重试。

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

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

在副本上测试清理¶

使用独立的状态目录，在修改活动安装之前测量清理效果。创建支持 WAL 的 SQLite 备份或协调一致的停止状态副本；仅复制活动数据库的主 .sqlite 文件可能会遗漏已提交的 WAL 数据。在准备副本时，保留代理 ID、目录结构以及相关会话工件。请使用普通复制文件，而不是指向活动状态的符号链接或硬链接。

在副本中准备 openclaw.json，其中包含你要测试的维护设置和被复制代理的配置。将其路径和插件配置与活动安装隔离。以下示例显式选择被复制的 main 代理数据库；请调整目录和代理 ID 以匹配你的副本：

(
  export OPENCLAW_STATE_DIR="$HOME/openclaw-state-copy"
  export OPENCLAW_CONFIG_PATH="$OPENCLAW_STATE_DIR/openclaw.json"
  copied_db="$OPENCLAW_STATE_DIR/agents/main/agent/openclaw-agent.sqlite"

  openclaw sessions cleanup --store "$copied_db" --dry-run --json"
)

查看预览后，应用清理并压缩被复制的数据库：

(
  export OPENCLAW_STATE_DIR="$HOME/openclaw-state-copy"
  export OPENCLAW_CONFIG_PATH="$OPENCLAW_STATE_DIR/openclaw.json"
  copied_db="$OPENCLAW_STATE_DIR/agents/main/agent/openclaw-agent.sqlite"

  openclaw sessions cleanup --store "$copied_db" --enforce --json
  openclaw doctor --session-sqlite compact --session-sqlite-agent main --session-sqlite-store "$copied_db" --json
)

显式 --store 清理仅在本地进行。Doctor 要求其目标位于 OPENCLAW_STATE_DIR 内，并且没有 Gateway 正在使用该状态目录；活动 Gateway 可继续使用其独立的原始状态。将 --session-sqlite-agent 设置为被复制数据库的所有者；否则，显式 Doctor 存储选择器默认使用 main。

archive-age、archive-dashboard 和 archive-cap 会更改会话元数据，同时保留转录行。磁盘预算清理可以用压缩归档替换符合条件的历史记录，其规范载荷仍保留在 SQLite 中。Doctor 的 compact 步骤随后使用 VACUUM 回收空闲数据库页面，并报告压缩前后的数据库和 WAL 大小。它不会选择删除更多历史记录。请比较物理大小和保留的历史记录，而不仅仅是会话数量；受保护的数据可能使使用量高于配置的预算。有关归档所有权和保护规则，请参阅 存储维护和保留。

压缩会话¶

为卡住或超大的会话回收上下文预算。openclaw sessions compact <key> 是 sessions.compact Gateway RPC 的一等封装，需要正在运行的 Gateway。

openclaw sessions compact "agent:main:main"
openclaw sessions compact "agent:main:main" --max-lines 200
openclaw sessions compact "agent:work:main" --agent work --json

• 未指定 --max-lines 时，Gateway 会使用 LLM 对转录进行摘要。CLI 默认不设置客户端截止时间；Gateway 负责配置的压缩生命周期。
• 指定 --max-lines <n> 时，它会永久截断 SQLite 转录，仅保留最后 n 行。此路径不会创建备份归档。
• --agent <id>：拥有该会话的代理；对于 global 键为必填项。
• --url / --token / --password：Gateway 连接覆盖项。
• --timeout <ms>：可选的客户端 RPC 超时时间（毫秒）。
• --json：打印原始 RPC 载荷。

当 Gateway 报告压缩失败或不可达时，该命令以非零状态退出，因此 cron 和脚本不会将静默的空操作误认为成功。

sessions.compact RPC¶

openclaw gateway call sessions.compact --params '<json>' 接受以下字段：

示例 LLM 摘要响应：

{
  "ok": true,
  "key": "agent:main:main",
  "compacted": true,
  "result": { "tokensBefore": 243868, "tokensAfter": 34941 }
}

示例截断响应（--max-lines 200）：

{
  "ok": true,
  "key": "agent:main:main",
  "compacted": true,
  "kept": 200
}

相关¶

• 会话配置
• 会话管理
• 压缩
• CLI 参考
• openclaw resume — 将 TUI 附加到最近的 Gateway 会话
• Cloud Workers — 托管在远程工作节点上的会话