Claude Code 设置

使用全局和项目级设置以及环境变量配置 Claude Code。 Claude Code 提供各种设置来配置其行为以满足您的需求。您可以通过在使用交互式 REPL 时运行 /config 命令来配置 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 的企业部署，我们还支持企业管理策略设置。这些设置优先于用户和项目设置。系统管理员可以将策略部署到：
• macOS：/Library/Application Support/ClaudeCode/managed-settings.json
• Linux 和 WSL：/etc/claude-code/managed-settings.json
• Windows：C:\ProgramData\ClaudeCode\managed-settings.json 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"
}
}

可用设置

settings.json 支持多个选项： 键 描述 示例 apiKeyHelper 自定义脚本，在 /bin/sh 中执行，生成认证值。此值将作为 X-Api-Key 和 Authorization: Bearer 标头发送给模型请求 /bin/generate_temp_api_key.shcleanupPeriodDays 基于最后活动日期本地保留聊天记录的时长（默认：30 天） 20env 将应用于每个会话的环境变量 {"FOO": "bar"}includeCoAuthoredBy 是否在 git 提交和拉取请求中包含 co-authored-by Claude 署名（默认：true） falsepermissions 权限结构见下表。 hooks 配置在工具执行前后运行的自定义命令。参见钩子文档{"PreToolUse": {"Bash": "echo 'Running command...'"}}model 覆盖 Claude Code 使用的默认模型 "claude-3-5-sonnet-20241022"statusLine 配置自定义状态行以显示上下文。参见statusLine 文档{"type": "command", "command": "~/.claude/statusline.sh"}forceLoginMethod 使用 claudeai 限制登录到 Claude.ai 账户，console 限制登录到 Anthropic Console（API 使用计费）账户 claudeaienableAllProjectMcpServers 自动批准项目 .mcp.json 文件中定义的所有 MCP 服务器 trueenabledMcpjsonServers 从 .mcp.json 文件中批准的特定 MCP 服务器列表 ["memory", "github"]disabledMcpjsonServers 从 .mcp.json 文件中拒绝的特定 MCP 服务器列表 ["filesystem"]awsAuthRefresh 修改 .aws 目录的自定义脚本（参见高级凭据配置） aws sso login --profile myprofileawsCredentialExport 输出包含 AWS 凭据的 JSON 的自定义脚本（参见高级凭据配置） /bin/generate_aws_grant.sh

权限设置

键 描述 示例 allow 允许工具使用的权限规则数组 [ "Bash(git diff:*)" ]ask 在工具使用时要求确认的权限规则数组。 [ "Bash(git push:*)" ]deny 拒绝工具使用的权限规则数组。使用此选项还可以排除 Claude Code 访问的敏感文件。 [ "WebFetch", "Bash(curl:*)", "Read(./.env)", "Read(./secrets/**)" ]additionalDirectories Claude 可以访问的额外工作目录[ "../docs/" ]defaultMode 打开 Claude Code 时的默认权限模式"acceptEdits"disableBypassPermissionsMode 设置为 "disable" 以防止激活 bypassPermissions 模式。参见管理策略设置"disable"

设置优先级

设置按优先级顺序应用（从高到低）：

1. 企业管理策略（managed-settings.json）由 IT/DevOps 部署无法被覆盖
2. 命令行参数特定会话的临时覆盖
3. 本地项目设置（.claude/settings.local.json）个人项目特定设置
4. 共享项目设置（.claude/settings.json）源代码控制中的团队共享项目设置
5. 用户设置（~/.claude/settings.json）个人全局设置 此层次结构确保企业安全策略始终得到执行，同时仍允许团队和个人自定义其体验。

配置系统的关键点

• 内存文件（CLAUDE.md）：包含 Claude 在启动时加载的指令和上下文
• 设置文件（JSON）：配置权限、环境变量和工具行为
• 斜杠命令：可以在会话期间使用 /command-name 调用的自定义命令
• MCP 服务器：使用额外工具和集成扩展 Claude Code
• 优先级：更高级别的配置（企业）覆盖较低级别的配置（用户/项目）
• 继承：设置被合并，更具体的设置添加到或覆盖更广泛的设置

系统提示可用性

ℹ️ 注意： 与 claude.ai 不同，我们不在此网站上发布 Claude Code 的内部系统提示。使用 CLAUDE.md 文件或 --append-system-prompt 向 Claude Code 的行为添加自定义指令。

排除敏感文件

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

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

这替换了已弃用的 ignorePatterns 配置。匹配这些模式的文件将对 Claude Code 完全不可见，防止任何意外暴露敏感数据。

子代理配置

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

• 用户子代理：~/.claude/agents/ - 在您的所有项目中可用
• 项目子代理：.claude/agents/ - 特定于您的项目，可以与您的团队共享 子代理文件定义具有自定义提示和工具权限的专门 AI 助手。在子代理文档中了解更多关于创建和使用子代理的信息。

环境变量

Claude Code 支持以下环境变量来控制其行为：

