所有設定

Claude Code settings.json 的完整參考：每個鍵的位置、類型和預設值，以及隨時可貼上的範例，包含每個鍵的索引。

Back to index

本參考頁面列出 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 上關閉思考時，對於 Claude Code 已知不接受該組合的模型（例如 Opus 5），Claude Code 會傳送 effort high 而非更高的等級。

• 範圍：Any file
• 類型：Boolean
  • true：沒有作用；思考已開啟
  • false：Claude Code 在每個工作階段中關閉延伸思考
• 預設值：未設定，因此支援思考的模型會開啟思考
• 每個工作階段的覆寫：MAX_THINKING_TOKENS 在單一工作階段中優先於此鍵：0 會關閉思考，受與 false 相同的模型和供應商限制；正值則會開啟思考，即使此鍵為 false 亦然。在自適應推理模型上，數值本身會被忽略

{
  "alwaysThinkingEnabled": false
}

availableModels

限制使用者可為主要工作階段、subagent、skill 以及 advisor 選擇哪些模型。受管清單會限制 /model、--model，以及開發者自己檔案中的 model 鍵；清單以外的模型無法被選擇。在預設的前綴比對下，此鍵本身不會影響 Default 選項；若要影響該選項，請搭配 enforceAvailableModels 使用。

• 範圍：Any file。將其部署於受管設定中，即可為組織強制執行。
• 類型：模型別名或 ID 的陣列
• 預設值：未設定，因此所有模型皆可使用

此範例讓使用者只能選擇 Sonnet 和 Haiku 模型：

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

像 "claude-opus-5" 這樣的模型 ID 項目，也會允許延伸自該 ID 的後續版本，例如 Opus 5.5。若要封鎖其中某個版本，請使用 deniedModels。若要讓每個模型 ID 項目只允許其所指定的版本，請使用 availableModelsMatch。請參閱限制模型選擇。關於第三方供應商的 ID，請參閱為第三方部署固定模型。

availableModelsMatch

選擇 availableModels 項目如何比對模型 ID。預設情況下，模型 ID 項目也會允許延伸自該 ID 的後續版本，因此 "claude-opus-5" 會允許 Opus 5.5。使用 "exact" 時，每個模型 ID 項目只允許其所指定的版本，因此該模型的較新版本在您將其列出之前都會保持封鎖。需要 Claude Code v2.1.283 或更新版本。

• 範圍：Managed。Claude Code 會忽略使用者、專案及本機設定中以及 --settings 中的此鍵，並顯示警告
• 類型：字串，為下列之一：
  • "prefix"：模型 ID 項目允許其版本，以及任何以另一個片段延伸該 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's 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's 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 或 subagent 的 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" 值表示不設上限
• 預設值：未設定，因此不套用任何上限
• 每個模型的上限：在模型的 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'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 Boolean 的物件
• 預設值：未設定，因此選擇器會顯示內建陣容

此範例在內建陣容之後新增兩個 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 對應至同一個項目。

此範例讓 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

此範例讓主要對話使用一小時的存留期，並讓 subagent 保持五分鐘：

