ZCloud Setup 安装与配置
了解 ZCloud Setup 的系统选择、Key 准备、安全检查与验证限制，以及安装遇阻后的手动配置路径。
文档更新:
本页目录
本页说明 ZCloud Setup 的工具选择、Key 准备和配置检查流程。想直接手动接入时，可以从 Codex CLI或 Claude Code开始；准备 Key 和正确地址分别见获取 API Key与接入地址选择。
文档复核：2026-10-18。说明对应 ZCloud Setup
0.2.1；2026-10-16 的 macOS Apple 芯片包静态核查显示 ad-hoc 签名、无 Developer ID 身份链，Gatekeeper 拒绝。该次没有完成真实安装、配置合并、凭据保存、失败回滚或最终调用。Windows、Intel 及四个目标工具的安装兼容性也未因此获验收。遇到系统安全拦截时暂停安装，核实来源与签名，或使用上述手动教程。
0.2.1的设计配置如下，不代表已在每种系统实装通过：四个工具默认均不勾选，由你按需选择。安装器会先检查每个组件：已经安装的版本只备份并合并 ZCloudAPI 配置，不会被强制重装或升级；缺失时安装 Codex CLI0.147.0、Claude Code CLI2.1.226，以及当前稳定版的 Codex Desktop 或 Claude Desktop。Codex CLI 官方原生包从 ZCloudAPI OSS 下载并验证 SHA512，不要求预装 Node.js 或 npm。
完成后你会得到什么
目标是让所选工具接入 ZCloudAPI，并完成最小真实请求与使用日志核对。下载速度、系统安全检查和工具版本会影响耗时；安装器显示“完成”不能替代目标工具重新启动后的真实调用。
开始前只需要准备：
- 一台 Windows 10 / 11 或 macOS 电脑。
- 一个可以登录
https://console.zcloudapi.com的 ZCloudAPI 账号。 - 可用余额或尚未使用的兑换码。
第 1 步：确认电脑类型并下载安装器
先根据电脑类型选择页面上方对应的安装包。不要直接运行以前保存的旧安装包。
图 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
核对下载来源、文件版本和系统显示的发布者后再决定是否运行。如果 SmartScreen 提示未知发布者或无法确认文件可信度，先停止，向支持人员索取可核对的发布信息，或改用 Codex / Claude Code的官方安装流程。本页不把“仍要运行”作为默认步骤。
macOS
双击下载的 DMG，将应用拖到「应用程序」。如果出现“Apple 无法验证”或其他安全拦截，不要直接移除隔离属性、关闭 Gatekeeper 或降低系统整体保护。当前已记录的 0.2.1 Apple 芯片包尚缺 Developer ID / 公证的验证依据，应暂停并使用手动教程；截图不能作为签名可信或安装成功的证据。
准备继续前，请核实实际包是否已有新的发布说明、可比对摘要和签名信息。本页的历史版本记录不推定新包已经修复，也不推定 Intel 包与 Apple 芯片包具有相同结果。
第 3 步：选择要配置的工具
安装器打开后，勾选自己实际要用的工具。可以只选一个，也可以同时选择多个。
图 2：Codex 和 Claude 各自分为桌面端与 CLI；选择后会显示「已安装，仅配置」或「未安装，将自动安装」。
| 工具 | 适合的使用方式 |
|---|---|
| Codex Desktop | 图形界面，适合日常交互、查看任务和审阅代码改动 |
| Codex CLI | 命令行工具，适合在终端和代码仓库中开发、编写脚本 |
| Claude Desktop | 图形界面，适合对话、文件分析和桌面工作流 |
| Claude Code CLI | 命令行工具，适合在终端中编码、处理项目和自动化任务 |
四项默认都不勾选，可以只选择其中一项。已经安装的组件会保留当前版本，安装器只备份并更新 ZCloudAPI 配置；只有选中且缺失的组件才会下载和安装。
第 4 步：没有 API Key 时进入创建引导
如果还没有 Key，点击安装器里的「没有 API Key？」或对应的创建引导。安装器会带你打开 ZCloudAPI 控制台；先登录账号，再按下面步骤准备余额和 Key。
图 3：第一次使用时从这里进入控制台，不需要提前记住页面地址。
如果已经有可用 Key，可以直接跳到「第 9 步：复制 Key 并粘贴回安装器」。
第 5 步：购买或兑换额度
登录 https://console.zcloudapi.com 后打开「钱包」。根据自己持有的付款方式或兑换码选择一种充值方式：
- 通过页面列出的区域商店购买额度；付款完成后回到钱包刷新余额。
- 如果已经拿到兑换码，在兑换区域输入兑换码并确认。
- 确认页面上的可用余额已经增加，再继续创建 Key。
图 4：选择一个适合自己的购买入口，或者直接使用已有兑换码。
只有充值记录还不够，请以钱包里实际显示的可用余额为准。安装完成前会产生一次很小的真实请求用于验证。
第 6 步：打开 API 密钥页并新建 Key
在控制台左侧点击「API 密钥」，然后点击页面右上角的「新建密钥」。
图 5：先进入「API 密钥」，再点击右上角按钮创建一条新 Key。
Key 相当于账号的调用密码。每台设备单独创建一条 Key 会更容易辨认和停用，例如家里电脑和公司电脑不要共用同一个名称。
第 7 步：填写 Key 的基础配置
在新建页面依次填写：
- 名称：写清设备和用途，例如
macbook-codex、office-claude。 - 分组：Codex 使用能看到 GPT 模型的分组；Claude Desktop 和 Claude Code CLI 使用能看到 Claude 模型的分组。以当前控制台提供的分组选项为准。
- 过期时间：个人长期使用可以按需设置；临时设备建议设置明确的过期时间。
- 额度：初次使用可以采用默认设置；需要控制单台设备消费时，再设置独立额度。
图 6：名称用于自己识别，分组决定这条 Key 能看到和调用哪些模型。
如果 Codex 和 Claude 使用不同分组，请分别创建两条 Key。不要为了省一步而给 Key 选择与工具不匹配的分组。
第 8 步：检查高级限制并创建
向下检查「模型限制」和「IP 白名单」等高级选项，然后点击创建。
图 7：普通个人电脑第一次配置时可以保持默认；明确需要限制时再填写。
- 开启模型限制后，必须包含准备在所选 Codex 或 Claude 工具中使用的模型，否则安装器会提示找不到可用模型。
- IP 白名单只适合具有固定公网 IP 的环境。普通家庭宽带、移动网络或经常切换网络的笔记本不建议随意填写。
- 后续需要调整时，可以回到「API 密钥」页面编辑或停用这条 Key。
第 9 步：复制 Key 并粘贴回安装器
Key 创建成功后，使用该行菜单的「复制密钥」取得纯 Key；如果主复制按钮返回连接 JSON，只取 api_key 字段。不要把整段 JSON 粘贴到 Key 输入框，也不要多带空格或换行。
图 8：通过复制按钮取得完整 Key，不要依靠手动输入。
回到 ZCloud Setup，把 Key 粘贴到对应输入框，然后点击「验证并继续」。安装器会连接 https://api.zcloudapi.com/v1/models 来确认 Key 有效，并读取它真正可以调用的模型。
图 9：粘贴后先验证；验证通过才会进入模型确认和安装步骤。
不要把完整 Key 发到群聊、截图、工单或公开仓库。发现泄露时，立即在「API 密钥」页面停用旧 Key 并创建新 Key。
第 10 步：确认模型并完成安装
- 验证通过后，检查 Codex 和 Claude 分别选中的模型。
- 如果某个工具提示没有可用模型，回控制台检查 Key 的分组和模型限制，不要反复点击安装。
- 确认无误后点击「配置并安装缺失组件」。
- 安装期间不要关闭窗口，也不要让电脑进入睡眠。等待下载、SHA512 校验、配置写入、环境变量更新和真实请求验证全部完成。
- 看到「安装完成」后退出安装器，并关闭所有已打开的 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。
安装器实际会做什么
0.2.1 的设计流程如下。当前没有真实安装全链验收，实际执行结果需要逐项确认：
- 分别检测 Codex Desktop、Codex CLI、Claude Desktop 和 Claude Code CLI 的现有安装路径与版本。
- 调用
https://api.zcloudapi.com/v1/models验证 Key 和模型权限。 - 已安装组件保留当前版本，并在修改配置前备份原文件。
- 缺失组件才会下载和安装；Codex CLI 使用 ZCloudAPI OSS 中经过 SHA512 校验的官方原生包。
- 把缺失 CLI 安装到当前用户目录，不修改系统级 Node.js，也不影响本机已有项目。
- 只为选中的 Codex 或 Claude 工具写入对应的 ZCloudAPI Provider 配置。
- 把 Key 存入操作系统凭据库，不把完整 Key 明文写进配置文件。
- 把备份写入
~/.zcloud/backups/<时间>/，安装失败时自动回滚本次改动。 - 执行一次最小真实调用，确认安装后的命令确实能访问 ZCloudAPI。
如何移除 ZCloudAPI 配置
重新打开 ZCloud Setup，在完成页或维护入口点击「移除 ZCloud 配置」。该入口的设计目标是恢复自身修改的配置并移除对应凭据，同时保留工具和用户后续新增配置；本轮尚未实测恢复、合并和凭据清理。操作前另行备份，完成后检查配置和目标工具，不依赖未经验证的自动恢复承诺。
如果图形安装器不能满足手动配置需求，请继续阅读「配置 Codex」或「配置 Claude Code」。
常见问题
| 现象 | 处理步骤 |
|---|---|
| 验证 Key 失败 | 回控制台重新复制 Key，确认没有空格、未停用且账户有余额 |
| 找不到 GPT 或 Claude 模型 | 查询 /v1/models，检查 Key 的分组和模型限制 |
| Windows 提示未知发布者 | 暂停运行，核对来源、发布者及可比对摘要，或改用手动教程 |
| macOS 阻止应用打开 | 暂停安装，核实签名和发布信息，或改用手动教程 |
| 安装后终端找不到命令 | 关闭所有终端并重新打开，再检查用户 PATH |
| 下载 Codex CLI 超时 | 重试并确认能访问 api.zcloudapi.com；安装包由 ZCloudAPI OSS 提供 |
| 下载 Desktop 或 Claude 超时 | 检查当前网络，确认能访问对应组件的官方发行源 |
| 最后真实调用失败 | 打开「使用日志」，按请求时间检查模型、余额和上游错误 |
安装遇阻后的下一步
- CLI 的独立配置与真实测试：Codex、Claude Code。这些 CLI 调用的验证不等于安装器或 Desktop 兼容通过。
- 权限、地址或费用不明确：接入地址、模型价格、计费与分组。
- 返回错误或一直等待：排障手册；公共探测可参考 ZCloudAPI 状态页，个人调用仍以实际结果和日志为准。
返回文档中心，按使用目标选择其他接入路径。