所有设置

Claude Code 每个 settings.json 键的完整参考：每个键的放置位置、类型和默认值，以及可直接粘贴的示例，并附有所有键的索引。

返回索引

本参考页面列出了 Claude Code 从设置文件中读取的每个键，以及它改为保存在 ~/.claude.json 中的一小组键。如需选择文件或查看优先级，请从设置文件和优先级开始。

设置索引

下面的每个键都链接到其对应条目。作用域列出了该键可以写入的文件：用户 指 ~/.claude/settings.json，项目 指 .claude/settings.json，本地 指 .claude/settings.local.json，托管 指您的组织部署的内容。任意文件 表示以上全部四种，全局配置 表示 ~/.claude.json。

模型与回复

选择 Claude Code 使用哪些模型以及如何回复。有关这些设置如何与 /model 命令和环境变量交互，请参阅模型配置。

advisorModel

选择 Claude 调用服务器端 advisor 工具时由哪个模型来回答。取消设置即可关闭 advisor。advisor 的能力必须至少与主模型相当。有关可接受的模型组合以及选择不被接受的模型时会发生什么，请参阅选择 advisor 模型。

通常无需手动编辑此键。运行 /advisor 会打开一个选择器，其中显示当前选择、可以担任 advisor 的模型以及 No advisor。Claude Code 会将您的选择保存到 ~/.claude/settings.json 中的此键。如果您从 Remote Control 客户端或在连接到远程 worker 的会话中进行选择，该选择仅适用于该会话，不会更改此键。

如果您的账户需要使用额度同意，请先运行 /model fable 接受。在接受之前，在 /advisor 中选择 Fable 不会保存任何内容，Claude Code 会提示您先运行 /model fable。

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

{
  "advisorModel": "opus"
}

在 advisor 不可用的提供商上（例如 Amazon Bedrock），此键不起作用。在 Claude Platform on AWS 上，此键需要 Claude Code v2.1.300 或更高版本。"fable" 需要 Fable 访问权限。

alwaysThinkingEnabled

将此项设置为 false 可在所有会话中关闭扩展思考。思考默认处于开启状态，因此 true 不会改变任何内容。大多数人通过 /config 设置此项，而不是编辑文件。

在始终进行思考的模型上（例如 Opus 5.5、Sonnet 5.5、Haiku 5.5 和 Fable 模型），false 不起作用。在第三方提供商上，Claude Code 会省略 thinking 参数而不是关闭思考，因此自适应推理模型可能仍会思考。在 Anthropic API 上关闭思考时，对于已知不接受该组合的模型（例如 Opus 5），Claude Code 会发送 effort high 而不是更高的级别。

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

{
  "alwaysThinkingEnabled": false
}

availableModels

限制用户可以为主会话、子代理、skill 和 advisor 选择哪些模型。托管列表会约束 /model、--model 以及开发者自己文件中的 model 键；列表之外的模型无法被选择。在默认的前缀匹配下，此项本身不会影响 Default 选项；如需影响，请将其与 enforceAvailableModels 配合使用。

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

此示例只允许用户选择 Sonnet 和 Haiku 模型：

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

诸如 "claude-opus-5" 之类的模型 ID 条目也会允许在其基础上扩展的后续版本，例如 Opus 5.5。要阻止其中某个版本，请使用 deniedModels。要让每个模型 ID 条目只允许其指定的版本，请使用 availableModelsMatch。请参阅限制模型选择。有关第三方提供商 ID，请参阅为第三方部署固定模型。

availableModelsMatch

选择 availableModels 条目如何匹配模型 ID。默认情况下，模型 ID 条目也会允许在其基础上扩展的后续版本，因此 "claude-opus-5" 会允许 Opus 5.5。使用 "exact" 时，每个模型 ID 条目只允许其指定的版本，因此该模型的较新版本在您将其列出之前会一直被阻止。需要 Claude Code v2.1.283 或更高版本。

• 作用域：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"

此示例允许 Opus 5 和 Sonnet 5，但不允许两者的任何后续版本：

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

使用 "exact" 时，只要列表中至少指定了一个模型或系列，Default 选项也会被限制为列出的模型。请参阅阻止特定模型或版本。

deniedModels

阻止特定模型，无论是否配合 availableModels 允许列表使用，即使该列表允许这些模型也同样生效。Claude Code 会在 /model 选择器中隐藏被阻止的模型，并且在强制执行 availableModels 的任何地方都无法选择该模型。使用 Default 选项的会话也不会运行被阻止的模型，详见阻止特定模型或版本。需要 Claude Code v2.1.283 或更高版本。

• 作用域：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 条目会被忽略
• 默认值：未设置，因此不阻止任何模型

此示例允许 Opus 和 Sonnet 模型，并阻止 Opus 5.5：

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

请参阅阻止特定模型或版本。

effortLevel

为尚未保存级别的模型设置默认 effort 级别。较低的级别在简单任务上更快、更便宜，较高的级别则在复杂问题上进行更深入的推理。

当您在本机的交互式会话中运行 /effort low、medium、high 或 xhigh 时，Claude Code 会将该级别保存到 modelSettings 下当前模型的条目中，而不是写入此键。在 v2.1.251 之前，/effort 会写入此键。

在同一个设置文件中，Claude Code 使用模型已保存的级别，而不是此键。跨文件的优先级请参阅 modelSettings。

在连接到远程 worker 的会话中、在 -p 运行中以及在 Agent SDK 中，/effort 仅适用于该会话。调整 effort 级别列出了同样仅适用于该会话的交互式选择。/effort 输出的消息会说明实际发生了哪种情况。

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

{
  "effortLevel": "xhigh"
}

在您的用户设置文件 ~/.claude/settings.json 中，此键是 /effort 在按模型保存级别之前所写入的旧形式，它会继续在之前适用的地方生效，即 Opus 5、Fable 5.1 及更早的模型。Opus 5.5 及之后发布的模型会忽略它，并以各自的默认级别启动，直到您为它们保存级别为止，/effort 会将该级别写入 modelSettings。在项目、本地和托管设置中，以及使用 --settings 时，此键适用于所有模型。

enforceAvailableModels

/model 选择器有一个 Default 选项，default 模型设置描述了它解析到的模型。availableModels 允许列表会限制您可以指定的模型，但在默认的前缀匹配下，它不会重新映射您账户类型的默认模型，因此 Default 仍可能解析到列表之外的模型。此键弥补了这一漏洞。需要 Claude Code v2.1.175 或更高版本。

当您的组织部署了任何托管设置时，Claude Code 只从托管来源读取此键，并忽略您其他文件中的此键。

有关此键如何应用于启动时的模型检查，请参阅 Amazon Bedrock 和 Google Cloud 的 Agent Platform。

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

此示例将指定选择限制为 Sonnet 和 Haiku 模型，并使 Default 解析为其中第一个可用的模型：

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

当 availableModels 未设置或为空时，此键不起作用。请参阅为 Default 模型强制执行允许列表。需要 Claude Code v2.1.175 或更高版本。

fallbackModel

指定当主模型过载或不可用时 Claude Code 按顺序尝试的备用模型。Claude Code 会在当前轮次的剩余部分切换到链中下一个可用的模型，并显示通知。如果没有配置链，Claude Code 会重试同一模型，然后显示服务器的错误，由您自行重试或切换模型。

一次切换意味着备用模型上会有一个轮次的提示缓存是冷的；您的下一条消息会再次先尝试主模型。

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

此示例在主模型失败时先尝试 Sonnet 5，然后尝试 Haiku 4.5：

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

与大多数数组设置不同，此键不会跨设置文件合并：定义了它的最高优先级文件会提供整个链。如果您的项目文件设置为 ["claude-sonnet-5"]，而用户文件设置为 ["claude-haiku-4-5"]，则链只有 ["claude-sonnet-5"]。Claude Code 最多保留列表中三个不同的允许模型，其余的会被忽略。请参阅备用模型链。

fastMode

在可用的会话中开启快速模式，适用于快速迭代或实时调试等需要以更高的每 token 成本换取速度的交互式工作。通常无需手动编辑此键。运行 /fast 会将 fastMode: true 写入 ~/.claude/settings.json，再次运行以关闭快速模式则会移除该键。

在 Anthropic API 上，只有 Fable 5.2、Opus 5.5、Opus 5 和 Opus 4.8 支持快速模式。在其他模型上运行 /fast 会将您切换到 Opus，而切换到不受支持的模型则会关闭快速模式。请参阅在快速模式开启时切换模型。在 Google Cloud 的 Agent Platform 上，/fast 则会将您切换到 Fable 5.2，且不会写入此键，Claude Code 也会忽略已保存的 true。

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

{
  "fastMode": true
}

fastModePerSessionOptIn

通常，运行 /fast 会将 fastMode 保存到个人的用户设置中，因此在受支持模型上的新会话开始时快速模式都会开启。在 Fable 5.2 上，只有当用户在使用 Fable 5.2 时开启了快速模式，才会如此。要让每个人在每个想要使用快速模式的会话中运行 /fast，请将此键设置为 true。Claude Code 会保留其文件中的 fastMode，因此关闭此键即可恢复原来的行为。

Team 或 Enterprise 计划的所有者可以通过服务器托管设置在整个组织中部署此项。当托管设置设置了此键时，/fast on 在交互式终端会话之外会被拒绝，并报告您的组织已禁用快速模式。这涵盖非交互模式、VS Code 扩展和云端会话。

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

{
  "fastModePerSessionOptIn": true
}

请参阅要求按会话选择启用。

language

让 Claude 默认使用英语以外的语言回复。回复语言没有固定列表：Claude Code 会将该值原样传递给 Claude，作为始终使用该语言回复的指令，因此 Claude 能识别的任何语言名称都可以使用。Claude Code 不会检查该值，因此拼写错误的名称会按原样传递给 Claude，而不会产生错误。同一个值还会设置语音听写的语言（语音听写确实有固定的支持的听写语言列表），以及自动生成的会话标题的语言。

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

{
  "language": "japanese"
}

maxEffortLevel

为会话可以使用的 effort 级别设置上限，较低的级别仍然可用。任何更高的级别都会改为以上限运行，包括来自 /effort、/model 选择器、--effort、CLAUDE_CODE_EFFORT_LEVEL、skill 或子代理的 effort frontmatter 或模型自身默认值的级别。Claude Code 会在每个请求之前自行应用该上限，因此它在所有提供商上都有效，包括 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry。需要 Claude Code v2.1.267 或更高版本。

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

此示例将所有模型的上限设为 medium，并使 Sonnet 4.6 不受限制：

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

当您的组织还为某个模型设置了 effort 限制时，以两个上限中较低的为准。

model

设置每个新会话使用的模型，这样您就不必每次都通过 /model 选择。在此处设置并不妨碍您在会话中途切换。如果您的管理员设置了覆盖用户选择的组织默认模型，即使您在用户、项目或本地设置中设置了此键，您也会使用该模型。

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

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

此处的值优先于 ANTHROPIC_DEFAULT_MODEL，后者仅在没有其他方式选择模型时才会被 Claude Code 使用。

modelOverrides

将 Anthropic 模型 ID 映射到提供商特定的模型 ID，例如 Amazon Bedrock 推理配置文件 ARN。之后，每个模型选择器条目在调用提供商 API 时都会使用其映射的值。管理员在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上使用此项，将每个模型版本路由到特定的推理配置文件、版本名称或部署，以便进行治理、成本分摊或区域路由。

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

此示例将 Opus 4.6 的所有调用路由到指定的 Bedrock 推理配置文件：

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

请参阅按版本覆盖模型 ID。

modelPicker

按您编写的顺序、使用您选择的标签列出 /model 选择器提供的模型，使选择器在内置模型列表之后或代替内置列表显示您组织所运行的模型。每一行的 model 都按原样使用，因此它接受 --model 所接受的任何内容：诸如 opus 之类的别名、Anthropic 模型 ID，或适用于 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 LLM 网关的提供商格式 ID。需要 Claude Code v2.1.242 或更高版本。

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

此示例在内置模型列表之后添加两个 Bedrock 部署，并使用您的团队熟悉的名称：

