\r \r

ComfyUI Bridge\r

\r Generate images, faceswap, animate expressions, and do style transfer via a self-hosted ComfyUI instance running on your LAN. No cloud API — your GPU, your models.\r \r

Requirements\r

\r

• ComfyUI Desktop (or server) running somewhere on your LAN\r
• ComfyUI Bridge server running on the same machine as ComfyUI (see Setup)\r
• uv installed on the machine running OpenClaw\r \r

Setup\r

\r

1. Install the bridge server (on your ComfyUI machine)\r

\r The bridge is a lightweight FastAPI server that wraps ComfyUI's API:\r \r

git clone https://github.com/Bortlesboat/comfyui-bridge\r
cd comfyui-bridge\r
pip install -r requirements.txt\r
python bridge_server.py\r
# Listening on http://0.0.0.0:8100\r
```\r
\r
### 2. Configure the skill\r
\r
Set the bridge URL as an environment variable on your OpenClaw machine:\r
\r
```bash\r
export COMFYUI_BRIDGE_URL=http://YOUR_COMFYUI_MACHINE_IP:8100\r
```\r
\r
Or add it to your LaunchAgent/systemd service environment.\r
\r
### 3. Required ComfyUI custom nodes (for all features)\r
\r
Install via ComfyUI Manager:\r
- **ReActor** — faceswap\r
- **ComfyUI-LivePortrait** — expression animation\r
- **ComfyUI_IPAdapter_plus** — style transfer\r
- **WAS Node Suite** — utilities\r
- **ComfyUI-GGUF** — GGUF model support (optional, for FLUX)\r
- **rgthree-comfy** — workflow utilities\r
\r
### 4. Recommended models\r
\r
| Model | Use |\r
|---|---|\r
| Juggernaut XL Ragnarok | Architecture, objects, general |\r
| RealVisXL V5.0 Lightning | People, portraits, fast |\r
| FLUX.1 Dev Q5 GGUF | Maximum photorealism (slow, VRAM-heavy) |\r
\r
---\r
\r
## Usage\r
\r
All commands use the `comfyui_generate.py` script via `uv run`. Replace `SKILL_SCRIPTS` with the path to this skill's `scripts/` directory.\r
\r
**Always use `--no-media`** — include one `MEDIA: /full/path/to/output.png` in your text response instead.\r
\r
### 1. Text to Image\r
\r
```bash\r
uv run $SKILL_SCRIPTS/comfyui_generate.py \\r
  --prompt "your description" \\r
  --filename ~/.openclaw/media/outbound/output.png \\r
  --no-media\r
```\r
\r
### 2. Image to Image\r
\r
```bash\r
uv run $SKILL_SCRIPTS/comfyui_generate.py \\r
  --prompt "make it sunset" \\r
  -i /path/to/input.png \\r
  --strength 0.5 \\r
  --filename ~/.openclaw/media/outbound/output.png \\r
  --no-media\r
```\r
\r
### 3. Faceswap (pipeline — best quality)\r
\r
Swaps a face then runs img2img cleanup for natural blending. ~30 seconds total.\r
\r
```bash\r
uv run $SKILL_SCRIPTS/comfyui_generate.py \\r
  --faceswap-pipeline \\r
  --source-face /path/to/source_face.png \\r
  -i /path/to/target.png \\r
  --cleanup-strength 0.40 \\r
  --filename ~/.openclaw/media/outbound/output.png \\r
  --no-media\r
```\r
\r
### 4. Faceswap (basic)\r
\r
```bash\r
uv run $SKILL_SCRIPTS/comfyui_generate.py \\r
  --faceswap \\r
  --source-face /path/to/source_face.png \\r
  -i /path/to/target.png \\r
  --filename ~/.openclaw/media/outbound/output.png \\r
  --no-media\r
```\r
\r
### 5. Targeted Faceswap (specific face in group photo)\r
\r
```bash\r
uv run $SKILL_SCRIPTS/comfyui_generate.py \\r
  --targeted-faceswap \\r
  --source-face /path/to/source_face.png \\r
  -i /path/to/group_photo.png \\r
  --target-face-index "1" \\r
  --filename ~/.openclaw/media/outbound/output.png \\r
  --no-media\r
```\r
\r
Face indices: `0` = leftmost, `1` = second from left, `"0,2"` = first and third.\r
\r
### 6. LivePortrait (expression animation)\r
\r
```bash\r
uv run $SKILL_SCRIPTS/comfyui_generate.py \\r
  --liveportrait \\r
  -i /path/to/portrait.png \\r
  --expression-preset smile \\r
  --filename ~/.openclaw/media/outbound/output.png \\r
  --no-media\r
```\r
\r
Presets: `smile`, `surprised`, `wink`, `suspicious`, `derp`, `angry`, `sleepy`\r
\r
Fine-grained control: `--smile` (-0.3 to 1.3), `--blink-val` (-20 to 5), `--eyebrow-val` (-10 to 15), `--aaa` (-30 to 120, mouth open), `--pitch`/`--yaw`/`--roll` (-20 to 20, head rotation).\r
\r
### 7. Style Transfer\r
\r
Generate a new image in the style of a reference:\r
\r
```bash\r
uv run $SKILL_SCRIPTS/comfyui_generate.py \\r
  --style-transfer \\r
  --style-ref /path/to/reference.png \\r
  --prompt "a portrait of a man" \\r
  --style-weight 0.85 \\r
  --filename ~/.openclaw/media/outbound/output.png \\r
  --no-media\r
