Claude Code 国内安装与配置全指南

-

从零开始，手把手教你在国内网络环境下安装、配置并高效使用 Claude Code。

一、Claude Code 是什么

Claude Code 是 Anthropic 推出的命令行 AI 编程助手。它不是网页聊天框，而是直接嵌入你终端的 " 资深搭档 "——读代码、写代码、跑测试、操作 Git，全在命令行完成。

简单说三句话：

  1. 终端原生：在 PowerShell / Terminal 里直接 claude 启动，不用切换窗口
  2. 理解项目：自动读取你的代码库，理解上下文后再动手
  3. 自主执行：不只是生成代码片段，而是直接修改文件、运行命令、修复 Bug

它的核心能力包括：

  • 🔍 代码搜索与理解（读懂整个 repo）
  • ✏️ 智能编辑（精确修改，不乱改）
  • 🐛 自主调试（定位 Bug 并修复）
  • 📋 Git 工作流（提交、PR、代码审查）
  • 🤖 子代理编排（复杂任务自动拆分）
  • 🔌 MCP 扩展（连接外部工具和服务）

二、安装前的准备

2.1 系统要求

项目 最低要求 推荐配置
操作系统 Windows 10+ / macOS 12+ / Linux Windows 11 / macOS 14+
Node.js v18 LTS v20+ LTS
npm 随 Node.js 安装 最新版
网络环境 需要访问 Anthropic API 稳定代理
内存 4 GB 8 GB+

2.2 安装 Node.js

Claude Code 基于 Node.js 运行，这是唯一的前置依赖。

Windows 用户推荐方式：

  1. 访问 Node.js 官网
  2. 下载 LTS 版本（长期支持版，最稳定）
  3. 双击安装，一路 " 下一步 " 即可
  4. 验证安装：
node -v    # 应显示 v20.x.x 或更高
npm -v     # 应显示 10.x.x 或更高

💡 如果你已经安装了 Node.js，版本在 v18 以上就行，不用重新装。

三、安装 Claude Code

3.1 Windows 推荐安装方式（官方一键脚本）

打开 PowerShell，执行：

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

这是 Anthropic 官方推荐的 Windows 安装方式，会自动下载最新版并配置好环境。

3.2 npm 全局安装方式（通用）

如果一键脚本不通，或者你更喜欢手动控制：

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

3.3 验证安装

claude --version

看到版本号就说明安装成功。

3.4 常见安装问题

问题 1：claude 命令找不到

原因：npm 全局 bin 目录没加到系统 PATH。

临时修复（当前会话有效）：

# PowerShell
$env:PATH += ";C:\Users\<你的用户名>\AppData\Roaming\npm"

永久修复：

  1. 按 Win + R，输入 sysdm.cpl
  2. 高级 → 环境变量
  3. 在用户变量中找到 Path，编辑
  4. 添加 C:\Users\<你的用户名>\AppData\Roaming\npm
  5. 重启终端

问题 2：npm 安装速度慢

国内网络直连 npm 官方源经常超时，建议切换镜像源：

# 切换到淘宝镜像
npm config set registry https://registry.npmmirror.com

# 安装完成后可以切回来
npm config set registry https://registry.npmjs.org

问题 3：权限不足

Windows 上用管理员身份打开 PowerShell 再执行安装命令。

四、国内网络环境配置（重点）

这是国内用户最头疼的部分。Claude Code 需要连接 Anthropic API（api.anthropic.com），国内直连基本不通。下面提供三种方案，按推荐度排序。

方案一：API Key + 代理（推荐）

这是最常用、最稳定的方案。你只需要一个 Anthropic API Key 和一个代理。

第一步：获取 API Key

  1. 访问 console.anthropic.com
  2. 注册并登录（需要海外手机号或邮箱）
  3. 进入 API Keys 页面，创建新 Key
  4. 复制保存（以 sk-ant- 开头，只显示一次）

第二步：配置环境变量

在 PowerShell 中设置：

# 设置 API Key
$env:ANTHROPIC_API_KEY = "sk-ant-你的密钥"

# 设置代理（替换为你的代理地址和端口）
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:HTTP_PROXY = "http://127.0.0.1:7890"

永久生效：右键 " 此电脑 " → 属性 → 高级系统设置 → 环境变量，在用户变量中添加以上三项。

第三步：启动 Claude Code

claude

