所有設定

​

設定索引

​

模型和回應

​

advisorModel

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

{
  "advisorModel": "opus"
}

​

alwaysThinkingEnabled

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

{
  "alwaysThinkingEnabled": false
}

​

availableModels

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

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

​

availableModelsMatch

• 範圍: 受管。Claude Code 在使用者、專案和本地設定以及 --settings 中忽略金鑰，並帶有警告
• 類型: 字串，其中之一：
  • "prefix": 模型 ID 項目允許其版本和任何用另一個區段擴展它的模型 ID
  • "exact": 模型 ID 項目僅允許它命名的版本，包括該版本的日期 ID，因此 "claude-opus-5" 允許 Opus 5 但不允許 claude-opus-5-5。系列別名（例如 "opus"）仍然允許整個系列，best、opusplan 和 default 項目被忽略
• 預設: "prefix"

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

​

deniedModels

• 範圍: 受管。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 項目被忽略
• 預設: 未設定，因此沒有模型被阻止

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

​

effortLevel

• 範圍: 任何檔案
• 類型: 字串，其中之一：
  • "low": 最少推理，用於短期、範圍內、延遲敏感且不是智慧敏感的任務
  • "medium": 減少成本敏感工作的令牌使用，可以權衡一些智慧
  • "high": 平衡令牌使用和智慧
  • "xhigh": 更深入的推理，令牌支出更高
• 預設: 未設定
• 每個工作階段的覆蓋: --effort 優先於此金鑰一個工作階段，CLAUDE_CODE_EFFORT_LEVEL優先於兩者

{
  "effortLevel": "xhigh"
}

​

enforceAvailableModels

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

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

​

fallbackModel

• 範圍: 任何檔案
• 類型: 模型別名或 ID 的陣列；"default" 擴展為預設模型
• 預設: 未設定，因此失敗的請求不會在另一個模型上重試
• 每個工作階段的覆蓋: --fallback-model 優先於此金鑰一個工作階段

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

​

fastMode

• 範圍: 任何檔案
• 類型: 布林值
  • true: Claude Code 為可用的工作階段開啟快速模式
  • false: 快速模式保持關閉
• 預設: 未設定，因此快速模式已關閉
• 每個工作階段的覆蓋: CLAUDE_CODE_DISABLE_FAST_MODE為一個工作階段關閉快速模式，此金鑰無法將其重新開啟

{
  "fastMode": true
}

​

fastModePerSessionOptIn

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

{
  "fastModePerSessionOptIn": true
}

​

language

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

{
  "language": "japanese"
}

​

maxEffortLevel

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

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

​

model

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

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

​

modelOverrides

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

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

​

modelPicker

• 範圍: 使用者或受管。Claude Code 從受管設定、--settings 和使用者設定讀取金鑰，並在專案和本地設定中忽略它，因此您複製的儲存庫無法重新標籤選擇器。這三個中最高的設定金鑰提供整個陣容，Claude Code 永遠不會合併來自兩個來源的陣容。
• 類型: 具有 options 陣列的物件和可選的 replaceBuiltInOptions 布林值
• 預設: 未設定，因此選擇器顯示內建陣容

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

​

modelPicker 的欄位

• 已刪除: Claude Code 無法提供的行，例如已停用的模型或您的組織無法存取的模型
• 灰顯: 您還無法選擇的行，顯示原因
• 沒有行倖存: Claude Code 保留內建陣容，由允許清單篩選如常

​

modelPricing

• 範圍: 受管。透過伺服器受管設定、MDM 原則、managed-settings.json 檔案或原則協助程式部署金鑰。Claude Code 在使用者、專案和本地設定中、在 --settings 中以及在 Windows 中的使用者可寫HKCU 登錄中忽略它。使用伺服器受管設定時，每個工作階段以列表價格報告成本，直到該工作階段的設定擷取已確認設定。嵌入 Claude Code 的主機應用程式，設定 CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST，可以透過 SDK managedSettings 選項提供自己的表格，Claude Code 僅在沒有受管來源設定金鑰時以及僅在 Claude Code v2.1.246 或更新版本中使用。
• 類型: 具有可選 multiplier 和可選 overrides 對應的物件
• 預設: 未設定，因此 Claude Code 報告列表價格，除非主機應用程式提供表格

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

​

modelPricing 的欄位

​

modelPricing 行適用於哪些模型

