跳转到主要内容

Claude Code Statusline 配置:可用脚本、字段与排障

个人初版可用 /statusline 生成;想控制字段和缺值处理,就用手动脚本。先用模拟 JSON 跑出一行输出,再配置作用域,定位空白、旧值及 Windows 路径问题。

LaoZhang AI Team发布于更新于 21 分钟阅读
文章目录
Claude Code 状态栏快速生成与手动脚本接入的概念预览

配置 Claude Code statusline,直接的起点是在会话里输入 /statusline,告诉它你想看哪些信息。想自己维护代码,则在设置中添加 statusLine 命令:Claude Code 把会话 JSON 送到标准输入(stdin),脚本把状态栏文字写到标准输出(stdout)。先让模型、项目、分支和上下文用量稳定显示,再考虑主题、颜色或更多指标。官方状态栏文档说明了这两种设置方式。

选哪条路,取决于你想控制什么:

需求建议起点完成时应看到什么
给自己快速做一个状态栏/statusline 生成生成脚本和配置,底部出现所需信息
自己决定字段、缺值和输出格式手动配置下文的小脚本模拟输入能输出预期文字,再接入会话
团队使用同一份行为共享项目设置和仓库内脚本同事能运行相同路径,不依赖你的个人目录
需要主题、多行布局和可视化编辑选用第三方 formatter能配置所需布局,并接受相应依赖和数据访问

共享项目设置是配置的作用域,也可以使用手动脚本;它不是另一套状态栏协议。下面先给出个人设置的完整流程,再说明如何共享和排障。

用 /statusline 生成个人初版

在 Claude Code 会话中输入:

/statusline 显示当前模型、当前项目目录、Git 分支和上下文已用百分比。保持一行,缺少数据时显示“—”,不要把缺值当成 0。

Claude Code 会生成脚本并更新设置。生成后,查看它保存的脚本与命令路径,确认输出的是你需要的信息;成功信号是底部出现相应状态栏,而不只是收到“配置完成”的文字回复。官方说明允许用自然语言继续调整或清除状态栏。

当你想明确控制每个字段、让同事能复现,或者定位生成脚本的问题时,使用下面的手动方式。这里的命令和路径是给你在自己的环境中操作的示例。

手动配置:先把一份完整脚本跑通

这个例子显示模型、项目名、分支、上下文已用百分比和会话费用估算;收到有效的五小时或七天用量窗口时再追加相应段落。它只读取输入 JSON,并按需对输入目录执行只读 Git 查询,不访问网络、不读取凭据或会话记录。

前提是本机有可用的 Node.js。先在终端执行 node --version 确认解释器能启动;安装了 Claude Code 不代表机器上一定有独立的 node 命令。Git 是可选依赖:没有 Git、目录不可访问或查询失败时,分支显示“—”,其他段落照常输出。

会话 JSON 经本地 Node 脚本解析,输出状态栏纯文本的数据流概念示意

1. 保存脚本

macOS、Linux 可先创建个人脚本目录:

bash
mkdir -p "$HOME/bin"

把以下完整代码保存为 ~/bin/claude-statusline.cjs。Windows 也使用同一份 .cjs 文件,命令路径在后面的 Windows 小节调整。

js
const { readFileSync } = require("node:fs");
const { spawnSync } = require("node:child_process");

const object = (v) =>
  v !== null && typeof v === "object" && !Array.isArray(v) ? v : {};
const number = (v) => typeof v === "number" && Number.isFinite(v);
const text = (v) => typeof v === "string"
  ? v.replace(/[\x00-\x1f\x7f|]/g, " ").trim()
  : "";

let data = {};
try {
  data = object(JSON.parse(readFileSync(0, "utf8")));
} catch {
  console.error("statusline: 输入不是可解析的 JSON");
  process.stdout.write("状态数据不可读\n");
  process.exit(0);
}

const model = object(data.model);
const workspace = object(data.workspace);
const context = object(data.context_window);
const cost = object(data.cost);
const worktree = object(data.worktree);
const pathValue = (v) => typeof v === "string" && v.length ? v : "";
const directory = pathValue(workspace.current_dir) || pathValue(data.cwd);
const project = text(directory.split(/[\\/]/).filter(Boolean).pop()) || "—";

