错误码 - Vibex

Vibex 的失败以结构化错误码返回，界面会显示为 错误码: 说明。提交 Issue 时请附上完整的错误码字符串——它比日志正文更有用。

远程与配对

错误码	含义	处理
`remote_pairing_code_invalid`	配对码错误、已被使用或不存在。	在权威端重新生成。
`remote_pairing_code_expired`	配对码已过期（默认 5 分钟，最长 30 分钟）。	重新生成并尽快使用。
`remote_pairing_link_invalid`	连接串格式错误，或其中地址不是允许的局域网地址。	使用权威端打印的完整连接串。
`device_revoked`	设备已被撤销。	重新配对。
`resync_required`	检测到序号或游标缺口。	等待权威端重新同步。
`server_shutdown`	权威运行时正在关闭。	重启后重连。
`permission_denied`	当前设备权限级别不足。	用更高权限级别重新配对。

会话与工作区

错误码	含义	处理
`remote_agent_workspace_root_missing`	会话请求的工作区目录在权威端不存在。	确认目录已挂载且位于 `VIBEX_WORKSPACE_ROOTS` 内。
`remote_agent_workspace_mode_mismatch`	请求的工作区模式与权威端记录不一致。	在权威端重新选择工作区。

文件与内容

错误码	含义	处理
`file_external_revision_changed`	保存时文件已被外部进程修改。	重新加载后再决定如何合并。
`office_legacy_format_unsupported`	`doc` / `xls` / `ppt` 无法渲染。	用系统默认应用打开，或转换为新格式。

配置与导入

错误码	含义	处理
`provider_native_import_source_missing`	找不到要导入的原生配置来源。	确认对应 Agent 的配置文件存在。

用量统计

错误码	含义	处理
`agent_usage_query_too_large`	查询超过 100000 行上限。	缩小时间范围或增加筛选条件。

发布与更新

错误码	含义	处理
`release_channel_override_rejected`	试图在运行时切换发布通道。	安装对应通道的版本。
`stable_channel_requires_release_build`	Stable 通道需要正式发布构建。	使用正式发布的安装包。

SSH 与 WSL

错误码	含义	处理
`ssh_client_missing` / `ssh_spawn_failed`	桌面端没有可用的 SSH 客户端。	安装 OpenSSH；Windows 使用 WSL。
`ssh_host_key_unknown`	主机密钥不在 `known_hosts` 中。	先在终端连接并核对指纹。
`ssh_host_key_changed`	主机密钥与记录不一致。	与主机所有者核对后再决定是否更新 `known_hosts`。
`ssh_auth_failed`	非交互认证失败。	检查 Key、ssh-agent 和 IdentityFile。
`ssh_connection_refused`	目标没有 SSH 服务。	安装/启动 sshd，或用 bootstrap。
`ssh_environment_glibc_too_old` / `ssh_environment_missing_glibc`	远端 glibc 低于 2.35 或缺失。	换受支持的发行版；musl 主机不支持。
`ssh_environment_disk_low`	远端 home 空间不足。	至少释放 512 MiB。
`ssh_environment_port_busy`	运行时端口被占用。	释放端口或重试。
`ssh_runtime_start_failed` / `ssh_runtime_health_timeout`	运行时没有启动或健康检查超时。	查看远端 `server.log`，修复后重试。
`ssh_tunnel_*`	隧道建立、保持或停止失败。	检查本地端口和 SSH 连接，重试。
`ssh_upgrade_incompatible`	运行时与桌面端版本不兼容。	按兼容性状态更新运行时或 Vibex。

浏览器

错误码	含义	处理
`browser_missing`	找不到 Chrome、Chromium 或 Edge。	安装受支持的浏览器。
`browser_unavailable`	浏览器服务不可用或正在关闭。	重新打开面板；检查运行时日志。
`browser_ref_stale`	元素引用已过期。	重新观察页面后再操作。
`browser_element_not_found` / `browser_element_not_visible`	目标元素不存在或不可见。	重新观察；必要时滚动或等待。
`browser_navigation_denied` / `browser_navigation_approval_required`	导航被拒绝或需要批准。	在面板里确认；不要绕过审批。
`browser_wait_timeout`	等待条件超时。	检查选择器或页面状态。
`browser_feature_disabled`	当前运行时或平台关闭了浏览器面板。	检查设置和平台支持。

电脑操作

错误码	含义	处理
`computer_feature_disabled`	总开关关闭。	在设置 → 电脑操作打开。
`computer_engine_missing` / `computer_driver_daemon_missing`	驱动或 helper 未安装/未运行。	安装驱动并重新检测。
`computer_accessibility_bridge_missing`	Linux 上辅助功能总线不可用。	安装/启动 AT-SPI；X11 下仍可能降级。
`computer_credential_target_blocked`	目标是密码管理器或安全输入框。	硬拒绝，不能批准。
`computer_element_reference_stale`	元素引用已过期。	重新观察应用。
`computer_stopped_by_user`	你按下了应急停止。	手动重新开启后才能继续。
`computer_paused_offline`	客户端断线，操作已暂停。	重新连接并确认恢复。

供应商与网关

错误码	含义	处理
`provider_authentication_required`	供应商或 Agent 需要认证。	登录 Agent 或补充 Provider Key。
`provider_profile_not_found`	配置不存在或已删除。	刷新配置中心，重新选择。
`agent_model_interface_unsupported`	当前 Agent 不支持所选接口协议。	换协议或换 Agent。
`model_gateway_port_invalid`	网关端口低于 1024 或不可用。	换一个高于 1023 的空闲端口。
`model_gateway_cooldown_invalid`	冷却时间不在 1 毫秒到 1 天之间。	调整冷却设置。
`model_gateway_token_limit_invalid`	Token 上限无效。	输入正整数或留空。
`reasoning_effort_unavailable`	所选思考档位不被模型支持。	换档位或留空。

状态值

这些不是错误，但经常被误读：

值	出现在	含义
`stale`	终端、运行状态	上次观察到的状态已失效，不代表进程仍存活。
`revoked`	设备	授权已被撤销。
`running`	会话	只是上次观察到的状态，重启后需要重新探测。
`Not reported` / `Partial`	用量上报覆盖	数据缺失或不全，不要当作零。

通用排查顺序

确认权威运行时正在运行，以及当前连的是哪一个（本地内嵌，还是远程服务器）。
确认当前项目和工作区正确——Local 和 Worktree 是不同目录。
确认设备权限级别足够（写操作需要 full_control）。
查看时间线最近一条事件，确认是否在等待你处理审批或询问表单。
仍无法解决时，按故障排查提交脱敏信息。