所有设置

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

返回索引

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

设置索引

下面的每个键都链接到其条目。范围列出了文件，其中可以使用该键：User 是 ~/.claude/settings.json，Project 是 .claude/settings.json，Local 是 .claude/settings.local.json，Managed 是您的组织部署的内容。Any file 表示所有四个文件，Global config 表示 ~/.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）上，此键不起作用。"fable" 需要 Fable 访问权限。

alwaysThinkingEnabled

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

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

• 作用域：Any file
• 类型：布尔值
  • 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。请参阅限制模型选择。

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 条目仅允许其所指定的版本（包括该版本带日期的 ID），因此 "claude-opus-5" 允许 Opus 5，但不允许 claude-opus-5-5。诸如 "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's Agent Platform。

• 作用域：Any file
• 类型：布尔值
  • 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，再次运行以关闭快速模式会移除该键。快速模式仅在 Opus 5.5、Opus 5 和 Opus 4.8 上运行：从其他模型开启它会将您切换到 Opus，而切换到不支持的模型会将其关闭。请参阅在快速模式开启时切换模型。

• 作用域：Any file
• 类型：布尔值
  • true：Claude Code 在可用的会话中开启快速模式
  • false：快速模式保持关闭
• 默认值：未设置，因此快速模式处于关闭状态
• 单会话覆盖：CLAUDE_CODE_DISABLE_FAST_MODE 会在单个会话中关闭快速模式，且此键无法将其重新打开

{
  "fastMode": true
}

fastModePerSessionOptIn

通常，运行 /fast 会将 fastMode 保存到用户的用户设置中，因此之后的每个会话开始时快速模式都会开启。将此键设置为 true 可阻止这种情况：已保存的 fastMode: true 不再在会话开始时开启快速模式，每个人都必须在需要它的每个会话中运行 /fast。Claude Code 会保留其文件中的 fastMode 键，因此关闭此键即可恢复原有行为。

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

• 作用域：Any file
• 类型：布尔值
  • true：已保存的 fastMode: true 不再在会话开始时开启快速模式，因此每个人需要在想要使用它的每个会话中运行 /fast；除非托管设置设置了此键，否则通过 --settings 传入的 fastMode: true 仍对该会话有效
  • false：已保存的 fastMode: true 会在之后每个会话开始时开启快速模式
• 默认值：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's Agent Platform 和 Microsoft Foundry。需要 Claude Code v2.1.267 或更高版本。

• 作用域：Any file。将其部署在托管设置中，可在组织范围内强制执行。当多个作用域设置了上限时，以最低的为准，因此在一个作用域中设置的上限无法在另一个作用域中提高
• 类型：字符串，为 "low"、"medium"、"high"、"xhigh" 或 "max" 之一。"max" 值表示不设上限
• 默认值：未设置，因此不应用任何上限
• 按模型上限：将 maxEffortLevel 添加到模型的 modelSettings 条目中。该条目仅在同时设置了二者的设置来源（例如您的用户设置或某个托管来源）中，针对该模型替代此键。在此处设置 "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's 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's Agent Platform、Microsoft Foundry 或 LLM 网关的提供商格式 ID。需要 Claude Code v2.1.242 或更高版本。

• 作用域：User or managed。Claude Code 从托管设置、--settings 和用户设置中读取此键，并忽略项目和本地设置中的此键，因此您克隆的仓库无法重新标注选择器。这三者中设置了此键的优先级最高者提供整个模型列表，Claude Code 永远不会合并来自两个来源的模型列表。
• 类型：包含行数组 options 和可选布尔值 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 版本更新的条目上，将其设置为您的 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
• 类型：布尔值
  • 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。
• 类型：布尔值
  • 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
• 类型：布尔值
  • 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 清单声明的插件

来自托管设置的 skill 和随附 skill 保留其 allowed-tools。skill 的 disallowed-tools 仍然适用。有关 Claude Code 忽略该字段时开发人员会看到什么，请参阅仅应用托管权限规则时。

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

{
  "allowManagedPermissionRulesOnly": true
}

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

autoMode

添加您自己的规则到自动模式分类器阻止和允许的内容。使用它告诉分类器您的组织信任哪些仓库、存储桶和域，以便它停止阻止常规内部操作。分类器附带内置允许和拒绝规则。在数组中包含字面字符串 "$defaults" 以在该位置保留这些内置规则并在其周围添加您的规则；省略它以用您的规则替换它们。

• 作用域: User or managed
• 类型: 包含 environment、allow、soft_deny 和 hard_deny 散文规则数组的对象，加上 classifyAllShell 布尔值
• 默认值: 未设置，因此分类器仅使用其内置规则

此示例保留内置的 soft_deny 规则（通过 "$defaults"），并添加一个阻止 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 的任何地方读取。
• 类型: 布尔值
  • 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、defaultMode、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 中显示为在计划期间使用自动模式。

• 作用域: User, local, or managed。存储库无法为您关闭它。
• 类型: 布尔值
  • true: 与未设置相同；当自动模式可用时，分类器在规划期间审查每个 shell 命令而不是提示您，除了关键路径删除。这些文件中的任何 false 仍然会关闭它
  • 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/ 下的 CLAUDE.md 内存文件。需要 Claude Code v2.1.257 或更高版本。

Claude Code 不以相同方式拒绝 shell 命令：

• 没有模式自动批准的操作涵盖读取此类路径的 shell 命令何时提示您
• 块下的沙箱命令涵盖沙箱命令可以读取的内容

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

Claude Code 还在您选择在自动模式的提示中阻止此类读取（在第一次在工作目录之外读取之前）时在此处写入 true。

• 作用域: Any file。任何文件中的 true 都适用，因此存储库可以为自己打开块，但无法解除您的块。
• 类型: 布尔值
  • 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 在会话中创建的 worktrees、会话临时目录以及命令需要的 ~/.claude 部分，如技能和插件。当块生效时，来自存储库设置的 allowRead 和 allowWrite 条目不计。

当会话的工作目录是链接的 git worktree（包括 Claude Code 在会话中途进入的）时，存储库的公共 .git 目录对沙箱命令保持可读和可写，因此 git 在那里保持工作。

在这些情况下，块不会到达沙箱命令，而 Claude 的文件工具继续强制执行它：

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

在块下，Claude Code 重新打开您的全局 git 配置文件到沙箱命令，以便 git 保持您的身份和设置：

• ~/.gitconfig
• $XDG_CONFIG_HOME/git 下的 config、ignore 和 attributes 文件，默认为 ~/.config/git
• 您的全局 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.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.disableBypassPermissionsMode

防止任何人进入 bypassPermissions 模式。Claude Code 随后拒绝 --dangerously-skip-permissions 标志，并忽略代理定义的 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。存储库无法为您设置它。
• 类型: 布尔值
  • true: Claude Code 跳过通知
  • false: 与未设置相同；通知出现一次，除非这些文件中的另一个设置 true
• 默认值: 未设置，因此通知出现一次

