Claude Code on the Web: 브라우저에서 바로 시작하는 AI 주도 개발

「시작하기」 코스의 마지막 편입니다. 지금까지는 내 컴퓨터의 터미널에서 Claude Code를 켰지만, 같은 엔진을 브라우저에서 돌리는 웹판이 있습니다. 이번 편은 Claude Code on the Web이 무엇인지, 어떤 일에 맞는지, GitHub 연결과 환경 설정 절차, 실제 작업 흐름, 웹 세션을 터미널로 이어받는 teleport, 의존 패키지 설치 자동화, 네트워크 접근 수준, 제한 사항, 그리고 CLI판과 가려 쓰는 기준을 다룹니다. 읽고 나면 "이 작업은 웹에서, 저 작업은 터미널에서"를 스스로 가를 수 있습니다.

핵심 요약

• 웹판은 claude.ai/code에서 GitHub 저장소를 연결해 Anthropic이 관리하는 클라우드 VM에서 작업합니다. 내 컴퓨터에 아무것도 설치하지 않아도 됩니다.
• Pro, Max, Team 사용자와 Premium 좌석 Enterprise 사용자가 쓸 수 있으며 연구 미리보기 단계입니다.
• 작업 하나가 세션 하나, 브랜치 하나입니다. 여러 작업을 병렬로 돌리고 브라우저를 닫아도 계속 실행됩니다.
• claude --teleport로 웹 세션을 터미널로 가져오고, claude --cloud "작업"으로 터미널에서 웹 세션을 만듭니다.
• 저장소에 커밋된 CLAUDE.md, .claude/settings.json, .mcp.json은 웹에서도 그대로 적용되고, 내 컴퓨터의 ~/.claude/ 설정은 적용되지 않습니다.

Claude Code on the Web은 무엇인가

웹판은 Claude Code를 내 머신 대신 Anthropic 관리 클라우드에서 실행하는 방식입니다. claude.ai/code 또는 Claude 모바일 앱의 Code 탭에서 저장소를 고르고 작업을 적으면, 격리된 VM에 저장소를 새로 복제해 변경하고 브랜치를 푸시합니다. 세션은 브라우저를 닫아도 유지되고, 노트북에서 시작한 작업을 휴대폰에서 검토할 수 있습니다. 클라우드 VM 사용에 별도 컴퓨팅 요금은 없고, 계정의 다른 Claude 사용과 같은 한도를 나눠 씁니다.

어떤 일에 쓰면 좋은가

코드 아키텍처에 대한 질문

로컬에 체크아웃하지 않은 저장소를 두고 "이 기능이 어떻게 구현돼 있는지 추적해 줘" 같은 탐색을 시킬 때 편합니다. 우리 3주차에서 GitHub에 백업을 올린 뒤, 수강생이 서로의 저장소를 웹판으로 열어 구조를 물어보는 실습이 여기에 해당합니다.

버그 수정과 정형 태스크

"tests/test_auth.py의 실패하는 테스트 고쳐 줘"처럼 잘 정의된 작업을 던져 두고 다른 일을 하다가 결과만 검토하는 용도입니다. 자주 방향을 잡아 줘야 하는 작업보다는 한 번에 끝나는 작업이 맞습니다.

여러 태스크의 병렬 처리

각 작업이 자기 세션과 자기 브랜치를 갖기 때문에 워크트리를 여러 개 관리할 필요 없이 동시에 여러 개를 돌릴 수 있습니다. 대신 병렬로 돌리는 만큼 사용 한도도 비례해서 소모됩니다.

이동 중의 작업

Claude iOS, Android 앱에서 세션을 모니터링하고 지시를 보낼 수 있습니다. 터미널에서 /mobile을 입력하면 앱 설치용 QR 코드가 나옵니다. 정광우 대표처럼 운영 코드 67개를 굴리는 입장에서는 외근 중에 "CI 실패 원인 봐 줘"를 던지고 사무실에서 결과를 받는 식으로 씁니다.

설정은 어떻게 하나

설정은 한 번만 하면 됩니다.

1. claude.ai/code에 접속해 Anthropic 계정으로 로그인합니다.
2. 안내에 따라 Claude GitHub 앱을 설치하고 저장소 접근을 허용합니다. 새 프로젝트라면 GitHub에서 빈 저장소를 먼저 만듭니다.
3. 클라우드 환경을 만듭니다. 이름, 네트워크 접근 수준, 환경 변수, 설정 스크립트 네 항목이 있고 첫 프로젝트는 기본값 그대로 두어도 됩니다.

이미 GitHub CLI(gh)를 쓴다면 브라우저 없이 터미널에서 끝낼 수 있습니다. gh auth login 뒤 Claude Code 안에서 /web-setup을 실행하면 로컬 gh 토큰을 Claude 계정에 동기화하고 기본 환경까지 만들어 줍니다. 클라우드 세션은 연결된 GitHub 계정이 볼 수 있는 모든 저장소에 접근할 수 있으므로, 팀에서 범위를 좁히려면 GitHub 쪽에서 계정의 저장소 멤버십을 제한합니다.

