V3 Claude Code 安装与配置指南

这篇只适用于 V3 + Claude Code。不要拿这篇配置 Codex，也不要拿这篇配置二合一。

开始前先看：3 步最简路径

不要一打开客户端就找 API Key，按下面顺序做：

1. 兑换（如果还没有兑换）：V3 的兑换码先在 V3 后台兑换；二合一不要去 V3 兑换，订单里的 cr-... 卡密直接作为 API Key。
2. 新建 API Key，并选择分组：V3 打开 https://v3.codesome.cn/dashboard，进入“API 密钥”并创建 sk-... Key；按要使用的模型选择具体分组——Claude 使用 Kiro 来源时选择 lite 或 pro，使用 Max 来源时选择当天后台可用的具体 Max 分组；Codex/GPT 选 codex，Grok 选 grok，月卡选择对应月卡/订阅分组。二合一直接使用 cr-... Key，不在 V3 创建或选择分组。
3. 安装并配置到客户端：先安装 Claude Code，再按本文选择 CC Switch 或手动方式，填入 sk-... Key、请求地址和对应分组，完成后新开窗口验证。

下面展开第 1 步的兑换细节；已经有可用 API Key 的用户可以直接跳到客户端配置部分。

兑换流程：先兑换，再获取 API Key

如果你还没有 API Key，先完成下面的兑换流程。兑换码不是 API Key：V3 兑换码要先兑换，再到“API 密钥”页面创建 sk-... Key；二合一的 cr-... 卡密则直接作为 API Key，不要去 V3 兑换。如果你已经有对应的可用 Key，可直接跳到本文后面的客户端配置步骤。完整兑换说明也可以查看cc兑换码兑换指南。

基本兑换步骤

1、登录 v3.codesome.cn（cc.codesome.ai 是同一个网站，.cn 登录不了就登录.ai）

2、注册后，在兑换区输入兑换码，入口：https://v3.codesome.cn/redeem

3、新人福利 3 美金兑换码可以加微信领取，微信oops0731111（口号：领新人福利）

付款后卡密在哪里

打开下单站点：

https://meta.codesome.cn

使用下单时注册的新站账号登录（新站账号与老站账号不通用），进入订单详情查看并保存卡密。老站已下单但尚未兑换的订单，联系客服处理。

兑换规则：一次一个、只贴纯卡密

• 一次只能输入并兑换一个兑换码，不能一次粘贴多个，也不能粘贴多个码之间加空格或换行。
• 不要使用下单页面带说明文字的一键复制内容，它可能包含“二合一卡密：xxxx”这类中文前缀。输入框里只能是纯卡密，不含中文、空格和换行。
• 页面显示“兑换成功”即表示卡密已生效。

兑换失败怎么排查

提示卡密无效、已使用或兑换失败时，按顺序检查：

1. 确认输入框里只有一个卡密。
2. 清空输入框，重新手动粘贴纯卡密（去掉中文前缀、空格和换行）后再次提交。
3. 确认你买的是 V3 产品（Claude 月卡、GPT 月卡、V3 按量）而不是二合一——二合一的 cr 开头卡密不在本站兑换。

仍失败时联系客服，并提供打码后的页面截图（保留报错信息）和兑换时间；截图请隐藏完整卡密、API Key、邮箱、订单号等身份信息。

兑换成功后在哪里确认到账

• V3 按量：在 V3 后台“余额”处查看。
• Claude 月卡 / GPT 月卡：在 V3 后台“订阅”页面查看。
• 随后进入“API 密钥”页面创建 Key，再按对应客户端教程配置。
• 二合一（V5）：订单里的 cr 开头卡密直接作为 API Key 使用，不会显示在 V3 余额里，也不要到 V3 兑换。

已显示兑换成功但余额或订阅没更新时，先刷新页面；仍无变化再联系客服。

适合谁读

• 你要使用 Claude Code。

• 你买的是 V3 / 普通 Codesome API / V3 月卡或按量。

