문제 해결

이 가이드를 마치면 흔한 문제를 증상에서 출발해 원인을 찾고 고칠 수 있어요. 각 항목은 증상 → 확인 → 해결 순서예요. 점검 항목 전체는 점검 항목을, 맥의 파일 위치는 맥의 파일과 경로를 보세요.

시작하기 전에

문제를 볼 곳은 네 군데예요. 먼저 어디를 볼지 알아 두세요.

볼 곳	여는 법	보이는 것
doctor	맥의 터미널에서 node ~/.claude-bridge/agent.mjs doctor	이 맥의 점검 결과. 아무것도 만들거나 바꾸지 않아요. fail 이 있으면 종료 코드 1
호스트 화면	조작 페이지의 기기 목록에서 맥을 누르기	점검, 상태 보기, 에이전트 상태, 호스트 로그
에이전트 로그	맥의 ~/.claude-bridge/agent.log(JSONL), 서비스 출력은 ~/.claude-bridge/service.log	에이전트가 한 일과 오류
서버 로그	서버에서 docker logs	서버 출력. 호스트 로그 줄도 user=<계정> host=<맥 이름> 과 함께 찍혀요

호스트 화면의 상태 보기는 이 줄로 돼 있어요.

• 연결: 언제부터 붙어 있는지, 몇 번째 연결인지, 서버와 에이전트 사이 왕복 시간.
• 에이전트: 버전과 build("최신" 여부), node 버전, 켜진 시간, 메모리.
• 맥: 부하와 여유 메모리.
• 점검: 항목마다 초록(정상), 주황(경고), 빨강(문제) 점.
• 연동 탭: 앞에 보이는지 백그라운드인지, 밀린 메시지 수, 재시도 횟수.
• 세션: 세션마다 상태, 터미널 프로그램, 서버가 받은 줄 수와 밀린 줄 수, push 실패.

아래 로그는 수준을 "모두" 또는 "경고 이상" 으로 거를 수 있어요. 세션 메뉴의 "이 세션의 로그" 로 한 세션만 볼 수도 있어요. 보낸 글의 내용은 로그에 남지 않아요.

1. 호스트가 연결 안 돼요

증상: 기기 목록에서 맥이 "끊김" 이에요.

확인

1. 그 맥에서 에이전트 서비스가 도는지 보세요.

   node ~/.claude-bridge/agent.mjs service status

2. 그 맥의 브라우저에 이 사이트의 탭이 하나라도 열려 있는지 보세요. 에이전트는 127.0.0.1 에서만 듣고, 열린 탭(연동 페이지)이 에이전트와 서버를 이어요. 탭을 모두 닫으면 끊겨요.

3. 그 탭이 같은 계정으로 로그인돼 있는지 보세요.

해결

• 서비스가 꺼져 있으면 node ~/.claude-bridge/agent.mjs service install 로 다시 설치하세요.
• 탭이 없으면 node ~/.claude-bridge/agent.mjs link 로 연동 링크를 여세요.
• Chrome 이 "로컬 네트워크의 기기에 연결" 을 물으면 허용하세요. Safari 는 이 연결을 막을 수 있어 Chrome 을 권해요.
• 탭을 열어 두지 않고도 늘 연결하려면 맥을 늘 연결해 두기를 보세요.

터미널에서 에이전트를 돌릴 때 45초 안에 붙지 않으면 연동 페이지가 아직 연결되지 않았습니다. 로 시작하는 안내가 찍혀요.

2. 호스트가 "응답 없음" 이에요

증상: 맥이 연결돼 있는데 "응답 없음" 이에요.

확인: 에이전트는 15초마다 상태를 보내요. 연동 탭은 붙어 있는데 50초 넘게 상태가 오지 않으면 "응답 없음" 이 되고 로그에 남아요. 맥이 잠들었거나, 에이전트가 멈췄거나, 탭이 백그라운드에서 멈춘 경우예요. 호스트 화면의 "연동 탭" 줄과 agent.log 의 마지막 줄을 보세요.

해결

• 맥이 잠들었다면 깨우고, 호스트 화면에서 잠자기 막기 를 켜세요.
• 호스트 화면의 에이전트 상태 를 보세요. 에이전트는 1분마다 스스로 살펴 고칠 수 있는 것은 고쳐요. 항목 옆에 다시 띄우기, 다시 적용, 다시 점검, 다시 시작 버튼이 있으면 눌러 바로 고칠 수 있어요.

3. 세션이 안 떠요

증상: 새 세션을 만들었는데 시작되지 않거나 오류가 떠요.

확인: 호스트 화면 맨 위의 점검을 보세요. 다음 문제는 세션 시작을 막아요.

점검	해결
claude 가 실행되지 않음	Claude Code 를 설치하세요
claude 버전이 옛것(--session-id·--resume 없음)	claude update
claude 로그인 안 됨	터미널에서 claude 를 실행하고 /login
에이전트 폴더나 claude 기록 폴더에 쓸 수 없음	폴더 권한을 고치세요

새 세션의 작업 폴더가 없거나, 폴더가 아니거나, 읽을 권한이 없으면 무엇이 문제인지 알려 줘요. 데스크탑·문서·다운로드 폴더는 macOS 권한도 확인하세요.