• 內建模型的 ID: Claude Code 本身為內建模型使用的金鑰，無論該金鑰是模型自己的 ID（例如 claude-sonnet-4-6）還是其 Bedrock、Agent Platform 或 Foundry ID。Claude Code 將行應用於該模型的每個日期快照 ID 和提供者特定 ID。
• 任何其他金鑰: 不是內建模型 ID 的金鑰，例如閘道模型別名。Claude Code 僅將行應用於該一個 ID。當模型 ID 完全符合您的一個金鑰，也落在以內建模型 ID 為鍵的行下時，Claude Code 使用完全符合。
• Bedrock 應用程式推論設定檔: 一旦 Claude Code 透過您的 modelOverrides 對應或 bedrock:GetInferenceProfile 查詢將設定檔解析為它路由到的模型，Claude Code 將該模型的行應用於設定檔。

​

modelSettings

• 範圍: 任何檔案
• 類型: 將模型名稱對應到物件的物件，該物件可包含下列任一欄位：
  • effortLevel: "low"、"medium"、"high" 或 "xhigh" 其中之一
  • maxEffortLevel: 模型可執行的最高 effort 等級
  • autoCompactWindow: 介於 100000 到 1000000 的 token 數，或 "auto" 表示為該模型調校的視窗。/autocompact 會儲存於此。對於該模型，此值優先於同一設定檔中的頂層 autoCompactWindow。需要 Claude Code v2.1.288 或更新版本
• 預設: 未設定

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

​

outputStyle

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

{
  "outputStyle": "Explanatory"
}

​

promptCacheTtl

• 範圍: 任何檔案
• 類型: 字串，其中之一：
  • "5m": 快取保持五分鐘
  • "1h": 快取保持一小時
• 預設: 未設定，因此每個主要對話請求獲得其預設生命週期
• 每個工作階段的覆蓋: FORCE_PROMPT_CACHING_5M優先於所有其他，然後 CLAUDE_CODE_PROMPT_CACHE_TTL，然後此金鑰，最後 ENABLE_PROMPT_CACHING_1H

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

​

showThinkingSummaries

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

{
  "showThinkingSummaries": true
}

​

subagentPromptCacheTtl

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

{
  "subagentPromptCacheTtl": "1h"
}

​

switchModelsOnFlag

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

{
  "switchModelsOnFlag": false
}

​

ultracode

• 範圍: 任何檔案
• 類型: 布林值
  • true: 當為您啟用動態工作流程且您的模型支援 xhigh 時，工作階段以 ultracode 開啟開始
  • false: 工作階段以 ultracode 關閉開始
• 預設: 未設定，因此 ultracode 已關閉
• 每個工作階段的覆蓋: /effort ultracode 在沒有此金鑰的情況下為一個工作階段開啟 ultracode，/effort ultracode off 在此金鑰為 true 時為一個工作階段關閉它。--effort ultracode 標誌也為一個工作階段開啟它，在 xhigh 努力，需要 Claude Code v2.1.203 或更新版本

{
  "ultracode": true
}

​

權限設定

​

allowManagedPermissionRulesOnly

• 儲存庫的 .claude/ 目錄
• 您的 ~/.claude/skills/ 和 ~/.claude/commands/ 目錄，包括從 claude.ai 同步的 skill
• --add-dir 目錄
• 位於 ~/.claude/skills/ 或專案的 .claude/skills/ 內、以 .claude-plugin 資訊清單宣告的外掛

• 範圍：Managed
• 類型：布林值
  • true：受管設定成為權限規則的唯一設定來源
  • false：Claude Code 除了套用受管規則外，還會套用來自使用者、專案、本機和 --settings 檔案的權限規則
• 預設值：未設定，因此 Claude Code 會套用來自使用者、專案和本機設定以及 --settings 的權限規則，以及受管規則

{
  "allowManagedPermissionRulesOnly": true
}

​

autoMode

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

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

​

autoMode.classifyAllShell

• 範圍：User or managed。讀取位置與 autoMode 相同。
• 類型：布林值
  • true：在自動模式啟用時，Claude Code 會將每個 Bash 和 PowerShell 命令傳送到分類器，並暫停您的 shell 允許規則；在自動模式外，規則仍然適用
  • false：自動模式只會暫停可能執行任意程式碼的允許規則，例如 Bash(*) 和 Bash(python *)；與任何其他允許規則相符的命令會跳過分類器，除非它帶有每個命令允許的網域，每個其他 shell 命令都會通過它
• 預設值：false

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

​

disableAutoMode

• 範圍：Any file。最適合在受管設定中使用，使用者無法覆寫它。也接受在 permissions 下作為 permissions.disableAutoMode。
• 類型：字串 "disable"
• 預設值：未設定

