<!-- title: 新手第一课：驯服Claude Code权限 -->

## 概述

本教程面向**第一次安装 Claude Code 的零基础学习者**。学习目标是：理解 AI 编程助手为什么会反复弹窗询问"我可以这样做吗"，掌握 Claude Code 的**权限系统**（六种模式 + allow/deny/ask 规则），并亲手造出一个可运行的**番茄钟命令行小工具**，在造工具的过程中把权限调到"既不烦人、又不危险"的舒适状态。完成本教程，你将不再被弹窗打断思路，也清楚什么时候**绝不**该点 Allow。

## 前置条件

- 一台 macOS、Linux 或 Windows（WSL）电脑，能联网
- 已安装 Node.js 18 及以上版本（`node -v` 能输出版本号即可）
- 一个 Anthropic 账号（或 Claude 订阅），首次运行会引导登录
- 终端基础操作：会 `cd` 切换目录、能看懂命令输出
- 不需要会写代码——脚本由 Claude Code 替你写，你负责**读懂权限弹窗并决策**

---

## 一、为什么权限系统是 Claude Code 的"第一道门槛"

很多新手第一次用 Claude Code 时都会被同一个问题困扰：**它为什么不停问我"我可以创建这个文件吗？""我可以运行这条命令吗？"**，弹窗多到把思路打断。要理解这件事，必须先搞懂 Claude Code 的核心运行机制——**回合制 Agent 循环（Agentic Loop）**。

Claude Code 不是聊天机器人，而是一个**会动手的智能体**。它的每一次"思考"之后，几乎都会调用一个**工具（Tool）**去真正改变你的电脑状态：读文件（Read）、写文件（Write）、改文件（Edit）、跑命令（Bash）、抓网页（WebFetch）等等。一个完整循环是：

1. **接收指令**：你输入需求（比如"造一个番茄钟"）。
2. **思考与规划**：模型决定下一步调用哪个工具。
3. **工具调用**：真正执行——这一步**会动你的文件系统和命令行**。
4. **读取结果**：把工具的输出喂回模型，进入下一轮思考。
5. **循环往复**，直到任务完成。

关键在第 3 步。因为工具调用会真实改变系统状态，**Claude Code 默认采用"人在回路（human-in-the-loop）"策略**：凡是可能造成副作用的高风险操作（写文件、删文件、跑命令、发网络请求），执行前都要先问人。

理解了这一点，你就明白了权限系统的本质——**它不是在给你添堵，而是在替你兜底**。一个能随意删文件、随意执行命令的 AI，没有这道闸门是极其危险的。权限系统就是你和这个强大智能体之间的**契约**：哪些事它可以直接做，哪些必须先请示，哪些永远不许做。

新手的第一课，不是学怎么让它干活，而是**学会和这道闸门相处**——把它调到你信任的程度。

---

## 二、安装与首次启动

打开终端，执行官方安装命令（以 npm 方式为例）：

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

安装完成后，验证版本：

```bash
claude --version
```

能看到版本号即安装成功。接着在任意目录启动：

```bash
mkdir ~/pomo && cd ~/pomo
claude
```

首次启动会引导你完成登录认证（浏览器跳转授权）。登录成功后，你会进入一个交互式界面，光标前通常是 `>` 提示符，下方有一行**模式提示**，类似：

```
> 
(default) cwd: ~/pomo
```

这里的 `(default)` 就是当前所处的**权限模式**。下面我们来逐一拆解它。

---

## 三、六种权限模式详解

权限模式（permission mode）决定了 Claude Code 在"没命中任何预定义规则"时，**默认该问还是该做**。截至 2026 年，Claude Code 提供 6 种模式，可在交互界面用 **Shift + Tab** 循环切换：

| 模式 | 中文名 | 行为 | 适用场景 |
|------|--------|------|----------|
| `default` | 默认模式 | 高风险操作逐个询问 | 新手、重要项目、首次操作 |
| `acceptEdits` | 自动接受编辑 | 文件编辑直接做，命令仍询问 | 重构、批量改代码 |
| `plan` | 计划模式 | 只读探索，只出方案不执行 | 复杂任务先调研、看大纲 |
| `auto` | 智能模式 | 安全操作自动放行，危险仍问 | 日常开发（新版本默认） |
| `dontAsk` | 不询问 | 几乎不问，但仍受 deny 约束 | 半信任的自动化任务 |
| `bypassPermissions` | 完全绕过 | 全部不问，YOLO 模式 | 一次性沙盒容器、CI 容器 |

