Claude Code 常用配置手册

面向日常使用的 Claude Code 配置参考：配置文件在哪、每个键干什么、权限怎么写、hooks 怎么挂、环境变量怎么设。
文末附可直接抄的场景配方。

关于准确性：本文内容已对照官方文档（https://code.claude.com/docs/en/）逐条核验，核验基准版本为 2.1.275。仍请以 claude doctor、claude config list、/help 的实际输出为准。

⚠️ settings.json 是严格 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."

目录

• 1. 配置文件层级与优先级
• 2. settings.json 键位参考
• 3. 权限系统 permissions
• 4. Hooks
• 5. 环境变量
• 6. MCP 配置
• 7. 子代理 / 斜杠命令 / 技能 / 输出风格
• 8. CLAUDE.md 记忆与上下文
• 9. statusLine 状态栏
• 10. CLI 参数与内置斜杠命令
• 11. 场景配方
• 12. 排错

1. 配置文件层级与优先级

1.1 五层结构

• ~/.claude 在 Windows 上 = %USERPROFILE%\.claude。可用 CLAUDE_CONFIG_DIR 改变它的位置。
• ~/.claude.json（注意是文件，不是目录）保存登录态、项目历史、local 作用域 MCP 等运行时数据，不要手工编辑。

1.2 合并规则

• 标量键（model）：高优先级覆盖低优先级。
• 列表键（permissions.allow）：跨文件合并，不是覆盖。
• permissions.deny：永远赢。
• 环境变量不属于这个栈。它与同名键按「键 + 变量」成对决定谁优先：ANTHROPIC_MODEL 覆盖任何文件里的 model；ANTHROPIC_DEFAULT_MODEL 只在没有任何文件设置 model 时才生效。
• 少数安全敏感键会采纳更低层级的更严格值（如 maxEffortLevel、remoteControlAtStartup、crossSessionInbound）。

生效时机：多数键（含 permissions、hooks、apiKeyHelper）热重载；model、effortLevel、modelSettings 只在会话启动时读一次，改了要重开会话。

1.3 企业级 managed settings

旧的 C:\ProgramData\ClaudeCode\managed-settings.json 已不再读取。
同目录可放 managed-settings.d/*.json 分片：先合并 managed-settings.json，再按文件名字母序合并分片。用 10-、20- 前缀控制顺序；隐藏文件和非 .json 文件被忽略。

托管源合并顺序（高 → 低）：remote（server-managed，来自 claude.ai 控制台）→ MDM/OS 策略 → managed-settings 文件与分片 → HKCU。

默认 managedSourcesBehavior 是 first-wins：只用最高且含 policy key 的源，其余忽略；设为 "merge" 才全部合成（需 v2.1.242+）。

会话内 /status 的 Setting sources 行会显示实际选中的来源：(remote)、(plist)、(HKLM)、(file)、(drop-ins)、(HKCU)、(parent process)、(helper)。

1.4 查当前生效配置

claude config list
claude config get <key>
claude doctor

/config 写入的「Global config」键（autoConnectIde、copyOnSelect、diffTool 等）存放在 ~/.claude.json，不在 settings.json 里。

2. settings.json 键位参考

2.1 完整骨架

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "sonnet",
  "fallbackModel": "haiku",
  "permissions": {
    "allow": ["Bash(npm run test:*)", "Read(./src/**)"],
    "ask": ["Bash(git push:*)"],
    "deny": ["Read(./.env)", "Read(./secrets/**)"],
    "defaultMode": "acceptEdits",
    "additionalDirectories": ["../shared-libs"],
    "disableBypassPermissionsMode": "disable"
  },
  "env": {
    "NODE_ENV": "development"
  },
  "hooks": {},
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 0
  },
  "enableAllProjectMcpServers": false,
  "enabledMcpjsonServers": ["tavily"],
  "disabledMcpjsonServers": ["untrusted"],
  "cleanupPeriodDays": 30,
  "alwaysThinkingEnabled": true,
  "spinnerTipsEnabled": false,
  "attribution": {
    "commit": "",
    "pr": ""
  },
  "outputStyle": "Explanatory",
  "autoUpdatesChannel": "stable",
  "disableAllHooks": false,
  "apiKeyHelper": "/path/to/get-key.sh",
  "forceLoginMethod": "claudeai",
  "sandbox": {
    "enabled": true
  }
}

2.2 键位说明

2.3 常见误写（重要）

另外，permissionExplainerEnabled 已在 v2.1.257 移除。

仅 managed 可设置的键（放在用户/项目 settings 里无效）：allowManagedHooksOnly、allowManagedMcpServersOnly、allowManagedPermissionRulesOnly、managedMcpServers、managedSourcesBehavior、strictKnownMarketplaces、blockedMarketplaces、policyHelper、wslInheritsWindowsSettings、claudeMd 等。

3. 权限系统 permissions

3.1 defaultMode 取值

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

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

禁用（都在 permissions 之下）：

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

3.2 求值顺序

官方原文："Rules are evaluated in order: deny, then ask, then allow. The first match in that order determines the outcome, and rule specificity doesn't change the order."

deny  >  ask  >  allow

第一个命中的决定结果，规则宽窄不改变顺序。宽泛的 deny 会压过更窄的 allow，allow 无法在 deny 里开口子。

3.3 规则语法

格式 Tool 或 Tool(specifier)。specifier 内的括号是字面量，无需转义。

Bash —— 通配与前缀

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

路径规则（Read / Edit）

/path 锚点对照：

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

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

各工具的可匹配形态

MCP 规则的坑：加载 settings 时会跳过任何带括号的 mcp__ 规则（mcp__x__y(...)）。要限定 MCP 参数得走 --disallowedTools。
裸工具名作 deny（如 Bash 或 Bash(*)）会把该工具整个从 Claude 上下文中移除；带限定符的 Bash(rm *) 保留工具、只在调用时拦截。

Bash 示例

{
  "permissions": {
    "allow": [
      "Bash(npm run test:*)",
      "Bash(git status)",
      "Bash(git diff:*)",
      "Bash(ls:*)"
    ],
    "deny": [
      "Bash(curl:*)",
      "Bash(rm -rf:*)",
      "Bash(git push --force:*)"
    ]
  }
}

路径示例

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(//etc/passwd)",
      "Edit(//etc/**)"
    ],
    "allow": [
      "Read(./src/**)",
      "Read(./**/*.md)",
      "Edit(./src/**)"
    ]
  }
}

3.4 信任（workspace trust）

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

.claude/settings.local.json 若未被 git 跟踪，其 allow 规则不等信任。

3.5 命令行管理

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

• --dangerously-skip-permissions：官方定义 "equivalent to --permission-mode bypassPermissions"。
• --allow-dangerously-skip-permissions：把 bypassPermissions 加入 Shift+Tab 模式循环，但不以它启动。
• 会话内：/permissions（别名 /allowed-tools）。

安全提醒：deny 是最后一道防线，但挡不住内容级逃逸 —— Bash(python:*) 等于任意代码执行。真正的隔离要靠 sandbox 或容器。切勿把 API key 写进会提交的 settings.json。

4. Hooks

Hooks 让 harness 本身在特定事件触发时执行动作（不依赖模型自觉），是实现"每次 X 之后自动 Y"的唯一可靠方式。

4.1 事件表

事件数量远多于早期版本（约 30+ 个），按用途分组：

常用事件的 matcher 匹配对象：

无 matcher 支持的事件（UserPromptSubmit、Stop、WorktreeCreate 等）上写了 matcher 会被静默忽略。
用 /hooks 或 claude doctor 查当前版本全集。

4.2 matcher 语法

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

MCP 工具匹配要写 mcp__memory__.* —— .* 是必需的，只写 mcp__memory 会被当精确串，匹配不到任何工具。插件服务器格式为 mcp__plugin_<plugin-name>_<server-name>__<tool>。

4.3 hook 类型（5 种）

通用字段：

路径占位符：${CLAUDE_PROJECT_DIR}（会话启动时的项目根）、${CLAUDE_PLUGIN_ROOT}、${CLAUDE_PLUGIN_DATA}。引用占位符时优先用 exec 形式；shell 形式要给每个占位符加双引号。

4.4 配置结构

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh",
            "args": []
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs -r npx prettier --write"
          }
        ]
      }
    ]
  }
}

• 所有匹配的 hook 并行执行。
• 同一 handler 在多个 settings 文件里定义只跑一次（插件/skill 的副本另算）。

hook 能配在哪：~/.claude/settings.json、.claude/settings.json、.claude/settings.local.json、managed settings、插件 hooks/hooks.json、skill frontmatter、subagent frontmatter。

整体关闭："disableAllHooks": true。注意它同时会关掉自定义 status line 和自定义 @ 文件补全命令；没有只关单个 hook 的办法。

4.5 输入（stdin JSON）

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

附加字段：UserPromptSubmit → prompt；SessionStart → source；PreCompact → trigger。

读法示例：

#!/usr/bin/env bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command // empty')
echo "about to run: $cmd" >&2
exit 0

4.6 退出码

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

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

4.7 输出 JSON

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

已确证存在的字段：

• PermissionRequest 用 hookSpecificOutput.decision.behavior（值 "allow"），并可带 updatedPermissions: [{"type": "setMode", "mode": "acceptEdits", "destination": "session"}]。

continue、stopReason、suppressOutput 在官方页面中存在，但其完整定义未逐字取得，本文不做示例。

4.8 完整示例：拦截危险命令

settings.json：

