<!-- title: Claude Code 配置入门：自造状态栏 -->

## 概述

本教程面向第一次接触 Claude Code 的开发者，目标是用一份 `settings.json` 让工具"默认就懂你"：选定模型、设定中文回复、自动清理历史，并亲手写一个状态栏脚本，把**当前模型、本次会话花费、增删行数**实时显示在终端底部。学完后你将掌握 Claude Code 的五层配置优先级，并拥有一个可复用、可提交团队共享的配置基线。

## 前置条件

- 已安装 Claude Code（v2.1.x，本文以 v2.1.199 为准），能运行 `claude` 进入交互界面
- 已完成登录（Claude.ai 订阅或 API Key 二选一）
- 终端里能用 `jq`（解析状态栏 JSON）：未装可 `brew install jq` 或 `apt install jq`
- 一个空目录，作为"第一个项目"的练习场

## 正文

### 第 1 步：理解五层配置优先级——为什么你的设置"没生效"

Claude Code 的配置不是一个文件说了算，而是**五层叠加**，从高到低依次为：

| 优先级 | 位置 | 是否共享 | 用途 |
|---|---|---|---|
| 1 | 托管设置（Managed，组织下发） | 是 | 安全策略，不可被覆盖 |
| 2 | 命令行参数（`claude --model opus`） | 否 | 单次会话临时覆盖 |
| 3 | `.claude/settings.local.json` | 否（git 忽略） | 个人在该项目的私有偏好 |
| 4 | `.claude/settings.json` | 是（提交到 Git） | 团队共享的项目配置 |
| 5 | `~/.claude/settings.json` | 否 | 全局个人默认值 |

两条铁律记牢：

- **`deny` 规则优先级最高**，任何低层级的 `allow`/`ask` 都无法放行被 `deny` 的命令。
- **数组类配置跨层级"拼接去重"**。例如你在全局 `allow` 了 `Bash(npm test)`，又在项目里 `allow` 了 `Bash(npm run build)`，最终两条都生效，而非后者覆盖前者。

**预期结果**：当你发现某个设置"改了没反应"，先问自己——是不是被更高优先级的层压住了？是不是命令行参数临时覆盖了？

**常见问题**：

- **问：我用 `/config` 改了设置，重启后没了？** 自 v2.1.126 起，`/config` 的修改会**持久化写入 `~/.claude/settings.json`**，重启后保留。如果你用的是更早的版本，升级即可。
- **问：团队 `.claude/settings.json` 强制了某个模型，我个人想换怎么办？** 项目级（第 4 层）高于用户级（第 5 层），所以你得改项目里的文件，或用命令行参数（第 2 层）临时覆盖。

### 第 2 步：写出你的第一个 `settings.json`

用户级配置位于 `~/.claude/settings.json`，这是个人所有项目的默认基线。新建并编辑它：

```bash
mkdir -p ~/.claude
cat > ~/.claude/settings.json <<'EOF'
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "sonnet",
  "language": "chinese",
  "cleanupPeriodDays": 30,
  "autoCompactEnabled": true,
  "alwaysThinkingEnabled": false
}
EOF
```

字段逐条解释：

- `$schema`：贴上后，VS Code / Cursor 编辑这个文件时会有**自动补全和字段校验**，强烈建议加上。
- `model`：默认模型，可填别名 `sonnet`/`opus`/`haiku`，也可填完整模型 ID。
- `language`：Claude 的回复语言，设为 `chinese` 后默认用中文作答（也会影响语音听写和终端标签标题，v2.1.121 起）。
- `cleanupPeriodDays`：超过该天数的不活跃会话记录会被清理（最小为 1，填 0 会被拒绝）。设 30 既保留近期历史，又控制磁盘占用。
- `autoCompactEnabled`：上下文逼近模型上限时自动压缩对话。新手建议保持 `true`，避免长会话突然"失忆"。
- `alwaysThinkingEnabled`：是否默认开启扩展思考（更慢但更深）。入门阶段先关掉，熟悉后再开。

