控制输出¶

按钮运行结束后，机器人需要把结果送到您的聊天里。 Telegram 单条消息最多只接受 4096 字节，所以较长的结果要么以多条回复消息 到达，要么作为一个 .txt 文件送来，您可以打开并下载它。

有三个可选字段决定结果如何送达。您可以一个都不写，机器人依然会有合理的表现。

只需记住一条规则

按钮优先。如果按钮设置了 output，就按它执行。如果按钮没写，就用根级的值。如果根级也没写，机器人使用 auto。

max_output_bytes

在发送任何内容之前，从命令保留多少输出。

了解更多
output

消息还是文件。唯一也能写在按钮上的字段。

了解更多
max_output_messages

在 auto 模式下，发送文件之前允许多少条消息。

了解更多

本页每张图片都可以放大

聊天截图特意做得比较小。点击其中一张即可查看原始大小。

三个字段一览¶

字段	写在哪里	类型	默认值	决定什么
`max_output_bytes`	仅根级	整数	`524288`	机器人为每个命令保留多少字节的输出
`output`	根级和按钮	`auto` \| `text` \| `file`	`auto`	结果以聊天消息到达，还是作为一个 `.txt` 文件
`max_output_messages`	仅根级	整数，`1`–`10`	`2`	在 `auto` 模式下，改为发送文件之前允许的消息条数

这三个字段都写在配置文件的根级，与 shell 和 timeout 并列，而不是放在 telegram 下面。完整的根级键列表见配置页面。

`max_output_bytes`¶

这是您自己的限制，并且最先生效。命令运行时，机器人最多保留这么多字节的输出，普通输出与错误输出分别计算。超出的部分会被丢弃，但命令本身会继续运行，直到结束或碰到它的 timeout。

每个命令最多保留 2 MB 输出

config.yaml

max_output_bytes: 2097152 # (1)!

2 MB，而不是默认的 512 KB。普通输出与错误输出分别计算。

您在聊天里看到的内容

达到限制时，结果会在摘要下方单独一行说明这一点。(output truncated) 上面的部分是机器人保留下来的内容；其余日志从未离开服务器。

只有发送文件时，调大它才有意义

一条聊天消息永远装不下超过 4096 字节的内容，所以更大的 max_output_bytes 只有在结果以 .txt 文件到达时才能完整送到您手里。请与 output: auto（默认）或 output: file 搭配使用。

`output`¶

output 选择送达方式。它接受三个取值，也是唯一可以写在单个按钮上的输出字段。

autotextfile

结果较短时用文本消息，较长时用一个 .txt 文件。这是默认行为，也是您什么都不写时保留的取值。

让机器人为每个结果自行判断

config.yaml

shell: /bin/bash
timeout: 60s
output: auto # (1)!
max_output_messages: 2 # (2)!

按每个结果分别决定，而不是强制一种送达方式。
切换点。两条消息以内留在聊天里；更长的内容变成一个文件。

无论结果多长，始终发聊天消息。机器人在十条消息后停止，并附上一条说明其余内容已被截断。

把所有内容都留在聊天里

config.yaml

shell: /bin/bash
timeout: 60s
output: text # (1)!

这里会忽略 max_output_messages，因为机器人永远不会自行切换到文件。

始终一个 .txt 文件，哪怕结果只有一行。摘要会作为文件说明一同送来。

把每个结果都作为附件发送

config.yaml

shell: /bin/bash
timeout: 60s
output: file # (1)!

现在每个按钮都会发送附件，包括那些很快的按钮。如果这样太多，请改为写在单个按钮上。

省略它等同于写 auto

您从来不必写 output。在这个字段出现之前就能用的配置，行为完全不变。

`max_output_messages`¶

这个字段只在 auto 模式下起作用，而且只存在于根级。它表示机器人在放弃消息、改为发送一个文件之前，愿意发送多少条聊天消息。允许的取值是 1 到 10，默认是 2。

结果一旦需要第二条消息就发文件

config.yaml

output: auto
max_output_messages: 1 # (1)!

最严格的设置。只有能装进一条消息的结果才会留在聊天里。

您在聊天里看到的内容

在允许条数以内的结果会作为聊天消息留下。一旦再多需要一条消息，整个结果就会改为作为一个 .txt 文件到达，并且不会发送任何零散的消息。

这是一个仅根级的字段

按钮不能设置 max_output_messages。请把它写在根级，让需要不同行为的按钮设置 output: text 或 output: file。

根级与按钮一起生效¶

按钮可以带上自己的 output。关于输出，按钮能设置的只有这一项。最终生效的模式就是：

如何选出生效的模式

Order of precedence

button output  →  root output  →  auto

根级 `output`	按钮 `output`	实际发生什么
未设置或 `auto`	未设置	`auto`
未设置或 `auto`	`auto`	`auto`
未设置或 `auto`	`text`	`text`
未设置或 `auto`	`file`	`file`
`text`	未设置	`text`
`text`	`auto`	`auto`
`text`	`text`	`text`
`text`	`file`	`file`
`file`	未设置	`file`
`file`	`auto`	`auto`
`file`	`text`	`text`
`file`	`file`	`file`

