WTFUtil 0.51.0 配置参数详解
WTFUtil（wtfutil/wtf）v0.51.0 配置体系实测详解：config.yml 加载优先级（--config/WTF_CONFIG）、colors 主题与 grid 布局全局参数、模块通用 Common 参数与 clocks/status/textfile/cmdrunner 专属参数，全配实测生效回显与 YAML/时区/TERM 排障实录。
WTFUtil 0.51.0 配置参数详解
目标：逐层讲清终端个人信息仪表盘 WTFUtil（GitHub 仓库 wtfutil/wtf，命令名
wtfutil）v0.51.0 的 YAML 配置体系——配置文件位置与加载方式、全局参数（颜色主题 / Grid 布局 / 导航 / 退出消息等）、所有模块通用的 Common 参数、以及 clocks / status / textfile / cmdrunner 四个实测模块的专属参数，全部参数说明均配实测配置与生效回显。全文命令与输出均在 Ubuntu 22.04.5 LTS（x86_64）服务器实测通过，实测版本为 v0.51.0（查询日期 2026-10-23）。
⚠️ 防混淆说明：本专栏的 WTFUtil 指 GitHub 上的 wtfutil/wtf 项目，安装后命令名为
wtfutil。它与部分 Linux 发行版软件仓库里自带的wtf命令（BSD games 工具集中用于查询术语释义的小工具）毫无关系，两者同名不同物——本文及本专栏所有内容均围绕wtfutil命令展开。
一、环境信息
本文实测所用环境如下，读者按相同环境操作可直接得到相同回显：
- 操作系统：Ubuntu 22.04.5 LTS（x86_64）；
- WTFUtil 版本：v0.51.0（安装过程见 《Ubuntu 22.04 安装 WTFUtil 0.51.0 指南》）；
- 许可证：MPL-2.0；
- 终端：任意支持 256 色的终端（GNOME Terminal、tmux 内均可），
TERM建议为xterm-256color； - 组件定位与选型背景见 《WTFUtil 介绍与选型指南》。
版本回显实测：
wtfutil --version
实测输出：
WTF v0.51.0 (built: 2026-09-29T16:08:28Z)
二、前置条件
阅读并复现本文操作前，确认以下条件已满足：
- 已按 《Ubuntu 22.04 安装 WTFUtil 0.51.0 指南》 安装 v0.51.0，且
wtfutil --version能正常输出版本号； - 当前用户对
~/.config/目录有写权限（wtfutil 首次启动会自动创建~/.config/wtf/目录）； - 终端已设置合理的
TERM值。TERM未设置或设置为无效值时，wtfutil 会直接报错退出（排障实录见第九章 9.3 节）：
echo $TERM
实测输出：
xterm-256color
- 若需复现文中的世界时钟模块，系统需带时区数据库（Ubuntu 22.04 默认自带）：
ls /usr/share/zoneinfo/ | head -5
实测输出：
Africa
America
Antarctica
Arctic
Asia
三、参数查看与修改方式
WTFUtil 的全部配置集中在一个 YAML 文件中，没有 config test 之类的子命令，参数的查看与验证依靠三类手段：配置文件本身、-m 模块帮助、以及"改完重启进程看界面"。
3.1 配置文件位置与加载优先级
WTFUtil 默认读取 ~/.config/wtf/config.yml。若该目录不存在，首次启动会自动创建目录并显示创建配置文件的指引。
首次启动后实测目录内容：
ls -la ~/.config/wtf/
实测输出：
total 16
drwxr-xr-x 2 root root 4096 Oct 23 07:04 .
drwxr-xr-x 4 root root 4096 Oct 23 07:10 ..
-rw------- 1 root root 1447 Oct 23 07:06 config.yml
-rw------- 1 root root 98 Oct 23 07:04 log.txt
log.txt 是 wtfutil 自身的运行日志（内容见 3.3 节），config.yml 为唯一配置入口。
除了默认路径，还有两种自定义加载方式，均已实测：
方式一：命令行 --config 参数（优先级最高）
wtfutil --config=/root/noexit.yml
方式二：WTF_CONFIG 环境变量
export WTF_CONFIG=/root/noexit.yml
wtfutil
实测验证环境变量方式：将 WTF_CONFIG 指向一个包含世界时钟的配置文件后直接运行 wtfutil，界面按该配置渲染（世界时钟 Beijing 一行出现在界面上，且使用的是自定义配置中的 2 列布局）：
│ Beijing 01:48 CST Oct 24 ││ │
💡 实测发现：
export WTF_CONFIG=...是 shell 会话级持久生效的——只要当前 shell 里导出过该变量，之后所有不带参数的wtfutil命令都会加载它指定的配置文件，直到执行unset WTF_CONFIG为止。排查"配置改了却不生效"时，先echo $WTF_CONFIG确认环境变量是否残留。
三种方式的优先级为：--config 命令行参数 > WTF_CONFIG 环境变量 > 默认的 ~/.config/wtf/config.yml。实际使用建议：日常固定一份 ~/.config/wtf/config.yml；临时试验其他配置用 --config；WTF_CONFIG 适合写进 shell profile 长期切换。
3.2 用 -m 参数查看模块内置帮助（不联网、离线可用）
wtfutil 二进制内置了每个模块的帮助文本（键盘命令 + 配置参数说明），用 -m=<模块名> 查看，无需联网：
wtfutil -m=clocks
实测输出（ clocks 模块的参数说明部分）：
Configuration Attributes
positionSettings
Defines where in the grid this module's widget will be displayed.
bordered
Optional Whether or not the module should be displayed with a border.
Values: true, false
enabled
Optional Whether or not this module is executed and if its data displayed onscreen.
Values: true, false
focusable
Optional Whether or not this module is focusable.
Values: true, false
languageTag
Optional The BCP 47 language tag to localize text to.
Values: Any supported BCP 47 language tag.
refreshInterval
Optional How often this module will update its data.
Values: A positive integer followed by a time unit (ns, us, ms, s, m, h, or nothing which defaults to s)
title
Optional The title string to show when displaying this module
focusChar
Optional Define one of the number keys as a short cut key to access the widget.
dateFormat
The format of the date string for all clocks.
Values: Any valid Go date layout which is handled by Time.Format. Defaults to Jan 2.
timeFormat
The format of the time string for all clocks.
Values: Any valid Go time layout which is handled by Time.Format. Defaults to 15:04 MST.
locations
Defines the timezones for the world clocks that you want to display. key is a unique label that will be displayed in the UI. value is a timezone name.
Values: Any TZ database timezone.
sort
Defines the display order of the clocks in the widget.
Values: 'alphabetical', 'chronological', or 'natural. 'alphabetical' will sort in ascending order by key, 'chronological' will sort in ascending order by date/time, 'natural' will keep ordering as per the config.
这一输出是 v0.51.0 二进制内的权威参数表（比网页文档更贴合当前版本），本文第七章的模块参数详解即以此 + 实际配置验证交叉确认。
3.3 日志文件
~/.config/wtf/log.txt 记录 wtfutil 的运行日志，排障时先看它。实测内容节选：
cat ~/.config/wtf/log.txt
实测输出：
2026/10/23 07:04:50 log.go:23: Protocol version: auto
2026/10/23 07:04:50 log.go:23: Network: tcp
💡 说明：这两行来自 Status 模块的系统监控初始化。日志随运行过程滚动追加，遇到模块异常（网络超时、命令执行失败等）时相关信息会出现在这里。
3.4 修改生效方式
WTFUtil 没有 reload 机制：任何配置修改都需要退出并重新启动 wtfutil 才生效。修改后验证生效的标准动作：
# 1. 在运行中的 wtfutil 界面按 q 退出
# 2. 重新启动
wtfutil
四、配置文件结构与参数总览
一个完整的 config.yml 由「全局参数」与「模块参数（mods）」两大块组成。下面的总览表先给全景，各参数的逐项详解在第五、六、七章：
| 顶层键 | 层级 | 作用 | 详解章节 |
|---|---|---|---|
wtf.colors | 全局 | 界面配色主题（背景 / 边框 / 高亮 / 文本） | 5.1 |
wtf.grid | 全局 | 网格布局：列宽与行高数组 | 5.2 |
wtf.refreshInterval | 全局 | 全局默认刷新间隔，可被模块覆盖 | 5.3 |
wtf.exitMessage | 全局 | 退出时的 ASCII 艺术字消息开关 | 5.4 |
wtf.navigation | 全局 | 数字导航快捷键开关 | 5.5 |
wtf.openFileUtil / wtf.openUrlUtil | 全局 | 打开文件 / URL 所用的外部工具 | 5.6 |
wtf.sigils | 全局 | 复选框与分页符的显示符号 | 5.7 |
wtf.term | 全局 | 强制指定终端类型（一般留空） | 5.8 |
wtf.githubAPIKey | 全局 | GitHub API 密钥（退出消息贡献者校验用） | 5.4 |
wtf.mods.<模块名> | 模块 | 每个模块的专属配置块 | 第七章 |
模块级配置又分两层：所有模块通用的 Common 参数（第六章，如 enabled、position、refreshInterval、title 等）与模块专属参数（第七章，如 clocks 的 locations、cmdrunner 的 cmd/args）。
💡 技术拓展：YAML 配置体系的组织方式在同类终端工具中主要有三种——单文件嵌套（WTFUtil 的
wtf.mods.*，全部配置集中一个 config.yml）、目录分片（如某些工具按模块拆多个 yaml）、环境变量驱动（如 glances 支持环境变量覆盖，见 《glances 4.5.8 配置参数详解》）。WTFUtil 选择单文件嵌套 + 命令行参数覆盖的组合：配置可整体备份、可多份切换（--config），但不支持环境变量逐项覆盖（仅WTF_CONFIG这一个路径级变量）。
五、全局参数详解
全局参数位于 YAML 顶层 wtf: 键下，控制整个应用的布局、配色与行为。以下各项均在实测环境中逐项验证。
5.1 颜色主题（colors）
colors 定义全应用的配色，取值均为 X11 颜色名（如 black、gray、orange、darkslateblue、lightblue）：
wtf:
colors:
background: "black"
border:
focusable: "darkslateblue"
focused: "orange"
normal: "gray"
逐项说明：
| 参数 | 含义 | 取值 |
|---|---|---|
colors.background | 应用整体背景色，可与终端配色匹配；可被模块级 colors 覆盖 | 任意 X11 颜色名 |
colors.border.focusable | 可接收键盘焦点的模块的边框颜色 | 任意 X11 颜色名 |
colors.border.focused | 当前持有键盘焦点的模块的边框颜色 | 任意 X11 颜色名 |
colors.border.normal | 不可聚焦模块的边框颜色 | 任意 X11 颜色名 |
colors.highlight.fore / back | 列表高亮项的前景 / 背景色 | 任意 X11 颜色名 |
colors.text / colors.title | 正文文本 / 模块标题颜色 | 任意 X11 颜色名 |
配置生效实测：把 colors.border.normal 从 gray 改为 red，重启后捕获界面首行边框，边框颜色码变为红色（ANSI 31）；按数字键聚焦模块后边框变为 focused 指定的橙色系（ANSI 33）且边框线型由单线 ┌─┐ 变为双线 ╔═╗；按 Esc 取消焦点后恢复。三态对照（文字版界面一致，仅颜色与线型不同）：
未聚焦（normal 灰色系、单线）： ┌──────────────── 系统负载 2 ────────────────┐
聚焦后（focused 橙色系、双线）： ╔════════════════ 系统负载 2 ════════════════╗
💡 技术拓展：终端前景色的表示有 X11 颜色名、16 色 ANSI 基本色、256 色（
38;5;N）与 24 位真彩（38;2;R;G;B）四种体系。WTFUtil 配置里写的是 X11 颜色名，运行时由 Go 的 tview/tcell 库把它映射为当前终端支持的最接近色——这也是为什么gray、darkslateblue等名字在不同终端里实际观感略有差异。若需精确控制色彩，应优先调整终端本身的配色方案。
5.2 网格布局（grid）
WTFUtil 用 tview 的 Grid 布局系统摆放各模块窗口：把终端屏幕视为一个矩阵，grid.columns 定义各列的宽度（字符数），grid.rows 定义各行的高度（行数），模块再通过 position（见 6.5 节）声明自己占据哪个格区。
wtf:
grid:
columns: [46, 46, 46]
rows: [10, 8, 8]
逐项说明：
columns：数组，每个元素是一列的宽度（终端字符数）。上例为 3 列、每列 46 字符宽，适配约 140+ 列的宽屏终端；rows：数组，每个元素是一行的高度（终端行数）。上例为 3 行（10/8/8）。
坐标系统：原点在屏幕左上角，position.top / position.left 从 0 开始计数，height / width 表示跨越几个格区。官方给的一个直观例子：一个占 2 列 × 2 行、位于屏幕右下角的部件应写：
position:
top: 4 # 从第 5 行格区开始（下标 4）
left: 9 # 从第 10 列格区开始（下标 9）
height: 2 # 纵跨 2 个格区
width: 2 # 横跨 2 个格区
布局生效实测：按上文 columns: [46, 46, 46] / rows: [10, 8, 8] 配置并启用 5 个模块后，界面渲染为 3 列布局（文本捕获，终端 180×50）：
┌───────────────── 世界时钟 ─────────────────┐┌────────────────── Status ──────────────────┐┌─────────────── ~/notes.md 1 ───────────────┐
│ Beijing 01:44 CST Oct 24 ││\ ││ │
│ London 18:44 BST Oct 23 ││ ││# 运维值班备忘 │
│ New York 13:44 EDT Oct 23 ││ ││ │
│ ││ ││- 09:30 例行巡检磁盘与内存 │
│ ││ ││- 14:00 备份任务复核（/var/backups） │
│ ││ ││- 周五 17:00 发布窗口，提前 30 分钟冻结变更 │
│ ││ ││ │
│ ││ ││ │
└────────────────────────────────────────────┘└────────────────────────────────────────────┘└────────────────────────────────────────────┘
┌──────────────── 系统负载 2 ────────────────┐┌────────────────────────────────────── 根分区容量 3 ──────────────────────────────────────┐
│ 17:44:01 up 4 days, 1:56, 0 users, load ││Filesystem Size Used Avail Use% Mounted on │
│ ││overlay 786G 516G 236G 69% / │
│ ││ │
│ ││ │
│ ││ │
└────────────────────────────────────────────┘└──────────────────────────────────────────────────────────────────────────────────────────┘
注意"根分区容量"模块的 width: 2——它横跨了第 2、3 两个列格区，所以边框宽度约等于两个 46 字符列。这正是 grid 布局"按格区跨度摆放"的直观体现。
5.3 全局刷新间隔（refreshInterval）
wtf:
refreshInterval: 1
顶层 refreshInterval 是全局默认值，单位为秒；每个模块可用自己的 refreshInterval 覆盖（见 6.6 节，模块级默认 300s）。实测配置中全局为 1 秒，而各模块分别配置为 15/30/60 秒——状态栏类轻量模块走全局短间隔，重数据模块用模块级长间隔，避免频繁刷新造成终端闪烁或外部请求过密。
5.4 退出消息（exitMessage）与 githubAPIKey
wtf:
exitMessage:
display: true
githubAPIKey: ""
逐项说明：
exitMessage.display：按q退出应用时是否在终端打印 WTF 的 ASCII 艺术字消息。默认true；githubAPIKey：用户自己的 GitHub API 密钥，用于退出消息中校验"贡献者/赞助者"身份；留空时可用环境变量WTF_GITHUB_TOKEN提供。不使用 GitHub 相关模块可留空。
默认配置下按 q 退出的实测回显（消息共三段：ASCII 艺术字 + 更名公告 + 赞助信息）：
_______ ______ _____ _____ ______ _____
|__ __| ____|/ ____|/ ____|| ____| __ \ /\
| | | |__ | (___ | (___ | |__ | |__) | / \
| | | __| \___ \ \___ \ | __| | _ / / /\ \
| | | |____ ____) |____) || |____| | \ \ / ____ \
|_| |______|_____/|_____/ |______|_| \_\/_/ \_\
the personal information dashboard for your terminal
Heads up! WTF is being renamed to Tessera. Stay tuned!
The development and maintenance of WTF is supported by sponsorships.
Sponsor the development of WTF at https://github.com/sponsors/FelicianoTech
⚠️ 实测发现（与官方文档描述不符）：官方文档声称
exitMessage.display: false可关闭退出消息，但在 v0.51.0 实测中，配置display: false后按q退出仍然打印了完整的 ASCII 艺术字与更名公告。若你依赖此开关静默退出，请以实际版本行为为准并自行验证，不要默认文档行为成立。
5.5 导航快捷键开关（navigation.shortcuts）
wtf:
navigation:
shortcuts: true
控制是否在可聚焦模块的标题栏中显示数字导航快捷键。默认 true。
生效实测：默认（true）时界面中三个可聚焦模块的标题分别为"系统负载 2""根分区容量 3"与 ~/notes.md 1——标题末尾的数字即该模块的聚焦快捷键（见 5.2 节实测界面与第六章 focusChar）。改为 false 后重启，标题恢复为 ~/notes.md（数字消失），但数字键聚焦功能本身不受影响。
5.6 文件与 URL 打开工具（openFileUtil / openUrlUtil）
wtf:
openFileUtil: "open"
openUrlUtil:
- "tmux"
- "new-window"
- "elinks"
逐项说明：
openFileUtil：模块内"打开文件"动作（如 textfile 模块按o）调用的本地工具，默认open（macOS 命令）。Linux 服务器上建议改为xdg-open；openUrlUtil：打开 URL 的命令序列，按数组顺序拼成一条命令执行（上例即tmux new-window elinks <URL>）；不配置时 wtfutil 按操作系统默认方式打开。
⚠️ 这两项修改需要重启应用才能生效（官方文档明确说明，与 3.4 节的通用规则一致）。
5.7 显示符号（sigils）
wtf:
sigils:
checkbox:
checked: "x"
unchecked: " "
paging:
normal: "*"
selected: "_"
sigils 定义界面中复选框（checked/unchecked 字符）与分页指示符（当前页/选中页字符）的显示符号，纯外观参数，按默认即可。上例为官方默认值写法，无需配置。
5.8 终端类型（term）
wtf:
term: "xterm-256color"
强制指定 wtfutil 运行时的终端类型，一般留空不配、直接使用终端默认值。⚠️ 只有在确有需要时才配置，且必须写合法的 terminfo 名称（vt100、xterm、xterm-256color、ansi 等）——配了非法值应用会直接崩溃，报错 terminal entry not found（排障实录见 9.3 节）。
六、模块通用参数详解（Common Settings）
以下参数对所有模块通用（写在各模块的配置块内），均有合理默认值、全部可选。这些参数的权威来源是二进制内置帮助（wtfutil -m=<模块名> 输出的通用参数段，见 3.2 节实测），逐项说明如下：
| 参数 | 含义 | 默认值 | 取值 |
|---|---|---|---|
enabled | 是否执行该模块并显示其数据 | false | true / false |
bordered | 是否为该模块绘制边框 | true | true / false |
border | 同 bordered（旧写法），是否绘制边框 | true | true / false |
focusable | 是否可被键盘聚焦 | false（textfile / cmdrunner 等交互模块内置为 true） | true / false |
focusChar | 以数字键 0-9 作为跳转到该模块的快捷键 | 无（按模块启用顺序分配） | 0..9 |
position | 该模块在 grid 中的位置（见下） | 必配 | top / left / height / width |
refreshInterval | 模块数据刷新间隔 | 300s | 正整数 + 时间单位（ns/us/µs/ms/s/m/h，无单位默认秒） |
title | 模块标题栏文字 | 各模块默认标题 | 任意字符串 |
languageTag | 文本本地化的 BCP 47 语言标签 | 无 | 如 zh-CN |
通用参数的标准写法（以一个模块块为例，可直接照抄结构）：
wtf:
mods:
feedreader:
enabled: true
feeds:
- https://news.ycombinator.com/rss
feedLimit: 10
focusable: false
focusChar: 2
position:
top: 2
left: 2
width: 1
height: 1
title: "Hacker News"
refreshInterval: 4h
逐项说明：
enabled: true是模块显示的总开关——漏写它（默认 false）是"配置了模块却不显示"的最常见原因；position四个下标的语义见 5.2 节坐标系统；refreshInterval支持多时间单位：30（30 秒）、15s、4h等写法均合法；focusChar与标题栏显示的数字快捷键（5.5 节）对应，按该数字键即聚焦此模块。
七、核心模块配置详解（实测模块）
本章选取四个零外部依赖（无需 API Key、无需第三方服务）即可跑通的模块做参数详解，全部配置与界面回显均为实测。其余几十个模块（GitHub、Weather、Kubernetes 等）的配置模式与本章一致：先用 wtfutil -m=<模块名> 看内置参数表，再按表填 mods 块。
7.1 clocks（世界时钟）
wtf:
mods:
clocks:
colors:
rows:
even: "lightblue"
odd: "white"
enabled: true
locations:
Beijing: "Asia/Shanghai"
London: "Europe/London"
"New York": "America/New_York"
position:
top: 0
left: 0
height: 1
width: 1
refreshInterval: 15
sort: "alphabetical"
title: "世界时钟"
逐项说明：
| 参数 | 含义 | 默认值 |
|---|---|---|
locations | 世界时钟清单：键为界面显示标签，值为 TZ 数据库时区名（<区域>/<城市>）；含空格的标签需加引号 | 无（必配） |
sort | 排序方式：alphabetical（按键名升序）/ chronological（按时间先后）/ natural（保持配置书写顺序） | 无（不配则按自然顺序） |
dateFormat | 日期列格式，Go 时间布局 | Jan 2 |
timeFormat | 时间列格式，Go 时间布局 | 15:04 MST |
colors.rows.even / odd | 偶数行 / 奇数行文字颜色 | 无（默认白色） |
生效实测（与 5.2 节界面捕获对应）：
│ Beijing 01:44 CST Oct 24 │
│ London 18:44 BST Oct 23 │
│ New York 13:44 EDT Oct 23 │
三行按 sort: "alphabetical" 键名升序排列；timeFormat 默认值 15:04 MST 渲染出 01:44 CST 这样的"24 小时制 + 时区缩写"格式。
⚠️ 时区值必须写 TZ 数据库中存在的名称。写成不存在的时区（如
Bad/Zone）不会崩溃，模块会显示占位提示（实测回显，排障实录见 9.2 节）。
7.2 status（系统状态栏）
wtf:
mods:
status:
enabled: true
position:
top: 0
left: 1
height: 1
width: 1
refreshInterval: 1
status 模块无专属参数，只有一个转轮动画（spinner）显示应用存活状态，每转一格表示一次全局刷新。实测界面（转轮字符位于窗口左上）：
┌────────────────── Status ──────────────────┐
│\ │
└────────────────────────────────────────────┘
refreshInterval: 1 让转轮每秒走一格，是"wtfutil 还活着、刷新循环正常"的直观指示器。
7.3 textfile（文本文件展示）
wtf:
mods:
textfile:
enabled: true
filePath: "~/notes.md"
format: true
position:
top: 0
left: 2
height: 1
width: 1
refreshInterval: 30
wrapText: false
title: "值班备忘"
逐项说明：
| 参数 | 含义 | 默认值 |
|---|---|---|
filePath | 要展示的文本文件路径，支持 ~ 展开；也接受目录（展示目录内文件列表） | 无（必配） |
format | 是否按 Markdown 渲染显示 | false |
wrapText | 长行是否自动换行 | true |
生效实测：~/notes.md 内容为一篇 Markdown 值班备忘，format: true 下 # 标题 与列表项被渲染展示（5.2 节界面捕获第 3 列）；标题栏显示 ~/notes.md 1，末尾数字 1 为自动分配的聚焦快捷键（textfile 内置可聚焦，详见 6 章表格说明）。
textfile 模块的键盘操作（来自 wtfutil -m=textfile 实测输出，完整讨论见本专栏命令篇）：
Keyboard commands for Textfile
\ Open the documentation for this module in a browser
/ Show/hide this help prompt
l Select next file
h Select previous file
o Open file
Right Select next file
Left Select previous file
Enter Open file
7.4 cmdrunner（自定义命令输出）
cmdrunner 是最通用的模块：把任意终端命令的输出搬进仪表盘，是自建监控小部件的首选。
wtf:
mods:
uptime:
type: cmdrunner
enabled: true
cmd: "uptime"
args: []
position:
top: 1
left: 0
height: 1
width: 1
refreshInterval: 30
title: "系统负载"
diskfree:
type: cmdrunner
enabled: true
cmd: "df"
args: ["-h", "/"]
position:
top: 1
left: 1
height: 1
width: 2
refreshInterval: 60
title: "根分区容量"
逐项说明（参数表来自 wtfutil -m=cmdrunner 实测输出）：
| 参数 | 含义 | 默认值 |
|---|---|---|
type | 模块类型声明，同一模块名可用 cmdrunner 复用多份 | 无（多实例时必写） |
cmd | 要执行的命令本体（如 uptime、df），不含参数 | 无（必配） |
args | 命令参数数组，每个元素一个参数 | 无 |
tail | 是否自动滚动到输出末尾 | false |
pty | 是否在伪终端中运行命令（部分命令在 TTY 下才有彩色输出） | false |
ptySuppressErrors | 隐藏 pty 模式下彩色命令的尾部报错 | false |
maxLines | 输出缓冲区保留的最大行数 | 无 |
workingDir | 命令的工作目录 | 当前目录 |
type: cmdrunner 的要点：mods 下的键名（如 uptime、diskfree）是自定义实例名，同一份配置可以定义多个 cmdrunner 实例、每个执行不同命令——上例两个实例分别跑 uptime 与 df -h /。
生效实测（与 5.2 节界面捕获第 2 行对应）：
│ 17:44:01 up 4 days, 1:56, 0 users, load │
│Filesystem Size Used Avail Use% Mounted on │
│overlay 786G 516G 236G 69% / │
uptime 与 df -h / 的标准输出被原样搬进窗口，长行按窗口宽度截断显示（终端里滚动或调整 grid 列宽可看全）。
八、生产配置模板
以下是一份实测跑通的完整 config.yml，适用于"单用户 Linux 服务器 / VPS 日常巡检"场景（1 GB 内存即可流畅运行，纯本地数据源、无外网依赖、无 API Key）：
wtf:
colors:
background: "black"
border:
focusable: "darkslateblue"
focused: "orange"
normal: "gray"
grid:
columns: [46, 46, 46]
rows: [10, 8, 8]
refreshInterval: 1
mods:
clocks:
colors:
rows:
even: "lightblue"
odd: "white"
enabled: true
locations:
Beijing: "Asia/Shanghai"
London: "Europe/London"
"New York": "America/New_York"
position:
top: 0
left: 0
height: 1
width: 1
refreshInterval: 15
sort: "alphabetical"
title: "世界时钟"
status:
enabled: true
position:
top: 0
left: 1
height: 1
width: 1
refreshInterval: 1
textfile:
enabled: true
filePath: "~/notes.md"
format: true
position:
top: 0
left: 2
height: 1
width: 1
refreshInterval: 30
wrapText: false
title: "值班备忘"
uptime:
type: cmdrunner
enabled: true
cmd: "uptime"
args: []
position:
top: 1
left: 0
height: 1
width: 1
refreshInterval: 30
title: "系统负载"
diskfree:
type: cmdrunner
enabled: true
cmd: "df"
args: ["-h", "/"]
position:
top: 1
left: 1
height: 1
width: 2
refreshInterval: 60
title: "根分区容量"
模板要点解读：
- 适用场景：服务器巡检大屏——世界时钟（多时区协作）、存活转轮、值班备忘（Markdown 渲染）、负载与根分区容量；全部数据源零外部依赖；
- 布局容量：3 列 × 2 行的 grid 占满约 140×20 以上的终端窗口，列宽 46 在 180 列终端下留有余量；
- 刷新率分层：全局 1 秒（status 转轮），模块级 15/30/60 秒按数据变化频率递增，兼顾实时性与终端流畅度；
- 扩展路径：加一块自定义巡检项就是再复制一段
type: cmdrunner块改cmd/args/position（注意先在grid.columns/rows里补容量）。
写入并启动：
cp config.yml ~/.config/wtf/config.yml
wtfutil
界面渲染效果即 5.2 节的实测捕获（5 个模块窗口：世界时钟 / Status / 值班备忘 / 系统负载 / 根分区容量）。
九、常见问题（FAQ）
9.1 配置了模块但界面上不显示
最常见原因是漏写 enabled: true（Common 参数默认 false，见第六章）。其次检查：position 是否超出 grid.columns/rows 定义的格区数量（如配置了 3 列却把 left 写成 3）；配置文件是否真的被加载（echo $WTF_CONFIG 看环境变量是否残留指向了别的文件，见 3.1 节实测发现）。
9.2 clocks 模块显示 no timezone data available
错误现象：界面世界时钟窗口显示 no timezone data available。
定位：locations 的时区值不是合法 TZ 数据库名称。实测配置 Nowhere: "Bad/Zone" 后界面回显：
│ no timezone data available
解决：改为 /usr/share/zoneinfo/ 下真实存在的时区路径（如 Asia/Shanghai），重启即恢复。该错误只影响对应时钟行，应用不会崩溃。
9.3 启动报 terminal entry not found
错误现象：启动即退出，报错：
ERROR terminal entry not found: term not set
定位：两类原因——其一，运行环境没有设置 TERM 环境变量（如某些非交互执行场景，echo $TERM 输出为空）；其二，配置文件 wtf.term 写了不存在的终端类型。本文实测中，在未设 TERM 的环境启动即复现上述报错；官方文档同样明确"为 term 提供非法值将导致应用崩溃并报 terminal entry not found"。
解决：执行环境里导出合法终端类型（export TERM=xterm-256color）后启动；若在配置中设置了 wtf.term，删除该项或改为合法值。
9.4 启动报 Could not load '/root/broken.yml'
错误现象：
ERROR Could not load '/root/broken.yml'.
This could mean one of two things:
1. That file doesn't exist.
2. That file has a YAML syntax error. Try running it through http://www.yamllint.com to check for errors.
Error: yaml: line 5: mapping values are not allowed in this context
定位：配置文件路径不存在，或 YAML 语法错误。报错最后一行 yaml: line 5: ... 会指出语法错误所在行号（实测的 broken.yml 第 5 行缩进层级写错）。解决：按行号修复缩进——YAML 对缩进敏感，同层键必须对齐；也可把文件内容贴到 yamllint.com 做语法检查（报错信息中官方给的建议）。
9.5 exitMessage.display 设为 false 后退出仍有 ASCII 艺术字
见 5.4 节实测发现：v0.51.0 中该开关实测未生效，属官方文档与实际行为的偏差。规避方式：接受该消息，或在脚本化场景改用后台会话（tmux/screen）承载 wtfutil，退出消息不影响使用。
9.6 WTF_CONFIG 与 --config 同时存在时用哪个
--config 命令行参数优先。若发现"明明传了 --config 却加载了别的配置"，先 echo $WTF_CONFIG 确认环境变量残留情况，必要时 unset WTF_CONFIG（实测行为见 3.1 节）。
十、参考链接
- WTFUtil 官方文档站（Configuration 章节）：https://wtfutil.com/
- 配置文件说明：https://wtfutil.com/configuration/files/
- 全局设置说明：https://wtfutil.com/configuration/global_settings/
- 模块通用设置说明：https://wtfutil.com/configuration/common_settings/
- Grid 布局说明：https://wtfutil.com/configuration/grid_layout/
- GitHub 仓库（含
_sample_configs/示例配置目录）：https://github.com/wtfutil/wtf - 本专栏相关文档：《WTFUtil 介绍与选型指南》（定位与选型）、《Ubuntu 22.04 安装 WTFUtil 0.51.0 指南》（安装与排障）、命令行参数与运行时快捷键见本专栏《WTFUtil 0.51.0 常用命令与快捷键详解》。