文档索引

在此获取完整文档索引：https://code.claude.com/docs/llms.txt 使用此文件发现所有可用页面，然后再进一步探索。

Claude Code 设置

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

Claude Code 提供各种设置来配置其行为以满足你的需求。你可以在使用交互式 REPL 时运行 /config 命令来配置 Claude Code，这会打开一个带标签的设置界面，你可以在其中查看状态信息和修改配置选项。

配置作用域

Claude Code 使用作用域系统来确定配置的适用范围和共享对象。了解作用域有助于你决定如何为个人使用、团队协作或企业部署配置 Claude Code。

可用作用域

何时使用每个作用域

管理作用域适用于：

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

用户作用域最适合：

• 你想要到处使用的个人偏好（主题、编辑器设置）
• 你跨所有项目使用的工具和插件
• API 密钥和认证（安全存储）

项目作用域最适合：

• 团队共享设置（权限、钩子、MCP 服务器）
• 整个团队应该有的插件
• 跨协作者标准化工具

本地作用域最适合：

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

作用域如何交互

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

1. 管理（最高）- 不能被任何内容覆盖
2. 命令行参数 - 临时会话覆盖
3. 本地 - 覆盖项目和用户设置
4. 项目 - 覆盖用户设置
5. 用户（最低）- 当没有其他内容指定该设置时应用

例如，如果你的用户设置将 spinnerTipsEnabled 设置为 true 而项目设置将其设置为 false，则应用项目值。权限规则的行为不同，因为它们跨作用域合并而不是覆盖。参见设置优先级。

使用作用域的功能

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

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

设置文件

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

• 用户设置定义在 ~/.claude/settings.json 中，适用于所有项目。

• 项目设置保存在你的项目目录中：

  • .claude/settings.json 用于检入源代码控制并与团队共享的设置
  • .claude/settings.local.json 用于不检入的设置，适合个人偏好和实验。Claude Code 会在创建时配置 git 忽略 .claude/settings.local.json

• 管理设置：对于需要集中控制的组织，Claude Code 支持多种管理设置传递机制。所有使用相同的 JSON 格式，不能被用户或项目设置覆盖：

  • 服务器管理设置：通过 Claude.ai 管理控制台从 Anthropic 服务器传递。参见服务器管理设置。

  • MDM/OS 级策略：通过 macOS 和 Windows 上的原生设备管理传递：

    • macOS：com.anthropic.claudecode 托管偏好设置域。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\
    ⚠️

    Warning

    旧的 Windows 路径 C:\ProgramData\ClaudeCode\managed-settings.json 从 v2.1.75 起不再支持。将设置部署到该位置的管理员必须将文件迁移到 C:\Program Files\ClaudeCode\managed-settings.json。

    基于文件的管理设置还支持在与 managed-settings.json 相同的系统目录中的 managed-settings.d/ 处的 drop-in 目录。这让不同团队可以部署独立的策略片段而无需协调对单个文件的编辑。

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

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

  参见管理设置和管理 MCP 配置了解详情。

  此仓库包含 Jamf、Iru (Kandji)、Intune 和组策略的入门部署模板。将这些作为起点并根据需要调整。

  ℹ️

  Note

  管理部署还可以使用 strictKnownMarketplaces 限制插件市场添加。更多信息参见管理市场限制。

• 其他配置存储在 ~/.claude.json 中。此文件包含你的 OAuth 会话、用户和本地作用域的 MCP 服务器配置、按项目状态（允许的工具、信任设置）和各种缓存。项目作用域的 MCP 服务器单独存储在 .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 schema。将其添加到你的 settings.json 可以在 VS Code、Cursor 和任何支持 JSON schema 验证的编辑器中启用自动补全和内联验证。

发布的 schema 定期更新，可能不包括最近 CLI 版本中添加的设置，因此最近文档化字段上的验证警告不一定意味着你的配置无效。

编辑何时生效

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

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

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

可用设置

settings.json 支持许多选项：

全局配置设置

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

工作树设置

配置 --worktree 如何创建和管理工作树。

要将 .env 等 gitignore 文件复制到新工作树中，使用项目根目录中的 .worktreeinclude 文件而不是设置。

权限设置

权限规则语法

权限规则遵循格式 Tool 或 Tool(specifier)。规则按顺序评估：先拒绝规则，然后询问，然后允许。第一个匹配的规则获胜。

快速示例：

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

沙箱设置

配置高级沙箱行为。沙箱将 bash 命令与你的文件系统和网络隔离。参见沙箱了解详情。

沙箱路径前缀

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

旧的 //path 绝对路径前缀仍然有效。如果你之前使用单斜杠 /path 期望项目相对解析，切换到 ./path。此语法与 Read 和 Edit 权限规则不同，后者使用 //path 表示绝对路径，/path 表示项目相对路径。沙箱文件系统路径使用标准约定：/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 设置（如上所示）：在操作系统级沙箱边界控制路径。这些限制适用于所有子进程命令（例如 kubectl、terraform、npm），而不仅仅是 Claude 的文件工具。
• 权限规则：使用 Edit 允许/拒绝规则控制 Claude 的文件工具访问，Read 拒绝规则阻止读取，WebFetch 允许/拒绝规则控制网络域名。这些规则的路径也合并到沙箱配置中。

