문제 해결

증상으로 문제를 찾아보세요. 각 항목은 증상 / 가능한 원인 / 진단 방법 / 해결 방법을 제공합니다. 여러분의 상황이 목록에 없다면 GitHub에 이슈를 등록하거나 지원팀에 문의하세요.

데몬이 서버에 연결되지 않음

증상: aacworkflow daemon의 status 명령이 offline 또는 connection refused를 표시합니다. AACWorkflow Cloud에도 이 런타임의 최근 활동이 보이지 않습니다. 데몬 메커니즘이 어떻게 동작하는지는 데몬과 런타임을 참고하세요.

가능한 원인:

1. AACWORKFLOW_SERVER_URL이 잘못된 주소를 가리킴 — 설정하지 않았거나, 기본값인 wss://api.aacworkflow.com/ws와 일치해야 합니다
2. 네트워크 / 방화벽 차단 — 여러분의 기기에서 나가는 WebSocket 트래픽이 차단됨
3. 토큰이 만료되었거나 유효하지 않음 — aacworkflow login을 한 번도 실행하지 않았거나, PAT이 취소됨
4. 대상 워크스페이스의 멤버가 아님 — 로그인한 계정이 데몬을 등록하려는 워크스페이스에 속해 있지 않음(register가 403을 반환)
5. DNS 해석 실패 — 데몬 기기에서 api.aacworkflow.com이 해석되지 않음

진단 방법:

aacworkflow daemon logs --lines 100    # look for daemon-side errors
echo $AACWORKFLOW_SERVER_URL          # confirm the address, if you set one
cat ~/.aacworkflow/config.json        # verify api_token exists
aacworkflow workspace list            # confirm you're a member of the target workspace

해결 방법: 위의 각 원인을 하나씩 처리하세요. 가장 흔한 두 가지 해결책은 커스텀 AACWORKFLOW_SERVER_URL을 해제하고 데몬을 재시작하는 것(aacworkflow daemon restart)과 다시 로그인하는 것(aacworkflow logout && aacworkflow login)입니다.

작업이 queued에서 멈춤

증상: 에이전트에게 이슈를 할당한 뒤 이슈 상태가 곧바로 in_progress로 바뀌지만, 오랜 시간이 지나도 페이지에 에이전트 실행의 흔적이 보이지 않습니다. aacworkflow daemon status는 데몬을 online으로 표시합니다.

가능한 원인(빈도순):

1. 에이전트 동시 실행 상한 도달 — 이 에이전트의 max_concurrent_tasks(기본값 6)가 이미 다른 실행 중인 작업들로 가득 참
2. 같은 이슈에서 같은 에이전트의 다른 작업이 아직 실행 중 — 같은 에이전트 × 같은 이슈는 순차 실행이 강제됩니다(중복 실행 방지)
3. 에이전트가 보관됨 — 보관 후에도 새 작업은 여전히 대기열에 들어가지만 클레임될 수 없으며, 5분 뒤 타임아웃됩니다
4. 데몬이 현재 워크스페이스에 이 런타임을 등록하지 않음 — 데몬을 재시작하거나 UI에서 런타임을 다시 선택하세요
5. 데몬 연결 끊김 — 최근 45초 동안 하트비트가 없었습니다. daemon status가 online으로 보이는 것은 방금 끊긴 상태를 반영한 것일 수 있습니다

진단 방법:

aacworkflow daemon status --output json       # runtime list + last_seen_at
aacworkflow agent list                         # check agent archived state
aacworkflow issue show <issue-id>             # inspect task history

해결 방법:

• 동시 실행 가득 참 → 실행 중인 작업이 끝나기를 기다리거나, aacworkflow agent update <id> --max-concurrent-tasks 10으로 상한을 올리세요
• 같은 이슈 순차 실행 → 이전 작업이 끝나기를 기다리거나, 다른 에이전트에게 다시 할당하세요
• 에이전트 보관됨 → aacworkflow agent restore <id>
• 런타임 미등록 → aacworkflow daemon restart하면 데몬이 다시 등록합니다

