Claude Code 모바일 푸시 알림: 긴 작업 끝나면 폰으로 받기

긴 리팩토링이나 테스트를 Claude Code에 맡겨 두고 자리를 비우면, 제일 애매한 순간은 “끝났나?”를 확인하러 다시 터미널을 보는 때입니다. Remote Control로 폰에서 세션을 열 수는 있지만, 사용자가 계속 앱을 들여다봐야 한다면 자동화의 맛이 조금 덜합니다.

Claude Code Remote Control 공식 문서 ↗에 모바일 푸시 알림 설정이 추가됐습니다. 이 글은 작성 시점 2026-04-29 · 공식 문서 https://code.claude.com/docs/en/remote-control#mobile-push-notifications 스냅숏 기준으로, 언제 알림이 오고 어떻게 켜는지 정리합니다.

무엇이 달라졌나?

Remote Control은 로컬에서 실행 중인 Claude Code 세션을 claude.ai/code ↗나 Claude 모바일 앱에서 이어 쓰는 기능입니다. 실행은 로컬 머신에 남고, 웹·모바일 UI가 그 세션에 붙는 구조입니다.

모바일 푸시 알림은 이 Remote Control 위에 얹히는 기능입니다. 공식 문서 ↗에 따르면 Remote Control이 활성화된 상태에서 Claude가 필요하다고 판단하면 휴대폰으로 푸시를 보낼 수 있습니다.

sequenceDiagram
    participant U as 사용자
    participant CC as Claude Code<br/>로컬 세션
    participant RC as Remote Control
    participant App as Claude 모바일 앱

    U->>CC: 긴 작업 요청
    CC->>RC: Remote Control 세션 유지
    CC->>CC: 테스트·빌드·수정 진행
    alt 작업 완료 또는 사용자 결정 필요
        CC->>App: 모바일 푸시 알림
        App-->>U: 알림 표시
        U->>App: 세션 열고 확인·승인
    end

핵심은 “모든 이벤트를 다 알림으로 보내는 설정”이 아니라는 점입니다. Claude가 보낼 시점을 결정합니다. 문서가 예로 든 상황은 긴 작업이 끝났을 때 또는 계속 진행하려면 사용자 결정이 필요할 때입니다.

요구사항

모바일 푸시 알림을 쓰려면 먼저 Remote Control 자체가 동작해야 합니다. 공식 문서 기준 요구사항은 다음과 같습니다.

버전은 터미널에서 확인합니다.

claude --version

Remote Control은 API 키 기반 사용이 아니라 claude.ai 로그인 기반 기능입니다. 문서의 Troubleshooting 섹션도 ANTHROPIC_API_KEY가 설정되어 있거나 Console/API 키 방식으로 인증된 경우 Remote Control이 막힐 수 있다고 안내합니다.

설정 방법

공식 문서의 설정 단계는 네 가지입니다.

1. Claude 모바일 앱 설치

iOS용 Claude 앱 ↗ 또는 Android용 Claude 앱 ↗을 설치합니다.

앱이 없다면 Claude Code 안에서 /mobile 명령으로 앱 설치 QR 코드를 볼 수도 있습니다. 이 명령은 Remote Control 연결 방법 설명에도 함께 안내되어 있습니다.

/mobile

2. Claude Code와 같은 계정으로 로그인

모바일 앱에서는 터미널의 Claude Code에서 쓰는 계정과 같은 계정·조직으로 로그인해야 합니다. Team·Enterprise에서는 조직이 다르면 Remote Control 정책이나 세션 목록이 다르게 보일 수 있습니다.

3. OS 알림 권한 허용

앱 첫 실행 또는 알림 요청 시 운영체제 알림 권한을 허용합니다. iOS는 Focus 모드나 알림 요약이 푸시를 숨기거나 지연시킬 수 있고, Android는 배터리 최적화가 알림 전달을 늦출 수 있습니다.

4. Claude Code에서 Push 설정 켜기

터미널의 Claude Code에서 /config를 열고 Push when Claude decides를 활성화합니다.

/config

문서상 이 설정 외에 이벤트별 세부 설정은 없습니다. 즉 “테스트 완료만”, “권한 요청만”, “10분 이상 작업만” 같은 세밀한 필터는 현재 공식 설정으로 제공되지 않습니다.

언제 알림이 오나?

공식 문서가 설명하는 기준은 간단합니다.

1. Remote Control이 활성화되어 있어야 합니다.
2. Claude가 알림이 필요하다고 판단해야 합니다.
3. 대표적으로 긴 작업 완료 또는 사용자 결정이 필요한 순간입니다.
4. 사용자가 프롬프트에서 알림을 요청할 수도 있습니다.

실무에서는 아래처럼 쓰기 좋습니다.

테스트가 끝나면 알려줘. 실패하면 원인 요약과 수정 후보를 정리해줘.

빌드가 끝나면 푸시로 알려줘. 배포 전 확인이 필요한 변경이면 멈추고 물어봐.

