Codex 零基础完全指南:从安装到实战,踩坑全记录

OPENAI CODEX · 零基础实战指南

Codex 完全上手指南从安装到实战，踩坑全记录

4种使用方式 · 6个可复用Prompt模板 · 5个真实踩坑看完直接能用，不废话

⏱ 阅读约10分钟

🎯 零基础可直接上手

📌 建议收藏备用

本文目录

① Codex 是什么

② 4种方式选哪个

③ Desktop App 安装

④ CLI 完整安装

⑤ 核心操作速查

⑥ AGENTS.md 配置

⑦ 6个Prompt模板

⑧ 实战案例

⑨ 5个踩坑记录

⑩ 总结

Codex 是什么？先搞清楚这件事

⚠️ 先区分两个"Codex"

老版 Codex（2021年）：OpenAI 的代码补全模型，已于2023年下线。新版 Codex（2025年）：OpenAI 推出的 AI 编程 Agent，本文讲的是这个。

新版 Codex 的定位是编程 Agent，不是代码补全，不是聊天机器人。它能做的事情是：

CODEX 核心能力

✦ 读取你的整个代码库，理解项目结构 ✦ 根据自然语言需求，自主写代码、改代码 ✦ 运行测试，发现并修复 Bug ✦ 生成 Git diff，提交变更，创建 PR ✦ 并行处理多个任务，不互相干扰 ✦ 最长可自主工作 7 小时以上

和 Cursor、GitHub Copilot 的区别：后两者是"副驾驶"，你还是主要在写代码；Codex 更像是"把任务交给它，它自己跑完再给你看结果"。

4种使用方式，选哪个？

Codex 有4个入口，不是替代关系，而是同一套能力的不同形态。

方式

适合谁

特点

Desktop App

零基础、想要完整GUI

线程管理、Diff面板、Git集成，最直观

CLI

习惯命令行的开发者

终端直接调用，可脚本化，灵活

IDE 插件

长时间在 VS Code/Cursor 里工作

编辑器内嵌，不用切窗口

Web 云端

想连接 GitHub 跑云端任务

零安装，直接操作 GitHub 仓库

零基础推荐：先从 Desktop App 开始。它有完整的 GUI，能看到线程、Diff、终端输出，上手最直观。CLI 适合熟悉命令行之后再切换。

Desktop App：零基础最推荐的方式

Desktop App 是 Codex 的"指挥中心"——线程管理、Diff 面板、内置终端、Git 操作全在一个界面里。第一次用 Codex，从这里开始。

📥 安装步骤

macOS：打开 App Store → 搜索「Codex」→ 找到 OpenAI 官方应用 → 下载安装Windows：访问微软商店，搜索「Codex」或直接搜索 apps.microsoft.com 中的 Codex → 获取安装系统要求：macOS 11.0+，Windows 10 19041+，需要联网

🔑 登录与授权

1. 打开 Codex Desktop 2. 用 ChatGPT 账号登录（需要 Plus 或 Pro 订阅） 3. 选择一个本地文件夹或 Git 仓库作为工作目录 4. 开始第一个任务

切换中文界面：File → Settings → General → Language for the app UI → 选择 Chinese (China) → 重启应用

界面核心区域说明

左侧栏：项目列表 + 线程列表（一个项目可开多个线程）中间区：对话输入 + 任务进度 + 模型输出右上角：内置终端（每个线程独立绑定）右侧面板：Diff 面板（显示所有文件变更）底部：模型切换 + 思考深度调节

订阅价格：Plus $20/月（轻量使用）、Pro $200/月（全职开发者）。国内用户需要 VPN，建议开启全局 Tun 模式，否则可能连接失败。

Codex CLI：终端党的完整安装指南

CLI 是在终端里直接运行的 Codex，适合习惯命令行的开发者。可以和现有的 shell 工作流无缝融合。

macOS / Linux 安装

方式一：npm 安装（推荐）

# 先确认 Node.js 已安装（需要 18+） node --version# macOS 安装 Node.js（如果没有） brew install node# 全局安装 Codex CLInpm install -g @openai/codex

方式二：Homebrew 安装

brew install codex

Windows 安装（必须用 WSL）

Windows 原生环境运行 Codex CLI 会出现乱码和各种奇怪问题。必须在 WSL（Windows Subsystem for Linux）里运行。

Windows WSL 安装流程

# 1. 在 PowerShell（管理员）中安装 WSL wsl --install -d Ubuntu-24.04# 2. 重启后进入 WSL wsl# 3. 在 WSL 里安装 Node.js curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash - sudo apt-get install -y nodejs# 4. 安装 Codex CLInpm install -g @openai/codex

首次启动与登录

