MemoryLake
返回全部文章
Tutorial2026 年 11 月 19 日·10 分钟阅读

Claude Code 状态栏可以显示什么?脚本接收哪些会话字段、如何显示上下文窗口使用情况,以及为什么在后台代理运行时它会停止更新 (2026)

你为 Claude Code 添加了一个状态栏,这样你就可以在不每隔几分钟输入 /context 的情况下查看上下文窗口的占用情况。在普通会话中它表现良好。但当你开始一项较长的任务,由 Claude 协调多个后台子代理(subagents)时,屏幕底部的数字在很长一段时间内停止了变动。当你最终运行 /context 时,它显示的数值比状态栏显示的要高。

这两种行为都在文档中有记载。Anthropic 的状态栏页面指出:“当主会话处于空闲状态时(例如协调器等待后台子代理时),事件驱动的触发器可能会进入静默状态。”关于数值差异:“状态栏报告的是上一次 API 响应的计数,而 /context 则增加了自该响应以来添加的消息估算值,因此在下一次响应之前,/context 的读数可能会更高。”

本指南涵盖了状态栏是什么、如何设置、你的脚本会接收哪些会话字段、如何准确显示上下文窗口使用情况、状态栏何时更新以及为什么会停止更新、什么会导致它消失,以及如何利用它显示的信息来决定何时在会话之外保存上下文。

什么是状态栏

文档用一句话描述了它:“状态栏是 Claude Code 底部的一个可定制栏,它运行你配置的任何 shell 脚本。它通过 stdin 接收 JSON 会话数据,并显示脚本打印的任何内容”。

它列出了人们使用它的原因:

  • 在工作时“监控上下文窗口使用情况”。
  • “追踪会话成本”。
  • 在“跨多个会话工作”时区分会话。
  • 保持 git 分支和状态可见。

在构建状态栏之前,有两个细节值得了解。首先,它不消耗模型使用成本:“状态栏在本地运行,不消耗 API token。”其次,它与内置页脚并排显示,而不是替换它,尽管文档指出,使用自定义状态栏后,Claude Code 会停止显示某些页脚提示。

如何设置状态栏

有两种途径。

让 Claude 编写。 文档说明:“/statusline 命令接受描述你想要显示内容的自然语言指令。Claude Code 会在 ~/.claude/ 中生成一个脚本文件,并自动更新你的设置”。你描述需求(例如模型名称和上下文进度条),然后批准文件编辑即可。

自己编写。 在 ~/.claude/settings.json 的用户设置或项目设置中添加 statusLine 字段。将其类型设置为 command,并将该命令指向一个脚本或内联 shell 命令。

三个可选字段决定了输出效果:

  • padding 添加水平间距。
  • refreshInterval 按定时器重新运行命令,下文将详细介绍。
  • hideVimModeIndicator 当你的脚本显示 vim 模式文本时,隐藏内置的文本。

要移除状态栏,文档建议你可以运行 /statusline 并要求它移除或清除状态栏,或者直接从设置中删除该字段。

你的脚本接收哪些会话字段

每次运行时,你的脚本都会在 stdin 上接收到一个 JSON 对象。文档中的表格很长,字段主要分为几组。

模型与努力程度。 model.id 和 model.display_name,以及 effort.level 和 thinking.enabled。

位置信息。 workspace.current_dir、workspace.project_dir(启动 Claude Code 的目录)、添加的目录、来自 origin 远程仓库的身份信息,以及当你处于工作树中时的 worktree 详情。

会话身份。 session_id(描述为“唯一会话标识符”)和 session_name(使用你设置的自定义名称或 AI 生成的会话标题)。还有正在处理的提示词的 prompt_id 以及 transcript_path(“对话转录文件的路径”)。

上下文。 context_window 对象,将在下一节详细介绍。

成本与时间。 cost.total_cost_usd,文档将其描述为客户端计算的估算值,“可能与你的实际账单有所不同”,此外还有总时长以及添加和删除的行数。

限制。 速率限制窗口及其重置时间的字段,以及一个包含缓存是否命中的 prompt 缓存对象。

拉取请求 (PR)。 当前分支的打开 PR 编号、URL 和评审状态。

某些字段在适用之前是不存在的。文档的故障排除部分提到:“在第一次 API 响应完成之前,字段可能为 null,因此请在脚本中使用备选值处理 null 值”。

如何显示上下文窗口使用情况

监控上下文是文档列出的首要用途,页面详细解释了它包含的内容。

它描述了“来自最近一次 API 响应的实时上下文窗口”。它包括最大窗口大小、输入和输出的总和、按类别划分的明细,以及两个预计算字段:used_percentage 和 remaining_percentage。

关键规则在于计算方式。文档指出:“used_percentage 字段仅根据输入 token 计算:input_tokens + cache_creation_input_tokens + cache_read_input_tokens。它不包括 output_tokens。”

如果你根据明细自行计算数值,文档建议“使用相同的仅限输入公式以匹配 used_percentage”。对于大多数脚本,其建议更简单:“使用 used_percentage 以获得最简单、准确的上下文状态。”

有一个字段需要谨慎对待:exceeds_200k_tokens。文档称它反映了最新响应的总计数是否超过 200k,并且“这是一个固定阈值,与实际上下文窗口大小无关”。它并不是窗口即将填满的警告。

为什么它与 /context 不同

状态栏和 /context 测量的是略有不同的时刻。状态栏使用上一次 API 响应的数据。/context 则增加了自那时以来添加的消息估算值。因此,在你粘贴大文件或 Claude 读取多个文件后,在下一次响应到达之前,/context 显示的数值可能会高于状态栏。

压缩(Compaction)会重置部分数据。文档指出 current_usage 对象“在会话中的第一次 API 调用之前为 null,在 /compact 之后也会立即变为 null,直到下一次 API 调用重新填充它”。压缩后出现空白或虚线显示的上下文片段是正常的,脚本中的备选方案可以保持其可读性。

状态栏何时更新

更新是由事件驱动的,而不是由时钟驱动。文档指出,脚本在会话开始或恢复时运行一次,并在以下情况再次运行:

  • “收到新的助手消息”。
  • “/compact 完成”。
  • “权限模式更改”。
  • “Vim 模式切换”。
  • 你更改了设置中的命令。
  • 如果你设置了刷新间隔,则在间隔到达时更新。
  • 上次数据中的速率限制窗口或 prompt 缓存达到重置或过期时间。

更新是批处理的:“Claude Code 以 300ms 的频率对更新进行防抖处理,因此快速的变化会合并在一起,脚本将在变化停止后运行一次。”如果你的脚本仍在运行时触发了新更新,Claude Code 会取消正在运行的脚本。

为什么在后台代理运行时它会停止更新

这就是开头例子中的行为。因为更新遵循主会话中的事件,主会话中的长时间等待意味着很少或没有更新,即使其他地方正在进行工作。

文档直接指出了这种情况:“当主会话处于空闲状态时(例如协调器等待后台子代理时),事件驱动的触发器可能会进入静默状态。”解决方法是:设置 refreshInterval “以便在固定计时器上重新运行命令”。最小值为一秒。

文档还提到,对于在会话之外发生变化的片段(如时钟),或者“当后台子代理在主会话空闲时更改 git 状态”时,也需要此设置。如果你的状态栏在多代理协作期间显示 git 状态,刷新间隔可以保持其数据最新。

刷新间隔会重新运行你的脚本,但它不会创建新的上下文数据。上下文字段仍然来自主会话中最近一次的 API 响应。

什么会导致它消失

故障排除部分列出了导致状态栏空白的几个原因:

  • 文件夹未被信任。 “在你接受工作区信任对话框之前,状态栏将保持空白。”状态栏运行 shell 命令,因此它遵循与钩子(hooks)相同的信任规则。
  • 脚本失败。 “以非零代码退出或不产生输出的脚本会导致状态栏变白”。
  • 钩子被禁用。 如果在托管设置之外 disableAllHooks 为 true,则只有托管的状态栏会运行。
  • 你的组织限制了钩子。 如果托管设置中设置了 allowManagedHooksOnly,“你的自定义状态栏会毫无预警地消失”。

要查看发生了什么,文档建议运行 claude --debug,它会记录脚本在会话第一次运行时的 stderr 和退出代码。

速度也很重要。“运行缓慢的脚本会阻塞状态栏更新,直到它们完成。”对于 git status 等命令,文档建议缓存结果。

我们在关于 Codex 剩余上下文 的指南中介绍了 Codex 如何计算其自身的剩余上下文数值,包括为什么它在新聊天中从顶部开始。

人们首先尝试的操作

将状态栏与 /context 进行对比。 它们测量的是不同时刻。在下一次响应之前,/context 的读数可能更高。

期望在长时间后台工作期间获得更新。 当主会话空闲时,事件触发器会进入静默状态。请设置刷新间隔。

将 exceeds_200k_tokens 视为窗口已满的警告。 它是一个固定阈值。

将输出 token 添加到上下文数值中。 used_percentage 仅计算输入 token。

在不受信任的文件夹中调试空白行。 请先接受信任对话框。

解决方案:让状态栏告诉你何时保存上下文

第 1 步:显示 used_percentage

