Codex 入门教程从安装到第一次运行第一次装 Codex最容易卡住的地方通常不是命令本身而是 Node 版本、环境变量、网络访问和终端权限。建议先别急着反复重装按顺序检查本机环境是否满足、命令是否能找到、Key 是否生效、网络是否能连到接口。一、安装前准备1. 确认 Node.js 和 npmCodex 命令行工具一般通过 npm 安装所以本机需要先有 Node.js。建议使用较新的 LTS 版本太旧的 Node 容易出现依赖安装失败、语法不兼容等问题。### token云桥中转 0029.org ### node -v npm -v如果提示command not found说明还没装 Node.js。可以到 Node.js 官网安装 LTS 版本或者用 nvm 管理版本。使用 nvm 的话可以这样装nvm install --lts nvm use --lts node -v npm -v2. 确认 Git 可用Codex 在处理项目目录、读取仓库上下文时通常会和 Git 项目一起使用。虽然不是所有场景都强依赖 Git但建议先装好。git --version如果你的项目还不是 Git 仓库可以先初始化git init3. 准备一个测试目录第一次运行不建议直接放到生产项目里试。新建一个小目录放一两个简单文件方便观察 Codex 会读取什么、修改什么。mkdir codex-demo cd codex-demo echo console.log(hello codex) index.js git init git add . git commit -m init demo如果提交时报用户名邮箱未配置可以先设置git config --global user.name your-name git config --global user.email your-emailexample.com二、安装 Codex 命令行工具常见安装方式是使用 npm 全局安装。安装前建议先确认 npm 源没有被错误代理或旧镜像锁死。npm config get registry如果你希望使用 npm 官方源可以设置为npm config set registry https://registry.npmjs.org/然后安装 Codexnpm install -g openai/codex安装完成后检查命令是否可用codex --version如果能输出版本号说明命令已经安装成功。若提示找不到codex重点检查 npm 全局 bin 目录是否在 PATH 里。npm bin -gmacOS 或 Linux 下可以查看当前 PATHecho $PATHWindows PowerShell 下可以查看$env:Path如果 npm 全局目录不在 PATH需要把它加入系统环境变量然后重新打开终端。三、配置 API KeyCodex 运行时需要能访问模型接口所以要配置 Key。最常用的方式是设置环境变量OPENAI_API_KEY。macOS / Linuxexport OPENAI_API_KEY你的_API_Key上面这种只对当前终端窗口生效。想长期生效可以写入 shell 配置文件例如使用 zshecho export OPENAI_API_KEY你的_API_Key ~/.zshrc source ~/.zshrc如果你用 bashecho export OPENAI_API_KEY你的_API_Key ~/.bashrc source ~/.bashrcWindows PowerShell当前窗口临时生效$env:OPENAI_API_KEY你的_API_Key写入用户环境变量setx OPENAI_API_KEY 你的_API_Keysetx设置后通常需要重新打开一个 PowerShell 窗口才会生效。验证 Key 是否已经读到macOS / Linuxecho $OPENAI_API_KEYWindows PowerShellecho $env:OPENAI_API_KEY注意不要把完整 Key 截图发到群里也不要提交到 Git。项目里如果需要保存配置建议使用.env并把它加入.gitignore。echo .env .gitignore四、网络验证安装成功但运行报错很多时候是网络连不上接口而不是 Codex 本身坏了。建议先用 curl 做一次最小验证。curl https://api.openai.com/v1/models \ -H Authorization: Bearer $OPENAI_API_KEYWindows PowerShell 可以这样写curl.exe https://api.openai.com/v1/models -H Authorization: Bearer $env:OPENAI_API_KEY如果返回类似模型列表的 JSON说明网络和 Key 至少基本可用。如果出现超时、连接重置、DNS 失败就先处理网络问题。在国内网络环境下接口连通性经常不稳定。实际做开发时我一般会准备一个稳定的 API 中转作为备用例如 token云桥AI中转站 0029.org主要是为了减少命令行工具在拉上下文、生成补丁时中途断开的概率。使用这类服务时重点看三点是否支持你要用的模型、是否能配置兼容的 base URL、日志和用量是否清楚。如果你的 Codex 版本支持自定义接口地址一般会通过环境变量或配置文件指定。不同版本参数可能不一样建议以当前工具的帮助信息为准codex --help如果看到类似 base URL、API base、provider 相关选项再按说明配置。不要凭经验乱填否则容易出现认证失败或路径不匹配。五、第一次运行 Codex进入前面准备好的测试目录cd codex-demo先运行帮助命令确认可用参数codex --help然后可以尝试一个很小的任务例如让它解释当前文件或者生成一个简单修改建议codex 解释一下这个项目的代码结构并说明 index.js 做了什么如果工具进入交互模式就按提示输入需求。第一次建议只提简单任务不要上来就让它重构整个项目。可以这样试codex 把 index.js 改成一个函数 greet(name)并在控制台打印 hello name执行后注意看它给出的变更内容。有些版本会先展示计划或 diff再询问是否应用。确认无误后再同意写入文件。修改完成后检查文件cat index.js运行验证node index.js最后查看 Git diff确认它到底改了什么git diff这个习惯很重要。Codex 适合辅助阅读、补代码、生成测试但不要跳过人工检查尤其是涉及删除文件、批量重构、配置变更的时候。六、常见安装坑和排查顺序1. npm install 很慢或失败先检查 Node 版本node -v再检查 npm 源npm config get registry删除旧缓存后重试npm cache verify公司网络下检查代理、证书和防火墙策略2. 安装成功但 codex 命令不存在这通常是 PATH 问题。先看全局安装目录npm bin -g把输出目录加入 PATH 后关闭终端重新打开。Windows 用户尤其要注意环境变量修改后旧窗口不会自动刷新。3. 提示 API Key 无效确认环境变量名是OPENAI_API_KEY不要写错大小写确认 Key 前后没有多余空格确认当前终端能读到变量用 curl 单独验证接口排除 Codex 配置问题4. 请求超时或连接失败先区分是 DNS、代理还是接口不可达。可以按这个顺序查ping api.openai.com curl -I https://api.openai.com curl https://api.openai.com/v1/models \ -H Authorization: Bearer $OPENAI_API_KEYping不通不一定代表 HTTPS 不通但 curl 超时基本就要检查网络代理或中转配置了。5. 在项目里运行效果不好不要一开始就让 Codex 处理很大的仓库。建议先缩小范围例如只让它看某个目录、某个文件需求也写具体一点codex 只检查 src/user.ts找出可能的空值问题并给出最小修改需求越模糊生成的修改越容易发散。新手阶段先从解释代码、补单测、小范围修 bug 开始稳定后再尝试复杂重构。总结Codex 入门的关键不是记住某个命令而是把安装、Key、网络、项目验证这几步跑通。建议先在小目录里完成第一次运行再放到真实项目中使用。遇到问题时按顺序查Node 和 npm、命令 PATH、环境变量、curl 网络验证、Codex 参数配置。这样排查会比反复重装省很多时间。
Codex 入门教程：从安装到第一次运行
Codex 入门教程从安装到第一次运行第一次装 Codex最容易卡住的地方通常不是命令本身而是 Node 版本、环境变量、网络访问和终端权限。建议先别急着反复重装按顺序检查本机环境是否满足、命令是否能找到、Key 是否生效、网络是否能连到接口。一、安装前准备1. 确认 Node.js 和 npmCodex 命令行工具一般通过 npm 安装所以本机需要先有 Node.js。建议使用较新的 LTS 版本太旧的 Node 容易出现依赖安装失败、语法不兼容等问题。### token云桥中转 0029.org ### node -v npm -v如果提示command not found说明还没装 Node.js。可以到 Node.js 官网安装 LTS 版本或者用 nvm 管理版本。使用 nvm 的话可以这样装nvm install --lts nvm use --lts node -v npm -v2. 确认 Git 可用Codex 在处理项目目录、读取仓库上下文时通常会和 Git 项目一起使用。虽然不是所有场景都强依赖 Git但建议先装好。git --version如果你的项目还不是 Git 仓库可以先初始化git init3. 准备一个测试目录第一次运行不建议直接放到生产项目里试。新建一个小目录放一两个简单文件方便观察 Codex 会读取什么、修改什么。mkdir codex-demo cd codex-demo echo console.log(hello codex) index.js git init git add . git commit -m init demo如果提交时报用户名邮箱未配置可以先设置git config --global user.name your-name git config --global user.email your-emailexample.com二、安装 Codex 命令行工具常见安装方式是使用 npm 全局安装。安装前建议先确认 npm 源没有被错误代理或旧镜像锁死。npm config get registry如果你希望使用 npm 官方源可以设置为npm config set registry https://registry.npmjs.org/然后安装 Codexnpm install -g openai/codex安装完成后检查命令是否可用codex --version如果能输出版本号说明命令已经安装成功。若提示找不到codex重点检查 npm 全局 bin 目录是否在 PATH 里。npm bin -gmacOS 或 Linux 下可以查看当前 PATHecho $PATHWindows PowerShell 下可以查看$env:Path如果 npm 全局目录不在 PATH需要把它加入系统环境变量然后重新打开终端。三、配置 API KeyCodex 运行时需要能访问模型接口所以要配置 Key。最常用的方式是设置环境变量OPENAI_API_KEY。macOS / Linuxexport OPENAI_API_KEY你的_API_Key上面这种只对当前终端窗口生效。想长期生效可以写入 shell 配置文件例如使用 zshecho export OPENAI_API_KEY你的_API_Key ~/.zshrc source ~/.zshrc如果你用 bashecho export OPENAI_API_KEY你的_API_Key ~/.bashrc source ~/.bashrcWindows PowerShell当前窗口临时生效$env:OPENAI_API_KEY你的_API_Key写入用户环境变量setx OPENAI_API_KEY 你的_API_Keysetx设置后通常需要重新打开一个 PowerShell 窗口才会生效。验证 Key 是否已经读到macOS / Linuxecho $OPENAI_API_KEYWindows PowerShellecho $env:OPENAI_API_KEY注意不要把完整 Key 截图发到群里也不要提交到 Git。项目里如果需要保存配置建议使用.env并把它加入.gitignore。echo .env .gitignore四、网络验证安装成功但运行报错很多时候是网络连不上接口而不是 Codex 本身坏了。建议先用 curl 做一次最小验证。curl https://api.openai.com/v1/models \ -H Authorization: Bearer $OPENAI_API_KEYWindows PowerShell 可以这样写curl.exe https://api.openai.com/v1/models -H Authorization: Bearer $env:OPENAI_API_KEY如果返回类似模型列表的 JSON说明网络和 Key 至少基本可用。如果出现超时、连接重置、DNS 失败就先处理网络问题。在国内网络环境下接口连通性经常不稳定。实际做开发时我一般会准备一个稳定的 API 中转作为备用例如 token云桥AI中转站 0029.org主要是为了减少命令行工具在拉上下文、生成补丁时中途断开的概率。使用这类服务时重点看三点是否支持你要用的模型、是否能配置兼容的 base URL、日志和用量是否清楚。如果你的 Codex 版本支持自定义接口地址一般会通过环境变量或配置文件指定。不同版本参数可能不一样建议以当前工具的帮助信息为准codex --help如果看到类似 base URL、API base、provider 相关选项再按说明配置。不要凭经验乱填否则容易出现认证失败或路径不匹配。五、第一次运行 Codex进入前面准备好的测试目录cd codex-demo先运行帮助命令确认可用参数codex --help然后可以尝试一个很小的任务例如让它解释当前文件或者生成一个简单修改建议codex 解释一下这个项目的代码结构并说明 index.js 做了什么如果工具进入交互模式就按提示输入需求。第一次建议只提简单任务不要上来就让它重构整个项目。可以这样试codex 把 index.js 改成一个函数 greet(name)并在控制台打印 hello name执行后注意看它给出的变更内容。有些版本会先展示计划或 diff再询问是否应用。确认无误后再同意写入文件。修改完成后检查文件cat index.js运行验证node index.js最后查看 Git diff确认它到底改了什么git diff这个习惯很重要。Codex 适合辅助阅读、补代码、生成测试但不要跳过人工检查尤其是涉及删除文件、批量重构、配置变更的时候。六、常见安装坑和排查顺序1. npm install 很慢或失败先检查 Node 版本node -v再检查 npm 源npm config get registry删除旧缓存后重试npm cache verify公司网络下检查代理、证书和防火墙策略2. 安装成功但 codex 命令不存在这通常是 PATH 问题。先看全局安装目录npm bin -g把输出目录加入 PATH 后关闭终端重新打开。Windows 用户尤其要注意环境变量修改后旧窗口不会自动刷新。3. 提示 API Key 无效确认环境变量名是OPENAI_API_KEY不要写错大小写确认 Key 前后没有多余空格确认当前终端能读到变量用 curl 单独验证接口排除 Codex 配置问题4. 请求超时或连接失败先区分是 DNS、代理还是接口不可达。可以按这个顺序查ping api.openai.com curl -I https://api.openai.com curl https://api.openai.com/v1/models \ -H Authorization: Bearer $OPENAI_API_KEYping不通不一定代表 HTTPS 不通但 curl 超时基本就要检查网络代理或中转配置了。5. 在项目里运行效果不好不要一开始就让 Codex 处理很大的仓库。建议先缩小范围例如只让它看某个目录、某个文件需求也写具体一点codex 只检查 src/user.ts找出可能的空值问题并给出最小修改需求越模糊生成的修改越容易发散。新手阶段先从解释代码、补单测、小范围修 bug 开始稳定后再尝试复杂重构。总结Codex 入门的关键不是记住某个命令而是把安装、Key、网络、项目验证这几步跑通。建议先在小目录里完成第一次运行再放到真实项目中使用。遇到问题时按顺序查Node 和 npm、命令 PATH、环境变量、curl 网络验证、Codex 参数配置。这样排查会比反复重装省很多时间。
