更新时间：2026 年 8 月 2 日。 本文根据 OpenAI Codex 官方文档、官方 GitHub 仓库和官方桌面应用介绍重新整理。Codex 更新较快，界面、模型名称与套餐额度可能变化，请以文末官方资料为准。

OpenAI Codex CLI 官方界面

Codex CLI 官方仓库界面图，经 jsDelivr CDN 引用

Codex 现在不只是一个终端工具。官方主要提供 CLI 命令行、IDE 扩展、桌面 GUI 和云端 Codex 四种入口。本文将命令行与 GUI 分开讲解，并补充权限管理、AGENTS.md、自动化执行和可直接套用的提示词模板。

一、先选择适合自己的 Codex

入口 适合场景 主要特点
Codex CLI Linux 服务器、WSL、SSH、重度开发 轻量，可执行命令，可脚本化
IDE 扩展 VS Code、Cursor、Windsurf 自动利用当前文件、选区和编辑器上下文
桌面 GUI Windows、macOS，多项目并行 线程、Diff、worktree、Skills、Automations
Codex Web 云端仓库与异步任务 不要求本机一直运行
Windows
Windows		 Linux
Linux / WSL2		 macOS
macOS		 VS Code
IDE 扩展

实际开发中可以同时使用：IDE 负责日常交互，CLI 负责终端与自动化，桌面应用负责并行任务和集中审查。

第一部分：Codex 命令行

二、安装 Codex CLI

1. Windows 原生安装

以普通 PowerShell 打开终端，执行官方安装命令：

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

重新打开终端后运行：

codex
codex --version

Windows 原生方式适合 PowerShell、Windows 工具链，以及存放在 Windows 文件系统中的项目。

2. Windows + WSL2

项目依赖 Docker、Shell 脚本或 Linux 工具链时，推荐在 WSL2 内安装 Codex。

管理员 PowerShell：

wsl --install

重启后进入 WSL，再执行：

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

官方已不再支持 WSL1。项目建议放在 Linux 文件系统中：

mkdir -p ~/code
cd ~/code
git clone https://github.com/example/example.git
cd example
codex

大型项目尽量不要放在 /mnt/c/ 下。使用 ~/code 一类目录，通常能减少跨文件系统带来的性能、权限、软链接和文件监听问题。

3. macOS 与 Linux

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

4. npm 安装

已经安装 Node.js 时，也可以使用：

npm install -g @openai/codex

更新：

npm install -g @openai/codex@latest

5. Homebrew 安装

brew install --cask codex

更新：

brew upgrade --cask codex

安装脚本、npm、Homebrew 和手动二进制最好只选一种。重复安装可能导致你更新了一个版本，终端实际执行的却是另一个版本。

遇到 codex: command not found 时，可检查：

which codex
npm config get prefix

Windows 使用：

where.exe codex
npm config get prefix

三、登录：ChatGPT 账户或 API Key

首次运行 codex 会进入登录流程，也可以主动执行：

codex login
codex login status

退出：

codex logout

使用 ChatGPT 账户

浏览器会打开授权页面。普通用户优先使用这种方式，Codex 用量计入当前账户可用的 Codex 权益。

使用 API Key

API Key 按 API 实际用量计费，与 ChatGPT 订阅额度不是同一套计费方式。

Linux、macOS 或 WSL：

export OPENAI_API_KEY="你的 API Key"
printenv OPENAI_API_KEY | codex login --with-api-key

远程服务器无法打开浏览器时：

codex login --device-auth

认证信息可能保存在系统凭据存储中，也可能位于 ~/.codex/auth.json。应把它当作密码文件，不要上传、分享或提交到 Git。

四、第一次使用 CLI

进入项目目录：

cd ~/code/my-project
git status
codex

第一次接触陌生项目，先让 Codex 阅读而不是直接修改：

先不要修改代码。阅读 README、构建文件、主要入口和目录结构，说明：
1. 项目用途、技术栈与模块边界；
2. 本地启动、构建和测试命令；
3. 请求或数据的主要流转路径；
4. 当前最值得注意的五个风险。
每条结论都给出对应文件路径，不能确认的标记为“待验证”。

权限与沙箱

只读分析：

codex --sandbox read-only --ask-for-approval on-request

允许修改当前工作区，但敏感操作仍需确认：

codex --sandbox workspace-write --ask-for-approval on-request

日常项目不建议直接开放完全不受限制的权限。仓库中存在部署密钥、生产数据库配置或危险脚本时，应先只读分析，再按任务逐步放权。

常用斜杠命令

命令 用途
/init 创建项目级 AGENTS.md
/status 查看会话、模型、权限和上下文状态
/permissions 调整当前权限模式
/model 切换可用模型
/plan 先规划，再执行复杂任务
/review 审查代码变更
/compact 压缩长会话上下文
/mcp 查看已配置的 MCP 工具

