我把 Codex 在 Windows 上跑通了：给新手看的安装和配置记录

这篇只写 Windows。

之前我想把 Windows、Mac、Linux 都放在一篇里，后来发现太长了。对刚接触 Codex 的朋友来说，一篇文章里出现太多系统、太多命令，反而更容易看懵。

所以这一篇就只做一件事：在 Windows 上把 Codex 跑起来。

我会按自己实际折腾的顺序写，尽量不讲太多概念。能复制的命令我直接贴出来，容易踩坑的地方也写在旁边。

先说 Codex 是干嘛的

Codex 可以理解成一个放在本地项目里的 AI 编程助手。

它不是只能聊天。你在某个文件夹里启动 Codex 后，它可以看这个文件夹里的代码，帮你分析项目结构、解释代码、定位报错，也可以在你确认后修改文件。

新手刚开始可以先让它做这些事：

• 看一个项目大概是干嘛的
• 分析项目用了哪些技术
• 解释某个报错
• 改一个很小的功能
• 帮你写一点测试

不要一上来就说“帮我重构整个项目”。这个范围太大，新手也不太好判断它改得对不对。

我的习惯是先让它看，再让它分析，最后才让它改。

安装前先准备一下

Windows 上这次只走 npm 安装。

你需要准备两个东西：

1. PowerShell
   Windows 自带，不用额外安装。

2. Node.js
   npm 是跟着 Node.js 一起安装的。后面安装 Codex 要用 npm。

如果你不知道自己有没有 Node.js，也没关系，下面会检查。

第一步：打开 PowerShell

按键盘上的 Windows 键，也就是 Ctrl 和 Alt 中间那个键。

搜索：

PowerShell

打开 Windows PowerShell 或者 PowerShell 都可以。

后面的命令都在这个窗口里输入。

第二步：检查 Node.js 和 npm

如果都能看到版本号，比如：
输入：

node -v 回车
v22.x.x
npm -v 回车
10.x.x

说明 Node.js 和 npm 已经有了，可以直接跳到下一步。

如果提示：

node 不是内部或外部命令
或者
npm 不是内部或外部命令

说明还没装 Node.js。

这时候打开 Node.js 官网：
下载 LTS 版本。安装过程一路下一步就行，不用改太多设置。

安装完之后，关闭 PowerShell，重新打开一次，再输入：

node -v 回车
npm -v 回车

能看到版本号，就说明这一步好了。

这了可能会遇到npm -v 提示你脚本无法运行:
你需要执行命令,同时允许脚本调用,然后你的npm命令就正常了:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

第三步：用 npm 安装 Codex

在 PowerShell 输入：

npm install -g @openai/codex

然后等它安装。

这里可能会等一会儿。如果长时间不动，大概率是 npm 包源访问不顺，可以换个网络环境再试。

安装完成后，输入，回车，如果能看到版本号：

codex --version
codex 0.x.x

说明 Codex 已经装好了。

如果提示：

codex 不是内部或外部命令

先关闭 PowerShell，再重新打开一次，然后重新输入：

codex --version

有时候只是环境变量还没刷新。

第四步：建一个测试文件夹

第一次别直接拿重要项目试。

我们先在桌面建一个测试文件夹。

可以选择在 PowerShell 输入：

cd Desktop
mkdir codex-test
cd codex-test

新建文件夹,也可以自己在任意位置新建一个文件夹.然后执行cd命令进入文件夹就好。

现在你已经进入了 codex-test 这个文件夹。

可以先放一个简单文件进去，比如：

notepad README.md

记事本弹出来后，随便写一句：

这是我第一次测试 Codex。

保存后关闭。

第五步：先启动一次 Codex

进入 codex-test 文件夹里输入：

codex

如果是第一次安装,这个时候会提示你:

第一次启动可能会让你登录。

如果你能正常登录官方账号，可以先按提示登录。

如果你准备用 API Key 接入，也可以继续往下看配置。

国内用户怎么接 API

国内用户用 Codex 时，最常见的问题其实不是安装，而是接口访问和模型管理。

如果你有自己的 API 网关，就可以把 Codex 接到自己的接口上。我自己使用的站点是：云AiCode，各位看官按需处理。注意我所有的截图都是我自己的在我使用站点的配置.创建API_KEY截图如下:

1. 创建账号我就不解释了.这里是新建api密钥
   
   2.新建的配置
   

后面的配置里我会用 https://cdn.yunaicode.com/v1 做占位，你实际填写时换成自己的接口地址就行。

第六步：创建 Codex 配置文件

Codex 的配置文件在这个位置：

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

新手可以手动去文件管理器里找到位置,自己新建，也可以直接用命令创建就行。