归属设置

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

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

默认提交归属：

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

   Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

默认拉取请求归属：

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

示例：

{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: AI <[email protected]>",
    "pr": ""
  }
}

文件建议设置

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

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

该命令使用与钩子相同的环境变量运行，包括 CLAUDE_PROJECT_DIR。它通过标准输入接收包含 query 字段的 JSON：

{"query": "src/comp"}

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

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

示例：

#!/bin/bash
query=$(cat | jq -r '.query')
your-repo-file-index --query "$query" | head -20

钩子配置

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

当 allowManagedHooksOnly 为 true 时的行为：

• 管理钩子和 SDK 钩子被加载
• 管理设置 enabledPlugins 中强制启用的插件的钩子被加载。这让管理员可以通过组织市场分发已审核的钩子，同时阻止其他所有内容。信任通过完整的 plugin@marketplace ID 授予，因此来自不同市场的同名插件仍然被阻止
• 用户钩子、项目钩子和所有其他插件钩子被阻止

限制 HTTP 钩子 URL：

限制 HTTP 钩子可以目标指向的 URL。支持 * 作为通配符进行匹配。当数组已定义时，目标指向不匹配 URL 的 HTTP 钩子被静默阻止。主机名匹配不区分大小写并忽略尾随的 FQDN 点，匹配 DNS 语义。

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

限制 HTTP 钩子环境变量：

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

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

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

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

该设置接受以下键：

助手将 JSON 信封写入标准输出。将设置放在 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 配置文件、注册表策略或管理设置文件部署的策略
   • 不能被任何其他级别覆盖，包括命令行参数
   • 在管理层内，优先级为：服务器管理 > MDM/OS 级策略 > 基于文件的（managed-settings.d/*.json + managed-settings.json）> HKCU 注册表（仅 Windows）。仅使用一个管理源；源不跨层合并。在基于文件的层内，drop-in 文件和基础文件合并在一起。
   • 嵌入主机如 Claude Desktop 可以通过 SDK managedSettings 选项提供策略。默认情况下，当存在任何管理层时这被忽略。管理员可以通过将 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 行确认正在读取哪些源。它不显示哪个层提供了每个单独的键。同一对话框中的 Config 标签是固定开关集（如主题和详细输出）的编辑器，不是你的 settings.json 内容的视图。如果设置文件包含错误，如无效 JSON 或验证失败的值，/status 会报告问题以便你修复。

关于配置系统的关键要点

• 记忆文件（CLAUDE.md）：包含 Claude 在启动时加载的指令和上下文
• 设置文件（JSON）：配置权限、环境变量和工具行为
• 技能：可以通过 /skill-name 调用或由 Claude 自动加载的自定义提示
• MCP 服务器：用额外的工具和集成扩展 Claude Code
• 优先级：较高层级的配置（管理）覆盖较低层级的（用户/项目）
• 继承：设置跨作用域合并；来自较高优先级作用域的标量值覆盖，数组连接

系统提示

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

排除敏感文件

要阻止 Claude Code 访问包含敏感信息（如 API 密钥、密钥和环境文件）的文件，使用 .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 支持插件系统，让你可以通过技能、代理、钩子和 MCP 服务器扩展功能。插件通过市场分发，可以在用户和仓库级别配置。

插件设置

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

作用域：

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

示例：

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

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）

每个市场条目还接受可选的 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、git 来源的 path），但 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（可选：分支/标签/SHA）、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://[email protected]/plugins.git", "ref": "v3.1", "path": "approved" }

字段：url（必需）、ref（可选：分支/标签/SHA）、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（必需，支持 scoped 包）

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{{CONTENT}}quot; }
{ "source": "hostPattern", "hostPattern": "^gitlab\\.internal\\.example\\.com{{CONTENT}}quot; }

字段：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{{CONTENT}}quot;
    }
  ]
}

精确匹配要求：

市场来源必须精确匹配才能允许用户的添加。对于基于 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 手动添加允许的市场，但它不会自动可用。

重要说明：

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

参见管理市场限制了解面向用户的文档。

strictPluginOnlyCustomization

仅管理设置：阻止来自用户和项目来源的技能、代理、钩子和 MCP 服务器，使它们只能来自插件或管理设置。将其与 strictKnownMarketplaces 结合以控制完整的自定义供应链：市场白名单控制用户可以安装哪些插件，此设置阻止不来自插件或管理设置的所有内容。

值为 true 以锁定所有四个表面，或命名要锁定的表面的数组：

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

对于每个锁定的表面，Claude Code 跳过用户级和项目级来源，仅加载插件提供的和管理来源：

Claude Code 版本不识别的表面名称被忽略而不是使设置文件失败，因此你可以在所有客户端更新之前添加新的表面名称。

管理插件

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

• 浏览市场的可用插件
• 安装/卸载插件
• 启用/禁用插件
• 查看插件详情（提供的技能、代理、钩子）
• 添加/移除市场

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

环境变量

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

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

Claude 可用的工具

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

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

另请参阅

• 权限：权限系统、规则语法、工具特定模式和管理策略
• 认证：设置用户对 Claude Code 的访问
• 调试你的配置：诊断设置、钩子或 MCP 服务器未生效的原因
• 安装和登录故障排除：安装、认证和平台问题