🔄 客户端接入

本站对外提供 OpenAI Compatible 接口。大多数聊天客户端、IDE 插件和脚本只需要填写 Base URL 与 API Key。

Base URL: 本站地址/v1
API Key:  sk-你的KEY

CC Switch

本指南按 CC Switch v3.16.5 的中文界面核对。先从 官方 Release 安装最新版；Windows 选择 .msi，macOS 选择 .dmg。界面名称会随版本微调，但字段含义不变。

把 Shana 接入 CC Switch

这套配置用于 Codex 调用本站的 GPT 模型。每一个 API Key 只会看到它所属分组已开放的模型。下方图示为 CC Switch v3.16.5 官方前端的 Codex 实际界面，不含用户数据。

1

打开 Codex 的供应商列表

打开 CC Switch，先在左侧选择 Codex，再点击右上角的 +。不要在 Claude Code 或 Gemini 的入口里添加，三个应用的配置是独立的。

实际 Codex 页面：确认顶部 OpenAI 图标对应的 Codex 标签已选中，再点击「添加供应商」。

2

选择「自定义配置」

保持顶部的 Codex 供应商 标签，点击左侧第一项 自定义配置。不要选择 OpenAI Official，也不要切到「统一供应商」。

实际 Codex 配置页：蓝色选中的「自定义配置」才是本站需要使用的入口。

3

在自定义配置中填入 URL 与 API Key

先填写 API Key 与 API 请求地址，地址固定为 本站地址/v1。上游格式保持 Responses（原生），随后点击「获取模型列表」。CC Switch 会把 API Key 同步到下方的 auth.json；再确认 config.toml 与下面内容一致。

真实配置界面：填写本站 URL 后保留「Responses（原生）」，模型从「获取模型列表」拉取。

// auth.json
{
  "OPENAI_API_KEY": "sk-你的API密钥"
}

# config.toml
model_provider = "shana"
model = "gpt-5.6-terra"

[model_providers.shana]
name = "Shana API"
base_url = "本站地址/v1"
wire_api = "responses"
requires_openai_auth = true

Base URL 已经包含 /v1。不要再追加 /chat/completions、/responses 或额外的 /v1。本站走 responses，不需要开启「本地路由映射」。

4

启用并验证

保存后，在供应商卡片上点击「启用」，完全退出并重新打开 Codex，再执行 /model 选择模型。GPT-5.6 请选择 gpt-5.6-luna、gpt-5.6-terra 或 gpt-5.6-sol。

成功标志：CC Switch 的模型下拉列表能拉到模型，并且 Codex 的 /model 能看到同一批模型。只要其中一步失败，就不要继续反复重装。

仍看不到 GPT-5.6？请使用下方的排障教程。它会检查 CC Switch 实际写入的 Codex 配置和模型目录，不会暴露或覆盖你的 API Key。

Codex 桌面版（ChatGPT App）

Windows 或 macOS 用户可从 OpenAI 官方下载页 安装 ChatGPT 桌面版，登录后从 App 内进入 Codex。桌面版内置 Codex 与 npm 安装的 Codex CLI 不是同一个程序；仅升级 CLI 不会更新桌面版内置的 Codex。

Codex CLI

使用 GPT-5.6 时要求 @openai/codex 0.144.0 或更高版本。下载/安装地址：OpenAI Codex CLI 官方文档，NPM 包：@openai/codex。具体安装命令以官方页面为准。

# Shana 侧需要准备的配置值
Base URL: 本站地址/v1
API Key:  sk-你的KEY
Models:   gpt-5.6-luna / gpt-5.6-terra / gpt-5.6-sol

Codex 的自定义 provider 配置会随版本变化；请按官方文档填写 provider，再把 Base URL、API Key 和模型名替换为上面的 Shana 配置值。

Codex / ChatGPT App 看不到 GPT-5.6

适用于 API Key 登录、自定义 provider、Sub2API 和 CC Switch 场景。仅在配置里写入 model = "gpt-5.6-terra"，不一定会让模型选择器显示 GPT-5.6；模型目录还需要由 model_catalog_json 提供。

帮我排查并修复 Codex CLI / ChatGPT 桌面 App 在 API Key 登录、自定义 provider、Sub2API 或 CC Switch 场景下，模型列表不显示 GPT-5.6 的问题。

目标：
让本机 Codex 的 /model，以及 ChatGPT 桌面 App 内置 Codex 的模型列表能够看到：
gpt-5.6-sol
gpt-5.6-terra
gpt-5.6-luna