실제 작업은 어떻게 흘러가나

1. 저장소와 브랜치를 고릅니다. 기본 브랜치 대신 기능 브랜치에서 시작하도록 바꿀 수 있고 한 세션에 여러 저장소를 붙일 수도 있습니다.
2. 권한 모드를 고릅니다. 기본은 "편집 자동 수락"이고 승인을 기다리게 하려면 Plan 모드로 바꿉니다. 웹 세션에는 Manual과 Bypass가 없습니다.
3. 작업을 적고 Enter를 누릅니다. 파일이나 함수 이름을 지정하고, 오류 출력이 있으면 붙여 넣고, 증상이 아니라 기대 동작을 씁니다.
4. Claude가 저장소를 복제하고 설정 스크립트를 돌린 뒤 작업합니다. 멈출 지점에 오면 브랜치를 GitHub에 푸시합니다.
5. +42 -18 같은 diff 표시를 눌러 변경을 보고, 줄 단위로 인라인 댓글을 남기면 다음 메시지에 묶여 전달됩니다.
6. 만족스러우면 diff 화면 위의 "PR 생성"으로 풀 리퀘스트를 엽니다. PR을 만든 뒤에도 세션은 살아 있어 CI 실패 출력이나 리뷰 댓글을 붙여 넣어 이어서 고칠 수 있습니다.

웹 세션을 로컬 CLI로 이어받으려면 (teleport)

웹에서 시작한 세션을 터미널로 가져오는 것이 teleport입니다.

# 세션 선택기에서 고르기
claude --teleport

# 세션 ID로 바로 가져오기
claude --teleport <session-id>

세션 안에서는 /teleport(또는 /tp)로 같은 선택기를 열고, /tasks 화면에서 t를 눌러도 됩니다. 웹 화면의 "Open in CLI"는 붙여 넣을 명령을 복사해 줍니다. teleport는 올바른 저장소인지 확인하고, 웹 세션의 브랜치를 가져와 체크아웃하고, 대화 기록 전체를 터미널에 불러옵니다. 조건은 넷입니다. 작업 디렉터리에 커밋되지 않은 변경이 없을 것(있으면 stash를 권함), 포크가 아닌 같은 저장소일 것, 웹 세션의 브랜치가 원격에 푸시돼 있을 것, 웹과 같은 claude.ai 계정으로 로그인돼 있을 것. API 키나 Bedrock으로 인증한 터미널에서는 쓸 수 없으므로 /login으로 구독 계정에 로그인합니다.

반대 방향도 있습니다. 터미널에서 claude --cloud "src/auth/login.ts의 인증 버그 수정"을 실행하면 현재 저장소의 GitHub 원격을 현재 브랜치에서 복제해 새 웹 세션을 만듭니다. VM은 내 머신이 아니라 GitHub에서 복제하므로 로컬 커밋은 먼저 푸시해야 합니다. 공식 문서가 권하는 조합은 "로컬에서 plan 모드로 계획을 세워 저장소에 커밋하고, 실행은 --cloud로 클라우드에 맡기는" 방식입니다.

의존 패키지 설치를 자동화하려면 (SessionStart 훅)

클라우드 세션은 매번 새 VM에서 시작하므로 npm install 같은 의존성 설치를 자동화해 두면 편합니다. 저장소에 커밋되는 SessionStart 훅을 쓰면 로컬과 클라우드 양쪽에서 같은 스크립트가 돌아갑니다.

훅 등록

저장소의 .claude/settings.json에 추가합니다.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/scripts/install_pkgs.sh"
          }
        ]
      }
    ]
  }
}

설치 스크립트

scripts/install_pkgs.sh를 만들고 chmod +x로 실행 권한을 줍니다. 클라우드 세션에서는 CLAUDE_CODE_REMOTE가 true로 설정되므로 이 값을 보고 로컬 실행을 건너뛸 수 있습니다.

#!/bin/bash
if [ "$CLAUDE_CODE_REMOTE" != "true" ]; then
  exit 0
fi
npm install
pip install -r requirements.txt
exit 0

훅은 세션이 시작되거나 재개될 때마다 돌며 환경 캐시의 이점을 받지 못합니다. 그래서 언어 런타임이나 CLI 도구처럼 한 번만 깔면 되는 것은 환경의 설정 스크립트에, 프로젝트 의존성처럼 로컬과 클라우드 모두에서 필요한 것은 SessionStart 훅에 두는 것이 공식 구분입니다. Bun은 프록시 호환 문제가 알려져 있으므로 npm이나 pnpm을 씁니다.

클라우드 환경은 어떻게 설정하나

네트워크 접근은 기본적으로 제한된다

