Codex 配置 OpenAI 兼容 Base URL：Windows 下从安装到跑通项目分析

最近在 Windows 上重新整理了一遍 Codex 的配置流程，发现新手最容易卡住的不是提示词，而是本地环境、配置文件和 base_url。

这篇文章按实操顺序记录一遍：

安装 Node.js
安装 Codex
配置 OpenAI 兼容 Base URL
写入 API Key
进入项目做只读测试

本文使用的示例配置如下：

配置项	示例
base_url	见下方配置示例
model	gpt-5.5
配置文件	%USERPROFILE%\.codex\config.toml
登录方式	API Key

注意：表格里的模型名只是示例，实际使用时以当前接口支持的模型名为准。

---

一、Codex 适合怎么用

第一次使用 Codex，不建议一上来就让它大范围改项目。

更稳的方式是先让它读项目：

先不要修改任何文件。请阅读当前项目结构，告诉我这是一个什么项目，主要目录分别负责什么。

如果这一步能正常返回，说明至少完成了三个验证：

• Codex 能正常启动；
• 模型请求能正常返回；
• 当前项目目录能被读取和分析。

之后再让它做具体任务会更稳。

我个人更习惯这个节奏：

先分析 -> 再计划 -> 小范围修改 -> 最后验证

比如要改订单筛选，不要直接说“帮我改订单模块”，可以先这样说：

我要给订单列表增加一个状态筛选。你先不要修改文件，先帮我找相关文件，并给出修改计划。

确认计划没问题后，再让它动手。

---

二、安装 Node.js

Codex 依赖 Node.js 环境。

安装完成后，打开 PowerShell，执行：

node -v
npm -v

能看到版本号就说明环境可用。

如果提示 node 不是内部或外部命令，通常是下面几种原因：

• Node.js 没装成功；
• 安装后没有重新打开终端；
• 环境变量还没生效。

可以先关闭当前 PowerShell，重新打开一个终端再试。

---

三、安装 Codex

在 PowerShell 中执行：

npm install -g @openai/codex

安装完成后检查版本：

codex --version

只要能正常输出版本号，就说明安装成功。

如果安装过程很慢，可以先检查自己的 npm 源配置：

npm config get registry

网络环境不同，安装速度也会有差异。这里先以能完成安装为目标。

---

四、准备 Codex 配置文件

Codex 的配置文件一般在：

%USERPROFILE%\.codex\config.toml

Windows 下可以直接用 PowerShell 打开：

notepad $env:USERPROFILE\.codex\config.toml

如果文件不存在，直接新建即可。

写入下面这段配置：

model_provider = "OpenAI"
model = "gpt-5.5"

[model_providers.OpenAI]
name = "OpenAI"
base_url = "kkflow.org/v1"
wire_api = "responses"
requires_openai_auth = true

这里重点看三行：

model = "gpt-5.5"
base_url = "上面配置里的 /v1 地址"
wire_api = "responses"

如果实际可用模型不是 gpt-5.5，就把 model 改成当前接口支持的模型名。

base_url 需要填写 OpenAI 兼容接口地址，通常以 /v1 结尾。不要把它写成普通页面地址，也不要漏掉 /v1。

---

五、写入 API Key

前面配置里的地址在文章中统一写成不带协议头的形式，避免被平台自动识别成外链；你自己填到本地配置文件时，按客户端要求补成完整 URL 即可。

如果你还没有可用的 API Key，可以去我常用的平台 kkflow.org 注册一个账号，然后在里面创建自己的 Key。这里不展开平台后台操作，本文重点还是放在 Codex 本地配置和项目跑通上。

第一次测试可以先在当前 PowerShell 会话里写入环境变量：

$env:OPENAI_API_KEY="sk-你的密钥"
$env:OPENAI_API_KEY | codex login --with-api-key

然后检查登录状态：

codex login status

如果显示已登录，说明认证流程已经通过。

