/setup 菜单：X Bot Telegram 界面完整指南

配置 X Bot 最快的方式就是交互式 /setup 菜单。它把每一条管理员命令都封装成一个可点击、可原地编辑的界面——无需记忆任何斜杠命令。

最快上手方式： 将机器人添加到你的群组，输入 /setup，点击 🚀 快速开始，按照四个提示操作。不到两分钟，你就能拥有一份基于真实筛选条件运行的每日报告计划。

`/setup` 长什么样

╔══════════════════════════════════════════════╗
║ ⚙️  Bot Setup                                ║
║                                              ║
║ Pick a section. Settings save instantly.     ║
║                                              ║
║ Current state                                ║
║ ─ Project:  MyToken                          ║
║ ─ Filter:   3 keywords · 2 cashtags          ║
║ ─ Schedule: daily 18:00 UTC                  ║
║ ─ Plan:     FREE — 47/100 credits left       ║
╠══════════════════════════════════════════════╣
║ [ 🚀 Quick Start ]                           ║
║ [ 🎯 Filters     ] [ ⏰ Schedule       ]      ║
║ [ 📊 Reports     ] [ 🎨 Customization  ]      ║
║ [ 👥 Admins      ] [ 💳 Buy Credits   ]      ║
║ [ ℹ️  About       ]                          ║
║ [ ✕ Close ]                                  ║
╚══════════════════════════════════════════════╝

每个界面顶部都会显示你的当前状态，让你在做任何修改之前就了解已配置的内容。每次修改都会即时保存到数据库——没有「保存」按钮需要记得点。

快速开始向导

点击 🚀 快速开始，进入一个四步线性流程，用最少的提示把一个全新群组从「什么都没配置」带到「第一份计划报告」。跳过和退出随时可用——一个未完成的向导不会阻塞你，未设置的选项只会保留默认值。

四个步骤：

步骤	询问内容	保存到
1	项目名称	`ProjectName` 设置项（用于报告、排行榜卡片、管理员私信）
2	在 X 上追踪什么——账号、cashtag 或关键词	默认筛选条件的 `from`、`cashtags` 或 `keywords` 数组
3	每日报告的发送时间——4 个预设时间或自定义 HH:MM	与你的群组绑定的计划任务
4	完成——摘要界面，附带 `/recreate` 提示以便立即预览	（无）

完整菜单

每个顶级按钮都会打开一个专注的界面。可以自由逐层深入——每个界面都有 ← 返回 回到上一级，以及 ✕ 关闭 关闭菜单。

🎯 筛选条件

机器人在每次计划运行时抓取哪些 X 帖子。

点击任意分类可深入查看。排除是勾选样式——点一下即可切换「排除转推 / 回复 / 引用推文」。

命名筛选器（高级功能）让你在同一个群组中同时运行多个筛选条件——适用于在一个群组中管理多个客户的场景。每个命名筛选器都有各自的删除按钮，并带有二次确认。点击 ➕ 添加命名筛选器，通过菜单发送单行定义（name from:@x keywords:y cashtags:$Z mention:@m exclude:retweet ignore:@spam）。至少需要 from / keywords / cashtags / mention 中的一项。

一个分类界面大致是这样的——简短说明该分类的作用、当前值，以及添加 / 移除 / 全部清除操作：

当你点击 ➕ 添加 时，菜单会切换到输入模式——将你的回复作为普通消息发送，界面会自动重绘并显示确认提示（例如「✓ 已添加 2 个 cashtag：$BTC、$ETH」）。

➕ Add cashtags

Send the cashtags to track, space-separated.
The $ is optional.

Example:  $BTC $ETH SOL

Type your reply as a normal message,
or tap Cancel to go back.

[✕ Cancel]

⏰ 计划

机器人何时运行并发布每日报告。

四个每日预设时间覆盖了大多数社区的需求。当前生效的预设会在标签前带有 ✓ 前缀。自定义时间会要求输入 HH:MM。指定星期接受 14:30 Mon Wed Fri 这样的格式。Cron 接受标准 cron 表达式（例如 cron(0 12 ? * MON-FRI *)）。机器人会强制执行 12 小时的最小间隔，以保证成本可预测。

