모바일로 코딩하기: Claude Code Remote Control 완전 가이드

2026년 4월 1일·10 min read

DevTools claude-code remote-control mobile-development web-session productivity

이 글은 실제로 모바일 Claude 앱으로 원격에서 resumate 프로젝트를 개발하면서 배운 내용을 정리한 학습 기록입니다.

왜 원격 작업이 필요했나

데스크탑에서 Tauri + React 앱을 개발하다가, 외출 중에 간단한 수정 사항이 떠올랐다. 노트북을 들고 나가지 않아도 스마트폰으로 개발을 이어갈 수 없을까?

Claude Code는 이 문제를 두 가지 방식으로 해결한다.

Claude Code 원격 작업의 두 가지 방식

방식 1: Remote Control (로컬 실행, 원격 제어)

[내 맥북] ──── 로컬에서 실행 ────> Claude Code
    ↑                                  ↓
    │         Anthropic 서버 경유      │
[스마트폰] ◄── 웹/앱으로 제어 ─────────┘

핵심: Claude Code 프로세스는 내 맥북에서 돌아간다. 스마트폰은 그 세션을 "창"처럼 들여다보는 것.

로컬 파일 시스템에 직접 접근
MCP 서버, 로컬 환경 변수 모두 사용 가능
터미널을 닫으면 세션 종료

방식 2: Claude Code on the Web (클라우드 실행)

[스마트폰/브라우저] ──> Anthropic 클라우드 VM에서 실행
                              ↓
                        GitHub 저장소 클론 & 작업

핵심: 내 맥북이 꺼져도 클라우드에서 계속 돌아간다.

로컬 설치 불필요
GitHub 저장소 기반
완료 후 PR로 결과 제출

Remote Control 설정 방법

요구 사항

Claude Pro / Max / Team / Enterprise 구독
Claude Code v2.1.51 이상 (claude --version으로 확인)
API 키 방식 불가, claude.ai OAuth 로그인 필수

3가지 시작 방법

1) 서버 모드 (추천)

cd your-project
claude remote-control

터미널에 세션 URL과 QR 코드가 표시된다. 스페이스바를 누르면 QR 코드 토글.

# 이름 지정 + git worktree로 병렬 세션
claude remote-control --name "resumate" --spawn worktree

플래그	설명
`--name "프로젝트명"`	세션 목록에 표시될 이름
`--spawn worktree`	동시 접속 시 각각 별도 git worktree 생성
`--spawn same-dir`	동시 접속 시 같은 디렉토리 공유 (기본값)
`--capacity 32`	최대 동시 세션 수
`--verbose`	상세 로그 출력

2) 대화형 세션 + Remote Control

# 터미널에서도 입력하고, 모바일에서도 입력 가능
claude --remote-control "resumate"

3) 이미 실행 중인 세션에서 활성화

/remote-control
/remote-control resumate
/rc  # 단축 명령

모바일에서 연결하는 방법

QR 코드 스캔: 터미널에 표시된 QR 코드를 Claude 앱으로 스캔
URL 직접 접속: 브라우저에서 세션 URL 열기
앱에서 선택: claude.ai/code → 세션 목록에서 녹색 점(●)이 표시된 세션 선택

Claude 앱이 없다면 Claude Code 내에서:

/mobile

iOS/Android 다운로드 QR 코드가 표시된다.

모든 세션에서 자동 활성화하기

매번 플래그를 붙이기 귀찮다면:

/config
→ "모든 세션에 대해 Remote Control 활성화" → true

내부 동작 원리 (보안 메커니즘)

Remote Control은 어떻게 안전하게 원격 접속을 허용하는가?

내 맥북 (Claude Code)
    │
    │  아웃바운드 HTTPS 요청만 (인바운드 포트 열지 않음)
    │
    ▼
Anthropic API 서버
    │
    │  TLS 암호화 스트리밍
    │
    ▼
모바일 앱 / 브라우저

핵심 보안 설계:

내 컴퓨터에서 인바운드 포트를 열지 않는다
맥북 → Anthropic API로 아웃바운드 HTTPS만 사용 (폴링 방식)
각 연결은 단기 자격 증명(short-lived credentials) 사용
모든 트래픽은 TLS 암호화

이 구조 덕분에 방화벽 설정 변경 없이도 원격 접속이 가능하다.

웹에서 Claude Code: 클라우드 세션

로컬 머신이 꺼져도 작업이 계속되길 원한다면 클라우드 세션이 답이다.

시작 방법