不同版本和入口支持的命令可能略有差异，输入 / 即可查看当前版本的实际命令列表。

五、用 codex exec 做自动化

非交互模式适合脚本、CI 和批量分析。

只读分析仓库：

codex exec "总结仓库结构，并列出最需要关注的五个风险区域。不要修改文件。"

生成发布说明：

codex exec "根据最近 10 个提交生成发布说明" | tee release-notes.md

允许修改工作区：

codex exec --sandbox workspace-write \
  "修复当前 lint 错误，只修改必要文件，并在完成后重新运行 lint。"

输出 JSONL：

codex exec --json "总结仓库结构" | jq

使用临时会话：

codex exec --ephemeral "检查仓库是否存在明显的密钥泄露风险"

自动化环境应配合容器、临时工作区、最小权限账号和明确的网络策略，不能因为无人值守就直接放开全部权限。

第二部分：Codex GUI

六、IDE 扩展：VS Code、Cursor、Windsurf

官方扩展标识为 OpenAI.chatgpt，在扩展市场中的名称是 Codex – OpenAI’s coding agent。

安装步骤：

  1. 打开编辑器扩展市场；
  2. 搜索 Codex；
  3. 确认发布者为 OpenAI；
  4. 安装并使用 ChatGPT 账户登录；
  5. 打开项目文件夹，在侧边栏打开 Codex。

也可以通过命令面板：

Ctrl + Shift + P

执行：

Codex: Open Codex Sidebar

IDE 扩展会利用当前打开的文件和选中代码，但跨模块任务仍应明确指出入口、相关目录和测试位置。例如：

解释当前选中代码的数据流和错误处理路径。
重点说明输入来源、空值分支、被吞掉的异常和测试缺口。
先分析，不要修改。每项结论给出对应符号或文件位置。

VS Code + WSL2

先通过 VS Code 的 WSL 远程窗口打开 Linux 项目，再使用 Codex。这样编辑器、终端、依赖、Codex 和项目文件都位于同一环境中，避免 Windows 路径与 Linux 路径混用。

七、桌面 GUI：Codex App

官方桌面应用支持 Windows 和 macOS。安装 CLI 后可尝试：

codex app

也可以从 Codex 官方页面下载桌面应用。

桌面应用更像一个 AI 开发工作台，适合：

  • 同时运行多个任务或 Agent；
  • 按项目管理独立线程；
  • 查看并评论 Diff；
  • 使用 Git worktree 隔离并行任务；
  • 在 CLI、IDE 与桌面应用之间延续部分会话和配置；
  • 管理 Skills 与定时 Automations。

复杂任务先使用：

/plan

要求计划包含受影响模块、接口变化、数据迁移、测试策略、风险和回滚方式。确认计划后，桌面应用中可以进入 Goal 模式：

/goal

Goal 模式适合边界清楚、验收标准完整的长任务。不要只写“把项目做好”，而要明确功能范围、禁止事项和完成标准。

多个 Agent 不应同时争抢同一个工作目录。使用独立 worktree 或分支，完成后再统一审查与合并。

八、用 AGENTS.md 固化项目规则

在项目根目录使用 /init，或手动创建：

# AGENTS.md

## 项目约定
- 后端使用 Java 21，前端只使用 TypeScript。
- 历史数据库迁移文件不得修改。
- 未经明确要求，不新增生产依赖。

## 常用命令
- 前端：`npm run lint && npm run test`
- 后端：`./gradlew test`

## 修改边界
- 不得删除现有公开 API。
- 不得写入密钥、Token 或真实个人信息。
- 修改接口时同步更新类型、测试和文档。

## 完成标准
- 运行与改动最相关的测试和构建。
- 报告实际执行过的命令及结果。
- 未运行或失败的验证必须明确说明，不能声称已经通过。

常见层级：

~/.codex/AGENTS.md
仓库根目录/AGENTS.md
子目录/AGENTS.override.md

全局文件放个人通用习惯，根目录文件放项目规则，子目录覆盖文件放某个服务的特殊要求。AGENTS.md 应简短、明确、可执行；长规范放在 docs/，再告诉 Codex 何时阅读。

第三部分：提示词技巧

九、稳定的提示词结构

OpenAI 官方建议围绕 目标、上下文、输出、边界 组织提示词。编程任务再加一项 验证：

目标：最终要实现什么行为。
上下文：相关路径、入口、日志、复现步骤和现有约定。
输出：需要分析、计划、代码、测试还是文档。
边界：不能改什么，兼容、依赖与安全要求是什么。
验证：必须运行哪些测试、构建或复现步骤。

差的提示词：

帮我优化一下这个项目。

更好的提示词：

