常见错误码
Vibex 的失败以结构化错误码返回，界面会显示错误码: 说明。常见错误码如下：
远程与配对
会话与工作区
文件与 Git
配置与发布
如果你的问题不在表里，请在 Issue 里附上完整的错误码字符串——它是定位问题的关键。
Agent 无法启动或不可用
- 打开 配置中心 → Agent，确认该 Agent 的状态不是 已停用。
- 状态为 未安装 时点击 安装；状态为 由用户管理 时，确认对应的命令行程序在
PATH上且可执行。 - 展开 原生凭证，检查登录状态；必要时 重新认证。
- 展开 模型供应商配置，确认已配置模型并用 测试连接 验证连通性。
- 在终端里直接运行该 Agent 的版本检查命令，确认
PATH和权限没有问题。
消息卡住或状态不正确
- 查看时间线是否停在 permission request 或 elicitation，等待你处理。
- 确认没有另一个运行正在占用同一个工作区。
- 应用刚重启时，等待持久化状态加载完成。
- 会话显示
running但实际没有进程时，重启一次权威运行时让它重新探测状态。
文件或 Git 结果不对
- 确认当前项目和工作区。
Local和Worktree是两个不同的目录，改错地方很常见。 - 保存编辑器文件后再刷新文件树和 Git status。
- 检查是否存在外部修改或合并冲突。
- 执行 revert、amend、push 或删除 worktree 之前，先阅读 diff 并创建恢复点。
终端没有输出
检查标签是否绑定到正确的工作区、PTY 是否被标记为stale，以及 shell 是否已退出。调整面板尺寸或重新打开标签，以新的终端快照为准。
Vibex 的终端滚动缓冲区固定为 10000 行，更早的输出已经丢弃，需要时请重新运行命令。
预览打不开
桌面端无法连接到自托管运行时
- 在服务器上确认
curl -fsS http://127.0.0.1:8765/api/v2/info有响应。 - 确认
VIBEX_PUBLIC_HOST是客户端实际能拨到的地址，并带上端口。 - 局域网模式必须使用
VIBEX_TLS_MODE=pinned_certificate，并从连接串配对（连接串里带证书）；手工填地址会因缺少证书而失败。 - 公网模式确认
VIBEX_ALLOWED_HOSTS包含实际访问的域名，否则网关返回421。 - 检查服务器日志里的
tls_fingerprint，与客户端显示的 证书 行比对。
手机无法连接
- 确认权威运行时正在运行，并且已经启用了一种连接方式（Tailscale Serve / Direct HTTPS / Self-hosted Relay / 局域网配对）。
- 检查手机和权威端的网络；Direct 失败时改试 Tailnet 或 Relay。
- 重新生成二维码或连接串，不要复用旧的配对凭据。
- 显示
revoked时必须重新配对；显示resync_required时等待权威端同步完成。 - 使用 Relay 时检查
/health和/api/info——注意 Relay 上没有/api/v2/info。
提交诊断信息
请提供：- Vibex 版本与发布通道（在 设置 → 关于 查看）
- 操作系统与版本
- 复现步骤
- 结构化错误码（最关键）
- 脱敏后的时间戳