AI 工具新手配置指南

1. 3 分钟开始

第一次使用不需要先理解 API、Responses 或供应商协议。准备下面三个值，选择一个客户端，然后照着对应章节操作即可。

先准备三个值

1. 注册 SunnyRae 账号并创建 API Key。
2. Windows 新手下载 Codex Desktop；已经使用其他客户端的用户进入对应章节。
3. 复制 Codex 章节的 config.toml 模板，并在 auth.json 中填写自己的 SunnyRae Key；不要走 OpenAI 登录页。
4. 保存两个文件后彻底退出 Codex，包括系统托盘和后台进程，再重新启动。
5. 发送：请只回复：连接成功。
6. 看到回复后，回 SunnyRae 控制台确认出现一条用量记录。

查看当前支持模型与倍率请打开模型价格；核对模型兼容映射请打开模型透明度。首次跑通前不要频繁换模型。

2. Codex Desktop（推荐）

本章不再区分 App 和 CLI。Codex 的桌面界面、命令行和 IDE 扩展共用用户目录下的 config.toml 与 auth.json；新手只需安装桌面版并写好这两个文件。

第一步：安装 Codex Desktop

OpenAI 当前把 Codex 放在 ChatGPT desktop app 中。Windows 安装后打开应用，在模式菜单里选择 Codex。

如果 Microsoft Store 页面无法打开，可以在 PowerShell 运行官方命令：

winget install Codex -s msstore

第二步：写入一次配置

完全退出 Codex Desktop，然后打开 PowerShell，运行：

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex" | Out-Null
notepad "$env:USERPROFILE\.codex\config.toml"

把下面内容完整复制到记事本并保存。Codex 使用根地址，末尾不要添加 /v1。这是 SunnyRae 推荐模板的核心配置；需要插件开关和可选项时，可直接下载完整 config.toml 模板。

openai_base_url = "https://sub2api.sunnyrae.net"

model = "gpt-5.5"
review_model = "gpt-5.5"
model_reasoning_effort = "xhigh"

model_context_window = 10000000
model_auto_compact_token_limit = 900000

forced_login_method = "api"
service_tier = "default"
disable_response_storage = true

[features]
fast_mode = true
multi_agent = true
responses_websockets = false
responses_websockets_v2 = false
goals = true
js_repl = false

[notice]
hide_rate_limit_model_nudge = true

如果长会话出现 context limit，先删除 model_context_window 与 model_auto_compact_token_limit 两行，让 Codex 使用模型默认值。

第三步：在 auth.json 中填写 API Key

SunnyRae 中转不使用 OpenAI 登录页。完全退出 Codex Desktop，在 PowerShell 运行下面命令；如果已有官方 ChatGPT 登录，命令会先保留一份 auth.json.bak。

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex" | Out-Null
Copy-Item "$env:USERPROFILE\.codex\auth.json" "$env:USERPROFILE\.codex\auth.json.bak" -ErrorAction SilentlyContinue
notepad "$env:USERPROFILE\.codex\auth.json"

把下面 JSON 完整复制到记事本，将占位文字替换为 SunnyRae 控制台创建的 API Key，然后保存：

{
  "auth_mode": "apikey",
  "OPENAI_API_KEY": "YOUR_SUNNYRAE_API_KEY"
}

auth.json 含有真实凭据，应当像密码一样保护；不要发送给客服、放进截图、同步盘或代码仓库。

第四步：彻底重启后发送第一次任务

1. 重新启动 Codex Desktop，在应用中选择 Codex，再选择一个本地文件夹。
2. 发送：请只回复：连接成功。
3. 回 SunnyRae 控制台查看用量记录。

最容易填错的是两个文件：config.toml 使用根地址 https://sub2api.sunnyrae.net，不要加 /v1；真实 Key 只放在 auth.json 的 OPENAI_API_KEY 字段。

官方参考：Windows 下载、Codex 快速开始、配置参考与认证缓存说明。SunnyRae 在官方用户配置与文件型凭据机制上替换 Base URL、模型 ID 和 API Key 来源。

3. GPT / Codex 常见问题

401

含义：API Key 无效、填错、被禁用，或 Codex 仍在使用旧的官方登录凭据。

处理：Codex 确认 config.toml 的 openai_base_url 是 https://sub2api.sunnyrae.net，并确认 auth.json 使用 auth_mode: "apikey" 且 OPENAI_API_KEY 非空。修改后必须彻底退出全部 Codex 窗口与后台进程，再重新启动。

429