ℹ️ 注意： 所有环境变量也可以在settings.json中配置。这作为自动为每个会话设置环境变量的方式很有用，或者为您的整个团队或组织推出一组环境变量。 变量 目的 ANTHROPIC_API_KEY 作为 X-Api-Key 标头发送的 API 密钥，通常用于 Claude SDK（对于交互使用，运行 /login） ANTHROPIC_AUTH_TOKENAuthorization 标头的自定义值（您在此处设置的值将以 Bearer 为前缀） ANTHROPIC_CUSTOM_HEADERS 您想要添加到请求的自定义标头（以 Name: Value 格式） ANTHROPIC_MODEL 要使用的自定义模型名称（参见模型配置） ANTHROPIC_SMALL_FAST_MODEL用于后台任务的 Haiku 类模型名称 ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION 使用 Bedrock 时覆盖小型/快速模型的 AWS 区域 AWS_BEARER_TOKEN_BEDROCK 用于身份验证的 Bedrock API 密钥（参见Bedrock API 密钥） BASH_DEFAULT_TIMEOUT_MS 长时间运行的 bash 命令的默认超时 BASH_MAX_TIMEOUT_MS 模型可以为长时间运行的 bash 命令设置的最大超时 BASH_MAX_OUTPUT_LENGTH bash 输出在中间截断之前的最大字符数 CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR 每个 Bash 命令后返回到原始工作目录 CLAUDE_CODE_API_KEY_HELPER_TTL_MS 应刷新凭据的间隔（以毫秒为单位）（使用 apiKeyHelper 时） CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL 跳过 IDE 扩展的自动安装 CLAUDE_CODE_MAX_OUTPUT_TOKENS 为大多数请求设置最大输出令牌数 CLAUDE_CODE_USE_BEDROCK 使用BedrockCLAUDE_CODE_USE_VERTEX 使用VertexCLAUDE_CODE_SKIP_BEDROCK_AUTH 跳过 Bedrock 的 AWS 身份验证（例如使用 LLM 网关时） CLAUDE_CODE_SKIP_VERTEX_AUTH 跳过 Vertex 的 Google 身份验证（例如使用 LLM 网关时） CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 等同于设置 DISABLE_AUTOUPDATER、DISABLE_BUG_COMMAND、DISABLE_ERROR_REPORTING 和 DISABLE_TELEMETRYCLAUDE_CODE_DISABLE_TERMINAL_TITLE 设置为 1 以禁用基于对话上下文的自动终端标题更新 DISABLE_AUTOUPDATER 设置为 1 以禁用自动更新。这优先于 autoUpdates 配置设置。 DISABLE_BUG_COMMAND 设置为 1 以禁用 /bug 命令 DISABLE_COST_WARNINGS 设置为 1 以禁用成本警告消息 DISABLE_ERROR_REPORTING 设置为 1 以选择退出 Sentry 错误报告 DISABLE_NON_ESSENTIAL_MODEL_CALLS 设置为 1 以禁用非关键路径的模型调用，如风味文本 DISABLE_TELEMETRY 设置为 1 以选择退出 Statsig 遥测（注意 Statsig 事件不包括用户数据，如代码、文件路径或 bash 命令） HTTP_PROXY 为网络连接指定 HTTP 代理服务器 HTTPS_PROXY 为网络连接指定 HTTPS 代理服务器 MAX_THINKING_TOKENS 强制模型思考预算 MCP_TIMEOUT MCP 服务器启动的超时时间（以毫秒为单位） MCP_TOOL_TIMEOUT MCP 工具执行的超时时间（以毫秒为单位） MAX_MCP_OUTPUT_TOKENS MCP 工具响应中允许的最大令牌数（默认：25000） USE_BUILTIN_RIPGREP 设置为 0 以使用系统安装的 rg 而不是 Claude Code 包含的 rgVERTEX_REGION_CLAUDE_3_5_HAIKU 使用 Vertex AI 时覆盖 Claude 3.5 Haiku 的区域 VERTEX_REGION_CLAUDE_3_5_SONNET 使用 Vertex AI 时覆盖 Claude Sonnet 3.5 的区域 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 config list
• 查看设置：claude config get <key>
• 更改设置：claude config set <key> <value>
• 推送到设置（对于列表）：claude config add <key> <value>
• 从设置中删除（对于列表）：claude config remove <key> <value> 默认情况下，config 更改您的项目配置。要管理您的全局配置，请使用 --global（或 -g）标志。

全局配置

要设置全局配置，请使用 claude config set -g <key> <value>： 键 描述 示例 autoUpdates 是否启用自动更新（默认：true）。启用时，Claude Code 会在后台自动下载和安装更新。重启 Claude Code 时应用更新。 falsepreferredNotifChannel 您希望接收通知的位置（默认：iterm2） iterm2、iterm2_with_bell、terminal_bell 或 notifications_disabledtheme 颜色主题 dark、light、light-daltonized 或 dark-daltonizedverbose 是否显示完整的 bash 和命令输出（默认：false） true

Claude 可用的工具

Claude Code 可以访问一组强大的工具，帮助它理解和修改您的代码库： 工具 描述 需要权限 Bash 在您的环境中执行 shell 命令 是 Edit 对特定文件进行有针对性的编辑 是 Glob 基于模式匹配查找文件 否 Grep 在文件内容中搜索模式 否 LS 列出文件和目录 否 MultiEdit 对单个文件原子性地执行多个编辑 是 NotebookEdit 修改 Jupyter notebook 单元格 是 NotebookRead 读取和显示 Jupyter notebook 内容 否 Read 读取文件内容 否 Task 运行子代理来处理复杂的多步骤任务 否 TodoWrite 创建和管理结构化任务列表 否 WebFetch 从指定 URL 获取内容 是 WebSearch 执行带有域过滤的网络搜索 是 Write 创建或覆盖文件 是 权限规则可以使用 /allowed-tools 或在权限设置中配置。

使用钩子扩展工具

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

另请参阅

• 身份和访问管理 - 了解 Claude Code 的权限系统
• IAM 和访问控制 - 企业策略管理
• 故障排除 - 常见配置问题的解决方案