{
  "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 的字段

此键接受两个字段，一个用于行本身，另一个用于指定这些行是替代内置模型列表还是添加到其中。

options 中的条目还可以在其 model 旁边带有一个可选的 behavesAs 字符串，这需要 v2.1.257 或更高版本。当条目的 model 比您的 Claude Code 版本更新时，将其设置为您的版本已知的模型 ID，例如 claude-opus-4-8。Claude Code 随后会将该已知模型的能力和 effort 默认值应用于该条目，而不是将其模型视为未知模型。条目的标签以及 Claude Code 在请求中发送的模型 ID 不会改变。

开启 replaceBuiltInOptions 时，Claude Code 会隐藏所有其他行：内置模型列表、为 availableModels 条目添加的行、网关发现找到的模型，以及 ANTHROPIC_CUSTOM_MODEL_OPTION。关闭时，Claude Code 会跳过内置模型列表已涵盖的列出模型。标签改变的是选择器显示的内容，而不是 Claude Code 运行的模型。

availableModels 允许列表仍然适用于这些行。在将列出的模型添加到允许列表之前，请阅读合并行为：特定的模型 ID 会缩小其系列通配符条目的范围。Claude Code 还会在显示选择器之前根据会话检查每一行：

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

Claude Code 会丢弃无法解析的行并保留其余行。请参阅修复损坏的设置文件。

modelPricing

按照您组织实际支付的费率而不是标价报告支出。当您的组织有合同费率时设置此项，使开发者看到的金额与您的账单一致。Claude Code 会在 /usage、状态栏、Agent SDK 的 total_cost_usd、--max-budget-usd 限制以及 OpenTelemetry 成本指标和事件中应用这些费率。费率由您提供：Claude Code 不会从您的合同或 Claude Console 中读取它们。需要 Claude Code v2.1.242 或更高版本。

• 作用域：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 按标价报告

单独设置 multiplier 可实现统一折扣或加价，单独设置 overrides 可实现按模型的费率，也可以两者都设置。

此示例为 Sonnet 4.6 设置合同费率，然后将所有金额（包括 Sonnet 这一行）降低 15%：

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

将 multiplier 设置为大于 1（最高 10）可对所有金额加价。加价需要 Claude Code v2.1.271 或更高版本。较早的版本会忽略大于 1 的 multiplier 并给出警告，同时保留该设置的其余部分。

有关具体步骤，包括如何确认费率已生效，请参阅按合同费率报告支出。

modelPricing 的字段

Claude Code 完全按照您编写的费率使用某一行，不会加上快速模式附加费或仅限美国推理的费率。如果您还设置了 multiplier，Claude Code 会在该行费率的基础上应用它。Claude Code 会丢弃包含无法解析的费率的行，或无法解析的 multiplier，并保留其余部分；请参阅修复损坏的设置文件。

modelPricing 行适用于哪些模型

Claude Code 根据行的键来决定该行适用于哪些模型：

• 内置模型的 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

为您使用的每个模型保存 effort 级别。需要 Claude Code v2.1.251 或更高版本。

在本机的交互式会话中，当您通过 /effort 或 /model 选择器的 effort 滑块将 low、medium、high 或 xhigh 保存为默认值时，Claude Code 会将该级别写入此处您正在使用的模型下，因此您很少需要自己编辑此键。当您在 VS Code 扩展的模型选择器中选择这些级别之一时，Claude Code 也会以同样的方式将其保存在此处。effortLevel 条目列出了 /effort 仅适用于该会话的会话类型。

手动编辑此键可以更改或删除您已保存的级别。

此处某个模型的 effortLevel 优先于同一设置文件中的顶层 effortLevel。跨文件时，Claude Code 会分别解析每个模型：为该模型设置了 effortLevel，或设置了适用于该模型的顶层 effortLevel 的最高优先级设置文件起决定作用，因此托管设置中的 effortLevel 优先于您在用户设置中保存的级别。调整 effort 级别列出了还有哪些方式可以覆盖已保存的级别，例如启动时的 --effort。

要为某个模型的 effort 设置上限而不是设置其级别，请在该模型的条目中添加 maxEffortLevel 字段。该字段需要 Claude Code v2.1.267 或更高版本。

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

Claude Code 会将每个条目写在模型的规范名称下（例如 claude-opus-5-5），并将该模型的别名、带日期后缀的 ID、[1m] ID 以及可识别的提供商特定 ID 匹配到同一个条目。

此示例将 Opus 5.5 保持在 high，而其他模型使用各自已保存的级别或默认级别：

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

运行 /effort auto 可清除您为当前使用的模型保存的级别。Claude Code 会保留其他条目以及任何顶层 effortLevel。

outputStyle

按名称选择输出样式。输出样式是一组已保存的指令，用于改变 Claude 的角色、语气和输出格式，例如内置的 Explanatory 和 Learning 样式，或您自己编写的样式。

如果您在会话期间更改此键，Claude 会从您的下一条消息开始使用新样式。有关该消息在提示缓存方面的成本，请参阅更改输出样式。在 v2.1.251 之前，该修改只有在您运行 /clear 或开始新会话后才会生效。

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

此示例选择内置的 Explanatory 样式，它会在任务之间添加教育性的见解：

{
  "outputStyle": "Explanatory"
}

promptCacheTtl

选择提示缓存保留主对话的时长。此键适用于您的交互式、-p 和 Agent SDK 轮次，以及 Claude Code 随这些轮次内联运行的辅助请求。一小时的生命周期可以在较长的间隔期间保持缓存处于热状态，但 API 对每次缓存写入的计费费率高于五分钟生命周期。需要 Claude Code v2.1.242 或更高版本。

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

此示例让主对话使用一小时生命周期，而子代理保持五分钟：

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

有关每种生命周期的成本，请参阅缓存生命周期。

showThinkingSummaries

在交互式会话中查看 Claude 扩展思考的摘要。如果您希望在使用 Ctrl+O 展开思考时看到完整的摘要，请设置此项。未设置或为 false 时，Anthropic API 会对思考块进行编辑隐藏，Claude Code 会显示一个折叠的占位内容。

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

{
  "showThinkingSummaries": true
}

编辑隐藏只会改变您看到的内容，不会改变模型生成的内容。要减少思考消耗，请改为降低预算或禁用思考。

subagentPromptCacheTtl

选择提示缓存保留 Claude Code 在主对话之外发出的请求的时长。此键适用于子代理、工作流以及 Claude Code 自身的后台和辅助请求，例如压缩和会话标题。一小时的生命周期可以在较长的间隔期间保持缓存处于热状态，但 API 对每次缓存写入的计费费率高于五分钟生命周期。需要 Claude Code v2.1.242 或更高版本。

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

此示例为子代理以及主对话之外的其他请求设置一小时生命周期：

{
  "subagentPromptCacheTtl": "1h"
}

此键涵盖 promptCacheTtl 未涵盖的请求，因此同时设置两者即可为 Claude Code 发出的每个请求选择生命周期。有关子代理的缓存与主对话的缓存有何不同，请参阅子代理与缓存。

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

在开启 ultracode 的状态下启动会话。开启后，Claude 会为每个实质性任务规划工作流，而不是等待您提出要求。只有在为您启用了动态工作流且您的模型支持 xhigh effort 时，Claude 才会规划工作流。此键不会改变会话的 effort 级别：ultracode 以会话所使用的任何级别运行。Claude Code 会读取此键但从不写入它：/effort ultracode 仅为当前会话开启 ultracode。

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

{
  "ultracode": true
}

会话的 effort 级别来自 effortLevel、modelSettings 以及其他 effort 来源，而诸如 maxEffortLevel 之类的 effort 上限会降低该级别，但不会关闭 ultracode。此行为以及 /effort ultracode off 形式需要 Claude Code v2.1.284 或更高版本。在 v2.1.284 之前，ultracode: true 会以 xhigh effort 运行会话，而低于 xhigh 的 effort 上限会使 ultracode 保持关闭。Agent SDK 的 apply_flag_settings 控制请求也接受此键。

权限设置

决定 Claude 无需询问即可执行哪些操作、新会话的默认权限模式，以及自动模式的分类器允许哪些操作。有关规则语法和权限模型，请参阅配置权限。

allowManagedPermissionRulesOnly

使托管设置成为权限规则的唯一设置来源。此后 Claude Code 会忽略用户、项目、本地以及 --settings 文件中的 allow、ask 和 deny 规则，忽略 --allowedTools，在权限提示中隐藏"始终允许"选项，并停止保存新规则。

当来自嵌入宿主的父级设置生效时，Claude Code 会将其视为托管层级的一部分。它会丢弃这些设置中的 allow 规则和 additionalDirectories，并保留其 deny 和 ask 规则，但模式以 ! 开头的 Read 和 Edit 规则除外。无论您是否设置此键，宿主都无法通过 ! 规则从托管规则中划出例外路径。

--disallowedTools 规则以及当前会话的 deny 和 ask 规则仍然适用，包括 Claude Code 在会话中途重新加载设置之后。这些规则只起限制作用，因此无法扩大托管规则所授予的范围。在 v2.1.257 之前，Claude Code 会在第一次重新加载设置时丢弃这些命令行规则和会话规则。

有关 --disallowedTools 或会话规则中的 ! 模式可以划出哪些例外，请参阅 Read 和 Edit 规则。

设置此键后，Claude Code v2.1.282 或更高版本还会忽略以下来源中 skill 和 .claude/commands/ 文件里的 allowed-tools frontmatter：

• 仓库的 .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 或更高版本

来自托管设置的 skill 和随附 skill 会保留其 allowed-tools。这些 Desktop 会话之外的 @inline 插件也会保留其 allowed-tools，但名为 anthropic-skills 的插件除外。skill 的 disallowed-tools 仍然适用。有关 Claude Code 忽略该字段时开发者会看到什么，请参阅仅托管权限规则生效时。

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

{
  "allowManagedPermissionRulesOnly": true
}

此键不会锁定 MCP 服务器允许列表；如需锁定，请设置 allowManagedMcpServersOnly。请参阅仅限托管的设置。

autoMode

为自动模式分类器的阻止和允许范围添加您自己的规则。使用它告诉分类器您的组织信任哪些仓库、存储桶和域名，使其不再阻止日常的内部操作。分类器自带内置的允许和拒绝规则。在数组中包含字面字符串 "$defaults"，即可在该位置保留这些内置规则并在其前后添加您的规则；省略它则会用您的规则替换内置规则。

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

此示例通过 "$defaults" 保留内置的 soft_deny 规则，并额外添加一条阻止 terraform apply 的规则：

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

当这些文件中有多个设置了同一个数组时，Claude Code 会将各条目串联起来。有关规则格式以及每个数组的应用方式，请参阅配置自动模式。

autoMode.classifyAllShell

在自动模式处于活动状态时，将每条 Bash 和 PowerShell 命令都交由自动模式分类器处理。默认情况下，自动模式仅暂停可能运行任意代码的允许规则：针对整个工具的规则和通配符规则（例如 Bash(*)），以及解释器或 shell 包装器前缀（例如 Bash(python *)）。与任何其他允许规则匹配的命令（例如 Bash(npm test)）会跳过分类器，除非该命令带有按命令允许的域名。跳过时，规则前缀未预料到的破坏性参数可能会在未被检查的情况下通过。设置此键会在会话期间暂停所有 shell 允许规则，使分类器能检查每一条命令。需要 Claude Code v2.1.193 或更高版本。

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

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

请参阅将所有 shell 命令交由分类器处理。

disableAutoMode

从 Shift+Tab 循环中移除自动模式。任何原本会以自动模式启动的会话，无论是由于 --permission-mode auto、设置文件还是内置默认值，都会改为以 default 启动。管理员可在托管设置中设置此项，以阻止其组织中的开发者使用自动模式。

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

{
  "disableAutoMode": "disable"
}

permissions

控制 Claude 无需询问即可使用哪些工具、哪些工具需要提示、哪些工具被阻止。还可设置新会话的默认权限模式。下面的每个 permissions.* 键都嵌套在此对象下。

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

此示例无需询问即批准 npm run 命令，在 git push 之前进行提示，阻止读取 .env，并以 acceptEdits 启动会话：

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

这三个规则数组使用同一种语法；请参阅 permissions.allow 下的权限规则语法。有关来自不同文件的权限规则如何组合，请参阅权限规则如何跨作用域合并；有关一般设置键如何组合，请参阅设置指南中的设置优先级。

useAutoModeDuringPlan

选择 Claude Code 是否在计划模式下使用自动模式分类器审查 shell 命令。在默认值 true 下，当自动模式可用时，分类器会在规划期间审查每条命令，您不会看到提示，关键路径删除除外。设置为 false 后，对于内置只读命令集之外的每条命令，您都会收到权限提示。在 /config 中显示为 Use auto mode during plan。

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

{
  "useAutoModeDuringPlan": false
}

permissions.allow

列出 Claude Code 无需询问您即可批准的工具使用。在 MCP 规则中，* 只能出现在 mcp__<server>__ 前缀之后的工具名称中，例如 mcp__github__get_*；它不能出现在服务器名称中。

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

此示例批准 git diff，并允许 Claude Code 无需询问即可读取您的 .zshrc：

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

只有在您为该文件夹接受工作区信任对话框之后，Claude Code 才会应用项目 .claude/settings.json 中的 allow 规则。

权限规则语法

权限规则采用 Tool 或 Tool(specifier) 格式。Claude Code 先评估 deny 规则，然后是 ask，最后是 allow，第一个匹配项决定结果，而不论每条规则的具体程度如何；请参阅权限规则评估顺序。

每一行显示一种规则形式及其匹配的内容。

有关完整的规则语法，包括通配符行为、针对 Read、Edit、WebFetch、MCP 和 Agent 规则的工具特定模式，以及 Bash 模式的安全限制，请参阅权限规则语法。

permissions.ask

列出即使在原本会批准它们的权限模式（例如 acceptEdits 或 bypassPermissions）下，也会提示您确认的工具使用。在 dontAsk 模式下，Claude Code 会拒绝匹配的工具使用，而不是发出提示。

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

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

permissions.deny

列出 Claude Code 阻止的工具使用。将其用于存放 API 密钥、机密或环境值的文件：Claude Code 会从文件发现和搜索结果中排除匹配的文件，拒绝对其进行读取，并在匹配路径上阻止 Edit 和 Write 工具。

Read 和 Edit 拒绝规则适用于 Claude 的内置文件工具、Claude Code 在 Bash 中识别的文件命令（例如 cat、head、tail、sed 和 tee），以及 Bash 重定向（例如 > file 和 < file）的目标；它们不适用于不指明文件名即可读取文件的命令（例如 grep -r pattern .），也不适用于任意子进程，因此如需操作系统级别的强制执行，请启用沙箱。

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

此示例拒绝读取 .env 文件、secrets 目录和一个凭据文件，并阻止 curl 命令：

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

工具名称接受 glob 模式，因此 "*" 会拒绝所有工具，"mcp__*" 会拒绝所有 MCP 工具。只要 Claude 仍有任何其他工具可用，Claude Code 就会忽略针对 EndConversation 工具的拒绝规则。Bash 拒绝规则按照 Claude 编写的命令原样进行匹配，因此 Bash(curl *) 无法阻止 /usr/bin/curl 或 sh -c 'curl …'；请参阅 Bash 规则无法匹配的内容。此键取代了已弃用的 ignorePatterns 配置。

permissions.additionalDirectories

允许 Claude 访问您启动时所在目录之外的目录中的文件，将其作为额外的工作目录。大多数 .claude/ 配置不会从这些目录中被发现。

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

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

与 allow 规则一样，项目 .claude/settings.json 中的条目只有在您为该文件夹接受工作区信任对话框之后才会生效。

permissions.blockReadsOutsideWorkingDirectories

使 Claude 的文件工具在所有权限模式下（包括 bypassPermissions）拒绝读取工作目录之外的内容。Claude Code 会拒绝对这些路径的 Read、Grep、Glob 和 LSP 调用，并告知 Claude 请您使用 /add-dir 添加该目录。Claude Code 自身需要的文件仍可读取，例如 ~/.claude/ 下的 skill、插件、规则、Agent、命令以及 CLAUDE.md 记忆文件。需要 Claude Code v2.1.257 或更高版本。

Claude Code 不会以同样的方式拒绝 shell 命令：

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

shell 解析器无法追踪的 Bash 命令（例如多次切换目录或运行子 shell 的命令），即使在自动模式和 bypassPermissions 模式下也会向您发出提示。即使命令未指明工作目录之外的任何路径，也会出现该提示。当命令在沙箱中运行且沙箱强制执行该阻止时，此提示不适用。

当您在自动模式首次读取工作目录之外内容前的提示中选择阻止此类读取时，Claude Code 也会在此处写入 true。

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

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

要解除阻止，请从所有设置了此键的设置文件中删除该键，然后重启每个正在运行的会话。

您通过 --add-dir、/add-dir 或用户设置或托管设置中的 additionalDirectories 添加的目录，在该阻止中均视为工作目录。仅在仓库设置中添加的目录不计入：即 .claude/settings.json 中的目录，以及 .claude/settings.local.json 中的目录（除非 git 将该文件报告为未跟踪）。在不是 git 仓库的目录中，或当 git 跟踪该文件时，Claude Code 会将 .claude/settings.local.json 视为仓库设置，因此请将您希望保持可读的目录放在用户设置中。

当 autoMemoryDirectory 来自项目的 .claude/settings.json，或来自被视为由仓库提供的 .claude/settings.local.json 时，Claude Code 不会从该目录加载任何自动记忆，也不会向其中保存任何内容。

阻止状态下的沙箱命令

启用沙箱隔离时，该阻止也涵盖沙箱中的命令。Claude Code 会拒绝它们读取您的主目录以及存放用户文件的其他根目录：/Users、/home、/root、/Volumes、/mnt、/media、/run/media 和 /srv。然后它会重新开放工作目录、Claude Code 在会话中创建的 worktree、会话临时目录，以及命令所需的 ~/.claude 部分（例如 skill 和插件）。在阻止生效期间，来自仓库设置的 allowRead 和 allowWrite 条目不计入。

当会话的工作目录是一个链接的 git worktree（包括 Claude Code 在会话中途进入的 worktree）时，仓库的公共 .git 目录对沙箱中的命令保持可读可写，因此 git 可以在其中继续正常工作。

在以下情况下，该阻止不会作用于沙箱中的命令，但 Claude 的文件工具仍会强制执行：

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

在阻止状态下，Claude Code 会向沙箱中的命令重新开放您的全局 git 配置文件，使 git 保留您的身份和设置：

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

Claude Code 会分别判断每个文件。如果某个文件位于沙箱中的命令可以直接或通过符号链接写入的位置，Claude Code 不会重新开放该文件所指定的文件。

在 Linux 和 WSL2 上，作为符号链接的配置文件在其自身路径上可能仍不可读，此时 git 会在没有该文件的情况下运行。~/.git-credentials 和 $XDG_CONFIG_HOME/git/credentials 仍保持阻止状态。

如果重新开放的文件中包含机密（例如 http.extraHeader 令牌），请将其路径添加到 sandbox.filesystem.denyRead。覆盖某个文件的 denyRead 条目始终优先于此重新开放。

permissions.blockWritesOutsideWorkingDirectories

使 Write、Edit 和 NotebookEdit 工具在所有权限模式下（包括 bypassPermissions）拒绝工作目录之外的路径，但 Claude Code 自身的部分文件除外。此键不限制 shell 命令、MCP 工具或 hook 运行的程序。要限制 shell 命令的写入位置，请启用沙箱隔离。需要 Claude Code v2.1.314 或更高版本。

启用此键后，Claude Code 还会移除 EnterWorktree 和 ExitWorktree 工具，或拒绝对它们的调用。要继续在 worktree 中工作，请按照 Claude 没有 EnterWorktree 工具中的说明操作。

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

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

要测试该阻止，请让 Claude 使用 Write 工具在工作目录之外创建一个文件，例如 ~/block-test.txt（如果您的主目录不属于工作目录）。Claude Code 会拒绝该调用，拒绝信息会说明设置阻止了工作目录之外的写入。

要解除阻止，请从所有设置了此键的设置文件中删除该键，然后重启 Claude Code。

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

Claude Code 自身的部分文件仍可写入，例如计划文件、草稿区、后台会话的 tmp 目录，以及此项目自动记忆中的 .md 文件。

除工作目录之外您自己的文件外，该阻止还会拒绝写入：

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

无论您添加什么，设置文件始终会被拒绝。要在其他任一情况下放行写入，请添加工作目录。/add-dir 需要一个已存在的目录，因此对于子代理 worktree，请指定仓库根目录下的 .claude/worktrees 目录。

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

当 blockReadsOutsideWorkingDirectories 或 blockWritesOutsideWorkingDirectories 为 true 时，要让 Claude 访问项目之外的某个目录，请将其添加为工作目录。在会话中运行 /add-dir <directory>，在启动 Claude Code 时传入 --add-dir <directory>，或在用户设置或托管设置的 additionalDirectories 下列出该目录。任何允许规则都无法让 Claude 的文件工具通过这两种阻止中的任何一种。

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"
  }
}

