Codex 使用指南

安装 Codex#

官方推荐通过 npm 全局安装：

npm i -g @openai/codex

安装完成后，先检查版本：

codex --version

然后直接启动：

codex

第一次运行时，Codex 会要求你登录。官方支持两种方式：

• 使用 ChatGPT 账号登录
• 使用 OpenAI API Key 登录

最基础的使用方式#

1. 进入项目目录再启动#

cd your-project
codex

这样 Codex 会以当前目录作为工作区，能够直接读取并修改这个项目里的文件。

2. 直接给一个任务#

你可以在启动时就带上提示词：

codex "解释这个项目的目录结构"

或者：

codex "为这个项目补充一个登录接口的单元测试"

3. 常见使用场景#

比如让它解释代码：

codex "解释 src/utils/request.ts 的作用和调用链"

比如让它修 bug：

codex "修复首页搜索框在移动端换行错位的问题"

比如让它补测试：

codex "给 userService 增加测试，并运行测试确认通过"

交互模式里怎么用#

Codex CLI 默认会进入一个交互式终端界面。在这个模式下，你可以：

• 连续追问
• 查看它的计划
• 审核它准备执行的命令
• 看它修改后的 diff
• 继续在同一个上下文里迭代

常用命令#

启动交互式会话#

codex

指定目录运行#

codex --cd ./my-project

指定模型#

codex -m gpt-5.4

允许工作区写入#

codex --sandbox workspace-write

关闭频繁确认，适合你自己完全信任的本地环境#

codex --ask-for-approval never

更稳妥的默认值通常是：

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

会话恢复#

Codex 会把本地会话记录保存下来，所以你下次可以继续之前的任务。

恢复最近一次会话：

codex resume --last

打开会话列表再选择：

codex resume

这对做大一点的重构很有用，不用每次都重新解释项目背景。

常用 Slash Commands#

在 Codex 交互界面里输入 /，可以看到内置命令。比较常用的有：

• /model 切换模型
• /permissions 调整权限策略
• /diff 查看当前修改差异
• /clear 清空当前会话界面
• /copy 复制最近一次输出
• /compact 压缩上下文，适合长对话
• /exit 退出 Codex
• /init 在当前目录生成 AGENTS.md 模板

如果已经和 Codex 聊了很久，优先记住 /compact，它能减少上下文膨胀。

推荐配置#

Codex 的用户级配置文件在：

~/.codex/config.toml

一个适合大多数前端/Node 项目的基础配置可以写成这样：

model = "gpt-5.4"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

这三个配置的意思分别是：

• model 默认模型
• approval_policy 命令执行前的确认策略
• sandbox_mode 文件系统与命令访问权限

如果你只想对某个仓库生效，也可以在项目里放：

.codex/config.toml

AGENTS.md 很重要#

如果你希望 Codex 更稳定地按你的习惯做事，建议在仓库根目录加一个 AGENTS.md。

例如：

# AGENTS.md

## Repository rules

- 修改前先阅读相关文件
- 改完后运行 npm run check
- 不要修改与当前任务无关的文件
- 新增依赖前先说明原因

Codex 会在开始工作前读取这些说明。
这比每次手动重复要求更有效。

给 Codex 接入 MCP#

MCP 可以理解成“给 Codex 装外部工具”。
比如你可以给它接文档、浏览器、设计工具、数据库代理等。

官方给出的添加方式是：

codex mcp add <server-name> -- <command>

例如接一个文档服务器：

codex mcp add context7 -- npx -y @upstash/context7-mcp

查看 MCP 配置：

codex mcp --help

如果想在会话里查看当前可用 MCP，也可以使用：

/mcp

实战建议#

1. 先让它分析，再让它修改#

不要一上来就说“全改掉”。
更稳的方式是先让它说明现状、问题点、修改计划，再开始动手。

2. 任务要具体#

下面这种提示更有效：

把 editor-studio 页面改成 GitHub Dark 风格，只改配色，不改结构，改完运行 npm run check

而不是：

帮我优化一下

3. 明确限制条件#

比如：

• 不要改接口
• 不要新增依赖
• 只改某几个文件
• 改完必须跑测试

这些边界越清楚，Codex 输出越稳定。

4. 不要默认给它最高权限#

danger-full-access 或完全免审批虽然爽，但风险也最大。
大多数本地项目用 workspace-write + on-request 就够了。

一个最小上手流程#

第一次使用，你可以直接照这个流程来：

npm i -g @openai/codex
codex

登录完成后，在你的项目目录执行：

codex "先阅读这个项目，然后告诉我最值得先改进的 3 个问题"

确认它理解项目后，再继续：

codex "修复第一个问题，只修改必要文件，并在完成后运行 npm run check"

升级 Codex#

官方建议定期升级：

npm i -g @openai/codex@latest

升级后再确认一下版本：

codex --version