Claude Code 状态栏怎么配置：/statusline 一句话生成，显示模型、上下文占用和 5 小时 / 7 天用量

本文根据 Claude Code 官方文档《Customize your status line》《Commands》整理，资料核对于 2026-11-05。配图为本站整理的示意图，不是界面截图。本站（bigolab.com）不是 Anthropic 官方网站。

适用于谁

• 想在 Claude Code 界面底部一直看到当前模型、上下文用了多少的人；
• 搜「claude hud」「claude code token 速度」，想知道状态栏能显示什么的人；
• 想知道 5 小时、7 天用量能不能放进状态栏的订阅用户。

结论先说

1. 状态栏是你自己配的一行（或多行）文字：Claude Code 每次更新时运行你设定的命令，把会话数据以 JSON 通过标准输入（stdin）传给它，命令打印什么就显示什么。
2. 最省事的做法是 /statusline：官方说它接受自然语言描述，会在 ~/.claude/ 下生成脚本并自动改好设置。
3. 手动配置在 settings.json 里加 statusLine 字段，type 设为 "command"，command 指向脚本或内联命令。
4. 状态栏在本地运行，不消耗 API token。
5. 能读到的数据包括模型、上下文占用百分比、会话花费、5 小时与 7 天限额的使用百分比（仅订阅用户）、工作目录等。官方字段表里没有「token 速度」这一项。

图：本站根据 Claude Code 官方文档：Customize your status line 整理的示意图

一、最快的做法：/statusline

在会话里输入：

text
/statusline show model name and context percentage with a progress bar

官方示例用英文，你也可以用中文描述想显示的内容。命令会在 ~/.claude/ 下生成脚本，并更新设置。如果提示你批准文件编辑，批准即可。官方对这个命令的描述是：描述你想要的内容，或者不带参数运行，让它根据你的 shell 提示符自动配置。

想去掉状态栏，运行 /statusline 并告诉它删除，例如 /statusline delete、/statusline clear、/statusline remove it；也可以手动删掉 settings.json 里的 statusLine 字段。

二、手动配置：settings.json

在用户设置 ~/.claude/settings.json（Windows 上是用户目录下的 .claude\settings.json）或项目设置里加：

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

可选字段：

• padding：额外的水平空白（字符数），默认 0；
• refreshInterval：每隔 N 秒再运行一次命令，最小是 1。适合显示时间之类随时间变化的内容，不设置则只在事件触发时运行；
• hideVimModeIndicator：设为 true 时去掉界面自带的 -- INSERT -- 提示，适合你的脚本自己显示 vim 模式的情况。

command 也可以直接写内联命令，官方示例用 jq 读 JSON：

json
{
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'"
  }
}

官方还给了完整的逐步例子：脚本从标准输入读到 JSON，用 jq 取出模型名、目录和上下文百分比后打印，再用 chmod +x 设为可执行。保存设置后，Claude Code 会自动重新加载并立即运行脚本。更多配置项的位置和优先级见 /guides/claude-code-settings-json。

三、脚本能读到哪些数据

图：本站根据 Claude Code 官方文档：Customize your status line 整理的示意图

官方字段表里，常用的有：

• model.id、model.display_name：模型标识和显示名；
• workspace.current_dir、workspace.project_dir：当前目录和启动目录；
• context_window.used_percentage、remaining_percentage：上下文已用、剩余的百分比；
• context_window.context_window_size：窗口大小，默认 200000，扩展上下文的模型是 1000000；
• cost.total_cost_usd：会话的估算花费，官方说是在本地按标价计算的，可能与实际账单不同；
• cost.total_duration_ms、cost.total_api_duration_ms：运行时长、等待 API 的时长；
• cost.total_lines_added、total_lines_removed：改动的行数；
• rate_limits.five_hour.used_percentage、rate_limits.seven_day.used_percentage：5 小时、7 天窗口的使用百分比；resets_at 是重置时间的 Unix 秒数；
• effort.level、fast_mode、thinking.enabled：思考强度、快速模式、是否启用扩展思考；
• session_name、session_id、version、output_style.name、vim.mode、agent.name、worktree.、pr. 等。

要注意几点：

