Codex 上手指南：从安装配置到 AI 编程实战（2026 更新）

更新说明：本文最初发表于 2025 年，现已于 2026 年 9 月更新安装命令、模型服务说明、MCP 与 SDK 示例，并替换失效的注册链接。旧版部分配置已不再适用，请以本文更新内容为准。命令与功能参考官方文档，界面和可用模型以你安装的版本及账号为准。

想用 AI 帮忙写代码，却卡在安装、账号和配置上？或者已经装好了 Codex，却不知道除了问答还能拿它做什么？

这篇文章按实际使用顺序，把安装、第一次任务、模型服务选择，以及 MCP、项目说明和 SDK 串起来。你可以先跑通一个小任务，再按需要增加功能。

一、先选一个适合自己的入口

Codex 可以围绕项目读取代码、修改文件、执行命令，帮助你理解项目、修复问题和实现功能。使用时，最好把任务放在一个明确的项目目录里，让它知道要处理哪些文件。

常见入口可以这样选择：

入口	适合的使用方式
命令行 CLI	已经习惯终端，希望在项目目录里直接开始工作
IDE 扩展	平时主要在 VS Code 等编辑器里开发，希望边看代码边协作
桌面端	希望通过图形界面组织项目、文件和任务
网页与云端任务	希望在支持的云端环境中处理代码任务
SDK	希望从自己的程序里启动或继续 Codex 任务

第一次接触，可以先用 CLI 或 IDE 扩展。下载和其他入口从 OpenAI 官方快速开始进入，避免把第三方同名网站误认为官方服务。

二、安装 CLI，完成第一次任务

1. 准备 Node.js 和 npm

下面采用 npm 安装方式。先在终端检查：

node --version
npm --version

如果找不到命令，先从 Node.js 官网安装受支持的 LTS 版本，然后重新打开终端。

2. 安装官方包

npm install -g @openai/codex
codex --version

注意包名是 @openai/codex。安装完成后，可运行下面的命令查看当前版本支持的选项：

codex --help

如果 Windows PowerShell 提示不能执行 npm.ps1，可以尝试用 npm.cmd 执行同一条安装命令，不必为了安装而修改整台电脑的脚本策略：

npm.cmd install -g @openai/codex

3. 打开项目并登录

在终端进入准备处理的项目目录，然后启动：

codex

按提示选择登录方式。使用 ChatGPT 账号时，需要确认账号具备相应的 Codex 使用权限；使用 OpenAI API Key 时，按 API 方式配置和计费。两种方式不要混为一谈，具体见 官方认证说明。

4. 先给它一个范围清楚的任务

已有项目可以先这样问：

先阅读这个项目，告诉我：
1. 项目主要做什么。
2. 从哪个文件开始运行。
3. 怎样启动和执行测试。
这一步先不要修改文件。

如果手边没有项目，就创建一个空的练习目录，再让它完成一个小脚本：

帮我写一个 Python 脚本：读取当前目录的 input.csv，
保留原有字段和顺序，移除完全重复的记录，写入 output.csv。
不要覆盖输入文件。
请补一份小样例，检查重复记录是否正确移除，最后说明运行方法。

这个练习能让你看清一次完整协作：说明需求、生成文件、运行检查、查看结果。完成后再检查代码差异和输出，确认它做的事情符合你的要求。

三、模型、账号和费用，该怎么理解？

使用 AI 编程时，容易把几件事混在一起：编程工具、背后的模型服务，以及自己的应用需要调用的 API。

例如，你可以让 Codex 帮你开发一个“整理 Excel 文本”的程序；这个程序运行时使用哪家模型 API，是另一项选择。用什么工具写程序，和程序最终调用什么模型，可以分别决定。

大致分清下面几类就够了：

需求	需要确认什么
用 Codex 帮自己写代码	登录方式、账号权限、当前可用模型与用量
用自己的程序调用模型	模型 API、API Key、调用费用或资源额度
使用某个平台的编程订阅套餐	套餐支持哪些工具、接口及使用范围

准备一个模型服务账号，方便后面做应用

如果你也想试试国产大模型，或者准备做自己的 AI 应用，可以先注册智谱大模型开放平台 BigModel。后续无论是整理文本、抽取表格字段，还是为应用增加问答功能，都可以从熟悉模型 API 的使用方式开始。

按平台当前邀请活动说明，通过下面的链接注册，可获得 2000 万 Tokens 新用户礼包。 还没有账号的朋友，可以从这里开始：

