Codex 配置教程

Codex 是 AI 编程助手，支持接入云枢科技AI 平台的国产大模型。创建 API Key 后即可在 Codex 中导入模型；令牌未限制模型权限时，模型目录中的全部模型（DeepSeek、通义千问、智谱 GLM、Kimi、MiniMax 等）都可以直接导入使用。本页介绍完整接入步骤，推荐使用一键配置。

⚠️ 数据迁移提醒：如果你之前在使用其他平台或其他中转站，切换前请先让原平台的 AI 把项目文件完整打包、整理清楚，确保新的 AI 拿到项目后能直接读懂、马上上手，再开始配置。一键脚本会自动把原有配置备份到 backup-yunshukjai 目录，需要还原时从该目录恢复即可。

先判断你是哪种情况

打开 PowerShell，执行：

Get-Content "$env:USERPROFILE\.codex\config.toml" | Select-String -Pattern "model_provider|base_url"

显示结果	你是哪种情况	怎么做
提示找不到文件 / 没有任何输出	全新电脑	从「一、创建 API Key」开始按顺序操作
显示官方地址（api.deepseek.com / api.openai.com / model_provider = "deepseek" 等）	原来配的是官方 DeepSeek / OpenAI	先创建 API Key，再看「三、一键配置（三）从官方迁移」
显示其他名字、其他网址	原来配的是其他中转	先创建 API Key，再看「三、一键配置（四）从其他中转迁移」
model_provider = "yunshukjai"	已经配好云枢	直接去「四、验证」确认即可

一、创建 API Key

1. 登录云枢科技AI 后台，点击「API 密钥」→「创建 API 密钥」；
2. 填写名称、分组、过期时间，并按需勾选模型权限（不限制时全部模型均可导入）；
3. 点击「保存更改」，复制以 sk- 开头的 API Key。

API Key 只在创建时显示一次，请立即保存。配置脚本只把 Key 写入本机，不会上传到任何服务器。

二、安装 Codex（命令行 / 客户端 二选一）

提示：命令行版与客户端版功能一致，任选一种安装即可。客户端版不会提供 codex 命令行命令，安装后请按对应分支的说明进行验证。

（一）方式一：命令行安装

1. 安装 Node.js LTS 版本（前往 nodejs.org 下载），安装完成后重新打开终端，执行以下命令验证安装：

   node -v

   能显示版本号（如 v20.x）即安装成功；

2. 执行以下命令安装：

   npm install -g @openai/codex

   ⚠️ 如果提示「无法加载文件 npm.ps1，因为在此系统上禁止运行脚本」，请先以管理员身份运行 PowerShell（右键 PowerShell 图标，选择「以管理员身份运行」），执行以下命令，再重新运行上面的安装命令：

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser -Force

3. 安装完成后，先运行一次 codex，首次启动会生成 %USERPROFILE%\.codex 配置目录（看到对话界面后按 Ctrl+C 退出）。此步骤必须在一键配置前完成，否则脚本会提示找不到配置目录。

4. 验证安装：

   codex --version

   能显示版本号即安装成功。

（二）方式二：客户端安装

1. 前往 Codex 官网（或微软商店）下载桌面版安装包并安装；

2. 打开一次 Codex，首次启动会自动生成 %USERPROFILE%\.codex 配置目录；

3. 完全退出桌面版（右键系统托盘中的 Codex 图标选择「退出」，而不是只关闭窗口）。

三、一键配置（推荐）

提示：如果你已打开 Codex 桌面端，请先完全退出（右键系统托盘中的 Codex 图标选择「退出」，而不是只关闭窗口），配置完成后再重新打开；否则桌面端读不到新写入的环境变量。

（一）Windows PowerShell

curl.exe -s https://www.yunshukjai.com/codex-setup.ps1 -o "$env:TEMP\codex-setup.ps1"
powershell -ExecutionPolicy Bypass -File "$env:TEMP\codex-setup.ps1"

（二）macOS / Linux

