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 的 Windows 上部署到 /etc/claude-code/managed-settings.json。

Example settings.json
{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl:*)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  }
}

可用设置

settings.json 支持多个选项：

键	描述	示例
`apiKeyHelper`	自定义脚本，在 `/bin/sh` 中执行，用于生成认证值。此值通常作为模型请求的 `X-Api-Key`、`Authorization: Bearer` 和 `Proxy-Authorization: Bearer` 头发送	`/bin/generate_temp_api_key.sh`
`cleanupPeriodDays`	本地保留聊天记录的时间长度（默认：30 天）	`20`
`env`	将应用于每个会话的环境变量	`{"FOO": "bar"}`
`includeCoAuthoredBy`	是否在 git 提交和拉取请求中包含 `co-authored-by Claude` 署名（默认：`true`）	`false`
`permissions`	权限结构见下表。

权限设置

键	描述	示例
`allow`	允许工具使用的权限规则数组	`[ "Bash(git diff:*)" ]`
`deny`	拒绝工具使用的权限规则数组	`[ "WebFetch", "Bash(curl:*)" ]`
`additionalDirectories`	Claude 可以访问的额外工作目录	`[ "../docs/" ]`
`defaultMode`	打开 Claude Code 时的默认权限模式	`"allowEdits"`
`disableBypassPermissionsMode`	设置为 `"disable"` 以防止激活 `bypassPermissions` 模式。参见管理策略设置	`"disable"`

设置优先级

设置按优先级顺序应用：

企业策略（参见 IAM 文档）
命令行参数
本地项目设置
共享项目设置
用户设置

环境变量

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

所有环境变量也可以在 settings.json 中配置。这作为为每个会话自动设置环境变量的方式很有用，或者为整个团队或组织推出一组环境变量。

变量	目的
`ANTHROPIC_API_KEY`	作为 `X-Api-Key` 头发送的 API 密钥，通常用于 Claude SDK（对于交互式使用，运行 `/login`）
`ANTHROPIC_AUTH_TOKEN`	`Authorization` 和 `Proxy-Authorization` 头的自定义值（您在此处设置的值将以 `Bearer` 为前缀）
`ANTHROPIC_CUSTOM_HEADERS`	您想要添加到请求中的自定义头（以 `Name: Value` 格式）
`ANTHROPIC_MODEL`	要使用的自定义模型名称（参见模型配置）
`ANTHROPIC_SMALL_FAST_MODEL`	用于后台任务的 Haiku 类模型名称
`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_MAX_OUTPUT_TOKENS`	为大多数请求设置最大输出令牌数
`CLAUDE_CODE_USE_BEDROCK`	使用 Bedrock（参见 Bedrock & Vertex）
`CLAUDE_CODE_USE_VERTEX`	使用 Vertex（参见 Bedrock & Vertex）
`CLAUDE_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_TELEMETRY`
`DISABLE_AUTOUPDATER`	设置为 `1` 以禁用自动更新器
`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）

配置选项

我们正在将全局配置迁移到 settings.json。

claude config 将被弃用，取而代之的是 settings.json

要管理您的配置，请使用以下命令：

列出设置：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`）	`false`
`preferredNotifChannel`	您希望接收通知的位置（默认：`iterm2`）	`iterm2`、`iterm2_with_bell`、`terminal_bell` 或 `notifications_disabled`
`theme`	颜色主题	`dark`、`light`、`light-daltonized` 或 `dark-daltonized`
`verbose`	是否显示完整的 bash 和命令输出（默认：`false`）	`true`

Claude 可用的工具

Claude Code 可以访问一组强大的工具，帮助它理解和修改您的代码库：

工具	描述	需要权限
Agent	运行子代理来处理复杂的多步骤任务	否
Bash	在您的环境中执行 shell 命令	是
Edit	对特定文件进行有针对性的编辑	是
Glob	基于模式匹配查找文件	否
Grep	在文件内容中搜索模式	否
LS	列出文件和目录	否
MultiEdit	对单个文件原子性地执行多个编辑	是
NotebookEdit	修改 Jupyter notebook 单元格	是
NotebookRead	读取和显示 Jupyter notebook 内容	否
Read	读取文件内容	否
TodoRead	读取当前会话的任务列表	否
TodoWrite	创建和管理结构化任务列表	否
WebFetch	从指定 URL 获取内容	是
WebSearch	执行带域名过滤的网络搜索	是
Write	创建或覆盖文件	是

权限规则可以使用 /allowed-tools 或在权限设置中配置。

使用钩子扩展工具

您可以使用 Claude Code 钩子在任何工具执行之前或之后运行自定义命令。

例如，您可以在 Claude 修改 Python 文件后自动运行 Python 格式化程序，或者通过阻止对某些路径的写入操作来防止修改生产配置文件。

另请参阅

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

开始使用

使用 Claude Code 构建

部署

管理

配置

参考

资源

Claude Code 设置

设置文件

可用设置

权限设置

设置优先级

环境变量

配置选项

全局配置

Claude 可用的工具

使用钩子扩展工具

另请参阅

开始使用

使用 Claude Code 构建

部署

管理

配置

参考

资源

​设置文件

​可用设置

​权限设置

​设置优先级

​环境变量

​配置选项

​全局配置

​Claude 可用的工具

​使用钩子扩展工具

​另请参阅

设置文件

可用设置

权限设置

设置优先级

环境变量

配置选项

全局配置

Claude 可用的工具

使用钩子扩展工具

另请参阅