余岂 AI 中转服务 Logo

余岂 AI 中转服务

Codex 使用说明

返回首页 进入后台
Codex Guide

不是只告诉你能不能用，而是让你第一次就能把 Codex 跑通。

这页按真正使用顺序来写：先准备 Node.js 和终端，再配置 API Key 与 Base URL，再跑一次最小测试， 最后再看常见报错怎么排。你不需要先懂很多原理，按步骤做就行。

注册领取测试额度 查看 OpenAI 官方 Codex 文档
适合代码阅读 / 改代码 / 排错 / 自动化开发 推荐先做短测，不建议直接压大项目 你的 Base URL：`https://api.yuqitoken.cn/v1`
先看全流程

第一次接入，建议按这个顺序走。

先把基础环境和配置跑顺，再去测模型和成本，效率最高。

1. 先准备环境

Node.js、终端、Git、代码编辑器先装好。没有这些，后面再多 key 也跑不起来。

2. 再拿你的站内 key

登录后台，创建你自己的 API key，不要把别人发给你的 key 混着用。

3. 配置 Codex

把环境变量和 `config.toml` 写好，重点是 `Base URL`、模型名、provider。

4. 做最小测试

先只读目录、先短请求、先看能不能返回，再决定要不要长时间使用。

Codex 是什么

它更像一个能进终端、会改代码、会执行任务的编码助手。

如果你只是偶尔问一句普通聊天问题，Codex 的优势不明显。它更适合读项目、改文件、执行命令、定位报错、 拆解开发任务、做连续的工程操作。你可以把它理解成“更偏工程执行”的智能编码能力，而不是普通对话机器人。

适合的场景

  • 读代码、找 bug、做小范围重构。
  • 跑脚本、查日志、核对接口返回。
  • 搭环境、改配置、整理工程说明。

不适合的预期

  • 不建议一上来就让它无约束地大改整站。
  • 不建议没备份就直接让它动生产配置。
  • 不建议完全不测试就把结果当成定稿。

第一次的正确打法

  • 先小任务测试。
  • 先只读理解，再开始改动。
  • 先验证结果，再逐步放大范围。
使用前准备

这几样没准备好，后面基本都会卡。

下面这套是偏稳的准备清单，适合第一次接 Codex 的用户。

基础软件

  • Node.js：建议用较新的 LTS 版本。OpenAI 官方 Windows/WSL 示例使用 Node 22。
  • Git：建议安装，后面做版本记录、代码 review、回滚都会更顺。
  • 终端：Windows Terminal / PowerShell / WSL 都可以。
  • 编辑器：VS Code、Cursor、Windsurf 都行，先保证能打开本地项目。

账号与 key

  • 先注册并登录你的站内账号。
  • 在后台创建你自己的 API key。
  • 复制后先保存好，丢了就重新生成，不建议到处转发。
  • 第一次测试建议单独新建一个测试 key，方便排错和核算消耗。

先记住这两个配置

Base URL: https://api.yuqitoken.cn/v1
模型名: 以后台实际开放模型名为准

如果客户端要填接口地址，最容易错的就是忘了加 `/v1`。

先选哪种运行方式

  • 原生 Windows：上手快，适合大多数人。
  • WSL2：适合你本身就跑 Linux 开发流，或者仓库放在 WSL 里。
  • 官方建议：Windows 原生默认更快；需要 Linux 环境再切 WSL2。
安装 Codex

先把命令装好，再谈接入。

这一步只解决“本机能不能跑 Codex”这个问题，不涉及你站内 key。

Windows 原生安装

# 先确认 Node.js
node -v

# 全局安装 Codex CLI
npm install -g @openai/codex

# 看看命令是否已就绪
codex --help

如果 `node -v` 没返回版本，先装 Node.js 再继续。

WSL2 安装

# PowerShell 里先安装并进入 WSL
wsl --install
wsl

# WSL 里安装 nvm 和 Node.js
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
nvm install 22

# 安装 Codex
npm i -g @openai/codex
codex