下面各节逐一讲解这十二种组合，每种配一个示例。

当根级是 `auto` 时¶

这也包括根级什么都没写的情况，因为缺少 output 就表示 auto。

根级是 `auto`，按钮没写¶

最常见的情况。较短的结果留在聊天里；需要超过 max_output_messages 条消息的结果会作为文件到达。

普通根级下的普通按钮

config.yaml

output: auto
max_output_messages: 2

menu:
  - name: Disk usage
    type: button
    function: command
    command: "df -h"

您在聊天里看到的内容

df -h 只打印几行，所以能装进一条消息，作为代码块留在聊天里，上面带着摘要。

根级是 `auto`，按钮写 `auto`¶

在这里，在按钮上写 auto 不会改变任何行为。只有当您希望这个按钮无论根级以后变成什么都保持 auto 时，才值得写上它。

在按钮上写明默认值

config.yaml

output: auto

menu:
  - name: Disk usage
    type: button
    function: command
    command: "df -h"
    output: auto # (1)!

今天的行为与不写一样，但即使根级以后改成 text 或 file，这个按钮仍然保持原样。

您在聊天里看到的内容

完全是自动行为：结果短时用文本，超过允许条数后用一个文件。在挂载了很多磁盘的服务器上，同一个按钮也可能发给您一个文件。

根级是 `auto`，按钮写 `text`¶

适合那些您总想直接在聊天里阅读的按钮，哪怕输出稍微长一点 —— 比如一份您愿意滚动浏览而不是下载的状态列表。

让一个按钮留在聊天里

config.yaml

output: auto

menu:
  - name: Service status
    type: button
    function: command
    command: "systemctl status nginx --no-pager"
    output: text # (1)!

无论 max_output_messages 是多少，都不会变成文件。

您在聊天里看到的内容

结果被拆成多条消息，每条都回复上一条，所以顺序不会乱。按钮留在最后一部分上。

根级是 `auto`，按钮写 `file`¶

日志和备份的典型选择：您几乎从不想在聊天里读它们，而文件更方便保存。

这一个总是下载

config.yaml

output: auto

menu:
  - name: Nginx logs
    type: button
    function: command
    command: "journalctl -u nginx -n 2000 --no-pager"
    output: file # (1)!

菜单其余部分仍然自动判断。只有这个按钮被固定为文件。

您在聊天里看到的内容

一个附件，说明文字里带着按钮名称、退出码和耗时。点击它可以阅读整份日志，也可以留着以后看。

当根级是 `output: text` 时¶

除非按钮另有说明，否则每个按钮都留在聊天里。如果您不喜欢在手机上下载文件，就选这个。

根级是 `text`，按钮没写¶

到处都是聊天消息

config.yaml

output: text

menu:
  - name: Uptime
    type: button
    function: command
    command: "uptime"

您在聊天里看到的内容

一条短消息，因为 uptime 只打印一行。更长的结果只会被拆成更多消息，最多十条。

根级是 `text`，按钮写 `auto`¶

这个按钮重新启用自动切换，所以即使菜单里其他按钮从不发文件，它也可能发。切换点由根级的 max_output_messages 决定。

允许一个按钮在输出变长时发文件

config.yaml

output: text
max_output_messages: 3 # (1)!

menu:
  - name: Package list
    type: button
    function: command
    command: "dpkg -l"
    output: auto

只有这个按钮会读取这个允许条数，因为只有它处于 auto 模式。

您在聊天里看到的内容

较短的软件包列表最多以三条消息到达。在装满软件的服务器上，同一个按钮会超过允许条数，改为发送一个文件。

根级是 `text`，按钮写 `text`¶

与不写一样，但把意图写了下来。在很长的配置里很有用，因为您不希望以后改动根级时连带改变这个按钮。

把一个按钮固定为聊天消息

config.yaml

output: text

menu:
  - name: Last logins
    type: button
    function: command
    command: "last -n 20"
    output: text

您在聊天里看到的内容

始终是聊天消息，最多十条，无论以后把根级改成什么。

根级是 `text`，按钮写 `file`¶

只发聊天消息的菜单里，有一个可下载的按钮

config.yaml

output: text

menu:
  - name: Full system report
    type: button
    function: command
    command: "/usr/local/bin/report.sh"
    output: file
    timeout: "5m" # (1)!

报告可能要跑一会儿，所以这个按钮的超时比全局超时更长。

您在聊天里看到的内容

在一个原本只发消息的菜单里，这是唯一的附件。说明文字会显示报告用了多长时间，当它跑上几分钟时很有用。

当根级是 `output: file` 时¶

每个结果都是文件，哪怕只有一行。这适合主要用来出报告和存档的机器人。

