Codex 使用指南：从下载、安装到高效上手

Codex 使用指南全解

更新时间：2026-06-17 适用对象：想系统了解并开始使用 Codex 的开发者、产品经理、测试、独立开发者

一、Codex 是什么

Codex 是 OpenAI 提供的编码代理（coding agent）。它不只是“代码补全”工具，而是一个可以理解项目、修改文件、执行命令、调用工具、查看结果、做代码审查、辅助调试，甚至在部分场景下操作浏览器或桌面应用的工作代理。

你可以把它理解成：

• 一个能直接参与软件开发流程的 AI 工程助手

• 一个同时支持本地开发、IDE 内协作、终端工作流和云端委托的编码代理

• 一个适合用于“读代码、改代码、跑命令、查资料、提 PR、做 Review”的开发搭档

官方文档当前把 Codex 分成几种主要使用方式：

• Codex App：桌面端工作中枢，适合并行任务、工作树、自动化、Git 操作

• Codex CLI：终端模式，适合开发者日常编码和脚本化工作流

• Codex IDE Extension：集成在 VS Code、Cursor、Windsurf、JetBrains 等编辑器中

• Codex Web / Cloud：把任务委托到云端后台执行，适合长任务、并行任务、远程环境任务

二、使用前先搞清楚：你该选哪一种入口

如果你是第一次用，建议这样选：

1. 想最快上手：先用 Codex App

适合你：

• 希望有可视化界面

• 想同时开多个任务线程

• 想方便看计划、Diff、Review、Git 结果

• 偶尔还想让 Codex 接管浏览器或桌面应用

2. 想最贴近工程师习惯：用 Codex CLI

适合你：

• 常驻终端开发

• 喜欢直接在仓库目录里工作

• 想把 Codex 纳入脚本、自动化或 CI 流程

3. 想边写代码边问：用 Codex IDE Extension

适合你：

• 主要在 VS Code / Cursor / Windsurf / JetBrains 里写代码

• 希望直接利用打开的文件、选中的代码、编辑器上下文

• 希望在 IDE 内完成聊天、修改、预览和云端委托

4. 想把任务扔后台跑：用 Codex Web

适合你：

• 想把大任务放云端执行

• 希望同时跑多个任务

• 想直接连 GitHub 仓库，让 Codex 在云端做修改并产出 PR

三、下载与安装

3.1 安装 Codex App（桌面端）

官方说明中，Codex App 当前支持：

• macOS

• Windows

Linux 目前不是正式桌面端下载入口，官方提供的是“获取通知”方式。

如果你是 Mac 用户，需要注意：

• Apple Silicon 芯片机型下载 Apple Silicon 版本

• Intel Mac 下载 Intel 版本

App 的基本安装流程：

1. 下载对应平台安装包

2. 完成安装

3. 打开 Codex

4. 使用 ChatGPT 账号 或 OpenAI API Key 登录

5. 选择一个项目目录开始工作

如果你用的是 ChatGPT 订阅，当前官方文档说明 ChatGPT Plus、Pro、Business、Edu、Enterprise 都包含 Codex。

3.2 安装 Codex CLI（终端版）

如果你更偏好命令行，CLI 是最值得装的版本。

官方给出的安装方式如下。

macOS / Linux

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

Windows

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

无交互安装

适合自动化环境或脚本安装：

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

$env:CODEX_NON_INTERACTIVE=1; irm https://chatgpt.com/codex/install.ps1 | iex

其他安装方式

官方还提供：

npm install -g @openai/codex

以及 Homebrew 安装：

brew install --cask codex

CLI 当前支持：

• macOS

• Windows

• Linux

3.3 安装 IDE 插件

如果你主要在编辑器里工作，可以安装 Codex IDE 插件。

官方说明当前支持：

• VS Code

• Cursor

• Windsurf

• 其他兼容 VS Code 的编辑器

• JetBrains IDEs（如 IntelliJ、PyCharm、WebStorm、Rider）

安装方式：

1. 从 Visual Studio Code Marketplace 安装

