所有設定

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 以開啟選擇器，顯示目前的選擇、可以提供建議的模型和無顧問。Claude Code 會將您的選擇儲存到 ~/.claude/settings.json 中的此金鑰。如果您從遠端控制用戶端或附加到遠端工作者的工作階段中選擇，該選擇僅適用於該工作階段，不會變更此金鑰。

如果您的帳戶需要使用額度同意，請先執行 /model fable 以接受。在您這樣做之前，在 /advisor 中選擇 Fable 不會儲存任何內容，Claude Code 會告訴您先執行 /model fable。

• 範圍: 任何檔案
• 類型: 字串，別名之一 "fable"、"opus" 或 "sonnet"，解析為 Claude Code 該模型系列的目前預設版本，或完整模型 ID，例如 "claude-opus-5-5"
• 預設: 未設定，因此顧問已關閉
• 每個工作階段的覆蓋: --advisor 優先於此金鑰一個工作階段。CLAUDE_CODE_DISABLE_ADVISOR_TOOL關閉顧問，此金鑰無法將其重新開啟

{
  "advisorModel": "opus"
}

此金鑰對顧問不可用的提供者（例如 Amazon Bedrock 和 AWS 上的 Claude Platform）無效。"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 而不是更高的等級。

• 範圍: 任何檔案
• 類型: 布林值
  • true: 無效；思考已經開啟
  • false: Claude Code 為每個工作階段關閉延伸思考
• 預設: 未設定，因此思考對支援它的模型開啟
• 每個工作階段的覆蓋: MAX_THINKING_TOKENS優先於此金鑰一個工作階段：0 關閉思考，受相同的模型和提供者限制如 false，正值開啟思考，即使此金鑰為 false。在自適應推理模型上，數字本身被忽略

{
  "alwaysThinkingEnabled": false
}

availableModels

限制人們可以為主要工作階段、子代理、技能和顧問選擇的模型。受管清單限制 /model、--model 和開發人員自己檔案中的 model 金鑰；清單外的模型無法選擇。使用預設的前綴符合，這不會單獨觸及預設選項；將其與 enforceAvailableModels 配對以實現該目的。

• 範圍: 任何檔案。在受管設定中部署以為組織強制執行。
• 類型: 模型別名或 ID 的陣列
• 預設: 未設定，因此每個模型都可用

此範例僅允許人們選擇 Sonnet 和 Haiku 模型：

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

模型 ID 項目（例如 "claude-opus-5"）也允許擴展它的更新版本，例如 Opus 5.5。要阻止其中一個版本，請使用 deniedModels。要使每個模型 ID 項目僅允許它命名的版本，請使用 availableModelsMatch。請參閱限制模型選擇。

availableModelsMatch

選擇 availableModels 項目如何符合模型 ID。預設情況下，模型 ID 項目也允許擴展它的更新版本，因此 "claude-opus-5" 允許 Opus 5.5。使用 "exact"，每個模型 ID 項目僅允許它命名的版本，因此該模型的更新版本保持被阻止，直到您列出它。需要 Claude Code v2.1.283 或更新版本。

• 範圍: 受管。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"，預設選項也限制為列出的模型，只要清單至少命名一個模型或系列。請參閱阻止特定模型或版本。

deniedModels

阻止特定模型，無論是否有 availableModels 允許清單，即使該清單允許它們。Claude Code 從 /model 選擇器隱藏被阻止的模型，該模型無法在強制執行 availableModels 的任何地方選擇。預設選項上的工作階段也不執行被阻止的模型，如阻止特定模型或版本所述。需要 Claude Code v2.1.283 或更新版本。

• 範圍: 受管。Claude Code 在使用者、專案和本地設定以及 --settings 中忽略金鑰，並帶有警告
• 類型: 模型別名或 ID 的陣列
  • 系列別名（例如 "opus"）阻止該系列中的每個模型
  • 模型 ID（例如 "claude-opus-5-5"）在每個拼寫中阻止該版本，包括日期和提供者特定 ID
  • 沒有次要版本的模型 ID（例如 "claude-opus-5"）也阻止更新的次要版本，例如 Opus 5.5。寫 "claude-opus-5-0" 以僅阻止 Opus 5
  • best、opusplan 和 default 項目被忽略
• 預設: 未設定，因此沒有模型被阻止

此範例允許 Opus 和 Sonnet 模型，並阻止 Opus 5.5：

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

請參閱阻止特定模型或版本。

effortLevel

為您尚未儲存級別的模型設定預設努力級別。較低的級別在直接任務上更快且更便宜，較高的級別在複雜問題上推理更深入。

當您在機器上的互動工作階段中執行 /effort low、medium、high 或 xhigh 時，Claude Code 會在 modelSettings 下為活動模型儲存級別，而不是寫入此金鑰。在 v2.1.251 之前，/effort 寫入此金鑰。

在同一設定檔中，Claude Code 使用模型的儲存級別而不是此金鑰。modelSettings說明跨檔案優先順序。

在附加到遠端工作者的工作階段中、在 -p 執行中以及在 Agent SDK 中，/effort 僅適用於該工作階段。調整努力級別列出也僅適用於該工作階段的互動選擇。/effort 列印的訊息說明發生了什麼。

• 範圍: 任何檔案
• 類型: 字串，其中之一：
  • "low": 最少推理，用於短期、範圍內、延遲敏感且不是智慧敏感的任務
  • "medium": 減少成本敏感工作的令牌使用，可以權衡一些智慧
  • "high": 平衡令牌使用和智慧
  • "xhigh": 更深入的推理，令牌支出更高
• 預設: 未設定
• 每個工作階段的覆蓋: --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 模型設定描述它解析為的模型。availableModels 允許清單限制您可以命名的模型，但使用預設的前綴符合，它不會重新對應您帳戶類型的預設，因此預設仍可解析為清單外的模型。此金鑰關閉該間隙。需要 Claude Code v2.1.175 或更新版本。

當您的組織部署任何受管設定時，Claude Code 僅從受管來源讀取此金鑰，並忽略您其他檔案中的此金鑰。

如需了解此設定鍵如何套用於啟動時的模型檢查，請參閱 Amazon Bedrock 和 Google Cloud 的 Agent Platform。

• 範圍: 任何檔案
• 類型: 布林值
  • true: 當預設會解析為 availableModels 外的模型時，Claude Code 將其解析為清單中第一個可用的模型
  • false: 此金鑰不會改變預設如何解析
• 預設: false

此範例將命名選擇限制為 Sonnet 和 Haiku 模型，並使預設解析為其中第一個可用的：

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

當 availableModels 未設定或為空時，此金鑰無效。請參閱為預設模型強制執行允許清單。需要 Claude Code v2.1.175 或更新版本。

fallbackModel

命名備份模型供 Claude Code 在您的主要模型過載或不可用時依序嘗試。Claude Code 為該輪的其餘部分切換到備用模型鏈中下一個可用的模型，並顯示通知。沒有鏈的情況下，Claude Code 重試相同的模型，然後顯示伺服器的錯誤，您重試或自己切換模型。

切換意味著在備用模型上進行一輪冷提示快取；您的下一條訊息首先再次嘗試主要模型。

• 範圍: 任何檔案
• 類型: 模型別名或 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

為可用的工作階段開啟快速模式，用於互動工作，例如快速迭代或實時除錯，您想要以更高的每令牌成本換取速度。您通常不會手動編輯此金鑰：執行 /fast 將 fastMode: true 寫入 ~/.claude/settings.json，再次執行以關閉快速模式會移除金鑰。快速模式僅在 Opus 5.5、Opus 5 和 Opus 4.8 上執行：從另一個模型開啟它會將您切換到 Opus，切換到不支援的模型會關閉它。請參閱在快速模式開啟時切換模型。

• 範圍: 任何檔案
• 類型: 布林值
  • 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 擴充功能和雲端工作階段。

