DramaClaw Docker Compose로 AI 영상 파이프라인 띄우기

AI 영상 제작은 대본, 캐릭터 이미지, 장면, 음성, 편집 도구가 따로 놀기 쉽습니다. DramaClaw는 이 단계를 한 프로젝트 안에서 다루려는 source-available 비디오 제작 엔진입니다. GitHub README와 문서에 적힌 구성과 설치 경로를 확인했습니다.

개요

DramaClaw Community Edition은 docker compose로 api와 web 서비스를 실행합니다. 웹 UI는 http://localhost:8080, REST API는 http://localhost:8780을 사용합니다. 모델 추론은 원격 OpenAI 호환 게이트웨이에 맡기고, 프로젝트 상태는 로컬 파일과 SQLite에 저장합니다. PostgreSQL이나 Redis를 별도로 준비하지 않는 구조입니다.

대본을 넣으면 인물과 관계, 에피소드 구성을 다룬 뒤 스토리보드, 보이스오버, 영상 조합 단계로 넘어갑니다. 단계별 화면이 나뉘어 있어 중간 결과를 확인하거나 건너뛸 수 있다는 점이 일반 이미지 생성 도구와 차이가 납니다.

시스템 아키텍처

대본과 프로젝트 에셋을 먼저 모읍니다. 이후 장면 구성과 이미지·영상·음성 모델 호출이 이어지고, 결과를 영상과 자막 파일로 내보내는 흐름입니다. README에는 노드형 Freezone 작업 화면도 따로 두었습니다. 본선 파이프라인 밖에서 후보 이미지를 만드는 용도입니다.

1. 쓸 만한 이유

저라면 Claude, GPT, Codex CLI처럼 범용 대화형 도구를 이미 쓰는 상황에서 검토합니다. 이 도구는 글 한 줄이나 이미지 한 장이 아니라, 여러 에피소드에서 캐릭터와 장면을 유지해야 하는 영상 작업을 겨냥한 도구입니다.

• 작업 단위: 대본 파싱, 에피소드 구성, 스토리보드, 음성, 편집 결과를 한 프로젝트에 묶는 방식입니다.
• 모델 연결: 텍스트, 이미지, 영상, 음성 모델을 OpenAI 호환 게이트웨이 한 곳으로 연결하는 구조입니다.
• 상태 관리: CE 문서 기준으로 SQLite와 로컬 파일을 쓰며 별도 PostgreSQL, Redis가 필요 없습니다.

반대로 한 장의 홍보 이미지나 짧은 영상만 만들 목적이면 이 파이프라인은 큽니다. 과한 구성입니다. 기존 GPT·Claude·Codex CLI는 기획 문안과 스크립트 보조에 맞습니다. DramaClaw는 제작 단계와 에셋 관리까지 묶어야 할 때 의미가 있습니다.

준비물

• docker compose를 지원하는 Docker Desktop 또는 Docker Engine.
• 모델 채널용 DC key, 또는 자체 NewAPI 설정.
• 포트 8080, 8780을 다른 서비스가 쓰지 않는 환경.

기본 비밀번호 방치가 제일 위험한 지점입니다. PROMPT_EXPORT_PASSWORD는 .env.example 값을 그대로 두지 말고 바꿔야 합니다. 이 값은 프롬프트 내보내기 보호에 쓰입니다.

1. Docker Compose로 실행

공식 문서는 소스 빌드 방식과 release compose 파일 방식을 제공합니다. 처음 구조를 확인하려면 아래 명령을 쓰시면 됩니다.

git clone https://github.com/dramaclaw/dramaclaw.git
cd dramaclaw
cp .env.example .env
# .env에서 PROMPT_EXPORT_PASSWORD를 기본값과 다른 값으로 변경
docker compose up -d --build
docker compose ps

api와 web이 실행 상태로 보이면 컨테이너 시작은 끝난 상태입니다. 앞선 Docker Compose로 n8n 설치한 글처럼 Docker 쪽 점검 순서를 보시면 됩니다.

1. 모델 채널 설정

브라우저에서 http://localhost:8080을 열고 Settings → Model Configuration → Official Channel로 들어갑니다. 공식 채널은 https://relayclaw.cdnfg.com/v1 주소를 사용하며 DC key를 저장하면 문서 기준으로 별도 모델 매핑이 필요 없습니다.

자체 모델 채널을 쓸 경우 docker-compose.selfhosted.yml로 NewAPI 컨테이너를 함께 실행합니다. 이 경로에서는 UI에서 upstream key와 논리 모델 이름을 매핑해야 합니다. 키와 런타임 token은 .env가 아니라 로컬 settings.db에 저장된다는 점을 구분해두면 됩니다.

1. 사용 범위

장편 대본을 에피소드 단위로 나누고, 캐릭터·장면·음성 에셋을 계속 관리해야 하는 개인 제작자나 소규모 팀에 맞는 편입니다. 모델 제공사를 바꿔도 OpenAI 호환 endpoint를 유지하려는 환경에도 맞습니다.

직접 돌려보지 않은 상태에서 운영 서버 투입을 권하지 않습니다. 생성 영상 비용, 제공사별 모델 품질, 저장 공간은 프로젝트 길이와 선택 모델에 따라 달라집니다. 먼저 테스트 프로젝트 하나로 출력 형식과 비용 조건을 확인하시면 됩니다.

확인

컨테이너 시작 뒤 아래 명령을 실행합니다.

docker compose ps

api와 web이 실행 상태로 나타나고 브라우저에서 http://localhost:8080이 열리면 정상적으로 설치된 것입니다.