Claude Code 安装配置指南

zuolan · 2025 年12 月 14 日 10:56

author: 左岚

Claude Code 安装配置指南

通过网盘分享的文件：3 claude code概念讲解与配置
链接: https://pan.baidu.com/s/1Pb_389Vq6jhRtLIpqY-siw?pwd=1ynw 提取码: 1ynw
–来自百度网盘超级会员v6的分享

我用夸克网盘分享了「3 claude code概念讲解与配置软件包」，点击链接即可保存。打开「夸克APP」，无需下载在线播放视频，畅享原画5倍速，支持电视投屏。
链接：夸克网盘分享

『来自123云盘用户左_岚的分享』3 claude code概念讲解与配置软件包
链接：https://www.123865.com/s/BoRRVv-zYDxh?pwd=tnli#
提取码：tnli

配套文档：阅读本指南前，建议先查看《Claude Code 核心概念详解》了解基础概念。

在线文档https://ai.feishu.cn/drive/folder/UQgzfSmeSlDA8Nd43UOc0WOCnRd

ai杂谈目录下
邀请链接
https://www.packyapi.com/register?aff=NUvl
https://cubence.com/signup?code=SCMOJRHS
优惠码DING113CCH，购买订阅和充钱的时候可以20%优惠
https://api.ikuncode.cc/register?aff=IqpG

一、环境准备

1.1 Git 安装

1.1.1 下载地址

Git for Windows 官方下载

1.1.2 为什么需要 Git

必要依赖：Git 是 Claude Code 的必要依赖，缺失会导致启动失败。

依赖原因：

Claude Code 基于 Git Bash 运行环境
没有 Git 将无法正常启动框架

1.1.3 安装步骤

下载适用于 Windows 的 Git 安装包
运行安装程序，大部分选项保持默认

1.1.4 安装后配置

git config --global user.name "Your Name"
git config --global user.email "youremail@yourdomain.com"

1.1.5 参考资料

详细的 Git 使用教程请参考：大学生扫盲课第一期

1.2 Node.js 安装

1.2.1 下载地址

Node.js 官方中文站

1.2.2 技术背景

Node.js 简介：

JavaScript 服务器运行环境
内置 npm 包管理器（类似 Python 的 pip）
是运行 Node 版本 Claude Code 的基础

为什么需要 Node.js：

Claude Code 提供了基于 Node.js 的版本
虽然有独立版本，但 Node.js 环境提供更好的灵活性
便于后续扩展和自定义配置

1.2.3 安装步骤

下载对应系统的安装包
运行安装程序
如无特殊路径要求，使用默认配置即可

验证安装：

node -v
npm -v

1.3 CC Switch 工具

1.3.1 项目地址

GitHub - cc-switch

1.3.2 工具简介

CC Switch 是一个可视化 API 配置管理工具，主要功能：

简化配置：无需手动编辑 URL 和 Token
一键切换：支持多个 API 站点快速切换
多框架支持：兼容 Claude Code、Codex、Gemini CLI

1.3.3 版本信息

当前最新版：v3.8.2（2024 年 12 月发布）

支持框架：

Claude Code
Codex
Gemini CLI

1.3.4 安装方式

方式一：安装版（推荐）

标准安装程序
自动更新支持

方式二：便携版

免安装，解压即用
缺点：需手动下载新版本覆盖更新

二、Claude Code 安装

2.1 安装说明

官方文档：https://code.claude.com/docs/zh-CN/overview

2.2 安装方式

方式一：npm 安装（推荐）

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

优势：

稳定性好
更新方便
推荐使用

方式二：独立安装（官方推荐）

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

说明：

官方提供的独立安装包
部分用户反馈存在兼容性问题

三、环境变量配置

重要：

使用 API 接入和官方账号登录二选一，同时配置会导致冲突

如有官方账号，直接登录即可，无需配置环境变量

3.1 获取 API URL 和 Token