首次启动会要求登录。选择 API Key 登录方式即可。

方案二：第三方 API 代理服务

如果你没有 Anthropic 官方账号，可以使用国内可访问的第三方 API 代理服务（如 OpenRouter、各种中转站）。

# 设置第三方 API 基础 URL
$env:ANTHROPIC_BASE_URL = "https://你的代理服务地址/v1"
$env:ANTHROPIC_API_KEY = "你的代理服务密钥"

⚠️ 使用第三方代理时注意：确认服务商的隐私政策、价格透明度和稳定性。敏感代码不建议通过不可信的中转服务。

方案三：Claude Desktop + 3P 模式

如果你更喜欢图形界面，可以使用 Claude Desktop 桌面版配合第三方推理网关。

操作步骤：

  1. 安装 Claude Desktop
  2. 开启开发者模式：Help → Troubleshooting → Enable Developer mode
  3. 打开 3P 配置：Developer → Configure third-party inference
  4. 选择 Gateway 连接方式
  5. 填写代理服务的连接信息

关键配置项：

{
  "inferenceProvider": "gateway",
  "inferenceGatewayBaseUrl": "http://127.0.0.1:15721",
  "inferenceGatewayApiKey": "PROXY_MANAGED",
  "inferenceGatewayAuthScheme": "bearer",
  "inferenceModels": ["sonnet", "haiku", "opus"],
  "isClaudeCodeForDesktopEnabled": true
}

也可以用 PowerShell 直接写入注册表：

New-Item -Path 'HKCU:\SOFTWARE\Policies\Claude' -Force | Out-Null
Set-ItemProperty -Path 'HKCU:\SOFTWARE\Policies\Claude' -Name 'inferenceProvider' -Value 'gateway'
Set-ItemProperty -Path 'HKCU:\SOFTWARE\Policies\Claude' -Name 'inferenceGatewayBaseUrl' -Value 'http://127.0.0.1:15721'
Set-ItemProperty -Path 'HKCU:\SOFTWARE\Policies\Claude' -Name 'inferenceGatewayApiKey' -Value 'PROXY_MANAGED'
Set-ItemProperty -Path 'HKCU:\SOFTWARE\Policies\Claude' -Name 'inferenceGatewayAuthScheme' -Value 'bearer'
Set-ItemProperty -Path 'HKCU:\SOFTWARE\Policies\Claude' -Name 'inferenceModels' -Value '["sonnet","haiku","opus"]'
Set-ItemProperty -Path 'HKCU:\SOFTWARE\Policies\Claude' -Name 'isClaudeCodeForDesktopEnabled' -Value 1 -Type DWord

💡 inferenceModels 这一行必须手动添加，面板里无法编辑。没有这行的话模型下拉框会是空的。

验证 3P 是否接通：

检查以下关键指标：

  • C:\Users\<用户名>\.cc-switch\logs\cc-switch.log 中是否有请求记录
  • Session 文件中 entrypoint 是否为 claude-desktop-3p
  • 请求日志中 source=proxy、status_code=200

五、首次运行与基本使用

5.1 一键健康检查

安装和配置完成后，运行诊断命令确认一切就绪：

claude doctor

或者手动检查：

# 检查 Node.js 和 npm
node --version
npm --version

# 检查 claude 是否在 PATH 中
where claude

# 检查 API Key 是否已设置
if ($env:ANTHROPIC_API_KEY) { "API Key: 已设置" } else { "API Key: 未设置" }

5.2 在项目中启动

# 进入你的项目目录
cd your-project

# 启动 Claude Code
claude

Claude Code 会自动读取项目结构、代码文件和配置，理解你的代码库后开始工作。

5.3 常用命令速查

命令 用途
claude 交互式对话
claude "你的问题" 单次提问
claude -p "任务描述" 以管道模式运行
claude doctor 健康检查
claude config 查看配置
claude mcp 管理 MCP 服务器

5.4 交互模式基本操作

进入交互模式后，你可以：

  • 直接提问：解释一下这个函数的作用
  • 让它写代码：添加一个用户登录接口
  • 修 Bug：测试失败了，帮我看看为什么
  • 操作 Git：把当前改动提交一下
  • 按 / 查看斜杠命令：如 /init、/review、/code-review

六、进阶配置

6.1 CLAUDE.md —— 项目行为规范

