Codex中文手册
1 章 · 约 7 千字
一、Codex 适合什么样的场景？
下面的五种情况，都适合选用Codex：
1. 已经有 ChatGPT Plus/Pro 订阅 ，那就优先试 Codex。每个月交那 20 刀，终于不只是用来写周报了。
2. 想要 GUI ，不想在终端里和 AI 大眼瞪小眼，想点点鼠标把活干了
3. 被账号稳定性折腾怕了 ，多一个官方工具，就多一条备用工作流。
4. 想先低成本试试 ，Codex 是否包含在你的套餐里，以官方页面和客户端显示为准。能用就先用别先付费上头。
如果你没有 ChatGPT 订阅，也不想充钱，那也没关系，后面会讲怎么给它接入国内大模型。
二、如何安装 Codex ？
Codex的安装过程并不复杂，一共就几步，只要你的电脑配置不是太差，基本都能跑起来。
环境要求
需要安装 Node.js 和 git 。
node --version
npm --version
git --version
Node.js 下载地址： 🔗 Node.js
Git 下载地址： 🔗 Git-scm
Windows 用户，最省心的方式是优先装 App。CLI 也能用，但如果遇到环境问题，可以考虑用 WSL，或者先跳到 App 部分。
安装 CLI
CLI 适合已经习惯终端的人。两种方式，选一个：
npm 安装
npm install -g @openai/codex
Homebrew 安装（macOS）
brew install --cask codex
验证安装：
codex --version
看到版本号就说明成功了。
如果这里没看到版本号，优先检查 Node.js、npm 全局路径和网络。
App 安装
Windows 下载地址： 🔗 Codex
云端版
直接访问： 🔗 云端版
IDE 插件
如果你用 VS Code、Cursor 或 Windsurf，可以装插件：
安装地址： 🔗 IDE插件
装完之后在编辑器里就能直接调用 Codex。
到这里你已经有四条路了。新手建议从 App 开始，开发者建议从 CLI 开始，已经有 GitHub 仓库的人可以直接试云端版。
别纠结入口，工具不是对象，不需要从一而终。
三、在 CLI 端使用 Codex
CLI 是 Codex 最像“开发者工具”的形态。你在终端里说需求，它在项目里改文件、跑命令、修问题。
启动
codex
👉 直接执行：
codex logout
或者一步到位：
codex login
登录方式
方案一：Sign in with ChatGPT（推荐）
会打开浏览器，用 ChatGPT 账号授权。
方案二：Enter API Key
模型选择
如果想切换模型，用 /model 命令。
30 秒上手
装好了，先跑一个试试。别上来就让它重构祖传系统，先拿小游戏练手，心态比较健康。
在 D 盘新建一个 test 文件夹，然后打开终端输入命令：
cd d:\test\
然后输入下面命令：
codex "用 Python 写一个贪吃蛇的游戏"
你不需要一开始就告诉它用什么框架、怎么组织代码，它会先根据需求做判断。这就是 AI 编码工具的核心价值： 你负责描述目标，它负责拆任务、改文件、跑命令。
试完这一个，你就知道 Codex 大概是什么感觉了。后面再把它放进真实项目里，价值会更明显。
当然，AI 写代码和人写代码一样，都需要你 review。不要把它当成完全不用检查的自动交付机器。
常用命令
命令
用途
codex login
登录
codex logout
退出
codex app
启动桌面应用
/init
初始化
/model
切换模型
/compact
压缩上下文
/new
开启新会话
/plan
开启计划模式
/ask
仅提问不执行
/settings
打开设置
四、在 App 端使用 Codex
启动
App 适合两类人：一类是不想一直待在终端里，另一类是希望同时看项目文件、对话记录和修改内容。
打开方式有两种，一种是直接双击桌面 Codex 的图标，一种是执行命令 codex app
基础使用
点击 项目 ，然后选择 使用现有文件夹 ，找到刚刚上面制作贪吃蛇的那个文件夹 test
可以看到刚刚的对话都已经加载进来了。这一点很关键：Codex 不是只能单次问答，它会围绕一个项目持续工作。
点击右上角的 切换文件树 ，可以看到当前目录下的文件。点击具体文件后，左侧可以预览内容，也可以直接在文件里做注释，让 Codex 按你的反馈继续修改。
这时候它就不只是“问答机器人”了，而是能围绕项目上下文继续修改。
右下角的设置里面还可以查看剩余额度。轻度使用一般够用，但额度策略会变化，最终以客户端显示为准。
五、在云端使用 Codex
云端版适合处理已经放到 GitHub 上的项目。你可以把它理解成：本地 Codex 是在你电脑上干活，云端 Codex 是连到你的 GitHub 仓库里干活。
如果你已经有 GitHub 仓库，可以直接跳到“连接 Codex 到 GitHub”。下面这段是从零创建仓库的完整流程。
初始化 Git 仓库
打开终端输入命令 cd d:\test\
然后执行以下命令：
git init
执行完成后，可以看到 App 上面多了一个 提交 的按钮。
点击 提交 ，在提交消息里填一段提交说明，然后点击 继续 ，这样我们的修改记录就保存了。
这里不要学某些老项目，全员提交信息都是 update ，多年以后查记录，自己都想给自己一拳。
创建 GitHub 远程仓库
接下来我们打开 GitHub，创建一个名为 test 的远程仓库。
创建完成后可以看到这些提示。
我们在刚刚打开的终端执行如下命令。注意把下面的地址替换成你自己的仓库地址：
git remote add origin https://github.com/ailot/test.git
执行完成后，可以看到 App 上面的 推送 按钮变成可点击的了。
在刚才的终端继续执行命令。
git branch -M maingit push -u origin main
在执行完第二条命令后，会提示你登录 GitHub。
选择浏览器登录 Sign in with your browser ，出现这个界面就表示成功了。
终端同样可以看到推送成功的日志。
GitHub 仓库也能够看到我们刚刚推送的文件。
连接 Codex 到 GitHub
打开 https://chatgpt.com/codex/cloud，点击 连接到 GitHub
点击 继续 GitHub
291
选择 Authorize 进行授权。
406
然后我们进入云端 Codex 了。
575
按照如下步骤配置远端代码仓库。
556
选择刚刚我们在 GitHub 上面创建的 test 仓库，然后点击 Install & Authorize ，输入密码授权。
476
刷新页面，可以看到我们的 test 仓库已经在 Codex 里面了。
我让它看一下这是个什么项目。
这一步很适合用来测试 Codex 有没有看懂仓库。别一上来就让它“重构整个系统”，先问它“这是个什么项目”。
输完提示词，点击发送，可以看到它在下面创建了一个任务在执行。
532
点击进去可以看到具体的执行结果。
六、IDE 端使用 Codex
IDE 插件适合日常写代码的人。它最大的价值不是“再开一个聊天窗口”，而是直接读取当前项目上下文，在写代码的位置改。
这就很适合那种写到一半突然卡住的时刻：脑子说我懂了，手说你放过我。
打开 VSCode ，然后安装 Codex IDE 插件 ，具体操作如下：
安装完成后重启 VS Code，然后打开刚刚我们在 D 盘的 test 文件夹，同样可以看到刚刚的对话都已经加载进来了。
后面还想怎么改，可以直接在对话框里面指挥。
建议从这几个场景开始用：
让它解释当前文件的作用
选中一段代码，让它重构或补注释
把报错信息贴进去，让它定位问题
让它给某个函数补单元测试
IDE 插件的优势是上下文更近，适合边写边改；CLI 的优势是执行力更强，适合让它完整跑一个任务。
简单说：IDE 插件适合边写边问，CLI 适合直接派活。
七、进阶用法
AGENTS.md 配置文件
在项目根目录创建一个 AGENTS.md 文件，告诉 Codex 你的项目规范。这个文件很重要，它相当于给 Codex 写一份”项目说明书”。
项目规范
- 语言：Python 3.11+
- 代码风格：PEP 8
- 测试框架：pytest
- 注释：中文注释
如果你是新手，可以先用下面这个更完整的模板：
AGENTS.md## 项目说明这是一个 Python 项目，主要用于练习小游戏开发。## 开发规范- 使用 Python 3.11+
- 代码保持简单，优先可读性
- 新增功能时同步更新 README
- 修改代码后尽量运行测试或启动程序验证## 交互偏好- 先解释修改思路，再改代码
- 涉及删除文件、重构目录、安装依赖时先询问
- 回复使用中文## Codex 特定配置- 权限模式：自动审查（关键操作需确认）
- 默认模型：qwen3.6-plus（或 gpt-5.5）
- 技能路径：./.codex/skills（如有）
这样 Codex 后面生成代码、跑命令、解释问题时会更贴合项目习惯。
常用场景
Codex 不只是写代码，还能：
代码重构 ，让它优化现有代码。
写单元测试 ，给函数补测试用例。
修复 Bug ，把报错信息丢给它。
代码审查， 让它 review 你的代码。
安全模式
Codex 有几种常见权限模式，不同版本界面里的中文翻译可能略有差异，但核心思路差不多：
• 默认权限， 只给建议，适合你想先看方案。
• 自动审查 ，可以自动编辑文件，但关键操作会请示你。
• 完全访问 ，权限更大，可以自动执行更多操作。
新手推荐配置 ：
• 日常使用开"自动审查"模式。
• 删除文件、安装依赖、推送代码必须手动确认。
• 批量重构时，先让他制定方案，确认后再执行。
不要一开始就完全放权，等你熟悉了 Codex 的行为模式再逐步开放权限。
八、接入国内大模型
支持的平台
通义千问 ，阿里系，稳定性好。
硅基流动， 聚合平台，模型多。
智谱 AI ，国产大模型，中文能力强。
其他提供 OpenAI 兼容 API 的平台。
配置方法
打开 App 的设置，进入配置文件进行修改。
将 config.toml 里面的配置改成下面内容：
model = "qwen3.6-plus"
model_provider = "bailian"[model_providers.bailian]
name = "bailian"
env_key = "BAILIAN_API_KEY"
base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"
然后在本地配置环境变量 BAILIAN_API_KEY ，具体步骤如下：
选中 此电脑 ，点击 右键 ，选择 属性 。
配置相关环境变量信息。
然后重启 Codex，配置即可生效。
验证国内模型是否生效
配置完成后，用这个简单任务测试一下：
用中文写一个 Python 脚本，打印"Hello 国内大模型"，然后运行它。
如果Codex能理解中文指令、生成代码、成功运行，说明配置生效了。
九、常见问题
大家安装和使用Codex的过程中，未必是一帆风顺的，小灰在此列出几个Codex使用的常见问题和解决方案：
Codex 登录失败
问题表现：
浏览器授权后回到终端，提示失败。
解决方法 ：
检查网络连接。
清除浏览器缓存重试。
换用 API Key 方式。
执行 codex logout 后重新登录。
codex 相关命令找不到
问题表现：
提示错误 codex: command not found
解决方法：
重新安装
npm install -g @openai/codex
检查 npm 全局路径
npm config get prefix
确保 npm 全局路径在你的 PATH 里。
Windows 用户如果 PATH 配置很麻烦，建议先用 App，不要卡在 CLI 环境上。
接入国内模型时配置了环境变量，仍然提示找不到
解决方法 ：
Windows 用户配置完环境变量后，需要重启 Codex（完全退出再打开），如果还不行，试试重启电脑。
注意：由于 Codex 新版本使用 Responses API，不支持 wire_api = "chat" 配置，很多大模型厂家的 API 还没适配，所以能选择的模型不多。
因此大家能跑就用，跑不起来就换平台。
其中阿里百炼支持 Responses 接口的模型如下：
qwen3-maxqwen3-max-2026-01-23qwen3.6-plusqwen3.6-plus-2026-04-02qwen3.5-plusqwen3.5-plus-2026-02-15qwen3.6-flashqwen3.6-flash-2026-04-16qwen3.5-flashqwen3.5-flash-2026-02-23qwen3.6-35b-a3bqwen3.5-397b-a17bqwen3.5-122b-a10bqwen3.5-27bqwen3.5-35b-a3bqwen-plusqwen-flashqwen3-coder-plusqwen3-coder-flashqwen3-coder-next