Claude Code 从零接入

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

1打开终端

2安装 Claude Code

3创建 Key 并选模型

4写入环境配置

5运行并验收

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

完成后会得到什么

完成本页后：

终端可以运行 claude 命令。
Claude Code 通过 https://api.zcloudapi.com/v1/messages 调用 ZCloudAPI，不会进入官方 Claude 账号登录流程。
模型名称来自当前 Key 的真实可用列表，不依赖猜测。
你能在控制台「使用日志」看到模型、Token 和扣费记录。

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

开始前确认电脑符合要求

Windows

Windows 10 1809 或更高版本，或者 Windows Server 2019 或更高版本。
使用 64 位 x64 或 ARM64 处理器，不要打开名称带 (x86) 的 32 位 PowerShell。
至少 4 GB 内存，并且可以访问互联网。

macOS / Linux

macOS 13 或更高版本；或者 Ubuntu 20.04+、Debian 10+、Alpine Linux 3.19+。
使用 x64 或 ARM64 处理器，至少 4 GB 内存，并且可以访问互联网。

完成标志： 电脑满足上面的版本和硬件要求，可以继续打开终端。

第 1 步：打开正确的终端

Windows

Windows

打开开始菜单，搜索 PowerShell 并打开。看到提示符以 PS 开头即可。后文标注“Windows PowerShell”的命令都粘贴到这里。

macOS / Linux

macOS / Linux

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

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

第 2 步：安装 Claude Code

先在终端执行：

claude --version

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

Windows

Windows PowerShell（推荐）

irm https://claude.ai/install.ps1 | iex

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

claude --version
claude doctor

Windows 上推荐另外安装 Git for Windows，这样 Claude Code 可以使用 Git Bash；没有安装时仍可使用 PowerShell 工具。已经使用 WSL 的用户应在 WSL 终端执行下面的 Linux 安装命令，不要和 Windows 版本混装。

macOS / Linux

macOS / Linux / WSL（推荐）

curl -fsSL https://claude.ai/install.sh | bash

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

claude --version
claude doctor

完成标志： 看到 Claude Code 版本号，并且 claude doctor 没有安装错误。此时不要直接运行 claude 完成官方登录；先继续写入 ZCloudAPI 配置。

Anthropic 官方教程安装后的下一步是登录 Claude 账号。ZCloudAPI 通过 LLM Gateway 环境变量鉴权，所以本教程会先完成 Key 和 settings.json 配置；这是有意调整，不是漏掉登录步骤。

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

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

打开 Node.js 官方下载页，安装 LTS 版本。Anthropic 官方 npm 文档的最低要求是 Node.js 18；本站建议直接安装 Node.js 22 或更高 LTS，避免旧版本和当前软件包不兼容。

Windows

Windows 也可以在 PowerShell 执行：

winget install OpenJS.NodeJS.LTS

macOS / Linux

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

brew install node

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

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

node --version
npm --version

安装 Claude Code：

npm install -g @anthropic-ai/claude-code@latest
claude --version
claude doctor

不要用 sudo npm install -g 绕过权限问题。遇到权限错误时优先改用官方原生安装器，或者安装用户级 Node.js 环境。

第 3 步：创建 Claude Code 专用 Key

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

API Key 相当于调用密码。不要把它发到群聊、工单截图或 Git 仓库。如果 Codex 和 Claude 使用不同分组，分别创建两条 Key，名称中写清用途。

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

第 4 步：临时设置 Key 并查询模型

先把 Key 放进当前终端，再查询它真正能调用的模型。

Windows

Windows PowerShell

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

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

macOS / Linux

macOS / Linux

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

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

从结果的 data[].id 中复制一个 Claude 模型名。下面以 claude-sonnet-4-6 为例；如果你的结果中没有它，必须把后文所有 claude-sonnet-4-6 替换成你实际看到的模型名。

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

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

第 5 步：先用临时环境变量测试

临时变量只对当前终端有效，适合先验证配置，不会立刻改动长期设置。

Windows

Windows PowerShell

$env:ANTHROPIC_BASE_URL="https://api.zcloudapi.com"
$env:ANTHROPIC_AUTH_TOKEN=$env:ZHICLOUD_API_KEY
$env:ANTHROPIC_MODEL="claude-sonnet-4-6"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-6"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL="claude-sonnet-4-6"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-sonnet-4-6"

macOS / Linux

macOS / Linux

