Claude Code 安装与配置完全指南：从零到跑通第一个项目

适用平台：Windows / macOS / Linux · 关键词：Claude Code、终端 AI 编程助手、API 接入

前言

AI 编程助手这两年层出不穷，而 Anthropic 推出的 Claude Code 之所以能从中脱颖而出，靠的不是「代码补全」这类小修小补，而是一套完整的 Agentic Coding（智能体编程） 理念。

它更像一位直接坐在你终端里的 AI 同事：你用自然语言描述目标，它自己去读文件、理解代码库、跑命令、提交 Git，最后把活干完。

这篇文章是一份可照着执行的手把手教程，覆盖环境准备 → 跨平台安装 → 网络问题处理 → API Key 配置 → 常见问题排查的完整链路。无论你用的是 Mac、Linux 还是 Windows，都能在这里找到可用的接入方式。

---

一、Claude Code 是什么

Claude Code 是一个运行在终端中的 AI 智能体 。它与 Copilot 这类「预测下一行代码」的工具定位完全不同------你只需要在命令行里描述任务目标，它会自主规划执行步骤：

• 读取相关文件，理解整个代码库的结构；
• 执行 Shell 命令，验证自己的改动；
• 操作 Git，完成提交等版本控制动作；
• 反复迭代，直到任务达成。

它的核心优势可以归纳为三点：

• 上下文感知：通过智能体式搜索主动探索项目，而不是依赖一层静态索引。
• 工具调用 ：可以原生调用 Git、MCP 服务器等外部工具，能力边界可扩展。
• 安全可控：默认在执行高风险操作（写入文件、运行命令）前先向你请求授权。

官方资源：

• 产品官网：Claude Code by Anthropic | AI Coding Agent, Terminal, IDE
• 中文文档：快速开始 - Claude Code Docs

---

二、环境准备

安装之前，先确认你的系统满足以下要求。

2.1 系统支持

平台	版本要求
macOS	10.14+
Linux	Ubuntu 18.04+、CentOS 7+ 以及其他主流发行版
Windows	Windows 10 / 11（推荐使用 PowerShell 或 Git Bash）

2.2 前置依赖

① Node.js

Claude Code 通过 npm 包分发，因此 Node.js 是必需项。按 Win + R 输入 cmd 打开终端，执行以下命令检查版本，要求 16.0 以上，推荐 18+ LTS：

node --version
npm --version

如果尚未安装，前往 nodejs.org 下载并安装长期支持版（LTS）。详细步骤可参考：Node.js 与 npm 的安装与配置（详细教程）。

② Git

Git 的版本没有硬性要求，但必须安装 。原因是 Claude Code 在执行任务时会用到 Git 提供的一个 bash 命令------Git Bash 是 Git for Windows 附带的类 Unix 命令行环境，为 Claude Code 提供了必要的终端执行能力。

用下面的命令验证是否已安装：

git --version

若未安装，可参考：Git 的安装与使用。

---

三、安装 Claude Code

Claude Code 提供两种安装方式。从可控性和可维护性考虑，个人更推荐使用 npm 方式。

3.1 方式一：官方原生安装脚本

官方文档提供了本地安装、Homebrew 安装和 WinGet 安装三种途径，这里直接采用最通用的本地安装命令。

macOS / Linux / WSL：

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

Windows PowerShell：

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

Windows CMD：

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

3.2 方式二：npm 全局安装（推荐）

Linux / macOS：

# 全局安装 Claude Code
sudo npm install -g @anthropic-ai/claude-code

# 验证安装
claude --version

**Windows：**以管理员身份打开 PowerShell 或命令提示符，执行：

# 全局安装
npm install -g @anthropic-ai/claude-code

# 验证安装
claude --version

下文以 Windows 环境为例演示，按 Win + R 输入 cmd 调出命令提示符即可。安装完成后，可通过下面的命令查看帮助文档，确认可用：

claude --help

---

四、处理网络访问限制

安装完成后，直接在终端输入 claude 即可启动：

claude

如果当前网络可以直连外网，Claude Code 会正常启动，先让你选择一个主题，随后提供三种登录方式：

1. 订阅 Claude 账户（专业版 / 高级版 / 团队版 / 企业版）；
2. 使用 API 计费方式；
3. 第三方平台接入。

但更常见的情况是：在国内网络环境下无法直连，启动时会直接报错------

Unable to connect to Anthropic services

Failed to connect to api.anthropic.com: ERR_BAD_REQUEST

出现该错误的根本原因是：Claude Code 会校验请求的位置信息，国内 IP 无法通过校验。

解决思路有两条：① 配置代理网络；② 修改配置绕过 IP 校验。

**实践建议：**更推荐方式二。代理方案依赖本地代理服务的稳定性，而绕过校验后配合第三方 API 使用，链路更短、更稳定。

4.1 方式一：配置代理网络

