7天精通 Codex：终端 AI 编程助手实操教程手册

Codex（社区常写作 CodeX）是 OpenAI 推出的 AI 编程智能体。它不只是一个"代码补全器"，而是一个住在你终端里的 AI 程序员：你给它一句话需求，它自己读代码、写代码、跑测试、修 bug，直到任务完成。

这篇手册用 7 天时间，带你从安装到进阶，最后能独立用 Codex 跑通"需求 → 开发 → 测试 → 提交"的完整闭环。

写在前面：Codex 的四种形态

在开始之前，先搞清楚 Codex 家族，避免混淆：

• Codex CLI：开源终端工具，本手册的主角，免费可装（GitHub: openai/codex，Apache-2.0 协议）
• Codex App：桌面应用，聊天界面 + 可打开本地仓库（codex app 启动）
• Codex Web：云端智能体，访问 chatgpt.com/codex，能直接创建 GitHub PR
• Codex IDE 扩展：VS Code、Cursor、Windsurf 里以插件形式使用

本手册第 1-6 天聚焦 CLI，第 7 天带你看完整个生态。

你需要准备什么：

• 一台电脑（macOS 12+ / Ubuntu 20.04+ / Windows 11 建议用 WSL2）
• 一个 ChatGPT 账号（Plus / Pro / Business / Edu / Enterprise 套餐均包含 Codex 额度；也可以改用 API Key 计费）
• 一颗愿意"把活交给 AI 干"的心

7 天路线图

第1天：安装与登录

1.1 安装

macOS / Linux 一条命令：

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

Windows（PowerShell）：

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

包管理器方式（任选其一）：

# npm 方式（Node 用户最熟）npm install -g @openai/codex# Homebrew 方式（macOS）brew install --cask codex

装完验证：

codex --help

能看到命令列表就说明装好了。

1.2 登录

运行 codex，首次启动会让你选择登录方式：

1. Sign in with ChatGPT（推荐）：浏览器弹出授权，登录你的 ChatGPT 账号即可。Codex 的用量包含在你的 ChatGPT 套餐里，Plus 起步就能用。
2. API Key 方式：适合没有 ChatGPT 订阅、或者想按量计费的用户。先设置环境变量：

export OPENAI_API_KEY=sk-你的密钥codex login --api-key

小提示：国内网络环境下如果登录卡住，大概率是网络问题——换个稳定的网络环境，或者参考第6天"接入第三方模型"的配置。

1.3 第一个对话

codex

进入交互界面后，输入：

你好，介绍一下你自己，然后告诉我这个目录里有什么文件。

它会先展示自己的"工作方式"，然后真的去读你的目录。第一次用，建议先 Ctrl+C 熟悉一下中断操作，再输入 /quit 退出。

今日小结： 装好、登录、跑通第一句对话。就这些。

第2天：交互模式实战

Codex 的交互模式（REPL）是日常最常用的形态——你在终端里跟它聊天，它边聊边干活。

2.1 把需求说清楚

Codex 不是搜索引擎，它是执行者。一句"帮我写个脚本"和"帮我写个脚本，输入数字 n 输出斐波那契第 n 项，用命令行参数接收，顺便写个测试"，效果天差地别。

好需求三要素：目标 + 验收标准 + 约束。

试试这个经典任务：

在当前目录创建一个 Python 脚本 fib.py：1. 命令行传入数字 n，输出斐波那契数列第 n 项2. 用 pytest 写 3 个测试用例3. 写完运行测试，确认全部通过

你会看到 Codex 的完整工作流：

1. 读取目录、检查环境
2. 创建 fib.py 和测试文件——每一次文件写入前都会先展示 diff 等你批准
3. 自动运行 pytest
4. 如果测试挂了，它会自己看报错、改代码、重跑

你只需要在它每次请求批准时输入 y（同意）或 n（拒绝）。

2.2 交互模式必会操作

• /help：查看所有可用命令
• /model：切换模型（后面第6天细讲）
• /quit：退出
• Shift+Tab：循环切换沙箱模式（read-only → workspace-write → danger-full-access），当前模式会显示在界面上
• 随时 Ctrl+C：打断它正在做的事，重新下指令

2.3 今日练习

在你自己的项目里挑一个小 bug（或者故意埋一个），然后对 Codex 说：

帮我定位并修复最近一次提交引入的 bug，修复后跑一遍测试确认没破坏其他功能。

观察它是怎么定位问题、怎么改、怎么验证的。这个"发现问题 → 修改 → 验证"的闭环，就是 Codex 的核心价值。

第3天：exec 非交互模式——把 Codex 变成你的自动化流水线

交互模式适合"人机协作"，而 exec 模式适合"下完指令就撒手"——非常适合脚本化、批量任务和 CI。

3.1 基础用法

codex exec"给当前项目写一个 README.md，包含安装和用法说明"

跟交互模式的区别：执行完自动退出，不进入聊天界面。

