아티클

Docker 컨테이너 환경에서 Claude Code 첫 실행 시 발생하는 3가지 문제와 해결책

2026년 7월 25일

새 컨테이너의 Claude Code는 온보딩, 디렉터리 신뢰, API 키 확인에서 정지합니다. 무인 환경에서는 ~/.claude.json에 사전 설정을 주입해야 합니다.

배너를 출력하고 대기 중인 에이전트도 바이트를 방출하므로 로그상 정상처럼 보이지만 실제로는 입력을 기다리며 멈춰 있습니다.

순서대로 마주치는 3가지 관문

일부만 해결하면 다음 관문에서 멈추게 됩니다.

실측 비교 매트릭스

깨끗한 HOME 환경에서 claude 2.1.220으로 측정한 결과:

심볼릭 링크 해결의 함정

~/.claude.json의 경로는 반드시 실제 정규화된 경로(canonical)여야 합니다.

export function trustKeyFor(root: string): string {
  try {
    return realpathSync(root);
  } catch {
    return root;
  }
}

API 키 승인의 복병

API 키 확인은 기본값이 2. No (recommended)로 지정되어 있습니다. CLI는 키의 마지막 20자를 승인 토큰으로 저장합니다.

export function approvalTokenFor(apiKey: string): string {
  return apiKey.slice(-20);
}

작동하지 않는 우회책

--permission-mode bypassPermissions 옵션은 디렉터리 신뢰 대화상자를 건너뛰지 못합니다.

테마 선택은 단순 취향이지만 파일 삭제는 중대한 결정입니다.

환경 초기화는 자동화하되 위험 도구 실행 권한 확인은 엄격히 유지합니다.

const trust: ProjectTrust = {
  hasTrustDialogAccepted: true,
  hasCompletedProjectOnboarding: true,
  projectOnboardingSeenCount: 0,
  allowedTools: [],
};

클라우드 환경 구동은 클라우드에서 Claude Code 실행, 연결 안정성은 직접 호스팅하지 않는 터미널 관찰에서 확인하실 수 있습니다.

직접적인 답변