{
  "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

记得 chmod +x .claude/hooks/block-rm.sh。

4.9 完整示例：保存即格式化

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

4.10 调试

claude --debug hooks
claude --debug='mcp,startup'

安全提醒：hook 是以你的身份执行的任意命令。项目共享 settings.json 里的 hooks 会被团队成员执行，审查时重点看这里。

5. 环境变量

分两类：配置类（你主动设置）和运行时注入类（Claude Code 传给子进程，你在脚本里读）。

5.1 认证与端点

5.2 模型与思考

5.3 网络

HTTPS_PROXY（推荐）、HTTP_PROXY、NO_PROXY。

• 取值顺序：https_proxy → HTTPS_PROXY → http_proxy → HTTP_PROXY（小写变体同样有效）。
• NO_PROXY 用空格或逗号分隔，支持 .example.com 与 *。
• 不支持 SOCKS 代理。
• 发往 localhost / ::1 / 127.0.0.0/8 的 WebSocket 永不走代理。
• Basic auth 写进 URL：http://user:pass@proxy:8080。

5.4 超时与上限

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

5.5 隐私与遥测

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

5.6 其他配置类

5.7 运行时注入类（脚本里读）

5.8 设置方式与优先级

① settings.json 的 env：

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

• shell 与 settings 文件同时设置时，设置文件的值生效。
• settings 文件里只能设变量、不能删变量；要压掉 shell 里无法 unset 的变量，就设为空串 ""（对 provider 选择类变量，空值等同于未设置）。
• env 受 settings 优先级约束，managed 覆盖 user/project。

② shell 环境变量（全局）：

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

③ 单次会话：

ANTHROPIC_MODEL=opus claude

敏感值不要写进 settings.json。放 settings.local.json 或走 shell / apiKeyHelper。

6. MCP 配置

6.1 .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 的值被忽略。

6.2 作用域

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

6.3 管理命令

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 认证、重连）。

6.4 项目 server 的信任开关

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

安全提醒：.mcp.json 描述的是会被执行的任意命令（command + args）。克隆陌生仓库后先审 .mcp.json 再信任 —— 这是典型的供应链风险面。

7. 子代理 / 斜杠命令 / 技能 / 输出风格

7.1 子代理 .claude/agents/*.md

查找优先级（高 → 低）：managed settings → --agents CLI 标志 → .claude/agents/ → ~/.claude/agents/ → 插件 agents/。递归扫描，子目录路径不影响身份（身份只来自 name）。

---
name: test-runner
description: 运行测试并修复失败。当需要执行测试或排查测试失败时使用。
tools: Bash, Read, Edit, Grep, Glob
model: haiku
---

你是测试专家。被调用时：

1. 先跑 `npm test`，读取失败信息
2. 定位到源码后修复，不要修改测试断言来"通过"
3. 重跑直到全绿，最后汇报改了哪些文件

⚠️ 常见错误：子代理没有 allowed-tools 字段（那是 skill 的字段）。子代理用 tools / disallowedTools。

子代理在独立上下文里运行，只把最终报告带回主会话 —— 适合"读一堆文件只留结论"的任务。

--agents 接受 JSON，用 prompt 字段代替 markdown 正文。

7.2 技能与自定义斜杠命令

技能：~/.claude/skills/<name>/SKILL.md（个人）、.claude/skills/<name>/SKILL.md（项目）、插件 skills/<name>/SKILL.md（以 /plugin-name:skill-name 调用）。

---
name: deploy
description: 部署到预发/生产。当用户提到部署、发布、上线时使用。
allowed-tools: Bash, Read
argument-hint: "[staging|prod]"
---

## 预发

./scripts/deploy.sh staging

## 生产（需二次确认）

1. 先确认当前分支已合并到 main
2. ...

参数语法：$ARGUMENTS（全部参数原样）、$ARGUMENTS[N]（0 起始索引）、$N（简写，$0 是第一个参数、$1 是第二个）、$name（由 arguments frontmatter 列表声明）。无占位符接收时，Claude Code 追加 ARGUMENTS: <value>。字面 $ 用反斜杠转义（\$1.00）。

! 前缀（bash 执行）： !`<command>` 在内容发给 Claude 前运行，输出替换占位符。仅当 ! 位于行首或紧跟空白时才被识别；多行命令用 `! 围栏。执行失败会中止整个 skill。可用 "disableSkillShellExecution": true 全局禁用。

旧格式仍可用：.claude/commands/*.md → /文件名；子目录 → /子目录:文件名（如 .claude/commands/frontend/component.md → /frontend:component）。个人命令放 ~/.claude/commands/。

/ 命令名可堆叠（如 /write-tests /fix-issue 123）。命令是用户显式触发，技能可由模型按 description 自动触发。

7.3 输出风格 .claude/output-styles/*.md

路径：~/.claude/output-styles/（用户）、.claude/output-styles/（项目，从工作目录到仓库根逐层加载，同名取最靠近工作目录的）。

---
name: 教学式
description: 每步都解释原理，适合学习
keep-coding-instructions: true
---

在动手前先用一句话说明思路。修改代码后，解释为什么这样改而不是别的方案。
遇到有多种解法时，列出权衡再推荐。

内置风格共 5 个：Default、Proactive、Concise、Explanatory、Learning。

切换：/output-style <style>（保存进 .claude/settings.local.json）或设 outputStyle 键。

8. CLAUDE.md 记忆与上下文

8.1 查找位置

按加载顺序（从宽到窄）：

加载规则：从当前工作目录向上每一级都加载 CLAUDE.md 与 CLAUDE.local.md，拼接而非覆盖，顺序是从文件系统根往下（离工作目录最近的读得最晚）；同目录内 CLAUDE.local.md 追加在 CLAUDE.md 之后。子目录中的文件在 Claude 读取该目录文件时按需加载。

8.2 @path 导入

• 相对路径相对于包含该 import 的文件解析（不是工作目录）。
• 可递归，最大深度 4 跳。
• Markdown 代码段与围栏代码块内的 @ 不解析（写 `@README` 可保持字面）。
• 从 project 级文件导入到工作目录之外的外部导入会首次触发批准对话框。

# 项目规范

@docs/coding-standards.md
@.claude/rules/testing.md

## 本仓库特有

- 包管理器用 pnpm，不要用 npm
- 提交前必须跑 `pnpm verify`

8.3 .claude/rules/

.md 文件递归发现：

• 无 paths frontmatter 的规则随启动加载，优先级等同 .claude/CLAUDE.md。
• 带 paths frontmatter 的规则只在 Claude 读到匹配文件时加载，glob 支持花括号展开（"src/**/*.{ts,tsx}"）。
• 个人规则目录 ~/.claude/rules/ 在项目规则之前加载。

8.4 自动记忆

默认开启，位于 ~/.claude/projects/<project>/memory/，含 MEMORY.md 索引 + 每主题一个文件。每次会话加载 MEMORY.md 的前 200 行或前 25KB（先到者为准）。

• 开关：autoMemoryEnabled（用户 settings）或 /memory 里的开关
• 目录：autoMemoryDirectory（须绝对路径或以 ~/ 开头）
• 关闭：CLAUDE_CODE_DISABLE_AUTO_MEMORY=1
• CLAUDE.md 文件上限 4 MiB，超过则跳过

8.5 关于 .claudeignore

不存在。 官方文档明确写 "No .claudeignore exists"，也没有任何供 Claude Code 使用的 ignore 文件。

要排除文件访问，用权限规则（deny 拒绝读取凭据文件）；要扩展文件访问，用 --add-dir / /add-dir / permissions.additionalDirectories。

（相关但不同：.worktreeinclude 是项目根的只读输入，gitignore 语法，仅在创建 worktree 时用于复制被 gitignore 的文件。）

8.6 上下文管理

/context      # 查看上下文组成与占用
/compact      # 手动压缩（可加指令：/compact 保留所有 schema 变更）
/clear        # 清空重开
/memory       # 编辑记忆文件

8.7 写什么才有效

CLAUDE.md 每次都会进上下文，所以要短且高信号：

• 该写：构建/测试命令、包管理器、目录约定、"不要动 X"、指向上位文档的链接。
• 不该写：大段代码示例、能从代码读出来的东西、临时任务笔记。

9. statusLine 状态栏

9.1 配置

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

9.2 输入 JSON

脚本从 stdin 收到（主要字段）：

⚠️ 注意层级：session_id 和 output_style 都在顶层，不在 cost 里。

9.3 示例脚本

#!/usr/bin/env bash
# ~/.claude/statusline.sh
input=$(cat)

cwd=$(echo "$input" | jq -r '.workspace.current_dir')
model=$(echo "$input" | jq -r '.model.display_name')
cost=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
added=$(echo "$input" | jq -r '.cost.total_lines_added // 0')
removed=$(echo "$input" | jq -r '.cost.total_lines_removed // 0')
pct=$(echo "$input" | jq -r '.context_window.used_percentage // 0')

branch=$(git -C "$cwd" branch --show-current 2>/dev/null)
dir=$(basename "$cwd")

printf '\033[36m%s\033[0m \033[32m%s\033[0m \033[33m$%.2f\033[0m \033[32m+%s\033[0m/\033[31m-%s\033[0m ctx:%s%%' \
  "$dir" "${branch:-no-git}" "$cost" "$added" "$removed" "$pct"

chmod +x ~/.claude/statusline.sh

要点：

• 输出支持 ANSI 颜色与 OSC 8 超链接；可多行输出。
• tput cols 在脚本内不可用，要读 Claude Code 设置的 COLUMNS / LINES 环境变量。
• status line 不消耗 API token。
• 脚本要快（每次刷新都执行），避免网络请求或重命令。

10. CLI 参数与内置斜杠命令

10.1 常用 CLI 参数

claude [prompt]
claude -p "总结这个仓库"
cat file | claude -p "解释这段代码"

官方提示：claude --help 不列出全部 flag，不在帮助里不代表不可用。

10.2 常用子命令

claude update
claude doctor
claude auth login | logout | status
claude mcp ...
claude plugin | plugins
claude install [version]
claude setup-token
claude project purge [path]

10.3 内置斜杠命令（常用）

命令全集远多于此，且可用性随平台/套餐/环境变化（例如 /desktop 仅在 macOS 与 x64 Windows + 订阅时出现）。以 /help 实际输出为准。

11. 场景配方

11.1 团队共享的项目配置

.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"]
}