这是文档记录的用于获取最简单、准确上下文状态的字段。

第 2 步:为 null 值添加备选方案

在第一次响应之前和 /compact 之后,字段可能为空。

第 3 步:为代理工作设置刷新间隔

在主会话等待时保持片段数据最新。

第 4 步:在窗口填满前保存决策

当数值攀升时,写下会话中你以后还会需要的决策和事实。

在 MemoryLake 中设置

状态栏告诉你上下文窗口有多满,但它不保存任何内容。当会话压缩或结束时,其中做出的决策仅与摘要或转录文件一样持久。跨会话的重要上下文(例如你做出的决定、哪些方法失败了以及适用的约束条件)最好保存为你编写的笔记。

MemoryLake 是此类项目上下文的记忆层,例如决策、约束和以往会话的教训,统一保存在你维护的一个地方,并可供你连接的助手(如 ChatGPT、Claude Code 和 Codex)使用。

你用自己的语言编写条目。不会从你的 Claude Code 会话、转录文件、状态栏脚本、设置文件或任何供应商的存储中读取、写入或删除任何内容。状态栏将按照 Anthropic 描述的方式工作。

第 1 步:创建 API 密钥

登录并从控制面板生成密钥。像处理任何其他凭据一样,将其存储在仓库之外。

MemoryLake 控制台显示 API 密钥屏幕,在此处创建并复制新密钥以供代理使用
MemoryLake 控制台显示 API 密钥屏幕,在此处创建并复制新密钥以供代理使用

第 2 步:上传你的第一条记忆

从你在解决方案第 4 步中写下的内容开始:值得从长会话中保留的决策和事实。每个条目一个主题。

MemoryLake 工作区显示已上传的首批文档,列出了每个变为可搜索记忆的文件
MemoryLake 工作区显示已上传的首批文档,列出了每个变为可搜索记忆的文件

第 3 步:连接你的 AI 和代理

连接 Claude Code、Codex 以及你使用的其他助手。新会话可以从相同的笔记开始。

MemoryLake 集成屏幕列出了可以连接到记忆层的 AI 客户端和代理框架
MemoryLake 集成屏幕列出了可以连接到记忆层的 AI 客户端和代理框架

这在实践中改变了什么

第一个区别是时机。状态栏变成了一个保存上下文的信号,而不仅仅是一个仪表盘。

第二个区别是更平滑的压缩。在摘要取代细节之前,你所需要的内容已经记录下来了。

第三个区别是跨工具的一致性。相同的笔记在 Claude Code 和其他助手中均可使用。

Claude Code 状态栏最佳实践

从 /statusline 开始。 描述你的需求,让 Claude Code 编写脚本。

使用 used_percentage。 根据设计,它仅计算输入 token。

处理 null 值。 预料到在第一次响应之前和压缩之后会出现空值。

为长时间的代理工作添加 refreshInterval。 事件触发器可能会进入静默状态。

保持脚本快速运行。 缓存 git status 等慢速命令。

显示会话名称。 当你运行多个会话时,这很有帮助。

如果显示为空白,请检查信任和钩子设置。 两者都可能隐藏它。

结论

Claude Code 状态栏运行你配置的 shell 脚本,通过 stdin 传递 JSON 会话数据,并显示脚本打印的内容,且不使用 API token。数据包括模型、工作区、会话 ID 和名称、转录路径、成本估算、速率限制以及一个 context_window 对象,其 used_percentage 仅计算输入 token。

它在收到新助手消息和执行 /compact 等事件时更新,并带有 300ms 的防抖。当主会话等待后台子代理时,这些触发器可能会静默,因此 refreshInterval 可以保持其更新。它报告的是最后一次 API 响应,这就是为什么 /context 读数可能更高。将其作为在窗口填满前保存重要内容的信号。

常见问题

什么是 Claude Code 状态栏?

它是 Claude Code 底部的一个可定制栏,运行 shell 脚本并显示其输出。

如何在 Claude Code 中设置状态栏?

运行带有描述的 /statusline,或在设置中添加 statusLine 字段。

如何在状态栏中显示上下文窗口使用情况?

使用脚本接收到的 JSON 中的 context_window.used_percentage 字段。

为什么我的状态栏与 /context 不同?

状态栏使用上一次 API 响应,而 /context 增加了对新消息的估算。

为什么我的状态栏停止更新?

当主会话空闲时,事件触发器可能会静默。请设置 refreshInterval。

状态栏会消耗 token 吗?

不会。它在本地运行,不消耗 API token。

为什么我的状态栏是空白的?

常见原因包括文件夹未受信任、脚本失败或设置中的钩子限制。