会话同步与附加

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

当你想在终端中继续对话时，使用 openclaw tui。当你想在会话旁边获得一个带有临时的、会话级 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 解析为对应的规范全局会话。

有关路由、隔离、生命周期和存储的详细信息，请参阅会话管理。

会话 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 不会移除或复制查询部分。请使用通过显式 --token 或 --password 手动认证的 CLI 目标，或配置一个不含查询的 Gateway URL。

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

openclaw resume
openclaw resume agent:main:deploy-monitor

若要在 Gateway 支持下通过 URL 或短引用继续会话，请将目标传给 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。

附加编码工作台¶

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

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

Gateway 会先解析会话，然后铸造一个仅限该会话范围的临时授权，并以严格的 MCP 配置启动编码工作台。持有者令牌通过子环境传递，而不是 argv。正常启动会在工作台退出时撤销授权；--print-config 会使其保持有效，直到 TTL 过期。有关授权有效期和启动选项，请参阅 Attach CLI。

每个 Gateway 源仅配对一次¶

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

首次连接时：

使用 --token 或 --password 运行一次 TUI 或 attach 命令。
在该 Gateway 的控制界面中打开 设置 > 设备，并批准待处理请求。在 Gateway 主机上，您也可以使用 openclaw devices approve --latest 预览最新请求，验证后运行打印出的 openclaw devices approve <requestId> 命令。
重试原始命令。OpenClaw 会将签发的操作员设备 Token 存储在 SQLite 中，位于该精确规范化 Gateway 源下。
之后到同一源的连接可以使用已存储的设备 Token。显式 --token 或 --password 始终在整个连接中优先。

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

当该客户端不应再连接时，从同一 Gateway 的设备页面吊销或移除设备。Token 不会跨源。通过 SSH 隧道的只读探测也会抑制已存储的设备身份验证，因为回环传输不会识别远程源；显式凭据仍然有效。

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

故障分类¶

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

故障或类型	含义	处理方法
旧版 Gateway 短链接拒绝	Gateway 不接受 `sessions.resolve` 中的 `shortId`。	从该 Gateway 的控制界面复制完整会话密钥，或升级 Gateway。
会话缺失	所选 Gateway 找不到该密钥或短 ID。	对于已配置的 Gateway，运行 `openclaw sessions list`。对于 URL 目标，在该 Gateway 的控制界面中选择会话。
会话引用不明确	多个可见会话共享前缀，且 slug 未选择一个。	使用 CLI 显示的较长 ID 前缀之一，或复制完整密钥。
`pairing-required`	设备是新的，或现有设备需要角色、范围或元数据批准。	在设置 > 设备中批准待处理请求，或使用 `openclaw devices approve --latest` 预览并运行打印出的精确 ID 命令，然后重试。
`device-identity-required`	Gateway 要求此连接使用签名的设备身份。	使用当前 OpenClaw 客户端，让它创建设备身份，并完成配对。
`scope-mismatch`	已存储的设备 Token 有效，但缺少请求的操作员范围。	查看 `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