配置¶

配置文件描述整个机器人：Telegram 连接、允许使用的用户、按钮菜单和日志。您可以使用 --config 将其传递给读取它的命令 - run、validate、 fmt 和 list-functions（请参见 CLI）。

所有键都使用 lower_snake_case。未知键会被拒绝，因此拼写错误会在验证时立即显示。

必填表示如果此字段丢失或为空，则验证失败应用默认值。
可选字段可以省略；默认列显示当时使用的内容。

刚接触本项目？请从在 CLI 中运行开始，其中会逐步创建第一份配置。下文术语详见概念。

最小配置¶

仅telegram（带有一个令牌和一个允许的用户）需要 menu。其他一切都有默认值：

以一名允许的用户和三个状态按钮启动

config.yaml (minimal)

telegram:
  bot_token: "YOUR_BOT_TOKEN"
  allowed_users:
    - "123456789"

menu:
  - name: System Status
    type: category
    icon: "🖥️"
    items:
      - name: Uptime
        type: button
        icon: "🕒"
        function: command
        command: "uptime"
      - name: Memory
        type: button
        icon: "🧮"
        function: command
        command: "free -h"
      - name: Disk Space
        type: button
        icon: "💾"
        function: command
        command: "df -h /"

该版本中的 config-examples/ 文件夹包括最小的和完整的示例。

根字段¶

字段	类型	必填	默认值	描述
`telegram`	对象	是	—	Telegram 设置（见下文）
`menu`	列表	是	—	菜单树；至少一个节点
`function_directory`	字符串	否	未设置	自定义函数YAML目录（见下面的规则）
`shell`	字符串	否	`/bin/bash`	Shell 用作 `shell -c "<command>"`
`timeout`	时长	否	`60s`	默认命令超时
`max_output_bytes`	整数	否	`524288`	每个命令保留的最大输出（请参阅可查看的命令输出量和控制输出）
`output`	`auto` \| `text` \| `file`	否	`auto`	命令结果的送达方式（请参阅可查看的命令输出量和控制输出）
`max_output_messages`	整数	否	`2`	仅根级。在 `auto` 模式下，当结果需要超过该条数的消息时改为发送 `.txt` 文件（1–10）。省略则保持 `2`。参见控制输出
`workdir`	字符串	否	进程cwd	命令的默认工作目录
`env`	映射	否	空	命令的额外环境变量
`menu_columns`	整数	否	`2`	消息框下方每行的项目按钮
`page_size`	整数	否	`8`	分页前每页的项目数
`confirm_ttl`	时长	否	`5m`	confirmation 提示保持有效的时间有多长
`delivery_retry_backoff`	时长	否	`1s`	仅根级。发送失败后首次重试前的初始等待时间。参见投递重试
`delivery_retry_backoff_max`	时长	否	`30s`	仅根级。重试之间的最长等待时间。参见投递重试
`delivery_retry_ttl`	时长	否	`2m`	仅根级。机器人放弃前持续重试的总时长（仅记录在服务器日志中）。参见投递重试
`enable_run_command`	布尔值	否	`false`	显示 `$ >_ Run Command` 按钮，将下一条消息作为 shell 命令运行。默认关闭。任何可使用机器人的人都能在主机上运行任意命令，因此只能在信任所有允许用户时启用。此键放在 `telegram` 下无效。
`logging`	对象	否	内置默认记录器	命名记录器（见下文）

如果我省略 shell 会怎样？

你可以省略它。该机器人使用 /bin/bash。与 timeout、page_size 相同，和其他可选根字段：忽略它们并应用默认值。你只需要当您想要非默认值时设置它们（例如 shell: /bin/sh）。

您看到多少命令输出¶

两个限制依次适用。max_output_bytes 是您的限制，叠加在您无法更改的 Telegram 限制之上。

1.您的限制：max_output_bytes（默认 524288，因此 512 KB）

命令运行时，机器人最多保留这么多输出，普通输出与错误输出分别计算。超出部分会被丢弃，但命令本身会继续跑到结束或碰到 timeout。发生这种情况时，结果以 (output truncated) 开头。

2.结果如何送达：output（默认 auto）

Telegram 单条消息最多 4096 字节。机器人可以把长结果拆成多条回复消息，或把完整输出作为 .txt 文件发送。用根配置里的 output 选择模式，或在单个按钮上覆盖：

取值	行为
`auto`	结果能装进 `max_output_messages` 条消息（默认 `2`）时用文本；若需要更多，则发送一个 `.txt` 文件。
`text`	始终拆成文本消息。仍会在 10 条后停止并注明被截断。
`file`	始终发送一个带简短说明（按钮名、退出码、耗时）的 `.txt` 文件。

在 auto 与 file 模式下，文件包含页眉以及 stdout 与 stderr，因此提高 max_output_bytes 会真正送达更多输出。若发送文件失败，机器人会先自动重试，只有放弃后才会回退到文本消息路径。参见投递重试。