{
  "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 在主要對話以外發出之請求的時間長度。此鍵套用於 subagent、工作流程，以及 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，它會要求每個請求都使用一小時的存留期。關於 subagent 自身 frontmatter 值的優先順序，請參閱自行選擇 TTL

此範例讓 subagent 以及主要對話以外的其他請求使用一小時的存留期：

{
  "subagentPromptCacheTtl": "1h"
}

此鍵涵蓋 promptCacheTtl 未涵蓋的請求，因此同時設定兩者即可為 Claude Code 發出的每個請求選擇存留期。關於 subagent 的快取與主要對話快取的差異，請參閱Subagent 與快取。

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

{
  "ultracode": true
}

工作階段的 effort 等級來自 effortLevel、modelSettings 以及其他 effort 來源，而 effort 上限（例如 maxEffortLevel）會降低該等級，但不會關閉 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
• 類型：布林值
  • true：受管設定成為權限規則的唯一設定來源
  • false：Claude Code 除了套用受管規則外，還會套用來自使用者、專案、本機和 --settings 檔案的權限規則
• 預設值：未設定，因此 Claude Code 會套用來自使用者、專案和本機設定以及 --settings 的權限規則，以及受管規則

{
  "allowManagedPermissionRulesOnly": true
}

此設定鍵不會鎖定 MCP 伺服器允許清單；若要執行此操作，請設定 allowManagedMcpServersOnly。請參閱僅受管設定。

autoMode

將您自己的規則新增至自動模式分類器封鎖和允許的內容。使用它來告訴分類器您的組織信任哪些儲存庫、貯體和網域，以便它停止封鎖例行的內部操作。分類器隨附內建的允許和拒絕規則。在陣列中包含字面字串 "$defaults" 以在該位置保留這些內建規則，並在其周圍新增您的規則；省略它以用您的規則取代它們。

• 範圍：User or managed
• 類型：物件，包含 environment、allow、soft_deny 和 hard_deny 散文規則陣列，加上 classifyAllShell 布林值
• 預設值：未設定，因此分類器僅使用其內建規則

此範例透過 "$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 相同。
• 類型：布林值
  • 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 是否在 plan mode 中使用自動模式分類器來檢查 shell 命令。使用預設值 true，分類器在規劃期間檢查每個命令（當自動模式可用且您看不到提示時），除了關鍵路徑移除。設定 false 以針對內建唯讀集之外的每個命令獲得權限提示。在 /config 中顯示為在計畫期間使用自動模式。

• 範圍：User, local, or managed。儲存庫無法為您關閉它。
  • 這些檔案中任一個或 --settings 中的 false 都會將其關閉，除非您使用 --setting-sources 等選項排除該使用者或本機檔案。忽略被排除的檔案需要 Claude Code v2.1.314 或更新版本
• 類型：布林值
  • 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 本身需要的檔案保持可讀，例如您的 skill、外掛、規則、agent、命令以及 ~/.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 在工作階段中建立的 worktree、工作階段暫存目錄，以及 ~/.claude 中命令需要的部分，例如 skill 和外掛。當區塊生效時，來自儲存庫設定的 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 token，請將其路徑新增到 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 可能不會套用此設定鍵，因為檔案工具在本身即為邊界的容器中執行。
• 類型：布林值
  • 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 也會拒絕這些寫入，因為設定檔可以解除封鎖。請自行編輯設定檔。
• 僅由儲存庫設定新增的目錄：僅在 .claude/settings.json 中，或在 .claude/settings.local.json 中（除非 git 報告該檔案為未追蹤）由 additionalDirectories 列出的目錄
• subagent 的 worktree：當 isolation: worktree subagent 的 worktree 位於工作目錄之外時，其檔案編輯會被拒絕
• 儲存庫選擇之目錄中的自動記憶：儲存庫設定中 autoMemoryDirectory 所指定的目錄

無論您新增什麼，設定檔都會保持被拒絕。若要讓其他任一情況中的寫入通過，請新增工作目錄。/add-dir 需要已存在的目錄，因此對於 subagent 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。儲存庫無法為您設定它。
• 類型：布林值
  • true：Claude Code 拒絕原本會提示的呼叫
  • false：與未設定相同；如果這些來源中的另一個設定 true，呼叫仍會被拒絕
• 預設值：未設定，因此需要核准的呼叫會提示您

在 ~/.claude/settings.json 中，此範例以自動模式啟動工作階段，並拒絕任何仍會退回到提示的操作：

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

此設定鍵適用於 -p 執行、互動式終端機工作階段、VS Code 擴充功能、Desktop 應用程式中的本機工作階段、subagent 和 agent team。若要改為只在單一非互動式執行中拒絕會提示的操作，請搭配 -p 傳入 --permission-prompts none。

denyInsteadOfPrompting 還會停止哪些項目

開啟此設定後，Claude Code 也會停止下列需要回應的請求：

• 問題和計畫工具：Claude Code 會省略 AskUserQuestion、EnterPlanMode 和 ExitPlanMode，因此處於 plan mode 的工作階段無法自行離開。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，因此 subagent 會以父工作階段的權限模式執行。

• 範圍：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，以及以 --settings 傳入的檔案。背景工作階段只計入使用者和受管設定。不受信任的儲存庫無法為您跳過對話。
• 類型：布林值
  • 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，但對專案和本機設定有所限制
• 類型：Boolean
  • 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
  }
}

