Codex 跨平台本地部署完整指南

要在 Windows、macOS 和 Linux 系统上完成 Codex 的本地部署，需要遵循一套标准化的环境配置流程。以下是三大平台的详细部署步骤对比与操作指南。

一、系统环境要求对比

操作系统	最低版本要求	核心依赖	推荐工具
Windows	Windows 10/11	Node.js 22+、npm 10+、Git Bash	PowerShell/CMD、VSCode
macOS	macOS 12+	Node.js 22+、npm 10+	Terminal、Homebrew
Linux	Ubuntu 20.04+/Debian 10+/CentOS 7+	Node.js 22+、npm 10+	Terminal、包管理器

二、核心部署流程（三平台通用）

1. Node.js 环境安装

所有平台都需要首先安装 Node.js 22 或更高版本，这是运行 Codex CLI 的基础。

Windows 安装示例：

# 1. 访问 Node.js 官网下载安装包
# 2. 运行安装程序，按默认选项安装
# 3. 验证安装
node --version
npm --version

macOS 安装（Homebrew 方式）：

# 安装 Homebrew（如果尚未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Node.js
brew install node

Linux（Ubuntu/Debian）安装：

# 更新包列表并安装 Node.js 
sudo apt update
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

2. Codex CLI 全局安装

在所有平台上使用 npm 进行全局安装：

# 全局安装 Codex CLI 工具 
npm install -g @openai/codex

# 验证安装是否成功
codex --version

注意：在 macOS 和 Linux 上，如果遇到权限问题，可能需要使用 sudo：

sudo npm install -g @openai/codex

3. API 密钥配置

这是最关键的一步，需要创建配置文件来设置 API 访问。

3.1 获取 API Token

访问 API 服务站点（如 api.kl-api.info）：

1. 登录控制台，进入 API 令牌页面
2. 点击"添加令牌"
3. 关键步骤：令牌分组必须选择 "codex专属" 或 "codex特供"（不同平台可能名称略有差异）
4. 令牌名称可自定义
5. 额度建议设置为"无限额度"
6. 其他选项保持默认

3.2 创建配置文件

需要创建两个核心配置文件：auth.json 和 config.toml。

配置文件路径：

• Windows: C:\Users\用户名\.codex\
• macOS/Linux: ~/.codex/

auth.json 配置：

{
  "OPENAI_API_KEY": "sk-您的实际API密钥"
}

config.toml 配置：

model_provider = "kl-api"
model = "gpt-5.4"  # 或使用 gpt-5.3-codex 
model_reasoning_effort = "high"  # 可选：high, medium, low
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.kl-api]
name = "kl-api"
base_url = "https://api.kl-api.info/v1"
wire_api = "responses"

3.3 各平台具体配置方法

Windows 配置步骤：

1. 打开文件资源管理器，开启"显示隐藏的项目"
2. 进入 C:\Users\您的用户名\.codex 目录
3. 如果没有该目录，手动创建 .codex 文件夹
4. 在文件夹内创建 auth.json 和 config.toml 文件
5. 将上述配置内容粘贴到对应文件中

macOS/Linux 配置步骤：

# 创建配置目录和文件 
mkdir -p ~/.codex
touch ~/.codex/auth.json
touch ~/.codex/config.toml

# 编辑 auth.json 文件
echo '{"OPENAI_API_KEY": "sk-您的实际API密钥"}' > ~/.codex/auth.json

# 编辑 config.toml 文件
cat > ~/.codex/config.toml << EOF
model_provider = "kl-api"
model = "gpt-5.4"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.kl-api]
name = "kl-api"
base_url = "https://api.kl-api.info/v1"
wire_api = "responses"
EOF

4. 启动与验证

4.1 重启终端

重要：配置完成后必须重启终端或命令提示符，使环境变量生效。

4.2 启动 Codex

# 进入您的项目目录
cd /path/to/your/project

# 启动 Codex CLI
codex

成功启动后，您将看到 Codex 的交互式终端界面。

4.3 基本功能验证

在 Codex 终端中尝试以下命令：

# 查看当前模型和配置状态
/status

# 测试简单的代码生成
请帮我写一个Python的Hello World程序

三、平台特定注意事项

Windows 平台

