Claude Code 的配置分散在好几个文件里，这是很多人觉得混乱的根源。先来看一张全景图：
用户级别（全局生效）：~/.claude/settings.json，你个人的默认配置，对所有项目生效。
项目级别（团队共享）：.claude/settings.json，放在项目根目录下，可以提交到 Git，让团队所有人共用一套配置。
本地覆盖（个人微调）：.claude/settings.local.json，同样在项目的 .claude/ 目录下，但 Claude Code 会自动把它加到 .gitignore 里，所以不会被提交。适合放 API Key 之类的个人配置。
MCP 服务器配置：这里有两个位置需要注意。全局的 MCP 配置放在 ~/.claude.json（注意，是 ~/.claude.json，不在 ~/.claude/ 目录里面，这是一个非常容易搞混的地方）。项目级别的 MCP 配置放在项目根目录的 .mcp.json 文件里。
托管配置（企业管控）：managed-settings.json 和 managed-mcp.json，由组织的 IT 管理员通过 Anthropic 管理后台或系统目录部署，优先级最高，用户无法覆盖。
这些配置文件的优先级从高到低是这样的：
托管配置 > 命令行参数 > 本地项目配置 > 项目配置 > 用户配置
也就是说，如果你在用户配置里允许了某个命令，但项目配置里禁止了，那就以项目配置为准，命令会被拒绝。而如果你在本地配置里又打开了它，因为本地优先级高于项目，那它又能用了。
这套优先级机制的设计意图很明确：团队的安全策略可以覆盖个人偏好，但你在自己的机器上仍然有微调的空间。
settings.json 能配什么？
一个典型的 settings.json 长这样：
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": [
"Bash(npm run lint)",
"Bash(npm run test *)",
"Bash(git *)",
"Read(~/.zshrc)"
],
"deny": [
"Bash(curl *)",
"Bash(rm -rf *)",
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)"
],
"defaultMode": "acceptEdits"
},
"env": {
"CLAUDE_CODE_ENABLE_TELEMETRY": "1"
},
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "case \"$CLAUDE_FILE_PATH\" in *.py) black \"$CLAUDE_FILE_PATH\" ;; esac",
"timeout": 30
}
]
}
]
}
}
第一行的 $schema 指向 Claude Code 官方的 JSON Schema，加上它之后，VS Code、Cursor 这类编辑器会自动提供补全和校验，少打很多错别字。
下面逐个模块来看。
权限控制：allow、deny 和 ask
权限配置是 settings.json 最核心的部分。规则的格式是 工具名(匹配模式)，支持通配符。
allow 列表里的操作会自动通过，不再弹窗询问。deny 列表里的操作会被拒绝。你还可以用 ask 列表来明确标记”每次都要问我”的操作。
三者的评估顺序是：先检查 deny，再检查 ask，最后检查 allow。第一个匹配到的规则生效。所以 deny 永远优先。
常见的工具名包括：Bash（执行 shell 命令）、Read（读取文件）、Edit（编辑文件）、Write（写入文件）、WebFetch（网络请求），以及 MCP 相关的工具。
举几个实用的配置例子：
"allow": [
"Bash(cat:*)",
"Bash(ls:*)",
"Bash(git:*)",
"Bash(npm run lint)",
"Bash(npm run test *)",
"Bash(python:*)",
"Bash(php:*)"
],
"deny": [
"Bash(rm -rf *)",
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)"
]
这组配置允许 Claude 自由地执行常见的读取、Git、测试和 lint 命令，但禁止它碰环境变量文件和执行危险的删除操作。
不过有一点要特别注意——社区里有不少开发者反馈过 deny 规则有时候不生效的问题。deny 规则只能阻止 Claude 通过内置工具（比如 Read 和 Edit）访问文件，但如果 Claude 用 Bash 执行了 cat .env，deny 规则是拦不住的。想要更可靠的安全保障，需要配合沙箱功能（sandbox）或者通过 hooks 来做运行时拦截。
权限模式：五档可调
除了细粒度的 allow/deny 规则，Claude Code 还提供了五种权限模式，可以在 settings.json 里通过 defaultMode 设置默认值，也可以在会话中按 Shift+Tab 临时切换。
default：默认模式。每种工具第一次使用时会询问你，同意后该会话内同类操作不再打扰。
acceptEdits：自动接受所有文件编辑，但 shell 命令仍然会逐个询问。适合你信任 Claude 的代码能力、但对系统操作还想保留控制的场景。
plan：计划模式。Claude 可以分析文件，但不能修改文件或执行命令。适合在动手之前先让它出个方案。
bypassPermissions：跳过所有权限检查，所有操作直接执行。等价于命令行的 --dangerously-skip-permissions 参数。
还有一个 dontAsk 模式（目前仅在 TypeScript SDK 中可用）：不在白名单里的工具直接拒绝，不会弹窗。适合完全锁定的自动化场景。
在 settings.json 里设置默认模式很简单：
{
"permissions": {
"defaultMode": "acceptEdits"
}
}
完全跳过授权：–dangerously-skip-permissions
这个 flag 的名字起得非常直白——Anthropic 故意让它又长又吓人，逼你在输入的时候做一个有意识的决定。没有简写，没有 -y 的快捷方式。
启用后，Claude Code 进入所谓的”YOLO 模式”：所有工具直接执行，不弹任何确认框，直到任务完成为止。
# 命令行方式
claude --dangerously-skip-permissions "Fix all lint errors"
# 或者用 permission-mode 参数，效果一样
claude --permission-mode bypassPermissions "Fix all lint errors"
你也可以在配置文件里永久启用它（虽然不建议）：
{
"permissions": {
"defaultMode": "bypassPermissions"
}
}
这个模式有一个重要特性：子代理继承。当你启用 bypass 模式后，Claude 启动的所有子代理也会继承完全自主的权限，你无法单独覆盖。这意味着如果 Claude 决定拆分任务给子代理，那些子代理也能不受限制地执行任何操作。
社区里出过一些著名的事故。有个叫 Mike Wolak 的开发者在 Ubuntu/WSL2 上用 bypass 模式做固件项目时，Claude 执行了一个从根目录开始的 rm -rf，试图删除整台机器上的所有文件。万幸 Linux 的权限系统拦住了大部分系统文件，但开发环境还是被毁了。
所以社区的共识很明确：如果你要用这个 flag，务必在隔离环境里用——Docker 容器、虚拟机，或者至少是一个你不在乎的一次性环境。
一个更安全的替代方案是用细粒度的 allow 规则来达到类似效果：
{
"permissions": {
"allow": [
"Bash(git:*)",
"Bash(npm:*)",
"Bash(node:*)",
"Bash(cat:*)",
"Bash(ls:*)",
"Bash(find:*)",
"Bash(grep:*)",
"Bash(echo:*)",
"Bash(mkdir:*)",
"Bash(python:*)",
"Read",
"Edit",
"Write"
],
"deny": [
"Bash(rm -rf *)",
"Read(./.env)",
"Read(./.env.*)"
],
"defaultMode": "acceptEdits"
}
}
这样你就能享受到几乎无打扰的开发体验，同时还保留了对危险操作的防护。
推理等级：让 Claude 想多想少由你控制
Claude Code 支持控制模型的”思考深度”。这在最新版本中通过 effort 参数实现，可以设成四个等级：low、medium、high、max。
low：速度优先，适合简单任务。Claude 可能跳过内部推理直接给答案，响应速度快，token 消耗少。
medium：性价比较高的平衡点。适合日常的编码、工具调用和代码生成任务。
high：默认值。Claude 几乎每次都会进行内部推理，适合需要仔细思考的复杂任务。
max：仅 Opus 4.6 支持。最大深度推理，适合最棘手的架构决策和复杂调试。
在 settings.json 里可以这样设置：
{
"effortLevel": "medium"
}
你也可以在会话中通过 /model 命令切换，选好模型后可以调整 effort 滑块。
除了配置文件，Claude Code 还支持”触发词”——在提示词中加入特定短语来临时调整推理深度。比如 think harder、ultrathink、think step by step 这些短语会让 Claude 投入更多 token 来深入分析问题。虽然新版本的自适应思考（adaptive thinking）已经能自动判断何时需要深入思考，但在遇到复杂问题时手动触发仍然有效。
另外还有一个环境变量 MAX_THINKING_TOKENS，可以控制 Claude 内部推理过程的最大 token 预算。默认是 31999，设成 0 可以完全关闭 extended thinking。
如果你想让 Claude 始终开启深度思考，可以在配置里加上：
{
"alwaysThinkingEnabled": true
}
MCP 服务器配置：给 Claude 装上外挂
MCP（Model Context Protocol）让你可以给 Claude Code 接入各种外部工具和服务——文件系统访问、搜索引擎、数据库、甚至自定义的 API。
MCP 的配置文件位置比较特别，前面提到过。全局配置在 ~/.claude.json，项目配置在项目根目录的 .mcp.json。两者会合并，项目级别的是补充而不是替换全局配置。
一个典型的 MCP 配置：
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/Documents"]
},
"memory": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-memory"]
},
"fetch": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-fetch"]
}
}
}
每个 MCP 服务器需要指定启动命令（command）和参数（args），有些还需要环境变量（env）来传递 API Key 之类的凭证。
配置 MCP 有两种方式。一种是用 CLI 向导：
claude mcp add filesystem npx -y @modelcontextprotocol/server-filesystem /path/to/dir
另一种是直接编辑配置文件。对于复杂的配置，直接改文件更高效——你能一次看到所有配置，方便复制备份，也更适合版本控制。
配置好之后，在 Claude Code 会话中输入 /mcp 可以查看所有 MCP 服务器的连接状态。
值得一提的是，当你配置了很多 MCP 服务器时，Claude Code 默认会启用 Tool Search 功能，只在需要的时候动态加载 MCP 工具，避免它们占满上下文窗口。如果你更喜欢预加载所有工具，可以关掉这个功能，但代价是更高的上下文消耗。
对 MCP 工具的权限控制同样遵循 allow/deny 规则。比如要自动批准某个 MCP 工具的使用：
{
"permissions": {
"allow": [
"mcp__memory",
"mcp__filesystem"
]
}
}
Hooks：在关键节点插入自定义逻辑
Hooks 允许你在 Claude Code 执行工具的前后运行自定义脚本。这是一个非常强大的机制，可以用来做代码格式化、安全拦截、日志审计等等。
支持的 hook 事件包括：
PreToolUse：工具执行之前触发。脚本可以返回退出码 2 来阻止工具执行，比 deny 规则更可靠。
PostToolUse：工具执行之后触发。适合做自动格式化、lint 检查之类的后处理。
SessionStart：会话启动时触发。可以用来设置环境变量或激活虚拟环境。
Stop：Claude 完成任务停下来时触发。很多人用它来发系统通知，提醒自己回来看结果。
Notification：Claude 发送通知时触发。
一个实际的例子——每次 Claude 编辑 Python 文件后自动用 Black 格式化：
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "case \"$CLAUDE_FILE_PATH\" in *.py) black \"$CLAUDE_FILE_PATH\" ;; esac",
"timeout": 30
}
]
}
]
}
}
再比如，用 PreToolUse hook 来可靠地阻止访问敏感文件（比 deny 规则更靠谱）：
{
"hooks": {
"PreToolUse": [
{
"matcher": "Read|Edit",
"hooks": [
{
"type": "command",
"command": "python3 ~/.claude/hooks/check_sensitive.py"
}
]
}
]
}
}
对应的 Python 脚本读取 stdin 的 JSON 输入，检查文件路径是否匹配敏感文件模式，如果匹配就以退出码 2 退出来阻止操作。
还有一个很讨喜的用法——让 Claude 完成任务时播放一个声音通知你：
{
"hooks": {
"Stop": [
{
"matcher": "*",
"hooks": [
{
"type": "command",
"command": "afplay /System/Library/Sounds/Blow.aiff"
}
]
}
]
}
}
环境变量：那些值得知道的开关
Claude Code 支持大约 70 个环境变量，大部分比较小众，但有一些在日常使用中相当有用。你可以在 settings.json 的 env 字段里设置它们，也可以在 shell 的 profile 文件里 export。
模型相关：ANTHROPIC_MODEL 可以指定默认模型。ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_HAIKU_MODEL 用来覆盖各个模型别名的实际指向，在使用自定义部署或第三方网关时特别有用。
API 相关：ANTHROPIC_BASE_URL 用来指定 API 端点，在用代理或第三方服务时需要。ANTHROPIC_AUTH_TOKEN 设置 API Key。
行为控制：CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 可以调整自动压缩上下文的触发阈值。DISABLE_NON_ESSENTIAL_MODEL_CALLS 设为 1 可以减少不必要的 API 调用。MAX_THINKING_TOKENS 控制思考预算。
在 settings.json 里配置环境变量：
{
"env": {
"ANTHROPIC_MODEL": "claude-sonnet-4-20250514",
"MAX_THINKING_TOKENS": "16000",
"DISABLE_TELEMETRY": "1"
}
}
需要注意的是，如果同一个环境变量在 shell 里已经 export 过，shell 里的值优先于 settings.json 里的值。
一些实用的配置模板
讲了这么多理论，来几个拿去就能用的完整配置。
日常开发配置（平衡效率和安全）：
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": [
"Bash(cat:*)",
"Bash(ls:*)",
"Bash(find:*)",
"Bash(grep:*)",
"Bash(git:*)",
"Bash(npm:*)",
"Bash(node:*)",
"Bash(python:*)",
"Bash(echo:*)",
"Bash(head:*)",
"Bash(tail:*)",
"Bash(wc:*)"
],
"deny": [
"Bash(rm -rf *)",
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)"
],
"defaultMode": "acceptEdits"
},
"effortLevel": "medium"
}
CI/CD 自动化配置（在容器里无人值守运行）：
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"defaultMode": "bypassPermissions"
}
}
搭配 Docker 使用：
docker run --rm -v $(pwd):/workspace -w /workspace \
your-claude-image \
claude --dangerously-skip-permissions -p "Run all tests and fix failures"
安全敏感项目配置（配合 hooks 做严格防护）：
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": [
"Bash(git status)",
"Bash(git diff *)",
"Bash(npm run test *)"
],
"deny": [
"Bash(curl *)",
"Bash(wget *)",
"Bash(rm *)",
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)",
"Read(./*.pem)",
"Read(./*.key)"
]
},
"hooks": {
"PreToolUse": [
{
"matcher": "Read|Edit",
"hooks": [
{
"type": "command",
"command": "python3 ~/.claude/hooks/check_sensitive.py"
}
]
}
]
}
}
小结
Claude Code 的配置系统确实不简单，文件分散、优先级层叠、还有些历史遗留的混乱。但一旦理解了整体架构，配置起来就很清晰了。
核心就是几件事：用 settings.json 的 allow/deny 规则控制权限，用 defaultMode 选择合适的权限模式，用 .mcp.json 或 ~/.claude.json 配置 MCP 工具，用 hooks 在关键节点做自动化处理，用 effortLevel 控制推理深度。
至于 --dangerously-skip-permissions，把它当成一把火力全开的武器——威力巨大，但只在安全的靶场里使用。日常开发中，一组精心配置的 allow 规则加上 acceptEdits 模式，就足以给你流畅的体验，同时不至于让 Claude 把你的 .env 读了或者把项目目录删了。
配置一次，省心每天。这笔投入绝对值得。
来源
- Claude Code Settings 官方文档: https://code.claude.com/docs/en/settings
- Claude Code Permissions 官方文档: https://code.claude.com/docs/en/permissions
- Claude Code Model Configuration 官方文档: https://code.claude.com/docs/en/model-config
- Effort Parameter 官方文档: https://platform.claude.com/docs/en/build-with-claude/effort
- Adaptive Thinking 官方文档: https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking
- Extended Thinking 官方文档: https://platform.claude.com/docs/en/build-with-claude/extended-thinking
- Claude Code Configuration Files 完整指南 (Inventive HQ): https://inventivehq.com/knowledge-base/claude/where-configuration-files-are-stored
- Claude Code Settings Reference (ClaudeFast): https://claudefa.st/blog/guide/settings-reference
- Claude Code Deep Thinking Techniques (ClaudeFast): https://claudefa.st/blog/guide/performance/deep-thinking-techniques
- Configuring MCP Tools in Claude Code (Scott Spence): https://scottspence.com/posts/configuring-mcp-tools-in-claude-code
- Claude Code Configuration Guide (ClaudeLog): https://claudelog.com/configuration/
- Dangerous Skip Permissions (ClaudeLog): https://claudelog.com/mechanics/dangerous-skip-permissions/
- --dangerously-skip-permissions 使用指南 (Kyle Redelinghuys): https://www.ksred.com/claude-code-dangerously-skip-permissions-when-to-use-it-and-when-you-absolutely-shouldnt/
- --dangerously-skip-permissions 深度分析 (Thomas Wiegold): https://thomas-wiegold.com/blog/claude-code-dangerously-skip-permissions/
- Claude Code Autonomous Mode 完整指南: https://pasqualepillitteri.it/en/news/141/claude-code-dangerously-skip-permissions-guide-autonomous-mode
- Trail of Bits Claude Code Config (GitHub): https://github.com/trailofbits/claude-code-config
- Claude Code for Symfony (DEV Community): https://dev.to/javiereguiluz/claude-code-for-symfony-and-php-the-setup-that-actually-works-1che
- Thinking Mode 详解 (kentgigger): https://kentgigger.com/posts/claude-code-thinking-triggers
- MCP 配置文件位置 Issue #4976: https://github.com/anthropics/claude-code/issues/4976
- deny 权限不生效 Issue #6699: https://github.com/anthropics/claude-code/issues/6699
发表回复