Claude Code 安装与配置：从入门到终端编程

引言

Claude Code 是 Anthropic 推出的终端 AI 编程助手，直接运行在你的命令行中。与需要打开浏览器或 IDE 插件的传统 AI 编程工具不同，Claude Code 让你在终端中通过自然语言完成代码编写、文件操作、Git 管理、项目构建等全流程开发任务。

本文将从零开始，带你完成 Claude Code 的安装、配置和首次使用。

安装前提

系统要求

Windows 用户注意：Claude Code 需要 Unix 环境，在 Windows 上请使用 WSL2（Windows Subsystem for Linux）。不支持 PowerShell 或 CMD 直接运行。

验证 Node.js 环境

在开始安装前，先确认你的 Node.js 环境：

node --version
# 输出示例：v20.11.0

npm --version
# 输出示例：10.2.4

如果版本低于要求，请先升级 Node.js：

# 使用 nvm 安装最新 LTS 版本
nvm install --lts
nvm use --lts

# 或者使用系统包管理器
# macOS: brew install node
# Ubuntu/Debian: sudo apt install nodejs npm

安装 Claude Code

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

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

安装完成后，验证是否成功：

claude --version
# 输出示例：@anthropic-ai/claude-code/0.2.29

方式二：使用 npx 直接运行（无需安装）

npx @anthropic-ai/claude-code

这种方式不需要全局安装，适合临时使用或测试。但每次运行都需要下载，建议日常使用还是采用全局安装。

安装过程中的常见问题

问题：权限错误（EACCES）

npm ERR! Error: EACCES: permission denied

解决方案：使用 npm 的 prefix 配置避免全局权限问题：

# 方案 A：配置 npm prefix
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

# 方案 B：使用 nvm 管理 Node（推荐）
# nvm 安装的 Node 默认在用户目录下，不会出现权限问题

问题：安装速度慢

# 使用国内镜像加速
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

配置 API 密钥

Claude Code 需要通过 Anthropic API 访问 Claude 模型，因此需要配置 API 密钥。

获取 API 密钥

1. 访问 console.anthropic.com
2. 注册或登录 Anthropic 账户
3. 进入 API Keys 页面
4. 点击 Create Key 创建新的 API 密钥
5. 复制密钥并妥善保存（创建后只会显示一次）

配置 API 密钥

方式一：环境变量（推荐）

将密钥添加到 shell 配置文件（~/.zshrc 或 ~/.bashrc）：

export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

然后重新加载配置：

source ~/.zshrc

方式二：直接传参

claude --api-key sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

方式三：配置文件

在 ~/.claude/settings.json 中配置：

{
  "apiKey": "sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

可用额度与计费

Claude Code 按 token 计费，使用 Anthropic API 的付费账户：

免费额度：新注册 Anthropic API 账户通常可获得 $5 的免费试用额度，足以完成数百次简单的编程交互。Opus 模型更贵，建议先用 Sonnet 进行日常开发。

费用估算示例：

• 一次简单的代码审查：约 2K-5K tokens → 约 $0.01-0.03
• 一次完整的代码生成任务：约 10K-20K tokens → 约 $0.05-0.15
• 全天高强度使用（100+次交互）：约 $5-15

首次启动

配置完成后，在终端中直接运行：

claude

首次启动时，Claude Code 会：

1. 显示欢迎信息和版本号
2. 检查 API 密钥是否配置正确
3. 初始化项目上下文（如在工作目录中启动）
4. 进入交互式 REPL 模式

启动后的交互界面示例：

╭──────────────────────────────────────────────╮
│  ✦ Claude Code (v0.2.29)                     │
│  Type /help for available commands           │
│  Press Ctrl+C to exit                        │
╰──────────────────────────────────────────────╯

  ┌─ Project: my-app ──────────────────────────┐
  │  README.md         package.json            │
  │  src/              tests/                  │
  └────────────────────────────────────────────┘

  > 

常用配置项

全局配置文件

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

{
  "apiKey": "sk-ant-xxxxxxxxxxxx",
  "model": "claude-sonnet-4",
  "permissions": {
    "allowCommands": ["npm", "node", "git", "python", "docker", "make"],
    "denyCommands": ["rm -rf /", "sudo", "chmod -R"]
  },
  "editor": {
    "theme": "dark",
    "showTokens": false
  }
}

项目级配置文件

在项目根目录创建 .claude/settings.json：

{
  "project": {
    "name": "my-app",
    "buildCommand": "npm run build",
    "testCommand": "npm test",
    "lintCommand": "npm run lint"
  },
  "ignorePatterns": ["node_modules", "dist", ".next"],
  "permissions": {
    "allowPaths": ["/home/user/projects/my-app"],
    "denyPaths": ["/home/user/projects/my-app/.env", "/etc"]
  }
}

关键配置项速查

模型选择建议

Sonnet vs Opus

选择策略

推荐方案：默认使用 Sonnet，按需切换到 Opus

# 日常使用 Sonnet（默认）
claude

# 遇到复杂问题时切换到 Opus
claude --model claude-opus-4

# 或者使用配置文件指定默认模型
# ~/.claude/settings.json → "model": "claude-sonnet-4"

实践经验：

• 代码生成、重构、测试编写 → Sonnet 完全够用，速度快成本低
• 架构设计评审、复杂算法实现、安全漏洞分析 → Opus 更可靠
• 长时间会话中，可以先让 Sonnet 处理基础部分，遇到难题时切换到 Opus

MCP 服务器配置

MCP（Model Context Protocol）允许你为 Claude Code 添加自定义工具。

配置 MCP 服务器

在 ~/.claude/settings.json 中添加 mcpServers 配置：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/home/user/projects"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxx"
      }
    },
    "sqlite": {
      "command": "uvx",
      "args": ["mcp-server-sqlite", "--db-path", "./test.db"]
    }
  }
}

