14. 设置文件与配置

本节目标：搞懂 Claude Code 的配置体系—四级作用域怎么排优先级、settings.json 长什么样、哪些配置项最常用，以及终端那些小毛病（Shift+Enter 不换行、没声音、tmux 里跑乱码）怎么治。

配置的四个作用域

Claude Code 的配置不是「一个文件搞定一切」，而是分了四个作用域（Scope）。新手最容易踩的坑就是改了用户配置发现没生效—因为项目配置把它覆盖了。

先看一张总表：

作用域	位置	影响范围	跟团队共享？
Managed（企业级）	服务器下发 / 系统目录 / 注册表	整个组织的成员	是（IT 部署）
User（用户级）	`~/.claude/`	你自己，跨所有项目	否
Project（项目级）	仓库里的 `.claude/`	这个仓库的所有协作者	是（提交到 git）
Local（本地级）	`.claude/settings.local.json`	你自己，仅在这个仓库	否（gitignored）

打个比方。Managed 像公司发的员工手册，谁都不能改；User 像你的个人笔记本，到哪儿都带着；Project 像项目 README，团队共用；Local 像你抽屉里的便签，只在这个工位、只给你自己看。

Note

Windows 上 ~/.claude 实际解析为 %USERPROFILE%\.claude。

优先级谁压谁

四个作用域同时存在时，优先级从高到低是这样：

Managed（最高）—谁也覆盖不了
命令行参数—临时覆盖一次会话
Local—压过 Project 和 User
Project—压过 User
User（最低）—没人指定时才用

举个例子：你在 User 里把 permissions.defaultMode 设成 acceptEdits，但项目的 .claude/settings.json 里设成了 default，最终生效的是 default—项目压过用户。

Warning

数组类型的设置特殊：像 permissions.allow、sandbox.filesystem.allowWrite 这类数组配置，跨作用域是拼接去重而不是覆盖。比如 Managed 设了 ["/opt/company-tools"]，你在 User 里加 ["~/.kube"]，最终两个路径都在。这样低优先级也能往上加条目，不会被冲掉。

settings.json 长什么样

settings.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(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  }
}

第一行 $schema 是给编辑器用的—加上它，VS Code、Cursor 这类支持 JSON Schema 的编辑器就能给你自动补全和校验。强烈建议加上。

三个文件分别放什么

同一个项目里，你可能同时有三个配置文件，分工要清楚：

文件	放什么
`~/.claude/settings.json`	你个人的全局偏好：主题、编辑器模式、跨项目通用的工具和插件
`.claude/settings.json`	团队共享：权限规则、钩子（Hook）、MCP 服务器、团队都要装的插件。提交到 git
`.claude/settings.local.json`	你在这个项目里的私人覆盖：试验性配置、机器相关的路径。自动 gitignore

Tip

Claude Code 自动创建 .claude/settings.local.json 时会顺手把它加进 gitignore。但如果你自己手动建的这个文件，记得手动加忽略，别把个人配置提交上去。

常用配置项速查

settings.json 支持的键非常多，下面挑最常用的几个讲。完整的键值表在官方文档 settings.md 里，跑 /config 也能在交互界面里改。

权限配置

最常配的一块。permissions 对象里有三个数组：

allow：自动放行的操作
ask：每次问一下
deny：直接拒绝

{
  "permissions": {
    "allow": ["Bash(npm run test *)"],
    "deny": ["Bash(rm -rf *)", "Read(./.env)"]
  }
}

权限规则语法、默认模式、自动模式这些细节，第 17 章专门讲。

环境变量

env 对象里塞环境变量，效果跟在 shell 里 export 一样，但只对 Claude Code 生效：

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "MAX_THINKING_TOKENS": "8000"
  }
}

好处是跨项目复用、跟着 git 走。第 16 章细讲环境变量。

模型与上下文

键	作用	示例
`model`	默认用什么模型	`"opus"`
`availableModels`	限制能选哪些模型	`["sonnet", "haiku"]`
`alwaysThinkingEnabled`	默认开扩展思考	`true`
`autoCompactEnabled`	上下文快满时自动压缩	`true`（默认）
`cleanupPeriodDays`	会话记录保留几天	`30`（默认）

模型配置细节看第 15 章。

编辑器与界面

键	作用	示例
`editorMode`	编辑器模式，`"vim"` 或 `"normal"`	`"vim"`
`preferredNotifChannel`	通知方式，`"terminal_bell"` 或 `"iterm2"` 等	`"terminal_bell"`
`autoUpdatesChannel`	更新渠道，`"stable"` 或 `"latest"`	`"stable"`
`autoScrollEnabled`	全屏模式自动滚动到底部	`true`（默认）

归属（Attribution）

自定义 git 提交和 PR 的署名：

{
  "attribution": {
    "commit": "Generated with Claude Code",
    "pr": ""
  }
}

pr 设空字符串就不在 PR 里加署名。

