Codex 零基础入门到实战：从装好到用顺的完整路线

Codex 是 OpenAI 推出的 AI 编程工具，2025 年 4 月第一次露面，最初必须自备 API Key 才能用。转折点是 2025 年 8 月 GPT-5 发布之后——ChatGPT Plus / Pro / Team 用户可以直接登录使用，不再额外收费。门槛一降下来，用的人就多了。

这篇文章把从安装到实际用起来的完整流程理一遍，重点放在新手最容易卡住的几个地方：怎么装、怎么认证、权限模式该怎么选、以及那几个能明显提升效率的功能怎么用。

一、装之前先确认环境

Codex CLI 需要 Node.js 18 或更高版本，系统上 macOS、Linux、Windows 都支持（Windows 建议用 PowerShell 或者 WSL2）。

先查一下版本：

node -v

如果版本太低，用 nvm 升到 22 是比较省事的做法：

nvm install 22
nvm use 22

图片来源：网络，版权归原作者所有，侵权请联系删除

二、安装

npm 全局安装是最通用的方式：

npm install -g @openai/codex

macOS 和 Linux 用户也可以用 Homebrew：

brew install --cask codex

装完验证一下：

codex --version

能打印出版本号就说明装好了。

三、认证：两种方式，按场景选

方式一：ChatGPT 账号登录（推荐给个人用户）

直接运行 codex，选择 Sign in with ChatGPT，浏览器里完成授权即可。支持 Plus、Pro、Team、Edu、Enterprise 几种计划。

这个方式的好处是能用到最新模型，Plus 用户还有 5 美元、Pro 用户有 50 美元的免费 API 额度（30 天内有效）。

方式二：API Key（推荐给 CI 和自动化）

export OPENAI_API_KEY="sk-your-api-key-here"

想让它长期生效，就写进 ~/.bashrc 或 ~/.zshrc。

两者有个实际差别值得留意：ChatGPT 登录能第一时间用上新模型，API Key 的新模型访问会滞后一些。所以日常写代码用订阅登录，跑 CI 流水线才用 API Key，是比较合理的分工。

四、第一次用：三种典型姿势

启动交互界面：

codex

直接带任务启动：

codex "fix build errors"

非交互模式跑脚本（适合自动化）：

codex exec "update the changelog for this diff"

五、权限模式：这是新手最容易踩坑的地方

Codex 能读写文件、执行 shell 命令，所以权限控制是它设计里最核心的一环。三种模式对应三种信任程度：

新手阶段老老实实用默认的 suggest，看着它每一步改了什么，心里有数。等用熟了、确认它在自己项目里的判断靠谱了，再考虑逐步放开。

full-auto 虽然写着"全自动"，但也不是毫无边界——它会限制可访问的目录，网络也是关的。另外如果你不在 git 管理的目录下运行，它会先提醒你一句。

六、让 Codex 真正懂你的项目：AGENTS.md

这是整套流程里最值得花时间的一步。AGENTS.md 相当于给 Codex 的项目说明书——新员工入职要看项目文档，它也一样。

放全局配置在 ~/.codex/AGENTS.md，放项目配置就放在项目根目录：

## Architecture
- Frontend: Next.js + TypeScript
- API: FastAPI (Python 3.12)
- DB: PostgreSQL via SQLAlchemy

## Conventions
- Python 用 snake_case，TypeScript 用 camelCase
- 新增接口必须配套集成测试

## Working agreements
- 改完源码后总是运行 pnpm test
- 优先用 pnpm 装依赖

它的加载顺序有优先级，越靠近当前工作目录的越优先：

~/.codex/AGENTS.override.md  （最高）
~/.codex/AGENTS.md
项目 git 根目录 → 当前目录（该目录下的 AGENTS.md 优先）

不想手写的话，在 Codex 里输入 /init 可以直接生成一个骨架。

有个大小限制要注意：project_doc_max_bytes 默认 32 KiB，写得太长会被截断。

七、用起来之后：四个明显提效的功能

计划模式（Plan Mode）

输入 /plan，让 Codex 先给方案再动手。复杂任务上这一步很值——它在执行前会梳理思路、拆解步骤，你能提前发现方向不对，省掉返工。对一个要改十几个文件的需求，先看计划比直接让它改要稳妥得多。

Skills 技能

Skills 是把常用流程固化成可复用能力的机制。CLI 里用 /skills 查看、/skills install 安装；桌面应用在左侧边栏的"插件市场"里找，用 $ 符号调用。

几个现成的例子：

• 代码审查 —— 自动检查代码质量和安全隐患
• 提交规范 —— 生成符合规范的 commit message
• 依赖扫描 —— 检查依赖的安全性和版本
• UI 优化 —— 分析界面并提出改进建议

自定义 Skills 也不复杂，写一个 .md 文件，定义清楚检查项和输出格式就行。官方现在更推荐用 Skills 来管理可复用指令。

MCP 扩展

MCP（Model Context Protocol）是一个标准化接口协议，让 Codex 能跟外部服务打交道。配置写在 ~/.codex/config.toml 里：

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp@latest"]

配好之后在 Codex 里用 /mcp 就能看到有哪些外部工具可以调用。生态里现在有 90 多个插件，覆盖 Gmail、Netlify、Linear、Playwright、数据库这些常用服务。

Windows 用户这里容易卡住：如果直接照抄 Linux/macOS 的配置，很可能报 program not found 或者 request timed out。原因是 PATH 解析不到可执行文件，解决方法是写完整路径：

# 先用 where.exe 找到位置
where.exe npx

# 输出类似 C:\Program Files\nodejs\npx.cmd
# 把这个完整路径填进 config.toml 的 command

另外设置好 SYSTEMROOT 环境变量（一般指向 C:\Windows）对 Windows 下的稳定运行也很关键。

斜杠命令

在输入框里敲 / 会弹出命令列表，常用的几个：

其中 /compact 在长会话里很有用——对话越聊越长，上下文会被撑爆，压缩一下能保住关键信息腾出空间。/diff 则是在提交前确认它到底改了什么的标准动作。

八、配置文件速查

主配置在 ~/.codex/config.toml，几个最常用的字段：

model = "gpt-5.3-codex"
model_reasoning_effort = "high"      # minimal / low / medium / high / xhigh
approval_policy = "on-request"       # untrusted / on-request / never
sandbox_mode = "workspace-write"     # read-only / workspace-write / danger-full-access
web_search = "cached"                # disabled / cached / live

也可以用命名配置档（profile），按场景切换：

[profiles.ci]
approval_policy = "never"
sandbox_mode = "workspace-write"

之后用 codex --profile ci 加载。

图片来源：网络，版权归原作者所有，侵权请联系删除

上手建议

给新手一条最省事的路径：

• 装好 Node.js 环境，npm 全局装 Codex
• 用 ChatGPT 账号登录，先跑通一个简单任务
• 保持默认的 suggest 权限模式，观察它的改动
• 在项目根目录写一份 AGENTS.md，把技术栈和约定讲清楚
• 熟悉 /plan、/diff、/review 三个命令后再放开权限

Codex 这类工具的价值不在于替你写完所有代码，而在于把重复的、机械的那部分工作接过去——修构建错误、补单元测试、写迁移脚本这类活。把 AGENTS.md 写好、把权限管住，它就能稳定地发挥价值。

本文链接：https://www.zkui.cn/post/26.html