claude-code/docs/safety/auto-mode.mdx

---
title: "Auto Mode - AI 分类器驱动的自主执行模式"
description: "详解 Claude Code 的 auto mode：基于 transcript classifier 的自动权限决策、两阶段分类流水线、危险权限剥离机制、模式切换状态管理、以及与 plan mode 的协作方式。"
keywords: ["auto mode", "yoloClassifier", "transcript classifier", "权限分类", "自动执行", "两阶段分类"]
---

## 概述

Auto mode 是 Claude Code 的一种权限模式，让 AI 进入**连续自主执行**状态。与传统模式（每个敏感操作都弹出权限对话框等待用户审批）不同，auto mode 使用 AI 分类器（transcript classifier）自动判断每个工具调用是否安全，从而实现无中断的执行体验。

```
权限模式层级：

default  →  auto  →  bypassPermissions
（逐项确认） （AI 分类器审批） （全部放行）
```

## 核心架构

### 1. AI 分类器（yoloClassifier）

分类器是 auto mode 的核心，位于 `src/utils/permissions/yoloClassifier.ts`。

每个工具调用经过分类器评估，返回三种裁决之一：

| 裁决 | 含义 | 处理方式 |
|------|------|---------|
| **allow** | 操作安全 | 直接执行，用户无感知 |
| **deny** | 操作危险 | 拒绝执行，向 AI 返回拒绝消息 |
| **ask** | 无法确定 | 回退到传统权限对话框 |

分类器的判断基于完整的对话上下文（transcript），而不仅仅看单条命令——它能理解操作的意图和上下文。

### 2. 两阶段分类流水线

分类器支持两阶段 XML 分类（`classifyYoloActionXml`）：

```
Stage 1 — "fast"（快速判断）
├── max_tokens=64，stop_sequences 触发即时 yes/no
├── 如果 allow → 直接放行（最快路径）
└── 如果 block → 进入 Stage 2

Stage 2 — "thinking"（深度思考）
├── chain-of-thought 推理
├── 减少误报（false positives）
└── 最终决定 allow / deny / ask
```

两个阶段共享相同的 system prompt 和 user content，利用 API 的 prompt caching（1 小时 TTL）优化性能。

可通过配置选择模式：
- `'both'`（默认）— 两阶段都跑
- `'fast'` — 只跑 Stage 1
- `'thinking'` — 只跑 Stage 2

### 3. 分类器结果类型

```typescript
// src/types/permissions.ts
type YoloClassifierResult = {
  thinking?: string          // 分类器的推理过程
  shouldBlock: boolean       // 是否阻止
  reason: string             // 决策原因
  unavailable?: boolean      // 分类器是否不可用
  transcriptTooLong?: boolean // 对话是否超出上下文窗口
  model: string              // 使用的分类器模型
  stage?: 'fast' | 'thinking' // 哪个阶段做出的决定
  // ... token 使用量、耗时等监控字段
}
```

## 安全机制

### 危险权限剥离

进入 auto mode 时，系统调用 `stripDangerousPermissionsForAutoMode()`（`permissionSetup.ts:510`），移除所有可能绕过分类器的 allow 规则。

被剥离的规则类型（`dangerousPatterns.ts`）：

| 规则类型 | 示例 | 剥离原因 |
|---------|------|---------|
| **Bash 代码执行** | `Bash(python:*)`, `Bash(node:*)` | 解释器可执行任意代码，绕过分类器审查 |
| **Shell 入口** | `Bash(bash:*)`, `Bash(sh:*)` | 直接 shell 访问等同无限制 |
| **Agent 规则** | `Agent(*)` | 任何 Agent allow 规则会绕过分类器审批子代理 |
| **PowerShell 代码执行** | `PowerShell(node:*)` | 同 Bash 逻辑 |
| **权限提升** | `Bash(sudo:*)`, `Bash(eval:*)` | 可执行任意命令 |

剥离的规则被暂存在 `strippedDangerousRules` 中，退出 auto mode 时通过 `restoreDangerousPermissions()` 恢复。

### 模型支持检测

不是所有模型都支持 auto mode。`modelSupportsAutoMode()`（`src/utils/betas.ts`）检查当前模型是否具备安全分类能力。不支持的模型无法进入 auto mode。

### Circuit Breaker 机制

`autoModeState.ts` 维护一个 circuit breaker 标志：

```typescript
let autoModeCircuitBroken = false  // 由远程配置控制
```

当远程配置（GrowthBook `tengu_auto_mode_config.enabled`）设为 `'disabled'` 时，circuit breaker 触发，阻止 auto mode 的进入和继续使用。这为 Anthropic 提供了远程紧急关停能力。

## 模式切换状态管理

### 进入 Auto Mode

`transitionPermissionMode()`（`permissionSetup.ts:597`）处理所有模式切换：

```
1. 检查 auto mode gate 是否开启（isAutoModeGateEnabled）
2. 设置 autoModeActive = true
3. 调用 stripDangerousPermissionsForAutoMode() 剥离危险规则
4. 向对话注入 Auto Mode 系统提示
```

### 退出 Auto Mode

```
1. 设置 autoModeActive = false
2. 设置 needsAutoModeExitAttachment = true（触发退出通知）
3. 调用 restoreDangerousPermissions() 恢复被剥离的规则
4. 向对话注入 "Exited Auto Mode" 提示
```

### 触发路径

Auto mode 可通过以下方式激活：
- CLI 参数 `--enable-auto-mode`
- settings.json 中的 `autoMode` 配置
- Plan mode 默认使用 auto mode 语义（`useAutoModeDuringPlan`，默认 true）
- SDK 控制消息
- REPL 中 Shift+Tab 切换

## 系统提示词

### 进入时（Full Instructions）

注入到对话中的指令（`messages.ts:3464`）：

> Auto mode is active. The user chose continuous, autonomous execution. You should:
>
> 1. **Execute immediately** — 直接实现，做合理假设
> 2. **Minimize interruptions** — 常规决策自行判断，减少提问
> 3. **Prefer action over planning** — 默认直接编码，不进 plan mode
> 4. **Expect course corrections** — 用户可随时纠正
> 5. **Do not take overly destructive actions** — 删除数据/修改生产系统仍需确认
> 6. **Avoid data exfiltration** — 不主动分享密钥/内部文档

### 持续运行时（Sparse Instructions）

后续轮次注入简短提醒：

> Auto mode still active. Execute autonomously, minimize interruptions, prefer action over planning.

### 退出时（Exit Instructions）

> You have exited auto mode. Ask clarifying questions when the approach is ambiguous rather than making assumptions.

## 与 Plan Mode 的协作

Plan mode 默认使用 auto mode 语义（`getUseAutoModeDuringPlan()`，默认 true）。这意味着：

- Plan mode 进入时，如果 auto mode 可用，也会激活分类器
- `isAutoModeActive()` 是权威信号（`prePlanMode`/`strippedDangerousRules` 不可靠）
- 退出 plan mode 时会同时退出 auto mode

## 分类器不可用的降级策略

当分类器 API 不可用时（`unavailable: true` 或 `transcriptTooLong: true`）：

- 不会直接 allow — 回退到传统的权限对话框（ask）
- 向 AI 发送消息："{model} is temporarily unavailable, so auto mode cannot determine the safety of {toolName} right now."
- 确定性错误（如对话过长）不重试，直接降级

## 相关源码索引

| 文件 | 职责 |
|------|------|
| `src/utils/permissions/yoloClassifier.ts` | 分类器核心实现 |
| `src/utils/permissions/autoModeState.ts` | Auto mode 状态管理 |
| `src/utils/permissions/permissionSetup.ts` | 模式切换、危险权限剥离 |
| `src/utils/permissions/dangerousPatterns.ts` | 危险命令模式列表 |
| `src/utils/permissions/classifierDecision.ts` | 分类器决策处理 |
| `src/utils/permissions/classifierShared.ts` | 分类器共享逻辑 |
| `src/utils/messages.ts` | Auto mode 系统提示词 |
| `src/types/permissions.ts` | 权限类型定义 |
| `src/utils/betas.ts` | 模型 auto mode 支持检测 |