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으로 컨테이너를 다른 호스트 포트에 매핑하세요.