它到底是什么

claude auto-mode defaults 是 Claude Code CLI 内置的一个只读诊断子命令,功能是将 auto mode 分类器的内置规则集以 JSON 格式打印到标准输出。输出包含四个数组字段:environment(受信基础设施描述)、allow(放行例外)、soft_deny(可被用户意图覆盖的软拦截规则)、hard_deny(无条件硬拦截规则)。

它是 claude auto-mode 子命令族中三条命令之一:

平台/订阅限制:在 Anthropic API 上直接可用。在 Amazon Bedrock、Google Vertex AI、Microsoft Foundry 上同样支持,但官方文档要求先设置环境变量 CLAUDE_CODE_ENABLE_AUTO_MODE(并非"不支持")。Team / Enterprise 由管理员在控制台侧管理。

版本里程碑:本指南早期曾标注 $defaults(v2.1.118)、hard_deny(v2.1.136)的引入版本,但这些版本号缺乏官方 changelog 佐证(hard_deny 仅见于第三方博客),已移除以免误导。具体字段在你当前版本是否可用,请以 claude auto-mode defaults 实际输出为准。

怎么触发 / 怎么使用

1. 直接打印到终端

claude auto-mode defaults

输出 JSON 到 stdout,包含四个字段的内置规则数组。

2. 保存到文件(官方推荐工作流)

claude auto-mode defaults > rules.json

将输出写入 rules.json,之后可手工编辑——删除或修改内置规则——再将结果粘贴回 settings 文件,替换 "$defaults" 哨兵。这是唯一安全地「移除或改写某条内置规则」的方式。

3. 对比有效配置

# 先看内置规则
claude auto-mode defaults

# 再看合并后的有效配置($defaults 已展开)
claude auto-mode config

两者 diff 可让你确认自定义 settings 是否正确被合并进去。

4. 典型完整工作流

# 1. 把内置规则导出
claude auto-mode defaults > ~/.claude/auto-mode-defaults.json

# 2. 编辑,剔除不需要的规则
$EDITOR ~/.claude/auto-mode-defaults.json

# 3. 用编辑后的内容替换 settings.json 中对应字段的 "$defaults"
#    (手工粘贴到 ~/.claude/settings.json 的 autoMode.soft_deny 等字段)

# 4. 验证有效配置
claude auto-mode config

# 5. 审查自定义规则质量
claude auto-mode critique

保存 / 配置 / 集成

settings 文件路径

注意:分类器不会读取项目共享设置 .claude/settings.json 里的 autoMode 字段,防止 repo 自行注入允许规则。

标准 autoMode settings 结构

{
  "autoMode": {
    "environment": [
      "$defaults",
      "Organization: Acme Corp. Primary use: software development",
      "Source control: github.com/acme-corp and all repos under it",
      "Trusted cloud buckets: s3://acme-build-artifacts",
      "Trusted internal domains: *.corp.example.com"
    ],
    "allow": [
      "$defaults",
      "Deploying to the staging namespace is allowed: isolated, resets nightly",
      "Writing to s3://acme-scratch/ is allowed: 7-day ephemeral lifecycle"
    ],
    "soft_deny": [
      "$defaults",
      "Never run database migrations outside the migrations CLI",
      "Never modify files under infra/terraform/prod/"
    ],
    "hard_deny": [
      "$defaults",
      "Never send repository contents to third-party code-review APIs"
    ]
  }
}

$defaults 哨兵

在任意数组中写入字符串 "$defaults",内置规则就会在该位置展开合并。这样你的自定义条目既可放在默认规则前面(更高优先级上下文),也可放在后面,并且能随版本升级自动继承新增内置规则。

autoMode.classifyAllShell(v2.1.193 新增)

默认情况下,auto mode 分类器只对疑似任意代码执行的 Bash/PowerShell 命令做语义分类(其余命令走更轻的快速路径)。v2.1.193 起新增布尔设置 autoMode.classifyAllShell:置为 true 后,所有 Bash/PowerShell 命令都会被送进分类器评估,而不再仅限于任意代码执行模式。适用于希望把每一条 shell 命令都纳入 soft_deny/hard_deny/allow 自然语言规则判定的高安全场景,代价是更多命令要过一次分类器(略增延迟与误报面)。

{
  "autoMode": {
    "classifyAllShell": true
  }
}

