Build hooks

Build hooks let you add custom Dockerfile layers — installing apt packages, Python deps, language runtimes, CLI tools — without editing the generated Dockerfile. Drop shell scripts into a directory and they're picked up automatically.

How to use them

1. Create a build-hooks/ directory in your project root.

2. Add one or more .sh scripts. Use a numeric prefix to control ordering:

   build-hooks/
   ├── 00-install-ffmpeg.sh
   ├── 01-install-python-deps.sh
   └── 02-install-node-deps.sh
   

3. Run snowclaw build or snowclaw deploy — hooks run alphabetically as root during docker build.

Empty or missing build-hooks/ adds no layer. Scripts are cleaned up after execution (rm -rf /tmp/build-hooks), so they don't bloat the final image.

Example

#!/usr/bin/env bash
# build-hooks/00-install-ffmpeg.sh
set -euo pipefail

apt-get update
apt-get install -y --no-install-recommends ffmpeg
rm -rf /var/lib/apt/lists/*

#!/usr/bin/env bash
# build-hooks/01-install-python-deps.sh
set -euo pipefail

pip install --no-cache-dir openpyxl pandas

Make sure each script is executable (chmod +x build-hooks/*.sh) and starts with set -euo pipefail so the build fails fast on errors.

When to use them vs. plugins

• Plugins (snowclaw plugins) are for OpenClaw-aware extensions that ship as npm packages or local directories.
• Build hooks are for everything else — system packages, language runtimes, binary CLIs, build-time file fetches. If the thing you're adding is "stuff that needs to be in the container at runtime but isn't an OpenClaw plugin," it belongs here.