Claude Code 配置速查（配置类）

键位、权限规则、hooks、环境变量、MCP。

目录

• 0. 严格 JSON
• 1. 配置文件放哪
• 2. settings.json 键位
• 3. 权限规则
• 4. Hooks
• 5. 环境变量
• 6. MCP
• 7. 可复制模板

0. 严格 JSON

官方原文："Settings files are strict JSON: a // comment or a trailing comma is a syntax error, and Claude Code reports the file as a Settings Error at the next start."

• // 注释 → 报错
• 尾逗号 → 报错
• 报错后该文件被整体跳过，不是只忽略一行

所以本文档所有片段都不带注释。想在文档里保留说明，请写在 JSON 外面。

1. 配置文件放哪

企业级 managed 路径

旧的 C:\ProgramData\ClaudeCode\managed-settings.json 已不再读取。
同目录可放 managed-settings.d/*.json 分片：先合并 managed-settings.json，再按文件名字母序合并分片（用 10-、20- 前缀控制顺序）。
托管源优先级：remote(server-managed) → MDM/OS 策略 → managed-settings 文件 → HKCU。

优先级与合并规则

企业 managed > 命令行 --settings > settings.local.json > 项目 settings.json > 用户 settings.json

• 标量键（model）：高优先级覆盖。
• 列表键（permissions.allow）：跨文件合并，不是覆盖。
• permissions.deny：永远赢，宽泛的 deny 压过更窄的 allow。
• 环境变量不属于这个栈，它与同名键按「键 + 变量」成对决定：ANTHROPIC_MODEL 覆盖任何文件里的 model。
• 少数安全键会采纳更低层级的更严格值（如 maxEffortLevel）。
• 部分键只在会话启动时读一次（model、effortLevel），改了要重开会话；permissions、hooks、apiKeyHelper 是热重载。

查当前状态

claude config list
claude config get <key>
claude doctor

会话内 /status 的 Setting sources 行会显示托管源，如 (remote) / (plist) / (HKLM) / (file) / (drop-ins) / (HKCU)。

2. settings.json 键位

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "sonnet",
  "fallbackModel": "haiku",
  "permissions": {
    "allow": [],
    "ask": [],
    "deny": [],
    "defaultMode": "acceptEdits",
    "additionalDirectories": ["../shared"],
    "disableBypassPermissionsMode": "disable"
  },
  "env": {
    "NODE_ENV": "development"
  },
  "hooks": {},
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 0
  },
  "enableAllProjectMcpServers": false,
  "enabledMcpjsonServers": [],
  "disabledMcpjsonServers": [],
  "cleanupPeriodDays": 30,
  "alwaysThinkingEnabled": true,
  "spinnerTipsEnabled": false,
  "attribution": {
    "commit": "",
    "pr": ""
  },
  "outputStyle": "Explanatory",
  "autoUpdatesChannel": "stable",
  "apiKeyHelper": "",
  "disableAllHooks": false,
  "sandbox": {
    "enabled": true
  }
}

已废弃 / 不存在（常见误写）：

$schema 可用但 schema 可能滞后于 CLI 版本；claude doctor 会报出不认识的键。

3. 权限规则

求值顺序

deny  >  ask  >  allow

先 deny，再 ask，最后 allow；第一个命中的决定结果，规则宽窄不改变顺序。allow 无法在 deny 里开口子。

完整示例

{
  "permissions": {
    "allow": [
      "Bash(npm run test:*)",
      "Bash(git status)",
      "Bash(git diff:*)",
      "Read(./src/**)",
      "Read(./**/*.md)",
      "Edit(./src/**)",
      "WebFetch(domain:docs.claude.com)",
      "WebSearch",
      "Agent(Explore)",
      "mcp__github__get_issue",
      "mcp__puppeteer__*"
    ],
    "ask": [
      "Bash(git push:*)",
      "Bash(npm publish:*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(//etc/passwd)",
      "Edit(./**/*.pem)",
      "Bash(curl:*)",
      "Bash(rm -rf:*)"
    ]
  }
}

Bash 匹配规则

