Agent 回复与 Control UI
Agent run failed with a storage error¶
一个指出 Gateway 状态数据库 的错误标识了运行期间观察到的存储故障。聊天横幅、记录的助手错误和 embedded_run_agent_end 日志显示相同的诊断。提供者的响应正文仍保持脱敏。
| 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 |
重试前检查存储健康和文件系统访问。此消息本身并不能证明磁盘已耗尽。 |
转录写作者所有权错误意味着该运行丢失了其会话写入声明。请在当前会话中重试,如果重复出现,请检查 Gateway 日志。存储故障不会触发提供者凭据轮换或自动重放该运行。
使用 openclaw logs --follow 将运行与存储活动关联起来。SQLite 可能会在同一个 Gateway 进程中的连接或工作线程之间产生争用;仅看到一个进程打开数据库并不能排除争用的可能。参见 数据库并发说明。在运行处于活动状态时,避免执行完整的数据库压缩。
Provider rejected the request¶
以 LLM request rejected: 开头的回复会包含提供者的请求验证消息。OpenClaw 会对凭据进行脱敏、限制诊断范围,并以字面文本形式显示,而不是暴露完整的响应体。已知的上下文、Token 限制和存储故障会保留其特定的恢复指导。
对于 Invalid service_tier argument,请检查所选模型和速度设置。某个提供者或账户支持 Fast 或 Ultrafast,并不意味着每个模型都支持该层级。请使用 Standard(/fast off)重试,或选择支持所请求层级的模型。仅此错误并不意味着对话已损坏。参见 OpenAI Fast 模式。
Connection to the AI service failed¶
如果回复说 OpenClaw 无法连接到 AI 服务,请检查提供者连接。对于本地模型,请确认其服务器正在运行,并且可以在配置的 URL 上访问。如果在某一轮期间服务器停止,可能会在对话中留下已完成的工作;重试前请检查这些结果。使用 openclaw logs --follow 进行连接诊断。
Unreadable conversation history¶
如果回复说 OpenClaw 无法读取会话历史,请让 Gateway 操作员在拥有该会话的主机和配置上尝试 openclaw doctor --fix。当允许静默回复时,此提醒也会出现在未被提及的群组轮次中。
当存储的转录条目已经是规范形式时,Doctor 可以恢复缺失的头部。它不能修复所有格式错误或不支持的历史记录。如果错误持续存在,请保留状态并联系支持,附上 Gateway 日志;历史记录可能需要迁移或从备份中恢复。重复使用 /new 或 /compact 命令无法修复无法加载的转录。
参见 Doctor 的会话修复 和 运行 Doctor。
No replies¶
如果通道在线但没有任何回复,在重新连接任何内容之前,请先检查路由和策略。
openclaw status
openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw config get channels
openclaw logs --follow
请检查以下内容:
- DM 发送者的配对待处理。
- 群组提及门控(
requireMention、mentionPatterns)。 - 通道/群组允许列表不匹配。
常见特征:
drop guild message (mention required→ 群组消息在被提及之前被忽略。pairing request→ 发送者需要批准。blocked/allowlist→ 发送者/通道被策略过滤。
相关:
如果共享模型目录工作进程退出,并且其自动运行时替换失败,则打开模型选择器、准备聊天或发送新消息可以再次检查失败的运行时,而无需重启 Gateway。检查时选择器会显示 正在加载模型…,如果准备仍然失败,则回到 模型不可用。重复的前台检查有短暂冷却时间。Cron 和 Heartbeat 每个故障事件只获得一次检查;后续的定时运行不会持续重建仍然不可用的运行时。现有消息和任务不会被重放。
此恢复过程仍会等待早期的准备工作稳定下来。永不完成的准备、无关的配置错误以及 Gateway 关闭都需要各自的诊断;模型检查不会绕过这些生命周期边界。
Dashboard control UI connectivity¶
当仪表板/控制界面无法连接时,请验证其 URL、身份验证和设备身份。
openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --json
请检查以下内容:
- 正确的检查 URL 和仪表板 URL。
- 客户端与网关之间的身份验证模式/令牌不匹配。
- 客户端在没有所需设备身份的情况下连接。当前 Control UI 可以通过普通 HTTP 创建和签署身份;参见 不安全 HTTP。
如果更新后本地浏览器无法连接到 127.0.0.1:18789,请先恢复本地 Gateway 服务,并确认其正在提供仪表盘:
如果 curl 返回 OpenClaw HTML,则 Gateway 正在工作,剩余问题可能是浏览器缓存、旧的深度链接或过期的标签页状态。直接打开 http://127.0.0.1:18789,并从仪表盘开始导航。如果重启后服务没有保持运行,请运行 openclaw gateway start,并重新检查 openclaw gateway status。
连接 / 身份验证签名
device identity required→ 客户端未提供其角色和身份验证策略所需的身份。仅使用普通 HTTP 并不是原因。在 token/password 模式下,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→ 客户端可以使用缓存的设备 token 进行一次可信重试。- 该缓存 token 重试会复用与配对设备 token 一起存储的缓存 scope 集合。显式
deviceToken/ 显式scopes调用方则保留其请求的 scope 集合。 AUTH_SCOPE_MISMATCH→ 设备 token 已被识别,但其已批准的 scope 不覆盖此连接请求;应重新配对或批准请求的 scope 契约,而不是轮换共享 Gateway token。- 在该重试路径之外,连接身份验证优先级依次为:显式共享 token/password,然后是显式
deviceToken,然后是存储的设备 token,最后是 bootstrap token。 - 在异步 Tailscale Serve Control UI 路径中,针对相同
{scope, ip}的失败尝试会在限流器记录失败之前被串行化。因此,来自同一客户端的两次错误并发重试可能在第二次尝试时显示retry later,而不是两个普通不匹配。 - 来自浏览器来源环回客户端的
too many failed authentication attempts (retry later)→ 来自同一规范化Origin的重复失败会被临时锁定;另一个 localhost origin 使用单独的桶。 - 该重试后反复出现
unauthorized→ 共享 token/设备 token 漂移;刷新 token 配置,并在需要时重新批准/轮换设备 token。 gateway connect failed:→ 主机/端口/URL 目标错误。
身份验证详情代码快速映射¶
使用失败的 connect 响应中的 error.details.code 来选择下一步操作:
| 详情代码 | 含义 | 建议操作 |
|---|---|---|
AUTH_TOKEN_MISSING |
客户端未发送必需的共享 token。 | 在 Gateway 主机上,在交互式终端中运行 openclaw gateway auth-token --show,将输出粘贴到客户端,然后重试。 |
AUTH_TOKEN_MISMATCH |
共享 token 与 Gateway 身份验证 token 不匹配。 | 如果 canRetryWithDeviceToken=true,允许一次可信重试。缓存 token 重试会复用已存储的已批准 scope;显式 deviceToken / scopes 调用方保留请求的 scope。如果仍然失败,请运行 token 漂移恢复检查清单。 |
AUTH_DEVICE_TOKEN_MISMATCH |
缓存的每设备 token 已过期或被吊销。 | 使用 devices CLI 轮换/重新批准设备 token,然后重新连接。 |
AUTH_SCOPE_MISMATCH |
设备 token 有效,但其已批准的角色/scope 不覆盖此连接请求。 | 重新配对设备或批准请求的 scope 契约;不要将此视为共享 token 漂移。 |
| Detail code | Meaning | Recommended action |
|---|---|---|
PAIRING_REQUIRED |
设备身份需要批准。检查 error.details.reason 是否为 not-paired、scope-upgrade、role-upgrade 或 metadata-upgrade,并在存在时使用 requestId / remediationHint。 |
批准待处理请求:先运行 openclaw devices list,然后运行 openclaw devices approve <requestId>。范围/角色升级在审查所请求的访问权限后使用相同流程。 |
Note
使用共享网关 token/密码进行身份验证的直接回环后端 RPC 不应依赖 CLI 的已配对设备范围基线。如果子代理或其他内部调用仍以 scope-upgrade 失败,请验证调用方正在使用 client.id: "gateway-client" 和 client.mode: "backend",并且未强制使用显式 deviceIdentity 或设备 token。
设备身份验证 v2 迁移检查:
如果日志显示 nonce/签名错误,请更新正在连接的客户端并验证它:
1. 等待 connect.challenge
客户端等待网关签发的 connect.challenge。
2. 对负载进行签名
客户端对与质询绑定的负载进行签名。
3. 发送设备 nonce
客户端发送 connect.params.device.nonce,并使用相同的质询 nonce。
如果 openclaw devices rotate / revoke / remove 被意外拒绝:
- 已配对设备 token 会话只能管理其自身设备,除非调用方还具有
operator.admin。 openclaw devices rotate --scope ...只能请求调用方会话已持有的 operator 范围。
相关:
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw