Telegram 集成
创建机器人、配置环境变量、注册 webhook 并完成联调。
创建机器人
- 在 Telegram 中找到
@BotFather - 执行
/newbot并完成创建 - 拿到
TELEGRAM_BOT_TOKEN
配置环境变量
TELEGRAM_BOT_TOKEN=<你的 bot token>
# 建议配置，防止伪造 webhook 请求
TELEGRAM_WEBHOOK_SECRET_TOKEN=<随机长字符串>说明：
TELEGRAM_WEBHOOK_SECRET_TOKEN是你自定义的值，不是 BotFather 提供。- 如果你配置了该值，Telegram 的
setWebhook必须传同样的secret_token。
启动 IM 服务
- Docker（本地 rustfs 版本，
docker-compose.yml）：
docker compose --profile im up -d im- Docker（R2 版本，
docker-compose.r2.yml）：
docker compose -f docker-compose.r2.yml --profile im up -d im- 本地：
cd im
uv sync
uv run uvicorn app.main:app --host 0.0.0.0 --port 8002设置 Telegram webhook
将 WEBHOOK_BASE 换成你的公网 HTTPS 域名。
export TELEGRAM_BOT_TOKEN="<你的 bot token>"
export WEBHOOK_SECRET="<TELEGRAM_WEBHOOK_SECRET_TOKEN>"
export WEBHOOK_BASE="https://your-domain.example.com"
curl -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/setWebhook" \
-H "Content-Type: application/json" \
-d "{
\"url\": \"${WEBHOOK_BASE}/api/v1/webhooks/telegram\",
\"secret_token\": \"${WEBHOOK_SECRET}\",
\"allowed_updates\": [\"message\", \"edited_message\"],
\"drop_pending_updates\": true
}"验证 webhook
curl "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getWebhookInfo"重点检查：
url是否正确last_error_message是否为空pending_update_count是否持续积压
联调测试
- 私聊机器人发送
/help - 发送
/new <任务描述>创建会话 - 再发送普通文本，验证续聊
提示：当前实现对群聊命令更建议直接使用 /help、/list、/new ...；若遇到命令无响应，优先在私聊中验证。