古法编程

Appearance

Claude Code v2.1.114 提供 60+ 配置项和 175+ 环境变量，通过 settings.json 统一管理。配置分 5 个优先级层——从不可覆盖的 managed settings 到个人 ~/.claude/settings.json。理解层级体系、permission 规则语法和 env 键的用法，是高效配置 Claude Code 的基础。

Claude Code Settings 完整配置参考：从 UI 到 settings.json 全字段解析 ​

配置层级体系 ​

Settings 按以下优先级从高到低应用，高优先级覆盖低优先级：

优先级位置作用域是否共享用途
1Managed settings组织是（IT 部署）不可覆盖的安全策略
2命令行参数会话N/A临时单次覆盖
3.claude/settings.local.json项目否（git-ignored）个人项目配置
4.claude/settings.json项目是（已提交）团队共享设置
5~/.claude/settings.json用户N/A全局个人默认值

关键规则：

  • deny 规则拥有最高安全优先级，不可被低优先级 allow/ask 规则覆盖
  • 数组类设置（如 permissions.allow）跨层级合并去重，而非替换
  • Managed settings 通过服务端推送、MDM、注册表或文件等方式部署，可锁定本地配置

核心配置项 ​

通用设置 ​

json
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "sonnet",
  "language": "english",
  "cleanupPeriodDays": 30,
  "autoUpdatesChannel": "stable",
  "alwaysThinkingEnabled": true,
  "showThinkingSummaries": true,
  "viewMode": "default",
  "tui": "fullscreen",
  "defaultShell": "bash",
  "includeGitInstructions": true
}
配置项类型说明
modelstring默认模型，支持别名（sonnet/opus/haiku）或完整 ID
agentstring主会话默认 agent，对应 .claude/agents/ 中的名称
languagestringClaude 响应语言，同时设置语音输入语言
cleanupPeriodDaysnumber不活跃 session 的自动清理天数（最小 1）
autoUpdatesChannelstring更新通道："stable" 或 "latest"
alwaysThinkingEnabledboolean默认开启扩展思考模式
showThinkingSummariesboolean在交互式会话中显示思考摘要
tuistring渲染模式："fullscreen"（无闪烁全屏）或 "default"
defaultShellstring! 命令默认 shell："bash" 或 "powershell"
includeGitInstructionsboolean在系统提示中包含 git 操作指引
availableModelsarray限制 /model 命令可选的模型列表

努力级别（Effort Level） ​

等级说明
max最大推理深度（仅 Opus 4.6）
xhigh扩展高推理（仅 Opus 4.7）
high完整推理深度，复杂任务首选
medium均衡推理，日常任务
low最小推理，响应最快
json
{ "effortLevel": "high" }

通过 /effort low|medium|high|xhigh 命令直接设置，自动写入 settings.json。

模型别名 ​

别名说明
"sonnet"最新 Sonnet 模型
"opus"最新 Opus 模型
"haiku"快速 Haiku 模型
"sonnet[1m]"Sonnet + 1M 上下文
"opus[1m]"Opus + 1M 上下文（Max/Team/Enterprise 默认）
"opusplan"Opus 规划 + Sonnet 执行

Permissions 权限配置 ​

权限配置是 settings.json 最核心的部分，控制 Claude 可以执行的操作。

结构 ​

json
{
  "permissions": {
    "allow": [],
    "ask": [],
    "deny": [],
    "additionalDirectories": [],
    "defaultMode": "acceptEdits"
  }
}

评估顺序：deny 优先 → ask → allow，第一条匹配规则生效。

工具权限语法 ​

