🤖
Claude Code
本地安装与运行 · 完整教程（新手友好版）
0 前置准备 — 打开终端（小白必看！）
这是整个教程的第一步！ 请先看完这一步再往下走 。
什么是"终端"？ 黑底白字的窗口 （也可以改成其他颜色），你可以在里面输入命令 ，电脑就会执行。就像你跟电脑"发短信"，电脑收到后立刻帮你做事。键盘输入文字命令 来操作电脑的方式。Claude Code 就是一个需要在终端里输入命令来使用的工具。PowerShell — 微软推荐的现代终端，功能最强（我们主要用这个）CMD（命令提示符） — 旧版终端，蓝底白字，功能较少Windows Terminal — 最新版终端，可以同时开多个标签页（推荐安装）
终端 = 你跟电脑的"聊天窗口"
🅰️ 方法一：最快捷 — 按快捷键
Windows 10/11： Win 键和 X 键（Win键就是键盘左下角有Windows图标那个键）"Windows Terminal" 或 "PowerShell"
🅱️ 方法二：开始菜单搜索
1. 点击屏幕左下角的开始按钮 （Windows图标），或者按键盘上的 Win 键powershell 点击它
🅲️ 方法三：运行窗口
1. 同时按 Win + R powershell 回车 或点"确定"
推荐使用 PowerShell ，因为它功能更全，后面的教程大部分也是用 PowerShell 语法。如果你不确定自己用的是 PowerShell 还是 CMD，看一眼窗口标题：
💡 怎么在终端里粘贴代码？
后面教程有很多代码要你复制粘贴到终端里。粘贴方法：在 PowerShell / Windows Terminal 中： Ctrl + V （最常用，跟普通粘贴一样）右键点击 （也能粘贴）在旧版 CMD 中： Ctrl + V 可能不生效 → 用右键点击 来粘贴推荐做法： 先复制教程里的代码（点"复制"按钮），然后到终端窗口里直接 Ctrl + V 或右键粘贴就行。
终端打开后，你会看到一个黑底（或蓝底）的窗口，上面有一行提示文字，结尾是 > 符号，后面有个光标在闪。光标闪的地方就是你输入命令的位置。
1 什么是 Claude CodeClaude Code 是 Anthropic 官方推出的命令行工具（CLI） ，它将 Claude AI 直接带到你的终端里，让你可以在本地项目中与 AI 协作编程。
🎨 Claude Code 能做什么
阅读和理解你的整个代码库
编写、修改、重构代码
运行测试、调试问题
搜索文件和代码内容
Git 操作（提交、PR等）
解释代码逻辑
多文件协同编辑
⚡ 与网页版 Claude 的区别
直接访问本地文件系统
理解项目上下文和结构
可以执行 shell 命令
与 Git 工作流深度集成
持久的项目记忆
更快的迭代速度
支持 IDE 集成
2 环境准备 — 安装 Node.js
什么是 Node.js？为什么需要它？ "运行引擎" ，就像汽车需要发动机才能跑一样，Claude Code 需要 Node.js 才能运行。你不需要懂 Node.js，只需要把它装上就行。npm 又是什么？ 下载和安装工具 的。后面我们会用 npm 来安装 Claude Code，就像用"应用商店"来下载APP一样。
方法一：官网下载（推荐新手）
访问 Node.js 官网：https://nodejs.org
下载 LTS（长期支持）版本 ，建议 v18 或更高
运行安装程序，按默认选项安装 （⚠️ 确保"Add to PATH" 选项是勾选的！这个很重要，不勾选的话后面命令会报错）
安装完成后，关闭终端再重新打开 （这样 Node.js 才会被系统识别）
在新终端里输入以下命令验证：
终端
复制
node --version
npm --version
如果看到版本号输出（如 v20.x.x 和 10.x.x ），说明安装成功。
如果报错 "node 不是内部或外部命令"：
方法二：使用包管理器安装
macOS / Linux (Homebrew)
复制
brew install node
Windows (winget)
复制
winget install OpenJS.NodeJS.LTS
Ubuntu / Debian
复制
sudo apt update && sudo apt install nodejs npm
Node.js 版本要求 ≥ 18。如果你的版本较低，请先升级。
3 安装 Claude Code使用 npm 全局安装 Claude Code CLI 工具：
终端
复制
npm install -g @anthropic-ai/claude-code
安装完成后，验证安装是否成功：
终端
复制
claude --version
如果输出了版本号，说明安装成功！
-g 表示全局安装，这样你可以在任何目录下使用 claude 命令。
如果安装遇到权限问题
macOS / Linux
复制
sudo npm install -g @anthropic-ai/claude-code
Windows 用户一般不会遇到权限问题。如果遇到，请以管理员身份运行终端。
4 首次启动与认证（必须做！否则无法使用）
重要：没有认证 = 无法使用！ 这一步是必须做的 ，不做的话后面全部白搭。
认证是什么？通俗理解： 三种认证方式，选一种就行：
进入你的项目目录，然后启动 Claude Code：
没有项目目录？没关系！ mkdir my-test → 创建一个叫 my-test 的文件夹cd my-test → 进入这个文件夹claude → 启动claude 启动，不需要先进入某个目录。
终端
复制
# 进入你的项目目录（Windows用户，路径格式像这样：）
cd C:\Users\你的用户名\my-project
# 或者如果你没有项目，创建一个测试文件夹：
mkdir my-test
cd my-test
# 启动 Claude Code
claude
首次启动时，Claude Code 会自动弹出认证引导 ，让你选择认证方式：
认证方式
通俗理解
适合谁
是否需要 API Key
Anthropic Console 浏览器登录你的 Anthropic 账号，就像登录微信一样
有 Anthropic 账号的人
不需要（浏览器自动认证）
Max / Pro 订阅 用你的 Claude 付费订阅账号登录，就像会员卡刷卡
已有 Claude 付费订阅的人
不需要（订阅账号自动认证）
API Key 手动输入一串密钥，就像用钥匙开门
买了 API Key 的开发者
需要！ 你得自己准备 Key
三种认证方式就像三种开门方式：Anthropic Console = 指纹锁 → 浏览器登录就行，不用带钥匙Max 订阅 = 会员卡 → 你已经是会员了，刷卡直接进API Key = 钥匙 → 你得有一把钥匙，手动插进去开门
🅰️ 如果选择"Anthropic Console"或"Max 订阅"（最省事）
操作步骤： claude ，选择对应选项
这两种方式不需要你手动处理任何 Key ，浏览器登录搞定一切，最省心。
🅱️ 如果选择"API Key"（需要你自己准备 Key）
什么是 API Key？ sk-ant- 开头的长字符串，像这样：sk-ant-api03-xxxxxx... （当然这个是假的）。它是你购买/申请的"访问凭证"。怎么获取 API Key？ 然后有两种方式把 Key 告诉 Claude Code：
方式A：首次启动时粘贴（最简单） claude ~/.claude/ 目录里
方式B：通过环境变量传入（更安全，详见第8章） $env:ANTHROPIC_API_KEY="你的密钥" （Windows）claude
如果你已经用方式A（首次启动粘贴）完成了认证，不用再重复做方式B 。两种方式选一种就行。
❌ 如果不做认证会怎样？
没认证时启动 Claude Code 的结果
╭──────────────────────────────────────────╮
│ 错误：未认证 │
│ │
│ 请先完成认证： │
│ 1. 登录 Anthropic Console │
│ 2. 使用 Claude Max 订阅 │
│ 3. 输入 API Key │
│ │
│ 无法继续，请选择认证方式后重试 │
╰──────────────────────────────────────────╯
简单说：不认证 = 白装了 。Claude Code 会直接报错，提示你必须先认证才能使用。就像买了手机不插卡，开机了但什么功能都用不了。Step 4（认证）是必须紧接着做的 ，不能跳过。
登录成功的界面
认证完成后，你会看到 Claude Code 的交互界面：
Claude Code 正常界面
╭──────────────────────────────────────╮
│ Claude Code │
│ 项目: my-project │
│ │
│ > 输入你的问题或指令... │
╰──────────────────────────────────────╯
看到这个界面就说明认证成功，Claude Code 可以正常使用了！现在你可以开始跟 Claude 对话了。
5 基本使用方法Claude Code 是一个交互式对话工具 ，你只需要用自然语言描述你想做什么，它就会帮你完成。
典型使用场景
示例：让 Claude 读取文件
请帮我读取 src/index.ts 的内容并解释这段代码的作用
示例：让 Claude 修复 bug
运行测试时出现了错误，请帮我看看 test/login.test.ts 中的测试为什么失败了
示例：让 Claude 写新功能
在 components 目录下新建一个 UserCard 组件，显示用户头像、姓名和简介
示例：让 Claude 重构代码
请把 utils/helpers.js 中的重复代码提取成公共函数，减少代码冗余
直接用中文或英文描述你的需求即可，Claude Code 会自动理解你的项目上下文，读取相关文件，然后给出解决方案或直接修改代码。
交互流程
你输入问题/指令
Claude 读取项目文件，分析上下文
Claude 给出方案并请求你的确认
你确认后，Claude 执行修改
你可以继续追问或提出新需求
Claude Code 不会未经确认就修改你的代码。所有文件编辑、命令执行都需要你批准才会生效。
6 常用命令速查表启动与基础命令
命令
说明
claude 在当前目录启动交互模式
claude "你的问题" 直接提问，一次性模式
claude -p "你的问题" 管道模式，适合脚本调用
claude -c 继续上一次对话
claude -r 恢复最近的对话
claude --version 查看版本
claude config 查看/修改配置
交互模式中的斜杠命令
斜杠命令
说明
/help 查看帮助信息
/clear 清空当前对话历史
/compact 压缩对话历史，释放上下文空间
/cost 查看当前会话的 Token 使用量
/permissions 管理工具权限设置
/review 代码审查模式
/vim 切换 Vim 编辑模式
/model 切换使用的模型
/fast 切换快速输出模式
项目配置文件
你可以在项目根目录创建 CLAUDE.md 文件，写入项目约定：
CLAUDE.md 示例
# 项目说明
这是一个 React + TypeScript 项目。
## 规则
- 使用中文注释
- 优先使用函数式组件
- 测试使用 Jest
- 不要使用 var，请使用 const/let
## 目录结构
- src/components/ — UI组件
- src/utils/ — 工具函数
- src/api/ — API调用
CLAUDE.md 文件会在每次对话开始时自动加载，让 Claude 了解你的项目规范和偏好。
7 进阶技巧1. IDE 集成
Claude Code 可以集成到 VS Code 和 JetBrains IDE 中：
VS Code ：安装 Claude Code 扩展（在扩展商店搜索 "Claude Code"）JetBrains ：安装 Claude Code 插件
安装后，你可以在 IDE 内直接使用 Claude Code，无需切换到终端。
2. 与 Git 深度集成
Claude Code 可以帮你完成各种 Git 操作：
Git 操作示例
请帮我提交当前的修改，写一个合适的 commit message
帮我创建一个 PR，标题和描述要根据代码变更来写
查看最近的 git log，分析一下这个项目的提交历史
3. MCP 服务器扩展
通过 MCP（Model Context Protocol）服务器，你可以给 Claude Code 添加外部能力：
配置 MCP 服务器 (settings.json)
复制
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"]
}
}
}
4. 权限管理
你可以精确控制 Claude Code 能做什么：
设置权限
# 允许读取特定文件
/permissions allow Read src/**
# 允许执行特定命令
/permissions allow Bash npm test
# 查看当前权限
/permissions list
5. 管道模式（脚本集成）
你可以将 Claude Code 的输出集成到自动化脚本中：
管道模式用法
# 分析代码并输出结果
claude -p "分析 src/app.ts 的代码质量" > analysis.txt
# 与其他命令配合
echo "修复所有 lint 错误" | claude -p
8 API Key 导入与配置
什么是 API Key？ "家门钥匙" 。你拿着这把钥匙，Claude Code 才能"开门"连接到 Anthropic 的服务器为你工作。没有钥匙，门打不开，Claude Code 就用不了。为什么要导入/配置 Key？ 这个教程讲什么？ 注意：每个人的配置方式可能不同，下面提供的是最常见的几种方法。如果你目前用的方式跟这里不一样，没关系，只要能正常使用就行——本教程不会暴露你现有的任何 Key 或配置。
🔑 先搞清楚：Key 存在哪里？
Claude Code 的配置信息存放在你电脑上的几个特定位置，了解这些位置很重要：
你可以把这些位置想象成"不同大小的钥匙盒" ：~/.claude/ = 家里的大保险箱（放所有钥匙）.claude/ = 办公桌上的小钥匙盒（只放当前项目用的）
位置名称
路径
通俗理解
全局配置目录 ~/.claude/ Claude Code 的"大本营"，所有配置都在这里
全局设置文件 ~/.claude/settings.json 所有项目共用的配置（权限、MCP等）
全局本地设置 ~/.claude/settings.local.json 你个人专用的配置，不会分享给别人
项目设置 项目/.claude/settings.json 这个项目专用的配置，可以分享给团队
项目本地设置 项目/.claude/settings.local.json 你在这个项目里的私人配置，不提交到 git
Windows 上 ~/.claude/ 的真实路径是 C:\Users\你的用户名\.claude\ 。在终端输入 echo %USERPROFILE% 就能看到你的路径。
🅰️ 方法一：环境变量（最安全，最推荐）
什么是"环境变量"？ "嘴上说的密码" ，不是写在纸上的，而是你说一遍、系统记住一会儿。你关掉终端（就像离开房间），这个"嘴上说的密码"就消失了，不会留任何痕迹。为什么最安全？
Windows PowerShell 临时设置（用完就消失）： $env:ANTHROPIC_API_KEY="你的密钥" claude 启动
Windows PowerShell — 临时设置
复制
# 第1步：设置Key（只在这次会话有效）
$env:ANTHROPIC_API_KEY="你的密钥"
# 第2步：启动Claude Code
claude
# 第3步：用完后关闭终端，Key自动清除
上面的 $env: 是 PowerShell 设置临时环境变量的方式。"临时"意味着：你关掉这个终端窗口，Key 就没了，非常安全。
Windows CMD — 临时设置
复制
# 第1步：设置Key
set ANTHROPIC_API_KEY=你的密钥
# 第2步：启动Claude Code
claude
macOS / Linux — 临时设置
复制
# 第1步：设置Key
export ANTHROPIC_API_KEY="你的密钥"
# 第2步：启动Claude Code
claude
如果你不想每次都输入 Key，可以设置永久环境变量 （一劳永逸）：
Windows 永久设置（推荐新手用图形界面）： Win+R ，输入 sysdm.cpl ，回车ANTHROPIC_API_KEY
Windows PowerShell — 永久设置（命令方式）
复制
# 一行命令设置永久环境变量
[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "你的密钥", "User")
# 设置后需要重启终端才能生效
"User" 表示这个 Key 只在你的用户账号下生效，其他用户看不到。这比"Machine"级别更安全。
macOS / Linux — 永久设置
复制
# 打开你的 shell 配置文件
nano ~/.bashrc # 如果用 bash
# 或
nano ~/.zshrc # 如果用 zsh
# 在文件末尾添加这一行：
export ANTHROPIC_API_KEY="你的密钥"
# 保存退出后，重新加载配置：
source ~/.bashrc # 或 source ~/.zshrc
环境变量方式的优点总结：Key 不写入项目文件 → 不会被 git 提交 → 不会被分享 → 最不容易泄露。临时方式更安全（关掉就消失），永久方式更方便（不用每次输入）。
🅱️ 方法二：claude config 命令（简单快捷）
这是什么？ ~/.claude/ ）。和环境变量有什么区别？
操作步骤： claude config set apiKey "你的密钥"
终端
复制
# 设置 API Key
claude config set apiKey "你的密钥"
# 查看是否设置成功
claude config list
# 查看当前 Key（会显示部分内容）
claude config get apiKey
🅲️ 方法三：首次启动时交互式输入（最省事）
这是什么？ claude 时，它会像"门卫"一样问你："你是谁？拿什么钥匙？"。你直接粘贴 Key 就行了，不需要记任何命令。适合谁？
操作步骤： claude
🅳️ 关于"不同人的配置方式可能不同"
你可能发现你的配置方式跟上面写的不完全一样——这完全没关系！ 不需要改成这里写的 。这里只是告诉你"还有这些选项"，方便你以后想换的时候知道怎么做。无论你用哪种方式，最重要的一点都是：保护好你的 Key，不要让别人看到。
🔄 如何切换到新的 Key（不影响旧的）
什么时候需要切换？ 临时切换 vs 永久替换？
临时切换（推荐！不会影响你现有的 Key）： 新的 终端窗口$env:ANTHROPIC_API_KEY="新密钥" （Windows）claude 完全不受影响
临时切换 — Windows PowerShell
复制
# 在新终端窗口中设置新Key（只在这个窗口有效）
$env:ANTHROPIC_API_KEY="新密钥"
# 启动Claude Code（使用新Key）
claude
# 用完后关闭这个终端窗口，新Key就消失了
# 你原来的配置完全不受影响！
临时切换 — macOS / Linux
复制
# 在新终端窗口中设置新Key
export ANTHROPIC_API_KEY="新密钥"
# 启动Claude Code
claude
# 用完后关闭窗口即可
永久替换 — 把旧Key换成新Key
复制
# 方法A：用配置命令替换
claude config set apiKey "新密钥"
# 方法B：修改Windows环境变量（图形界面）
# Win+R → sysdm.cpl → 高级 → 环境变量 → 编辑 ANTHROPIC_API_KEY 的值
# 方法C：修改macOS/Linux配置文件
# 编辑 ~/.bashrc 或 ~/.zshrc 中的 export 行，改成新Key
🛡️ 如何保护你的 Key 不被泄露
API Key 就像你的银行卡密码 ！别人拿到你的 Key 就能用你的额度，产生费用。以下是必须做 的保护措施。
🔒 必须做的 6 件事
用环境变量存 Key ，不要写在代码文件里把 .env 和 .claude/ 加入 gitignore ，防止提交到 git不要在 CLAUDE.md 里写 Key 不要把 Key 硬编码到代码里 （如 const key = "sk-ant-..." ）不要截图含 Key 的终端内容 并分享定期更换 Key （在 Anthropic Console 可以重新生成）
📁 gitignore 配置
在你的项目 .gitignore 中加上这几行：
.claude/settings.local.json
这是什么意思？ 不要提交 到远程仓库。加了这几行后，即使你的 Key 写在这些文件里，也不会被上传到 GitHub 等平台。
🌐 使用第三方代理 / 自定义 API 地址（同事分享的方法详解）⭐
什么时候需要这个？ 如果你用的是官方 Anthropic API，不需要 设置这个，跳过即可。
🅰️ 同事分享的 settings.json 一键写入法（Windows）
这段代码是做什么的？通俗解释： 删除旧的 settings.json → 创建新目录（如果不存在）→ 写入新的 settings.json 配置文件 。C:\Users\你的用户名\.claude\settings.json ，也就是 Claude Code 的全局配置文件 （影响所有项目）。
⚠️ 重要提醒： 删除并覆盖 你现有的 settings.json ！如果你之前已经在里面写了权限配置或其他设置，会被全部替换掉。C:\Users\你的用户名\.claude\ ，把 settings.json 复制一份改名 settings.json.bak ，万一要恢复就改回来。
操作步骤： PowerShell 终端把 在这里替换成你的API Key 替换成你自己的真实 Key （这一步很重要！不换就连不上）把 在这里替换成你的代理地址 替换成你自己的代理地址 把 3个模型名称替换成你的代理支持的模型名
PowerShell — 一键写入 settings.json（同事分享的配置）
复制
$path="$env:USERPROFILE\.claude\settings.json";
Remove-Item $path -Force -ErrorAction SilentlyContinue;
New-Item -ItemType Directory -Force -Path (Split-Path $path)|Out-Null;
@"
{
"env": {
"OS": "Windows_NT",
"ANTHROPIC_AUTH_TOKEN": "在这里替换成你的API Key",
"ANTHROPIC_API_KEY": "",
"ANTHROPIC_BASE_URL": "在这里替换成你的代理地址",
"API_TIMEOUT_MS": "3000000",
"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
"CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "在这里替换成你想用的Opus模型名",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "在这里替换成你想用的Sonnet模型名",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "在这里替换成你想用的Haiku模型名",
"CLAUDE_CODE_NEW_INIT": "1"
}
}
"@|Set-Content $path
配置内容逐项解释：
配置项 通俗解释 你需要改吗？
ANTHROPIC_AUTH_TOKEN 你的认证密钥 ——就是你的 API Key。为什么叫 AUTH_TOKEN 而不是 API_KEY？因为用第三方代理时，认证方式可能跟官方不同，所以用的是 AUTH_TOKEN（认证令牌）而不是 API_KEY（接口密钥）。简单理解：这两个都是放 Key 的 ，只是名字不同。用代理时填 AUTH_TOKEN，用官方 API 时填 API_KEY 就行。你必须替换成你自己的真实 Key 必须替换！
ANTHROPIC_API_KEY 另一个 Key 的位置，这里留空表示用上面的 AUTH_TOKEN 就够了。如果你有两种 Key，可以在这里填另一个
一般留空即可
ANTHROPIC_BASE_URL API 的地址 ——告诉 Claude Code 去哪个服务器连接。原来的地址是同事用的代理。你必须替换成你自己的代理地址 ，如果你用官方 API 就不需要这项必须替换！ （用代理的话）
API_TIMEOUT_MS 超时时间，3000000 = 50分钟。意思是：如果 Claude 50分钟还没回复，就自动断开。一般不用改
不用改
DISABLE_NONESSENTIAL_TRAFFIC 设为 1 = 关闭非必要的网络请求（更新检查、统计等），只保留核心功能。节省流量，适合代理场景
不用改
DISABLE_EXPERIMENTAL_BETAS 设为 1 = 关闭实验性功能，只用稳定版，避免意外
不用改
DEFAULT_OPUS_MODEL 指定"最强"级别的模型名 。原来填的是同事用的模型名，你需要改成你自己的代理支持的模型名 必须替换！
DEFAULT_SONNET_MODEL 指定"日常"级别的模型名 。同样改成你代理支持的模型必须替换！
DEFAULT_HAIKU_MODEL 指定"快速/便宜"级别的模型名 。同样改成你代理支持的模型必须替换！
CLAUDE_CODE_NEW_INIT 设为 1 = 使用新版初始化流程，界面更友好
不用改
OS 标记你是 Windows 系统
不用改
总结：你需要替换的 3 类东西（非常重要！） API Key （ANTHROPIC_AUTH_TOKEN ）：把 sk-xxx 改成你自己的密钥——这是最重要的，不换就连不上代理地址 （ANTHROPIC_BASE_URL ）：改成你自己的代理地址——不换就走错门了模型名称 （3个 MODEL 项）：改成你的代理支持的模型名——不换就用不了对应的模型其余项不用改，保持原样就行。
不知道你的代理地址和模型名？ 一定要问清楚再替换 ，不能直接抄同事的。
替换完成后，这段配置的作用就是：
🅱️ 其他方法：环境变量（临时设置）
如果你不想覆盖 settings.json 文件，也可以用环境变量 的方式临时设置代理地址和 Key。这种方式关掉终端就消失，不会修改任何文件。
设置自定义 API 地址 — 环境变量方式
复制
# Windows PowerShell（临时，关掉终端就消失）:
$env:ANTHROPIC_BASE_URL="你的代理地址"
$env:ANTHROPIC_API_KEY="你的密钥"
# macOS/Linux（临时）:
export ANTHROPIC_BASE_URL="你的代理地址"
export ANTHROPIC_API_KEY="你的密钥"
# 或永久配置：
claude config set apiBaseUrl "你的代理地址"
如果你用同事的 settings.json 方法，不需要 再用环境变量方法了。两种方式选一种就行。settings.json 方式是永久的，环境变量方式是临时的。
9 Bypass Permissions 模式
先搞懂"权限系统"是什么？ "新来的助手" 。默认情况下，这个助手每做一件事都要问你：默认的权限模式 ——很安全，但很烦，一个任务可能要你点 20-30 次确认。什么是 Bypass Permissions？ 直接干活 。就像你跟助手说："以后这些事你自己决定，不用问我了。"效率大增，但风险也增加了——助手可能做了你不希望的事。什么时候该开 Bypass？ "精细 Bypass" （只允许它做安全的事，危险的事还是要问你）
📂 配置文件的层级（通俗版）
想象你有4个不同大小的"规则手册" ：全局设置 （~/.claude/settings.json ）= 国家法律 → 所有项目都得遵守全局本地设置 （~/.claude/settings.local.json ）= 你的私人规矩 → 只有你遵守，不给别人看项目设置 （项目/.claude/settings.json ）= 公司规章 → 这个项目的团队都遵守，可以分享项目本地设置 （项目/.claude/settings.local.json ）= 你的个人工作习惯 → 只在你电脑上，不提交到 git
建议：权限规则 写在项目设置里（方便团队共享），Key 和私人偏好 写在 local 文件里（不会被分享）。
🤔 默认模式是什么样的？
默认模式 — Claude 每做一步都要问你
╭─────────────────────────────────────────╮
│ Claude 想要编辑文件: │
│ src/index.ts │
│ │
│ 允许吗？ [y=允许 / n=拒绝] │
╰─────────────────────────────────────────╯
╭─────────────────────────────────────────╮
│ Claude 想要运行命令: │
│ npm test │
│ │
│ 允许吗？ [y=允许 / n=拒绝] │
╰─────────────────────────────────────────╯
# 一个大任务可能弹出 20-30 次这样的确认...
🚀 开启 Bypass 的四种方法
方法零：设置快捷命令 cc（最省事，同事推荐！）⭐
这是什么？ claude --dangerously-skip-permissions 太长了，容易打错。所以你同事创建了一个"快捷命令" ：cc 。cc ，就等于输入了 claude --dangerously-skip-permissions 。就像你把"开门解锁进入房间坐下开始工作"这一长串动作，简化成了"啪"一下按遥控器。为什么要写到 PowerShell Profile 里？ "开机自启文件" ——每次打开 PowerShell，它都会自动加载这个文件里的内容。所以你只要往里面写一次，以后每次打开终端，cc 命令就已经准备好了，不用再设置。
打个比方：claude --dangerously-skip-permissions = 每次出门都要念一长串咒语才能开门cc 快捷命令 = 把咒语刻在门卡上，以后刷卡就行，只要刷一下 "cc"
操作步骤（只需做一次！）： PowerShell 终端（注意：必须是 PowerShell，不是 CMD）先设置 PowerShell 执行策略 （让系统允许加载 Profile 文件）。在终端输入：Set-ExecutionPolicy RemoteSigned -Scope CurrentUser ，按回车，如果弹出确认提示，输入 Y 再回车完整复制 ，粘贴到终端里回车 重启 PowerShell （关闭终端再重新打开）验证是否生效 ：在新终端里输入 cc ，如果 Claude Code 启动界面出现，说明成功！
PowerShell — 一键设置 cc 快捷命令（同事分享的方法）
复制
$profilePath = "$env:USERPROFILE\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1"
$content = @'
# Import the Chocolatey Profile that contains the necessary code to enable
# tab-completions to function for `choco`.
# Be aware that if you are missing these lines from your profile, tab completion
# for `choco` will not function.
# See https://ch0.co/tab-completion for details.
function cc {
claude --dangerously-skip-permissions @Args
}
'@
# 确保目录存在
$directory = Split-Path $profilePath -Parent
if (-not (Test-Path $directory)) {
New-Item -ItemType Directory -Path $directory -Force
}
# 写入文件（如果文件已存在会覆盖）
$content | Out-File -FilePath $profilePath -Encoding UTF8
这段代码逐行解释： $profilePath = ... → 找到你的 PowerShell 配置文件路径（就像找到你家的门锁位置）$content = @' ... '@ → 定义要写入的内容。里面有两部分：function cc { claude --dangerously-skip-permissions @Args } → 这是核心！ 创建了一个叫 cc 的函数，当你输入 cc 时，它自动帮你执行 claude --dangerously-skip-permissions 。@Args 的意思是"把你输入的其他参数也一起传过去"，比如 cc -c 就等于 claude --dangerously-skip-permissions -c # 确保目录存在... → 如果配置文件的目录不存在，就自动创建（就像如果门锁位置还没装锁，就先帮你装好）$content | Out-File ... → 把内容写入配置文件（把咒语刻到门卡上）
如果你已经有 PowerShell Profile 文件了： 覆盖 你现有的 Profile。如果你之前在 Profile 里写了自己的内容，建议先备份旧文件，然后把 function cc { ... } 这一行追加 到旧文件末尾，而不是整体覆盖。cat $PROFILE 看看现有内容，记下来，然后手动编辑。
设置完成后，你以后只需要输入 cc 就能启动 Bypass 模式的 Claude Code！cc -c （继续上次对话）、cc "你的问题" （直接提问）等。
方法一：启动参数（每次手动输入）
如果你不想设置快捷命令，也可以每次启动时手动输入完整参数。就是每次都念一长串咒语。
终端 — 启动时加参数即可
复制
claude --dangerously-skip-permissions
为什么叫 "dangerously"？ 实际用起来危险吗？ 不危险 。Claude 不会故意做坏事。不要开全 Bypass ，用下面的"精细 Bypass"更稳妥。
方法二：对话中动态切换
你已经在跟 Claude 聊天了，突然觉得"确认太烦了"，想改成自动模式。不用退出，直接在对话里输入命令就行。
在 Claude Code 对话中输入
复制
# 开放所有权限（全 Bypass）
/permissions allow All
# 或者只开放某几类（精细 Bypass，更安全）
/permissions allow Read # 只允许读取文件（不能改、不能删）
/permissions allow Edit # 只允许编辑文件
/permissions allow Bash # 只允许执行命令
/permissions allow Read 的意思是：告诉 Claude "读取文件不需要问我了，你自己看吧"。但改文件、执行命令还是需要确认。只放开安全的操作 ，保留危险操作的确认机制。
方法三：写入配置文件（永久生效）
前两种方法都是"临时"的（关闭 Claude Code 就恢复了）。如果你想每次启动都自动 Bypass ，就要把规则写进配置文件。
操作步骤： ~/.claude/settings.json （全局）或 项目/.claude/settings.json （项目级）"permissions" 部分（见下方示例）
📝 配置文件示例（从简单到精细）
下面从最简单 到最精细 ，给你3个层次的示例，选一个适合你的：
层次1：全开 Bypass（最简单，效率最高）
复制
{
"permissions": {
"allow": [
"Read", // 读文件 → 不用问
"Edit", // 改文件 → 不用问
"Write", // 新建文件 → 不用问
"Bash", // 执行命令 → 不用问
"Glob", // 搜索文件名 → 不用问
"Grep", // 搜索文件内容 → 不用问
"WebFetch" // 网页请求 → 不用问
],
"deny": [] // 没有禁止的操作
}
}
这段配置是什么意思？ "allow" 列表里写了 Claude 可以自动执行 的所有操作类型。"deny" 列表是禁止 的操作（这里是空的，表示什么都不禁止）。效果： Claude 做任何事都不用问你，全自动。效率最高，但风险也最大 。
层次2：新手推荐（安全又高效）⭐
复制
{
"permissions": {
"allow": [
"Read", // 读文件 → 不用问（看文件不会有危险）
"Edit", // 改文件 → 不用问（写代码是主要需求）
"Glob", // 搜索文件 → 不用问
"Grep", // 搜索内容 → 不用问
"Bash(npm test)", // 运行测试 → 不用问（只允许 npm test）
"Bash(npm run *)", // 运行项目命令 → 不用问（只允许 npm run 开头的）
"Bash(git status)", // 查看 git 状态 → 不用问
"Bash(git diff*)", // 查看 git 差异 → 不用问
"Bash(git log*)", // 查看 git 日志 → 不用问
"Bash(ls *)", // 列出文件 → 不用问
"Bash(cat *)" // 看文件内容 → 不用问
],
"deny": [
"Write(.env*)", // ❌ 禁止写入 .env 文件（保护密钥！）
"Bash(rm *)", // ❌ 禁止删除文件
"Bash(rm -rf *)", // ❌ 禁止强制删除
"Bash(curl *)", // ❌ 禁止外部网络请求
"Bash(sudo *)" // ❌ 禁止管理员权限命令
]
}
}
为什么推荐这个？ allow 里开放了日常开发最需要的操作（读、写、搜索、git查看、npm命令）deny 里禁止了危险操作 ：删除文件、写 .env（密钥文件）、管理员命令不会碰你的密钥文件，也不会删你的东西 Bash(npm test) 是什么意思？ npm test 这一条命令，其他命令还是需要确认"。Bash(git *) 则是"所有以 git 开头的命令都可以自动执行"。括号里是命令匹配规则 ，星号 * 表示"任意内容"。
层次3：最严格（只开放最安全的操作）
复制
{
"permissions": {
"allow": [
"Read", // 只允许读文件
"Glob", // 只允许搜索文件名
"Grep" // 只允许搜索内容
],
"deny": [
"Write(.env*)", // 禁止写密钥文件
"Bash(rm *)" // 禁止删除
]
}
}
这个配置的效果： 看 你的文件和搜索内容，但改文件、执行命令 还是要每次问你确认。适合你刚开始用、还不太放心的时候。
🛡️ Bypass 模式下如何保护你的 Key
为什么 Bypass 模式下保护 Key 更重要？ 自动操作任何没有被 deny 的文件 。明确禁止 Claude 碰你的密钥文件。就像你跟助手说"什么事你自己做，但千万别碰保险柜 "。
🛡️ Key 保护要点
环境变量传 Key （不留文件痕迹）deny 中禁止写 .env ："Write(.env*)" deny 中禁止读密钥文件 ："Read(.env*)" 把 local 文件加入 gitignore 不要在项目代码中存 Key
🎯 一句话理解
开 Bypass = 给助手自由自由 + 红线 = 效率高 + 安全
📋 完整配置文件参考
下面是一个 settings.json 的完整示例，包含权限 + MCP + 环境变量 。你可以按需取用，不需要的部分删掉就行。
settings.json 完整示例
复制
{
// ============ 权限设置 ============
// allow: Claude可以自动做的事（不用问你）
// deny: Claude绝对不能做的事（即使开了Bypass）
"permissions": {
"allow": [
"Read",
"Edit",
"Glob",
"Grep",
"Bash(npm test)",
"Bash(npm run *)",
"Bash(git status)",
"Bash(git diff*)",
"Bash(git log*)"
],
"deny": [
"Write(.env*)",
"Read(.env*)",
"Write(.claude/settings.local.json)",
"Bash(rm -rf *)",
"Bash(curl *)",
"Bash(sudo *)"
]
},
// ============ MCP服务器（可选）============
// 给Claude添加外部能力，比如文件系统访问、GitHub操作等
// 不需要的话可以删掉这个部分
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
}
},
// ============ 环境变量（可选）============
// 可以在这里设置一些环境变量
"env": {
"CLAUDE_CODE_USE_BEDROCK": "0"
}
}
⚡ 权限操作速查表
你想做什么
命令 / 方法
通俗解释
一次性全开 Bypass
claude --dangerously-skip-permissions "今天助手全权处理，不用问我"
快捷命令 Bypass（设置cc后）
cc "刷卡开门，一键搞定"
对话中开放所有权限
/permissions allow All "从现在开始，什么事都自己做"
只允许读文件
/permissions allow Read "文件可以自己看，但别的要问我"
只允许改文件
/permissions allow Edit "可以改代码，但执行命令要问我"
只允许运行测试
/permissions allow Bash(npm test) "可以自己跑测试，别的命令要问我"
禁止碰 .env 文件
/permissions deny Write(.env*) "绝对不能碰密钥文件"
查看当前权限
/permissions list "看看助手现在有哪些自由"
重置所有权限
/permissions reset "回到默认模式，所有事都要问我"
重要提醒： 开了 Bypass 后，Claude 可以自动做任何没被 deny 禁止 的操作。所以一定要在 deny 列表里写上你想保护的东西（密钥文件、删除操作等），相当于给助手画红线："这些事绝对不能碰"。
🎯 新手推荐路线
如果你不知道从哪里开始，按这个顺序走：第1周： 不开 Bypass，每次都确认 → 熟悉 Claude 会做什么第2周： 用"层次3"（最严格）配置 → 只放开读取，改文件还是要确认第3周： 用"层次2"（新手推荐）配置 → 日常操作自动，危险操作禁止以后： 觉得效率不够再用"层次1"（全开）→ 但一定要配好 deny 列表保护密钥无论哪个阶段，Key 都用环境变量方式设置，永远不要写进代码文件。
10 常见问题 FAQ
❓ Claude Code 是免费的吗？
Claude Code 需要 Anthropic 账号。使用方式包括：Claude Max/Pro 订阅（每月有使用额度）、Anthropic Console（按 API 使用量计费）。安装工具本身是免费的，使用时产生的费用取决于你的认证方式和用量。
❓ Windows 上能用吗？
可以！Claude Code 支持 Windows、macOS 和 Linux。Windows 用户建议使用 Windows Terminal 或 Git Bash 作为终端。WSL（Windows Subsystem for Linux）环境也完全支持。
❓ 安装时报错 "npm ERR!" 怎么办？
常见原因和解决方法：npm config set registry https://registry.npmmirror.com
❓ Claude Code 会自动修改我的代码吗？
不会。Claude Code 在修改文件或执行命令前都需要你的确认。你可以逐个批准或拒绝它的操作建议。只有在获得明确授权后，它才会执行修改。
❓ 如何更新 Claude Code？
运行以下命令即可更新到最新版本：npm update -g @anthropic-ai/claude-codeclaude --version 查看当前版本。
❓ 如何卸载 Claude Code？
npm uninstall -g @anthropic-ai/claude-code~/.claude/ 目录即可。
❓ 可以在多个项目之间切换使用吗？
当然可以！Claude Code 的上下文是基于你当前所在的项目目录的。只需要 cd 到另一个项目目录，然后运行 claude 即可。每个项目可以有独立的 CLAUDE.md 配置。
❓ 对话历史会保存吗？
会。Claude Code 会保存你的对话历史，你可以用 claude -c 继续上一次对话，或用 claude -r 恢复最近的对话。项目级别的记忆（CLAUDE.md）会永久保留。
❓ 我的配置方式跟教程不一样，怎么办？
完全没关系！ 每个人都有自己的配置习惯，只要 Claude Code 能正常工作就行。本教程提供的只是最常见的几种方法，你不需要改成这里写的。无论你用什么方式，保护好你的 Key 不被泄露就行。
❓ API Key 存在哪里？会泄露吗？
取决于你使用的配置方式：环境变量方式： Key 存在终端环境中，不会写入任何文件。关闭终端后消失（临时方式），或只在你的系统环境变量中存在（永久方式）。最不容易泄露。交互式登录方式： Key 会保存在 ~/.claude/ 目录下。这个目录不会被 git 自动提交，但仍需注意不要手动分享此目录的内容。claude config 命令方式： 同样保存在 ~/.claude/ 目录下。
❓ 开了 Bypass 模式，Claude 会删除我的 .env 或密钥文件吗？
如果你在 deny 规则中禁止了这些操作，就不会："deny": ["Write(.env*)", "Read(.env*)", "Write(.claude/settings.local.json)"]没有设置 deny 规则 且开了全 Bypass，理论上 Claude 可以操作任何文件——所以一定要配 deny 列表！
❓ 如何在不影响旧 Key 的前提下测试新 Key？
最简单的方法：打开一个新的终端窗口 ，在里面临时设置新 Key。$env:ANTHROPIC_API_KEY="新密钥"; claudeexport ANTHROPIC_API_KEY="新密钥" && claude完全不受影响 。测试完关闭新窗口即可。
❓ Bypass 模式和普通模式的效率差别有多大？
差别很大！打个比方：普通模式 = 每走一步都要向领导汇报 → 安全但慢全 Bypass = 领导说"你自己做决定" → 快但可能有意外精细 Bypass = 领导说"日常小事自己做，大事要汇报" → 又快又安全
❓ 我的 API Key 过期了/额度用完了怎么办？
需要更换新的 Key：$env:ANTHROPIC_API_KEY="新密钥"（Windows）claude config set apiKey "新密钥"
❓ 可以同时用两个不同的 Key 吗？
不能同时用一个，但可以在不同终端窗口里用不同的 Key ：$env:ANTHROPIC_API_KEY="密钥A"; claude$env:ANTHROPIC_API_KEY="密钥B"; claude
❓ settings.json 和 settings.local.json 有什么区别？
settings.json = 可以分享的配置（权限规则、MCP服务器等），会被提交到 git，团队共享。settings.local.json = 你私人的配置（Key、个人偏好等），不会被提交到 git，只有你自己能看到。Key 应该放在 settings.local.json 或环境变量里，千万不要放在 settings.json 里。
❓ 终端里输入 node 或 claude 报错"不是内部或外部命令"？
这个问题很常见，原因通常是：没勾选 "Add to PATH" → 安装 Node.js 时默认会勾选这个选项，如果你取消了，系统就找不到 node 命令。解决：重新安装 Node.js，确保勾选 "Add to PATH"安装后没重启终端 → 安装完 Node.js 或 Claude Code 后，必须关闭终端再重新打开 ，系统才能识别新安装的程序安装路径不对 → 用默认安装路径，不要改路径新的 终端窗口，输入 node --version，如果还是报错，就重新安装 Node.js。
❓ 设置了 cc 快捷命令但输入 cc 没反应？
最常见的原因：PowerShell 执行策略限制了 Profile 文件的加载 。Set-ExecutionPolicy RemoteSigned -Scope CurrentUserY 再回车。cc。$PROFILE，看看输出的路径是否跟你写入 Profile 的路径一致。如果不一致，说明你用了不同版本的 PowerShell（比如 PowerShell 7 和 Windows PowerShell 5 的 Profile 路径不同）。
❓ 怎么确认 Bypass 模式是否已经开启？
开启 Bypass 模式后，Claude Code 界面上会有明显提示：claude --dangerously-skip-permissions 或 cc 启动时，界面会显示一条警告文字 ，类似："Bypassing permissions: all operations will be auto-approved"不再弹出确认提示 ，直接执行了，说明 Bypass 在生效。
❓ ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN 有什么区别？
简单理解：这两个都是放 API Key 的，只是名字不同，适用场景不同。 ANTHROPIC_API_KEY = 官方 API 的密钥名字。如果你直接用 Anthropic 官方的服务，Key 就放在这个字段里ANTHROPIC_AUTH_TOKEN = 第三方代理服务的密钥名字。如果你通过代理/转发服务来用，Key 放在这个字段里走代理用 AUTH_TOKEN，走官方用 API_KEY 。
❓ npm install 安装 Claude Code 时很慢或卡住怎么办？
这通常是网络问题 （npm 默认从国外服务器下载，国内可能很慢）。npm config set registry https://registry.npmmirror.comnpm install -g @anthropic-ai/claude-codenpm config set registry https://registry.npmjs.org
❓ 认证时终端里显示的链接点击不了怎么办？
有些终端不支持直接点击链接。解决方法：选中链接文字 ，然后右键复制Windows Terminal （最新版终端），链接通常可以直接点击。建议安装 Windows Terminal 来获得更好的体验。
🚀 快速上手流程
① 安装 Node.js
→
② npm 安装 Claude Code
→
③ 导入 API Key
→
④ 选择权限模式
→
⑤ 开始使用！