由 Claude Code 创建的 .claude/settings.local.json 会自动加进你的全局 git excludes；手工创建的要自己加 .gitignore。

11.2 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 HTTPS_PROXY "http://127.0.0.1:7890"。改完需重开终端。不支持 SOCKS。

11.3 接入企业网关

{
  "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"
}

get-gateway-key.sh 从 Vault / SSO 取短期 token 并输出到 stdout。

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

11.4 只读审计模式

claude --permission-mode plan \
       --allowedTools "Read,Grep,Glob" \
       --disallowedTools "Bash,Edit,Write"

或写成技能 .claude/skills/audit/SKILL.md：

---
name: audit
description: 只读审计指定模块，列出风险点
allowed-tools: Read, Grep, Glob
argument-hint: "[目录]"
---

对 $ARGUMENTS 做只读审计：列出风险点、缺失的错误处理、可疑的并发假设。
不要修改任何文件，最后给一份带 file:line 的清单。

11.5 沙箱

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

⚠️ 沙箱只在 macOS、Linux、WSL 2 上支持。官方安装对照表里 Native Windows 的 Sandboxing 一栏是 "Not supported"（WSL 1 同样不支持）。要在 Windows 上用沙箱，得在 WSL 2 里跑 Claude Code。

11.6 关闭全部遥测