执行要求：
1. 不要猜测操作系统、Codex 路径、CODEX_HOME 或配置结构，先读取实际环境。
2. 用户级 config.toml 已存在时，修改前必须备份；不存在时先记录该状态，再创建新文件。
3. 不要输出、删除或改写现有 API Key；保留现有 provider、base_url 和其他无关配置。
4. 只修复模型目录和模型选择器问题。每一步执行后读取结果，再决定下一步。

一、确认 Codex 实际路径和版本

macOS / Linux：
command -v codex
which -a codex
codex --version

Windows PowerShell：
Get-Command codex -All | Select-Object CommandType, Source, Version
codex --version

要求至少 0.144.0。低于这个版本就升级：
npm install -g @openai/codex@latest

升级后重新检查路径和版本，确认终端没有被旧版 codex 抢先命中。如果存在多个 codex，先解释当前实际使用的是哪一个。

二、定位 CODEX_HOME 并备份配置

优先读取 CODEX_HOME 环境变量；未设置时，默认目录为 macOS/Linux 的 ~/.codex 或 Windows 的 $HOME\.codex。不要修改项目目录里的 .codex/config.toml 来替代用户级 provider 配置。若 config.toml 不存在，不要执行会报错的复制命令；先创建 CODEX_HOME 目录并记录“无旧配置可备份”。

macOS / Linux 备份示例：
cp ~/.codex/config.toml ~/.codex/config.toml.bak-$(date +%Y%m%d-%H%M%S)

Windows PowerShell 备份示例：
$stamp = Get-Date -Format yyyyMMdd-HHmmss
Copy-Item "$HOME\.codex\config.toml" "$HOME\.codex\config.toml.bak-$stamp"

三、检查当前 Codex 配置

macOS / Linux：
grep -nE '^(model|model_provider|model_catalog_json)[[:space:]]*=|base_url' ~/.codex/config.toml

Windows PowerShell：
Select-String -Path "$HOME\.codex\config.toml" -Pattern '^(model|model_provider|model_catalog_json)\s*=|base_url'

如果 Codex 或 CC Switch 使用了 --profile，还要检查实际选中的 $CODEX_HOME/profile-name.config.toml。profile 文件里的 model_catalog_json 会覆盖主 config.toml；不要只改主配置后就停止排查。

四、检查 Codex 当前看到的模型目录

执行：
codex debug models

该命令应该输出 JSON。确认输出中是否同时存在：
gpt-5.6-sol
gpt-5.6-terra
gpt-5.6-luna

再执行下面的命令，区分当前有效目录和程序内置目录：
codex debug models --bundled

如果普通输出已经有三个 GPT-5.6 模型，但 App 或 /model 里看不到，重点检查 model_catalog_json。若升级后两个输出都没有 GPT-5.6，不要凭空手写未知 JSON 结构；先检查是否仍命中旧二进制、ChatGPT App 是否捆绑旧版 Codex、CC Switch 是否使用了另一个 CODEX_HOME，并报告准确结果。

五、创建模型目录文件

如果 ~/.codex/config.toml 没有 model_catalog_json，则把“包含三个 GPT-5.6 模型”的 codex debug models JSON 输出保存为模型目录。

macOS / Linux：
mkdir -p ~/.codex
codex debug models > ~/.codex/cc-switch-model-catalog.json
python3 -m json.tool ~/.codex/cc-switch-model-catalog.json >/dev/null

Windows PowerShell（明确写成无 BOM 的 UTF-8，避免旧版 PowerShell 生成 UTF-16 文件）：
$catalogPath = Join-Path $HOME ".codex\cc-switch-model-catalog.json"
$catalogJson = (codex debug models | Out-String)
[System.IO.File]::WriteAllText($catalogPath, $catalogJson, [System.Text.UTF8Encoding]::new($false))
Get-Content -Raw $catalogPath | ConvertFrom-Json | Out-Null

保存后必须确认文件是合法 JSON，并且包含三个 GPT-5.6 模型。若 codex debug models --bundled 才是包含三者的正确目录，可以使用 --bundled 导出，并说明原因。

六、写入用户级 config.toml

在用户级 ~/.codex/config.toml 顶层加入 model_catalog_json。它必须和 model、model_provider 同级，并放在第一个 [model_providers...] 表头之前。已有该字段时更新原值，不要重复写第二个。

