Codex 使用指南

Appearance

Codex 官网国内访问 + 完整安装教程：macOS / Windows / Linux 一次跑通（2026） ​

2026 年新手优先推荐安装 ChatGPT 桌面端，再在应用中打开 Codex。 它不要求你先安装 Node.js，也不用处理 npm、终端 PATH 或配置文件，下载、登录、选择项目文件夹后就能开始工作。

如果你已经习惯终端，或者需要脚本化、非交互执行和精确控制沙箱，再继续安装 Codex CLI。本文先介绍桌面端的选择依据，再重点讲解 CLI 安装与配置；桌面版的详细安装步骤请阅读单独的图文教程。

IMPORTANT

本文于 2026 年 7 月 22 日校对。桌面端入口和平台按钮已在 OpenAI 官方下载页实际核对；CLI 命令已在 macOS 环境实际执行。命令截图环境为 macOS 26.5.2、Node.js 22.21.1、npm 11.7.0、Codex CLI 0.145.0-alpha.27。产品更新较快，界面或版本号略有不同通常不是故障。

开始前：Codex 官网在国内访问不了怎么办？ ​

Codex 的产品介绍、下载、登录和 API 控制台不是同一个站点。某个页面打不开，并不一定代表 Codex 本身不能安装。建议先确认自己需要访问的是哪个入口：

目的官方入口用途
了解 Codexdevelopers.openai.com/codex产品介绍、文档与各客户端入口
下载桌面端chatgpt.com/downloadmacOS、Windows 桌面应用
安装 CLIgithub.com/openai/codex源码、发行说明和 CLI 安装资料
使用 APIplatform.openai.comAPI Key、用量和账单管理

国内网络环境中常见的现象包括页面加载超时、登录回调没有返回客户端、验证码或付款页面无法打开。排查时按下面的顺序进行：

  1. 检查系统日期、时区、DNS 和浏览器是否正常；
  2. 换一个浏览器或无痕窗口，排除旧 Cookie 与扩展干扰；
  3. 如果处于公司或校园网络，确认防火墙是否阻止登录回调和应用更新；
  4. 确认账号所在地区、付款方式和服务可用范围符合 OpenAI 当前政策；
  5. 只从官方页面或可信软件仓库下载安装包，不使用来源不明的“破解版”。

CAUTION

网络可达、账号可登录、订阅可用和 API 有余额是四件不同的事。本文不保证任何第三方网络、账号或中转服务的可用性，也不要把 API Key 交给不可信网站。请遵守所在地法律法规及 OpenAI 的服务条款。

如果你能打开桌面版并完成登录，就不必为了“配置完整”再安装 CLI。先用桌面版跑通第一个项目，通常是新手最省时间的路线。

一、2026 年首先推荐：安装桌面端 ​

截至本文校对日期，OpenAI 官方下载页主推的是 桌面版 ChatGPT，Codex 已经作为开发工作入口集成其中。页面同时提示：原 Codex 应用用户可以更新到 ChatGPT，然后在应用内打开 Codex。

OpenAI 官方桌面版下载页，提供 macOS 和 Windows 下载按钮

图：2026 年 7 月 22 日实际访问 OpenAI 官方下载页 截图。页面提供 macOS 和 Windows 下载按钮，并说明桌面版包含 Codex。

为什么新手应优先用桌面端？ ​

  • 不需要预先安装 Node.js、npm，也不用配置命令行 PATH；
  • 有完整图形界面，可以选择项目文件夹、查看任务进度和审查文件改动；
  • 登录、权限请求和任务切换更直观；
  • 仍然可以让 Codex 读取代码、修改工作区并运行项目命令；
  • 熟悉工作流后，再安装 CLI 不会冲突。

Codex 常见入口对比如下：

入口适合谁是否必须安装 Node.js
ChatGPT 桌面端中的 Codex绝大多数新手、希望图形化管理任务的用户不需要
Codex CLI喜欢终端、需要脚本化或非交互执行的开发者npm 安装方式需要
IDE 扩展主要在代码编辑器中工作的用户视编辑器和扩展要求而定
Codex 网页/云端希望把任务交给托管环境运行的用户本机通常不需要

TIP

如果你电脑里已经有旧版独立 Codex 应用，不必并行保留多个入口。先在应用内检查更新，或从官方页面安装当前桌面版 ChatGPT，再从模式菜单打开 Codex。

二、下载安装桌面端（推荐路线） ​

桌面版的下载、API Key 授权登录、Base URL 配置、CC Switch 多模型切换和中文界面设置已有独立图文教程，本文不再重复展开。

TIP

前往完整教程：Codex 桌面版安装配置全流程（保姆级教程）

该教程包含桌面版下载安装、API Key 登录、CC Switch 配置与中文界面设置，并配有操作截图。完成桌面版安装后，如果还需要终端工作流、自动化或更精细的权限控制，再返回本文继续阅读下面的 Codex CLI 部分。

