登录
文档导航
AI 编程入门

一键安装（推荐）

图文完成充值、创建 API Key，并安装配置 Codex 与 Claude Code。

本页目录
  1. 完成后你会得到什么
  2. 第 1 步：确认电脑类型并下载安装器
  3. 第 2 步：安装并打开 ZCloud Setup
  4. 第 3 步：选择要配置的工具
  5. 第 4 步：没有 API Key 时进入创建引导
  6. 第 5 步：购买或兑换额度
  7. 第 6 步：打开 API 密钥页并新建 Key
  8. 第 7 步：填写 Key 的基础配置
  9. 第 8 步：检查高级限制并创建
  10. 第 9 步：复制 Key 并粘贴回安装器
  11. 第 10 步：确认模型并完成安装
  12. 一个 Key 还是两个 Key
  13. 安装完成后的最小测试
  14. 安装器实际会做什么
  15. 如何移除 ZCloudAPI 配置
  16. 常见问题

ZCloud Setup 可以在 Windows 或 macOS 上分别配置 Codex Desktop、Codex CLI、Claude Desktop 和 Claude Code CLI，并把它们接入 ZCloudAPI。按照下面的图文步骤操作，即使以前没有创建过 API Key，也可以从充值开始完成安装和验证。

Windows 64 位下载 .exe 安装包 macOS Apple 芯片下载 Apple Silicon .dmg macOS Intel 芯片下载 Intel .dmg

当前 ZCloud Setup 版本为 0.2.1。四个工具默认均不勾选，由你按需选择。安装器会先检查每个组件：已经安装的版本只备份并合并 ZCloudAPI 配置，不会被强制重装或升级；缺失时安装 Codex CLI 0.147.0、Claude Code CLI 2.1.226，以及当前稳定版的 Codex Desktop 或 Claude Desktop。Codex CLI 官方原生包从 ZCloudAPI OSS 下载并验证 SHA512，不要求预装 Node.js 或 npm。

完成后你会得到什么

整个过程通常需要 5 至 10 分钟。完成后，你选择的桌面端或 CLI 会接入 ZCloudAPI，并且安装器会执行一次最小真实请求来确认配置可用。

开始前只需要准备：

  • 一台 Windows 10 / 11 或 macOS 电脑。
  • 一个可以登录 https://console.zcloudapi.com 的 ZCloudAPI 账号。
  • 可用余额或尚未使用的兑换码。

第 1 步：确认电脑类型并下载安装器

先根据电脑类型选择页面上方对应的安装包。不要直接运行以前保存的旧安装包。

ZCloud Setup 的 Windows、Apple 芯片和 Intel 下载入口

图 1：下载入口的本地开发预览。Windows 和两种 Mac 使用不同的安装包，请按电脑类型下载；此图不表示安装器下载、安装或真实调用已通过验证。

你的电脑 下载项 怎么确认
Windows 10 / 11 普通电脑 Windows 64 位 打开「设置 -> 系统 -> 系统信息」，查看系统类型
M1、M2、M3、M4 等新款 Mac macOS Apple 芯片 点击左上角 Apple 菜单 ->「关于本机」
处理器显示 Intel 的旧款 Mac macOS Intel 芯片 点击左上角 Apple 菜单 ->「关于本机」

macOS 也可以打开「终端」执行 uname -m：输出 arm64 时下载 Apple 芯片版，输出 x86_64 时下载 Intel 版。

第 2 步：安装并打开 ZCloud Setup

Windows

  1. 打开浏览器的下载列表，运行 ZCloud-Setup-0.2.1-windows-x64.exe。
  2. 如果 Microsoft Defender SmartScreen 显示「Windows 已保护你的电脑」，点击「更多信息」。
  3. 确认应用名称是 ZCloud Setup，然后点击「仍要运行」。

macOS

  1. 在 Finder 的「下载」目录双击刚下载的 DMG。
  2. 把 ZCloud Setup 拖到 Applications 文件夹，不要长期从 DMG 窗口中运行。
  3. 打开 Finder ->「应用程序」，按住 Control 点击 ZCloud Setup，然后选择「打开」。
  4. 如果系统仍然拦截，先尝试打开一次，再进入「系统设置 -> 隐私与安全性」，在安全提示下方点击「仍要打开」。

如果提示“Apple 无法验证 ZCloud Setup”

第一次打开时，部分 Mac 会显示“Apple 无法验证 ‘ZCloud Setup’ 是否包含可能危害 Mac 安全或泄漏隐私的恶意软件”。这是 macOS 对未经过 Apple 公证的应用显示的安全提示。

macOS 显示 Apple 无法验证 ZCloud Setup 的提示

图 2：看到这个提示时，先点击「完成」关闭窗口。

确认安装包是从本页下载后，按下面步骤放行：

  1. 打开左上角 Apple 菜单，进入「系统设置」。
  2. 在左侧选择「隐私与安全性」。
  3. 向下滚动到「安全性」，找到“已阻止 ‘ZCloud Setup’ 以保护 Mac”。
  4. 点击右侧「仍要打开」，按提示使用登录密码或 Touch ID 确认。
  5. 如果随后再次出现确认窗口，点击「打开」。以后可以从「应用程序」正常启动。