• context_window.used_percentage 只按输入 token 算（输入 + 缓存创建 + 缓存读取），不含输出；
• 状态栏读到的是上一次 API 响应的计数，而 /context 会额外估算之后新增的消息，所以 /context 的数字有时更高；
• rate_limits 只对 claude.ai 的 Pro、Max、Ultra 订阅用户提供，并且要等第一次 API 响应之后才有；用 API 密钥时没有这个字段，脚本里要做缺省处理（官方示例用 // empty）；
• 字段在第一次 API 响应前可能是 null，用 // 0 之类写缺省值，否则会显示 -- 或空白。

订阅用量怎么看、什么时候重置，见 /guides/claude-usage-limits。额度不够、想换更大的订阅时，可以了解 /chongzhi/claude-code。

四、什么时候更新

官方说脚本在会话开始（包括恢复）时运行一次，之后在这些时刻再运行：有新的助手消息、/compact 完成、权限模式变化、vim 模式切换、你改了 command、refreshInterval 到时，以及限额窗口或提示缓存到期。更新有 300 毫秒的防抖；如果脚本还在跑时又有新更新，旧的脚本会被取消。

输出方面，脚本可以打印多行（每个 echo 一行）、用 ANSI 转义码加颜色、用 OSC 8 转义序列做可点击的链接（需要终端支持，如 iTerm2、Kitty、WezTerm）。脚本里读不到终端宽度，用环境变量 COLUMNS 和 LINES。

五、Windows 怎么配

官方说 Windows 上，装了 Git Bash 就通过 Git Bash 运行状态栏命令，没装就用 PowerShell。Git Bash 会吃掉未加引号的反斜杠，所以 command 里的路径要用正斜杠，~ 也可以用。

用 PowerShell 脚本的写法：

json
{
  "statusLine": {
    "type": "command",
    "command": "powershell -NoProfile -File C:/Users/username/.claude/statusline.ps1"
  }
}

官方给的 statusline.ps1 例子读 $input，用 ConvertFrom-Json 取出 cwd、model.display_name 和 context_window.used_percentage 后 Write-Host。装了 Git Bash 的话，也可以直接写成 "command": "~/.claude/statusline.sh" 运行 Bash 脚本。Windows 上 Git 的说明见 /guides/claude-code-install-methods-git-npm-official。

六、状态栏不显示，按顺序查

官方的排查清单：

• 脚本是否可执行：chmod +x ~/.claude/statusline.sh；
• 脚本是否把内容输出到 stdout，而不是 stderr；
• 手动跑一遍脚本，看有没有输出；
• Windows 且装了 Git Bash 时，路径里的反斜杠是不是被吃掉了；
• 脚本必须以退出码 0 结束才会显示，非 0 或没有输出会让状态栏变空白；脚本太慢会阻塞更新；
• 没接受工作区信任对话框时状态栏保持空白（claude --debug 会打印 Status line command skipped: workspace trust not accepted），接受后重启；
• 企业管理设置里的 allowManagedHooksOnly 或 disableAllHooks 可能让自定义状态栏失效；
• 用 claude --debug 查看脚本 stderr 和退出码。

另外官方提到：配了自定义状态栏之后，界面底部原来的多数键盘提示（如 esc to interrupt、? for shortcuts）不再显示。

现成的第三方项目

官方文档在「Tips」里提到两个社区项目，ccstatusline 和 starship-claude，提供带主题的现成配置。这是官方的提及，不是官方产品，装之前建议先看一眼代码，安全习惯见 /guides/ai-coding-security-secrets-permissions。

常见问题

Q：状态栏会消耗我的额度吗？

官方说状态栏在本地运行，不消耗 API token。

Q：能显示 git 分支吗？

普通会话的字段表里没有当前 git 分支名（只有 worktree 会话才有 worktree.branch，另有 pr.*），官方的例子是在脚本里自己运行 git，并提醒 git status 这类命令可能拖慢状态栏，可以缓存。

Q：能显示每秒多少 token 吗？

官方字段表里没有这一项。

相关教程

• /guides/claude-code-slash-commands：斜杠命令速查
• /guides/claude-code-context-compact：上下文满了怎么办

参考资料

• Claude Code 官方文档：Customize your status line — https://code.claude.com/docs/en/statusline
• Claude Code 官方文档：Commands — https://code.claude.com/docs/en/commands