**原理要点**：模式只控制"兜底行为"。如果你在 `settings.json` 里写了明确的 `allow`/`deny` 规则，**规则优先级永远高于模式**——被 `deny` 的操作在任何模式下（包括 `bypassPermissions`）都会被挡掉；被 `allow` 的操作在任何模式下都直接放行。模式只对"规则没覆盖到的灰色地带"生效。

**新手建议**：前两个项目只用 `default` 模式，认真看完每一次弹窗。等你熟悉了它"想做什么"，再升级到 `auto`。**`bypassPermissions` 在你自己的工作电脑上慎用**，最好只留给 Docker 等一次性容器。

---

## 四、用 settings.json 精准放行：allow / deny / ask

光靠模式切换，要么太严（一直问），要么太松（不安全）。真正强大的，是**细粒度规则**。Claude Code 把每个工具调用都表示成一条**规则串**，你预先写好放行（allow）、拒绝（deny）、询问（ask）三类清单，就能让安全命令静默、危险命令永远挡住。

### 规则串语法

| 规则串 | 含义 |
|--------|------|
| `Bash(git status:*)` | 允许所有 `git status ...` 命令 |
| `Bash(npm run test)` | 只允许恰好这条命令 |
| `Read(./src/**)` | 允许读取 src 目录下所有文件 |
| `Edit(./src/**)` | 允许编辑 src 目录下所有文件 |
| `Write(./pomo.log)` | 允许写入这个特定文件 |
| `WebFetch(docs.anthropic.com)` | 允许抓取该域名网页 |
| `mcp__github__*` | 允许某个 MCP 服务器的所有工具 |

其中 `*` 是通配符，`:**` 表示"任意参数"。**deny 的优先级高于 allow**——只要命中 deny，无论是否同时命中 allow，都会被拒绝。

### 三层配置文件（优先级从高到低）

1. **企业托管策略**：`/etc/claude-code/managed-settings.json`（Linux）或对应路径，由 IT 管理员锁定，个人改不了。
2. **用户级**：`~/.claude/settings.json`，对你所有项目生效。
3. **项目级**：项目根目录下 `.claude/settings.json`（可提交到 Git 团队共享）和 `.claude/settings.local.json`（个人本地，应加入 `.gitignore`）。

**新手只需关注用户级和项目级即可**。

### 一个安全的起手配置

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

```json
{
  "permissions": {
    "allow": [
      "Bash(python3:*)",
      "Bash(cat:*)",
      "Bash(ls:*)",
      "Read(./**)",
      "Edit(./**)",
      "Write(./pomo.log)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Bash(curl:*)",
      "Read(./.env)",
      "Read(./.env/**)",
      "Edit(./.env)"
    ],
    "ask": [
      "Bash(npm publish:*)",
      "Bash(git push:*)"
    ]
  },
  "defaultMode": "default"
}
```

这套配置的含义是：**读改项目文件、跑 Python 脚本、看日志都直接放行**；**删除、提权、外发网络、读写 `.env` 一律禁止**；**发布、推送这种对外操作必须问**。这正是"既不烦人、又不危险"的舒适区。

---

## 五、实战项目：在权限弹窗中造一个番茄钟 CLI

现在把理论用起来。我们让 Claude Code 替我们写一个 25 分钟工作 + 5 分钟休息的番茄钟，过程中你会真实经历"弹窗 → 决策 → 永久放行"的完整流程。

### 步骤 1：准备目录并启动

```bash
cd ~/pomo
claude
```

确认界面底部显示 `(default)` 模式。

### 步骤 2：下达需求，观察第一次弹窗

在提示符后输入：

```
帮我写一个 Python 番茄钟 pomo.py：工作 25 分钟、休息 5 分钟，倒计时显示在终端，
完成后把每条记录追加写入 pomo.log，格式为"时间 | 类型 | 时长 | 任务名"。
```

**预期结果**：Claude Code 思考后会调用 `Write` 工具创建 `pomo.py`。此时弹窗出现：

```
Claude wants to write to ./pomo.py
[1] Yes, and don't ask again for Write in this project
[2] Yes
[3] Yes, and allow all future write/edit operations
[4] No
```

**决策示范**：选 **1**——既允许这次，又把"本项目内写文件"永久放行。这正是规则写入的时刻。文件创建成功后，Claude Code 会显示写入路径与行数。

### 步骤 3：让它跑起来，再次观察弹窗

接着让它运行测试：

```
跑一下这个脚本，任务名设为"学权限"，确认能正常计时并把日志写进去。
```

**预期结果**：Claude Code 调用 `Bash` 工具，弹窗询问是否运行 `python3 pomo.py 学权限`。**注意**：为了演示，我们临时把脚本的工作时间改短（见步骤 4），否则要等 25 分钟。在弹窗里选"don't ask again for `Bash(python3:*)`"，把 Python 执行权永久放行。

### 步骤 4：精简版脚本（方便演示验证）

完整脚本由 Claude Code 生成，核心逻辑如下（你可以对照它写出的版本）：

```python
#!/usr/bin/env python3
import time, sys
from datetime import datetime

WORK, BREAK, LOG = 3, 1, "pomo.log"   # 演示用 3 秒/1 秒，正式用 1500/300

def countdown(seconds, label):
    while seconds:
        m, s = divmod(seconds, 60)
        print(f"\r{label}: {m:02d}:{s:02d}", end="", flush=True)
        time.sleep(1); seconds -= 1
    print()

def log(task, kind, minutes):
    with open(LOG, "a") as f:
        f.write(f"{datetime.now():%Y-%m-%d %H:%M} | {kind} | {minutes}min | {task}\n")

task = sys.argv[1] if len(sys.argv) > 1 else "专注"
countdown(WORK,  f"🍅 {task}")
log(task, "work", WORK // 60)
countdown(BREAK, "☕ 休息")
log(task, "break", BREAK // 60)
print(f"✅ 完成！记录已写入 {LOG}")
```

### 步骤 5：验证日志，体验"静默放行"

运行结束后，让它读取日志：

```
把 pomo.log 的内容显示出来。
```

**预期结果**：因为 `Read(./**)` 已在 allow 列表（或刚被你永久放行），这次**不再弹窗，直接输出**：

```
2026-07-09 14:30 | work  | 0min | 学权限
2026-07-09 14:30 | break | 0min | 学权限
```

这就是权限调好之后的畅快感——**安全操作静默通过，只在真正有风险时才打断你**。

### 步骤 6：用 /permissions 命令回看与微调

在交互界面输入：

```
/permissions
```

会打开一个交互式面板，列出当前所有 allow / deny / ask 规则、来源（用户级/项目级）、当前模式。你可以在这里**直接增删规则**，而不用手改 JSON。这个命令的别名是 `/allowed-tools`。

---

## 六、常见问题与解决方案

**Q1：弹窗太多，思路全被打断了。**
→ 在 `default` 模式下用 **Shift + Tab** 切到 `acceptEdits`（自动改文件）或 `auto`（智能放行安全操作）。再把高频安全命令（`git status`、`npm run test`、`ls`、`cat`）写进 `allow`。

**Q2：我点了"allow all"，现在它开始乱删文件，怎么办？**
→ 立即用 `/permissions` 打开面板，找到过宽的规则（如 `Bash(*)`）删除；或在 `deny` 里加 `Bash(rm:*)` 兜底。**deny 永远胜过 allow**。

**Q3：`.env` 里有密钥，怕它读出去。**
→ 把 `Read(./.env)`、`Read(./.env/**)`、`Edit(./.env)`、`Bash(cat:.env*)` 全写进 `deny`。这样即便误入 `bypassPermissions`，密钥也读不到。

**Q4：团队项目，规则要共享给同事。**
→ 写进 `.claude/settings.json` 并提交 Git；个人的临时规则写进 `.claude/settings.local.json` 并加入 `.gitignore`。

**Q5：脚本卡在 25 分钟倒计时，没法快速验证。**
→ 演示阶段把 `WORK`/`BREAK` 改成秒级（如 3 秒/1 秒），验证逻辑无误后再改回 1500/300。这也是调试倒计时类程序的标准技巧。

**Q6：`bypassPermissions` 到底能不能用？**
→ 只在**一次性、可丢弃的沙盒环境**里用（Docker 容器、CI 临时机器、虚拟机快照）。在装满个人数据的工作电脑上，永远别开——一旦它决定 `rm -rf`，没人拦得住。

---

## 七、安全红线：什么时候绝不点 Allow

权限系统再灵活，也挡不住人在弹窗前习惯性地点"Yes"。请牢记以下红线——**只要弹窗里的命令沾边，立刻选 No**：

