新用户使用引导手册

这是一份"按顺序看完就能上手"的手册。如果你是第一次接触喜云（claudeapi.com），从第一章开始读；如果你已经注册过，跳到对应章节即可。

每个小节都附带了官网已发布的详细教程链接，本手册只讲流程主线，深入细节直接点链接。

一、新用户先看这里

1. 如何注册账号

打开 https://claudeapi.com → 右上角"注册" → 邮箱 + 密码 → 邮箱收到验证邮件后点击激活 → 自动进入控制台 https://console.claudeapi.com。

注册过程没有手机号强制要求，邮箱可达即可。注册完成后系统会自动赠送测试额度，无需单独申请。

📖 详细图文步骤：喜云注册流程与新用户赠送额度详解

2. 如何申请测试额度

注册成功的账号会自动获得新用户赠送额度，进入控制台 https://console.claudeapi.com 首页即可在"账户余额"卡片看到。

赠送额度可用于：

• 调用 Claude Opus 4.7 / Sonnet 4.6 / Haiku 4.5 任意模型
• 在 Claude Code、Cherry Studio、自己写的脚本里测试连通性
• 验证 base_url 与 Key 是否配置正确

📖 额度规则与到账时间：新用户赠送额度领取与使用规则

3. 如何充值

登录控制台 → 左侧菜单"钱包" → 选择充值金额 → 按页面提示完成支付 → 余额实时到账。

充值后的余额按调用消耗扣费，模型按官网定价计费。完整价格表与模型适用场景见下方教程。其他支付方式可以联系客服。

📖 价格与计费规则详解：

• Claude API 价格指南（2026 最新版）
• Claude API 定价完整指南
• Prompt Caching 省钱机制详解

4. 如何创建 API Key

控制台 → 左侧菜单 “API密钥” → 点击"创建新 Key" → 给 Key 取个识别名（如 claude-code-mac、cherry-studio-home）→ 点确认 → 页面会显示完整的 Key，仅此一次，立刻复制保存。

📖 详细 Key 管理流程：国内如何获取并管理 Claude API Key

5. 遇到问题时需要提供哪些信息

向客服反馈或在工单提问时，附上以下信息能让排查至少快 5 倍：

📖 自助排查手册（先看再开工单）：

• 喜云 API 接入排错完整指南
• Claude API 常见错误码逐条解读

二、我是小白，应该用什么工具？

不同需求对应不同工具，先对号入座再去看教程：

1. 写作 / 编剧 / 文案

最简单的入门方式是装一个桌面客户端，配上 base_url 与 Key 就能用。

📖 推荐教程：

• Chatbox 与 Cherry Studio 配置 Claude API 全流程
• Claude Desktop 接入第三方 API（喜云）
• 2026 最佳 Claude AI 客户端横评

2. 分析对话 / 文档总结

涉及 PDF、长文档、结构化输出时，建议直接用 API（脚本几行就能跑）。

📖 推荐教程：

• Claude API PDF 文档问答完整指南
• Claude Files API 深度解析
• 结构化输出（JSON Schema）实战 2026
• Claude API 自动生成周报

3. 写代码 / 编程辅助：Claude Code + cc-switch

Claude Code 是 Anthropic 官方 CLI 编程助手，配合 cc-switch 可以一键切换喜云接入。这套组合是目前最丝滑的工作流。

📖 推荐教程：

• Claude Code + cc-switch 完整教程
• cc-switch 新手入门指南
• Claude Code 国内配置流程

4. 桌面客户端使用

Cherry Studio 是中文用户最常用的 GUI 客户端，支持多模型、对话历史、知识库、绘图等。

📖 推荐教程：Chatbox 与 Cherry Studio 配置 Claude API 全流程

5. VSCode 插件使用：Cline / Continue

在 VSCode/IntelliJ 里直接用 Claude 对话、补全、改代码。

📖 推荐教程：

• Claude Code / Cline / Cursor 喜云配置指南
• IntelliJ IDEA + Continue 插件接入 Claude API
• Cursor / Roo Code 接入 Claude API
• Trae IDE 接入 Claude API

三、Claude Code 使用指南

Claude Code 是 Anthropic 推出的 CLI 编程助手，运行在本地终端，能直接读写你的项目文件。

1. 是否需要注册 Claude 官方账号？

不需要。

通过喜云接入时，你只需要：

• ✅ 一个喜云账号（claudeapi.com 注册）
• ✅ 一把 sk- 开头的 API Key
• ✅ base_url：https://gw.claudeapi.com

不需要 Anthropic 官方账号、不需要绑定信用卡、不需要切换网络环境。喜云接口兼容 Anthropic SDK 标准格式，Claude Code 客户端原生支持。

📖 账号风险与数据保护说明：

• Claude 账号风险与避坑指南
• 账号封禁解决方案

2. 为什么推荐安装 cc-switch？

Claude Code 默认指向 Anthropic 官方端点。要切到喜云，需要修改环境变量。手动切换的痛点：