在 macOS 隐私与安全性中点击仍要打开

图 3：在「隐私与安全性 -> 安全性」中找到 ZCloud Setup，然后点击「仍要打开」。

只对从本页官方入口下载的 ZCloud Setup 执行以上操作。不要关闭 macOS 的整体安全保护，也不需要修改“允许以下来源的应用程序”选项。

第 3 步：选择要配置的工具

安装器打开后，勾选自己实际要用的工具。可以只选一个，也可以同时选择多个。

ZCloud Setup 中四个桌面端与 CLI 工具的独立选择页

图 4：Codex 和 Claude 各自分为桌面端与 CLI；选择后会显示「已安装，仅配置」或「未安装，将自动安装」。

工具 适合的使用方式
Codex Desktop 图形界面，适合日常交互、查看任务和审阅代码改动
Codex CLI 命令行工具，适合在终端和代码仓库中开发、编写脚本
Claude Desktop 图形界面，适合对话、文件分析和桌面工作流
Claude Code CLI 命令行工具，适合在终端中编码、处理项目和自动化任务

四项默认都不勾选，可以只选择其中一项。已经安装的组件会保留当前版本，安装器只备份并更新 ZCloudAPI 配置；只有选中且缺失的组件才会下载和安装。

第 4 步：没有 API Key 时进入创建引导

如果还没有 Key，点击安装器里的「没有 API Key？」或对应的创建引导。安装器会带你打开 ZCloudAPI 控制台；先登录账号，再按下面步骤准备余额和 Key。

ZCloud Setup 中没有 API Key 时的操作入口

图 5：第一次使用时从这里进入控制台，不需要提前记住页面地址。

如果已经有可用 Key，可以直接跳到「第 9 步：复制 Key 并粘贴回安装器」。

第 5 步：购买或兑换额度

登录 https://console.zcloudapi.com 后打开「钱包」。根据自己持有的付款方式或兑换码选择一种充值方式：

  1. 通过页面列出的区域商店购买额度；付款完成后回到钱包刷新余额。
  2. 如果已经拿到兑换码，在兑换区域输入兑换码并确认。
  3. 确认页面上的可用余额已经增加，再继续创建 Key。

ZCloudAPI 钱包中的额度购买入口和兑换码输入框

图 6：选择一个适合自己的购买入口，或者直接使用已有兑换码。

只有充值记录还不够，请以钱包里实际显示的可用余额为准。安装完成前会产生一次很小的真实请求用于验证。

第 6 步：打开 API 密钥页并新建 Key

在控制台左侧点击「API 密钥」，然后点击页面右上角的「新建密钥」。

ZCloudAPI 控制台的 API 密钥菜单和新建密钥按钮

图 7：先进入「API 密钥」，再点击右上角按钮创建一条新 Key。

Key 相当于账号的调用密码。每台设备单独创建一条 Key 会更容易辨认和停用，例如家里电脑和公司电脑不要共用同一个名称。

第 7 步：填写 Key 的基础配置

在新建页面依次填写：

  1. 名称：写清设备和用途，例如 macbook-codex、office-claude。
  2. 分组：Codex 使用能看到 GPT 模型的分组；Claude Desktop 和 Claude Code CLI 使用能看到 Claude 模型的分组。以当前控制台提供的分组选项为准。
  3. 过期时间：个人长期使用可以按需设置；临时设备建议设置明确的过期时间。
  4. 额度：初次使用可以采用默认设置；需要控制单台设备消费时，再设置独立额度。

创建 API Key 时的名称、分组、过期时间和额度设置

图 8：名称用于自己识别，分组决定这条 Key 能看到和调用哪些模型。

如果 Codex 和 Claude 使用不同分组，请分别创建两条 Key。不要为了省一步而给 Key 选择与工具不匹配的分组。

第 8 步：检查高级限制并创建

向下检查「模型限制」和「IP 白名单」等高级选项，然后点击创建。

API Key 的模型限制和 IP 白名单高级设置

图 9：普通个人电脑第一次配置时可以保持默认；明确需要限制时再填写。

  • 开启模型限制后，必须包含准备在所选 Codex 或 Claude 工具中使用的模型，否则安装器会提示找不到可用模型。
  • IP 白名单只适合具有固定公网 IP 的环境。普通家庭宽带、移动网络或经常切换网络的笔记本不建议随意填写。
  • 后续需要调整时，可以回到「API 密钥」页面编辑或停用这条 Key。

第 9 步：复制 Key 并粘贴回安装器

Key 创建成功后，点击它右侧的复制按钮。只复制以 sk- 开头的 Key，不要复制整段 JSON，也不要多带空格或换行。

在 API 密钥列表中复制新创建的 Key

图 10：通过复制按钮取得完整 Key，不要依靠手动输入。