如果你在一个没有任何筛选条件的群组中选择计划预设，菜单会拒绝该操作，并给出友好提示，引导你回到 🎯 筛选条件——机器人不会为一个没有任何抓取内容的群组安排计划任务。

📊 报告与时间段

📊 Reports & Period

Period: 01/05/2026 7days
Start:  2026-05-01
End:    2026-05-07

The bot fetches X posts inside this window on
every scheduled run. Without a period
configured, the bot uses a rolling 24-hour
window.

[📆 Set period]   [🗑 Clear period]
[⚡ Generate report now]
[📰 Show last report]

设置时间段将报告限定在一个特定的时间窗口内（例如持续一周的竞赛）。格式为 DD/MM/YYYY Ndays 或 Nweeks。清除时间段会恢复为默认的滚动 24 小时窗口。立即生成报告会触发与 cron 相同的 Step Function——适合用于即时预览。查看上一份报告会指向 /report（以零积分成本重新发送最近一次缓存的报告图片）。

🎨 自定义

出现在报告和公开排行榜上的项目元数据。

🎨 Customization

🏷 Name:        MyToken
✏️ Description: A community-driven DeFi project
📝 Long desc.:  (multi-paragraph project pitch…)
🖼 Logo:        ✓ uploaded
🔗 URLs:        2 URLs
💬 Topic:       Forum topic "Reports"

[🏷 Name]      [✏️ Description]
[📝 Long desc.][🖼 Logo]
[🔗 URLs]      [💬 Topic]
[📈 Leaderboard customization]

排行榜子菜单包含：

设置项	格式
🏆 积分	五个数字，以空格分隔：`点赞转推回复引用浏览量`（例如 `5 1 20 10 0.01`）
🎨 颜色	五个十六进制颜色代码，顺序相同
🔢 排行榜人数	1..10 之间的整数——排行榜上显示多少用户
📛 排行榜标题	自由文本。可选的 `\|#hex` 后缀可设置自定义颜色（例如 `Top contributors\|#FF8800`）
🥇 最佳推文标题	同上
📊 互动标题	同上

Logo 上传使用机器人现有的图片处理程序——点击 🖼 Logo，然后以 Telegram 图片（而非文件）的形式发送图片。机器人会自动调整大小并上传到网站 CDN。

话题会提示你在目标论坛话题内发送 /set_topic。菜单无法从回调按钮中捕获 message_thread_id，因此这仍然是一个只能通过斜杠命令完成的操作。

👥 管理员与通知

列出被指定接收积分耗尽、抓取错误和群组丢失警告私信的用户。添加管理员仍然需要在群组中发送 /add_admin @user1 @user2——Telegram 的 @-提及解析器只对真实消息生效，对回调按钮无效。

👥 Admins & Notifications

Currently:
  • Alice (@alice_admin)
  • Bob (@bob_dev)

To add admins, send /add_admin @user1 @user2
in this chat.

[🗑 Clear notification list]

💳 购买积分与套餐

套餐与余额展示，以及驱动购买和管理流程的按钮。此界面会根据群组当前的套餐呈现不同内容：

FREE 群组：

💳 Buy Credits & Plan

Plan: FREE
Used this month: 47 / 100
Remaining:        53
Resets: 2026-06-01

[💰 Buy credits / upgrade]   [🛠 Manage subscription]
[📊 Usage this month]

PRO 订阅群组：

💳 Buy Credits & Plan

Plan: PRO (subscription) ✓
Unlimited fetching with Stripe metering above 1 000 / month free.

[💰 Buy credits / upgrade]   [🛠 Manage subscription]
[📊 Usage this month]

PRO credits 群组（ETH 购买）：

💳 Buy Credits & Plan

Plan: PRO (credits)
Credits remaining: 4 152
Total purchased:   5 000

[💰 Buy credits / upgrade]   [🛠 Manage subscription]
[📊 Usage this month]

💰 购买积分 / 升级 按钮会在菜单下方发布一张付款选项卡片。机器人提供的选项取决于当前套餐：