1. **删除命令**：`rm -rf`、`rm -r`、`git clean -fd`、`drop table`、`truncate`。
2. **提权命令**：`sudo`、`chmod 777`、`chown`。
3. **外发与下载**：`curl`、`wget`、`scp`、`npm publish`、`pip upload`、`git push --force`。
4. **读写敏感文件**：`.env`、`id_rsa`、`credentials.json`、`~/.ssh/**`、浏览器 profile。
5. **访问本不该碰的目录**：弹窗里出现 `~/Documents`、`~/Desktop`、`/etc`、`/var` 而当前项目根本不在那里——说明它可能要越界操作。

遇到拿不准的命令，**先选 No，再让它解释这条命令会做什么**，听懂了再重新放行。记住：**Allow 是不可逆的授权习惯，谨慎永远不吃亏。**

---

## 八、权限决策流程图

下图展示一次工具调用从发起到执行/拒绝的完整判定路径。建议存下来，作为你每次面对弹窗时的决策参照：

```mermaid
flowchart TD
    A[Claude 发起一次工具调用] --> B{命中 deny 规则?}
    B -- 是 --> X[❌ 直接拒绝 不询问]
    B -- 否 --> C{命中 allow 规则?}
    C -- 是 --> D[✅ 自动放行 静默执行]
    C -- 否 --> E{命中 ask 规则?}
    E -- 是 --> F[🔔 弹窗询问用户]
    E -- 否 --> G{当前权限模式}
    G -- default --> F
    G -- acceptEdits --> H{是文件编辑类?}
    H -- 是 --> D
    H -- 否 --> F
    G -- plan --> I[🔒 只读 拒绝执行]
    G -- auto --> J{操作判定为安全?}
    J -- 安全 --> D
    J -- 危险 --> F
    G -- bypassPermissions --> D
    F --> K{用户选择}
    K -- Allow once --> D
    K -- Allow always --> L[📝 写入 allow 规则]
    K -- Deny --> X
    L --> D
```

---

## 延伸阅读

- **Anthropic 官方 Claude Code 文档**（中文）：权限、模式、规则语法的权威来源。
- **Claude Code settings.json 完全指南**：理解除 permissions 外的环境变量、模型选择、钩子（hooks）等配置项。
- **Agent SDK 权限文档**：当你开始用 SDK 写自动化脚本时，权限模型略有不同，值得提前了解。
- **CLAUDE.md 记忆机制**：本系列后续会讲——让 Claude Code"记住"你的项目约定，配合权限系统形成完整的"信任契约"。

---

## 训练营适用性评估

- **适合训练营类型**：**零基础 AI 编程入门营 / 企业 AI 安全合规培训营**。前者用于建立"安全地与 AI 协作"的第一直觉，后者用于向非技术管理者演示 AI 工具的"可控边界"。
- **预计教学时长**：**90 分钟**（含 20 分钟讲解原理 + 40 分钟动手造番茄钟 + 30 分钟调权限与答疑）。
- **学员产出**：一个可运行的番茄钟 CLI + 一份团队可复用的 `.claude/settings.json` 权限模板。
- **延伸作业**：让学员把番茄钟升级成"读取任务清单逐个完成"的多任务版，并在升级过程中独立设计自己的 allow/deny 规则，写出"为什么这样放行/拒绝"的说明。

## 参考来源

1. [配置权限 - Claude Code 官方文档（中文）](https://code.claude.com/docs/zh-CN/permissions) — 权限模式、allow/deny/ask 规则语法与托管策略的权威说明。
2. [Claude Code settings.json 详解：permissions 权限系统全解析](https://blog.vincentqiao.com/posts/claude-code-settings-permissions/) — 三类规则、通配符语法、defaultMode 各模式含义的深度技术博客。
3. [Claude Code Permission Modes Explained (2026)](https://www.explainx.ai/blog/claude-code-permission-modes-explained-2026) — 2026 年最新模式集合与切换方法的实战教程。
4. [Claude Code Permissions: A Practical settings.json Guide](https://www.developersdigest.tech/blog/claude-code-permissions-settings-guide) — 含 `/permissions` 交互管理与三层配置优先级的实用指南。
5. [Configure permissions - Claude Code Docs (English)](https://code.claude.com/docs/en/permissions) — 英文官方文档，用于交叉核对规则串与模式行为的最新定义。

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)