Claude Code on the Web: Why Your .env Vars Don't Reach the Setup Script (and How SessionStart Hook Fixes It)

개요

Claude Code on the Web의 .env 변수가 설정 스크립트(setup script)에 전달되지 않아 발생하는 문제를 해결하기 위해, 환경 변수를 SessionStart 훅에서 로드하는 방법을 설명합니다.

주요 내용

• Claude Code on the Web에서 .env 패널에 설정한 환경 변수는 설정 스크립트에서는 접근할 수 없고, 실행 중인 Claude Code 세션의 쉘에서만 접근 가능합니다.
• 이로 인해 설정 스크립트 내에서 git clone 명령을 실행할 때 GH_TOKEN과 같은 환경 변수가 비어있어 실패하는 문제가 발생합니다.
• 문제 해결을 위해 git clone 명령을 설정 스크립트가 아닌, 세션 시작 후 환경 변수가 로드되는 SessionStart 훅으로 이동시켜야 합니다.
• 설정 스크립트의 디버깅을 위해 echo 출력을 /tmp/env-diag.log 파일로 리다이렉션하고 세션 내에서 해당 파일을 읽어오는 방법을 사용할 수 있습니다.
• Claude Code의 파일 시스템 스냅샷 캐싱 메커니즘 때문에 설정 스크립트가 재실행되지 않는 경우, 스크립트 상단에 임시 주석을 추가하여 캐시를 무효화할 수 있습니다.
• GitHub Private Repository 클론 시 GH_TOKEN을 .git/config에 평문으로 저장하지 않기 위해 git clone 명령어에 http.extraHeader 옵션을 사용하여 토큰을 전달하는 방식이 권장됩니다.
• SessionStart 훅에서 로컬 개발 환경에서의 불필요한 실행을 방지하기 위해 CLAUDE_CODE_REMOTE 변수를 확인하는 로직을 추가했습니다.
• 심볼릭 링크 생성 시 기존 디렉토리를 덮어쓰기 위해 ln -sf 대신 ln -sfn 옵션을 사용하고, 기존 디렉토리를 백업하는 로직을 포함했습니다.

시사점

Claude Code on the Web 환경에서 .env 변수 활용 시 설정 스크립트와 세션 쉘의 접근 범위를 명확히 이해하고, Git Repository 클론과 같은 민감한 작업을 수행할 때는 SessionStart 훅을 활용하여 보안 및 기능적 문제를 해결할 수 있습니다.