bash <(curl -fsSL https://www.yunshukjai.com/codex-setup.sh)

脚本会提示输入 API Key（如果系统已设置过 YUNSHUKJAI_API_KEY 环境变量，则直接使用），并自动完成：备份旧配置 → 写入云枢配置 → 保存环境变量 → 注册模型目录。看到 DONE! 即配置成功。

注意：请使用「下载运行」方式，不要用 irm | iex；运行后必须新开一个终端（使用客户端则需完全退出再重新打开），配置才会生效。

（三）从官方 DeepSeek / OpenAI 迁移

适用于原来配的是官方 DeepSeek 或 OpenAI 官方账号/Key 的用户。一键脚本会自动把原配置备份到 backup-yunshukjai 目录，原官方配置保留但不再使用，不用手动删除任何东西。

1. 按上面（一）（二）的一键配置命令运行脚本，按提示输入云枢 API Key，看到 DONE! 即成功；

2. 重开终端，确认环境变量生效：

   $env:YUNSHUKJAI_API_KEY.Length

   显示数字（40 以上）即正常；若无输出，执行 setx YUNSHUKJAI_API_KEY "sk-你的密钥" 后重新打开终端；

3. 验证：

   codex exec --skip-git-repo-check -m deepseek-v4-flash "你好"

   能正常回复即迁移完成。

⚠️ 原来使用 OpenAI 官方的用户注意：迁移后命令行必须带 -m deepseek-v4-flash（或改用云枢其他模型），桌面端请在模型选择器中手动选择 deepseek-v4-flash，不要再选 GPT 模型（会提示 403）。

（四）从其他中转迁移

适用于原来配的是其他中转站/平台（base_url 不是官方地址）的用户。

1. 按上面（一）（二）的一键配置命令运行脚本，按提示输入云枢 API Key，看到 DONE! 即成功；

2. 清理旧平台留下的模型列表（建议做）：完全退出 Codex 后执行：

   Remove-Item "$env:USERPROFILE\.codex\models.json"

   然后重新运行一次一键配置（会直接使用刚才保存的 Key，不用重新输入）；

3. 重开终端并验证：

   $env:YUNSHUKJAI_API_KEY.Length
   codex exec --skip-git-repo-check -m deepseek-v4-flash "你好"

   能正常回复即迁移完成。

四、验证（按安装方式选择）

（一）命令行用户

新开一个终端，确认环境变量已生效：

$env:YUNSHUKJAI_API_KEY.Length

输出为 40 以上的数字即正常；若无输出，请执行以下命令（sk-你的密钥 换成你的 Key）后重新打开终端：

setx YUNSHUKJAI_API_KEY "sk-你的密钥"

命令行用户还可以用下面的命令自测模型调用（客户端用户无需执行，直接看（二））。新终端里执行：

(Get-Content "$env:USERPROFILE\.codex\models.json" -Raw | ConvertFrom-Json).models.slug

显示 deepseek-v4-flash 就对了。再执行：

codex exec --skip-git-repo-check -m deepseek-v4-flash "你好"

能正常回复即配置成功；若提示 codex 无法识别，说明未安装命令行版或没有新开终端，请检查「二、安装 Codex」方式一的步骤。

（二）客户端用户

1. 完全退出桌面版（右键系统托盘图标选择「退出」），再重新打开，在引导界面点击「Skip」进入主界面：

   

2. 在 Codex 主界面点击模型选择器（如图中箭头所指的位置），选择 deepseek-v4-flash：

   

3. 发送「你好，介绍一下自己」，能正常回复即配置成功。

五、可用模型

在 Codex 主界面点击模型选择器，即可看到全部可用模型，按需切换：

deepseek-v4-flash、deepseek-v4-pro、glm-5.2、kimi-k3、MiniMax-M3、qwen3.7-flash、qwen3.7-max、qwen3.7-plus、qwen3.8-max

提示：命令行用户可通过 codex exec -m 模型ID "任务" 临时指定模型；模型 ID 以平台 /v1/models 实际返回为准。

六、常见问题

现象	解决办法
401 Invalid token	API Key 复制错、已删除或环境变量未更新 → 后台重新创建，重跑一键脚本，新开终端
403 no access to model	令牌未勾选对应模型权限 → 后台勾选或新建令牌
404 Model Not Exist	模型 ID 不正确 → 通过 /v1/models 查询准确 ID 后原样填写
提示 codex 无法识别 / CommandNotFoundException	客户端用户属正常现象：客户端版不提供命令行命令，按「四、验证（二）客户端用户」在界面验证即可；若需使用命令行，执行 npm install -g @openai/codex 后新开 PowerShell 再试
提示 npm.ps1 禁止运行脚本	PowerShell 执行策略默认禁止脚本 → 执行 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser -Force 后重新安装
Missing environment variable	执行 setx YUNSHUKJAI_API_KEY "sk-..." 后完全退出客户端（含托盘）重新打开
客户端不显示模型	完全退出后重新打开；确认已运行一键配置并注册模型目录
提示还在用 GPT 模型 / 用错模型	会话仍在使用内置模型 → 命令行加 -m deepseek-v4-flash；桌面端在模型选择器中手动选择模型
PowerShell 里 curl -H 报参数错误	curl 是 Invoke-WebRequest 的别名 → 改用 curl.exe
curl.exe 无法识别	PATH 中没有 curl → 用 C:\Windows\System32\curl.exe 或 Invoke-RestMethod
irm | iex 结尾报空字符串	PowerShell 5.1 兼容性提示 → 配置已写入，改用「下载运行」方式
配置文件 / 脚本乱码	编码或 BOM 问题 → 配置文件保存为 UTF-8 无 BOM
models.json 里有重复的旧模型 ID	旧注册脚本只合并不清理 → 删除 %USERPROFILE%\.codex\models.json 后重新运行一键配置
想还原旧配置	恢复备份文件（*.bak-yunshukjai）

七、手动配置（备用）

一键脚本正常工作时不需要使用本节；只有脚本反复报错、实在跑不通时，才手动操作。

（一）备份

Windows PowerShell：

Copy-Item "$env:USERPROFILE\.codex\config.toml" "$env:USERPROFILE\.codex\config.toml.bak"
Copy-Item "$env:USERPROFILE\.codex\models.json" "$env:USERPROFILE\.codex\models.json.bak"

macOS / Linux：

cp ~/.codex/config.toml ~/.codex/config.toml.bak
cp ~/.codex/models.json ~/.codex/models.json.bak

（二）修改 config.toml

用记事本（Windows）或 nano（macOS / Linux）打开 %USERPROFILE%\.codex\config.toml（macOS / Linux：~/.codex/config.toml），删掉原来顶部所有 model =、model_provider = 行，改成：

model = "deepseek-v4-flash"
model_provider = "yunshukjai"
model_catalog_json = "C:/Users/<用户名>/.codex/models.json"

macOS / Linux 用户把第三行的路径改成 ~/.codex/models.json。

在文件末尾追加：

[model_providers.yunshukjai]
name = "YunShu AI"
base_url = "https://www.yunshukjai.com/v1"
wire_api = "responses"
env_key = "YUNSHUKJAI_API_KEY"
requires_openai_auth = false

（三）保存并重开终端

• 保存时编码必须为 UTF-8 无 BOM；
• 关掉所有 PowerShell 重新打开；
• 执行「四、验证」中的步骤确认。

提示：原来配置里的 [model_providers.deepseek] 等旧块，以及 DEEPSEEK_API_KEY、OPENAI_API_KEY 等旧环境变量都不用删除，放着不影响；云枢的环境变量必须叫 YUNSHUKJAI_API_KEY（注意拼写），拼错的 YUNSHUKAI_API_KEY 请删除。

相关文档

• API 密钥创建
• WorkBuddy配置
• CodeBuddy配置