클라우드 세션의 아웃바운드 연결은 보안 프록시를 거치며 기본값은 Trusted입니다. npm, PyPI, RubyGems, crates.io 같은 패키지 레지스트리와 GitHub, 주요 클라우드 SDK 도메인만 허용되고 일반 인터넷은 막힙니다. GitHub 작업은 별도 프록시를 통해 실제 자격증명이 샌드박스 밖에 남도록 처리되고, 푸시는 현재 작업 브랜치로만 제한됩니다.

새 클라우드 환경 추가

현재 환경 이름을 눌러 선택기를 열고 "환경 추가"를 고릅니다. 프로젝트나 접근 수준별로 여러 환경을 둘 수 있습니다. 설정 스크립트는 Ubuntu 24.04에서 root로 돌아가며, 첫 실행 결과가 파일 시스템 스냅샷으로 캐시돼 이후 세션은 설치를 건너뜁니다. 캐시는 스크립트나 허용 도메인을 바꾸거나 약 7일이 지나면 다시 만들어지므로 스크립트 총 실행 시간을 대략 5분 안에 맞춥니다. 터미널에서는 /remote-env로 기본 환경을 고를 수 있습니다. VM 자원 상한은 대략 4 vCPU, 16GB RAM, 30GB 디스크입니다.

네트워크 접근 레벨 네 가지

Custom에서는 한 줄에 도메인 하나씩 적고 *.internal.example.com처럼 와일드카드를 쓸 수 있습니다. 조직 단위로 허용 목록을 내려보내는 기능은 없고 환경마다 설정합니다.

환경 변수

.env 형식으로 한 줄에 KEY=value 하나씩 적습니다. 따옴표는 값의 일부로 저장되므로 감싸지 않습니다. 중요한 점은 전용 비밀 저장소가 아직 없다는 것입니다. 환경 변수와 설정 스크립트는 그 환경을 편집할 수 있는 모든 사람에게 보입니다. 우리 3주차 키 관리 원칙대로 운영 키는 여기에 넣지 않고, 테스트용 키만 넣습니다. GH_TOKEN을 비워 두면 GitHub 프록시가 자동으로 인증을 대신하고, 직접 넣으면 그 값이 그대로 전달됩니다.

제한 사항은 무엇인가

• 저장소 복제와 PR 생성에는 GitHub가 필요합니다. GitLab, Bitbucket 저장소는 claude --cloud의 로컬 번들로 보낼 수는 있지만 결과를 원격에 되돌려 푸시할 수 없습니다.
• 사용 한도를 계정의 다른 Claude 사용과 공유하며, 병렬 세션은 비례해서 한도를 씁니다.
• ~/.claude/ 아래의 사용자 설정, claude mcp add로 넣은 MCP 서버, 사용자 범위 플러그인은 적용되지 않습니다. 저장소의 .claude/와 .mcp.json에 커밋해야 합니다.
• 전용 비밀 저장소가 없고, AWS SSO 같은 대화형 인증은 지원되지 않습니다.
• /clear, /resume, /plugin처럼 터미널 전용 명령은 쓸 수 없고, 새 작업은 사이드바에서 새 세션으로 시작합니다.
• 설정 파일의 defaultMode: "bypassPermissions"나 "dontAsk"는 무시됩니다.
• 조직 IP 허용 목록이 켜져 있으면 클라우드 세션이 인증 오류로 실패하고, Zero Data Retention 조직은 웹판을 쓸 수 없습니다.
• 자체 Docker 이미지로 기본 이미지를 바꾸는 것은 아직 지원되지 않습니다.

CLI판과 웹판은 어떻게 가려 쓰나

우리 기준은 단순합니다. 로컬 도구, 로컬 DB, 내 컴퓨터의 파일이 필요한 작업과 대화하며 방향을 잡아야 하는 작업은 CLI, GitHub에 올라간 저장소를 대상으로 잘 정의된 작업을 던져 두고 결과만 검토하면 되는 일은 웹판입니다. 무인 자동화(7주차)는 어느 쪽도 아닌 별개의 무인 서버 잡으로 다룹니다. 이 코스를 마쳤다면 다음은 CLAUDE.md와 권한 설정을 시스템으로 갖추는 단계입니다.

정리

• 웹판은 GitHub 저장소를 클라우드 VM에 복제해 브라우저에서 작업하고 PR까지 만드는 Claude Code입니다.
• 설정은 GitHub 앱 설치와 환경 생성 한 번이며 /web-setup으로 터미널에서도 가능합니다.
• 작업당 세션 하나와 브랜치 하나, 병렬 가능, 브라우저를 닫아도 계속됩니다.
• --teleport로 웹에서 터미널로, --cloud로 터미널에서 웹으로 옮깁니다.
• 로컬 설정과 비밀은 넘어가지 않으므로 저장소에 커밋된 것만 믿고, 운영 키는 넣지 않습니다.

자주 묻는 질문