{
  "disableAutoMode": "disable"
}

​

permissions

• 範圍：Any file
• 類型：物件，包含 allow、ask、deny、additionalDirectories、blockReadsOutsideWorkingDirectories、defaultMode、disableBypassPermissionsMode 和 disableAutoMode
• 預設值：未設定

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

​

useAutoModeDuringPlan

• 範圍：User, local, or managed。儲存庫無法為您關閉它。
• 類型：布林值
  • true：與未設定相同；當自動模式可用時，分類器在規劃期間檢查每個 shell 命令，而不是提示您，除了關鍵路徑移除。任何這些檔案中的 false 仍然會關閉它
  • false：您會針對內建唯讀集之外的每個命令獲得權限提示
• 預設值：true

{
  "useAutoModeDuringPlan": false
}

​

permissions.allow

• 範圍：Any file
• 類型：權限規則字串陣列
• 預設值：未設定
• 每個工作階段的覆寫：--allowedTools 為一個工作階段新增允許規則，任何設定檔中的拒絕規則仍然會封鎖它命名的工具

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

​

權限規則語法

​

permissions.ask

• 範圍：Any file
• 類型：權限規則字串陣列
• 預設值：未設定

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

​

permissions.deny

• 範圍：Any file
• 類型：權限規則字串陣列
• 預設值：未設定
• 每個工作階段的覆寫：--disallowedTools 在此設定鍵之外為一個工作階段新增拒絕規則

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

​

permissions.additionalDirectories

• 範圍：Any file，專案和本機項目所給予的沙箱寫入存取權有其限制
• 類型：目錄路徑陣列
• 預設值：未設定
• 每個工作階段的覆寫：--add-dir 和 /add-dir 在此設定鍵之外為一個工作階段新增目錄

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

​

permissions.blockReadsOutsideWorkingDirectories

• 沒有任何模式自動核准的操作涵蓋讀取此類路徑的 shell 命令何時提示您
• 區塊下的沙箱化命令涵蓋沙箱化命令可以讀取的內容

• 範圍：Any file。如果任何檔案設定 true，則區塊適用，因此儲存庫可以為自己開啟區塊，但無法解除您設定的區塊。
• 類型：布林值
  • true：Claude 的檔案工具拒絕讀取工作目錄之外的路徑
  • false：與未設定相同；另一個檔案中的 true 仍然會套用區塊
• 預設值：未設定，因此工作目錄外的讀取遵循您的權限模式

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

​

區塊下的沙箱化命令