验证 MCP 连接

启动 Claude Code 后，使用 /mcp 命令查看已连接的 MCP 服务器：

> /mcp list

已连接的 MCP 服务器：
  ✅ filesystem - 文件系统操作工具
  ✅ github - GitHub API 工具（issues, PR, repos）
  ❌ sqlite - 连接失败，请检查数据库路径

常用 MCP 服务器推荐

ACP 运行模式

ACP（Agent Communication Protocol）允许 Claude Code 与其他 Agent 协同工作。

启动子 Agent

# 方式一：在当前会话中启动子 Agent
claude --acp-mode child --parent-pipe /tmp/claude-acp-main

# 方式二：通过文件描述符连接
claude --acp-mode child --parent-fd 3

多 Agent 协作配置

创建一个简单的多 Agent 协作脚本：

#!/bin/bash
# multi-agent.sh - 启动多 Agent 协作

# 启动主 Agent
claude --acp-mode parent --pipe /tmp/claude-acp-main &
MAIN_PID=$!

# 启动两个子 Agent
claude --acp-mode child --parent-pipe /tmp/claude-acp-main &
CHILD1_PID=$!

claude --acp-mode child --parent-pipe /tmp/claude-acp-main &
CHILD2_PID=$!

# 等待所有进程结束
wait $MAIN_PID $CHILD1_PID $CHILD2_PID

ACP 模式适用于大型项目的任务分解：主 Agent 负责架构设计和任务分配，子 Agent 负责具体模块的实现。

内置命令速查

Claude Code 提供了一系列内置命令：

退出与清理

正常退出

# 在交互界面中输入
/exit
# 或使用快捷键
Ctrl+D

卸载

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

清理配置文件（如果需要完全移除）：

rm -rf ~/.claude

注意事项

安全提醒

1. API 密钥保护：永远不要将 API 密钥提交到 Git 仓库，建议使用 .env 文件或系统环境变量
2. 权限管理：默认使用 ask-first 模式，不要轻易切换到 allow-all
3. 敏感文件：在项目配置中明确禁止访问 .env、id_rsa 等敏感文件
4. 公共环境：在共享服务器上使用 Claude Code 时，注意日志中可能包含代码上下文

性能建议

1. 本地项目优先：在项目根目录启动 Claude Code，自动加载项目上下文效果更佳
2. 合理控制上下文：长时间会话定期使用 /compact 压缩上下文
3. 选择性加载：使用 .claudeignore 排除不必要的目录（类似 .gitignore）
4. 网络稳定：Anthropic API 需要稳定的网络连接，建议使用有线网络或稳定的 Wi-Fi

常见问题排查

Q: 启动时提示 “API key not found”

# 检查环境变量是否设置正确
echo $ANTHROPIC_API_KEY

# 如果为空，重新设置
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxx"

Q: “Model not available” 错误

# 确认当前地区是否支持
# 检查模型名称是否正确
claude --model claude-sonnet-4

Q: 响应速度慢

# 切换到 Sonnet 模型
claude --model claude-sonnet-4

# 或检查网络延迟
ping api.anthropic.com

Q: 上下文不足错误

# 使用 /compact 压缩上下文
/compact

# 或减少会话中的文件操作次数

总结

通过本文的教程，你已经完成了 Claude Code 从安装到配置的完整流程：

1. 安装：npm install -g @anthropic-ai/claude-code
2. 配置：设置 ANTHROPIC_API_KEY 环境变量
3. 模型选择：默认 Sonnet，复杂任务切换到 Opus
4. 工具扩展：通过 MCP 添加自定义工具
5. 多 Agent：使用 ACP 实现 Agent 间协作
6. 安全：使用 PBC/ACL 控制权限

配置好 Claude Code 后，你可以直接在终端中与它对话，让它帮你完成代码编写、调试、重构、测试等各种开发任务。开始你的终端 AI 编程之旅吧！

本文最后更新于 2026-05-09