{
  "skipAutoPermissionPrompt": true
}

skipDangerousModePermissionPrompt

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

• 作用域: User, local, or managed。不受信任的存储库无法为您跳过对话框。
• 类型: 布尔值
  • true: Claude Code 跳过会话进入 bypassPermissions 模式之前的确认对话框
  • false: 与未设置相同；对话框出现，除非这些文件中的另一个设置 true
• 默认值: 未设置，因此对话框出现

{
  "skipDangerousModePermissionPrompt": true
}

Sandbox 设置

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

sandbox

使用 sandboxing 将 Claude 运行的 Bash 命令与您的文件系统和网络隔离。使用 enabled 打开沙箱，然后使用 filesystem、network 和 credentials 子对象缩小或扩大沙箱命令可以接触的内容。沙箱在 macOS、Linux 和 WSL2 上运行。

• Scope: Any file
• Type: 对象，包含 enabled、failIfUnavailable、autoAllowBashIfSandboxed、excludedCommands、allowUnsandboxedCommands、enableWeakerNestedSandbox、enableWeakerNetworkIsolation、allowAppleEvents、bwrapPath、socatPath、ignoreViolations 和 ripgrep，以及 filesystem、network 和 credentials 对象
• Default: 未设置，因此 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 在会话加载的各个设置作用域中合并数组键，因此开发人员可以追加条目；请参阅 Keep developers from widening the policy 了解仅限托管的锁。要为组织强制执行沙箱，请参阅 Enforce sandboxing with managed settings。

sandbox.enabled

为 Bash 命令打开 sandboxing。当您在 /sandbox 面板中选择一个模式时，Claude Code 会将此键写入当前项目的 .claude/settings.local.json；在 ~/.claude/settings.json 中设置它以对每个项目进行沙箱处理。

• Scope: Any file，项目和本地设置受到限制
• Type: 布尔值
  • true: Claude Code 对 Bash 命令进行沙箱处理
  • false: Bash 命令在没有沙箱的情况下运行
• Default: false

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

在 Linux 和 WSL2 上，沙箱需要 bubblewrap 和 socat；请参阅 Set up Linux and WSL2。当沙箱无法启动时，除非您同时设置了 failIfUnavailable，否则 Claude Code 会在没有沙箱的情况下运行命令。

sandbox.failIfUnavailable

当 sandbox.enabled 为 true 但沙箱无法启动时（因为缺少依赖项或不支持该平台），使 Claude Code 在启动时以错误退出。没有此键时，Claude Code 会在没有沙箱的情况下运行命令。将沙箱作为安全关卡强制要求的托管部署可以使用此设置。

在沙箱不支持的平台上，启用此键时 Claude Code 不会启动。请参阅 Enforce sandboxing with managed settings。

• Scope: Any file，项目和本地设置受到限制
• Type: 布尔值
  • true: 当 sandbox.enabled 为 true 但沙箱无法启动时，Claude Code 在启动时以错误退出
  • false: 当沙箱无法启动时，Claude Code 在没有沙箱的情况下运行命令
• Default: false

这使每台托管机器对命令进行沙箱处理或拒绝启动：

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

请参阅 Enforce sandboxing with managed settings。

sandbox.autoAllowBashIfSandboxed

让 Claude Code 运行沙箱化的 Bash 命令而无需权限提示。无法在沙箱中运行的命令仍会通过常规权限流程，deny 规则和内容范围的 ask 规则（如 Bash(git push *) ）仍然适用；对于沙箱化命令，裸 Bash ask 规则被跳过。将其设置为 false 以也通过常规权限流程发送沙箱化命令，/sandbox Mode 选项卡称之为常规权限模式。

• Scope: Any file
• Type: 布尔值
  • true: Claude Code 运行沙箱化的 Bash 命令而无需权限提示，Auto-allow mode 所述的情况除外；CLAUDE_CODE_SUBPROCESS_ENV_SCRUB 关闭自动允许
  • false: 沙箱化命令通过常规权限流程，因此您的允许规则和权限模式决定。/sandbox Mode 选项卡称之为常规权限模式
• Default: true

这保持沙箱打开并通过常规权限流程发送沙箱化命令：

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

请参阅 Auto-allow mode 了解自动允许模式仍会提示什么以及它在计划模式中的行为。

sandbox.excludedCommands

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

您的条目仅当它们覆盖复合命令中的每个命令时才将 Bash 调用从沙箱中取出，某些调用形式即使这样也保持沙箱化。单独的 docker * 条目不会将 npm ci && docker build . 从沙箱中取出。

• Scope: Any file，项目和本地设置受到限制
• Type: 命令模式数组
• Default: 未设置，因此没有命令被排除

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

Claude Code 在具有以下形式之一时保持 Bash 调用沙箱化，以及其他形式：

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

例如，cd build && docker compose up 在 docker * 条目下保持沙箱化，添加 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 会为其覆盖的开发人员打开严格沙箱模式。

• Scope: Any file，项目和本地设置受到一项限制
• Type: 布尔值
  • true: Claude 可以在沙箱阻止后使用 dangerouslyDisableSandbox 参数在沙箱外重试命令
  • false: Claude Code 忽略该参数，因此在沙箱运行期间，Claude 运行的命令都会进行沙箱处理，除非它们匹配 excludedCommands 条目
• Default: true

这为托管设置覆盖的每个人强制执行严格沙箱模式：

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

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

由谁批准未沙箱化的重试取决于您的权限模式和允许规则。请参阅 The unsandboxed retry escape hatch。

要查看您在 ! shell-mode prompt 处自己输入的命令何时以沙箱化方式运行，请参阅 strict sandbox mode。

sandbox.filesystem

控制沙箱化命令可以读取和写入的路径。默认情况下，它们可以写入工作目录、会话临时目录以及使用 --add-dir、/add-dir 或 permissions.additionalDirectories 添加的目录，并可以读取文件系统的其余部分，包括凭证文件。使用四个路径列表扩大或缩小范围，或使用 disabled 关闭文件系统层。请参阅 Filesystem isolation 了解默认边界。

• Scope: Any file
• Type: 对象，包含 allowWrite、denyWrite、denyRead 和 allowRead 数组，以及 allowManagedReadPathsOnly 和 disabled 布尔值
• Default: 未设置，因此应用默认读写边界

这让沙箱化命令写入构建目录和您的 kubeconfig，并隐藏您的 AWS 凭证文件：

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

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

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

Configure sandboxing 涵盖您使用 --setting-sources 排除的源。当您在会话期间编辑列表时，Claude Code applies the change to the running session。

Sandbox 路径前缀

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

绝对路径的 //path 前缀也有效。如果您使用单斜杠 /path 期望项目相对解析，请切换到 ./path。此语法与 Read and Edit permission rules 不同，后者使用 //path 表示绝对路径，/path 表示项目相对路径：沙箱文件系统路径使用标准约定，因此 /tmp/build 是绝对路径。

