YIXO CODEX GUIDE

从安装到验证，开始使用 Codex

按顺序完成账号、密钥、环境、CCSwitch 和 Codex 配置。壹象 AI 接口地址：https://api.yixo.com/v1。

安全提示：API 密钥相当于账户凭证。不要写入公开仓库、截图或前端代码；如怀疑泄露，请立即在控制台删除旧密钥并创建新密钥。

约 10 分钟新用户完成安装和基础配置

准备内容可用网络、Node.js、壹象 AI 账号

1. 在壹象 AI 创建 API 密钥

打开 api.yixo.com，注册或登录账号。
进入控制台的“API 密钥”页面，点击创建密钥。
选择适合当前用途的分组或模型权限，创建后立即复制并妥善保存。
为不同设备或项目单独创建密钥，方便后续停用和排查。

Base URL: https://api.yixo.com/v1
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。

提示：“导入到 CCS”会自动带入该密钥对应的服务配置。请勿再在 CCSwitch 中手动重复创建同一提供商，也不要将真实 API Key 复制到截图或公开仓库。

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://api.yixo.com/v1"
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`

通过 CCSwitch：完成“导入到 CCS”后，无需使用本节的直连配置。请在 CCSwitch 中使用已导入的配置，并以其界面生成或展示的 Codex 连接方式为准。

5. 验证配置

先用与 Codex 相同的 Responses 接口确认密钥、网络和模型可用，再启动 Codex。以下命令仅用于直连壹象 AI；使用 CCSwitch 时，请按“导入到 CCS”完成后的 CCSwitch 连接方式进行测试。

Windows PowerShell

curl.exe "https://api.yixo.com/v1/responses" `
  -H "Content-Type: application/json" `
  -H "Authorization: Bearer YOUR_API_KEY" `
  -d '{"model":"YOUR_MODEL_ID","input":"你好，请返回一条测试消息"}'

macOS 终端

curl https://api.yixo.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"model":"YOUR_MODEL_ID","input":"你好，请返回一条测试消息"}'

返回正常 JSON：说明密钥、网络和 Base URL 已连通。
随后在项目目录执行 codex。
输入一个简单请求，例如“说明当前目录中的文件”，确认 Codex 能正常响应。

常见问题

现象	优先检查
401 未授权	API Key 是否完整、是否已被删除；确认请求头为 `Bearer YOUR_API_KEY`。
402 或额度不足	登录壹象 AI 控制台查看账号额度、分组权限或服务状态。
404 / 模型不可用	确认 Base URL 是 `https://api.yixo.com/v1`，并使用控制台显示的模型 ID。
429 限流	降低并发或稍后重试。
Codex 无法读取配置	确认文件名、目录和 JSON/TOML 格式正确；修改后重新启动终端和 Codex。

售后服务

安装、配置或使用遇到问题时，请加入 QQ 交流群获取支持。

QQ群：261097

壹象 AI Codex 使用指南 · 接口地址：https://api.yixo.com/v1