Codex 配置教程

Codex 安装与配置教程

Windows 版本教程

系统要求

Windows 10 或 Windows 11

建议 Node.js 22+

建议 npm 10+

可正常访问外网

终端建议使用 PowerShell 或 Windows Terminal

安装步骤

前置步骤：

安装 Node.js

安装 Codex CLI

验证是否安装成功

1. 安装 Node.js

访问 Node.js 官网，下载并安装当前 LTS 版本。

安装完成后，在 PowerShell 中执行：

node -v
npm -v

如果都能正常输出版本号，就可以继续。

2. 安装 Codex

打开 PowerShell，执行：

npm install -g @openai/codex

3. 验证安装

codex --version

能看到版本号就说明安装成功。

配置 API

1. 创建配置文件

Codex 在 Windows 下的配置文件通常位于：

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

如果目录不存在，可以执行：

New-Item -ItemType Directory -Force $env:USERPROFILE\.codex
New-Item -ItemType File -Force $env:USERPROFILE\.codex\config.toml
notepad $env:USERPROFILE\.codex\config.toml

2. 写入星狐云配置

把下面内容全部复制写入 config.toml：

model_provider = "xinghu"
model = "gpt-5-codex"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.xinghu]
name = "xinghu"
base_url = "https://xinghuapi.com/v1"
wire_api = "responses"

字段说明：

base_url 填星狐云的 OpenAI 兼容接口地址

wire_api = "responses" 是 Codex 当前官方支持的协议写法

model 请替换成你在星狐云后台实际可用的模型名

[windows].sandbox = "elevated" 是 Windows 场景下常见的配置项

3. 配置 API Key

打开同目录下的auth.json文件

只需要修改下面这个apikey即可

{"OPENAI_API_KEY": "sk-xxx"}

启动 Codex

推荐使用 profile 启动：

codex --profile xinghu

如果你把星狐云写成默认 provider，也可以直接运行：

codex

首次进入后，可以让 Codex 回答一句简单的话测试：

请用一句话说明你当前使用的 provider 和模型。

VSCode 插件 Codex

如果你想在 VSCode 中使用 Codex，建议按下面方式操作：

打开 VSCode 扩展市场

搜索并安装官方 Codex 扩展

重启 VSCode

在 VSCode 中登录或复用本机 Codex 配置

Windows 平台要注意：

Codex CLI 在 Windows 原生终端中可以直接运行

但官方文档对 IDE 场景更推荐 WSL

如果你在 Windows 下遇到 VSCode 插件无法稳定调用终端、权限异常、路径映射问题，建议把项目放进 WSL 后再使用

Mac 版本教程

系统要求

macOS

推荐安装 Homebrew

如果使用 npm 安装，则建议 Node.js 22+

可正常访问外网

终端使用 Terminal 或 iTerm2

安装步骤

前置步骤：

安装 Homebrew 或 Node.js

安装 Codex CLI

验证安装结果

1. 安装 Homebrew

如果你还没有 Homebrew，可以先执行：

如果你已经有 Node.js，也可以跳过这一步，直接用 npm 安装 Codex。

2. 安装 Codex

推荐方式一，使用 Homebrew：

备选方式二，使用 npm：

3. 验证安装

配置 API

1. 创建配置文件

macOS 下配置文件路径通常为：

~/.codex/config.toml

创建目录并打开配置文件：

2. 写入星狐云配置

把下面内容写入：

[model_providers.xinghuapi]
name = "xinghuapi"
base_url = "https://xinghuapi.com/v1"
env_key = "XINGHU_API_KEY"
wire_api = "responses"
request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 300000

[profiles.xinghu]
model_provider = "xinghuapi"
model = "gpt-5.4"
model_reasoning_effort = "high"

3. 配置 API Key

当前终端临时生效：

如果你使用 zsh，永久写入：

如果你使用 bash，永久写入：

验证变量：

启动 Codex

如果配置成默认 provider，则直接运行：

VSCode 插件 Codex

macOS 上的使用步骤和 Windows 类似，但终端与权限问题通常更少：

打开 VSCode

在扩展市场搜索官方 Codex

安装后重启 VSCode

在项目根目录打开 Codex 面板使用

如果你的 VSCode 与终端使用的是同一用户环境，通常也能直接读取 ~/.codex/config.toml 和 XINGHU_API_KEY。

Linux 版本教程

系统要求

主流 Linux 发行版

建议 Node.js 22+

建议 npm 10+

可正常访问外网

终端使用 bash、zsh 或其他常见 shell

建议：

Linux 上优先使用 nvm 安装 Node.js，版本管理更方便

如果你不想装 Node.js，也可以用 GitHub Release 二进制包

安装步骤

前置步骤：

安装 Node.js

安装 Codex CLI

验证安装结果

1. 安装 Node.js

如果你使用 nvm，可以执行：

然后确认版本：

2. 安装 Codex

使用 npm 安装：

如果你更偏向纯二进制方式，也可以从 OpenAI 的 Codex GitHub Release 页面下载 Linux 对应版本并加入 PATH。

3. 验证安装

配置 API

1. 创建配置文件

Linux 下配置文件路径：

~/.codex/config.toml

创建目录与文件：

2. 写入星狐云配置

[model_providers.xinghuapi]
name = "xinghuapi"
base_url = "https://xinghuapi.com/v1"
env_key = "XINGHU_API_KEY"
wire_api = "responses"
request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 300000