Claude Code 从目录路径中删除尾部斜杠，因此 ~/.aws 和 ~/.aws/ 匹配同一目录。在 v2.1.224 之前，Claude Code 将尾部斜杠传递给沙箱，Claude 仍然可以读取或写入使用一个尾部斜杠编写的 denyRead 或 denyWrite 条目下的路径。

Claude Code 也删除尾部 /**，因此 ~/build/** 和 ~/build 覆盖同一目录。通配符（如 * ）是否有效取决于条目所在的列表和平台：

• allowWrite 和 denyWrite: 在 macOS 上，通配符有效。在 Linux 和 WSL2 上，沙箱挂载具体路径，因此 Claude Code 在删除尾部 /** 后跳过包含 *、? 或 [ 的条目，该条目无效。Claude Code 将您的 Edit 权限规则中的路径添加到这些列表中，因此相同的限制适用于它们，/sandbox 的 Config 选项卡警告包含通配符的 Edit 和 Read 权限规则。
• denyRead 和 allowRead: 通配符在每个平台上都有效。在 Linux 和 WSL2 上，Claude Code 将读取条目扩展到它匹配的具体路径，对写入列表不执行此操作。

花括号在名称中按普通字符匹配，因此 ~/data/{keys,tokens} 覆盖的是一个字面名为 {keys,tokens} 的目录，而不是两个备选项。要覆盖 ~/data/keys 和 ~/data/tokens，请将每个路径作为单独的条目添加。

sandbox.filesystem.allowWrite

添加沙箱化命令可以写入的路径，超出工作目录、会话临时目录以及使用 --add-dir、/add-dir 或 permissions.additionalDirectories 添加的目录。当子进程（如 kubectl 或构建工具）需要在项目外写入时使用它。

• Scope: Any file，项目和本地设置受到限制
• Type: 路径字符串数组，使用 sandbox path prefixes
• Default: 未设置，因此沙箱化命令可以写入工作目录、会话临时目录、使用 --add-dir 或 /add-dir 添加的目录以及 permissions.additionalDirectories 中的目录

这让构建在 /tmp/build 下写入并让 kubectl 更新您的 kubeconfig：

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

Claude Code 在会话加载的各个设置作用域中合并 allowWrite 条目和您的 Edit(...) 允许权限规则中的路径，在 permissions.blockReadsOutsideWorkingDirectories 打开时排除来自仓库设置的条目。仓库锁也可能排除仓库的条目。allowWrite 条目不能解除 protected path。

sandbox.filesystem.denyWrite

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

• Scope: Any file
• Type: 路径字符串数组，使用 sandbox path prefixes
• Default: 未设置

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

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

Claude Code 在会话加载的每个设置范围中合并条目，并添加您的 Edit(...) 拒绝权限规则中的路径。

sandbox.filesystem.denyRead

阻止沙箱化命令读取特定路径，例如默认读取策略会公开的凭证文件。要保护凭证文件并使其可通过沙箱代理使用，请改为参阅 sandbox.credentials。

• Scope: Any file
• Type: 路径字符串数组，使用 sandbox path prefixes
• Default: 未设置，因此沙箱化命令保持 default read access，包括凭证文件，如 ~/.aws/credentials

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

Claude Code 在会话加载的每个设置范围中合并条目，并添加您的 Read(...) 拒绝权限规则中的路径。当 filesystem.disabled 为 true 时，Claude Code 不强制执行这些条目。

sandbox.filesystem.allowRead

重新打开 denyRead 阻止的区域内特定路径的读取，以构建仅工作区读取访问。精确或通配符 denyRead 条目在更广泛的 allowRead 内保持阻止，如 overlap table 所示。当通配符 denyRead 条目（如 ~/**/.env ）匹配目录时，Claude Code 也会阻止其内容的读取。在 v2.1.236 之前的 macOS 上，Claude Code 在更广泛的 allowRead 条目覆盖它们的任何地方重新打开通配符 denyRead 条目匹配的路径，并保持匹配目录的内容可读。

• Scope: Any file，项目和本地设置受到限制
• Type: 路径字符串数组，使用 sandbox path prefixes
• Default: 未设置

这阻止读取您的主目录，除了项目本身：

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

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

sandbox.filesystem.allowManagedReadPathsOnly

仅遵守来自托管设置的 allowRead 条目，以便开发人员无法重新打开对您的组织阻止的路径的读取访问。Claude Code 仍然从会话加载的每个设置范围合并 denyRead 条目。

• Scope: Managed
• Type: 布尔值
  • true: Claude Code 仅遵守来自托管设置的 allowRead 条目
  • false: 来自其他设置文件的 allowRead 条目可以合并进来
• Default: false

这阻止读取主目录，重新打开 ~/work，并阻止开发人员重新打开任何其他内容：

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

请参阅 Keep developers from widening the policy。

sandbox.filesystem.disabled

跳过文件系统隔离，同时保持网络隔离。沙箱化命令获得对主机文件系统的无限制读写访问，其网络出口仍限制在 network.allowedDomains。当您沙箱化以控制命令连接的位置而不是它们写入的内容时使用它。需要 Claude Code v2.1.216 或更高版本。

• Scope: User or managed。当托管设置配置 sandbox.filesystem 时，或列出带有 "mode": "deny" 的 sandbox.credentials.files 条目时，只有托管设置可以设置它。
• Type: 布尔值
  • true: Claude Code 跳过文件系统隔离并保持网络隔离
  • false: 文件系统隔离保持打开
• Default: 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 以保持提示。请参阅 Disable filesystem isolation 了解可以设置它的完整源列表以及隔离关闭时的变化。需要 Claude Code v2.1.216 或更高版本。

sandbox.ignoreViolations

沉默沙箱违规报告，针对您期望命令探测并被拒绝的路径，例如在启动时检查 /etc/hosts 的工具，因此这些拒绝不会显示为违规或在 Claude 看到的内容中。沙箱仍然阻止访问；只有报告被抑制。键是与命令匹配的子字符串，* 匹配每个命令，值是该命令要忽略的违规子字符串，例如文件系统路径。

• Scope: Any file，项目和本地设置受到限制
• Type: 对象，将命令子字符串映射到违规子字符串数组，通常是路径
• Default: 未设置，因此报告每个违规

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

sandbox.enableWeakerNestedSandbox

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

• Scope: Any file，项目和本地设置受到限制
• Type: 布尔值
  • true: 内部沙箱绑定挂载容器的现有 /proc 而不是挂载新的
  • false: 沙箱挂载新的 /proc，在无特权 Docker 容器中不工作
• Default: false

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

仅限 Linux 和 WSL2。请参阅 Bubblewrap fails to start inside a container。

sandbox.enableWeakerNetworkIsolation

让 macOS 上的沙箱化命令到达系统 TLS 信任服务 com.apple.trustd.agent。基于 Go 的工具（如 gh、gcloud 和 terraform ）在您使用 network.httpProxyPort 与 MITM 代理和自定义 CA 时需要它来验证 TLS 证书。这通过打开通过信任服务的潜在数据泄露路径来降低安全性。