• 範圍: 任何檔案
• 類型: 布林值
  • true: 儲存的 fastMode: true 不再在工作階段開始時開啟快速模式，因此每個人在他們想要的每個工作階段中執行 /fast；使用 --settings 傳遞的 fastMode: true 仍然計為該工作階段，除非受管設定設定此金鑰
  • false: 儲存的 fastMode: true 在之後每個工作階段的開始時開啟快速模式
• 預設: false

{
  "fastModePerSessionOptIn": true
}

請參閱要求每個工作階段的選擇加入。

language

預設讓 Claude 以英文以外的語言回應。回應沒有固定清單：Claude Code 將值逐字傳遞給 Claude 作為始終以該語言回應的指令，因此任何 Claude 可以讀取的語言名稱都有效。Claude Code 不檢查值，因此拼寫錯誤的名稱會按原樣到達 Claude，而不是產生錯誤。相同的值設定語音聽寫的語言，它確實有支援的聽寫語言的固定清單，以及自動生成的工作階段標題。

• 範圍: 任何檔案
• 類型: 字串，任何語言名稱，例如 "japanese"、"spanish" 或 "french"；Claude Code 不驗證它
• 預設: 未設定；工作階段標題然後符合您對話的語言

{
  "language": "japanese"
}

maxEffortLevel

限制工作階段可以使用的努力級別，保留較低的級別可用。任何更高的級別改為在上限執行，包括來自 /effort、/model 選擇器、--effort、CLAUDE_CODE_EFFORT_LEVEL、技能或子代理的 effort frontmatter 或模型自己的預設。Claude Code 在每個請求之前自己應用上限，因此它在每個提供者上保持，包括 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry。需要 Claude Code v2.1.267 或更新版本。

• 範圍: 任何檔案。在受管設定中部署以為組織強制執行。當多個範圍設定上限時，最低的適用，因此在一個範圍中設定的上限無法從另一個範圍提高
• 類型: 字串，其中之一 "low"、"medium"、"high"、"xhigh" 或 "max"。"max" 值設定無上限
• 預設: 未設定，因此無上限適用
• 每個模型的上限: 將 maxEffortLevel 新增到模型的 modelSettings 項目。該項目在設定來源（例如您的使用者設定或一個受管來源）中設定兩者的範圍內僅替換該模型的此金鑰。在那裡設定 "max" 以豁免該模型免受該來源的上限；Claude Code 仍然應用來自其他來源的上限

此範例將每個模型限制在 medium，並豁免 Sonnet 4.6：

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

當您的組織也為模型設定努力限制時，兩個上限中較低的適用。

model

設定每個新工作階段使用的模型，因此您不必每次都使用 /model 選擇一個。在此設定它不會阻止您在工作階段中期切換。如果您的管理員設定組織預設模型以覆蓋使用者選擇，即使您在使用者、專案或本地設定中設定此金鑰，您也會獲得該模型。

• 範圍: 任何檔案
• 類型: 字串，模型別名或完整模型 ID
• 預設: 未設定，因此 Claude Code 使用您帳戶的預設模型
• 每個工作階段的覆蓋: --model 優先於 ANTHROPIC_MODEL，兩者優先於此金鑰一個工作階段，包括優先於受管 model；availableModels 清單仍然適用於選擇

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

此處的值優先於 ANTHROPIC_DEFAULT_MODEL，Claude Code 僅在沒有其他內容選擇模型時使用。

modelOverrides

將 Anthropic 模型 ID 對應到提供者特定的模型 ID，例如 Amazon Bedrock 推論設定檔 ARN。每個模型選擇器項目然後在呼叫提供者 API 時使用其對應的值。管理員在Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry上使用此項以將每個模型版本路由到特定的推論設定檔、版本名稱或部署，以進行治理、成本分配或區域路由。

• 範圍: 任何檔案
• 類型: 將模型 ID 對應到提供者模型 ID 的物件
• 預設: 未設定

此範例將 Opus 4.6 的每個呼叫路由到命名的 Bedrock 推論設定檔：

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

請參閱按版本覆蓋模型 ID。

modelPicker

