원격 제어 (Remote Control)
원격 제어란?
원격 제어(Remote Control)는 내 컴퓨터에서 실행 중인 Claude Code 세션을 claude.ai/code나 Claude 모바일 앱에서 이어서 사용할 수 있는 기능입니다.
핵심 포인트: 세션은 내 컴퓨터에서 로컬로 실행됩니다. 클라우드로 코드가 이동하는 것이 아니라, 웹/모바일 인터페이스가 로컬 세션의 "창" 역할을 합니다.
원격 제어 연결 구조
QR 코드 스캔
세션 목록에서 연결
URL 직접 열기
로컬 파일 전체 접근
MCP 서버 활용
코드 외부 이동 없음
포트 443만 사용
동시 접속: 스마트폰 + 태블릿 + 브라우저 동시 가능 | 10분 네트워크 장애 시 타임아웃
클라우드 세션과의 차이
| 항목 | 원격 제어 | 클라우드 세션 |
|---|---|---|
| 실행 위치 | 내 컴퓨터 | Anthropic 클라우드 |
| 파일 접근 | 로컬 파일시스템 전체 | Git 클론만 |
| MCP 서버 | 내 설정된 서버 사용 | 커넥터만 가능 |
| 컴퓨터 켜야 하나 | 예 | 아니오 |
| 설정 | claude remote-control 실행 | 별도 설정 불필요 |
| 적합한 상황 | 진행 중인 로컬 작업 이어가기 | 로컬 환경 없이 시작 |
요구사항
- Claude Code v2.1.51 이상
- Pro, Max, Team, 또는 Enterprise 플랜 (Team/Enterprise는 관리자 활성화 필요)
- 전체 범위 로그인(Full-scope Login) 필수
- 프로젝트에서
claude를 한 번 이상 실행하여 워크스페이스 신뢰 수락
인증 방식 확인
원격 제어는 전체 범위(full-scope) 로그인만 지원합니다:
# 올바른 방법: claude.ai로 전체 범위 로그인
claude auth login
# → claude.ai 옵션 선택
지원하지 않는 인증:
- API 키 (
ANTHROPIC_API_KEY) - 단기 설정 토큰 (Console 토큰)
사용 방법
방법 1: 서버 모드 (전용 원격 서버)
여러 세션을 동시에 지원하는 전용 서버입니다:
# 기본 실행
claude remote-control
# 이름 지정
claude remote-control --name "내 프로젝트"
# 여러 세션 동시 지원 + 워크트리 격리
claude remote-control --capacity 5 --spawn worktree
실행하면 터미널에 표시되는 정보:
- 브라우저에서 열 세션 URL
- QR 코드 (스페이스바로 토글)
- 연결 상태
방법 2: 인터랙티브 세션 + 원격 제어
# 터미널에서 작업하면서 동시에 원격 접근 가능
claude --remote-control
# 이름 지정
claude --remote-control "내 프로젝트"
터미널에서 직접 작업하면서, 동시에 웹/모바일에서도 접근할 수 있습니다.
방법 3: 기존 세션에서 활성화
이미 실행 중인 Claude Code 세션에서:
/remote-control
# 이름 지정
/remote-control 내 프로젝트
원격에서 접속하기
세션이 활성화되면 세 가지 방법으로 접속할 수 있습니다:
- URL 직접 열기: 터미널에 표시된 세션 URL을 브라우저에서 열기
- QR 코드 스캔: Claude 모바일 앱으로 QR 코드 스캔
- 세션 목록: claude.ai/code에서 세션 이름으로 찾기 (초록색 상태 점 표시)
서버 모드 옵션
claude remote-control \
--name "내 프로젝트" # 세션 이름 지정
--capacity 5 # 최대 동시 세션 수 (기본값 32)
--spawn worktree # 각 세션을 Git 워크트리로 격리 (기본값: 같은 디렉토리)
--sandbox # 파일시스템/네트워크 격리 활성화
--verbose # 상세 연결 로그 출력
--spawn 옵션
| 값 | 설명 |
|---|---|
same-dir (기본값) | 모든 세션이 같은 디렉토리 사용 |
worktree | 각 세션이 별도의 Git 워크트리에서 실행 (격리) |
worktree를 사용하면 여러 세션이 서로의 파일을 건드리지 않아 안전합니다.
모든 세션에서 자동 활성화
매번 수동으로 원격 제어를 켜지 않고, 항상 활성화하려면:
방법 1: 설정 UI
/config
# "Enable Remote Control for all sessions" → true로 변경
방법 2: 쉘 프로필에 alias 등록
~/.bashrc 또는 ~/.zshrc에 다음을 추가합니다:
# 원격 제어 자동 활성화 alias
alias claude='claude --remote-control'
프로젝트별로 항상 특정 세션 이름으로 시작하려면:
# 프로젝트 디렉토리의 .envrc 또는 Makefile에서
claude --remote-control --remote-control-session-name-prefix "my-project"
공식 설정 문서에 remoteControl.* 키는 정의되어 있지 않습니다. 원격 제어 활성화는 claude --remote-control CLI 플래그 또는 /config UI를 통해 설정합니다.
네트워크 요구사항
원격 제어는 아웃바운드 HTTPS 연결만 사용합니다. 인바운드 포트를 열 필요가 없습니다.
| 항목 | 상세 |
|---|---|
| 프로토콜 | HTTPS (TLS 1.2 이상) |
| 포트 | 443 (아웃바운드만) |
| 대상 도메인 | *.anthropic.com, *.claude.ai |
| 연결 방식 | 폴링(Polling) — 내 컴퓨터가 주기적으로 Anthropic API에 확인 |
| WebSocket | 사용하지 않음 |
| 프록시 | HTTPS_PROXY 환경 변수 지원 |
기업 네트워크에서 *.anthropic.com과 *.claude.ai 도메인의 아웃바운드 443 포트가 차단되어 있으면 원격 제어가 동작하지 않습니다. IT 관리자에게 해당 도메인의 허용을 요청하세요.
성능 및 대역폭
| 항목 | 수치 |
|---|---|
| 폴링 간격 | 수초 (Anthropic 서버가 자동 조절) |
| 대역폭 사용 | 매우 낮음 (텍스트 기반 통신) |
| 지연 시간 | 일반적으로 1~3초 (네트워크 상태에 따라 다름) |
| 모바일 데이터 | 텍스트 위주로 데이터 소비 최소 |
연결 품질 팁
- VPN 사용 시: VPN이
*.anthropic.com트래픽을 차단하지 않는지 확인 - Wi-Fi 불안정 시: 자동 재연결이 동작하므로 일시적 끊김은 문제 없음
- 모바일 네트워크: 4G/5G 환경에서 정상 동작, 3G에서는 지연 가능
- 해외 출장 시: 해당 국가에서 Anthropic 도메인 접근 가능 여부 확인
보안
- 아웃바운드(Outbound, 나가는 방향) HTTPS만 사용: 내 컴퓨터에 인바운드(Inbound, 들어오는 방향) 포트를 열지 않음
- 폴링(Polling) 기반: 내 컴퓨터가 주기적으로 Anthropic API에 새 작업이 있는지 확인
- TLS 암호화: 모든 트래픽이 암호화됨
- 단기 인증 정보: 각 인증 정보는 단일 목적으로 한정, 독립적으로 만료
- 동시 접속: 스마트폰, 태블릿, 브라우저에서 동시에 접속 가능
동작 특성
- 모든 연결 디바이스에서 대화가 실시간 동기화
- 노트북 절전이나 네트워크 끊김 시 자동 재연결
- 터미널을 닫으면 세션 종료
- 10분 이상 네트워크 장애 시 세션 타임아웃
- 인터랙티브 세션은 원격 세션 1개만 지원 (여러 개 필요하면 서버 모드 사용)
다른 원격 기능과 비교
| 기능 | 원격 제어 | 디스패치 | 채널 | 스케줄 |
|---|---|---|---|---|
| 트리거 | 웹/모바일에서 직접 | 모바일 작업 요청 | 외부 메시지 | 시간 간격 |
| 방향 | 양방향 실시간 | 작업 위임 + 결과 | 양방향 메시지 | 자동 실행 |
| 실행 위치 | 내 컴퓨터 | 내 컴퓨터 | 내 컴퓨터 | 내 컴퓨터/클라우드 |
| 세션 생성 | 기존 세션 연결 | 자동 생성 | 기존 세션 연결 | 기존 세션 내 |
문제 해결
"Remote Control requires a claude.ai subscription"
claude.ai로 인증되지 않았습니다:
claude auth login
# → claude.ai 옵션 선택
"Remote Control requires a full-scope login token"
제한된 API 키를 사용하고 있습니다:
# 전체 범위 로그인 필요
claude auth login
"Remote Control is disabled by your organization's policy"
Team/Enterprise에서 관리자가 활성화하지 않았습니다. 관리자에게 요청하세요.
"Remote credentials fetch failed"
네트워크 또는 프록시 문제입니다:
# 상세 로그로 원인 파악
claude remote-control --verbose
방화벽이 Anthropic API (포트 443)를 차단하고 있는지 확인하세요.
연결이 자주 끊기는 경우
# 1. 네트워크 연결 상태 확인
curl -I https://api.anthropic.com
# 2. verbose 모드로 원인 파악
claude remote-control --verbose
# 3. 프록시 환경이라면 환경 변수 설정
export HTTPS_PROXY=http://proxy.company.com:8080
claude remote-control
실전 활용 시나리오
카페에서 작업 이어가기
- 회사에서
claude --remote-control "auth-refactor"로 세션 시작 - 작업 중 퇴근
- 카페에서 claude.ai/code 접속 → 세션 이어서 작업
모바일에서 진행 상황 확인
claude remote-control로 서버 모드 실행- 장시간 작업 위임 (예: 대규모 리팩토링)
- 이동 중 스마트폰으로 진행 상황 확인 및 피드백
팀원에게 세션 공유
claude remote-control --name "디버깅 세션" --capacity 2- 세션 URL을 팀원에게 공유
- 같은 세션에서 함께 작업
페어 프로그래밍 세션
원격 제어를 활용하면 물리적으로 떨어진 팀원과 실시간 페어 프로그래밍이 가능합니다.
# 1. 서버 모드로 시작 (2인 동시 접속)
claude remote-control --name "pair-auth-refactor" --capacity 2 --spawn worktree
워크플로우:
개발자 A (터미널) 개발자 B (브라우저)
───────────────── ─────────────────
세션 URL 공유 → claude.ai/code에서 세션 접속
│
"인증 로직 구조를 설명해줘" │ 실시간으로 Claude 응답 확인
│ │
Claude가 코드 분석 + 설명 │
│ │
"토큰 갱신 로직에 race condition이
있는 것 같아. 확인해줘"
│ │
Claude가 문제 확인 + 수정 제안 │
│ │
"수정해줘" │ diff 리뷰
│ │
Claude가 코드 수정 "LGTM, PR 만들어줘"
--spawn worktree를 사용하면 각 세션이 독립된 워크트리에서 작업하여 충돌 방지- 한 명은 터미널에서 직접 작업, 다른 한 명은 웹에서 리뷰 + 피드백 역할 분담
- 복잡한 버그를 함께 디버깅할 때 특히 유용
라이브 데모 세션
컨퍼런스 발표나 팀 미팅에서 Claude Code를 라이브 코딩 데모에 활용할 수 있습니다.
# 발표자 컴퓨터에서
claude remote-control --name "live-demo-react" --capacity 10
데모 진행 방식:
1. 발표자가 세션 URL 또는 QR 코드를 화면에 표시
2. 청중이 스마트폰/노트북으로 접속하여 실시간 관전
3. 발표자가 Claude에게 라이브 코딩 요청:
"React로 할 일 목록 앱을 처음부터 만들어줘. TypeScript 사용."
4. 청중이 실시간으로 코드 생성 과정을 관전
5. 청중 질문: "테스트도 추가해줄 수 있어?" → 발표자가 즉시 요청
- 네트워크 안정성 확인 (유선 연결 권장)
--verbose플래그로 사전 테스트- 데모용 프로젝트 디렉토리 미리 준비
- 권한 프롬프트 방지를 위해 필요한 도구를 미리 허용
Remote Control vs 다른 원격 접근 비교
세 기능 모두 '다른 기기에서 Claude를 사용'하지만 방식이 다릅니다.
| 기능 | 핵심 차이 | 적합한 상황 |
|---|---|---|
| Remote Control | 로컬 세션을 그대로 공유 | "지금 돌아가는 작업 확인하고 싶다" |
| Dispatch | 새 작업을 만들어서 전달 | "새로운 작업을 시키고 싶다" |
| Cloud Sessions | 클라우드 VM에서 독립 실행 | "내 컴퓨터를 안 켜고 싶다" |
Remote Control은 '보기' — 이미 실행 중인 세션의 창을 다른 기기에서 여는 것입니다. Dispatch는 '시키기' — 폰에서 새 작업 지시를 내리고 결과 알림을 기다립니다. Cloud Sessions는 '빌리기' — 내 컴퓨터 대신 클라우드 VM을 사용합니다. 현재 진행 중인 작업에 접근할 때는 Remote Control, 새 작업을 시작할 때는 Dispatch나 Cloud Sessions를 선택하세요.
연계 기능
장점, 단점과 한계점
장점
- 어디서든 로컬 세션 접근: 카페, 지하철, 해외 출장 등 어디서든 웹 브라우저나 모바일 앱으로 로컬에서 실행 중인 세션에 접속할 수 있습니다
- 코드가 클라우드로 이동하지 않음: 세션은 내 컴퓨터에서 로컬로 실행되므로, 코드와 환경 설정이 외부로 노출되지 않습니다
- 실시간 동기화: 모든 연결 디바이스에서 대화가 실시간으로 동기화되어 끊김 없는 작업 경험을 제공합니다
- 자동 재연결: 노트북 절전이나 일시적 네트워크 끊김 후 자동으로 재연결되어 수동 개입이 필요 없습니다
- 멀티 디바이스 동시 접속: 스마트폰, 태블릿, 브라우저에서 동시에 같은 세션에 접속하여 페어 프로그래밍이나 라이브 데모가 가능합니다
단점과 한계점
- 컴퓨터 켜져 있어야 함: 로컬 세션 기반이므로 컴퓨터가 절전 모드이거나 꺼져 있으면 원격 접속이 불가능합니다
- 전체 범위 로그인 필수: API 키나 단기 토큰으로는 사용할 수 없고, claude.ai 전체 범위(full-scope) 로그인이 반드시 필요합니다
- 10분 네트워크 장애 시 타임아웃: 10분 이상 네트워크가 끊기면 세션이 타임아웃되어 재시작해야 합니다
- 인터랙티브 모드는 1개 세션만: 인터랙티브 세션은 원격 세션 1개만 지원하여, 여러 세션이 필요하면 서버 모드를 사용해야 합니다
컴퓨터를 켜 둘 수 없는 상황이라면 클라우드 세션을 대안으로 사용하세요. 여러 세션이 필요하면 claude remote-control --capacity 5 --spawn worktree로 서버 모드를 실행하면 최대 32개 동시 세션을 지원합니다.