跳转至

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 输出保留精确的数值计数。

标志:

Flag Description
--agent <id> 一个已配置的代理存储(多个显式代理时必填)。
--all-agents 聚合所有已配置的代理存储。
--store <path> 旧版存储选择器路径(不能与 --all-agents 组合使用)。
--active <minutes> 仅显示过去 N 分钟内更新过的会话。
--limit <n\|all> 输出的最大行数(默认 100;all 恢复完整输出)。
--json 机器可读输出。
--verbose 详细日志输出。

--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。

当设置了会话颜色时(例如 "color": "blue"),JSON 会话行包含 color 字段。未着色会话和颜色已被清除的会话会省略该字段。

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

--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 import claude <thread-id>
openclaw sessions import codex <thread-id> --source-home <home-id>
openclaw sessions import claude <thread-id> --host <host-id> --agent work
openclaw sessions import --all --json
openclaw sessions import --all --catalog claude --limit 20 --dry-run
openclaw sessions import --all --host <host-id>

Claude Code 和 Codex 的目录 ID 分别是 claude 和 codex。其他支持转录读取的目录使用相同的命令。对于没有 --host 的单个转录,CLI 会在该目录中发现 Gateway 主机:如果存在 gateway:local 则优先使用,否则使用仅有的 Gateway 主机。如果不存在明确的 Gateway 主机,请显式传入 --host <host-id>。使用目录行的 host 和 sourceHomeId 选择另一台机器或原生工具主目录。--agent 选择目标代理。导入支持调用方可读取的 Gateway-local、paired-node、macOS 应用和 Linux 应用源。

导入会创建一个包含不可信参考材料的普通 OpenClaw 会话。导入的副本以草稿形式开始,仅对其创建者和 Gateway 管理员可见。通过会话共享控件发布副本以进行共享;重新导入会保留其当前的可见性。当草稿被禁用时,导入的副本遵循 Gateway 的默认可见性。它独立于原生工具清理来保留目录的投影消息;它不会恢复原生会话,也不会将副本绑定到其模型或机器。重复相同的导入会复用该副本,并仅追加新条目。每次导入最多读取 50,000 个条目和 64 MiB,达到该上限时保留最新的历史记录。现有的逐条目文本限制仍然适用。不完整的结果会警告较旧的历史记录已被省略。请参阅会话目录。

--all 会分页遍历可见的目录行,并按顺序导入它们。新副本使用目录行名称作为标题;重新导入会保留现有副本的标题。名称会去除首尾空白,并限制为 500 个 UTF-16 码元。--catalog 和 --host 用于筛选来源;--limit <n> 限制尝试的会话总数。--dry-run 列出选中的来源但不导入,不预测条目数量,也不执行写入授权检查。某个来源失败不会阻止其余来源的处理。如果任一导入或目录页获取失败,命令将以非零状态退出。

连接覆盖参数为 --url、--token、--password 和 --timeout <ms>(默认每个请求五分钟)。人类可读输出报告已导入、已更新或未更改的会话,并带有条目数量和最终摘要。--json 输出一个信封对象,包含 ok、operation: "import"、dryRun、results 和 summary。成功的结果包含来源定位符、status、sessionKey、importedItems、totalItems、complete 和 created;dry-run 结果包含 status: "would_import"。失败的结果包含 status: "failed" 和 error。

存档会话

通过运行中的 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 生命周期操作。它会保留转录,将会话标记为已存档,并将该会话从默认活动列表中移除。对于具有活动 placement 的 cloud-worker 会话,Gateway 会先停止 worker,协调其工作区,然后回收环境。如果 placement 仍在转换中,或者已经失败但无法证明其环境已消失,则会话仍保持未存档状态;请等待 placement 稳定后重试。Agent main 会话仍受保护。已存档的会话是成功的空操作(no-op)。使用 --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。

Warning

删除操作具有破坏性。在交互式终端中,它会在删除有效键之前询问一次。非交互式和 --json 删除需要 --yes。在编写批量清理脚本时,请先使用 --dry-run。

删除操作使用与 Control UI 相同的 sessions.delete 生命周期操作,并启用转录清理。Gateway 会移除活动会话行、转录世代、会话拥有的运行时状态、绑定、看板(boards)以及其他生命周期工件。对于普通会话,它会将转录保留为经过验证的 .jsonl.deleted.<timestamp> 存档;隐身(incognito)会话的转录会被移除,且不保留存档。保留的已删除会话存档仍可能有资格用于记忆搜索。要移除已索引的记忆,请在 Gateway 主机或容器上运行 openclaw memory forget --agent <agent-id> --session <id-or-key>,并使用该 Gateway 的状态和配置。请选择拥有已删除会话的 agent,包括 global 键的情况。记忆清理在本地运行;通过 --url 或已配置的远程 Gateway 删除时,不会将清理命令转发到该 Gateway。预览和删除详情请参阅 内存忘记。

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

两个生命周期命令:

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

生命周期命令会直接查找每个请求的键,包括在 Gateway 常规会话列表中不可见的 cron 运行会话。Dry-run 使用这些 Gateway 实际信息,将受保护的 agent-main 会话报告为失败,即使 CLI 使用不同的本地会话设置。已存档的会话仍然是成功的存档空操作。Dry-run 不会执行所有 Gateway 生命周期检查:global 预览仍可能显示 Gateway 会拒绝的存档或删除操作。明确选择的非默认 global 删除仍然受支持。真实的存档或删除请求才是权威依据。

带 agent 限定的别名在查找和变更过程中会保持其选定的所有者。例如,当 Gateway 使用规范键 global 描述某个会话时,sessions delete agent:work:main --yes 仍会以 work 为目标。