export ANTHROPIC_BASE_URL="https://api.zcloudapi.com"
export ANTHROPIC_AUTH_TOKEN="$ZHICLOUD_API_KEY"
export ANTHROPIC_MODEL="claude-sonnet-4-6"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-6"
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-sonnet-4-6"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-sonnet-4-6"

这里把 Sonnet、Opus 和 Haiku 别名先指向同一个确定可用的模型，目的是让主任务、计划模式和后台小任务都能成功。接入完成后，如果 Key 还能看到其他 Claude 模型，再分别优化。

现在执行最小测试：

claude -p --model claude-sonnet-4-6 "只回复 OK"

临时测试的成功标准终端输出 OK；没有打开官方 Claude 登录；ZCloudAPI 控制台「使用日志」出现同一时间的 Claude 请求。三项都满足后再写长期配置。

第 6 步：备份并打开 settings.json

接下来打开 Claude Code 的用户级 settings.json。这份配置对当前电脑上的所有项目生效。下面会创建目录，并在已有文件时自动备份。

Windows

Windows PowerShell

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

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

macOS / Linux

macOS / Linux

mkdir -p ~/.claude
if [ -f ~/.claude/settings.json ]; then
  cp ~/.claude/settings.json ~/.claude/settings.json.backup
fi
nano ~/.claude/settings.json

nano 中按 Ctrl + O、Enter 保存，再按 Ctrl + X 退出。如果原文件已有其他设置，只合并下一节的 env 字段，不要直接覆盖其他配置。

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

第 7 步：写入长期配置

JSON 是 Claude Code 的配置格式。把下面内容完整粘贴到 settings.json，只替换 Key 和模型名，不要改动大括号、引号和逗号。

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.zcloudapi.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-替换成你复制的完整-Key",
    "ANTHROPIC_MODEL": "claude-sonnet-4-6",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-sonnet-4-6",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-sonnet-4-6"
  }
}

保存前逐项检查：

配置	正确写法	常见错误
`ANTHROPIC_BASE_URL`	`https://api.zcloudapi.com`	多写 `/v1` 或 `/v1/messages`
`ANTHROPIC_AUTH_TOKEN`	完整 ZCloudAPI Key	同时设置两种认证变量，或漏掉 Key 字符
模型名	来自 `/v1/models` 的准确 ID	原样照抄本页但 Key 无权使用
JSON 格式	最后一项后面没有逗号	使用中文引号、漏引号、末尾多逗号

macOS / Linux

macOS / Linux 可以限制文件只允许当前用户读取：

chmod 600 ~/.claude/settings.json

保存并关闭编辑器。完成标志： 重新打开 settings.json 时，内容仍在，并且最后一行没有多余逗号。

这种新手配置会把 Key 明文保存在自己的电脑中。只适合可信的个人设备。更安全的方式是从 settings.json 删除 ANTHROPIC_AUTH_TOKEN，再通过系统凭据库、密码管理器或 Secret 注入；ZCloud Setup 默认使用操作系统凭据库。

第 8 步：关闭旧终端并再次验收

完全关闭正在运行的 Claude Code。
关闭所有终端窗口。
重新打开一个终端。
执行：

claude --version
claude doctor
claude -p --model claude-sonnet-4-6 "只回复 OK"

如果新终端仍然返回 OK，说明 settings.json 已被正确读取。最后到控制台「使用日志」核对模型、Token 和扣费。

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

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

Windows

Windows PowerShell

New-Item -ItemType Directory -Force -Path "$HOME\zcloud-test" | Out-Null
Set-Location "$HOME\zcloud-test"
claude --model claude-sonnet-4-6

macOS / Linux

macOS / Linux

mkdir -p ~/zcloud-test
cd ~/zcloud-test
claude --model claude-sonnet-4-6

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

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

确认 Claude Code 正常回复后，按 Ctrl + C 中断当前任务，再按一次退出。以后使用时，先用 cd 或 Set-Location 进入自己的代码目录，再运行 claude。交互界面中可以输入 /model 查看或切换模型。

如果第一次启动时询问是否信任当前目录，先确认页面显示的是刚才创建的 zcloud-test，再选择信任或继续。遇到工具执行确认时先阅读它准备执行的操作，再决定是否允许。

需要排障时，再测试 Messages API

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

Windows

Windows PowerShell

$body = @{
  model = "claude-sonnet-4-6"
  max_tokens = 32
  messages = @(@{ role = "user"; content = "只回复 OK" })
} | ConvertTo-Json -Depth 5

