SpyBara
Go Premium

settings.md 2026-10-22 22:58 UTC to 2026-10-23 22:59 UTC

This page contains 83 additions and 83 deletions.

2026
Wed 7 23:59 Fri 9 23:02 Sat 10 23:01 Tue 20 23:00 Wed 21 23:02 Thu 22 22:58 Fri 23 22:59 Tue 27 22:59 Wed 28 23:57

設定檔案和優先順序

變更 Claude Code 設定、選擇金鑰所屬的範圍、驗證變更，並了解當金鑰在多個位置設定時 Claude Code 使用哪個值。

設定是變更 Claude Code 行為方式的 JSON 金鑰：它啟動時使用的模型、它可以在不詢問的情況下執行的內容、它無法讀取的檔案、它在您的終端機中的外觀，以及您的組織強制執行的內容。

[!TIP]

若要查詢特定金鑰，請前往所有設定，其中列出每個金鑰及其設定位置、預設值和範例。

Claude Code 從 JSON 設定檔案（例如 ~/.claude/settings.json）讀取設定。它在幾個位置尋找它們，而它讀取設定的檔案決定了設定適用於誰。本頁涵蓋這些檔案：將設定放在哪個檔案中、如何變更設定並確認其已應用，以及當相同金鑰在多個檔案中設定時 Claude Code 使用哪個值。設定權限涵蓋 Claude Code 可以在不詢問的情況下執行的內容以及如何編寫 allow、ask 和 deny 規則。

[!NOTE]

本頁涵蓋在您的機器上執行的 Claude Code：終端機、VS Code 和 JetBrains 擴充功能，以及桌面應用程式，它們都讀取相同的設定檔案。Claude Code on the web 上的雲端工作階段在不同的機器上執行並僅讀取其中一些；請參閱雲端工作階段中的設定。

設定檔案及其影響範圍

Claude Code 從四個檔案讀取設定，組織也可以從 claude.ai 主控台傳遞受管設定。每個來源都有一個範圍：設定儲存在其中的人員和專案集合，無論是只有您、專案中的每個人，還是組織中的每個人。

範圍 檔案 影響對象 用途
使用者 ~/.claude/settings.json 您，在此機器上的每個專案中 個人偏好設定：佈景主題、編輯器模式、預設模型、您自己的權限規則
共享專案 .claude/settings.json 每個在包含它的資料夾中工作的人。在 git 儲存庫中，提交它以便隊友取得 團隊權限、hook、外掛和專案需要的環境變數
專案本機 .claude/settings.local.json 您，僅在此一個專案中。Claude Code 在建立檔案時將其保留在 git 之外；如果您手動建立，請自行將其新增至 .gitignore 一個專案的個人覆寫，以及在共享前進行測試
受管 managed-settings.json 和其他受管來源 您的組織部署到的每個人；設定優先順序說明哪些內容可以覆寫它 安全政策和合規要求

在「檔案」欄中，~/.claude 是您家目錄中的 .claude 資料夾，而單獨的 .claude 是您專案內的 .claude 資料夾。

比較每個設定檔案的範圍

假設您在機器上有三個專案 website/、api/ 和 acme-app/，隊友有自己的 acme-app/ 複製，而您在 acme-app/ 上啟動雲端工作階段。

下圖顯示當您從這些資料夾啟動 Claude Code 時，設定適用於哪些資料夾。按一下設定檔案以查看它到達的資料夾。

Settings file

Your machine

A teammate’s machine

A cloud session

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

[!NOTE]

在 Windows 上，~/.claude 表示 %USERPROFILE%\.claude。若要將家目錄檔案保留在其他地方，請設定 CLAUDE_CONFIG_DIR；Claude Code 會改為在那裡儲存您的設定、工作階段歷史記錄和外掛。

Claude Code 也保留第五個檔案 ~/.claude.json，它為自己寫入；您不需要編輯它。它保留您的帳戶詳細資料、MCP 伺服器設定、每個專案的狀態（例如信任決定），以及 /config 為您寫入的全域設定鍵。

與您的團隊共享設定

提交 .claude/settings.json 以便複製儲存庫的每個人都取得相同的權限、hook 和外掛。每個隊友仍然可以在自己的 .claude/settings.local.json 中為自己覆寫它，因此個人例外不需要提交。如需完整的團隊檔案，請參閱團隊的共享設定。

