Codex CLI 手动配置

大约 6 分钟

Codex CLI 手动配置

接入结论

接口地址（base_url）：https://www.yuzhixiaolongxia.com/v1（带 /v1）
认证字段：OPENAI_API_KEY（写入 auth.json）
令牌分组：Codex 家族令牌分组
推荐模型 ID：gpt-5.5（最新）
模型 ID 查询：模型广场

这篇文档适合谁

适合：会基础命令行、想用 AI 写代码 / 修 bug / 解释代码的开发者
不适合：完全不会终端的小白——走一键安装包

Codex CLI 适合做什么

终端里直接跟 AI 对话，写代码、改代码、解释代码
跟 Claude Code 对比：模型不同，风格不同，可以同时装两个互相补足

前置条件

请先完成环境检查。Node.js ≥ 20 是硬性要求。

极简步骤一览

装好 Codex CLI（一行 npm install）
在 ~/.codex/ 下建 config.toml，粘贴模板
在同目录建 auth.json，填进你的令牌
重开终端，跑 codex 验证

下面是每一步的详细操作。

第一步：安装 Codex CLI

打开终端（Windows 用「命令提示符」或「PowerShell」，Mac 用「终端」），输入：

npm install -g @openai/codex

没有 npm？

说明你还没装 Node.js。先去 https://nodejs.org 下载 LTS 版本，装完再回来。

装完之后验证：

codex --version

显示了版本号，说明装好了。如果提示"命令不存在"，看文末的常见错误。

第二步：找到配置目录（没有就自己建）

Codex CLI 的配置文件放在用户主目录下的 .codex 文件夹里。

Windows

按 Win + R，输入 %USERPROFILE%，回车，打开用户目录（比如 C:\Users\张三）。

.codex 是隐藏文件夹

资源管理器里默认看不到。要先「查看」→ 勾选「隐藏的项目」才能看见。

在这个目录里找 .codex 文件夹。没有的话就新建一个（文件夹名 .codex，前面有个点）。

完整路径长这样：

C:\Users\你的用户名\.codex\

@tab Mac / Linux

打开终端，输入：

mkdir -p ~/.codex

已经存在也没关系，不会报错。

:::

第三步：创建 config.toml 文件

在 .codex 目录里新建一个文件，文件名叫 config.toml。

Windows 用户注意

记事本新建文件时，文件名写 config.toml，文件类型选「所有文件」。不然它会自动加 .txt 变成 config.toml.txt，就白搭了。

推荐用 VS Code

打开 VS Code
菜单「文件」→「打开文件夹」，选中 .codex 文件夹
左侧点「新建文件」图标，文件名输入 config.toml，回车

Mac / Linux 直接跑：

touch ~/.codex/config.toml

第四步：把配置内容粘进去

打开 config.toml，把下面这段 完整复制粘贴进去：

disable_response_storage = true
model_provider = "yuzhi"
model = "gpt-5.5"
model_reasoning_effort = "high"
model_verbosity = "high"

[features]
web_search_request = true

[model_providers.yuzhi]
name = "yuzhi"
base_url = "https://www.yuzhixiaolongxia.com/v1"
wire_api = "responses"
requires_openai_auth = true

粘进去之后保存（Ctrl + S 或 Cmd + S）。

重点：接口地址必须带 /v1

Codex CLI 的 base_url 必须以 /v1 结尾：https://www.yuzhixiaolongxia.com/v1。这是 Codex 与 Claude Code 最大的差异——少了 /v1 会直接找不到接口。

每个字段是什么意思

字段	含义
`disable_response_storage`	不让 Codex 在本地存聊天记录，设 `true` 更省事
`model_provider`	告诉 Codex 用平台（名字叫 `yuzhi`），不走默认渠道
`model`	用哪个模型，推荐 `gpt-5.5`
`model_reasoning_effort`	思考力度，`high` 就是多想一想
`model_verbosity`	回答详细程度，`high` 就是说清楚一点
`web_search_request`	允许联网搜索
`base_url`	平台的接口地址，必须带 /v1，别改
`wire_api`	协议模式，固定写 `responses`
`requires_openai_auth`	告诉 Codex 用 API Key 验证，必须 `true`

模型 ID 写错了？

平台支持 模型 ID 智能归一化，常见笔误也能识别。完整可用模型 ID 见模型广场。

第五步：创建 auth.json，填入你的令牌

在同一个 .codex 目录下，再新建一个文件，名字叫 auth.json。

Windows 用户

存文件时要选「所有文件」，别让它变成 auth.json.txt。

文件内容如下，把 你的Codex令牌填这里 替换成你的真实令牌：

{
  "OPENAI_API_KEY": "你的Codex令牌填这里"
}

令牌在哪里找？

新用户不用自己创建

平台为新用户预设了 Codex 家族令牌分组，登录后到令牌页面直接复制就行。

需要自定义的话，参考：创建令牌教程

必须选对分组

Codex CLI 只能用 "Codex 家族令牌分组" 的令牌。Claude / Gemini 分组的令牌在这里用不了，会直接 401。

令牌一般长这样：sk-xxxxxxxxxxxxxxxxxxxxxxxx。复制时别带多余空格。

保存文件。

第六步：重新打开终端，测试一下

必须重开终端

关掉当前的终端窗口，重新打开一个新的。配置文件是启动时读取的，不重开就不生效。

重开之后输入：

codex

如果看到 Codex 的交互界面出来了，配置成功。

成功是什么样子

启动后终端会显示一个交互式界面，类似这样：

Codex  gpt-5.5  yuzhi
>

在 > 后面输入问题，比如"帮我写一个 Python 的 Hello World"，它就会回答。

失败是什么样子 & 怎么解决

提示 `invalid_api_key` 或 `Unauthorized`

令牌填错了，或令牌复制时多了空格。重新检查 auth.json 里的令牌：

没有多余空格
没有多余引号（只有 JSON 语法要求的那对双引号）
令牌本身完整
确认是 Codex 家族令牌分组 创建的令牌

提示 `model not found` 或 `model does not exist`

config.toml 里的 model 字段写错了。检查是不是手抄出错，直接对照上面的内容重新复制粘贴，或去模型广场复制最新模型 ID。

提示 `404` 或接口找不到

最大概率是 base_url 少了 /v1。检查 config.toml：

base_url = "https://www.yuzhixiaolongxia.com/v1"

末尾的 /v1 不能省略。

提示 `codex: command not found` 或 `'codex' 不是内部或外部命令`

两种情况：

没装成功：重新跑 npm install -g @openai/codex，看有没有报错
PATH 没加：npm 全局安装目录没在系统 PATH 里。Windows 装好后可以看终端提示有没有 added to PATH 说明，或者 重启电脑 再试

改完配置但没生效

完全关掉所有终端（包括标签页），重新开一个新的。

常见坑速查（base URL / 模型 ID / 分组）

坑	现象	解决
`base_url` 少了 `/v1`	404 / 接口找不到	必须是 `.../v1`，末尾不能丢
令牌选错分组	401 Unauthorized	必须用 Codex 家族令牌分组
Windows 文件名变成 `.txt`	配置不读取	存文件选"所有文件"类型
改完没重开终端	配置不生效	完全关掉终端，重新打开
令牌带了空格 / 引号	401	清理多余字符，只保留令牌本体
模型 ID 拼错	model not found	去模型广场直接复制

配置完成

Codex CLI 配置完毕。可以用 codex 命令启动，跟 AI 一起写代码。

上一步：Claude Code 手动配置｜下一步：Gemini CLI 手动配置