Claude Code 底部那条状态栏，平时最容易被当成摆设：命令行里一堆输出来回滚，只有它安静地贴在屏幕最底下，偶尔冒几个字提示你当前状态。但你一旦知道它其实可以完全自定义，能挂脚本实时显示当前目录、git 分支、上下文用量、甚至当前时间，就会明白这大概是整个工具里“性价比”最高的配置项之一。这篇教程就是写给零基础的人：从找配置文件开始，到改成静态文字，再到写一个能真实干活的状态栏脚本，最后把常见的坑一次性说清楚。我不预设你懂 JSON，也不预设你写过 shell，只要你愿意打开终端跟着敲，十来分钟就能让状态栏显示你想让它显示的东西。
1. 为什么说状态栏是 Claude Code 里最值得折腾的隐藏功能
1.1 状态栏在 Claude Code 界面里的位置与默认表现
先把最基础的问题说清楚：状态栏到底在哪。你正常在终端里执行claude进入交互界面后，会看到输入框、对话记录、代码输出这些常见元素。状态栏就是贴在最底部的那一条信息区域，通常会显示当前会话的一些基础信息，不同版本表现略有差异，有的显示模型名称，有的显示会话状态，有的干脆只给你一条平平无奇的提示。
我最初根本没留意它，直到有一次同时开着三个终端窗口，分别在不同目录下跑任务，每次往下翻历史记录时都得重新想一遍“我现在在哪、用的是哪个项目”。那个状态下，状态栏就成了唯一能一眼定位当前环境的地方。默认样式并不是不好看，问题在于它显示的内容是官方预设的，你没法控制它说什么、不说什么。而经过自定义的状态栏，完全就是你的私人信息看板。
所谓“自定义”，并不神秘。它的本质是让 Claude Code 在渲染状态栏这一小块内容时，不再使用内置逻辑，而是读取你指定的配置，甚至执行你写好的脚本，然后把脚本吐出来的文本直接当成状态栏内容显示出来。理解这个机制后，你会发现它其实就是一个“终端版的动态便签条”。
1.2 自定义状态栏能解决哪些实际问题
为什么值得折腾？我说几个实际场景，你对照一下：
- 多项目并行：你在几个目录里来回切换，状态栏直接写清楚当前路径，省得每次都要敲
pwd。 - 长任务心里没底：AI 工具跑长任务时你不知道上下文用了多少、会话还稳不稳，状态栏可以挂上时间、目录、分支等信息，让你对会话状态有个实时感知。
- 代码分支感知：你在 git 仓库里干活，状态栏能持久显示当前分支，防止在错误的代码分支上做了一堆操作。
- 团队协作录屏、截图：开会演示时状态栏把你当前项目名、分支、时间打上去，比空口解说直观得多。
- 纯粹的氛围感：一个定制好的状态栏，会让终端看起来更“职业”，这属于附加价值，但确实存在。
这些场景背后有一个共同点：它们都是“高频、低权重但容易忘”的信息。你不需要专门去查，但你需要它在你视线边缘始终存在。状态栏恰恰是干这个的。很多人离开了默认配置就不知道从何下手，其实它离你只有一个配置文件加一次重启远。
1.3 适合哪些人来配，前置知识门槛到底有多低
我先把结论放在前面：只要你能打开终端，并且会用文本编辑器改文件，你就具备配置状态栏的基础条件。不需要会写代码，因为你可以先只用静态文本配置；也不需要懂脚本语言，因为我会把完整脚本贴出来，你照抄就能用。
但有两类人从这项配置里获益最大：一是天天用 Claude Code 干活的开发者，二是刚接触 AI 编程工具、想让终端环境更顺手的新手。前者能把状态栏变成生产力工具，后者能通过这个小小的改动，慢慢理解配置文件、脚本、JSON 这些概念的协作方式。
配置状态栏真正需要掌握的核心，无非三件事：配置文件放哪、配置项长什么样、脚本输出的格式是什么。这三点我会在下面几节逐一拆开讲。
2. 动手前准备：版本要求、配置文件定位与默认效果确认
2.1 先确认你的环境和版本，避免白忙一场
任何配置教程第一步都不该是直接改配置，而是确认你手里的“食材”是新鲜的。状态栏功能依赖的是 Claude Code 本身的版本支持，所以请确保以下几点：
- Claude Code 已经正常安装，并且你至少成功进入过交互界面一次。
- 你所在的系统有 Node.js 环境，因为 Claude Code 本身依赖它运行，版本建议保持较新的稳定版本，老版本容易碰到各种奇怪的兼容问题。
- 操作系统不影响配置逻辑。macOS、Linux、Windows 都能配，区别只在于配置文件路径和脚本权限的设置方式。
我的建议是：在动手之前，先执行一次claude --version看看版本号，如果版本过于陈旧，优先升级到最新版。我不建议你带着一个半年前的老版本去做配置，因为状态栏相关的字段和新功能往往只在较新版本里才稳定支持。版本太旧时，明明配置写对了，工具不认，排查起来很浪费时间。
有个很容易被忽略的点：如果你之前从未成功启动过 Claude Code，第一次运行时它可能还在做初始化、登录之类的流程，此时界面底部的状态栏也未必是完整形态。先让它跑完初始化，确保基本功能能用，再来做下面的步骤。
2.2 全局配置文件在哪：~/.claude/settings.json 的定位与作用
Claude Code 的配置体系里有全局配置和项目配置之分。状态栏这种希望所有项目都生效的改动，放在全局配置里最省心。全局配置文件的默认路径是：
- macOS / Linux：
~/.claude/settings.json - Windows：
C:\Users\你的用户名\.claude\settings.json
注意，这个settings.json是你自己用户目录下的.claude目录里的那个，不是某个项目目录里的.claude。如果你在某个具体项目里建过配置文件，那是项目级配置，作用范围只限于那个目录，新手经常在这里搞混。
如果你的机器上.claude目录不存在，或者里面没有settings.json，那就手动创建一个。这完全正常，不要等着工具去生成，它不会主动帮你建。文件内容一开始可以是一个空对象，也就是只有一对大括号：
{ "statusLine": { "type": "message", "text": "状态栏配置从这里开始", "output_mode": "replace" } }先说明一下：上面这段配置我建议直接写上，保存后你就能验证配置文件路径是否正确。其中的含义，第 3 节会展开讲。
2.3 配置前，先看一眼默认状态栏长什么样
这一步看似多余，但我强烈建议你先在配置前启动一次 Claude Code，把默认状态栏的样式、位置记在脑子里。这不是为了仪式感，而是为了之后排查问题。
具体做法很简单：终端里进入任意一个工作目录，执行claude，等界面加载完成后，观察屏幕底部的信息。有的版本会显示模型名，有的会显示空闲/忙碌状态，有的甚至有简短的说明文字。默认状态栏就是你的对照组。
我自己的习惯是写配置前后分别截屏，或者直接用手机拍一张留档。这样一旦配置后状态栏样式不变，你能立刻判断：是配置没生效，还是配置生效了但脚本输出内容和原来长得一样？千万别小看这一步，很多人在排查“为什么没变化”时，才发现自己根本想不起来原始状态栏长什么样，结果绕了很大一圈。
3. 核心配置逐项拆解：statusLine 字段到底该怎么填
3.1 最简单的起步方式：type=message 静态文本
状态栏自定义的入口，就是settings.json里的一级字段statusLine。它下面最关键的字段是type，用来决定状态栏内容是“固定文本”还是“动态脚本”。
先看静态文本模式，也就是type: "message"。它的配置结构是：
{ "statusLine": { "type": "message", "text": "写在这里的内容会原样显示在状态栏", "output_mode": "replace" } }三个字段的作用分别是：
type：必填。指定状态栏的模式。“message”表示直接展示文本。text：必填。静态文本内容，之后完全原样显示，不做变量替换。output_mode：可选但建议写。指定输出方式是替换原有状态栏内容还是追加到其后。
这套配置是最没有技术含量的，但你最好老老实实先配它，因为它的作用是验证链路：配置格式对不对、文件路径对不对、保存后重进界面状态栏变不变。如果连静态文本都不生效，后面挂脚本的时候更难排查问题。我见过一上来就写脚本，结果脚本死活不显示，最后发现是配置文件路径放错了，白白浪费了一个晚上。
3.2 动态脚本模式：type=script 与输出格式
静态文本只是开胃菜，状态栏真正的价值在type: "script"。这个模式下，Claude Code 会执行你指定的脚本，把脚本的输出当成状态栏内容显示。
为什么需要脚本？因为静态文本做不到动态变化。你想要的状态栏大概率是这样的：早上九点打开终端，状态栏显示“09:00 | 我的项目目录 | 分支 main | 上下文 20%”，每过一会它还自动更新。这种内容只能靠脚本实时生成。
配置结构如下：
{ "statusLine": { "type": "script", "script_path": "/Users/你的用户名/statusline/status.sh", "output_mode": "replace" } }关键在于script_path要指向一个可执行文件，并且这个文件运行后必须输出特定格式的 JSON。JSON 里最重要的字段是status_line，它对应的字符串会被展示在状态栏。
这里我要特别强调输出格式，因为它决定了脚本跟状态栏之间能不能对得上话。脚本不需要输出华丽的界面，只需要在标准输出里打印一行 JSON，例如：
{"status_line": "2025-01-15 09:00 | /home/user/project | main"}如果脚本输出的不是合法 JSON，或者缺失status_line字段，状态栏很可能会显示一个错误信息，或者直接拒绝更新。很多新手最容易栽在这里：脚本明明能打印内容，但状态栏就是没反应，原因就是多打了个逗号、少了个引号，或者额外打印了一行调试信息。
3.3 output_mode 选 replace 还是 add，差别在哪里
output_mode字段虽然看起来不起眼，但实际上决定了状态栏的表现形式。官方常见支持的有两个取值：replace和add。
replace：用脚本输出的内容完全替换原来的状态栏信息。适合自定义程度高、想彻底控制状态栏展示内容的场景。add：把脚本内容追加到原有状态栏信息后面。适合只想在默认信息基础上加一点补充内容的场景。
我给你的建议是无脑选replace。原因有两点：第一，add模式意味着原有内容还在，新内容挤在后面，容易出现重复信息，状态栏本来空间就窄，越挤越乱；第二，replace模式下你拥有完全的控制权，想显示什么、不显示什么，全由脚本说了算，排查问题时也更容易理解“状态栏里出现的东西都是从哪来的”。
从另一个角度说，add模式适合那些纯粹想给默认状态栏加时间戳又不想动其他信息的轻度用户，但如果你已经在写脚本了，说明你是有定制需求的，与其让别人掌握一半控制权，不如全拿过来。
4. 从零到能跑的完整实操：做一个“时间 + 目录 + git 分支 + 上下文用量”状态栏
4.1 先规划目录与脚本骨架，避免路径问题
现在进入正题。我们的目标状态栏默认显示四样信息：当前时间、当前目录、git 分支、上下文用量。其中上下文销耗不一定每个版本都开放相关接口，所以脚本里我会写成“通过简单提示词模拟状态”的方式，或者根据是否有可用的环境变量来判断；实际使用中模板逻辑是一致的。
第一步是建一个专门放状态栏脚本的目录。不建议把脚本随手扔在任何地方，更不建议直接在配置里写script_path: "status.sh"这种相对路径，因为脚本执行时的工作目录不固定，相对路径非常容易出事。请务必使用绝对路径。
我的建议是建一个独立的目录，比如：
~/.claude/statusline/在这个目录下新建脚本文件，例如status.sh。为什么要独立目录？因为以后你可能会有多个脚本、一个主脚本若干辅助脚本，集中管理方便得多。而且状态栏脚本属于你个人环境的一部分，跟着配置目录走，语义也清晰。
4.2 完整脚本编写：bash 版逐行解释与配置 JSON
我先把完整的 bash 脚本贴出来，再逐段解释。之所以用 bash，是因为它在绝大多数系统上免安装、开箱即用。
#!/usr/bin/env bash # 1. 当前时间 time_now=$(date "+%Y-%m-%d %H:%M:%S") # 2. 当前目录，把 $HOME 缩成 ~ 更简洁 dir_now=$(pwd | sed "s|$HOME|~|") # 3. 当前 git 分支，非仓库目录则标记 no-git branch_now=$(git branch --show-current 2>/dev/null || echo "no-git") # 4. 模拟上下文状态：这里用一个占位变量，你可以替换成真实接口 ctx_now="ctx-ready" # 5. 拼成状态栏要的 JSON 输出 echo "{\"status_line\": \"${time_now} | ${dir_now} | ${branch_now} | ${ctx_now}\"}"逐段看：
第 1 行指定解释器为 bash。第 3 行用date拿到时间戳，格式精确到秒，够用也直观。第 4 行是关键技巧：pwd | sed "s|$HOME|~|"会把当前路径中的用户目录前缀缩写为~，比如/Users/abc/project显示成~/project，状态栏空间有限，这个缩写很实用。第 5 行用git branch --show-current拿分支名，注意这里的处理逻辑——如果不是 git 仓库，该命令会报错，所以用2>/dev/null || echo "no-git"做了兜底，不会让脚本因为跑在非仓库目录而崩溃。第 6 行是上下文状态的占位符，你可以根据实际情况替换为能读取上下文用量的命令或接口。第 7 行是输出 JSON，重点在于转义：内层双引号前都加了反斜杠，这样 echo 输出的才是合法的 JSON 字符串。
写完之后，给脚本赋予执行权限：
chmod +x ~/.claude/statusline/status.sh这一步在 macOS 和 Linux 上必须做，否则脚本不可执行，配置了也不会生效。Windows 用户如果用的是 Git Bash 或 WSL 环境，同样按这种方式操作；如果你是纯 PowerShell 环境，建议改用 Python 脚本或直接安装一个 WSL 环境，状态栏脚本的生态在 Unix 环境下最顺。
然后修改~/.claude/settings.json，填入：
{ "statusLine": { "type": "script", "script_path": "/你的绝对路径/.claude/statusline/status.sh", "output_mode": "replace" } }注意一定把script_path替换成你自己机器上的绝对路径。在写路径时，不要偷懒写~/.claude/statusline/status.sh，因为有些场景下不会把~展开，直接导致路径找不到。配置里用完整路径最稳妥。
4.3 保存、重进、验证：状态栏生效的完整检查流程
配置和脚本都准备好之后，就是见证结果的时候。操作顺序是：
- 保存
settings.json - 退出当前 Claude Code 会话，重新执行
claude - 观察底部状态栏是否显示了脚本输出的内容
如果一切正常，你会看到状态栏变成类似：
2025-01-15 09:00:00 | ~/project | main | ctx-ready这是一个完整的成功信号。如果没变化，那就进入排查模式：先在终端里手动执行一遍脚本，比如：
bash ~/.claude/statusline/status.sh如果手动执行就报错或者输出不是合法 JSON，那问题出在脚本本身，和 Claude Code 无关。如果手动执行输出正常，但状态栏还是老样子，问题大概率出在配置路径、statusLine配置结构或文件位置。就近原则：谁离错误最近，先查谁。
成功运行一次之后，你可以把脚本里的ctx_now替换成你真正关心的信息，比如磁盘剩余空间、当前 Python 虚拟环境名称等等。只要保持最终输出是{"status_line": "..."}这个结构，状态栏就能正常渲染。
5. 常见问题与排查实录：这些坑我刚开始全踩过
5.1 状态栏纹丝不动，还是默认样式怎么办
这是最常见的故障，几乎每个第一次配的人都遇到过。我按优先级列出排查顺序：
| 排查点 | 检查方法 | 原因说明 |
|---|---|---|
| 配置文件位置 | 确认改的是~/.claude/settings.json，不是项目目录里的.claude/settings.json | 项目级配置只在该项目下生效 |
| 配置字段大小写 | statusLine大小写必须完全匹配 | 配置字段对大小写敏感 |
| JSON 合法性 | 用在线 JSON 校验工具或node -e "JSON.parse(...)"检查 | 少个逗号整个文件都会失效 |
| 脚本执行权限 | ls -l查看脚本是否有x权限 | 没有执行权限，工具无法运行脚本 |
| 重新启动会话 | 配置修改后需要退出重进 | 配置通常不会热加载 |
其中最阴险的是第一条。很多人在项目目录下跑 Claude Code，就顺手在项目里建了个.claude目录放配置，结果状态栏配置只在那个目录生效，换个目录就没了。全局配置和项目配置的定位完全不同：全局配置管所有项目，项目配置管当前这一个项目。所以我的建议是：没有特殊需求时，所有状态栏相关配置一律放全局。
5.2 脚本报错、路径有误、JSON 格式飘了
脚本相关的报错类型比较集中，我挑三个最典型的来说。
第一个是路径问题。script_path写的是相对路径，或者写成了~/xxxx这种简写，都可能让工具找不到脚本。排查方式很简单：打开终端，把配置里的路径原样复制出来执行一下，如果 shell 都找不到文件，那配置自然也不可能找到。请用绝对路径，一劳永逸。
第二个是输出格式不是合法 JSON。常见错误包括：用echo输出时少转义了一个引号，JSON 数组和对象混淆，或者脚本里除了 JSON 还打印了其他调试信息。状态栏脚本会把你所有标准输出都当作内容来解析，如果你在脚本开头加了一行echo "调试信息"，那整个输出就不再是合法 JSON，状态栏也会罢工。所以脚本里任何额外输出都要清理干净，确保最终只有一行、合法的 JSON。
第三个是行尾符问题。Windows 下编辑的脚本经常带着 CRLF 行尾，拿到 bash 环境下执行会报$'\r': command not found之类的错误。如果你是在 Windows 上写脚本然后到 Linux 上运行，记得把换行符转成 LF，或者直接用编辑器右下角切换行尾格式。
5.3 显示不全、中文乱码、刷新频率不理想
状态栏显示不全，通常是内容太长了。状态栏可用的宽度就是终端宽度，一旦超过就会被截断。我的处理原则是：状态栏内容控制在 60 个字符以内，超过的部分主动舍掉。脚本里可以加一个截断逻辑，比如只取当前目录的最后一级，而不是把整个路径全打出来。
中文乱码这个事，跟状态栏本身关系不大，更多是终端编码问题。如果你的系统 locale 是英文环境，强行在状态栏里输出中文，很可能显示成乱码。这种情况下我建议直接改成英文显示，省心。非要中文的话，先把终端字符编码统一为 UTF-8，再检查系统的 locale 设置，两处一致了基本能正常显示。
刷新频率也需要有个预期管理。状态栏不是“每秒自动刷新”的定时器，它的更新通常和会话状态变化绑定。你不要指望脚本里的date能像时钟一样每秒跳字，更多时候它是在会话有交互、状态切换的时候才会拉取一次脚本输出。想靠状态栏当实时秒表，那方向就偏了。
6. 再往前走一步：脚本状态与个人习惯
6.1 一个脚本对付多个项目：根据目录动态切换状态内容
状态栏脚本的妙处在于，它是活的，可以根据环境动态改变内容。我目前用的状态栏脚本已经能做到在不同目录下显示不同信息：在项目 A 目录里显示约定好的项目代号，在项目 B 目录里显示另一个代号，既保留了时间、分支这样的通用信息，又增加了项目维度的提示。
实现思路很简单：脚本里先拿pwd，然后根据路径做判断。比如用 case 语句匹配几个关键目录名，匹配上了就追加一个“项目标识”，没匹配上就显示一个通用标识。对于直接用同一个工具管理多个仓库的人来说，这个功能很实用，你基本不用刻意去记当前在哪个项目里，状态栏已经把答案放在眼前了。
更进一步，你可以准备一个独立的配置文件，用来维护“目录到项目名的映射表格”。脚本每次运行时先读这个映射表，再拼装结果。这样做的好处是以后新增项目时，只需要改映射表，不用动状态栏脚本主体。维护成本非常低。
6.2 配合 hook 做会话状态提示
如果你已经熟练使用状态栏了，就会开始想：“能不能让它告诉我，Claude Code 正在忙还是在等我？”这就涉及到 hook 机制。简单说，hook 是会话生命周期里能被触发的事件钩子，你可以在特定事件发生时执行自己的脚本，而状态栏的刷新依赖脚本执行结果，两者天然可以联动。
我之前试过一种做法：在 hook 里设置一个标记文件，标记当前会话是“工作状态”还是“等待状态”；状态栏脚本每次运行时去读这个标记，决定显示什么内容。这样在 AI 处理长任务时，状态栏能显示出“工作中”的提示，任务结束再变回“待命中”。虽然看着简单，但对长时间驻留终端的用户来说，这个心理提示很有价值。
这个玩法需要你对 hook 的配置方式有一些了解，如果你暂时没接触过，可以先放一放，把前面的基础配置吃透再说。
6.3 我用了大半年以后留下的几个建议
最后分享一些个人经验。状态栏脚本最重要的一条原则是：保持脚本轻量。它就是用来显示信息的，不是用来做重计算的。不要在脚本里执行耗时的命令、不要联网请求接口、不要跑复杂的循环，否则每次状态刷新都要卡一下，体验非常糟糕。我踩过这个坑：一开始在脚本里加了个磁盘测速命令，结果每次刷新都肉眼可见地停顿，后来果断去掉了。
第二个建议是：把状态栏模板纳入你的 dotfiles 管理。如果你本来就有点 dotfiles 备份习惯，就把settings.json和脚本目录一起纳入版本管理，以后换机器、重装系统，一条命令就能恢复整套环境。如果没有这个习惯，也至少把这两个文件备份到一个网盘或代码仓库里。
第三个建议是给自己留一个“逃生通道”。在你充分熟悉状态栏配置之前，不要删掉默认配置备份。改之前先把原始settings.json复制一份，起个名字叫settings.json.bak。配置出问题、心态崩了的时候，把备份还原回去，至少能保证工具回到可用状态。这个习惯帮我省了很多不必要的折腾。
状态栏配置这件事，说小了只是终端里的一行文字，说大了其实是你使用习惯的一个缩影。从复制粘贴别人的脚本，到真正理解字段含义，再到按自己需求改脚本，这个过程本身就是在熟悉工具的工作机制。多用几次，你自然就会有自己的心得。
