从服务端往外，逐层排查连接。

1. 确认版本和服务端模式

把 KKCode 升到最新版本，OpenCode 也用当前版本。为了给 KKCode 提供专用 API，启动 opencode serve。

opencode --version

2. 测试准确的 API 基址

在 KKCode 里填的同一个基址后面追加 /global/health：

curl -i -u your-user:your-password \
  https://your-opencode-host.example/global/health

预期：返回包含 OpenCode health 数据的 HTTP 成功响应。

• HTML 响应 —— 大概率你填的是 Web UI 的 URL，不是 API 基址。
• 404 —— 看看 API 是否挂在 /api 或别的子路径下。
• 401/403 —— 检查 OPENCODE_SERVER_USERNAME 和 OPENCODE_SERVER_PASSWORD。
• 超时 / DNS 失败 —— 先修网络、隧道、VPN 或 hostname，再动 App。

3. 检查所用的传输层

Tailscale：确认两端在同一个 tailnet、ACL 允许该路由、tailscale serve status 指到 OpenCode 端口。

Cloudflare Tunnel：确认 cloudflared 跑着、hostname 能解析、ingress 指到 127.0.0.1:4096、鉴权仍开启。

内置扫码隧道：在开发机重启 npx -y @kkcode-app/agent@latest，在 KKCode 重新扫一次码。中继不通时，回退到局域网、Tailscale 或 Cloudflare。

反向代理：保留 API 前缀、Authorization 头、SSE 流。

4. 看懂 App 状态

• 已连接但没有 workspace —— 确认 OpenCode 版本兼容，开发机能访问某个项目目录。
• 要刷新才能更新消息 —— 看 SSE / realtime 状态、代理对事件流的支持。
• 鉴权失败 —— 让用户名密码跟服务端环境变量对得上。改连接字段不会自动触发重连 —— 点 Reconnect。
• 浏览器里隧道通，App 里不通 —— 用真正的 API 基址路径，不要贴返回 HTML 的 URL。

5. 写出有用的 Bug 报告

附上 KKCode 版本号、OpenCode 版本、连接方式、清理过的 API 基址形态（不要带凭证）、health 响应状态、可见错误。绝不要带上密码、Provider key、私有 hostname、客户数据、源码。

提交前先在 GitHub issue tracker 搜一下避免重复。涉及安全的问题发邮件到 kkcode.app 页脚的邮箱，不要发公开 issue。