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--versionnpm--version如果找不到命令先从 Node.js 官网安装受支持的 LTS 版本然后重新打开终端。2. 安装官方包npminstall-gopenai/codex codex--version注意包名是openai/codex。安装完成后可运行下面的命令查看当前版本支持的选项codex--help如果 Windows PowerShell 提示不能执行npm.ps1可以尝试用npm.cmd执行同一条安装命令不必为了安装而修改整台电脑的脚本策略npm.cmd install-g openai/codex3. 打开项目并登录在终端进入准备处理的项目目录然后启动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 官方说明六、需要外部工具时再接 MCPMCP 是连接模型应用和外部工具、数据源的一种协议。它可以用于查询文档、访问某个系统的数据或调用专门工具具体能力取决于接入的服务。原文举过查技术文档和处理 Excel 的例子。这里保留一个清楚的起点先接文档工具再按实际任务增加其他服务。例子接入 Context7 查询开发文档官方文档提供的 CLI 添加方式是codex mcpaddcontext7 -- npx-yupstash/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.mdSKILL.md的简化示例--- name: review-change description: 审查当前项目的代码改动检查行为变化、调用影响和测试覆盖。 --- 先阅读本次差异与相关调用代码。 说明改动解决什么问题再检查异常路径和兼容性。 只报告有代码依据的问题并附文件位置。 最后列出已经完成和仍未完成的验证。这适合把已经用顺手的流程固定下来。只是一两句临时要求时直接输入即可。技能的发现位置与使用方式见 官方 Skill 文档。八、IDE、网页和 SDK 怎么选在编辑器里协作经常使用 VS Code 的读者可以从 Codex 官方 IDE 扩展说明进入安装核对发布方后登录。使用时先打开项目再选中需要解释的代码或者描述要修改的行为。一个实用习惯是让它先指出相关文件再实施改动最后在编辑器里查看差异。用桌面端或网页组织任务希望通过图形界面管理项目和多项任务可以从 官方快速开始选择适合的入口。使用云端任务时按界面要求准备代码仓库、环境和访问权限再检查执行结果。无论从哪个入口使用把“一次完成整个系统”拆成可以检查的任务通常更便于协作例如“先解释这个模块”“补一个边界测试”“修复这一处错误”。在自己的程序里调用 Codex需要将 Codex 接入开发流程时可以使用官方 SDK。普通交互使用不需要安装它。在一个已经初始化的 Node.js 项目中安装npminstallopenai/codex-sdk创建review.mjsimport{Codex}fromopenai/codex-sdk;constclientnewCodex();constreviewThreadclient.startThread();constreviewResultawaitreviewThread.run(阅读当前项目的 README说明启动方式与测试步骤不要修改文件。);console.log(reviewResult.finalResponse);在已准备好认证的项目目录中执行nodereview.mjsSDK 应在服务端环境使用运行需要满足其环境和认证要求并可能消耗相应的模型用量。这段展示的是基本调用结构具体选项见 官方 SDK 文档。九、遇到问题先分清是哪一层现象优先检查找不到node、npm或codex是否安装成功、终端是否重开、PATH 是否包含相应目录登录完成但无法使用登录账号、使用权限、当前网络与错误提示API 返回认证错误Key 是否属于当前平台环境变量是否在当前进程中生效提示额度不足当前使用的是哪种计费方式礼包是否适用于这个模型换模型地址后无法调用接口协议、模型名称、地址与认证方式是否匹配MCP 无法启动启动命令、依赖、认证和网络查看实际错误不反复堆配置AI 修改偏离目标输入文件、允许修改范围、输出要求和验收条件是否明确把完整错误信息交给 Codex 时先隐去密钥等敏感内容并说明执行了什么命令、期待什么结果。只有“不能用”三个字往往不足以定位问题。最后从一个小任务开始第一次使用不妨只做一件事让 Codex 解释一个项目、修复一个小问题或者写出一个处理表格的脚本。完成后检查结果再决定下一步需要模型 API、MCP 还是 SDK。如果你准备进一步做自己的 AI 应用还没有模型服务账号也可以通过我的邀请链接注册智谱 BigModel领取新用户 Tokens 礼包。按活动要求领取后先从一个小型 API 示例开始具体福利以活动页为准符合规则时我也可能获得推荐奖励。把一个真实问题解决掉比一次记住所有功能更有帮助。