Claude Code 웹 · 모바일 · Remote Control — 클라우드에 맡길지, 내 PC를 원격으로 쓸지 고르기

KAITABASE가 공식 문서와 원문을 직접 읽고 새로 쓴 가이드입니다.

이 가이드로 할 수 있는 것

공식 문서는 "책상을 떠나서도 Claude Code를 쓰는 방법"을 두 가지로 나눕니다. 겉보기에는 둘 다 claude.ai/code 화면이나 Claude 앱에서 보이지만, 세션이 어디에서 실행되는지가 다릅니다.

공식 문서는 진행 중인 로컬 작업을 다른 기기에서 이어 갈 때는 Remote Control을, 로컬 준비 없이 작업을 시작하거나 내 PC에 없는 저장소를 다루거나 여러 작업을 동시에 돌릴 때는 클라우드 세션을 쓰라고 정리합니다. 이 가이드는 그 판단부터 실제 시작 · 정리까지를 순서대로 다룹니다.

빠른 시작

내 PC에서 하던 작업을 휴대폰으로 이어 갈 때(공식 문서 기준, 직접 실행 안 함):

claude --remote-control "My Project"

터미널의 대화를 그대로 쓰면서 claude.ai/code나 Claude 앱에서도 같은 세션을 조작할 수 있습니다. 이미 열려 있는 세션이라면 /remote-control 만 입력하면 지금까지의 대화를 그대로 넘깁니다.

작업을 클라우드에 맡기고 자리를 뜰 때(공식 문서 기준, 직접 실행 안 함):

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

이 명령은 claude.ai에 새 클라우드 세션을 만들고, 현재 폴더의 GitHub 원격 저장소를 현재 브랜치로 clone합니다.

STEP 1. 쓸 수 있는 계정인지 확인하기

목표: 시작하기 전에 요금제 · 로그인 방식 · 조직 설정을 확인합니다. · 예상 시간: 3분

Remote Control은 ANTHROPIC_BASE_URL 을 api.anthropic.com 이 아닌 곳(LLM 게이트웨이 · 프록시)으로 돌려 둔 경우에도 쓸 수 없고, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 이나 DISABLE_GROWTHBOOK 을 설정해도 쓸 수 없습니다.

확인 세션 안에서 /status 를 실행해 어떤 계정 · 조직으로 로그인돼 있는지 봅니다. 공식 문서는 Pro · Max로 바꿨는데도 예전 Team 조직 정책에 막히면 claude auth logout 후 claude auth login 으로 다시 로그인하라고 안내합니다.

주의 Zero Data Retention이 켜진 조직, HIPAA 구성을 적용한 조직은 클라우드 세션과 Remote Control을 모두 쓸 수 없습니다. 고객 관리 암호화 키(CMEK)를 쓰는 조직은 클라우드 세션을 시작할 수 없습니다.

STEP 2. Remote Control로 내 PC 세션 이어 쓰기

목표: 터미널에서 하던 작업을 휴대폰 · 브라우저에서 계속합니다. · 예상 시간: 5분

CLI에는 세 가지 시작 방법이 있습니다(공식 문서 기준, 직접 실행 안 함).

처음 실행하면 한 번만 확인을 묻습니다. 서버 모드는 Enable Remote Control? (y/n), 세션 안에서는 Enable Remote Control 버튼입니다. 신뢰하지 않은 폴더라면 Trust <directory>? [y/N] 도 묻습니다.

다른 기기에서 연결하는 방법은 세 가지입니다.

1. 터미널에 나온 세션 URL을 브라우저로 엽니다.
2. QR 코드를 휴대폰으로 찍어 Claude 앱에서 엽니다.
3. claude.ai/code나 Claude 앱의 Code 탭 세션 목록에서 이름으로 찾습니다. 연결 중인 세션은 컴퓨터 아이콘에 초록 점이 붙습니다.

휴대폰에 앱이 없다면 Claude Code에서 /mobile 을 입력해 앱 설치용 QR 코드를 띄웁니다.

확인 대화형 세션에서는 연결되는 동안 터미널에 /rc active 표시가 보입니다. 직접 확인한 claude remote-control --help 에도 "You must be logged in with a Claude account that has a subscription" 이 필수 조건으로 적혀 있었습니다.

막히면 Remote Control requires a claude.ai subscription 이 뜨면서 ANTHROPIC_API_KEY is set 같은 문구가 붙으면, API 키가 로그인보다 우선 적용된 것입니다. 그 환경 변수를 지우고 claude auth login 에서 claude.ai를 고릅니다. claude setup-token 으로 만든 장기 토큰은 모델 요청만 할 수 있어 Remote Control을 열 수 없습니다.

STEP 3. 서버 모드 옵션과 다시 붙기

목표: 여러 세션을 한 프로세스로 받고, 끊긴 세션에 다시 붙습니다. · 예상 시간: 4분

직접 확인한 claude remote-control --help 의 주요 옵션입니다.