2. 或下载对应 IDE 的插件版本

3. 安装完成后，在编辑器侧边栏中打开 Codex

4. 使用 ChatGPT 账号 或 API Key 登录

如果是 VS Code，Codex 默认出现在右侧边栏。 如果是 Cursor，由于活动栏布局原因，你可能需要手动把 Codex 图标固定或拖到右侧边栏。

四、登录与权限：第一次使用最容易卡住的地方

Codex 当前支持两种主要登录方式：

• 使用 ChatGPT 登录

• 使用 OpenAI API Key 登录

它们的区别要先搞清楚。

4.1 使用 ChatGPT 登录

适合：

• 日常个人使用

• 使用桌面端 App

• 使用云端 Codex

• 使用 IDE 插件但不想单独管理 API 账单

特点：

• CLI 默认优先走 ChatGPT 登录

• 浏览器会弹出登录流程

• 登录后，权限与一些数据策略会跟随你的 ChatGPT 工作区策略

4.2 使用 API Key 登录

适合：

• 本地工作流

• 脚本化调用

• CI/CD

• 更明确地按 API 使用量计费

特点：

• 费用按 OpenAI Platform API 标准费率走

• 本地 CLI / IDE 工作流支持良好

• 一些依赖 ChatGPT 工作区或云能力的功能可能不可用或受限

4.3 一个重要结论

如果你要用 Codex Cloud / Web，官方明确说明必须使用 ChatGPT 登录。 如果你只是想在本地 CLI 或 IDE 里改代码，那么 API Key 也完全可以。

五、第一次启动后，建议你这样完成初始化

5.1 CLI 的最小上手流程

进入你的项目目录：

cd /path/to/your/project
codex

第一次进入后，你通常会经历：

1. 登录

2. 让 Codex 读取当前目录

3. 给出第一条任务指令

例如你可以直接输入：

先阅读这个项目，告诉我目录结构、技术栈和启动方式

或者：

请帮我找出这个仓库里最值得优先修复的 3 个问题

再或者：

只做高置信度修改，修复当前项目中的构建错误

5.2 App 的最小上手流程

桌面端首次使用建议这么走：

1. 打开 App

2. 登录

3. 选择项目目录

4. 先用 Local 模式跑第一个任务

5. 等熟悉后再尝试 Worktree 或 Cloud

App 中常见三种模式：

• Local：直接在当前项目目录工作

• Worktree：为并行任务创建 Git worktree，隔离改动

• Cloud：在远端环境里执行任务

如果你当前就是在本机仓库里迭代功能，建议默认先用 Local。 如果你经常同时做多个需求、多个修复分支，Worktree 非常值得用。

5.3 IDE 插件的最小上手流程

插件安装好以后，不要一上来就丢一个泛化问题。 最好的使用方法是让 Codex 利用编辑器上下文。

比如：

基于 @api.ts 和 @user_service.ts，帮我补一个获取用户详情的接口封装

或者先选中一段代码，再问：

解释这段代码的核心逻辑，并指出潜在 bug

IDE 模式最大的优势就是：

• 能利用你当前打开的文件

• 能利用你当前选中的代码

• 能通过 @文件名 的方式给上下文

这会明显提升结果质量，也能让提示词更短。

六、常用功能详解

下面是最值得掌握的一批 Codex 功能。

6.1 读代码、讲代码、梳理项目

这是最适合用 Codex 的第一个场景。

常用提示词：

先不要改代码，帮我梳理这个仓库的模块结构、依赖关系和启动方式

阅读这个目录，列出最关键的入口文件和调用链

解释这个服务的请求链路，从 controller 到 repository

适合场景：

• 接手新项目

• 看别人的代码

• 回忆久没碰的老仓库

• 做技术文档梳理

6.2 修改代码与执行命令

Codex CLI 和 IDE 插件都支持真正进入工作流：

• 读取仓库

• 修改文件

• 执行命令

• 解释结果

• 继续迭代