關於自動允許模式仍會針對哪些情況提示，以及它在 plan mode 中的行為，請參閱自動允許模式。

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

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。取而代之的是，內層沙箱會 bind-mount 容器現有的 /proc，這會公開新掛載原本會隱藏的程序資訊。這會降低安全性；請僅在外層容器已提供您所需的隔離時使用。

• 範圍：Any file，但對專案和本機設定有所限制
• 類型：布林值
  • true：內層沙箱會 bind-mount 容器現有的 /proc，而不是掛載新的 /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。true 僅在來自 ~/.claude/settings.json、透過 --settings 傳入的 JSON 或受管設定時有效。Claude Code 會忽略專案的 .claude/settings.json 或 .claude/settings.local.json 中的 true。在 CLAUDE_CODE_SUBPROCESS_ENV_SCRUB 設為 1 的工作階段中，Claude Code 會忽略來自所有來源的 true。false 來自任何檔案皆有效，依設定優先順序決定。
• 類型：Boolean
  • 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，且 mode 為 mask 或 deny 的項目（例如其 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 hosts 檔案，僅在送往 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 hosts 檔案中的 oauth_token 值、取代檔案中它的所有其他副本、在模式比對不到任何內容時讓檔案無法讀取，並僅在送往 api.github.com 的請求中替換為真實 token：

