AI 编程新王 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 | 推理最强但响应稍慢。 |
🆓 免费接入国产模型（替代 Plus 方案）
没开通 ChatGPT Plus？ 没关系——你可以通过国产开放模型 API 接入 Codex，实现免费使用。
以下以 智谱大模型开放平台 为例：
- 前往 docs.bigmodel.cn 注册账号；
- 进入「账号设置 → 访问令牌」创建新的 API Key；
- 打开模型库，筛选「支持推理 API」的模型（如
glm-4.6）； - 复制模型的
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 的概率。
🔧 Codex 常用命令一览
| 命令 | 功能 |
|---|---|
/init | 扫描当前目录并生成 AGENTS.md，帮助 Codex 理解项目结构。 |
/compact | 压缩对话上下文，节省 token 并提高专注度。 |
/new | 清空对话记录，开始新任务。 |
/approvals | 调整 Codex 执行权限（手动 / 自动 / 全自动）。 |
/mcp | 列出已安装的 MCP（Model Context Protocol）工具。 |
🧰 MCP 工具：让 Codex '会用外部软件'
MCP（Model Context Protocol）是 Codex 的插件机制，
让它能直接操作数据库、Excel、甚至网页浏览器。
例 1：安装 Context7 MCP
🧠 Context7 是什么？
Context7 是由 Upstash 推出的一个开源 MCP（Model Context Protocol）Server。
它的核心目标是：
让 AI 编程助手（如 Codex、Claude Code、Cursor 等）能够实时访问最新的框架文档、API 用法与示例，从而生成更准确、更贴近版本实际的代码。
换句话说，Context7 让 Codex 拥有'技术文档即时记忆'。
当你让 Codex 写 Next.js、React、Tailwind、Prisma 等框架代码时，
它会自动查询 Context7 提供的实时文档数据，从而避免'胡编 API'或引用旧版语法的问题。
例如，
当你让 Codex 生成 Next.js 15 的路由代码时，
它不再依赖模型训练时的旧语料，而是即时从 Context7 获取该版本的真实写法。
⚙️ Context7 的作用
集成 Context7 后，Codex 可以在执行编程任务时做到：
- 自动查询文档
- 识别你当前使用的框架或库；
- 自动匹配正确的 API 文档和示例。
- 版本感知开发
- 了解每个库的具体版本差异；
- 避免'方法弃用'或'参数错误'问题。
- 减少幻觉（Hallucination）
- 不再凭空生成不存在的函数或类型；
- 输出代码几乎总是与真实 API 匹配。
- 提示增强（Prompt Enrichment）
- Codex 的提示上下文中自动注入对应库的技术知识；
- 让模型生成代码时'有理有据'。
一句话总结：
Codex 负责思考与生成，Context7 负责提供真实知识。
🧩 在 OpenAI Codex 中安装 Context7
要让 Context7 为 Codex 提供文档支持，只需在 Codex 的 MCP 配置文件中添加一段配置。
官方推荐的配置方式如下：
🛠️ 基本安装配置
在 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 是什么？
Excel MCP 是一个通过 MCP 协议暴露的'表格自动化工具'，
让 Codex 能直接创建/读取/修改 Excel 文件（以及常见 CSV/表格操作），
把'让 AI 写代码→写入表格→分析数据'这一整链路打通。
适用场景包括：批量报表生成、数据清洗、按规则高亮、排名/统计汇总、从代码输出到表格等。
⚙️ Excel MCP 的作用
- 表格生成与导出：从自然语言需求直接生成结构化表格；
- 数据处理与统计：排序、筛选、分组、聚合、计算平均/中位数等；
- 格式与样式：条件高亮、前 n 名标记、列宽优化；
- 自动化工作流：与 Git/数据库 MCP 串联，做'拉数据→整形→导出→发 PR'。
一句话总结：
Codex 负责指令和逻辑，Excel MCP 负责把结果落地到真实表格。
🧩 在 OpenAI Codex 中安装 Excel MCP
在 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"]
✍️ 自定义命令（Prompt 级命令）
你可以在 .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 还支持 云端开发模式。
访问 codexgpt.com：
- 登录并绑定 GitHub 账户；
- 上传项目仓库；
- 在网页输入修改指令（如'让按钮更显眼'）；
- Codex 自动修改代码、创建 Pull Request；
- 审核后合并，VS Code 可直接同步更新。
自动 Code Review 功能
打开「设置 → 启用自动代码审核」，
Codex 会对每次 Pull Request 自动进行 Code Review。
例如它能提示：
'将 HTTPS 改为 HTTP 可能导致请求失败。'
这个功能在团队协作与代码质量保障上非常有用。
🧬 SDK 集成：让 Codex 嵌入你自己的程序
如果你想让自己的项目直接调用 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 环境已正确配置。