在当前项目目录下创建 .claude/settings.json：

{
  "env": {
    "HTTP_PROXY": "http://127.0.0.1:7890",
    "HTTPS_PROXY": "http://127.0.0.1:7890"
  }
}

这个配置的作用是：让 Claude Code 在运行时通过你指定的代理服务器（此处为 127.0.0.1:7890）访问外部网络。

4.2 方式二：修改配置绕过 IP 校验（推荐）

进入 C:\Users\{username} 目录，找到 Claude 的 JSON 配置文件 .claude.json，在其中添加以下配置：

"hasCompletedOnboarding": true,

保存后重新启动 Claude Code，此时它就能正常启动了。启动过程中它会询问是否读取当前目录文件；如果选择 Yes 却出现 not login 报错，属于正常现象------因为默认情况下它会使用 Claude Code 自带的 Sonnet 4.6 模型，而该模型需要付费订阅，最低约 $17/月。

因此，我们改用 API 方式接入，完全跳过 Claude Code 账户登录环节。

---

五、配置第三方 API Key

这里以接入 七牛云 和 DeepSeek 的 API 为例。

5.1 获取 API Key 与 BaseURL

接入七牛云 API

1. 进入七牛云 AI 大模型控制台：AI 大模型平台 - 七牛云；
2. 在控制台中创建一个 API Key，例如 sk-c6159***********************783a；
3. 在「模型广场」中选择一个模型，例如 qwen3-coder-480b-a35b-instruct；
4. 找到它对应的 Anthropic BaseURL ：https://api.qnaigc.com。

提示： 模型参数可以不设置。不设置时默认使用 claude-4.6-sonnet。

接入 DeepSeek API

1. 打开 DeepSeek API 开放平台：DeepSeek；
2. 创建一个 API Key；
3. 打开接口文档，即可查到对应的 Anthropic BaseURL 与模型名称。

5.2 方式一：环境变量全局配置

# 临时设置（仅当前窗口生效）
set ANTHROPIC_API_KEY "sk-c6159***********************783a"
set ANTHROPIC_BASE_URL "https://api.qnaigc.com"
# 模型不设置时，默认使用 claude-4.6-sonnet
set ANTHROPIC_MODEL "qwen3-coder-480b-a35b-instruct"

# 永久设置（写入系统环境变量，需重开终端生效）
setx ANTHROPIC_API_KEY "sk-c6159***********************783a"
setx ANTHROPIC_BASE_URL "https://api.qnaigc.com"
setx ANTHROPIC_MODEL "qwen3-coder-480b-a35b-instruct"

5.3 方式二：配置文件内配置

在 C:\Users\{username}\.claude\settings.json 中添加以下配置：

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-c6159***********************783a",
    "ANTHROPIC_BASE_URL": "https://api.qnaigc.com",
    "ANTHROPIC_MODEL": "qwen3-coder-480b-a35b-instruct",
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0"
  }
}

两个易踩的坑：

1. 外层键名必须是 env，不是 evn，写错会导致配置整体失效；

2. 环境变量名使用下划线 CLAUDE_CODE_ATTRIBUTION_HEADER，不要写成带空格的 CLAUDE CODE ATTRIBUTION HEADER。

5.4 两种配置方式怎么选

对比项	环境变量全局配置	settings.json 配置文件
生效范围	整个系统，所有项目	跟随配置文件，可按用户/项目隔离
生效时机	setx 需重开终端	重启 Claude Code 即生效
多 Key 切换	较麻烦，需反复改环境变量	方便，直接改配置文件
适用场景	只用一个 Key，追求一次配好	需要按项目切换模型或服务商

本文采用的是全局配置 方式。配置完成后，即可在项目目录中正常启动 Claude Code。

---

六、常见问题

问题 1：API 已配置好，但运行 claude 仍提示登录

可以关闭当前开发软件，或重新打开一个文件夹后打开命令提示符，再次启动 claude。此时选择 Yes，它会进一步询问是否使用 API key，同样选择 Yes，即可跳过登录直接进入。

问题 2：提示模型不可用

通常是所选模型名称填写有误，或该模型在当前服务商侧未开放。处理方式：更换一个可用模型，或者干脆不设置 ANTHROPIC_MODEL，交由服务端使用默认模型。

---

七、小结

回顾整条链路，核心只有四步：

1. 装好依赖：Node.js（16+，推荐 18+）与 Git 缺一不可；
2. 安装本体 ：npm install -g @anthropic-ai/claude-code 最省心；
3. 解决网络 ：修改 .claude.json 中的 hasCompletedOnboarding 绕过 IP 校验；
4. 接入 API ：通过 ANTHROPIC_API_KEY + ANTHROPIC_BASE_URL + ANTHROPIC_MODEL 三个变量指向第三方服务商。

配置完成后，你就能在终端里用最自然的方式驱动整个项目的开发流程了。