AI精品店

Appearance

环境配置 ​

本页把 CodexZH 官方“上手指南”的配置步骤拆成可直接照做的版本：先三步最小可用，再按系统展开更细操作。

【推荐配置方式】

如果你更喜欢一键配置（自动写入 ~/.codex/config.toml 与 ~/.codex/auth.json），建议优先使用：CC-Switch 一键配置。

一、所有系统通用：三步最小可用配置 ​

1. 创建配置目录 ​

在用户主目录下创建 .codex 文件夹：

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

2. 创建 config.toml ​

在 .codex 目录中创建 config.toml，写入以下内容：

toml
model_provider = "codexzh"
model = "gpt-5.2"
model_reasoning_effort = "high"
disable_response_storage = true

[model_providers.codexzh]
name = "codexzh"
base_url = "https://api.codexzh.com/v1"
wire_api = "responses"
requires_openai_auth = true

web_search = "live"

3. 创建 auth.json ​

同目录创建 auth.json，把 OPENAI_API_KEY 替换为你控制台里 sk- 开头的真实密钥：

json
{
  "OPENAI_API_KEY": "sk-你的实际密钥"
}

完成后即可启动测试：

bash
codex

二、Windows：一键脚本与手动配置 ​

1. 一键配置脚本（省事） ​

CodexZH 控制台提供 Windows 一键配置脚本（.bat）。它会自动：

  • 检测运行环境
  • 安装 Codex 客户端
  • 创建 .codex 目录与配置文件

适合不想手动折腾的场景。脚本包含你的 API Key，请妥善保管。

2. 手动配置（建议至少看一遍） ​

2.1 环境检查 ​

CodexZH 上手指南的环境建议：

  • Windows 10 或更新版本
  • Node.js 22+
  • npm 10+
  • 稳定网络连接

验证命令：

bash
node --version
npm --version

2.2 安装 Codex CLI ​

在 PowerShell 或 CMD 执行：

bash
npm install -g @openai/codex
codex --version

2.3 写入配置文件 ​

打开配置目录的常用方式：

  • 按 Win + R，输入 %USERPROFILE%\.codex 并回车

如果目录不存在就新建，然后按“通用三步”创建并写入 config.toml 与 auth.json。

2.4 启动测试 ​

配置完成后建议重启命令行窗口，然后在任意项目目录运行：

bash
codex

三、macOS / Linux：一键脚本与手动配置 ​

1. 一键配置脚本（省事） ​

CodexZH 控制台提供 macOS / Linux 一键配置脚本。下载后在终端运行即可自动完成环境检测、安装客户端与写入配置文件。

同样注意：脚本包含你的 API Key，请妥善保管。

2. 手动配置（推荐使用 nvm） ​

2.1 安装 Node.js（使用 nvm） ​

如果你还没有 Node.js，CodexZH 上手指南推荐用 nvm（Node Version Manager）安装：

  1. 安装 nvm：
bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
  1. 让 nvm 生效（按你的 shell 选择其一）：
bash
source ~/.bashrc
# 或 source ~/.zshrc
  1. 安装并启用 Node.js 22：
bash
nvm install 22
nvm use 22
node --version

2.2 安装 Codex CLI ​

bash
npm install -g @openai/codex
codex --version

2.3 创建并写入配置文件（可复制） ​

打开配置目录的常用方式（可选）：

  • 在访达按 Command + Shift + G，输入 ~/.codex 并回车
bash
mkdir -p ~/.codex

cat > ~/.codex/config.toml <<'EOF'
model_provider = "codexzh"
model = "gpt-5.2"
model_reasoning_effort = "high"
disable_response_storage = true

[model_providers.codexzh]
name = "codexzh"
base_url = "https://api.codexzh.com/v1"
wire_api = "responses"
requires_openai_auth = true

web_search = "live"
EOF

cat > ~/.codex/auth.json <<'EOF'
{ "OPENAI_API_KEY": "sk-你的实际密钥" }
EOF

然后把 auth.json 里的密钥替换为真实值：

bash
nano ~/.codex/auth.json
# 或使用 vim ~/.codex/auth.json

2.4 启动测试 ​

bash
codex

四、关键字段解释（理解后排障更快） ​

  • model_provider：固定填 codexzh。
  • base_url：固定填 https://api.codexzh.com/v1。
  • wire_api：CodexZH 教程给出的值是 responses。
  • requires_openai_auth：建议保持为 true；遇到 VSCode / CLI 切换模型异常时，这个字段也常是排查点之一（见：问题解决）。
  • model：示例是 gpt-5.2（也可能有 gpt-5.2-codex 等可选模型，具体以官网模型页为准）。
  • model_reasoning_effort：示例是 high（一般还有 low/medium/high 等可选）。
  • disable_response_storage：示例为 true，用于关闭响应存储（更偏隐私取向）。
  • features.web_search_request：示例为 true，用于允许模型发起联网搜索请求（是否可用以客户端与权限为准）。