混合结果 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 时,它会向已配置的 Gateway 查询正在运行的会话,并优先跟踪匹配的本地会话,然后回退到最近活动的已存储会话。如果 Gateway 不可达,它会打印 Gateway unreachable: showing the most recently active session。显式提供 --store 会跳过 Gateway 查询,按活动顺序排序,并打印 explicit store: ordered by activity。显式提供 --session-key 只会选择该本地会话,而不进行 Gateway 查询。--tail <count> 控制进入跟随模式前打印多少条现有事件;默认值为 80,0 表示从当前末尾开始。--follow 会持续监视所选的 SQLite 支持的会话。会话密钥使用固定宽度的终端列,长密钥会在完整字素边界处截断,以便 CJK 字符、组合重音符号和组合表情符号保持进度行对齐。

完全限定的 --session-key 仅在未提供 --agent、--store 和 --all-agents 时选择其所属代理。显式为空或仅包含空白字符的 --agent 会被拒绝,而不是选择推断出的代理。

显式提供但未匹配任何已存储会话的 --session-key 会以非零状态退出,并给出列出有效密钥的指引;为空或仅包含空白字符的 --session-key 会被拒绝。未提供密钥时,空选择会打印 No sessions found. 并成功退出,包括使用 --follow 时。

进度视图有意保持保守:提示文本、工具参数和工具结果正文不会打印。工具调用会显示工具名称并附带 {...redacted...};工具结果会显示状态,例如 ok、error 或 done;模型完成行会显示提供方/模型和终止状态。提供方故障以及未投递的轮次显示 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

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

对于没有代理前缀的已存储密钥(例如 global),导出会使用已配置的默认代理或唯一代理。当配置了多个代理但没有默认代理时,请传入 --agent <id>。

清理维护

立即运行维护,而不是等待下一个写入周期。未提供 --store 时,清理会委托给可到达的 Gateway。破坏性本地清理需要独占的离线维护所有权;如果 Gateway 或其他活动所有者持有状态,命令会指明该所有者并拒绝执行。运行不带 --store 的清理以使用 Gateway,或先停止 Gateway 和其他所有者。在 Gateway 运行期间,试运行预览仍然可用:

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 维护会话存储、转录、轨迹行和旧版轨迹旁路文件。它不会修剪 cron 运行历史。Cron 会保留终态运行历史 7 天(lost 行保留 24 小时),并将每个作业和历史类别的最新 2000 行作为额外上限强制执行(Cron 配置)。
  • 清理还会修剪未被引用的旧版/归档转录产物、压缩检查点以及早于 session.maintenance.pruneAfter 的轨迹旁路文件;仍被 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,并在权威压缩文件中保留非活动转录。清理命令的重置/删除归档保留不会删除这些冷文件。

标志:

标志 描述
--dry-run 在不写入的情况下预览将被修剪/截断的条目数。在文本模式下,打印按会话划分的操作表(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 路由遗留的、按对端键控的过期直接私信行。请先使用 --dry-run;应用后会从 SQLite 中删除这些行,并将其遗留转录工件作为已删除归档保留。
--active-key <key> 保护某个特定的活动键免受自动维护影响。它仍会计入 maxEntries。持久化的外部会话指针(例如群组会话和线程范围聊天会话)也会通过按年龄/数量/磁盘预算维护而保留。
--agent <id> 为一个已配置的 agent 存储运行清理。
--all-agents 为所有已配置的 agent 存储运行清理。
--store <path> 在本地针对特定的 SQLite 数据库或遗留存储选择器路径运行。
--json 打印 JSON 摘要。使用 --all-agents 时,输出包含每个存储一个摘要。

当 Gateway 可达时,针对已配置 agent 存储的非 dry-run 清理会通过 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 插件,以便其会话拥有的资源随被删除的行一起回收,即使 agent 现在使用不同的模型。显式禁用或不受信任的插件不会被运行。如果它们的资源可能仍然保留,清理会在 stderr 上打印警告,但不更改 JSON 结果。dry-run 不会加载 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 数据。在准备副本时,保留 agent ID、目录布局和相关会话工件。使用普通复制文件,不要使用指向正在使用状态的符号链接或硬链接。

在副本内准备 openclaw.json,包含你要测试的维护设置和已复制 agent 的配置。保持其路径和插件配置与正在使用的安装隔离。以下示例显式选择已复制的 main agent 数据库;根据你的副本调整目录和 agent 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 可继续使用其独立的原始状态。将 --session-sqlite-agent 设置为已复制数据库的所有者;否则,显式 Doctor store 选择器默认使用 main。

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

压缩会话

为卡住或过大的会话回收上下文预算。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>:拥有该会话的 agent;对于 global 键为必填。
  • --url / --token / --password:Gateway 连接覆盖。
  • --timeout <ms>:可选的客户端 RPC 超时,单位为毫秒。
  • --json:打印原始 RPC 负载。

当 Gateway 报告压缩失败或无法访问时,该命令会以非零状态退出,因此定时任务和脚本不会将静默的空操作误认为成功。在两种模式下,缺失的会话都是错误。一个没有历史或没有可截断内容的现有会话仍保持为显式空操作。

Note

openclaw agent --message '/compact ...' 不是压缩路径。来自 CLI 的斜杠命令会被授权发送者检查拒绝;该调用会以非零状态退出,并给出指向此处的指导,而不是静默空操作。

sessions.compact RPC

openclaw gateway call sessions.compact --params '<json>' 接受:

字段 类型 必填 描述
key 字符串 是 要压缩的会话键(例如 agent:main:main)。
agentId 字符串 否 拥有该会话的 agent ID(用于 global 键)。
maxLines 整数 ≥ 1 否 截断到最后 N 行,而不是 LLM 摘要。

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
}

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw