所有设置

设置索引

模型与回复

advisorModel

• 作用域：Any file
• 类型：字符串，可以是别名 "fable"、"opus" 或 "sonnet" 之一（解析为 Claude Code 当前该模型系列的默认版本），也可以是完整的模型 ID，例如 "claude-opus-5-5"
• 默认值：未设置，因此 advisor 处于关闭状态
• 单会话覆盖：--advisor 在单个会话中优先于此键。CLAUDE_CODE_DISABLE_ADVISOR_TOOL 会关闭 advisor，且此键无法将其重新打开

{
  "advisorModel": "opus"
}

alwaysThinkingEnabled

• 作用域：Any file
• 类型：Boolean
  • true：不起作用；思考已经处于开启状态
  • false：Claude Code 在所有会话中关闭扩展思考
• 默认值：未设置，因此在支持思考的模型上思考处于开启状态
• 单会话覆盖：MAX_THINKING_TOKENS 在单个会话中优先于此键：0 会关闭思考（受与 false 相同的模型和提供商限制），正值则会开启思考，即使此键为 false。在自适应推理模型上，该数值本身会被忽略

{
  "alwaysThinkingEnabled": false
}

availableModels

• 作用域：Any file。在托管设置中部署此项可对整个组织强制执行。
• 类型：模型别名或 ID 的数组
• 默认值：未设置，因此所有模型都可用

{
  "availableModels": ["sonnet", "haiku"]
}

availableModelsMatch

• 作用域：Managed。Claude Code 会忽略用户、项目和本地设置以及 --settings 中的此键，并给出警告
• 类型：字符串，可选值之一：
  • "prefix"：模型 ID 条目允许其对应版本以及在其基础上再扩展一个段的任何模型 ID
  • "exact"：模型 ID 条目只允许其指定的版本，因此 "claude-opus-5" 允许 Opus 5 但不允许 claude-opus-5-5。诸如 "claude-opus-4-5" 之类的条目还会允许其带日期的 Anthropic 模型 ID claude-opus-4-5-20251101。诸如 "opus" 之类的系列别名仍允许整个系列，而 best、opusplan 和 default 条目会被忽略
• 默认值："prefix"

{
  "availableModels": ["claude-opus-5", "claude-sonnet-5"],
  "availableModelsMatch": "exact"
}

deniedModels

• 作用域：Managed。Claude Code 会忽略用户、项目和本地设置以及 --settings 中的此键，并给出警告
• 类型：模型别名或 ID 的数组
  • 诸如 "opus" 之类的系列别名会阻止该系列中的所有模型
  • 诸如 "claude-opus-5-5" 之类的模型 ID 会阻止该版本的所有写法，包括带日期的 ID 和提供商特定的 ID
  • 不带次版本号的模型 ID（例如 "claude-opus-5"）也会阻止后续的次版本，例如 Opus 5.5。如需仅阻止 Opus 5，请写成 "claude-opus-5-0"
  • best、opusplan 和 default 条目会被忽略
• 默认值：未设置，因此不阻止任何模型

{
  "availableModels": ["opus", "sonnet"],
  "deniedModels": ["claude-opus-5-5"]
}

effortLevel

• 作用域：Any file
• 类型：字符串，可选值之一：
  • "low"：推理最少，适用于简短、范围明确、对延迟敏感且对智能要求不高的任务
  • "medium"：为可以牺牲部分智能的成本敏感型工作减少 token 使用量
  • "high"：在 token 使用量和智能之间取得平衡
  • "xhigh"：以更高的 token 消耗进行更深入的推理
• 默认值：未设置
• 单会话覆盖：--effort 在单个会话中优先于此键，而 CLAUDE_CODE_EFFORT_LEVEL 优先于两者

{
  "effortLevel": "xhigh"
}

enforceAvailableModels

• 作用域：Any file
• 类型：Boolean
  • true：当 Default 会解析到 availableModels 之外的模型时，Claude Code 会将其解析为列表中第一个可用的模型
  • false：此键不改变 Default 的解析方式
• 默认值：false

{
  "availableModels": ["sonnet", "haiku"],
  "enforceAvailableModels": true
}

fallbackModel

• 作用域：Any file
• 类型：模型别名或 ID 的数组；"default" 会展开为默认模型
• 默认值：未设置，因此失败的请求不会在其他模型上重试
• 单会话覆盖：--fallback-model 在单个会话中优先于此键

{
  "fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"]
}

fastMode

• 作用域：Any file
• 类型：Boolean
  • true：Claude Code 在可用的会话中开启快速模式。在 Fable 5.2 上，您还必须在使用 Fable 5.2 时运行 /fast
  • false：快速模式保持关闭
• 默认值：未设置，因此快速模式处于关闭状态
• 单会话覆盖：CLAUDE_CODE_DISABLE_FAST_MODE 会在单个会话中关闭快速模式，且此键无法将其重新开启

{
  "fastMode": true
}

fastModePerSessionOptIn

• 作用域：Any file
• 类型：Boolean
  • true：已保存的 fastMode: true 不再在会话开始时开启快速模式，因此每个人需要在每个想要使用快速模式的会话中运行 /fast；通过 --settings 传入的 fastMode: true 仍对该会话有效，除非托管设置设置了此键
  • false：已保存的 fastMode: true 按照 fastMode 所述的方式生效
• 默认值：false

{
  "fastModePerSessionOptIn": true
}

language

• 作用域：Any file
• 类型：字符串，任意语言名称，例如 "japanese"、"spanish" 或 "french"；Claude Code 不会对其进行验证
• 默认值：未设置；此时会话标题与您对话所用的语言一致

{
  "language": "japanese"
}

maxEffortLevel

• 作用域：Any file。在托管设置中部署此项可对整个组织强制执行。当多个作用域设置了上限时，以最低的上限为准，因此在一个作用域中设置的上限无法从另一个作用域提高
• 类型：字符串，可以是 "low"、"medium"、"high"、"xhigh" 或 "max" 之一。值为 "max" 时不设上限
• 默认值：未设置，因此不应用任何上限
• 按模型设置上限：在模型的 modelSettings 条目中添加 maxEffortLevel。只有在同时设置了两者的设置来源中（例如您的用户设置或某个托管来源），该条目才会针对该模型替代此键。在该条目中设置 "max" 可使该模型不受该来源上限的限制；Claude Code 仍会应用来自其他来源的上限

{
  "maxEffortLevel": "medium",
  "modelSettings": {
    "claude-sonnet-4-6": {
      "maxEffortLevel": "max"
    }
  }
}

model

• 作用域：Any file
• 类型：字符串，模型别名或完整的模型 ID
• 默认值：未设置，因此 Claude Code 使用您账户的默认模型
• 单会话覆盖：--model 优先于 ANTHROPIC_MODEL，两者在单个会话中都优先于此键，包括托管的 model；availableModels 列表仍适用于所做的选择

{
  "model": "claude-sonnet-5"
}

modelOverrides

• 作用域：Any file
• 类型：将模型 ID 映射到提供商模型 ID 的对象
• 默认值：未设置

{
  "modelOverrides": {
    "claude-opus-4-6": "arn:aws:bedrock:us-east-1:123456789012:inference-profile/example"
  }
}

modelPicker

• 作用域：User or managed。Claude Code 从托管设置、--settings 和用户设置中读取此键，并忽略项目和本地设置中的此键，以防止您克隆的仓库重新标记选择器。这三者中设置了此键的最高一级提供整个模型列表，Claude Code 从不合并来自两个来源的列表。
• 类型：包含行数组 options 和可选 Boolean 值 replaceBuiltInOptions 的对象
• 默认值：未设置，因此选择器显示内置模型列表

{
  "modelPicker": {
    "options": [
      { "model": "us.anthropic.claude-opus-4-8", "label": "Opus (production)" },
      {
        "model": "us.anthropic.claude-sonnet-4-6",
        "label": "Sonnet (production)",
        "description": "Day-to-day work"
      }
    ]
  }
}

modelPicker 的字段

• 丢弃：Claude Code 无法提供的行，例如已停用的模型或您的组织无权访问的模型
• 灰显：您暂时无法选择的行，会显示原因
• 没有保留任何行：Claude Code 保留内置模型列表，并照常按允许列表过滤

modelPricing

• 作用域：Managed。通过服务器托管设置、MDM 策略、managed-settings.json 文件或策略辅助程序部署此键。Claude Code 会忽略用户、项目和本地设置、--settings 以及 Windows 上用户可写的 HKCU 注册表中的此键。使用服务器托管设置时，每个会话会按标价报告成本，直到该会话的设置获取确认了该设置为止。嵌入 Claude Code 并设置了 CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST 的宿主应用程序可以通过 SDK 的 managedSettings 选项提供自己的费率表，Claude Code 仅在没有托管来源设置此键时才使用该表，并且仅限 Claude Code v2.1.246 或更高版本。
• 类型：包含可选 multiplier 和可选 overrides 映射的对象
• 默认值：未设置，因此除非宿主应用程序提供了费率表，否则 Claude Code 按标价报告

{
  "modelPricing": {
    "multiplier": 0.85,
    "overrides": {
      "claude-sonnet-4-6": {
        "input": 2.4,
        "output": 12,
        "cacheRead": 0.24,
        "cacheWrite": 3
      }
    }
  }
}

modelPricing 的字段

modelPricing 行适用于哪些模型

• 内置模型的 ID：Claude Code 自身用于内置模型的键，无论该键是模型自己的 ID（例如 claude-sonnet-4-6），还是其 Bedrock、Agent Platform 或 Foundry ID。Claude Code 会将该行应用于该模型的每个带日期的快照 ID 和提供商特定 ID。
• 任何其他键：不是内置模型 ID 的键，例如网关模型别名。Claude Code 只将该行应用于这一个 ID。当某个模型 ID 与您的某个键完全匹配，同时又属于以内置模型 ID 为键的行时，Claude Code 使用完全匹配的那一行。
• Bedrock 应用程序推理配置文件：一旦 Claude Code 通过您的 modelOverrides 映射或 bedrock:GetInferenceProfile 查询将该配置文件解析为其路由到的模型，Claude Code 就会将该模型的行应用于该配置文件。

modelSettings

• 作用域：Any file
• 类型：将模型名称映射到对象的对象，该对象可包含以下任意字段：
  • effortLevel："low"、"medium"、"high" 或 "xhigh" 之一
  • maxEffortLevel：该模型可以运行的最高 effort 级别
  • autoCompactWindow：从 100000 到 1000000 的 token 数，或表示为该模型调优的窗口的 "auto"。/autocompact 会保存到此处。对于该模型，此值优先于同一设置文件中的顶层 autoCompactWindow。需要 Claude Code v2.1.288 或更高版本
• 默认值：未设置

{
  "modelSettings": {
    "claude-opus-5-5": {
      "effortLevel": "high"
    }
  }
}

outputStyle

• 作用域：Any file
• 类型：字符串，内置或自定义输出样式的名称
• 默认值：未设置，因此 Claude Code 使用默认样式

{
  "outputStyle": "Explanatory"
}

promptCacheTtl

• 作用域：Any file
• 类型：字符串，可选值之一：
  • "5m"：缓存保留五分钟
  • "1h"：缓存保留一小时
• 默认值：未设置，因此每个主对话请求使用其默认生命周期
• 单会话覆盖：FORCE_PROMPT_CACHING_5M 优先于其他所有方式，其次是 CLAUDE_CODE_PROMPT_CACHE_TTL，然后是此键，最后是 ENABLE_PROMPT_CACHING_1H

{
  "promptCacheTtl": "1h",
  "subagentPromptCacheTtl": "5m"
}

showThinkingSummaries

• 作用域：Any file
• 类型：Boolean
  • true：使用 Ctrl+O 展开思考时，您会看到完整的思考摘要
  • false：Anthropic API 会对思考块进行编辑隐藏，Claude Code 显示折叠的占位内容
• 默认值：false

{
  "showThinkingSummaries": true
}

subagentPromptCacheTtl

• 作用域：Any file
• 类型：字符串，可选值之一：
  • "5m"：缓存保留五分钟
  • "1h"：缓存保留一小时
• 默认值：未设置，因此这些请求各自使用其默认生命周期
• 单会话覆盖：FORCE_PROMPT_CACHING_5M 优先于其他所有方式，其次是 CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL，然后是此键，再然后是 ENABLE_PROMPT_CACHING_1H，后者会为每个请求要求一小时生命周期。有关子代理自身 frontmatter 值的优先级位置，请参阅自行选择 TTL

{
  "subagentPromptCacheTtl": "1h"
}

switchModelsOnFlag

• 作用域：Any file。在 /config 中显示为 Switch models when a message is flagged，选项为 Switch automatically 和 Ask each time。
• 类型：Boolean
  • true：Claude Code 切换到备用模型并继续
  • false：在交互式会话中，Claude Code 会暂停，以便您在切换和编辑提示词之间做出选择；在无法显示对话框的情况下（例如 -p 运行），被标记的请求会以错误结束
• 默认值：未设置。Claude Code 会自动切换，但在交互式会话中可能会先询问

{
  "switchModelsOnFlag": false
}

ultracode

• 作用域：Any file
• 类型：Boolean
  • true：当为您启用了动态工作流且您的模型支持 xhigh 时，会话以开启 ultracode 的状态启动
  • false：会话以关闭 ultracode 的状态启动
• 默认值：未设置，因此 ultracode 处于关闭状态
• 单会话覆盖：/effort ultracode 无需此键即可为单个会话开启 ultracode，而当此键为 true 时，/effort ultracode off 会为单个会话关闭它。--effort ultracode 标志也会为单个会话开启它，并使用 xhigh effort

{
  "ultracode": true
}

权限设置

allowManagedPermissionRulesOnly

• 仓库的 .claude/ 目录
• 您的 ~/.claude/skills/ 和 ~/.claude/commands/ 目录，包括从 claude.ai 同步的 skill
• --add-dir 目录
• 位于 ~/.claude/skills/ 或项目 .claude/skills/ 内、通过 .claude-plugin 清单声明的插件
• 仅为单个会话加载、ID 以 @inline 结尾的插件，前提是同时满足以下所有条件：
  • 该会话是由 Claude Desktop 应用自身启动 Claude Code 的 Code 会话或 Cowork 会话，云端会话除外
  • 该键由您的托管设置设置，而不仅仅由嵌入宿主的父级设置设置
  • 该会话运行 Claude Code v2.1.305 或更高版本

• 作用域：Managed
• 类型：Boolean
  • true：托管设置成为权限规则的唯一设置来源
  • false：除托管规则外，Claude Code 还会应用来自用户、项目、本地以及 --settings 文件的权限规则
• 默认值：未设置，因此除托管规则外，Claude Code 还会应用来自用户、项目和本地设置以及 --settings 的权限规则

{
  "allowManagedPermissionRulesOnly": true
}

autoMode

• 作用域：User or managed
• 类型：包含 environment、allow、soft_deny 和 hard_deny 文字描述规则数组以及 classifyAllShell Boolean 的对象
• 默认值：未设置，因此分类器仅使用其内置规则

{
  "autoMode": {
    "soft_deny": ["$defaults", "Never run terraform apply"]
  }
}

autoMode.classifyAllShell

• 作用域：User or managed。凡是读取 autoMode 的位置都会读取此键。
• 类型：Boolean
  • true：在自动模式处于活动状态时，Claude Code 将每条 Bash 和 PowerShell 命令交由分类器处理，并暂停您的 shell 允许规则；在自动模式之外，这些规则仍然适用
  • false：自动模式仅暂停可能运行任意代码的允许规则，例如 Bash(*) 和 Bash(python *)；与任何其他允许规则匹配的命令会跳过分类器，除非它带有按命令允许的域名，而其他所有 shell 命令都会经过分类器
• 默认值：false

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

disableAutoMode

• 作用域：Any file。在托管设置中最为有用，因为用户无法覆盖它。也可以在 permissions 下以 permissions.disableAutoMode 的形式设置。
• 类型：字符串 "disable"
• 默认值：未设置

{
  "disableAutoMode": "disable"
}

permissions

• 作用域：Any file
• 类型：包含 allow、ask、deny、additionalDirectories、blockReadsOutsideWorkingDirectories、blockWritesOutsideWorkingDirectories、defaultMode、denyInsteadOfPrompting、disableBypassPermissionsMode 和 disableAutoMode 的对象
• 默认值：未设置

{
  "permissions": {
    "allow": ["Bash(npm run *)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env)"],
    "defaultMode": "acceptEdits"
  }
}

useAutoModeDuringPlan

• 作用域：User, local, or managed。仓库无法替您关闭它。
  • 这些文件中任何一个或 --settings 中的 false 都会将其关闭，除非您使用 --setting-sources 等选项排除了该用户或本地文件。忽略被排除的文件需要 Claude Code v2.1.314 或更高版本
• 类型：Boolean
  • true：与未设置相同；当自动模式可用时，分类器会在规划期间审查 shell 命令
  • false：对于内置只读命令集之外的每条命令，您都会收到权限提示
• 默认值：true

{
  "useAutoModeDuringPlan": false
}

permissions.allow

• 作用域：Any file
• 类型：权限规则字符串数组
• 默认值：未设置
• 按会话覆盖：--allowedTools 为单个会话添加允许规则，而任何设置文件中的拒绝规则仍会阻止其所指定的工具

{
  "permissions": {
    "allow": ["Bash(git diff *)", "Read(~/.zshrc)"]
  }
}

权限规则语法

permissions.ask

• 作用域：Any file
• 类型：权限规则字符串数组
• 默认值：未设置

{
  "permissions": {
    "ask": ["Bash(git push *)"]
  }
}

permissions.deny

• 作用域：Any file
• 类型：权限规则字符串数组
• 默认值：未设置
• 按会话覆盖：--disallowedTools 会在此键之外为单个会话添加拒绝规则

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)",
      "Bash(curl *)"
    ]
  }
}

permissions.additionalDirectories

• 作用域：Any file，但项目和本地条目所授予的沙箱写入访问权限受到限制
• 类型：目录路径数组
• 默认值：未设置
• 按会话覆盖：--add-dir 和 /add-dir 会在此键之外为单个会话添加目录

{
  "permissions": {
    "additionalDirectories": ["../docs/"]
  }
}

permissions.blockReadsOutsideWorkingDirectories

• 任何模式都不会自动批准的操作介绍了读取此类路径的 shell 命令何时会向您发出提示
• 阻止状态下的沙箱命令介绍了沙箱中的命令可以读取哪些内容

• 作用域：Any file。任何文件中的 true 都会生效，因此仓库可以为自身开启阻止，但无法解除您设置的阻止。
• 类型：Boolean
  • true：Claude 的文件工具拒绝读取工作目录之外的内容
  • false：与未设置相同；如果其他文件设置了 true，阻止仍然适用
• 默认值：未设置，因此对工作目录之外内容的读取遵循您的权限模式

{
  "permissions": {
    "blockReadsOutsideWorkingDirectories": true
  }
}

阻止状态下的沙箱命令

