Claude Code 设置

Claude Code 提供了各种设置选项，以便根据您的需求配置其行为。您可以在使用交互式 REPL 时运行 /config 命令来配置 Claude Code。

设置文件

新的 settings.json 文件格式是我们通过层次化设置配置 Claude Code 的官方机制：

用户设置定义在 ~/.claude/settings.json 中，适用于所有项目。
项目设置保存在您的项目目录下，共享设置在 .claude/settings.json 中，本地项目设置在 .claude/settings.local.json 中。当创建 .claude/settings.local.json 时，Claude Code 会配置 git 忽略该文件。
对于 Claude Code 的企业部署，我们还支持企业管理策略设置。这些设置优先于用户和项目设置。系统管理员可以在 macOS 上将策略部署到 /Library/Application Support/ClaudeCode/policies.json，在 Linux 和通过 WSL 的 Windows 上部署到 /etc/claude-code/policies.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`	生成 Anthropic API 密钥的自定义脚本	`/bin/generate_temp_api_key.sh`
`cleanupPeriodDays`	本地保留聊天记录的时长（默认：30 天）	`20`
`env`	将应用于每个会话的环境变量	`{"FOO": "bar"}`
`includeCoAuthoredBy`	是否在 git 提交和拉取请求中包含 `co-authored-by Claude` 署名（默认：`true`）	`false`
`permissions`	`allow` 和 `deny` 键是权限规则的列表	`{"allow": [ "Bash(npm run lint)" ]}`

设置优先级

设置按以下优先级顺序应用：

企业策略
命令行参数
本地项目设置
共享项目设置
用户设置

权限

您可以使用 /permissions 查看和管理 Claude Code 的工具权限。此 UI 列出了所有权限规则及其来源的 settings.json 文件。

允许规则将允许 Claude Code 使用指定的工具，无需进一步手动批准。
拒绝规则将阻止 Claude Code 使用指定的工具。拒绝规则优先于允许规则。

权限规则使用以下格式：Tool(optional-specifier)

仅包含工具名称的规则匹配该工具的任何使用。例如，将 Bash 添加到允许规则列表中将允许 Claude Code 使用 Bash 工具而无需用户批准。查看Claude 可用的工具列表。

特定工具的权限规则

一些工具使用可选说明符来实现更精细的权限控制。例如，带有 Bash(git diff:*) 的允许规则将允许以 git diff 开头的 Bash 命令。以下工具支持带有说明符的权限规则：

Bash

Bash(npm run build) 匹配确切的 Bash 命令 npm run build
Bash(npm run test:*) 匹配以 npm run test 开头的 Bash 命令。

Claude Code 了解 shell 运算符（如 &&），因此像 Bash(safe-cmd:*) 这样的前缀匹配规则不会授予它运行 safe-cmd && other-cmd 命令的权限

Read 和 Edit

Edit 规则适用于所有编辑文件的内置工具。 Claude 将尽最大努力将 Read 规则应用于所有读取文件的内置工具，如 Grep、Glob 和 LS。

Read 和 Edit 规则都遵循 gitignore 规范。模式相对于包含 .claude/settings.json 的目录解析。要引用绝对路径，请使用 //。对于相对于您的主目录的路径，请使用 ~/。

Edit(docs/**) 匹配对项目中 docs 目录下文件的编辑
Read(~/.zshrc) 匹配对您的 ~/.zshrc 文件的读取
Edit(//tmp/scratch.txt) 匹配对 /tmp/scratch.txt 的编辑

WebFetch

WebFetch(domain:example.com) 匹配对 example.com 的获取请求

MCP

mcp__puppeteer 匹配由 puppeteer 服务器提供的任何工具（名称在 Claude Code 中配置）
mcp__puppeteer__puppeteer_navigate 匹配由 puppeteer 服务器提供的 puppeteer_navigate 工具

自动更新器权限选项

当 Claude Code 检测到它没有足够的权限写入您的全局 npm 前缀目录（自动更新所需）时，您将看到一个警告，指向本文档页面。有关自动更新器问题的详细解决方案，请参阅故障排除指南。

推荐：创建新的用户可写 npm 前缀

# 首先，保存现有全局包的列表，以便稍后迁移
npm list -g --depth=0 > ~/npm-global-packages.txt

# 为全局包创建一个目录
mkdir -p ~/.npm-global

# 配置 npm 使用新的目录路径
npm config set prefix ~/.npm-global

# 注意：根据您的 shell 将 ~/.bashrc 替换为 ~/.zshrc、~/.profile 或其他适当的文件
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc

# 应用新的 PATH 设置
source ~/.bashrc

# 现在在新位置重新安装 Claude Code
npm install -g @anthropic-ai/claude-code

# 可选：在新位置重新安装您之前的全局包
# 查看 ~/npm-global-packages.txt 并安装您想保留的包
# npm install -g package1 package2 package3...

为什么我们推荐这个选项：

避免修改系统目录权限
为您的全局 npm 包创建一个干净、专用的位置
遵循安全最佳实践

由于 Claude Code 正在积极开发中，我们建议使用上述推荐选项设置自动更新。

禁用自动更新器

如果您更喜欢禁用自动更新器而不是修复权限，可以将 DISABLE_AUTOUPDATER 环境变量设置为 1

优化您的终端设置

Claude Code 在正确配置的终端中效果最佳。请遵循以下指南优化您的体验。

支持的 shell：

Bash
Zsh
Fish

主题和外观

Claude 无法控制您终端的主题。这由您的终端应用程序处理。您可以在入门过程中或随时通过 /config 命令将 Claude Code 的主题与您的终端匹配

换行符

您有几种选项可以在 Claude Code 中输入换行符：

快速转义：输入 \ 后跟 Enter 键创建换行
键盘快捷键：在正确配置的情况下按 Option+Enter（Meta+Enter）

要在您的终端中设置 Option+Enter：

对于 Mac Terminal.app：

打开设置 → 配置文件 → 键盘
勾选”将 Option 键用作 Meta 键”

对于 iTerm2 和 VSCode 终端：

打开设置 → 配置文件 → 按键
在常规下，将左/右 Option 键设置为”Esc+”

iTerm2 和 VSCode 用户提示：在 Claude Code 中运行 /terminal-setup 自动配置 Shift+Enter 作为更直观的替代方案。

通知设置

通过正确的通知配置，永远不会错过 Claude 完成任务的时机：

终端铃声通知

启用任务完成时的声音提醒：

claude config set --global preferredNotifChannel terminal_bell

对于 macOS 用户：不要忘记在系统设置 → 通知 → [您的终端应用] 中启用通知权限。

iTerm 2 系统通知

对于任务完成时的 iTerm 2 提醒：

打开 iTerm 2 首选项
导航到配置文件 → 终端
启用”静音铃声”和过滤提醒 → “发送转义序列生成的提醒”
设置您首选的通知延迟

请注意，这些通知是 iTerm 2 特有的，在默认的 macOS 终端中不可用。

处理大量输入

处理大量代码或长指令时：

避免直接粘贴：Claude Code 可能难以处理非常长的粘贴内容
使用基于文件的工作流：将内容写入文件并要求 Claude 读取
了解 VS Code 的限制：VS Code 终端特别容易截断长粘贴内容

Vim 模式

Claude Code 支持一部分 Vim 键绑定，可以通过 /vim 启用或通过 /config 配置。

支持的子集包括：

模式切换：Esc（到 NORMAL），i/I，a/A，o/O（到 INSERT）
导航：h/j/k/l，w/e/b，0/$/^，gg/G
编辑：x，dw/de/db/dd/D，cw/ce/cb/cc/C，.（重复）

环境变量

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

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

变量	用途
`ANTHROPIC_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_CODE_API_KEY_HELPER_TTL_MS`	应刷新凭据的间隔（使用 `apiKeyHelper` 时）
`CLAUDE_CODE_USE_BEDROCK`	使用 Bedrock（参见 Bedrock 和 Vertex）
`CLAUDE_CODE_USE_VERTEX`	使用 Vertex（参见 Bedrock 和 Vertex）
`CLAUDE_CODE_SKIP_VERTEX_AUTH`	跳过 Vertex 的 Google 认证（例如，当使用代理时）
`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_TELEMETRY`	设置为 `1` 以选择退出 Statsig 遥测（注意，Statsig 事件不包括用户数据，如代码、文件路径或 bash 命令）
`HTTP_PROXY`	指定网络连接的 HTTP 代理服务器
`HTTPS_PROXY`	指定网络连接的 HTTPS 代理服务器
`MAX_THINKING_TOKENS`	强制为模型预算设置思考
`MCP_TIMEOUT`	MCP 服务器启动的超时时间（毫秒）
`MCP_TOOL_TIMEOUT`	MCP 工具执行的超时时间（毫秒）

配置选项

我们正在将全局配置迁移到 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>：

键	描述	示例
`autoUpdaterStatus`	启用或禁用自动更新器（默认：`enabled`）	`disabled`
`preferredNotifChannel`	您希望接收通知的位置（默认：`iterm2`）	`iterm2`、`iterm2_with_bell`、`terminal_bell` 或 `notifications_disabled`
`theme`	颜色主题	`dark`、`light`、`light-daltonized` 或 `dark-daltonized`
`verbose`	是否显示完整的 bash 和命令输出（默认：`false`）	`true`

Claude 代码

​设置文件

​可用设置

​设置优先级

​权限

​特定工具的权限规则

​Bash

​Read 和 Edit

​WebFetch

​MCP

​自动更新器权限选项

​推荐：创建新的用户可写 npm 前缀

​禁用自动更新器

​优化您的终端设置

​主题和外观

​换行符

​通知设置

​终端铃声通知

​iTerm 2 系统通知

​处理大量输入

​Vim 模式

​环境变量

​配置选项

​全局配置

设置文件

可用设置

设置优先级

权限

特定工具的权限规则

Bash

Read 和 Edit

WebFetch

MCP

自动更新器权限选项

推荐：创建新的用户可写 npm 前缀

禁用自动更新器

优化您的终端设置

主题和外观

换行符

通知设置

终端铃声通知

iTerm 2 系统通知

处理大量输入

Vim 模式

环境变量

配置选项

全局配置