Codex 从安装到国内接入跑通了：Windows / Mac / Linux 小白版记录

我把 Codex 从安装到国内接入跑通了：Windows / Mac / Linux 小白版记录

单独整理了windows从安装到运行的保姆级教程

这两天我又重新折腾了一遍 Codex。

这篇写得比较细，因为问我的朋友里不只有程序员，也有 HR、运营同学。他们也想试试 Codex，但一看到终端、配置文件、API Key，就有点懵。

他们问得最多的是这几个问题：

Windows 到底能不能装？ 命令应该在哪里输入？ API Key 放在哪里？ 国内怎么接比较方便？ 为什么 Codex 一直用英文回我？

这里先说一个情况：安装 Codex 的时候，npm 包源要能正常访问。安装成功后，如果后面走国内 API 网关，日常使用就不一定一直依赖魔法。

网上教程不少，但很多都默认你已经会终端、会配环境、知道配置文件在哪。对新手来说，最容易卡的反而就是这些地方。

这篇就按小白视角来，步骤尽量拆细。能复制的命令直接复制，容易踩的坑也顺手写上。

这篇算 Codex 系列第一篇，先把环境跑起来。

1. Codex 是什么？先用一句话理解

Codex 是一个“在你电脑项目里工作的 AI 编程助手”。

它不是只能聊天。你在某个项目目录里启动 Codex 后，它可以读取项目文件，帮你看目录结构、解释代码、分析报错，也可以在你确认后修改文件、执行命令。

刚开始可以先把它当成这几种工具：

• 帮你读项目文档
• 看项目的助手
• 帮你看项目用了什么技术
• 帮你查报错大概出在哪
• 帮你改一点小功能
• 帮你写测试
• 帮你做代码 review

刚开始不要直接说“帮我重构整个项目”。这个范围太大，新手也不好判断它改得对不对。

比较稳的方式是：先让它读项目，再让它分析，再让它小范围修改。

2. 安装前先准备什么？

先确认自己是哪种系统：

• Windows 用户：建议先用 PowerShell
• Mac 用户：使用系统自带终端 Terminal
• Linux 用户：使用终端

然后准备两个东西：

如果你准备走 API Key 方式，后面我会写怎么配置。（PS：我自己平时用 Mac，所以 Windows 这块没法放截图，只能把命令写细一点。）

3. Windows 安装 Codex

这里我只写 npm 安装方式。

简单理解一下：npm 是 Node.js 自带的包管理工具。我们先安装 Node.js，然后用 npm 安装 Codex。

第一步：打开 PowerShell

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

PowerShell

然后打开它。

如果你不知道该选哪个，就选系统自带的 Windows PowerShell 或 PowerShell 都可以。

第二步：检查有没有 Node.js 和 npm

先输入：

node –v

再输入：

npm –v

如果两条命令都能看到版本号，比如：

v22.x.x
10.x.x

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

如果提示不是内部或外部命令，说明还没装 Node.js。

这时候打开 Node.js 官网：

https://nodejs.org

下载 LTS 版本，一路下一步安装即可。装完之后，关闭 PowerShell，重新打开，再执行：

node –v
npm –v

能看到版本号就可以继续。

第三步：用 npm 安装 Codex

在 PowerShell 输入：

npm install –g @openai/codex

等待它安装完成。

如果中间卡住，大概率是 npm 包源访问不顺。可以换个网络环境后再试。

第四步：检查 Codex 有没有装好

继续在 PowerShell 输入：

codex —version

如果能看到版本号，比如类似：

codex 0.x.x

就说明 Codex 已经安装好了。

如果提示：

codex 不是内部或外部命令

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

codex —version

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

第五步：新建一个测试项目目录

比如我在 D 盘新建一个目录：

mkdir D:\\code\\codex-test
cd D:\\code\\codex-test

如果你的电脑没有 D 盘，也可以放桌面：

cd Desktop
mkdir codex-test
cd codex-test

第六步：启动 Codex

在这个目录里输入：

codex

第一次启动会让你登录。你可以先按界面提示使用账号登录。

如果你准备使用 API Key，也可以先退出，继续看后面的 API 网关配置。

4. Mac 安装 Codex

Mac 用户打开系统自带的“终端”。

可以按 Command + 空格，搜索：

Terminal

或者搜索：

终端

打开后先检查有没有 Node.js 和 npm：

