Codex 中文教程：安装、配置与项目实战

Codex 是 OpenAI 的编程代理，可以阅读项目文件、修改代码、运行命令并检查结果。它与普通聊天式代码生成的主要区别，是能够围绕一个真实工作目录持续执行任务，而不只是返回一段需要手动复制的代码。

真正有效的使用方式不是把整个项目交给 Codex 后等待结果，而是给它明确目标、合适权限和可以执行的验收步骤，再由你审查最终差异。

先选择适合自己的 Codex 入口

Codex 有多种使用入口，底层协作思路相近，但适合的工作环境不同。

Codex CLI：直接在终端和本地仓库中工作，适合开发者、服务器环境和自动化任务
IDE 扩展：在编辑器中查看文件和差异，适合边阅读边修改代码
桌面端：官方文档当前将其归入 ChatGPT 桌面应用中的 Codex 工作方式，适合图形界面操作、项目规划和变更审查
Codex Cloud：任务在托管环境中运行，适合将独立任务交给云端处理

如果你第一次使用，CLI 或 IDE 扩展更容易理解 Codex 实际改了什么。喜欢图形界面可以选择桌面端，但安装前应以 Codex App 官方页面显示的平台支持和系统要求为准。

安装 Codex CLI

Codex CLI 官方页面会根据操作系统提供独立安装器、npm 和 Homebrew 等方式。macOS 或 Linux 当前可以使用官方独立安装脚本：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

执行远程脚本前应确认域名和命令来源。团队设备或受管环境建议先查看脚本内容，再按内部软件安装规范操作。

安装后检查命令是否可用：

codex --version

如果终端提示找不到命令，先关闭并重新打开终端，再检查安装目录是否已经加入 PATH。Windows、npm 和 Homebrew 的具体命令可能更新，建议从 Codex CLI 官方页面获取当前版本，而不是长期保存旧下载地址。

登录方式：ChatGPT 还是 API Key

本地 Codex 支持两类官方登录方式：使用 ChatGPT 账号登录，或使用 API Key 按调用量计费。Codex Cloud 需要使用 ChatGPT 登录。

首次运行：

codex

没有有效会话时，CLI 会引导你完成登录。也可以主动运行：

codex login
codex login status

使用官方 API Key 时，不要把密钥直接写进命令历史或项目文件。可以先放入环境变量，再通过标准输入登录：

printenv OPENAI_API_KEY | codex login --with-api-key

选择登录方式时需要区分两件事：ChatGPT 订阅权益与 API 按量计费不是同一个计费入口；API Key 登录也不等于自动获得 ChatGPT 工作区或云任务能力。

可选方案：配置 DKAI Codex 中转站

在无法直接使用官方 API，或者需要独立管理 Codex 调用额度时，可以评估兼容的第三方中转服务。本站提供的可选方案是 DKAI Codex 中转站，文章底部的入口属于商业推广链接。注册和付费前应自行确认价格、隐私政策、日志保留、模型兼容性和服务可用性。

参考资料中的配置流程可以整理为五步：

安装 Codex CLI、IDE 扩展或桌面端
在 DKAI 后台创建 API 密钥，并选择与 Codex 对应的分组
打开“使用密钥”，选择当前操作系统和工具
阅读平台生成的配置内容，确认路径和域名后再执行
重启 Codex，用一个小任务验证连接和模型响应

配置脚本通常会修改用户目录下的 Codex 配置。执行覆盖前，建议备份 ~/.codex/config.toml；不要在截图、聊天记录、Git 仓库或公开日志中暴露密钥。

Codex 官方配置支持代理地址和自定义模型提供方，但不同服务的地址、请求协议和模型名称可能变化。优先使用服务后台针对当前 Codex 版本生成的说明，不要从旧文章复制一段长期不变的配置。

第一次启动前先选对目录

Codex 会围绕当前工作目录理解项目。启动前先进入目标目录：

cd /path/to/your-project
codex

不要在用户主目录、服务器根目录或包含大量无关文件的位置直接启动并授予写权限。目录边界越清楚，Codex 越容易找到相关文件，也越不容易触碰无关内容。

已有项目最好先确认 Git 状态：

git status

如果目录中已经有未提交修改，先弄清这些修改来自哪里。Codex 应当在保留现有工作成果的前提下继续，而不是把不认识的改动恢复掉。

用一个真实任务完成首次实践

第一次任务可以选择“为现有项目增加健康检查页面”。它会涉及阅读结构、复用样式、实现路由和运行验证，但改动范围仍然容易控制。

