Claude Code 上手指南：安装、部署、接入大模型（超详细）

摘要：本文是一份面向新手的 Claude Code 完整上手指南，从环境准备、安装方式、登录与 API Key 配置，到接入第三方大模型（兼容 Anthropic 协议的中转服务、本地模型网关），再到常用命令、项目级配置、权限管理与常见问题排查，逐步带你跑通第一个真实项目。

一、Claude Code 是什么

Claude Code 是 Anthropic 推出的命令行 AI 编程助手。它不是一个独立的 IDE 插件，而是运行在终端里的 Agent：能够读取你的项目文件、执行命令、修改代码、运行测试，并根据结果自我修正。

它的几个关键特点：

• 终端原生：直接在项目根目录启动，天然理解当前工作区。
• 工具调用能力强：可以读写文件、执行 shell 命令、搜索代码、调用 Git。
• 上下文感知：自动加载 CLAUDE.md 等项目说明文件，形成长期项目记忆。
• 可扩展：支持 MCP（Model Context Protocol）接入外部工具与数据源。

下面这张图概括了它的整体工作方式：

flowchart LR
    U[开发者终端] --> CLI[Claude Code CLI]
    CLI --> A[Agent 循环]
    A --> T[工具层: 读写文件 / 执行命令 / 搜索]
    T --> P[本地项目文件]
    A --> M[大模型 API]
    M --> A
    A --> R[代码修改与结果反馈]
    R --> U

二、环境准备

2.1 系统与硬件要求

2.2 检查 Node.js 版本

node -v
npm -v

如果版本过低，推荐用 nvm 管理：

# 安装 nvm（macOS / Linux）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
重新加载 shell 配置
source ~/.bashrc
安装并使用 Node 20
nvm install 20
nvm use 20
node -v

Windows 用户建议先安装 WSL2，再在 Ubuntu 子系统中按上面的步骤操作，可以避免大量路径与权限问题。

三、安装 Claude Code

3.1 使用 npm 全局安装

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

安装完成后验证：

claude --version

能正常输出版本号即表示安装成功。

3.2 使用官方安装脚本（推荐）

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

该脚本会自动检测系统架构、下载对应二进制并配置 PATH，适合不想折腾 Node 环境的用户。

3.3 常见安装问题

• 权限报错 EACCES：不要用 sudo npm install -g，应配置 npm 全局目录，或改用 nvm。
• 命令找不到：检查 npm bin -g 输出目录是否在 PATH 中。
• 下载缓慢：可临时切换 npm 镜像源，但安装完成后建议切回官方源。

四、首次启动与登录

4.1 进入项目目录启动

cd /path/to/your-project
claude

首次启动会引导你完成认证。Claude Code 支持两种方式：

1. 订阅账号登录：浏览器授权，适合个人开发者。
2. API Key 方式：适合团队、CI 环境或需要接入第三方模型网关的场景。

4.2 使用 API Key

export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxxxxx"

建议写入 shell 配置文件（~/.bashrc 或 ~/.zshrc），避免每次手动设置：

echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc

安全提示：不要把 API Key 提交到 Git 仓库。项目里请把 .env、.claude/ 中的敏感配置加入 .gitignore。

五、接入大模型

Claude Code 默认调用 Anthropic 官方 API。如果你的网络环境受限，或希望使用其他模型，可以通过环境变量把请求指向兼容 Anthropic 协议的服务。

5.1 核心环境变量

5.2 接入兼容 Anthropic 协议的中转服务

export ANTHROPIC_BASE_URL="https://your-gateway.example.com"
export ANTHROPIC_AUTH_TOKEN="your-token"
export ANTHROPIC_MODEL="claude-sonnet-4-20250514"
claude

要点说明：

• ANTHROPIC_BASE_URL 只写到域名或前缀，不要带 /v1/messages，SDK 会自动拼接路径。
• 中转服务必须实现 /v1/messages 接口，并支持流式返回（SSE），否则会出现长时间无响应。
• 模型名称要与网关实际支持的名称一致，写错通常返回 404 或 model not found。

5.3 接入本地模型网关

如果希望使用本地部署的模型，可以搭一层协议转换网关，把 Anthropic 请求转换为 OpenAI 兼容格式。以常见的 one-api / new-api 类网关为例：

# 1. 启动网关服务（示例端口 3000）
docker run -d --name ai-gateway -p 3000:3000 \
  -v /data/gateway:/data \
  your-gateway-image:latest