# 进入你的项目目录 cd ~/your-project# 启动 Codex CLIcodex# 首次运行会提示用 ChatGPT 账号登录# 登录后即可开始使用

先说三个你熟悉的场景

写完一个功能，调试三遍才跑通——每次都是低级错误，但就是看不出来。

遇到陌生框架，翻文档加问 AI，一来一回30分钟，写出来的代码还要改。

脑子里有清晰的需求，但从需求到跑通代码，中间隔着两个小时的体力活。

Codex 能把这三类问题压缩掉大半。它不是代码补全，也不是问答 AI——它是一个能在你的代码库里自主读文件、写代码、跑测试、提交变更的编程 Agent。

但工具好不等于用得好。这篇文章把我踩过的坑全部列出来，帮你直接跳到"能用对"的状态。

核心操作速查：这几个命令最常用

CLI 常用命令

codex# 启动 Codex CLI/model# 切换模型（推荐 gpt-5-codex high）/plan# 先规划再执行，复杂任务必用/init# 在当前目录生成 AGENTS.mdcodex --approval-mode full# 全自动模式，不需要每步确认

Desktop App 核心操作习惯

操作

说明

一个线程一件事

不要在一个线程里混着做功能开发+测试+重构，上下文会乱

先看 Diff 再确认

Agent 改完代码，先看右侧 Diff 面板，确认改动符合预期再继续

用 /plan 先对齐

复杂任务先输入 /plan，让 Codex 列出执行步骤，确认后再开始

思考深度按需调

小任务用 Fast，复杂逻辑/重构用 High，速度和质量的权衡

💡 关于 Approval 权限设置

Codex 默认每次操作都需要你确认（安全但慢）。熟悉之后可以在 config.toml 里设置 approval_policy = "auto"，让它自动执行。建议：新项目先用手动确认，熟悉代码库后再放开权限。

AGENTS.md：让 Codex 记住你的偏好

AGENTS.md 是 Codex 的"记忆文件"，类似于给 AI 写的工作说明书。每次启动 Codex，它都会先读这个文件，然后按照里面的规则工作。

两种 AGENTS.md 的位置

全局（推荐）：~/.codex/AGENTS.md — 对所有项目生效项目级：./AGENTS.md（项目根目录）— 只对当前项目生效

AGENTS.md 模板（直接复用）

# 语言偏好 Always respond in Chinese-simplified.# 代码风格 - 使用 Python 时，遵循 PEP8 规范 - 函数命名用 snake_case，类命名用 PascalCase - 每个函数写简短注释说明用途# 工作习惯 - 修改代码前先用 /plan 列出步骤 - 每次改动后运行相关测试 - 提交信息用中文，格式：[类型] 描述# 禁止事项 - 不要删除已有的注释 - 不要修改 config/ 目录下的文件

设置一次，永久生效。Codex 每次启动都会读取这个文件，不需要每次重新说明偏好。

6个可直接复用的Prompt模板

这6个模板覆盖了日常开发80%的场景，直接复制改改就能用。

模板1：新功能开发

我需要在 [项目名] 里实现 [功能描述]。技术栈：[Python/Node.js/等] 要求： - [具体要求1] - [具体要求2] 先用 /plan 列出实现步骤，我确认后再开始写代码。

模板2：Bug 排查与修复

运行 [命令] 时出现以下报错： [粘贴完整错误信息] 请： 1. 定位错误根因 2. 给出修复方案 3. 修复后运行测试确认没有引入新问题

模板3：代码重构

请重构 [文件路径] 中的 [函数/模块名]。重构目标：[提升可读性/减少重复/优化性能] 约束： - 保持对外接口不变 - 不改变现有测试 - 重构完成后运行测试套件确认通过

模板4：补充测试

为 [文件路径] 中的所有函数补充单元测试。测试框架：[pytest/jest/等] 要求： - 覆盖正常路径和边界情况 - 每个测试用例有清晰的命名 - 测试文件放在 [tests/目录]

模板5：代码审查

请审查 [文件路径] 的代码，重点关注： - 潜在的 Bug 和边界情况 - 安全漏洞（SQL注入/XSS/等） - 性能问题 - 代码可读性给出具体的改进建议，不需要直接修改代码。

模板6：理解陌生代码库

我刚接手这个项目，请帮我： 1. 分析整体项目结构和技术栈 2. 找出核心模块和入口文件 3. 梳理主要的数据流向 4. 列出我需要重点了解的5个文件用中文输出，结构清晰。

实战案例：用 Codex 从零搭建 FastAPI 项目

以下是一个真实的工作流，展示如何用 Codex 在30分钟内搭建一个带测试的 FastAPI 项目。

