Claude Code 入门：Anthropic 终端编码代理快速上手

TL;DR: Claude Code 是 Anthropic 推出的终端原生 AI 编码代理，通过 claude 命令直接在终端中执行代码编辑、文件操作和命令运行。本教程将带你完成从安装配置到安全沙箱和审批模式的完整入门流程，确保你能够安全、高效地使用这个强大的开发工具。

🎯 学习目标

完成本教程后，你将能够：

在 macOS/Linux 系统上安装并配置 Claude Code
理解并配置安全沙箱机制，保护你的文件系统
掌握审批模式的三种级别，根据项目需求灵活切换
使用 claude 命令完成第一个实际的编码任务

🔧 安装与配置：从零到运行

系统要求

Claude Code 目前支持 macOS 10.15+ 和 Linux（Ubuntu 20.04+、Debian 11+、Fedora 38+）。Windows 用户需要通过 WSL2 使用。

最低硬件要求：

4GB 可用内存
2GB 磁盘空间（用于模型缓存）
稳定的网络连接（API 调用延迟 <500ms）

步骤 1：安装 Node.js 和 npm

Claude Code 基于 Node.js 构建，需要 Node.js 18+ 版本。推荐使用 nvm 管理版本：

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 重新加载 shell 配置
source ~/.bashrc  # 或 source ~/.zshrc

# 安装并切换到 Node.js 20
nvm install 20
nvm use 20

# 验证版本
node --version  # 应输出 v20.x.x
npm --version   # 应输出 10.x.x

步骤 2：安装 Claude Code

通过 npm 全局安装：

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

安装完成后，验证安装：

claude --version
# 输出示例：claude-code/0.1.0 (node v20.11.0)

步骤 3：获取 API 密钥

访问 console.anthropic.com 注册账号
在 API Keys 页面创建新的 API 密钥
设置环境变量：

export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxxxxx"

安全提示：永远不要将 API 密钥硬编码在代码中或提交到版本控制。推荐使用 .env 文件配合 direnv 管理：

# 安装 direnv
brew install direnv  # macOS
# 或 apt install direnv  # Linux

# 在项目根目录创建 .envrc
echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxxxxx"' > .envrc
direnv allow .

步骤 4：首次运行

在任意项目目录中执行：

claude

首次运行会进行以下操作：

下载模型配置文件（约 50MB）
建立 WebSocket 连接
提示你选择审批模式

$ claude
⚡ Initializing Claude Code...
📦 Downloading model configuration... done
🔗 Connecting to API... connected
🔐 Choose approval mode (strict/balanced/off): [strict]

🛡️ 安全沙箱：保护你的文件系统

Claude Code 的安全沙箱是一个关键特性，它控制 AI 代理对文件系统和系统命令的访问权限。理解沙箱机制对于安全使用至关重要。

沙箱的工作原理

Claude Code 使用 路径白名单 机制，默认只允许访问当前工作目录及其子目录。任何尝试访问白名单外路径的操作都会被拦截。

flowchart LR
    A[Claude Code] --> B{路径检查}
    B -->|在白名单内| C[允许访问]
    B -->|不在白名单内| D[拒绝并提示]
    C --> E[执行操作]
    D --> F[请求用户审批]

沙箱配置

沙箱行为通过 .claude/settings.json 文件配置：

{
  "permissions": {
    "allowPaths": [
      "/home/user/projects/my-app",
      "/home/user/shared-libs"
    ],
    "denyPaths": [
      "/etc",
      "/var/log",
      "/home/user/.ssh"
    ],
    "allowCommands": [
      "npm",
      "node",
      "git",
      "python3",
      "pip3"
    ],
    "denyCommands": [
      "rm -rf /",
      "sudo",
      "chmod 777"
    ]
  },
  "sandbox": {
    "enabled": true,
    "networkAccess": "ask",
    "fileWrite": "ask"
  }
}

关键配置项说明：

配置项	类型	默认值	说明
`allowPaths`	string[]	`["."]`	允许 AI 访问的路径
`denyPaths`	string[]	`[]`	明确禁止的路径
`allowCommands`	string[]	`["*"]`	允许执行的命令
`denyCommands`	string[]	`[]`	禁止执行的命令
`sandbox.networkAccess`	string	`"ask"`	网络访问策略：`allow`/`deny`/`ask`
`sandbox.fileWrite`	string	`"ask"`	文件写入策略：`allow`/`deny`/`ask`

实际沙箱行为演示

创建一个测试项目来观察沙箱行为：

mkdir claude-sandbox-test
cd claude-sandbox-test
echo "console.log('Hello, Claude!')" > index.js

启动 Claude Code 并尝试访问外部文件：

claude

在 Claude Code 交互界面中，输入：

Read the contents of /etc/passwd

你会看到类似以下的拦截提示：

