本页目录10
- `autoMode` 块含四个字段:environment、allow、soft_deny、hard_deny,均为自然语言描述字符串数组,非正则或工具模式
- 在任意字段数组中加入字面值 `"$defaults"` 可在该位置展开内置规则;省略则完全替换整个默认列表(危险)
- 规则优先级从高到低:hard_deny → soft_deny → allow → 用户明确意图
- 三条 CLI 子命令:claude auto-mode defaults / config / critique,分别用于查看内置规则、有效配置和审查自定义规则
- 分类器不从项目共享文件 `.claude/settings.json` 读取 `autoMode`,防止已检入仓库自行注入 allow 规则
- Bedrock / Vertex AI / Foundry 用户须先设置环境变量 `CLAUDE_CODE_ENABLE_AUTO_MODE` 才能启用 auto mode
本文是对官方「Configure auto mode」参考页的中文整理,完整与最新内容以原文为准。原文链接:https://code.claude.com/docs/en/auto-mode-config
概述
Auto mode 通过分类器路由工具调用,自动放行常规内部操作,拦截不可逆、破坏性或指向环境外部的操作,从而消除例行权限提示。autoMode 设置块用于告知分类器哪些仓库、存储桶和域名属于可信范围。
平台要求: Auto mode 对 Anthropic API 用户开箱可用。在 Amazon Bedrock、Google Cloud Vertex AI、Microsoft Foundry 上,须先设置 CLAUDE_CODE_ENABLE_AUTO_MODE。
开箱默认仅信任工作目录及当前仓库已配置的远程地址。推送到公司 SCM 组织或写入团队云存储桶需在 autoMode.environment 中声明后才会被放行。
配置读取位置
分类器与 Claude 本身共享同一份 CLAUDE.md 内容——写在项目 CLAUDE.md 里的行为规则同时约束 Claude 和分类器。跨项目的基础设施规则使用 autoMode 设置块。
| 作用范围 | 文件路径 | 适用场景 |
|---|---|---|
| 单个开发者 | ~/.claude/settings.json | 个人可信基础设施 |
| 单项目单开发者 | .claude/settings.local.json | 项目级可信存储桶或服务 |
| 全组织 | 托管设置 (Managed settings) | 分发给所有开发者的可信基础设施 |
--settings flag 或 Agent SDK | 内联 JSON | 自动化流水线的单次调用覆盖 |
重要限制: 分类器不从项目共享设置 .claude/settings.json 读取 autoMode,防止已检入仓库自行注入 allow 规则。各作用范围条目合并生效;开发者可扩展各字段,但无法移除托管设置中已有的条目。
autoMode 字段一览
| 字段 | 类型 | 作用 | 缺省行为 |
|---|---|---|---|
environment | 字符串数组 | 声明可信仓库、存储桶、域名和服务 | 仅信任工作目录及当前仓库配置的远程地址 |
allow | 字符串数组 | 为 soft_deny 规则添加例外 | 内置例外列表 |
soft_deny | 字符串数组 | 可被用户明确意图或 allow 覆盖的阻断规则 | 内置规则(含强制推送、curl | bash、生产部署等) |
hard_deny | 字符串数组 | 无条件阻断规则,不可被用户意图或 allow 覆盖 | 内置规则(含数据外泄、绕过 auto mode 等) |
所有字段均为自然语言描述的字符串数组,分类器将其作为语义规则读取,而非正则表达式或工具模式。
"$defaults" 特殊值
在任意字段数组中加入字面字符串 "$defaults" 可在该位置展开内置规则,保留默认值的同时追加自定义条目。
| 写法 | 效果 |
|---|---|
数组中包含 "$defaults" | 内置规则保留并在该位置展开,自定义条目前置或后置 |
数组中不包含 "$defaults" | 完全替换该字段的整个默认列表(高风险) |
警告: 省略
"$defaults"会丢弃该字段全部内置规则。soft_deny不含"$defaults"将移除强制推送、curl | bash、生产部署等全部内置软阻断;hard_deny不含"$defaults"将移除数据外泄及 auto mode 绕过检测规则。每个字段独立评估,设置environment不影响其他字段的默认列表。
若需完全自定义某字段,应先运行 claude auto-mode defaults 打印内置规则,将其复制到配置文件后逐条审查修改。
规则优先级
分类器内部按以下四层优先级评估(Deny 和 explicit ask 规则在分类器之前评估,此处仅描述分类器内部顺序):
| 优先级 | 规则层 | 能否被覆盖 | 说明 |
|---|---|---|---|
| 1(最高) | hard_deny | 否 | 无条件阻断,用户意图与 allow 均无效 |
| 2 | soft_deny | 是(被 allow 或明确用户意图) | 默认阻断,可被例外覆盖 |
| 3 | allow | — | 作为 soft_deny 的例外放行 |
| 4 | 用户明确意图 | — | 用户消息中明确描述了即将执行的具体操作时覆盖剩余软阻断 |
明确意图的判定: 泛化请求不构成明确意图。「整理仓库」不授权强制推送;「强制推送这个分支」才是明确意图。
定义可信基础设施(environment)
对大多数组织而言,autoMode.environment 是唯一需要配置的字段。推荐涵盖的内容类别:
| 类别 | 写法示例 |
|---|---|
| 组织信息 | 公司名称及 Claude Code 主要用途(软件开发、基础设施自动化等) |
| 源代码管理 | 所有开发者推送的 GitHub / GitLab / Bitbucket 组织地址 |
| 云提供商与可信存储桶 | s3://acme-build-artifacts、gs://acme-ml-datasets 等 |
| 可信内部域名 | *.corp.example.com、api.internal.example.com |
| 关键内部服务 | CI、制品仓库、内部包索引、故障响应工具(含地址) |
| 附加上下文 | 合规要求、多租户基础设施、受监管行业约束等 |
推荐落地顺序: ① 先添加源代码管理组织与核心内部服务(解决最多误拦截);② 再加可信域名和云存储桶;③ 最后随拦截记录补充其余上下文。
CLI 子命令
| 命令 | 输出格式 | 说明 |
|---|---|---|
claude auto-mode defaults | JSON | 打印内置的 environment、allow、soft_deny、hard_deny 规则 |
claude auto-mode config | JSON | 打印分类器实际使用的有效配置("$defaults" 已原位展开) |
claude auto-mode critique | AI 反馈 | 审查自定义 allow、soft_deny、hard_deny 规则,标记模糊、冗余或易误报条目 |
推荐工作流: 修改设置后运行 claude auto-mode config 确认有效规则符合预期;编写自定义规则后运行 claude auto-mode critique 检查规则质量。
查看拒绝记录
| 操作 | 位置 / 方式 |
|---|---|
| 查看被拒绝的工具调用 | 进入 /permissions → 「Recently denied」标签页 |
| 标记重试 | 在被拒操作上按 r,退出对话框后 Claude Code 通知模型重试并恢复会话 |
| 排查反复拒绝原因 | 通常表示分类器缺少上下文,将该目标加入 autoMode.environment,再用 claude auto-mode config 确认生效 |
| 以编程方式响应拒绝 | 使用 PermissionDenied hook |
与其他机制的关系
| 机制 | 执行时机 | 能否被 autoMode 覆盖 |
|---|---|---|
permissions.deny | 分类器运行之前 | 否,最高优先级,无法被 autoMode 覆盖 |
autoMode.hard_deny | 分类器内,第一层 | 否,用户意图与 allow 均无效 |
autoMode.soft_deny | 分类器内,第二层 | 是,可被 allow 或明确用户意图覆盖 |
autoMode.allow | 分类器内,第三层 | — |
| CLAUDE.md 行为规则 | 同时约束 Claude 与分类器 | — |
相关文档
| 文档 | 说明 |
|---|---|
| Permission modes | auto mode 的含义、默认阻断项及启用方式 |
| Managed settings | 在组织范围内分发 autoMode 配置 |
| Permissions | 在分类器运行前生效的 allow / ask / deny 规则 |
| Settings | 完整设置参考,包含 autoMode 键的完整定义 |