DramaClaw Complete Tutorial: From Novel to Finished AI Short Drama

DramaClaw is a source-available production line for AI comic dramas and short dramas. You feed it a novel or a script; it splits chapters, plans episodes, writes the script, draws storyboards and first frames, records voice-over, generates shot videos, and composes a finished episode with subtitles. This tutorial is based on v2.0.6 (released September 28, 2026). It goes from deployment to exporting your first episode, and for every step it tells you which page you're on, what to choose, what you get, and where people usually go wrong.

Is it the right tool for you? If you only need the occasional single-shot clip, Kling or Jimeng-style tools are simpler. If you want to turn a whole novel into dozens of episodes where every character looks the same from episode to episode, DramaClaw's "full pipeline + asset library" approach is where it pays off.

1. How DramaClaw Is Organized

DramaClaw has two ways of working that share one asset library:

For your first project, stay in the Series pipeline until one episode is done. Move to the canvas for polishing and experiments once you know the flow.

About the license: DramaClaw uses the Elastic License 2.0 (ELv2). That makes it source-available, not open source in the OSI sense. According to the official README, you can run it, modify it, and sell what you make with the self-hosted edition without asking or paying; the team only asks you to keep a small "Based on DramaClaw" line in the UI. The one thing you can't do is offer DramaClaw itself to others as a hosted service.

2. Before You Start

2.1 Hardware and System Requirements

DramaClaw doesn't run models on your machine. All text, image, video, and audio inference goes through a remote OpenAI-compatible gateway, so local requirements are modest:

2.2 Accounts You'll Need

3. Installation

3.1 Option A: Pull the Release Images (Easiest)

If you don't want to build from source, use the published images. Every GitHub release ships multi-arch (amd64/arm64) images:

git clone https://github.com/dramaclaw/dramaclaw.git
cd dramaclaw
cp .env.example .env
# Edit .env and change PROMPT_EXPORT_PASSWORD to a non-default value
docker compose -f docker-compose.release.yml up -d

To pin a version, set DRAMACLAW_VERSION (and DRAMACLAW_GATEWAY_VERSION when the release notes say so) in .env.

3.2 Option B: Build from Source

Build from source if you want to change code or track the latest commits. Since v2.0.3, a source build needs the built-in gateway, dramaclaw-gateway, cloned next to the main repo. Skip it and the build fails with unable to prepare context: path ".../dramaclaw-gateway" not found:

git clone https://github.com/dramaclaw/dramaclaw.git
git clone https://github.com/dramaclaw/dramaclaw-gateway.git
cd dramaclaw
cp .env.example .env
# Change PROMPT_EXPORT_PASSWORD here too
docker compose up -d --build

The first build compiles the gateway (Go + bun) and takes a few minutes. On Windows, clone and run everything from a WSL2 terminal and keep the code on the Linux filesystem (not under /mnt/c/...); otherwise volume mounts are slow and you may hit line-ending issues.

3.3 Check That It's Running

docker compose ps

You should see api, newapi, and web all running. Open http://localhost:8080 and the UI should load. The Community Edition (CE) runs as a single local user with no login, so there's no account system to set up for personal use.

4. Configure Models (Required — Nothing Generates Without This)

Go to Settings → Model Config. There are three modes; pick one and enable it:

4.1 Official Mode (Recommended)

Open Official, paste your DC key, and click Save & Enable. The official gateway already has every model mapping DramaClaw needs. Per the README, official mode uses the DC-*-LLM series for text, gpt-image and nano-banana for images, the Seedance 1.0 / 1.5 / 2.0 series and happyhorse for video, and IndexTTS2 for voice. v2.0.5 also added the LingShan G25 Fast and Pro image models.

4.2 Custom Mode

1. Open Custom. When the status reads "waiting for initialization", set a NewAPI root admin password (at least 8 characters) and click Initialize Local NewAPI. DramaClaw doesn't store this password — keep it somewhere safe, you'll need it to log into the gateway admin.
2. Start with the Recommended Setup. It currently covers OpenRouter, VolcEngine, fal.ai, and DoubaoAudio. Fill in the API key for each channel and click Save & Apply All. That writes provider channels, feature models, the embedding model, and image/video/audio mappings in one go.
3. Use Advanced Settings for fine-tuning. DramaClaw uses fixed internal model names such as DC-character-builder-LLM and DC-scene-builder-LLM; in custom mode you keep those names and map them to real upstream models. Any vision feature that sends images or video must be mapped to a model that accepts multimodal input.

