문제 해결
컨테이너가 시작되지 않음
섹션 제목: “컨테이너가 시작되지 않음””Conflict. The container name is already in use”
섹션 제목: “”Conflict. The container name is already in use””docker rm -f devcontainerdocker compose up -dpodman rm -f devcontainerpodman-compose up -dAI 도구가 작동하지 않음
섹션 제목: “AI 도구가 작동하지 않음””claude: command not found”
섹션 제목: “”claude: command not found””이미지가 오래되었을 수 있습니다. 최신 이미지를 가져온 후 재시작하세요:
docker compose pulldocker compose up -dpodman-compose pullpodman-compose up -dClaude에서 “Not logged in” 표시
섹션 제목: “Claude에서 “Not logged in” 표시”엔트리포인트는 온보딩 플래그와 함께 ~/.claude.json을 시드합니다. 누락된 경우:
echo '{"hasCompletedOnboarding": true}' > ~/.claude.jsonClaude에서 “Invalid API key” 표시
섹션 제목: “Claude에서 “Invalid API key” 표시”실제로 설정된 값을 확인하세요:
echo "$ANTHROPIC_API_KEY"일반적인 원인:
- LiteLLM 프록시 키 누락 또는 유효하지 않음 — 프록시 모드를 사용하는 경우,
.env의LITELLM_API_KEY에 올바른 프록시 자격 증명이 포함되어 있는지 확인한 다음 컨테이너를 재시작하여 엔트리포인트가ANTHROPIC_API_KEY를 파생할 수 있도록 하세요. - OAuth 토큰 또는 프록시 모드 불일치 — 인증 모드를 하나만 사용하세요.
CLAUDE_CODE_OAUTH_TOKEN이 설정된 경우, LiteLLM 프록시 모드보다 우선합니다.
API 요청이 401로 실패
섹션 제목: “API 요청이 401로 실패”API 키가 올바르게 설정되어 있는지 확인하세요:
echo "$ANTHROPIC_API_KEY"공급자에게 직접 호출하여 작동 여부를 확인하세요.
Claude에서 “model not found” 표시
섹션 제목: “Claude에서 “model not found” 표시”모델은 공급자와 API 키에 의해 결정됩니다. 사용 가능한 모델에 대해서는 공급자의 문서를 확인하세요.
GitHub CLI
섹션 제목: “GitHub CLI””gh: not authenticated”
섹션 제목: “”gh: not authenticated””gh CLI에는 GH_TOKEN 환경 변수가 필요합니다. .env 파일에 추가하세요:
GH_TOKEN=ghp_your-token-heregithub.com/settings/tokens에서 토큰을 생성하세요. 세분화된 토큰(권장) 또는 repo 범위가 있는 클래식 토큰 모두 사용할 수 있습니다. .env를 업데이트한 후 컨테이너를 재시작하세요.
HTTPS git clone이 401로 실패
섹션 제목: “HTTPS git clone이 401로 실패”GH_TOKEN이 설정되면, 엔트리포인트는 gh auth setup-git을 실행하여 HTTPS용 git 자격 증명 도우미를 구성합니다. HTTPS 작업이 실패하는 경우:
- 토큰이 유효한지 확인:
gh auth status - 자격 증명 도우미가 구성되었는지 확인:
git config --global credential.helper - 컨테이너를 재시작하여 엔트리포인트를 다시 실행
SSH vs HTTPS
섹션 제목: “SSH vs HTTPS”두 인증 방법 모두 컨테이너에서 공존할 수 있습니다:
- SSH (
.env의SSH_PRIVATE_KEY) —git@github.com:URL을 사용합니다. 조직에서 SSH를 강제하는 경우 필요합니다. - HTTPS (
.env의GH_TOKEN) —https://github.com/URL을 사용합니다. 설정이 간단하며 키 관리가 필요 없습니다.
두 가지 모두 구성된 경우, git은 원격 URL과 일치하는 프로토콜을 사용합니다. 기존 클론을 전환하려면:
# SSH에서 HTTPS로git remote set-url origin https://github.com/owner/repo.git
# HTTPS에서 SSH로git remote set-url origin git@github.com:owner/repo.git권한 문제
섹션 제목: “권한 문제”/workspace 또는 /home에서 “Permission denied”
섹션 제목: “/workspace 또는 /home에서 “Permission denied””sudo chown -R $(id -u):$(id -g) /workspace ~npm install이 EACCES로 실패
섹션 제목: “npm install이 EACCES로 실패”엔트리포인트는 ~/.npm-global에 사용자 쓰기 가능한 npm 글로벌 접두사를 자동으로 구성하므로, 런타임 npm install -g 명령이 sudo 없이 작동해야 합니다. 여전히 EACCES 오류가 발생하면, 수동으로 수정을 다시 적용하세요:
mkdir -p ~/.npm-globalnpm config set prefix ~/.npm-globalexport PATH="$HOME/.npm-global/bin:$PATH"빌드 문제
섹션 제목: “빌드 문제”빌드에 매우 오랜 시간이 걸림
섹션 제목: “빌드에 매우 오랜 시간이 걸림”첫 번째 빌드는 베이스 이미지(~1 GB)를 다운로드합니다. 이후 빌드는 캐시를 사용합니다. 매번 느린 경우:
docker builder prunepodman builder prune“No space left on device”
섹션 제목: ““No space left on device””docker system prune -a --volumespodman system prune -a --volumes경고: 이 명령은 이 프로젝트의 것뿐만 아니라 사용되지 않는 모든 컨테이너, 이미지, 볼륨을 제거합니다.
네트워킹
섹션 제목: “네트워킹”컨테이너 내부에서 인터넷에 접근할 수 없음
섹션 제목: “컨테이너 내부에서 인터넷에 접근할 수 없음”ping -c 1 8.8.8.8nslookup google.comcurl -I https://github.comDNS가 실패하면, 호스트의 /etc/docker/daemon.json에 추가하세요:
{ "dns": ["8.8.8.8", "8.8.4.4"]}그런 다음 Docker를 재시작하세요.
DNS가 실패하면, Podman 머신 내부에서 DNS를 구성하세요:
podman machine sshsudo sh -c 'echo "nameserver 8.8.8.8" > /etc/resolv.conf'exit또는 호스트의 ~/.config/containers/containers.conf에 DNS 설정을 추가하세요:
[containers]dns_servers = ["8.8.8.8", "8.8.4.4"]그런 다음 Podman을 재시작하세요: podman machine stop && podman machine start.
원격 디스플레이 (noVNC)
섹션 제목: “원격 디스플레이 (noVNC)”noVNC에서 검은 화면
섹션 제목: “noVNC에서 검은 화면”Xvfb가 시작되지 않았을 수 있습니다. 컨테이너 내부에서 확인하세요:
ps aux | grep Xvfb실행 중이 아닌 경우, ENABLE_VNC가 false로 설정되지 않았는지 확인하고 컨테이너를 재시작하세요.
”Cannot open display” 또는 “No display” 오류
섹션 제목: “”Cannot open display” 또는 “No display” 오류”DISPLAY 환경 변수가 설정되지 않았을 수 있습니다. 확인하세요:
echo "$DISPLAY":99여야 합니다. 비어 있는 경우, .env 또는 devcontainer.json에 DISPLAY=:99를 추가하고 재시작하세요.
포트 6080 연결 거부
섹션 제목: “포트 6080 연결 거부”noVNC가 실행 중이 아닐 수 있습니다. 컨테이너 내부에서 확인하세요:
ps aux | grep -E 'novnc|websockify'실행 중이 아닌 경우, ENABLE_VNC가 true(기본값)인지 확인하고 컨테이너 로그를 확인하세요:
docker compose logs dev | grep -i vncpodman-compose logs dev | grep -i vnc포트 6080이 이미 사용 중
섹션 제목: “포트 6080이 이미 사용 중”docker-compose.yml에서 호스트 포트를 변경하세요:
ports: - "127.0.0.1:16080:6080"Chrome DevTools MCP
섹션 제목: “Chrome DevTools MCP”Chrome 원격 디버깅이 응답하지 않음
섹션 제목: “Chrome 원격 디버깅이 응답하지 않음”공유 Chrome 인스턴스는 포트 9222에서 실행되어야 합니다. 컨테이너 내부에서 확인하세요:
# Chrome이 실행 중인가?curl http://localhost:9222/json/version
# Chrome 로그 확인cat ~/.local/share/chrome-browser/chrome.log
# 심볼릭 링크 확인ls -la /opt/google/chrome/chrome
# Chrome 수동 재시작. /usr/local/lib/chrome-browser.shstart_chrome_browser심볼릭 링크가 누락된 경우, 최신 이미지를 가져온 후 컨테이너를 재시작하세요.
브라우저 프로필 잠금 오류
섹션 제목: “브라우저 프로필 잠금 오류”공유 브라우저 아키텍처에서는 프로필 잠금 오류가 발생하지 않아야 합니다. 발생하는 경우, 오래된 Chrome 프로세스가 잠금을 유지하고 있을 수 있습니다:
# 오래된 Chrome 프로세스 종료pkill -f 'chrome.*remote-debugging-port' || true
# 잠금 파일 제거rm -f ~/.cache/chrome-devtools-mcp/chrome-profile/SingletonLock
# Chrome 재시작. /usr/local/lib/chrome-browser.shstart_chrome_browserchrome-devtools-mcp 도구 중복
섹션 제목: “chrome-devtools-mcp 도구 중복”chrome-devtools-mcp 서버는 현재 ~/.claude/settings.json에 전역적으로 등록되어 있습니다. 리포지토리별 .mcp.json에도 등록되어 있으면 도구가 중복됩니다. 리포지토리별 .mcp.json 파일에서 chrome-devtools-mcp 항목을 제거하세요:
# 리포지토리별 설정 확인cat .mcp.json전역 등록을 사용하려면 리포지토리별 .mcp.json에서 chrome-devtools-mcp 키를 제거하세요.
모든 것 초기화
섹션 제목: “모든 것 초기화”docker compose down -vdocker rm -f devcontainer 2>/dev/nulldocker compose pulldocker compose up -dpodman-compose down -vpodman rm -f devcontainer 2>/dev/nullpodman-compose pullpodman-compose up -d이 명령은 볼륨의 모든 데이터를 삭제합니다. 리포지토리를 다시 클론하고 도구를 재구성해야 합니다.