curl.exe -i "https://api.zcloudapi.com/v1/messages" `
  -H "x-api-key: $env:ZHICLOUD_API_KEY" `
  -H "anthropic-version: 2023-06-01" `
  -H "content-type: application/json" `
  -d $body

macOS / Linux

macOS / Linux

curl -i "https://api.zcloudapi.com/v1/messages" \
  -H "x-api-key: $ZHICLOUD_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 32,
    "messages": [
      {"role": "user", "content": "只回复 OK"}
    ]
  }'

状态码 200 且 content[0].text 包含 OK，说明 Key、模型、余额和 Messages API 正常，继续检查 Claude Code 环境变量。这里也失败时，先解决返回的 401、404、模型权限或余额问题，不要反复重装 Claude Code。

清理冲突 Provider

以前配置过 Bedrock、Vertex、Foundry 或其他网关时，Claude Code 可能忽略当前地址。先查看相关变量。

macOS / Linux

macOS / Linux：

env | grep -E 'ANTHROPIC|CLAUDE_CODE_USE|BEDROCK|VERTEX|FOUNDRY'

Windows

Windows PowerShell：

Get-ChildItem Env: | Where-Object {
  $_.Name -match 'ANTHROPIC|CLAUDE_CODE_USE|BEDROCK|VERTEX|FOUNDRY'
}

确认没有 CLAUDE_CODE_USE_BEDROCK=1、CLAUDE_CODE_USE_VERTEX=1、CLAUDE_CODE_USE_FOUNDRY=1，也不要同时设置另一个 ANTHROPIC_API_KEY 或 Base URL。删除冲突配置后完全关闭终端再重开。

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

更新 Claude Code

原生安装通常会自动更新，也可以执行：

claude update

npm 安装则执行：

npm install -g @anthropic-ai/claude-code@latest

切换模型

重新查询 https://api.zcloudapi.com/v1/models。
更新 settings.json 中 ANTHROPIC_MODEL 和对应默认模型变量。
完全退出 Claude Code 并重新打开终端。
再运行一次 claude -p 最小测试。
到使用日志确认新模型已经生效。

恢复备份

macOS / Linux

macOS / Linux：

cp ~/.claude/settings.json.backup ~/.claude/settings.json

Windows

Windows PowerShell：

Copy-Item "$HOME\.claude\settings.json.backup" "$HOME\.claude\settings.json" -Force

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

常见问题速查

现象	先检查什么
`claude` 命令不存在	关闭终端重开；检查安装是否成功和 `PATH`
Claude Code 打开官方登录	`ANTHROPIC_AUTH_TOKEN` 是否存在；是否有冲突 Provider
`401 Unauthorized`	Key 是否完整、过期或停用；当前终端是否仍有旧变量
`404 Not Found`	`ANTHROPIC_BASE_URL` 必须只写 `https://api.zcloudapi.com`，不要追加路径
模型不存在	从 `/v1/models` 复制准确模型名，不要照抄本页示例
主对话成功、后台任务失败	`ANTHROPIC_DEFAULT_HAIKU_MODEL` 是否指向可用模型
curl 成功但 Claude Code 失败	检查 `settings.json` JSON 格式、冲突变量和 `claude doctor`
使用日志没有请求	确认启动 Claude Code 的终端读取了 ZCloudAPI Base URL
npm 提示 Node 版本过低	安装 Node.js 22 或更高 LTS，关闭终端重开后再安装

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

Claude Code 从零接入

完成后会得到什么

开始前确认电脑符合要求

第 1 步：打开正确的终端

Windows

macOS / Linux

第 2 步：安装 Claude Code

Windows PowerShell（推荐）

macOS / Linux / WSL（推荐）

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

第 3 步：创建 Claude Code 专用 Key

第 4 步：临时设置 Key 并查询模型

Windows PowerShell

macOS / Linux

第 5 步：先用临时环境变量测试

Windows PowerShell

macOS / Linux

第 6 步：备份并打开 settings.json

Windows PowerShell

macOS / Linux

第 7 步：写入长期配置

第 8 步：关闭旧终端并再次验收

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

Windows PowerShell

macOS / Linux

需要排障时，再测试 Messages API

Windows PowerShell

macOS / Linux

清理冲突 Provider

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

更新 Claude Code

切换模型

恢复备份

常见问题速查

官方资料

页面资源加载失败