背景：需要搭建一个用户管理 API

需求：用户注册/登录/查询，JWT鉴权，PostgreSQL 数据库，需要单元测试

第1步：先规划

/plan 我需要用 FastAPI + PostgreSQL 搭建用户管理 API，包含注册/登录/查询功能，JWT鉴权，并为所有接口写单元测试。请列出实现步骤。

Codex 返回的计划（示意）： 1. 初始化项目结构和依赖（requirements.txt） 2. 设计数据库模型（User 表） 3. 实现认证逻辑（密码哈希 + JWT） 4. 实现 API 路由（注册/登录/查询） 5. 补充单元测试（用 pytest + httpx） 6. 添加 Docker 配置

第2步：确认计划，开始执行

计划看起来没问题，按这个顺序开始吧。数据库用 SQLAlchemy ORM，密码用 bcrypt 加密， JWT 有效期设为24小时。

第3步：Codex 跑完后，检查 Diff

Codex 会在 Diff 面板里展示所有新增/修改的文件。检查要点： ✦ requirements.txt 里的依赖版本是否合理 ✦ 数据库模型字段是否符合预期 ✦ JWT 密钥是否硬编码了（应该用环境变量） ✦ 测试用例是否覆盖了边界情况

第4步：发现问题，用新线程修复

[新建线程] auth.py 里 JWT_SECRET 是硬编码的，请改为从环境变量 JWT_SECRET_KEY 读取，并在 README 里说明需要设置这个环境变量。

整个过程耗时约25分钟（规划5分钟 + Codex执行15分钟 + 检查和修复5分钟），得到一个有完整测试的项目框架。手写至少需要2-3小时。

5个真实踩坑记录

这些坑我都亲自踩过，列出来帮你直接跳过。

坑1：一个线程做太多事，最后乱成一锅粥

在同一个线程里让 Codex 又写功能、又改 Bug、又优化代码，结果上下文越来越乱，后面的修改开始覆盖前面的决定。

解决：一个线程只做一件事。功能开发是一个线程，修 Bug 是另一个线程，重构再开一个。

坑2：只看对话，不看 Diff，代码悄悄被改错了

Codex 在对话里说"已完成"，但实际上它顺手改了几个本来不该动的文件，我没注意，直接提交了，后来才发现。

解决：每次 Codex 完成任务后，先看 Diff 面板，确认所有改动文件都在预期范围内再继续。

坑3：国内直接用，连接老断，还可能被封号

挂了梯子但没开全局模式，Codex 连接频繁超时；或者用了共享 IP，被 OpenAI 检测为滥用账号风险。

解决：VPN 必须开全局 Tun 模式，不要用共享节点。固定用一个独立 IP 的节点更安全。

坑4：给的需求太模糊，Codex 猜了个错误方向

说"帮我优化这个函数"，没说具体要优化什么，Codex 去优化了性能，但我其实想要的是可读性。白跑了一轮。

解决：需求里说清楚"目标"（要达成什么）和"约束"（不能动什么）。先用 /plan 对齐，比直接让它跑省时间。

坑5：上下文用完了，Codex 忘记了前面的决定

长线程里后期 Codex 会压缩上下文，它压缩后可能忘记前面定下的架构决策或变量命名规范，导致后面的代码风格不一致。

解决：把关键约束写进 AGENTS.md，不要只靠对话里的一句话。重要决策明确写成规则。

总结：用好 Codex 的3个核心原则

CORE PRINCIPLES

原则1：先规划，再执行

复杂任务先用 /plan 对齐思路，比直接让 Codex 跑省时间。一个清晰的计划能减少80%的返工。

原则2：看 Diff，不只看对话

Codex 说"完成了"不等于改对了。每次任务结束后看 Diff 面板，确认所有改动都在预期范围内。

原则3：用 AGENTS.md 固化规则

不要每次都在对话里重复说明偏好。把代码风格、工作习惯、禁止事项写进 AGENTS.md，一次设置，永久生效。

快速上手路径（推荐顺序）

1. 安装 Desktop App（App Store 搜 Codex） 2. 用 ChatGPT Plus 账号登录 3. 创建 ~/.codex/AGENTS.md，写入语言偏好和代码规范 4. 打开一个项目，新建线程，用模板6先让 Codex 理解代码库 5. 用模板1开始第一个真实任务

— CORE INSIGHT —

Codex 不是让你少写代码是让你把时间花在值得花的地方

架构决策、需求拆解、代码审查——这些才是工程师的核心价值体力活交给 Codex

你现在用的是哪个 AI 编程工具？

评论区告诉我：Codex / Cursor / Claude Code / 其他或者你有什么用 Codex 踩过的坑，欢迎补充