• 多个项目要切来切去，手动改 ~/.zshrc 容易乱
• 想临时用一下不同的 Key（公司 Key vs 个人 Key），切换繁琐
• 不同机器（Mac / Windows / Linux）配置语法不一样

cc-switch 把这些都封装成 GUI 一键切换：选好"喜云"线路，启动 Claude Code 即可。

📖 详解：cc-switch 新手入门指南

3. cc-switch 下载和安装

完整步骤（Mac / Windows 都有）：

📖 Claude Code + cc-switch 完整教程

简要说明：

1. 从 cc-switch 项目页下载对应平台安装包
2. 安装并启动
3. 在"线路管理"里添加喜云线路：
   • 名称：claudeapi
   • Base URL：https://gw.claudeapi.com
   • API Key：你在控制台创建的 sk- Key
4. 选中喜云线路 → 点"启动 Claude Code"

4. 线路应该怎么选？

cc-switch 里通常会预置多条线路，按以下原则选：

📖 接入配置详解：Claude Code 国内配置流程

5. API Key / Base URL 如何配置

cc-switch GUI 已封装大部分操作。如果不用 cc-switch、想直接在终端配置：

# Mac / Linux：写入 ~/.zshrc 或 ~/.bashrc
export ANTHROPIC_BASE_URL="https://gw.claudeapi.com"
export ANTHROPIC_API_KEY="sk-你的Key"

# Windows PowerShell（临时）
$env:ANTHROPIC_BASE_URL = "https://gw.claudeapi.com"
$env:ANTHROPIC_API_KEY = "sk-你的Key"

# Mac / Linux：写入 ~/.zshrc 或 ~/.bashrc
export ANTHROPIC_BASE_URL="https://gw.claudeapi.com"
export ANTHROPIC_API_KEY="sk-你的Key"

# Windows PowerShell（临时）
$env:ANTHROPIC_BASE_URL = "https://gw.claudeapi.com"
$env:ANTHROPIC_API_KEY = "sk-你的Key"

写入后重启终端，运行 claude 即可。

📖 Claude Code 国内配置流程

6. 常见报错自查

📖 详细排查：

• Claude API 接入排错完整指南
• Claude API 常见错误码解读

7. 为什么 cc-switch 里面不能查询余额？

cc-switch 是一个纯本地的线路与 Key 管理工具，它只负责帮你切换 base_url 和 API Key，不会向喜云服务器查询账户数据。

要查余额请到喜云官方控制台：

• 控制台首页：https://console.claudeapi.com
• 余额、用量、账单、Key 列表都在控制台内

把"查询余额"这件事独立到控制台，好处是 cc-switch 不需要任何额外授权或 Token，更轻量、更安全。

四、Cherry Studio 使用指南

Cherry Studio 是一款开源跨平台 AI 客户端，对国内用户友好，支持多模型、知识库、对话备份。

1. Base URL 填哪里

打开 Cherry Studio → 设置（左下齿轮）→ 模型服务 → 找到 “Anthropic” 或点击"添加自定义服务"：

如果你的 Cherry Studio 版本要求 OpenAI 兼容路径，则填 https://gw.claudeapi.com/v1，并把 API 类型改成 OpenAI 兼容。

2. API Key 填哪里

同一页面 → “API 密钥” 字段 → 粘贴你在控制台创建的 sk- 开头的完整 Key → 保存。

填好后点"检查"按钮，返回成功即可。

3. 模型怎么选择

回到对话界面 → 顶部模型下拉 → 选择以下模型（任选）：

如果下拉里没有这些模型 ID，去模型设置页"自定义模型"里手动添加即可。

4. 测试连接失败怎么办

按以下顺序排查：

1. Key 是否带空格：粘贴时容易尾部多空格，重新复制一次
2. Base URL 是不是 /v1：Anthropic 类型不要加 /v1，OpenAI 兼容类型必须加 /v1
3. 网络层：浏览器能否打开 https://gw.claudeapi.com（应该返回一段 JSON 提示）
4. 余额：控制台看余额是否为 0
5. 模型 ID：拼写是否与第 2 节固定模型表一致

📖 详细图文：Chatbox 与 Cherry Studio 配置 Claude API 全流程

5. 常见报错截图说明

五、API 接入指南

1. 我是开发者，如何接入 API

喜云完全兼容 Anthropic SDK 标准格式，已有 Anthropic 项目只需替换 base_url 与 API Key即可迁移过来，业务代码无需修改。

📖 完整 Python 教程：Claude API Python 接入完整教程

2. Base URL、API Key、模型名说明

3. cURL 示例

curl https://gw.claudeapi.com/v1/messages \
  -H "x-api-key: sk-你的Key" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "用一句话介绍你自己"}
    ]
  }'

curl https://gw.claudeapi.com/v1/messages \
  -H "x-api-key: sk-你的Key" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "用一句话介绍你自己"}
    ]
  }'

4. Python 示例

from anthropic import Anthropic

client = Anthropic(
    base_url="https://gw.claudeapi.com",
    api_key="sk-你的Key",
)

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "用一句话介绍你自己"},
    ],
)

print(response.content[0].text)

from anthropic import Anthropic