以西风站点（https://www.openclaudecode.cn）为例：

步骤 1：获取 API URL

在主页左侧可以看到两个线路选项，选择其中一个作为 API URL：

步骤 2：充值余额

前往"钱包管理"进行充值测试

步骤 3：创建 API Token

点击"令牌管理" → “添加令牌”

配置参数说明：

参数	说明	推荐设置
名称	自定义标识	便于识别即可
过期时间	Token 有效期	个人使用：永不过期
额度限制	单 Token 用量上限	个人使用：无限额度
缓存时长	上下文缓存有效期	重度开发：1 小时轻度使用：5 分钟

3.2 方式一：手动添加环境变量（必须做，因为她会优先检测环境变量，再检测cc switch的，一旦没有，会导致claude启动的时候要求认证）

手动添加环境变量：

变量名：ANTHROPIC_BASE_URL
变量值：你的 API URL
变量名：ANTHROPIC_AUTH_TOKEN
变量值：你的 API Token

3.3 方式二：配置文件配置

配置文件路径：C:\Users\你的用户名\.claude\config.json

创建或修改配置文件：

{
    "primaryApiKey": "你的API密钥"
}

如已有其他配置：

{
    "其他配置项": "值",
    "primaryApiKey": "你的API密钥"
}

3.4 方式三：CC Switch 配置（推荐）

优势：

可视化操作
一键切换多个 API
配置简单

操作步骤：

步骤 1：添加新配置

打开 CC Switch，点击添加配置：

步骤 2：选择供应商

如果是预设供应商（Zhipu GLM、Minimax、Kimi 等），直接选择
如果是其他供应商，选择"自定义配置"

步骤 3：填写配置信息

字段	说明	示例
供应商名称	自定义标识	西风 OCC
官网链接	可选	https://www.openclaudecode.cn
API Key	必填	sk-xxxxxxxxxxxx
API URL	必填	https://api.example.com/v1

步骤 4：西风 OCC 配置示例（这里注意一下，请求地址有两个，选择一个就行，可以测速试试，优先使用国内的那个）

四、ZCF 快速配置工具

4.1 项目介绍

项目地址：https://github.com/UfoMiao/zcf

ZCF（Zero-Config Code Flow）功能：

自动安装和配置 Claude Code
预配置常用 MCP 服务器
集成提示词人设模板
一键完成所有配置

4.2 快速安装

npx zcf

前提：已安装 Node.js

4.3 配置流程

推荐配置方案：

安装类型：选择"完整安装"
API 配置：选择"自行配置"（使用 CC Switch）
MCP 服务器：推荐安装
- context7（文档查询）
- deepwiki（知识库）
- 其他根据需求选择
完成安装：关闭并重启终端

4.4 启动测试

claude

五、CCometixLine 状态栏配置

5.1 插件简介

项目地址：CCometixLine

功能特性：

实时显示令牌消耗
显示当前模型

5.2 安装命令

npm install -g @cometix/ccline

5.3 配置方法

修改配置文件：

Windows：C:\Users\你的用户名\.claude\settings.json
Linux/macOS：~/.claude/settings.json

配置内容：

Linux/macOS 配置

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/ccline/ccline",
    "padding": 0
  }
}

Windows 配置

{
  "statusLine": {
    "type": "command",
    "command": "%USERPROFILE%\\.claude\\ccline\\ccline.exe",
    "padding": 0
  }
}

Fallback 配置（npm 安装）

{
  "statusLine": {
    "type": "command",
    "command": "ccline",
    "padding": 0
  }
}

5.4 CC Switch 用户配置

在 CC Switch 中新建配置时，在"通用配置"部分添加：

{
  "includeCoAuthoredBy": false,
  "statusLine": {
    "type": "command",
    "command": "%USERPROFILE%\\.claude\\ccline\\ccline.exe",
    "padding": 0
  }
}

