openclaw resume¶

将终端 UI 附加到现有的 Gateway 会话。该会话保留在 Gateway 上；resume 会选择该会话并打开现有的 TUI。

openclaw resume
openclaw resume <query>
openclaw resume --handoff <payload>

如果没有查询，OpenClaw 会显示最近七天内活跃的最多 50 个会话。如果提供了查询，精确的会话密钥优先；否则 OpenClaw 要求在会话密钥、显示名称和标签中存在唯一的子字符串或模糊匹配。

选择器会省略裸 global 行，因为它们不标识拥有它的代理。要附加此类会话，请传入完全限定的密钥，例如 openclaw resume agent:main:global。

如果查询有歧义，OpenClaw 会打印匹配的候选并退出，状态为 1。如果没有匹配的近期会话，它会建议使用选择器和 openclaw sessions，然后退出，状态为 1。

选项¶

--handoff 不能与位置查询或 --url 结合使用，因为它会权威地提供这两者。你可以将其与 --token、--password 和 --tls-fingerprint 结合使用；这些显式认证值保持其通常的最高优先级。

resume 绝不会自动启动 Gateway。如果配置的 Gateway 不可用，请启动或修复它，然后重新运行命令。

resume 在可能的情况下会解析配置的 Gateway 认证 SecretRef，以用于令牌/密码认证（env/file/exec/store 提供程序）。

当存在 --handoff 时，它会提供目标 Gateway URL。否则，Gateway 目标的优先级顺序为：显式 --url，然后是 OPENCLAW_GATEWAY_URL，再然后是当 gateway.mode 为 remote 时的 gateway.remote.url，最后是本地回环 Gateway。对于该本地 Gateway，OPENCLAW_GATEWAY_PORT 优先于运行中的 Gateway 记录的活跃端口，而该端口又优先于已配置或默认的 gateway.port。

显式目标通常需要显式的 --token 或 --password；OpenClaw 不会从其他已配置目标借用凭据或 TLS 固定值。resume 对于从 Control UI 复制的 handoff 有一个狭窄的例外：当其中的 Gateway URL 与当前配置文件的规范目标逐字节匹配时，它可以复用该配置文件已配置的交互式认证、SecretRef 以及存储的精确来源设备认证。在本地模式下，合格的目标是当前本地目标，其中 gateway.controlUi.basePath 和 gateway.publicOrigin 使用该基础路径转换为 WebSocket 形式。在远程模式下，只有精确的 gateway.remote.url 是合格的。TLS 固定值的所有权更窄：精确的直连本地目标可以复用本地 Gateway 证书指纹，精确配置的远程目标可以复用 gateway.remote.tlsFingerprint；公共来源目标永远不会继承本地监听器的固定值。当该公共来源需要固定值时，请显式传入 --tls-fingerprint。在正常的显式目标策略下，主机、端口、路径、配置文件、查询或片段不匹配时会失败关闭（fail closed）。OpenClaw 永远不会扫描其他配置文件来寻找匹配项。Handoff 连接还会忽略环境中的 OPENCLAW_GATEWAY_TOKEN 和 OPENCLAW_GATEWAY_PASSWORD 回退，因此无法将另一个 Gateway 的 shell 凭据带入所选目标。由精确配置目标拥有的显式标志和凭据仍然可以使用。

从 Control UI 继续¶

打开所选会话的头部菜单，然后选择 在终端中继续…。对话框会显示一条可复制的 openclaw resume --handoff <payload> 命令。该不透明载荷带有版本、有界，并使用无填充的 URL 安全 base64 字符集编码，因此该命令无需引用，即可安全粘贴到常见的 POSIX shell、PowerShell 和 cmd.exe 中。编码后的参数限制为 4096 个字符；其中，代理限定的会话密钥限制为 512 个用户感知字符，Gateway URL 限制为 2048 个字符。它只包含确切的限定会话密钥和所选 Gateway WebSocket URL（包括任何 Control UI 基础路径）。它不包含令牌、密码、设备凭据或引导凭据，并且浏览器不会执行它。

当所选 Gateway URL 使用查询字符串时，Control UI 不提供此命令。Gateway 认证和存储的设备作用域基于来源（origin），不感知查询字符串，因此 OpenClaw 绝不会将该查询字符串剥离或复制到无凭据的 handoff 中。请使用显式提供 --token 或 --password 的手动认证 CLI 目标，或配置无查询字符串的 Gateway URL。

在已经配置好的 OpenClaw 终端中运行该命令。终端会独立认证。在打开 TUI 之前，resume 会请求该 Gateway 解析限定密钥，并使用返回的规范密钥。已删除或失效的会话会停止，并提示复制新命令；它绝不会启动新会话。Gateway 的会话访问控制仍然具有权威性。此流程继续现有会话，不会委托来自浏览器的首次使用认证。

如果 OpenClaw 报告 --handoff 载荷无效，请返回会话的 Control UI 菜单并复制新命令。不要编辑或复用被截断的载荷。

示例¶

# Choose from recent sessions
openclaw resume

# Exact key
openclaw resume agent:main:bugfix

# Unique display-name or label fragment
openclaw resume bugfix

# Remote Gateway override
openclaw resume bugfix --url wss://gateway.example.com --token <token>

# Opaque command copied from the Control UI
openclaw resume --handoff <payload>

相关¶

• TUI
• 会话
• TUI 指南