• 你已经完成兑换，并创建了 V3 API Key。

• 你的 key 常见形态是 sk-...。

不适合谁读

配置前确认

1. 已经在 V3 后台完成兑换。

2. 已经创建 sk-... API Key。

3. API Key 分组选对：月卡选月卡/订阅分组，按量选按量分组。

4. 你正在配置的是 Claude Code，不是 Codex。

5. 如果以前配置过其他 Claude / Anthropic 地址，建议先清理旧环境变量。

切换到 Max 分组后要新开窗口：如果你是从其他分组切换到 Max 分组，请关闭当前 Claude Code 窗口，重新打开一个新窗口再测试。旧窗口可能沿用旧会话或旧进程状态，继续测试容易误以为 Codesome API 出问题。

大扫除：先清理残留配置

重要：如果你以前配置过其他 Claude / Anthropic 地址、其他中转站，或者从别的分组切换过来，先做这一步。很多配置失败不是新 key 有问题，而是旧环境变量还在生效。

下面命令执行时如果出现红字报错，通常说明对应变量本来不存在，可以继续下一步。

Windows 清理环境变量和旧配置

在 PowerShell 里执行，先清理当前用户级环境变量：

$vars = @(
  'ANTHROPIC_BASE_URL',
  'ANTHROPIC_AUTH_TOKEN',
  'ANTHROPIC_MODEL',
  'ANTHROPIC_DEFAULT_OPUS_MODEL',
  'ANTHROPIC_DEFAULT_SONNET_MODEL',
  'ANTHROPIC_DEFAULT_HAIKU_MODEL',
  'CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC',
  'CLAUDE_CODE_SUBAGENT_MODEL',
  'CLAUDE_CODE_EFFORT_LEVEL'
)

foreach ($var in $vars) {
  reg delete HKCU\Environment /V $var /F 2>$null
  Remove-Item "Env:$var" -ErrorAction SilentlyContinue
}

Get-ChildItem Env: |
  Where-Object {
    $_.Name -like 'ANTHROPIC_*' -or
    $_.Name -like 'CLAUDE_CODE_*'
  }

Get-ItemProperty HKCU:\Environment |
  Select-Object *ANTHROPIC*, *CLAUDE_CODE*

如果你以前用管理员权限配置过，还需要用"管理员身份运行"的 PowerShell 清理系统级环境变量：

$machineEnvPath = 'HKLM:\SYSTEM\CurrentControlSet\Control\Session Manager\Environment'

Get-ItemProperty -Path $machineEnvPath |
  Get-Member -MemberType NoteProperty |
  Where-Object {
    $_.Name -like 'ANTHROPIC_*' -or
    $_.Name -like 'CLAUDE_CODE_*'
  } |
  ForEach-Object {
    Remove-ItemProperty -Path $machineEnvPath -Name $_.Name -ErrorAction SilentlyContinue
    Write-Host "Removed machine env:" $_.Name
  }

macOS / Linux 清理环境变量和旧配置

如果你在 macOS、Linux 或 WSL 里配置过 Claude Code，也要清理当前 Session、shell 配置文件和旧的 settings.json。

# 临时清除当前 Session 环境变量
unset ANTHROPIC_BASE_URL
unset ANTHROPIC_AUTH_TOKEN
unset ANTHROPIC_MODEL
unset ANTHROPIC_DEFAULT_OPUS_MODEL
unset ANTHROPIC_DEFAULT_SONNET_MODEL
unset ANTHROPIC_DEFAULT_HAIKU_MODEL
unset CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC
unset CLAUDE_CODE_SUBAGENT_MODEL
unset CLAUDE_CODE_EFFORT_LEVEL
unset OPENAI_API_KEY
unset CODESOME_API_KEY
unset SUB2API_API_KEY
unset http_proxy
unset https_proxy
unset HTTP_PROXY
unset HTTPS_PROXY
unset ALL_PROXY

