Claude Code 設定

​

設定範圍

​

可用的範圍

​

何時使用各個範圍

• 必須在整個組織範圍內強制執行的安全政策
• 無法覆蓋的合規要求
• 由 IT/DevOps 部署的標準化設定

• 您想在任何地方使用的個人偏好設定（主題、編輯器設定）
• 您在所有專案中使用的工具和 plugins
• API 金鑰和身份驗證（安全儲存）

• 團隊共享的設定（權限、hooks、MCP servers）
• 整個團隊應該擁有的 plugins
• 跨協作者標準化工具

• 特定專案的個人覆蓋
• 在與團隊共享之前測試設定
• 對其他人不適用的機器特定設定

​

範圍如何互動

1. Managed（最高）- 無法被任何東西覆蓋
2. 命令列引數 - 臨時工作階段覆蓋
3. Local - 覆蓋專案和使用者設定
4. Project - 覆蓋使用者設定
5. User（最低）- 當沒有其他東西指定設定時適用

​

哪些功能使用範圍

​

設定檔案

• 使用者設定在 ~/.claude/settings.json 中定義，適用於所有專案。
• 專案設定儲存在您的專案目錄中：
  • .claude/settings.json 用於簽入原始碼控制並與您的團隊共享的設定
  • .claude/settings.local.json 用於未簽入的設定，適用於個人偏好和實驗。Claude Code 建立 .claude/settings.local.json 時，會設定 git 以忽略該檔案。如果您自己建立該檔案，請手動將其新增到 gitignore。 因為此檔案是您的而不是儲存庫的，其權限 allow 規則會生效，無需 .claude/settings.json allow 規則所需的工作區信任步驟。如果儲存庫提供該檔案，例如透過提交它，工作區信任仍然適用。
• Managed 設定：對於需要集中控制的組織，Claude Code 支援多種 managed 設定的傳遞機制。所有機制都使用相同的 JSON 格式，無法被使用者或專案設定覆蓋：
  • 伺服器管理的設定：透過 Anthropic 的伺服器或自託管的 Claude apps gateway 在登入時遠端傳遞，可從 claude.ai 管理員主控台或自託管 Claude apps gateway 傳遞。請參閱伺服器管理的設定。
  • MDM/OS 層級政策：透過 macOS 和 Windows 上的原生裝置管理傳遞：
    • macOS：com.anthropic.claudecode managed preferences 網域。plist 的頂層金鑰鏡像 managed-settings.json，巢狀設定為字典，陣列為 plist 陣列。透過 Jamf、Iru (Kandji) 或類似 MDM 工具中的設定檔案部署。
    • Windows：HKLM\SOFTWARE\Policies\ClaudeCode 登錄機碼，其中包含 Settings 值（REG_SZ 或 REG_EXPAND_SZ）包含 JSON（透過群組原則或 Intune 部署）
    • Windows（使用者層級）：HKCU\SOFTWARE\Policies\ClaudeCode（最低政策優先順序，僅在沒有管理員層級來源時使用）
  • 檔案型：managed-settings.json 和 managed-mcp.json 部署到系統目錄：
    • macOS：/Library/Application Support/ClaudeCode/
    • Linux 和 WSL：/etc/claude-code/
    • Windows：C:\Program Files\ClaudeCode\
    自 v2.1.75 起，舊版 Windows 路徑 C:\ProgramData\ClaudeCode\managed-settings.json 不再受支援。已將設定部署到該位置的管理員必須將檔案遷移到 C:\Program Files\ClaudeCode\managed-settings.json。
    檔案型 managed 設定也支援在與 managed-settings.json 相同的系統目錄中的 managed-settings.d/ 放入目錄。這讓不同的團隊可以部署獨立的政策片段，而無需協調對單一檔案的編輯。 遵循 systemd 慣例，managed-settings.json 首先作為基礎合併，然後放入目錄中的所有 *.json 檔案按字母順序排序並合併在頂部。對於純量值，後面的檔案會覆蓋前面的檔案；陣列會連接並去重；物件會深度合併。以 . 開頭的隱藏檔案會被忽略。 使用數字前綴來控制合併順序，例如 10-telemetry.json 和 20-security.json。
  請參閱 managed 設定 和 Managed MCP 設定 以取得詳細資訊。 此儲存庫包含 Jamf、Iru (Kandji)、Intune 和群組原則的入門部署範本。使用這些作為起點，並根據您的需求進行調整。
  Managed 部署也可以使用 strictKnownMarketplaces 限制 plugin marketplace 新增。如需詳細資訊，請參閱 Managed marketplace 限制。