回到 ZCloud Setup，把 Key 粘贴到对应输入框，然后点击「验证并继续」。安装器会连接 https://api.zcloudapi.com/v1/models 来确认 Key 有效，并读取它真正可以调用的模型。

把 API Key 粘贴到 ZCloud Setup 并验证

图 11：粘贴后先验证；验证通过才会进入模型确认和安装步骤。

不要把完整 Key 发到群聊、截图、工单或公开仓库。发现泄露时，立即在「API 密钥」页面停用旧 Key 并创建新 Key。

第 10 步：确认模型并完成安装

  1. 验证通过后，检查 Codex 和 Claude 分别选中的模型。
  2. 如果某个工具提示没有可用模型，回控制台检查 Key 的分组和模型限制，不要反复点击安装。
  3. 确认无误后点击「配置并安装缺失组件」。
  4. 安装期间不要关闭窗口，也不要让电脑进入睡眠。等待下载、SHA512 校验、配置写入、环境变量更新和真实请求验证全部完成。
  5. 看到「安装完成」后退出安装器，并关闭所有已打开的 PowerShell、Windows Terminal 或 macOS「终端」窗口。

一个 Key 还是两个 Key

使用方式 应该怎么填
只选择 Codex Desktop 或 CLI 填入能在 /v1/models 中看到 GPT 模型的 Key
同时选择两个 Codex 工具 两个工具共用上面的同一条 GPT Key
只选择 Claude Desktop 或 CLI 填入能在 /v1/models 中看到 Claude 模型的 Key
同时选择两个 Claude 工具 两个工具共用上面的同一条 Claude Key
同时选择 Codex 与 Claude 工具 必须分别填写 GPT Key 和 Claude Key，共两个 Key

安装器不会再把一条 Key 同时写给两个模型分组。选择了 Codex 与 Claude 时，请分别创建两条 Key，并在名称中写明用途；这样分组更清楚，后续也能单独停用。

安装完成后的最小测试

重新打开 PowerShell 或终端，执行：

codex --version
claude --version

只安装了其中一个工具时，只需要执行对应命令。版本号能显示后，再执行一次最小真实请求：

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

最后回到 https://console.zcloudapi.com 的「使用日志」，确认刚才的模型、时间和用量已经出现。命令返回 OK 且日志中有对应记录，才表示从客户端到 ZCloudAPI 的整条调用链路已经可用。

如果终端提示找不到命令，先完全退出所有终端窗口后重新打开。macOS 仍然找不到时，执行 echo $PATH，确认其中包含 $HOME/.local/bin。

安装器实际会做什么

ZCloud Setup 会按以下顺序执行：

  1. 分别检测 Codex Desktop、Codex CLI、Claude Desktop 和 Claude Code CLI 的现有安装路径与版本。
  2. 调用 https://api.zcloudapi.com/v1/models 验证 Key 和模型权限。
  3. 已安装组件保留当前版本，并在修改配置前备份原文件。
  4. 缺失组件才会下载和安装；Codex CLI 使用 ZCloudAPI OSS 中经过 SHA512 校验的官方原生包。
  5. 把缺失 CLI 安装到当前用户目录，不修改系统级 Node.js，也不影响本机已有项目。
  6. 只为选中的 Codex 或 Claude 工具写入对应的 ZCloudAPI Provider 配置。
  7. 把 Key 存入操作系统凭据库，不把完整 Key 明文写进配置文件。
  8. 把备份写入 ~/.zcloud/backups/<时间>/，安装失败时自动回滚本次改动。
  9. 执行一次最小真实调用，确认安装后的命令确实能访问 ZCloudAPI。

如何移除 ZCloudAPI 配置

重新打开 ZCloud Setup，在完成页或维护入口点击「移除 ZCloud 配置」。安装器会恢复自己修改的配置并移除仍未被用户替换的凭据，但不会删除 Codex Desktop、Codex CLI、Claude Desktop 或 Claude Code CLI，也不会覆盖安装后由你新增的其他配置。

如果图形安装器不能满足手动配置需求，请继续阅读「配置 Codex」或「配置 Claude Code」。

常见问题

现象 处理步骤
验证 Key 失败 回控制台重新复制 Key，确认没有空格、未停用且账户有余额
找不到 GPT 或 Claude 模型 查询 /v1/models，检查 Key 的分组和模型限制
Windows 提示未知发布者 确认文件来自本页下载入口，点击「更多信息 -> 仍要运行」
macOS 阻止应用打开 先尝试打开一次，再到「隐私与安全性」选择「仍要打开」
安装后终端找不到命令 关闭所有终端并重新打开，再检查用户 PATH
下载 Codex CLI 超时 重试并确认能访问 api.zcloudapi.com；安装包由 ZCloudAPI OSS 提供
下载 Desktop 或 Claude 超时 检查当前网络，确认能访问对应组件的官方发行源
最后真实调用失败 打开「使用日志」，按请求时间检查模型、余额和上游错误