第一章：安装配置与本地大模型

1.1 安装 Claude Code

Claude Code 是 Anthropic 出品的 CLI 工具，让你在终端里直接与 Claude 对话，执行代码、操作文件、调用工具。

系统要求

• macOS 12+ / Linux / WSL2
• Node.js 18+
• Git

安装命令

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

# 验证安装
claude --version

# 首次启动，按提示登录 Anthropic 账号
claude

国内网络加速

如果 npm 安装慢，换国内源：

npm config set registry https://registry.npmmirror.com
npm install -g @anthropic-ai/claude-code

1.2 配置本地大模型

Claude Code 默认调用 Anthropic 的云端 API（Claude 3.5/4 Sonnet 等）。但如果你希望：

• 节省 API 费用
• 保护代码隐私
• 离线使用

可以配置本地大模型。

支持方式：OpenAI 兼容 API

Claude Code 通过 OpenAI 兼容接口支持本地模型。常见选择：

本地模型方案	特点	推荐场景
Ollama	一键运行，模型丰富	个人开发、快速验证
vLLM	高性能，生产级	团队共享、高并发
LM Studio	图形界面，易用	新手入门

以 Ollama 为例配置

# 1. 安装 Ollama
brew install ollama          # macOS
curl -fsSL https://ollama.com/install.sh | sh  # Linux

# 2. 拉取模型（推荐 Qwen2.5-Coder-32B，代码能力强）
ollama pull qwen2.5-coder:32b

# 3. 启动 Ollama 服务（默认端口 11434）
ollama serve

# 4. 测试模型是否正常工作
curl http://localhost:11434/api/generate -d '{
  "model": "qwen2.5-coder:32b",
  "prompt": "Hello"
}'

配置 Claude Code 使用本地模型

# 设置环境变量指向本地 Ollama
export ANTHROPIC_BASE_URL=http://localhost:11434/v1
export ANTHROPIC_MODEL=qwen2.5-coder:32b

# 启动 Claude Code
claude

# 或者在 .zshrc / .bashrc 中永久配置
echo 'export ANTHROPIC_BASE_URL=http://localhost:11434/v1' >> ~/.zshrc
echo 'export ANTHROPIC_MODEL=qwen2.5-coder:32b' >> ~/.zshrc

⚠️ 注意: 本地模型能力通常弱于 Claude 3.5 Sonnet，复杂任务建议切回云端：unset ANTHROPIC_BASE_URL

配置多个模型快速切换

# 在 ~/.zshrc 中定义快捷命令
alias claude-local='ANTHROPIC_BASE_URL=http://localhost:11434/v1 ANTHROPIC_MODEL=qwen2.5-coder:32b claude'
alias claude-cloud='unset ANTHROPIC_BASE_URL && unset ANTHROPIC_MODEL && claude'

1.3 项目级配置

进入项目目录后，Claude Code 会读取项目配置：

# 进入项目目录
cd my-project

# 启动（自动加载项目配置）
claude

# 查看当前配置
claude config

# 设置权限模式（见第二章详解）
claude config set permission default

项目配置文件位置

my-project/
├── .claude/
│   ├── settings.json       # 项目级设置
│   ├── skills/             # Skill 目录（核心！）
│   │   └── *.md
│   └── CLAUDE.md           # 项目记忆文件
├── src/
└── ...

---

2.2 安装方法

Claude Code 提供了三种安装方式，你可以根据自己的偏好选择。

2.2.1 方法一：官方安装脚本（推荐）

这是最简单、最推荐的安装方式。官方脚本会自动检测你的操作系统，下载正确的二进制文件，并将其安装到合适的位置。

# 使用 curl 运行官方安装脚本
curl -sSL https://claude.ai/install | sh

这个脚本会执行以下操作：

1. 检测你的操作系统和架构（x64 / ARM64）
2. 从 Anthropic 服务器下载最新版本的 Claude Code
3. 将可执行文件安装到 ~/.local/bin/claude（Linux）或 /usr/local/bin/claude（macOS）
4. 如果必要，将安装目录添加到你的 PATH 环境变量

验证安装：

claude --version

预期输出：

claude version 0.2.x

如果看到版本号，说明安装成功。

2.2.2 方法二：包管理器安装

如果你更喜欢使用系统的包管理器，可以通过以下方式安装。

macOS（使用 Homebrew）：

# 添加 Anthropic 的 Homebrew 仓库（如果官方提供）
brew install claude-code

注意：截至本书写作时，Claude Code 可能尚未进入官方 Homebrew 核心仓库。如果上述命令失败，请使用官方安装脚本，或者通过以下方式安装：

# 下载最新 release
curl -L -o claude https://github.com/anthropics/claude-code/releases/latest/download/claude-darwin-$(uname -m)
chmod +x claude
sudo mv claude /usr/local/bin/

Linux（使用 npm）：

虽然 Claude Code 本身不是 Node.js 应用，但你可以通过 npm 安装它的封装包：

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

Arch Linux（使用 AUR）：

Arch 用户可以通过 AUR 安装：

yay -S claude-code
# 或者
paru -S claude-code

2.2.3 方法三：手动安装

如果你需要精确控制安装过程，或者处于没有网络访问权限的环境，可以选择手动安装。

步骤 1：下载二进制文件

访问官方发布页面，下载适合你系统的版本：

# macOS Apple Silicon
curl -L -o claude https://github.com/anthropics/claude-code/releases/latest/download/claude-darwin-arm64

# macOS Intel
curl -L -o claude https://github.com/anthropics/claude-code/releases/latest/download/claude-darwin-x64

# Linux x64
curl -L -o claude https://github.com/anthropics/claude-code/releases/latest/download/claude-linux-x64

# Linux ARM64
curl -L -o claude https://github.com/anthropics/claude-code/releases/latest/download/claude-linux-arm64

步骤 2：设置可执行权限

chmod +x claude

步骤 3：移动到 PATH 目录

# 用户级安装
mkdir -p ~/.local/bin
mv claude ~/.local/bin/

# 确保 ~/.local/bin 在 PATH 中
export PATH="$HOME/.local/bin:$PATH"

# 将上述 export 添加到 ~/.bashrc 或 ~/.zshrc 以持久化
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

步骤 4：验证

which claude
claude --version

2.2.4 安装方法对比

安装方式	难度	适用场景	更新方式	离线可用
官方脚本	简单	大多数用户	重新运行脚本	否
包管理器	中等	喜欢系统管理的用户	包管理器更新	否
手动安装	复杂	受限环境、精确控制	手动下载新版本	是（下载后）

2.3 安装验证

安装完成后，建议进行一系列验证，确保 Claude Code 能正常工作。

2.3.1 基础验证清单

# 1. 检查版本
claude --version

# 2. 查看帮助信息
claude --help

# 3. 检查更新
claude update

# 4. 验证自动补全（如果支持）
claude --completion bash > /dev/null && echo "补全脚本生成成功"