如果你走 WSL，仓库尽量放在 `/home/...`，别长期挂在 `C:\` 目录里。

官方两种登录口径

  • 官方 OpenAI：可以直接 `codex login`，走 ChatGPT 或 OpenAI API key。
  • 接你的站：更适合用自定义 provider，不建议把它当官方 OpenAI 登录来配。
  • 如果你是在远程或无头环境里登录官方账号，可用 `codex login --device-auth`。

先确认这些命令能跑

codex --version
codex --help
codex exec --help
codex mcp --help

这些都能跑，说明本机 CLI 基本没问题，下一步再接入你的站。

接入余岂

如果你要用余岂 AI 中转服务接 Codex，推荐这样配。

这套做法的重点，是把你的站内 key 放进环境变量，再让 Codex 读取本地 `config.toml`。

步骤 1：在后台创建 key

  1. 注册并登录 `余岂 AI 中转服务` 后台。
  2. 进入令牌管理，创建一个专门给 Codex 用的 key。
  3. 确认你的账号分组能访问你要测的模型。
  4. 第一次建议只先开测试额度，先测通再长期使用。

步骤 2：设置环境变量

# 当前 PowerShell 会话临时生效
$env:YUQI_API_KEY="你的站内 key"

# 持久化到 Windows 用户环境变量
setx YUQI_API_KEY "你的站内 key"

`setx` 生效后，重开一个新终端再继续。旧终端一般读不到新值。

步骤 3：把下面这段写进 `config.toml`

Windows 一般在 `C:\Users\你的用户名\.codex\config.toml`。官方说明里，用户级配置默认就在 `~/.codex/config.toml`。

model = "gpt-5.4"
model_provider = "yuqi"

[model_providers.yuqi]
name = "余岂 AI 中转服务"
base_url = "https://api.yuqitoken.cn/v1"
wire_api = "responses"
env_key = "YUQI_API_KEY"
env_key_instructions = "请先在本机环境变量中设置 YUQI_API_KEY"
怎么理解这段配置： `model_provider` 指向你定义的 provider； `base_url` 是你的站内接口地址； `wire_api` 官方目前只支持 `responses`； `env_key` 表示让 Codex 从环境变量里取 key。

步骤 4：先跑最小测试

mkdir D:\codex-test
cd D:\codex-test

codex "先只读取当前目录，告诉我目录里有什么，不要修改任何文件。"

先只做“读取型任务”，不要一上来就让它改生产项目。

步骤 5：再进真实项目

cd D:\你的项目目录
codex "先概览这个项目的结构，告诉我入口文件、依赖和主要模块，不要动代码。"

这一步成功了，说明你的 key、Base URL、模型和基本网络都已经打通。

推荐命令

第一次最常用的命令，先记这几条就够了。

先能用，再慢慢扩展，不需要一开始就把全部命令都学完。

基础检查

codex --version
codex --help
codex login status
codex mcp list

非交互执行

codex exec "概览当前项目结构"

# 如果当前目录不是 Git 仓库
codex exec --skip-git-repo-check "只读取当前目录并总结文件结构"

代码 review

codex review

更适合已经在 Git 仓库里的代码项目。

登录相关

# 官方 OpenAI API key 登录
codex login --with-api-key

# 浏览器回调受限时
codex login --device-auth

如果你是接余岂，一般优先走上面的自定义 provider 方案。

常见报错

报错不可怕，先看是哪一层出了问题。

大多数问题都不是“不能用”，而是地址、令牌、模型名、配置文件或运行环境没对齐。

`invalid_api_key`

通常是 key 填错、复制时带了空格，或者环境变量没生效。先新开终端，再检查 `YUQI_API_KEY` 是否真的有值。

`model_not_found`

通常是模型名写错，或者当前分组没开放这个模型。以你后台实际可见模型名为准，不要自己猜。

连得上但一直报格式问题

先检查 `base_url` 是否写成了 `https://api.yuqitoken.cn/v1`。少了 `/v1`，或者地址填成网页首页，都会出问题。

`config.toml` 读不进去

通常是 TOML 语法格式错了，比如表头位置不对、引号不成对。最稳的办法是先按上面的最小配置原样抄进去，再逐步加项。

Windows 跑得慢或路径很乱

如果你长期走 Linux 工具链，可以直接切 WSL2；如果只是普通项目，官方更建议先用原生 Windows，速度和兼容性通常更直接。

测试一下就消耗很高

先用短提示词、小文件、小目录测试，不要一上来丢几十个文件。Codex 是按真实调用计费的，任务越大消耗越快。

如果你要做纯净度验证，建议固定一组短测试提示词，在不同站点分别对比返回风格、延迟、报错率和扣费体感。
最后建议

第一次先测通，不要先测猛。

最稳的打法不是一上来就让 Codex 改整站，而是先确认环境、key、Base URL、模型名都对，再从读取型任务开始。 真要长期用，建议给 Codex 单独建一个 key，单独核算消耗，也更容易排错。

登录后台创建 key 继续看常见问题解决方案