client = Anthropic(
    base_url="https://gw.claudeapi.com",
    api_key="sk-你的Key",
)

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "用一句话介绍你自己"},
    ],
)

print(response.content[0].text)

启用 Prompt Caching 可大幅省钱：

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "<这里放长系统提示或长文档，至少 1024 tokens>",
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": "总结要点"}],
)

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "<这里放长系统提示或长文档，至少 1024 tokens>",
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": "总结要点"}],
)

📖 进阶用法：

• Claude API 流式 SSE 完整指南
• Claude API Tool Use 工具调用指南
• Claude Batch API 成本优化

5. Node.js 示例

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://gw.claudeapi.com",
  apiKey: "sk-你的Key",
});

const msg = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [
    { role: "user", content: "用一句话介绍你自己" },
  ],
});

console.log(msg.content[0].text);

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://gw.claudeapi.com",
  apiKey: "sk-你的Key",
});

const msg = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [
    { role: "user", content: "用一句话介绍你自己" },
  ],
});

console.log(msg.content[0].text);

6. OpenAI-compatible 接入说明

如果你的项目已经在用 OpenAI SDK（如 Dify、LangChain、自家工具），可以直接用 OpenAI 兼容路径接入：

from openai import OpenAI

client = OpenAI(
    base_url="https://gw.claudeapi.com/v1",
    api_key="sk-你的Key",
)

response = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "你好"}],
)

print(response.choices[0].message.content)

from openai import OpenAI

client = OpenAI(
    base_url="https://gw.claudeapi.com/v1",
    api_key="sk-你的Key",
)

response = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "你好"}],
)

print(response.choices[0].message.content)

注意：OpenAI 兼容路径必须加 /v1，Anthropic 原生路径不加 /v1。

📖 框架集成：

• LangChain + Claude API 实战
• Dify 接入喜云完整指南

六、常见问题 FAQ

1. 会不会封号？

通过喜云接入是调用 API，不是登录 Anthropic 官方账号。所以"Anthropic 账号封禁"这件事与喜云用户无关——你根本没有 Anthropic 账号需要被封。

但如果你同时也在使用 Anthropic 官方账号（例如订阅了官方 Claude Pro），那是另一回事，与喜云无关。

📖 相关阅读：

• Claude 账号封禁风险与原因
• Claude 账号被封解决方案
• 账号封禁后的数据保护指南

2. 中转服务和官方直连有什么区别？

喜云提供工程化的接入与用量管理服务：账单清晰、用量透明、成本可追踪、企业结算支持，并兼容 Anthropic SDK 格式，让团队能更高效地集成 Claude 能力。

📖 接口真实性自检方法：如何验证 Claude API 真实性（指纹检测）

3. token 为什么消耗这么快？

常见原因：

📖 省钱实战：Claude API Prompt Caching 完整指南

4. 为什么提示余额不足？

控制台首页查看实际余额；如果显示 ≤ 0，到"钱包"补上；若刚充值还显示不足，刷新一下控制台或等几秒。

如果余额还有但提示不足，多半是 Key 关联的子账户额度限制，详情看控制台或联系客服。

5. 为什么提示模型是老版本？

Anthropic 模型版本号经常更新。目前喜云支持的最新与推荐模型：

如果客户端显示的是 claude-3-5-sonnet 等老版本，说明客户端模型列表过时，到设置里手动加上新模型 ID 即可。

📖 模型对比与选型：

• Claude Opus 4.7 / Opus 4.6 / Sonnet 4.6 全面对比
• Claude Opus 4.7 发布要点

6. 为什么官网打不开？

按顺序自查：

1. 浏览器换一个（Edge / Chrome / Safari 都试）
2. 用手机流量打开 https://claudeapi.com 验证
3. 清浏览器缓存或开无痕窗口
4. 试试备用域名（在客服渠道获取最新备用入口）
5. 仍不行，联系客服反馈所在地区与运营商，会派备用线路

API 接口（https://gw.claudeapi.com）与官网（https://claudeapi.com）是独立链路，官网偶尔抖动不影响 API 调用。

7. 充值后多久到账？

正常情况下实时到账，刷新一下控制台余额即可看到。极少数情况（支付通道延迟）会在数分钟内到账。如超过 10 分钟仍未到账，带订单号联系客服。

七、按经验排序的下一步推荐阅读

如果你已经走完上面所有章节，下面是按"用户成长路径"排好序的进阶读物：

1. 想把成本打下来 → Prompt Caching 完整指南 + Batch API 成本优化
2. 想做企业知识库 → Claude API RAG 知识库企业指南
3. 想做图片/PDF 理解 → Vision API 图像识别指南 + PDF 文档问答指南
4. 想做 Agent 工作流 → Claude Code Agent Skills 快速入门 + MCP Server CSV 教程
5. 想做企业级工具 → Memory Tool 指南 + Tool Use 完整指南
6. 想接到企业微信/钉钉/飞书 → Claude API 接入企业 IM 机器人教程

八、获取帮助

本手册会随产品更新与新教程发布持续修订。建议加入收藏，并定期回看官网博客中心获取最新指南。