来源:Claude Code changelog v2.1.193 —— "Added autoMode.classifyAllShell setting to route all Bash/PowerShell commands through the auto-mode classifier instead of only arbitrary-code-execution patterns"。该设置较新,官方 auto-mode-config 文档页尚未收录,以 changelog 与实际 settings schema 为准。

同版(v2.1.193)还把拒绝原因写入了 transcript、拒绝 toast 和 /permissions 的最近拒绝列表,排查"为什么这条被拦"时可直接在这三处看到具体理由。

与 CLAUDE.md 集成

分类器同时读取 CLAUDE.md 中的文本。例如在项目 CLAUDE.md 中写 never force push(普通英文指令),这条约束会同时作用于 Claude 和分类器。项目行为约定放 CLAUDE.md,跨项目的基础设施信任规则放 autoMode.environment。

运行约束 / 限制

跟同类原语对比

关键区别:permissions.deny 是确定性的工具模式拦截,在分类器调用前生效;hard_deny 是 NLP 驱动的语义拦截,在分类器内运行。两者互补,不互斥。

经典使用场景

• 初次接入 auto mode 前的安全审查:运行 claude auto-mode defaults > rules.json,浏览内置的 hard_deny 和 soft_deny 列表,确认你能接受这些规则再启用 auto mode。

• 定制化替换某条内置规则:某条内置 soft_deny 规则在你的团队流程里是误报(例如内部部署到 staging 被错误拦截),先 defaults > rules.json,删掉那条规则,把剩余内容粘贴到 settings 中,代替 "$defaults"。

• 组织 Managed Settings 基线制定:安全团队拉出内置规则,逐条结合合规要求注释评审,将修改后的版本写入 Managed Settings 下发全员,形成可版本控制的安全基线。

• 升级版本后规则 diff:升级 Claude Code 后重新运行 claude auto-mode defaults,与上次存档对比,了解新版本增删了哪些内置规则,评估是否影响现有 pipeline。

• 调试重复拒绝问题:某条操作反复被 auto mode 拦截,先跑 claude auto-mode config 看有效规则,再跑 defaults 确认拦截来自内置规则还是自定义规则,针对性修改 allow 或 environment。

常见坑

1. 忘写 $defaults 导致丢失所有内置规则
   只要你在 settings 里写了 "soft_deny": ["自定义规则"] 而没有 "$defaults",内置的 force-push 拦截、curl | bash 拦截、生产部署拦截全部失效。正确写法是 ["$defaults", "自定义规则"]。

2. 把 autoMode 写到项目共享 settings 里
   .claude/settings.json(进入 git 的那个)里的 autoMode 字段会被分类器完全忽略。想做项目级配置必须用 .claude/settings.local.json(gitignored)或 Managed Settings。

3. 误以为自然语言规则是精确匹配
   soft_deny / allow 的条目是给分类器 LLM 读的散文描述,不是 glob 或 regex。写得太笼统(比如 "block all writes")会产生大量误报,建议附上业务理由("…because production infra changes must go through the review workflow")。

4. hard_deny 是较新引入的字段
   hard_deny 在早期 auto mode 版本中不存在(早期仅 environment、allow、soft_deny 三个字段)。其确切引入版本无官方 changelog 佐证,使用前请用 claude auto-mode defaults 确认当前版本是否输出该字段。

5. 以为 claude auto-mode defaults 和 claude auto-mode config 输出相同
   defaults 只显示内置规则(无个人/组织设置影响);config 是合并展开后的有效规则,$defaults 已被真实列表替换。调试时必须用 config,而非 defaults。

关闭 / 退出 / 卸载

claude auto-mode defaults 本身是只读命令,无需关闭。

若要禁用 auto mode:

据 SmartScope,组织级管理员可在 Managed Settings 中用字符串值禁用 auto mode 入口:

// Managed Settings
{
  "disableAutoMode": "disable"
}

注:个人配置中用布尔 true 禁用的写法无可靠来源佐证,已移除;以官方文档 / 实际 settings schema 为准。

若只想对当次会话不使用 auto mode,在会话中按 Shift+Tab 循环切换权限模式(normal → accept edits → plan → auto),切走即可。

来源

• Configure auto mode — Claude Code Docs (code.claude.com)
• Claude Code Auto Mode Complete Guide — SmartScope
• Step-by-Step: Complete Auto Mode configuration — Daniel Avila / Medium
• Auto mode for Claude Code — Simon Willison's Weblog
• Claude Code Auto Mode gist — sc0tfree / GitHub Gist