您提交的某些內容會等到每個隊友信任資料夾，而少數設定鍵永遠不會從儲存庫檔案生效；對不適用的設定進行疑難排解涵蓋兩者。

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

若要在一個專案中為自己變更設定而不為隊友變更，請將其儲存在專案內的 .claude/settings.local.json 中。Claude Code 在提交的 .claude/settings.json 上套用該檔案，因此如果您的團隊檔案設定 "model": "claude-sonnet-5" 而您想要 Opus，請在本機檔案中放入 "model": "claude-opus-5-5"，只有您的工作階段會變更。

Claude Code 也寫入此檔案，將其保留在您的提交之外，並在不需要信任步驟的情況下套用其允許規則：

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

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

當 Claude 要求執行 Bash 命令的權限，而您選擇「是的，不要再問」時，Claude Code 會將該核准儲存為 .claude/settings.local.json 中的 allow 規則。如果您在 git 儲存庫的子目錄中啟動 Claude Code，它會在儲存庫根目錄讀取和寫入該檔案，並在整個儲存庫中套用核准。在 worktree 中，它使用主簽出根目錄的檔案。

兩個規則限定根位置：

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

在 v2.1.211 之前，Claude Code 在啟動目錄中保留檔案。它仍然會讀取較早版本留在該處的檔案，與根檔案一併讀取；當兩者設定相同的設定鍵時，以根的值為準，而兩個檔案的權限規則都適用。Agent SDK 的 resolveSettings() 協助程式始終從啟動目錄讀取檔案。

Claude Code 從工作階段的主要工作目錄讀取共享 .claude/settings.json，因此若要使用在儲存庫根目錄提交的檔案，請從那裡啟動 Claude Code。在您使用 /cd 移動工作階段後，Claude Code 改為從新目錄讀取兩個專案檔案，按相同規則放置本機檔案。從您移動到的目錄讀取它們需要 Claude Code v2.1.246 或更新版本。若是從桌面應用程式啟動的 worktree 工作階段，請參閱worktree 與主簽出共享的內容。

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

如果您的組織管理 Claude Code，某些設定是為您決定的，您在自己的檔案中放入的任何內容都不會變更它們。若要查看哪些，請執行 /status：Setting sources 行會列出適用於您的受管來源。受管設定在此機器上 Claude Code 執行的任何地方適用；開發人員可以變更的內容涵蓋本機管理員權限和 Claude Code 以外的工具。

受管設定透過受管設定頁面上的傳遞機制到達您，最常見的是：

在 Claude Desktop 應用程式中於您的機器上執行的 Cowork 工作階段中，Claude Code 不會從 claude.ai 管理主控台擷取伺服器受管設定，且它會讀取部署到您裝置的政策，除非您組織的 Claude Desktop 設定設定了 requireCoworkFullVmSandbox。政策適用的位置和時間涵蓋 Cowork 和雲端工作階段。

如果您是管理員，為您的組織設定 Claude Code 會逐步說明選擇要強制執行的內容，而部署受管設定涵蓋傳遞以及如何確認政策生效。關於 claude.ai 管理主控台中受管設定編輯器可能顯示的警告，請參閱設定伺服器受管設定。

變更設定

您可以從 /config 功能表、編輯設定檔案或一個工作階段的命令列變更設定。

Claude Code 的系統提示未發佈。若要給 Claude 常設指示，請使用 CLAUDE.md 檔案或 --append-system-prompt 旗標。

使用 /config 功能表

在 Claude Code 內執行 /config 並開啟 Config 標籤。它列出一小組個人選項，例如主題、編輯器模式和詳細輸出，而不是每個設定金鑰。選擇一個選項來變更它；Claude Code 為您儲存它：

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

若要設定一個選項而不使用功能表，請傳遞 key=value，例如 /config verbose=true。

[!NOTE]

/config 是終端機介面的一部分。VS Code 聊天面板和桌面應用程式不開啟它；通過編輯設定檔案或通過這些應用程式自己的設定在那裡變更設定。

編輯設定檔案

在您的編輯器中開啟您想要的範圍的設定檔案，並新增或變更金鑰。設定檔案是嚴格的 JSON：// 註解或尾部逗號是語法錯誤，Claude Code 在下次啟動時將檔案報告為設定錯誤。例如，若要讓 Claude Code 執行您的 lint 和測試命令而不詢問並停止讀取 .env 檔案，請將此新增到 ~/.claude/settings.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.*)"
    ]
  }
}

