Zivv Docs

主题

Claude Code 配置指南 ​

Claude Code 是 Anthropic 官方的编程助手。Zivv 提供 Anthropic Messages API 兼容网关，可通过官方支持的网关环境变量接入。

最近核验：2026-10-23。安装命令、ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 已对照 Anthropic 官方安装与网关文档。本次更新：原生 Windows 不再强制要求 Git for Windows；补充 settings.json 持久化配置、npm 安装与 Homebrew 发布渠道说明。

1. 安装 Claude Code ​

原生安装（官方推荐） ​

原生安装支持后台自动更新，不依赖 Node.js。

bash
curl -fsSL https://claude.ai/install.sh | bash
powershell
irm https://claude.ai/install.ps1 | iex
batch
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Windows 可以原生运行（无需管理员权限），也可以在 WSL 中运行。原生 Windows 上 Git for Windows 为可选：安装后 Claude Code 用 Git Bash 执行命令，未安装时改用 PowerShell 工具。

包管理器安装 ​

bash
brew install --cask claude-code
powershell
winget install Anthropic.ClaudeCode

Homebrew 的 claude-code 跟随 stable 渠道（通常比最新版晚约一周，并跳过有重大回归的版本）；需要第一时间获取新版本时改装 claude-code@latest。Homebrew 和 WinGet 安装默认不会自动更新，需要分别执行 brew upgrade claude-code（或 brew upgrade claude-code@latest）、winget upgrade Anthropic.ClaudeCode。Debian、Fedora、RHEL 和 Alpine 也可以使用官方 apt、dnf、apk 仓库，见 官方安装文档。

npm 安装 ​

npm 方式需要 Node.js 22 或更高版本：

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

不要使用 sudo npm install -g。升级时执行 npm install -g @anthropic-ai/claude-code@latest，不要用 npm update -g：它受原安装的版本范围限制，可能升级不到最新版。

验证安装：

bash
claude --version

需要更完整的安装与配置诊断时，执行 claude doctor。最新平台要求见 Claude Code 安装文档。

2. 配置 Zivv 网关 ​

Claude Code 官方网关配置使用：

  • ANTHROPIC_BASE_URL：网关地址
  • ANTHROPIC_AUTH_TOKEN：网关 Bearer Token

Zivv 同时兼容 x-api-key 和 Authorization: Bearer，因此这里优先使用官方网关文档推荐的 ANTHROPIC_AUTH_TOKEN，不要同时设置 ANTHROPIC_API_KEY。

临时设置 ​

bash
export ANTHROPIC_BASE_URL="https://zivv.pro"
export ANTHROPIC_AUTH_TOKEN="sk-你的Key"
claude
powershell
$env:ANTHROPIC_BASE_URL = "https://zivv.pro"
$env:ANTHROPIC_AUTH_TOKEN = "sk-你的Key"
claude
cmd
set ANTHROPIC_BASE_URL=https://zivv.pro
set ANTHROPIC_AUTH_TOKEN=sk-你的Key
claude

永久设置 ​

推荐写入用户级配置文件 ~/.claude/settings.json（Windows 为 %USERPROFILE%\.claude\settings.json）的 env 块。它对所有项目生效，也能覆盖从 Dock、开始菜单启动的编辑器和后台会话；只写在 Shell 配置里的变量不一定能传到这些场景。

json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://zivv.pro",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的Key"
  }
}

文件已存在时，只合并 env 中的这两项，保留其他配置。

不要提交 Key

不要把 Key 写进项目的 .claude/settings.json：该文件会随仓库提交并共享。只想在某个项目里使用另一个 Key 时，写入该项目的 .claude/settings.local.json，并确认它已被 Git 忽略。

也可以继续使用 Shell 配置文件：

bash
echo 'export ANTHROPIC_BASE_URL="https://zivv.pro"' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN="sk-你的Key"' >> ~/.zshrc
source ~/.zshrc
bash
echo 'export ANTHROPIC_BASE_URL="https://zivv.pro"' >> ~/.bashrc
echo 'export ANTHROPIC_AUTH_TOKEN="sk-你的Key"' >> ~/.bashrc
source ~/.bashrc
powershell
[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://zivv.pro", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "sk-你的Key", "User")

Shell 变量与 settings.json 同时设置同一变量时，以 settings.json 为准。设置后重新打开终端和 Claude Code。ANTHROPIC_BASE_URL 不要追加 /v1/messages，客户端会自动拼接请求路径。

VS Code 扩展

VS Code 扩展在启动前会自行检查凭证，请在 VS Code 用户设置（Preferences: Open User Settings (JSON)）中另外填写：

json
{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://zivv.pro" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-你的Key" }
  ]
}

3. 验证配置 ​

启动 Claude Code 后执行 /status，在 Status 页确认：

  • Anthropic base URL 为 https://zivv.pro
  • Auth token 一行显示凭证来自 ANTHROPIC_AUTH_TOKEN

如果显示的是 claude.ai 账号的 Login method，说明变量没有生效。也可以直接测试：

bash
echo "只回复 pong" | claude -p --output-format text

返回正常文本后，到 用量日志 核对模型、Token 和状态码。

4. 选择模型 ​

Claude Code 的默认模型和别名会随版本变化。请从 模型广场 复制当前可用模型 ID，并确认 Key 分组允许访问。

临时指定模型：

bash
claude --model "模型广场中的模型 ID"

希望在 /model 选择器中直接看到 Zivv 当前提供的模型时，可以额外设置 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1（写入 Shell 或 settings.json 的 env）。Claude Code 启动时会查询网关的 /v1/models，并把结果加入选择器。

升级 Claude Code 后，应重新验证默认模型、工具调用、扩展思考和上下文能力。不要长期依赖文档中的固定模型版本。

故障排查 ​

401 或认证错误 ​

  • 确认只设置了 ANTHROPIC_AUTH_TOKEN，没有残留冲突的 ANTHROPIC_API_KEY
  • 检查 Key 是否完整、有效、未过期
  • 重新打开终端，确认新进程已读取环境变量
  • Key 轮换后完全退出并重启 Claude Code

启动时提示存在两个凭证来源 ​

提示以 auth may not work as expected 结尾（旧版本为 Auth conflict: Both a token ... and an API key ... are set）时，说明网关变量与已保存的 claude.ai 登录同时存在。请求会使用变量中的 Key，但残留登录可能导致认证异常；只用 Zivv 时执行 /logout 清除已保存的登录。

连接失败或 404 ​

  • Base URL 使用 https://zivv.pro
  • 不要填写 https://zivv.pro/v1/messages
  • 用 curl https://zivv.pro/health 检查基础网络
  • 检查本地代理、防火墙和 HTTPS 证书拦截

模型不可用、402 或 403 ​

检查模型 ID、个人余额、Key 额度、模型权限和团队预算，详见 用量、额度与限流。

普通对话成功，但工具调用失败 ​

第三方网关必须正确处理 anthropic-version、anthropic-beta、流式事件和工具字段。Zivv 会处理已支持的 Anthropic 协议，并对部分字段做自动修正（见 请求兼容性修正）；具体能力仍取决于所选模型和当前网关版本。

如果返回 400，且提到 context_management、Extra inputs are not permitted 等无法识别的字段，可以设置 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 关闭大部分实验性请求字段后重试。

官方资料 ​

Zivv — OpenAI / Anthropic / Gemini 多协议 AI Gateway

© 2026 Zivv