X Bot 故障排查：报告、筛选条件、计划、账单
一份汇总了所有「看起来不对劲，现在该怎么办」路径的索引页面。安装指南 / /setup 菜单 / 支持页面中的对照表也都汇总在这里，方便你在一个页面里搜索，而不必翻三个页面。
从这里开始：在你的群组中打开
/setup→ ℹ️ 关于。该界面上的四行信息（群组 ID、套餐、计划、项目名称）正是支持团队排查问题所需要的。在采取任何其他行动之前，请先复制这些信息。
自助诊断流程
按顺序回答以下问题。大多数问题会在前两项检查中就得到解决。
1. Does the bot reply to /setup at all?
├─ No → bot was kicked or demoted from admin → re-promote and retry
└─ Yes → continue.
2. Does /setup → 📊 Reports → ⚡ Generate report now produce a post
within 3 minutes?
├─ No DM, no post → check matrix in §"Reports not arriving"
├─ DM "no posts found" → see §"Filter / no posts"
├─ DM "credit exhausted" → see §"Billing & credits"
├─ Post landed but renders wrong → see §"Render quality"
└─ Post landed correctly → you're fine.
3. Are scheduled reports arriving on time?
├─ No → see §"Schedule not firing"
└─ Yes → all good.
4. X Posts Auto-relay issues?
└─ See §"X Posts Auto-relay"如果下面的所有对照表都没能帮你找到解决方法，请跳转到升级处理。
报告未送达
| 症状 | 可能原因 | 解决方法 |
|---|---|---|
| 之前一直正常，突然沉默 | 机器人被静默撤销管理员身份 / 被踢出 | Telegram → 群组管理员 → 重新提升。如果仍然没有反应，请联系支持——可能触发了群组丢失时的自动禁用机制。 |
| 手动立即生成报告没有任何产出 | 机器人是管理员，但积分为零 | /setup → 💳 购买积分。如果 FREE 显示「100/100 已用」——请等待每月重置（UTC 每月 1 日）。如果 PRO·credits 且 REMAINING=0——群组已自动降级为 FREE；/setup → 💳 → 💰 购买以充值。 |
| 手动立即生成报告：管理员收到「未找到帖子」私信 | 筛选条件过窄，或时间窗口内没有帖子 | /setup → 🎯 筛选条件。检查实际的 X API 查询是否有拼写错误。尝试放宽条件或移除时间段。 |
| 图片已渲染但文字为空 | AI 点评超时 | 重新运行；这是暂时性问题。如持续出现，请联系支持。 |
| 图片完全渲染失败 | 临时性渲染故障 | 重新运行。如果某个群组反复失败，请携带群组 ID 联系支持。 |
| 管理员私信中出现「Unauthorized」/「Forbidden」错误 | X API 令牌问题（运营方问题） | 请联系支持；此问题用户无法自行解决。 |
筛选条件 / 没有帖子
| 症状 | 可能原因 | 解决方法 |
|---|---|---|
| 报告到处都显示「0 posts」 | 筛选条件在所配置的时间段内没有匹配任何内容 | 第一步：/setup → 🎯 筛选条件 — 确认查询内容。第二步：/setup → 📊 报告 → 🗑 清除时间段（滚动 24 小时更宽松）。第三步：放宽筛选条件（增加一个兜底 cashtag，或放宽过于严格的关键词组合）。 |
| 排行榜上出现了我没有添加到筛选条件中的用户 | 筛选条件是「加法」逻辑——任何人只要发布了被追踪的 cashtag / 关键词都会计入 | 若要同时要求账号和 cashtag 两个条件，请使用 /set_x_filtering name from:@x cashtags:$Y（命名筛选器，多个类别之间为「与」关系）。 |
| 同一个用户刷爆了排行榜 | 机器人合理地为其每条帖子计分 | /setup → 🎯 筛选条件 → 🙈 忽略 → ➕ 添加 @spammer — 他们会在抓取后被从结果中剔除。 |
| 带有特殊字符的 cashtag 无法匹配 | X API 会对大小写做归一化；筛选条件输入中的首尾空格会造成影响 | 通过 /setup → 🎯 筛选条件 → 💵 Cashtags → ➕ 添加 重新添加——不需要 $，也不要有空格。 |
数字开头的 cashtag（例如 $1INCH）无法被追踪 | X API 对以数字开头的搜索行为可能不稳定 | 改用关键词而非 cashtag：在 🔍 关键词 中使用带引号的 "$1INCH"。 |
| 「最佳推文」的选择结果看起来不对 | AI 去重机制最近选中了一条相似的推文 | 等待一个周期。如果持续出现异味，请反馈——该提示词是可调整的。 |
计划未触发
| 症状 | 可能原因 | 解决方法 |
|---|---|---|
计划以 FREQUENCY_ERROR 被拒绝 | Cron 触发频率高于每 12 小时一次 | 间隔检查会强制 ≥ 12 小时的间隔。错误信息会标明冲突的小时对。请选择更宽的间隔。 |
| 已设置计划，但报告没有按时到达 | 计划的 cron 会在触发时刻的约 1–2 分钟内执行 | 在判定为漏发之前，请在设定时间之后再等 5 分钟。偶尔会出现罕见的上游延迟，但会自行恢复。 |
| 多次触发的 cron 只触发了一次 | 小时列表顺序错误或有重复 | cron(0 14,22 ? * * *) — 小时需按升序排列。cron(0 22,14 ? * * *) 会被拒绝。 |
| 测试环境每 5 分钟触发一次，生产环境不触发 | 使用了不同的 RULE_NAME 命名空间 | 确认你检查的是正确的环境。/setup → ℹ️ 关于 会显示环境信息。 |
| 时区看起来不对 | 计划时间按设计以 UTC 表示 | 请将你的本地时间换算为 UTC。在某些边缘情况下，设置计划的输入也接受具名时区——请查看该输入项的说明文档。 |
| X 帖子自动转发正常触发，但报告没有 | 使用的是不同的 cron 计划 | X 帖子自动转发使用每 5 分钟一次的轮询；报告使用群组的主计划 cron（通常为每日一次）。两者相互独立。 |
渲染质量
| 症状 | 可能原因 | 解决方法 |
|---|---|---|
| 自定义标题 / 颜色一夜之间恢复 | 缓存已失效，下一次抓取会显示新值 | 等待一个报告周期（约 1 天）。渲染缓存会在下一次抓取时重建。 |
| Logo 模糊 / 被裁切 | 源图片过小，或非正方形 | 请重新上传 ≥ 512×512、正方形的 PNG 图片。/setup → 🎨 自定义 → 🖼 Logo。 |
| 排行榜图片中用户名溢出 | 显示名称过长 | 机器人会用省略号截断；除非持续出现，否则无需处理。 |
最佳推文文本显示原始的 <a href> HTML 标签 | Telegram 解析模式不匹配 | 属于 Bug——请附上推文 URL 进行反馈。 |
| 报告图片与 Telegram 预览不一致 | Telegram 会按 URL 缓存首次加载的图片字节；预签名 URL 包含时间戳，因此每次抓取都是唯一的 | 理论上不应发生；如果发生，请通过 /recreate 重新生成。 |
X 帖子自动转发
| 症状 | 可能原因 | 解决方法 |
|---|---|---|
| 转发一次性推送了一整个 6 条推文的 thread | 自我回复绕过了 X API 的 exclude=replies | /setup → 📡 X 帖子自动转发 → @账号 → 关闭 ☐ 连续帖子（Thread）。此后机器人只会保留 thread 的第一条。 |
| 转发在当天中途停止 | 达到了每日上限 | 单个转发的界面会显示 Today: N/N forwarded。点击 ✏️ 上限 并调高。将在 UTC 午夜重置。 |
| 转发显示 ⏸ 已暂停，但我并没有暂停它 | 在 Telegram 群组丢失时自动暂停（被踢出 / 被拉黑 / 群组升级） | 机器人同时也停止了轮询计划。要恢复：/setup → 📡 X 帖子自动转发 → @账号 → ▶️ 恢复。如果仍然失败，群组本身可能已经更换了 ID（超级群组升级）——请在新群组中重新添加机器人。 |
| 转发的首次轮询一次性转发了 50 条帖子 | Bootstrap 逻辑本不应如此——它应只设置 LAST_POST_ID 的种子，而不进行转发 | 如遇到此问题，请反馈。2026-04 添加的修复应能防止此情况。 |
| 尽管已开启该开关，引用推文仍然出现 | X API 没有服务端的 exclude=quotes 参数——机器人在客户端进行过滤 | 该开关本身是生效的，但你仍需为 API 返回的引用推文付费。仅节省了外观上的噪音。 |
| 群组已被删除，但转发仍在无限轮询 | 旧版本的转发——自动清理机制是 2026-05 才添加的 | 请让支持团队强制停止该转发。新部署会自动清理。 |
账单与积分
| 症状 | 可能原因 | 解决方法 |
|---|---|---|
| 已购买积分，余额未变化 | Stripe webhook 延迟 | 请等待 5 分钟。如果仍然不对，请携带 Stripe 收据和群组 ID 联系支持。 |
| 积分消耗数量比预期更高 | 某个转发在被追踪账号活跃的时段进行了多次轮询 | X 帖子自动转发按帖子计费。点击转发查看 Today 计数器。 |
| PRO·sub 上出现了超额费用，但我发帖并不多 | 群组的其他用量（转发、报告、抓取重试） | /setup → 💳 购买积分 → 本月用量。与按量计费的费用进行对比。 |
| FREE 群组被收费 | 不应发生——FREE 没有 Stripe 客户记录 | 请立即反馈；这属于计费 Bug。 |
| 订阅显示「已取消」，但我没有取消过 | Stripe 取消可能由银行卡自动续费失败触发 | 检查邮箱中的 Stripe 收据，通过 /setup → 💳 → 🛠 管理订阅（Stripe 客户门户）更新银行卡。 |
| 已取消订阅，但仍是 PRO | 周期结束时取消：在付费周期结束前仍保持 PRO | 属预期行为。将在下一个账单周期结束时恢复为 FREE。 |
公开仪表盘
| 症状 | 可能原因 | 解决方法 |
|---|---|---|
| 项目未出现在 xbot.ninja 上 | 未达到门槛（当月 ≥ 300 最高分、≥ 5 条帖子、≥ 2 名活跃用户） | 直接 URL 仍然可用。请等待指标达到门槛。独立 KOL 的设置是刻意从展示页中隐藏的。 |
| 项目出现在 xbot.ninja 上，但 Logo 缺失 | Logo 从未上传，或上传失败 | /setup → 🎨 自定义 → 🖼 Logo。请发送一张正方形 PNG 图片。 |
| 公开 URL 显示旧的项目名称 | 将在下一个报告周期刷新 | 通过 /setup → 🎨 自定义 → 🏷 名称 重命名。URL 短链和卡片会在下一次报告触发时刷新。 |
| URL 返回 404 | 群组已被彻底删除，或尚未达到门槛，因此展示页将其隐藏 | 通过 /setup → ℹ️ 关于 确认群组 ID。测试直接 URL https://xbot.ninja/?chatId=<id>。 |
升级处理
当以上对照表都无法解决问题时，请使用以下模板联系支持。
Project: <your project name>
Chat ID: <from /setup → ℹ️ About>
Plan: FREE / PRO·credits / PRO·sub
What's wrong: <1–2 sentences>
What you tried: </setup → … → … steps you ran>
When it broke: <approx UTC time>
Recent change: <any new filter / schedule / payment in the last 24 h>仅群组 ID 一项，就能为支持团队提供 80% 的排查信息——请务必附上。
联系方式：
- 一般支持：bws.ninja 联系表单
- GitHub issues（开源可见）：bws-api-telegram-xbot/issues
- 直接 Telegram 联系：@BlockchainWebServices
按严重程度划分的响应时间：
- 紧急（机器人全平台离线、计费故障）：欧美工作时段重叠期间 1 个工作小时内响应
- 高（单个群组的报告无法送达）：当日内响应
- 一般（功能咨询、配置帮助）：1–2 个工作日内响应
常用诊断命令
| 命令 | 显示内容 |
|---|---|
/setup → ℹ️ 关于 | 群组 ID、套餐、计划、项目名称——请原样复制到支持请求中 |
/setup → 🎯 筛选条件 | 实际的 X API 查询字符串 |
/setup → 💳 购买积分 → 📊 本月用量 | 每日 + 每月的 fetched_posts 计数器——用于发现静默失败（尝试次数高、帖子数为零 → 可能是 402 错误） |
/setup → 📡 X 帖子自动转发 → @账号 | 单个转发的状态（活跃 / 暂停、当日转发数、每日上限） |
/get_chatid | 仅返回群组 ID（当「关于」界面信息过多时的简化版本） |