Claude Code 设置

使用全局和项目级设置以及环境变量配置 Claude Code。

Claude Code 提供多种设置来配置其行为以满足您的需求。您可以通过运行 /config 命令来配置 Claude Code，这会打开一个选项卡式设置界面，您可以在其中查看状态信息并修改配置选项。从 v2.1.181 开始，您可以通过向 /config 传递 key=value 来更改单个选项而无需打开界面，例如 /config verbose=true。

配置作用域

Claude Code 使用作用域系统来确定配置应用的位置以及与谁共享。了解作用域可以帮助您决定如何为个人使用、团队协作或企业部署配置 Claude Code。

可用作用域

何时使用每个作用域

Managed 作用域用于：

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

User 作用域最适合：

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

Project 作用域最适合：

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

Local 作用域最适合：

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

作用域如何相互作用

当在多个作用域中出现相同的设置时，Claude Code 按优先级顺序应用它们：

1. Managed（最高）- 无法被任何内容覆盖
2. 命令行参数 - 临时会话覆盖
3. Local - 覆盖项目和用户设置
4. Project - 覆盖用户设置
5. User（最低）- 当没有其他内容指定设置时应用

例如，如果您的用户设置将 spinnerTipsEnabled 设置为 true，而项目设置将其设置为 false，则项目值适用。权限规则的行为不同，因为它们跨作用域合并而不是覆盖。请参阅 Settings precedence。

哪些功能使用作用域

作用域适用于许多 Claude Code 功能：

在 Windows 上，显示为 ~/.claude 的路径解析为 %USERPROFILE%\.claude。

设置文件

settings.json 文件是通过分层设置配置 Claude Code 的官方机制：

• 用户设置在 ~/.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 仍然适用。

• 托管设置：对于需要集中控制的组织，Claude Code 支持多种 托管设置的交付机制。所有机制都使用相同的 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-settings.json 相同的系统目录中的 managed-settings.d/ 放入目录。这让独立的团队可以部署独立的策略片段，而无需协调对单个文件的编辑。

    遵循 systemd 约定，managed-settings.json 首先作为基础合并，然后放入目录中的所有 *.json 文件按字母顺序排序并合并在顶部。对于标量值，后面的文件覆盖前面的文件；数组被连接和去重；对象被深度合并。以 . 开头的隐藏文件被忽略。

    使用数字前缀来控制合并顺序，例如 10-telemetry.json 和 20-security.json。

  请参阅 托管设置 和 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"
  ]
}

上面示例中的 $schema 行指向 Claude Code 设置的官方 JSON 架构。将其添加到您的 settings.json 可在 VS Code、Cursor 和任何其他支持 JSON 架构验证的编辑器中启用自动完成和内联验证。

已发布的架构会定期更新，可能不包括最近 CLI 版本中添加的设置，因此最近记录的字段上的验证警告不一定意味着您的配置无效。

编辑何时生效

Claude Code 监视您的设置文件，并在它们更改时重新加载它们，因此对大多数键的编辑会在运行的会话中应用，无需重启。这包括 permissions、hooks 和凭证助手（如 apiKeyHelper）。重新加载涵盖用户、项目、本地和托管设置，并为每个检测到的更改触发 ConfigChange hook。

少数几个键在会话启动时读取一次，并在下次重启时应用：

• model：使用 /model 在会话中切换
• outputStyle：系统提示的一部分，在 /clear 或重启时重建

托管设置中的无效条目

托管设置宽容地解析。当 托管配置包含验证架构失败的条目时，Claude Code 会删除该条目，记录警告，并强制执行所有剩余的有效策略。单个拼写错误无法禁用组织的其余策略。运行 /doctor 以列出被删除的条目及其源文件和字段。此行为在所有三种交付机制中一致：服务器托管设置、通过 MDM 部署的 plist 和注册表策略，以及 managed-settings.json 文件。需要 Claude Code v2.1.169 或更高版本。