export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
export DISABLE_TELEMETRY=1
export DISABLE_ERROR_REPORTING=1

这类开关非空即开启，设成 0 仍然算开启。

11.7 无人值守 CI

claude -p "$PROMPT" \
  --output-format json \
  --max-turns 10 \
  --max-budget-usd 5 \
  --permission-mode bypassPermissions \
  --allowedTools "Read,Grep,Glob"

仅在一次性容器里用 bypassPermissions。宿主机上永远不要。

12. 排错

通用手法：

claude doctor
claude --debug
claude --debug='mcp,hooks,startup'
claude config list

附：文件清单速查

~/.claude/
├── settings.json                 用户级配置
├── CLAUDE.md                     用户级记忆
├── rules/                        个人规则
├── statusline.sh                 状态栏脚本（自定义）
├── commands/                     个人斜杠命令
├── agents/                       个人子代理
├── skills/                       个人技能
├── output-styles/                个人输出风格
└── projects/<project>/memory/    自动记忆（MEMORY.md + 主题文件）
~/.claude.json                    运行时状态（登录态/项目历史/本地 MCP），勿手编

<项目>/
├── .claude/
│   ├── settings.json             项目共享配置（进 git）
│   ├── settings.local.json       个人覆盖（自动 gitignore）
│   ├── hooks/                    hook 脚本
│   ├── rules/                    规则（可带 paths frontmatter）
│   ├── commands/                 斜杠命令（旧格式仍可用）
│   ├── agents/                   子代理
│   ├── skills/<name>/SKILL.md    技能
│   └── output-styles/            输出风格
├── .mcp.json                     项目 MCP servers（进 git）
├── CLAUDE.md                     项目记忆（进 git）
└── CLAUDE.local.md               本地记忆（自加 gitignore）

<企业托管>/
├── Windows: C:\Program Files\ClaudeCode\managed-settings.json
├── Windows: HKLM\SOFTWARE\Policies\ClaudeCode → "Settings"
├── macOS:   /Library/Application Support/ClaudeCode/managed-settings.json
└── Linux:   /etc/claude-code/managed-settings.json
             （同目录可放 managed-settings.d/*.json 分片）

核验基准：Claude Code 2.1.275，官方文档 https://code.claude.com/docs/en/。配置项随版本演进较快，遇到与本文不符处，以 claude doctor、claude config list、/help 的实际输出为准。