Remote Control (원격 제어)
기준일: 2026-07-13 난이도: 중급 공식 기준: Remote Control, CLI reference, Commands
Remote Control은 로컬 머신에서 실행 중인 Claude Code 세션을 claude.ai/code 또는 Claude 모바일 앱에서 이어서 조작하는 기능입니다. 세션은 cloud로 이동하지 않습니다. 파일 시스템, MCP 서버, 도구, 프로젝트 설정은 로컬에 남고, 웹·모바일 화면은 그 로컬 세션을 보는 창 역할을 합니다.
핵심 개념
| 항목 | 공식 기준 |
|---|---|
| 실행 위치 | Claude Code는 사용자의 로컬 머신에서 계속 실행 |
| 접속 표면 | claude.ai/code, Claude iOS/Android 앱, 브라우저 |
| 요구 버전 | Claude Code v2.1.51 이상 |
| 요구 계정 | claude.ai 구독 로그인. API key만으로는 사용 불가 |
| Team/Enterprise | 기본 꺼짐. Owner가 Claude Code admin settings에서 켜야 함 |
| 엔드포인트 제한 | api.anthropic.com 사용 필요. Bedrock, Google Cloud Agent Platform, Microsoft Foundry, 임의 proxy에서는 사용 불가 |
| workspace trust | 프로젝트 디렉터리에서 한 번 claude를 실행해 trust dialog를 수락해야 함 |
선택 기준
| 상황 | 추천 |
|---|---|
| 로컬 파일과 MCP 서버를 그대로 쓰며 폰에서 이어가기 | Remote Control |
| 로컬 clone 없이 cloud에서 새 작업 시작 | Claude Code on the web |
| 터미널 세션과 브라우저를 동시에 보며 작업 | claude --remote-control |
| 터미널을 Remote Control 서버로만 두기 | claude remote-control |
| web 세션을 새로 만들기 | claude --cloud "task" |
실습
1. 서버 모드
프로젝트 디렉터리에서 실행합니다.
claude remote-control
터미널은 Remote Control 서버로 동작하며 원격 접속을 기다립니다. URL이 표시되고, 스페이스바로 QR 코드를 볼 수 있습니다.
이름을 붙여 구분할 수 있습니다.
claude remote-control --name "My Project"
2. 대화형 세션과 함께 시작
로컬 터미널에서도 대화하고, 동시에 다른 기기에서도 이어가려면 플래그를 사용합니다.
claude --remote-control "My Project"
짧은 별칭도 공식 플래그입니다.
claude --rc "My Project"
3. 이미 열린 세션에서 켜기
세션 안에서 slash command를 실행합니다.
/remote-control
/rc
VS Code 확장에서도 /remote-control 명령을 사용합니다.
연결 방법
- 터미널에 표시된 Remote Control URL을 복사하거나 QR 코드를 스캔합니다.
- 다른 기기의 브라우저에서 claude.ai/code 흐름으로 로그인합니다.
- Claude 앱에서는 같은 계정으로 로그인한 뒤 해당 local session에 연결합니다.
- 원격 표면에서 메시지를 보내면 로컬 세션이 도구 호출과 파일 작업을 수행합니다.
원격에서 이미지나 파일을 첨부하면 Claude Code가 로컬 머신으로 다운로드한 뒤 @ 파일 참조로 Claude에게 전달합니다.
연결과 보안
- 세션의 파일 접근, tool permission, MCP 설정은 로컬 Claude Code 환경을 따릅니다.
- Remote Control은 세션을 cloud로 옮기는 기능이 아닙니다.
- Team/Enterprise 조직은 admin settings에서 기능을 켜야 합니다.
- 조직이 Trusted Devices를 요구하면 브라우저나 모바일 기기별 등록과 생체 인증 또는 passkey 확인이 필요할 수 있습니다.
ANTHROPIC_BASE_URL이api.anthropic.com이 아닌 proxy나 gateway를 가리키면 Remote Control을 사용할 수 없습니다.- 분실한 기기는 claude.ai account settings의 Trusted devices에서 제거합니다.
Remote Control과 web의 차이
| 기준 | Remote Control | Claude Code on the web |
|---|---|---|
| 실행 위치 | 로컬 머신 | Anthropic-managed cloud 환경 |
| 로컬 파일 접근 | 가능 | 직접 접근 불가 |
| 로컬 MCP 서버 | 그대로 사용 | cloud 환경 기준 |
| 사용 시점 | 이미 로컬 작업 중이고 다른 기기에서 이어갈 때 | repo clone 없이 cloud에서 새 작업을 시작할 때 |
| CLI 시작 | claude remote-control, claude --remote-control |
claude --cloud "task" |
문제 해결
| 메시지 또는 증상 | 확인할 것 |
|---|---|
| 구독이 필요하다는 메시지 | claude.ai 구독 계정으로 /login했는지 확인 |
| full-scope login token 필요 | 터미널에서 claude 실행 후 claude.ai 로그인 흐름을 다시 완료 |
| 조직 eligibility 확인 실패 | Team/Enterprise Owner가 admin settings에서 기능을 켰는지 확인 |
| API endpoint 오류 | ANTHROPIC_BASE_URL proxy 설정 제거 후 api.anthropic.com 사용 |
| 조직 정책으로 비활성화 | 조직 admin policy 확인 |
| 재연결 실패 | 로컬 머신이 깨어 있고 네트워크가 연결되어 있는지 확인 |
| Trusted Devices 요구 | 해당 기기를 등록하고 필요한 생체 인증 또는 passkey 확인 수행 |
진단은 공식 CLI 표면으로 시작합니다.
claude doctor
claude --safe-mode
세션 안에서는 다음을 확인합니다.
/doctor
/login
/remote-control
도구에 입력할 프롬프트
이 프로젝트에서 Remote Control을 켤 수 있는지 공식 요구 사항 기준으로 점검해줘.
Claude Code 버전, claude.ai 로그인, workspace trust, ANTHROPIC_BASE_URL,
조직 admin settings, Trusted Devices 요구 여부를 확인 항목으로 나눠줘.
deprecated alias나 문서에 없는 원격 명령은 제안하지 마.
체크리스트
-
claude --version이 Remote Control 요구 버전 이상이다. - API key가 아니라 claude.ai 계정으로 로그인했다.
- 프로젝트 디렉터리에서 workspace trust를 수락했다.
- Team/Enterprise에서는 Owner가 Remote Control을 켰다.
-
ANTHROPIC_BASE_URL이 proxy나 gateway를 가리키지 않는다. - 서버 모드와 대화형 모드 중 목적에 맞는 시작 방식을 골랐다.
- 조직이 Trusted Devices를 요구하면 연결 기기를 등록했다.