Codex 入门教程：从安装到第一次运行

Codex 入门教程：从安装到第一次运行

第一次装 Codex，最容易卡住的地方通常不是命令本身，而是 Node 版本、环境变量、网络访问和终端权限。建议先别急着反复重装，按顺序检查：本机环境是否满足、命令是否能找到、Key 是否生效、网络是否能连到接口。

一、安装前准备

1. 确认 Node.js 和 npm

Codex 命令行工具一般通过 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 -v

2. 确认 Git 可用

Codex 在处理项目目录、读取仓库上下文时，通常会和 Git 项目一起使用。虽然不是所有场景都强依赖 Git，但建议先装好。

git --version

如果你的项目还不是 Git 仓库，可以先初始化：

git init

3. 准备一个测试目录

第一次运行不建议直接放到生产项目里试。新建一个小目录，放一两个简单文件，方便观察 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-email@example.com"

二、安装 Codex 命令行工具

常见安装方式是使用 npm 全局安装。安装前建议先确认 npm 源没有被错误代理或旧镜像锁死。

npm config get registry

如果你希望使用 npm 官方源，可以设置为：

npm config set registry https://registry.npmjs.org/

然后安装 Codex：

npm install -g @openai/codex

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

codex --version

如果能输出版本号，说明命令已经安装成功。若提示找不到codex，重点检查 npm 全局 bin 目录是否在 PATH 里。

npm bin -g

macOS 或 Linux 下可以查看当前 PATH：

echo $PATH

Windows PowerShell 下可以查看：

$env:Path

如果 npm 全局目录不在 PATH，需要把它加入系统环境变量，然后重新打开终端。

三、配置 API Key

Codex 运行时需要能访问模型接口，所以要配置 Key。最常用的方式是设置环境变量OPENAI_API_KEY。

macOS / Linux

export OPENAI_API_KEY="你的_API_Key"

上面这种只对当前终端窗口生效。想长期生效，可以写入 shell 配置文件，例如使用 zsh：

echo 'export OPENAI_API_KEY="你的_API_Key"' >> ~/.zshrc source ~/.zshrc

如果你用 bash：

echo 'export OPENAI_API_KEY="你的_API_Key"' >> ~/.bashrc source ~/.bashrc

Windows PowerShell

当前窗口临时生效：

$env:OPENAI_API_KEY="你的_API_Key"

写入用户环境变量：

setx OPENAI_API_KEY "你的_API_Key"

setx设置后，通常需要重新打开一个 PowerShell 窗口才会生效。

验证 Key 是否已经读到

macOS / Linux：

echo $OPENAI_API_KEY

Windows PowerShell：

echo $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_KEY"

Windows 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_KEY"

ping不通不一定代表 HTTPS 不通，但 curl 超时基本就要检查网络代理或中转配置了。

5. 在项目里运行效果不好

不要一开始就让 Codex 处理很大的仓库。建议先缩小范围，例如只让它看某个目录、某个文件，需求也写具体一点：

codex "只检查 src/user.ts，找出可能的空值问题，并给出最小修改"

需求越模糊，生成的修改越容易发散。新手阶段先从解释代码、补单测、小范围修 bug 开始，稳定后再尝试复杂重构。

总结

Codex 入门的关键不是记住某个命令，而是把安装、Key、网络、项目验证这几步跑通。建议先在小目录里完成第一次运行，再放到真实项目中使用。遇到问题时按顺序查：Node 和 npm、命令 PATH、环境变量、curl 网络验证、Codex 参数配置。这样排查会比反复重装省很多时间。