function git(args) {
  if (!directory) return "";
  const result = spawnSync("git", ["-C", directory, ...args], {
    encoding: "utf8", timeout: 500, maxBuffer: 4096,
    windowsHide: true
  });
  return !result.error && result.status === 0 ? text(result.stdout) : "";
}

let branch = text(worktree.branch);
if (!branch) {
  branch = git(["symbolic-ref", "--quiet", "--short", "HEAD"]);
  if (!branch) {
    const commit = git(["rev-parse", "--short", "HEAD"]);
    branch = commit ? `游离:${commit}` : "—";
  }
}

const parts = [
  text(model.display_name) || text(model.id) || "模型:—",
  `项目:${project}`,
  `分支:${branch}`,
  number(context.used_percentage)
    ? `上下文:${context.used_percentage.toFixed(1)}%` : "上下文:—",
  number(cost.total_cost_usd) && cost.total_cost_usd >= 0
    ? `估算:USD ${cost.total_cost_usd.toFixed(2)}` : "估算:—"
];

const windows = object(data.rate_limits);
const now = Date.now() / 1000;
for (const [key, label] of [["five_hour", "五小时"], ["seven_day", "七天"]]) {
  const window = object(windows[key]);
  if (number(window.used_percentage) &&
      number(window.resets_at) && window.resets_at > now) {
    parts.push(`${label}已用:${window.used_percentage.toFixed(1)}%`);
  }
}
process.stdout.write(parts.join(" | ") + "\n");

.cjs 让这份代码使用 Node 的 CommonJS 模块,不受项目 package.json 的模块类型影响。我们显式用 node 读取脚本,因此不需要给脚本加 chmod +x;直接把脚本路径当作可执行命令则有不同的解释器和权限要求。

普通 Git 分支不是当前 JSON 中的通用 git.branch 字段。这份脚本先采用可用的 worktree.branch,否则通过 git -C 查询 输入提供的目录,避免误显示终端当前目录的分支。游离 HEAD 显示短提交号;新仓库尚未提交但已有分支名时,仍能显示该分支。它不查询未提交文件,也不把分支名当成“工作区干净”的证明。Git 子进程设置了超时,查询失败会退回“—”;这不是整条状态栏的耗时保证。

2. 用模拟 JSON 确认输出

在当前目录新建 statusline-demo.json,内容如下。这里的项目路径、用量和费用都是虚构数据;resets_at 设为 2100 年的时间戳,便于离线演示未过期窗口。

json
{
  "model": {"id": "demo-model", "display_name": "Claude 演示模型"},
  "workspace": {"current_dir": "/demo/demo-app"},
  "worktree": {"branch": "feature/demo"},
  "context_window": {"used_percentage": 42},
  "cost": {"total_cost_usd": 0.18},
  "rate_limits": {
    "five_hour": {"used_percentage": 0, "resets_at": 4102444800}
  }
}

macOS、Linux 在该文件所在目录执行:

bash
node "$HOME/bin/claude-statusline.cjs" < statusline-demo.json

预期输出是一行纯文本:

Claude 演示模型 | 项目:demo-app | 分支:feature/demo | 上下文:42.0% | 估算:USD 0.18 | 五小时已用:0.0%

注意最后的 0.0%:这是输入明确给出的数值 0。把 used_percentage 改成 null,上下文会显示“—”;删掉 five_hour 或把它的 resets_at 改为已经过去的时间,五小时段落会消失。它们都不意味着“已用 0%”或“没有限额”。

本例代码已用合成 JSON、缺值与类型变化、过期时间以及隔离的 Git 仓库做离线检查。这里的预期输出只验证脚本处理,不代表真实 Claude Code 界面、Windows 客户端或账户用量已经实测。

3. 添加 statusLine 设置

个人跨项目使用时,把下面的键合入用户设置文件 ~/.claude/settings.json。保留已有键,不要把整份设置覆盖成这个片段。

json
{
  "statusLine": {
    "type": "command",
    "command": "node \"$HOME/bin/claude-statusline.cjs\""
  }
}

type 和 command 描述如何启动脚本,主状态栏的 stdout 是显示文字,不要求返回 { "text": "..." } 一类 JSON 对象。错误说明放在 stderr,避免污染显示。当前配置项说明还提供 padding、refreshInterval 和 hideVimModeIndicator 等可选项;第一版不必全加。

修改命令会立即触发运行;只编辑脚本文件时,要等下一个刷新事件。接入后的成功信号是模型和项目等段落出现在底部,并在后续会话变化时更新。第一次响应之前,上下文或用量可能尚无数据,显示“—”不等于安装失败。