permissions 下的每個項目都是命名工具及其可能執行的操作的規則；設定權限解釋語法。$schema 行指向 Claude Code 設定的已發佈 JSON 架構，它在 VS Code、Cursor 和任何其他支援 JSON 架構的編輯器中為您提供自動完成和內嵌驗證。架構可能滯後於最新的 CLI 版本，因此最近記錄的金鑰上的驗證警告並不意味著您的設定無效。

儲存後，在 Claude Code 內執行 /status 以確認檔案已載入；確認已載入的內容說明 Setting sources 行顯示的內容以及如何報告損壞的檔案。

如需完整的個人檔案、團隊檔案和組織檔案，每個都帶有每個金鑰的註解，請參閱範例設定檔案。

為一個工作階段變更設定

若要嘗試值而不儲存它，請在啟動 Claude Code 時設定它。該值適用於該工作階段，您的設定檔案保持原樣。您有三種方式執行此操作：

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

設定參考上的每個金鑰項目列出其每個工作階段覆蓋及其優先順序，因此檢查您想變更的金鑰的項目。

您在工作階段內執行的命令大多儲存您的選擇：當您在 /config 中變更設定時，Claude Code 將其寫入您的設定檔案，而 /model 將值儲存為新工作階段的預設值。

如果您在 /model 選擇器中按 s，Claude Code 會切換模型而不將其儲存為您的使用者預設值。調整努力等級說明哪些 /effort 選擇 Claude Code 儲存為您使用的模型的預設值，哪些僅適用於目前工作階段。

例如，若要在 Opus 上啟動一個工作階段而不變更您的預設值：

claude --settings '{"model": "claude-opus-5-5"}'

編輯何時生效

Claude Code 監視您的設定檔案並在它們變更時重新載入它們，因此它應用大多數編輯到執行中的工作階段而不需要重新啟動，包括對 permissions、hooks 和認證協助程式（例如 apiKeyHelper）的編輯。Claude Code 也在其資料夾在工作階段啟動時存在時載入您在中途建立的設定檔案。對於專案的 .claude/ 資料夾，即使您在同一工作階段中建立資料夾，它也會載入檔案。

重新載入涵蓋使用者、專案、本機和受管設定，Claude Code 為它偵測到的每個設定檔案變更執行 ConfigChange hook，而不是來自 MDM 或 claude.ai 主控台的受管設定。來自 MDM 或 claude.ai 主控台的受管設定按排程而不是保存時到達執行中的工作階段；傳遞表按來源給出它。

Claude Code 只在工作階段啟動時讀取某些金鑰一次，因此對其中一個的編輯不會到達執行中的工作階段。也等待重新啟動的管理員端金鑰（例如 requiredMinimumVersion）列在政策適用的位置和時間下。您最可能在中途編輯的是：

確認已載入的內容

在 Claude Code 內執行 /status 以查看哪些設定來源是使用中的。Status 標籤包含 Setting sources 行，列出 Claude Code 為目前工作階段載入的每個設定檔案，例如 User settings 或 Project local settings。當受管設定生效時，受管設定項目在括號中顯示它們如何到達您的機器。

該行確認 Claude Code 讀取了哪些檔案；它不顯示哪個檔案提供了每個金鑰。若要列出 Claude Code 拒絕的項目，請執行 claude doctor；對於專案或受管設定設定的模型，啟動標頭命名設定它的檔案。/status 和 /config 在不同標籤上開啟相同的對話框，Config 標籤不是您 settings.json 內容的檢視。

修復損壞的設定檔案

如果您輸入錯誤的 JSON 或將金鑰設定為 Claude Code 不接受的值，Claude Code 在互動式工作階段啟動時會告訴您。它顯示的內容取決於檔案受影響的程度：

  • 設定錯誤：使用者、專案或本機檔案有無效的 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 在寫入檔案前儲存。

繼續後，執行 /status 以查看受影響的檔案，執行 claude doctor 以查看每個錯誤的詳細資訊。

-p 執行不顯示對話框。除非受管設定文件無法解析，Claude Code 跳過損壞的檔案或值並繼續其餘部分，因此在忽略設定的 -p 執行後，執行 claude doctor 以查看它丟棄的內容。

設定優先順序

當相同的鍵出現在多個位置時，Claude Code 會使用最高層級設定的值。下面的堆疊顯示各個層級，最高的在頂部；較高層級的鍵會覆寫下面任何地方的相同鍵。