{
  "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 以外的所有 claim 保持可讀：

{
  "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：Claude Code 除了 TLS 終止的 HTTPS 之外，也允許在純 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 中不含 extract 或 decode 的完整值 mask 項目，且在所有配對中只能填入一個欄位。以下規則也適用：

• 代理伺服器會在存取金鑰 ID 項目的 injectHosts 所列出的主機上重新簽署請求
• 設定 sessionTokenVar 時，代理伺服器會在重新簽署的請求中以 x-amz-security-token 傳送真實 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

控制沙箱化命令可以存取哪些主機、連接埠和 socket。沙箱會將外送流量透過強制執行這些清單的代理伺服器轉送；關於代理伺服器如何決定以及何時提示，請參閱網路隔離。

• 範圍：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 socket 路徑。Claude Code 在 Linux 和 WSL2 上會忽略此清單，因為 seccomp 篩選器無法檢查 socket 路徑；在這些平台上請改用 allowAllUnixSockets。

• 範圍：Any file，但對專案和本機設定有所限制
• 類型：字串陣列，每個都是 socket 路徑
• 預設值：未設定，因此 macOS 沙箱會封鎖每個 Unix socket

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

socket 路徑可能授予廣泛的存取權：例如，允許 /var/run/docker.sock 會讓沙箱化命令能夠控制 Docker daemon。請參閱安全性限制。

sandbox.network.allowAllUnixSockets

讓沙箱化命令可以連線到每個 Unix socket。在 Linux 和 WSL2 上，沙箱的 seccomp 篩選器會封鎖 socket(AF_UNIX, ...) 呼叫，因此這是在這些平台上允許 Unix socket 的唯一方式。當篩選器不存在時（/sandbox 會在其 Dependencies 分頁中回報），沙箱不會封鎖 Unix socket 呼叫。關於篩選器的來源，請參閱設定 Linux 和 WSL2。

• 範圍：Any file，但對專案和本機設定有所限制
• 類型：布林值
  • true：沙箱化命令可以連線到每個 Unix socket。在 Linux 和 WSL2 上，它們也可以連線到 VM socket，即 AF_VSOCK 位址系列
  • false：沙箱會封鎖 Unix socket 連線：在 macOS 上，allowUnixSockets 中的路徑除外；在 Linux 和 WSL2 上，則在 seccomp 過濾器存在時透過它封鎖
• 預設值：false

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

在 WSL2 上，true 也會重新開放用來啟動 cmd.exe 和 powershell.exe 等 Windows 二進位檔的 interop socket。

sandbox.network.allowLocalBinding

讓 macOS 上的沙箱化命令可以監聽網路連接埠（例如用來啟動開發伺服器），並連線到 localhost 上的任何連接埠。在非 loopback 位址上監聽的命令會接受來自其他機器的連線。此鍵在 Linux 和 WSL2 上沒有作用，因為在這些平台上每個沙箱化命令都有自己的 loopback 介面。若要從 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 模式以及可使用略過功能的互動式終端機 plan mode 工作階段中會允許；其他情況則會詢問您
• 預設值：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 中顯示為自動壓縮，在那裡切換它會將此鍵寫入您的使用者設定。

• 範圍：任何檔案
• 類型：布林值
  • true：當上下文接近限制時，Claude Code 自動壓縮對話
  • false：Claude Code 不自動壓縮
• 預設：true
• 每個工作階段的覆蓋：DISABLE_AUTO_COMPACT 關閉一個工作階段的自動壓縮；無論哪一個關閉它，另一個都無法將其重新開啟

{
  "autoCompactEnabled": false
}

手動 /compact 命令在自動壓縮關閉時繼續工作。如果您關閉自動壓縮，閒置壓縮也會隨之關閉。

autoCompactWindow

設定在 Claude Code 自動壓縮之前上下文視窗有多滿。

• 範圍：任何檔案
• 類型：權杖數量，從 100000 到 1000000。Claude Code 將值上限設定為您的模型的上下文視窗；模型概覽列出每個模型的視窗
• 預設：未設定，因此 Claude Code 選擇為您的模型調整的視窗
• 每個工作階段的覆寫：--autocompact 在一個工作階段內優先於此鍵，CLAUDE_CODE_AUTO_COMPACT_WINDOW 優先於兩者，除非 Claude Code 忽略該變數的值

{
  "autoCompactWindow": 500000
}

/autocompact 命令會將目前模型的視窗保存在 modelSettings 下，對於該模型，它優先於同一檔案中的此鍵。設定自動壓縮視窗涵蓋命令、旗標、變數和設定如何相互作用。

autoMemoryDirectory

將自動記憶儲存在您選擇的目錄中，而不是每個專案的預設值。

• 範圍：任何檔案
• 類型：字串，絕對路徑或 ~/ 前綴的目錄路徑
• 預設：未設定，因此 Claude Code 使用 ~/.claude/projects/<project>/memory/

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

從專案或本機設定，Claude Code 在與 hooks 相同的工作區信任規則下遵守此鍵，因為複製的儲存庫可以提供這些檔案。

autoMemoryEnabled

開啟或關閉自動記憶。當為 false 時，Claude 不會從自動記憶目錄讀取或寫入。您也可以在工作階段期間使用 /memory 切換它，這會將此鍵寫入您的使用者設定。

• 範圍：任何檔案
• 類型：布林值
  • 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 或更高版本。

• 範圍：任何檔案
• 類型：字元數，正整數。Claude Code 將值限制在 4000 到 128000 的範圍內
• 預設：未設定，因此 Claude 內聯接收最多 30,000 個字元

{
  "bashOutputMaxChars": 100000
}

當您設定此鍵時，Claude Code 忽略 BASH_MAX_OUTPUT_LENGTH 環境變數。

claudeMd

注入 CLAUDE.md 風格的指示作為組織管理的記憶，無需部署單獨的檔案。Claude Code 將文字作為受管記憶條目載入，位於使用者和專案 CLAUDE.md 檔案之前。

• 範圍：受管
• 類型：字串，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 檔案。在大型單一儲存庫中，使用它跳過與您的工作無關的其他團隊的 CLAUDE.md 檔案；排除無關的 CLAUDE.md 檔案在大型程式碼庫指南中介紹了該情況。模式與絕對檔案路徑匹配。

• 範圍：任何檔案
• 類型：字串陣列，每個都是 glob 模式或絕對路徑
• 預設：未設定，因此 Claude Code 載入它找到的每個 CLAUDE.md

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

排除僅適用於使用者、專案和本機記憶檔案；受管原則 CLAUDE.md 檔案無法被排除。

env

為每個工作階段和 Claude Code 從中啟動的子程序設定環境變數。環境變數參考中的大多數變數都可以放在這裡，這是如何將其應用於每個工作階段或將其推出到您的團隊的方式。專案和本機設定無法設定其中一些。

• 範圍：任何檔案
• 類型：將變數名稱對應到字串值的物件
• 預設：未設定

此範例關閉自動壓縮並通過代理路由 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 和詳細的測試版追蹤對 ENABLE_BETA_TRACING_DETAILED 和 BETA_TRACING_ENDPOINT。

  • OpenTelemetry 匯出器變數，開啟遙測、選擇它的去向或選擇它捕獲的內容：

    • CLAUDE_CODE_ENABLE_TELEMETRY，加上增強遙測測試版對 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.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 或更高版本，忽略令牌需要 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 中顯示為倒帶程式碼（檢查點），在那裡切換它會將此鍵寫入您的使用者設定。

• 範圍：任何檔案
• 類型：布林值
  • 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。

• 範圍：任何檔案
• 類型：布林值
  • true：Claude Code 壓縮符合條件的閒置對話
  • false：Claude Code 不會在您的工作階段閒置時進行壓縮
• 預設：true
• 每個工作階段的覆寫：DISABLE_AUTO_COMPACT 會連同自動壓縮一起關閉閒置壓縮

{
  "idleCompaction": false
}

若要在終端機工作階段內關閉或開啟閒置壓縮，請執行 /config 並變更閒置壓縮列。您的選擇會儲存到您的使用者設定並立即套用。此列需要 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 在 plan mode 中寫入的計畫檔案的儲存位置。Claude Code 相對於專案根目錄解析路徑。

• 範圍：任何檔案
• 類型：字串，相對於專案根目錄的路徑
• 預設：未設定，因此 Claude Code 使用 ~/.claude/plans

{
  "plansDirectory": "./plans"
}

在以下這類情況中，Claude Code 會將計畫儲存在 ~/.claude/plans，而非您設定的目錄：

• 位於專案根目錄之外：路徑解析到專案根目錄之外，例如 "../plans"。
• 在 macOS、Linux 和 WSL 上使用反斜線：解析後的路徑包含反斜線，例如 Windows 風格的 "docs\\plans"。請改寫為 "docs/plans"，這在 Windows 上也適用。

skillListingBudgetFraction

每個回合，Claude 看到您的 skills 清單及其描述，Claude Code 將該清單上限設定為上下文視窗的一部分。當清單超過上限時，Claude Code 保留每個 skill 的名稱，但刪除最少使用 skills 的描述，因此 Claude 仍然可以呼叫這些 skills，但不太可能自己選擇一個。提高此鍵以保持更多描述可見，代價是每個回合更多上下文。

• 範圍：任何檔案
• 類型：數字，大於 0 且最多 1 的分數
• 預設：0.01，保留上下文視窗的 1%

{
  "skillListingBudgetFraction": 0.02
}

要查看清單使用多少上下文以及哪些 skills 貢獻最多，請執行 /doctor。

skillListingMaxDescChars

每個回合，Claude 看到您的 skills 清單，顯示每個 skill 的 description 和 when_to_use 文字。此鍵限制 Claude Code 每個 skill 顯示多少字元的該文字；較長的文字在上限處被切割。

• 範圍：任何檔案
• 類型：字元數，正整數
• 預設：1536

{
  "skillListingMaxDescChars": 2048
}

提高它以保持長描述完整，代價是每個回合更多上下文；降低它以在 skillListingBudgetFraction 下適應更多 skills。

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 與受管設定讀取。當這些都未設定此設定鍵時，設定了此設定鍵的專案或本機設定檔會關閉此功能，而非被忽略。
• 類型：Boolean
  • true：當 claude.ai 用量上限停止您的工作階段後，Claude Code 會在開啟的工作階段中等待，並於重設後自動繼續任務
  • false：Claude Code 不會自行開始等待。您仍可從用量上限選項選單中自行開始等待
• 預設值：true

{
  "autoContinueAtUsageLimit": false
}

在 /config 中顯示為 Continue automatically at usage limit，會將此設定鍵寫入使用者設定；當受管設定或 --settings 旗標設定了此設定鍵時，Claude Code 會隱藏該列。

autoScrollEnabled

在全螢幕渲染中，跟隨新輸出捲動至對話底部。關閉此項目後，當 Claude 持續工作時，畫面會停留在您捲動到的位置；權限提示仍會捲動進入可見範圍。

• 範圍：Any file
• 類型：Boolean
  • true：對話會跟隨新輸出捲動至底部
  • false：當 Claude 持續工作時，畫面停留在您捲動到的位置；權限提示仍會出現在逐字稿下方
• 預設值：true

{
  "autoScrollEnabled": false
}

當全螢幕渲染開啟時，在 /config 中顯示為 Auto-scroll，會將此設定鍵寫入使用者設定。

axScreenReader

渲染適合螢幕閱讀器的輸出：沒有裝飾性邊框或動畫的純文字。螢幕閱讀器模式使用經典渲染器，因此在其啟用期間 tui 設定沒有作用；附加的背景工作階段仍會以全螢幕渲染。

• 範圍：User or managed。您也可以在透過 --settings 傳入的檔案中設定此設定鍵。Claude Code 會忽略專案與本機設定中的此設定鍵，因此無論是儲存庫或您自己的 .claude/settings.local.json 都無法開啟或關閉螢幕閱讀器模式。
• 類型：Boolean
  • true：Claude Code 使用經典渲染器，渲染沒有裝飾性邊框或動畫的純文字
  • false：Claude Code 正常渲染
• 預設值：未設定，因此螢幕閱讀器模式為關閉
• 個別工作階段覆寫：--ax-screen-reader 優先於 CLAUDE_AX_SCREEN_READER，且兩者在單一工作階段中皆優先於此設定鍵

{
  "axScreenReader": true
}

bashEditDiffEnabled

選擇 Claude Code 是否在 Bash 命令執行期間記錄 Git 儲存庫中有哪些檔案變更。記錄時，您會在命令執行後於終端機中看到它們的差異，而您的 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。
• 類型：Boolean
• 預設值：未設定，因此 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's 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

當您在提示詞輸入中輸入 : 加上簡碼時顯示表情符號建議，並將完整的簡碼（例如 :heart:）替換為其表情符號。將其設為 false 可同時關閉兩者。

• 範圍：Any file
• 類型：Boolean
  • true：Claude Code 在 : 之後顯示表情符號建議，並將完整的簡碼替換為其表情符號
  • false：Claude Code 既不建議表情符號，也不替換簡碼
• 預設值：true

{
  "emojiCompletionEnabled": false
}

請參閱表情符號簡碼。

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
• 類型：Boolean
  • true：Claude Code 會減少或關閉介面動畫，例如旋轉指示器、微光與閃爍效果
  • false：與未設定相同；Claude Code 會顯示其動畫
• 預設值：false

{
  "prefersReducedMotion": true
}

promptSuggestionEnabled

顯示或隱藏提示詞建議，也就是出現在提示詞輸入中的灰色預測內容。將其設為 false，或在 /config 中關閉 Prompt suggestions，即可隱藏它們。

• 範圍：Any file
• 類型：Boolean
  • true：您會在提示詞輸入中看到提示詞建議
  • false：Claude Code 會隱藏提示詞建議
• 預設值：true
• 個別工作階段覆寫：CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION 在單一工作階段中優先於此設定鍵

{
  "promptSuggestionEnabled": false
}

提示詞建議需要開啟遙測的 claude.ai 或 Console 帳戶。在 Amazon Bedrock、Google Cloud's 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 切換開關所寫入的位置。
• 類型：Boolean
  • true：@ 檔案選擇器會排除符合 .gitignore 模式的檔案
  • false：@ 檔案選擇器會包含符合 .gitignore 模式的檔案
• 預設值：true

{
  "respectGitignore": false
}

respondToBashCommands

選擇在您於輸入框中以 ! 前綴執行 shell 命令後，Claude 是否回應。預設情況下，Claude Code 會將命令的輸出加入對話，而 Claude 會對其回覆。將此設定鍵設為 false 可將輸出加入上下文而不回覆，讓您可以執行多個命令後再一併詢問。

• 範圍：Any file
• 類型：Boolean
  • true：Claude Code 將命令的輸出加入對話，而 Claude 會對其回覆
  • false：Claude Code 將輸出加入上下文而不回覆
• 預設值：true

{
  "respondToBashCommands": false
}

請參閱使用 ! 前綴的 shell 模式。

showClearContextOnPlanAccept

當 Claude 在 plan mode 中完成計畫時，會顯示核准選單。規劃可能使用大量上下文，因此此設定鍵會在該選單中加入第一個選項 Yes, clear context and …，用於核准計畫、清除對話上下文，並僅依據計畫開始實作。標籤的其餘部分會指出工作階段將以哪種權限模式繼續，並顯示規劃使用了多少上下文。

• 範圍：Any file
• 類型：Boolean
  • 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 中的值。
• 類型：Boolean
  • true：您會在每次回應後看到回合時間訊息
  • false：Claude Code 會隱藏回合時間訊息
• 預設值：true

{
  "showTurnDuration": false
}

spellcheck

使用您安裝的拼字檢查器，在您輸入時於提示詞輸入中為拼錯的單字加上底線。Claude Code 只檢查輸入框中的文字。輸入時檢查拼字說明了如何安裝 aspell、hunspell 或 ispell，以及檢查器涵蓋的範圍。需要 Claude Code v2.1.235 或更新版本。

• 範圍：User or managed。會整體套用設定了此項目之最高層級的區塊。
• 類型：物件，包含 enabled（Boolean）、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
• 類型：Boolean
  • 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（Boolean）
• 預設值：未設定，因此沒有狀態列

此範例會輸出模型名稱與上下文使用量，並加入兩個字元的水平間距：

{
  "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 執行 subagent 時，Claude Code 會在提示詞下方的任務顯示區中列出它們，每個 subagent 一列，顯示 name · description · token count。此設定鍵讓您執行自己的命令來改寫這些列，例如以百分比顯示每個 subagent 的上下文使用量。每次重新整理時，Claude Code 會將可見的列以一個 JSON 物件透過 stdin 傳送，其中的 tasks 陣列包含每個 subagent 的 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\"}'"
  }
}

請參閱 Subagent 狀態列。

syntaxHighlightingDisabled

Claude Code 會以其內建的語法突顯器，依語言為終端機中顯示的差異、程式碼區塊與檔案預覽上色。將此設定鍵設為 true 即可改以純文字顯示，例如當色彩與您的終端機主題衝突或拖慢螢幕閱讀器時。

• 範圍：Any file
• 類型：Boolean
  • true：Claude Code 會關閉差異、程式碼區塊與檔案預覽中的語法突顯
  • false：Claude Code 會突顯語法
• 預設值：false

{
  "syntaxHighlightingDisabled": true
}

terminalProgressBarEnabled

部分終端機可以在分頁或工作列上顯示其中執行之程式的進度指示器。當 Claude 工作時，Claude Code 會向終端機回報進行中的狀態，讓您可以從其他分頁或視窗看出工作階段是否仍在忙碌。當回合結束後仍有背景 subagent 或動態工作流程在執行時，指示器會保持顯示，並在工作階段閒置後清除。

Claude Code 只在支援此指示器的終端機中回報：ConEmu、Ghostty 1.2.0 或更新版本，以及 iTerm2 3.6.6 或更新版本。將此設定鍵設為 false 可讓 Claude Code 停止回報。在 /config 中顯示為 Terminal progress bar。

• 範圍：Any file。當沒有設定檔設定此項目時，會套用舊版本在 ~/.claude.json 中的值。
• 類型：Boolean
  • true：您會在支援的終端機中看到終端機進度列
  • false：Claude Code 會隱藏終端機進度列
• 預設值：true

{
  "terminalProgressBarEnabled": false
}

terminalTitleFromRename

Claude Code 會設定您終端機分頁的標題。預設情況下，它會使用從對話產生的標題，而一旦您以 /rename 或 --name 為工作階段命名，分頁就會改為顯示該名稱。將此設定鍵設為 false，即使在您為工作階段命名後，分頁仍會保留產生的標題。名稱本身仍然生效，因此 /resume <name> 和工作階段選擇器都能找到它。

• 範圍：Any file
• 類型：Boolean
  • 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 會將其關閉