跳到主要内容

Telegram 设置

本页端到端地配置 Telegram 渠道：创建机器人凭据、写入渠道配置、启动常驻网关、用 doctor 检查进行验证，并调整访问策略、会话、媒体、命令以及定时（cron）投递。

关于各渠道如何协同工作的整体视角，参见 消息网关总览。Telegram 配置字段的完整 列表，参见 渠道参考。

概述​

Anyy 以机器人账号身份接入 Telegram，并通过 HTTPS 与 Bot API 通信。适配器使用长轮询 （getUpdates），因此 Telegram 无需主动连接你的主机，你也不需要公网地址、Webhook 或反向代理。 私聊与群聊均受支持，入站的图片、文档与语音消息也受支持，并在一轮处理进行时显示“正在输入”指示。

身份与路由遵循标准的渠道模型：每个 Telegram 会话都映射到形如 telegram:<account_id>:<chat_id> 的稳定 Anyy 身份，且每个会话拥有各自独立的 session。

备注

Anyy 在对话中始终以 Anyy 的身份呈现。Bot API token 仅用于向 Telegram 认证你的 机器人，并不会改变助手的身份。

前提条件​

  • 已安装 Anyy，且 anyy CLI 在你的 PATH 中（anyy --version）。
  • 一个 Telegram 账号以及官方 Telegram 客户端（移动端或桌面端），用于与 @BotFather 对话。
  • 来自 BotFather 的机器人 token（将在下一节创建）。请将该 token 视为机密。
  • 一台能够持续运行常驻网关的主机 —— 参见 以常驻服务方式运行。

配置​

整体流程为：用 BotFather 创建机器人、用 setup 命令写入渠道配置、启动网关，然后运行 doctor 检查。

创建凭据​

  1. 在 Telegram 中打开与 @BotFather 的会话。
  2. 发送 /newbot 并按提示操作：先取一个显示名称，再取一个以 bot 结尾的用户名（例如 my_anyy_bot）。
  3. BotFather 会回复一个形如 123456789:AA... 的 HTTP API token。复制它。下文中作为 <BOT_TOKEN> 传入的就是这个值。
  4. 可选、推荐的设置（仍在 BotFather 会话中）：
    • 若要让机器人读取群里的全部消息（而不仅是回复/提及），发送 /setprivacy，选择你的 机器人，再选 Disable。如果你只希望机器人在群里对提及和回复作出响应，则保持隐私模式 Enabled。
    • 发送 /setjoingroups 以控制机器人能否被加入群组。
    • 用 /setcommands 发布你对外暴露的斜杠命令（参见 命令）。
注意

机器人 token 拥有对你机器人的完全控制权。切勿将其粘贴到聊天中、提交到版本控制，或出现在日志、 截图或错误报告中。如果泄露，向 BotFather 发送 /revoke（或 /token）以轮换，然后更新所存的 机密。Anyy 将 token 作为 profile 本地机密文件（权限 0600）存储，配置中仅保留 secret: 引用；原始 token 永远不会写入配置。

配置 Anyy​

用一条命令写入 Telegram 配置块并将 token 存为受管机密。把 <BOT_TOKEN> 替换为 BotFather 给出的 token：

anyy setup channels telegram \
  --secret token='<BOT_TOKEN>' \
  --write-config

该命令会：

  • 将 token 作为 profile 本地机密存储在 telegram/personal/token，并在配置中记录引用 token_ref: secret:telegram/personal/token。
  • 因为带了 --write-config，向 config.yaml 写入一个 channels.telegram 配置块。
  • 打印一段 JSON 摘要，其中包含解析出的 config_path 以及接下来要运行的精确 doctor_command。

生成的配置块使用以下默认值：

channels:
  telegram:
    enabled: true
    account_id: personal
    token_ref: secret:telegram/personal/token
    dm_policy: pairing
    group_policy: mention
    allow_from: []
    allow_groups: []
    media_max_bytes: 5242880

常用参数（--help 仅打印一行简略用法，因此像 --force 这类参数虽可接受，但并不会列在其中）：

  • --account-id ID —— 本地账号标签（默认 personal）。它会成为身份和机密路径的一部分，因此 修改它会改变 token 的存储位置。
  • --secret token=<BOT_TOKEN> —— 机器人 token。可重复指定以提供其他机密，但 Telegram 只需要 token。
  • --set NAME=VALUE —— 覆盖或新增一个字符串配置字段，例如 --set dm_policy=allowlist 或 --set bot_username=my_anyy_bot。可重复指定。不能用 --set 覆盖 token_ref；凭据请 使用 --secret。
  • --write-config —— 实际写入配置块。不带它时，命令仅做一次试运行，只打印将要写入的内容（机密 仍会被写入）。
  • --force —— 替换已存在的 channels.telegram 配置块，而不是直接失败。
  • --home PATH / 全局 --profile NAME —— 指向特定的 Anyy home/profile。