1. Git Bash 推荐：虽然可以使用 CMD 或 PowerShell，但 Git Bash 提供更好的 Unix-like 体验
2. 路径问题：Windows 路径使用反斜杠，但在配置文件中建议使用正斜杠或双反斜杠
3. 权限问题：如果遇到权限错误，尝试以管理员身份运行终端

macOS 平台

1. Homebrew 管理：推荐使用 Homebrew 管理 Node.js，便于后续更新
2. 权限设置：可能需要运行 sudo chown -R $(whoami) ~/.codex 确保对配置目录有写入权限
3. zsh/bash：根据使用的 shell 不同，可能需要将配置添加到对应的配置文件（如 .zshrc 或 .bash_profile）

Linux 平台

1. 发行版差异：不同 Linux 发行版的包管理器命令不同
2. CentOS/RHEL：可能需要启用 EPEL 仓库
3. Arch Linux：使用 pacman 安装：sudo pacman -S nodejs npm
4. 权限管理：避免使用 root 用户运行 Codex，建议创建专用用户

四、IDE 集成（可选但推荐）

VSCode 插件安装

1. 打开 VSCode
2. 进入扩展商店（Ctrl+Shift+X）
3. 搜索 "codex"
4. 安装官方 Codex 插件
5. 安装完成后，侧边栏会出现 Codex 图标

Cursor 编辑器集成

如果您使用 Cursor 编辑器：

1. 确保已安装 Codex CLI
2. Cursor 会自动检测 Codex 配置
3. 可以在 Cursor 中直接使用 Codex 功能

五、常见问题排查

1. 命令未识别

# 如果 codex 命令未找到，检查 npm 全局路径
npm list -g --depth=0
# 确保 @openai/codex 在列表中
# 如果没有，重新安装并检查 PATH 环境变量

2. API 连接失败

• 检查 auth.json 中的 API 密钥是否正确
• 验证网络连接，确保可以访问 API 端点
• 检查 config.toml 中的 base_url 配置

3. 配置不生效

• 确认配置文件在正确的目录（~/.codex/ 或 C:\Users\用户名\.codex\）
• 重启终端使配置生效
• 使用 codex --version 确认安装成功

4. 权限问题（Linux/macOS）

# 修复权限问题
sudo chmod 755 ~/.codex
sudo chmod 644 ~/.codex/*

六、进阶配置

MCP（Model Context Protocol）服务配置

Codex 支持 MCP 服务扩展，可以在 config.toml 中添加：

[mcp_servers]
# 示例：添加文件系统访问
fs = { command = "npx", args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"] }

模型切换

在 Codex 终端中使用 /model 命令可以切换模型和推理等级：

• 可用模型：gpt-5.4、gpt-5.3-codex 等
• 推理等级：high（高）、medium（中）、low（低）

项目上下文配置

在项目根目录创建 AGENTS.md 文件，Codex 会自动读取作为项目上下文：

# 生成 AGENTS.md 文件
/init

七、部署验证清单

完成部署后，请检查以下项目：

检查项	Windows	macOS	Linux	验证命令
Node.js 版本 ≥22	✅	✅	✅	node --version
npm 版本 ≥10	✅	✅	✅	npm --version
Codex CLI 安装	✅	✅	✅	codex --version
配置文件存在	✅	✅	✅	检查 ~/.codex/ 目录
API 密钥有效	✅	✅	✅	启动 codex 测试
网络连接正常	✅	✅	✅	访问 API 端点
IDE 集成（可选）	✅	✅	✅	VSCode 插件安装

通过以上步骤，您应该能在 Windows、macOS 和 Linux 系统上成功完成 Codex 的本地部署。如果在任何步骤遇到问题，建议参考官方文档或社区支持资源 。

---

参考来源

• [Codex 配置使用教程](https://blog.csdn.net/visual studio code/article/details/154265720)
• Codex 下载与登录全流程（Windows/macOS/Linux）
• OpenAI Codex 国内使用完全指南：Windows/macOS/Linux 三平台详细安装配置教程（现在最新的有gpt-5.3-codex和gpt-5.4）
• [Codex 配置使用教程](https://blog.csdn.net/visual studio code/article/details/154265720)
• Codex 配置使用教程
• GPT-5.5 Codex 国内使用教程：Windows / macOS / Linux 配置