```\r
\r
### 8. Restyle\r
\r
Apply a reference image's style to an existing photo:\r
\r
```bash\r
uv run $SKILL_SCRIPTS/comfyui_generate.py \\r
  --restyle \\r
  --style-ref /path/to/reference.png \\r
  -i /path/to/photo.png \\r
  --style-weight 0.85 \\r
  --strength 0.65 \\r
  --filename ~/.openclaw/media/outbound/output.png \\r
  --no-media\r
```\r
\r
### 9. Enhanced mode\r
\r
Add `--enhanced` to any command for FaceDetailer + 4x-UltraSharp upscale (net ~2x resolution). Works with txt2img and faceswap.\r
\r
---\r
\r
## Quality Gates (built-in)\r
\r
The script includes two automatic quality checks on faceswap outputs:\r
\r
**Gate 1 — Size check:** ReActor blank outputs when no face is detected (~2KB). Any faceswap output under 10KB automatically retries once. If still blank, exits with `FACESWAP_BLANK:` error — no garbage delivered.\r
\r
**Gate 2 — Vision QA:** If you have [Ollama](https://ollama.ai) running locally with `gemma3:12b`, faceswap outputs are checked with vision QA before delivery. PASS → deliver normally. FAIL → file renamed `_qa_flagged` and still delivered. Add ~10-20s but catches glitchy outputs. Disable by not having Ollama/gemma3 installed (fails open).\r
\r
---\r
\r
## Offline Queue\r
\r
When the bridge is unreachable, requests are automatically queued to `~/.openclaw/faceswap-queue/`. A companion daemon (`queue_processor.py`) polls every 5 minutes and delivers via iMessage when the bridge comes back online.\r
\r
Tell users: "Got it — the system is offline right now but your request is queued and will be sent automatically when it comes back."\r
\r
---\r
\r
## Options Reference\r
\r
| Flag | Default | Description |\r
|---|---|---|\r
| `--prompt` / `-p` | — | Text description |\r
| `--filename` / `-f` | required | Output path (use `~/.openclaw/media/outbound/`) |\r
| `-i` / `--input-image` | — | Input image (img2img target / faceswap target / portrait) |\r
| `--source-face` | — | Source face image (faceswap modes) |\r
| `--faceswap` | false | Basic faceswap |\r
| `--faceswap-pipeline` | false | Faceswap + cleanup (best quality) |\r
| `--cleanup-strength` | `0.40` | Pipeline cleanup denoise strength |\r
| `--targeted-faceswap` | false | Swap specific face in multi-face image |\r
| `--target-face-index` | `0` | Which face(s) to replace (comma-separated) |\r
| `--liveportrait` | false | Expression animation mode |\r
| `--expression-preset` | — | smile / surprised / wink / suspicious / derp / angry / sleepy |\r
| `--style-transfer` | false | Generate in reference style |\r
| `--restyle` | false | Apply reference style to existing photo |\r
| `--style-ref` | — | Style reference image |\r
| `--style-weight` | `0.85` | Style influence (0.5–1.0) |\r
| `--model` / `-m` | `juggernaut` | `juggernaut`, `flux`, `realvis` |\r
| `--aspect-ratio` / `-a` | `1:1` | `1:1`, `4:5`, `9:16`, `16:9`, `5:4` |\r
| `--strength` / `-s` | `0.6` | img2img denoise strength |\r
| `--seed` | `-1` | Seed (-1 = random) |\r
| `--enhanced` / `-e` | false | FaceDetailer + 4x upscale |\r
| `--no-media` | false | Suppress MEDIA: stdout line (always use this) |\r
\r
---\r
\r
## Routing Guide\r
\r
| User says | Mode |\r
|---|---|\r
| "generate an image of..." | txt2img |\r
| "make this look like..." (with image) | img2img |\r
| "put [person]'s face on this" | --faceswap-pipeline |\r
| "swap the second face" | --targeted-faceswap --target-face-index 1 |\r
| "make him smile / look surprised" | --liveportrait --expression-preset |\r
| "generate something that looks like this painting" | --style-transfer |\r
| "make this photo look like a painting" | --restyle |\r
| "high quality / best quality" | add --enhanced |\r
\r
---\r
\r
## Timing Reference\r
\r
| Mode | Approximate time |\r
|---|---|\r
| txt2img (realvis) | ~5 seconds |\r
| txt2img (juggernaut) | ~5 minutes |\r
| txt2img (flux) | ~10 minutes |\r
| faceswap pipeline | ~30 seconds |\r
| liveportrait | ~7 seconds (21s first run) |\r
| style transfer / restyle | ~5 minutes |\r
| +enhanced | +10-30 seconds |\r