六、Claudia Global 可视化工具

6.1 工具介绍

项目地址：Claudia Global

功能特性：

可视化历史记录查看
API 和 URL 配置管理
可替代 CC Switch 使用

6.2 界面预览

七、常见问题排查

7.1 找不到 `claude` 命令

错误提示：

'claude' 不是内部或外部命令，也不是可运行的程序或批处理文件。

解决方案：

步骤 1：找到 Claude Code 安装路径

where claude

或手动查找（Windows 常见路径）：

C:\Users\你的用户名\AppData\Roaming\npm

步骤 2：添加到系统环境变量

右键"此电脑" → “属性”
点击"高级系统设置"
点击"环境变量"
在"用户变量"和"系统变量"中找到 Path
双击 Path，点击"新建"
添加路径：C:\Users\你的用户名\AppData\Roaming\npm
点击"确定"保存

步骤 3：重启终端并验证

claude --version

八、常见错误处理

8.1 API 相关错误

错误 1：429 Rate Limit Exceeded

错误信息：

Error: 429 Too Many Requests - Rate limit exceeded

原因分析：

请求频率超过 API 限制
短时间内发送过多请求

解决方案：

等待冷却：暂停 1-5 分钟后重试
降低请求频率：减少并发对话数量
升级套餐：联系站点管理员提升限额
切换 API：使用 CC Switch 切换到备用站点

错误 2：401 Unauthorized

错误信息：

Error: 401 Unauthorized - Invalid API key

原因分析：

API Token 无效或过期
API Token 输入错误

解决方案：

检查 Token：确认复制的 Token 完整无误
重新生成：在站点后台重新生成 Token
检查配置：确认环境变量或配置文件正确
清除缓存：删除 .claude 目录下的缓存文件

验证命令：

echo %ANTHROPIC_AUTH_TOKEN%

错误 3：403 Forbidden

错误信息：

Error: 403 Forbidden - Access denied

原因分析：

余额不足
站点封禁
IP 限制

解决方案：

检查余额：登录站点查看剩余额度
更换 IP：切换网络或使用代理
联系客服：确认账号状态

错误 4：500 Internal Server Error

错误信息：

Error: 500 Internal Server Error

原因分析：

站点服务器故障
API 接口异常

解决方案：

等待恢复：站点通常会在数分钟内修复
切换线路：使用站点提供的备用 URL
切换站点：使用 CC Switch 切换到备用 API

错误 5：Connection Timeout

错误信息：

Error: Request timeout - Connection timed out

原因分析：

网络连接不稳定
站点响应速度慢

解决方案：

检查网络：确认网络连接正常
更换网络：切换到更稳定的网络环境
增加超时时间：在配置文件中调整 timeout 参数

8.2 配置相关错误

错误 1：找不到配置文件

错误信息：

Error: Config file not found

解决方案：

创建配置文件：

# Windows
mkdir %USERPROFILE%\.claude
echo {} > %USERPROFILE%\.claude\config.json

# Linux/macOS
mkdir -p ~/.claude
echo '{}' > ~/.claude/config.json

错误 2：配置文件格式错误

错误信息：

Error: Invalid JSON format in config file

解决方案：

使用 JSON 验证工具检查格式
确保没有多余的逗号
确保引号使用正确（双引号）

正确格式示例：

{
  "primaryApiKey": "sk-xxxxx",
  "statusLine": {
    "type": "command",
    "command": "ccline"
  }
}

8.3 运行时错误

错误 1：Git 未安装

错误信息：

Error: Git is not installed

解决方案：

参考 1.1 Git 安装章节完成安装

错误 2：Node.js 版本过低

错误信息：

Error: Node.js version too old. Required: >=18.0.0

解决方案：

前往 Node.js 官网下载最新版本
卸载旧版本
安装新版本
验证：node -v

错误 3：权限不足

错误信息：

Error: Permission denied

解决方案：

Windows：