**预期结果**：再次运行 `claude`，向它提问，应直接用中文回答；用 `/model` 查看时默认停留在 `sonnet`。

**常见问题**：

- **问：JSON 报错"Unexpected token"？** 多半是多了/少了逗号，或最后一个字段后多了逗号。`$schema` 已开启的话编辑器会直接标红。
- **问：`language` 写成 `zh` 没效果？** 取值需用全称 `chinese`（参考官方示例用 `japanese` 这种全称写法）。

### 第 3 步：自造状态栏——把模型、花费、改动量焊到终端底部

状态栏（status line）是 Claude Code 在交互界面底部显示的一行信息。默认很简陋，但它支持你用**任意脚本**接管：Claude Code 会把当前会话的 JSON 数据通过标准输入喂给你的脚本，你的脚本打印什么，底部就显示什么。

先确认数据格式。Claude Code 传给脚本的 JSON 大致长这样：

```json
{
  "model": { "id": "claude-sonnet-4-6", "display_name": "Sonnet" },
  "workspace": { "current_dir": "/home/you/myapp", "project_dir": "/home/you/myapp" },
  "version": "2.1.199",
  "cost": {
    "total_cost_usd": 0.0234,
    "total_duration_ms": 45120,
    "total_lines_added": 87,
    "total_lines_removed": 12
  }
}
```

接下来写一个解析脚本：

```bash
cat > ~/.claude/statusline.sh <<'EOF'
#!/usr/bin/env bash
input=$(cat)
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')
dir=$(echo "$input" | jq -r '.workspace.current_dir // ""' | sed "s|$HOME|~|")
printf "🤖 %-8s 💰 \$%.4f  ✎ +%s/-%s  📂 %s" \
  "$model" "$cost" "$added" "$removed" "$dir"
EOF
chmod +x ~/.claude/statusline.sh
```

然后把它挂到配置里。编辑 `~/.claude/settings.json`，增加 `statusLine` 字段：

```json
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "sonnet",
  "language": "chinese",
  "cleanupPeriodDays": 30,
  "autoCompactEnabled": true,
  "alwaysThinkingEnabled": false,
  "statusLine": {
    "type": "command",
    "command": "bash ~/.claude/statusline.sh",
    "padding": 0
  }
}
```

**预期结果**：重新进入 `claude`，终端底部出现一行类似：

```
🤖 Sonnet  💰 $0.0234  ✎ +87/-12  📂 ~/myapp
```

随着对话推进，金额与增删行数会**实时跳动**——这就是你最直观的"开销仪表盘"。

**常见问题**：

- **问：底部一片空白？** 多半是脚本没给执行权限或 `jq` 没装。先在终端手测：`echo '{"model":{"display_name":"X"},"cost":{"total_cost_usd":0}}' | bash ~/.claude/statusline.sh`，能正常输出说明脚本本身没问题。
- **问：想显示上下文占用百分比怎么办？** JSON 里还带了 `transcript_path`，进阶脚本可读取该文件估算上下文占比。入门阶段先用上面的"四件套"，稳定后再扩展。
- **问：状态栏想换颜色？** 在 `printf` 里用 ANSI 转义码即可，例如 `\033[36m`（青色）……`\033[0m`（复位）。

### 第 4 步：用 `/config` 与 `/model` 在会话里微调

不想每次改文件也可以：进入 `claude` 后输入 `/config` 打开交互式配置面板，能可视化切换主题、是否自动压缩、是否推送通知等，**改动会写回 `~/.claude/settings.json`**；输入 `/model` 可临时切模型，输入 `/output-style` 可切换输出风格（如更简洁或更详尽）。

## 实战案例：在空目录里跑通"第一个项目"，验证配置生效

把前面学的串起来，用一个最小闭环验证：建项目 → 用配置好的环境 → 让 Claude 生成并测试代码 → 状态栏反映改动量。

