ChatGPT中文镜像站导航

Appearance

Codex 使用教程 2026：从安装、登录到第一次改代码 ​

更新日期：2026 年 10 月 24 日。本文依据 OpenAI Codex 官方 GitHub 文档、2026 年 10 月本机 CLI 帮助整理。命令和配置会随版本变化，遇到差异时先运行 codex --version 与 codex doctor。

Codex 是 OpenAI 的编程智能体，不是一个“自动替你把所有代码写完”的按钮。 它会阅读工作区、运行命令、修改文件并验证结果；你负责给出目标、约束和验收标准。新手最稳妥的上手路径是：先备份或提交现有代码，再安装 Codex CLI，用 ChatGPT 账号登录，在一个 Git 项目里完成一次小改动，最后检查差异和测试结果。

如果你刚开始搜索“Codex 使用教程”，先不要同时安装五六个工具。把 Codex CLI 当作主线，熟悉后再选择 IDE 扩展、桌面 App 或 Codex Web。下面这条路径覆盖了大多数第一次使用会遇到的问题。

先分清：Codex CLI、IDE、桌面版和网页版 ​

使用方式适合谁主要特点开始方式
Codex CLI熟悉终端、希望直接操作项目的开发者在本地工作区运行，可用交互模式、脚本和代码审查安装后运行 codex
IDE 扩展主要在 VS Code、Cursor 或 Windsurf 中工作的人在编辑器里查看上下文、修改与审查从 IDE 扩展市场安装
桌面 App希望有独立窗口和更完整界面的人管理本地会话、项目与任务运行 codex app 或安装桌面版
Codex Web / Cloud想让任务在云端环境运行的人适合任务委派、拉取结果与异步处理打开 Codex 官方入口

四种入口共享“编程智能体”的基本工作方式，但安装方式、可用功能和权限模型并不完全相同。第三方中文聊天网站即使能回答编程问题，也不等于支持 Codex CLI、工作区操作或账号登录。选择入口时先看你的工作流，不要只看宣传页上的模型名称。

使用前的 5 分钟准备 ​

Codex 会读写当前项目，所以第一次使用前先做三件事：

  1. 确认项目有版本控制。 运行 git status；有未提交改动时，先提交或建立临时分支。不要在没有备份的生产目录里让智能体随意修改。
  2. 明确目标与验收。 例如“为登录表单增加邮箱格式校验，并补充现有测试”，比“优化登录”更容易检查。
  3. 准备可执行的验证命令。 常见的是 npm test、pnpm lint、pytest 或 cargo test。如果没有测试，也要明确要检查哪些页面和路径。

官方安装说明列出的系统要求是 macOS 12+、Ubuntu 20.04+/Debian 10+，Windows 11 需要 WSL2；最低 4 GB 内存，推荐 8 GB。实际能否运行还取决于模型服务、网络和项目工具链。

安装 Codex CLI ​

macOS 或 Linux 的官方独立安装命令：

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

Windows 11 在 PowerShell 中运行：

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

也可以使用 npm 或 Homebrew：

bash
npm install -g @openai/codex
brew install --cask codex

安装完成后检查版本：

bash
codex --version

不要把网上流传的“固定版本安装包”当作长期方案。先使用当前官方安装入口，出问题再运行 codex doctor 获取安装、配置、认证和运行环境信息。完整的安装、更新和命令说明见 Codex CLI 使用教程。

登录 ChatGPT 账号 ​

进入终端后运行：

bash
codex

在登录界面选择 Sign in with ChatGPT，按浏览器提示授权。官方推荐使用具备 Codex 权益的 ChatGPT 套餐；不同套餐的额度与功能由 OpenAI 当前规则决定。你也可以使用 API Key，但它需要额外配置，按量计费方式也与 ChatGPT 套餐不同。

检查当前登录状态：

bash
codex login status

如果浏览器回调没有成功，先确认终端显示的登录流程，再尝试设备授权：

bash
codex login --device-auth

不要把账号 Cookie、访问令牌或 API Key 粘贴到文章评论区、聊天截图或仓库文件里。登录、API Key 与第三方模型接口的边界见 Codex 配置与安全指南 和 Codex 登录失败排查。

第一次修改项目：从只读检查开始 ​

进入项目根目录，然后启动交互模式：

bash
cd /path/to/your-project
codex

第一轮可以只让 Codex 理解项目，不修改文件：

text
请先只读检查这个项目：说明技术栈、主要入口、测试和构建命令。
不要修改文件。列出你判断有风险或不确定的地方。

确认它的理解基本正确后，再提出一个范围明确的改动：

text
修复搜索框在空字符串时仍提交的问题。
要求：
1. 保持现有 API 不变；
2. 增加输入空白判断；
3. 补充覆盖空字符串的测试；
4. 完成后运行相关测试并汇报结果。

Codex 可能会读取文件、提出计划、请求执行命令或展示差异。你要关注三件事：它改了什么、为什么改、验证是否真的通过。不要只看“已完成”这句话。

怎样提问，结果才稳定 ​

高质量任务通常包含以下信息：

  • 目标：要改变的用户行为或系统结果。
  • 边界：哪些文件、接口、依赖不能动。
  • 验收：测试命令、复现步骤或页面表现。
  • 风险：迁移兼容、性能、隐私、部署等限制。
  • 输出：只要分析，还是直接修改并验证。

一个可复用的模板：