⚠️ Security: Attempted to read path outside allowed scope
Path: /etc/passwd
Allowed scope: /home/user/projects/claude-sandbox-test

Would you like to allow this operation? (y/N):

为什么这是重要的：如果没有沙箱，恶意提示词（prompt injection）可能导致 AI 读取你的 SSH 密钥、数据库密码等敏感信息。

进阶沙箱配置：项目级 vs 全局

Claude Code 支持两层沙箱配置：

项目级配置：存放在项目根目录的 .claude/settings.json
用户级配置：存放在 ~/.claude/settings.json

配置合并规则：项目级配置会覆盖用户级配置的对应字段，但 denyPaths 和 denyCommands 会进行交集合并（即两个列表中的禁止项都会生效）。

// ~/.claude/settings.json (用户级)
{
  "permissions": {
    "denyPaths": ["/etc", "/var"],
    "allowCommands": ["npm", "git"]
  }
}

// /project/.claude/settings.json (项目级)
{
  "permissions": {
    "denyPaths": ["/tmp"],
    "allowCommands": ["python3"]
  }
}

// 实际生效的配置：
// denyPaths: ["/etc", "/var", "/tmp"]  (合并)
// allowCommands: ["npm", "git", "python3"]  (合并)

🔐 审批模式：控制 AI 的操作权限

审批模式决定了 AI 在需要执行敏感操作时的行为。Claude Code 提供三种模式，每种模式对应不同的安全级别和开发效率。

模式对比

模式	安全级别	效率	适用场景
`strict`	高	低	生产环境、敏感项目
`balanced`	中	中	日常开发（推荐）
`off`	低	高	个人项目、原型开发

模式详解

1. strict 模式（严格模式）

在 strict 模式下，AI 的所有文件写入、命令执行和网络请求都需要用户确认。

# 启动时指定
claude --approval-mode strict

行为示例：

🤖 AI: I need to create a new file src/utils/helpers.js
🔐 Approval required: Create file "src/utils/helpers.js"
Content preview:
  export function formatDate(date) {
    return date.toISOString().split('T')[0];
  }
Approve? (y/N/diff): y

🤖 AI: I need to run "npm install express"
🔐 Approval required: Execute command "npm install express"
Approve? (y/N): y

优点：完全控制 AI 行为，防止意外修改缺点：频繁确认打断开发流程

2. balanced 模式（平衡模式）

balanced 模式是默认选项，它会智能判断哪些操作需要审批：

自动批准：创建新文件、修改已跟踪的代码文件、运行 npm install 等常见命令
需审批：删除文件、修改配置文件（如 .env）、运行 sudo 命令、网络请求

# 启动时指定
claude --approval-mode balanced

智能审批逻辑：

# Claude Code 内部的审批决策逻辑（简化版）
def should_ask_approval(action):
    if action.type == "file_write":
        # 修改 .env、.ssh 等敏感文件需要审批
        if any(sensitive in action.path for sensitive in [".env", ".ssh", ".gitconfig"]):
            return True
        # 删除文件需要审批
        if action.type == "file_delete":
            return True
        # 创建新文件自动批准
        return False
    
    if action.type == "command":
        # 危险命令需要审批
        dangerous_commands = ["sudo", "rm -rf", "chmod 777", "curl | bash"]
        if any(cmd in action.command for cmd in dangerous_commands):
            return True
        # 常见开发命令自动批准
        return False
    
    return True  # 默认需要审批

3. off 模式（无审批）

off 模式允许 AI 完全自主执行操作，适合信任 AI 的场景：

claude --approval-mode off

使用场景：

个人实验项目
自动化批量重构
CI/CD 管道中的自动化任务

风险提示：在 off 模式下，一次 prompt injection 攻击可能导致 AI 执行 rm -rf / 或泄露敏感数据。

动态切换审批模式

你可以在 Claude Code 会话中动态切换模式，无需重启：

/approval-mode strict

模式切换命令：

命令	效果
`/approval-mode strict`	切换到严格模式
`/approval-mode balanced`	切换到平衡模式
`/approval-mode off`	切换到无审批模式
`/approval-mode status`	显示当前模式

🚀 实战：完成第一个任务

让我们通过一个实际任务来体验 Claude Code 的完整工作流。

任务：创建一个简单的 REST API

步骤 1：初始化项目

mkdir my-first-claude-api
cd my-first-claude-api
claude --approval-mode balanced

步骤 2：向 Claude 描述需求

Create a simple Express.js REST API with the following endpoints:
- GET /health - returns { status: "ok" }
- GET /users - returns a list of users
- POST /users - creates a new user
- GET /users/:id - returns a specific user

Use an in-memory array for data storage. Include proper error handling.

步骤 3：观察 AI 的操作

Claude Code 会逐步执行以下操作：

