我读了 Claude Code 源码,挖出 10 个官方没文档的隐藏配置

Claude Code 的自动权限系统，内部代号叫 "YOLO Classifier"。

没错，就是那个变量名。在源码里真真切切地写着 yoloClassifier.ts。

这还只是冰山一角。有人通读了 Claude Code 的源码（它就躺在你的 node_modules 里），挖出了 几十个官方文档没写的配置项。

今天给你 10 个最实用的。

● ● ●

一、Hooks 能返回 JSON 修改 Claude 行为

官方文档说 Hooks 能拦截操作、能阻断执行。但文档没说的是：Hooks 可以返回 JSON，实时修改 Claude 的行为。

1. PreToolUse Hook：自动改写命令

你想让 Claude 执行 git push 时自动加 --dry-run？

可以。

settings.json：

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "~/.claude/hooks/dry-run-pushes.sh"
      }]
    }]
  }
}

~/.claude/hooks/dry-run-pushes.sh：

#!/bin/bash
INPUT=$(jq -r '.tool_input.command' < /dev/stdin)
if echo "$INPUT" | grep -q 'git push'; then
  jq -n --arg cmd "$INPUT --dry-run" '{"updatedInput": {"command": $cmd}}'
fi

Claude 以为自己在执行 git push origin main，实际上你悄悄改成了 git push origin main --dry-run。

这就是 updatedInput 字段的威力——文档里根本没提。

2. SessionStart Hook：自动注入上下文

每次打开 Claude Code，自动告诉它你在哪个分支、有多少未提交文件？

可以。

settings.json：

{
  "hooks": {
    "SessionStart": [{
      "hooks": [{
        "type": "command",
        "command": "~/.claude/hooks/session-context.sh"
      }]
    }]
  }
}

~/.claude/hooks/session-context.sh：

#!/bin/bash
BRANCH=$(git branch --show-current 2>/dev/null)
CHANGES=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')

jq -n \
  --arg branch "$BRANCH" \
  --arg changes "$CHANGES" \
  '{
    "watchPaths": ["package.json", ".env", "tsconfig.json"],
    "additionalContext": "Current branch: \($branch). Uncommitted changes: \($changes) files."
  }'

Claude 还没等你开口，就知道你在 feature/login 分支，有 3 个文件没提交。

● ● ●

二、Hooks 的三个隐藏字段

文档只说了 type、command、matcher、timeout、if、statusMessage。

源码里还藏着三个：once、async、asyncRewake。

字段	作用	场景
once	只运行一次，然后自动删除	首次使用时的初始化配置
async	后台运行，不阻塞 Claude	日志记录、审计
asyncRewake	平时不阻塞，出错时阻断	安全检查、敏感信息扫描

3. once：首次配置自动化

{
  "hooks": {
    "SessionStart": [{
      "hooks": [{
        "type": "command",
        "command": "[ -f .env ] || cp .env.example .env",
        "once": true,
        "statusMessage": "First-time setup..."
      }]
    }]
  }
}

第一次用这个项目时，自动从模板创建 .env 文件。

以后再也不跑。

4. async：后台审计日志

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "jq '{timestamp: now, command: .tool_input.command}' < /dev/stdin >> ~/.claude/audit.jsonl",
        "async": true
      }]
    }]
  }
}

每条 Bash 命令都记录到 audit.jsonl，零延迟。

5. asyncRewake：非阻塞式安全检查

平时不卡你，发现敏感信息时立即阻断。

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "~/.claude/hooks/scan-secrets.sh",
        "asyncRewake": true,
        "statusMessage": "Scanning for secrets..."
      }]
    }]
  }
}

scan-secrets.sh：

#!/bin/bash
FILE=$(jq -r '.tool_input.file_path // .tool_response.filePath' < /dev/stdin)
if grep -qE '(password|secret|api_key)\s*=' "$FILE" 2>/dev/null; then
  exit 2  # 阻断！
fi
exit 0  # 放行

文件里有硬编码密码？Claude 写不进去。

● ● ●

三、Skill Frontmatter 的隐藏字段

文档说了 name、description、allowed-tools。

源码里还有：model、effort、hooks。

6. model：指定模型运行 Skill

简单任务用 Haiku，便宜又快：

---
name: quick-lint
description: Fast lint check using the cheapest model
model: haiku
effort: low
allowed-tools: Bash, Read
---

复杂架构评审用 Opus，深度思考。

7. effort：控制模型思考深度

---
name: deep-review
description: Deep architecture review
model: opus
effort: max
allowed-tools: Read, Grep, Glob
---

low、medium、high、max 四档，直接控制推理深度。

8. hooks：Skill 级别的 Hook

Skill 运行时自动注册 Hook，退出时自动注销。

---
name: strict-typescript
description: Write TypeScript with type checking on every save
allowed-tools: Bash, Read, Write, Edit
hooks:
  PostToolUse:
    - matcher: "Write|Edit"
      hooks:
        - type: command
          command: "npx tsc --noEmit"
          statusMessage: "Type checking..."
---

只要这个 Skill 在运行，每保存一个 TypeScript 文件就自动类型检查。

● ● ●

四、YOLO Classifier：用自然语言配置权限

Claude Code 的自动权限系统，源码里叫 yoloClassifier.ts。

你可以用自然语言描述你的环境，让它自己判断什么是安全的：

{
  "yoloClassifier": {
    "environmentDescription": "This is a staging server. Destructive operations are acceptable."
  }
}

Claude 读到这个，对暂存服务器的"破坏性操作"就不会反复确认了。

不是黑名单机制，是语义理解。

● ● ●

五、拿走即用

完整配置模板

~/.claude/settings.json：

{
  "hooks": {
    "SessionStart": [{
      "hooks": [{
        "type": "command",
        "command": "~/.claude/hooks/git-context.sh"
      }]
    }],
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "~/.claude/hooks/auto-approve-readonly.sh"
      }]
    }],
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "~/.claude/hooks/scan-secrets.sh",
        "asyncRewake": true
      }]
    }]
  }
}

快速安装脚本

# 创建 Hooks 目录
mkdir -p ~/.claude/hooks

# 赋予执行权限
chmod +x ~/.claude/hooks/*.sh

● ● ●

写在最后

Claude Code 的源码就躺在你的 node_modules/@anthropic-ai/claude-code 里。

官方文档是起点，源码才是真相。

那些隐藏字段、未公开的返回值、内部代号——它们不是 Bug，是还没写完的文档。

"文档没写的功能，不是不存在，是还没被大众发现。"

早一步知道，早一步用好。

参考链接：

原文：I Read the Claude Code Source Code（buildingbetter.tech）
Claude Code 官方文档：https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview
源码位置：node_modules/@anthropic-ai/claude-code