OpenAI Codex 实用技巧介绍

一、引言

1.1 介绍及安装

OpenAI Codex 是一个可以满足您所有编码需求的智能体，一个在终端中运行的轻量级编码智能体。

使用您喜欢的包管理器进行全局安装。如果您使用 npm：

1

npm install -g @openai/codex

或者，如果您使用 Homebrew：

1

brew install --cask codex

然后只需运行“codex”即可开始使用：

1

codex

1.2 配置文件

配置文件在 ~/.codex/config.toml，没有的话可以自己创建一个，或者用起来就有了。这个配置文件是全局共享的，可用于配置 Codex 应该有权访问的默认模型、 批准策略、沙盒设置或 MCP 服务器等内容。

1
2
3
4
5
6
7
8
9
10

model_provider = "provider_name"
model = "gpt-5"
model_reasoning_effort = "medium"
disable_response_storage = true
preferred_auth_method = "apikey"
 
[model_providers.provider_name]
name = "provider_name"
base_url = "https://codex-api.[provider_name].com/v1"
wire_api = "responses"

• • model：这里配置的是模型，可选模型有 gpt-5 和 gpt-5-codex。
• • model_reasoning_effort：是模型的思考级别，可选 high, low, medium 等
• • model_provider：这是配置不同的中转站，根据自己的中转站配置。
• • model_providers.<id>.wire_api：提供商使用的协议，可选 chat|responses，如果省略则默认为“chat”。

要使用 Codex IDE 扩展时访问配置文件，您可以单击扩展右上角的齿轮图标，然后单击 Codex Settings -> Open config.toml 。

详细配置项可以参考官方文档：

https://developers.openai.com/codex/local-config

https://github.com/openai/codex/blob/main/docs/config.md

二、 Codex CLI

2.1 CLI 命令

帮助命令（--help）

进入时指定模型（--model，-m）

进入时指定配置（--profile, -p）

指定从 ~/.codex/config.toml 加载的配置文件名称。比如在 toml 文件中增加配置指定模型为 gpt-5-codex 的 medium 等级，默认不带参数进入时显示 gpt-5 medium，使用 codex -p gpt-5-codex-medium 指定后进入显示 gpt-5-codex medium。

进入时覆盖配置项（--config, -c）

覆盖配置值。值尽可能解析为 JSON 格式；否则，使用字符串字面值。

2.2 TUI 命令

切换模型（/model）

输入 /model 可以选择模型和推理级别。

有两个模型可以选，gpt-5-codex 是为编码做了优化，gpt-5 是推理能力强。

选完模型需要选一个推理级别，级别越高越能处理复杂问题，但是速度会更慢。

设置权限（/approvals）

有三种可选：

1. 1. Read Only 只读，不能改文件，几乎啥也干不了，不建议选。
2. 2. Auto 自动，建议新手首选，自动读文件，改文件需要确认。
3. 3. Full Access 完全读写，重要文件建议备份好或使用版本控制工具。

初始化（/init）

在你的项目根目录创建一个 AgentS.md 文件，包含 Codex 的用法说明。

过程是通过如下图的提示词让模型生成内容，大致内容是“生成一个名为“AGENTS.md”的文件，作为此仓库的贡献者指南。您的任务是......”这样的，完整内容我放在文末。