브라우저에서:

claude.ai/code 접속
GitHub 계정 연결
저장소에 Claude GitHub 앱 설치
작업 제출

터미널에서 웹 세션 시작:

claude --remote "Fix the authentication bug in src/auth/login.ts"

이 명령 하나로 클라우드 VM이 생성되고, GitHub 저장소를 클론하고, Claude가 작업을 시작한다. 나는 그동안 다른 일을 해도 된다.

병렬 작업 예시

# 세 가지 작업을 동시에 클라우드에서 실행
claude --remote "Fix the flaky test in auth.spec.ts"
claude --remote "Update the API documentation"
claude --remote "Refactor the logger to use structured output"
 
# 진행 상황 확인
/tasks

클라우드 세션의 실행 흐름

1. 저장소 클론 (Anthropic 관리 VM)
2. 설정 스크립트 실행 (npm install 등)
3. Claude Code 시작
4. 코드 분석 → 변경 → 테스트 실행 → 검증
5. 완료 → 브랜치 push → PR 생성

Teleport: 클라우드 ↔ 터미널 전환

클라우드에서 시작한 작업을 로컬 터미널로 가져오거나, 반대로 터미널 작업을 클라우드로 보낼 수 있다.

웹 → 터미널

# 대화형 세션 선택기
claude --teleport
 
# 특정 세션 직접 지정
claude --teleport <session-id>
 
# 세션 내에서
/teleport
/tp  # 단축 명령

Teleport 요구 사항:

현재 디렉토리가 clean한 git 상태여야 함 (uncommitted 변경 없음)
동일한 저장소의 체크아웃이어야 함
동일한 claude.ai 계정으로 인증

터미널 → 웹

# 새로운 웹 세션 시작
claude --remote "Execute the migration plan in docs/migration-plan.md"

주의: 기존 터미널 세션을 웹으로 "이동"시키는 건 불가능. --remote는 항상 새 세션 생성.

접근 방법 선택 가이드

상황	최적 방법
외출 중에 집 맥북 세션 이어서 작업	Remote Control
맥북 꺼도 되고, 오래 걸리는 작업 위임	Claude Code on the Web
여러 버그 동시에 병렬 수정	`--remote` 병렬 실행
모바일에서 데스크탑 앱에 작업 던지기	Dispatch
Telegram/Discord 이벤트로 세션 트리거	Channels
PR 검토, CI 실패 자동 수정	GitHub Actions + Slack

실제 사용 사례: resumate 프로젝트

이번에 실제로 겪은 워크플로우:

맥북에서 개발 시작: Tauri + React 앱, Nova 에이전트 구현
이동 중 모바일로 접속: claude remote-control → QR 코드 스캔
모바일에서 작업 지시: "ForgeView를 NovaView로 리네임하고 nova.lottie 에셋 연결해줘"
터미널 확인: 맥북에서 변경 사항 확인, 테스트
커밋 & 푸시: 모바일에서도 커밋 메시지 작성 지시 가능

# 집에서 시작
claude remote-control --name "resumate"
 
# 터미널에 출력된 URL을 모바일에서 열거나 QR 스캔
# → 소파에서 스마트폰으로 코드 리뷰 및 수정 지시

트러블슈팅

"Remote Control이 계정에 활성화되지 않았습니다"

# 환경 변수 확인
echo $CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC
echo $CLAUDE_CODE_USE_BEDROCK
 
# 재로그인 시도
/logout
/login

"Remote Control이 조직 정책에 의해 비활성화됨"

API 키로 로그인 중: /login → claude.ai OAuth 선택
Team/Enterprise: 관리자가 claude.ai/admin-settings/claude-code에서 토글 활성화 필요

버전 오류

claude --version  # v2.1.51 이상인지 확인
curl -fsSL https://claude.ai/install.sh | bash  # 업데이트

핵심 정리

원격 작업의 두 패러다임:
 
Remote Control     = 내 맥북을 원격으로 조종
                   = 로컬 환경 그대로, 창만 다른 기기
 
Web Session        = 클라우드에 위임
                   = 내 맥북 상태 무관, 24/7 실행 가능

Remote Control을 선택할 때:

로컬 파일, MCP 서버, 환경 설정이 필요한 작업
작업 중간에 다른 기기로 전환해야 할 때

Web Session을 선택할 때:

작업 위임 후 다른 일을 해야 할 때
여러 작업을 병렬로 처리할 때
로컬 환경 세팅 없이 빠르게 시작할 때