```bash
# 1) 建项目目录与团队共享配置（第 4 层，可提交 Git）
mkdir -p hello-cc/.claude && cd hello-cc
cat > .claude/settings.json <<'EOF'
{
  "model": "sonnet",
  "language": "chinese"
}
EOF

# 2) 进入 Claude Code
claude
```

在交互界面输入一句需求（直接喂文件、给清楚验收标准是高效提问的要诀）：

> 在当前目录用 Python 写一个 `adder.py`，提供 `add(a, b)` 函数，并用 `assert` 写 3 条测试。写完直接运行 `python3 -c "import adder; adder.add(1,2)"` 验证。

**预期结果**：

- Claude 用中文回应，创建 `adder.py` 并自动执行验证命令。
- 执行前会请求权限——首次可逐条放行；想免打扰，可把 `Bash(python3 *)` 加入项目 `settings.json` 的 `permissions.allow`（详见官方权限文档）。
- 终端底部状态栏的 `✎ +N/-M` 随文件写入而增长，`💰` 金额同步上升。

完成后，退出 `claude`，查看文件：

```bash
cat adder.py
```

至此，你的配置（中文、Sonnet、状态栏、自动压缩）在真实任务里全部跑通。

## 工作流程图

```mermaid
flowchart TD
    A[启动 claude] --> B{读取五层配置}
    B -->|优先级由高到低| C1[托管设置 Managed]
    C1 --> C2[命令行参数]
    C2 --> C3[.claude/settings.local.json]
    C3 --> C4[.claude/settings.json 团队共享]
    C4 --> C5[~/.claude/settings.json 个人]
    C5 --> D[合并: 标量覆盖 数组拼接去重 deny最高]
    D --> E[会话按配置运行]
    E --> F[每轮更新会话JSON]
    F --> G[statusLine脚本接收JSON]
    G --> H[终端底部渲染: 模型/花费/改动量]
    H --> E
```

## 延伸阅读

- **权限配置**：`allow`/`ask`/`deny` 三态与 `Bash()` 通配规则——告别逐条放行。
- **输出风格自定义**：在 `~/.claude/output-styles/` 放 Markdown，定义专属回答范式。
- **扩展思考预算**：`thinkingBudgetTokens` 精确控制每次回复的思考开销。
- **托管设置进阶**：企业用 `policyHelper`、`requiredMinimumVersion` 做版本与策略下发。

## 训练营适用性评估

- **适用类型**：面向零基础开发者的"Claude Code 入门营 / 工程师提效训练营"第一课，建议紧接着上权限与记忆文件两节。
- **预计教学时长**：讲师演示 + 学员动手约 **60–75 分钟**（含写脚本与排错）。
- **难度**：★★☆☆☆（会改 JSON、会用终端即可）。
- **交付物**：每人一份可复用的 `~/.claude/settings.json` 与 `statusline.sh`。

## 参考来源

1. [Claude Code settings — 官方文档](https://code.claude.com/docs/en/settings) — 五层优先级、80+ 配置字段与 200+ 环境变量的权威出处。
2. [Customize your status line — 官方文档](https://code.claude.com/docs/en/statusline) — `statusLine` 字段、传入 JSON 数据结构的官方说明。
3. [claude-code-best-practice / claude-settings.md（v2.1.199, 2026-07-03）](https://github.com/shanraisshan/claude-code-best-practice/blob/main/best-practice/claude-settings.md) — 逐字段详解的社区维护参考，时效性强。
4. [Claude Code Status Line — Complete Guide（gist）](https://gist.github.com/AKCodez/ffb420ba6a7662b5c3dda2edce7783de) — 可用数据字段清单与脚本模板合集。
5. [Claude Code settings.json: Every Option Explained（2026）](https://www.explainx.ai/blog/claude-code-settings-json-complete-reference-2026) — 配置体系与实战片段的图文讲解。

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)