照着 7 步走，第一次请求就能跑通。
这是一份给第一次使用 API 的教程。你会从安装客户端开始，创建自己的 API Key，导入 CCSwitch，最后在 Codex 里发出第一句 “hi”。每一步都写明了应该看到什么。
https://api.blue-ring.xyz/v1开始前，你只需要准备这些
这条教程按 CCSwitch + Codex 来写；只调用 API 的开发者可以直接跳到最后的可选章节。
用于进入控制台、创建密钥和查看自己的用量。
推荐 Codex + CCSwitch；开发者也可以直接使用终端或 Python。
从控制台导入后，CCSwitch 会把这份 Provider 配置交给 Codex。
完成这章以后：你应该能在 Codex 里看到一条正常回复，也能在控制台的用量页面找到这次请求。
安装 Codex 和 CCSwitch
先安装，再配置。不要在还没有 Provider 的时候反复折腾 Codex 的默认设置。
- 安装 Codex按你当前系统提供的安装方式完成安装。安装后先不要在里面创建复杂配置。
- 安装 CCSwitchCCSwitch 用来保存和切换 Provider，支持 Windows、macOS 和 Linux。打开官方发布页后，下载与你系统对应的安装包。下载 CCSwitch
- 两个程序都能打开看到程序窗口即可。此时还没有 API Key，不需要发送请求。
只调用 API 的开发者不需要安装这两个工具，直接看最后的“API 调用（可选）”。
注册或登录 Blue Ring
密钥和用量都在控制台里管理，不要向别人索取“公共 Key”。
左侧菜单或页面中能看到 API Keys / API 密钥 入口。
创建 API Key，并马上保存
密钥就是调用权限。建议为每台设备或每个用途单独创建，出问题时可以只撤销这一枚。
- 进入 API Keys在控制台打开 API Keys 或 API 密钥页面。
- 点击创建密钥名称可以写
codex-mac、开发测试等容易识别的名字。 - 选择需要的分组如果页面提供分组或模型组，按你要使用的能力选择；不确定时先按默认值。
- 创建后复制完整密钥创建成功后只复制一次并保存到 CCSwitch 的安全配置中，不要发到群里。
sk-••••••••••••••••••••••••已隐藏不要把完整 Key 放进截图、Git、公开 issue 或聊天记录。
你已经把密钥放进密码管理器或客户端安全存储，并且知道它对应哪台设备。
导入 Provider，先不用手动填模型
优先使用控制台的“导入 CC Switch”按钮。只有自动导入不可用时，才按下面的字段手动填写。
导入 CC Switch。图中名称和 Key 均为脱敏示例。找到刚刚创建的密钥，点击「导入 CC Switch」（如果页面提供这个按钮）。
浏览器询问是否打开应用时选择允许，然后在 CCSwitch 中点击导入。
写一个容易识别的名称，点击添加并确认保存，最后点击启用。
https://api.blue-ring.xyz/v1保留 /v1；不要填到具体请求路径你刚创建的密钥不要把前后引号一起复制，不要使用别人的 Key按客户端提示导入路线通常不需要新手额外设置在 CCSwitch 里点击启用
这一步不需要打开终端，也不需要先请求模型列表。CCSwitch 配置好以后，Codex 会直接使用这份 Provider。
在 CCSwitch 的 Provider 列表里找到刚刚导入的配置。
不要再新建第二份配置，直接启用当前这一份。
看到“使用中”或启用状态，说明配置已经交给 Codex。
CCSwitch 里的 Blue Ring 配置显示为启用或使用中。
打开 Codex，输入 hi
CCSwitch 配置完成后，Codex 会直接使用刚启用的 Provider。
hi 并发送；看到正常回复就可以进入下一步。Codex 对 hi 返回正常内容。
回控制台看用量
Codex 已经能正常回复后，再回控制台确认请求记录和消耗。
先看消息内容是否正常，不要只看客户端的加载状态。
回到控制台的使用记录或用量页面。
看到刚才的请求和消耗，说明整条链路已完成。
你已经跑通了 Blue Ring
之后换模型、换客户端，都只需要重复检查三项：Base URL、API Key、Model。
Codex 能返回内容，就是客户端已经接入。
控制台使用记录里应该出现刚才的请求。
确认这次调用产生了对应的 Token 或费用记录。
需要直接调用 API？
下面的模型列表、curl 和 Python 只服务于 API 开发者。使用 CCSwitch + Codex 的新手可以直接跳过。
这部分不是 Codex 的必经步骤。只有当你要在终端、脚本或自己的程序里调用 Blue Ring 时，才需要继续。
export BLUE_RING_API_KEY="替换成你的 API Key"
curl "https://api.blue-ring.xyz/v1/models" \
-H "Authorization: Bearer $BLUE_RING_API_KEY"export BLUE_RING_API_KEY="替换成你的 API Key"
export BLUE_RING_MODEL="替换成 /v1/models 返回的模型 ID"
curl "https://api.blue-ring.xyz/v1/responses" \
-H "Authorization: Bearer $BLUE_RING_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$BLUE_RING_MODEL"'",
"input": "你好，请用一句话介绍你自己。"
}'OpenAI SDK 只需要替换 base_url 和 api_key。
from openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://api.blue-ring.xyz/v1",
)
response = client.responses.create(
model="YOUR_MODEL_ID",
input="Hello from Blue Ring",
)
print(response.output_text)常见问题：先看状态码
先确认 CCSwitch 是否启用，再判断是密钥、路径还是上游问题。
401API_KEY_REQUIRED / 未授权
请求没有携带有效密钥。检查 Authorization: Bearer ... 是否存在，环境变量是否为空，或客户端是否把 Key 填到了错误字段。
404找不到 chat/completions
当前公开入口的主调用路径是 /v1/responses。如果客户端只能发 /v1/chat/completions，切换到 Responses API / OpenAI Responses 模式。
200有响应但模型不可用
如果你走的是 CCSwitch 导入路线，先重新确认当前 Provider 已启用；直接调用 API 的开发者再请求 /v1/models，使用当前返回的模型 ID。
—请求卡住或超时
先用最短文本测试；确认没有额外代理、错误的流式设置或重复的 /v1 路径，再判断是否只是上游模型暂时拥塞。
↗CCSwitch 导入后 Codex 没反应
重新确认 Provider 是否处于启用状态，Base URL 是否仍然包含 /v1，并关闭后重新打开 Codex 让它读取最新配置。
API Key 安全：三条底线
API Key 等同于账户调用权限，按密码处理，不要当成普通配置分享。
教程、群聊、工单和屏幕录制都不要出现完整密钥。
本地使用环境变量或客户端安全存储，不要写入仓库。
在控制台删除旧密钥，再创建新的密钥替换客户端配置。