Codex 官网国内访问 + 完整安装教程：macOS / Windows / Linux 一次跑通（2026）
codex-cliai-codingchina-guidetutorial

Codex 官网国内访问 + 完整安装教程：macOS / Windows / Linux 一次跑通（2026）

TL;DR — chatgpt.com/codex 和 openai.com/codex 这俩入口在国内都打不开，CLI 默认连 api.openai.com 也连不通。绕梯子不如直接把 Codex CLI 的 base_url 指向 OpenAI 兼容网关。本文给 macOS、Windows、Linux 三平台一份从安装到第一次跑通的可照抄步骤，模型用 ofox 上架的 openai/gpt-5.3-codex，全程不碰 OpenAI 账号。

为什么 Codex 官网国内访问这么麻烦

Codex 不是一个单独的产品，是 OpenAI 在 2025 末重启的一组编程入口的统称。它现在有几种形态：桌面 App（macOS / Windows，安装包在 chatgpt.com 子路径下）、IDE 插件（VS Code / Cursor / Windsurf）、CLI（@openai/codex npm 包，本文重点）、以及云端浏览器版（chatgpt.com/codex，仅在线，要绑 GitHub 仓库）。

不管走哪一种，首次启动都要去 chatgpt.com 或 api.openai.com 完成鉴权。在国内这就是麻烦的开始：chatgpt.com 走 Cloudflare 边缘节点，国内 DNS 解析时延不稳定，登录页经常加载到一半挂掉；api.openai.com 在大陆出口被收紧，超时、握手失败、SSL 报错都常见；developers.openai.com 文档站偶尔能打开，但下载安装包时跳到的对象存储域名又是另一回事。

只看文档，凑合一下梯子还能忍。但 Codex CLI 是常驻进程，每次请求都要握手，梯子稳定性会直接决定编程会话能不能进行下去。装完跑半天最后回来骂”网络问题”，多半就是栽在这里。

更彻底的做法是让 CLI 不要去连 OpenAI 的域名。Codex CLI 从设计上就支持自定义 base_url 和 wire_api，把请求改向 OpenAI 兼容网关，整个调用链就不再碰 openai.com。本文用 ofox.ai 演示，原因很实在：它把 GPT-5.3 Codex 和 GPT-5.4 系列都上架了，模型 ID 直接以 openai/ 开头，CLI 不需要做额外映射。

安装前的准备

不分平台先确认两件事，省得装到一半返工。

第一是 Node.js 版本。Codex CLI 当前要求 Node ≥ 22，官方实测的最低版本是 22.22.0。Node 20 及以下都跑不起来，npm 全局安装能过，但启动 codex 时会报 SyntaxError: Unexpected token 之类的解析错。

node -v
# v22.x.x 以上 OK

版本不够就装个新 LTS：macOS / Linux 用 nvm，Windows 用 nvm-windows。

第二是 ofox.ai 的 API Key。去 ofox.ai 注册账号，控制台 → API Keys → Create new key，复制后先别关页面——Key 只显示一次，关掉就找不回来。

macOS 安装：三种方式选一种

方式 A：Homebrew（推荐）

brew install --cask codex

Cask 安装的好处是 brew 会接管后续更新（brew upgrade --cask codex），不用自己惦记版本。装完之后 codex --version 应该能输出 0.130.x 或更新（截至 2026-05-08 最新是 0.130.0）。

方式 B：npm 全局安装

npm install -g @openai/codex

这是 OpenAI 自己最先支持的方式，版本同步最快。

方式 C：桌面 App

进 developers.openai.com/codex 下载 .dmg。这一步需要梯子，不推荐当主路径，CLI 装好之后桌面 App 用得也不多。

Windows 安装

Windows 实际只有两条路：npm 或 Microsoft Store 桌面 App。

npm 安装（推荐 CLI 用户）

PowerShell 里：

npm install -g @openai/codex

装完后 codex 应该立刻能用。没找到命令？ 大概率是 npm 全局目录没在 PATH。运行：

npm prefix -g

把输出（通常是 C:\Users\<你>\AppData\Roaming\npm）加到系统 PATH，重开 PowerShell。

Microsoft Store 桌面 App

商店里搜 “Codex by OpenAI”，一键装。这个方式不需要 Node，但桌面 App 登录流程仍然走 chatgpt.com，国内不稳定，别选它当主路径。

Windows 用户的路径建议

把要让 Codex 改的项目放在 C:\Users\<你>\Code\ 之类的用户目录下。Codex 的沙箱在写 Program Files 或盘根目录时容易触发权限拒绝，省事的办法就是不去碰那些目录。

Linux 安装

主流发行版都用 npm 装就行：

npm install -g @openai/codex

如果服务器上不想装 Node，可以从 GitHub Releases 下对应架构的归档包。注意官方发布的 Linux 产物是 musl 静态链接的 tar.gz 压缩包，不是裸二进制——文件名形如 codex-x86_64-unknown-linux-musl.tar.gz（ARM 服务器换成 codex-aarch64-unknown-linux-musl.tar.gz），需要先解压再赋执行权限：

mkdir -p ~/.local/bin
curl -L -o /tmp/codex.tar.gz \
  https://github.com/openai/codex/releases/latest/download/codex-x86_64-unknown-linux-musl.tar.gz
tar -xzf /tmp/codex.tar.gz -C ~/.local/bin/
chmod +x ~/.local/bin/codex
rm /tmp/codex.tar.gz