打开 PowerShell，输入：

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

如果弹出记事本，并提示文件不存在，要不要创建，点“是”。

然后把下面这段复制进去：

model = "这里填你能用的模型名"
model_provider = "custom"

[model_providers.custom]
name = "Custom API"
base_url = "https://cdn.yunaicode.com/v1"
env_key = "API_KEY"
wire_api = "responses"

approval_policy = "on-request"
sandbox_mode = "workspace-write"

[windows]
sandbox = "elevated"

这里要改两个地方。

第一个是模型名：

model = "这里填你能用的模型名"

不要自己猜，去你的后台复制可用模型名。

第二个是接口地址：

base_url = "https://cdn.yunaicode.com/v1"

注意最后的 /v1。少了这个，很容易报错。

改完之后，按Ctrl + S保存，然后关闭记事本。

注意注意:我截图里面用的都是我自己账号站点的,来源:云AiCode 各位根据自己情况来调整

第七步：设置 API Key

上面的配置里有一行：

env_key = "API_KEY"

意思是 Codex 会去 Windows 环境变量里找一个叫 API_KEY 的值。

所以我们要把自己的 Key 放进去。

在 PowerShell 输入，比如你的 Key 是 sk-xxxx，就写成：

setx API_KEY "sk-xxxx"

执行成功后，可能会看到：

SUCCESS: Specified value was saved.

这里有个小坑：setx 设置完之后，当前 PowerShell 不一定马上生效。

所以要关闭 PowerShell，重新打开一个新的 PowerShell。

然后检查一下：

echo $env:API_KEY

如果能看到你的 Key，就说明设置成功了。
注意截图里面的设置
PS:这个图片漏打码了key…懒得重新截图了,已经删掉了

第八步：让 Codex 用中文回复

我刚开始用的时候，Codex 经常中英文混着来。

比较简单的办法是在项目目录里放一个 AGENTS.md。

先进入刚才的测试目录：

cd Desktop\codex-test

然后创建文件：

notepad AGENTS.md

复制下面这段进去：

# AGENTS.md

## 回复习惯

- 默认使用简体中文回复。
- 命令、文件名、函数名保持原文。
- 解释代码时尽量说人话，不要写成官方文档。

## 操作规则

- 修改文件前先说明计划。
- 不确定的地方先问我。
- 不要改 .env、密钥文件和生产配置。
- 新增依赖前先说明原因。
- 修改完成后告诉我改了哪些文件，以及怎么验证。

保存后关闭。

然后启动 Codex：

codex

第一次可以这样问它：

请先阅读 AGENTS.md，后面默认用简体中文回复。

这样后面沟通会自然很多。

第九步：第一次怎么问 Codex

不要一上来就说：

帮我把项目改好

它不知道你说的“改好”是什么意思。

我建议按这个顺序来。

先让它看项目：

先不要修改文件，请帮我看一下当前项目结构，告诉我这个项目大概是做什么的。

再让它判断怎么启动：

这个项目应该怎么启动？先给我步骤，不要直接执行命令。

如果你有报错，就这样问：

我遇到了下面这个报错，请先帮我分析原因，不要直接改代码。

这里粘贴报错内容

确认之后再让它改：

请只修改和这个报错相关的文件，改动尽量小。修改前先告诉我计划。

这个节奏比较稳。

常见问题

1. npm install 卡住

大概率是网络问题。

换个网络环境，或者稍后再试。

2. codex 不是内部或外部命令

先关闭 PowerShell，重新打开。

然后再试：

codex --version

如果还不行，重新执行：

npm install -g @openai/codex

3. API Key 设置后没反应

setx 设置完，要重新打开 PowerShell。

然后检查：

echo $env:API_KEY

有输出才说明生效。

4. model not found

一般是模型名写错。

回到 config.toml，检查：

model = "这里填你能用的模型名"

把它改成你后台真实可用的模型名。

5. 接口 404

检查：

base_url = "https://cdn.yunaicode.com/v1"

重点看最后有没有 /v1。

6. Codex 一直用英文

确认项目目录里有没有 AGENTS.md。

启动后再说一句：

请先阅读 AGENTS.md，后续默认用简体中文回复。

最后说一句

新手第一次用 Codex，不要急着让它改大项目。

先建一个测试文件夹，跑通安装、配置、中文回复，再慢慢拿真实项目试。

我自己的感觉是，Codex 好用的地方不是“让它一次性替你写完整项目”，而是它能在项目上下文里帮你看代码、查问题、改小功能。

第一篇先写到这里。

后面如果继续写，我会再整理一篇 Windows 下 Codex 的常用提问模板。