Claude Code 设置

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

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

Claude Code 提供了丰富的设置来定制其行为。在交互式 REPL 中运行 /config 命令即可打开分页式设置界面，查看状态信息和修改配置选项。

配置范围

Claude Code 使用范围系统来决定配置的作用范围和共享对象。理解范围有助于你决定如何配置 Claude Code——无论是个人使用、团队协作还是企业部署。

可用范围

何时使用每个范围

托管范围适合：

• 必须在整个组织范围内执行的安全策略
• 不可推翻的合规性要求
• IT/DevOps 部署的标准化配置

用户范围适合：

• 你希望在所有项目中通用的个人偏好（主题、编辑器设置等）
• 你在所有项目中使用的工具和插件
• API 密钥和认证信息（安全存储）

项目范围适合：

• 团队共享设置（权限、hook、MCP 服务器）
• 整个团队都应该有的插件
• 统一协作者的工具配置

本地范围适合：

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

范围之间的交互

当同一个设置在多个范围中都有配置时，更具体的范围优先：

1. 托管（最高）— 不可被任何其他级别覆盖
2. 命令行参数 — 临时 session 覆盖
3. 本地 — 覆盖项目和用户设置
4. 项目 — 覆盖用户设置
5. 用户（最低）— 没有其他级别指定时生效

例如，如果某个权限在用户设置中是 Allow 但在项目设置中是 Deny，项目设置优先，该权限会被阻止。

各范围的适用对象

范围适用于 Claude Code 的多种功能：

设置文件

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/操作系统级策略：通过 macOS 和 Windows 原生设备管理下发：

    • macOS：com.anthropic.claudecode 托管偏好域（通过 Jamf、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。

详情参见托管设置和托管 MCP 配置。

注意

托管部署还可以用 strictKnownMarketplaces 来限制插件市场的添加。详情参见托管市场限制。

• 其他配置存储在 ~/.claude.json 中。该文件包含你的偏好（主题、通知设置、编辑器模式）、OAuth session、用户和本地范围的 MCP 服务器配置、按项目的状态（允许的工具、信任设置）以及各种缓存。项目范围的 MCP 服务器单独存储在 .mcp.json 中。

注意 Claude Code 会自动创建配置文件的带时间戳备份，保留最近五份以防数据丢失。

{
  "$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(/docs/.env)",
      "Read(/docs/.env.*)",
      "Read(/docs/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 验证的编辑器中获得自动补全和内联校验。

可用设置

settings.json 支持以下选项：

全局配置设置

以下显示偏好存储在 ~/.claude.json 而不是 settings.json 中。把它们加到 settings.json 里会触发 Schema 验证错误。

Worktree 设置

配置 --worktree 如何创建和管理 git worktree。用这些设置可以减少大型 monorepo 的磁盘占用和启动时间。

权限设置

权限规则语法

权限规则的格式为 Tool 或 Tool(specifier)。规则按顺序评估：先 Deny，再 Ask，最后 Allow。第一个匹配的规则生效。

简单示例：

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

沙箱设置

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

沙箱路径前缀

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

配置示例：

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

文件系统和网络限制可以通过两种方式配置（两者会合并）：

• sandbox.filesystem 设置（如上所示）：控制操作系统级沙箱边界的路径。这些限制适用于所有子进程命令（如 kubectl、terraform、npm），而不仅仅是 Claude 的文件工具。
• 权限规则：用 Edit Allow/Deny 规则控制 Claude 文件工具的访问，用 Read Deny 规则阻止读取，用 WebFetch Allow/Deny 规则控制网络域名。这些规则中的路径也会合并到沙箱配置中。

署名设置

Claude Code 会为 git commit 和 PR 添加署名。两者分别配置：

• commit 默认使用 git trailers（如 Co-Authored-By），可自定义或禁用
• PR 描述是纯文本

默认 commit 署名：

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

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

默认 PR 署名：

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

示例：

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

注意

attribution 设置优先于已弃用的 includeCoAuthoredBy 设置。要隐藏所有署名，把 commit 和 pr 都设为空字符串。

文件建议设置

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

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

该命令使用与 hook 相同的环境变量运行，包括 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 --query "$query" | head -20

Hook 配置

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

当 allowManagedHooksOnly 为 true 时：

• 托管 hook 和 SDK hook 正常加载
• 用户 hook、项目 hook、插件 hook 被屏蔽

限制 HTTP hook URL：

限制 HTTP hook 可以请求的 URL。支持 * 通配符。定义后，URL 不匹配的 HTTP hook 会被静默阻止。

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

限制 HTTP hook 环境变量：

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

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

设置优先级

设置按以下优先级应用（从高到低）：

1. 托管设置（服务器托管、MDM/操作系统级策略或托管设置）

   • IT 通过服务器、MDM 配置文件、注册表策略或托管设置文件部署的策略
   • 不可被任何其他级别覆盖，包括命令行参数
   • 在托管层内，优先级为：服务器托管 > MDM/操作系统级策略 > managed-settings.json > HKCU 注册表（仅限 Windows）。只使用一个托管来源，不会合并。

2. 命令行参数

   • 针对特定 session 的临时覆盖

3. 本地项目设置 (.claude/settings.local.json)

   • 个人的项目特定设置

4. 共享项目设置 (.claude/settings.json)

   • 签入版本控制、团队共享的项目设置

5. 用户设置 (~/.claude/settings.json)

   • 个人全局设置

这种层级确保组织策略始终得到执行，同时团队和个人仍可定制自己的体验。

比如你的用户设置允许 Bash(npm run *)，但项目的共享设置拒绝了它，那么项目设置优先，该命令会被阻止。

注意

数组设置跨范围合并。 当同一个数组设置（如 sandbox.filesystem.allowWrite 或 permissions.allow）出现在多个范围中时，数组会被拼接并去重，而非替换。低优先级范围可以添加条目而不会覆盖高优先级范围设置的条目，反之亦然。例如托管设置将 allowWrite 设为 ["//opt/company-tools"]，用户添加 ["~/.kube"]，两个路径都会包含在最终配置中。

验证当前设置

在 Claude Code 中运行 /status 可以查看哪些设置来源处于活动状态及其来源。输出显示每个配置层（托管、用户、项目）及其来源，如 Enterprise managed settings (remote)、Enterprise managed settings (plist)、Enterprise managed settings (HKLM) 或 Enterprise managed settings (file)。如果设置文件包含错误，/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(/docs/.env)",
      "Read(/docs/.env.*)",
      "Read(/docs/secrets/**)",
      "Read(/docs/config/credentials.json)",
      "Read(/docs/build)"
    ]
  }
}