工具语法示例
BashBash(命令模式)Bash(npm run *), Bash(git *)
ReadRead(路径模式)Read(.env), Read(./secrets/**)
EditEdit(路径模式)Edit(src/**), Edit(*.ts)
WriteWrite(路径模式)Write(*.md)
WebFetchWebFetch(domain:模式)WebFetch(domain:example.com)
TaskTask(agent名称)Task(Explore)
MCPmcp__server__toolmcp__memory__*
SkillSkill(skill名称)Skill(weather-fetcher)

路径前缀说明：

前缀含义示例
//文件系统绝对路径Read(//Users/alice/file)
~/相对 home 目录Read(~/.zshrc)
/相对项目根目录Edit(/src/**)
./ 或无相对路径Read(.env)

Bash 通配符规则：

  • Bash(*) 等同于 Bash（匹配所有命令）
  • Bash(ls *) 匹配 ls -la 但不匹配 lsof（有空格则为词边界）
  • Bash(ls*) 无空格时匹配 lsof

权限模式 ​

模式行为
"default"标准权限检查，有提示
"acceptEdits"自动接受文件编辑，无需确认
"dontAsk"自动拒绝工具，除非通过 allow 预批准
"bypassPermissions"跳过所有权限检查（危险）
"auto"后台分类器替代手动提示（研究预览）
"plan"只读探索模式

实用权限示例 ​

json
{
  "permissions": {
    "allow": [
      "Edit(*)",
      "Write(*)",
      "Bash(npm run *)",
      "Bash(git *)",
      "WebFetch(domain:*)",
      "mcp__*",
      "Agent(*)"
    ],
    "ask": [
      "Bash(rm *)",
      "Bash(git push *)"
    ],
    "deny": [
      "Read(.env)",
      "Read(./secrets/**)",
      "Bash(curl *)"
    ],
    "additionalDirectories": ["../shared-libs/"],
    "defaultMode": "acceptEdits"
  }
}

env 键：环境变量配置 ​

env 键是替代 wrapper 脚本的最佳方式，直接在 settings.json 中为所有 Claude Code 会话注入环境变量：

json
{
  "env": {
    "NODE_ENV": "development",
    "CLAUDE_CODE_EFFORT_LEVEL": "medium",
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "MAX_THINKING_TOKENS": "10000",
    "ANTHROPIC_MODEL": "sonnet"
  }
}

高频实用环境变量 ​

变量说明
ANTHROPIC_MODEL覆盖模型，优先于 model 设置
CLAUDE_CODE_SUBAGENT_MODEL子代理专用模型（如 haiku 节省费用）
MAX_THINKING_TOKENS单次响应最大思考 token 数
CLAUDE_CODE_EFFORT_LEVEL努力等级：low/medium/high/xhigh/max
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE自动压缩触发阈值（1-100，默认 95%）
BASH_MAX_TIMEOUT_MSBash 命令超时时间
BASH_MAX_OUTPUT_LENGTHBash 命令最大输出长度
DISABLE_AUTO_COMPACT禁用自动上下文压缩（1 禁用）
CLAUDE_CODE_DISABLE_AUTO_MEMORY禁用自动记忆（1 禁用）
HTTP_PROXY / HTTPS_PROXY代理服务器配置
MCP_TIMEOUTMCP 服务器启动超时（ms）

Sandbox 沙箱配置 ​

在受限环境中运行 Bash 命令：

json
{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker", "gh"],
    "allowUnsandboxedCommands": false,
    "network": {
      "allowLocalBinding": true,
      "allowedDomains": ["*.github.com", "registry.npmjs.org"]
    },
    "filesystem": {
      "denyRead": ["./secrets/"],
      "denyWrite": ["./.env"]
    }
  }
}
配置项说明
sandbox.enabled开启沙箱
sandbox.excludedCommands在沙箱外运行的命令白名单
sandbox.allowUnsandboxedCommands是否允许 dangerouslyDisableSandbox 逃逸
sandbox.network.allowedDomains沙箱内可访问的域名白名单
sandbox.filesystem.denyWrite禁止写入的路径

Status Line 自定义状态栏 ​

json
{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "refreshInterval": 5
  }
}

状态栏脚本通过 stdin 接收 JSON 数据，可读取以下字段：

字段说明
model.display_name当前模型名
cost.total_cost_usd会话累计费用
context_window.used_percentage上下文窗口使用率
rate_limits.five_hour.used_percentage5小时速率限制使用率
session_name当前会话名称
worktree.branchworktree 分支名

Worktree 与归因设置 ​

json
{
  "worktree": {
    "symlinkDirectories": ["node_modules", ".cache"],
    "sparsePaths": ["packages/my-app", "shared/utils"]
  },
  "attribution": {
    "commit": "Generated with Claude Code",
    "pr": ""
  }
}
  • worktree.symlinkDirectories：在 worktree 中符号链接的大目录，避免磁盘重复
  • worktree.sparsePaths：sparse-checkout 仅检出指定目录，加快大型 monorepo 启动
  • attribution.commit：设为空字符串 "" 完全隐藏 git commit 归因

完整配置示例 ​

json
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "sonnet",
  "language": "english",
  "alwaysThinkingEnabled": true,
  "tui": "fullscreen",
  "permissions": {
    "allow": ["Edit(*)", "Write(*)", "Bash(npm run *)", "Bash(git *)", "mcp__*"],
    "deny": ["Read(.env)", "Read(./secrets/**)"],
    "defaultMode": "acceptEdits"
  },
  "env": {
    "NODE_ENV": "development",
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku"
  },
  "statusLine": {
    "type": "command",
    "command": "git branch --show-current"
  }
}

FAQ ​

Q: settings.json 和 settings.local.json 分别放什么？ A: settings.json 提交到 git，放团队共享的配置（如项目级 permissions、env 等）；settings.local.json 加入 .gitignore，放个人偏好（如个人的 statusLine 脚本路径、本机特定路径）。

Q: permissions.allow 里的规则各层级会合并吗？ A: 是的，数组类设置（allow/ask/deny/additionalDirectories）跨所有层级合并去重，而非替换。这意味着你在 ~/.claude/settings.json 添加的全局允许规则会自动和项目级规则叠加。

Q: 怎么让 Claude Code 使用较便宜的 Haiku 模型运行子代理？ A: 在 env 键中设置 "CLAUDE_CODE_SUBAGENT_MODEL": "haiku"，主会话保持 sonnet，所有子代理自动切换为 haiku，显著降低多代理工作流的费用。

Q: deny 规则可以被 allow 覆盖吗？ A: 不能。评估顺序是 deny → ask → allow，deny 规则优先级最高，即使 allow 有更具体的匹配也无法覆盖 deny。

Q: 如何完全隐藏 Claude Code 的 git commit 归因信息？ A: 设置 "attribution": { "commit": "", "pr": "" }，空字符串会完全移除归因文字。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 地豆 蜀ICP备2021007188号 | 关于本站 | 隐私政策