CLAUDE.md 是 Claude Code 的 " 项目说明书 "，放在项目根目录。它告诉 Claude 如何在你的项目中工作。

最简模板：

# 项目规范

## 技术栈
- 语言：TypeScript
- 框架：Next.js
- 测试：Vitest

## 编码规范
- 使用函数式组件
- 优先使用 const
- 文件命名用 kebab-case

## 工作流
- 3 步以上的任务先做计划
- 修改被引用的文件前先搜索所有引用点
- 提交前必须跑测试

Anthropic 官方推荐的六大工作流原则：

  1. 计划优先：3 步以上的任务必须先做计划
  2. 善用子代理：研究、探索、并行分析交给子代理
  3. 自我改进：被纠正后记录教训，避免重复犯错
  4. 完成前验证：没证明能用之前，别标记完成
  5. 追求优雅：非平凡改动先问 " 有更优雅的方法吗 "
  6. 自主修 Bug：给个 Bug 报告，让它自己修

6.2 MCP 服务器扩展

MCP（Model Context Protocol）让 Claude Code 连接外部工具。常用扩展：

MCP 服务器 用途
filesystem 安全的文件系统访问
github GitHub PR/Issue 操作
fetch 网页内容获取
context7 最新库文档查询

配置文件位置：~/.claude/settings.json

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    }
  }
}

6.3 Skills 技能系统

Skills 是 Claude Code 的可复用工作流封装。每个技能是一个文件夹，核心是 SKILL.md 文件。

技能的典型结构：

skill-name/
├── SKILL.md        # 必须：技能定义与指令
├── scripts/        # 可选：可执行脚本
├── references/     # 可选：参考文档
└── assets/         # 可选：模板资源

安装社区技能：

  1. 从 Claude Skills 仓库 或社区获取
  2. 放入 ~/.claude/skills/ 目录
  3. 重启 Claude Code 即可使用

6.4 Obsidian 集成

Claude Code 可以深度集成到 Obsidian 中，打造 AI 驱动的智能笔记系统。

两种方式：

  1. Claudian 插件：直接在 Obsidian 内调用 Claude Code
  2. Obsidian Skills：Kepano 维护的 Obsidian 专用技能包

七、常见问题排查

Q1：连接超时 / 无法连接 API

# 1. 确认代理正在运行
curl -x http://127.0.0.1:7890 https://api.anthropic.com

# 2. 确认环境变量
echo $env:HTTPS_PROXY
echo $env:ANTHROPIC_API_KEY

# 3. 尝试直接测试 API
curl -x http://127.0.0.1:7890 https://api.anthropic.com/v1/messages -H "x-api-key: $env:ANTHROPIC_API_KEY" -H "anthropic-version: 2023-06-01" -H "content-type: application/json" -d '{"model":"claude-sonnet-4-20250514","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

Q2：API Key 无效

  • 确认 Key 以 sk-ant- 开头
  • 确认账户有余额（在 console.anthropic.com 查看）
  • 确认 Key 没有过期或被撤销

Q3：响应很慢

  • Sonnet 模型：标准速度，适合日常使用
  • Haiku 模型：最快，适合简单任务
  • Opus 模型：最慢但最强，适合架构和深度分析

Q4：上下文窗口不够

  • 使用 /compact 命令压缩上下文
  • 用子代理处理独立任务，保持主窗口整洁
  • 在 CLAUDE.md 中设置精简的项目规范

Q5：Claude Desktop 3P 模型下拉框为空

这是因为 inferenceModels 注册表项没有设置。参见 方案三 中的 PowerShell 命令手动写入。

八、安全注意事项

  1. 不要把 API Key 硬编码在代码里——用环境变量
  2. 不要在公共仓库中提交 .env 文件——加入 .gitignore
  3. 第三方代理服务要谨慎选择——敏感项目优先用官方 API
  4. 定期轮换 API Key——降低泄露风险
  5. 设置使用限额——在 Anthropic Console 中配置月度预算上限

九、快速上手检查清单

安装完成后，对照这个清单确认一切就绪：

  • [ ] Node.js v18+ 已安装（node -v 验证）
  • [ ] Claude Code 已安装（claude --version 验证）
  • [ ] API Key 已设置（$env:ANTHROPIC_API_KEY 非空）
  • [ ] 代理已配置（$env:HTTPS_PROXY 非空）
  • [ ] 能正常对话（claude "hello" 有响应）
  • [ ] 项目目录有 CLAUDE.md（可选但推荐）

