#Codex 接入万模API

适用协议：OpenAI Responses | 适合：代码代理、仓库修改、代码审查和自动化开发任务

Codex 是可以在本地读取项目、执行命令、修改文件的编码代理，不是普通聊天客户端。它更依赖 Responses API 的输入/输出结构、工具调用和流式事件。如果把 Codex 配成普通 Chat Completions，常见结果是认证通过但任务跑不起来。

这篇教程按“小白第一次安装”的顺序写：先准备系统工具，再安装 Codex，再把模型请求指向万模API。

#你最终要填什么

#安装路线

如果你还不会打开终端，先看：本地环境准备。

#第一步：创建 Codex 专用令牌

建议给 Codex 单独创建一个令牌，例如 codex-dev。

这样做有三个好处：

• 可以单独查看 Codex 的调用日志和消耗。
• 出现异常消耗时可以只停用这个令牌。
• 后续可以给编码工具配置独立分组和额度。

#第二步：准备系统工具

Codex 本体可以通过官方安装器安装；Node.js / npm 不是 Codex 唯一安装方式，但它们是前端项目和很多仓库任务的常用工具。建议一起准备好。

#Windows PowerShell

安装 Git 和 Node.js LTS：

winget install --id Git.Git
winget install --id OpenJS.NodeJS.LTS

可选安装 Python：

winget install --id Python.Python.3

安装完成后重新打开 PowerShell：

git --version
node -v
npm -v
python --version

#macOS

如果你会用 Homebrew：

brew install git node python

如果没有 Homebrew，直接从 Node.js 官网下载安装 LTS 版本即可。安装后验证：

git --version
node -v
npm -v
python3 --version

#Linux

Ubuntu / Debian：

sudo apt update
sudo apt install -y curl git nodejs npm python3

Fedora：

sudo dnf install -y curl git nodejs npm python3

验证：

git --version
node -v
npm -v
python3 --version

#第三步：安装 Codex

#Windows App

如果你希望用图形界面管理项目，可以安装 Codex Windows App。命令行安装方式：

winget install Codex -s msstore

安装后从开始菜单打开 Codex，登录后添加项目。

#Windows WSL2

如果你的项目放在 WSL 或你更熟悉 Linux 命令，先在管理员 PowerShell 安装 WSL：

wsl --install
wsl

进入 WSL 后安装 Codex CLI：

curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex

#macOS / Linux CLI

在终端中执行：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

安装完成后验证：

codex --version

#npm 路线怎么处理

很多用户会先想到“安装 Node/npm，再 npm 安装 Codex”。这条路线的前提是：你能确认当前官方发布的 npm 包名、版本和适用平台。当前官方 Codex 手册明确给出的稳定安装方式是上面的独立安装器、Windows App、WinGet 和 WSL 安装脚本；Node/npm 更适合作为项目开发依赖和其他 CLI 工具的前置环境。

如果你的团队已经确认使用官方 npm 包，可以按这个顺序操作：

node -v
npm -v
npm view @openai/codex version
npm install -g @openai/codex
codex --version

如果 npm view @openai/codex version 查询不到包、网络失败或包名不一致，请不要继续全局安装，改用官方安装器：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

#第四步：设置 WANMO_API_KEY

#Windows PowerShell

当前窗口临时生效：

$env:WANMO_API_KEY="sk-..."

长期保存到当前用户：

[Environment]::SetEnvironmentVariable("WANMO_API_KEY", "sk-...", "User")

重新打开 PowerShell 后验证：

echo $env:WANMO_API_KEY

#macOS / Linux / WSL

当前终端临时生效：

export WANMO_API_KEY="sk-..."

长期保存到 zsh：

echo 'export WANMO_API_KEY="sk-..."' >> ~/.zshrc
source ~/.zshrc

如果你使用 Bash：

echo 'export WANMO_API_KEY="sk-..."' >> ~/.bashrc
source ~/.bashrc

#第五步：选择配置方式

Codex 有两种配置方式：

如果你已经安装了 CCSwitch，建议优先走自动配置；它会帮你写入用户级 provider 配置，减少路径、协议和模型名填错的概率。详细安装和截图见：CCSwitch 接入万模API。

#方式一：用 CCSwitch 自动配置 Codex

1. 打开 CCSwitch。
2. 在 API Key 列表中选择刚创建的 Codex 专用令牌。
3. 添加 provider 时选择 Codex。
4. Base URL 填 https://www.wanmoapi.com/v1。
5. 模型选择控制台可用的 Responses 模型，例如 gpt-5.4-mini。
6. 保存后在 CCSwitch 面板中把该 provider 切换为使用中。

完成后重新打开终端，再运行：

codex

如果你走 CCSwitch 方式，仍然建议保留 WANMO_API_KEY 环境变量，方便终端里直接验证 Key，也方便排查 Codex 是否读取到了正确令牌。