三、安装 Codex CLI 前的准备 ​

如果桌面端已经满足需求，可以跳过 CLI 安装。只有在你需要终端工作流、自动化或 codex exec 时，再继续本节。

1. 检查系统和基础工具 ​

macOS 或 Linux 打开“终端”，Windows 打开 PowerShell，依次执行：

bash
git --version
node --version
npm --version

如果出现“command not found”或“不是内部或外部命令”：

  • Git：从 git-scm.com 下载；
  • Node.js：从 nodejs.org 安装当前 LTS 版；
  • 安装 Node.js 时会一并安装 npm。

下面是本文环境中真实执行的版本检查：

macOS 终端实际执行 Node.js、npm 与 Codex 版本检查

TIP

已安装 Codex 的用户不必重装，先运行 codex --version。能输出版本号就说明命令已经进入 PATH。

2. 准备 CLI 登录方式 ​

你需要以下二选一：

  1. 可使用 Codex 的 ChatGPT 账号，首次启动后按浏览器页面提示登录；
  2. OpenAI API Key，通过标准输入交给 CLI。

ChatGPT 订阅和 API 计费是两套体系。使用 API Key 时，消耗通常计入 API 平台账户，而不是 ChatGPT 订阅额度。

四、下载并安装 Codex CLI（进阶可选） ​

方案 A：官方安装脚本（macOS / Linux） ​

在终端执行：

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

安装结束后关闭并重新打开终端，再检查：

bash
codex --version

如果公司网络禁止执行在线脚本，使用下面的 npm 方案；在安全要求较高的环境中，也应先审查脚本内容再执行。

方案 B：npm 安装（macOS / Linux / Windows） ​

bash
npm install -g @openai/codex
codex --version

升级到 npm 仓库当前版本：

bash
npm install -g @openai/codex@latest

如果是由 Codex 桌面应用附带的 CLI，也可以先查看当前版本是否支持内置更新：

bash
codex update --help

不要同时用多个包管理器反复全局安装，否则 PATH 中可能出现多个 codex。可以这样确认实际运行的是哪一个：

bash
# macOS / Linux
command -v codex

# Windows PowerShell
Get-Command codex

五、CLI 首次登录 ​

1. 浏览器账号登录 ​

直接运行：

bash
codex

首次启动时按终端和浏览器提示登录。登录成功后，回到终端即可进入 Codex 交互界面。

也可以先查看当前版本支持的登录选项：

bash
codex login --help

Codex login help 的实际终端输出

检查登录状态：

bash
codex login status

2. 使用 API Key 登录 ​

macOS / Linux：

bash
export OPENAI_API_KEY="你的_API_Key"
printenv OPENAI_API_KEY | codex login --with-api-key

Windows PowerShell：

powershell
$env:OPENAI_API_KEY="你的_API_Key"
$env:OPENAI_API_KEY | codex login --with-api-key

CAUTION

不要把真实 API Key 写进 Git 仓库、截图、聊天记录或 AGENTS.md。上面的写法只用于演示；长期使用应交给系统钥匙串、密码管理器或受控的环境变量管理工具。

退出当前账号：

bash
codex logout

六、配置 Codex CLI：先用安全默认值 ​

Codex 的用户级配置文件通常位于：

  • macOS / Linux：~/.codex/config.toml
  • Windows：%USERPROFILE%\.codex\config.toml

如果文件不存在，可以新建它。第一次使用推荐写入：

toml
sandbox_mode = "workspace-write"
approval_policy = "on-request"

这两个设置的含义是：

  • workspace-write：允许 Codex 在当前工作区内修改文件，但不等于拥有整台电脑的任意写权限；
  • on-request：任务确实需要越过现有边界时，由 Codex发起审批请求。

本文用命令行临时覆盖配置，并启用 --strict-config 做了真实校验：

Codex sandbox_mode 与 approval_policy 配置严格校验

你也可以用同样方式排查配置拼写：

bash
codex \
  -c 'sandbox_mode="workspace-write"' \
  -c 'approval_policy="on-request"' \
  --strict-config --version

要不要手动指定模型？ ​

新手建议先不写 model，让 Codex 使用当前账号和客户端的默认选择。模型可用性可能因账号、工作空间和发布时间而不同；确实需要指定时，先运行 codex --help，再用当前环境明确提供的模型标识。

临时指定模型的命令形式是：

bash
codex --model "你的模型标识"

不要从旧教程复制一个过时模型名后长期写死在全局配置中。

权限模式怎么选？ ​

模式能做什么适用场景
read-only读取和分析，不写工作区代码审查、首次调查陌生仓库
workspace-write可在工作区内修改日常开发，推荐默认
danger-full-access大幅放宽沙箱限制仅限已有外部隔离的受控环境

