Claude Code Teleport 완전 정리: 웹 세션을 로컬로 가져오는 법

출근길 지하철에서 스마트폰으로 Claude Code 웹 세션 하나 던져놓고, 회사 도착해서 노트북 열자마자 그 작업을 이어서 하고 싶었던 적 있으신가요? 저도 처음엔 "그냥 새로 시작하면 되지"라고 생각했는데, 막상 컨텍스트를 다시 설명하려니 시간이 꽤 걸리더라고요. Claude Code의 Teleport 기능이 정확히 이 문제를 풉니다. claude.ai/code에서 돌아가던 클라우드 세션을 대화 기록과 작업 브랜치까지 통째로 로컬 터미널로 끌고 올 수 있거든요. 이번 글에서는 --teleport와 /teleport 사용법, 텔레포트 전에 반드시 확인해야 할 요구조건, 그리고 헷갈리기 쉬운 --resume·--remote·Remote Control과의 차이를 정리해봤습니다.

claude.ai/code 웹 화면에서 "Open in CLI" 버튼을 클릭하는 장면

 

Teleport란 무엇인가: 세션 모빌리티 기능

Teleport는 Claude Code에서 웹과 로컬 터미널 사이에 작업을 이동시키는 "세션 모빌리티" 기능입니다. 공식 문서는 이걸 "Move tasks between web and terminal" 섹션에서 설명하는데, 방향이 두 개예요. --remote는 터미널에서 웹으로, --teleport는 반대로 웹에서 터미널로 보내는 명령입니다. 클라우드 세션은 Anthropic이 관리하는 인프라에서 돌아가기 때문에 브라우저를 닫아도 세션이 살아있고, 심지어 Claude 모바일 앱에서 진행 상황을 확인할 수도 있어요.

다만 아직은 모든 사용자에게 열려 있는 건 아닙니다. 현재는 Pro, Max, Team 사용자, 그리고 프리미엄 시트를 가진 Enterprise 사용자에게 리서치 프리뷰 형태로 제공되고 있어요.

 

--teleport / /teleport 사용법: 웹 세션을 로컬로 가져오기

공식 문서에 나온 방법은 크게 네 가지입니다.

• claude --teleport: 터미널에서 이 명령을 실행하면 대화형 세션 선택기가 뜹니다. 목록에서 원하는 클라우드 세션을 고르면 됩니다.
• claude --teleport <session-id>: 세션 ID를 알고 있으면 선택기를 거치지 않고 바로 재개할 수 있어요.
• /teleport (단축형 /tp): 이미 CLI 세션 안에 있다면 Claude Code를 재시작할 필요 없이 이 명령으로 같은 선택기를 열 수 있습니다.
• /tasks에서 t 키: 백그라운드 세션 목록을 /tasks로 확인한 뒤 t를 누르면 해당 세션으로 텔레포트됩니다.

웹 인터페이스 쪽에서 시작하는 방법도 있어요. 세션 화면에서 "Open in CLI"를 누르면 터미널에 붙여넣을 명령이 클립보드에 복사됩니다.

텔레포트가 실행되면 Claude가 자동으로 (1) 올바른 저장소에 있는지 확인하고, (2) 클라우드 세션에서 만든 브랜치를 fetch·checkout하고, (3) 전체 대화 기록을 터미널로 불러옵니다. 커밋되지 않은 변경사항이 있으면 먼저 stash 하라는 안내가 뜨니 참고하세요.

--teleport 실행 시 나타나는 대화형 세션 선택기 터미널 화면

 

텔레포트 전에 반드시 확인해야 할 4가지 요구조건

여기서 막히는 경우가 은근히 많습니다. 텔레포트는 세션을 재개하기 전에 아래 네 가지를 검사하는데, 하나라도 안 맞으면 오류가 나거나 해결 방법을 안내받습니다.