提示

不带 --write-config 运行时，预览的只是配置块——机密文件仍会被写入。--write-config 控制的 是 config.yaml 配置块，而非机密；无论是否带该参数，token 都会被存储。若想先暂存机密、之后再写入 配置块，可先不带 --write-config 运行一次，再带着它重新运行。

将 bot_username 设为你机器人去掉 @ 后的精确用户名（通过 --set bot_username=... 或直接 编辑配置）。在默认的 mention 策略下，群聊中 Anyy 正是据此识别消息是否提及了它 （@my_anyy_bot）。

启动 Gateway​

渠道在常驻网关内运行。启动网关（或在修改配置后重启）：

anyy gateway start
anyy gateway status

gateway status 应当显示服务正在运行。如果网关已在运行，而你只是修改了渠道配置，可以不必完全 重启即可应用：

anyy channels reload

要让网关在重启后仍保持存活，请将其安装为系统服务 —— 参见 以常驻服务方式运行。

运行 Doctor 检查​

用渠道 doctor 验证 Telegram 接线：

anyy channels doctor telegram

加 --json 可获得机器可读输出，加 --home PATH 可指向特定 home。人类可读输出分为三个部分：

  • Channel doctor —— 解析出的 home 与配置文件。
  • Checks —— 各渠道的配置探测（配置存在、机密引用可解析等）。
  • Live smoke —— 渠道是否已配置并启用，以及一次实况冒烟运行是否会连接 Telegram API （Will contact）。doctor 本身不会发送消息；它只报告计划。

setup 命令的 JSON 输出中也会打印精确的 doctor_command（含解析出的 --home），可直接复制。

访问策略​

两条相互独立的策略决定哪些入站消息被接受：dm_policy 用于私聊，group_policy 用于群组和超级群。 两者都在创建 session 之前执行，且每次拒绝都会记录到渠道状态中以便观测。

私信​

dm_policy 接受以下取值之一：

  • open —— 接受任何向机器人发消息的发送者的私聊。
  • allowlist —— 仅接受其数字 Telegram 用户 ID 列在 allow_from 中的发送者。
  • pairing —— 仅接受已知（已配对）的身份。
  • disabled —— 拒绝所有私聊。

setup 默认值为 pairing。

注意

在当前构建中，交互式的配对令牌签发尚未接通：/pair 命令与配对 RPC 处于保留状态，会返回 “pairing is not configured”。在配对签发上线之前，请使用 allowlist（把你的数字用户 ID 填入 allow_from）或 open，以便你自己的私聊能被接受。

对于私有的单用户助手，最简单且可用的配置是 allowlist：

channels:
  telegram:
    dm_policy: allowlist
    allow_from:
      - "123456789"   # 你的数字 Telegram 用户 ID

你可以通过向 @userinfobot 这类机器人发消息来查到自己的数字用户 ID，或在发送一条消息后从渠道 状态/审计中读取（拒绝记录中带有 sender_id）。修改后运行 anyy channels reload。

群组​

group_policy 接受以下取值之一：

  • disabled —— 忽略所有群消息。
  • mention —— 仅在机器人被提及（@<bot_username>）时响应 —— 默认值。
  • allowlist —— 仅在其数字会话 ID 列在 allow_groups 中的群里响应。
  • open —— 在机器人所在的群里对每条消息都响应。
  • pairing —— 仅在已知（已配对）的群里响应（同样受上文所述配对限制影响）。

在默认的 mention 策略下，请设置 bot_username 以使提及检测生效，并把机器人加入群组。Telegram 的机器人隐私模式同样重要：隐私开启时（BotFather 默认），机器人只会收到提及它或回复它的消息， 这与 mention 天然契合。如果你希望 open 能看到每条消息，请在 BotFather 中关闭隐私模式。

channels:
  telegram:
    group_policy: allowlist
    allow_groups:
      - "-1001234567890"   # 数字（超级）群会话 ID

管理员​

在渠道层并不存在独立的“Telegram 管理员”角色；访问完全由上面的策略与白名单治理。运维控制（网关 生命周期、配置、机密、审批）通过主机上的 anyy CLI 行使，且无论操作由哪个渠道发起，审批与 审计语义都适用于会改变状态的操作。