含义：可能是当前用户并发槽位、等待队列、分组或上游达到限制。

处理：先停止并行任务和自动重试，等待片刻后只重试一次；持续出现时联系人工，并提供出错时间、模型和脱敏后的错误文字。

502 / 503

含义：上游账号、上游代理或模型通道暂时不可用。

处理：避免连续重试风暴，可换一个已发布模型再试一次；若持续出现，联系客服并提供时间、模型和错误码。

stream closed before response.completed

含义：Responses 流没有收到正常结束事件，常见于上游流式返回异常。

处理：重试一次；若连续出现，优先切换 GPT 稳定主渠道并联系人工排查。

compact / invalid_encrypted_content / Upstream request failed

含义：Codex 在压缩长会话上下文时，当前选中的上游没有完成 Responses compact；这不等于普通对话请求永久不可用。

处理：先保存必要内容并新建任务，避免在同一长会话中反复压缩重试；若普通短任务可用但 compact 持续失败，联系人工并提供 Codex 版本、时间、模型和脱敏错误文字。

模型不存在

含义：客户端模型 ID 与平台支持模型不一致。

处理：手动添加模型 ID，确认大小写和连字符完全一致。

为什么 Codex 只问了一次，却出现多条模型调用记录？

含义：Codex 是代码 Agent，不是普通聊天客户端。用户看到的一次任务，后台可能会拆成多次模型请求，例如主回答、工具调用后的继续推理、断流重试、上下文压缩、/review 审查或用户明确要求的 subagent 子任务。控制台会按实际后台请求逐条记录，所以一次 Codex 任务附近出现多条使用记录是正常现象。

如果用户明明选择了 gpt-5.5，但同一任务附近还出现 gpt-5.4 等其他模型，通常说明某个辅助请求实际使用了其他模型。常见来源包括 review_model、项目级 .codex/config.toml、自定义 agent 配置、旧会话残留配置，或用户让 Codex 启动了子 agent。

处理：先在 Codex 里用 /model 确认当前主模型，再检查 ~/.codex/config.toml、项目内 .codex/config.toml、自定义 agent / subagent 配置里是否写了其他模型或 review_model。如果确认没有使用 /review、subagent 或项目级配置，仍持续出现不符合预期的模型记录，请联系人工并提供 Codex 版本、出错时间、使用记录截图和相关配置截图。

联系人工排查时提供这些信息

如果按上面的错误码处理后仍然失败，直接复制下面的模板发给客服，避免来回补信息。

使用工具：Codex / GPT 图片 / OpenClaw / Hermes Agent
Base URL：
模型 ID：
出错时间：
错误码或截图：
是否首次配置：

截图前遮住 API Key、Authorization、Cookie、账号 token 和完整请求正文。客服不会要求你发送完整 API Key。

Codex 配置与认证排查参考：Codex Authentication。429 并发槽、compact 和上游切换说明属于 SunnyRae 当前网关行为。

4. GPT-Image-2 图片教程

本节说明如何在 Cherry Studio 中配置 gpt-image-2 图片生成模型，并完成一次基础连通性测试。

首次配置时，建议先按“Cherry Studio 配置步骤”和“首次测试参数”完成小尺寸图片测试。确认可用后，再根据需要调整图片尺寸、质量和其他高级参数。

准备事项

API Key 是访问凭据，用于验证当前用户是否有权限调用服务。请勿发送给他人，也不要在截图、文档或公开页面中展示完整 API Key。

Cherry Studio 配置步骤

1. 打开 Cherry Studio。
2. 进入设置里的模型服务页面。
3. 新增一个供应商。
4. 供应商类型选择 OpenAI。
5. 按下表填写。
6. 打开启用开关。
7. 如果模型列表中没有 gpt-image-2，手动添加这个模型 ID。
8. 保存配置。

Cherry Studio 的 API 地址应填写根地址，也就是 https://sub2api.sunnyrae.cn。不要填写 https://sub2api.sunnyrae.cn/v1，否则部分版本可能会重复拼接 /v1，导致请求地址错误。

首次测试参数

首次验证建议使用小尺寸图片，先确认 API Key、API 地址和模型 ID 配置正确，再测试更高分辨率。

推荐尺寸

不要使用 4096x4096。这里的 4K 指 3840x2160 或 2160x3840，不是方形 4096。

3072x1728 也可以作为中间档横图测试，但它是按尺寸规则推导出的合法自定义尺寸，不是 OpenAI 官方列出的常用尺寸。

超时设置