3.2 常用参数

# 全自动执行：不需要任何批准（慎用！第4天讲安全）codex exec --full-auto "把 TODO 注释整理成 TODO.md"# 指定沙箱级别：允许写当前工作区codex exec --sandbox workspace-write "重构 utils.py，保持对外接口不变"# 在非 git 目录里运行（默认要求 git 仓库）codex exec --skip-git-repo-check "..."# 指定目录codex exec -C /path/to/project "..."# 机器可读输出（写脚本时很有用）codex exec --json "..."# 只输出最后一条消息（适合管道处理）codex exec --output-last-message "解释一下这段代码的作用"

3.3 管道玩法

exec 模式支持从标准输入读内容，这让它变成了一个"能思考的管道命令"：

git diff | codex exec"帮我 review 这些改动，指出潜在 bug 和风格问题"cat server.py | codex exec --output-last-message "给这段代码写单元测试"

3.4 接入 CI

在 GitHub Actions 里，可以这样让 Codex 自动完成重复性工作：

-name:自动生成变更日志run:|    codex exec --full-auto --sandbox workspace-write \      "根据 git log 生成 CHANGELOG.md，按 语义化版本 分类"env:OPENAI_API_KEY:${{secrets.OPENAI_API_KEY}}

今日练习： 用一行 codex exec 给项目生成一份 CHANGELOG，再试试 git diff | codex exec 做一次代码审查。

第4天：沙箱与安全模型——知道它"能碰什么"

这是 Codex 最重要的概念，也是新手最容易踩坑的地方。Codex 有两个独立的控制维度：

4.1 沙箱（能碰什么文件）

• read-only（默认）：只能读文件，不能写。适合让 Codex 分析代码、给建议
• workspace-write：只能写当前工作区内的文件。日常开发推荐
• danger-full-access：完全放开，能改系统任何文件、执行任何命令。只在隔离环境（容器/虚拟机/CI）里用

4.2 审批模式（要不要问你）

• --ask（默认）：写文件、跑命令前都先征求你同意
• --auto：自动批准安全的操作（如运行测试、写工作区内文件），危险操作仍会询问
• --full-auto：全自动，什么都不问

4.3 组合建议

4.4 必须警惕的危险操作

即使开着审批，以下情况也要留个心眼：

• rm -rf、git push --force 这类不可逆命令
• curl xxx | sh 这类下载执行脚本
• 把 API 密钥、密码写进代码或 AGENTS.md
• 让它连接生产数据库

防线： 让 Codex 干活前，先把当前状态 git commit 好。它改坏了，你随时能回滚。它展示的 diff 值得花 10 秒看一眼——这是你作为"审查者"而非"执行者"的价值所在。

今日练习： 在 read-only 模式下让 Codex 写文件，观察它怎么拒绝；再切到 workspace-write 让它成功写入，感受两种模式的边界。

第5天：AGENTS.md——把 Codex 调教成懂你项目的同事

每次新开项目，你都希望 AI 立刻懂你的技术栈、代码规范、目录约定。AGENTS.md 就是干这个的——它是给 AI 看的"入职手册"，Codex 每次会话都会自动读取。

5.1 两个层级

• 项目级：放在仓库根目录的 AGENTS.md，跟着仓库走，团队成员共享
• 全局级：~/.codex/AGENTS.md，作用于你机器上的所有项目

5.2 写什么

一个实用的 AGENTS.md 通常包含：

# 项目指南## 技术栈- 后端：Python 3.11 + FastAPI- 前端：React 18 + TypeScript- 包管理：uv（不要用 pip）## 代码规范- 类型注解必须完整，通过 mypy 检查- 提交信息遵循 Conventional Commits- 新功能必须带单元测试，覆盖率不低于 80%## 常用命令- 跑测试：uv run pytest- 跑开发服务器：uv run uvicorn app.main:app --reload## 禁忌- 不要修改 migrations/ 目录下的文件- 不要提交 .env 文件- 不要动 legacy/ 下的旧代码，除非明确要求

5.3 为什么它比"每次口头说"强

• 不用每次重复交代背景，Codex 自动加载
• 团队所有人共享同一套约束，产出风格统一
• 新人（人类）入职也能看这份文档，一举两得

今日练习： 给你最常写的项目补一份 AGENTS.md，然后让 Codex 按里面的规范写一段代码，看它是否遵守——不遵守就继续完善你的文档。你写文档的水平，直接决定 AI 的产出质量。

第6天：模型切换、第三方模型、MCP 与自定义命令

6.1 切换模型

Codex 默认使用 Codex 系列模型（如 gpt-5-codex 及其更新版本）。交互模式里输入 /model 即可切换：

• 大而重的任务（大型重构、复杂架构设计）→ 用最强模型
• 小任务（改个文案、写个测试）→ 用轻量模型，省额度、速度快

6.2 接入第三方模型（国内用户重点）

