Claude Code 配置速查表

最常用的键、规则、模板和坑。

⚠️ 严格 JSON

settings.json 是严格 JSON。// 注释和尾逗号都是语法错误，会导致该文件被整个跳过，启动时报 Settings Error。

一、放到哪

优先级（高 → 低）：企业 managed → 命令行 --settings → settings.local.json → 项目 settings.json → 用户 settings.json

企业 managed 路径：

旧的 C:\ProgramData\ClaudeCode\managed-settings.json 已不再读取。
同目录可放 managed-settings.d/*.json 分片，按文件名字母序合并。

claude config list      # 看当前生效值
claude doctor           # 报出配置错误

二、最常用键

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "sonnet",
  "fallbackModel": "haiku",
  "permissions": {
    "allow": ["Bash(npm run test:*)", "Bash(git status)", "Read(./src/**)"],
    "ask": ["Bash(git push:*)"],
    "deny": ["Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)", "Bash(curl:*)"],
    "defaultMode": "acceptEdits",
    "additionalDirectories": ["../shared-libs"]
  },
  "env": { "NODE_ENV": "development" },
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 0
  },
  "cleanupPeriodDays": 30,
  "alwaysThinkingEnabled": true,
  "spinnerTipsEnabled": false,
  "outputStyle": "Explanatory",
  "enableAllProjectMcpServers": false,
  "enabledMcpjsonServers": [],
  "disabledMcpjsonServers": [],
  "disableAllHooks": false
}

三、权限

求值顺序

deny  >  ask  >  allow

先看 deny，再看 ask，最后看 allow；第一个命中的决定结果，规则宽窄不影响顺序。宽泛的 deny 会压过更窄的 allow。

常用写法

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

路径写法（Read / Edit）

Windows 路径先归一化为 POSIX：C:\Users\alice → /c/Users/alice，所以写 //c/**/.env。

defaultMode 取值

default（CLI 里叫 manual）、acceptEdits、plan、auto、dontAsk、bypassPermissions

坑：auto 与 bypassPermissions 不从项目或本地 settings 生效（v2.1.257 起）。要设就设在用户级或 managed，或用 --permission-mode。
禁用它们："disableBypassPermissionsMode": "disable"、"disableAutoMode": "disable"（都在 permissions 下，取值都是字符串 "disable"）。

要点

• Bash 是前缀匹配，Bash(npm run test:*) 的 :* 必须写（等价 Bash(npm run test *)）。
• Bash(ls*) 会连 lsof 一起匹配；要精确就写 Bash(ls *)。
• 复合命令按 && || ; | 拆分，规则要逐个子命令都命中。
• MCP 规则是 mcp__<server>__<tool>，支持 mcp__puppeteer__* 这种通配；但带括号的 mcp__x__y(...) 会被跳过。
• Write / MultiEdit / NotebookEdit 上的路径规则会被接受但永不生效，要用 Edit(...)。
• 裸 Bash 作为 deny 会把 Bash 工具整个从上下文移除（省 token 但也失去能力）；Bash(rm *) 只拦截。
• 会话内改：/permissions；单次注入：claude --allowedTools "..." --disallowedTools "..."

四、环境变量（常设）

# 端点 / 认证
ANTHROPIC_BASE_URL          # 网关或代理端点
ANTHROPIC_AUTH_TOKEN        # 自定义 Authorization 头
ANTHROPIC_API_KEY

# 模型
ANTHROPIC_MODEL             # 覆盖 settings 里的 model
ANTHROPIC_DEFAULT_HAIKU_MODEL   # 后台小模型
CLAUDE_CODE_SUBAGENT_MODEL

# 代理
HTTPS_PROXY / HTTP_PROXY / NO_PROXY    # 不支持 SOCKS
                                       # 小写变体也有效

# 超时 / 上限
API_TIMEOUT_MS=600000
BASH_DEFAULT_TIMEOUT_MS=120000
BASH_MAX_TIMEOUT_MS=600000
BASH_MAX_OUTPUT_LENGTH=30000
MCP_TIMEOUT / MCP_TOOL_TIMEOUT

# 隐私 / 遥测
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
DISABLE_TELEMETRY=1
DISABLE_ERROR_REPORTING=1

# 脚本里读（运行时注入）
CLAUDECODE                  # 在 CC 子进程中为 1
CLAUDE_PROJECT_DIR          # 项目根绝对路径

ANTHROPIC_SMALL_FAST_MODEL 已废弃 → 用 ANTHROPIC_DEFAULT_HAIKU_MODEL。
这些是「非空即开启」的开关，设成 0 仍然算开启，要关必须 unset 或设为空串。

五、Hook 最小可用

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

（实际事件远多于此，约 30+ 个；/hooks 可查当前版本全集。）

退出码：

要强制策略必须用 exit 2。

拦截式输出（配合 exit 0）：

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "禁止 rm -rf"
  }
}

command 里用 ${CLAUDE_PROJECT_DIR} 拼绝对路径（hook 的 cwd 不保证是项目根）；脚本记得 chmod +x；调试 claude --debug hooks。

六、MCP 最小

<项目>/.mcp.json（进 git）：

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

• type：stdio / http / sse / ws。有 url 但没 type 会被当成 stdio（配置错误）。
• 支持 ${VAR} 与 ${VAR:-default}；${VAR} 未定义 → 该 server 加载失败。
• 整个 server 超时可设 "timeout": 600000（毫秒，低于 1000 会被忽略）。

claude mcp add --transport http <name> <url>
claude mcp add-json <name> '{"type":"stdio","command":"npx","args":["-y","pkg"]}'
claude mcp list / get <name> / remove <name>

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

七、常见坑

配置随版本演进较快，以 claude doctor、claude config list、/help 的实际输出为准。