← 返回 OpenAI Codex 教程卡片

OpenAI Codex

OpenAI 推出的 AI 编程智能体（CLI 以 Apache 2.0 开源）。

需特殊网络环境。

采集于 2026-10-05 · 关键步骤请以官方最新文档为准

一句话简介： OpenAI 推出的 AI 编程智能体（CLI 以 Apache 2.0 开源）。

主流功能：委托式云端编程、多仓库并行、自动提 PR

可用性：需特殊网络环境。

适用人群：开发者；想在终端里用 AI 结对编程、做仓库级重构、自动跑测试修 bug 的人

前置条件：

Node.js 20+（LTS 版本），node -v / npm -v 能正常输出
OpenAI 账号：二选一
方式 A（推荐新手）：ChatGPT Plus / Pro / Business 订阅账号，用 codex login 走浏览器 OAuth 登录
方式 B：OpenAI API Key（OPENAI_API_KEY），按量付费

分步骤教程

第一步：安装 Node.js

前往 Node.js 官网下载 LTS 版本安装（Windows 保持默认安装路径最省心）。
终端验证：
```
node -v
npm -v
```
两个命令都输出版本号即成功。

第二步：安装 Codex CLI（国内建议换镜像源）

国内用户先给 npm 换淘宝镜像（只换源，不影响后续使用）：

npm config set registry https://registry.npmmirror.com

或单次安装时指定：

npm i -g @openai/codex --registry=https://registry.npmmirror.com

正常安装命令（包名以 OpenAI 官方 GitHub 仓库为准）：
```
npm install -g @openai/codex
```
注意：网上老教程常写 npm install -g codex，那是旧包名/旧写法，以 @openai/codex 为准。
验证安装：
```
codex --version
```
能输出版本号即成功。Windows 若提示"找不到 codex 命令"：重新打开终端再试；或用 npx @openai/codex 临时启动；或检查 npm config get prefix 的路径是否在系统 PATH 中。

第三步：登录

在终端执行：
```
codex login
```
会自动打开浏览器跳转到 OpenAI 登录页，选择 Sign in with ChatGPT 完成授权，凭证会写回本地（~/.codex/ 下）。

另外两种登录方式：

codex login --device-auth        # 设备码方式（浏览器打不开时用）
echo $OPENAI_API_KEY | codex login --with-api-key   # 用 API Key 登录

检查登录状态：
```
codex login status
```
若授权后回调失败：多为网络问题，检查代理是否开了全局路由/TUN 模式，然后重新执行 codex 登录。

第四步：基础配置（`~/.codex/config.toml`）

配置文件位于用户主目录：macOS/Linux ~/.codex/config.toml，Windows %USERPROFILE%\.codex\config.toml（没有就手动新建）。

新手推荐配置：

model_provider = "openai"
model = "gpt-5-codex"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[history]
persistence = "save-all"

含义：走官方模型、代码专用模型、推理强度中档、风险动作人工确认、只允许改当前工作区、保存历史会话。

想让它默认用中文回复，在 ~/.codex/ 下建 AGENTS.md 并写入：

mkdir -p ~/.codex && printf 'Always respond in Chinese-simplified\n' > ~/.codex/AGENTS.md

第五步：开始使用——常用命令

交互模式（推荐日常使用）：
```
cd 你的项目目录
codex
```
进入后直接用自然语言下指令，支持 Tab 补全、Ctrl-R 搜历史。

单次指令直达：

codex "写一个下载文件的 Python 脚本"
codex -i error.png "修掉截图里的报错"     # 直接读报错截图
codex exec "跑通 pytest"                  # 执行命令：装依赖→跑测试→失败自动修

常用参数：

codex -m gpt-5-codex "给整个 Go 项目加 ctx 传值"   # -m/--model 临时切换模型
codex -s read-only "解释这个仓库的架构"            # --sandbox: read-only | workspace-write | danger-full-access
codex -a on-request "重构登录模块"                  # --ask-for-approval: untrusted | on-request | never
codex --search "查一下这个报错的最新解法"          # 临时启用实时联网搜索

危险模式（跳过审批与沙箱，明确知道后果再用）：
```
codex --yolo "批量重命名所有测试文件"
```

第六步：云端版 Codex 使用