• Scope: Any file，项目和本地设置受到限制
• Type: 布尔值
  • true: macOS 上的沙箱化命令可以到达 com.apple.trustd.agent
  • false: macOS 上的沙箱化命令无法到达系统 TLS 信任服务
• Default: false

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

如果您不使用 MITM 代理，请改为在 excludedCommands 中列出失败的工具；请参阅 Go-based CLIs fail TLS verification on macOS。

sandbox.allowAppleEvents

让 macOS 上的沙箱化命令发送 Apple Events，open、osascript 和在浏览器中打开 URL 的工具需要它；没有它们会失败，错误为 -600。这删除了代码执行隔离：沙箱化命令可以在没有用户提示的情况下启动其他应用程序，并可以向运行的应用程序（如 Terminal）发送 AppleScript 命令，受每个应用程序的 macOS 自动化同意提示 (TCC) 约束。

• Scope: User or managed
• Type: 布尔值
  • true: macOS 上的沙箱化命令可以发送 Apple Events
  • false: macOS 上的沙箱化命令无法发送 Apple Events，因此 open 和 osascript 失败，错误为 -600
• Default: false

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

要保持隔离并仍然运行一个这样的工具，请改为将其添加到 excludedCommands。请参阅 Apple Events on macOS。

sandbox.ripgrep

将沙箱指向您自己的 ripgrep 二进制文件，而不是 Claude Code 使用的，例如当您的平台需要不同构建的 rg 时。

• Scope: User or managed
• Type: 对象，包含 command（ripgrep 二进制文件的路径）和可选的 args（要前置的参数数组）
• Default: 未设置，因此沙箱使用与 Claude Code 相同的 ripgrep 二进制文件。这是捆绑的二进制文件，除非您将 USE_BUILTIN_RIPGREP 设置为 0

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

sandbox.bwrapPath

将沙箱指向安装在 PATH 外的 bubblewrap 二进制文件，例如在气隙主机上的供应商副本。Claude Code 在启动依赖项检查和包装每个沙箱化命令时都使用该路径。

• Scope: Managed。Claude Code 仅从托管设置读取它，以便用户、项目或本地文件无法将沙箱指向不同的二进制文件。
• Type: 字符串，绝对路径；Claude Code 删除相对路径并回退到 PATH 查找
• Default: 未设置，因此 Claude Code 在 PATH 上找到 bwrap

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

仅限 Linux 和 WSL2。

sandbox.socatPath

将沙箱网络代理指向安装在 PATH 外的 socat 二进制文件。

• Scope: Managed
• Type: 字符串，绝对路径；Claude Code 删除相对路径并回退到 PATH 查找
• Default: 未设置，因此 Claude Code 在 PATH 上找到 socat

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

仅限 Linux 和 WSL2。

sandbox.credentials

声明凭证文件和环境变量以 protect from sandboxed commands。每个条目命名文件 path 或变量 name 和 mode：deny 在沙箱内隐藏凭证，mask 向沙箱化命令显示占位符，同时 sandbox proxy 在出站请求上替换真实值。Claude Code 仅保护您列出的条目；没有内置凭证拒绝列表。

• Scope: Any file。Claude Code 仅从用户设置、托管设置和 --settings 标志遵守 mask 条目、allowPlaintextInject、awsPairs 和 sigv4。
• Type: 对象，包含 files、envVars、allowPlaintextInject、awsPairs 和 sigv4
• Default: 未设置，因此没有凭证被保护

这隐藏您的 AWS 凭证文件并从沙箱化命令中删除 GITHUB_TOKEN：

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

deny 文件保护是文件系统层的一部分，因此当您 disable filesystem isolation 时不适用；环境变量保护仍然适用。

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

当托管 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 之前，每个无效条目都被删除。对于其他具有每字段处理的托管键，请参阅 Invalid entries in managed settings。

sandbox.credentials.files

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

• Scope: Any file。Claude Code 从项目 .claude/settings.json 和本地 .claude/settings.local.json 删除 mask 条目。
• Type: 对象数组，每个包含 path 和 "deny" 或 "mask" 的 mode，加上可选的 mask fields for files
• Default: 未设置，因此没有凭证文件被保护

这隐藏您的 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.* 设置相同的 prefixes，Claude Code 在会话加载的每个设置范围中合并数组。Protect credentials 涵盖您使用 --setting-sources 排除的源仍然适用的内容。mask 条目需要 Claude Code v2.1.221 或更高版本。

mask 替换仅通过沙箱代理运行，因此请设置 sandbox.network.tlsTerminate，或针对纯 HTTP 测试网络设置 allowPlaintextInject。mask 适用于单个文件，因此请单独列出每个凭据文件。Claude Code 接受但忽略 deny 条目上的 mask 字段。Mask credentials 涵盖遵守哪些设置源，Mask credential files 涵盖条目何时回退到 deny。

文件的掩盖字段

mask 条目接受这些可选字段。没有 extract 或 decode，Claude Code 用一个哨兵替换整个文件内容。在启用文件系统隔离的 macOS 上，Claude Code 在 extract 或 decode 运行之前将 mask 条目应用为 deny；请参阅 Mask credential files。

这仅掩盖 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 等工具保持身份验证而无需持有真实凭据。

• Scope: Any file。Claude Code 从项目 .claude/settings.json 和本地 .claude/settings.local.json 删除 mask 条目。
• Type: 对象数组，每个包含 name 和 "deny" 或 "mask" 的 mode，加上可选的 mask fields for environment variables
• Default: 未设置，因此没有环境变量被保护

这从沙箱化命令中删除 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。Protect credentials 涵盖您使用 --setting-sources 排除的源仍然适用的内容。

mask 替换仅通过沙箱代理运行，因此请设置 sandbox.network.tlsTerminate，或针对纯 HTTP 测试网络设置 allowPlaintextInject；请参阅 Mask credentials。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

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

• Scope: User or managed
• Type: 布尔值
  • true: Claude Code 允许 mask 替换在纯 HTTP 请求以及 TLS 终止的 HTTPS 上
  • false: Claude Code 仅允许 mask 替换在 TLS 终止的 HTTPS 上
• Default: false

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

sandbox.credentials.awsPairs

分组掩盖的环境变量，形成一个 AWS 凭证用于 SigV4 re-signing，当您的凭证存在于具有非标准名称的变量中时。Claude Code 在您掩盖其整个值时自动链接常规 AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY 和 AWS_SESSION_TOKEN 三元组，因此您仅在其他名称时需要此键。需要 Claude Code v2.1.224 或更高版本。

• Scope: User or managed
• Type: 对象数组，每个包含 accessKeyIdVar、secretAccessKeyVar 和可选的 sessionTokenVar，命名 sandbox.credentials.envVars 条目
• Default: 未设置，因此仅配对常规三元组

