Telegram

通过长轮询将 ZeroClaw 智能体作为 Telegram 机器人运行。无需公共 URL 或 webhook。本指南从运行时连接配置开始，然后从机器人创建一直引导到首次授权对话。

当前实现的连接方式

Telegram 设置有三个独立的可信来源。channel 块拥有 Telegram 连接，agent 块拥有路由，peer 组拥有入站授权：

flowchart LR
    T["channels.telegram.home<br/>token and channel behavior"] --> C["TelegramChannel<br/>alias = home"]
    P["matching peer groups<br/>authorized Telegram identities"] --> C
    G["Telegram Bot API<br/>getUpdates long poll"] --> C
    C -->|"authorized ChannelMessage"| R["AgentRouter"]
    A["agents.primary<br/>channels includes telegram.home"] --> R
    R --> L["agent turn and Telegram reply"]

collect_configured_channels 会为每个已启用的、归属于代理的别名构造一个 TelegramChannel。当每条消息到达时，该通道会从共享的 Config 中解析出匹配的对等组成员。它接受发送者的数字 Telegram 用户 ID 或用户名，然后将已授权的 ChannelMessage 交给共享通道调度和代理轮次生命周期。

[channels.telegram.<alias>] 下没有 allowed_users 字段。授权由 Peer Groups 管理；该页面是关于 peer-group 字段、匹配和多智能体行为的权威参考。

1. 创建 Telegram 机器人

1. 在 Telegram 中打开 @BotFather。
2. 发送 /newbot 并按照提示输入显示名称和用户名。
3. 复制机器人令牌。Telegram 的官方教程介绍了相同的流程。

像对待密码一样对待令牌。任何拥有该令牌的人都可以控制该机器人。不要将其粘贴到 config.toml、日志、屏幕截图或源代码管理中。

2. 配置别名并将其关联到代理

本指南使用 home 作为频道别名，使用 primary 作为代理别名。别名是 ZeroClaw 为此机器人实例指定的本地名称；它不必与 Telegram 机器人用户名匹配。

通过掩码密钥提示设置令牌，然后启用频道：

zeroclaw config set channels.telegram.home.bot_token
zeroclaw config set channels.telegram.home.enabled true

列出代理别名，然后将 telegram.home 添加到目标代理现有的频道列表中。省略该值会打开列表编辑器，因此你可以添加新条目，而不会丢弃其他频道绑定：

zeroclaw agents list
zeroclaw config set agents.primary.channels

之后，相关的非机密结构等同于：

[channels.telegram.home]
enabled = true
# bot_token 在通过 `config set` 提示符加密存储后将被掩码显示

[agents.primary]
channels = ["telegram.home"]

将 primary 替换为一个已存在的代理，该代理已经具有可用的模型提供程序和风险配置文件。一旦配置中的任何代理声明了 channels 列表，已启用但未出现在某个已启用代理的 channels 列表中的通道就不会被启动。如果没有任何代理声明任何通道绑定，ZeroClaw 会改为回退到旧版路由：每个已启用的通道都会启动，并由解析得到的默认已启用代理提供服务。请按上文所示声明显式绑定，这样未列出的 bot 才会真正处于非活动状态，而不是静默地在默认代理下运行。

3. 选择首批用户的授权方式

启动机器人之前，请选择以下路径之一。

将第一个用户与一次性代码配对

对于私有首次运行，将已解析的 external_peers 集合保留为空。特别是，channel 为 telegram 或 telegram.home 的对等组不得贡献任何 external_peers 条目。仅携带其他设置而不贡献任何 external_peers 的匹配组不会影响配对。

当 TelegramChannel 在没有已解析的对等端的情况下构造时，它会创建一个一次性配对码，并将其写入前台输出和结构化日志。首个获准用户可在 Telegram 中使用 /bind 兑换该配对码。

预授权已知用户

如果你已经知道 Telegram 用户的数字 ID，请在启动前对其进行授权。数字 ID 优于用户名，因为即使用户重命名其账户，数字 ID 也保持不变。这是最简化的、按 alias 划分作用域的示例：

[peer_groups.telegram_home]
channel = "telegram.home"
external_peers = ["111111111", "222222222"]

仅当相同的身份应被每个已配置的 Telegram 别名接受时，才在类型范围内使用 channel = "telegram"。有关完整的架构和解析规则，请参阅 Peer Groups。

任何非空的已解析外部对等集都会禁用该通道实例的首用户配对。这包括通配符对等组。

[!CAUTION] external_peers = ["*"] 会接受所有能够访问该机器人的 Telegram 发送者，并禁用一次性配对流程。这些发送者可以驱动代理及其风险配置文件所允许的任何工具。仅在有意将机器人设为公开且代理受到适当限制时才使用通配符；这不是私有配置的快捷方式。

4. 启动通道并检查它

对于常规操作使用完整守护进程，对于前台诊断运行使用仅通道进程，对于长期运行使用已安装的服务：

zeroclaw daemon

# 备用前台诊断：启动所有已配置的通道。
zeroclaw channel start

# 如果 ZeroClaw 安装为托管服务。
zeroclaw service restart

Telegram 使用 getUpdates 长轮询，因此不需要入站端口或公开的回调 URL。在另一个终端中，检查连通性并跟踪日志：