👉 点击注册智谱 BigModel，领取 2000 万 Tokens 新用户礼包

注册后，按活动页面提示完成领取要求，在账号内查看礼包是否到账、适用模型以及有效期。准备调用 API 时，再按照平台文档创建自己的 API Key，并妥善保存。

推荐说明：这是我的邀请链接。你按活动规则领取新用户福利，我也可能获得平台推荐奖励。礼包的具体领取条件与使用范围，以活动页面和账号内显示为准。

接下来，你可以把 智谱官方快速开始交给 Codex，请它帮你搭一个最小示例：

请参考智谱官方快速开始，为当前项目添加一个最小的模型 API 调用示例。
API Key 从环境变量读取，不要写进代码。
模型名称做成可配置项，我会填写账号中可用的模型。
先生成代码和运行说明，处理认证失败、额度不足和请求超时。
这一步不要实际发送付费请求。

这样，注册账号就接到了一个具体任务上：让 Codex 帮你写应用，再由应用使用模型服务。运行示例前，填好本地环境变量，确认所选模型的费用和礼包适用范围。密钥不需要发到聊天里，也不要提交到代码仓库。

能不能直接把智谱模型接到 Codex？

需要看接口兼容性，不能只改一个地址就默认能用。

当前 Codex 配置参考中，模型提供方的 wire_api 只列出 responses。提供 Chat Completions 兼容接口，并不自动意味着满足 Codex 的接口要求。

因此，本文不提供未经验证的直连配置。需要在编程工具里使用智谱时，应按平台最新的 编程套餐接入说明，确认工具支持、接口地址和套餐范围。新用户 Tokens 礼包也不能直接理解为 Codex 订阅或编程套餐。

四、日常使用，先记住这些命令

终端命令与对话里的斜杠命令是两回事：codex --help 在终端执行，/model 则在 Codex 的交互输入框里输入。

交互命令	用途
/model	选择当前账号与环境可用的模型及相关选项
/status	查看当前会话状态
/new	开始新会话
/compact	压缩较长会话的上下文
/init	生成可供完善的 AGENTS.md 项目说明
/mcp	查看 MCP 相关信息
/permissions	查看或调整当前权限设置

功能名称可能随版本调整；在输入框键入 /，以当前菜单为准。官方命令说明

模型和推理强度不用一开始就反复纠结。先用默认设置完成任务；遇到复杂设计、跨文件排错，再尝试当前模型支持的更高推理强度。判断结果时，看修改是否正确、测试是否通过，而不仅是回答有多长。

五、把项目习惯写进 AGENTS.md

如果每次都要重复告诉 AI“不要改编码”“先看 README”“测试怎么运行”，可以把这些稳定要求写成项目说明。

在 Codex 中运行 /init 后，检查生成的内容，再按项目实际情况修改。例如：

# 项目说明

## 开始前
- 先阅读 README，确认目录结构和运行方式。
- 保留现有文件编码和换行格式。

## 修改要求
- 只处理本次需求涉及的内容。
- 不把密钥、账号密码写入代码或示例文件。
- 改动公共接口时，说明受影响的调用方。

## 验证要求
- 优先使用项目已有的测试命令。
- 无法执行的测试明确写出来，不声称已经通过。

这份文件应写项目里确实适用的规则，具体测试命令也要来自项目本身。它适合保存长期约定，临时需求仍直接在任务里说明。AGENTS.md 官方说明

六、需要外部工具时，再接 MCP

MCP 是连接模型应用和外部工具、数据源的一种协议。它可以用于查询文档、访问某个系统的数据或调用专门工具，具体能力取决于接入的服务。

原文举过查技术文档和处理 Excel 的例子。这里保留一个清楚的起点：先接文档工具，再按实际任务增加其他服务。

例子：接入 Context7 查询开发文档

官方文档提供的 CLI 添加方式是：

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

查看已配置的服务：

codex mcp list

如果服务要求认证或出现调用限制，再按该服务的文档完成设置。进入 Codex 后，可以给出这样的任务：

先通过 Context7 查询这个项目使用的框架版本对应的文档，
再解释当前代码里的这个接口应该怎么调用。
请标明文档依据，不要先凭印象修改代码。

接入方式与配置项见 Codex MCP 文档。这里的命令用于添加配置，并不保证你的网络、运行环境和服务认证已经准备完毕。

