Codex 小白安装教程:从 0 到跑通第三方 API

这篇默认你不会命令行。
你只需要照着复制命令，看电脑返回什么结果，再走下一步。
这是「Codex 小白到实战」系列的第一篇。
这个系列会参考开源项目《Codex 蓝皮书》的章节结构，但每篇都会重新用新手能听懂的方式讲一遍，并优先用官方文档和本机实测校验命令。

很多 Codex 教程一上来就是一行命令：

npm install -g @openai/codex

这行命令没错，但对新手不够。

真正卡人的地方通常不是“安装”，而是后面的三件事：

装完以后，电脑提示 codex: command not found。
登录时不知道该选 ChatGPT，还是 API Key。
想接 OpenRouter、中转 API、New API 这类第三方接口，不知道配置文件怎么写。

这篇只解决一件事：

让你第一次把 Codex 跑起来。

后面再讲怎么给 Codex 提需求、怎么写 AGENTS.md 规则、怎么让它接手真实项目。先别急着学那些，第一步是让工具能稳定打开。

1. Codex 是什么？

Codex 是 OpenAI 的 AI 编程助手。

它可以在你的电脑项目里做这些事：

看代码。
改代码。
运行命令。
帮你排查报错。
解释一个项目是怎么工作的。

你可以先把它理解成：

一个住在终端里的 AI 程序员

这里有两个词先说清楚。

终端：电脑里输入命令的窗口。Mac 上就叫“终端”，Windows 上可以用 PowerShell。

CLI：命令行版。Codex CLI 的意思就是“在终端里运行的 Codex”。

如果你以前没用过终端，也没关系。本文里的命令都可以直接复制。

2. 安装前先检查电脑

打开终端，先输入：

git --version
node --version
npm --version

你可能看到类似这样的结果：

git version 2.45.0
v24.4.1
11.4.2

只要能看到版本号，就说明这些工具已经装好了。

如果提示 command not found，说明电脑里还没有对应工具。

完全新手建议这样处理：

没有 Git：去 Git 官网安装。
没有 Node / npm：去 Node.js 官网安装 LTS 版本。
Mac 用户也可以用 Homebrew，但如果你不知道 Homebrew 是什么，先不用管。

3. 安装 Codex

安装方式有好几种。小白不要纠结，优先用官方安装脚本。

Mac / Linux 复制这一行：

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

Windows PowerShell 复制这一行：

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

如果你本来就熟悉 npm，也可以用：

npm install -g @openai/codex

如果你是 Mac，并且已经会用 Homebrew，也可以用：

brew install --cask codex

安装完，输入：

codex --version

如果你看到类似这样的返回：

codex-cli 0.xxx.x

说明安装成功。

如果看到：

codex: command not found

说明电脑还找不到 Codex 命令。先不要继续配置 API，直接跳到后面的“常见报错排查”。

懒人一键安装包:https://api.aiphui.top/docs/

4. 第一次启动 Codex

先建一个测试目录，不要一上来就在重要项目里试。

复制：

mkdir codex-demo
cd codex-demo
git init
codex

这几行的意思是：

mkdir codex-demo：新建一个测试文件夹。
cd codex-demo：进入这个文件夹。
git init：把它变成一个 Git 项目。
codex：启动 Codex。

第一次启动时，Codex 会让你登录。

常见有两种方式：

ChatGPT 登录：适合已经有 ChatGPT 账号和订阅的人。
API Key 登录：适合想按 API 用量付费，或者想接第三方 API 的人。

新手建议：

只是想先体验：选 ChatGPT 登录。
明确要用第三方 API：继续看后面的配置。

5. Codex 的配置文件在哪里？

Codex 有一个设置文件，名字叫：

config.toml

你可以把它理解成：

Codex 的设置面板

它一般放在这里：

~/.codex/config.toml

Mac / Linux 可以这样打开：

mkdir -p ~/.codex
nano ~/.codex/config.toml