Settings precedence, highest first: managed settings, command line, project local, shared project, user. A key set at a higher level overrides the same key set lower down.

按順序，優先順序最高的優先：

  1. 受管設定：您的組織部署的設定，透過 managed-settings.json 檔案、MDM 原則或來自 claude.ai 主控台的伺服器管理設定。您自己的設定檔案或 --settings 中的任何內容都不會覆寫受管鍵，而 --model 之類的旗標只會從您的組織允許的模型中選擇。受管 model 是起始預設值，而不是鎖定；鎖定是 availableModels 和 deniedModels。當您的組織提供多個受管來源時，受管層級內的優先順序規則說明 Claude Code 從每個來源讀取的內容。
  2. 命令列：您啟動 claude 時使用 --settings <file-or-json> 傳遞的 JSON，僅適用於該工作階段；請參閱變更一個工作階段的設定。您在此設定的鍵會覆寫您專案和使用者設定檔案中的相同鍵，而您省略的鍵會保留這些檔案中的值。其他旗標（例如 --model）會為工作階段設定單一項目，不屬於此堆疊；設定參考上的鍵項目說明哪些旗標會覆寫它。
  3. 專案本機設定 (.claude/settings.local.json)：您對此專案的個人設定。
  4. 共用專案設定 (.claude/settings.json)：您的團隊簽入原始碼控制的設定。
  5. 使用者設定 (~/.claude/settings.json)：您對每個專案的個人設定。

環境變數不是此堆疊中的層級。當行為同時具有 shell 變數和設定鍵時，哪一個適用是按對決定的，而不是按層級：在您的 shell 中匯出的 ANTHROPIC_MODEL 適用於任何檔案中的 model 鍵，而 ANTHROPIC_DEFAULT_MODEL 僅在沒有檔案設定 model 時適用。環境變數參考說明哪些鍵有對應以及 Claude Code 首先讀取哪一個。設定檔案內的 env 區塊是普通鍵，遵循上述層級。

對於少數安全敏感的鍵，Claude Code 會尊重來自較低層級的更嚴格值而不是受管值；受管設定優先順序的例外列出了它們。

列表合併而不是覆寫

當您在多個檔案中設定相同的列表鍵（例如 permissions.allow）時，Claude Code 會合併列表而不是選擇一個，因此每個檔案都可以新增項目而不移除另一個檔案的項目。四個保存模型列表或每個模型項目的鍵遵循自己的規則：

  • 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 項目說明哪個檔案的值適用於模型。

優先順序範例

當 Claude 工作時，Claude Code 在微調器下方顯示一行提示，例如「使用 /config 變更您的預設權限模式（包括 Plan Mode）」。假設您想關閉這些提示，因此您在 ~/.claude/settings.json 中將 spinnerTipsEnabled 設定為 false。下面的每個情景都是可能將它們重新開啟的事情，以及您可以做什麼。

團隊設定覆寫個人設定

您的團隊的 .claude/settings.json 將其設定為 true。Claude Code 使用專案值，因為共用專案位於使用者之上，因此您在該專案中看到提示，在其他地方看不到。

您可以取回您的值：在該專案的 .claude/settings.local.json 中新增 "spinnerTipsEnabled": false。專案本機位於共用專案之上，因此您在那裡的工作階段停止顯示提示，您的隊友的工作階段不會改變。

組織設定覆寫一切

您的組織的受管設定將其設定為 true。您在使用者、專案或本機設定中放置的任何內容都不會關閉提示，--settings 也不會。受管是最高層級。

您無法取回您的值。執行 /status 以查看哪個受管來源適用，並詢問您的管理員是否應該變更原則。

命令列覆寫您的檔案一個工作階段

您使用 claude --settings '{"spinnerTipsEnabled": true}' 啟動了工作階段。命令列位於除受管外的每個檔案之上，因此該工作階段顯示提示，即使您的檔案說 false。

您在下一個工作階段取回您的值；--settings 持續一個工作階段，不會寫入任何檔案。

旗標或環境變數設定相同的內容

某些鍵具有命令列旗標或環境變數，無論哪個檔案設定它，都會覆寫設定值：ANTHROPIC_MODEL 覆寫 model 設定，--model 在一個工作階段內覆寫兩者。

