文章目录

• • @[toc]
  • 0\. 【Claude基础】全部目录
  • 1\. 安装方式
  • • npm 全局安装
    • 系统要求
    • 网络代理配置
    • IDE 集成安装
  • 2\. 首次认证
  • • API Key 获取
    • 环境变量配置
    • 多 API Key 管理与工作区隔离
  • 3\. 第一次对话
  • • 启动 Claude Code
    • 基本交互模式
    • 理解工作目录感知能力
    • 第一个实用任务
  • 4\. 权限模式详解
  • • 五种权限模式
    • 启动时指定权限模式
    • 运行时切换
    • 权限模式与安全的平衡
  • 5\. 理解 Claude Code 的工作方式
  • • 它不是聊天窗口
    • Token 消耗与 /cost 命令
    • 会话的生命周期
    • 什么时候该开新会话
  • 6\. 常见问题排查
  • • 连接超时与代理配置
    • 权限被拒绝的处理
    • 模型不可用的切换策略

0. 【Claude基础】全部目录

• 【Claude基础】01.Claude全景图：模型、产品与生态
• 【Claude基础】02.安装与首次交互：5分钟上手Claude Code
• 【Claude基础】03.斜杠命令体系：掌握Claude Code的操作语言
• 【Claude基础】04.Memory与CLAUDE.md：打造你的专属AI助手
• 【Claude基础】05.Skills深度指南：让Claude学会你的工作流
• 【Claude基础】06.Hooks深度指南：事件驱动的自动化管道
• 【Claude基础】07.MCP Servers深度指南：连接万物的协议
• 【Claude基础】08.子代理系统：分身术与并行执行
• 【Claude基础】09.多代理协作：Agent Teams与编排模式
• 【Claude基础】10.插件开发与生产部署：构建可分发的能力包

---

Claude Code 是 Anthropic 官方出品的 CLI 工具，直接在终端里跟 Claude 交互，能读写文件、执行命令、分析代码。这篇文章把从安装到跑通第一个任务的全流程走一遍。

1. 安装方式

npm 全局安装

一行命令搞定：

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

装完之后终端里直接敲 claude 就能用。如果提示找不到命令，检查一下 npm 全局安装路径有没有加到 PATH 里。

如果你用 yarn 或 pnpm，也可以：

# yarn
yarn global add @anthropic-ai/claude-code

# pnpm
pnpm add -g @anthropic-ai/claude-code

更新到最新版本：

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

系统要求

• **Node.js 18+**：这是硬性要求。用 node -v 看一下版本，低于 18 的话先升级。推荐用 nvm 管理 Node 版本，切换起来方便。

• 操作系统：macOS、Linux 原生支持。Windows 上需要通过 WSL2（Windows Subsystem for Linux）来运行，原生 Windows 终端目前还不是官方推荐的方式，但实际使用中 Git Bash 和 PowerShell 也能跑起来。

• 磁盘空间：安装包本身不大，几十 MB 的事。

# 检查 Node 版本
node -v
# v20.11.0  ← OK

# 如果版本太低，用 nvm 切换
nvm install 20
nvm use 20

网络代理配置

国内用户大概率需要配代理，不然连不上 Anthropic 的 API。Claude Code 会读取标准的环境变量：

# mac/linux 在 .bashrc 或 .zshrc 里加上
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

# windows 在 .bat中增加下面命令（.ps1需要设置$env:HTTPS_PROXY="http://127.0.0.1:7890"）
SET HTTP_PROXY=http://127.0.0.1:7890
SET HTTPS_PROXY=http://127.0.0.1:7890

端口号换成你自己代理工具的实际端口。

如果用了自签名证书的企业代理，可能还需要：

export NODE_TLS_REJECT_UNAUTHORIZED=0

不过这个会跳过 TLS 验证，生产环境别这么干。

建议设置下面命令，防止mcp或者其它地方访问出错

set "NO_PROXY=127.0.0.1,localhost"