根级是 `file`，按钮没写¶

到处都是文件

config.yaml

output: file

menu:
  - name: Uptime
    type: button
    function: command
    command: "uptime"

您在聊天里看到的内容

即使只有一行输出也会作为附件到达。说明文字里仍然带着摘要，所以不打开文件也能看到退出码。

连很小的结果也会变成下载

一行答案也会作为需要打开的附件到达。如果这让您觉得麻烦，请把根级留在 auto，只在需要的按钮上写 output: file。

根级是 `file`，按钮写 `auto`¶

这个按钮跳出了只发文件的规则，重新恢复正常行为。

让一次快速检查保持可读

config.yaml

output: file
max_output_messages: 2

menu:
  - name: Uptime
    type: button
    function: command
    command: "uptime"
    output: auto # (1)!

只有这个按钮回到自动切换。

您在聊天里看到的内容

这条只有一行的答案很短，所以它作为消息留在聊天里，而菜单中其他按钮仍然发送文件。

根级是 `file`，按钮写 `text`¶

强制一个按钮回到聊天里

config.yaml

output: file

menu:
  - name: Who is logged in
    type: button
    function: command
    command: "who"
    output: text

您在聊天里看到的内容

无论登录用户的列表变得多长，都是消息，永远不是附件。超过十条消息时，机器人会注明其余内容已被截断。

根级是 `file`，按钮写 `file`¶

重复根级的取值。这没有坏处，而且以后放宽根级时，这个按钮依然正确。

一个必须始终是文件的按钮

config.yaml

output: file

menu:
  - name: Database dump log
    type: button
    function: command
    command: "cat /var/log/pg_dump.log"
    output: file

您在聊天里看到的内容

一个附件，正如根级已经要求的那样。把它写在按钮上，可以让这个意图在根级改动后依然保留。

文件是什么样的¶

当结果以文件送达时，您会收到一个附件和一段简短的说明文字。

名称 —— 按钮名称转成小写并用连字符连接，然后是 UTC 的日期和时间，例如 nginx-logs-20260913-091204.txt。
说明文字 —— 与聊天消息顶部相同的摘要：按钮名称、退出码、耗时，以及出现超时或截断时的提示。
正文 —— 再次是那段摘要，然后是 --- stdout --- 部分；当命令向错误输出写过内容时，还有 --- stderr --- 部分。

下载的文件里面

nginx-logs-20260913-091204.txt

Button: Nginx logs
Exit: 0
Duration: 316ms

--- stdout ---
2026-09-13T09:11:58 nginx: worker process started
...

--- stderr ---
2026-09-13T09:12:01 nginx: warning: duplicate server name

您无法更改的限制¶

上限由 Telegram 决定，不是机器人

一条聊天消息最多 4096 字节。
在 text 模式下，机器人最多发送十条消息，并以 (output too long; showing first N bytes) 结束。
无论您把 max_output_messages 写成多少，十条消息仍然是硬上限。

发送失败时，机器人会先重试

当文件发不出去时 —— 没有网络，或者 Telegram 要求放慢速度 —— 机器人会自动重试，等待时间逐渐变长。只有放弃后才会回退到聊天消息，这样短暂中断不会丢失结果。参见投递重试。

运行命令使用根级设置¶

$ >_ Run Command 按钮不属于您的菜单，因此它没有自己的 output。它始终跟随根级的 output 和 max_output_messages。参见菜单 → 运行命令。

控制输出¶

三个字段一览¶

max_output_bytes¶

output¶

max_output_messages¶

根级与按钮一起生效¶

当根级是 auto 时¶

根级是 auto，按钮没写¶

根级是 auto，按钮写 auto¶

根级是 auto，按钮写 text¶

根级是 auto，按钮写 file¶

当根级是 output: text 时¶

根级是 text，按钮没写¶

根级是 text，按钮写 auto¶

根级是 text，按钮写 text¶

根级是 text，按钮写 file¶

当根级是 output: file 时¶

根级是 file，按钮没写¶

根级是 file，按钮写 auto¶

根级是 file，按钮写 text¶

根级是 file，按钮写 file¶

文件是什么样的¶

您无法更改的限制¶

运行命令使用根级设置¶

相关¶

`max_output_bytes`¶

`output`¶

`max_output_messages`¶

当根级是 `auto` 时¶

根级是 `auto`，按钮没写¶

根级是 `auto`，按钮写 `auto`¶

根级是 `auto`，按钮写 `text`¶

根级是 `auto`，按钮写 `file`¶

当根级是 `output: text` 时¶

根级是 `text`，按钮没写¶

根级是 `text`，按钮写 `auto`¶

根级是 `text`，按钮写 `text`¶

根级是 `text`，按钮写 `file`¶

当根级是 `output: file` 时¶

根级是 `file`，按钮没写¶

根级是 `file`，按钮写 `auto`¶

根级是 `file`，按钮写 `text`¶

根级是 `file`，按钮写 `file`¶