字段怎么选,哪些值不能互相替代

日常先保留能帮你判断“在哪个项目、用哪个模型、上下文还够不够”的信息。费用、套餐窗口和缓存各有口径,不能把它们混成同一个使用率。官方完整 JSON 说明列出了当前字段和出现条件。

想显示的信息当前字段或获取方式读数含义与缺值处理
模型名称model.display_name,回退到 model.idmodel 是对象,不能当作平面字符串
当前目录workspace.current_dir 或 cwdworkspace.project_dir 是启动目录,可能与当前目录不同
普通分支对输入目录执行只读 Git 查询没有通用 git.branch;特定 worktree 会话可有 worktree.branch
上下文已用比例context_window.used_percentage最新响应对应的当前上下文;可能为 null,数值 0 应保留
会话费用估算cost.total_cost_usd客户端按模型价格估算的会话成本,不是实际账单
五小时、七天用量rate_limits.five_hour、seven_day其中 used_percentage 表示已用,resets_at 单位是 Unix 秒

上下文用量不是累计消耗,也不是套餐余额

context_window.current_usage 在第一次 API 响应前、以及 /compact 后尚未收到下一次响应时,可能为 null,百分比也可能暂时缺失。当前输入 token 总量包含 input_tokens、cache_creation_input_tokens 和 cache_read_input_tokens;used_percentage 依据这些输入计算,不把输出 token 加进去。

因此,不能把当前上下文 token 除以一个自设的套餐额度,算出“订阅还剩多少”。/context 还会估算新加入但尚未发送的内容,它显示的用量可能高于状态栏的最近一次响应值;两处数字有差异不一定是脚本错误。上下文与更新口径见官方说明。

费用估算不能确认扣款或付费账户

cost.total_cost_usd 可以帮你观察会话成本变化,但它是客户端估算,既不证明谁承担账单,也不代表订阅实际扣了相同金额。累计运行时间 total_duration_ms 与 API 等待时间 total_api_duration_ms 的单位都是毫秒;显示秒数时要除以 1,000。当前文档还说明,从 v2.1.211 起,/clear 开始的新会话会从 0 重新计算成本,旧版本行为不同。成本字段说明给出了适用口径。

套餐窗口和网关支出有独立条件

当前 rate_limits 只在 claude.ai Pro/Max 订阅或设有支出上限的 Claude apps gateway 路线下、首次 API 响应后出现。五小时、七天和 spend_limit 窗口可以分别缺失,过了各自 resets_at 后会被移除。某个段落消失时,不能推断额度为零、额度无限或 API key 出错。用量字段条件以官方文档为准。

网关的 spend_limit.used_percentage 可超过 100%,要求 v2.1.251;可选的 used_usd、limit_usd 和 period 要求客户端及网关均达到 v2.1.284。美元金额大约每五分钟独立更新,可能落后于百分比,关闭非必要流量时也可能不提供这些可选值。不要通过改组织流量策略来“补齐”状态栏。

缓存指标也应单独看:prompt_cache 从 v2.1.251 起提供主对话统计,首次响应后才出现,hit_ratio 是 0–1 或 null,不包含子代理调用。缓存未命中可能来自压缩或工具结果重建等多种情况,单个低值不能证明提示词写错。如果第一行已经够用,可以不显示它。

设置作用域决定谁会使用这条命令

个人偏好通常放用户设置;仅当前项目自己使用的覆盖放项目本地设置;要团队共同维护时,才把脚本和共享设置一起提交。常见位置如下,Git worktree、本地主目录归属及 Windows 情况可能改变实际本地设置位置,先看客户端加载了哪些文件。官方设置文档说明了作用域和路径规则。

作用域常见文件或入口适用场景
用户~/.claude/settings.json个人跨项目默认值
项目本地.claude/settings.local.json自己对一个项目的覆盖,不作为团队标准
共享项目.claude/settings.json随仓库共享的行为及非私人路径
命令行--settings启动时的临时覆盖
托管组织管理员提供组织控制的配置

同一个键的优先级从高到低是:托管、命令行、项目本地、共享项目、用户。未指定的键仍可沿用较低层设置;不能把所有配置理解成整份文件覆盖,列表等类型还有自己的合并规则。

例如,团队把上面的脚本保存为仓库内 tools/claude-statusline.cjs,共享设置可以使用:

json
{
  "statusLine": {
    "type": "command",
    "command": "node \"./tools/claude-statusline.cjs\""
  }
}

同事需要有可用的 Node.js,并从对应项目目录启动;目录变化后重新确认相对路径。提交前检查脚本行为和依赖,个人绝对路径、凭据与私人状态不要写进共享文件。/status 的 Setting sources 可以查看已加载的设置文件,但它不会逐键告诉你究竟是哪一份提供了 statusLine。

更新慢、值不变:先分清触发与数据来源

状态栏会在启动或恢复会话、助手消息、/compact 完成、权限模式或 Vim 状态变化等事件后运行。更新有 300 毫秒防抖,命令改变会立即运行;新更新会取消仍在运行的旧脚本。限额、缓存时间戳到期,以及配置的计时器也可以触发刷新。运行生命周期见官方文档。

所以,“编辑脚本后立刻没变化”和“每次输出都卡住”应分开处理:前者等下一次触发,后者先查看脚本是否访问网络、扫描大文件或执行慢命令。stdout 是被捕获的输出,不是直接连接终端的 TTY;自适应宽度可读客户端提供的 COLUMNS,不要依赖 tput cols 一定能读到终端宽度。

如果你确实显示时钟、随时间变化的外部状态,才考虑给已有对象加上:

json
"refreshInterval": 10

这是 10 秒,当前最小值为 1 秒。定时重跑只保证脚本重新执行,不保证上游用量也获得了新测量。慢脚本不会靠更频繁刷新变快;若引入缓存,应按会话和目录区分,避免切项目后仍显示上个仓库的结果。

Windows:先验证解释器和路径

当前官方文档说明,Windows 安装 Git Bash 时会使用它,否则使用 PowerShell;不能把所有 Windows 环境都当成同一种 shell。下面给 Node 脚本指定完整路径,减少相对目录与 ~ 展开的差异:Windows 配置示例。

json
{
  "statusLine": {
    "type": "command",
    "command": "node \"C:/Users/你的用户名/bin/claude-statusline.cjs\""
  }
}

把用户名换成自己的实际目录;如果 node 不在客户端能使用的 PATH 中,命令里的解释器也要改成带引号的绝对路径。路径内有空格时保留引号。JSON 中反斜杠需要转义,这里用正斜杠避免混淆。

在 PowerShell 中,可在模拟文件所在目录先测试:

powershell
Get-Content -Raw -Encoding UTF8 ./statusline-demo.json | node "C:/Users/你的用户名/bin/claude-statusline.cjs"

成功时应看到前面那行模拟输出。若乱码或空白,核对当前 PowerShell/终端的 UTF-8 编码与 Node 路径,再检查 Claude Code 实际使用的命令。以上是依据当前文档编写的 Windows 操作示例,未作 Windows 客户端实测。

需要主题和布局时,再选第三方 formatter

当你要多行组件、Powerline 主题、可视化调整和导入导出布局时,可以考虑 ccstatusline。它的项目 README 给出的快速入口是:

bash
npx -y ccstatusline@latest

这是下载并运行第三方包,所需 npm/Node 环境与自行维护一个 .cjs 脚本不同。初始 TUI 提供的 Pinned global install 会把选定版本安装到全局,并写入固定版本的命令;固定安装后,ccstatusline 可打开 TUI。工具自身的配置位于 ~/.config/ccstatusline/settings.json,不要与 Claude 的设置文件混淆。

选择它的理由是已有的主题和布局功能,不是未经验证的“最快”或“最安全”。一些用量组件会查找凭据或 macOS Keychain、直接访问 Anthropic usage API;部分指标读取会话记录或缓存,服务健康组件也使用网络数据。因此,不能把整个工具说成只读官方 stdin JSON、全程离线。按自己要启用的组件判断依赖;这里未安装或运行该工具,也未读取任何凭据或真实使用数据。

如果只需要前面几个字段,保留小脚本就能完成任务。要停用自定义状态栏,移除对应设置中的 statusLine 键,或让 /statusline 清除它;保留其他设置。

空白、缺值、旧数据怎么排查

从同一命令、输入输出、设置来源与终端显示定位状态栏问题的概念示意

先在 Claude Code 外,用模拟文件运行 设置中的同一条命令。这一步把脚本、解释器和路径问题与客户端设置问题分开。

