문제 해결
자주 겪는 문제와 해결 방법을 증상별로 정리했습니다.
로그인·기관
| 증상 | 원인과 해결 |
|---|---|
| 브라우저가 열리지만 앱으로 돌아오지 않음 | 로그인 화면 아래 웹 사이트에서 로그인 코드 받기로 코드를 받아 입력하세요. |
| "코드가 올바르지 않거나 만료되었습니다" | 코드를 다시 받아 입력하세요. |
| "서버 오류로 로그인하지 못했습니다" | 잠시 후 다시 로그인하세요. |
| "로그인 세션이 만료되어 로그아웃되었습니다" | 다시 로그인하세요. |
| "소속된 기관이 없습니다" | 기관에 소속된 엘리스 계정으로 다시 로그인하세요(런박스는 기관에 소속된 뒤 런박스를 재시작). |
| "기관 목록을 불러오지 못했습니다" | 다시 시도를 누르세요. 계속되면 네트워크를 확인하세요. |
| 런박스에서 "세션이 만료되었습니다" | 런박스를 다시 시작하세요. 로그인 화면이 없습니다. |
| 앱이 시작되지 않고 오류창이 뜸 | "Helpy Code failed to start" 오류의 원인(포트 충돌, 엔진 바이너리 없음 등)을 확인하세요. |
대화가 진행되지 않을 때
| 증상 | 원인과 해결 |
|---|---|
| 입력창이 비활성화됨 | 화면 위 배너를 확인하세요: 모델 없음, 토큰 한도 소진, 폴더 유실 중 하나입니다. |
| "현재 이 AI 모델을 사용할 수 없어 대화를 진행할 수 없습니다" | 기관에 활성화된 모델이 없습니다. 관리자가 설정 > 모델 설정에서 모델을 켜야 합니다. |
| "…토큰이 만료되었습니다 / 소진되었습니다" | 관리자에게 문의하세요. 관리자는 플랜 시작 또는 한도 조정이 필요합니다. 모델과 사용량 |
| "프로젝트와 연결된 폴더가 유실되어…" | 폴더를 원래 위치로 되돌리거나 프로젝트를 새로 연결하세요. |
| 모델을 바꿨는데 목록에 없음 | 모델 설정 변경은 앱 재시작 또는 기관 재선택 뒤 반영됩니다. |
| 응답이 멈춤 | 중단 후 다시 시도하세요. |
| 앱 시작 후 한참 로딩 | 엔진 시작을 최대 60초 기다립니다. 계속되면 앱을 재시작하세요. |
| 대화가 너무 길어져 답이 이상함 | /compact로 요약하거나 새 대화를 시작하세요. |
권한
| 증상 | 원인과 해결 |
|---|---|
| 권한 패널이 계속 뜸 | 수동 수락 모드입니다. 신뢰하는 범위에 한해 항상 허용을 쓰거나 자동 수락을 사용하세요. 권한 |
AGENTS.md/.opencode 수정 때 항상 묻는 이유 | 에이전트 구성 파일은 보호 파일이라 모든 모드에서 확인합니다. 의도된 동작입니다. |
| 자동 수락인데 작업이 막힘 | AI 판정이 차단한 것입니다. AI에게 다른 방법을 찾게 하거나, 수동 수락으로 바꿔 직접 허용하세요. |
| 자동 수락에서 "항상 허용"해 둔 명령이 또 묻는다 | 자동 수락 진입 시 인터프리터·스크립트 러너·curl 등을 허용하는 규칙은 비활성화됩니다. |
| 권한 패널이 사라지지 않음 | 새로고침하거나 대화를 이동했다 돌아오면 대기 중인 요청이 다시 표시됩니다. 중단한 실행의 요청은 제외됩니다. |
파일 첨부
| 증상 | 원인과 해결 |
|---|---|
| "지원되지 않는 파일 형식입니다" | 이미지, 텍스트, PDF, .docx, .xlsx, .pptx만 가능합니다. .hwp는 지원되지 않습니다. |
| "25MB 이하 파일만 첨부할 수 있습니다" | 파일을 나누거나 줄이세요. |
| 첨부했는데 AI가 못 읽음 | 모델이 이미지/PDF 입력을 지원하지 않으면 "읽을 수 없음"으로 전달됩니다. 다른 모델을 선택하세요. 첨부는 7일 후 정리됩니다. |
| 스캔 PDF 내용이 안 나옴 | AI에게 헬피비전 OCR(document_vision) 사용을 요청하세요. |
스킬·에이전트·MCP
| 증상 | 원인과 해결 |
|---|---|
새로 만든 스킬이 / 목록에 없음 | /reload-skills를 실행하세요. 프런트매터(name, description)가 올바른지 확인하세요. |
| 스킬을 AI가 안 씀 | description이 없거나 모호합니다. 언제 쓰는지 구체적으로 적으세요. |
| 서브에이전트가 호출되지 않음 | 정의 파일의 description이 모호하거나 mode가 맞지 않을 수 있습니다. "이름으로 서브에이전트를 지정해서" 요청해 보세요. |
| 서브에이전트 정의 파일이 안 읽힘 | 위치(.opencode/agents/<이름>.md)와 프런트매터를 확인하고, 앱을 재시작해 보세요. 전역 폴더는 앱 전용 경로입니다. 서브에이전트 |
| 서브에이전트가 또 서브에이전트를 못 부름 | 기본 중첩 한도(subagent_depth = 1) 때문입니다. |
| MCP "연결 실패" | URL과 네트워크를 확인하고 다시 시도하세요. |
| MCP "인증필요"가 풀리지 않음 | 인증은 5분 안에 끝내야 합니다. 인증하기를 다시 누르세요. |
| 채팅에서 추가한 MCP가 안 보임 | /mcp 패널을 열어 설정을 다시 불러오세요. |
CLAUDE.md 내용을 안 따름 | 헬피코드는 CLAUDE.md를 읽지 않습니다. AGENTS.md로 옮기세요. 지침 |
데스크톱 앱
| 증상 | 원인과 해결 |
|---|---|
| 앱을 두 번 실행해도 창이 하 나 | 단일 인스턴스입니다. 기존 창이 앞으로 나옵니다. |
| 사내 프록시에서 연결 오류 | 시스템 인증서(CA)를 신뢰하도록 설정되어 있습니다. IT 팀에 프록시 인증서가 OS에 설치되어 있는지 확인하세요. |
| 포트 충돌 | 앱은 마지막 포트를 재사용하고, 막히면 OS가 빈 포트를 고릅니다. |
| "Helpy Code stopped" | 엔진이 치명적으로 종료되었습니다. 앱을 다시 실행하고, 반복되면 오류 보고를 확인하세요. |
런박스
| 증상 | 원인과 해결 |
|---|---|
| 최신 버전이 아님 | 컨테이너를 재시작하면 새 버전을 받습니다. |
| 시작 즉시 종료 | 최신 버전을 받지 못한 경우입니다. 네트워크를 확인하고 다시 시작하세요. |
그래도 해결되지 않으면
- 사용 중인 앱 버전과 환경(데스크톱/런박스)을 확인하세요.
- 관리자에게는 기관, 모델 설정, 플랜 상태를 확인해 달라고 요청하세요.