FREE → 同时提供 💳 使用信用卡支付（Stripe 订阅）和 🪙 使用 ETH 支付（积分包）。
PRO credits → 两种选项都会显示。ETH 会为现有余额充值；Stripe 则会在此基础上叠加订阅（现有 ETH credits 保留，且在每次抓取时优先扣减）。
PRO 订阅 → 无购买选项。机器人会回复「订阅已存在」的消息，并引导你点击 🛠 管理 前往 Stripe 门户。

🛠 管理订阅 按钮会在浏览器中打开 Stripe 客户门户——你可以在那里更新银行卡、取消订阅或下载发票。只有在你拥有有效的 Stripe 订阅时才有意义。

📊 本月用量 子界面会拆分展示当月及当日的 fetched_posts 和 fetch_attempts——有助于发现静默失败（尝试次数高、帖子数为零 → 可能是 402 错误或空查询），也便于在接近 1000 条帖子门槛时预览下一张 Stripe 账单。

购买和管理也可以通过旧版斜杠命令 /buy 和 /subscription 实现。行为完全一致；菜单按钮只是帮你省去了打字的麻烦。

📡 X 帖子自动转发

在选定的 X 账号一发布内容就立即将其转发到群组中——与计划报告是相互独立的功能。适合项目希望社区管理员能实时看到官方账号的推文，而无需自己去查看 X 的场景。

📡 X Posts Auto-relay

Forward posts from X accounts to this chat as soon
as they're published. Posts can take up to 5
minutes to appear here after the original was
posted on X.

3 active relays:
▶️ @MyTokenOfficial    (4/10 today)
▶️ @MyTokenCEO         (1/10 today)
⏸ @MyTokenSupport     (0/10 today)

[ ▶️ @MyTokenOfficial ]
[ ▶️ @MyTokenCEO ]
[ ⏸ @MyTokenSupport ]
[ ➕ Add Account ]

每个转发都会通过 X API 每 5 分钟轮询一次。自上次成功转发以来的新帖子会以纯 URL 的形式推送到群组中——Telegram 会自动渲染 X 的预览卡片，因此帖子正文依然可见。

单个转发的管理界面让运营者可以调整行为：

📡 X Posts Auto-relay › @MyTokenOfficial

State: ▶️ Active
Today: 4/10 forwarded
Polls every: 5 min

Post types to forward
☐ Retweets
☐ Replies (to other users)
✅ Quote tweets
✅ Thread continuations (self-replies)

Topic: (default — top of chat)

[ ⏸ Pause ] [ ✏️ Cap: 10/day ]
[ ☐ Retweets ] [ ☐ Replies ]
[ ✅ Quote tweets ] [ ✅ Thread ]
[ 💬 Set topic ] [ 🧹 Clear topic ]
[ 🗑 Delete relay ]

设置项	作用
每日上限（1–100）	每个群组每 UTC 日的最大转发次数——达到上限后，转发会静默停止，直到 UTC 午夜。默认 10。
暂停 / 恢复	关闭该转发的轮询计划；恢复时会立即重新创建。
转推	为 ✅ 时，转发被追踪账号的转推。默认关闭。
回复	为 ✅ 时，转发对其他用户的回复。默认关闭。
引用推文	为 ✅ 时，转发引用推文。默认开启。
连续帖子（Thread）	为 ✅ 时，转发自我回复（用户回复自己之前的推文）——涵盖 Twitter 的连续帖子（thread）。默认开启。如果你只想要每个 thread 的第一条，请将此项关闭。
话题	可选的 Telegram 论坛话题 ID。设置后，转发只会发到该话题，而非主聊天区。

自动清理：如果 Telegram 返回「群组已消失」错误（机器人被踢出 / 被拉黑），该转发会自动移除其轮询计划和已存储的配置。不会产生残留。

硬性上限：每个群组最多 10 个转发。如需更多，可调整底层的常量配置。

ℹ️ 关于

ℹ️ About this chat

Chat ID: -1002593612414
Plan: PRO ✓
Schedule: daily 18:00 UTC
Project: MyToken