权限规则叠加在每种模式之上：deny 规则在所有模式下都会阻止，包括 bypassPermissions。请参阅权限模式。在云端会话中，Claude Code 仅采用此键中的 acceptEdits、plan、default 和 auto。对于 VS Code 扩展启动的对话，请参阅扩展读取哪个设置作为起始权限模式。

permissions.denyInsteadOfPrompting

将此项设置为 true，可在无人回答权限提示时让会话继续运行。Claude Code 会拒绝原本需要等待提示的工具调用，轮次继续进行。需要 Claude Code v2.1.319 或更高版本。

如果允许规则、您的权限模式或自动模式的分类器批准了某个调用，该调用会继续执行。要允许大多数原本会发出提示的调用，请通过 PermissionRequest hook 进行应答。

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

在 ~/.claude/settings.json 中，此示例以自动模式启动会话，并拒绝所有仍会回退到提示的操作：

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

此键适用于 -p 运行、交互式终端会话、VS Code 扩展、Desktop 应用中的本地会话、子代理以及 agent team。如果只想在单次非交互式运行中拒绝会发出提示的操作，请改为将 --permission-prompts none 与 -p 一起传入。

denyInsteadOfPrompting 还会阻止什么

启用此设置后，Claude Code 还会停止以下需要应答的请求：

• 问题和计划工具：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 不会显示该通知，并会拒绝需要这些请求的操作

会话仍可能等待工作区信任对话框和项目 MCP 服务器批准。请在让会话无人值守地运行之前先应答这两项。

来自 denyInsteadOfPrompting 的消息

这些消息报告被拒绝的调用。它们不是提示，因此不会等待您的应答。

Claude 读取到的拒绝信息可能以以下文本开头：

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

在 stream-json 输出中，发出 permission_denied 消息的运行会报告以下 decision_reason：

no approval surface in this session; permission request denied automatically

在启用此设置的自动模式下，当连续 20 次调用被分类器阻止或被安全检查拒绝后，该轮次会结束，您会看到以下消息：

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

-p 运行会将该轮次报告为 error_during_execution。

permissions.disableBypassPermissionsMode

阻止任何人进入 bypassPermissions 模式。此后 Claude Code 会拒绝 --dangerously-skip-permissions 标志，并忽略 Agent 定义中的 permissionMode: bypassPermissions，因此子代理会以父会话的权限模式运行。

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

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

在 v2.1.223 之前，即使禁用了绕过模式，Claude Code 仍会应用 frontmatter 中的权限模式。

skipAutoPermissionPrompt

跳过描述自动模式的一次性通知。当您首次自行进入自动模式时（例如通过您自己的设置或模式选择器，而不是由内置默认值以该模式启动会话），Claude Code 会显示此通知。Claude Code 只显示一次该通知，之后会记录它已显示过，因此此键仅在通知尚未出现时才有意义。

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

{
  "skipAutoPermissionPrompt": true
}

skipDangerousModePermissionPrompt

跳过 Claude Code 在会话进入 bypassPermissions 模式之前显示的确认对话框，无论是由 --dangerously-skip-permissions 还是 defaultMode: "bypassPermissions" 触发。当您接受过一次该对话框后，Claude Code 会在您的用户设置中此处写入 true。

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

{
  "skipDangerousModePermissionPrompt": true
}

沙箱设置

将 Claude 运行的命令与您的文件系统、网络和凭据隔离。有关沙箱隔离的工作原理和平台要求，请参阅沙箱隔离。

sandbox

通过沙箱隔离将 Claude 运行的 Bash 命令与您的文件系统和网络隔离。使用 enabled 启用沙箱，然后通过 filesystem、network 和 credentials 子对象收窄或放宽沙箱化命令可以访问的范围。沙箱可在 macOS、Linux 和 WSL2 上运行。

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

以下配置启用沙箱，对沙箱化命令跳过权限提示，在沙箱外运行 docker，开放两个额外的写入路径，隐藏您的 AWS 凭据文件，并预先允许 GitHub 和 npm：

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

当托管设置设定了 enabled 或 failIfUnavailable 等布尔键时，该值会覆盖开发者设置的任何值。Claude Code 会在会话加载的各设置作用域之间合并数组键，因此开发者可以追加条目；有关仅限托管设置的锁定，请参阅防止开发者放宽策略。要为组织强制要求沙箱，请参阅使用托管设置强制沙箱隔离。

sandbox.enabled

为 Bash 命令启用沙箱隔离。当您在 /sandbox 面板中选择模式时，Claude Code 会将此键写入当前项目的 .claude/settings.local.json；在 ~/.claude/settings.json 中设置它可对所有项目启用沙箱。

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

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

在 Linux 和 WSL2 上，沙箱需要 bubblewrap 和 socat；请参阅设置 Linux 和 WSL2。当沙箱无法启动时，Claude Code 会在沙箱外运行命令，除非您还设置了 failIfUnavailable。

sandbox.failIfUnavailable

当 sandbox.enabled 为 true，但由于平台不支持或依赖检查失败而导致沙箱无法启动时，让 Claude Code 在启动时报错退出。如果没有此键，Claude Code 会在沙箱外运行命令。将沙箱隔离作为安全关卡的托管部署可以使用此设置。

在沙箱不支持的平台上，启用此键后 Claude Code 将无法启动。请参阅使用托管设置强制沙箱隔离。

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

以下配置为托管计算机启用沙箱，并将 failIfUnavailable 设置为 true：

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

请参阅使用托管设置强制沙箱隔离。

sandbox.autoAllowBashIfSandboxed

让 Claude Code 在没有权限提示的情况下运行沙箱化的 Bash 命令。无法在沙箱中运行的命令仍会走常规权限流程，deny 规则和限定内容的 ask 规则（例如 Bash(git push *)）仍然适用；单独的 Bash ask 规则对沙箱化命令会被跳过。将其设置为 false 可让沙箱化命令也走常规权限流程，/sandbox 的 Mode 选项卡将此称为常规权限模式。

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

以下配置保持沙箱启用，并让沙箱化命令走常规权限流程：

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

有关自动允许模式仍会提示的情况以及它在计划模式下的行为，请参阅自动允许模式。

sandbox.excludedCommands

指定 Claude Code 在沙箱外运行的命令，例如在沙箱下无法工作的工具。每个条目使用与 Bash(...) 权限规则内容相同的语法：精确命令、前缀（如 docker *）或通配符模式。不含通配符的模式为精确匹配，因此 docker 只匹配不带参数的 docker。

只有当您的条目覆盖某个 Bash 调用中的每条命令时，该调用才会被移出沙箱，而且即便如此，某些调用形式仍会保持沙箱化。仅有 docker * 条目并不会将 npm ci && docker build . 移出沙箱。

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

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

当 Bash 调用具有以下形式之一（但不限于这些）时，Claude Code 会使其保持沙箱化：

• 以 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

例如，在 docker * 条目下，cd build && docker compose up 仍保持沙箱化，添加 cd 条目也不会改变这一点。在 git * 条目下，git clone <url> vendor/lib 在沙箱外运行，但 git clone <url> ~/tools 保持沙箱化。克隆会在其目标路径指向的任何位置写入整个文件树，其中可能包含可执行文件。

被排除的命令仍会走常规权限流程。排除只是一种便利措施，而不是安全边界：当某个工具只需要写入特定位置时，filesystem.allowWrite 可以让它保持沙箱化。

来自会话加载的各设置作用域的条目会合并为一个列表，除非沙箱是管理员强制要求的。在这种情况下，Claude Code 会忽略 .claude/settings.json 和 .claude/settings.local.json 中的条目，因此克隆的仓库无法将命令移出沙箱。托管设置、--settings 和您的 ~/.claude/settings.json 中的条目仍然适用，并且没有仅限托管设置的锁定覆盖此列表。

sandbox.allowUnsandboxedCommands

允许 Claude 在沙箱阻止某条命令后，使用 dangerouslyDisableSandbox 参数在沙箱外重试该命令。当其为 false 时，Claude Code 会忽略该参数。此时在沙箱运行期间，Claude 运行的命令都会被沙箱化，除非它们匹配 excludedCommands 条目。/sandbox 的 Overrides 选项卡将该状态显示为 Strict sandbox mode。托管设置中的 false 会为其覆盖的开发者启用严格沙箱模式。

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

以下配置为托管设置覆盖的所有人强制启用严格沙箱模式：

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

来自托管设置或 --settings 的 false 还会使沙箱成为管理员强制要求的。用户设置中的 false 可以抵御项目中的 true，但不会使沙箱成为管理员强制要求的。抵御项目的值需要 Claude Code v2.1.285 或更高版本。

由谁批准沙箱外重试取决于您的权限模式和允许规则。请参阅沙箱外重试这一逃生通道。

要了解您自己在 ! shell 模式提示符中输入的命令何时会被沙箱化运行，请参阅严格沙箱模式。

sandbox.filesystem

控制沙箱化命令可以读取和写入哪些路径。默认情况下，它们可以写入工作目录、每用户临时目录，以及您通过 --add-dir、/add-dir 或 permissions.additionalDirectories 添加的目录，并可以读取文件系统的其余部分，包括凭据文件。使用四个路径列表来放宽或收窄这些范围，或使用 disabled 关闭文件系统层。有关默认边界，请参阅文件系统隔离。

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

以下配置允许沙箱化命令写入构建目录和您的 kubeconfig，并隐藏您的 AWS 凭据文件：

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

Claude Code 在操作系统沙箱边界强制执行这些列表，因此它们适用于沙箱化命令启动的每个子进程，例如 kubectl、terraform 或 npm。Claude Code 会将您的权限规则添加到相同的列表中：Edit 允许和拒绝规则添加到 allowWrite 和 denyWrite，Read 拒绝规则添加到 denyRead，WebFetch(domain:...) 允许和拒绝规则添加到 network 域名列表。

除非有锁定适用，否则 Claude Code 会在会话加载的各设置文件之间合并这些列表。allowManagedReadPathsOnly 将 allowRead 限制为来自托管设置的条目，allowManagedDomainsOnly 对允许的域名执行同样的限制。仓库锁定会排除来自仓库设置文件的条目。

配置沙箱隔离介绍了您通过 --setting-sources 排除的来源。当您在会话期间编辑列表时，Claude Code 会将更改应用于正在运行的会话。

沙箱路径前缀

allowWrite、denyWrite、denyRead、allowRead 和 credentials.files 中的路径按其前缀解析：

用于绝对路径的 //path 前缀也可以使用。如果您使用单斜杠 /path 并期望按项目相对路径解析，请改用 ./path。此语法与 Read 和 Edit 权限规则不同，后者使用 //path 表示绝对路径，使用 /path 表示项目相对路径：沙箱文件系统路径使用标准约定，因此 /tmp/build 是绝对路径。

Claude Code 会去除目录路径末尾的斜杠，因此 ~/.aws 和 ~/.aws/ 匹配同一目录。在 v2.1.224 之前，Claude Code 会将末尾斜杠原样传递给沙箱，对于带末尾斜杠写法的 denyRead 或 denyWrite 条目，Claude 仍可能读取或写入其下的路径。

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

通配符 *、? 和 ** 在 macOS 上适用于全部四个 sandbox.filesystem 路径列表，在 Linux 和 WSL2 上则适用的位置较少：

