第 10 章 · 01 Telegram 机器人控制

第 10 章 · 01 Telegram 机器人控制

本节摘要:Telegram 是 freqtrade 最常用的远程控制方式——创建一个 Bot、拿到 token 和 chat_id 填进配置，就能用手机随时查状态(/status)、看盈亏(/profit)、手动平仓(/forceexit)、开关交易(/start / /stop)。本节讲清完整流程:用 BotFather 创建 bot 拿 token、用 userinfobot 拿 chat_id、配置 telegram 块(含通知噪音控制和自定义键盘)、掌握常用命令分类(系统、状态、修改交易、统计)，以及安全注意事项(群组权限、authorized_users)。读完你能用手机把机器人管起来。

内容来源:原项目文档 docs/telegram-usage.md，汉化并套用体系化模板。

⚠️ 风险提示:Telegram 群组里任何成员都能向 bot 发命令。用群组控制时要确保信任所有成员，或用 authorized_users 限制可发命令的用户。

学习目标

阅读完本节，你应当能够:

1. 用 BotFather 创建 bot 并拿到 token。
2. 获取 chat_id 并完成 telegram 配置。
3. 用 notification_settings 控制消息噪音。
4. 掌握常用命令:/status、/profit、/forceexit、/start、/stop。
5. 配置 authorized_users 限制群组权限。

一、创建 bot 与获取凭证

第 1 步:创建 Telegram bot

1. 在 Telegram 搜索并打开 @BotFather，发 /newbot。
2. 按提示给 bot 起公开名(如 Freqtrade bot)和用户名(必须以 bot 结尾，如 my_freqtrade_bot)。
3. BotFather 返回一段话，里面有 API token(形如 22222222:APIToken)。复制保存。
4. 点 bot 链接，点 START 开始对话(否则 bot 不能主动给你发消息)。

第 2 步:获取 chat_id

• 个人用:打开 @userinfobot，它返回你的 user id，用作 chat_id。
• 群组用:把 bot 拉进群，启动 freqtrade，在群里发 /tg_info，bot 会返回群 id(形如 -1001332619709)和可选的 topic_id。

"telegram": {
    "enabled": true,
    "token": "你的API token",
    "chat_id": "你的chat_id",
    "allow_custom_messages": true
}
​

💡 群组 chat_id 带负号，整个值(含负号)作为字符串填入。群组里还可以用 topic_id 指定在哪个话题(thread)里发消息。

二、控制通知噪音

freqtrade 默认会对很多事件发通知(开仓、平仓、止损、保护触发等)，可能很吵。用 notification_settings 精细控制，每个事件有三档:

• on:发消息并提醒(有声音/震动)。
• silent:发消息但不提醒(无声)。
• off:不发该类消息。

"telegram": {
    "enabled": true,
    "token": "...",
    "chat_id": "...",
    "notification_settings": {
        "status": "silent",
        "warning": "on",
        "startup": "off",
        "entry": "silent",
        "entry_fill": "on",
        "exit": {
            "roi": "silent",
            "emergency_exit": "on",
            "stop_loss": "on",
            "trailing_stop_loss": "on",
            "*": "off"
        },
        "exit_fill": "off",
        "protection_trigger": "off",
        "strategy_msg": "off"
    }
}
​

关键设置:

• entry 是下单时通知，entry_fill 是成交时通知(后者默认 off，需显式开)。
• exit 可以按出场原因细分:止损、ROI、紧急平仓等用不同级别；通配符 * 设未明确列出的原因的默认级别。
• strategy_msg 控制策略里 self.dp.send_msg() 发的自定义消息。
• balance_dust_level 定义 /balance 命令把多少余额以下的币当「灰尘」显示。

三、常用命令速查

Telegram 命令分几大类。最常用的几个:

系统命令

状态查询

修改交易

💡 /forceexit(别名 /fx)不带参数会弹出按钮列表让你选要平哪个，紧急情况用 /fx 更快。

统计

/profit 的输出很丰富，包含:ROI(每笔平均 + 基于初始资本的累计)、总交易数、平均持仓时长、最佳交易对、交易量、盈亏比(profit factor)、胜率、期望值(expectancy)、最大回撤。

四、自定义键盘与 marketdir

可以自定义 Telegram 的快捷按钮键盘:

"telegram": {
    "keyboard": [
        ["/daily", "/stats", "/balance", "/profit"],
        ["/status table", "/performance"],
        ["/reload_config", "/count", "/logs"]
    ]
}
​

⚠️ 键盘只支持预定义命令，不支持命令参数。允许的命令见文档列表。

marketdir(手动市场方向):/marketdir [long | short | even | none] 设置一个用户管理的「市场方向」变量，策略里用 self.market_direction 读取。可用来人工干预 bot 的多空倾向。

# 策略里
if self.market_direction == "long":
    # 只做多
elif self.market_direction == "short":
    # 只做空
​

⚠️ market_direction 重启 bot 后会重置(不持久化)，且回测时不可用(这是手动变量)。用它的策略回测结果可能不可复现。

五、安全:群组与 authorized_users

用群组控制 bot 时，所有群成员默认都能向 bot 发命令。两种防护:

1. 限制授权用户:用 authorized_users 白名单，只有列出的 user id 能发命令:

"telegram": {
    "chat_id": "-1001332619709",
    "topic_id": "3",
    "authorized_users": ["1234567"]
}
​

authorized_users 为空数组则没人能发命令(只能收通知)。

2. 信任群成员:如果不开 authorized_users，确保群里每个人都可信。

⚠️ 用群组等于把 bot 控制权分享给所有成员。别在公开群或半公开群里跑生产 bot。

本节要点回顾

1. 创建 bot:BotFather /newbot 拿 token；userinfobot 拿个人 chat_id；群组用 /tg_info 拿群 id(带负号)和 topic_id。
2. 通知控制:notification_settings 每个事件三档(on/silent/off)；entry vs entry_fill；exit 可按原因细分，* 是通配默认。
3. 常用命令:系统(/start/stop/pause/reload_config)、状态(/status/count/locks)、交易(/forceexit/fx/forcelong)、统计(/profit/performance/daily)。
4. 自定义键盘:keyboard 数组定义快捷按钮，只支持预定义命令；/marketdir 手动设多空倾向(不持久、回测不可用)。
5. 安全:群组里默认人人可发命令，用 authorized_users 白名单限制，或确保信任所有成员。

下一节，我们看 FreqUI 与 REST API——更丰富的 Web 可视化界面与编程化控制。