OpenClaw Docker Essentials 스킬 가이드

개요

Docker Essentials 스킬 은 Docker CLI 를 통해 OpenClaw에 완전한 Docker 컨테이너 관리 기능을 제공합니다. 수십 가지 Docker 명령어와 플래그를 외울 필요 없이, 원하는 작업을 자연어로 설명하면 OpenClaw 에이전트가 나머지를 처리합니다 — 이미지 빌드부터 충돌한 컨테이너 디버깅까지.

Docker는 현대 배포 파이프라인의 핵심이지만, 명령어 범위가 방대합니다. OpenClaw Docker Essentials 스킬은 의도와 실행 사이의 간격을 메워주어, 모든 수준의 개발자가 컨테이너화에 쉽게 접근할 수 있도록 합니다. Node.js 앱을 프로덕션용으로 패키징하든, 빌드가 레이어 7에서 실패하는 이유를 조사하든, 에이전트가 요청을 적절한 docker 명령어로 변환하고 출력을 해석해 줍니다.

일반적인 워크플로:

1. OpenClaw에게 애플리케이션을 컨테이너에서 빌드하고 실행하도록 요청합니다.
2. 에이전트가 Dockerfile을 생성하거나 읽고, 올바른 플래그로 docker build 및 docker run 을 실행합니다.
3. 결과가 읽기 쉬운 요약으로 반환됩니다 — 컨텍스트 전환이 필요 없습니다.

사전 요구사항

Docker Essentials 스킬을 설치하기 전에 다음을 준비하세요:

• OpenClaw 설치 및 실행 중 (v1.0+)
• Docker Engine 설치 완료 — Docker 설치
• Docker 데몬 실행 중 — 스킬이 Docker 소켓과 통신합니다
• 스킬 관리를 위한 clawhub CLI 설치 완료

설정 확인:

# OpenClaw 버전 확인
openclaw --version

# Docker 버전 확인
docker --version

# Docker 데몬 실행 상태 확인
docker info

docker info 에서 오류가 반환되면, sudo systemctl start docker (Linux)로 Docker 데몬을 시작하거나 Docker Desktop(macOS / Windows)을 실행하세요.

설치 방법

한 줄의 명령어로 Docker Essentials 스킬을 설치합니다:

npx clawhub@latest install docker-essentials

설치 전에 스킬의 권한과 소스 코드를 검사할 수 있습니다:

clawhub inspect docker-essentials

설치 확인:

clawhub list

설치된 스킬 목록에 docker-essentials 가 표시되어야 합니다. 이 스킬은 Arnarsson 이 제작했으며, recommended 배지를 보유하고 있습니다. 이는 충분히 테스트되었고 적절한 구성 하에 위험이 낮다는 것을 의미합니다.

구성

Docker Essentials 스킬은 로컬 Docker 소켓( /var/run/docker.sock )을 통해 Docker 데몬에 연결합니다. 로컬 사용 시 API 키나 토큰이 필요하지 않습니다.

환경 설정

# 기본 Docker 소켓 (일반적으로 별도 설정 없이 작동)
export DOCKER_HOST=unix:///var/run/docker.sock

# 원격 Docker 호스트용 (선택 사항)
export DOCKER_HOST=tcp://your-remote-host:2376
export DOCKER_TLS_VERIFY=1
export DOCKER_CERT_PATH=~/.docker/certs

중요: TLS 없이 네트워크를 통해 Docker 소켓을 노출하지 마세요. 원격 Docker 호스트에 연결할 때는 항상 TLS 검증을 활성화하고 클라이언트 인증서를 사용하세요.

Docker Compose 지원

이 스킬은 Docker Compose 워크플로도 지원합니다. Docker Compose V2가 설치되어 있는지 확인하세요(Docker Desktop에 번들로 포함되어 있거나, docker-compose-plugin 을 별도로 설치):

docker compose version

사용 예시

1. 애플리케이션 빌드 및 실행

사용자: "프로젝트 루트의 Dockerfile에서 Docker 이미지를 빌드하고 포트 3000에서 실행해줘."

에이전트가 docker build -t my-app . 을 실행한 후 docker run -d -p 3000:3000 my-app 을 실행합니다. 컨테이너 ID, 매핑된 포트를 보고하고 앱이 localhost:3000 에서 접근 가능한지 확인합니다.

2. 실패한 컨테이너 디버그

사용자: "내 컨테이너 api-server 가 계속 충돌해. 마지막 50줄의 로그를 보여주고 원인을 알려줘."