用于支持请求的诊断面板。

`/setup` 与斜杠命令的关系

/setup 是附加功能——所有现有的斜杠命令都会继续照常工作。菜单封装的是同一套底层机制（buildQueryFromComponents、saveXBotSetting、createScheduleRule 等），因此两种方式的行为完全一致。资深用户可以继续输入 /add_keywords DeFi airdrop 以获得肌肉记忆式的速度；新手则获得一个友好的可点击界面。

有三条命令由于需要纯文本 + Telegram 消息实体上下文（回调按钮无法携带），因此从根本上无法迁移到菜单按钮：

命令	为什么仍需保留
`/set_topic [name]`	捕获消息所在话题的 `message_thread_id`——按钮没有话题上下文
`/add_admin @user`	依赖 Telegram 已验证的提及实体来进行群组管理员身份验证
`/set_x_filtering`	旧版添加命名筛选器的斜杠命令；菜单中的 ⤴ 命名筛选器 → ➕ 添加命名筛选器实现了相同的功能

配置技巧

常见目标 → 对应的菜单路径。每个技巧只需一两分钟点击操作。

「只追踪原创帖子（不含转推、不含回复）」

大多数社区希望排行榜奖励原创内容，而非转发。

/setup → 🎯 筛选条件 → 🚫 排除 → 点击转推和回复，使两者都显示为 ✅。完成。此后的抓取会向 X API 发送 -is:retweet -is:reply，引用推文仍会保留。

「让回复比点赞更有分量（社区建设）」

默认权重：点赞 1×，转推 2×，回复 1.5×，引用 3×，浏览量 0.001×。要偏向对话：

/setup → 🎨 自定义 → 📈 排行榜自定义 → 🏆 积分 → 发送：

1 1 5 3 0.001

回复权重现在是 5×——实质性的讨论会超过随手点赞。

「每天运行两次报告」

默认情况下计划每天最多触发一次。要同时获得欧洲和美国的收工时段报告：

/setup → ⏰ 计划 → 🔧 Cron 表达式 → 发送：

cron(0 14,22 ? * * *)

每天触发两次，分别在 UTC 14:00 和 22:00。12 小时最小间隔检查会自动强制 ≥ 12 小时的间隔——间隔太窄会被明确拒绝。

「在同一个群组中同时追踪多场活动」

三场并行的客户活动，一个 Telegram 群组，每场活动每次触发生成一份报告。

/setup → 🎯 筛选条件 → ⤴ 命名筛选器 → ➕ 添加命名筛选器，然后依次发送：

campaign_a from:@kol1,@kol2 keywords:"#CampaignALaunch"
campaign_b from:@kol3,@kol4,@kol5 cashtags:$CBT
campaign_c from:@kol6 mention:@CampaignC_Official

每个都会在同一计划下触发，并生成带有对应筛选器名称标签的独立报告。

「在报告之间实时转发某个账号的推文」

@MyTokenOfficial 的重大消息不应该等到 UTC 22:00 的报告才出现。

/setup → 📡 X 帖子自动转发 → ➕ 添加账号 → 发送：

@MyTokenOfficial 5

（可选的 5 是每日上限；默认 10。）机器人每 5 分钟轮询一次，在有新帖子时转发 URL，Telegram 会渲染预览卡片。

「将报告限定在某个活动窗口内（例如 7 天的推广）」

不希望活动开始前的无关内容干扰排行榜。

/setup → 📊 报告 → 📆 设置时间段 → 发送：

01/05/2026 7days

此后报告只会严格抓取该窗口内的帖子。🗑 清除时间段 会恢复为滚动 24 小时。

「让报告发到论坛话题而非主聊天区」

群组使用话题功能；报告应该发到专门的 Reports 话题中。

打开 Reports 话题，然后在该话题内发送：

/set_topic Reports

此后的报告都会路由到该话题。要恢复：在群组内任意位置发送 /set_topic clear。

「积分耗尽时只通知两位指定管理员」

机器人会在积分 / 抓取 / 群组丢失出错时私信指定的管理员。默认情况下会回退给所有群组管理员——可以缩小到一个精选名单。

