# 문제 해결 일반적인 문제와 해결 방법입니다. --- ## 게이트웨이 문제 ### 게이트웨이가 시작되지 않음 - **포트 충돌**, 다른 프로세스가 포트 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` 엔드포인트는 모든 구성 요소의 기계 판독 가능한 상태를 제공합니다. --- ## 도움 받기 1. 자동 수정을 위해 진단 도구를 실행하세요 2. 자세한 오류 메시지는 게이트웨이 로그를 확인하세요 3. 데스크톱 앱의 Intercom 채팅 위젯을 통해 지원팀에 문의하세요