Codex 使用教程

本教程将帮助您在不同平台上配置和使用 Codex。

Windows 平台

（一）安装 Node.js 环境

Windows 安装方法

方法一：官网下载（推荐）

打开浏览器访问 https://nodejs.org/
点击 "LTS" 版本进行下载（版本号要大于18，推荐长期支持版本）
下载完成后双击 .msi 文件
按照安装向导完成安装，保持默认设置即可

方法二：使用包管理器

如果你安装了 Chocolatey 或 Scoop，可以使用命令行安装：

# 使用 Chocolatey
choco install nodejs

# 或使用 Scoop
scoop install nodejs

Windows 注意事项

建议使用 PowerShell 而不是 CMD
如果遇到权限问题，尝试以管理员身份运行
某些杀毒软件可能会误报，需要添加白名单

验证安装是否成功

安装完成后，打开 PowerShell 或 CMD，输入以下命令：

node --version
npm --version

如果显示版本号，说明安装成功了！

（二）安装 Codex Cli

安装 Codex Cli

打开 PowerShell 或 CMD，运行以下命令：

# 全局安装 Codex
npm i -g @openai/codex --registry=https://registry.npmmirror.com

这个命令会从 npm 官方仓库下载并安装最新版本的 Codex。更新也使用这个命令

验证

codex --version

提示：

建议使用 PowerShell 而不是 CMD，功能更强大
如果遇到权限问题，以管理员身份运行 PowerShell

配置 Codex 环境变量

方法一

使用编辑配置文件方式配置 Codex 环境变量

打开文件资源管理器，找到 C:\Users\你的用户名\.codex 文件夹（如果没有则创建），创建 config.toml 文件，用 Notepad 打开，输入以下内容：

model_provider = "codeyy"

model = "gpt-5-codex"

model_reasoning_effort = "high"

disable_response_storage = true

sandbox_mode = "workspace-write" 

windows_wsl_setup_acknowledged = true

[features]
plan_tool = true
apply_patch_freeform = true
view_image_tool = true
web_search_request = true
unified_exec = false #会造成Windows不停弹窗，不要开
streamable_shell = false
rmcp_client = true

# approve_all = true  # 谨慎开，但想偷懒的开，但也要承担被删库的风险

[tools]
web_search = true
view_image = true

[model_providers.codeyy]
name = "codeyy"
base_url = "https://codeyy.top/v1"
wire_api = "responses"
env_key = "key_codeyy"
requires_openai_auth = true

[sandbox_workspace_write]
network_access = true

# [mcp_servers.context7]
# command = "cmd"
# args = [
#     "/c",
#     "bunx",
#     "-y",
#     "@upstash/context7-mcp",
#     "--api-key",
#     "ctx7sk-xxx",
# ]
# env = { SystemRoot="C:\\Windows" }
# startup_timeout_ms = 20_000

# [mcp_servers.fetch]
# command = "cmd"
# args = [
#     "/c",
#     "uvx",
#     "mcp-server-fetch"
# ]
# env = { SystemRoot="C:\\Windows" }
# startup_timeout_ms = 20_000

# [mcp_servers.sequential-thinking-offical]
# command = "cmd"
# args = [
#     "/c",
#     "npx",
#     "-y",
#     "@modelcontextprotocol/server-sequential-thinking"
# ]
# env = { SystemRoot="C:\\Windows" }
# startup_timeout_ms = 20_000

# [mcp_servers.hyperbrowser]
# command = "cmd"
# args = [
#     "/c",
#     "npx",
#     "-y",
#     "hyperbrowser-mcp"
# ]
# env = { SystemRoot="C:\\Windows",HYPERBROWSER_API_KEY="Yhb_xxx" }
# startup_timeout_ms = 20_000

# [mcp_servers.memory]
# command = "cmd"
# args = [
#     "/c",
#     "npx",
#     "-y",
#     "@modelcontextprotocol/server-memory"
# ]
# env = { SystemRoot="C:\\Windows" }
# startup_timeout_ms = 20_000

# [mcp_servers.ast-grep]
# command = "cmd"
# args = [
#     "/c",
#     "uvx",
#     "--from",
# 	"git+https://github.com/ast-grep/ast-grep-mcp",
# 	"ast-grep-server"
# ]
# env = { SystemRoot="C:\\Windows" }
# startup_timeout_ms = 20_000

# [mcp_servers.everything-search]
# command = "cmd"
# args = [
#     "/c",
#     "uvx",
#     "mcp-server-everything-search",
# ]
# env = { SystemRoot="C:\\Windows",EVERYTHING_SDK_PATH="D:\\xxxx\\Everything-SDK\\dll\\Everything64.dll" }
# startup_timeout_ms = 20_000

