Deepseek ArtifactsDeepseek Artifacts
配置指南

Claude Code 设置详解：settings.json 字段指南

settings.json 里所有值得关心的键：四层配置文件与优先级、model 与 effort、permissions 的 allow/deny 规则、env 块，以及一套真实的 settings.local.json 清理流程——全部对照官方文档核实。

开始图文教程看常见问题

一分钟看懂

  • 四个文件一条优先级链：managed-settings.json 压过命令行，命令行压过 .claude/settings.local.json，再压过 .claude/settings.json，最后是 ~/.claude/settings.json。allow 列表跨文件是合并而非覆盖。
  • settings.json 是严格 JSON：不能写注释，不能有末尾逗号。加上 "$schema": "https://json.schemastore.org/claude-code-settings.json" 这一行，编辑器就能自动补全每个键。
  • deny 永远赢。任何一层里的 deny 规则都能压过所有 allow 规则——先写上 Read(./.env) 和 Bash(git push:*)，两行就护住了密钥和远端仓库。
  • settings.local.json 是你这台机器的私人沙盒：优先于共享的项目设置，还会被自动加进 gitignore，个人路径和实验配置不会漏进仓库。

Claude Code Configuration EP1: The Global Files Decoded (settings.json, CLAUDE.md, skills)

频道：Terminode AI2:31

看视频

Learning In Public: Cleaning Up Claude Code Settings

频道：Ben Nadel5:26

看视频

Settings — official documentation

官方文档：code.claude.com/docs

看视频

Settings reference — the full key table

官方文档：code.claude.com/docs

看视频

Environment variables — official reference

官方文档：code.claude.com/docs

看视频

本页事实均已对照官方设置文档核实；上面两支视频是画面素材来源，也是这套审计流程的灵感出处。

截图版权归各自创作者所有，并深链到对应时间点；未使用任何人脸镜头。

一步步配好 Claude Code 的 settings.json

第 1 部分 — 摸清配置版图

  1. 1

    认清四个设置文件

    Claude Code 从四个作用域读配置：~/.claude/settings.json（你自己，所有项目通用）、.claude/settings.json（团队共享，随仓库提交）、.claude/settings.local.json（你自己，仅限本项目）和 managed-settings.json（你的组织）。~/.claude 里的一切——CLAUDE.md、projects、skills、agents、plugins——都属于同一张地图。

    Claude Code global config map card listing settings.json, CLAUDE.md, projects, skills, agents, plugins and the .claude.json state file inside the ~/.claude directory
    全局层一览：会话启动时 Claude Code 会从 ~/.claude 读取的每一个文件。跳到 2:28 观看
  2. 2

    打开或创建 ~/.claude/settings.json

    Mac 和 Linux 上文件位于 ~/.claude/settings.json；Windows 上是 %USERPROFILE%\.claude\settings.json。不存在就新建——下个会话 Claude Code 就会读它。想把整个配置目录挪到别处，设置 CLAUDE_CONFIG_DIR 即可。

    Claude Code settings.json card showing the ~/.claude/settings.json path on Mac and Linux and the Windows USERPROFILE location for themes, model choice and permissions
    settings.json 管着你机器上所有项目的主题、模型选择、插件、环境变量和权限。跳到 0:20 观看
  3. 3

    固定模型和 effort 级别

    把 "model" 设为具体模型或 "opusplan"（Opus 负责规划、Sonnet 负责执行），它就成了每个新会话的默认值——和 /model 交互式切换是同一个选择。再配 "effortLevel" 给默认思考深度封顶，模型级别的覆写交给 modelSettings。

  4. 4

    放行你信任的命令

    在 permissions 块里，"allow" 列出跳过审批弹窗的工具规则："Bash(npm run lint)"、"Bash(npm run test *)"、"Read(~/.zshrc)"。规则是按工具划定作用域的模式——* 通配符前面要留一个空格（"Bash(git push:*)"），否则会误吞更长的命令名。

    Claude Code settings.local.json permissions allow list open in VS Code showing Bash git commands and WebFetch domain allow entries
    一份真实的 settings.local.json allow 列表：这里的每一条都对应一个再也不会出现的审批弹窗。跳到 0:50 观看

第 2 部分 — 权限、env 与覆盖

  1. 5

    用 deny 规则守住密钥

    deny 规则最先求值，任何层级的配置都翻不了它。先写 "Read(./.env)" 和 "Read(./.env.*)"，让 API 密钥永远进不了上下文；再写 "Bash(git push:*)"，把发布到远端的决定留给人类。灰色地带交给 ask 规则。

  2. 6

    机器本地的覆写放 settings.local.json

    Claude Code 替你记录的权限会落进 .claude/settings.local.json——而且这个文件会被自动加进 gitignore。个人路径、实验性开关、不想强加给同事的东西都放这里。要共享的、深思熟虑的规则才进 .claude/settings.json。

  3. 7

    密钥和开关写进 env 块

    "env" 对象会给每个会话注入环境变量："ANTHROPIC_API_KEY"、"DISABLE_TELEMETRY": "1"、"DISABLE_NON_ESSENTIAL_MODEL_CALLS": "1"、CLAUDE_CODE_MAX_OUTPUT_TOKENS 之类。官方文档给出的经验法则：settings.json 里的全大写键几乎都属于 env。

  4. 8

    别把 ~/.claude.json 当成设置

    ~/.claude.json 是状态，不是配置：OAuth 令牌、MCP 服务器注册、逐项目的信任决定、全局开关都住在里面。意图写进 settings.json；.claude.json 让 Claude Code 自己管——两个都记得备份，因为 cleanupPeriodDays 也管着会话记录的保存期限。

    Terminal listing of the ~/.claude folder in Claude Code showing statsig feature flags, the plugins directory, shell snapshots and the .claude.json global state file
    ~/.claude 里面：功能开关、插件、shell 快照，还有那个容易被误认成配置文件的 .claude.json 状态文件。跳到 2:00 观看