IDE 集成安装

Claude Code 有 VS Code 和 JetBrains 的官方扩展，装上之后可以直接在编辑器里唤起 Claude：

VS Code：

在扩展市场搜索 “Claude Code”，安装 Anthropic 官方发布的扩展。装完后侧边栏会多出一个 Claude 图标，点进去就是一个内嵌的终端面板，和直接在终端里用的体验一致。

也可以命令行装：

claude install-extension vscode

JetBrains（IntelliJ IDEA、PyCharm、WebStorm 等）：

Settings → Plugins → Marketplace，搜索 “Claude Code” 安装。或者用命令：

claude install-extension jetbrains

IDE 集成的好处是能直接跳转到 Claude 提到的文件和行号，改代码的时候 diff 预览也更直观。不过功能上和终端版没有区别，选你习惯的方式就行。

2. 首次认证

API Key 获取

Claude Code 需要一个 Anthropic API Key 才能工作。获取步骤：

1. 打开 Anthropic Console

2. 注册或登录账号

3. 进入 Settings → API Keys 页面（直达链接：https://console.anthropic.com/settings/keys）

4. 点击 “Create Key”，给 Key 起个名字，比如 “claude-code-dev”

5. 复制生成的 Key（以 sk-ant- 开头），只会显示一次，存好

API Key 是按 token 计费的，首次注册通常会有免费额度，够你体验一阵子。

环境变量配置

最简单的方式是设置环境变量：

# 临时设置（当前终端有效）
export ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxx

# 永久设置（加到 shell 配置文件）
echo 'export ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxx' >> ~/.bashrc
source ~/.bashrc

或者第一次运行 claude 时，它会交互式地引导你完成认证，按提示操作就行。Claude Code 还支持 OAuth 登录方式，如果你有 Claude Pro/Team/Enterprise 订阅，可以直接用账号登录，不需要单独的 API Key。

安全提醒：API Key 不要提交到 Git 仓库里。.env 文件记得加到 .gitignore。

多 API Key 管理与工作区隔离

如果你有多个项目，分别用不同的 API Key（比如个人项目用自己的 Key，公司项目用公司的），可以用几种方式隔离：

方式一：项目级 .env 文件

在项目根目录放一个 .env 文件：

ANTHROPIC_API_KEY=sk-ant-project-specific-key

Claude Code 启动时会自动读取当前目录的 .env。

方式二：direnv

用 direnv 自动按目录切换环境变量，进入不同项目目录时自动加载对应的 Key：

# 项目 A 的 .envrc
export ANTHROPIC_API_KEY=sk-ant-key-for-project-a

# 项目 B 的 .envrc
export ANTHROPIC_API_KEY=sk-ant-key-for-project-b

方式三：命令行直接指定

ANTHROPIC_API_KEY=sk-ant-another-key claude

适合偶尔切换的场景。

3. 第一次对话

启动 Claude Code

Claude Code 是工作目录感知的。它会把你当前所在的目录作为项目根目录，分析里面的文件。所以启动前先 cd 到你的项目目录：

cd /path/to/your/project
claude

启动后你会看到一个交互式的命令行界面，光标停在输入区域等你提问。

基本交互模式

直接用自然语言提问就行，不需要任何特殊语法：

> 这个项目是干什么的？

> src/main.ts 里的 handleRequest 函数逻辑是什么？

> 帮我找一下所有使用了 deprecated API 的地方

Claude 会根据你的问题，主动去读取项目里的文件，然后给出回答。你不需要手动告诉它"先读一下某个文件"——它会自己判断需要看哪些文件。

当然，你也可以明确指定：

> 读一下 package.json，告诉我项目的依赖有哪些

理解工作目录感知能力

Claude Code 启动后做的第一件事，就是扫描当前目录的结构。它能看到：

• 目录树结构

• 文件名和路径

• .gitignore 里排除的文件（这些不会被读取）

