Claude Code 部署指南

资源	地址
Claude Code 官方文档	docs.claude.com

📋 前置要求

请先安装 Node.js 18+。可以去 Node.js 官网 下载安装。

⚡ 首次启动必读：跳过初始化报错

使用中转服务（包括卡皮巴拉）时，Claude Code 首次启动会出现连接报错：

Welcome to Claude Code
Unable to connect to Anthropic services
Failed to connect to api.anthropic.com: ERR_BAD_REQUEST

这是因为 Claude Code 第一次启动时会强制连接 Anthropic 官方 API 做初始化校验，中转服务无法通过这一步。安装完成后、首次启动前，请先用下面任一方法跳过这个校验。

方法一：用 CC-Switch 跳过（推荐）

打开 CC-Switch 配置工具，进入 设置 → 通用，开启 「跳过 Claude Code 初次安装确认」 选项即可。

方法二：手动改配置文件

在用户主目录下找到 ~/.claude.json（Windows 在 C:\Users\你的用户名\.claude.json），在末尾追加 "hasCompletedOnboarding": true 字段：

⚠️ 注意 JSON 格式

新增字段前，要在上一个字段末尾补一个英文逗号，否则 JSON 格式错误会让 Claude Code 直接启动失败。

{
  "installMethod": "unknown",
  "autoUpdates": true,
  "firstStartTime": "2025-07-14T06:11:03.877Z",
  "userID": "xxxx",
  "projects": {
    "/home/your-user": {
      "allowedTools": [],
      "history": [],
      "mcpContextUris": [],
      "mcpServers": {},
      "enabledMcpjsonServers": [],
      "disabledMcpjsonServers": [],
      "hasTrustDialogAccepted": false,
      "projectOnboardingSeenCount": 0,
      "hasClaudeMdExternalIncludesApproved": false,
      "hasClaudeMdExternalIncludesWarningShown": false
    }
  },
  "hasCompletedOnboarding": true
}

注意第二行末尾从原本的 } 改成 },（加一个英文逗号），然后再加最后一行 "hasCompletedOnboarding": true。

保存文件后，重新执行 claude 命令就能正常使用了。

---

🚀 用 CC-Switch 一键配置（推荐）

如果你已经装了 CC-Switch，整个配置过程可以纯图形界面完成，不用碰命令行、不用手动改配置文件。

为什么推荐

• 🖱️ 图形界面，鼠标点点就行
• 🔄 一键切换不同 API 提供商
• 🔧 自动管理环境变量和配置文件
• 💾 配置自动备份和恢复
• ⚡ 切换后立即生效，无需重启终端

配置步骤

1. 在 CC-Switch 添加卡皮巴拉配置

1. 打开 CC-Switch 应用
2. 点击顶部 「Claude」 标签页
3. 点击右上角橙色 「+」 按钮添加新配置

2. 填写配置信息

字段	填写内容
提供商名称	自定义，比如「卡皮巴拉」
API Base URL	https://ai.bututrip.fun
API Key	你在卡皮巴拉创建的 Claude 专用密钥
模型选择	根据需求选择可用的 Claude 模型

填完点 「保存」。

💡 提示

• 可以同时添加多个不同提供商配置（卡皮巴拉、官方、其他渠道等），随时切换
• CC-Switch 会自动写入 ~/.claude/settings.json，不需要你动手

3. 启用配置

1. 在配置列表里找到刚创建的「卡皮巴拉」
2. 点击右侧的 「当前使用」 按钮（或直接点配置卡片）
3. 该配置会被标记成绿色「当前使用」状态
4. 重启 Claude Code 让新配置生效

4. 系统托盘快速切换

CC-Switch 还支持托盘菜单切换，更快：

1. 右键点击系统托盘里的 CC-Switch 图标
2. 在菜单里选择 Claude 分类
3. 直接点要切换到的配置
4. 立即生效，不用打开主界面

⚠️ 注意事项

• 确保创建的是 Claude Code 专用密钥（卡皮巴拉管理页面里有相应类型）
• 切换后重启 Claude Code 才能生效
• 在 CC-Switch 中可以测试 API 端点连接情况

