OpenAI Codex 全面上手指南

OpenAI Codex 全面上手指南

Codex 的四种运行环境

Codex 支持以下四种主要运行方式：

环境	说明
CLI（命令行环境）	轻量快速，最核心、功能最完整的环境。
IDE 插件环境	直接在 VS Code 中使用，具备交互式文件修改与撤销功能。
SDK 环境	可嵌入 Node.js 工程中，用代码直接调用 Codex。
云端环境	无需本地安装，通过网页与 GitHub 完成远程开发与代码审核。

其中最推荐的起点是 CLI 环境 —— 它是 Codex 的控制中心。

命令行环境安装与配置

1. 安装 Node.js

Codex CLI 依赖 Node.js 环境。 进入 Node.js 官网，根据系统下载并安装 LTS 版本即可。 安装完成后，终端输入：

node -v

若能正常输出版本号，说明 Node.js 安装成功。

2. 安装 Codex CLI

打开命令行或 PowerShell，输入：

npm install -g codex

等待安装完成。 你可以执行 codex --version 来验证安装是否成功。

3. 登录 OpenAI 账户

Codex CLI 默认使用 OpenAI 官方模型（GPT-5 / GPT-5-Codex）。 首次启动时会要求你登录 ChatGPT 账号。

codex

终端会自动打开浏览器，跳转至 OpenAI 登录页面。 登录完成后回到终端，输入一句：

Hello Codex!

若收到回复，说明配置成功。

模型选择与性能档位

使用命令：

codex model

可在不同模型间切换。

模型	特点
GPT-5	通用模型，支持代码、自然语言、分析类任务。
GPT-5-Codex	编程专用模型，优化代码生成与文件操作能力。

Codex 还支持三种性能档位（Reasoning Effort）：

档位	特点
Low	速度最快，逻辑简单任务。
Medium	平衡模式（推荐）。
High	推理最强但响应稍慢。

替代模型接入

未开通 ChatGPT Plus 时，可以通过国产开放模型 API 接入 Codex。

以下以 智谱大模型开放平台 为例：

1. 前往 docs.bigmodel.cn 注册账号；
2. 进入「账号设置 → 访问令牌」创建新的 API Key；
3. 打开模型库，筛选「支持推理 API」的模型（如 glm-4.6）；
4. 复制模型的 base_url 与 api_key。

然后编辑 Codex 配置文件：

• Windows：C:\Users\<用户名>\.codex\config.toml
• macOS/Linux：~/.codex/config.toml

示例：

model_name = "glm-4.6"
base_url = "https://api.xxx.com/v1"
api_key_env = "BIGMODEL_KEY"

⚠️ 注意： 不要在配置文件中直接写 API Key。 你需要在系统环境变量中新建一个变量：

变量名	变量值
BIGMODEL_KEY	你的 API Key

保存后重启 Codex，即可直接调用该模型。

注意事项

自定义模型存在一个小问题： 有时 Codex 会调用系统默认编辑器修改文件，效率较低。

解决方法：

在提示词中加入「请使用 Codex 内置编辑接口修改文件」， 可降低触发外部调用 Bug 的概率。

常用命令一览

命令	功能
/init	扫描当前目录并生成 AGENTS.md，帮助 Codex 理解项目结构。
/compact	压缩对话上下文，节省 token 并提高专注度。
/new	清空对话记录，开始新任务。
/approvals	调整 Codex 执行权限（手动 / 自动 / 全自动）。
/mcp	列出已安装的 MCP（Model Context Protocol）工具。

MCP 工具配置

MCP（Model Context Protocol）是 Codex 的插件机制， 让它能直接操作数据库、Excel、甚至网页浏览器。

例 1：安装 Context7 MCP

Context7 是由 Upstash 推出的一个开源 MCP Server。 它的核心目标是让 AI 编程助手能够实时访问最新的框架文档、API 用法与示例。

集成 Context7 后，Codex 可以在执行编程任务时做到：

1. 自动查询文档：识别你当前使用的框架或库，自动匹配正确的 API 文档和示例。
2. 版本感知开发：了解每个库的具体版本差异，避免'方法弃用'或'参数错误'问题。
3. 减少幻觉：不再凭空生成不存在的函数或类型，输出代码几乎总是与真实 API 匹配。
4. 提示增强：Codex 的提示上下文中自动注入对应库的技术知识。

基本安装配置

在 Codex 的 MCP server 配置文件（通常是 config.toml）中，添加以下内容：

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

解释：

• command = "npx"：让 Codex 通过 Node.js 的 npx 运行 Context7；
• args：传入运行参数，包括包名和认证密钥；
• YOUR_API_KEY：到 Upstash Context7 注册并生成的密钥。

完成后保存配置，重启 Codex CLI。 首次运行 Codex 时，它会自动加载 Context7，并显示类似：

✔ Loaded MCP server: context7

Windows 用户注意事项

若遇到 request timed out（请求超时）错误，可改用完整路径配置 Node.js 与包路径：

