Codex 从零接入

这篇教程从打开终端开始，带你创建 ZCloudAPI Key、安装 Codex CLI、查询可用模型、写入 config.toml，最后在真实目录里运行第一条任务。按顺序完成即可。

1打开终端

2安装 Codex CLI

3创建 Key 并选模型

4写入 Provider

5运行并验收

更省事的方式： Windows 和 macOS 用户可以使用「一键安装 AI Coding 工具」。本页适合 Linux 用户，或希望手动管理 Codex 配置的用户。

完成后会得到什么

完成本页后：

终端可以运行 codex 命令。
Codex 通过 https://api.zcloudapi.com/v1/responses 调用 ZCloudAPI，不会要求登录官方 OpenAI 账号。
API Key 不会写进项目仓库，Codex 从环境变量读取它。
你能在控制台「使用日志」看到模型、Token 和扣费记录。

整个过程通常需要 10 至 20 分钟。请按编号依次完成；每一步看到“完成标志”后，再继续下一步。

第 1 步：打开正确的终端

Windows

Windows

打开开始菜单，搜索 PowerShell 并打开。后文标注“Windows PowerShell”的命令都粘贴到这个窗口，不要粘贴到浏览器地址栏。

macOS / Linux

macOS / Linux

macOS：按 Command + 空格，搜索终端或 Terminal 并打开。
Linux：从应用列表打开 Terminal。Ubuntu 等桌面系统通常也可以按 Ctrl + Alt + T。

完成标志： 屏幕上出现一行等待输入的提示符，可以粘贴命令。

第 2 步：安装 Codex CLI

先在终端执行：

codex --version

如果已经显示版本号，本步完成，继续第 3 步。如果提示找不到 codex，使用下面与你系统对应的官方安装命令。原生安装器不要求先安装 Node.js。

Windows

Windows PowerShell（推荐）

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

安装结束后，关闭 PowerShell 并重新打开，再检查版本：

codex --version

macOS / Linux

macOS / Linux（推荐）

curl -fsSL https://chatgpt.com/codex/install.sh | sh

安装结束后，关闭终端并重新打开，再检查版本：

codex --version

完成标志： 看到类似 codex-cli 0.x.x 的版本号。此时不要直接运行 codex 完成官方登录；先继续写入 ZCloudAPI 配置。

OpenAI 官方教程安装后的下一步是登录 ChatGPT。ZCloudAPI 使用自定义 Model Provider，所以本教程会先完成第 3 至第 7 步，再启动 Codex；这是有意调整，不是漏掉登录步骤。

备用方式：通过 Node.js 和 npm 安装

只有官方安装命令失败时才做这一节；官方安装已经成功就不要重复安装。

打开 Node.js 官方下载页，安装 LTS 版本。为了同时兼容 Claude Code，建议使用 Node.js 22 或更高版本。

Windows

Windows 也可以在 PowerShell 执行：

winget install OpenJS.NodeJS.LTS

macOS / Linux

macOS 已经安装 Homebrew 时，也可以执行：

brew install node

Linux 用户从 Node.js 官方下载页选择自己的发行版安装方式。

关闭终端并重新打开，确认两个命令都能显示版本号：

node --version
npm --version

安装 Codex：

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

如果 node 或 npm 仍提示找不到，不要继续安装 Codex；先重新安装 Node.js LTS，并确认安装程序已经把 Node.js 加入 PATH。不要用 sudo npm install -g 绕过权限问题。

第 3 步：创建 Codex 专用 Key

打开 ZCloudAPI 控制台并登录。
打开「钱包」，确认可用余额大于 0。如果余额为 0，先充值或兑换额度，再回到本页。
打开 API 密钥页，点击「创建 API 密钥」。
名称填写用途和设备，例如 codex-home-pc 或 codex-macbook。
分组选择能看到 GPT / Codex 模型的分组；以控制台当前显示的选项为准。
第一次配置可以先保持默认额度；需要控制消费时再设置独立额度和过期时间。
如果开启模型限制，至少勾选一个支持 Responses API 的 GPT 模型。
点击「创建」，回到密钥列表后点击复制，只保存以 sk- 开头的完整 Key。