리팩토링을 진행하고, 타입 체크까지 통과하면 알려줘.

여기서 중요한 점은 알림이 “작업 결과를 대신 검토해 주는 것”은 아니라는 점입니다. 푸시는 사용자를 다시 세션으로 데려오는 신호이고, 최종 승인·리뷰는 여전히 사람이 해야 합니다.

알림이 오지 않을 때 체크리스트

공식 문서의 Troubleshooting 항목을 기준으로 정리하면 다음 순서로 보면 됩니다.

/config에 No mobile registered가 보일 때

/config에서 No mobile registered가 보이면 Claude 앱이 아직 푸시 토큰을 갱신하지 못한 상태일 수 있습니다. 문서는 휴대폰에서 Claude 앱을 열어 푸시 토큰을 새로고침하라고 안내합니다. 이 경고는 다음 Remote Control 연결 때 사라집니다.

iOS에서 안 올 때

iOS에서는 Focus 모드, 알림 요약, 앱별 알림 설정이 푸시를 숨기거나 늦출 수 있습니다. 시스템 설정에서 Settings → Notifications → Claude를 확인합니다.

Android에서 늦게 올 때

Android는 제조사별 배터리 최적화가 백그라운드 알림을 늦출 수 있습니다. Claude 앱을 배터리 최적화 예외로 두는 것이 공식 문서의 권장 확인 항목입니다.

Remote Control 자체가 안 켜질 때

푸시 알림은 Remote Control 위에서 동작하므로 Remote Control 연결부터 확인해야 합니다. 특히 Team·Enterprise에서는 관리자가 Claude Code admin settings ↗에서 Remote Control을 켜야 합니다.

또한 공식 문서는 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, DISABLE_TELEMETRY, CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX, CLAUDE_CODE_USE_FOUNDRY 같은 환경 변수가 Remote Control eligibility 확인에 영향을 줄 수 있다고 안내합니다.

Channels와는 어떻게 다른가?

이 기능은 이름 때문에 Claude Code Channels와 헷갈릴 수 있습니다. 둘 다 “외부 신호”와 관련 있지만 방향이 다릅니다.

한 문장으로 정리하면, 모바일 푸시 알림은 Claude가 나를 부르는 기능이고, Channels는 외부 이벤트가 Claude를 부르는 기능입니다.

더 큰 작업 흐름에서는 Claude Code Routines처럼 정기 작업을 설계하고, 긴 실행은 Remote Control과 푸시 알림으로 감시하는 식으로 조합할 수 있습니다.

추천 사용 패턴

모바일 푸시 알림은 “계속 보고 있지 않아도 되는 작업”과 잘 맞습니다.

• 테스트·빌드·타입 체크처럼 시간이 걸리는 검증
• 대규모 리팩토링 후 결과 요약 요청
• 코드 리뷰 초안 작성 후 사람 승인 요청
• 문서 생성·마이그레이션처럼 완료 시점만 중요한 작업

반대로 빠르게 왕복해야 하는 페어 프로그래밍, 긴 코드 diff를 꼼꼼히 읽어야 하는 리뷰, 로컬 전용 interactive picker가 필요한 작업에는 모바일 푸시만 믿기 어렵습니다. 공식 문서도 /mcp, /plugin, /resume처럼 터미널의 interactive picker를 여는 명령은 local-only라고 안내합니다.

마무리

Claude Code 모바일 푸시 알림은 작은 기능처럼 보이지만, 실제 사용 패턴을 꽤 바꿉니다. 핵심은 세 가지입니다.

1. Remote Control이 켜져 있어야 합니다. 푸시는 독립 기능이 아니라 Remote Control 위에서 동작합니다.
2. Claude가 보낼 시점을 결정합니다. 긴 작업 완료, 사용자 결정 필요, 프롬프트로 요청한 상황이 대표적입니다.
3. 설정은 단순합니다. 모바일 앱 설치, 같은 계정 로그인, OS 알림 허용, /config의 Push when Claude decides 활성화가 전부입니다.

장시간 작업을 자주 맡긴다면, 다음 세션에서 notify me when the tests finish 한 줄을 같이 넣어 보세요. 터미널 앞에서 기다리는 시간이 조금 줄어듭니다.

관련 글

• Claude Code Remote Control — 원격 세션의 전체 개념과 보안 모델
• Claude Code Channels 살펴보기 — 외부 이벤트를 Claude Code 세션으로 전달하는 방식
• Claude Code Routines 살펴보기 — 반복 작업을 자동화하는 흐름

참고 자료

• Claude Code Remote Control 공식 문서 ↗ — Remote Control, 모바일 푸시 알림, 제한사항, Troubleshooting
• Claude iOS 앱 ↗ — 모바일 앱 설치
• Claude Android 앱 ↗ — 모바일 앱 설치
• Claude Code admin settings ↗ — Team·Enterprise Remote Control 조직 설정