2. 在网关后台添加渠道，填入本地模型服务地址
例如 http://127.0.0.1:11434/v1
3. 创建令牌，然后在终端配置
export ANTHROPIC_BASE_URL="http://127.0.0.1:3000"
export ANTHROPIC_AUTH_TOKEN="sk-网关生成的令牌"
export ANTHROPIC_MODEL="你配置的模型名"
claude

验证连通性：

curl -s http://127.0.0.1:3000/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-网关生成的令牌" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "你配置的模型名",
    "max_tokens": 64,
    "messages": [{"role": "user", "content": "ping"}]
  }'

返回 JSON 中包含 content 字段即表示链路正常。

5.4 多环境配置建议

把不同环境的配置写进独立脚本，切换时 source 即可：

# ~/.claude-env/official.sh
export ANTHROPIC_API_KEY="sk-ant-xxx"
unset ANTHROPIC_BASE_URL
unset ANTHROPIC_AUTH_TOKEN
~/.claude-env/gateway.sh
export ANTHROPIC_BASE_URL="https://your-gateway.example.com"
export ANTHROPIC_AUTH_TOKEN="your-token"
export ANTHROPIC_MODEL="claude-sonnet-4-20250514"

source ~/.claude-env/gateway.sh
claude

六、项目级配置：CLAUDE.md

CLAUDE.md 是 Claude Code 的项目记忆文件，每次会话都会自动读取。写得好，能显著减少来回沟通。

# 项目说明
技术栈
后端：Java 17 + Spring Boot 3
前端：Vue 3 + Vite
数据库：MySQL 8
代码规范
统一使用 4 空格缩进
类名使用大驼峰，方法名使用小驼峰
禁止在 Controller 中写业务逻辑
常用命令
启动：mvn spring-boot:run
测试：mvn test
打包：mvn clean package -DskipTests
注意事项
不要修改 src/main/resources/application-prod.yml
新增接口必须同步更新 docs/api.md

建议放在项目根目录，并提交到仓库，让团队成员共享同一份约定。

七、常用命令与交互技巧

几个实用技巧：

• 用 @文件路径 显式引用文件，比让模型自己搜索更省 token。
• 描述任务时给出验收标准，例如“改完后 mvn test 必须全部通过”。
• 长任务拆成小步，每步确认后再继续，避免一次性大改难以回滚。
• 重要改动前先让 Claude Code 执行 git status，确保工作区干净。

八、权限与安全

Claude Code 在执行命令和修改文件前会请求授权。建议遵循以下原则：

1. 最小权限：只对必要的命令设置自动允许，例如 git status、ls。
2. 危险命令白名单外：rm -rf、git push --force、数据库删除语句一律手动确认。
3. 隔离环境：在容器或独立分支中运行，避免误改生产配置。
4. 密钥隔离：不要把生产密钥放进项目目录，使用环境变量或密钥管理服务。

九、常见问题排查

9.1 启动报认证失败

• 检查 ANTHROPIC_API_KEY 是否有多余空格或引号。
• 确认 Key 未过期、额度未用尽。
• 使用网关时，确认 ANTHROPIC_BASE_URL 与 ANTHROPIC_AUTH_TOKEN 配套使用。

9.2 请求超时或长时间无响应

• 确认网关支持 SSE 流式返回。
• 检查代理设置，必要时设置 HTTPS_PROXY。
• 用 5.3 节的 curl 命令单独验证接口连通性。

9.3 模型返回 404

通常是模型名称不匹配。用 /model 查看当前模型，并与网关后台配置的名称逐字比对。

9.4 修改后代码无法编译

让 Claude Code 直接运行构建命令，把报错贴回给它，通常能自行修复。若反复失败，用 /clear 重开上下文，并补充更明确的约束。

十、实战：用 Claude Code 跑通第一个任务

前面几节把环境和模型入口都配好了，这一节用一个真实场景把流程串起来。假设你手上有一个 Spring Boot + Vue 的示例项目 demo-shop，后端在 backend/，前端在 frontend/，现在要给商品模块新增一个「按关键字分页查询」的接口，并补上单元测试。

10.1 进入项目并启动 Claude Code

先确认工作区是干净的，再在项目根目录启动：

cd ~/workspace/demo-shop
git status
claude

启动后 Claude Code 会读取根目录的 CLAUDE.md，自动获得技术栈、代码规范和常用命令，不需要你再重复交代一遍。

10.2 用 @ 引用关键文件

与其让模型自己去搜索，不如直接把关键文件喂给它，既省 token 也更准确。在输入框里用 @ 加路径即可引用：