• * 匹配任意文本（含空格）。
• :* 后缀等价末尾通配：Bash(ls:*) == Bash(ls *)。:* 只在模式末尾被识别。
• 末尾 * 且前面有空格时也匹配裸命令：Bash(ls *) 匹配 ls；而 Bash(ls*) 连 lsof 也匹配。
• 复合命令按 &&、||、;、|、|&、&、换行拆分，规则须逐个子命令都匹配。
• 会被自动剥离的包装器：timeout、time、nice、nohup、stdbuf、shell 内建 command/builtin、zsh noglob、裸 xargs，以及「已知安全变量的前导赋值」。npx、docker exec 不在剥离列表内。
• 文档提醒：Bash(curl http://example.com/ *) 这类参数约束规则很脆弱，别依赖它做安全边界。

路径规则（Read / Edit）

/path 的锚点按来源区分：项目/本地 settings → 主工作目录；用户 settings → ~/.claude/；--settings <file> → 该文件所在目录；CLI flags → 主工作目录。

Windows：路径先归一化为 POSIX（C:\Users\alice → /c/Users/alice），跨盘用 //**/.env。

! 开头是 gitignore 取反，且只能在本文件内抵消前面的规则。

各工具的可匹配形态

MCP 规则的坑：带括号的 mcp__x__y(...) 在加载 settings 时会被跳过；要限定 MCP 参数得走 --disallowedTools。按 server 通配用 mcp__puppeteer__*。
裸工具名作为 deny 会把该工具整个从 Claude 上下文中移除（省 token，但也彻底没有该能力）；带限定符的 Bash(rm *) 只在使用时拦截。

defaultMode 取值

default（CLI 显示为 Manual，接受 manual 作别名）、acceptEdits、plan、auto、dontAsk、bypassPermissions

坑：auto 与 bypassPermissions 不从项目或本地 settings 生效（v2.1.257 起）。必须设在用户级或 managed，或用 --permission-mode。v2.1.257 之前任何文件都能设 bypassPermissions。

禁用方式（都在 permissions 下）：

{
  "permissions": {
    "disableBypassPermissionsMode": "disable",
    "disableAutoMode": "disable"
  }
}

信任（workspace trust）

项目 .claude/settings.json 里的 permissions.allow 与 permissions.additionalDirectories 须在信任对话框接受后才生效；deny 和 ask 立即生效。

命令行

claude --allowedTools "Bash(git log:*)" "Read(./src/**)"
claude --disallowedTools "Bash(rm:*)"
claude --permission-mode plan
claude --dangerously-skip-permissions

--dangerously-skip-permissions 官方定义就是「equivalent to --permission-mode bypassPermissions」。另有 --allow-dangerously-skip-permissions：把该模式加入 Shift+Tab 循环，但不以它启动。

4. Hooks

结构

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/guard.sh",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

matcher 语法

• "*"、"" 或省略 → 匹配全部。
• 只含字母数字、_、-、空格、,、| → 精确字符串或精确列表（"Edit|Write"、"Edit, Write"）。
• 含其他字符 → 未锚定的 JS 正则。"Edit.*" 会同时匹配 Edit 和 NotebookEdit；要整串匹配写 "^Edit$"。

MCP 工具匹配要写 mcp__memory__.* —— .* 是必需的，只写 mcp__memory 会被当精确串，匹配不到任何工具。

常用事件

实际事件约 30+ 个，还在增加。/hooks 或 claude doctor 可查当前版本全集。无 matcher 支持的事件上写了 matcher 会被静默忽略。

hook 类型

type 有 5 种：command、http、mcp_tool、prompt、agent。

通用字段：type（必填）、if（单条权限规则语法，如 "Bash(git *)"）、timeout、statusMessage。

timeout 默认值：command/http/mcp_tool = 600 秒，prompt = 30，agent = 60。UserPromptSubmit/PreModelSwitch/PostModelSwitch 降到 30，MessageDisplay 降到 10。

输入（stdin JSON）

{
  "session_id": "abc123",
  "prompt_id": "uuid",
  "transcript_path": "/path/to/session.jsonl",
  "cwd": "/path/to/project",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": { "command": "rm -rf build" },
  "tool_use_id": "toolu_xxx"
}

• permission_mode 取值：default/plan/acceptEdits/auto/dontAsk/bypassPermissions。界面上的 Manual 传过来是 "default"，永远不是 "manual"。
• 子代理内另有 agent_id、agent_type。
• 附加字段：UserPromptSubmit → prompt；SessionStart → source；PreCompact → trigger。

退出码

文档明确警告：exit 1 在多数事件上不阻塞。要强制策略必须用 exit 2。

stdout 被当作 JSON 解析的条件：首字符 { 且末字符 }。以 { 开头但未闭合、或以任何其他字符开头（含 JSON 数组），都按纯文本处理。

输出 JSON

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Destructive command blocked by hook"
  }
}

