設定檔案和優先順序

​

設定檔案及其影響範圍

​

比較每個設定檔案的範圍

• ~/.claude/settings.json：您機器上的每個專案，以及隊友或雲端工作階段上的任何內容都不會
• acme-app/.claude/settings.json：您的 acme-app/。只有在您將檔案提交到版本控制時，它才會到達隊友的複製和雲端工作階段；在您這樣做之前，它就像任何其他檔案一樣在您的磁碟上，沒有人有它
• acme-app/.claude/settings.local.json：僅您的 acme-app/。Claude Code 在第一次寫入檔案時將其新增至您的全域 git 排除項目，因此它保留在您的提交之外；如果您手動建立檔案，自行將其新增至 .gitignore
• 受管設定，無論是 managed-settings.json 檔案、MDM 政策，還是來自 claude.ai 主控台的伺服器受管設定：您的組織部署到的每台機器上的每個專案，或您使用組織帳戶登入的地方。只有伺服器受管設定才能到達雲端工作階段

​

尋找或建立您的設定檔案

• 受管：您的組織部署它。您不建立或編輯它。
• 共享專案：已經使用 Claude Code 的專案可能已提交一個。如果沒有，請在專案資料夾中的 .claude/settings.json 建立一個。
• 使用者和專案本機：自行建立它們，或讓 Claude Code 建立它們。它在您第一次在 /config 選單中變更儲存在使用者設定中的選項時寫入 ~/.claude/settings.json，例如佈景主題，以及在您第一次在權限提示上給予常設核准時寫入 .claude/settings.local.json，例如「是的，不要再問」以取得 Bash 命令。少數 /config 選項，包括顯示提示，改為儲存至 .claude/settings.local.json 而不是使用者檔案。

​

與您的團隊共享設定

​

將個人設定保留在儲存庫之外

• Claude Code 也寫入它。 當 Claude 要求執行 Bash 命令的權限，而您選擇「是的，不要再問」時，Claude Code 會將該權限核准儲存在此處作為 allow 規則。
• 您不需要自行 gitignore 它，除非您手動建立它。 Claude Code 在不已忽略它的 git 儲存庫中第一次寫入檔案時，它會將 **/.claude/settings.local.json 新增至您的全域 git 排除項目檔案，因此檔案在每個儲存庫中保留在您的提交之外。該檔案是 core.excludesFile，當您的全域 git 設定將其設定為絕對或 ~ 前綴路徑時；否則它是 $XDG_CONFIG_HOME/git/ignore，或當 XDG_CONFIG_HOME 未設定時為 ~/.config/git/ignore。如果您手動建立檔案，而 Claude Code 尚未寫入它，請自行將其新增至 .gitignore。
• 其 allow 規則在檔案保持未追蹤時不等待信任。 因為檔案是您的而不是儲存庫的，Claude Code 應用其 allow 規則而不需要它對提交檔案要求的工作區信任步驟。如果檔案由 git 追蹤，信任步驟也適用於它；請參閱當您的本機設定檔案需要信任時。

​

Claude Code 在 git 儲存庫中保留本機檔案的位置

• 當檔案改為與 .claude/settings.json 保持在一起時：在 git 儲存庫之外，當儲存庫根目錄是您的主目錄時，在 Windows 上，或當儲存庫根目錄或其 .git 或 .claude 項目不由您的使用者擁有時。
• 檔案中的路徑不在儲存庫根目錄錨定：以 / 開頭的權限規則或相對沙箱路徑改為在工作階段的主要工作目錄錨定。

​

檢查您的組織強制執行的內容

• 伺服器受管設定，Claude Code 從 claude.ai 管理主控台或自託管Claude 應用程式閘道擷取
• MDM 或作業系統層級政策，以及系統目錄中的 managed-settings.json 檔案
• 嵌入主機（例如 Claude Desktop），通過 SDK managedSettings 選項；請參閱從嵌入主機控制政策

​

變更設定

​

使用 /config 功能表

• 大多數選項：~/.claude/settings.json
• 少數選項，例如顯示提示：.claude/settings.local.json
• 全域設定選項：~/.claude.json

​

編輯設定檔案

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

​

為一個工作階段變更設定