列出 /model 選擇器提供的模型，按您寫入的順序和您選擇的標籤下，因此選擇器列出您的組織執行的模型，在內建陣容之後或代替它。每行的 model 逐字取用，因此它接受 --model 接受的任何內容：別名（例如 opus）、Anthropic 模型 ID 或 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 LLM 閘道的提供者格式 ID。需要 Claude Code v2.1.242 或更新版本。

• 範圍: 使用者或受管。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 或更新版本。將其設定為您的 Claude Code 版本已知的模型 ID，例如 claude-opus-4-8，在其 model 比您的版本更新的項目上。Claude Code 然後將該已知模型的能力和努力預設應用於項目，而不是將其模型視為未知。項目的標籤和 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 主控台讀取它們。需要 Claude Code v2.1.242 或更新版本。

• 範圍: 受管。透過伺服器受管設定、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 或更新版本。較早的版本忽略 multiplier 超過 1 並帶有警告，並保留設定的其餘部分。

如需步驟，包括如何確認費率有效，請參閱以您的合約費率報告支出。

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

為您使用的每個模型儲存努力級別。需要 Claude Code v2.1.251 或更新版本。

在機器上的互動工作階段中，當您使用 /effort 或 /model 選擇器的努力滑塊將 low、medium、high 或 xhigh 儲存為預設時，Claude Code 在您使用的模型下在此處寫入該級別，因此您很少自己編輯此金鑰。當您在 VS Code 擴充功能的模型選擇器中選擇其中一個級別時，Claude Code 以相同方式在此處儲存它。effortLevel 項目列出 /effort 僅適用於該工作階段的工作階段。

手動編輯金鑰以變更或移除您儲存的級別。

此處模型的 effortLevel 優先於同一設定檔中的頂級 effortLevel。跨檔案，Claude Code 分別解析每個模型：最高優先順序設定檔設定該模型的 effortLevel 或適用於該模型的頂級 effortLevel 決定，因此受管設定中的 effortLevel 優先於您在使用者設定中儲存的級別。調整努力級別列出還可以覆蓋儲存級別的內容，例如啟動時的 --effort。

要限制一個模型的努力而不是設定其級別，將 maxEffortLevel 欄位新增到該模型的項目。該欄位需要 Claude Code v2.1.267 或更新版本。

• 範圍: 任何檔案
• 類型: 將模型名稱對應到物件的物件，該物件可包含下列任一欄位：
  • 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，並將該模型的別名、日期後綴、[1m] 和識別的提供者特定 ID 符合到同一項目。

此範例將 Opus 5.5 保持在 high，而其他模型使用它們自己的儲存或預設級別：

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

執行 /effort auto 以清除您為正在使用的模型儲存的級別。Claude Code 保留其他項目和任何頂級 effortLevel。

outputStyle

按名稱選擇輸出樣式。輸出樣式是一組儲存的指令，改變 Claude 的角色、語調和輸出格式，例如內建的解釋性和學習樣式或您自己寫的。

如果您在工作階段期間變更此金鑰，Claude 從您的下一條訊息開始使用新樣式。如需該訊息在提示快取中的成本，請參閱變更輸出樣式。在 v2.1.251 之前，編輯僅在您執行 /clear 或開始新工作階段後適用。

• 範圍: 任何檔案
• 類型: 字串，內建或自訂輸出樣式的名稱
• 預設: 未設定，因此 Claude Code 使用預設樣式

此範例選擇內建的解釋性樣式，在任務之間新增教育見解：

{
  "outputStyle": "Explanatory"
}

promptCacheTtl

選擇提示快取保持主要對話多長時間。此金鑰適用於您的互動、-p 和 Agent SDK 輪，以及 Claude Code 與它們內聯執行的協助程式。一小時的生命週期在較長的中斷中保持快取溫暖，API 以比五分鐘生命週期更高的費率計費每個快取寫入。需要 Claude Code v2.1.242 或更新版本。

• 範圍: 任何檔案
• 類型: 字串，其中之一：
  • "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 顯示摺疊的存根。