CLI 交互模式下，官方描述很明确：它可以读取仓库、修改文件、运行命令，并在你协作迭代时显示计划和差异。

你可以这样用：

修复当前项目的类型错误，只改必要代码，不要顺手重构

先分析为什么单元测试失败，再给出最小修复方案并执行

新增一个登录页，UI 尽量复用现有组件，不要引入新依赖

6.3 审批模式与权限控制

这是 Codex 很关键的一个能力：你可以控制它“能自动做到什么程度”。

在 IDE 文档里，官方给出的典型模式有：

• Chat

• Agent

• Agent (Full Access)

含义可以简单理解为：

• Chat：更偏问答和规划，不急着动代码

• Agent：可以在工作目录里自动读文件、改文件、跑命令，但越界行为仍需要批准

• Agent (Full Access)：更高自治度，包含更宽的访问权限，需要谨慎使用

CLI 里也可以通过 /permissions 动态切换。

如果你是第一次用，建议：

1. 先从保守模式开始

2. 先看它怎么计划

3. 确认它改动风格可靠后，再放宽权限

6.4 Slash Commands：CLI 里最实用的一组命令

如果你用的是 CLI，下面几条非常常用。

/model

切换当前线程使用的模型。

适合：

• 当前任务变复杂，需要更强推理

• 当前任务只是小修小改，想更快一点

/permissions

动态调整权限与审批方式。

适合：

• 先保守，后放开

• 中途切到只读模式做评审

/status

查看当前会话摘要。

能看到：

• 当前模型

• 审批策略

• 可写目录

• Token 使用情况

/plan

把当前对话切换到规划模式。

适合：

• 需求还不明确

• 先想方案，再决定是否改代码

• 做迁移、重构、拆模块这类多步骤工作

/theme

切换 CLI 主题，属于舒适度功能，但常用。

/init

帮你初始化 AGENTS.md 模板。

适合：

• 给仓库建立长期规则

• 让 Codex 以后每次进来都知道“这个项目该怎么做”

/mcp

查看当前会话可用的 MCP 工具。

适合：

• 检查某个连接器、插件、工具是否已经接入

6.5 AGENTS.md：把你的工作规则长期交给 Codex

这是非常值得掌握的能力。

你可以在全局或项目里写 AGENTS.md，告诉 Codex：

• 改完 JavaScript 必须跑 npm test

• 安装依赖优先用 pnpm

• 改公共接口要同步文档

• 未经确认不要新增生产依赖

全局文件路径示例：

~/.codex/AGENTS.md

项目级文件则放在仓库目录中：

AGENTS.md

一个很实用的思路是：

• 全局 AGENTS.md 放个人工作习惯

• 仓库 AGENTS.md 放项目规范

• 子目录 AGENTS.md 或 override 放局部服务规则

这样 Codex 每次进入项目时，都会更像“懂你团队规范的人”。

6.6 config.toml：更偏底层的行为配置

Codex 的用户级配置文件在：

~/.codex/config.toml

项目级配置可以放在：

.codex/config.toml

常见用途：

• 配默认权限

• 配模型默认值

• 配状态栏/标题栏显示

• 配 profile

• 配规则、hooks、MCP、插件等

一个很重要的点是：

• 用户默认配置在 ~/.codex/config.toml

• 项目覆盖配置在 .codex/config.toml

• 只有在你“信任项目”时，项目级 .codex/ 层才会生效

这意味着它既方便共享项目规范，也保留了安全边界。

6.7 Web Search：让 Codex 自己查资料

CLI 特性页说明，Codex 内置了第一方 Web Search 工具。

它的价值在于：

• 查官方文档

• 查库版本

• 查最新变更

• 在需要时补充外部信息

官方当前说明里，CLI 默认启用的是缓存搜索结果；在更高权限模式下，可以切换到实时网络搜索。

这对下面几类任务很有帮助：

• 你让它升级依赖

• 你让它对比官方最新文档

• 你让它确认某个 API 是否已经变化

6.8 云端委托与后台任务

如果你不想让本机一直跑长任务，Codex Web / Cloud 很有价值。