# [mcp_servers.tavily-mcp]
# command = "cmd"
# args = [
#     "/c",
#     "npx",
#     "-y",
#     "tavily-mcp@0.2.4",
# ]
# env = { SystemRoot="C:\\Windows",TAVILY_API_KEY="ctx7sk-xxxx" }
# startup_timeout_ms = 20_000

# [mcp_servers.github]
# command = "cmd"
# args = [
#     "/c",
#     "npx",
#     "-y",
#     "@modelcontextprotocol/server-github",
# ]
# env = { SystemRoot="C:\\Windows",GITHUB_PERSONAL_ACCESS_TOKEN="github_pat_xxx" }
# startup_timeout_ms = 20_000

# [mcp_servers.mcpr]
# command = "D:\\FNM_DIR\\aliases\\default\\mcpr-cli.cmd"
# args = [
#     "connect"
# ]
# env = { SystemRoot="C:\\Windows",MCPR_TOKEN="mcpr_xxx" }
# startup_timeout_ms = 200000

上面的 mcp 被我注释了，有需要的自己去掉注释加上自己的 apikey 就可以使用，有使用 mcp router 的可以使用最后一个被注释的 mcp 即可

创建 auth.json 文件，在文件添加以下内容：

{
  "OPENAI_API_KEY": "你的API密钥"
}

把 "你的API密钥" 替换为你的 codeyy.top 的 key 即可

设置环境变量

[System.Environment]::SetEnvironmentVariable("key_codeyy", "你的API密钥", [System.EnvironmentVariableTarget]::User)

方法二

如果你使用支持 OpenAI API 的工具（如 Codex），需要设置以下环境变量：

PowerShell 设置方法

在 PowerShell 中运行以下命令：

$env:OPENAI_BASE_URL = "https://codeyy.top/v1"
$env:OPENAI_API_KEY = "你的API密钥"

使用你的 codeyy.top API 密钥，使用与 Claude Code 相同的 API 密钥即可。

PowerShell 永久设置（用户级）

在 PowerShell 中运行以下命令：

# 设置用户级环境变量（永久生效）
[System.Environment]::SetEnvironmentVariable("OPENAI_BASE_URL", "https://codeyy.top/v1", [System.EnvironmentVariableTarget]::User)
[System.Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "你的API密钥", [System.EnvironmentVariableTarget]::User)

设置后需要重新打开 PowerShell 窗口才能生效。

验证 Codex 环境变量

在 PowerShell 中验证：

echo $env:OPENAI_BASE_URL
echo $env:OPENAI_API_KEY

（三）开始使用 Codex

启动 Codex

配置完成后，在 PowerShell 或 CMD 中输入以下命令启动 Codex：

codex

首次启动时，Codex 会进行初始化配置。

基本使用

交互模式：直接输入 codex 进入交互式对话
指定项目：在项目目录下运行 codex，Codex 会自动识别项目上下文
退出程序：输入 exit 或按 Ctrl+C 退出

（四）常见问题解决

1. 命令未找到错误

问题：运行 codex 时提示 "不是内部或外部命令"

解决方法：

# 检查 npm 全局安装路径
npm config get prefix

# 确保该路径在 PATH 中
$env:Path

# 如果不在，添加到系统环境变量
# 打开系统环境变量设置，将 npm 全局路径添加到 Path 中
# 默认路径通常是：C:\Users\你的用户名\AppData\Roaming\npm

2. 权限问题

问题：安装时提示权限不足

解决方法：

# 以管理员身份运行 PowerShell
# 右键点击 PowerShell 图标，选择"以管理员身份运行"
# 然后重新安装
npm install -g @openai/codex

3. API 连接失败

问题：Codex 无法连接到 API 服务

解决方法：

# 检查环境变量是否正确设置
echo $env:OPENAI_BASE_URL
echo $env:OPENAI_API_KEY

# 测试网络连接
Test-NetConnection -ComputerName codeyy.top -Port 443

# 重新设置环境变量
$env:OPENAI_BASE_URL = "https://codeyy.top/v1"
$env:OPENAI_API_KEY = "你的API密钥"

4. 更新 Codex

问题：如何更新到最新版本

解决方法：

# 更新 Codex（推荐使用国内镜像）
npm i -g @openai/codex --registry=https://registry.npmmirror.com

# 或者重新安装
npm install -g @openai/codex

5. Node.js 版本过低

问题：提示 Node.js 版本不兼容

解决方法：

# 检查当前版本
node --version

# 从官网下载最新的 LTS 版本（需要 18 或更高版本）
# 访问 https://nodejs.org/ 下载安装

6. 防火墙或杀毒软件拦截

问题：安装或运行时被防火墙拦截

