会话目录
目录列表会并发等待每个提供方最多一秒。在该预算内完成的提供方会正常返回。较慢的提供方会返回 catalog.error.code: "catalog_pending";如果可用,会包含同一调用方和查询的最新可用页面,其中主机被标记为 pending: true,并附带过期结果消息。失败的目录枚举同样可以返回该页面,并带有 catalog.error.code: "catalog_stale",其消息中包含底层错误。已完成的主机结果是权威的,包括离线或不可用的主机;即使另一个主机处于待定状态,网关也不会用较旧的行替换这些结果。提供方负责其主机快照的新鲜度和失效。其他提供方仍可使用。迟到的结果会刷新下一次列表的页面;现有主机进度更新仍受支持。
这些回退页面在内存中受限,并会因配置或提供方注册变更以及目录归档操作而失效。每次投递都会重新检查当前可见性和本地会话身份。一秒预算涵盖提供方发现和排队,不包括会话投影准备或等待网关事件循环所花费的时间。
启用诊断时,慢提供方警告会报告经过时间,包括排队和异步 I/O。isMainThread 标识调用线程;它不测量 CPU 时间。调试日志会为每次提供方注册输出一次每个提供方 ID 及其 providerIdHash,以便在无需记录会话内容的情况下将警告归因。
导入转录¶
将原生转录导入 OpenClaw 的持久会话存储,以便在源工具清理其历史记录或源计算机不可用时保留它。在会话侧边栏中,打开目录行的菜单并选择 导入到 OpenClaw。当副本就绪时,成功通知会提供 打开已导入的会话。
从 CLI 导入一个转录或所有可见目录行:
openclaw sessions import claude <thread-id>
openclaw sessions import codex <thread-id> --host <host-id>
openclaw sessions import --all --dry-run
openclaw sessions import --all --json
捆绑提供方的目录 ID 为 claude、codex、openclaw、opencode 和 pi。使用 --catalog <id> 筛选批量导入,使用 --source-home <id> 从特定源主目录选择单个转录。有关连接选项和批量导入输出,参见 sessions CLI。
导入适用于任何可读目录,包括网关上的源、无头配对节点、macOS 应用和 Linux 应用。导入期间源必须可访问。导入的副本是一个由所选代理拥有的普通 OpenClaw 会话,带有源来源信息和不可信引用通知。导入的副本初始为 草稿,仅对其创建者和网关管理员可见。通过现有的会话共享控件发布副本,以与其他人共享。重新导入会保留副本的当前可见性,包括已明确发布的副本。当草稿被禁用时,导入的副本遵循网关的默认可见性。控制 UI 和 CLI --all 在可用时提供目录行的名称作为初始标题。单会话 CLI 导入使用通用的 Imported <catalog label> session 标题。RPC 调用方可以为新导入的会话提供 displayName(1–500 个字符);重新导入永远不会重命名现有会话。它没有原生模型锁定或节点执行绑定,并且导入不会恢复或分叉原生会话。源转录保持不变。
为该代理重新导入相同的目录、主机、源主目录和线程会更新同一个 OpenClaw 会话。仅追加之前未见的转录项;未更改的源添加零项。这是显式同步:再次导入时,后续原生消息会被保留。
导入保留目录的投影转录文本,而不是原始原生文件或原始提供方记录。每次导入最多保留 50,000 个转录项或 64 MiB 的投影历史,以先达到者为准,从最近的历史开始。提供方截断和现有的每项文本限制仍然适用。如果历史上限省略了较早的项,结果将带有 complete: false,并且 CLI 会警告副本不完整。importedItems 统计新追加的源项;totalItems 统计本次导入期间读取的源项,包括已保留的项。Claude 和 Codex 提供稳定的项 ID;对于项缺少 ID 的目录,重新导入通过内容识别项,因此一旦转录超过历史上限,相同的重复项可以被跳过。较小的续传种子仍限制为 200 项和 512 KiB。
导入需要 operator.write 权限,以及与读取目录转录相同的行可见性。在多用户模式下,非管理员调用方只能导入其可读的行。源读取访问权限通过每个目标写入进行检查;撤销会停止进一步复制,而已提交的内容仍保留在导入的会话中。导入副本不会采用原生会话,也不会更改点击其目录行时打开的内容。
Codex 会话和转录¶
官方 codex 插件可以在无头节点主机或原生 macOS 节点上公开未归档的 Codex 会话。目录注册不再依赖于 supervision.enabled;该选项控制面向代理的监督工具。在 Codex 插件配置中设置 sessionCatalog.enabled: false,可禁用操作员目录和配对节点目录命令,而无需禁用提供方或 harness。插件仍必须在两台计算机上处于活动状态,并且节点设置仍为本地同意:仅启用网关无法读取另一台计算机的 Codex 状态。
节点通告带版本的只读 codex.appServer.threads.list.v1 和 codex.appServer.thread.turns.list.v1 命令。具有 Codex CLI 的原生节点主机还会通告 codex.terminal.resume.v1。当这些命令首次出现时,批准节点配对升级。网关通过正常的插件节点策略调用它们,并按主机隔离故障。
配对节点行会作为 Codex 组显示在常规会话侧边栏中。
在每个主机内,行默认按项目文件夹分组;位于 .claude/worktrees/<name> 下的工作目录
会归入其源仓库,并且项目组可以像其他侧边栏部分一样折叠。使用目录头部中的文件夹图标
来展平或恢复项目组。相同的分组也适用于 Claude 会话目录。
默认情况下,选择某一行会打开常规聊天窗格,并通过有界的、基于游标分页的
thread/turns/list 调用读取其持久化转录,且使用完整项投影。使用行菜单、查看器头部或 在...中打开 Codex/Claude 会话 偏好设置,可在拥有该会话的计算机上的操作员终端中启动 codex resume <thread-id>。配对节点终端路径是由 Codex 插件拥有的允许列表 PTY 中继,而不是任意节点命令执行。
终端中继独立于配对节点聊天延续。已连接节点如果通告并允许这两个目录命令以及
codex.cli.session.resume,就可以为具有 operator.admin 权限的操作员继续一个已存储或空闲的交互式线程。
聊天会镜像有界的可见历史;后续消息会在该节点上针对确切线程运行原生 Codex CLI 恢复,
并返回最终文本,而不使用流式 App Server 框架桥接。
缺少所需命令的节点仍保持可读,但不支持聊天延续。
配对节点的 归档 不可用。
在 Gateway 计算机上,已存储和空闲的行可以启动一个独立的模型锁定聊天分支。 只有操作员确认没有其他 Codex 客户端正在使用它之后,二者才可归档;已存储行的实时活动状态仍未知。 活动行不能分支或归档。
有关设置、分页、本地和配对节点延续以及元数据安全边界,请参阅 监督 Codex 会话。
Claude 会话与转录¶
捆绑的 anthropic 插件默认会在 Gateway 和配对节点上发现未归档的 Claude CLI 和 Claude
Desktop 会话。设置
plugins.entries.anthropic.config.sessionCatalog.enabled: false 可禁用操作员目录和配对节点目录命令,而不会禁用 Anthropic
模型或 Claude CLI 后端。
当 Anthropic 插件已启用且其 Claude 项目目录存在时,远程 macOS 应用节点会通告
anthropic.claude.sessions.list.v1 和 anthropic.claude.sessions.read.v1:
如果应用环境设置了 CLAUDE_CONFIG_DIR,则为 $CLAUDE_CONFIG_DIR/projects/,否则为 ~/.claude/projects/。Claude Desktop 元数据
始终来自用户主目录。当这些命令首次出现时,批准节点配对升级。
具有可用 Claude CLI 的原生节点主机还会通告
anthropic.claude.terminal.resume.v1。符合条件的 CLI 和 Desktop 行可以在其所属主机上的操作员终端中打开
claude --resume <session-id>。
这是对原生会话的接管;与 OpenClaw 采用不同,它不会先分叉 Claude 会话。
目录将有效的 Claude CLI 项目索引记录与针对未索引 JSONL 转录的有界元数据回退相结合。该回退可识别
并发的非侧链交互式(cli)和无头 Agent SDK CLI(sdk-cli)会话。Claude Desktop 的本地元数据提供 Desktop 标题和归档状态。当两个来源指向同一个 Claude Code
会话 ID 时,Desktop 元数据优先;仅 CLI 的转录仍保持可见,因为 CLI 没有归档标志。转录读取使用不透明的
字节偏移游标和有界的向后文件读取,因此选择大型会话或加载较早页面时,不会将整个 JSONL 历史读入一个
Gateway 响应中。
目录 RPC 保持其正常方法作用域:sessions.catalog.list 和
sessions.catalog.read 需要 operator.read;sessions.catalog.continue、
sessions.catalog.import 和 sessions.catalog.archive 需要 operator.write。
目录可见性也遵循已认证的调用者。operator.admin
连接可以看到所有发现的行。当 Gateway 拥有少于两个人的持久配置文件时,目录可见性不变,行保持未过滤状态。
在多用户 Gateway 上,非管理员连接只能看到并读取、继续、导入或归档其记录的 createdActor.id 与调用者的 Gateway
配置文件匹配的行。未归属的主机 CLI 或桌面会话对这些调用者隐藏。
这是在一个受信任 Gateway 域内的隐私和协调边界,而不是恶意用户隔离;当人员不得共享对文件、凭据或工具的访问时,请使用独立的代理或 Gateway/主机信任边界。请参阅
多用户模式。
可以从常规聊天编辑器采用 Gateway 本地的 Claude CLI 行:
OpenClaw 导入有界的可见历史,在第一轮使用 --fork-session 恢复,并保持源转录不变。
无头节点主机可以选择加入相同的延续流程:
仅当此节点本地设置已启用且 claude 可执行文件在该节点上可解析时,节点才会通告 agent.cli.claude.run.v1。Gateway 无法
远程启用它。该命令还会经过节点现有的 exec 审批策略。当所有三个 Claude 命令均被通告并获 Gateway 节点命令策略允许时,该节点上的 Claude CLI
行即可继续:OpenClaw 导入有界历史,将采用的会话绑定到该节点及其目录报告的工作目录,并在那里运行每个一次性 claude -p 轮次。第一轮仍使用
--fork-session,以保留源转录。
放置在节点上的轮次使用节点的 Claude 默认设置。在 v1 中,它们不会接收 Gateway 回环 MCP 配置或 Gateway 技能插件,不能从 Gateway 转录重新播种,并拒绝附件和图片。Claude Desktop 行以及未通告运行命令的节点仍保持只读。macOS 应用节点尚未通告此命令,因此其行仍保持只读。
OpenCode 与 Pi 会话¶
捆绑的 OpenCode 和 ACPX 插件还会在 Gateway 和已配对节点上发现只读的原生会话目录。当安装了 opencode CLI 时,节点会通告 opencode.sessions.list.v1 / opencode.sessions.read.v1;当 Pi 的会话目录存在时,会通告 acpx.pi.sessions.list.v1 / acpx.pi.sessions.read.v1。当新命令首次出现时,批准节点配对升级。当匹配的 CLI 也可用时,节点会添加 opencode.terminal.resume.v1 或 acpx.pi.terminal.resume.v1;随后,现有的行菜单和查看器标题可以使用 opencode --session <id> 或 pi --session <id> 在其所属终端中重新打开所选会话。
OpenCode 通过其官方 CLI 的 JSON/导出接口读取。Pi 读取其文档中说明的 JSONL 会话存储,包括项目和全局 settings.json 会话目录,以及 PI_CODING_AGENT_DIR 和 PI_CODING_AGENT_SESSION_DIR 覆盖项。这两个目录默认启用;可在 Web UI 的 Config > Plugins 下关闭它们。
终端恢复使用已存储的会话工作目录,以及与 Codex 和 Claude 相同的白名单全双工 PTY 中继。它不会暴露任意节点命令执行。
OpenClaw 会话与转录¶
捆绑的 Session Share 插件 会将选定的原生 OpenClaw 会话从源 Gateway 发布到已配对的接收 Gateway。源节点主机以相同用户身份运行,并使用源 Gateway 的状态目录。在两端启用该插件,选择源会话组,并在 --commands 中仅使用 openclaw.sessions.list.v1 和 openclaw.sessions.read.v1 进行连接。
接收方会在源节点下的 OpenClaw sessions 中显示只读行。在角色受限的 Gateway 上,查看者需要查看他人会话的权限。这不允许在源端继续会话、访问终端或执行 worker。它与在节点上托管新会话是分开的,后者在 会话托管 中说明。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw