Claude Code 综合配置

覆盖 Windows、macOS、Linux、Anthropic 兼容地址、Claude/DeepSeek/ChatGPT 路由和 CC Switch 配置。

本页将青云 TOP API 客户端接入资料按使用场景合并整理，适合第一次接入的用户，也适合需要核对协议和路径的 API 开发者。青云 TOP API 基于 New API 部署，因此 New API 官方应用教程中的兼容配置可以直接复用。

快速判断：我应该看哪一段？

只想聊天：先看桌面端的基础配置。
要接入 MCP、知识库或工作流：看 Agent/自动化章节。
要在终端写代码：看 CLI、Provider 和环境变量章节。
遇到 401、403、404 或模型不兼容：先检查本文末尾的接入检查清单，再查看对应来源章节。

Claude Code（融合自原文档）

Claude Code 教程 — 将 Anthropic 的终端编程助手对接青云 TOP API。支持代码理解、多文件编辑，集成 VS Code 与 JetBrains IDE。

项目介绍

直接在你的终端中释放 Claude 的强大能力。瞬间搜索百万行代码库。将耗时数小时的工作流程化为一条命令。你的工具，你的工作流，你的代码库，以思维速度进化。

官方主页：https://www.anthropic.com/claude-code

效果演示

特性

功能分类

特性

代码理解

深度代码库分析，利用智能代理搜索理解项目结构和依赖

自动生成高层次代码概述，快速帮助用户理解代码库

代码编辑

支持多文件协同编辑，适用于复杂代码修改

提供符合项目模式和架构的实际可用代码建议

集成能力

支持在终端中直接运行，无需切换上下文

与VS Code和JetBrains IDE无缝集成，无需复制粘贴

代码生成和优化

自动生成代码、创建测试、修复错误，支持从概念到提交的完整流程

为代码生成和理解优化，结合Claude Opus 4等先进模型

安全与灵活性

改动需获得用户明确授权，文件和命令操作更安全

适应用户代码规范，支持自定义配置

工具链整合

支持与GitHub、GitLab等工具结合，实现自动化工作流程

与测试套件、构建系统集成，增强现有开发工具

跨平台与扩展

支持Windows、macOS、Linux操作系统

可配置运行在SDK或GitHub Actions中，灵活适配不同需求

主要应用场景

代码库入门和理解、新成员快速上手

代码问题修复与优化流程，从分析问题到提交PR

项目代码重构与新功能实现

用户反馈亮点

提升日常开发效率，省去例行任务消耗的时间

处理复杂多步骤任务表现优异，扩展开发可能性

AI 模型配置方法

Windows 端图文指引

1.安装 Node.js 环境

Claude Code 需要 Node.js 环境才能运行。

Node.js 环境安装步骤

打开浏览器访问 https://nodejs.org/
点击 "LTS"版本进行下载（推荐长期支持版本）
下载完成后双击 .msi 文件
按照安装向导完成安装，保持默认设置即可

Windows 注意事项

建议使用 PowerShell 而不是 CMD
如果遇到权限问题，尝试以管理员身份运行
某些杀毒软件可能会误报，需要添加白名单

验证安装是否成功

安装完成后，打开 PowerShell 或 CMD，输入以下命令：

node --version
npm --version

如果显示版本号，说明安装成功。

2.安装 Git Bash

Windows 注意事项

Windows 环境下需要使用 Git Bash 安装 Claude code。安装完成后，环境变量设置和使用 Claude Code 仍然在普通的 PowerShell 或 CMD 中进行。

下载并安装 Git for Windows

访问 https://git-scm.com/downloads/win
点击 "Download for Windows" 下载安装包
运行下载的 .exe 安装文件
在安装过程中保持默认设置，直接点击 "Next" 完成安装

验证 Git Bash 安装

安装完成后，打开 Git Bash，输入以下命令验证：

git --version

如果显示版本号，说明安装成功。

3.安装 Claude Code

安装 Claude Code

打开 PowerShell，运行以下命令：

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

这个命令会从 npm 官方仓库下载并安装最新版本的 Claude Code。

将 ~/.local/bin 加入 PATH（仅当提示要求时）

[Environment]::SetEnvironmentVariable('Path', ([Environment]::GetEnvironmentVariable('Path','User') + ";$HOME\.local\bin"), 'User')

验证 Claude Code 安装

安装完成后，输入以下命令检查是否安装成功：

claude --version

如果显示版本号，恭喜你！Claude Code 已经成功安装了。

4.设置环境变量

一键设置命令 (Windows 系统)

为了让 Claude Code 连接到你的中转服务，需要设置多个环境变量：

iex (irm 'https://raw.githubusercontent.com/QuantumNous/new-api-docs/refs/heads/main/helper/claude-cli-setup.ps1')

5.开始使用 Claude Code

现在你可以开始使用 Claude Code 了！

启动 Claude Code

打开 PowerShell，直接启动 Claude Code：

claude

在特定项目中使用：

# 进入你的项目目录
cd C:\path\to\your\project

# 启动 Claude Code
claude

选择模型

输入命令：

/model

按 Enter 进入，选择模型，通常使用默认设置即可。

> 注意：设置环境变量修改后，使用所有模型（包括官方预设模型）均调用自定义接入点，而不使用官方账号额度。

MacOS 端图文指引

1.安装 Claude Code CLI

打开终端

安装 Claude Code

打开终端，运行以下命令：

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

可选项：出现提示后运行提供的命令

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

2.设置环境变量

为了让 Claude Code 连接到第三方中转服务，需要设置环境变量：

一键设置 Claude Code 环境变量

输入命令：

curl -fsSL https://raw.githubusercontent.com/QuantumNous/new-api-docs/refs/heads/main/helper/claude-cli-setup.sh | bash

验证 Claude Code 安装

安装完成后，输入以下命令检查是否安装成功：

claude --version

如果显示版本号，恭喜你！Claude Code 已经成功安装了。

3.开始使用 Claude Code

现在你可以开始使用 Claude Code 了！

启动 Claude Code

直接启动 Claude Code：

claude

在特定项目中使用：

# 进入你的项目目录
cd /path/to/your/project

# 启动 Claude Code
claude

选择模型 (可选)

输入命令：

/model

按 Enter 进入，选择官方模型，通常使用默认模型即可。

> 注意：设置环境变量修改 ANTHROPIC_BASE_URL 后，使用所有模型（包括官方预设模型）均调用自定义接入点，而不使用官方账号额度。

4.macOS 常见问题解决

macOS 安全设置阻止运行

如果系统阻止运行 Claude Code：

打开"系统偏好设置" → "安全性与隐私"
点击"仍要打开"或"允许"
或者在 Terminal 中运行：sudo spctl --master-disable

Linux 端图文指引

1.安装 Claude Code

安装 Claude Code

打开终端，运行以下命令：

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

如果遇到权限问题，可以使用 sudo：

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

验证 Claude Code 安装

安装完成后，输入以下命令检查是否安装成功：

claude --version

如果显示版本号，恭喜你！Claude Code 已经成功安装了。

2.设置环境变量

为了让 Claude Code 连接到你的中转服务，需要设置两个环境变量：

一键修改环境变量

输入命令：

curl -fsSL https://raw.githubusercontent.com/QuantumNous/new-api-docs/refs/heads/main/helper/claude-cli-setup.sh | bash

3.开始使用 Claude Code

现在你可以开始使用 Claude Code 了！

启动 Claude Code

直接启动 Claude Code：

claude

在特定项目中使用：

# 进入你的项目目录
cd /path/to/your/project

# 启动 Claude Code
claude

选择模型

输入命令：

/model

按 Enter 进入，选择官方模型，通常使用默认模型即可。

> 注意：设置环境变量修改 ANTHROPIC_BASE_URL 后，使用所有模型（包括官方预设模型）均调用自定义接入点，而不使用官方账号额度。

4.Linux 常见问题解决

缺少依赖库

某些 Linux 发行版需要安装额外依赖：

# Ubuntu/Debian
sudo apt install build-essential

# CentOS/RHEL
sudo dnf groupinstall "Development Tools"

环境变量不生效

检查以下几点：

确认修改了正确的配置文件（.bashrc 或 .zshrc）
重新启动终端或运行 source ~/.bashrc
验证设置：echo $ANTHROPIC_BASE_URL

接入检查

API 地址填写青云 TOP API 的 Base URL：https://top.qingyuntop.ai/v1；应用若要求不带 /v1 的站点地址，请按页面说明填写对应格式。
API Key 只使用环境变量 $QINGYUN_TOP_API_KEY 或应用的安全密钥存储，不要把真实密钥提交到代码仓库。
模型名称必须与控制台可用模型完全一致；遇到 401/403 检查密钥、分组和模型权限，遇到 404 检查 Base URL 是否重复填写 /v1。

CherryStudio 配置 Claude Code、Gemini CLI、OpenCode（融合自原文档）

客户端下载地址: https://www.cherry-ai.com/
请保证你是最新版本,老版本不兼容

1、安装后，在设置-模型服务-New api：按下图设置你的密匙、API地址、添加最新模型。
API地址为：https://top.qingyuntop.ai/dashboard/

CherryStudio 配置 Claude Code、Gemini CLI、OpenCode 配置步骤图 1

2、选择code工具

CherryStudio 配置 Claude Code、Gemini CLI、OpenCode 配置步骤图 2

3、选择你需要的编程工具以及模型，点击启动，就可以愉快的编程了

CherryStudio 配置 Claude Code、Gemini CLI、OpenCode 配置步骤图 3

接入检查

API Key 使用 $QINGYUN_TOP_API_KEY 占位符保存，不要直接粘贴到公开代码或截图。
OpenAI 兼容客户端通常使用 https://top.qingyuntop.ai/v1；如果客户端要求完整接口路径，再按其界面说明追加路径，避免重复填写 /v1。
先用客户端的“测试连接”或发送一条短消息验证，再到控制台调用日志核对模型和状态。

Claude Code 安装与使用（融合自原文档）

Claude Code 是一个强大的 AI 编程助手，让您可以直接在终端中与 AI 协作编程。本教程将指导您完成安装和配置过程。

📋 系统要求

Node.js 版本 ≥ 18.0

支持的操作系统：macOS、Linux、Windows (WSL)

🚀 快速开始

1\. 安装 Node.js

> 💡 提示：如果您已经安装了 Node.js 18.0 或更高版本，可以跳过此步骤。

Ubuntu / Debian 用户

macOS 用户

2\. 安装 Claude Code

使用 npm 全局安装 Claude Code：

3\. 配置并开始使用

获取必要的配置信息

您需要准备两个重要的配置项：

配置项

说明

获取方式

ANTHROPIC\_AUTH\_TOKEN

API 认证令牌

注册后在 API令牌 页面点击 添加令牌 获得（以 sk- 开头）

ANTHROPIC\_BASE\_URL

API 服务地址

使用 https://top.qingyuntop.ai/dashboard/（与主站地址相同）

> 📝 创建令牌时的建议设置：
>
> 名称：随意命名
>
> 额度：设为无限额度
>
> 分组：选择Claude code专属或者官转克劳德3及以上
>
> 其他选项：保持默认设置

启动 Claude Code

在您的项目目录下运行：

初次运行配置

启动后，您将看到以下配置步骤：

选择主题 → 选择您喜欢的主题 + 按 Enter

安全须知 → 确认安全须知 + 按 Enter

Terminal 配置 → 使用默认配置 + 按 Enter

工作目录信任 → 信任当前目录 + 按 Enter

✨ 恭喜！ 现在您可以开始与您的 AI 编程搭档一起写代码了！

❓ 常见问题解答

A: 这表明 Claude Code 未检测到环境变量。请检查：

是否正确设置了 ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_BASE_URL

环境变量值是否正确（令牌以 sk- 开头）

如果使用了永久配置，是否重启了终端

Q: 为什么显示 "offline" 状态？

A: Claude Code 通过连接 Google 来判断网络状态。显示 "offline" 不影响正常使用，只是表明无法连接到 Google。

Q: 为什么浏览网页的 Fetch 会失败？

A: Claude Code 在访问网页前需要调用 Claude 服务进行安全检查。您需要：

保持稳定的国际互联网连接

必要时使用全局代理

Q: 请求总是显示 "fetch failed"？

A: 可能是网络环境导致的问题。解决方案：

尝试使用代理工具

Q: API 报错如何处理？

A: 可能是转发代理不稳定导致的，建议：

退出 Claude Code（Ctrl+C）

重新运行 claude 命令

如果问题持续，请稍后再试

Q: 网页登录错误？

A: 尝试清除本站的 Cookie，然后重新登录。

📌 注意事项

本站直接接入官方 Claude Code 转发服务

仅支持 Claude Code 的 API 流量，不支持其他 API 调用

请妥善保管您的 API 令牌，避免泄露

🔗 相关链接

Claude Code 官方文档

Node.js 官方网站

💡 提示：如遇到其他问题，请查看官方文档或联系技术支持。

接入检查

API Key 使用 $QINGYUN_TOP_API_KEY 占位符保存，不要直接粘贴到公开代码或截图。
OpenAI 兼容客户端通常使用 https://top.qingyuntop.ai/v1；如果客户端要求完整接口路径，再按其界面说明追加路径，避免重复填写 /v1。
先用客户端的“测试连接”或发送一条短消息验证，再到控制台调用日志核对模型和状态。

CC Switch 配置 Claude Code（融合自原文档）

开始前完成通用备份，并在青云TOP API 模型列表中确认目标模型支持 Anthropic Messages 协议。

添加 Provider

打开已安装的 CC Switch，确认初始 Provider 页面能正常显示。
在顶部应用切换栏选择 Claude Code，不要停留在 Claude Desktop。

点击右上角 +，选择“自定义配置”。

在青云TOP API 创建适用于 Anthropic Messages 的专用令牌并复制；不要使用账号访问令牌。

![青云TOP API API 密钥页面中的创建 API 密钥按钮](https://docs.qingyuntop.ai/images/青云TOP API-api-key-create.png) 在创建表单中填写名称并选择能访问目标 Anthropic 模型的分组；下面截图中的 auto 仅展示表单位置，实际分组以当前模型列表和账户权限为准。 ![青云TOP API 创建 API 密钥表单中的名称与分组设置](https://docs.qingyuntop.ai/images/青云TOP API-api-key-form.png)

名称填写 青云TOP API，API Key 填写模型令牌；请求地址填写 https://top.qingyuntop.ai/dashboard/，亚太地区填写 https://top.qingyuntop.ai/dashboard/。不要追加 /v1 或 /v1/messages。

!CC Switch 中青云TOP API Provider 的名称、官网、已打码 API Key 和请求地址配置 API Key 会显示为圆点；确认截图或录屏中没有展开明文。继续向下检查请求地址： !CC Switch 中青云TOP API Claude API 请求地址为 https://top.qingyuntop.ai/dashboard/

没有合并需求时关闭“应用通用配置”，点击“添加”，确认返回 Provider 列表并出现青云TOP API 卡片。
点击卡片右侧“启用”，确认显示“使用中”。

打开“设置 → 通用”，开启“跳过 Claude Code 初次安装确认”。

完全退出并重新打开终端；下面以 Ghostty 为例启动 Claude Code。

在 Ghostty 中启动

claude --version
claude

下面是在 Ghostty 中实际启动 Claude Code 后的界面。顶部应显示 Claude Code 版本、当前模型和工作目录；不应再跳转到官方登录页。 !在 Ghostty 中启动由 CC Switch 配置的 Claude Code 在 Claude Code 输入框发送一条短消息，并在青云TOP API 控制台日志中核对模型、状态和请求时间。若需要固定模型，在 Claude Code 配置中使用青云TOP API 实际返回的 Anthropic 模型 ID，不要照抄截图中的示例模型。

独立接口检查

curl "https://top.qingyuntop.ai/v1/messages" \
  -H "Authorization: Bearer $QINGYUN_TOP_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"your-anthropic-model","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

排错

仍出现官方登录：核对“跳过初次安装确认”、Provider 启用状态和 ANTHROPIC_BASE_URL 的实际来源。
CC Switch 自检失败：某些令牌分组可能限制第三方探测；不能据此断定 Claude Code 对话失败。
对话使用错误模型：核对令牌可见模型与 CC Switch 的主模型/快速模型映射。
切换后无变化：完全退出 Claude Code，而不是只关闭当前窗口。

DeepSeek 接入 Claude Code（融合自原文档）

准备令牌和模型

在青云TOP API 控制台创建专用令牌。
选择包含目标 DeepSeek 模型的分组。
请求 /v1/models，确认模型 ID 与 Anthropic 能力。

curl "https://top.qingyuntop.ai/v1/models" \
  -H "Authorization: Bearer $QINGYUN_TOP_API_KEY"

使用 CC Switch

打开 CC Switch 的 Claude Code 分支并新增 Provider。
Provider 名称填写 青云TOP API DeepSeek。
请求地址填写 https://top.qingyuntop.ai/dashboard/。
API Key 填专用令牌。
主模型、Thinking、Sonnet、Opus、Haiku 映射都使用 /v1/models 返回的准确 ID；不照抄任何示例模型。
保存、启用并完全重启 Claude Code。

手动配置（Windows/macOS）

如果不使用 CC Switch，使用 Claude Code 当前版本支持的环境变量或 settings.json 配置，保持 Anthropic Base URL 为域名根目录：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://top.qingyuntop.ai/dashboard/",
    "ANTHROPIC_API_KEY": "sk-...",
    "ANTHROPIC_MODEL": "your-anthropic-model"
  }
}

验证

在 Claude Code 发送一条短消息，确认左侧模型名称、返回内容和青云TOP API 用量记录都符合预期。配置页显示 Provider 已保存，不能代替这一步。

ChatGPT 接入 Claude Code（融合自原文档）

这是协议转换流程：Claude Code 使用 Anthropic Messages，路由器把请求转换为青云TOP API 支持的协议。配置完成后，必须在 Claude Code 中收到回复，并在青云TOP API 控制台核对对应请求。

准备

创建专用青云TOP API 令牌，并确保分组允许目标模型。
用 /v1/models 选择一个支持目标协议的模型。
安装并确认 Claude Code 与本地路由工具版本。
备份 Claude Code 配置和环境变量。

创建路由 Provider

在 CC Switch 的 Claude Code 分支点击新增供应商。
选择自定义 Provider。
使用青云TOP API 站点 https://top.qingyuntop.ai/dashboard/、专用令牌和准确模型 ID。
在路由设置中只启用 Claude Code，避免其他客户端配置被同时修改。
完全退出并重新打开 CC Switch 和 Claude Code。

验证顺序

查看 Claude Code 当前环境变量，确认 Base URL 指向本地路由而不是旧地址。
启动 claude，发送一句短消息。
检查 Claude Code 是否返回内容。
查看本地路由日志，确认协议转换和目标模型。
最后查看青云TOP API 侧请求/用量记录，确认调用命中了预期分组。

Claude Code 常见问题（融合自原文档）

Claude Code 的配置字段会随版本变化。先运行 claude --version 和 claude --help 核对本机版本；模型 ID、分组、价格和协议能力以青云TOP API 控制台及实际请求为准。

为什么消费日志里出现了另一个模型？

Claude Code 的主会话、子 Agent、标题生成、压缩和快速任务可能使用不同模型。先按请求时间、模型 ID、输入/输出令牌和请求 ID 对照消费日志，不要只看当前界面选择的主模型。

少量、紧邻主请求的调用通常来自辅助任务。
持续出现大量未知调用时，立即停用对应令牌，检查本机进程与令牌使用范围。
创建 Claude Code 专用令牌，能把客户端流量与其他应用分开审计。
联系支持时提供请求 ID、时间范围和模型 ID；不要发送完整 API Key。

首次启动提示无法连接 Anthropic

先在同一个终端检查环境变量，不要直接修改 ~/.claude.json 绕过首次启动状态：

test -n "$ANTHROPIC_API_KEY" && echo "API key is set"
printf '%s\n' "$ANTHROPIC_BASE_URL"
claude --version

青云TOP API 的 Anthropic Base URL 使用域名根目录，Claude Code 会自行追加 /v1/messages：

export ANTHROPIC_BASE_URL="https://top.qingyuntop.ai/dashboard/"
export ANTHROPIC_API_KEY="sk-..."
claude