聊天内审批对所有被策略放行的人开放：已配对或在白名单中的用户可以在 Telegram 中运行 /approve 与 /deny（参见 命令）。如果你依赖此机制，请把 dm_policy/group_policy 收紧，因为它 实质上授予了审批权限。

Sessions​

每个 Telegram 会话都映射到各自独立的 Anyy session，以会话为键：

  • 私聊使用 session key anyy:telegram:dm:<chat_id>。
  • 群组/超级群使用 anyy:telegram:group:<chat_id>。

session 在多条消息间保持，因此同一会话内的上下文会延续。不同会话之间不会共享 session。要在某个 会话中重新开始，发送 /new。重复的更新以及机器人自身的回声会被自动过滤，因此重试与被重新投递的 更新不会产生重复的处理轮次。

媒体支持​

入站媒体​

Anyy 会在处理轮次开始前，下载并安全暂存受支持的入站附件：

  • 图片 —— 拉取可用的最大尺寸并作为图像暂存。
  • 文档 —— 作为文件暂存；图像类文档会按图像进行校验。
  • 语音消息 —— 作为语音附件暂存（带时长元数据）。

图像会进行内容嗅探，类型不匹配时会被拒绝。每个附件适用大小上限：media_max_bytes（默认 5242880 字节 = 5 MiB）。超限或无法下载的附件会被跳过；如果一条消息只有媒体且无一能被暂存， Anyy 会替换为一段简短的占位说明，使该轮次仍有上下文。媒体上的任何说明文字会被用作消息文本。

按需调高或调低上限，然后 reload：

channels:
  telegram:
    media_max_bytes: 10485760   # 10 MiB

出站媒体​

出站回复以文本消息形式投递。过长的回复会按字符数自动拆分为多条消息（默认分块大小 3500 个 字符；用 send_chunk_chars 调整）。在一轮处理进行时，机器人会在该会话中显示 Telegram 的 “正在输入…”指示。

命令​

在 Telegram 会话中输入的斜杠命令由 Anyy 解释（它们与你通过 BotFather 的 /setcommands 发布的命令相互独立，后者只填充 Telegram 界面的提示）。可从渠道会话使用的命令包括：

  • /new —— 在本会话开始一个新 session。
  • /status —— 显示运行时状态。
  • /stop —— 停止正在运行的轮次。
  • /approve / /deny —— 批准或拒绝一个待处理请求。
  • /voice —— 管理本会话的语音回复。

用于管理主机级运行时（provider、skills、cron、secrets 等）的命令在 CLI/TUI 中暴露，而非来自渠道 会话。请在主机上用 anyy 运行它们。

Cron 投递​

定时任务可以把输出投递回某个 Telegram 会话。当你从 Telegram 会话内（经由运行时）创建 cron 任务 时，该任务会把发起时的渠道与身份（telegram:<account_id>:<chat_id>）记录为它的投递路由，因此 定时运行的输出会经由网关被发回同一个会话。

这意味着：定时投递要送达，网关必须处于运行状态，且目标会话仍需被访问策略放行。关于投递路由字段 以及 cron 输出如何绑定到渠道身份，参见 渠道参考 及你的 cron 配置。

故障排查​

  • doctor 报告未配置 / 已禁用 —— 确认 channels.telegram.enabled: true，并确认你指向了正确的 home（--home / --profile）。若配置块缺失，重新运行 anyy setup channels telegram --write-config。
  • 机密无法解析 —— token_ref 指向了一个尚未写入的 profile 机密。带 --secret token='<BOT_TOKEN>' 重新运行 setup 命令，然后 anyy channels reload。
  • 机器人从不回复你的私聊 —— 多数情况下是 dm_policy: pairing 把你挡住了，而配对签发尚未配置。 改用 allowlist（把你的数字用户 ID 加入 allow_from）或 open，然后 reload。
  • 机器人在群里沉默 —— 在 mention 下它只在被提及时回答；请核对 bot_username 与真实用户名 一致、把机器人加入群组，并检查 BotFather 的隐私模式。对于 allowlist，确认数字会话 ID 在 allow_groups 中。
  • 收到了消息但没有 session/轮次 —— 检查网关是否在运行（anyy gateway status），以及消息 是否被拒绝（渠道状态会记录策略原因，例如 pairing_required、mention_required、 sender_not_allowed）。
  • 附件被忽略 —— 它们很可能超过了 media_max_bytes 或未通过校验。调高上限或重发更小的文件。
  • 配置改动未生效 —— 运行 anyy channels reload（或重启网关）。reload 需要网关处于运行 状态。
  • token 泄露 —— 通过 BotFather 轮换（/revoke），用新的 --secret token=... 重新运行 setup， 然后 reload。