已确证存在的字段：hookSpecificOutput（含 hookEventName、permissionDecision、permissionDecisionReason、retry、updatedInput、additionalContext）、systemMessage、terminalSequence、decision。

• PermissionRequest 用 hookSpecificOutput.decision.behavior（值 "allow"）。
• PostToolUse 与 Stop 用顶层 decision: "block"。

continue、stopReason、suppressOutput 在官方页面上存在但定义未逐字取到，暂不示例。

拦截危险命令（完整可用）

配置：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

脚本 .claude/hooks/block-rm.sh：

#!/usr/bin/env bash
set -euo pipefail
input=$(cat)
cmd=$(jq -r '.tool_input.command // empty' <<<"$input")

if [[ "$cmd" =~ rm[[:space:]]+-rf ]]; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Destructive command blocked by hook"
    }
  }'
fi
exit 0

保存即格式化

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs -r npx prettier --write"
          }
        ]
      }
    ]
  }
}

hook 配置能放哪

~/.claude/settings.json、.claude/settings.json、.claude/settings.local.json、managed settings、插件 hooks/hooks.json、skill frontmatter、subagent frontmatter。

所有匹配的 hook 并行执行。同一 handler 在多个 settings 文件里定义只跑一次。整体关闭："disableAllHooks": true（它同时会关掉自定义 statusLine 和 @ 文件补全命令）；没有只关单个 hook 的办法。

调试：claude --debug hooks

5. 环境变量

端点 / 认证

模型

网络

HTTPS_PROXY（推荐）、HTTP_PROXY、NO_PROXY（空格或逗号分隔，支持 .example.com 与 *）。

• 小写变体同样有效，取值顺序：https_proxy → HTTPS_PROXY → http_proxy → HTTP_PROXY。
• 不支持 SOCKS 代理。
• Basic auth 直接写进 URL：http://user:pass@proxy:8080。

超时 / 上限

隐私 / 遥测

CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
DISABLE_TELEMETRY=1
DISABLE_ERROR_REPORTING=1

「非空即开启」型开关：这类变量只要非空（包括设成 0）就算开启。要关闭必须 unset 或设为空串。属于这一类的有 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC、DISABLE_TELEMETRY、DISABLE_ERROR_REPORTING、CLAUDE_CODE_TMUX_TRUECOLOR、FALLBACK_FOR_ALL_PRIMARY_MODELS、IS_DEMO。

其他

脚本里读（运行时注入）

写在哪

① settings.json 的 env：

{
  "env": {
    "NODE_ENV": "development",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

• shell 与 settings 文件同时设置时，设置文件的值生效。
• settings 文件里只能设变量，不能删变量；要压掉 shell 里无法 unset 的变量，就设为空串 ""。

② shell 环境变量（全局）：

export ANTHROPIC_BASE_URL="https://gateway.example.com"

③ 单次会话：

ANTHROPIC_MODEL=opus claude

数字变量的写法：支持科学计数法与数字分隔符，2e3 读作 2000、64_000 读作 64000。（v2.1.211 之前 1e6 会被错误地设成 1。）

6. MCP

.mcp.json（项目根，进 git）

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./data"],
      "env": { "LOG_LEVEL": "info" }
    },
    "tavily": {
      "type": "http",
      "url": "https://mcp.tavily.com/mcp/",
      "headers": { "Authorization": "Bearer ${TAVILY_API_KEY}" }
    },
    "legacy": {
      "type": "sse",
      "url": "https://example.com/sse"
    }
  }
}