您是否可以取回您的值取決於鍵：取消設定變數或刪除旗標，並檢查設定參考上的鍵項目和環境變數參考上的變數列，以了解 Claude Code 使用哪一個。

疑難排解不適用的設定

當您設定鍵而 Claude Code 沒有表現得像您一樣時，從 /status 開始查看它載入了哪些檔案，然後在下面找到您的症狀。偵錯您的設定涵蓋更廣泛的檢查，包括乾淨設定測試。

您設定的值被忽略

其他東西設定了相同的鍵，檔案無法設定該值，或檔案未載入：

  • 較高層級設定它。 另一個設定檔案、--settings 旗標或受管來源在您的上方設定鍵；堆疊說明哪一個。旗標或環境變數也可以自行覆寫鍵，按鍵決定；設定參考上的鍵項目說明 Claude Code 使用哪一個，env 項目涵蓋受管 env 值與 shell 匯出。

  • 安全鍵保持其嚴格值。 對於少數鍵，Claude Code 尊重來自任何檔案的限制值，因此專案 true 的 disableClaudeAiConnectors 保持開啟；請參閱受管設定優先順序的例外。

  • 檔案無法設定該值。 permissions.defaultMode 值 auto 和 bypassPermissions 不會從專案或本機設定生效；改為在使用者或受管設定中設定它們，或為一個工作階段傳遞 --permission-mode。在 v2.1.257 之前，bypassPermissions 從任何檔案生效。

    env 區塊中的遙測匯出變數也不會從專案或本機設定生效，除了少數關閉值。Claude Code 在 env 中忽略的變數列出變數和這些值。

  • 檔案已損壞。 無效的 JSON 或被拒絕的值會導致 Claude Code 跳過檔案或項目；請參閱修復損壞的設定檔案。

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

當您從 Claude Code 內部為新工作階段儲存選擇時，例如使用 /model 的預設模型，Claude Code 會將其寫入您的使用者設定檔案 ~/.claude/settings.json。如果您無法寫入該檔案，例如因為另一個工具生成它或將其連結到唯讀副本，變更適用於目前工作階段，在下一個工作階段中消失。在生成檔案的工具中設定鍵，或將檔案替換為您可以寫入的檔案。

如果您可以寫入檔案，變更仍然不持續，請檢查變更是否僅適用於一個工作階段或較高層級設定相同的鍵。對於 model 鍵，新工作階段以不同的模型開始，而不是您選擇的列出更多原因。

受管變更尚未到達您

受管來源根據傳遞表中的排程到達執行中的工作階段，因此請先重新啟動工作階段。如果 /status 隨後命名與您的管理員變更的來源不同的來源，則較高優先順序的來源適用；Claude Code 如何合併受管來源給出順序。

已提交的鍵無法到達隊友

兩件事使 .claude/settings.json 中的鍵無法為克隆它的每個人應用：

  • Claude Code 忽略儲存庫檔案中的鍵。 在設定索引的「範圍」欄中查找 User, local, or managed、User or managed、User、Managed 或 Global config。這些鍵永遠不會從共用檔案應用，除了少數儲存庫檔案仍然可以關閉的鍵。每個這些項目在其「範圍」行上都說明了這一點。Global config 鍵僅從 ~/.claude.json 應用。

    在 env 鍵內，遙測匯出變數也永遠不會從共用檔案應用，除了少數關閉值；請參閱Claude Code 在 env 中忽略的變數。

  • 鍵等待信任。 permissions.allow 規則、permissions.additionalDirectories、extraKnownMarketplaces 和大多數 env 值僅在每個隊友信任資料夾後應用。在那之前，他們仍然看到提示，不會從檔案宣告的市集獲得外掛。deny 和 ask 規則立即應用。

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

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

受管設定優先順序的例外

對於少數值限制工作階段的鍵，Claude Code 尊重來自範圍的限制值，該範圍在其他情況下無法覆寫受管設定。在此表中找到鍵以查看它尊重哪個值以及來自何處。