• 範圍: 任何檔案
• 類型: 布林值
  • true: 當您使用 Ctrl+O 展開思考時，您看到完整思考摘要
  • false: Anthropic API 編輯思考區塊，Claude Code 顯示摺疊的存根
• 預設: false

{
  "showThinkingSummaries": true
}

編輯僅改變您看到的內容，而不是模型生成的內容。要減少思考支出，降低預算或停用思考。

subagentPromptCacheTtl

選擇提示快取保持 Claude Code 在主要對話外進行的請求多長時間。此金鑰適用於子代理、工作流程和 Claude Code 自己的背景和協助程式請求，例如壓縮和工作階段標題。一小時的生命週期在較長的中斷中保持快取溫暖，API 以比五分鐘生命週期更高的費率計費每個快取寫入。需要 Claude Code v2.1.242 或更新版本。

• 範圍: 任何檔案
• 類型: 字串，其中之一：
  • "5m": 快取保持五分鐘
  • "1h": 快取保持一小時
• 預設: 未設定，因此這些請求中的每一個獲得其預設生命週期
• 每個工作階段的覆蓋: FORCE_PROMPT_CACHING_5M優先於所有其他，然後 CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL，然後此金鑰，然後 ENABLE_PROMPT_CACHING_1H，要求每個請求的一小時生命週期。如需子代理自己的 frontmatter 值排名的位置，請參閱自己選擇 TTL

此範例為子代理和主要對話外的其他請求提供一小時生命週期：

{
  "subagentPromptCacheTtl": "1h"
}

此金鑰涵蓋 promptCacheTtl 不涵蓋的請求，因此設定兩者以為 Claude Code 進行的每個請求選擇生命週期。如需子代理的快取與主要對話的快取有何不同，請參閱子代理和快取。

switchModelsOnFlag

選擇當安全分類器標記請求時會發生什麼：切換到備用模型並繼續，或暫停以便您可以在切換和編輯提示之間選擇。

• 範圍: 任何檔案。在 /config 中顯示為訊息被標示時切換模型，選項為自動切換和每次詢問。
• 類型: 布林值
  • true: Claude Code 切換到備用模型並繼續
  • false: 在互動工作階段中，Claude Code 暫停以便您可以在切換和編輯提示之間選擇；在無法顯示對話框的地方，例如 -p 執行，標記的請求以錯誤結束
• 預設: 未設定。Claude Code 會自動切換，但在互動工作階段中可能會先詢問

{
  "switchModelsOnFlag": false
}

請參閱切換前詢問。

ultracode

使用ultracode啟動工作階段。開啟時，Claude 為每個實質性任務規劃工作流程，而不是等待您要求。Claude 僅在為您啟用動態工作流程且您的模型支援 xhigh 努力時規劃工作流程。此金鑰不會改變工作階段的努力級別：ultracode 在工作階段使用的任何級別執行。Claude Code 讀取此金鑰但永遠不寫入它：/effort ultracode 為目前工作階段開啟 ultracode。

• 範圍: 任何檔案
• 類型: 布林值
  • true: 當為您啟用動態工作流程且您的模型支援 xhigh 時，工作階段以 ultracode 開啟開始
  • false: 工作階段以 ultracode 關閉開始
• 預設: 未設定，因此 ultracode 已關閉
• 每個工作階段的覆寫: /effort ultracode 在沒有此設定鍵的情況下為一個工作階段開啟 ultracode，/effort ultracode off 在此設定鍵為 true 時為一個工作階段關閉它。--effort ultracode 旗標也會為一個工作階段開啟它，並使用 xhigh effort

{
  "ultracode": true
}

工作階段的努力級別來自 effortLevel、modelSettings 和其他努力來源，努力上限（例如 maxEffortLevel）降低該級別而不關閉 ultracode。這和 /effort ultracode off 形式需要 Claude Code v2.1.284 或更新版本。在 v2.1.284 之前，ultracode: true 在 xhigh 努力執行工作階段，低於 xhigh 的努力上限保持 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、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 是否在 plan mode 中使用自動模式分類器來檢查 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 本身需要的檔案保持可讀，例如您的 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.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 旗標，並忽略 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。不受信任的儲存庫無法為您跳過對話。
• 類型：布林值
  • true：Claude Code 在工作階段進入 bypassPermissions 模式前跳過確認對話
  • false：與未設定相同；除非這些檔案中的另一個設定 true，否則對話會出現