요구조건	내용
클린 git 상태	작업 디렉터리에 커밋되지 않은 변경사항이 없어야 합니다. 있으면 stash 하라고 안내됩니다.
올바른 저장소	포크가 아닌, 동일한 저장소의 체크아웃에서 실행해야 합니다.
브랜치 존재	클라우드 세션에서 만든 브랜치가 원격에 push되어 있어야 합니다.
동일 계정	클라우드 세션과 같은 claude.ai 계정으로 인증돼 있어야 합니다.

이 중에서 특히 헷갈리는 게 인증 방식이에요. Teleport는 claude.ai 구독 인증이 필요합니다. API 키나 Bedrock, Vertex AI, Microsoft Foundry로 로그인한 상태라면 --teleport 자체가 안 뜹니다. /login으로 claude.ai 계정으로 다시 로그인해야 해요. claude.ai로 이미 로그인했는데도 안 된다면, 조직(organization)에서 클라우드 세션 기능을 아직 활성화하지 않았을 가능성이 큽니다.

 

Teleport는 일방향이다: --remote와의 관계

여기서 오해하기 쉬운 부분이 하나 있는데요, 텔레포트는 웹에서 로컬로 가져오는 것만 됩니다. 반대로 로컬에서 작업하던 세션을 그대로 웹으로 밀어 올리는 기능은 없어요.

로컬 작업을 클라우드로 보내고 싶다면 --remote 플래그를 씁니다. 예를 들어 claude --remote "Fix the authentication bug in src/auth/login.ts"처럼 실행하면, 현재 디렉터리의 GitHub 원격 저장소를 현재 브랜치 기준으로 클론해서 새 클라우드 세션을 만듭니다. 여기서 중요한 건 "새로 만든다"는 점이에요. 기존 로컬 대화를 그대로 옮기는 게 아니라, VM이 로컬 머신이 아니라 GitHub에서 클론하는 방식이라 push하지 않은 로컬 변경사항이 있으면 먼저 push해야 합니다. --remote는 한 번에 하나의 저장소에서만 동작하고요.

v2.1.195부터는 컨테이너가 준비되는 동안 저장소 클론, 셋업 스크립트 실행 같은 과정을 실시간 체크리스트로 보여주는데, 이 대기 시간에 입력한 메시지는 큐에 쌓였다가 세션이 준비되면 자동으로 전송됩니다.

정리하면, --remote(로컬→웹, 새 세션 생성)와 --teleport(웹→로컬, 기존 세션 그대로 가져오기)는 짝을 이루는 반대 방향 명령이지만 동작 방식은 완전히 대칭은 아닙니다. 참고로 Desktop 앱에는 로컬 세션을 웹으로 보내는 "Continue in" 메뉴가 별도로 존재한다고 하니, 데스크톱 사용자라면 이 경로도 확인해보시면 좋을 것 같아요.

--teleport와 --remote 방향을 화살표로 표시한 다이어그램

 

--teleport vs --resume: 헷갈리지 말아야 할 차이

이름이 비슷해서 처음엔 저도 둘을 혼동했는데, 역할이 완전히 다릅니다. --resume은 "이 머신"에 저장된 로컬 대화 기록만 재개하는 명령이에요. 클라우드 세션 목록은 아예 보여주지 않습니다. 반면 --teleport는 클라우드에서 실행 중이던 세션과 그 세션이 만든 브랜치를 통째로 끌어옵니다.

즉 지금 쓰던 노트북에서 어제 하던 로컬 작업을 이어가고 싶으면 --resume, 다른 기기(또는 웹)에서 돌리던 클라우드 세션을 이 컴퓨터로 가져오고 싶으면 --teleport를 쓰면 됩니다.

 

Remote Control과는 다른 개념

Teleport와 자주 헷갈리는 또 다른 기능이 Remote Control입니다. 이름도 비슷하고 둘 다 "다른 기기에서 이어간다"는 느낌이라 헷갈리기 쉬운데, 실행 위치가 정반대예요.