这取代了已弃用的 ignorePatterns 配置。匹配这些模式的文件会从文件发现和搜索结果中排除，对这些文件的读取操作会被拒绝。

子 agent 配置

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

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

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

插件配置

Claude Code 支持插件系统，让你通过技能、agent、hook 和 MCP 服务器扩展功能。插件通过市场分发，可在用户和仓库级别配置。

插件设置

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

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

enabledPlugins

控制启用哪些插件。格式："plugin-name@marketplace-name": true/false

范围：

• 用户设置 (~/.claude/settings.json)：个人插件偏好
• 项目设置 (.claude/settings.json)：与团队共享的项目特定插件
• 本地设置 (.claude/settings.local.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）

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) 中可用
• 不可被用户或项目设置覆盖（最高优先级）
• 在网络/文件系统操作前执行（被阻止的来源永远不会执行）
• 对来源规范使用精确匹配（包括 git 来源的 ref、path），hostPattern 除外（使用正则匹配）

白名单行为：

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

所有支持的来源类型：

白名单支持七种市场来源类型。大多数来源使用精确匹配，而 hostPattern 使用正则匹配市场主机。

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://git@git.example.com/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 标头）

注意

基于 URL 的市场仅下载 marketplace.json 文件，不会从服务器下载插件文件。基于 URL 的市场中的插件必须使用外部来源（GitHub、npm 或 git URL）而非相对路径。对于使用相对路径的插件，请改用基于 Git 的市场。详情参见故障排除。

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

字段：hostPattern（必填：匹配市场主机的正则模式）

当你想允许来自特定主机的所有市场而不逐一列举每个仓库时，使用主机模式匹配。这对于有内部 GitHub Enterprise 或 GitLab 服务器、开发者会自建市场的组织特别有用。

按来源类型提取主机：

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

配置示例：

示例 — 仅允许特定市场：

{
  "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 字段必须完全匹配（或者两者都未定义）

不匹配的来源示例：

// These are DIFFERENT sources:
{ "source": "github", "repo": "acme-corp/plugins" }
{ "source": "github", "repo": "acme-corp/plugins", "ref": "main" }

// These are also DIFFERENT:
{ "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 手动添加允许的市场，但不会自动使用。

重要说明：

• 在任何网络请求或文件系统操作之前检查限制
• 被阻止时，用户会看到明确的错误消息，说明来源被托管策略阻止
• 限制仅适用于添加新市场；已安装的市场仍可访问
• 托管设置具有最高优先级，不可被覆盖

面向用户的文档参见托管市场限制。

管理插件

用 /plugin 命令可以交互式地管理插件：

• 从市场浏览可用插件
• 安装/卸载插件
• 启用/禁用插件
• 查看插件详情（提供的命令、agent、hook）
• 添加/删除市场

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

环境变量

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

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

Claude 可用的工具

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

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

另请参阅

• 权限：权限系统、规则语法、工具特定模式和托管策略
• 认证：设置 Claude Code 的用户访问
• 故障排除：常见配置问题的解决方案