鍵 Claude Code 尊重的值 備註
disableClaudeAiConnectors 來自任何範圍的 true 即使受管來源設定 false 也被尊重
enableArtifact 來自任何範圍的 false，以及來自任何範圍的 disableArtifact: true 即使受管來源設定 true 也被尊重；沒有任何東西會重新開啟 Artifact 工具。需要 Claude Code v2.1.242 或更新版本
isolatePeerMachines 來自任何範圍的 true 即使受管來源設定 false 也被尊重
permissions.blockReadsOutsideWorkingDirectories 來自任何範圍的 true 即使受管來源設定 false 也被尊重。需要 Claude Code v2.1.257 或更新版本
autoMode.classifyAllShell 來自 ~/.claude/settings.json 或 --settings 的 true 即使受管來源設定 false 也被尊重
remoteControlAtStartup 來自 .claude/settings.json 或 .claude/settings.local.json 的 false 即使受管來源設定 true 也被尊重；專案或本機 true 被忽略
crossSessionInbound 來自 .claude/settings.json 或 .claude/settings.local.json 的更嚴格值，在 accept < hold < refuse 梯級上 在受管、--settings 和使用者值上被尊重；不是更嚴格的專案或本機值被忽略
useAutoModeDuringPlan 來自任何受管來源、--settings、~/.claude/settings.json 或 .claude/settings.local.json 的 false 即使獲勝的受管來源設定 true 也被尊重；.claude/settings.json 中的 false 被忽略
syncClaudeAiSkills 來自任何受管來源、--settings、~/.claude/settings.json 或 .claude/settings.local.json 的 false 即使獲勝的受管來源設定 true 也被尊重；.claude/settings.json 中的 false 被忽略
syncClaudeAiPlugins 來自任何受管來源、--settings、~/.claude/settings.json 或 .claude/settings.local.json 的 false 即使獲勝的受管來源設定 true 也被尊重；.claude/settings.json 中的 false 被忽略
maxEffortLevel 來自任何範圍（包括 --settings）的較低上限 即使 Claude Code 應用的受管設定設定較高的上限也被尊重；最低上限適用。需要 Claude Code v2.1.267 或更新版本

在自身內部執行 Claude Code 並設定 CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST 的應用程式也是例外。Claude Code 採用該應用程式的模型設定而不是來自每個受管來源的 model、fallbackModel、modelPicker 和 modelOverrides 鍵，以及受管 env 區塊中的模型選擇變數，例如 ANTHROPIC_MODEL 和 ANTHROPIC_DEFAULT_*_MODEL 系列。Claude Code 保持受管 availableModels 允許清單有效，除非應用程式提供自己的。

雲端工作階段中的設定

雲端工作階段在雲端環境中執行，在您儲存庫的新複製上，而不是在您的機器上。這改變了哪些設定到達它：

  • 專案中的雲端執行緒：在專案中的雲端執行緒裡，無論專案有多少個儲存庫，儲存庫 .claude/settings.json 中的權限規則、hook 或 env 都不會套用。執行緒從您的儲存庫取得哪些內容列出了可改用的方式。
  • 共享專案設定（.claude/settings.json）：在專案執行緒之外具有一個儲存庫的工作階段中讀取，因為檔案是複製的一部分，且工作階段在其內部啟動。在那裡提交設定以在這些工作階段中套用它。
  • 具有多個儲存庫的共享專案設定：在 Anthropic 託管的環境中，具有多個儲存庫的工作階段在複製上方啟動，並從每個儲存庫的 .claude/settings.json 只讀取 enabledPlugins 和 extraKnownMarketplaces 設定鍵，而不是權限規則、hook、env 或其他設定鍵。這兩個設定鍵宣告的市集和外掛仍然不會在雲端工作階段中載入。若為自託管環境，請參閱適用哪個儲存庫的設定。
  • 使用者和專案本機設定（~/.claude/settings.json 和 .claude/settings.local.json）：未讀取。兩者都保留在您的機器上，本機檔案不在複製中。
  • 受管設定：您組織的伺服器管理設定會到達雲端工作階段；您裝置上的 managed-settings.json 檔案或 MDM 設定檔不會。表面涵蓋範圍列出哪些雲端工作階段接收它們。自託管環境也讀取其執行器映像中的受管設定檔案。Claude Code 如何合併受管來源說明該檔案何時適用。
  • /config：在您的瀏覽器中的 claude.ai/code，開啟您的 claude.ai 設定的 Claude Code 部分而不是變更值。若要為雲端工作階段變更設定，請在環境上設定環境變數。在專案執行緒之外具有一個儲存庫的工作階段中，您也可以改為將設定鍵提交到該儲存庫的 .claude/settings.json。

從您的設定進行的內容列出其餘部分：CLAUDE.md、skills、MCP 伺服器、plugins 和認證。

下一步