• 檔案系統隔離透過 sandbox.filesystem.disabled 關閉
• allowManagedReadPathsOnly 已設定
• 您啟動 Claude Code 的目錄路徑包含 glob 字元，例如 *、? 或 [

• ~/.gitconfig
• $XDG_CONFIG_HOME/git 下的 config、ignore 和 attributes 檔案，預設為 ~/.config/git
• 您的全域 git 設定透過 [include]、[includeIf]、core.excludesFile 或 core.attributesFile 命名的檔案

​

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 自動拒絕每個原本會提示的呼叫；工作目錄內的檔案讀取、不需要核准的其他操作以及預先核准的工具仍然執行，但從網路路徑的讀取除外
  • "bypassPermissions"：Claude Code 在不詢問的情況下執行所有操作
  • "manual"："default" 的別名
• 預設值：未設定
• 每個工作階段的覆寫：--permission-mode 及其 bypassPermissions 的等效項 --dangerously-skip-permissions 對一個工作階段優先於此設定鍵

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

​

permissions.disableBypassPermissionsMode

• 範圍：Any file。通常在受管設定中設定以強制執行組織原則。
• 類型：字串 "disable"
• 預設值：未設定
• 每個工作階段的覆寫：此設定鍵優先於 --dangerously-skip-permissions，在設定此設定鍵時 Claude Code 會拒絕它

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

​

skipAutoPermissionPrompt

• 範圍：User or managed。儲存庫無法為您設定它。
• 類型：布林值
  • true：Claude Code 跳過通知
  • false：與未設定相同；除非這些檔案中的另一個設定 true，否則通知會出現一次
• 預設值：未設定，因此通知會出現一次

{
  "skipAutoPermissionPrompt": true
}

​

skipDangerousModePermissionPrompt

• 範圍：User, local, or managed。不受信任的儲存庫無法為您跳過對話。
• 類型：布林值
  • true：Claude Code 在工作階段進入 bypassPermissions 模式前跳過確認對話
  • false：與未設定相同；除非這些檔案中的另一個設定 true，否則對話會出現
• 預設值：未設定，因此對話會出現

{
  "skipDangerousModePermissionPrompt": true
}

​

沙箱設定

​

sandbox

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

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

​

sandbox.enabled

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

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

​

sandbox.failIfUnavailable

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

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

​

sandbox.autoAllowBashIfSandboxed

• 範圍：Any file
• 類型：布林值
  • true：Claude Code 會在不顯示權限提示的情況下執行沙箱化的 Bash 命令，但自動允許模式所述的情況除外；CLAUDE_CODE_SUBPROCESS_ENV_SCRUB 會關閉自動允許
  • false：沙箱化命令會經過一般權限流程，因此由您的允許規則和權限模式決定。/sandbox 的 Mode 分頁將此稱為一般權限模式
• 預設值：true

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

​

sandbox.excludedCommands

• 範圍：Any file，但對專案和本機設定有所限制
• 類型：命令模式的陣列
• 預設值：未設定，因此不排除任何命令

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

• 以 sudo、eval 或 xargs 開頭的命令
• cd、pushd 或 popd，無論出現在呼叫中的何處
• 命令替換、子 shell，或 if、for 等控制流程區塊
• 重新導向，例如 docker build . > build.log，但僅複製檔案描述元的重新導向（如 2>&1）除外
• 命令名稱來自變數
• 帶有絕對路徑、以 ~ 開頭或包含 .. 區段之路徑引數的 git clone、git init、git worktree add、git worktree move 或 git bundle create

​

sandbox.allowUnsandboxedCommands

• 範圍：Any file，但對專案和本機設定有所限制
• 類型：布林值
  • true：Claude 可在沙箱封鎖命令後，使用 dangerouslyDisableSandbox 參數在沙箱外重試該命令
  • false：Claude Code 會忽略該參數，因此在沙箱執行期間，Claude 執行的命令都會沙箱化，除非它們符合 excludedCommands 項目
• 預設值：true

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

​

sandbox.filesystem

• 範圍：Any file
• 類型：包含 allowWrite、denyWrite、denyRead 和 allowRead 陣列，以及 allowManagedReadPathsOnly 和 disabled 布林值的物件
• 預設值：未設定，因此套用預設的讀取和寫入邊界

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

​

沙箱路徑前綴

• allowWrite 和 denyWrite：在 macOS 上，萬用字元有效。在 Linux 和 WSL2 上，沙箱會掛載具體路徑，因此在移除結尾的 /** 後，若項目仍包含 *、? 或 [，Claude Code 會略過該項目，而該項目不會產生任何效果。Claude Code 會將您 Edit 權限規則中的路徑加入這些清單，因此同樣的限制也適用於它們，且 /sandbox 的 Config 分頁會針對包含萬用字元的 Edit 和 Read 權限規則發出警告。
• denyRead 和 allowRead：萬用字元在所有平台上都有效。在 Linux 和 WSL2 上，Claude Code 會將讀取項目展開為其所比對到的具體路徑，而寫入清單則不會這樣處理。

​

sandbox.filesystem.allowWrite

• 範圍：Any file，但對專案和本機設定有所限制
• 類型：路徑字串的陣列，使用沙箱路徑前綴
• 預設值：未設定，因此沙箱化命令可以寫入工作目錄、每位使用者的暫存目錄、您透過 --add-dir 或 /add-dir 新增的目錄，以及 permissions.additionalDirectories 中的目錄

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

​

sandbox.filesystem.denyWrite

• 範圍：Any file
• 類型：路徑字串的陣列，使用沙箱路徑前綴
• 預設值：未設定

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

​

sandbox.filesystem.denyRead

• 範圍：Any file
• 類型：路徑字串的陣列，使用沙箱路徑前綴
• 預設值：未設定，因此沙箱化命令保有預設讀取存取權，其中包括 ~/.aws/credentials 等憑證檔案

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

​

sandbox.filesystem.allowRead

• 範圍：Any file，但對專案和本機設定有所限制
• 類型：路徑字串的陣列，使用沙箱路徑前綴
• 預設值：未設定

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

​

sandbox.filesystem.allowManagedReadPathsOnly

• 範圍：Managed
• 類型：布林值
  • true：Claude Code 僅採用來自受管設定的 allowRead 項目
  • false：來自其他設定檔的 allowRead 項目可以合併進來
• 預設值：false

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

​

sandbox.filesystem.disabled

• 範圍：User or managed。當受管設定有任何 sandbox.filesystem 設定，或列出 "mode": "deny" 的 sandbox.credentials.files 項目時，只有受管設定能設定此項。
• 類型：布林值
  • true：Claude Code 略過檔案系統隔離，並保留網路隔離
  • false：檔案系統隔離保持開啟
• 預設值：false，因此檔案系統隔離保持開啟

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

​

sandbox.ignoreViolations

• 範圍：Any file，但對專案和本機設定有所限制
• 類型：將命令子字串對應到違規子字串（通常為路徑）陣列的物件
• 預設值：未設定，因此會回報每個違規

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

​

sandbox.enableWeakerNestedSandbox

• 範圍：Any file，但對專案和本機設定有所限制
• 類型：布林值
  • true：內層沙箱會 bind-mount 容器現有的 /proc，而不是掛載新的 /proc
  • false：沙箱會掛載新的 /proc，這在無特權的 Docker 容器中無法運作
• 預設值：false

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

​

sandbox.enableWeakerNetworkIsolation

• 範圍：Any file，但對專案和本機設定有所限制
• 類型：布林值
  • true：macOS 上的沙箱化命令可以存取 com.apple.trustd.agent
  • false：macOS 上的沙箱化命令無法存取系統 TLS 信任服務
• 預設值：false

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

​

sandbox.allowAppleEvents

• 範圍：User or managed
• 類型：布林值
  • true：macOS 上的沙箱化命令可以傳送 Apple Events
  • false：macOS 上的沙箱化命令無法傳送 Apple Events，因此 open 和 osascript 會以錯誤 -600 失敗
• 預設值：false

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

​

sandbox.ripgrep

• 範圍：User or managed
• 類型：包含 command（ripgrep 二進位檔的路徑）和選用 args（要前置的引數陣列）的物件
• 預設值：未設定，因此沙箱使用與 Claude Code 相同的 ripgrep 二進位檔。除非您將 USE_BUILTIN_RIPGREP 設為 0，否則即為內建的二進位檔

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

​

sandbox.bwrapPath

• 範圍：Managed。Claude Code 只從受管設定讀取此項，使使用者、專案或本機檔案無法讓沙箱指向不同的二進位檔。
• 類型：字串，必須是絕對路徑；Claude Code 會捨棄相對路徑並改用 PATH 查找
• 預設值：未設定，因此 Claude Code 會在 PATH 上尋找 bwrap

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

​

sandbox.socatPath

• 範圍：Managed
• 類型：字串，必須是絕對路徑；Claude Code 會捨棄相對路徑並改用 PATH 查找
• 預設值：未設定，因此 Claude Code 會在 PATH 上尋找 socat

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

​

sandbox.credentials

• 範圍：Any file。Claude Code 只會採用來自使用者設定、受管設定和 --settings 旗標的 mask 項目、allowPlaintextInject、awsPairs 和 sigv4。
• 類型：包含 files、envVars、allowPlaintextInject、awsPairs 和 sigv4 的物件
• 預設值：未設定，因此不保護任何憑證

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

​

受管設定中的無效憑證項目

• files 或 envVars 中仍具有有效 path 或 name，且 mode 為 mask 或 deny 的項目（例如其 extract 模式沒有擷取群組），會被降級為 mode: "deny" 並顯示警告，因此在您修正該項目之前，憑證會保持封鎖而非遮罩。降級的 files 項目會像明確的 deny 項目一樣鎖定 filesystem.disabled，且警告會註明，若受管設定關閉檔案系統隔離，其讀取封鎖將不會強制執行。
• 具有未知 mode 或無效 path 或 name 的項目會被移除。
• 每種情況都會發出警告；無論項目是被降級或移除，其餘有效項目仍會強制執行。

​

sandbox.credentials.files

• 範圍：Any file。Claude Code 會捨棄來自專案 .claude/settings.json 和本機 .claude/settings.local.json 的 mask 項目。
• 類型：物件陣列，每個物件包含 path 和值為 "deny" 或 "mask" 的 mode，以及選用的檔案遮罩欄位
• 預設值：未設定，因此不保護任何憑證檔案

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

​

檔案遮罩欄位

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

​

sandbox.credentials.envVars

• 範圍：Any file。Claude Code 會捨棄來自專案 .claude/settings.json 和本機 .claude/settings.local.json 的 mask 項目。
• 類型：物件陣列，每個物件包含 name 和值為 "deny" 或 "mask" 的 mode，以及選用的環境變數遮罩欄位
• 預設值：未設定，因此不保護任何環境變數

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

​

環境變數遮罩欄位

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