这将三个自定义命名的变量链接到一个 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 请求形式的处理，它 can't re-sign：streaming 用于 aws-chunked 流上传，presigned 用于预签名 URL，sigv4a 用于 SigV4A 非对称签名。这仅适用于使用掩盖对的占位符访问密钥 ID 签名的请求。需要 Claude Code v2.1.224 或更高版本。

• Scope: User or managed
• Type: 对象，包含 streaming、presigned 和 sigv4a，每个为以下之一：
  • "deny": 代理失败请求
  • "passthrough": 代理转发使用掩盖占位符签名的请求，因此工具接收 AWS 自己的拒绝
• Default: 未设置，因此每种形式都是 "deny"

这转发流上传而不是在代理处失败它们：

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

使用 deny，代理失败请求。使用 passthrough，代理转发使用掩盖占位符计算的签名的请求，因此 AWS 拒绝它，调用工具接收 AWS 自己的响应而不是代理错误。

sandbox.network

控制沙箱化命令可以到达的主机、端口和套接字。沙箱通过强制执行这些列表的代理路由出站流量；请参阅 Network isolation 了解代理如何决定以及何时提示。

• Scope: Any file。strictAllowlist、allowManagedDomainsOnly 和 tlsTerminate 从较少的源读取，如其条目所述。
• Type: 对象，包含以下子键
• Default: 未设置，因此没有域被预先允许，由您的权限模式决定每个新主机的处理方式

这预先允许 GitHub 和 npm，阻止 uploads.github.com，并让命令绑定到 localhost：

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

Claude Code 在各个设置作用域中合并数组子键，因此项目可以向您的用户列表添加域，除非有仓库锁适用。WebFetch(domain:...) 允许和拒绝 permission rules 会填充相同的允许和拒绝列表。

sandbox.network.allowUnixSockets

列出 macOS 上沙箱化命令可以连接到的 Unix 套接字路径。Claude Code 在 Linux 和 WSL2 上忽略此列表，其中 seccomp 过滤器无法检查套接字路径；改为在那里使用 allowAllUnixSockets。

• Scope: Any file，项目和本地设置受到限制
• Type: 字符串数组，每个是套接字路径
• Default: 未设置，因此 macOS 沙箱阻止每个 Unix 套接字

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

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

sandbox.network.allowAllUnixSockets

让沙箱化命令连接到每个 Unix 套接字。在 Linux 和 WSL2 上，沙箱的 seccomp filter 阻止 socket(AF_UNIX, ...) 调用，因此这是在那里允许 Unix 套接字的唯一方式。当过滤器缺失时，/sandbox 在其 Dependencies 选项卡上报告，沙箱不阻止 Unix 套接字调用。请参阅 Set up Linux and WSL2 了解过滤器来自何处。

• Scope: Any file，项目和本地设置受到限制
• Type: 布尔值
  • true: 沙箱化命令可以连接到每个 Unix 套接字
  • false: 沙箱阻止 Unix 套接字连接：在 macOS 上除了 allowUnixSockets 中的路径，在 Linux 和 WSL2 上通过 seccomp 过滤器（当存在时）
• Default: false

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

在 WSL2 上，true 也重新打开启动 Windows 二进制文件（如 cmd.exe 和 powershell.exe ）的互操作套接字。

sandbox.network.allowLocalBinding

让 macOS 上的沙箱化命令监听网络端口（例如启动开发服务器），并连接到 localhost 上的任何端口。监听非回环地址的命令会接受来自其他机器的连接。该键在 Linux 和 WSL2 上无效，因为那里每个沙箱化命令都有自己的回环接口。要从 Linux 或 WSL2 访问主机上的服务器，请参阅 A command fails to reach a server on localhost。

• Scope: Any file，项目和本地设置受到限制
• Type: 布尔值
  • true: macOS 上的沙箱化命令可以监听任何本地地址并连接到 localhost 上的任何端口
  • false: macOS 上的沙箱化命令无法监听端口，也无法直接连接到 localhost 上的服务器
• Default: false

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

sandbox.network.allowMachLookup

列出 macOS 沙箱可能查找的其他 XPC 和 Mach 服务名称。通过 XPC 通信的工具，例如 iOS Simulator 或 Playwright，需要在此处列出其服务。

• Scope: Any file，项目和本地设置受到限制
• Type: 字符串数组，每个是服务名称；单个尾部 * 匹配前缀，"*" 单独匹配每个服务
• Default: 未设置

这允许 com.apple.coresimulator. 前缀下的每个服务：

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

sandbox.network.allowedDomains

预先允许来自沙箱化命令的出站流量的域，因此沙箱不会为它们提示。通配符（如 *.example.com ）匹配子域，可选的 :port 后缀将条目限制为一个端口；没有端口的条目匹配每个端口。

• Scope: Any file，项目和本地设置受到限制。当设置了 allowManagedDomainsOnly 时，仅限托管设置。
• Type: 字符串数组，每个是域、通配符模式或 IP 文字，带有可选的 :port 后缀
• Default: 未设置，因此由您的权限模式决定每个新主机的处理方式

这预先允许 GitHub 在每个端口、每个 npm 子域和一个 API 主机仅在端口 443 上：

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

将 IPv6 文字写成括号形式，带有可选端口："[::1]" 允许每个端口，"[::1]:443" 一个端口。括号形式需要 Claude Code v2.1.229 或更高版本。请参阅 IPv6 addresses in domain lists。

sandbox.network.deniedDomains

阻止来自沙箱化命令的出站流量的域，使用与 allowedDomains 相同的通配符、端口和 IPv6 语法。被拒绝的域即使 allowedDomains 条目也匹配它也保持阻止。

• Scope: Any file
• Type: 字符串数组，每个是域、通配符模式或 IP 文字，带有可选的 :port 后缀
• Default: 未设置

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

Claude Code 从会话加载的每个设置源合并此列表，即使设置了 allowManagedDomainsOnly，因此开发人员总是可以收紧拒绝列表。对于 IPv6 文字，请参阅 IPv6 addresses in domain lists。

使用标记完全限定域名的尾部点编写的条目，例如 example.com.，阻止与 example.com 相同的连接。

sandbox.network.strictAllowlist

拒绝沙箱化命令访问允许列表外的主机，而不是提示批准。允许列表是 allowedDomains 加上来自 WebFetch(domain:...) 允许规则的域，或者当设置了 allowManagedDomainsOnly 时仅为托管设置条目。Locks that apply without an admin-required sandbox 涵盖仓库的条目。需要 Claude Code v2.1.219 或更高版本。

• Scope: User or managed。存储库无法打开或关闭它。
• Type: 布尔值
  • true: Claude Code 拒绝沙箱化命令访问允许列表外的主机
  • false: 除非另一个受信任的设置文件设置 true，Claude Code 根据权限模式而不是直接拒绝来决定允许列表外的主机：它在自动模式下检查主机对命令的 per-command allowed domains，在 dontAsk 模式下拒绝，在 bypassPermissions 模式下允许，在交互式终端计划模式会话中当绕过可用时允许，否则询问您
• Default: false

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