# 清理 shell 配置文件里的旧变量
cleanup_file() {
  file="$1"
  [ -f "$file" ] || return 0
  tmp="$(mktemp)"
  grep -Ev 'ANTHROPIC|CLAUDE|OPENAI|CODESOME|SUB2API|proxy|PROXY' "$file" > "$tmp"
  cat "$tmp" > "$file"
  rm -f "$tmp"
}

cleanup_file ~/.zshrc
cleanup_file ~/.bashrc
cleanup_file ~/.bash_profile
cleanup_file ~/.profile

# 删除 Claude Code 旧配置文件
rm -f ~/.claude/settings.json

# 重新加载 shell 配置
source ~/.zshrc 2>/dev/null
source ~/.bashrc 2>/dev/null

# 检查是否还有残留
env | grep -E 'ANTHROPIC|CLAUDE|OPENAI|CODESOME|SUB2API|proxy|PROXY'

echo ""
echo "如果没有任何输出，说明环境变量已基本清理完成。"

清理完成后，关闭当前终端，重新打开一个新终端。

V3 Claude Code 核心配置：

ANTHROPIC_BASE_URL=https://cc.codesome.ai
ANTHROPIC_AUTH_TOKEN=你的 sk-... 开头 API Key
CLAUDE_CODE_ATTRIBUTION_HEADER=0

方法 1（推荐）：使用 CC switch 配置

方法 1 是完整的推荐流程：安装 Claude Code CLI 后，再用 CC switch 管理请求地址、API Key 和本地代理配置。CC switch 本身不负责安装 CLI；Windows、macOS 和 Linux 都有当前客户端安装包，请继续完成对应系统的 CLI 安装与验证。

Windows

打开 ccswitch 下载页：https://github.com/farion1231/cc-switch/releases

在页面的 Assets 区域下载 Windows 版本的 .msi 安装包。如果 GitHub 无法打开，在 Codesome 用户群说明"需要 ccswitch 安装包"。

不要从第三方网盘或来路不明的页面下载 ccswitch。

安装完成后打开 ccswitch，新建自定义配置。注意勾选最左侧的 claude 图标（不要选第二个带电脑标志的）。

按下图填写：

• 供应商名称填：codesome-v3

• 请求地址填：https://cc.codesome.ai

• API Key 填你的 sk-... 开头 API Key

如果买的是月卡，记得在后台把这个 API Key 选到月卡/订阅分组。

安装并验证 Claude Code CLI

CC switch 配置完成后，还要安装 claude 命令。已经安装过 Claude Code 的用户可直接执行 claude --version，无需重复安装。

Git for Windows 不是运行官方安装器的硬性前提，没有安装时 Claude Code 可以继续使用 PowerShell。不过仍然推荐安装：Claude Code 和其他 Agent 后续经常需要读取 Git 仓库、查看改动和提交代码，Git 基本属于必装的开发工具，建议现在一并安装：

https://git-scm.com/download/win

打开 PowerShell（不要用 CMD），安装 Claude Code：

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

验证：

claude --version

macOS

打开 ccswitch 下载页：https://github.com/farion1231/cc-switch/releases

在页面的 Assets 区域下载对应系统的安装包：按自己的芯片选择 Apple Silicon 或 Intel 版本的 .dmg 安装包。如果 GitHub 无法打开，在 Codesome 用户群说明"需要 ccswitch 安装包"。

不要从第三方网盘或来路不明的页面下载 ccswitch。

macOS 首次打开如果遇到安全提示，需要在系统设置里允许打开当前开发者。

安装完成后打开 ccswitch，新建自定义配置。注意勾选最左侧的 claude 图标（不要选第二个带电脑标志的）。

按下图填写：

• 供应商名称填：codesome-v3

• 请求地址填：https://cc.codesome.ai

• API Key 填你的 sk-... 开头 API Key

如果买的是月卡，记得在后台把这个 API Key 选到月卡/订阅分组。

安装并验证 Claude Code CLI