它的典型流程是：

1. 打开 chatgpt.com/codex

2. 连接 GitHub

3. 选择仓库或环境

4. 把任务委托给云端 Codex

5. 等它后台完成，再回来 Review

适合场景：

• 大规模重构

• 长时间构建

• 批量代码修复

• 并行处理多个任务

官方文档明确提到，Codex Cloud 支持在后台并行处理任务。

6.9 App 里的高阶功能

Codex App 不是简单的聊天壳子，它更像一个开发工作台。官方概览页列出的高价值功能包括：

• 多线程并行处理不同项目或不同任务

• Worktrees 隔离并行改动

• Review 查看差异、处理反馈、提交和推送

• 每个线程直接跑终端命令

• Automations 做定时任务或线程唤醒

• Computer Use 直接操作 macOS / Windows 应用

• Chrome extension 处理带登录态的网站任务

• In-app browser 查看本地页面、预览页面和评论页面

• Image generation 在开发流程中顺手生成或编辑图片

• Plugins / Skills / MCP 扩展能力边界

如果你已经把 Codex 当成一个“开发代理”，那 App 往往是体验最完整的入口。

七、App、CLI、IDE、Web 分别适合做什么

7.1 App 适合

• 多线程并行任务

• 代码修改 + Review + Git 操作

• 本地与云端来回切换

• 带 GUI 的桌面协作

• 需要 Computer Use 或 Chrome extension

7.2 CLI 适合

• 终端党开发者

• 快速读仓库、修 bug、跑命令

• 脚本化流程

• 自动化工作流

• 通过 codex exec 接入现有 shell 脚本

7.3 IDE 插件适合

• 边看文件边提问

• 基于选中代码直接修改

• 通过 @文件 精准给上下文

• 不离开编辑器完成日常编码协作

7.4 Web / Cloud 适合

• 长任务

• 后台并行任务

• GitHub 仓库级任务

• 让 Codex 独立执行并最终回收结果

八、几个非常实用的使用姿势

8.1 先让它“只分析”，不要一上来就改

错误做法：

把这个项目重构一下

更好的做法：

先不要改代码。请阅读这个项目，找出最需要重构的 3 个点，解释原因，并给出最小风险方案。

这样你会先得到：

• 问题识别

• 风险判断

• 改造顺序

然后再决定是否执行。

8.2 把范围写清楚

比如：

修复当前登录接口的异常处理，只改 service 和 controller，不改数据库层，不新增依赖。

这种提示会比“修复登录问题”好很多。

8.3 明确改动原则

可以直接写：

• 只做最小修改

• 不要顺手重构

• 不要改业务逻辑，只解决构建错误

• 改完请跑测试

• 如果不确定，先给方案不要直接动手

8.4 善用 @文件 和选中代码

这是 IDE 插件最容易被低估的能力。

与其说：

帮我改一下用户页

不如说：

参考 @UserCard.tsx 和 @user_api.ts，给 @UserProfile.tsx 增加“最近活跃时间”展示，样式保持现有设计系统一致。

8.5 给它长期规则，不要每次重复说

这就是 AGENTS.md 的价值。

重复说十次：

• 改完必须跑测试

• 不要加新依赖

• 优先用现有组件

不如写进：

AGENTS.md

九、一些你很快就会遇到的常见问题

9.1 为什么有时候它会停下来问我要不要继续

因为你当前的审批模式、可写目录、网络权限或系统权限不允许它直接执行下一步动作。

这是正常的，不是坏事。 Codex 的设计目标之一就是：在高效和可控之间给你一个清晰边界。

9.2 为什么 App 里的浏览器和你自己平时登录的网站不一样

官方文档明确说明：

• In-app browser 不支持你日常浏览器的登录态、Cookie、扩展和现有标签页

所以：

• 预览本地页面，用 In-app browser 很合适

• 带登录态的网站操作，更适合 Chrome extension

• 如果是桌面应用或系统级 GUI，更适合 Computer Use

9.3 为什么 API Key 登录后有些功能不完整