API Key 相当于调用密码。不要把它发到群聊、工单截图或 Git 仓库。这里需要的是你在 ZCloudAPI 控制台创建的用户 Key，不是管理员配置的上游 Key。

完成标志： 你已经复制到一条以 sk- 开头的完整 Key，并且创建 Key 的控制台页面仍然可以打开。

第 4 步：临时设置 Key

先把 Key 放进当前终端。这样可以在写长期配置前确认 Key 本身可用。

Windows

Windows PowerShell

$env:ZHICLOUD_API_KEY="sk-替换成你复制的完整-Key"

不要把示例文字原样保留。把双引号中间的内容替换为刚才复制的完整 Key，然后检查：

if ($env:ZHICLOUD_API_KEY) { "Key 已设置" } else { "Key 未设置" }

macOS / Linux

macOS / Linux

export ZHICLOUD_API_KEY="sk-替换成你复制的完整-Key"

不要把示例文字原样保留。把双引号中间的内容替换为刚才复制的完整 Key，然后检查：

test -n "$ZHICLOUD_API_KEY" && echo "Key 已设置" || echo "Key 未设置"

完成标志： 终端明确显示 Key 已设置。检查命令不会打印完整 Key。

第 5 步：查询这条 Key 能用的模型

不要凭空猜模型名。用刚才的 Key 查询 /v1/models，然后从结果的 data[].id 中复制一个 GPT 模型 ID。

Windows

Windows PowerShell

curl.exe "https://api.zcloudapi.com/v1/models" `
  -H "Authorization: Bearer $env:ZHICLOUD_API_KEY"

macOS / Linux

macOS / Linux

curl "https://api.zcloudapi.com/v1/models" \
  -H "Authorization: Bearer $ZHICLOUD_API_KEY"

下面配置以 gpt-5.6-terra 为例。如果你的结果里没有它，必须把后文所有 gpt-5.6-terra 替换成你实际看到的模型名。

如果命令返回 401，回控制台重新复制 Key；如果返回的模型列表里没有 GPT 模型，检查 Key 的分组和模型限制。

完成标志： 你已经从返回结果中复制了一个 GPT 模型 ID。后文出现示例模型名时，都用这个 ID 替换。

第 6 步：备份并打开 Codex 配置

接下来打开 Codex 的用户级 config.toml。这份配置对当前电脑上的所有项目生效，不要在代码项目内部新建同名文件。

Windows

Windows PowerShell

New-Item -ItemType Directory -Force -Path "$HOME\.codex" | Out-Null
if (Test-Path "$HOME\.codex\config.toml") {
  Copy-Item "$HOME\.codex\config.toml" "$HOME\.codex\config.toml.backup"
}
notepad "$HOME\.codex\config.toml"

如果记事本询问是否创建新文件，选择“是”。

macOS / Linux

macOS / Linux

mkdir -p ~/.codex
if [ -f ~/.codex/config.toml ]; then
  cp ~/.codex/config.toml ~/.codex/config.toml.backup
fi
nano ~/.codex/config.toml

nano 中按 Ctrl + O、Enter 保存，再按 Ctrl + X 退出。如果原文件已有其他配置，把下一节内容合并进去，不要直接删除自己不认识的配置。

完成标志： 记事本或 nano 已经打开 config.toml，可以粘贴下一步的内容。

第 7 步：写入 ZCloudAPI Provider

Provider 就是“Codex 应该把请求发到哪里”的设置。把下面内容完整粘贴到 config.toml。只修改第一行的模型名；地址和 env_key 不要改。

model = "gpt-5.6-terra"
model_provider = "zhicloud"

[model_providers.zhicloud]
name = "ZCloudAPI"
base_url = "https://api.zcloudapi.com/v1"
env_key = "ZHICLOUD_API_KEY"
wire_api = "responses"

保存前逐项检查：

配置	正确写法	常见错误
`model_provider`	`zhicloud`	与下方 `[model_providers.zhicloud]` 名称不一致
`base_url`	`https://api.zcloudapi.com/v1`	少写 `/v1`，或多写 `/responses`
`env_key`	`ZHICLOUD_API_KEY`	在这里直接粘贴完整 Key
`wire_api`	`responses`	改成 `chat` 或 `chat_completions`
`requires_openai_auth`	不要添加	设置为 `true` 后进入官方 OpenAI 登录