• 預設值：未設定，因此對話會出現

{
  "skipDangerousModePermissionPrompt": true
}

沙箱設定

將 Claude 執行的命令與您的檔案系統、網路和憑證隔離。關於沙箱機制的運作方式和平台需求，請參閱沙箱機制。

sandbox

透過沙箱機制將 Claude 執行的 Bash 命令與您的檔案系統和網路隔離。使用 enabled 開啟沙箱，再透過 filesystem、network 和 credentials 子物件縮小或擴大沙箱化命令可存取的範圍。沙箱可在 macOS、Linux 和 WSL2 上執行。

• 範圍：Any file
• 類型：包含 enabled、failIfUnavailable、autoAllowBashIfSandboxed、excludedCommands、allowUnsandboxedCommands、enableWeakerNestedSandbox、enableWeakerNetworkIsolation、allowAppleEvents、allowNestedUserNamespaces、bwrapPath、socatPath、ignoreViolations 和 ripgrep，以及 filesystem、network 和 credentials 物件的物件
• 預設值：未設定，因此 Claude Code 會在沒有沙箱的情況下執行命令

以下設定會開啟沙箱、略過沙箱化命令的權限提示、在沙箱外執行 docker、開放兩個額外的寫入路徑、隱藏您的 AWS 憑證檔案，並預先允許 GitHub 和 npm：

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

當受管設定設定了 enabled 或 failIfUnavailable 等布林值鍵時，該值會覆寫開發人員所設定的任何值。Claude Code 會在工作階段載入的所有設定範圍之間合併陣列鍵，因此開發人員可以附加項目；關於僅限受管設定的鎖定，請參閱防止開發人員擴大政策。若要為組織強制要求沙箱，請參閱使用受管設定強制執行沙箱機制。

sandbox.enabled

為 Bash 命令開啟沙箱機制。當您在 /sandbox 面板中選擇模式時，Claude Code 會將此鍵寫入目前專案的 .claude/settings.local.json；若要讓每個專案都使用沙箱，請在 ~/.claude/settings.json 中設定。

• 範圍：Any file，但對專案和本機設定有所限制
• 類型：布林值
  • true：Claude Code 會將 Bash 命令沙箱化
  • false：Bash 命令在沙箱外執行
• 預設值：false

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

在 Linux 和 WSL2 上，沙箱需要 bubblewrap 和 socat；請參閱設定 Linux 和 WSL2。當沙箱無法啟動時，Claude Code 會在沙箱外執行命令，除非您也設定了 failIfUnavailable。

sandbox.failIfUnavailable

當 sandbox.enabled 為 true，但因缺少相依套件或平台不受支援而導致沙箱無法啟動時，讓 Claude Code 在啟動時以錯誤結束。若未設定此鍵，Claude Code 會在沙箱外執行命令。將沙箱機制視為安全關卡的受管部署可以使用此設定。

在沙箱不支援的平台上，開啟此鍵時 Claude Code 不會啟動。請參閱使用受管設定強制執行沙箱機制。

• 範圍：Any file，但對專案和本機設定有所限制
• 類型：布林值
  • true：當 sandbox.enabled 為 true 但沙箱無法啟動時，Claude Code 會在啟動時以錯誤結束
  • false：當沙箱無法啟動時，Claude Code 會在沙箱外執行命令
• 預設值：false

以下設定會讓每台受管機器都將命令沙箱化，否則拒絕啟動：