CC switch 配置完成后，还要安装 claude 命令。已经安装过 Claude Code 的用户可直接执行 claude --version，无需重复安装。

先安装 Node.js：

https://nodejs.org/en/download

安装完成后，在终端验证：

node -v
npm -v

通过 npm 安装 Claude Code：

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

如果默认 npm 下载慢或无法连接，使用镜像：

npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

不要在 npm 安装命令前加 sudo。遇到权限或路径问题（无法写入 /usr/local）时，先看使用问题速查里的「npm 全局安装权限与路径修复」。

验证：

claude --version

Linux

CC Switch 当前 Release 提供 Linux x86_64/ARM64 的 AppImage、deb 和 rpm。请从 https://github.com/farion1231/cc-switch/releases 下载与你的架构和发行版匹配的安装包，再按本节相同字段创建供应商。

先确认 Node.js 和 npm 已安装：

node -v
npm -v

如果未安装，Ubuntu / Debian 可以执行：

sudo apt update
sudo apt install -y nodejs npm

通过 npm 安装 Claude Code：

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

如果默认 npm 无法连接，使用镜像：

npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

不要使用 sudo npm install -g。遇到权限或路径问题（无法写入 /usr/local）时，先看使用问题速查里的「npm 全局安装权限与路径修复」。安装完成后验证：

claude --version

方法 2：不使用 CC switch，手动安装 CLI 并配置

方法 2 是方法 1 的替代流程，不是方法 1 的必做下一步。如果已经按方法 1 安装并验证过 CLI，不要重复安装；只有在不使用 CC switch 时，才从本节开始手动配置。

Windows

安装 Claude Code CLI

Git for Windows 不是运行官方安装器的硬性前提，没有安装时 Claude Code 可以继续使用 PowerShell。不过仍然推荐安装：Claude Code 和其他 Agent 后续经常需要读取 Git 仓库、查看改动和提交代码，Git 基本属于必装的开发工具，建议现在一并安装：

https://git-scm.com/download/win

安装后可以在 PowerShell 验证；如果暂时不安装，跳过这一步：

git --version

打开 PowerShell（不要用 CMD），安装 Claude Code：

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

验证：

claude --version

手动配置环境变量

如果你不想用 ccswitch，可以通过环境变量直接配置。

把 你的 sk-... 开头 API Key 替换成真实 key：

setx ANTHROPIC_BASE_URL "https://cc.codesome.ai"
setx ANTHROPIC_AUTH_TOKEN "你的 sk-... 开头 API Key"
setx CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC "1"
setx CLAUDE_CODE_ATTRIBUTION_HEADER "0"

关闭当前 PowerShell，重新打开一个新 PowerShell。

验证：

claude

如果输入 claude 后提示“无法加载文件 claude.ps1，因为在此系统上禁止运行脚本”，或者看到 PSSecurityException，这是 PowerShell 执行策略阻止 claude.ps1 运行，不是 Claude Code 没有安装。执行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

出现确认提示后输入 y 并回车，再重新打开 PowerShell，输入 claude 验证。这个设置只作用于当前 Windows 用户，不需要把整台电脑的执行策略改成 Unrestricted。

能进入 Claude Code 并正常回复，就配置完成。

macOS

安装 Claude Code CLI

打开终端：按 Command + 空格，搜索"终端"，回车。后面的安装和验证都在这个窗口里完成。

先安装 Node.js：

https://nodejs.org/en/download

下载 macOS 安装包并安装。

在终端验证：

node -v
npm -v

通过 npm 安装 Claude Code：

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

如果默认 npm 下载慢或无法连接，使用镜像：

npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

不要在 npm 安装命令前加 sudo。遇到权限或路径问题（无法写入 /usr/local）时，先看使用问题速查里的「npm 全局安装权限与路径修复」。

验证：

claude --version

手动配置环境变量

如果你不想用 ccswitch，可以通过环境变量直接配置：