에이전트가 docker logs --tail 50 api-server 를 실행하고, 출력을 분석하여 근본 원인을 식별합니다 — 예를 들어, 누락된 환경 변수나 포트 충돌 등. 그런 다음 수정 방법을 제안하고 직접 적용할 수도 있습니다.

3. Dockerfile 최적화

사용자: "내 Dockerfile을 분석하고 이미지 크기를 줄이기 위한 최적화를 제안해줘."

에이전트가 Dockerfile을 읽고, 불필요한 레이어, 누락된 멀티 스테이지 빌드, 비대한 베이스 이미지 등 일반적인 문제를 식별하여 구체적인 권장 사항을 제공합니다. 최적화가 적용된 Dockerfile을 다시 작성할 수 있으며, 이미지 크기를 50% 이상 줄이는 경우가 많습니다.

4. Docker 리소스 정리

사용자: "중지된 모든 컨테이너, 댕글링 이미지, 사용하지 않는 볼륨을 제거해줘."

에이전트가 정리 범위를 확인한 후 docker system prune -a --volumes 를 실행합니다. 회수된 디스크 공간과 제거된 리소스 목록을 보고합니다.

5. Docker Compose 스택 관리

사용자: "docker-compose.yml에 정의된 개발 스택을 실행하고 모든 서비스의 상태를 보여줘."

에이전트가 docker compose up -d 를 실행한 후 docker compose ps 를 실행하여, 실행 중인 서비스, 포트, 상태를 포맷된 표로 제공합니다. 서비스 시작에 실패하면 자동으로 로그를 확인하고 문제를 보고합니다.

보안 및 모범 사례

Docker 데몬 접근은 강력합니다 — 적절한 플래그가 있는 컨테이너는 호스트 파일 시스템, 네트워크, 심지어 다른 컨테이너에도 접근할 수 있습니다. 안전을 위해 다음 지침을 따르세요:

• 특권 모드를 피하세요. 절대적으로 필요한 경우가 아니면 --privileged 를 사용하지 마세요. 컨테이너에 호스트에 대한 완전한 접근 권한을 부여합니다.
• 비루트 사용자를 사용하세요. Dockerfile에 USER 지시문을 추가하여 컨테이너 내부에서 비루트 사용자로 프로세스를 실행하세요.
• 확인 후 실행하세요. OpenClaw는 docker system prune 이나 docker rm -f 와 같은 파괴적인 명령어를 실행하기 전에 승인을 요청합니다. 영향을 받는 항목을 항상 확인하세요.
• 리소스 사용을 제한하세요. --memory 및 --cpus 플래그를 사용하여 컨테이너가 호스트의 모든 리소스를 소비하지 않도록 방지하세요.
• 이미지 취약점을 스캔하세요. 이 스킬을 docker scout 또는 Snyk와 함께 사용하여 베이스 이미지의 알려진 CVE를 식별하세요.
• Docker를 최신 상태로 유지하세요. 보안 패치의 혜택을 받으려면 최신 안정 버전의 Docker Engine을 실행하세요.

일반적인 스킬 보안 지침은 안전 체크리스트 를 참조하세요.

문제 해결

"Cannot connect to the Docker daemon"

Docker 데몬이 실행 중이 아니거나 현재 사용자에게 소켓 접근 권한이 없습니다.

# Docker 데몬 시작 (Linux)
sudo systemctl start docker

# docker 그룹에 사용자 추가 (sudo 불필요)
sudo usermod -aG docker $USER
# 그룹 변경이 적용되려면 로그아웃 후 다시 로그인하세요

macOS 또는 Windows에서는 Docker Desktop이 실행 중인지 확인하세요.

"no space left on device"

Docker 이미지, 컨테이너, 볼륨이 디스크를 가득 채웠습니다.

# Docker 디스크 사용량 확인
docker system df

# 사용하지 않는 리소스 제거
docker system prune -a --volumes

Cron Creator 스킬을 사용하여 정기적인 정리 일정을 설정하는 것을 고려하세요.

"port is already allocated"

다른 프로세스 또는 컨테이너가 이미 요청된 포트를 사용 중입니다.

# 포트를 사용 중인 프로세스 확인 (예: 포트 3000)
lsof -i :3000

# 해당 포트를 사용 중인 Docker 컨테이너 목록
docker ps --filter "publish=3000"

충돌하는 프로세스를 중지하거나, -p 3001:3000 으로 컨테이너를 다른 호스트 포트에 매핑하세요.