安全强制字段按字段处理，而不是在存在但无效时被整体删除：

requiredMinimumVersion 和 requiredMaximumVersion 通过设计失败开放：无效值被删除而不是强制执行，因此坏策略推送无法阻止 Claude Code 启动。

验证错误出现在三个地方：

• 交互式会话在启动时显示列出无效条目的对话框。
• 使用 -p 的无头运行将摘要打印到 stderr。
• claude doctor 列出每个无效条目及其源和字段。

在将策略更改部署到整个机队之前，在测试机器上运行 claude doctor 来验证策略更改。

此容限仅适用于 托管设置。用户、项目和本地设置文件保持严格：验证失败的文件被整体拒绝并报告。

可用设置

settings.json 支持多个选项：

全局配置设置

这些设置存储在 ~/.claude.json 中，而不是 settings.json。将它们添加到 settings.json 将触发架构验证错误。

Worktree 设置

配置 --worktree 如何创建和管理 git worktrees。

要将 gitignored 文件（如 .env）复制到新的 worktrees，请在项目根目录中使用 .worktreeinclude 文件，而不是设置。

权限设置

权限规则语法

权限规则遵循 Tool 或 Tool(specifier) 的格式。规则按顺序评估：首先是拒绝规则，然后是询问，最后是允许。第一个匹配的规则确定结果，无论规则特异性如何。请参阅权限规则评估顺序了解详情。

快速示例：

有关完整的规则语法参考，包括通配符行为、Read、Edit、WebFetch、MCP 和 Agent 规则的工具特定模式，以及 Bash 模式的安全限制，请参阅权限规则语法。

Sandbox 设置

配置高级 sandboxing 行为。Sandboxing 将 bash 命令与您的文件系统和网络隔离。请参阅 Sandboxing 了解详情。

Sandbox 路径前缀

filesystem.allowWrite、filesystem.denyWrite、filesystem.denyRead、filesystem.allowRead 和 credentials.files 中的路径支持这些前缀：

较旧的 //path 前缀用于绝对路径仍然有效。如果您之前使用单斜杠 /path 期望项目相对解析，请切换到 ./path。此语法与读取和编辑权限规则不同，后者使用 //path 用于绝对和 /path 用于项目相对。Sandbox 文件系统路径使用标准约定：/tmp/build 是绝对路径。

配置示例：