123456--name <name>             Name for the session (shown in claude.ai/code)
-c, --continue            Reattach to the session ... last recorded for this directory
--session-id <id>         Reattach to a specific session by ID
--permission-mode <mode>  Permission mode for spawned sessions
--spawn <mode>            Spawn mode: same-dir, worktree, session (default: same-dir)
--capacity <N>            Max concurrent sessions in worktree or same-dir mode (default: 32)

--spawn same-dir 은 모든 세션이 같은 폴더를 써서 같은 파일을 고치면 부딪힐 수 있습니다. 세션마다 따로 떨어진 폴더가 필요하면 --spawn worktree 를 씁니다(Git 저장소 필요). 실행 중에 w 를 누르면 두 모드를 오갈 수 있고, 바꾼 모드는 그 프로젝트의 기본값으로 저장됩니다.

Ctrl+C 로 서버를 멈추면 원격 화면에서는 응답이 끊깁니다. 공식 문서에 따르면 멈춘 뒤 약 4시간 안에는 같은 폴더에서 claude remote-control(전체), claude remote-control --continue(처음 세션만), claude remote-control --session-id <id>(특정 세션)로 다시 살릴 수 있습니다.

막히면 네트워크가 끊기면 서버 모드는 약 10분 뒤 포기하고 종료합니다. 대화형 세션은 끊긴 동안 계속 재시도하다 네트워크가 돌아오면 다시 붙습니다. SSH로 원격 서버에서 돌린다면 tmux 나 screen 안에서 시작해야 SSH가 끊겨도 세션이 살아 있습니다.

STEP 4. 클라우드 세션 시작하기

목표: 내 PC가 꺼져 있어도 도는 작업을 맡깁니다. · 예상 시간: 5분

클라우드 세션이 GitHub에서 코드를 가져오려면 GitHub를 연결해야 합니다. 방법은 두 가지입니다.

터미널에서 시작할 때 꼭 알아 둘 점은, 클라우드 VM이 내 로컬 폴더가 아니라 GitHub 원격의 현재 브랜치를 clone한다는 것입니다. 로컬에만 있는 커밋은 먼저 push합니다. push하지 않은 브랜치라면 Branch <name> is not on GitHub 가 뜨고 다른 시작점에서 시작합니다.

공식 문서가 권하는 흐름은 "계획은 로컬에서, 실행은 클라우드에서" 입니다.

claude --permission-mode plan
## 계획을 docs/migration-plan.md 로 저장 · 커밋 · push 한 뒤
claude --cloud "Execute the migration plan in docs/migration-plan.md"

--cloud 를 여러 번 실행하면 세션이 각각 따로 동시에 돕니다. 돌고 있는 세션에 메시지를 더 보내려면 claude -p "your message" --cloud <session-id> 를 씁니다.

확인 공식 문서에 따르면 보내기에 성공하면 Sent to cloud session. 과 세션 ID, 보기 링크가 출력됩니다.

주의 원격 저장소가 없거나 Claude GitHub App이 설치되지 않은 저장소에서 --cloud 를 실행하면 로컬 저장소를 묶어 직접 올립니다. macOS · Linux · WSL에서는 .env, *.pem 같은 자격 증명 이름의 파일 변경을 빼고 올리지만, Windows 기본 환경에서는 추적 중인 파일의 커밋하지 않은 변경을 이름과 관계없이 그대로 올립니다. 올리고 싶지 않은 수정은 먼저 stash하거나 되돌립니다.

STEP 5. 클라우드 세션을 내 터미널로 가져오기

목표: 클라우드에서 하던 작업을 로컬에서 이어 갑니다. · 예상 시간: 3분

claude --teleport
claude --teleport <session-id>

세션 안에서는 /teleport(또는 /tp)로 같은 선택 화면을 엽니다. teleport는 같은 저장소인지 확인하고, 클라우드 세션의 브랜치를 가져와 체크아웃하고, 대화 기록 전체를 불러옵니다.

확인 teleport한 뒤 터미널에서 한 작업은 로컬에만 남고 claude.ai나 앱의 클라우드 세션에는 나타나지 않습니다. 휴대폰에서 계속 조작하려면 로컬 세션에서 /remote-control 을 켭니다.

막히면 --resume 은 이 컴퓨터의 기록만 보여 주고 클라우드 세션은 보여 주지 않습니다. 클라우드 세션을 가져오려면 --teleport 를 씁니다. API 키로 로그인돼 있으면 Unable to get organization UUID 가 뜨므로 claude auth login 으로 claude.ai에 로그인합니다.

STEP 6. 클라우드 환경 설정하기

목표: 클라우드 세션이 닿을 수 있는 네트워크와 설치 도구를 정합니다. · 예상 시간: 5분

모든 클라우드 세션은 클라우드 환경 하나에서 돕니다. 처음에는 Default 환경이 만들어지며, 네트워크는 Trusted(패키지 저장소 · GitHub · 클라우드 SDK 같은 허용 목록만), 환경 변수 · 설정 스크립트는 없습니다. claude.ai/code의 새 세션 화면에서 메시지 상자 아래 첫 번째 컨트롤로 환경을 추가 · 수정합니다.

