从导入账号到 Codex 接入

01

安装与首次启动

Amber 面向 Windows 10/11 x64。Windows 11 通常已经包含 WebView2；Windows 10 若打开后界面空白，应先安装当前版 Microsoft Edge WebView2 Runtime。

1. 下载安装包

   从本站下载页进入 v0.4.4 GitHub Release，下载 Amber_0.4.4_x64-setup.exe，并核对页面提供的 SHA-256。

2. 处理 SmartScreen 提示

   若 Windows 显示“已保护你的电脑”，先确认文件名、来源和 SHA-256，再选择“更多信息”继续。不要忽略校验直接运行来源不明的安装包。

3. 等待后台就绪

   启动 Amber 后，左下角应显示“已就绪”。若持续启动中或启动失败，打开运行诊断检查数据目录、端口和 Sidecar 状态。

02

导入与管理账号

进入“账号”，点击右上角“导入账号”。Amber 支持 ChatGPT OAuth、Base URL + API Key，以及单个或批量 JSON 文件。

选择合适的导入方式

ChatGPT OAuth

在浏览器完成登录与授权。授权超时或提示会话过期时，应重新发起流程，不要反复导入旧 Token。

Base URL + API Key

适用于 OpenAI 兼容上游。Base URL 通常以 /v1 结尾，可在保存前选择直连或一个已保存代理。

JSON 文件

支持单账号、账号数组、{ "accounts": [...] }，以及一次选择多个文件。提交前先检查新增、更新、跳过和冲突预览。

并发、队列和批处理

账号详情中的“最大并发”限制同时处理的请求数，“队列容量”控制并发占满后的等待数量。队列也满时，新请求会被明确拒绝，而不是无限等待。批量全选只覆盖当前页，跨页选择会保留并显示总数。

03

代理配置与批量应用

Amber 支持 HTTP、HTTPS 和 SOCKS5。代理保存后应先运行测试，分别查看 DNS、连接、TLS 和 HTTP 阶段，而不是只看最终成功或失败。

• 代理密码留空时可复用已保存值；只有明确清除才会删除。
• 批量应用后重新读取账号绑定摘要，确认实际写入结果。
• 代理测试成功不代表账号凭据、模型权限和上游策略一定可用。
• 不要求普通用户开启 TUN；先使用 Amber 自身的连接诊断定位失败阶段。

04

启动本地 OpenAI 兼容服务

回到仪表盘，点击“启动服务”。默认地址为 http://127.0.0.1:8080/v1，本地 API Key 由 Amber 生成，与上游 OpenAI API Key 不是同一项凭据。

先验证模型列表

仪表盘显示“运行中”后，在 PowerShell 中使用当前本地 API Key 检查模型列表：

curl.exe http://127.0.0.1:8080/v1/models `
  -H "Authorization: Bearer sk-local-替换为你的密钥"

05

本地 Codex 接入

v0.4.4 提供“启动服务并注入”：Amber 会先启动本地网关，验证健康状态、API Key 和模型列表，再写入并回读 Codex 配置。

1. 选择“启动服务并注入”

   Amber 会启动本地服务；启动失败、端口冲突或健康检查异常时不会写入配置。

2. 选择模型并核对预览

   检查将写入的 config.toml、auth.json 路径、Base URL 和模型。

3. 执行一键注入

   Amber 会先备份已有配置。应用后重新加载或重启 Codex，再发起最小请求。

06

首次连接时确认 SSH 主机密钥

主机密钥用于确认正在连接的是预期服务器。第一次测试远程目标时，Amber 会显示服务器 SHA-256 指纹并等待你在本机确认。

1. 点击“测试连接”

   Amber 使用表单中的主机、SSH 端口、用户名和认证信息连接远程服务器。

2. 在可信渠道取得指纹

   通过云厂商控制台、服务器本地终端或管理员提供的可信记录核对，不要使用同一条可疑网络连接自行证明自己。

3. 逐字比较 SHA-256

   只有指纹完全一致时，才在本机 Amber 点击“信任并继续”；不一致立即取消并检查主机地址或服务器变更。

可在服务器可信终端列出 OpenSSH 主机公钥指纹：

for key in /etc/ssh/ssh_host_*_key.pub; do
  ssh-keygen -lf "$key" -E sha256
done

07

SSH 反向隧道与远程 Codex

当远程服务器不能直接访问上游，但 Windows 电脑上的 Amber 能够通过本机网络或代理访问时，选择“反向隧道（回流本机）”。

远端准备条件

• SSH 服务允许 TCP 转发，通常需要 AllowTcpForwarding yes。
• 选定的远程回流端口未被其他进程占用。
• SSH 用户可以创建并写入自己的 ~/.codex。
• 普通个人回流不需要开启 GatewayPorts。

08

云账号注册与加密同步

云账号用于同步、备份、多设备和共享，不是使用本地网关的前置条件。注册时需要邮箱验证码，并应使用密码管理器保存云主密码。

同步失败时按阶段诊断

1. DNS域名是否解析，系统或代理 DNS 是否返回可用地址。
2. TCP目标端口能否建立连接，防火墙和代理是否拦截。
3. TLS证书、SNI 和系统时间是否正常。
4. HTTP服务是否返回预期状态，而不是代理登录页或错误页。

在“连接设置”中依次尝试系统代理、Amber 已保存代理或直连，运行网络探测，成功后应用并重试。退出云账号不会修复网络链路，只会清除当前会话。

09

当前 v0.4.4 的共享流程

v0.4.4 使用“连接码 + 临时密码”快速共享，不要求先添加好友。使用前，双方都需要登录各自的 Amber 云账号。

10

v0.4.4 的多设备定向路由

新共享默认固定到创建它的电脑。共享者可显式添加最多两台具备目标账号且健康的备用设备，其他在线设备不会自动接管。

路由与故障转移边界

• 主设备正常时，共享始终保持其账号、代理和网络出口。
• 主设备在上游开始前不可用时，才按明确优先级尝试合格备用设备。
• 上游请求开始后不跨设备重放，避免重复扣费或重复执行。

11

v0.4.4 的独立云账号工作区

v0.4.4 为每个云用户使用独立工作区，隔离普通账号、代理、同步队列、Guest Key、日志、设置与 SSH 目标。