• 其他設定儲存在 ~/.claude.json 中。此檔案包含您的 OAuth 工作階段、MCP server 設定（用於使用者和本機範圍）、每個專案的狀態（允許的工具、信任設定）和各種快取。專案範圍的 MCP servers 分別儲存在 .mcp.json 中。

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  },
  "companyAnnouncements": [
    "Welcome to Acme Corp! Review our code guidelines at docs.acme.com",
    "Reminder: Code reviews required for all PRs",
    "New security policy in effect"
  ]
}

​

編輯何時生效

• model：使用 /model 在工作階段中切換
• outputStyle：系統提示的一部分，在 /clear 或重新啟動時重建

​

Managed 設定中的無效項目

• 互動式工作階段在啟動時顯示列出無效項目的對話框。
• 使用 -p 的無頭執行會將摘要列印到 stderr。
• claude doctor 列出每個無效項目及其來源和欄位。

​

可用的設定

​

全域設定設定

​

Worktree 設定

​

權限設定

​

權限規則語法

​

Sandbox 設定

​

Sandbox 路徑前綴

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker *"],
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"],
      "denyRead": ["~/.aws/credentials"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],
      "deniedDomains": ["uploads.github.com"],
      "allowUnixSockets": [
        "/var/run/docker.sock"
      ],
      "allowLocalBinding": true
    }
  }
}

• sandbox.filesystem 設定（如上所示）：在 OS 層級 sandbox 邊界控制路徑。這些限制適用於所有子流程命令（例如 kubectl、terraform、npm），而不僅僅是 Claude 的檔案工具。
• 權限規則：使用 Edit 允許/拒絕規則控制 Claude 的檔案工具存取，Read 拒絕規則阻止讀取，WebFetch 允許/拒絕規則控制網路網域。這些規則中的路徑也會合併到 sandbox 設定中。

​

歸屬設定

• 提交預設使用 git trailers（如 Co-Authored-By），可以自訂或停用
• 拉取請求說明是純文字

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

🤖 Generated with [Claude Code](https://claude.com/claude-code)

{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: AI <ai@example.com>",
    "pr": ""
  }
}

​

檔案建議設定

{
  "fileSuggestion": {
    "type": "command",
    "command": "~/.claude/file-suggestion.sh"
  }
}

{"query": "src/comp"}

src/components/Button.tsx
src/components/Modal.tsx
src/components/Form.tsx

#!/bin/bash
query=$(cat | jq -r '.query')
# 用您自己的檔案搜尋命令替換 your-repo-file-index
your-repo-file-index --query "$query" | head -20

​

頁尾連結徽章

{
  "footerLinksRegexes": [
    {
      "type": "regex",
      "pattern": "\\b(?<key>PROJ-\\d+)\\b",
      "url": "https://issues.example.com/browse/{key}",
      "label": "{key}"
    }
  ]
}

​

Hook 設定

• 載入 Managed hooks 和 SDK hooks
• 從在 managed 設定 enabledPlugins 中強制啟用的 plugins 載入 Hooks。這讓管理員透過組織 marketplace 分發經過審查的 hooks，同時阻止其他所有內容。信任由完整 plugin@marketplace ID 授予，因此來自不同 marketplace 的同名 plugin 保持被阻止
• 使用者 hooks、專案 hooks 和所有其他 plugin hooks 被阻止

{
  "allowedHttpHookUrls": ["https://hooks.example.com/*", "http://localhost:*"]
}

{
  "httpHookAllowedEnvVars": ["MY_TOKEN", "HOOK_SECRET"]
}

​

使用政策協助程式計算 managed 設定

{
  "managedSettings": {
    "permissions": { "deny": ["Read(//etc/secrets/**)"] }
  },
  "claudeMd": "# Organization context\n...",
  "appendSystemPrompt": "Always cite the internal style guide."
}

​

設定優先順序