• CLAUDE.md 文件（如果有的话，这是给 Claude 的项目说明）

这意味着它对项目有一个整体的认知，不是盲人摸象。你问它"这个项目的架构是什么"，它能给出靠谱的回答，因为它真的看了代码。

但它不会一开始就把所有文件都读一遍——那太浪费 token 了。它是按需读取的：你问到哪个模块，它就去看哪个模块的代码。

第一个实用任务

试试让 Claude 分析你的项目结构，这是一个很好的起手任务：

> 分析一下当前项目的目录结构和技术栈，给我一个概览

Claude 会列出主要目录、用了什么框架、入口文件在哪、配置文件有哪些。这个过程中它会调用文件系统工具去读取关键文件，你能在终端里看到它的操作过程。

再进阶一点：

> 这个项目有哪些潜在的代码质量问题？

> 帮我给 src/utils/helper.ts 写单元测试

> 把 README 里过时的安装说明更新一下

这些都是 Claude Code 擅长的任务。

4. 权限模式详解

Claude Code 执行操作时会涉及文件读写和命令执行，不同的权限模式决定了它能自动做什么、做什么之前要问你。

五种权限模式

模式	行为	适用场景
default	读文件自动，写文件和执行命令前会询问	日常开发，推荐新手使用
plan	只分析和展示方案，不做任何修改	代码审查、方案评估
acceptEdits	允许编辑文件不再询问，但执行命令仍需确认	信任 Claude 的代码修改能力时
auto	所有操作自动执行，不询问	熟练用户、批量任务
bypassPermissions	跳过所有安全检查	仅限 CI/CD 流水线使用

default 模式是最安全的起点。Claude 每次要写文件或跑命令之前都会把内容展示给你，你确认后才会执行。虽然多了几次回车，但能防止意外操作。

plan 模式适合"我只想听听你的建议，别动我的代码"的场景。比如你想让 Claude 做一个重构方案的分析，但不希望它真的去改文件。

acceptEdits 模式是一个实用的中间地带。文件编辑通常是安全的（大不了 git checkout 撤销），但命令执行可能有副作用（比如 rm -rf 或者 npm publish），所以命令还是让你确认。

auto 模式适合你已经很了解 Claude Code 行为模式的时候。批量处理多个文件、跑一系列测试、执行重构，每次都确认太烦了，开 auto 省事。（目前官方写的是：Team 先用，Enterprise 和 API 正在陆续放开，需要 Claude Sonnet 4.6 或 Claude Opus 4.6，像 Claude 3、Haiku、Bedrock、Vertex、Foundry 这些暂时还不支持。）

bypassPermissions 只在 CI/CD 管道中有意义，人工交互场景下不要用。

启动时指定权限模式

# 以 plan 模式启动
claude --permission-mode plan

# 以 auto 模式启动
claude --permission-mode auto

运行时切换

在 Claude Code 的交互界面里，按 Shift+Tab 可以实时切换权限模式。不需要退出重启。

这个快捷键很实用——你可能一开始用 default 模式边看边确认，确认 Claude 理解了你的意图后，切到 acceptEdits 让它快速执行剩下的修改。

权限模式与安全的平衡

我的建议：

• 不熟悉的项目或者重要的生产代码：用 default 或 plan

• 有 git 保护的开发分支：acceptEdits 就够了

• 批量机械任务（格式化、重命名、加注释）：auto 省时间

• 永远不要在没有版本控制的目录里用 auto 模式

记住一点：Claude Code 的所有文件操作都可以通过 git 回滚，所以只要你在 git 管理的项目里工作，风险是可控的。

5. 理解 Claude Code 的工作方式

它不是聊天窗口

Claude Code 和网页版 Claude 的核心区别在于：它能操作你的开发环境，不只是聊天。

它手里有一套工具：

• 文件读取：读取项目中任意文件的内容

• 文件写入：创建新文件或修改已有文件

• 命令执行：在终端里运行 shell 命令（npm install、git、pytest 等等）

