Codex 保姆级教程:从安装到配国产模型,一篇搞定

Codex 保姆级教程：从安装到配国产模型，一篇搞定

Codex 是 OpenAI 出的终端 AI 编程助手，很火。

但国内用户直接装上会发现：用不了。因为 Codex 新版只认 OpenAI 的 Responses API，国产模型大多不支持。

这篇教程会把安装、配国产模型、基础用法一次性讲清楚，让你能真正用起来。

一、安装 Codex

macOS / Linux

# 官方推荐curl -fsSL https://chatgpt.com/codex/install.sh | sh# 或者 Homebrewbrew install --cask codex# 或者 npmnpm install -g @openai/codex

验证安装：

codex --version

Windows

推荐用 WSL2：

# 先装 WSL2wsl --install# 在 WSL2 里装 Codexcurl -fsSL https://chatgpt.com/codex/install.sh | sh

原生 PowerShell 也能装，但不稳定，容易出问题。

二、配置国产模型（最重要的一步）

装好 Codex，直接运行会报错——因为你没有 ChatGPT 账号。

国内用户要用 Codex，第一步就是配国产模型。

先搞清楚一个问题：Responses API vs Chat Completions API

Codex 0.8 以后，只用 OpenAI 的 Responses API（/responses 端点），不用传统的 Chat Completions API（/chat/completions）。

Responses API 是 OpenAI 给 Agent 设计的新协议，支持多轮对话接力、工具调用生命周期、reasoning 输出等。

国产模型分两类：

方案 A：火山引擎（豆包）— 直接接入

火山引擎支持 Responses API，可以直接配。

1. 获取 API Key

去火山引擎控制台：https://console.volcengine.com/ark

创建接入点，获取 API Key。

2. 配置 Codex

编辑 ~/.codex/config.toml：

model_provider = "volcengine"model = "doubao-pro-32k"[model_providers.volcengine]name = "火山引擎"base_url = "https://ark.cn-beijing.volces.com/api/v3"env_key = "VOLCENGINE_API_KEY"wire_api = "responses"

3. 设置环境变量

重要： Codex 对自定义 model_provider 不会自动读取 auth.json，必须设置环境变量。

# 临时设置（当前终端有效）export VOLCENGINE_API_KEY="你的API Key"# 永久设置（写入 ~/.zshrc 或 ~/.bashrc）echo 'export VOLCENGINE_API_KEY="你的API Key"' >> ~/.zshrcsource ~/.zshrc

4. 测试

在终端输入codex进入交互模式体验一下吧

方案 B：阿里云通义千问（qwen3.7-max / qwen3.6-plus）— 直接接入

阿里云的 qwen3.7-max 和 qwen3.6-plus 支持 Responses API。

1. 获取 API Key

去阿里云百炼控制台：https://bailian.console.aliyun.com/

创建 API Key。

2. 配置 Codex

编辑 ~/.codex/config.toml：

model_provider = "aliyun"model = "qwen3.7-max"[model_providers.aliyun]name = "阿里云百炼"base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"env_key = "DASHSCOPE_API_KEY"wire_api = "responses"

3. 设置环境变量

# 临时设置export DASHSCOPE_API_KEY="你的API Key"# 永久设置echo 'export DASHSCOPE_API_KEY="你的API Key"' >> ~/.zshrcsource ~/.zshrc

方案 C：其他国产模型（DeepSeek、GLM、Kimi 等）— 需要中转站

这些模型只支持 Chat Completions API，必须用中转站把 Responses 请求翻译成 Chat Completions。

常用中转站：

工具	链接	说明
CLIProxyAPI	https://kelen.cc/posts/cliproxyapi-guide	专为 Codex 接国产模型设计，有图形界面
codex-bridge	https://github.com/wujfeng712-ui/codex-bridge	命令行工具，支持 DeepSeek、MiMo

用 CLIProxyAPI

1. 下载并运行

去官网下载 CLIProxyAPI，运行后会在本地开一个端口（默认 8317）。

2. 在前端页面配置

打开浏览器访问 http://localhost:8317，填入你的国产模型 API Key。

3. 配置 Codex

编辑 ~/.codex/config.toml：

model_provider = "proxy"model = "deepseek-chat"[model_providers.proxy]name = "中转站"base_url = "http://localhost:8317/v1"wire_api = "responses"requires_openai_auth = true