[profiles.xinghu]
model_provider = "xinghuapi"
model = "gpt-5.4"
model_reasoning_effort = "high"

3. 配置 API Key

当前终端临时生效：

如果你使用 bash，永久写入：

如果你使用 zsh，永久写入：

验证变量：

启动 Codex

如果你把星狐云配置成默认 provider：

VSCode 插件 Codex

Linux 下的 VSCode 使用方式通常最直接：

打开 VSCode

安装官方 Codex 扩展

在项目目录启动 VSCode

让扩展读取本机环境变量和 ~/.codex/config.toml

如果你是远程开发、容器开发或 SSH 开发，建议保证插件所在环境与 config.toml、环境变量处于同一运行环境中，否则可能会出现“终端里可用、插件里不可用”的情况。

常见问题

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

通常是以下原因：

npm 全局安装目录没有加入 PATH

新装完之后没有重开终端

你装的是二进制包，但没有把目录加入 PATH

可以先重新打开终端，再执行：

2. 提示 `401 Unauthorized`

优先检查这几项：

XINGHU_API_KEY 是否真的存在

API Key 是否复制完整

当前 shell 是否已经重新加载环境变量

星狐云后台的令牌是否失效

Windows 检查命令：

echo $env:XINGHU_API_KEY

macOS / Linux 检查命令：

3. 提示 `404`、`unsupported_parameter` 或请求失败

这类问题通常不是 Codex 本身坏了，而是接口兼容性问题。

要注意一点：

Codex 当前配置里的 wire_api 使用的是 responses

也就是说，你的中转服务需要兼容 POST /v1/responses

如果星狐云当前线路只兼容 Chat Completions，但不兼容 Responses API，Codex 就可能无法正常工作。

建议按顺序排查：

检查 base_url 是否为 https://xinghuapi.com/v1

检查模型名是否为你账号下真实可用的模型

联系星狐云客服确认是否支持 OpenAI Responses API

如果星狐云提供了专门的 Codex 节点地址，以后台说明为准

4. 模型名应该填什么

请以星狐云控制台里实际显示的模型名为准。

本文中的 gpt-5.4 只是示例，不代表所有账号都能直接使用这个模型。

5. VSCode 插件里可用，终端里不可用，或者反过来

大多数时候是环境不一致：

插件读取的是 VSCode 自己的环境

终端读取的是你的 shell 环境

远程开发、WSL、容器、SSH 都可能导致配置文件和环境变量不在同一个位置

排查思路很简单：

先确认 config.toml 放在哪个环境里

再确认 XINGHU_API_KEY 配在哪个环境里

最后确认 Codex 实际运行在哪个环境里

参考来源

OpenAI Codex 官方 README
https://github.com/openai/codex

OpenAI Codex 官方文档：Authentication
https://developers.openai.com/codex/auth

OpenAI Codex 官方文档：Config Basics
https://developers.openai.com/codex/config-basic

OpenAI Codex 官方文档：Configuration Reference
https://developers.openai.com/codex/config-reference

OpenAI Codex 官方文档：Windows
https://developers.openai.com/codex/windows

OpenAI Codex 官方文档：IDE
https://developers.openai.com/codex/ide

Codex配置星狐云API教程

Codex 配置教程#

Codex 安装与配置教程#

Windows 版本教程#

系统要求#

安装步骤#

1. 安装 Node.js#

2. 安装 Codex#

3. 验证安装#

配置 API#

1. 创建配置文件#

2. 写入星狐云配置#

3. 配置 API Key#

启动 Codex#

VSCode 插件 Codex#

Mac 版本教程#

系统要求#

安装步骤#

1. 安装 Homebrew#

2. 安装 Codex#

3. 验证安装#

配置 API#

1. 创建配置文件#

2. 写入星狐云配置#

3. 配置 API Key#

启动 Codex#

VSCode 插件 Codex#

Linux 版本教程#

系统要求#

安装步骤#

1. 安装 Node.js#

2. 安装 Codex#

3. 验证安装#

配置 API#

1. 创建配置文件#

2. 写入星狐云配置#

3. 配置 API Key#

启动 Codex#

VSCode 插件 Codex#

常见问题#

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

2. 提示 401 Unauthorized#

3. 提示 404、unsupported_parameter 或请求失败#

4. 模型名应该填什么#

5. VSCode 插件里可用，终端里不可用，或者反过来#

推荐的统一配置模板#

参考来源#

Codex 配置教程

Codex 安装与配置教程

Windows 版本教程

系统要求

安装步骤

1. 安装 Node.js

2. 安装 Codex

3. 验证安装

配置 API

1. 创建配置文件

2. 写入星狐云配置

3. 配置 API Key

启动 Codex

VSCode 插件 Codex

Mac 版本教程

系统要求

安装步骤

1. 安装 Homebrew

2. 安装 Codex

3. 验证安装

配置 API

1. 创建配置文件

2. 写入星狐云配置

3. 配置 API Key

启动 Codex

VSCode 插件 Codex

Linux 版本教程

系统要求

安装步骤

1. 安装 Node.js

2. 安装 Codex

3. 验证安装

配置 API

1. 创建配置文件

2. 写入星狐云配置

3. 配置 API Key

启动 Codex

VSCode 插件 Codex

常见问题

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

2. 提示 `401 Unauthorized`

3. 提示 `404`、`unsupported_parameter` 或请求失败

4. 模型名应该填什么

5. VSCode 插件里可用，终端里不可用，或者反过来

推荐的统一配置模板

参考来源