会话同步与附加
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 会话键使用以下格式:
<rest> 部分可以是简单名称、多个以冒号分隔的路由段,或以 UUID 结尾的值。配置为全局会话范围的 Gateway 会改用规范的 global 会话。当针对全局范围 Gateway 打开仅包含 agent 的 URL 时,CLI 会向 Gateway 查询其会话范围,并将该 URL 解析到该规范全局会话。
有关路由、隔离、生命周期和存储详情,请参阅 会话管理。
会话 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。
你也可以直接选择或查询最近的会话:
对于从 URL 或短引用进行 Gateway 支持的继续,请将目标传递给 openclaw tui:
openclaw tui https://claw.example.com/dashboard/main/deploy-monitor-6db92d48
openclaw tui deploy-monitor-6db92d48
你也可以直接在 CLI 根处粘贴完整的会话 URL:
这会在 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 回退,同时保留这些显式值以及精确目标配置的凭据可用。
首次连接时:
- 使用
--token或--password运行一次 TUI 或 attach 命令。 - 在该 Gateway 的 Control UI 中打开 设置 > 设备,并批准待处理请求。在 Gateway 主机上,你也可以改用
openclaw devices approve --latest预览最新请求,验证它,并运行打印出的openclaw devices approve <requestId>命令。 - 重试原始命令。OpenClaw 会将签发的 operator 设备 token 存储在 SQLite 中,归属于该精确的规范化 Gateway 源。
- 之后连接到同一源时可以使用已存储的设备 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