클라우드 세션 (Cloud Sessions)
공식 문서: https://code.claude.com/docs/ko/claude-code-on-the-web
클라우드 세션이란?
클라우드 세션(Cloud Sessions)은 Anthropic이 관리하는 **클라우드 VM(Virtual Machine, 가상 머신)**에서 Claude Code를 실행하는 기능입니다. 로컬 컴퓨터를 켜지 않아도 코드 작업을 수행할 수 있습니다.
다른 원격 기능(원격 제어, 디스패치)은 내 컴퓨터에서 실행되지만, 클라우드 세션은 Anthropic의 클라우드에서 실행된다는 점이 핵심 차이입니다.
로컬 세션 vs 클라우드 세션 비교
💻 로컬 세션
📍 실행 위치
내 컴퓨터 (로컬 머신)
📂 파일 접근
전체 파일시스템 접근 가능
🌐 네트워크
제한 없음 (로컬 네트워크 포함)
💰 비용
API 사용량만 (VM 비용 없음)
⚠️ 조건
컴퓨터가 켜져 있어야 함
☁️ 클라우드 세션
📍 실행 위치
Anthropic 클라우드 VM
📂 파일 접근
GitHub 저장소만 (클론 후 접근)
🌐 네트워크
허용 목록 도메인만 (보안 프록시)
💰 비용
API 사용량 + 클라우드 VM 비용
✅ 조건
브라우저만 있으면 어디서든 가능
연구 프리뷰
이 기능은 현재 연구 프리뷰(Research Preview) 단계입니다.
무엇을 할 수 있나?
- 스마트폰이나 태블릿에서 코딩 작업 지시 후 모니터링
- 로컬에 클론하지 않은 리포지토리에서 작업
- 여러 작업을 병렬로 실행 (각각 별도의 VM)
- 비동기 작업: 작업을 시작하고 나중에 결과 확인
- PR 자동 수정: CI 실패나 리뷰 코멘트에 자동 대응
- Diff 리뷰: 웹에서 변경 사항을 인라인으로 확인하고 코멘트
요구사항
| 항목 | 요구사항 |
|---|---|
| 플랜 | Pro, Max, Team, 또는 Enterprise |
| 소스 관리 | GitHub 계정 (Enterprise/Team은 GitHub Enterprise Server 가능) |
| CLI 버전 | v2.1 이상 (--remote 플래그 사용 시) |
| GitLab | 현재 미지원 |
웹에서 시작하기
브라우저에서 바로 시작
- claude.ai/code 접속
- GitHub 계정 연결
- Claude GitHub App 설치 (작업할 리포지토리에)
- 기본 클라우드 환경 선택
- 작업 지시 제출
처음 사용한다면
별도 설치 없이 브라우저에서 바로 시작할 수 있습니다. claude.ai/code에 접속하여 GitHub 계정을 연결하면 됩니다.
터미널에서 시작
# 최초 설정 (대화형 세션에서)
/web-setup
# GitHub 인증 (gh CLI 사용)
# 기본 클라우드 환경 선택
# 클라우드 세션 실행
claude --remote "auth.ts의 버그를 수정해줘"
클라우드 환경
기본 설치 도구
클라우드 VM에는 주요 개발 도구가 사전 설치되어 있습니다:
| 카테고리 | 포함 도구 |
|---|---|
| 언어 | Python 3.x, Node.js (LTS), Ruby 3.x, PHP 8.4, Java, Go, Rust, C++ |
| 데이터베이스 | PostgreSQL 16, Redis 7.0 |
| 도구 | Git, Docker, 패키지 매니저들 (npm, pip, gem, cargo 등) |
설치된 도구 확인
Claude에게 check-tools를 실행해달라고 요청하면 현재 사용 가능한 도구 목록을 확인할 수 있습니다.
셋업 스크립트 (Setup Scripts)
프로젝트에 필요한 추가 도구는 **셋업 스크립트(Setup Script)**로 설치합니다. 새 세션이 시작될 때 한 번 실행됩니다:
#!/bin/bash
# Ubuntu 24.04, root로 실행
apt update && apt install -y my-package
npm install -g my-tool
pip install my-library
셋업 스크립트 vs SessionStart 훅
| 항목 | 셋업 스크립트 | SessionStart 훅 |
|---|---|---|
| 실행 환경 | 클라우드 세션만 | 모든 환경 (로컬 + 클라우드) |
| 실행 시점 | Claude Code 시작 전 | 세션 시작 시 |
| 권한 | root | 일반 사용자 |
| 용도 | 시스템 패키지 설치, 환경 구성 | 환경변수 설정, 도구 확인 |
| 설정 위치 | claude.ai 웹 UI | .claude/settings.json |
사용 구분
- 셋업 스크립트:
apt install, 시스템 레벨 설정 등 클라우드 전용 작업 - SessionStart 훅: 로컬과 클라우드 모두에서 실행해야 하는 공통 로직
환경변수
API 키나 설정값을 .env 형식으로 등록하면 모든 명령어에서 사용할 수 있습니다.
네트워크 접근
클라우드 세션의 네트워크 접근은 3단계로 설정할 수 있습니다:
| 수준 | 설명 | 사용 사례 |
|---|---|---|
| 없음 | 네트워크 완전 차단 | 보안이 중요한 작업 |
| 제한됨 (기본값) | 허용 목록의 도메인만 접근 | 일반적인 개발 |
| 전체 | 모든 아웃바운드 트래픽 허용 | 외부 API 호출 필요 시 |
기본 허용 도메인 (제한됨 모드)
기본적으로 허용되는 도메인 목록:
| 서비스 | 도메인 |
|---|---|
| npm | registry.npmjs.org |
| PyPI | pypi.org, files.pythonhosted.org |
| crates.io | crates.io, static.crates.io |
| GitHub | github.com, api.github.com |
| Go | proxy.golang.org |
| RubyGems | rubygems.org |
GitHub 프록시
클라우드 세션은 범위가 제한된(scoped) GitHub 자격 증명을 사용합니다. Claude GitHub App이 설치된 리포지토리에만 접근할 수 있습니다.
보안 프록시
모든 아웃바운드 트래픽은 보안 프록시를 통해 라우팅됩니다. 이를 통해:
- 허용되지 않은 도메인으로의 접근 차단
- 네트워크 활동 로깅
- 민감한 데이터 유출 방지
Diff 리뷰
클라우드 세션에서 Claude가 코드를 수정하면, 웹 UI에서 변경 사항을 인라인으로 확인할 수 있습니다:
- 파일별 변경 사항 확인
- 특정 줄에 코멘트 작성
- 수정 요청 후 반복 (iterate)
> 이 함수의 에러 핸들링을 개선해줘
[Claude가 코드 수정]
[Diff 리뷰에서 변경 사항 확인]
[특정 줄에 "여기서 null 체크도 추가해줘" 코멘트]
[Claude가 추가 수정]
PR 자동 수정 (Auto-fix)
Claude GitHub App을 설치하면, Claude가 PR을 감시하고 자동으로 대응합니다:
작동 방식
- CI 실패 시 자동으로 수정 시도
- 리뷰 코멘트에 자동 대응
- 수정 사항을 같은 PR에 커밋
활성화 방법
- claude.ai/code에서 리포지토리 선택
- Auto-fix 기능 활성화
- PR에서 CI가 실패하거나 리뷰 코멘트가 달리면 자동 실행
주의사항
Auto-fix는 보수적으로 동작합니다. 큰 변경이 필요한 경우 수정하지 않고 코멘트로 알려줍니다.
터미널과 웹 간 이동
로컬 터미널 → 웹 (클라우드)
# 작업을 클라우드로 보내기
claude --remote "이 작업을 클라우드에서 실행해줘"
# 여러 작업을 병렬로 실행
claude --remote "프론트엔드 테스트를 실행해줘"
claude --remote "백엔드 API 문서를 생성해줘"
웹 → 로컬 터미널 (텔레포트)
클라우드 세션을 로컬 터미널로 가져올 수 있습니다:
# 대화형 선택
claude --teleport
# 특정 세션 ID 지정
claude --teleport <세션_ID>
웹 UI에서 /teleport 명령어를 사용하거나 "Open in CLI" 버튼을 클릭할 수도 있습니다.
작업 모니터링
# 진행 중인 클라우드 작업 목록 확인
/tasks
텔레포트 조건
- Git 상태가 깨끗해야 합니다 (커밋되지 않은 변경 없음)
- 올바른 리포지토리에 있어야 합니다 (포크 아님)
- 브랜치가 푸시되어 있어야 합니다
- 동일한 Claude.ai 계정이어야 합니다
세션 관리
세션 아카이브/삭제
- 완료된 세션은 아카이브하여 정리할 수 있습니다
- 불필요한 세션은 삭제할 수 있습니다
세션 공유
| 플랜 | 공유 옵션 |
|---|---|
| Pro / Max | Private (나만) 또는 Public (링크 공유) |
| Team / Enterprise | Private (나만) 또는 Team (조직 내 공유) |
공유된 세션에서는 코드 변경 이력, 대화 내용, 결과물을 확인할 수 있습니다.
원격 제어와의 차이
| 항목 | 클라우드 세션 | 원격 제어 |
|---|---|---|
| 실행 위치 | Anthropic 클라우드 VM | 내 컴퓨터 |
| 로컬 파일 | Git 클론만 | 파일시스템 전체 접근 |
| MCP 서버 | 커넥터만 | 내 설정된 서버 사용 |
| 컴퓨터 켜야 하나 | 아니오 | 예 |
| 병렬 작업 | 각각 별도 VM | 서버 모드로 가능 |
| 적합한 상황 | 로컬 환경 없이 비동기 작업 | 진행 중인 로컬 작업 이어가기 |
실전 예제: 오픈소스 프로젝트에 기여하기
클라우드 세션을 활용하면 로컬에 환경을 구성하지 않고도 오픈소스에 기여할 수 있습니다:
# 1단계: 웹에서 시작 (claude.ai/code)
# - 기여하려는 리포지토리의 포크를 선택
# - Claude GitHub App 설치
# 2단계: 이슈 분석 요청
> 이 리포지토리의 이슈 #156을 확인하고,
> 코드베이스를 분석해서 수정 방법을 제안해줘
# 3단계: 수정 및 테스트
> 제안한 방법대로 수정하고 테스트를 실행해줘
# 4단계: PR 생성
> 수정 내용으로 원본 리포지토리에 PR을 만들어줘.
> PR 설명에 수정 이유와 테스트 결과를 포함해줘.
# 5단계: (선택) 로컬로 텔레포트
# 추가 작업이 필요하면 로컬로 가져와서 작업
claude --teleport
환경 걱정 없이 기여
Python, Node.js, Go, Rust 등 주요 언어가 모두 설치되어 있어 대부분의 오픈소스 프로젝트를 바로 빌드하고 테스트할 수 있습니다.
실전 예제: 팀 코드 리뷰 워크플로우
클라우드 세션의 공유 기능을 활용한 팀 코드 리뷰:
# 1단계: 리뷰어가 클라우드 세션 생성
# claude.ai/code에서 PR #78의 브랜치를 선택
# 2단계: Claude에게 리뷰 요청
> 이 PR의 변경사항을 종합적으로 리뷰해줘.
> 보안, 성능, 코드 품질, 테스트 커버리지를 확인해줘.
# 3단계: Diff 리뷰에서 세부 확인
# 각 파일의 변경사항을 확인하고 인라인 코멘트 작성
# 4단계: 세션 공유
# Team 공유로 설정하여 다른 팀원도 리뷰 내용 확인 가능
# 5단계: PR 작성자가 피드백 반영
> 리뷰 코멘트를 확인하고 수정해줘
제한사항
- GitHub만 지원 (GitLab은 현재 미지원)
- 기존 로컬 세션을 클라우드로 직접 이전 불가 (
--remote로 새로 생성만 가능) - 클라우드 세션은 모든 Claude 사용량과 **레이트 리밋(Rate Limit, 사용량 제한)**을 공유
- Bun은 보안 프록시와 호환되지 않아 패키지 매니저로 설치 불가
모범 사례
- 셋업 스크립트 활용: 클라우드 전용 도구는 셋업 스크립트에, 공유 로직은 SessionStart 훅(Hook)에 작성
- CLAUDE.md에 의존성 문서화: 클라우드 환경이 프로젝트를 올바르게 셋업할 수 있도록
- 로컬에서 설계, 클라우드에서 실행: 플랜 모드로 설계 후
--remote로 실행 - 병렬 작업:
--remote로 여러 작업을 동시에 실행하여 생산성 극대화 - 세션 공유: 팀원과 세션을 공유하여 작업 내용과 결과를 투명하게 공유
문제 해결
클라우드 세션이 시작되지 않는 경우
- 플랜 확인: Pro, Max, Team, Enterprise 플랜인지 확인
- GitHub 연결: Claude GitHub App이 해당 리포지토리에 설치되어 있는지 확인
- CLI 버전:
claude --version으로 v2.1 이상인지 확인
패키지 설치가 실패하는 경우
# 네트워크 수준 확인
# 제한됨 모드에서는 허용 목록의 도메인만 접근 가능
# 필요한 패키지 레지스트리가 차단되어 있다면 "전체" 모드로 변경
텔레포트가 실패하는 경우
# Git 상태 확인
git status # 커밋되지 않은 변경이 없어야 함
git push # 브랜치가 원격에 푸시되어 있어야 함
연계 기능
클라우드 세션과 함께 사용하면 좋은 기능들
🖥️ 원격 제어 (Remote Control)
클라우드 세션은 원격에서 새로 실행하는 방식이지만, 원격 제어는 내 로컬 세션을 원격으로 조작합니다. 두 기능을 상황에 따라 선택해서 사용하세요.
원격 제어 가이드 →🚀 고급 기능 (Advanced)
헤드리스 모드(
고급 기능 가이드 →-p)와 클라우드 세션을 함께 사용하면 GitHub Actions 등 CI/CD에서 클라우드 VM으로 작업을 위임할 수 있습니다.장점, 단점과 한계점
장점
- 로컬 환경 불필요: 클라우드 VM에 주요 언어와 도구가 사전 설치되어 있어, 로컬에 개발 환경을 구성하지 않고도 바로 코딩 작업을 시작할 수 있습니다.
- 어디서든 접근 가능: 브라우저만 있으면 스마트폰, 태블릿, 다른 PC 등 어디서든 claude.ai/code에 접속하여 작업할 수 있습니다.
- 사전 구성된 개발 환경: Python, Node.js, Go, Rust, PostgreSQL, Docker 등이 미리 설치되어 있어 대부분의 프로젝트를 바로 빌드하고 테스트할 수 있습니다.
- PR 자동 수정: Claude GitHub App을 통해 CI 실패나 리뷰 코멘트에 자동으로 대응하여, 반복적인 수정 작업을 줄여줍니다.
- 세션 공유 가능: Team/Enterprise 플랜에서 세션을 팀원과 공유하여 코드 변경 이력, 대화 내용, 결과물을 투명하게 공유할 수 있습니다.
단점과 한계점
- 연구 프리뷰 단계: 아직 정식 출시가 아니므로 기능 변경, 일시적 장애, 예기치 않은 동작이 발생할 수 있어 안정성이 보장되지 않습니다.
- 네트워크 필수: 인터넷 연결이 없으면 사용할 수 없으며, 네트워크 품질에 따라 응답 속도가 달라집니다.
- Git 저장소만 접근 가능: 클라우드 세션은 Claude GitHub App이 설치된 리포지토리만 클론할 수 있으며, 로컬 파일시스템에는 접근할 수 없습니다.
- 로컬 도구/MCP 사용 불가: 로컬에 설정한 MCP 서버나 커스텀 도구를 클라우드 세션에서 직접 사용할 수 없고, 커넥터만 사용 가능합니다.
- 레이트 리밋 공유: 클라우드 세션은 다른 모든 Claude 사용량과 레이트 리밋을 공유하므로, 여러 작업을 동시에 실행하면 제한에 걸릴 수 있습니다.
활용 팁
로컬에서 플랜 모드로 설계한 후 --remote로 클라우드에서 실행하면 효율적입니다. 클라우드 전용 도구는 셋업 스크립트에, 로컬과 공통으로 사용하는 로직은 SessionStart 훅에 작성하여 환경을 분리하세요.