如果你会用 VS Code，也可以：

code ~/.codex/config.toml

Windows 一般在：

C:\Users\你的用户名\.codex\config.toml

这个文件会告诉 Codex：

用哪个模型。
去哪里调用模型。
API Key 从哪里读。
第三方接口怎么连。

6. 如果你用 OpenAI 官方账号

最简单的方式是直接登录：

codex login

然后按提示选择 ChatGPT 登录或 API Key 登录。

如果你只是想指定默认模型，可以在 config.toml 写：

model = "gpt-5.4"
model_provider = "openai"

这里的 model_provider 可以理解成“模型服务商”。

这段配置的意思是：

让 Codex 使用 OpenAI 官方服务。

如果你不知道自己要不要改这个，先不用改。

7. 为什么要配置第三方 API？

很多人配置第三方 API，通常是因为：

想用 OpenRouter。
想用中转站。
公司有自己的模型网关。
某些模型只在第三方平台里方便调用。

第三方平台一般会给你三样东西：

接口地址 Base URL
API Key
模型名

新手可以这样理解：

接口地址 Base URL：Codex 要去哪里找模型。
API Key：你的钥匙。
模型名：你要用哪个模型。

接下来用 OpenRouter 举例。

8. 第三方 API 配置：OpenRouter 示例

第一步：设置 API Key

Mac / Linux 复制这一行，把里面的中文换成你的真实 Key：

export OPENROUTER_API_KEY="你的 OpenRouter Key"

如果想长期生效，复制：

echo'export OPENROUTER_API_KEY="你的 OpenRouter Key"' >> ~/.zshrc
source ~/.zshrc

Windows PowerShell 复制：

setx OPENROUTER_API_KEY "你的 OpenRouter Key"

Windows 这一步做完后，要重新打开一个 PowerShell。

然后检查一下：

echo $env:OPENROUTER_API_KEY

如果能看到一串 Key，说明环境变量设置成功。

如果什么都没有，说明 Key 没生效。

第二步：写配置文件

打开配置文件：

nano ~/.codex/config.toml

填入下面这段：

model = "~openai/gpt-latest"
model_provider = "openrouter"

[model_providers.openrouter]
name = "OpenRouter"
base_url = "https://openrouter.ai/api/v1"
env_key = "OPENROUTER_API_KEY"
wire_api = "responses"

这段不用全部理解，先知道每一行大概是什么意思：

model：你要用的模型名。真实使用时，以 OpenRouter 模型页为准。
model_provider：让 Codex 使用哪个模型服务商。
[model_providers.openrouter]：创建一个叫 openrouter 的模型服务商配置。
base_url：OpenRouter 的接口地址。
env_key：API Key 所在的环境变量名字。注意，这里不是写真实 Key。
wire_api = "responses"：这行先照抄。很多第三方 API 连不上，就是少了它。

重点再说一次：

env_key 后面写的是环境变量名字，不是 API Key 本身。

错误写法：

env_key = "sk-xxxxxxxx"

正确写法：

env_key = "OPENROUTER_API_KEY"

第三步：启动 Codex 测试

输入：

codex

然后问它一句：

请用一句话介绍当前目录。

如果它能正常回答，说明已经接通。

如果报 401 / 403 / 404，看后面的排查。

9. 其他中转 API 怎么配？

如果你用的不是 OpenRouter，而是其他中转站、New API、公司内部网关，可以套这个模板：

model = "你的模型名"
model_provider = "my_proxy"

[model_providers.my_proxy]
name = "My Proxy"
base_url = "https://你的接口地址/v1"
env_key = "MY_PROXY_API_KEY"
wire_api = "responses"

然后设置环境变量：

export MY_PROXY_API_KEY="你的 API Key"

你只需要替换 3 个地方：

model：换成平台给你的模型名。
base_url：换成平台给你的接口地址。
MY_PROXY_API_KEY：换成你自己取的环境变量名。