zeroclaw channel doctor
zeroclaw service logs --follow

在对等方集合为空时，请查找 Telegram pairing required; one-time bind code issued。结构化事件包含频道别名和 pairing_code。前台运行 zeroclaw daemon 和 zeroclaw channel start 时也会直接打印代码。在代码被使用前，请将代码和日志输出视为敏感信息。

5. 将第一个用户与 /bind 配对

使用你想要批准的 Telegram 账户将打印出的代码发送给机器人：

/bind 123456

授权路径为：

flowchart TD
    S["Telegram update arrives"] --> I["Read username and numeric user ID"]
    I --> M{"Either identity matches<br/>the resolved peer set?"}
    M -->|"yes"| D["Dispatch ChannelMessage to the owning agent"]
    M -->|"no"| B{"Message is /bind code?"}
    B -->|"no"| H["Reply with the alias-aware operator bind command"]
    B -->|"yes, pairing active"| V{"One-time code is valid?"}
    V -->|"no"| X["Reject; repeated failures can lock out retries"]
    V -->|"yes"| P["Add numeric user ID to peer_groups.telegram_home"]
    P --> W["Save config.toml and accept subsequent messages"]

成功后，ZeroClaw 会优先使用稳定的数字发送者 ID，将其添加到 [peer_groups.telegram_home] 以供 telegram.home 使用，并保存 config.toml。正在运行的通道的对等方解析器会读取该共享配置，因此用户可以立即发送下一条消息，无需重启。

该码是一次性的。在后续重启时，已保存的对等端会使解析后的集合非空，因此配对保持禁用，并且不会发放替换码。如果 bot 表示由于持久化失败而仅在当前运行时完成了配对，请在重启前修复报告的配置权限或写入错误。

6. 从操作员 CLI 绑定另一个用户

未授权用户可以向机器人发送消息，以获取包含其数字 ID 的建议操作员命令。请在 ZeroClaw 主机上运行该命令。对于 home 别名，其格式如下：

zeroclaw channel bind-telegram 111111111 --alias home

你也可以绑定不带前导 @ 的 Telegram 用户名：

zeroclaw channel bind-telegram example_user --alias home

--alias 必须与 [channels.telegram.<alias>] 中的键匹配。CLI 默认使用 default，因此只有当配置的通道确实是 [channels.telegram.default] 时才可以省略该标志：

zeroclaw channel bind-telegram 111111111

该命令会拒绝未知的别名，而不是创建一个没有任何运行中的通道会读取的对等组。对于有效的别名，它会创建或更新 [peer_groups.telegram_<alias>]，将该组的作用域限定为 telegram.<alias>，并以幂等方式保存身份信息。

重启和持久化行为

如果自动重新加载失败，bind 命令会保留已保存的更改，并提示你手动重启：

zeroclaw service stop
zeroclaw service start

日志与故障排查

对于已安装的服务：

zeroclaw service logs --lines 200
zeroclaw service logs --follow

对于前台运行，请读取进程输出。启用持久化结构化日志记录后，事件也会写入安装目录下的 data/state/runtime-trace.jsonl；请参阅 可观测性。

完整的 Telegram 字段列表是根据实时配置架构生成的：

zeroclaw config set channels.telegram.<alias>.ack_reactions <value>

export ZEROCLAW_channels__telegram__<alias>__ack_reactions=

zeroclaw config set channels.telegram.<alias>.api_base_url <value>

export ZEROCLAW_channels__telegram__<alias>__api_base_url=

zeroclaw config set channels.telegram.<alias>.approval_timeout_secs <value>

export ZEROCLAW_channels__telegram__<alias>__approval_timeout_secs=

zeroclaw config set channels.telegram.<alias>.bot_token    # 掩码输入，加密存储

export ZEROCLAW_channels__telegram__<alias>__bot_token=

zeroclaw config set channels.telegram.<alias>.debounce_ms <value>

export ZEROCLAW_channels__telegram__<alias>__debounce_ms=

zeroclaw config set channels.telegram.<alias>.draft_update_interval_ms <value>

export ZEROCLAW_channels__telegram__<alias>__draft_update_interval_ms=

zeroclaw config set channels.telegram.<alias>.excluded_tools <value>

export ZEROCLAW_channels__telegram__<alias>__excluded_tools=

zeroclaw config set channels.telegram.<alias>.interrupt_on_new_message <value>

export ZEROCLAW_channels__telegram__<alias>__interrupt_on_new_message=

zeroclaw config set channels.telegram.<alias>.mention_only <value>

export ZEROCLAW_channels__telegram__<alias>__mention_only=

zeroclaw config set channels.telegram.<alias>.proxy_url <value>

export ZEROCLAW_channels__telegram__<alias>__proxy_url=

zeroclaw config set channels.telegram.<alias>.reply_min_interval_secs <value>

export ZEROCLAW_channels__telegram__<alias>__reply_min_interval_secs=

zeroclaw config set channels.telegram.<alias>.reply_queue_depth_max <value>

export ZEROCLAW_channels__telegram__<alias>__reply_queue_depth_max=

zeroclaw config set channels.telegram.<alias>.stream_mode <value>

export ZEROCLAW_channels__telegram__<alias>__stream_mode=

另见

• 对等组：规范化的入站授权模式
• 通道运行时生命周期
• 服务管理
• 可观测性