클로드 클라우드 세션 설정 방법
안녕하세요 novice-22입니다.
이번 글은 Claude Code 클라우드 세션의 개념과 크레딧 차감 구조, GitHub 연결, 그리고 세션이 비공개 저장소 하나에서만 작업하도록 범위를 제한하는 방법을 정리한 글입니다.
1. 클라우드 세션
1-1 개념
내 PC 대신 Anthropic 클라우드의 가상 머신(VM)에서 Claude Code가 작업하는 방식이다. VM이 내 코드를 가져오고 결과를 돌려주는 통로가 GitHub다.
1. 작업 지시
2. VM이 GitHub에서 저장소를 clone
3. Claude가 코드 수정, 테스트 실행
4. 결과를 브랜치로 push (또는 PR 생성)
5. GitHub에서 확인하고 머지1-2 로컬 세션과 비교
| 항목 | 로컬 세션 | 클라우드 세션 |
|---|---|---|
| 실행 위치 | 내 PC | Anthropic 클라우드 VM |
| 코드 위치 | 내 PC 폴더 | GitHub 저장소 |
| GitHub | 불필요 | 필요 (claude --cloud는 로컬 저장소를 올려서 시작 가능) |
| 로컬 설정 | 사용 | 사용 안 함 (저장소만) |
| PC를 끄면 | 중단 | 계속 진행 |
| 권한 모드 | 전체 | Accept edits, Plan, Auto |
| 네트워크 | 내 PC 네트워크 | 환경별 설정 (기본: 허용 목록만) |
병렬 작업, 로컬에 없는 저장소, 오래 걸리고 자주 개입하지 않는 작업에 잘 맞는다. 회사·고객 자료처럼 외부에 올리면 안 되는 코드나 로컬 도구가 필요한 작업은 로컬 세션에서 한다.
2. 비용과 크레딧
Pro, Max, Team 플랜에 포함된 기능이다. VM 사용료는 따로 없고 채팅, 로컬 Claude Code와 같은 플랜 사용량에서 차감된다.
클라우드 세션 크레딧은 2026년 9월 정식 출시 때 기존 구독자에게 준 1회성 크레딧이다(Pro $100, Max $250). 클라우드 세션에 먼저 차감되고, 다 쓰거나 만료되면 플랜 사용량이 차감된다. 신청은 10월 7일에 마감됐고 잔액은 11월 초에 만료된다. 잔액은 claude.ai 사용량 화면의 카드로 보이고, CLI의 /usage에는 나오지 않는다. Console API 크레딧과는 별개다.
| 선택 | 차감되는 곳 |
|---|---|
| 이 컴퓨터 (로컬) | 플랜 사용량 |
| 클라우드 | 클라우드 세션 크레딧 → 소진 후 플랜 사용량 |
3. GitHub 연결과 범위 제한
3-1 저장소 만들기
github.com/new에서 Private, Add README: On으로 만든다. 무료 계정도 비공개 저장소를 무제한으로 만들 수 있다. 세션 안에서는 저장소를 만들 수 없으니(5-1) 브라우저에서 직접 만든다. API 키나 비밀번호는 .env에 두고 .gitignore로 제외한다.
이 글에서는 예시로 sec-research라는 저장소를 쓴다.
3-2 Claude GitHub App 설치
claude.ai/code에서 GitHub 계정만 연결해도 공개 저장소는 바로 쓸 수 있다. 비공개 저장소에서 작업하려면 Claude GitHub App이 따로 설치돼 있어야 한다. claude.ai → 설정 → 커넥터 → GitHub 통합에서 계정 옆 수정을 누르면 설치 화면으로 넘어간다.
기본값 All repositories 대신 Only select repositories를 고르고 3-1의 저장소만 선택한다. 저장소를 먼저 만들어야 선택 목록에 나온다. 이 범위는 비공개 저장소에만 적용된다(5-2).
터미널의 /web-setup으로 연결하면 gh 토큰이 그대로 클라우드 세션에 쓰인다. 이 경우 세션은 토큰이 접근할 수 있는 모든 저장소에 접근하고 App 설치도 필요 없어서, 위의 범위 제한이 의미가 없어진다. 범위를 좁혀 쓰려면 브라우저로 연결한다.
3-3 확인
설치가 끝나면 GitHub 통합 화면에서 계정이 설치됨으로 바뀐다. 세션에서 비공개 저장소에 쓰기 권한이 있는지 확인한다.
gh api repos/novice-22/sec-research --jq '{private, push: .permissions.push}'{"private":true,"push":true}출처
4. 환경과 세션 시작
4-1 환경
Pro, Max 플랜은 온보딩 때 Default 환경이 자동으로 만들어진다. 처음엔 그대로 쓰면 된다. 환경은 VM 설정이고 GitHub 연결은 계정 단위라 서로 별개다.
| 항목 | Default 값 | 설명 |
|---|---|---|
| 네트워크 | Trusted | 패키지 저장소, GitHub, 클라우드 SDK 등 허용 목록만 접속 |
| 설정 스크립트 | 없음 | 세션 시작 시 자동 실행할 설치 명령 |
| 환경 변수 | 없음 | 환경을 쓰는 누구나 읽을 수 있어서 API 키는 넣지 않는다 |
| 네트워크 시크릿 | 없음 | API 키는 여기에 넣는다. 세션은 키를 보지 못하고 프록시가 요청에 붙인다 |
Trusted가 실제로 어디까지 되는지 확인해봤다.
curl -sS -o /dev/null -w "%{http_code}\n" https://pypi.org/simple/
curl -sS -o /dev/null https://example.com200
curl: (56) CONNECT tunnel failed, response 403pip, apt 같은 패키지 설치는 되고 그 외 일반 사이트는 막힌다. 다른 도메인이 필요하면 환경의 네트워크 액세스를 Custom으로 바꿔 추가한다.
4-2 세션 시작
| 위치 | 방법 |
|---|---|
| 웹 | claude.ai/code |
| 데스크톱 앱 | 입력창 왼쪽 아래 이 컴퓨터 →클라우드 |
| 모바일 앱 | Code 탭 |
| 터미널 | claude --cloud |
| VS Code | 확장에서는 불가. 내장 터미널에서claude --cloud |
환경(Default)과 저장소를 고르고, 권한 모드는 처음엔 Plan으로 시작하는 게 안전하다. 탭을 닫아도 세션은 계속 돈다.
작업이 끝나면 +42 -18 같은 diff 표시를 눌러 변경을 확인하고, 줄 단위로 코멘트를 남기거나 Create PR로 PR을 만든다. PR을 만든 뒤에도 같은 세션에서 계속 수정할 수 있다.
4-3 세션 수명
새 세션은 대화도 VM도 새것이다. 세션을 오래 비워두면 VM이 회수되고, 다시 열면 새 VM에서 이어진다. 대화는 복원되지만 push하지 않은 변경과 직접 설치한 패키지는 남지 않는다.
그래서 의미 있는 단위마다 push한다. 매번 까는 패키지는 환경의 설정 스크립트에, 작업 규칙은 저장소의 CLAUDE.md에 적어두면 새 세션이 자동으로 쓴다.
출처
5. 겪은 문제와 해결
5-1 세션 안에서 저장소를 만들 수 없다
gh repo create sec-research --private
gh api -X POST /user/repos -f name=sec-research -F private=trueHTTP 403: GitHub GraphQL is not available from Claude Code sessions
This GitHub API path is not available: sessions are bound to their configured repositories.세션 자격증명은 연결된 저장소 단위로만 쓸 수 있고, 계정 단위 API인 저장소 생성은 막혀 있다. 3-1처럼 브라우저에서 만들어서 해결했다.
5-2 범위를 좁혀도 공개 저장소는 막히지 않는다
범위 밖 저장소를 세션에서 조회하자 403이 나와서 격리된 줄 알았다.
gh api repos/novice-22/ctf-botgh: GitHub access to this repository is not enabled for this session. (HTTP 403)그런데 git으로는 읽혔다.
git ls-remote https://github.com/novice-22/ctf-bot HEADe7437b35b47ea88f515ecb6e29aa0983a2efe543 HEAD403은 App 범위 때문이 아니라 그 저장소를 이 세션에 붙이지 않아서였다. 오류 메시지도 "this session"이라고 말한다. 공식 문서 기준으로 GitHub App으로 연결한 세션은 모든 공개 저장소와 App이 설치된 비공개 저장소에 접근할 수 있다. Only select repositories가 막는 건 범위 밖 비공개 저장소뿐이다.
세션이 실제로 다루는 저장소는 세션을 시작할 때 고른 저장소다. 공개 저장소까지 막고 싶으면 Private으로 바꾼다.
6. 마무리
| 용도 | 어디서 |
|---|---|
| 개인 프로젝트 (비공개 저장소) | 클라우드 세션 |
| 회사·고객 자료, 로컬 도구가 필요한 작업 | 로컬 세션 |
| 이동 중 확인·지시 | 모바일 앱 |
핵심은 저장소를 Private으로 만들고, GitHub App을 Only select repositories로 설치하고, /web-setup 대신 브라우저로 연결하는 것이다. 이 범위는 비공개 저장소에만 적용되니 숨길 저장소는 Private으로 둔다. 컨테이너는 임시라 push하지 않은 작업은 사라지니 자주 push한다. 클라우드 세션 크레딧이 있다면 만료일도 확인해둔다.