登录
文档导航
AI 编程入门

Codex / Claude Code 入门

从零选择、安装并接入 Codex 或 Claude Code。

本页目录
  1. 先选一条路线
  2. Codex 和 Claude Code 怎么选
  3. 开始前只要准备三样东西
  4. 第一次用终端，先看这里
  5. Node.js 和 npm 是什么
  6. API Key、模型和 Base URL 分别是什么
  7. 推荐的完成顺序
  8. 怎样才算接入完成
  9. 下一步

这是一张从“电脑上什么都没有”走到“Codex 或 Claude Code 成功回复”的路线图。先选工具和安装方式，再按对应教程从上往下做；不需要提前理解 API、Node.js 或配置文件。

1准备账号与余额
2创建 API Key
3安装客户端
4写入 ZCloud 配置
5发送第一条测试

先记住一个成功标准： 终端里看到 OK，并且 ZCloudAPI 控制台「使用日志」出现同一时间的请求，才表示整条接入链路已经可用。

先选一条路线

最适合第一次使用一键安装Windows 或 macOS。图形界面会创建引导、安装工具、保存 Key 并自动验证。 手动教程接入 Codex逐步安装 Codex CLI，配置 Responses Provider，再进入你的代码目录使用。 手动教程接入 Claude Code逐步安装 Claude Code，设置 Anthropic 兼容地址、Key 和默认模型。

如果你使用 Windows 或 macOS，并且只想尽快开始，选择「一键安装」。如果你使用 Linux、需要自己管理配置，或者想知道每一步做了什么，选择对应的手动教程。

Codex 和 Claude Code 怎么选

你的需求 建议选择 启动命令 ZCloudAPI 协议
使用 GPT / Codex 模型完成编程任务 Codex codex Responses API
使用 Claude 模型完成编程任务 Claude Code claude Anthropic Messages
两个都想试 分别配置 codex / claude 两套配置互不覆盖

两个工具都能读取代码、修改文件和运行命令。第一次使用时只安装一个，更容易定位问题；确认成功后再配置另一个。

开始前只要准备三样东西

  1. 一个可以登录 https://console.zcloudapi.com 的 ZCloudAPI 账号。
  2. 账户中有可用余额或额度。
  3. 一台 Windows 10 / 11、macOS 或常见 Linux 电脑。

还没有 API Key 没关系，两篇手动教程都会从创建 Key 开始，不需要先跳去别的文档。

第一次用终端，先看这里

终端就是输入命令的窗口。下面的教程会明确写出每条命令应该粘贴在哪里。

Windows打开开始菜单，搜索并打开 PowerShell。看到提示符以 PS 开头即可。
macOS按 Command + 空格，搜索“终端”或 Terminal，然后打开。
Linux从应用列表打开 Terminal，常见快捷键是 Ctrl + Alt + T。
代码块点击右上角“复制代码”，粘贴到终端后按 Enter。不要连同解释文字一起复制。

命令中的 sk-你的-ZCloudAPI-Key、/path/to/your/project 都是占位文字，必须替换成你自己的内容。不要把尖括号、引号外的说明或示例 Key 原样保留。

Node.js 和 npm 是什么

Node.js 是运行 JavaScript 工具的环境，npm 是随 Node.js 安装的软件包管理器。Codex 和 Claude Code 现在都有官方原生安装器，推荐方式不要求预装 Node.js。

只有在你选择 npm 安装时才需要 Node.js。为了同时兼容两个工具，建议安装 Node.js 的 LTS 版本，并使用 Node.js 22 或更高版本。对应手动教程会提供 Windows、macOS 和 Linux 的安装入口与检查命令。

API Key、模型和 Base URL 分别是什么

API Key相当于客户端的调用密码，通常以 sk- 开头。不要发送给他人，也不要提交到 Git。
模型决定实际调用哪个 GPT 或 Claude。不要凭空猜名称，要用自己的 Key 查询可用模型。
Codex Base URL使用 https://api.zcloudapi.com/v1，结尾包含 /v1，但不包含 /responses。
Claude Code Base URL使用 https://api.zcloudapi.com，结尾不要添加 /v1 或 /messages。

这两个 Base URL 不一样，是因为两个客户端会以不同方式拼接请求路径。照教程填写即可，不需要自己改写。

推荐的完成顺序

  1. 先安装客户端并确认 codex --version 或 claude --version 能输出版本号。
  2. 创建一条用途明确的 API Key，例如 home-codex 或 office-claude。
  3. 查询这条 Key 真正能看到的模型，复制一个准确的模型 ID。
  4. 按教程设置临时环境变量，先完成一次测试。
  5. 测试成功后再写入长期配置，避免把“Key 不可用”和“配置写错”混在一起排查。
  6. 在一个自己的代码目录里启动客户端，先让它执行只读任务。

怎样才算接入完成

同时满足下面四项，才算完成命令能输出版本号；最小测试返回 OK；客户端没有跳转到官方账号登录；ZCloudAPI「使用日志」记录了正确的模型、Token 和扣费。

如果其中一项不满足，不要反复卸载。先到对应教程底部按错误现象检查；仍无法解决时进入「排障手册」。

下一步