Claude Code 完整上手指南：安装、认证与第三方模型接入

这是「工具分享」专栏的第一篇。本文根据 Claude Code 官方文档和 CC Switch 官方仓库重新整理，信息更新至 2026 年 7 月。

Claude Code 是什么

Claude Code 是 Anthropic 推出的一款 AI 编程工具。它可以运行在终端、桌面应用和 IDE 中，直接读取项目文件、搜索代码、执行命令并修改文件。

它与普通聊天工具的区别，不只是“能看到更多代码”。普通聊天通常停留在给建议或生成代码片段；Claude Code 则可以围绕一个目标连续工作：先理解项目，再修改代码、运行测试，最后根据结果继续调整。

换句话说，使用方式从“帮我写一段代码”变成了“帮我把这个任务完成”。

官方网站：Claude Code

安装前先确认环境

根据官方文档，Claude Code 支持 macOS、Windows 和主流 Linux 发行版，至少需要 4 GB 内存和网络连接。Windows 可以直接运行，也可以使用 WSL 2；如果项目依赖 Linux 工具链，WSL 2 通常更省事。

官方服务还受到支持地区限制。使用 Claude 账号或 Anthropic API 前，先确认自己所在地区符合官方的可用范围和服务条款。

安装 Claude Code

macOS、Linux 和 WSL

官方当前推荐使用原生安装器：

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

原生安装会自动更新。如果你不希望直接执行远程脚本，也可以在 macOS 上通过 Homebrew 安装：

brew install --cask claude-code

Windows PowerShell

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

也可以使用 WinGet：

winget install Anthropic.ClaudeCode

Homebrew 和 WinGet 安装的版本默认不会自动更新，需要通过对应的包管理器手动升级。

npm 安装已经弃用

旧教程通常会使用下面这条命令：

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

这种安装方式目前仍可能出现在旧环境中，但已经被官方标记为弃用，不建议新用户继续使用。尤其不要通过 sudo npm install -g 解决权限问题，它容易留下权限混乱和安全隐患。

检查安装结果

安装完成后运行：

claude --version
claude doctor

claude --version 用于确认命令是否可用；claude doctor 会检查安装、配置文件和路径问题。

然后进入项目目录启动 Claude Code：

cd 你的项目目录
claude

三种常见的认证方式

方式一：使用 Claude 订阅账号

直接运行 claude，按照浏览器提示登录。也可以显式执行：

claude auth login

Claude Code 官方登录需要 Pro、Max、Team、Enterprise 或 Console 账号，免费版 Claude.ai 账号不包含 Claude Code 使用权限。

方式二：使用 Anthropic API Key

如果希望按 API 用量付费，可以在 Claude Console 创建 API Key，然后通过环境变量配置。

Linux 或 macOS：

export ANTHROPIC_API_KEY="你的 Anthropic API Key"

Windows PowerShell：

$env:ANTHROPIC_API_KEY="你的 Anthropic API Key"

在非交互模式中，只要存在 ANTHROPIC_API_KEY，Claude Code 就会优先使用它，而不是订阅账号。交互模式首次发现该变量时，会询问你是否允许切换到 API Key。

方式三：通过 API 网关或第三方服务

Claude Code 支持用 ANTHROPIC_BASE_URL 修改 API 请求地址：

export ANTHROPIC_API_KEY="你的 API Key"
export ANTHROPIC_BASE_URL="https://你的 API 地址"

如果网关使用 Bearer Token 鉴权，可以改用 ANTHROPIC_AUTH_TOKEN。它会通过 Authorization: Bearer ... 请求头发送；ANTHROPIC_API_KEY 则通过 X-Api-Key 请求头发送。

这里有一个很容易忽略的前提：

仅仅“兼容 OpenAI API”并不代表能直接供 Claude Code 使用。

Claude Code 默认使用 Anthropic Messages 协议。第三方服务要么原生兼容这个协议，要么在中间完成协议转换。只有 OpenAI Chat Completions 或 Responses 接口、却没有转换层的服务，不能只改一个 ANTHROPIC_BASE_URL 就直接接入。

配置完成后，可以在 Claude Code 中运行 /status，查看当前账号、模型和连接状态。

为什么要用 CC Switch

手动修改环境变量并不复杂，但当你同时使用多个 API 服务，或者需要在 Claude Code、Codex、Gemini CLI 之间切换时，配置文件很快就会变得混乱。

CC Switch 是一款开源的跨平台桌面应用。它可以集中管理不同工具的服务商配置、API 地址和模型，还提供托盘切换、配置备份、用量统计，以及可选的本地协议转换功能。

它的作用不是简单地“把模型名替换掉”，而是管理各个工具的真实配置；当上下游 API 协议不一致时，还可以通过本地路由完成请求与响应格式转换。

安装 CC Switch

CC Switch 不是 npm 包，不要使用 npm install -g cc-switch。请只从官方仓库或官网获取安装包：

• Windows：从 GitHub Releases 下载 .msi 或便携版
• macOS：下载 .dmg，或使用 brew install --cask cc-switch
• Linux：从 Releases 下载 .deb、.rpm 或 .AppImage