如果 Cherry Studio 或其他客户端可以设置请求超时，建议至少设置为 300s。

OpenAI 官方说明复杂提示词可能最多需要约 2 分钟。这里建议 300s，是为了给客户端、网关和上游波动预留余量，不是 OpenAI 官方固定超时值。

常见问题

• 模型列表中没有 gpt-image-2：在模型管理里手动添加模型 ID。
• 提示连接失败或地址错误：检查 API 地址是不是 https://sub2api.sunnyrae.cn，不要带 /v1。
• 请求长时间等待或超时：把超时设置到 300s 以上，把尺寸降到 1024x1024，把 quality 改成 low 或 medium。
• 4K 图片失败：确认尺寸是 3840x2160 或 2160x3840，不要用 4096x4096。
• 透明背景失败：gpt-image-2 当前不支持透明背景，不要发送 background: "transparent"。

脚本或其他客户端配置

如果不使用 Cherry Studio，而是使用脚本、工作流工具或其他 OpenAI 兼容客户端，一般使用下面这组配置：

{
  "model": "gpt-image-2",
  "prompt": "A clean product photo of a white ceramic cup on a wooden desk, soft natural light",
  "size": "1024x1024",
  "quality": "medium",
  "output_format": "jpeg"
}

高级尺寸规则

• 最大边不超过 3840px。
• 宽高都必须是 16px 的倍数。
• 长边和短边比例不超过 3:1。
• 总像素不低于 655,360，且不超过 8,294,400。
• 总像素超过 2560x1440（3,686,400）的输出属于 experimental 范围。

参考：Cherry Studio 官方 模型服务设置；OpenAI 官方 Image generation guide 与 GPT-Image-2 model page。尺寸、质量、透明背景和复杂提示词延迟均以这些页面为依据。

5. OpenClaw

OpenClaw 官方通过 models.providers 注册 OpenAI Compatible 自定义供应商，并使用 provider/model 形式选择模型。下面只把官方示例中的 provider、Base URL、API Key 环境变量和模型 ID 替换为 SunnyRae。

准备事项

配置 API Key

先在启动 OpenClaw 的同一个终端设置环境变量：

export SUNNYRAE_API_KEY="YOUR_API_KEY"

不要把真实 API Key 直接写入公开仓库或分享的配置截图。

配置文件

编辑 OpenClaw 配置文件：

~/.openclaw/openclaw.json

加入或合并下面的配置。已有配置时，不要直接覆盖整份文件，只合并 agents.defaults.model 和 models.providers.sunnyrae 这两部分。

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "sunnyrae/gpt-5.5"
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "sunnyrae": {
        "baseUrl": "https://sub2api.sunnyrae.cn/v1",
        "apiKey": "${SUNNYRAE_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "gpt-5.5",
            "name": "GPT-5.5 via SunnyRae"
          }
        ]
      }
    }
  }
}

检查命令

保存后按 OpenClaw 官方 CLI 流程列出模型并显式设置默认模型：

openclaw models list
openclaw models set sunnyrae/gpt-5.5

列表中能看到 sunnyrae/gpt-5.5 后，再启动一次普通对话并发送：请只回复：连接成功。旧版第三方教程里的运行命令不再作为当前验收依据。

参考：OpenClaw 官方 Model providers。官方明确要求自定义 provider 同时注册 models.providers.<provider>.models[]，仅设置 agents.defaults.models 不会创建运行时模型。

6. Hermes Agent

Hermes Agent 官方把 hermes model 作为添加 provider、API Key 和自定义端点的首选入口。当前官方仓库同时支持原生 Windows 与 WSL2，不再要求 Windows 用户只能使用 WSL2。

准备事项

官方推荐配置流程

1. 退出正在运行的 Hermes 会话。
2. 在终端运行 hermes model。
3. 选择 Custom endpoint (self-hosted / VLLM / etc.)。
4. API Base URL 填 https://sub2api.sunnyrae.cn/v1。
5. API Key 填 SunnyRae 控制台创建的 key。
6. Model name 填 gpt-5.5。
7. API mode 选择 chat_completions。

向导会把 endpoint、provider 和模型持久化到 ~/.hermes/config.yaml，并把密钥保存到 Hermes 的配置体系。不要把 ~/.hermes/.env、config.yaml 或登录文件上传到仓库。

检查命令

配置完成后运行官方诊断与一次性对话：

hermes doctor
hermes chat --quiet -q "Reply with exactly: ok" --max-turns 3

参考：NousResearch 官方 AI Providers、CLI Commands 与 Hermes Agent README。