Claude Code: 에이전트형 코딩 도구의 설치 및 설정

2024년, 거대 언어 모델 (Large Language Models, LLM)의 진화와 소프트웨어 애플리케이션 및 웹페이지 인터페이스에서의 활용이 시작되었습니다. OpenAI의 GPT-4 모델은 텍스트 생성 및 정보 조립 측면에서 타의 추종을 불허하는 능력을 보여주었습니다. 2026년에는 두 가지 트렌드가 통합되었습니다. 바로 모델의 복잡성과 능력의 지속적인 진화, 그리고 LLM 호출의 에이전트적 (agentic) 능력을 크게 향상시킨 정교한 프레임워크와 라이브러리입니다.

LLM을 에이전트로 사용하는 것은 한때 함수 호출 (function calls)을 모니터링하고 수정해야 하는, 사실상 지속적인 인간 참여형 (human-in-the-loop) 호출 방식이었습니다. 하지만 이제 진정으로 자율적인 에이전트가 진화했습니다. 이들은 함수 호출 (function calling)과 함수 실행 (function execution)을 정확하게 적용하며, 오류를 분석하고 필요할 때 해결책을 적용합니다. 이들은 컴퓨터의 파일 및 소켓 (sockets)과 완전히 상호작용할 수 있어, 자율적인 코드 생성과 심지어 시스템 운영까지 현실로 만들고 있습니다.

에이전트형 도구의 최전선에는 CLI 도구인 Claude Code가 있습니다. 이 도구는 뛰어난 코드 생성 능력을 약속하고 제공하며, 모든 숙련도의 개발자들에게 향상된 생산성을 지원합니다.

이 글은 에이전트형 도구에 관한 새로운 블로그 시리즈의 시작이며, Claude Code CLI를 체계적으로 탐구하는 것으로 시작합니다. 이 글의 특별한 초점은 Claude Code의 설치 및 초기 구성입니다. 세밀한 권한을 가진 안전한 샌드박스(sandbox)로서, 그리고 당신이 작업할 파일에만 접근할 수 있는 Docker 컨테이너를 사용하는 방법을 배워보세요.

이 글의 기술적 맥락은 2026-04-02에 게시된 claude_code v2.1.91입니다. 예시와 대부분의 CLI 명령은 최신 버전에서도 작동할 것입니다.

이 글의 모든 글자, 숫자, 기호는 로그 메시지와 스크린샷의 상세한 복사본을 추가하여 수동으로 입력되었습니다. 저는 인공지능 도구와 애플리케이션의 능력에 매료되어 있지만, 블로그 기사를 작성하는 것은 여전히 저의 개인적인 기술입니다.

이 기사는 원래 저의 블로그 admantium.com에 게시되었습니다.

Docker 컨테이너 설정 (Docker Container Setup)

Claude Code는 컴퓨터나 노트북의 모든 파일을 생성, 편집 및 삭제할 수 있는 완전한 지원 기능을 갖춘 에이전트형 도구 (agentic tool)입니다. 이는 설치 스크립트를 통해 네이티브로 설치할 수 있으며, 이 스크립트는 기본적으로 플랫폼별 바이너리 (binary)와 필요한 라이브러리 (libraries)를 복사합니다. 또는 NPM 패키지 (NPM packages) 및 관련 요구 사항으로 설치할 수도 있습니다.

메인 컴퓨터의 파일이 실수로 수정되는 것을 방지하기 위해, Docker 이미지 (Docker image)를 설정하고 특정 디렉토리 (directories)를 마운트 (mount)하는 Docker 컨테이너 (Docker container)를 시작하는 것을 권장합니다.

디렉토리 구조 (Directory Structure)

다음과 같은 디렉토리 및 파일 구조를 설정하십시오:

.
├── Dockerfile
├── build
...

Dockerfile

Docker 이미지는 다음과 같은 특징을 가집니다:

• 공식 NodeJS LTS 이미지 (LTS image) 기반
• claude-code를 NPM 패키지로 설치
• 기본 보안 권한 (security permissions) 복사
• 전용 비밀번호를 통해 root가 될 수 있는 비루트 사용자 (non-root user)로 실행

파일 내용은 다음과 같습니다:

FROM node:24-trixie

WORKDIR /opt/claude
...

이 Dockerfile을 스테이징 포인트 (staging point)로 사용하십시오. 만약 Python, Go 또는 Rust 프로젝트를 개발 중이라면, 이 파일에 필요한 라이브러리와 기본 도구들을 추가하십시오.

권한 (Permissions)

Claude Code가 시작되면 현재 폴더에 대한 권한 대화 상자가 열립니다. 이를 승인하면 이 폴더 내의 모든 파일에 대한 읽기 권한 (read access)이 제공됩니다. 그 이후부터는 bash 명령부터 바이너리까지 모든 도구 호출 (tool invocations)에 대해서도 승인이 필요합니다. 특정 명령은 비밀 정보 (secrets)가 포함된 파일을 실수로 노출하거나, 환경 변수 (environment variables)를 출력하는 명령을 실행하거나, 네트워크 및 Docker 소켓 (sockets)에 접근할 수 있습니다.

