Skip to main content
Claude Code 提供多种设置来配置其行为以满足您的需求。您可以在使用交互式 REPL 时运行 /config 命令来配置 Claude Code,这会打开一个选项卡式设置界面,您可以在其中查看状态信息并修改配置选项。

配置作用域

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

可用作用域

作用域位置影响范围与团队共享?
Managed系统级 managed-settings.json机器上的所有用户是(由 IT 部署)
User~/.claude/ 目录您,跨所有项目
Project存储库中的 .claude/此存储库上的所有协作者是(提交到 git)
Local.claude/*.local.* 文件您,仅在此存储库中否(gitignored)

何时使用每个作用域

Managed 作用域用于:
  • 必须在整个组织范围内强制执行的安全策略
  • 无法被覆盖的合规要求
  • 由 IT/DevOps 部署的标准化配置
User 作用域最适合:
  • 您想在任何地方使用的个人偏好(主题、编辑器设置)
  • 您在所有项目中使用的工具和插件
  • API 密钥和身份验证(安全存储)
Project 作用域最适合:
  • 团队共享的设置(权限、hooks、MCP servers)
  • 整个团队应该拥有的插件
  • 跨协作者标准化工具
Local 作用域最适合:
  • 特定项目的个人覆盖
  • 在与团队共享之前测试配置
  • 对其他人不适用的特定于机器的设置

作用域如何相互作用

当在多个作用域中配置相同的设置时,更具体的作用域优先:
  1. Managed(最高)- 无法被任何内容覆盖
  2. 命令行参数 - 临时会话覆盖
  3. Local - 覆盖项目和用户设置
  4. Project - 覆盖用户设置
  5. User(最低)- 当没有其他内容指定设置时应用
例如,如果在用户设置中允许某个权限,但在项目设置中拒绝,则项目设置优先,权限被阻止。

哪些功能使用作用域

作用域适用于许多 Claude Code 功能:
功能用户位置项目位置本地位置
Settings~/.claude/settings.json.claude/settings.json.claude/settings.local.json
Subagents~/.claude/agents/.claude/agents/
MCP servers~/.claude.json.mcp.json~/.claude.json(每个项目)
Plugins~/.claude/settings.json.claude/settings.json.claude/settings.local.json
CLAUDE.md~/.claude/CLAUDE.mdCLAUDE.md.claude/CLAUDE.mdCLAUDE.local.md

设置文件

settings.json 文件是我们用于通过分层设置配置 Claude Code 的官方机制:
  • 用户设置~/.claude/settings.json 中定义,适用于所有项目。
  • 项目设置保存在您的项目目录中:
    • .claude/settings.json 用于检入源代码管理并与您的团队共享的设置
    • .claude/settings.local.json 用于未检入的设置,适用于个人偏好和实验。Claude Code 将在创建 .claude/settings.local.json 时配置 git 以忽略它。
  • Managed 设置:对于需要集中控制的组织,Claude Code 支持可以部署到系统目录的 managed-settings.jsonmanaged-mcp.json 文件:
    • macOS:/Library/Application Support/ClaudeCode/
    • Linux 和 WSL:/etc/claude-code/
    • Windows:C:\Program Files\ClaudeCode\
    这些是系统范围的路径(不是像 ~/Library/... 这样的用户主目录),需要管理员权限。它们设计用于由 IT 管理员部署。
    有关详细信息,请参阅 Managed 设置Managed MCP 配置
    Managed 部署还可以使用 strictKnownMarketplaces 限制插件市场添加。有关更多信息,请参阅 Managed 市场限制
  • 其他配置存储在 ~/.claude.json 中。此文件包含您的偏好(主题、通知设置、编辑器模式)、OAuth 会话、用户和本地作用域的 MCP server 配置、每个项目的状态(允许的工具、信任设置)和各种缓存。项目作用域的 MCP servers 单独存储在 .mcp.json 中。
Claude Code 自动创建配置文件的时间戳备份,并保留最近五个备份以防止数据丢失。
示例 settings.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": [
    "欢迎来到 Acme Corp!在 docs.acme.com 查看我们的代码指南",
    "提醒:所有 PR 都需要代码审查",
    "新的安全政策已生效"
  ]
}
上面示例中的 $schema 行指向 Claude Code 设置的官方 JSON 架构。将其添加到您的 settings.json 可在 VS Code、Cursor 和任何其他支持 JSON 架构验证的编辑器中启用自动完成和内联验证。

可用设置

settings.json 支持多个选项:
描述示例
apiKeyHelper自定义脚本,在 /bin/sh 中执行,以生成身份验证值。此值将作为 X-Api-KeyAuthorization: Bearer 标头发送用于模型请求/bin/generate_temp_api_key.sh
cleanupPeriodDays非活动时间超过此期间的会话在启动时被删除。设置为 0 立即删除所有会话。(默认:30 天)20
companyAnnouncements在启动时显示给用户的公告。如果提供多个公告,它们将随机循环显示。["欢迎来到 Acme Corp!在 docs.acme.com 查看我们的代码指南"]
env将应用于每个会话的环境变量{"FOO": "bar"}
attribution自定义 git 提交和拉取请求的归属。请参阅 Attribution 设置{"commit": "🤖 Generated with Claude Code", "pr": ""}
includeCoAuthoredBy已弃用:改用 attribution。是否在 git 提交和拉取请求中包含 co-authored-by Claude 署名(默认:truefalse
permissions有关权限结构,请参阅下表。
hooks配置自定义命令以在生命周期事件处运行。有关格式,请参阅 hooks 文档请参阅 hooks
disableAllHooks禁用所有 hookstrue
allowManagedHooksOnly(仅 Managed 设置)防止加载用户、项目和插件 hooks。仅允许 managed hooks 和 SDK hooks。请参阅 Hook 配置true
allowManagedPermissionRulesOnly(仅 Managed 设置)防止用户和项目设置定义 allowaskdeny 权限规则。仅应用 managed 设置中的规则。请参阅 仅 Managed 设置true
model覆盖 Claude Code 使用的默认模型"claude-sonnet-4-5-20250929"
otelHeadersHelper生成动态 OpenTelemetry 标头的脚本。在启动时和定期运行(请参阅 动态标头/bin/generate_otel_headers.sh
statusLine配置自定义状态行以显示上下文。请参阅 statusLine 文档{"type": "command", "command": "~/.claude/statusline.sh"}
fileSuggestion@ 文件自动完成配置自定义脚本。请参阅 文件建议设置{"type": "command", "command": "~/.claude/file-suggestion.sh"}
respectGitignore控制 @ 文件选择器是否遵守 .gitignore 模式。当为 true(默认)时,匹配 .gitignore 模式的文件被排除在建议之外false
outputStyle配置输出样式以调整系统提示。请参阅 输出样式文档"Explanatory"
forceLoginMethod使用 claudeai 限制登录到 Claude.ai 账户,使用 console 限制登录到 Claude Console(API 使用计费)账户claudeai
forceLoginOrgUUID指定组织的 UUID 以在登录期间自动选择它,绕过组织选择步骤。需要设置 forceLoginMethod"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
enableAllProjectMcpServers自动批准项目 .mcp.json 文件中定义的所有 MCP serverstrue
enabledMcpjsonServers要批准的 .mcp.json 文件中的特定 MCP servers 列表["memory", "github"]
disabledMcpjsonServers要拒绝的 .mcp.json 文件中的特定 MCP servers 列表["filesystem"]
allowedMcpServers在 managed-settings.json 中设置时,用户可以配置的 MCP servers 的允许列表。未定义 = 无限制,空数组 = 锁定。适用于所有作用域。拒绝列表优先。请参阅 Managed MCP 配置[{ "serverName": "github" }]
deniedMcpServers在 managed-settings.json 中设置时,明确阻止的 MCP servers 的拒绝列表。适用于所有作用域,包括 managed servers。拒绝列表优先于允许列表。请参阅 Managed MCP 配置[{ "serverName": "filesystem" }]
strictKnownMarketplaces在 managed-settings.json 中设置时,用户可以添加的插件市场的允许列表。未定义 = 无限制,空数组 = 锁定。仅适用于市场添加。请参阅 Managed 市场限制[{ "source": "github", "repo": "acme-corp/plugins" }]
awsAuthRefresh修改 .aws 目录的自定义脚本(请参阅 高级凭证配置aws sso login --profile myprofile
awsCredentialExport输出包含 AWS 凭证的 JSON 的自定义脚本(请参阅 高级凭证配置/bin/generate_aws_grant.sh
alwaysThinkingEnabled为所有会话默认启用 扩展思考。通常通过 /config 命令而不是直接编辑来配置true
plansDirectory自定义计划文件的存储位置。路径相对于项目根目录。默认:~/.claude/plans"./plans"
showTurnDuration在响应后显示轮次持续时间消息(例如”Cooked for 1m 6s”)。设置为 false 以隐藏这些消息true
spinnerVerbs自定义在微调器和轮次持续时间消息中显示的操作动词。将 mode 设置为 "replace" 以仅使用您的动词,或 "append" 以将它们添加到默认值{"mode": "append", "verbs": ["Pondering", "Crafting"]}
language配置 Claude 的首选响应语言(例如 "japanese""spanish""french")。Claude 将默认以此语言响应"japanese"
autoUpdatesChannel遵循更新的发布渠道。使用 "stable" 获取通常约一周前的版本并跳过有重大回归的版本,或使用 "latest"(默认)获取最新版本"stable"
spinnerTipsEnabled在 Claude 工作时在微调器中显示提示。设置为 false 以禁用提示(默认:truefalse
terminalProgressBarEnabled启用终端进度条,在 Windows Terminal 和 iTerm2 等支持的终端中显示进度(默认:truefalse
prefersReducedMotion减少或禁用 UI 动画(微调器、闪烁、闪光效果)以实现可访问性true
teammateModeagent team 队友的显示方式:auto(在 tmux 或 iTerm2 中选择分割窗格,否则为进程内)、in-processtmux。请参阅 设置 agent teams"in-process"

权限设置

描述示例
allow允许工具使用的权限规则数组。有关模式匹配详细信息,请参阅下面的 权限规则语法[ "Bash(git diff *)" ]
ask在工具使用时要求确认的权限规则数组。有关详细信息,请参阅下面的 权限规则语法[ "Bash(git push *)" ]
deny拒绝工具使用的权限规则数组。使用此选项从 Claude Code 访问中排除敏感文件。请参阅 权限规则语法Bash 权限限制[ "WebFetch", "Bash(curl *)", "Read(./.env)", "Read(./secrets/**)" ]
additionalDirectoriesClaude 有权访问的其他工作目录[ "../docs/" ]
defaultMode打开 Claude Code 时的默认权限模式"acceptEdits"
disableBypassPermissionsMode设置为 "disable" 以防止激活 bypassPermissions 模式。这禁用 --dangerously-skip-permissions 命令行标志。请参阅 managed 设置"disable"

权限规则语法

权限规则遵循格式 ToolTool(specifier)。规则按顺序评估:首先是拒绝规则,然后是询问,最后是允许。第一个匹配的规则获胜。 快速示例:
规则效果
Bash匹配所有 Bash 命令
Bash(npm run *)匹配以 npm run 开头的命令
Read(./.env)匹配读取 .env 文件
WebFetch(domain:example.com)匹配对 example.com 的获取请求
有关完整的规则语法参考,包括通配符行为、Read、Edit、WebFetch、MCP 和 Task 规则的工具特定模式,以及 Bash 模式的安全限制,请参阅 权限规则语法

Sandbox 设置

配置高级沙箱行为。沙箱将 bash 命令与您的文件系统和网络隔离。有关详细信息,请参阅 Sandboxing 文件系统和网络限制通过 Read、Edit 和 WebFetch 权限规则配置,而不是通过这些沙箱设置。
描述示例
enabled启用 bash 沙箱(macOS、Linux 和 WSL2)。默认:falsetrue
autoAllowBashIfSandboxed沙箱化时自动批准 bash 命令。默认:truetrue
excludedCommands应在沙箱外运行的命令["git", "docker"]
allowUnsandboxedCommands允许命令通过 dangerouslyDisableSandbox 参数在沙箱外运行。当设置为 false 时,dangerouslyDisableSandbox 逃生舱口完全禁用,所有命令必须沙箱化(或在 excludedCommands 中)。对于需要严格沙箱的企业政策很有用。默认:truefalse
network.allowUnixSockets沙箱中可访问的 Unix 套接字路径(用于 SSH 代理等)["~/.ssh/agent-socket"]
network.allowAllUnixSockets允许沙箱中的所有 Unix 套接字连接。默认:falsetrue
network.allowLocalBinding允许绑定到 localhost 端口(仅 macOS)。默认:falsetrue
network.allowedDomains允许出站网络流量的域数组。支持通配符(例如 *.example.com)。["github.com", "*.npmjs.org"]
network.httpProxyPort如果您想使用自己的代理,则使用 HTTP 代理端口。如果未指定,Claude 将运行自己的代理。8080
network.socksProxyPort如果您想使用自己的代理,则使用 SOCKS5 代理端口。如果未指定,Claude 将运行自己的代理。8081
enableWeakerNestedSandbox为无特权 Docker 环境启用较弱的沙箱(仅 Linux 和 WSL2)。降低安全性。 默认:falsetrue
配置示例:
{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker"],
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],
      "allowUnixSockets": [
        "/var/run/docker.sock"
      ],
      "allowLocalBinding": true
    }
  },
  "permissions": {
    "deny": [
      "Read(.envrc)",
      "Read(~/.aws/**)"
    ]
  }
}
文件系统和网络限制使用标准权限规则:
  • 使用 Read 拒绝规则阻止 Claude 读取特定文件或目录
  • 使用 Edit 允许规则让 Claude 写入当前工作目录之外的目录
  • 使用 Edit 拒绝规则阻止写入特定路径
  • 使用 WebFetch 允许/拒绝规则控制 Claude 可以访问哪些网络域

Attribution 设置

Claude Code 为 git 提交和拉取请求添加归属。这些是单独配置的:
  • 提交默认使用 git trailers(如 Co-Authored-By),可以自定义或禁用
  • 拉取请求描述是纯文本
描述
commitgit 提交的归属,包括任何 trailers。空字符串隐藏提交归属
pr拉取请求描述的归属。空字符串隐藏拉取请求归属
默认提交归属:
🤖 Generated with [Claude Code](https://claude.com/claude-code)

   Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
默认拉取请求归属:
🤖 Generated with [Claude Code](https://claude.com/claude-code)
示例:
{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: AI <[email protected]>",
    "pr": ""
  }
}
attribution 设置优先于已弃用的 includeCoAuthoredBy 设置。要隐藏所有归属,请将 commitpr 设置为空字符串。

文件建议设置

@ 文件路径自动完成配置自定义命令。内置文件建议使用快速文件系统遍历,但大型 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 --query "$query" | head -20

Hook 配置

仅 Managed 设置:控制允许运行哪些 hooks。此设置只能在 managed 设置 中配置,为管理员提供对 hook 执行的严格控制。 allowManagedHooksOnlytrue 时的行为:
  • 加载 Managed hooks 和 SDK hooks
  • 阻止用户 hooks、项目 hooks 和插件 hooks
配置:
{
  "allowManagedHooksOnly": true
}

设置优先级

设置按优先级顺序应用。从最高到最低:
  1. Managed 设置 (managed-settings.json)
    • 由 IT/DevOps 部署到系统目录的策略
    • 无法被用户或项目设置覆盖
  2. 命令行参数
    • 特定会话的临时覆盖
  3. 本地项目设置 (.claude/settings.local.json)
    • 个人项目特定设置
  4. 共享项目设置 (.claude/settings.json)
    • 源代码管理中的团队共享项目设置
  5. 用户设置 (~/.claude/settings.json)
    • 个人全局设置
此层次结构确保组织策略始终被强制执行,同时仍允许团队和个人自定义其体验。 例如,如果您的用户设置允许 Bash(npm run *),但项目的共享设置拒绝它,则项目设置优先,命令被阻止。

关于配置系统的关键要点

  • 内存文件 (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 密钥、机密和环境文件)的文件,请在您的 .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": "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

仅 Managed 设置:控制用户可以添加哪些插件市场。此设置只能在 managed-settings.json 中配置,为管理员提供对市场源的严格控制。 Managed 设置文件位置
  • macOS/Library/Application Support/ClaudeCode/managed-settings.json
  • Linux 和 WSL/etc/claude-code/managed-settings.json
  • WindowsC:\Program Files\ClaudeCode\managed-settings.json
关键特征
  • 仅在 managed 设置 (managed-settings.json) 中可用
  • 无法被用户或项目设置覆盖(最高优先级)
  • 在网络/文件系统操作之前强制执行(阻止的源永远不会执行)
  • 对源规范使用精确匹配(包括 git 源的 refpath),除了 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(可选:子目录)
  1. 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(可选:子目录)
  1. 基于 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 的市场。有关详细信息,请参阅 故障排除
  1. NPM 包
{ "source": "npm", "package": "@acme-corp/claude-plugins" }
{ "source": "npm", "package": "@acme-corp/approved-marketplace" }
字段:package(必需,支持作用域包)
  1. 文件路径
{ "source": "file", "path": "/usr/local/share/claude/acme-marketplace.json" }
{ "source": "file", "path": "/opt/acme-corp/plugins/marketplace.json" }
字段:path(必需:marketplace.json 文件的绝对路径)
  1. 目录路径
{ "source": "directory", "path": "/usr/local/share/claude/acme-plugins" }
{ "source": "directory", "path": "/opt/acme-corp/approved-marketplaces" }
字段:path(必需:包含 .claude-plugin/marketplace.json 的目录的绝对路径)
  1. 主机模式匹配
{ "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 提取主机名
  • npmfiledirectory:不支持主机模式匹配
配置示例 示例:仅允许特定市场:
{
  "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 的源(githubgit),这包括所有可选字段:
  • repourl 必须精确匹配
  • 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 的比较
方面strictKnownMarketplacesextraKnownMarketplaces
目的组织策略强制执行团队便利
设置文件managed-settings.json任何设置文件
行为阻止非允许列表的添加自动安装缺失的市场
何时强制执行在网络/文件系统操作之前在用户信任提示之后
可以被覆盖否(最高优先级)是(由更高优先级设置)
源格式直接源对象具有嵌套源的命名市场
用例合规、安全限制入职、标准化
格式差异 strictKnownMarketplaces 使用直接源对象:
{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme-corp/plugins" }
  ]
}
extraKnownMarketplaces 需要命名市场:
{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "github", "repo": "acme-corp/plugins" }
    }
  }
}
重要说明
  • 限制在任何网络请求或文件系统操作之前检查
  • 被阻止时,用户会看到清晰的错误消息,指示源被 managed 策略阻止
  • 限制仅适用于添加新市场;以前安装的市场保持可访问
  • Managed 设置具有最高优先级,无法被覆盖
有关面向用户的文档,请参阅 Managed 市场限制

管理插件

使用 /plugin 命令以交互方式管理插件:
  • 浏览市场中的可用插件
  • 安装/卸载插件
  • 启用/禁用插件
  • 查看插件详细信息(提供的命令、agents、hooks)
  • 添加/删除市场
插件文档 中了解有关插件系统的更多信息。

环境变量

Claude Code 支持以下环境变量来控制其行为:
所有环境变量也可以在 settings.json 中配置。这是自动为每个会话设置环境变量或为整个团队或组织推出一组环境变量的有用方式。
变量目的
ANTHROPIC_API_KEY作为 X-Api-Key 标头发送的 API 密钥,通常用于 Claude SDK(对于交互式使用,运行 /login
ANTHROPIC_AUTH_TOKENAuthorization 标头的自定义值(您在此处设置的值将以 Bearer 为前缀)
ANTHROPIC_CUSTOM_HEADERS要添加到请求的自定义标头(Name: Value 格式,多个标头用换行符分隔)
ANTHROPIC_DEFAULT_HAIKU_MODEL请参阅 模型配置
ANTHROPIC_DEFAULT_OPUS_MODEL请参阅 模型配置
ANTHROPIC_DEFAULT_SONNET_MODEL请参阅 模型配置
ANTHROPIC_FOUNDRY_API_KEYMicrosoft Foundry 身份验证的 API 密钥(请参阅 Microsoft Foundry
ANTHROPIC_FOUNDRY_BASE_URLFoundry 资源的完整基础 URL(例如 https://my-resource.services.ai.azure.com/anthropic)。ANTHROPIC_FOUNDRY_RESOURCE 的替代方案(请参阅 Microsoft Foundry
ANTHROPIC_FOUNDRY_RESOURCEFoundry 资源名称(例如 my-resource)。如果未设置 ANTHROPIC_FOUNDRY_BASE_URL,则为必需(请参阅 Microsoft Foundry
ANTHROPIC_MODEL要使用的模型设置的名称(请参阅 模型配置
ANTHROPIC_SMALL_FAST_MODEL已弃用 用于后台任务的 Haiku 级模型 的名称
ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION使用 Bedrock 时覆盖 Haiku 级模型的 AWS 区域
AWS_BEARER_TOKEN_BEDROCKBedrock API 密钥用于身份验证(请参阅 Bedrock API 密钥
BASH_DEFAULT_TIMEOUT_MS长时间运行的 bash 命令的默认超时
BASH_MAX_OUTPUT_LENGTHbash 输出中的最大字符数,超过此数字后会进行中间截断
BASH_MAX_TIMEOUT_MS模型可以为长时间运行的 bash 命令设置的最大超时
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE设置触发自动压缩的上下文容量百分比(1-100)。默认情况下,自动压缩在约 95% 容量时触发。使用较低的值(如 50)以更早压缩。高于默认阈值的值无效。适用于主对话和 subagents。此百分比与 状态行 中可用的 context_window.used_percentage 字段对齐
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR在每个 Bash 命令后返回到原始工作目录
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD设置为 1 以从使用 --add-dir 指定的目录加载 CLAUDE.md 文件。默认情况下,其他目录不加载内存文件1
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS设置为 1 以启用 agent teams。Agent teams 是实验性的,默认禁用
CLAUDE_CODE_API_KEY_HELPER_TTL_MS应刷新凭证的间隔(以毫秒为单位)(使用 apiKeyHelper 时)
CLAUDE_CODE_CLIENT_CERT用于 mTLS 身份验证的客户端证书文件的路径
CLAUDE_CODE_CLIENT_KEY_PASSPHRASE加密 CLAUDE_CODE_CLIENT_KEY 的密码(可选)
CLAUDE_CODE_CLIENT_KEY用于 mTLS 身份验证的客户端私钥文件的路径
CLAUDE_CODE_EFFORT_LEVEL为支持的模型设置努力级别。值:lowmediumhigh(默认)。较低的努力更快且更便宜,较高的努力提供更深入的推理。目前仅支持 Opus 4.6。请参阅 调整努力级别
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS设置为 1 以禁用 Anthropic API 特定的 anthropic-beta 标头。当使用具有第三方提供商的 LLM 网关时遇到”Unexpected value(s) for the anthropic-beta header”之类的问题时,请使用此选项
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS设置为 1 以禁用所有后台任务功能,包括 Bash 和 subagent 工具上的 run_in_background 参数、自动后台处理和 Ctrl+B 快捷键
CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY设置为 1 以禁用”Claude 做得怎么样?“会话质量调查。当使用第三方提供商或禁用遥测时也会禁用。请参阅 会话质量调查
CLAUDE_CODE_EXIT_AFTER_STOP_DELAY查询循环变为空闲后自动退出前等待的时间(以毫秒为单位)。对于使用 SDK 模式的自动化工作流和脚本很有用
CLAUDE_CODE_PROXY_RESOLVES_HOSTS设置为 true 以允许代理执行 DNS 解析而不是调用者。对于代理应处理主机名解析的环境选择加入
CLAUDE_CODE_TASK_LIST_ID跨会话共享任务列表。在多个 Claude Code 实例中设置相同的 ID 以协调共享任务列表。请参阅 任务列表
CLAUDE_CODE_TEAM_NAME此队友所属的 agent team 的名称。在 agent team 成员上自动设置
CLAUDE_CODE_TMPDIR覆盖用于内部临时文件的临时目录。Claude Code 将 /claude/ 附加到此路径。默认:Unix/macOS 上的 /tmp,Windows 上的 os.tmpdir()
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC等同于设置 DISABLE_AUTOUPDATERDISABLE_BUG_COMMANDDISABLE_ERROR_REPORTINGDISABLE_TELEMETRY
CLAUDE_CODE_DISABLE_TERMINAL_TITLE设置为 1 以禁用基于对话上下文的自动终端标题更新
CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION设置为 false 以禁用提示建议(/config 中的”提示建议”切换)。这些是 Claude 响应后出现在您的提示输入中的灰显预测。请参阅 提示建议
CLAUDE_CODE_ENABLE_TASKS设置为 false 以临时恢复到之前的 TODO 列表而不是任务跟踪系统。默认:true。请参阅 任务列表
CLAUDE_CODE_ENABLE_TELEMETRY设置为 1 以启用用于指标和日志记录的 OpenTelemetry 数据收集。在配置 OTel 导出器之前需要。请参阅 监控
CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS覆盖文件读取的默认令牌限制。当您需要完整读取较大文件时很有用
CLAUDE_CODE_HIDE_ACCOUNT_INFO设置为 1 以从 Claude Code UI 中隐藏您的电子邮件地址和组织名称。在流式传输或录制时很有用
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL跳过 IDE 扩展的自动安装
CLAUDE_CODE_MAX_OUTPUT_TOKENS为大多数请求设置最大输出令牌数。默认:32,000。最大:64,000。增加此值会减少在 自动压缩 触发之前可用的有效上下文窗口。
CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS刷新动态 OpenTelemetry 标头的间隔(以毫秒为单位)(默认:1740000 / 29 分钟)。请参阅 动态标头
CLAUDE_CODE_PLAN_MODE_REQUIRED在需要计划批准的 agent team 队友上自动设置为 true。只读:由 Claude Code 在生成队友时设置。请参阅 需要计划批准
CLAUDE_CODE_SHELL覆盖自动 shell 检测。当您的登录 shell 与您的首选工作 shell 不同时很有用(例如 bash vs zsh
CLAUDE_CODE_SHELL_PREFIX命令前缀以包装所有 bash 命令(例如,用于日志记录或审计)。示例:/path/to/logger.sh 将执行 /path/to/logger.sh <command>
CLAUDE_CODE_SKIP_BEDROCK_AUTH跳过 Bedrock 的 AWS 身份验证(例如,使用 LLM 网关时)
CLAUDE_CODE_SKIP_FOUNDRY_AUTH跳过 Microsoft Foundry 的 Azure 身份验证(例如,使用 LLM 网关时)
CLAUDE_CODE_SKIP_VERTEX_AUTH跳过 Vertex 的 Google 身份验证(例如,使用 LLM 网关时)
CLAUDE_CODE_SUBAGENT_MODEL请参阅 模型配置
CLAUDE_CODE_USE_BEDROCK使用 Bedrock
CLAUDE_CODE_USE_FOUNDRY使用 Microsoft Foundry
CLAUDE_CODE_USE_VERTEX使用 Vertex
CLAUDE_CONFIG_DIR自定义 Claude Code 存储其配置和数据文件的位置
DISABLE_AUTOUPDATER设置为 1 以禁用自动更新。
DISABLE_BUG_COMMAND设置为 1 以禁用 /bug 命令
DISABLE_COST_WARNINGS设置为 1 以禁用成本警告消息
DISABLE_ERROR_REPORTING设置为 1 以选择退出 Sentry 错误报告
DISABLE_INSTALLATION_CHECKS设置为 1 以禁用安装警告。仅在手动管理安装位置时使用,因为这可能会掩盖标准安装的问题
DISABLE_NON_ESSENTIAL_MODEL_CALLS设置为 1 以禁用非关键路径(如风味文本)的模型调用
DISABLE_PROMPT_CACHING设置为 1 以禁用所有模型的提示缓存(优先于每个模型的设置)
DISABLE_PROMPT_CACHING_HAIKU设置为 1 以禁用 Haiku 模型的提示缓存
DISABLE_PROMPT_CACHING_OPUS设置为 1 以禁用 Opus 模型的提示缓存
DISABLE_PROMPT_CACHING_SONNET设置为 1 以禁用 Sonnet 模型的提示缓存
DISABLE_TELEMETRY设置为 1 以选择退出 Statsig 遥测(请注意,Statsig 事件不包括用户数据,如代码、文件路径或 bash 命令)
ENABLE_TOOL_SEARCH控制 MCP 工具搜索。值:auto(默认,在 10% 上下文处启用)、auto:N(自定义阈值,例如 auto:5 表示 5%)、true(始终开启)、false(禁用)
FORCE_AUTOUPDATE_PLUGINS设置为 true 以强制插件自动更新,即使主自动更新程序通过 DISABLE_AUTOUPDATER 禁用
HTTP_PROXY为网络连接指定 HTTP 代理服务器
HTTPS_PROXY为网络连接指定 HTTPS 代理服务器
IS_DEMO设置为 true 以启用演示模式:从 UI 隐藏电子邮件和组织,跳过入职,隐藏内部命令。对于流式传输或录制会话很有用
MAX_MCP_OUTPUT_TOKENSMCP 工具响应中允许的最大令牌数。当输出超过 10,000 个令牌时,Claude Code 显示警告(默认:25000)
MAX_THINKING_TOKENS覆盖 扩展思考 令牌预算。默认情况下,思考在最大预算(31,999 个令牌)处启用。使用此选项限制预算(例如 MAX_THINKING_TOKENS=10000)或完全禁用思考(MAX_THINKING_TOKENS=0)。对于 Opus 4.6,思考深度由 努力级别 控制,此变量被忽略,除非设置为 0 以禁用思考。
MCP_CLIENT_SECRET需要 预配置凭证 的 MCP servers 的 OAuth 客户端密钥。在使用 --client-secret 添加服务器时避免交互式提示
MCP_OAUTH_CALLBACK_PORTOAuth 重定向回调的固定端口,作为使用 预配置凭证 添加 MCP 服务器时 --callback-port 的替代方案
MCP_TIMEOUTMCP 服务器启动的超时(以毫秒为单位)
MCP_TOOL_TIMEOUTMCP 工具执行的超时(以毫秒为单位)
NO_PROXY将直接发出请求的域和 IP 列表,绕过代理
SLASH_COMMAND_TOOL_CHAR_BUDGET显示给 Skill 工具 的技能元数据的最大字符数(默认:15000)。为了向后兼容而保留的旧名称。
USE_BUILTIN_RIPGREP设置为 0 以使用系统安装的 rg 而不是 Claude Code 附带的 rg
VERTEX_REGION_CLAUDE_3_5_HAIKU使用 Vertex AI 时覆盖 Claude 3.5 Haiku 的区域
VERTEX_REGION_CLAUDE_3_7_SONNET使用 Vertex AI 时覆盖 Claude 3.7 Sonnet 的区域
VERTEX_REGION_CLAUDE_4_0_OPUS使用 Vertex AI 时覆盖 Claude 4.0 Opus 的区域
VERTEX_REGION_CLAUDE_4_0_SONNET使用 Vertex AI 时覆盖 Claude 4.0 Sonnet 的区域
VERTEX_REGION_CLAUDE_4_1_OPUS使用 Vertex AI 时覆盖 Claude 4.1 Opus 的区域

Claude 可用的工具

Claude Code 可以访问一组强大的工具,帮助它理解和修改您的代码库:
工具描述需要权限
AskUserQuestion提出多选问题以收集需求或澄清歧义
Bash在您的环境中执行 shell 命令(请参阅下面的 Bash 工具行为
TaskOutput从后台任务(bash shell 或 subagent)检索输出
Edit对特定文件进行有针对性的编辑
ExitPlanMode提示用户退出计划模式并开始编码
Glob基于模式匹配查找文件
Grep在文件内容中搜索模式
KillShell按 ID 杀死正在运行的后台 bash shell
MCPSearch当启用 工具搜索 时搜索和加载 MCP 工具
NotebookEdit修改 Jupyter notebook 单元格
Read读取文件的内容
Skill在主对话中执行 skill
Task运行 sub-agent 以处理复杂的多步骤任务
TaskCreate在任务列表中创建新任务
TaskGet检索特定任务的完整详细信息
TaskList列出所有任务及其当前状态
TaskUpdate更新任务状态、依赖项、详细信息或删除任务
WebFetch从指定的 URL 获取内容
WebSearch执行带有域过滤的网络搜索
Write创建或覆盖文件
LSP通过语言服务器的代码智能。在文件编辑后自动报告类型错误和警告。还支持导航操作:跳转到定义、查找引用、获取类型信息、列出符号、查找实现、跟踪调用层次结构。需要 代码智能插件 及其语言服务器二进制文件
权限规则可以使用 /allowed-tools 或在 权限设置 中配置。另请参阅 工具特定权限规则

Bash 工具行为

Bash 工具执行 shell 命令,具有以下持久性行为:
  • 工作目录持久化:当 Claude 更改工作目录(例如 cd /path/to/dir)时,后续 Bash 命令将在该目录中执行。您可以使用 CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1 在每个命令后重置为项目目录。
  • 环境变量不持久化:在一个 Bash 命令中设置的环境变量(例如 export MY_VAR=value)在后续 Bash 命令中可用。每个 Bash 命令在新的 shell 环境中运行。
要在 Bash 命令中提供环境变量,您有三个选项 选项 1:在启动 Claude Code 之前激活环境(最简单的方法) 在启动 Claude Code 之前在您的终端中激活您的虚拟环境:
conda activate myenv
# 或:source /path/to/venv/bin/activate
claude
这适用于 shell 环境,但在 Claude 的 Bash 命令中设置的环境变量不会在命令之间持久化。 选项 2:在启动 Claude Code 之前设置 CLAUDE_ENV_FILE(持久环境设置) 导出包含您的环境设置的 shell 脚本的路径:
export CLAUDE_ENV_FILE=/path/to/env-setup.sh
claude
其中 /path/to/env-setup.sh 包含:
conda activate myenv
# 或:source /path/to/venv/bin/activate
# 或:export MY_VAR=value
Claude Code 将在每个 Bash 命令之前获取此文件,使环境在所有命令中持久化。 选项 3:使用 SessionStart hook(项目特定配置) .claude/settings.json 中配置:
{
  "hooks": {
    "SessionStart": [{
      "matcher": "startup",
      "hooks": [{
        "type": "command",
        "command": "echo 'conda activate myenv' >> \"$CLAUDE_ENV_FILE\""
      }]
    }]
  }
}
hook 写入 $CLAUDE_ENV_FILE,然后在每个 Bash 命令之前获取。这对于团队共享的项目配置很理想。 有关选项 3 的更多详细信息,请参阅 SessionStart hooks

使用 hooks 扩展工具

您可以使用 Claude Code hooks 在任何工具执行之前或之后运行自定义命令。 例如,您可以在 Claude 修改 Python 文件后自动运行 Python 格式化程序,或通过阻止对某些路径的 Write 操作来防止修改生产配置文件。

另请参阅

  • 权限:权限系统、规则语法、工具特定模式和 managed 策略
  • 身份验证:设置用户对 Claude Code 的访问
  • 故障排除:常见配置问题的解决方案
Last modified on February 12, 2026