4. 设置 Codex 的认证

# 必须设置环境变量（auth.json 不生效）export OPENAI_API_KEY="sk-proxy"# 或永久设置echo 'export OPENAI_API_KEY="sk-proxy"' >> ~/.zshrcsource ~/.zshrc

中转站会自动把 Codex 的 /responses 请求翻译成 /chat/completions，发给国产模型。

用 codex-bridge

1. 下载

git clone https://github.com/wujfeng712-ui/codex-bridge.gitcd codex-bridge

2. 配置环境变量

创建 .env 文件：

PROXY_AUTH_KEY=sk-proxy-local-testDEEPSEEK_API_KEY=你的DeepSeek密钥DEEPSEEK_BASE_URL=https://api.deepseek.com/v1DEFAULT_PROVIDER=deepseek

3. 启动中转站

node --env-file=.env proxy.mjs

4. 配置 Codex

编辑 ~/.codex/config.toml：

model = "deepseek-v4-flash"model_provider = "bridge"[model_providers.bridge]name = "codex-bridge"base_url = "http://127.0.0.1:4000/v1"wire_api = "responses"requires_openai_auth = true

# 设置环境变量（与 .env 中的 PROXY_AUTH_KEY 一致）export OPENAI_API_KEY="sk-proxy-local-test"

多模型切换

如果你有好几个模型想换着用，用 profiles 配置：

[profiles.doubao]model_provider = "volcengine"model = "doubao-pro-32k"[profiles.deepseek]model_provider = "proxy"model = "deepseek-chat"[profiles.glm]model_provider = "proxy"model = "glm-4.7"[model_providers.volcengine]name = "火山引擎"base_url = "https://ark.cn-beijing.volces.com/api/v3"env_key = "VOLCENGINE_API_KEY"wire_api = "responses"[model_providers.proxy]name = "中转站"base_url = "http://localhost:8317/v1"wire_api = "responses"requires_openai_auth = true

启动时指定：

codex --profile doubaocodex --profile deepseekcodex --profile glm

配置成功的标志

运行 codex exec "回复 OK"，看到类似这样的输出就说明配对了：

OpenAI Codex v0.134.0--------workdir: /Users/xxx/projectmodel: qwen3.7-maxprovider: aliyun--------user回复 OKcodexOK

如果报错 Missing environment variable 或 stream disconnected before completion，说明配置有问题：

检查环境变量是否设置（echo $OPENAI_API_KEY 或对应变量）
检查 API Key 是否正确
检查 base_url 是否正确
如果用中转站，确认中转站在运行

三、基础操作

启动

cd 你的项目目录codex

进入交互界面，打字跟它说话，告诉它你的需求是什么，你希望它帮你做什么。

权限模式

Codex 能改代码、跑命令。有三档权限：

模式	命令	说明
Suggest	`--approval-mode suggest`	只能看，不能改，最安全
Auto-edit	`--approval-mode auto-edit`	改文件自动，跑命令要确认，推荐日常用
Full-auto	`--approval-mode full-auto`	全自动，适合长任务

新手建议先用 suggest，熟悉了再开 auto-edit。

常用命令

帮我看看这个项目的结构

这个函数为什么跑这么慢，帮我优化

把 src/utils 的测试覆盖率提到 80%

斜杠命令

输入 / 能看到所有命令：

命令	作用
`/model`	切换模型
`/permissions`	调整权限
`/clear`	清屏新对话
`/status`	会话状态
`/diff`	查看改动
`/review`	代码审查
`/goal`	长期目标（需先启用 goals）
`/plan`	计划模式

四、进阶功能：/goal 长期任务

普通对话是一问一答。但有些任务需要多轮迭代：改代码 → 跑测试 → 发现报错 → 再改 → 再跑……

/goal 让 Codex 持续朝一个目标工作，可以跑几个小时。

启用

codex features enable goals

重启 Codex，/goal 命令就出现了。

用法

设置目标：

/goal 把用户认证模块重构为 JWT，所有认证测试通过才算完成

查看：/goal

暂停：/goal pause

继续：/goal resume

写好 goal 的要点

好的 goal 要包含：目标、范围、验证方式、停止条件。

/goal 修复 issue #123，checkout 时接受过期卡片Scope: 只改 payment 相关代码Verification: npm test -- checkoutStop rule: 支付网关行为无文档说明时停止