保存文件后关闭编辑器。完成标志： 重新打开 config.toml 时，能看到完整的 model_provider 和 [model_providers.zhicloud] 两部分。

第 8 步：运行最小测试

保持刚才设置了 ZHICLOUD_API_KEY 的终端窗口，执行：

codex exec --skip-git-repo-check "只回复 OK"

看到 OK 后做最后一次核对打开 ZCloudAPI 控制台「使用日志」，确认同一时间出现了刚才选择的 GPT 模型，并且 Token 与扣费记录正常。终端和日志都成功，才表示配置完成。

如果 Codex 打开官方 OpenAI 登录页，立即退出，然后检查 model_provider = "zhicloud" 是否存在，以及配置中是否误写了 requires_openai_auth = true。

第 9 步：让 Key 在新终端中仍然生效

第 4 步的变量会在关闭终端后消失。下面选择与你系统对应的一种方式。

Windows

Windows PowerShell

把完整 Key 写入当前 Windows 用户的环境变量：

[Environment]::SetEnvironmentVariable(
  "ZHICLOUD_API_KEY",
  "sk-替换成你复制的完整-Key",
  "User"
)

执行后关闭所有 PowerShell 和 Windows Terminal 窗口，再重新打开。用下面命令确认：

if ($env:ZHICLOUD_API_KEY) { "Key 已长期保存" } else { "Key 未读取到" }

macOS / Linux

macOS（默认 zsh）

nano ~/.zshrc

在文件末尾新增一行，保存并退出：

export ZHICLOUD_API_KEY="sk-替换成你复制的完整-Key"

让当前终端立即读取新配置：

source ~/.zshrc

Linux（常见 bash）

nano ~/.bashrc

在文件末尾新增一行，保存并退出：

export ZHICLOUD_API_KEY="sk-替换成你复制的完整-Key"

让当前终端立即读取新配置：

source ~/.bashrc

这些方式会在本机用户配置中保存明文 Key，只适合自己的可信电脑。更安全的方式是使用 ZCloud Setup、系统凭据库、密码管理器或 CI Secret。不要把 Key 写进项目 .env 后提交到 Git。

第 10 步：在真实项目中使用

第一次先创建一个空的测试目录，这样不需要提前知道项目路径，也不会误改已有文件。

Windows

Windows PowerShell

New-Item -ItemType Directory -Force -Path "$HOME\zcloud-test" | Out-Null
Set-Location "$HOME\zcloud-test"
codex

macOS / Linux

macOS / Linux

mkdir -p ~/zcloud-test
cd ~/zcloud-test
codex

第一次先发送一条只读任务：

请阅读 README 和目录结构，不修改文件，只总结这个项目的启动方式和主要模块。

确认 Codex 正常回复后，按 Ctrl + C 退出。以后使用时，先用 cd 或 Set-Location 进入自己的代码目录，再运行 codex。Codex 中可以输入 /status 查看当前模型和 Provider，输入 /model 切换模型。

如果第一次启动时询问是否信任当前目录，先确认页面显示的是刚才创建的 zcloud-test，再选择信任或继续。遇到命令执行确认时先保留默认权限，确认它准备执行的操作后再允许。