Codex 支持 OpenAI 兼容接口的第三方模型，配置文件在 ~/.codex/config.toml。比如接 DeepSeek：

model = "deepseek-chat"model_provider = "deepseek"[model_providers.deepseek]name = "DeepSeek"base_url = "https://api.deepseek.com/v1"env_key = "DEEPSEEK_API_KEY"

然后设置 export DEEPSEEK_API_KEY=sk-xxx 即可。通义、Kimi、GLM 等支持 OpenAI 兼容协议的服务商同理——把 base_url 和 env_key 换成对应的就行。

注意：部分 Codex 专属功能（如某些工具调用）依赖 OpenAI 官方模型，第三方模型可能不支持，属正常现象。

6.3 MCP：给 Codex 接外部工具

MCP（Model Context Protocol）让 Codex 能调用外部工具，比如 GitHub、数据库、文件系统：

# 添加一个文件系统工具codex mcp add filesystem npx -y @modelcontextprotocol/server-filesystem /path/to/allow# 查看已添加的 MCP 服务器codex mcp list# 移除codex mcp remove filesystem

添加后在 ~/.codex/config.toml 里启用：

mcp_servers = ["filesystem"]

以后你说"把 dist 目录压缩上传到服务器"，它就能自己调用工具完成。

6.4 自定义斜杠命令

在 ~/.codex/prompts/ 目录下建一个 Markdown 文件，文件名就是命令名。比如 review.md：

---description: 审查最近一次提交---请审查最近一次提交的代码改动，重点检查：1. 潜在的 bug 和边界情况2. 安全问题（注入、密钥泄露等）3. 性能问题4. 是否符合项目 AGENTS.md 中的规范输出格式：按严重程度列出问题清单，并给出修改建议。

之后在 Codex 里输入 /review 就能一键触发。

今日练习： 接一个第三方模型试试手感，再给自己造一个 /review 或 /test 自定义命令。

第7天：生态打通与真实工作流

7.1 Codex 全家桶

• Codex App（桌面版）：codex app 启动。图形界面，可以直接打开本地仓库，适合不习惯终端的朋友
• Codex Web（云端）：chatgpt.com/codex。云端沙箱里干活，能直接创建 GitHub PR，适合"给它一个 issue，它给你一个 PR"
• IDE 扩展：VS Code、Cursor、Windsurf 官方插件，编辑器内对话、内联 diff、一键接受修改
• codex tunnel：把本机终端和 ChatGPT App 配对，手机上下指令、电脑上干活

7.2 一个完整的真实工作流

以"给开源项目加一个新命令"为例：

1. 项目根目录写好 AGENTS.md（技术栈、规范、测试命令）
2. 提一个清晰的 issue 描述需求
3. 本地执行：

codex exec --sandbox workspace-write \"实现 issue #42 描述的功能：新增 --dry-run 参数，输出将要执行的操作但不实际执行。写完补测试并全部跑通。"

1. Codex 写代码 → 跑测试 → 修 bug → 你 review diff
2. 通过后 commit、push、提交 PR

整个过程里，你的角色是"产品经理 + 代码审查者"，Codex 是执行者。

7.3 避坑指南（血泪总结）

1. --full-auto 只用在可信环境（容器/CI），本地别裸奔
2. 大改动前先 commit，给 AI 的失误留退路
3. 密钥别写进 prompt 和 AGENTS.md，它可能会被写进代码
4. 需求越具体，产出越靠谱——验收标准说清楚，比咒语管用
5. 让它跑测试再交付，别信"我觉得没问题"
6. 长任务拆小步：一次一个大目标，分多次执行，每步验收
7. 会话可以续：codex resume 找回历史会话，长任务别浪费上下文
8. 网络问题：官方服务需要稳定网络；国内可用第三方兼容端点（见第6天）
9. AI 会一本正经地胡说：关键代码必须人工 review，测试是唯一的真相
10. 团队锁版本：用同一版本 Codex，避免行为不一致（仓库里的 DotSlash 文件就是干这个的）

7.4 结业任务

用 Codex 独立完成一个小工具：从 0 到 1 开发一个命令行工具（比如"批量重命名图片"、"自动整理下载目录"），要求：

• 有 AGENTS.md
• 用 exec 模式全流程开发
• 有测试且全部通过
• 用 /review 或管道方式做一次自我审查

做完这个，你就出师了。

最后

7 天学下来你会发现，Codex 真正改变的不是"写代码的速度"，而是工作方式：你从"亲手写每一行代码"，变成了"定义目标、设定边界、审查结果"。

搜索、写码、debug 这些体力活正在变成自动化的基建。而"想清楚要做什么、怎样才算好"——这件事，永远是你的。

参考资料：

• GitHub 仓库：github.com/openai/codex
• 官方文档：developers.openai.com/codex
• 安装脚本：chatgpt.com/codex/install.sh

动手装一个吧，今天就是第 1 天。