---

⌨️ 手动命令行配置

不想用 CC-Switch 也可以纯命令行配置。下面分平台讲。

🖥️ Windows

系统要求： Windows 10 或 11

安装 Claude Code

方法一：官方安装脚本（推荐）

PowerShell：

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

CMD：

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

方法二：通过 npm（不推荐）

⚠️ 不建议使用 npm

npm 渠道更新滞后，安装的版本通常较旧。优先用上面的官方安装脚本。

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

验证安装：

claude --version

配置环境变量

PowerShell：

[Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "sk-xxx", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://ai.bututrip.fun", "User")

CMD：

setx ANTHROPIC_AUTH_TOKEN "sk-xxx"
setx ANTHROPIC_BASE_URL "https://ai.bututrip.fun"

💡 提示

把 sk-xxx 替换成你在卡皮巴拉创建的真实密钥。设置后必须重启终端，环境变量才会生效。

启动

打开新的终端窗口（让环境变量生效），cd 到任意项目目录，输入：

claude

---

🍏 macOS

系统要求： macOS 10.15 (Catalina) 或更高

安装 Claude Code

方法一：Homebrew（推荐）

brew install --cask claude-code

方法二：官方安装脚本

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

方法三：通过 npm（不推荐）

⚠️ 不建议使用 npm

npm 版本通常较旧，优先用 Homebrew 或官方脚本。

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

验证安装

claude -v

应该输出类似：1.0.108 (Claude Code)

配置环境变量

如果你用 zsh（macOS 默认）：

echo 'export ANTHROPIC_AUTH_TOKEN="sk-xxx"' >> ~/.zshrc
echo 'export ANTHROPIC_BASE_URL="https://ai.bututrip.fun"' >> ~/.zshrc
source ~/.zshrc

如果你用 bash：

echo 'export ANTHROPIC_AUTH_TOKEN="sk-xxx"' >> ~/.bash_profile
echo 'export ANTHROPIC_BASE_URL="https://ai.bututrip.fun"' >> ~/.bash_profile
source ~/.bash_profile

💡 提示

把 sk-xxx 替换成你的卡皮巴拉密钥。

启动

重启终端后，在任意目录输入 claude 即可使用。

---

🐧 Linux

系统要求： 主流发行版 (Ubuntu 18.04+ / CentOS 7+ / Debian 9+ 等)

安装 Claude Code

方法一：官方安装脚本（推荐）

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

方法二：通过 npm（不推荐）

⚠️ 不建议使用 npm

npm 版本通常较旧，优先用官方脚本。

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

验证安装

claude -v

配置环境变量

Bash 用户（Ubuntu/Debian 默认）：

echo 'export ANTHROPIC_AUTH_TOKEN="sk-xxx"' >> ~/.bash_profile
echo 'export ANTHROPIC_BASE_URL="https://ai.bututrip.fun"' >> ~/.bash_profile
source ~/.bash_profile

Zsh 用户：

echo 'export ANTHROPIC_AUTH_TOKEN="sk-xxx"' >> ~/.zshrc
echo 'export ANTHROPIC_BASE_URL="https://ai.bututrip.fun"' >> ~/.zshrc
source ~/.zshrc

💡 提示

把 sk-xxx 替换成你的卡皮巴拉密钥。

启动

重启终端，输入 claude 即可使用。

---

常见问题

提示找不到 claude 命令？

• 确认 Claude Code 已正确安装（用 claude -v 验证）
• 检查 PATH 环境变量是否包含安装目录
• 关闭并重新打开终端

连接失败 / 报错 ERR_BAD_REQUEST？

• 看本文最上方的「首次启动必读：跳过初始化报错」一节，这是新手 99% 会踩的坑
• 检查 ANTHROPIC_BASE_URL 是否填对：https://ai.bututrip.fun
• 检查 ANTHROPIC_AUTH_TOKEN 是否是从卡皮巴拉创建的有效密钥

切换配置后不生效？

• 必须重启 Claude Code 终端，环境变量改了之后旧的进程还是用旧值
• 用 CC-Switch 切换后也需要重启 Claude Code

更多问题？

参考 常见问题排查。