iPhone에서 개발 컴퓨터에 연결할 수 없을 때: 로컬 네트워크 및 Tactic Relay 문제 해결 완벽 가이드

집에서는 Mac에 잘 연결되다가 카페에 가면 실패하는 경우, 계정 목록에는 컴퓨터가 보이는데 프로젝트를 열 때 계속 시간 초과가 발생하는 경우, 터미널 화면은 표시되지만 새 응답이 오지 않는 경우. 이 세 가지 상황은 모두 연결 장애처럼 보이지만, 실제로 점검해야 할 위치는 각기 다릅니다.

문제를 해결할 때는 먼저 '마지막으로 정상 작동했던 단계'를 찾으세요. 컴퓨터 자체가 작동하지 않는다면 호스트부터 복구해야 합니다. 로컬 네트워크 연결이 실패하지만 이미 설정된 Relay가 작동한다면 로컬 네트워크를 점검해야 합니다. 원래 세션에서 실시간 터미널 출력이 나타난다면 에이전트 상태를 확인해야 합니다. 이렇게 하면 각 단계마다 구체적인 판단 기준이 생기고, 진행 중이던 작업도 안전하게 보존할 수 있습니다.

연결 설정을 변경하기 전에 현재 상태를 먼저 기록하세요

현재 컴퓨터 이름, 프로젝트 및 세션, 연결 방식, 오류 메시지, 대략적인 발생 시간을 기록하세요. 그리고 최근에 네트워크 전환, 컴퓨터 절전 모드, 호스트 업데이트, 로그인 취소 등이 발생했는지 확인하세요.

컴퓨터의 계정 등록 해제, 세션 삭제, 모든 연결 설정 초기화부터 시작하지 마세요. 이러한 조치는 기존의 인증이나 작업 상태를 변경해 버리며, 컴퓨터 절전 모드나 게스트 네트워크 격리 문제를 해결해 주지도 못합니다. 증상과 관련된 조건을 한 번에 하나씩 변경하고 결과를 비교하세요.

아래 단계는 기존 연결의 문제를 진단하기 위한 것입니다. 처음 설정하는 경우라면 iPhone 시작 가이드에 따라 컴패니언 설치 및 페어링을 완료하세요.

1단계: 컴퓨터와 컴패니언 서비스가 실행 중인지 확인

컴퓨터가 작업 가능한 상태여야 하고, 컴패니언 앱 또는 CLI 서비스가 실행 중이어야 합니다. 화면이 꺼진 것과 컴퓨터 전체가 절전 모드에 들어간 것은 다릅니다. 또한 계정 목록에 컴퓨터가 표시되어 있다고 해서 현재 연결이 유효하다는 뜻은 아닙니다. 호스트에서 서비스 실행 상태와 오류 여부를 확인하고, 접속하려는 컴퓨터가 맞는지 확인하세요.

Mac에서는 다음 읽기 전용 명령어로 기본 포트를 확인할 수 있습니다:

lsof -nP -iTCP:8765 -sTCP:LISTEN

기본 포트는 8765입니다. 포트를 변경했다면 설정한 포트를 사용하세요. 출력 결과의 COMMAND, PID, 수신(listening) 주소는 어떤 프로세스가 서비스를 제공하고 있는지 확인하는 데 도움이 됩니다.

이 점검은 Tactic 인증을 검증하거나 iPhone의 접근 가능 여부를 증명하지는 않습니다. Mac 앱과 별도 CLI가 모두 동일한 기본 포트를 사용할 수 있으므로, 어떤 것을 실행했는지 명확히 파악하세요. 컴퓨터를 직접 확인할 수 없다면 '호스트 상태 미확인'으로 기록하고 휴대폰에 표시되는 오류를 계속 점검하세요.

2단계: 로컬 네트워크 연결 시 권한과 실제 접근성 확인

두 기기에 동일한 Wi-Fi 이름이 표시되어 있다고 해서 서로 통신할 수 있다는 보장은 없습니다. 게스트 네트워크, 기업 네트워크 격리, VPN 라우팅 등이 연결에 영향을 줄 수 있습니다. 먼저 iPhone의 설정 → 개인정보 보호 및 보안 → 로컬 네트워크에서 Tactic Remote의 접근 권한을 확인하세요. Apple의 로컬 네트워크 권한 가이드에서 자세한 내용을 확인할 수 있습니다.

그런 다음 컴퓨터의 현재 주소와 앱에 저장된 주소를 대조하세요. 라우터를 변경했거나, Wi-Fi에서 유선 랜으로 전환했거나, DHCP가 새 IP를 할당한 경우 저장된 주소가 다른 곳을 가리킬 수 있습니다. 호스트 컴패니언에 현재 표시된 주소를 기준으로 삼아야 하며, 모든 Mac의 Wi-Fi가 en0이라고 가정하지 마세요.

동일한 신뢰할 수 있는 네트워크에 다른 Mac이 있다면, 대상 컴퓨터에 대해 TCP 연결을 점검할 수 있습니다:

# 예시 IP 주소를 개발 컴퓨터의 실제 로컬 IP 주소로 바꾸세요.
nc -vz -G 3 192.168.1.42 8765

이 명령어는 TCP 연결만 시도하며 Tactic 인증 정보나 코딩 명령을 보내지 않습니다. -G 3은 macOS nc의 연결 시간 초과 인자이며, 다른 운영체제에서는 인자가 다를 수 있습니다.

개발 컴퓨터 자체에서 127.0.0.1을 테스트하는 것은 자기 자신만 확인하는 것입니다. iPhone 브라우저의 127.0.0.1은 휴대폰을 가리키며 Mac에 접근하는 데 사용할 수 없습니다. 또한 네트워크 환경에 따라 ICMP를 제한할 수 있으므로, ping이 실패한다고 해서 서비스가 오프라인이라고 단정할 수도 없습니다.

방화벽을 조정해야 하는 경우 실제로 실행 중인 컴패니언 앱에 필요한 접근만 허용하고 인증은 유지하세요. VPN을 사용하는 경우 조직의 네트워크 규정 범위 내에서 라우팅 변경 사항을 비교하세요. 방화벽 전체 해제, 인증 비활성화, 라우터 포트 개방을 일상적인 복구 수단으로 사용해서는 안 됩니다. 기본 구성은 로컬 네트워크 가이드를 참조하세요.

3단계: Relay 연결 시 계정 및 호스트 상태 확인

집을 떠나면 집 컴퓨터의 로컬 네트워크 주소에 더 이상 의존할 수 없습니다. Tactic Relay를 사용할 때는 양쪽 기기 모두 의도한 Tactic 계정을 사용 중인지, 컴퓨터가 해당 계정에 등록되어 있는지, 호스트 컴패니언의 Relay 연결이 활성화되어 있는지 확인해야 합니다.

다음 순서로 점검하세요:

1. 컴퓨터가 켜져 있고 컴패니언이 실행 중이며 인터넷 접속이 정상적인지 확인합니다.
2. 휴대폰과 컴퓨터가 올바른 계정에 로그인되어 있고 올바른 컴퓨터 이름이 선택되었는지 확인합니다.
3. 컴퓨터에서 Relay가 정상 연결 상태인지, 아니면 재연결 중이거나 오류가 발생했는지 확인합니다.
4. 계정 확인, 재로그인 또는 브라우저에서 앱으로 복귀하는 절차가 요구되는지 확인합니다.
5. 안내를 완료한 후 해당 컴퓨터에 연결하여 프로젝트를 엽니다.

Tactic 계정 로그인은 호스트 연결 및 접근 권한 부여를 담당합니다. Claude Code와 같은 코딩 에이전트는 개발 컴퓨터의 자체 서비스 제공자 계정을 사용합니다. 계정 목록에 컴퓨터가 표시되는 것, 워크스페이스에 성공적으로 연결되는 것, 에이전트가 로그인되어 있는 것은 서로 다른 상태입니다.

1.11 버전에서는 로그인 후 일정 시간이 지나면 컴퓨터를 계정에 등록하는 작업이 실패할 수 있던 문제가 해결되었습니다. 확인 요청이 나타나면 이를 완료한 후 다시 등록을 시도하세요. 계정 등록 해제와 재등록을 반복하면 추적해야 할 변경 사항만 늘어나므로, 모든 시간 초과 문제의 첫 번째 단계가 되어서는 안 됩니다.

올바르게 구성된 두 연결 방식을 비교 도구로 활용할 수도 있습니다. 동일한 컴퓨터에서 로컬 연결은 실패하지만 Relay는 성공한다면 로컬 네트워크를 우선 점검하세요. 로컬 연결은 성공하지만 Relay가 실패한다면 계정 확인, 호스트 Relay 상태, 인터넷 연결을 우선 확인하세요. 이 비교는 문제 범위를 좁히기 위한 것이며 특정 구성 요소에 결함이 없음을 입증하는 것은 아닙니다.