在 ~/keys/*.pem 中，通配符位于第一个目录名之后；对于主目录为 /home/alice 的情况，第一个目录名是 home：

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

在 Linux 和 WSL2 上，会话中 /sandbox 的 Config 选项卡会针对包含末尾 /** 以外通配符的 Edit 权限规则发出警告。这些通配符对沙箱化命令无效。请将该规则应覆盖的每个路径或包含这些路径的目录添加到 allowWrite（对于允许规则）或 denyWrite（对于拒绝规则）。

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

要允许或阻止名称中包含方括号的目录，请按原样写出名称，例如 ./app/[slug]。在该条目中，[slug] 是目录的真实名称，包括方括号：

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

该条目覆盖该目录下的所有内容，因此不要添加末尾的 /**。在 macOS 以及 Linux 和 WSL2 上，app/[slug] 目录必须在沙箱化命令启动时已存在。

• 方括号，例如 [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

在工作目录、每用户临时目录以及您通过 --add-dir、/add-dir 或 permissions.additionalDirectories 添加的目录之外，添加沙箱化命令可以写入的路径。当 kubectl 或构建工具等子进程需要在项目外写入时使用此设置。

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

以下配置允许构建写入 /tmp/build 下的内容，并允许 kubectl 更新您的 kubeconfig：

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

在 Linux 和 WSL2 上，针对尚不存在的路径的条目不会生效，因此请先创建该路径。

Claude Code 会在会话加载的各设置作用域之间合并 allowWrite 条目以及来自您的 Edit(...) 允许权限规则的路径，当 permissions.blockReadsOutsideWorkingDirectories 启用时，会排除来自仓库设置的条目。仓库锁定也可能排除仓库的条目。allowWrite 条目无法解除受保护路径的保护。

sandbox.filesystem.denyWrite

阻止沙箱化命令写入特定路径，包括原本可写目录内的路径。

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

以下配置阻止沙箱化命令更改系统配置或安装二进制文件：

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

Claude Code 会在会话加载的所有设置作用域之间合并条目，并添加来自您的 Edit(...) 拒绝权限规则的路径。

sandbox.filesystem.denyRead

阻止沙箱化命令读取特定路径，例如默认读取策略原本会暴露的凭据文件。要保护凭据文件并使其仍可通过沙箱代理使用，请改用 sandbox.credentials。

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

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

Claude Code 会在会话加载的所有设置作用域之间合并条目，并添加来自您的 Read(...) 拒绝权限规则的路径。当 filesystem.disabled 为 true 时，Claude Code 不会强制执行这些条目。

sandbox.filesystem.allowRead

在 denyRead 阻止的区域内重新开放特定路径的读取权限，以构建仅限工作区的读取访问。精确或通配符 denyRead 条目在更宽泛的 allowRead 中仍保持阻止，如重叠表所示。当 ~/**/.env 等通配符 denyRead 条目匹配某个目录时，Claude Code 也会阻止读取其内容。在 v2.1.236 之前的 macOS 上，只要更宽泛的 allowRead 条目覆盖了通配符 denyRead 条目匹配的路径，Claude Code 就会重新开放这些路径，并使被匹配目录的内容保持可读。

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

以下配置阻止读取您的主目录，但项目本身除外：

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

Claude Code 在项目设置中将 . 条目解析为项目根目录，在用户设置中解析为 ~/.claude。除非设置了 allowManagedReadPathsOnly，否则 Claude Code 会在会话加载的各设置文件之间合并条目；当 permissions.blockReadsOutsideWorkingDirectories 启用时，会排除来自仓库设置的条目。仓库锁定也可能排除仓库的条目。

sandbox.filesystem.allowManagedReadPathsOnly

仅遵循来自托管设置的 allowRead 条目，使开发者无法重新开放组织已阻止路径的读取权限。Claude Code 仍会合并来自会话加载的所有设置作用域的 denyRead 条目。

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

以下配置阻止读取主目录，重新开放 ~/work，并阻止开发者重新开放其他任何内容：

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

请参阅防止开发者放宽策略。

sandbox.filesystem.disabled

跳过文件系统隔离，同时保留网络隔离。沙箱化命令可以不受限制地读写主机文件系统，而其网络出站流量仍限制在 network.allowedDomains 范围内。当您使用沙箱是为了控制命令连接到哪里而非写入什么时使用此设置。

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

以下配置使文件系统保持开放，并将网络出站流量限制为 GitHub 和 npm：

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

关闭该层后，Claude Code 不会强制执行 denyRead 或 credentials.files 的 deny 条目，而 credentials.envVars 条目和已应用的 mask 条目仍然有效。autoAllowBashIfSandboxed 仍默认为 true，因此请将其设置为 false 以继续显示提示。有关可以设置它的完整来源列表以及关闭隔离后的变化，请参阅禁用文件系统隔离。

sandbox.ignoreViolations

对于您预期某条命令会探测并被拒绝的路径（例如某个在启动时检查 /etc/hosts 的工具），静默其沙箱违规报告，使这些拒绝不会显示为违规，也不会出现在 Claude 看到的内容中。沙箱仍会阻止该访问；只是报告被抑制。键是用于匹配命令的子字符串，* 匹配所有命令；值是该命令要忽略的违规子字符串，例如文件系统路径。

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

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

sandbox.enableWeakerNestedSandbox

在非特权 Docker 容器内运行 Linux 沙箱，在这种容器中 bubblewrap 无法挂载新的 /proc。此时内部沙箱会绑定挂载容器现有的 /proc，这会暴露新挂载本应隐藏的进程信息。这会降低安全性；仅当外部容器已提供您所需的隔离时才使用。

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

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

仅限 Linux 和 WSL2。请参阅Bubblewrap 在容器内无法启动。

sandbox.enableWeakerNetworkIsolation

允许 macOS 上的沙箱化命令访问系统 TLS 信任服务 com.apple.trustd.agent。当您将 network.httpProxyPort 与 MITM 代理和自定义 CA 一起使用时，gh、gcloud 和 terraform 等基于 Go 的工具需要它来验证 TLS 证书。这会通过信任服务打开一条潜在的数据外泄路径，从而降低安全性。

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

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

如果您不使用 MITM 代理，请改为在 excludedCommands 中列出失败的工具；请参阅基于 Go 的 CLI 在 macOS 上 TLS 验证失败。

sandbox.allowAppleEvents

允许 macOS 上的沙箱化命令发送 Apple Events，open、osascript 以及在浏览器中打开 URL 的工具都需要它；没有它时，这些命令会以错误 -600 失败。这会移除代码执行隔离：沙箱化命令可以在没有用户提示的情况下在沙箱外启动其他应用程序，并可以向正在运行的应用程序（如 Terminal）发送 AppleScript 命令，但需经过 macOS 针对每个应用的自动化授权提示（TCC）。

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

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

要保留隔离并仍运行某个此类工具，请改为将其添加到 excludedCommands。请参阅 macOS 上的 Apple Events。

sandbox.allowNestedUserNamespaces

允许 Linux 和 WSL2 上的沙箱化命令创建用户命名空间，Chromium 和 Electron 自身的沙箱、嵌套的 bubblewrap 以及 unshare 都需要它。如果将此键设置为 true，您就关闭了一道安全边界：来自沙箱化命令的代码可能最终在沙箱外运行。对于 rootless Podman 或 Buildah，请改用 excludedCommands，因为沙箱还会以其他方式阻止它们。需要 Claude Code v2.1.305 或更高版本。

• 作用域：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
  }
}

启用此键后，不要依赖沙箱的任何限制（包括受保护路径和 credentials.files 条目）来阻止恶意命令。在自动允许模式下，该命令可以在没有权限提示的情况下运行。如果您的组织有安全团队，请在启用此键之前与他们确认。

要找到适用于您工具的解决方法，请参阅Chromium 或 rootless Podman 在 Linux 沙箱内失败。

sandbox.ripgrep

让沙箱使用您自己的 ripgrep 二进制文件，而不是 Claude Code 使用的那个，例如当您的平台需要以不同方式构建的 rg 时。

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

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

sandbox.bwrapPath

让沙箱使用安装在 PATH 之外的 bubblewrap 二进制文件，例如隔离网络主机上的内置副本。Claude Code 在启动时的依赖检查以及包装每条沙箱化命令时都会使用此路径。

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

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

仅限 Linux 和 WSL2。

sandbox.socatPath

让沙箱网络代理使用安装在 PATH 之外的 socat 二进制文件。

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

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

仅限 Linux 和 WSL2。

sandbox.credentials

声明要对沙箱化命令进行保护的凭据文件和环境变量。每个条目指定一个文件 path 或变量 name 以及一个 mode：deny 在沙箱内隐藏凭据，mask 向沙箱化命令显示一个占位符，同时由沙箱代理在出站请求中替换为真实值。Claude Code 仅保护您列出的条目；没有内置的凭据拒绝列表。

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

以下配置隐藏您的 AWS 凭据文件，并从沙箱化命令中移除 GITHUB_TOKEN：

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

deny 文件保护属于文件系统层，因此当您禁用文件系统隔离时它不适用；环境变量保护仍然适用。

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

当托管的 sandbox.credentials 条目验证失败时，Claude Code 会尽可能继续保护该凭据：

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

适用于 v2.1.191 及更高版本；在 v2.1.221 之前，每个无效条目都会被移除。有关其他按字段处理的托管键，请参阅托管设置中的无效条目。

sandbox.credentials.files

保护凭据文件或目录免受沙箱化命令访问。使用 "mode": "deny" 时，Claude Code 会在沙箱内阻止读取该路径，与 sandbox.filesystem.denyRead 的读取阻止相同。使用 "mode": "mask" 时，Linux 和 WSL2 上的沙箱化命令读取的是该文件的哨兵副本，沙箱代理会在发往该条目 injectHosts 的出站请求中替换为真实值；在 macOS 上，该文件在沙箱内则不可读。"mode": "mask" 需要 Claude Code v2.1.221 或更高版本。

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

以下配置隐藏您的 AWS 凭据文件并掩码 gh 主机文件，仅在发往 api.github.com 的请求中替换为真实值：

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

路径使用与 sandbox.filesystem.* 设置相同的前缀，Claude Code 会合并来自会话加载的所有设置作用域的数组。保护凭据介绍了您通过 --setting-sources 排除的来源中仍然适用的内容。mask 条目需要 Claude Code v2.1.221 或更高版本。

mask 替换仅通过沙箱代理进行，因此请设置 sandbox.network.tlsTerminate，对于纯 HTTP 测试网络则设置 allowPlaintextInject。mask 适用于单个文件，因此请逐个列出每个凭据文件。Claude Code 接受但会忽略 deny 条目上的 mask 字段。掩码凭据介绍了会遵循哪些设置来源，掩码凭据文件介绍了条目何时会回退为 deny。

文件掩码字段

mask 条目接受以下可选字段。没有 extract 或 decode 时，Claude Code 会将整个文件内容替换为一个哨兵值。在启用了文件系统隔离的 macOS 上，Claude Code 会在 extract 或 decode 运行之前将 mask 条目作为 deny 应用；请参阅掩码凭据文件。

以下配置仅掩码 gh 主机文件中的 oauth_token 值，替换该值在文件中的所有其他副本，在模式未匹配任何内容时使文件不可读，并仅在发往 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

保护环境变量免受沙箱化命令访问。使用 "mode": "deny" 时，Claude Code 会从沙箱化命令的环境中移除该变量。使用 "mode": "mask" 时，沙箱化命令看到的是每会话的哨兵值，沙箱代理会在发往该条目 injectHosts 的出站请求中替换为真实值，因此 gh 和 npm 等工具可以继续进行身份验证，而无需持有真实凭据。

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

以下配置从沙箱化命令中移除 NPM_TOKEN 并掩码 GITHUB_TOKEN，仅在发往 api.github.com 的请求中替换为真实值：

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

name 必须以字母或下划线开头，且只能包含字母、数字和下划线。Claude Code 会合并来自会话加载的所有设置作用域的数组，当同一变量以两种模式出现时应用 deny。保护凭据介绍了您通过 --setting-sources 排除的来源中仍然适用的内容。

mask 替换仅通过沙箱代理进行，因此请设置 sandbox.network.tlsTerminate，对于纯 HTTP 测试网络则设置 allowPlaintextInject；请参阅掩码凭据。Claude Code 接受但会忽略 deny 条目上的 mask 字段。

环境变量掩码字段

mask 条目接受以下可选字段。没有 extract 或 decode 时，Claude Code 会将整个值替换为一个哨兵值。extract 和 decode 不能在同一条目上组合使用。

以下配置仅掩码 DATABASE_URL 中的密码，在模式未匹配任何内容时取消设置该变量，并掩码 SERVICE_JWT 中的 JWT，同时使除 api_key 之外的所有声明保持可读：

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

sandbox.credentials.allowPlaintextInject

除 TLS 终止的 HTTPS 外，还允许在纯 HTTP 请求上进行 mask 替换。在纯 HTTP 上，上游身份未经验证，凭据以明文传输，因此在受信任的测试网络之外请保持关闭。

• 作用域：User or managed
• 类型：布尔值
  • true：除 TLS 终止的 HTTPS 外，Claude Code 还允许在纯 HTTP 请求上进行 mask 替换
  • false：Claude Code 仅允许在 TLS 终止的 HTTPS 上进行 mask 替换
• 默认值：false

{
  "sandbox": {
    "credentials": {
      "allowPlaintextInject": true
    }
  }
}

sandbox.credentials.awsPairs

当您的凭据存放在非标准名称的变量中时，将构成同一 AWS 凭据的被掩码环境变量分组，用于 SigV4 重新签名。当您掩码常规的 AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY 和 AWS_SESSION_TOKEN 三者的完整值时，Claude Code 会自动将它们关联，因此仅在使用其他名称时才需要此键。需要 Claude Code v2.1.224 或更高版本。

• 作用域：User or managed
• 类型：对象数组，每个对象包含 accessKeyIdVar、secretAccessKeyVar 以及可选的 sessionTokenVar，用于指定 sandbox.credentials.envVars 条目
• 默认值：未设置，因此只有常规的三个变量会被配对

以下配置将三个自定义名称的变量关联为一个 AWS 凭据以进行重新签名：

{
  "sandbox": {
    "credentials": {
      "awsPairs": [
        {
          "accessKeyIdVar": "MY_KEY_ID",
          "secretAccessKeyVar": "MY_SECRET_KEY",
          "sessionTokenVar": "MY_SESSION_TOKEN"
        }
      ]
    }
  }
}

每个指定的变量都必须是 sandbox.credentials.envVars 中完整值的 mask 条目，不带 extract 或 decode，并且在所有配对中只能占据一个位置。以下规则同样适用：

• 代理会对访问密钥 ID 条目的 injectHosts 中列出的主机上的请求进行重新签名
• 设置了 sessionTokenVar 时，代理会在重新签名的请求中以 x-amz-security-token 发送真实令牌
• 在配对中指定任何常规变量都会替换自动配对

sandbox.credentials.sigv4

选择沙箱代理如何处理它无法重新签名的 AWS 请求形式：streaming 用于 aws-chunked 流式上传，presigned 用于预签名 URL，sigv4a 用于 SigV4A 非对称签名。这仅适用于使用被掩码配对的占位访问密钥 ID 签名的请求。需要 Claude Code v2.1.224 或更高版本。

• 作用域：User or managed
• 类型：包含 streaming、presigned 和 sigv4a 的对象，每项取以下值之一：
  • "deny"：代理使请求失败
  • "passthrough"：代理转发使用被掩码占位符签名的请求，因此工具会收到 AWS 自身的拒绝
• 默认值：未设置，因此每种形式都为 "deny"

以下配置转发流式上传，而不是在代理处使其失败：

{
  "sandbox": {
    "credentials": {
      "sigv4": {
        "streaming": "passthrough"
      }
    }
  }
}

使用 deny 时，代理会使请求失败。使用 passthrough 时，代理会转发签名基于被掩码占位符计算的请求，因此 AWS 会拒绝它，调用工具收到的是 AWS 自身的响应，而不是代理错误。

sandbox.network

控制沙箱化命令可以访问哪些主机、端口和套接字。沙箱通过一个强制执行这些列表的代理路由出站流量；有关代理如何决策以及何时提示，请参阅网络隔离。

• 作用域：Any file。strictAllowlist、allowManagedDomainsOnly 和 tlsTerminate 从较少的来源读取，详见各自条目。
• 类型：包含以下子键的对象
• 默认值：未设置，因此没有预先允许的域名，由您的权限模式决定每个新主机的处理方式

以下配置预先允许 GitHub 和 npm，阻止 uploads.github.com，并允许命令绑定到 localhost：