解压后看一眼 ~/.local/bin/，如果实际文件名不是 codex（不同版本归档里偶尔带后缀），自己 mv 重命名一下即可。GitHub Releases 下载会走 githubusercontent.com，国内速度看运气，命令卡住的话回头用 npm 安装更稳。

把 Codex CLI 接到 ofox.ai

装好的 Codex 默认连 api.openai.com，国内会立刻报超时。配置入口在 ~/.codex/config.toml（Windows 是 %USERPROFILE%\.codex\config.toml）。这个文件不存在就手动创建。

最小可用配置

# 默认模型（OpenAI Codex 编程专用）
model = "openai/gpt-5.3-codex"

# 默认 Provider
model_provider = "ofoxai"

# Provider 定义
[model_providers.ofoxai]
name = "OfoxAI"
base_url = "https://api.ofox.ai/v1"
env_key = "OFOXAI_API_KEY"
wire_api = "responses"

wire_api = "responses" 这一行务必写上。2026-02 起 Codex CLI 已经把 wire_api = "chat" 标记为弃用并从主分支移除，写 chat 在 0.130.0 上会直接打印 Support for the "chat" wire API is deprecated and will soon be removed 然后拒绝发请求。ofox.ai 已经原生提供 /v1/responses 端点，直接走 Responses API 即可，prompt cache 命中率也比 Chat Completions 路径高。

设置环境变量

env_key = "OFOXAI_API_KEY" 告诉 CLI 去哪个环境变量里读 key。把 ofox 控制台拿到的那串塞进去：

macOS / Linux（~/.zshrc 或 ~/.bashrc）：

export OFOXAI_API_KEY="sk-ofox-xxxxxxxxxxxx"

source ~/.zshrc 让它立刻生效。

Windows（PowerShell，永久生效）：

[Environment]::SetEnvironmentVariable("OFOXAI_API_KEY", "sk-ofox-xxxxxxxxxxxx", "User")

设完重开 PowerShell。

第一次跑通

新建一个空目录，进去：

mkdir codex-test && cd codex-test
codex

正常情况下 Codex 会进入交互模式，提示你输入任务。试一句最简单的：

写一个 Python 的 fibonacci(n) 函数，要求带类型注解和单测

回车之后能看到模型在拉取上下文、写文件、再跑测试，整个过程在 terminal 里滚动。能拉起一次完整流程，证明网络和模型都通了。

三个最常见的报错

照上面配下来还出问题，基本是这三个里的一个。

Error: 401 Unauthorized

  • 99% 是环境变量没加载。新开的 terminal 跑 echo $OFOXAI_API_KEY（Windows 跑 echo $env:OFOXAI_API_KEY），输出空就 source 一下配置文件
  • Key 拼错也会 401，去 ofox 控制台对一遍

Error: 404 - Endpoint not found 或 invalid endpoint

  • 多半是 base_url 写错或者末尾多了 /。ofox.ai 的正确写法是 https://api.ofox.ai/v1，不要写成 https://api.ofox.ai/v1/ 也不要漏掉 /v1
  • 也有可能是把 wire_api 配成了已经被弃用的 "chat"，新版 Codex CLI 会直接拒绝；改成 "responses" 即可

Error: model not found 或 invalid_model

  • 模型 ID 大小写错了或者带了非法字符。ofox 上的 Codex 模型当前是 openai/gpt-5.3-codex，注意是小写 + 短横线 + 点（5.3 中间是点）
  • 也可能是该模型没在你账户的可用列表里。去 ofox 控制台 → Models 翻一遍，没看到就先用 openai/gpt-5.4-mini 顶一下

详细的报错代码对照可以翻 AI API 报错大全。如果想再深一层定制 Codex 的沙箱权限和推理强度，往下接 Codex CLI 进阶配置：自定义 API 与 config.toml 完全指南。

选 Codex 还是选 Claude Code

装到这一步很多人会犹豫：既然都过 ofox，要不要也装一个 Claude Code 比一比。我的实际感受是这样：Codex CLI 跟 OpenAI 系模型配合最顺，GPT-5.3 Codex 是它默认调过的，沙箱粒度也细；Claude Code 长上下文表现更稳，写文档和大段重构更舒服。Cursor、Windsurf 那些是 IDE 路线，不是 terminal 路线，本来就不该和 CLI 放一起选。

具体哪个适合你，看横评 Claude Code vs Codex vs Cursor。如果只是想用 GPT-5.4 系列做接口调用，不打算做终端编程，GPT-5.4 API 国内调用指南 更直接。觉得 Codex 太重的，ChatGPT 国内平替 里有几个轻量方案。

每天用之前的 90 秒检查清单

第一次跑通之后，建议把下面这套写进自己的笔记，新设备复用：

  1. node -v ≥ 22（22.22.0 起官方实测可跑）
  2. codex --version 拿到版本号（截至 2026-05-09 最新 0.130.0）
  3. cat ~/.codex/config.toml 看到 wire_api = "responses" 这一行
  4. echo $OFOXAI_API_KEY 不为空
  5. cd 到任意空目录，codex 能进入交互模式

任何一步对不上，回头看本文对应章节，比硬调好太多。

相关文章

GLM-5 API 接入完全指南：国产编程 SOTA 模型上手实战（GLM-5 / GLM-5.1 / GLM-5-Turbo）

GLM-5V-Turbo 多模态视觉 API 接入指南：截图生成代码的正确打开方式（2026）

Flux 2 Max 图像生成 API 国内完整教程：通过 ofox 一键接入（2026）

← 返回文章列表