WebSocket이 연결되지 않음

증상: 브라우저 콘솔에 WebSocket is closed가 기록됩니다. 페이지에 실시간 업데이트(작업 진행 상황, 댓글, 인박스)가 표시되지 않아 새로고침해야 보입니다. 에이전트 작업은 백그라운드에서 계속 실행됩니다.

가능한 원인:

1. 회사 프록시나 방화벽이 WebSocket 업그레이드를 차단함 — 일반 HTTPS는 허용하면서 Upgrade 헤더만 제거하는 네트워크가 있습니다
2. JWT 쿠키 만료 또는 누락 — 30일 만료 후 다시 로그인하지 않음
3. 브라우저 확장 프로그램의 간섭 — 일부 프라이버시 / 광고 차단 확장 프로그램이 wss:// 연결만 선택적으로 차단하기도 합니다

진단 방법:

• 브라우저 DevTools → Network → "WS"로 필터링하여 연결 상태와 상태 코드를 확인하세요
• 다른 네트워크(모바일 테더링 등)에서 시도해 회사 프록시가 원인인지 확인하세요

해결 방법:

• 쿠키 만료 → 페이지를 새로고침하고 다시 로그인하세요
• 프록시 / 방화벽 차단 → 다른 네트워크에서 시도하거나, 네트워크 관리자에게 wss://api.aacworkflow.com을 허용해 달라고 요청하세요
• 그래도 해결되지 않으면 → DevTools Network 탭 스크린샷과 함께 지원팀에 문의하세요

이메일이 수신되지 않음

증상: 로그인 또는 초대 수락 중 이메일을 제출했는데, 인박스에도 스팸 폴더에도 인증 코드가 없습니다.

가능한 원인:

1. 전송 지연 — 드물게 1분 정도 걸릴 수 있습니다
2. 스팸 / 프로모션 폴더 — 인증 메일이 필터링될 수 있습니다
3. 회사 메일 필터링 — 일부 회사 메일 게이트웨이가 자동 발송 메일을 격리할 수 있습니다
4. 이메일 주소 오타 — 로그인 페이지에 입력한 내용을 다시 확인하세요

해결 방법:

• 1분 정도 기다린 뒤 스팸 / 프로모션 폴더를 확인하세요
• 로그인 페이지의 코드 재전송을 클릭하세요
• 조직에서 수신 메일을 필터링한다면 noreply@aacworkflow.com을 허용 목록에 추가하도록 IT 부서에 요청하세요
• 몇 분이 지나도 오지 않으면 지원팀에 문의하세요

포트 충돌(데몬)

증상: aacworkflow daemon start가 address already in use로 실패합니다.

가능한 원인:

1. 데몬 health 포트 점유됨(기본값 19514, 프로필마다 해시로 오프셋됨)
2. 다른 데몬 프로필이 이미 같은 포트에 바인딩됨

진단 방법:

lsof -i :19514        # macOS / Linux
netstat -ano | findstr :19514    # Windows

해결 방법: 충돌하는 프로세스를 중지하거나, aacworkflow daemon start --profile <name>으로 다른 프로필의 데몬을 추가로 실행하세요. 프로필마다 서로 다른 health 포트가 자동으로 선택됩니다.

로그를 찾는 위치

백그라운드 모드에서 daemon.log는 크기 기준으로 로테이션되므로(기본값 20MB × gzip 백업 5개; AACWORKFLOW_DAEMON_LOG_MAX_SIZE_MB / _MAX_BACKUPS / _MAX_AGE_DAYS로 조정 가능) 열 수 없을 만큼 커지지 않습니다.

더 자세한 데몬 로그가 필요하면, 데몬을 백그라운드에서 포그라운드로 옮기세요: aacworkflow daemon stop && aacworkflow daemon start --foreground. 포그라운드로 실행하면 로그가 로테이션 파일이 아니라 터미널에 실시간으로 출력됩니다.