Two common traps:

• The embedding model and dimension are bound when a project is created. Changing them later only affects new projects; to switch an existing project you have to clear and rebuild its knowledge graph.
• After an upgrade, new feature rows (for example DC-character-builder-LLM, added in v2.0.3) start empty. Pick a model and click Save Mapping, or that feature fails with No available channel for model DC-....

4.3 Reference Media Storage (When You Need It)

Image-to-image, first-frame video, first/last-frame video, and reference images all require upstream models to read your local files. Configure a publicly reachable temporary relay under Settings → Media Storage: either Alibaba Cloud OSS (endpoint, bucket, access key — the bucket doesn't need public read, DramaClaw uses short-lived signed URLs) or Cloudinary. Skip this for a pure text-to-video run.

5. Core Workflow: From Novel to Your First Episode

This follows the left-hand navigation in order: Story Source (import) → characters and scenes → Episode Studio (plan episodes) → Script → Sketches → Audio → Video → Compose. Each step is its own async task. Watch progress and logs in the Task Center, and retry a failed step on its own instead of starting over.

Step 1: Import Your Novel in Story Source

Goal: get the manuscript into the project and make sure chapters are detected correctly.

1. Create a project, open Story Source, and choose Upload Novel or Paste Text.
2. Uploads accept .txt, .md, and .docx, up to 512 KB per file and 100,000 characters of text. Pasted text is capped at 1,000 characters, which is only good for a quick test. For a long novel, split it by volume into separate projects.
3. Before importing, open Project Settings. These choices carry through every later step:
   • Visual Style: the overall look of the drama.
   • Narration Style: first person (the lead narrates) or third person (an outside narrator).
   • Rhythm, TTS Provider and TTS Voice, Video Engine, Video Resolution.
4. Click Start Import. When it finishes you get a Novel Structure Preview: filename, total characters, billable characters, chapters detected, estimated episodes, and each chapter's title and length. Below it there's a knowledge graph you can pan around to see how characters relate.

Watch out: check the chapter split carefully. If chapters are detected wrong, episode planning, characters, and scripts all inherit the mistake. Re-importing warns you that it rebuilds the graph and can affect characters, episodes, scripts, and videos you've already generated.

Step 2: Build Characters and Scenes, Lock Their Looks

Goal: create reusable character, scene, and prop assets. This is what keeps episodes consistent.

1. Open the Characters page and build characters from the graph. The system picks out the people in your novel.
2. Open each character and use AI generate under Portrait to create their main look. You can regenerate, but after several tries the page warns "High usage — verify settings before generating again."
3. Under Identities / Wardrobe, add variants of the same character, such as "teenage years" or "battle armor." Describe the outfit in keywords, or upload a wardrobe reference image to lock style and color. Identity images have a retry guard: the 3rd attempt asks for confirmation and the 5th needs the admin password, to stop endless rerolls from burning credits. Write the appearance and wardrobe description properly before you hit generate.
4. In the Asset Library, build scenes from the graph. Each scene can get a front image, a reverse image, and a 360° panorama, which keeps the space coherent when the camera moves.
5. Props work the same way: generate a reference image, and add important props to the global prop library so every episode can reuse them.

Step 3: Plan Episodes in Episode Studio

Goal: turn the chapter structure into episodes, each with its identities, scenes, and props ready.

1. Open Episode Studio and click Plan episodes. The episode list is generated from the chapter structure.
2. Each episode card shows its source lines, identities, scenes, and props. Inside an episode, finish identity planning, scene planning, and prop planning first. Without identities, the script step tells you to "Plan identities for this episode before generating the script."
3. Planning reuses existing identities and only creates new ones for looks that haven't appeared yet, so the more complete your Step 2 assets are, the less work this is.

Step 4: Generate the Script

Goal: turn the episode's source text into a structured script split into beats.

1. Open the episode's Script stage. The read-only source is on the left; the beat source text on the right is what gets turned into storyboards, and it auto-saves as you edit.
2. Pick how to split it:
   • Split scenes by target duration: for dramatized adaptations; the system reworks the pacing.
   • One beat per source line: when the source is already a shot list, or when you want to stay strictly faithful to the original.
3. For narrated comic dramas, click AI Rewrite first. It rewrites the source into short lines suited to voice-over, within your Min chars/line and Max chars/line settings, and then you generate the script. Note that AI Rewrite overwrites any existing rewrite.
4. After generation the script goes through a review-and-repair loop. The preview lists each beat's visual description, and the episode page also shows an AI-generated story summary, key events, and cliffhanger. Anything that failed review is flagged as "Unresolved issues remain" — fix those before moving on.

Step 5: Sketches and First Frames

Goal: lock composition with cheap sketches before rendering final first frames.

1. Open the Sketches stage. The system groups beats into grids by scene and shows a plan like "N beats → M grids." Confirm it and the sketch tasks are dispatched in bulk.
2. In sketch settings, pick the sketch model and aspect ratio. Changing the aspect ratio only affects content generated afterwards; existing assets have to be regenerated to pick up the new ratio, so settle the ratio before you start episode one.
3. Once the sketches look right, generate the renders (first frames). Confirming composition first and coloring second saves a lot of rework.

Step 6: Voice-Over

Goal: generate expressive voice-over for every beat.

Open the Audio stage and generate using the TTS provider and voice from your project settings. The Voice tab on each character lets you assign that character its own voice, so the narrator and each character are managed separately.

Step 7: Generate Shot Videos

Goal: turn each beat's first frame into a video shot.

Open the Video stage and generate shot by shot. The video node supports text-to-video, image-to-video, first frame, first/last frame, image reference, all-reference, video edit, and video extend (new in v2.0.6). Which modes you can actually use depends on the video model you've configured. Retry any failed shot individually from the Task Center.

Step 8: Compose and Export

Goal: assemble the full episode and export it.

1. Open the Compose stage. An episode can only be composed once every beat has a sketch, audio, and video. If anything's missing, the page lists it ("N beat(s) still not ready") and clicking a card jumps to that beat.
2. When everything is ready, click Compose Episode in the top right. You can include subtitles and background music; composing takes a few minutes.
3. Preview and download the MP4 on the page, or use Export SRT (subtitles) and Export ZIP (the full asset pack) in the top right.

6. Going Further

6.1 The Freezone Canvas

The canvas has 18 node types — upload, image generate/edit, storyboard, script, beat context, video, video compose, audio, style, 3D world, export, and more — and you can wire them however you like, with each node keeping its own generation history. On the image side you get repaint, outpaint, relight, upscale, multi-view, and prompt extraction, plus 45 built-in comic-drama styles. On the video side there's vocal separation, camera-move templates, and shot analysis.

The most useful feature is commit back to episode: when you've found something good on the canvas, preview what it will change, then write it into the asset library or a specific episode. The main pipeline and your canvas experiments don't step on each other.

6.2 Director World: Fixing Scene Drift

The most common failure in AI video is that the same location looks like a different place once the camera angle changes. Director World turns a scene image into a 3D Gaussian set or a 360° panorama, locking spatial layout, character blocking, and camera placement. Frame the shot in the 3D view, take a screenshot, and use it as the background for the next generation.

From a scene asset you can convert the front, reverse, or 360° image into a Director World. Full 3D conversion is part of the optional world extra and needs a GPU:

INSTALL_WORLD=1 docker compose up -d --build

If you're not doing 3D work, ignore this entirely — text-to-final-cut doesn't need it.

6.3 Visual Style Templates

In Visual Style, click Create Style and upload a reference image; AI extracts a style directive, an avoid directive, and a style tag. You can also fill these in by hand. Save, then click Apply to project, and every later generation in the project uses that style. It's much more stable than repeating the same description in every prompt.

6.4 Driving DramaClaw from Claude Code or Other Agents (MCP)

DramaClaw ships an MCP server that exposes the whole pipeline — ingest, characters, script, storyboards, first frames, video, audio, compose, export — as about 34 tools, so MCP-capable agents like Claude Code or Codex can build a drama end to end. On the Community Edition, local calls need no token:

claude mcp add dramaclaw \
  --env DRAMACLAW_API_URL=http://localhost:8780 \
  --env DRAMACLAW_CE_OWNER=1 \
  -- uv run python -m novelvideo.chat.dramaclaw_mcp

This needs a local checkout with uv sync already run. If you only use Docker, start the bridge inside the container instead: docker compose exec -T -e DRAMACLAW_API_URL=http://localhost:8780 -e DRAMACLAW_CE_OWNER=1 api python -m novelvideo.chat.dramaclaw_mcp.

For safety, tokenless mode only accepts loopback addresses such as localhost and 127.0.0.1, because it has full owner access to the instance. Never point it at a shared instance.

7. Backups and Upgrades

7.1 Where Your Data Lives

The project database, settings, and generated media are in the Docker named volume ce-data (/data inside the container). The built-in gateway's channels, keys, and tokens are in the newapi-data volume. docker compose down keeps both volumes — never add -v, which deletes them.

Back them up like this (the volume prefix follows your compose project name; check with docker volume ls):

docker run --rm -v dramaclaw-ce_ce-data:/data -v "$PWD":/backup alpine \
  tar czf /backup/ce-data-backup.tar.gz -C /data .
docker run --rm -v dramaclaw-ce_newapi-data:/data -v "$PWD":/backup alpine \
  tar czf /backup/newapi-data.tgz -C /data .

Back up your .env file separately.

7.2 Upgrading

Release images: update DRAMACLAW_VERSION in .env (and DRAMACLAW_GATEWAY_VERSION if the release notes ask), then:

docker compose -f docker-compose.release.yml pull
docker compose -f docker-compose.release.yml up -d

Source build: pull both repositories:

git -C ../dramaclaw-gateway pull
git pull
docker compose up -d --build

Upgrades leave your .env alone and reuse both data volumes as they are.

8. Troubleshooting Cheat Sheet

The general-purpose log command: docker compose logs -f api.

9. FAQ

Q: What GPU does DramaClaw need?

None. In the standard flow, all inference happens on the remote gateway; your machine only orchestrates, stores files, and composes the final video, so a 2-core / 4 GB machine or a small VPS is enough. You only need a GPU with CUDA for the optional world extra (voxel and panorama-to-3D work).

Q: How much does one episode cost?

It depends on the models, the number of episodes, and how many shots each episode has. The official gateway bills by usage, and the structure preview after import shows billable characters, so you can estimate the text side before you start. Images, video, and audio are billed per model. Video is usually the biggest cost, which is why confirming composition with sketches first matters — it cuts down repeated video generations. In custom mode, cost is whatever your own providers charge.

Q: Does it handle English novels?

Yes. Import works the same way, the UI is available in English, Chinese, and Vietnamese, and the screenplay format guidance has an English version (v2.0.4 corrected the English screenplay guidance). For an English drama, remember to pick an English TTS voice in project settings.

Q: My characters look different from one episode to the next. What do I do?

Consistency comes from the asset library. Lock each character's portrait and identity looks in Step 2, uploading wardrobe references where needed; episode identity planning then reuses those identities first. For locations, use front/reverse/360° scene images or Director World to pin down the space. Avoid regenerating character looks for every episode.

Q: How is this different from Kling or Jimeng?

Kling and Jimeng are video generation models and products: you make one shot at a time. DramaClaw is the production workflow that chains models together — it manages scripts, character assets, storyboards, voice-over, and compositing, and the underlying video model can be Seedance, Kling, Hailuo, ComfyUI, and others (in custom mode, depending on the built-in gateway's adapters). They aren't substitutes; DramaClaw can call those models to generate its shots.

Q: Can I sell the dramas I make?

Yes. According to the official README, the self-hosted edition can be used commercially under ELv2 and you can sell what you produce; the team only asks you to keep "Based on DramaClaw" in a corner of the UI. What isn't allowed is offering DramaClaw itself as a hosted service (SaaS). See official issue #475 for details.

10. Resources

• GitHub repository: https://github.com/dramaclaw/dramaclaw
• Official site: https://dramaclaw.ai
• Official docs (quickstart, model configuration, self-hosting, troubleshooting): https://github.com/dramaclaw/dramaclaw/tree/main/docs/en
• Built-in gateway, dramaclaw-gateway: https://github.com/dramaclaw/dramaclaw-gateway
• DramaClaw detail page on this site: https://www.ai-all.info/en/ai-models/dramaclaw-ai

---

This tutorial is based on DramaClaw v2.0.6 (September 2026) and the official documentation. Check the official repository for the latest UI and settings.