macOS 示例：
model_provider = "custom"
model = "gpt-5.6-terra"
model_catalog_json = "/Users/你的用户名/.codex/cc-switch-model-catalog.json"

[model_providers.custom]
# 保留现有 provider 配置

Windows 示例（TOML 路径建议使用正斜杠）：
model_provider = "custom"
model = "gpt-5.6-terra"
model_catalog_json = "C:/Users/你的用户名/.codex/cc-switch-model-catalog.json"

[model_providers.custom]
# 保留现有 provider 配置

必须使用本机真实绝对路径，不要照抄“你的用户名”。修改后解析配置，确认 model_catalog_json 没有误写进 [model_providers.custom] 表内。

七、验证

执行：
codex debug models
codex doctor --summary --ascii

期望 codex debug models 的 JSON 中能够找到：
gpt-5.6-sol
gpt-5.6-terra
gpt-5.6-luna

同时确认 doctor 没有报告 config.toml 或 model_catalog_json 解析错误。

八、检查 ChatGPT 桌面 App 内置 Codex

macOS：
/Applications/ChatGPT.app/Contents/Resources/codex debug models

它也应该显示三个 GPT-5.6 模型。如果该二进制版本低于 0.144.0，请先更新 ChatGPT App；npm 全局升级不会替换 App 自带的二进制。

Windows：
不要假定 App 内置 Codex 与 npm 全局 codex 是同一个文件。通过 ChatGPT App 诊断信息或实际安装目录定位它捆绑的 codex.exe，再对该真实路径执行 debug models；若版本过旧，更新 ChatGPT App。

九、重新加载

彻底退出 ChatGPT / Codex App，包括系统托盘或后台进程，不是只关闭窗口。重新打开后再检查 /model 和模型选择器。

最后向我汇报：
1. 实际 Codex 路径与版本。
2. 实际 CODEX_HOME 和已创建的备份路径。
3. model_catalog_json 的最终绝对路径及其所在 TOML 层级。
4. CLI 与 App 内置 Codex 是否都能看到三个 GPT-5.6 模型。
5. 若仍失败，给出准确失败层，不要只说“可能是缓存”。

注意：
API Key 登录、自定义 provider、Sub2API、CC Switch 场景下，ChatGPT 账号模型列表和 Codex API Key 模型列表不是一回事。仅设置 model = "gpt-5.6-terra" 不一定会让模型选择器显示 GPT-5.6，关键是有效且可解析的 model_catalog_json。

配置字段与命令可同时参考 OpenAI 的 Codex 配置参考和 开发者命令说明。

Claude Code

当前核对版本：@anthropic-ai/claude-code 2.1.196。下载/安装地址：Claude Code 官方文档，NPM 包：@anthropic-ai/claude-code。具体安装命令以官方页面为准。

本站的 Kiro 是对外售卖代号；用户侧模型名使用 claude-kiro。更高阶 Claude 池使用 max 分组，并直接暴露模型广场里的 Claude 模型名。若 Claude Code 当前版本要求 Anthropic 原生 Messages 协议或额外代理层，请以官方文档和 CC Switch 的适配说明为准。

ChatBox / LobeChat / NextChat

Cline / Continue / Cursor 类工具

选择 OpenAI Compatible Provider 后使用同样的 Base URL 和 API Key。若工具要求单独填写模型名，请填「模型广场」里能看到的模型 ID。

🔑 API Key 使用说明

什么是 API Key

API Key 是你在本站的身份凭证。每个 Key 绑定一个分组（group），分组决定了你可用的模型和计费倍率。

分组说明

• PRO — 高性能聊天分组，可用 GPT-5.4、GPT-5.5 与 GPT-5.6 系列
• plus — 轻量聊天分组，可用 GPT-5.4、GPT-5.5 与 GPT-5.6 系列
• claude kiro — Claude 聊天分组，对外模型名以模型广场为准
• max — 高阶 Claude 聊天分组，可用模型以模型广场为准
• image2 — 绘图分组，可用 gpt-image-2，按图计费

费用说明

模型广场展示的是对外实际价格，计算方式为：模型原价 × 当前分组倍率。倍率本身不是价格。

公开模型：
gpt-5.4
gpt-5.4-mini
gpt-5.5
gpt-5.6-luna
gpt-5.6-terra
gpt-5.6-sol
claude-kiro
claude-fable-5
claude-haiku-4-5-20251001
claude-opus-4-6
claude-opus-4-7
claude-opus-4-8
claude-sonnet-4-6
claude-sonnet-5
gpt-image-2