1. Managed 設定（伺服器管理、MDM/OS 層級政策或 managed 設定）
   • 由 IT 透過伺服器傳遞、MDM 設定檔案、登錄政策或 managed 設定檔案部署的政策
   • 無法被任何其他層級覆蓋，包括命令列引數
   • 在 managed 層級內，僅使用一個 managed 來源，其他來源被忽略而不是合併。優先順序，最高優先：
     • policyHelper 輸出：當設定時，這是唯一使用的 managed 來源
     • 遠端（claude.ai 伺服器管理或 Claude apps gateway傳遞）
     • MDM/OS 層級政策
     • 檔案型（managed-settings.d/*.json 和 managed-settings.json，合併在一起）
     • HKCU 登錄（僅限 Windows）
   • 少數金鑰是例外，在任何管理員控制的 managed 來源設定它們時受尊重，而不是僅由獲勝的來源。使用者可寫的 HKCU 登錄來源被排除。例外金鑰為：
     • sandbox 鎖定金鑰 sandbox.network.allowManagedDomainsOnly 和 sandbox.filesystem.allowManagedReadPathsOnly，以及其相關聯的白名單
     • allowAllClaudeAiMcps
     • sandbox 二進位路徑 sandbox.bwrapPath 和 sandbox.socatPath
     • forceRemoteSettingsRefresh
   • 嵌入主機（例如 Claude Desktop）可以透過 SDK managedSettings 選項提供政策。預設情況下，當任何 admin 部署的 managed 來源存在時，此會被忽略：伺服器管理的設定、MDM 或 OS 層級政策，或 managed 設定檔案。使用者可寫的 HKCU 登錄回退不計為 admin 部署的來源。管理員可以透過設定 parentSettingsBehavior 為 "merge" 來選擇加入。嵌入器的值會被篩選，以便它們可以收緊 managed 政策但不能放鬆政策。
2. 命令列引數
   • 特定工作階段的臨時覆蓋。JSON 透過 --settings <file-or-json> 傳遞會與檔案型設定合併，使用與其他層級相同的規則：此處設定的金鑰會覆蓋本機、專案或使用者設定中的相同金鑰，省略金鑰會保留較低層級的值
3. 本機專案設定（.claude/settings.local.json）
   • 個人專案特定設定
4. 共享專案設定（.claude/settings.json）
   • 原始碼控制中的團隊共享專案設定
5. 使用者設定（~/.claude/settings.json）
   • 個人全域設定

​

驗證使用中的設定

​

設定系統的關鍵要點

• 記憶檔案（CLAUDE.md）：包含 Claude 在啟動時載入的指示和內容
• 設定檔案（JSON）：設定權限、環境變數和工具行為
• Skills：可以使用 /skill-name 叫用或由 Claude 自動載入的自訂提示
• MCP servers：使用其他工具和整合擴展 Claude Code
• 優先順序：較高層級的設定（Managed）覆蓋較低層級的設定（User/Project）
• 繼承：設定會合併跨範圍；較高優先順序範圍中的純量值覆蓋，陣列連接，有兩個例外如陣列合併注意中所述

​

系統提示

​

排除敏感檔案

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

​

Subagent 設定

• 使用者 subagents：~/.claude/agents/，在所有專案中可用
• 專案 subagents：.claude/agents/，特定於您的專案，可與您的團隊共享

​

Plugin 配置

​

Plugin 設定

{
  "enabledPlugins": {
    "formatter@acme-tools": true,
    "deployer@acme-tools": true,
    "analyzer@security-plugins": false
  },
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    }
  }
}

​

enabledPlugins

• 使用者設定（~/.claude/settings.json）：個人 plugin 偏好設定
• 專案設定（.claude/settings.json）：與團隊共享的專案特定 plugins
• 本機設定（.claude/settings.local.json）：每台機器的覆蓋，Claude Code 建立時會被 gitignored
• Managed 設定（managed-settings.json）：組織範圍的政策覆蓋，在所有範圍阻止安裝並從 marketplace 隱藏 plugin

{
  "enabledPlugins": {
    "code-formatter@team-tools": true,
    "deployment-tools@team-tools": true,
    "experimental-features@personal": false
  }
}

​

pluginConfigs

{
  "pluginConfigs": {
    "deployer@acme-tools": {
      "options": {
        "api_endpoint": "https://api.example.com"
      }
    }
  }
}

​

extraKnownMarketplaces

1. 當團隊成員信任資料夾時，系統會提示他們安裝 marketplace
2. 然後提示團隊成員從該 marketplace 安裝 plugins
3. 使用者可以跳過不需要的 marketplaces 或 plugins（儲存在使用者設定中）
4. 安裝尊重信任邊界並需要明確同意

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    },
    "security-plugins": {
      "source": {
        "source": "git",
        "url": "https://git.example.com/security/plugins.git"
      }
    }
  }
}

• github：GitHub 儲存庫（使用 repo）
• git：任何 git URL（使用 url）
• directory：本機檔案系統路徑（使用 path，僅用於開發）
• hostPattern：正規表達式模式以符合 marketplace 主機（使用 hostPattern）
• settings：直接在 settings.json 中宣告的內嵌 marketplace，無需單獨的託管儲存庫（使用 name 和 plugins）

{
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {
        "source": "settings",
        "name": "team-tools",
        "plugins": [
          {
            "name": "code-formatter",
            "source": {
              "source": "github",
              "repo": "acme-corp/code-formatter"
            }
          }
        ]
      }
    }
  }
}

​

strictKnownMarketplaces

• macOS：/Library/Application Support/ClaudeCode/managed-settings.json
• Linux 和 WSL：/etc/claude-code/managed-settings.json
• Windows：C:\Program Files\ClaudeCode\managed-settings.json

• 僅在 managed 設定（managed-settings.json）中可用
• 無法被使用者或專案設定覆蓋（最高優先順序）
• 在網路/檔案系統操作之前強制執行（被阻止的來源永遠不會執行）
• 對來源規格使用精確匹配（包括 git 來源的 ref、path），除了 hostPattern 和 pathPattern，它們使用正規表達式匹配

• undefined（預設）：無限制 - 使用者可以新增任何 marketplace
• 空陣列 []：完全鎖定 - 使用者無法新增任何新 marketplaces
• 來源清單：使用者只能新增完全符合的 marketplaces

1. GitHub 儲存庫：

{ "source": "github", "repo": "acme-corp/approved-plugins" }
{ "source": "github", "repo": "acme-corp/security-tools", "ref": "v2.0" }
{ "source": "github", "repo": "acme-corp/plugins", "ref": "main", "path": "marketplace" }

2. Git 儲存庫：

{ "source": "git", "url": "https://gitlab.example.com/tools/plugins.git" }
{ "source": "git", "url": "https://bitbucket.org/acme-corp/plugins.git", "ref": "production" }
{ "source": "git", "url": "ssh://git@git.example.com/plugins.git", "ref": "v3.1", "path": "approved" }

3. 基於 URL 的 marketplaces：

{ "source": "url", "url": "https://plugins.example.com/marketplace.json" }
{ "source": "url", "url": "https://cdn.example.com/marketplace.json", "headers": { "Authorization": "Bearer ${TOKEN}" } }

4. NPM 套件：

{ "source": "npm", "package": "@acme-corp/claude-plugins" }
{ "source": "npm", "package": "@acme-corp/approved-marketplace" }

5. 檔案路徑：

{ "source": "file", "path": "/usr/local/share/claude/acme-marketplace.json" }
{ "source": "file", "path": "/opt/acme-corp/plugins/marketplace.json" }

6. 目錄路徑：

{ "source": "directory", "path": "/usr/local/share/claude/acme-plugins" }
{ "source": "directory", "path": "/opt/acme-corp/approved-marketplaces" }

7. 主機模式匹配：

{ "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }
{ "source": "hostPattern", "hostPattern": "^gitlab\\.internal\\.example\\.com$" }

• github：始終符合 github.com
• git：從 URL 提取主機名稱（支援 HTTPS 和 SSH 格式）
• url：從 URL 提取主機名稱
• npm、file、directory：不支援主機模式匹配

8. 路徑模式匹配：

{ "source": "pathPattern", "pathPattern": "^/opt/approved/" }
{ "source": "pathPattern", "pathPattern": ".*" }

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/approved-plugins"
    },
    {
      "source": "github",
      "repo": "acme-corp/security-tools",
      "ref": "v2.0"
    },
    {
      "source": "url",
      "url": "https://plugins.example.com/marketplace.json"
    },
    {
      "source": "npm",
      "package": "@acme-corp/compliance-plugins"
    }
  ]
}

{
  "strictKnownMarketplaces": []
}

{
  "strictKnownMarketplaces": [
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.example\\.com$"
    }
  ]
}

• repo 或 url 必須完全符合
• ref 欄位必須完全符合（或兩者都未定義）
• path 欄位必須完全符合（或兩者都未定義）

// 這些是不同的來源：
{ "source": "github", "repo": "acme-corp/plugins" }
{ "source": "github", "repo": "acme-corp/plugins", "ref": "main" }

// 這些也不同：
{ "source": "github", "repo": "acme-corp/plugins", "path": "marketplace" }
{ "source": "github", "repo": "acme-corp/plugins" }

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme-corp/plugins" }
  ]
}

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "github", "repo": "acme-corp/plugins" }
    }
  }
}

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme-corp/plugins" }
  ],
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "github", "repo": "acme-corp/plugins" }
    }
  }
}

• 限制在任何網路請求或檔案系統操作之前檢查
• 被阻止時，使用者會看到清晰的錯誤訊息，指示來源被 managed 政策阻止
• 限制在 marketplace 新增和 plugin 安裝、更新、重新整理和自動更新時強制執行。在設定政策之前新增的 marketplace 一旦其來源不再符合白名單，就無法用於安裝或更新 plugins
• Managed 設定具有最高優先順序，無法被覆蓋

​

strictPluginOnlyCustomization

{
  "strictPluginOnlyCustomization": ["skills", "hooks"]
}

​

管理 plugins

• 瀏覽 marketplaces 中的可用 plugins
• 安裝/解除安裝 plugins
• 啟用/停用 plugins
• 檢視 plugin 詳細資訊（提供的 skills、agents、hooks）
• 新增/移除 marketplaces

​

環境變數

​

Claude 可用的工具

​

另請參閱

• Permissions：權限系統、規則語法、工具特定模式和 managed 政策
• Authentication：設定使用者對 Claude Code 的存取
• Debug your configuration：診斷為什麼設定、hook 或 MCP server 未生效
• Troubleshoot installation and login：安裝、authentication 和平台問題