Claude Code 仅对沙箱化命令强制执行此；进程内工具（如 WebFetch ）仍然遵循其 permission rules。当任何遵守的源将其设置为 true 时，它保持打开。请参阅 Network isolation。需要 Claude Code v2.1.219 或更高版本。

sandbox.network.allowManagedDomainsOnly

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

• Scope: Managed
• Type: 布尔值
  • true: Claude Code 仅遵守来自托管设置的 allowedDomains 和 WebFetch(domain:...) 允许规则，并阻止非允许的域而不是提示
  • false: 来自其他设置文件的域可以合并到允许列表中
• Default: false

这将允许列表锁定到 GitHub 和 npm，并忽略开发人员添加的任何域：

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

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

被拒绝的域仍然从会话加载的每个源合并。请参阅 Keep developers from widening the policy。

sandbox.network.httpProxyPort

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

• Scope: Any file，除非其他沙箱设置限制了哪些文件可以设置端口
• Type: 数字，本地 TCP 端口
• Default: 未设置，因此 Claude Code 运行自己的代理

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

如果您的代理也应该携带 SOCKS 流量，也设置 socksProxyPort；仅设置其中一个，Claude Code 仍然为另一个协议运行自己的代理。请参阅 Custom proxy configuration。

sandbox.network.socksProxyPort

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

• Scope: Any file，除非其他沙箱设置限制了哪些文件可以设置端口
• Type: 数字，本地 TCP 端口
• Default: 未设置，因此 Claude Code 运行自己的代理

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

请参阅 Custom proxy configuration。

sandbox.network.tlsTerminate

使沙箱代理终止 TLS，以便它可以读取 HTTPS 请求的内容。这是实验性的，mask credential substitution 需要它。设置 {} 为会话生成临时证书颁发机构，或设置 caCertPath 和 caKeyPath 以使用您自己的。

• Scope: User or managed。存储库无法打开它或提供证书颁发机构。
• Type: 对象，包含可选的 caCertPath 和 caKeyPath 字符串，每个是文件路径
• Default: 未设置，因此代理不终止或检查 TLS

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

当多个遵守的源设置它时，Claude Code 使用来自最高优先级源的值：托管设置，然后是 --settings 标志，然后是用户设置。

记忆和上下文

控制 Claude Code 加载到上下文中的内容、如何压缩以及在何处保存内存和计划。请参阅管理上下文和内存。

autoCompactEnabled

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

• Scope: Any file
• Type: Boolean
  • true: 当上下文接近限制时，Claude Code 自动压缩对话
  • false: Claude Code 不自动压缩
• Default: true
• Per-session overrides: DISABLE_AUTO_COMPACT 为一个会话关闭自动压缩；两者中任何一个关闭它，另一个就无法将其打开

{
  "autoCompactEnabled": false
}

手动 /compact 命令在自动压缩关闭时继续工作。如果您关闭自动压缩，空闲压缩也会随之关闭。

autoCompactWindow

设置在 Claude Code 自动压缩之前上下文窗口的填充程度。

• Scope: Any file
• Type: 令牌数，从 100000 到 1000000。Claude Code 将值限制在您的模型的上下文窗口；模型概览列出了每个模型的窗口
• Default: 未设置，因此 Claude Code 选择为您的模型调整的窗口
• Per-session overrides: --autocompact 对一个会话优先于此键，CLAUDE_CODE_AUTO_COMPACT_WINDOW 优先于两者，除非 Claude Code 忽略该变量的值

{
  "autoCompactWindow": 500000
}

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

autoMemoryDirectory

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

• Scope: Any file
• Type: 字符串，绝对路径或 ~/ 前缀的目录路径
• Default: 未设置，因此 Claude Code 使用 ~/.claude/projects/<project>/memory/

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

从项目或本地设置中，Claude Code 在与 hooks 相同的工作区信任规则下遵守此键，因为克隆的存储库可以提供这些文件。

autoMemoryEnabled

打开或关闭自动内存。当为 false 时，Claude 不会从自动内存目录读取或写入。您也可以在会话期间使用 /memory 切换它，这会将此键写入您的用户设置。

• Scope: Any file
• Type: Boolean
  • true: 与未设置相同；自动内存保持打开，除非优先于此键的内容为会话关闭它，例如 --bare、安全模式或 CLAUDE_CODE_DISABLE_AUTO_MEMORY
  • false: Claude 不会从自动内存目录读取或写入
• Default: true
• Per-session overrides: CLAUDE_CODE_DISABLE_AUTO_MEMORY 对一个会话优先于此键，无论哪个方向

{
  "autoMemoryEnabled": false
}

bashOutputMaxChars

设置成功的 Bash 或 PowerShell 命令的输出 Claude 内联接收的字符数。当输出超过限制时，Claude Code 将其保存到文件，Claude 接收简短预览加文件路径。当命令输出（例如详细构建或完整测试套件日志）经常超过默认值且您希望 Claude 在不打开文件的情况下读取它时，提高限制。需要 Claude Code v2.1.261 或更高版本。

• Scope: Any file
• Type: 字符数，正整数。Claude Code 将值限制在 4000 到 128000 范围内
• Default: 未设置，因此 Claude 内联接收最多 30,000 个字符

{
  "bashOutputMaxChars": 100000
}

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

claudeMd

注入 CLAUDE.md 风格的说明作为组织管理的内存，无需部署单独的文件。Claude Code 将文本作为托管内存条目加载，位于用户和项目 CLAUDE.md 文件之前。

• Scope: Managed
• Type: 字符串，CLAUDE.md 文件的文本；按照您编写文件的方式编写，包括 Markdown，行中断为 \n
• Default: 未设置

此示例将两个规则部署为简短的 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 文件。在大型单体仓库中，使用它跳过来自与您的工作无关的其他团队的 CLAUDE.md 文件；大型代码库指南中的排除无关的 CLAUDE.md 文件演示了该情况。模式与绝对文件路径匹配。

• Scope: Any file
• Type: 字符串数组，每个都是 glob 模式或绝对路径
• Default: 未设置，因此 Claude Code 加载它找到的每个 CLAUDE.md

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

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

env

为每个会话和 Claude Code 从中启动的子进程设置环境变量。环境变量参考中的大多数变量都可以放在这里，这是如何将其应用于每个会话或向您的团队推出的方式。项目和本地设置无法设置其中一些。

• Scope: Any file
• Type: 将变量名映射到字符串值的对象
• Default: 未设置

此示例关闭自动压缩并通过代理路由 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 承载令牌，使用 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
    • OTEL_EXPORTER_OTLP_* 变量，其名称以 _ENDPOINT、_HEADERS、_PROTOCOL、_CERTIFICATE、_CLIENT_KEY 或 _INSECURE 结尾，采用通用和按信号形式，例如 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_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 自己导出的，从每个文件中被忽略。忽略套接字变量需要 Claude Code v2.1.224 或更高版本，忽略令牌需要 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 仅从启动环境读取，从每个文件中被忽略。