{
  "sandbox": {
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"],
      "deniedDomains": ["uploads.github.com"],
      "allowLocalBinding": true
    }
  }
}

Claude Code 会在各设置作用域之间合并数组子键，因此除非适用仓库锁定，否则项目可以向您的用户列表添加域名。WebFetch(domain:...) 允许和拒绝权限规则也会添加到相同的允许和拒绝列表中。

sandbox.network.allowUnixSockets

列出 macOS 上沙箱化命令可以连接的 Unix 套接字路径。Claude Code 在 Linux 和 WSL2 上会忽略此列表，因为 seccomp 过滤器无法检查套接字路径；在这些平台上请改用 allowAllUnixSockets。

• 作用域：Any file，对项目设置和本地设置有限制
• 类型：字符串数组，每项是一个套接字路径
• 默认值：未设置，因此 macOS 沙箱阻止所有 Unix 套接字

{
  "sandbox": {
    "network": {
      "allowUnixSockets": ["~/.ssh/agent-socket"]
    }
  }
}

套接字路径可能授予广泛的访问权限：例如，允许 /var/run/docker.sock 会让沙箱化命令控制 Docker 守护进程。请参阅安全限制。

sandbox.network.allowAllUnixSockets

允许沙箱化命令连接到所有 Unix 套接字。在 Linux 和 WSL2 上，沙箱的 seccomp 过滤器会阻止 socket(AF_UNIX, ...) 调用，因此这是在这些平台上允许 Unix 套接字的唯一方式。当过滤器缺失时（/sandbox 会在其 Dependencies 选项卡中报告），沙箱不会阻止 Unix 套接字调用。有关过滤器的来源，请参阅设置 Linux 和 WSL2。

• 作用域：Any file，对项目设置和本地设置有限制
• 类型：Boolean
  • true：沙箱内命令可以连接到所有 Unix 套接字。在 Linux 和 WSL2 上，它们还可以连接到 VM 套接字，即 AF_VSOCK 地址族
  • false：沙箱阻止 Unix 套接字连接：在 macOS 上，allowUnixSockets 中的路径除外；在 Linux 和 WSL2 上，在 seccomp 过滤器存在时通过该过滤器阻止
• 默认值：false

{
  "sandbox": {
    "network": {
      "allowAllUnixSockets": true
    }
  }
}

在 WSL2 上，true 还会重新开放用于启动 cmd.exe 和 powershell.exe 等 Windows 二进制文件的互操作套接字。

sandbox.network.allowLocalBinding

允许 macOS 上的沙箱化命令监听网络端口（例如启动开发服务器），并连接到 localhost 上的任意端口。监听非回环地址的命令会接受来自其他机器的连接。此键在 Linux 和 WSL2 上无效，因为在这些平台上每条沙箱化命令都有自己的回环接口。要从 Linux 或 WSL2 访问主机上的服务器，请参阅命令无法访问 localhost 上的服务器。

• 作用域：Any file，对项目设置和本地设置有限制
• 类型：布尔值
  • true：macOS 上的沙箱化命令可以监听任何本地地址，并连接到 localhost 上的任意端口
  • false：macOS 上的沙箱化命令无法监听端口，也无法直接连接到 localhost 上的服务器
• 默认值：false

{
  "sandbox": {
    "network": {
      "allowLocalBinding": true
    }
  }
}

sandbox.network.allowMachLookup

列出 macOS 沙箱可以查找的额外 XPC 和 Mach 服务名称。通过 XPC 通信的工具（例如 iOS Simulator 或 Playwright）需要在此处列出其服务。沙箱化命令可以访问沙箱外您列出的每个服务，而沙箱不会限制这些服务为这些命令所做的事情。

• 作用域：Any file，对项目设置和本地设置有限制
• 类型：字符串数组，每项是一个服务名称；单个末尾 * 匹配前缀，单独的 "*" 匹配所有服务
• 默认值：未设置

以下配置允许 com.apple.CoreSimulator. 前缀下的所有服务：

{
  "sandbox": {
    "network": {
      "allowMachLookup": ["com.apple.CoreSimulator.*"]
    }
  }
}

sandbox.network.allowedDomains

为沙箱化命令的出站流量预先允许域名，使沙箱不再为它们提示。*.example.com 等通配符匹配子域名，可选的 :port 后缀将条目限制为一个端口；不带端口的条目匹配所有端口。

• 作用域：Any file，对项目设置和本地设置有限制。设置了 allowManagedDomainsOnly 时仅限托管设置。
• 类型：字符串数组，每项是一个域名、通配符模式或 IP 字面量，可带可选的 :port 后缀
• 默认值：未设置，因此由您的权限模式决定每个新主机的处理方式

以下配置在所有端口上预先允许 GitHub、所有 npm 子域名，以及仅在 443 端口上的一个 API 主机：

{
  "sandbox": {
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org", "api.example.com:443"]
    }
  }
}

IPv6 字面量请用方括号括起，可带可选端口："[::1]" 允许所有端口，"[::1]:443" 允许一个端口。方括号形式需要 Claude Code v2.1.229 或更高版本。请参阅域名列表中的 IPv6 地址。

sandbox.network.deniedDomains

阻止沙箱化命令出站流量访问某些域名，使用与 allowedDomains 相同的通配符、端口和 IPv6 语法。即使某个 allowedDomains 条目也匹配被拒绝的域名，该域名仍保持阻止。

• 作用域：Any file
• 类型：字符串数组，每项是一个域名、通配符模式或 IP 字面量，可带可选的 :port 后缀
• 默认值：未设置

{
  "sandbox": {
    "network": {
      "deniedDomains": ["sensitive.cloud.example.com"]
    }
  }
}

即使设置了 allowManagedDomainsOnly，Claude Code 也会合并来自会话加载的所有设置来源的此列表，因此开发者始终可以收紧拒绝列表。有关 IPv6 字面量，请参阅域名列表中的 IPv6 地址。

使用标记完全限定域名的末尾点书写的条目（如 example.com.）与 example.com 阻止相同的连接。

sandbox.network.strictAllowlist

拒绝沙箱化命令访问允许列表之外的主机，而不是提示批准。允许列表为 allowedDomains 加上来自 WebFetch(domain:...) 允许规则的域名；设置了 allowManagedDomainsOnly 时，则仅为托管设置中的条目。无需管理员强制要求沙箱即适用的锁定介绍了仓库的条目。需要 Claude Code v2.1.219 或更高版本。

• 作用域：User or managed。仓库无法启用或关闭它。
• 类型：布尔值
  • true：Claude Code 拒绝沙箱化命令访问允许列表之外的主机
  • false：除非另一个受信任的设置文件设置了 true，否则 Claude Code 会按权限模式处理允许列表之外的主机，而不是直接拒绝：在自动模式下，它会根据命令的每命令允许域名检查该主机；在 dontAsk 模式下拒绝；在 bypassPermissions 模式下以及可使用绕过的交互式终端计划模式会话中允许；其他情况下询问您
• 默认值：false

{
  "sandbox": {
    "network": {
      "strictAllowlist": true
    }
  }
}

Claude Code 仅对沙箱化命令强制执行此设置；WebFetch 等进程内工具仍遵循其权限规则。当任何被遵循的来源将其设置为 true 时，它会保持启用。请参阅网络隔离。需要 Claude Code v2.1.219 或更高版本。

sandbox.network.allowManagedDomainsOnly

将网络允许列表锁定为托管设置所定义的内容。此时 Claude Code 仅遵循来自托管设置的 allowedDomains 和 WebFetch(domain:...) 允许规则，忽略来自用户、项目、本地和 --settings 设置的域名，并自动阻止未允许的域名而不是提示。

• 作用域：Managed
• 类型：布尔值
  • true：Claude Code 仅遵循来自托管设置的 allowedDomains 和 WebFetch(domain:...) 允许规则，并阻止未允许的域名而不是提示
  • false：来自其他设置文件的域名可以合并到允许列表中
• 默认值：false

以下配置将允许列表锁定为 GitHub 和 npm，并忽略开发者添加的任何域名：

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

当此键为 true 时，沙箱是管理员强制要求的，并且只有托管设置可以设置代理端口。

被拒绝的域名仍会从会话加载的所有来源合并。请参阅防止开发者放宽策略。

sandbox.network.httpProxyPort

让沙箱使用您自己的 HTTP 代理，而不是 Claude Code 运行的代理。组织这样做是为了检查 HTTPS 流量、应用自己的过滤规则或记录请求日志。您的代理接管过滤工作，Claude Code 不再对发送到那里的流量应用其域名列表和网络提示。未设置时，Claude Code 会为 HTTP 流量启动自己的代理。

• 作用域：Any file，除非其他沙箱设置限制了哪些文件可以设置端口
• 类型：数字，一个本地 TCP 端口
• 默认值：未设置，因此 Claude Code 运行自己的代理

{
  "sandbox": {
    "network": {
      "httpProxyPort": 8080
    }
  }
}

如果您的代理也应承载 SOCKS 流量，请同时设置 socksProxyPort；如果只设置了两者之一，Claude Code 仍会为另一种协议运行自己的代理。请参阅自定义代理配置。

sandbox.network.socksProxyPort

让沙箱使用您自己的 SOCKS5 代理，而不是 Claude Code 运行的代理。您的代理接管过滤工作，Claude Code 不再对发送到那里的流量应用其域名列表和网络提示。未设置时，Claude Code 会为 SOCKS 流量启动自己的代理。

• 作用域：Any file，除非其他沙箱设置限制了哪些文件可以设置端口
• 类型：数字，一个本地 TCP 端口
• 默认值：未设置，因此 Claude Code 运行自己的代理

{
  "sandbox": {
    "network": {
      "socksProxyPort": 8081
    }
  }
}

请参阅自定义代理配置。

sandbox.network.tlsTerminate

让沙箱代理终止 TLS，以便读取 HTTPS 请求的内容。此功能为实验性功能，mask 凭据替换需要启用它。设置为 {} 可为会话生成一个临时证书颁发机构，或设置 caCertPath 和 caKeyPath 以使用您自己的证书颁发机构。

• 作用域：User or managed。仓库无法启用此设置，也无法提供证书颁发机构。
• 类型：对象，包含可选的 caCertPath 和 caKeyPath 字符串，每个均为文件路径
• 默认值：未设置，因此代理不会终止或检查 TLS

{
  "sandbox": {
    "network": {
      "tlsTerminate": {}
    }
  }
}

当多个受认可的来源都设置了此项时，Claude Code 使用优先级最高的来源中的值：托管设置，其次是 --settings 标志，然后是用户设置。

记忆与上下文

控制 Claude Code 将哪些内容加载到上下文中、如何进行压缩，以及将记忆和计划保存在何处。请参阅管理上下文和记忆。

autoCompactEnabled

让 Claude Code 在上下文接近上限时自动压缩对话。在 /config 中显示为 Auto-compact，在其中切换时会将此键写入您的用户设置。

• 作用域：Any file
• 类型：布尔值
  • true：Claude Code 在上下文接近上限时自动压缩对话
  • false：Claude Code 不会自动压缩
• 默认值：true
• 单会话覆盖：DISABLE_AUTO_COMPACT 可为单个会话关闭自动压缩；两者中任意一个将其关闭后，另一个都无法重新将其开启

{
  "autoCompactEnabled": false
}

关闭自动压缩后，手动 /compact 命令仍然可用。如果您关闭自动压缩，空闲压缩也会随之关闭。

autoCompactWindow

设置上下文窗口填充到多满时 Claude Code 会自动压缩。

• 作用域：Any file
• 类型：token 数量，范围为 100000 到 1000000。Claude Code 会将该值限制在您所用模型的上下文窗口以内；模型概览列出了每个模型的上下文窗口
• 默认值：未设置，此时 Claude Code 会选择针对您的模型调优的窗口
• 单会话覆盖：--autocompact 在单个会话中优先于此键，而 CLAUDE_CODE_AUTO_COMPACT_WINDOW 优先于这两者，除非 Claude Code 忽略该变量的值

{
  "autoCompactWindow": 500000
}

/autocompact 命令会将当前模型的窗口保存在 modelSettings 下，对于该模型，它优先于同一文件中的此键。设置自动压缩窗口介绍了该命令、标志、变量和设置之间的相互作用。

autoMemoryDirectory

将自动记忆存储在您选择的目录中，而不是每个项目的默认目录。

• 作用域：Any file
• 类型：字符串，绝对路径或以 ~/ 开头的目录路径
• 默认值：未设置，此时 Claude Code 使用 ~/.claude/projects/<project>/memory/

{
  "autoMemoryDirectory": "~/my-memory-dir"
}

对于项目设置或本地设置中的此键，Claude Code 遵循与 hook 相同的工作区信任规则，因为克隆的仓库可能会提供这些文件。

autoMemoryEnabled

开启或关闭自动记忆。为 false 时，Claude 不会读取或写入自动记忆目录。您也可以在会话中使用 /memory 切换它，这会将此键写入您的用户设置。

• 作用域：Any file
• 类型：布尔值
  • true：与未设置相同；自动记忆保持开启，除非有优先级高于此键的设置为当前会话将其关闭，例如 --bare、安全模式或 CLAUDE_CODE_DISABLE_AUTO_MEMORY
  • false：Claude 不会读取或写入自动记忆目录
• 默认值：true
• 单会话覆盖：CLAUDE_CODE_DISABLE_AUTO_MEMORY 在单个会话中优先于此键，无论开启还是关闭

{
  "autoMemoryEnabled": false
}

bashOutputMaxChars

设置成功执行的 Bash 或 PowerShell 命令的输出中，有多少字符会以内联方式提供给 Claude。当输出超过此上限时，Claude Code 会将其保存到文件中，Claude 会收到一段简短预览以及该文件的路径。如果命令输出（例如详细的构建输出或完整的测试套件日志）经常超出默认上限，而您希望 Claude 无需打开文件即可读取，请提高此上限。需要 Claude Code v2.1.261 或更高版本。

• 作用域：Any file
• 类型：字符数，正整数。Claude Code 会将该值限制在 4000 到 128000 的范围内
• 默认值：未设置，此时 Claude 以内联方式最多接收 30,000 个字符

{
  "bashOutputMaxChars": 100000
}

设置此键后，Claude Code 会忽略 BASH_MAX_OUTPUT_LENGTH 环境变量。

claudeMd

将 CLAUDE.md 风格的指令作为组织托管的记忆注入，而无需部署单独的文件。Claude Code 会将该文本作为托管记忆条目加载，其顺序先于用户和项目的 CLAUDE.md 文件。

• 作用域：Managed
• 类型：字符串，即 CLAUDE.md 文件的文本；按照编写该文件的方式书写，包括 Markdown，换行符写作 \n
• 默认值：未设置

此示例以简短的 Markdown 列表形式部署两条规则：

{
  "claudeMd": "# Engineering rules\n\n- Always run make lint before committing.\n- Never push directly to main."
}

请参阅部署组织范围的 CLAUDE.md。

claudeMdExcludes

在 Claude Code 加载记忆时跳过特定的 CLAUDE.md 文件。在大型 monorepo 中，可用它跳过其他团队与您的工作无关的 CLAUDE.md 文件；大型代码库指南中的排除无关的 CLAUDE.md 文件详细介绍了这种情况。模式会与绝对文件路径进行匹配。