评论

发表评论

此博客中的热门博文

GUI.for.SingBox 配置指南：告别 JSON，图形界面搞定一切

-
从下载安装到规则分流，手把手教你用 GUI.for.SingBox 图形界面客户端——不用手写一行 JSON，轻松管理 sing-box 全部功能。 一、GUI.for.SingBox 是什么 一句话定义 ：GUI.for.SingBox 是 sing-box 内核的图形界面配置管理前端。它本身不是代理程序，而是通过 GUI 操作自动生成 sing-box 的 JSON 配置文件并驱动内核运行。 为什么需要它 ：sing-box 原生只提供命令行 + JSON 配置，手写 JSON 配置对大多数人来说门槛太高。GUI.for.SingBox 把所有配置项变成可视化表单，点击填选即可，完全不需要接触 JSON。 1.1 核心功能一览 功能 说明 多协议支持 VLESS / VMess / Trojan / Shadowsocks / Hysteria2 / TUIC / Reality / NaiveProxy 订阅管理 支持 sing-box JSON、Clash YAML、URI 列表格式的一键导入 节点转换插件 自动将 V2Ray/Clash 格式订阅转为 sing-box 格式 分流控制 规则分流 / 直连 / 全局代理三种模式 TUN 透明代理 创建虚拟网卡，接管全部系统流量 策略组 手动选择 / 自动测速（urltest）/ 负载均衡 路由规则 域名 / IP / 进程 / 协议 / 规则集，完整可视化配置 DNS 管理 服务器 / DNS 规则 / FakeIP，全图形化 规则集 远程规则集自动下载更新，支持 SRS 二进制格式 插件系统 Sub-Store / 广告拦截 / 速度测试 / IP 查询等 配置导出 一键生成完整 sing-box JSON 配置文件 跨平台 Windows / macOS / Linux 1.2 与其他客户端对比 对比维度 GUI.for.SingBox Karing Clash Verge Rev V2RayN 内核 sing-box sing-box mihomo v2ray/xray 配置方式 GUI 表单 → 自动生成 JSON GUI +...
阅读全文

Claude Code 采用cc-switch配置第三方模型的完全指南

-
从零开始，手把手带你安装 Claude Code 和 cc-switch，实现无需翻墙、一键切换国产大模型，丝滑开启 AI 编程。 0. 写在前面：这篇教程解决什么问题 你可能已经听说过 Claude Code —— Anthropic 官方的终端 AI 编程助手，能直接在命令行里读代码、写代码、跑测试、操作 Git。但国内用户上手时，往往卡在三道坎上： 网络不通 ：Claude Code 需要连接 Anthropic API，国内直连基本超时 账号难搞 ：Anthropic 官方账号需要海外手机号注册 模型切换麻烦 ：今天想用 Claude，明天想试 DeepSeek，每次手动改配置文件 cc-switch 就是来填这些坑的。它是一个跨平台桌面应用，专为 Claude Code 等 AI 命令行助手设计，核心能力是： 图形化管理多个 API 供应商，一键切换模型，自动完成协议转换 。 读完这篇，你将拥有一个开箱即用的 AI 编程环境 —— 无论选择 Claude 中转还是国产大模型，都能在终端里直接 claude 开干。 一、cc-switch 是什么？适不适合你？ 1.1 一句话说清楚 cc-switch 是一个本地运行的 API 路由 + 配置管理器。它不卖模型额度，也不替你聊天，而是帮你： 管理多个 API 供应商的配置（Key、地址、模型名） 一键切换不同供应商，不用手改 settings.json 自动完成协议转换（Anthropic 格式 ↔ OpenAI 格式 ↔ 国产模型格式） 支持本地代理模式，让 Claude Desktop 也能用第三方模型 数据流长这样 ： Claude Code (终端) ↓ 发起 Anthropic 格式请求 cc-switch (本地代理) ├─ 解析请求头与 Body ├─ 匹配当前启用的供应商 ├─ 协议转换：Anthropic → 目标模型兼容格式 ├─ 替换鉴权 Key、注入 System Prompt ├─ 转发至目标 API └─ 接收响应 → 逆向转换 → 返回 Claude Code 期望的格式 1.2 你需要 cc-switch 吗 场景 需要？ 只有官方 Claude ...
阅读全文