Claude Code基础概念及使用手册

cuixiaogang
  2026-03-10 2026-03-10 Created      3.2k Words  12 Mins  

Claude Code 是 Anthropic 推出的面向开发者的 AI 编程协作工具，与在聊天窗口里写几段代码不同，Claude Code 的核心目标是理解你的整个项目，并参与到真实的编码、修改和重构过程中。

Claude Code不是一个代码生成器，而是一个能读项目、懂上下文、遵守约束的 AI 编程搭档。

简单说：Claude Code 是 Claude 的命令行版本,专门为编程场景设计。

部署及安装

Claude Code有三种使用方式：

方式 适合人群 优点 缺点
Web端 完全新手 无需安装 功能受限
编辑器集成（VSCode/Cursor/Jetbrains） 日常开发 无缝融入开发工作 依赖环境、插件
CLI 有一定基础 功能完整,集成度高 熟悉命令行

WEB端使用

功能受限，不推荐。基本使用类似于ChatGPT，只是能力强弱有区别

编辑器集成

  • VSCode插件：请认准作者

VSCode插件
VSCode插件

  • Jetbrains插件：推荐两个，一个是Claude Code GUI，一个是官方提供的插件（请认准作者）

Jetbrains插件
Jetbrains插件

CLI

因为Claude Code在开发过程中，经常需要测试验证功能，所以需要提前配置好代码运行的环境。

另外，根据官方文档，Claude Code CLI 从 1.0 版本开始就不再支持通过 npm 安装，而是统一采用脚本安装的方式，所以也无需准备 npm 环境了。

  • npm 废弃的原因
    • npm 无法处理二进制依赖
    • 难以跨平台管理
    • 无法自动更新
    • 无法集成系统级功能（如 git hook、MCP）

安装

macOS、Linux、WSL:

1
curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell:

1
irm https://claude.ai/install.ps1 | iex

Windows CMD:

1
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

CLI模式的Claude
CLI模式的Claude

登录账号（土豪用户）

如果购买了官方的Token或订阅了官方的服务，可直接在项目目录下执行claude就进入了命令启动交互式会话，然后执行/login按提示登录账号既可

Coding Plan（普通用户）

使用官方的Claude Code API不仅Token昂贵，而且国内还需要梯子，很不方便。Claude Code可以接入其他厂商的Coding Plan，我们可以使用其他的模型来帮助我们开发，这里推荐两个国产模型。

方舟Coding-Plan
方舟Coding-Plan

百炼Coding-Plan
百炼Coding-Plan

购买后，按文档配置环境变量，然后在项目目录下执行claude既可使用，一般需要配置三个环境变量

1
2
3
4
# macOS、Linux、WSL
export ANTHROPIC_AUTH_TOKEN=
export ANTHROPIC_BASE_URL=
export ANTHROPIC_API_KEY=

Claude Code的工作原理

当用户给 Claude 发布一个任务时，它会经历三个阶段：

  • 收集上下文（查看代码、文件、错误信息）
  • 采取行动（编辑文件、运行命令、搜索等）
  • 验证结果（执行测试、检查）

Claude Code的工作流程
Claude Code的工作流程

这三个步骤会不断循环，直到任务完成。同时，用户也是这个循环的一部分：用户可以推送同Claude对话，用来改变需求、调整策略等操作。这个循环由两个组件来驱动：负责推理的模型和负责行动的工具。Claude Code通过这两个组件，将语言模型转为能进行编程的工具。

模型

用于理解代码并推理任务。具体模型相关内容，可参考后续文档

工具

工具是将语言模型转为能进行编程的工具，它能读取代码、编辑文件、运行命令、搜索网络并与外部服务器交互等。每个工具使用都会返回信息并反馈到循环中，帮助Claude决定如何执行、执行什么。

类别 执行内容
文件操作 读取文件、编辑代码、创建新文件、重命名和重新组织
搜索 按模式查找文件、使用正则表达式搜索内容、探索代码库
执行 运行shell命令、启动服务器、运行测试、使用git
网络 搜索网络、获取文档、查找错误消息
代码智能 编辑后查看类型错误和警告、跳转到定义、查找引用（需要代码智能插件）

交互模式

权限模式

因为Claude Code存在多种交互模式，这些交互模式的区别主要集中在权限控制上，具体的权限模式如下：

