乐于分享
好东西不私藏
夜雨聆风 > > 办公文件 > Codex 小白安装教程:从 0 到跑通第三方 API

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

当前时间： 2026-08-14 01:44:24 分类：办公文件 评论(0)
Codex 小白安装教程:从 0 到跑通第三方 API

这篇默认你不会命令行。
你只需要照着复制命令，看电脑返回什么结果，再走下一步。

这是「Codex 小白到实战」系列的第一篇。
这个系列会参考开源项目《Codex 蓝皮书》的章节结构，但每篇都会重新用新手能听懂的方式讲一遍，并优先用官方文档和本机实测校验命令。

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

npm install -g @openai/codex

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

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

  1. 装完以后，电脑提示 codex: command not found。
  2. 登录时不知道该选 ChatGPT，还是 API Key。
  3. 想接 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 会让你登录。

常见有两种方式：

  1. ChatGPT 登录：适合已经有 ChatGPT 账号和订阅的人。
  2. 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 个地方：

  1. model：换成平台给你的模型名。
  2. base_url：换成平台给你的接口地址。
  3. 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
扫一扫,远程帮你解决一切问题!!!

相关学习资料