Claude Code 安装配置使用指南

1. 什么是 Claude Code

Claude Code 是 Anthropic 推出的一款终端 AI 编程代理工具 ，与传统代码补全插件（如 Copilot）不同，它是任务驱动型的------你描述目标，它会自主规划步骤、读取项目代码、执行命令、修改文件。它直接运行在终端中，与开发者的原生工作流深度融合。

核心能力：

实时代码生成、解释与优化
多语言支持（Python、JavaScript、Java、Go 等）
可直接执行 Shell 命令、操作 Git
支持 MCP 协议扩展，连接外部工具和数据源
自然语言交互，无需依赖图形界面

2. 安装前的环境准备

2.1 系统要求

要求项	说明
操作系统	macOS 13+ / Ubuntu 20.04+ / Debian 10+ / Windows 10+（需 Git Bash 或 WSL）
Node.js	版本 ≥ 18.0
RAM	建议 8 GB 及以上
Git	2.23 及以上（推荐）

2.2 安装 Node.js

Claude Code 依赖 Node.js 运行环境。在终端中执行 node -v 检查是否已安装，若版本低于 18.0 或未安装，参考以下方式：

macOS（使用 Homebrew）：

bash 复制代码

brew install node

Ubuntu/Debian：

bash 复制代码

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

Windows： 访问 nodejs.org 下载 LTS 版本安装包，安装时勾选 "Add to PATH"。

3. 安装 Claude Code

3.1 方式一：原生安装脚本（推荐）

这是 Anthropic 官方推荐的安装方式，会自动处理依赖并支持后台自动更新：

bash 复制代码

curl -fsSL https://claude.ai/install.sh | bash
claude --version  # 验证安装

3.2 方式二：npm 全局安装

bash 复制代码

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

安装完成后验证：

bash 复制代码

claude --version

注意：Anthropic 已逐步弃用 npm 安装方式，建议优先使用原生安装脚本。若已用 npm 安装，可运行 claude install 迁移到原生版本。

3.3 方式三：Homebrew 安装（macOS）

bash 复制代码

brew install --cask claude-code

Homebrew 安装不会自动更新，需定期运行 brew upgrade claude-code 。

4. 配置 API 密钥

4.1 获取 API Key

访问 Anthropic 官网 Console
注册/登录账号，进入 API Keys 页面
点击 Create Key ，为密钥命名（如 claude-code-local）
立即复制保存------密钥仅显示一次，关闭页面后将无法再次查看
新账号通常有 5 美元免费额度

4.2 配置方式一：settings.json（推荐）

Claude Code 支持通过 settings.json 文件统一管理配置，更清晰、便于版本控制。

创建全局配置文件 ~/.claude/settings.json：

bash 复制代码

mkdir -p ~/.claude

编辑文件内容：

json 复制代码

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-your-api-key-here",
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com"
  },
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

密钥安全提示：

使用 ANTHROPIC_AUTH_TOKEN 而非硬编码到代码中

通过 permissions.deny 阻止 AI 读取 .env 等敏感文件

不要将包含真实密钥的配置文件提交到 Git

项目级配置 （可选）：在项目根目录创建 .claude/settings.json，配置优先级高于全局配置。

4.3 配置方式二：环境变量

若习惯使用环境变量，在 Shell 配置文件（~/.zshrc 或 ~/.bashrc）中添加：

bash 复制代码

# Anthropic API 配置
export ANTHROPIC_AUTH_TOKEN="sk-your-api-key-here"
export ANTHROPIC_BASE_URL="https://api.anthropic.com"

保存后执行 source ~/.zshrc（或 source ~/.bashrc）使配置生效。

4.4 使用第三方 API 兼容服务

国内用户或希望使用其他模型的开发者，可配置第三方兼容 Anthropic API 的服务：

服务商	Base URL	说明
七牛云 AI	`https://api.qnaigc.com`	支持 Kimi、DeepSeek 等模型
硅基流动	`https://api.siliconflow.cn/`	需注册获取 API Key
金山云星流	`https://kspmas.ksyun.com`	企业级 API 服务

配置示例（以七牛云为例）：

json 复制代码

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-your-qiniu-key",
    "ANTHROPIC_BASE_URL": "https://api.qnaigc.com",
    "ANTHROPIC_MODEL": "moonshotai/kimi-k2-thinking"
  }
}

5. 启动与验证

5.1 首次启动

在终端中进入项目目录，运行：

bash 复制代码

claude

首次启动时，Claude Code 会：

请求当前目录的访问授权
显示欢迎信息和配置状态
进入交互式对话界面

5.2 验证配置

在 Claude Code 交互界面中输入 /status，检查：

✅ Base URL 正确显示
✅ API Key 状态为"已设置"
✅ 模型配置正确

6. 核心命令与工具使用

6.1 高频斜杠命令