@backend/src/main/java/com/demo/shop/controller/ProductController.java
@backend/src/main/java/com/demo/shop/service/ProductService.java
@backend/src/main/java/com/demo/shop/mapper/ProductMapper.java
@backend/src/test/java/com/demo/shop/service/ProductServiceTest.java

引用完成后，Claude Code 会把这些文件的内容加载进上下文，并在回复中列出它读到的关键方法签名，方便你确认没有引错文件。

10.3 下达任务指令

指令要写清楚「做什么、改哪里、怎么算完成」，下面是一条可以直接复用的输入：

在 ProductController 中新增一个接口：
GET /api/products/search?keyword=xxx&page=1&size=10
要求：
返回分页结果，字段包含 list、total、page、size
keyword 为空时返回全部商品，按 id 倒序
Service 层新增 searchProducts 方法，Mapper 用 MyBatis 的 XML 写 SQL
在 ProductServiceTest 中补单元测试，覆盖「有关键字」和「关键字为空」两种情况
不要修改 application-prod.yml，新增接口同步更新 docs/api.md
验收标准：mvn test 全部通过，且不出现新的编译警告。

10.4 Claude Code 的执行过程

收到指令后，它不会一次性把代码全写完，而是按「读 → 改 → 验证」的循环推进。下面是典型的输出节奏：

Claude Code：我先看一下现有的 ProductController 和 ProductService 结构，确认分页对象的复用方式。

已读取 4 个文件。发现项目里已有 PageResult<T> 通用分页类，我会直接复用它，不新建 DTO。

接下来我会：
1. 在 ProductService 中新增 searchProducts(String keyword, int page, int size)
2. 在 ProductMapper 与对应 XML 中新增 searchByKeyword 查询
3. 在 ProductController 中新增 GET /api/products/search
4. 补充 ProductServiceTest 的两个用例
5. 更新 docs/api.md

是否允许我修改以上 5 个文件？

确认后它会逐个文件给出 diff，并在每次写文件前请求授权：

Claude Code：已修改 ProductService.java，新增方法如下：

public PageResult<Product> searchProducts(String keyword, int page, int size) {
    int offset = (page - 1) * size;
    String kw = (keyword == null || keyword.isBlank()) ? null : keyword.trim();
    List<Product> list = productMapper.searchByKeyword(kw, offset, size);
    long total = productMapper.countByKeyword(kw);
    return new PageResult<>(list, total, page, size);
}

下一步修改 Mapper XML，需要写入 backend/src/main/resources/mapper/ProductMapper.xml，是否继续？

10.5 运行测试验证

代码改完后，让它自己跑一遍构建，把结果作为验收依据：

mvn -f backend/pom.xml test

Claude Code：执行 mvn -f backend/pom.xml test，结果如下：

Tests run: 18, Failures: 0, Errors: 0, Skipped: 0
BUILD SUCCESS

新增的 2 个用例均已通过。另外我注意到 ProductServiceTest 中有一处未使用的 import，已顺手删除，避免编译警告。

如果测试失败，直接把报错贴回去即可，它会定位到具体行并给出修复方案，例如：

你：测试报 NullPointerException，在 ProductServiceTest#searchWithEmptyKeyword 第 42 行。

Claude Code：原因是 mock 的 countByKeyword(null) 未设置返回值，默认返回 0，导致分页对象构造时校验失败。我会补上 when(productMapper.countByKeyword(null)).thenReturn(20L)，然后重新执行测试。

10.6 小结：验收标准怎么写

这一节最关键的经验是：把验收标准写进指令里，而不是等结果出来再判断。一条好的验收标准通常包含三层：

• 可执行的命令：明确写出 mvn test、npm run build 这类能一键验证的命令，让模型自己跑、自己看结果。
• 可判定的结果：不要写「功能正常」，而要写「18 个用例全部通过」「接口返回 200 且 list 长度等于 10」这类非黑即白的条件。
• 不可越界的约束：把「不要改 application-prod.yml」「不要新增第三方依赖」这类红线一并写进去，减少事后返工。

把这三层写清楚，Claude Code 的执行路径会明显收敛，你只需要在关键节点做确认，而不是逐行 review 它写的每一行代码。

十一、总结

Claude Code 的上手路径可以归纳为四步：装好环境 → 完成认证 → 配好模型入口 → 写好 CLAUDE.md。前两步决定能不能跑起来，后两步决定用起来顺不顺手。建议先在个人小项目里跑通完整流程，再逐步引入团队规范与权限策略。