fileCheckpointingEnabled

让 Claude Code 在每次编辑前快照文件，以便 /rewind 可以恢复它们。在 /config 中显示为回退代码（检查点），在那里切换它会将此键写入您的用户设置。

• Scope: Any file
• Type: Boolean
  • true: Claude Code 在每次编辑前快照文件，以便 /rewind 可以恢复它们
  • false: Claude Code 不快照文件，因此 /rewind 无法恢复它们
• Default: true
• Per-session overrides: 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 开头的内容。

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

• 会话：您处于交互式终端会话中
• 提示缓存：该对话使用一小时提示缓存 TTL
• 功能标志：Claude Code 可以从 Anthropic 获取功能标志
• 大小：对话的上下文已达到 token 阈值，您可以将该阈值从默认的 200,000 进行更改
• 空闲时间：自上次请求以来已过去约 54 分钟，且此时您的计算机处于唤醒状态

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

• Scope: Any file
• Type: Boolean
  • true: Claude Code 压缩满足条件的空闲对话
  • false: Claude Code 在您的会话空闲时不进行压缩
• Default: true
• Per-session overrides: DISABLE_AUTO_COMPACT 会在关闭自动压缩的同时关闭空闲压缩

{
  "idleCompaction": false
}

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

• 其他设置来源设置了该键：托管设置、--settings 标志或项目或本地设置文件中的值会覆盖您的用户设置。请改为在该来源中更改此键
• 功能标志不可用：在 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"
  }
}

plansDirectory

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

• Scope: Any file
• Type: 字符串，相对于项目根目录的路径
• Default: 未设置，因此 Claude Code 使用 ~/.claude/plans

{
  "plansDirectory": "./plans"
}

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

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

skillListingBudgetFraction

每个回合，Claude 看到您的技能列表及其描述，Claude Code 将该列表限制在上下文窗口的一部分。当列表超过上限时，Claude Code 保留每个技能的名称，但删除使用最少的技能的描述，因此 Claude 仍然可以调用这些技能，但不太可能自己选择一个。提高此键以保持更多描述可见，代价是每个回合更多上下文。

• Scope: Any file
• Type: 数字，大于 0 且最多 1 的分数
• Default: 0.01，保留 1% 的上下文窗口

{
  "skillListingBudgetFraction": 0.02
}

要查看列表使用多少上下文以及哪些技能贡献最多，请运行 /doctor。

skillListingMaxDescChars

每个回合，Claude 看到您的技能列表，显示每个技能的 description 和 when_to_use 文本。此键限制 Claude Code 每个技能显示多少字符的该文本；较长的文本在上限处被切割。

• Scope: Any file
• Type: 字符数，正整数
• Default: 1536

{
  "skillListingMaxDescChars": 2048
}

提高它以保持长描述完整，代价是每个回合更多上下文；降低它以在 skillListingBudgetFraction 下适应更多技能。

taskOutputMaxChars

[!WARNING]

在 v2.1.277 中删除，连同它调整大小的 TaskOutput 工具一起。设置它对当前版本没有影响。Claude 使用 Read 读取后台任务的输出文件。

通过 v2.1.276，您将此键设置为后台任务的输出字符数，当 Claude 使用 TaskOutput 工具读取任务时 Claude 内联接收。

界面和终端

更改 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 设置不起作用；附加的后台会话仍以全屏方式渲染。

• 作用域：Any file
• 类型：布尔值
  • 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 指示 Claude 通过 Bash 编辑文件时，会在自动模式和 bypassPermissions 模式下记录更改
• 单会话覆盖：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"，在 Bash 不可用的 Windows 上为 "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 短代码。需要 Claude Code v2.1.217 或更高版本。

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 的回复中时，页脚中会出现一个 PROJ-1234 徽章，链接到 https://issues.example.com/browse/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 Code 在 Claude 工作时显示的加载动画提示中添加您自己的提示，或用您的提示替换内置提示。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 对应的行。您未写回的行保持默认渲染。

• 作用域：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 会关闭全屏

{
  "tui": "fullscreen"
}

在 tmux -CC 下或通过 SSH 连接到 Windows 时，除非您设置 CLAUDE_CODE_NO_FLICKER=1，否则 Claude Code 会保持使用经典渲染器。从 Agent 视图打开的后台会话始终使用全屏渲染器，不受此设置影响。

verbose

默认情况下，会话记录会将每个工具调用折叠为简短摘要，例如 Claude 运行的命令及其输出的行数；当您需要详细信息时，按 Ctrl+O 可将整个会话记录切换到展开视图。将此键设置为 true 可在每个工具调用发生时内联显示其完整的输入和输出，这在调试 hook、MCP 服务器或较长的 shell 命令时非常有用。在 /config 中显示为 Verbose output。

• 作用域：Any file。当没有设置文件设置此项时，来自旧版本的 ~/.claude.json 中的值会生效。
• 类型：布尔值
  • true：您会看到完整的工具输出
  • false：您会看到截断的工具输出摘要
• 默认值：false
• 单会话覆盖：--verbose 在单个会话中优先于此键

{
  "verbose": true
}

viewMode 值或持久的 /focus 选择会在每个会话中覆盖此键。

viewMode

设置 Claude Code 启动时的会话记录视图："default"、"verbose" 或 "focus"。设置后，它会同时覆盖持久的 /focus 选择和 verbose 设置。

• 作用域：Any file
• 类型：字符串，取值为以下之一：
  • "default"：带有截断工具输出的普通会话记录
  • "verbose"：带有完整工具输出的会话记录
  • "focus"：仅显示您的最后一条提示词、带有编辑 diffstat 的工具调用单行摘要以及最终回复。专注视图需要全屏渲染器
• 默认值：未设置，因此 verbose 设置和您上次的 /focus 选择生效
• 单会话覆盖：--verbose 在单个会话中优先于此键

{
  "viewMode": "focus"
}

vimInsertModeRemaps

在 vim 编辑器模式中，将 INSERT 模式下的两键序列映射为 Escape。每个键必须恰好是依次输入的两个可打印字符，且 "<Esc>" 是唯一支持的目标；Claude Code 会忽略其他条目。

• 作用域：User or managed。仓库无法重新映射您的按键。
• 类型：将两字符序列映射到 "<Esc>" 的对象
• 默认值：未设置

{
  "vimInsertModeRemaps": {
    "jj": "<Esc>"
  }
}

除非 editorMode 为 "vim"，否则此项不起作用。请参阅重新映射 INSERT 模式按键序列。

voice

开启语音听写并选择听写键的行为方式。当您运行 /voice 时，Claude Code 会为您写入此对象。

• 作用域：Any file
• 类型：包含 enabled（布尔值）、autoSubmit（布尔值，仅在按住模式下生效）和 mode 的对象，mode 取值为以下之一：
  • "hold"：说话时按住听写键，松开即停止
  • "tap"：轻按一次开始录音，再按一次发送
