十分钟 Codex 入门

English version

Codex 和普通聊天机器人最大的区别是，它不是只在对话框里回答你。

它可以在你的项目目录里读代码、改文件、跑命令、看报错，再把修改交给你检查。

所以学 Codex 的重点，不是背一堆 prompt 技巧。

真正重要的是三件事：

怎么把任务讲清楚。
怎么限制它只动应该动的地方。
怎么检查它到底改了什么。

这篇文章只带你完成第一次真实使用。

一、安装

官方推荐的 CLI 安装方式之一是 npm：

npm i -g @openai/codex

安装完运行：

codex

第一次运行会提示你登录。可以用支持 Codex 的 OpenAI 账号，也可以按提示使用 API key。

升级到最新版：

npm i -g @openai/codex@latest

如果你在 Windows 上用 Codex，可以直接在 PowerShell 里跑；如果项目依赖 Linux 工具链，再考虑 WSL2。

二、打开一个真实项目

别在空目录里试。

找一个你熟悉的小项目，最好是可以跑测试、可以 build 的项目：

cd ~/projects/my-app
codex

进来后先别急着让它改代码。

第一句话可以这样问：

先帮我读一下这个项目，不要改文件。告诉我入口文件、主要目录、启动命令和测试命令。

这个问题很适合第一次使用。

因为你可以观察 Codex 怎么读文件、怎么总结项目，也不会马上产生一堆改动。

三、第一轮真实任务

等它理解项目后，给一个小任务。

例如：

帮我修复首页里按钮文字溢出的问题，只改和这个按钮相关的文件。改完后告诉我改了哪些文件，不要提交。

这句话里有几个关键点：

任务很具体，按钮文字溢出。
范围很明确，只改按钮相关文件。
不让它提交，先让你检查。

如果你要它写测试，也可以这样：

给 src/lib/price.ts 里的 formatPrice 补 3 个测试，只覆盖正常金额、0、负数这三个场景。先不要改实现。

AI 编程代理最怕任务边界太糊。

不是因为它不能做，而是因为它很容易把一个小问题扩成一个大工程。

四、看它改了什么

Codex 有一个很重要的习惯，一定要养成：

改完先看 diff。

在交互里输入：

/diff

你也可以在终端里自己看：

git diff

检查三个问题：

有没有改到不相关文件。
有没有把简单问题改复杂。
有没有漏跑必要验证。

如果你不满意，可以直接说：

这个改动范围太大了。只保留按钮样式相关的修改，其他文件恢复到修改前。

或者：

先不要继续写新代码，解释一下为什么需要改这两个文件。

这不是在为难它。

这是你作为项目 owner 必须做的事。

五、几个常用命令

Codex CLI 里有一些 slash command，够你开始用了。

| 命令 | 用来做什么 |

| --- | --- |

| /diff | 查看当前修改 |

| /status | 查看当前会话和环境状态 |

| /permissions | 调整它能不能自动跑命令、改文件 |

| /model | 切换模型 |

| /clear | 清空当前对话，重新开始 |

| /compact | 对长对话做压缩，释放上下文 |

| /mention | 指定某个文件或目录给它看 |

| /init | 生成项目里的 AGENTS.md |

| /exit | 退出 |

如果你忘了命令，输入 / 看提示。

六、命令行里直接给任务

有时候你不想进入完整交互界面，只想让 Codex 做一次性分析。

可以直接这样：

codex "解释这个项目的主要模块"

或者带工作目录：

codex --cd ~/projects/my-app "找一下为什么 pnpm build 失败，先不要改代码"

如果你想加图片，比如截图或设计稿，可以用：

codex --image screenshot.png "对照截图检查页面样式问题"

这些能力很适合快速问问题。

真正要改代码时，我还是更建议进入交互模式，边看计划边确认。

七、权限要保守一点

Codex 可以跑命令、改文件，所以权限不是小事。

刚开始建议保守：

codex --ask-for-approval on-request

如果你只是想让它读项目：

codex --sandbox read-only

如果你真的要全自动跑，确保是在隔离环境里，不要在重要项目和脏工作区里直接开最大权限。

这块没有什么玄学。

AI 能力越强，你越要知道它什么时候在动你的真实文件。

八、一个适合新手的 prompt 模板

刚开始可以直接套这个：

你先读一下这个项目，不要改文件。

我要解决的问题是：
[把问题写清楚]

限制：
- 只改 [文件或目录]
- 不要改 [不相关模块]
- 改完先给我 diff 摘要
- 不要提交

验证：
- 优先运行 [测试或 build 命令]
- 如果命令跑不了，告诉我原因

这比一句「帮我优化一下」好太多。

你给它边界，它才更像一个靠谱的协作者，而不是一个到处乱动的自动补全。

九、什么时候适合用 Codex

| 任务 | 适合程度 |

| --- | --- |

| 读陌生项目结构 | 很适合 |

| 修明确 bug | 很适合 |

| 写测试 | 很适合 |

| 做小范围重构 | 适合 |

| 大范围架构迁移 | 谨慎 |

| 没想清楚的产品方向 | 先别急着让它写代码 |

我觉得 Codex 最适合的起点，是那些你已经能描述清楚的问题。

比如某个 build 报错、某个按钮溢出、某个函数缺测试、某段逻辑需要解释。

先从这些任务开始。

等你熟悉它的工作节奏，再把更复杂的事情交给它。