改了配置什么时候生效

好消息：Claude Code 会监视你的设置文件，改了就自动重新加载，不用重启。permissions、hooks、apiKeyHelper 这些改完立刻生效。

少数几个键例外，得重启或者 /clear 才行：

model：会话中用 /model 切换，重启后才读新默认值
outputStyle：系统提示的一部分，/clear 或重启时重建

Tip

想看当前会话到底加载了哪些配置层，跑 /status，看 Setting sources 那一行。会列出 User settings、Project local settings 之类，Managed 生效时还会标来源（(remote)、(plist)、(file) 等）。

用 /config 可视化改配置

不想手撕 JSON？跑 /config 打开交互式设置界面，能可视化改大部分常用项。

从 v2.1.181 起，还能直接传键值对单改一项，不打开界面：

/config verbose=true

终端配置：治那些小毛病

上面讲的都是 Claude Code 自己的行为配置。下面这部分是终端层面的配置—当 Claude Code 在你终端里表现怪异时，问题往往不在 settings.json，而在终端设置。官方专门有个 terminal-config 页面治这些毛病。

Shift+Enter 不换行

按 Enter 提交、想换行不提交，通用解法是 Ctrl+J，或者输 \ 再按 Enter。这俩在所有终端都管用。

Shift+Enter 换行看终端：

终端	Shift+Enter 换行
Ghostty、Kitty、iTerm2、WezTerm、Warp、Apple Terminal、Windows Terminal	直接可用
VS Code、Cursor、Alacritty、Zed	跑一次 `/terminal-setup`
gnome-terminal、JetBrains IDE	不可用，用 `Ctrl+J`

/terminal-setup 会把 Shift+Enter 等快捷键写进终端配置文件。要在主机终端里跑，别在 tmux 或 screen 里跑。

完成时没声音/通知

Claude 完成任务或要权限时会触发通知事件。默认只在 Ghostty、Kitty、iTerm2 里发桌面通知。别的终端想响铃，加配置：

{
  "preferredNotifChannel": "terminal_bell"
}

想自定义声音，用通知钩子（Hook）：

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          { "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff" }
        ]
      }
    ]
  }
}

这是 macOS 播系统声音的例子，Linux 和 Windows 的命令在钩子指南里有。

tmux 里的坑

在 tmux 里跑 Claude Code，默认两件事会坏：Shift+Enter 不换行、桌面通知和进度条到不了外层终端。把下面三行加进 ~/.tmux.conf：

set -g allow-passthrough on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'

改完跑 tmux source-file ~/.tmux.conf 让它生效。allow-passthrough 让通知穿出去，extended-keys 让 tmux 分清 Shift+Enter 和 Enter。

闪烁或滚动条乱跳

显示闪烁，跑 /tui fullscreen 切到全屏渲染模式。全屏模式画在终端为全屏应用保留的独立屏幕上，不挂在你的滚动条后面，内存也平稳。

只想消闪烁不改渲染器，设环境变量：

CLAUDE_CODE_NO_FLICKER=1 claude

Vim 模式

Claude Code 自带提示符输入的 Vim 模式。开它两种方式：

/config 里找「编辑器模式」选 Vim
直接在 ~/.claude/settings.json 里写：

{
  "editorMode": "vim"
}

支持 hjkl 导航、v/V 选择、d/c/y 配文本对象等子集。注意：INSERT 模式下按 Enter 还是会提交，跟标准 Vim 不一样—想插换行用 NORMAL 模式的 o/O 或 Ctrl+J。

Warning

Vim 动作不能通过快捷键文件重映射。想映射 INSERT 模式的两键序列（比如 jj 当 Escape），用 vimInsertModeRemaps 设置。

颜色主题

跑 /theme 选主题。有内置预设（dark、light、daltonized 色盲友好版、ansi 版），选「自动」会跟随终端深浅色。

从 v2.1.118 起支持自定义主题。每个主题是 ~/.claude/themes/ 里的一个 JSON 文件，结构简单：

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555",
    "success": "#50fa7b"
  }
}

base 选个内置预设打底，overrides 里只覆盖你想改的颜色令牌。Claude Code 会监视这个目录，文件一改立即生效，不用重启。

小结

记住这几条就够用了：

四个作用域：Managed > 命令行 > Local > Project > User，数组类配置是拼接而不是覆盖
三个文件：~/.claude/settings.json（全局）、.claude/settings.json（团队共享）、.claude/settings.local.json（本地私人）
改了就生效，少数几个键（model、outputStyle）要重启或 /clear
/status 看加载了哪些层，/config 可视化改配置，/doctor 查配置错误
终端毛病用 terminal-config 那套治：Ctrl+J 换行、preferredNotifChannel 响铃、tmux 加三行配置、Vim 模式用 editorMode

下一章讲模型配置—Opus 5、Sonnet 怎么选、/model 怎么切、推理强度怎么调。