YIXO CODEX GUIDE
从安装到验证，开始使用 Codex
按顺序完成账号、密钥、环境、CCSwitch 和 Codex 配置。灵集 AI 接口地址：https://ai.lingee.ltd。
1. 在灵集 AI 创建 API 密钥
- 打开 ai.lingee.ltd，注册或登录账号。
- 进入控制台的“API 密钥”页面，点击创建密钥。
- 选择适合当前用途的分组或模型权限，创建后立即复制并妥善保存。
- 为不同设备或项目单独创建密钥，方便后续停用和排查。
Base URL: https://ai.lingee.ltd
API Key: YOUR_API_KEY密钥格式说明：YOUR_API_KEY 是占位符，请替换为在灵集 AI 控制台创建的真实密钥，格式通常以 sk- 开头，例如 sk-xxxxxxxxxxxxxxxxxxxxxxx。
2. 环境准备与 Codex 安装
Codex 命令行依赖 Node.js。请先在终端执行 node -v 与 npm -v；能看到版本号即可进入安装步骤。建议使用 Node.js 当前 LTS 版本。
Windows
- 从 Node.js 官网安装 LTS 版本；安装完成后重新打开 PowerShell。
- 安装 Codex CLI：
npm install -g @openai/codex
codex --version若终端提示找不到 npm，请重启 PowerShell；仍无效时检查 Node.js 是否已加入系统 PATH。
macOS
- 从 Node.js 官网安装 LTS 版本，或使用已有的 Node.js 环境。
- 在“终端”执行：
npm install -g @openai/codex
codex --version如遇权限错误，不要使用不明来源脚本；优先按 npm 的错误提示修复 Node.js 安装目录权限。
3. 可选：一键导入 CCSwitch
不使用 CCSwitch 的用户可跳过本节，直接进入下一步配置 Codex。使用 CCSwitch 时，无需手动新增提供商或填写 Base URL、API Key 与模型。
请前往 CCSwitch 官网 下载并安装。
- 在灵集 AI 控制台创建 API 密钥。
- 在该密钥所在行的“操作”栏点击“导入到 CCS”。
- 按页面提示完成导入后，打开 CCSwitch，确认已出现灵集 AI 配置。
- 在 CCSwitch 中选择已导入的配置并执行连接测试；成功后按 CCSwitch 的引导启动或连接 Codex。
4. 配置 Codex 使用灵集 AI
以下步骤仅适用于直连灵集 AI 的用户。关闭正在运行的 Codex 后，创建或编辑用户目录中的配置文件；将 YOUR_MODEL_ID 改为控制台显示的可用模型，YOUR_API_KEY 改为你自己的密钥。
配置文件位置：Windows 通常位于 C:\Users\当前用户名\.codex，例如 C:\Users\Administrator\.codex。其中包含 config.toml 和 auth.json；若你的 Windows 用户名或 Codex 安装方式不同，请以本机实际的 Codex 配置目录为准。
直连灵集 AI：config.toml
model_provider = "yixo"
model = "YOUR_MODEL_ID"
model_reasoning_effort = "high"
[model_providers.yixo]
name = "Yixo AI"
base_url = "https://ai.lingee.ltd"
wire_api = "responses"
requires_openai_auth = false直连灵集 AI：auth.json
{
"OPENAI_API_KEY": "YOUR_API_KEY"
}| 系统 | 配置目录 |
|---|---|
| Windows | %USERPROFILE%\.codex\config.toml 和 %USERPROFILE%\.codex\auth.json |
| macOS | ~/.codex/config.toml 和 ~/.codex/auth.json |
5. 验证配置
先用与 Codex 相同的 Responses 接口确认密钥、网络和模型可用，再启动 Codex。以下命令仅用于直连灵集 AI；使用 CCSwitch 时，请按“导入到 CCS”完成后的 CCSwitch 连接方式进行测试。
Windows PowerShell
curl.exe "https://ai.lingee.ltd/responses" `
-H "Content-Type: application/json" `
-H "Authorization: Bearer YOUR_API_KEY" `
-d '{"model":"YOUR_MODEL_ID","input":"你好，请返回一条测试消息"}'macOS 终端
curl https://ai.lingee.ltd/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{"model":"YOUR_MODEL_ID","input":"你好，请返回一条测试消息"}'- 返回正常 JSON：说明密钥、网络和 Base URL 已连通。
- 随后在项目目录执行
codex。 - 输入一个简单请求，例如“说明当前目录中的文件”，确认 Codex 能正常响应。
常见问题
使用灵集 AI 接口遇到报错时，先记录错误码和报错文字，再按下表排查。同一错误码可能有多种原因，请结合具体提示判断。
| 现象 | 优先检查与处理 |
|---|---|
| 400 请求格式错误 | 检查 JSON、字段名及接口支持的参数；出现 Failed to read request body 时，检查上传是否中断、请求是否过大。 |
| 401 未授权 | 确认 API Key 完整、有效且未被停用；直连 Codex 的请求头应为 Authorization: Bearer YOUR_API_KEY。 |
| 402 特定上游图像账户余额不足 | 当报错明确提示 Upstream image account has insufficient balance 时，表示上游图像账户余额不足，请联系本站售后；不能据此判断本站账户余额不足。 |
| 403 账户余额不足或权限受限 | 本站账户余额不足通常返回 403；在 灵集 AI 控制台检查余额。若提示密钥过期、分组或接口权限不足、订阅不可用或 IP 限制，则处理对应问题；不能把所有 403 都当作余额不足。 |
| 404 路径或模型不可用 | 直连 Codex 的 Base URL 为 https://ai.lingee.ltd；确认接口路径正确，模型 ID 在当前密钥分组中可用。 |
| 413 请求体过大 | 减少图片和大文件，降低单次上传大小。上下文超限不一定返回 413，也可能返回 400；出现上下文超限提示时，删除无关历史、缩短输入或拆分任务。 |
| 429 限流或额度耗尽 | 可能是密钥总额度、5 小时/日/7 天限额、平台周期配额、请求频率或并发限制，以及上游限流。总额度耗尽需要检查额度设置，周期限额需要等待重置；请求限流则降低频率或并发。详见下方“余额、额度与限流”。 |
| 500 服务内部错误 | 偶发时稍后重试；持续出现时，记录 request_id 并联系本站售后。 |
| 502 网关异常 | 可能是服务端或上游异常，也可能是代理链路中断；用小请求复测，持续失败时反馈。 |
| 503 服务暂不可用 | 可能是服务繁忙或当前模型暂无可用通道；稍后重试，或选择控制台中当前分组支持的其他模型。 |
| 504 网关超时 | 减少上下文，客户端支持时开启流式输出；小请求仍持续超时则联系本站售后。 |
| 522 边缘网关连接超时 | 通常表示边缘网关未能连到源站；稍后重试，并保留报错页面中的追踪编号反馈。 |
| 524 边缘网关响应超时 | 通常表示源站响应超过边缘网关等待时间；减少上下文、拆分任务，支持时开启流式输出。 |
| Codex 无法读取配置 | 检查用户配置目录、文件名和 JSON/TOML 格式；修改后重新启动 Codex。使用 CCSwitch 时确认已启用导入的灵集 AI 配置。 |
请求格式、接口地址和模型怎么检查？
余额、额度与限流：403 和 429 怎么区分？
账户余额、单个 API Key 的额度和请求限流是不同问题。请结合错误文字、错误代码和灵集 AI 控制台信息处理，不要只根据 HTTP 状态码判断。
- 403 账户余额不足：提示
INSUFFICIENT_BALANCE、Insufficient account balance或insufficient balance时，检查本站账户余额，补充余额后再试；余额正常但仍报错时联系本站售后。 - 403 权限或状态限制：密钥过期、分组或接口权限不足、订阅不可用、IP 访问限制也可能返回 403。按具体提示检查对应设置，充值不一定能解决。
- 429 密钥总额度耗尽：提示“API key 额度已用完”时，检查该密钥的已用额度和总额度。需要调整额度设置或联系本站售后；单纯等待、反复重试或给账户充值，都不一定能解除密钥额度限制。
- 429 周期限额：密钥的 5 小时、日、7 天限额，以及平台日、周、月配额达到上限时，查看具体限额和重置时间；等待窗口重置，或按权限调整限额，不能统一按等待 30–60 秒处理。
- 429 请求限流：请求频率、并发或排队请求过多时，降低频率或并发，避免连续快速重试；优先遵守响应中的
Retry-After等等待提示，未给出时间时可等待 30–60 秒后复测。 - 429 上游限流：
Upstream rate limit exceeded表示上游触发限流，稍后重试；切换模型时，只选择当前分组支持的模型。 The usage limit has been reached表示某一层使用量达到限制；仅凭这句话无法确定限制来自本站还是上游，需要结合完整错误判断。
402 的特定场景：报错为 Upstream image account has insufficient balance 时，请将错误信息交给本站售后处理。这属于上游图像账户问题，不代表需要给本站账户充值。
流式输出中途断开怎么办？
以下报错通常说明连接在响应完成前中断：
stream disconnected before completion、stream closed before response.completedresponses stream error、stream ended before a terminal eventconnection reset by peer、client connection lost、context canceledserver sent GOAWAY、http2: server sent GOAWAY
- 确认任务是否被手动取消；取消后产生的中断提示不一定是服务故障。
- 检查网络是否稳定，代理是否切换节点或中途断开；可在网络允许时停用不稳定代理复测。
- 重启客户端，用较小的上下文测试；减少图片、大文件和无关历史。
- 稍后重试，避免连续快速请求。若多次小请求也失败，记录时间、模型和请求编号，联系本站售后。
请求太大、服务繁忙或长时间超时怎么办？
长上下文、大文件和复杂任务可能增加处理时间，但超时也可能来自网络、网关或服务端。不要仅凭超时判断密钥失效。
- 删除无关历史，压缩提示词，减少图片和单次文件大小。
- 把大任务拆成多个小任务；客户端支持时开启流式输出。
- 等待 30–60 秒后再试；若服务明确给出等待时间，以其提示为准。
- 用小请求复测。小请求也持续出现 500、502、503 或 504 时，联系本站售后。
报错含 no available accounts、no auth available 或 model channel not available 时，可能是服务端当前暂无可用通道，请保留原始错误反馈。
如果页面出现 522、524 或 cf-ray，请保留错误码和追踪编号。不要因为这类网关错误反复更换 API Key。
Codex、Claude Code 等客户端如何排查？
- 核对客户端使用的接口协议、服务地址、API Key 和当前分组支持的模型。
- Codex 直连用户检查
config.toml和auth.json的目录、文件名和格式；更改后重启 Codex。 - 通过 CCSwitch 接入时，按本站 导入说明确认灵集 AI 配置已启用，连接方式以 CCSwitch 当前展示的配置为准。
- 检查是否使用不稳定代理、是否发送超大上下文、是否连续快速重试。
- Claude Code 用户可先执行
claude --version和claude doctor，安装问题参考本站 Claude CLI 安装教程。
联系本站售后时，需要提供哪些信息？
请通过 本站售后QQ群 8210978反馈，并提供：
- 已隐藏敏感信息的报错截图或完整错误文字。
request_id或报错页面中的追踪编号（如果有）。- 使用的模型 ID、客户端名称与版本。
- 出错的大概时间和时区，以及是否每次都能复现。
- 是否使用代理，以及小请求是否也失败。
不要发送完整 API Key、Token、账号密码或敏感配置文件。
售后服务
安装、配置或使用遇到问题时，请加入 QQ 交流群获取支持。
QQ群：8210978