Codex CLI 在 Windows 11 上从零到跑通：新手完全教程

写在前面（30 秒速览）

如果你是第一次接触命令行工具，或对「环境变量」「配置文件」这些词还陌生——完全不用担心。这篇会把每一步拆到最细，照着做就行。

如果任何一步卡住、看不懂、报错，随时停下来问 AI，把报错信息复制给它并说「我在跟着教程做，卡在这一步了」，它会带你逐个解决。

这是我们在 Windows 11 上从零跑通 Codex CLI 的完整真实过程。踩过坑、绕路过，最后发现核心其实就三件事：

一、先确认你的环境

开始前确认这三点，一步一步来：

检查项	你的情况	不确定怎么做
操作系统	Windows 11（家庭版/专业版均可）	按 Win+R 输 winver 回车看版本号
网络	能访问外网（Google/GitHub）	公司/学校内网可能需先问网管
终端工具	PowerShell 或 CMD	按 Win+S 搜「PowerShell」，右键管理员运行

二、安装 Codex：别用 npm，直接下载最省心

2.1 为什么不用 npm？（了解即可，可跳过）

官方文档写了可用 npm 安装：

npm install -g @openai/codex

但我们实测发现，Windows 平台最近有变动，npm 装完会报这个错：

Error: Missing optional dependency @openai/codex-win32-x64

因为 Codex 的 Windows 版本文件不再通过 npm 自动下载。新手直接跳过 npm，走更稳的方式。

2.2 正确做法：从 GitHub 下载

第一步：下载文件。访问 github.com/openai/codex/releases，找版本 0.150.0-alpha.8（或页面最新版），下载类似 codex-x86_64-pc-windows-msvc.exe.zip，解压到一个记得住的文件夹，比如：

C:\tools\codex\

💡 也可改成 D:\Software\codex\，但路径尽量别有中文字符或空格，避免后续问题。

第二步：加入系统 PATH（关键！）。刚下载完在 PowerShell 里敲 codex 会提示找不到命令，因为它还没「注册」进系统：

1. 按 Win+S 搜「环境变量」
2. 点「编辑系统环境变量」→ 弹窗点「环境变量」
3. 下半「系统变量」找 Path，双击它
4. 点「新建」，输入刚才的解压路径（如 C:\tools\codex）
5. 一路「确定」保存
6. 关掉当前 PowerShell 重开一个新的（否则系统没刷新）

第三步：验证安装。新窗口输入：

codex --version

codex-cli 0.150.0-alpha.8

三、配置模型端点：让 Codex 能「说话」

Codex 装好了，但它还不知连哪个 AI 服务。要写一个配置文件告诉它：用哪个端点、API 地址、走什么协议。下面以接入一个 OpenAI 兼容端点为例（你也可换成官方或其它服务）。

3.1 找到配置文件夹

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

3.2 创建 config.toml

新建文本文件命名 config.toml。注意后缀是 .toml——若显示 config.toml.txt，说明系统隐藏了扩展名，在资源管理器「查看」勾选「文件扩展名」删掉 .txt。复制以下内容（把 C:\users\administrator 改成你自己的用户名路径）：

# Codex 配置：改用户路径 + 端点信息即可
model = "openai/gpt-5.6-luna"
model_provider = "ofox"

[model_providers.ofox]
name = "ofox"
base_url = "https://api.ofox.io/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

# 改成你自己的用户名！
[projects.'C:\users\administrator']
trust_level = "trusted"

[windows]
sandbox = "unelevated"

[network]
use_websocket = false

3.3 创建 API Key 文件 auth.json

同目录新建 auth.json，把 sk-xxxxxxxxxx 换成你的真实 Key：

{"OPENAI_API_KEY": "sk-xxxxxxxxxx"}

3.4 我们踩过的三个坑

现象	原因	解决
启动一直转圈、超时	默认走 WebSocket（wss://）连不上	config 加 [network]，设 use_websocket = false
终端 curl 不通某域名，浏览器能开	DNS 污染，终端与浏览器解析路径不同	换可用域名作 base_url
连上了但无法正常对话	协议不匹配	在 provider 里加 wire_api = "responses"

看不懂表？没关系——只要 config 完全按 3.2/3.3 写，这三个坑你已经提前避开了。

四、启动验证：确认整条链路跑通

4.1 交互启动

codex

首次启动选登录方式：选择 3. Provide your own API key，然后输入问题（如 say hi）。一切正常会看到 AI 回复。

4.2 命令行快速验证（不进交互）

codex exec --json "say hi"

{
  "agent_message": "你好！有什么我可以帮你的吗？",
  "turn": "completed",
  "usage": { "input": 9499, "output": 13 }
}

五、排查清单

还有问题就按这个顺序查：

1. Codex 装了吗？ → codex --version 有无版本号
2. 配置路径对吗？ → 确认在 C:\Users\你的用户名\.codex\ 下
3. Key 填对了吗？ → 打开 auth.json，确认没多复制空格/换行
4. base_url 对吗？ → 别写错可用域名
5. 两个关键配置加了吗？ → wire_api = "responses" 和 use_websocket = false

六、核心经验总结

关键点	一句话总结
安装方式	Windows 上别用 npm，直接从 GitHub Releases 下 zip 最稳
PATH 配置	解压后必须手动把文件夹加进系统 Path
配置文件	不是只填 base_url 就行，wire_api 和 use_websocket 缺一不可

如果跟着做到了这里，Codex CLI 已经在你的 Windows 电脑上跑起来了。以后遇到任何命令行工具的安装问题，都可套用这套思路：下载 → 加 PATH → 写配置。

追光点评