Codex 与 Claude Code 全平台安装配置指南（Windows / macOS / Linux）

本文整合 Codex 与 Claude Code 两款主流 AI 编程助手的安装与配置流程，覆盖 Windows、macOS、Linux 三大系统，所有命令均经过验证，可直接复制使用。

目录

• 一、环境准备
• 二、Codex 安装与配置
• 三、Claude Code 安装与配置
• 四、常见问题排查

一、环境准备

两款工具均依赖 Node.js ≥ 18(Codex 推荐 22+)。先完成 Node.js 安装。

1.1 Windows

推荐两种方式任选其一:

方式 A:官方安装包

访问 https://nodejs.org/ 下载 LTS 版本,双击安装即可。

方式 B:使用 nvm-windows(便于多版本管理)

从 nvm-windows releases 下载 nvm-setup.exe,安装后:

nvm install 22
nvm use 22

另外建议安装 Git for Windows:https://git-scm.com/downloads,后续部分命令依赖 Git Bash。

1.2 macOS

# 安装 Xcode 命令行工具
xcode-select –install

# 安装 Homebrew(已安装可跳过)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Node.js
brew install node@22

1.3 Linux

Ubuntu / Debian:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash –
sudo apt-get install -y nodejs

Fedora / RHEL / CentOS:

curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo -E bash –
sudo dnf install -y nodejs

Arch Linux:

sudo pacman -S nodejs npm

1.4 验证安装

node –version # 应输出 v22.x.x 或 v18.x.x 以上
npm –version

二、Codex 安装与配置

Codex 是 OpenAI 推出的命令行 AI 编程助手,支持 CLI 与 VSCode 插件两种使用方式。

2.1 安装 Codex CLI

所有系统通用(Windows 用户在 PowerShell 或 CMD 中执行,Linux/macOS 可能需要 sudo):

npm install -g @openai/codex

验证:

codex –version

2.2 获取 API Token

复制生成的 sk-xxx 密钥备用。

2.3 配置文件

Codex 配置位于用户主目录下的 .codex/ 文件夹,需要两个文件:

Windows 路径

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

若文件夹不存在,可在 PowerShell 中执行:

New-Item –ItemType Directory –Force –Path "$env:USERPROFILE\\.codex"
New-Item –ItemType File –Force –Path "$env:USERPROFILE\\.codex\\auth.json"
New-Item –ItemType File –Force –Path "$env:USERPROFILE\\.codex\\config.toml"

macOS / Linux 路径

mkdir -p ~/.codex
touch ~/.codex/auth.json ~/.codex/config.toml

auth.json 内容

将 sk-xxx 替换为你的真实密钥:

{
"OPENAI_API_KEY": "sk-xxx"
}

config.toml 内容

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

[model_providers.api111]
name = "api111"
base_url = "https://xuedingmao.com/v1"
wire_api = "responses"

model_reasoning_effort 可选 high / medium / low,分别对应高/中/低推理强度。

2.4 启动 Codex

关闭并重新打开终端(让配置生效),然后:

cd your-project-folder
codex

2.5 VSCode 插件

在 VSCode 扩展商店搜索 codex 并安装。安装完成后会在左侧栏出现 Codex 图标,与 CLI 共用同一份 ~/.codex/ 配置,无需重复设置。

三、Claude Code 安装与配置

Claude Code 是 Anthropic 官方推出的终端 AI 编程助手。

3.1 安装

所有系统通用:

npm install -g @anthropic-ai/claude-code
claude –version

Windows 用户建议在 WSL2 中使用以获得最佳体验;原生 PowerShell / CMD 也可运行。

3.2 获取 API Token

同样在 xuedingmao.com 创建令牌:

• 分组:选择 Claude Code 专属 或 官转 Claude 3+ 分组
• 额度:无限额度
• 记录生成的 sk-xxx

3.3 配置环境变量

Claude Code 通过环境变量读取认证信息,有两种配置方式:临时(仅当前终端会话)和永久(写入配置文件)。

3.3.1 临时配置

Linux / macOS (bash/zsh):

export ANTHROPIC_BASE_URL=https://xuedingmao.com
export ANTHROPIC_AUTH_TOKEN=sk-xxx
export API_TIMEOUT_MS=300000
claude

Windows PowerShell:

$env:ANTHROPIC_BASE_URL = "https://xuedingmao.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-xxx"
$env:API_TIMEOUT_MS = "300000"
claude

Windows CMD:

set ANTHROPIC_BASE_URL=https://xuedingmao.com
set ANTHROPIC_AUTH_TOKEN=sk-xxx
set API_TIMEOUT_MS=300000
claude

3.3.2 永久配置(推荐)

macOS / Linux — 将以下内容追加到 ~/.zshrc 或 ~/.bashrc:

export ANTHROPIC_BASE_URL=https://xuedingmao.com
export ANTHROPIC_AUTH_TOKEN=sk-xxx
export API_TIMEOUT_MS=300000

然后执行 source ~/.zshrc(或重启终端)。

Windows PowerShell — 写入用户级环境变量:

[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://xuedingmao.com", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "sk-xxx", "User")
[Environment]::SetEnvironmentVariable("API_TIMEOUT_MS", "300000", "User")

设置后需关闭并重新打开终端窗口。

3.4 启动 Claude Code

cd your-project-folder
claude

首次启动会引导完成:

进入交互界面后,即可用自然语言描述需求开始协作编程。

四、常见问题排查

4.1 Codex 相关

Q1:启动 Codex 报 API 错误

依次检查:

Q2:配置文件改了但不生效

务必关闭并重新打开终端;部分编辑器保存时会生成 BOM 头,建议用 VSCode 保存为 “UTF-8(无 BOM)”。

4.2 Claude Code 相关

Q1:Invalid API Key · Please run /login

环境变量未被读取。检查:

• echo $ANTHROPIC_AUTH_TOKEN(Windows 用 echo %ANTHROPIC_AUTH_TOKEN%)是否能输出密钥
• 是否在设置环境变量的同一个终端窗口启动 claude
• 若使用永久配置,是否重启终端

Q2:状态栏显示 offline

Claude Code 通过 ping Google 判断网络。该提示不影响功能,可忽略。

Q3:fetch failed 或 API 超时

• 网络抖动导致,Ctrl+C 退出后重试
• 提高超时:export API_TIMEOUT_MS=600000
• 检查代理设置是否影响到 xuedingmao.com 的访问

Q4:WebFetch 抓取网页失败

Claude Code 抓取网页前会调用安全检查服务,需要稳定的国际网络。可配置代理后重试。

4.3 通用建议

• 保护好你的 API Key:不要提交到 Git 仓库,不要分享到截图/聊天中
• Node.js 版本:Codex 推荐 Node 22+,Claude Code 要求 Node 18+;版本过低会出现奇怪的安装/运行错误
• 更新工具:定期执行以下命令获取最新版本

npm update -g @openai/codex
npm update -g @anthropic-ai/claude-code

参考链接

• Node.js 官网:https://nodejs.org/
• Git 下载:https://git-scm.com/downloads
• Claude Code 官方文档:https://docs.anthropic.com/claude/docs/claude-code
• OpenAI Codex 仓库:https://github.com/openai/codex

如遇本文未覆盖的问题,优先查阅官方文档或在评论区交流。