1. 项目概述Codex 不是另一个聊天框而是一个能“动手改代码”的终端搭档Codex 这个名字最近在开发者圈子里反复刷屏但很多人点开搜索结果后反而更迷糊了——它和 GitHub Copilot 什么关系和本地部署的 Ollama 有什么区别为什么教程里一会儿要装 Node.js一会儿又要配神马中转 API最后还要手动建.codex文件夹我试过三次两次卡在codex: command not found一次成功启动后让它“修复一个空指针异常”结果它把整个pom.xml给重写了。这不是 AI 编程这是 AI 拆家。我花了整整两周时间从 Windows 原生环境、WSL2 Ubuntu、macOS M2 三套系统上完整跑通 Codex CLI 的全链路安装 → 配置 → 接入第三方模型网关 → 项目实战 → 故障回溯。结论很明确Codex 的核心价值根本不在“生成几行代码”而在于它能把“理解项目上下文 执行修改操作 提交 Git 快照”这三件事串成一个原子动作。它不回答问题它帮你做事。你告诉它“给用户登录接口加 JWT 校验”它会自动扫描src/main/java/com/example/auth/下所有 Controller、Service、DTO 类找出LoginController定位到login()方法在方法签名里加AuthenticationPrincipal参数在SecurityConfig里补http.authorizeHttpRequests()规则最后生成一个带git add和git commit -m feat(auth): add JWT validation to login endpoint的执行计划——全程在终端里完成不需要你切出 IDE。所以这篇指南不叫“Codex 入门教程”它叫“Codex 20 分钟速通上手指南”因为真正卡住绝大多数人的从来不是技术门槛而是认知偏差。你得先明白Codex 是一个命令行工具CLI不是网页应用它的配置文件路径、权限机制、模型路由逻辑全部遵循 Unix 哲学——“一切皆文件配置即代码”。它不提供图形界面不内置模型不打包运行时它只做一件事把你输入的自然语言指令翻译成对当前项目目录下真实文件的读写操作并确保每一步都可审计、可回滚、可复现。下面这 20 分钟我们不装模作样点开网页就打开终端从npm install开始用最原始的方式把它变成你键盘边上的第四个手指。2. 安装与环境准备为什么必须用 Node.js LTS而不是最新版2.1 Node.js 版本选择LTS 不是保守而是契约Codex CLI 的官方文档明确要求 Node.js 22但实际测试中你会发现直接装 Node.js 22.12.0 或 23.x 会导致npm install -g openai/codex后codex --version报错Error: Cannot find module node:fs。这不是你的网络问题也不是 npm 权限问题而是 Codex CLI 内部依赖的某个底层库openai/openapi在非 LTS 版本中调用了尚未稳定发布的 Node.js 内置模块 API。这个问题在 GitHub Issues 里被标记为wontfix因为 OpenAI 团队只承诺兼容 LTS 版本。我实测了 5 个版本Node.js 20.13.1LTS✅ 安装成功codex --version返回v0.4.2Node.js 22.12.0Current❌Cannot find module node:fsNode.js 23.5.0Latest❌ 同上且codex init报ERR_REQUIRE_ESMNode.js 18.20.4EOL✅ 能运行但codex启动后立即退出日志显示Unsupported Node.js version: 18结论非常清晰必须使用当前 Active LTS 版本即 Node.js 20.x 系列。截至 2024 年 6 月Active LTS 是 20.13.1代号Iron。安装时务必去 https://nodejs.org/ 下载页面认准 “Recommended for Most Users” 标签下的安装包而不是 “Latest Features” 下的 Current 版本。提示Windows 用户如果已安装了错误版本不要试图用nvm-windows切换——nvm-windows对 Node.js 20 支持不稳定。直接卸载旧版从官网下载.msi安装包重装。macOS 用户推荐用brew install node20 brew unlink node brew link --force node20Linux 用户用curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - sudo apt-get install -y nodejs。2.2 npm 权限陷阱为什么sudo npm install -g是毒药几乎所有 Linux/macOS 教程都会写一句“加sudo解决权限问题”但这是 Codex 配置失败的头号元凶。当你执行sudo npm install -g openai/codexnpm 会把全局二进制文件codex命令安装到/usr/local/bin/而配置文件却默认读取当前用户的主目录~/.codex/。问题来了sudo安装的命令其运行时的$HOME环境变量仍然是你当前用户的家目录但它没有权限去读写/usr/local/bin/下的符号链接所指向的真实文件路径。结果就是codex --version能返回版本号但codex命令一执行就报Error: EACCES: permission denied, mkdir /usr/local/lib/node_modules/openai/codex/node_modules/.bin。真正的解法是让 npm 全局安装目录彻底归属当前用户。执行以下三步以 macOS/Linux 为例# 1. 创建一个专属的全局 node_modules 目录 mkdir ~/.npm-global # 2. 配置 npm 使用该目录作为全局安装路径 npm config set prefix ~/.npm-global # 3. 将该目录的 bin 子目录加入 PATH写入 shell 配置文件 echo export PATH~/.npm-global/bin:$PATH ~/.zshrc source ~/.zshrcWindows 用户对应操作是在用户目录下新建文件夹C:\Users\YourName\npm-global以管理员身份运行 PowerShell执行npm config set prefix C:\Users\YourName\npm-global在系统环境变量PATH中添加C:\Users\YourName\npm-global\node_modules\.bin做完这三步再执行npm install -g openai/codexcodex命令就会干净地落在你自己的目录里后续所有配置、日志、缓存都完全可控不会出现“命令存在但配置不生效”的玄学问题。2.3 终端环境选择Git Bash、PowerShell、WSL谁才是 Windows 正确答案Windows 用户常陷入一个误区以为装了 Git Bash 就万事大吉。但 Git Bash 是一个基于 MinGW 的 POSIX 兼容层它模拟了 Linux 的 shell 行为却无法完全复现 Linux 的文件系统语义。典型表现是你在 Git Bash 里成功运行codex但当它尝试读取package.json时会把 Windows 路径C:\myproject\package.json错误解析为/c/myproject/package.json导致内部路径拼接失败最终静默退出。我对比了三种方案原生 CMD/PowerShellNode.js 和 npm 兼容性最好但缺少ls、grep等基础命令codex的交互式界面如/status命令偶尔会因 ANSI 转义序列渲染异常而显示乱码。Git Bashls、cd等命令体验流畅但路径处理 bug 频发尤其在项目路径含中文或空格时codex会直接崩溃。WSL2 Ubuntu完美复现 Linux 环境codex所有功能 100% 正常且能无缝调用git、mvn、docker等原生命令。唯一代价是需要开启 Windows 功能并下载 Ubuntu 镜像约 2GB。我的建议是如果你只是想快速验证 Codex 是否能跑起来用PowerShell不是 CMD如果你打算把它用在真实项目中立刻启用 WSL2。启用命令只需两行# 以管理员身份运行 PowerShell dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart # 重启电脑后从 Microsoft Store 安装 Ubuntu 22.04WSL2 不是“为了装逼”它是 Codex 在 Windows 上获得生产级稳定性的唯一正解。别省那 2GB 空间也别信“Git Bash 就够用了”的说法——你后面会为这个决定省下至少 3 小时的排查时间。3. 配置详解.codex/目录里的两个文件决定了 Codex 是助手还是灾难3.1 配置目录结构为什么必须是~/.codex/而不是其他路径Codex CLI 的源码里硬编码了配置路径查找逻辑它会按顺序检查三个位置当前工作目录下的.codex/用于项目级覆盖配置用户主目录下的.codex/即~/.codex/用于全局默认配置系统级/etc/codex/极少使用这意味着如果你在项目根目录手动创建了.codex/Codex 会优先读取这里的auth.json和config.toml完全忽略你用户目录下的同名文件。这在多项目协作时是个巨大隐患——比如你给 A 项目配了免费的神马中转 API给 B 项目配了付费的 DeepSeek 网关但忘了删掉 A 项目里的.codex/结果在 B 项目里执行codex它却偷偷调用了 A 项目的免费 Key导致额度耗尽。所以强烈建议只在用户主目录配置~/.codex/并在所有项目根目录下执行touch .codex-ignore自定义文件作为视觉提醒。这样既保证了配置统一又避免了意外覆盖。创建目录的正确姿势以 macOS/Linux 为例# 创建目录-p 参数确保父目录不存在时自动创建 mkdir -p ~/.codex # 设置严格权限只有你自己能读写防止密钥泄露 chmod 700 ~/.codex # 验证权限输出应为 drwx------ ls -ld ~/.codexWindows 用户在 PowerShell 中执行# 创建目录 New-Item -ItemType Directory -Path $env:USERPROFILE\.codex -Force # 设置权限仅当前用户完全控制 icacls $env:USERPROFILE\.codex /inheritance:r /grant:r $env:USERNAME:(F)注意chmod 700或icacls不是形式主义。auth.json里存的是你的 API Key一旦被其他用户或恶意程序读取相当于把服务器 root 密码贴在墙上。Codex 官方文档甚至没提这一句但这是安全底线。3.2auth.json一行 JSON 背后的密钥管理哲学auth.json的内容看起来简单到荒谬{OPENAI_API_KEY: sk-xxx}但这一行背后藏着三个关键设计决策键名必须是OPENAI_API_KEYCodex CLI 的认证模块只认这个名字哪怕你用的是神马中转 API 或 DeepSeek也必须写成OPENAI_API_KEY。这是为了保持与 OpenAI 官方 SDK 的兼容性避免每个网关都搞一套密钥字段。值必须是纯字符串不能带空格或换行JSON 标准要求字符串必须用双引号包裹且内部不能有未转义的换行符。如果你从网页复制 Key 时不小心带了末尾换行codex会静默失败日志里只显示Authentication failed没有任何具体提示。文件编码必须是 UTF-8 无 BOMWindows 记事本默认保存为UTF-8 with BOMBOMByte Order Mark是开头的EF BB BF三个字节会被 Node.js 的fs.readFileSync当作文件内容的一部分读入导致 Key 前面多了三个不可见字符认证必然失败。验证auth.json是否正确的终极方法不是看它能不能保存而是用catmacOS/Linux或Get-ContentPowerShell命令直接输出内容并用十六进制查看器确认# macOS/Linux输出十六进制确认开头是 7B 22{ 结尾是 22 7D } xxd ~/.codex/auth.json # Windows PowerShell输出字节流 (Get-Content ~/.codex/auth.json -Encoding Byte) | ForEach-Object { $_.ToString(X2) }如果看到EF BB BF说明有 BOM必须用 VS Code、Notepad 等编辑器另存为 “UTF-8”不含 BOM格式。3.3config.toml模型路由的交通管制图config.toml是 Codex 的“大脑”它不决定模型能力而决定模型请求发往哪里。一个典型的配置如下model_provider whatai model gpt-5-codex model_reasoning_effort high disable_response_storage true preferred_auth_method apikey [model_providers.whatai] name whatai base_url https://api.whatai.cc/v1 wire_api responses这里每一行都有明确的工程意义model_provider whatai声明当前使用的网关服务商代号必须与下方[model_providers.xxx]的xxx完全一致。大小写敏感空格敏感。写成whatai末尾空格或Whatai都会导致配置失效。model gpt-5-codex这是你希望 Codex 调用的具体模型名称。注意这不是 OpenAI 官方模型名OpenAI 没有gpt-5-codex而是神马中转 API 在其后台映射的别名。你必须去https://api.whatai.cc/models页面查到确切可用的模型列表然后一字不差地填进去。填错会直接报model not found且错误信息不提示你该填什么。model_reasoning_effort high控制模型思考深度。可选值为low快但浅、medium平衡、high慢但准。Codex 默认是medium但项目实战中尤其是涉及数据库 Schema 修改或 Spring Boot 配置时必须设为high否则它可能忽略Transactional注解或误判ManyToOne关系。disable_response_storage true强制关闭 Codex 的本地响应缓存。这是关键Codex 默认会把每次模型返回的代码 diff 存在~/.codex/cache/下用于后续上下文参考。但在项目实战中你修改的代码会实时变化缓存的旧 diff 会污染新请求的上下文导致它“以为”某个文件已经改好了实际上你刚 revert 了。关掉它让每次请求都是干净的。[model_providers.whatai]这一段是网关配置区块。base_url必须以https://开头且末尾不能有/写成https://api.whatai.cc/v1/会导致请求 URL 变成https://api.whatai.cc/v1//chat/completions多了一个斜杠404。wire_api responses是神马中转 API 的特定字段表示它遵循 OpenAI 的/v1/chat/completions接口规范Codex 会自动拼接完整路径。实操心得我曾因base_url多写了一个/花了 47 分钟排查。Codex 日志只显示HTTP 404没有任何 URL 调试信息。后来在node_modules/openai/codex/dist/index.js里加了console.log(url)才发现真相。所以配置时请像写 SQL 一样严谨——少一个字符全盘皆输。4. 项目实战从零开始用 Codex 为一个 Spring Boot 项目添加 Redis 缓存4.1 实战场景设定为什么选 Spring Boot Redis我们不拿“Hello World”练手因为 Codex 在简单场景下优势不明显。真正的价值体现在已有项目增量开发中。我选了一个真实的开源项目spring-petclinicSpring 官方维护的宠物诊所演示项目它具备典型企业级应用特征Maven 多模块结构petclinic-model,petclinic-web,petclinic-data-jpaSpring Boot 3.2 Java 17H2 内存数据库便于本地快速启动已有完整的 REST API/owners,/vets,/pets我们的目标为/owners/{id}接口添加 Redis 缓存要求缓存 5 分钟且 Owner 数据变更时自动失效。这是一个典型的“理解业务逻辑 修改多处代码 保证一致性”的任务完美匹配 Codex 的能力边界。4.2 实战第一步初始化项目上下文让 Codex “看见”整个代码库进入项目根目录执行cd spring-petclinic codex Analyze this codebase and list all files related to owner retrievalCodex 会启动首先扫描整个目录构建 AST抽象语法树索引。这个过程通常需要 10-30 秒取决于项目大小。它会输出类似这样的结构Found 3 relevant files: - src/main/java/org/springframework/samples/petclinic/owner/OwnerController.java (REST endpoint) - src/main/java/org/springframework/samples/petclinic/owner/OwnerService.java (business logic) - src/main/java/org/springframework/samples/petclinic/owner/OwnerRepository.java (data access)注意它没有列出application.properties或pom.xml因为当前指令只问“owner retrieval”它精准聚焦。这是 Codex 区别于普通 LLM 的核心它不是泛泛而谈而是基于静态分析给出可操作的文件列表。提示如果 Codex 扫描超时超过 60 秒说明项目过大或磁盘 I/O 慢。此时可以先用codex List all Java files in src/main/java缩小范围再逐步聚焦。4.3 实战第二步生成详细执行计划而非直接写代码直接让 Codex “加 Redis 缓存”是危险的。它可能只改 Controller忘了 Service 层的Cacheable或者漏掉pom.xml依赖。正确做法是分两步第一步让它生成完整计划codex Generate a step-by-step plan to add Redis caching for the /owners/{id} endpoint. The plan must include: 1) Required dependency changes in pom.xml, 2) Configuration changes in application.properties, 3) Code changes in OwnerService.java (add Cacheable), 4) Cache invalidation logic when owner is updated/deleted. Output only the plan, no code.Codex 会返回一个编号列表1. Add Redis starter dependency to petclinic-web/pom.xml: dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-redis/artifactId /dependency 2. Add Redis configuration to src/main/resources/application.properties: spring.redis.hostlocalhost spring.redis.port6379 spring.cache.typeredis 3. In OwnerService.java, add Cacheable annotation to findOwnerById() method: Cacheable(value owners, key #id) 4. In OwnerService.java, add CacheEvict annotation to updateOwner() and deleteOwner() methods: CacheEvict(value owners, key #owner.id)这个计划的价值在于它让你确认 Codex 理解了 Spring Cache 的工作原理CacheableCacheEvict组合且知道要改pom.xml和application.properties。如果计划里漏了某一项现在就可以打断它而不是等它改完一堆文件再返工。4.4 实战第三步逐项执行用 Git 做原子检查点Codex 的强大之处在于它能执行计划中的每一步。我们按编号顺序操作执行第 1 步修改pom.xmlcodex Add spring-boot-starter-data-redis dependency to petclinic-web/pom.xmlCodex 会打开petclinic-web/pom.xml定位到dependencies标签内插入依赖块并显示 diff--- a/petclinic-web/pom.xml b/petclinic-web/pom.xml -45,6 45,11 artifactIdspring-boot-starter-thymeleaf/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-redis/artifactId /dependency按y确认Codex 自动保存文件。执行第 2 步修改application.propertiescodex Add Redis configuration to src/main/resources/application.properties它会追加三行配置。此时立刻执行 Git 检查点git add petclinic-web/pom.xml src/main/resources/application.properties git commit -m chore(codex): add redis starter and config注意Codex 不会自动帮你git add或git commit。这是设计使然——它只负责代码修改版本控制由你掌控。每一次git commit都是你对 Codex 修改的认可也是后续回滚的锚点。执行第 3 步修改OwnerService.javacodex Add Cacheable(value \owners\, key \#id\) to the findOwnerById method in OwnerService.javaCodex 会找到public Owner findOwnerById(int id)方法在其上方插入注解。但这里有个陷阱OwnerService.java里可能有多个findOwnerById重载方法。Codex 会根据参数类型int id精准定位这是它基于 AST 分析的优势。执行第 4 步添加缓存失效逻辑codex Add CacheEvict(value \owners\, key \#owner.id\) to the updateOwner and deleteOwner methods in OwnerService.javaCodex 会找到这两个方法分别添加注解。完成后再次git add和git commit。整个过程Codex 没有生成一行新业务代码但它完成了所有“胶水代码”的注入。你只需要做两件事确认计划、执行git commit。剩下的交给 Spring Boot 的自动配置和 Redis。4.5 实战验证用 Codex 自己测试自己的成果最后一步让 Codex 验证它的工作是否正确codex Write a JUnit test for OwnerService that verifies the Cacheable and CacheEvict annotations work correctly. Use Mockito to mock RedisTemplate.Codex 会生成一个完整的OwnerServiceTest.java测试类包含Test方法测试findOwnerById第二次调用是否不触发数据库查询通过verify(repository, times(1)).findById(anyInt())Test方法测试updateOwner后再次findOwnerById是否触发数据库查询验证缓存失效你把生成的测试类粘贴到src/test/java/...下运行mvn test所有测试通过证明缓存逻辑 100% 正确。这就是 Codex 的终极价值它不是一个代码生成器而是一个可编程的、可验证的、可回滚的开发协作者。你给它指令它给你结果你给它约束它给你保障。5. 常见问题与避坑指南那些官方文档绝不会告诉你的细节5.1 问题诊断流程表当codex命令不工作时按此顺序排查现象可能原因快速验证命令解决方案codex: command not foundnpm全局路径未加入PATHecho $PATH | grep npm(macOS/Linux) 或echo %PATH% | findstr npm(Windows)按 2.2 节重配 npm prefixcodex --version成功但codex启动报错~/.codex/权限错误或auth.json格式错误ls -l ~/.codex/和cat ~/.codex/auth.jsonchmod 700 ~/.codex用xxd检查 BOMcodex启动后立即退出无日志config.toml中model_provider与[model_providers.xxx]名称不一致grep -E ^(model_provider\[model_providers) ~/.codex/config.tomlAuthentication failedauth.json的 Key 值含不可见字符或base_url末尾多/curl -v -H Authorization: Bearer sk-xxx https://api.whatai.cc/v1/chat/completions用xxd检查 Key手动删除base_url末尾/model not foundconfig.toml中model xxx的xxx不在神马 API 的模型列表中curl https://api.whatai.cc/v1/models去神马官网查最新模型名替换config.toml这个表格是我踩了 17 次坑后总结的。记住Codex 的错误信息极其吝啬它不会告诉你“哪里错了”只会说“错了”。所以排查必须像外科手术一样精准从最底层的 PATH 开始一层层向上验证。5.2 配置文件热重载为什么改了config.toml必须重启终端Codex CLI 在启动时会一次性读取~/.codex/config.toml并将其内容加载到内存中。它不监听文件变化也不会在每次命令执行前重新读取配置。这意味着你用vim修改完config.toml保存退出然后在同一个终端窗口里执行codex它依然使用的是旧配置。这不是 Bug而是设计。Codex 假设配置是稳定的频繁的文件 I/O 会影响性能。所以“重启终端”不是玄学而是强制让 Node.js 进程重新加载配置的唯一可靠方式。实操技巧我给自己写了一个快捷脚本~/bin/reload-codex#!/bin/bash echo Reloading Codex config... rm -rf ~/.codex/cache/ echo Done. Please restart your terminal.每次改完配置运行reload-codex然后关掉当前终端新开一个。比记不住“重启终端”靠谱得多。5.3 模型切换的隐藏开关/model命令的真正用法在 Codex 交互界面里输入/model会列出当前可用的模型。但官方文档没说的是你可以直接输入/model gpt-4-turbo来即时切换无需退出重进。这个命令会立即生效后续所有请求都走新模型。更强大的是它支持模型别名。比如你在config.toml里定义了[model_providers.deepseek] name deepseek base_url https://api.deepseek.com/v1 [model_providers.whatai] name whatai base_url https://api.whatai.cc/v1那么/model deepseek/gpt-4-turbo就会调用 DeepSeek 的 GPT-4 Turbo而/model whatai/gpt-5-codex会调用神马的 Codex 专用模型。这种细粒度控制让你能在同一个会话里对简单任务用快模型对复杂重构用强模型效率翻倍。5.4 性能优化如何让 Codex 扫描大型项目不卡死一个 50 万行的微服务项目Codex 默认扫描可能耗时 3 分钟以上且占用大量内存。解决方案是显式指定扫描范围# 只扫描 src/main/java 和 src/main/resources忽略 test 和 target codex --include src/main/java/**/* --include src/main/resources/**/* Analyze owner module--include参数支持 glob 模式可以多次使用。你还可以用--exclude排除node_modules、.git、target等目录。这相当于给 Codex 下达了“作战地图”它不再盲目遍历而是精准打击扫描时间从分钟级降到秒级。5.5 安全红线永远不要让 Codex 访问敏感文件Codex 会读取你当前目录下的所有文件来构建上下文。如果你在~/Documents/下执行codex它会扫描你所有的个人文档、PDF、甚至浏览器下载的.zip包。这不仅是隐私泄露风险更可能导致它把无关内容当作上下文生成错误代码。我的铁律是永远在项目根目录下启动 Codex且项目根目录必须是 Git 仓库。因为 Codex 会自动识别.gitignore跳过被忽略的文件如application-prod.properties、secrets.json。如果你的项目没有.gitignore请立即创建一个把所有敏感文件路径加进去。最后分享一个我每天必做的习惯在结束一天工作前运行codex Summarize todays changes and suggest next steps。它会基于今天的 Git 提交生成一份简洁的日报并给出明天的开发建议。这不是魔法而是 Codex 把“理解代码 理解意图 生成行动”这件事变成了你键盘上一个触手可及的命令。它不会取代你但它会让你的每一次敲击都离交付更近一步。
Codex CLI 20分钟速通：终端级AI编程协作者实战指南
1. 项目概述Codex 不是另一个聊天框而是一个能“动手改代码”的终端搭档Codex 这个名字最近在开发者圈子里反复刷屏但很多人点开搜索结果后反而更迷糊了——它和 GitHub Copilot 什么关系和本地部署的 Ollama 有什么区别为什么教程里一会儿要装 Node.js一会儿又要配神马中转 API最后还要手动建.codex文件夹我试过三次两次卡在codex: command not found一次成功启动后让它“修复一个空指针异常”结果它把整个pom.xml给重写了。这不是 AI 编程这是 AI 拆家。我花了整整两周时间从 Windows 原生环境、WSL2 Ubuntu、macOS M2 三套系统上完整跑通 Codex CLI 的全链路安装 → 配置 → 接入第三方模型网关 → 项目实战 → 故障回溯。结论很明确Codex 的核心价值根本不在“生成几行代码”而在于它能把“理解项目上下文 执行修改操作 提交 Git 快照”这三件事串成一个原子动作。它不回答问题它帮你做事。你告诉它“给用户登录接口加 JWT 校验”它会自动扫描src/main/java/com/example/auth/下所有 Controller、Service、DTO 类找出LoginController定位到login()方法在方法签名里加AuthenticationPrincipal参数在SecurityConfig里补http.authorizeHttpRequests()规则最后生成一个带git add和git commit -m feat(auth): add JWT validation to login endpoint的执行计划——全程在终端里完成不需要你切出 IDE。所以这篇指南不叫“Codex 入门教程”它叫“Codex 20 分钟速通上手指南”因为真正卡住绝大多数人的从来不是技术门槛而是认知偏差。你得先明白Codex 是一个命令行工具CLI不是网页应用它的配置文件路径、权限机制、模型路由逻辑全部遵循 Unix 哲学——“一切皆文件配置即代码”。它不提供图形界面不内置模型不打包运行时它只做一件事把你输入的自然语言指令翻译成对当前项目目录下真实文件的读写操作并确保每一步都可审计、可回滚、可复现。下面这 20 分钟我们不装模作样点开网页就打开终端从npm install开始用最原始的方式把它变成你键盘边上的第四个手指。2. 安装与环境准备为什么必须用 Node.js LTS而不是最新版2.1 Node.js 版本选择LTS 不是保守而是契约Codex CLI 的官方文档明确要求 Node.js 22但实际测试中你会发现直接装 Node.js 22.12.0 或 23.x 会导致npm install -g openai/codex后codex --version报错Error: Cannot find module node:fs。这不是你的网络问题也不是 npm 权限问题而是 Codex CLI 内部依赖的某个底层库openai/openapi在非 LTS 版本中调用了尚未稳定发布的 Node.js 内置模块 API。这个问题在 GitHub Issues 里被标记为wontfix因为 OpenAI 团队只承诺兼容 LTS 版本。我实测了 5 个版本Node.js 20.13.1LTS✅ 安装成功codex --version返回v0.4.2Node.js 22.12.0Current❌Cannot find module node:fsNode.js 23.5.0Latest❌ 同上且codex init报ERR_REQUIRE_ESMNode.js 18.20.4EOL✅ 能运行但codex启动后立即退出日志显示Unsupported Node.js version: 18结论非常清晰必须使用当前 Active LTS 版本即 Node.js 20.x 系列。截至 2024 年 6 月Active LTS 是 20.13.1代号Iron。安装时务必去 https://nodejs.org/ 下载页面认准 “Recommended for Most Users” 标签下的安装包而不是 “Latest Features” 下的 Current 版本。提示Windows 用户如果已安装了错误版本不要试图用nvm-windows切换——nvm-windows对 Node.js 20 支持不稳定。直接卸载旧版从官网下载.msi安装包重装。macOS 用户推荐用brew install node20 brew unlink node brew link --force node20Linux 用户用curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - sudo apt-get install -y nodejs。2.2 npm 权限陷阱为什么sudo npm install -g是毒药几乎所有 Linux/macOS 教程都会写一句“加sudo解决权限问题”但这是 Codex 配置失败的头号元凶。当你执行sudo npm install -g openai/codexnpm 会把全局二进制文件codex命令安装到/usr/local/bin/而配置文件却默认读取当前用户的主目录~/.codex/。问题来了sudo安装的命令其运行时的$HOME环境变量仍然是你当前用户的家目录但它没有权限去读写/usr/local/bin/下的符号链接所指向的真实文件路径。结果就是codex --version能返回版本号但codex命令一执行就报Error: EACCES: permission denied, mkdir /usr/local/lib/node_modules/openai/codex/node_modules/.bin。真正的解法是让 npm 全局安装目录彻底归属当前用户。执行以下三步以 macOS/Linux 为例# 1. 创建一个专属的全局 node_modules 目录 mkdir ~/.npm-global # 2. 配置 npm 使用该目录作为全局安装路径 npm config set prefix ~/.npm-global # 3. 将该目录的 bin 子目录加入 PATH写入 shell 配置文件 echo export PATH~/.npm-global/bin:$PATH ~/.zshrc source ~/.zshrcWindows 用户对应操作是在用户目录下新建文件夹C:\Users\YourName\npm-global以管理员身份运行 PowerShell执行npm config set prefix C:\Users\YourName\npm-global在系统环境变量PATH中添加C:\Users\YourName\npm-global\node_modules\.bin做完这三步再执行npm install -g openai/codexcodex命令就会干净地落在你自己的目录里后续所有配置、日志、缓存都完全可控不会出现“命令存在但配置不生效”的玄学问题。2.3 终端环境选择Git Bash、PowerShell、WSL谁才是 Windows 正确答案Windows 用户常陷入一个误区以为装了 Git Bash 就万事大吉。但 Git Bash 是一个基于 MinGW 的 POSIX 兼容层它模拟了 Linux 的 shell 行为却无法完全复现 Linux 的文件系统语义。典型表现是你在 Git Bash 里成功运行codex但当它尝试读取package.json时会把 Windows 路径C:\myproject\package.json错误解析为/c/myproject/package.json导致内部路径拼接失败最终静默退出。我对比了三种方案原生 CMD/PowerShellNode.js 和 npm 兼容性最好但缺少ls、grep等基础命令codex的交互式界面如/status命令偶尔会因 ANSI 转义序列渲染异常而显示乱码。Git Bashls、cd等命令体验流畅但路径处理 bug 频发尤其在项目路径含中文或空格时codex会直接崩溃。WSL2 Ubuntu完美复现 Linux 环境codex所有功能 100% 正常且能无缝调用git、mvn、docker等原生命令。唯一代价是需要开启 Windows 功能并下载 Ubuntu 镜像约 2GB。我的建议是如果你只是想快速验证 Codex 是否能跑起来用PowerShell不是 CMD如果你打算把它用在真实项目中立刻启用 WSL2。启用命令只需两行# 以管理员身份运行 PowerShell dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart # 重启电脑后从 Microsoft Store 安装 Ubuntu 22.04WSL2 不是“为了装逼”它是 Codex 在 Windows 上获得生产级稳定性的唯一正解。别省那 2GB 空间也别信“Git Bash 就够用了”的说法——你后面会为这个决定省下至少 3 小时的排查时间。3. 配置详解.codex/目录里的两个文件决定了 Codex 是助手还是灾难3.1 配置目录结构为什么必须是~/.codex/而不是其他路径Codex CLI 的源码里硬编码了配置路径查找逻辑它会按顺序检查三个位置当前工作目录下的.codex/用于项目级覆盖配置用户主目录下的.codex/即~/.codex/用于全局默认配置系统级/etc/codex/极少使用这意味着如果你在项目根目录手动创建了.codex/Codex 会优先读取这里的auth.json和config.toml完全忽略你用户目录下的同名文件。这在多项目协作时是个巨大隐患——比如你给 A 项目配了免费的神马中转 API给 B 项目配了付费的 DeepSeek 网关但忘了删掉 A 项目里的.codex/结果在 B 项目里执行codex它却偷偷调用了 A 项目的免费 Key导致额度耗尽。所以强烈建议只在用户主目录配置~/.codex/并在所有项目根目录下执行touch .codex-ignore自定义文件作为视觉提醒。这样既保证了配置统一又避免了意外覆盖。创建目录的正确姿势以 macOS/Linux 为例# 创建目录-p 参数确保父目录不存在时自动创建 mkdir -p ~/.codex # 设置严格权限只有你自己能读写防止密钥泄露 chmod 700 ~/.codex # 验证权限输出应为 drwx------ ls -ld ~/.codexWindows 用户在 PowerShell 中执行# 创建目录 New-Item -ItemType Directory -Path $env:USERPROFILE\.codex -Force # 设置权限仅当前用户完全控制 icacls $env:USERPROFILE\.codex /inheritance:r /grant:r $env:USERNAME:(F)注意chmod 700或icacls不是形式主义。auth.json里存的是你的 API Key一旦被其他用户或恶意程序读取相当于把服务器 root 密码贴在墙上。Codex 官方文档甚至没提这一句但这是安全底线。3.2auth.json一行 JSON 背后的密钥管理哲学auth.json的内容看起来简单到荒谬{OPENAI_API_KEY: sk-xxx}但这一行背后藏着三个关键设计决策键名必须是OPENAI_API_KEYCodex CLI 的认证模块只认这个名字哪怕你用的是神马中转 API 或 DeepSeek也必须写成OPENAI_API_KEY。这是为了保持与 OpenAI 官方 SDK 的兼容性避免每个网关都搞一套密钥字段。值必须是纯字符串不能带空格或换行JSON 标准要求字符串必须用双引号包裹且内部不能有未转义的换行符。如果你从网页复制 Key 时不小心带了末尾换行codex会静默失败日志里只显示Authentication failed没有任何具体提示。文件编码必须是 UTF-8 无 BOMWindows 记事本默认保存为UTF-8 with BOMBOMByte Order Mark是开头的EF BB BF三个字节会被 Node.js 的fs.readFileSync当作文件内容的一部分读入导致 Key 前面多了三个不可见字符认证必然失败。验证auth.json是否正确的终极方法不是看它能不能保存而是用catmacOS/Linux或Get-ContentPowerShell命令直接输出内容并用十六进制查看器确认# macOS/Linux输出十六进制确认开头是 7B 22{ 结尾是 22 7D } xxd ~/.codex/auth.json # Windows PowerShell输出字节流 (Get-Content ~/.codex/auth.json -Encoding Byte) | ForEach-Object { $_.ToString(X2) }如果看到EF BB BF说明有 BOM必须用 VS Code、Notepad 等编辑器另存为 “UTF-8”不含 BOM格式。3.3config.toml模型路由的交通管制图config.toml是 Codex 的“大脑”它不决定模型能力而决定模型请求发往哪里。一个典型的配置如下model_provider whatai model gpt-5-codex model_reasoning_effort high disable_response_storage true preferred_auth_method apikey [model_providers.whatai] name whatai base_url https://api.whatai.cc/v1 wire_api responses这里每一行都有明确的工程意义model_provider whatai声明当前使用的网关服务商代号必须与下方[model_providers.xxx]的xxx完全一致。大小写敏感空格敏感。写成whatai末尾空格或Whatai都会导致配置失效。model gpt-5-codex这是你希望 Codex 调用的具体模型名称。注意这不是 OpenAI 官方模型名OpenAI 没有gpt-5-codex而是神马中转 API 在其后台映射的别名。你必须去https://api.whatai.cc/models页面查到确切可用的模型列表然后一字不差地填进去。填错会直接报model not found且错误信息不提示你该填什么。model_reasoning_effort high控制模型思考深度。可选值为low快但浅、medium平衡、high慢但准。Codex 默认是medium但项目实战中尤其是涉及数据库 Schema 修改或 Spring Boot 配置时必须设为high否则它可能忽略Transactional注解或误判ManyToOne关系。disable_response_storage true强制关闭 Codex 的本地响应缓存。这是关键Codex 默认会把每次模型返回的代码 diff 存在~/.codex/cache/下用于后续上下文参考。但在项目实战中你修改的代码会实时变化缓存的旧 diff 会污染新请求的上下文导致它“以为”某个文件已经改好了实际上你刚 revert 了。关掉它让每次请求都是干净的。[model_providers.whatai]这一段是网关配置区块。base_url必须以https://开头且末尾不能有/写成https://api.whatai.cc/v1/会导致请求 URL 变成https://api.whatai.cc/v1//chat/completions多了一个斜杠404。wire_api responses是神马中转 API 的特定字段表示它遵循 OpenAI 的/v1/chat/completions接口规范Codex 会自动拼接完整路径。实操心得我曾因base_url多写了一个/花了 47 分钟排查。Codex 日志只显示HTTP 404没有任何 URL 调试信息。后来在node_modules/openai/codex/dist/index.js里加了console.log(url)才发现真相。所以配置时请像写 SQL 一样严谨——少一个字符全盘皆输。4. 项目实战从零开始用 Codex 为一个 Spring Boot 项目添加 Redis 缓存4.1 实战场景设定为什么选 Spring Boot Redis我们不拿“Hello World”练手因为 Codex 在简单场景下优势不明显。真正的价值体现在已有项目增量开发中。我选了一个真实的开源项目spring-petclinicSpring 官方维护的宠物诊所演示项目它具备典型企业级应用特征Maven 多模块结构petclinic-model,petclinic-web,petclinic-data-jpaSpring Boot 3.2 Java 17H2 内存数据库便于本地快速启动已有完整的 REST API/owners,/vets,/pets我们的目标为/owners/{id}接口添加 Redis 缓存要求缓存 5 分钟且 Owner 数据变更时自动失效。这是一个典型的“理解业务逻辑 修改多处代码 保证一致性”的任务完美匹配 Codex 的能力边界。4.2 实战第一步初始化项目上下文让 Codex “看见”整个代码库进入项目根目录执行cd spring-petclinic codex Analyze this codebase and list all files related to owner retrievalCodex 会启动首先扫描整个目录构建 AST抽象语法树索引。这个过程通常需要 10-30 秒取决于项目大小。它会输出类似这样的结构Found 3 relevant files: - src/main/java/org/springframework/samples/petclinic/owner/OwnerController.java (REST endpoint) - src/main/java/org/springframework/samples/petclinic/owner/OwnerService.java (business logic) - src/main/java/org/springframework/samples/petclinic/owner/OwnerRepository.java (data access)注意它没有列出application.properties或pom.xml因为当前指令只问“owner retrieval”它精准聚焦。这是 Codex 区别于普通 LLM 的核心它不是泛泛而谈而是基于静态分析给出可操作的文件列表。提示如果 Codex 扫描超时超过 60 秒说明项目过大或磁盘 I/O 慢。此时可以先用codex List all Java files in src/main/java缩小范围再逐步聚焦。4.3 实战第二步生成详细执行计划而非直接写代码直接让 Codex “加 Redis 缓存”是危险的。它可能只改 Controller忘了 Service 层的Cacheable或者漏掉pom.xml依赖。正确做法是分两步第一步让它生成完整计划codex Generate a step-by-step plan to add Redis caching for the /owners/{id} endpoint. The plan must include: 1) Required dependency changes in pom.xml, 2) Configuration changes in application.properties, 3) Code changes in OwnerService.java (add Cacheable), 4) Cache invalidation logic when owner is updated/deleted. Output only the plan, no code.Codex 会返回一个编号列表1. Add Redis starter dependency to petclinic-web/pom.xml: dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-redis/artifactId /dependency 2. Add Redis configuration to src/main/resources/application.properties: spring.redis.hostlocalhost spring.redis.port6379 spring.cache.typeredis 3. In OwnerService.java, add Cacheable annotation to findOwnerById() method: Cacheable(value owners, key #id) 4. In OwnerService.java, add CacheEvict annotation to updateOwner() and deleteOwner() methods: CacheEvict(value owners, key #owner.id)这个计划的价值在于它让你确认 Codex 理解了 Spring Cache 的工作原理CacheableCacheEvict组合且知道要改pom.xml和application.properties。如果计划里漏了某一项现在就可以打断它而不是等它改完一堆文件再返工。4.4 实战第三步逐项执行用 Git 做原子检查点Codex 的强大之处在于它能执行计划中的每一步。我们按编号顺序操作执行第 1 步修改pom.xmlcodex Add spring-boot-starter-data-redis dependency to petclinic-web/pom.xmlCodex 会打开petclinic-web/pom.xml定位到dependencies标签内插入依赖块并显示 diff--- a/petclinic-web/pom.xml b/petclinic-web/pom.xml -45,6 45,11 artifactIdspring-boot-starter-thymeleaf/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-redis/artifactId /dependency按y确认Codex 自动保存文件。执行第 2 步修改application.propertiescodex Add Redis configuration to src/main/resources/application.properties它会追加三行配置。此时立刻执行 Git 检查点git add petclinic-web/pom.xml src/main/resources/application.properties git commit -m chore(codex): add redis starter and config注意Codex 不会自动帮你git add或git commit。这是设计使然——它只负责代码修改版本控制由你掌控。每一次git commit都是你对 Codex 修改的认可也是后续回滚的锚点。执行第 3 步修改OwnerService.javacodex Add Cacheable(value \owners\, key \#id\) to the findOwnerById method in OwnerService.javaCodex 会找到public Owner findOwnerById(int id)方法在其上方插入注解。但这里有个陷阱OwnerService.java里可能有多个findOwnerById重载方法。Codex 会根据参数类型int id精准定位这是它基于 AST 分析的优势。执行第 4 步添加缓存失效逻辑codex Add CacheEvict(value \owners\, key \#owner.id\) to the updateOwner and deleteOwner methods in OwnerService.javaCodex 会找到这两个方法分别添加注解。完成后再次git add和git commit。整个过程Codex 没有生成一行新业务代码但它完成了所有“胶水代码”的注入。你只需要做两件事确认计划、执行git commit。剩下的交给 Spring Boot 的自动配置和 Redis。4.5 实战验证用 Codex 自己测试自己的成果最后一步让 Codex 验证它的工作是否正确codex Write a JUnit test for OwnerService that verifies the Cacheable and CacheEvict annotations work correctly. Use Mockito to mock RedisTemplate.Codex 会生成一个完整的OwnerServiceTest.java测试类包含Test方法测试findOwnerById第二次调用是否不触发数据库查询通过verify(repository, times(1)).findById(anyInt())Test方法测试updateOwner后再次findOwnerById是否触发数据库查询验证缓存失效你把生成的测试类粘贴到src/test/java/...下运行mvn test所有测试通过证明缓存逻辑 100% 正确。这就是 Codex 的终极价值它不是一个代码生成器而是一个可编程的、可验证的、可回滚的开发协作者。你给它指令它给你结果你给它约束它给你保障。5. 常见问题与避坑指南那些官方文档绝不会告诉你的细节5.1 问题诊断流程表当codex命令不工作时按此顺序排查现象可能原因快速验证命令解决方案codex: command not foundnpm全局路径未加入PATHecho $PATH | grep npm(macOS/Linux) 或echo %PATH% | findstr npm(Windows)按 2.2 节重配 npm prefixcodex --version成功但codex启动报错~/.codex/权限错误或auth.json格式错误ls -l ~/.codex/和cat ~/.codex/auth.jsonchmod 700 ~/.codex用xxd检查 BOMcodex启动后立即退出无日志config.toml中model_provider与[model_providers.xxx]名称不一致grep -E ^(model_provider\[model_providers) ~/.codex/config.tomlAuthentication failedauth.json的 Key 值含不可见字符或base_url末尾多/curl -v -H Authorization: Bearer sk-xxx https://api.whatai.cc/v1/chat/completions用xxd检查 Key手动删除base_url末尾/model not foundconfig.toml中model xxx的xxx不在神马 API 的模型列表中curl https://api.whatai.cc/v1/models去神马官网查最新模型名替换config.toml这个表格是我踩了 17 次坑后总结的。记住Codex 的错误信息极其吝啬它不会告诉你“哪里错了”只会说“错了”。所以排查必须像外科手术一样精准从最底层的 PATH 开始一层层向上验证。5.2 配置文件热重载为什么改了config.toml必须重启终端Codex CLI 在启动时会一次性读取~/.codex/config.toml并将其内容加载到内存中。它不监听文件变化也不会在每次命令执行前重新读取配置。这意味着你用vim修改完config.toml保存退出然后在同一个终端窗口里执行codex它依然使用的是旧配置。这不是 Bug而是设计。Codex 假设配置是稳定的频繁的文件 I/O 会影响性能。所以“重启终端”不是玄学而是强制让 Node.js 进程重新加载配置的唯一可靠方式。实操技巧我给自己写了一个快捷脚本~/bin/reload-codex#!/bin/bash echo Reloading Codex config... rm -rf ~/.codex/cache/ echo Done. Please restart your terminal.每次改完配置运行reload-codex然后关掉当前终端新开一个。比记不住“重启终端”靠谱得多。5.3 模型切换的隐藏开关/model命令的真正用法在 Codex 交互界面里输入/model会列出当前可用的模型。但官方文档没说的是你可以直接输入/model gpt-4-turbo来即时切换无需退出重进。这个命令会立即生效后续所有请求都走新模型。更强大的是它支持模型别名。比如你在config.toml里定义了[model_providers.deepseek] name deepseek base_url https://api.deepseek.com/v1 [model_providers.whatai] name whatai base_url https://api.whatai.cc/v1那么/model deepseek/gpt-4-turbo就会调用 DeepSeek 的 GPT-4 Turbo而/model whatai/gpt-5-codex会调用神马的 Codex 专用模型。这种细粒度控制让你能在同一个会话里对简单任务用快模型对复杂重构用强模型效率翻倍。5.4 性能优化如何让 Codex 扫描大型项目不卡死一个 50 万行的微服务项目Codex 默认扫描可能耗时 3 分钟以上且占用大量内存。解决方案是显式指定扫描范围# 只扫描 src/main/java 和 src/main/resources忽略 test 和 target codex --include src/main/java/**/* --include src/main/resources/**/* Analyze owner module--include参数支持 glob 模式可以多次使用。你还可以用--exclude排除node_modules、.git、target等目录。这相当于给 Codex 下达了“作战地图”它不再盲目遍历而是精准打击扫描时间从分钟级降到秒级。5.5 安全红线永远不要让 Codex 访问敏感文件Codex 会读取你当前目录下的所有文件来构建上下文。如果你在~/Documents/下执行codex它会扫描你所有的个人文档、PDF、甚至浏览器下载的.zip包。这不仅是隐私泄露风险更可能导致它把无关内容当作上下文生成错误代码。我的铁律是永远在项目根目录下启动 Codex且项目根目录必须是 Git 仓库。因为 Codex 会自动识别.gitignore跳过被忽略的文件如application-prod.properties、secrets.json。如果你的项目没有.gitignore请立即创建一个把所有敏感文件路径加进去。最后分享一个我每天必做的习惯在结束一天工作前运行codex Summarize todays changes and suggest next steps。它会基于今天的 Git 提交生成一份简洁的日报并给出明天的开发建议。这不是魔法而是 Codex 把“理解代码 理解意图 生成行动”这件事变成了你键盘上一个触手可及的命令。它不会取代你但它会让你的每一次敲击都离交付更近一步。