해결: 고친 뒤 호스트 화면의 다시 점검 을 누르세요. 에이전트를 다시 켜지 않아도 반영돼요. 전체 항목은 점검 항목을 보세요.

4. 옮기기가 실패해요

증상: 다른 맥으로 옮기는데 오류가 떠요.

확인: 오류 문장을 보세요. 실패하면 세션은 원래 맥에 그대로 남아요.

오류	뜻
… 이 연결돼 있지 않아 옮길 수 없어요. 서버는 대화 사본을 갖고 있지 않아요.	보내는 맥이 끊겨 있어요. 서버는 대화를 갖고 있지 않아 보내는 맥이 있어야 해요
받는 호스트가 연결돼 있지 않습니다	받는 맥이 끊겨 있어요
보내는 호스트에서 마지막 싱크를 하지 못했습니다	보내는 맥이 마지막 대화를 넘기지 못했어요
받는 호스트에서 열지 못했습니다: …	받는 맥에서 claude --resume 이 실패했어요
이미 옮기는 중입니다	앞의 옮기기가 아직 끝나지 않았어요

해결: 두 맥이 모두 "연결됨" 인지 확인하고 다시 해 보세요. 받는 맥의 저장소에 커밋하지 않은 변경이 있으면 에이전트는 건드리지 않고 알려요. 정리한 뒤 다시 옮기세요. 자세한 흐름은 세션 옮기기을 보세요.

5. 세션 화면에 "맥 연결 끊김" 이 떠요

증상: 세션을 열었는데 "맥 연결 끊김" 띠가 보이고 새 글이 오지 않아요.

확인: 서버는 대화를 저장하지 않아요. 화면의 기록은 그 세션의 맥에 물어서 가져와요. 맥이 끊겨 있으면 이 기기에 남은 캐시만 보여요.

해결: 1단계처럼 그 맥을 다시 연결하세요. 화면은 10초마다 다시 물어 저절로 이어져요.

6. 알림이 안 와요

증상: 결정이 필요한 세션이 있는데 폰에 알림이 오지 않아요.

확인

• 설정 → 이 기기에서 알림이 켜져 있는지 보세요.
• "이 브라우저는 웹 푸시를 못 받아요 (폰은 홈 화면에 추가한 뒤)" 가 보이면, iPhone 에서는 사이트를 홈 화면에 추가한 뒤 그 앱에서 켜야 해요. iOS 16.4 이상이 필요해요.
• "알림 권한이 꺼져 있어요. 브라우저 설정에서 켜 주세요" 가 뜨면 브라우저나 기기 설정에서 사이트의 알림을 허용하세요.

해결: 알림을 껐다가 다시 켜서 구독을 새로 만드세요. 자세한 내용은 알림과 웹 푸시를 보세요.

7. 음성 입력이 안 돼요

증상: 마이크 버튼을 눌렀는데 오류가 떠요.

확인: 받아쓰기는 세션이 도는 맥의 whisper.cpp 로 해요. 오류 문장이 필요한 명령을 알려 줘요.

• 이 맥에 whisper.cpp 가 없어요. 터미널에서 brew install whisper-cpp 로 설치해 주세요
• 이 맥에 음성 모델(…)이 없어요. 터미널에서: … 뒤에 모델을 받는 명령이 붙어요.

해결: 그 맥의 터미널에서 안내된 명령을 실행하세요. 설정 → 음성에서 "음성 입력" 이 켜져 있는지도 보세요. 자세한 내용은 음성 입력을 보세요.

8. 업데이트가 안 돼요

증상: 호스트 화면에 "에이전트가 서버와 다른 버전이에요." 가 계속 보이거나, 운영 탭에서 "최신 아님" 이에요.

확인

• 맥은 세션이 모두 쉴 때 스스로 바꿔요. 일하는 세션이 있으면 기다려요.
• agent.log 에 --no-auto-update 로 켜져 있어 그대로 둠 이 있으면 자동 업데이트를 꺼 둔 거예요.
• 관리자 서명이 없거나 맞지 않아 버림 이 있으면 그 맥이 다른 서명 키를 믿어요.
• 운영 탭에 "업데이트 보류" 나 서명 안 됨, 업데이트 안 보냄 이 보이면 서버가 서명 문제로 보내지 않는 거예요.

해결

• 자동 업데이트를 다시 켜려면 설치 명령에 --auto-update 를 붙여 실행하세요(curl -fsSL SITE/install.sh | bash -s -- --auto-update). 이 선택은 agent.json 에 남아요.

• 서명 문제는 에이전트 서명 키를 따라 고치세요.

• 그래도 안 바뀌면 그 맥에서 설치 명령을 다시 실행하세요.

  curl -fsSL SITE/install.sh | bash

  SITE 는 서버 주소예요(예: https://bridge.example.com).

확인하기

고친 뒤 호스트 화면의 다시 점검 을 누르세요. 점검이 모두 초록이고, 기기 목록에서 맥이 "연결됨" 이면 해결된 거예요. doctor 를 다시 돌려 종료 코드가 0 인지 봐도 돼요.

다음 단계

• 점검 항목: 모든 점검과 해결 방법이에요.
• 설치 스크립트와 에이전트 명령: doctor, service, link 의 옵션이에요.
• 접근 관리와 운영 화면: 운영자가 모든 맥의 상태를 보는 곳이에요.