跳转至

会话同步与附加

OpenClaw 在 Gateway 上保存共享会话状态。Control UI、移动客户端、ACP、openclaw tui <target> 和 openclaw attach <target> 会呈现该 Gateway 拥有的状态,而不是保留独立的会话副本。这样你就可以在多个客户端中打开同一个会话,而无需导出或复制其对话记录。

当你想在终端中继续对话时,使用 openclaw tui。当你希望在会话旁边使用编码 harness,并附带一个临时的、会话范围的 MCP 授权时,使用 openclaw attach。

嵌入式本地模式是独立的:openclaw tui --local、openclaw chat 和 openclaw terminal 使用本地 agent 运行时,并且不能接受会话目标。有关本地模式行为,请参阅 TUI CLI 参考。

一个 Gateway,多个客户端

Gateway 拥有会话行、对话记录历史、路由元数据和活动运行。客户端选择会话键,并通过 Gateway 协议读取或更新同一状态。移动节点仍然是连接到 Gateway 的外围设备;它不会成为第二个会话所有者。

大多数 agent 会话键使用以下格式:

agent:<agentId>:<rest>

<rest> 部分可以是简单名称、多个以冒号分隔的路由段,或以 UUID 结尾的值。配置为全局会话范围的 Gateway 会改用规范的 global 会话。当针对全局范围 Gateway 打开仅包含 agent 的 URL 时,CLI 会向 Gateway 查询其会话范围,并将该 URL 解析到该规范全局会话。

有关路由、隔离、生命周期和存储详情,请参阅 会话管理。

Control UI 聊天和仪表板链接共享以下路由语法:

/{chat|dashboard}/<agentId>
/{chat|dashboard}/<agentId>/<slug>-<shortId>
/{chat|dashboard}/<agentId>/<literal-rest-segments...>

已配置的 Control UI 基础路径会作为这些路由的前缀。仅包含 agent 的形式会打开该 agent 的主投影。字面形式将 agent:<agentId>: 之后以冒号分隔的会话键编码为路径段。

对于 rest 以 UUID 结尾的键,可共享的短形式使用该 UUID 开头的 8 到 32 个小写十六进制字符,并移除 UUID 连字符。短 ID 是权威的。显示名称 slug 是装饰性的,除非两个会话共享相同前缀,在这种情况下,一个精确的 slug 匹配会打破平局。对于 CLI 短链接目标,agent 段也是装饰性的:Gateway 会解析短 ID,而不将其限制为该 URL 中的 agent。

Gateway 方法 sessions.resolve 负责解析精确键、原始会话 ID、标签和短 ID。发现选择器会根据调用客户端的会话可见性进行过滤。短 ID 歧义结果最多包含十个最近的候选项,因此客户端可以要求你提供更长的前缀,而无需猜测。有关完整的字面编码和稳定性契约,请参阅 Control UI URL。

Gateway 版本要求

Gateway 在会话存储所有者处解析短引用,Control UI 和 CLI 使用返回的规范键和拥有 agent,包括通过过期 URL 到达的全局会话。短链接需要当前 Gateway。如果旧版或自定义 Gateway 拒绝 shortId 选择器,请升级它或使用完整会话键。

选择继续方式

CLI 接受三种目标语法:

  • 完整的 Control UI URL,例如 https://claw.example.com/dashboard/main/deploy-monitor-6db92d48。
  • Gateway 简写,例如 claw.example.com/main/deploy-monitor-6db92d48。
  • 裸短引用或完整键,例如 deploy-monitor-6db92d48 或 agent:main:telegram:12345。裸引用使用已配置或默认 Gateway。

会话 URL 不得包含凭据。首次与 Gateway 源配对时,请单独传递 --token 或 --password。

在终端中继续

从 Control UI 中,打开会话标题菜单并选择 在终端中继续…。对话框会复制一条不含凭据的 openclaw resume 命令,其中包含一个不透明的、带版本号的交接参数。该参数仅编码精确的 agent 限定会话键和所选 Gateway WebSocket URL。该键限制在 512 个用户感知字符内。其 URL 安全字母表无需 shell 引号,因此该命令可以安全地粘贴到常见 POSIX shell、PowerShell 和 cmd.exe 中。请在已为该 Gateway 配置好的 OpenClaw CLI 配置文件中运行它;终端会独立进行身份验证。Gateway 会在 TUI 附加之前规范化该键,并且缺失的会话会产生恢复指导,而不是创建另一个会话。会话 ACL 仍然适用。

查询路由的 Gateway URL 无法生成此不含凭据的命令,因为 Gateway 身份验证和存储的设备范围不是查询感知的。Control UI 不会剥离或复制查询。请使用手动身份验证的 CLI 目标并显式指定 --token 或 --password,或配置无查询的 Gateway URL。

你也可以直接选择或查询最近的会话:

openclaw resume
openclaw resume agent:main:deploy-monitor

对于从 URL 或短引用进行 Gateway 支持的继续,请将目标传递给 openclaw tui:

openclaw tui https://claw.example.com/dashboard/main/deploy-monitor-6db92d48
openclaw tui deploy-monitor-6db92d48

你也可以直接在 CLI 根处粘贴完整的会话 URL:

openclaw https://claw.example.com/dashboard/main/deploy-monitor-6db92d48

这会在 Gateway 返回的规范会话键上打开 TUI。它不会克隆对话记录或创建新会话。有关目标冲突、支持的裸 URL 选项和示例,请参阅 TUI。

附加编码 harness

