문제 해결

일반적인 문제와 해결 방법입니다.

게이트웨이 문제

게이트웨이가 시작되지 않음

포트 충돌, 다른 프로세스가 포트 18789를 사용 중일 수 있습니다. lsof -i :18789로 확인하세요.
구성 오류, neotask.json의 잘못된 JSON. 게이트웨이는 시작 시 구성을 검증하고 특정 오류를 보고합니다.
게이트웨이 잠금, 이전 인스턴스가 오래된 잠금 파일을 남겼을 수 있습니다. 진단 도구가 이를 감지하고 수정할 수 있습니다.
Node.js 버전, Neotask는 Node 22+가 필요합니다.

게이트웨이가 시작되지만 채널이 연결되지 않음

자격 증명 누락, 각 채널에는 자체 인증(봇 토큰, QR 스캔, API 키)이 필요합니다.
네트워크 문제, 채널은 메시지 플랫폼 API에 연결하기 위한 인터넷 접근이 필요합니다.
속도 제한, 일부 플랫폼은 새 연결을 속도 제한합니다. 기다렸다가 다시 시도하세요.

데스크톱 앱에서 연결할 수 없음

잘못된 포트, 데스크톱 앱이 올바른 게이트웨이 포트에 연결되는지 확인하세요.
인증 불일치, 게이트웨이 토큰이 일치해야 합니다.
방화벽, 게이트웨이가 다른 머신에 있는 경우 포트가 접근 가능한지 확인하세요.

채널 문제

WhatsApp이 연결되지 않음

QR 만료, QR 코드는 약 60초 후 만료됩니다. 빠르게 다시 스캔하세요.
멀티 기기 제한, WhatsApp은 연결된 기기 수를 제한합니다.
세션 손상, WhatsApp 세션 디렉토리를 삭제하고 다시 페어링하세요.

Telegram 봇이 메시지를 받지 못함

봇 토큰 유효하지 않음, BotFather로 봇 토큰을 확인하세요.
개인정보 보호 모드, 봇은 기본적으로 그룹에서 언급될 때만 메시지를 봅니다.
웹훅 충돌, 다른 서비스가 메시지를 소비하고 있을 수 있습니다.

Discord 봇이 응답하지 않음

인텐트 누락, Discord 개발자 포털에서 필요한 게이트웨이 인텐트를 활성화하세요.
권한 누락, 봇은 대상 채널에서 읽기 및 보내기 권한이 필요합니다.

모델 문제

인증 오류

키가 구성되지 않음, 제공업체 API 키가 설정되어 있는지 확인하세요.
키 만료, 일부 OAuth 토큰은 만료됩니다. 다시 인증하세요.
속도 제한, 키 순환은 여러 키가 있는 경우 자동으로 전환됩니다.

느린 응답

모델 선택, 더 큰 모델은 더 느립니다. 빠른 작업에는 더 빠른 모델을 시도해 보세요.
컨텍스트 크기, 긴 대화는 처리 속도를 늦춥니다. /compact를 시도해 보세요.
네트워크 지연, 모델 제공업체에 대한 연결을 확인하세요.

노드 문제

컴패니언 앱이 게이트웨이를 찾을 수 없음

바인딩 모드, 외부 기기를 위해 게이트웨이가 LAN 또는 Tailnet에 바인딩되어 있어야 합니다(루프백이 아님).
동일 네트워크, Bonjour 발견을 위해 두 기기 모두 동일한 네트워크에 있어야 합니다.
수동 입력, 앱 설정에서 게이트웨이 호스트와 포트를 수동으로 입력하세요.

세션 문제

컨텍스트 창 초과

컴팩션, /compact를 사용하여 컨텍스트를 요약하고 초기화하세요.
자동 컴팩션 활성화, 구성에서 컴팩션 임계값을 설정하세요.
새 세션, /new로 새로 시작하세요.

진단

내장 진단 도구는 일반적인 문제를 확인하고 많은 것을 자동으로 수정할 수 있습니다:

구성 유효성 검사
파일 권한
채널 연결성
모델 인증 상태
Node.js 호환성
네트워크 구성

자세한 오류 정보는 게이트웨이 로그를 확인하세요. /health 엔드포인트는 모든 구성 요소의 기계 판독 가능한 상태를 제공합니다.

도움 받기

자동 수정을 위해 진단 도구를 실행하세요
자세한 오류 메시지는 게이트웨이 로그를 확인하세요
데스크톱 앱의 Intercom 채팅 위젯을 통해 지원팀에 문의하세요