• 作用域：Any file
• 类型：字符串数组，每一项为 glob 模式或绝对路径
• 默认值：未设置，此时 Claude Code 会加载它找到的每个 CLAUDE.md

{
  "claudeMdExcludes": ["**/vendor/**/CLAUDE.md"]
}

排除仅适用于用户、项目和本地记忆文件；托管策略的 CLAUDE.md 文件无法被排除。

env

为每个会话以及 Claude Code 从中启动的子进程设置环境变量。环境变量参考中的大多数变量都可以放在这里，这样就能将某个变量应用到每个会话或推广到您的团队。项目设置和本地设置无法设置其中一部分变量。

• 作用域：Any file
• 类型：将变量名映射到字符串值的对象
• 默认值：未设置

此示例关闭自动压缩，并通过代理路由 API 请求：

{
  "env": {
    "DISABLE_AUTO_COMPACT": "1",
    "ANTHROPIC_BASE_URL": "https://proxy.example.com"
  }
}

env 值如何与您的 shell 交互

• 此处的值会覆盖您在 shell 中导出的同名变量；当多个设置文件设置了同一变量时，以优先级最高的为准。Claude Code 在 env 中忽略的变量列出了项目设置和本地设置的例外情况。
• 当 Claude Desktop 应用或自托管环境运行器启动会话时，它所构建的启动环境优先：对于启动环境已设置的变量，Claude Code 会忽略任何设置文件中的 env 值。调试日志会列出每个被忽略的变量。
• 要取消 shell 中的导出，请将该变量设置为 ""。在选择提供商时，Claude Code 将空值视为未设置，而子进程会继承该空值。
• 在此处设置的 NO_COLOR 和 FORCE_COLOR 仅作用于子进程。要更改 Claude Code 自身的界面颜色，请在启动 claude 之前在 shell 中设置它们。
• 此处的值以明文形式保存在设置文件中，并会传递给 Claude Code 启动的每个子进程。对于会轮换的 OTLP bearer 令牌，请使用 otelHeadersHelper；对于 API 凭据，请使用 apiKeyHelper。

Claude Code 何时应用 env 值

• 来自用户设置、--settings 和托管设置的值：在启动时应用；当保存的更改改变了合并后的 env 时，会在正在运行的会话中再次应用。
• 来自项目设置和本地设置的值：在您信任工作区之后应用，或在 -p 模式（从不显示信任对话框）下于启动时应用；当保存的更改改变了合并后的 env 时会再次应用。
• Claude Code 归类为安全的变量，例如模型选择、超时和限制以及功能开关：在启动时从每个设置文件中应用，但项目设置和本地设置无法设置的变量除外。
• 在 v2.1.246 或更高版本中使用 /cd 移动会话之后：在前一个目录的值之上应用新目录的项目和本地 env 值。

Claude Code 在 env 中忽略的变量

• 项目设置和本地设置无法设置那些不应由检出的仓库控制的变量；请改为在 shell、用户设置或托管设置中设置它们。Claude Code 会丢弃每个此类变量（少数关闭遥测的值除外），并记录一条可通过 claude --debug 查看的警告。它们包括：

  • 选择 Claude Code 存储或写入自身文件位置的变量：CLAUDE_CONFIG_DIR、CLAUDE_CODE_TMPDIR，以及操作系统目录变量，例如 HOME、TMPDIR、TMP、TEMP 和 XDG_* 系列。

  • 为 Claude Code 启动的进程选择程序和全机配置的 Windows 变量，例如 SystemRoot、ComSpec、ProgramData、LOCALAPPDATA、PATHEXT、PSModulePath 和 ProgramFiles 系列。

  • 导出会话内容的变量：OTEL_LOG_RAW_API_BODIES 以及详细 beta 追踪变量对 ENABLE_BETA_TRACING_DETAILED 和 BETA_TRACING_ENDPOINT。

  • 用于开启遥测、选择遥测去向或选择其捕获内容的 OpenTelemetry 导出器变量：

    • CLAUDE_CODE_ENABLE_TELEMETRY，以及增强遥测 beta 变量对 CLAUDE_CODE_ENHANCED_TELEMETRY_BETA 和 ENABLE_ENHANCED_TELEMETRY_BETA
    • 导出器选择变量 OTEL_LOGS_EXPORTER、OTEL_METRICS_EXPORTER 和 OTEL_TRACES_EXPORTER
    • 内容变量 OTEL_LOG_USER_PROMPTS、OTEL_LOG_ASSISTANT_RESPONSES、OTEL_LOG_TOOL_CONTENT 和 OTEL_LOG_TOOL_DETAILS
    • 名称以 _ENDPOINT、_HEADERS、_PROTOCOL、_CERTIFICATE、_CLIENT_KEY 或 _INSECURE 结尾的 OTEL_EXPORTER_OTLP_* 变量，包括通用形式和按信号区分的形式，例如 OTEL_EXPORTER_OTLP_ENDPOINT 和 OTEL_EXPORTER_OTLP_METRICS_HEADERS
    • OTEL_EXPORTER_PROMETHEUS_HOST 和 OTEL_EXPORTER_PROMETHEUS_PORT

    只有以下值仍会从项目设置和本地设置中生效，因为它们用于关闭某项功能：三个导出器选择变量的 none，以及 OTEL_LOG_USER_PROMPTS、OTEL_LOG_TOOL_CONTENT 和 OTEL_LOG_TOOL_DETAILS 的关闭值（例如 0）。此类值会覆盖您用户设置中的同名变量，但不会覆盖由启动 Claude Code 的环境、--settings 文件或托管设置所设置的变量。

    当项目或本地设置文件设置了此组中的变量时，本地交互式会话会在启动时显示一条通知。运行 /status 或 claude doctor 可查看 Claude Code 忽略了哪些变量以及哪些变量关闭了遥测；两者都只列出名称，从不列出值。使用 -p 的非交互式运行或 Agent SDK 会话不会显示通知，因此升级后请检查您的收集器是否仍能收到数据。如果收不到，请在用户设置、托管设置、作业环境或通过 --settings 传入的文件中设置这些变量。

    在项目设置和本地设置中忽略此组变量需要 Claude Code v2.1.282 或更高版本。

  • 改变 Claude Code 启动或同步方式的变量，例如 CLAUDE_CODE_PROCESS_WRAPPER、CLAUDE_CODE_SYNC_SKILLS、CLAUDE_CODE_SYNC_PLUGINS、CLAUDE_CODE_PLUGIN_CACHE_DIR 和 CLAUDE_CODE_PLUGIN_SEED_DIR。

  • 设置您的 claude.ai 登录信息的变量，例如 CLAUDE_CODE_OAUTH_TOKEN、CLAUDE_CODE_OAUTH_REFRESH_TOKEN 和 CLAUDE_CODE_OAUTH_SCOPES。

  • 屏幕阅读器模式变量 CLAUDE_AX_SCREEN_READER，以及其他名称以 CLAUDE_AX_ 开头的变量，例如 CLAUDE_AX_STARTUP_QUIET_MS。

  • CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS，用于设置未响应对话框的计时器。

  • CLAUDE_CODE_DISABLE_ATTACHMENTS，用于关闭附件处理。

  • CLAUDE_CODE_DISABLE_FILE_MENTIONS，用于阻止 Claude Code 展开对文件和目录的 @ 提及。

  在 v2.1.251 之前，项目设置和本地设置还可以设置此列表中选择 Claude Code 文件写入位置或导出会话内容的变量，但 HOME 和 XDG_CONFIG_HOME 除外。在 v2.1.290 之前，它们还可以设置对话框计时器变量和 CLAUDE_CODE_DISABLE_ATTACHMENTS。

• 由 Claude Code 托管环境所拥有的身份变量（例如 CLAUDE_CODE_REMOTE 和 CLAUDE_CODE_ACCOUNT_UUID）在所有文件中都会被忽略。

• CLAUDE_CODE_MESSAGING_SOCKET 和 CLAUDE_CODE_MESSAGING_TOKEN 由 Claude Code 自行导出，在所有文件中都会被忽略。忽略 socket 变量需要 Claude Code v2.1.224 或更高版本，忽略 token 变量需要 v2.1.228 或更高版本。

• CLAUDE_CODE_PROJECT_DIR_NAME 仅由 Claude Code 从启动环境中读取，在所有文件中都会被忽略；需要 v2.1.234 或更高版本。

• CLAUDE_CODE_RESTRICTED 仅由 Claude Code 从启动环境中读取，在所有文件中都会被忽略。

• CLAUDE_CODE_DISABLE_POWERSHELL_CMD_RM_DENY 仅由 Claude Code 从启动环境中读取，在所有文件中都会被忽略。该变量需要 Claude Code v2.1.283 或更高版本。

• CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT、CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT、CLAUDE_CODE_DISABLE_INLINE_SHELL_RM_PROMPT 和 CLAUDE_CODE_DISABLE_MOUNTED_DRIVE_RM_PROMPT 仅由 Claude Code 从启动环境中读取，在所有文件中都会被忽略。

• CLAUDE_CODE_EVEN_MORE_DANGEROUSLY_SKIP_PERMISSIONS 仅由 Claude Code 从启动环境中读取，在所有文件中都会被忽略。

• CLAUDE_CODE_WARN_DISK_FREE_GIB 和 CLAUDE_CODE_WARN_MEMORY_FREE_GIB 仅由 Claude Code 从启动环境中读取，在所有文件中都会被忽略。这些变量需要 Claude Code v2.1.304 或更高版本。

fileCheckpointingEnabled

让 Claude Code 在每次编辑前为文件创建快照，以便 /rewind 可以恢复它们。在 /config 中显示为 Rewind code (checkpoints)，在其中切换时会将此键写入您的用户设置。

• 作用域：Any file
• 类型：布尔值
  • true：Claude Code 在每次编辑前为文件创建快照，以便 /rewind 可以恢复它们
  • false：Claude Code 不为文件创建快照，因此 /rewind 无法恢复它们
• 默认值：true
• 单会话覆盖：CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING 可为单个会话关闭检查点功能；两者中任意一个将其关闭后，另一个都无法重新将其开启

{
  "fileCheckpointingEnabled": false
}

在 -p 运行或 Agent SDK 会话中，Claude Code 会忽略此键。SDK 通过其 enableFileCheckpointing 选项开启检查点功能，而单纯的 -p 运行需要 CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=true。请参阅 Agent SDK 中的文件检查点功能。

idleCompaction

空闲压缩会对您离开的长对话进行压缩。这样，您的下一条消息发送的将是摘要，而不是整个对话。压缩完成后，对话中会显示一条通知：

• 终端：一行以 Compacted while idle, before the prompt cache expired 开头的内容
• VS Code 聊天面板：一条包含 a summary written while you were away 的通知
• 桌面应用：同样的通知，位于标签包含 Claude Code notice 的行中。如果您看不到该行或其文本，请切换到 Verbose 视图模式。

对于满足以下所有条件的对话，空闲压缩默认开启：

• 会话：您处于交互式终端会话中、VS Code 扩展的聊天面板中，或者在会话运行于您的计算机上或通过 SSH 运行时处于桌面应用的 Code 标签页中
• 自动压缩：autoCompactEnabled 已开启
• 提示缓存：该对话使用一小时提示缓存 TTL
• 大小：对话的上下文已达到 token 阈值，您可以将其从默认的 200,000 进行更改
• 空闲时间：自上次请求以来已过去约一小时，且在此期间您的计算机保持唤醒状态

要关闭空闲压缩，请将此键设置为 false。

• 作用域：Any file
• 类型：布尔值
  • true：Claude Code 会压缩满足条件的空闲对话
  • false：Claude Code 不会在会话空闲时进行压缩
• 默认值：true
• 单会话覆盖：DISABLE_AUTO_COMPACT 会在关闭自动压缩的同时关闭空闲压缩

{
  "idleCompaction": false
}

要在终端会话中开启或关闭空闲压缩，请运行 /config 并更改 Idle compaction 行。您的选择会保存到用户设置中并立即生效。该行需要 Claude Code v2.1.302 或更高版本。如果您使用的是这些版本之一，但 /config 中未显示该行，请检查以下原因：

• 其他设置来源设置了此键：托管设置、--settings 标志或项目或本地设置文件中的值覆盖了您的用户设置。请改为在该来源中更改此键
• 在 v2.1.314 之前的版本中功能标志不可用：当 Claude Code 无法从 Anthropic 获取功能标志时，空闲压缩不会运行，因此没有需要关闭的内容

此键需要 Claude Code v2.1.290 或更高版本。较早版本会忽略此键，要停止空闲压缩，请关闭 autoCompactEnabled。

更改空闲压缩阈值

将 CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS 设置为对话上下文在适用空闲压缩前必须达到的 token 数。请使用正整数。低于 100000 的值会被提高到最低阈值 100000。

在默认值下，使用 200K 上下文窗口的对话会在达到 200,000 个 token 之前自动压缩。此示例将阈值降低到 150,000，以便这些对话符合条件：

{
  "env": {
    "CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS": "150000"
  }
}

VS Code 和桌面应用中的空闲压缩

类似下面这样的通知表示 Claude Code 已用摘要替换了您之前的对话，Claude 现在基于该摘要继续工作：

Compacted using a summary written while you were away · turn off with "idleCompaction": false in settings.json

您无需执行任何操作。要关闭空闲压缩，请在运行该会话的计算机或 WSL 发行版上的 ~/.claude/settings.json 中，或在其他设置文件中，将 idleCompaction 设置为 false。

plansDirectory

选择 Claude Code 存储其在计划模式中编写的计划文件的位置。Claude Code 会相对于项目根目录解析该路径。

• 作用域：Any file
• 类型：字符串，相对于项目根目录的路径
• 默认值：未设置，此时 Claude Code 使用 ~/.claude/plans

{
  "plansDirectory": "./plans"
}

在以下情况下，Claude Code 会将计划存储在 ~/.claude/plans 中，而不是您设置的目录中：

• 位于项目根目录之外：路径解析到项目根目录之外，例如 "../plans"。
• 在 macOS、Linux 和 WSL 上包含反斜杠：解析后的路径包含反斜杠，例如 Windows 风格的 "docs\\plans"。请写成 "docs/plans"，它在 Windows 上同样适用。

skillListingBudgetFraction

每一轮中，Claude 都会看到一份skill 列表及其描述，Claude Code 会将该列表限制在上下文窗口的一定比例以内。当列表超出上限时，Claude Code 会保留每个 skill 的名称，但会删除最少使用的 skill 的描述，因此 Claude 仍可调用这些 skill，但不太可能主动选择它们。提高此键可保留更多可见的描述，代价是每轮占用更多上下文。

• 作用域：Any file
• 类型：数字，大于 0 且不超过 1 的比例
• 默认值：0.01，即预留上下文窗口的 1%

{
  "skillListingBudgetFraction": 0.02
}

要查看该列表占用了多少上下文以及哪些 skill 占用最多，请运行 /doctor。

skillListingMaxDescChars

每一轮中，Claude 都会看到一份skill 列表，其中显示每个 skill 的 description 和 when_to_use 文本。此键限制 Claude Code 为每个 skill 显示的该文本的字符数；更长的文本会在上限处截断。

• 作用域：Any file
• 类型：字符数，正整数
• 默认值：1536

{
  "skillListingMaxDescChars": 2048
}