• 已通过 sandbox.filesystem.disabled 关闭文件系统隔离
• 已设置 allowManagedReadPathsOnly
• 您启动 Claude Code 时所在目录的路径包含 glob 字符，例如 *、? 或 [

• ~/.gitconfig
• $XDG_CONFIG_HOME/git（默认为 ~/.config/git）下的 config、ignore 和 attributes 文件
• 您的全局 git 配置通过 [include]、[includeIf]、core.excludesFile 或 core.attributesFile 指定的文件

permissions.blockWritesOutsideWorkingDirectories

• 作用域：Any file。会话加载的任何文件中的 true 都会生效，因此仓库可以为自身开启阻止，但无法解除您设置的阻止。在云端会话中，Claude Code 可能不会应用此键，因为文件工具运行在容器中，而容器本身就是边界。
• 类型：Boolean
  • true：开启阻止
  • false：与未设置相同；如果其他文件设置了 true，阻止仍然适用
• 默认值：未设置，因此对工作目录之外的写入遵循您的权限模式。当 Claude Code 无法读取您托管设置中的 permissions 对象时，该阻止也会开启。

{
  "permissions": {
    "blockWritesOutsideWorkingDirectories": true
  }
}

写入阻止会拒绝哪些写入以及哪些内容仍可写入

• Claude Code 设置文件：在工作目录内，Claude Code 同样会拒绝这些写入，因为设置文件可以解除该阻止。请自行编辑设置文件。
• 仅由仓库设置添加的目录：additionalDirectories 仅在 .claude/settings.json 中列出的目录，或仅在 .claude/settings.local.json 中列出的目录（除非 git 将该文件报告为未跟踪）
• 子代理的 worktree：当 isolation: worktree 子代理的 worktree 位于工作目录之外时，其文件编辑会被拒绝
• 仓库所选目录中的自动记忆：仓库设置中 autoMemoryDirectory 指定的目录

让单个目录通过读取或写入阻止

permissions.defaultMode

• 作用域：Any file。auto 和 bypassPermissions 在项目或本地设置中不生效，因此请改为在 ~/.claude/settings.json 中设置它们。在 v2.1.257 之前，bypassPermissions 在任何文件中都会生效。对于 VS Code 扩展启动的对话，Claude Code 仅读取用户、托管和 --settings 中的值。
• 类型：字符串，取值之一：
  • "default"：Claude Code 无需询问仅执行读取操作
  • "acceptEdits"：Claude Code 还会无需询问即执行文件编辑和常见的文件系统命令，例如 mkdir 和 mv
  • "plan"：Claude Code 会进行读取和规划，但在您批准计划之前阻止编辑
  • "auto"：Claude Code 运行时不会出现常规提示；在 shell 命令和网络请求等操作运行之前，后台分类器会检查这些操作是否与您的请求一致
  • "dontAsk"：Claude Code 自动拒绝所有原本会发出提示的调用，不过您安装的 mod 仍可批准其中部分调用。工作目录内的文件读取、其他无需批准的操作以及预先批准的工具仍会运行，但从网络路径进行的读取除外
  • "bypassPermissions"：Claude Code 无需询问即执行所有操作
  • "manual"："default" 的别名
• 默认值：未设置
• 按会话覆盖：--permission-mode 及其在 bypassPermissions 方面的等效项 --dangerously-skip-permissions 在单个会话中优先于此键

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

permissions.denyInsteadOfPrompting

• 作用域：User or managed，以及 --settings。仓库无法替您设置它。
• 类型：Boolean
  • true：Claude Code 拒绝原本会发出提示的调用
  • false：与未设置相同；如果这些来源中的另一个设置了 true，调用仍会被拒绝
• 默认值：未设置，因此需要批准的调用会向您发出提示

{
  "permissions": {
    "defaultMode": "auto",
    "denyInsteadOfPrompting": true
  }
}

denyInsteadOfPrompting 还会阻止什么

• 问题和计划工具：Claude Code 会省略 AskUserQuestion、EnterPlanMode 和 ExitPlanMode，因此处于计划模式的会话无法自行退出该模式。agent team 中的队友会保留 EnterPlanMode 和 ExitPlanMode
• MCP elicitation：Claude Code 会取消 elicitation 请求，除非有 Elicitation hook 对其作出应答
• 权限宿主：Claude Code 不会询问您的 canUseTool 回调或 --permission-prompt-tool。要通过代码批准调用，请通过 PermissionRequest hook 应答。某些调用会在询问任何 hook 之前就被拒绝，例如 auto 模式下未被任何 ask 规则覆盖的关键路径删除。
• 分类器计费通知：在关于计费分类器请求的通知会打开对话框的情况下，Claude Code 不会显示该通知，并会拒绝需要这些请求的操作

来自 denyInsteadOfPrompting 的消息

Permission for this tool use was denied. It requires approval, and this session has no approval surface

no approval surface in this session; permission request denied automatically

20 actions were refused and no work went ahead in between, so Claude stopped.

permissions.disableBypassPermissionsMode

• 作用域：Any file。通常在托管设置中设置，以强制执行组织策略。
• 类型：字符串 "disable"
• 默认值：未设置
• 按会话覆盖：此键优先于 --dangerously-skip-permissions，设置此键期间 Claude Code 会拒绝该标志

{
  "permissions": {
    "disableBypassPermissionsMode": "disable"
  }
}

skipAutoPermissionPrompt

• 作用域：User or managed。仓库无法替您设置它。
• 类型：Boolean
  • true：Claude Code 跳过该通知
  • false：与未设置相同；除非这些文件中的另一个设置了 true，否则通知会出现一次
• 默认值：未设置，因此通知会出现一次

{
  "skipAutoPermissionPrompt": true
}

skipDangerousModePermissionPrompt

• 作用域：User, local, or managed，以及通过 --settings 传入的文件。后台会话仅计入用户设置和托管设置。不受信任的仓库无法替您跳过该对话框。
• 类型：Boolean
  • true：Claude Code 在会话进入 bypassPermissions 模式之前跳过确认对话框
  • false：与未设置相同；除非这些文件中的另一个设置了 true，否则对话框会出现
• 默认值：未设置，因此对话框会出现

{
  "skipDangerousModePermissionPrompt": true
}

沙箱设置

sandbox

• 作用域：Any file
• 类型：包含 enabled、failIfUnavailable、autoAllowBashIfSandboxed、excludedCommands、allowUnsandboxedCommands、enableWeakerNestedSandbox、enableWeakerNetworkIsolation、allowAppleEvents、allowNestedUserNamespaces、bwrapPath、socatPath、ignoreViolations 和 ripgrep 的对象，外加 filesystem、network 和 credentials 对象
• 默认值：未设置，因此 Claude Code 在没有沙箱的情况下运行命令

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker *"],
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"],
      "denyRead": ["~/.aws/credentials"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

sandbox.enabled

• 作用域：Any file，对项目设置和本地设置有限制
• 类型：布尔值
  • true：Claude Code 对 Bash 命令进行沙箱隔离
  • false：Bash 命令在沙箱外运行
• 默认值：false

{
  "sandbox": {
    "enabled": true
  }
}

sandbox.failIfUnavailable

• 作用域：Any file，对项目设置和本地设置有限制
• 类型：布尔值
  • true：当 sandbox.enabled 为 true 但沙箱无法启动时，Claude Code 在启动时报错退出。如果沙箱通过了该检查但随后初始化失败，会话将继续运行，而 Claude Code 会拒绝每个沙箱命令
  • false：当沙箱无法启动时，Claude Code 在沙箱外运行命令
• 默认值：false

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true
  }
}