模式名 是否允许文件修改 是否执行bash 是否允许Git修改 是否需要确认 安全等级
default（默认模式） ✅ 部分（需确认） ❌ 需确认 ❌ 需确认 ✅ 是 ⭐⭐⭐⭐⭐
acceptEdits（接收编辑） ✅ 是 ❌ 需确认 ❌ 需确认 ✅ 是（Bash/Git） ⭐⭐⭐⭐
bypassPermissions（绕过权限） ✅ 是 ✅ 是 ✅ 是 ❌ 否 ⭐
dontAsk（不询问） ✅ 是 ❌ 禁止 ❌ 禁止 ✅ 是（危险操作） ⭐⭐⭐⭐
plan（计划模式） ❌ 禁止 ❌ 禁止 ❌ 禁止 ✅ 是（所有） ⭐⭐⭐⭐⭐
auto（自动模式） ✅ 是 ✅ 是（高危才确认） ✅ 是（高危才确认） ✅ 少数 ⭐⭐⭐

交互模式

在Claude Code终端交互界面中，我们可以使用shift+tab来控制权限批准的开关

  • default：对应的就是default（默认模式）。交互界面中没有任何提示信息

默认模式
默认模式

  • accept edits on：对应的就是acceptEdits（接收编辑），交互界面中的提示信息为⏵⏵ accept edits on

接收编辑
接收编辑

  • plan mode on：对应的就是plan（计划模式），交互界面中的提示信息为⏸ plan mode on

计划模式
计划模式

plan（计划模式）

在该模式下，Claude根据当前代码库，使用只读操作来创建一个完成用户需求的计划，同时它也会分析需求，帮助用户补充需求说明。用户可以跟Claude讨论该方案的问题，确认后，Claude将切换为“默认模式”，执行该计划。

  • 下面是一个2048小游戏的HTML需求，它会补充需求的内容：

计划模式示例
计划模式示例

  • 确认后将切换为“默认模式”，询问是否创建并写入文件：

image.png
image.png

配置

生效范围

Claude Code通常会分为三层，且由低到高覆盖

全局配置（用户级）

针对账号/机器上的所有项目均生效。一般由于统一设置默认模型、默认输出风格、API Key、代理等，配置位置如下：

  • macOS/Linux：~/.config/claude/
  • Windows：%USERPROFILE%\.claude\

项目配置（仓库级）

只对当前项目生效，适合团队协作。一般用于团队约定模型、工具权限、代码风格、忽略路径、Prompt规范等。配置位置一般是项目根目录下的.claude/目录

环境变量（会话级/CI 级）

优先级最高，适合临时覆盖或在CI/CD注入。一般用于流水线里注入Key、切换模型、指定代理、开启/关闭某些能力。

配置项说明