#方式二：手动填写 Codex 配置

打开或创建用户级配置文件：

macOS / Linux / WSL 可以这样打开：

mkdir -p ~/.codex
nano ~/.codex/config.toml

Windows PowerShell 可以这样打开：

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex"
notepad "$env:USERPROFILE\.codex\config.toml"

写入下面配置，把 gpt-5.4-mini 换成你控制台可用的模型名：

model = "gpt-5.4-mini"
model_provider = "wanmoapi"

[model_providers.wanmoapi]
name = "WanmoAPI"
base_url = "https://www.wanmoapi.com/v1"
wire_api = "responses"
env_key = "WANMO_API_KEY"

配置里只写 provider、模型和 env_key。真实 API Key 放进 WANMO_API_KEY 环境变量，不要写入 config.toml。

字段含义：

#第六步：选择模型

编码代理建议优先选择：

• 支持长上下文的模型，用于读取多文件。
• 支持工具调用或函数调用的模型，用于执行编辑任务。
• 响应稳定、延迟可控的模型，用于长时间任务。

如果模型不存在，先在控制台或 /v1/models 确认模型名，再检查令牌分组是否有权限。

#第七步：只读验证

先不要让 Codex 直接改代码。进入一个测试项目目录，运行：

codex

然后输入只读任务：

列出当前项目主要目录，并用中文说明每个目录的用途。不要修改文件。

成功标志：

• Codex 能读取项目上下文。
• 能连续返回结果。
• 控制台调用日志能看到对应请求。
• 没有出现 401、404 model not found、协议不支持等错误。

验证通过后，再尝试小范围编辑任务，例如：

给 README 增加一段“本地启动方式”，修改前先说明你准备改哪个文件。

#可选：单次运行指定配置

如果你不想长期修改默认配置，可以用一次性参数测试：

codex \
  --config model='"gpt-5.4-mini"' \
  --config model_provider='"wanmoapi"'

前提是 ~/.codex/config.toml 已经定义了 [model_providers.wanmoapi]。

#常见问题

#codex 命令找不到

常见原因：

• 安装后没有重新打开终端。
• Codex 安装目录没有加入 PATH。
• Windows 用户在 PowerShell、WSL、Git Bash 之间混用了环境。

处理方式：

1. 关闭并重新打开终端。
2. 执行 codex --version。
3. 如果使用 WSL，请在 WSL 里重新安装并运行 Codex，不要在 Windows PowerShell 和 WSL 里交叉复用路径。

#node 或 npm 找不到

Node/npm 不是配置万模API的必需项，但很多项目任务会用到它。按本地环境准备安装 Node.js LTS，安装后重新打开终端。

如果你准备走 npm 安装 Codex 的路线，先执行 npm view @openai/codex version 确认包存在，再执行全局安装。查询失败时不要猜包名，优先使用官方安装器。

#PowerShell 提示 npm.ps1 被禁用

执行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

然后重新打开 PowerShell。

#认证失败或 401

常见原因：

• Key 少复制字符。
• 环境变量名和配置里的 env_key 不一致。
• 终端没有重新加载环境变量。
• 把 WANMO_API_KEY 写在了另一个终端环境里，例如 WSL 和 PowerShell 不共享变量。

处理方式：

1. 重新复制控制台令牌。
2. macOS / Linux 执行 echo $WANMO_API_KEY；Windows PowerShell 执行 echo $env:WANMO_API_KEY。
3. 用在线调试台验证同一个 Key。

#404 model not found

常见原因：

• 模型名拼写错误。
• 令牌所在分组无权访问该模型。
• 当前模型不支持 Responses 协议或工具调用。

处理方式：

1. 在控制台确认模型名。
2. 更换一个已知可用模型测试。
3. 检查令牌分组。
4. 确认配置里 wire_api = "responses"。

#Codex 能启动但任务中途失败

常见原因：

• 模型上下文不够。
• 工具调用不兼容。
• 客户端超时或网络中断。
• Codex 需要运行项目命令，但本机缺少 Node、Python、Go 等工具。

处理方式：

• 先降低任务范围，让 Codex 只读一个目录。
• 使用更稳定或更长上下文的模型。
• 查看控制台调用日志里的原始错误。
• 按项目 README 安装依赖后再试。

#只支持 Chat 的网关能不能跑 Codex？

不建议。Codex 推荐 Responses API，并且官方 Codex 文档已经标注 Chat Completions 支持处于弃用方向。即使某些版本能通过兼容层发起请求，也容易在工具调用、流式事件或多轮状态上出问题。

#下一步

• 还没跑通 Key：回到三件套与第一个请求。
• 想理解 Responses 和 Chat 的区别：看协议选择指南。
• 请求失败：看常见问题排查。