기본으로 설치된 VM은 Ubuntu 24.04 · x86_64이며, Python · Node.js 20 · 21 · 22 · Java 21 · Go · Rust · Docker · PostgreSQL 16 · Redis 7.0 · gh 등이 들어 있습니다. 대략의 자원 한도는 vCPU 4개 · RAM 16GB · 디스크 30GB입니다. 없는 도구는 설정 스크립트로 설치합니다.

#!/bin/bash
apt update && apt install -y shellcheck

설정 스크립트는 root로 실행되며, 0이 아닌 값으로 끝나면 세션이 시작되지 않습니다. 약 5분 안에 끝나야 결과가 캐시되어 다음 세션부터 빨리 시작합니다.

주의 환경 변수와 설정 스크립트는 그 환경을 쓰는 누구나 읽을 수 있습니다. API 키는 환경 변수가 아니라 network secret 으로 넣으면 키가 VM 안에 들어가지 않고 프록시가 요청에 붙여 줍니다.

되돌리기 필요 없어진 환경은 편집 화면에서 Archive environment 로 보관합니다. 공식 문서는 Anthropic 호스팅 환경은 삭제 메뉴가 없고 보관만 된다고 설명합니다.

잘못 쓰는 예 · 바르게 쓰는 예

바로 쓰는 프롬프트 · 템플릿

클라우드 세션에 맡길 때는 묻지 못하고 혼자 끝까지 갈 수 있게 완료 조건을 분명히 씁니다.

1234docs/migration-plan.md 의 1~3단계만 실행해 주세요.
- 각 단계 뒤에 pytest 를 실행하고, 실패하면 그 단계에서 멈추고 원인을 적어 주세요.
- 4단계 이후와 마이그레이션 파일 외 폴더는 고치지 마세요.
- 끝나면 바뀐 파일 목록, 테스트 결과, 남은 질문을 정리하고 PR 초안을 만들어 주세요.

Remote Control로 휴대폰에서 확인할 때 쓰는 짧은 지시입니다. 공식 문서는 프롬프트에 알림을 요청할 수 있다고 설명합니다.

테스트가 끝나면 알려 주세요(notify me when the tests finish). 실패가 있으면 실패한 테스트 이름만 먼저 보여 주세요.

주의할 점

• 요금: 클라우드 세션은 요금제 사용 한도에 다른 Claude · Claude Code 사용량과 함께 계산되고, 클라우드 VM 자체는 따로 청구하지 않는다고 공식 문서는 밝힙니다. 여러 작업을 동시에 돌리면 한도도 그만큼 빨리 씁니다. 요금제는 claude.com/pricing에서 확인합니다.
• 데이터: Remote Control이 연결된 동안 대화 기록(메시지 · 응답 · 도구 활동)은 Anthropic 서버에 저장됩니다. 실행과 파일 접근은 내 PC에 남습니다. 내 PC는 바깥으로 HTTPS 요청만 보내고 들어오는 포트를 열지 않습니다.
• 공유: Pro · Max 계정에서 세션을 Public 으로 공유하면 claude.ai에 로그인한 누구나 볼 수 있고, 비공개 저장소의 코드 · 자격 증명이 들어 있을 수 있습니다. 공유 전에 내용을 확인합니다.
• 자동 수정(Auto-fix): PR 자동 수정은 내 GitHub 계정 이름으로 리뷰 댓글에 답할 수 있습니다. 댓글로 배포가 돌아가는 저장소(Atlantis · Terraform Cloud 등)에서는 켜기 전에 자동화를 점검하라고 공식 문서는 경고합니다.
• 조직 관리: 조직 전체에서 끄려면 disableRemoteControl 설정을 씁니다. Trusted Devices(베타)를 켜면 원격 조작 기기를 등록하고 18시간 안에 다시 인증해야 합니다.
• 라이선스: 이 가이드는 Anthropic 공식 문서를 우리 말로 다시 정리한 것입니다.

공식 자료

• Remote Control — https://code.claude.com/docs/en/remote-control
• Use Claude Code in the cloud — https://code.claude.com/docs/en/claude-code-on-the-web
• Configure cloud environments — https://code.claude.com/docs/en/cloud-environments
• Get started with cloud sessions — https://code.claude.com/docs/en/web-quickstart
• Data usage — https://code.claude.com/docs/en/data-usage
• 요금제 — https://claude.com/pricing

더 보기

이 가이드는 KAITABASE가 공식 문서와 원문을 직접 읽고 실행해 본 뒤 새로 쓴 자료입니다. 같은 주제의 다른 글은 KAITABASE에서 이어서 볼 수 있습니다.

• 업무 자동화 자료 모음 — https://kaitabase.vercel.app/?area=automate
• KAITABASE 전체 자료 — https://kaitabase.vercel.app