[mcp_servers.context7]
command = "C:\Program Files\nodejs\node.exe"
args = [
    "C:\Users\yourname\AppData\Roaming\npm\node_modules\@upstash\context7-mcp\dist\index.js",
    "--transport", "stdio",
    "--api-key", "YOUR_API_KEY"
]

或使用 CMD 启动方式：

[mcp_servers.context7]
command = "cmd"
args = ["/c", "npx", "-y", "@upstash/context7-mcp", "--api-key", "ctx7sk-06b8d8a7-827a-450d-92e3-c8ef9ea0c2ce"]
startup_timeout_sec = 20.0
[mcp_servers.context7.env]
SystemRoot = 'C:\Windows'

macOS 用户注意事项

如遇相同问题，可显式指定 Node.js 全路径：

[mcp_servers.context7]
command = "/Users/yourname/.nvm/versions/node/v22.14.0/bin/node"
args = [
    "/Users/yourname/.nvm/versions/node/v22.14.0/lib/node_modules/@upstash/context7-mcp/dist/index.js",
    "--transport", "stdio",
    "--api-key", "YOUR_API_KEY"
]

使用示例

帮我写一段使用 Prisma Client 连接 PostgreSQL 的示例代码

或：

Next.js 15 中的 app router 怎么动态加载组件？

Codex 将实时从 Context7 中提取对应框架的官方文档片段，生成完全匹配当前版本的写法。

例 2：安装 Excel MCP

Excel MCP 是一个通过 MCP 协议暴露的'表格自动化工具'， 让 Codex 能直接创建/读取/修改 Excel 文件（以及常见 CSV/表格操作）， 把'让 AI 写代码→写入表格→分析数据'这一整链路打通。

适用场景包括：批量报表生成、数据清洗、按规则高亮、排名/统计汇总、从代码输出到表格等。

作用

• 表格生成与导出：从自然语言需求直接生成结构化表格；
• 数据处理与统计：排序、筛选、分组、聚合、计算平均/中位数等；
• 格式与样式：条件高亮、前 n 名标记、列宽优化；
• 自动化工作流：与 Git/数据库 MCP 串联，做'拉数据→整形→导出→发 PR'。

安装配置

在 Codex 的 MCP 配置文件（通常是 config.toml）中添加如下配置（使用 Python uvx 运行）：

[mcp.excel]
command = "uvx"
args = ["excel-mcp", "--stdio"]

保存并重启 Codex 后，执行 /mcp 应能看到 excel 已被加载。

Windows 用户注意事项

如果你的系统没有正确识别 uvx，或遇到超时问题：

• 确保已安装好 Python/UV（pip install uv 或参考 uv 官方安装方式）；
• 必要时使用完整路径，例如：

[mcp_servers.excel]
command = "cmd"
args = ["/c", "uvx", "excel-mcp-server", "stdio"]
startup_timeout_sec = 20.0
[mcp_servers.excel.env]
SystemRoot = 'C:\Windows'

macOS 用户注意事项

若使用 uvx 命令不可用或存在多版本 Python，请显式写全路径：

[mcp.excel]
command = "/Users/yourname/.local/bin/uvx"
args = ["excel-mcp", "--stdio"]

或：

[mcp.excel]
command = "/opt/homebrew/bin/uvx"
args = ["excel-mcp", "--stdio"]

自定义命令

你可以在 .codex/prompts/ 文件夹里创建文件，来自定义命令。

例如新建 gitdiff.md：

比较 {{branch1}} 与 {{branch2}} 的差异，并用自然语言总结。

重启 Codex 后执行：

/cmd gitdiff main dev

Codex 就会自动对比两个分支并输出总结结果。 这种方式非常适合创建你的个性化开发指令库。

IDE 插件环境：VS Code 直接使用 Codex

打开 VS Code → Extensions，搜索 'OpenAI Codex' 并安装。

Codex 插件优点：

• 支持可视化文件对比；
• 支持'一键撤销（Undo）'；
• 支持粘贴图片进聊天窗口，便于 AI 理解 UI 或截图。

插件与 CLI 共用配置文件和历史记录，无需重复设置。

云端环境

Codex 还支持 云端开发模式。 访问官方网页端：

1. 登录并绑定 GitHub 账户；
2. 上传项目仓库；
3. 在网页输入修改指令（如'让按钮更显眼'）；
4. Codex 自动修改代码、创建 Pull Request；
5. 审核后合并，VS Code 可直接同步更新。

自动 Code Review 功能

打开「设置 → 启用自动代码审核」， Codex 会对每次 Pull Request 自动进行 Code Review。

例如它能提示：

'将 HTTPS 改为 HTTP 可能导致请求失败。'

这个功能在团队协作与代码质量保障上非常有用。

SDK 集成

如果你想让自己的项目直接调用 Codex，可使用官方 SDK。

使用步骤

npm init -y
npm install codex-sdk

创建 index.mjs：

import Codex from "codex-sdk";
const codex = new Codex();
const result = await codex.ask("写一个输出 Hello World 的 Python 程序");
console.log(result);

运行：

node index.mjs

若成功输出结果，说明 SDK 环境已正确配置。