text
目标：<用户可观察到的结果>
范围：<允许修改的目录或模块>
限制：<不能改的接口、依赖或行为>
验证：<必须运行的命令和预期结果>
交付：完成后列出改动、验证结果与剩余风险。

任务较大时先让 Codex 给出计划并检查，再批准实施。长任务中断后，可以用 codex resume --last 继续最近会话；需要非交互执行或接入脚本时，使用 codex exec。这些命令的区别放在 CLI 专题中。

看懂权限：沙箱与审批 ​

Codex CLI 的沙箱模式主要有三种：

模式允许的范围适合场景
read-only只读检查，不应修改工作区熟悉项目、代码审查、风险调查
workspace-write可写当前工作区，边界更受控日常开发与大多数修改任务
danger-full-access绕过工作区和系统限制仅用于已由外部环境严格隔离的场景

审批参数包括 on-request 与 never。never 表示不再向人请求批准，并不代表系统没有风险；把“不弹审批”当成“绝对安全”会制造误判。普通开发任务应先保持沙箱和必要审批，只给任务真正需要的目录与网络权限。

可以在启动时明确参数：

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

不要在教程或自动化脚本里默认使用 --dangerously-bypass-approvals-and-sandbox。这个开关是为已经处于外部隔离环境中的特殊运行准备的高风险选项。

修改后怎样验收 ​

一次可靠的交付至少包括：

bash
git status --short
git diff
npm test

把测试命令换成项目实际使用的命令。验收时还要确认：

  • 未提交文件里没有密钥、临时日志和构建产物；
  • 依赖锁文件只发生与本次任务有关的改变；
  • 测试覆盖了故障复现路径；
  • 部署或数据迁移需要额外步骤时已经明确列出；
  • 没有把“没运行测试”写成“测试通过”。

代码审查也可以单独交给 Codex：

bash
codex review --uncommitted

它适合在提交前找回归、遗漏测试和安全问题，但审查输出仍要由你结合项目上下文判断。尤其是删除数据、修改权限、发布生产环境和处理外部消息这类动作，必须按组织现有流程确认。

让 Codex 记住项目规则 ​

如果每次都要重复“使用 pnpm”“不要改生成文件”“提交前运行什么测试”，应把这些规则写进仓库根目录的 AGENTS.md。Codex 会在工作区中读取适用的项目说明，子目录规则可以更具体地约束该目录。

一个最小模板：

markdown
# 项目规则

- 使用 pnpm，不要改用 npm。
- 修改代码后运行 pnpm test 和 pnpm lint。
- 不要编辑 dist/、coverage/ 或自动生成文件。
- 数据库迁移必须保留向后兼容，并在交付中说明回滚方式。
- 不提交密钥、个人数据和真实生产配置。

规则应该写成可验证的要求，而不是“代码要优雅”这类无法判断的口号。位置、嵌套规则、覆盖顺序与完整模板见 Codex AGENTS.md 教程。

需要外部数据时再用 MCP ​

MCP（Model Context Protocol）让 Codex 通过受控接口连接文档、数据库、项目管理工具或其他服务。只有任务确实需要外部数据时才添加，不要为了“配置更多”安装一堆来源不明的服务器。

常用命令：

bash
codex mcp list
codex mcp add docs --url https://example.com/mcp
codex mcp login docs

添加前要确认来源、权限、数据处理方式和可撤销性。涉及账号授权时优先使用 OAuth 或环境变量，不要硬编码密钥。具体流程和安全边界见 Codex MCP 配置教程。

常见问题：为什么它没有按预期工作 ​

Codex 看不到我的项目文件 ​

确认是在项目根目录启动，且文件位于当前工作区。需要额外目录时，使用 --add-dir 并理解额外目录的写入权限。大仓库还要检查忽略规则与项目说明是否让智能体遗漏了关键文件。

登录成功但请求失败 ​

先运行：

bash
codex doctor --summary

再检查当前账号、网络、代理、组织策略、套餐权益与版本。不要把浏览器能登录 ChatGPT 自动等同于 Codex 本地进程一定拥有可用认证。

它改了太多文件 ​

停止继续修改，检查 git diff，撤销无关变更后再重新发起。任务描述里增加允许修改的目录、禁止改动的文件和明确验收条件。不要靠放宽权限解决任务边界不清的问题。

没有测试项目还能用吗 ​

可以，但要自己建立验收方式，例如启动页面、复现步骤、截图检查或最小示例。没有自动测试时，交付应明确写“未运行自动测试”及手动检查了什么。

第三方平台能代替 Codex 吗 ​

网页聊天工具可以帮你写代码、解释错误和设计方案，但只有具备相应本地工具、工作区权限和账号支持的客户端才能执行 Codex 的项目操作。不要把普通 AI 对话网站宣传成 Codex 官方客户端。国内网络与第三方 API 的边界，请看 Codex 登录失败与国内使用排查。

建议的进阶阅读顺序 ​

  1. Codex CLI 教程：安装、命令与非交互执行
  2. Codex AGENTS.md 模板与最佳实践
  3. Codex 配置、沙箱、审批与 API Key 安全
  4. Codex MCP 添加、登录与安全使用
  5. Codex 登录失败、网络与国内使用排查

官方来源 ​

免责声明：本站仅提供信息导航服务，不对第三方站点内容负责

© 2024-2026 ChatGPT中文镜像站导航