初始化 package.json
安装 express 依赖
创建 index.js 文件
运行代码进行测试

每次操作都会根据审批模式进行确认（在 balanced 模式下，大部分操作会自动批准）。

步骤 4：验证结果

AI 完成后，你可以直接测试 API：

# 启动服务器
node index.js &

# 测试端点
curl http://localhost:3000/health
# 输出: {"status":"ok"}

curl http://localhost:3000/users
# 输出: []

curl -X POST http://localhost:3000/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "[email protected]"}'
# 输出: {"id":1,"name":"Alice","email":"[email protected]"}

⚠️ 常见陷阱与故障排除

陷阱 1：API 密钥未设置

症状：

Error: ANTHROPIC_API_KEY environment variable is not set

解决方案：

# 检查是否已设置
echo $ANTHROPIC_API_KEY

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

陷阱 2：沙箱阻止了必要操作

症状：AI 反复提示 “Permission denied” 或操作被拦截

解决方案：

检查 .claude/settings.json 中的 allowPaths 配置
确保项目路径在允许列表中
临时切换到 off 模式测试（不推荐生产环境使用）

陷阱 3：Node.js 版本不兼容

症状：

Error: The engine "node" is incompatible with this module

解决方案：

# 检查当前版本
node --version

# 切换到兼容版本
nvm install 20
nvm use 20

陷阱 4：网络连接问题

症状：AI 响应缓慢或超时

解决方案：

# 测试 API 连接
curl -I https://api.anthropic.com

# 检查代理设置
echo $HTTP_PROXY
echo $HTTPS_PROXY

# 如果使用代理，确保配置正确
export HTTPS_PROXY="http://your-proxy:port"

📋 关键要点

安装配置：Claude Code 通过 npm 安装，需要 Node.js 18+ 和有效的 Anthropic API 密钥
安全沙箱：默认限制 AI 只能访问当前项目目录，通过 .claude/settings.json 精细控制
审批模式：提供 strict、balanced、off 三种模式，balanced 是推荐的生产环境选择
配置优先级：项目级配置覆盖用户级配置，deny 规则进行交集合并
动态切换：可在会话中使用 /approval-mode 命令随时切换模式

❓ 常见问题

Q1: Claude Code 和 GitHub Copilot 有什么区别？

Claude Code 是一个终端原生编码代理，能够自主执行多步骤操作（创建文件、安装依赖、运行测试），而不仅仅是代码补全。它更像一个 AI 开发伙伴，而不是智能输入法。

Q2: 如何撤销 AI 的误操作？

Claude Code 会记录所有操作到 .claude/audit.log。你可以使用 git diff 查看变更，或者直接告诉 AI “撤销刚才的修改”。

Q3: 可以在 CI/CD 中使用 Claude Code 吗？

可以。在 CI 环境中使用 --approval-mode off 和 --non-interactive 标志。但强烈建议先在沙箱中测试，并确保 API 密钥通过环境变量安全传递。

Q4: 如何查看 AI 消耗的 token 数量？

在会话中输入 /stats 命令，会显示当前会话的 token 使用统计，包括输入和输出 token 数量。

Q5: 如果 AI 陷入无限循环怎么办？

按 Ctrl+C 终止当前操作，然后输入 /reset 重置会话状态。如果问题持续，检查你的提示词是否过于模糊。

🔮 下期预告

在 Part 2 中，我们将深入探讨 Claude Code 的高级功能：

多文件编辑和项目级重构
自定义工具（Custom Tools）开发
与 Git 工作流集成
性能优化和缓存策略

敬请期待！

本文是 Claude Code 入门教程系列的第 1 部分。如果你有任何问题或建议，欢迎在评论区留言。

Have questions? Join our Discord community or follow us on X.

Claude Code Deep Dive — Complete Developer Guide

Claude Code 入门：Anthropic 终端编码代理快速上手

🎯 学习目标

🔧 安装与配置：从零到运行

系统要求

步骤 1：安装 Node.js 和 npm

步骤 2：安装 Claude Code

步骤 3：获取 API 密钥

步骤 4：首次运行

🛡️ 安全沙箱：保护你的文件系统

沙箱的工作原理

沙箱配置

实际沙箱行为演示

进阶沙箱配置：项目级 vs 全局

🔐 审批模式：控制 AI 的操作权限

模式对比

模式详解

1. strict 模式（严格模式）

2. balanced 模式（平衡模式）

3. off 模式（无审批）

动态切换审批模式

🚀 实战：完成第一个任务

任务：创建一个简单的 REST API

⚠️ 常见陷阱与故障排除

陷阱 1：API 密钥未设置

陷阱 2：沙箱阻止了必要操作

陷阱 3：Node.js 版本不兼容

陷阱 4：网络连接问题

📋 关键要点

❓ 常见问题

🔮 下期预告