node -v
npm -v

如果能看到版本号，说明已经安装好了 Node.js 和 npm。

如果提示 command not found，先去 Node.js 官网下载 LTS 版本安装：

https://nodejs.org

安装完成后，关闭终端，重新打开，再输入：

node -v
npm -v

确认能看到版本号后，再安装 Codex：

npm install -g @openai/codex

安装完成后检查：

codex –version

如果能看到版本号，就可以继续。

新建一个测试目录：

mkdir -p ~/code/codex-test
cd ~/code/codex-test

启动 Codex：

codex

5. Linux 安装 Codex

Linux 用户打开终端。

先检查有没有 Node.js 和 npm：

node -v
npm -v

如果能看到版本号，可以直接安装 Codex：

npm install -g @openai/codex

如果提示没有 node 或 npm，先安装 Node.js 和 npm。

Ubuntu / Debian 可以先试：

sudo apt update
sudo apt install -y nodejs npm

安装后再检查：

node -v
npm -v

然后安装 Codex：

npm install -g @openai/codex

如果遇到权限问题，可以用：

sudo npm install -g @openai/codex

安装完成后检查：

codex –version

创建测试目录：

mkdir -p ~/code/codex-test
cd ~/code/codex-test

启动：

codex

6. 国内用户为什么还要看 API 配置？

如果你能直接用官方账号登录，并且网络访问正常，这一节可以先跳过。

但国内用户实际用的时候，经常会遇到几个问题。说白了，主要就是访问不稳定，或者一直要折腾网络环境。

• 登录或接口访问不稳定
• 不同模型的 Key 分散在不同地方
• 想同时试 OpenAI、Claude、Gemini 等模型
• 想看用量统计
• 想统一管理模型入口

所以我自己更习惯用一个统一 API 网关，把不同模型放在一个入口里管理。这里不多展开，我使用的站点是：云AiCode，各位看官按需处理啊.如果有用注册一下,我也能多白嫖一点token.谢谢

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

7. 先搞清楚配置文件放在哪里

Codex 的配置文件叫：

config.toml

它一般放在 .codex 文件夹里。

Windows 配置文件路径

Windows 一般是：

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

比如你的用户名是 zhangsan，路径可能就是：

C:\\Users\\zhangsan\\.codex\\config.toml

Mac / Linux 配置文件路径

一般是：

~/.codex/config.toml

这里的 ~ 代表你的用户目录。

8. Windows 怎么创建 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"

然后把第一行里的：

这里填你后台可用的模型名

改成你自己能用的模型名。

注意，不要自己猜模型名，尽量复制后台显示的名字。

第三步：保存文件

记事本里按：

Ctrl + S

然后关闭记事本。

9. Mac / Linux 怎么创建 config.toml

打开终端，输入：

mkdir -p ~/.codex
nano ~/.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"

同样，把：

这里填你后台可用的模型名

换成你自己能用的模型名。

保存方式：

这样就保存并退出了。

10. 设置 API Key

配置文件里没有直接写 API Key，而是写了：

env_key = "API_KEY"

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

所以我们还要把 Key 设置到环境变量里。

Windows 设置 API Key

打开 PowerShell，输入：

setx API_KEY "你的 API Key"

比如你的 Key 是 sk-xxxx，就写成：

setx API_KEY "sk-xxxx"

执行成功后，PowerShell 可能会提示：

SUCCESS: Specified value was saved.

然后一定要关闭当前 PowerShell，重新打开一个新的 PowerShell。

重新打开后，可以检查一下：

echo $env:API_KEY

如果能看到你的 Key，就说明生效了。

Mac / Linux 设置 API Key

临时设置，可以输入：

export API_KEY="你的 API Key"

这种方式只对当前终端窗口有效。

如果想长期生效，先判断你用的是 zsh 还是 bash：

echo $SHELL

如果输出里有 zsh，执行：

echo 'export API_KEY="你的 API Key"' >> ~/.zshrc
source ~/.zshrc

如果输出里有 bash，执行：

echo 'export API_KEY="你的 API Key"' >> ~/.bashrc
source ~/.bashrc

检查一下：

echo $API_KEY

能看到 Key 就说明成功了。

11. 第一次启动 Codex

先进入一个测试目录。

Windows：

cd D:\\code\\codex-test
codex

如果你前面是放桌面：

cd Desktop\\codex-test
codex