亚太地区将域名替换为 https://top.qingyuntop.ai/dashboard/。不要填写 /v1、/v1/messages，否则可能形成重复路径。

如何做最小连通性验证？

先查询模型，再向 Messages API 发送短请求：

curl "https://top.qingyuntop.ai/v1/models" \
  -H "Authorization: Bearer $ANTHROPIC_API_KEY"

curl "https://top.qingyuntop.ai/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "your-anthropic-model",
    "max_tokens": 64,
    "messages": [{"role": "user", "content": "Reply with OK"}]
  }'

只有模型端点存在、令牌分组可见并且 /v1/messages 返回内容后，才继续排查 Claude Code 本身。

常用命令

claude                              # 在当前目录启动交互会话
claude "解释这个项目"              # 带首条消息启动
claude -p "解释这个函数"           # 一次性输出后退出
cat build.log | claude -p "定位错误" # 通过标准输入分析文本
claude -c                           # 继续当前目录最近的会话
claude -r <session-id>              # 恢复指定会话
claude --model <model-id>           # 指定本次会话模型
claude --add-dir ../shared          # 增加允许访问的目录
claude mcp                          # 管理 MCP
claude doctor                       # 检查本地安装和设置
claude update                       # 更新客户端

--dangerously-skip-permissions 会绕过工具权限确认。仅能在没有真实凭据、没有重要文件且网络受控的临时沙箱中使用；普通接入教程不需要它。

VS Code 中的 Claude Code 扩展怎么接入？

先在 VS Code 集成终端中运行 claude --version。
在该终端确认 ANTHROPIC_BASE_URL 和 ANTHROPIC_API_KEY 已注入。
用 CLI 完成最小请求，排除网络、令牌和模型问题。
完全退出并重启 VS Code，让扩展重新读取环境。
如果扩展仍固定使用官方账号登录，不要把青云TOP API API Key 填入 OAuth 登录框；改用 CLI 或 CC Switch 支持的配置入口。

扩展版本的配置字段可能独立于 CLI。不要写入来源不明的 primaryApiKey 固定字符串，也不要覆盖现有官方登录状态。

Windows 与 macOS 到哪里检查配置？

Windows

macOS / Linux

使用 PowerShell 检查 $HOME\.claude\settings.json。修改前复制备份，并完全退出 Claude Code 与 VS Code。

检查 ~/.claude/settings.json，并用 env | grep -E '^(ANTHROPIC|CLAUDE_CODE)_' 排查 shell 环境覆盖。

如何限制上下文和非必要流量？

Claude Code 2.1.227 的本机程序包含以下开关。它们会改变客户端行为，按需逐项启用，不要一次复制整组不熟悉的配置：

{
  "env": {
    "CLAUDE_CODE_DISABLE_1M_CONTEXT": "1",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "CLAUDE_CODE_DISABLE_TERMINAL_TITLE": "1",
    "CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS": "1"
  }
}

将它们合并进 ~/.claude/settings.json 的现有 env 对象，不能覆盖已有青云TOP API 地址、令牌或其他用户设置。修改前备份并记录校验和：

cp -p ~/.claude/settings.json ~/.claude/settings.json.bak
shasum -a 256 ~/.claude/settings.json ~/.claude/settings.json.bak

CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS 会减少自动注入的动态 Git 信息，但也会丢失相关上下文；只有确认任务不依赖 Git 状态时再启用。

401、403、404 怎么排查？

401：令牌缺失、无效或同时存在冲突的凭据变量。重新打开终端并检查注入来源。
403：令牌分组无权访问模型、余额不足或策略拒绝。查看完整错误消息和消费日志。
404：Base URL 多写了 /v1、模型 ID 不存在，或模型不支持 Anthropic Messages 协议。
429：命中速率或并发限制。使用退避重试，不要并行重复提交相同任务。
5xx：记录请求 ID 后重试一次；持续失败再联系支持。

CC Switch 和手工环境变量冲突怎么办？

完全退出 Claude Code。
关闭 CC Switch 对 Claude Code 的接管。
在新终端运行 env | grep -E '^(ANTHROPIC|CLAUDE_CODE)_'。
检查 shell 配置中的重复 export、别名和包装器。
选择一种配置来源，再重新启动 Claude Code。