Excel 不一定要先装 MCP

如果只是读取本地表格、去重、生成汇总，先让 Codex 用项目已有的 Python 或其他工具处理即可。确实需要某个 Excel 服务提供的能力时，再选对应的 MCP 实现。

给任务时说明输入、规则和输出，例如：

读取当前目录的 sales.xlsx，按“月份”和“部门”汇总销售额。
空值单独列出，不直接当作 0。
输出到一个新文件，并说明原始行数和汇总规则。

比起一次装很多扩展，先把任务说明白，通常更容易发现缺的究竟是哪项能力。

七、重复做的工作，可以整理成 Skill

如果某项工作需要固定步骤，例如代码审查、生成测试说明、整理发布记录，就可以把流程整理成 Skill。

项目内可以使用这样的目录结构：

.agents/
  skills/
    review-change/
      SKILL.md

SKILL.md 的简化示例：

---
name: review-change
description: 审查当前项目的代码改动，检查行为变化、调用影响和测试覆盖。
---

先阅读本次差异与相关调用代码。
说明改动解决什么问题，再检查异常路径和兼容性。
只报告有代码依据的问题，并附文件位置。
最后列出已经完成和仍未完成的验证。

这适合把已经用顺手的流程固定下来。只是一两句临时要求时，直接输入即可。技能的发现位置与使用方式见 官方 Skill 文档。

八、IDE、网页和 SDK 怎么选？

在编辑器里协作

经常使用 VS Code 的读者，可以从 Codex 官方 IDE 扩展说明进入安装，核对发布方后登录。

使用时先打开项目，再选中需要解释的代码，或者描述要修改的行为。一个实用习惯是：让它先指出相关文件，再实施改动，最后在编辑器里查看差异。

用桌面端或网页组织任务

希望通过图形界面管理项目和多项任务，可以从 官方快速开始选择适合的入口。使用云端任务时，按界面要求准备代码仓库、环境和访问权限，再检查执行结果。

无论从哪个入口使用，把“一次完成整个系统”拆成可以检查的任务，通常更便于协作，例如“先解释这个模块”“补一个边界测试”“修复这一处错误”。

在自己的程序里调用 Codex

需要将 Codex 接入开发流程时，可以使用官方 SDK。普通交互使用不需要安装它。

在一个已经初始化的 Node.js 项目中安装：

npm install @openai/codex-sdk

创建 review.mjs：

import { Codex } from "@openai/codex-sdk";

const client = new Codex();
const reviewThread = client.startThread();
const reviewResult = await reviewThread.run(
  "阅读当前项目的 README，说明启动方式与测试步骤，不要修改文件。"
);

console.log(reviewResult.finalResponse);

在已准备好认证的项目目录中执行：

node review.mjs

SDK 应在服务端环境使用，运行需要满足其环境和认证要求，并可能消耗相应的模型用量。这段展示的是基本调用结构，具体选项见 官方 SDK 文档。

九、遇到问题，先分清是哪一层

现象	优先检查
找不到 node、npm 或 codex	是否安装成功、终端是否重开、PATH 是否包含相应目录
登录完成但无法使用	登录账号、使用权限、当前网络与错误提示
API 返回认证错误	Key 是否属于当前平台，环境变量是否在当前进程中生效
提示额度不足	当前使用的是哪种计费方式，礼包是否适用于这个模型
换模型地址后无法调用	接口协议、模型名称、地址与认证方式是否匹配
MCP 无法启动	启动命令、依赖、认证和网络；查看实际错误，不反复堆配置
AI 修改偏离目标	输入文件、允许修改范围、输出要求和验收条件是否明确

把完整错误信息交给 Codex 时，先隐去密钥等敏感内容，并说明执行了什么命令、期待什么结果。只有“不能用”三个字，往往不足以定位问题。

最后，从一个小任务开始

第一次使用，不妨只做一件事：让 Codex 解释一个项目、修复一个小问题，或者写出一个处理表格的脚本。完成后检查结果，再决定下一步需要模型 API、MCP 还是 SDK。

如果你准备进一步做自己的 AI 应用，还没有模型服务账号，也可以通过 我的邀请链接注册智谱 BigModel，领取新用户 Tokens 礼包。按活动要求领取后，先从一个小型 API 示例开始；具体福利以活动页为准，符合规则时我也可能获得推荐奖励。

把一个真实问题解决掉，比一次记住所有功能更有帮助。