提高此值可保持长描述完整，代价是每轮占用更多上下文；降低此值可在 skillListingBudgetFraction 限制内容纳更多 skill。

taskOutputMaxChars

[!WARNING]

已在 v2.1.277 中移除，同时移除的还有它所控制大小的 TaskOutput 工具。在当前版本中设置它没有任何效果。Claude 现在改用 Read 读取后台任务的输出文件。

在 v2.1.276 及之前的版本中，您可以将此键设置为 Claude 使用 TaskOutput 工具读取后台任务时以内联方式接收的输出字符数。

界面与终端

更改 Claude Code 在终端中的外观和行为：主题、编辑器模式、状态栏、加载指示器、会话内通知以及无障碍功能。请参阅终端配置。

askUserQuestionTimeout

让未回答的 AskUserQuestion 对话框在空闲一段时间后自动继续，并提交您已选择的选项。当您暂时离开并希望 Claude 在没有您的情况下继续时，可设置此项。使用默认值时，问题会一直等待您回答。关于计时器何时暂停或从不启动，请参阅问题自动继续超时。

• 作用域：User or managed
• 类型：字符串，取值为 "60s"、"5m"、"10m" 或 "never" 之一
• 默认值："never"

{
  "askUserQuestionTimeout": "5m"
}

在 /config 中显示为 Question auto-continue timeout，该选项会将此键写入用户设置；当托管设置或 --settings 标志设置了此键时，Claude Code 会隐藏该行。

autoContinueAtUsageLimit

当 claude.ai 用量限制中止您的会话后，在打开的会话中等待，并在重置后自动继续任务。请参阅关闭自动继续。需要 Claude Code v2.1.234 或更高版本。

• 作用域：User or managed。仅从用户设置、--settings 和托管设置中读取。当这些都未设置此键时，设置了此键的项目或本地设置文件会关闭此功能，而不是被忽略。
• 类型：布尔值
  • true：当 claude.ai 用量限制中止您的会话后，Claude Code 会在打开的会话中等待，并在重置后自动继续任务
  • false：Claude Code 不会自行开始等待。您仍然可以从用量限制选项菜单中自行开始等待
• 默认值：true

{
  "autoContinueAtUsageLimit": false
}

在 /config 中显示为 Continue automatically at usage limit，该选项会将此键写入用户设置；当托管设置或 --settings 标志设置了此键时，Claude Code 会隐藏该行。

autoScrollEnabled

在全屏渲染中，跟随新输出滚动到对话底部。关闭此项后，Claude 继续工作时视图会停留在您滚动到的位置；权限提示仍会滚动到视野中。

• 作用域：Any file
• 类型：布尔值
  • true：对话跟随新输出滚动到底部
  • false：Claude 继续工作时视图停留在您滚动到的位置；权限提示仍显示在会话记录下方
• 默认值：true

{
  "autoScrollEnabled": false
}

开启全屏渲染时，在 /config 中显示为 Auto-scroll，该选项会将此键写入用户设置。

axScreenReader

渲染适合屏幕阅读器的输出：不带装饰性边框或动画的纯文本。屏幕阅读器模式使用经典渲染器，因此在该模式启用时 tui 设置无效；附加的后台会话仍以全屏方式渲染。

• 作用域：User or managed。您也可以在通过 --settings 传入的文件中设置此键。Claude Code 会忽略项目设置和本地设置中的此键，因此无论是仓库还是您自己的 .claude/settings.local.json 都无法开启或关闭屏幕阅读器模式。
• 类型：布尔值
  • true：Claude Code 使用经典渲染器，渲染不带装饰性边框或动画的纯文本
  • false：Claude Code 正常渲染
• 默认值：未设置，因此屏幕阅读器模式关闭
• 单会话覆盖：--ax-screen-reader 优先于 CLAUDE_AX_SCREEN_READER，两者在单个会话中均优先于此键

{
  "axScreenReader": true
}

bashEditDiffEnabled

选择 Claude Code 是否记录 Bash 命令运行期间 Git 仓库中哪些文件发生了更改。记录时，您会在命令执行后于终端中看到这些文件的 diff，并且您的 PostToolUse Bash hook 会收到已更改文件列表。

列出的文件不一定是该命令更改的。在命令运行期间由其他程序或其他 Bash 调用所做的更改也可能出现在其中。

将此键设置为 true 可在所有权限模式下记录这些文件。需要 Claude Code v2.1.269 或更高版本。

• 作用域：User or managed。true 仅在来自用户设置、通过 --settings 传入的 JSON 或托管设置时生效，因此仓库的 .claude/settings.json 或 .claude/settings.local.json 中的 true 无法开启记录。但这两个仓库文件中的 false 仍会关闭记录，除非某个优先级更高的文件设置为 true。
• 类型：布尔值
• 默认值：未设置，因此 Claude Code 在自动模式和 bypassPermissions 模式下，当其指示 Claude 通过 Bash 编辑文件时记录更改
• 单会话覆盖：CLAUDE_CODE_BASH_EDIT_DIFF 在单个会话中优先于此键

{
  "bashEditDiffEnabled": true
}

companyAnnouncements

在启动时向用户显示您组织的公告。当您列出多条公告时，Claude Code 会为每个会话随机选择一条；在用户首次启动时则显示第一条。

• 作用域：Any file
• 类型：字符串数组
• 默认值：未设置，因此不显示公告

{
  "companyAnnouncements": [
    "Welcome to Acme Corp! Review our code guidelines at docs.example.com"
  ]
}

defaultShell

选择由 Bash 还是 PowerShell 来运行您在输入框中使用 ! 前缀键入的 shell 命令，即 Claude Code 直接运行并添加到会话中的命令。

"powershell" 仅在 PowerShell 工具开启时有效。在未安装 Git Bash 的 Windows 上，该工具默认开启；在安装了 Git Bash 的 Windows 上，对于 claude.ai 和 Console 账户，该工具也默认开启。在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 会话中，以及在 macOS、Linux 和 WSL 上，设置 CLAUDE_CODE_USE_POWERSHELL_TOOL=1 可开启该工具。将该变量设置为 0 可关闭该工具。

• 作用域：Any file
• 类型：字符串，取值为以下之一：
  • "bash"：Claude Code 在 Bash 中运行您的 ! 命令
  • "powershell"：Claude Code 在 PowerShell 中运行您的 ! 命令
• 默认值："bash"；在 Windows 上 Bash 不可用时为 "powershell"

{
  "defaultShell": "powershell"
}

如果您指定的 shell 不可用，Claude Code 会使用另一个：当 PowerShell 工具关闭时，"powershell" 回退到 Bash；当未安装 Bash 时，"bash" 回退到 PowerShell。

dialogExpiry

为 Claude Code 转发到远程客户端（例如 Remote Control 或 SDK 主机）的对话框，以及被暂留的跨会话消息的批准对话框设置截止时间。在 Claude Code v2.1.236 或更高版本中，同一截止时间也适用于在可能无人值守终端的会话中出现的会话中途 Fable 使用额度同意提示。如果在截止时间之前未收到答复，Claude Code 会取消该对话框，并按其不执行操作的默认行为继续。需要 Claude Code v2.1.224 或更高版本。

• 作用域：User or managed
• 类型：字符串，取值为 "60s"、"5m"、"10m" 或 "never"（禁用截止时间）之一
• 默认值："5m"
• 单会话覆盖：CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS 在单个会话中优先于此键

{
  "dialogExpiry": "10m"
}

权限提示和 AskUserQuestion 问题使用各自的流程，不受此截止时间约束。在 /config 中显示为 Dialog expiry，该选项会将此键写入用户设置；该行需要 Claude Code v2.1.232 或更高版本，并且当托管设置或 --settings 标志设置了此键时，Claude Code 会隐藏该行。

editorMode

选择输入框的按键绑定模式。

• 作用域：Any file
• 类型：字符串，取值为以下之一：
  • "normal"：输入框中的标准按键绑定
  • "vim"：带有 NORMAL、INSERT 和 VISUAL 模式的 vim 风格编辑
• 默认值："normal"

{
  "editorMode": "vim"
}

在 /config 中显示为 Editor mode，该选项会将此键写入用户设置。

emojiCompletionEnabled

在输入框中键入 : 加短代码时显示 emoji 建议，并将完整的短代码（例如 :heart:）替换为对应的 emoji。设置为 false 可同时关闭这两项功能。

• 作用域：Any file
• 类型：布尔值
  • true：Claude Code 在 : 之后显示 emoji 建议，并将完整的短代码替换为对应的 emoji
  • false：Claude Code 既不建议 emoji，也不替换短代码
• 默认值：true

{
  "emojiCompletionEnabled": false
}

请参阅 Emoji 短代码。

fileSuggestion

运行您自己的命令来提供 @ 文件路径自动补全，以替代内置的文件建议。内置建议使用快速文件系统遍历；对于大型 monorepo，使用项目特定的索引（例如预构建的文件索引）可能效果更好。

• 作用域：Any file。在状态栏和文件建议限制下，Claude Code 会关闭该命令或仅运行托管值，并在不发出警告的情况下跳过您的命令。
• 类型：对象，包含 type（始终为 "command"）和 command（要运行的 shell 命令）
• 默认值：未设置，因此 Claude Code 使用内置的文件建议

{
  "fileSuggestion": {
    "type": "command",
    "command": "~/.claude/file-suggestion.sh"
  }
}

保存后，在输入框中键入 @ 并跟上部分路径：建议将来自您命令的输出。

命令输入和输出

Claude Code 使用与 hook 相同的环境变量（包括 CLAUDE_PROJECT_DIR）运行该命令，并在五秒后停止等待。该命令通过 stdin 接收 JSON，其中 query 字段包含您目前已键入的内容：

{"query": "src/comp"}

将以换行符分隔的文件路径输出到 stdout。Claude Code 最多显示 15 个：

src/components/Button.tsx
src/components/Modal.tsx
src/components/Form.tsx

以下脚本读取查询并将其传递给仓库文件索引：

#!/bin/bash
query=$(cat | jq -r '.query')
# Replace your-repo-file-index with your own file search command
your-repo-file-index --query "$query" | head -20

footerLinksRegexes

当正则表达式匹配轮次输出（包括文件内容和获取的页面在内的工具结果，以及 Claude 自己的回复）时，在输入框下方的页脚中渲染额外的可点击徽章。可用它将项目 CLI（例如审查工具和问题跟踪器）打印的 ID 转换为会话中的链接。

• 作用域：User or managed
• 类型：对象数组，每个对象包含设置为 "regex" 的 type、一个 pattern 正则表达式、一个 url 模板以及可选的 label；url 和 label 中的 {name} 占位符由 pattern 中的命名捕获组填充
• 默认值：未设置，因此不渲染徽章

此示例匹配 PROJ-1234 之类的问题键，并根据捕获的键构建每个链接：

{
  "footerLinksRegexes": [
    {
      "type": "regex",
      "pattern": "\\b(?<key>PROJ-\\d+)\\b",
      "url": "https://issues.example.com/browse/{key}",
      "label": "{key}"
    }
  ]
}

配置此项后，当 PROJ-1234 出现在工具结果或 Claude 的回复中时，页脚中会出现一个链接到 https://issues.example.com/browse/PROJ-1234 的 PROJ-1234 徽章。

徽章限制

每个条目的 URL、标签和徽章数量受以下限制：

轮次完成时，Claude Code 会在主线程上将每个条目的 pattern 正则表达式与轮次输出进行匹配，因此缓慢的正则表达式会阻塞 UI 直至完成。诸如 (a+)+$ 之类的嵌套量词在某些输入下可能耗费指数级时间并冻结会话，因此请保持每个 pattern 为线性，并避免嵌套 + 或 *。

配置了自定义状态栏时，页脚徽章会与其一同渲染；两者互不替代。状态栏适用于由脚本驱动、根据会话数据计算自身内容的行，页脚徽章则适用于无需脚本即可将对话中的 ID 转换为链接。

keybindingFlavor

[!WARNING]

自 v2.1.261 起已弃用，且不再生效。输入框的单词编辑按键始终遵循 readline 约定，与 Bash 中相同。Claude Code 仍然接受 keybindingFlavor，因此设置了此项的设置文件仍然有效。

在 v2.1.238 到 v2.1.260 中，将其设置为 "readline" 会使 Ctrl+W 向后删除到上一个空白字符，而不仅仅是上一个单词。

• 作用域：Any file
• 类型：字符串，"classic" 或 "readline"
• 默认值：未设置

maxProseWidth

限制 Claude 回复中正文的宽度，使其在宽终端中保持易读。段落、标题、列表和引用块会在此列数内换行，而表格和代码块保持完整的终端宽度。需要 Claude Code v2.1.282 或更高版本。

• 作用域：Any file
• 类型：终端列数，整数，最小值为 40。Claude Code 会忽略任何其他值
• 默认值：未设置，因此正文在终端边缘换行

{
  "maxProseWidth": 80
}

prefersReducedMotion

减少或关闭界面动画，例如加载指示器、闪光和闪烁效果。在 /config 中显示为 Reduce motion。

• 作用域：Any file
• 类型：布尔值
  • true：Claude Code 减少或关闭界面动画，例如加载指示器、闪光和闪烁效果
  • false：与未设置相同；Claude Code 显示其动画
• 默认值：false

{
  "prefersReducedMotion": true
}

promptSuggestionEnabled

显示或隐藏提示词建议，即出现在输入框中的灰色预测内容。将其设置为 false，或在 /config 中关闭 Prompt suggestions，即可隐藏它们。

• 作用域：Any file
• 类型：布尔值
  • true：您会在输入框中看到提示词建议
  • false：Claude Code 隐藏提示词建议
• 默认值：true
• 单会话覆盖：CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION 在单个会话中优先于此键

{
  "promptSuggestionEnabled": false
}

提示词建议需要开启了遥测的 claude.ai 或 Console 账户。在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，或者在遥测已关闭（例如通过 DISABLE_TELEMETRY）的情况下，此键无效，只有 CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=1 能开启提示词建议。

respectGitignore

控制 @ 文件选择器是否排除匹配 .gitignore 模式的文件。在 /config 中显示为 Respect .gitignore in file picker。

• 作用域：Any file。当没有任何设置文件设置此项时，Claude Code 会回退到 ~/.claude.json 中的 respectGitignore，该值由 /config 开关写入。
• 类型：布尔值
  • true：@ 文件选择器排除匹配 .gitignore 模式的文件
  • false：@ 文件选择器包含匹配 .gitignore 模式的文件
• 默认值：true

{
  "respectGitignore": false
}

respondToBashCommands

选择在您于输入框中使用 ! 前缀运行 shell 命令后，Claude 是否进行回复。默认情况下，Claude Code 会将命令的输出添加到对话中，并由 Claude 对其进行回复。将此键设置为 false 可将输出添加到上下文而不回复，这样您就可以运行多个命令，然后一起询问。

• 作用域：Any file
• 类型：布尔值
  • true：Claude Code 将命令的输出添加到对话中，并由 Claude 对其进行回复
  • false：Claude Code 将输出添加到上下文而不回复
• 默认值：true

{
  "respondToBashCommands": false
}

请参阅使用 ! 前缀的 shell 模式。

showClearContextOnPlanAccept