在 ChatGPT 网页端/桌面端侧边栏找到 Codex 入口（2025 年 6 月起向 Plus 用户开放）。
连接你的 GitHub 账号并授权目标仓库。
新建任务：用自然语言描述需求（如"给登录接口加限流并补单测"），Codex 会在云端沙盒里执行：拉代码 → 改代码 → 跑测试 → 生成 diff/PR。
你在网页端审查每一步的执行日志和代码 diff，确认后合并。
云端任务会计入相应计划的用量；本地 CLI 走订阅登录则按订阅规则计（2026 年具体额度以官网为准，未验证）。

第七步：IDE 插件（可选）

VS Code / Cursor 的扩展市场搜索 Codex 官方插件并安装，登录后即可在编辑器内对话式改代码、查看 diff 并一键撤销，适合不习惯纯终端的用户。

常见问题

npm 安装特别慢或超时怎么办？ 换国内镜像：npm config set registry https://registry.npmmirror.com 后重装。只是下载包走镜像，不影响 Codex 后续调用 OpenAI 服务。
codex login 浏览器回调失败？ 多为代理问题：需要开启代理的全局路由/TUN 模式后再重新登录；或改用 codex login --device-auth 设备码方式。
提示 command not found: codex？ 先重开终端；仍不行用 npx @openai/codex 应急；Windows 检查 npm 全局路径是否加入 PATH（npm config get prefix）。
一定要订阅 Plus 才能用吗？ 两种鉴权：ChatGPT 订阅（Plus/Pro/Business）OAuth 登录，或自备 OPENAI_API_KEY 按量付费。CLI 本体开源免费，不收授权费。
国内有中转/镜像方案吗？ 有第三方 API 中转服务可把 base_url 指向中转地址（在 config.toml 的 [model_providers.*] 中配置），但属于非官方渠道，稳定性与合规性自行评估，此处不推荐具体服务商。

← 返回教程目录

OpenAI Codex

一句话简介： OpenAI 推出的 AI 编程智能体（CLI 以 Apache 2.0 开源）。

主流功能：委托式云端编程、多仓库并行、自动提 PR

可用性：需特殊网络环境。

适用人群：开发者；想在终端里用 AI 结对编程、做仓库级重构、自动跑测试修 bug 的人

前置条件：

Node.js 20+（LTS 版本），node -v / npm -v 能正常输出
OpenAI 账号：二选一
方式 A（推荐新手）：ChatGPT Plus / Pro / Business 订阅账号，用 codex login 走浏览器 OAuth 登录
方式 B：OpenAI API Key（OPENAI_API_KEY），按量付费

分步骤教程

第一步：安装 Node.js

前往 Node.js 官网下载 LTS 版本安装（Windows 保持默认安装路径最省心）。
终端验证：
```
node -v
npm -v
```
两个命令都输出版本号即成功。

第二步：安装 Codex CLI（国内建议换镜像源）

国内用户先给 npm 换淘宝镜像（只换源，不影响后续使用）：

npm config set registry https://registry.npmmirror.com

或单次安装时指定：

npm i -g @openai/codex --registry=https://registry.npmmirror.com

正常安装命令（包名以 OpenAI 官方 GitHub 仓库为准）：
```
npm install -g @openai/codex
```
注意：网上老教程常写 npm install -g codex，那是旧包名/旧写法，以 @openai/codex 为准。
验证安装：
```
codex --version
```
能输出版本号即成功。Windows 若提示"找不到 codex 命令"：重新打开终端再试；或用 npx @openai/codex 临时启动；或检查 npm config get prefix 的路径是否在系统 PATH 中。

第三步：登录

在终端执行：
```
codex login
```
会自动打开浏览器跳转到 OpenAI 登录页，选择 Sign in with ChatGPT 完成授权，凭证会写回本地（~/.codex/ 下）。

另外两种登录方式：

codex login --device-auth        # 设备码方式（浏览器打不开时用）
echo $OPENAI_API_KEY | codex login --with-api-key   # 用 API Key 登录

检查登录状态：
```
codex login status
```
若授权后回调失败：多为网络问题，检查代理是否开了全局路由/TUN 模式，然后重新执行 codex 登录。

第四步：基础配置（`~/.codex/config.toml`）

