Agent 回复和控制 UI

Agent 运行因存储错误而失败¶

如果错误信息提到了 Gateway 状态数据库，则表明运行期间出现了存储故障。聊天横幅、记录到的助手错误以及 embedded_run_agent_end 日志均显示相同的诊断结果。Provider 响应正文仍保持脱敏状态。

SQLite 消息	后续步骤
`database is locked` 或 `database table is locked`	重试。如果重复出现，请检查 Gateway 日志和并发的存储维护。
`database or disk is full`	释放 Gateway 主机上的磁盘空间，然后重试。
`attempt to write a readonly database`	检查 Gateway 服务用户的存储权限和文件系统挂载模式。
`disk I/O error`	重试前检查存储健康状况和文件系统访问权限。仅凭此消息并不能证明磁盘已耗尽。

会话记录（transcript）写入器所有权错误意味着该运行丢失了其会话写入权。请在当前会话中重试；如果再次发生，请检查 Gateway 日志。存储故障不会触发 Provider 凭据轮换或运行的自动重放。

使用 openclaw logs --follow 将运行与存储活动进行关联。SQLite 可能在同一 Gateway 进程内的连接或工作线程之间发生争用；即使只看到一个进程打开了数据库，也不能排除争用的可能。请参阅数据库并发说明。避免在运行处于活动状态时执行完整的数据库压缩。

没有回复¶

如果通道已启用但没有任何回复，请在重新连接任何内容之前检查路由和策略。

openclaw status
openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw config get channels
openclaw logs --follow

请检查以下方面：

私信发送者的配对待处理。
群组提及门控（requireMention、mentionPatterns）。
通道/群组允许列表不匹配。

常见特征：