其他地方先不要乱改。

10. 进阶：更安全的密钥写法

这一段不是必看。

如果你只是第一次安装，可以先跳过。

如果你不想把 Key 写进 shell 配置里，可以把 Key 单独放到一个本地文件。

先创建文件：

mkdir -p ~/.codex/secrets
nano ~/.codex/secrets/openrouter_api_key
chmod 600 ~/.codex/secrets/openrouter_api_key

然后 config.toml 写：

model = "~openai/gpt-latest"
model_provider = "openrouter"

[model_providers.openrouter]
name = "OpenRouter"
base_url = "https://openrouter.ai/api/v1"
wire_api = "responses"

[model_providers.openrouter.auth]
command = "/bin/sh"
args = ["-lc", "cat \"$HOME/.codex/secrets/openrouter_api_key\""]
timeout_ms = 5000
refresh_interval_ms = 0

这段的意思是：

Codex 每次需要 Key 时，从本地文件里读取。

这比直接把 Key 到处复制更安全。

11. 常见报错排查

1. `codex: command not found`

意思是：电脑找不到 Codex 命令。

先输入：

npm prefix -g

如果你不想研究 PATH，最简单的办法是换官方安装脚本或 Homebrew 重新装。

PATH 可以理解成：

电脑用来寻找命令的位置列表。

小白不需要一开始就理解它。

2. 401 / 403

通常是这几个原因：

API Key 写错了。
环境变量没有生效。
平台余额不足。
这个 Key 没有模型权限。

检查：

echo$OPENROUTER_API_KEY

如果没有返回任何内容，说明 Key 没设置成功。

如果返回了 Key，也不要截图发给别人。

3. 404 / model not found

通常是模型名写错，或者接口地址写错。

重点检查：

model = "平台实际模型名"
base_url = "https://平台接口地址/v1"

模型名不要自己猜。

去平台模型页复制。

4. 第三方 API 一直连不上

先检查配置里有没有这一行：

wire_api = "responses"

如果没有，先加上。

这行可以先不用理解，照抄就行。

5. npm 安装报权限错误

不要急着乱用 sudo。

小白最稳的办法是：

换官方安装脚本，或者用 Homebrew 安装。

12. 小白最稳路线

如果你只是想最快用起来：

官方脚本安装
→ codex --version
→ codex login
→ 新建测试目录
→ codex

如果你想接第三方 API：

安装 Codex
→ 设置 API Key
→ 创建 ~/.codex/config.toml
→ 填 model_providers 配置
→ codex 测试

如果你要长期用 Codex 写项目：

先进入一个 Git 项目
→ 让 Codex 解释项目结构
→ 让它只改一个小功能
→ 自己检查 diff
→ 跑测试

不要一上来就让它重构整个项目。

先让它做小事。

结尾

这一篇先把安装和 API 配置跑通。

你现在至少应该知道：

Codex 是在终端里运行的 AI 编程助手。
config.toml 是 Codex 的设置文件。
第三方 API 要配置 model_provider 和 model_providers。
env_key 后面写环境变量名，不写真实密钥。
wire_api = "responses" 先照抄。
看到 401 / 403，多半先查 Key。
看到 404，多半先查模型名和接口地址。

下一篇写：

Codex 新手第一次使用：怎么提需求，怎么让它改代码，怎么检查它有没有乱改

真正让 Codex 变强的，不是装上它。

是你学会给它一个清楚、可验证、能落地的任务。

参考来源

OpenAI Codex CLI 官方页：https://developers.openai.com/codex/cli
OpenAI Codex GitHub：https://github.com/openai/codex
OpenAI Codex 配置文档：https://developers.openai.com/codex/config-advanced
OpenAI Codex 认证文档：https://developers.openai.com/codex/auth
OpenRouter Codex CLI 集成文档：https://openrouter.ai/docs/cookbook/coding-agents/codex-cli

扫一扫,远程帮你解决一切问题!!!