OpenAI Codex 全面上手指南

替代模型接入

未开通 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。 你需要在系统环境变量中新建一个变量：

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

注意事项

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

解决方法：

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

常用命令一览

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 环境已正确配置。