X Bot 문제 해결: 리포트, 필터, 일정, 결제
"뭔가 이상한데 어떻게 하지"에 대한 모든 경로를 모아놓은 통합 색인입니다. installation / setup-menu / support에 있는 매트릭스도 여기에 함께 있어 세 페이지가 아니라 한 페이지에서 검색할 수 있습니다.
여기서 시작하세요: 그룹에서
/setup→ ℹ️ About을 여세요. 그 화면의 네 줄(채팅 ID, 요금제, 일정, 프로젝트 이름)이 지원팀이 문제를 파악하는 데 필요한 정보입니다. 다른 작업을 하기 전에 먼저 복사해 두세요.
자가 진단 흐름
다음 질문을 순서대로 확인하세요. 대부분의 문제는 처음 두 가지 확인에서 해결됩니다.
1. 봇이 /setup에 응답하는가?
├─ 아니오 → 봇이 관리자에서 강퇴되거나 강등됨 → 재승격 후 재시도
└─ 예 → 계속.
2. /setup → 📊 Reports → ⚡ Generate report now가 3분 이내에
게시물을 생성하는가?
├─ DM 없음, 게시물 없음 → §"리포트가 오지 않음" 매트릭스 확인
├─ DM "게시물을 찾지 못함" → §"필터 / 게시물 없음" 참고
├─ DM "크레딧 소진" → §"결제 및 크레딧" 참고
├─ 게시물은 왔지만 렌더링이 이상함 → §"렌더링 품질" 참고
└─ 게시물이 정상적으로 도착함 → 문제 없음.
3. 예약 리포트가 제시간에 오는가?
├─ 아니오 → §"일정이 발동하지 않음" 참고
└─ 예 → 모두 정상.
4. X Posts Auto-relay 관련 문제인가?
└─ §"X Posts Auto-relay" 참고아래 매트릭스로 해결되지 않으면 에스컬레이션으로 이동하세요.
리포트가 오지 않음
| 증상 | 가능성 있는 원인 | 해결 방법 |
|---|---|---|
| 이전에는 정상이었는데 갑자기 조용함 | 봇이 조용히 관리자에서 강등되거나 강퇴됨 | 텔레그램 → 그룹 관리자 → 재승격. 여전히 조용하면 지원팀에 문의하세요 — 채팅-없음 시 자동 비활성화가 발동했을 수 있습니다. |
| 수동 generate-now가 아무것도 생성하지 않음 | 봇은 관리자지만 크레딧이 0 | /setup → 💳 Buy Credits. FREE가 "100/100 사용"이면 월간 초기화(UTC 기준 매월 1일)를 기다리세요. PRO·크레딧이 REMAINING=0이면 채팅이 이미 FREE로 자동 강등됨 — /setup → 💳 → 💰 Buy로 충전하세요. |
| 수동 generate-now: "게시물을 찾지 못함" 관리자 DM | 필터가 너무 좁거나 해당 기간에 게시물이 없음 | /setup → 🎯 Filters. 실제 X API 쿼리의 오타를 확인하세요. 범위를 넓히거나 기간을 제거해 보세요. |
| 이미지는 렌더링되지만 텍스트가 비어있음 | AI 코멘터리 시간 초과 | 재실행하세요. 일시적 현상입니다. 지속되면 지원팀에 문의하세요. |
| 이미지 렌더링 자체가 실패함 | 일시적 렌더링 오류 | 재실행하세요. 특정 채팅에서 반복적으로 실패하면 채팅 ID와 함께 지원팀에 문의하세요. |
| 관리자 DM에 "Unauthorized" / "Forbidden" 오류 | X API 토큰 문제(운영자 측) | 지원팀에 문의하세요. 사용자가 고칠 수 있는 부분이 아닙니다. |
필터 / 게시물 없음
| 증상 | 가능성 있는 원인 | 해결 방법 |
|---|---|---|
| 리포트에 "게시물 0건"만 표시됨 | 설정된 기간 안에서 필터가 아무것도 매칭하지 않음 | 1단계: /setup → 🎯 Filters — 쿼리를 확인하세요. 2단계: /setup → 📊 Reports → 🗑 Clear period(롤링 24시간이 더 관대함). 3단계: 필터를 넓히세요(캐시태그 폴백 추가, 엄격한 키워드 그룹 제거). |
| 필터에 추가하지 않은 사용자가 리더보드에 표시됨 | 필터는 합산 방식입니다 — 추적된 캐시태그/키워드를 트윗하는 누구나 카운트됨 | 계정과 캐시태그를 모두 요구하려면 /set_x_filtering name from:@x cashtags:$Y(명명된 필터, 카테고리 간 AND)를 사용하세요. |
| 같은 사용자가 리더보드를 도배함 | 봇이 모든 게시물을 정당하게 채점함 | /setup → 🎯 Filters → 🙈 Ignore → ➕ Add @spammer — 가져오기 이후 결과에서 제외됩니다. |
| 특이 문자가 있는 캐시태그가 매칭되지 않음 | X API는 대소문자를 정규화하지만 필터 입력의 앞뒤 공백은 중요함 | /setup → 🎯 Filters → 💵 Cashtags → ➕ Add로 다시 추가하세요 — $ 불필요, 공백 없이. |
숫자로 시작하는 캐시태그(예: $1INCH)가 추적되지 않음 | 앞자리 숫자가 있는 경우 X API 검색 동작이 일관되지 않을 수 있음 | 캐시태그 대신 키워드로 사용하세요: 🔍 Keywords에서 따옴표로 감싼 "$1INCH". |
| "Best Tweet" 선정이 이상해 보임 | AI 중복 제거가 최근 비슷한 트윗을 선택함 | 한 주기 기다려보세요. 계속 이상하면 신고하세요 — 프롬프트는 조정 가능합니다. |
일정이 발동하지 않음
| 증상 | 가능성 있는 원인 | 해결 방법 |
|---|---|---|
FREQUENCY_ERROR로 일정이 "거부됨" | 크론이 12시간보다 더 자주 발동하려고 시도 | 간격 검사는 ≥ 12시간 간격을 강제합니다. 오류 메시지가 문제가 되는 시간 쌍을 알려줍니다. 더 넓은 간격을 선택하세요. |
| 일정은 설정되었지만 리포트가 제시간에 오지 않음 | 예약된 크론은 발동 시각 기준 약 1~2분 이내에 실행됨 | 놓쳤다고 가정하기 전에 설정한 시각 이후 5분을 기다리세요. 드물게 업스트림 지연이 있지만 대부분 자체적으로 해결됩니다. |
| 다중 발동 크론이 한 번만 발동함 | 시간 목록 순서가 잘못되었거나 중복됨 | cron(0 14,22 ? * * *) — 오름차순이어야 합니다. cron(0 22,14 ? * * *)는 거부됩니다. |
| 스테이징에서는 5분마다 발동하는데 프로덕션은 안 됨 | 서로 다른 RULE_NAME 네임스페이스 | 올바른 환경을 확인하고 있는지 확인하세요. /setup → ℹ️ About이 환경을 표시합니다. |
| 시간대가 잘못된 것 같음 | 설계상 일정은 UTC 기준 | 현지 시각을 UTC로 변환하세요. 일부 예외적인 경우 일정 설정 입력이 이름 붙은 시간대를 받아들이기도 합니다 — 해당 입력의 설명을 확인하세요. |
| X Posts Auto-relay는 발동하는데 리포트는 안 됨 | 서로 다른 크론 일정 | X Posts Auto-relay는 릴레이당 5분 폴링을 사용하고, 리포트는 채팅의 메인 일정 크론(보통 일간)을 사용합니다. 서로 독립적입니다. |
렌더링 품질
| 증상 | 가능성 있는 원인 | 해결 방법 |
|---|---|---|
| 커스텀 제목/색상이 밤사이 되돌아감 | 캐시가 무효화되었고 다음 가져오기에서 새 값이 표시됨 | 리포트 주기(약 하루) 하나를 기다리세요. 렌더 캐시는 다음 가져오기에서 재구축됩니다. |
| 로고가 흐리거나 잘림 | 원본 이미지가 너무 작거나 정사각형이 아님 | 512×512 이상의 PNG를 정사각형 비율로 재업로드하세요. /setup → 🎨 Customization → 🖼 Logo. |
| 리더보드 이미지에서 사용자명이 넘침 | 표시 이름이 김 | 봇이 말줄임표로 자릅니다. 지속적으로 문제가 아니라면 조치 불필요. |
Best-tweet 텍스트에 원본 <a href> HTML이 표시됨 | 텔레그램 파스 모드 불일치 | 버그입니다 — 트윗 URL과 함께 신고해 주세요. |
| 리포트 이미지가 텔레그램 미리보기와 다름 | 텔레그램이 URL별로 첫 이미지 바이트를 캐시함. 사전 서명 URL에는 타임스탬프가 포함되어 매 가져오기마다 고유함 | 발생해서는 안 됩니다. 발생하면 /recreate로 갱신하세요. |
X Posts Auto-relay
| 증상 | 가능성 있는 원인 | 해결 방법 |
|---|---|---|
| 릴레이가 6개짜리 스레드를 한 번에 전달함 | 자기 답글은 X API의 exclude=replies를 우회함 | /setup → 📡 X Posts Auto-relay → @account → ☐ Thread continuations를 off로 전환. 그러면 봇은 스레드의 첫 트윗만 유지합니다. |
| 릴레이가 하루 중간에 멈춤 | 일일 한도 도달 | 릴레이별 화면에 Today: N/N forwarded가 표시됩니다. ✏️ Cap을 탭해 올리세요. 자정 UTC에 초기화됩니다. |
| 릴레이가 ⏸ Paused로 표시되는데 일시정지한 적이 없음 | 텔레그램 채팅-없음(강퇴/차단/채팅 업그레이드)으로 자동 일시정지됨 | 봇도 폴링 일정을 중단했습니다. 복원하려면: /setup → 📡 X Posts Auto-relay → @account → ▶️ Resume. 계속 실패하면 채팅 자체의 ID가 바뀌었을 수 있습니다(슈퍼그룹 업그레이드) — 새 채팅에 봇을 다시 추가하세요. |
| 릴레이의 첫 폴링이 게시물 50개를 전달함 | 부트스트랩은 이렇게 하면 안 됩니다 — LAST_POST_ID만 시딩하고 전달하지 않아야 함 | 이런 현상을 보면 신고해 주세요. 2026-04에 추가된 수정으로 이를 방지해야 합니다. |
| 토글에도 불구하고 인용 트윗이 계속 나타남 | X API에는 서버 측 exclude=quotes가 없음 — 봇이 클라이언트 측에서 필터링함 | 토글은 작동하지만 API가 반환한 인용 트윗에 대한 비용은 여전히 지불합니다. 표시만 절약될 뿐입니다. |
| 채팅이 삭제됐는데도 릴레이가 계속 폴링함 | 구버전 릴레이 — 자동 정리는 2026-05에 추가됨 | 지원팀에 릴레이 강제 중단을 요청하세요. 새 배포는 스스로 정리됩니다. |
결제 및 크레딧
| 증상 | 가능성 있는 원인 | 해결 방법 |
|---|---|---|
| 크레딧을 구매했는데 잔액이 그대로임 | Stripe 웹훅 지연 | 5분 기다리세요. 여전히 잘못되었다면 Stripe 영수증과 채팅 ID를 첨부해 지원팀에 문의하세요. |
| 예상보다 크레딧 소모가 많음 | 추적 대상 계정이 활발했던 기간에 릴레이가 여러 번 폴링함 | X Posts Auto-relay는 게시물당 과금됩니다. 릴레이를 탭해 Today 카운터를 확인하세요. |
| 게시물을 거의 안 올렸는데 PRO·구독에 초과 요금이 부과됨 | 채팅의 다른 사용량(릴레이, 리포트, 가져오기 재시도) | /setup → 💳 Buy Credits → Usage this month. 미터링 요금과 비교하세요. |
| FREE 채팅에 요금이 청구됨 | 발생해서는 안 됩니다 — FREE는 Stripe 고객이 아님 | 즉시 신고하세요. 결제 버그입니다. |
| 취소하지 않았는데 구독이 "취소됨"으로 표시됨 | 카드 자동 갱신 실패로 Stripe 취소가 트리거될 수 있음 | 이메일에서 Stripe 영수증을 확인하고 /setup → 💳 → 🛠 Manage subscription(Stripe 고객 포털)에서 카드를 업데이트하세요. |
| 구독을 취소했는데 여전히 PRO임 | 결제 주기 종료 시 취소: 유료 기간이 끝날 때까지 PRO 유지 | 정상 동작입니다. 다음 결제 주기 종료 시 FREE로 전환됩니다. |
공개 대시보드
| 증상 | 가능성 있는 원인 | 해결 방법 |
|---|---|---|
| xbot.ninja에 프로젝트가 없음 | 기준 미달(최고 점수 ≥ 300, 게시물 ≥ 5건, 당월 활성 사용자 ≥ 2명) | 직접 URL은 여전히 작동합니다. 지표가 기준에 도달할 때까지 기다리세요. 솔로 KOL 설정은 의도적으로 쇼케이스에서 숨겨집니다. |
| xbot.ninja에는 있지만 로고가 없음 | 로고를 업로드하지 않았거나 업로드 실패 | /setup → 🎨 Customization → 🖼 Logo. 정사각형 PNG를 보내세요. |
| 공개 URL에 예전 프로젝트 이름이 표시됨 | 다음 리포트 주기에 갱신됨 | /setup → 🎨 Customization → 🏷 Name으로 이름을 변경하세요. 다음 리포트가 발동하면 URL 슬러그 + 카드가 갱신됩니다. |
| URL이 404를 반환함 | 채팅이 완전히 삭제되었거나, 아직 기준을 충족하지 않아 쇼케이스가 숨김 | /setup → ℹ️ About으로 채팅 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 이슈(오픈소스 인지): bws-api-telegram-xbot/issues
- 직접 텔레그램: @BlockchainWebServices
심각도별 응답 시간:
- 긴급(봇 전체 오프라인, 결제 실패): EU+US 업무 시간 겹침 구간 기준 1영업시간 이내
- 높음(특정 채팅의 리포트 미전송): 당일 이내
- 일반(기능 문의, 설정 도움): 1~2영업일 이내
유용한 진단 명령어
| 명령 | 보여주는 것 |
|---|---|
/setup → ℹ️ About | 채팅 ID, 요금제, 일정, 프로젝트 — 지원 요청에 그대로 복사 |
/setup → 🎯 Filters | 실제 X API 쿼리 문자열 |
/setup → 💳 Buy Credits → 📊 Usage this month | 일간 + 월간 fetched_posts 카운터 — 조용한 실패를 발견(시도는 많은데 게시물이 0건이면 402일 가능성) |
/setup → 📡 X Posts Auto-relay → @account | 릴레이별 상태(active/paused, 오늘의 전달 건수, 일일 한도) |
/get_chatid | 채팅 ID만(About이 과하다면 한 줄로) |
다음 단계
- Installation — 다른 방법이 모두 실패하면 깔끔하게 재설치
- The /setup menu — 전체 메뉴 레퍼런스
- Pricing — 결제 관련 문제 해결
- Support — FAQ + 문의 escalation