★ FEATURED ARTICLE 1. 为什么第一次用 Codex CLI 总卡在环境这一步Codex CLI 是 OpenAI 推出的命令行编程助手你可以把它理解成一个能直接在你项目目录里读文件、改代码、跑命令的智能体。它和网页版问答最大的区别是它真的会打开你的文件夹看到你的目录结构然后动手改文件。适合谁适合已经会一点命令行、想把手上的 React 或 Node 项目交给 AI 帮忙推进的开发者。如果你连npm都没跑过这篇也能跟但建议先把终端基本操作过一遍。我见过太多人第一次装 Codex 的流程是这样的搜到一条npm install -g openai/codex装完输入codex然后卡在登录或者卡在401或者卡在local proxy failed。问题往往不在 Codex 本身而在三件事没对齐Node.js 版本、认证方式、以及请求到底发到了哪个 Base URL。这篇按「从零到跑通第一个 React 项目」的路径写中间会把 auth.json 和 Base URL 的可复制配置片段给全最后用一个真实请求验证链路。统一 Key 接入的部分用 TaoToken 来做这样你只需要维护一套 Key 和一套地址不用在多个平台之间来回切换。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 后面配置里会反复用到。先明确一个概念避免后面混淆。Codex 常见有三种形态Codex CLI 跑在本机终端适合本地项目Codex Cloud 跑在云端任务里适合耗时长、上下文大的活API 则是把模型能力接进你自己的产品。这篇只讲 CLI因为它是本地开发最顺手的入口也是新手最容易跑通的一条路。环境这块官方建议 Node.js 18 或更高。我实测下来 Node 20 LTS 最稳Node 22 也能跑但个别老项目依赖会挑版本。系统方面 macOS 13、Ubuntu 20.04、Windows 10 都行Windows 建议直接用 WSL省掉一堆路径和权限的坑。Git 不是硬性要求但 Codex 很多操作涉及版本管理装上更省心。下面从 Node.js 检查开始一步步走到 React 项目跑起来。每一步都给可复制的命令你照着敲就行。2. Node.js 版本检查与 Codex CLI 安装命令实操先确认你机器上的 Node.js 版本。打开终端执行node -v npm -v正常会输出类似v20.11.0和10.2.4。如果node -v报 command not found说明还没装。macOS 用 Homebrew 最省事brew install nodeUbuntu 可以用 NodeSource 的源或者直接用 nvm 管理多版本curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20Windows 用户如果不想折腾 WSL去 Node.js 官网下 LTS 安装包也行但后面路径相关的问题会多一些遇到codex: command not found的概率更高。Node 就绪后装 Codex CLI。全局安装是最通用的方式npm install -g openai/codex如果你不想污染全局环境也可以在项目目录里局部装npm install openai/codex装完验证codex --version能输出版本号就说明二进制已经进 PATH 了。如果这一步报command not found先别急着重装八成是 npm 全局 bin 目录没进 PATH。查一下npm config get prefix把这个路径下的bin目录加进你的 shell 配置。macOS/Linux 编辑~/.zshrc或~/.bashrc加一行export PATH$(npm config get prefix)/bin:$PATH然后source一下配置文件重开终端再试。这一步是新手最高频的卡点先解决掉后面才顺。Git 顺手也确认一下git --version没有的话 macOS 用brew install gitUbuntu 用sudo apt install gitWindows 去 Git 官网下安装包。装 Git 不是为了 Codex 本身而是它执行某些操作时会调用 git 命令缺了会报一些看起来莫名其妙的错。到这里环境三件套Node、npm、Git就齐了。接下来是认证这也是统一 Key 接入真正发挥作用的地方。3. auth.json 与 Base URL 可复制配置片段统一 Key 接入Codex CLI 支持两种认证路径一种是走 ChatGPT 账号登录一种是走 API Key。如果你已经有 ChatGPT Plus/Pro/Teamcodex login走浏览器授权是最快的。但如果你想像我一样把 Codex 和其他工具共用一套 Key、统一走一个 Base URL那就用 API Key 方式配合 TaoToken 的地址。先说清楚原理。Codex CLI 读取配置有两个位置一个是环境变量一个是~/.codex/auth.json。环境变量适合临时测试auth.json 适合长期固定。统一 Key 接入的核心就是把OPENAI_API_KEY和OPENAI_BASE_URL这两个值指向同一套。先拿 Key。打开 https://taotoken.net/api-keys 登录后创建一个 API Key复制出来形如sk-xxxx。这个 Key 后面既给 Codex 用也能给别的工具用这就是「统一 Key」的意思。然后配置 auth.json。先建目录mkdir -p ~/.codex编辑~/.codex/auth.json写入{ OPENAI_API_KEY: sk-你的TaoToken密钥, OPENAI_BASE_URL: https://taotoken.net/api }注意 Base URL 结尾不要带/v1Codex 会自己拼路径。这一点很多人踩坑写成https://taotoken.net/api/v1反而会 404。如果你更习惯用环境变量macOS/Linux 在~/.zshrc或~/.bashrc里加export OPENAI_API_KEYsk-你的TaoToken密钥 export OPENAI_BASE_URLhttps://taotoken.net/apiWindows PowerShell 用$env:OPENAI_API_KEYsk-你的TaoToken密钥 $env:OPENAI_BASE_URLhttps://taotoken.net/api想长期生效就写进 PowerShell Profile。这里有个细节要提醒auth.json 和环境变量同时存在时优先级可能因版本而异。我的建议是只保留一种别两边都写否则排查起来很痛苦。我一般用 auth.json因为它跟项目无关换目录也不用重新 export。配置完验证一下 Codex 能不能读到codex --help如果帮助信息正常输出说明二进制没问题。真正的链路验证在下一节用一个真实请求来确认。顺便说下模型 ID。Codex CLI 默认会用一个内置模型名如果你想指定可以在启动时加参数或者在配置里写model字段。统一 Key 接入时模型 ID 要跟 TaoToken 支持的名称对齐常见的是gpt-4o、gpt-4o-mini这类。具体支持列表在 https://taotoken.net/doc 里能查到配置前扫一眼避免写了个不存在的名字然后报model not found。三件套记牢Base URL 是https://taotoken.net/apiKey 是你在 api-keys 页面创建的那串Model ID 按文档填。这三个对齐了链路基本就通了。4. 一次真实请求验证链路从 codex 启动到 React 项目跑通配置写完不算通得发一次真实请求。先做个最小验证再上 React 项目。建个空目录mkdir codex-demo cd codex-demo启动交互模式codex进去后输入一句最简单的任务请创建一个 hello.js 文件用 Node 打印 Codex OK然后运行它。如果链路通Codex 会分析当前目录、创建文件、执行node hello.js你会在终端看到Codex OK。这一步成功说明 Key、Base URL、模型三件套全部对齐。如果这里报错直接跳到第 5 节对照排查。验证通过后正式上 React。还是在项目目录里让 Codex 用 Vite 初始化请使用 Vite 创建一个 React 项目项目名 countdown-app模板选 react然后安装依赖。Codex 会执行类似这样的命令npm create vitelatest countdown-app -- --template react cd countdown-app npm install等它跑完进目录确认结构cd countdown-app ls -la你应该能看到src、public、package.json、vite.config.js。接着让它加一个倒计时组件请在 src 目录下创建 Countdown.jsx接收 seconds 属性每秒递减显示剩余秒数归零显示时间到。然后在 App.jsx 里引入并传入 seconds{10}。Codex 生成的组件大概长这样import { useState, useEffect } from react; function Countdown({ seconds }) { const [remaining, setRemaining] useState(seconds); useEffect(() { if (remaining 0) return; const timer setTimeout(() { setRemaining(remaining - 1); }, 1000); return () clearTimeout(timer); }, [remaining]); if (remaining 0) { return p时间到/p; } return p剩余时间{remaining} 秒/p; } export default Countdown;然后启动开发服务器npm run dev终端会输出http://localhost:5173。浏览器打开看到倒计时从 10 往下走归零显示「时间到」整个链路就彻底跑通了。从装 Node 到 React 组件在浏览器里动起来全程没离开终端也没手动改过一行配置。这一步的意义不只是「跑通一个 demo」。它验证的是Codex 能读你的项目、能写文件、能跑命令、能根据运行结果继续调整。后面你让它改 bug、补测试、重构靠的都是这套能力。5. 常见报错排查401、local proxy failed、reading choices、OAuth链路跑不通时报错信息通常很具体对着查就行。下面是我和身边人踩过的几类。401 Unauthorized。这是最高频的。原因基本是 Key 不对或没被读到。先确认~/.codex/auth.json里的 Key 没有多余空格字符串引号是英文的。然后确认环境变量里没有另一个冲突的OPENAI_API_KEY。排查命令echo $OPENAI_API_KEY cat ~/.codex/auth.json两边如果都有值且不一致删掉环境变量那个只留 auth.json。还有一种情况是 Key 本身失效了去 https://taotoken.net/api-keys 重新生成一个换上。local proxy failed。这个报错通常出现在网络层意思是 Codex 尝试连 Base URL 时失败了。先确认OPENAI_BASE_URL写的是https://taotoken.net/api没有多余斜杠没有/v1。然后用 curl 直接测一下地址通不通curl -I https://taotoken.net/api能返回 HTTP 状态码说明网络可达。如果 curl 都不通那是本机网络问题跟 Codex 无关。如果 curl 通但 Codex 报 proxy failed检查是不是系统里设了全局代理变量HTTP_PROXY/HTTPS_PROXY临时 unset 掉再试。reading choices 相关报错。这类通常表现为cannot read property choices of undefined或类似。根因是返回体结构跟 Codex 预期的不一致多半是 Base URL 拼错导致返回了 HTML 错误页或者模型 ID 写错导致返回了错误 JSON。先确认 Model ID 在 https://taotoken.net/doc 的支持列表里再确认 Base URL 没带/v1。两个都对还报就把 Codex 升到最新版npm install -g openai/codexlatestOAuth 相关报错。如果你走的是codex login浏览器授权报 OAuth 失败通常是回调端口被占或浏览器没弹出来。可以改用 API Key 方式绕开也就是第 3 节的 auth.json 配置。统一 Key 接入的好处在这里体现得很明显不依赖浏览器授权流程纯配置可复制换机器也能一键搬。codex: command not found。回到第 2 节检查 npm 全局 bin 是否在 PATH。模型不存在 / model not found。Model ID 拼错或者该模型在当前 Key 下不可用。对照文档改。排查顺序建议固定成先codex --version确认二进制再cat ~/.codex/auth.json确认配置再curl -I确认网络最后看具体报错。四步走完九成问题能定位。6. 把 Codex 用顺手的几个实战习惯链路通了之后真正决定效率的是你怎么给它下指令。Codex 和普通问答最大的区别是它有工作目录概念所以上下文给得越准它干得越对。第一项目里维护一个清楚的 README。写清项目目标、目录结构、怎么跑。Codex 启动时会读读完它就知道src/services放接口、src/components放组件不用你每次解释。第二指令里点名文件和函数。与其说「帮我优化代码」不如说「阅读 src/services/api.js把错误处理抽成统一函数不改返回结构跑一遍测试」。后者它一次就能做对。第三要求它自己验证。让它「运行测试并给出结果」「启动服务确认端口」它会根据真实输出继续调整而不是写完就交差。这是 Codex 相比纯生成最强的地方。第四任务拆小。一个大重构拆成三四个小任务每个都能验证出问题也好回滚。一次让它改十个文件出错你都不知道从哪查。第五长期编码或跑 Agent 类任务可以考虑 Coding Plan把额度固定下来不用每次临时配。入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果你只是想先验证模型对话效果用模型对话页更轻https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。第六接入文档常备。配置字段、模型列表、参数说明都在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 遇到不确定的字段先查再写比反复试错快。最后说个我自己的习惯每次开新项目先让 Codex 读一遍目录并输出一份「项目结构说明」确认它理解对了再开始派活。这一步花不了一分钟但能省掉后面大量「它改错文件」的返工。Codex 的能力上限很高前提是你把上下文和验证这两件事做扎实。
阅读完成 · 觉得有帮助？