📊 可用模型

📡 API 调用示例

Chat Completions

curl 本站地址/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的KEY" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": true
  }'

Image2 接入：文生图

image2 分组使用 OpenAI Compatible Images API。请先创建绑定 image2 分组的 API Key，再把客户端或代码里的 Base URL 设置为 本站地址/v1。

文生图使用 POST /images/generations，模型名固定使用模型广场里显示的 gpt-image-2。

curl 本站地址/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的KEY" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一张 16:9 的赛博朋克城市夜景，电影感，高细节",
    "n": 1,
    "size": "1536x1024",
    "quality": "high",
    "response_format": "b64_json"
  }'

常用参数：model、prompt 必填；n、size、quality、response_format 可按上游支持情况填写。常用尺寸为 1024x1024、1536x1024、1024x1536；medium / high 通常代表质量档位，不保证固定 2K/4K 像素。

返回结果通常在 data[0].b64_json 或 data[0].url。如果返回 b64_json，需要由调用方自行保存成图片文件。

Image2 文生图 Python 示例

from openai import OpenAI

client = OpenAI(
    base_url="本站地址/v1",
    api_key="sk-你的KEY",
)

result = client.images.generate(
    model="gpt-image-2",
    prompt="一张横版夏日海边插画，清爽明亮，高细节",
    n=1,
    size="1536x1024",
    quality="high",
    response_format="b64_json",
)

image = result.data[0]
print(getattr(image, "b64_json", None) or getattr(image, "url", None))

Image2 接入：图生图 / 参考图

图生图、参考图改图使用 POST /images/edits。请求体必须是 multipart/form-data，不要用 JSON。单张参考图用 image=@./reference.png，多张参考图用多个 image[] 字段。

curl 本站地址/v1/images/edits \
  -H "Authorization: Bearer sk-你的KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=参考这张图的人物姿势，生成一张写实商业海报" \
  -F "n=1" \
  -F "size=1536x1024" \
  -F "quality=high" \
  -F "image=@./reference.png"

多图参考示例：

curl 本站地址/v1/images/edits \
  -H "Authorization: Bearer sk-你的KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=融合两张参考图的主体和风格，生成一张横版封面" \
  -F "n=1" \
  -F "size=1536x1024" \
  -F "quality=high" \
  -F "image[]=@./ref1.png" \
  -F "image[]=@./ref2.png"

Image2 图生图 Python 示例

from openai import OpenAI

client = OpenAI(
    base_url="本站地址/v1",
    api_key="sk-你的KEY",
)

with open("./reference.png", "rb") as image:
    result = client.images.edit(
        model="gpt-image-2",
        image=image,
        prompt="保留参考图主体，改成日系动画海报风格",
        n=1,
        size="1536x1024",
        quality="high",
        response_format="b64_json",
    )

print(result.data[0].b64_json or result.data[0].url)

Image2 返回格式

{
  "created": 1760000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgo...",
      "revised_prompt": "..."
    }
  ]
}

也可能返回：

{
  "data": [
    {
      "url": "https://example.com/image.png"
    }
  ]
}

Python SDK 示例

from openai import OpenAI

client = OpenAI(
    base_url="本站地址/v1",
    api_key="sk-你的KEY"
)

response = client.chat.completions.create(
    model="gpt-5.4-mini",
    messages=[{"role": "user", "content": "你好"}]
)
print(response.choices[0].message.content)

❓ 常见问题

Q：提示 401 未授权怎么办？

检查 API Key 是否拼写正确，前缀必须是 sk-。确认 Key 状态为「有效」。

Q：为什么我调 gpt-image-2 返回 502？

图片生成依赖上游服务商，如遇 502 请稍后重试或联系管理员切换上游。

Q：Claude 为什么看不到？

请先确认你的 API Key 绑定了 claude kiro 或 max 分组。具体模型名请直接从模型广场复制；若模型广场未显示，说明当前 Claude 通道正在维护或未向你的账号开放。

Q：Codex 为什么看不到 GPT-5.6？

API Key 与 ChatGPT 账号的模型目录并不相同。请打开 客户端接入里的 GPT-5.6 排障教程，让 AI 检查 Codex 版本、实际配置层和 model_catalog_json。

Q：我的余额不足怎么办？

联系管理员充值。余额在个人中心可查看。

Q：如何查看实时价格？

访问「模型广场」板块，查看当前公开分组下的可用模型和实际价格。实际价格 = 模型原价 × 分组倍率。