提供一份完整的配置说明，当前设置值均为默认值

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
{
  // 【认证】Claude API Key。安全起见建议留空，改用环境变量（如 ANTHROPIC_API_KEY / 公司统一网关注入）
  "apiKey": "",

  // 【API 网关】默认是官方地址；若你公司有自建网关/审计出口，在这里改
  "apiBaseUrl": "https://api.anthropic.com",

  // 【默认模型】你日常使用的默认模型
  "defaultModel": "claude-3-5-sonnet-latest",

  // 【输出长度】限制单次回复最多输出多少 token（越大越贵/越慢，但可能更完整）
  "maxOutputTokens": 2048,

  // 【稳定性/发散度】越低越稳（适合代码/规范），越高越发散（适合创意文案）
  "temperature": 0.2,

  // 【采样参数】通常保持 1；配合 temperature 调整生成多样性（如果版本支持）
  "topP": 1,

  // 【流式输出】true：边生成边显示；false：生成完一次性输出
  "stream": true,

  "proxy": {
    // 【代理总开关】公司网络/特殊网络环境需要
    "enabled": false,

    // 【HTTP 代理】示例："http://127.0.0.1:7890"
    "http": "",

    // 【HTTPS 代理】示例："http://127.0.0.1:7890"
    "https": "",

    // 【不走代理】逗号分隔
    "noProxy": "localhost,127.0.0.1"
  },

  "network": {
    // 【请求超时】毫秒；弱网可调大
    "timeoutMs": 60000,

    // 【重试次数】偶发网络抖动时提升稳定性
    "retries": 2,

    // 【重试退避】毫秒；避免快速重试触发限流
    "retryBackoffMs": 500
  },

  "workspace": {
    // 【项目根目录】留空一般表示“当前工作目录”；也可写死一个路径
    "root": "",

    // 【是否跟随软链接】安全考虑通常建议 false，避免越权读到仓库外
    "followSymlinks": false,

    // 【只读模式】true 时即使允许写文件也不落盘（适合演示/审阅）
    "readOnly": false,

    // 【允许访问的路径白名单】留空表示不启用白名单；启用后只能访问这些目录/文件
    "allowedPaths": [],

    // 【禁止访问的路径黑名单】强烈建议加入敏感目录（如 ~/.ssh、含密钥的目录）
    "blockedPaths": [],

    // 【忽略规则】类似 .gitignore；减少无关上下文、避免误读敏感信息、降低成本
    "ignore": [
      "**/.git/**",
      "**/node_modules/**",
      "**/dist/**",
      "**/build/**",
      "**/.next/**",
      "**/coverage/**",

      // 常见敏感文件
      "**/.env",
      "**/*.pem",
      "**/*secret*",
      "**/*token*"
    ],

    // 【单文件读取上限】字节；过大文件会浪费上下文/增加成本
    "maxFileBytes": 1048576,

    // 【总读取上限】字节；控制一次会话读取的总量，避免上下文膨胀
    "maxTotalReadBytes": 10485760
  },

  "permissions": {
    // 【读文件】Claude Code 要做代码理解通常需要开启
    "allowReadFiles": true,

    // 【写文件】开启后允许直接修改项目文件；建议配合二次确认
    "allowWriteFiles": false,

    // 【执行命令】如运行测试、格式化、grep；高风险能力，建议默认关闭
    "allowShell": false,

    // 【联网】允许访问外网资源；企业内一般要关或走网关
    "allowNetwork": false,

    // 【执行命令前确认】避免误执行破坏性命令
    "requireConfirmationForShell": true,

    // 【写文件前确认】避免批量改坏代码
    "requireConfirmationForWrite": true
  },

  "git": {
    // 【Git 集成】允许读 git 状态、diff 等（不同版本能力不同）
    "enabled": true,

    // 【自动暂存】是否自动 git add（谨慎开启）
    "autoStage": false,

    // 【自动提交】是否自动 git commit（一般不建议）
    "autoCommit": false
  },

  "ui": {
    // 【主题】auto / light / dark（如果版本支持）
    "theme": "auto",

    // 【Markdown 渲染】提升可读性
    "markdown": true,

    // 【彩色输出】终端显示更友好
    "color": true,

    // 【显示 token/费用信息】用于成本观察（若版本支持）
    "showTokenUsage": false
  },

  "logging": {
    // 【日志级别】error / warn / info / debug
    "level": "info",

    // 【日志路径】留空表示默认；写死路径便于审计与排错
    "path": "",

    // 【脱敏】避免把 key/token 写进日志
    "redactSecrets": true
  }
}

会话

Claude Code在工作时，会将对话内容保存在本地，帮助用户回退、恢复和创建分支会话。在更新代码文件之前，还会对受影响的文件进行快照操作，便于回退版本。

主要功能

  • 保持上下文连续性：在多次对话间保留项目状态、历史记录和配置。
  • 持久化记忆：通过 memory/ 目录存储项目级别的关键信息（如架构决策、代码模式、用户偏好）。
  • 状态恢复：重新进入项目时自动加载上下文，无需重新解释项目背景

相关命令

命令 作用 备注
claude 启动交互式会话 默认启动，自动加载项目上下文
claude -c/--continue 继续当前目录中最新的会话 等价于 --continue
claude -r "<session>" 按名称恢复会话 claude -r "auth-refactor"
claude --resume [session] 恢复特定会话或打开选择器 恢复已保存的会话历史

模型

Claude Code提供了多种模型来负责推理任务，使用/model或/fast来切换模型。

Claude切换模型
Claude切换模型

简单总结官方推荐的几种模型：

模型名称 行为
default 推荐的模型设置，取决于账户类型
sonnet 使用最新的 Sonnet 模型（当前为 Sonnet 4.6）用于日常编码任务
opus 使用最新的 Opus 模型（当前为 Opus 4.6）用于复杂推理任务
haiku 使用快速高效的 Haiku 模型用于简单任务
sonnet[1m] 使用Sonnet和100万token上下文窗口用于长会话
opusplan 特殊模式，在计划模式中使用opus，然后在执行时切换到sonnet

当然，我们也可以使用自定义模型，可关注后面的配置栏。

On this page
Claude Code基础概念及使用手册
  1. 部署及安装
    1. WEB端使用
    2. 编辑器集成
    3. CLI
      1. 安装
      2. 登录账号（土豪用户）
      3. Coding Plan（普通用户）
  2. Claude Code的工作原理
    1. 模型
    2. 工具
  3. 交互模式
    1. 权限模式
    2. 交互模式
    3. plan（计划模式）
  4. 配置
    1. 生效范围
      1. 全局配置（用户级）
      2. 项目配置（仓库级）
      3. 环境变量（会话级/CI 级）
    2. 配置项说明
  5. 会话
    1. 主要功能
    2. 相关命令
  6. 模型