Codex CLI 状态栏配置指南
Codex CLI 的状态栏(status line)是 TUI 底部持久显示的页脚区域,用于实时展示模型、Git 分支、上下文用量、速率限制等会话信息。配置入口统一位于 ~/.codex/config.toml 的 [tui] 段,通过 status_line 数组声明要显示的项目及其顺序。
适用版本:Codex CLI 0.154.0+
一、概述
Codex CLI 原生支持可配置状态栏,无需任何外部脚本。
Codex 把状态栏做成了内置功能,通过 config.toml 里的字段名数组配置即可,配置都在 [tui] 段下:
|
1
2
3
|
[tui]
status_line = ["git-branch", "context-used", "used-tokens", "context-window-size", "model-with-reasoning", "thread-name"]
status_line_use_colors = true
|
二、字段表与调整方式
内置字段全集(0.154.0)
| 分类 |
字段 |
| 位置与仓库 |
current-dir、project-name、git-branch、pull-request-number、branch-changes |
| 上下文与用量 |
context-used、context-remaining、context-window-size、used-tokens、total-input-tokens、total-output-tokens、thread-credits、estimated-thread-cost |
| 会话 |
status、run-state、task-progress、thread-id、thread-name、thread-title、workspace-headline |
| 模型 |
model、model-with-reasoning、reasoning、fast-mode |
| 权限与版本 |
permissions、approval-mode、codex-version |
| 其他 |
five-hour-limit、weekly-limit、raw-output |
字段名拼错会被忽略或报 unknown item,不会导致启动失败,但也不会显示。
三种调整方式
|
1
2
3
4
5
6
|
# 1) 会话内交互式调整(官方入口,会写回 config.toml)
# 提示语:"Use /statusline to configure which items appear in the status line."
/statusline
# 2) 单次覆盖,用于快速试验字段是否有效
codex -c 'tui.status_line=["codex-version","permissions","approval-mode"]'
# 3) 直接编辑 ~/.codex/config.toml 的 [tui] 段(推荐用于固化配置)
|
变更流程固定为:改配置 → 重启 codex → 看底栏。
注意事项
- 版本要求:内置状态栏功能需要 Codex CLI v0.101.0 及以上。运行 codex --version 确认版本,升级后重启 CLI 使配置生效。
- 配置生效:手动编辑 config.toml 后需重启 Codex CLI。使用 /statusline 命令修改则立即生效。
- 配置层级:Codex CLI 的配置存在多级覆盖关系,系统配置 → 用户配置(~/.codex/config.toml)→ 项目配置(<project>/.codex/config.toml),后者仅在项目受信任时加载-。状态栏设置通常写入用户级配置即可全局生效。
- 扩展工具限制:目前 Codex 的状态栏仅支持预定义项目 ID 的原生渲染,不支持 ANSI 颜色、自定义分隔符、多行布局和任意命令输出。社区工具通过模拟内置项目或借助外部命令(如 codex-hud)绕过这一限制,但无法完全复现 Claude Code 的 statusLine.command 那种自由格式化能力。
|