瑞科 API 使用文档

Appearance

Codex CLI ​

推荐方式：使用后台生成配置 ​

进入 API Key -> 使用密钥 -> Codex 配置，认证模式选择 API Key Mode，再按页面提示写入配置文件。

不要选择兼容模式

旧的“兼容模式”会生成 requires_openai_auth = true。该模式用于兼容旧版 Codex；使用 gpt-5.6-sol、gpt-5.6-terra 等模型并希望 Codex 生图时，请选择 API Key Mode。

Windows 用户也可以下载 一键接入脚本。脚本会写入 API Key Mode 配置，并在覆盖前保留原配置备份。

手动配置 ​

配置文件位于运行 Codex 的电脑，而不是瑞科 API 服务器：

text
Windows: %USERPROFILE%\.codex\config.toml
macOS/Linux: ~/.codex/config.toml

将正在使用的 OpenAI Provider 配置为：

toml
model_provider = "OpenAI"
model = "gpt-5.6-sol"

[model_providers.OpenAI]
name = "OpenAI"
base_url = "https://api.ruikon.com"
wire_api = "responses"
requires_openai_auth = false
http_headers = { "x-openai-actor-authorization" = "local-image-extension" }

model_provider 必须与 [model_providers.OpenAI] 的 Provider ID 完全一致。模型可替换为当前分组实际支持的名称，例如 gpt-5.6-terra。

API Key 继续保存在同目录的 auth.json：

json
{
  "OPENAI_API_KEY": "sk-替换为你的瑞科 API Key"
}

不要删除 OPENAI_API_KEY，也不要替换成 OpenAI 官方 Key。新版 Codex 已默认提供图片能力，不必额外添加 image_generation = true；旧配置已有该字段时可以保留。

上述 model_providers.*、wire_api、requires_openai_auth 和 http_headers 字段可在 Codex 配置参考 中核对。其中 local-image-extension 是瑞科 API 用于 API Key Mode 的图片桥接标识。

无法生图：提示“未提供内置图片生成工具” ​

现象 ​

使用自定义 OpenAI Provider 请求 gpt-5.6-sol 或 gpt-5.6-terra 时，Codex 提示：

当前会话未提供内置图片生成工具。可以改用 CLI 图片生成，但需要本机配置 OPENAI_API_KEY。

即使后台已经确认以下配置正确，问题仍可能出现：

  • OpenAI 账号已启用 Codex 图片桥接策略。
  • 分组已开启“允许图片生成”。
  • 请求命中了正确账号。
  • 客户端已识别为官方 Codex。

原因 ​

社区排查发现，近期 Codex 的 Responses Lite 请求不会采用服务端自动注入的 hosted image_generation，图片应由 Codex 客户端本地 image_gen 执行器处理。

如果自定义 Provider 仍设置为 requires_openai_auth = true，API Key Provider 不会获得这一本地图片执行器，当前 task 的工具表中便没有图片生成工具。此时继续调整服务端账号或分组不会解决客户端工具缺失。

解决步骤 ​

  1. 在运行 Codex 的电脑上打开 config.toml，不要修改瑞科 API 服务器配置。
  2. 把正在使用的 Provider 改为本页“手动配置”中的 API Key Mode：requires_openai_auth = false，并添加 local-image-extension 请求头。
  3. 保留 auth.json 中现有的瑞科 API Key。
  4. 检查后台 API Key -> 使用密钥 -> Codex 配置 是否选择了 API Key Mode。
  5. 完全退出 Codex CLI、Codex Desktop 和 VS Code/VS Code Insiders 中的 Codex 会话。
  6. 重新启动 Codex 并新建 task，再发起生图请求。已有 task 不会重新加载工具表。

必须新建 task

只关闭当前对话或重新发送提示词不够。Provider 配置和工具表在 task 创建时加载，必须结束残留进程并创建新 task。

Windows PowerShell 可先检查残留进程：

powershell
Get-CimInstance Win32_Process |
  Where-Object { $_.Name -match 'codex' -or $_.CommandLine -match '(?i)\bcodex\b' } |
  Select-Object ProcessId, Name, CommandLine

关闭 VS Code 和所有 Codex 终端后，如果仍有残留：

powershell
Get-Process codex, codex-code-mode-host -ErrorAction SilentlyContinue |
  Stop-Process -Force

然后重新启动 Codex 并新建 task 测试。

仍然失败时 ​

按顺序检查：

  1. 修改的是用户级 config.toml，而不是项目内 .codex/config.toml。
  2. 文件中没有另一个同名 Provider 或 profile 覆盖当前配置。
  3. model_provider = "OpenAI" 与 [model_providers.OpenAI] 大小写一致。
  4. auth.json 是合法 JSON，且包含非空的 OPENAI_API_KEY。
  5. 新 task 使用的是目标模型和目标分组，不是旧 task 保存的模型。
  6. 后台使用记录中能看到新 task 的 Responses 请求。

如果新 task 已出现本地图片工具，但调用后才返回账号、分组或上游错误，再检查服务端图片桥接策略、分组图片权限和账号模型能力。前者是“客户端没有工具”，后者是“工具已经调用但服务端执行失败”，两者不要混在一起排查。

验证普通调用 ​

启动 Codex 后发送一句简单问题，再到使用记录查看 /v1/responses 请求。若客户端版本只发送 /v1/chat/completions，确认分组允许该端点。

其他常见问题 ​

  • WebSocket 是可选能力，遇到反复重连时先关闭 WebSocket，使用 HTTPS Responses。
  • model 必须是分组允许的模型，不要使用上游不可见的内部名称。
  • 修改 Provider、认证模式或图片相关配置后，都必须彻底重启 Codex 并新建 task。

瑞科 API 文档

Copyright © 2026 瑞科 API