Skip to main content
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 使用本地代理运行时，不能接受会话目标。有关本地模式的行为， 请参阅 TUI CLI 参考。

​
一个 Gateway，多个客户端

Gateway 拥有会话记录、转录历史、路由元数据和活动中的运行。客户端选择一个会话键，并通过 Gateway 协议读取或更新相同的状态。移动节点仍然是连接到 Gateway 的外围设备； 它不会成为第二个会话所有者。 大多数代理会话键采用以下形式：
<rest> 部分可以是一个简单名称、多个以冒号分隔的路由片段，或以 UUID 结尾的值。配置了全局会话范围的 Gateway 则使用规范的 global 会话。当针对全局范围的 Gateway 打开仅代理 URL 时，CLI 会向 Gateway 请求其会话范围，并将该 URL 解析为规范的全局会话。 请参阅会话管理，了解路由、隔离、生命周期和存储详情。

​
会话 URL 和短链接

Control UI 聊天和仪表盘链接共享以下路由语法：
配置的 Control UI 基础路径会为这些路由添加前缀。仅包含 agent 的形式会打开该 agent 的主投影。字面量形式会将 agent:<agentId>: 之后以冒号分隔的会话密钥编码为路径片段。 对于其余部分以 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 会使用返回的规范密钥。 较旧的 Gateway 可能会拒绝附加的 shortId 选择器。Control UI 可以回退到较旧的有界列表搜索，最多扫描五页。CLI 不会复现该分页策略：它会提示你从该 Gateway 的 Control UI 复制完整的会话密钥，或升级 Gateway。

​
选择如何继续

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。

​
在终端中继续

对于由 Gateway 支持的继续操作，将 URL 或引用传递给 openclaw tui：
你也可以直接在 CLI 根目录粘贴完整的会话 URL：
这会在 Gateway 返回的规范会话键上打开 TUI。它不会克隆会话记录，也不会创建新会话。有关目标冲突、支持的裸 URL 选项和示例，请参阅 TUI。

​
附加 coding harness

将相同的 URL 或引用传递给 openclaw attach：
Gateway 会先解析会话，然后生成限定于该会话的临时授权，并使用严格的 MCP 配置启动 coding harness。Bearer token 会通过子进程环境传递，而不是通过 argv 传递。正常启动时，harness 退出后会撤销授权；--print-config 会使授权保持有效，直到其 TTL 过期。有关授权有效期和启动选项，请参阅 Attach CLI。

​
每个 Gateway origin 仅配对一次

URL 或 Gateway 简写会权威地选择一个规范化的 Gateway origin。OpenClaw 绝不会为该目标重用来自其他 origin 的已配置凭据或已存储的设备令牌。 首次连接时：
  1. 使用 --token 或 --password 运行 TUI 或 attach 命令一次。
  2. 在该 Gateway 的 Control UI 中打开 Settings > Devices，并批准待处理的 请求。在 Gateway 主机上，你也可以改为使用 openclaw devices approve --latest 预览最新请求，核对后运行输出的 openclaw devices approve <requestId> 命令。
  3. 重试原始命令。OpenClaw 会将签发的操作员设备令牌存储在 SQLite 中，并与该完全规范化的 Gateway origin 绑定。
  4. 之后连接到同一 origin 时，可以使用已存储的设备令牌。显式提供的 --token 或 --password 始终对整个连接生效。
当客户端不应再连接时，请从同一 Gateway 的 Devices 页面撤销或移除该设备。令牌不会跨 origin 使用。通过 SSH 隧道进行的只读探测也会抑制已存储的设备身份验证，因为回环传输无法识别远程 origin；显式凭据仍然有效。 有关批准、轮换、撤销和网络指导，请参阅 Devices、Remote access 和 Gateway security。

​
故障分类

Gateway 连接故障使用一个结构化优先的分类器。较旧的 Gateway 仍可通过有界文本回退机制正常工作，因此 health、status 和 TUI 会提供相同的类别和恢复指导。

​
相关页面