Teleport로 가져오는 세션은 Anthropic이 관리하는 클라우드 VM에서 실행됩니다. 반면 Remote Control은 로컬 머신에서 계속 돌아가는 Claude Code 세션을 웹이나 모바일 앱에서 원격으로 조작하는 기능입니다. 코드 자체는 클라우드로 이동하지 않고, 로컬 파일시스템과 MCP 서버, 로컬 툴이 그대로 사용돼요. claude remote-control(서버 모드), claude --remote-control(단축 --rc), 세션 도중 /remote-control(단축 /rc)로 시작할 수 있고, v2.1.51 이상이 필요합니다. API 키 인증으로는 쓸 수 없고 Pro/Max/Team/Enterprise 구독이 있어야 하며, Team/Enterprise라면 관리자가 별도로 토글을 켜야 합니다.

공식 문서는 두 기능의 용도를 이렇게 구분합니다. Claude Code on the web(및 --remote, --teleport)은 "로컬 설정 없이 작업을 시작하거나 여러 작업을 병렬로 돌릴 때", Remote Control은 "로컬 작업 도중 다른 기기에서 이어가고 싶을 때" 적합하다고요. 실제로 Claude Code 개발을 이끄는 Anthropic의 Boris Cherny는 v2.1.0 출시를 알리며 두 기능을 나란히 소개했는데, 본인은 /config에서 "Enable Remote Control for all sessions"를 켜두고 쓴다고 언급하기도 했습니다.

트러블슈팅 관점에서 하나 더 알아두면 좋은 게, --teleport는 사실 Remote Control과 같은 연결 인프라를 씁니다. 그래서 인증 오류가 날 때 "Remote Control session expired" 같은 문구로 뜨는 경우가 있어요. 이땐 로컬에서 /login으로 자격 증명을 새로고침하고, 클라우드 세션을 만든 계정과 같은 계정으로 로그인했는지 확인하면 됩니다. 클라우드 세션은 일정 시간 활동이 없으면 환경이 회수되는데, 이 경우 "Could not resume session ... its environment has expired"라는 메시지가 뜨고 claude.ai/code에서 다시 열면 대화 기록이 복원된 새 환경이 준비됩니다.

 

실전 팁: 백그라운드 세션과 함께 쓰기

매번 브라우저 열어서 세션 시작하는 게 번거롭다면? CLI나 VS Code에서 프롬프트 앞에 &를 붙이면 백그라운드 클라우드 세션이 바로 시작됩니다. 예를 들어 & Refactor the authentication module to use JWT tokens처럼요. 이렇게 시작한 세션은 나중에 claude --teleport <session-id>로 로컬로 가져올 수 있어요. 여러 작업을 병렬로 돌리거나, 세션 ID를 공유해서 비동기로 페어 프로그래밍하는 식으로 활용할 수 있습니다. 나중에 기기를 바꿀 가능성이 조금이라도 있다면 처음부터 &로 작업을 띄우고 git 상태를 깨끗하게 유지하는 습관을 들이는 게 좋습니다. 텔레포트 요구조건 1번(클린 git 상태)에서 걸리는 걸 미리 막아주거든요.

다만 /teleport 명령 자체는 아직 신생 기능이라 배포 초기 버전 간 편차가 있었습니다. GitHub 이슈 트래커에는 v2.1.1의 Claude Max 계정, macOS 환경에서 /teleport가 자동완성 목록에 안 뜨고 /remote-env만 표시됐다는 버그 보고가 있었어요. 최신 버전에서는 해결됐을 가능성이 높지만, 명령이 안 보인다면 버전부터 확인해보시길 권합니다.

 

마치며

Teleport는 "어디서 시작했든 계속 이어간다"는 방향으로 Claude Code가 진화하고 있다는 걸 보여주는 기능이라고 생각해요. 아직 리서치 프리뷰 단계라 세부 동작이 조금씩 바뀔 수 있으니, 자주 쓰는 워크플로라면 claude --version으로 버전을 챙겨두고 공식 릴리스 노트를 가끔 확인해보시는 걸 추천합니다.