将相同的 URL 或引用传递给 openclaw attach:

openclaw attach https://claw.example.com/dashboard/main/deploy-monitor-6db92d48
openclaw attach deploy-monitor-6db92d48

Gateway 首先解析会话,然后颁发一个限定于该会话的临时授权,并使用严格的 MCP 配置启动编码 harness。bearer Token 通过子进程环境传递,而不是 argv。正常启动会在 harness 退出时撤销授权;--print-config 会使其保持有效,直到其 TTL 过期。有关授权生命周期和启动选项,请参阅 Attach CLI。

每个 Gateway 源仅配对一次

URL 或 Gateway 简写会明确选择一个规范化 Gateway 源。OpenClaw 绝不会针对该目标复用来自其他源的已配置凭据或已存储设备 token。由 在终端中继续… 复制的无凭据命令有更窄的规则:openclaw resume 仅在其显式 WebSocket URL 逐字节匹配该配置文件的模式时,才可能复用当前 CLI 配置文件:本地和公共源目标仅在本地模式下符合条件,而只有 gateway.remote.url 在远程模式下符合条件。它从不搜索其他配置文件,任何主机、端口或路径不匹配都会回退到正常的显式凭据要求。精确的直连本地目标可以复用本地监听器的证书指纹,精确的配置远程目标可以复用已配置的远程 pin。公共源目标不会继承本地监听器的 pin;如果该代理源需要 pin,请显式传递 --tls-fingerprint。该负载不包含凭据;在交接旁显式提供的 --token、--password 或 --tls-fingerprint 值仍然优先。交接解析会抑制环境中的 OPENCLAW_GATEWAY_TOKEN 和 OPENCLAW_GATEWAY_PASSWORD 回退,同时保留这些显式值以及精确目标配置的凭据可用。

首次连接时:

  1. 使用 --token 或 --password 运行一次 TUI 或 attach 命令。
  2. 在该 Gateway 的 Control UI 中打开 设置 > 设备,并批准待处理请求。在 Gateway 主机上,你也可以改用 openclaw devices approve --latest 预览最新请求,验证它,并运行打印出的 openclaw devices approve <requestId> 命令。
  3. 重试原始命令。OpenClaw 会将签发的 operator 设备 token 存储在 SQLite 中,归属于该精确的规范化 Gateway 源。
  4. 之后连接到同一源时可以使用已存储的设备 token。显式 --token 或 --password 在整个连接期间始终优先。

Control UI 的继续命令不会执行这些首次连接步骤,也不会携带其凭据。使用前请独立配置或配对终端。如果 CLI 拒绝无效或被截断的交接,请从 Control UI 复制一条新命令,而不是编辑不透明参数。如果复制命令后该会话已被删除,请返回 Control UI,并从可用会话中复制一条命令。

当该客户端不应再连接时,从同一 Gateway 的 设备 页面吊销或移除设备。Token 不会跨源使用。通过 SSH 隧道进行的只读检查也会抑制已存储的设备认证,因为回环传输无法识别远程源;显式凭据仍然有效。

有关批准、轮换、吊销和网络指导,请参阅 设备、远程访问 和 Gateway 安全。

故障分类

Gateway 连接故障使用一个结构化优先的分类器。旧版 Gateway 仍可通过有界文本回退工作,因此健康检查、状态和 TUI 会给出相同的类别和恢复指导。

故障或类型 含义 处理方法
旧版 Gateway 短链接拒绝 Gateway 在 sessions.resolve 中不接受 shortId。 从该 Gateway 的 Control UI 复制完整会话密钥,或升级 Gateway。
会话缺失 所选 Gateway 找不到该密钥或短 ID。 对于已配置的 Gateway,运行 openclaw sessions list。对于 URL 目标,在该 Gateway 的 Control UI 中选择会话。
会话引用不明确 多个可见会话共享同一前缀,且 slug 未选中其中一个。 使用 CLI 显示的较长 ID 前缀之一,或复制完整密钥。
pairing-required 设备是新的,或现有设备需要角色、范围或元数据批准。 在 设置 > 设备 中批准待处理请求,或使用 openclaw devices approve --latest 预览它并运行打印出的精确 ID 命令,然后重试。
device-identity-required Gateway 要求此连接使用已签名的设备身份。 使用当前 OpenClaw 客户端,让它创建设备身份,并完成配对。
scope-mismatch 已存储的设备 token 有效,但缺少请求的 operator 范围。 查看 openclaw devices list,批准待处理的范围升级,然后重新连接。
auth-rejected 显式共享凭据错误,或已配对设备 token 已被吊销或轮换。 验证显式 Gateway 认证。对于过期的设备 token,使用 openclaw devices rotate --device <deviceId> --role operator 轮换它,或重新配对。
rate-limited 过多失败的认证尝试导致临时锁定。 等待锁定过期后重试。不要仅因为 Gateway 被限流就轮换凭据。
故障或类型 含义 处理方法
gateway-rejected Gateway 返回了另一个结构化拒绝,例如协议不匹配。 按照错误详情处理。对于版本偏差,在重试前更新较旧的客户端或 Gateway。
unreachable 无法访问所选源。 检查 Gateway 进程和路由。对于 *.ts.net 主机,连接 Tailscale 并确认 tailnet 可达性;对于 SSH,确认隧道正在运行。
TLS 指纹不匹配 提供的证书与配置或显式 pin 不匹配。 验证证书和预期指纹。仅在确认 Gateway 身份后更改 pin。

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