以管理员身份运行 PowerShell 或 CMD

Linux/macOS：

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

8.4 MCP 相关错误

错误 1：MCP 服务器无法连接

错误信息：

Error: Failed to connect to MCP server

解决方案：

检查 MCP 服务器配置
确认服务器地址正确
检查防火墙设置

错误 2：MCP 工具调用失败

错误信息：

Error: MCP tool execution failed

解决方案：

查看 MCP 服务器日志
确认工具参数格式正确
尝试重启 MCP 服务器

8.5 快速诊断流程

graph TD
    A[遇到错误] --> B{错误类型?}
    B -->|API错误| C[检查Token和URL]
    B -->|配置错误| D[检查配置文件]
    B -->|运行时错误| E[检查环境依赖]
    B -->|网络错误| F[检查网络连接]

    C --> G{余额充足?}
    G -->|否| H[充值或切换API]
    G -->|是| I{Token有效?}
    I -->|否| J[重新生成Token]
    I -->|是| K[切换备用线路]

    D --> L[验证JSON格式]
    L --> M[检查路径正确性]

    E --> N[验证Git安装]
    N --> O[验证Node.js版本]

    F --> P[切换网络]

九、推荐的 API 中转站

9.4 其他

可参考这个链接

https://aio.helphelp.club/transit

9.5 使用建议

最佳实践：

建议同时注册 2-3 个站点

使用 CC Switch 一键切换

避免单点故障导致工作中断

小额多次充值，降低风险

Claude Code 安装配置指南

Claude Code 安装配置指南

一、环境准备

1.1 Git 安装

1.1.1 下载地址

1.1.2 为什么需要 Git

1.1.3 安装步骤

1.1.4 安装后配置

1.1.5 参考资料

1.2 Node.js 安装

1.2.1 下载地址

1.2.2 技术背景

1.2.3 安装步骤

1.3 CC Switch 工具

1.3.1 项目地址

1.3.2 工具简介

1.3.3 版本信息

1.3.4 安装方式

二、Claude Code 安装

2.1 安装说明

2.2 安装方式

方式一：npm 安装（推荐）

方式二：独立安装（官方推荐）

三、环境变量配置

3.1 获取 API URL 和 Token

3.2 方式一：手动添加环境变量（必须做，因为她会优先检测环境变量，再检测cc switch的，一旦没有，会导致claude启动的时候 要求认证）

3.3 方式二：配置文件配置

3.4 方式三：CC Switch 配置（推荐）

四、ZCF 快速配置工具

4.1 项目介绍

4.2 快速安装

4.3 配置流程

4.4 启动测试

五、CCometixLine 状态栏配置

5.1 插件简介

5.2 安装命令

5.3 配置方法

5.4 CC Switch 用户配置

六、Claudia Global 可视化工具

6.1 工具介绍

6.2 界面预览

七、常见问题排查

7.1 找不到 claude 命令

八、常见错误处理

8.1 API 相关错误

错误 1：429 Rate Limit Exceeded

错误 2：401 Unauthorized

错误 3：403 Forbidden

错误 4：500 Internal Server Error

错误 5：Connection Timeout

8.2 配置相关错误

错误 1：找不到配置文件

错误 2：配置文件格式错误

8.3 运行时错误

错误 1：Git 未安装

错误 2：Node.js 版本过低

错误 3：权限不足

8.4 MCP 相关错误

错误 1：MCP 服务器无法连接

错误 2：MCP 工具调用失败

8.5 快速诊断流程

九、推荐的 API 中转站

9.1 Ikuncode（有点贵，但是稳定）

9.2 大鹅 - Cubence

9.3 Packy

9.4 其他

9.5 使用建议

3.2 方式一：手动添加环境变量（必须做，因为她会优先检测环境变量，再检测cc switch的，一旦没有，会导致claude启动的时候要求认证）

7.1 找不到 `claude` 命令