{
  "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 配置中。

归属设置

Claude Code 为 git 提交和拉取请求添加归属。这些分别配置：

• 提交默认使用 git trailers（如 Co-Authored-By），可以自定义或禁用
• 拉取请求描述是纯文本

默认提交归属：

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

会话的活跃模型在 trailer 中反映。

默认拉取请求归属：

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

示例：

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

文件建议设置

为 @ 文件路径自动完成配置自定义命令。内置文件建议使用快速文件系统遍历，但大型 monorepos 可能受益于项目特定的索引，例如预构建的文件索引或自定义工具。

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

该命令使用与 hooks 相同的环境变量运行，包括 CLAUDE_PROJECT_DIR。它通过 stdin 接收包含 query 字段的 JSON：

{"query": "src/comp"}

将换行符分隔的文件路径输出到 stdout（当前限制为 15）：

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 设置在输入框下方的页脚中渲染额外的可点击徽章。使用它将项目 CLI 打印的 ID（如审查工具和问题跟踪器）转换为会话链接。

每个条目的 pattern 正则表达式与轮次输出匹配：工具结果，包括文件内容和获取的页面，以及 Claude 自己的响应。url 和 label 中的 {name} 占位符从模式中的命名捕获组填充。

以下示例在问题键（如 PROJ-1234）出现在轮次输出中时渲染徽章。(?<key>...) 命名组捕获键，{key} 将其替换到 URL 和标签中：

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

配置此后，当 PROJ-1234 出现在工具结果或 Claude 的回复中时，一个 PROJ-1234 徽章出现在页脚中，链接到 https://issues.example.com/browse/PROJ-1234。

以下约束适用于每个条目：

当轮次完成时，Claude Code 在主线程上将每个条目的 pattern 正则表达式与轮次输出匹配，因此缓慢的正则表达式会阻止 UI，直到完成。嵌套量词（如 (a+)+$）可能对某些输入花费指数级长时间并冻结会话，因此保持每个 pattern 线性并避免嵌套 + 或 *。

页脚徽章与自定义状态行一起渲染，当配置了一个时；两者都不替换另一个。使用状态行用于从会话数据计算自己内容的脚本驱动行，使用页脚徽章将对话中的 ID 转换为链接，无需脚本。

Hook 配置

这些设置控制允许运行哪些 hooks 以及 HTTP hooks 可以访问什么。allowManagedHooksOnly 设置只能在 托管设置中配置。URL 和环境变量允许列表可以在任何设置级别设置并跨源合并。

当 allowManagedHooksOnly 为 true 时的行为：

• 加载 Managed hooks 和 SDK hooks
• 从在托管设置 enabledPlugins 中强制启用的插件加载 Hooks。这让管理员通过组织市场分发经过审查的 hooks，同时阻止其他所有内容。信任由完整的 plugin@marketplace ID 授予，因此来自不同市场的同名插件保持被阻止
• 用户 hooks、项目 hooks 和所有其他插件 hooks 被阻止

限制 HTTP hook URL：

限制 HTTP hooks 可以针对的 URL。支持 * 作为匹配的通配符。定义数组后，针对不匹配 URL 的 HTTP hooks 被静默阻止。主机名匹配不区分大小写，忽略尾部 FQDN 点，匹配 DNS 语义。

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

限制 HTTP hook 环境变量：

限制 HTTP hooks 可以插入到标头值中的环境变量名称。每个 hook 的有效 allowedEnvVars 是其自己列表与此设置的交集。

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

使用策略助手计算 托管设置

policyHelper 设置指向一个可执行文件，在启动时动态计算 托管设置，因此管理员可以从设备状态、身份或远程服务而不是静态文件派生策略。从 MDM 或系统 managed-settings.json 文件配置它。Claude Code 在 policyHelper 出现在任何其他作用域时忽略它，包括用户设置、项目设置、HKCU 注册表配置单元和服务器托管设置。

该设置接受这些键：

助手将 JSON 信封写入 stdout。将设置放在 managedSettings 键下而不是顶级，因为裸设置对象解析时 managedSettings 未定义并应用任何内容：

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

当助手发出 managedSettings 时，该对象替换该运行的基于文件的托管设置。当助手在启动时以非零状态退出时，Claude Code 打印错误并拒绝启动，因此需要中断恢复的助手应从其自己的缓存提供并以 0 退出。

设置优先级

设置按优先级顺序应用。从最高到最低：

1. 托管设置（服务器管理、MDM/OS 级别策略 或 托管设置）

   • 由 IT 通过服务器交付、MDM 配置文件、注册表策略或托管设置文件部署的策略
   • 无法被任何其他级别覆盖，包括命令行参数
   • 在 managed 层内，仅使用一个源，其他源被忽略而不是合并。优先级，从最高到最低：
     • policyHelper 输出：当配置时，这是唯一使用的托管源
     • 远程（claude.ai 服务器管理 或 Claude apps gateway 交付）
     • MDM/OS 级别策略
     • 基于文件（managed-settings.d/*.json 和 managed-settings.json，合并在一起）
     • HKCU 注册表（仅 Windows）
   • 少数几个键是例外，当任何管理员控制的托管源设置它们时被尊重，而不仅仅是获胜的源。用户可写的 HKCU 注册表源被排除。例外键是：
     • sandbox 锁定键 sandbox.network.allowManagedDomainsOnly 和 sandbox.filesystem.allowManagedReadPathsOnly，带有其关联的允许列表
     • allowAllClaudeAiMcps
     • sandbox 二进制路径 sandbox.bwrapPath 和 sandbox.socatPath
     • forceRemoteSettingsRefresh
   • 嵌入主机（如 Claude Desktop）可以通过 SDK managedSettings 选项提供策略。默认情况下，当存在任何管理员部署的托管源时，这被忽略：服务器托管设置、MDM 或 OS 级别策略或托管设置文件。用户可写的 HKCU 注册表回退不计为管理员部署的源。管理员可以通过将 parentSettingsBehavior 设置为 "merge" 来选择加入。嵌入器的值被筛选，以便它们可以收紧 托管策略但不能放松它。

2. 命令行参数

   • 特定会话的临时覆盖。通过 --settings <file-or-json> 传递的 JSON 使用与其他层相同的规则与基于文件的设置合并：此处设置的键覆盖本地、项目或用户设置中的相同键，省略键会保留较低层的值

3. 本地项目设置（.claude/settings.local.json）

   • 个人项目特定设置

4. 共享项目设置（.claude/settings.json）

   • 源代码管理中的团队共享项目设置

5. 用户设置（~/.claude/settings.json）

   • 个人全局设置

此层次结构确保组织策略始终被强制执行，同时仍允许团队和个人自定义其体验。无论您从 CLI、VS Code 扩展 还是 JetBrains IDE 运行 Claude Code，相同的优先级都适用。

例如，如果您的用户设置将 permissions.defaultMode 设置为 acceptEdits，而项目的共享设置将其设置为 default，则项目值适用。下面的示例涵盖了数组值设置（如权限规则）如何组合的方式。

验证活跃设置

在 Claude Code 中运行 /status 以查看哪些设置源处于活跃状态。在菜单中，状态选项卡包含一个 Setting sources 行，列出 Claude Code 为当前会话加载的每个层，例如 User settings 或 Project local settings。当托管设置生效时，该条目在括号中显示交付渠道，例如 Enterprise managed settings (remote)、(plist)、(HKLM)、(HKCU) 或 (file)。仅当该源被加载且至少有一个键时，层才出现在列表中，因此空列表意味着未找到设置源。

Setting sources 行确认正在读取哪些源。它不显示哪一层提供了每个单独的键。同一对话框中的配置选项卡是一个编辑器，用于一组固定的切换，例如主题和详细输出，而不是您的 settings.json 内容的视图。

如果设置文件包含错误，例如无效的 JSON 或验证失败的值，/status 列出受影响的文件。运行 /doctor 以查看每个错误的详情。

配置系统的关键点

• 内存文件（CLAUDE.md）：包含 Claude 在启动时加载的说明和上下文
• 设置文件（JSON）：配置权限、环境变量和工具行为
• Skills：可以使用 /skill-name 调用或由 Claude 自动加载的自定义提示
• MCP servers：使用额外的工具和集成扩展 Claude Code
• 优先级：更高级别的配置（Managed）覆盖较低级别的配置（User/Project）
• 继承：设置被合并跨作用域；来自较高优先级作用域的标量值覆盖，数组连接，有两个例外，如数组合并注释中所述

系统提示

Claude Code 的内部系统提示未发布。要添加自定义说明，请使用 CLAUDE.md 文件或 --append-system-prompt 标志。

排除敏感文件

要防止 Claude Code 访问包含敏感信息（如 API 密钥、secrets 和环境文件）的文件，请在您的 .claude/settings.json 文件中使用 permissions.deny 设置：

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

这替代了已弃用的 ignorePatterns 配置。匹配这些模式的文件被排除在文件发现和搜索结果之外，这些文件上的读取操作被拒绝。

Subagent 配置

Claude Code 支持可在用户和项目级别配置的自定义 AI subagents。这些 subagents 存储为带有 YAML frontmatter 的 Markdown 文件：

• 用户 subagents：~/.claude/agents/，在所有项目中可用
• 项目 subagents：.claude/agents/，特定于您的项目，可与您的团队共享

Subagent 文件定义具有自定义提示和工具权限的专门 AI 助手。在 subagents 文档中了解有关创建和使用 subagents 的更多信息。

插件配置

Claude Code 支持一个插件系统，让您可以使用 skills、agents、hooks 和 MCP servers 扩展功能。插件通过市场分发，可以在用户和存储库级别配置。

插件设置

settings.json 中的插件相关设置：

{
  "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

控制启用哪些插件。格式："plugin-name@marketplace-name": true/false。没有在任何作用域中有条目的插件会回退到其 defaultEnabled 值。

作用域：

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

示例：

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

pluginConfigs

存储插件的 userConfig 提示收集的非敏感选项值，按插件 ID 键入。当您填写插件的配置对话框时，Claude Code 会将此键写入用户设置，因此您无需手动编辑它。敏感选项存储在 macOS Keychain 中，或在没有支持的 keychain 的平台上存储在 ~/.claude/.credentials.json 中。

此示例为从 acme-tools 市场安装的插件存储一个选项：

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

pluginConfigs 仅从用户设置、--settings 标志和托管设置中读取。项目的 .claude/settings.json 或 .claude/settings.local.json 中的条目被忽略，因为这些值被替换到插件 hook、MCP 和 LSP 配置中，克隆的存储库不能提供它们。在 v2.1.207 之前，项目和本地设置也被读取。

extraKnownMarketplaces

定义应为存储库提供的额外市场。通常在存储库级别设置中使用，以确保团队成员有权访问所需的插件源。

当存储库包含 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）

git 源类型适用于任何 git 托管服务，包括自托管的 GitLab 和 Bitbucket。Claude Code 使用与该机器上 git clone 相同的身份验证克隆存储库：配置的凭证助手或 SSH 密钥。提供者 Token（如 GITHUB_TOKEN）仅通过读取它的凭证助手生效。有关设置详情，请参阅私有存储库。

对于 github 和 git 源，在 source 对象内设置 "skipLfs": true（与 repo 或 url 一起）以在 Claude Code 克隆或更新市场存储库时跳过 Git LFS 下载。LFS 指针文件保持为指针而不是下载其内容。当存储库包含与插件内容无关的大型 LFS 对象时，使用此选项。需要 Claude Code v2.1.153 或更高版本。

每个市场条目还接受可选的 autoUpdate 布尔值。在 source 旁边设置 "autoUpdate": true 以使 Claude Code 在启动时刷新该市场并更新其已安装的插件。省略时，官方 Anthropic 市场默认为 true，所有其他市场默认为 false。请参阅配置自动更新。

使用 source: 'settings' 声明一小组插件内联，无需设置托管市场存储库。此处列出的插件必须引用外部源，例如 GitHub 或 npm。您仍需要在 enabledPlugins 中单独启用每个插件。

{
  "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-settings.json）中可用
• 无法被用户或项目设置覆盖（最高优先级）
• 在网络/文件系统操作之前强制执行（被阻止的源永远不会执行）
• 对源规范使用精确匹配（包括 ref、path 用于 git 源），除了 hostPattern 和 pathPattern，它们使用正则表达式匹配

允许列表行为：

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

所有支持的源类型：

允许列表支持多种市场源类型。大多数源使用精确匹配，而 hostPattern 和 pathPattern 分别使用正则表达式匹配市场主机和文件系统路径。

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" }

字段：repo（必需）、ref（可选：分支或标签）、path（可选：子目录）

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" }

字段：url（必需）、ref（可选：分支或标签）、path（可选：子目录）

3. 基于 URL 的市场：

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

字段：url（必需）、headers（可选：用于身份验证访问的 HTTP 标头）

4. NPM 包：

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

字段：package（必需，支持作用域包）

5. 文件路径：

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

字段：path（必需：marketplace.json 文件的绝对路径）

6. 目录路径：

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

字段：path（必需：包含 .claude-plugin/marketplace.json 的目录的绝对路径）

7. 主机模式匹配：

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

字段：hostPattern（必需：与市场主机匹配的正则表达式模式）

当您想允许来自特定主机的所有市场而不枚举每个存储库时，使用主机模式匹配。这对于具有内部 GitHub Enterprise 或 GitLab 服务器的组织很有用，开发人员在其中创建自己的市场。

按源类型的主机提取：

• github：始终与 github.com 匹配
• git：从 URL 提取主机名（支持 HTTPS 和 SSH 格式）
• url：从 URL 提取主机名
• npm、file、directory：不支持主机模式匹配

8. 路径模式匹配：

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

字段：pathPattern（必需：与 file 和 directory 源的 path 字段匹配的正则表达式模式）

使用路径模式匹配来允许基于文件系统的市场与网络源的 hostPattern 限制一起使用。设置 ".*" 以允许所有本地路径，或使用更窄的模式来限制特定目录。

配置示例：

示例：仅允许特定市场：

{
  "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": []
}

示例：允许来自内部 git 服务器的所有市场：

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

精确匹配要求：

市场源必须精确匹配才能允许用户的添加。对于基于 git 的源（github 和 git），这包括所有可选字段：

• 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" }

与 extraKnownMarketplaces 的比较：

格式差异：

strictKnownMarketplaces 使用直接源对象：

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

extraKnownMarketplaces 需要命名市场：

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

同时使用两者：

strictKnownMarketplaces 是一个策略门：它控制用户可能添加什么，但不注册任何市场。要同时限制和为所有用户预注册市场，请在 managed-settings.json 中设置两者：

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

仅设置 strictKnownMarketplaces 时，用户仍可以通过 /plugin marketplace add 手动添加允许的市场，但它不会自动可用。

重要说明：

• 限制在任何网络请求或文件系统操作之前检查
• 被阻止时，用户看到清晰的错误消息，指示源被 托管策略阻止
• 限制在市场添加和插件安装、更新、刷新和自动更新时强制执行。在策略设置之前添加的市场一旦其源不再与允许列表匹配，就无法用于安装或更新插件
• 托管设置具有最高优先级，无法被覆盖

请参阅 Managed 市场限制了解面向用户的文档。

strictPluginOnlyCustomization

仅限托管设置：阻止从用户和项目来源加载 Skills、agents、Hooks 和 MCP servers，使它们只能来自插件或托管设置。将其与 strictKnownMarketplaces 结合，可控制完整的自定义供应链：插件市场允许列表决定用户可以安装哪些插件，此设置则阻止一切并非来自插件或托管设置的内容。

该值可以是 true，表示锁定全部四类扩展入口；也可以是一个数组，列出要锁定的入口：

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

对于每个被锁定的入口，Claude Code 会跳过用户级和项目级来源，只加载插件提供的内容和托管来源：

Claude Code 会忽略当前版本无法识别的入口名称，而不会让设置文件失效，因此您可以在所有客户端完成更新前先加入新的入口名称。

管理插件

使用 /plugin 命令以交互方式管理插件：

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

在插件文档中了解有关插件系统的更多信息。

环境变量

环境变量让您可以控制 Claude Code 行为而无需编辑设置文件。任何变量也可以在 settings.json 中的 env 键下配置，以将其应用于每个会话或将其推出到您的团队。

请参阅环境变量参考了解完整列表。

Claude 可用的工具

Claude Code 可以访问一组用于读取、编辑、搜索、运行命令和编排 subagents 的工具。工具名称是您在权限规则和 hook 匹配器中使用的确切字符串。

请参阅工具参考了解完整列表和 Bash 工具行为详情。

另请参阅

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