如何自定义 Claude Code 状态栏

内容来源：alexop.dev。https://alexop.dev/posts/customize_claude_code_status_line/
原题：How to Customize Your Claude Code Status Line
原发布时间：2025-12-14

在终端中直接显示 Claude Code 的模型名称、上下文用量和成本，并逐步创建自定义状态栏脚本。

兼容性说明（核对于 2026-07-20）：当前状态栏文档直接提供 context_window.used_percentage，所以新脚本不必手工计算百分比。设置现在会自动重新加载，cost.total_cost_usd 则要求 Claude Code v2.1.211 或更高版本。下文保留历史原文中的实现。

你是否曾经看着 Claude Code，却不知道当前实际使用的是哪个模型，或者上下文窗口已经消耗了多少？这些信息默认隐藏起来，但可以直接显示在终端中。

自定义状态栏能够让重要信息一目了然：

[Opus] 上下文：12%

不必中断工作，就能看到当前模型和上下文用量。下面介绍配置方法。

状态栏如何工作

Claude Code 会通过标准输入把 JSON 数据传给状态栏脚本。脚本处理数据，再输出任何希望显示的文本。

Claude Code 状态栏数据流

JSON 包含模型信息、Token 计数、成本和工作区详情等全部常用数据。

第一步：创建状态栏脚本

在 ~/.claude/statusline.sh 创建新文件：

#!/bin/bash
input=$(cat)

MODEL=$(echo "$input" | jq -r '.model.display_name')
INPUT_TOKENS=$(echo "$input" | jq -r '.context_window.total_input_tokens')
OUTPUT_TOKENS=$(echo "$input" | jq -r '.context_window.total_output_tokens')
CONTEXT_SIZE=$(echo "$input" | jq -r '.context_window.context_window_size')

TOTAL_TOKENS=$((INPUT_TOKENS + OUTPUT_TOKENS))
PERCENT_USED=$((TOTAL_TOKENS * 100 / CONTEXT_SIZE))

echo "[$MODEL] 上下文：${PERCENT_USED}%"

脚本从标准输入读取 JSON，使用 jq 提取相关字段、计算百分比，再输出格式化字符串。

第二步：添加执行权限

chmod +x ~/.claude/statusline.sh

第三步：配置 Claude Code

把状态栏配置加入 ~/.claude/settings.json：

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  }
}

如果文件中已有其他设置，把 statusLine 区块与现有配置并列加入。

└── .claude/
    ├── statusline.sh  自定义脚本
    └── settings.json  配置文件

第四步：重新启动 Claude Code

关闭并重新打开 Claude Code，新状态栏应该就会出现。

可用变量

脚本收到的 JSON 包含以下字段：

变量	说明
`model.id`	完整模型 ID，例如 `claude-opus-4-5-20251101`
`model.display_name`	简称，例如 `Opus`
`context_window.total_input_tokens`	已使用的输入 Token
`context_window.total_output_tokens`	已使用的输出 Token
`context_window.context_window_size`	最大上下文容量
`cost.total_cost_usd`	会话成本，美元
`cost.total_duration_ms`	总运行时间
`workspace.current_dir`	当前目录

添加成本追踪

想查看当前会话花了多少钱，可以扩展脚本：

#!/bin/bash
input=$(cat)

MODEL=$(echo "$input" | jq -r '.model.display_name')
INPUT_TOKENS=$(echo "$input" | jq -r '.context_window.total_input_tokens')
OUTPUT_TOKENS=$(echo "$input" | jq -r '.context_window.total_output_tokens')
CONTEXT_SIZE=$(echo "$input" | jq -r '.context_window.context_window_size')
COST=$(echo "$input" | jq -r '.cost.total_cost_usd')

TOTAL_TOKENS=$((INPUT_TOKENS + OUTPUT_TOKENS))
PERCENT_USED=$((TOTAL_TOKENS * 100 / CONTEXT_SIZE))

printf "[%s] 上下文：%d%% | $%.2f" "$MODEL" "$PERCENT_USED" "$COST"

现在会看到类似内容：[Opus] 上下文：12% | $0.45

💡 快速替代方式

使用 /statusline 斜杠命令进行引导式配置。只需输入 /statusline show the model name and context usage percentage，Claude Code 就会自动创建配置。

故障排查

状态栏没有显示？

1、检查是否已经安装 jq：macOS 运行 brew install jq，Linux 运行 apt install jq
2、确认脚本可执行：ls -la ~/.claude/statusline.sh
3、修改后重新启动 Claude Code

手工测试脚本：

echo '{"model":{"display_name":"Opus"},"context_window":{"total_input_tokens":1000,"total_output_tokens":500,"context_window_size":200000}}' | ~/.claude/statusline.sh

预期输出：[Opus] 上下文：0%

💡 依赖项

状态栏脚本依赖 jq 解析 JSON。没有安装时，脚本会静默失败。

继续扩展

状态栏只是 Claude Code 自定义体系的一部分。熟悉这类脚本后，还可以探索：

• 使用通知 Hooks，在 Claude 需要输入时收到桌面提醒
• 使用斜杠命令自动执行重复任务
• 阅读 Claude Code 完整功能技术栈，了解 MCP、Skills 和子智能体

状态栏脚本所采用的模式，也就是从标准输入读取 JSON，再输出格式化文本，同样是 Claude Code 许多扩展功能的基础。