五、进阶功能：Computer Use（Mac 专属，桌面端，不是cli）

如果你用 Codex Desktop App，还有 Computer Use 功能——让 Codex 像人一样操作你的 Mac。

启用

Settings → Computer Use → Install
授权 macOS 权限：Screen Recording、Accessibility

用法

提示词前加 @Computer：

@Computer 打开 Chrome，去 localhost:3000，测试登录流程

Appshots

Mac 上按两个 Command 键，截取当前窗口发给 Codex。

六、配置文件

config.toml

全局配置在 ~/.codex/config.toml：

[defaults]model = "qwen3.7-max"approval_mode = "auto-edit"[features]goals = true

auth.json

对于自定义 model_provider，Codex 不读取 auth.json，必须用环境变量。

只有使用 OpenAI 官方账号时，auth.json 才生效：

{  "OPENAI_API_KEY": "你的OpenAI Key"}

instructions.md

全局指令 ~/.codex/instructions.md，给 Codex 的"规矩"：

写代码前先跑测试确认能跑用 TypeScript测试覆盖率至少 70%

CODEX.md

项目级指令，放项目根目录：

所有 React 组件在 src/components/API 用 RESTful

七、实战案例

从零建项目

mkdir my-apicd my-apicodex

帮我从零开始写一个 Express + TypeScript 的 REST API：- 用户注册登录- JWT 认证- PostgreSQL 连接- 测试框架

Codex 会自动创建项目结构、写代码、装依赖、跑测试。

重构遗留代码

用 /goal 跑长期任务：

/goal 把 src/auth 的认证逻辑重构为 JWTScope: 只改 src/authVerification: npm test 全部通过Stop rule: 遇到无文档的老代码就暂停

八、常见问题

`stream disconnected before completion`

原因：API 不支持 Responses API，或配置错误。

解决： - 确认你的模型在"支持 Responses API"列表里 - 不支持的模型要用中转站

`403 Forbidden` / `not found`

原因：请求到了 /responses 端点，但 API 只有 /chat/completions。

解决：用中转站。

`wire_api = chat is no longer supported`

原因：Codex 新版本不支持 Chat Completions 配置。

解决：必须用 wire_api = "responses"，不支持的模型走中转站。

登录失败

如果你用 codex login 登录 ChatGPT 账号失败——正常，国内网络问题。

搞不定网络问题的话，咱就直接用国产模型，不用 ChatGPT 账号。

MCP 连不上

codex mcp  # 检查配置

重启 Codex。

九、Mac vs Windows

功能	Mac	Windows
Computer Use	有	没有
手机远程连接	有	没有
Appshots	有	没有

这些功能目前只有 Mac 能用。

有问题评论区聊。

参考资源：

Codex 官方文档：https://developers.openai.com/codex
阿里云 Codex 接入文档：https://help.aliyun.com/zh/model-studio/codex
CLIProxyAPI：https://kelen.cc/posts/cliproxyapi-guide
codex-bridge：https://github.com/wujfeng712-ui/codex-bridge

Codex 保姆级教程：从安装到配国产模型，一篇搞定

一、安装 Codex

macOS / Linux

Windows

二、配置国产模型（最重要的一步）

先搞清楚一个问题：Responses API vs Chat Completions API

方案 A：火山引擎（豆包）— 直接接入

方案 B：阿里云通义千问（qwen3.7-max / qwen3.6-plus）— 直接接入

方案 C：其他国产模型（DeepSeek、GLM、Kimi 等）— 需要中转站

用 CLIProxyAPI

用 codex-bridge

多模型切换

配置成功的标志

三、基础操作

启动

权限模式

常用命令

斜杠命令

四、进阶功能：/goal 长期任务

启用

用法

写好 goal 的要点

五、进阶功能：Computer Use（Mac 专属，桌面端，不是cli）

启用

用法

Appshots

六、配置文件

config.toml

auth.json

instructions.md

CODEX.md

七、实战案例

从零建项目

重构遗留代码

八、常见问题

stream disconnected before completion

403 Forbidden / not found

wire_api = chat is no longer supported

登录失败

MCP 连不上

九、Mac vs Windows

相关学习资料

`stream disconnected before completion`

`403 Forbidden` / `not found`

`wire_api = chat is no longer supported`