{
  "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，但僅複製檔案描述元的重新導向（如 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 仍可讀取或寫入其下的路徑。

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 或建置工具等子程序需要寫入專案外部時，請使用此項。

• 範圍：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 內。當您使用沙箱是為了控制命令連線的目的地，而非它們寫入的內容時，請使用此項。需要 Claude Code v2.1.216 或更新版本。

• 範圍：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。關於可設定此項的完整來源清單，以及關閉隔離後會有哪些變化，請參閱停用檔案系統隔離。需要 Claude Code v2.1.216 或更新版本。

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_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_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 開頭的訊息。

對於符合以下所有條件的對話，閒置壓縮預設為開啟：

• 工作階段：您處於互動式終端機工作階段中
• 自動壓縮：autoCompactEnabled 已開啟
• 提示快取：對話使用一小時提示快取 TTL
• 功能旗標：Claude Code 可以從 Anthropic 擷取功能旗標
• 大小：對話的上下文已達到 token 閾值，您可以從其預設值 200,000 變更此閾值
• 閒置時間：自上次請求以來已經過約 54 分鐘，且您的電腦在那時處於喚醒狀態

若要關閉閒置壓縮，請將此鍵設定為 false。

• 範圍：任何檔案
• 類型：布林值
  • true：Claude Code 壓縮符合條件的閒置對話
  • false：Claude Code 不會在您的工作階段閒置時進行壓縮
• 預設：true
• 每個工作階段的覆寫：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 在 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
}

請參閱表情符號簡碼。需要 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 的回覆中時，頁尾會出現一個連結至 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 會將其關閉

{
  "tui": "fullscreen"
}

在 tmux -CC 下或透過 SSH 連線至 Windows 時，除非您設定 CLAUDE_CODE_NO_FLICKER=1，否則 Claude Code 會保留經典渲染器。從 agent view 開啟的背景工作階段一律使用全螢幕渲染器，不受此設定影響。

verbose

預設情況下，逐字稿會將每個工具呼叫收合為簡短摘要，例如 Claude 執行的命令及其輸出的行數，當您需要詳細資訊時，按下 Ctrl+O 即可將整份逐字稿切換為展開檢視。將此設定鍵設為 true，即可在每個工具呼叫發生時以內嵌方式顯示其完整的輸入與輸出，這在您為 hook、MCP 伺服器或冗長的 shell 命令除錯時很有用。在 /config 中顯示為 Verbose output。

• 範圍：Any file。當沒有設定檔設定此項目時，會套用舊版本在 ~/.claude.json 中的值。
• 類型：Boolean
  • true：您會看到完整的工具輸出
  • false：您會看到截斷的工具輸出摘要
• 預設值：false
• 個別工作階段覆寫：--verbose 在單一工作階段中優先於此設定鍵

{
  "verbose": true
}

viewMode 值或持續生效的 /focus 選擇會在每個工作階段覆寫此設定鍵。

viewMode

設定 Claude Code 啟動時的逐字稿檢視："default"、"verbose" 或 "focus"。設定後，它會同時覆寫持續生效的 /focus 選擇與 verbose 設定。

• 範圍：Any file
• 類型：字串，為下列之一：
  • "default"：工具輸出被截斷的一般逐字稿
  • "verbose"：含有完整工具輸出的逐字稿
  • "focus"：僅顯示您最後的提示詞、附有編輯差異統計的工具呼叫單行摘要，以及最終回應。Focus 檢視需要全螢幕渲染器
• 預設值：未設定，因此套用 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
• 類型：物件，包含 Boolean 的 enabled、僅在按住模式下適用的 Boolean 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 物件的單一 Boolean 形式開啟語音聽寫。當兩者都設定時，套用 voice.enabled。

• 範圍：Any file
• 類型：Boolean
  • true：當您以 claude.ai 帳戶登入且您組織的政策允許語音時，語音聽寫為開啟，除非已設定 voice.enabled
  • false：語音聽寫為關閉，除非已設定 voice.enabled
• 預設值：未設定

{
  "voiceEnabled": true
}

wheelScrollAccelerationEnabled

在全螢幕渲染中快速捲動時加速滑鼠滾輪的捲動速度。將其設為 false 可讓每個滾輪刻度以固定速率捲動。

• 範圍：Any file
• 類型：Boolean
  • 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 或記憶規則）優先於這些提交和 PR 行，除非該行在受管設定中設定。

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 對此鍵優先