先阅读当前项目的目录结构、启动方式和路由写法，不要立即修改。

目标：增加一个 /health 页面，显示应用状态、当前版本和检查时间。
约束：复用现有框架和页面样式，不引入新依赖，不修改无关模块。
安全：页面不能输出数据库密码、API Key、绝对路径或完整异常堆栈。
验收：路由返回 200，手机宽度下正常显示，现有测试继续通过。

请先说明计划修改哪些文件；完成后运行项目已有的语法检查和测试，
最后列出改动、验证结果以及仍未验证的部分。

这个任务没有指定具体代码，却明确了阅读顺序、功能目标、禁止事项和验收条件。Codex 可以根据项目实际结构选择实现，而结果仍然可以被检查。

权限和沙箱不要一开始就开到最大

Codex CLI 可以控制文件系统沙箱和命令审批。初次使用时，保持工作区写入和按需确认通常更稳妥：Codex 可以修改当前项目，但访问额外目录、网络或敏感命令时需要确认。

审批提示不是需要无脑点击的障碍。确认前至少看清：

命令会读写哪个目录
是否安装新依赖或访问网络
是否修改数据库、系统服务或部署环境
是否包含删除、覆盖或权限变更
为什么完成当前任务必须执行这条命令

绕过审批和沙箱的模式只适合已经由外部环境隔离、任务和命令都受控的自动化场景，不应作为日常默认设置。

让 Codex 先读项目再写代码

面对已有项目，可以先单独下达阅读任务：

阅读项目入口、依赖文件、README 和测试配置。
总结应用如何启动、数据如何流动、有哪些现成的验证命令。
本轮不要修改文件，并指出你仍不确定的信息。

这一步可以暴露错误假设。等 Codex 的理解与项目实际情况一致后，再给出具体修改任务，通常比一开始直接要求“重构整个项目”更可靠。

项目中还可以使用 AGENTS.md 保存长期规则，例如测试命令、代码风格、禁止修改的目录和交付要求。一次性需求仍然写在当前提示中，不要把临时任务全部塞进长期规则文件。

审查结果时不要只看最终回答

Codex 的文字总结只是线索，真正需要确认的是文件差异和运行结果。

查看修改了哪些文件，有没有超出任务范围
检查输入验证、权限、错误处理和数据写入
运行项目已有的 lint、类型检查和测试
手动验证正常、空数据、错误输入和未授权状态
前端改动同时检查桌面与移动端
确认没有把密钥、日志或临时文件加入版本库

Codex CLI 还提供代码审查能力，但代理审查不能代替对高风险业务逻辑的人工确认。认证、支付、隐私数据和生产数据库操作需要更严格的复核。

常见问题排查顺序

输入 codex 后提示找不到命令

重新打开终端，运行 codex --version，再检查安装方式对应的目录是否位于 PATH。不要通过下载来源不明的同名程序解决。

登录成功但无法调用

运行 codex login status 确认当前登录方式。API Key 用户还要检查账户余额、组织权限和环境变量；第三方服务用户应检查分组、接口地址、模型兼容性和平台状态。

Codex 修改了错误的项目

检查启动时的当前目录和 Git 根目录。退出后进入正确项目目录重新开始，并在提示中明确允许修改的范围。

一直要求确认命令

先判断命令是否超出当前沙箱或涉及网络。频繁确认可能说明任务需要额外权限，也可能说明任务拆分得不够清楚。不要为了省一次点击就长期关闭所有审批。

修改完成但结果不能运行

把完整报错、触发步骤和实际运行命令交给 Codex，让它先复现再修复。只说“还是不行”通常无法提供足够上下文。

Codex 适合处理哪些工作

Codex 擅长围绕明确项目完成可验证任务：

阅读陌生代码并解释模块关系
增加功能、修复缺陷和重构局部代码
编写测试、运行检查并分析失败
整理 README、接口说明和开发计划
编写构建、数据处理和日常自动化脚本
审查未提交修改、提交或分支差异

它不应在无人监督的情况下获得生产环境无限权限。任务越接近真实用户数据、资金或基础设施，越要缩小权限、增加测试并保留回滚方案。

把一次成功任务变成稳定工作流

高效使用 Codex 的关键不是记住更多命令，而是形成固定闭环：进入正确目录，说明目标和边界，让 Codex 先理解项目，审查修改，运行验证，再根据证据继续迭代。

工具界面和安装方式会更新，但这套流程不会轻易过时。只要你始终掌握目录、权限和验收标准，Codex 才能成为可靠的工程协作者，而不是不可控的代码生成器。