不要在 CC Switch 接管期间手工覆盖同一个配置文件。恢复备份前先确认接管已经关闭。

仍然失败时需要保存什么？

保存 claude --version、HTTP 状态、错误正文、请求 ID、模型 ID、令牌分组和发生时间。环境变量只记录“已设置/未设置”，API Key 只保留前后少量字符并打码。

统一接入检查与故障排查

401/403：确认 API Key 未过期、令牌分组允许目标模型，且没有把示例占位符原样提交。
404：核对应用要求的 Base URL 形式；https://top.qingyuntop.ai/dashboard/、https://top.qingyuntop.ai/v1 和完整路径不能重复拼接。
模型为空或不可用：调用 GET /v1/models，复制返回的完整模型 ID，并确认应用使用的协议（OpenAI Chat Completions、Responses 或 Anthropic Messages）。
切换 Provider 后仍访问旧地址：完全退出并重启客户端，检查环境变量、代理和 CC Switch 路由是否覆盖了新配置。
生产环境安全：不要把真实密钥放进前端代码、截图、公开仓库、Deep Link 或工作流导出文件；先用低额度测试令牌验证。

> 本页保留每个来源教程的具体字段、命令、截图和高级选项；重复的 API Key、Base URL 和验证说明已统一到本页开头与本节。

发布前检查

以下检查适用于客户端中选择 OpenAI 兼容 或 Responses 提供商的场景；如果你选择的是 Anthropic、Gemini 等原生协议，请按对应协议的接口和返回结构配置。

模型 ID：先用目标 API Key 请求 GET https://top.qingyuntop.ai/v1/models，把返回的 data[].id 原样填入客户端。截图、教程和历史配置中的模型名不保证仍可用。
协议选择：新 OpenAI 集成优先选择 Responses；只有客户端或模型明确要求 Chat Completions 时才选择 Chat。Responses 的返回从 output 读取，Chat 的返回从 choices[].message 读取。
Base URL：通常填写 https://top.qingyuntop.ai/v1，也就是只保留一个 /v1。要求完整接口地址的客户端才追加 /responses 或 /chat/completions，不要重复追加。
流式与重试：流式响应必须按所选协议解析事件；连接中断后不要盲目重放可能已被服务端接受的生成请求。对 429 和 5xx 使用带抖动的退避，并设置连接、读取和总超时。
上线前验证：分别验证普通文本、流式文本、工具调用或结构化输出中实际用到的能力，并记录 request id、HTTP 状态、业务状态和完成原因，避免只根据 HTTP 200 判定成功。

快速判断：我应该看哪一段？

Claude Code（融合自原文档）

效果演示

特性

AI 模型配置方法

Windows 端图文指引

1.安装 Node.js 环境

2.安装 Git Bash

3.安装 Claude Code

4.设置环境变量

5.开始使用 Claude Code

MacOS 端图文指引

1.安装 Claude Code CLI

2.设置环境变量

3.开始使用 Claude Code

4.macOS 常见问题解决

Linux 端图文指引

1.安装 Claude Code

2.设置环境变量

3.开始使用 Claude Code

4.Linux 常见问题解决

接入检查

CherryStudio 配置 Claude Code、Gemini CLI、OpenCode（融合自原文档）

接入检查

Claude Code 安装与使用（融合自原文档）

📋 系统要求

🚀 快速开始

1\. 安装 Node.js

Ubuntu / Debian 用户

macOS 用户

2\. 安装 Claude Code

3\. 配置并开始使用

获取必要的配置信息

启动 Claude Code

初次运行配置

❓ 常见问题解答

Q: 遇到 "Invalid API Key · Please run /login" 错误？

Q: 为什么显示 "offline" 状态？

Q: 为什么浏览网页的 Fetch 会失败？

Q: 请求总是显示 "fetch failed"？

Q: API 报错如何处理？

Q: 网页登录错误？

📌 注意事项

🔗 相关链接

接入检查

CC Switch 配置 Claude Code（融合自原文档）

DeepSeek 接入 Claude Code（融合自原文档）

ChatGPT 接入 Claude Code（融合自原文档）

Claude Code 常见问题（融合自原文档）

统一接入检查与故障排查

发布前检查