配置文件位于用户主目录：macOS/Linux ~/.codex/config.toml，Windows %USERPROFILE%\.codex\config.toml（没有就手动新建）。

新手推荐配置：

model_provider = "openai"
model = "gpt-5-codex"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[history]
persistence = "save-all"

含义：走官方模型、代码专用模型、推理强度中档、风险动作人工确认、只允许改当前工作区、保存历史会话。

想让它默认用中文回复，在 ~/.codex/ 下建 AGENTS.md 并写入：

mkdir -p ~/.codex && printf 'Always respond in Chinese-simplified\n' > ~/.codex/AGENTS.md

第五步：开始使用——常用命令

交互模式（推荐日常使用）：
```
cd 你的项目目录
codex
```
进入后直接用自然语言下指令，支持 Tab 补全、Ctrl-R 搜历史。

单次指令直达：

codex "写一个下载文件的 Python 脚本"
codex -i error.png "修掉截图里的报错"     # 直接读报错截图
codex exec "跑通 pytest"                  # 执行命令：装依赖→跑测试→失败自动修

常用参数：

codex -m gpt-5-codex "给整个 Go 项目加 ctx 传值"   # -m/--model 临时切换模型
codex -s read-only "解释这个仓库的架构"            # --sandbox: read-only | workspace-write | danger-full-access
codex -a on-request "重构登录模块"                  # --ask-for-approval: untrusted | on-request | never
codex --search "查一下这个报错的最新解法"          # 临时启用实时联网搜索

危险模式（跳过审批与沙箱，明确知道后果再用）：
```
codex --yolo "批量重命名所有测试文件"
```

第六步：云端版 Codex 使用

在 ChatGPT 网页端/桌面端侧边栏找到 Codex 入口（2025 年 6 月起向 Plus 用户开放）。
连接你的 GitHub 账号并授权目标仓库。
新建任务：用自然语言描述需求（如"给登录接口加限流并补单测"），Codex 会在云端沙盒里执行：拉代码 → 改代码 → 跑测试 → 生成 diff/PR。
你在网页端审查每一步的执行日志和代码 diff，确认后合并。
云端任务会计入相应计划的用量；本地 CLI 走订阅登录则按订阅规则计（2026 年具体额度以官网为准，未验证）。

第七步：IDE 插件（可选）

VS Code / Cursor 的扩展市场搜索 Codex 官方插件并安装，登录后即可在编辑器内对话式改代码、查看 diff 并一键撤销，适合不习惯纯终端的用户。

常见问题

npm 安装特别慢或超时怎么办？ 换国内镜像：npm config set registry https://registry.npmmirror.com 后重装。只是下载包走镜像，不影响 Codex 后续调用 OpenAI 服务。
codex login 浏览器回调失败？ 多为代理问题：需要开启代理的全局路由/TUN 模式后再重新登录；或改用 codex login --device-auth 设备码方式。
提示 command not found: codex？ 先重开终端；仍不行用 npx @openai/codex 应急；Windows 检查 npm 全局路径是否加入 PATH（npm config get prefix）。
一定要订阅 Plus 才能用吗？ 两种鉴权：ChatGPT 订阅（Plus/Pro/Business）OAuth 登录，或自备 OPENAI_API_KEY 按量付费。CLI 本体开源免费，不收授权费。
国内有中转/镜像方案吗？ 有第三方 API 中转服务可把 base_url 指向中转地址（在 config.toml 的 [model_providers.*] 中配置），但属于非官方渠道，稳定性与合规性自行评估，此处不推荐具体服务商。

分步骤教程

第一步：安装 Node.js

第二步：安装 Codex CLI（国内建议换镜像源）

第三步：登录

第四步：基础配置（~/.codex/config.toml）

第五步：开始使用——常用命令

第六步：云端版 Codex 使用

第七步：IDE 插件（可选）

常见问题

OpenAI Codex

分步骤教程

第一步：安装 Node.js

第二步：安装 Codex CLI（国内建议换镜像源）

第三步：登录

第四步：基础配置（~/.codex/config.toml）

第五步：开始使用——常用命令

第六步：云端版 Codex 使用

第七步：IDE 插件（可选）

常见问题

第四步：基础配置（`~/.codex/config.toml`）

第四步：基础配置（`~/.codex/config.toml`）