不必写 output 或 max_output_messages。省略时机器人使用 auto 和 2。已经能用的配置保持不变。max_output_messages 只存在于根级。按钮上省略 output 即使用根值；仅当该按钮应始终发文件或始终保持文本时再写。

对于很长的日志，优先使用 output: auto（默认）或在该按钮上设置 output: file。若只需日志尾部，仍可缩短命令本身。

`function_directory` 规则¶

情况	结果
缺少键	信息日志；仅内置函数
键存在但为空 (`""`)	信息日志；仅内置函数
键设置为不存在或不可访问的路径	硬错误；进程停止
路径存在但目录为空	好的

错误路径会阻止机器人启动

如果function_directory指向的文件夹不存在或无法访问阅读，程序因错误而停止，而不是在没有您的情况下启动自定义函数。

`telegram`¶

字段	类型	必填	默认值	描述
`bot_token`	字符串	是	—	来自 BotFather 的 Bot 令牌
`allowed_users`	字符串列表	是	—	允许的用户
`api`	字符串	否	`https://api.telegram.org`	机器人 API 基本 URL
`proxy.enabled`	布尔值	否	`false`	使用 Telegram API 代理
`proxy.url`	字符串	条件必填	—	`proxy.enabled` 为 `true` 时必填
`insecure`	布尔值	否	`false`	跳过 TLS 验证（不推荐）

未经授权的用户会收到一条包含 user_id 和 username 的消息，以便他们可以向管理员请求访问权限。这也是您第一次找到自己的 id 的方法 — 请参阅 CLI 中的 Run → 步骤 5。

通过代理连接

telegram section with a proxy

telegram:
  bot_token: "123456789:AAExampleTokenValue"
  allowed_users:
    - "123456789"        # 用户数字 id
    - "@alice"           # 或用户名
  proxy:
    enabled: true
    url: "socks5://127.0.0.1:10808"

要让允许的用户从 Telegram 键入 shell 命令，请将其设置在文件的 root 下（而不是在 telegram 下）：

添加一根设置

Enable the Run Command button

enable_run_command: true

本节提供字段参考。带示例的分步说明详见菜单。每个按钮或分类节点：

字段	类型	必填	描述
`name`	字符串	是	显示名称（兄弟姐妹中唯一，不区分大小写）
`type`	`category` \| `button`	是	节点种类
`items`	列表	是，如果 `category`	子节点；分类必须至少包含一个
`function`	字符串	是，如果 `button`	函数名称
`command`	字符串	是，如果 `function: command`	内置`command`的Shell命令
`path`	字符串	是，如果 `function: script`	内置`script`的脚本路径
`icon`	字符串	否	可选的表情符号前缀
`id`	字符串	否	该节点的可选 ID。你可以省略它
`confirm`	布尔值	否	运行前询问确认（默认`false`）
`timeout`	时长	否	覆盖全局超时
`workdir`	字符串	否	覆盖工作目录
`env`	映射	否	此按钮的额外环境
`columns`	整数	否	覆盖此类别的列
`output`	`auto` \| `text` \| `file`	否	可选。省略则使用根级 `output`。仅在要强制此按钮为 `file` 或 `text` 时再写（请参阅可查看的命令输出量和控制输出）
`args`	字符串	否	`script` 的可选参数
任何声明的参数名称	标量	正如函数所声明的	传递给所选函数的值，例如 `url`、`host`、`unit` 或 `lines`

在按钮上，任何其他标量键都被视为函数参数。其名称必须与所选函数声明的参数匹配。未知参数名称失败 validate。声明为 int 的值或 bool 也已检查。字符串、数字和布尔值可以直接写入作为 YAML 值；数字不需要引号。

在分类上，上述分类字段之外的任何键都是错误的。分类不运行函数，因此不能包含参数键。

command、path 和 args 是用以下参数填充参数的快捷字段相同的名字。其他参数名称直接写在按钮上。不要将按钮值放置在嵌套的 params: 映射内。参见函数 → 从按钮传递值。

`logging`¶

可选。如果省略，则使用 stderr 上 info 上的默认控制台记录器。

命名记录器：

写入正常日志和审计文件

logging section with an audit file

logging:
  logs:
    default:
      level: info
      format: console   # 或 JSON
      output:
        - output: stderr
    audit:
      level: info
      format: json
      output:
        - output: file
          file: /var/log/telegram-commander/audit.log

支持的输出：stdout、stderr、file、discard。

上面显示的 audit 日志记录器会记录每次命令运行（用户、按钮、退出代码和耗时）。详见审计日志。

配置¶

最小配置¶

根字段¶

您看到多少命令输出¶

`function_directory` 规则¶

`telegram`¶

菜单¶

`logging`¶

相关页面¶

配置¶

最小配置¶

根字段¶

您看到多少命令输出¶

function_directory 规则¶

telegram¶

菜单¶

logging¶

相关页面¶

`function_directory` 规则¶

`telegram`¶

`logging`¶