• 搜索：在项目中搜索代码、文件名、内容

• 网络请求：访问 URL 获取文档信息

所以你可以给它下达真正的开发任务：“帮我把这个函数重构成 async/await 写法并跑一遍测试”——它会改代码、跑测试、看结果、如果测试挂了还会尝试修复。

Token 消耗与 /cost 命令

Claude Code 按 token 计费，每次对话都在消耗额度。用 /cost 命令可以看到当前会话已经用了多少 token：

> /cost

输出会告诉你输入 token 数、输出 token 数、总费用。

几个省 token 的技巧：

• 问题描述尽量精确，减少来回试探

• 不需要的时候别让它读大文件

• 用完一个任务就结束会话，别在一个会话里堆太多不相关的任务

• 利用 CLAUDE.md 文件预置项目上下文，减少每次重复解释

会话的生命周期

一个 Claude Code 会话从你敲 claude 开始，到你输入 /exit 或者 Ctrl+C 退出结束。中间的流程大致是：

1. 启动：加载项目上下文，读取 CLAUDE.md（如果有）

2. 交互：你提问，Claude 操作，循环往复

3. 上下文压缩：当对话太长、token 接近上限时，Claude Code 会自动压缩早期的对话内容，保留关键信息，丢弃细节。你会看到一个压缩的提示

4. 结束：退出会话

压缩是自动发生的，你不需要手动操作。但压缩意味着丢失细节，所以如果你发现 Claude 开始"忘记"早期讨论的内容，那就是压缩生效了。

什么时候该开新会话

继续当前会话：

• 任务还没做完，需要继续

• 后续问题和前面的讨论有关联

• Claude 对当前代码的理解你很满意，不想让它重新了解

开新会话：

• 切换到完全不同的任务

• 当前会话已经很长，Claude 的回答开始跑偏

• 上下文压缩后丢失了重要信息

• 切换到不同的项目目录

一个经验法则：一个会话专注做一件事。"帮我重构用户模块"是一个会话，"帮我修复登录 bug"是另一个会话。别把不相关的任务塞进同一个会话里。

恢复上一次的会话也可以：

claude --continue        # 继续最近一次会话
claude --resume          # 选择一个历史会话继续

6. 常见问题排查

连接超时与代理配置

症状：卡在 “Connecting…” 或者报 ETIMEDOUT / ECONNREFUSED 错误。

排查步骤：

# 1. 确认代理是否工作
curl -x http://127.0.0.1:7890 https://api.anthropic.com

# 2. 确认环境变量是否设置
echo $HTTPS_PROXY

# 3. 如果用的是 socks5 代理
export HTTPS_PROXY=socks5://127.0.0.1:1080

如果代理没问题但还是连不上，可能是代理工具没有正确转发 WebSocket 连接。换一个代理协议试试，或者用 TUN 模式（全局代理）。

权限被拒绝的处理

症状：Claude 想执行操作但被拒绝了。

这通常是正常行为——在 default 模式下，写操作需要你确认。如果你觉得每次确认太麻烦：

# 切换到 acceptEdits 模式
# 在会话中按 Shift+Tab 切换

# 或者对特定命令添加白名单
# 在 .claude/settings.json 中配置 allowedTools

如果是文件系统权限问题（不是 Claude Code 的权限模式），检查文件的读写权限：

ls -la 目标文件
chmod u+w 目标文件

模型不可用的切换策略

症状：报错提示当前模型不可用或超出配额。

Claude Code 默认使用最新的 Claude Sonnet 模型。如果遇到可用性问题：

# 指定模型启动
claude --model claude-sonnet-4-20250514

# 查看可用模型
claude config list

如果是 API 配额用完了，去 Console 检查一下用量，可能需要充值或者等待配额重置。

还有一种情况是 Anthropic 的 API 在做维护或者某个区域有故障，这种等一会就好了。可以看看 Anthropic Status 页面确认一下。