/add_admin @alice @bob

此后私信只会发给 @alice 和 @bob。要清除：/setup → 👥 管理员 → 🗑 清空通知名单。

「将群组从公开的 xbot.ninja 展示页中隐藏」

独立 KOL 作品集会被自动隐藏（单用户无法满足 ≥ 2 名活跃用户的门槛）。对于希望保持私密的社区项目：

没有明确的隐藏开关——公开列表是由指标门槛控制的。有两种方式可以保持私密：

运营一个小型 / 安静的群组，使其不满足门槛（最高用户分数 < 300，帖子数 < 5/月，或活跃用户数 < 2）。
联系支持，将该群组设为豁免——公开仪表盘会无视其指标，直接跳过它。

无论如何，群组的直接 URL（https://xbot.ninja/?chatId=…）始终可以访问。请只分享给应该看到这些数据的人。

常见坑点

症状	原因	解决方法
计划以 `FREQUENCY_ERROR` 被拒绝	Cron 触发频率高于每 12 小时一次	间隔检查——请至少间隔 12 小时。错误信息会标明冲突的小时对。
`/setup` 未出现在自动补全中	BotFather 命令列表过期	无论自动补全是否显示，机器人都会接受 `/setup`。如果需要可发现性，请通过 BotFather → `/setcommands` 更新。
筛选条件预览显示空括号或奇怪的查询语句	某个组成部分为空	`/setup` → 🎯 筛选条件会显示实际的查询语句。请至少添加账号 / cashtag / 关键词 / 提及中的一项。
X 帖子自动转发一次性转发了一整个 thread 的帖子	自我回复绕过了 X API 的 `exclude=replies`	`/setup` → 📡 X 帖子自动转发 → @账号 → 关闭 ☐ 连续帖子（Thread）。此后机器人只会保留 thread 的第一条。
达到每日上限但我想要更多	达到了转发的 `MAX_POSTS_PER_DAY`	点击 ✏️ 上限并调高。每转发一条帖子计为一个积分。
自定义标题 / 颜色一夜之间恢复	设置更新成功，但 UPDATED_AT 的变动使渲染缓存失效；下一次抓取会显示新值	等待一个报告周期。渲染缓存会在下一次抓取时重建。
报告到处都显示「0 posts」	在所配置的时间段内没有帖子匹配筛选条件	移除时间段（滚动 24 小时更宽松），或放宽筛选条件。通常是 cashtag 拼写错误导致的。
机器人「在线」但报告不再送达	机器人被撤销管理员身份 / 被静默踢出	检查 Telegram → 群组管理员。如缺失请重新提升。机器人在遇到群组丢失错误时会自我禁用。

完成

向导的最后一个界面会回顾所有已保存的内容，并引导你前往 /setup → 📊 报告 → ⚡ 立即生成报告进行即时预览：

这就是完整的功能导览。在你的群组中输入 /setup 即可开始。

配置某个菜单项时遇到问题？请参见故障排查，了解涵盖筛选条件、计划和账单的症状-解决方法对照表。

/setup 菜单：X Bot Telegram 界面完整指南 ​

/setup 长什么样 ​

快速开始向导 ​

完整菜单 ​

🎯 筛选条件 ​

⏰ 计划 ​

📊 报告与时间段 ​

🎨 自定义 ​

👥 管理员与通知 ​

💳 购买积分与套餐 ​

📡 X 帖子自动转发 ​

ℹ️ 关于 ​

/setup 与斜杠命令的关系 ​

配置技巧 ​

「只追踪原创帖子（不含转推、不含回复）」 ​

「让回复比点赞更有分量（社区建设）」 ​

「每天运行两次报告」 ​

「在同一个群组中同时追踪多场活动」 ​

「在报告之间实时转发某个账号的推文」 ​

「将报告限定在某个活动窗口内（例如 7 天的推广）」 ​

「让报告发到论坛话题而非主聊天区」 ​

「积分耗尽时只通知两位指定管理员」 ​

「将群组从公开的 xbot.ninja 展示页中隐藏」 ​

常见坑点 ​

完成 ​