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