(1/3) Claude Code Remote Control — 폰으로 내 PC 세션 이어받기
📱 터미널 밖에서 Claude Code 쓰기 시리즈 (전체 3편)
- Remote Control — 폰으로 내 PC 세션 이어받기 ← 지금 글
- Dispatch — 폰에서 작업 맡기고 결과만 받기
- Channels — 텔레그램·CI 이벤트를 세션에 흘려보내기
Summary
책상에서 Claude Code 로 작업을 돌려놓고 잠깐 자리를 비웠는데, 소파에서 폰으로 “그거 다 됐나?” 확인하고 싶을 때가 있어요. Remote Control(원격 제어) 이 정확히 그걸 해줍니다. 내 PC 에서 돌고 있는 세션을 폰·태블릿·다른 컴퓨터 브라우저에서 그대로 이어받아 메시지를 보내고, 결과를 보고, 승인까지 할 수 있어요.
이 글에서는 Remote Control 이 어떤 기능인지, 어떻게 켜고 접속하는지, 실제로 어떻게 쓰는지를 처음 보는 분도 따라올 수 있게 차근차근 풀어볼게요.
💡 이 글에서 다루는 것
- Remote Control 이 뭐고, “웹용 Claude Code” 와 뭐가 다른지
- 시작 전 준비물 (버전·플랜·로그인)
- 세 가지 시작 방법 (서버 모드 / 인터랙티브 / 진행 중 세션 전환)
- 폰·브라우저에서 접속하는 3가지 경로 (URL·QR·세션 목록)
- 실전 워크플로우 예시
- 모바일 푸시 알림 설정
- 보안은 안전한지, 한계는 무엇인지
- 장점·단점 한눈 정리
1. Remote Control 이 뭔가요?
한 문장으로 요약하면, “세션은 내 PC 에서 돌고, 조종은 폰이나 브라우저에서” 하는 기능이에요.
조금 더 풀어볼게요. 보통 Claude Code 는 내 컴퓨터 터미널에서 돌아갑니다. 내 파일을 읽고, 내가 설정해둔 MCP 서버를 쓰고, 내 프로젝트 폴더를 그대로 봅니다. Remote Control 을 켜면 이 로컬 세션은 그대로 둔 채, 화면만 폰이나 다른 브라우저로 하나 더 열어주는 거예요. 폰에서 메시지를 보내도 실제 작업은 내 PC 에서 실행됩니다.
그래서 폰에서도 @ 를 치면 내 프로젝트 파일 경로가 자동완성되고, 로컬 MCP 서버도 그대로 동작해요. 아무것도 클라우드로 올라가지 않습니다. 웹·모바일 화면은 그저 내 PC 세션을 들여다보는 창문일 뿐이에요.
그리고 연결이 한 방향만 되는 게 아니라 모든 기기에서 대화가 실시간으로 동기화 됩니다. 터미널에서 한 줄 치고, 폰에서 한 줄 치고, 브라우저에서 한 줄 쳐도 같은 대화로 합쳐져요. 노트북이 잠자기에 들어가거나 잠깐 네트워크가 끊겨도, 다시 깨어나면 알아서 재연결됩니다.
✅ 핵심: 로컬 실행 + 원격 조종 + 실시간 동기화. 클라우드로 코드가 올라가는 게 아니에요.
2. “웹용 Claude Code” 랑 헷갈리지 않기
이름이 비슷하고 똑같이 claude.ai/code 화면을 쓰다 보니 헷갈리기 쉬운데, 세션이 어디서 도는지 가 결정적으로 다릅니다.
| Remote Control | Claude Code on the web | |
|---|---|---|
| 세션 실행 위치 | 내 PC (CLI·VS Code) | Anthropic 클라우드 |
| 내 로컬 파일 | 그대로 접근, @ 자동완성 됨 |
접근 불가 (레포를 새로 받아야) |
| 내 로컬 MCP 서버 | 그대로 사용 | 사용 불가 |
| 시작 방법 | claude remote-control 실행 |
그냥 claude.ai/code 접속 |
| 내 PC 의존성 | PC 가 켜져 있어야 함 | PC 안 켜도 됨 |
| 잘 맞는 상황 | 진행 중인 로컬 작업을 다른 기기에서 이어받기 | 로컬 셋업 없이 새 작업 시작, 병렬 작업 |
쉽게 가르면 이래요. 이미 내 PC 에서 하던 작업을 다른 기기에서 마저 하고 싶으면 Remote Control, 로컬 세팅 없이 새로 시작하거나 여러 작업을 병렬로 돌리고 싶으면 웹용 Claude Code 입니다.
3. 시작 전 준비물
세 가지만 확인하면 됩니다.
① 버전 — Claude Code v2.1.51 이상이 필요해요. 터미널에서 확인합니다.
claude --version
2.1.175 (Claude Code)
이렇게 2.1.51 보다 높으면 OK 예요. (모바일 푸시 알림까지 쓰려면 v2.1.110 이상을 권장합니다.)
② 플랜과 로그인 — Pro·Max·Team·Enterprise 플랜에서 동작합니다. 중요한 건 API 키로는 안 된다 는 점이에요. 반드시 claude.ai 계정으로 로그인해야 합니다.
claude
# 세션 안에서
/login
⚠️ 환경변수에
ANTHROPIC_API_KEY가 설정돼 있으면 Remote Control 이 거부됩니다. 그럴 땐 먼저 그 변수를 해제(unset)하고/login으로 claude.ai 로그인을 다시 잡아주세요.claude setup-token으로 만든 장기 토큰(CLAUDE_CODE_OAUTH_TOKEN)도 추론 전용이라 Remote Control 에는 못 써요.
③ 워크스페이스 신뢰 — 프로젝트 폴더에서 claude 를 한 번이라도 실행해서 “이 폴더를 신뢰하시겠어요?” 다이얼로그를 수락해둬야 합니다. 평소에 쓰던 프로젝트라면 이미 통과한 상태일 거예요.
🚨 Team·Enterprise 사용자라면 Remote Control 이 기본적으로 꺼져 있어요. 관리자가 Claude Code 관리자 설정에서 토글을 켜줘야 합니다. 개인 Pro·Max 는 바로 쓸 수 있어요.
4. 세 가지 시작 방법
상황에 맞게 고르면 됩니다. 처음이라면 서버 모드(첫 번째)가 제일 직관적이에요.
4-1. 서버 모드 — claude remote-control
프로젝트 폴더에서 이 명령 하나면 끝나요.
claude remote-control
실행하면 터미널이 “서버 모드” 로 떠서 원격 연결을 기다립니다. 화면에 세션 URL 이 뜨고, 스페이스바를 누르면 QR 코드 가 나타나요. 폰으로 그 QR 을 찍으면 바로 연결됩니다.
자주 쓰는 플래그를 정리하면 이렇습니다.
| 플래그 | 설명 |
|---|---|
--name "프로젝트명" |
claude.ai 세션 목록에 보일 제목을 직접 지정 |
--spawn worktree |
원격 연결마다 별도의 git worktree 를 생성 (파일 충돌 방지, git 레포 필요) |
--spawn session |
단일 세션만 받고 추가 연결은 거부 |
--capacity <N> |
동시 세션 최대 개수 (기본 32) |
--sandbox / --no-sandbox |
파일시스템·네트워크 격리 켜기/끄기 (기본 꺼짐) |
--verbose |
연결·세션 로그 상세 출력 |
예를 들어 이름을 붙여서 띄우면 세션 목록에서 찾기가 훨씬 편해져요.
claude remote-control --name "결제 API 버그 수정"
4-2. 인터랙티브 세션 — claude --remote-control
평소처럼 터미널에서 직접 타이핑하면서, 동시에 원격으로도 열어두고 싶을 때 씁니다.
claude --remote-control
이름도 같이 줄 수 있어요.
claude --remote-control "결제 API 버그 수정"
서버 모드와 다른 점은, 로컬 터미널에서도 그대로 타이핑이 된다 는 거예요. 책상에선 키보드로 치고, 잠깐 화장실 갈 땐 폰으로 이어보는 식이죠. 연결되면 입력창 아래에 Remote Control active 표시가 뜨고, 그 표시를 아래 화살표로 선택해 Enter 를 누르면 세션 URL 과 QR 코드 패널이 열립니다.
4-3. 진행 중인 세션을 전환 — /remote-control
이미 Claude Code 로 한참 작업 중인데 “아, 이거 폰으로 이어서 봐야겠다” 싶을 때예요. 세션 안에서 이 명령을 치면 됩니다.
/remote-control
이름을 붙이려면 인자로 넘기면 돼요.
/remote-control 결제 API 버그 수정
좋은 점은 지금까지의 대화 히스토리를 그대로 들고 원격 세션으로 넘어간다는 거예요. 작업 맥락이 끊기지 않아요. (/rc 로 줄여 칠 수도 있습니다.)
💡 VS Code 확장에서도 프롬프트 칸에
/remote-control또는/rc를 치면 됩니다. (v2.1.79이상) 배너에 연결 상태가 뜨고 Open in browser 버튼으로 바로 열려요.
5. 다른 기기에서 접속하기
세션을 띄웠으면, 폰이나 다른 컴퓨터에서 접속하는 방법은 세 가지예요.
- 세션 URL 열기 — 터미널에 뜬 URL 을 아무 브라우저에서나 열면 바로 그 세션으로 들어갑니다.
- QR 코드 스캔 —
claude remote-control에서 스페이스바를 눌러 QR 을 띄우고, 폰으로 찍으면 Claude 앱에서 바로 열려요. 제일 빠른 길입니다. - 세션 목록에서 찾기 —
claude.ai/code나 Claude 모바일 앱(하단 Code 탭)을 열면 세션 목록이 나와요. 온라인 상태인 Remote Control 세션은 컴퓨터 아이콘 + 초록 점 으로 표시됩니다.
세션 제목은 이 순서로 정해져요. ① --name 등으로 직접 준 이름 → ② /rename 으로 바꾼 제목 → ③ 대화의 마지막 의미 있는 메시지 → ④ myhost-graceful-unicorn 같은 자동 생성 이름. 그래서 이름을 안 주면 처음엔 자동 이름이었다가, 첫 메시지를 보내면 그 내용으로 제목이 갱신됩니다.
💡 아직 Claude 앱이 없으면 Claude Code 안에서
/mobile을 치세요. iOS·Android 다운로드 QR 코드를 띄워줍니다.
6. 모든 세션에 자동으로 켜기
매번 플래그를 붙이기 귀찮으면, 인터랙티브 세션마다 Remote Control 이 자동으로 켜지게 할 수 있어요. 세션 안에서 설정을 엽니다.
/config
거기서 Enable Remote Control for all sessions 를 true 로 바꾸면 끝이에요. 끄고 싶으면 다시 false 로 돌리면 됩니다. (데스크톱 앱이라면 Settings → Claude Code → Enable remote control by default 에서도 토글할 수 있어요.)
이 설정을 켜면 인터랙티브 Claude Code 프로세스마다 원격 세션이 하나씩 등록돼요. 여러 개를 띄우면 각각 자기 세션을 갖습니다. 단, 한 프로세스에서 여러 세션을 동시에 굴리고 싶으면 그건 서버 모드(claude remote-control)의 몫이에요.
7. 실전 워크플로우 예시
말로만 들으면 감이 잘 안 오니, 실제로 이렇게 쓴다는 그림을 몇 개 그려볼게요.
예시 ① 책상에서 시작해 소파에서 이어받기
# 책상 PC 에서
claude remote-control --name "리포트 생성 스크립트"
# 터미널에 세션 URL 출력 + 스페이스바로 QR 표시
폰으로 QR 을 찍거나 Claude 앱 Code 탭에서 세션을 탭하면, 소파에 앉아서 Claude 가 짠 코드를 읽고, 후속 지시를 보내고, 변경 승인까지 폰으로 할 수 있어요. 작업 자체는 계속 책상 PC 에서 돌아갑니다.
예시 ② 긴 작업 걸어두고 알림 기다리기
테스트 스위트 전체 돌리기처럼 오래 걸리는 작업을 걸어두고 자리를 뜰 때, 프롬프트에 한 줄 덧붙이면 됩니다.
테스트 다 끝나면 폰으로 알려줘
그러면 작업이 끝났을 때 폰으로 푸시가 와요. (푸시 설정은 바로 다음 절에서 다룹니다.)
예시 ③ 팀이 한 서버에 같이 붙기
claude remote-control --spawn worktree --capacity 10
공용 머신에서 서버 모드로 띄우고, 최대 10명이 동시에 접속하는 구성이에요. --spawn worktree 라서 각자 자기 worktree 를 받아 같은 파일을 동시에 건드려도 충돌이 안 납니다.
8. 모바일 푸시 알림
Remote Control 이 켜져 있으면 Claude 가 폰으로 푸시를 보낼 수 있어요. 보통 오래 걸리는 작업이 끝났을 때, 또는 판단이 필요해서 사용자 입력을 기다릴 때 알아서 보냅니다. 앞 예시처럼 프롬프트에 “끝나면 알려줘” 라고 직접 부탁할 수도 있고요.
설정은 네 단계예요.
- Claude 모바일 앱(iOS·Android)을 설치합니다.
- 터미널에서 쓰는 것과 같은 계정·조직 으로 로그인합니다.
- OS 의 알림 권한 요청을 수락합니다.
- 터미널에서
/config를 열어 Push when Claude decides 를 켭니다.
⚠️ 알림이 안 오면?
/config에 No mobile registered 가 뜨면 폰에서 Claude 앱을 한 번 열어주세요(푸시 토큰 갱신). iOS 는 집중 모드·알림 요약이 푸시를 늦출 수 있으니 설정 → 알림 → Claude 를 확인하고, Android 는 배터리 최적화에서 Claude 앱을 예외로 빼주세요.
9. 보안은 안전한가요?
원격이라는 말에 “혹시 내 PC 에 포트가 열리는 거 아냐?” 걱정될 수 있는데, 구조가 안전한 편이에요.
- 인바운드 포트를 열지 않습니다. 내 PC 는 바깥쪽(Anthropic API)으로 나가는 HTTPS 요청만 보내고, 일감을 폴링해서 가져옵니다. 외부에서 내 PC 로 직접 들어오는 통로가 없어요.
- 모든 트래픽이 TLS 로 Anthropic API 를 거칩니다. 일반 Claude Code 세션과 똑같은 전송 보안이에요.
- 짧은 수명의 자격증명 을 여러 개 쓰고, 각각 용도가 하나로 한정되며 독립적으로 만료됩니다.
🚨 그래도 본질적으로 “내 로컬 환경을 원격에서 조종” 하는 기능이에요. 세션 URL 을 아무에게나 공유하면 그 사람이 내 파일을 건드릴 수 있다는 뜻이니, URL·QR 공유는 신뢰하는 사람에게만 하세요. 공용 머신에 띄울 땐
--sandbox로 파일시스템·네트워크 격리를 거는 것도 고려할 만해요.
10. 한계와 주의점
장점만 있는 건 아니에요. 미리 알아두면 덜 당황합니다.
- 내 PC 가 계속 켜져 있어야 합니다. 터미널을 닫거나 VS Code 를 끄거나
claude프로세스를 멈추면 세션도 끝나요. 클라우드가 대신 돌려주는 게 아니에요. - 네트워크가 오래 끊기면 종료됩니다. PC 는 깨어 있는데 네트워크가 ~10분 넘게 안 잡히면 세션이 타임아웃돼 프로세스가 종료돼요. 그땐
claude remote-control을 다시 실행해서 새로 시작해야 합니다. - 인터랙티브 모드는 프로세스당 원격 세션 하나 예요. 여러 개를 동시에 돌리려면 서버 모드를 쓰세요.
- Ultraplan 과는 같이 못 켭니다. Ultraplan 세션을 시작하면 활성 Remote Control 이 끊겨요. 둘 다
claude.ai/code화면을 차지하는데 한 번에 하나만 붙을 수 있거든요. - 일부 명령은 로컬 전용이에요. 터미널에서 선택 창을 띄우는
/plugin,/resume같은 명령은 로컬 CLI 에서만 됩니다. 반면/compact,/clear,/context,/usage,/exit,/recap,/reload-plugins처럼 텍스트만 출력하는 명령은 모바일·웹에서도 동작해요. (v2.1.166부터는/mcp도 모바일·웹에서 텍스트 요약 형태로 동작합니다.)
11. 장점·단점 한눈 정리
지금까지 내용을 표로 압축하면 이렇습니다.
| 👍 장점 | 👎 단점 |
|---|---|
| 내 로컬 환경(파일·MCP·설정) 그대로 원격 사용 | 내 PC 가 켜져 있고 네트워크가 살아있어야 함 |
| 코드가 클라우드로 안 올라감 | ~10분 이상 네트워크 끊기면 세션 종료 |
| 폰·태블릿·브라우저 어디서나 이어받기 | 인터랙티브 모드는 프로세스당 세션 1개 |
| 모든 기기 대화 실시간 동기화 | Ultraplan 과 동시 사용 불가 |
| 끊겨도 자동 재연결 | 일부 명령(/plugin·/resume)은 로컬 전용 |
| 플래그 하나로 시작, 추가 셋업 거의 없음 | API 키 불가 — claude.ai 로그인 필수 |
| 서버 모드 + worktree 로 팀 동시 접속 | Team·Enterprise 는 관리자 토글 필요 |
| 모바일 푸시 알림 지원 | 푸시는 앱·OS 권한·/config 설정이 다 필요 |
12. 자주 막히는 곳
처음 켤 때 잘 만나는 에러 몇 개만 짚어둘게요.
- “requires a claude.ai subscription” — API 키로 로그인된 상태예요.
ANTHROPIC_API_KEY가 환경변수에 있으면 해제하고,claude auth login으로 claude.ai 계정 로그인을 다시 잡으세요. - “requires a full-scope login token” —
claude setup-token으로 만든 추론 전용 토큰을 쓰고 있어요.claude auth login으로 풀스코프 세션 토큰을 받으면 됩니다. - “disabled by your organization’s policy” —
/status로 로그인 방식부터 확인하세요. API 키 로그인이거나, Team·Enterprise 관리자 토글이 꺼져 있거나, 디바이스 관리 설정(disableRemoteControl)으로 막힌 경우예요. - “Remote credentials fetch failed” —
claude remote-control --verbose로 다시 띄워 전체 에러를 보세요. 보통 미로그인이거나, 방화벽·프록시가 443 포트 아웃바운드 HTTPS 를 막고 있는 경우가 많아요.
이미 평소에 Claude Code 를 쓰고 있다면, Remote Control 은 정말 플래그 하나 차이예요. claude remote-control 한 줄 띄우고 폰으로 QR 한 번 찍어보면, 자리에 묶여 있을 이유가 확 줄어드는 걸 느끼실 거예요. 자주 쓰는 명령어 정리는 Claude Code 자주 쓰는 명령어 모음 글에 따로 정리해뒀으니 같이 보시면 좋아요.
일단 오늘은 여기까지…..
다음 글에서는 폰에서 작업을 통째로 맡겨버리는 Dispatch 를 정리해볼게요.