• 默认值：未设置，因此听写关闭；当 enabled 为 true 且未设置 mode 时，Claude Code 使用 "hold"

此示例开启听写，并将按键设置为轻按一次开始录音、再按一次发送：

{
  "voice": {
    "enabled": true,
    "mode": "tap"
  }
}

autoSubmit 会在按住模式下您松开按键时发送提示词。语音听写需要 claude.ai 账户。

voiceEnabled

[!WARNING]

自 v2.1.92 起已弃用，当时被 voice 对象取代。Claude Code 仍会读取它，以便旧的设置文件继续工作，但新的配置应设置 voice.enabled。

使用早于 voice 对象的单一布尔值形式开启语音听写。当两者都设置时，以 voice.enabled 为准。

• 作用域：Any file
• 类型：布尔值
  • true：当您使用 claude.ai 账户登录且您组织的策略允许语音时，语音听写开启，除非设置了 voice.enabled
  • false：语音听写关闭，除非设置了 voice.enabled
• 默认值：未设置

{
  "voiceEnabled": true
}

wheelScrollAccelerationEnabled

在全屏渲染中快速滚动时加快鼠标滚轮的滚动速度。将其设置为 false 可使每个滚轮刻度的滚动速率保持恒定。

• 作用域：Any file
• 类型：布尔值
  • true：Claude Code 在快速滚动时加快鼠标滚轮的滚动速度
  • false：Claude Code 按每个滚轮刻度以恒定速率滚动
• 默认值：true

{
  "wheelScrollAccelerationEnabled": false
}

Git 和归属

控制 Claude Code 添加到提交和拉取请求的归属，以及它如何与 git 配合使用。

attribution

自定义 Claude Code 添加到 git 提交和拉取请求的归属。提交默认获得 git trailer，例如 Co-Authored-By；拉取请求描述获得纯文本。使用下面的子键分别设置每个部分。

• Scope: Any file
• Type: 包含 commit 和 pr 字符串以及 sessionUrl 布尔值的对象，或 false 以隐藏所有归属。false 值需要 Claude Code v2.1.281 或更高版本；更早的版本会拒绝它并跳过整个用户、项目或本地设置文件
• Default: 未设置，因此 Claude Code 使用每个子键下显示的标准归属

要隐藏所有归属，请将 attribution 设置为 false。在早期版本也读取的设置文件中，将 commit 和 pr 设置为空字符串，并将 sessionUrl 设置为 false。

此示例替换提交归属，删除拉取请求归属，并删除会话链接：

{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: AI <ai@example.com>",
    "pr": "",
    "sessionUrl": false
  }
}

一旦设置 commit 或 pr，Claude Code 将忽略已弃用的 includeCoAuthoredBy 设置，并对未设置的两个中的任何一个使用其默认文本。

Claude Code 告诉 Claude，您自己关于归属的说明（例如 CLAUDE.md 或 memory 规则）优先于这些提交和 PR 行，除非该行在 managed settings 中设置。

includeCoAuthoredBy

[!WARNING]

自 v2.0.62 起已弃用，当 attribution 替换它时。Claude Code 仍然读取它，但新配置应设置 attribution。

改用 attribution，它替换此键，让您可以分别更改或隐藏提交 trailer、拉取请求文本和会话链接。Claude Code 仍然遵守来自早于 attribution 的设置文件中的 includeCoAuthoredBy: false，但一旦设置 attribution.commit 或 attribution.pr，就会忽略它。

• Scope: Any file
• Type: 布尔值
  • true: 与未设置相同；Claude Code 添加提交 trailer 和拉取请求归属文本
  • false: Claude Code 省略提交 trailer 和拉取请求归属文本，除非 attribution 设置 commit 或 pr，在这种情况下 attribution 规则适用
• Default: true

{
  "includeCoAuthoredBy": false
}

要隐藏所有归属，请参阅 attribution。

includeGitInstructions

Claude Code 向 Claude 提供两个与 git 相关的上下文片段：其内置的关于如何编写提交和拉取请求的说明（在 Bash 工具的描述中），以及您的存储库的 git 状态快照。快照包含当前分支、主分支、git status 输出和最近的提交。Claude Code 在会话开始时读取它。

将此键设置为 false 以将两者都排除，例如当您使用自己的 git 工作流技能时。

• Scope: Any file
• Type: 布尔值
  • true: Claude Code 包含其内置的提交和拉取请求工作流说明以及 git 状态快照。云会话永远不包括快照
  • false: Claude Code 将两者都排除
• Default: true
• Per-session overrides: CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS 对此键优先一个会话

{
  "includeGitInstructions": false
}

如果您在非交互模式或 Agent SDK 中替换系统提示词，即使此键为 true，会话启动时也不会包含快照：

• -p 运行：当您传递 --system-prompt 或 --system-prompt-file 时，即替换了提示词。当您运行带有自己提示词的自定义 Agent（通过 --agent 或 agent 设置选择）时，也会替换提示词。在 bare 模式之外，要保留快照，请不使用自定义 Agent 运行，并使用 --append-system-prompt 添加您的说明，而不是替换提示词。
• Agent SDK：当您使用自定义系统提示词或自定义主线程 Agent 时，即替换了提示词。如果您未设置系统提示词，SDK 会使用其最小默认值，会话启动时同样不包含快照。在 bare 模式之外，要保留快照，请使用 claude_code 预设且不使用自定义 agent。

prUrlTemplate

将 Claude Code 呈现的 PR 链接（在页脚徽章和工具结果摘要中）指向内部代码审查工具而不是 github.com。Claude Code 从 PR URL 替换 {host}、{owner}、{repo}、{number} 和 {url}。GitLab 合并请求 两个表面上的链接保持其 GitLab URL。

• Scope: Any file
• Type: 字符串，使用五个占位符中任何一个的 URL 模板
• Default: 未设置

{
  "prUrlTemplate": "https://reviews.example.com/{owner}/{repo}/pull/{number}"
}

Claude Code 仅将模板应用于它自己呈现的链接；Claude 在消息中编写的 PR 号（例如 #123）保持 Claude 编写的样子。没有 /pull/<number> 形状的 URL 保持不变。

attribution.commit

设置 Claude Code 添加到 git 提交的归属文本，包括任何 trailer。将其设置为空字符串以隐藏提交归属。

• Scope: Any file
• Type: 字符串
• Default: 未设置，因此 Claude Code 添加 Co-Authored-By: <name> <noreply@anthropic.com>。名称是进行提交时使用的模型，例如 Claude Sonnet 5。当 subagent 进行提交时，trailer 命名 subagent 的模型。
  • 当 Claude Code 识别模型为 Claude 模型但无法确认其确切版本时，它单独写入 Claude。
  • 当它无法将模型 ID 匹配到任何 Claude 模型（例如通过自定义 ANTHROPIC_BASE_URL 提供的第三方模型）时，它写入 Claude Code。

此示例用自定义行和自定义 Co-Authored-By trailer 替换默认 trailer：

{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: AI <ai@example.com>"
  }
}