drop guild message (mention required → 群组消息在被提及前被忽略。
pairing request → 发送者需要获得批准。
blocked / allowlist → 发送者/通道被策略过滤。

仪表盘/Control UI 连接¶

当仪表盘/Control UI 无法连接时，请验证其 URL、身份验证和设备身份。

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --json

请检查以下方面：

正确的探测 URL 和仪表盘 URL。
客户端与 Gateway 之间的身份验证模式/令牌不匹配。
客户端在未提供所需设备身份的情况下进行连接。当前的 Control UI 可以通过普通 HTTP 创建并签署身份；请参阅不安全 HTTP。

如果更新后本地浏览器无法连接到 127.0.0.1:18789，请先恢复本地 Gateway 服务并确认其正在提供仪表盘服务：

openclaw gateway restart
lsof -i :18789
curl http://127.0.0.1:18789

如果 curl 返回 OpenClaw HTML，则说明 Gateway 工作正常，剩余问题很可能是浏览器缓存、过时的深层链接或过期的标签页状态。请直接打开 http://127.0.0.1:18789 并从仪表盘开始导航。如果重启后服务未能保持运行，请运行 openclaw gateway start 并重新检查 openclaw gateway status。

连接/身份验证特征

device identity required → 客户端未提供其角色和身份验证策略所要求的身份。仅使用普通 HTTP 本身并不是原因。在令牌/密码模式下，Control UI 仍然需要浏览器设备身份；共享密钥并不能替代它。
origin not allowed → 浏览器的 Origin 不被允许，且不属于私有同源加载。私有同源加载（包括私有 LAN/Tailscale 地址以及 .local 或 .ts.net 主机）不需要允许列表条目。公共或跨源浏览器部署需要在 gateway.controlUi.allowedOrigins 中添加条目。
device nonce required / device nonce mismatch → 客户端未完成基于质询的设备身份验证流程（connect.challenge + device.nonce）。
device signature invalid / device signature expired → 客户端为当前握手签署了错误的载荷（或使用了过期的时间戳）。
AUTH_TOKEN_MISMATCH 且 canRetryWithDeviceToken=true → 客户端可以使用缓存的设备令牌执行一次受信任的重试。
该缓存令牌重试会重用与已配对设备令牌一起存储的缓存范围集。显式指定 deviceToken / 显式指定 scopes 的调用方则保留其请求的范围集。
AUTH_SCOPE_MISMATCH → 设备令牌已被识别，但其已批准的范围未涵盖此连接请求；请重新配对或批准所请求的范围合同，而不是轮换共享的 Gateway 令牌。
在该重试路径之外，连接身份验证的优先级为：显式共享令牌/密码优先，其次是显式 deviceToken，然后是已存储的设备令牌，最后是 bootstrap 令牌。
在异步 Tailscale Serve Control UI 路径上，针对相同 {scope, ip} 的失败尝试会在限流器记录失败之前被序列化。因此，来自同一客户端的两次并发错误重试会在第二次尝试时显示 retry later，而不是两个普通的 mismatch 错误。
来自浏览器源回环客户端的 too many failed authentication attempts (retry later) → 来自同一规范化 Origin 的重复失败会被临时锁定；其他 localhost 源使用独立的桶。
在该重试之后反复出现 unauthorized → 共享令牌/设备令牌漂移；请刷新令牌配置，并在必要时重新批准/轮换设备令牌。
gateway connect failed: → 主机/端口/URL 目标错误。

认证详情代码快速对照表¶

使用失败的 connect 响应中的 error.details.code 来选择下一步操作：

详情代码	含义	推荐操作
`AUTH_TOKEN_MISSING`	客户端未发送必需的共享令牌。	在网关主机上，在交互式终端中运行 `openclaw gateway auth-token --show`，将输出粘贴到客户端，然后重试。
`AUTH_TOKEN_MISMATCH`	共享令牌与网关认证令牌不匹配。	如果 `canRetryWithDeviceToken=true`，允许一次受信任的重试。缓存令牌重试会复用已存储的已批准作用域；显式传入 `deviceToken` / `scopes` 的调用方保留所请求的作用域。如果仍然失败，请运行令牌漂移恢复检查清单。
`AUTH_DEVICE_TOKEN_MISMATCH`	缓存的每设备令牌已过期或被吊销。	使用设备 CLI轮换/重新批准设备令牌，然后重新连接。
`AUTH_SCOPE_MISMATCH`	设备令牌有效，但其已批准的角色/作用域不覆盖此连接请求。	重新配对设备或批准请求的作用域契约；不要将其视为共享令牌漂移。
`PAIRING_REQUIRED`	设备身份需要审批。检查 `error.details.reason` 是否为 `not-paired`、`scope-upgrade`、`role-upgrade` 或 `metadata-upgrade`，并在存在时使用 `requestId` / `remediationHint`。	批准待处理请求：先运行 `openclaw devices list`，再运行 `openclaw devices approve <requestId>`。查看所请求的访问权限后，作用域/角色升级使用相同流程。

Note

使用共享网关令牌/密码认证的直接环回后端 RPC 不应依赖 CLI 的已配对设备作用域基线。如果子代理或其他内部调用仍以 scope-upgrade 失败，请验证调用方是否使用 client.id: "gateway-client" 和 client.mode: "backend"，并且未强制指定显式的 deviceIdentity 或设备令牌。

设备认证 v2 迁移检查：

openclaw --version
openclaw doctor
openclaw gateway status

如果日志显示 nonce/签名错误，请更新连接的客户端并验证：

1. 等待 connect.challenge

客户端等待网关颁发的 connect.challenge。

2. 对负载进行签名

客户端对与 challenge 绑定的负载进行签名。

3. 发送设备 nonce

客户端发送带有相同 challenge nonce 的 connect.params.device.nonce。

如果 openclaw devices rotate / revoke / remove 意外被拒绝：

已配对设备令牌会话只能管理自己的设备，除非调用方同时具有 operator.admin 权限。
openclaw devices rotate --scope ... 只能请求调用方会话已拥有的 operator 作用域。