Claude Code 设置

​

配置作用域

​

可用作用域

​

何时使用每个作用域

• 必须在整个组织范围内强制执行的安全策略
• 无法被覆盖的合规要求
• 由 IT/DevOps 部署的标准化配置

• 您想在任何地方使用的个人偏好设置（主题、编辑器设置）
• 您在所有项目中使用的工具和插件
• API 密钥和身份验证（安全存储）

• 团队共享的设置（权限、hooks、MCP servers）
• 整个团队应该拥有的插件
• 跨协作者标准化工具

• 特定项目的个人覆盖
• 在与团队共享之前测试配置
• 对其他人不适用的特定于机器的设置

​

作用域如何相互作用

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 规则生效时无需 workspace trust 步骤，而 .claude/settings.json allow 规则需要此步骤。如果存储库提供该文件，例如通过提交它，workspace trust 仍然适用。
• Managed 设置：对于需要集中控制的组织，Claude Code 支持多种 managed 设置的交付机制。所有机制都使用相同的 JSON 格式，无法被用户或项目设置覆盖：
  • 服务器管理的设置：通过 Anthropic 的服务器从 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 注册表项，带有包含 JSON 的 Settings 值（REG_SZ 或 REG_EXPAND_SZ）（通过组策略或 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 限制插件市场添加。有关更多信息，请参阅 Managed 市场限制。
• 其他配置存储在 ~/.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 中强制启用的插件加载 Hooks。这让管理员通过组织市场分发经过审查的 hooks，同时阻止其他所有内容。信任由完整的 plugin@marketplace ID 授予，因此来自不同市场的同名插件保持被阻止
• 用户 hooks、项目 hooks 和所有其他插件 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 层内，仅使用一个源，其他源被忽略而不是合并。优先级，从最高到最低：
     • 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 选项提供策略。默认情况下，当存在任何管理员部署的 managed 源时，这被忽略：服务器管理的设置、MDM 或 OS 级别策略或 managed 设置文件。用户可写的 HKCU 注册表回退不计为管理员部署的源。管理员可以通过将 parentSettingsBehavior 设置为 "merge" 来选择加入。嵌入器的值被筛选，以便它们可以收紧 managed 策略但不能放松它。
2. 命令行参数
   • 特定会话的临时覆盖。通过 --settings <file-or-json> 传递的 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/，特定于您的项目，可与您的团队共享

​

插件配置

​

插件设置

{
  "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）：个人插件偏好
• 项目设置（.claude/settings.json）：与团队共享的项目特定插件
• 本地设置（.claude/settings.local.json）：每台机器的覆盖，Claude Code 创建时被 gitignored
• Managed 设置（managed-settings.json）：组织范围的策略覆盖，在所有作用域中阻止安装并从市场隐藏插件

{
  "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. 当他们信任文件夹时，团队成员被提示安装市场
2. 然后团队成员被提示从该市场安装插件
3. 用户可以跳过不需要的市场或插件（存储在用户设置中）
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：正则表达式模式以匹配市场主机（使用 hostPattern）
• settings：直接在 settings.json 中声明的内联市场，无需单独的托管存储库（使用 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）中可用
• 无法被用户或项目设置覆盖（最高优先级）
• 在网络/文件系统操作之前强制执行（被阻止的源永远不会执行）
• 对源规范使用精确匹配（包括 ref、path 用于 git 源），除了 hostPattern 和 pathPattern，它们使用正则表达式匹配

• undefined（默认）：无限制 - 用户可以添加任何市场
• 空数组 []：完全锁定 - 用户无法添加任何新市场
• 源列表：用户只能添加与之完全匹配的市场

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 的市场：

{ "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 策略阻止
• 限制在市场添加和插件安装、更新、刷新和自动更新时强制执行。在策略设置之前添加的市场一旦其源不再与允许列表匹配，就无法用于安装或更新插件
• Managed 设置具有最高优先级，无法被覆盖

​

strictPluginOnlyCustomization

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

​

管理插件

• 浏览市场中的可用插件
• 安装/卸载插件
• 启用/禁用插件
• 查看插件详情（提供的 skills、agents、hooks）
• 添加/删除市场

​

环境变量

​

Claude 可用的工具

​

另请参阅

• 权限：权限系统、规则语法、工具特定模式和 managed 策略
• 身份验证：设置用户对 Claude Code 的访问
• 调试您的配置：诊断为什么设置、hook 或 MCP 服务器没有生效
• 故障排除安装和登录：安装、身份验证和平台问题