第 3 部分 — 长期保持干净

  1. 9

    看看 ~/.claude 里还住着谁

    CLAUDE.md 是你的全局指令文件，每个会话开头都会读。projects/ 存每个仓库的会话历史和自动记忆，skills/ 放按需加载的 SKILL.md 工作流，agents/ 定义子智能体，plugins/ 记录已安装插件，statsig/ 缓存功能开关。settings.json 统领这一切。

    Claude Code CLAUDE.md global instruction file card with personal preferences, code style rules and testing patterns loaded at the start of every session
    CLAUDE.md 就是那个常被误认成设置的邻居：它装的是偏好和约定，不是配置键。跳到 0:45 观看
  2. 10

    让 Claude 审计你的 allow 列表

    allow 列表一次弹窗长一条，长到没人记得里面有什么。打开 Claude Code，请它检查 .claude/settings.local.json 里的冗余、不必要和危险条目——Claude 知道自己内置了哪些工具，也知道哪些规则互相重叠。

    Claude Code prompt asking Claude to review the permissions allow list in settings.local.json for redundant and overly permissive entries
    审计提示词：让 Claude 复查 allow 列表，标出冗余项、与内置工具重复的项，以及明显危险的项。跳到 1:40 观看
  3. 11

    像评审一样读审计结论

    在本页截图的这次真实审计里，Claude 把 41 条记录分了类：ls、grep、find、echo、cd 与内置工具重复；带通配符的条目已经覆盖了那些显式命令；本地绝对路径没必要——Claude 知道自己的工作目录；只有 curl 被认定为真的权限过宽。

    Claude Code analysis table flagging unnecessary Bash ls, grep and find permission entries that duplicate built-in tools in settings.local.json
    审计结论：41 条被归入不必要、冗余、危险三类——每条都给了替换建议。跳到 3:05 观看
  4. 12

    应用清理结果，每月复查

    批准建议的修改，文件就从 41 条缩到 15 条。把它变成习惯：读不下去的 allow 列表就是看不见的攻击面。大项目结束后重跑一次审计；能用 Bash(git diff:*) 这种限定范围的规则，就别用一揽子放行。

    Claude Code summary of permission changes removing curl, explicit home directory paths and one-off shell script entries from the settings allow list
    应用后的清理：curl、显式的家目录路径、一次性 shell 脚本都从 allow 列表里移除了。跳到 4:50 观看

settings.json vs CLAUDE.md vs ~/.claude.json vs /config

四个地方都长着「Claude Code 设置」的脸——但它们不能互换。谁管什么：

  • 1settings.json（所有层级）——声明式配置：model、effort、permissions、env、hooks、statusLine、plugins。严格 JSON、有 schema 校验、可以提交（.local 那份除外）。
  • 2CLAUDE.md——自然语言指令和约定。它塑造行为而非配置；没有键值契约，每个会话都会读。
  • 3~/.claude.json——机器状态：OAuth/会话数据、MCP 注册、逐项目信任、引导开关。它由 Claude Code 写入，别手动编辑。
  • 4/config——交互面板。同一批键的 UI 外壳：大多数开关写进 ~/.claude/settings.json，少数（如 Show tips）写进 settings.local.json，全局选项落进 ~/.claude.json。
  • 5managed-settings.json——组织层。它压过一切（少数安全例外取更严的值），所以你在工作电脑上的本地模型选择可能悄悄失效。

经验法则：行为写 CLAUDE.md，配置写 settings.json；如果某个值好像不生效，先查 ~/.claude.json 或托管文件是不是已经替你做了决定。

设置不生效？急救五步

settings.json 的问题基本都能归结为五种原因。按顺序排查：

  • 1JSON 语法错误。settings.json 是严格 JSON——一个末尾逗号或一行 // 注释就会让整个文件被拒。贴进校验器检查，或者加 $schema 行让编辑器边打字边报错。
  • 2上面有更严的规则。托管设置和安全敏感键（如 disableClaudeAiConnectors、useAutoModeDuringPlan）永远压过你的文件。看看是不是公司电脑在覆盖你。
  • 3文件错了，作用域错了。.claude/settings.json 里的规则只在该项目内生效；按设计，defaultMode 的 auto 和 bypassPermissions 写在项目级文件里会被忽略。
  • 4env 值放错了位置。全大写键属于 env 块，不是顶层。如果 ANTHROPIC_API_KEY 或 DISABLE_TELEMETRY 像是被无视了，多半是放在高一层了。
  • 5被静默拒绝的条目。跑一下 claude doctor 列出未通过校验的设置条目；会话里用 /status 看哪些文件真的被加载了。

还不行？删掉最近一次改动，用 /status 确认文件已加载，再一个键一个键地加回来——二分排查比干瞪眼快。

Claude Code 设置常见问题

相关攻略

Claude Code 键位与 vim 模式Claude Code statusline 教程Claude Code permissions 权限配置指南Claude Code Hooks 攻略Claude Code Auto CompactClaude Code 用量限额详解