이러한 접근을 방지하기 위해 권한 파일 (permission file)을 사용할 수 있습니다. 이 파일은 모든 Claude Code 세션에 대해 전역 규칙 (global rules)을 제공할 수 있도록 OS별 특정 디렉토리에 배치되어야 합니다. Linux 환경의 경우, 권한 파일은 /etc/claude-code/managed-settings.json 위치에 배치되어야 합니다.

일반적인 비밀 정보(secrets)의 우발적인 노출을 방지하고, 텔레메트리 (telemetry)를 위한 모델 호출 (model invocation) 횟수를 줄이기 위해 다음 내용을 붙여넣으세요.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "allow_remote_sessions": false,
...

컨테이너 빌드 (Building the Container)

다음 명령어를 사용하여 컨테이너를 빌드하세요. 관찰되지 않은 권한 상승 (privilege escalation)을 방지하기 위해 기본 사용자 node를 위한 무작위 비밀번호가 생성됩니다:

 docker build . \
  --build-arg SUDO_PASSWORD=$(LC_CTYPE=C tr -cd '[:alnum:]' </dev/urandom | head -c 10) \
  --tag claude-code-local:2.1.91 

빌드 로그를 주의 깊게 살펴보세요. 생성된 비밀번호가 로그에 나타납니다. 이를 반드시 기록해 두세요.

Docker 컨테이너 사용법 (Docker Container Usage)

컨테이너 시작하기 (Starting the Container)

Docker 이미지 빌드가 완료되면, 다음과 같이 선호하는 마운트 디렉토리 (mount directory)와 함께 컨테이너를 시작할 수 있습니다:

docker run --rm \
  --mount type=bind,src=./,dst=/opt/claude \
  --detach \
...

Claude Code는 세션 (session), 메모리 (memory), 그리고 전역 설정 (global settings)을 로컬 ~/.claude 디렉토리에 유지합니다. 이러한 설정을 유지하고 싶다면, 이 디렉토리를 생성하여 컨테이너에 마운트해야 합니다.

로컬 터미널에서:

mkdir -p ~/.claude/

그 다음, 추가 마운트 옵션을 사용하여 컨테이너를 시작하세요. 만약 컨테이너가 여전히 실행 중이라면, 먼저 docker stop claude-code-local 명령어로 중지해야 합니다.

docker run --rm \
  --mount type=bind,src=./,dst=/opt/claude \
  --mount type=bind,src="${HOME}/.claude",dst=/home/node/.claude \
...

Claude Code 세션 시작하기 (Starting a Claude Code session)

모델 설정 (Model Configuration)

컨테이너를 처음 실행할 때, LLM 제공업체 (LLM provider)를 통해 인증해야 합니다. Anthropic 계정을 사용하는 것 외에도, openrouter 또는 litellm과 같은 LLM 라우터 (LLM routers)를 사용하여 Azure, Google, Ollama 등을 포함한 모든 LLM 제공업체에 접근할 수 있습니다.

여기 표시된 것처럼 GitHub Co-Pilot 구독을 사용할 수도 있습니다. 컨테이너 내부로 진입(exec)하려면 다음 명령어를 실행하세요:

docker exec -it claude-code-local bash

그 다음, 헬퍼 라이브러리인 copilot-api를 설치하고 실행합니다.

npx copilot-api@latest start --proxy-env
Need to install the following packages:
copilot-api@0.7.0
...

링크를 열고 GitHub 자격 증명으로 로그인한 뒤, OTP 코드를 붙여넣으세요. 잠시 후, 현재 세션에서 선택 가능한 LLM 모델들을 확인할 수 있습니다.

Available models:
- claude-opus-4.6-fast
- claude-opus-4.6
...

마지막으로, ~/.claude/settings.json 파일을 생성하고 다음 내용을 붙여넣으세요. 모델 매핑(model mapping)은 본인의 취향에 맞게 설정해야 합니다. Anthropic의 Haiku, Sonnet, Opus 구분은 사용 가능한 GitHub Co-Pilot 모델로 매핑되어야 합니다.

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:4141",
...

세션 시작 (Session Start)

이제 마지막으로, Claude Code 세션을 시작할 수 있습니다. Docker 컨테이너로 진입(exec)하면, 마운트된 프로젝트가 포함된 정의된 디렉토리 /opt/claude로 자동 이동합니다.

claude

시작 대화창이 나타납니다...

확인되면 세션을 시작할 수 있습니다.

결론 (Conclusion)

결론 (Conclusion)

Claude Code는 코드 생성 (Code Generation)을 위한 가장 두드러진 에이전트형 (Agentic) 도구 중 하나입니다. 이 기사는 Claude Code의 CLI 도구, 슬래시 명령 (Slash Commands), 그리고 사용 사례 (Use-cases)를 체계적으로 탐구하기 위한 새로운 시리즈의 시작입니다. 여러분은 특정 로컬 디렉토리를 마운트할 수 있는 샌드박스 환경 (Sandboxed Environment)을 제공하는 Docker 컨테이너 내에 Claude Code를 설정하는 방법을 배웠습니다. Dockerfile, 민감한 데이터 및 환경에 대한 액세스를 제한하는 관리형 설정 권한 파일, 그리고 Docker 컨테이너를 빌드, 시작 및 사용하는 명령어를 확인했습니다. 다양한 LLM 제공업체 옵션 중에서 GitHub CoPilot이 선택되었습니다. 다음 기사에서는 CLI 명령어에 대한 탐구를 이어갑니다.