症状先看什么下一步
终端就无法运行解释器、脚本文件与路径引号修正命令;明确用 node 读取文件时无需加执行位
有日志但没有状态文字stdout 与 stderr 是否写反把显示结果写 stdout,诊断信息写 stderr
显示“状态数据不可读”送入脚本的 JSON 是否完整有效先用文中的模拟文件测试,修正解析或传入方式
有状态栏,但上下文是“—”首次响应、压缩后的缺值、字段名等适用的新响应;读 used_percentage,不要读旧 percentage
分支是“—”输入目录、Git 是否可用、是否在仓库内在同一目录验证只读查询;不要凭空加 git.branch
五小时或七天段落消失路线条件、首次响应和窗口是否过期视为尚未提供有效窗口,不推断为 0 或无限
只有旧值,或刷新很慢是否有触发、脚本耗时及缓存归属先简化慢逻辑;外部时间数据才考虑定时刷新
脚本能跑,会话里完全没有设置来源、拒绝条目和策略限制查看实际加载文件与客户端诊断,再核对下文规则
纯文本正常,颜色或链接异常终端支持与可用宽度先恢复纯文本,再逐项加 ANSI 或 OSC 8 特性

脚本在终端通过后仍不运行,尤其要区分以下两类策略。官方策略条目规定:

  • 托管 disableAllHooks=true,或工作区未受信任时,所有自定义 statusLine 都关闭。
  • allowManagedHooksOnly、生效的非托管 disableAllHooks=true,或 --safe-mode 会把可运行的配置收窄到托管设置。管理员部署的托管状态栏仍可以运行,个人、项目或插件设置则可能无警告地被跳过。

允许某个托管插件的 hooks,不代表该插件的 statusline 也自动获准;状态栏配置本身必须来自托管设置。遇到组织控制时,把症状和命令测试结果交给管理员核对,不把关闭策略、改信任状态或删除整份设置当作通用修复。

当前客户端会报告部分无效 JSON 或已知无效值,claude doctor 可帮助查看被拒绝的配置条目,不能假设所有错误都静默忽略。此外,帮助或权限提示期间状态栏可能暂时隐藏,通知与窄终端会占用或截断行,不能仅凭一次没看见就判定脚本失效。官方排障说明也列出了这些显示条件。

常见问题

statusline、/statusline 和 statusLine 有什么区别?

statusline 是状态栏功能的常见称呼,/statusline 是会话内的设置命令,statusLine 是 JSON 设置键。写配置时大小写必须准确;它接收 stdin JSON,输出显示文字。

状态栏本身会额外消耗模型 token 吗?

读取已提供的 JSON 并打印文字不会产生一次新的模型请求。本文小脚本也没有网络调用。第三方工具或自定义脚本可能另外访问服务,须按具体代码和组件判断,不能从“statusline”这个名称推出所有实现都离线。

为什么费用显示 0,上下文却不是 0?

它们是不同指标:上下文是当前输入占用,费用是会话成本估算。实际数值 0 应保留,缺少数据则显示“—”;成本估算也不能用来确认扣款或订阅余额。官方字段口径解释了两者的区别。

自定义状态栏只能有一行吗?

不是。官方支持多行、ANSI 颜色和 OSC 8 链接,效果取决于终端能力与空间;例如 macOS Terminal.app 不支持可点击的 OSC 8 链接。本例保持一行是为了便于验证和扫读,不是协议限制。显示能力说明见官方文档。

参考来源4

本文引用的外部页面,按正文出现顺序排列。最后更新于 2026年10月8日。

  1. 1.官方状态栏文档code.claude.com/docs/en/statusline
  2. 2.当前配置项说明code.claude.com/docs/en/settings-reference
  3. 3.官方设置文档code.claude.com/docs/en/settings
  4. 4.ccstatuslinegithub.com/sirmalloc/ccstatusline
更多 Claude Code
Claude Code 泄露事件与公开模型、账号合同现实并列展示
Claude Code

Claude Code 源码泄露:封号风险、当前模型和帐号逻辑说明(2026)

Claude Code 在 2026 年 3 月确实发生过源码暴露。Anthropic 对 Axios 表示,这是一场发布打包错误,不是外部入侵,而且没有暴露客户数据或凭证。真正更难的部分,是把这件事和真实封号边界、当前模型合同,以及 Claude/Console 账号逻辑拆开。

15 分钟