웹에서 Claude Code 시작하기
웹 세션은 사용자의 머신이 아니라 Anthropic 관리 클라우드 VM에서 실행됩니다. claude.ai/code 또는 Claude 모바일 앱에서 작업을 제출하면 Claude가 저장소를 복제하고, 변경 사항을 만들고, 검토할 브랜치를 GitHub로 푸시합니다.
웹 세션은 다음 작업에 특히 잘 맞습니다.
- 병렬 작업: 서로 독립적인 작업을 여러 세션과 브랜치에서 동시에 실행합니다.
- 로컬에 없는 저장소 작업: 저장소를 직접 체크아웃하지 않아도 Claude가 클라우드 VM에 복제합니다.
- 중간 개입이 적은 작업: 명확한 작업을 맡기고, 완료 후 결과를 검토합니다.
- 코드 질문과 탐색: 로컬 환경 없이 코드 구조나 구현 위치를 조사합니다.
로컬 도구, 사설 네트워크, 로컬 설정이 필요한 작업은 터미널 CLI, 데스크톱 앱 또는 Remote Control이 더 적합합니다.
전체 흐름
- GitHub를 연결하고 클라우드 환경을 만듭니다.
- 저장소, 브랜치, 환경을 선택합니다.
- 작업을 설명하고 제출합니다.
- diff를 검토하고, 필요하면 추가 지시를 보낸 뒤 PR을 만듭니다.
각 세션은 새 VM에서 시작됩니다. 저장소가 복제되고, 선택한 클라우드 환경에 따라 설정 스크립트와 네트워크 정책이 적용됩니다. Claude가 작업을 마치면 브랜치를 GitHub로 푸시하지만, 세션은 닫히지 않으므로 PR 생성 이후에도 같은 대화에서 계속 수정할 수 있습니다.
GitHub 연결 및 환경 생성
클라우드 세션은 저장소를 복제하고 작업 브랜치를 푸시하기 위해 GitHub 접근 권한이 필요합니다. 두 가지 연결 방식이 있습니다.
| 방법 | 작동 방식 | 적합한 경우 |
|---|---|---|
| GitHub App | 웹 온보딩 중 Claude GitHub 앱을 승인합니다. | 브라우저에서 시작하거나 PR 자동 수정을 사용하려는 팀 |
/web-setup | Claude Code CLI에서 로컬 gh 토큰을 Claude 계정과 동기화합니다. | 이미 GitHub CLI를 사용하는 개인 개발자 |
두 방법 모두 클라우드 세션이 연결된 GitHub 계정이 볼 수 있는 저장소에 접근하도록 합니다. GitHub App 설치는 PR 웹훅을 받아 자동 수정 기능을 실행할 때 필요합니다.
저장소 접근 범위는 Claude Code 세션 안에서 따로 제한하지 않습니다. 팀이 클라우드 세션에서 도달할 수 있는 저장소를 제한해야 한다면 GitHub 조직, 팀, 저장소 권한에서 제한하세요.
브라우저에서 연결
claude.ai/code에 로그인하면 GitHub 연결을 요청받습니다. 프롬프트에 따라 Claude GitHub 앱을 설치하고 Claude가 접근할 저장소를 허용합니다. 클라우드 세션은 GitHub 저장소를 기준으로 실행되므로, 새 프로젝트를 시작하려면 먼저 GitHub에 저장소를 만들어야 합니다.
GitHub 연결 후 클라우드 환경을 생성합니다. 첫 환경은 기본값으로 시작해도 됩니다.
- 이름: 여러 프로젝트나 접근 수준을 구분하는 표시 이름입니다.
- 네트워크 접근: 세션이 인터넷에서 도달할 수 있는 범위입니다. 기본값인
Trusted는 일반 패키지 레지스트리와 개발 도메인을 허용하고 임의의 외부 접근은 차단합니다. - 환경 변수: 모든 세션에서 사용할
.env형식 변수입니다. 환경을 편집할 수 있는 사람에게 보이므로 민감한 값은 신중하게 추가합니다. - 설정 스크립트: Claude Code 시작 전에 실행되는 Bash 스크립트입니다. 클라우드 VM에 없는 도구를 설치할 때 사용합니다.
환경의 자세한 동작, 캐싱, 설치 도구, 네트워크 허용 목록은 클라우드 환경 구성을 참조하세요.
터미널에서 연결
이미 GitHub CLI(gh)를 사용한다면 Claude Code CLI에서 /web-setup을 실행해 브라우저 온보딩을 줄일 수 있습니다. 먼저 gh와 Claude Code가 각각 인증되어 있어야 합니다.
gh auth login
Claude Code CLI 안에서 로그인한 뒤:
/web-setup
/web-setup은 로컬 gh 토큰을 Claude 계정과 동기화하고, 클라우드 환경이 없으면 기본 환경을 생성합니다. 완료 후에는 --remote로 터미널에서 클라우드 세션을 시작하거나 /schedule로 루틴을 만들 수 있습니다.
Zero Data Retention이 활성화된 조직은 /web-setup과 클라우드 세션 기능을 사용할 수 없습니다.
첫 작업 제출
claude.ai/code 또는 Claude 모바일 앱의 Code 탭에서 입력 상자 아래의 저장소 선택기를 열고 작업할 저장소와 브랜치를 선택합니다. 한 세션에 여러 저장소를 추가할 수도 있습니다.
입력 옆의 모드 드롭다운은 기본값으로 편집 자동 수락입니다. 이 모드에서 Claude는 승인 대기 없이 변경 사항을 만들고 브랜치를 푸시합니다. 파일 편집 전에 접근 방식을 먼저 보고 싶다면 Plan mode로 바꿉니다. 클라우드 세션은 Ask 권한, Auto 모드, Bypass 권한을 제공하지 않습니다. 전체 목록은 권한 모드를 참조하세요.
작업 설명은 구체적으로 작성합니다.
- 파일, 함수, 실패한 테스트 이름을 포함합니다.
- 오류 출력이 있으면 그대로 붙여넣습니다.
- "테스트 수정"보다 "
tests/test_auth.py의 로그인 만료 테스트를 통과하게 수정"처럼 기대 동작을 적습니다.
제출하면 Claude가 저장소를 복제하고 작업을 시작합니다. 각 작업은 고유한 세션과 브랜치를 가지므로 여러 작업을 동시에 맡길 수 있습니다.
검토 및 반복
Claude가 변경 사항을 만들면 세션의 diff 표시기에서 추가 및 제거된 줄 수를 볼 수 있습니다. diff 보기를 열어 파일별 변경 사항을 확인하고, 필요한 줄에 인라인 댓글을 남긴 뒤 다음 메시지로 Claude에게 보냅니다.
변경 사항이 맞으면 diff 보기 상단의 PR 생성 을 선택합니다. PR을 만든 뒤에도 세션은 계속 활성 상태이므로 CI 실패 출력이나 리뷰어 댓글을 붙여넣고 추가 수정을 요청할 수 있습니다. Claude가 PR을 계속 감시하도록 하려면 PR 자동 수정을 사용합니다.
빠른 문제 해결
저장소가 보이지 않음
GitHub 앱이 해당 저장소에 접근하도록 허용되어 있는지 확인합니다. GitHub의 Settings -> Applications -> Claude -> Configure 에서 저장소 접근 범위를 수정할 수 있습니다.
GitHub 로그인 버튼만 표시됨
클라우드 세션에는 연결된 GitHub 계정이 필요합니다. 브라우저 흐름으로 연결하거나, GitHub CLI를 사용한다면 Claude Code CLI에서 /web-setup을 실행합니다. GitHub를 연결하지 않고 자신의 머신에서 실행하려면 Remote Control을 사용합니다.
/web-setup이 Unknown command를 반환함
/web-setup은 셸 명령이 아니라 Claude Code CLI 안에서 실행하는 슬래시 명령입니다. claude를 시작한 뒤 프롬프트에 입력합니다. 그래도 실패하면 claude update 후 /login으로 claude.ai 계정에 다시 로그인합니다.
설정 스크립트가 실패함
설정 스크립트가 0이 아닌 상태로 종료되면 세션 시작이 차단됩니다. 네트워크 접근 수준, 존재하지 않는 경로, Ubuntu에서 다른 명령 이름을 사용하는지 확인합니다. 디버깅할 때는 스크립트 상단에 set -x를 추가하고, 중요하지 않은 명령에는 || true를 붙입니다.