sandbox.autoAllowBashIfSandboxed

• 作用域：Any file
• 类型：布尔值
  • true：Claude Code 在没有权限提示的情况下运行沙箱化的 Bash 命令，自动允许模式中描述的情况除外；CLAUDE_CODE_SUBPROCESS_ENV_SCRUB 会关闭自动允许
  • false：沙箱化命令走常规权限流程，由您的允许规则和权限模式决定。/sandbox 的 Mode 选项卡将此称为常规权限模式
• 默认值：true

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": false
  }
}

sandbox.excludedCommands

• 作用域：Any file，对项目设置和本地设置有限制
• 类型：命令模式数组
• 默认值：未设置，因此不排除任何命令

{
  "sandbox": {
    "excludedCommands": ["docker *"]
  }
}

• 以 sudo、eval 或 xargs 开头的命令
• cd、pushd 或 popd，无论出现在调用中的哪个位置
• 命令替换、子 shell，或 if、for 等控制流块
• 重定向，例如 docker build . > build.log 或 <<EOF heredoc，仅复制文件描述符的重定向（如 2>&1）除外
• 命令名来自变量
• 带有绝对路径、以 ~ 开头或包含 .. 段的路径参数的 git clone、git init、git worktree add、git worktree move 或 git bundle create

sandbox.allowUnsandboxedCommands

• 作用域：Any file，对项目设置和本地设置有一项限制
• 类型：布尔值
  • true：沙箱阻止某条命令后，Claude 可以使用 dangerouslyDisableSandbox 参数在沙箱外重试该命令
  • false：Claude Code 忽略该参数，因此在沙箱运行期间，Claude 运行的命令都会被沙箱化，除非它们匹配 excludedCommands 条目
• 默认值：true

{
  "sandbox": {
    "enabled": true,
    "allowUnsandboxedCommands": false
  }
}

sandbox.filesystem

• 作用域：Any file
• 类型：包含 allowWrite、denyWrite、denyRead 和 allowRead 数组，以及 allowManagedReadPathsOnly 和 disabled 布尔值的对象
• 默认值：未设置，因此适用默认的读写边界

{
  "sandbox": {
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"],
      "denyRead": ["~/.aws/credentials"]
    }
  }
}

沙箱路径前缀

通配符在沙箱路径中的适用位置