• --settings：將金鑰作為 JSON 傳遞，內嵌或作為檔案路徑。Claude Code 在您的使用者、專案和本機檔案上方以及受管設定下方應用它。它可以設定您的使用者設定檔案可以設定的任何金鑰；它無法設定 Managed 或 Global config 金鑰。
• 該金鑰的旗標：某些金鑰有自己的旗標，例如 model 的 --model 和 effortLevel 和 modelSettings 的 --effort。
• 環境變數：在執行 claude 之前匯出金鑰的配對變數，例如 ANTHROPIC_MODEL 用於 model。

claude --settings '{"model": "claude-opus-4-8"}'

​

編輯何時生效

• model：使用 /model 在中途切換。每個模型都有自己的提示快取，因此切換後的第一個請求會重新讀取整個對話未快取；請參閱切換模型
• effortLevel 和 modelSettings：使用 /effort 在中途變更努力

​

確認已載入的內容

​

修復損壞的設定檔案

• 設定錯誤：使用者、專案或本機檔案有無效的 JSON 或架構拒絕的值。在互動式工作階段啟動時，Claude Code 顯示一個對話框，讓您用 Claude 的幫助修復檔案、退出或繼續而不使用損壞的設定。
• 設定警告：只有個別項目失敗，例如格式錯誤的權限規則或未知的 hook 事件名稱。Claude Code 跳過這些值並保持檔案的其餘部分生效。
• 受管設定：Claude Code 繼續強制執行檔案的其餘部分。受管設定中的無效項目說明它丟棄的內容以及哪些金鑰回退到更嚴格的值，直到您修復它們。對於不是有效 JSON 的受管設定文件，請參閱受管設定文件無法解析。
• 設定錯誤：~/.claude.json 無法解析。Claude Code 將損壞的檔案複製到 ~/.claude/backups/.claude.json.corrupted.<timestamp> 並詢問是否退出並手動修復它或重設為預設設定；-p 執行列印錯誤並退出。若要恢復您之前的狀態，請複製回 ~/.claude/backups/ 中最近五個 .claude.json.backup.<timestamp> 檔案之一，Claude Code 在寫入檔案前儲存。

​

設定優先順序

1. 受管設定：您的組織部署的設定，通過 managed-settings.json 檔案、MDM 政策或來自 claude.ai 主控台的伺服器管理設定。沒有什麼您設定會覆蓋它們：您用 --settings 傳遞的金鑰不覆蓋相同的受管金鑰，而 --model 之類的旗標只從您的組織允許的模型中選擇。受管 model 設定每個工作階段啟動時的模型，您仍然可以用 /model 切換；鎖定是 availableModels，它限制 /model、--model 和您自己檔案中的 model 金鑰。當您的組織傳遞多個受管來源時，受管層級內的優先順序的規則說明 Claude Code 從每個讀取什麼。
2. 命令列引數：您在終端機啟動 claude 時傳遞的旗標，用於一個工作階段；請參閱為一個工作階段變更設定。Claude Code 使用與其他層級相同的規則合併您用 --settings <file-or-json> 傳遞的 JSON：它在此處設定的金鑰優先於本機、專案或使用者設定中的相同金鑰，並為您省略的金鑰保留較低層級的值。
3. 專案本機設定（.claude/settings.local.json）：此專案的您的個人設定。
4. 共享專案設定（.claude/settings.json）：您的團隊簽入原始碼控制的設定。
5. 使用者設定（~/.claude/settings.json）：每個專案的您的個人設定。

​

列表改為合併而不是覆蓋

• fallbackModel 是一個有序鏈，其中位置具有意義，因此 Claude Code 從定義它的最高優先順序檔案取整個值。
• modelPicker 保存一個有序行列表加上替換旗標，因此 Claude Code 永遠不會合併來自兩個來源的行。它從定義它的受管設定、--settings 和使用者設定的最高取整個值，並忽略專案和本機設定中的金鑰。需要 Claude Code v2.1.242 或更新版本。
• availableModels：當 Claude Code 應用的受管設定定義它時，Claude Code 按原樣應用該列表並忽略您在使用者、專案或本機設定中新增的項目，除非嵌入 Claude Code 的應用程式提供自己的模型列表；請參閱受管設定優先順序的例外。跨受管來源列表也永遠不會合併；Claude Code 如何合併受管來源說明哪個來源的列表適用。跨非受管範圍 Claude Code 照常合併陣列。
• modelSettings：Claude Code 一次解析它一個模型，連同 effortLevel。modelSettings 項目說明哪個檔案的值適用於模型。

​

優先順序範例

​

團隊設定覆蓋個人設定

​

組織設定覆蓋一切

​

命令列覆蓋您的檔案用於一個工作階段

​

旗標或環境變數設定相同的東西

​

疑難排解不適用的設定

​

您設定的值被忽略

• 較高層級設定它。 另一個設定檔案、--settings 旗標或受管來源在您的上方設定金鑰；堆疊說明哪一個。旗標或環境變數也可以按自己的方式覆蓋金鑰，按金鑰決定；設定參考上的金鑰項目說明 Claude Code 使用哪一個，而 env 項目涵蓋受管 env 值與 shell 匯出。
• 安全金鑰保持其嚴格值。 對於少數金鑰，Claude Code 尊重來自任何檔案的限制值，因此專案 true 用於 disableClaudeAiConnectors 保持開啟；請參閱受管設定優先順序的例外。
• 檔案無法設定該值。 permissions.defaultMode 值 auto 和 bypassPermissions 不從專案或本機設定生效；改為在使用者或受管設定中設定它們，或為一個工作階段傳遞 --permission-mode。在 v2.1.257 之前，bypassPermissions 從任何檔案生效。
• 檔案損壞。 無效的 JSON 或拒絕的值使 Claude Code 跳過檔案或項目；請參閱修復損壞的設定檔案。

​

您在 Claude Code 中所做的變更在新工作階段中丟失

​

受管變更還沒有到達您

​

提交的金鑰不到達隊友

• Claude Code 忽略儲存庫檔案中的金鑰。 在設定索引的「範圍」欄中查找 User, local, or managed、User or managed、Managed 或 Global config；這些金鑰永遠不會從共享檔案應用，除了 autoContinueAtUsageLimit，儲存庫檔案仍然可以關閉：當檔案設定金鑰而沒有使用者、--settings 或受管值時，Claude Code 讀取設定為關閉。Global config 金鑰僅從 ~/.claude.json 應用。
• 金鑰等待信任。 permissions.allow 規則、permissions.additionalDirectories、extraKnownMarketplaces 和大多數 env 值僅在每個隊友信任資料夾後應用。在那之前，他們仍然看到提示並不從檔案宣告的 marketplace 獲得 plugins。deny 和 ask 規則立即應用。

​

權限規則組合方式與您預期不同

• 您在權限提示上選擇「是，不要再問」但仍然為相同工具獲得提示。 該選擇將 allow 規則儲存到您的本機檔案，本機的 allow 規則不優先於專案或受管檔案的 ask 規則；權限規則如何組合解釋順序。在 VS Code 擴充功能中，批准卡讓您選擇目標檔案，包括專案的共享檔案，這為每個人變更規則；在 CLI 中，Claude Code 僅寫入您的本機檔案。
• 您的組織的 allow 規則仍然與您的一起應用。 這是預期的：Claude Code 跨範圍合併 permissions.allow，除非您的組織設定 allowManagedPermissionRulesOnly。

​

受管設定優先順序的例外

​

雲端工作階段中的設定

• 共享專案設定（.claude/settings.json）：讀取，因為檔案是複製的一部分。在那裡提交設定以在雲端工作階段中應用它。
• 使用者和專案本機設定（~/.claude/settings.json 和 .claude/settings.local.json）：未讀取。兩者都保留在您的機器上，本機檔案不在複製中。
• 受管設定：只有伺服器管理設定到達雲端工作階段；您裝置上的 managed-settings.json 檔案或 MDM 設定檔不會。自託管環境也讀取其執行器映像中的受管設定檔案。Claude Code 如何合併受管來源說明該檔案何時適用。
• /config：在網路上，開啟您的 claude.ai 設定的 Claude Code 部分而不是變更值。若要為雲端工作階段變更設定，請在環境上設定環境變數或將金鑰提交到儲存庫的 .claude/settings.json。

​

下一步

• 所有設定：每個金鑰，及其設定位置和範例
• 範例設定檔案：個人檔案、團隊檔案和組織的受管檔案
• 設定權限：allow、ask 和 deny 規則，以及 Claude Code 在不詢問的情況下執行的內容
• 環境變數：Claude Code 讀取的變數和 env 區塊
• 除錯您的設定：當設定不適用時
• Claude 目錄參考：Claude Code 讀取的每個檔案，包括 subagents、MCP 伺服器、plugins 和 CLAUDE.md