因为某些能力依赖 ChatGPT 工作区、云端任务或相关工作区权限。 如果你需要完整的 App / Cloud / 工作区能力，优先使用 ChatGPT 登录。

9.4 为什么我改了 .codex/config.toml 没生效

要先确认几件事：

1. 你改的是用户级还是项目级配置

2. 项目是否处于“可信任”状态

3. 是否被 CLI 参数或更高优先级配置覆盖

4. 是否需要重开新会话

CLI 里可以用：

/debug-config

来检查配置层级和生效来源。

十、一个推荐的新手学习路径

如果你想真正把 Codex 用起来，不要只停留在“偶尔问一句”。

推荐顺序如下：

第 1 阶段：先用 CLI 学会基本协作

目标：

• 会安装

• 会登录

• 会在仓库里发任务

• 会看它的计划和输出

建议练习：

• 读项目结构

• 找 bug

• 修一处小问题

第 2 阶段：把 AGENTS.md 和 config.toml 用起来

目标：

• 让 Codex 知道你的长期规则

• 让行为更贴近你的开发习惯

第 3 阶段：接入 IDE 插件

目标：

• 学会 @文件

• 学会用选中代码做局部修改

• 学会切换模型、推理力度、审批模式

第 4 阶段：上手 App 和 Cloud

目标：

• 多线程并行做任务

• 用 Worktree 隔离改动

• 把长任务委托到云端

第 5 阶段：尝试更高级的能力

包括：

• Web Search

• Automations

• MCP

• Plugins

• Computer Use

• Chrome extension

十一、我建议你一开始就记住的几个结论

1. Codex 最强的地方不是“回答问题”，而是“进入真实工作流”。

2. 第一次使用时，先保守授权，先看计划，再逐步放权。

3. CLI + AGENTS.md + IDE 插件 是大多数开发者最实用的组合。

4. 复杂任务别急着让它直接改，先让它分析、规划、列风险。

5. 如果你需要并行处理和后台执行，App 和 Cloud 的价值会非常明显。

6. 如果你希望它越来越像你的团队成员，就要把规则写进 AGENTS.md 和配置文件，而不是每次重复口述。

十二、推荐你立刻做的 3 个动作

动作 1：先装 CLI

装好后在你的项目目录里运行：

codex

然后输入：

先不要修改代码，帮我读懂这个项目，输出技术栈、目录结构、启动方式和最值得关注的 5 个文件。

动作 2：建立你的全局 AGENTS.md

比如写：

# Working agreements
​
- 改完代码后优先运行对应测试
- 不要无故新增依赖
- 优先最小修改，不要顺手重构
- 如果要改动超过 3 个文件，先给计划

动作 3：在 IDE 里试一次 @文件 工作流

例如：

参考 @api.ts 和 @types.ts，帮我补全 @user_service.ts 中缺失的用户详情接口，并补上错误处理。

参考资料

本文基于 2026-06-17 查阅的 OpenAI 官方 Codex 文档整理，主要包括：

• Codex 总览：https://developers.openai.com/codex

• Codex Quickstart：https://developers.openai.com/codex/quickstart

• Codex App：https://developers.openai.com/codex/app

• Codex App Features：https://developers.openai.com/codex/app/features

• Codex App Settings：https://developers.openai.com/codex/app/settings

• Codex CLI：https://developers.openai.com/codex/cli

• Codex CLI Features：https://developers.openai.com/codex/cli/features

• Codex CLI Slash Commands：https://developers.openai.com/codex/cli/slash-commands

• Codex IDE Extension：https://developers.openai.com/codex/ide

• Codex IDE Features：https://developers.openai.com/codex/ide/features

• Authentication：https://developers.openai.com/codex/auth

• Config Basics：https://developers.openai.com/codex/config-basic

• Permissions：https://developers.openai.com/codex/permissions

• AGENTS.md 指南：https://developers.openai.com/codex/guides/agents-md

• Codex Web / Cloud：https://developers.openai.com/codex/cloud