当 Claude 在计划模式中完成计划时，会显示一个批准菜单。制定计划可能会占用大量上下文，因此此键会在该菜单中添加第一个选项 Yes, clear context and …，用于批准计划、清除对话上下文，并仅依据计划开始实施。标签的其余部分会说明会话将继续使用的权限模式，并显示计划占用了多少上下文。

• 作用域：Any file
• 类型：布尔值
  • true：计划批准菜单获得第一个选项 Yes, clear context and …，用于批准计划并清除对话上下文
  • false：计划批准菜单不显示清除上下文选项
• 默认值：false

{
  "showClearContextOnPlanAccept": true
}

showTurnDuration

显示或隐藏每次回复后的轮次耗时消息，例如 "Cooked for 1m 6s · done 6:05 PM"。"done" 后面的时钟显示轮次完成的时间；timeFormat 和 timeZone 控制其格式和时区。在 /config 中显示为 Show turn duration。

• 作用域：Any file。当没有任何设置文件设置此项时，旧版本写入 ~/.claude.json 的值会生效。
• 类型：布尔值
  • true：您会在每次回复后看到轮次耗时消息
  • false：Claude Code 隐藏轮次耗时消息
• 默认值：true

{
  "showTurnDuration": false
}

spellcheck

在您键入时，使用您安装的拼写检查器为输入框中的拼写错误单词添加下划线。Claude Code 仅检查输入框中的文本。键入时检查拼写介绍了如何安装 aspell、hunspell 或 ispell，以及检查器的检查范围。需要 Claude Code v2.1.235 或更高版本。

• 作用域：User or managed。来自设置了此项的最高层级的整个块作为一个整体生效。
• 类型：对象，包含 enabled（布尔值）、checker（"aspell"、"hunspell"、"ispell" 或 "auto"）、language（字符串，作为词典名称传递给检查器）和 color（字符串，终端颜色名称、#rrggbb、rgb(r,g,b)、ansi256(n) 或 ansi:<name>）
• 默认值：未设置，因此拼写检查关闭；checker 默认为 "auto"，即在 PATH 中找到的三者中的第一个；language 默认为检查器自己的词典；color 默认为主题的错误颜色

{
  "spellcheck": { "enabled": true, "language": "en_GB" }
}

spinnerTipsEnabled

在 Claude 工作时，加载指示器行会轮流显示关于 Claude Code 功能的简短提示，例如 "Use Plan Mode to prepare for a complex request before making changes. Press Shift+Tab twice to enable."。将此键设置为 false 可隐藏这些提示。在 /config 中显示为 Show tips。

• 作用域：Any file
• 类型：布尔值
  • true：Claude 工作时，您会在加载指示器中看到提示
  • false：Claude Code 隐藏加载指示器提示
• 默认值：true

{
  "spinnerTipsEnabled": false
}

spinnerTipsOverride

向 Claude 工作时 Claude Code 显示的加载指示器提示中添加您自己的提示，或用您的提示替换内置提示。Claude Code 会将您的提示与内置提示放在同一轮换中。

如果您将 spinnerTipsEnabled 设置为 false，Claude Code 会隐藏所有提示，包括您的提示。

• 作用域：Any file。Claude Code 接受来自用户设置、--settings 标志和托管设置的提示对象、tipsFile、label 和 excludeDefault；从项目和本地设置中仅读取纯字符串提示。
• 类型：对象，包含 tips、tipsFile、label 和 excludeDefault 字段，均为可选
• 默认值：未设置，因此 Claude Code 仅显示内置提示

提示对象、tipsFile、label，以及作用域说明中项目和本地设置仅提供纯字符串的规则，需要 Claude Code v2.1.247 或更高版本。

每个 tips 条目是一个纯字符串或包含以下字段的对象：

Claude Code 将纯字符串视为使用上述默认值和基于位置的 id 的提示，因此重新排列列表时其显示历史会重置。为提示指定 id 可在编辑时保留其历史。

Claude Code 在 tips 和 tipsFile 中总共最多读取 200 条提示，并会丢弃无效条目并输出调试警告，而不是拒绝整个设置文件。

使用其余字段来指定提示文件、设置前缀以及隐藏内置提示：

• tipsFile：指向本地 JSON 文件的绝对路径或 ~/ 路径，该文件包含由相同条目组成的数组，或包含 tips 数组的对象，最大 256 KB。Claude Code 每个进程只读取该文件一次，因此会在下次启动时加载您的修改。您不能通过服务器托管设置设置此项；请在那里部署内联的 tips，或在磁盘上的 managed-settings.json 中部署该路径。
• label：Claude Code 在来自用户设置、--settings 和托管设置的提示前显示的前缀，最多 40 个字符。默认为 Tip，与内置提示的前缀相同，来自项目和本地设置的提示始终使用该默认前缀。
• excludeDefault：设置为 true 可隐藏内置提示，仅显示您的提示。当 Claude Code 无法加载您的任何提示时（例如 tipsFile 不存在或所有条目均无效），它会保留内置轮换，而不是显示空的加载指示器。

当多个设置文件设置了此键时，Claude Code 会显示所有这些文件中的提示，并从托管设置、--settings 标志和用户设置中设置了相应字段且优先级最高的那个获取 tipsFile、label 和 excludeDefault。

此示例位于您的用户设置中，在 Acme tip 前缀下向轮换中添加一个纯字符串提示和一个对象提示：

{
  "spinnerTipsOverride": {
    "label": "Acme tip",
    "tips": [
      "Run /review before opening a PR",
      {
        "id": "gateway-errors",
        "text": "Seeing 5xx errors? Check the gateway status page first",
        "cooldownSessions": 5,
        "priority": 2
      }
    ]
  }
}

示例中的每个字段都会改变 Claude Code 显示提示的一个方面：

• label：Claude Code 将两个提示都显示为 Acme tip: ...，而不是 Tip: ...。
• 纯字符串：Claude Code 为其使用默认值，因此它可能在紧接着的下一个会话中再次出现。
• id：Claude Code 以 gateway-errors 记录第二个提示的显示历史，因此在您添加或重新排列提示后，其冷却期仍然适用。
• cooldownSessions：Claude Code 显示 gateway-errors 提示后，要等到五个会话之后才会再次显示该提示。
• priority：当 gateway-errors 提示与另一个提示未显示的会话数相同时（例如两者都尚未显示过），Claude Code 会先显示 gateway-errors。纯字符串使用默认优先级 0。

Claude 工作时，Claude Code 会在加载指示器中以您的前缀显示您的提示，例如 Acme tip: Run /review before opening a PR。

spinnerVerbs

轮次进行期间，加载指示器会轮流显示动词，例如 "Accomplishing"、"Architecting" 或 "Baking"。使用此键可将您自己的动词添加到该轮换中，或用您的动词替换内置列表。

• 作用域：Any file
• 类型：对象，包含字符串数组 verbs 和 mode，mode 取值为以下之一：
  • "append"：Claude Code 将您的动词添加到内置集合中
  • "replace"：Claude Code 仅显示您的动词
• 默认值：未设置，因此 Claude Code 使用内置动词

此示例向内置集合中添加两个动词：

{
  "spinnerVerbs": {
    "mode": "append",
    "verbs": ["Pondering", "Crafting"]
  }
}

在 "replace" 模式下，如果 verbs 数组为空，Claude Code 会保留内置动词。

statusLine

运行您自己的命令，在输入框下方渲染状态栏，显示模型、费用或 git 分支等上下文信息。可选字段用于调整间距、添加定期重新运行，以及在您的脚本自行渲染 vim.mode 时隐藏内置的 vim 模式指示器。

• 作用域：Any file。当 allowManagedHooksOnly 开启，或在托管设置之外设置了 disableAllHooks 时，仅运行托管设置中的值。
• 类型：对象，包含设置为 "command" 的 type 和 command 字符串，以及可选的 padding（字符数）、refreshInterval（秒数，最小值为 1）和 hideVimModeIndicator（布尔值）
• 默认值：未设置，因此不显示状态栏

此示例打印模型名称和上下文使用情况，并添加两个字符的水平间距：

{
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'",
    "padding": 2
  }
}

该示例需要安装 jq 并在 shell 中运行。有关 PowerShell 和 Git Bash 的等效写法，请参阅 Windows 配置；有关完整设置，请参阅手动配置状态栏。

subagentStatusLine

当 Claude 运行子代理时，Claude Code 会在输入框下方的任务显示区域中列出它们，每个子代理占一行，显示 name · description · token count。此键允许您运行自己的命令来改写这些行，例如以百分比显示每个子代理的上下文使用情况。每次刷新时，Claude Code 会通过 stdin 发送一个 JSON 对象来表示可见的行，其中 tasks 数组包含每个子代理的 id、name、status、model、tokenCount 等信息；对于您以 {"id", "content"} 行形式写回的每个 id，Claude Code 会替换相应的行。您未写回的行保持默认渲染。

• 作用域：Any file。当 allowManagedHooksOnly 开启，或在托管设置之外设置了 disableAllHooks 时，仅运行托管设置中的值。
• 类型：对象，包含设置为 "command" 的 type 和 command 字符串
• 默认值：未设置，因此 Claude Code 渲染默认行

{
  "subagentStatusLine": {
    "type": "command",
    "command": "jq -c '.tasks[] | {id, content: \"\\(.name): \\(.tokenCount) tokens\"}'"
  }
}

请参阅子代理状态栏。

syntaxHighlightingDisabled

Claude Code 使用其内置的高亮器，按语言为其在终端中显示的 diff、代码块和文件预览中的代码着色。将此键设置为 true 可改为以纯文本显示，例如当颜色与您的终端主题冲突或拖慢屏幕阅读器时。

• 作用域：Any file
• 类型：布尔值
  • true：Claude Code 关闭 diff、代码块和文件预览中的语法高亮
  • false：Claude Code 进行语法高亮
• 默认值：false

{
  "syntaxHighlightingDisabled": true
}

terminalProgressBarEnabled

某些终端可以在标签页或任务栏上为其中运行的程序显示进度指示器。Claude 工作时，Claude Code 会向终端报告进行中状态，因此您可以从其他标签页或窗口查看会话是否仍在忙碌。当后台子代理或动态工作流仍在运行时，指示器在轮次结束后仍保持可见，并在会话空闲后清除。

Claude Code 仅在支持该指示器的终端中报告：ConEmu、Ghostty 1.2.0 或更高版本，以及 iTerm2 3.6.6 或更高版本。将此键设置为 false 可阻止 Claude Code 报告。在 /config 中显示为 Terminal progress bar。

• 作用域：Any file。当没有任何设置文件设置此项时，旧版本写入 ~/.claude.json 的值会生效。
• 类型：布尔值
  • true：您会在支持的终端中看到终端进度条
  • false：Claude Code 隐藏终端进度条
• 默认值：true

{
  "terminalProgressBarEnabled": false
}

terminalTitleFromRename

Claude Code 会设置您的终端标签页标题。默认情况下，它使用根据对话生成的标题；一旦您使用 /rename 或 --name 为会话命名，标签页就会改为显示该名称。将此键设置为 false 可在您为会话命名后仍在标签页上保留生成的标题。名称本身仍然生效，因此 /resume <name> 和会话选择器都能找到它。

• 作用域：Any file
• 类型：布尔值
  • true：终端标签页标题显示您设置的会话名称
  • false：标签页保留 Claude Code 根据您的对话生成的标题
• 默认值：true

{
  "terminalTitleFromRename": false
}

如需完全阻止 Claude Code 更新终端标题，请改为将 CLAUDE_CODE_DISABLE_TERMINAL_TITLE 设置为 1。

theme

选择界面的颜色主题。在 /config 中显示为 Theme。

• 作用域：Any file。当没有任何设置文件设置此项时，旧版本写入 ~/.claude.json 的值会生效。
• 类型：字符串，取值为以下之一：
  • "auto"：匹配终端的浅色或深色背景
  • "dark"：深色主题
  • "light"：浅色主题
  • "dark-daltonized"：使用色盲友好颜色的深色主题
  • "light-daltonized"：使用色盲友好颜色的浅色主题
  • "dark-ansi"：仅使用终端 ANSI 调色板的深色主题
  • "light-ansi"：仅使用终端 ANSI 调色板的浅色主题
  • "custom:<slug>" 或 "custom:<plugin-name>:<slug>"：来自 ~/.claude/themes/ 或插件的自定义主题
• 默认值："dark"

{
  "theme": "light-daltonized"
}

请参阅创建自定义主题。

timeFormat

选择 Claude Code 在界面中显示时间的格式，例如每条轮次耗时消息末尾的 done 6:05 PM，以及会话记录查看器中的时间戳。要选择预设，请运行 /config 并设置 Time format。需要 Claude Code v2.1.257 或更高版本。

• 作用域：Any file
• 类型：字符串，取值为以下之一：
  • "auto"：与未设置相同；每个时间保持其内置格式，轮次耗时消息中的时间遵循您的区域设置
  • "12-hour"：12 小时制
  • "24-hour"：24 小时制
  • "24-hour-utc"：UTC 24 小时制，分钟后带有 Z，例如 18:05Z；对于此预设，Claude Code 会忽略 timeZone
  • strftime 模式，例如 "%H:%M"：Claude Code 使用该模式写入每个时间。任何包含 % 的值都是模式，预设以外的任何其他值都视为 "auto"
• 默认值："auto"

{
  "timeFormat": "24-hour"
}

/config 仅提供预设，因此如需使用 strftime 模式，请将此键添加到设置文件中。此示例将每个时间显示为两位数的 24 小时制：

{
  "timeFormat": "%H:%M"
}

之后，轮次耗时消息和会话记录查看器会显示 18:05 之类的时间。在会话记录查看器中，该模式就是完整的时间戳，因此如果您希望其中显示日期，请添加日期指令。此示例在时钟前加上日期：

{
  "timeFormat": "%Y-%m-%d %H:%M"
}

之后，这些位置会显示 2026-09-01 18:05 之类的时间。

timeZone

以系统时区以外的时区显示界面中的时间。将其设置为 IANA 时区名称，例如 "UTC" 或 "Europe/Dublin"。由 timeFormat 控制的时间随后会以此时区显示。如果 timeFormat 为 "24-hour-utc"，时间保持为 UTC，Claude Code 会忽略此键。/config 中没有此键对应的行，因此请在设置文件中设置。需要 Claude Code v2.1.257 或更高版本。

• 作用域：Any file
• 类型：字符串，IANA 时区名称。当 Claude Code 无法识别该名称时，会使用您的系统时区
• 默认值：未设置，因此时间以您的系统时区显示

{
  "timeZone": "Europe/Dublin"
}

tui

选择终端 UI 渲染器。使用 "fullscreen" 选择带有虚拟化回滚的无闪烁备用屏幕渲染器，或使用 "default" 选择经典的主屏幕渲染器。运行 /tui fullscreen 或 /tui default 会为您写入此键。

• 作用域：Any file
• 类型：字符串，取值为以下之一：
  • "default"：经典的主屏幕渲染器
  • "fullscreen"：带有虚拟化回滚的无闪烁备用屏幕渲染器
• 默认值：未设置，因此 Claude Code 为您选择渲染器
• 单会话覆盖：CLAUDE_CODE_NO_FLICKER 和 CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN 在单个会话中优先于此键：CLAUDE_CODE_NO_FLICKER=1 开启全屏，CLAUDE_CODE_NO_FLICKER=0 或 CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1 关闭全屏；两者同时设置时，Claude Code 关闭全屏