解决方法：

将 Node.js 和 npm 添加到防火墙白名单
临时关闭杀毒软件进行安装
检查企业网络策略是否允许访问 npm 仓库

Linux 平台

（一）安装 Node.js 环境

Codex 需要 Node.js 环境才能运行。

Linux 安装方法

方法一：使用官方仓库（推荐）

# 添加 NodeSource 仓库
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -

# 安装 Node.js
sudo apt-get install -y nodejs

方法二：使用系统包管理器

虽然版本可能不是最新的，但对于基本使用已经足够：

# Ubuntu/Debian
sudo apt update
sudo apt install nodejs npm

# CentOS/RHEL/Fedora
sudo dnf install nodejs npm

Linux 注意事项

某些发行版可能需要安装额外的依赖
如果遇到权限问题，使用 sudo
确保你的用户在 npm 的全局目录有写权限

验证安装是否成功

安装完成后，打开终端，输入以下命令：

node --version
npm --version

如果显示版本号，说明安装成功了！

（二）安装 Codex

安装 Codex

打开终端，运行以下命令：

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

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

sudo npm install -g @openai/codex

验证 Codex 安装

安装完成后，输入以下命令检查是否安装成功：

codex --version

如果显示版本号，恭喜你！Codex 已经成功安装了。

（三）设置环境变量

配置 Codex 环境变量

为了让 Codex 连接到你的中转服务，需要设置两个环境变量：

方法一：临时设置（当前会话）

在终端中运行以下命令：

export OPENAI_BASE_URL="https://codeyy.top/v1"
export OPENAI_API_KEY="你的API密钥"

注意：记得将 "你的API密钥" 替换为在控制台的 API 管理页面中创建的实际密钥。

方法二：永久设置

编辑你的 shell 配置文件：

对于 bash (默认)：

echo 'export OPENAI_BASE_URL="https://codeyy.top/v1"' >> ~/.bashrc
echo 'export OPENAI_API_KEY="你的API密钥"' >> ~/.bashrc
source ~/.bashrc

对于 zsh：

echo 'export OPENAI_BASE_URL="https://codeyy.top/v1"' >> ~/.zshrc
echo 'export OPENAI_API_KEY="你的API密钥"' >> ~/.zshrc
source ~/.zshrc

（四）开始使用 Codex

现在你可以开始使用 Codex 了！

启动 Codex：

codex

在特定项目中使用：

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

# 启动 Codex
codex

（五）Linux 常见问题解决

安装时提示权限错误

尝试以下解决方法：

# 使用 sudo 安装
sudo npm install -g @openai/codex

# 或者配置 npm 使用用户目录
npm config set prefix ~/.npm-global

# 然后添加到 PATH
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

缺少依赖库

# Ubuntu/Debian
sudo apt install build-essential

# CentOS/RHEL
sudo dnf groupinstall "Development Tools"

环境变量不生效

检查以下几点：

确认修改了正确的配置文件（.bashrc 或 .zshrc）
重新启动终端或运行 source ~/.bashrc
验证设置：echo $OPENAI_BASE_URL

🎉 恭喜你！

你已经成功安装并配置了 Codex，现在可以开始享受 AI 编程助手带来的便利了。

如果在使用过程中遇到任何问题，可以查看官方文档或社区讨论获取帮助。

Mac 平台

（一）安装 Node.js 环境

Codex 需要 Node.js 环境才能运行。

macOS 安装方法

方法一：使用 Homebrew（推荐）

如果你已经安装了 Homebrew，使用它安装 Node.js 会更方便：

# 更新 Homebrew
brew update

# 安装 Node.js
brew install node

方法二：官网下载

访问 https://nodejs.org/
下载适合 macOS 的 LTS 版本
打开下载的 .pkg 文件
按照安装程序指引完成安装

macOS 注意事项

如果遇到权限问题，可能需要使用 sudo
首次运行可能需要在系统偏好设置中允许
建议使用 Terminal 或 iTerm2

验证安装是否成功

安装完成后，打开 Terminal，输入以下命令：

node --version
npm --version

如果显示版本号，说明安装成功了！

（二）安装 Codex

安装 Codex

打开 Terminal，运行以下命令：

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

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

sudo npm install -g @openai/codex

验证 Codex 安装

安装完成后，输入以下命令检查是否安装成功：

codex --version

如果显示版本号，恭喜你！Codex 已经成功安装了。

（三）设置环境变量

配置 Codex 环境变量

为了让 Codex 连接到你的中转服务，需要设置两个环境变量：

方法一：临时设置（当前会话）

在 Terminal 中运行以下命令：

export OPENAI_BASE_URL="https://codeyy.top/v1"
export OPENAI_API_KEY="你的API密钥"