~/keys/*.pem              the entry
/home/alice/keys/*.pem    its full path
 ^^^^                     the first directory name, home

包含方括号、花括号或圆括号的目录名

app/
└── [slug]/
    └── page.tsx

• 方括号，例如 [slug]：在 macOS 的所有列表中，以及 Linux 和 WSL2 的 denyRead 和 allowRead 中，./app/[slug] 中的方括号同时也是一个模式。该条目还会匹配 app 下以 slug 中某一个字符命名的任何路径，例如 app/s 或 app/g。如果该条目位于 allowRead 中，或在 macOS 上位于 allowWrite 中，沙箱化命令也可以访问这些路径。请重命名任何不应被它们访问的路径。
• 方括号，例如 [user-id] 或 [post-id]，其中连字符左侧字符的排序位于右侧字符之后：在所有平台的所有列表中，./app/[user-id] 只覆盖恰好具有该名称的目录。在 v2.1.304 之前，当 denyRead 或 allowRead 包含此类条目时，Linux 和 WSL2 上的沙箱化命令无法启动。
• 花括号和圆括号：它们是普通字符，因此 ~/data/{keys,tokens} 覆盖的是一个名为 {keys,tokens} 的目录，而不是两个备选项。要覆盖 ~/data/keys 和 ~/data/tokens，请将它们分别添加为单独的条目。

sandbox.filesystem.allowWrite

• 作用域：Any file，对项目设置和本地设置有限制
• 类型：路径字符串数组，使用沙箱路径前缀
• 默认值：未设置，因此沙箱化命令可以写入工作目录、每用户临时目录、您通过 --add-dir 或 /add-dir 添加的目录，以及 permissions.additionalDirectories 中的目录

{
  "sandbox": {
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"]
    }
  }
}

sandbox.filesystem.denyWrite

• 作用域：Any file
• 类型：路径字符串数组，使用沙箱路径前缀
• 默认值：未设置

{
  "sandbox": {
    "filesystem": {
      "denyWrite": ["/etc", "/usr/local/bin"]
    }
  }
}

sandbox.filesystem.denyRead

• 作用域：Any file
• 类型：路径字符串数组，使用沙箱路径前缀
• 默认值：未设置，因此沙箱化命令保留默认读取权限，其中包括 ~/.aws/credentials 等凭据文件

{
  "sandbox": {
    "filesystem": {
      "denyRead": ["~/.aws/credentials"]
    }
  }
}

sandbox.filesystem.allowRead

• 作用域：Any file，对项目设置和本地设置有限制
• 类型：路径字符串数组，使用沙箱路径前缀
• 默认值：未设置

{
  "sandbox": {
    "filesystem": {
      "denyRead": ["~/"],
      "allowRead": ["."]
    }
  }
}

sandbox.filesystem.allowManagedReadPathsOnly

• 作用域：Managed
• 类型：布尔值
  • true：Claude Code 仅遵循来自托管设置的 allowRead 条目
  • false：来自其他设置文件的 allowRead 条目可以合并进来
• 默认值：false

{
  "sandbox": {
    "filesystem": {
      "denyRead": ["~/"],
      "allowRead": ["~/work"],
      "allowManagedReadPathsOnly": true
    }
  }
}

sandbox.filesystem.disabled

• 作用域：User or managed。当托管设置配置了任何 sandbox.filesystem 内容，或列出了带有 "mode": "deny" 的 sandbox.credentials.files 条目时，只有托管设置可以设置它。
• 类型：布尔值
  • true：Claude Code 跳过文件系统隔离并保留网络隔离
  • false：文件系统隔离保持启用
• 默认值：false，因此文件系统隔离保持启用

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "disabled": true
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

sandbox.ignoreViolations

• 作用域：Any file，对项目设置和本地设置有限制
• 类型：将命令子字符串映射到违规子字符串（通常是路径）数组的对象
• 默认值：未设置，因此报告所有违规

{
  "sandbox": {
    "ignoreViolations": {
      "*": ["/etc/hosts"]
    }
  }
}

sandbox.enableWeakerNestedSandbox

• 作用域：Any file，对项目设置和本地设置有限制
• 类型：布尔值
  • true：内部沙箱绑定挂载容器现有的 /proc，而不是挂载新的
  • false：沙箱挂载新的 /proc，这在非特权 Docker 容器中无法工作
• 默认值：false

{
  "sandbox": {
    "enabled": true,
    "enableWeakerNestedSandbox": true
  }
}

sandbox.enableWeakerNetworkIsolation

• 作用域：Any file，对项目设置和本地设置有限制
• 类型：布尔值
  • true：macOS 上的沙箱化命令可以访问 com.apple.trustd.agent
  • false：macOS 上的沙箱化命令无法访问系统 TLS 信任服务
• 默认值：false

{
  "sandbox": {
    "enabled": true,
    "enableWeakerNetworkIsolation": true
  }
}

sandbox.allowAppleEvents

• 作用域：User or managed
• 类型：布尔值
  • true：macOS 上的沙箱化命令可以发送 Apple Events
  • false：macOS 上的沙箱化命令无法发送 Apple Events，因此 open 和 osascript 会以错误 -600 失败
• 默认值：false

{
  "sandbox": {
    "enabled": true,
    "allowAppleEvents": true
  }
}

sandbox.allowNestedUserNamespaces

• 作用域：User or managed。来自 ~/.claude/settings.json、通过 --settings 传入的 JSON 或托管设置的 true 有效。Claude Code 会忽略项目 .claude/settings.json 或 .claude/settings.local.json 中的 true。在 CLAUDE_CODE_SUBPROCESS_ENV_SCRUB 设置为 1 的会话中，Claude Code 会忽略来自所有来源的 true。来自任何文件的 false 都有效，按设置优先级处理。
• 类型：布尔值
  • true：沙箱化命令可以创建用户命名空间
  • false：此键不额外允许任何内容，适用沙箱的默认行为
• 默认值：false

{
  "sandbox": {
    "enabled": true,
    "allowNestedUserNamespaces": true
  }
}

sandbox.ripgrep

• 作用域：User or managed
• 类型：包含 command（ripgrep 二进制文件的路径）和可选 args（要前置的参数数组）的对象
• 默认值：未设置，因此沙箱使用与 Claude Code 相同的 ripgrep 二进制文件。除非您将 USE_BUILTIN_RIPGREP 设置为 0，否则使用的是内置二进制文件

{
  "sandbox": {
    "ripgrep": {
      "command": "/usr/local/bin/rg"
    }
  }
}

sandbox.bwrapPath

• 作用域：Managed。Claude Code 仅从托管设置中读取它，以防用户、项目或本地文件将沙箱指向其他二进制文件。
• 类型：字符串，一个绝对路径；Claude Code 会丢弃相对路径并回退到 PATH 查找
• 默认值：未设置，因此 Claude Code 在 PATH 上查找 bwrap

{
  "sandbox": {
    "enabled": true,
    "bwrapPath": "/opt/admin/bwrap"
  }
}

sandbox.socatPath

• 作用域：Managed
• 类型：字符串，一个绝对路径；Claude Code 会丢弃相对路径并回退到 PATH 查找
• 默认值：未设置，因此 Claude Code 在 PATH 上查找 socat

{
  "sandbox": {
    "enabled": true,
    "socatPath": "/opt/admin/socat"
  }
}

sandbox.credentials

• 作用域：Any file。Claude Code 仅从用户设置、托管设置和 --settings 标志中遵循 mask 条目、allowPlaintextInject、awsPairs 和 sigv4。
• 类型：包含 files、envVars、allowPlaintextInject、awsPairs 和 sigv4 的对象
• 默认值：未设置，因此不保护任何凭据

{
  "sandbox": {
    "credentials": {
      "files": [{ "path": "~/.aws/credentials", "mode": "deny" }],
      "envVars": [{ "name": "GITHUB_TOKEN", "mode": "deny" }]
    }
  }
}

托管设置中的无效凭据条目

• files 或 envVars 中仍具有有效 path 或 name 以及 mask 或 deny 的 mode 的条目（例如其 extract 模式没有捕获组的条目）会被降级为 mode: "deny" 并附带警告，因此在您修复该条目之前，凭据保持被阻止而不是被掩码。降级后的 files 条目会像显式 deny 条目一样锁定 filesystem.disabled，并且警告会注明：如果托管设置关闭了文件系统隔离，则其读取阻止不会被强制执行。
• 具有未知 mode 或无效 path、name 的条目会被移除。
• 每种情况都会发出警告；无论条目被降级还是移除，其余有效条目仍会被强制执行。

sandbox.credentials.files

• 作用域：Any file。Claude Code 会丢弃来自项目 .claude/settings.json 和本地 .claude/settings.local.json 的 mask 条目。
• 类型：对象数组，每个对象包含 path 和值为 "deny" 或 "mask" 的 mode，外加可选的文件掩码字段
• 默认值：未设置，因此不保护任何凭据文件

{
  "sandbox": {
    "credentials": {
      "files": [
        { "path": "~/.aws/credentials", "mode": "deny" },
        { "path": "~/.config/gh/hosts.yml", "mode": "mask", "injectHosts": ["api.github.com"] }
      ]
    }
  }
}

文件掩码字段

{
  "sandbox": {
    "credentials": {
      "files": [
        {
          "path": "~/.config/gh/hosts.yml",
          "mode": "mask",
          "extract": "oauth_token:\\s*(\\S+)",
          "maskDuplicates": true,
          "onExtractNoMatch": "deny",
          "injectHosts": ["api.github.com"]
        }
      ]
    }
  }
}

sandbox.credentials.envVars

• 作用域：Any file。Claude Code 会丢弃来自项目 .claude/settings.json 和本地 .claude/settings.local.json 的 mask 条目。
• 类型：对象数组，每个对象包含 name 和值为 "deny" 或 "mask" 的 mode，外加可选的环境变量掩码字段
• 默认值：未设置，因此不保护任何环境变量

{
  "sandbox": {
    "credentials": {
      "envVars": [
        { "name": "NPM_TOKEN", "mode": "deny" },
        { "name": "GITHUB_TOKEN", "mode": "mask", "injectHosts": ["api.github.com"] }
      ]
    }
  }
}

环境变量掩码字段

{
  "sandbox": {
    "credentials": {
      "envVars": [
        {
          "name": "DATABASE_URL",
          "mode": "mask",
          "extract": "://[^:]+:([^@]+)@",
          "onExtractNoMatch": "deny"
        },
        {
          "name": "SERVICE_JWT",
          "mode": "mask",
          "decode": "jwt",
          "maskClaims": ["api_key"]
        }
      ]
    }
  }
}