• 有 url 但没 type 是配置错误 —— 会被当成 stdio 服务器读取。
• 变量展开支持 ${VAR} 与 ${VAR:-default}，位置：command、args、env、url、headers。
• ${VAR} 未定义 → 该 server 加载失败。
• 每服务器工具超时 "timeout": 600000（毫秒），覆盖该服务器的 MCP_TOOL_TIMEOUT；低于 1000 的值被忽略。

作用域与优先级

整个 server 条目取用（字段不合并），优先级高 → 低：local → project → user → 插件提供 → claude.ai 连接器。

命令

claude mcp add --transport http <name> <url>
claude mcp add --transport sse <name> <url>
claude mcp add --env KEY=val <name> -- <command> [args...]
claude mcp add-json <name> '{"type":"stdio","command":"npx","args":["-y","pkg"]}'
claude mcp add-from-claude-desktop
claude mcp list
claude mcp get <name>
claude mcp remove <name>
claude mcp login <name>
claude mcp logout <name>
claude mcp reset-project-choices
claude mcp serve

标志：-s/--scope（local/project/user）、-t/--transport（http/sse/stdio，不接受 ws）、-e/--env、-H/--header、--callback-port、--client-id、--client-secret。

--env 与服务器名之间至少放一个其他选项，否则名字会被当成又一对 KEY=value。

会话内：/mcp（状态、OAuth 认证、重连）。

信任开关

{
  "enableAllProjectMcpServers": false,
  "enabledMcpjsonServers": ["tavily"],
  "disabledMcpjsonServers": ["experimental"]
}

.mcp.json 里写的是会被执行的任意命令。克隆陌生仓库先审再信任。

7. 可复制模板

团队共享（.claude/settings.json，进 git）

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(pnpm install)",
      "Bash(pnpm run test:*)",
      "Bash(pnpm run lint:*)",
      "Bash(git status)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Read(./src/**)",
      "Read(./docs/**)"
    ],
    "ask": [
      "Bash(git push:*)",
      "Bash(pnpm publish:*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Edit(./**/*.pem)",
      "Bash(curl:*)",
      "Bash(rm -rf:*)"
    ]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "pnpm exec prettier --write $(jq -r '.tool_input.file_path')"
          }
        ]
      }
    ]
  }
}

个人覆盖（.claude/settings.local.json，不进 git）

{
  "env": {
    "TAVILY_API_KEY": ""
  },
  "permissions": {
    "allow": ["Bash(docker:*)"]
  },
  "enabledMcpjsonServers": ["tavily"]
}

敏感值放这里，或干脆走 shell 环境变量 / apiKeyHelper。不要写进会提交的 settings.json。

企业网关

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm-gateway.corp.example.com",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "apiKeyHelper": "/usr/local/bin/get-gateway-key.sh",
  "forceLoginMethod": "console"
}

走 Bedrock 另加 CLAUDE_CODE_USE_BEDROCK=1 + AWS_REGION；走 Vertex 加 CLAUDE_CODE_USE_VERTEX=1 + CLOUD_ML_REGION + ANTHROPIC_VERTEX_PROJECT_ID。

Windows 代理

{
  "env": {
    "HTTPS_PROXY": "http://127.0.0.1:7890",
    "HTTP_PROXY": "http://127.0.0.1:7890",
    "NO_PROXY": "localhost,127.0.0.1"
  }
}

或用 setx（改完需重开终端）。

沙箱

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "network": {
      "allowUnixSockets": ["/var/run/docker.sock"]
    },
    "filesystem": {
      "allowWrite": ["./tmp", "./build"],
      "denyRead": ["~/.ssh", "~/.aws"]
    }
  }
}

⚠️ 沙箱只在 macOS、Linux、WSL 2 上支持。Native Windows 不支持（WSL 1 也不支持）。

statusLine

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

padding 默认 0；refreshInterval 最小 1 秒；hideVimModeIndicator 可抑制 -- INSERT --。