临时只读启动：

bash
codex --sandbox read-only

WARNING

不要为了少点几次确认就使用 --dangerously-bypass-approvals-and-sandbox。这个选项会同时绕过审批和沙箱，官方帮助也将其标记为极其危险。

七、给项目增加 AGENTS.md ​

config.toml 管运行设置，AGENTS.md 管项目协作规则。进入仓库根目录，新建 AGENTS.md：

md
# Repository guidance

## Commands
- Install: `npm install`
- Test: `npm test`
- Lint: `npm run lint`
- Build: `npm run build`

## Change rules
- 修改前先阅读 README 和相关测试。
- 不要在未说明原因时新增依赖。
- 完成后列出实际运行的验证命令和结果。
- 不要修改 `.env`、密钥或生产配置。

这样 Codex 每次进入仓库都更容易找到正确的安装、测试和构建命令。一次性需求仍应写在当前提示词中，不要把所有临时任务都塞进 AGENTS.md。

八、运行你的第一个 CLI 任务 ​

先进入一个带 Git 版本控制的练习项目：

bash
cd /path/to/your-project
git status --short
codex

第一次不要直接让它“大改项目”，可以复制下面这段：

text
先不要修改文件。

请阅读 README、项目清单文件和测试目录，然后告诉我：
1. 项目如何安装、测试和构建；
2. 主要入口文件在哪里；
3. 当前工作区是否有未提交改动；
4. 建议从哪个最小任务开始。

回答时引用真实文件，不确定的地方明确说明。

如果只想执行一次非交互任务：

bash
codex exec "阅读 README 和 package.json，总结项目的启动、测试和构建命令，不要修改文件"

从其他目录直接指定项目：

bash
codex --cd /path/to/your-project

九、CLI 安装失败排查 ​

1. codex: command not found ​

先检查 npm 全局目录和安装状态：

bash
npm config get prefix
npm list -g @openai/codex

然后关闭并重新打开终端。若仍找不到，确认 npm 全局可执行目录已加入 PATH。Windows 还可以执行 Get-Command codex 查看命令解析结果。

2. npm 提示权限不足 ​

不要一看到 EACCES 就直接使用 sudo npm install -g。更稳妥的做法是使用 Node 版本管理器，或把 npm 全局目录配置到当前用户可写的位置，再重新安装。

3. 登录页面打不开或一直等待 ​

依次检查：

bash
codex login --help
codex doctor

再确认系统时间、DNS、代理、防火墙和公司网络策略。设备认证是否可用，以 codex login --help 的实际输出为准。

4. 配置文件报错 ​

TOML 字符串要使用引号，布尔值不要加引号。先移除刚添加的配置，再逐项恢复；也可以使用：

bash
codex --strict-config --version

严格模式会在当前版本不认识配置字段时直接报错，比“看起来写对了”可靠。

5. Codex 能读文件但不能联网或写目录 ​

这通常是沙箱和审批策略在生效，不等于安装损坏。先确认任务是否真的需要网络或工作区外写入，再只批准必要的命令与目标。不要把放宽所有权限当作通用修复。

十、CLI 升级、卸载与日常自检 ​

npm 安装方式 ​

bash
# 升级
npm install -g @openai/codex@latest

# 卸载
npm uninstall -g @openai/codex

每次升级后建议检查 ​

bash
codex --version
codex --help
codex login status
codex doctor

发布 doctor 输出或错误截图前，先删除用户名、本机路径、代理地址、模型提供方、MCP 服务和认证摘要等敏感信息。

十一、最短安装清单 ​

如果你只想照着做，优先走桌面端路线：

  1. 打开 OpenAI 官方下载页；
  2. 点击 macOS 或 Windows；
  3. 按系统提示安装并打开 ChatGPT；
  4. 使用 ChatGPT 账号登录；
  5. 新建任务并选择 Codex；
  6. 选择一个练习项目文件夹；
  7. 先发送“只调查、不修改”的第一条任务。

只有需要终端、自动化或非交互执行时，再安装 CLI：

bash
# 1. 安装 Node.js 后确认 npm 可用
node --version
npm --version

# 2. 安装 Codex CLI
npm install -g @openai/codex

# 3. 验证
codex --version

# 4. 启动并按提示登录
codex

# 5. 进入练习仓库
cd /path/to/your-project
git status --short
codex

CLI 配置文件推荐从最小安全设置开始：

toml
sandbox_mode = "workspace-write"
approval_policy = "on-request"

到这里，桌面端路线已经可以直接使用，CLI 路线也完成了安装、登录和基础配置。真正决定使用效果的下一步，是把目标、范围、约束和验证命令写清楚，并始终审查 Codex 产生的 diff 和实际测试结果。

官方资料 ​

最后校对：2026 年 7 月 22 日