Mac / Linux：

cd ~/code/codex-test
codex

启动后可以先输入一句最简单的：

你好，请用一句话介绍一下你现在能帮我做什么。

如果它正常回复，就说明基本跑通了。

如果报错，先看报错里有没有这些关键词：

• model not found
• 401
• 403
• 404
• unsupported endpoint
• API key

这些问题后面我会单独说。

12. 让 Codex 默认用中文回复

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

后来我发现，最简单的方式是在项目根目录放一个 AGENTS.md。

这个文件可以理解成“写给 Codex 看的项目说明”。

Windows 创建 AGENTS.md

进入你的项目目录，比如：

cd D:\\code\\codex-test
notepad AGENTS.md

记事本弹出来后，复制下面内容：

# AGENTS.md

## 回复习惯

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

## 操作规则

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

保存后关闭。

Mac / Linux 创建 AGENTS.md

进入项目目录：

cd ~/code/codex-test
nano AGENTS.md

复制同样内容进去：

# AGENTS.md

## 回复习惯

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

## 操作规则

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

保存方式还是：

启动后提醒它读规则

然后运行：

codex

第一次可以这样说：

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

这样后面就舒服很多。

13. 第一次应该怎么问 Codex？

新手最容易犯的错误是任务给得太大。

比如这句就不太适合：

帮我把项目改好

Codex 不知道你说的“改好”到底是什么。

更稳的方式是一步一步来。

第一步：先让它看项目

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

第二步：让它判断怎么启动

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

第三步：遇到报错时这样问

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

这里粘贴报错内容

第四步：确认后再让它改

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

这个节奏会稳很多。

先分析，再计划，再修改，再验证。不要一开始就让它全自动乱跑。

14. 新手常见报错怎么处理

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

Windows 常见。

先关闭 PowerShell，重新打开，再试：

codex —version

如果还不行，说明安装没有成功，重新执行 npm 安装命令：

npm install –g @openai/codex

2. Windows 设置 Key 后没反应

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

然后用这个检查：

echo $env:API_KEY

能看到 Key 才说明生效。

3. model not found

一般是模型名写错。

回到 config.toml，检查这一行：

model = "这里填你后台可用的模型名"

把它改成你自己能用的模型名。

4. 接口 404

优先检查 base_url。

配置里可以写成这种形式：

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

注意最后有 /v1。

5. API Key 报错

检查环境变量是否设置成功。

Windows：

echo $env:API_KEY

Mac / Linux：

echo $API_KEY

如果没有输出，说明 Key 没设置成功。

6. unsupported endpoint

这个一般和接口支持有关。

Codex 配置里用了：

wire_api = "responses"

如果当前模型或渠道不支持 Responses API，就可能报这个错误。可以换一个模型或渠道再试。

7. Codex 一直用英文

项目根目录创建 AGENTS.md，写清楚：

默认使用简体中文回复。

启动后再说一句：

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

15. 正式改项目之前，建议先做备份

如果你准备让 Codex 修改真实项目，建议先用 Git 做一个 checkpoint。

进入项目目录后执行：

git status
git add .
git commit -m "checkpoint before codex"

如果你还不会 Git，也至少先复制一份项目文件夹。

新手阶段别怕慢，先保证能回退。

16. 我自己现在的使用习惯

我现在一般会这样用 Codex：

先让它看：

先不要改文件，帮我读一下这个项目结构。

再让它分析：

这个报错可能和哪些文件有关？先列出来。

再让它计划：

如果要修这个问题，你打算改哪些地方？先给我方案。

最后才让它动手：

按刚才方案修改，改动尽量小。

这样用下来，Codex 更像一个项目助手，而不是一个你完全看不住的自动脚本。

17. 小结

这篇主要把 Codex 新手最容易卡住的地方走了一遍：

• Windows 怎么装
• Mac 怎么装
• Linux 怎么装
• 配置文件在哪里
• 国内用户怎么接 API 网关
• API Key 怎么设置
• 怎么让 Codex 用中文回复
• 第一次怎么问
• 常见报错怎么排查

我自己的感受是，Codex 最有价值的地方不是“替你一口气写完项目”，而是它能在本地项目上下文里帮你一起看代码、分析问题、做小范围修改。

第一篇先到这里。后面可以继续整理 Codex 的常用配置、权限模式、常用提问模板，以及更适合新手的实战例子。