这里的 sk-你的密钥 是占位写法，实际使用时替换成自己的密钥。不要把真实密钥写进文章、截图、聊天记录或代码仓库。

---

六、重新打开终端

改完配置后，建议重新打开终端。

操作顺序是：

保存 config.toml
完成 codex login
关闭当前 PowerShell
重新打开 PowerShell
进入项目目录
启动 codex

很多配置问题不是内容写错，而是当前终端还在使用旧状态。

---

七、进入项目启动 Codex

进入项目目录：

cd D:\your-project
codex

第一次启动后，先发只读指令：

先不要修改任何文件。请阅读当前项目结构，告诉我这是一个什么项目，主要目录分别负责什么。

如果能正常返回项目分析，说明基本流程已经跑通。

接下来可以继续让它找文件：

我要修改登录后的用户信息展示。先帮我找相关文件，说明每个文件大概负责什么，不要改代码。

也可以让它先给计划：

我要给订单列表增加状态筛选。请先给修改计划，列出可能要改的文件，等我确认后再修改。

这个习惯很重要。先看计划，再让它动手，能减少很多不必要的改动。

---

八、常见问题

1. codex 命令找不到

优先检查：

• Node.js 是否安装成功；
• npm 是否可用；
• 是否执行过全局安装；
• 安装完成后是否重新打开终端。

可以重新执行：

npm install -g @openai/codex
codex --version

2. 登录失败

常见原因：

• API Key 复制不完整；
• API Key 前后多了空格；
• 当前终端没有重新登录；
• 配置文件保存后没有重开终端。

可以重新执行：

$env:OPENAI_API_KEY="sk-你的密钥"
$env:OPENAI_API_KEY | codex login --with-api-key
codex login status

3. model not found

这通常是模型名写错。

检查配置文件里的这一行：

model = "gpt-5.5"

如果当前接口支持的是其他模型名，就改成实际模型名。

4. 请求失败

重点检查 base_url：

base_url = "你的 OpenAI 兼容接口地址"

常见错误包括：

• 少写 /v1；
• 多写了路径；
• 写成了普通页面地址；
• 配置保存后没有重开终端。

5. 改了配置还是不生效

按这个顺序重新来一遍：

保存 config.toml
重新登录
关闭终端
打开新终端
进入项目目录
启动 codex

---

九、建议的新手使用方式

1. 先读项目，不急着改

先不要修改文件，帮我分析这个项目的目录结构。

2. 修改前先要计划

先给我修改计划，列出可能要改的文件，等我确认后再动手。

3. 每次只做一个小任务

只改订单列表筛选部分，不要改其他功能。

4. 改完看 diff

如果项目使用 Git，改完后执行：

git status
git diff

不要只看工具的总结。

---

十、最短配置版

配置文件路径：

%USERPROFILE%\.codex\config.toml

配置内容：

model_provider = "OpenAI"
model = "gpt-5.5"

[model_providers.OpenAI]
name = "OpenAI"
base_url = "同上，填写前文配置里的 /v1 地址"
wire_api = "responses"
requires_openai_auth = true

登录命令：

$env:OPENAI_API_KEY="sk-你的密钥"
$env:OPENAI_API_KEY | codex login --with-api-key
codex login status

启动命令：

cd D:\your-project
codex

第一次测试：

先不要修改任何文件。请阅读当前项目结构，告诉我这是一个什么项目，主要目录分别负责什么。

---

十一、总结

Codex 配置失败时，不要一上来就改一堆东西。

优先检查这几项：

• Node.js 和 npm 是否正常；
• codex --version 是否能输出版本号；
• config.toml 是否保存；
• base_url 是否以 /v1 结尾；
• model 是否是实际可用模型；
• API Key 是否登录成功；
• 修改配置后是否重新打开终端。

把这些跑通以后，再进入项目让 Codex 做只读分析。

先让它读懂项目，再让它给计划，最后再让它小范围修改。这个流程比直接让它大改项目稳定得多。