注意：记得将 "你的API密钥" 替换为在控制台的 API 管理页面中创建的实际密钥。

方法二：永久设置

编辑你的 shell 配置文件（根据你使用的 shell）：

对于 zsh (默认)：

echo 'export OPENAI_BASE_URL="https://codeyy.top/v1"' >> ~/.zshrc
echo 'export OPENAI_API_KEY="你的API密钥"' >> ~/.zshrc
source ~/.zshrc

对于 bash：

echo 'export OPENAI_BASE_URL="https://codeyy.top/v1"' >> ~/.bash_profile
echo 'export OPENAI_API_KEY="你的API密钥"' >> ~/.bash_profile
source ~/.bash_profile

（四）开始使用 Codex

现在你可以开始使用 Codex 了！

启动 Codex：

codex

在特定项目中使用：

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

# 启动 Codex
codex

（五）macOS 常见问题解决

安装时提示权限错误

尝试以下解决方法：

# 使用 sudo 安装
sudo npm install -g @openai/codex

# 或者配置 npm 使用用户目录
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

macOS 安全设置阻止运行

如果系统阻止运行 Codex：

打开"系统偏好设置" → "安全性与隐私"
点击"仍要打开"或"允许"
或者在 Terminal 中运行：sudo spctl --master-disable

环境变量不生效

检查以下几点：

确认修改了正确的配置文件（.zshrc 或 .bash_profile）
重新启动 Terminal
验证设置：echo $OPENAI_BASE_URL

🎉 恭喜你！

你已经成功安装并配置了 Codex，现在可以开始享受 AI 编程助手带来的便利了。

如果在使用过程中遇到任何问题，可以查看官方文档或社区讨论获取帮助。

VSCode 插件

（一）VSCode 安装（版本 >= 1.75.2）

访问 VSCode 官网下载所需版本

（二）安装 Codex 扩展

在扩展中安装 Codex – OpenAI's coding agent

打开 VSCode 扩展市场（Ctrl+Shift+X 或 Cmd+Shift+X）
搜索 "Codex" 并点击安装
安装完成后，需要配置 API 密钥和服务器地址

（三）配置文件设置

到 .codex 文件夹下的 auth.json 和 config.toml 文件中添加以下内容（如果没有这两个文件，请自行创建）：

Windows 下路径为：C:/Users/你的用户名/.codex

Linux 或 macOS 系统中通常位于：~/.codex

auth.json

{
  "OPENAI_API_KEY": "你的API密钥"
}

config.toml

model_provider = "codeyy"

model = "gpt-5-codex"

model_reasoning_effort = "high"

disable_response_storage = true

[model_providers.codeyy]
name = "codeyy"
base_url = "https://codeyy.top/v1"
wire_api = "responses"
env_key = "key_codeyy"
requires_openai_auth = true

注意：env_key 只能是环境变量中的名称，不能放完整的令牌（密钥），令牌要放到环境变量中。

如果你放了完整的令牌（密钥）使用时会报错找不到令牌或者令牌配置错误（见常见问题）。

requires_openai_auth = true，可以让你在插件中切换模型。

（四）设置环境变量

在你的环境变量中设置 key_codeyy="你的API密钥"：

Linux/Mac：

export key_codeyy='你的API密钥'

Windows：

$env:key_codeyy = "你的API密钥"

永久设置方法参考指南中 Windows、Linux、Mac 的设置方法。

Jetbrains IDE 插件

在 Jetbrains IDE（IntelliJ IDEA、PyCharm、WebStorm 等）中使用 Codex：

打开 IDE，进入 File → Settings → Plugins
搜索 "Codex" 插件并安装
重启 IDE，在插件设置中配置 API 密钥
在代码编辑时使用 Tab 键或快捷键触发 Codex 补全

API 使用示例

使用 REST API 调用 Codex：

curl -X POST https://codeyy.top/v1/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "codex",
    "prompt": "def fibonacci(n):",
    "max_tokens": 100,
    "temperature": 0.7
  }'

Python 示例

import requests

url = "https://codeyy.top/v1/completions"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}
data = {
    "model": "codex",
    "prompt": "def fibonacci(n):",
    "max_tokens": 100,
    "temperature": 0.7
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

常见问题

Codex 支持哪些编程语言？

Codex 支持多种主流编程语言，包括 Python、JavaScript、Java、C++、Go、Rust 等。

如何提高代码生成质量？

建议提供清晰的注释和上下文，使用合适的温度参数（temperature），并根据实际情况调整 max_tokens 参数。

API 调用失败怎么办？

请检查 API 密钥是否正确、网络连接是否正常、余额是否充足。如果问题持续，请联系技术支持。