OpenAgent
OpenAgent

排错

常见问题

先保留错误码、当前状态和 ID，再做最小修复。不要把访问令牌、Cookie、私钥或完整凭据复制到工单、聊天或截图中。

离线手册打开后正文空白

导航和页眉可见、正文区域全空通常表示生成后的 assets/content.js 缺失、未加载或内容数组为空。完整离线包至少应包含：

index.html
assets/app.js
assets/styles.css
assets/content.js
assets/screenshots/...
  1. 确认不是只复制了 index.html。
  2. 确认 assets/content.js 存在且文件大小不为 0。
  3. 重新解压完整目录，再从目录中的 index.html 打开。
  4. 仍为空白时，打开浏览器开发者工具，检查是否有 content.js 或 CSP 加载错误。

CLI 安装与环境检查

现象/错误原因处理
CLI_DIGEST_MISMATCH下载脚本与页面给出的 SHA-256 不一致停止执行，重新从当前页面下载并逐字复制该页面的摘要；不要跳过校验
doctor 返回 action_requiredSSH、ssh-keygen、本地回环端口或公钥至少一项缺失根据各布尔字段逐项安装/启用；缺公钥时先征得同意再创建
SSH_KEY_REQUIRED没有可用公钥明确同意后运行 oasn-sa-dev ssh-key ensure --create
SSH_KEY_EXISTS目标私钥或公钥路径已存在不要覆盖；使用现有合法 key，或选择一个全新明确路径
SSH_KEYGEN_REQUIRED系统找不到 OpenSSH ssh-keygen安装/启用 OpenSSH 客户端后重跑 doctor

浏览器登录与凭据库

现象/错误处理
LOGIN_TIMEOUT在允许时间内完成浏览器授权；确认本地回环端口未被安全软件拦截，再重试原命令
auth status 为 login_required运行本次需要的认证命令，例如 workspace sources/create/status/connect/resume、version webui-ports 或 allow-listed portal 操作，再按浏览器提示登录
credential_store=unavailable启用 Windows Credential Manager、macOS Keychain 或 Linux Secret Service；CLI 不会降级为明文会话文件
auth logout 的 server_status=unconfirmed本地删除结果与服务端吊销结果分开判断；检查 status 是否为 local_delete_failed，并结合 server_status、server_revoked 判断

Workspace 一直未就绪

WORKSPACE_TIMEOUT

超时并不证明创建失败。错误文本带有 workspace_id 和 last_status；保存该 ID，使用状态命令继续等待，不要立即重新创建：

oasn-sa-dev workspace status --workspace-id <WORKSPACE_ID>

需要调整等待窗口时，可使用 --timeout-seconds 30..3600、--poll-interval-seconds 1..30 和 --login-timeout-seconds 60..600。

WORKSPACE_NOT_READY

这表示 Workspace 已进入 failed、closed、published、cleanup_pending 或 close_pending 之一。记录错误中的 status 与 failure_code；不要继续 SSH/SCP。

WORKSPACE_RESPONSE_INVALID

生命周期响应缺少必需身份、状态或期限字段，或 connect 已报告 bound + ssh_verified=true 却缺少可用 SSH/SCP 命令。active 且 unbound 时没有 SSH 入口是正常边界；应先 connect。其他缺失不要自行拼地址，保留 Workspace ID 和缺失字段交由平台排查。

active 但 SSH 不能用

active 只表示生命周期就绪。运行 oasn-sa-dev workspace connect --workspace-id <ID>，按稳定错误区分本机私钥/ssh-agent、host key、网络入口与真正公钥认证；只有 ssh_binding_status=bound 且 ssh_verified=true 才使用连接命令。不要换 key、覆盖 known_hosts 或 authorized_keys。

WebChat 或集成测试失败

  • 先在 /oasn 中确认程序、配置和依赖确实存在，而不是只在本机副本中修改。
  • 正常输入能工作但附件失败：检查实际附件下载/读取和输出文件交付，不要只看聊天文本。
  • 插件失败：检查插件运行时状态，并做一次真实调用。
  • MCP/A2A 失败：同时检查传输层 isError、业务状态和输出字段。
  • webui_urls=[]：运行 version webui-ports get。not_configured 时确认完整端口列表后 set；pending 只继续 get。
  • sync_status=ready 但没有 URL：继续检查 proxy_status；只有 proxy ready 才交付链接。
  • 业务 URL 返回 410：业务代理会话无效，不等于 Owner OAuth 失效；先 get，按 expired/revoked 规则经授权 resume 或 refresh。
  • 业务 URL 返回 502：先确认服务仍监听 0.0.0.0:<已声明端口>，不要立即 refresh。
  • 最终回复只显示代码块而没有页面：检查 fence 是否精确为小写 oasn-webui，JSON 是否恰好四字段，以及 defaultOpen 是否为 boolean。
  • OPENCLAW_FINAL_REPLY_INVALID：检查未声明端口、私网/公网 HTTP URL、URL 用户名密码和 query/hash 中的敏感字段。

发布卡住或失败

  • PRICING_MAPPING_INVALID：检查 Gross margin 是否为 0–100 的整数百分比；不要输入小数，也不要假设平台会自动取整。
  • queued/running：继续观察当前 Job，不重复点击 Publish。
  • failed：记录失败阶段与页面错误，修复草稿、重新保存，再发起新任务。
  • Job 为 succeeded 但 publication 为 pending/syncing：仍未完成，继续等待可见性收敛。
  • publication 为 failed：保留 Job ID、版本 ID 和错误信息，不能宣称已发布。
  • 已经 visible 但不能被调用：检查是否仍为 Offline；需要点击 Go Online。

不要用“猜命令”排障

先用 0.7.3 的真实命令树，不按旧手册猜

portal、workspace sources/connect/resume、workspace create --fresh/--source-version-id 和 version webui-ports get/set/refresh 已经可用。仍不存在通用 sync 或 workspace close/delete/publish；运行 oasn-sa-dev portal commands 和具体 --help 核对，禁止拼原始平台 API。

搜索文档

推荐搜索