常见问题与排障

127.0.0.1 只代表正在运行客户端的那台电脑。先确认 Amber 左下角后台状态正常，仪表盘中的本地服务显示“运行中”，再核对客户端 Base URL、端口和本地 API Key。默认地址是 http://127.0.0.1:8080/v1。

如果客户端已经自动追加 /v1，不要在地址中重复填写。WSL、Dev Container 或 SSH Remote 中的 127.0.0.1 也不是 Windows 主机，应改用对应的远程注入或 SSH 隧道。

1. 打开仪表盘并启动服务。
2. 确认客户端端口与 Amber 设置一致。
3. 重新复制本地 API Key，并重新加载客户端。

v0.4.4 的“启动服务并注入”会在写入配置前启动本地服务，并验证 Amber 实例、本地 API Key 与 /v1/models。若之后仍出现 502，先确认 Amber 没有退出、端口未变化，再查看统计页最近错误，区分本地连接问题与上游账号问题。

1. 打开 Amber。
2. 在仪表盘启动服务并确认运行中。
3. 重新加载 Codex 后再次请求。

先在仪表盘手动启动服务。若状态很快回到“已停止”或显示“启动失败”，进入设置中的运行诊断，检查 Sidecar、数据目录、监听端口和健康检查结果。不要用反复卸载代替诊断。

如果已启用“启动应用时自动开启服务”，仍应先解决诊断中报告的具体阻断项；自动启动不会绕过端口占用或数据目录错误。

停止占用该端口且不再需要的程序，或在 Amber 设置中改用一个未占用端口。端口改变后，所有客户端和 Codex 配置中的 Base URL 都必须同步更新。

v0.4.4 会在注入前验证服务是否成功启动；端口冲突或健康检查失败时不会继续写入 Codex 配置。修复占用或改用新端口后，再执行“启动服务并注入”。

注意：不要关闭来源不明的系统进程。无法确认占用者时，优先改用其他端口。

Amber 支持 HTTP、HTTPS 和 SOCKS5 代理。先在代理页添加并测试，再绑定到账号；云连接可在系统代理、Amber 已保存代理和直连之间单独选择。代理测试通过后，还应执行账号测试，因为真实请求还会涉及凭据、模型权限和目标站点。

普通用户不需要为了 Amber Cloud 专门开启 TUN。TUN 会改变系统 DNS 和路由，若与系统代理或账号代理叠加，反而可能让诊断更困难。必须使用 TUN 时，先避免重复代理，再逐项测试 Amber 的代理链路和云网络探测。

账号测试说明该账号当时能够通过所选网络访问上游，不代表本地 API 服务、Codex 配置和运行环境都正确。继续检查 Amber 服务是否运行、Base URL 与端口是否匹配、本地 API Key 是否最新，以及所选模型是否对该账号开放。

在 v0.4.4 中，使用“启动服务并注入”完成本地验证和配置写入，再重新加载 Codex。若 Codex 运行在 WSL、容器或远程主机，必须使用对应的远程接入方式，不能直接引用 Windows 的 127.0.0.1。

先在 Amber 中添加 SSH 目标并测试连接，通过服务器控制台、可信终端或管理员提供的记录核对 SHA-256 主机指纹。确认无误后，Amber 才能为该 SSH 用户写入并回读远程 Codex 配置。

远程服务器能够访问目标 Base URL 时可使用直连模式；需要借用 Windows 电脑上的账号、代理或网络出口时，使用 SSH 反向隧道让请求回流本机 Amber。反向隧道依赖本机 Amber、本地服务和 SSH 连接持续在线。

1. 添加远程 SSH 目标并测试连接。
2. 从可信渠道核对并确认主机指纹。
3. 选择直连或反向隧道，执行远程注入后重新加载 Codex。

反向隧道把远程服务器上的 Codex 请求送回安装 Amber 的电脑，再使用这台电脑上的账号、代理和网络出口访问上游。本机 Amber、SSH 连接或目标卡片中的路由开关任一离线，链路都会中断。

若远程服务器本身可以直接访问目标 Base URL，可改用直连模式；直连不会建立回流本机的隧道。

点击“测试连接”取得远程服务器的 SHA256 主机指纹，然后通过服务器控制台查看指纹，或向服务器管理员从可信渠道索取。只有两边完全一致时，才在本机 Amber 点击“信任并继续”。

这里确认的是表单中填写的 SSH 服务器，不是 Amber 电脑、代理服务器或上游服务。已经信任的主机指纹若意外变化，应取消连接并先查明服务器重装、密钥轮换或中间人风险。

可以。导入账号、配置代理、启动本地网关、查看统计与日志，以及本机或 SSH Codex 接入，都不要求注册或登录 Amber 云账号。OAuth 登录、SSH 连接和上游请求仍需各自的网络与凭据可用。

Amber 云账号只用于加密同步、备份、多设备和共享授权。使用这些云功能时需要登录；连接码共享的双方都需要登录各自的云账号。

DNS 失败表示域名未解析；TCP 失败表示无法建立到目标端口的连接；TLS 失败通常与证书链、SNI、系统时间或网络拦截有关；HTTP 失败表示连接已建立，但服务返回了错误状态或请求被拒绝。超时则要结合最后完成的阶段判断。

在云账户的“连接设置”中选择系统代理、Amber 已保存代理或直连，运行网络探测，探测成功后应用并重试同步。v0.4.4 首选 api.amberapp.asia；幂等请求在首选入口不可用时可回退到 Workers 域名。

OAuth 共享默认由共享者设备回流：Owner Relay 负责把请求送到共享者的 Amber，最终上游请求由该设备使用本地账号、代理和网络出口发出。因此共享者设备、Amber 或 Relay 离线时，请求会返回设备离线类错误。

等待共享者设备恢复在线，或请共享者检查 Amber、云登录和共享路由。只有明确配置为 Worker 直连的兼容 API Key 共享不依赖拥有者设备；不要把两种路径混为一谈。

v0.4.4 的新共享默认绑定创建共享的具体电脑。共享者可以显式配置最多两台具备目标账号且健康的备用设备；未配置的其他在线设备不会自动接管。

故障转移只发生在上游请求开始之前。上游已经开始后不会跨设备重放，以避免重复扣费或重复执行。

v0.4.4 为每个云账号建立独立本地工作区，各自保存账号、代理、同步队列、Guest Key、日志和 SSH 目标。退出登录不会删除数据或解除工作区归属；登录另一个账号时会切换或创建对应工作区。

升级时若旧数据库包含多个历史用户或归属不明确的同步数据，Amber 会进入只读恢复工作区，不会猜测归属或自动上传。