在生成完成后，会在根目录创建 AGENTS.md 文件，关于该文件的详细介绍可以访问 [https://agents.md/](https://agents.md/) 来详细了解。

MCP（/mcp）

MCP 就是给 AI 装插件，执行 /mcp 命令可以查看当前安装的 MCP 工具。TUI 中仅能查看配置了的 MCP 服务，关于 MCP 的配置，需要使用 CLI 命令或者修改配置文件，后面再说。

2.3 引用（搜索）文件

使用 @ 可以搜索文件，不过无法贴图啥的。

三、 Codex IDE

3.1 支持多个平台安装

vscode 系列会在左侧看到边栏中看到 Codex 扩展，如果是 Cursor 默认情况下左侧边栏是水平显示的，因此 Codex 可能会隐藏在折叠的项目中，不过可以固定它或者筒通过设置主侧边栏的 Location 为垂直布局。

vscode 系列设置主侧边栏位置的配置项，cursor 有点特殊。

3.2 切换模型和推理等级

可以使用扩展聊天输入下的切换器切换模型和推理等级。

3.3 设置权限（审批模式）

我们为 Codex 在您的计算机上运行选择了一种强大的默认模式，称为 Agent 。在此授权模式下，Codex 可以自动读取工作目录中的文件、进行编辑并运行命令。但是，Codex 需要您的授权才能在工作目录之外运行或访问互联网。

如果您只是想聊天，或者想在开始之前做好计划，您可以使用扩展聊天输入框下方的切换器切换到 Chat 模式。

如果您需要 Codex 在未经授权的情况下通过网络访问读取文件、进行编辑和运行命令，可以使用 Agent (Full Access) 。但请务必谨慎操作。

大概对应下就是：

1. 1. Read Only 只读，对应 Chat 模式
2. 2. Auto 自动，对应 Agent
3. 3. Full Access 完全读写，对应 Agent（full access）

3.4 插件的 apiKey 配置

在点击插件图标打开插件页面的时候会提示使用授权使用：

1. 1. sign in With OpenAI
2. 2. use API Key

如果使用中转站都是使用第二项，那就需要在这个目录下配置：~/.codex/auth.json，没有就新建一个，内容如下：

1
2
3

{
  "OPENAI_API_KEY": "sk-在中转站获取"
}

3.5 引用（拖拽）文件

1. 1. 使用 Add context 按钮搜索并添加文件；
2. 2. 和 Codex CLI 一样，可以通过 @ 进行文件的搜索；
3. 3. 另外 Codex IDE 插件是可以拖拽文件到聊天窗口的，但直接拖拽过去是不行的，需要拖拽按着 Shift 松手，就能将文件的完整路径加入到聊天框中了。

四、 AGENTS.md

官网：https://agents.md/

README.md 文件是为人类准备的：快速入门指南、项目描述和贡献指南。

AGENTS.md 对此进行了补充，其中包含编码代理所需的额外、有时详细的上下文：构建步骤、测试和约定，这些内容可能会使 README 变得杂乱，或者与人类贡献者无关。

• • 为代理提供一个清晰、可预测的指令位置。
• • 保持 README 文件简洁明了，并重点关注人类贡献者。
• • 提供精确的、以代理为中心的指导，补充现有的自述文件和文档。

添加 AGENTS.md 文件有以下三种位置：

1. 1. ~/.codex/AGENTS.md：全局个人指令，比如指定 Always respond in Chinese-simplified。
2. 2. 项目根目录/AGENTS.md：针对整个项目的说明，可以使用 /init 命令创建或者让 codex 编写。
3. 3. 子目录/AGENTS.md：针对特定模块的详细说明。

五、提示词技巧

https://developers.openai.com/codex/prompting

Codex 的有效性也取决于您提供的指令，以下是一些我们认为在指导 Codex 时很有用的技巧：

• • 提供清晰的代码指引：Codex 可以自己搜索代码，但是如果提示词能缩小范围，效率会更高。比如直接指定代码文件或包名、目录，甚至直接指定行数。
• • 包括验证步骤：Codex 在能够在完成任务时验证是否成功。
• • 自定义工作方式：你可以告诉 Codex 如何处理任务或如何使用它的工具。比如将特定的文件视为 AGENTS.md 文件，告诉他如何执行命令。
• • 拆分大任务：处理复杂任务时，如果将其分解成更小、更专注的步骤，就能更好地完成任务。
• • 进行 debug：遇到错误或意外行为时，请尝试将详细日志或错误跟踪粘贴到 Codex 中作为第一步调试 。Codex 可以并行分析问题，并帮助您更快地找到根本原因。

六、 MCP

官方文档：https://developers.openai.com/codex/mcp

6.1 让 Codex 连接 MCP Server

Codex 的 MCP 配置与其他 Codex 配置选项一起存储在 ~/.codex/config.toml 配置文件中。

CLI 和 IDE 扩展共享配置。因此，一旦配置了 MCP 服务器，您就可以在两个 Codex 客户端之间无缝切换。

要配置您的 MCP 服务器，您有两个选择：

1. 1. 使用 CLI ：如果您安装了 Codex CLI，则可以使用 codex mcp 命令来配置您的 MCP 服务器。
2. 2. 直接修改配置文件 ：或者，您可以直接修改 config.toml 文件。

其实使用 CLI 命令就是改配置文件，比如安装 context7：

1

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

配置文件中会多出来：

1
2
3

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

需要注意的是，Windows 使用 MCP 会出现一些问题，最好是通过 WSL2 使用 Codex，或者通过 AI 工具搜索如何解决。

6.2 让 Codex 作为 MCP Server 运行

除了将 Codex 连接到 MCP 服务器之外，您还可以将 Codex 作为 MCP 服务器运行。这样，您可以将其连接到其他 MCP 客户端，比如让 Claude Code 连上 Codex 的 MCP Server。启动命令是这个：

1

codex mcp-server

或者通过模型上下文协议检查器（Model Context Protocol Inspector）启动：

1

npx @modelcontextprotocol/inspector codex mcp-server

发送 tools/list 请求后，会发现有两个工具，分别是 codex 和 codex-reply。

1. 1. codex：开启会话，接收匹配的参数属性，参数可以参考官方文档。
2. 2. codex-repy：继续会话，需要提供会话 ID。