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

离线手册打开后正文空白

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

index.html
assets/app.js
assets/styles.css
assets/content.js
assets/screenshots/...

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

CLI 安装与环境检查

现象/错误	原因	处理
`CLI_DIGEST_MISMATCH`	下载脚本与页面给出的 SHA-256 不一致	停止执行，重新从当前页面下载并逐字复制该页面的摘要；不要跳过校验
`doctor` 返回 `action_required`	SSH、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。