首次启动时，CC Switch 可以导入现有的 Claude Code 配置，作为默认服务商。这样切换配置时，不必从头填写所有内容。

用 CC Switch 给 Claude Code 添加服务商

第一步：添加配置

在 CC Switch 中切换到 Claude Code 面板，点击右上角的添加按钮。可以选择内置预设，也可以选择“自定义”并填写：

• 服务商名称
• API Key 或 Token
• API 地址
• 模型名称或模型映射

如果服务商原生支持 Anthropic Messages 协议，通常可以直接连接。

第二步：确认 API 格式

如果服务商只提供 OpenAI Chat Completions 或 OpenAI Responses API，需要在高级选项中选择正确的 API 格式，并启用 CC Switch 的本地路由或接管功能。转换依赖本地代理运行，因此使用期间不能退出对应的代理服务。

这一步决定了工具调用、流式输出和错误响应能否被正确转换。接口能返回一句普通文本，并不代表它已经完整兼容 Claude Code。

第三步：启用并验证

保存配置后，点击服务商卡片上的“启用”。Claude Code 支持配置热加载，通常不需要重启；如果当前会话没有切换成功，再重新打开终端或 Claude Code。

进入项目后，先做两个检查：

/status
读取当前项目的 README，并告诉我项目使用了什么技术栈

第一个检查认证和模型状态，第二个检查基本的文件读取与工具调用。只有两项都正常，才算真正接入成功。

哪些模型可以接入

能否接入，主要取决于服务商协议，而不只是模型名称。

上游服务类型	接入方式	注意事项
Anthropic 官方 API	直接配置 API Key	兼容性最好
Anthropic Messages 兼容服务	配置 Key 和 Base URL	需要确认工具调用与流式输出是否完整
OpenAI Chat Completions 服务	通过 CC Switch 本地转换	必须保持本地路由运行
OpenAI Responses 服务	通过支持 Responses 的转换层	需要检查工具调用和推理字段
Bedrock、Vertex AI、Foundry	优先使用 Claude Code 官方集成	适合已有云平台账号的团队

DeepSeek、GLM、Qwen 等模型可以通过兼容服务或协议转换接入，但“能对话”和“适合做编程代理”是两回事。实际使用时需要重点检查：

• 是否支持稳定的工具调用
• 是否能正确处理长上下文
• 流式响应是否完整
• 是否支持提示词缓存或推理模式
• 修改文件后能否继续运行测试并根据结果迭代

模型能力、服务商实现和网络质量都会影响最终体验，因此不建议仅凭模型名称判断效果。

几个安全注意事项

不要把 API Key 提交到仓库

不要把密钥写入会被 Git 跟踪的文件。个人环境变量和用户级配置更合适；如果团队需要统一管理，应该使用专门的密钥管理服务。

第三方服务能够看到请求内容

使用第三方 API 时，代码片段、提示词和工具返回内容都可能经过对方服务器。涉及商业源码、用户数据或密钥的项目，需要先确认服务商的数据处理政策。

只从官方渠道下载 CC Switch

CC Switch 官方仓库明确提醒过仿冒网站问题。不要向所谓的“CC Switch 服务”支付费用，也不要在来历不明的客户端中输入账号密码。

谨慎使用实验性 OAuth 转发

CC Switch 的部分版本包含实验性的 OAuth 反向代理功能。项目文档明确提示，这类功能可能存在账号、服务条款和长期可用性风险。普通 API Key 接入并不需要它，不清楚风险时不要开启。

不要随意跳过权限确认

无论使用哪个模型，Claude Code 都可能修改文件和运行命令。刚接触时保留默认权限确认，先检查 diff 和测试结果，再提交代码。

常见问题排查

终端提示 claude: command not found

重新打开终端，检查安装目录是否已经加入 PATH，然后运行 claude doctor。如果使用的是旧 npm 安装，优先迁移到官方推荐的原生安装方式。

配了 API Key，仍然使用订阅账号

运行 /status 查看当前认证来源，并确认环境变量是在启动 Claude Code 的同一个终端中设置的。

能聊天，但无法读文件或运行命令

这通常不是提示词问题，而是第三方服务的工具调用兼容性不完整。检查 API 格式、本地路由状态和模型是否支持工具调用。

CC Switch 切换后没有生效

先确认服务商卡片已经启用。如果使用协议转换，再确认本地路由仍在运行。Claude Code 通常支持热加载配置，但遇到旧会话缓存时，重启一次 CLI 最直接。

总结

完整流程可以压缩成五步：

1. 使用官方推荐方式安装 Claude Code
2. 通过账号、Anthropic API Key 或合规的 API 网关完成认证
3. 用 claude --version、claude doctor 和 /status 检查状态
4. 需要多服务商切换时，再安装 CC Switch
5. 接入第三方模型后，重点验证工具调用，而不只是测试聊天回复

工具和模型会不断更新，但“安装来源可信、协议真正兼容、密钥妥善保存、操作权限可控”这四条原则不会过时。

参考资料

• Claude Code 官方安装文档
• Claude Code 认证文档
• Claude Code 环境变量参考
• CC Switch 官方仓库
• CC Switch 服务商配置手册