需要排障时，再测试 Responses API

只有客户端测试失败时才需要执行这一节。它可以把“ZCloudAPI 链路问题”和“Codex 配置问题”分开。

Windows

Windows PowerShell

$body = @{
  model = "gpt-5.6-terra"
  input = "只回复 OK"
  max_output_tokens = 16
  stream = $false
} | ConvertTo-Json

curl.exe -i "https://api.zcloudapi.com/v1/responses" `
  -H "Authorization: Bearer $env:ZHICLOUD_API_KEY" `
  -H "Content-Type: application/json" `
  -d $body

macOS / Linux

macOS / Linux

curl -i "https://api.zcloudapi.com/v1/responses" \
  -H "Authorization: Bearer $ZHICLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "input": "只回复 OK",
    "max_output_tokens": 16,
    "stream": false
  }'

状态码 200 且正文包含 OK，说明 Key、模型、余额和 API 地址正常，继续检查 config.toml。如果这里也失败，先解决返回的 401、404、模型权限或余额问题，不要反复重装 Codex。

更新、切换模型与恢复配置

更新 Codex

原生安装器：重新执行第 2 步的官方安装命令。npm 安装：

npm install -g @openai/codex@latest

切换模型

重新查询 https://api.zcloudapi.com/v1/models。
打开第 6 步创建的 config.toml，修改顶部的 model。
完全退出 Codex，再运行最小测试。
到使用日志确认新模型已经生效。

恢复备份

macOS / Linux

macOS / Linux：

cp ~/.codex/config.toml.backup ~/.codex/config.toml

Windows

Windows PowerShell：

Copy-Item "$HOME\.codex\config.toml.backup" "$HOME\.codex\config.toml" -Force

只有确认 .backup 文件存在且内容正确时才恢复。

常见问题速查

现象	先检查什么
`codex` 命令不存在	关闭终端重开；检查安装是否成功和 `PATH`
Codex 要求登录 OpenAI	`model_provider` 是否为 `zhicloud`；删除 `requires_openai_auth = true`
`401 Unauthorized`	当前终端是否读到 `ZHICLOUD_API_KEY`；Key 是否完整、过期或停用
`model not found`	从 `/v1/models` 复制准确模型名，不要照抄本页示例
`/responses` 返回 `404`	`base_url` 必须是 `https://api.zcloudapi.com/v1`，不要多写 `/responses`
修改配置后没有变化	是否编辑了用户级 `~/.codex/config.toml`；完全退出并重开 Codex
使用日志没有请求	检查当前 Provider、代理和 Base URL；运行本页最小 API 测试
npm 提示权限不足	改用官方原生安装器或用户级 Node.js；不要长期使用 `sudo npm -g`

仍无法解决时，进入「排障手册」，并准备错误全文、发生时间、Codex 版本和模型名。不要提供完整 API Key。

完成后会得到什么

第 1 步：打开正确的终端

Windows

macOS / Linux

第 2 步：安装 Codex CLI

Windows PowerShell（推荐）

macOS / Linux（推荐）

备用方式：通过 Node.js 和 npm 安装

第 3 步：创建 Codex 专用 Key

第 4 步：临时设置 Key

Windows PowerShell

macOS / Linux

第 5 步：查询这条 Key 能用的模型

Windows PowerShell

macOS / Linux

第 6 步：备份并打开 Codex 配置

Windows PowerShell

macOS / Linux

第 7 步：写入 ZCloudAPI Provider

第 8 步：运行最小测试

第 9 步：让 Key 在新终端中仍然生效

Windows PowerShell

macOS（默认 zsh）

Linux（常见 bash）

第 10 步：在真实项目中使用

Windows PowerShell

macOS / Linux

需要排障时，再测试 Responses API

Windows PowerShell

macOS / Linux

更新、切换模型与恢复配置

更新 Codex

切换模型

恢复备份

常见问题速查

官方资料

页面资源加载失败