跳转至

Telegram 集成

ZeroClaw 支持 Telegram Bot 集成，提供即时通讯界面。

快速开始

1. 创建 Telegram Bot

  1. 在 Telegram 中搜索 @BotFather
  2. 发送 /newbot
  3. 按照提示创建机器人
  4. 保存 API Token

2. 配置 ZeroClaw

# 使用向导配置
zeroclaw integrations enable Telegram

# 或手动配置
zeroclaw onboard --channels-only

3. 配置文件

[channels_config.telegram]
bot_token = "1234567890:ABCDEF..."

# 允许的用户（推荐）
allowed_users = ["your_username"]

# 或允许所有用户（仅测试）
# allowed_users = ["*"]

4. 启动网关

zeroclaw gateway

用户白名单

推荐配置（安全）

[channels_config.telegram]
# 只允许特定用户
allowed_users = ["your_username", "123456789"]

获取用户信息

  1. 启动网关
  2. 在 Telegram 中发送任何消息给机器人
  3. 查看日志中的警告： 
    [WARN] Ignoring message from unauthorized user: @unknown_user
[WARN] User ID: 123456789
  4. 将用户 ID 添加到 allowed_users

配置格式

格式 示例 说明
用户名 @username 去掉 @ 符号
用户 ID 123456789 数值 ID
通配符 * 允许所有人（不推荐）

白名单策略

# 空列表 = 拒绝所有人
allowed_users = []

# 通配符 = 允许所有人（仅测试）
allowed_users = ["*"]

# 指定用户 = 只允许这些用户
allowed_users = ["username1", "123456789"]

媒体回复

ZeroClaw 支持在 Telegram 中发送多种媒体：

上传文件

# AI 助手包含以下标记时会上传文件
[IMAGE:/tmp/screenshot.png]
[DOCUMENT:/tmp/report.pdf]
[VIDEO:/tmp/demo.mp4]
[AUDIO:/tmp/message.mp3]
[VOICE:/tmp/voice.ogg]

下载文件

# 机器人可以处理用户发送的图片和文件
# 自动分析图片中的文字（OCR）
# 读取文件内容

高级功能

自定义命令

[channels_config.telegram]
# 自定义命令前缀（可选）
command_prefix = "/"

# 禁用特定命令
disabled_commands = ["help", "status"]

机器人设置

[channels_config.telegram]
# 机器人类别（可选）
bot_type = "assistant"

测试集成

# 测试 Telegram 连接
zeroclaw channel doctor telegram

# 查看日志
zeroclaw gateway --log-level debug

故障排查

消息不回复

  1. 检查用户是否在白名单
  2. 检查 Bot Token 是否正确
  3. 查看日志中的错误消息
  4. 测试网关：zeroclaw channel doctor telegram

Bot 无响应

# 检查网关状态
curl http://localhost:8080/health

# 检查 Telegram API
curl https://api.telegram.org/bot<TOKEN>/getMe

配置问题

# 重新配置
zeroclaw onboard --channels-only

# 验证配置
zeroclaw doctor

安全最佳实践

1. 使用白名单

[channels_config.telegram]
allowed_users = ["your_username"]

2. 启用配对

[gateway]
require_pairing = true

3. 使用环境变量

# Telegram Bot Token
export TELEGRAM_BOT_TOKEN="your-token"

4. 定期更新

# 更新 ZeroClaw
cargo install zeroclaw

示例对话

User: 你好，ZeroClaw！
Bot: 您好！我是 ZeroClaw，很高兴为您服务！

User: 帮我写一个 Python 函数
Bot: 好的，这是您的 Python 函数示例...

User: 运行一下这个代码
Bot: [正在执行...]
    输出：Hello, World!

更多信息