X Bot のトラブルシューティング：レポート、フィルター、スケジュール、請求
「何かがおかしい、どうすればいいか」というあらゆるケースをまとめたインデックスです。インストール／setup メニュー／サポートの各ページにあるマトリクスもここに集約されているため、3ページではなく1ページで検索できます。
まずここから：グループで
/setup→ ℹ️ 情報 を開いてください。その画面にある4行（チャット ID、プラン、スケジュール、プロジェクト名）が、サポートがトリアージに必要とする情報です。他の何をする前に、まずそれをコピーしてください。
セルフ診断フロー
以下の質問に順番に答えてください。ほとんどの問題は最初の2つのチェックのどちらかで解決します。
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使用済み」なら月次リセット（毎月1日 UTC）を待つ。PRO・クレジットで REMAINING=0 なら、チャットはすでに FREE に自動ダウングレード済み。/setup → 💳 → 💰 購入 で追加購入。 |
| 手動の今すぐ生成：管理者 DM に「投稿が見つかりません」 | フィルターが狭すぎる、またはウィンドウ内に投稿がない | /setup → 🎯 フィルター。実際の X API クエリにタイプミスがないか確認。範囲を広げるか期間を解除してみる。 |
| 画像は表示されるがテキストが空 | AI コメント生成がタイムアウト | 再実行してください（一時的な問題）。継続する場合はサポートに連絡。 |
| 画像がまったく表示されない | 一時的なレンダリングの不具合 | 再実行してください。特定のチャットで繰り返し失敗する場合は、チャット ID を添えてサポートに連絡してください。 |
| 管理者 DM に「Unauthorized」「Forbidden」エラー | X API トークンの問題（運営側） | サポートに連絡してください。ユーザー側で対処できることはありません。 |
フィルター／投稿なし
| 症状 | 考えられる原因 | 対処法 |
|---|---|---|
| レポートがどこも「0投稿」になる | 設定された期間内でフィルターが何にも一致しない | ステップ1：/setup → 🎯 フィルター — クエリを確認。ステップ2：/setup → 📊 レポート → 🗑 期間をクリア（ローリング24時間の方が寛容）。ステップ3：フィルターを広げる（キャッシュタグのフォールバックを追加、厳格なキーワードグループを外す）。 |
| フィルターに追加していないユーザーがリーダーボードに表示される | フィルターは加算的です — 追跡対象のキャッシュタグ／キーワードをツイートすれば誰でもカウントされます | アカウント と キャッシュタグの両方を必須にするには、/set_x_filtering name from:@x cashtags:$Y（名前付きフィルター、カテゴリの AND 条件）を使用してください。 |
| 同じユーザーがリーダーボードをスパムしている | ボットはすべての投稿を正当にスコアリングしている | /setup → 🎯 フィルター → 🙈 無視リスト → ➕ 追加 で @spammer を追加 — 取得後の結果から除外されます。 |
| 奇妙な文字を含むキャッシュタグが一致しない | X API は大文字小文字を正規化しますが、フィルター入力では前後のスペースが影響します | /setup → 🎯 フィルター → 💵 キャッシュタグ → ➕ 追加 で再追加してください — $ は不要、スペースなし。 |
数字で始まるキャッシュタグ（例：$1INCH）が追跡されない | 先頭が数字の場合、X API の検索動作が一貫しないことがある | キャッシュタグではなくキーワードとして使用：🔍 キーワード に引用符付きで "$1INCH" と入力。 |
| 「ベストツイート」の選出がおかしい | AI の重複排除が最近似たツイートを選んでしまった | 1サイクル待ってください。継続的に不自然な場合は報告してください — プロンプトは調整可能です。 |
スケジュールが発火しない
| 症状 | 考えられる原因 | 対処法 |
|---|---|---|
スケジュールが FREQUENCY_ERROR で「拒否」される | Cron が12時間より頻繁に発火しようとしている | 間隔チェックにより12時間以上の間隔が強制されます。エラーメッセージには問題のある時刻ペアが示されます。より広い間隔を選んでください。 |
| スケジュールは設定済みだがレポートが時間通りに届かない | スケジュールされた cron はティックから約1〜2分以内に発火する | 見逃しと判断する前に、設定時刻から5分待ってください。まれに上流の遅延が発生しますが、自然に解消します。 |
| 複数回発火するはずの cron が1回しか発火しない | 時刻リストの順序が不正または重複している | cron(0 14,22 ? * * *) — 昇順で時刻を指定。cron(0 22,14 ? * * *) は拒否されます。 |
| ステージングのスケジュールは5分ごとに発火するが本番は発火しない | RULE_NAME の名前空間が異なる | 正しい環境を確認しているか確認してください。/setup → ℹ️ 情報 で環境が表示されます。 |
| タイムゾーンが間違っているように見える | スケジュールは仕様上 UTC です | ローカル時刻を UTC に変換してください。スケジュール設定の入力は、一部のエッジケースで名前付きタイムゾーンも受け付けます — 該当項目のドキュメント文字列を確認してください。 |
| X 投稿自動リレーは発火するがレポートは発火しない | cron スケジュールが異なる | X 投稿自動リレーはリレーごとに5分間隔でポーリングし、レポートはチャットのメインスケジュール cron（通常は毎日）を使用します。両者は独立しています。 |
レンダリング品質
| 症状 | 考えられる原因 | 対処法 |
|---|---|---|
| カスタムタイトル／カラーが一晩で元に戻った | キャッシュが無効化され、次回の取得で新しい値が反映される | 1回のレポートサイクル（約1日）を待ってください。次回の取得でレンダーキャッシュが再構築されます。 |
| ロゴがぼやけている／切り抜かれている | 元画像が小さすぎる、または正方形でない | 512×512ピクセル以上の正方形 PNG で再アップロードしてください。/setup → 🎨 カスタマイズ → 🖼 ロゴ。 |
| リーダーボード画像でユーザー名がはみ出す | 表示名が長い | ボットは省略記号で切り詰めます。継続的でない限り対処は不要です。 |
ベストツイートのテキストに生の <a href> HTML が表示される | Telegram のパースモードの不一致 | バグです — ツイート URL を添えて報告してください。 |
| レポート画像と Telegram のプレビューが異なる | Telegram は URL ごとに最初の画像バイトをキャッシュします。署名付き URL にはタイムスタンプが含まれるため、各取得は一意です | 通常発生しないはずです。発生した場合は /recreate でローテーションしてください。 |
X 投稿自動リレー
| 症状 | 考えられる原因 | 対処法 |
|---|---|---|
| リレーが6ツイートのスレッドを一度に転送する | セルフリプライが X API の exclude=replies をすり抜ける | /setup → 📡 X 投稿自動リレー → @account → ☐ スレッド継続 をオフに切り替え。ボットは先頭だけを保持するようになります。 |
| リレーが日中に停止した | 1日の上限に達した | リレーごとの画面に Today: N/N forwarded と表示されます。✏️ 上限 をタップして引き上げてください。UTC の深夜0時にリセットされます。 |
| リレーが ⏸ 一時停止 と表示されるが自分では一時停止していない | Telegram のチャット消失（キック／ブロック／チャットのアップグレード）により自動的に一時停止した | ボットはポーリングスケジュールも停止しています。復元するには：/setup → 📡 X 投稿自動リレー → @account → ▶️ 再開。それでも失敗する場合、チャット自体の ID が変わった可能性があります（スーパーグループへのアップグレード） — 新しいチャットにボットを再追加してください。 |
| リレーの最初のポーリングで50件の投稿が転送された | ブートストラップはこれを行うべきではなく、転送せずに LAST_POST_ID をシードするだけのはず | これが発生した場合は報告してください。2026年4月に追加された修正で防止されるはずです。 |
| トグルをオフにしても引用ツイートが表示され続ける | X API にはサーバー側の exclude=quotes がなく、ボットが取得後にクライアント側でフィルタリングしている | トグルは機能していますが、API から返される引用ツイートの分は引き続き課金されます。見た目上の節約のみです。 |
| チャットが削除されたのにリレーがポーリングし続ける | 旧バージョンのリレー — 自動クリーンアップは2026年5月に追加された | サポートにリレーの強制停止を依頼してください。新しいデプロイでは自動的にクリーンアップされます。 |
請求とクレジット
| 症状 | 考えられる原因 | 対処法 |
|---|---|---|
| クレジットを購入したのに残高が変わらない | Stripe の webhook が遅延している | 5分待ってください。それでも変わらない場合は、Stripe の領収書とチャット ID を添えてサポートに連絡してください。 |
| クレジットの消費数が想定より多い | 追跡対象アカウントがアクティブだった期間中にリレーが何度もポーリングした | X 投稿自動リレーは投稿ごとに課金されます。リレーをタップして Today カウンターを確認してください。 |
| あまり投稿していないのに PRO・サブスクリプションで超過料金が発生している | チャット内の他の利用（リレー、レポート、再取得）が原因 | /setup → 💳 クレジット購入 → 今月の利用状況。従量課金額と比較してください。 |
| FREE チャットに課金された | 発生しないはずです — FREE には Stripe 顧客が存在しません | すぐに報告してください。これは請求のバグです。 |
| サブスクリプションが「解約済み」と表示されるが解約していない | カードの自動更新失敗により Stripe の解約がトリガーされることがある | メールで Stripe の領収書を確認し、/setup → 💳 → 🛠 サブスクリプション管理（Stripe カスタマーポータル）でカードを更新してください。 |
| サブスクリプションを解約したがまだ PRO のまま | 期間終了時解約：支払い期間の終了まで PRO のまま | 想定どおりです。次の請求サイクルの終了時に FREE に戻ります。 |
公開ダッシュボード
| 症状 | 考えられる原因 | 対処法 |
|---|---|---|
| プロジェクトが xbot.ninja に表示されない | しきい値を満たしていない（当月内で最高スコア300以上、投稿数5件以上、アクティブユーザー2人以上） | 直接 URL は引き続き機能します。指標がしきい値に達するのを待ってください。ソロ KOL の設定は意図的にショーケースから非表示になっています。 |
| プロジェクトは xbot.ninja に表示されているがロゴがない | ロゴがアップロードされていない、またはアップロードに失敗した | /setup → 🎨 カスタマイズ → 🖼 ロゴ。正方形の 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
深刻度別の応答時間：
- クリティカル（ボットが全体的にオフライン、請求の失敗）：EU + 米国の営業時間の重複帯で1営業時間以内
- 高（特定のチャットのレポートが届かない）：当日中
- 通常（機能に関する質問、設定サポート）：1〜2営業日
役立つ診断コマンド
| コマンド | 表示内容 |
|---|---|
/setup → ℹ️ 情報 | チャット ID、プラン、スケジュール、プロジェクト — そのままサポートにコピーしてください |
/setup → 🎯 フィルター | 実際の X API クエリ文字列 |
/setup → 💳 クレジット購入 → 📊 今月の利用状況 | 日次・月次の fetched_posts カウンター — サイレント障害を発見（試行回数が多いのに投稿数がゼロ → おそらく 402 エラー） |
/setup → 📡 X 投稿自動リレー → @account | リレーごとの状態（アクティブ／一時停止、本日の転送数、1日の上限） |
/get_chatid | チャット ID だけ（情報画面では大げさすぎる場合のワンライナー） |
次に読むもの
- インストール — 他がすべて失敗した場合のクリーンな再インストール
- /setup メニュー — メニューの完全なリファレンス
- 料金 — 請求側のトラブルシューティング
- サポート — FAQ + 連絡先エスカレーション