Cloudflare Tunnel 사용 시 터널 주소를 별도로 대조

Cloudflare Tunnel을 사용하는 경우 터널 프로세스, 현재 주소, 실제 서비스 매핑을 확인하세요. 임시 터널을 재시작하면 주소가 변경될 수 있으므로 저장된 이전 URL이 현재 컴퓨터를 가리키지 않을 수 있습니다.

브라우저에서 HTTP 페이지가 열린다고 해서 앱의 WebSocket 연결과 인증이 모두 정상 작동한다는 뜻은 아닙니다. 전체 오류 메시지를 유지하고 현재 주소를 대조한 다음 Cloudflare Tunnel 설정 가이드에 따라 점검하세요. 터널 접근 규칙과 Tactic Relay 계정 연결을 동시에 변경하지 않도록 주의하세요.

4단계: 원래 세션으로 돌아가 새로운 출력 확인

연결이 복구되면 문제 발생 전에 사용하던 컴퓨터, 프로젝트, 원래 세션을 선택하세요. 프로젝트 목록이 나타나면 워크스페이스 접근이 복구된 것입니다. 원래 터미널에서 실시간 출력이 변하는 것이 보인다면 세션 출력이 휴대폰으로 전달될 수 있는 상태입니다. 과거 기록 텍스트는 이전에 작업이 있었다는 증거일 뿐 현재 연결이 정상이라는 증거는 아닙니다.

터미널이 프로젝트 신뢰, 제공자 로그인 또는 시작 프롬프트에서 멈춰 있다면 에이전트 대기 처리 가이드로 이동하세요. 이때 Wi-Fi 설정을 반복해서 바꾸거나 계정을 다시 연결해도 해당 터미널 프롬프트에는 응답할 수 없습니다.

전송 중에 연결이 끊겼다면 해당 요청에 해당하는 새로운 출력을 먼저 찾으세요. 요청이 이미 컴퓨터에 도달했을 수 있습니다. 네트워크가 복구된 직후 전체 작업을 즉시 다시 보내지 마세요. 세션이 유휴 상태임을 확인한 후 범위가 좁은 상태 조회를 보낼 수 있습니다:

현재 프로젝트, 이미 완료된 작업, 결정을 기다리는 사항에 대해 읽기 전용으로 요약해 주세요. 이전 작업을 다시 실행하거나 파일을 편집하지 마세요.

디렉터리와 결과가 원래 작업과 일치하는지 확인한 후 후속 조치를 결정하세요. 새 세션을 만들어야 하는 경우 기존 세션의 실제 상태를 먼저 기록해 두세요. 새 세션이 모든 컨텍스트를 자동으로 이어받지는 않습니다.

여전히 실패할 경우, 조사 과정을 지원팀에 전달하세요

아래 템플릿을 복사하여 확인된 사실을 기재하세요. 확인하지 못한 항목에는 '미확인'으로 적으세요.

휴대폰 OS 및 Tactic Remote 버전:
컴퓨터 OS, 컴패니언 유형 및 버전:
연결 방식: 로컬 네트워크 / Tactic Relay / Cloudflare Tunnel
장애 발생 시작 일시(시간대 포함):
최근 변경 사항: 절전 / 네트워크 전환 / 업데이트 / 로그인 / 기타
마지막 정상 단계: 로그인 / 컴퓨터 발견 / 프로젝트 열기 / 터미널 실시간 출력
전체 오류 메시지:
호스트 서비스 및 Relay 상태:
이미 수행한 확인 항목 및 결과:
원래 세션을 계속 열 수 있는지 여부:
방금 보낸 요청이 이미 전송되었을 가능성이 있는지 여부:

외부에 공유하기 전에 자격 증명, 페어링 QR 코드, 로그인 링크, 개인 터미널 내용을 삭제하세요. 계정, 경로, 네트워크 주소는 필요에 따라 마스킹하세요. 지원팀에 "로컬 포트 접근은 가능하지만 앱에서 인증 실패가 표시되며 호스트 버전은..."과 같이 구체적인 진단 내용을 전달하는 것이 단순히 "연결이 안 된다"고만 하는 것보다 훨씬 빠르게 문제를 해결할 수 있습니다.

연결이 복구된 후에는 다운로드 페이지에서 양쪽 버전을 대조하여 버전 불일치 문제를 다음 원격 사용 시점까지 방치하지 않도록 하세요. 1.11의 다른 변경 사항과 모바일 앱 및 컴퓨터 컴패니언의 업데이트 방법은 Tactic Remote 1.11 개요를 참조하세요.