ACORG docs

主题

Codex CLI ​

更习惯图形界面？先看 ChatGPT 桌面端（Codex）安装与权限设置。本页只讲终端版的安装与使用。

OpenAI 官方推出的本地编码 Agent,运行在你的电脑上,可在终端中读取代码、生成补丁、执行命令并协助完成开发任务。

作用说明 ​

Codex CLI 是 OpenAI 的本地命令行编码助手,适合在项目目录中完成"读代码 → 修改代码 → 运行验证"的开发闭环。

  • 在终端中以对话方式完成代码编辑、补丁生成、命令执行
  • 直接读写本地文件,可结合 Git 工作流使用
  • 推荐使用 ChatGPT 账号登录,可使用 Plus / Pro / Business / Edu / Enterprise 计划额度
  • 也支持使用 OpenAI API Key,但需要额外配置
  • 支持 macOS、Linux、Windows,也可下载 GitHub Release 中的独立二进制文件

相关产品区分:

  • Codex CLI: 本页介绍的本地终端 Agent
  • Codex IDE: 面向 VS Code、Cursor、Windsurf 等编辑器的 IDE 集成
  • ChatGPT 桌面端中的 Codex: 图形界面入口，安装、登录与权限设置见桌面端指南；部分 CLI 安装版本也提供 codex app 启动入口
  • Codex Web: OpenAI 的云端编码 Agent,入口是 https://chatgpt.com/codex

环境要求 ​

  • 一个可登录的 ChatGPT 账号,或 OpenAI API Key
  • 使用 npm 安装时需要 Node.js 与 npm
  • 使用 Homebrew 安装时需要 macOS 与 Homebrew
  • Windows 可直接使用官方 PowerShell 安装脚本

安装 ​

官方 README 推荐优先使用安装脚本。

bash
curl -fsSL https://chatgpt.com/codex/install.sh | sh
powershell
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
bash
npm install -g @openai/codex
bash
brew install --cask codex

也可以到 GitHub Release 下载对应平台的二进制文件。常见文件包括:

  • macOS Apple Silicon: codex-aarch64-apple-darwin.tar.gz
  • macOS x86_64: codex-x86_64-apple-darwin.tar.gz
  • Linux x86_64: codex-x86_64-unknown-linux-musl.tar.gz
  • Linux arm64: codex-aarch64-unknown-linux-musl.tar.gz

解压后通常需要把可执行文件重命名为 codex,并放入 PATH。

验证安装:

bash
codex --version

首次登录 ​

直接运行:

bash
codex

首次启动时选择登录方式:

  • Sign in with ChatGPT: 官方推荐方式,使用 ChatGPT 订阅计划中的 Codex 权益
  • API Key: 适合使用 OpenAI API 计费的开发者,需要按官方认证文档完成额外配置

如果选择 API Key 计费,先在当前终端设置变量,再执行 Codex 登录；只设置变量不等于已经完成 Codex 认证。只选择自己使用的终端执行对应示例:

powershell
$env:OPENAI_API_KEY = "sk-xxxx"
$env:OPENAI_API_KEY | codex login --with-api-key
bash
export OPENAI_API_KEY="sk-xxxx"
printenv OPENAI_API_KEY | codex login --with-api-key

环境变量只在当前终端生效。若需要持久配置,使用操作系统或密钥管理工具；新开终端需要重新读取环境变量。不要把真实密钥写入项目文件或提交到 Git。首次使用通常优先选择 Sign in with ChatGPT。

常用命令 ​

  • codex: 启动 Codex CLI 交互式会话
  • codex "<任务描述>": 直接带任务启动会话
  • codex app: 启动 Codex 桌面应用体验
  • codex --help: 查看命令帮助
  • codex --version: 查看当前版本

会话内命令以实际 codex --help 和交互界面提示为准。

基本工作流 ​

  1. 进入项目目录:

    bash
    cd your-project

  2. 启动 Codex:

    bash
    codex

  3. 用自然语言描述任务,例如:

    text
    修复 src/api/user.ts 中的 token 刷新逻辑,补充错误处理

  4. Codex 会读取文件、生成补丁、运行命令或请求权限

  5. 检查修改与验证结果,必要时继续给出反馈

升级 ​

如果使用 npm 安装:

bash
npm update -g @openai/codex

如果使用 Homebrew 安装:

bash
brew upgrade --cask codex

如果使用官方安装脚本或 GitHub Release 安装,按最新 README 或 Release 说明重新安装对应版本。

常见问题 ​

codex: command not found ​

通常是安装目录未加入 PATH。npm 安装时先查看全局前缀和命令解析位置:

bash
npm prefix -g
powershell
Get-Command codex
where.exe codex

macOS / Linux 可使用:

bash
command -v codex

脚本或二进制安装时,确认 codex 可执行文件所在目录已加入 PATH。

npm 全局安装权限错误 ​

Linux / macOS 下可以改用用户级 npm 前缀:

bash
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH

也可以改用官方安装脚本或 Homebrew。

Windows 是否必须使用 WSL2? ​

不必须。README 提供了 Windows PowerShell 安装脚本。若项目依赖 Linux 工具链或团队统一使用 WSL2,再在 WSL2 中安装即可。

想在编辑器里使用 Codex? ​

如果需要 VS Code、Cursor、Windsurf 等编辑器集成,应安装 Codex IDE,而不是只使用 Codex CLI。

想使用云端 Agent? ​

云端版本是 Codex Web,访问 https://chatgpt.com/codex。

参考链接 ​