Claude Code on the Web 완전 정리
핵심 요약
Claude Code on the web은 GitHub 저장소를 클라우드 VM에 클론해, Claude가 자동으로 코드 분석·수정·테스트·PR 생성까지 도와주는 클라우드 개발 환경입니다. 웹·iOS에서 작업을 시작하고, 필요하면 터미널(로컬 CLI)로 그대로 이어서 작업할 수 있으며, 네트워크·환경변수·훅(hook) 등을 세밀하게 설정할 수 있습니다. 보안은 프록시·격리된 VM·스코프된 자격 증명으로 관리되며, 기본적으로 개발에 필요한 도메인들만 인터넷 접근이 허용됩니다.
Claude Code on the Web 개념 잡기
Claude Code on the web은 "Claude가 대신 개발 환경을 띄우고 코드를 만지는 GitHub 기반 클라우드 개발 에이전트"라고 보면 됩니다. 사용자는 브라우저(또는 iOS 앱)에서 작업 설명만 하면, Claude가 GitHub 저장소를 복제하고, 코드를 읽고, 수정하고, 테스트하고, 브랜치를 만들어 PR까지 준비합니다.
이 환경은 특히 로컬에 코드가 없거나, 여러 저장소에서 동시에 버그 수정·리팩터링을 하고 싶을 때, 혹은 백엔드 변경처럼 테스트가 중요한 작업에 유리합니다. iOS 앱에서는 이동 중에 작업을 시작하거나 진행 상황을 모니터링하고 방향을 조정하는 용도로 사용할 수 있습니다.
누가 사용할 수 있나
이 기능은 아직 연구 프리뷰 단계이며, 유료 등급 사용자에게 제공됩니다. 구체적으로 Pro, Max, Team 및 Enterprise의 프리미엄 좌석을 가진 사용자만 사용할 수 있습니다.
무료 계정이나 프리미엄 좌석이 없는 팀 구성원은 이 기능을 직접 사용할 수 없습니다. 따라서 도입을 검토할 때는 조직의 요금제와 좌석 구성을 먼저 확인하는 것이 좋습니다.
시작하기: 기본 사용 흐름
시작 흐름은 "접속 → GitHub 연결 → 환경 선택 → 작업 실행 → PR 생성" 순서로 이해하면 쉽습니다.
먼저 https://claude.ai/code에 접속한 뒤, GitHub 계정을 연결하고 Claude GitHub 앱을 원하는 저장소에 설치합니다. 그 다음 기본으로 사용할 환경(네트워크 수준, 환경 변수 등)을 선택하고, 해결하고 싶은 개발 작업(버그 수정, 기능 추가, 리팩터링 등)을 설명합니다.
작업이 완료되면 Claude가 만든 변경사항을 검토하고, 승인할 만하다면 GitHub에서 바로 Pull Request를 생성해 팀 워크플로에 통합할 수 있습니다. 결국 "작업 설명 → 결과 리뷰 → PR 생성"의 반복 구조로 사용하게 됩니다.
동작 방식 이해하기
작업을 시작하면, Claude가 내부적으로 수행하는 단계는 크게 여섯 가지입니다.
먼저 저장소가 Anthropic에서 관리하는 가상 머신에 클론됩니다. 이후 미리 준비된 범용 이미지와 설정을 기반으로 언어·빌드 툴·테스트 도구가 포함된 환경을 준비합니다.
그 다음 네트워크 접근 수준(없음/제한/완전)을 설정하고, 설정에 따라 인터넷 사용을 제어합니다. 준비가 끝나면 Claude가 코드를 분석하고, 파일을 수정하고, 테스트를 실행하고, 자체적으로 결과를 점검하는 루프를 돕습니다.
작업이 끝나면 변경 사항은 새 브랜치에 커밋·푸시되고, 사용자는 결과를 확인한 뒤 PR을 생성합니다. 중요한 점은 이 모든 과정이 VM 내부의 CLI와 터미널 도구를 통해 자동으로 이뤄진다는 것입니다.
웹 세션을 터미널로 이어서 작업하기
웹에서 시작한 작업을 로컬 터미널로 가져와 이어서 할 수 있습니다. 이 기능은 "먼저 Claude가 클라우드에서 작업을 어느 정도 진행하게 하고, 이후 세밀한 조정이나 로컬 환경 통합은 직접 하는" 패턴에 적합합니다.
웹 UI에서 "Open in CLI" 버튼을 누르면 명령어가 제공되며, 이를 해당 저장소가 체크아웃된 로컬 디렉터리에서 실행합니다.
명령어를 실행하면 현재 로컬 변경사항은 안전하게 stash 되고, 클라우드 세션 상태가 로컬로 동기화됩니다.
이후에는 평소처럼 로컬 터미널에서 Claude Code CLI를 사용해 작업을 이어갈 수 있습니다. 단, 웹과 로컬을 이동하려면 동일한 계정으로 인증되어 있어야 하며, GitHub 기반 저장소여야 합니다.
클라우드 환경 구성 요소 이해하기
Claude Code on the web은 "범용 이미지"라는 기본 VM 이미지를 사용합니다. 여기에는 인기 프로그래밍 언어, 런타임, 빌드 도구, 테스트 프레임워크가 미리 설치되어 있어, 대부분의 프로젝트가 바로 실행 가능합니다.
예를 들어 Python(3.x, pip, poetry, 대표적인 과학 라이브러리), Node.js(LTS, npm·yarn·pnpm·bun), Go, Java(OpenJDK, Maven, Gradle), Rust(cargo), C++(GCC, Clang) 등이 준비되어 있습니다. Ruby는 3.1.6, 3.2.6, 3.3.6 버전이 있으며 기본은 3.3.6이고, rbenv로 버전 관리가 가능합니다.
데이터베이스도 PostgreSQL 16과 Redis 7.0이 포함되어 있어, 로컬 개발 환경에서 하던 대부분의 실험·테스트를 클라우드에서도 재현할 수 있습니다. 현재 설치된 도구를 확인하고 싶다면 Claude에게 아래 명령을 실행해 달라고 요청할 수 있습니다.
check-tools이 명령은 사용 가능한 언어, 버전, 패키지 매니저, 개발 도구 목록을 출력해, 환경을 파악하는 데 도움을 줍니다.
세션 초기 설정과 환경 변수 관리
새 세션이 시작될 때 Claude는 먼저 저장소를 클론하고, .claude 관련 설정과 훅(hook)을 읽어 초기화 동작을 수행합니다. 기본적으로 GitHub 저장소의 기본 브랜치가 사용되지만, 프롬프트에서 특정 브랜치를 명시하면 해당 브랜치를 체크아웃하도록 지시할 수 있습니다.
이후 네트워크 접근 수준이 설정되고, Claude는 CLAUDE.md에 정의한 컨텍스트와 지침을 참고해 작업을 진행합니다. CLAUDE.md에 "테스트는 어떻게 돌리는지", "빌드 명령은 무엇인지"를 잘 정리해두면, 매번 설명하지 않아도 에이전트가 더 정확하게 행동합니다.
환경 설정은 웹 UI에서 "환경 선택 → Add environment"를 통해 새 환경을 추가하거나, 기존 환경의 설정 버튼을 통해 이름·네트워크 수준·환경 변수를 수정할 수 있습니다. 환경 변수는 .env 형식의 key=value로 입력합니다.
API_KEY=your_api_key
DEBUG=trueSessionStart 훅에서 CLAUDE_ENV_FILE에 값을 기록하면, 이후 명령에서 지속적으로 사용할 환경 변수를 설정할 수 있습니다. 이 방식은 "로그인 토큰, 서비스 URL, 실험 플래그" 등을 세션 전체에 걸쳐 재사용할 때 유용합니다.
자동 의존성 설치와 훅 활용법
세션이 시작될 때마다 자동으로 npm install, pip install 등을 실행하고 싶다면, SessionStart 훅을 설정하면 됩니다. 이를 위해 저장소의 .claude/settings.json에 훅을 정의하고, 실제 명령을 담은 스크립트를 작성합니다.
예시 설정은 다음과 같습니다.
{
"hooks": {
"SessionStart": [
{
"matcher": "startup",
"hooks": [
{
"type": "command",
"command": ""$CLAUDE_PROJECT_DIR"/scripts/install_pkgs.sh"
}
]
}
]
}
}그리고 scripts/install_pkgs.sh 스크립트를 만들어 의존성 설치를 자동화합니다.
#!/bin/bash
npm install
pip install -r requirements.txt
exit 0권한을 부여하려면 다음 명령을 실행합니다.
chmod +x scripts/install_pkgs.sh모든 훅은 기본적으로 로컬과 클라우드 환경에서 모두 실행되지만, CLAUDE_CODE_REMOTE 환경 변수를 확인해 특정 환경에서만 동작하도록 제어할 수 있습니다. 예를 들어 아래처럼 "클라우드에서만 의존성 설치"를 하도록 만들 수 있습니다.
#!/bin/bash
if [ "$CLAUDE_CODE_REMOTE" != "true" ]; then
exit 0
fi
npm install
pip install -r requirements.txt네트워크 접근과 보안 정책 이해하기
Claude Code on the web의 네트워크는 기본적으로 "제한된 허용 목록 기반"입니다. 즉, 처음부터 아무 사이트나 접속할 수 있는 것이 아니라, 개발에 필요한 핵심 도메인들만 미리 열어둔 상태입니다.
GitHub 연동은 별도의 GitHub 프록시를 통해 처리되며, 클라우드 VM 안에서는 스코프가 제한된 특수 자격 증명을 사용합니다. 이 프록시는 실제 GitHub 토큰과의 매핑·검증을 처리하고, 푸시를 현재 작업 중인 브랜치로만 제한해 안전성을 확보합니다.
또한 모든 외부 HTTP/HTTPS 요청은 보안 프록시를 거쳐 나가며, 이 프록시는 악성 요청 방어, 레이트 리밋, 콘텐츠 필터링을 수행합니다. 사용자는 네트워크 수준을 "허용 안 함 / 제한 / 완전 허용" 등으로 구성할 수 있으며, 제한 모드에서는 문서에 나열된 도메인들(Anthropic, GitHub·GitLab·Bitbucket, 주요 패키지 레지스트리, 클라우드 플랫폼 등)만 접근이 허용됩니다.
도메인 목록에는 *.gcr.io처럼 와일드카드도 포함되어 있어, 특정 서비스의 모든 서브도메인을 한 번에 허용할 수 있습니다. 추가로, 네트워크 설정을 커스터마이즈할 때는 "최소 권한 원칙"을 적용하고, 허용 도메인을 주기적으로 점검하며, 가능하면 HTTPS를 쓰는 것이 권장됩니다.
격리, 보안, 한계 사항
각 세션은 독립된 Anthropic 관리 VM에서 실행되며, 네트워크 접근은 설정에 따라 제한되거나 완전히 차단될 수 있습니다. 네트워크를 완전히 끄더라도, Claude가 동작하기 위해 Anthropic API와 통신하는 것은 허용된다는 점은 염두에 둬야 합니다.
Git 자격 증명이나 서명 키 같은 민감한 정보는 VM 내부에 직접 저장되지 않고, 프록시와 스코프된 자격 증명으로만 사용됩니다. 코드 분석과 수정은 이 격리된 환경 안에서 수행된 뒤 PR로 결과만 외부에 노출되는 구조입니다.
한계로는, 현재 클라우드 세션은 GitHub 저장소에만 사용할 수 있고, GitLab 등 다른 호스팅 서비스의 저장소는 지원하지 않습니다. 또한 웹에서 시작한 세션을 로컬로 옮길 때는 동일 계정으로 인증되어 있어야 하며, 계정이 다르면 세션 이동이 불가능합니다.
요금과 사용량 측면에서는, Claude Code on the web은 계정의 다른 Claude 사용과 동일한 레이트 리밋을 공유합니다. 여러 작업을 병렬로 실행할수록 그만큼 더 많은 토큰·쿼터를 소비한다는 점을 고려해 작업량을 조절해야 합니다.
활용 팁과 실전 가이드
실무에서 효율적으로 쓰려면 "환경 자동화 + 문서화"를 잘 해두는 것이 핵심입니다. SessionStart 훅으로 의존성 설치와 기본 세팅(예: DB 마이그레이션, 코드 생성 등)을 자동화하면, 매번 환경 셋업을 설명할 필요가 줄어듭니다.
CLAUDE.md에는 프로젝트 개요, 빌드·테스트 명령, 디렉터리 구조, 코딩 규칙 등을 정리해 두고, 에이전트 관련 상세 설명이 있다면 AGENTS.md를 작성해 @AGENTS.md처럼 포함시키면 좋습니다. 이렇게 하면 사람이 보든, Claude가 보든 동일한 문서를 참조하게 되어 혼동이 줄어듭니다.
네트워크는 기본 제한 모드에서 시작해, 정말 필요한 외부 서비스만 추가로 허용하는 방식이 안전합니다. 또한 "한 번에 큰 기능을 맡기기"보다, "작은 변경 단위로 여러 작업을 병렬로 돌리고, 각 PR을 사람이 검토"하는 워크플로가 품질과 생산성 모두에 유리합니다.
인사이트
Claude Code on the web은 단순한 "AI 코드 어시스턴트"를 넘어, GitHub와 통합된 클라우드 개발 에이전트에 가깝습니다. 초기 진입 장벽은 GitHub 앱 설치, 환경 설정, 훅 구성 정도이지만, 한 번 세팅해 두면 반복적인 작업과 의존성 설치, 테스트 실행을 상당 부분 자동화할 수 있습니다.
실무에서 가장 큰 가치는 "환경 맞추기와 반복 작업에서 해방"되는 데 있습니다. 프로젝트마다 CLAUDE.md와 SessionStart 훅을 잘 설계해 두고, 한 번에 맡기는 작업 범위를 작게 유지하면서 PR 단위로 검증하는 습관을 들이면, 팀 전체 개발 속도와 코드 품질을 동시에 끌어올릴 수 있습니다.