命令	用途	使用场景
`/init`	扫描项目生成 `CLAUDE.md`	新项目接入时首次使用，让 AI 理解项目结构
`/model`	切换使用的模型	简单任务切小模型节省 Token
`/cost`	查看本次会话费用	控制成本
`/clear`	清空对话历史	切换任务时避免上下文干扰
`/compact`	压缩当前对话上下文	对话过长时保持 AI 聚焦
`/review`	让 AI 做 Code Review	提交代码前检查
`/mcp`	管理 MCP 服务器	接入外部工具

6.2 交互前缀与修饰符

语法	作用	示例
`@文件路径`	引用文件作为上下文	`请 review @src/utils/auth.ts`
`!命令`	执行终端命令，输出作为上下文	`! npm run test`
`#信息`	存入 AI 长期记忆	`# 本项目使用 TypeScript 严格模式`
`think hard` / `ultrathink`	扩展思考深度（复杂任务）	`ultrathink 帮我设计这个模块的架构`

6.3 键盘快捷键

快捷键	功能
`Ctrl + C`	打断当前 AI 执行
`Ctrl + O`	切换详细输出，查看 AI 思考过程
`Shift + Tab`	切换权限模式（确认模式 ↔ 自动执行）
`Esc + Esc`	撤销上一次文件改动（救命键）
`Shift + Enter`	多行输入换行

6.4 三种交互模式

模式	切换方式	说明
Interactive	默认	每步操作需人工确认
Auto-accept	`Shift + Tab`	AI 自动执行，适合简单明确任务
Plan	连按两次 `Shift + Tab`	仅制定计划，不修改代码

7. 进阶功能配置

7.1 MCP 服务器：连接外部工具

MCP（Model Context Protocol）让 Claude Code 能调用数据库、API、浏览器等外部工具。

添加 MCP 服务器示例（以 Context7 文档查询工具为例）：

bash 复制代码

claude mcp add --transport http context7 https://api.context7.com

三种传输方式：

HTTP：适合远程服务调用
SSE：服务端推送，适合流式数据
Stdio：本地进程通信，最常用

7.2 自定义命令

在 ~/.claude/commands/（全局）或 .claude/commands/（项目级）创建 .md 文件，即可定义专属命令。

示例：创建 ~/.claude/commands/optimize.md

markdown 复制代码

分析这段代码的性能问题，并提出优化建议。重点关注：
- 算法效率
- 内存使用模式
- 数据库查询优化
- 缓存使用可能性

使用时直接输入 /optimize 即可调用。

7.3 Hooks 钩子：自动化工作流

在关键事件节点自动触发自定义脚本：

事件	触发时机
`PreToolUse`	工具调用前（如执行命令前做安全检查）
`PostToolUse`	工具调用后（如自动运行 `eslint --fix`）
`SessionStart`	会话启动时
`PreCompact`	上下文压缩前

8. VS Code 插件集成

8.1 安装与配置

在 VS Code 扩展商店搜索 Claude Code for VS Code（蓝色机器人图标）并安装
点击扩展齿轮图标 → Extension Settings
配置 API Key 和 Base URL（同 CLI 配置）
或在 settings.json 中添加：

json 复制代码

{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://api.anthropic.com" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-****" }
  ]
}

8.2 常用 VS Code 快捷键

快捷键	功能
`Cmd/Ctrl + Esc`	启动 Claude Code
`Cmd/Ctrl + Option + K`	将选中代码添加到 Claude 上下文

9. 常见问题排查

问题	可能原因	解决方案
`Invalid API Key`	密钥错误或未生效	检查是否含多余空格；重启终端；确认配置文件中 `ANTHROPIC_AUTH_TOKEN` 已正确设置
`Model not found`	模型名错误	使用 `/status` 检查配置；确认第三方服务的模型名称正确
终端显示 `offline`	网络检测服务不可达	不影响核心功能，只要能连接 API 地址即可
`fetch failed`	网络无法访问 Base URL	检查代理设置；尝试切换备用 Base URL
对话越来越慢	上下文过长	使用 `/compact` 压缩或 `/clear` 清空
Windows 下命令无效	缺少 Git Bash	安装 Git for Windows

10. 最佳实践总结

首次使用先 /init：让 AI 生成项目理解文件，后续交互更精准
复杂任务先规划 ：使用 Plan 模式或 ultrathink 让 AI 先出方案再执行
善用 # 长期记忆：将项目约定、技术栈等关键信息存入记忆
密钥不进 Git ：用环境变量或 settings.json，并在 .gitignore 中加入 .claude/
选对模型省成本：简单任务用 Haiku 或第三方高性价比模型，复杂推理再用 Sonnet/Opus
Esc + Esc 是救命键：AI 改坏了代码双击 Esc 即可回退

Claude Code 安装配置使用指南