echo 'export ANTHROPIC_BASE_URL="https://cc.codesome.ai"' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN="你的 sk-... 开头 API Key"' >> ~/.zshrc
echo 'export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1' >> ~/.zshrc
echo 'export CLAUDE_CODE_ATTRIBUTION_HEADER=0' >> ~/.zshrc
source ~/.zshrc

验证：

新开终端：

claude

看到欢迎界面后，按回车接受协议；再随便输一句话试试，能正常回复就说明配好了。

Linux

不使用 CC Switch 时，可以直接安装 CLI 并通过环境变量配置。

1. 安装 Node.js 和 npm

先检查：

node -v
npm -v

如果没有安装，Ubuntu / Debian 可以执行：

sudo apt update
sudo apt install -y nodejs npm

2. 安装 Claude Code

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

如果默认 npm 无法连接，使用镜像：

npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

不要使用 sudo npm install -g。遇到权限或路径问题（无法写入 /usr/local）时，先看使用问题速查里的「npm 全局安装权限与路径修复」。

3. 写入 V3 配置

Bash 用户：

echo 'export ANTHROPIC_BASE_URL="https://cc.codesome.ai"' >> ~/.bashrc
echo 'export ANTHROPIC_AUTH_TOKEN="你的 sk-... 开头 API Key"' >> ~/.bashrc
echo 'export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1' >> ~/.bashrc
echo 'export CLAUDE_CODE_ATTRIBUTION_HEADER=0' >> ~/.bashrc
source ~/.bashrc

Zsh 用户：

echo 'export ANTHROPIC_BASE_URL="https://cc.codesome.ai"' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN="你的 sk-... 开头 API Key"' >> ~/.zshrc
echo 'export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1' >> ~/.zshrc
echo 'export CLAUDE_CODE_ATTRIBUTION_HEADER=0' >> ~/.zshrc
source ~/.zshrc

4. 验证

claude

VS Code 等 IDE 插件

直接使用前文已经完成的 CC Switch 配置，不需要再手动编辑 settings.json。

1. 打开 CC Switch，点击左上角的齿轮进入设置。
2. 勾选 应用到 VS Code 插件。
3. 打开 VS Code 的扩展市场，搜索 Claude Code。
4. 安装 Claude Code 插件后即可使用。

常见错误

1. 把兑换码当成 API Key。

2. 用 Codex 的配置方式配置 Claude Code。

3. ANTHROPIC_AUTH_TOKEN 没有替换成真实 key。

4. 配完没有重开终端。

5. 月卡用户没有选择月卡/订阅分组。

6. 用二合一的 cr-... key 或 v5 地址配置了这篇 V3 教程。

1. CLAUDE_CODE_ATTRIBUTION_HEADER 没有设置为 0。

遇到报错，去看：

使用问题速查：报错、账单与配置排查

在 Claude Code 里使用 gpt-5.6-terra

在 ccswitch 里配置 gpt-5.6-terra

如图，重点核对这几项：

• 提供商名称填 codesome

• 请求地址填 https://cc.codesome.ai

• API Key 填你在 Codesome 里设置的 key

• 分组选择 codex月卡 或 codex分组

配置高级选项

打开 ccswitch 的代理开关

请务必开启这个开关，否则无法连接到 Codex。

如果找不到开关，就点击设置齿轮按钮进入设置页，再找到"代理"。

进入代理页面后，找到"在主页面显示本地代理开关"。

打开后即可在主页看到这个开关。

验证

新开一个终端窗口，输入：

claude

看到欢迎界面后，按回车接受协议；再随便输一句话试试，能正常回复就说明配好了。

常见问题

询问模型，发现是 claude 模型

原理是 ccs 的代理进行了转换，claude 客户端误以为自己是 claude 模型，是正常的，无需担忧，下图都是正常的

模型不回复

1. 看一下 ccswitch 的代理开关是不是关闭，需要保持开启

2. 新开一个窗口进行测试

3. 如果还是不回复，请在群里反馈，我们会第一时间帮您排查