目标：把用户列表接口的 P95 响应时间从约 900ms 降到 400ms 以内。

上下文：入口在 `internal/user/handler.go`，查询逻辑在
`internal/user/repository.go`。先阅读现有 benchmark 和数据库索引，
复现瓶颈后再修改。

边界：保持 HTTP 响应结构不变；不引入新缓存服务；不修改无关模块。

验证：运行单元测试、接口测试和 benchmark，报告修改前后结果。
环境不足时明确写“未验证”，不能虚构数据。

十、四套可直接复制的提示词

1. 接手陌生项目

先不要修改代码。系统阅读仓库并输出：
1. 项目用途、技术栈和模块边界；
2. 启动、测试、构建和部署命令；
3. 主要请求链路与数据流；
4. 配置、数据库、鉴权和外部服务的位置；
5. 最值得优先处理的风险。
每条结论引用具体文件路径。无法确认的内容标记为“待验证”，不要猜测。

2. 修复 Bug

修复问题：<问题描述>。
复现步骤：<步骤与日志>。
期望结果：<正确行为>。

先复现并定位根因，再做最小范围修复。不得通过删除校验、吞掉异常、
硬编码返回值或降低测试标准绕过问题。保留现有公开接口。

完成后添加覆盖根因的回归测试，重新执行复现步骤，并运行最相关的
lint、测试和构建。列出实际执行的命令与结果，未运行的验证写“未运行”。

3. 实现完整功能

实现功能：<功能名称>。
用户场景：<谁在什么情况下使用>。
验收标准：<逐条列出>。

先搜索仓库中的相似功能、公共组件和现有约定，给出实施计划后再修改。
同时完成后端、前端、类型、测试和文档之间的连接，不能只做页面或只做接口。
未经必要性论证不要新增依赖。完成后按验收标准逐条自检并运行构建与测试。

4. 代码审查

审查当前分支相对 `<基准分支>` 的变更。
重点检查功能正确性、边界条件、并发与事务、权限校验、输入验证、
敏感信息、数据兼容、测试覆盖和前后端是否真实连接。

只报告有证据的问题。每项给出文件或符号位置、触发条件、影响和修复建议，
按严重程度排序。不要为了凑数量报告纯风格偏好。

十一、避免 Codex “做一半”

把以下要求写进任务中，效果通常比单纯加长提示词更好：

先搜索现有实现，再决定方案。
只修改与任务直接相关的文件。
逐条对应验收标准，不得只完成前端或后端的一侧。
列出实际运行过的命令和结果。
没有运行的测试必须写“未运行”，不得推测为通过。
发现额外问题先记录，不要擅自扩大重构范围。

大任务采用这一流程：

调研现状 → 输出计划 → 确认边界 → 分阶段实现 → 每阶段验证 → 最终审查

真正决定结果质量的不是提示词有多长，而是任务是否具备明确目标、准确上下文、修改边界和可执行的验收标准。

十二、安全工作流

  1. 在 Git 仓库中工作，开始前检查 git status；
  2. 大任务建立独立分支或 worktree；
  3. 首轮只读分析，先理解项目和计划；
  4. 只开放完成当前任务所需的权限；
  5. 禁止访问生产系统、真实密钥和不可逆操作；
  6. 先运行最小相关测试，再扩大到完整测试；
  7. 人工检查 git diff，重点看权限、迁移、依赖和配置；
  8. 重要代码仍经过正常代码审查和发布流程。

Codex 是能够执行命令和修改文件的 Agent，不只是代码补全工具。能力越强，越需要清晰的权限边界和验收标准。

十三、常见问题

安装后找不到 codex

重新打开终端，并用 which codex 或 where.exe codex 检查实际路径。若曾用多种方式安装，先清理重复版本。

远程服务器无法登录

codex login --device-auth

不要把本地认证文件发送到服务器或分享给他人。

WSL 中项目读取很慢

把仓库放到 ~/code 等 Linux 目录，并在 WSL 远程窗口中运行编辑器和 Codex，避免频繁跨 /mnt/c/ 读写。

Codex 说完成了，但项目跑不起来

在提示词里明确测试命令和验收步骤，要求区分“已验证、验证失败、环境不足未验证”。最终仍要人工检查 Diff 和关键业务流程。

图片 CDN 说明

本文界面图来自 openai/codex 官方仓库，平台图标来自 Devicon，均优先通过 jsDelivr 引用，以减少对 GitHub Raw 等海外静态资源域名的直接依赖。大陆不同运营商和网络环境仍可能波动，无法保证所有地区始终可访问。

图片 CDN 的可访问性与 Codex 服务本身的支持地区、账号条件和网络要求是两件事。使用服务时应遵守 OpenAI 当前政策、服务条款与所在地法律法规。

官方资料